From 30466b0d7174982939e9231e0cd056aa448ca193 Mon Sep 17 00:00:00 2001 From: Rob Browning Date: Wed, 29 Jul 2009 20:14:15 -0500 Subject: [PATCH] Import emacs23_23.1+1.orig.tar.gz. --- .arch-inventory | 7 - .cvsignore | 20 - .gitignore | 7 - INSTALL.CVS | 111 - admin/CPP-DEFINES | 468 - admin/ChangeLog | 837 - admin/FOR-RELEASE | 234 - admin/MAINTAINERS | 217 - admin/README | 97 - admin/admin.el | 219 - admin/alloc-colors.c | 116 - admin/build-configs | 100 - admin/charsets/.arch-inventory | 4 - admin/charsets/.cvsignore | 2 - admin/charsets/Makefile | 310 - admin/charsets/big5.awk | 73 - admin/charsets/compact.awk | 123 - admin/charsets/cp51932.awk | 59 - admin/charsets/cp932.awk | 117 - admin/charsets/eucjp-ms.awk | 113 - admin/charsets/gb180302.awk | 101 - admin/charsets/gb180304.awk | 123 - admin/charsets/kuten.awk | 7 - admin/charsets/mapconv | 146 - admin/charsets/mapfiles/CP720.map.gz | Bin 562 -> 0 bytes admin/charsets/mapfiles/CP858.map.gz | Bin 715 -> 0 bytes admin/charsets/mapfiles/CP932.TXT.gz | Bin 49842 -> 0 bytes admin/charsets/mapfiles/JISX213A.map.gz | Bin 178 -> 0 bytes admin/charsets/mapfiles/MULE-ethiopic.map.gz | Bin 1481 -> 0 bytes admin/charsets/mapfiles/MULE-ipa.map.gz | Bin 370 -> 0 bytes admin/charsets/mapfiles/MULE-is13194.map.gz | Bin 436 -> 0 bytes admin/charsets/mapfiles/MULE-lviscii.map.gz | Bin 388 -> 0 bytes admin/charsets/mapfiles/MULE-sisheng.map.gz | Bin 400 -> 0 bytes admin/charsets/mapfiles/MULE-tibetan.map.gz | Bin 825 -> 0 bytes admin/charsets/mapfiles/MULE-uviscii.map.gz | Bin 388 -> 0 bytes admin/charsets/mapfiles/PTCP154.gz | Bin 3169 -> 0 bytes admin/charsets/mapfiles/README | 82 - admin/charsets/mapfiles/Uni2JIS.gz | Bin 113926 -> 0 bytes admin/charsets/mapfiles/bulgarian-mik.txt.gz | Bin 2075 -> 0 bytes admin/charsets/mapfiles/cns2ucsdkw.txt.gz | Bin 395503 -> 0 bytes admin/charsets/mapfiles/stdenc.txt.gz | Bin 3190 -> 0 bytes admin/charsets/mapfiles/symbol.txt.gz | Bin 4109 -> 0 bytes admin/charsets/mule-charsets.el | 57 - admin/check-doc-strings | 304 - admin/cus-test.el | 529 - admin/diff-tar-files | 45 - admin/emacs-pretesters | 219 - admin/make-announcement | 89 - admin/make-changelog-diff | 30 - admin/make-emacs | 188 - admin/make-tarball.txt | 107 - admin/notes/BRANCH | 5 - admin/notes/bugtracker | 312 - admin/notes/changelogs | 17 - admin/notes/copyright | 676 - admin/notes/cpp | 18 - admin/notes/cvslogs | 15 - admin/notes/documentation | 114 - admin/notes/exit-value | 35 - admin/notes/font-backend | 79 - admin/notes/iftc | 27 - admin/notes/lel-TODO | 125 - admin/notes/multi-tty | 1363 - admin/notes/trailing-whitespace | 8 - admin/notes/unicode | 144 - admin/notes/years | 30 - admin/nt/README-UNDUMP.W32 | 59 - admin/nt/README-ftp-server | 281 - admin/nt/README.W32 | 264 - admin/nt/dump.bat | 23 - admin/nt/makedist.bat | 65 - admin/quick-install-emacs | 378 - admin/revdiff | 137 - admin/unidata/.arch-inventory | 4 - admin/unidata/.cvsignore | 5 - admin/unidata/Makefile.in | 48 - admin/unidata/README | 4 - admin/unidata/UnicodeData.txt | 19336 --------- admin/unidata/copyright.html | 345 - admin/unidata/makefile.w32-in | 55 - admin/unidata/unidata-gen.el | 1238 - autogen.sh | 9 - doc/emacs/.cvsignore | 23 - doc/emacs/ChangeLog | 6809 --- doc/emacs/Makefile.in | 159 - doc/emacs/abbrevs.texi | 461 - doc/emacs/ack.texi | 1402 - doc/emacs/anti.texi | 141 - doc/emacs/arevert-xtra.texi | 192 - doc/emacs/basic.texi | 724 - doc/emacs/buffers.texi | 678 - doc/emacs/building.texi | 1484 - doc/emacs/cal-xtra.texi | 864 - doc/emacs/calendar.texi | 1715 - doc/emacs/cmdargs.texi | 1414 - doc/emacs/commands.texi | 201 - doc/emacs/custom.texi | 2579 -- doc/emacs/dired-xtra.texi | 48 - doc/emacs/dired.texi | 1368 - doc/emacs/display.texi | 1317 - doc/emacs/doclicense.texi | 512 - doc/emacs/emacs-xtra.texi | 142 - doc/emacs/emacs.texi | 1570 - doc/emacs/emerge-xtra.texi | 417 - doc/emacs/entering.texi | 190 - doc/emacs/files.texi | 1973 - doc/emacs/fixit.texi | 429 - doc/emacs/fortran-xtra.texi | 587 - doc/emacs/frames.texi | 1130 - doc/emacs/glossary.texi | 1378 - doc/emacs/gnu.texi | 555 - doc/emacs/gpl.texi | 721 - doc/emacs/help.texi | 680 - doc/emacs/indent.texi | 251 - doc/emacs/killing.texi | 665 - doc/emacs/kmacro.texi | 575 - doc/emacs/m-x.texi | 75 - doc/emacs/macos.texi | 236 - doc/emacs/maintaining.texi | 2226 - doc/emacs/major.texi | 226 - doc/emacs/makefile.w32-in | 144 - doc/emacs/mark.texi | 453 - doc/emacs/mini.texi | 658 - doc/emacs/misc.texi | 2852 -- doc/emacs/msdog-xtra.texi | 619 - doc/emacs/msdog.texi | 921 - doc/emacs/mule.texi | 1672 - doc/emacs/picture-xtra.texi | 291 - doc/emacs/programs.texi | 1775 - doc/emacs/regs.texi | 336 - doc/emacs/rmail.texi | 1484 - doc/emacs/screen.texi | 325 - doc/emacs/search.texi | 1371 - doc/emacs/sending.texi | 812 - doc/emacs/text.texi | 2929 -- doc/emacs/trouble.texi | 1055 - doc/emacs/vc-xtra.texi | 30 - doc/emacs/vc1-xtra.texi | 793 - doc/emacs/windows.texi | 403 - doc/emacs/xresources.texi | 1195 - doc/lispintro/.cvsignore | 21 - doc/lispintro/ChangeLog | 356 - doc/lispintro/Makefile.in | 73 - doc/lispintro/README | 73 - doc/lispintro/cons-1.eps | 582 - doc/lispintro/cons-2.eps | 604 - doc/lispintro/cons-2a.eps | 598 - doc/lispintro/cons-3.eps | 628 - doc/lispintro/cons-4.eps | 681 - doc/lispintro/cons-5.eps | 626 - doc/lispintro/doclicense.texi | 512 - doc/lispintro/drawers.eps | 511 - doc/lispintro/emacs-lisp-intro.texi | 22281 ---------- doc/lispintro/lambda-1.eps | 469 - doc/lispintro/lambda-2.eps | 469 - doc/lispintro/lambda-3.eps | 469 - doc/lispintro/makefile.w32-in | 74 - doc/lispref/.arch-inventory | 4 - doc/lispref/.cvsignore | 13 - doc/lispref/ChangeLog | 8156 ---- doc/lispref/Makefile.in | 115 - doc/lispref/README | 50 - doc/lispref/abbrevs.texi | 523 - doc/lispref/advice.texi | 783 - doc/lispref/anti.texi | 160 - doc/lispref/back.texi | 42 - doc/lispref/backups.texi | 756 - doc/lispref/book-spine.texinfo | 29 - doc/lispref/buffers.texi | 1221 - doc/lispref/commands.texi | 3362 -- doc/lispref/compile.texi | 802 - doc/lispref/control.texi | 1311 - doc/lispref/customize.texi | 1288 - doc/lispref/debugging.texi | 823 - doc/lispref/display.texi | 5880 --- doc/lispref/doclicense.texi | 514 - doc/lispref/edebug.texi | 1594 - doc/lispref/elisp-covers.texi | 257 - doc/lispref/elisp.texi | 1529 - doc/lispref/errors.texi | 209 - doc/lispref/eval.texi | 754 - doc/lispref/files.texi | 3142 -- doc/lispref/frames.texi | 2406 -- doc/lispref/front-cover-1.texi | 56 - doc/lispref/functions.texi | 1501 - doc/lispref/gpl.texi | 727 - doc/lispref/hash.texi | 337 - doc/lispref/help.texi | 706 - doc/lispref/hooks.texi | 358 - doc/lispref/index.texi | 29 - doc/lispref/internals.texi | 1404 - doc/lispref/intro.texi | 552 - doc/lispref/keymaps.texi | 2810 -- doc/lispref/lay-flat.texi | 48 - doc/lispref/lists.texi | 1894 - doc/lispref/loading.texi | 988 - doc/lispref/locals.texi | 228 - doc/lispref/macros.texi | 738 - doc/lispref/makefile.w32-in | 125 - doc/lispref/maps.texi | 244 - doc/lispref/markers.texi | 679 - doc/lispref/minibuf.texi | 2140 - doc/lispref/modes.texi | 3287 -- doc/lispref/nonascii.texi | 1924 - doc/lispref/numbers.texi | 1214 - doc/lispref/objects.texi | 2101 - doc/lispref/os.texi | 2190 - doc/lispref/positions.texi | 1016 - doc/lispref/processes.texi | 3003 -- doc/lispref/searching.texi | 1842 - doc/lispref/sequences.texi | 734 - doc/lispref/spellfile | 738 - doc/lispref/streams.texi | 843 - doc/lispref/strings.texi | 1160 - doc/lispref/symbols.texi | 596 - doc/lispref/syntax.texi | 1196 - doc/lispref/text.texi | 4276 -- doc/lispref/tindex.pl | 126 - doc/lispref/tips.texi | 1095 - doc/lispref/two-volume-cross-refs.txt | 320 - doc/lispref/two-volume.make | 224 - doc/lispref/two.el | 80 - doc/lispref/variables.texi | 1927 - doc/lispref/vol1.texi | 1548 - doc/lispref/vol2.texi | 1547 - doc/lispref/windows.texi | 2603 -- doc/misc/.cvsignore | 23 - doc/misc/ada-mode.texi | 1530 - doc/misc/auth.texi | 197 - doc/misc/autotype.texi | 670 - doc/misc/calc.texi | 36383 ----------------- doc/misc/cc-mode.texi | 6998 ---- doc/misc/cl.texi | 5342 --- doc/misc/dbus.texi | 1582 - doc/misc/dired-x.texi | 1266 - doc/misc/doclicense.texi | 511 - doc/misc/ebrowse.texi | 1459 - doc/misc/ediff.texi | 2541 -- doc/misc/emacs-mime.texi | 1892 - doc/misc/epa.texi | 405 - doc/misc/erc.texi | 1066 - doc/misc/eshell.texi | 942 - doc/misc/eudc.texi | 974 - doc/misc/flymake.texi | 755 - doc/misc/forms.texi | 982 - doc/misc/gnus-coding.texi | 387 - doc/misc/gnus-faq.texi | 2337 -- doc/misc/gnus-news.el | 117 - doc/misc/gnus-news.texi | 322 - doc/misc/gnus.texi | 31302 -------------- doc/misc/gpl.texi | 721 - doc/misc/idlwave.texi | 4301 -- doc/misc/info.texi | 1506 - doc/misc/mairix-el.texi | 355 - doc/misc/makefile.w32-in | 357 - doc/misc/message.texi | 2446 -- doc/misc/mh-e.texi | 9066 ---- doc/misc/newsticker.texi | 321 - doc/misc/nxml-mode.texi | 865 - doc/misc/org.texi | 10525 ----- doc/misc/pcl-cvs.texi | 1438 - doc/misc/pgg.texi | 503 - doc/misc/rcirc.texi | 953 - doc/misc/reftex.texi | 5895 --- doc/misc/remember.texi | 409 - doc/misc/sasl.texi | 273 - doc/misc/sc.texi | 1946 - doc/misc/ses.texi | 988 - doc/misc/sieve.texi | 362 - doc/misc/smtpmail.texi | 421 - doc/misc/speedbar.texi | 1259 - doc/misc/texinfo.tex | 8662 ---- doc/misc/tramp.texi | 3500 -- doc/misc/trampver.texi | 71 - doc/misc/url.texi | 1192 - doc/misc/vip.texi | 1952 - doc/misc/viper.texi | 4547 -- doc/misc/widget.texi | 1835 - doc/misc/woman.texi | 1436 - etc/.arch-inventory | 13 - etc/.cvsignore | 7 - etc/.gitignore | 5 - etc/CENSORSHIP | 87 - etc/COOKIES | 157 - etc/DEVEL.HUMOR | 196 - etc/GNU | 545 - etc/INTERVIEW | 442 - etc/JOKES | 647 - etc/LINUX-GNU | 147 - etc/MOTIVATION | 179 - etc/THE-GNU-PROJECT | 903 - etc/WHY-FREE | 244 - etc/copying.paper | 819 - etc/schema/dbhier.rnc | 2 +- etc/schema/dbnotn.rnc | 2 +- etc/schema/dbpool.rnc | 2 +- info/.arch-inventory | 20 - info/.cvsignore | 1 - info/.gitignore | 3 - leim/.arch-inventory | 4 - leim/.cvsignore | 5 - leim/.gitignore | 4 - leim/ja-dic/.cvsignore | 1 - leim/quail/.arch-inventory | 4 - leim/quail/.cvsignore | 23 - leim/quail/.gitignore | 23 - lib-src/.arch-inventory | 10 - lib-src/.cvsignore | 26 - lib-src/.gitignore | 9 - lisp/.arch-inventory | 4 - lisp/.cvsignore | 12 - lisp/.gitignore | 8 - lisp/calc/.arch-inventory | 4 - lisp/calc/.cvsignore | 2 - lisp/calc/calc-loaddefs.el | 456 + lisp/calendar/.arch-inventory | 4 - lisp/calendar/.cvsignore | 4 - lisp/calendar/cal-loaddefs.el | 967 + lisp/calendar/diary-loaddefs.el | 345 + lisp/calendar/hol-loaddefs.el | 182 + lisp/cus-load.el | 1137 + lisp/emacs-lisp/.cvsignore | 1 - lisp/emacs-lisp/.gitignore | 3 - lisp/emulation/.cvsignore | 1 - lisp/erc/.cvsignore | 3 - lisp/eshell/.arch-inventory | 4 - lisp/eshell/.cvsignore | 14 - lisp/eshell/.gitignore | 3 - lisp/eshell/esh-groups.el | 125 + lisp/finder-inf.el | 3270 ++ lisp/gnus/.cvsignore | 1 - lisp/international/.cvsignore | 1 - lisp/language/.cvsignore | 1 - lisp/loaddefs.el | 32715 +++++++++++++++ lisp/mail/.cvsignore | 1 - lisp/mh-e/.arch-inventory | 4 - lisp/mh-e/.cvsignore | 3 - lisp/mh-e/mh-loaddefs.el | 3150 ++ lisp/net/.cvsignore | 1 - lisp/nxml/.cvsignore | 2 - lisp/obsolete/.cvsignore | 0 lisp/play/.cvsignore | 1 - lisp/progmodes/.cvsignore | 1 - lisp/subdirs.el | 8 + lisp/term/.cvsignore | 1 - lisp/textmodes/.cvsignore | 1 - lisp/url/.cvsignore | 4 - lwlib/.cvsignore | 1 - nextstep/.cvsignore | 2 - nt/.arch-inventory | 3 - nt/.cvsignore | 7 - nt/.gitignore | 7 - oldXMenu/.cvsignore | 1 - src/.arch-inventory | 12 - src/.cvsignore | 25 - src/.gitignore | 8 - test/ChangeLog | 84 - test/README | 2 - test/bytecomp-testsuite.el | 283 - test/icalendar-testsuite.el | 1571 - test/newsticker-testsuite.el | 181 - 361 files changed, 42358 insertions(+), 377510 deletions(-) delete mode 100644 .arch-inventory delete mode 100644 .cvsignore delete mode 100644 .gitignore delete mode 100644 INSTALL.CVS delete mode 100644 admin/CPP-DEFINES delete mode 100644 admin/ChangeLog delete mode 100644 admin/FOR-RELEASE delete mode 100644 admin/MAINTAINERS delete mode 100644 admin/README delete mode 100644 admin/admin.el delete mode 100644 admin/alloc-colors.c delete mode 100755 admin/build-configs delete mode 100644 admin/charsets/.arch-inventory delete mode 100644 admin/charsets/.cvsignore delete mode 100644 admin/charsets/Makefile delete mode 100644 admin/charsets/big5.awk delete mode 100644 admin/charsets/compact.awk delete mode 100644 admin/charsets/cp51932.awk delete mode 100644 admin/charsets/cp932.awk delete mode 100644 admin/charsets/eucjp-ms.awk delete mode 100644 admin/charsets/gb180302.awk delete mode 100644 admin/charsets/gb180304.awk delete mode 100644 admin/charsets/kuten.awk delete mode 100755 admin/charsets/mapconv delete mode 100644 admin/charsets/mapfiles/CP720.map.gz delete mode 100644 admin/charsets/mapfiles/CP858.map.gz delete mode 100644 admin/charsets/mapfiles/CP932.TXT.gz delete mode 100644 admin/charsets/mapfiles/JISX213A.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-ethiopic.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-ipa.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-is13194.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-lviscii.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-sisheng.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-tibetan.map.gz delete mode 100644 admin/charsets/mapfiles/MULE-uviscii.map.gz delete mode 100644 admin/charsets/mapfiles/PTCP154.gz delete mode 100644 admin/charsets/mapfiles/README delete mode 100644 admin/charsets/mapfiles/Uni2JIS.gz delete mode 100644 admin/charsets/mapfiles/bulgarian-mik.txt.gz delete mode 100644 admin/charsets/mapfiles/cns2ucsdkw.txt.gz delete mode 100644 admin/charsets/mapfiles/stdenc.txt.gz delete mode 100644 admin/charsets/mapfiles/symbol.txt.gz delete mode 100644 admin/charsets/mule-charsets.el delete mode 100755 admin/check-doc-strings delete mode 100644 admin/cus-test.el delete mode 100755 admin/diff-tar-files delete mode 100644 admin/emacs-pretesters delete mode 100755 admin/make-announcement delete mode 100755 admin/make-changelog-diff delete mode 100755 admin/make-emacs delete mode 100644 admin/make-tarball.txt delete mode 100644 admin/notes/BRANCH delete mode 100644 admin/notes/bugtracker delete mode 100644 admin/notes/changelogs delete mode 100644 admin/notes/copyright delete mode 100644 admin/notes/cpp delete mode 100644 admin/notes/cvslogs delete mode 100644 admin/notes/documentation delete mode 100644 admin/notes/exit-value delete mode 100644 admin/notes/font-backend delete mode 100644 admin/notes/iftc delete mode 100644 admin/notes/lel-TODO delete mode 100644 admin/notes/multi-tty delete mode 100644 admin/notes/trailing-whitespace delete mode 100644 admin/notes/unicode delete mode 100644 admin/notes/years delete mode 100644 admin/nt/README-UNDUMP.W32 delete mode 100644 admin/nt/README-ftp-server delete mode 100644 admin/nt/README.W32 delete mode 100755 admin/nt/dump.bat delete mode 100755 admin/nt/makedist.bat delete mode 100755 admin/quick-install-emacs delete mode 100755 admin/revdiff delete mode 100644 admin/unidata/.arch-inventory delete mode 100644 admin/unidata/.cvsignore delete mode 100644 admin/unidata/Makefile.in delete mode 100644 admin/unidata/README delete mode 100644 admin/unidata/UnicodeData.txt delete mode 100644 admin/unidata/copyright.html delete mode 100644 admin/unidata/makefile.w32-in delete mode 100644 admin/unidata/unidata-gen.el delete mode 100755 autogen.sh delete mode 100644 doc/emacs/.cvsignore delete mode 100644 doc/emacs/ChangeLog delete mode 100644 doc/emacs/Makefile.in delete mode 100644 doc/emacs/abbrevs.texi delete mode 100644 doc/emacs/ack.texi delete mode 100644 doc/emacs/anti.texi delete mode 100644 doc/emacs/arevert-xtra.texi delete mode 100644 doc/emacs/basic.texi delete mode 100644 doc/emacs/buffers.texi delete mode 100644 doc/emacs/building.texi delete mode 100644 doc/emacs/cal-xtra.texi delete mode 100644 doc/emacs/calendar.texi delete mode 100644 doc/emacs/cmdargs.texi delete mode 100644 doc/emacs/commands.texi delete mode 100644 doc/emacs/custom.texi delete mode 100644 doc/emacs/dired-xtra.texi delete mode 100644 doc/emacs/dired.texi delete mode 100644 doc/emacs/display.texi delete mode 100644 doc/emacs/doclicense.texi delete mode 100644 doc/emacs/emacs-xtra.texi delete mode 100644 doc/emacs/emacs.texi delete mode 100644 doc/emacs/emerge-xtra.texi delete mode 100644 doc/emacs/entering.texi delete mode 100644 doc/emacs/files.texi delete mode 100644 doc/emacs/fixit.texi delete mode 100644 doc/emacs/fortran-xtra.texi delete mode 100644 doc/emacs/frames.texi delete mode 100644 doc/emacs/glossary.texi delete mode 100644 doc/emacs/gnu.texi delete mode 100644 doc/emacs/gpl.texi delete mode 100644 doc/emacs/help.texi delete mode 100644 doc/emacs/indent.texi delete mode 100644 doc/emacs/killing.texi delete mode 100644 doc/emacs/kmacro.texi delete mode 100644 doc/emacs/m-x.texi delete mode 100644 doc/emacs/macos.texi delete mode 100644 doc/emacs/maintaining.texi delete mode 100644 doc/emacs/major.texi delete mode 100644 doc/emacs/makefile.w32-in delete mode 100644 doc/emacs/mark.texi delete mode 100644 doc/emacs/mini.texi delete mode 100644 doc/emacs/misc.texi delete mode 100644 doc/emacs/msdog-xtra.texi delete mode 100644 doc/emacs/msdog.texi delete mode 100644 doc/emacs/mule.texi delete mode 100644 doc/emacs/picture-xtra.texi delete mode 100644 doc/emacs/programs.texi delete mode 100644 doc/emacs/regs.texi delete mode 100644 doc/emacs/rmail.texi delete mode 100644 doc/emacs/screen.texi delete mode 100644 doc/emacs/search.texi delete mode 100644 doc/emacs/sending.texi delete mode 100644 doc/emacs/text.texi delete mode 100644 doc/emacs/trouble.texi delete mode 100644 doc/emacs/vc-xtra.texi delete mode 100644 doc/emacs/vc1-xtra.texi delete mode 100644 doc/emacs/windows.texi delete mode 100644 doc/emacs/xresources.texi delete mode 100644 doc/lispintro/.cvsignore delete mode 100644 doc/lispintro/ChangeLog delete mode 100644 doc/lispintro/Makefile.in delete mode 100644 doc/lispintro/README delete mode 100644 doc/lispintro/cons-1.eps delete mode 100644 doc/lispintro/cons-2.eps delete mode 100644 doc/lispintro/cons-2a.eps delete mode 100644 doc/lispintro/cons-3.eps delete mode 100644 doc/lispintro/cons-4.eps delete mode 100644 doc/lispintro/cons-5.eps delete mode 100644 doc/lispintro/doclicense.texi delete mode 100644 doc/lispintro/drawers.eps delete mode 100644 doc/lispintro/emacs-lisp-intro.texi delete mode 100644 doc/lispintro/lambda-1.eps delete mode 100644 doc/lispintro/lambda-2.eps delete mode 100644 doc/lispintro/lambda-3.eps delete mode 100644 doc/lispintro/makefile.w32-in delete mode 100644 doc/lispref/.arch-inventory delete mode 100644 doc/lispref/.cvsignore delete mode 100644 doc/lispref/ChangeLog delete mode 100644 doc/lispref/Makefile.in delete mode 100644 doc/lispref/README delete mode 100644 doc/lispref/abbrevs.texi delete mode 100644 doc/lispref/advice.texi delete mode 100644 doc/lispref/anti.texi delete mode 100644 doc/lispref/back.texi delete mode 100644 doc/lispref/backups.texi delete mode 100644 doc/lispref/book-spine.texinfo delete mode 100644 doc/lispref/buffers.texi delete mode 100644 doc/lispref/commands.texi delete mode 100644 doc/lispref/compile.texi delete mode 100644 doc/lispref/control.texi delete mode 100644 doc/lispref/customize.texi delete mode 100644 doc/lispref/debugging.texi delete mode 100644 doc/lispref/display.texi delete mode 100644 doc/lispref/doclicense.texi delete mode 100644 doc/lispref/edebug.texi delete mode 100644 doc/lispref/elisp-covers.texi delete mode 100644 doc/lispref/elisp.texi delete mode 100644 doc/lispref/errors.texi delete mode 100644 doc/lispref/eval.texi delete mode 100644 doc/lispref/files.texi delete mode 100644 doc/lispref/frames.texi delete mode 100644 doc/lispref/front-cover-1.texi delete mode 100644 doc/lispref/functions.texi delete mode 100644 doc/lispref/gpl.texi delete mode 100644 doc/lispref/hash.texi delete mode 100644 doc/lispref/help.texi delete mode 100644 doc/lispref/hooks.texi delete mode 100644 doc/lispref/index.texi delete mode 100644 doc/lispref/internals.texi delete mode 100644 doc/lispref/intro.texi delete mode 100644 doc/lispref/keymaps.texi delete mode 100644 doc/lispref/lay-flat.texi delete mode 100644 doc/lispref/lists.texi delete mode 100644 doc/lispref/loading.texi delete mode 100644 doc/lispref/locals.texi delete mode 100644 doc/lispref/macros.texi delete mode 100644 doc/lispref/makefile.w32-in delete mode 100644 doc/lispref/maps.texi delete mode 100644 doc/lispref/markers.texi delete mode 100644 doc/lispref/minibuf.texi delete mode 100644 doc/lispref/modes.texi delete mode 100644 doc/lispref/nonascii.texi delete mode 100644 doc/lispref/numbers.texi delete mode 100644 doc/lispref/objects.texi delete mode 100644 doc/lispref/os.texi delete mode 100644 doc/lispref/positions.texi delete mode 100644 doc/lispref/processes.texi delete mode 100644 doc/lispref/searching.texi delete mode 100644 doc/lispref/sequences.texi delete mode 100644 doc/lispref/spellfile delete mode 100644 doc/lispref/streams.texi delete mode 100644 doc/lispref/strings.texi delete mode 100644 doc/lispref/symbols.texi delete mode 100644 doc/lispref/syntax.texi delete mode 100644 doc/lispref/text.texi delete mode 100755 doc/lispref/tindex.pl delete mode 100644 doc/lispref/tips.texi delete mode 100644 doc/lispref/two-volume-cross-refs.txt delete mode 100644 doc/lispref/two-volume.make delete mode 100644 doc/lispref/two.el delete mode 100644 doc/lispref/variables.texi delete mode 100644 doc/lispref/vol1.texi delete mode 100644 doc/lispref/vol2.texi delete mode 100644 doc/lispref/windows.texi delete mode 100644 doc/misc/.cvsignore delete mode 100644 doc/misc/ada-mode.texi delete mode 100644 doc/misc/auth.texi delete mode 100644 doc/misc/autotype.texi delete mode 100644 doc/misc/calc.texi delete mode 100644 doc/misc/cc-mode.texi delete mode 100644 doc/misc/cl.texi delete mode 100644 doc/misc/dbus.texi delete mode 100644 doc/misc/dired-x.texi delete mode 100644 doc/misc/doclicense.texi delete mode 100644 doc/misc/ebrowse.texi delete mode 100644 doc/misc/ediff.texi delete mode 100644 doc/misc/emacs-mime.texi delete mode 100644 doc/misc/epa.texi delete mode 100644 doc/misc/erc.texi delete mode 100644 doc/misc/eshell.texi delete mode 100644 doc/misc/eudc.texi delete mode 100644 doc/misc/flymake.texi delete mode 100644 doc/misc/forms.texi delete mode 100644 doc/misc/gnus-coding.texi delete mode 100644 doc/misc/gnus-faq.texi delete mode 100644 doc/misc/gnus-news.el delete mode 100644 doc/misc/gnus-news.texi delete mode 100644 doc/misc/gnus.texi delete mode 100644 doc/misc/gpl.texi delete mode 100644 doc/misc/idlwave.texi delete mode 100644 doc/misc/info.texi delete mode 100644 doc/misc/mairix-el.texi delete mode 100644 doc/misc/makefile.w32-in delete mode 100644 doc/misc/message.texi delete mode 100644 doc/misc/mh-e.texi delete mode 100644 doc/misc/newsticker.texi delete mode 100644 doc/misc/nxml-mode.texi delete mode 100644 doc/misc/org.texi delete mode 100644 doc/misc/pcl-cvs.texi delete mode 100644 doc/misc/pgg.texi delete mode 100644 doc/misc/rcirc.texi delete mode 100644 doc/misc/reftex.texi delete mode 100644 doc/misc/remember.texi delete mode 100644 doc/misc/sasl.texi delete mode 100644 doc/misc/sc.texi delete mode 100644 doc/misc/ses.texi delete mode 100644 doc/misc/sieve.texi delete mode 100644 doc/misc/smtpmail.texi delete mode 100644 doc/misc/speedbar.texi delete mode 100644 doc/misc/texinfo.tex delete mode 100644 doc/misc/tramp.texi delete mode 100644 doc/misc/trampver.texi delete mode 100644 doc/misc/url.texi delete mode 100644 doc/misc/vip.texi delete mode 100644 doc/misc/viper.texi delete mode 100644 doc/misc/widget.texi delete mode 100644 doc/misc/woman.texi delete mode 100644 etc/.arch-inventory delete mode 100644 etc/.cvsignore delete mode 100644 etc/.gitignore delete mode 100644 etc/CENSORSHIP delete mode 100644 etc/COOKIES delete mode 100644 etc/DEVEL.HUMOR delete mode 100644 etc/GNU delete mode 100644 etc/INTERVIEW delete mode 100644 etc/JOKES delete mode 100644 etc/LINUX-GNU delete mode 100644 etc/MOTIVATION delete mode 100644 etc/THE-GNU-PROJECT delete mode 100644 etc/WHY-FREE delete mode 100644 etc/copying.paper delete mode 100644 info/.arch-inventory delete mode 100644 info/.cvsignore delete mode 100644 info/.gitignore delete mode 100644 leim/.arch-inventory delete mode 100644 leim/.cvsignore delete mode 100644 leim/.gitignore delete mode 100644 leim/ja-dic/.cvsignore delete mode 100644 leim/quail/.arch-inventory delete mode 100644 leim/quail/.cvsignore delete mode 100644 leim/quail/.gitignore delete mode 100644 lib-src/.arch-inventory delete mode 100644 lib-src/.cvsignore delete mode 100644 lib-src/.gitignore delete mode 100644 lisp/.arch-inventory delete mode 100644 lisp/.cvsignore delete mode 100644 lisp/.gitignore delete mode 100644 lisp/calc/.arch-inventory delete mode 100644 lisp/calc/.cvsignore create mode 100644 lisp/calc/calc-loaddefs.el delete mode 100644 lisp/calendar/.arch-inventory delete mode 100644 lisp/calendar/.cvsignore create mode 100644 lisp/calendar/cal-loaddefs.el create mode 100644 lisp/calendar/diary-loaddefs.el create mode 100644 lisp/calendar/hol-loaddefs.el create mode 100644 lisp/cus-load.el delete mode 100644 lisp/emacs-lisp/.cvsignore delete mode 100644 lisp/emacs-lisp/.gitignore delete mode 100644 lisp/emulation/.cvsignore delete mode 100644 lisp/erc/.cvsignore delete mode 100644 lisp/eshell/.arch-inventory delete mode 100644 lisp/eshell/.cvsignore delete mode 100644 lisp/eshell/.gitignore create mode 100644 lisp/eshell/esh-groups.el create mode 100644 lisp/finder-inf.el delete mode 100644 lisp/gnus/.cvsignore delete mode 100644 lisp/international/.cvsignore delete mode 100644 lisp/language/.cvsignore create mode 100644 lisp/loaddefs.el delete mode 100644 lisp/mail/.cvsignore delete mode 100644 lisp/mh-e/.arch-inventory delete mode 100644 lisp/mh-e/.cvsignore create mode 100644 lisp/mh-e/mh-loaddefs.el delete mode 100644 lisp/net/.cvsignore delete mode 100644 lisp/nxml/.cvsignore delete mode 100644 lisp/obsolete/.cvsignore delete mode 100644 lisp/play/.cvsignore delete mode 100644 lisp/progmodes/.cvsignore create mode 100644 lisp/subdirs.el delete mode 100644 lisp/term/.cvsignore delete mode 100644 lisp/textmodes/.cvsignore delete mode 100644 lisp/url/.cvsignore delete mode 100644 lwlib/.cvsignore delete mode 100644 nextstep/.cvsignore delete mode 100644 nt/.arch-inventory delete mode 100644 nt/.cvsignore delete mode 100644 nt/.gitignore delete mode 100644 oldXMenu/.cvsignore delete mode 100644 src/.arch-inventory delete mode 100644 src/.cvsignore delete mode 100644 src/.gitignore delete mode 100644 test/ChangeLog delete mode 100644 test/README delete mode 100644 test/bytecomp-testsuite.el delete mode 100644 test/icalendar-testsuite.el delete mode 100644 test/newsticker-testsuite.el diff --git a/.arch-inventory b/.arch-inventory deleted file mode 100644 index 66aae859b87..00000000000 --- a/.arch-inventory +++ /dev/null @@ -1,7 +0,0 @@ -# Generated files -precious ^(config\.status|config\.cache)$ - -# Install-in-place makes these directories, so just ignore them -backup ^(bin|data|lock|site-lisp)$ - -# arch-tag: 6eeeaa4e-cc7e-4b22-b3d7-1089e155da14 diff --git a/.cvsignore b/.cvsignore deleted file mode 100644 index 6427839d5e5..00000000000 --- a/.cvsignore +++ /dev/null @@ -1,20 +0,0 @@ -*.xdelta -.DS_Store -Makefile -autom4te.cache -bin -boot.log -boot.log.diff -boot.log.old -config.cache -config.log -config.status -data -emacs*.tar.gz -leim*.tar.gz -lock -site-lisp -update.log -_dir-locals.el -_dir-loc.el - diff --git a/.gitignore b/.gitignore deleted file mode 100644 index da7b0fffdd4..00000000000 --- a/.gitignore +++ /dev/null @@ -1,7 +0,0 @@ -autom4te.cache -makefile - -/bin/ -/site-lisp/ - -# arch-tag: 75cd3c50-1875-4814-8360-190f7de38302 diff --git a/INSTALL.CVS b/INSTALL.CVS deleted file mode 100644 index aee016f28d3..00000000000 --- a/INSTALL.CVS +++ /dev/null @@ -1,111 +0,0 @@ -Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - - Building and Installing Emacs from CVS - -If this is the first time you go through it, you'll need to configure -before bootstrapping: - - $ ./configure - -Some of the files that are included in the Emacs tarball, such as -byte-compiled Lisp files, are not stored in the CVS repository. -Therefore, to build from CVS you must run "make bootstrap" -instead of just "make": - - $ cvs update -dP - $ make bootstrap - -Normally, it is not necessary to use "make bootstrap" after every CVS -update. "make" should work in 90% of the cases and be much quicker. - - $ make - -(If you want to install the Emacs binary, type "make install" instead -of "make" in the last command.) - -Occasionally the file "lisp/loaddefs.el" (and similar automatically -generated files, such as esh-groups.el, and *-loaddefs.el in some -subdirectories of lisp/, e.g. mh-e/ and calendar/) will need to be -updated to reflect new autoloaded functions. If you see errors (rather -than warnings) about undefined lisp functions during compilation, that -may be the reason. Another symptom may be an error saying that -"loaddefs.el" could not be found; this is due to a change in the way -loaddefs.el was handled in CVS, and should only happen once, for users -that are updating old CVS trees. Finally, sometimes there can be build -failures related to *loaddefs.el (e.g. "required feature `esh-groups' -was not provided"). In that case, follow the instructions below. - -To update loaddefs.el (and similar files), do: - - $ cd lisp - $ make autoloads - -If either of the above partial procedures fails, try "make bootstrap". - -Very occasionally changes in the source can introduce -incompatibilities with previous builds. If a bootstrap fails, as a -last resort try "make maintainer-clean" before configuring and -bootstrapping again. If CPU time is not an issue, the most thorough -way to rebuild, and avoid any spurious problems, is always to use this -method. - -Users of non-Posix systems (MS-Windows etc.) should run the -platform-specific configuration scripts (nt/configure.bat, config.bat, -etc.) before "make bootstrap" or "make"; the rest of the procedure is -applicable to those systems as well. - -Questions, requests, and bug reports about the CVS versions of Emacs -should be sent to emacs-pretest-bug@gnu.org rather than gnu.emacs.help -or gnu.emacs.bug. Ideally, use M-x report-emacs-bug RET which will -send it to the proper place. - -Because the CVS version of Emacs is a work in progress, it will -sometimes fail to build. Please wait a day or so (and check the bug -and development mailing list archives) before reporting such problems. -In most cases, the problem is known about and is just waiting for -someone to fix it. - - -Note on using SSH to access the CVS repository from inside Emacs ----------------------------------------------------------------- - -Write access to the CVS repository requires using SSH v2. - -If you execute cvs commands inside Emacs, specifically if you use -pcl-cvs, output from CVS may be lost due to a problem in the -interface between ssh, cvs, and libc. Corrupted checkins are -also known to have happened. - -To fix the problem, save the following script into a file, make it -executable, and set CVS_RSH to the file name of the script: - -#!/bin/bash -exec 2> >(exec cat >&2 2>/dev/null) -exec ssh "$@" - -This may be combined with the following entry in ~/.ssh/config to -simplify accessing the CVS repository: - -Host subversions.gnu.org - Protocol 2 - ForwardX11 no - User YOUR_USERID - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/CPP-DEFINES b/admin/CPP-DEFINES deleted file mode 100644 index 9e656c39aa1..00000000000 --- a/admin/CPP-DEFINES +++ /dev/null @@ -1,468 +0,0 @@ -Here are some of the cpp macros used, together with some short explanation -of their use. Feel free to add more macros and more categories. - -** Distinguishing OSes ** - -CYGWIN Compiling the Cygwin port. -__CYGWIN__ Ditto -MSDOS Compiling the MS-DOS port. -__MSDOS__ Ditto. -__DJGPP__ Major version number of the DJGPP library for the DOS port. -__DJGPP_MINOR__ Minor version number of the DJGPP library. -__GO32__ Compiling the DOS port with DJGPP v1.x (obsolete). -DOS_NT Compiling for either the MS-DOS or native MS-Windows port. -WINDOWSNT Compiling the native MS-Windows (W32) port. -__MINGW32__ Compiling the W32 port with the MinGW port of GCC. -_MSC_VER Compiling the W32 port with the Microsoft C compiler. -DARWIN_OS Compiling on Mac OS X or pure Darwin (and using s/darwin.h). - -** Distinguishing GUIs ** - -HAVE_NTGUI Use the native W32 GUI for windows, frames, menus&scrollbars. -HAVE_NS Use the NeXT/OpenStep/Cocoa UI under Mac OS X or GNUstep. -NS_IMPL_GNUSTEP Compile support for GNUstep implementation of NS GUI API. -NS_IMPL_COCOA Compile support for Cocoa (Apple) implementation of NS GUI API. -HAVE_X11 Compile support for the X11 GUI. -HAVE_X_WINDOWS Compile support for X Window system -X11 ?? Makefile.in suggests it's equivalent to HAVE_X11 -USE_LUCID Use the Lucid toolkit for menus&scrollbars. Requires HAVE_X11. -USE_MOTIF Use the Motif toolkit for menus&scrollbars. Requires HAVE_X11. -USE_GTK Use the Gtk toolkit for menus&scrollbars. Requires HAVE_X11. - -** Frame types ** - -FRAME_TERMCAP_P A tty (character terminal) frame. -FRAME_X_P A frame on X Window system. -FRAME_MSDOS_P An MS-DOS frame (used only by the DOS port). -FRAME_W32_P A frame using native MS-Windows GUI. -FRAME_WINDOW_P A GUI frame (like X, w32, etc.) - -** Support for accessing other processes on the system ** - -HAVE_PROCFS The /proc filesystem is supported. - -** Compile-time options ** - -REL_ALLOC Compile in the relocatable memory allocator ralloc.c. -SYSTEM_MALLOC Use the system library's malloc. -subprocesses System can use subprocesses (for M-x shell for example). Defined by default, only MSDOS undefines it. -USE_LISP_UNION_TYPE Define it in lisp.h to make Lisp_Object be a union type instead of the default int. - -** System specific macros, decribed in detail in src/s/template.h -BSTRING -CLASH_DETECTION -COFF -FIRST_PTY_LETTER -HAVE_PTYS -HAVE_TERMIO -HAVE_TERMIOS -INTERRUPT_INPUT -MAIL_USE_FLOCK -NARROWPROTO -NOMULTIPLEJOBS -SEPCHAR -SIGTYPE -SYSTEM_TYPE -USE_MMAP_FOR_BUFFERS - -** Machine specific macros, decribed in detail in src/m/template.h -CANNOT_DUMP -EXPLICIT_SIGN_EXTEND -LOAD_AVE_CVT -LOAD_AVE_TYPE -NO_ARG_ARRAY -NO_REMAP -VIRT_ADDR_VARIES -WORDS_BIG_ENDIAN - -** Not used anymore by any port, can be cleaned up -NO_SOCK_SIGIO - -** Misc macros -USER_FULL_NAME If defined, overrides the default pw->pw_gecos for getting at the full user name. Only MSDOS overrides the default. - -** Replace, the definition is trivial: SWITCH_ENUM_CAST - -** Defines from src/m/*.h and src/s/*.h. Some of these might not be used in the code anymore, so they can be removed. The HAVE_* definitions are probably handled by autoconf, so it might be possible to just remove them from src/[sm]/*.h. - - -AIX -AMPERSAND_FULL_NAME -BCOPY_DOWNWARD_SAFE -BCOPY_UPWARD_SAFE -BITS_PER_EMACS_INT -BITS_PER_LONG -BROKEN_DATAGRAM_SOCKETS -BROKEN_FIONREAD -BROKEN_GET_CURRENT_DIR_NAME -BROKEN_NON_BLOCKING_CONNECT -BROKEN_PTY_READ_AFTER_EAGAIN -BROKEN_SA_RESTART -BROKEN_SIGAIO -BROKEN_SIGIO -BROKEN_SIGPOLL -BROKEN_SIGPTY -BSD4_2 -BSD4_3 -BSD_PGRPS -BSD_SYSTEM -CLASH_DETECTION -COFF_BSD_SYMBOLS -CRT0_DUMMIES -C_DEBUG_SWITCH -C_SWITCH_MACHINE -C_SWITCH_SYSTEM -C_SWITCH_SYSTEM_TEMACS -C_SWITCH_X_SYSTEM -DATA_SEG_BITS -DATA_START -DBL_MIN_REPLACEMENT -DECLARE_GETPWUID_WITH_UID_T -DEFAULT_SOUND_DEVICE -DEVICE_SEP -DIRECTORY_SEP -DONT_REOPEN_PTY -DOUG_LEA_MALLOC -DebPrint -EMACSDEBUG -EMACS_CONFIGURATION -EMACS_CONFIG_OPTIONS -EMACS_INT -EMACS_UINT -END_FILES_1 -FILE_SYSTEM_CASE -FLOAT_CHECK_DOMAIN -FSCALE -GAP_USE_BCOPY -GC_LISP_OBJECT_ALIGNMENT -GC_MARK_SECONDARY_STACK -GC_MARK_STACK -GC_SETJMP_WORKS -GMALLOC_INHIBIT_VALLOC -GNU_LIBRARY_PENDING_OUTPUT_COUNT -GNU_LINUX -GNU_MALLOC -HAVE_AIX_SMT_EXP -HAVE_ALLOCA -HAVE_BCMP -HAVE_BCOPY -HAVE_CBRT -HAVE_CLOSEDIR -HAVE_CRTIN -HAVE_DUP2 -HAVE_EUIDACCESS -HAVE_FMOD -HAVE_FPATHCONF -HAVE_FREXP -HAVE_FSYNC -HAVE_FTIME -HAVE_GETCWD -HAVE_GETDOMAINNAME -HAVE_GETHOSTNAME -HAVE_GETLOADAVG -HAVE_GETPAGESIZE -HAVE_GETPT -HAVE_GETTIMEOFDAY -HAVE_GETWD -HAVE_H_ERRNO -HAVE_INDEX -HAVE_INET_SOCKETS -HAVE_INVERSE_HYPERBOLIC -HAVE_LIB64_DIR -HAVE_LIBKSTAT -HAVE_LIBNCURSES -HAVE_LIBPTHREADS -HAVE_LIBXMU -HAVE_LIMITS_H -HAVE_LINUX_VERSION_H -HAVE_LOGB -HAVE_LONG_FILE_NAMES -HAVE_LRAND48 -HAVE_MENUS -HAVE_MKDIR -HAVE_MKTIME -HAVE_MOUSE -HAVE_PERROR -HAVE_PSTAT_GETDYNAMIC -HAVE_PWD_H -HAVE_RANDOM -HAVE_RENAME -HAVE_RES_INIT -HAVE_RINDEX -HAVE_RINT -HAVE_RMDIR -HAVE_SELECT -HAVE_SETLOCALE -HAVE_SETPGID -HAVE_SETRLIMIT -HAVE_SETSID -HAVE_SHUTDOWN -HAVE_SOCKETS -HAVE_SOUND -HAVE_STDLIB_H -HAVE_STRERROR -HAVE_STRFTIME -HAVE_STRING_H -HAVE_STRUCT_UTIMBUF -HAVE_SYSINFO -HAVE_SYSV_SIGPAUSE -HAVE_SYS_SELECT_H -HAVE_SYS_SYSTEMINFO_H -HAVE_SYS_TIMEB_H -HAVE_SYS_TIME_H -HAVE_TCATTR -HAVE_TERMIOS_H -HAVE_TEXT_START -HAVE_TIMEVAL -HAVE_TM_ZONE -HAVE_TZSET -HAVE_UNISTD_H -HAVE_UTIMES -HAVE_UTIME_H -HAVE_VOLATILE -HAVE_WINDOW_SYSTEM -HAVE_WORKING_VFORK -HAVE_XRMSETDATABASE -HPUX -IBMR2AIX -INHIBIT_X11R6_XIM -INTERNAL_TERMINAL -IS_ANY_SEP -IS_DIRECTORY_SEP -KERNEL_FILE -LDAV_SYMBOL -LD_SWITCH_MACHINE -LD_SWITCH_MACHINE_TEMACS -LD_SWITCH_SYSTEM -LD_SWITCH_SYSTEM_TEMACS -LD_SWITCH_SYSTEM_tmp -LD_SWITCH_X_DEFAULT -LIBS_DEBUG -LIBS_MACHINE -LIBS_SYSTEM -LIBS_TERMCAP -LIBX11_SYSTEM -LIBXMU -LIB_GCC -LIB_MATH -LIB_MOTIF -LIB_STANDARD -LINKER -LINUX_VERSION_CODE -LISP_FLOAT_TYPE -LNOFLSH -LOCALTIME_CACHE -MAIL_USE_LOCKF -MAIL_USE_POP -MAIL_USE_SYSTEM_LOCK -MAXPATHLEN -MIN_PTY_KERNEL_VERSION -- only used on Mac -MODE_LINE_BINARY_TEXT -MUST_UNDEF__STDC__ -NEED_BSDTTY -NEED_ERRNO -NEED_LIBW -NEED_UNISTD_H -NLIST_STRUCT -NOT_C_CODE -NOT_USING_MOTIF -NO_ABORT -NO_DIR_LIBRARY -NO_EDITRES -NO_MATHERR -NO_SHARED_LIBS -NO_TERMIO -NSIG -NSIG_MINIMUM -NULL -NULL_DEVICE -ORDINARY_LINK -OTHER_FILES -O_APPEND -O_BINARY -O_CREAT -O_EXCL -O_RDONLY -O_RDWR -O_TEXT -O_TRUNC -O_WRONLY -PAGESIZE -PENDING_OUTPUT_COUNT -POSIX -POSIX_SIGNALS -PREFER_VSUSP -PTY_ITERATION -PTY_NAME_SPRINTF -PTY_OPEN -PTY_TTY_NAME_SPRINTF -PURESIZE -RUN_TIME_REMAP -SA_RESTART -SECTION_ALIGNMENT -SEGMENT_MASK -SETPGRP_RELEASES_CTTY -SETUP_SLAVE_PTY -SIGALRM -SIGCHLD -SIGHUP -SIGKILL -SIGNALS_VIA_CHARACTERS -SIGPIPE -SIGQUIT -SIGTRAP -SIGTYPE -SOLARIS2 -START_FILES -START_FILES_1 -STDC_HEADERS -SYMS_SYSTEM -SYSTEM_PURESIZE_EXTRA -SYSTEM_MALLOC -SYSV_SYSTEM_DIR -Srandom -TAB3 -TABDLY -TERM -TERMINFO -TEXT_START -THIS_IS_CONFIGURE -THIS_IS_MAKEFILE -TIME_WITH_SYS_TIME -TIOCSIGSEND -TM_IN_SYS_TIME -ULIMIT_BREAK_VALUE -UNEXEC -UNIX98_PTYS -USE_CRT_DLL -USE_MAC_IMAGE_IO -USE_TOOLKIT_SCROLL_BARS -USG -USG5 -USG5_4 -USG_SUBTTY_WORKS -VALBITS -WORDS_BIG_ENDIAN -WRETCODE -XINT -XOS_NEEDS_TIME_H -XPNTR -XSET -XUINT -_AIX -_ARCH_PPC64 -_CALLBACK_ -_FILE_OFFSET_BITS -_LP64 -_MALLOC_INTERNAL -_NAIVE_DOS_REGS -_VARARGS_ -_WINSOCKAPI_ -_WINSOCK_H -__ELF__ -__FreeBSD__ -__FreeBSD_version -__GNUC__ -__GNU_LIBRARY__ -__GNUC_MINOR__ -__NetBSD__ -__OpenBSD__ -__STDC__ -__arch64__ -__cplusplus -__hpux -__ia64__ -__linux__ -__mc68000__ -__mips__ -_longjmp -_setjmp -_start -abort -access -alloca -bcmp -bcopy -brk -bzero -calloc -chdir -chmod -chown -close -const -creat -ctime -dup -dup2 -edata -emacs -etext -execlp -execvp -fdopen -fileno -fopen -free -fsync -ftruncate -fwrite -getdefdir -getdisk -getenv -getpid -getuid -gmtime -i386 -index -init_process -isatty -kill -link -linux -localtime -logb -lseek -m68k -malloc -mkdir -mktemp -open -pclose -pipe -popen -random -read -realloc -rename -rindex -rmdir -sbrk -select -sigmask -signal -sigsetmask -sleep -spawnve -srandom -strdup -strerror -stricmp -strnicmp -strupr -sys_nerr -system -temacs -tzname -tzset -umask -unix -unlink -utimbuf -utime -vfork -wait -write -xfree - -# arch-tag: bc80061a-1168-4911-9766-46aaf2640250 diff --git a/admin/ChangeLog b/admin/ChangeLog deleted file mode 100644 index b04df9a68b6..00000000000 --- a/admin/ChangeLog +++ /dev/null @@ -1,837 +0,0 @@ -2009-07-29 Chong Yidong - - * Version 23.1 released. - -2009-06-24 Kenichi Handa - - * charsets/mapconv: For the UNICODE format files, do reverse sort - and don't compact the map. This is to prefer the first one in the - duplicated mappings (e.g. 0x20->U+0020, 0x20->U+00A0). - -2009-06-12 Kenichi Handa - - * charsets/Makefile (JISX213A.map): Make it depend on - mapfiles/JISX213A.map.gz. - (BIG5-1.map, BIG5-2.map): Prepend "# " to the first comment line. - - * charsets/mapfiles/JISX213A.map.gz: New file. - - * charsets/mapfiles/README: Describe JISX213A.map.gz. - -2009-06-12 Kenichi Handa - - * charsets/mapfiles/*: New files. - - * charsets/mule-charsets.el: Mostly re-written to generate all - MULE-*.map files. - - * charsets/mapconv: Mostly re-written to handle "gzip"ed input - files. - - * charsets/eucjp-ms.awk: Mostly re-written to handle glibc's - EUC-JP-MS. - - * charsets/cp51932.awk (END): Print arch-tag at the tail. - - * charsets/Makefile: Maps depend on files under mapfiles or - ${GLIBC_CHARMAPS}. - -2009-04-21 Kenichi Handa - - * unidata/unidata-gen.el (unidata-get-decomposition): Fix previous - change. - -2009-04-17 Kenichi Handa - - * unidata/unidata-gen.el (unidata-get-decomposition): Adjust - Hangle decomposition rule to Unicode. - -2009-04-09 Kenichi Handa - - * unidata/unidata-gen.el (unidata-describe-decomposition): Return - a string with a composition property to disable combining - characters being composed. - -2009-03-11 Miles Bader > - - * quick-install-emacs: Be more clever about locating info directory. - -2009-02-24 Juanma Barranquero - - * nt/README.W32: Fix typos. - -2009-02-23 Jason Rumney - - * nt/README-ftp-server: Update for 23.0.91 - - * nt/README.W32: Remove ever expanding versions of Windows. - Shorten FAQ URL. Remove mention of obsolete lock directory. - Windows distribution now bin and barebin only. Add note about - SVG support. Remove old tar and gzip problem workarounds. - Use new (22.x) -Q option. Report all bugs through bug tracker. - - * nt/README-UNDUMP.W32: Modify for barebin distribution, as - undumped distribution no longer exists. - -2009-02-05 Yu-ji Hosokawa (tiny change) - - * nt/README.W32: Fix typo. (Bug#2207) - -2009-02-01 Chong Yidong - - * admin.el (set-version): Remove deleted file ns-emacs.texi. - -2008-12-02 Kenichi Handa - - * unidata/unidata-gen.el (unidata-prop-alist): Docstring for - `decomposition' property adjusted. - (unidata-split-decomposition): Don't include surrounding "<" and - ">" in a symbol name. - -2008-12-01 Kenichi Handa - - * unidata/unidata-gen.el (unidata-prop-alist): Set `numeric-value' - property generator to unidata-gen-table-numeric. Docstring adjusted. - (unidata-get-numeric, unidata-put-numeric) - (unidata-gen-table-numeric): New functions. - (unidata-encode-val): Use assoc to get a slot in VAL-LIST. - -2008-11-29 Eli Zaretskii - - * notes/documentation: Add notes about Antinews. - -2008-10-23 Glenn Morris - - * admin.el (set-version): Add doc/misc/ns-emacs.texi. - Add/tweak some nextstep/ entries. - -2008-09-19 Kenichi Handa - - * FOR-RELEASE: Add an item for using EMACS_INT for buffer/string - positions. - -2008-08-23 Eli Zaretskii - - * CPP-DEFINES: Add USER_FULL_NAME. - -2008-08-16 Jason Rumney - - * admin.el (set-version): Set version in nt/emacsclient.rc. - -2008-08-06 Juanma Barranquero - - * nt/dump.bat: Fix mixed EOLs. - -2008-08-04 Adrian Robert - - * CPP-DEFINES: Add DARWIN_OS. Move USE_LISP_UNION_TYPE away from OS's. - -2008-08-02 Eli Zaretskii - - * CPP-DEFINES: Add defines for accessing system processes. - -2008-07-27 Dan Nicolaescu - - * make-tarball.txt: - * admin.el: - * FOR-RELEASE: - * CPP-DEFINES: Remove mentions of Mac Carbon. - -2008-07-16 Glenn Morris - - * admin.el (set-version, set-copyright): Add nextstep/ files. - -2008-07-15 Adrian Robert - - * CPP-DEFINES: Add NS port related defines. - -2008-06-16 Glenn Morris - - * admin.el (set-version): Add doc/lispref/vol1.texi,vol2.texi, - doc/lispref/book-spine.texinfo. - -2008-06-15 Glenn Morris - - * admin.el (set-version): Add doc/misc/faq.texi. - -2008-05-22 Juanma Barranquero - - * FOR-RELEASE: Remove Windows problem about the XPM image library - being loaded too soon (fixed by Stefan Monnier on 2008-05-07). - -2008-04-15 Juanma Barranquero - - * unidata/UnicodeData.txt: Update to Unicode 5.1. - -2008-04-14 Juanma Barranquero - - * unidata/unidata-gen.el (unidata-prop-alist): - Fix typo in description of `numeric-value'. - (unidata-put-character): Fix typo in error message. - -2008-02-21 Glenn Morris - - * notes/unicode, notes/font-backend: New files, split off from - README.unicode. - -2008-02-20 Kenichi Handa - - * FOR-RELEASE: Remove the problem of ucs-mule-8859-to-mule-unicode - being used in latin1-disp.el. Remove the problem of - cp-supported-codepages. Remove the problem of lost changelog for - ps-prin1.ps. - -2008-02-16 Eli Zaretskii - - * unidata/makefile.w32-in (unidata.txt): Don't use $<, it's - non-portable in this context. - - * unidata/Makefile.in (unidata.txt): Don't use $<, it's - non-portable in this context. - -2008-02-09 Eli Zaretskii - - * unidata/makefile.w32-in (lisp): New variable. - (EMACSLOADPATH): Use $(lisp). Add lisp/international and - lisp/emacs-lisp. - -2008-02-04 Jason Rumney - - * unidata/makefile.w32-in (unidata.txt): Use ARGQUOTE and DQUOTE macros. - -2008-02-02 Juanma Barranquero - - * unidata/.cvsignore: Ignore also "Makefile.unix" and "makefile". - -2008-02-02 Eli Zaretskii - - * unidata/makefile.w32-in (charprop-CMD): Fix last change. - - * unidata/Makefile.in: Rename from Makefile. - - * unidata/makefile.w32-in: New file. - -2008-02-02 Jason Rumney - - * unidata/unidata-gen.el (unidata-gen-files): Force unix line ends. - -2008-02-01 Kenichi Handa - - * unidata/copyright.html: New file. - -2008-02-01 Kenichi Handa - - * unidata/unidata-gen.el (unidata-get-decomposition): For Hangul - decomposition, if T is the same as TBase, don't include it in the - returned list. - -2008-02-01 Kenichi Handa - - * unidata/unidata-gen.el (unidata-text-file): Delete it. - (unidata-list): Initialize to nil. - (unidata-setup-list): New function. - (unidata-gen-files): New optional arg unidata-text-file. - If it's nil, set unidata-text-file to the left command line arg. - Call unidate-setup-list at first. - - * unidata/Makefile (all): Depends on ${DSTDIR}/charprop.el. - (${DSTDIR}/charprop.el): Run emacs after cd to DISDIR. - -2008-02-01 Kenichi Handa - - * unidata/unidata-gen.el: Fix comment typo. - Change string-to-int to string-to-number. - (unidata-text-file): Define to .../unidata.txt. - (unidata-list): Just insert unidata-text-file. - (unidata-get-decomposition): Handle Hangul decomposition. - (unidata-gen-files): Don't use \040, instead at ^L near the end of file. - - * unidata/Makefile (unidata.txt): New target. - (charprop.el): Depends on unidata.txt. - (clean): Remove unidata.txt. - -2008-02-01 Kenichi Handa - - * unidata/unidata-gen.el (unidata-get-name): Handle "CJK IDEOGRAPH". - (unidata-get-name): Handle U+110B. - -2008-02-01 Kenichi Handa - - Sub-directory `unidata' is for codes to generate charprop.el and - many other uni-*.el files from `UnicodeData.txt'. - - * Unidata/README: New file. - - * unidata/Makefile: New file. - - * unidata/unidata-gen.el: New file. - - * unidata/UnicodeData.txt: New file. Copied from - http://www.unicode.org on 2006-05-23. - - * unidata/.cvsignore: New file. - -2008-02-01 Kenichi Handa - - * charsets/.cvsignore: New file. - - * charsets/mapconv: Add code for handling KANJI-DATABASE format. - - * charsets/Makefile (all): Rename target from charsets. - Depend on ${TRANS_TABLE}. - (CNS-2.map, CNS-3.map, CNS-4.map, CNS-5.map, CNS-6.map, CNS-7.map): - Generate from cns2ucsdkw.txt. - (install): Copy updated files only. - -2008-02-02 Kenichi Handa - - * charsets/cp932.awk: Append user-defined area of CP932. - -2008-02-02 Kenichi Handa - - * charsets/Makefile (JISX2131.map): Convert 0x2015 to 0x2014, - 0x2299 to 0x29BF. - -2008-02-01 Kenichi Handa - - * charsets/Makefile (TRANS_TABLE): New macro. - (JISX0208.map): Convert 0x2015 to 0x2014. - (cp51932.el): New target. - (eucjp-ms.el): New target. - (install): Include ${TRANS_TABLE}. - (CJK): Include JISX213A.map. - (JISX213A.map): New target. - - * charsets/eucjp-ms.awk: New file. - - * charsets/cp51932.awk: New file. - -2008-02-01 Kenichi Handa - - * charsets/cp932.awk: New file. - - * charsets/Makefile (CP932-2BYTE.map): Call mapconv with cp932.awk. - - * charsets/mapconv: In UNICODE2 case, sort by 4th field after - running an awk program. - -2008-02-01 Kenichi Handa - - * charsets/mapconv: Handle UNICODE2. - - * charsets/Makefile (CJK): Include CP932-2BYTE.map - (CP932-2BYTE.map): New target. - -2008-02-01 Kenichi Handa - - * charsets: New directory for scripts to generate charset map - files in ../etc/charsets/. - - * charsets/Makefile, charsets/mapconv, charsets/compact.awk: - * charsets/big5.awk, charsets/gb180302.awk, charsets/gb180304.awk: - * charsets/kuten.awk: New files. - -2008-01-08 Glenn Morris - - * admin.el (set-version): Add doc/man/emacs.1. - -2008-01-06 Dan Nicolaescu - - * notes/copyright: - * MAINTAINERS: Remove references to files that have been removed. - -2008-01-04 Glenn Morris - - * admin.el (set-copyright): Add lib-src/ebrowse.c. - -2007-12-10 Stefan Monnier - - * CPP-DEFINES: New file. - -2007-12-08 Reiner Steib - - * FOR-RELEASE: Remove "window-system in face definition" [of - gnus-treat-emphasize]. Remove "Gnus archive groups". Add comment - on gnus-dired.el. - -2007-12-05 Glenn Morris - - * admin.el (set-version): Handle configure.in. Adapt for doc/ - directory layout for manuals. - -2007-12-01 Reiner Steib - - * FOR-RELEASE: Remove Gnus send mail problem. Other Gnus bugs have - been fixed in Gnus CVS but have not yet been synched to Emacs. - -2007-11-17 Glenn Morris - - * admin.el (process-lines): Move to ../lisp/subr.el. - -2007-10-23 Glenn Morris - - * MAINTAINERS: Move here from ../. - -2007-10-17 Juanma Barranquero - - * make-emacs: Doc fix. - -2007-08-28 Glenn Morris - - * admin.el: Provide self. - -2007-08-10 Jan Djärv - - * FOR-RELEASE: Add Gtk+ tool bar and GUD focus problem. - -2007-07-25 Glenn Morris - - * Relicense all FSF files to GPLv3 or later. - -2007-06-07 Glenn Morris - - * admin.el (set-copyright): New function. - -2007-04-25 Nick Roberts - - * make-tarball.txt: Add note about cutting the branch. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-02-03 Eli Zaretskii - - * nt/makedist.bat: Change EOL format to DOS. Don't use - redirection characters in REM lines. - -2007-01-27 Jan Djärv - - * FOR-RELEASE: Removed Gtk/Xft issue. - -2007-01-01 Miles Bader - - * quick-install-emacs (get_config_var): Deal with weird magic - string inserted by recent versions of autoconf. - -2006-11-25 Juanma Barranquero - - * admin.el (set-version): Set version number in - lib-src/makefile.w32-in. - -2006-11-06 Reiner Steib - - * FOR-RELEASE (BUGS): Remove "Build failure under Suse 10.0" was - due to a local miss-configuration. - -2006-10-28 Chong Yidong - - * make-announcement (OLD): Remove LEIM references in announcement - since it is now built-in. - -2006-10-15 YAMAMOTO Mitsuharu - - * admin.el (set-version): Set version numbers in "mac" subdirectory. - -2006-10-03 Kenichi Handa - - * FOR-RELEASE (BUGS): "An iso-8859-6 cannot be saved" fixed. - -2006-08-13 Chong Yidong - - * FOR-RELEASE: Elisp manual checking completed. - -2006-07-17 Reiner Steib - - * FOR-RELEASE: Update refcard section. - -2006-07-14 Kim F. Storm - - * FOR-RELEASE (BUGS): High cpu load on windows server sockets fixed. - -2006-07-09 Kim F. Storm - - * README: Use outline format. Add FOR-RELEASE. - -2006-06-27 Chong Yidong - - * FOR-RELEASE: Checking of info.texi done. - -2006-06-08 Reiner Steib - - * FOR-RELEASE: Update refcard section. - -2006-06-07 Reiner Steib - - * FOR-RELEASE: Update refcard section. - -2006-05-25 Chong Yidong - - * FOR-RELEASE: Key sequence elisp node done. - -2006-05-24 Reiner Steib - - * FOR-RELEASE: Update refcard translations. Add coding cookie. - -2006-05-21 Chong Yidong - - * FOR-RELEASE: point-entered /point-left bug fixed. - -2006-05-12 Eli Zaretskii - - * FOR-RELEASE: Spell-checking the manuals is now done; remove the - entry. - -2006-05-06 Bill Wohler - - * FOR-RELEASE: MH-E 8.0 has been released, so removed reminder - about it. - -2006-04-17 Ramprasad B - - * ./* (Copyright): Updated Copyright year(s). - -2006-02-24 Reiner Steib - - * FOR-RELEASE (BUGS): Add URLs/MIDs. - -2006-02-20 Kim F. Storm - - * FOR-RELEASE (NEW FEATURES): Completed work on this item: - Rework how fringe bitmaps are defined and used. - Currently, bitmap usage and bitmap appearence are "mixed-up" in a - one-level representation. It would be cleaner to split the - representation into a two-level model where first level maps - bitmap usage to a bitmap name, and second level maps bitmap name to - a bitmap appearence. - -2006-01-27 Chong Yidong - - * FOR-RELEASE: String allocation bugs fixed. - -2005-12-13 Bill Wohler - - * FOR-RELEASE: Ensure MH-E 8.0 has been released. - -2005-12-09 Reiner Steib - - * FOR-RELEASE (DOCUMENTATION): Remove message-mail, gnus-* - completing-read-multiple, mail-extract-address-components, - mail-mode, quail-define-package, save-buffer and - ucs-set-table-for-input from doc strings item (Done). - -2005-11-28 Chong Yidong - - * FOR-RELEASE: Icons installed. Partial completion bug fixed. - -2005-11-11 Kim F. Storm - - * FOR-RELEASE (FATAL ERRORS): Fix infinite loop in redisplay - when displaying a non-breaking space in an overlay string. - -2005-10-30 Chong Yidong - - * FOR-RELEASE: Init file change implemented. - -2005-10-27 Chong Yidong - - * FOR-RELEASE: Fringe angle bitmap at eob fixed. - -2005-10-19 Chong Yidong - - * FOR-RELEASE (New features): max-image-size implemented. - (Bugs): split-window done, by Kim F. Storm. - -2005-10-17 Bill Wohler - - * FOR-RELEASE (DOCUMENTATION): Removed lisp/toolbar from list - since it's gone. Also marked mh-e as done. - -2005-10-11 Juanma Barranquero - - * FOR-RELEASE (FATAL ERRORS): Remove item about JPEG - libraries on Windows (Done). - -2005-10-01 Jason Rumney - - * admin.el (set-version): Set version numbers in nt/emacs.rc. - -2005-08-31 Romain Francoise - - * FOR-RELEASE (New features): Remove vhdl-mode.el update - item (Done). - -2005-08-27 Romain Francoise - - * FOR-RELEASE (Bugs): Remove compile-internal item (Done). - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - -2005-06-10 Lute Kamstra - - * admin.el (set-version): Set version in lisp manual too. - * make-tarball.txt: Commit lispref/elisp.texi too. - -2005-06-04 Richard M. Stallman - - * emacs-pretesters: Refer to etc/DEBUG instead of duplicating it. - Other cleanups. - -2005-04-19 Lute Kamstra - - * make-tarball.txt: Don't commit lisp/loaddefs.el. - -2005-04-14 Lute Kamstra - - * nt/makedist.bat (elfiles): Update. - - * admin.el (add-release-logs): Fix require call. - -2005-03-30 Marcelo Toledo - - * FOR-RELEASE (Documentation): Added check the Emacs Tutorial. - The first line of every tutorial must begin with a sentence saying - "Emacs Tutorial" in the respective language. This should be - followed by "See end for copying conditions", likewise in the - respective language. - -2005-03-29 Luc Teirlinck - - * FOR-RELEASE (TO BE DONE SHORTLY BEFORE RELEASE): New section. - Add `undo-ask-before-discard' to it. - -2005-03-02 Miles Bader - - * quick-install-emacs: Only use the mkdir --verbose option if the - script's --verbose option was specified (this avoids problems with - default usage on systems where mkdir doesn't support that option). - -2005-02-15 Jason Rumney - - * nt/makedist.bat: Do not rely on non-standard behavior of - tar --exclude. - -2004-11-02 Jan Djärv - - * FOR-RELEASE (Indications): Remove two stage update for toolbar (Done). - -2004-09-20 Luc Teirlinck - - * FOR-RELEASE (Indications): Rearrange checklists for Emacs and - Elisp manuals. - -2004-09-18 Luc Teirlinck - - * FOR-RELEASE (Indications): Clean up and update checklists for - Emacs and Elisp manuals. - -2004-09-11 Kim F. Storm - - * FOR-RELEASE (New features): Remove Gnus 5.10 entry (Done!). - (Documentation): Add NEWS entry. - Add section lists for proof-reading Emacs and Lisp manuals. - -2004-08-29 Kim F. Storm - - * FOR-RELEASE (Documentation): Add man/ack.texi and AUTHORS. - -2004-08-28 Jan Djärv - - * FOR-RELEASE (Indications): Remove entry about GTK and geometry, - (now behaves as well as other ports). - -2004-06-28 Jan Djärv - - * FOR-RELEASE: Remove entry about GTK and monochrome displays (done). - -2004-06-26 Eli Zaretskii - - * FOR-RELEASE: Moved here from the etc directory. - -2004-05-08 Thien-Thi Nguyen - - * notes/BRANCH: New file, to be maintained per CVS branch. - -2003-10-01 Miles Bader - - * quick-install-emacs: Don't use "function" keyword when defining - shell functions. - -2003-09-29 Lute Kamstra - - * make-tarball.txt: Mention regenerating Emacs' AUTHORS file. - -2003-09-27 Miles Bader - - * quick-install-emacs: Remove fns-* pruning, since that file no - longer seems to be generated. - (AVOID): Quote literal periods. Quote braces in a way acceptable - to all parties (gawk gets bitchy about using `\'). - -2003-08-19 Miles Bader - - * quick-install-emacs: Add arch-specific ignored files to - quick-install-emacs. Use quoting for periods that's acceptable - to recent versions of gawk. - -2003-08-11 Markus Rost - - * cus-test.el: Remove obsolete workaround. - -2003-04-22 Andrew Innes - - * nt/makedist.bat: Fix multi-file .zip distribution, by splitting - emacs.exe before zipping, and including batch file to recreate - after unpacking. - - * nt/stitch.bat: New file. - - * nt/README-ftp-server: Update wording and version number etc. - Add extra instructions for installing multi-file .zip - distribution. - - * nt/README.W32: Remove personal email address and update wording. - - * nt/README-UNDUMP.W32: Remove personal email address and update - wording. - -2003-02-10 Francesco Potortì - - * make-changelog-diff: New script, code stolen from make-announcement. - - * make-announcement: Use make-changelog-diff. - -2003-01-20 Francesco Potortì - - * make-tarball.txt: Step-by-step instructions for making a tarball. - - * make-announcement: A script for creating pretest announcements. - -2003-01-17 Francesco Potortì - - * admin.el (add-release-logs): Expand the directory name before - calling find(1). - (add-release-logs): Use the same methods as add-log.el for writing - the date and the user's name and address. - -2003-01-07 Miles Bader - - * quick-install-emacs: Unset LANG etc. to avoid non-standard - command output from non-C locales. - -2002-10-16 Markus Rost - - * cus-test.el: Extended and reorganized. There are now 4 tests - which can be run in batch mode. See the Commentary section. - -2002-10-08 Markus Rost - - * cus-test.el: New file. - -2002-05-27 Miles Bader - - * quick-install-emacs (VERSION): Calculate using the same method - that configure.in uses. - -2002-04-26 Pavel Janík - - * emacs-pretesters: New file with information for Emacs - pretesters. - -2002-03-22 Paul Eggert - - * quick-install-emacs (PRUNED): Avoid "head -1" and "tail +2", as - POSIX 1003.1-2001 disallows both usages. - -2002-02-11 Andrew Innes - - * nt/makedist.bat: Don't include elisp/term/*.el files twice. - -2002-01-24 Andrew Innes - - * nt/README.W32: Remove unnecessary version number and date - references. - - * nt/README-UNDUMP.W32: Ditto. - -2001-12-06 Gerd Moellmann - - * make-emacs: Add --trace-move. - -2001-10-23 Andrew Innes - - * nt/makedist.bat: Remove remaining obsolete reference to - GETTING.GNU.SOFTWARE. - -2001-10-22 Gerd Moellmann - - * admin.el (set-version): Use `s' interactive spec for - version number. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-20 Gerd Moellmann - - * admin.el (add-release-logs): Put the log entry in lispref, too. - -2001-10-20 Miles Bader - - * quick-install-emacs: Exit if we can't find some variable. - (AVOID): Add .orig & .rej files. - (get_config_var): Be more liberal about format of config.status - sed commands. - -2001-10-19 Gerd Moellmann - - * admin.el: New file. - - * build-configs: Add --help option. Add support for building - in arbitrary source trees. - -2001-10-17 Gerd Moellmann - - * alloc-colors.c: New file. - -2001-10-13 Gerd Moellmann - - * make-emacs: Add --boot switch for bootstrapping. Logs to - EMACS_ROOT/boot.log, renames previous log file to boot.log.old. - -2001-10-05 Gerd Moellmann - - * Branch for 21.1. - -2001-09-04 Andrew Innes - - * admin/nt/makedist.bat: Remove reference to obsolete file - GETTING.GNU.SOFTWARE. Remove outdated comments. Explain about - version of tar used. - -;; Local Variables: -;; coding: utf-8 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, - 2008, 2009 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . - -;;; arch-tag: 97728c77-77c0-4156-b669-0e8c07d94e5a diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE deleted file mode 100644 index 66b65166ab5..00000000000 --- a/admin/FOR-RELEASE +++ /dev/null @@ -1,234 +0,0 @@ -Tasks needed before the next release. - -* TO BE DONE SHORTLY BEFORE RELEASE - -** Check for widow and orphan lines in manuals; -make sure all the pages really look ok in the manual as formatted. - -** Regenerate the pdf versions of the reference cards in etc/refcards/. -Done. - -** Ask maintainers of refcard translations to update them. - -Emacs 22 translators: - -LANG Translator Status -cs Pavel Janík -de Sven Joachim -fr Eric Jacoboni -pl Włodek Bzyl -pt-br Rodrigo Real -ru Alex Ott -sk Miroslav VaÅ¡ko - -** Remove temporary +++/--- lines in NEWS. - -** Try to reorder NEWS: most important things first, related items together. - -* BUGS - -** Does deleting frames run Lisp code? If so, can we get rid of that? -It is a dangerous design. -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01330.html - -** Why were the calls to x_fully_uncatch_errors commented out in eval.c? -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01987.html - -** rms: gnus-dired.el is a mistake. Those features should not -be part of Gnus. They should be moved to some other part of Emacs. -rsteib: Gnus dependencies in `gnus-dired.el' (and `mailcap.el') have been -minimized. I don't know what is left to do here. - -** Check for modes which bind M-s that conflicts with a new global binding M-s -and change key bindings where necessary. The current list of modes: - -1. Gnus binds `M-s' to `gnus-summary-search-article-forward'. - -2. Minibuffer binds `M-s' to `next-matching-history-element' - (not useful any more since C-s can now search in the history). - -3. Shell mode binds `M-s' to `comint-next-matching-input'. - This key binding can be changed later when we will implement - incremental search through the shell history. - -4. `center-line' in Text mode was already moved to the text formatting - keymap as `M-o M-s' (thus this binding is not necessary any more - in `nroff-mode-map' too and can be removed now from the nroff mode - because it can now use the global key binding `M-o M-s' `center-line'). - -5. PCL-CVS binds `M-s' to `cvs-status', and log-edit-mode binds it to - `log-edit-comment-search-forward'. Perhaps search commands - on the global key binding `M-s' are useless in these modes. - -** sdl.web@gmail.com, 30 Oct: ps-lpr-switches has no effect -http://lists.gnu.org/archive/html/emacs-devel/2007-10/msg02091.html - -Fixed by this change? - -2007-11-09 Vinicius Jose Latorre - - * ps-print.el: [...] - (ps-do-despool): If ps-lpr-switches is not a list, force it to be one. - -** In C, use EMACS_INT for variables and structure members -for buffer/string positions. E.g. struct it, struct text_pos. - -* DOCUMENTATION - -** Clean up Emacs.app references in code and documentation. - -** Document new font backend - -** Document XEmbed support - -** Check the Emacs Tutorial. - -The first line of every tutorial must begin with text ending in a -period (".", ASCII 0x2E) saying "Emacs Tutorial" in the respective -language. This should be followed by "See end for copying conditions", -likewise in the respective language. - -After each file name, on the same line or the following line, come the -names of the people who have checked it. - -SECTION READERS ----------------------------------- -etc/TUTORIAL rgm (but see Bug#3783) -etc/TUTORIAL.bg -etc/TUTORIAL.cn -etc/TUTORIAL.cs -etc/TUTORIAL.de Werner Lemberg -etc/TUTORIAL.eo -etc/TUTORIAL.es -etc/TUTORIAL.fr -etc/TUTORIAL.it -etc/TUTORIAL.ja -etc/TUTORIAL.ko -etc/TUTORIAL.nl -etc/TUTORIAL.pl -etc/TUTORIAL.pt_BR -etc/TUTORIAL.ro -etc/TUTORIAL.ru -etc/TUTORIAL.sk -etc/TUTORIAL.sl -etc/TUTORIAL.sv -etc/TUTORIAL.th -etc/TUTORIAL.zh - -** Check the manual. - -abbrevs.texi -- cyd -ack.texi -- rgm -anti.texi -- rgm -arevert-xtra.texi -- rgm -basic.texi -- cyd -buffers.texi -- cyd -building.texi -- cyd -calendar.texi -- rgm -cal-xtra.texi -- rgm -cmdargs.texi -- cyd -commands.texi -- cyd -custom.texi -- cyd -dired.texi -- cyd -dired-xtra.texi -- rgm -display.texi -- cyd -emacs.texi -- cyd -emacs-xtra.texi -- rgm -emerge-xtra.texi -- rgm -entering.texi -- cyd -files.texi -- cyd -fixit.texi -- cyd -fortran-xtra.texi -- rgm -frames.texi -- cyd -glossary.texi -- rgm Are "MULE" & "Multibyte Character" still appropriate? - Add "Unicode"? -help.texi -- cyd -indent.texi -- cyd -killing.texi -- cyd -kmacro.texi -- cyd -macos.texi -- davidswelt -maintaining.texi -- cyd -major.texi -- cyd -mark.texi -- cyd -mini.texi -- cyd -misc.texi -- cyd -msdog.texi -- eliz -msdog-xtra.texi -- eliz -mule.texi -- cyd -m-x.texi -- cyd -programs.texi -- cyd -regs.texi -- cyd -rmail.texi -- rgm -screen.texi -- cyd -search.texi -- cyd -sending.texi -- rgm -text.texi -- cyd -trouble.texi -- cyd -windows.texi -- rudalics -xresources.texi -- cyd - -** Check the Lisp manual. - -abbrevs.texi -- cyd -advice.texi -- cyd -anti.texi -- cyd -back.texi -- rgm -backups.texi -- cyd -buffers.texi -- cyd -commands.texi -- cyd -compile.texi -- cyd -control.texi -- cyd -customize.texi -- cyd -debugging.texi -- cyd -display.texi -- cyd -edebug.texi -- rgm -elisp.texi -- rgm -errors.texi -- cyd -eval.texi -- cyd -files.texi -- cyd -frames.texi -- cyd -functions.texi -- cyd -hash.texi -- cyd -help.texi -- cyd -hooks.texi -- cyd -index.texi -- rgm -internals.texi -- cyd -intro.texi -- cyd -keymaps.texi -- cyd -lists.texi -- cyd -loading.texi -- cyd -locals.texi -- cyd -macros.texi -- cyd -maps.texi -- cyd -markers.texi -- cyd -minibuf.texi -- cyd -modes.texi -- cyd -nonascii.texi -- cyd -numbers.texi -- cyd -objects.texi -- cyd -os.texi -- cyd -positions.texi -- cyd -processes.texi -- cyd -searching.texi -- cyd -sequences.texi -- cyd -streams.texi -- cyd -strings.texi -- cyd -symbols.texi -- cyd -syntax.texi -- cyd -text.texi -- cyd -tips.texi -- cyd -variables.texi -- cyd -windows.texi -- rudalics - -* PLANNED ADDITIONS - -** CEDET (not for 23.1 due to paperwork issues, perhaps for 23.2) -** js2-mode -** pov-mode (probably not for Emacs-23: waiting for a Free POV-Ray). -** gas-mode ? - - -Local variables: -mode: outline -coding: utf-8 -end: diff --git a/admin/MAINTAINERS b/admin/MAINTAINERS deleted file mode 100644 index 0e8c9b32325..00000000000 --- a/admin/MAINTAINERS +++ /dev/null @@ -1,217 +0,0 @@ - Emacs Maintainers - -This file contains a description of who is responsible for maintaining -what parts of the Emacs distribution. The areas can be defined -"arbitrarily", but should provide fairly well-defined boundaries so -that there are not too many ambiguities. - -The list below consists of 3 parts. First, the list of areas that -someone wants to be maintaining (i.e. has a particularly keen interest -for it); then the list of areas that someone is willing to maintain, -although he would not necessarily mind if someone else was the -official maintainer; and finally the list of areas for which no -maintainer has been found so far. - -============================================================================== -1. -============================================================================== - -Richard Stallman - ??? - -Jason Rumney - W32 - -Eli Zaretskii - The MS-DOS (a.k.a. DJGPP) port: - config.bat - msdos/* - src/msdos.[ch] - src/dosfns.[ch] - src/w16select.c - src/s/msdos.h - lisp/term/internal.el - lisp/term/pc-win.el - lisp/dos-fns.el - lisp/dos-w32.el - lisp/dos-vars.el - - lisp/term/tty-colors.el - lisp/international/codepage.el - - doc/emacs/msdog.texi - -Kenichi Handa - Mule - -Stefan Monnier - src/regex.c - src/syntax.c - src/keymap.c - font-lock/jit-lock/syntax - minor-mode/major-mode infrastructure - text filling - minibuffer completion - lisp/textmodes/outline.el - -Miles Bader - src/xfaces.c - field-property related stuff - lisp/comint.el - lisp/shell.el - [other comint-related packages] - lisp/button.el - lisp/image-file.el - lisp/minibuf-eldef.el - lisp/rfn-eshadow.el - -Jay Belanger - Calc - lisp/calc/* - etc/calccard.tex - doc/misc/calc.texi - -Michael Olson - ERC - lisp/erc/* - etc/ERC-NEWS - doc/misc/erc.texi - lisp/emacs-lisp/tq.el - -============================================================================== -2. -============================================================================== - -Steven Tamm - MacOS - -Eli Zaretskii - doc/* - lispref/* - info/dir - - src/xfaces.c - src/term.c - src/frame.c - src/dired.c - - lisp/arc-mode.el - lisp/menu-bar.el - lisp/hexl.el - lisp/info.el - lisp/ls-lisp.el - lisp/startup.el - -Stefan Monnier - src/intervals.c - src/keyboard.c - lisp/textmodes/tex-mode.el - lisp/progmodes/perl-mode.el - lisp/progmodes/tcl.el - lisp/emacs-lisp/easymenu.el - -Miles Bader - src/eval.c - src/bytecode.c - src/editfns.c - lisp/textmodes/refill.el - -============================================================================== -3. -============================================================================== - -src/Makefile.in -src/abbrev.c -src/alloc.c -src/alloca.c -src/alloca.s -src/atimer.c -src/bitmaps/ -src/buffer.c -src/callint.c -src/callproc.c -src/casefiddle.c -src/casetab.c -src/category.c -src/ccl.c -src/charset.c -src/cm.c -src/cmds.c -src/coding.c -src/composite.c -src/config.in -src/data.c -src/dispnew.c -src/doc.c -src/doprnt.c -src/ecrt0.c -src/emacs.c -src/epaths.in -src/fileio.c -src/filelock.c -src/filemode.c -src/firstfile.c -src/floatfns.c -src/fringe.c -src/fns.c -src/fontset.c -src/getloadavg.c -src/gmalloc.c -src/gtkutil.c -src/indent.c -src/insdel.c -src/image.c -src/lastfile.c -src/lread.c -src/m/ -src/macros.c -src/makefile.w32-in -src/marker.c -src/md5.c -src/minibuf.c -src/mktime.c -src/pre-crt0.c -src/prefix-args.c -src/print.c -src/process.c -src/ralloc.c -src/region-cache.c -src/s/ -src/scroll.c -src/search.c -src/sound.c -src/strftime.c -src/sysdep.c -src/termcap.c -src/terminfo.c -src/textprop.c -src/tparam.c -src/undo.c -src/unexaix.c -src/unexalpha.c -src/unexec.c -src/unexelf.c -src/unexhp9k800.c -src/unexw32.c -src/vm-limit.c -src/w32.c -src/w32console.c -src/w32fns.c -src/w32heap.c -src/w32inevt.c -src/w32menu.c -src/w32proc.c -src/w32reg.c -src/w32select.c -src/w32term.c -src/w32xfns.c -src/widget.c -src/window.c -src/xdisp.c -src/xfns.c -src/xmenu.c -src/xrdb.c -src/xselect.c -src/xterm.c - -;;; arch-tag: 869126d4-4851-41b2-8470-14dd492a3c98 diff --git a/admin/README b/admin/README deleted file mode 100644 index 0c44aa0e32f..00000000000 --- a/admin/README +++ /dev/null @@ -1,97 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - - The admin directory - -This directory contains scripts and other things useful for developing -and maintaining Emacs. These files are not part of Emacs releases -because they are not deemed generally useful, and you have to know -what you do when using them. - - -* Instructions and scripts used to prepare an Emacs release. - -** FOR-RELEASE - -Living list of activities that must be completed before the next release. - -** make-tarball.txt - -Instructions to create pretest or release tarballs, annoucements, etc. - -** admin.el - -Utilities for setting version numbers and alike. - -** make-announcement, make-changelog-diff - -Scripts used to prepare release announcements. - - -* Scripts that can be used to build and test Emacs. - -** build-configs - -Build Emacs in various configurations. - -** make-emacs - -Build Emacs in various ways. - -** quick-install-emacs - -Install emacs quickly (`incrementally'). - -** alloc-color.c - -A utility program that allocates a given number of colors on X. Can -be used to debug Emacs with dense colormaps (PseudoColor). - -** check-doc-strings - -Check doc strings against documentation. - -** cus-test.el - -Tests for custom types and load problems. - -** diff-tar-files - -Show files added/removed between two tar files. - -** revdiff - -Get CVS diffs of files. - - -Brief description of sub-directories: - -charsets scripts for generating charset map files - in ../etc/charsets -unidata scripts for generating character property files - in ../lisp/international - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . - -Local variables: -mode: outline -paragraph-separate: "[ ]*$" -end: - -# arch-tag: 812b9461-bc0a-46a7-925e-24bd41118463 diff --git a/admin/admin.el b/admin/admin.el deleted file mode 100644 index f4ebdc5e614..00000000000 --- a/admin/admin.el +++ /dev/null @@ -1,219 +0,0 @@ -;;; admin.el --- utilities for Emacs administration - -;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -;; Free Software Foundation, Inc. - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; add-release-logs Add ``Version X released'' change log entries. -;; set-version Change Emacs version number in source tree. -;; set-copyright Change emacs short copyright string (eg as -;; printed by --version) in source tree. - -;;; Code: - -(defun add-release-logs (root version) - "Add \"Version VERSION released.\" change log entries in ROOT. -Root must be the root of an Emacs source tree." - (interactive "DEmacs root directory: \nNVersion number: ") - (setq root (expand-file-name root)) - (unless (file-exists-p (expand-file-name "src/emacs.c" root)) - (error "%s doesn't seem to be the root of an Emacs source tree" root)) - (require 'add-log) - (let* ((logs (process-lines "find" root "-name" "ChangeLog")) - (entry (format "%s %s <%s>\n\n\t* Version %s released.\n\n" - (funcall add-log-time-format) - (or add-log-full-name (user-full-name)) - (or add-log-mailing-address user-mail-address) - version))) - (dolist (log logs) - (unless (string-match "/gnus/" log) - (find-file log) - (goto-char (point-min)) - (insert entry))))) - -(defun set-version-in-file (root file version rx) - (find-file (expand-file-name file root)) - (goto-char (point-min)) - (unless (re-search-forward rx nil t) - (error "Version not found in %s" file)) - (replace-match (format "%s" version) nil nil nil 1)) - -(defun set-version (root version) - "Set Emacs version to VERSION in relevant files under ROOT. -Root must be the root of an Emacs source tree." - (interactive "DEmacs root directory: \nsVersion number: ") - (unless (file-exists-p (expand-file-name "src/emacs.c" root)) - (error "%s doesn't seem to be the root of an Emacs source tree" root)) - (set-version-in-file root "lisp/version.el" version - (rx (and "emacs-version" (0+ space) - ?\" (submatch (1+ (not (in ?\")))) ?\"))) - (set-version-in-file root "README" version - (rx (and "version" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "configure.in" version - (rx (and "AC_INIT" (1+ (not (in ?,))) - ?, (0+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/emacs/emacs.texi" version - (rx (and "EMACSVER" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/lispref/elisp.texi" version - (rx (and "EMACSVER" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/lispref/vol1.texi" version - (rx (and "EMACSVER" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/lispref/vol2.texi" version - (rx (and "EMACSVER" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/lispref/book-spine.texinfo" version - (rx (and "Emacs Version" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/man/emacs.1" version - (rx (and ".TH EMACS" (1+ not-newline) - "GNU Emacs" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "doc/misc/faq.texi" version - (rx (and "VER" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file root "lib-src/makefile.w32-in" version - (rx (and "VERSION" (0+ space) "=" (0+ space) - (submatch (1+ (in "0-9.")))))) - ;; nt/emacs.rc also contains the version number, but in an awkward - ;; format. It must contain four components, separated by commas, and - ;; in two places those commas are followed by space, in two other - ;; places they are not. - (let* ((version-components (append (split-string version "\\.") - '("0" "0"))) - (comma-version - (concat (car version-components) "," - (cadr version-components) "," - (cadr (cdr version-components)) "," - (cadr (cdr (cdr version-components))))) - (comma-space-version - (concat (car version-components) ", " - (cadr version-components) ", " - (cadr (cdr version-components)) ", " - (cadr (cdr (cdr version-components)))))) - (set-version-in-file root "nt/emacs.rc" comma-version - (rx (and "FILEVERSION" (1+ space) - (submatch (1+ (in "0-9,")))))) - (set-version-in-file root "nt/emacs.rc" comma-version - (rx (and "PRODUCTVERSION" (1+ space) - (submatch (1+ (in "0-9,")))))) - (set-version-in-file root "nt/emacs.rc" comma-space-version - (rx (and "\"FileVersion\"" (0+ space) ?, (0+ space) - ?\" (submatch (1+ (in "0-9, "))) "\\0\""))) - (set-version-in-file root "nt/emacs.rc" comma-space-version - (rx (and "\"ProductVersion\"" (0+ space) ?, - (0+ space) ?\" (submatch (1+ (in "0-9, "))) - "\\0\""))) - ;; Likewise for emacsclient.rc - (set-version-in-file root "nt/emacsclient.rc" comma-version - (rx (and "FILEVERSION" (1+ space) - (submatch (1+ (in "0-9,")))))) - (set-version-in-file root "nt/emacsclient.rc" comma-version - (rx (and "PRODUCTVERSION" (1+ space) - (submatch (1+ (in "0-9,")))))) - (set-version-in-file root "nt/emacsclient.rc" comma-space-version - (rx (and "\"FileVersion\"" (0+ space) ?, (0+ space) - ?\" (submatch (1+ (in "0-9, "))) "\\0\""))) - (set-version-in-file root "nt/emacsclient.rc" comma-space-version - (rx (and "\"ProductVersion\"" (0+ space) ?, - (0+ space) ?\" (submatch (1+ (in "0-9, "))) - "\\0\"")))) - ;; nextstep. - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Info.plist" - version (rx (and "CFBundleGetInfoString" (1+ anything) "Emacs" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Info.plist" - version (rx (and "CFBundleShortVersionString" (1+ not-newline) ?\n - (0+ not-newline) "" (0+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Resources/English.lproj/InfoPlist.strings" - version (rx (and "CFBundleShortVersionString" (0+ space) ?= (0+ space) - ?\" (0+ space) "Version" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Resources/English.lproj/InfoPlist.strings" - version (rx (and "CFBundleGetInfoString" (0+ space) ?= (0+ space) - ?\" (0+ space) "Emacs version" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/GNUstep/Emacs.base/Resources/Info-gnustep.plist" - version (rx (and "ApplicationRelease" (0+ space) ?= (0+ space) - ?\" (0+ space) (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/GNUstep/Emacs.base/Resources/Info-gnustep.plist" - version (rx (and "FullVersionID" (0+ space) ?= (0+ space) - ?\" (0+ space) "Emacs" (1+ space) - (submatch (1+ (in "0-9.")))))) - (set-version-in-file - root "nextstep/GNUstep/Emacs.base/Resources/Emacs.desktop" - version (rx (and "Version=" (submatch (1+ (in "0-9."))))))) - -;; Note this makes some assumptions about form of short copyright. -;; FIXME add the \year in the refcards/*.tex files. -(defun set-copyright (root copyright) - "Set Emacs short copyright to COPYRIGHT in relevant files under ROOT. -Root must be the root of an Emacs source tree." - (interactive (list - (read-directory-name "Emacs root directory: " nil nil t) - (read-string - "Short copyright string: " - (format "Copyright (C) %s Free Software Foundation, Inc." - (format-time-string "%Y"))))) - (unless (file-exists-p (expand-file-name "src/emacs.c" root)) - (error "%s doesn't seem to be the root of an Emacs source tree" root)) - (set-version-in-file root "lisp/version.el" copyright - (rx (and "emacs-copyright" (0+ space) - ?\" (submatch (1+ (not (in ?\")))) ?\"))) - (set-version-in-file root "lib-src/ebrowse.c" copyright - (rx (and "emacs_copyright" (0+ (not (in ?\"))) - ?\" (submatch (1+ (not (in ?\")))) ?\"))) - (set-version-in-file root "lib-src/etags.c" copyright - (rx (and "emacs_copyright" (0+ (not (in ?\"))) - ?\" (submatch (1+ (not (in ?\")))) ?\"))) - (set-version-in-file root "lib-src/rcs2log" copyright - (rx (and "Copyright" (0+ space) ?= (0+ space) - ?\' (submatch (1+ nonl))))) - ;; This one is a nuisance, as it needs to be split over two lines. - (string-match "\\(.*[0-9]\\{4\\} *\\)\\(.*\\)" copyright) - ;; nextstep. - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Info.plist" - copyright (rx (and "CFBundleGetInfoString" (1+ anything) "Emacs" (1+ space) - (1+ (in "0-9.")) (1+ space) - (submatch (1+ (not (in ?\<))))))) - (set-version-in-file - root "nextstep/Cocoa/Emacs.base/Contents/Resources/English.lproj/InfoPlist.strings" - copyright (rx (and "NSHumanReadableCopyright" (0+ space) ?\= (0+ space) - ?\" (submatch (1+ (not (in ?\"))))))) - (set-version-in-file - root "nextstep/GNUstep/Emacs.base/Resources/Info-gnustep.plist" - copyright (rx (and "Copyright" (0+ space) ?\= (0+ space) - ?\" (submatch (1+ (not (in ?\")))))))) - -(provide 'admin) - -;; arch-tag: 4ea83636-2293-408b-884e-ad64f22a3bf5 -;;; admin.el ends here diff --git a/admin/alloc-colors.c b/admin/alloc-colors.c deleted file mode 100644 index a8d0b92f613..00000000000 --- a/admin/alloc-colors.c +++ /dev/null @@ -1,116 +0,0 @@ -/* Allocate X colors. Used for testing with dense colormaps. - Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . */ - - -#include -#include -#include -#include -#include - -void -fatal (const char *fmt, ...) -{ - va_list ap; - - va_start (ap, fmt); - vfprintf (stderr, fmt, ap); - fputc ('\n', stderr); - va_end (ap); - exit (1); -} - -void -usage (const char *progname) -{ - fprintf (stderr, "Usage %s options\n", progname); - fprintf (stderr, "-n NCOLORS allcoate NCOLORS colors\n"); - exit (1); -} - -int -main (int argc, char **argv) -{ - Display *dpy; - int opt, ncolors = 0, i; - XColor *allocated; - int nallocated; - XColor color; - Colormap cmap; - - while ((opt = getopt (argc, argv, "n:")) != EOF) - switch (opt) - { - case 'n': - ncolors = atoi (optarg); - break; - - case '?': - usage (argv[0]); - } - - if (ncolors == 0) - usage (argv[0]); - - dpy = XOpenDisplay (""); - if (dpy == NULL) - fatal ("Cannot open display"); - cmap = DefaultColormap (dpy, 0); - - allocated = malloc (ncolors * sizeof *allocated); - nallocated = 0; - memset (&color, 0, sizeof color); - - while (nallocated < ncolors - && color.red < 65536) - { - allocated[nallocated] = color; - if (XAllocColor (dpy, cmap, &allocated[nallocated])) - { - for (i = 0; i < nallocated; ++i) - if (allocated[i].red == allocated[nallocated].red - && allocated[i].green == allocated[nallocated].green - && allocated[i].blue == allocated[nallocated].blue) - break; - - if (i == nallocated) - { - printf ("allocated %d/%d/%d\n", - allocated[nallocated].red, - allocated[nallocated].green, - allocated[nallocated].blue); - ++nallocated; - } - } - - ++color.red; - ++color.green; - ++color.blue; - } - - fprintf (stderr, "Waiting. Press ^C to stop.\n"); - while (1) - sleep (10); - - XCloseDisplay (dpy); - return 0; -} - -/* arch-tag: f1be90ac-5b70-43c2-835e-5a6432a25145 - (do not change this comment) */ diff --git a/admin/build-configs b/admin/build-configs deleted file mode 100755 index da24a2d79f0..00000000000 --- a/admin/build-configs +++ /dev/null @@ -1,100 +0,0 @@ -#! /usr/bin/perl -# Build Emacs in several different configurations. - -# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -require 5; -use Getopt::Long; -use File::Basename; -use Cwd; - -@configs = - ( - ["--without-x", "--optim"], - ["--without-x-toolkit", "--optim"], - ["--without-toolkit-scroll-bars", "--optim"], - ["--with-x-toolkit=lucid", "--optim"], - ["--with-x-toolkit=motif", "--optim"], - ["--with-x-toolkit=motif", "--enable-checking"], - ["--with-x-toolkit=motif", "--gcc3"], - ["--with-x-toolkit=motif", ""], - ); - -$log = "/tmp/$$.out"; -print "Using log file $log\n"; -unlink $log; - -$root = $ENV{"EMACS_ROOT"}; -$root = "/gd/gnu/emacs" unless $root; - -$rc = GetOptions ("help" => \$help); -if ($rc == 0 || $help) - { - print <>$log 2>&1"); - if ($rc != 0) - { - print "configure failed\n"; - exit 1; - } - - $rc = system ("make-emacs --all $make_options >>$log 2>&1"); - if ($rc != 0) - { - print "Make failed\n"; - exit 1; - } - } - -# Local Variables: -# mode: cperl -# End: - -# arch-tag: 20a4452d-610a-4e54-9abc-ffe79f5c0d30 diff --git a/admin/charsets/.arch-inventory b/admin/charsets/.arch-inventory deleted file mode 100644 index 0924093e90d..00000000000 --- a/admin/charsets/.arch-inventory +++ /dev/null @@ -1,4 +0,0 @@ -# Unlike most emacs dirs, admin/charsets has a simple non-autoconf-generated makefile -source ^(Makefile)$ - -# arch-tag: ee36cfe3-96f8-4e91-aec4-008c80a85e6b diff --git a/admin/charsets/.cvsignore b/admin/charsets/.cvsignore deleted file mode 100644 index ea375dc5915..00000000000 --- a/admin/charsets/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -*.map -*.el diff --git a/admin/charsets/Makefile b/admin/charsets/Makefile deleted file mode 100644 index 3c44417eb4d..00000000000 --- a/admin/charsets/Makefile +++ /dev/null @@ -1,310 +0,0 @@ -# Makefile -- Makefile to generate charset maps in etc/charsets. -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 -# -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: - -# If your system doesn't have the directory /usr/share/i18n/charmaps, -# get the source of the latest glibc, gzip all the charmap files in -# the directory "localedate/charmaps", and set the variable -# GLIBC_CHARMAPS to that directory. - -GLIBC_CHARMAPS=/usr/share/i18n/charmaps - -CHARSETS = ${ISO8859} ${IBM} ${CODEPAGE} ${CJK} ${MISC} ${MULE} - -# Note: We can not prepend "ISO-" to these map files because of file -# name limits on DOS. -ISO8859 = \ - 8859-2.map 8859-3.map 8859-4.map 8859-5.map 8859-6.map 8859-7.map \ - 8859-8.map 8859-9.map 8859-10.map 8859-11.map 8859-13.map 8859-14.map \ - 8859-15.map 8859-16.map - -IBM = \ - IBM037.map IBM038.map \ - IBM256.map IBM273.map IBM274.map IBM275.map IBM277.map IBM278.map \ - IBM280.map IBM281.map IBM284.map IBM285.map IBM290.map IBM297.map \ - IBM420.map IBM423.map IBM424.map IBM437.map IBM500.map IBM850.map \ - IBM851.map IBM852.map IBM855.map IBM856.map IBM857.map IBM860.map \ - IBM861.map IBM862.map IBM863.map IBM864.map IBM865.map IBM866.map \ - IBM868.map IBM869.map IBM870.map IBM871.map IBM874.map IBM875.map \ - IBM880.map IBM891.map IBM903.map IBM904.map IBM905.map IBM918.map \ - IBM1004.map IBM1026.map IBM1047.map - -CODEPAGE = \ - CP737.map CP775.map CP1125.map\ - CP1250.map CP1251.map CP1252.map CP1253.map CP1254.map \ - CP1255.map CP1256.map CP1257.map CP1258.map \ - CP10007.map \ - CP720.map CP858.map - -CJK = GB2312.map GBK.map GB180302.map GB180304.map \ - BIG5.map BIG5-HKSCS.map\ - CNS-1.map CNS-2.map CNS-3.map CNS-4.map CNS-5.map CNS-6.map CNS-7.map \ - CNS-F.map \ - JISX0201.map JISX0208.map JISX0212.map JISX2131.map JISX2132.map \ - JISC6226.map CP932-2BYTE.map JISX213A.map\ - KSC5601.map KSC5636.map JOHAB.map - -MISC = KOI-8.map KOI8-R.map KOI8-U.map KOI8-T.map ALTERNATIVNYJ.map \ - MIK.map PTCP154.map \ - TIS-620.map VISCII.map VSCII.map VSCII-2.map\ - KA-PS.map KA-ACADEMY.map \ - HP-ROMAN8.map NEXTSTEP.map MACINTOSH.map EBCDICUK.map EBCDICUS.map \ - stdenc.map symbol.map \ - CP949-2BYTE.map \ - BIG5-1.map BIG5-2.map - -# Emacs-mule charsets. -MULE = MULE-ethiopic.map MULE-ipa.map MULE-is13194.map \ - MULE-sisheng.map MULE-tibetan.map \ - MULE-lviscii.map MULE-uviscii.map - -TRANS_TABLE = cp51932.el eucjp-ms.el - -all: ${CHARSETS} ${TRANS_TABLE} - -AWK = gawk - -# Rules for each charset - -VSCII.map: ${GLIBC_CHARMAPS}/TCVN5712-1.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[0-9a-f].[ ]/' GLIBC-1 compact.awk > $@ - -VSCII-2.map: ${GLIBC_CHARMAPS}/TCVN5712-1.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[2-7a-f].[ ]/' GLIBC-1 compact.awk \ - | sed 's/0x20-0x7F.*/0x00-0x7F 0x0000/' > $@ - -ALTERNATIVNYJ.map: IBM866.map - # Generating $@... - @echo "# Modified from IBM866.map according to the chart at" > $@ - @echo "# http://www.cyrillic.com/ref/cyrillic/koi-8alt.html," >> $@ - @echo "# with guesses for the Unicodes of the glyphs." >> $@ - @sed -e '1 d' \ - -e '/0xF2/ s/ .*/ 0x2019/' \ - -e '/0xF3/ s/ .*/ 0x2018/' \ - -e '/0xF4/ s/ .*/ 0x0301/' \ - -e '/0xF5/ s/ .*/ 0x0300/' \ - -e '/0xF6/ s/ .*/ 0x203A/' \ - -e '/0xF7/ s/ .*/ 0x2039/' \ - -e '/0xF8/ s/ .*/ 0x2191/' \ - -e '/0xF9/ s/ .*/ 0x2193/' \ - -e '/0xFA/ s/ .*/ 0x00B1/' \ - -e '/0xFB/ s/ .*/ 0x00F7/' < $< >> $@ - -MIK.map: mapfiles/bulgarian-mik.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '1,$$' CZYBORRA compact.awk > $@ - -PTCP154.map: mapfiles/PTCP154.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^0x/' IANA compact.awk > $@ - -stdenc.map: mapfiles/stdenc.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^[0-9A-Fa-f]/' UNICODE compact.awk > $@ - -symbol.map: mapfiles/symbol.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^[0-9A-Fa-f]/' UNICODE compact.awk > $@ - -CP720.map: mapfiles/CP720.map.gz - # Generating $@... - @zcat $< > $@ - -CP858.map: mapfiles/CP858.map.gz - # Generating $@... - @zcat $< > $@ - -CP949-2BYTE.map: ${GLIBC_CHARMAPS}/CP949.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[89a-f]/' GLIBC-2 compact.awk > $@ - -GB2312.map: ${GLIBC_CHARMAPS}/GB2312.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2-7 compact.awk > $@ - -GBK.map: ${GLIBC_CHARMAPS}/GBK.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[89a-f]/' GLIBC-2 compact.awk > $@ - -GB180302.map: ${GLIBC_CHARMAPS}/GB18030.gz mapconv gb180302.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x..\/x..[ ]/' GLIBC-2 gb180302.awk > $@ - -GB180304.map: GB180302.map gb180304.awk - # Generating $@... - @$(AWK) -f gb180304.awk < $< > $@ - -JISX0201.map: ${GLIBC_CHARMAPS}/JIS_X0201.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[0-9]/' GLIBC-1 compact.awk > $@ - @echo "# Generated by hand" >> $@ - @echo "0xA1-0xDF 0xFF61" >> $@ - -JISX0208.map: ${GLIBC_CHARMAPS}/EUC-JP.gz mapconv - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2-7 \ - | sed 's/0x2015/0x2014/' > $@ - -JISX0212.map: ${GLIBC_CHARMAPS}/EUC-JP.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x8f/ s,/x8f,,' GLIBC-2-7 compact.awk > $@ - -JISX2131.map: ${GLIBC_CHARMAPS}/EUC-JISX0213.gz mapconv - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2-7 \ - | sed -e 's/0x2015/0x2014/' -e 's/0x2299/0x29BF/' > $@ - -JISX2132.map: ${GLIBC_CHARMAPS}/EUC-JISX0213.gz mapconv - # Generating $@... - @mapconv $< '/^<.*[ ]\/x8f/ s,/x8f,,' GLIBC-2-7 > $@ - -JISX213A.map: mapfiles/JISX213A.map.gz - # Generating $@ - @zcat $< > $@ - -CP932-2BYTE.map: mapfiles/CP932.TXT.gz mapconv cp932.awk - # Generating $@... - @mapconv $< '/^0x[89A-F][0-9A-F][0-9A-F]/' UNICODE2 cp932.awk > $@ - -cp51932.el: CP932-2BYTE.map cp51932.awk - @$(AWK) -f cp51932.awk < CP932-2BYTE.map > $@ - -eucjp-ms.el: ${GLIBC_CHARMAPS}/EUC-JP-MS.gz eucjp-ms.awk - @zcat $< | $(AWK) -f eucjp-ms.awk > $@ - -JISC6226.map : mapfiles/Uni2JIS.gz mapconv kuten.awk - # Generating $@... - @mapconv $< '/^[^#].*0-/' YASUOKA kuten.awk > $@ - -KSC5601.map: ${GLIBC_CHARMAPS}/EUC-KR.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2-7 compact.awk > $@ - -BIG5.map: ${GLIBC_CHARMAPS}/BIG5.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2 > $@ - -BIG5-1.map: BIG5.map mapconv big5.awk - # Generating $@... - @echo "# Generated from $<" > $@ - @sed -n -e '/0xa140/,/0xc8fe/p' < $< | gawk -f big5.awk >> $@ - -BIG5-2.map: BIG5.map mapconv big5.awk - # Generating $@... - @echo "# Generated from $<" > $@ - @sed -n -e '/0xc940/,$$ p' < $< | gawk -f big5.awk >> $@ - -BIG5-HKSCS.map: ${GLIBC_CHARMAPS}/BIG5-HKSCS.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[89a-f].\//' GLIBC-2 compact.awk > $@ - -JOHAB.map: ${GLIBC_CHARMAPS}/JOHAB.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[89a-f]/' GLIBC-2 compact.awk > $@ - -CNS-1.map: ${GLIBC_CHARMAPS}/EUC-TW.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x[a-f]/' GLIBC-2-7 compact.awk > $@ - -# CNS-1.map: mapfiles/cns2ucsdkw.txt mapconv compact.awk -# # Generating $@... -# @mapconv $< '/^C1/' KANJI-DATABASE compact.awk > $@ - -CNS-2.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C2/' KANJI-DATABASE compact.awk > $@ - -CNS-3.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C3/' KANJI-DATABASE compact.awk > $@ - -CNS-4.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C4/' KANJI-DATABASE compact.awk > $@ - -CNS-5.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C5/' KANJI-DATABASE compact.awk > $@ - -CNS-6.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C6/' KANJI-DATABASE compact.awk > $@ - -CNS-7.map: mapfiles/cns2ucsdkw.txt.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^C7/' KANJI-DATABASE compact.awk > $@ - -CNS-F.map: ${GLIBC_CHARMAPS}/EUC-TW.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*\/x8e\/xaf/ s,/x8e/xaf,,' GLIBC-2-7 compact.awk > $@ - -# General target to produce map files for mule charsets. -MULE-%.map: mapfiles/MULE-%.map.gz - # Generating $@... - @zcat $< > $@ - -# General target to produce map files for ISO-8859, GEORGIAN, and -# EBCDIC charsets. We can not use the original file name because of -# file name limit on DOS. "KA" is ISO 639 language code for Georgian. - -8859-%.map: ${GLIBC_CHARMAPS}/ISO-8859-%.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x/' GLIBC-1 compact.awk > $@ - -KA-%.map: ${GLIBC_CHARMAPS}/GEORGIAN-%.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x/' GLIBC-1 compact.awk > $@ - -EBCDIC%.map: ${GLIBC_CHARMAPS}/EBCDIC-%.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x/' GLIBC-1 compact.awk > $@ - -# General target to produce map files for single-byte charsets. - -%.map: ${GLIBC_CHARMAPS}/%.gz mapconv compact.awk - # Generating $@... - @mapconv $< '/^<.*[ ]\/x/' GLIBC-1 compact.awk > $@ - -install: - @for f in ${CHARSETS}; do \ - if test -r $$f; then \ - if ! cmp -s $$f ../../etc/charsets/$$f; then \ - echo updating $$f; \ - cp $$f ../../etc/charsets; \ - fi; \ - fi; \ - done - @for f in ${TRANS_TABLE}; do \ - if test -r $$f; then \ - if ! cmp -s $$f ../../lisp/international/$$f; then \ - echo updating $$f; \ - cp $$f ../../lisp/international; \ - fi; \ - fi; \ - done - -# Clear files that are automatically generated. -clean: - rm -f ${CHARSETS} ${TRANS_TABLE} - -# arch-tag: 90b3bf30-1fef-45bf-b30c-665c30c22310 diff --git a/admin/charsets/big5.awk b/admin/charsets/big5.awk deleted file mode 100644 index 7213c437a10..00000000000 --- a/admin/charsets/big5.awk +++ /dev/null @@ -1,73 +0,0 @@ -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -BEGIN { - tohex["A"] = 10; - tohex["B"] = 11; - tohex["C"] = 12; - tohex["D"] = 13; - tohex["E"] = 14; - tohex["F"] = 15; - tohex["a"] = 10; - tohex["b"] = 11; - tohex["c"] = 12; - tohex["d"] = 13; - tohex["e"] = 14; - tohex["f"] = 15; -} - -function decode_hex(str) { - n = 0; - len = length(str); - for (i = 1; i <= len; i++) - { - c = substr (str, i, 1); - if (c >= "0" && c <= "9") - n = n * 16 + (c - "0"); - else - n = n * 16 + tohex[c]; - } - return n; -} - -function decode_big5(big5) { - b0 = int(big5 / 256); - b1 = big5 % 256; -# (0xFF - 0xA1 + 0x7F - 0x40) = 157 -# (0xA1 - (0x7F - 0x40)) = 98 -# (0xC9 - 0xA1) * (0xFF - 0xA1 + 0x7F - 0x40) = 6280 - if (b1 < 127) - idx = (b0 - 161) * 157 + (b1 - 64); - else - idx = (b0 - 161) * 157 + (b1 - 98); - if (b0 >= 201) - idx -= 6280; - b0 = int(idx / 94) + 33; - b1 = (idx % 94) + 33; - return (b0 * 256 + b1) -} - -{ - big5 = decode_hex($1); - code = decode_big5(big5); - printf "0x%04X %s\n", code, $2; -} - - -# arch-tag: 36f08d21-0d24-4b67-852d-a9a51299586d diff --git a/admin/charsets/compact.awk b/admin/charsets/compact.awk deleted file mode 100644 index 0e55631ea2c..00000000000 --- a/admin/charsets/compact.awk +++ /dev/null @@ -1,123 +0,0 @@ -# compact.awk -- Make charset map compact. -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: -# Make a charset map compact by changing this kind of line sequence: -# 0x00 0x0000 -# 0x01 0x0001 -# ... -# 0x7F 0x007F -# to one line of this format: -# 0x00-0x7F 0x0000 - -BEGIN { - tohex["0"] = 1; - tohex["1"] = 2; - tohex["2"] = 3; - tohex["3"] = 4; - tohex["4"] = 5; - tohex["5"] = 6; - tohex["6"] = 7; - tohex["7"] = 8; - tohex["8"] = 9; - tohex["9"] = 10; - tohex["A"] = 11; - tohex["B"] = 12; - tohex["C"] = 13; - tohex["D"] = 14; - tohex["E"] = 15; - tohex["F"] = 16; - tohex["a"] = 11; - tohex["b"] = 12; - tohex["c"] = 13; - tohex["d"] = 14; - tohex["e"] = 15; - tohex["f"] = 16; - from_code = 0; - to_code = -1; - to_unicode = 0; - from_unicode = 0; -} - -function decode_hex(str, idx) { - n = 0; - len = length(str); - for (i = idx; i <= len; i++) - { - c = tohex[substr (str, i, 1)]; - if (c == 0) - break; - n = n * 16 + c - 1; - } - return n; -} - -/^\#/ { - print; - next; -} - -{ - code = decode_hex($1, 3); - unicode = decode_hex($2, 3); - if ((code == to_code + 1) && (unicode == to_unicode + 1)) - { - to_code++; - to_unicode++; - } - else - { - if (to_code < 256) - { - if (from_code == to_code) - printf "0x%02X 0x%04X\n", from_code, from_unicode; - else if (from_code < to_code) - printf "0x%02X-0x%02X 0x%04X\n", from_code, to_code, from_unicode; - } - else - { - if (from_code == to_code) - printf "0x%04X 0x%04X\n", from_code, from_unicode; - else if (from_code < to_code) - printf "0x%04X-0x%04X 0x%04X\n", from_code, to_code, from_unicode; - } - from_code = to_code = code; - from_unicode = to_unicode = unicode; - } -} - -END { - if (to_code < 256) - { - if (from_code == to_code) - printf "0x%02X 0x%04X\n", from_code, from_unicode; - else - printf "0x%02X-0x%02X 0x%04X\n", from_code, to_code, from_unicode; - } - else - { - if (from_code == to_code) - printf "0x%04X 0x%04X\n", from_code, from_unicode; - else - printf "0x%04X-0x%04X 0x%04X\n", from_code, to_code, from_unicode; - } -} - -# arch-tag: 7e6f57c3-8e62-4af3-8916-ca67bca3a0ce diff --git a/admin/charsets/cp51932.awk b/admin/charsets/cp51932.awk deleted file mode 100644 index 161342e7f9f..00000000000 --- a/admin/charsets/cp51932.awk +++ /dev/null @@ -1,59 +0,0 @@ -# cp51932.awk -- Generate a translation table for CP51932. -# Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: - -# Genereate a translation table for CP51932 (EUC-JP of MicroSoft Version). -# It maps invalid JISX0208 code points used by CP51932 to Unicode. -# 4th field of the input has these meanings: -# 0: JISX0208 characters. -# 1: NEC special characters. -# 2: IBM extension characters. -# 3: NEC selection of IBM extension characters. -# Among them, 1 and 3 are the target characters. 2 should have -# already been mapped to 1 or 3. - -BEGIN { - print ";;; cp51932.el -- translation table for CP51932. -*- no-byte-compile: t -*-"; - print ";;; Automatically genrated from CP932-2BYTE.map"; - print "(let ((map"; - printf " '(;JISEXT<->UNICODE"; -} - -/# [13]/ { - printf "\n (#x%s . #x%s)", $5 ,substr($2, 3, 4); -} - -END { - print ")))"; - print " (mapc #'(lambda (x)"; - print " (setcar x (decode-char 'japanese-jisx0208 (car x))))"; - print " map)"; - print " (define-translation-table 'cp51932-decode map)"; - print " (mapc #'(lambda (x)"; - print " (let ((tmp (car x)))"; - print " (setcar x (cdr x)) (setcdr x tmp)))"; - print " map)"; - print " (define-translation-table 'cp51932-encode map))"; - print ""; - print ";; arch-tag: d21c06e5-a548-4dda-8802-c2922ff19da3"; -} - -# arch-tag: bbae996b-2d1c-4e85-bb55-ac30146d7504 diff --git a/admin/charsets/cp932.awk b/admin/charsets/cp932.awk deleted file mode 100644 index fb50d098a7b..00000000000 --- a/admin/charsets/cp932.awk +++ /dev/null @@ -1,117 +0,0 @@ -# cp932.awk -- Add sort keys and append user defined area to CP932-2BYTE.map. -# Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: - -# Add a sort key 0, 1, 2, or 3 at the tail of each line as a comment -# to realize the round trip mapping to Unicode works as described in -# this page: -# http://support.microsoft.com/default.aspx?scid=kb;EN-US;170559 -# Each sort key means as below: -# 0: JISX0208 characters. -# 1: NEC special characters. -# 2: IBM extension characters. -# 3: NEC selection of IBM extension characters. -# 4: user defined area - -BEGIN { - tohex["A"] = 10; - tohex["B"] = 11; - tohex["C"] = 12; - tohex["D"] = 13; - tohex["E"] = 14; - tohex["F"] = 15; -} - -function decode_hex(str) { - n = 0; - len = length(str); - for (i = 1; i <= len; i++) - { - c = substr(str, i, 1); - if (c >= "0" && c <= "9") - n = n * 16 + (c - "0"); - else - n = n * 16 + tohex[c]; - } - return n; -} - -function sjis_to_jis_ku(code) -{ - s1 = int(code / 256); - s2 = code % 256; - if (s2 >= 159) # s2 >= 0x9F - { - if (s1 >= 224) # s1 >= 0xE0 - j1 = s1 * 2 - 352; # j1 = s1 * 2 - 0x160 - else - j1 = s1 * 2 - 224; # j1 = s1 * 2 - 0xE0 - j2 = s2 - 126 # j2 = s2 - #x7E - } - else - { - if (s1 >= 224) - j1 = s1 * 2 - 353; # j1 = s1 * 2 - 0x161 - else - j1 = s1 * 2 - 225; # j1 = s1 * 2 - 0xE1 - if (s2 >= 127) # s2 >= #x7F - j2 = s2 - 32; - else - j2 = s2 - 31; - } - return j1 - 32; -} - -/^0x[89E]/ { - sjis=decode_hex(substr($1, 3, 4)) - ku=sjis_to_jis_ku(sjis); - if (ku == 13) - printf "%s # 1 %02X%02X\n", $0, j1, j2; - else if (ku >= 89 && ku <= 92) - printf "%s # 3 %02X%02X\n", $0, j1, j2; - else - printf "%s # 0 %02X%02X\n", $0, j1, j2; - next; -} - -/^0xF/ { - printf "%s # 2\n", $0; - next; -} - -{ - print; -} - -END { - code = 57344; # 0xE000 - for (i = 240; i < 250; i++) - { - for (j = 64; j <= 126; j++) - printf "0x%02X%02X 0x%04X # 4\n", i, j, code++; - for (j = 128; j <= 158; j++) - printf "0x%02X%02X 0x%04X # 4\n", i, j, code++; - for (; j <= 252; j++) - printf "0x%02X%02X 0x%04X # 4\n", i, j, code++; - } -} - -# arch-tag: 998dc444-759d-43ef-87e3-2ab205011394 diff --git a/admin/charsets/eucjp-ms.awk b/admin/charsets/eucjp-ms.awk deleted file mode 100644 index 7710e0c0e00..00000000000 --- a/admin/charsets/eucjp-ms.awk +++ /dev/null @@ -1,113 +0,0 @@ -# eucjp-ms.awk -- Generate a translation table for eucJP-ms. -# Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: - -# eucJP-ms is one of eucJP-open encoding defined at this page: -# http://home.m05.itscom.net/numa/cde/ucs-conv/appendix.html -# This program reads the mapping file EUC-JP-MS (of glibc) and -# generates the Elisp file eucjp-ms.el that defines two translation -# tables `eucjp-ms-decode' and `eucjp-ms-encode'. - -BEGIN { - FS = "[ \t][ \t]*" - - # STATE: 0/ignore, 1/JISX0208, 2/JISX0208 target range - # 3/JISX0212 4/JISX0212 target range - state = 0; - - JISX0208_FROM1 = "/xad/xa1"; - JISX0208_TO1 = "/xad/xfc"; - JISX0208_FROM2 = "/xf5/xa1"; - JISX0212_FROM = "/x8f/xf3/xf3"; - - print ";;; eucjp-ms.el -- translation table for eucJP-ms. -*- no-byte-compile: t -*-"; - print ";;; Automatically generated from /usr/share/i18n/charmaps/EUC-JP-MS.gz"; - print "(let ((map"; - print " '(;JISEXT<->UNICODE"; -} - -function write_entry (unicode) { - if (state == 1) { - if ($2 == JISX0208_FROM1 || $2 == JISX0208_FROM2) - state = 2; - } else if (state == 3) { - if ($2 == JISX0212_FROM) - state = 4; - } - if (state == 2) { - jis = $2 - gsub("/x", "", jis); - printf "\n (#x%s . #x%s)", jis, unicode; - if ($2 == JISX0208_TO1) - state = 1; - } else if (state == 4) { - jis = substr($2, 5, 8); - gsub("/x", "", jis); - printf "\n (#x%s #x%s)", jis, unicode; - } -} - - -/^% JIS X 0208/ { - state = 1; - next; -} - -/^% JIS X 0212/ { - state = 3; - next; -} - -/^END CHARMAP/ { - state = 0; - next; -} - -/^/ { - if (state > 0) - write_entry(substr($1, 3, 4)); -} - -/^%IRREVERSIBLE%/ { - if (state > 0) - write_entry(substr($1, 17, 4)); -} - -END { - print ")))"; - print " (mapc #'(lambda (x)"; - print " (let ((code (logand (car x) #x7F7F)))"; - print " (if (integerp (cdr x))"; - print " (setcar x (decode-char 'japanese-jisx0208 code))"; - print " (setcar x (decode-char 'japanese-jisx0212 code))"; - print " (setcdr x (cadr x)))))"; - print " map)"; - print " (define-translation-table 'eucjp-ms-decode map)"; - print " (mapc #'(lambda (x)"; - print " (let ((tmp (car x)))"; - print " (setcar x (cdr x)) (setcdr x tmp)))"; - print " map)"; - print " (define-translation-table 'eucjp-ms-encode map))"; - print ""; - print ";; arch-tag: c4191096-288a-4f13-9b2a-ee7a1f11eb4a"; -} - -# arch-tag: d9cc7af7-2d6e-48cd-8eed-a6d25226de7c diff --git a/admin/charsets/gb180302.awk b/admin/charsets/gb180302.awk deleted file mode 100644 index d5ee74c4c1f..00000000000 --- a/admin/charsets/gb180302.awk +++ /dev/null @@ -1,101 +0,0 @@ -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -BEGIN { - tohex["A"] = 10; - tohex["B"] = 11; - tohex["C"] = 12; - tohex["D"] = 13; - tohex["E"] = 14; - tohex["F"] = 15; - tohex["a"] = 10; - tohex["b"] = 11; - tohex["c"] = 12; - tohex["d"] = 13; - tohex["e"] = 14; - tohex["f"] = 15; - from_gb = 0; - to_gb = -1; - to_unicode = 0; - from_unicode = 0; -} - -function decode_hex(str) { - n = 0; - len = length(str); - for (i = 1; i <= len; i++) - { - c = substr (str, i, 1); - if (c >= "0" && c <= "9") - n = n * 16 + (c - "0"); - else - n = n * 16 + tohex[c]; - } - return n; -} - -function gb_to_index(gb) { - b0 = int(gb / 256); - b1 = gb % 256; - idx = (((b0 - 129)) * 191 + b1 - 64); -# if (b1 >= 128) -# idx--; - return idx -} - -function index_to_gb(idx) { - b0 = int(idx / 191) + 129; - b1 = (idx % 191) + 64; -# if (b1 >= 127) -# b1++; - return (b0 * 256 + b1); -} - -/^\#/ { - print; - next; -} - -{ - gb = gb_to_index(decode_hex(substr($1, 3, 4))); - unicode = decode_hex(substr($2, 3, 4)); - if ((gb == to_gb + 1) && (unicode == to_unicode + 1)) - { - to_gb++; - to_unicode++; - } - else - { - if (from_gb == to_gb) - printf "0x%04X 0x%04X\n", index_to_gb(from_gb), from_unicode; - else if (from_gb < to_gb) - printf "0x%04X-0x%04X 0x%04X\n", - index_to_gb(from_gb), index_to_gb(to_gb), from_unicode; - from_gb = to_gb = gb; - from_unicode = to_unicode = unicode; - } -} - -END { - if (from_gb <= to_gb) - printf "0x%04X-0x%04X 0x%04X\n", - index_to_gb(from_gb), index_to_gb(to_gb), from_unicode; -} - -# arch-tag: d7dbad89-a512-41a4-8ee0-ba1a4505b8c1 diff --git a/admin/charsets/gb180304.awk b/admin/charsets/gb180304.awk deleted file mode 100644 index 74038b4a293..00000000000 --- a/admin/charsets/gb180304.awk +++ /dev/null @@ -1,123 +0,0 @@ -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -BEGIN { - tohex["A"] = 10; - tohex["B"] = 11; - tohex["C"] = 12; - tohex["D"] = 13; - tohex["E"] = 14; - tohex["F"] = 15; - tohex["a"] = 10; - tohex["b"] = 11; - tohex["c"] = 12; - tohex["d"] = 13; - tohex["e"] = 14; - tohex["f"] = 15; -} - -function decode_hex(str) { - n = 0; - len = length(str); - for (i = 1; i <= len; i++) - { - c = substr (str, i, 1); - if (c >= "0" && c <= "9") - n = n * 16 + (c - "0"); - else - n = n * 16 + tohex[c]; - } - return n; -} - -function gb_to_index(gb) { - b0 = int(gb / 256); - b1 = gb % 256; - idx = (((b0 - 129)) * 191 + b1 - 64); -# if (b1 >= 127) -# idx--; - return idx -} - -function index_to_gb(idx) { - b3 = (idx % 10) + 48; - idx = int(idx / 10); - b2 = (idx % 126) + 129; - idx = int(idx / 126); - b1 = (idx % 10) + 48; - b0 = int(idx / 10) + 129; - return sprintf("%02X%02X%02X%02X", b0, b1, b2, b3); -} - -/^\#/ { - print; - next; -} - -/0x....-0x..../ { - gb_from = gb_to_index(decode_hex(substr($1, 3, 4))); - gb_to = gb_to_index(decode_hex(substr($1, 10, 4))); - unicode = decode_hex(substr($2, 3, 4)); - while (gb_from <= gb_to) - { - table[unicode++] = 1; - gb_from++; - } - next; -} - -{ - gb = decode_hex(substr($1, 3, 4)); - unicode = decode_hex(substr($2, 3, 4)); - table[unicode] = 1; -} - -END { - from_gb = -1; - to_gb = 0; - from_i = 0; - table[65536] = 1; - for (i = 128; i <= 65536; i++) - { - if (table[i] == 0) - { - if (i < 55296 || i >= 57344) - { - if (from_gb < 0) - { - from_gb = to_gb; - from_i = i; - } - to_gb++; - } - } - else if (from_gb >= 0) - { - if (from_gb + 1 == to_gb) - printf "0x%s\t\t0x%04X\n", - index_to_gb(from_gb), from_i; - else - printf "0x%s-0x%s\t0x%04X\n", - index_to_gb(from_gb), index_to_gb(to_gb - 1), from_i; - from_gb = -1; - } - } -} - -# arch-tag: 8e5a22ae-610e-411f-ae17-d6e528b30d71 diff --git a/admin/charsets/kuten.awk b/admin/charsets/kuten.awk deleted file mode 100644 index 9d43f2e0e8f..00000000000 --- a/admin/charsets/kuten.awk +++ /dev/null @@ -1,7 +0,0 @@ -/^[0-9]/ { - ku=substr($1, 3, 2) + 32; - ten=substr($1, 5, 2) + 32; - printf "0x%02X%02X %s\n", ku, ten, $2; -} - -# arch-tag: dade6b45-b4c5-42ab-9d49-d6bf23a710b6 diff --git a/admin/charsets/mapconv b/admin/charsets/mapconv deleted file mode 100755 index 64c0772af52..00000000000 --- a/admin/charsets/mapconv +++ /dev/null @@ -1,146 +0,0 @@ -#!/bin/sh - -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - -# Commentary: - -# Convert charset map of various format into this: -# 0xXX 0xYYYY -# where, -# XX is a code point of the charset in hexa-decimal, -# YYYY is the corresponding Unicode character code in hexa-decimal. -# Arguments are: -# $1: source map file -# $2: address pattern for sed (optionally with substitution command) -# $3: format of source map file -# GLIBC-1 GLIBC-2 GLIBC-2-7 CZYBORRA IANA UNICODE UNICODE2 YASUOKA -# $4: awk script - -FILE="admin/charsets/$1" -BASE=`basename $1 .gz` - -case "$3" in - GLIBC*) - FILE="$BASE in localedate/charmaps of glibc"; - SOURCE="";; - CZYBORRA) - BASE="$BASE.gz"; - SOURCE="http://czyborra.com/charsets/${BASE}";; - IANA) - SOURCE="http://www.iana.org/assignments/charset-reg/${BASE}";; - UNICODE) - SOURCE="http://www.unicode.org/Public/MAPPINGS/VENDORS/ADOBE/${BASE}";; - UNICODE2) - SOURCE="http://www.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/${BASE}";; - YASUOKA) - BASE="$BASE.Z"; - SOURCE="http://kanji.zinbun.kyoto-u.ac.jp/~yasuoka/ftp/CJKtable/${BASE}";; - KANJI-DATABASE) - SOURCE="http://kanji-database.cvs.sourceforge.net/viewvc/*checkout*/kanji-database/kanji-database/data/cns2ucsdkw.txt?revision=1.4";; - *) - echo "Unknown file type: $3"; - exit 1;; -esac - -if [ -n "$SOURCE" ] ; then - echo "# Generated from $FILE which is a copy of"; - echo "# $SOURCE" -else - echo "# Generated from $FILE" -fi - - -if [ -n "$4" ] ; then - if [ -f "$4" ] ; then - AWKPROG="gawk -f $4" - else - echo "Awk program does not exist: $4" - exit 1 - fi -else - AWKPROG=cat -fi - -if [ "$3" = "GLIBC-1" ] ; then - # Source format is: - # /xXX - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's,]*\)>[ ]*/x\(..\).*,0x\2 0x\1,' \ - | sort | ${AWKPROG} -elif [ "$3" = "GLIBC-2" ] ; then - # Source format is: - # /xXX/xZZ - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's,]*\)>[ ]*/x\(..\)/x\(..\).*,0x\2\3 0x\1,' \ - | sort | ${AWKPROG} -elif [ "$3" = "GLIBC-2-7" ] ; then - # Source format is: - # /xXX/xZZ - # We must drop MSBs of XX and ZZ - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/xa/x2/g' -e 's/xb/x3/g' -e 's/xc/x4/g' \ - -e 's/xd/x5/g' -e 's/xe/x6/g' -e 's/xf/x7/g' \ - -e 's,]*\)>[ ]*/x\(..\)/x\(..\).*,0x\2\3 0x\1,' \ - | tee temp \ - | sort | ${AWKPROG} -elif [ "$3" = "CZYBORRA" ] ; then - # Source format is: - # =XX U+YYYY - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/=\(..\)[^U]*U+\([0-9A-F]*\).*/0x\1 0x\2/' \ - | sort | ${AWKPROG} -elif [ "$3" = "IANA" ] ; then - # Source format is: - # 0xXX 0xYYYY - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/\(0x[0-9A-Fa-f]*\)[^0]*\(0x[0-9A-Fa-f]*\).*/\1 \2/' \ - | sort | ${AWKPROG} -elif [ "$3" = "UNICODE" ] ; then - # Source format is: - # YYYY XX - # We perform reverse sort to prefer the first one in the - # duplicated mappings (e.g. 0x20->U+0020, 0x20->U+00A0). - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/\([0-9A-F]*\)[^0-9A-F]*\([0-9A-F]*\).*/0x\2 0x\1/' \ - | sort -r -elif [ "$3" = "UNICODE2" ] ; then - # Source format is: - # 0xXXXX 0xYYYY # ... - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/\([0-9A-Fx]*\)[^0]*\([0-9A-Fx]*\).*/\1 \2/' \ - | ${AWKPROG} | sort -n -k 4,4 -elif [ "$3" = "YASUOKA" ] ; then - # Source format is: - # YYYY 0-XXXX (XXXX is a Kuten code) - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/\([0-9A-F]*\)[^0]*0-\([0-9]*\).*/0x\2 0x\1/' \ - | sort | ${AWKPROG} -elif [ "$3" = "KANJI-DATABASE" ] ; then - # Source format is: - # C?-XXXX U+YYYYY ..... - zcat $1 | sed -n -e "$2 p" \ - | sed -e 's/...\(....\) U+\([0-9A-F]*\).*/0x\1 0x\2/' \ - | sort | ${AWKPROG} -else - echo "Invalid arguments: $3" - exit 1 -fi - -# arch-tag: c33acb47-7eb6-4872-b871-15e1447e8f0e diff --git a/admin/charsets/mapfiles/CP720.map.gz b/admin/charsets/mapfiles/CP720.map.gz deleted file mode 100644 index c8918bb30a371bb12c930b737799756fe652e731..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 562 zcmV-20?qv&iwFo#?=eaM14B?ZGB7S}VQ>H~lfjOgFc60C`xKV;+{73#xT-2)8~0N6 z)Sg%D#=AjHAR?qq-@g3w=k~=j%zQI;o>f@#u;zn057TWpo&Kr!Wj?Df$927Y-tY6Y z`#b&~FZnPIyLtK8SNf<5dlRhVeAK zp0c`4hrDb-BrfNxn&0Kew;#V$T5{fs#QE)Z&eJ-q<29_?C_E?LDlBpf4_)=Iy&sV|* zO1>7hl4Hq|(+JlV+>+7IJLbT~cRZJGJsB(YfgHh+9KbzU1e0)qRRm3jPbh>-Vfq_< z8|YsM(_gMT(7%*(`q#Lc@bJf#g@-?`IMBbA`t-M0d!WC?yn+5!>OcI2>2IYM{VnE= z^tX5_k^UC-BmFJ*7U^H3SEPR}`Sh1(6CeKAZKS`&t|I*{{3HDf`Ii0~K9T;doYTJ* z2l}^?Lw|=^BK=!%kH^x>JGCVi&_CWOF1F`8^%$aWkeC>Ragxc6yq;8S!DJbPc9IcH z1*OD)nMb=MBbWlKNc@+1tTB0>W6UHY=myu9B6Fl6N9d#u-}}b@0c^b2ldA*(0K};$ AL;wH) diff --git a/admin/charsets/mapfiles/CP858.map.gz b/admin/charsets/mapfiles/CP858.map.gz deleted file mode 100644 index ac9d75b277eb10648c293196bbd75f19e7238cb7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 715 zcmV;+0yO;}iwFo-?=eaM14B?aH8?J9VQ>H~lub_?F%(7j{0d8~o6IC6jH{}WKf9^A zYS(BW21ZRLC=4zA_vPOEb_eJA`ONb**DhV!xU_>ijq}@hJpOZ!m-ESed0v*6&+B!Y zSAVD9(@Q%{rY{t0J!^M|LGf7yfOpUCpB*z4tAxi0^T@AC4maP#u7>?!{WH!uIpz4Fg+ z^YX9w7BBy>1}meUOsuTw(Lc$*hfk9KmMs4b z=8)vyljYC1lXj}-y5%2k$^6NKd~g>@{yX-U{~q6!?@`9x^iUFd zXevFS2neAEfzUz^0n)#t^WL@Yx@&#+pPZcY?6aS<_xbIbK*D$L-hV{-<{v@^ceK=0 zl^&Qs_#=%sNH}HWnZC#74EE%eiBEY~j^b!b8f$s3x?;NLPnojhJ;|X zLZY5WhY5PA{9y!w+XCa)^Jfr9<~o*NkLFdN1vB6=+8-~NNwHxC9Sz>3R=6X!meHIF zG^<5m4pCVY_}yK%6SN2__51iJFTu>TpevQ%Yg9YJ-zXBSMhn& zLcoRz*aB_>nxBp44A%=5>jf>~dp(cb3)`X<3D^`gr$xY;KnOM+|R6g4-IJs_y%3rMK zF{$x=i|A1|^hE)dIYX{=98~u6gy%33KEHwj5d`sD{uM~_R|usD zYOSC*r5i0Zv+u5QBdi8zfY6$&|I9?hFJ_BoCOzs$ccT4R^Sl-c+F!8b<yy!GYe{X-C&&P@n4goUyeR0)0}p%7S| zQhkI3q-BPxKU6Oj;DIyRoM&1kENND2-xv7n^JXa7t63ZZzh;5v<&Uo$EmCgIhU=%+ zyY%W=qHQ)-TPUtIPv|YdL4xTf4r+tA)Wc>>(y@YdevoyA6OT2=G=qfJzFZn)GcuZj z1j8-8e{Z_*{8?^XLLnK_6283LnuGpceaDHkZc)8*@!`ezQ%VwH10vt0|m4 z9n4`~=q<2D_a6zSH2YU;j#8L2bJ#i=9@E{uE5RE^!6sls^0E5$eD1I#=fdcBa6gpr zoWRPo%@tO}9>9sT&O~P1%(C z)VdP-*y2oWpkVqoi~Zu4#A^*(1I^W42%GNOp{~%y#el{8{wOx1Fr}1VqW~F0TW$&( zpqw5e6ud{%zG{K}n%-d(X;K7BE1KuyV9KyMKCRD0nJ!xZQzmD3O-|BHHk`df`>_d- zF$GP3wjJ>X*tx-99QNd&8BGDF&W9B(GnSUe>OwYCYD?VO*$mIZriG^Lu4P!Nzyjp} z!xnG4+n`GHyrEHyZGk*8(F838>AE)gop-T3TTpmr{(I!bjcfrAKS#29*4 zaEkxXY+)g6)3r0Qe{NUxdPGNlui<6@*vnv-b_b(qQYnIfp;ob9dwf%-juh(IdnvUW zkKy?v6tKxsvZ8^R^7*APf~^_uOwf~B;E88o zGXWDc7+*`E#Tz7}xn6w6@KZU#Y8R^uVj}(D4)3AXUk|(rm2CKvSO%6MIsJPFi~Ng{ zIdnk3AoJ&>-(6Ut(AQ#!(u@VVKdQ?30k+?bgFLmdmduFSpJ#)afP64%=U0oyS^?#rZX*@0rw!V9?;O#jmTy=G8LL565uSr#uzho@7Q7t|b zduZy=&q`+xrL&g~h>ci>dui?Q3>{y#9B_ZH_UajB!s_M=s}qfY@baOl-6uxNE+)hr z*WAr2Y^r*@L+jF6lw#+pzgl-*t_2*9U(!D~1URsEd%pUIMR>}DwL zM4oijS9Zy_1g3hYAl?mq$01m@os&o(?aEehMex0f7JJz}ne{p7e%Rp8G9eqUmE=&$ z_8Re@Wjl(Heg$8gkJvb`ScXz|)o5VRiqvuSO0?7x;teO^Cm;F$`_*g-7C^IlGNY?G zVMgoV_R{&RzHmx#4MKV&)U0SY+&!a`K=u>#n>)90qL({eS>zXY4kXD^lWm+^Ov;VR zm#UUm4*QBL8wd)17SX&|Wi?RcvAQK*hhH~!IB-|eo9ZkR=jAFX%vtjFc*|RhI)5c) zw@lBJTNBzD_6#r0b62Nn_^Qz#@(lLCNQhIMf1nHBkyBv3!9xuUS3n4m`i8N(t`EE* z7Xd3s5TM3kjI5OKsI>t+JlB)oAPVVHVJCD`_Mlko`yU?C<~=e@bkM$-l$NypT`3P~ zQ>(`fI1_6tv#l#NA5CRtmjkynujR-KqGqY}Lq##@YwOF1#hKPJIpRjqM&MMRSS{O( zbIEh|?Ezjs?>eHi^WUygZ}&Jr{r@cYmiHv|{DW#wL#Rsw& zNP?-cXRcMJ|K7x6{$`IRApZLG*s+~TOJ~&u@>hBEjY+o=S{AD=CB1E>zIwB3*Q*mk z-`;O~)cTK#!{3ss$M;Jee6xSI!T)9X^ho`lP4{oSlxKqf>({~MH$h$_f-c4q+Bl{A zW5fKPbt0tn**Vn#hvH!OmBVFwmj0dGsTh zOcqz2K8KDO7Mdd7>(L-#E4;v5q?nadx3KJ0EK_k?h`xAjA6voiS({~+pDL@hYT zOkKqJX^ZBT@H0gcrKu3=XnNr1QDyTX_U!V~Xv&cdZI@$I>!0p9-w5wviUNK> z2BN57HWcdI{v;{Vy}fXsSJ%+or}V(l-m)6U(`QQ3mO`t&yR=&wBF1Pwm!D#0Z041L z^^q4aDH0%2&_iICSJ#7D&(2{v%aGJS$OoiUh~F-1jbNQUs!Sbd8}1~fxi1#Zzuxyn zSf46HL;p15ujH;-Q%|$-*??=(Ub?t__ zUJ9YrdwtDzSr1@&=Lc7i!q@OM{%T`qb1anSzR%Zl-a@>_$qU7hXYeOM3`TQ`W)VzR zZvj;mD=U}nRA|#jkNAKBQ-`b~W!NcHY z)wVSwamcMA8Z>xwKi|rcpy2bj9<-*eN)P2^9G{yyukeIW!RGQOXEuwvs<)i18{H4R zAeXlNfCZZp`ba)Muyu5k!(LM4(a!lWNd1zYGb>%dDnRcz{xm#+GwMI1(@cqHP3>t~ zT0)6a(pgPHONmc{OGs7jOI#TPMOR0~QIsY>DidBY9H++nkZ*mO61#!fIf@S>NKuBl zbA6VCrK2|cMuGxLW)#c5q~(X!B7;k89&S#I23$w$?8DWm^~JYiUEqme7>Ygt@&LrPiQfY)ZzUttl(Pz^T7 ztUyK>>A_ht3PK2#M)*FQHlF6Y73goQ^=c=0Hx3PLE^!T>cN2OooTaJQogsziEVFDN z5_JU+0t78;X{^yR!bwdKr?@5aA_r`!-NT;!2SZp+SCv!GB(F9YUH-_#=}Oc01#@CIic3ff4J{P+qOR}#NcG17-gW+q zHTj&!4{OHqBQ>!$2&I_P7q~mCDMqZB)s7?WmYSVCBSqp=2@xf^QTFQS+`{nuSLCPL zE*WB~UgrvBsvw23aBh?7$41o$Z&iyfBZ_FQG8_8nAXjL$f~duk$?{rFW*kzm1|1X3 zje3>alrNH_w?9lncJlo7%IV#pCZNO_cEdgTZ(wN!^el96n=GprU-nLr8?=D6`4A1E z3T_lR)`qz5fz?{AuMx|^d*+(*Bo@Q?z13Kox=sk4hG?EyW9pbH8q757jYU+pm$qNYP=_UbVcSp^7e(B6Z$C$;MU(2eF{SU3bysSwdlT zHUUKlf8>uA{^%bN_ciVsYS5h{!b%5a-GPT{1jj7E!rU2+9pWpw&qA|CdY&A$QoG37MhGG#%={E zJ>W4fbm6_FJCvy{4_ z%zVL1v2}Vf42wQVuMRN}Wzf{9TuIkW$1oq60`A5f+iYmKYdfQt0$<4uS66~LBg!eu zHtD`k%Nf{$VW0Rf^}P98UcK|4B`??#?udGpZwA(P=eHY)RQ|?XyJf9B1Qx_#f244F z>5SW~=KI;bWIEg2qe6=iLVlo7k)l17fGE5c*%wP31CD&4^(fEp3Du!!Uu|{hhV=$>1|gNBh7AJA*k!X_lYR>Vv@!>Jmop$JJ9~vCSRD|+ z+HCk}-3_$fOy!!0#b?pDv5$${uq*7;dGkc9wdS+A+ zHM7Kj@D95HEgN4N8OD;<63Ui7RC_t1<+~C6M3be?U|y~jZ1D!FZL}&MhFQwio0F~5 z*<8<7|Ahbsq^MW z+zwj{#M#+S?Txr&wieE&o+vmT`*|DL(mA%e@S3R{Tktg(3ijG1yIcIc>y&4_Z$ap_&vud2sWa*59y}yXwEf$L7zOio+l^h zw?taRHF$?2Dtk@JDxWIb_0F7RW(*?#y~3$d8bw3&g02p3cwJ(5FR0!rt;%-Gnu#9E%e|60w#fhbSMdB_I3G8 zU3-Zrg63GUt9-dnR>{Z{g_G>G&C0^`o^x&^{?X)5WV5+^T8& z#mOHPeE&CTQK7rMau}-SvyJ##tY3?fe(NW)(F7pKL=4kTtwtsM0Mdv7X+r-uLap&i zg10Dc2G|ho*80!qP<&SV>V{D_%Tacp>N0aryz4t=$bxFnYHNk1^G3{VCo6w8>pJ8w#zoL z>3RuV3u-{CS&t0DpYXouv!lsrbX{Gw?&;Ch#54Q+ZxJWYLyFuLqi>*er!$rs-nV?# zk!7s1>(&yzTkQ31HZRG>E%~)$)Mb7ztfvUPgAuIT#7RvP@wJqo7I(fks90{-O=_Zh zHq(Bu6ml0nP^WZ4?0@!o^f{&LuKMp8R_*2B?k}4>PI!LIJuLw1kEN)_Z5I5uGP3ka zzAJnzJ}C%1LaSEqpYlGlEyPBoqJ7HW(SJhEr%(0$B%oDWX4pJltMggswJoT=XJFVR zUyCS5J}@vFB~8i+uTzWGb(TG>^{T9;P``jWToAY11s1fbMlI%7dIMX(ksaq{u-$mp zif2MVi*-nq!jv*Is(yAL$f_xk8I{lVv}iS(*F$t4sdiGP%V@Fy6k)lW+$(17C z62In<+|8gVqMc`SK#Lw9(8J~dWWBA=v#!-nLePLCgc*enA{HicGr;ZD|GMq~aP0_i zS>52WqB^d)T=kK(G81Rdc0fTCUY-=s$4(B1cg$m|uizOGLNdgk#qAaGRbbzqV?6#c#_0 zzzbOZ2JhT|JV-`t8D-WpU?^Y&8mV-W<;W=K0{O;x7^7o8FP+S8b$J|o%Z$-p-Z?^pA zd7a3a95lTWIw994+zgD0@Ln{+vFj8-Ynkq&kyQ*(%{RXdhqW1cH5t+@6AcJp5x>FO zzZUB8A6WS+0IV%^4(S&G%WqVe)lm5x;PPlm0PtaZMog(wgieT;g#)XjW>QmI17Z=P zw!9SyZl>7iS&U4nhGPT!OEACP`-3= zrbuU>T}u(nRI-NkOtCh8qAsm|tqv(eF?P#c8fMuqOY`q3DfT@Y1e5&bha0QYb9$l{ zY)6HbP?I8M<+fP<| zQy(u%aYKf!A}z4^p!;JsGjc}nmB||sw6Z@epmYGqHuEa z8ISyO)LVugLRli)k9v#IJtzxw1Mnrk+If>1<3{|ak6OmrcuZwpiZB3JKD1YwOFUydRx>}5!F$r-+VjTqX4YvH{KTYa78T^UaOoFE94b+ zGyl-k`{FaAPL!o)wN!Lg8&dUaZi~8CkCxTQj-F0%-n3qt`?}~^=}V2P(=WG{r7Q*Z z^coD)+!yO0!JJlKf2-={YbK&D2^D1=xApZ(U#*AL%Z4VR&Iu)D9OHG`T_2|)dMAmr zF%w-xt*0jhloA^+L=ov+{zfY2O5^?4>2RVnF z!&U?ZTMVgtYHr;qqLNkT^%@xQXn*#n8(Ctvl*tO@9T4S)lMUROpV?;1u#gbdB30!s z(DoheJxylUWHPl8@z(Jo3RIG3E8!(g$HLemYDUqA$)ja3{0&}*8`t`d9vH*jbjXgX zb_)%J>9^f8Cce}`EQ)Y-q5nrlBpEIhOJ5)uG|p&8R_ zgK0tVH=ctsR`5&s`;&-@mtFD)QBFJQQSQMTGj><9LyDIM($%Wr2%pzJE&SBcvW+}V zoKDotLOR^0?5$5|VCRY@s_$&S3}36-xzDtEfN?jt)7YdoxtS=Z>$q7uk%z+ROq9Gy zNDE?J?+PhypK7@l(z!5P2A4sO-c47lgIoH<`&^IKGy((Rr?HXz; z>7`jsYUx69cwo>aV9qOnM@_UK6fS$Rx=AB zV{Pg=wBB&d)A5|4tZxy@Wpn4Os_nTyRxW29!lp<5v6Pq|+jf8N+1u&-=ZABLdCF@v zNa{`fL8F9#bivYqVB@E-^V9oXLMx1ZYLHah{R$41Z{!#a;m16!;PS`M2>fnm@cVe~ z8>82PdFojxhA=-F0y{&ea-*>8ll2Nj%&@3nt?w+F%P?tSC=T=KTlJL4NgI>Ds1*@DoM7u-f!wNbMJ;=9GM|whBnj zW>0->dK!fCj}F9n@3^}@GvGx?%^>}oF1wws#a`uv^e%-8YSXjSz6Gu?`{dTKvIEMa zAVmc0ydoGgC7L%aOn;lZ`G3|LPJ;EzNPH>C}GEmN!XS{2)8DpPfyaB*Hv%8l6BAB$vAa2{wm+egE_jzT|a+S zoOULBb()UKRn3FdcVL@SvLT}mKSDGDnC!`!)pZ-|$GkHojO}Q3X;o=hN^Lr#APYBb z0;k_ZHgw;^KTJu~F z%v`ss)XY7iH?zJ1P!=soW*Z4?SDGSg*cVcjc(rY23GkMRl9JzBEUl@XZ|q?Fv22s` z*Ms6m^q9x}IF=W5^44ZAngmmf>g&W`M9FJuch>x1_GFiQd|@-pjN;LCqE=b8oy@zZ z3|stHYHWD4ifGy*^Hc9|v$Aps{E$vw-t0wDLkcugw>INEbuyx_D8VKYf#z_TK2WiX z`LlK278e7z>DMN&&r_ng_gP#P8)E@sGZVO$`h}Sr?6j+h4f@Q6vb!a-XLXcTHC8%T z#-^2tW(F}lDSc4tXf&Hi+0Pqt=d&cyRdq2-w6M!qe!xDFm_v~nIQy* z(4Hg`ucrJT(W3sF>m9HXYzV2RPQeK=q+jP(CTnl8(}EQUcXU5%`sPX>F?FI;$JhNw z^r^h>w8J^0YQ)ZpyG=^j`ioJ02|}m`P2`YiUY+lsTr#Q|tM7bkPPI^V467MpTFAVM zRN*Ae1axjpZmoC(5sC4JrcJ4tcVJp=!>jByfw%uX!QiZyKX0yUnYlYxX9E$nscvN!v_v7-z`G6}}~ zXUQ2Ku;6$^7`#a_EV3QzYons@BT8}7()RUL->NUIdGCVsn#^n+=)F0!Ch$9lqonJ5 z=S)sG@QtTU+J5%fBd-i5pMB9iXTlnZXq#QnJ}6^z3wqqse&y6fUYmumk&67|sVyB- zHIj=rJ5KX1Ofro>)o^9AEbjzXv@Y>}myEt5{6cBDYEXNDU8|<=5vb%|_|*f3()*gtK8h6AJs=?#aiDLMyD2-OujL8w6wsUMyIA>4Sy<+ErvrX z2U4sw;$KqRxN~2_eCD|yR(7ShX;jD*#WCNlr!*L;&`h{H9u8keKOSpqO%a0_7GOV% zzJwXioUu`vo--NKR(;X!6Y_0X)damac%{XZvHCnPT)p;INH+aLsD=02OkMtDQOC1{a#mN2Z;{Ek#VQhES@%IN72fw@! zm9{z4uy>3)d#Ux!k;|hiV^WsaLmKD~ekU|XmI;&>&mF0NW6Jop2tvV5$%)4XBHcc9 z6Ma#FJ-oJOFDq;Wwm-^JGV;y4?aS-TY%eTc`a)BY{;ZOwCpF0a;O@64;-R0h$<%Rl zo?nxQ{Z_#EO~)$@Ci}-r@R4O(YdRKRj`(G&b&4H=?cSw(xuL;8V@Yi2Wpv4_JJjxA zk=KnSvI!9`!Fwa?;|^SiI?y_}a@|NO~jTQQU{EaOul8PL0>9rN*M#9gqgl zkCS2Q(vQRHR#1D1iIs0HR-HRVC}*HSBAT~Sk@*4E-MbL&y;%4kEz}$I-j_zU!c!4@ zKDw9|^1pmnl#W}Q89A(?`WJ2T4Yf`3gGr6Jr2pFBN5`Wt*UAVnih4q7t%Jo6Du1@= zOJnwmY8*GX_w!2xLgTL^mQAOI-aaTUpSE>)I2h?(?2%Kc=Xd5|KxdV!gM(35|LP@` z*~6k!y9eLjKgK=opr|LdoVM+>vxlK!`MTe&eUBTASNJek!M#-^;0Y_X!C*nOUBba0>0!5aN*Y@7r>4{(ydPC(98aH1 zv?e!`)}Cy{&~T~psl8oEy!;@m_kZwA&GCUM># z*?m?^Qbzpx${|-=`|XX@ya#_b@;c2eDp%PKIG3GSE+4!ln`AEG6xPlWZK@1vP^P(m z{AC4LN(%*#m?xzqZgw=2QX`-3kh5pSL3Y?9-3)7X*dcWsBZrOcy zD|<0O9X@>;BHKthIujg;d7btrzL_-9sgsQ-%xamQgO_{c^_V9ycb@@XS%qbn3{zLA zAT^Ub$Jbxs2}cw@a^7K(QOj@cQ6r1uHgt>+gk#b+lOkN|_W`eBZsE!G09yCbV~`}q zi~fYByiHyE!3q=FV~=#+*DU-Xqzatwe8Q5gc^xJU%k8k<#pRnJ6!v+-?y{IO)$SF%FU#j2FCsK@bb^Y;kFIMKL;@? zHz>{J>+CkjxgwF>q89-DUYTE*&=+6d4zAX?M)8tx@|z`RoWgRV>Nz`P;KZ_n^uZRz ztGM=`gMcGL$OLy4=hE^|{##6%rKu`GEg>B9 z=!|>#)#o#nx-S8hnh*;=cy%<(0x)>55Sd@oQw(^PuUPK>ug!SiiOSm@@ zqv>Riq#yd1a}>&$X+Nh*dVJwo@F6HY(f=%9J5Q#zd4`In>);98@pAK7IO~!MeA>C$ z=uW24w-0W)J=<1y0S_Vd)AI>VVPxyaedV;1Ztr?9t~n>q+99PwEA5aiz%_HyTC7aK z5l*@zO|Q9jAx5Hx_INzXwUZVWXxmFOzqSl^=XlsU0nOSR0E!DcA_GuUe51qmGc)YI zQ8VdN%g_)|<*s%|aeL(Xliw6>b7X|GfakcHW!^{{>NJE)_Xz9X1B8)hgyr(pljD@L z(y(qpuP(sjeGmK zqW3#<8!O-kjvs`avqx&#wiyFsc%jNS_6;Eg&5J>YS--s2u9xv;WNLLqL}Kn)Use+uzdws*EB;o>asv+($f zGRpAymGTGKuMR$blGnRUDm**i+@dK5_YPAQS$JO^E`Bs?e7=dK5@*^(QoXs9U+o!M zTJd0xw3l=(zxVm{^O&7hxI6jHB%DoB#KPbApF#7Dn~s_vu#CiY|W-E@w0 z+Nm-RPe@(4lmi6(`nv2W^r52y-}sP*eXTq2sO}5i0Q1e7TRoVctlXPsa1VS@4`%V~ zK!MFO-q)g%oehtAO4!ixPng1^&~U5W=8>4I`Z92PWQ^v&PB@oEhth4PcvX0Q|8bdv z{Z3}~$XvT!RY#%wW+LQO33db_vcA*7;qmaNxOSb9m-%=C@|7`&cO@FRHn{y=CZ;&t zI4gHofr+S6mbp}aDcFC)PRjsO=yDBRz3ht`Isf3bIuRynsr49K4=q%O{=!jD|;_x?+9u@Stk+ji9xuJbEqQe<3dg5>k z98X}6Q*Kl|KXO^!$g^wMSv-)|@G?Nf7`Hd)Dp5pVH%E9<#A~C>N)NH}6xi>+Ph;Tq z?uoNG641aEW8WY8Tav)h+9p@M!^j*v2R;(pfX>pF!ND$DnKzM+_QOo^gs??&9&pM> zr{t{%BYy?DpUsX(=16Yau(nKFU6s(gO(b1-iy5BqBCkpw-miiJH{T?a2?fBK()h!a zNO(((1kPd9PfQISuknfw*6seX$q(2KE~;SuhI%&^_<6VbyO9`Vp)C$z&u|{x0PS0T z5nfgE;4;9m#@NHpQ0D>XTn%Qsk>8%=fa%qj$E_{AxJ`tLV!gk z)QFoX4GmxXda9T?*DM8N+K%9N!c9e+TczIzsQBv39EFmF%N6qGzs~LpIm5KY=@d@R ze>K-KoYjuDZ-^VhCP1f=j7b2Bm#@A* zu&8gjdJETX?|MBAoOH5F9_~AN76Dv}RT0P;BNJxN#bdv#Wd|Ivr;z30@M5Q2AgS~< zRx>GR(yHr+|FKJV|AgukPvE4W;X4D(HSvTuZ~wK{lRR%a7=g(QQ#_VzZt=Bzp z=L2cKMpt%f+lZ(DZvL30>jiNBPg}S!jLdFs3ZCF? zOU%D|3g@pCans!128gA$=af{^5~j)Vww`3m)bd}}QnDvfypb}_2FW0IB(8!CakqLF z$o~u9DkcZ0ES-h80?Tf`cN^FKh+S$;RCT%24HAJbOZl=9VJHx!_-|6R#0KO5uCE)1d3(h}4K$J21lI)GtQT_Kca1=!(pyWNK zi9q;2AqL=S)X-Wz=mj1F)d#>qh$gML=`I;0$PzAFsjHEmfLJ|n*Ta*aQVU<=}`O|P2irdeSx~+6!fku z<_b?fKMZK>Z6Ri&&ELA;1gLmcnZ^|^e6?4yw)pa*t^Wwo<5PpV#q{3hepBaH)^{!I zn*+zQ2Kwa01HA#}_~Sn|@9a}ZZKEi`-@F(-ZEf-O-Uo1iKX;Db#zmwImw%My)SLss zGOP=@gUeqxkiP(>Wl%khIWZ3qwo^R|VCI?UfO!&z7aNm?)fjtOBpb222%s`ZT;ZP> z;7LJ+4)u!D{5Ll}y`~uWvdM;7;MTMr{s|r4y7aw<5cy|BvRQeFqmzx)pIaIj_VoQ| zJi$l%O4niFHFg0T*J>|CW$zS<^9L}FX3CEOXeF|jjD>>ncJv-imuZ`t z<1)*aH*S>1`6HztmsOjsUMPPyJO35U%fY9t)vXSp%VkcRPWPgkV58<1vjcWnpkkJhZuS9K^xHpoiLqR4 ze?=26t{1Q74YHGA=*GXV4!TL}y`@d2rhp68IJ|rPUs-&j&I0fcGoflZiTk^D>OC31 zSZ=#~Nl48@-!Y+Z;SD=p_QH3GuASf&M7=Fz@h|Q*aveh?*2rbV4DkHY{ z7cgA$nc4pq;vDA={r9ica@SU9&@DakGTPNXE(-mKp(1j z2hPZ>*)rCqkaf?m2_#w~Y9Y0=Ig$UAOJKx4mRBd_>!}lqrZK1V^ADHl%+Nr*U9Twy z38f4)mxw2nf?gc+Xv;s*{utQD3A`CC;C(F6tq{Y+8rRNn6@$`SZK^?9mAnCTjqkn# z4x=P)jl->0{SE5VD@95mo1Xqqh|{f{D5v88{x=+x*(q^f`#AriJu>9kKmmv$8jf@c zX#Upmx0um`TPQq1B=oHJ9O>l5HzoM=KyVZ3kg$~c!SR1&zUt|AlN^T+iQmmLwVr|5qsZ*`yQ1I@@PVtpXm?1M~&DG;zTRH3bbBS z_3tH{_2ch-l!iV$v!8#l?aIaRd!mM+SMPz-*xC(cLia7y0WZ^NM{vWrq^YcE1A|v6 zoded;bn`Xf>${LMk_pwhDE2Fexr2h+%HvZIFenTCA!YcR%HnVg-X<>`;}QJznOU4C zafbne{%8AiaOnNj3rnehwOh{pW65UC8CHN& zy&Zo5PmmTL+K*QaWy(+5AG;N6YO`6Y2eUK8@-sBQ(ktrU^z_6A z$xC_+ZC7LiXrTFBIC@F@>HK(V+SxC}^L z@rQz~KyoLh1H!aWzBdpt5l?i^5w>qWhytIJE#Rq6x>_j6i8tE4=QOtLEM4kWU%vkl zxA(P{0Zzfb+5IyV^)|HI$m~sSX3PV}=|>_E}sXTRtxn;N-KAR{#W%sk+_W_$&_fo_BF|X zND$&&J^)$kTW}p($a7p+@W-bH!3{5fD)dP*c>R(BNXo#7p;n+WoB>D1oSv#btI44hB zja&MlY{yTL>p0vR$mlYrdmr`PmHxPzW9GVBJI&nU$}6qBfnB~SGR&UZiLrZS`j4!; zKyZ{6mlp-;%D6npOSE$D^yx#MZoV(Xt@eVR7QQtIG}2_NegL|6>K6d$&JM`j&ON1Y zSEiZN(|PSW$h3F5f#|=MSRe!TYy7G|519;uBS~)`>IMoIei{vWVVU2)*QhSN0mt_v ze1Bi)Vh|5&B&jZgzDPe_96JsaX8H^$jD-K-jkJ2F3bLS$af(G=>}#7}RxohO*}F{P z8(bm-K@!9^TVzmRuJPhpQS<2Q9(M6Pbk|s#SQp05vZoMjs%iQjZ6F+8vRBYV)H0IGUU6B7I z+NT){nd3j8oNNZ)jP_+uV?5$=a{ZA9Zj6JvZff>CcK&PPYNK`}X7CSD)q7uFizH>? z2^Y?1>eNne!-Jk0*$So)%2M%9#>yM-YQ3{5e+24YHUh!%_ z{W50V>-=_mxn)`pX0G!?F+nav*P^ge0j@pGc(|vP`Y3pL{p#dCg@3rgz6*oy= z6X5it1^0=nvf28X(8*PbTAtt0hR-0>bjX1o_rYh4{SikmMxBX}Qh&8q3`9GZmR$%y z{`lQ}oXaG}m_a(-jAGa!FPeCOPIvnt;P);!^BlZijC2c6c-}H}4z7W>^?ZlfsSkR% zKDdi1Js2OC{c3S`ULQCep9}UMDOG#Aq4t=P1#l>>+S_L=`O6A@e;C~cO&ME8E70)A z3<=O06{>#O>3w5~MaktsAryk4`&##P25Ea%QntC&mFc>>5qzbPueHep(py=4;6x=iA%q>PP?shr4 z{G2xj5Hl5R4k$XH>EPakJA1(yt~~z&Ol|a8 zpp1Nj;d5GzxzsnN)`RLdK6bx=woni1#^q^X#bJ#X;M0E|SV}Qq*x;MpL96;m<{eYVjp=kwfOHM=eF{AXK0H~83rFNvTX zPdjKvBrJZ_kpczeh!rkEXb)ahDLM(Xjy_4Jx+j~x>2*nn86Cf+XZLHkS^YzmARXc7 zC^aY|TNbfiOIzaX&f=`T3vl zo5JxiuX0Mo737?^>z=DFkNB}8@x>RU!?uKM$rIGiQ0UYo`8rYL=FTb51;EVji;sDy zepGjwe0>4KzB&Wea?V>D9wOa8^9t$Bv~3K`1{u@8tExSJBVLG*TelY)ui*eQiH$1= z!(`>FJ1fc8BOm2>^r;erJU^?A{u;7|1VQ`cPfz};Ln7)yR#_@`t$6U@%!^AFt;o+p zsz?C?)TkuUh##L*_g2Km6qpR;=~ICZo`{Zc5hC85`=Z+OZCpMCS5~t7ICx1(4 zV}@@XsC7TTMATiy2WcNwlp9_y=FwGS@1!560{_{!64O&dxN`pTFDgT);vi633pJ&Z zTe)-p#yhbM4cZ(9^!&R~_-!rK#|wLf>!PCReEQ;aCMZGIQjt8ZqL6 z=-Vg(dG;vnoe4-V-!2|ufJV@jyMwB#W>t4D^{B??uZZ2#lN9YyP?qZu`t&wH>Z$C( zpJ_qA3VkYQXgF;(sTbiG^ZEYBfeAmUB$$8QL=WcC6oPi`u?KHz zBObKeype}=xF&~FwJ@Z(1OzQLlAaw}1#<6wFjN}xV=^K`b&mAx59d12?|QP^v@Q%| z`r;!CcnFbXr{V|&@9M=$FB_uj&3#JXH^nd4TtVLsvI9@xjVl*giHaN~gZ9%cMn^%q zAVTBG*%sB<18?8#q5*X1DC;$oUSu~n{sNKwxpvT1II-eilNWlhJ`PVP`~I`(0$ltM z2mI_vvwv$oczoyeI?%ln{S*Y!zslx>FB{du^!t4w*A{%FEab-xweUz#E{cUAAC%dS z%VmNt=9fv;*eK#k%Z+Qd%ifc(Ydhr~>#Xoi!>)vDGTSr$4^LknNLAPU|2C*pWQfce zQ!YZ8mC6tiQLd|yF^S5QDJAikXAvbbl<9`6NN6z2R3uT6DWz0~6eZ8^vwOeq@1Nt` zeb!!k?X~yWXU#IUx9L4NS=e`6H!RwXfj2cTV(dE2BJ032M~B}7x_SY;&X2{+zA2cV zUc>%^G{xkO^~w)Wx!$t(1b1x;$jzm!J5pI5UChn;(b�TdF~e?B$Oez|7;DaZJJ{PQDGx5L*tN@4TcHulGKhuJ=W?la_{9F2SC>3%mu5>$jDpBzQ&kSUT`-o9hT$ z%_!^CFU(q~Ju+JweWcg8(VV_k4!hs$ifnlSz_ai7dtc%Oxn z=iv!GX(v#ldU_8})oFNk4_aC1R@h9Y2EJ}+4aiyz(-Vcq`>dT~OuX+PUSAhu1yfl* zMkDNNJI3BXv1sP6!CPg-)!U{wd(7=DjJEF&{Mm6eA<}A^UKWw;7d-!Ykd+Ecfj!G_l5cE5stm}Fk<-pi_Jgo= z@wmbwoiDr%vtGTWQwf^eONOkN0d0r;Ktn4}#92sZ`n;#KYUz8KcKevjs6-O#u1U+xWrQ_9Uqfw$0jOY4F5t;ejETwcXYg0%u~JtXO$qV`Quh z#E^5nG+jIX0Qtt&nc#1^7k|`fOWwHPED&7KNxv5nLw6c{viM>P^~XoG{{BrmW^FB< zkJ8)UB#Pf5M$0I{ZC_JxFs(J1#Zk5)MT@vUSOWCeDjhXhG=A=}c4F6W>&ev}EevCRGau!y54{@e13T1cbhw3?B{F|x1 zygJg$QDvhyZ-4jQX$uLL?^|?BV1ypif6E}Qac&XJekMlwQ+A3lEu})=+*@m~Oy9g| zA_CmK8QJIP;OMMu%C}vNVSe%J&Jt<6LJ!zagDTx%)9sXp8$J3$SxQ2yKtWrlLSpfH z=0!{*X6KY2CuMdLB6*+l;+#UF5qp0VRk4-J#Ra?Rjoi8i7^c*z*TqY9_Zn!G1tLjY z+Q*vWwg)XF)z6H;axF0ZDB7!MJjcY$f^VB6`Tp>lv{GMwO>g>y!(33wdh)tQ*CN6^ z{Nh~gU(_fF2$sW9az&o;xV)&DH_&}zW5G{tZ1{h|6)#@*m$Nfh{k+ksR)N3&;wC+h z$ME&G(Tg*}y#!(Tv6f{e4BE*_YY%>qlosrRVIx#${Mgm6T%YACWCtjc zAyrN1r*8L^D7ae6RV_x;pMmh#(_+sHb8jCB2-(Y5>?oe{OkWDBW4q2-xL|ttop^cM zjEVPEkt1C?CreEH_~n8XEK6!oO{we7z(`pnsWj30X@%HCtI8v=HTW#Ft8(qp2Sn-$ zpu(;19)PpfFywGD*7XCM`7WN-9K|q{Kj=M)P40UkvAErH#BjD%s)Pw10TP|!ed^J} z=$)OB#y>V8Q?CJwc%>#G;g*!(#5XKcDSJMQ>f!!v=re>|R?b;z(#EP`7~@8D)n~T23PXg!%j$8L?T(XNcP>J0fJc zT!P2vEqipb%+L4V99Cb`+Yxg$0qi)(gC1@51@4QWQ@^l$L8kdwf62l% zKRi0#JlQTwRa$Unr(ECZeUZ1n>*VOI{Wx+~9dFayH9J2a$WWlO^f$H&P1fpU@n6n< zXelEw<-AReZB$sGARGI+O2QBd1Ba$>kw?c zX)??X4iB`RefBl`%2qUrJ^f&sL9HrV-R1JIHGEz@O_OQ&JeaFJcCTo)ea`Lhww6|b z4buG>oKLhJWW&-06ZdkDSrD)OY3Aqc=PZ=t@BkJUzC~yRbsR?ZB%~;`&eUc=I}&;^ zT}>lC?GBi2o2v{UwKT)9=_?5OqF<_1!)s#lt_E*YZ55T(>L@v@t0ZM_T2mx`*imBq;V zj>-}B8blQ!`bXbfNyS*wsz2wA-G^xsO{K&Tc7E(HXL@$rQJmTov4c?-9Or_M>V8Lv zGQs?evL=&9G>dHgb!{yp)zRJ0 zC9f6zzp^6Yq-?Q%+ok53RuO8&uFJorSe3?9e#5N?nF^YpOC_(8zVg zh8#R)+Gqw#7ghe&`AUQPduuyHsNT=#vmA4?1p3x|K?suIs@t##a#nv6v~Ha5@$@Ca zyHpQr2jzOpC02V!UGt|OrHr)A<)Jp}E`%`@9*fHEOgsbQ2~35ndWARRYc-wj7oI%q zyFpC5Hz>qAq#mYIYWC))R@d}xy!}C2M6RmkQmPr6ycAE)pF=Q^xzS!h0t-K%Db$_p z7otFjd?aJ%nEqX3XGy!Q+7gU+A^L>?O#TaVm+z11 zoBt7dmKFvz-TRTxxUtB{>8_fx6-<&qrfBV-eM(EN))yR7UY`OJc7>Y)gIb_A! zbiUEXee+l6d}xNbGlYFkgqkwnlXS!f%ADzqT}?9kyQxZD2xw9hy)34Gx#fHt-opUN zxqxBf-V>GOv2$cz@dC@Ex8YG`qv_kM-#~v!ApsLr%gnwze*b3rcnd-f%?APFVB0A| z4NdC4ny|oWp1s*(_L$J3TFk1Zkhz4HOI(fn_V=1x-&{Z!5^Pb54Vc(Cy|+b5%q|ZO z#Dx$M7+jXT@b-)ngNyNtz8RASB^4=nfj`B(d)lX~H3iNX1c#oJ5wqu4cC8M$0wc*c zhX*IaZm7hG4y;nRiSdnUzHfvjdKF&8A>xwcKf9+p`NjebDnp0uzj>fpMe|}0@eoDA z61MZ=Nqi{A5eW*kWk zR70%E*VgkeGbjFrG4*NK5C2=sr(QwqrIcaOrs-9ph(L?15m17aSojdW*W1JF9FuQD zhMdh4y#8P_oUOBuuz4fQ)u4vtTWVhWG|8y@1!^z9v zjI=GQAvH)PzRx*cuKN*(&q$1Ua&ehOCm%26SS?Zoyd0IKrD68fND18xC5-bo*-x>T zs(K}_t#}-L@16T9gx&hk(ydGSZoo8H zY_6K&<>=Zo*XaHMW|mc9XS8ob5esyVw2T@VM8Up8&#D>=j=>J z^x6gsBf7L*^|lY<+KoH!LKfH>d(Nmaf=90s9>`OMH)y=Z-#v_$X-Ji%(|AjyItyqk zTwHEI4wjqr2J;xRjraa@QA>NMp>@^xjsbWLM0=s&rIvalq^H!h7AHSLx&vAe%Wq-z zlAyFyPER{W`|e+3HIdWqXWi`_+1G6ufYT+)3IUreZw{+>P(}w;jOg@H`33~C*u9HL zK27VG#Oo?|#vR))_(`oEXwSM1*MsoQb9=R{gAB*WO_A;#G1gyG@HgD3jt zz41nn8P!_*(jg}tsv60qjK;PCxs6dfNaBoQLwm!(2~4Lw{uvXOq@5oF;(4vHK~2ca z{Eb|SI@>0&t#&l66Y3=U3Ry`iH@tXEQ+=|vki_dFY0%{cN*n4BVZ&*#+OlU+Jz6Q9 zp%6Gar%#v8E^d!VW`wrk3t1=k6xSxLl%!(U`p^_`|HdZjMC(x<^9M9u?()jqDy{Zn zRT3mQS76YpV}Gq57}?d!RpxBkQ*%8g67^;!o_B@ckSz#fs~B;|A=tTkEVs)$)z6KH zuex_nXxhi^kfb&ZbYn(5rK8n5sN6116u4c%fjOJ8fT=CiGp zj}bHdh7lOVN#Unek0bDCg;S^+4#K{m26(nDLx#Y2-&(jVD4CNGWJ2zy1O1$lZzMOR zdOAoK@8gNG^zme_9#0G+kSgH)KC;7|g0XjPnYBzfvtm{X_H8A49@boabr8K$x*}SdR&9jKC)*fL zagaSVgk#ZSbdBCF9)7AEX8FdCy&A!bONeEkev+;Js(6n1Y$==q{h>G~f2=lt+iCok z<&9!;hsStU!9Od!oxp2;?>KkFW!UzI0fsZB6$6E^cv+f%3_X1|-Cr(r^*jAp)rE}% z2tK;pWi}punG-w2uhU`9<-$IkCed&HqXJEMP!$e@U+M^`baKu7mP_FesAHpCXGi$I zMWy>G=X@t2J2T}gYo9bc;(z^Z-b)3y6BogY{J!ViEFC%H|FPc1^C#Hg=0bY@r*n{e zMkM^VK0{9+9WSrP z$SxX!o%~hd(5X=HvU60Po}XusZBdb>RH_oW%h0JffBhRx+J99BLf-=Q)DJqDZ0ldS2| zqn65u)D_}!{tu;ayoP2`&l&o2ZDnb8{c47}q1-RnMl@w!)hN)pzwe#h$oTQjz}(xW z*$0@%5E0I-8>Y{677q6d?#K~I;ZM;xk65-Xvo#Qu!iMK>F6&DDJPmKbm1w^?n;Kht zp3P&%wEW3n)}4K8U+-tKtii$MXE^GMbP(Ix+_*xPy{pD@XuC7k)xg%neretpk;S}pM&UIk3A+;i2IqJ|JK+lpzBDWJ+Zv%DH^}=r!p4I$#Vy({O=ATU}dMPs_pNnVb;Op=&k`tu!8UXcNN9w9D^jaKZ3Xrggrjhco{bK&n_WYPL#^^LcKCmidx zQ=2AVZhFtU5Mqmkm~@*+D3;FhZ{F1LxL!^Ec*Bg}3M9EGPY#XWqO@%od>X6E(iVlC zQqNF(RM^aW*>yXW+pQ(4r2Di@Xw&g3g?5L9!i97J#JG7{N{)l@^ESB|etj-aqmo&U zSi`khT>1kaeEuvyXoq_G0f*yu>@M0lVaUwD#E@_}RK&4370VChVlyLQ$%cn`QJSd|H~G zMI{Ta=ZD*MMqM+xP@Csd-mmAvzUz(Z_PP$UAv8d$OMJY#fXo;3edehMC=alV<+Zqpx|pbFqK$(?R^GMGk@W_V60IFEf^uu6fm?Y>E_3wK^tp(saNF7NQ|p8I&xM=Y^H|F5EQy};*}IEJ zS$pMPy6b)`3xuJ}kQ@=WaDGJ7{6-GX9^PYQ2K}y3Ct8f~26MjP9EM-ti3|A?HVhXw ziYJc&6GA0J2Sng3K91ZWKbtQ{5t3`?XpNpD6LR7m9L?;lwY2`Kj>;2AHehEfHipGZ zu96vcUq6aLT_MjqCVNL`tsi_n!SdPpQc$fl8g_&y>j;<&l*Q`yO>RdHMrp$S7B#-< zG<-&`_bH1z0O^lNk*L$9ni0r9xaXvwo3ITF6%o-FpB&Y+(+GhTE0qfUzq)NuLX@az z9u5pwS~WL>NmgzaY|ybN9Ip+m`rwejmN2b^Gr>6sws|1Ryxz`HLk%=Uyu2ADuUrrO@UGQL;uG}LcJnoyqfDN5Stl=44SPybQy8Wq=oCY=@X&&9!vD?b zsF>xjO8#6MF$4aNYQYGh`Z_hbCz!ph6tc9=;J2M6bbI!F`JeO~{lL&iHVJ-g6pD(f zQh4%dY)I_Q<(rYi(wYEhrpe{pIYod=EUq0=nkBO5D|>nP0oX7vcEVN19Mw4+9r~5H}Xv1b2 zBdnOE;;yZYfRi({9el|6F&;e+T4-u) zh;|A$4R&KFSZ6l0Zs{%lr{IW0Mb>)6n0>hWt*6G^b&3nVlqr~EEMn7tWki0Pcfe;w zD8f1QQ$(y;GM1zMQv}HggTua8#XlJ#kI=6jAHAx=-S`*HO9BF9-2bM-&d` z3q|vXp6RlBp!NDvHoOkEQ?ikj7uNN$L1`+Tci`oYIBv#AuVBV!M=!pQQM2sX)izuG z_9AkiZ^2ILQuCM_adiLCM0DfoVy`Y*zd~JHQgORjP#g|A=`36&+WYq-QD!J>mp_Zi zlW;YE#o~P(9?;Ov(r)oTy_N(8__87u^r68K!-}{jS=NNY;7#`^Z{O(0gwcHz2;+ju{m8uQE$h3*D# z2lE@M%JAN=lukrinBzsZT#CKb#hx04-GWW{U<sbxay$5t^c1Ee(}nPxL-kyDp}d!P zBRpZl6}|?#cU{1zt{R1m?OZX*OlKl_UP6ynJ&CoxR5uPHd5cDY?y)_SeLIv~-lzq> zhfg;hejw!9M&M<8!*O~Y^4^HNr{*Gfa)egQBYEr45iaDUU}r|@9-RFpPSiO`*eC>C zq)%nWUC_#Al=JvoAtj3gOPG1tQmE#^jy zsDf`+fINo%g}oao)wZYg5K2xgpWFSwer4L!2wm-GjGZGZXRirfJ^!k$R3+63 z^$ zA$(^;rxZkN*UZhx5>0v0kabinwiO;aWOc(?qUWCDFL#2q5_+fL?>TK~WQ{n5jlQw_e0VG%h*9=_lqC6bngBQVa&Af84oXq_+W6vVrW6zC(VIP?z9DOdyBj`wA7g44GK#NAh#NFpwEe-7+ZcT?qY zoCVz)*5Ab=D0DIrLA09#+!Y@-ORB(5py475Q^NDiL^w*$MM5o#O}%XJskSo5U-E&A z5StABX~FdJiY7xNH^IYOp!kn)rXy5P=v5*_6+@aNVz^U}9%yP^uKZjdUo8P)KdvNO zZUsNCYSEp@iS1^IQcN@#+h91c1xYuS{)t2$l1zLYx^-%kxje5_85}7sFReh?Szlj0 zVl3Z)k3jrtNhE!Nj=ha9^xPp^GaXLW$H8$PVPGumClaAf9Qck8iSl~!M4CmzPNPH| zZd{gY*A7iLT)Vv7cfCF)`8M8Y3l21!83||WwEY*a5=)iOb8)!BWs{+mF1ke~OK3Pq zAh`MWCUKUGw0sLA9euAysXAJ=3Ep|4walw53-qF*bk-E)Zx>(1@iZ}`Ej;kX2@TON zM&>(Yc5m9Ks9E zp|!s8N}Y)V{xh+M-WzYdtZ&|(v?0fADdfiG!)6cHDp~8z9grF-slMi%6)CK^z$x19 zpl_@!&&YgjW*lZ5C9!Kj?Q1t(KzaH1dy*5`hMH2L^ zmO^eFEGXK|nN(lUmRUMVt-9ts{i6H5am{zH1sIVxDCsNfNtWsSo>@cF#6_kd)YUmR6i`<$Fz*t|-d_ z=ayYB;x%o*%2{-KUXZM*bQqzF-85G zGuDZ-RZer<$(6kCXK=uOaDKid_XA7R(Zp-c18y2eO?TYkKO6aKhk&>17}~G@}Ns$U8EtRk6aIJS-rryN?ElfQ!c&* zW7~dGCzRchExYD?nnw?#j%0ka=(wlkP(rSTX{hW`H~b&f*3436qu3eA$%VvGGpf*a8WTc0a~6m=)_6XTT>luMr*v`~;l4&bo|;&Yc{hJ@;9Qe?=|lTsk73l~ zq{WE)i{j?Bx9_MvHS^6e^5BYQ_b^??-2D_>P;YexJzr`bUfW~ykTXzHv8stxT-Azc zU|z2vt@qJvbHr-<2WHeAcLbd_jf+q3Zhhlv8pO|<@pKCtO*f!14`D~jL6_b!?rj6l zW`!{E&g*t5nzj!QP}r|BOfr!+UwcqzM;7CSFeZ4wxB0LUygg4d9u6Gufk53eB{B?%u+Tv zXuY~0r9ixUZ~oIv-wkJGBnLOXH2gf2dN|lgA^XbPG2`%bk0j0E{01!Q>is1Lmm0E; zC25MZbaJc_5U6sVY7hFNT()xgYAMGV3AUj%`E8l;-XCNG>zW$C!BCww4-DACb`^Nw z5Lwk`)p44kupNGFen}oh-*I0X@xXmu`@Uk#Z{lo2y(=Fa?^trX_4(9~u%mCW^0Axb z@huzM5|yk<&ug=DjNNe&7ic*OVUF4s^mdV}t$Z4zN=qYqUqw7lx?>!B*Z`k-E*(6w z%{mC(OYq0nR;}RQ^BTyj@l_QtpVjl?f&e5B?PgTs7oSEwbCaLqeVy&lBxx6}!Dz%i z>ICFw%Ls;&Thi2V6(&jQcK^vkrw9@`qHndh|If9VBlPKshD@3s)-990oVBGzx6o@E#L>f#Vpn>6v zDY&0+#I1?ZVT|G3i}DOYyocB+qrCS(>ujtrph(pa_g6uHlGi2Ae^!&e)B8XPEd_&W z^vu8l=!gA9@fIT!MV2!YgPN~UK zxlsZGPs)IRTh8l$Lqt1;as#kI5%?7d3mCG$L$lb^hpHjV$Nkax(HamXQTBAN^n?cTM;t)R35@kkUJo8Tq|@z{UGl!Qo}}T zv(ZU30lZ<~--l`;;ePKxjNfAfK=EAP#84301m=o%24N4d7Y$+DF_@{+KKvcruE3I% zXV?Ox!pbF}v9o)O0j%M86`dIZ7REB$uA#K>w>4;`b7Fd^O&Uq#rJRg{EYy7)5UOEd zG2?9^01PKVZ3`CSztlzr(77m4edPrNV>U9(ekg1^xD+x)Kv(u-u;~M^BPe}`eih<8 zj*NY&OHcK*o-+<$`V!L8@M1F;xr5xgnzPQY*u0cXXT|7uNGn4Jg;7+Tvj9f_gIO`F z8)M*x1*~Vo0^-R-WTFmS)wC7Vg_(2sUW+I-MK0J95mUx=K8+-mNp9rQuZ%(}UNI6G zcSqop&bA4w)zE+Rf0u&);O_4wr~owsk`H6NbbBs}K>!afD#yw(azi23r#S=zNApEs znPZCEUJUVC`a@vNlSJHC$jV3I$&MQ*us5R{?%`JaHm2-p3RPm3-4uyP|K=f1*Mn^T z6oyA-c=B{9(4;KTP(;Qg3;SBZ+X+jWrmRCE+!n!yCSGBJ!5Wv*ZB@u|IMRX26JMQ< zH@0?;98jnVnejSSm~;p)h!jw&9^<04(HMBBAf$`B8ck}^Xm%GYL6%?Ji6RmuKQYAQHxSaAy-__SZ!!!@(C8ZQvfM)ek4A=SrdnA(K2fSNV3c8ccqzy2c zGEmjV5G5x*aGL}Y;@d^ z0wCZ*2%5p|XcBP&#C{`VidKM>Saz71znLPGSIZLMA5f$!)VUU8lW$#b=`U=6>HqZN z_bQk>I5$|)?HmP}+|fNJv?vk@H@u+m#^Gi7cD=fT-<_La4*Sdh8~2f9*GXRA*gfP4 z>U^N9fggz2FN@kQYG?WJJLqU~F?|+CZtuc#T>K)qDW7SX7I=J09Q@nA*OH6!Io}ms zZ`_Rsyv{ldEml+bhi_xuX34;POnP`;qm882)Y~9(VSYQc*W?Yhjhg9w{FW!Lidvo_ zLQcGeu}n8Me6e$Ud$b1hTse)MP-}3H)<1**G1sYXF{+Yp$3_Z&&9BI0cjZYbs#0lm zeq=I>>tn3SDoK1xSA8&p-d7`l#vU;+H)xj{ijC~KgO~EW8;(VOni3XimA5A*xi<-mjQ8f^T~0T0e;+FuMjf0Q)UG6kbK(@UIf-uIoKW$1Q=912*kN_gtpd z-*zWpygGPhBNm5ehnAkh%BXbuG&m4ggXjURDYQ<{zeDR+AApU>zQk=^C|XVSBdB>x z%8s2dMl)xjLH^YX()m6*bH@EkfT_J`Si22_X!jAsQVZ8;y!Zb(J3J#-NlyB z>fUx1P=-YjaH|FpDl-TZ#$t}bPkNqAh#PV92M4j2x12>7S<*8mVo-2912^nOAJi-e zI#!Bwh2c;$16ZpnZQW3aLPqRjp4GdEcTZ1P50q}RgIE3xzG}Bz!X^FpcDGXuYZcKg z>;sB~w5{3og4X}*obNXnZ;yu=7$+79TbzOUJw~|^x`yeMlrbq1a((O_bD&jfx1M6;w-+?YB(+35CR9kTMID+S?_NUQ7CmoMU6;Dur{qtGOqNxa_ zzn<*+ah*|CYOCB#eQ!)V{=9IJx$$=gX01{)Vz$)a?v|`6a>xb#x#ldC0$ZmcaMNso zbMvdhUdi1Khzxoc@y+Tgdxjj?x_yXpX6c^om!mFFVf;=)Hn7TooIl-(RII5Z!3eFK zV*96e%s7AlNuX2D(o|%*qw7Zn^q}hXMP_XJsz%gD`I9~Gjngwe&PaA@tOwu9?}-HNvwI!7STHQXGb1VB&=b1I ztm?#1^q4T*?ZX}YnXA@PLvuVJ3r>*Vcfr7s2GIf~XgB_EU~jlUnosZp%83gWyZI>; z^$b{_HX~`|Ww^jeT~od-a38bX^{bj$aR}8^-&{sEq8FlQ+SU-ir(?t8;uaW*?igz% zWP`7|V`&JKRmlF_gD_{o4HpL>Z!)<4|FzHkKQ7ADis+9aT{q6iDKS19Df7%q4NR;O z6a9!=Gf&*wv*xG|*c@T^%HxmbeT*b|-h|%>61Hs)bqAh4dBJxN7n#*vytW6{W%v!i z*rN2!dMRX=S`}FQ;3g~rz5PCT=BoE|Mp9!F!1irBg4>O)q?P04*Z0OP9o2y47yurh zP6R1euHJNbDWuwO!;IvWQ$L{T-#vg^jiT?k^#~P0B!JSJ;6>&g7Q0$9r%sZYt?&s! zb6-*+%m|?aAWKEg{|k19&&cNbhny2E2W=az-+m9n~1zY+jmzSA)z~>$gIw^tXcT`ZUSuzFz8u zq70s4Xn4|xpz`UyNLkd6xqZQ+b!$aG*Cl6QhT@dtL{Dx4~?YnU4jrK;r6%hou z=p_`x(v7#EU>cg9gND|RM2hi4+h0NzOnidUX?NFDL6cb`l^?Q5B?r~^eTei8^D4vb zq+J)l#xtvEyvid$uc4h4mF&kV4h7NZReH#WMs_ zHUdrahCF!L7^Hwi5EDk2RzmYtFF9&h)@8+^|l*U=B zi3)oZox1c;u*r^$LgadZ+wP#aKJpKUzwj@Bn#T=wPHxmH^dMPN*G4u}v=dcx^RA>jfFDH`H-_jM!hW$4|bu%oAN@nUrMm&=> zD;{r0A+DCgELG@O35nkA(=ocV@RzSZf6fs>@ivqUD3>Jsah-r3)Ip;)5$FvMA``v+ zGk~JnG2|Yzvmjo61%Wq5<`K6FQO1ZXqG^^r6bfeJMRbsU2k~jyx_5};d?M_I2Fqr0 ztB?)YcXp@z0dHIk(Qi8KJN*RN(IiKCjjVEb3_kmKSXM>|1O4fNPCWgGonhKh*M>^4*^BU zLq|ie4n_3_>k6S*u7oIAQASW=0qz`vd~3b#jw%J3=ZDh<2_3 zJsK5uXl)n7q&-(|Kt83!pb|m>N)W@vtYZdPTc1#bCd+lnqqX-rCKICi8x4KU&}VN~ zW5^M_5z^DBe3(+Y)falFap1~q-C2oq}rb^C9|wsH+Jr+N2RkW~l< zA33^n!9jZpG5|ETI$#p9s))4leYzDNA15f9W3^-ympqKZ-U`&wjm2n~W+tsKe}c{$ zgNS5DS7xB{)o#FV+5&DBlpMg}G;=j{=+MJ{Y5Gxu9>gY-Vsf3(nF%f_^a^86(Ki&q z%khsWs~4Tt1!6{bk>B%1^ym+#F=G2M1o}4>A4Gq1OIRlqZZiR)uKs5XmO70^PFukY z4{V<WGkR;7Opg1q{D?sI2U^D$gtaZGO`w1EPhES%ZC7>!7JAH?{Kn6ep zBhXr>E|*H?m^bU7zYfE14c;p*K4;jOJ0GP?m=%Iws?lzHh}cd@_5oiXL2LO1;%aQ z48D#Yr5OZ5dV2;`a8lMc6g3oJI2csG%ewppU{j~B1J;v{&eJ$anpR|z=R8<$KJGMZ zizZkSdE;V1?_b7YJ7DG9JL)&Wv04wt2~xPwVSgVeRm+?N*4L;!@|hN~8^4t_P-x+X zm@t%d3+$p^2CF?(<0G~pH+IeoBig?!NAtoZl=oKEWkWYx@K|j#vWO~o%@H(1O87l~ zArHD{XbMUx*mQdmW&iKM?{f$SziGgw2cX%`!(y+KN6cj_}iflOcG=23!tr!Q*5FV0V++151I)vH!ccDQTlET9~S&;z*QxBUf}LMbuVN z{lUSY(-PQ8#?Q!TMaJ0k#_gDr#)gv!pioXv#pd*t>iNIPM@!0Kw?zC(0rl~uYRXg9 z^B}i21}ZbzSV|wKFnZh*X>eB)a>fM8-34)P5HR)jO2kG+hIQ2JL)JNC@T0I4^28R@;=SX=eU6D)_5L* z_xw~P61}!Ir`C)YLolMTnIQyKfVl}mxaYdQqmAM=9uef+ouu{`RXA=3e$G(L` zrIM<V>Ma7dVqTvmZH^6_or*7y@}wj@Xw?mI;Y}-Y?OAWfD{(>Kj3e==Rh6J$ z*K{Dd+}Yl_`PFy#MI)=ntR#B;ZGQAg-h&T0Wsx5{qTBx(?9JX5j#)^LgohJeqnZH1 zXQ)qSBzqx>-L4Wk&6*!x+rVG{CkO%B)AbOE1RRGJ1>ktKlO-0vS|YIgvDwQYa#0W`M9pW z?ne|SNn!sN$wf;>X1W2#@c%u!O}6LAidjw&ZFOm6+*rLCmB2?jVe$qIMStsj%YqYk~!;0dfV2C8*XMO zoDKDZcpxiD^}W?|mye;k!fFTq&q6mHdSo9UhBs5qMyd z=;*LCHor*fnG<_TRII&G2gNhsA~x?}L`)SnFrs1wYl|FrVv7>f(tRdPWH@+{a>3aA z#&EZd-g0WqTvJS5&CH40ixFyPVz3`S=1-Bga(;0qXmb_1zb!EP>Aq2=_r?N7Mt6); zIp3t8k;^bs%HucuBiA(U6)d0r7A@uP`L4fUX_|BPtg6+Pyqa)E?wpYTS}wZX@CtS} z>nEKWUWP(agQ0VSyYB5X#zvxxcn{# zw9-$4WKZ_+d4d&kVSigvlq!S+MfIEd;9D#|atv=t;b#k6a|f$9USUp?|S0uK<2uD$KE^%}aP4MLb>uFOhsTLd6Nf zlQ6LQ8SVf=p}Vh9rex1+)ExHP9SR?&_!Iy>9FBuZeG0XOrEScfAY;e34eDh0Ivj(S z?wv<1#h&+myk@-9jjo9G=yq(_G_2 zlqBQXhVR6(7t*CjS5??8+R>czMNPBmN%uNI7a7w8fFik(|C;($!%fmW^@_4 z8;J{uvv}fPMaIw{-a-u}=i4GP^CIY!Q-ZzN?LKkQ)==RnI7yBG|VSaX5*9Pjj|%?kUF#)%XJFrq~rpVioKnr`(V^I15sI}>QS zMw`Pnq0U+Z5{S39tSN!xlGur*J^Ez+>pzVWkd8{$A&v?i>HAnV(Q`Vy7^Fda64TSS zS0iYVD8b8W!UHp-?cSegE?C!x35#wC!}^ei7W9vguvfYRF^PQjkKnSq$~L%7{oxy3 zQvwWniM=?&M@~bhuw(8c7)E;uhH~$t;5DmZW2>7${r`1KQ8@-BPwy-_(@M+d0mjh` zA+~S3KT%!7)`dbJm88+v|L%_i8{F3-$qR|*xVYnI*J28Gq=b=aM6#{elHT9_ zn;wN)CLHIg__4l9@2qwA>dvR4Y~Qze$17gU&!KB^lo%u3`rd#&UZqF>;%Y#XdjNj#gnFS0k?P)1n95&QS97m_lxm?nW?T(D zF0l?4ix;`5O{A=1|Go_f5}tg6$`t29o)%uh)AL8=NY6Pb(vs9iK*V6+;`RK2R5R~- zYu!9ei!ej5W%$5-&@%cRJgjS20^IZ>YJ)jO2m7GA**kRC{fCq)`IAj{)hjrgqeZ?F zuswI7e65!R*yX3gNEE-h@zf@iT84L;OQQ%wF`<+L#y0GgrBe0!YN8{fpF`n z8YcTr^f;6mhQs-Y?=950(MutS`d?eo*Iz$CPTDPYNb~Q#5rwxub@u=|h9&`B#G*R_ zbIgFE@46p$#G!43ich;31ne0sc57KwEV1m;p5$J)1YK%Bo&#OJmSE~yZZEKjN$V{P znU8E`!E*{vDj_E>{{I8g2FihvSTWYlu~_JOa5(@8Z$+LpZjWpN@IT6s;V(;kM~|$p zRB}=sW@*A4;~(N-GD_o!Ns84#@lkQL0~h9+9(OJln0|ghX6gsOWKj*=l4gbt1lWHZ z6)N%~{R_Yh(>JIewiNQE0AI+%?@72rBOTRhsSGz1axH4<0DB^{p8?RW)d3B(`A1R7 zX6?N|!!=75S*H_w%4{&WvGr5~g7N91@?e_Oxh>@U-K`OxY^yv;#GW5}>`_)^{0*Ud zg+HNN{$H%OS^Ft)hD*YpV7f4cW@rCia-yvVmeO5wq;@TfA34P*7r}9}L2ESFy(Fu3 zmaNv-Ol+iwm5)*8spCqJEPf>>;{$&Xe6peEUrz z#Waf?TTb$cDkKF9+%KCzeUsOQ0{G_z9Gxn)TcP@q7tEzk-VRrCb|YH=1CWn|B5Nf+ zElCTQtgUe&`gcu!0HgMiP2YR6uYt7hxPx}vq9}sB(3DQkiUqcMBh+(SYM3|-8q!QK z=lMsNbN*p$ywcI%q}!b?pg8oiid0V#BU70fA{f5ozaE$yt&2>yZT?B#I{$ZQmEXz% zqF{4Tr0<2{SWUMCM{{%dFDQcf95A=3Nky_kQ?&gFolSlS1}-(bC|FevZyv)TP?^*8 zodB*!ws@)89|b8W8OJ79`CQXuL_?}L3k#Z>)T<5Xe~wPjcHc%s+&0|eb(u!%Gi8cL7-OW5K+0$Nk=l1Y6{Cz#k^0;|9Ma}?L%|B!WTEGEqd zrwLrtZs3zT2`U996wV%bQp##6JCRj4v zEhiWp29cdUBy*hZ`uqyR5uV3YT%?)rnif34jk~(vOD!VcvEdnMJO$&Pt4&lIxe5fJ z_{92n$J|?C_fd?^c}5r7ap^u-Df#uP!IIiMAt!woeV=8c5{$De zhJT^8G0yvNj9li!sBW@AcXD;KB>T(Xs_0&8}XiHfc8a;?kEMM&%4tK2~Mn5QB zMV^hbf?;0;1JPhOE(kYo(npLrwnh(VU`SK)+YjTX{E9H*2f;%4ey;^?Kh=$t>owoe zXR-if9klibCQ_G(vr!O`<}w74$UB(VWd2|>PrE{)GQS=E-|yAuqlgNfNvLwO$Nxy$ ziKY85B^f#dAN?~nfp7a0bl_ZxX+0H*fJ^(L4<0#0Vt@_rRnWmZRpXlORZsGk45-K; zYX#!#CxyBj5HzaXQxPK%KQ&Sb{))NKLM2GH56PuGrn`6}o!1@ziUZI7)_N%IdTvXQ zka829yjvWu{MYCAH+1zCyq2F{x!D z5I5w%B7t?W-U56j@&aT@SWp5n3lhaEeZ(1P29?{Fef^g)?{6duzXRXse z(S8~=B>un0GMxMyMgDGaBm;UDt;6+nr8cs~owW*rFgK+uf=JnSuD{f#D#NqY8Hw24 zp-yT9D%>X>%7(|P4^TgRK0>$X-KPfUqWf6dIoGTTfus2gnqgm%KW$y!!%)>4E(78eBQ>|FU#_@&Dl@ zgl0zmca;$%IhVHtpD_{mI`SWQzNFp(XHwXUkpjiB;RtFMbjQ{-V!j#_a#g=9y6L?! zPt}91fg_E(5gpy$CGlWwlaK6EGr32e`o))Tw&1tYbN2}ku7IzJmj4*<(l6$icGmac zYVWPW5h1G%&_nlz5-pjsqG8F9X1JkO@>;Z(o+l0KD=oXbgZmXFsTDcD`VoTgZ4Dw0 zB>s^_NP@yM{2rgMOwpXKz~T!M{WOKuRpu*<4u4}9-e$FdqrcsVtF}%;4bJ0rFcIAG z86iQ)_Tl7zl1yB}O8QPklWS)Tl)XXx2S~!L&2Z+i4k{7wI)g*-pO0H6Xo?&re0Vkp zKBTa#!9vrpBNENFgRj7h)msY4{i&zq-kag3v((ULo2+Tum{v3+>CjV*)Q7NP1TO5Y z!0+5M_^r}#2lO%AU|2A*0Axikq81{#QHnrFK-wG|Nuv^36R!i!k$oVBk}s^c4jI9q z=5pBtfy(nDui%r8X~Af*_hYsMjv&*i-(PZR1YsL1tF{F0%eso`?2bh`hQK?7CiDtI z=Y;_Y|D;bwU_8D*FR@btZiAnvPfL!VL<+!$xGRt0#N zG~83y#{j+`G7qbZ5YX3;i^9t}ORY^;g6jL!|@*;gL|7CVGnYAxxfvxbb{5e%FtP5{Mx))=%2yW)S>EL$N9!#bxY zsshJto`H?_Q!_le8gb`gA+{ZDM2yU4r=^A$&M1@cq--Y==Sz3K#q9F7en)uQrSjMR z!=v%I5&hcxNxzMl-EvWP0JAy3lzXW_0z)u~6LwhLgRW0&{S1I!Ve+h87tKTL-3UIQ zZ$uCB4k&-|97hhoWnE5KcpdLoZxXl{(Cr6CGe0>X;Zxc zXl>Bd!f(68R^Z*k1-uNABsjL$@RMgDVD38Nnb#R?g<{IVjOTuW#PhtBbYdyP?Sc%r z?$qiFr5AQ|3+;{=^6wi?Lvwa00Z_IzFzZ~|M}~HECcOfWW0IqG1pgu#igq0Q7fspd z4~T?pG=xt;d9E`hlVraIyy4CQxRq!605Br1v%eX}T4hv$d8m{F#4RLKIqicRxxJnZ zT^{m}wB4-O|Hc`s4~Ahq59^tLu!FMj{y^YM5CiIv7zd2?R|WUD2Rj2}HjWTr3gYVI zhY7W|A<%D$<|8pSj^DOM?Fb-dO@eZ~g$G^tEyo_?P`VFRGc(r!w2%Ec0Ejlj5i9%C z&hhE=IfcLj`75wvB1p7j2n!QI-tY*pYaDB6{WDxUVHqgiPnXV8=t0+pXBY-G8n7PE zg^5%6I<`3niCAO)jZIS)a?Xwb1Q1wPajZGVH&ioaUiTJgN3`j2@L>^#_`$b9?F1V#*r;`=TAUn~-)<7VX%FTYCWkfGOoe z1=9$l5bPx3$*N>obx6ue&Rcr*ixHzXlD85}gw2mP+Y_NFh>$5K1|Yi*g7V5}6fl%9KN)M3IY( zM>urNDP$<(%1~~mlDWxLp?JUhbbrJ9c|Y$T@4xRq`|M}!wbovH?fpFGS^;aY0~*DDnl{XKe*SOem5 zJ_Pv`Pmzu@t)MQho6_j=^KG~~b1ZCt@X8e_!wjee_=DkU_Ct<^#TFPWBDMc!mg~1! z3J4^eN1R57mao3sir|lbu+i?hU=^(Xc}NbOIl2sHGB)$$U3Y{VXSspMAVvEFxVlc5^dlY#+GB14Xd|O$5f{Hfi#AyZ)~k_`ieU;a3^6RI zwr}AuM}vky)q6P}ZoRIhFu!p~n)LbrOy4@1J4Rofim#-1b;-5)G-w=k&0ts)&!b)1 zA`CQ?#7&2e!+zk&`wN`Od6sQCTA1^nq0pQ#|F|S+FnP;iS`JA#{5&#sNoDHNcOfBK}>QxAgM4uz^SkoF@htYE^ zHZ6_N`LKc&NcK39atl~_^qO^;k1pcz-DUx;ah#`@u1mr!B=(obZBPo)53E9U8;mxg zG!3kf1tF%FVM6j2Vt2IMukqMh|2SF(9#KVG4cM2dgV-+p`Sb?-k#(uV)w*N~2nRl| zg{w8O3r#sMfXkl083gu`LV(iB4q;|L@uB*030VIAjY^o!5@t(BK!FSSFX*cOOj?-~F!5zZRcG%-WQE$W_Q`65-%whr$}#2tJhn6&E=on(QZ(dgBX zn>x&A;CCq41u_OLBXZHj(cul{LpZ#snppqA$=i@*pllRpQ3y6}AuNt-6F@@CFGzI& z8@5z1;Q*;}T$hLnzUW7SD@|~awdLKLtFVtyGVCiHRAr1lZG@9BzbW8L{ln%Lm$@_v zn~f4oysWct5SJ}M>t8Cyu8lvskU!*m@S2%TWW!=@{7ObOB9~{y(UN1en=-}Ez1RX4 zfd><(lw65Kc80~7)xlshYFgALwg;bm2AFuSKWK)?oPll)0VnS333nh(i;xyiB0INq^l29{%1Hk4bFbQE z$*@WO!?EfZDx&v$xhhF3IYsr{#S|Dbp4&8j4m3vjY;@i=Vy~P!GM*ZGd@HH?rfwCT zm7C(XjWmx`W{m3DkBRxnArSfaR`?NDSl?1MxcCuq%fW}5dwc@fA+WtqB=sAXgJ+F& zBED{T3wt59$2IPAIJP$P_K>-rsNe4U_R1u_8yFVJA@I6vO)7M08#^XupH4}|(B|P= zL7XpCdC|=KAi!alk@Ree9=q=^n!TkW%iiMof4pB*g}=bdx_@QzW~^Xr z<^%1Dg=$ZcIwo8T=Dm>X*jTD=qv;qd`Pr@bRv=)4YRfS(L@%FpNA<+zEr2f2L6t)$ z)q@NKxxImi^Ot_>J}muK+idm;Pd}0Gc?S{J$s-O+J#Z)spL+IX=3!w-f6al*ylr2T z(H2fXf?)^U$c-)^OVDC630emqhVec}VLyfuW>}1m24UCn(cqfhcC3AySU)5~)1%^p zLc_4mvDqu3iuyN{6NKf}U~tR0Jl7xYLx+Bc;lvxpR37p_2e z{7*f;bOooTdmIxx=7}4$=Xy)_vghd)XEQ%aV7Q`Bth(+VJ=z zO*51ET0#sQu#3m&z>Nsx{Ylf(gx!MIR;roSUhuj#0A7wMPT)nh-Es-5+=K)vE|GLW zcTXb0ni;RjmF933WW%A?(G40d;$|sa>bPo02(l*p)E%1KL` zp12qSi@r7-P_gtU&)$Zu!TY)SQ)fVHKatE56+!5K1=$T5l)M0=IDZjIGTCpb;8m{% zXf3`8z*h1AK`9P3{weRS=DT1>;?z2h$s>)LqQD;Dp9m&g#EJ5pp3q3Y!32%`pNEUW z=MW_QdNa+ftt%X^+U*Yik}J$g6J`}#4FKWdP*&pt^41wt6%6Iw*+L{BL74BPaJf&M zTrO2d*tkm^IG@Wlw-l?~1ZU9GKt!24^k8jQ`K1xHYV<)0zCX7D$_3O_Q4Ek?G3AC% z-XgY|NmfekmCAWg!Q1-?$s9%Mrl@a-5Z@98W3%u$l&ekei2`LmZyro0S4A|vZwiOS z6IF8>q)yt{&`Gz9K%CjRv#27806rZX-@)|)2V58Kw*(el7GwgkAYdNa1T&PK%tlp=zbHc$^}q$FVnQ8uXg4T@EbEs zCnXUAnak<|Big2sZ1uvRz)76oKKo~=e|4(LpScXiYd*Je{#uuylT2fV88T0K)JT5Z8K&4y%gqLatr%u|Tl01E3E}Jky*<2YoF$ zL#~MT7}$t~`h%ZgT( zz0nMs>M1c4LlUqp{**($b14?4V%;Z1!SNh~D(qtYNN}mrR=Dmqf5zxWC5Y{^6t{{U zF}q}S%i*abK0Mil?Pz8cJixm@=MdNEA5c*!c}fIW=Amih?glWuU;uRljD5k>g$83B zm6y2C_GaN{LWaoc5wfG&)dwf%*j@a-2ByLx6yFg?;JRM~L7wl`aStdgKzMUQ>KPPx zNaS)(5NsgN;{hB1o|$yu7htz6L_ZDW2>AiTF=SfI(?l>Ry_^n{qfG@9AGSRbk)NZ# zAR|4jF~Xfj3)>rAA#$U8bUFZ3eMq&1yI$* zp3OG4CVCZ$PS_4Z;2QS!Glf2)k4sk*Nyuk0HgE8p5Lk@|q1~_W=kdx>F~dx34d;oS zrw>5b*KMF%R*X+0?qv7-$h)hEOyaJ(U8_7`|Dy$9P+0kx7 z+hz-S%C)b-PWr4*&Y-$& z0@X-zd-6weLy)l)SU9F92x+Dp$(o;d1CEebWKJ(es>KY{6?i+5t}xVnAx@W5Eq5r0 zmO0-$;q$z60Kg`Sj#e2c=Eu)DeP;O?>9MzLhGEA;my{xY8L$ zRVxUF_A-eqK9zg^f%ZoXS_xo9YfQk`xtR^z?qku-;Jz>SCAnY+<)MAWNhxZ-iTVR) zH*mh>kxD>{3>R_{T}CeIvml;Q0d<(-oVB33kL$ya*DLzQN2aHrk2LzuHno&K8x?s_ z+r01OGwRp`ujqtBc&dA;J^kH~(r`<$+THzc*(t{FhD2%8t|5xvPs)rtH|aG_vw(HY zWBmxlvq5r8wu>`$HnuN4dDZRPPX;U1CmxMw7kCzIYl&Ck!i(lxcW!Bw z!2E43*395ywS@f^cT0=~hGne$O4JhWE?(;%qM~FN;u4~gRAX@wM2205soaw{*PIPe z@$Th$nRv9@LkYxt%XBIJ(*fos4#(0y(Vw@WtGFLe6aSo)v%j`safq7tK+^K8-Y9NtsOvm>y$^=tsog`F;}*UN>t z7vpNtNA0fr4l?%JUJa@Jc+K9HX54Az;i!^V{M_+#rGx98OU5r;fgGlnODhl*PI*!S zl51OHz)rPiK?1lvt}$i3Hrch$;S8;yXg}}E`M~bDoNk!B#6z~A_&EturgvH`xyYNL z#rHdRlHK|PJr=iG&u001`Ia6vp0rw$mi>YDP;mahjZ80@g-2Mftghu9W2tt2U*se1 zFy9%x`cVL^9?H(njJ?)A;xAHIma?&zE?Bv+-YgGq)}vJluIgu%v^oaVY6t_g)b(Vi zt(?9O3%)i;wU z7mNfHw>k$@wDYqDmiupzM#=S>=7yilz#&>=5%aT^v66M#tDtQBoS{p$-oGoe`@L~9 z`3c)jN@_ju1U=L*6nHf}R&6e6bzYRUZ5W_JdKzd3>9@Lp<`U+N($QO+U~!3|=UaTm zSAl!?a|arh>vsIAWWDx17w8t%Y(mHT!@8e-xB0xDF&WE{cF*x@kaDs*3}UIN&z6(1 z;Tol`tN{~vYcuc4bjj76n~WVTXLJqA_wp=zJ1roivf2^2mRGLbXmzd*efSs+)pjYZ zcodZB8r=!>E%l@uSijpv?aWZ<4XC7*7`Rr8T)48FFJFYeymE>0yM+T%75P3E9^Zrl zo$@_?i4du7e|v0bLYbLYwLt#$O6%VKiAp(R#iLEq%)I;ViGSFxwGQdv@l#Cb)pech7mNT+;TV+vfqqJvnXl#`Bg@RM zy26;0`isJ^!eTtwxi!;#z4~kO>gLZ`*iEt(oC^xIrP}SYd6&6hlCQawC`N=xID7(w#Z@=6;Q@%(GUg2#+Q4l(-!L{<5V`8S;2ov?58pgMo?GV!E zTy-AA39?)pr=59LNPR%RX8u#BrlKEC<_-XvJl)T1xc~J+Y_w4IVAN2rl)Xu0N%+-J zyYqW1k{S0Lyazu8g`C(|ywPNBhDfK>-d(6O#%$6Wp9PE;225w#e-|>?SDdi^41wIY zB9Lf);o-bohUeVT_?sdIELCrso3OfUi?yXj=M(`6En}X49{=uIbLoNl9igNel0Fq# z%1Cc~7N$~{uz$zCls52r|GgeO8|?B>js1lX_Pr*&_K#-(yuuIQv`QiLBwDgz@>jNx z#(`9a9s44N5>RTH2Nd6bpSDtXIRCua-pj|bx8E3)8qUwP5E)G~7oYhQ)Y{_Qcc5Cn z#o4kZgPm}9$6_~}_FZ(oXXO~Vpxoh|G?Bj^MarDbHV^DhY?L_jVVyzkOU)$iU6RTz z&Q**zQ%4(D2j1*aRWe*J-27UWo0(l0_u%}TNcm9Jh|l7kBEyeXd8$7QH+{)m_cC+7y@qU-5!b6%wkCPp9{hz?tIY~(5@vS<|1kYwxT;NX zd9UjT?`&AC_M-;+Bhk3Tlhl}NdOsAJ=6IElYedyg@wlGeUTVw|)qcZcWg@a_)baN) z>T0ffRS_d`%H|cWr_<#gGtxx0E&n8N7Eg6+IG46#fI_azNw?PUWaqW}C05Lc*oaM9 z3cliVOOveYp~f~9c<*~On_AHK{LY#U-H&#DI$1jN;lnq2SEnw=iB|UdBpd6%q=62YWwd_ zrIC#5jM8&*C+Eh7^Oh$qZ}zTq&yJTci!k-+f2Qc2)wgfJC|%0;!g#-4_RN5xWY@#F zQlE0kTWaC{Gi`}J7w1Miz9vSEWVFveJ@zttPhaJXUc7SI+~?tG6`eiZ-Y>f6zRZq~ z6@7)oJ2&|L&`aG{{Q8sQ^>o^fYr>~9+Mii0j(6}sF@cUD=i`P`D#TxUx*k7xbELF5{r6|C8F#o@ zCaJ~gIsdad(5k~_kafKC1ieq8RmcDTakcMjnn|ix2GKz(QOEzGYF#w=%Hrn83G18P zNlR%F`xeCUdBc-NiT}b{eXyP6nQhI+0aZJNG7>!$|v{z2MLi-837)_N)HlFD*}>{CByzZzo@r5i^_( zOd~aAN_FEV9ia@!vi(rbN(RN|FT(Z6Mn8}NRdY{NxW7xVfAJu_7z zwt572qxI0Ov8d2{rG2Uy0`{aQExwgCzpCqZjj>s*;X%kr8G7~KhB{2M4i5vby2HNEu&6H}ifutRacZ`EFovYMg7uW< zoyW&_k^%9tYY3S=kxhEVze=ipK4D>DhiR^=UB@!9j?wRm_&H^d9JD;OSD(#Wt7Ack zx>e9)brbHOkX^gURK8w(jLcGLvPz}p=^YdZy6Z|cnUdKn=qm1B&OMAc0&lFwsDE2d z6WdNTXs#cY*iJ3da=j%G^(Yb`#`Jv^U@1&F<2cd}4B}M}Hkq%t-Sg>UN_U#n?PqN%UxG}NV@`t6Om5rtHx2BQ} z$#f{pem;yLP1s@rCpELb zQ#o(X$J|~<$W7&}Z5zC!MEz`%646E`JVum*{Nk^`zJR)x z4uVkoALZf1U+XC?n~&{0C#C)lYkG$Y@;6FcF$WELe{!b2rU<@ z*3x#JCYg=q!(@rX1QI#_XNhNwSofyBon#_t*@R5|$Ig;Jnjj{gF*1a~j!>fLb-o^C zVWyO--5kkOAHY~f)CSh$k(EA$HGHcn`Lj=KG;31dV=heU$j^1a>aZ?65x@KFBTnwW+JJU z6gw+R>p9_uN79Ce$>hE!508bqdHLF&b)NuLmf#MFu;=<}G32eeKH+*BsF9_<#hQ^W!2sJZEHvpnOe?Y#?Nv) z|0un$_(--)+o!{+XP(KC`EgC06Y)tg>LuOvGyYk|JvY^-D+up?z7G14F20vD@mTh` zH%FNQl!L0yc;1wj*|ZT3;Z~}>xv#T~de;W*b?@x2u}Mt{=5ULs*dOmdGdJ(G|GFiy JmlpoxzW^n??~ecg diff --git a/admin/charsets/mapfiles/JISX213A.map.gz b/admin/charsets/mapfiles/JISX213A.map.gz deleted file mode 100644 index ffe3d3344f5450dcf3d4eda2db6e407856a5bc3a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 178 zcmV;j08RfNiwFRcNHR(Q10~Eo4}vfl1mK-t@dkF&?}{6RHqq6^wL*;~Pz=-r|Gh08 zZg}pJtDs$-4Q_zh`mdd)A3W_Axp)X~2ZP)Cb^L@edU+ky=K6z_78Q&h%G>o04?qOd z3qgoMGdn-T1i0xmmN}bL&Gv#)-s18XD-Vab|X3)Y7XZw+J;Ndp)nvo{{ z1H0|=>*lW$Wz(s%OKnKx&wgjfLYRzb@L~bBL^G+5U83l1*5BI-@K*tkd<#Ru>H> zn+}n!&YI34D|W}iz(^9Z>R6mSywZboFR#o#UN$VP%&Th&rl(?L>G6Eq=X4lW_mt1i zkDX{$;8>j#I96gt6f3cEf2&qXFX;S`Yr3>!T$^{|RZ~aJcxrWRGow{W?%0W=xQf=b zpDH`)_AL;P-IuVgm9qQP_IRk2t@wYkm06O?lZ-y50o)2ISfSiwAPP&9VvH z^e>|*Fw(OiOwzqd`!=0iZTCg`4_Nmjf;MXur8F%$4UIXHQsKGny8JiK5bkDfrg^(r zqY2e?b!AJkv!_o_-yfbD9;&`xT}dn;9{4)|-RbI&nHxK!{3zg;8=wU!@$L9kL1+Lx zlotm^L=w8S{)^#j1!>(`H zlvLF@Roor|WsUO*!xJwXN&%M%EWm97?2BXKL%ttFda@AC^wf*J_&G+tkNLKCtL>4w zB>yb8pLCUYuSQ#)HDVr?Fu6=k`=YnLMmq-1+`{~`=&TVTz=Px@B45I^5#^+-Iv;bW zML}{wB-6cE+jhIY##txl-YphvhA_JG1jZqYBEkj9G4^5!-r#GUb^MuLEYsVb+(Z=R z7==CzX-Xk%_6$LD(N>kV`b90z4G$_Gu3Umli#G>Te>7YkXf~7&oa!>r%4ZyDN*jb$ z;>#+5l#HK&ZSI(hjJJGo zvY5!&JaI+i6KW7mrcV*Y5CFgcfD8b60GN+qL<0c^0^ym12OKDIH%zU&#ecUBP$)oo zs3K!=4c|4!9t);5U0BEi0xOV+hmFGfVwLw$gqZj}OyzdiVvNEC22ML#6(_9^ZRUh$ z#{;4T5OhGaQ@L+5FPhV4{<3@mggzjA4TKH;+EH}8w0>&~CpO zn7}at9JRm^1|0thcozA40S-^WHEeAG>nDQsFN5`=g*vJ$ZMVKX#t$UF50dLZGC4iW zpQnQ2QDR4nJ9X}M!9hHfCw4qKQne*)UX@jbGD^aE98Ep>keTM=ZEL(B%#S@bK*BZL z+u`xgajS;P<3u))CtRBV69Je#9xCfMC}YlhybkpT&%ZIN9A!Kh!7Eu;rh4*<%dOn| KL2qK5oc;t2E*pFR diff --git a/admin/charsets/mapfiles/MULE-ipa.map.gz b/admin/charsets/mapfiles/MULE-ipa.map.gz deleted file mode 100644 index 7a046584f7dffe23bf5ccba1e07534b83dec56c6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 370 zcmV-&0ge72iwFop@G(jN15H&-MJ;J?VJ>Z9Z~!%u!EVAZ5Jc~Mg{7VW$M$-YBMC{r zBZa6%B0dC==-*efub==q9I?;oDQ%`L?%&oP$zi@7Ogil-krOXatEz55xu@{iDo8Dgdw zf0M9_ke_wt)`C-*o83;xZ~v8$KjYR??{4$S-ywe?zx{hceg(fw^n*>wKY&?z_W?7N QcR%~xAE~;p93le%04r?5Qvd(} diff --git a/admin/charsets/mapfiles/MULE-is13194.map.gz b/admin/charsets/mapfiles/MULE-is13194.map.gz deleted file mode 100644 index 524359c5544f801d7da3f31a09e1cfc35e5a9693..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 436 zcmb2|=HPJpVCcob>>KLis+(DCXl!U{qL-Ukz~Fkp+wZW0K+8kh^zM{ z=$xPsx00a#rwNDN2L5E$L~Ay z&OLtmr(#cCFMqv%_s7*T%Qo5Nl|N6~_TlK=g3VEFw>QYF+BDJk=E-$3PnO*|v2xCn zb$3qspYngQ^wXq2YySAeX|6w!{Z#yu+t1Q-r2%oD|Akf_uD)5LaQfMgY>nIhzxVAw z_2$RwGgzqC-A4bc${()3^=N-xZsDJ0x_$Rco*&4+CG^8LnrVNg_XG2v%==Hu|M2~H zApaA4-DLX@v;Q>Sf5QJqtsY70{3et8|8IHk>KMwtUzw!E!oUCkdHeUk diff --git a/admin/charsets/mapfiles/MULE-lviscii.map.gz b/admin/charsets/mapfiles/MULE-lviscii.map.gz deleted file mode 100644 index 4bc0812b30e27240aa89a0bf8389951110c0c03d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 388 zcmV-~0ek)*iwFop@G(jN15H&-MJ;T0X>(&~X)bMHZ~!%t%WlFj6h!xYg{7_wP8{2? zj9>kZ6rvUhvfv@nzi($I-5soZ?;Iv?=3`#w+w_=E=JUtgp38DxzRYwzotNG5d%E4{ z$9;EwUgr1zU)%X&&Wown>3BDNzjfP_+>=uWcH#&gG~>Zu%=aKZfTOs8 z_u3^N#GDz$%u3|UtSolmB4$<%HZaK~%6!N+U2;-*(_g^yPcjl1fh;l7tc z<()>iWdAtezgt_$oftEr7x!Q%hFe&_9oh4aCCja%hp>J-xP`rT_uzvVZebLUU^yqw zXT4`|5#xV_%B-Hd>MDaH{ksm%QN1;?{2TnE{Ml_B!~@ui(NC0rhJTcQMs8fY<&6B< iZIpk5e@t`;d{^fc-zdtz@y^=6+x!Bx_tb=H0{{Rt>Ct!q diff --git a/admin/charsets/mapfiles/MULE-sisheng.map.gz b/admin/charsets/mapfiles/MULE-sisheng.map.gz deleted file mode 100644 index eb9bf0d6897a536abeb511747215d7c939ef219a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 400 zcmb2|=HPJpVCcob>>KLis#}~{oRONBu9urwz+igmblxEYf!2q%{)sDJH>JOkoTU2X z(sK{RtceQTdP23oznxjQ+g|zjzoJTS`Oil2%YWDS%(s8}D`MK^Pg9qj{#D_azWbB^JN@6` zeEEL3$zSC;t^e*_JlD4Q!u{iWd8OxF`gHHbbo*-ubettG>KD&3-H_}*>+u~azqgB~ z_SR-4=3kuJo4&F@>||S+*_qPQeP4N{)2~jG{r&#N#{ctVtIKk1yx-oeIA5CZIQsg; z-shWSbbq+1<@}Lemb0f`JEul@b+xT8Eq38vB>Y MKu;rn7Bd3_0D`a3DF6Tf diff --git a/admin/charsets/mapfiles/MULE-tibetan.map.gz b/admin/charsets/mapfiles/MULE-tibetan.map.gz deleted file mode 100644 index 4f0b0fec200cc7c891946babb0bdb9ddcd5ab867..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 825 zcmb2|=HPJpVCcob>>KLis#}tolvpz+if9Z{D3S36=}@{5LveovyC;oTj4s z)Ka8+qQr)66LJnz{${Y6T(s+bOhVhA$Df|Rt*fs7S^2x{=j;2YZ?FIT_xIoTr%%7$ z{{Fju{Qt_z>ivIf{(t)Q`uN+=|6e}*_W0A^y2`5BpTFu>eqCr=v+LiwrLp?g?_YoZ zI#erY;;N9PYNji_W2G)lSZ1=+HEKy{)KcGDOJZ*=b+%d(Y_-(=Wnk5$c}vn?{!}jA zcj)?0uK4HLHFMX0Ad9o9FKYiC>zAU)(zv)^}u?EfG$2W(zb+ z5x_wm)B4D}FXzOA(``H$)RWU~K0radl=pq{?MvQwM_>AWRQKiYN7KI47JC2Mw?nly z{?4R*`gxvUY45y`*Sfd+-51ZFyHEd~Rc-v9(qH>3UVo|mdhO-!Q`7gYufb3KdYGO0 zv25y{ouVh_Mgu8RAT|BYPTrGqZ%?_iQ+LwoZN5b}w|VQ`E}A+0zTe5y`Tdio-?xj~ zxAf@k%`RJnmmakajM{^hS}%0}+;p+`HJKkVD0!gZ!Rcc7sh`3YKR&4!e0X}hUI2=P yQn~#WHci%uE(&~X)bMHZ~!%tOK!t33`F-ig@CS`=wnIA z(zc|Y!%d7fK;lI{KzjRjX58JgKyseRH}f$s^KE*}C-eDZZqH>oFJET5p3cke_&we3 z^W(m|J}>k8|JQcDnDb)lbvoXS_uH`D*q3+4zFh4q*pmkf4&nsvRMUZ@nD0rv2WRmJ z-m8~<5VNKiGixA^%o@cWT*S<(VrDgRL4B}d)Cc(&)Cc(&)CYMMb_yl~ha{a{X1Z-Y-%Z^g{0+zOwlJv8=e4-NC9 z94hBDxwSt|_;+i$x8%eQ?8Wd&K^(yA?f4!!$CBk%v4^zY4sL0$UihSg_yF$3tda9T z9`%lYNkv@1m06y1v@6cc^mh*aS$k__`SYe({ssQI6JsYiiX&M5BmA@c>5$jmvR?iL i{#pLKX&&g1=%bxi+$hVxz(241_nTkWVr)}t0{{T=mCY*v diff --git a/admin/charsets/mapfiles/PTCP154.gz b/admin/charsets/mapfiles/PTCP154.gz deleted file mode 100644 index fd56923697c52d1d26e8e1d73391ba9f49f0a8fe..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3169 zcmV-n44(5JiwFo<6fa5u15i{$P%$+$0F9e%bJ|81hQDXV|6yl3)21_zJLnzqO^5|l z3yJ6@iStc>sF`AD0k=ti{j)lIV|(Q#tUFUD;hfb+*nGHo zH!q{P<+(TSZk}JMx10Ld9L0;v+s)}a zTkj9->DaK%j?Lm3XQ$@dNsM;i9NWma$e7jhU7t07KW+Z0x6N+(or&aaJD;DJ_!;jH zkM-#TD<2L`)4p_jZ2qbb^{H90<$nA0xH}@U{fX#b*iRPQ9NFoiVe>Zh`(F*C*@}!+ z!`_R@JT%{a)#TadylS_39n0z?>wWtoesoz*H>|yF+j{fiJ4}3{54C< zFkxjltdg)iPd!9@sKh66%GsFn5ycDB93f_;#6)49 z$KiytoR?KDN8^a(>TR9IV{uz6d9%id8Eax<8pZ-=mde>EEW`F(?-(zla86gy0&|wi z+=zdQBhDgm5%VlzSt^4;on`+hxcr<^FwnD{9|lizF2@FgmiwddaaQFN4F)Zh!IV$L zo%zJOs96BgQh_Y)(`cG!X;u|19wjmqR9Y&P8W-3w$)Y>T0jidYY80jsCzdU6Y7KOQ z&iE*?m^qKKeAEdApO(sJmBytSXoFH)rSw^D8)(`pn*2+YgfkM5&BB~+fDJHh70i!S zR(1jbrL97lR^*zWLpfd+@Io^yFkA%myN zkc$qL7yNZg_h5miS|FD+nt|bfr#cYDc~s5D3I8G<5!z)M#R7k?gMap!o($U%AHe%6 z@RK~GhmG?{J}~!nm>07!QH#D0$bB8;N;s8#ABg)p#FcO=_&xylb$~13RPKG??d$MX z!sQhK+`bNOC7epV543$9+DbSTdLLl>I+D)T(K<(?GR>G;o`#{>) zm3Sqb3cL@deO-Z9!l}Ib0NdAf^#HsFS9zzB9)S1YD(_Sw0`MMO<(*s&zi64GL3yB3UdG8tjs~m)73&cf=fT-~@%z^{tS@nP2kK3W?(;ZF;^<8Sn{xI!E~jFg zLX`9oCk*=*2CnVbh{AKmY0wtdOH%em1AmCT=oQ7#{h`VMB`==0V3sX0EGVRv_L zMp-pXc-!Z02b#T-z9+Lf8yBxOSGhR)9NP$e>4!TsyVQ~XQcG*x(Ck8qGYp9zGPK{v z49xD+G}KLCfC-HCW2jX}J$#MSp3&ilVKKdnMa!U-Kz{*3%;p}yA!Lbzo8|LVckU}t z78;Flr@ej+?t$4D#dIo9e~q-hQQ9*+&sFAy^}$*BKtGgP?z9vREa;-yXe;7$BAj_^ z%fLpGZp-a*mV>PBmWMbL^wcDsb=H;A%UNfgRYZnWlE|7n@G)%ny&^UetWrdPh|c>& zvzLgogC>dhXx~P4IG>e zG#TOS-{9=uz#!>I_SINFc8Xw{-41ge-o0$@*J!Fe!%8o@j;OQj{qTFU-5;Kg?c3GV z;%oHQ?t|Wi^Sw9>T5Qj(0{t#e!UZj6Ny9MD`A9CbYY#WtEcL67^ZML!%{tCYyXvkF zYAjYm)wzO4R6)+0q&4L3UGS>gq~wWWsTy|B%I5dy+KAC%?a1tk6w&lEv0G!c8ophv z-p;c)6>HqdxhjSi%5aTEY^avuG3r`3$-*~`(-#+jVmvu_Ld)@d*#v$1dsbV~1n?CK_rBn$$E zW=l(6=A92y`?{a)xHLb? z!5Y@OAeMG+8Nm#U67pU%+e|9jR9HbN+e|4= zd+jSIWt%A_9|2ZS$~IG~EaW*sDcek`NQ$_EQ?}t!4>N>Swy9MS^5B$h=F~LIUshu) zsAZd}b!!VbonvGu;nkzVF8#+cgP|P+{>|Rb1j@f38-P6Tv;Fxp4vA1t> zH4w}(dK#zGX`q*LK`(W?U8X=T$8d|3av+y;K`!+@GMNIkoC|8HYcZJuu^f}-EIL&K ztsJ9GESUnQ9Fr9l^_m7gIY!IBmmbx?r|w66E-Zm41sXX<>n`d~4HR-ND5R!PcWPjc zW3o1ry{UmXj>+x;b*2W^I3~}5vM;USO!q@W`gu`TT0k$X){w?Ekw$i;HKcJ( zq@kLzhBB^+GO`=3p^R&yjI7veDC3$agHE)DGOppiA?3gs*Tflgp*5^=&8$HWTEiLF z#2KXnt)Y%gZkZYol>^y5YaJAZ;Hv3(@ zWt-iazE~pu_TlDT`LH>%CBE~rsE?uy?04*=f&~``xKtp6IJE>!-u%p*eI8A8wm(^=>8p zy*mE6|L5jiygN0AU2_`Mr#fodzp(w9-PQlqe?FAWwps2U#X+0f_D~;K{nTdtyjd-O z`}05gT8+rqwex*C)_=6$q-j4~*zO|TynBBT$%hqN9vb=zjos_nx4prw9sK%#m9Mim H5HtV)f9*Vh diff --git a/admin/charsets/mapfiles/README b/admin/charsets/mapfiles/README deleted file mode 100644 index 66fc3546341..00000000000 --- a/admin/charsets/mapfiles/README +++ /dev/null @@ -1,82 +0,0 @@ -Copyright (C) 2009 Free Software Foundation, Inc. -Copyright (C) 2009 - National Institute of Advanced Industrial Science and Technology (AIST) - Registration Number H13PRO009 -See the end of the file for license conditions. - - The charset map files directory - -This directory contains two kinds of charse map files; verbatim copies -(or their compressed versions) of files freely available in the -Internet, and newly created files based on freely available -information. - -(1) Copied files (all files are copied on 2009-06-12) - -* CP932.TXT.gz - -The uncompressed version is available at: - - -* PTCP154.gz - -The uncompressed version is available at: - - -* Uni2JIS.gz - -The version compressed by Unix's "compress" command is available at: - - -* bulgarian-mik.txt.gz - -It is available at: - . - -* cns2ucsdkw.txt.gz - -Uncompressed version is available at: - - -* stdenc.txt.gz and symbol.txt.gz - -The uncompressed versions are available at: - - - -(2) Newly created files - -* CP720.map.gz and CP858.map.gz - -Created manually by looking at these pages: - . - . -The text in that page is under the terms of the GNU Free Documentation -License. - -* JISX213A.map.gz - -Created manually based on the description of the section 33 in "JIS X -0213:2004 Amendment 1". It lists 10 characters that are newly added -to "JIS X 0213:2004". - -* MULE-*.map.gz - -Created by using ../mule-charsets.el in Emacs 22 as this: - % emacs-22 -batch -l ../mule-charsets.el - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/charsets/mapfiles/Uni2JIS.gz b/admin/charsets/mapfiles/Uni2JIS.gz deleted file mode 100644 index d87c3af23384735619ff03de3df72090e0862002..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 113926 zcmbTbbyVCz&oGJ;zOVUkQHlgY@BJo5ExReTm1I7D^3?`$&Cs&I+AwkeB}f1i#YQM2xP z`7BIOuFD1&EGDRbq{f8?zF~12SUV#GmRnF*bY)ya9!~x+5@P*vi)Z0+(Q|d5=}^~; zPu*J+^yktMVDeXpfn-!^x@TaHm^Ml4YfhUsdH4g+-N04Q4xi;puA`iUD|O<|?5VTq z6zRX7Gn}CyVLLMNcl@1?0noHRAJsJDl;?Ji0ZQtrGHIIp$&kwCgN)Jj{WhkEfo^ll@K| zKDx_vM`Ly^PicU3Ume?;ify~P)lV8nXMmjKq0oN2IGfp_;xTd*x@BJ-0p?RTBk!T! z&0EukRofo?L6)Tz<0qr@J0mcIbW9~7q{dVCsZodJ6a=6pC+EgI?l(w?Q8|!ZTw&Dj zGX$k|AFj#vbS^XdV>+KCllS~N1qhTkbsttg1p#ETi#gywxdFNe%Bt6Q{QY>iS7|5k zk7(?L4`)Ed6yj8?CdLpdEseYAof=c%{g3VMcN)2Ae%yHQ#Tc zG)PAcpiYGH*N25)%OD`#sZkpyuBTFm%)4x4h z)p#)H`b*+sb88pkcPVwIG(XbY>(n9JShhAROzZCr;U48c`!xoPEo;MfWHM~*yXSfs zh1v}(go;wqUjp1wJX2kK-Jxc(=($+F2JM|Py9HKCNl%4`DO-`!e$Mw7b7yO}!fY3@ ziX(nPL~JaB zGN-)_{MUxBoZ=X`G33?q=m1!@0|D5kKC<}eS0;d<*zdp-pzlNmje&LbN30u0t?T$q z6nD99@So01npgFj7dOw3VvTmUnH`Pi7I?K>^H1*)C>Q)o%4k+;>d3_DW z0p)1zWA&mfnZb;TJ}o6fY}tpp)W&A_r`_{j9E~+s1m$db{XaQ;M(KM)SF|iL4{SRu zs*u{p2EyIB`*Pyg_#+=DiLD4Aek_!Yd_qBrGuDcXbgasIhbB#ffSQ<1z|^BenC$Ik zG3AI@a;V*~v~rAj=x3lw4DjNJm2XVSm-tLz{j&pm_BicUhV1H>0cxUH^pS3+mLa;0 z_>`Uc^uHb{z%~J)QfB4}bf-JG?4ja1Clz^5Z$b1fe(v7;tLjk%>NDBTot@(cOG2GL zg_-SpA0%0-%BC_cK7M{3i@w`y#FiCpZ)qBU&11?(rr|4TiJDr8I9tX1NBg2OGwM6d zPTZBHsQ{IMWk2GfrQuC7b~?({dDl*%Y19U#GY1FZ1RaO5XCGOtnmyr`M;~dlT$#c5 zuFC*nGWxZ|ZT75lB{vQ=6%Nai5wVqmJmsGlJM-U*-L4!)Qw}%2@fhmpYlg-lQ2#OS zb$M`dON+g6oc2ZU#oS@J^zjHQW&VsTr7JfqfVF`q81S=VMoA&I-;iE+w|G1dCvZVs zNX}_7Pudd;jSLw(I-UwpYHsACHQpos278dcQKeQrww&YJ_k}+cjJ+C?ja1r1BN`fw z`SgT94TVPHUr82>EZ_8gsSjwR*|GVBG>9{URZR;LrEP{a;(Q@rG$JafmT1nujcLT`sl?QV zR8VEm+|QVP-!#T=)Dl#9&hPdW8Pl0`oTsEjL*W-gaU~2tV6VHeuNbACLI*Oyl<-7L@)t zrQ6nvXz+BQ*()lx^Jkb782u^;Ux2$K2mxb$3mr-Nq$r3 z)J8XR%Sh_iL^pHFNa)u^H?ylma@$bbMQNRUS_%W_(`=J2g)!yhZ3{mCyxL}O#MTx+ z0J<+onqq$-&*=@#FZg(UM-~;MqWC!n-98rQCyOD1RH!a{8S1dXAW~=S)RwNZ+s})I zD>KX2hU{e_zF&4f`j>6oS&3`D&H5(G7{@s7t3BMp@*Kc=*MD%^#2SOYh}cXei7w0q z$geTYLyE@^r)Pa|-d^>e7~x$PtsdKY@^tUKEki=`N;p?1JlYYjT{hW7$F)f1*}63A z2G1K%oAgq|;*q10yEu)FNUx}E>tzptA9y^Rzge6;Q1OOz*NO6U{|)3OQhb=9|M8pn zTFk@TL|;o3x6~n9^)6T6`qAaXkN)8A2^abK$VEOE|KN;*iz_dUdr)@tL)|xO&|>vG zRwanWJ9o%dWf#UN$=;qj{5cJsTp_W+5GdFn!kDnM`V(<~T+)6;V*l~zBDn`euaY?A zcZZ-Z2N_y$IMrSwvE%4$4+1{#o0$@6&epFN ztAu`rysk@6N_yLMo;>B-HU~9vgOErsXs8ka5o?^7?n0O>LD=9%wN2j#iysj@%{Gy; zn79&;>Wv;PhKVs)6;?JSnBqSy)lI}cU|~yX+P)`-dzUBg+L%B?1}2=L*=6Cl(w?zibT|#&4tDar$nX`G>1D;WtBCHhQH9kTR`d*-Sn09{EW zityC@o=}8P0Z+2P1Dyh$&aO$B4|(zjuF0eZ4>HzI-0&$CE@Ui8TI4Ea4rF>_w);hy z0l1z)aiitzPfVHhj;k?v`+V-F@3|NVGHv>EGvN=Dsh#E;Laz3AsVQ@#W9a9Kd{?Z+ ztvsU%4WguW@I?>fDZTE{1K2f=SA89E#4oTcbd}}g!L4IqnV%w@g;Zv?zKh#61UZaG ztejLCJxy-RePBQN$0;5q`yP3(d|ox;3E?uG1uN1AvF3ZM0<~MuAvczi48v}Ch;PIN zw)H5uxHK|<9ABz4WBHZH2Zqh!TFP=fHs$<+ak%yBh~ol*SVL4Y#yCS;LI-V$RzNLf zHJ*S*K5!h)b%aFObRmrTu1s8l>!e!`-)L4MvRMU7EBwj|DX^d6=HCU!(Qm_=cyg-D zMaFF}{O^g(MK~H&Uo8!^`g_Hmr$BZvzbDK3~_-bp+5!IKq zl!`lf7N3hO;OIqw*(5n6orC@D`1eK%y=0Gb*aK?OuW~8iKB?@YE3Ng1i`QBWs?6*; z*VJ;s6Sx1vPEy|^nRX4rZ^DT>Xh8FNB}s~o((W4J+oah+D;qu1SPuF3)`hc%4)SSq zI=3t?r@tZaSEKxKLts%RM|@*k&R!O!17FI4JLgaW0YU7@&V$1)P3^^B<0^*CY$uNK zeM!HN`D)+^DelzanGGXP{z&uyFT$;>T;ao8MeATmkX7I2QaunOYd-6Q*ir8q+#7%Q z-Vj*|lQ*V~_`EbP{(=6N}6#i3{Ua z53M*dc}(XasUBSGOnaN-tQ<*ER-PrT`!pX!!?+b&aR4|2b<5LUi>$}q@vM5S_1ol+ zz`>KJ0imC<3pk~n(XqvD*S3$ZG3km&8?J2$;(p45A0WOo+;Zvd4PVbR%gs5_~r=|F>o=mabnwEdw>{Hdg z&RETwg^y*X!VUjdFGUb1VRhGbNj6;&JJ@$M6;hgmCB-(_Hr>8EC2eYq{C$27WL(c( zN5@@-`FeB`+rn~jj>SlPQ#p(3!Q+Za*wA`$>nFzhjiKhilANk=>FV#XkUl9qE_;f} z91mq(dG9N_g{HdWz$0m)L*d`w+Z*G|*JN68NU|cKHzWAP1oPJUu|fm>M+fNvA?8m_ z25mh3gGx8Kj=ZI2i^Wd%^#cvKgW1qJb=rr^7SS1 zs@TP5x_@n}4qbooOuAo26S&^%@z*iek=g#38o&?a01cs^)0+V&#`1#6KlYSQ=HxBf^wT>C{yvdNkKA+d)kVJjMG7H-RBjz^>`9u z!ceM}4>ALxT5-I_UHWrpHK3RwCeqzEg3>FhpiWOpP;q zatd339b;M1QlF4lUhl)X!12Llz4FntA4l8?yb!s6E&C=B{sp9S7tAn@5N46e(X_Y+ z?7r+o$?!*^!cIB}hYWxgBP~o;B^o3Nl{l*2$JU8zg#U7L&OKLw@SQ4+7ZecyuPoZQED^;+fH&6 zUq2vyR>7ji5C2@jti`}v7#~FVF)S{kFLh_To8*h~`cDLw#KFjWQF`7V`CaHp=Jaty z+$qOz_r(JVP}`NLSWp9UagmJavBbjrUNh2Qsr^?dQ~!-dO5|zIM}p9DnJzMw=KF+F z=&MMlgx@Mu_N95AN)bC#PEESziSDb z4r`GdZHQ?O6`_|S{yZ1f!gZ3{%5By5W85D3z%Q%HwIckdCNskQcou zvMDP?F!o>PuE{iRwS zDm^fW<6U75!gr+{)YrfuHdqsanNrp>%?{H>uu#fC9US-{nVY0i5wqcA1D+FHbl1|Q zd+VXpU#{vGIJFH(42P}%o>VVMm0)qMNzZB$F6w=};c@oPY!S?9iCmKAB+=;i+@U3O zUY@hRkuG|g%lnwaOulA+O2!?z65*d`bk{!{(4c(We-v+nVWaoY&5v`aOgSkwK0@>z z1-Zd8f1_*lSbk&2k`qt%Xz?^FaHL>iAAyWuUy{Y)+Xt529CCuP>(w{Q9pDFb#5c&~ zE=K8+@}bpZMrHYp)blrnWd)6O2WHk-XaQTVntQ}Q*lfY)=*Q62nP#`|`|7RQlL2g+ zz@^9mK;B7zDG+LEJ)%(Yx-+U!F}9&Xi4GDfJyK%C=O8-OfbU%#hI|O#y{s6i@S||% z#>QQ%=nn6A&@!WWe;U1GMM*^*?WY-MMbScr!Mng2?6WS{z$1jY=ncXF{H}tA8_Np8 zrrAw~H#1168;t=9RQr}yzQkw`_|Csk2!mqYE*010ricaM2T<-?*1{UR zJmsr}48wRIY;p#S75rC+3O~TO))!7&kQDBxaexp^$JjwEPj!-n&o)+JsrYkIB5shV z%YMBepKZ=Sn2Jij3KprCZLI!M8KJUy``56yS&dS~C+bljoxg}WSvCmj*j5>nd_;K_ zygg~-&9S84&-0}sMfn%WqHU}jOh?LGb@e?>u?P-Qd zhjrpX| z=6qzMZ>PTm6aSmajfqhX%|d&#S%v2L=t@~-@~>s*_m|-P1wk*jXXXRY$`Z>rLMmr- zEZkb5&9_G+U|&Fh57VBXD#SWFz&QS23kfJsDX= zXp@e(W5e_>vUJSY-QI81LCv$@Ut@OskYd@Wz!fcVA+D|a75EdqJVhBjXqO4kFb^(c z=!hEq${braa$SeFS&>sg%>FH<+v}PHu~B>lG4ub@*YaY- z*1R7dR{42*beA}O{9M!VdYt_WgO9-<5KWN5h`hR3_O^Lx?PggWr+WpRs+4VN4CI7ntAZe#=s~m1(y>&}RIfb%4=KJU{GBdU=dko*=OnxowgR@O3LKXrI%@$sN z3xCSGDJ-aAhX8-by6C@uPtF<&=S=t{?DGhyrKayCgyvD(qYbd``tQH)!JCl@RdJoIWDo|v1MfNu3Vwnv+OFs(x= z-ssU+nn#m4MS|YlPxyo7D5TbcfGi%5@nrrTBTX?aoP-{cflXSQpM=+{zzNDAi0eEX zuM?Ehaa++oqgzLa7x4mE{q80_9^5xfecKLwm=J~@J$d~Q1*}ER+~4{?oxs9#t?{E$ z$Y$uT-~GK{(Eaop1Zrv-l~)So7W#hB`bx zUMfN%SD&spA1)fg`yP+Tg|9fg*tm1Wlj)U-7csLKVURW`ZdI8Bd2&DTK3}R<&yfUN zXdcW}b!4qZubx0Jj}Wk(4LVM`r+ZX<)7?RHisS>=RXNa|6y8U_^w@I}dzLdU;L$`? zCd_dmJx^SZGR4cZEa49R#|?;qKV**u`si}t^Zxz~3}Y{=fO}BZPp9`eyIbiHFX&0a z*?I9?G2-R$Psp@S`=*7_<2?uz_pnC}ar2KK2Jj>Jyt8}#^Zl2h_dUr$XDcV`MuSZA zY<250>EKI6;iroOM>EXv#2i}9aYd*H|8Y}>M{F01u&>ujDyOj2UOdXAF!bqq^_~BH zm3#4yZ1a{6anwcC?H-g6-{UXL&#D|qYRpZ-6l5j1CJ^t5<6CTwP*v17ZszSATK}gM z#q@Q#ulEN%M@}T`I2mA54dT z-wwI??srn}f89n-q#EtqQ+%%l0gU^vTK~q-VAJ|rJOqW}Y2D2RmuHHY=9oi6CQ9sM zg;?!lNMLz!61s|V)BWd(s%YH2^3}r!Eo)1vH=OAx;IPibk zc(}j21@oLwDE6%{-TSV|3+D`dBx}A>yxg*YxR66H0e*K;=lnjq=Svf3{DAC4p`4OO znH|kT(Bm*9oDR@UM+SK6Gf1I^-ma-CC-^;Gwh#ceALF6pEKj@6X3?ZM-j6rV!jG#K z?Dsx49a?A3=Kyevf$;95&eq%_=yB2e?+y{a@a%mJgkSh(s~8#3Pc7sJ4!igU5LzEn zJP+7u!lW0zJ_?=9JokxR6UtfqDP-o=(QQRsPJ4gsb_($sYMQv90ofaR6B)wN)g2IM z0fk`r>rEJ1vw4PGELkWqChawG79_amKk-J6`~J6wp2_z&yQ8f2u;2=N zTs{Wbvy9t_&G@84g9)J58*`cL=CNxr3z$ceB;hq$8_GgsvE<{izWzriWM@ZhbDT#} zZBK5?myDf&+Z%j9r?1}hxMt#-Uq7a`mVRL5=6WvpJ7nwdZ)|NQ?+FI@gxK4EUl_oD zIZnoTX#eyCMuS{tRC(^99XAj4bM1jl>)j+i>DA6N$90$0|* zav$2?=Cjy9Bje6EaeShmR=MuLRl!ydb7*i&$-n=u`_}tI%(DInleWlI$Rc@{{EpvP z^MANxxxI}U6u|f#xY7Bk|CP@c0CFx2IiCg}--pNF@9YUzCAj2Xanz#?_?egLt%LnR zCW=A>qDTaGAK5qOgl3`FC@eyQ-@{19RNA{hPp2qT6+|dlTa(5gUugsG_O|SWePbYj zx)pM)X>VxR0f4`=mxXkN18xJgvhD$am8fLSzC0xCW_r@wm{6fR#OJZKn#MNdW$= ztWigzE{nIlRm6;<#>4R#S{=G9b8pA(t&{O}4HnT2q~{>75N910V9=2&72kEuZfr+u z^-Qwq*)5Bo;?%@@KMitgA<8qf%1)X<7Deb>j*!P%6Q&VpIUJ3wmc|?4Z;AhFgxKOb zLH**AsALmCU3c?6b86)2H`j;_PK?9*-Fgegeo1s>V}XL}PCnG-xYjzU`o zKD6E_9l@)jpt}`=ySY8~=m`#?={q^_Ci_C$^b0^wS$r~?eJX;b_(HuEOTf>jq+j43 zX6jtip?)xse8b5tg$e)1TxUo|v4KZ;8?2j`cs(9R6 zB}3y?-KMkNn2*7jAZY4}fr~|mC~CV8XRrUgoTkA3__h=L?ZwPCC48{(VR%+bckS$;AV1&WlcN{0QW|WgwI=Q|;v;8`^aBFthxZv~2GN#G0=UNMB-X zGr3;ACiPo5(sTxoSlD&XlIkyPB*FS>(sTnJ<|UBwEj*RAJngVIVU&eRx>=guR_)#l zpK1xZyM!(~Lapqe+0KzOxR6~|!Bc~=lQrksYA=Nk3InlHvZV- zm>Fjx2WCVv*no3{5Ep8^m=VX#y0*%+1?%{4#`U^d&^&xN%b2&Ta8;jEuO8)TO! z_1-%Jkw64t(S;cVWjRZ;Gr!r3n?-=Y3-!rZ3;RUtI_8%uO zN21tu>=SqqoMzI3r}ri?i-pZIFJ)pksz}C`rE|MKXD|95;PR(7N*FikdC_xY8+EIr zOGb>{G*FZM5j1g^+vbRu5o7#6EE;vEW3#Q))7BO&4{rB<#;x(FH5C**a2VJ)=Bx(r zE_b84SI4_o14sZQ{+_oG@-?9wVb~UVsjA9u{fikZ(DdU^S?vuKjSH2Vr3rtlf6!PK zz^jr_MzM`yrK{ny_vkUlAAfp_ZLBI?tycRTa+4#K8_;+Lu=bhw@2ydxpsc9PkI%z_Vjb&3-yuo|JhRP{tQr9ElXus zP(b)WDMCnv9YQXg&_VYCdmu;;ur=02B61!RE9C2sjpu5XusX^yOA4za3O_bH{$@!J zq!##a4u!Ll5Uiw`VTI5ej5$%E1LfUm34c%yYvN|U?mf@vXGibB+9@Ma_z|en2>*Ob zRPIb)7AG83uI)pC@jGP;@;~4gtxDg*oPa51yhe0UfAKW2%A5-uStXvSQdoqr2Uf1c z3BO9>G)H#n{dg%?;yCeLs;{!Cj?1*=e*`{K%W}bt8yQrtOmM_`n|?%s+51mZIkhb5 zf0~vuX-7$)#|kqy12e~oLxB$S;btd&?0e6uDB*uq;8j>fUYL>V^ywcR!OtQ62g`qK zWT!|N8Ne$3WTk;?L{a?p#nb;Z;Y2X0i~P6A!x;2p`ufE=Q>y=r+<)yoov8?09GuZ> ztdJ6eu}>>CURWV;Mq#kRMcV_1-S+PlOz^s_1r`!6t``>$HJxE02^V{rq8?aLgSk!o zAGaaTN@snCFMdD1DEaZcD7`Qn;WICe-#uIC#Vtd5?)0o`7Zy~W{TC0;UWPRPe=s3v z{}qD`_W#O+J?s3p<$oCO7t{YA3^FPf%1h{A)hC=)cb@}A`7_*{6=e~LSoQ_j3sbF{fk{9_; zkZ>N#;P?ND0!;3IXXplOvH1ht&W8Lseez)y!v%Qr68Hzunm-O(vo`$8e8VbG5kDi` z{|HTlvo4pzz4!^MS#&)PbqFu>^PqVNTO4DkFSD?3Fy;*N=KrpQZV!{=`(HUX|C+Zi z76vrgVHP4?;hu-^xifu3oKU|U@ujEpm$Wb@eM!wImfIyo`*&T2R&m(A>1#KToSYV~ z8aQOtNUnqF$5qSS{*!(Lk#_R0*+OF=Kl(M|{oo^q4L;o~zIOG-KRKIi;XD-g>-D^js=;3u&^uqr`!Q!HeYqL+4ya1cjJ_SxSOM$^ennub8&1z8-87 zwF?D@Lc#Y?@Cfws;QVtU@khgv0n0|RG;n9dmyAQsgLj};{?N%Ij(My+UVq$RS zue;FU=bOlKcwI)8Dsfp;U>**16lNGx!+mNdPFvrnFvm6Dq;|op&`jWBFfDq@M$kM) zr1BKCRb5QOec*iY>&W19&=s=_E=jWX_Pt{X1d(BIleB4l?DErWtoLukqHe@rADZ@q zzF($w*LNOMO$D;n*>6nE>aM#W5jtkWBk11?DWf?GP_wE^a_;Z#PurN zthlk+f-Q1%sNr4cN@Nk$pwyQhg+ejd>YTznAeyS)hPH^@j2@-+p|kg z=rnB|^bR!VIp=&Q$IIi~vu&6)5=krngLCp6% zitDU2?!|u(`xES2xL$_VsiS}(-K|5O8G>A#SF*Fx1ib>$<{a!8&1z!xTAWwCfj<&(X#es~4f*&F4WXBGB}4aNS98UB#nJ zGLMzI=0P93hTd=O@gDClVGFP&V)D0l-{|TW-SFq)AA!m}UFmlnG_q)%vZycEd2Kja zR{6JOAT#S#EZgCBtq34E!E}`%3X6=<$>8heMA$1fs=)FvI+@Ce z*TQT)u~BCQ_JU3F)Ep7R{_4i7dN{A)jn4g+Nnbdfp@Kf@Ds;yKHHf-HTcw)hKCl6yQe zDCS{H|5!@hJ!o4z^L?r_qH{-};GB2eyR#gzM++4qNs=&Z6yv@?pCiX@nK5vT@;ESk z**$ytm2=fgB_f#U{*I$4+&3+(-LP!_`t_LkQCwNF$6LDWUU`MEe~s4a?gQd~E9jaM zp4U|nSr!by(;xKpr=S{FfElw89ID&ytR#(q>$_ zTUs33PHErZX_^}2r)jzJUVdOW{uFrlTss1DMxTn5tnxV)?Cr+wD!u!o^)!5B`&^oz{#y9urHC?_#bM@)pV)LbIf(+!pzBh4}&#}T)N;W^?@H7Rq5j1i%bhV6p} zXRnh?eeYwz>Js_~UP*d6Xath@3_xL(9H4s64;JXadBdni^AU!&!YA!yp^vCiVEDXM`plx`s*f`<5@6_eOkVk@fi)Dgl-Pk1CJyX%6R=4k z^F*fn0_W!Rdx~zvCfw`Z?Hp)Zrjd^MDUD?%{ULId19NfDBZ0$vWywM*R@|AMCtt z=5=&eSkA(|6&eoz)S+0ARrh_*ruBC4D}MoPrZVpMqFbcuJ4A zl`)oq8qQCNw@qWbQeE=A5T*Ed_~W-(X~|-3Sq;kPFgV~ip2CfjcJ1&AT|W8MZ=+j{ zi*tR$yqV1_E2uF~U)=oC98#G!V7GtA3!J!zWJcreD|r{kJXOu?c0MI>3jAArZ!v6G z6qFX>Tg10IOQdKaV78;e3Yo)^UW4e=kOJLEmKLPw5gjwtycOPd!`9bwY8Mys{J^i3 zY^Ni@JCmmy&2sA!P8K!0l8PJ75UX%fMyKP^8ukjBgx z4nIuxUK>yZ_qL?*aO0lGYKt{r0WlT*&*sRpA*L2c;WiX;o3eFE4hONYe;5~U+3_}i zi}CF+&0GJQWafi08{mBCrm(_ac{Usm_|3?En|`JcnDV+^{MeZ*dZLtceAr;-ZSkdM zLvPDKHh!0&>+$VBf)Yc`)f3LSD2I4Ag}{E*(oH!2-3)Hbnn?nH1SQv}WmX=$LWqM&`{OxDO>lU8KhC)uSsj zO=r-UdUeYa#sue{RqS56azo?gc9oSa9phKe^0_p!GDiL@zBFF5P<^`BN?jf(QMWPb z9ogl?JGS~0J+R^7xYniLeSKc)>*xt}I?{5=dax@*GaE5+SO{|diStb#;3NN)7Z>Eu zzU2;L zS8x~z_Z??e@QKEi+4@n-eq0sV!N-&LiY{?p^Rl0ZG5JYGZd{t-$dntlCDbTLc_`cX zghj7W$i{MtboxUvW;2!9U$$Lexlb&go129HcoavtFU|=QE?XX>M(gECW8QTR#4OLp zAuW7m8WV{}rx|)B?X}YG3*6*;H|HMdUDJcV<=Zj)?SR-bk8p6>=A{@~&@zvQM_$%C zb5s$u83B{|8<&4eEhcnd5zAGb?B5Kz4z8Ecm?&RA69cbMzkHoN#0tWkv zD@{-kXjXVu4n1$JnK-Ym(QB=VJn5p^ad+Q)5nw7cGdElQVlErM5`G?SFzHv;F$$UC;35fYzsO@koKJ7LzYk$tvb;poV z8sG3$FpM&6@;x?rr7$OU^1J%|&qdiky{;P z#}LSp)RjWq3268P9bB|5kEUIN*U2HYd=9Y|`)`f!$Cm3sh`J8-z9G@xzCdnwALrW+ zU^*vLy-}Y0Kny=llhYZ;+IhWu?9WNI%d9jI8*&RYaFXwJ1?crj8!%m4Pq^gFtK>v; z_fP3cP|Hn`8(RKi#-c9OAM>nUf2rSeWS<&bK-wOxbeOy1UWQ|0pO6b{xf{&u?K?_2 z!CsgR=Akp@27&6=lz`)-EWbOm@nm^hQ_8ep_OW$2>c$%A?nn@8A>`+H^z= zKk4m#)GEsiodn-i-i8BJ<}e;lyFf83AY|)?BVCl@`%32y)`4zRvU0=osc?$fB@HXy|6lFet&?Gh!50-pRl9wmYtW4+$oxYaDGkrTmOosU-D#?1P4TlKxJ zYjBy}W-mY4&y{4KTG*j}md}J7?hT<>C$;hih2I0E|87*j|B@X*L0=DmCvm>TFo_Nv z2OEZjj`I)dlJkLN0aBUW6yt_+o~XONhwUssY!BP%RCe(t)FqVFZEuCqK4w@EA(mzH zfzU`Z_(0(?+Wi@t?VkAdZ~3^$9&B<=w(LR|Jm#Q5^pn zqW^i9fk2;uoKIJun4-YdvXo`^W8>nr&xNMmt)anI-X-P@CmA0U7z{XkB>yg2uzySz zWjKW`@D}oiI?SrPW|Nq)awq~3pBiuZ4bp81I6Iiu1~2Pp0v$6S8Xe!Cp>fs)qTNpR zT)d1vJ2_+SU6b1*y1j$&y&Mn7N5P;bt9JFRiW~fFX>6PP;*9-+B0u2vy({emX9QmY zg=xXQoOvf)S*a!L1lxJ*QTh3Ai=_1c>2gaj*bgNZMW;^rA8~d$va0nUt9RWtQ`Dw1 zEWms@s@_9bx3{2o+4*O9Z54E#*N}{<-u)VH@?YgfR?dnX_v^wXzDJce(TbyZ4QS8SdrrC_LL$kJG=cd*5;W`s-VMHL_D8dwXsR;q^Y;_K)3psBS;6ylr+ z;&eB^+M*IfUMs&rD4J11;7SY_yV2Xz*($wpGV(2&4REr-`OOxtl2)s#U%vF`2H}C@ zk4|rg#?JNILdSB z-ba`w0f`me2=mFz<8Dm|G-=8LR5AKXhl6K|>D4^T8+0;vEjgc238!h;3~`89 zx#i{Y^65hJdHQExAC%*~=f%6H&*h}yaK=gZJZ=;DysB0cXWU+DO#O2Zm^c4bbczeF zo1SQHzYx*&Z(u9X4sD%9>~oCb)BIyu%;%C(rB?-}V-L5f8zUk+dw$S+yp*wtgV*`S z?<0f~BPtv&DeNY1o4eg(6UaPBHc^UBoMkv@Y629Pauv^Y#Kjb-&}p%eorPnQn6x&< zQF-DJI;Bv>hfE=*DIYmt)w=7JFhmF7X+%D82-oZ)(cmESXJ*|m=XddYiXZZ^DQKkd*AOWD9~Ec;nssYi}5+!`*75Z-yD+3o}G5g^LO!=yR-%E4`10&n)OUv*^jd+D+HHVO0m6og@f5Ad%8#<92IS{o84 zs}ob6$s0YUJjZMr1{0j5&qqSYzAG{!c}gY=enKn&hK(+5Z4BD7JlxB8{bm*G+*Xf` zaj(!S);rXt&pYv2nkRiW?#7L69<&^`tP{wWHvE^5r`l`ye1~ZHtJ4{nBS;C6_vW=F#kN*3k$H8RpHaV_}(~KvS>N} zpeQ1*rD|uebM$7h+4|CCvEtQ%>LZR!gCw3BHR_-5m;>6_vq37ho49mBjuDEZKAlf- z+1xKT4XQ60{8PIMYZVkGx*fH(42)&N!|BV|%EpR`^V9CunVBleb_$6Z(>we;zw?PQ zEs={sN9L7bcWT4J@#Le=cV@M|7MfOz5^N04e2gb^1^o!=lqmKFsa3<5m!M)+vlP^t z-?$a~;*5NHLQOW`I`+D?$$gB1SVl<==!qN;@dg}FO`1VGqP(;8wUv|iV^24_G57}| z@fbhl7d+>ks&NcGmCWxdM?G%4=6bjk<_8WgNHP~EzbMrIa-Ks^>?3DntgWRgs~j{L zi#Wv>&m3=PaAHhzV&tu{yeh@@J&al*?xvz+7!Hqc8h|XJMT(NEgNE(t z9}E;&an$5-)u*FY%#|K7B%mWh3!+odi*3B}eShgs`o9BwUJgVB{eL!2*>+Cj&uh7q zvE=YxsWK5nuc{&EF$v&C?m0tx_Y@Q+`qBef24Yx}N9zxwU;mYS^}Vc3Fu?XkP3z@( zhd{Bozylxhry#7yjv+x=gt6EOeFqitN1wiC(1WHk=Xs6JT9y*D&JLT|7G!7CRGl2% zLzd3SbApa3&fXyB7(RG&1B#FC%>@g%#80;JZ$5HQJ<`8pjOb_BTlS7lt_;j@RE{ZJ z)>2+|dU-`;kSOo2K_;+nuA$GiybxE-*0CaMzUeK|f<<0@{?1pN8HERIV$B`(F`PO41VniNza z*{#98AZU=lU*2hF8=WL&N%)f3Ye&U2WwVK2{NF?TXNt?YVDr~R`*G5q z7D#YQwzX;k?f|k`>os)oqpW(~{<@*4QfCu-K6h{B0t;cV?7gl%KSJxhU~|D3#Y;R8 z9^!aPQiDzOZD?N!hVGdI!^C>$NFhS@3}WVJdJ@;1%D!WIpAE(TDVPmLg)NpIC*$8( zxqQUXlUcHt4Y9IkXfq=s0^f+T#*<1q3C|I?Ho-&|BGkr;{T+yXj*CUbX3R57quCoy ztPgPYlc>jeLz`Dx`cFa@ymlwoXxT93zvjLPe=4%c&ArnGPPE=>*Ksa+h+O$StR~?j zXHRzHKE%)w^6aY>jUN)T=ouxklNMJDeYbYIZ{%ER^*bCUS!Ar+;AYBaUk$xKJk*+MHr=5{ zRJN@>%}ffq@y>tB_PrI{Unz2m*ggK;f~FSXt>HhoN1HQ^zq{PvnJ|#S;fV{($X)zE zPzY+FSQBh^FF?!M|5EHHmA$~watFi1@hHLw?)-_Yedo1;iQb?%(Kha>(=k$u8ZGLA zRfK3AB&n+PeOD<5bS4J|VJpKx)dfZB*d?`_X#{V}^-7FobphtI)gq^icl6cxD|Ln) z`JS1UWP6pK9Fu*enI(Bn8N;@I2#gn1R^i&~XB})x3b}@r{KnsHSK6YyQyf8yz-SC2 z>YWdb&|YUo(04RF@dh5{PYT*uXnHgW(=a5tD9fBpoT+cD6)kjCI$Ifu8TmFaZ9did z<@xpcw9W^(&0pjfx)UDzmCkK8pWhmIn@5iH#!WP+f`xzJeVw=bLdWEsx&nO?u1pdx z>Qs{|kq-5P8-tj&_?m*5WrZ_?WH_g?@fanbJ3>5~SJ`A-ulM#1XwZJPLB#Y}?d=>J zTVsIOJBL9kojk`YT%0juzO5>b{z8N$&am#=5Bx z9eaip8}T-U8Nzuj>QG@*sq9*6mO{*HykR?YkQF!xsyn_HdSFHR|;`6?E81VJ-M4EDf((Lg{9@cZNe5gm z!K!I?h+|?iMOraty>}KkM8mT(ySW|k)trGj&OK{jtFQaU`D%~t zPgEql8m2TE!5iZ*5Fc>Q)nx;<6#^|r1TprIG<=?cCr>ONMoP+mZpDX0f|O_%>JOUA z^W-uyzvswx8uDU=>yE`gTJ_9>t*lk^t={Ku1=ywiP{l2ISN%qi?(5Ns_$_Gb7l7T{1fLCgJ#3tSLJzMVk6U9a?d ze}l=!ceVUq9DpuhXW?!gQ;wtWoyaoZIcRn6AFvWewAVYt78^oWLjdm!L#v^(`dpsy zd*)A`;pIi%J8oECaCbXs9^4lg`$E(Sx?4xhf>M<0P#?8kC^O&P>Y*LiUBc2=*4v5f z5agQ}Tk2$6YNLk*XoOeTP*Er5ZojgcnWBB3M>k!3zChRs2qb75$h97eW8kyjP@J1q z3P)h8y1n{7O{W9Jn4lj-P!XJck^J^4>eXHX6E**8f|Ruysy{6&RfK;G+o=5pOHm(Q zC_oHIUMuj*zaYH3O|ePp--g$BI&2XsBz|&ZE?T(wbmC3oW~$*KMV=L(`Q3EA15c2R zy!tThT|ODE1R|%@mb)}^7uw@_c+y;Fy_y9)2J2vL`qxq-Fsn6n?7Mu@w_^_{`q4VS zRJ*G7Zob^;=YIuqqgEFkpvbV|69quw1~j{*==*oZ_@_$$Ejyy9EqXsmY(_I)-TOka zM_X-pMA6sWE7G`kxo=3&Sz(bfkSCdvQ;JI{$TeTR2Sey;dm0QJ7-G5Dt2|_!Ah?%R zp6fojA&!UrutJIpv&~y987FM`8vQrCQzMn$<)xp89M?|1Ih`rUE*GL1S(gQ z_Nh4=OI@y3p&O*p*$Y$y4jLxHqSCrXH`FIXVJw78y2PF4C|e7~LyjZ%nbn+?k&}7J zzhyC+f=ULysrJd8WrFYQrOf&nt1aRaY%DAhilu!6z-TS)V>=QnnX(r~eRMQSw$s#; zF-`R!P6+DVBKW7uYIHA?b=8e07%>tPElSA%N0eF31jZIvr3nIcqUCkH24JkZT>^y1 zT;V>c=p1vj6caD{`TXC=s@JTkaKzijnd@H`LE=7q&` z#DQw^m=Qn%J(ihcuJHQFL7UWxeIkhIK;r@SCN=A+%P8j|M>|*PaF_C{2B0M6boAW- z#-P{rra4*Xz!Hn#WR8-Ge||yx^{};$%}10E0`APKK`iC~29LbO@8mLKu zm`NuZ11b;bw+3F5Jbl|w(zMn;%rFgg?oiHN808>bEWr1DPo`W6)v4-O8xR!1>bn0? zpd80d!vdsX*%>{2rJKyui(u*%ydYO1{uO(|1&C$m@W$P!)b8|+Ex8GW28lrgz!b5s zDb!gle&nyd04|wNXHH&x<||Ekz-K4UXFw-jbi!3%V}YG{Iw^&;4|4-$@5Isvw37$M z=TawsWC54#rZ*-d&N)ss>2^(h!{>Y)`fWs|9Q1}J6&(5346wfYp`=*-faatSwBD)T zz}~bu5fbN_Vj*sH!Wo*VQQVPRm8mF}KkrnnPt7|$czJ^3y$0uwQsLQqhIeXl~j7CT68?7HQp#_BADEQ2Fz zw`*zh>P_;J4*Y1^BKFtJa8Bc(%jYBv7NRdiC<$vL|d@{cX$aWZbzWf+NUO zLpSPft0kbbirrH!^4{|>Bw%(Byr)h2=Vl#M{xFzT+KgxYf@}RE#eX|l+i4~GzG+># z%&vQE`0%;AVta*g!UD$YSBF${aE*=N1&Ym|^7`-S3@xn@d90IqZyx?wjjV^`o~?y? z@0*Hs<#H@&aLIgE+JtCwOSTHXaxN*4OV8Jgp0CsFx~0Yn?bV_iOgrH@+T2L3E}X@- zybR&7Z`0AP*k&+AQey*)*4XY&&)NU>2*hRzD-F{nX9}Mi#^9gB1~#7?o3&RfTG0Y& zm509$`_7)X1-yyIC{7Umt>ThxZ>qwTl04dO9d2BjsXlplZZcVT1bM3h8y?S1L2zwj z(P_iPJ~fNTqVY<5qp7O=aeIp|aN24rL*m{9-2*E@Spx?p`+0eqc)vCBl#vqQ#_rGL zc-flH1HynOvJp6zB8(^gzB`^C(s2j<-jeF=gEEA2_Rk7**Tu6Jd{!n)W1bVKwl|v! z1h{;;#O(j*E64ZOsn#158_tXjCjelv8em{OPd}u?6@F4D*x}${zatn+prRDcLKn&! zQl~ZkwPf2026l|9vsPNY^S{-~f^@>_oMJ48dP<7?@X(WnAI0MfgWQA%SprUb1c zy_M`A6VjUOE!i>m*ZJrjKUgJkg~0DTnei{^6#}!wlB>*Xuz(ep{+QKE>+g%>Z{wdT)<`5Ue{U z2CIwtE1mxPxM-!x=TYx94b=$A6wZqLLIJxN?v5{Mv; zebXv5Mecp38l%OkRC=I$^9b{;IJv#MG$DFltYO!_l~4!D_?@b(ge#w}aW-yb`zkX~ zu(^WQ?YD6p>FyW(r$xJ8%wp(TH7%&-j_DdV4n_KfhmTv4v&6yEN8ZH2jk}QxB0L=P z+n%w;2Z_J&v4d9rv^h9wN0z+q}(y1Qj|-uSC*ksSBD5 z)Ns1_S-C0)ie`U-14eUY&se6$&AxpDUBB>0-INSQ9@lZD5Vj>X~xZzmig{Jwder;7`r)C$Q-mm(j!D7aJ5K|Mo3-G8mG%CT5jLQ6&%{z>}#S& zZ8#&K&9mfVDEGMRG8`R~4g4~+!5SRMhw0+L&u^=WNEYJ`Lv>?WrPFeye%p4hpRW7( zCJF}H+|vH}If-~7zEEXbhV-m3 zUhABh-aJ6?kMTuZRoYcLgYR)TxtoLI0&T_uZH`0b#6`|b1={{kk26B&6nbuDUx!_y zmi^yJ0yY+ZnaswBozA6A|NiaVM@dZSX@?xB;Bw7Z`>cC6ePdg^*q<8zQiW(BW&zIE z2247OTGIfUbvziuw`d8v!h!7W3F%GKv;zGx-mq|}xBnFjuu*0CIntR~54 zezEoH>#&p3o4S-Jc<9$aO>W;RU%)*j&6Gld6lF!4q7|@d%(8Hhsr6Tx_aZs?o2N4x z1c?|VT&M*ZTZxQ)oT8{`P$pvl9kl~^7+Ou+DZ&mbQ?(2@FcIGP2N=egX;wMPJmweBik%aXuD?dJ^YLTtPcob;An==}gZ;H9ZlU zVe$F~ESIgixeu5weG>d7Sg;oVF+;Fozo}yX(}lC>6T2U%XB*w!HT+f|xE0D->j(inDn#QQ9dCaI?D6O3J!&D;q-QqxG%d1b&_9-QU>$ zXxk4?@B{w->HEYfOzsq$Hf&=diTwGZ#P{oPI-ac(B=wmLKivGV>sxc~YtYtrOy%q7 z;nsX!plu8$$UQF3yKG3t3h$!T?5#UDoCRNaGt{~!*MO^aj(h5xLCsHUqCE39UTP`< zCEQp@>4{Ub5NIXIFd_z!#p515GjWSvXKtH`xxm>>E<@hNLdZKgihLn@E!Ufig$WR5*vC-V zpEv^hRlj4J=G`kWA9ktPgSO)K=2zsR8`V<;QhWAX?HjfKS;9oZ3xDES ztbfH_^vRkTUHDmsih2vZoJyDY0=vQJQiBg2vZ^C{Y=~PSC#^LaPvMJ%n`#-?=~&+< z)|AD8dJ$``McBhLg|2o&k%hUooZ?@vI17_=w4)8Z^=B+n%AaEd-BUZc#NQko%TYxD5DyrqEB*y zqSjs^_LI5pH^?hCM$J;Rb|D75#%K?>7c~774SP0&d*Rc7SL+D(uU{Dsp(WC>i7cz_ z_0wipyKJw1g0KgPc-~6?id!{^70=?#o@^RVTQwlooue4B?=kzdYEbdQ!Nw||lr&sn zt;hzhC`fIuZx)6t^d^LksGgH)lJ-`>FDW#;U{CnZ)R7>^a{|>!H0ZgZ#fVZOMAI?_ zrarb(tL|Dg^+{f_z|hp9gkM1*f^%tNAktz&jMqMECT^%9&P7w8G*Qog{m;LgUt}_} z=-ya9_gKEuqRZGLfQOvb^rQNa3Qp_EK0l`Vh?+J4)`=Cg>g=s+E4Kbw^e;N<^`;j! z*Ak8#0&>)1Du?XD>dSq!>3q0*GiZM~g&gy|{9|SFYrZG+jSnG_%k1nsq3MSug6mGa zRHlD66aKDc=9XwP8+KE8+9#iv`DlhU3-*T1)%;A5e1!XY7QnSXKpY!NF}wG-|HZwA z*3Vuav-X{iAorTKAFqx>*p6(G&;YvwIeW0 zM?2WjI+k&Yjf2}#k^K9{?r~JIU!Eu8#9oDm;uYq~a<<|XcGaXK`JIk)s&8<0JNHmQ z;%P35Hgm~oir!kISt&5@?*qkJng|LgtCb$2t`~+xadJ4oub@oS1Um_#Vg-9U2}%#b zID^K`*a*cELLV3GHLmqZj#2!u(=aD?3baf9`-P2S({ACpdQApiupQjGj$J6^1ex2$ z(RzX;jW&bR)SE$T>l|Vkh3YFqUvSt4KXs+*~0&)P1SvIXlPN+pPdFJ0JstYT%(~qPE;1< zO-ikLEEe|pMsYG&S>aSE)6*A+^@3!||E}{rFg&)7Zd}VapA=>WHxxh;szIW?*7_;x zZH1>wuM}EoK)vj9tKMTe6dnMpX`MRgUMGX}tVC(bxR;{5KQ9oTRA>2)(4e2dpdW6@ z;K1YdORFZ_NOjVP;PR$yOXX`Do9x*gv}OKb;mQ24i+JY?$xxT< zn{Tlrf>P60#`FFt*T;SjB(b+*4j|dYpbA!dy1g;jNZjFc#H2Jd3& zSe}wf3jdX9Soj73e{hZ>_y~D)qPJOPPwbehlbGx5u)uc6>l@#EIlwRC8Xn%%&Ey)s zc*3ZZ5=CldPGHYK1y8W-42OHWy@e`J2>h^iJb8EIY#SSr>bT6^F)W{P z>rM5(Xev%x9xbG9p&*B;l1!DYs<#7zG7u3`U0w^djpw5E%?JaL->G@81RyM4Zu-z( zl%LVViw9lV&t^{i_mtuG=R#NIh7{M_M8wf~Z)#v)zSGrM`!qz@IIPZ&{?_Yl_cL-Y zr3^pl1X@qZYLu;NwXg94KJJ(SbzDoA45s0)JyZT*hmYg50G>Np5N);6WM3q3Zd{xZ zJeIvggRkiC*Z+O(gSQ3!>Id&HaS#of9nSelZH6pa9r_}h4miPgm~2b=vqc8tV4Z@Z z_>In)eNEe$;fS-4z+86TGZwbi2L!(i2TQfE6!z2J%L*Ti`p+{lj~fkxO}sfOHy35- zDQtM!5j(5>zBsuR2^1TbH7nZ*zcJP*t;Ofo27KJc{_|YZ9{=Akf_q>TH|=sS zW$E_Fxjza|fKdy-Mp{%S4~Ne~hOHREzE=84EBGW6j_--)gHqT7!VM8Hnx1?h;{^G9 zi9!*SNxMv;$fG*8?3MZmSB*gr^6n8Uj8sP4+*VnQi@DQz>tQh4IrIn`FC)19Z+3-@!|3fJ$J<9d^*-wkFh(GdXroDKIq z$R*WrIs0v5(UUF*vTW5Y2~&b9riwMm>sXeCi9>tq#JB=<)XKwNLa}v5(J-yVj6ZH7 zYJAmseMvqc;P*i~j>S9*GKm>r=%1Hv7SzqWJ@IYTZxx;W%<(+Q7(}DuGR0kHyNDt^ z_?WWPn6hp_o{|;r;GN9mo;gzo+Cy%rL$ByMNR z?j-#?E}SzL#P4C%VBv_P*7a1nZLrt$oRiPg&hv>levSKeLwEE2Nx=EM+)g9$!Dc1L z@H3(1Q6E}bjd{WBu)W+$k&$QOTO>N`c;0S$0an!PerNU(Cf~f;=LQU4Aw*EB^txF4 zCKj9c{g&1F`1h{Xf?gStG>lu^Cow8nedU6_>0!&o?b3CmtM2&AFB5LPQX}h<>r4+9-R-_BYc;?saF3BUZZ%R zNfD~wy?(E*DDA-?5Igr&z8XC`53+CEnuR6i%Dxv990Cdsl})^)>uUb5JuOeTHj9Be zEg5}b*?YGS%186|vzBEA5zxX2D1ufiObwBR3C9vBjT89Ygxx=@-g1C@FA3(8P>i}*{?7Ugo zG-11rU}i*z`w}}^#c}8`xMv)saQnzfyC}(kV>5}d+^J*kD z3Q0{LDA_#c)ZdvOC{P#Ac1v|>uD9S&Ah%q?;RvM=D&>&S+-haAurRxY#}GSztt^>( z^}9V}kmgh7BQ{}lw|9br^g#X7B!}P_!DxG)5=vu8h3t9@s7w$&H+)-VkH3I`)gWcx zw}8k5G>2PPC2+<Gng{gKD5SI^MZ)H05aU)G9tM}=8?P$- z3;TSqAZXVtD!spxDzrP>0*EV+`-Z))M?r7^@xf@N{+Nh<6Ly$FgdOH;37!{a`e}2Y z7vWu+>Iv9A5qB;zBL<-MfiodeU7B6AK>c~0>NR7HDt_O};_0*kT><^#FwYjVtT26N zd59ec@I^ttVHV2&Y%FvoE}5Jet|?Dy-^%2Xx!c}6mbXy<`;P$F(Ex&WU5!p2!}=y2 zm(R%PMs|F3^+s-tne!V?dqM%_bX&`%qhwIqN2Q~DTH7Z1-Lz1B9MNdEVDH|eKKK0_ zs0|Z;l_e3qr4Eac3agO{!jTo{JQVa;WVE*x8Gz#y3W^XOWuvA!iXrl8umRF?Y{HHk zYYuL<2ur(ZwZc7(V~ST@m>v4s@Duc(^KnM_Bt@SW>MzLrHM2D(-Y?&uo0j!x&MOmy z)=#Zx)EIeGM?9Wd4^YBW((7@_?fI}ltiSXm)!W#CaYDDM-VG}f%AT*RptC(Ej;+b# zZD8T#NG18sZ(5#<luiIXv1x3U1fTBus|smp%q@3bormbl)miKCdbX|YkG#ya}!_3DfUe)0`x1moB!^IY7`5L!0@ zb!IR%MDiPyt>(IFFaUFg0))y4G9+-Xfsf*H!u?{!#f2bGC7N*WxM;W6lD10vXo2P6 za>ZakT2=DliKx!trodM;XB!cL^6m+J+QvZX=I+F)Cj*Z}CewH_*ZazWv*L-f&H0$2 zc%`5HSs&6lD2x-gqvW~(-q{f&a(5@AlO7bD@9bjpK#aM%DpDm#UJvSPZTV_{u;NZ> z6ffA&H$!XDT2(OQxz&RW7qW97vyV^tS$)gTs)LD(4tm;hh!a~C6Vp^p44p$?{Ht~Z zpTeCrn4rdE`v!WC_1tP89|QKhZ&cnB)Tf3TzJ6YxY7OHr0fk?Y>!tW5J?{b(W&?1e z@;BYj0&ZW}aR)v~*W$YuVR=6j!9eK*y3&65M}R6dU;m2b;tPN<2V9xZ7uf7-y5zmK zy{kUq3=v2`d>g=6Cn21YGTyE~V!BKEugDLstEZH_PT4XR!xKP8C{1{IPO34;SJ+;I z4F9y`2(v++N03cwBIn{Bs(BCzzL5I&Em6SrUkaITojU~iOCE*yAy^hKhctL60+=KO zRgLB~y4>?*Vu`A-sCQV*J^~RT3W&G6N|mm|Y4%iY?TOVZ_C;=3UWbB&U*edSEPQ4W z>qF3eBBaqW4i@@(4}i>*6EGO*8EInr>z=1n!a)ou+y`P*xMD$-e>wlA{RvC|FFF0c zR_+t+@BE!<^$~90>-sT4DW@{HJwU*dO|7upR{|7K4Inah`-EpB)56E*!58d9OlTPI~O)`x7#9Ruv8&UfCfz(eT-^ z2_&<*lA4VrMRvCj!5XL6R~c!(!9*!68=~a=?tJ&fX+mIp_eXSY-}4u^M|ggzNxS8Pe9y9c&8R&@7PiEx%ox;wA*qPsDHzGGHTFsr1 zuO4ksSnnvIXUy-^q90C0>oFEJes7ajSd!+08Fyim&QxfnUk0pyP?#C(g9ugdB^IFQ zB735A-a?ix5 zHwvd(5CuJoF;6`OjnNv-l)$9;YVE29EMK>enz6MJ+sz5^;Z3oed7B4AT-dKtjj>Lw z*kKXZ5a2l(a3^z1Gl%TGrf?W#iCQj5i)*)=S%Wh>bC1B}mf*zah&f$8ZkOeZ>xuw%FPG`7NzS z^EX{tu)%a%;#djF0XijEiV`2|e2;#7YI6It=O>#`W4z7O-rIo0wP@qOv2X3%=O$ni zfsbvrrzUGiFaIi6NI450dy3~Lo;^i_57*{(*x^KnEs67MEa=Iqi?{FkHC4n*3K+ChZe@zGrz5@D%e;WkZx;NMmEZb2pkn;-jFBaU zL}aw?J<~aUIwkso#^6>BeZlaIDeu*9h%Y;|L4p3g0zLiu=n4f{rkou3xpH_#*N8TL zyDGz3*sEx`R4a0%Qk>f>_gP+czV^siVfNY&2k-g-;$&`bQO8tV^197$3CL{Pgo_G8+p{#{%Ma^ z)+;t)j~3h6QnT&Sc9(O4mQSgBP<(xz!EI37qfXFSjLgKl7+4@-*5j((xaEBNSkIv2fFnJyY+gL^AoB#%t7#(mK<9W z>N9vm2Qsfpr(1F==dnYDdm(ptnq1+;rA&Ts9*@#^K|?ZdM>9A);y$*r|fTP$LYo9=fd z5hTw3C3^!;=#rjayq~m(vt1Q%i(6^ddN?bA?-zRa`Jq}(@?4BgZvuVz8HS? zohPVKb+Eba~01{eZUwjrd!kvcIZ7L-;A>M`^-_srS6P z)7m%>Jn?K^+lPtQcfqU+L(-*7B!19F%?cS2N~lgLS#=ds|KqZREpA zOJ3dw^aZ6$Lo|eY+rcv^_yHQ(in?h|reSK8imF*yZ=4<|`55AE56{X9tPq-FR+W!p z5-T-Pazf_{8N6~r*VdkBZshWj+4DWnSl)0H0Ce7;ESR{y15p+xh{LU-)*2o7Jt}$Rsg;2CgVSPz>mR# zwgw=>skwE%qdE9UcFA7GYAt)?e$l}8BhU=RxrDZhi{-2!dN18_R`Simj8!DN?-HG7 z6_$+5<)%g9UPTS(OLf<=(`i*lXec){bO{o3YHZIMp!TJI&wlol=!ps+DHR{-q3x|XEpx_9PXVo=>vPqrO-n916GHB`9fe2pza3f z^zG`Yq4K;ya{G_T!6>SvO5=syJpYwI9Heelfo^tzw@?I+4$au>_9%o7E`#s*qF1{_~F7!bHv`OxYgoAZ}Vp+nCjC?3v zKGc*X-pY{v1D7bBf0b2MzjriDzTOzb+a{K;5WH+xKfXN;mzMou1i8``RqnnKQoI_` zyGeMZ2>U1Rwiv!qh8cT%9$#bpS$uDSzPDxT`{IMhcP%rTR2e1FBjI4q@wXi%+)5tB z;UknY3)K+uihgduY~4CO03)t0a+ z;|gx8CwJLrbII8B2iqdZ4H4vX&$Efb$8I5x8CBUeW$Eo6{hTHoFTatlCaQS6CN794<= z=~&o_{IrF3RlGhFIZlo1@7flY!YH&_x9og$C}!7Ni3Yu|-|M+xyd{Y%m<{B!PR&GZF2{TR#`pgx1U}LYR8La%1 zc+B6W{c8ho-a+@ z*J8dkaNp-eB1kL5kl;d2@Ss9Rx71NC&oJd*D64<0B!jj8`W33|{fy!8Dzm795?gle}(S@alk z8+$SPU*r?{p!DB=o2(#ph3dbhe<4rCMwAx2pH06?a9~-F`b_L5`R_vU!rQ3JA^f2O zzExpJC~`a{kBvxnm>Cq@^Z(h#P8<8@>c_T=6jcEC)j~&AJ(aNBFNGC$FM&TQ!(TUH(=y@(4HlbA}Pee$zfko+yZ!v))jl_lhcFevGFzsde4=KIP(?G@}Y!=n}LUwZ;rcUaU3ru zxsvPfbOlep#8s!nmDPWuCR^Pm#4rv<)5}i7-GWAsO#IMG5e96i12(>$zH`9S^LYyVOI%k zS++gTCavNx$`-YcwW73)5n49bN&B~X|I@%2l3r^@_q=M0-Zp$4SC=@kA( zDEyTw-5Nv02Wi#kV`sQ+3We@kW;eG;F*tU6VlV;E*yFlOb4cFDbW57AJk%66Wf|c*=5qb=<5r}+qh{=+YVRO9G>gDFzs$K zHOlG@pJ0rF3oF&JAXZUggPA7cDXNcd(wfZka4J}rbREkYbc;V-Jb zTf}yt;-cZP&_I&1jt|hlPJ(i3*6jSA)5X;)Q+F!O*Pr}iYG08|iP{S*@BeI_+h=OM z2apVfGd>4Ma-WEZVK|jVH^g7R&C6idVvd}67&Xx};Jm_tp;t^hgrf<=B_O|KDS}^7 z{OwiGj!Bm78%&5vrV_rcY&!{;>i{_fxcVPr9+{S`wxa8&zjwMHGULs%;$5#^EFm6s z0)wGYmi;2j_wZ&K!EL`dssinrAYw+*}Y z!7kH$UjBQx6wQuhaqI^9L?tfWS6oxQizAQ%QMkY|z)o-JP{PgX-xb@Z@7oa_@WEE= zzPf58+lJiy5<;)7so&G;Z{>=*W@S=4GmC$};sakjyaVKpx!%Q|{ceZVZQ9D3?~0{{Zm=5(y|E) zqw^=+Q~WwCI;LATbEDloTswAGxsk=KXvOK4c@86wJgsdEC9DM6f>xxWO{wJiCYZXo zLOj-{^8QpY^>=0F7r~>SCEGHy@|qV8D^ZY>#C>6`e^&3TiBUD)#VgGG5*}2LZ@pDQ zb2Iz^wi~CIi9_xAP$^KonjC5n2mI~Qd6m}!;I_kk}l_ zwIv-ySDVXmfH1h1wa^B3Hu<>FHrW{HW1Pawl~IcOwXEq z*f>F`l-Z_^Xj9iY5rR?88kVNQyE-EFvU!_ z_tDQQ_j0t2dAb+NFe_2Cs!-gX8$$McgIA3${kZ*J7=7{1Z#!XIhR9mb+N$Bi&bHq_ z$FXMBQ)bosupncyAfx$2lz_?Qgu#Kn^g^%XqH)cdN(UzbSvc(wn>9D&z$p?L#?d27 z;d@x8=P?Y(atCCcA_5u{VN(O#4oR>JHWLeuRX_Hytj(@}LVEf!x$FWgX#Z&OYrEj} z7wmUIUymU1v&N6#Rv-|*>khI5{0_$_R??B^Iyt6O6Vu$#!IBl98gc5TI1yuR7mT@QpHpFS&u|o`yDO{c@{Lr&XVOv4B zIRWM7txH}qk$Q)g(Q1SNBOJ0kK}-#oSyrla44|z4Qaw4fjm_(PyHxEX#tgyjkOQ*zcGee!Da{B{tRr7N~hGa15LFDYYW! zS>q_64^KH%MPv+6pK#&%Qp%rjEe+c}ElkayIAH*^BcJsZ zfG?%xdX@1hBhT@3mbVjo(dQ`6w^5u;(=fVrM1JE5tje_??E_m}sQSQk;*BCT+eg~E zrRA)vF|cOk7q~;dFZL`D_3j<&H*}>dw{P4=tv}ZNguD?pSczEO7e?)14~&h{ngbq) z|B&K_XZ4}n>cayRV5NkOVX`3F{)DY>aqOiiE!(o7nm2Q!H=EJ{Q7fPnnJj9o|YWM`LVUud{8)U;O9^&FNKqX z-QR=1V1vKfEjWd*XW4cNqQvYDehsMy#N;QrLA5$g-(7YCMtMYUSU>*eW47g+*1HP^ z;j5)V8V5>@>fBj`d4=L`1|Uzb|elS!ZG>#=@ z?3q?!o{i%cO~xLXWjJ$AVe-g#)|?G>+;H%^0s9H+>th5dds=J7KW#Ynoww9kBKRLg zK4i>=#dToD^qM8`Q74*zez5(W*X+5Gni&Jgc9MwXeAdiHNPcohLMx?gmkY{GWz3Q`dr4pF=`KfiIVJ z%!DC;IIVAxvgXWfZq#eha5}F54tZD8ay0t_!!=*gka#^!gd3@FJ=F&^uW%D2H;mBZ z?Q`#!ZX*x}ff7MlEr&C_7ffGm6RZSSzHX_fM&)t!XHjcu>WG$<(QD~kcT7c=>sYgd zQ=R?B4Gf;8>7*OZ8CTd4fSd~?a%jK9f8ZnYknt_Kj;x2z69z^yhM?qqrhzQl0V4SW z(MwwQdPlw)(x+5C{oy_RizSa{n!~chJvKW&E|!H`XGQ#%MKD_W#AAo8F9aq$<0C9k{D4D3oh*5>05Ne@JfrZ~iVAaq9n~ zM}?-H%J)^oi6@WS4Q@-Gj4;J5=Pn|V1bnVv?1y@NK0~Fin|t`^O!5t%l5Y{scKQES z4f^2wGGO@-hsUUB&@~BF*!G_`biM8Ov#$L2MBj+lEa{KN$3NBxJk z{g$-^ny}-C3?wh{HXx=^Ws}dWIU;G`S>FNxUiYmGO)Z0IFm)YTvk*FcFwR#yaor;( z=^;(-3oD00wcj8cK`RwgTZssCL6yQTeM+}1=fe3%y35*?Aj*XiFaLoS0G^HW+n;Qi z*ACBvFi9OT_3u@InkwOgn@7Jf`5lp0)L2_0MQV$=uWqpAj%G@+3uG0e4sm;~$=wq) zA4E#Sml7RVu|pp9jaF5Zyl|nsl61Pch{=}uuQ!(YktaMzg$Q(gmBNEqxQ$XTe=^*L zXZ6*6De;wBi_Kb7&)DL**Bf|SbPE|T( zB=GtKc;yWZt0~7bU5}y1>~{>%h^90LCX%{wxZj=#%K5kmIBV_xM36EZx;n+US)^R@ zD%6tO4&VP~u$Nx@v1&}q{~nCU!#ZS`%L}?&KdQLlWxD?B5!5tf2V^NdxD}%sID`dw z&TCqugl#2tl*2K6zt>>Tc!;ooSMvZD(>`;EstOkXj@%OH3Sru1nyGHvkLs&mS;d;x z^riC3xzn*(^Z=D-={Wo?qz^kZDTu9tO`T$y9B`~M&0g`WN(^jSTYB&hZe1|VS#X5? zk_#3{nGdX3$RI&ZK2<0`EIyzjWt2~w*V{?ut9o^}*ehrAz(X?Vnwt0g)=%>q%nBRK z5ObkbeQ@uNFV~Mh9-3v2fs)3gS@Qoz?@4PnFY0YdnXj7*yVZOpvZi>o4Q=1SvMN|& z$crEe%uDH>f3UmmntVkw5WC-G;ivou9+vY}bQB zd;AVtsn|q?d_qJKS_67uy3R~+79A4AixnM#64jZF@)Ik@Sd7*jHrSYoo`h=x!bb^V z`nm52Dc;tAR!nd@X*C&Cz6jU#DVpQ&qDP zWct`rPm!P67SCdus6!?gN75+QCK|SXBsQ9)>A-;dF6#aYu9O7gcVGyK#s-aP$yyO# zM^%`sY(ACknfYd}DUIj4Rp_}|bv6TT0E4ekT8PtwhUdaI0zTT;3)3}y+D?Bzf5{&r zO!0lbd!S#_<}2*;ZdtmAa`2e|A~-N_Is@~e<1?bzEe-ohuQF!u#edCjo#D@>whTOQ zk&77^uMTk8Dk;@m6yd&Gl6)Z*2MNx`oAC5fAXgcsK}BE3^g zR9bDAM0=QII{i&ONA+T9%r>E;H_+my1sJU3@ZU%l=2HiyTeL3UsA^v&A^>KYH^g}7 zURvlZtFXMw{K+l)&6G;VVc3FJw1N$Lxn#Kqv;<0NtW|UBU za>ko-`qAXn>uE+brAR_s^1>3~*AjJ_iL+@fNtZ}d^h;`v*eXujD%Qi~w)GWBrrG*E z9i$|2&ASzkA`57xHnc{Yt{6NJTn|~3^!j?SU8khKzNr|b`_SA1r(uCJB&DC z8qV(uKREETI4lP+=gd4}#0cMLAn~A~&fX&&w%^_N_2tUi$C}E_CMBxeh#~i3l|=@44N3#S zartG&BTau#s^sXlr|I$h?amFGv6EU}@zjtIe%?!Ir6Ckqt5)7w^b@I10%&!@R8_u} zh71=9ix4@k9_g4o|JqG)HenZGWSHF@+cBYy*#Fe(W%?;C&5nk?CPeipDOje=u)RHV zY*IrB{5LDOd|;8#>p*%KKx=p&%N3x1>Y@Y_&BAuZP76@;hTW=t$a!l$O9NrBMeI}~ zpzakRcIK^UE1G3w&5J`mwSVDX^76KjMr%&W?RrwHJOHxZCRZ zChPkwcv>QAGOE7Por%B}(X8QEN&KnsR=S|oo!J_-HgLsD;tLy1y^Yn|ttPQI6*Pu> zBf+j`6<71XA&e`Tb~txf9+5T(r2* z=jfj(dn1c~64@_OyG~rE22Xa!e5JR0(WeupRfZ)Bgz<4QUz8PbV?p-$t#L&X zPZ(!2Nnsm5jbB#8LQ&dHg{B*it^?Ka405Q>sx3#?DR*#+WL{6+d!kFr_NM&OXG1i1 z9D-lE@fd`3c2TGorht(s!a19Fi@A?(zKRcN{j3xpiq2{MgVEB`+#<-?46*f#vPGM^ z$n#BTtJl>G50i6cUEU76ye;o67hTsHY&_*<;k4hr)ielgJ2@EfyfCpWaoB2HFhi)X zl@2v^UzzbhInaT-c4q$b>(Nm&5iu3{77o^C`Bat$9&Ea-8NTDImD6{jWf3?`Klo_* z=Izi}xMtQ|^Uj?jiOy~V3RHjBI3_7;xbLfN+jreHaok+lp;%AV23MhJ&Bv~ffD7@y z)LuA)lutXseuMD?KUGc3&X-)rf?k%TitB#eTWnkKXdaAzz$kDcU)4oq=@M-%%G}WE z=71qNMSB;v3sOFua3YckxfI>c4y|cMs}8LbD-~=mthry_ z<}W`<7R}7oFl%WjwN5!`%nx-a`H{K9#dCVw!-fQ9SQ}_%TCS}-5cG;EbQt_gOkVT- ziY-%{XcSMpRNMJ{*bVrDiaf_Rb*1Bem+ed67ZslsTXu=cNcLRxSAK zHPNupK4du%(bew%0~B82^9K+Lm};+a$xC>-VQG}M-m)3eoi}c;7vxeAe0px4un5EG zFkIJ{canZc2}WHaluXWJ&&)W3pI#yY%720P+p#xUdXYvScF#WO&;XjL9D^zojody9 zm?OA07YsaH5^F25piL-bc&M%?stXd+P5T@RM-_)ARETSp>V1qP3vpJ++b^q`J`~z{ z0%@G>DFlj_G-1d)DS>%{R<%fA^F1^7mP=3|*4W__+-EQ_naB`4Wthqsr12RYc`YdT z*lE%DdAE_tdXvRdtUK}`%$HvLOG&uC1NOuMPkE zgn9F95Ft+pl}=9SYml($5X`PokMtT`B$XA8`Y*@t z^dG%G^faaI6#=aWOU>WcX>vpVq?_|q7 zAV)IlBPhu5bR~MaIjxn0++WAJC@;dn4n$)VUcX2)V8T447ItJOu?}OKEZ)(`i2YO} zVr}sX*OH3&R(G<{>PAADXy0xraO!ire-#gBF6==fAYX!~G5&DTiO6qXqX_r{OKXjGk+w9 z+igbBG`pBqQzxRI@XW=K_r5b5bM zDO?2cY)o(E)#Cl^Z!*_R(5BCK zJ~xqw+~U_);ULKCQ(iSYVE6L z@_)9j>o(0Kf_Erwg-)r*y-Cr5V+H>_&3nKB4I%sWfmp{U zW>qC5ly$qD-}|biIX&e8yjKRIW?5^40pH)7?ZP+^KSIf8KiU-rT7GhNJ-F-Q)1=StGUOMUe zRc)mqs>eG$tBM{>j^A~tNv_ub4dlgG@91$YNwJDcF`2@Np=0nd@@ob++@_h+* zXY-ee8C11GMnmh_!@EbXdn#CTP=CW8B^jQhzx?q&|I=pqBbWDbXLMt91t^D+QO97lrNZ@2U+764p?FzdE#WEq)?g-Z=&C=Aj*5GHd=NM# zZeYfor#~}Qz9b-%c@-~cT&xLI5!lLwZZXnYX=-5qy=nSUJ6iQH668-e*-RinDlz*) zxjA+Nm!NDzBU%j2PWeE{E#4F!@0>s2n9S&+Pay{i*G^jprgA&*f*gTFElXu&42SmLnRWdpa z3_Em%$B^FrzU6vIuh}*bFq~EqH@FOuk@Q z8a&Z`H~B8lCzQ9qWRb`-(H$Ft99W|So-Y(PZ^)#g*)3AMoV5>HT##~$Be|aH2qrl& zV+Z8qHtohe1RFWC&+o4O*o zKU{qnhjE}Es{bnpz0 zdm2{SeTg{?ju4Kedz41^NT|z8CSP1FEdE;_0=Nu1?K(V9QSE%%B@YIsUx2TM_-P;% zxC)s@5PFUuSh+aA)Z9EL+wopJz&mn(Ph!!DQ$JqGOKDw*I28|?pl)t0CF&d%^~O`n}O5 z24tJ1RJ&jHU?ak2S?BM7PT1whN+S=zGPCm#9fV9=?akgdyn#2~d%uPP*HI)-jg?^| zFp6U&%-n7!#?AYkk#N|R&?htUy(v>43g7_KkkaQge{nxUt=D%Q$I`aGDiCQMt%N>A z(RBbIgR)ZU+@d0K$|3T0m3psO_P;6EeNXlOm}{3r6C8*!w-OFJ4UALULh;k7!ca#6cp5o z6x5(@Ls)&SbO%@JZuw((`fg3->ajCVZN}I(w+s-8A&k5BT^d0qowGvQJ$D$DUy-Dh z;w}Bu$ntRa7`G@PX5~1Hjgp?g_p;1Z|A(qkXZ$Vcy9;IL8Z?cUHi^Wk{dC16PE{+F zC;WvfRw~HpB)5!-$>}m7?WtRZUu9<16YK4PMky@~LlQ0!yfkR$)owPb3tHvp^uwS{ zY>-iL{AofzA9F%{@3K~gCQsoo@S++W!=)s`#D7D7*L2&YCrXPGv_i1lv#~W7#8AKI zGj_x=TybWo$(7C;y8Zc8s(d+7FYG}zH=Q#0b0)R=2W}65`E5BscE26>P~X;xL*8Ii z>{XVC^ATIaMa)oX!O_Nsq+j3uD>vA?YVjPB6B0c;^uV<4L0f_NR!RINRvbh00k%+q zZ&}h}jO>f8vG;r;U>=A+X)7^_2rI|Je=5F00)z=+2TkIHa>P?Iz`IV2q~)t2bvp$U z1|+!oi5?S9Zv?F`A8d~Xhx`tXR8wDeJ$xhXD|d$cBs|mrkrh`pR+*WMtn5B}}!pErMV^B{@P+R3>A+85dSp?A?jx(_vg+4uHBGdyO7tHLBA`1 z$P@)2Sb3%jAB+Obd3t;DE8+AeVol47xO9*PB!rS%tlg$OoAY?@&O?M(0iLvrT-em5 z_xEuO!^!J7YF}NtWdF8~5D?}wRKB1q2tO?rZW=+;7{SS( z+JD8QrDfv)JcmoK_ilwoe8Uuc+-m-YVE`l@YZCq&4qfax$~2%+N#S7DFForZ2Wwe9 zlY}u@e^?r&VW{XQU-fMO+E3B%3#$!d4juG*p9-LJFh%K?=_)Db$R+v zC1znT<%~n*iNR3?=T1i@WEh^V2_5}cZ)Kr&?445tOtZfeXsIzR@zBZv!%fLolAvDQ z)iFTw%;dxhRY1G5f#1CILo49PR%QHU*}hMJBE2;(Mb9l1*4V1k*t(bYeNn1IP+N^m z5&THeFt^-yb#_Y*J3^QAT)N4CnD1>7mjTj%A_lSp8IPBVRu{uwnw${yk*n3U)%+wA zf}vv;KA^oz0j6k}k$UjkyLKkxH0f=Y_k{%B=;^XmJQ}dWrA#=)y)&{{BXO@elbE>* z9A5adm$XH4h!DTvlv=^}fw?5@Ozo@{HH%$Bfxj&5{0HPPk;=l7sJdFw!je;s<8b_r zuf5#iI6PGc$WZH4P#;toZ^j$HE_CyKjX6jom7`a0U+*c$*&@N!zWk}#LrUHFvbOgE ztHt*AXhL`7`)#!QjnRIgdz?-T;gIaz^$j;Brr*P<)ulXMLe`F34qt`TUMh36GHd-d zXz!&)Uu-w8?WgoHwHvO@cG9UEGHU4!`_Fr~$n+8&w-QJ&8&${am+w3D%F?Kd5wmlD zP5tsKbT#o-Valz-eXvY+_EjC9s_E+3_Pp3h-XMi@AJL~(_ep~i1Z2@z*zmRu=+jE7f_6~F8*x;uqf2(yi*!uEiwAC2vR#$*HBfN z|8UX;PlQj=yA}JY^C+)wMTSd|K7XZMDhm*+K%Xa_XFhRdDr-)Z#!}zSc_iZ+vTPE-{A} zO|=Cctj~gWE)KH1El?=65lvRRbOs1n>9IZBua17nn<-2^NzTmMrTbTQ%)_ zS?_JFCq38MLn}>BIdSV&?fCtqiPsNV7Ga$4mtVIzm&V{-cHO2}JyPAZbryi&si)p* zqad`imN1%WJ6e<$>n>>6-Eg|XHh5ZC0cA03fOp>tM6c&9EEO&+%}sDhXOJmgWPhU8 zO&uO3C*Dg4yZSkDW=RYpIJS&?H#8RF35{3>Yw3=bzy+atg3usdIY@|v+K;xMZf$#+ zK$!sTaofWm>QRU9MW+%)5z1%UCBJn5y4D%b!HOH%(9qgY1---)sEgZ|s7`Jv^K>uz z(p<>9Q7P&sf)r#3oy5ebqIgpueXl14s7NJ0w?)L4rZ^1Vr%GD)Mdqcrc4j>C<p?X~@8j_;@@(i!410&VL}{Wh z2IyjZCVc2ZNQ`&iMu98!h9`mFeD$^`N>W4*IGMv5dR(LZ?z(^q#9~VOR*Y#C1i?^Yv=cq7XtR?2%XRgX`y{Tm(v zC}+7C9`aBoUDC>>xc>20hKv+BI_DMt81Zoe-pxtdl}n;+9pYga4KaKIPw!+}Z{qjoZ`yk#ss5Hz zU&P2{@zPdhti`Ny{VJ;U2G&lW&zV0Ip?)N?QEC0w{z~EZ!$7ctS%iYw<=Y9&Jrwz_ zz{m`-hp^?kv6LPGn8@Jow5FsWEc6?t!g*B#zQ04?0*%5synFOEy{sOwBWRIM#kG8~aMK8fdZRK4W zL#_A%OR;-@Z+r!hgJk9M<+3Kz_IyG>R0?mR}Yr_ih^T+XR@(Mh)JBv>P60TS%nsZ#p=?>L`O2;g-7a1 zQW&0p?I+JyT_}6p=3hQK3TBVEdpd0XM}4~ev530f4#yVFt(H6XbkVP)aPe_$ukuvs zn%Ve10VAobC9RMAche|AW&=6G(_=kt#dkr=CG}+R?@_I@N>`~eY7>kZHl?q4Pu;cP zlW`X2N!2_`8Y%^Bg}Xve7NtZ%6*)lQAHNzxk1Ci%OZHFQ-TCa9Med(MI zyIhsMIYbhWb>+gldznTFIZ2*s%M*R9-M(c51IZGNL}Tt5b=5r6=Zl%D&fQ>scT;UM z@-rUk4}vhTrDX%GVF#lO3i`xl$R)feA^gR$;4}4~IWKDviF`IyzX=FGFMa!2MBs2A zIpqq5wPY`ck4}n~S?f~m$=oM=s!FI(vP23bELq&#u8x@lIelAXFPl=qAZ}Q%TI73;4 z*>A7@2As|It-YA#WG-zs!@STPC}~ZvbRWaj^i0uXuT@yTyK%oeXHdcpRF7}^JrD~z z9QKSj+*WbPP;m+TSVj-@A<0lDd&f%Ci$8tGN>;sJra)q3BOX~m3)Z#xGMXxynM|*7 zFEJlO?UHBq!@YA|?wRswDhA?8$Eg`>QmDkOb3mAjPhQQG!4T?s2u)+>}6V*ny~+e7+i8$)m`f z9))RYa91p`h43mz3Av&Z%XuWzwY)Zh_#`>slpn@(HwvcbA)Pa)JbFzm_{?(Zy30N8 zHI|XTmRR)DEdmj*2i)2$#BeRViLq%tE!l2O{8H|Cj`-;DRxrI17M>^z!)YkHg$m@YfAgl56f96e`{7s}7^P3Sv$O7ve~GNTesH z`h}aJ>1}~#3GUXNB#55a>pYv8Fbo|j#!b?zMG`AyWZwV|Jp7HkCKE3rJ3KD85RAc# zTTV141S9|M@*%{-2@m-_5%lRH1n!MDG5@f+RqSaJ>87l7VdUT}YT+#xc^VhFUX8i} zS}mOp9V$4rXR5Q{IK0PW9?JPC#8_TaO!F|1Rz@gWeVQ`*Q!xln_hB`drv8R^m zJ2-gU+Z!K?pOHY&R1(5%-}kA-Ko3{e^*JaN@sf1G%#a+%V325XFt+n2vQiEqIRZ)u zOt&YZ(i!^j!S9PU84Xm99Q4AU%i1}|POKjx*544$$l)?Z8C014-2ZiLzB5BfR&P+f zQ^E(K-D}hJv&)4r^2kHsr?su05d1s<`yw~*aAeGH8bvmzFr>NX_z#|D^XG+um$-tuU5rr>b~0S zP5m80C;-%5S7S#HGMWFmdzS#RIgCl1Y)PCX$Af7+FYVwa7s*PRRKOn%nS`+>%JLP5 zGOsQHrbp}Wz1DD#1($vMtYQ7uFxGTM`Qc?8pWs6wL{OfdjqF88y{quJJKo9M^uB=8 zlB1nCLFUlt3WsQSUNxN^S1-2OamB`Km5_!^2|Fl%1){oI+8h(mep06Mq)aWmT&dog z={odYd*Z$JHHVKLLH&60IjN7e)Kqd(*LW|w@?$5ctShV6IFj#nC2%rHRi4I*j>DpW~VG~kz>a81-~a> zj=_%^4`K4$fp#nPP$8tzu(Y@xTBTExlpWfqRaC2tG^5Y3*I(F^?0)Mx5s@Tv{u!}o zMa3U{?$zdd0FSkNMq3x2kpGYt(iLIAIFm-O)A?G8TEc&%17~6wAK}-R_QfvFT>#e^ z;^w;30&^J1F-Wtc>ct`*qw~`G8?D`(Gp-sxp0bxW;7`g-06V zkc*Q&G-C8|fPjkvG+P& zNOZEw^89Iamz-260Mp66Srg_+<<}gkkeY~^L6E0Q*Rw|S9*Ix}=Y#pa)}0vnhGVXQD>OJw9xC<3 zLrdnq($L&vTW6J_Ii)lK#7=$w@6fv>1|ttCKaxo)c%?p;P*d?r#SdMN*%PkeYG$f+ zTJp1FFV&*a$^96z-Dpv?8=a15sSR1x_^3o)F*;YLZi3U;5MsgRiq5lTp7; zqjgG85gs}(C}@T)vB!&aR}}c}9+zl@N1e&3G|m5R{f08l8`Cl-y%7D@8Z`WGPDI$g zE8wgcAE;jnTZ>VsAH*#uN&l-?d66u_zK^mbyT@LCYGg_x>59W>$xaj}VzhQm_ve8T z)@uL8tPGv<8ZuHr7`I01bNBVN+13TUr!hW{5#=@WgSkveyLCB1hqNh+(^F2EfColaJa%!jq=HKdvV2MJd29J_6{*(Q$Zhu}1J zKEf30aE`Xax?i91O{Y7Eys!MKT_BiQ({0BRVa3x`0)s<5t_!k5rwtZPvOj52f1oak zCwDZh&%a`Vj_!UV+28p!)b>YB%jq2qufHV3N(Zl$onbv&2vu7&V0e^*7Fsmc_hw(O z;S8N&>|*hDy9U@VKGxK$hLqQTw*M|rangGq4{uxi1=4$ePT&+rBt<9{bJ~FhsqQLR zX;8c)4_}=Fy`yJ+&pA0u&M1I>90yTJf%KX79qRZ0rQX3^oXjAF*d0K3L4vs|JFCcj z%%kz8m!K8)y~{9Ne>|($yA=yn6kR_y%2|uV@Gh+4F-GsT0mQ+~`O7?)U)6J&)>;4Zm z7q^ssB6i*K7KEnBQ1pPIbp?<_Ie1bQX%80}z4A3>V#KMf=Pt?p8qRd}2m7{<@4bzDInxSeWvODk(b zgWYeeF_+kHlJ{t%E62k^t4UJXqAuU@xl49_zls=u_l+{a3E`@aU$bbpkmjp6-R#)G zuj}JXkBG{6At3w@gkj%0KbOQk99Ozm8aECTF6el&#yERPV~1?wl$@VQ7ovvL+{ zqJxuyes9s?O8qn%F-}cq68453?DI=Wl^{)T@tS)Ya6xj=*Hm|~odLvsy#KBg>|B$g ztrq8#zr1d8@x$aIaZJW0@Kl+V)}NL33VXb>u_M>`L3;9DNjqKk&}hIRTfR$Z%mdap z1#etoavl${(c*sS_?*MRpM?aRq@G*jwx-NqE|oeZyvqv`tV6aMqEW=wotG?rUtiR! z7+LUFcEKWQ%uyK2d^*H%pGswP@V{w_8DibYJth*}dJ+o3~bbsJznNs+67!f_w`>N)U1J^%D2DYEDgMN*mXqt4%T`o-u%4=gDIiriRN;cQ9McY3d@~;h*?^EG& zPX@_%S7ldU6QtpJW!F9vYtAFGN++IY9c|ITc&KAM22rEi8U4Ku)+Y!+y15`@e`chX z+K-Z4>Ulf0aksd*SdP;VPJ%YKzV*Z3gBSsQ)Fy^`k3ZFW8|-a(5DfZ*nD~QqP?+%2 zU&w7~_$Qvi1#4{15ncQ~IWsWQtJx@m9K2({6m8_QXTPL5|54ipQ|!#$w@tU=`JjJ$ zZoh8%013%1K1XFq$%(aV-dR&%6@#e`A?L@a^rJ2V(LuS(@JsTv-*aRmK|Dk& z6cL}{Zr?pEcoB1yu$d>Y8Ttwn$l0_mCn9Xj*wv3nthM#s#3qfp)o7sWFyq{jw|adT z*P|@UuC@1FYsXZo4g`pTrNbMCkDhnQQ@}VMua7?Ygs*=y32@sk_hfwP&k!Y(uIySz zEFWzT8JsDc6Rx*@_O0ymb&)hr_(Yl{QK`1ql623Em9p>=kq#^63ORKSe+6KWW%od21h@KelfEahhBd(JWm z?RVjSeq|5%85%=u*0JyDyA&h%OPD!*4S$f~B~Ujj(}Bed*@Pwl*5ZRnj48)XvSt`l zvu@rHuemP=Yi|r8^Ck2>tZKUd*7mRz{>!20Hut^Du#i2@)PDMUCFd~wiP1AI+bGpNOYueAny7-i(`7%%RZsi?p1(^xC+yM7%XemIXuZ}^chh*T?I^2k6G z?9+Xx^1Xy9-$-gW|0wgQKml73jC`z+ZA~RG0|CDa(vzLfs3B80q;52O==)r%xcVU% z{5?4kuv71SL51#fi-+N}W7fR~%ErT$obLH5xF}MnZ+OiNWB;q)dKDR5-||gP@-hP< z2&oc1t&_C8OEr~~w2&NV>Q{!qi8q>x{D#aiR&mth#knQg?9lPXGHn7VMjPw*@F^H4 zkPr^yP?prz4Cn6%!)%M*?D{iQCkLgL~!R&R>< z)wIE^h5Wepb~{H3DSwA}-aTEa)$SZZ-j$%lFO1zX05$#+32DE7AVP$vgLThyBedox zc$Kq44;|o+uQ_#Gg5#-JjOR)SN)h3@KUkm-FD?QcPv z*AoqTB{7s+SvU8{RYfglC>#v3wUcni_E0M@-AST0*UN?zu}`4cC&C5tFHm+t>sU5w z_JF%;GtoL;I1;NTFx&tMh56AG`J?LH!>`dKGkEkj0G3nKvEd{f?jnz9?Gvm#|2YkA z>w#;NW;wkNr^GKDkbCCCC)gbf&>@Jgjb)#SExkC(TN}1SRFE7S=eNw|CEqBJij02I z2t;@ptd8TqO4Sf6lpVqr5s!ZAJ5?IjW!);>qaJz8?4cWB$Ko~4Q0n#1t6w%j4fxzt zM2|QoFy^!!HU5+K>rH7fBS)<(tc$IFyz_fJbskJ*WJ`exK?|&$68`%>)onKM%!Eht zh};-8z4e=-RKQ;g&k{~ufNG>u@N&~4*(=RI8y}=Q4GP{l4VmAIsgaGZD!Ly2GzFo_ z6_93MlswP&d&vJVa2oJK!>6v&5Ok*C7BB!xE25{SrvEOnfZF zF2dkK)_Ofe&HDP*EqxZoC6tH~N_JbRWs$5JC|*D*$6H>V@YA47g5lF2GhPF}`K7#q zpopT+D`%6`TarLT%q=eM;Bw$sjBhJc9peZkxItcPc>Z!J(xZjL$R`4f4)el0=oeJq zm=6aj6sGV;>z+taGh36bSyrfd-St>R_hc)02(N4uw2d#~=Bn7VI!!|; zeb9Gvnh~f3J*osFeX9h}onV_mTg6Dk=#t*(($^0f%(Lc?oOr!kER&zMaNtCv?>OO7 z0u-FYF8@aNVDu+#sW@b*EhpQ*oEkEV{0(w?e%SQ4!Ts5h=^OJ|m%^726Hg4_=DTP6 zIb*bN4KDTylYPGT#}@6ezu%oeb$!n8M7-Zcc+^bmcuF^C{8!Ljho=VHL5!$+uZ;dE zO(l=q&JU*Yani7YVGb?vbC4J2vu0gxeNhFOyPv33J?dQkZLl9aAh3ICzj(Xp=7InoyCXfG1-mUx|8I9 z+ZgQnPGefRbdu@Qs@lWbqS~DWKVgIGJK!$V&Gw78BOT2&8sBY}_59cJNX*w_-HE+A zQbR00<9!m<@teC+FUVZLKF=*B;|}KZYy|{-tUciWp8Ct+zRBQNA8X~(9Y}M%1-_8Y zC$mms{TKMQ!1eo9jjI$U)dHY;@(Vm@v|0gm(Oa!>_N!uoa$2m5*w|yCu)wsEHo(?a z|K_~%wSKm!^-e$tkybLJHtq;mRs7?kmZ3tXK;1j8I?)vz#eAc>LaWTuiJHLZ3HAjN zCp_3QTX~)rLpm$OEx?Htf({A;l=4czY=u@qY+GE+we3kWi(Zof!fT!9PCpy0saWjE z;FB`e8rn1W7ba6T-~VvZn2Gqi==8qyGiDCT*?@yK;AW=8ms0Jsb-V?w(0%+P2)w{L z`al$lysVlj7F2C1RQt1-rSf9AGT%!eWngObytnvkLYJob2Ai_g{{rj3><)im&H)(mT%G57Qps+hbyKeONk>N;C67}UCvr@a4MH26jGU9s(| zzW&}2nFjQ&kmB`vzln$@aUA)VA=bf^TIUbSAC%J=eBwHq?=ENz;j{Y}9}*s!xKy|Y z*3_gS-m|yO_&!^|Ss8kBS;}$5tJTw;VP+fDZHAgdpk`j#D7T!Y@VR+e*s?EF7hJ3a zY@c)Xn(gA=-Orpzy_GSXR=Q%D`{l?c1?cqf>EK&Q&kSUfc`KO=r46TvS%x}jxjOlx z;eH|?O-U*cV`rv~Yo+nZ;jK-zkfTPW^pn+c9JQEAewfS@ePiB%St&H(NHX9**^vwKWoREqazVGy=6p+9{v9 ziyTK=4w!LwzlJYBs07W<<0AqEcjPtc#w8taxWVvE$T~lj-f-Zr!Jb;aoGYwvVp$nSt$SitE62K*GBF*#9>T2o7W10il(AM6CT6CM zP!*0X;GUrI!-VA6+ipJ4&i#G<;!dBCu>pPfM0LRng3*whgD=#r=VjO+Glx`>&6fV5 zYX);!q+v!_xjtaO%-|6OIsWKfK?TIonOgo3@)}?N&w2}2LTC4(>5x^~<_kYFQDaj0 zoO)0~wYJjgT1avzPIf3(!=ehF{s}E+^tpT@Wq`!t=$tC(TZTHe z`{EUX&al}7vcjc+y~XqmI4+m7;nS}qB=+Ln=~n`_a1nGwWz;_DA>K1&$6+R_$eF}~ z0xoBWDy`bLn-zDfigPu^2>>WaFQIxtVb{8R9qtb6

)no+jk~w0!O4?%anZs4M>k6nya<|?!dg!ZG610yFIvO=ep*S1)Z}DYNj=k! z@KB5*O?`r_{vKu=7?Q%}nryw!k}w|Ml6&h<7=PgoE-}o{6?w4uvu7L1@4r&902>sI z0aJAkzN#ea;Qqn$HhX#xh#YYX!rg?%5O|+rOSWVswGk~xJ{4v?0(s5Q=DjVS>U#46 zB1eyznT?-yIU4IUaSDjRECr5qXhO`CPjv zK%(r1K1~)y?3a;PyR}B=g*f_8)p+|!)a(swSfBOiy*$nZU$^wV7@M5A4@500Ayga^ zJZ?5STAWopcTYd;>ThB<<_!&~cqQ*f6z>#o z3e>96j($`6_)+!av8u;IA;!4O1U4bY;g*WbB*xi3QYQ(oU^nC47_uCt$vy(IDN-h^ z_r9N7?rscIPJNF`MTk!>mU=%>}qqe=uRF+hQt)G{R{JobJnii$JECkr5t>Fi8NJbxS#w?*A z4@+oV;Bg|QG{I<@jhI7JDU_Gj8_!*&b8Z+85}i3kIbLzkoN6rxG%+T3SBjAx@>NHQ@r^d!ublzP1Ia2wYunnPPQP#s zuBvEj+X+nz?}+8s>m9|N-k@`A%@LAa6 zwhUO`@(jc?MUSt5q_yOvqve%reDcMHf&ec?f@E|oI7T^#i1f7-Pu05OGpY>zP7z z>F!@MXP+xAQhVF~)O2zyme!gkb0bLFEK(`TI=V9|`$|`PE;X^iNT5XD7Yl}$Nk*sj zNww&-W7Te&jxu0&N_+IoXYu{yNt`wiX@6-{J7!+G|If+e$ursV%5v}J5W?A%(9^;w zZ@e37Kr&ZrhrXw+V>%sG{R~i!L08(^GtG%NyV)Wrwa!fp*`vCih?vZSr;p@#qK#1E zSiP-JIlu_qBZia@+7C8)*bnjw`H(Cg*CXrowc#wi z|BQ{z9R`LbbL{9Nmb=)ix!~qb06HNjcjUn_P4DIIys!!wAEv1G>hL`w&waMf@5Vy<1Nqv`W zC~dLY1<9`jKs3F!!=`}M?rPG0--Dmw_{1nlFpPQ)0N$z^e&rBVTO$yZ3k8GtP z>kbPaO=_>4sd}a6Q}2^|SVDTP?(_oZLE7mnW=LrCf&9S?`{)Bn>s5|2Y1WM%Al>^- ze>1DURiVR|q9Ty4Qp*lj6ZcgBxNKv5R$4C&Yz;*aE1KoPHI&ykHt3KZ@meEMKv4wT z;|nQ^{zbZiGNg&y09vRO&BD?t z-Q6i5wE~jTjj$}8(ug!ttGjebOLxb&`knoqduHd&n|g2N&AoHy-s2{Tm`V+B79`Nv=yS;S!OH@p9#l z1eXo9|J1dY%ZA6a#OG*v8ZRQfIH7ke3WI11WQwd_3PP(})<)c2JU>b)?TRSNE_dR6 zWS?kigpp^&baJci<&4zGxb3qGq(-jHtJj4R$kpcQYYhnx(XfjoC(kGQh8J8O*C%^r z&95B>u-z^u+hV>dz+po^BJ(GGt}(Gp!S8D|wJbhRN8s(!fcF1uFHWX)m~ZZ-Q48|k zU2S=a)z^~8f&Dk{6ijqEo6n-2**8WSR1Vn#92`+5ym^jahMmz!1-6YxQ03zlD>)?t z8`U9L*p@h>U)j*`>wZxt9%I=u!D~&c+cC+tWTAnk zN>Ei52w(8k5BiVJS^hN`G}snb)a*%~_R_<>V)wyv2Vl9gK;fcpPJ?IgIqdV7U4ze? z-=C1HhP=%FPh3t)9qcXMm+VLLXG9v zZ&s#D$Xnlyg|5>vyK;|NQkTo(4Z4i-*b(ifdYbV~+K@ABb+xZsU4vrtEGLI2LuD9o zB()Q&<^_3M&m-M&$49Qggbw@_h+bO0q(ai?#xV(1q|fh0gr6uV9&r3IPB|TC7cD#{ z9^W*OYW;~o50=xuRJRKIz~%|fCN7kZl~us z&<_$rt5R_h@^KMt0+hM>qT5c5@r0s+?VotlzX#qP2D77OdNzU1UpbJpCr3Sx%|}TJGJ)) zr`53?h0|0mTqS6lNSe46^7je8H5!^orEVqV`Wb!%VY!ul!b`E)IT5JR7s_wKeUw0au5fx_s(8r!M2t*_Gl#K{9(%KfymwzGI*(@ zz<-~O*&6vtrzY7u3_)@;nc5}6>Mt=IYdXL+omnraF7u5mJPHpL1ch9*1XsRReM6E$ z6{cw96jxZKc}k*Hdx3u@gPy5idH~TTAFKWk(pIBrFr^AqL!^;OLf!w4Mma)L6`P)d z;YMp*Il~x6Fp?4`^w~k(d^|qLJGK+P$y=CJI8MS;e$rIFl1aFO24RX3fz->$1OQ(V zHtpBw{uhNqFIJc+&49mL6O+w=pIk?+dM^1r%Qfq7R)Qr`6`D6_F>X0$L352>R2g_B z?*CC;+>||j=(`IBfuI&QuWgUaM|Gw6j?-m&%IqF*oIB9eTlkBdSe8tXjFycko_~(R2=cSW ziI#XVSiD&AECGKq5Qy)#?lf&U`_E=t^JTUHp8b6pcW-K7lY%?w-yYvro%r7?{Yq-- z@@na9BJWy>l&SQeSuUoQHYXjOQ|cL-IkiDo z{M|FkBMDZoJ&;L4ebO4J7`6=xDYz774Gp!j`(0DnVdQ+eJ? zAho)cOqG|qHrr}z+046MD_XaVm4HFESE)nI&fXT}I%^wtNm-jrOWz<>tF39Qyp*;= zs@|x8O1X9pkmy`Xk;8&&Dp&L50=XQO-%8e6OjlAHPaGaG8cxG5JmqVm6Cs%un^_2j zFIKPym3_Ml^lLgdg(il;l6=xC*oSi1hwAo3+Sfz!Ds_q~$BoX#!*7lB?PglaM1{Q4 zvaaPOhs(12QqR)j>fvrW0^;SJll$YttOr>`SIdpon5JR=6KmNj`;W#fQ~C5!d^AUN zS}n<0?YL+fu+W)G)54gY-a_SmTTn9;dE05V z>E*HuqU()Gd~D(sn3L;BTx>{Pd^Vlt2W#vsr}>9!{HUD4TVez`QG4tYSsd|YViO(v zTO9sqW2Ae~+$;_vYU=RN*YC`ni~Lzq??I{e*YTB0NMP=;;DRkvG=r@yF@Fq0GeVYn zmR=^y;s)3rM*xe-{=a90=h$P--)Ig>djblc4ErxE4#%m01&D11x-ym=>1c{%_}dUms>_1U-Ks>&@OhB7voU;r(N?g;UGXd56vsV5 zADV;jn)7quw~8zoIiLF;7iu5ta;T+{|1IJFW zY?ODR;u?Z3>_04?AUnEizo9h>$xQ*-Kv&YYK+4!`tWoTmBUhst4$mcjb&oktr zZSU?)nN;dz=RN$4 zg6Y=t1g`dmgmyAndoTj>>MvUMgCMDdYQo)5*w;Sr`MIPBA@dwGL-xmnaYHyx+)Hut z8`L`BXc)J-GiJw5bWvYZ&7JXFAg-*9g9c_5^awe)D~E*m!iNv$X+A9zulwvFd`h$;WUh#OPADHoVFa<#P8;DBv8NAg{|KlQ6R#CQ!}TGdjuf z4;`V@`sa=(6GHh%9>Z*FkN}V|)B-vp4&nIdDKSM*zVK$M88(_Y^=%@XCX;W@W#J;( z4eY!T`5=^{5}7pQ&H5|H78<~W{ZB(E035s-yyB%z=OZEFRrFQhw5e&w=|EQFwjg%& z&PXX%mLKP;qJNBW313P|?j4Ln<@OiZ4PEmgWQ9}T9)FlTbi z$o`)bdb49q^Ha2L?JTX&%YJ(BtYP0}6iD#t_n_T8mDa(u^pRF*lLeaM#MS8C6Ts@2<&TCN$Ehw@K$vtUi;V(QNQP zzppLsh{VQ+v~mw+_mcI{Qz%_ z_4D3)B6IL=OI+oYVSLPFI)>(;H`XVHCZy?NiN`7^mrHmlW-CfLhhjYNyElq}*HbVa}Ed5qWVm%?BNJLh@SvkH&eL9vb-El_ji~9vBxYUOpEumpB(1;<1GE#*67ASnevPc!=>G1Ni?h|fxezWb z;C=lmkL2goLhjc9W-1pnE7N3XJu)3}UtoW}%eaviRqhEjMllvS(K2gm)FV zi^NWqkc6P?mUY5iD>I&=bFJ@hufi z-IY>Tu{Hs)-yF{LeQ{H5Cww)!R${rK9YCt1gp2nEKcp(x6AXTgZye_s&&@O%d+*uM z2cTL2**?Q^Vyl+9bM`v$aKSR7>qlRO)|qlw5B}b_^d9IgPa%>FbSIvdRAP9N~6~Q#DIX{YG9O29c`+B-$pG%reNzk)@sAus$tj-*>|K@qeVqK_tjYo|UbF2y|N`wH7=s;_n!&$25M`Q%06)aY4Rod-U80sj6X9*SBervZK?FL5NY0jUu z_?h+@=Y?Z%>|f7Mhp$u-556zbb0g<^>GSjdk+BKpCF47>3Gom3FR{Fo3!N23#!YNK zOz$9^{7_Ef)hG8L^?yXvfBE8}f|{Sh#BX^sqJxX~rhTX~LVgCp(U$$6Vc9`Wo5^O? z)VgO#UeNoFM+>owLW_`OspN(UmKVvUzl|v#f+oa;Qz6+(Koi8m=H)ST|II*}uIGhF zZfjv1@qJ~Hh#Nnk zpb&|yr2|!xmCcW&zNGI2V_uQvJvLo@X8RM=cy(RL)hx5>kD0O&ac zZH%s6ln9@OuViP!q*Rd!nJ{9v>-bz0qTb)iA=fx2U#PDxZ*x47>@(!6rpW3S z(Z}5FMKx~Zf+j7WY&>>5IMr^K_k{X<8QX)Re)$Lo@ni>^P^~guI+{$;P;ER~h@;|v zQT_2N<*7jRUYASa%ze?&QWCN8LpXq7FS2Oiu+HM%KO6PEGtRvqU-x0ByA2=b<|YLd z_Sa&$A3}E>HD*}%9Z}(ns90+Z+Eeq+L&K#0W(^%rc(vC*_I|M!k=1<9coIuG0ABG0 zuiW|{E^d9Ize}XLLsa7my=&l$_wEk>v=!Ac!gg_iH_w;c^LaS7%4eTBv|=8XWGxSMsgHv!#k;=;RPU7W<(8Beorslu zUYH3{b*jqSMEGrIOO~88&}=NKD7bENG-!DcH2SBHm~0xk2Mu?F!o)qNWf;BEXg0+? zjc@~^cbdQ7kBz$S_S-5EPqyt0emZdk9djT7lvD5AjCCXr9jh$pH)lL!h3MusnrauQ zRsVF~wv9<=+x*hMWaPoulDU=qT>rXS>}<7cLao1y)#3TL$F|D;;Q6A_fM^+EP0MTM zn`qQ7a~H!LCY#?P8rDbzlRIE-L~@MVlJK`*Q&oK{AL?S#Ym7~O=^sH2dlR+huDwxn zXWZ2GiO&fi8%kQSR6NRLU7rdc_I}0ugfB^7AuvZgtc?cFgcec-{ITcRX^)xx0dgsv zteIACHRv(d_Q@IQyNXWg1J_-`Hhaxq_~h(lmC}Rog@U5SFhv#sluPf9f{=+FWmsXy zF8Q}~I^%pybpY|WqS7On1#y~^rSDT31_53%o+MO}&of>7vFl5#BZ5|)g-h)vsr$F#Rgt?URtoysni|z1;C<7#} zAyJMZIf|%$?Ugcvms8NRxXfmzt%<_G=GLXyHmz_j$@Xgn@eS~JEYAVCJ>lm4C!9|s zX<$Cnd;eWy+{vn**|XuoFTQhS ziN5dH7sKBBGaO=oh*GMQ^QrI-sf604(vj$A7G3Hsp-=WxS#n%j{#-2}yKqgb(*z4gaTh_>8mk;+l zeIEXxW+h#n`XoerEd3AtcR(XjMC|J%Qe^(?q`2PAC*}M8%p6d%D9$gbUjY6EuFTv~ z{U9xypXx->Lvt#NCGjp2U8NoiehpO4b=1fIq3E)>cfIl9}IiUE>&mb>) zQJwc}QSPyAoZ_7|toTiq-Jg*pw0gbBmiHp|T2o|Kuw_H6P66Ojrqg@f0yQ@zXReo1 zH&f#mK9T4bYUcFG)B_a(j{?DlpyY6Y7SG(VJD)#d*erb zAPRNFdL#Gh<<=N1nYvNUys76VpZB?_CUW=fOcU^DS;aO)=gdG~fNmtg7=&rrS(0gA znrUB+f`o|2r`9|aesiap8zr4#Q8FWCeYGy?Jyz5Oa%XMMW z=GpiXUhGr&9E5mEF>dQhR}!t;=EvSwKRe1%r0a2N|7M3HuZ<7ytpdiM`dQ)IP=Ut6 zDL=eMlFRT2ZXU4HX4n%|FwA=zij_1UsZ6~dyv1lFj)9IM7xE`I}&OKx-S7%k?MZd=WqJbX#*oU`;l*K){wO4Ie`g# zK4>5vyJk9{dBe8pwR3)`U5gu(#$ng~XxVoc@8W%)` zN|vp1cp2@pw~^K*AE1UVwgr}Ust59N2)0Fuw?#i0EQ!qZ>_^QGfNw707Wb}`oWQB* zd6`jiSVkc{BUt>97;FwwQW>{rANNDAzaXXB6c0N`>tDT63$cseIB4Vv*auDWUt(zy zj4xwQ+N`a_8hKe0^7N7S@F9arsB?{{3k&1DgM0-yXR>X$Ra{^~=L9L8Max?p!v1nwj=EQSCDVBV-Wq*-Bhx43UvK!L@94T+9(9p44#;;7 zk}a=2Im~2Vo(dON2aC+<-5j*BEs0%i=m%tj)%;n+>&}-|$!GW^EV?ec`W`B0Ee@an zl$OF7(y)zCipGnis=3SFSP8D!OR zFPR}D9q{xJ@fr+aX{Odfc~A7THD>!cdhH|a(8Uf~+#4qfYA(Xxw?#@9vZaEPhfDPM zpzZOzr9~ruD&tjbbTr7kkg^?%JOqpr6Zk1mnVi88Cvopf6*7OF@k9p?nzOiV^Tw7Ry%?$?1LoRq zJykt|^nBv)(|QQ&ZMt{dY={#lM$aqMB61+YH@)P48oHlU36~T|vfTJ3+=a^<~)af=u&-CRB8X zi#EbJcB6~IOw`=xE z?;$Ph^;~`~}`Q zg;w2R`|P^tI1HYYfTl##CaSn6Y|*1f*ahy9qZhxDj#JvJ=$yS)!Y(qCAd2@hKCD64 zrTaMc^Vr&?C@qa@Y%H4&UuJQE&m(LCjc-rMCniL_$qfO0I#gVl*;>%%du-?32a9oq z7p30fA}-`^0u9k6(dDX+vLw2On={i#;9p)DKKv0S(XbcZ7M>P>1-s;Sgzej|1+`;XK98|G3$ zpS(n^tT{&ruHW`Eb>jr~aGyHJNB^7)3qS$hj?NTGdoriJ15b_Rtqw3fpwjGqr(2xS z3vFuv%q$xs?n~C^wRbrMot@R$q?sv;-Gx~5_CTKQZ&iU>%bmScNxY^IU%gJ97ItPO z%cj5xFNmk{F2N8VJyNG~0CHD62%9n54tZihkkE`qG?EOyg%qz*#LjS-bT<-0rXc z;>!A5qz^`@-dZ%j1%tKj4w#;cKp+4L?P?(KCik_ux@78fhrvkNYfbXGPPF|pchmHF zs*-uCPD^*(^_={6t;yLmrTl=YSNu`dbq->?7SIoKJqB7V^U)2fY^3wD(k@KI8J;mu zsbwD%w0vT$rURHLL``*cQncrBE;{$FWUTBp-5sc<&ZCj*KJ3`(y2)t&cTnu24xk@y zs*ccVe?Lld)Qu$ofwO17)_xV_IR_aih)jct&f)Z)m(scwlZcfT^Pa^qEwwx3mFJ(* zT~3Zw&~UR!s@r0^X-W{l%C!1?t+%zsyuH)m*i$!lYOc(%?=HE*rel$W9<3qTyTfth zpT^)j)Enk$F6AGCeRXDbPL6$E*|{SXG?xFy2C4n0e~?pccll8jN6mqwpj2nvvn6?C zAl)Cd)iSkRZ+T^#pL!S^Sfaz1gy3e+&Y#YeRH=*)v^{wRW-pGjTknSrg_xqN-k=req!LJDv z&piYEbhD>@A`LAf<7fnPegnE~6umwdgOnprg~uxd6{<4hDeH^+c2NVzV+2LO;#?!7 zzxyBGC3Ma`E9eTvQ|&=3ug%z{j8S0SGw8yNnG?s$ZH}kLVD*76uRi{u&0l*}=_RYb zTFo;V*5W+O|3pU_ozXueC+t4_^23{KWcsWYkr%%LFKXVF>5Kz_U#phxt1DnlA-CINDaE0!!> zWPi(*gu*g#ejbGwBjm^VB6q`VSM4XSJ@w3Wxe+nDJ6pd&{>>(5uDNE~9Md4YCX*|Y z0YmRTW`Oq$MZt+*zno3dTQS`aV?tz3m#-p;EmnGjRT{V=H@A3=6JIX{?;oJfiKvjm zG0L4zOHYRoc57Sw$-mqR%R6B4!C*iK(|r8H4zx?;$fxQuYxM-J!xb<6i^ACBcqid^ z-{7ISK+lhAT%UVV;&>v)guBEQN`V~QWX*aLR*PKgDuS`hzn zTU1ndiYnpCT;tKnEmXWWH!k4ag%Jd3(|}&PRp}*m`LfHo(U;6o6deiOklVM$XIA~N zb$)0ocxeYy&V(svPYda04=j!3u87@RQ%NsPBZSW3E}mlce`Arj{nbjhaDG3v4P7^e z0Wu#svq0UZJDSJMf{n9<{)pf}uar!{7i)Ai`n7D1!-KfwS8G=aGx2pqFOf zsmgU#zISb^dOhlb1xap1+ceOQU+x@X92F{oOO+CRJ(u`iW_xXM1+0(KcQ{5V>>mzx z91q4T>_Y>EU%OYqA|%@LR-UL)X2%Ow7OCz~7`riT8rA+c!06M5NgpzgQuZlaH|p>V zIRp{V4}D7nGHtYt?T@i)-dFd8`kZw?fcDT6j5sQEFo$eytPI`~f3S#BKA;l(fLB{2 zy{jED%@arhj0pvJb;pBpgLT!rOksROUm4ftJ`HDhxo_SU4R7zYn{Jnu9w60C1A!+? zdyp_@3G#c3>P5MM@xASVi`C6SuH7xX0C5|Th-It)H9+EPIq~8U_b*h>zUAjX+wXkz zPOI)c2BP-1C43;?jK$|VxjIg(Ozfg$4z^RhkB2?aL_~v~bVF(x1p(TQ3KVlY;w7RP zJ~(G8Xhfb)Ur4*F(zdWwZe)&hwp;*w7XE%}C9i60N!d%=rn2{E-p#c6H|5+`0|=cI zWahMj=|Y|wGbM&UPYe%vI&p8EqgXfL35f!r-c`eU;t%Ff7kj;nUT21)t(#SEY!oi$ zQJcG4X>HfpfRN^Lg&Ev>ID^$d+TJ$!+-*1SOYXJ7 zW8cX|Qe+q)tfLH9>{xSkbkxgdYE-t?ANun?)4vft$7T z9`=26`NMqpm6Y-t;DB@Z z`R?Tp)gJTtKBw zwZZrs5oYAgzVA2VyOmB~(X)@Dt$S6$ZUf1C+f+X8{oZH(qDs3}CN2Xzd)sH{Ue=Kd zIO~q1&yIJx>B>y!4^HGkZ_txS&`pmZS@=YZ)Rucz>&zU=WB+o{SbQ@$-R=|y5Vx;} z_Yv_epuX-4S$xU$7|7e-7V)|LQN-m61BzYDh7uoKMSWYlzPpze(iNU@dB!J&(h(~cJ2Aal@%aQ=!OAr zAzu2cZiMrI#U46VD1c^mDgONHkD&GN#xjZ7BeAyYB7nGHqkp(T2Vy<)PUN82BG$gO zd|*~0w#2{UuHNC(mx3)p@&#?|i6O#Y=}*-r zFTBNnErrl5y$e(T$e5%3)^-4_&Ld1#rK{bBVq$m$@|OV|z6z*2Pu@|_vyV5{*&*Vh z4^vkXR~vjQ_Jm7(E1)Ug4lL{g$!^i!;4T|S6m2eF)6fI!gRTORi(h^f0Op_|Cok$} zg*&_$TIU0qua`h4Dr6w9%A%Y3%g)8V*q#k-^@hAK7#L^Z@WjPi08_LAKDCyIEFQto z4?d@Y-?-x-_}1#Ib09*lATlC|_}$V2o5#gBXD~7z4g*~FU{&r&?tp;x!qM@2+pEOe zwM67KSlGKTyy?)Y>}wCHyB65lX0Uh-bwkD4@u$om5(8u07U2XfXcXlJVaW$_B)yuY zq2b0!&8>+j%DL#@o(RHQ6&}0?k;hTn&PElISZtQP2EL$9rL52~xIBAS`n`#N;HMF{ zlcV>1vi(~{fnt8Y4L%b++U*X6CBHWt0a7X6U`Vc#Kl(QS3MFs|1f6Q(o_$CzUR15r zO2IOE$5HqihLapH`Hw%CWFu&JkM&|1X7KHuO}18-A6FXg5j5Pl53!y_^&oWi;QYq; z`i~B`Mt8necm5O}P8Wlo2)sWO?gr@?`p=CTS`k}0dr|ySQW@eGk2BdXam&1vAN_;8@dNE~MsNpG*J7&mc#u!M{BBCEcdm-qrsfMZLLXPfXsk z{rGErw1Iq$Ja5f^&>6A2r19_;IL+-T9*A0+6xcF-qy6KYPr`oY8NEzm2}ba1ay!}_ zadM|ENjeZ*(DT${bXU-pCaS{7HLk!G_3U9nqru)&&B`-p?eUW#5?=51tbBWAjYd{` z)MwLAU0?&v6Xq=<+0;U&5J; zA#$y2z3l8q8f#AZM=m!EHGg|h4;Q9aHV$Zf;}Z`US{$O9M?+?xSu|;3u)*5WfN!Wl zFzkjBsJ%_3P$_!5(|s+;B|0%2KRiJIBr|>1K=pV}n`Bl>;F-M_c4KSdBbn;>M3CZrWqx~9(GFWiHL4#dluKZ)hup{LkMxLFYM{z3Cz z#~V_)n?C(QX(E)=6SC;4a!z-ejwQYU^B<{2ROSTLBhVt|T7;>4AxH$g(C6%9g2|2# zOU6bTJ2G-RqRXa40b!g7G%WAJKN9w--~y8h(*Nk`@ohu)pB4B#^+fCQqA+p=$w>e^ zvGnB>3tO<^bPTi?9zMWF?RXQnd|moF#sX>@s6Wv$pOz^HjEB6ja{?{Sx9F3@MWy4| z{|KFRhcvD?|Hj7Qe2EIdI7RgH{|iiaeiP{5$>4UrtY9M59XeW6u~~n z#arhq(ZZ7CwOQlFX?Plkd34Y!R+3;o^52Zh$x<)U@;@s>9(m9Ql73+oLQP}=FV{4P z%<`*fhB0D!>>86+S&i@eIXJE*V4MQvcZ_C{GKdGaS28J*SgaE;rTn8;c*Df8;bet+ zh5dnOZO1MK8}f9k^aOB5f>Z?1o5m*1ZNX{+MPT(Dho%e{o*xRdeLO4a9TU3ZoZn2R z?Ix6K!MW?YbuT~YB5`W=ASWUScjwlaA+VAOQ$b;|E=tA-!AW_d6KIAbAI)4u);$kB zx8|TD-LggprK+F>j&BoeT=G?EY_;UYdoTq?H3V4(-Nh#^2u{U|wgbXc0%fj}gl$fg%Zb;AB>i~d z7bKQF48vNF&Ps9pBSKByK{}+VnajoG5_~330_}#EnyZUWp7(?x2_Dcrh2z<@8w($! z)Cb|rriThzLq_GE^6;f#J>J$NT>tO;_)Q&d0S}F~DXA=i!0JhuBfX4%nDAS)KNG12 z6{Ck+-g4a0AxRHj_y)`15A??f*VljpPQUi;v0Q4A2dPN&$M80YDe&8GY4EzF0y*?C zu0F5y(V}oPJ%}96DqH#a5bbQKh=j&gRvr~CyUF$uWRX8ct(`++iARjiArI}eNV10< zN;WV=u7(_!Lyl{Y*G`MP0x2QlH5)!^@(+5GK#%&zzBGGu^3(nmf!)-akVL#y(bNdw zB3~u+R9q_|cK;QHrU_*lfr4Ro7!gkzv5O`tN1kP^NVdJ6aE^s9Ja&(bGH)lbd4wDz zN_u1?zFeWOUco%}xMoa4=W!c3u7mW@D-GUQxaH#%SuFXWZ?I3pFkBjPL^6*5&!^&c z`9M6mA}nn%2Q9#@UuO@%O5&d-=|Wcc^@&EQMuiAWceL_VGezV)9y5(wpD$K1=W-p^ zOHp7NVEHWuJHYiPSme)J4bV25DN?m_TUFfK@{>&z$<8ZtR5BjiADh7Yo7n*CfvVUm zfi^0EwzLWlxRp>{7JpqDjb<@;p;l__l(}9Xu$U z%*e0{`c@@Vv-6(?6CF4qj)MhFcbL)c1-<&;P91?Pig&14bvc@7Ia;J^QU7J&_32>c z=%D}SgA1nZpI(qdD{(TbG}icGPbr}vaX?iX#ji9RBUau^RcKvG9Gqj9yVn45%i%@W z=4S=`@3jbildq!wbYIIVJbM$eYrm8%)Q9@H4XRT#7594>{bb0)f9O{qrRx2O(@#%kHku~8NsiDZG!N{h_ zKt93zX4~CBmK>EMG>m!s2I7nDXNFqlhgyshM<5WGIpzYjefD_#URK)<$6+=sE+^Cpbp*#wp>3afX_ZYAa# z1U4=8#mwV-*$Vm=KREx}a^H1mp2QGANjUkn`&w|Xn+RVE@CpUa*uG3)cC>iNxqV@L z{Pj_~Cb}(_;!m2F-{Z#*V-LuGimlj^*YQlQ*gA?R1!P~K#mUyWmsQJz;X(v{GAnJ; zZV1T-%2yj077VGciBDY$nr#F1t82bu1kj~+5GKGikbF%)E6I}QV-)vElj$Lf_;TV{ zDnRnH*eJR;el9UN2c)8m&(tu?8J=zYJ`S)k^7Kl`i6A&oi}Xn&IKa@PfGXhlX<#ji zE_W0iFCJyPAy88DR4ux(^IU8#y2qeZrlvf)0C(!ZsBWKkhhzZ5Z+N&BuFa>y%r&Q3 zwFJUD@9X1-_3tPyrp2eF%#y7flbfqP`qrRPzPLoj0wkvzjgzI(r;OwN$fi$u0?KHP zPG0R~ZV^8*ztD6P=+2ft`c)k5!4aHkrdDuiS7?qer$9EsN&a=jd-3I&mgA#NzGcy( zs*6XdczyU}gofXEaBtlq!6Jy7Za$D$5&n2O-N)^<f}B|bSG{IHg&nBtI6h2c*UX2ODSE10%P!j4Q|dbT0NvLPh(SsH<08GAtvP=(n1 zy|gJnKBH1os4>qAj*M9O{KuxF<`_Z!VY;H;WEqAP4+1LWEUTgu-mB9zjSKDDzVvB0 z4Ufn#DE_>yeROonCv6W7mVdkHZ)5A_8i+gK(|wd|R8jEQfk8}>WRk_;1^GMGSHZJm8yMiae6KBZum-&6Y?$A>nu~eQwmC ziXp_{x(aSNVhOS1D9M1OO1~ZzOHW|>ta$!eqnB4mb1lws9gRx!BgIpFbPCby5q9{G zm~HprZEOi8Iq_sXdJHZ`bc@y>nu&|ZN_kDwh65D?4NM-|m-Js$_(O=kKfb4bc7KpZ zB5X0P7LofLp8I@=BpJO8Kt%9Hn~uqZn?haH>Sk1B!e*K`FDYpAF)NFPkYap>zFn81)cE;GDHFz^`1e2C`p2M1?(Ssn?)qze zMSeXXX$sFi5sVeHQ5MoD%MgnJz-c^?wqIh^*T<}s%%_NkQ@r)$<#>vPZ61yJ8Zq>A zfll@!QubnFC$?~Q{-bux8!RiA=sKaLT~4U|dX@+2WM;+nbNw^2if0rT!>bEDR=7sq z5OSun{xoPTtG%-LpkMG{lfYr?p}g#V)mIQSRb{1NC=>6 z{RBzjDdPAt)rfcmPk_M_=DiT3(H~wjy{lj%h#AO(POvhB09!vBTCCty zzdNL5+hj!8mrd(yPO(tXD6b5n8x|PvREwW)5##@mGZoL%{X?idkc=lJX_KEqG|P9k zY;d}`=`9d05JQTOqzAmldAc}VaF z5LAOoZfpKcncFs9X=lXwwBysWskrMMwzH|yoQq#AO?<@Y18iD~a&8;(y0iLj{}e)y z-(?uTP7GA~)8$^m%Q(i0oqd6wyhEO(e*F=6I%lW3mZ0aKG7D_^zzwP?IAxc^vUUm3 z>XG=g_n2%N-((k3ttH0GJXBNEftY-v0jW%{$QWNygl6~#lsz7y-=y=TjAm=0Uj6vG z(=vA8iV$ESRtrIzlX4|N6;rN zWhBv(Y?Q>iQ7yN)77sUSluzuoC>zShx-g^U&7NG)Z22)N`SPP=2RST_Xo9TeQuCZ{w~DdBuB0oe`+Qd!ANSGN|pJ&>$PW)r~2xS9~jYK`m#t!9>Izv#40;vwdggOxbJ| z9$@dPo?4zY(4|Rk^V0k3PPU&c;|*d~L^v7Bs@RuQ(TP6bpa3N0Cl-pm=b8xVOL?#e z(H^l$Lhw?YWDF>1p@S{V6v~-sQ&FH2$pLchrB?@hl=i7Y+F|E!{=ci51=rrcO>>@; z`Bxts?q+aN2Nd3sDI}W4q)8SmOre?y5iOnc(by3!p1df=v;;2lf7&eZ{l(&=fDV>j zr$gCP%>kHqy7>=K_(LWHXzH4ePvkjNrd0CD?+!g8U-HW!j|j_FMSsU^o{j&iFVtYh zwl9X+7b~8Ahw$5VUa0ZT+_AMSr7RqbwiTx0HE4nxHIwluLjAckT>4TD-Ub^gB<`|k zk(9-B2~i|w%07RjR3^zuk!qI#aV7reR2eSq_?=8$u91!V5CU<~bUU8Czx*qn`EN*y zdElO=HDtv>t*?X4PrYQtB)OeEbdh@^OAeK#8i*`|O|ochqHkIWWuvW-4Nuh$7Z{4= zrRd7^{iIb}8gn5`5s=wSs?wLscE1d1a10*T+NSOqWy7nNefL@WonV(}Ngi}N2fA$x zgsZoAl%=C?bG3Wlgm1inZ#V_V$S$(muJ%u!_Mg8BfZD6tTdMR`Y*@czMr5)Y)Ti9M z;NFGo+9l<90MGe{&?mq2GcVn>+=^Np3}g$xC^vX=`j8!?51lzsI_^MHobEn3?aeUQE-l@o$QR1DUhiGA@ECYnhDgb$d*8AeYM7_%g5r6?Nk4^G>@l$-C zE44>-2~&jXuOYLc-?)8;%BBauPh~;lD)vw_?Ss^TiLdpnW1&P^wTX>0J@M>|N4;&n zEBNQGK>s>5fx)2Fxxak($`=nYi*{g9G+i+O9?)I^#N$88Y6@ItSY|qg;N)^ZkTN6uqq-lFxC=l;HXgNHqXJ?RJe*VGtvBOh3Ox-Ql zi2a}8cSIdFg%>063nOGhI&_6Q9VHu=4kM}OU2w=w)cW{6FAw^yVsD%-Jtj0G-HdH# z?WUNPQgGQGYwbqXlzIza<}`vUUce(w@-9>RuC+;UiArfbLep<3w^kpyq$q9Gq-NDL zjQv9RXPNEKS$aDc(SYH9Iz4$>?RI@Ma*e||U%Qt*3DgEY{L-%}&_WcavLBKqUgiDL zy6->WQffFJ;j_WFAFr_OW4h^v(Ay>6nE{m=zWrBHD9bfIQcGNPI08R3vi(IyC|xKu z2$#}Zek}N{3U}J8W4)?UdTCd==ym4L@ay05cdkXj&1n5*T8`IcB($2$o}+xU_Gc%t zkp|*hm~HMBy3Va!$(#R$^d2b~-6l4k(0ekkprU;n{ZEW6FS4QKFODfx`cRb7-yulH z?rAl-QOejobTE`&1s%*hDuc~P^Sz-EFtp^#zt-2d<1W6Q!DLQ{mRANW@yr&^t`*K& zp3za!h?0pr7DkQ2(XRIV{BziOz18H}CxaYA?{LuGwUbQIT2X-2N^D{{_akjeX*f5x z?|hjpYF4bOI>_+fM0PWF^R?pP{*Krc7_u5GC9d?jK7rfjqtRn@*PVe(OHQ7ID=!W` zJFtAaICKUo>gkkf;utzrCD`F3vZ)!`sV$v{@=si3l|os40)X}}`#L7a zvaj3lMTD3)tyvxhI-}kQBXDg{nN_25qHafOM(xT*x0pG4(0~{2#pu+O>2ie@YMvvU zK8*)a55LZ8P5`&gT9#2^4qd>X&1RWtD<=5;zMT7wO`UB854KwpnOhQ+*ZW^!lR@Cd zbT6cyLS3BR3 zrK#Evaq9J;kqees&q6E`x?Zz{tP;ZC8FIFv?d??KI-Y6D?kyUfRwW_+?l6A)OySYy zQ#rP{TuOTjXkhnjH?`v|q8 zkH-QQT!{g3JP)Oma*Ls|s@brZdU%Wr^|@?fHb;_HCrxA!XQWSfI(Ofp^L9M9T(5IY z?3d;R)xD7xzqY@M!bgW8_8v8>%84CwGXTUKoBv#e%}~eH2~HGpIU&>at&s4rrspA! zfp>^b^ewV7rd6Qa#oq-|GTQwFBrFxx zerD6d{Fc;vrsG&>KOAO8M&YPae7s1|g*FH@*lL~RwYMl7N3!YCdzICDwY0`uQwje6 zLPKLKJjM$@#;Z-r{c~Zo(AzOh@}qqP<#y(i98k+ki?Dbz&N1I2W<4n1q9s17JSaMm zC?>HJOv^3Dbf7jlG4FztET+mCdh^13cwxGP`>G}5b`Uy#IN@a0iTGe-vs;8b z#3>mz8<724GfRG`ll-8am?<2X&W;zv#7oI7Cwt%~FX@!I&8b{FOqX-5S#c~6s3k9N zU#+k^XM-R(E#AswU9P=XC;FXyAneC@;k5JpQwN+eAbG)zbI~vS3%4Af%P|Fu(x&X6 zY!p^A*aRJMP}y$#vBhNMEGaRL&j6&p26*e)6XPtr-aZX~!i+N-EyWij)ppXJH|Dic z&-TV)rG6N$G8xWP=#xugHZF$j}29?iO_$eq*#m@JsxZ{#`o4-~8`T4xrxa#yt z)-9&8+f){aTN#YXip7XQ^WZ!-a!Jle7G)9y-I@)$Io0Te7}$(g`Stezny;=6B@nN) zK+}uK56$e{THkrK$G330^`T6Q`050z9))&eaJ$YSKtc^)i~(rJ>B?kR8P-IGHd8!) zYhtrD%{gIdgR)%WkosJhaWT7@#(QK01vTcOaK9 zIx&;MobLWzV->Z;`8#U*bVzG`sKVm^NV*EJD4st2HxL6vN*W9rr27bo1L-`vq$Q;r z6r_%hqw7HGIJ%@o8mXiEXprtY;#>V5-e+%bc9`4QnVtB>`?C`I*+-%6Nr=3Dl%WIF zUMS;cv#w)YU(&p9Pxno)z85P+j{-d*C8eUMt;u0A4K4{gdG_jU-Q*XAm&=pmPF(Bs!p^GXsPqGO7B+Gm4OEi33cE_ z9HU^ONijd?y|5X6RZPA%xo&jc=C&eM8f}*TuL_GbZ3mMliOW^z(jLKfyrchS(?`9u zi3cT240Gb%Do+@gmyj2oiuS!ydZ||O>TYGZXYUo03jb7EPuh=B%g3%_0xd08eR+;V zHTy4a)A2i{QM?x8ybBcgsgq~l{^@=$sC@$T6gFPIJr4dILv?DP=ShtOLcLN9 zDOW5St|7BJpF#42<|YL6r|bYMz?u8(nEP@fN8I05Er0Y9mlJun7QJjF(rInI_)YQ7 zm3j1sMt(is^Y1?{Z$xTK8atCx-n*t0vQ;72_DifBnQ;YRkMx;w=ghhkPQHXub9ABw zKg62s^W$U7$DU%~2!7t8h*S+tUYhek&T^5gzxupx@nLdH_m!PQ>d&{h%8g5(v=XOu0?lccaSTzwA{{iNwTvTcGV zm6F29UA1Rk=2k5p?<%a*U3KTLe=UlpW^81rK3 zgFT_|-6{KH4i-(rdh}ku^^c@>`1{P73QemL3OuMZG6yoddn%}K3>)wmZ0zcu!9O1tf!^kr9s|d zoHVH#P*VJ<5dN#95=U`I8%FzgCm_-5Gckassi*}#=yr+GC_!e`X;Qqg{uVJV-nA7I zG0uLFJ<+o@-?L@lkX{yvebb_2SJ;kaP^iT|R(v(!y=a=S$`BRNdSF-Iw#IK^+bFcE!R{LbN|&}dG9&7NMXIi=~5CE3#sXv~%N=4rl z?K*tlJO?a|r&$>gg<;IrnzzfuNLq6Z!^5>Z(q}v$)RDs4HhoD=@000;8p8(d`-);B zsnh$ck}Nt&jr0zWF%|}5pu4tx^_o6m%WIPal3e{sg-p*6fNAxXXd+T;O~`OFh+b|p zjKE7%q|b(HA85?=-c>nRr4p>ttIltiF^iA?Y29C)a`H!WNyAle@}?}kR~!?|XOlLo zbb9gv9bTof-Wg5lwVE1!@ozpaUege~zSGriabhd$q((&a+2o3Gsun1WF;yYd4W9*j z{Cc5GYEs{5mtH`4ZzAl!ZGwAex=89ZJ41?D&J)Vu%yy}v!~3%-R=5nh?K(BV>`wAZ zF7F5pej^(aNe(3mPsgN0c#FNZYFs5+3r5E)2CX}EQ6aqpmo<~Mo)BbMOnHP1nc z8AJcw80|3j^)(p^*Hv^pgmm3fy`05yE2qo8usYA? zaz1l&!!qZ5LX0#{$(WaK^Arrm4kSNclQ%5mwil9QKeGg$oZk6L@L=1ppmt}Bp~IO@ zf+C^$XaelO;#-2MXS1?zZS&F3M-9dg%J|=YPyZbrnj6Mvnlq3*Uggsq_VF!CbS$hp z_$1k2l3ed<+3jdD}0HmJJVC_A4f)2XmZ zwixGV7EQn3x6>p#6@J85hQ|;I)C;e%nTxq>$djQa7%wqbq3fAKsF0v|MtY2pU|Hk^ zX?qG6%i`ntv6_XL}P35qpl_1e06@_g#Qw^7emvWz|k!&E(0r#*7OsaCNT zklUt~h+v@9eb4>fA$Z_UPN0v-)Q=-Nc0_PC(X#}T*K!q;?MUX_Bd>BF;L+eY;G%_> z(k$1~j5O#nIra(HeKpr_PSYJ#y*!DE~A7E%`QJes5+?#;SGPDbGrnZ^!I(bVMvN@+HL{BJktemc#G z3K;S_Ync@+@vs znPM=$Vob|}xtf4q*#7U1Y2?DCkHy`>;3 zVCuSDn1)EJM;td-DMjU9tWu2SF>ReMxY{>5wsUb^q(scNX)QJ~_?#ns&H=jeqM)50 z2o#aLH^V+$dj_QZXumn_^oFAGvaCBS^^IxVYvpP-5w}}b8Qk4Mc=H>u!~bJ?(ubA z7j`vCotcus)w03WI-XJIIS9hjog(mX-pe-cZ3jOz@@0)9nNhs$X8^ExFNcR+RARpl z-|Dkkyya+#n38(Srz&lMe@|lm4|x6$ojb2eO#bGIcdYnN6uZz>=N5LexOl2b_&2)3oa6R3)GLDcOqLVw|VR!JcE2iQWs!RO{y4m3uG6>b=GIm!`1uRIB^+sb6$> z@9j^L85sO2<8DB*5Is}tyt)y}{Y@R9Yob}xkycn1wrrB~BN^g&_z3<9+SOu&R0OM` zrF`MUc-70Vbr1P}D5|HQ;M$K8VfhBm@_@zBX1nQ(B=mhjIbPP%Fh?r2VBhZ$yG=##HY9ZrZfI{|C|gk`(5Ny ztmr&X^Sz^SFtLe561Jhk7WbVByqq5~`d#?NC*3az%_TnU8*D;HBrb>S0|OE(Hoc!F z{q4){vKuZ>w}w*^S=(1NpG1NnWj{L z@3?$pK<@Y~mmG`aLbCk1OEF6`*GxC6IP~;GHtZ@(n3hKtX%+32Xjn_q>5~?z8t>eh zX4x9d`Fa0?#{YbdkUmG4-%mBaA2*w}2$Ai8$aWgd%KiPx-ga`LjV2H|3H$8)U>96M zgLWk4c3Nr`;rK798V;7$3;L@5Z%dgRb5%|W4xe)XUnR_LASb36O%l$-xf`cYTTHcb@d`y@2cm)7x71hed4kx3wV}hDu|I&~`ja1Lhi->Z7KgLG0Z_c)DhBGdW_7v$EaN9a=&Q16Gc!GA zIyB*{BI(q(Cwzy~Te;|TK8qim?IVGd3{r&IGQ6lm)6B+4=GmfKMGPUFzuiWkbrd#VM$LMuEt(^$(;U%i4htA>2(K;o91b-ViCHn6~ zgwO0o{d|U?d<1zeiJ+33(V{)?b$cQa^vT-qEYemPs=&T#7quF?L zsg2!sO4Bat-x@_*xbK-${*tBV?|B6t+fu(`R$u9MPO8 zC?1|gn|^}U`S--j`}n+|p&_8T6F(dyioMJBu!i>dy9s9;PIT#|wVX=NBSHLp8-U@Z zsk2PW`OaTCi=$h78#i92=NNU{rgKg(RF8@H8P%jjcMW1@ zOY)r&+UoG%4B?!!U0}M#X!^1*83N;^;b;qbY6}0Q4GB7&PR_=^F_CIbmTL9sN?|eh znC-7f1|1T3+pQGYWeJHKvIHc(X%Fgc`fz;S@1=4*ph5g*J*W!GH|@253Y|=NaPeiC zw{u?%ggxRg#L!1*VXR@XSY>)DRMQQr>24gOzI%9BhjIDmhB^47TuDWbRZu3-JN4*s zmOzDVV3qmj+OcWDsf?q?G>C521iEMDy>T@(f9-vjwTUqFGm(%QimbpXrsxCN%J12Q z?`8hv+3S~7R@jgcp_{UIk8wl@&<%)M?MomQ(-@K0dPL^H_jaW}K%}5|G zBBI-}`&Ng+T^7KkgXl`0TiVsvvO<-3z z&an8S%@~|vnlXJv)FmFTkNEceYPN?ZnCuQ~DBAxez)g=Cn$WyC(@~jv{#36534HNH z7rXu4&!sm%E|$)!L5OZwxoV2x5#w;Ry<$;2)v=6lp%*9Ky|R2rDtN@f`Xdm6KY+Kn z7=UY7-X_2I@|+CZ@*pql>b|jmzCyd@~`?s#<$N(q1Gj3>LJePe2m4uo4S`k?)U8@u&dG*w~B9@*)6}e>b;}gtd7ux? zmT_w})D~$psSL1ca2F#iL_w8@=l%_~y`UNu_IG3Q#W{gl26{c%uF?QP=6?Tt6?XO{ z$5$f9S9CQy2k{{n@!^@Tmi6#nmDfLsj*D6T_29<9CQIw_J$IfpcTvVZ1y9&enyRMZ znk3PxL|dK8!8=cz7t*s4+kgA}RLc^qeB}wq@DMo^WpRB|Tgnk5tFE+qY%!_AwtOs_ zOy-#q*QDSSIDLr_avcZIFb2W+{78!*HH#fJgQQ@I$yuTvYWTzoyiml=T1QL7YQ~V<7c>22=a0~>zbfFbGWz8@|`+a3TvwP z%YhiyRGK%Wy#u?e>u$XRH?IR?ZTH1%&tq)&v)J8=Bibyt7fs-}dRFa;Qy3B(h|SbfU_M*P}B@dmmngq_9AA*D3Tm7z-MI7gtVDWe9y#wkS2jJWlLXB z*_9zuK0(oJ^KtL+Ayy=hIZF!(zc>%m*x0k8qH~cRTIPbFzE9%@EAnQq9qYvB>^{ux z)*UYNdH9GEE0RUC>ok(+<_1kzL4@~blf~AgS|WXAfMnIc@QX~a¥s-A>cr%*zU7 z(GG7n2>obZ?`QN)Y;2Gi1*ys>&+7vpw~!7BsB7tJ&&nEI{8Zp|H|PkBy`3<%r&gr*B?lrx#+4Om&W$pKwJ$vq{I3$p^3JTj7k2%4;Aj&F0s}L zXo0t#%#y#~PRq33le`jJNj{3ub6lI1{Ab(PJu+4q7R=MR-}+>*k#qMS4~bI2<2#b3 zexla9bx-#R4)RP0uQ1vSPeP_@7{ywjq%v;{&(+zq((L4G#g>tz2pqy+cJ_(KSD{{# z-#ZRsHiygUKww8$pSXciH;;PCY*)4TddsfCNiu!s|9+sQjPfUmK_<|;bSx7RE0x1P zkO;?1YM$q(IH<7Ks4#S|uR7|I9WpiCg*Efzh20#9*&uK?YMyp*0d2indJ|5SRY9nQ0KBm%Nk^MSMXGmKP%}%WDYso6El*%lnbs|1sxnEaC$7h zP`nK39vUt1^UCzwD%jD2BE>T1Kg6DH%;6C6`}5@{6_OG1nnF_#1>OGxPh<@=(#599 zu3E^gu2(_MW$n7Z*P6=Nbz3@rmYp*va8Ds{zjRqpKEzla+k5VE`~986c)T8p1W>Db ze_m$7K8WCU5_*eKik-9&_`hR9=XaTrw>HtT(O}>Y;%)r4k4N~x5ty|e&{+1p71k5W znq2<^2siFdA4`{V&PGm`GE4{hEhL0{3=gF_;p34JDx?H&%#kO^cmT^g;6E_=FLM={-l=jR^5mT`H#N`TDx6qsFbcL~+K?^; zqJNruh_SMk!bWf1WAf9Vz~n#T{UB5SpH*&cP6JO`Xg14f=C? z$=DH<@1c+dz)-Zb?h4&2v}H!++ADOmqmUzQj+I*(AZs3kEscWFdDz=Z34YnI(5Gy4 z+iBq97#i?2LE@U)jbXNqO(MxzhPA(*PTcJ)i;ZZ@FJV(=)1VWy^AWz@M)l=Wa zU;5KQ8@^rO-LrB%%s0Mj2Kt%!jdrCa?J!e1n5Vy}B~Llv!NuHo6~oyEGw=}I2pg;X z2vdOxA=F49e~#DuHm9OYL9lwi7R!k-`=tndGU&!{1y@ZqOFGEQz1KzoEb<3F6^nz+ zo5+B^Y!S3Cd%a4W5o0gAU~9|N52yczk}lPsFJ5x#LJ!11?s=->gN3gw)x`H+V**&P z4}^EVWf0Hkz=>=8Gmrgtnldu#mQ(N|qJct%UoBE}|65>p2cTeB4VBP15j^iqF5Dq! zpf+oQD{32Fh9u*JOV^Lm(TtBTn)uqsoU>RP0ow;t8#ZiH5b3OHmzyDpO>UJgsJP}J z?N~xqd8`4y#$G*ZWr_v_wk#MnTIwgx|7iGGi%s~~zWTb9$2W8VyIM6PaSa9Mud_!ENnac=g{zK``9{NJ%g&S z>H%@Bo#E!T!RKR7UM2RnfsJt`TS-ezP}PhLp3+6>OE7Or3t98O@wsSnI!Oo<*Fs}s zT|S9(mio);#_O{s!1KTvb3|Uhxs-4GyRN}1T zq(gA$$i4ZH!5Yq&f%B&2-VqHAi)}ue`m>%uJ~3q^cm4RPbfV~6`K)nP-{Yg>4x#u# z!52aS6!KeC{>3W}r%0O)oe;RG!gFjqDpMx`k4;k0_UG~mY#RgH#~Qto-5yn%txw+4 zl*i*u6+^yocy6)^xc_VuG5@SgHa?+RHOZd_qH;TZSC<&a`eRQ|6kD>2uwL;U55z0hn@* zw&G{U{VLtXhrSZs|H;j=$br~3#xfgLY!|x1c3n(B&0TH)%@yV~K=tHG>0Pn{c%`q` ziO&~0f9^H-hLf7vVDk>iT+!IES1EdI0ZJbo7c?+Xo&=k(`R2RiuzAOGuNhPIB0gw> zH8DCnM`5lE6B(|1c;s;nt@b<}KNQL9WJhOLh4xE8&oAGC-1`Tqs($zSw(rNXWXL^F zwh!uA(-Zi?r&+_b1idrUEx-mud&~g z>Ftx(%-kvEx8a_?7f1De@G$MERm8DzdPv0aUBZxT^mmz?D3Vxq@5q0aG+U23*V~dq zA}+&;d0fw>!gkcpYf7YmD3Vb#?Mdm)jm&ayOUv*lCnW~I@`JiN*cjXdiw*3@mffpf z@$X|KA93kJ^zjRcp2wRGhV7Z|E`B&xR-evz#6R>kO6kvR*=!)*Yk2w zT?>2qz7JyFZ|WXHu}3A;($|Eiv1P1Mtm#gz`1-Sn!r5rApV0OX-zi>t?@=>{)bRze z9rE~NV<+nV1`AQ`Gc%*Co$abY4xNXE;ISg`n89EzyL)0D-?<1Vv?@>l^xFI6p+#VA*o6`;>>=|L$>=u<` z3TN1Y{y!zJ^4=Z@03u}(D}_jAQ)w7yJzY-BZjz{o;KLv7@88@1?YDl`t(FQz{O4mI6mNkw=39%4?5xg-?< zltXTg;SA*Cq0%)0h=JN;#WP_~$zE#+OYvYWi_eKt;vE3Pi_YoNs=cXg25(;!_}VKQ zMl+T~F_u(pY5LaRoMgg`kK+p)ve$O=Q{(41$Lx^d+p!b%oRyDs6iBmT_s9wD!*JqO z?Ze_Ie4#lYA25Wfkw#A+Y&CLFSCP5rbPiTerD*#4H(jy$blC#RgxyZk{Z4Wtx9yvjiC5AP`4ld5QmG`jOZy@|K3$ zkH1Dv7}m@vCDcqCaI0Z16Y{w;(^$_@#H zk~btyYzeOd29&cU{ud>>%rJfcmv%>YvG9c+6^F`}qe6JyF2=AP*b3F|l{v5ibhF1s z(VmCbQ=&o<6Nud*Q%-A)6)ib=Sg>>sBqA3cYqe=few8w@b*z4u!-7GD2JiKe@(`sO zkOcJTE<6*y zRnyhSt66$Yy%kiN{=xerofU*!7pA#?f_o|0s`m1BVAp*3G&J~r4n(*GXfBrH zky@|U6wvVCBfa3J-P|JHmI`h+D;_}MTY!*BUh!r zoNs4sqzzoEyUxgF%PH^OV@chDYq8VgXnq5Z+BbT zsoH{nL()_l>OBw73%j1O^w8zzH-%#+HEO@hx>JZNd~E>#e}?z^YA;A;<>Hj)D*za7 zM=46mj=+XE5@-$TLtD)VG3Vv_M1&ndd%Gwt!>mrzGT#QZ}=DM><9 zurR~5sf_9LAukD7B_MM-fLHD2{rLUAE4a)4~MmtsaEUMvbq29=4 zkK}Z$vc%BQq$iz}tBliZ)a_yIsjtJ_Keuj>N&(LplUyC}F(F05z^;BLZ{lrk8 z*`0*o2(!1jl!)sZ1cypatM=FP#C+iZRoCw<(FY`QHzD{cMLdNX{$o-eXfy89z0L&L6QaodMQ2`eYfLndq6eRbG(mbV<#u-teZoA(~ zxGN{wIKpiC$??rKUwnWQN~+$<*h2EqTatKmIGcxuvBX-1b&#?0rD|O@!oI?|;Jy6F za9ni^dck{5CGjU;qJ{DAN42&A?`Ba8JEu*5&04#~2UL>3{K$V*S_|QOUb?<$&Guu) zsC?B=sAi`m=2JcXuYVf?gZt)Bdt{y-eUzf+rMO?LFiI2}9+c(jQ9VlGot+-&FD37^97)UgMcRv9;0n z!@i&5L!aWqOk*2g6Do}j^VWo6%CJE(T)5IaLqMHhZsT=6neM2vAk31civ^y_*AUz_ zd>mn0MtNh9jj`n*$a%qaaFXm9m8nW4e5w)d3ct!wy&1GVZ8X9=d*i}~o1s`Nkg6&p z#gca;YW|HVqb}`I%WU3W8XW7|s9ZZhWh!Bh)^x@IYhB)lM|1Bp(_Re)vso|-Iq(C7 znvL_?iEp;0d4^T`XYJ2ud6ZVc1F0mZlMiYI1jXWx->yv?hl8vmqjV*kUc@xOJ!uJ{?SHK_b}C9RG3khytoL8zQKVoEBY0&z#@ZJXcYhTeTJFdYtSOOrdzAO3^W*%aAR5PVev z_p^cASgejxKs{#x>7|{jq~6$SKeqDUyGz<6W+qaJ{GC7d#qA_PN9~xU=#sASM0(E0 zHnQuVC8d@I&ScLIexk3nRO)MEVJ=%zS40o*!%!*_GohK}Q0m!0n0w9>5bE2J-4L1J z&f@|7;#5KJAMH7P)`gY25OXrpX%*x&wHs4sYGh$?uwN0}$XY!!)SE@FGB^$yR^WcX zRjrP@t5KYe6tRpLJ3~Fj1?N&BZ5Wky#`3A4gcz`>cI79x%1>udiA&e6_-2AmrQ(T2 zP(DIcrUJmY5OkD%(6ZWU^~8#|pxea+K`sOfR?359Knc}(iBN7Ph~ONQUq)ajO|P@c;}a(9&@uDnX=(7mcfFI_l64p{ru} z2V}gfC8P9KwoE;ucJB^Qdxn!kzX)lMsho^p$l5y{Sp7`LsoT8nHuy>T z!6J7O&+iUuWO1Vbcqw_ePV=SPwXd}fF%||<(aOhuK%a8@J>OW6bmsp4*DysOm*2Ch zH*LK6deIOHxr#dAsx&8^=0aNhPFBjyRKeS2M}FRCxjGr^r`pbHNiT%H6k;xeTfy@!<@JW3ehJ=Jdx!6NH0>$`)xV(c^m=MM(BeaW9gqUqsN`RRQlP)Gv zIFT`Md@fIuF&TLB_xP-!r>e3+g-GI@d}X(%V>kzzOii#{Wv&E<;G+%%LB|GQ4_1<4 zNmo>#G&c8J*V*B=clG@4&y1iPtqC@H#e@1CGTqf;Il5oSy!8> zgrl%gxUwsKm=agDRq)FJ#LEF75eR$!hKcB-vr|RT8`~D=O47qAY2jK~;o351@=7ih zW*zW*s&|A>kEFyib6%aNIpgsr!PhJ4Mamh$SCp%CM1PLcFfX7al7}Xc!)3srBx4&B z!O-|0xkzyY9LYb~wZ>g_eR8^c1CE2^KHdX#COiE7@A~M%bX-rs zkCbf>Iy6yE*s71goK#Y;i8@^X)&859+x4!1t#%b(ZSbDYTl~S@*?Ql`g_a^?a;S+= zjhrN>TtVD_axW!&O>)c*seH{IRhqs6y*%y3qh1#fTVi_$3;tJpPMs z235$324Ed|X@uv71(vvRHX*3HdEvfK;J%+_+St#$#ZVOr*BF(Z@z%Lsu9^DHu_lV)t4-_en}s;8Q&XX=T-3fF1c&<~DG#ww(f$;}%)z0B>E zxI0m|_D^3I2DaEx>@M|%_Eh5~Mk6abnL7l9Uy(<*H#us**9HH{nJ}SmMlzb{;h`r+ z+CzR86E9O`ic`ClH1AZJ>T@4I0mnCH!20^L-&I1l+(CQ;>AA|42<0t3qa`zXH!ec& z0R@0u$uo34$ODn!fv}%bSaQKtnq)4R-HnLVc0y-y$wST#P20Aeo-TO zPo>O3w6v$8fdekUoZ(@nhU)+B$)_O1{Cgh3@WRh%M=_C5S3HyXT$7hn&614FbB7oS zkr^c)Wk$oLEMcUPLKq83XNr^?rY-|^R& zYY@O0tz?#7Km**YU;lD*nTlewm63TMj@9!0zR|=}pQ?S`P%$GLbT~cplFnhG(n7Qf zvL-&Bm&j(1o)`x-rJa1DJq;T3Ue3o$>d3M%?qaN zHCZ&I-B7YZC(nePbNB#Sw+SWFT^<8a*cwaA3`&#qDTm}e3*z~`SNGu;)~i^PTi?GJJ?d`gnj4U>Dn4qBH835WReG_T_1@MW;a1L_HAB0y1b_%6;Mee` ziRwlY&Hc}q`V9Ahh>r{&8jOby+kVpd1#_6FI!bCyUfc)uTXAkflU-*(^vh|Cv^f`} z7G4o$>~@br%xZG^9|O`vUrp9Va%-OAx?MkKX~we|qp9dO#TiJl)d~jyywNvh*u{z! zlP&e$3>07DaevZLy!X#IZEN{zDCg3B#PQ{JudTNT4o;gHsJbJRk!%obQpZtNOsWHTKxadDpXxABk!>upHKR41j zmErKkqC5}l8;@;hn;X~HZzkn8zV?h66mlEEYTfZT1;L0xm2sV(w9ify{NgM0R!3Aj zX3!J296uaI7`&)5!M#(H_|Gnl{UBrHV!67&juPzWLSgGvVJo9|S4gw8Bj3Dkv-AI^|LB~5bj_C+Wma_ zz1rc_y)wHFBho_>&BN4tWf{<^sAtbqzq`aVauYLAjpfOAir-0n_xBh)V*@Rilk7X$ zI@G$Glz=KGnvWv=j|N0^g+*o_70(2t4h~eBfQrf746Lo+5Pt6f_h>KCZDD07bZJ(amM>E1JeN^z_t4IF361+vpHxM&5`KiYtWtq2H@VEkJ*&@Re=r8M5A3V?j+0BVT47|R7o zGfz?TanvkfDY^H_*6Kso-X}sm%d%`3^vs)uQOMr)fXwW$U2!$Mz7~tLFe7O+p<#GquB2z9;TI< zL(TE)$%OYgC#GEG%~nqSMN4JK53rq94DA{jGH$3lJ3vwdZ+C*ENHPrS+l> zqn53Q6J2gW1@+jvd*qV#iM0Ika`uVh zkBDWwSF9YGtQ{V45*BUF|7RoHx&BC7p1G7yh4;IO$%^7Uws1;EyzHUbdo?xHs(Vl4 zpsA7Pp6bZQz6dSftyd1RK-M0;zp4DJqh|*HR!k0vA2S|e!dTuwmkAs1W+IAH-vGV$(}eyOi&o@7~)rdZFx<6L%vB-ID;yhLFHL@Pw7aU zL2X&pfr-D|96bCe<%4=f$=AeJ#P#HQ^2Qpnyom2JagD>yJMjhYMK&NJ{Gkk=t2v|i zx{CQMgw2SP{~?CzX{0#w6>m@Jl9eFkyO2iV`OKxF9>@zv4&wT!POw2gA9~xS1)RHY zP|ThFox{PWN##Jx_8FAehuc3>UJu<(_A-*a%M4ZYEmyTMR((xZ0$-WiK3-4-qYW}I z+edMI8`!h@QlV~Lbf=?T1?pnF0C{N9v2eueRN}H!*i;3!cvQu!ZtV|I6;qEDVyd`$ zbjad>V~7y3=QE9GKr32V;^@Gv(&pCA4X?9wA87Y$jIoBYCPP!P8nB&`=<0u~IVE9T zbZd<5D6`gxjq8+G$*B7SaR+Vs>UNp?E6!WyNeBEz(&tHQpt+ikNz`o)+xi&bU9m|x zQb!@)Gl>zGJOxf;^Rtyg{{=BIOexM*>d|<&n3cVDcT0m|m{rL}WI+|NJUTUOnG3nM z3*nT!30k}wUuad_y9*ml)!Z3s)#iKJO;$g0_O=tO2*(bxe`wS2VJRfpW?Z1`Omn}i z&2Vs0U9tuMc_h;1sg)se@<;u!DQ+2&l1%Qhz z;C6kVXd8OZuwC|kpM5|jcKvH0=x1)|F(UNY=b$1h?Jq0}okjQcKQdntnuR4pZy##^ z(l}u#6x}YYp{z;Ns?qEqlgtPzG5wq%92M6M?j>yNQ+>$v9y@O8|Js-JxKXS2v@QrbSYpZ;4h=P2sIVrsVGI#5JhJENz0!m_BdA|8>T=yz=H zqD_d3{}^fvzq~r_&MW3}6!l9$m$VED^~k7z*mzXPGkOtURH|1Lc~o2xr9EX%CJ0RF zFwXBV2F8!dLEeQu4SlA_ST>|a;- z>aSczZq)f_(zM-yeR5wT(#8;(%O~ee7~kV_vINv zIgEWe4&<2(U@bV5?`x`4Myiv6bzkRs1U?A2?_*itl7~{qR_$zyPCDQ`+VqSW|467{ z)ir9PziEc%sjtk^5~FYvv+%MYciCCUvN7`l(QJV|A!J)>T&S3wmfa0PBpvmur}!6R z*a-IJ&Z{hgm?5dPeZ~<=aHXf$1b5Fiff{ni%<2P0=VYrJ{&x{ zX4TNNJnfkw*mkDs;0bY9J4B%r1sj;k8j5J;0QRTUj{5=#3K`cGp+S#qXfWN?9q_79 z4;jQFZRe;^EP`HiWnOvTkBV|(PSt9L4kofKeL#jl-bcZaVAcI%`Q|d=+XfQ@S-&qu+FI1?h83k^MeVm58@=yORTi@al~9xn zDYQu@3bORF8opr&cJO#o$7R`emZkTFM%DlYpl*iiYeRQw9WSF622rz~r(z?AwkqBP zSeXE%I9WSG2q=x2L=(m+>23wX{FMO21mrzd3m{?z$HWQc%2#9vU)&Sow>HclYf?A} z%-d8Z_|!@?EBl5i(FDZs0k?P6ehY0#(O(d;kyw$?>i8?0$%zMS$P1Qr=};SE1TpNl zIjFLDu4%>1(3#yRRr(c}-3*G;t{Rdkb>byKX#|sPs^3Iub|m>=pA}DO#L0{Tz-6}|M&|=F@NN>cB3>VECYh*{S@J}nIHYq+rLHgXHX&Up zb~W5N6zeTD|11!cuz4OwJ!(t3UKk)0R9+QUHCU0N_7%ab)$p%K+l5;0W~X%7^^UwB260%%OgV|04-(&4hlv_9ktdqz=mUKrv_p-D6?Kml+)j|_&lCqM zzm``mOwX>B9`MXv_c8a6L%fxDM0{&Ef~wQu1B?R*{ifJujVHg#iGuoE7e1gfFTUiF zs+V$yw^3p_YfQ2VW7Hy;_POfbu}_)Dh26>dhPaQ;mqhXh)>*r4S;>Q0MF+wl;8mTPk7C`*(KN z@0iA;?WWV^G!nG_Bt7T(oNrvC^49!@>jGqh+{c(HHDPRTvoJx3InNLx_e8Ut$U#o! zYt&4BZtWk4UHruz6|bs{;#hGiW8GaARi3)cpD~v6c&l50he~$tR!xd|sTnxEv=Bz^ zxm1Iit=$QNy@4_TTFG>_LJO&{S*ve%I5Md6tF#_+93Cg-$X>wIQ)aj zA5gkq$mo7$F`+!r)qAmtLN=ShCkt`B;q0xqWJ$ZfDPYDCavbz9V}ilP+?>rqMlXme zZTh*Ij}?JkE747g6wu`M>x2GvLx){U_JFX9uViYFhO9}9>gtc@C=ki&rTHUzLq{3# zh-$1$ypibs5L@70uGXHjVK?*#434`6q2M`8Oj>3nbf|Byb)PyjoIZQ9(M-gd;?W}? z3k?ftA}UJmpmDjldTxYfF%s(?ka>AS8}29f^5zMqndo=&Zp6)qGMRTLHGRann%PH! z_;Mnhu0}L8g4zklq3Ys0YNg$hG?D9Ek?|@mCC?) zG3L?pPXUsH1AX0jq@6TH7w6uamW8il)g(>q9j?#)h3;phVd40O!1sy$GiHtcN77Y* zMb&iSPY@6(=?0}sx)BfwkzUv(q)QNxUOEJ%mQcED5m}Z7>6Gq}?q-pcZul?$&+|Tq zVQ$UrojY;nocG+{X3cVX9+35Q2Ol{Jc@Fj77s#J?=G%O8s^wCuJlI4zUB!SMSM-$j zLqogWd7s^|q3J~L-og5rd+(k!aUodHjOF0zy^`vAeCmGOO)xE4OZ%#O$`q4&ch~8^ zwLIW(J7;0YL3P+bbnLzR+8WJk;_<+%v(|z~#xE~}Pzr*PJ{$^Cq;WnRE@r?6(hVW$ zb=pkc%9{7a8cOEPGNhL(Ay&vnjlYLF#XD-CiKV4!W|&Sc6(i=um22c9JEjQ>EoAQy zG!s4IGilN*bQddJ*Zr{}-`Nc*N%DLi1D@0ZlEHC<-Dj|+flhpxpZ+L=1LqPRw8QcUKU`oYjf?O{bkkrco3%H?8S})J~F4g$y zU8fiD8|FA0B%~vA%)Yq1C38LEf&v(G`0zFO(E;yr6Wr_ArAzyhJtsR?^*Nv%1om!9 zT1LzTo<1}(#>)=?2SVm0 zdmJrGk#Eg%DEAuk)N=8@bO&J0+%q z_c#~pxOdeLhpISjs;fTPJhTOxm%W+haGM6X32rldaXYur!Tp3mqrK_z@g*t7niH)d z8+nM%8W}SAkIn7?ETyE2uIM32Sr$$!T&^SRBs2t#$E3}ZDOC!Rj&<~}91?mO9Q`{x zS8xmR@$cKDJwUs{KN)XU)<1N;^C~7GhN6urgqJzQ5rm%8zU`*FU^HC5f%*d_OHatT z_~WcbEdMr1;493oBq+NT;Gs<>%CGI2oiKA1BTEfS_ z)aTw=`!hVZ@c0fE&CM_5dU1qrytwny{8WHUT>Vy8Qi2*8VFV%HS>|x8r&X)bQFEs? zkmsA8C?^AMBBM%TY+y}~X#X~Ds#wroCQQU%8r8M`U}NKkDG!-iE+&QCGJ@`OuOsFg z$?H5h{cA9_i)(kpYlF;w*gD>Eir3>$W^ZkYE24RYMbp9i>7=7kieF@(t!OyFaW>GY zTIJA_;g1Y{*=XRpbyDJFfzLrfDM;Ky`F~SZvsI2 ztSWUW63!=BMFuY6_?4E_Sy-|KHuQ}1j_~9D#9fPBY9At5Gt35j3Q>QSe6EHoeJ@V3 zjPH*6mde zt$9wQJrJJ zt?k)N?+syoVF1;Aw3y%8cr|z;kw&`r z{Xfh05;^|khWtkc<-ytx4)8MVu@9=Z$o@>h_FMt-x@d}$vT8S@iXV&WTL7j77_Vpc zinyWmoagUtp)vuNYRu`WI3v=n;h1L^p?@iO2`-L(^%PyrueJAUUvKGDIc^m>nA78L zI9Ar`FP?8{0h*@SU<%Sb18WGT%KqnGT4(o*ZwGN#UVrISJ-(ir8jz40(|5@e?mZ-J zjeunNW|a%+zb-F*w5@BU^zB9|xhD?h&F$wF`UHKwECJ_f3FH?L1bauB`N>g@3V=hB zX4LICmD@{s2XbLQ(=}(9kJ!qHM7EhSsJxiRyK=R1r$002V)v?Ijzg;9HF+w$)Rt2a z&VE(jii2r)|9Ou-Vb7Sr<;V24*EH7XHttXH+^gN46-g3bLjv_8k9Du<4U(^oy^T+j z92_rM4DOn4y$QDCA48Ski_s3N&oNVj0ya&?wXU1XjO8T{A}%2+$IWG6`KJds+5s0I zRx4CiEA}IrzD9nEiu_c}Pb{MQA4uojI7DfDq6tbV1qvMU6_^HmpA|qwEA~ZBB!uYl z9p6B9(-CH==aXh~S}Mnjx}Rf|`+M>%W0e61(0q8N$P*bLTLEZ=X1G5oa&7qbGYVS| z%W3HQJG<-MRlZdDGCWw%eI;*c%M36w12=Wxx$$by;F4hFa^UY5|GtoH**TV8cEYAh zT6Q}9^O_`ewXz0KOQZ>O2~*Bl*l7W5A;s^RFFIbY@M?%gA{}dgv8DpW>7o($ECNu! zUS1z%_?B;QPV_6uSR)?E*H@h$R@{p-pQeG*oojnjRMkelH(;r%wP)pF7lXc*s((&@ z9^K=}aF-G0pA>daZIR2q?Ri};?PeZNpUWX_Z`H}k?R8z(&$Z7V(J+9N41<5iU(Uu~ zMkLQPacYb5Ij9Y!DG$u;?Ir-EVkY#ehdtE0x$K%ALB6=IsF-%L-SYp9AL*~uryqn=u1$5C!sC?p-2`~=>~|o#$79KJh7wI7LCFa0PZwdmo3Qyp8PU zi|l5P4IYQG#2+5(v{vym#Usj*+)D#eiX;M{4HnRbyGa&MN2i;HUIF#Yy7%6^nJ}+K znMBdE1&bxs8TXp5T-G{xtN}<5!s_nmm#a*Ws#tFRz$Su_1&G5MR8OMgM#hNjETVv1b)b*9UbOVdFyU;zQbQHGFQ7&&Hl zc~Gr=Jo28dSnUvjzLG&F7UadiYb;R-lg>FLo)=cc*81 zl0io5qs4KtXd&_q`#+%DBu;pvszBQ(?lZQCn58}${fhWo-y$rwp zFhE+`+`B6_QibRGDR+BzKaEeP@v1pI7zh=S-<+)MTkfqR>*PElmQrrWZ@whb5W+Bf zKB&TGrHon{iFiW?#vmf+jRgF9l*R>hkqMD&{Qhnli8gV$s zkE!a}2YR+g8YsMRPucw&ecJV?28%WB8H;rdtd!M`bF7z;w~%oVX)i5x-Z%DGpP(0SIL;=m!M(Uk97D*I8}p4rK` zBypy{*V-KlCorVl_nG{O=Qx&90fFlQtZ0sidh;VN*rxG~ zOvo&fc?{rxoeA!4Z1KSMMge}qH&f`haqOGE(vh_F%>gA2V8f+bN2#1L8aA%C5Z%S$ zas$IWM4HOz7B%h|NmMg16zytmO({&2E>Lg$tb$NJd_`-RxvsoQSh+>H_q^3G&n320 z4HZ!sHhE_U9*YeO)*{R@+gm*YfO&3n$L7M4xW#TYX>is&>m8v*0!~HWgw_$1qt(9I z z+sZ^4;2~|~)|EmUf~f{4Fme+GESogr)c13E%;i9z@WA@H&U`#;)nWXw^f`918e{8x z%%>#*fwo|bseZ&wC|z|<=%-U3PfAq85hahH&JUli{+T9?fq=WbY=0g{d4QInig7fu zFImA-C9W@-hoMhp2A1T~mqSO5=vG+BH^Rb}!;l}Ei%+lN0c-q-?8fmKi9hs!o*7wE z8D)q3c-4ke6$cP&FgOpyGkZXFEnF?oX=e}(t2mM*Dz0sE`Mje%8nQe0jop+lxCrs) z5LDGVp)cj33i5ODuxcI>tsgW1PuWO3r3apZqSO6UYa+-6Z`>gF2vTYo(ZzDp_r*9R z!PpaTzo?J45g{+2A%z#Op39MCghek$FE;Wv+AGc@#NjE+eNV-&tm(b=UEmLn5wQFOxJfJqy%U_B41>`&4SOQ(I=w3$r3w-S0PtLX*e8PxwV19T zgfqd^>IK4gA;ExC{nBk&hs5syn5-cOepC30u>8eR`gnjg=ZKAb)sBc2zg}f*ksiBV zs$Sr^iN6dV#$9}%bW`||@CM-`>bo}Gim#fDCH5jX4c$TUZwN`_3J@B!P^fh< z<><+Q%LmTYyG5&Nb&6$d^jC%XXA07v`nVfScU4jX&Z9HVY;)EBjnKZ2C3Um0B48FR z!(zo3w`m?9wQlZc)0Ke|2c7F!+|r_Mp^-IDXJ2dJKJI)hoJsmz78jYgr6sSBcCg0cVF?Gwch5U#o;)`((xG9d4h$B5N)Aa-@3H+kz_h)_&>5Ti|n; zX(b3u$GK}AI}4ZMfE^wEY_|xcoAe_jIL_R{lbU4wj7mKtU-c59U zw=tJ@S`;B{0ak5}%)|zNn#`N<)CQJ2R7A_q7d-t8leWH6Ls$XmTPiQ5@!7cKX8-Hj z$GsVNgdy!E-0Gn(;h0ayU#}c-V!e}m;*Y+P1PTm*YnFlvrb1qImn%;`w<&h?#NQ># zP|dCk=WeOcLu=IQPJq)Y zCG395$?&0==EE-%*wU3qxD(hGO9euAW4DlR+_DB^pxcM801CQ~7iV{b!w1skJ`BM~ znwRFEfg&HnVh}}>X-}@^rMe&H9@BPW4H1M53kunDVaPd;mSMZ?yQ{?-W@l>gIy^&X>gMoicgxR~r%uen^uO}^*Qg`)#uSFK`Ph|;I*Vp(D z)ov|5X&_^JhsOM_XR&rhNZCp)T`b0BKj!KBHOE z_q$Q#>t+P(2Y^Cnt^3>w1^+~u#AhCL;!5GY*|R`hLvPC8G7ln_mUZ^Y_LW48;x z2L`LJO%JF?b1+zxA+=h-6c|O@GSFhn-Y{QjHd1eCo#W#`X8WWF^sT4>4 z^KXP({;gLi^v5Lw>RGq9{Cid?5OHWw&GEEptZ1$gv&Ziv5nH>VPaf%TugX^ccht<} zX{>qF>|-(-=p*%ro_0d(wiS-C>(F|qu%IJ_=dE46IwtxkzW8D{%rIZAK`VbDPwg5@ zvVb$|@KIJKEmw0;=Tye2EJo#LZ-Ux$gh-rvx|q?`palIK!#^N*P{h0ReW^aH>6W^* zUI9-$i68Kb%ldGBA{sTfL zo6-IvuPl6WZ*|Q&MEk3bv38zNO3tdD;f5aUT5@rVx_AZ~@(&y8;8D9-C26?`svaWM zyMI>s=W^J=aZE0X1QGMb&EENA-2;=FYk(%R22!p`-gk)BaP(xjE|)X)&J$4m{qWc5 zsWaQ4|LItwdl^cz9N@<=qAoX~?laPcv5k05OIktxjkcdu^k0jmA0V>w!nQp6Qr&;S~M38Q92tHI&*L37I$6PYPd1TUxZwdA?Z2~9vIBhvlula+x5 z>m^akcHbkPUds(YhEp>Kna2L&We!?NO4kZ7Vjd~%h)2CT4z0>n35RX?hQEMr{MXzy z#@TkyTrm!O+53I^qre{`(%Dk~W|7O2tb>KZ#Hxg%;`pl5JO*K<3Aut)IQTX;9LZ^a zcY17R6FNTq^n@!QlNp)0v2$T<{W0uTE&TTG%2T?^Qu-jj8dqzcROG&m#9cnOhjXh-4~ZmZ@u{$qbNTPDEj(SEXlRRY>8BC zi!^T)6P>ESGkcMlmu_yhB%%RmtVlEz&h;EA)=k?T%T=nJaa_`?dmwBHCS0Py%){7Y zx#VJwoKAFfh-o&ZXf}ms-d=}h52q$=i<-z+R(qk3brS?pr7zU0BNmz;sCfx*@I zVzy*@hWsT&XMRVbhhHw_En|BwWcZdERm?gp>{(r3O6WdAT6q<_hU8>8&D+$0)4Ypk z)JtGAJ~CwXN|qyts~B5dbL%W>_9!#tD|ARNA4$R8)Zr`S5i6)S(_VVzkZ-P1vMc8h zyQNxjg|@VpF>7Pt=wRVkY7=x&vYHT%WCm4PK&pH|>QMRb&2lf@0LfcpNLau#@CnZU z4$PuQ8OPIX565}u`a;il9Z2ecca)jTbOiqZ65gf=rqF{>EO~09A4hOAahBX=>mwGNW zYg(dWS#A3J2EcoKFz36HD?JdRtZ;t~CpV1^pQux2l6sk(zL_)iq%&0g1TEa?d7;sA zLo{uHW&5$4d|-0~^tp8SD4OoU(i?3z1gQ3Ytd@V@UmP?o3r&X85FQl?Vl;Pv|exfp@F;{+neR{a~ zd%5^IiT*Ckra)q$a186<5YSuC+&B zIMrABS_rDEgnShYnd9n}jJG40kuW((43yrdM1b3jXSkED_{o$Ds5_jCCW4Em&{>bb zKpWnwNJ61UN%dOtQ)<)MB_@gYF zAf>3D;gh<#0ZE1zqAUZ!M3f+>ozQ{Kn84c!sD2XI{e&4OKCKo0o5Dsic#|W8i;%%s zU$Qxs&VCA1=VWD;tKP;_qlwA&@W;kluD^&Q4UYfkjA9-^^&Et5u~9_F&`3qd67?i* z@;g=`1XO{Q&ah%j+$_v#d_A2)U#0H|E7_WLd4?@NMYnbW-raqH7O5ie?ng?zioozM zE)q)bo}UY(=U#3Lj>ZUka^#%Qx}-1*hWD(gdP7-00cBaenH2${nPGWlH-&2F5ZxRl zh+JaI4D}w0@(O#QEV}h2XsAy{dZ-TGGreYo3njxRgCizg%AUzr(Xp;!kaF}m&NH_k z%69(za;r9dP=q>>{cuo{JORirb85AFMe}E}O!{r&tVJ%`ul~;TU8((O1i+nglo`~) z#(ze`q!3e%#l<NBrZJWl8vFYFLIOb=F5)f#?6GxU}dYlBUy@tA_-aKZz_g;VMcq z%Ag|x`K`>L+19dl*&lzu4a*q!2)xF1RKoo`27=qQj2z+^-n3ys{n~!Ba`|c}-aSg7 zgpo*DAB4hv2+Cb#LCsd_z~d~Z&9yI+k>z-eU6YkC=Z~+A z{x-|;gz|{?;)ml2_S>u%!@t-#=q`)a(u8~}LmaeGUKxjGhHb4@mdjbtF6H6?8WCdJ zDYnuU1HoebbPVH7@-3{jI>}!Lx=OqL%gRBl=6*FoMms5=~(t{_Du* z68z~KU=K3L-i__*N@L6hkaopIViVWt+rHe_d#K3Z_wAE?se4Vf|K^l$*s8C-Reb=Y zPi-kd#X5lgTl7tT;Ih^URs-L*39F6mEFSgJ>1|mSa{g}Clr=5>Zs{c;vgg#_KeA4v zsQ$tKZe`%oJxFPfX7I|i)vtejO9I>WrB5B@I*5swT6gp}%3I+xG1|+(b*NAE*Mo@2 z1^|WpiNm0B;gdr=U!P8Ox|`da>Fs05Yf`HxNW$LAi&q_O`1YL^8bpTk=;FL2`o2A8 zs{8d!?uJVH^(e8kZ0&bO$-otr$8E0s!EOM0Nv^)#iko&4X>(b!=5UjVU&vu)!GruY zX5e*df>Z3NJ1A2_j;?Esml0dfSj9V-#n)v-BpzcJO%2hkftg%6h`fpwYfCc3x-wGS zKP>hSl;Yr;JyB~ciINcoqFAKz8QFFf;S~RR#^h;;mGXM*%~^KQOwgpU>58;*f*n(o z9aHh{)ec%7MWDjHROj$#Ep^dTuJo(Y?zDTHTWK}Ri<>XQ!xeshl4r%q1ETLfq!*<) z`AJ6eoAOabj3QbVL=#f5E2J*JrDSV*!HX2*NyT=&MO@jyazRO_ef=f2=2X#ByB>o^ zO`A|!6?CWqe5i+gDIhd3gke-;y+}aWZ@;TSa53*sLpr4r<)098wZ<8SMZ3IL3sD)z zA?vP%qdY(Wa$l9(4@Vlrhh}n($^G{$Guge0f|TrTYDNychFD{#usw?n{snF8W;0RBo}+2R^10^a(!Cq!2!GF<l-LFee=Pm1p@SDK6n?RTG z{GCV_=Ngs$L_PoO=M1thVd<|K$Km32y1n1NHuo1c+ZyV3n^m7D|MRBsm|8XraxZS+ z7ki2@|6O4I+m<%Yn1CZ&Vg{LEH(_K|X}*!;R_7EOjjYH;?m{4!JBJ%3!nK8X`!>JV zRxYWBmptyS=GgRD#M8s^t@^~5X8QfJ#3a+{PVst;)O^FfOUbFt#9*R+=A;M+x@e;U zRW`@TUA7}GM~o@w>P7HJG*)Yn9meEh(Y1I?H38#utwT=n>EC*>Q@q~bJ5xB^*bqqw zG)Q52`){dLfoKop?A;hd8hS-4Z2^|s@ys-Y2@6N^%r>`IMaBVfofCtIWK3_%a=Olt z=Z3RUPAg@O1k22j1Rr5Wau~O*q?%0m-jjU{!@Dj#Vb@{C;maor$AM07&jm*%2etPc zt=_nk@J6F`6{2lUtrZb19J?97*2=}{3LA=6{=;H8@+P{Jw4{xR`3P@LK{x>PnO@n1 z^|?7WDO;8-UMcKrNmf?BZ#lZ9oX{jSvaw(`oLd2{B}BU%oNiSmw8N|8YEYZ}`u?ze zF2en}ihuU%tWMj_bpo=23{q5t^u-E3H(t8}fugf&G@nYHezwrjXJ!eYS*i~*pY4>F zpV(eMjCFvWdjCiGND7ixA|I%HBy+8np8P_`{^oaDfo*o_m7qjz=j3&0|W#}?W7a?k|Yg@alpgXKEbupjND&< z<(vv2&xYw$QRxQLqpm+&9CaKg@OAbo#sa=NSE|@27KkYG8>*AI6L&8BtS2D0BvI}5 z?j}AJ4j;*q+rm+hv23&!uQ29c+&%th9+&PuQT{d#I4LtZ(^~vY;zz#L$1(r}dQHm_ zqvL0Eujr2WG+KVC_{5;rv6tyElVXleOngRNwZo$bRt&Ud)k)eAMQ(gnTez&^?Rr`8 zfZ5=(7lni`NZO!93STsyOqEk@89c!`ye63=CNryY%j7>DJC0BP3`EW`&C<3-vFG0{ zd1mHiRV*5GV}0QOgb=}2ez!xtf}25-?i zRcf1AVJVKZ$`S_!4g{OThD(|CpG;KnyVe8wgh;qXp+2onZ$O(0BqMSYq9CCmxQ#&+ zTeb#n-DQfEnucpeCEN{J-fmqFUw)7(Mmh(f zhfaVk|C4GqN`tF7=3JCS*_L|cFSfSCFB_{)8)_#};?7OEa5U@iR8axcgv|YncMmT0!<(gHdXL# zo3%*z5L1|(GQ2-->!|3!_b;Yk3bE=YSL(n-R|4G zPk(HlqvzDV!#NWdOapiJz9&UZp?~?5o0_4r-}J%x{?xPY!lG}}Y zd;+oMMvgiD%wdYFlX0Y+6>w^%g zMU8g-zRRF{I#{cqS>PMOWCaxsHm~2CGW3H=Tuqhr}>j!JB1`S2;0N zeB%=KU}AlXSUmuGdm9(OtTkCv$7go@q&&4wv#4Vvi6Q%P2@;%ClL(f{xLv$=XCX!A zU)5>0rA3aI-M8bR0Lta~ZNGR;f3gC(xvZ{bTzH73^ej_s2Z`{rh633cpve>iiO5SE zCi0tx_lYg#$Au0HlX^ly5CL7GBd`^TYvN&sY}0`oeVQqc+^xRAzj~yo+jj1NyA+T^;dt zDf&E$!wU|}Yz;o;Yv6sOHqo$B|?p z{h$CPA?1M}Sp55o2iai&4zJ^Am@=}Wo0bHPPkPY;y{H(VS3ZjS;#Gt9RchSbfk(~t zbbz{QEqvmg8MLBn`^M|DefDRJW7S_ibKYN_k?u>c(KMT`Lx!`q7iwrD#(DU64K1b{ zI{JDP6{~p|=aPaWZ`0U_e!eqNW|`LXuEc>8Wg@XSAhw}!A%74s6gXf^=j{I0HW9WZsF47c%a1u90cnZbC?y%L;V6_}9zKj< zzqUAy#+oCW;l@!uFAGE!8MV1c>pog{YdWQ1zK?_T3y!3M4SwVhDt9W(w$nv6Qys8Q zTzi&*PbPNJ3$FhISzi(~zlqel3o6ZC?DHQXX6WhBN?&ImO3lBR3IbhX8GAyLxV8VXYKBY8+?)jYh$f$bjANtDJ5bF}hdmj5!xD&;lo^F&~L;!B)88 zIErbCXKjsNs+v@{rD1k+ZmPL^Z?lE&`8(jcoPtz<48`V;9_d>JsdjMWX6cjFJMi0Y zG$F(jS8`QSoaUB@Ld2Uy@QeQU!FH77U%|UwuX8m=>20lkx{^^X zVW9<&iycr-ac)*iPk5r4Ds_5B&hr(pMdt`9bz0lKHP~3yuCGlf@!}McC=3)po46}7 zC<>6tTYZIznE*Sc5USI3qB}kw5)YIZR$*1w15oPOmw4&vPiyX&4`%AQ0bBjxAfU4< zwJMCUVj<<^|5gAl>UsS`vz!4vMX6IKl7k7TFeump9+9zSW_6knsapWH>p);6!h9%1 zbvTYpEs!tzgW@)R*(Qcs-WEM}GddZnbe5hRw%(=)%FctcDrl#L!#v;&nR>;4wt_Wm z)yHSGHh&6Kz%q4F(VyuOdbW#VCR*rY(}fCZLjr>G%!u6LrM3clE0Tr!SNT`- zH4h&%4t<0hWU)3pBHU-$^U2Q9iU2p>5&S-O71i<$@RT#sw(ey5seJOg&=glwmQR`G zBYMeJT&|Ha?V7h9j68No0{dnC0;$@Ut`-(Td5f_Px*{pInoX{ZE`xG|k{}m#z4D#i z_IbULwt;O)s)QDn`s46@AGOO*Me^nU%?YV^Ex7|4e!$84tt~R&0Vk?vWrD&es#hRO zGNp-z^fdiwaGo|S_p_d&DOn^}t=8dV**Jcn_Hgukuj-I$3#66pdUwip4VA|XxOBWH zKw^SZ2stX@CGpk)1v&n3?&(&=KT=T8oEh*!_4G6{tl=G32NRjur0x^OReL0>6^|O| z=RH`Y=l#O+)Y|5~>*HT(Kd!tm7X>G#1pfYbxK8BZI*JA$NoXztmeq+jie^?%dOuN6(MJR1bOOchk9n;fC;MV?c+-uO`=&9M9f<5<1dYW+3fv!#X_O53-w5)iU4H!<>}+|rCKE6=;QxxvmHn9h z0L!rNru$kZ33!5EGfEQbgJ9*mKl~In3_MKO*tzW`9G?t?1zB@gW(Cd;ov(S2$&Hs^ z&t+8>nckQaf$hx*%L+ag?A+@H>XUTd?j~7 zs@TmBAnY8fDgg42#9Y7BpahlEw)Cy)0;6Q&pb(bX5xF#LIBh~dSb7jtr*b-$UXK%p zhb)~+>DF^10f4#L#cl@|ml@e4 z^RVYw`=6DQzq9Ct5dYCR%A~w3vx4m%F-T|r)kn46i7JF^Ey9(}TyZD`cwGk`g-Zfd z>UOW3GJ0tpPOpo`a>sI~=prkwyzmwHC#H@wYPxVYf0@wP^|(}gMU?#t~?Enu?{$lvyRjnqxSddw)We7!D?I2u#Top$v<;Rtl1DM)+hE#lPER{A?+xtLb8e-9y0{O^3QmMtEX4IfU=~L^z@^{R&e6Ud%dHn zpi#}NvC%QEQ!!e}K_KaX(#pW#4a}3u&&|}^cDWiN9Z!s59q1v}PB_FjDjVm7R_tAwrRYDH&4$oQNiDC!`-(k%t|ea)1+X)mr>#9Rtqq>X)t zi_GK1t6_YGvT+HwX90PO<#B)92wf_}>hy$^ItrZX#{J!nj=4^=Xqik4?suPK_uo@u zYu8^5M{lAh=)w7wK`CNYT)kQQ>+0w6GZ?hG+d* zTl%)&uR!-R@j+X?`lRo6JuA*LN`lx(EOttQn}|;K%w-b-v9csx24Z_8sBc`>wfd9&M2x3pO`CWnS4fBqZ4I&aB-=8i;8YDDY%~x57gVHb>|JRy$=7U z|7XK6O9_v4505>-B7WXyOSnK z^o?_uk{PyU8o+z<&!ala7oYOTQ*Qblty4eFx!29ftYl7@S8fxpz*^YDFl0%Hs<25{ zcHa&mQeFzrJD7;u@78B_ex$}3JhnZQ3SO!qZmJl+-(APn+a^5s`|vn|5zTbs$(Lv< zlY*t$!$9(w#}SHw5Jv2~r&tdhFKswR+X-$SS9wMsS+%+~OMf2VQo6-(ZZqhNLnN2f zLL%i|I~c^xAc^I`fhLEd{|D&G*RlOw&lpc^7dMuQ(y1&n06b`aVe5xFRV7{s+rcv zr{G{N$mvCeDd9|+jfE`1u1?chv~R$judnvv7&5Kh8{-N38c+B?)CMlw!HNpUmOho)Hx?N1#(K#^E052{hh&nc%UN zlPm2)5~h7oo;|^So;k)wke2!0)v^&Ao}aUYX5tyvad}d{`EA>p_x|6=8F3xj{<3WQ zx@7a{!Z2`8Fq9>4WBdiulf16XUGAG4B$pl(@U1qZ7CeG8g*Fx4+E}79kJ5MlczETh4+Sf`e6D>p@Gn#{n4VDQ1-2*%i zL|Te-YxzDmlEhIQM}FGMAO4VdCbo$9`rF1gUTAXW6IR2XNlmdppO4oV7^2GP3Lzxts}^1S0PYY^EDh#b~FLE#%M$EyB0*O-vm@_Uu($}MQi47T_GLW z&>lcZll&`Sg0R*-{mRn9ldqyN`Q%Ban$C1oLN24>mZDD2SjMQ;)N8&b4jWCJTw z^30*J9J4bDlk^KYRdaBN0|al$!<=&K6}k8@1e$5i`Qjn6>8a^Ujx#~G#ptDc8$9aM z9%ZN6LsQh7cU2mi#eIP0$sHYx9LMT;Prp1B)P(nG|4mv0QrP|3BLT4tmi)2!u|F;f z274Ppz5rK~R3z)R_EEUiAnV;uz$yE_kkoDv%sYyJEWdW@f`1Wag9q0qOPvbdghB>) zp8NN_ajzc9C`L+98*7&_n6H_zS+|hQmO@Ce*CK*B-N>SDU~|>tpbbNKUv5VEliL;n zGBZ4ezc34Y@N33jA#S8`Qc4b$i7dS zRyU~ZRO;x)AdhU*BZonQE4cv*n8Dq8;)xA8sOM>T+whY=uf)jUwK{g4zKngPgd0;# zeFr?ZU0MFa2T;G#{sU;2YI)_BRa6-&yF2dU=XA6CTe07uXjf45PNt;(uy(5UeV*xC$jmK;{~CY6Q$7H;kT7F{ zNfM5y$Tt?nPY-tv|I&83Q!IhbD#OgFZDxMqZ80?bk$2O&+{*y9Q9~^O=r?^-pm|Ai zDI0d7uk7dTsIO{Y*!!s}`uF7Uur24ie=3g;d$opQHJnLv5IZApBmIc-f9!|Bq`py1 zvZ!FH{Wo~5<~0JU1Gc4u4~rg|_>HsSe;1a&UceD18p$P=9}j0hdZ_Fg#H#J9vY!7? z-X9dzeMBYNB@MlC=Z4XdLkqaKH4Tqky=xA}&$a<1NJp%fItSjzg!VbGSoJq5ydc}2ogjrZWuU0zwICWZ?@0<^wMgOw}bo*&*XK(S( zE_MNK4Bl%%%<2fe;1dIpU_|c~dt(V4m~1wADaz1AhD4X-_V3UP}xn}fo- z6}T$_Ak)J4O1D%?&XSn%Vp^S?Is6!?#29z!nWHC6YBnOimIC6 ze;7y2e>47xIYCs{vyHsd?FN)-U3w)5=&to6oRjPTIzbMjXFKcZin`HXHoh5e80Y|m zK})69?(|gA4(%=W%*DCo*Br6y@)QA7 ztGQf8>pZ&aJl`Y+sKE}5c>jKwB|fZ69sqA4!W|{5<6*;g9ah5O!;u-4?Iv4zA&Xyf zzMhBYGItXY+8e56imX{rH<})^sC#vRrVfY3_;}jkcoB(}pRaydTnY30rdeD?i%3+P z=7l6^zk2DG8SN?L*3z}FBSat*9kt%^PAxs&_jH-C577~NJ6)#Pu4H-hi&R`ZBU&xL z|LLV8mbM$Sls}_*t1Xtt-m^x4qdfaY*#|-Ub|P6}BALZ+Ig~o1d_M}xbL{&KYr}E% zIYHk_hYVeOPI%PwliJz%bqp6*lw}r#)Kob@|_pZ+>!v$R4X!&oo)zfX}S7~-f_Qe$gtMt z`Ra<=mr{xg*o(q=4#l9J3mJPaw-MjCfFVl%qS5 zyy07=y4W?iDzNddNJhdRASPL;)ta2!kUpxhcspT!JHb;-qP&t=CqqrRYt&N{^{&v3 zkvegG*Jh|h`?h4hPP>vlKcN9lLwMt-bFTNk#h`P=2hUD=BG*#(orM2Y^&Q}FHEsV7 zf`}l(>QYF8)q5wAtdcyzDyxUpt=>C91gk|v^pYj&Dyw%vtlpyc-aFAP-|@cR_5WYr zHNWegnS1WJ&&-^ebI#PWqj4DO>$EfF6RQ|D?fAUuCe|1H>NH6JV%1I)@8|V7scn(N zKXaE(XG&6M%6o>*d2OsCn@f$MN~pb&`Lf9Ci;LZdsOOU3^(k?83aq>SSqYmMKW$Pj zZ24dfD!S$DEsvJmcS#{&UVFf7At5-cL!0V4xRQ+7i!yNC&Y$)81Gs$Mx9jrRO4FOg(;f`N~3e{Xaa#S0{o3+xg6| z^Cr|v%V@s!cBKZhB$w*cl&PAk7lGS5gR5~c4@=rd62y`y0cZ`YnAe;I?)F`zc&$?S zXt#ex!tL}+&AfyRqJ$ zF8y2W`0PrmZh+|G--q+Z{Kc@yw_od?P0WBve z7{6zu(e&@QgF)hg@rgAl^c(o(wBIy22^q6@2fvmq=xC|klZ-#KBmB+Hz6ZOQ`S$Re zAZHx2G<=DKG2Nsm5egPm!E)?90&;@W`(^h2sb;3|KnH%1`))n_W-~OcRG0 zi74zteExG#`sK23@G;f|(VX|9Oxa>|Bk>12nQZ^KE!NJWLEZ}O-*p2j0Uis6R^w5n z-apBtZ3(UNpS(ZPujI!^I6u*Qb>8%+B%-G=<{(7J3OZ15$Lua?wWg|DvCDLqoGiuP zkb?wWhivF>5jy2q;3N^Fa-QwlBl$fB6Cq9m<}83>y#;1jbGQWBznav4F{xLKItWyI z#{OCxhNy5Y-lACIub?x@5~*^0t4fZsF}VZ$sE;4tLj~(?E>m$oD{uaia4wxbsuZr* z^_pgw{gn>36ob#vtu4Z(K;MGzL=6-Tqsh+{oe4UUm7aSNUo!wF{o|FMu0BO-srvZ^ zL72wHPSV3~1z<_T;_dennB>4Y+ABX;*f(Zg_0^x-+Um_?q>VCjq1?G@fdY>RUD(-| zphOZH+O+q!TF?m`l9_oC3KKeUaR=;@Cg=!-SFsPj9k5&8%C68c)J8qTJWkjpCN@E* zD2mf@nsMH%R#7F-$aqSEoQn^_dz3)PoSfs2QP&)C?rKd6S^X&dhD zRAfIi81TOXY3%OYK$U!_9{oxm!)?(tCjT9u?OnjT?}7M-52??2#ym)wo5MSPlw5;G zWy89>qat2DPXX{G&Y?@V@r}iTu|lDTdRww-Z{7Zvu39x6Epwc5O@b?+w++pirvK7B z5S6*Yvc#*lpbBmzvhzpisJ@=a`t0=Fo;Y9pwXg*$si2#V7t>Vxg)wuF1qYYPrZL$@owSOA zIiY6H^92OXJ}>6DHj7eUq6rf7&>?Zh4lt1szhd?m`QO;`zva-^<-s$~hkG~y97=X% zjhRF#_E0`w&4mveEcH=jKCKD2{*?y$Sr{<$FLY8OA0mo469M4KDziCuN z@vy)1pShl}I;Y(b{{3?eJp#@u<0=qDOLe+}fio7BKO!cs1xxNi2wI~yfB8`F)ek|A z{m@Bqn$9pQO(DbVyK0al5cLwea`0p!^7LlY39Kfr5P!p(!=r=EMQ^C-0HvTl=fBnp z92Ke2lx?DfQ~7%nap;ewaJBOh(yZG{)OsCe*~7|kB>tgTMjj&F3YX+$>**qK#y-h! zU5&n*QySjyRX-_g$p2TYNj9Q=*q9iHt-Cj?x$ItYs&Nw7^+9z7*PfeC@mHd=jk>jf zKs{sJs$OIbh0DtKK zKY0XMG5LFmhx2=Y^NU0qM@ko9EP54fc03i39CBJv|63Js1*G@L8?%9yhGGEcceIB( z_+G(gU&3Y+oeSAJ{>79fVM7aW$F;Ap^n+roNhy@pO=K{DJ!v0w{*UesQAhU8RE8XT zsYek0(2eUbvS%-*XAdgSG}dFuQ44#Oc&p)nqpc6IdI^fDr6QSG8eOZp%`*O$dVLjC?U7g$`ye#{~6Vxp4p9i9GUbEwdmr*r|p>?9~USGzO=Jiw^Sf zB6VM8($Ji9#?Z)BcyhHZ0?bW<+q_-yZL%cTSml!JZHszUp zI!FbWAI)K|83udLUr@^rM(SuTs;Q%McgGuyg9(Wmc>Hp#B(tpa_M& zcT9U5!JyiDXP6Ie{(4iUQDZGEVUT()FI6-;MVqBgW7yzcn~aTIzzjYinspN=KI0?)-vP|ihDOsDCAM{@$EBMm7?a0&ofGdv;BNcRne{b@QglZ($eP;N%C$hXC(%EX@T{y6AP&NGDW}Ybz z+XCP@VpFn_9jc+X|EwH_SE!i~_pDF>&i}PW0D!p_KRRQ>9;-qBR^O%YVwmo^$Q`jDIE5t z;^p?-V8Bbil_%$MdPXa+OlSrYf<23Lf3;G#TE9`xru#q|QE2Q@sGusG@ru+En2Kr; zsdiESR^0qE8RZk1+X;v*%-fe>QTF%B8uMIv8i-tAc&VBRt}yPBY)YCIv+d=FfWGlj1?~$@&@sSulPAtR0cMi4j2q-M8gg)mbHKK(51=m|f zN8n_M!ZlrV^FBvwjyXi7jNi!v50S@L@Xw@}9C&hEe*34T2_q&R71=v62eP$comJz) zIL2eC-`Pz6*jbTx7RD!8kDTj3dL4WL>KTZD=JUk8l5Ki^e=97t$w+{#&kK#LGRZfy+-idqXV1%4kc*m_(NE+@)9!;|Zfv0^O{SG#ov; zS@PR714DQI3c*K*%0tP1Op@ff1)?2e)U%9}$bvs|WKTSN6e7owp?a@OF7LS%IWzR7 z0<}3a^j!ou_{Yb$>>Wv6z0B&vWzXfA%v6DDWp1YWE)(W<$39{{@~8^M%?FX53T>u7 zwqYm!7ux^5M5PT+&$yg=#X3y$-C)jl%xlOAL(N`Cw!P_)XlM4EYA3Oa3f_!*f-4mA2 zQPzd+N&!9c0A2|&3L{>sF?QsUEvqr+7NV&vUtRN_Pf6^pX{0*l_f>18TJ8H~dwdA$K3Z9rf%#qR+j+<& z<$int?n%nUk~tYZn!R4kxrncuoT?dGowjnW85;G%UhUzAC%vzh+4Y%%!^2yC{=nlk zc>15ur&o5%aw}1CE9Byw(73_eBgC+0#kumksrHV%v15IA<@bg;*~RbP&$*SP{kXZe z-qaGoUzNr=hj!-v@B7hoILBy7-*MXQKE!89e_V{V&(LXpCAS4Xzl5)#Ws<*96Za5O z$@zVp-0gu2VweN1mQ!-vbkVyO^G+E?3_%W<>{`7H!2k_FwOnG2utGWxNwRZ392BQ(N1t&A3a*} zzv-128!KTMeO_)H__WH}M|kTYvWTyYlZk_OX_ZY7pi@QdoNW2ht9SwF=(l%_lSdDnjIhf5kS&f=; zYkN2rOsSUTU@#v2@H$X}t7o&swOO9pK#$hu&0s~vR#v1XHq`uIR3b=(C&QU^eYyqh ztVbY%x;yjs*#@$yQ2MJ2n}0)W)2zjP_)bg~WS0F<9y%KuIsp2iHwdK|VM5e_5p|%( zZot1#r%zcMC)RcAtiE;X6BPk^wwI9uh2M0MzKL7W=Qp1#79-i`Tk89ZK39N6swU5P zm~Z+tJ)aj?0Z65c7-=6{zfVb0gEB7=Tt$Wz?nCh^IWlrcou5^I&HM!t)>Ci^BH{)f zNP?BUPH@D*TTC`PR;t6)PXND}OC z|G~mmC{*7u-Ssy+`yM_pT$o<0HO{KlWBz`eP`BnIjHgGprb19o9^#eB(x3#n5MCh5 z-M~lG@)c~1eiCIDDF3SPBtwlfcen+urY9&8_?8>+mA$ovL^G+H5>o5HVHD`Zm{)i- zsvm=O;285!)?pnyS6D(#jc{vh2KzmBWQz~t13VT#3H|W}XOGX+Waj;MraX!O1n0_& z#?x8MIKgsSOg791L`f`8ts0$VWi8lhfb0IjAf_}4I}2`^+PGT=ua|0>I6js;*k0%2Q6Iu)`us$N-1j~{^3B6wJP^sy2wB;N$^ ze*T*fC$J?huVdl#o0i=fzbl20(|Oc6g3T`!@rG^+6#N6ob&E$0>fIIzRVc9USxa+M zzmPQzdS$h8oy&P$u67fyw-lqd1htDS4#LSPP!2#p=_p{L))n~C6$-MH*`h6f<>6jq zl(-CP5_U*n3Z$Q(?F`)YjgM1(l#--*%DK3{tKsmt1q*to2k+9ylpnVgK`AmQ3s97L z3O-quQ(l-k6xm%%f|ed26EbQ{HV~2xWKiLo_n)JF4N#7wS+y00vlJ)1FtZ%wmE78e ziz-ts3^`{*A}H3j^h!!*4!3ej=C+lE(-*)a)f*Ub@rgNrh*ahN^*-y4OqaP@iA;Zi z+vrm%yZ$?$1M&AdRHr|U6a$0%Fvnfn&jAZK5(~mFa>o054!$mFGwN=`em4_E$9PZf zH3rTuVgs|W;WLHuBgsBstW<+FjoZN6JVtpKw|W3ud$c7X#nda&JJ`P7RD?4{GAe()K;#hmc>sC9!@(46R* zZ}K@Vaw?xF)}HTN25eO&ZfkSNWs=&SVX}inV+hpi>Saxu%Q0D!OtwA z`MzL6F#U9jPQaybwPAA2T%?!)*u1Q{3<5C~L3QVPbj$nI0hH*H2E;jGG>0;NuBRnz z4z9dK-gvF6W@d920~$@jSr;?H1D-8Cw%HFrd<5_+AJ0yDwLAj#ER(%ckh6}`nW4VC z`Q21~x9xPX@VH|Tb5$bq9E%r0sni<)2Vm{0-0FV$EPBxCM5s`vu?S;KcC#(xbY<^& zHw{Mo_V79p`Zh5ea*9uxBJ^Zp!atERNM>7hP^Phh z-Xp^t!Nf#Yh`-2i7!;Grebk8Dv0;ChX)LLSWu&f|sKziXwN|@L zdzEU=8en1y1;UZKHgUXv*nOAMEQi^B3wjE%^Ll1>!bEc&K97W3W;^n~FT4<(HchMP zEEJGo2(phn7^L&DZcW#z8vu`^HOFUpb3Q=6A?1i_zCKTsEZu8FYyjxy#gKcZ=@TyUMrtw3@4yeX&_|i28 zr~nKq$k#wms&2?bm_#&cp@V^uK4wPWKoO<)P)_%mrq!Gq>*k;f;cq6Z2aE2Dl&}Up6`?au zreEBl(=4X-F={3@*CXObBE@XlfxZ@z(erT`?2*I zgxk#_AuG3yeDN!F#ds%!IbRGBm6ae>4aFNm*tk)!t$DC}sXx6`MYH-;kNTcvS{~&G z06*o=8cP~~Z7`%1^``8S)5KC6PSivr_V>;);Bc&GPS=0L~Nfy1Zc@%%{RZb?xU zQhK|4^mbj_{*v|XYSb1AuWWN)-Uo&Dg1@Bd8-K<&4~UJU9miV}Kvy*HgL{*Z(!d+} z_;ozIjK_pn^eytm&X2>P4B57aAkImsDjOv5pA3grX{Mh@wQ111%EWiG#E3iAHYHe*GHhL>qq_CSB^9L4 zwkh}>K(UtKLtvsTucO`0Xl$6|cQ~ItjSjtib3~9=7-K@L8Lso6sGlgE;1GHVy0i^N9v?@e;MhKk@wqPu>QKp8}EpcXf`S)JDFT%_Kr5uA7-egNuiD%hf+Oj zdv?-sm*WM-nd-YuQk+eaW~tR~j3tr$tkJTq`SNL+Sua&>^rv0cUbZu7<1nP|_B!=f z6pdt8AaGli%_{(!HVy}FE|oB^g!lM=hE1zEiZD6+b`sbpQc8}I(lM!GG5i8C{Awqh z-~K4YL`wrJfkAxb_#)PXZV%G3fV3eb+Cto0lc@P8UIl$+c_FF0ndQ-;OfK>|(TJVO z2KHim9-?&cMcM?EOL<>7uov-(`5QY&DaL~9mE$+&ZFY{R(l!2v5{L7z0PPJ%BtTgQ z3+u&1Gk;>^IKeCmkYRkrwEBYX5qD{ zq;BSl)MP)PWN}Qa{R~LCR`X!&tUazRSgMlL(}q?j*hma|2^((I9B#bq^d$Nj`hyyy z!%-T2#M?#ox&~h6WYUCPFX%l<;T~KtWWFA;F!kC?F^w4B2?xN_lz2go+n%{CBL3C4 zw!i`6p!X8kFpa^4pi7V3ublbI;QVEi6h$Z_9fBY^b0jFDVx)6zVfo16oVnFY`yA>O zDsV|>0Tbf>oZV*rzMEe;3#rcB?P)JZO}-nwaf1zm#$=nM&@H6p?Wq2&Y~@$><~tyw zvKL%)ba=AmwIYsjvBc3a8L#ZDr&Zwi;4f^F(@TQd=K&-XUSkeAY^X`2-)hIA~n| z3V!+Nhg!cK(KdpC3MH_eijH|EDG>u~bQgD$k4ZuVTP?x&-v@V&EA*YLi{FNKGZ#0k>x7zW+10 z_ieaIN+$JzM77nb!y-A`uHb8@U&xq-vabzgZ%_J6QepvNthf>;H*+n%kUW0ZVME4w zLt(MfVcvyFjJbd9cTm1^6#4JLfU_Q-N7Awit}dXcq81B-HvT?wWEe9p#Uw0w27ndp zHM8`XO$5=DRY|Jgn$wqaRt_1rh@%)|D`GEY1=@vm7N1cF6Q7;Z0oo)bnz~;Cd#*T` zf9oui@Pg#5iV>rE45HmAl5=3_ffA4ImcufRc6eq(Erbn`}8jn8>wpqCUS2`Cj&_?&I%T1&0mfH zYEyzBs2;!?-Q~;h6wrcr?#CrdRwmm|{ga^tBaX29>*EO=e;-6WYO#?1jfsqD-5oSL zi{N|gpseGVMc~H4>F2z?EyOOQ9h+aIBx!PoajOI)Q-&c%ETixCV<@KJ@8#B527lwd zUdiQQ8VT;t4=4Bx=6vh2ZL&O!>M%_LHHjO=Gie57g7?K2B~me%7waiSWzJPV@;DCD5??DzEDMD0Y)+bqdHrF-jJ_ zbk{x>lqufFTfsivRl9Ix!wKk)Zf$|D(&YPNk7!s;&OlrDa_w7f+Pgw0Fz)U>A5 zy|JB!_8iM5BBbdxrO7ImDF~+PGI|YkB(zX?3Lgxy`QE-ndMC1q-B1{ge^$u zSE^3}y^|QsGlv8!JJp&3R67){I6yM@1wP6m3HMMsXvke(KNgR^#ZtLD$$7eG5*kAiGwqS-b1|I)X`6gtqbx@M2q2HrR zC*dh1Nx9EZ=ODSvqIb_9bz>2G!#Mh>x25#5r!;+qrRzPg1e4wU`XMz`hd(J+>VlkN zZ+~CrXrHZuyA1VYO$-lQ=^RCsvG|y6GY>u97N!jB3U!3lQ;p8SalYm_6{ju9l&V(G z%O1~k*Brt|Vtby7#C}HxjjN?M9C4rmdYA#roAZfs&RXQNU>v#fA|IHhY`?yp$kW(fe3mQ^+g`L8rx!hAeu1@k zvHC_h4m2ZHhX9)+&;V8wTP5-+5`k-t9gKK9kZS0c!c7PsNRE6?MYQsaeD06iQ@_8$ z#HJ^NA0_|GBJ!7#-RlszD;+HQun#SaY)zR)J6G$4)Ey_*Nw;%oIVQv=yXp*vQ~lHc znpW0@32b_KJ4ff;C*RX&{Wl@mbfM3*baJp(G?3uT+0{Uzfm83k0&;(&u@tbYRv{fsW8=5PYd}s?p*{t||9?S&` zy5l%avM`=5yfR0jYhu=%jV{1o!zS^A0C4E9PO>_*<%nnL*B_D&F2pihAQK)7MNNZoKI{DNmU-tLFW#2 z`id$9%(FkxuTQwN(}Cv1di_IAx?3_Yqp;2)^6wdR%T3Q=>|MLrjWeLwj>1pSj5 zuC|MADVgLMFP;7Wv$N=@4^Uk? zJTZ6()kz{%qfs4G)X0Li@2WQMZW9QyP?RS4JMY`P##@KHZw}l`J8hG^s4x`W6hsJ0 zZBo~A_9t8Rx#(TtB39v|rEOkX`txvO8`^&pTmMLK74~!OK;EcP2iMK_BT){tj&GsV zyK=Oe0Haz|3y9ruqfPy|&g)uXjcFw%Q@;;NTgx6o?B-#_`zO#*{mxG5fvW^oWLCR9 zfzc9zDI~4zUWjM*o3QXZ58MGGZ4KB%k&9}yHd;{q&A>4*lEYv<2)X!**1h$XGHFAB zg$ML|w8I*ti2TI%>iJ(tl=LmTd@Yc`na(H#??fEgloF#VwJs;9p>g2ci~zNH@(8_# zIHrZ0=t5K0Sa?kU8rT3v9_hynabAgB+<-4`3M`CzEVBiY^0<=n3g-Udw6wjao6Mq{ zY;D?T@rg#>GKP}H0+s3EKusaj{#c7)2_={~&Z~--@jM^(y!Hv%*w9Z!qNy;qRTgI3+vB(MwRr3bzQ_fLV`}upLzTcb@K2DX+KSDZ#o2e zcW=+iQDP&IN7M@K^Xqgzqx|}bBgEgw;GVuw#6?o(ay!qX6IHD{&T>$?v|M^njV-W8 zAxd{_es;bjuT<}6*KV6{6{>nHcr=fF*Y$@hi(1|ruqI1fLBs*pa3JsuO<40Q0%>eP z3!(~N{Ge6LLg(B*|DUNYx~C9qk%+uvdv)aP2p}G3{#i|Rt0wjPTHqfr`M;o`Gc>sR zB|j3SL~EmcTNb(*t=p14jr~2>BL_(RP=$L3ib{v4C5(_Po?Qp=>84iPWdvBC4*}sX z2=@vEsCAnhpbf_LW*}>8({qKUbdT3`&ak7=-`Cq0hg&(jxSlyL#<}9E{d~`_HfGw7 zcUot9y{j7axt=lWC`ue^RjJI$*sV>~@$xqL)Ox@1+7AKy=WafhkZEcx@;_Gm>)<6O zt?zZ^)wr{kQ|#~7>7sON{+Qv;8iwMJha9Vl8+;YIXq>osmbI@6a9f_fzNcFkC%FE4 z*`|7*nmXay1M?Ws@C$Q$-lqDSXg|*4c+ZBOEi>N+Uc>&XcwXNxRkKoprio9xB}|(d z{VosJ#`YR;Em>UucA;WR{jbj)8>Z6A&9Z3Z5rZ+cH^;l(WBpCDJH@k&N5rJ(v9yP5 zHzU{GYh&?CQ@9^Eo>qLS+Fze|_;k-vNk zn2VqjL;t;|IjcEK!1xVcN&HY2Y8`4B_ zdE(3@?s{TpD*1ZPu^O4lTU5#gFO)nYMxw zQ)L^b#taP`{q|10{BYN$dv>y-Ol|yl?RTVP_UdO+4;b1Rn5_5z)*tz~V*^rzf9ViN z$?o~^_Iwr;-wG&udZhqsO>Kc{N&cB3k06f5tOYkOu3wdcekoPX4QG0c_8L z1McnPU7rDZ(r|6iuqE zp`r0_Y1u6tK3EI=UrF52ZiFlw7Z)790VteBG5ITNYqzxgQPCc6$dSBGDJl6B{4>3z z#GB0dN*oR+A$=zchtKWyojJF(Jf!*V*V5uwC%M!Q@U^usfK=fAkGf*!|F5nI$m0Kt zbbY$pBOh+^1?fu?9p(7gy2)qm?p&Yy)Ksm%*rgQ4dlB^Po4mP0A7zsM#t{E!~-1T9l|D{Jm+KpG$?rAe_w_T(Q8r3EE&O@xL!S5P3!$};~LCzqyOhjJuDsmyd z>bUBtxaonTSkxV(i}1C_iNE5bw+d|1Dc!s2USj__jK2S}b~f4K_k>u($5Y;G53lq7 zqSH}&M`7h>5AXo__l+(MqJ5#6W;F3Vi(mcAs};v&N~?9?RvcX1D+=$zfzaO2SP;$k zmKHU?@)E@{@9v0dZMY5x7w3vXHxdZ$2@L|##I>M+;9MZME}~isuEfE`0mQxy?(Q(x zDaj5Lj>{Q!v5$)>EH!#hXbn~=+?Zu&Wi)F}x;LtkraRQ|UcRz3P#A>Hld8z}j*YPS z3J7Vddm`SS(j<Twr4_rlYQ^Btedi_*C|-a2)LOE&(e7Ipg$l_obnSJvWJVdO-hefPX!-f6*(PpZ zzo>A}l^t1_#cSLPa}PODXSQ?i=Ag$8+6ywQ$0x-vqQ-2YUQ#$Ic_vw+7(mQS5Ll&7MvQJL3`{g&%HokfRUgv1j&V~&^ z-m`(Gg1?ph_4BW9N+zddoIg_Fx^?X@droBks^}$twlKf>;Xf_EltVMuWS4WGZnBr| zK5&+oc)BNPbv69!lK6v=A7b*9cyuavX^!DIUGfs=D-7tvE^gsGN4%yiUJo)Cc-ddt zJZqeNtYrc?o;04=ziZejb37Yv;y$hHN1v(RRQ{QgDO*&*O(B3QBQHPb>D}70$M$-O z;TBYJ{1{!!&C zLi2d9-+FWk*j5;QIwrhln;!YQ{c=fn+cur-%^Zc^Cct<-cUN!MHeJVY4o`0bun+Y7 zLx5r^Tdb04EUfZ1Z?nhwYOO9#{BAhLo3*^MS(UgMbz_iCuARGFV;1rgad*Enp*(rL zGmSerH}jvqn1bXqrT$KSe$gK7mA3z9KlGc`hZch9Gsl@Zi6$30KB^ftUNaJk!JVf5 R=F_Xk_Qm20`^SX;{14!7$YuZl diff --git a/admin/charsets/mapfiles/bulgarian-mik.txt.gz b/admin/charsets/mapfiles/bulgarian-mik.txt.gz deleted file mode 100644 index 7a9782dc48fea67ebf005cfcbf830c874b4cb74f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2075 zcmV+$2;}!4iwFo9?T|GB17dY-XJK+_VQwvLX=^TYcys`Tnaz@$IuM1|}7lJPoJZaJ*od4xNoJ4>3W@9o2#)14=?TWU9M zcfY1zCw9QdYR3jnL#IjXJgwU@%@@DTg5DzOUArA-yI`4%Te}rwCCAES>CTt0gO-Cf zvFqlRZuPsb=&O>szpnSq)O6NKJq?3}qoJcoE;sC9{62K!)vxI2cS(Eg`@_0TGn_4* zZL&^%*La;`s9~D!+--;7Zkga^ykY2_M%0LE`FVBgCm1sZ8pdZ1gmtz* zSnNGxtYLbnFi}MX1+xGXRn$;0Auv$|kj|JKn5Y8r%$O*c zsG@~}S%Zlx&QLIcFj2(?3g!|fs_39#USXn&f1zNaVWJA34rU!Ds_3C$_FFriVeDDTA`s>RlC&fhBG zfLYLXmem~|{W2#NFl^(0OeGUAb+^>lq3zwTgRTAZ1cSr@rk_3zeP~je0Kl9V`|ciE z&9v)#+SkGMpPPba(sddeM@!I5xmK}pGz86r>nt{ocA%MVoyW%gzL{*TW8-KAnyJ<% zHjYN1nP^?a#?b~e)2z$bIGTWFlC_PEqXlTDSXZ%eGyu&U>pC`$^4CnXZersoe$7N{ z7aK?EYvx+Fv2hf>VcyL#Hjc74%)g1|A4PANe-q6=O5QO4CYpbMY?yx&%|G}v%)g1| zAH{B%e-q6=O5HI3CYpZ~x?%oJH2)}b!~C0Q{!!$H`8U!0qr?sKZ}t+euSzOaH~0GfI*(b0*}A@gz6fc|PI#=}magx+I`RN7P86L)QRSCPsY*qa zKP?rCDkZAU{wP{xlx3nU>^`R|7ge2CX{xlS`W-H5C^NFms|uLf^fPqV~LrGmzHG)vf&5;UQoS;D3=LFBuc zC2A@cG`^Qvf~K^f37yOmGi4-^*N`z)NEd^Ie5q29JbIWVU&;zX-@z=gQk9_b{mT+5 zRZALlFH4eCBWXaJB}mE%8gwp8ic~8|eBY|bP$n_tyH-VrG6^EzvnoQANf7ytRS}|0 zf(YPOL@1LG^4+Q;LYah+?*clhCLt91R7HleLIlKLjud4wMWIJkWGJ)Z z&L17BB1)Nr68lp{m@)~bPu-~^Q<=yVBt$Bckn)|WB2$^flwK_db6EIMs6GX$dL=~#cE6_)%@6uC=+TfP`eynV|D2(?ndpqi!SeH# zvM}Lzj7@l2Ip^O0zVg#79cJO3?`c*uU8~+bPxFUjOfX?WetJ0px`H|z)qM$jNo^L@ zKH_*+TW-00wer(FR-B+;FaI>9=9J^#!*btM!+VI&cv{>r0~zzY|<|jH>z=TWH2n#f68cvcfV*b66(lGAg#r zU8A|@I;I)$IBez+s<`FojvCj8 zl>!|p-ut?-?Z$4q!564Vk9p#TdAl7}|0%&aI*Y{hZt(w`CLBOqAR)y&NjGl((_<)~ zZ$H}51X6uUx(3=%h8xadEk6^14*!>ke}DF3Yg10ipZ`-#cpm%T8Jw=D$v*x3cou|) zpz!XwO*6Ul8#^z)TeLX`{o`ZXrs0oqwt?3F#Ch-5|NB52`ap_TUhDe+Gu1U;W@8r|%WQj-l`i^FRFfrR3Bc F000PL6!QQ8 diff --git a/admin/charsets/mapfiles/cns2ucsdkw.txt.gz b/admin/charsets/mapfiles/cns2ucsdkw.txt.gz deleted file mode 100644 index d50419122116867e8f804459871bcced2a9e374a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 395503 zcmW(+cRX9~_y4q7qk^`Sq?Dp4H4-t3pla2s+SH7Y(As-zYqbPbN@A;3tM(>FDpu^h zs%r1O*Dv4SU-z7I@9Vj**Llvp=RD`U-)s?-lq(|;)&Iy44z9xP2v@83o`P;(ZvVMm zN^Obtl+AoOeb`36vT;cj_Or{^Xrt~W?IS9h4z9OM_wP27=T+UJv>A-ym%E#Oqhpvw zz>cxvwxp z$B@~;``o3(m_?%ibr#IT+Jn;~4Pb&!iwL}s20>PSXFpB?eVE^>PS`Q72cNdbvAL#i zsbK19u8)deq@3L#m@dF$p`bT1)x@A`wuUDt5TmvGGed>oa|&(F?sm7l{#IQv*F-k%W26{& zW%jdm{H=~Wj&@K$0afe(Q6h6|Undm?9ssTnauDqR^&-?zP>^8CPy$s11T5%EFA=ku z40*FGDZDb+bSa)fYqxvraI9FV%8T+ns#gVrB$7+awO#mdJuJUgWgNb9-?4LG@CXCTB*x@O{uYXTKFATNN7-63>$-LLHa6fHP+p?EBV*Lz_K>NU z(ktf0Y4W;y&qAlgFeWf4&fz;fOEk;m^2z{*Hw?L zHY)`9ZEN+3j#4*)rLNH=b@Y0|8*xVonapQrcviUqlVo1B%|9#enPL26ehr!b%$L{Q zdEA~V?6_*MG*PiutlY|)=A3kN>2rA&`?aU%ui?9`qu}0}q>p)G{97+S>{8tq<&(qQ ze#HE)QTDvL$ur=Z;^Kz-Blym$5LqOR)bxRKB zO*Z1Jc%Iz)BK=!+;x@1BjJf4rk|?34kpb`=~ZQO#z9&u>Imke z)h(XfJMzUG%1_nNGPjy<#YuRQF+_7wl8rQi;=O$#f$(&A7jML?bd>Qka)h^!D+ok8 z4vmor$=ENG&e<`@+#q8_)4lT=aKE1e3QEl{2a~p5f9lFIK!>->?-?)A;nH>wMw@N@ z>4pTW^53e1=+o5sexJVPSvIPDzmw*`C&3Hv@2Y<-J!y`arP0wq-T1-d&JDKro_$`AUpJb1j2*LJbeB9R+ zf`5vXimScN=4tVlWnn7eHuQi2DBfB@mT;`NhOQlF5h|h_Ld&J)r~t*6PDY`J4WRYn z=BqpA$ehghnoteABon%L-r|||U1ZfEuabs&b_2#@@k`0(|DrISw}>kC?Cth|KJkgI z;rhpSIRl2q*+xE z(V3-Xi%tQ>8}aXRsf&>Js!N7I0yF!*i&l+Q7cQq(J{Y~Nb|2EBPKj~%fyg4v(H~3A z8DsD&{0f+_T-34XkKTqAZ|z#Uit=EXg5E4UK%#^)+|OQ7Ty?Skk}4T&@SXJ0W;BH- zkE7*07mYBtxt}<#6szDwnels8@K$Jeom@0{1Niv8?|`A@vFxeT!W9{gUecm*+Ow6y zZa@!gZWjx#kYPTA(NXh(aSIddJbqXhDCqRPZ}%y$xoGH}I!e5MN2IIjuPwPbW0U`` z?G&!#g-duO^bPUT)B88%)100iL@~n4yx;U`JIElv&;OacDX|=JI?^o-@d};da{)h} zH!~{kPO!B|gft3O2{&QRjrSFzqav=Q>y#;wV&rG#xlH?07H-9KWJsYcwXF7aU!>L1 z@V|18t@}0p;3O);klja!xCKmz3gJcUu?EHtKtAwmad*bWaKrDUkS1r+q}yk+^<*P@ z&R@N?#sEKBAG}-3M(=|2LvEuh^c`%PvY$|@XO+$qXu^Slkk>gUx0VR;xn}~5 z9Zwji!2MG~8o)Kb^kRK|`13X;A6^tAp?W7BfqIYw4DyhP1t0X^KW<(tDIyOw^V!H1 zIBvyJ&O>ic=F&df?d4Clgf_M$hLny-8XWZb?DzCX7}s!1)4>gkBcDaoo$&t`>L9m1 zmEhUv0r%^Pn%LxP6+wXOP31_TjI4fkhqMr3Rg}n0N6+nruGOpRTV-TbUlZda+^W|S zf|qnf81l9=AmJtM%#LaFixR~UA!dv8XB;jt-Z&_LevOT0_E0zP>t4}{z4Nk`f< zk_+fsHp{e>)27aMq=#tFwx2!XoXd1HW>>U)<_iCX0VcjX#yL^cIh< zVnr9TSTLP2UPKt7<@);cfN9Y2ef+QYs12_onbeg&J`uQ`dyL_dBCzU!%ACCqpZ}k_ zh;O@au|sb2lYKNqd$~v8E^y4|UHf0o(cbYn;YxRzkX;1eT{{>0Jf=Si?2omZ?2^FI z$Z%jR0t8;m5KMvKD*Be%TGQ5(FSi%?<)?1|BZyB+`qdZ-e&(rn`Q?DKyDe7}--025 zDb{8`z^veA#|NYsEcKM7$TKLF7JJs`^q4mE$|t+hIMn%0s8q>E-0)!V?u^-r(&yHi z=vOnZTKjV~sp<=&We~}q^2Yn?4PM308D1Uql-?`$&^89oMe^Y8f+FXP-Z79W1(;e- z>k0e4q>Rq$3tb@I8AJpC#T9j@_Pd9zaz4Au2G5moA!;EM-(w?No=B(O3!1ZvCtF;p z_WI9xz)vtCNd%ls&zP~nO^4#=MfO{; z%JcOm4|w{c-R2*G0aY&W&n=jHD!}n|uts&SF7)pBk`V>xO~T8m`){2iTlvLoGUVn{ z%}|VN-6ZME{}9Da5LiJrm#iC{+&R$0Z#Hp*}{ORNz5CO}`Ht@mim0r zNcJlC`egfhCh+R`dd~4W>3Xi|dMfZj^Lj4u+VQGq7K|RR#diwaQeu9$F|7kk42!(l zVZ;H(gv7~&?2{B;i;|B9HU@VRUf5O}VcJ4PAM)|Q?G_W^NEZfjBzJqb=oq7a^A9tV zN=M3GZ2P4yxQ$!}%K@MW$T`L`!R@}QXZPfS4JT$(Zfb5#qfO zmL9uHe3%hK(9okyLVsL}U+pFWZ&RL)oW4&*I7<4NIAr238lD5+&1n6itM}QpT!65Ef~XFV26C1vFxb! z(~b+TddD1)>&xCl%Yel%gcts)-`kB}mmSKQj$oO}SKWahsZI9l zinfGJXu>aycj}K!fetQxfVJleffpYrmE-pL+=V<$|6}gk=R4DZ`TZAv%+mW$3cHba%g?N5T zoHsgTXI$4?#e2giSmV3n<*E05)+Mrb$MbjzYgu|l?_YC13aC%!87tg#iSa`8{;Si6 zJBcBktb%SYd-+^GL6{b-Vi2>fpoI}lDl-@U4NBk8F&GuX_$G$D*!xO2!2j0JUs09w zaaONI5w8#-L_uHIdq#s(;qpN0rRB+BUPAMQiFR@4V)K=W7O-9t|MXOC(&@;j=x2RJ zwBn)OM!i{VoW$Emd-N!3f7$hnEZzyFr6yifQmXIAbuwmCtxxWDlEA^H24USG$a zY|`6>22ps2>}V#{>N6;d@Eb*shH9!nDNsK{TGdA%JeY*4RoX?~uZi^ea)?ctE4+Br z>1>3~_|9bidIa-;D2VRP(EBc!k_oBEx4c)gfCCwhs7y+nsF1M~sdYhpv8y)z$`&RY z#=6T!U9kd^1f-`esy>3{XYZWp@houxFk;kYa$&5C0!g+^V%K2ZXiFZ+kJLZZFcXvg z2S&K>-u!pHRIBrDA9p-{E173-@Is%TMNCv{1W39(VhWh}n)AAlue#ta_@W?T#dTL0 zzdvQ|XB~@|ZqzuCz$U+%>7PhJ9RvDPqN_VEsGI)5-07)cvx*xd#TD9_8>j`FIq86= zy^F4@?=oeEW1nr(y>+Di-ZMMM&(;V%XR(>ma32@+-CIG%LacdaW6qoFz1XWd`)!{2 zzWh+BaiB;aUdaRJvw(sc7IpvA?uE{ETH_cL+=O-scd{8VY|?uZ`G7EW_vncjyuoZI zSv&6P4#DDA=d4HXlE2t*9dqXdM{n~tf#H4;#7|O^2B+~nNz09oZytBeI$H0`FezM{ zDxP(Vff$p=Oy&yu@)!{P+bReB4Rg1bMGfM7^n~cn{bPiEX9l*72_WsNI= z--Ii<*U-=-Jv+1gJ&S;-LG$ld0bQ81%$0YG+@1<|f=+#)va&Oogn>}GPzx2p zGnA|`pUdmy?aU5ega!~8xv{?UR)Ah6cfe$h?=1iIh+2D@vRE0>vO6eDyd?sbrRj}k zK0}^H$JBCpQ!@BpK9xC;eh?9KbydcP;C^#!hb5Ev!|PEeJUJW4k^KDtm&E3 z7CNS6ZJ7xXE#@zydKs=63mxBUvnG&rLzawRoIei&6{^li??kf_Io!>YKa!8=tT{YX zpvzH76YPBvDM>u0wAk;kezDlm8#}PAclP6XPypNZ)rVc-%-N(BQqLiMHmReOvyo+DTN}Bb z<&w3`w+TDAeSY~YSN%_D3A5svv=R1RroVuBj{0ctmorXxp*G-(CcSjwmB3mwy5-;O zrz`%!?TAXc#;V0B8SA~h7lDkc)KZc?&lwxzw}JfeaG|01%;hyNqQywc(R_wqqW%SE#`EZJf>!iBBciq6Cd$X2k(cjxWb`(Fc9^zbwoAf5y zYdK#Est>{{vB1~cKV%qVw4wK<7G)n`0im|^cVbz^5g2;djhUl*q?@% zQFTtuxWu5ZLZxD*)j_vAzHE7Vs z)gsHajr+3uX(5l1qJP)smuv>?SHNXGJ9RjavX?Q#;qW%siU|{+K*DYdk&yU(t z1OG&)Y`G2ppb8uz2z_ya?C+J!S@;W>l<=FX9p`XRu|q-X%c0B*9YC5tGExgGn4LPd zulrTfO}8t@9*Nm8P9d1nn4-J;*ufX@d;t$Z)`VmEtdG2%+wsjCQF1FOUsxIF%Im2R z_d=MM^p~G3?mD(?vCaxJ8Q(WC(cj!F5(AOd`?Bm6SpcRpr2`h@tN=NiMX$~cnO%%V z#JQA^&g5GIy8^D2T+?mVdePG?i@HK|Ih&bX)h4t#o4cQGo^?-A3?1!mMhrIir_1_& zJKA-W3p{#^K4v;t{^~O^xc;x~U4pOyDqXfcAElgxTKUkEQNj7v zc$CKr=g(K;dwANXVzzALh7_dROuU*Rak;5Tx+EFRb1Pk; zD*>Bk?zc&eqVOUQkYd#Ti1y`gQl>^Gm(2(N;dyqTwV!%bge;Nm>uEpxeuT< z306cnJ^Yrf$%INrBn?0FO=aMxEz94x1GuX%7_wqRVfpN;Qe&0?MhYVy4Iw(W4U?{;N(`3pHS|f@+t8Xip1)l5KIWN_s6@^3@B)dOUk8}uW846WC6&WfDF>fvH{T%bq z!B#$K&vR#30_2)u&~{#Zkj*p5M>>O6j!YV1Tq-Z%9}X*m{AI4CxGw|$ZvRaA(UMA; z_eRQEyL%KFQs8ljG^MRng~^9zTfs8F<=WP~{{#B~73~|>wy!%TE)owSqfonhS z`#RMB`9d6%$<{iR9?Ag4(?fcp`_>Un5QCnHQkYl z=ajK2tF{TbC+|?u4!W{=9g?%!SS<8;UqhB|(Pz~+cngBd!Q5ejlU%dmy>I+;gklTT zIER<1C<6n#b@{dZv+5ajAZN5=7n(_6ZQrc7COjw@I`;hh>GmICnso=ct>RY=NfQ+k zFMW}`E}}H^&OKb29A5M;vi}$eb&pi)&!xz>mz*Wuq&=Rg^fG7`s3Dc|NuV|QEPqBv z`Ja7HHe+keB=0Ck`E^H)MYYCoa!N=A)oJQstN>wA73D>0(VsHttqesHg6fpDP}ILA z?~u&VGnP^{Os*=88@(+pjTp61MJEZM+c=BW4tT^6HtPzn zcf_)aV(Y}O8SPWXPwiaJuwyg1!XErW7vCXzsx#}BoBK~3PfRBa>fxKQkofs(n7}Pk z>9kuQ+jIU*M_eKB$Dwbi!-8XDqCJ}lwvPP>>|#_ukZIPYw2NNN=zqC8#oUvsH-5)o z3p;18)ie+&D7h|%=ns!2#!sk4LW?;X-_3bT=dEuWuYL9QF5w$8tLzDF`@4^NJFq-`$yN)01UF8%BROb4XZ{xq2)>@ zCH`SP<>K_>zZXM(a1&j=b1thGT0bnQ7O3iKn;0X0x2i;%{NaJTm80nz@sO+r_@xGm!3@apv zaLbG?V}1MYCEUVn?+X5Qx489{toTPWz_t-;8dHmXO0)u?-M%?;q5e88I?^!D)4FEj z4}Z5eH0ect#E)o9bm$5}xp!nzl|w0vYX|03bK@rVpX2Ac_KG%UTW^_#z}G4poFX!t z`VK7fA;TXG%+c?=L!?+%zj2)BJ}>aYo=Lr5lPmL{V^zMVQl)KN)2@Y69rb#|q2$AT z8B@SS-`Nl49o%hLyvHdW3-M)=9Kn4bcwr=2Si@5BCT1_L4M+>nTG_B(Y93d(XG%NC zqjnxgYT_!<49fIcSir_Y{><_boGd!3z2165fk2f>FsaoEE*mcJnvno!HT~#rX@06* zytX*U-S25JY@T){vYU}ErxHpx<_BT4dBbQgpwHpsps21~uAjB6pLNu;_$Ej}D!=ls zbTtPaJ69zxPjjE1!IV~`z~((Tk`SbFDN$EVZluO!^X9v-keMfG37xb{tgDU zeiP2NFUqy;zQPx$)4djop7}TDyhQg#ew5^uzd^U0p<-9RY=2W)N(bb6iyFLUQ{@9eMtpc*={QLKZ zkIrJnXnV+z(<=~4h_hnt>fB{xF=n6>^W(# zu9@KpN~_w}40RQodwK5wbrmWxq{^bs?cRd|Gj})JQxAjp`mB;^5pnH|YR^*o6m?~c z69!N1S``w=mdlqV14d?MQ7^Gmq*Q3d*Uj&8a+A=LPSns9y^SzLg3LObLe#(N>GIdH zOj8%Hv+2#trSEDe*_LelVKFU0Ym-;c0P0@?$){!juT}EV$qTcV1|2rbzB%GS?k|S& z&#V73nn+G2L4chaB=6j{G0cWdbmQGW&(_Wb4PH1%@^JHSkb4Z zBBh9k-l*4YFZ-Xlap z@pb$4?JL2IO}(Z~#ZTx;Z@m<1!i#0W!-m41pRS4vBI|6wzY$ajPi8}TV^S@Sm!!8Z zV7r8op61bm>^~h~u^r@Ju>;Y=4zS{IPqY2_53m`ldP}`u#Gm(Hk_)Q#yA@DigG2u> z291RcvxfwSju0nny5D`hhTy{PZ?+OMO=k^V{xBHfJC+=zlif~ z+ahU&%R^$jd+mEOl-&QUb zRZud1!+5%L%b2Mc=OnQ*go{4-hS0Qg;qi_28A!pAmg06nqW%VM{E$Tx>OqB1Qm1qs z3Ee^8e{=gkOwPD^#q81~uHh$ArRts228=f%&>p7^{T}J#24toWT9Kw->V1jaXX*tN z`wZxeUbS-tloO(+YaFhtk+=dadh3b$xo?>XoO6Q?d!OoON7qvfH-2FiW?VwPIX1;w z0FD%sRxqbIQb#eCF+Nzf28vt3x}a@#<{%MMJv(Zhlt1ceeFz4r_y*VxQ|4N9=W6{c zgQTokd%B~)ED2fuCthbg7E#pN#S_@uo1F8X*xAJ8n^ex+j(Fy4wF*26LFGaBm>-ZD zOiAG@uFj#G{Fe^KwG>-wzd7tXl7x3(xEY`aWw?N3O?j`Hh64S6Zb`JArC^so7_;_u zIy)++P+bndy-0%!T=7Zp12?6j9N8S*H}7m$(@>{V!_)&};%W1Zztm@YlVYWBoUq(J zr0d>UM*efv7G^}El1R^H@3k+-m6 zr!{tN2 zly^bo;CUF7*T6OeApTZc6A!X26>3tFXz51V?$$oPvOH00Aw4gPTf}1CuOpv}nwaNE z1ljJYz;=)gFsIwaLQqsfkgfA|)!cA{KUm;szQkZ=Ro@6Ud}@!MFypHB`ibkj%=Z-u z-Q3?i{t|Z7`7h&)cXZu20%DVf`~CtsE~3FmdpO-2;5lYz*$>Ngv)$py^rqE{>;!qy zELX3Ud*?9Hx+~bpHlz(uQ~=tMVJlM_8>0%^EGZD74& z{CO`rsR}L@+6_2_7B=ypZ`G#+D$|V0Ao)jx_z7%kL!3Eu=N6A2~V;8!5aN;m(A~ zb%I-T5onRJ+{LT>kIjv`|8m>ZW;wMLxI(cof<(2l6a?kGSk#(u2OwApW_#Y4OJW zUu9`6n|vc_2oBo`7~jjUPe6T4)?4UTZch3K5g05WZpDgm3z<~3Ga|k|a?{c{a4a>O zJ)&AVx0{YL#%;0?^=4{#Jyil9Bm`;HF1De6jT2nIt0mTo(3fX+%pz%H#rtj`zsh=>TRAFZ`x!!Q(f`?!<_x+x7ES^zpxBnUirpT=-ku&tC3>xdG(tm zd1Ge?x%D3_^$Hunft!KE)rAC0mgzx7@eXUK4<9$eme4FGnMH#NRC?s|w&_fU#-5VG zHg4I*?=A&7x@wAXoF%#Fn{l&^_;-leXKXY=^q zBAhutSyjCIh=1@&B1U4k78P^$Zk3D5L4)6kHulKRJtrwhq`P{}3Shhv=Scdgy)2I> z0aFA-REmY4qIyPAI)2YK-@G$Y%;5pl;6baH(PldkhHh=S<;F zAmAU5Vt3NVrm&M}tOPV6mOOjEqUEGy$LeND-X=BJyTMcz68BiZ$MAc~5}4|) zJKK`d877W75Ahidejwa^Bj~?(K5svW2Niv8n1jR~1XJUhZuga_hxnYJBSgAd_Ns|Q z_sd|1P?#{w7Demkkn3AuSI3SVd5%qrZ}?m;&2k>p&njs3_R^K44GVTMs4;+-=ag3A zC8l$lOTIIDOOutzWKzJ7;aWh;;5txn(9i z%)MpO`}-dF(kGolCz}Xcp!Hb6IdFu5vV6IdXLsk=T{d=oem^~;c6F4vT7gYp<pX!;{WOf|1|nuX4u3s zMLI^nO_rY4G_i-QHmMBo8QZrM6%1!70@r+?7>6Xkf?k4!A6?(AZ>63&&jpi2$fBzp zjX$+r@5GS-ahV4Tcem6pg<%lt$RtjAMsMNxM{G$ChrZIJCN5+DWO&;%Nu;hmN*tqw z=Z{e9SR7e-7c#jXrvm6Y3cwYa(rpWUO02D3HxZ4uUD1I1o|({qk^u7j=qrAv-splfCi5w%w3 zA0R0H7uSyQR77nzFKV>&8Nac*bO%)TD}? z*%t8Pmbzn3Q;)bXTsU-gQjs?Itd`?zwye;1Wr<`8vc1l%tF1o~@N?Z>bL*Y@mVWDI z6VN%>ADW!x_3itaZ-h|J!yunS@w?`LbBp8KrvWq%%fZq5zeN2(3sIhb=+hkUPbw8>@D}y+iiklo z>;EJqH=$*ph3?}nf@vBT$8~JLh2DZ3?P(9Dns3D*=;)jWi&Be{U0~Ewb?^0&Weh(4 z-dCCW8T{>%9>M!N#Css)oEAh6-c{TxT!W$zo4d}5_;P*bvb{C(7|o;jG5N2GXEUHv zBmE%b&b&_F$32r)FP9s3=75Be&hcyq^=A_5t>d?Cr|))VP~lfDJ28qFp7W*IsO!D! z%ce`u>#^(Ari-R)q3fpW*8x?ygg_|Z>OH?Laj;mze{vE7<7>vVs^+WWbaxb!;{cDWm4ZS@JV(iV_*(q^$4AN8udq9&7$n*`oM{EMI}-Q{3y zRSG=3BLiv|3`?p5v=A?y+nx*id1X76TrWIHyJ*HBdde&HaYVbM<>`J0tp%qc6d}hj zDy#!S!NKX?!oOIGx`X1cbAg5I%HL4`(U&c&K5lXG=0ja62|>-y;t_X+Iqn$8OGCxy z($qdXN{sfJP#*RaG9fP82Bzo~%+LbyhQ|kj`{pO2f5)C=TT}11qo$?Ilfh)A0_Nq<-scFrN7H&k?%mjC=s+RdaGUB636 zFs8=oDIq%$%)o(!A#TeWKc;jcsQs-{lK{12E?D8%#L(M|+Ly{coNMMHv z%1qy)u6=*@W>}(7Q1^cl2aZsVy8RjrT7oGZaDSQv^kV?8N1VEQ3Fp+aR{DkuNf1RP zozDY7Cgk8AR_xH6Jze6ao(gOY>c+;^jzqc~m zegM~s?|x#rV!EJk`*|=nGUH})>yC6x2yXdbURbA<7&6gCk;5q&Mwb_);=5%lNa+EG zEeaM+>==^iwG56O{l#d9Svh^huP->m5l6RnIPsjlhIabW!Mj-wJFFyF=_L>G4Oak2 zt)v#Z;`i#Sk_4_nxj2pkeQpTk%f2&T%?4KppH<+RH@n*qH5go~#$dwF*u?UZ5R^Y* z&U&9FXUC=EbtHc-m{o;RVuX__km#83MeeQFDIcMeEYU77^c2!+ z1ENhH!rXgeC7INhN5e1s+Xezhp6GuKwOJ2atBm#UJF$y z@VzT>G$=7rThuzfUN(ISN)=%)xO$9v8)`8AlrYvz5{_3pPJ$wSj_&+o0R>|2PC^@o z$wLd8Kdf_#LnBzsZ@9|-phEPem#Bq_oL?~NSnP%yZ|N*W>_+MtE>{JDd{Yr{eYAf` z@7H;w6yNh?UP^?mY7B~(uCuMv@SWa*QI|aTJ7HX1$Zd02-+fTGadT0A8&v))T#Wij zO6~gM*q)@07p(zS%*pIBloFJBx_NMWR0T*FN=w$#r<3Q#i@wW%jvt~xAoI-D=f^d_ zZLNSvU*~I^!xJUp=T-%^B}7)CV}#Ee4Re~Sx7_tbMAMu0(=4_w3F1&inL!6{qa}Ak ze`~h%zJJuzcleVGi9M+~e^g#S~Ff zJr?7^>R+T}&!0LH@I^L4iQs@5a$iXY@gOYvqx6g}?Xj$-)l4O<2N>`DAk^`bQtw*e zPpRrA>Q9n;Y+ZOfWlmEvTQqRU28G!=N{z~USWluO9gXp#g}|i`y=ZG@N$0Gv=yN_2 zJ?UJn3(qgl?waORZ>DZ|v;4vBsoI$!zh^))O^@i-CkSxdv8|O7N)XyIi2DruMGk%0 zvTv64mNhM8u97E))SH)>DF?f;h%3=;;Zsg^OcPM#TRbGU$O1;1l|Y;hWGe?Oe@%>KYeI4 zA#M8GgaJGp!moKI+#u%z<<}&!2kZ?~xo1@g7WZn>IH5{AM^l5<-yW5JcCH37)3iTn zD?J`tRoT#6IALA@7o2mTo6s6uI)r(ejQ%h&S5fji{;&3T>W~)WMl!no8z(dd%zNx> zh;2pd2ET;9$LJ<4DrWZ+G8?N4>lYPskU%VBB%IldBg`lv_xDveN4xny{9P7SdrmxF z5c#(Q74LWoe;m4M6kMtSVTI8aPsZ$0c!K$(;NGA1O8gle?y_hBXP@I$&e#?h5I^_5 zt^UwWTkt*q^jU>FbVd(HZ2k4rWX`nfgiLT{(9@Zfz$X8(%e>2rl2`ZY+Y*TNf7&3- zgJ6sLl`uNPy5C%s4udVp5$Ko8>q8r5{JM`H+?(`@qtoHhZIOxTz<)({F;_kG%CYx(#0688`I9$h3WDzj1f*FLo~MWlyNCL>2}|I69AFk3U^x zSw`Q`UlQhs2D$+UAy*h~b+OO~zW!?~nnHj6(sx`{2cENC4+UNvUvJ4?pI`4(&j*sQ z>~tgy`?)7+FtHhUB_1gMFQ}bmXA?7K&@UohZn=$MB9|}N!DJ9q(I3#tsPbJ}_{E^i zuq6(sesF#;a}WonMtHV3vzYmO`eJRh@kfFqN9}W~VZ!nU-$z`4(y{b@15u@bO^IPj z&iOG21bgH)+Z)%b>tF+q(N2AlCXS%E1&i2K*I=N>2I?4B73tE#j6OGIwA6FR|qJV}N)C2c2yn`%WozLcW+cmlDcM zCdE_^W_{7=qX*xR*b`{-2=f*$YCZWbxuQ84yep8T9N5~x8|(buiHcsC0zS|3ouQHG`KO z=eh86J-3A8VQJL$?DwQWIr`HRjq@tfz^yMtfKF|wn#^Ilh|hMi%@*$^iRJdfmD`s8 zGFc)jF89`lG+&x~pDb#M#W-^cb**h??V^6_kqA6Kg<^28&8JYs7SZH1PvjAleS^}p z0L-e`5i@{8r^(JaSDxm#I#Cn43upJdB&+thNldkUt?xd&6T!X#zs+ocz57!17euzI zitj?uA)sRNhxmZJ^EN}`qfuP8M(el5b4 zNZ+grPlOa2(Gx7Ypo>;;FC}qAc|~E@cvp~2J3Z5`rCqF_(o+YcN@5$(ra#}hin^Hc zgFr!5bl>a#QTLcVFSOLswmTC6#rm!vjQG%*JU>K^ycQS#6UJ?rX z!V>*T>M@F5q7BFr%KDboc$zWzAXfiu;C`-B4=T;|G)50#x$`$>#w^m@xNE zJpYiLIyp2DGa3#ldF^^491&RX(zRDehY9g;fq^&LR`{l6E6bv>7{|}-{U_GQCocho zzV{_??H}qi6FR5}C0j-d{Dkx^*H|CO+mD_CT^^s4Edc!EN1Me21b+mDfOO(KS9@{% zUX3ztBp-sAI(9tgS65oWt>HSVYw9RJE>0{M_W%pqs{eL!hqtX;?#C$eAy56J@U znPvvE2}C={TMoE>lgYM+2khPb)KR*CJQ(#@jpzgs zufjU0t^|nR!{Sg!m%8JT@@KCwD z#^6om2iV8~gMJ%5asHz1{Na8p7tI0%qi&Sx0#SW_EOC3cB=9zhvZtpcF!r-s=wtgG9Vo@%HQm(Du#JP7?@SsdFH3TJ4m#IJ|VQVn9*}ulAn4Jqgd{Yq12_ zZSeXenbJ<}eD%ng>FyXb6Vy_bF=P|gUK&=JthGj1$O?hR+#%#g`wZN*EaQD@leymB z7P6YWnl2>Uw;ON#qrV>Bmzqau7~UIGS-?bBGgy@Z9HoN5AKK`ey%wCi4Ee6)bhqwj zT2GiTO19>@6)vJpS18RVZOu|cyBZ&CE@zFmus)j8dB}TO4em4%?zs5yHEJh2aucx8 z!A16&dIjdZn-Hoo#YUea0Ssz04|iPpbxy*B;%qOw=0?(zjG9Sk-U*-`Q?@CIG{KxG zb{d~RLH~aoop&Hx?-$0~Qi`A`l3KN^M(jPRC`wUk&xpN8ty)z?5vyj*R*l+w)Cxk3 zq(+O{YVX$G^mo6%zuerLOWb?&zVA8bc|HeT3P^lFg$*iCwT1Vrx!?}x^suWFCXoGL zw-KXs&fr)?jjZ+TTdA_KIo+kb+>LMd^x|NsDk$9WMPrBO$G6jgaBOpI?(M7760W=h z{}Xw_Z9e2Kndq6l4@EZ~2xLtv96*&b!^xtbMZoXjbSy!!jpZ;Vi*@4_8+eO?ImUFz zQnL5cD-uf*G*e|Rn)~->WZB*8c-sfvIeQNauK8F9Sq8t>f%p%(QAD)}zT*@3ibQq{ z^lb5lh%1`$-$cB-qk{jfTQg_WSU1pbv%(=^E{yHP^?w7&Q^b$oBJa*_LV34O|heQ z>wKd_9}7cTwtmotkQM0UsA%o2DR$y{=4??nXCp7-@=F7RiMUuxFZ_Kqd;^nP4B-O( zuf~6;)UiGfnUiK%h zm2!R7rBKQ&qp;OTt^R5ATz}mOv|Y$GxY}vM1&hIT9kCRW@7gWK>!2SN2G@p?=@o80 z_mRqY5>GZSsxEF(mTE7UlZ^)>reS;PI0Vy(Vcu_vz4I5V^F1eO(kdcur6&q zGFcDOy)P}clGwNMx)O>p?6l^~$R6YZ1cqG2UiW~yOzM+XVD*xntp)R+dhAJDRu5f1 z?Q0I#$3>w+>l7(nV`(ls_$*@te6uG{jh(PcyIG%i6AfGhhem#QW@<4JCm>Nf8uNA1ncE*ui9P(YG=L?;t@m zs@T-qDq=4J@`V`bvx0ab1oSmp2Ni=lC0R@TU!QehqVE!mHK04LE~c$P&%Ki~@1|pP z$uKG*e3D;Fj;Za0iPGA{&eL#Rh;B~X+;-WKjUxWtTQ=ox-Ur937w^XA4tgeX^cPB~s=FJ(&ry!EFxXx`5Xn< z;Lw0bZFS_M`W#AV#m>L}zN%d_9(=0ilcr5>Oa&`2;6HEyA;(I4OR!H@{T%JQ-F=ny z$8+6x^^aXZuS2p5WOECtN?V)^AHYAAmX&^9m_|mN&Do3N73$^$x;`9Yz&d1GV zg+XQta=xv!LNv9u1C0u%cVJ%$UakA+r=Ak0jL>I&6>)c)16^4ETx?8r6ETt+*7M-NtugXL`r9$&d{{A^GQHJhGFk#H^3oYY*Fd{LK{MQY1&=wUefv&LVF&K8 zot@So+{#FWOoucbR~h|Wi}@w+um(M=&eNFiJ5rjR4B~OwLh)H~h_T zS6T$bBEws({w1K-z_pRVAxhxY@pOu+mO%0QL-fV{``P*R3?^$+;EhEdS4lvtV?I(V zm`hH$oX^ev5c1rCdxlP-0nokiB^>=SLv}T9_@$~MaLqO|OT}Zsl~^mY>{9s65F55v z4A=Bg2uz>em|!o})hwyfmoe1+hh;p(?8y46{rTj&o)3PtQ$DX0E;NPNNfCEo4Jg@70i%Ogvo;a(h}4UTP^x6jAIFFZ`bz${S&(z6N#x_6T<_iJ z4r_EtPT|&*@pZY~@aJ|r5S2ApOh@?%yAzp&s$X&pH`Ohgs(?eK-Vn35Bmqj~i`=L! z&OZ0=O50U>VE+$N^lA3Z&N1%%*b#>I4$!iw_Zk}--TdEbVdSq|?8vrhhytC#)-)PO zKYv26sdud6-@kQ4*~1M4qf(-Vi|Bf)fAjOgZ@R09LsBP}-?oetvBl{yK(zmb|A^;# z-|7F5HAP$#x(2-(q{Z`4f5Pn7x3~cRU-f$wH_SuUpmwT>)zsJi$?@VdO}7y1;(4S3 zP3!~%4b^{{Gka{rbE_-bCzCOs7P|449t)f&^i$oUK*FWxb>wdJ>RXXs@MN-1B<#{f zwlc6W1>@mCHSGdw%UvHjk6rB2`bHWUL`!sW?sDK`m+TI^Yo@hQdT+S>=)NiugMDxJ zqdfc{cf@9{uz0`>P2E4c>TX_!|27+$pC>eb&LR8T*}%QQhV(6|DqtaM*=OuPLjs-B z{qChL1`HL7;!FzJ#F*~cUprrnDd)281x$wX^r@N>{o-RJC6 z@4yxilbKKYG%rO|0Uq3_+F>)h~^0CA$MXQotALsnbU2Cyq>>Y{<{71N=op$B}(g?d(+$Qr|&X1;+R zmT5(vJUe7Ob&*cmvqm#f_m74itbE%3mmLPreP~H~iy4H@fi7hvV4H}ghu(+>RCC7Tzb$^;g^SY`xZ`04WY-5f^?yZFp&9LRIZXyQRhs~m6Bag;ZEZhJ^--*P;RCALvp zoXErk^Z&qJq{yivOZ}Z~xykkv*r+|9e<$hN-jhMDhLd}i4py#gefb}gw7!n348o(Q zg@5=&vT1HjhX6XlU7m!w$Tdc#70&;1w^F!tGp- zJX^P+{@=~wM3nFMt>nZp0zhtW%?Y%s93Xq2^2tcODc>GB6}v0w86h0vNOgBC?a^x2 z2z0c?@56)ljP^QJbwQ}#pxFp+zpgCxBYds}Aw}66qOS1h2z}` zS4+3o4kTMw7lPUdbKGd*#5Hljji9y;o)l&tuCb!yJBs=`yDD2ln1QS?CunTS)SVQ~ zy9E}StzIINw~gxqYqS%0()y(c>)s#?!O3&fQWCJ=b4B>LqQm=$sF}$9-|J6+heg$$ z^nO^lX z$t*$Uy*tT`bUbw;f{xDAQp~dNQSRe62k$8GLEFc+wZsUkHPf>G{dW}pl*^yxRs`3M zt>0GcS2F=I|1OpjNvv9}tqqg?dOLWOfJC*(%3g3^%WS4zmKpiZcRs&={}a(!^Y9HY z{@o&-%zHUQ%xsk7P+GOpuQV z4$vJ1wx4A6!E{7nLP?u`NH#~pRDlCO=bbYL; zQ&%Y)GP^o)vy`yXfiAx0yzae~GBzI7?5nfH)f!^rM4d7wV7#;F8}$iBExdh@P)cOR z=BRpKeHI;?M83Q3Vk67M?j&B|!m+$Ap0N-$hOm)sU|kzvjbno-Xnd}`2$9OLqU1kq zZIq}Zfm2emYqDvz3Z^}$@WaoHM$~xU5)h)~Pq4kUe6eH{vCrh2)~C0exQNnRroefU zEMKA>)<9L(LU`>erx?AoM5b10Ya*6_{R zi1J6v2>V@t2or5|vdssGBpX;h-a<}XPt9S@-#r=0 zIuwGr%Oo6I@kOY!avL`(E!356iXfA=35vtJDXf_81qdsZEbqWNQ!v2^WH;-=Jn+TV zNkt39p1ClcZY=c9+pLdH!~jX}qe4<7J z_+8u?3S3LZf5?NhCF>kIpq3>jME81sW-6=VJd2ltEU16V9`~j0AIZx5#xisgm=)j*!sehbut;~GZQ9p`gN(tL4#~*ot*9n?>upOn#k zU80t^Y|MU`AnKP=dX62joE5fe3ffp#-oOqL%rOt#5Y9N^`8Y`x%J1;`!gj|Pfq1>( zsfK&O1;GgawZ!H|JA7D<1s=V$__R9hOkg!p{U=>;XB@Xe2y+R3A>~Mo)h*2Q&F=P} zer5DYkT1W}--X;d1Hp*2lJ%Z?sTkGGmD1bpfp}QklT?Eb&HnsD0Lgz%3b{@jwsuh| zK`H2b=sdUW&r~OZvtvn3#fM=3op;xc9(xrZNQY6=EY`tOHxcy+^}^yFG&5o@s&!z8 zqR$i*&7v26vX;?B>?^rbP$(pDV`#UBKzD^m^!Pb{gk_m%2s|@(BV|;91^~LiM6wRL z$o)2&jG!+prtb$rWRcN)THS(?nv3)Hpl*Np2!t@y(oS-^$4Sl(w&Rc-lP3ZA`B6g* z`U+Lggzmv&%iCG@k`_PnD~+VJku4KPW{4lMA{W#UUBktK8CxQ{VRNexx_4I94&VJX zd`w=P32Rzq1$f;5!jh6i(&!ORl=>J%8JofKc2oT~cA)pqGmGZsZx7Hcs$Bb2i9hbc zXud3Put$0fwwby=fL%>IbVieg+d9MKGgnDY$lw|xJvEGPiY}Y51}kyxA2(jhDZYi3 zw@11y&FwH=9?kG8?SRs$HJzJ}R);%R7SAHJFiRS`{WX4!-y#_eVONo>7N@y0y{LuS zUQ0!cBwslDJ*k@mXu0*bh<*Cf4TG~(u%PV6HYO-CS2`F4>v|!hA6et-FJ0x6<~~(+ zN@c3^s$=}Ultmm(z_FE$Zb$X<%0~-)6|Ji_gqT+2C0kz(QOa9?w)e>03@_PVFk*US zaUwp18i3o$zrB?_9SFSHiG4-YI+bgZ=S07GFLijX@G|*<>ULAA1 zCWA`JW@wt7aD_Ub<|Z;@=a&m#YTnfHLx_xrXU(>+kF7JV-mX=8lXjmy?s51t{EEZA zwEasul@9GC%|j^m4=>xNCnv>F3*T?FU zLWil4a+g#Dr#mOmLsRAxxz>mNXGdgn|A=oA2df8IT0EX$#DtfV+=0R8wWg4ek=e>- z@2vR1#{m(&u^+(dW;-3+%C8aV;n*dikzTaBSa&&`XXwh) zDiQT%!FDQg-yPOsX#m^N=Px)kN_z>O-^!5WUxPu5L@;rpM!B;QpHZ%JanTwBmR#ra z#O`H`>>|v@!hBA~QIT@;s|VmQiI104CPbtAtcweeF^Jet zRj9=Fn1gWz(U1CV`y17N*IjgB3WGhyP+&S;2&oTrwZG(tkf! zvAN~Ib2MDLe)5O_eW>0xvkJ^s)$yq3>FdJg)x!TGH5rT|S#smTsW%om-_8UWRjm$9 zN|UwT(L+UkUeEmI{xK?1T9BEv4;FN9*@7PV=AQv`hByNOyEzxkLHG_TC>XWHOgrJM z`ant^mfx2ETe=H}ntCfUs)O^gN3&FE5Luf^Wtqa7h@2Y3Vb?gRwo(nLn=Qe%;*ZMl z=u(Zj$^YC?W1y<5k2PgCNvpu6|7Ec_MUR%&!d5M?n|JTk+Sz9^UG0@5t~M*jYZq28 z^zk6I&8uYrRn1g`#~%#}XvW9=k_Tz_{y8bgcAMzE?Lt+Tb}%I@Ttuu*>jhS6a>No- zR%RnPcM$#FsN=ZwME7z~X>hSuXK<0!yZ1QK2*CqEwr})R$9i82*D-n9hd5J7y>Wi% zOV`K&BsOKRzrK;c`&QqGN1dMa>x7D*T#Dgmto$F;9o}30udwvcZJXba3cJ+j(O~;6 zUy!a0+urINAcWQ*aseIfm9q5-916RvPoqIULucjhxZ*sFC=f#a#P7$_ooTQbAgQSj zZhe|*e5wRSAOGsxlqTnP$bM@u(`LuBa$nVEgw?U$)poiRS0|HQDJ z$eoE?%~YnV@i~w!uo0|F|B!k$trW45Mjh?Qr@7W4p zvUSH-cvE4o<7hRh5g}vUVv0;x-p8=4!Z-Y=y0d6L7 zv+8Y2P~^2I$coU8_D{SbL0ybT-ciYlE|qDUSrWpU3aC5K^aPPE_c5rtUrCbCwAY52 z`uQzi5rk1Q9xLgX)r1FJ&HYurI#LP??HmGMI>?=G{xhX#T+J0RV`BJxB1^szdD_dW8 zZW|zs_x9+Nu~fQ`J>?PHrcCHc+$S5YegTs#B*w%h1WEWa3GjWanMztG2@Y-kRVEJ_ zZqQxp@MF*t?K&HH{M?+EUBpf@JAh+8|3eL&q{p-ZMvoxw2up@D#6M-WgJF>i$xy55 zC`TnybzehTgv_9bfLr5P1Q5Hi6u}#yI@8Lu84EUZQru5eMViU)~Jo`c905BgFY++obK~>Ep%d3ipJzPjzwB}BX3Rq$4le(mWrs>rOqPO7K zu`&n-&@V~Op6436*YK4bDS__&yDI{8=0O;tEVIwC|nIi>H*L0-tP=lI(ia*>3%bl4#w5VmJy zIfGICi~5dV(jFt%eQhj7Va=V2&&yja(gj1(FygY2pW`d;8JlMSPh>ppT9-E`RHOYpQ$rFsi{r=@+*KhOT?l0ZQXaH^&E7%1-0pcoq z<(@Y!z;C}bOYNGIHuVQ#?d|pbN#9arjnucaBiq``c8B$HA3rob+`eC5P3q6jZaX?h zmSKIhEEFXSA6istR}$EG@H>7~+Qxwcej`GEqco%>>}$wbLoNZ^seG~2JQ-Od=^&6_ zcOnBdFN)ZF1DQP-+VkKz^jT|Wv@8-_Sz0+?^@?G{>Gzv4!^ebH2;ui1Ca#$JraLct zPJ$OfQoz^K)0PT*$YveSYr>3s{$ZrX$6qxE*}feQZ1o37wr~u45$Y+9I-N6fj|Hd& zsbNngONLB*X1rAhu_pDre76`4yMD1!u|r~Ym8yG9UW>W>ZPd*vOX(Ym=FO@m2`5vm zA$GkQvzJ`ByS!Z#adqgK(~+Vu7^k<{KnuI-fg~%MNABlXgBN^&+*K78vMyb4!oFN` z{po`b71l5N^9OyW;pXnFFd}kC@_{pJ+J~YAVuW>PO`jB%NL2_PZYX)xOi6#Tx@Se`ZNzqbIJ)`HU!K#TewM?^(Nv0k+ zuo$8$;rx@D6D~-II4uVL0(0HeUOp7J10$a7g?wbujdwp(LLq*=<>`Y8JVlw%NaZHp z9~5od(2zRGcP|t+?-o>=wQ1kdcKW#Q61+364?G{TDT^h>!aK1!BIj)Q*`2L_@e*&A z_dIxcLQ`n@>+uI-!<$ibChz+f75jVW9(sX3F3z1m0#YXmNdS_t`BZ_e7WOF)AsYeM z5d`a%n4bwx?(xUXK$YSp1yA;vMDSQZ0tF5I{YiS*65&ij$z-k#sC2t7JhGJI6%f&* zb>)_JC*iyRXnEm4gTqCsqE*hW|2$+WqNep<_FqF7LP=OtNvT7Au!fk`^HZz9^w3En z`)Me>t5RUk$Bu(UnWWVkRlaYkZ7&$S=Db9z1%QuG*|6iOg4h8CoIK+8H1%3m>`$~$ z08#Y1GhuR?`MmrcqWauJSEV9h=)>o;Efxp-xL$hL=HZd;d$|kMh2Z|nz7~7t?AE-2|hWiTv}m!#9l-ZW{^HJf0YgTuI*G zMUrL(Ec{-1{+$MXVmDI5={<5fS#8*LZlNc%R*du%%|^v8pjhXw7o+5v8i$O$gq1TZ z`aIlkgXps~C!3hn!J$$*NpJe9omS?n>ZKD<5S*;as z8Bc~rbs0Dh-yNn;yJx~df2Agme2VA~Mfh(*A|0_F%4Xe@jT}uchhV1Et2Lb`9j?Mrp3d|>>y@GW9`{cd&A?t)K@ho)C}>?Z z)P?L#o^rf9t#yoyAuQ;Ug8j%WVt-fJ;ouv|vXEUh(YgTAJ-zE?Gh)WNJ$UE1F;X6i3KqZdQv+X*)Gdj#Eu|e+dT@2|lY>kAQyJoNF43L06BuANRxIE!z_!;#} z9PuWM1c0BrONB1}imVr?C{RG1)r%_Ya zQrYcCPyfjZk7jhZ8x8_gWo+j)cZz+k3PqlL+~m@f-EfvB(a(_bU^HL>Qu-j>v3g!y zol{RqACNB4SH-5AM4uPabw>LvLVO3~BMW@&N&7iN70+uZBGx9ghgb#$msH&7TEl=``B6DtXoi+f2H#-O}^lO zfV3%DB-?}H!gu-@x>CV3cDkWcy6M<&s@f=Iml}Cpf6Ze;O?T7&ZXMHo>&4{SA7*hw z1p{Cg$^?itYo8L4M36JBlZ0XbG{yQD%9r}R>@egsCt1;(5h7vTTc)dW){ zB_m6$D(Mfm$q!FKM4S-@dJYA%7f3-R}9^9x60*r6h5%=5o-zosg z-_si1`6WIta9Yc)%(RM>e8ZkDMfVxMNDqkI~xOh)EQ9TJH1B}6uiix<6pFQ{+_u@BaJ z{`vN7AA&)&sQ5kO={V(^4|Lfbp4Nlwa7jZ<)78!0zu_+3lX}jR^0No~wwZZ%->Vn* zdlETMDnS%5a5%21*{%)JST}~#YVop_sbcFJ=9(I670lH>dzCno%&3KTTN6jiK6yK| zE;-sne=L#{f{0=j6=2cXasUf(lFT>CpZoA{zVYc#ua^7*SyuxgW`FQWb(@2w>#(c1nJGE=0{0F3czv zR%4%b|F9aUFDcv!a~snGE3m!KGC!q1{Hc%IQi&a92N4yE<3m>7`MSLV2gcu1eQB!E z{aa0zUO?e8+0oX<<6fZlo&zStspj2=GVO7ey{kQCo92K5?WnXT>80RX1 zC;yuGXOHBiFfgWfu1_7ru(!LSI`BJ9cp-rcp*U2JF_v6`L>!V0>jDc0fhQhL!+Ky`V^2kvchZ3<{P$_jOK@vcpJ0o| zpk4*u3}ng1-OA|VYHkdMiqH|Qa~)^$g=zFNIGE(K6*gJG9-V$8g}39p%Xs?@bGi`y zKolg_6Ws}93GCJFYzt`fo9>8h-k0(X|A-sWFe&vo2WJeI^f$$z36-UOAcA%T2%T2+ zBlqLD9acD}?QrFt8uwM6-}8pegG3K>u@cpjLqFuF`0lav3JCxB=JukT7jo~7H#JI4`w(74iX%^U%f2U-skP#oTuu0s zF|JE5Rp}|;oE>#GhBioP4R!vU>G;lgZOuq|X#kP>F3>(2K36b9pRN=L{nCEnE4y=D z^aS9{2BJeNVA(-9=93WmSV5WaIixvXj*2#iGQ=h8q!kB4$Ld#vJW%9?(tRGKG+|S{ z{5jf16%jo{QtbD<72%he95JW?-nFCL^$xBQbqX4pt z)lrGJ_3PyPow8z@=I*N)r1wzZFidE>&5AQOU$A$zQ@M}}nGUJz_25ZdsJ(gC|0Ywy z(LSAkhL#Sv^boEm6$cgH6#nGWP3JxKDh(yOped9c-=?^Z);)F7ju@G_m(MV@rR5Iy zcMEr&M26icZ|a$H@*jzJAKB(_61B%Q$1*xAy=72enRICxnE}Vw8rhY}w8uSi1(aY% z;sQYVbR_SQ?HapBHqqY$H57lyNKw~gc<~Tcr%yR_XX(?+aH%-t%kZ$DzmIzIL!v%~ z#&EqD6O<&N%_`jLS|BNm8EDFD#tBe-M533J>#<5`DGs=Y<7x=2wo=(d@98 zyFlIj5GneKRlS|>Hu=lf7ru_Q55@-4obnMuU`%28iHbPUb!x|MGQd0Wxp`7F^uwRK z(P8NRycN}4^<`P~Z4VVhI{&hsZK%48guMfG$HI#c%l2BdP0I%h z=A&PH#|Pr&f+Vk|s{x8)VbG=Mlu~brbu%#lpuf!Vuc{5fWpmjJ&VH%a-hb=a1`QP@ zp}ccE@KZr`BT?-;zb^-Iyzb^JF7@;F&{*wu=MZS>u8Ryi%zv;kiw`<*2IR zvA;bjJ1T|!f%Ynab8xZh>%bsYFP9S{y1crt(n2q>ztgl{6%YNe@tXOUm;{eLVqf<6 z^-;Sr_2{NVrPSfVXhJ>|IuAYiSp6aS_rAdF8!6>1J#j>qz|vDKfhaQ3l0a`M;H{&W zo|&yAA^r5DR{jrc304#ksUUuz4YJLuUUX!KWWho*ZZo(>d%?YM0CEy(6rdeENM5aU z5zK=vKb!EwzDyP|y3b@yexAv9X+1sUmv(lbYuN8L7E=ZTA#Zb_SozRb15xz z{ZLwx`;^>G_eQeP^L+rgotE1YQPWccl9lo~GLFAbl)Gac@G%`?(t`UM&HT;h+01w` z$%nv|pGGs4@@Xo5p0U3_&X>Pg4xkj#A7+2wVsCHN?o4MVL^Kh|!@@PA>rk8^#?cba z=#BQfFv6XhN=b%GwZ62JQfe2p|Me2A(bi}CJ25+9wWcS~jHvO*HWSyCEw}RKHk?>n zCOvF-M!rM}IN^`39h7oyM`g<`D+Ac=lXe400VgVTnYA_hZLN|Ij7Y0%|0ir~a)DDA5nn_WH06x(}t_JS#~U%lTTl#JhmZ&E&c{=x6bkK!P2s7-c#AzSbk zPxk$S%ovcK_Fa9+lo^(&q41}{F-GeSrLR88tGpJwC#H-C0lq|AX3AQ%H%m^nfHUUAMXclk zBc_S4Y}VGTV&&YScJmc8`XvK zemSu&;Hz>)RCV;Zli3EkJ;4|**ypUY;mPraG6$jzb??s8q-IDtf!*s>&+ScxY|pkX zuf{(Cx8-YvG}YTnMysAD52|G9eI}^>YMzdtexhk>5D7XCrgJqf4;F4X2AUbD`aoo; zFZm2+f4r-__jcAEMSisysdh~j+*r24d*HnD>N%o)ww>*1NZ#0sb8^xR?W;!b##XEU zA3Eap52$AUd?ONWhl#m*7n*qAw zHiGi@0>~~r_(Iq$9KdLXbI<&Ug;_D&(Fye$q6|N6WFZ>*-VwCA$AirZ^R63cib;pe z_m~vOhAiKm{|?+74_>1A9*aU*z$il$n0O+D*q#LMLW;+wHcpdTC^jxn=-D&AeloH17j|s~-Og%t#ORHR%`-{5}!!I?p__IKcCh zd~3fkpn#LN#=c+OFTNOqChv@mY2hSRXb%mts#tU|Unh;HT~jc^4Z> zs)0JuAG0P#F$@nHLLQ7l9ENLd4%zeq3i^Eo8uuscX|V1(UT}Mw-v0SPvy52l$!}ZO zxEvK1qdj-U0C9-qRM!3V(wBqDNS=FCZr1Bd)*#p6Uqh+Cy}rsxFPJcRG1Y|<8d3myZG^q~cl1Xkozbf@JV8L7nQtiD3l zy)68g-iG!MZhS*l0RLGN(3TsS*84HsXgQcuOwhgb!Eg08I2y43^{Q^{mlnugoIWaJ z7|_~!_^U|e+BrSE!SNNk>Y-Bb1WE7Z`-}3BubW`t$dSFL)JPuRwe9v07C2i0H-ozP z5|X#c3LL}6D5NEU0G~+re>YJ^S!fAsxD<_n}}td)UxO` zoGztBt)%^CFEI*l$(JC)F#R~#Sv-YUYsj1CkGWkHeRlTYned6OcYd<>3ynj>g7<@w z?c-~MkDxhV6$TS&bMF!G<(RX@+nD9kD6|aMyS9)eLpl@ z-ga^Qu=`#%TE(awKP%8|v+{sfq%rG&V;6oJs^vy+rfX-~mkS&y(02VEbi>mtp;^~3dh*UsX zNGKrOp(}!bubZwpX_Utj`xS3Eq2d-Nsph^8S?!ov=al^-gWG=;ru@bsM5Fn`()X6X zK3^W)X6)8+ch_A0^&c;-`UE5tadPv~`wQT%N4bTnH*{T1G0NXNFyMqpkM}+*@}lwv z=L?CVgoUOwq_XtQTW|*HrYeNTY^y?2flp;O*_`_O_}qxJR*H%$Aq3oB^kUiBVKm~f4$)fSDjKqgogy&Y zFoD`vcTd00X}5S2Vq>K2ZeM!!Yw9bWjoCNXZ1r!GS9V+&0Y9dFI=*XYj>PlIDHEwU zXZz%9Binq9j3=QOJhzs#4EM4qcBiCDtN)cD8zfwRk_+Bv?dbPMYiFr^+Brb8tj=B7 zw{|?XmB#vQnYo!N;nLp~i$NDCiKm}+Iu9o>f!v}IF$h1V_v02vX~p8YCZ`I~z#8UA zbvEK*PS}mh5_m>nBz`Vhsc80LyX+W?W1d6RW8h>OVwuaPuL{-@F-?>P`&r1Uoz-uj z;JSV@4Kv?j=zkSGX9zdz{VT0+643l^VeICt$sy1-d-@NH-q}u8C8;r&S z`+-cS&0>tD2@O<5M%l7l#&wj{=Mujdkn0f0VAqG_P^cEnBoG zcz&;WM1LTF>m1a~LNl4xBc+{(s*8KNMY@dmvN`?cI2^DZ1+hLc0>p9+xUZ;o*&QC# zZToag?#HPJ_r9L@Wy6OT z;Zj!g>V%B4$RVelMvreLcqPfW*p#k6>9fgNiYmdEBnG6+| zt%ZJ0{mGh1g@o~H16F~N!Tp)-RK@!e;RY0z zaaB{6yGp$F5c8l}iRWfScuqC<0J8klWxv<2=T+j9$~w=+&rGJ|Ny<7c*^b@Y-wT1w zjR!F}w9uloRVc@q+_X7`#6bbN$Oh#19=%YC^iLqs_?#=TWqTgXF z&zGONcpv!tmF8<7qAi-joGgIwOQW14Voei5N!F#2s-EaL;)b|jr+ERyiKzSoPhsH2 zE+z+&6$UI;qGqGNLCOopS&iH9A84lL*Ve0UcrCY0dN%~ZsQnK^Qg07(s7ffMKL>qo z?~~F8n0*a(scCwyfb45k%fEX~hhQzC=Y-p(^2GDp<6`=~&t3c3uib68AId-8(reSv zVaXw(v)}mDk2ja2@p;dZe&W36dv!f2Aaw5m8aPS7tv>|;pz z$sbj7@4;Qiwx_`&41?u2UqZ>Ube3=uhy~S-O5bu}!n$-~CDkZHAR3{8(IlhJ2`Te* zq)Pkuca|n2q~|q?){o{dfK#II&HNWlY=eAu;S4NE!!*oW^w0@;;4S$S%0M@oMcmk; z=?IG$XaEPgE-5_}h$=FC+1vz-7P9@~-xxQBxpEDJnJ`>qpP6mEi7wcGYQ+wX9F_iB z0v)UN#W#4bjqytllMgN=KXhO*4*V7mquKhZdur|a;pJC&az}q|PVTbCmIW2(zK+A^ z1ntY84#V0BbkjBkcEjnzuG0H8s6G+qRCdk!af_Du_E7OaT{X zI*QJuo?R-O>csPYsH>5=%#+IIwo_jV_ZEE$p{YACEJ5Jy-NeE}o%2;GXN4iQSmb+P%Lrv(gH*!eG&r2sDJ-!J&p0a)*Q?)d_8?m*XEQ{~+m zOWe+C81MMczvvZZ`0r?UsNHOd>^G(QTuY(Y*su$}^f!?rv#r3$f?iWpo{aYY*A^_z zzPP!Gg3jM`aFOTiI^R1Ro;lIxMZ9ZndyzLi@oV5+v%FkfFRB6xrZ7a)I&0Pi0@;;C z^T3mIdep^XF`Hj;&^}c+f0zn~uvr;?>?ZAI^4_B5(hE-GwJNa1@HfcgfhXY~gajp& z_y+*LqQk%wf;65zHzE_=Z3U>8VbVwWycgP;t9fkKkDm-Y`O;$axr8GYnFwHD`5kr7 z1B3yh_ttP{RaRJ<%Yv?U*Teq$l^KZZzObG~0e&2(G?&<-3Z*Q^KS}$bs3AeXtA}Qq z$ZVplKqB*}aGH0Y98|b~9()a%spg-T7Zu630U9sdHBtGjAx8APC|Z4)DW%zq%!7(I zJ6o|m{&1$4jIk@KTMNsz=0wUxA_K{C8nFgBHLCFfw9UJrdSbR&yu}kE_Owz|MYtw~G6;n`};T5u600YX4)z#;AJ= z*a^_MrXqmRWX^@OfhO$d&sGBK7`1axmj!W`#wnA;gXPI_Ad@pmq+euw`I|OJDemve z!uzR7l|C@t8JU|>!0SAqn4m!UEQKg+$q&wNC{Uw#Q31DyrA)%uk8PNYW2ULB30BW>HZN_OiF z1eT%ZQGm;;kpdzC+;h3gw@!Z*5B86jDaA3X)eAnA9z^i%=7K*r{L^;k*#A#SdGABX zE+w4M5P`QqJA!8h=_gh}Dj&8X1s2ITMKp_U?*A{-4^IcBqf6G4ckT+a_{f8=IU-!v z|J>;n-d~269LxeuhunV&dRspE99el{ZZ;?P*InM)hEX_+!d>1gbo;mg7Rp-_R>Xmg zL@6dqBxXp-6J}06?fZ?Y z2mV3-NB|&4wgd{kXA@Kk_#PLbNaIs)^oP@rfI48hOh)`m_7Z5qqWup$rnribZ}L^9TWRGF6s7JOA3*? z#Snb-Y+U2X6`aIUtu(srZ{D(PP!c&x!HG44 z{&|p3?W3A#N}`Jmd3WTF7~JZ?4Sk@eE9{BGi>&S-?6s1R@9LJd4>!U5`ABb6#CSz; zav;#Wpk)B;J$7t=cI)?XUWde*^>WrAn^08-w&lk$w!*q@txSgzJ@FacL~3`k@^8Dw zOvky~0!QYkGDIpOUf(-;YwipO-E(gnEwC0)Fr1C^!DYV)8xD@$w7|bq87AKctoc^z z-X^NN+lY{+Wk}Kx)3=fBozh=ClEgzqZIQVR=|`o&$uQDR?D+75r(`N+fwW>CsP`4~ z+c`=KzkEJtGt;=Z+6^obabC9u#e_IeV!(!TDg+}}MdgN;$?w55@efz$flHQ#nf3|q z(Cyb=Hlv~{r7U5Wda#e~2n|LIXq73x*Tq#rZEFcWh$Kfl1#9r-=3f7y^zd6{PJZW8 zyK|s1KD#Ttl^IMa$uR@jVzp(YOc(H}A=h|eZGEQs@?YmI4e=#x&f=cB%k@1^?;Hwi zj0dsOTwN9W$Lc_(#icDrKe&3t>#;~Ul+*kYbtm=oN|>4oZy6cKnZDZDroYX6!utyj z6_&qb{7f@7K2ZLS*T1P=ImNX%c|wm?RK~4i^O5uxM{xN>19n1_Q~w3F|1yY0HW=Pt z#Q6yc-&t7KNEc~Z`Osn@CE&`ToMGUQaIHxzQQ}*`N-&UbM3Ir0r}kvVMcQP|c*kdb z)HYg!`?IjEjHhXQvKK!2guY(KdlS1KS2{M-P*ws={O;ee7ZOpkcrBxA2KCkqM@8_M4Rvi5C0ogufb5X8PV{$4ke9I$44zJeTF0$ooRv$?S_ z5tlxmhx?WoLU*vI`}bI7H_}GvPWK5ig&@#ndstp7>bFc!UWWC!4tisxt-+sVoF%`b zD6Xu?uQ?aJ^xgt_@1%~bFbFT`&An(3ukDeqy+vN$WYtg~yiFDxP`7{NMq`bpo=F5N zE53p>z^gjOD?F6_JL!t%2$UF>t#;soMEzXLaAN;%FSY#F)ypsQ!mNQ~p}1o@5yY>w z2yFpOIvAKyajeSXlc-#zH_JMWjlJmZZcls|+RVJu;`rLa-;hG6B9HqHk27$N0X{On zp80&gFtfnl9laPCsg_0+bvGC|u^1I~iJu`;jE^8rA%A zgyDo^*ZFD>xCuNCv+04da5QdGEEusLK>`mEfh&T4ubt2ddwtoDvTB*XmH?CSPs6g4 zFsGRXmfQmV*p}kwsCXco{KuduYl zmAX4q+SWf&4FingD=H#=I2yV`34c7Em}!WrYIol<ORevQ^``f zL-|~o?UH^voB&JlKsfmiJ(iERLT^H7;LLoO5<%s&QBTki62evDa9QD=_L{e1e`4eA zvFv|-1oU#0Z-B;TNZ1X)8i%CO;KwB$s&r@4y@dA(Qncs7~OZm$IUa8{( zaKNm$l;EWIDeK$k;tXA6hTN0YtjyJ&O9=7$#aOIs*x$LV&(G=Aqm^*4%lHhz5>{R5?B_sgli>iTw6 zRMJvnU6CxaMmP-9vFFh~`HVM1YLdyVRW_<)6rYB`{gSw~ahOrShnR5iy9qx&U4&tg zzX4Dh}k;@Do_1mCrjHuhxuB;I{lRG(ZcdP1HumgAoyUQ&O|VN1le^Eg!v2+OsEA+m;WIZDpvrKc>9q z`vzR_@=aAK9EDL$q7%6Z1N!fGa``T*$xqRMwjg!MbWsWR@8}YdIX5T9eLi`qyb2P9 ziR!I)$zxkQDCw5&u?J?W7BZc5jX?84a@6HD`4HusBN&^-ZAgrC?Yi{7B{IJF{got- z?O3W)P%fFAXHj=mkQ@y#Z@JOH*z9xK+{89+Lv15Bs#6I?At(D&d&NAAz}w@+%0?|W z$vsgs{kAKc737ZqsmzgW$WBJxJ$j2?sA0K&KeUqoRfDp zctli%q>W`qGyA{opMCBd=iqpznuI)^c-dpit5)#YqIt?^;8y)cUfkEYnPSr3%KCAO zXL_q9s7j^H4#NJqkO`q)Atn_xDjP$P_Sw^L5}wRezdOt@P>eww!TM8Km+Ve?RXm5w zPj0>GzAQ5J&F=N5s;-fJX=z@69&hX8PIOkoO@}KT$?g9ZIL5D;YC{-4B8?1Gz4*&? zBV56dvozUWRm|&iO$GzI82RUm`=;5tGJ)0n9I1bENnx;Avj44UYrgeoON&v*Uw@E45hfW;RR-@k%;0WSV>IOp%%_l%dnB_hu{~ zw*?4w#`+);H>wA&2L~GkaLp-lr7b+HqFqPcR3P=qc9(R|!WmDxM#bV?)H9Mf+^zGH zt@h6^KdqMAyMC>TDoj_8l$m6dDetEG);#u(?py6Su{CGz*Z9Oh}>v2oN~Z%@av-A!$*>Ky5KAKAcdfe8}3 zVlnTM)86Y5WAz#5x=LJGcbn=r!P#13I&qy8Z~p6VAo8O&v!`k9xu_ov5dNY#x3Pf%cYKToFct}p(=4Xrr*Ss`WPtt%f8PLboi?1byJop3US-upfJfd@|59fN7%4_e4Cts7d~s;tui1Op32Md_oLCGg{m z%dRaz2ZBvhya3qXQF_%Hj%wOG(Mttfa5mOzhfzK*Z#O;%PUKU+mSpwkftTj*ZjSD-Q#`t2uA*cqfw-k}v|e+$ zNcRgH#1oq`o@-4)^A}4$FM&Pyn%bIeMIM)cl$wNTA6tn9zH}YPFvS-qn!G3<&U4D1 z7@P}F7&3!={`^+jR)}W#_Zwf^mL#g9sC2)ofY$$3h9i2g+sW+BR^CRvA@AtA$sf6L!5@gu9=LoP z2xpIHr^CsqrLo!4Wm6HH81kzj|L{&5y+o|}c(@!ykOEjzzikL64h_-rOZoToB;OR` zpyZO!8%x`3%V(Ps$%|N+?kUn4i(NoK1zKFpl~W8LTP$33*P3~1;k^GDqsVjtKarHZ zz#D0QwqMRt1swOC8vuz9_VCY-H-IYLjPX1EFFqa8oI+6=`pXKA|EtJ-N(elCA^+?I z&qJisDi~3w0N%9Aa4baaqjXL{2f9BpQ{khJh4a$GTyIaRsqf(?XC~F+*-&~KBkmJlT|u{z@ZWcxo-Q ztx`;*)zub^X+GUOn^Wedx+j#|5jX-}$G%+RsG$Xm*A(FQ3|+~kF#&al{(pSrzhd?L z|Fk%r9qRe(s;1Vv{|LwpS&0kvqA!@U4tlH2fbUY}*6zCKYCmG(b7IN$>!uTHwQ8d4 z@4Crii@y~Z|27lk+C9@L%I<8&{$hAY!! zCX_F=E`}J8apgsN1tC==M>zn`i0x%}?+Wc2T>h}!sU1(X;uXMx<@bh53`vE zT&~d`G0x%qw5q;A%Cj7Pe%zV(Cnhq~i_TT~djk$Z<5PSs@?bwk!jt^XV)0xnAGV@l zkcX1GyDw7U4~su;vsU%eD%I$QO#9#bRN3heviRWf#P}v-QfX8T2b|!7f)q6isW80# zkb;(Lu1wc4=VkR7C}=#6Ca!vVWZSc*onj`3_k6R3?lRFtj{*p-H5%Pi`D_=GztPj$ zBNAb4agXEx%%JpFG8L5&b$G2z-)a6Im+Y5?V zytV>cvCfX!6>I#O%jp#-kYo6ik;*+M7jdg!WL$0aNk|;oyk{w7>pcJfjC!O$kH?}q z`&mWUpnHda+{!9B@TeyDjGFE>Lq_siCv@E{ss=F?3cL1gG`U0LZQi?i9qr zS!ETM^+1NZLei{F5uUrEd{KQL{$gU2)`#cqQllzrK zVd}kRffm+j!4)wjH%nl!i}qlem{m;;d4o{nvW4UKTuZLkQ@O+o(~Gbxeph<8R9Tdh zM_PC*8gOHYhWqc>hIHq0KtqqxGu(m~9!x)cbwUUTUU6JGCfB5P7wDhxsM3cmO4c^_ z#on^;WXfUn?u!w`Sfcs;SA>?qygO#?sgRfa*QlhGKo3G^gCas_n)lo>0>}t>9ASzN zma;|4P}|CiPdor)DYReq-c#bNJ*oM}BTKcv!aw(gj>D1$DCu$2DuU=CBbDPeE4ULP zPCivWU0^80OVyoUVGhtaPF(n*b1Oh1tC$*^Ea2nO(7xC*yfZOQXl?-GZ0_D>RBRm^ z4j7xJn)W5O^|BD5$x@+?*N50GO{jYypqbfLsI|c6gu_PIJAQJDZINOoOZ>!5#<(>{ zH!2;{hX_hz#iVXcg;)3~t)kux87k##W4%?;`_8|T%)#*BI%RiD+ z>uUreLy*FI&61!YliHM0QR5w6(}-)>S^?>WSg}Vv(6|e2Oq)n}n$_m4Br&P8Z*#V5 zEWg2G$Ol1tah{{P_)e&ked4x zeTnOCjjS@02V{EA&A2RnSl|-Va{@Q#)95)sL@Jnz9Ny~r(EhR{CYDX|psjzQfogr6 z6#oj%ih{X|%9PE{1!476AES}R&6;}gju$bA@oQ&`@%p&0J-*+=jj}~(K7qR$zsAMb z8PNSzv(*e53I%nO1=vY!fBBQISX|xg9%B-Y){gv{qsUwrF4H_k=d=!hc=(A#c=dw$@C<|_{$%FgD7+`c;w)EZ7 z@KjBa@DLRNa}(ibw3pu5ILq|P?u^4{C6w4|X7m5j@aIV18%`7V43e6jbeBobJI09D z->|pYifnhgPz5&~^2YOov?Lt)2}Wd^%7dhyQ{fThOI6HQTkpebdkWCGac#>*BA*@q zP;}XXfr9EX-au=4>Ua+-o)Qo#r(zdQ-EZ{44|V

#E40lts(bk|;lh*vhF6?Cx?r*eWfIif>T!OqG-A|$fk<5x6eXc^3*nW|7% zvO8d@jWHzL%74UzdyItHein6Nku|G$GG+w+l(z@d9wI;@SeZX zLU?T^^6QfgxdW%*dp4WF7s&&MWY6$Dz6h%MCz%0?yOT5#wvTs$vPFXqD%W9;J=Jhm z&h$S-uNpb`eUUBSQ+C)Qd)>m7PnA7r3Uw%IdX_}fDeTdGZJ4uzKlD`W%wW!DoeUAe zFH*fVYr`57K#bO1UI}0D)?0-@f5N8kuCw7ah;cO=pyoq-ndOl6f(i^XPGERYp-7J2 zaA3O6nbT}rz1CyJ@sey^aqv(N{fCR@s&cUiH67pPF#P26Y3+|gL$^xW-p|Im{sJ79 zpaTPV>?ZH4PK|SP2|Vsj3kzuNR?CVWw0H=Fu>e*+vG|EIIbbpsAGPMyO|?7jr3EPF zbtW$O-=AB|Q@m~mmXAdZ05AAbX)V|FEMF1gPv5YRURXyy<)zYkp3vE4Qlp1ozq?syRGMt?F#pI zuXz9p&r@01ZTEkX9h(p`N>CxgomH6i z4gE^OuVLKE-<~!Xyr7sQwEOoZs-3?h_w!M1w?t!G=-=)UWJVP#%-rN9uWU~j8}ra6 zXt7Rf#8(57pVR}11R7r6ardX}`$XA3Y;T19ktzS3J?LFZS8{O8_s;S_-*MhBkh;zE z9H}koCh<5^z1(;u()h@1?q_u0Prpto)36X_|CfGo*$2Ee=lv@^McuD$_Ck@XMOA;4YDPAA#4%i~1oai;e#Q~_jZ(N#k~sW(8xtiD*QY?!nyS8N2QAZl zZH5H6v;M0ulhySaTZuBk&fUU`7Z6X`m@45%chO!0{K zm*N(42*dkQ#f(SJt&e$ArV7k2EBZvJe8hI1AG5Sm9h=OgC)e+;4^d}y_dt(LqQ%T- z#ny+I+>soo-acEO6UuCP@o#iU*b$=9{%aLq!fTE?w$c52<}v)o5;mu`!!r(#&$aZp zc=0d1KN;6eJeCs30r}`yl}Q-2k4NF4Snyc#jfcz?C$>>FP+zl~qzP|eT(`t&ilKKb zp2N$ft1@Y!>hV-_@QT+$dm0xL8%>LK@k0cagl45I&FgzpQ<7?we<&Q*DK?0vs5+}I zo+O0Oq1S7v&TW+JW9hcignhqhULz*OO zf;Jw}i#Hv<+6Xd$)RsM1nrpV3T-F3*)uD~UPb1)>gP8A9;W}1TbsX1dk*BO+DNv>T zg+hp;!CSZvsam=-z+^{0!mR0T9UzdWZ{u|6jIbj&9PgpGzZ*I2|L!r&E8hF4mBn%j zGi=HJM>r|)&r_8QInH-u8?r~?Ng~$wY(sVZN!peJX~c4)xHK=S8Rt;$(yJ*7Yiq}h zeN9r$i-kOHU%RfOi=PKaaa#YQrCtKpVF~HPS=`6dOxF{UucC@VSN~VzDEKA9-$tmY z(EZ=Kns%!3v5fcSz=>NpMG`o^I*lN8DV6Ya3P?iS^Mj*=oSk8RIOPEq?fM(*4r#L2 z+=13Vp14lz-<@Ne=IizWLE@dFvmk-~VOwh1pf{dot=Rt0FH?~RiOw;me55{Ti=Sc@ zUS-zQUk0^7=@2>wPFCMxysFxTkW49#Hr_(h;!8B3_#a21Brx(UQ3UMxf7p6^g!#N0Y z?^>Dh&Ibpu48mPw*Bq@DAklJ|6~^z=Yl4O_fkMj5o5xFooMw?%v;k4^Y0h^pYCVN1 znAoU%JjBc9>UFk(H+44l#~jIs1WBjwz;wX(mVkKY8fyeB;q4`_2^?R#)X0QB9>}GP zca<=0LMzMJl6?YK5leCcd0dz-ks2B{(X!{BZR5l4gFM3Nn+{dhgFI8CB#4QVACa?) zo-%8yz?^-2B&&8-weqn4W&)#{dfu-sxN$48y4F)gTO~eKDH3Tenq=phB8&&F`3#)r zEULcHMT41pCKVOIZ-@W#6f)!(9|`|Z>>hInf)J#!mse`N-L4!0J}QCd`D4TXNhVIg zk^=R+cTl$!p}xtcWOPY0z|F}vP%KE}!*$Et!r?NLmK!GIRvFg0kT!Zs=RGtS5`Vx& zMJZw&)bOYO%I<1u-{tY|&0EzL=Ze3~u*%!Y`JKV{RA({-BLSwmoLDJz9#|s@%dJf$ zd=L0s`}-w>H<7SqWhM`TE9A?B^%w4>pZXP~C7Oub*90gSQHm~kB85?ZZ@_Q$BHp9x z+d*F2L{w$GrW{eK1-jx`(^2(NXcN`jq>MRR7}`I{@@ky4KZZ*bUsZzS!`pZsxOkoZ z2`#ml4Xepo_rGgTHPBSvom5U-v2j*9Z-V`9>^m#b93(#jmN?OTc&L8eHOCih51uAtB%8eP76%5|Ts9e}^z+S<$~g*ejHT>e3` zZ$F#(CgW+WPtS6ZANZGy2J?Rb(p=a?-2Kc4C;`!RMAA^DNE;P&5kaUD>cxn`ti)3q zQFoDoWs=7HqRdS0j7VA^Z1%XZ64=AF7g}0&6IDp)FV;DO_+Mw-tggAoh`W^#YO&1O zBbN`Mjgl){8>{3%i%pS{uJzoSw#o8o5!Y-*6#NKwMBw#Y?+n76M+UUriK$oieRt6? zOC4QSIUTg!n3K|jmuN~irdlBT4IcaAL%Z?N<&S_5d9%|7zCEzC*fNY=AV;GV+_rMX zKq|CpXS3q+giGa-v`><9iv9}nRR>GWKpqeDk&TC{M*#?q_OaI}<b9HfM=YPsOvUN28(?BhXxhH0Mz6NGYZe3RSqqBi7%!a9T+Z<5#-fiRyEk;zO(Hs)k*WHURN1t}tYJ<xGZ zkk1QIO8sb5)z@$xmk3C#vJFH^pC>z`A7azG@B z7=E<5cZe2DXdV2ND=fepY5aGw13IaN-5v-&J}+4c2Xx}(zFe0-^)dqG^IA<8)3*|qrHdiv4PmeGYGH2#j5>(|BJdq;XTJ^D3M#abjG#d zNI<9O@s`ZKPoJz?Tr}KX7(?K1kM;Sn`3Bo&H9}SyDVDlP8L3xtOI&+Oa^3k&e1LFF zwms&1V4&A3ko5i(>!)}Yjg ztkF|bo_n!b;{uTbo}bY!Wz+0mkX5Y@3k9G)8--ib9k3tU=y~arCub2uArp*m!DKoI8EMYj%wvRLb%g(Ux*D(Gf%bYK`)yNjOpBVZ>X`MPA<&9nnz23;>lc~C=_ zK}CP~gOjSDKG7p?@8c8UR^{GqxlZwLq2n#5LKjukJW})x2;_7^Yc?-hx*KK|ZdW_y z-{1yi2iJ4+{obFFlXV#|_(b&7ew?MDem}ZLfPq>Xzl{HgaaqYWnDcsK1Qb@=LNDDM zbKruk=5Jo-^cRT<5H=iVxDxN*mt{3_6Av zaq(a!y)tL5i(`$aOZxParWSR)w_MZDL7R!whs5qF7q&&-`@0=&B0->L|{XPB^WK^1Kz5JCMo`J~8!dT{G3_ zIzBq^%x&{%4m2Y>HzwCE@nv&st^=GetpMI6_Bwj^+~z79G76rhOn`Rq^jmp4!NciiqaBpZj%xCw|8YRB}ow zd`jwg!ziUN>MN*aEY;OgHZ0KchEY2qsp-epxkKL!DxWt>=~JZ$D4G2&id2j$phz~W zEiE+;nm*li+t>E&F(+<3Xxz``1+ha~TqS6g#@RM_cpekfLSMZ067WGP8N~7bp$PCh zW?z!9#BcdoOIDb0Q7Jf`(LK@Nhg6bO0L5Vx8ve1)Xt%yOu53>X0nfhgC$1_?MieKPD}K;SYsds`ha8W##-;k}{8U{4B&RRUV_7 z05@)t{}|$oT9lbHinKfss&E=Sn~;1|I!1@-V`Y6=O>3r^GT7Ta6k#;_B{seUAN9%U z_BE%7D|CzHCBu#8@3H@V)04@$(v3dP;}E0Yv2u7#hv=T;4Ptg%K7X+pR*CQ7zZ;Bc zVZ60RvqwDM4?^NnK_%BT%6jbZyi$<6)t3^tEIm{bDE8J!kXw=@e(2Y$M2x?P(fSY? z(tT|^Woht~frI;z(b7(J`8CKA=&e#B{SO zK@%75Rq7wr{Br+9)x{TYsb%(WU`)nnY4vT2-`!taW&2-fktZB%+@DNokaM$NxoCWz zRCE|CjQ+#loQ`fHMg6lCdlKfq^rl8JV)eN1$!T^}9A$+izRDR3$_jX>~aJ5e!e!M_P`==W&K+jvmlW)x^f<^sXh4)qHC zyrS7dHU1l8BEoCWi?8#y=bEcQ96qzQ$dir4YaXE{=e3ijK z%YtScm(MYtZdFx0T}TLzn6f*_=PcDe`qNw($5whg{8YXfkMKyXIkJp;hr*{Uk*xt; z+v&9MYe>MyK~^_0GOH8%O?aSw8!{ztW^?2_V_bP&{>Rw{emj+mzyA; zQc|J(bc1b6MWf6;0gk|wcU5wF34R+L$~(&QB+`){bk3)4vCdj4c3DstZF{j&ELM&> zIc4j~rnP>ZfR6mDhwx{roQxLR=WWcR&;GN^ENh8PmxY$r-@2D=^op- zjTTB{po#vix9s=M z+cKMhjOwbFQ5td{8>)@(u6)fPQy;eYs3f$bG3$L)A`pA~NQYBPCAIS1-VbW!kA#RE z758Gvb?l;>1ow|EGS|;dv5loUUCb!Gh2V-XPa*_LNwgI%@hwWlUh5U=*&4}BN@$au zl6}(P)7>QYpbFbp_z0;12V$&Vrm-@;n3M-1j=f~^1qX?Kk@A2`57^ydO1iC?#GW%= zqaM;EH;~SAzJ1Z7m#LmE0-?*6bDeP+4R{R;F)0A6m(iP)V8X&SU6|AWA`Pb_r$;#E z$rqT+@f3k29mqY3l4OO`W$HppK9t}r4^oR5>)M9~33mljHB#+VU65q6s$)>*F&g)e z1l9K2DEnm3&L;KVcj?ZE+$c6`AENi#o;o&3O;yHBY^o?2_a}A|(v{^$dzl$h_9*_< zi%+6ubGZmwpW2QmKfkXPwN5i7R%em^A&8Hz9XlCFKhz(an%L&JvVJ+%IrV`kt|b)FVwemMT7NdgAmM z7;TknnTK6FSGicAu0UIs;~sHXN7cI*?OJ*BVyjJ$`-Pk2%afUCN{~k6nOxfqH)(=) z%ex0`wt=v##U|?FgzI!{N_#cqv!L_I3jqkD~+0a)oMDB`pM{%O~;e}e&iyZ+K#js)m;mQ&paVcN%S|Pz)p`{ ztAQ1*@Xo!$ty9LpSg7{}$RhnPbZ2#gN5cC{B(~^7y<+G-ubM$bT}DDpA)lnOMsX{R zxi`mGioYmPu*ERT8H8>}p4<5^(M#IQ;_m&s@0VEOvK|32L-kXk=9DjmmiVRbi<4aX z6fP6lu|K+FVaMCM7R`BwTGEcI6`Q1LjBGaiZZ{23{p!)pC2 zbOOA7_o7?89v)(1~@gL}tI#%lxtmy3{&poG3 z>o5KXd?D9w#UVC9@axgSM@w6pZWf)&0>{2F^~orsbHRJ5!zOF{%(PI}cM!i7=jCOu z;s6yUqd{AzQ=$;j=WSOJYx_U$LtWSWZBmMl(AyXEy&Ylpm%IpQH`y3-h`7!j(IiD= zoN5Iec0*mF?o(_w9=~H-AE%qjyF{PbZaVh;3Av33C>dVs(q%=UF8pr%MHracBUMi| zo)JX1R1P^N39P}EeeMEDNa({iaT69ELvK6M9vEum{T@IuAz*c_ae1dL`ED?WEV?6Q z`n@urV$I0Tc83B zQ`d8jp**4yr8rSiPmy1CV#eqE!r82D@Srb%l`AZD0!462-K*4i?hL`%hJ@fTh&~7| z4TjFO?qUt&{X>U(U(MzDkUmyKR{g*Ta$dIK2Hrgiej{gNLWIAWNggYPdg=XMhiDdX$PE6SVkMzt1LQY^H6}q*?jH`~JwAFMdc<|3Q zrgg;fsIH+L7Rn@cHE(=)z{lyvPwiu3>Lv>bX{f`abaKmjd4kr9nDwr70H54?&*qwr z%y{bjlmzOqm!Prw0zyi5#L{g@ooNkADWYqCXFLMvi>mC7EVWX?It8wgwSGV|w8 zU2~P`74o{-%H?8^$e)2#lDp7__`vSue#{kjB@tD5UdA+UEc2#8Dqa7smiX5ujI!c`rz2;IjiM%(uFya-e#~WrrSlJXcL#L!fzatg z(e_O!Am~ZFT)+=YyVm2h!>iP@q4R#z$egH+3~FDJgn5wR)8*vCFnkI^EivNIxlzBA zlSc&u+^uNHah@*93G~71g)VMXVtkT0E_IWO2Pt;$hjiarRK z97iaBK+9~UDikwX_dI`um&8^uu0yD6!<=2&(yzZN;J z+Kytg!5d~+66zlp7>1|Or5<;kxXvldFTWKb^^Ij;A#d!ZO`KO~AB+pxK}{f(^7C-x z)H}`swL0ui7EP-c+p&m(qfmlK)|jjR<4Ukl4`cHl8J!FHfh8 zD6tWvR-UG!zQxS1r&FmT4}OTmRQa{I%Q4>*^4McoWrI+9F=T2irbb$HIt7y3Y&Y|r zh8$+vu%bS!a($(3XbcvkQ=cOu|K9U9sZn~}ZcG0CNQ2`I zF~N%OEr=NUSPK1yEGnIqG@8!wyp>KCLbXycNa4R(wAm+Nh;V6E>K4p65Kib>ZUn}A z025HbTg9LjftFbR)ehdh=6cs3-&)t6ZgN9F75YGjtW zmi>z3Ju4f(J`hzJaszQ)c101m1@`798N-q=%s(|fR|>kZufAStCX zGw#}fnDw`%JlJnRLdiOl{(fH+X%Dzf)DaH;8X|+e?sFggfPCzc3Q#lNOZMdT#6WfQ z<%N|Qc`k6Aa)wVH&VJKPiTqVb>zPY;g)zD6Dt0%<-{Ath^jYb`agnT1Jh z3bnil9j-}TjH6d_qAW&L)Zh-$9)RDT{%}IiG~CQ4?0J2R(wK}7T(`vMZnS?t1JJx5 zss9(~?k{5Wss8j$7kF zsG(panX=%?+;)5YpO4)m&xrYYDsji=^Ub$$g}hg&=J6LBY&kqar{}g(>L=$Ee9&(z z{_+95Db`*Zz=zpthaqzU=l;m{O?*_bqjRy6GCIGuzB)KVCmx*hjt)oZsh>C-zNUah zS=yr=ZPi`)Dr-n`7Nbxjcn5pdOK0j!CU>g!%~GN9c9Xyj4mNqLUXs5&W(1Titw?ok z(|7{9{=3J(fe?nj#2jKNxw{U|$dHFwU$M&fT;BsH=y{v}rWX*vdz#uS41xH+=9Jw3x@eY_o*d$#!G+6g~U>{!5j-7{Gi zJ9pIN%7=5B4dk8Fl;+2fT*Nel`nVVXwW*AN?a$O)m>i85!KLwM9?v0v{=*0`&HCGO z2!Nw)q+v2(U|=Q#X+C#`ZH=UN-`aKHNpD7*OOW5XdPd#!{HHh#4clDMJdGkO?B*WS zrO<2Njxuyh$FtdHjBTx0Ycw{(64S4o$}7+x%I`Cw0###yIj2wgE5I->T5C%BITC6q(Auh7>{z_6p&q6u;`ZnOY*_^z1@S z+8dqz<(5{P@mnaCdSKR|3R;uRkBP84012)${Ms*-T6)8MX}IzfI|LW8PtDZQ?d}^q z_{v=3{+V3JEH&A7CT{djNc*cM?@B4CqQGB7vku4vco?4IL6Yymt2^66@=!(1Mxbia z6TPVQ#Y0yq&r<2I;%K<1qJiioyx)y4Jp|x%@1w^3V_`*#hS=z<4B}Y*CcT{mHQLaV z`W%5J%B%f+wmToBc_m_!K`xVJp#|0 z%|5d;l?$@b5;q)zkB6kJLi>=bkkZcnCdQe5mqtkqAj`R*#H~#2ky1J^4mBCqMzvGX ze$3OQOEeO{&J+u#<$h&}UtK%KgHWvFNJ1?3jLI*o*H``4PJeXq(Ws;QM@`qce!6K# zChC$a*Hv0N^dy(&$n50jH@=&gSgO|*9pf5#j}XLf)aZ2SY5x*6Q$~wnp-jnr@?0oB z|IwpdaZ-WJe_kbC(BV{${<_;sFexVTD(C@@Ctz~K079%sTuj))!q@E|@QrA8id(Cn zfmdM-Xx>w_C$m7275-#72&S8TG|M>}fR1XLk@5It&{?wcOj%V;QDL4WI~XWyRLDb# zrn4+)H*kgBfAOj8cG1n{K0AO$t__LG z(%9U-^tycB{U^21v3(}PsNyQq<}bFnv%7a|oXyd@TdzbOvRm6J7~Ju{)AFwk$1v@y zdnONw$(_h{vt09E@{f5Wn{Th3867EeQgrH*+xksIR^Cpw)y)aqyO_w(9!b`ICSKct zKO`RD-TKu$(g6gvmyPB!QtP#&7{ZIUPrR>znB29jrzjN$3lN*KVl?lnpL=^)~ zmk@YSBC7RiG4~gDr#mzh6?s|{`1Hg$eLe=?dj!* zLer^w+U+L(c-@|>$F84~aT8Rnu^*{|X9LEEazgkRhc&-2{(@3slUIQMi5XA74KALbsZ@EM!8xxo|DJSY?+T9SqhmmIIsLKA8nuD~ zMeo>NX{@EMPe|$8&(I%K~7e+M;*@mbBEZk zk#6mI&71lc1}2QJFQX%QT}(J)3ENog^Re^VnXrK_maIeiV_^4X^G(*xkRQKm-TH&u zGzqEk3d426FYccsa-Bt_rXnZRQb|2WCCGX?ESvKbOOEWt#1x)Z?T^x#DIeU?-vf>u zk_r|-%;hr3s4O7&vsT@-qxk;Hvn zFgCHk9LJG!Wf~HHyp7GSLsC{K4oZwbd%41rm%9UPq>{`x3vDSK1Ki84yhSRkGl9Rk z8dgu7-M5TvEPJy;tjghy*QRVgc#d-)13DVfTl?;avF#?C8ROarlFQLq3Y3hIUu38;%g4_Rxtqaq!&v4fzi_J?6I>4T!g_ z`=9?Rs!Tl#_9UaQlVJzg@KyJEv542`7d~G>?^R0$+$frTntO$FWR5MZU#s(8R=|E8 zR%}afQCo_jqcLiG<;d4eaeM>NkPMTVjqOE~k2GK+NMNGo7KFcfYj}|T3)k0^J4B5|tI^%+1dc-GU3lM0@jN+EdsMRAR z4l!5KJ9yI3$W)W*VU!a^h3YFg=0Y#csSh-_nW5x%`?rC51)2;z!+3P48lE37Kp* zUn|ZuOfAGWKJ80cBn?gp5Is?X8zZe~9owHLPBE)oi9Z*FJ)59o-cX$Pin-ra%ekd=l;TIf?l*c(@4pS? zFI-4+7wlZE<0i;TvsYL9ShQ$UYLe@r%#qGip8c4G7dNlO1ho5%K1Q=sHGU&@r!{>N z;6IA0e5a|b*SOPt+AjSrQW1l-itbANLg|;dy5sj@ZaMUUko=%uBa}G8m5mW82xip+ z+6o7flYED7oGP^PONMCZo0k2n3eUZyVsn+rm60aJ_#=9~4Jd_FWzl?Lg;C~7yJF!X zR1d902Q)TU3rov^Z9oO{WURzD+=<}}lIZ{og)o{%N6~9BE8DUaXld{EG1EvMd=Bg` zOrG_`J1Wt+Xy~k$#YkKZeOYK(LBy%u3bW5y`>K3XriLE8DZv0OlTZ$v)uGB zuH}VXiV`88?h39(Kr%X@7`JD1sR~%DEomidqNhaEdt=PP%+5kE({vBoW<~MPH~JYa zf@eGol=o*QCHh^V7xP9dZ{VtwamLCQCb?1j+8xCE=l*USIl%RUDPvmes1W~uaPxGv zOO1;l$Km$(>2`eR+--i2P2vNkZ!ayHOL>Ki=RXGwWpu7JfLai zle?AIBhLMG)5yKC1M zYEs2j0*ZzDwC#wP`{x0ve?Ic!A4H(0nSez+GmwhWk{pM=(g^H*<31?3Q*`e1*8L#M zWoQ}q$z7_TmtTnuho(BM9Iw>u3@uG`C+0r1xgO>Y#`cR-8_|9K{e!CTP}trb51G}R zPIWQZ(*5#5=0>m~$U!eNUt|Q*4i9rD?tOzzUEA9*_rs8dtpXFf{3MX}LY4IgD&^{vN5 zpoZ8$Q>tUv(it%%Yrgd8kL6>}kiW_09^FG5Vu}U1s(DmgPs7!gXg)q@;;4ZzwX*fK zDn4&FyHEaaykn8aMd(QyeIhLG&B4R0_IKbyty+OYe;fP1ua*bIt+uQ--q8d%{&R>3 zh)!($SI(+rQM!{zk6C7H>RWCUxKH;l;0`1C%un!7DyROwa-xf zRvxi6DXsoiXaoYWG=C9m_Owiq!t$7+D;sFb`B}m*k`|WA;yuO906p_2$gMKOzPCJE z%XzHCeFM31{uZA28jLJo?j%a$=VzM|N8<35UQ{!YaS?1dzlcwgh%9nG{QT{~&O0is+q^>YV5HK|UOmq|$p zu)vWDlYB1Kh!OqNr;J<#OS4k$#=DXU!}_Ue+vWeC$rBy1wPX4Jpj=Fy%WsKuvdzL8 z_$2m-NTfYyWoY%XHgJ@Sq?CCDgZN6)m0qQE!!lsdm&1hGHriN}*xv;S1d#(wlB zT>6y}8W9|H9u7ul^`oo}e(l7ky!rbMDc>0=_)b02s#q5;P1W+v|4oJo$WJY@5XX$l zO{ofewsIWbO7ZvWtU@DX3!|ajWX+8)@<)}-e~bWG6etUDzaT-X89v+oY>qOS?Ic6* z=Rj@mTK+lH7^2fg&&;+Lj}tm=OE0X@b{}bsFTub;>~#~9y@>-U*GR$;C$WmZW^m94 zy}m@l3S%w;kxj`B-YF-e&d|=94%Q!8!*sXG45ANP-*2<*8e8O!a2}>bjBimFi#wj@ z3#FxU$JsKEG`))YLXj9(boV+CpLkj?{gxybblZ}Q@NT7-7xnuPHCylZfs?l<{o}6w zNJvSH*Heulp3jc^X0igRHLn$;&~lluX~|nf`oc7c@ImQ8R@bOQ5wZtEGQN6YJ`>PU zH*)MEYOrRq*R!K%(@S^4;USE!)o17>da-A+2-C{9~(Wctz+l`Re*(qB4lM6&wS@2Slv-PigiKudR z918i8(v1QZiQInoBhkJZnD)7U2D|0j#wDhhVXhh7T46bdjsL_oKwyv?U_buiw z&ynZfvGbW~D`GAgBLENahq&bPX8>hiaT?-nmbX=MPJZ zKZfE_L8{6Tp(J;MB!8sybVp6@0)-k`UDd33@GbY|?0B}C23asm5I_g{V!n0S)|4L=Uz`fcfJn!l0twcAvk!vjJTS_3NC7`C_K_tp5<={rWC zan4{$%FEb7%GI;UV5+(|9A4UKKeG>D(dBRxmrod{vx~o8-#^#7fe~=f38IisQS)TCTw<-KcZI6Or*NwC6aoVmyHoR~KeMg*< z5J2ZcQ4XV6bV_U7NQ_;Z=186l5v--^NoDI$P?;c<4qVPnyrGJ?FrFd-958PBUSSnjMRv=llZB`}Mr=5xZ*QH=SX#`MsYEjgGWo8Q;S$`g`S} z(7Nc~Y+SsqW?M8-v~^K+&|#s!&!v%{&{1FO$m^h^TAF|ab|WE8yrUjZo9&~7_M^kc zmgzB~UqgTGf5)Z3`u?7zp7#4vtB3&veFjbrWL;fxbJAo6XK1T7ow#x(GldL+J)Avg}f+F76<8WpO4THbj&rJ;0%&h@C1#N#vz5S24 zG>@7DA`A#WLMQ{Ay(9HKmK|rTaTKc9gbK0^`sAqf&0n!LdqI7T@@zp{<@Jh~6C4~T z4m=oYh1q{qLn2gA&=G`u(_Q$_>_)G+(xpJ+-k{_QK`&{uFdL^HXI^+qvHZCZrI$2& z&aepZ?o+~4x`Q4oHECgp^o4PuHwTZNaqO0${O53aXFaCO7k;vW32SlKVewZDaCq7_ zfS9{ZFv|F!_bwzi6~X%&jEZxqXeIG-&%fYMTK9I(A3RyKmyzhBQw5k@ms+Uf8H70K z!Z}QM6#<-*L(zvt?5M@<13^*$RHds?G+ezebXP>x$zJ!H-f{TH!Yb*iRu?`u8b?#{6#p%ce<>bHv31}#m`IP{VM z$U$@y9Q~)k##BPmR+MGO(di#z#j6D{g~~7AqW%CR0l(e1$9^o>LK4Sy$pR7u^6k|L z$dLi0zO1I8hg4zI#eG{iW4fK^&fs7g$-ml+4vM)#gE>nBj>=P;GmQv`f!Y=0y}WH+ zaN^W^#XY;v4p7b=drN$mnT(ksOruIaiurHMAxQeym~u-r3#C^&BE}}R&9UoPL}`~UaKazLO3(4hugZ|-qtXlWQyxJIB;g} z%Iq}5t1A?w&adR~F>*cJYgt7~PXOB~lSts2M1rt-}LVk)Ae6{EVTib+{+mkJ%_+=*~ZY|*2^ zT(T_nf+Q-eF#%-B(%D3{b$f&P-J*J~fAWq%s!gjOaYuD4x3CCqD+}kS(^c(KBmLV! z8eTbI6-!vliS)7!u35}-6iOE_ZQgNsORU5Juq1E^P3+h=#B)>SBwlzhy{9;xNxun5 zF*%xyH*p3fe1I(=Ej&1X?aM8K1*8nF+@R=K( z>ruC*$H9vH6`uTq;O2qT?OVT$$lNfMaBmjur;ope*&+AEZaAT0C4z_DSX1X@LKleK?16QcHdhYe|Xjnk}L=^nUl6@Z~t72~mCwrPt?KPrfo{VT~E zW}R5h)TC%Vs92Xbt2X<>Kftf-&+jA=Z-AkEqAqDNX; zUz=?1RxkpCy_VB+9$>pzE?Xx}-lVVg239iM2HonXQC;tvr!U_NEa;glzxC1Ay!y*0 ztI>onQ#Z)0)5a#qA^NR7Zcg{s4CHeiKH0R!Rmu5J`})Z0)TwU&QSP{T2kAs68Z5lJ z5-}#w*ScFl#f(Wtl6_NxDt^MRu;>$-is`^UhkYiVOhO_gLbpFVS-A3Ut*Uo6Vt-Qw zY=7Gr68i?2?m_9MTzLb9K|g&&)k~J?cQJg{oTR=m>y3 z17+=6o!-?>MuC=BC(_*FOhB*uY*)^&HTW2R$f_vvGkSiZJA7c^s?z`vzIk%KVB%L(7ldcPQ%rr{d+Wt~AD4 zH#>vmA^d24(%CQf0UloTc5F0B~yzEXJiZTonyf;`Qx%2peK46P6wKpud+?>rq3Z? z1Dc$gl%q+#iymZ!;ZO#m=d@`{0m{clz<^3795(IZ^G+#+DP*LA3JoKY3$qcep66}O zSP!>h*Ti-*h_mrR?{h?z>GsID<7ks}B3mBHxh9rHaZWvg^dTSc>5V3>kDUGZ5TUJ= z29ep;n+H!03h{vUz+iF1Zw`2KHjvk*P3a%Is)0c2wH6f_W1#m-D!{@-DH-J?n|Q7L zDL`wotQ(8?yCMm}FMem&T}@KGHi!7jUGQ?pc|DFZO&QUho42KcNxwTU^fs^w2)&>*gHK=C*SQV1bJs0dMG(?|+;RtP- z?_@amC$$HJ6BmLeh(|q3?Fp~7Y4S-U-_x~h%hSj_1DV>VZ6b zPlE#;7x^XovtQc2nLUSW7{y9184Dt$A-;De_S-wxeN_a(+D&+8V-fN(y1+KT0Y9jGCfV8m{Yhl(CZ@=* z8ov4?^ziJ^ug|p`0aEV7VNmKCA85l%l~}kb_i$!V&pWR*7!X zlC_jJ6H8mdi#@^AJRtPBv6pCY5_nttXmfI%PF=v@%Kee8vw71Qi#V=O+I=&Vw}|8K5%VmyL~H-1B=&;UHqDIP zJ@t<77Y6jG^ZpChUwXbBGY~sKHJMKur|;(41v=ath}-3l#=#gyx{0=#-2a~d5$x27 z=SHy(K#a(lP{}1v4`eO5?ewUtpLyZW{K*5zIjmecd%Byw?wE0D%C_7M8YfKYbzX;J z0pI`%?Mu8D9DZ683r^4GFhIOzY}5>uQZy~de5)ZMPoO8A8xR6~XeAY2RBakG^9qeC zd!eE&!Q2pS6O)vp?#dhLTOXauabT%@PwD?{2gkRjP*-0WQ!58HD?!{&UV9eS5;$O&J+d_^;cj*}uUgLS*BAlY zC1-Kb+1p2#?@`G8KaaZ?SK`-W;+P~Rzf+Z~1D6l>s7R(xp3nEtjs_}zryAP6u%vg& zf#&wLsgxCxN9fW{kr5bw4dOP_jJ8xxI&bhWl?L1)Q}!Y9dp6_w^f*A7k}ub}Z@D0~ zShQA$iMgK_?{!3?ME{7|;w{=8VxiBgnILI|P0jQvfE8Tc6u3!EJ>vI zHirI$hjhmB_AmIgvpRweaEhyEoeO>M=2xOpT*}+NxhnC03c(rua_XxE1G2W4NYiJ) zL<)6bUnL=}p=uxhl}@E}(|f^A*L)?qP-?kNCn?9ibwt|n87*f)ZH);}7k9n2=Pe8z z%R^UH90>f_OlH?zJFngUT-EogZv)Z7TX^3U~jT>1C8$0IBV= z=t7u~R$O7yuJ@vY1RJL+bxTUcDDEqZX|iNe+_zo2ARf~{BlE@nlO=RN@|Vu;GVc3z zrcCo~CH&W3&9!kqZ;We@c0_`6QjPOHepqWL$UwtV8IagLAJ+h~$s2}e!eM#uz?DG9zKXyM+HZd)2OcEqA*VpR5IP>Ln22WyDm?;8|qj3w{$sdIpI== z#DGNnupf6(Q%Gqs9}!YO+2tF0PIw(I7}2m+*$4O}-U55rx7DLS+&Mu$^ZT~pu7%11 zx)P@;p`DUQWQT;oRzXC&>q&{B8EHwo%n5xQL1)+ntnNqc+**lQN$(YS&hluYsiPbF zz;%-i*^UT!td$&*5Z)Z*|3h*@Jdve-k%itdk`AMbnIF*E8nO=uU>YM4Jgu=rm|pQ5 z5~|M^xvRM)={YTTSA{$L(dcoPIqI7@2oTfhuVvg~$ihK{_BIi+U_i1YJQbECwd_e1 zi=RTxKChSj?mj6d(cATa;zHoQB&x5;NeJd}N{?Y`^De3;09aP^n3-*g*ne8IiWYk( zw79ccg3$=KXdCv97omzLvJfSEY1wI?{VP?SbCT>(2K}JiLmr-_Kdg-p*^q8Oe8T$t zZL4Z`G2(N@4^SEL0@)?2SwHj$m*Cwq!6Z}mofUt%V-1wCVsN1_XOFt;Lt*@qMWtd! z`E@}J(Q&aRO!XKa<^^nsgs1mmdx>Ga0mNS)s-*JfqgObmSu*BUH_EvAxgU3j@%oJu zIW9?*D69HcuA)~1JyQxp?TH(^QtpYTQ}r!=ci(AB_Ha~}hd&Qf-BvZyJ5?9QvhqA1 z;3Yu#d=%cAfNYG)0XKApCaX%aA@CBJaVWewkZmc%Dju!-J^D?g!74H5U>TXLj0A4H z!i13ig+tIcCApU$r#OsRb+yBum!pgIS&+XN$!O3p1=Wa)vohWbCZcAs$)4XHD$zEg zG9s7gr`Y_?Y>f!{A;f--Gu-}+k85+OC@cFJ*Z=}$*$bREp+mmC(-Uwq{@#~bLg2oZ z*k9MKMfo9OK@C6~@rkmHajqENMW(qUT{qJD%=ZzOY#naw;Ab$8T%wo-_X#nB9Do&Q zmkATk-TBzCFYK)~TX;vntGSgH`4#%fp;LxX1s%j7zgZz=z|P5)Hz!frwKVoFDF>rz zkAI+}#?Ow;8*vW5h?Tpin5yw&$k5u^`dQgcibuD3O7Zq*bkJQ)rQL_g>+De8{v4c$ zUcD|*xcpYue#JWL5X<55Q!@0E+{E6vJ0ccQ$DYuo+pPqXce-_%talwk!O!~+O#7r#O`pKdirV+s(H824I8B?yR zCnPo^IR8+!0iEF$+PSZK=v-}uEv_r zU2{T?faGXKCX3LlsGfg3p`=HR3;u z?4vCKg)MfJ8RKWx?34$13nkkPdS-$BWz=0&;g=jr`tqd@ZC(#l7@@j}*c((q&ZZJ0 zMgHbtIDeDaHm&cO5Ss>f$SrtShI}Ao#;ffy30|x9+8BF2<)Z4#^qEZhAQC@E_YaGP z-Fis9QwSjLegv^G{v$ApM&7qt||h;td7jmL}cn3A^yU?lB8M;u%ZMl0x3TjDo+1aM~r@kODEnB^;uL ze_QgD&s(KZR1bgC?5(82OwX!O8XQ1!zq*hUlx5{y_<+Z? zrS2eWBe2N{;d?MiZ+`(36bL?w>LL#wVUslg+Qbvi!61Q50k5|rjw}R;!B37QR-Rz* zL0+zO{tZ5SNg(PWro;jWnS}LAB7r`8Vu37#s2lNvajugZcW2cqroI3zbQ73-oZSR# zXl}f5=4_Glc#QIlP}F;*f5SB(9J0#r4Nv`jV9K_I@!g0tdY8Nqxk7=H z{fdMR$fyaK?*QIti_MjS0F=r(I1N!k&RxQt4?~*l|vP4V)?tbp92&S!)o8kx$yYgIws220|paqJ^Z+)9pXmB z^vbeu=#vY6M3t0Dzrg%z%-cJjO^y|o{auAeAW&pe?mf%?;r?&FJAUBxEyAk%ZF}bi zm2`yN;z#&iK1e}G6+5@w!buCSUj!dSI8?JrvMvdhj-GZS6ZoyUxzloBvZL0D^!>7)J0Qxr~DCCGCs++C3J=QqKOy~F`r6cJ3mhI2Q8nB zaghcuz;&ATiXX`{f767^9)dH7{>33qpqTn zb?|Y<8s+EpxCYwxbM+O+>M9oxm@8g)g{{jj;eB87x1>$j-C6=7$mzYWh(Oq}SciXs z@=e6!>u6wNIF%c*Sz{Ps#bs8TxW%CaE}V|amAcx;r45_^RJi?Z+Iu@?cJ10(ag}H0^=2 z9V-%$eyNd^%T$&3d(@TSni%#iRSrqBrl$y#?Xcy9GQ@|yhh_y`d(KH^t~7Jrq^-C= z!#kN22#eTGVxgMZ>F3QYLwyh#x^q4-U=Fw7h)?@jK{rgMR z+_7Bi&#_)t20P0ZnRwX8F2hWYzSmu9GF-eK{fNd_)B zUF8WCaa{@ldtgb@m(5HF4|ajrXNWCx$TOy0C9`AT;vebnDIh=gTj)xFUjB32nf3Kd zS#|s_(IUQ@v@Vtxr|p~^@!YHA2DU_OpZo{r>Z-iok4&y!{mj+8{SlEc&(_8@M3Kx- zARafpD%}a3+P>Aq3L-vx_vQ(sl6x*aE`;9LC_dy}dt@5Lg#g`P4E(Q?J`F)m(Xi@To zr4iD~QIFhUI-Zo`FTcSWS5x)EsSro5cZ_ufCl$P2>0>?SUn*HN0FWLAG(7AJ%~xQ? zlFwH4H{wy(?p?VwD=+gEASJ1@!N<=-m_gUjiU#XlSI34*iN_nNTn3+3)h7IcqLf^G}y!NshYK&u|}tzFYs}LXIPsjhw~|AN$2#$C`jt0Zfh!}!W7|O zt{Q8`GUK3#u?KhN(kNma2$AHl=fBHJJ~X^WTAiy^gsoff!Wu_eF>QDa#WnV;dx)z% zarQLMiu=%6q8jbKCo4AzP!LkD_n~(n!DG3;-`lt!CC!^^RNp+ypBRIj>Ig{Yq8Gc^ zm9}P9lglmYn4X_rgyUI;*b?@H83GZh-w(m`-A+7vRqs9GCLm^D>fJG}X1@>eq}Nr3 zNLd2OkzVhF0`y|ceuE`sy_Qf?4v*k{UsO3q3WCDcY9>gSWbQP~@M_IP*)OV|rpYOb z4?>XQa`%$Qr(lLQMCqguBM%@$V2^TOq7)riv!+iEX`_0%376jUsa3Z5HNJ8;&Ioxj zG4nnQ>nzU?XTRn(aD`ENg^2!&Tmq@}y-HMLrahW>O+?g#T8kby1rG1XuNrNoe5)46#~h6bkudKi#6AGD5uW%pP}rQp=$< zgsFv^vv(r{7IqHpU2Rqbwoa%HYL#TixQUR~T~69oGTD{9PlACebqB;BtCddW@e*IG z%#OrZ&p0K?@E)aLtQ*ARgU^kSqrr4T8YI8zjF-lL!5LVNtFK~-o1FMr+LDZv84_08 zt>_?V87KWJfxBEo#z+JW`xlfG!ELXdg^3_NAXkivAyuSd!nr|*R zI{P}bQ`!Ds+z*RZJA!StsLJ;_JUqT1vnV!IB1MN6RD7%nT%?lV(Vi?r|5r^vrzaT7 za9;v#HGIL9_2cW&f^7?(5|6;hB^lwB^)kXG#hJn)!__-iml{c87SICz=o15X^UV7* z7=Mb(=XJQ!fL91hV}gh@D#uQ-1}Ov41^%{FK;P_ZJ#1ktEo6?$K#ktu8OPYLH`@Pd zFaz+g-2f=rNw^wGyl5hPe2olo>hDXA(2P8UTin_JeeT;akK5#%WRGi-+mpGQf?J%# zO{m8u*X^pub;a#f0i{k|A)>8!m(ar;%D7N@PA%aEJ(X&D*bUsKUpK@xm}0d$xp!YC zZ13n|-@zKi9A5J2j*3SwB}wGkM%jo8LpDWag?bBngCd(BYH_RnapF&mUsv3-(59;1 zg5UV7dAuy?a|spIUmP)SoUG_eOuhrDul88ot=@lJ+nW+IY1^jzM$E7H8vbBfU&4i@ zJh%Fn0tuP(Oa2nScT`YpwpYyl5z3%&hPZPf>Gw-?Cv`PM3n6N(dAEeHd2{OLe8NBG z=C%bL%fhL1Kxo~a^V54l-K61Ht;Fu#deAA&&yZ^InWS~2@V0?eC!iC5!H+sQWCd+U z{cH!UMn|meS|&|SuQ{Us*ehb+kod|$f+~H)uBl6P9h`!w$Xo<{7Lw{-eeF-Gx}NA- zHUXUkeF6I_|I=tGnW?s#KmnM#^2DZo2TWxZ*2xW09u&Ix@(_FV+VC~LEgz?fBFy-1 z3DFY4SU*wGLoc>&yTa}4poT*pP*oUlxtI}vi0LQHe%L(Z{iEWi%g3f}?EC|Ib%W`= zyX9sy>kl!~>Wf!j58Ks(=3CCAegS=(@wIgII_X;Fd(>_mV}J$You>yIYD+bw+VG8K z3*fi!eZYv9UGm*E z4#1N{hkPJEf{oLcvg4ct86g=Qgv})}c)piOOa`JM&muc$CULkzab<`^Hp1-(j5?Ii zw>V^MF%t?$b&0~FI=rk|4@}3}BaN*iY3tLMb}AHO?X)f@uDng28E>N{o;0F51|@n( zq+nddM@onHpY{?(IUmX{GNxdVpP7O>k1U?KkJiEx^r8DTbK)&2cOan|-a@g5?cLN- zgtjmx72@U{?zPjTph#8VP7a6tJQsY0S)TIK$NnKV@N8FxgbI7NgYzCOJ#~eFrKc;j|k`FfgUfOp@vtuIMbM0v;V*C#XN1{B;rrFFJFBW3mVQyRKMk zQVg6*;1}W&mGaQR-N!bm_F;1yT7XnJWSD9EoJ{?l2b3tj{a*i`YX(VDxOmDc&m9Kcfa_o`n`gzo%KBwtTnJ6+7O zWufEc0u!#c%rw@0$cvb3DjDT5T+#ft*zd4Q0{o71NzK;v94e;u*=@gyKPWK~Ex)^; z+nM!Qv@wFT4v(d+-iL55jXdJTcbg`z&%_MYM3Kci{I^Ez_h!I=q{QIrPULk-i2PUV zZ;#JWHb4$(GEk$!{q`8$*B*t^Zw{C8V6X{w$RWZKq%loi;`yxiE$6eD{^-X>0tKLq?S(tlEcuI_vJh{ zr}ez|D<8*Zx`bPDVCOH2w^aa`e{m6-#n0jm)ROA-I^1Sj`4><9LuAntEBoqQ1xS$3 z_naxWf+l#veQNz(KNwX|qNZGWwb`8#h$JZx-^5lUy6}ZselA3d(L+0QDdA>c5Tb|M z(oqdjg?MBU$4P(UG4G80YFGBPieE&?hs)<<=VvA{FBmAD@*-!D~)fmWP%~jIE_ifjL|`)W@1G?36?r z&m=#N6UJn2GI)vSlD=EqPIsAp=o=@5u0woVl%20)1aK7hcReOK+Fh!hIP9NJ7sv1Q z?hMj8|44SGy{fv(NLu((fJ@Nzg4yL6k7fa1+LjD!!@T%xo7F!wATe1ZJ24x!-n@gI z8RCkJ0A{A3JB$E(H30GBe=4gn*w;elsh?5XaN>cNwGw}9zV?f_*U)B`XX#Y+%JBU> z=}zlR?h{+b3lL*X>gyPE-*FQAF3UU$S{;cLUMA^5zi4~bR!X!~_o+ZpY-NX@SbizL zp;tO|{dp%<=rh0lXV~7O-)DtpX*ypuyX2V>7|E>IeZY8mogoMLI3v<6iu4OyErd3 zRtxW7lXfHrs4Wc--PzBI*$#2b`;7dzrCs4)Y;`?CUZxawb@f-7>HTnxSh3O~14HTd!|=BQ-KnTpeV%nTHrX!lV_t&dHN{qySfL3A_0 zOmIXWw9NK)MO-hc0_ zVBdS#{K!HDO=J_Emuw^-=RR*d-j_MtW^-MXJcXWi83{jcvWj5s(*s$Q@vkSXsT&KJ z3e}Z)@=r@G$E5&NshGlm_P)BZ6ye;#p5FOcL$as5=xTq}sz05j?Rv!Qd924pOghm? zR-^-nQmK~j=h>3b!7tpttg4wlwJeK&6ViKKQLCY`{O90g-V1)-uA^V^+@Er^G7h%v zeLwdI*8*Gl94!0p~5>l7xoO!Yk=&lwPXeM@F z^9ZTt-G!2+CE?W3UOhSGi8ec!Zz}86&nSO}@zj_Av$V}XQ)s?$=$-zO26>fn(U-L?h$Vn9f70R%|zmy{|*>KiO_{WR=tA@oBU!^9Rq1*FO6v%F-E)-)vwLQ?S z{GQR-?f2%1Lgy=Fs4=mD4Zp9s1ORh{!0)uN;^>iC+G)w=rj~6K)un6zfZ^UaPTPUB zYEW1-@c-F_Y{&n97sFjD*;rt)zjW`YbeZDbsRq7$8$rNCF>wi9s_TMFS&Cq7e#x>c{(Hlwis2FKU$ftf7u`Y zEgOQ(l4OVAxqbLx2Ul0S&()z_s`oqC)wezms<13sKbZ@W|0#a)cD?zjkI#i!p9-jt z6TDF((T*(s#2NI3fQ7|~jj(!Lp;Y|XkPdCNZZ)r>!E^ge)VoEu^yVv zOA;G!sv#`7HEa73?k12p;yx7=C0_=zeLDl1%%_mJ42DhCW%Hlf^q;7g{hRyrXFI3& zs|UxAFq%?Oalq2TYD%$c4O;PG-P*;X*!^mSG3v=j)=e&f$PxQi=(xF8{_P8&DU*Z0 z2vcNG5;pYc{!V=3Rc(2gfnIEUUcc&jVbty*<>bsMMxG$Q@9fRehj{Z?`|KA@gl z72HuRc{5sbM-aF|sV93y8g=WWW5xsI}o zc+uR;8!k5~e)*|pvqh-GiVs~`uNeiDUd$q@OKY_x4!`a{Y8sysC3XJdQdr(hdMGHp zd>u@a3a8G@ik^R)0@DKozoaBSUeq7jvJx|YVHyM7*NzTOy-SVNjQEizUBTPG{*FO6 zFIZSRXD6sdgM?+uxcPu<_SlvxXd)j+k|h12Y7rk9afLnO&zreZq`y|T~kj-tt6JiMY(@<%$dQsX*WSHA!WsI8xzR`6hTr}vhaK4y*j>V(hNfo zs2CO^T}ZwrI^n5r+P7y%#~3okj(qD;7{B1u0e=p-h3r2FwL(J1Sk09HawX%JF%$@E zI+-r6hYlH|UBUsK8pdqi-CV;JCm&^O(=w=y4Orn*?z#n-0sMuU#msHv4`Lr=$U_!I z4?k}j!xSVVHw2pvVm9DXbr`Qox&)8h-ovI}$rNbCSd)WQsoKI-eBE26hYtF1&lGZhY@Jet}aOPn`1pT_P35;|zUBfU?s{ z=ZsTVtgF4dyt>_K?YOGb1M1?c6m;9|G3B#ou=FNsMBhVzXLykm zA5-#&3VOU{p6Q)EdF-FU)EUMAIHdIG4!esJtmsJ5q6#9?=}0d~fi@_1Cp*gXmJ_uhKk}ro|3AQ3;RE)KMi55&Xq9=5hL27({jJfhf42bI ziSgB85P6b7bL%?=VWQ6OUEREHZDM6CE<#p1qS!LFZaw0Q_s1m7ccwuXnIXr7jnHl* zZmp)RyDwo}gN*hkH;pwPR1}Ydk$P#nfd|wK`Uy{EKlhNM1iYXrSOyy097sm=Z&5hV z%iI(;;HVO$EB^2j$u|o!_NHi=*z|g;dEX95Ws>n$uKLmX55NhwSS7^KuNcD?i=nac zG0jiOvGjY7hGz}MwBWCke5tdEzU`0x`$q9PH{6*bt`*w-D^>=(c$)BfQ8fyX%?Mdk zc8a9JY8LCD<7_M;^3I2XHGPfz{e?Q6qeHd-sv4)Z?fY)Q?YfP=@inItjTHw$+%O%$ z%m%-29p%`<{vs;4@i!`)M8A9*gwK%3!`zGbR1DDQ91K3C+8G}RH}3@JfC9&$A~}w! zZW{?0&lyURbs970+pU(yA~3n&p(@0nw&E}eatB6PwA*HyYgCha}hhE z`J9^_*iVkCUigKcE#eFK)3Ge2_`Re!9QWg;F=*vLDB0@M5CPq1S3zYu;B6IPlgoe&g9r4v%xvi4a`_qz-)nEDWHQv8qp!@dPZBsI? zqX!Cq5j5KNLq&R;E-@7pU&dzB8X1SYj12trX7wQI|Ilm>^!cOYpVJ@?$@K*W=zWot zK*el5;w^91iyzrq7WmNyFIJsPbtPN9MoRoc;LEr}je}+wq{Y0^)dPrqAfHi4M zGenam8lE%6{>RaI$5Z`(ar|4dFDl|*M999lu8eDjkjyBXTzl_5lU&KQB70VtbnB!N8Krj?-##HzK9MNk(uV~Twp5yH?K1>vNwAy_itvF>QQ zb1=Q1wYayfYdIy@KGF&)w;(V=7+>?c5r^gn{ZniodPQ+y#S_J`_k!+2B&8OC1ARI` z%ITpOl@9C3df3bMO^(Di*+>6rmBbaVTKR*dj^@lZ@=<9G_4@VKe<7_(i?6D zvZV91S!#Yl4WZ%Mp1-emrnl$uAX4c!%s_C%~yBp%Cm^=e~ z4Y&OiCTsRmuS_^eag7y6@m{K@tzWv{b1BP~FQdP-kuqg>D&=gAH94H;N}R*F@nd3_ z+K2|&=FQ{X@eF_{+@%Py&@i;#o^IxPgIGFBXb@p~Lo6gC&KtS>1nRfe+!r*WXKQq8 z11RE0-`A1pL42hyta{Tu|2A9+UB3TrMeE#0dCu&&T~i{~i~DpUX2=U|3HbTGwI4*) z2M;Hy?8_L;_`{j|mwK%Ovl|fRxX*R9n(N-g^$N~iT90?QJBwFnZOwrhILUP~9+nrY;DVu^coO0zqZw)n1aLrr&Q<;%Qdp*Cw z^GXY*YFAW9xqF%vZ(~xL62bplM}^Dn$nhQDuB`nv5T$^1)!@LYWQ&Kpez!Ddk4tkQ zF>>Smx5YGayFaiT0dSy?0*Pco*K5JyroQ**SQx5ke9!}@6?8FSJ!==-HO;53RmsH-;{?1 zaPIx83aqZ1M^)7kyncw&A9s~z-w5x_wyCrBZO6WFvAO}Lcx;uFm61Cd`%)AAIYcD$ zfn{WIYRt^8z?~3Oa}$JOi|0Rg329-zWd z+Q4t+sj}~jjNmfkW2*Kq1(4|8^gAE7q=Cy!iAEiA=W5t9siqejmbAC>TUu#oHxJRa z$SbEjc~8hkSCd)z`B`Ey)wg$9l32h&TdnxA9`G$`rtM0vt0LULy-@WJHYYKaq-v<>uecp=r52-}3yY z#f5eAYd_s$w%*al1r~>6xkNHc{10ONUa#i9Ul<6>^;wrN4(1`G^wJ3h<~%apL4P3l zH~{h(A;a15&}g_|`lIR7RCIKSd?=>I^LZdmtVa*D3k>}v5ThQ3_`q$(StkasXC#W5 zC)_#hfgE-&ds5V;q6*kKn5y(*{hNZ*P3mSZfn|qHVGle9@By) zp8Fnm`++;mc3|j}Y4jvFr{%QZnyuOG1rYU8`ebuJ7IM3aeFRPFC-Nn8v6b%MK>ACj z-bYqfsZ}LFbuK1Z!4J{3iRl1v^hsFp0&&mR3GP*6srprB=K>_ct!b2mcbY$QwH@3v zOt{h*`r0G(BlVdF`V!k>+e%(DMtNB|%4E`}s49oMBV0&y#5SN-N!RzsJgW><2J?F+ zD(N+F0~vLA_}X~(FiS~DcVofuP#TrY!~C&US!VySbZPo$Qi6$&rhh90YX zq0Sp)K=&72NzQ#M{-FUa$KWXDWeuYeP&OJ)TS{9i2&F{0k2?bY)Y<+mSZb{f} zB191#15?;9YKw}yT7MrnVcM*%?EaYe?eAyHg?^n+?@dfO`mk>7yWdKXq1k~fF3bmy zEDPvd&7_i83k+_8P$x1~mw;^vyS(t*c-n6X&&+l`UReSmdYSZO9;(rO*xuE&0d-zg z9L(S~ugkOp4g1(YzC!xX7lkYtIoDXTZRF^ZhaY0T_4tTme?)7;%O{4u92vH+5FX#* zuBcDJ{%`~c3Ov7{9Q19>JiiKLGzvo>HkcMzy5K%-sdDMKkvQjA+kBe=*U1e0j!SOK zj@D-B_?XW9Mt&}lC;umCHrpFzI1Uk1FtkNAQbuckkQ`ZzGaKk4h{$PB>B2;zFCd{D%UMgM8E3)uD$L_r+1C@}_BT2rS0n9rQ$B|t_3TAue_<$-pIgroelg81B z9q(ztfcPl~Xk!8%zstqpL-mXpdASbmvm9U)WP%w^=mSdfGnrM96=3~jaoPX4Vu)=b zl~V>ZjoOJ^`J*3%KliZ{>dZmw2WAB!Mq31PVdtf>*1|G%+~X5ySrWF~A+7yX3q90) zbhNDSMH#+^y=+%H*j2bpDBDs*Sii?T4)35bl3gmrJsxQ*uE_C7rP|8M?eMSx!oAXUJDR6=J$S4@10aA0hN%Kr&NLLusI-@DPRTC zHzki`IImzILEh_uj8}m895%7Er8zSALvHf(j^Lp#HOu7-PmrI&$=ebkQe`#6CXpca z%76YSA5`4Hx0L0EDB=I&xG%>dmqop8K%IE<8;1hLjN$ipXqQ%vHP4k)p8laCeSgwpg#OqV;NX9?PP`@uv~LJ9MMW@<*`PpISBooyL}`QIf)JWbqBXE4N%R2MDQtEjX@~@ndsDRzp^&D#Qv$W2*_-kE z&j|7lhP57~j{1u+pdJX2=IF{G-_)g&c5MbQ-<0d#b>Vy!RDb-0{5*u>fyoD zlK~(}a$pB~6;uXf7l()r6f=+blW(;GLEanJHlMQUO`|xFKGS7}vcQ;W{J#4o(L&hk z8J>|inx_TN8nb;u)90ULGP>V#e^?Z-UGHfQuNBoodCfAWnLQ}`Rh`s37Bt?KZ2w$vN?&%vsg5nmN3Va+a zvOrD_o=uZDYff`vCB>b*x}#2ugV(nQ)@2}qy#pZIWBp9zr#9JhL!&8*w);tbkFQWv zp`si6@WBNb2W!v%+mB&3#JcF_-3mkS@ab8bZATgp@NC)&sD+1uizKXUvc%i@;P2W& z`EYKVAO3jn5I~9L(87+kE(xyaXpz+b#?V%lKh9y7PM`FjcQC%*t3w0Q?rbqwHiI(& zT}Mh6Gi(Hr;b*DU|K!zns2|!*Y_1B9KLk%%+Fb;49U!Is`pJtXo||9VOZt*596Whd(oyo#hrs(aZkb`1d`K#`)sxTdkPXaJXo=dH-EoIjH3nD z(g-ow!sx2C$11s#2U6VeB&C8rQ3wY5w>M=g z1&?lnwZ7jJM!y7WVc*!#GTkr-TL%$vCE_;erf z8p&XTl#USly6eyQ7x~p|L0j4|BO4ud-ggct^~Ky1Bz<|?5CS;Ca#II4pISh?VhW=R zT6{|mti7$x>T>8p5+Q8?|BvU7EX|8oxCm}Y+v{R+zS9;r`A0TO?w$b^z$PwE9NUn? zK`X5V@AwYr5q{>;N2CQ;cl!s-177AY! zWi8Q~Y#7IeQhIW0a3o$$-c-{a19Dm)SSnq_-@z|6MCR1yq4nV;7vp)(Be+g&0Y15C z;ZY`~f0nKFFVC{Vb8zPE3|opL+~_kieDCOw4#?mM_a!D}zYr?9v2gD{M&ahX!qyZf^b1O z`oQ{ZkiG(k_lbaW%xeHQC_}17yR~5~a<@JAjU1Z51&vxN)rqxTA~b%O?17Kkgp{cw zlI89pWEMYVFL^)(psi+$KT}?zRSTK`q_&w`s4ty9vqJ zj=1%B)Clh=?^3A%MT1cBr%XpHXzj`SlwemsypZMD{k@tUD&~u;WP;1Lfp+n?$0^k& zAN*!~eO6U2lL^;oC;bl|5?UwUe6q&nl9z;$A)LHD4a70W%6u{t8PhQ<${)6obo&`$ z(a*a(!%;g@hG_frL&6I?ZLk7XM92&ZRcFHA4q(~PKm`aR3{Y7c-u z@A9c1@pB!zrNqY*4Bjib$m&7dU7+zjTlzWd0yX?xF0wy>K8dUQLG?4l(7^K3k~-s^ zv0TAEJH0Xy@uD(y?UuoGzmUngt!sg27lP=*n%~F^$!GQ(;{v~!*-n98lvZQYn;B)B zW0SBKni{EnV4mVHX!PnSzZF2oNjtf9fS%|bW#iMF?~Kr$wZ2mpnxG_K%ixpS_T(7D zi7xcQyUUl3E2wqjp3f8>`?Mjo)Dw@BL|~?3TkcxjsIyjk*MM=s$<^TMqqF2f6}*p4 zM#SC=%W|NBsT)%*J3f+JS4NUltA>~_od*phT(8~Lmp9(xtN)&=Vr)9_ArP0`Od3`* z+fMu2mu#c^v7xhJ`u17Vr*g51SYhe63opJw<$$fk?29k?!rFQ}a~)d2nO!wC1Mwt| z`oQ51!UJfJRN{5m+Od{NjpeoSNY!hL<{SO3sZy4AY~UmZ;<$vUY#c?cm>zHBjnP`+ z)m|_E1X!&lBLr7~M%2n`v=e6hPAi}U39M^{PAn%sCZk(~#J)wu?Noiq=PF{3n0lL& z)1WBrZI=ue0E>}cnJH-K0+&B&IdtOx)96^B_sahCD_5@L3#X zmQ)m|BAN4kHh0B1J6l-u955Ja-q-z0KX+7dpw(p*LhU#uh$cu>`>cVEBrPkX3b&GV zE`AyLM)|C_M~JS|ZA~tGM#f0KRZSLptKu8!KvYEoT~}OB1V-dfv)Chn{WN!8UG~Bd zb82!-u8*YhN@L_X!b*njP&Z}kzsX;(u(`%5!f#*Is?)e7BU+qDt)OAVE(arm&&fIn z!_=b`hQ>C{M0VIBcJwN-c}pp+CHqXZpjxK!ff4dj|J@ zkIQDpzYWg(8EHKYMDnBMRJub*Y)otm{IT{nv8^f1$H7N6UqGZN|1s zXsWoJ_y6qI%_yZi!cbR@WcY+l-dCj?^Sa9ltRp(C1MHn;XtkcM+1N6)KOg2NMc(vx z>-~34=BIQ##I17jl~pwOgjsiicugdjNvyMDb(4K2d|9_9qifGrvVb|de8e%VP8E^4 zLHgSvd85?_BdrA>F;da4s#yXVyK#Ubo09j!5Ao) z%|5sc{tg`dEcz;U8&;R(;pCHFEAoxOHO5(EFm2#*+oQ3@ta zz5^_Lchv#IJ28*DRVwGUjk)4)X?W{&E5t4w@Tj}WGyQ&uRvV1 zV8~62l}}syl6dr^5e&?4Hsk0-KlV5`qG@R7y@(2Lu>k_YubJeLO8S7HJ_Ox5&jN&w z+Z#*9MhspjD&4%p*P;z(Dp*IVE4n9loAoszvX!1mW_7o{AlrJL+9fB+@@m9e_Clma ze46_LGtxY;cTV_V5}m6jf%7OO4k1t}ru{Z%nND*2DGN9Kr0x*wZIw=X@@<0R zN{?ZlcGmh2R^0AfuS8#yH%z`ML$#zXJ+Lq%ED2YA!nMsao*}YgGtMPY^E%oUg@yr| z34{2jMx>^vvT!qMn^z`p_dcPWQVwB6KMJzM6h8O}&p(~D=Xe6qkd!L=cfeKPditF= zy{gML_n_o}p8!4A7>-@FMcRvPJ=4lY_|H3p-LSA4f<=W!vfb|ybeNHnyEpJl4H)(b;eUl~+IdVdpReE-x~juVzh@uo!8fg#(^wR}<>WrnPuiLld#eCPQT> zAC!ohvQy2um6fOAi#Jdorm4C4-^Rlau(NqOD_fY&HH*G#=D-x}Ornw`fMzXpx=V5~ z$LKGmBh5??j%H~-uxX^UR4QUrEO`~N_n(bK$vVa$Aqqg?w0wGQ1%Pad*KfW^NJIOx z?k00BS&Uw_y8m5@ShN6Yu=p53Ixr+ujGU@q%L1yf@;NAbEQa9M2_2mDrMiTHI7K)@ z1>rn`S3nf}^xqU+FlslImuaUdG_@Pt;CK&5WLj;i0Y>Te`Mr79nqFbq)Y8i!{bEH9 z)&&p^JSgzXi7=slP5^B(dyQ(ifEje@gf;e<*aAgWYB2$vw(ZQku8WO4qrBk-yC@~? zS=I-`+4n(BP>kOLmf>-*FJi^%veV&5k{`&b(V})jmx%UXAr>++QmR*xlsZz`qA}`wWb{sY z^tdHk^EZN7a#HO|wsN*&$ibAH=*}7n%j?ZUwTi3}DX^0V2D9o=Pk|MuV4`^e{KCF$ zigG8z@du8Nn_C#4)ceLLBDQC4a!yIw7N!_p-esmJ_fE+*_j}#k3Gr}QD7+1py0m2l zq6Jv8W|%(B-rs$*XQ>EAZQaG~)4M-6Y9XS8T|YiYauqmlT6^!MTK>U)#}`!R$T&~} zec=iIR>E$KLafu&%EX5Crs>q6^J)OO2vc~-;tCBG(w|m;v8hOY{hn1|HV>B6**Ww( zSyuhmUKjT9&Bg}=KPPbV#E=*4x-?4tM1f4b9`elQ4$7r1qSj`^3?!`%({I8!zT2YX zn%(56rNq9wK`S0s@5x4jA1;gU1U_Ie?vsB&iX^PnEX{wi-dFIJxm(@gB)&q+SAzmq zg?)gyI7i;4VPrv3?sE|gKIk+#jF|pXgMt2w;;i z#{jXAO9LLDk)PO41xo#}JMOoT(hp=}5?mZ9QIt~S*d+p;IJ+52uxuo^SIR8K5q%0j zK24*x-ziI)7XiwW*J`&>LNtq)5IGxqAmpiH?(SdhVf1%;MyEBs-ziA1=-Y_xo#;*) z;5V{tKe=Z#aw}TuWqf{-3C6GB&Yzro3cOHM?#5RMgYvjY*PnhBfY;?Qb(~Ur_mp>( z@=~=Lz#Sj#vZTeCZDZ~P%cchnU{u{4J)W^DSJ8M4xRYTSTvt9fdsWfALgli%pgasz zP}Di%iU<=GRG;(?b!6;%1r!*J3`Q6JJ4?~E)(j}korK8l0d|1?RbIaczlCK$q(Oqr zuxAr;*R$X)2i79WzaboUdKowiuK_=H=WC_%1pO?}-@#6V~G z;nIF&i*}i9g2!c-z~p*bVWthJXo}O>ww*B7gsYRV=GnYs6rsNv^xkfiW5-590MIG| zsc%M^eEZj(_smFM_9GWpGL{YA^&Z5YEZ+V}SL7XcXjU|feIcvh=xy~rC0xbMnKiAO zWqzN!)|!_a9DcB+_jZqpLjCnDFx3EuINrgr7GW~-L;a!vvU*|3T4SqhD#KR1M-v?# z$;(pJSwft-un;hv2{f^l_bEe90pY>4pBz{NfEOEtK+i2FZmAB zOZenm7_mX^1)-%GxcF6m3K6D*V`M6(_mL3kSHg$uFY%$f`8ion_>;E+I?9lG{* z0-#C%ouv^O^}0@Ges7FeGHs&u)^)@YX$+)=i+3#NdyNg!s>lK4@S~ynSPe#k>R|+I zVF8rb{7~cf=c7O8?dL0NlK_LehH*zOkqAU_%MExWSdk@N1hVr0O~_e?glpvaN``ze zeaXQlU{nFn9XRKF9|J3|tu2Q2Ab|nC55EWB_`F138c$N=Q6`*y1Aqb@=6F9XO>10>g|Qs4 z&=&2~83y+Q*=G`E`hdftyBXMq1R+Gns=V8jxz6UEHMI3L)(9K)B?JE_P^CP5gyg_D zR>cilI@58cn00lZyW?X)W_POZcM$S}2T!C*0lF_0zBDuR821La@)eky{K;yMN31~W zBGG6=yCEW#bhcY1BCAt3LRVlLO~%1)IS?Dj$xp(qAjf3az1{ah%nI=yI>IE9Y)@Ia z1^&Rk>HS27W&aF>y;BfeyO+#q-F}xle?q4kc0O8EdoRom3 znHMHmrRY>mbraO+X~nn_IH;H7Z&lNgWEBh$IvKI&bqTp0Q$t^5<=X*;6;ZnqG9a1_ zFZ0lLb8%wf_*B`=0f?*@*(D5_7!<^I2%y>z=8jLujxXo+c(WEc)b5LMs@XJP_|SBH?b<-~_MJqZYiO_<^lNx{)fgQWf6c4+a?-*FZ zv=;s27vU34{yUERcqPfuNS>=f^l-xP5}U)^RSEZ`V-oL+D-z0eQ5K!p`sj7hGN!F;5jMX54k;VQ1@SM zs;~~V%a)}d??NNL!#3Pz)C@97BX~4+%mNfzj`d;H9hM^uJ8dV;D%%$0>fwhJ5_+@Y zfVYjAe`_r+C%{axMr^`h@VAgq$wpjQRLt>G2FYHJiB4?WzWVN|>jZ1rfi(Zy%t{@Q zC;XeZOzjX;cPZR0Rm=(t?s35{Mf`&a8OnNWYlUz;0HjHdK@Q^SeHfP zV6J33I?9U6J{gM4x>2Bo%_+i33ZZ* z18x_Q=>V3O{e3v?vP=%FiHkTAAug_%FXIE ze-M;882TJ;59rZSy?)x5A3DQL)Xm&PVCQ-j`&J-LtZ@R{k%!y2$Muc^z>gYd91*GFJ`(dSaLKO`nsx~QHiC60d$?B}g!rtR-KexF8Lt5yH@f)6kGT8OIgf|=- zIc?0D;Xo}J7|<(HYWmf-0pwc;J>fZWCkZ27^!}wATiBf^)2zm@Z+|t^nLS_69Ewwk z5dOg}%>Q)pv?4!H>?9fMn3d7h7z={~u>FROvL!h}r@q*Jn3|t+4-G&!-wW8vron5? zz&^$q{uB0;1Z}c%;RZJ${`oS#K3b!@0yZ=`%S%j)qHEYw5z)F0D$egB2}jLM(X#r0 z-KP5#f(YI4puR@^G<(C`IVUV8@tP9F1swwlB50rpji$RuXnZW zS*AoTw$`Xbf)p8Z%yn~LO{He#SNcr>oD;R&slTl)EosE+cTv=zYKPi;vNoOd10a&G zmA7N6wm-6hCC6sHFTW#{JJ5tbn$kxuQ@viX4HBH2SqxoG2mG7>@o;e|5b06keI9rV zXSTzadj8+k2^Y~su9jiAa&z$mV*G8KZqVb@RbB82*W2J(g55(rFVuiw3JkSLEogC9 z5nqrSf8Wlv+sJljspU*X1Y>o;88M!o5$Q=FQVS-+te_x<%#!Ri6mXQ&Vh zw*Bv}yM0IS75R+CK3TSi?MQO58-|)EdH|Mkx|TkkOsGkUdCpF`9RA~w=a zpZxOR5;hvemV=`W`}d}9GW8ph6scdsm(z-^DFKV85Hn0GzhPk`+<&(C1GbS%SGJ1x zgF>-bXH$=KPaYYbWj%hii5$-|T|UBw4phPl6i3h`f+yB{9+>%}TapsdX!2>y~2#8i}YoTYP(oQPnms+79!Z=(*olU#CTixEuY&5L*3HkcxwO6Z=P1t$XgN6 z`^yY_ z53~+vgL zDF%n*|A}qP6E4(>d*42X;S?B#ewovBp02=Uko)Fj&A{B zyO!sunlsq++5$1=aggG#AbKLLXCuVkp7^R(g4pazc{->Ig0*|Az@=lAWp3k4O z1WeE}ISRktH+hXTn-!@^s2Fb1zks!aEX<%U!D=Vn)dufj?Y|Y`j%X}9PrqUte6tJ9 zp`!8_gTbt&p#cN*$L{kpI-F&Gr$n|?mZ7Ys7b!lkqEIE<;xq1MO8;Wtf9NtrFXYA~ zAGm{wZDIi$=3XCGSmRwv40^>qT(`P3Rp2_YfqfKb?v=MTR{Q|0IlbyT!9Br^eA$1jjh>i(aPY?wA7Mr9}0N$T`AaMacZ*D-iI zq|Q-8C&vNw+wG&z5X&KnuA4K)E$8kXd4Wp#_Kz`PjK=xE^E~zL&cNVEqsfrUp(g|M zmvySpgIkGbFTt-UZgU1YV;-a*DlRXa@NpWlADFKiMFXYX=D5vSIwzdQ@1@UB%j7#s z8rL`Y05Z#5DK}bX{Vld<+P{QU@nXOf`DoLSQT5FQ&f?jnEQ)58vK&BrL%U3^yg ztY=-5{jFGTYQCcVlqaVT_w0_u+vRGL%H1e4UnEpniI5}{fwbi^$_!@ag3+72F+Ovq z#od&3e|G zz_u_fXD)yOo8Lk#tX~-qw4~pLU0-Z)0{g;t$+?F>ES|QWFQn@CkB7M6sgQ=Jfvp;| z)~(XfV(h=W70+jC?K~N(%bZSy!RjbQT%8|96*)DF{vVdS@O_n?>A1JL;B5{clqX1k z%6l;z%5?Um6(9`K^ZFS0n7wa=5Xq4g+pO7go&)W&04Zy&hISD>>gxaR@iI_$x zi+aD{?W+}6RAtowkI+#K{2FDPv1hMnwY-PZx>4QE91Ux?@0$I}iQN2t;Yg+74{#)_ zMs!#0V|9jqF)-Z=_-W9odIJ zx8Ba>+77me*Lv=`Srm4hQ2lLHO6JDJt@_hsnFm!8y0bVB`T(*BA~UHyfSwyTIdsq_ z($~0|fEaNb<|9m7di$mHc;3UoF_;71Y>iY4(xIReI<2+b7490Rw8Qv94ih4kd?{xo zn!W0|_fKH@e}`$%GR9&>WVA6|0W%%Nx5DeWZL)n1cQkV8p~C!T1twQSZRayG95u%> zyBR<;@X0c2K@MndjY#FL3psz4F^(t;l@{Xd$$72dYLW;$MklwN9nj&Z^Zidfh>@EQ z!dHG2E;x}cJ!%xZ@AH@b+v+%5{c4f)!?xoDax-c!9OqUI(6oBKj|VK8o6Yts2F&{c z%EV1S*F(FvwVBXuZ`G%joL75C2V<);7OR-8`?XkQ)k$jm8ZVVNtv7GuXg>1w8v;+D zgku5T9_kH-^3V1ZI@CEbLIzs8Ih-T2N;V{kZ_{GP>T%2_rbu{Ryc6|z%-9J^lqev^7`qhGna0RAh-m zHdQq+-a`5#%V0w=JqqKVy4|LX>Z|>Q4F5`w7o^|B{1XVpHv2e#-OBLnyfR7m$xS`w z{TU*tp|i0q3Pumf#Hu%VxtUPu_@)q{gg*Ruy_Wa^c0K#~brc7_ulA>1_R0hF(sL!) zxxnY4R^30gXL`pM++s~>(EVg? zmi}XaW3pTSJYPKE?m%T=$m%;#yJj5`ym+Fawguyf9-S_qr)Xc<1XLMX(Y(mG| z>fcK5CekrbbT=2O!<1q+fO+6Y)as3rgYM9@b@JG0#SGX=w3an%DQsJDL=qV8m=2Q{ zk>kbV41yHsaXQn}22e~VOT``6g38IW^zhszpNK>yibz;;2(czTuN`8AHLk#n*My_C zQ-fQ7LNLo!9Q@Q`k%vi`Ofha5GR4iShm?+?JVz)a|D0%H1=^0Qh5Kmp3DK4bU%j|p z5kY0zsZTh%J*`qF`R_3&6-{;8Up3BSGYF6V@n1DqeF072G_aIjR}_bi``jO|1Qe)O zqD8XkKv!E>R-`!44q550wFrWoB-_YoVPF;LzM%J*R0fGwMjZ-_`Ku(Y+Iy0&YmxS} zbvC@a$EtCtYq--z1b=c8aI2YREPw_|bf{gAIflo_^Vd2+CeJr)_?1%zi9uHFxL#S4 zh^|r{Gohqch^!sp>?-AE=m#7s_sS3)+fS58pPcLG&CkT4`I5-^|7*MFXuwjX8}VIaJPmyUb>YfjIOpY{`L}s$_}> zza)D2_JiJ6yz(PT@Ekd;w2z>vJy)D0Y}p-%f5Q_F1y;_IlnjEy4NTQo31IbxXI0WI z{R@z3wHX$#mAg3;y#^2a(;TD$zBd@_V)C!=nfwuWX_o3_`+k4;^)FTSeDmT~N=xAr zo=JaN+^?T|KRJDi!RCXeu|-z0DqO!X94@`~0R$IT5}YsUPp)ho71-Akn>R+fbpszL zsvau~q5#X9+qj*Ujj&OpnxEP(wjDS3cAXZHP@3{$nxY0JeJgE+CYnE14-fSEQ5!Md zwEpN36!@BafqUUUe8_!mzrx_uNn1jYt2#a~T+ypn}gn_IQ1Y*7<+!FO;h zk^4_R`2uAC#_})n?s2v)4{lz4@xC5t?nKwOHr*d{ufWymB{*=3Y$SIwuz1Z#TR*H?+VQwT5e%|l{P{RzG1KL0Gq2V}xVWXKMD#EZ zc{Y~X%Gc(O+Kdw+JM0Vb8#j7WKiP=I41y_^Hj!93^mITW9pgw!r8A z;mm|yWY%s2AifxN8wQ-kpeIwyBjn}x8;?%&2u-3lsM^ahu=g8p8BX-qw#i?ij4@v( zYD?*mP@S_tlF&A-?G8|WUe0mFHU^*>8Lx;n3}H@{z_>CEi~*hbyk!B9q%IKUTW=>y zh7H7s>V$kfxK6QmaW?N3&;WPn{0drn+b8jA(i0{ns~H*E4{d+1sg^@T9br7;p=6X;a;!3PIH^OVcAAw_|8=rewutc zH>Bh3-oDMVPSXFObkAhV6NsohVA2w7dIi@{dRG!v-kjRMTukoC2cN(4hIdKnhIahgvdg z0}TP7uM;6mGGO#S-d(j;Vmh-*H_80Hzi&UK1zq0Su_xa6qSbf|?~2pP?fJ)TmhG0_ z%I|+&P3JECVcl~7b#>5@^amq=tiDWgVatG038ke;jT^>8(8g_cQ)1-d3rd=kZLa0H zGQZUeiuw)(&Wc& z*us5oe(EKSNn>-?0Jn2xt$Dv#;JBo3iFB{B`;#-&R@b*{{>zjy1W#DRn%`x;Ke)T3 zI>!kz<*@A^$uO$1&Fg50komz`Z;dc%A$sNNqw3t}XQc7xvkV!&z4{L}_%0VXTzDZL zmdqYo{NMKlg)XZ`w(9mNE_6$cPMiSdp(PKKwN)x56QU<%5Ew#dKWaKElmR$moq9_I z~;mhR1+(4oXw0-cUai-MxNb8TcJ-b!RYpd&! z;xE+CTDS({rv6ZPK5f|~X1t1+aHr4(SijPEU^LueahxR|;8$~30tf@P*+#KHFp5o^FVoOlfRp78XvuEK>nzD|(9=I_jd3d*FMA6PaQ z`3ZIa{mQ0@cg4H>+_C7@`d{`heI2?ypmB6G0a|B2Hn+e1SygMl$7MM^(h@YV5H$v5 z!)S?;lpQw%=h^&wyA{;Nl|gTdUo{Je{oVx{PNV5EsW*-$U7G_B-b|2`c&>8A_?Sv= z&wv~F)qs=;yD45v$qQAwj+cNaa?zEbx=uU)F+G^aa=p3e56VYCCzjBokos=2+1XP) zD~zP&33YhH*iU=x%ZTbk$!swbcu{hXixO(OOsaw%&+TpS(Fh1YD0chuX%+#Wff#5z z1Dgj12G$o9wMqD+u831fa?9aAbqX!CVj+}LRjJL2Yns!&2H67HkA1j9HUWIL-d`Wp z;Lo8R@)qfGK-`PpX|`d%d!+ZUe2JC~Swb33_YWA{%fAKEuo3T(+4Vk%%f5v>Ex_A` zdZV{4tjfd4Y>2CUCN&gRH=AXYljU1C!6*7XOUIV3M zNo{c+MtvypSzQNJ6Cjy+!cQt9sx=-xGhFO0n97}2;`KJhYpTCCNp};}vTH1vvGwl- zzTY>T?XDTmowheGgrlS`_opveZPROYGdpU3bq+UUeLC}Se0?qVCp^t|jG}vZav7e+ zU7`gMU0&O!7D*|NZZDvh-{UdRj&74UQ zADO=r8IM8Xj~w^7XEegcB@!USHB%cII>>Zx8T+)j9PY5aoRNOPrZ`mX(P)iwNQ z;Y~$-I!d9YY=8#IrupR`0iF2IZPWlEY|Bh@zhVaBbTYhWEFwNBPULBkQNSEK9T8cI z;3|o;-RWXy$OjxhB+({}bD{?d2iZAx`h)udfnhg#K3<;Bhk&EEiEUp4+cE$>_~p?L zgcpNVDzbzE&)^JT<-sUwC}qu4(~MV6VX7ffB*bm^kkBQ{tFMg`@J4c(@a0r4WHRf4 zN!_w2Ry0oiwSqcYH?uYSDL4UH@Wp8D2cW{z-=AO3QZG* z!4pttn(T05%k=tTAPLf5mH@;@*bTMzHeM2_=+TY<4|U+D2h27h#(dj%@?A6Vk@8ce z5Kmh&yXO0Ja%N0ODsqGXW#OMy_M@n4f#LhSk;W?-UG(@5lAcU~K#C9`%&m-UdOPIL zfSYHo$e}?(8$lK_uQED*E;DYdWthRy?22!9irBoi&0#kN?I`?+3QDOAJ`!3E@I@j0%0+FOz1c`wcIAtN{ zFGwWlSNQPV3?9w%&unv-BLv8KB|Jx=IHbxhlP*eE$-dD*+N3>I=m z?H^LR4mjOo!ld;pL@v&LN>^wA=Xb?khG0Af{(~(I{&QVnH+44x$?~o@rfbFZQ!gN> z_B`v!-~_fjrfD zM1SusNwr(C-3bvuXMaof1MuuPJ`jbATmUT~N3*%!(Y3><(#sJ3{(pg5qdw*1$H2hz zp(&8r))67P9e?hnsb@f`S5YhMH3%Uf@nZz{Sh3^Ix$LV9 zbQo%}F0xcOb7;242INapoP-y&8D(ynd;Ho=ftN{CpPfNeVn8uLcom@pX(=u09M>_xkA${6^_=F;fJ6B)%gcm`vM2q>hljw@dgF< za1x6^vvENoQj5T-r{fZVZ-iS1dE}m|{)LS+rPwp}@DG_$Tfdwg{^D|iT9J9^oQO`5 zsT_VpuT>&KE4&2SkdC!a2hvm44GRFGdVi_<##^HHjIi=;cDY(oYiGL@bV-EWNYZ!5 zOTF~WuyPi75q+nKuAWwjr#DGWfa+X^2uxkcv@lIQx7-ZAl;Q-kez~&$i||;litET8 z_wX>cpY6)@E=_%*ti8|569juCy`C&magM7Zj&MKVRsRC|kgfKZ{dCK9hVK47ddr*r zW6hgOzglmny_%PT;I0Hcd!$=+3*v@(k`zT% znntG(O+1{bv$J;Q5Ik!Te>#&5+N8Gk$N$LE>q`&QlIRMeOFOOI{@CasxaChypi zxLnq#&E%Q0svZT5Vfa1E+%-88hqN+{V;rH}8Y`~D6}XQ*9;(E(0^U+`T$A*2)K z5y?tx8X`s=pikZd0b}Woqp8G7b-(1*{mgrfrivRqEVR@dw`OJEA`d*%j*LA1vcu{R<&ypx58e#q?{ z*`!${xf;$yI(LeN&58<*8gdw2uIjUCBQv3!n>a zD~^Yj|KsSa!=m`!Httsx6jnlVX#pvh?hsT;LK>uN7nYRn`T+t0yL6{?cS{K?9V^}4 z-Cgha^3Tki9rj``;LJJCbKjraeAqIrh4Rdpa#QgF6jUzdnZR?Qr0`H@hL!ChHk)_l zI`hEs=(Z4*bEkB->?cn7oKYt)ud@yY?UwErntjTse)mFy=6%cafqaXohaOE(iC|oU zD$*~m_@u+CR2l!A$&e1`!Y7+{M`@wk9lXuv!Sj6a_56fr-BW8UeenPuoW3Y`?dGA# z1ozYgA)TL{DITSLS*ixnaW#I!+MA`pf42JIm8B>69sH+a% z?^!dvyoPUub|A2E5)_h}<*w44!Y>gu83PAOOHWK1=9<7Iy-(k3caH3TIfT^ z{KeS4bi+(Q4n{uR-4kmBLhi|uaRdi_q6T--w}8p8M_JB~W&C-0NdZC9bBQ-d=b=I} z42jHeXLdxP8;`QK=^e?4)MMfciE4y*;=$<>)J{-hfUf;_R8$O)V!S03a4@}duf9{VVfN&d1+G) z6;A*NJ9V2XJ`U%$nfn&8C~M4>zE_s7Zsm+J^u5E+$L)+}U#>+smzK zdzJIR%;bDn@BGM}V@K4}{M7$cG8SrA(S4iW&4-H#MKm~~Sp~;K{a%r^Qr+n`G@lkI zOMQOt`r7qCHdYNtKW5GeV51|aq&{Si4Kan!v6=j4(w+nG&=_L<{xNBV%rd0x{p~RR zC9RAat>lRwW76dn&#DydVRY8-BAzKW%rxGIM}DazFm_RG9k|~_1e$aKQvUv#wsp<@Z{1*tP}Nz@j7CaF&>(RJirSN159-du;l7>@3SLD6c9Qt=%In*i2#sORt`0eaxeGVV3eD+8prP@_+|nrk6E$v1Po@w|Uo>qi0QEsL>A77I<)wYm`rbz~&I6m&n_S_5PBA%} zk>xGmT4M(YS0fu$nK5{;^{T6-FBaI4lU?$LON9>^%@r3cZ=7dxF|3MlyvPta-g*0j zb?52%@5J=n3_!58d0RkOb-p}s-5L%(mM0bqX!kOd#2tmL8_j(k7SGfcYA_4oK5)`A zIm*@Lht07ucLTTjbhXSvr9}|dbmX<#Tx1s-lF(xjqz2r``K^iyiSLh)BDrW| z0pDx^mGN><$@?P$T|u`LVkz~cymyongTIJ)p#_>!RG8&>*4wPbW@$i-Hba(5(%gnw z!(^mIR12k!Ja}Ubxh236=WOS(wzKJrS$*4kuR%6??(COUQ7SqZfuCq$QdjcOhu|saC0!Te?9J zdvq9A#r9>T)VSy-uBZ~nte~p%iG$JTSMZ>9O9D$S9kC141qONQp2`;{Gt$9Ru4*bR zSW4tSAv%?$VkdEwe?=c zUN4d$t>F1I#nCSoZd@x_6C)i_$}VFzS+l{t{S{n&l6r26fMZrew#(VwoB9F`SUI<6 zlc2#byyJ&{%y`Mp97Qo3vHb9QCSitsNw~Pdywovn&PJ&-ydPz!x?kztz5Mj?! zmm77Qsv`Po3mV@t!>+9$kdA5Ht)(c}^;>%Cv}etKzgYj9jVe3>-aY!iFMThEev^n? zR1Q^7VliF;d3o$zzn_VB`55d;cCy!pSBiz{Pt2@Oh+P<;H@Jzu5|jo@VD1O|-C1)V z47WYM7Sgn6LW)E@xnMm%zVfKq?sAYT0f2tVJ*@BXq2XlZrq-UzQqTc{)!H;Vaq9et zRX(5MlNU>7oCdR6n{ws90e&Fzw1ywfY0xdmLDD+d2u4hbg@4s=rbJA#oQ4_Xayhor zWGjBayr4l{`yfuOlJ<4^7p3?^6HwP;@-#CIz{{(YdS(K1H~Bi^j;+8Q&6LQb^n9B=)F+vao+rF)K~dX%nG2D&$Hwjh&ppE! z6pj+3r+zVQ!#x7J^eUW{vbrt#F&*3x>yViGu-$M(0+lXIG~C91%sE%9i8bPhH2B@Z z1-6i0x4TMmZQ5Z^)>gdv{XllcX|}*kspm$o((B`pi9pe7p182HWa5Bnw#KDcVQGv3H~1-|LJ11>;=%t3L`hnas>;_g ztOM$C={1_zFywRpwmMNCtL4BM36&uAw;rq+V`;XL#qAF`ZryNv!gQM-K9 zHLPwM0zf^pLsgM0LgR`l^VZ2G$5IZwRh4|1U1ndWmn-tV#t z+}2c`=A|S;oKq7ju~z59zuyegoT>9{q@8MPOqrxqgpKG(B{&=F4qw#vm}{}tbU?#Z zEy1mO;|)N<14WuRg1e zu*j_=r0?k_@;mEiaUg5ikIZl!`_OOu{`WA(X%^{x9%DHl!xp7(og29+_3C5$o#~(P zm)%! z#@ie>f`%zx{r!Hj9)O)W$<>OtZ9B6!ar%aqQAC#2aH^iG% zmQ_}#FD9;d3#oPW4g{v1i^^U?7{#Wv(WlH}NK%x2w#25GPjNgzCWI3PC7cNaPz{QO zDwP`Gy6|plWdt6K*=Nga0+T@LkRALzuEo0P^#`-W*bAh4dJ^xPp~*3$e~kF=P2W)&+S^W zKSh9!DL`&0JmV?KFcUdLmT!#os5>f8xsAA$`KpWK`QICmH|58}I)8fRv09=!23LRD z<7T~1Jh=s^DNNcgH-H}QWz`Q$C(PRx2&-c3La6&(8)i_{Jx@bRZ*;XF{lteaTnW>w!`zzV{^7QI1 zmEP7$gS?;C@q>)v5Tx?76!v!d|9C&O)%6b;3%>*I2w>GHR+6SM1Huwo<1B)UR%+{@ zj|N!NS2%60o)P3yk=xA6Ut6U-+%A%rYRZ1(O6U9NT|ekBl(HKrN`UPW)ci4@oc8ce`o&W8A#Kl+3RPB@y*3 zQ1P%oiT~&yP3F|z7F3-9x%Jy)vq}`06tqn@{Mu8PxBwb;;)zUS0L_bh+lWj1^}|a8 z2xKI5%7*d1qbOcr3=dfjDbPtAPR!TO9ayxzSA3qf zTp0e1gbDgnTM5k7>e~h$!ZnVrPs{iB7+N{^)2DaPZ1Httb?e#Toz*&0w<9Iw(V;m} zxBCiRoEcJU_m2IUObWGQbqgPOU9#US)1Q4&>U1EBqx4*9m~$Asqmfh!Y{T$fi?#ln zzQyN(R?q;^l8FT8_`Q{S(s5Q*TH)389x`8?h>ukMw+5>m3#}*j(BQ{FZcnJLS{Mf61xz0amtNP0x9bh52C_S4~o zfj4jYp%o&bn?29qv^XlQo%mkQ{mlC*ix9xdql%M?p69mS%}FE25J(9=1Mh0l2>+Su zJQB1hL3h+c1W?BoBf*1Y;eD*$f)oLjFX&tm&mx~j#HhyGYV-3@Gj-DKI{*^No&TY= z1W{CnLKDHZncpy>$w27yP4KBmPxD&k*r1({AylZd%l}ja;aJA@z=qhiTD)AB+#4Z` zv8a#kaxmerOeAG1Ay&G{r2WO*J7mIl`g%I@Y1K{YsBG5SgOfXZ^;}Y$Nng&fk8vtU1Kfx? z$?6lK{=ubz(oi$g#Nd==zYES)+uMcyW%nraFQ+R)bm*|I2W@P0EbiWo)dPUlgi)?N zD6frOKuOcTPeOK|RG&yL%nVj@f}AMJd+sv_*hF+2$lMwc{2!s*CvH+R5>*TJW}v-H zW{;tZV$$`R!Xf6a4|1gA2>^C>>C2e_4?`!8Qil~`THn&M=^G#xaswLm~+2Oez+ycbt1iATMeu({3X}42U%U2 zR*w@_ViXrm(a9BykG=t})ja=HIWzV}m?J{8Uk0SfhKlmoO6PH?=*!srt%BeGX@G0L zYuN4ggGX!BU}r?YZeDBXD;2@<)`#3PZjOtFK=pXHFjC&y_M=qBVYM zHDO<>m|XH%k)~&k4VyLgS3+{!zN=ObxZW_V|K6QZslQXLAV=AgCMiu^bSS^>?`dud z2+mx(>~nm}uR+6rs`me&jH)kZX)W2Y7y6qBCyn9-$&BzDBpF zN_WHzmbXIKgpHuW^$U zP9gvlg6x~~I$Nczm?G8{>Tb2Sv(-)Kvd{6nVmGQHK&v-gqbf;;=%I9$3HB@IK|a~0 zl8o)_SQ)b_DmHGa`E|qz58Re?LowccxLH3@L~0Fw;Xo^{()ZE;K15ZhbR_I}(9@u_ z5FDF9=bUa04@d*DMF}WXGrwNlN>;*)5(3_bA#RDd7eNd`k{P>GH$u0QKPO4!CZ@?Q zBFzKIkRS2bMkI2@oJVyz=`%rL#-6Sy zA;^hM%jyU734{Uqsr21T<{X#D2e&$o- z6R|%B+TC=X-gb;xV8&l-$ZQ7p zIUA_vr|dB*Faf7g@mk@>`yM$R$-(uw@`K)7a}U0|eL7sw(^CjGIuv(Xt8n59ng$snMEcp$Il_Ohzn+ z8}_}NKu02fFt%E-oh3Z}7xJ z^#T;2HwQ9&n@Ud@z*TXzIJ%r(+0>ZUw0?tfH- z=d!T6K8@s&pBqG`;&KpQT$6@o=u=E_rMl&0IHZ{(uqjbWY|bz~Ed#>N(}?z(vGlrb zzK00G3>}x5?9ep7pBQuxVNZ)GU|jLN^kBRSexpz>yaN`CV-b0^#5iD`)+yhvLH_#% zq5G#l{_atJ#?&REZ%o?nzFCU-zeX%SGw1&APPgE+Ngc5Jyfsb7uQXbK9g&@JEB(;o zEYDuTYz^)qq$3#!8_NfPssAOv_-Kbo_!DV^S6xp6vtR9tLuf<{?jN#y+M^}83m2mV$kH)!s9+2!qD5CTysB=r{0PS!I2qs0Kk;r#QAPQ)ZN={PH-r#mwm%kxK@3e1{1dh zZ2jBWuTuUXO_8l%kffSQY|qJ38@8+mfPXI;f3XV&ymGtk>p~MbVNx84Zy|fhc950( z#uqLswmmxd&3KLfO0s#K8~ISc+HzV3SOGg1%ks-iC7 z;Ef?A9}=ipjsDIYm#9{xJzTW?&*wCav%5dt*uAgRk`7}Ms*T>g!KCD{Af$JmP;>f} zj>rs;wjGCo>S|x7HbA=}**3GM1lJG9-x{x{dpi4t)G_ey2Nx zG7@nKwU&e{Z)zt_4tbGL5C3>|EleZ|!u#wD9Yy$2i#SWHfM5^gn?q-1&+#ylGS+nu zYkN_=h`=cy{n^a!=pL-6v=zN4LBHY-S0F(z{Gee7VZgq)}+^H z&|LYSnD^HCM{(N`bc`>~{hf6FtyljozGv2#n+kvxJ<1OCHanm?ITT-TD2fGSSq5gL z*C9ZewO(a|-eyMhnA4olJ-u0s>{5Sb2y4=P#rQ9U%HgQE0S&@4Mo93s-h5PU)?Fo$ zX~yTvTK-kNU>mlGokM-c7x4}V?Y=GDDA%4zL4aj^9GPO>TMu&sekGT@eEgh<*4Tg+V} z!ux?eHGu%kPP8Tf^2VC;!8HY@+!Vq2NH)&+-c%36znib`ftt8 zP()BW%VUG1bA@ULe0>WangX94iDGn_-9p$ry50d_#{u>C%|5RVLivn`ChIxWN zJ7gkN-1r@OKAXb-dLBOC$p=2r)Ijj(=NX-ACUAOHn(9kzn~wX}j9`?b(e`^x%pQeT zZMVw$N-hbm-z#`kcQG%gDFhD~!*QC;RxK;I~ zwI+P#YttECfY}=IVw~^7G5Kf9;kH7U>D|O#^}3HhF<#)XmJ|T?PGb5XvE zn&1To@G$n!_k>`MFBzzsWPz-WJw~3xRO=nJ%${o(2R$lfq5JsSv@FUP_Pe`t z`F?_nGi2yb1mSUi>c4$n1&&wRsz(qD77f;2eX2$)A4R}u)TG~mS~!oEt>I>xlF$PC zL3IC=%K}+K(r)kWhf5Z$dX2^tqU9Te6saTR>&@r#5hnx61rU4W%v501aPCQ$x|z*h zdSVLKj}POp&!lj>?eVTRNO|5M6Xq3EqK*JY%;m^8+^%Nqf-g{k{OMg3@?J|30zmFF zpnE7S08c&wxd#A`R%u^4yG^tcz_$7E0<0HslO^)pfk3&B(uhi%KEyMz{x^hix+fh| zyZu5F%nnWZW_lm#I(!XxtDI`fwyeMrOK*)oHb`H8o@*fOGO!(;y5aQ{dY8xwV5QrR zLT!ai2Xy#?R#{JULb9&z1;%m z{VK#+%xFHh@b-55-F9@}yGt>3;}9AL(52bm0dgpb@#MfvIat-gbz1RzRP5RHisnX3 z#SYk@YymWQZ3Ww~RQR7Y!bV9!#Epkw00PjBoTiKR{Rz}r!#^z4?9l}IOy{n=$Z7fb zT^yjYbl=aSfvE&>MIm>t_7wi5b6Lg{mE%KJ%!Vr-Sy2TK9e)-~(?c_y%OFs`pVBT@ zQKT*jeeIEl1g&l@DqzxQCy_!6JjJ4+ICB9XjwK5fD?k1eKwE`*7hzBUWIP`E%RfLS zRjf1Y6F+9?W=rSY3kU8XY=va%7BPw)di@@rFm)qzo$L&sr#J2Y9OK`xb$xikl;rgv zHbi5p+9vwuXkgcjR;*eOQzS zMU~eI$diZYsq^>oP-j!7nKJXI>eu~86PvJtXpL44dsSt+4&3JJATiLZp4Wu^Q8$oI zvYzGDkP}lg=u%ppB_O0#hg!g*eZw5I0{>yHGG?P}y$f(%$+IFzCtV?Cz{ICyS7e(O z0~8s)0IqV3>)w&zHt&U|T}3Peioe%e_cw$qh`X*U|V5{yPr^XF_EdY0P zvv(lDZ}N^%^@wUzrpp0sq+f{K?OXM}Fn!w3b$exOi8dNlcjLGbV|m~focuK?-Z#aQ zCy)NUS5DzPzv}&H$_oCT>HfY}VizpRh{N-VsFO*s<1F0bDgkP#BzAc@uV^wcbfguc zMtAN>9Hv|2$r5Ii9_@f$a^j>7SsdgwHnPusYsdd6Z4K~85rsxB0Aw=t_#ez>;0lhq zH2x;<@PM@Zp`cPP=RGp;7fYaa+3Ks(G|9V0p6y+-hf@5Q9GkN8y|dMSt?* zHjFrZB;D%p)%KG*6R8Fupt8MBeo%e4A=Op|o*;PkWY3zBLg04!xv}c)pY@Z*1DB1E zI0{zJjYhXepXcR5wn1;rZGg$gE+g!~763k3Ur-0f+6ob+VJP`_IL>ggQK9PH1OhBh zt;yR!`I3bYCM4+9jdH3RC>VqCWT zb}d;Jl1bL-J|a4p29ob|WP)tXRuwFK`7;aw%ICW1!7m`b5JOu(kY$hzLQ*`|IMnsq z+#S@$fueNPgDkvSP5=liKGgK5{l9-;4>*x5NF)^=N?1Fg+NaXX-yH;pz#5EwsMy6o zwSDc)mF4}X!9Z;2WAnGV_oIx!LarQVKcCWUw3wIQ;BpFpsrw;X4l=s#Kr?0_1oF#m z_v>FN-?q6gGl$|usnOV|=9jDBfXe1`*{XIe9|OUZ?|`D0rz6Yv=Fhkh-iIvrfwvSt<5LptZASchvKPOS#}NYVLlZ2TK6sew3*h3m~T4R|7CgCByEx zn*Q|vx}s^?(}d2z|NHG0Pdm3`(@)cv6qWs4I8%w`k{jXlnv{IX8}kWgdc@Q9v);_# zZY8dD-f=f>2$!t|v0vfpnG^tYd<5a$G=R{@~)b!$&y!f5dAL5d(y; z+VH;{-&HDW4*}dqgioJ^BTfIMnNPX$`xD-QYy55pf1ZlT1}XM z5?Hl|mA;7?lAe2dWeb3Vm&@%~>-~4S^Q1Q+SP|#Ag%L6?-i}iW_Aw4_8DNgJ3X5QF zk`RH9!iwOqrA2=yK+#RY79$|qeID!*WlYnjrFC{0m<(|`=2H&uhNH}wc#TE7sCcak zI^6VHaR&IgdsnKLRb01LNrDyv-w>yM2o|$`Bi1R9J`9qyi4SJ;fAio$>{GP59P#si ziWVf^zrJB&7vQx#WhBE`-MDjEHhdxSDRV0K8D`9K|KLP0l|-1R*Gt`4fXDdGeE4mE z1q-&z?(#t{1)1+QI>Z@3n;jocpV|_+82fXnV@~$`J>}#}AJv!bt4!z-&2OsWq-4S5 zv;9h$bg<4iL{k5S>}FhML0f;f=g*(flax=$At_7sQU-`Z0`~*ogpOy=;?qy(dK!H! zT_5_&=nx4QEKRNSk7`Xo@=D)?Y-{ItYUh>f&wB>M|2w{vfSDPS>~<1*w+tEQ6x}*9 zjhPcOlEt+18gCp}Js)FNuZm_(1c>SbPdAA2$VPut0tv!XlVN8BW>!eMfESggL4ZY4 zorCiy^mSKrGETxM6t<_2CxF^5S^qn3X8bsy(q~`((L7?RvF<0Ohp++X&&fu>BoFzu ziz)4VK>1V|*S7lILSp%;F!!LXw-RSQrw@I7!1g!t_M@>xmafUa^Zx%^Mt=Gu?dm;H z0I)3%agHrN?R~@feWb_96uw<;?8E2o1t!}y4w5l)Tj-=1Wy?42s_wu~Xp?xFHSm2Z z&1FSiF#DCGad8!==+n%29U2rmsm+eE$1vj}w)Gj=5|G_+o=EpzjVUpqePDyh;0bQa z@1-13A}Bu)M!;E`A#exG_@cB!h(g%MbNeeX&rVDyl-|;*R6AIN8sVJ0eE5q z2DOvFxA#$zHS_(EAQLxQ#Z=q{pf0N;`fY*40z`8k%0BiVqgXk)ynu9oOAP+4_QV{@ zytIsE50dm0IOS9`Xi+LS&iksF{+_#&?82DHtP;gDmCzKALIIMYf~E;9;kUeVD`gP@ zCCnqoNGralygvf%ZoMm}2?`cY;?DRb zk(bbDvkS(uhJ|t}cns!zcw=fj6^u0*T?1G;{07nS+9hv2$438HP3LI=@kLm50EVxF<2q_) z{S=N{W;j=ns(m=ZTtu^c%ZZ7D&|?h?HS%MJx_v=|?>CNeo4Wa;~=M zxq11wf@)nq3q~&jzKmkurP`_0uNQ3j6&dbp&GJoT$)W>@jXL?qzY*^S?5^}_XhJ!F zM|_EUho#T%z^>TA(FEQ8N^Q_Sus-{F2;^jNw#miV8V4tkEbNQRav6oZAK<<&<;BII zc}z|(wBf?MeT4gXgPSK``c);n8YgqbqSST>5q^|n!)dJpCZM&WW9SX{G+B=^3%$f+ zGQN4cxa0M|$dGqmzm2dzlH9sS1AE-PO^v=nAfUx?`f4mGVYbo^g8MH;S2M=zCGf*h zdU?5v0XtL=NQ8o^xu;~#%^;O&G*``^uF3+1iJ%|q;%2dxrj}hsZ`q);@3NuK@|LuB zzit4%KCRKP&n%0&n0YhWRyWX>5!4OwU)CM#UjM`@>WR~y7o{{P?m4nvU$S%4uc0hv zqkKQXS|wBd7p^3Y03;0s4w6PAuCuzeQyOe;)cXX(DhO5S!qyfaR|Hp?Pj&8Z15y9?`)US>6({1)a_d?obk1|G$=9yXEk5y-x~=3_6KxIcQ*EjKC+W;{v?o0?S?y~a<8DJ{LyL8dmU|9_UK=YGy=e_(SQK#}S z1XrO2D*%rdX3+!hbY@HgjGNg8Z^U?vaaEuOJc;U!T~>1@Kv8t!tKSzGkC1Xyf2mC^V& zCgYhutF5^G!pkR7^*Kgwm;Y)IgAZ5U{1un(TLv6K%l>a-+>dSTn;70x-F+ZtjA#7= zh_OFetI~*sD;^2zI=7oolaWD-1l_3Ic&3uKdq~BX0%h}pKJf=JCb4d9fE2j(Q+G`M z9Y9&fbsU>Tay?<-|H`q zGjSJ(40g?x%V+Ufx8p3U7<;^by#OxRraRrp42iB{L5b_a5%#8%kNj~J@@e|%$2kyd z?H%hXIoCUA+)d)0-E8Y1{psm{p4AC=4?-CE%(4khC;`_a8G^22X_e@2M;2c$v-JC9 zFW44jO1Yh?U)km|r;VhEzBTD+uaHaNF_bm}PD0Fsd&z#xzL`%7<029$R64W$IHw7u zG}^HCyeHt_&R7aRClX-k2HKZ%gvN0<0}J9r0!cTBbqehHOHCC|mnw~|*81Ktyao22 zDb`W*6S40I8*ZxovMRbu$tg)qjDtRj)zR=TH^JAmpH_8KzoG*4q}lKt;I_RzpRiiRG>S7}v?b$zf|`5ON02}({u7i8mb4Y+e^PV`=LjY= z=wpfDN<7L}KzIh+>x?2(P!f#G6bg67g3D4{`!6c(F)I4&P53cm+!KUnH}dVVD#9YA zcHsw4a0zZY!7u)@tOMnuGAizuU=n=N*0xIJz|SI$uo?MmYe=tQZv`c>IR{oH;-Mn` zcqj8O<7BPa&08^R2jc4~gkMW3b|s1Q^It4lbHC)imJ>h@)O5NA0xtbS$ZJ)y5=fBC zxJG;1xo$!QN)$5Ay#}~D+47h?_wyi^C%>YVx;US#ejQIyb;GxQ@=!sZ$Ryd0`2ndo z`@}j>2{T8yocM@y>Pf*wO;Z+fLBr;5q9bNr)KT8k32kHD5#xStoZ6r8lJJn;c0=Qb zy(K;2JPMU7a}$Nzf>>{+pW?nWFnB8H1chy69WoI3%AI<~cUTc`Rv|Ng!*wWV*dlaRsh#0=&kA%PxAk_8K7I9O z99Sb>W0m{8ca+;$9y@*dNcS%@Y~klgO}5L4?y+Nye2*l2<#Kn{pysdYVZ?CS!8Z>o zf2f~btTr$&W~}JW1T6{e)*&>?hMMbkNOJlVDD8O;>-jYj%}51ih7y>OYar`!`Jh;I z+_#`C)|J(7g>E!0MXGF?xCUFL*_qA>(DO{)9dqkBM1q8hMj#mBS6S58cvb&%jY-34 zq3p88Lq2OOabe%A;#T!JP;J83;On|t5FdiT6FRem1049dp4@rAH^3-MArl|hcVG!N zIdidHsD!I#4=oO@wmkCVR5uiJttpd+E$wGf_BD`}p9X#jEmD9MaF1WHY*-=$@n$&> z+SFci1Un>3)(T<>sq^t`(~N{T>ct*9l<0@6TiDxdL`+mw@{MbO#Y(w&HBMaP@B`JN5)RHj#DRC;;sQ)s*PZ zs(ipflJ2_f-i)?ZWe3V$KpG*W8f)u53jl-i#mrJgUwr2e{h(+73Ur~o5OR-uQzQGG z-{bOwc{ZqU{{u(5!}m(D(bq`7f>t2V=Zh<57I}AOVzMtzRAFm;hF#DJ{o)GOeM?;XfkWy+y)~q3sc1FYAvz&IIN07kDKX&Q%x>IX zwyB}I6+9-?-w_4W?A%qv2g&rD{{Xg^nR>d5goK_q?~81MnBEAxF6B7!h`yYDD0of% zY_`$r!SmT`8ky}%>q7yI5OntH{TZSzFeKf z3gVrr(RayklGKTwL05C(^bvG&d!|v45o}Cn=^M*57j|kii>2<(ut)p|^c-}ItqjS` zu-*7Qqyv$4Y!J88uPWR}NvAfAu(i#udxqFE&7K; z_PVX-*End##!DhA*NZ9BIZpt7U$AVo**ExCkW>@p5XI~nvUxe^VmEjckU70hC1YU6=wy;iP22>f3ZA@WX&T;O+#9vwRfoJkn>&q`<=Sc{^ zTJ7AS>V$yKdc?q7;1z0RmZY#c_$r{bu}qcbkpxmNEdQtuHEL|p-V$FwVh(WCvM1=` zuW|_nA{auPiaddZOEAGCzeSb?(sPfS+tD#7i$UM?*1c)S&OcMa3qVIj(a5 z^ZhL+elGXLvi0QlJC3BHA8cyB=RK8c-iO;{=x_y%nx}@JuB=z=pOnTTKF*SE!^M^w z!HU@uJA0s+R-{5I23RyU)Hb~#!W!^c ztxfMdWB?yXqjM0{epG(Np_&0(mExO|)U2KaJLZ4(W~5LnT6Qi`N^SO~71tQM-dk6G z)i1h^sxxOw12j1&4}Nzg&@{Gl+nSgm)KEe2sGs9%>K>IM(?yAZvizRowe} zka?28e(~_;2g3A`WRRT&=tUYg_Z4`;MTA-6N#xE>5962kz93wQ%q!lTxYieOUk^i%yoEJPL3q?O$tq)w>p{?u6?TZPP@Os;z$T~Gh zrf|oN{kz#sh=>8KC*0oEs7gB?F5hLO#2DjYklLQEKr-PDq<*C0?iOqe_SYt3h-go2&UHtCN< z)mFzk(64#&PDchgtkDx+DJ?qj-7Z+w;@hX8FDTvlhyfXEsHVm3%3?>)Zdr*ChGDXm z^`tdD4L;gpwvGOAvW?b2u(&v$Lb1q%nMi%Sj5;NCJnm&rOc9w|a&E`zs9U*=D@YVQ z)3$O)>eJcor*jWNIPnMyMp8+q0v2;ST9NdmhXo64Q9i=s)wG+zC0(h$OpZ?AC|ns2 zXdYOcHvdef3RD~OMaohxfA{7Q%rVdU9dER5B-~>rrbsbqzax5Cm-^eQ_`|9Q#I@{{^R~|`1(@Ye>&aYOYX5Yu3{Vrh zH%jgjLB%@lyv+_WtTF=zPO;8FhK0b{K6E0R(n_RU{#NUbBc_=WqPIB}T&W{|`s*yR z?ljP}Zg)f=+Yt>o-dq%eYu*8Z)>-y_9WRK{$BfM$-f}!8sxI5WZ_TvghhHSRb9!&_ zPaJ`n}eGK7H%@z|Rln z5Y}1*;uO`AE|mi#k@{V9>|M(IRXvG-iuO2Y^Wn^qGpOp#>6qd-{(~}?sLkoN^FC=y zLon+7e$h7@$>H;#@-z*+=&`6YvUe#z>qqN@_(5^3!GAP(7hbm#u%@#4Lf}aCzKRn_9&q^uWb>lGrjt zd8cv&J#zR-hD%Vhci!GWLnjIJ-9wE@*M%u0GQJCJ59EtY1kY*jkFa-DG=c$d4t7^K z0U*cR127!-5&~sbu_#!#tVqji+(O4XuH3I3Z^9CjC#n@r6s7+@+_qr&|D_ zqS2FJZWr&H{KX|((c=Y;2;Fd6(d~#7Uhlf)4##`9-imzx)1X)A^VK(ta&sLT&C7E$ zf^h*h16CWQCsTnu0nZjddr+0&;kt%6rucjXsz=RsKNQ3=Zn@T$(P&C45DU=|5oW*u*#a<4npsc*Rmm`;Z@2QyAaG=1 z>5`QdR$mJ_8GpM?wunZ%SqOo40XF3&B zQR}8Gh+rPvLWTFH!u+KOB}M0blrc>KpSRSQSz7^vRQGTAD?QbY z?6En4r|YUbQ*WzVDcawL^+eCx;9cumY+>QSNE)vHsdBb5 z^+o(e;m3E(R9g7d>UeP?mRL)uQql{WNikpjv>gbtmsZGfEUs{|_E7z?uv+m<*LZ*G zZ0(~L=O8E376C{;op>Vri*by7k?~SP@=(-Xzfo>8tRHYu;YLl99-#89Vi&Ms&AxIYvG??v%lW zpIJsC&d62{?REG;lkU;(*MfSRw21&M%rU_^{Z)W7?n&tZS&1Wl`iM*{-Ti0#IT3dk z(1egTXE{+Z(XzB$^^Z4d06D=%xQcGvjLdqpTl%JAK0nZgynDU3y}O+snSBMTW0xDQ zE3C*8c~|iT)gW3(G28fsY1&|VYnlI56&s^2&9_m(Dqb|d>$g$PGNrs*PN{FByrGUm z{I0Wk^c)U$9?W9&N~e2dKhV5IsMs{>A81J823e0%bR*ml-lK$nz1=z#nL+DyS&G<; z=SAuYnG(9^VNkCM4zJ@M>RQCxC-*Al-1SsSeEk+0Vrej@RDUk3e(JzWeD&k?Xg-Mw zI*ND!I2mEMedmn&(6!RQ!R@VSk%y3qlIR*{U{LOqiWq(U3IiNQSM12I&?(r*ks)HL zpw3v_`xf@^#e+RwHJO(jMWYIaq126vJadu0f7ulAzPucU#-PKv8D-c<|0Be<>Xf>W zN`DozBtPs;u&4X-B>POO+n8iRPDLSlZB-J%LoMQ7$EPr+LgRgPpf~VKhh^NCT=nQ} zREIg`mq_aI=JrCrGs!4~QPWe70*luH4A-ov5Vm}&^sSItLg-!>F~Wiy1bU#ux6}#70XujBZd6Fp!WI7#rOo5~Fi8h}38i73osx7{k$_ zAcE4PyBqo4&-eBF>ppw#w%6V6eV%jP@AE$AC^DId1nk)6ntV#pKhl&4FqOo!{N~HF zg*39nCyoWPSTH8!d^ut-_=b7~Lx*lHeJv$NG5YT>F&R%q{^*Ey@uSc0e3}8MOg>fi zHM!R6@@*u$8u?Ohu65J8G-l|>I2;-kSYU+%q|LSbs}LD8EN(lW73(UUpPk7y`hsgW zAvfs+*FKTHO(55AZwGJxYkt0!IT?@Gs}yvYF27Xr4f^dtgoSsU3PadQOs?L`d>c!= zhH1F)vXh9u7yM?`EIn#<(sA8!v#)w3ds7&CC3bV7dj0z*_vTFXX1n9^@6B1m%?Z27 zmGno`FT>@__dlBI-m{W_>;-mrD4}~{VVgBJmd(XP>0zY%4Gwv1ML**vf}iRSDz|3T zU?;h!ukq7B2E?PrJ)XxzDaO3sm%Zm3fnie5LYZKW+#Ajku?pND7mT3GQr276b9&v1 zB3z#&-miDf%T?hU$cqz2K^097Bpn^!H3z}OvM4R{Ae>i#C!1Iux7KkQ0cSXhs-f4QGvw$H^|AKM`P^QqI7vHb%SFfhX*V9EbG z)-n??JAG6bZhKUctt28LRzji_Z2M0#c}%@P6C;HUD>0gw%42fyLSWqh1KNUnk(bhLzUM(qnB#eK}PSVg>veHFjqo5@8Qb+p31Y zLYLAuZ&BPZ_(b%MEJ>+{l&w(`hjL3X#p*_`QQKFciVU><`{&VyXwkcN`7RQmwLUK8 z?AuatNyINQqz9A3?JAqA{IFY{u{%jRlFLX7?BLsq|4ya`W7I^z#6X`bR+#D5O4kFb zgi%RF;#cUNw!Eq58(n%-cDpt1*U{lDGDR^&j-sIRsslXaz|yu|ZfM-5SchMp2^FAy zbhrfZXR-~=*f_j1H)ethF)p&{Jx#T0k{@c+*O2$l9gAc(GMq^;H;L!>Y<~1Z-_~GSy6#hyKsTr9T6m<|g;jBOFgZn{84CaL&W|_Yf+)gBPIw zZW!D>%7a`^y!a2_n>>>SxqGy%eU@NENr*N3?V!R3tIH(w*?O-;Uzz5CPg%EJu?=_Q z^0%Khai!Y|y{BUo@IveiSXdl&CPpJT!Q{W2j11)?UxQL$66mcjt3dx$csa8G?EMRGSx~nNxR$>j z@#a-aoPX^x%zmoOZLGK)LcI7jLBaor`u^MEFJ}$+rOR_(t58|oD*rsbvq_LWHEt-K zjkxL+EQ<-Q@5hy|y(7~3t zT1b4p{hUM<;(0yrEyrHLPyGVmCn9yjee1X93hS8J6H^G8am_tD zY#MtGJ!pf$vwS6K|B7-lu(ZMHy5}?y{ zIh}kY@U-hVb26Xw4g}?o+wDRz9O71d(y7>CA)Z5@7tE(l2n4D-DF2B2ckt3^4`y06 z)hM&%aqsWAXG}c;Vj!RN3SD6oX4dIFb+ynm2vn^NeAkyo@losRwWw26AKP4TZM{5={+$5Z0Tp9klUI-k8cI$KP7g`sq(?mC4~65tic=4|FE{9gLU42-cy z|3l6H$+ivs>droJ|FQTGl!$^`4c9L0gsk$+x)%1OxUBoY)9IE9D70;ox({mq^5!~- zqQY54nWg_4d8W`&{U{FtJ^z9|eJ2xVbD!nm*5{QYJvm!gT8jFDo}wV*O1DCSXN}p@ zKQujU2`UxeC+>Pp2hy1@dWlVhGH`l)Y^g#>4N?`vyIRQn1%YACd}`{!NBej+G#9&=h59`%qPnq<^ZZd#ms|0kW* zIFEUn(OG~H%QBBP^%WboaRBu!k9Z*Nb?2u>tvDZfI>au&NElMqkFY%ju<{aLoTf0Y z`q4Q}Xz^n}Nq zeP9Y*S(d^+n(p!VIt5HLrW`sKF`{M@)Z3#;hAfy6ccNX{a%Y&w!lOpskl48+D;H<~uea@p1S zC@8{QMaqOZhIsL_>>t;|vYNZ~JNdSdJ(ruU)8E@05n+~>pF^1D1jRrN^N(L`>qvmQ zD>!!t)P4KDaL(EubaQDus;DKwL}OBaKH`DWD(Wh|$ccpv+<`$@1fHAaP)2fnO!z~Z z{NHK2VHq(t0W8zM#tAj(Cw)7JQsD5_ z2W=IqrILXktoB&F5L+w5l57dp9A-D)fX|Y@29Knpu7oxG5w9NSPyOO9ilcL4Q=xV` zRz9_dZmTqJ)H<+_vwWy$ zp*5-mDFbq2PE7(#DiE-+Rx;5MCeE$;1r<9Y0j_&H-VMX^@}F*Sp}s?U!BJTg-Q)I|e37`%vLIs_kPJrK|3c&*zqz zHRt0+D}MShKwhaNBCB$Yg+LNPn>zAMNs87N^Tis1CM(-$7U39*vNWVi!BD8vq`AFx z4Ib2fBZAIna~IRk7G;`-wTx<~Ep<&VdVhQVO<=CY1@Za9AgHu$wSbb~_=+3x-xAat z(M42&KgIMxQ)0(2)uF$H&o z!i=NXP^7E{&1qF+BJ0h4bYpCem$LOFCG8YHa9rVXfld8*7kgDxV-Cw6gxT(P_d)Z1f2O^#J<_ZG_fRIUK&zT9bkb@DI$92( zy>BXeYs*j8$W*9~HrP)Br9ekzYe^G`I~JD|J?reY|2co98?}8s7~}N-Vz9`F~L4cdx>b|3S|`ptMcyH1<9_JyEpKt^HI*@zqls^mq5+52F6_uJdTIyUw} zS2R7E*LxQ=6=nt)2Z-~tB6)e`@yt4vY{ePwy*TZ&L<35L@IHxQTQsruTdy3%{qT{N zb%#6vGr{Qs%Enr)SyF4`d!xE$GqmUeoFzc*9}g^cWy6@U9s;_x390D^%vwvxg1B&= zP{NE_TZm%~-=h_EU8r`a9H;7+JcI9X-b$(5?0_ASG93;60V1Ge@CgorrL$-JatE;g z3z(d8I{S=O5P0j0^UhE0gQ(zBRB4Xhyt~-P!Q60?oC_Wa>6?!8@eJx|H^avv+@rTLr*5(t9I# zd^)?G>i#_hlRG*3C7%0zfOCc0m~{Ym&=MWZEW8wisG+E@;G`JJr1aaddFycvb1Gbs zvBOqgHnQ%r8w$wWJ8{0-Zod(o6ewLDG$}V--e9nqP>RC9o~u#ki`d~|L!4vzfssQw zDZ&RBb9d|d6|RJ!FOHB3pp?m>_%g7}53&wJgF`AU7*p-N%j=dM+9|$9o%0}k{pj*^WzM|2!qMuUIFESpM!DmhDyZWKcoxNR9q7MIur-VOBZmo ziJtGvH-1rnz-h5XL`ZXyIgcs1FZXxPzKfyU9b`KDQdZ8@D?>Iz({=;wtX@S>V%@yR zi8tz)gm&PKV)FHf&iJZ47KLi$;bfzN969b(;Mg)l{roS zSPyL|ARYgE_Zp7=XTWG)=wY*!P=xU2{K_|nngdHR5({3*oOK*^PV&>va2Y`pbH&z# ze3Qm(SsJJXkMbByv<0sJVE zU5C@+gH!V#&`AbA-*LY@cZh3(qRSre=q$8G1i7qS+~o{JO~D4x722IYc2a(4@T{~=dbNmAX?a%}Uh9+)b6ZfD;j`0-}T1Ocwr@HNxhOF;uhHDe$3;oEhJ1LlH)I}KM$CK_Zo|PX3=r_ipKJSbKw`Geh@xJ;*+lYtv$@% z`M99gvf`gzMXG{tYKVjHtRfezG0nmpC1P^|DptS)Np+#?d z|0;Y)jVhwk$TpV&eORO0sgHLsbrLP;x}K!;b{S5uhrf^nNv$^Z%5AX?T=bsnltg3@ z0NeU-lA_3FqyY3eR&5Ab!Ws;%AY^CgezUBYzmb5E9JVYzEOKCRShNX&Z^7Fw@m2x6 zSZ+A)xv>PudMjs8NESQqbrv#xY28R0h^v1=8{qHO1Wh6G9*%g@KA^zaFk)t+AWwd| z)mpgPK8IywoxHn}XZP>*Cb3jh6SPZmLWbOx)O&U$XwE|(mE%aSE#<;=G(F;N1sJ~E z0t@$&A0!5>1OYp%iDLE=p!F#`7zU~cP3Lgnsz8W8ywej=AvyN>; znN(lH4v7WJcqWFPZTQQnOwU0RyZz>L+IsYPc_KufX z!1}}U2?b`}+gvU~6eHi25+w)Zq#23vgKEbjL^s(3xVeX6|JXu%mreRkFcie9wtLQy zyq^ylqU?Hw15Sc|uBaw3P!hP&x6eh;F1HEl6^#hpI6(Qxhf$yYMh&fl)00Ayy)8bm zPrWA*5mRC+)b5bQF-`tAx;F^85|FJJzJ%Q*L|bv|{R$P;b@xIbmf`+2^Uy%%57fZ5 z+C#q*DE-Y&@(G(JeumRl5kphy;^t%6tk}^4x&c!p*n)*@-d?a z+*nV_EZLPA^~Rc%r?i=Mppoc>K2K6!2ey?eVlkML;pZ8W|=>(EfuPlSH_|~>~7U0bWKynV&(ecN0yJDu=MDI$H8~BmeQmz7Q}M3 z2wM#cpDb}J5MRjlvBkN*y9@tR*sS#l4nYe&fliEabZV=*T;nAyWo|(CGX(@4nki8l z7X(&YKW@|(&`;~MQ`;Esq?B@-NBh-KMB2S1G-!)iBeWW2)Yz%0U8QT%Q)`f>&zmPx zNaOEBgVgn35UtHVuh73|XFVj69T`~mB3_2dz0|?5_ABzo_!9-HN0%=w9X=@_&qa&= zmEO@!_r5esBlrYd-G?X|b=5!>{b3PRL@Ti2w#7UZ_35q&dilk#zOGfg`s7tAPwA^C zYIQBKrH^H@10+BN6HhNoREcs=$Oiuf_2*#!V*L6`$`FnHW3h<#@#qD?k%)CvcvjmD z(r1TvvSzjnD%7M<^<}QCZZj!j*~so==nkX$!sCsnjbC{j1S+d2oJ4xuUOhE{f|5Uo z*4s#!RtSImmCiA7r|rc6Iqzk|JEeb}QXW4*hx!e=`z5646sy$sRd=_l1wp0q3SEGy z8#O*RuKE@X3vv656JUvJ4@M?5RcF=r%h8tF|(ruZyt>QYWGp?Q6sDwZ`xZ`F@) z7TAw_eHe1mj=yLe7S)rQP<83h zHML+g7^Wm)$Fgz=V8p0dRmkM0-S4QjqjAt#&?xlC+}Ezc=ZPeW5W|gq!@5nGvOiu2o()Jkx?AG* zht1w0@1_3qWwW(9VLFpJ=dm6a@~v)@Mu! z@N&fOYbzv@rAy%x%lGV9JOXa@>~I={5{ZV<4*=bV?1=`6Ene?T9EDYw+QNeFwnF7F zS)yo1NZ$Oe^TE5R9JTwhc%Tl0%^@JPXxg|qlhb>!8-EDtS=9(xpRRnWA{LS`%EE$e z+H9z}6S6p+3y?{e>A57Xuv!3&d3G?H-Lj!Sr*V8GS~57$voM_oueeaHV;MH`PgU9@ za&}EcB6rDD^eQ=-C(={4pN$*~l`9n;Y%4bnlwoZ@S1-ODflocF#s(Xf!%Z_o8=lW; zf@s$c#2U9Tbc`iT#Ii%py>iKz=Z7C`x_3*dBuz(Uo2^O(%i0FBS#X! zA?(kX#I?;@pmNeOMLD}^eUC!ZGVEi1+P?1yT|XBJi5}erghEYbq}Oa(+CHGD5Jg*- z5(c#nvXM5lV06e|y9t;fty+gbb;TNgbO<;R%=&S3S1{6;Fr&Jzr9W9Kb75;XvLXe{ z`+ce{E-#?gta~>9Qg{w1Qk>xd?kkn?gPjip2B+n_<4T4{;gUH_n2xIWqD<)+4*O1z zY%k>cgz-Zb%l(vjf7XfSL%kGxt|@VP9DT=X$E^kzQLn(S^78I%MzZC&M2%Vs;y6y&EES#@EP50QVhIT|4?;phJyC`tvuPn{h z*25`fPARuhXxV60`ERB;R8;-^va(Pr;JNs4TYp0k%iy&sk&Vyj=jd6ltam-D(M|0A zV&$n?BCiJ}l7AT#GblU?G5rFBcwSPcVu1+oM$uJWv(LC%%oe-QJ=*Na37AigyLL_) z!ZV;j&f30ugh)#>*N&wcOq}&Pmk@hxQQ(KNYR-ah5pAh$KRBk|;A5SR-t_jnvisBf z7-s2AWKWaWHfh2C^EG+@=Cf2z%N|EG0mPC^>~567!ng<0i#v~eRUFRw%*P5%JI5p* zC-$zXj&AEf(DrsBcw%it&YLz7%vQ8rM~0(7!9T8YL&Pd>=K%3^?ZHEdlV?M8iQu96 zhD;h-7J`D|`b0dDLg$$LfE?^Dfl__~yw!r>4#6Lxd=|*3S-E&}SzC7k*RqazA-d%&rA;Xi-*n-cn2@+c z391BcrEQxKG(Y||))t-)&@OidFL14bUj;vi;!svd*7A6m%2O2c zu&Z{j>56qD(t{rB8BB$NMw5MSto9JV0kWoaon2Be08wiEX2VrFp1rR~N^I$qI(uAi>e-7A?U zvJu_vDV#i1Amja;!LGp3(L8kvPes1997K*&*wgb!hg#=Y)=DA+dgVfbiFFS}AszSO z!Tp<@C=X<`YU8Ji0n$6D3_38=-)p0pTM+x*LhZ0YS9A0(oFl$7{nt zsJ1WZZKXCVepN`jJ;%_h?6A;xGRQ`)4wqLj&*xj%M*Q%~z@`u(JLL6?BwY>M-m@|~ zP%)DvE$4;M#vyJgE}YwYv7tZg$xKAW`N1E+PI0AiluP%^vH2v{*V+Ha$vfCRkJyhj z$y4zrBX~1n-gLbj4ta9d@urmvALeD*gIt&U4)9_U)+c(kXs1>BTjc@QL2BC_9A1NtwhbD1n+ zKiSu`@Z^B^4qnAWDW)>sD~0RP)(k%#WTY}$!2&j`3~xP=?l^8Zag#{S%EVu^_P5=}z94@VVb;(-E(!fHE;&AV(4VtSjk32Sm1}o5SWI|myJ(l| znP*-8RyNM1dB`0JP(LfmLR zI&jb*e1~{N*Hmv!Ml1nd#;W+(&rB9`RvQ`orvBt6QidBJwH~PsoRPuawn7Oxd1v^PCajw5KV&%vt?;ns1o6SRDW3gXw0r%``IXm zY=8qo&DT9^#(;sERvD~haYLvfk%=Nk02X;u`;iovOp(Jppk!S~l<~uL>Jt$2l&cH_ zKTGp4qmS-FYGBUfpc+~Ck4(d?!iOz<8GD>?wXL=oe@~{9-+v8zT7_c=R(wctf~xOo zd_t_m!uI*u_N<2@YWe8{LjOUNwMwVGM-Hi`gfn$>6{#j4@i3xR75wXupd^J(-cp6zdYcDhx`OOl#6S=D3 z!38+>i+z5P+v#3|b5`Qj!S@og>ZAW6LXq>~UM3>L1J}!a#5f`BL#k7gR26tnA~k?XGw@1pSt5W&2&g|_!|J7HDA7QbB*eUy;<87DyY-}RnC6* z?UuLZWUbkPr&}GD#qO8gT51dudWllj9pfU!Idgx{_U)>oGb0lDL)P-*k?aQ^+jc=? z8hjPqq>nk9xHb(rpU^U}w7x?=U zZ&xeB!;DvAPKJzYlV|*_B3fC}iUZ;MB2*#2~xM$80ktNiyaM zG_ehhup2oPfP8aP+&_cH+y~zMk!Ob6M+r@ru!*QAN{1o-owie;D5)6= zAeX!l52oA55NTEpl-&}uhf@pq3m@)TvO^-CXDS@Qx9LKg3WibVKr&?=K8&*Dz#-kK z>>j?M2R;$&NpzdE*+*G7S5`NFL$Aed7Ur%8LXWd?{TeN#W| znIBXmAZ6rbBdxprA#Fk$K#+*#o{t7MW?kMZX2whNda=#u=UFBG7XDy?98$A({9#JI z^p`jkYW(}Iw0@}179sw7XiX1(-~|zm{rVjNUKmpT@Ss&LZ`-Z%R+`y*DY2x*nyvEt z&NOVcQeWU2%S_hO#=>?Xs2Maa+~_Ij-SZN{HD&{rNbIse+BrrW6|TQ8 z*xT=+fqn2~)+BRR?sfcpv+urI$8xlXybh!IuO5t#Tb9SKK4>ibkI&AGg+*-8v=0o% z0wz{x2&h=HeqWp33~z;qoLAwwu@8=CkK@|W)({pcrwn9mg@8J8^(rH2j#gb3MAiPK zSMI+k83zE$D|G)58h{A!+|t=#qw!%0(dvWGOQkLM*h^k!kA*pTi)$0`lH+=iCpy{R zXe2eT!ky`=SDt|^gQRWY&G2|2(C?M+;sf$mNK&dC!h-&L$y^*R3PS#gDsY8tV2#$i zKuCptUAJTo-5xKdzVx&%`9>LFCoG2~S zI6IZ<#g6>*$sK~ewaOp!71>MTQ+?3&{^p(&1EY(kF6WSfjx=Z)nWy-tdJZyqZ?%y` zC||OOF2rSeHz{LZ6ttCTU^~mCo!%vBH*J+P6s1-xsc~ADv9c0f1>~?|pwPmEHT4!W zU6l8rh8?!>xu?ybou+Iib+(%KeixKtD8GmBE9(%X5rt3oAc#nzmai;(kM$dW$H*(a4VnNsW{5cd@QuehIYgpH@D zY=%S6yoGxm%Js|#vEzO2dZ|_2HFV-VsdLDxbe+|4$@4qCvA!9;J%)@K&UVm`mq>1S*=d%p6%bJ4<5}nJM|m`}Ae=@K4 zY|2AMBCmtaj9utvAguE3+n|9z4&42RqOE&(Ir0j7ddE}%@#4(^WVxo^Lc?E8ClpOB zHmDKOvHu|BwV8c;ZFD|w2>aCRc6{Sl_bwigOL&45pI?a@gtk4ye4Ny9tBH6nxAtNS zIMa?tMT&l}8ZZDwmRn}otKB%55PZHYXHRHIm6Bn+^T*xvU@WVTZj?<`%V&Z=K8fFR~ z8DbxNO*eyLpn4+63}DS@Eth{MG0Gpq7QagKs<0$Z>Ax4n=92Z$Z?c^7PRB9?U9-zC zT~TDydCH02q8^wJO!c5ov5kBZtfQ9V^JyNY;scvVj|fE42f*Aod;L-i*JuLde03I_ z1W^n6_a$WHl_v*cdUbsQYO+iiV>Be+D=Sw?oSImXG&WOV#@8&l*S22TmAo8h*~qqp zm~r5$KanBn4+Vere;(`3i$l_vuHyA`AT+h{uenonyFcRTD(CGW{_Cb1EvAU=I7Z=7V~9w#$=ykeXzh?Rc-Howhh4i^ zQz;c|4kP*%E?#`|$ZP$;`SAnoI**6X+WME~&{4xjvcxYpjQ9(VOa&6|h#U*rg?ov{ z;TqOlL+Rs5?7w+nreI~m%8bOsuPfE+eMa8#1}@tjntz9m+x|ThQK_?lQa_KA5c{u$>h+U?xT34A zI#hBI5w}vCsFEa9iOkN*l;(`@)_jb>fe6mX>{h4XWj;^EkNhjyHC`;ukOfUo9~6q@mDbtFh^ zBUEmVMEdglGzl4sf!_aeT zKqLR}yyFIZb0T)r5_;`%b9zH@b?ki*V`h(CoCBj|Y76e^5N$)JjE0P}j3*l-#h$Vf ztScHh3;TuZCO0eMyITvoIxBu!d8JU7)ikRR)c2RG-_~+Qg%7&{{k$~keD8@>SKaQ0 z(%#?K?*JF|yy`vwd{buGDyvwq(1j!}a zcvhVPxHgnx^`g9xxMv-OY5KRJ{SXK=R`#<7d9Lq5E4BuXsdiy9BpYMTh2W#cNj1ao3+o1aj>Zdni{vyq-`?1kwml;HxvKuA8W{=U7L0mV zaq86=U-q(+kaVxH`4x`!AAU9$@_ju>B_FaB;;HEs( zQd187M<`D9bai{-D1)v3jOct4~%;q9` zfAK>+ioC;C)Pd0SQW+d(7AdqwgRl!Tx6a?!)67|QR4%)>nHZx~HQN33U#T8)Nne4t z9QNX~Qr%#?StLtYvV|SXKz5K}&y;UQpv#8(uT-t%Az>M`sXWIL@7ya8y(c))sG-mB zp_+GyNgn309g9;z5I28O*(;Aqw|R96Wcp?42&(ifb1=jgwBu#uKT;Qs)GD3V!?h{s z8aI%9j8JDhoz(6yo??t`X_e4r*LFmOU$+3@-|JoEgp~Cl+gxengc)=YlK&>bYC;%r zX}8WxcE(5maD1}zQw!({(Nz%o>+Yi5Y$ZufP$d`YNo72;o6!WM>HctX)Kn;0d;g|+m)NH(oC6224_?Ji|N(XMdqnV*1w z%U2&%Zb_+ARH;cCaEpP2SKXM!UDI;;P;>2qrCz}~2xCXKk3HgzZ9rdD7HBDQyE8eK;=3aruKd%B+cJ4_kkHN6p&25pX~iz$YZ95v7456FkvG_-H2iYNyV@{4(LGR-Bi;racT&cA*Z{ zq)sU*5gv^xaEEM-zdQ1jRW+Gr*PM7`_e^5bBwe|`p~4M36lZe#sddE^!~YL7AVYC( z-~iM3Py0+2-VT@^t7H&Po`{w*GGFkD+&HX`BT&q>xMH}Ckyz2^uPrPYqr*C}S7JGN zR=J0PpT5tY1`7vD785y7fiaJ;^N)kGi0<$*5~uL!KKUTK^6L@k(@IFM91L_6bw!5( zDx0U(^3Ro_Fza-6iTEVkedbF6h?pJWX%EL-JglFz&TFlqRhuR+q$mWc8bXg%s-y9K z>w$d2-HR)d!cOTimpw`^nL>mjUdVu0ZtcF(I%5!><~jVaY$-#Aufa@Px2{R(NP>{H zy@0H7RJG>{*Giccow*Xy50#szNVp%xr@0iF4I;=?+1+7(3s{wV1r2*6a;}ud>ybf= zt}6e*TQ7&V9!A*t*g)(1DnO!{`D)zn^PmJ}7R6sz3)_QXMMRcNHUT@QmtwpCSM!^O z2-p@FHd6`Je@rHR{Li_YU)TTdM#*-Y@W~F(D0V%pEGS9DO55^$l3Q1pnsg#;k>z8rrEyo8&!QCOzf z(fX!Dbl?vle z@qyA?ETWcaz>(c}N8$0pGL|yPyaVdb*JR_^4&-`9mvGN!Ws4E>x~bfCpxu4;0~{&4 zCUHm{TE6#Y4pK#J6S>$*M$G%<36y7%m56p$>$WnBfMnHtkdbx*H7ZU*(x=NHkH14) z`2Nqeju3L<3@|E#$DsJ;A~6CX;ao8};B^l~Q7o*z5dfCIgNr9$m^3>PME~ar`Q7G% zSHNS2HjVUdLBwFU+GF@340k3QJ0gD{)>j7*kFj>n7{7jGiV!KUHj(D9sIr%r4%p5--7W==rmE9>o-Z0EF>MbGJU_HFGoIz&< zh?s^W{7^GEq*+a;{}?Q<;I!ogjHUJc9vIv@H;Rp6GX?uiy``w{{>vG^%Syu}UNeZl ze$OyB9b{Ct1oH?XFJZ>gUCfEl;kQD_2_z*|q>3W0q<@x&aO(-*NfXpkAjC#!2uFbH z8}fK?3Ev;iJ_Ev@5s|G~X3$?yO7wk*m;wozU>e-iaJxo%U(oajE~>0dkQQ!6s53#H97lWR zMH2s1G9g&`l5>y#Fmm73qZ{%lAMB=VOq#NMH_>5HEp4b;=^>oyDfQeY6A?$9VO zmTYiP{qewvi-ozwp7E6oNJb}vBiF_gWSlKh__3NRtNcd7DBKCPu(2EQBy%ka-aV-a zDkp_O+~d`8`%(9;WiZfhjfbCu_?Q>X-4(FndeH^W8r4X>_B6`y{qf{Lf=^PF5&PU> zJpwPVLi)FkY$fCM?;xxQ4cJSY-JwVNINBNLqM|XgC$3s!_GS(V?(}~nK0NCuN(gm# zAbE2W|1k(U!v!u?HO6S$tIs`yZIo|LQy;bn1t_s*wr=C)hTObN4TIl$EFk1X)&}lf z4lw98CytI0WSr9L6b*q@P{69Bz*dqX@n-KH!Hc>HpJ9&|C5&8UA-{7@c}$1}bxY z0>}`;%L0yfw=Z-4Aae&eNEq80p%Y@nkbKrr#rs%Ea#P2E4uH{YgW(Pt+<0EC8kywG6 z2ahc}Hm`p77;2Y7?q0al<6frzd319um}obX{7l6&^kpOeFAqC^5sM-zOpSlHVy2XvB3*`$dJrj+m1}^foSpi@O2`n=kXbgg3qjtNWZbJYe zs_1}3^#)|E&d=udpfY5IP_sS5mE}S+VQ^+ne~o!)KMBd>(zKpc{${I<^YJT&S2>8s zb%{38C+MdZ_1bMON8%m9Cv=WvM-5#~%A)?wSnH{4l<@Q>AL4R{kflmc%arX6^E`HA z;k%TR!wP~Oka8H@4=v8n|MLpx; zuL-TS+S7>s<5CUB69{=#%9er0O4o7IW@r#{0SF4Dc@UK_UY7G<&ZcWSfJomB!-+}S zHGOb?ZAZ@DjHvP8mr^6!LFTWcpV#aBDjq0Hx;eA^7=BA&0|r^wcF$YTP6oNX-Zf2! zd({%BQ|m=nq{@Rmp#MJR-(Qu3QL-{}EC`0ZDHOe`Tk)Dnq`A(N&AP2@mySJheu2Ff zmB_r>raqDa+|-_MCE10**C2`5w*^E%zg2|qbORCd`?B;ipwnUuHhU?dtJ9~kQ(ub9qQ7J<2Hz1~W$)6UE zOIY7~MjQ3w^LyL8E#+wVgYDwayu5ocY9=e9t`6wO{QP~4r}{%BJIXffBa0_I^##3AS2>i@mLZ|W1Kpfr0o;}I(ZP~9NHa=9mfM?A<4EDwOOEB2CJ&0{Y% zto-x$8}X`f-Yiq#iCuRJ7Omec7h7N-|$Ik9@2NPW5~`hO&ybwE_l*T%n! zfWjgI0!u3hNH5)>ARy8uAQDTLgmgN z=A7sA9Q8Fmf*ZVU|9yO9-7+caPucic8`_hx_cjOft20)%fbfqt71K)f_5`qrLHN96Ln!jr4Njf*ZKh5Rft;l`bEaI=kJKnN=)KDAyAS&sc z%|}NYSz}V`aU|>1pJ1eO#!_n$#(FY2yIIT+c4GRmX;ruBwheBHjUTa(Ymd7)CT6rv z?DI{)%`=|$QRZD!*B{uXw}lVR>RRRYt!C8nXd0&xwVOo!E+^Da{oT6oCsafb*nY%Km#n< z7hJMLjP_O21XoR>98!~wy9Qsn4~G4-P47oK&F9A1dX&}lsL$u(X3!_}9ZNR!HhxF4 z&F3l%v&2@E9!WL??xk3!fd66D6l{e?Q$>_^k0tlH#!$gU#G7yRHtlDhOy(7-?pa_-t>T~qtY1v&G^8Y~I1s0KX9BxikGx{LK9s5&&xo)= zjv_O4`qivy71<{8-B4ETL^%>4mg$vPah3nsOxP(BUj6s0C;Qf|mCQw-_TXo0+JJrn zox&MPtG=)nRN$BPSDkw2uUaPOUedHSHq6vLFkrcU24DC}&OVkk#yd3PpK2LTv4BNG zCx~jUigXV?&wl9Eh<+KX-H*LYKadaOs-++sfSiXU=Pg3`t47-JZKD% za9&!VUI0yq3lA6854C=Q;@zH5kKHB`8=U-vZHKk3i06xlk(b=#gu$o;ZA+UGlx8EGJ9XM+1rkY+n|9!#&WHJm%bW zbs=CE{Jpj(EW`Y{ti9_C(efc7{)HL|$xDX*rVbWr#-AfMqD!e}Z&mLsS5)&f_yvr! z5<0DaoB|alz%kVag^OR}5k``uT|S{Eb6k_?PsFA%w?4BpJHf42gSGZ zgv(mRlh@?~zYFN%Bv8H%(EeFn>cOZHAhq?RO(IUhf1V(?J^hY{*7WVBZDMH?N-3Oh zKRMCm(G%e@ff8fNw`BtzW+=Q@M=Nt`a%$MdM=lwtyNu3ahqPawsZy5=^S@%Q_#Z2n zY}?D+k{jxj_orO(_i7GVl5eduU-y#o47<&jb=7nK$ULu?SgQ*M@AqqVU&ztiB{h?U zhCVL@m1>wqr1QhEzVFv-*O(aGwti+HL6_hQM{v=K)o^SG=Ay+ zH8Wi=`oJ={9dbtP6MLhz;rTLzWsdzMX(RjG-%sHS1)<4aSc`BTmat>6J0to{BkggJ zh?CU|yqnat`WBl-Y4(2V7yb&#n5oZ4s2~LUO~HbOgs7RQ6L0#CpXYw+qI!MWUq;3u zZ8iBX7pHQ`HX=g1=p~q{<4%59r*JbBtm-IZr{RTu{K|H_lzTi)qtQYAT$AN_?5vD= z189=_u=k64!F7!PE$jKqE#C?{<_U&Pxu{cieerK^7|m<>g$0qrT1o3Cl+g7$M3aIu}n*;}!vEgXPzq+p;<#&rWt;AyV%?;fN=y`Tm z$`rh5`=RNWF|SU5kd2B7YE-U%&9(G_OS*MNa+}78rRLF_$l9SOk6*8)I(P$kc7BECm+67Kw-+CU&uD=C8$MZb&c%7JL zg}2Ej;?y-sy{$qa{)P6YY_AxVlTSTpU-a&HL@mNZ(n#`nq>x(FoihxTV*!e$P2gB9 zf@(Y6!n2lj0kqa1H1u2@Jf!GXP?t;{-veYE0F*g$QL17t8wks=!b`xF=e*D{N|O(J zu#n$ne!%_H3Qu#5>5hEShmY~NE8pah- zF_t7-JOsTmw(@dd%-piPeR~SOCu+~g7EtXoF7ha+y4Gw=}`&#x; zTkvI6Oog@@sqvaS1=*;niI-naZ0!8#k1}an%wt5zq-jXg9ki%~iV8esg%p*yjv<%n zh!KAoKa5N(aHa_tQU{K6Bwg-E|I9iyhJH3tPnj?T4`a~Xu(#$*F9o?Bw-rbu`chBC zS|7F(V-OFE=Kj`?zor(D+Y}tw{~H`^o2dAWuOs5vU)~$rH{qA9wW*!^QLjkG2Go3;x+4JvlcIzmW_A|D41-Lmc>(^5x*9sjZg^uL9w-^f|F^Vrz4Ga6*Be(Rf~~OhfG}-=%dfJB5v&1AG%U?tnt;ftM)oo9)`;b;ac445~XCiylfH>se1D#}jx<$!InI#*@e#_sVeyK|SN0sA0RE)eb7 zbqSd0iU%oBG#NF9hDz?!x#Na;U&zWK*&{mJ42xIlQCrX}OQeHUBf>d;=a_kW1)9gM zv^2)9YS3CdHBRD9;}N?{=&>h+v1Yo3#1_O@`|dU@dx;k_l|q?Ys^UBxnj?gPn~}qZ z*fNRX{^Q|oP@)igFnY!i)*=#o^PDW8bCIqyecy=EH)+VSu{5-Ek##%D(qji2ZB46X zLg^cDa4W&Nx*mNyaO00HeoJ%B#Ml2L?ROVxqUF#;U2oNA`k@K8u0u8VJw6N*_Ai+u zXtx9+@!^T<4Ap@>$u4R08#+RMgk#(3%On*ZotHQ(&_|NIN)9MvR}N0EcskG^_V&RN zV{a6NxEg(4T*JmPQ3Q#Ok=tbzxK5(IkD`3I!TGyGm*p8YK}*p}ctQ2cA^Rw(sAZ`W z{8{UW;ir~Z*s}7xDu?@4^eAh=YlQbttFN_~x|C4Ms1p0HkcDu6%HW^wK8z0nhU7C3 za!jF=iC_OC)WslA447=1%K0vC7v)RChY^Nk#PD_bHJMo#;FVbCjyCh|J+ofO+^=bd zReOS00?vsWQ0zqgfIX4m8cmL1GMc8GFZwF5MS79bI8T+h(1k?!BBPSZOtNw)SyRv} z06eB}(?^rnd7tnUU9)Xhdccc>nn=UM&3_w#DJ z!dJMw-fARL47W52J5RUAGM;4RyDCg&wY9l0YrK71Ym!@S10J)4jkX@9V;^j=I6JJ} z=AML&#u~zuOvFFt* zI?hOm2#5TcwXi(0Kt3TE2aTV+Vy&aNyHrJ6X&(MB0=FXbK<`8p z-SagoC|~ZWh)QVwkfG*&=+wuE_3jO;T4U>zcONo0E-cAcTr#aPjqP~l=%&|BSw8$I zfPaO&GOZ4{39;>b;}a%Y6G^$U7Z`9Q_(<+n`0nZSm-;&GZMX&1OEuTdjQr}7WV8L^ zum`*t{SMZBc23)aZBy8soK$(>^}*in8GgUq?R-%t9uAhHN&llp#9U zpQXJbEuRq}Hn*AbDL(bSd6kiKeWmEz>*%E9e_m;l;C6DFaTB6tv-J;9)DyVO;<3>n zM@?2D1vxgu;=Vrt?1!Ux}(0WI|FJS~ykwyls{&bTG?b4Q)VlkzA?< z3j$sD8ij0f9q`7ca-JUk7E^FYByoEc`_3sbgQqO_5*qmXSsLB;2nE`q8RO9uOp%P` zKB^#n{Jnljf2GhUsix(DUaxpzMEk>dOP5^kAibc{;7>GRf;LA++2gON`==Z^DkSk( zVm+QLh3}fbxSVy_3fU$wz9Mt-yEYs?;_RK%fr@P8DosGdx24)kuJ{hN9r4l@q2}yM z6I>*SPqO2kKI~5R5(BQSr8uqr8K;~@OQRqRFLfAI9CrUHXpS_DNz>=bGM4=q99k1c zjNv&~6q_54#xmX!?=}4SkfmZP68`L9=EVNodTHP`;5rkSx#~;w4=16uTD*$$;m2rO z)RJDMN5}RMlKV8~c^0wAjbAiSOgVo*x*3yu%?EV-h25Rr_sT^t0L&5X{@0`^r{H+U z$WOIDK9_uH-%8VbK8A~PL+T}io!>A&JN@}5NLVz$6#71YGJ*4&a=pua_{+t|t-hst z*vWBVrpfzt{|8Oee8sRq#Dk_$?4cw$(1Lu>j3*cO3`|i>raX}O(q$Dd>lrwHG9TSV z+;1-Ks3pD{jN;i#)oYlcIg&W$=z+&udMGLiQ~}ZE{%0;(jQ%o2H#_=vmJ?G>!nA~Z z%^sIsXK<*tJNcgTDfMN2uJ#G#`gY$fYof>n-|Rm1@f`c?ekQMZhJt`-)$s!BD5uEe z`yc5%VbAH3JTe~rMlUtB82`MF=u_s?~*|8fypAWAb_-uk8y?T zp$qFAo%40Gm*`Z2rXmq1=&(n--|ETY-mTwU6MKIXI*n_LEp${%plt4n8v5~!kz(of z?b5`$mL#suuj^yalT>w>D>STZm&0j=ctr`wCG$ogOs-@`Gy_N#!@AR7-z_HvI4O+? zJmo+)uL%iz%jYa?59RIGqAl)**fdz`8J#yA*!!^xs%<7Z|N7CZ2VU|cj!BKUIga*P zZFC97({<#e!566fpH8kDfr7Qhcqml~lH^zW!JuQR(vQap4f ziGz12j$g8#NCRTx6gV|_NCoVi)qM7+Jf32y*A_8*mFB>cdgNGxl?{~TX|`#Sc1~>d z+C?12R%JaiYt+}mg2F#QV{i;G9iq~t+E0*68zl%ojBo*2(1?`m_eR8M{>oLm-gUJ1 zY5tDUF>aZ;+rAIG7kPf=xx@zi^t?T9*8|VRINMf#>}+0wM+5Igskz&Ns6|)Y!2P2a zB2qzbr0Bn6=2@Z^p^RZK9=W6%6 zWJ+xTX)TexOUF~UHDmhv-SM~5DK!At^X0z>=M?+=9)sDCEAjUw9shaT>`)taC%o-H94lx_QgXq= zIebR(oTTn5zYZ&8+3&v32i-};1fzmx=36-@#F8o*yXTqYrcNLTk(EhhjGV;p0^Pi1Yh(RB9l9DX}M0n<^uDh&hLW1 z*9ntPS@N$!D@9IpHYp+hd+2AMx*Br(<#yojz5dpU#5NC+vHtc9J_vA;m z*#6jMLL3DN@1teAqI)jCzgcJO9<+kOLax?^Tki8qOAO@&>6cPY&dxmromQL>b-gJzeq%dC z+jT3&ga?B2bm~|41ZLgI^JCO$A;k@TVavPYvNqf@p*59q17*iPgGv?!i9=jt9>|}q z;}_Sh?>?@uSq7F0J>js1xRDW`wQHo>XAJ_$ICJv}9x&yCZKg4I3|3{rdHOtl(i?T| zT*MYA*t8{!`gl^=ztV#skv3zDx z$jISG2z)R*s}Yy_6_MleHL>N~EV_;Bl5g>veJ}X^{i1(H80jTp-5`a4Ild=)=c2Jo z&<%{|pcOpns)|o=gUh?ioG`it+|QqRup_due_&OGYd9}dhsPnZA39i-guTj{A1 z_x$Jz=sh{ch_6&LHa`6IQEl~EBDOGV-w(#Or~8)Bcg9~bbNZ6XU@MLU6#aeLhT^v{ zY6^Z5jG{>Z@Q`BKb;@`xt{;=IVE(q!BqEBI!)hP+K4syb{XX6%Tm>Jn}K2 zfHz(dMv}*J|0k|_!v(QQlR*7YVl6WwrCGz|Ssa45;i)2bEVBi1`y5Yu8oZxn zIo~~j`V`U$!6i;tcB0h^eD=7h0?x&2EZ7r|T7{f;A{&`b)o*IQ;a7a~pvVa5>AL>B zS*O1rs4Q_bV+ifZG@k@Kyv(fuU<$$_+_ObUg<1BRH&??K{yMnK6-CdMpg3E%Hnp9OfYVog znFVE2U+9wbixt40onPfC<)!qR#r3V8%Dl^-GS=QSAlyvc(HeA{nYuHL>T9++{~gXe z#W(4(WszjL7ZdQU2-n?f>_$)_#L8tMfgYfuroTz=NNR2_Xr^jx;AWFzRPIO3T-*_r zM>E|D_D1zzBTqmZG`Gu7dXqF_<^?`arcxS%UtT6I`WXu=V2)5ohUo_lQk>t=2QT~D zCfYiE;3x)^;XRMcYta)MoPYP-xI3?(3@uCaT9;nG9Rg{nyFwWPg4rE&KF9~=j~n@- zdM}a9j(yuagA#=F#Q^Jn3E>Aa5jC7toX3Qofi!G?v3moHtA#glfEI_p9Lz>PM3qZ9OZ}VUY9t;bN$2%sYs*T^QpVofM|V54RKHSch0tFY>+jn zN;3}6mpAs^S?1l{>*$x#)JH9w|1vB3X;PwEbAL({OJc8+3*!rSlp0Q(?K@$GFmH0> zmUo?t59@j<4ZnrgxW~OZfw>H7H`=!UL@oFXJB6G)NBo!2>jZXUIg>=IdwGL;?L=p1i(2-UCYUtT6IfTkzPx%u(Ygc&_0xx@Hm6s3Tzm4iK#&xTtmuf9Fi*>c;ox!W3td45mVDSu)O-{#7o2W@fVn#eCo#=6F? z4@TbwRX?FRX<=EZ?>TO@GpKeLU0yG|PRA_@G!>$DGu3&e(3yXi)7F+YgS|)-Uk`=vnHoL1JYrrl*%D!a{?Lwv z31VQZQbV)HRzvSHq{KatOa87oUK@C0xWZ#Fy@{x{Tet)lWb$+;nHRaN<=B4D98PpS zv;r;Lj&|Y4*xAZ2;UYua;3p=HKs+6mh>z=7As1tQx{i4BXqU8QN;g`I>QUB4x+c&Y z?eP-6rp0K}f12KdTmA-}c!A3*8oc@yUM;hJC9QjA0mFXsPnvU@sv3BgPuHrstGL277HNAIbGM_We z%{Yq5A-=tv4CW!W3?+X&Ena^GLCt67fx)YK{3t!s+iX^?9~oS*Kc26!`G-Z(mA+(s zC#-X#qst+uK0?t*%gXcnX*=@vt18L02fUPN(h@>O7#TNr5B_YP^+y4lqVEoX+rG~k zrSi1przP~_mAo*k4?I0H(K2Ng;`<}G{6>Yje^jyeNUF<$jPW(4HvQbU`ZYoXL2}+I zn5#o*K4hu4*`Nh|tt8_eG3#NN)t|cRvrqiGb-BOLxfM1HoaEGvN;SK=gA&8P6Zk7F|MglF?7|FiV1@q#2|LvufGe@W%7&>o-Gf3Go^ew z4;f(}$aUOWjkY;G`M!hjKJ@6BH;7czF>_BVD^45<8N=57eIfiAv#t3`WK77W&%k4X z?`!=uy0ibO_R8yD4y|jicvdc|5edW{*y4$ubLuYqK-Hib?$G%SrD(Kw#_~#$Q20Zp zfsFy*SUb>!hAu^C@$j@M8sr-7Ld`?OO)I$#p{u`90Di)aNPQr})>9ucLNQW;P}%_9 zXQ;90Qx_JfNxSNNENfqo?I^^~mGbhp%g-7PW`GIw=}{5C_@;U>RCvlbP9jqG!e zH_6{Lin5LWPxaqVm9ZD%qjAuD_oM@E^nBnp(;^RA(*XD8;Lh=J|1gYCfwFiK6HUA# zJ#X!_ka=MX;k|bJYS6yzTCvkG1B-5`!3*T0f+{0R{^%%k#5@l0&7(O^&RG-$xb_xRcM<`K2yz z`*vo4GG8(7(-3AMBd%lrCGU(IpCx5u=W`3-UGfRu(ZkW!q?^=NaP^*#HOjJ;zh1J{ zI{`h0j_e7hab%6ZIn>ouiocgDlnsIs4HaS%CdI%|S0+i+QKfnls45lqd`KzhqY@+p zrx6zIt`s!P9_^ly3wB=_X_q=@anQO40VT`Y`&ybCNY_3zhP2h@5M$I2a7N+u+av1`P=hG#Jl5C-kUfJbzdH7r|F_3I3awxjoUZsH&|h8Wlp9c+1-3ab<|`S zmcF6B~$5Q9OSQ~lOk z*cV-5=H>yFiasKEY8^dQJwe?evE{e`Nkj!4I~h_HqeLkCcpnAqtm7v7q$b%av`Mwk0e8n$xmEqkP}h=9HK(I%=~7a(Cd87lcDbG3D)g4NP&B1 z@-@$s1xH0A<_p1VYH!1C|ac`9#*ta|sfUqh6N=IEX18ZH7uYh`%UDDAI-6WoT& zfuvJ56q)rqSYD4L6WcfIHKZqTj2nuglTIrd@+fGC1^!r+Nck;)}M@Bb;!tprb zZ=ch=02$e{H5+}}gy~J$nzTmGC)NXOl=3OO7c(q3EhV42{97J4)+sarQIaP}&UaM2 z;5Ogp)I9#tWy$rb&X;}7rhph~&%~cico@d@?P)@tS1{%z1C%m%1DB#ov#|qmg{=ar z0egLa20nT(d0JkD5#Wr#23U{3y6XL)C===4Z1KJdPP^2*T7{D5mLH7jr11(Wo@)Ig zv6c-$dYL0Iw=Of*)!5H4QlRhsVu}J=i@x>Vo*i_&YU_iV5QgCSRR!dct<>5NHovj8 zY%N(mdF3wisEaj~EYWFPZqpVbA0mgIOM*d>0H=$`A0l(nqMQeltST<`ACby!>7M3CT! z>rDKDtq)x9c)r+l!L}CuG=#t?*%UfiU$rs{D{e0>TkiQYkGfk|Ny)xx;Y*%rzX2d~ z8|7K!Lt+q(M(O{9B5@t32;X!Vwy6#Y^^Puavij#VF~f7Hs$i?>sWdWLosz}j0jpBs z`T($Va?g4kx{2^s=63*lq>7A#(pMQ%P3XVAhAodIhWqZ)>Q7Fo})3++brQ+zZ{8W0Uy!bx~=8HDSFbKyYgRoFzt_t_Hz*NM)z>!Q52BnZu%^Z3lUT(69OnNK|F`PF{vDVkGgev2WAS~xoJ~%f^cM;6B8iwP|ZjaC`fACH}E&lx-Qj`TX_CP`NF56r{bo z1|{ADVUTs49s~(hI*NYaL(%8Y!6u2%#ao;JW`8I6wUAu&I$<{-3szI6N4`yp6A32q z?6%*h7Y4ljn{wgZxS21;*ZFSsaz~*1<9qbOYzPaDP?U&%roo$IZRC+J{6@R*{R{JR z--UCn&s4^Rf39C1|6|h&EZ`=D)m(JEO6)6$aTJyGKr)2YnBAHE*K$zd&w##dr!-&< z8DLFv*+{@1wj2m}xks1D3O973mnDzyq=GP4T*?=wu&akr>aJ zBF!vnzDmwn6MnjXCKyyyRTquKRAFw2MXsay=;_t=y<6zBbD^ZW~W|Lv)*2$Ow zWtGq;@x>>O#fokQxti*;bu-$tE5S=2=ryW$J-^-QN5WynbtDZ2o^{U>39Vg4`>b^i zca1YoKgo_P4E{O%;&8;8%u!fB^EDwg<&%|cr@S1FfBnP^R(ucHF*d>F;Kkr2n^#qg z7tz=6UiStLdOV}9>QUEsFBzKxEVFwq16oX|+-otszF)fCyfk)_Qu4ZgR!sYH7^B`- zFWWqxLoTf41Ca8w^>IJtbAvO&H2;kj%;kptrj>LdkM#Vexf)_!*_U*GbwpOdd^b7b zG}J*1b{O2Q21>3yvCWJ(o7*m3JA37Kg`b{S=t-xYhWX#>X?VS~pXc9$Zm@x0!_{e+ z^_`xW>y2kddd|h!<33C@r)Gcek>kp#CZHmD!#2;RuIpL`?+Vt25wN@8y1lyh1=^X$ zCWG-N=*H#&*Y}IiEPz>lgRDKEzTg|8bb8b6v^NGDqSQ9CLbNn))Pl98nhgk^*&zd^ zf~qLMFlyl+_tWK^ZbF2vYmlKlyUjTvmlfSr0_^q*vu4f<)=R^*1?yap+( z%1UM$HGui0rF~Q=7Z{d{xL#)im;^Xz*K4f%XB}K^i;bCFIeO4p_0-$bf3#Klxm*0} zjvu-yLJcYkO$#3o4;1zT{@`Xyqz)1X)gAnZFeZEQc~{H<7Gz4h(4D$qOO6)m+$8R0 zGL8eDh|YMh4;9!-Cgtu98&b(~K%6ESPTsZI1pJOBY|{&vyX^nRu$kSU4lGE0F5fO) ztU%Jc>CX^m)|~7ExcjyZ*mO{goEDY&v(VpnER!D;GOBqI=t)_c-U`yggH_~hDYaqH z`F2(a>MlC%CdBt5q$I2F4?)w^KGhOZI}CM8>9O=ymuK#VOK zki)!2sJ+fXp@x-qZU1=Vd ze0Hmly6@7z-{AXmM`I(ynNi9EfUIVHm4IlKZ!I-QgG!dW@2M;qI|Xm8hHPp$UR%L5 zwy(+_gX-la(V0BtPdXLFDR6*zD?3xZAPUvsWj``52|ei(m099XVSUbbZ@A%}i=jTE znww!{47`O%uex)uLRNqlnf`dAJg6LAqC(Ywl|Z6(D|-?k^oz00&3Fvd+SvrI1I@s42= z{L|S+xsaKqf|2sbRH*KN696LAT^yH8fN90SZ8!8P1g)3Waa3$3HRX^5w2!>H3N*hi zfP?wQWrUj<;Y~NQrX?#@4I45{IsyvkL`#)af&P-nGh3W>lGx{@=r^#HDpU;={0Z)h zjt9x`0q(Z?w-9gJH)4g+!*wl@r_AFX(P=IN2!5)74*n;?mfW$=<{Cu0DG#}ymY?Cv z)E6jxyCEZ}gQsVt{mIA8Cc(Hqd2(~FccV3#qmT(qjELZt_@Bn<3sK^L&~dgIrF=>f z@P)-V3*779^ciVe?R3^7T#c1Yf^f6J0|U39Nvg_y;|U^TZw_62?rVDB*4akezbZ$Hg)wYUDqm!#;+N;u&Y`~ZJXgDnivGz0jH6h62bGWxR zyI-eQUm<)Bj2eKjs>Vq^BSFppU-%BdnG^ZwNB8FbGDEG&A*qem-&VBdcc4NZReO(+ zWYdlZ%fWDQ_4mL!<1>pAdqUc7w2M|2)^T~tThmgE`jhVZneY1Z^L<1|r&gLlwnH|X zRy-e6@uI<|X3F85DIwG%vnQ@qrN$~$?oeQiekqpMpkrG#jjlxlO|xG9RQh8sQCoA6 z0B*~pHpSrI?SjHX`Z@32E0D#nul~?x)M$t+uRbrl91~b+`2+Shr2oEzS_cKprJA%j zmotP!wS8X_-UD5ok@6&+q`AWjky#-IavO>+#xg$e(`my?G3kxNO1bZOoBP?;&CYJI zXz@Jyc?Rk13v%>d;*>vJ*R3%%>W6B|eo$|5t_$}me#~1qWYV56N54d;d)BIAd|;yM zS$!GiUpq8E>Pu=$+*7aF{jleqNI^TD*7&*R8V#8-S~eCku|)N#09!Pf@ec)3oDJ4J6ol!_ zL8~Tzo;XVwZ#_+zSS3s#b1r?1?ETLm#pKsiPqEm-sS82K#EV~sOl4Z#kppC13)0#DW z!oudQ`-=pS5z?KqIGt|V3*aEp7YTjTRuaL0Zx`U#XC2b1O|Ms`mk2M3F~FDQhE#q{ zMsIr_M7TL*;ezfV0u|wjMT&D0{jSk`O(`Qq_47FGt9uEyF_5HV*JBApYnTu(VR%db-HN+q3BYT4CZh%e3HgYVoG=h0-SLhlKF{Hun z?-y6Md2f6h>z{l8llE%uYyOs+Y^XyNE2gvh&sO?q8Oq)vu3i#XUI52Nco(2Ff%BGW zFA%aX_*C{OftBdTIa9=Sx48KI`Ci;%2-3hn9-fLkHdR^DR?K)LV=$ zDT}?`tUqtL5a+p2tJT{pnQpr2yubFkNxMH=xTU)Hx{teW^EzDs;L4jBulw*`(Yt{A zt)~0V`y=c75ig;;r2Ec=ySnZByBV*~_s74HGPU<-_tQQ1M_#v8_v>D_qBm)G*7xi8 zoA*~uS2OqLRO;@SLUAsgW*ncIkCpv_jWV>~h%iL7UYsgg0%mV3wRLgj3c(Z}!Zgc_ zO0UF46%Q5*Ris+grQtz~TA7b4>M1)YWe=oet0liuvNKoVCm1!x8npL4ei?{^tJc8k z1L8((YGOd0p|jP|hMlqe#5&JAdBe1jGw-X34kAWnCEk`vH1bWew*Ur_p3_Z=L4}!E zhsAdD5_gQjbq+8-(E8_$TPEA6DRta}#Rd(5f0v9;0w9?!>Lwu$zkqQh$9TS8Jux$L#no3OVd(s?*0=O)bq08_JsuzQVTBfr3Cdc! zh5m|fPY~Yo&b*J%kRQsA!!E4Q&_W0eBri<7&e4Fc5UIH6g!<_lz4(HwR}y!tQtUc} zcsYNSB|~EL9@n=pgZb++9C}G)ZOm;vupN_*1=+7)YW;M5^&$BYs2_f<#%R%Ce2nE@ zaIX1{Ob4i@Gg4f7Yh;MLVCY3v&n(&4Jl)WcR>}4Wb3g?GRS@(}+80r=;Y35ke$xA| z*xwP@FHYI+bLjY9T#8lua}>mTjtjPNzVv5dOkIi%6Ce za)SIQC7T3H=C+H@8e4!4nESlfv3DYZw@42kkHf@GH;z-hdK{fxk386772RF<6Wm$kD5I5->WA|3@^WoQX-Df(;qe zxd+p}7SFl0v(M;M(RvXOaMap>_oGdGVrWDc93AxH_qi_3=Idp``OdYSw-#E3e;NIY z57!$5Z!}z=`4nGe0QU-ko13HU;`ixG1Ce;~j3k;&^;Fcq>RBYmvG#M`$I)VxesmTk z%BTc!pJRyUtKEiMH1K3MowF1S)?F z!DXRUt<(}93frFgNczS%WXZLN)KPGl`j4Zz^PT=+OC0ztJH3ms?vG7%I_TqfdV2{# z+#1=^ul4higr%v<#6T@zCQiCKvEMha+#|uy03uiin}h@44L>58cvCNZ&A&yMtq05K zSVTD|RRWm+W&YRykd!VIi1Bqn_csM@wrlItf<8wqB)+4DXXY*qf|ipNa(?_0bmA|0 z&Kr{Nm3E3TB~B<6 zfQ>yH5GsN%?{0fqH?qI%;Y$_yW00)61%EMyphJB^Rz z?n~A2kNhJOZ%8gP(zCkxnk-O_$Uv%f6W^Gm^KU}+z>?qq5Y1FX+2mchq5T;V`k-fi zSNULnSS&>5E)4JA*jevz zP@f~=G>k^wFmkEa2G17#y&Hoi8YSk-_xtdD0Sf{xAq*&^xbU{FUMwV1h--`L<69r_ zD^Exz)a9%wP6QnLzI}99vEy|qXoK26#Qgl7)%Vlg)7hUgvOcBtN$Xec)Schr6>h#Z z)=}NfMUj3zx}Jox_fEzZ`!b#4n`pl2&1i{n4Fn*SdLmN8V%cw)ZC1{rt>5_3RdlGe zsJNI2SVz7aS2U|?J}^mGh*xJ?uxNT4q#PSArq2f9GB7`4kco!lWsp81(2zV9Yx%fS z=iaYuL_H{|jUf{Q=kE~couF%bL#YyJ%bbGfAjo5;F1)T!iXX*mYb6DOnj?9yhr+;U zZ#5wRxS9i&$nz&uk*^WYU6ZaKY&zHcZx9-)HbhUg!aUSqZS6C&#}m;7uA&y0z@FDrVnZN~*UtdRy~y5%|_Y zeBUjC_B$%faxbwyQ4l)~oQTZP+yhIn8Zl($`IiJm)OOyGWUymjFY4F}h z^!3fC5-a~?GW=4$@Z zeo>cg&o>5wayE^(o-WK$gM8zoVckLd+0xKXQpuNlj=$Al^Hk`isi$MpXwcZrP*a7* zF;?inc8!!@@b0N^&7N{g(uc+DlXn_@`?f;jXzL%e9~s14Edl-vBQzN^!KgK^_6f4r zZ{_pvV*JHsSpF;ZcQoVb-K&^w9F)WupX%j&o*uRn`Sz3$uN;1LVksXIoq9_D zhivGWy$k?U?2=Osx_d*tt!V_W0t>fUp*<(a$H}Kq_9>4d zXDxTBV|`F}(D=Fk*idg)J?Iw1QRqlv8^JTlTRqQnfSyIDjjR7#%SEjhcwl^PMd8bP z)eRqt_4c{}9A5=yulNWhQ*qMr(<*R?;fL;wP*@u|-F8_$bCP?nwse)MtitmV%oWEazLQfA1}u(2S{Hh?XG=)fMjxNK9~>E zD`-WhA{=K0>@%i7=KQd>XPfN?@Gm|Y2DwB~^_gw+Ydum5al(}0@xrk9o`ZG%mp3JZ z|GZO>YEia3t|k?b|KsSa_F4 z0)7PnNs;cZ(J>_*jP5S|9e;n_yL%6JdyTtu&-t9^c|RYA3Az>z0giV7-X(Wu{}y4a-`B9Ds#Bw_#I-{(?2H3)<%;lJ7M?13d2@|5N1wY82ol?oh)`X zxbkb!a3Pm5RMJoBSD8?y0xlNgv-{A2o1Yxk156tnbEi+jS2;V_<6^%Z?VntjWG`Ol z8dtFqq}=qI2znqR^B8+{R`U14_)mP}`O@Fh**|OlD7Tx&e+nAcL0-W*{omEhzpej> zx0?cgSNu-tr+TxFJYrTBJTDMYOt?p1;*)KX&w_iW`ro$5n}4nl^jXPZ8n8{} zl_syN(r|tfvHp?oxPVe-Z;RJOnskwhO&lY;wo|9=T6>*y*fQU%La-FYb=@Dr_y`ke zm%B&*)!*na5Zh*{x@jefxA}y>U~Q{9cc!3k_Ge{p3tMD-g(qY3sE4Gf; z>Rh;K%s?BsiH=8SzxBSIuOJTJ*e2gBF6Who_V&nI42{gJN0@Rd38&1SL#}j`?}`hw z!^$6`Hs}8{c)Pw+ZDvqhQ`sxz!M%WIP$>Q#;)gmh zDEuAbh7KTFBtsNo86w}Wl;7xZ7dZ6QyGGDgncT{XffkbmtncSCbb2yR)KAhsS;Dy^ zQ|1qQ#4ZKj&1}U@5_CQK18wVK455ZGKJQV|tylNL3rq@CDZ=Fu57rx@177}-?O=Sl z6975PmA;_Ygb0z8lY=SXDNH-1)^fM00n@YS2Tzm;r0>sdJESL^@Vw9ba1Cf1PQp}e zGALTz5myNke0od5y9KHl5drRMIS#@RWIql`LzJgTS_7hoeljuto9zy|D>K2r|H^5H zv1)XHM>>V~)n@Vj60v9=C_=9WJgoIwSJ$V+BTQzxP zkT}@dTBZUryJ#FD*};Pvrd6m2WtBF%#>CNms`7`=A(Gd%Qd#D(Olh%iVCup@GT>Nn zy(D->A~>MxMn`SQt@0S4F_K@g2{7e5Z@LxJa2>2P`3K6}kom)_q-cEAy!##lRc!GR zhuQj#=$PZ;Tp_bG7G@Wb>mAfjn~He|+rQm_8H%T_3xbRh?#eHuitpfuSTyvU-tT-& z1P|PUysT2~pe=OOQ`fo5?7n)2;Mq9$AGviY!Cti32Y=}(b9n@<=o7$8ZH5;BS8tV- z;-5gxN=ikQv{dP3vVIvCt=mXx!fR_s<@HInHS}w|sk5zgj!Cj`MQOhK>^lHOeRwJa z5bdwXIwjs&3G`mQ7^yLl_P@&2Awk~ZGrE0JvlUR>yozh@c~u1M2i5m*H07AOww4=R8_~{&tpq-*ck6jBA|~P+asPNRa>hIHhY(9 z&D&b#v$a_I8EbNv@85dY%Pz82E|*w!`DjZjAXUEU zGzQEGWQH5;mSg0)8mq>e0Zb!Y9<|SeyK(MK-#4LY@0K|Ku?)G7JaSCa%%C>WAt?YLaBQ~zq~G>992LR{n)@bdPRk#z;nbVH3Z3A0o`@>h+KbvDyR zk4xg{vZ|}eukV&euTAB6#+$70T;;}E5o3t&Ke?yrF9mT5J!HDq$(n!R&*Eb$VZq$_ zSfG%jQ&Qkj$`ibL$xnL1WfH?IjXMTMs62XwJKm)@^epBIS>r6Q;4n0X-WTm`;@6Ll zG@s2jD(kMaN(-{Jyo4`!K?+l8c+UOm&PZsA%G`L@}yFKy+UB`wVQot8}?CAK1JORT~r;q^byF&3Xd&5iUh%Nyf6u4#E&(MK9y) z?1AQshKTb)tA4Vhvp@4+jZ&Sif2rt(mHXZNh0)vr18%5C^YQnR=@_>AzR5S+onukx zlzYKvykJskQoD7^#}x7lLyuC+Am2|8{k3ocYpQbzS2Ou?J6;lwCX)d_#vH~`&dD!q zv%Bbfp_4-ZYOR{B;UfGGo7@(CAKD3A3(`DTupn%n!2I-AdbEuQivhAE>AFeganz^ zsz0+rrd`X2F zUZ;fw3WQkHc6O$<(q{mnt{Wq#N>gmGysW$bG81%--ymmj-te!%{v%fScPzaX*&(M| zsi;d*e@O{4L}MaF1^7-Adi5F~r|@ z{V4592DR_3$hk|uupM}BR>%(jW`rFI6{&tq{bqy{S{#)MK%gWX?8TwM_%HIXjEepB zLdT4&niQ=U733X1r{*lzsP@dxxLljwxW=MVO+`(HLs!HTZW^D$j}AMWDRd>p#-G9H z@EyG4x^%Q~XGr2D$LgTN_EFn1ULKoXM;#w&Im+`?da%y()>z#=lB%Oo`w0k=^4e!w zzVW2vYw%?m(>Q>j=Uch469|GiuRYkiXYB9z(&b)m-6N{TmO;(l2iT&wtPpdukNrt^NRf3a-OGZ^9_eSN_;FVe*;dhm~er(wG z@_|j-jKp7(7iN<&xpVG^wn}%2V!`zuoEb622>CXXzgFW+Gn@3y0>O@19&Tq|`;V^+ zKm_MG^l(m%4)a-Q6LOLz5Y8(FJMse0d8P<5d8tu8V!Z|(~*n8w1< z|3ygK{cE9dsr6DjiPDj%?;R#sT}%+gHS3HwF2<1wFAEJ@CgfqTKi4TWR6)79i=4#6 zSJs)NH7-d?vteRFiUsxuaS5eXEJg=r9^%FFFk+5>>ACQwfJPE%?H&Q+(p!A#Gg-W} zD4MLpyf19$Gt#V1a5)-f7h`iVUR}}I?_H4dm!4zI=01hzlZ$+CnKro&${kPX_w$$j{WT&J_jw{ z;#6Fl*HvD(`2zFXaHLaZK!&cxbr|vmy>Q4108?Ilm(WX1l$9&fZNlgdFDB(Xx`*#_ zLL&s4W%i9KlAw8`hU{8)USCN-N!I!IJ4rLBlc%YP`8!TP6w!gv09BHS`n&s3#I;>K zid-MYa(KyL@h;+Wq%7VwEh&{Gcp&M)JRJjF^Km(1%GaJQa)LmpLk^fyb-c>tln#6| zPXnZ0qPCMtDm$qd_4ReSTv;H9V)$TIMc$D~p7qN3U<;d^`TT$kI(W`=qa77z`gpGZ zJE1#ZS)=k&X-f!F-r%$F9f^El@)XyxTTvXzZ#Fe{Iq0QMbJe5kH?w#Hz7nP9o~@?n zH3_T7H*@PFi4rj3PswV#AG~fl?bx!sispkF=f1+iAR!qWWn)+6gSv-1)b+E(tgOD1 z%LVw&+F@%-$z<>BuaxA$oRIy6(!iL9W7`f8>GCWcS-D-ZR8EG}-Msce#H)efjFBVqWUZ z4*D=jw^a#O$Uw>@V%e$wcP+A?yqzW^aOnk*$a*Lt zfiN^MJ=TJP?@9j7r57QCtqM1ne7((QIG;Ucx$U!y2}T*v_J}#jxxgU~GxrNi(BB>x z@bd}s{iRdn=oTM?-HN*ZLYzrPi}{(&kD_Z1X%}wHr#PT~ZP(Xhl;&p@*1f&dgOeuK zM{>w$ZUy_3dEH$SDOG!8qWx0uJ8No=>8IsinRpib=&G2?2isD}Ghr7uF5f~s1;d}3 z0fgGYnN%_^ySqoYHqP*St=G;&6fOL5@4e|AS|A-wM#*QFw;Yx{{jtFjv#E1=c7kUX z``d_Vg)Uxho{?Kl?1f>7uy(Z;UG{5kz@T|}W?t9`cVP7}Et&OYg)P6tnmf~d_h!zO zAeGD#X+Ey}MDz3bTeYt_@?lV-C3B{fsGf0lMd-*5 z+NB=RLJo{0nu?SWz?}#-_Wv9voD7`{)vvG})dT&2g{ajG9AXQ(-BY!o$%wK~%ff8H z`F^ai=@*AWtwGiC+@Yg*5X{w3-X!}v@WLV|+(A58PU9raQxEj>Q9H}VPZrttR&$4&V~^iV zc5cw>xn|g{Gb&d~X{Iy6v>#|Zpk%LmRv zwR+XjeD|gD8dP!ghx0`DxCPq3UNRHY$>JyRELtr?N`32uxnoI7W>*sCy5EiV{L=fM zZJ>GYbj1`+@<&J#oGr3|-8i}!kTpw4PlNoQ>mA*WPq$(=Ub_dz%RHvEsjearx0c%$ z=@$m#uMz>|R|1&sG5PhyL+n&J>Dq}pp61$&ImZ$;oUxG|MVmlRnskf@wAvfrwuy0@)p6FQakZv z?m)|84E|xv{4-bTi{e*0F(`_hvAS>Iz=u+3HeiX?cDZ``uoV>aO&g$Xo`CU9}BaL z7z(;qs}OK;(p}eZq)4L;_)Bk*&c|4flW`0CuFg1ZuT%#ln%9k&37I)v{J$x?|rlfvubz%(mof37*+aw zxhV3uymdMK!t&4Ka&w!;-jgOJ1U;$RiYiVWfkQ%TX5P{6SwInEk-`Ibq9T535t5Q- zB~4h#*eja<&~HBV2nD2wV`^Tvb4DO|=?)Bo@m>IQ(`?HvH^uCs@UMy=nh^K&`ZqD% zS?JzP$DlV2=A(Wn4~XGk7hU7p*F83rrmFU7OzZvx`G4r< zQ4$#Q&2nBEc8^5dnK5hg2pZUm;K(U0eGd z9Z6bG-Zlp<%wGNl-7v_j-Xlv*slfs)w+ljWMbaVfvSbE_tfC=BYi?F7v05Cgj~X5K4uRtO3wVOO_^+?Ro}*)(vAdq)o_|>ULKT@5wvIx6u(|O<4CY%V z4e%W_r10(E3)KE|8-lSG5y2Mx^~~+dP{YH6xOQfIN!FXUNa1Yy9EIsi^=xemdvaG} z49nQbm4i1#XRr|hWWxiQQSAbV`v);o<=$MqLYYcGbg%P&R~PKd$vm>X3mY<MzkXFezq`@> zw*jFpuEPAra%+`3`<3?PCwvz&*M0jxDF1$mZxt`L5zu+cT(kU44oHd{ADEfxZi;9+ zsL$JqK-xs34enq2OV{qf%ms+lW>PT*vf~!e&<)`?7d8{g3A&4bS+Xg-mrrepIXBSK zB`_-aeltL6&n#(RvyBFH3=@tXuJQnk*_b|YjG06~U0H;>U_{Q5$81i0 zT2U3x*0WLPGVl5PI(502q1`$zUK?z*S_Fuf)H!z810e7{-dLS0G09_7&mf?Q?{ zZfKpZD*~C&U#LDiWs@*ZDrY;Xtis8;9#pqplmLRyum!Z{y9Fj26XAosgYQxjIzY#j zbCb1}^i^k|l&B8S??t}r9;6Gj)B<>d(-Ul5nyNtRis<`t?o?*EfvqRwA$&CaK~y6L zFYji67``Fy(~xgT{15?LSrWdCjaQf?K8>4~>NcHLSzrO799S-@>eI~Z|1(KmI?T4V zG)oC9k)9xyM_|b|>3!Iox8`mz24Q zHYS`k20(VYr}X)5pPvpDa>7>hmzTvqP* zr=Fh(ZY|uppvG*5#>rSveDotfGuou*mgom~m&|3tOYCUJA&Nz}%jWMn(Nb6_aPL;_ z#4m9eVEGs1ca#2n=~lXS9<8G{HILR##@JXTZU;3>=mCT_^s=w1Gv%SQN!j$!%~#?_ zx@!t1a(+KCAkZ%G+s!YN;w8E-7*@Wj39XOu%mO>KN=SWAC1(yp3gy|zm$Qp+4)&q2 z&QbI~P3V3oIKXWO^v;Nf3CL$zcz+DS>qJJ)xADOHLP#Eg0OBp9-G%3g` z-7IgA;xpCTb!4Hf176eXTO+iQP#osN(mBrqH3JOm5qGAd0AvY4KAUcZlj)jDw^~n^ z-c0}C$b9+$c+ShT2Ewpmg2QR4Lyf5XPGNN>FF>J0xW{^w`4(fTJ1A`Jbb^@0cP;ZJFLb z*{p1@4;SxQGi!FSzjkWpk{*I(>X0TV7vNfH>beeYwzdq!U>+w6rU2dJPCrMRR4`;5GE z*jZ$&^AXgmRC3g22UUVEV0M;)1{>1n6p51>Zn@}{{B@bcH=f^mB9hyNbncdEW4kc~ z8+c$zWoL3GPR4KS0t0kB!&d>@qaWW$Z{a5v@mkyM;h zdY{96($_^XbQ8aFSu8uUHMp0abn2GoBVAUqDe*?aIc;OnCxr!j4?8iF{T2(%)|>^S zfJ$RRDIJfqpv;cTtiG$#1xnD!@D~1SH*89*>~As|%CrkLM7A!5HJzi0+~xaGSp}Q( zdO1A;k&lj0Q;ojdNoKxLi9iUr7#_lXrdDeXNaE}K;dCX$@ zH)W(imV1=Gai4t|ptS?jjQUTm)iYUAMD*X~9v$EqJ~H@$dz!@}klqNGQQ43C_7eYI z=!ifDUcrktn$aTi2iiX%*0yj6Z=yRB%+dvHg`%NEPK(2msmz%Ur$~vE$#O^I)~D)w zPR&*lL{!@E*%n1>>QwzA{$Dw#u@=md?&}&ChL*@5!Dt5w`hVcm9|Lg9W(#q1aGbmO zPZplou6&@n3@7_2lP^oF08|1Hl3&)qZQe=6I(DRJks|?URhTv!Vw{DqmTb`0^uHmo z(`XVNP5w+vysB$DoUehToMB+|PA3MJZXw zKpd&X-tU~#d+6dnd|df_$T^{k+H1(h%tT0vcz3uqfJ!#9ZfG*)R4E;&>AHGe^ zlq3lSpm^gsvlm3Z9AM4v?5oyO8Hnfu;NR5~3_XxA$q1ZsomA#61=08Ug$4OwsV}Ji zVF3#Uh5p%{nD}qtGT2`m~m4kDBQ3K(OR|A;@NnKZdy44e-Ll+mwLEZKv#>TuQs;thm zP4Jeq5*B}MbY{)|{?@5?r>PUa5cx6Clr7}rpwOB4`&RJvo@8fabjp%_9_)Mk`FMf* z9G35gM!s*gG;B3oS?7JYt$v%^=yKK|PTBG?uy2{0#yZ z?sP*Y3mW{TAoTH3_134Q9Na96QSVXgT?6PY{iFJdwTBleDb_=~n0=krTV;B;>#-_1 ziC>%HHoje+!rL+(SeADUs8PwsjN9s}^Z7 z(IxgCK66(KIBErdq1&3SKCK@F0E@JHMpVW*)lCe;3ct&TH0L0;c2BKa!OKo}fDyc6 z9SV)FmLjDh_i5gDSMv6&i^dW+2~8<O;IOeFB?EF#GfH3(`>c* zcc)Kp1F(wWCl)eXl)sSUZ9d{fEV;<2*W`sT5dulGb>S|Gl~LgUK|Rm^0%)8vWGR=~ zV$AoUkl-5)Pysw1Ywt3pswXGGhCM-U$*;;@zPUNT|48`c>0EMEvE42{&^&^LFf+!$ zY+#W#H+!X1Vb$It7@tK83}rPc9HNvv46J;M(Dh?Zt7!MdsL-fiYgGhSSBM8XX)is& zTcEF;@Yk8Yu}0J+J;yMj+|#{7vJ)kii==2R_hrs4OI-?Tmh^;keKh~1-%isr?&SI9 zqkhrE!Po)gTHSJ%z3@o?R8X!;XB}*`FneP;zY#WA7||y)Sy!dGc&b-E)R+Fc{r*;T zmKCk*M^qX;sZ_;R{N}z%E~W1F?8-DnAO_HAhA@~a^>`3b5O5w^ki$vfKC(>`Ndq@& zCeIhl5g2mnr08y=*kp~qZ>_KOVe)mtHpn+e_;up^*21>JYN3w*;ipQ~ZyO( zal2==)~cDqut9!^h}N`@*G345p=9rm+(28YwG@ASZM~jC)&G00!0j`g(#72^;#I2P zl$an5zs|k4M;&e;9o|xnAWAEa z&fZo+j)J~?dhQ0v>2_~pg-LqMZS!d+=z(V)liFM3@k=Bce#&4lRR4@L`%g4LL>A!4 zyVO5;mp;_{cQqxS*DwZoa2aKM-gHAyUL#@pJ;|(K1IOytQ;ykR7W-_gTgjG~@cz4M zha5eU>i_y<(VmWC>m3L%UY53pdApx-Lr$fL{AM=U&slx%xCDfeqSuvUzgip1g{t34 zfTciNI@}PI;RcT#f?0-Ssokvm^^5qWXH~Kfamsl&2Rn{euvAo7)1pgX#6{Vh}MZ&jo(V z!t1qV>g2DW3M2TvUNt_tAR{{a2F-~7cD~#6J&CHdh2uB68?V6&+4BW_*n)wTV5fSI zhK6qzO~H-GZU(vb?bg!nKNp~(>WS54)Y>CvWgwl0^taHBew=_^DeTSB&q(@FGkq;N z7mzBUsK!a}ZC5H?_}eksqs9$I?O zDTW;_0N@=lc{7{)kFf!Ivh9uS|5{p|1*iwVZ&;J4`h_MiXah|Dk2`B&2H zbl;2zbt7&Un#p*MU8iD{!nYb9+y~YyiBrIEkt}kpJ>=UZ-D06O0nFiiDAHv?2B=*q}FbaR~VNA{R<50IAx{fEAdRn=0|63fWe92D?I3&@k*~V6^U(N30L;6>U)$G>ldBH1C zWj-lm`&2P@`S=+5dNzBlG}b|KZMT;P-a9w+j^QWbWSgbz5zQw)S2)g6X#2Mg-%<6u zd?{P(pT=(Kvknms_kYl?UaQap6>Iuc@nRNGP5;De^=cRO@QDkH7C~`-80b z%4{o8=Vdw>6DX%}JifVcXWn)jwaqA4P`?PBDO%{uYxwu2;9p%8^(haW^2+a4&oW|{ zrq~a!R51=qt>}kc-is3|lp^jV%w?^&j^JVY;SqfwD;u+V805?lz9rBvZ&@S+K!yFJ z=tsoJ$TnYnI-veKbxDW;C0;Gk8t_+TdJr3GR40htf?xI;t&fs@o}5ZEkfMtT*sbzC z@dnl8Ui+GxlA-1*9R zN)4|MwrB-#fk|BSodAf19U*`Pxy!k4iPC{00O2|Hx2b68p_IGZgm){Pp;Ac*I z*JzEu;a>+GkX@wmpQo0p+#nWD``(T_u(Ic<$(W?aZa>&r_RhFOAO~#!9BT<>2uJpd z?Cw*AOOjty`>s^MstyamQUZ(Q9o2EZNPBiN7vq@E;3k%&YyhYq~D zX1*5aux+l&9=t96xvlCOzkOE^8=$mI_C6IV;4_47o7r<%c|g2|EPStZzNP;dDlH>K zA6)kywT!QY%_+w00*Qdy4giH*`b92}ye_kU`bDAmSTf?LGsJr+h+d8A$1dlZv;?Vv zH+@C(V?M8K&`fRi9q|64tB(t5K)z^A>EA1#I)eAEzLC<@52+#M_{VCM7Yg~V zKhScvYB~RxM%-tg;F=;cNBu~gHNs>$Of_$=?|SLL>3uVm;+yJ$pvvT);2ILd#}BEK z(f}6IV9vO-gl_l^!u46M&ZYu-i%mc(zjCn3epYZiH9rk9eelP$w-s6U(P9mn#YJZJ zB7~rJl}OQNkJN+?+jmkX9@R<7v|r*PX8I*|cKaW%XZu8y)BG;)9p^^4J4EE1$1l7r z;5V}!;!3+h$jjE#XokPf`1BLs^~_5*bWK*3^1~`WS(?*Lo-uh*MU)GhwDR9v*=y-F z#e$J=b`1|LQVo;)ETM%8PyZV5^YWiuuOeO>dPEoD$5wWyRGn1~RO6}Itl;XKJIf@A z9mj))kU)E+c5R1^DCXs&fs*UzoW}>1Ly=w2>rSz5!6PJMzieU*mmEbP2mXbo=@jx9 zwli_bVCk{F{)t;NGoNZ(;Lg+^<1A3b< zGVLc532?jHnqifj13dum=u%dQ6#i(1aOPfLnJqVYK#?Jw;V30)vuSj6co#Tw%TVj zD);coyU`}7-r(~-b?A}HGaFHes!{@j@jUh3os<;EO$It8u(Dasf?C;TNgL>YP!FR! z_+?7W7zmtWYV`rpD#Ef(?E-ymyQ1{OHu2qWkExKk>Aumksi`0ptNBFFcMCOnbG7Aa zpZ#ZRY!o#dCv5ggOy!DIypu$KOqMSKcRWz%fH7Il7$6KWwf@kg|MJ@)pc^6JMTOfj z(DY12y^y?WPI*QNuC<;{CDZZm#L~_ESc>>eg%jHV6d22B5VbK#G9rIjEQr)mr;`x& znUfJ`EjVp0HUnJM?cVG?so%voQQRXC-*e6@7~KucDF(QtFLvkwP`O+JM8|?t<_TxJ z=&Ykx4F{?8i@81G`;6a+sDyfEK%1$SQbwvo{;dO^^t1`B3xoG3&yL?@G|{q52wk5A znGY$l%2-w6GvqvjI6?gAM3G9GWa*)-=8^XkV&HP(Z^C0D*N_H8qY?K0L^zsSkK?%I zB@sYw>fYj{tz%nlT*cD4U9Dp>$w^W&Ed@T3IsJ!=ENe{dkC1dtykLpUB{EMcie{VU zfpuE2@+zyb4}HP=26w*`_{|Tq!vMHRK zA_>&i7J-sNJ^0aoGjWZ>=z6vi;b~N8pKd(GYTvU3Yf+y(Auc>U@qv|XjSxsc3kv#g z1^3J*!vO;gL5H8ab-w%?Sq49mv<8IQV&Y!Fd0!c>`xqy_py}px5Qx{1Q=H5cn2 zC!m3)-ppK=HAFOSyEm=K!O{;`rp{5nV`DiGm&uxXH}E3k1Irm*fQXvW(i{7ycwk3z z%_;wPt;lNx`alsJY73AT#07@Q%yA2CA)RZd4~Ua}@5kFB%2;y!gXGrdchVLovp(Wj zSO(ZMtu^8-=ogLj7_C~_&^lVgG_KaUn!4U`+vsL@Z+h24iT+7CjWIhxNQ-rRsyUFi z^Xp2yiW|5)v1p|7b5pqWUa=X7Q?1hTpe?n5R_RgV>86R%xRK7H{0UI=G5VqQy?PJ& z;ot_yNSmLiWtM8TfXq*Lz5kmhFG)vkKIb9B6JgpEVWh=rj@5huNkaya5L7fxAuCxE znz>|kx8h}0fXA|(-%ez3r-y%~^PaM0r8k^ZtuL{fsXx+RYXA5qFnk3+IsiRpRmqwn z-YV+(a%WaFz{82xdx(5Ok59ITILEuM#M3hM=6okpx@F}n%HuMbN`4&b_9sG1;gQMv z9cP+@_HTTBEsme`$C&B>S$g;H zhu5j^Mh=h+yK(tMyH=vSUTwO(B8?ZS`9L*fHr;sb#vOunzNkRW2T%M)v-m*#?#tAb zOQwP=C)@0e6zdL9sC!KLMNk+q)Epe6x#Vqb#Y(0$9nW^&@@@{C90;6cGJn98tl~r5 zF}QbHXEIuWO6!sw3F`j5M40i5F~>=A#%HK|M~HE%1~;!9h?mYLvrxzf{(bMH{Xxz| za0L(a#kVv;o0#~&d*7_UCDmPKm`2dZsy14Ec~=&}lzntde5kkbnPAd>pP+lhaE0OU zQWM7X3q9#?O(i&_KZ)VDrp4=SkVw%jNV(kq+uuegV z{VuAhNJkNJm&5}sW8CRIBc>oea{b)oV2r+8`|}|#R>PK_^xP-k5e-8KI2>{Qk`eD; zn0TtbEmd^l@Qxm!?R5Vo2OtFAc-}r)-fQvLDw_t}n(2bP#5b->9s-0Zd3VUgR15j( zBtK+ehiF2<22yz&!Cg0ono@eb(8nr<3AmPlbFg z&q7(~38zm>k0mZkFJ3f6`*Pvbs4Q}NXHZ6+XPDbQWnf7=Pw;5-4^Nj;tc)I* zP(|_VnW^u+JD+#KwRqBfQ|)6#fWes|gan@#VA~I?x?WJNabfWElB%FU1Z?^y`$$}u z>kri6M=FX{gmgLu34XG(+Td>kd0>}tLM9QqN;jkd=Ful%azf;XNNDPv|7WNuKTq6i zX%VUHDYs?j>Tm$bX!pebpWNtL zFv@49RJtn=r{K3ADM%*|gN!RLaFx_Nic`p~_2_;$&<-0oc(IWQMW@k1$3muIRoIJp z13YZX*kzN3bqV!m`BXvYr()c)+e8k-(Wj`u`$Ix2r<0Q94f1iA+c~Bsjcp6+?eHor zUkez!9=QIUtcOKy<*y`-{tV|BJJsSd-+am$k^j9NObUv2YhK}X{WH*|HQ~>0h`8S_ zs2^-E&)Hx?Zq6iw^ADcsgs<$`D({Ka-N)Yl#7L~}D(Hv-U&gaL_H0U$KGC@+2Iqle zmhecj)W)yvw={(y_aE~s!%r&jH2jxq1c#jP-vOxJx!NgocDoge&7UtxYun)uWo|8g zooF~tJ2=R^7BNhHS4w6}T8#8fg5wm&NRIUzNLpe@4MmOV@?(~-86Trsq4nk;qEEcZ zYTiVO$iu@#2?7p&WC?H+(xN<|*i|w!ogKkhspa&(TSuCPf23J8OHDKUb)% z-r}_Gbwi_uspEF-Q}MfmP_$Mq16M11<=B#yt9eQ0VlYhv*u7C+>PH+vPU?3vm*m8-mR;&`BKz)O_FZpD+WHt9*A>%C%F~n< zvE24scu)G}+8Bsi4y`y=Sei;cESxt%5#EP4%U-{C=jb^^P5j-%uqIBf@Q{G(Ki3Ry zWzYZoOKta;?ww7nqcOVF`(Y?|yrX;$X%Ldu>_`8TJu`+Bx(L4e{p1pczb%C6Z^k13 zMp~uP+xbZDkte+OF;v~Q)ynIhyfBb9d`FLm-(s(3?^s?Vd2oNCv5URYUFmPk-dFjT z$S<_=)&h{eDXtGkQ2_egB(ATdV&P?x9{UuF=q||wUdlPf?fX#;ou(V_BspTwr`~0N zAQEt>tFdz>x>>}8*2gNBj6ay`-bGYc6!gAyhPulU6SV_H?6wy|ZWNwFDvcS(di?@qu=0z5Os&J8=t*_^b8l@kwZ00cCoKvG1@tahHMu+k zlXon1)z$Q&IS}HQvze<`5kpuyUv{Jdck|m+16qJs`$EIk z;2F84c(?N`35MV@IPQ_4!&b{wnMSVdX9*#d&6f9D`p4Q7Bn<*(xcCuBL$REzvrp5J zqL-uuDcZOL#U5WP06D=%|1*xFjjx#(9V$(ig*(8&Mc!`p=23CTPXHcqLpOE+WH!>{ zrQ*%=3>2_sI{`J8vEHhp0wa9ct=4CB?!7!d4gvOI10CTJFuq+KfDNQii1F}8#g{A@WT6&6); z?rlN~X`9PlHFbRcwIhU&6FI=&qL~L_G&6((TO>N;=uxD*~BFa zsMp;HX4Prho94mZWu!t}5d~t*ZyU*<-y_9f zajH}g3|QaMrq@0sn$61T4S8ShAM0%X&y@a#1=lz7z!!l~<)NkaPuZ%FR=YLkl|A~X z=DA98&CG)^Lgj8Rmn-6=dcvjak5FS<*!k2Rjl{)8j|fs>UexD~nt^%3q6M^Y2eHeO zDzLi17!k`@YhKck+x2O>YQQ>5fP9Gt4>*184oL~6y&K(4-;BPy0O*3UrwE%v5Qj*b zp-Xo0y~8|4B@bKK*lXxbyIWGhzFOaH0mi;`R&mB$6e2vuy^F*!Z)(ifo^TJe$?*8f zfRt`yY0KiXQ|TF?Q8%*~1wC_)*&q!om%r86CTGEoT_M_7Rswf@L~WX=N2%ZrUBV-E&E%PunVUY3N76RZ2Lur=jbB4~wYrV_R&hF;U=5_+q7B{pq|BLw46=X0P zN@tjy4^#rA_l~#)1*iy=U|Vj@CgUd<=wpjJ%>ABl2{FUpT z0p(D&@&GZKqg_bSv%-JZ+j>uk$G!u z;1t^5CxpJTAzPPB5m>+X&IJn-73e73;1GBvmda3mm}b0%it~#|3Xdg@f~*5iNC0R094kgg%s~yW6udW2Dry=1!NW7fpB9uwt33+B>b}rw zRfx-^CGqYFGmv6qcz&g~=koVay2{&7A}A}{^N5;9)j-_LgR6T;_vMH7bWh!#!h|n* zp=j=4f9~4~3n!2LOl_V=vSM*b4D)|h+idwLhG;q|DE?)hr+`%%y{o%VJ_cdXpVR?Afrg$#z9&Zg`{ zek-|Mlu412M9qi=G`T=yRBzXtw(o^av>H|Mhy2$L6x`-JwZVSv#dnQ0I0`1Of8dvK z$T4Lz((o|03-)(=Fi%5Rdi4EydPV^0M$k$-j2yQ1mfImmk37&aQx3j`3iq>b6<2H! zVImD4h`$B=r|TX;I$xccFv}~!5V)%W ziE>y=kiI{FDM|F}wJNVQG`0_q&|7tia|qm|XeB2h>@ZJo(brLa*sdEjB&f*kfe|=n z=^<0KIH`b$>4L9m(`iuFkXVtcReUWui9CV%MElsz!}O*N-3eU4M@WTQMHFJm(K8ic z>iktwxxqT|>7qTZy%WX>PRf%Tq>X07R?5nt-vAgb>QfJCciX!H|Yz_L# z&eUht|8Vq{XY&GpN=Lo!bV>j@!s8kV2Vk{YPg&KXP=b`Pf~TYLTK(&HTNMnX{JZ&r zTWch1d0~Z|#@5SYqMIWvm&VU&?2dYKF#w=^8wK*?hB7^E?KJyMG(EEM{0F&HdTbV$yn(5 z2mDfy2yYnz-|?)(E+1VWMXIA3iy3l2-taByN_lm+RVMEoBtX7*kaH!2fC? zH%fATGwne7(&w;Oja};;h2MlzMti%3BuKRcvL$TjbHiR4D{zQ*zFk$cq64*}1MR{% z{EGjmSSd|_>B9p>wH82){#u;f4Pt`7>V9KDGe5o9oi>%F|IwfR%D8XUDg>ImxH`%opqI&c- z3Yz%gOvI{9JOcETHl6SpTZ|MwccB}`k1p8mRn6g6bfzR@2 z<*Vk7K5J*wb052Mw9T7f{{$KkD`gve?P3&hjDEyKO1G~WGZ(mn0-Q(BqkkbMmG9Zs z%ys;V!2E?ZF{=jlKC`oU?{Dtftb653>bBal79y+-8^3})qs7;cUB7xG)yCrXB{|Y3 zX5M$Qw<1d3#}0mqefpj)&2{b)uW48^3Dk7KgwnsEwz$B~-8d%aXvp{Pp9+r(JI5NG zu>xLu-=IIz^MyzPE`3XG_C2S0&r5lFd5Ms&lXkP?rB>R3C|6g3cBGwDp#O7HjmlwF zO0lEibc$l+u0HD8_~(LSr3abP(#1d1anA8v)7`u&Ckyl5+U{!|b1$&*9z*i;`OA;^yDwdbsq?^;Gs2Qt%?B|hS?kF&rS^ol~B6jmYxnuMf@{?@s zvK`^d$fLp*jK*R4`41WLW+<=L(c(-OjjO{ZE%_McySI>VS$gNTl-hIwZ^L{e6a+0P zt{FrN8Jge(%yorjO#G`a)R2}td`InIw|HyD($c)7X(}nx$x4)zT;=pfy;3}NY133G zdiJ2yLy;G@^Q(xlkcxvYSPC~^OZCm@c0u!n(V~%#Sa3nJuG&|mb)@fUv@Zpct`n1R zTE*<}ax-GqleGry3|D6Id3q{EA4^U{inf{j*X{JCdqFrI<*J!&5gS5q}TQOB)GeL^)`O#@frlraTZ*Xp^b!H>6BsE3$ z${Mexbw=cqboG=TG?yE^u>3n__f* zWBid5WZ*RP#46z5NzEg%Rwnxw`y>A$Agmwxh6e7|uT1k>m+;O~^~|b>koN9g)bALL zTR;*Q?^{0j85Q6yIcuyoL(q;iO%H^PK_^>_%zs9DyJ0hex`&|XkS#$vhM0UOyO8?~ zV*vvF31WJ#?~!SN@Z_LeSmd0Zcc93C;BGav^)z(cT7aCchCIFw$FoVvAz z-Wn>AB#_!?{Abj@8p%{B5&lC|?<+Iv(nssDWfPSvIUI?R-6m}=Gy(;0Q$BCR!)e_U z%kn2ebk4sWG*Z+jjcFwIMG7*JT%@=MilvmDKA1Te#NEMc(#Eb+ zEOelpY-Ya0+*I_3`&DAan#9{6@vjNLqf+%}&$!*Ln`7eOB@IUrIrJk{42p(z5#8*$ zOeAZ*jro|~l&Iz}hgjmSRW@9lX8N+$jOEa2MjgCHQ;ktb@_Bk4tj74Tv3-zj7;la} z94KBDHlK?b|4)DatXQ-@Thv~VbmS3#%gc5~G3pgQt^<>i0#hNltaVCKnh9hS_WT!v z`4y^JY~+s!oR>izm(ML}eOiozx(At)ehOld)+L_nlNVq>Jz-3TMyD5)VO-QDeo(cRr$;^^|d zzxSV=``lf|?(XxP=bX>^oO3{v{<(>nN=XZQI8JL)jzqo#2dAbBZ`kEGefFfjJr_P} zp-9+_j79STV-gua3MZR}dwj;)0|A8DGaxVtxeq|jGD-hQZ(10{G@hw010 zce)>EUUbJic~3}4{(+-usYCEF&pcO0=CD3KN>hPtVDPCpR)oR2(l_4kVpbFETfsl~ zAAsn(vqcXO+_f9m#I@+@r8A zU%Oa7#Voe>V(>0kDSG9cWHX~{)3Al!S11I2uitLJ)C8r)WPY(?rTP3fFxi zyAs}B3Y{-vV4*3L?ZYfS{!JR&q`lfRTA52X?sL&H^Z8-S3ZHht2`#a#w+uFLenEZk z`6G-}$Ggt2KF*@2;OMIJ=+GqlNMyeu=>gqbNV(aYsFb5Hr+P4V#%){5WiK+g3%ovj z(v}%MUkHG!lx80C&duL8~7kC@kVtkM4mo@2je2rg^`j$d$o-mPQEUf?? zk6iXC>AU>qSZ7xc7SnYSsGW9P>eZSSa?jb zGwIM5-=w#CM6ltf=8H+C`{xT@OIsha|6MKq?Uh0myS&PwQq>9Qv0U0MIxt~J6>D3l zBvcgix$e0QkXW?;R?@jO>F}KcoR`9n zb2St+#EL1hihe81m3f|hrI!u$JnOEc-pd)a*|`|rOd+)D1dHREeG&#KZfdRx54fuT z;Ax{K8D3(bt&HmgZv})(!vbnkc6}j?I8_`1ba-}6|G&jL0V)_0_cZ(?5x`Q%b~~aq zZqO{h4(pLe`2B58B4)mzy^@oGKICG}>Pz2Y4Fo;t; z5B5zQsau#It0&eAgNNGxYXHZhnJwp$*0XuoX@BXutS4yZhNkUC$c&zU7wDwBN-vS= z884~(1zzr7OUOq;IUz`vtApUpCO2!T2GDjH~ht;y^Ol!MI%s15l93c9@xux zv&*FoSkL+Se7ECL-UHTVB>v?fg7CfZ+kH{iC6CA{|#Ccxwa zdcVtF|0-#@hUWSk}0OVqcU&cruQnbhsbO=N zTAERNEW3tZS}+pY`%d@fq-cFpD>ubM7CsusPN~gs>4L_-t49e5w}jM&ZdiaSH{&_W zy74-0cT^+XUjB{it(WH=w*Za(R<9@qqn&nBdtU>>G8JOUPr5rL4gUeZ)a5eP+x`tA zMcJCwu}7lcG&2*5*-DCP(Ks3G_ zp}ifgMj(@m<>d1p%YYnfJVJt!F?b7aL%D`6Y?^e!L+m28$f|k_yf{Fqrz|3+2tb0o zlO{BHO;}J@W%9sNJ?y8x*j8Vk#ASJhpSVR)=fXCUIe5A-CBkLij7=+=p7njj0d*a5 z^=I)(OqiopPc5oS_aV!b7U^a3)FM(BqpEQ^Aaw| zFq;~{4*toTW>d0=>d;gqy^n|N+&<{KN2|dQN}ZH0h6nzC%30Jt?&T>8C}lI<8%ErqYFgJb#60ic`_WQ{WG$%7RK#!5XIO0kYMJ zSqtjw6=1aSdKBk0%z9nSVVf`g&oYQi@$`iW+Evwh3$}!$xn0__aD%DzzR_>6!e2w1 zAQ9t*&3o=J!Bz%CEjrrSzR%05>`ImdqY>?pD7cnGzjhQW1TB3M^&lPtyJtzo!tn$c zsiA1G_|&|+3=O+nQ_qfq0RvaQ0!{Wtvm`FEj{Wa_e2-UT)a z?!n4-%dmge7EO7xEXJo$OG{y}o~WV`O0dWdi;|wt)H)U3A57MqZphE_W=!Ts1)xp2 zMVrKIC-e=?)-jI#?6bom$PoPmQ(oq!luW{&f=WXgI25hzdb8r-HeZT)`-#B0R#6G~eJ07OSnDgrsN5UtINozR^-M%Z>~<(M3Pl(0~jt9i?=2yF3;} z1>Z<1FiG4kt5IqHO&^>$5;R!EOIr0XPXX%X*8uKw-rW51`khVQeKnC>7&+F=(}IA= z0p$kwEoc}pR6`{BH+^BzQ^pPYl}*6n>X{sn-%6pOvEAh1tnfzd=>xog)Zpk?$YOPOy%~SzDUPnIDnBlz z?r#4`zkPrZ7PSScnvn{+H~jeWTAFr4o%i*r&2cYrvizB7@@lMymqHKDji zJ@=KKLcd;iW@U~%pwTWrzu7BBEZtjmMRD(vUP6DDlkh7!+4bD;Ctz-xiu^PD0m$bH zcA3AZGQ8P&DdN*jlR_12geKUe2S<18isgScU5OIoO=qeTsaOK{)zVf^XQe2`pG&Qr z7W9`z2n=HvwSpLB@{}_AG|d6^b&^+C&P5lgY|5Z&TI^-Xr?1LKih5woT{;e#cdyd) zB)ESIp&R2UUCML+9;`j^W(a6`-}o*x8;&+@1>Sh72ll9jMx#gC3oXN!PQJwalpHga zebpq?@d@f_ZE^X$OpbO)`pB^OYO)+q2s4ouhLmWymde(6Pk&{F`R({7#fx@GZrCAw z|1(b}V)B7w-(2B(=F>xGPp|0^3sBLz@eC%`|D~KV5#7I4!bVjgfHjl+fb_R1 zp7KIy_}%)x)~$0AeGtvsVL`vbd$ZWYk!(;OCi zY}0R0#61)fd_(nIUm*_b!#Fms1rjiNVVt|j@?}Hs{p(A9t{yR6HObAjrC#4BYeipr zX6wiarMj=Oxo56$H2_6X6A=e=aMxtLff6oaU9+Ivgr~_SrG-J{AwL7`Oa3 zekatnj;C%EY|%*>hXVb2Kou`OCFxS&&Ozz2l`o$H@7Lh`n97s`SlEZ0N66+tksEkc z*{#Tg#h@I9A_Ah7f3qd1KTYUhZ~y)@-qPq}{e_58eQ7tI;7#4I&e5G9*zPp>qphz+ zVof#FCTMj9#!7r4tK~T6UXWw_#iwCx;m}B~fU8y3C#OTxmf5-F%e`b)@XxvQ7Vg=93=#!@gq(>&NbXG; ztweUGkOq$ti+@CXyf!onXj^#VH-TP!B-bW`4!n|-Vg1ZIL_!Q_%$*r?)>*g^>e<<+ zb1%PG?%SQUH-Ag0bQbX4ou!7o36Z`{jed3+toDZQ4FtWbccH;CP_S!Q>^EQJudkjd zqN7ve=-#Z-*!436|JS4Gj%znL0pV(;2WZe@(W;^Z#I%&mN7p&7#yAsDrPc0q;XpmN z#q1s}=f1GJwpLOy9a=fmGD1^-ypmBmq%IJ#3{tE3PA9(`n*dP>QkhL3!xna1FEyv8@heXwSZa)?gho7XVq$4hZwRk&Z zJR)bI^krXaU=F10n=&ynL>opUJZp;LhYCB_i{%rOU!I20-)Egw)n5HxS1H(S2y;Z; zTnQ2;N`4hvc+Y6caBQM*o5=88P>Jvg%J*_@5)6{|80WB6b%%q$%LQPV8sH80moF_f zLHbM}Y29>gYuZ4=e|(dx2=3aB&bdPBBiHV;?X$sA%b7!tS%()_V-hdpQB+a+HnUnf{Eu)QgzO&a0 z_Nx_h@0q5q+WWfyNQ2K8^g!c|IZ6&f;3DZMX@d&PqD!z9^z&Am&F;AQV8~*pWL9jf z|ACIw$75mp`tKva$~n+6s%`%QvU*QxPMdsNzvs=Yz2LlEX86WIOj3|=Y=UZ*JDik4 znucKY9;_m0k`p%T1x>f?P&o*;FdXRMV>ZrrTkVx9n4IVhJq$hqAs^5f9nX($3^k+E@6ShF`>=(9*Aa| zn-G8YoQD)+NyF9tDTx+cSMiq-(@GZ-FBi_LAuy%2Ky>KgyZFFQI{j+!xYc>1%DWdu zzAwg&PKW`v9B)Qfkit)0O72VheNny`GEc(vpR=I0_3%eeA z@+^xEeXsevz}`ZihX2lV)o$?q;THCecYpj4Ep>x;v4qRqLWqJBDV^W?npwV5RcUy- zx!0b&0Z6k-#(HIU`go!aruCxIT3l8?X~ksO>%%_)Q`p;f<_4Ox3+_puoAQw^H+nj< z{{6dRD7aTP0!+~vrlyi{7a_Fme3K{6f_BhihISBEL`Ar&fqB5@0>LM{(}Cv42hG*u z0x3n6_Na~(T_TTgKlpZBaMhaPxoc@9>%kb26zDBy`irjaklEngO5BP6cGYe~6^H8@ z>RNT}spst99*UNu&lva)5?(AgqLET^&0MpqHD+CYxV!75~beVK(A^+1V;Jt5jgoZpH?dvLOWu=^M=(9UACEDuIuJVS7Wn{KdypXwI6rOLlG+pB|S z;~K<97&aRaQ<~XArE^ll4j%ScyXsSv zgmoV84N=d{FT(zItb74!6t<^^f*5FdN$Y;DUv%Z=n}D3^`>T9tmyMCnJo8uc@;kvh zF3EL2BXaa*K6ID+$eisMp&NvL`Ou^;`5< zeBW7(xND~z0U_(`F&&MwJ2Wh|7t7G=-NrJ^G8=1u@9)t&Cx&dbNujFUAI%~*RPwFF zh4gSnJ!S5q>^b)9p*;4n*E8`AD{820VrqZyR!`#Pi`}J@ZcIuauS(1~M@rwkZU13j zm%ql=h%1Z^ZF)azq{ak=$oOb3(v+tM+9oC%2pI>scF>7SBnr1w7ft>l=e$C`Vn-!C z$ZJO43?Wd|!lUtM^l9cu4UWWkv*-6+XUG5q8`WlUmlo~RYmLEev^&6e z%qvtPVdQq{Sy>3s7+ST!nlBU4nyxq6T|16G%dZ0zVBgW(ic!c8+s8!zL7XW^#1FGL zV`s$Er8D{;*5Z~`7B~Ev;`$T;XwGzz8Niv#{#Y0U>{H9X{kHd~r#Ye|AqwjbPtJly z!pfKQy1o#&pL2OZ&JnbP28rTm%{sG;qVqZP&p45_b0bG zDA4y3wAM!ay)$}j2wHO=5Hku``lc#*cPP+fMD370TG?}t@XPz%gMc$6~~VhrEq?(79<$X_rOtm`INj?b=6z7styi^9SsUU6~5Hc4Z@RJ^&)f8IwUpv;aBe zcWG&bjt1OO1gN$rTTJq=L(^0_bz-uHte$_RA*hCk6Z0o2yGF2GSL-^@x|O?AnpMj*`~aSAL3_2x)>-|r6f94b$`As_d@Bdt=e=O(yyE!q$B1XMSo^fw$B2#2Xua1lw>s-Ofj zkfI)K07gZk@;B-{Ci-O>0$7#Kf!0Dvd^G1}Y)I}a&h^by%c`jC8E@WrXp-+EH<$VN z#_b)@p^cEfLMj=t_bt`FHPe16`&{&T$Es7#y8{P8@ycT3vpY!o5{sU@YmWjrGKXoB z6ak>zVskG@ppUH2B%A{#9@C4IeG)&jH`uwUcC_1SGdBNr|wbl zr-a$rIOT1__e`7a*(b=5=IV6W`%m_{$3K>Z$8a1|iTx*&PJ_gu^lP z-FJLcb(3h2+$hqIwr7nmykQ}49B>KDQ*QqIj)Dr!$LB{J_+=?E_iRxrTNb<)y`qcZ z3XJA&8{69R+Bj17AbLW`GM6uuaP!u(L<97v{lfs}JPqBTRUrx#ZyCilyk5}@>>V8{ zpG(h_wLUICilr7z>^aVFu>lLp6gHUoa zbbZfvU0H~!xrcubT4LNmdNUvghl}KGWxjj`4pRwwW`-RAS`J44>O&ohLK%lh92wIn zd>7qkLaQp9)VBEbsg`-M$(C)8E;vDn2CBvY?ny;Reo`W)2)37&IX~4UrIm)RnIs@S zf1nLG{zIO5f6etWlZ?<5HY-2ir_{|G;7YSA_Vm0aONpxGQNoQq-Wu*^2NAjwy}ZN_ zF9pN!AQ5N5)tUG)z79yAj21s;Jshagpj%@6-ioTzMMpjV#p)x1CHq*BFvT(%&4$Nl zsc1V}AF@+m$|$#2g7KFI@;fZsKBQU8jo)Lf|MeXd*&VBcFXwzoJfWZKfBKia(zBtu z8+NV08rj2+=q*qO_gl3%z2s$w{cP@~M||%%cm?9_mfVdruhd5*jj4mhSrAE;XKiex z9o3LAS6U&)FUgK`eg~*q?X#?{z9lx7T;ov}@PYVF0%EUR8fRAGqA5z#S#WoCjP}Xw zPpDV1gi;l^0v~Cf^L8^-g%}~I`lgi{%W54*`nKbCJ3#~wWP17oyjC?H)8{aD` zCF!zK-udomHE!GaB#KBAa)M9xxaEaB zILnl?E|{@(uBG{kU}s08X=h|lVuO_{vad1^{; zHbCrri3N#63Zm^U?a6QuRs)ubBQKf<`Fh@O1WIO}i866dKlc&H4$j+D@jswbqi5X5 zHEGSR2jUB#vGoOWG*~kLp@tC6w@TlqX;rcK=c3wC1`4Ir54M*%Soj*@b4c|QUTTln zZ()r@W{~QthUi*z-xzWFb=F=CHSs3YU6#1Y~8I3uu_<#C!_YycG zIo2}hO>Ju5cgF@R99q?dFi#4tx(w+Z_J==8u;cc5$?F^7&=Q3jkFI|K=JSd?_$rex zFPUk@*Xu;Lu|7(zQ!18Z{vc~+J$1Rw0X5LS%?_IGGZS~!^DCkM-k-H2-~JKlae@}A zW;9^86&RxyOAU})(bAVpq94-(E4BK0F+LP7$wz?BUE}=^Fd8GS6wMPncS99jyPLHh zrmRQ)o0J7GA{$QnFRxq#G*6xZ!r>G|dFYcq40f3BQPvl@wiZAwGTkN8OK( zk+KWHqHK>-==+PmMLUT2Zvs##W4#CSk9gq<2ZS5*Cv4Q(J$It*ilTvw;pBD zQ#d5nWQq78`R^0Bx-VEjE!~PXq@5R>STbT8{ft14J(P62@BWKb}E)-mp z2R0NidDjoClcB z;B(Xib~=(Y*H=h@HKig+&&@{zCr_Rr-jDyTxb7rQ%ykdymKK@?M>+PfaDZD%og#*@ zDRvIXOE*x@{X}15brh65u;Z@LB`0O1jmx+qp}U!lp2a@=K(qZ*$zq#0}%Ark^Eo*{O5zD;6e_q2*^Pce?{#jL5h3KW~Api^- zAuUjIkJ7Ug56Jm*!u^snik4AY@O*g*RUI@2D_pXx2%fi)wn)EJ?F>7k_{>ykrghDX zuM*?-c2FWFUVg?8K<9$4Juc`_!%`+Va7c`9T`AY{)N z%-be{0?4Gt^DYL|WilaXMdX~nPyd%YCf8I*7l4I5>+0>}1@~&u`?Ssi(wA8B-Q&!w z-loFguz1J6iD#?-BbUHx#oOv37D+eZm7>ALb09{cTlMflrA#$cfbq*mw|a%%(ZU>3 zC6ba{{G`Eil>$E_wIM{eR7iExlSW9Bk$at3~vI<=bXA-J)k2AsWk6}{T~hhC3s zmD?a7C#VR{SKqzItIiw1+ss4CsnHdS{FRNt$CeGHi(RXuFY;8ub;G}D()^w)@CP{R zXXx>8{K}Wy(#58b&-g9QD&x;G{N!*}pqX+q-q(DcxB%O6fX0HjHZAA}9Plb`*!$@+ z7}v^sak!BqB75`UoF@)EeP)87Y~e=1=%QU@sX+~A?pE^5RAMp9C1m6q?nYm~0#OdqD1&4cpg6Qw@B3UCZ8fwnllX|N>|sW7{A}M6LgPny-i3g! zR%Gj@(hvP%%VKXZDH*Lc`km{@_9v z6qi=>LE9#%+yBJhal*+!0mr^}4@-UXv)_~-0OQXxHd%@HtboRL54vB2O_uIGXfJ4& z*l%M)6$gIj|xsiYTOl~ExmX48LLo`Z%JrlpBHM_p2s$2-fz! z{U|^hpFQ}J6vc$aliE3)`T%SSe(^L4N-%rIyg9ATBX%%J-GFa-9z^o92H=wL98g6^GNQRJk-s_D{dos{8!-7>@mP$ zd{vyg*2C^ordRGe_|PybBTx8e%ynYS9@WoCtk3^O2@klcN^>8#0q9X*kYSb2OqYgv zY|T)?OjoXxy8WYNjmq4ZsX*E4fS9SKG@F0l-$+gCH?gxf*NHz~;$xF_(L-FU-ftcct_d&j1PN|tg-bsd?FmnVbS_?jEFhg zJ}KQGbEA=a{xwYH#Yb#c?@@SAB-ZmQk8U{NT|H(@N{`{#IO|a81@pXb?ul6|w2}C6 zuAtA9a4^J~*xFz4IC=kjx#!Y4z_%<9BFp4)69qn-YuM>Y=75zf|(xN}r=DYwCmtjm-% z{nCBSATf(qa=zpV+|h=XfVzH(;71~OyML6J*EN0g6C7(#wv`^?@Q7Pr<`6W@0u&r} zLX-ksreORW$Z$VWWJRmGByNg0B^SJ7gakZ_C)w6*1QC~Mrh~+lxwku@x?0U4DxNIX zl@TQapCg?1t~V~qx!!;p(=!y>FV-JuJb|3IJ`SjLW7JxWNa=13wVYk0$~pR*g{4Ww+@= z@bxab-ujlj1Vm%tU&HI>A}+5{jbZX&{K3}7jqfTmT-030{4T0u3dvaf_XdAn6y=*> zXFH&v4hC5`5Wex##$dlb&It6%6r&Q;?Xxyh1D$sSxGZB9WgWns?CQkws?M+iJq*Ml z?y=HjX@+(h5s}ywQmdikNw8MZMa^(WYv(GWe(X9rvJM6=Itm9U?!_^Ahs?we`k+fb znJ~RWB%E~Kwk)cx=WSCE4MIu)9CJwkmu z{)w@|n_uK70epKM*Iw`m%(EONB?3ZWc-rdH-vIVg*`(H=&wPfq%^I_`(l<(fd+_&O z#p?4{gFM!+WtinW-2_O}!i~nD4jpZXN2$=Z#D)?ROEelLGo09P;Aki!rtoV163xU8 z5QkNssUAoh7Xfe^qT$5a(=c7SK-79ydW8)&QK-HJq>MQ2Dy|Ih3Aiy^4i!#9^4Twr zjk}CM8j)|_*ZqWPDIT){!~n$WNm`^XrG}5<7WEI9*6m~Mt(KE}6#e;W_F@31!N&WO z5%;^-0Y{Vm=7eG~<*CI_*AjFY(6r-M?0Q`b)E^mEVxEFwrYX=9k$sG z^>d``AbAq14Q^cgtes|g#&?){k8T{#>Io5nS?ZF70cZ(ai!4liY85n&SN-1ubNmx7 z>}-l~4`Vqxa6--srA8SeS!%3>ay#MxTzH3REw;jw6de||tV-R{$sTxBb|paxIqZ)x z=FWxfBtP9P4R`&6%2OwFCrA8Y{v2_@+4s9}#Cn>w?A4+iL8-4wZ*Xkb|Kp|f%0M2u zLbaq|W8CkPZCVnFC~5E1ZlBv<_;_o@zXEb7ut&=qR{U0dJr?*~)iS68vv`5gn)^{H z!Y6kF=_mw@4&w|icu3cMQ;FTl+lbLkm6#LwyNa>ga|iLLd#mnRB zRofjw_kkJI@!hPlehK zJAU)EQbXcK`AO&gC2NCYhm|$LOGSI0JH@G=htGd)e(C zGs2;Pf|6+>H?+W%NxZe#oZG)dz?#3ha5`_xSc{XTlXrO%Z`g0;);_`dcP}q z#*}`jGl?a+sPCvI^FF$LF=MPh5ghc<(J}hE#QM2IZXTu_QzTWWNPF(8oLJS~L3{ga z)rak~*K3BwsfGJV*Si-l6X@pdj7qNxq90daD$?BN+7PWYgRLtdO|{X|FTiUAu`aq~ z4AoOR(YsKvjtjn0Ok)exi4{wIW^lkD(${j4EUU6lP=n?{dvTNR;wqIbT}?$0Jr)BgWXvl~A{4HTM3lwNu= zzpUwap>H}Ple8WiJSQ%)az`~$=+pZ0bYLZmn$Csx)=VCZzDTaiE?^f3LvbSB2hy|`&Cdb*O6SYA!Pr9~su_nRcWOUr=?bMK1V?q}F-M}-Sheo_&iNwC61iQ;*nc8FnmV9Rx4R-E-O-hevFl9!hs9bnbdQ?2ZOj2vJSjuuma`b>N8 zGq~NEY0etVBfU&avcJ}y=5u}aoE`;~hUTM^+LF)N2XXV9dFAHEc7l|A)?mMXhJciP zIdTf}?ye2KNBq5i2%c^-UY+b(VpzW3jTimQ$TWc4brPO%^xcC z<&`#WHfJX+GHkGNXriG1-d*$A3y@Yq*&~4Ls7s2g?upM1bI@H53wYx)4NI5U5_R{4rYozl(xS{%s`j;@!e3@;3gQ}%v0GdJabP$hJ}+##_PhZ&quI_UeysjEY78104B;%b4M*U2WW`sN$bXi*76-D(CAqaD}xArz@vqmnx}sd8-bHyRX&u9xf( zsZ?<&bAD2kQwLze8UR;L8;cFUc+GQp=^T_K4XEr&`DsY6KtcV$Y{qWn>fJ^EJ$5$& z24HF**lW^R0v+2^>bmWqXDycW;sPZMNwI#kwShg7Vc=ehS=IA!N>*Bud%{M2@b-Z= zM4nBDsL@<@`QLXZ9`Gih+9yTC$Tq;Ixr%hr&fE5ZyM&C6T)SzHNX7-?w?S`2GpHih zdC^xPEvmLrqgbCShU8n~MAt2XO}DMrYPk_;$6D0yfa6bbuMN50e9#k{kp_Oj4Cp5(7Sb1*KA2DYK^o#5NSF`^9YC5n?_O5B2iMb|w%XlZi zFXR(KJKf$~H#2@*nfKn)CEv(x)Xif%;pN|}$le9bdhZ}9=1cE}q0LigCo+jb|#ZxTt|VxVPrdpT0cr zMI?t4JFu>IIm1e{ThqT77AwAAk40_`UR)4aWov7o$~sHaJsM4V9nLu~4lGT!`E>gh zv|h>ZNhCIK&$u}4nozCypp;{g>nHp&-mx|KNy+R}!B`%ojnK zb`ip#@B4mFQ|MM!lFaMSf@VtI`c+nrYnF0m%B~jgSuu@)o+C;U6z5)L^%y4&ecU`W&gP=l{m&TvsU@H0M3^-e?z)jooPwpm)Iy+mnzi!Gb6$9RZl%jw<3@? z7b>DO;}?;Vd{wbz_@YCFsd1+k%yWA^b~6&Db+?O60ZMAwUl$dPMNVs)YYLERdK<@- zmcn#ZXd;#^*MAQA2NMvAFNOjy|HdA7Jk#9jQL8myjJBRj-=(Q;i|Jy)l35|^{9g18 z$UHL#sE;+erO+7YNa2(e)mht~q0Qi!^hbMA&7XP>74C`VY3bfz8*zs6z@t3WC`$uy zAiW;CPW4VZtUmo^vm6|IACmbI#uKxq)7(Be>){*US@c!x*eN{ ze@>hDBFUCKO}D~Sl;n}D>jlaZ*7efs88jNmEQ`YQY!f=TASGft5ocP7i(1~@oNYR- zS3@kdZ$9_iG>sS)I+{Yqq{nXq%B>-&k8Mr-=VB8hlTb_dVi*0Znr9QK%&Q^*>DXc? zTsTSLRRDkG-AF9HvBAQCT^QZZ^$bHFX6eUjtu5VW1R5JNwQ5{}dUf}}b|qGBp=>-y zGq~OCbV2QET_1SJ#x?b(7!&ZgO1-XJ0^-^ULg6LcAv9Q;!3)>U&rs-g`k-9~YgU0X^Lj?~D`;9=BzK2M1f(=7dDWBLI^|dD$ z#~}O>^fd(Ca0Q>24PXozPf1!?k z_wNRIHZRA|$qG$^L&yIbgGW;pMDxaYK&-YEK{cX;=aSkJVYBg&{;kEk#K65)Z zE+RV(xTz4InwfN}mzT*553KhoOs$%#O8-jq>@Gc7Q@)9goOCW1`R{jp4&g16RqT+! z^5Qh&&hatwNtlt4okXpt=$xI6gvNuzKU1^!@Iy}nrz%Xp^t}MdM&{5=?d}QkRX9_S zjJsqMJ4g6^&9jpkGrJQ@nh8dyeTw&&BOvBxWcvh2;6bu?n$Gi^UCj7HCwQ=dF3Uld z%{EpASnA7Ld-CYL8J}rHx%GT8RM&)`F`VeLAHI9+?gj@F`G}uqc1<7s?SMX~L(f-C zw{wp~AaR@lGT*CYX?;Ui0}sf0i~`7N5xAQ<0~zJ_!eW0zlNs%2+W4!xd~0aaE++ru zPc9%wbv}1N@}1ZFlmv~7a?`i?pS9c~_3i91WSkE7s1(JLIpEG5&s=M-Q%~<)*9c#| zWU*dzR@?Hpl?*oIoMWmQ7!Plioh$1dmIjkv-f|iq>x-Qo2R~e`^3%KRGjg91wQA6W83(*SNiWV|_sU_$|9?5w8 z$2c{R2|ahhZYO#PE&xhEqE{bf-q4{$avMEKOXQ6oX_xdx1|;gN%gn1%jEwfleJJ~l zbYYqJXbx$?kgfTcwZE_vHF{k5mC_s%spxNF+}UB;Z4Xq2JqgNSsoUex;tuAZV%x_RLG+l?$0>b!wXW~w zL#XFCISIV(_{O2+)IQOO&v$p6x(>T^K~9Y{2I`(aVf_KAN_;yn!PNMUR~cwE7rWxC z%Dck1fqkDP0r01lVy2-h2h|i>!X2kISL`$rBFBlhM`7fsJ z-gp~Aq)E}hpGacc*>_u-&yXyKTbZ);fGL7-zkI~@ zz2}3eoTJK)|JrhYOZqSAR_S;XSNnR`srS4!P~1q`6&n*S0}9^TKCS5iwk8zomBK?K z_Gwbnok220lL%zHImr0qRjU(_dp8hc)|7=+)GGMKGmCojKQ`R##H}*kgTvy-wTkI| ztJ~UCQVyi>_b#afh#9@&ujWrG!vjJhH7vu;YUb+wqBv1|qk>%7#rASFb~Ni|pDcAU znjX%sE_y?IVb{O>eWDVTSM=T`F&*oAMf$Aasn||OVr^$88QhG3?q4I9hvSI@AGQZje_VpJo$cGkfDv08 zy)FR^wsyG``r$p{wy7t!hFP$l)QcBl;|V=@k1g`j>l-$58D=XIS~rtc6l>`DTn9eU z#I`Z77p_VlFez>-m-03fEXB=!w}?5VBnMlV?K=9Ugp_B#JY6pf4SPoZsC{ddL)DSE z(924XZK?nUrG8e`5=0`qc>JAr`R2E8g+-m2*)FC^Eo@q8%=9IgS2^5J6e!vO8ut+M z#&SNq)r=Xzd!W|Y?odw85Dv&e@r8wqb$8hny{|fxxQVBF`0`9yhRcD{-Ds4k7zGd32yT^30fV1~qw9>B~&@`1fBz zl44{6(3-$n2f`JQ1W4l~Dy=+Q$^14nq8rvA+u#cR+tk2Wvcj8Z#44@7UQVX9YB<<& zcC44EII_(28;nqKKqt#vNlz0S@9Eq9^^n& zwdUapcgT=J3O$z-mhoBAa42aLfjekb@W8h!a{ucXTDSQafD@D)Y43c5+&KGs;Jp4^ zHLx?hNX@%5@M)`Jo+UGsYT`CiQhNPi)*XSc;-4R~NN%>3Kj}i(SP{`|+sWvxaafk^ zzfXeUE|b5cKRM#nw-6jmO8;(Io-F@~CGM-@#+f3JE9*j}$*_S)P)WrjJsUw7Rqc-} zhTvnIhdHUF_F$`A)x>}2ad(o3RA)Dx42p11K@ZP z#9!>~xW^zmO+(P;3Ha7sba%id8|M65596)7vquBqj@!U0``FvKS=C9RZ1(xOrr{f+ z!QgqxmhRxg23!AOl<3i1vNYB+Ak_|Z?m#Qi4?cu_aT_mRZwX2gQK=s=2N4_?FM)n_ zx7>^of3xoOlu@}CR3?PTqB&8mo%jI0UV8JX@NT`9&$5;~^2Gs_LmiREBqh>=U^X%Y z15haoLMyrvD%LyGPt!%u12L${E8^Ar! z`&X6`^XQ6h55)xe%V>$jA6rxMe}(e;Cn+yOOFf}%MQ)QXeCu|FzB5+eHTW*lec09W zpRdK*3%{&paAA~-x)bp_U2aN}Bd;jS>6LZ{P{Of$;{GnRbIgsL$|xMnuki}DjbVwDmsl*wrCW^X4z4?aRDk4|&l1K3H*KznV`$_bEA_dHc_xJiC1Sx)_4>MD z63Z6)W`x>wSJq{h(Ryk`z-3nvfJ!R%_oPFXgJ?^LG+%45Tbee<916$Mnt(QSVhFn+ z52)_7)2Yx!XWYLFu8!w%r~W+il8`0dEi&wX{@AhqtP)0<39;r=mQhfJ%d@T|fS*K& zRS-K}gCMrO2Wqxr+c~O-3X{M&Ph*FR*uXx-n=j;Q;J5~suK(Y!L_8c&8EtSNf^ z&b=X69ET7IObE&URez{{R4pI0Y=5mfKKX`%HX=O`s5`Gs%4ycP%?BxT4fM8Ri!|uk z>r{K@%>6t0(IX|V)#x{bJbk~(y(-=@zf>is&-Lg3vfG*yS07og{H=|1^fy6hNyS|J zqN&hzUU)5(TsPLQ`U|yYn;MQoo5QOri!S8`^Wbl4kk8>{if+LWdVb;Z{$PPR_M1_- zzEBi4sNI{%*8*~ZQ*OSbCQkz*@iRrb39J19eaBkM6(JFGgR@PAh@aI5vX);7x}6}| z%dKv2RsWQGC3R_T#UR+*z7jjoVVMG~5LyODoC%G02i`9lOqi!j4iC7`R}ZN=8PJm|Gs6vNbYOxpr!tXEDBF6cs z)?SdG{v%tnpKGAiE8;Ws>fB>B_=tR&tffZ z{?_xB3PUspfg{EvMuj2DpO8sr?ueXI9-z7p36Hof7lVk2*E_8y0%)FR>AP}xGe_Uu z_j&AQ^fB%DRw=w+rxj$!R@UQ>ch~JAV@3f_^)>dUM!tIH0uCqQiEWUQA3DNOI3S}} zfSAq?y|>$0j>l0ZoVQ zlL00@LWzEnlH0@fk>p-Qoyz17S!voxDEHeDAjqlmu}xPG81{?5jc?zak1p$~9sDS^ z#b4xiZfVyFwz=xr{h;NrI~U1obzdC(-GxYKj)B}rxOvs^jKMb#~N6a%Z+#Ix2&>mVvDU3#^R~b;}4V*IVk^9 zN@!?*#+pvW_T0C86PGJGWwv7a!_Xp4N|aHTFF|j`6iWPY=_1V}fNj|oneWAdFP2s% z!?q|zlq<0z_4ovc@6AFZJ2Ah_K$}W(xj=+p3|o8ORGOG-)8`V%{M$J~%MReIG(#xp zFw25@4kD%kxSbo}XzI@LF^ME!a1%gnSjD6(Mz*g#A4#mjX|RvYNIO$Ou%kDH@5!eW zAOO#VxE!KEV^M2BvHt^OG`$*a@iOO+75PeO42j5*5!mp~Vp2T57b>Z&B{j-zyGOApoUjTS5Md6K` zL{-y(Knd9K#ed6>n>!X(-pDc&6(s?CWjj>`c5G?tpQPIo1E^o%*mvyxTH#aCtHp=6 zOTQCgRzgltp(%R#f|&c4z6DpEJSKVKL?6YJ8lUU28GRlp@nc^8Ru9&#f98|4?PRs3 z%~J%%Fvw3Z0CNZ!u5hn26x;GapdP|TLt2eU%cV*Su+^&o3YE;&2y`2f1e+e|RaZWm zr}Vi1((Q;^0#Lk^)SnjJ3yK|NLGWimYguG|`UC8_as(arp$Lppo7r6ni#zr>i`z3} z95>P2gvntZ~jif zl^Ua4_1`M`*C|`I>A!UqP==d&rwrwL`;N&8HG>17ZY3sa8+cpG>(yFkl&*(&IjBGK zZM^c=HdY^2ViK->j8VDf6FR-bb?uWt^xsD_JhyxY?N$~7KVs&t%0{98Ye z&1=S;4}@9<-ctY&1TOyPi{e4HZL~mPU}`e>z_a++PKrwUFYaLaSXO8nTzIjMSnW0z zvj5xhNuP=?8yXj@NSSXs|Kp6VcJnc}jH4;w;Jo%YiUbLM+HXVbdXnt(0?a*?sgV$1 z0k&H9%J+o`($>Ds^c4?X=}3lYVyUDQ5#5owviG088&;6{-uRrT!A52xx~8Vdqrr#| zxImsKml%Z`xk;Y!(6rP5PvaaTmk!`FO_AM}DqvG%TqmkY`smH-SYK;G_^N zENTZ=ee8F%gw*wvYMfxEAPp*^heS`)4DjdE0IM#0vLWee(*#K>BtT3MR-%^&Ds!n) zDS&07MLOzTUyFmW&7q#(LRcfX$T`!qq;0NKS9AiWb&e8^4X8*^oZJRQ^1vTSbk5TR z-y9pfWRL{SEI|Rk!nx0RUIUn%(M#djnI8FWgKS3msd`*3@C5~IHP+m)=VA$}mct(v z3Rl0AaH_9+RS!-TR(|wacLd*lv3w`tB&}}mcK|tDZy3Ca-6A?Si}?ecUggYZCOVhK zdJthGQ>Hy!uG$?`#Uuk~)WtEoUuA_7Kj@A1s;4P)!NZNnqkjDZj(~-2b8S6c@Q+Ch zen{?l5EKGbvRTK1dM)Ze@EugrbvqXfIi<#u~)NsBen zUijn)61-x=#x~;*W+m>ooqGQOSzHUHpQe*6?rlDWNm5=F^|8}{?Mh^O{F|*i}tSxc&p7ykBSX)aSM8!&arFHlwI(Oj3&@bn7 zAl(Ga%DrugDx_`#8+5A+?Ydrkn}#FS=R&Hq8B`5v2Kii0iG>K?3-1yFCaQ-}@ zelbM&3_W%uqYm|W(~DTviDx9hD#&J30PTO(ZMq(Qwk9nYV%hLby~AOgLLz+thDtr? zHgvWmcK+70M1>0u-@GN!!QPeZ7_A_IX@@SJMzkUQ*aYla{w<0;X^`CMH@s_m)WCif zRqDYV4qrMI^lgy-erWmIJ1j=GRP+?wD@?d&;H5V9^&~mz>$;u+MhlXH_pe zHq6!mc*WyPOO-kr*%w9NW4(YM5=ex{rH(JtG{9g zvN1}{;ipQubC01aBO7`jea!JN>~`wg(Fbr?sf=Z0d##)g*n3IJnZJi0t&C{p@t+D0 zEN>Ad&Hr+CA#~y33az@A(z(|nI#$#RJeO_~Zzv|_0GZj24Qga&N93(~mY@D%P+dIs zF64_abI=*XPb%NiNa+3S`cHc@ayA}5C%yK*?!*LXrRD(EC|aU=mT(AqyTUO;VjI(6 zVg{1kMW64Y)+)Eo_^=C4S9DgaREc79_~oSj^M4UvVMuw%tq={T;icYP162Y)zjgI% zNRoFyc)a(_Amd_kREB#QJU;kJAKO3#<$S%*LRIkY-lJBxoCh%#ui8?3O}K=M+>-g0 zR5?*pFEidJHVe`ZMB(11-D2e&@c>-ZLB6&c0H}5|HwH~I?Tl}wGQ^*eZS9Xv){={# zCuEW@yMAkDhND3N={>;W-6WCWgW@MLbD?jDS^fyJ79FUuFbj3;Orx1Qpt!`{tO zsC7P4Op6K==gD)x*9%lZ-lFFvYsld{EPNd*-4!*+T8Uo#87pXO=%!_nu$A6bJf*Y5 zM*w_NM*8@rp3j6oeQGZdwIS?oU=nTFa5kXhWEcbRKb^VXXs~-v>U@{uMe&Gp4^sS4 z7XoONaG3qv_g)}QWPkp>H`j;RUj;?4|FIwXv&NE133S>i`AN}5B^Gt365xwM6^6b{6mbenIC7}!1JJFy}Jrjzz5aS@~lx$)M zVpZ8OE|Am6Fn8B@$>gDA?d>E{TZ-1|+Lz+NEj`(K-DB!c2NYO0f-co?ZMtF3Gt+Sb zh%;xNRrO)FU#zR@(QbRH9?;@m{-ZsS*|DgR8oP^Q+bepq^Zq@G$6foDI%C{g!xWZf zDlD^;&m(hZkPlVUiFLeJqjG0}450LkzYMz3aYdFx-DvT2F!{Xcfo-;w-@W^=5;()K za-rsh*O&Fmm+yMs`sPTsmvTa&5fXzRn>Q(6jibK)m2?X~L{s6dH+ehR_+ zY{-t(@JycR5Jz>t!WmwWZ`tyTVS`}D<})H32m1UkzDov>c*q5qe?*=A#Vh`qsFGb4 zi<%3tj3c-JwhXxs*K<}e!Zo~ViQ9hbV}(`62%Nhx(}>>0@ZTD?Nd1o+8tfK5skI0@ zy)Gv?8(h71h~umYf9AnlLMTBz=&?(>oNBpFnCfEu$^%v4i+6mj=OXGUL~8<%&gz6V z&!C}dvjlUC%wE-7E_sifaF#VrQ$J+^%J=B2^Nx$4y>++yzUJ?=+gFfnOOn>ty74*< zbw-mMh+kAtY@`2%=Bbc?eLx+-Rwqfih}Y$3^Z81Rw6;*Hi42+iWShC2=S9_C+_QSB zCpO)w!H)iex48V6*&ZM0J5Zz-{#$<7<#3{XKg?T(&*bnI(>&glEVAe9s4Q%gJy8U^ z-&(302`N|2mlinG0=w7!J}%s8>kG}Bd*z=_qTGy{-&;y9tCf9i1a>F>ee~`_TZ__H zrAy|@%q-dTV_Mgy`)@EJU6}`5vJpnWz<)W~afPQ#FL(_Ilug-71KHH(-@5!p;Om?_ zllAnl80grtpuVMZS=+};SG{J{!{6~$r0(@?oj7cnQ9Wc#NT-gjxSI#Gp^EA{a{KNh z>>^+wWIO%k!#>Qfl;6Top~;1`ifc&xz)v}y-!VzW&D2*zK8Vbs^UNl^{Lx-+=9jQjDDQq*qd?nk zHU(b2cw>&`4z}{;^Pmwmu%Q`pn&7~I6&8Y>i1}IF!gQbi7cRc+>6y66{+|^Cl8VXn zbZ^DONgu_nwwSUL|%eTsnWEzA^Yi{YSlvH%P+&L$}+U%4kuUo*3h>L|PwfcY19W=qF)FKE2d6_yy% zuxpipYNQ9xa+k{jQLdwujOgll*d4I?TeMy+6=jKO-CxM|L-n3?&t$v2H=>v_wkgUQ zd*Tez&D=|`diCi)q7kH`7)W7#?wK&xI4C=nAMNjl)!ozrFUK3y8gCza4uj7d$SnJT zjI|X5V>&5tV`KoWBaZ(i!l<&w9^ZD}&kmjsVmI(5!$-O&8nnuefMadg;43TaRm2v4 zvV>g)7hD^p!s=U4XC_e9{T8r&*9z?qZmV;#@&zkfEVO5%Mntig_kyNC3~RUfvr1yJ zj8Da%0_>E&78c+0BO_LTo zBF!VmEIOkfBw-fv?x>0$91L03+sCDy-A~iaV7M9RR3`nCE1!kP`83DQ2io+m^T|iZ zJ5%XK{50xddtCF+Zuffo)Us!Cx=oEB_VVWmN)Hg|xs7oF1p0!geD}rMEUNU29-RLf zs@0NoMlrXYU?bIgC(V1vxw!P+R9#I?t4@}aAu`e(S1LUBL2&+Bj~riF-@t%*fjJ*p z8THz1RZPp^SBlIzKg2kmt1EM3-qr7=sm+h7H>tL>*Q)5PrUX*BZ{U_L4N_Q6Kq~45 z3I)wo2KQW;XLv*ZB;Me<8ynHuMVk$AArJqY`gNz5A`xtw%p=3~p}6FbijEr&dAD=E zA%?+4gnEabUlIO#WZA?Ihro_s)N^+M@chv=j`?-_`qJk!W~&jgr%Mn%%nt=TQ>S4t z4^|=WCz)o1XVZhF^NH6*KHNrFS?O(AHFoHqw3`y^`H=WUaOtOaL*dp~Q#p1j*eZ3+ zZv1K!hc{F@=)pBU>J_jl$GH74LG}(OUY9SQ6Ym+ZTN0e(&#Ep3Q|H9zCWM!7{kfd- zO*pgbx4~V+Wj*`Tn)s>0CFi>#Lxx4ox9qum#i8-(r$6`&p6t?_l1q|R&xY_}8LLig zW-n^Zg1OBB`nMQy7;BY3&I`ruW{|j|rf;uzfBwCWvk>=7q4?*tE2GJST8XLaCM;fmNv(ry+k{C(=L-%RQZ6g-0*+RUMET45)Brkz zctVvKDE_!AoV5oXVuGlsmH`v}pqg-#(t4cyzQ9>*Wi)tm^xfpPgnoGp@qKr9o9UMC zS3n^JL8Xzgz%6bQm9DivjM{z>o>VA_RVCXaMf+}vyzf{|Wt3k64VIUwmQGpU<|*>f z8#9}sys<+thg$`>P}ZfANmO={0#LSB;Mu{Dl{X8U{@TS6GKU0S#?2V&S7#wYz4Cs#cW6y}SrDz%QN;NtdHze8R-j z?SvYb@Z?m4Pi--Kmrn(kS5SWySm9NL5})_^yiAkXdu*W|Q=T~WEZN;=K+Yu>L^3Mz zG`!bb0IB`DV<7tuq{1FAyC5lpepWtJpdkRcBaOrVt;+Tw3^$gGA~ffD20zkJ2P>y$e%w#7$r;N zo5)6K+F8^8D7dq9OlWl_%!}Pnup&U`y8*1#QS%$XQaquIOODBrjUR}X>ZA?Xt3sCX zBH{@iWQw|9f$)|9N~{$H@e}NoEgq1&`Vy}{k=xS_wpwGy0_|F&3E8gIXjR~F6xwgp z>j;)S5Qvi~mt%3^q$z>chJI`?RJ)mBD5^!nrQV#l5^q~1Y2(L0ig_ox2DtS>%3m}8 zZfC#2lz(O|r9vr4J~%t#K`EeSOJOi^pyHbdwc<@>Ti&p9x**UGW&^M~taO8X_Y$CG zF73?iRoMWmFX-flu++_(qB!Tztlce0hw@*WZDU^r{EJ5Le8 z;Kr)@S4o|dgZwM2>)H%CH7#nuO>k*F;pTr%K{r(;JDwQ$YDD49{K)q4cmGH2Oh>|} z0;H8?q49f_xb|;M2DB3C31pKwl2a%-r@E!Zg7Qj3pA)2yvwe~*hxM8Eih-D|Td8@!I;I*C`N;ds(yRym7Jb=9i!_Lpteed1< zbBE66tZNNdlE94e-k3nei=b*Wj3#>CZzVa_)(BkUZgBrQX;PU4P;VLag$=_b0XM6g z$l#YjEjJ8igImqMB$~}F1(c?vE*q~&4sD- z4oP>6q;piNy7b6IygcB0BRKR|0OVVY)`Z=wgf~9&)A5=>Q1sA~qHW4@r}>iU`t-#A zdi46}`eNsLSnle)`Fi7e(%qnk(^W@?&(MZxjwph=ADRLYkMcRTyVweVZ4ats5@N&IZg{Jf zIKv_#lkggZN;dZ{rW#tLKv4)-8y7U(B)57Nb>`;(4Lu?AjipM2&3zL!8_Hq zG+55e1AhFBB-X>+7G2J~`WO4Urw=|i+GN_Grz|M3v z6U^a5*FAgvu6;y>Culjs{pmSRTsz;gScr^@bvyWQ0s8NqDfx}YKZct=JvlZjp|f1E zaw+-bO)bG#n#eb29O5WZ92JSY6C2Xp;3S&$GDS#cWGhbwsKqnt?`6q`tTPqipy#PrJ^5w%vGX4MrUN1*i@> zO_vut?I~Ay(cT}kdsdFk{62QsfHtNS-#l9`IPjCR@`Fb7x9DtG9*l@0*@h?(TT!Ff zaF{Q++D%Fww#wXOUZN%@oKC_bQ>P;>IhB8C=4TrPB$WaoZ#}&mYSkG<{&emCrxXW= zJ&Y&-dYBYK`Z8XqA6@z(7?nPb)j|0Z@!f}iz$1Xdcr|q=;mP@B1yAH9?)zbGi|dDG z8LNe{-swiT6?A6@-rMw87S!w}44IQvhD|*NZFw0gbal31o`@JLiyWMZA_G{NHh&&_ zp1J`|g|jJ(o!st+(swNV`)$p2|lFuKD{r7EkpZ=7; zjB49>4F+!H>vITxp4s{~lkSpdM}_>9BVf(EHgo5!8^Y)X8Lc>vS$m3l7fUN^xRn{2 zY7Vjs+POCY7~_I|jQBnzSgeA+?3#b1Qd|cLq!mbBr&Ydjv>x!|`!7?T3G3TdwhQ0{ zPDnAFC*l$f;JV%WK9GJA%M=uh{+G)Gr04c!_is}W_ZTNyDssMTbTWZ-J6KVosPh%} ztqv8;0>0~!Yhj&GZ}zT36mSc*)^_M6T7WtZ>9G%I=f{22+GBI3H}AU43Uh5Tb`x4j7hz#%oBO(DIfAijlu>t77_qG1Jx&`k?lgh17R_LEJFOyR z8Xchh32Fg=Kv+E^Y$||^P)W~IbWi@0Mnb+yR=^3cA2~Tp6-@MQ|JN=V&g%D*l-!kH ztxZ>si@^Phh+$J{D%WVcSW!kg*cv0Lc!yD#Kd!(Cx<7g#L)PpZEGWK6HT zX)k%2UbTH-&drb^jK)kDI={B%NENL;Gmz@fPs<5S{OdM^20A_(GFHd`tcN^>Fh4xb6YnXVr*$sp}g`n zpMSaQ&#?evI@nPHxZpZ|_=nMyvhA#7Zz};+a`ll;!bLS{?QPwg0fDGOQdEp>d`0TK z$B%&$pk&4u${Mx*XOA#qNx8j^-IG)l1EON3oVM-~tfh+UHrsZF&DA@#y%)RGL>U@l z{m}4JCXY`0Ecmq1g2N4i=1bw97ND&QosPU^1gv3X$3v~*WgTS%(7h>~(hXprIqTW8 zXT3cSTwYwRj}4`^%4UW}boq&+dC0X(O;B z8}0+0N4&)De?Ec(z1vo(+4@LT3?#(&XO&#HsxkG|K3$*Fhbw-}`O=%YxDUOPj#NNw@^c(>R zUAVMHX*0z(qtj5LvPTBZxS`Ek5o{kO_rJy(QjUfhfxYU66(l+m{prA_7Y_VK#EEK5Yk8C`A z)@#DEdzJrsa!Nk&L{4oht%d?_l2Y}T)8at(^?9^JwOv@YN$|qa`ESjB=xOSVYT|TM zV!Y2K#JLyS62ty(QA9|ZVe68wLtb|GeU%vCiBj2&G zaoqvHohOQbXkUB?RnhBddCk7my~`-d<|9zQqY-~@hJRF(G2mwD5F<5^Ksw{5e{Mgy zvg|h^&V0xZsP(S0O{#ZW!KolZjS=j)!a-%SG+m)-d9heg_-!l7Q2YyzQ3Xv|f?P18NquLLZRSG9p|1PAyqp<0r zjj@5Kt46z9|9u48DHX<4%s+K_IinSHYX0;Gu5+l}3AATlW}<7Z1^c}sH9^Qm3{=e9 z-qdgYTs_g9`mA#6LjYknCg4ZH-Zz8o`!$!*RiB%H_~6QQpH~r$A?QR7N3p@-XL%L$ zv~uL2dzsSwGld)H**1{sgLp2V(7KeTKQdhW_(J-VAi4CJ_7hG#yHQ_SZPY}9=`f+`EHbhkk>RCa|2 zK-J!ek@;j9WH-tLP-Fd+>e;6hC=ZI-gCyt~3o7MQ%$}slA4+)o*1AVKmiCykmxbE$ z^q4+2GzWV7$QK8v#I>h7^iN%hmfstm?D1`>F>-X6Y`apjc~O-Q(X^;{+4hjt*|Zm3 zlb>NR1Wo)5Pu+GJ6G)O8X0B4PQCVbLH7je|ndrSz0BxKL5b)~16I1fK6TPk-d}k5U z1;gMT@}!+%Y#{JQ{7f=5l}V^M=4UuCa{i?UT*EYZ@2^axHSMv{$oBfSS6_zwW~EH5 zSw*lf-MQffGxH(vkvdkaq7DVdn&C9ug5iYh^V{BG3F3k|RF^z#=_8vR?);q1+DudZ zv-2@xbyPDTr|}sa;O_QM>=c~HWtuqC0zzBfpRN#_B{_K6T{UtZ#=*573dxN>F3u3(;M#THg+lzU*Z)$aebd#Nw`=zJ>9xy;p1##%RyY-b|<3 zyc}GE6P`}K^AEP~s#6zd%(&TGASrk6U@QY3;~3TRen>BI({`n<*qNIdcrDxa{H&+o zL~84C)6MJQmsMX|yY`4LMumnS>||0nah1IiiU;Lcfp7(6!%_DdF+N){x1SKYY0nKFX{w6ONdxNevIsR_>2lcU>+~ zO&s4qPxc;39lI|(MJnZKhhz82|la`Tz9xHI}L;IvP}uFy%zToauRh_jr8CC-QT zp6hQ0eSXSc6({R+9pm(&Q9>2!QV?uJ-*b(Pdu< z@5|g!+Qk0X?b7@uH6Z?u(ME%8pO8^TtT2V^m6dPDgp=G7_G+p8Jw_$)_l=K;m8-{x zg79cbw{4T<1I%y0w{i9O5l{De(9ZM6ae^3AJ0{_vq<>!d^KX`_CTO{L9Ze6-dHBE> z-wqC-&A^yDZuTm)A)_|&4o(1=E`V_g;In5feX_N0=mswJj3&^-A;y`$OAfuR&?);8 z&W?=UIRh-=D;;y-?RORa1pY0vH|E3)O^ZI~5`TwBcE6ffkCf(!IO~)T@c!nNG3VK_ zV#q>Ev%fI{6~DOnptrb%1CY}{{k)&(y$%1W&9RCro4bASy0Yu@-pE`}-eqTh|86yg z+nzy<-`H~V`-uJZ?`7MLNZ!xYq6tA-kH5!z*6+5%y^rR1YkBXF@v`b6MI2tq)M|as zD)td~)ntW0HPIvx z0b4dUo3~Nf{=fPKcL=TX`w*Kg0_BH&E7}nOXmjk6l6ig1q4O@`n~|ET2)-DVTJU+c zg42W!%|H7r2Am6nK5_cPph3u`e>n<=IkLyfAt@ByM%>LXTMZG@JMo=@BH}V={;V&Obs(1Rbp8IR!!! z8I9^7wXANv{0LWg?JApz#PD{KU>F@<>U-#~ntd$kh{7LfHAn+n*Cp|x(S{v}OE-Zg zr3jj6YQ#m1e{2Y{?`wV-UpGpEY)aDrI;VmzIf3q8J%Eq4{SWhpKKDi8C@0S#|H<;M z+u<_;;8iuQ52S22DA?>ecxBQO`^qtc*Sa}O*}~vq#Y1#ynH?FqhYk^ZE#sH#M~&=1 zDwx`8BVZ?q{aHlgBmo}P>cDBL!42!zvxLE;0!O6A?2$z*4L~l)wcpVdNq*{Hy*xhA z9v*UhKVs-d&s3djIh#D0txaG>ZZTIZH{4g{%q zR0xolT7JUC&evT$J!L(yL)>7Dq%us}S3L4VZ+NZFWGr;7VnuPC$bJWBuKoBQ)1<6V zX6>!XQ7E=ACZlcFs!F@q|v*LVhhPa9F-WMa?9C&WG4b(I*WV z(II?cn`a90tP3r%;3H=f@8I(7tfgZLN^7ZBVb?ApVY*|`92$=(eP(m%br)k5qM7OT znM+^1DYTqDH(O_}0TUZ;xg05_NZk#Xh^s5nGF9XA_>@<%0ieZJdg*8&gr_Xf*0 zY=J7WsvohYqH@Yj(eo#f8nuGnk?MjHY&o|gG7%hNtF&@G>5oTG7oN-OGDk+8S6&3L5-`wIv z@oauje*eSCL_OGgD8m$_J#;>?^w)HW$H&)m%5VFh=Zlc4&-jKJfky>FS)TwHAi~Nq zl`mBI{A^CZ3B*h$!KNMOYOL@Ef^^*$Tt1PhyGL~H`~m2hVd`%;dm)C;d|NJ=rUpE< zCS2zW4Um1=RCKjO`e$3`P060ZpKrxb`KdIPP8y@{_y7NFYX&6fO4VdH^ELB6-)WiC zOcU!40f(K_aPR$x|4^BpRBB{iRZr_ft|%WLjV9wJw@+`$f(hyweu5AQmPK zf;L7zypJAA%14FkwLF5=ivF1Dmz#G()d)WB!8!=on{dq$DU@%dNXcRhD9^d~vj=Qf zW}T7&&VI2|7L=77*bLP(Vaj!L`L{>Z(?Q#BGdLohz7-`zXGTbd%-0<#3=@79k!u1A zq6-NUnD{n`$a{uO3t(i9?}ycA9lXl9h`~^|-phie)i9+BC)oaph2BJ0r?F3q8c$A- zW^+XRqwq}a+>NtG9&C`ZTy11%{j>bghC@_2jbJOilm2UeAw!Vao2fO|e^Pj`WmG@; zk$2O}m(y#aUU$OTg>39wBDy@!&w}T9tIIM}6w;h99Cs}SkJQ==P>DwhF^(jGD+rsC+aKRkNBP?y?B*cX6sLrN} zCNc?>=FA-kl-|UPxthP{T3P}D77{Vx`UI4dw~TMLO%InzJ0-3+_TQP0R0#yPnS$BHA3Xl>3yx?2 zHvuuB3Kv;NeiIx(ne>jU059HeGSbnr{d`G|)c{E3z5whtZtrdRIear^FA-}v?*=&7 zYP0R%fw36XQ&VrQA5_5IUhs_qYRZn}u6k?jm;R{#q5NoWcx!Fcs|k({&1kqH^I&>V zDAu$g-6Kj63vYShKS7VE+6~h<|P-rmskWTdaB|pP08!R z5A;y+p z-C3*$&O7Uyjy|SP>?x0_bTuXaI+*=7dWAcref2qjQhd!tir-^| zgl`-oV(dA`XL8@z+t&HNATOIBuSqKkV3YIWY##r~vVi zWI8MG#Rc94{0sOl8UV1d`1WfZDPA1`E5_mgH{uyDT5A{}`I#24pCLAxNh`BCPS?Zd z55N}6-hqD2-DaXaSU46cof*LDFO96wr^B)<&68cdG|3yIV-YySJBxPiadW=?1vC~w zmW{1_93#mvg&eyCtOPXyjX^W*HchZTl0=R61P-)}(KnuLfG-qzmUv5s9Pc+=TPGP; z{#R6%m%}CQA7daDR?2ac^IU?n2JGy$C}5owT<+q5ruLzS z;hvRMbOG)QY$U3xi40S^K)2;07hEplCVDpo@;`(hu73$z*k@5yYO?rOAHnfQl+tzJ&DF5qhtYkHHyrWzz=QnP;uP z95(<}(gps#u71cyl(?{-80K&S^k0(WYD#Rjd%Sj0>o6*+ntj{&!cCumpux%|n@W#x zf;!MUu0794@$5VfCq(poYVU7Kk!dxfHeSuIKjqS~F{Ge3}m^ z7W%YUeivWh>YzG1B1q?%Tctemi(Hr)Bl%Ge=tfjs&4tbl39ZG+A^C2`Efu`;7}F2g z<0HeB`qCnG#L10$W!^lr$42dgPh{@ml|8#8g3IZdr#K=D9 zptZbGl+ke5kuBhK^=Nl}AcsEynr7>Y`_yX6unWwpR%0aj4~#?hh-A9;bB!2trn@GB z_fi~Jd#~(9{bk3A4#v*jIoWHl6BEKhHwGP`pDLuMLPp%Ns zsv@J)^4(^T7t3kC-%KUW4#$~*OxYpEFaC>UUv=cEphRt=U=z8u2W@ZwO@hA0?o=PaS&^>?)GE@LzdUB-7D`GL=v$REjZr@%dR9 zjUnor5*4QGAEH7Pmq2&#)#h{$kH zFp(tTlfJhf9A^Q*#=eEKF9d?Otd(P;vPHvAVee=rIrFy61MH5- zSbIL?iseSfaR15~EYSNmT*~)YP`I8-w2n&ww#s+9NO=m~YQNwQHPU+j#PKC(M+xtD zNe-1XZumFJ%)5BM>P^i2zzx-B#B}1tfLg^zEWO!AFSUDf5aXFMJnyh+!A&H;_D(vMAFjoiD1i*wQo_tUy{i0o;NrFRz0kkGweGh} zF!Nv~KX-oYbX-f0*CFY{#0A5Ue_B3)C+B!}A?-3uW&M*~34gY41{9T@7q0v@hwswZ zcel;`aU2s*05JKD?+idjqXe``<0#b8rRw}c;A10V$4 zmz>76Gvk7r6DjFMafly+#5KL@!q=pPg^UGtU6+I`$2ax%FUsU5kp_{dx;GrcV4tq> zV?j*c{%Mw;1~#XbzDeKRgj!9{i=jQ#`k4*dAEO zE$gjsI_(;5O9P~CSJR|UJ+S(jvNOjK576X^l(WO$9`ZLs*-tQ!g(#$J0QGlZMa$}K zysXXk`Q0U7w%1KvoRzzaX+XZ3>&&d|(Gn*R`zmAjlXVZ|?ExJNGw)xC_uO%KH`Woa zzJWiy{pK>w6|gvrJ7X`!uJ8BO))bL1cPDo4ME4F+dn{hT+Y+p|g@Vp1O6`|RT0!pM z)w9H4N(7Xmk1p;|%p|9{=hxfl2aV{^JFU7xQjcB=dIJGWy+ekX@Xo#4&V9W?r1%<7 zzIADp>r-2{qXTLz?ROc2sgHl?up09Uc8&)CheD4zew6cQE#7?dEG8y@AOtEw>SYY* zo&HQJD~WY?FLA%yNZ2W&tgBl*!oCyvfd1BSCn#$K2Slwv)~aSplFJ7Pg0JNB&S0M+)nF$dxYXS{tSj*bBNMKsWBc8z4zo(KJ<8vJn5Oi+@Cn@ih9PJqh#1H2h0oAJ&FFJ`dF%{O6lC6p-Z&^?J zC&>_cB0OxPI?))*-DcxYsjtA!0k6R)K-YBv68y|hDv52LcT}i34yyn0bl%}?{r~@d zw^|*7DwV`6Rf-^?wQAI^T1Ac27PF|mY86FEP?Sim)~vnvUa|My)!2LQ@jdm+%d*YokXZ*_>68;=PPl&kt8MmO{MtvR{qmtC5f+=hy{;Xr$AksDCATl+v6 zSe{BdRcDszh#;o6pQr;3HR^(3f0<1m$sVnh^rPD8fXz-IYYuG7oaIO?XzxJZuV{1? z8M5k9uNTQaRzNa-+x z=pr97ql+vm&he~Ef>v4qEvg_4AmoRR{LGfJAcAj!Zzs(80fzv`F@6#P)4hWHnPhlP zfZ7pS!+rtkvF*9xhh0Z|UO53%J10x#U2VkSSip+OvWaoasmvUPxi|Kim%7I40 zD}l1b)@d*+@zpFD7_xf)3XBhBCYoB3C7ji8`XIJs1K!L8l?te1B+`zUL30=|P3x`~ z0#cN!=$wIwh z)3faRLzoWWqYqe78*im;^;D!l6`KhxhsH$+$f-y0C%z~IoHU$r0==ta*U3J}ZNl~X zPOWj@{OGAs^4xdSx=VUQV^HDw-`!+;3)0Ym%HC%WQxJj|iTl`jqcvl@Rr~6*8e9iN zcPjzexmWFKO}xy4X@!BJ(>0&o#(vpsg>j*%T0d*agP&Y>@Ob>%YZp`K0*sb&4FEH? zET0let#f*k)v_Y%S(!PFWp|( z#9mhR%4gBHLSP=|QANN^?I^MOTx+UFV(={EHF5?39&(rpHD6^mxgk}qyN5iceX_rK z)i$mnRCv=n&X$p)y@}F3Cz7!JV6WQzQM=V^_(*-X-PSP=pGe{Iv~AOg)=x^);P{UQ zQGXWRW@tdN`NDmcnVidtAnwK&4Eyjj0EVe~$=g%UdK*5-ZRShrx%f8Y872t)8ZZeo z#)4Q$C_~u|saKOsKy_h>gWP!L8pwNtRrA2+df>>8F1*{^h>c%nN6jnxg`S0hi_mkR zu=@l7{_ip`%S^&#fSNe|&!lyXSa&02R1RMv*n9@8PwG$SdCjR=J-j#|fC+T7N#7#I z-6$!V+EXHThy_zSvE+=;acr9^ZTh$}ZEr^OkweL*E=dgAs8nKF zuTc?acY$G_Xy1pljTdM8?>3E{0+E(>O+S|NV~}J+Xx~EsP(QXZey`W3-y&Z{cHKE} z0;{`mYx&eF&9DBaPa>Tz=D_Lj>^VF+n7YTXG0Y*+Dewh~x?PoIVbhPe$G{5AdLBY* z@C|9MeOy#Q^l-h&0)im^@U3^L17gviO5I);D7O}#Co%)^qND7Gedyzm$$E_FWRiVq?mh=_M;6nCT;nrG6*%Jv|L_kw zSfQ`+A3Id3&U>|$T3E@)0?Wr23;e?X;zROxXQd%1 z@PF`?A;!$1;!rfTcQjA(GUAM7J;`rV^TB2CEVr_$(TWI!(R|!Myo(OBbz@g>ohczp z@tF2khak2Q@5?9Z zXoR*J;llJJCy>k@O!;MA)0fQtMY?SQl)r)Q?*~kiwwIefMZI%a*-REr;ltG^+e`na zFY*Qf2<>>wNi=28d{<{kREa3We=2f^i_;06)LPV}1FH^JPdxA4U*EC{EQnco{^Hg}6VBrY>wHpnc^{soAazC4cvasJOG067U$Kd7>q(>pJ z_e)hs7loDCJb7RJR*y_Gl-1#+3IG#-pelW}MI54$(yr~sB2cm3Ed%=tC{!@a)IZ7v zBJ!=4SVy@(F&fLMI#E~YaJWz@neo-vwj69cOMk`(`(z^I=@W~7AJ758c&KtlV}3Ds z=jyE-{iHX@UuN}!Oy8!i4!EF4_t%I)j+3b;*M|y{*VatJcXq4H@`S0mg9zN+3(oio zEqWev_!bbe9oUiltE{G3u;jc{feu47w6*>r&ROAZ!24C7ot4rKFmKfYEMRJ4a(QZL_o5EE0I%0eDs0NwGkQROZf3Zue#r~Eri)Ph z1KdH`6LWe_)+?45ozy-vjX*gs9VeG~LZ>R}F7&^Xu>*l44S`&P^h&zPQ-Hp%jT%2<1$O9+rmEpf#=Z1%A!;$V3;u+mKysw%v_#_QXAVW!*0MVh1PN|W8vE__H6^ZUTy#~sw}R7bLhFufE0=FjpM9?n%96e9qMnZtBNmqf%^At zVr;I9DjQM*?&LQk3%KQ=Lrb7Kdzld_5-Lfbq-XodZr2TW%t45-T?gX1ie!wX3vr)J z@(PFE{RscEETFI-iH z7`EuGK91SD3TZoH^LyC>MJpg1rBy4$L~**H(P`GpC;)j-sn^B{@qbZ{Rx*?%RM_>{ z@ba8|;^)?N1V;?jia~~CtQC%n;OTJ(03skQ`h1o!b@W`szEL}8d-p82vKNrOPbL|I z+9a34ZZo~F+_ow5e#%3V?>7=SgpQE{MUPFTd=HmXfnM% zBj$p+c!D9qbnDID&cafrqZ2WwBSpFss(_On&^-PZpeHX@2bvo;0BJ4(2*f=6A8td> zGAF+FP*1*!YYy}~zIpdZ2NGJjDn@%*$*@gI6Gfmzr5>ZjkA+cbXf#Y>8 zMRxwpC_*>p@h1)T1%O;j`#Sbo-=PYMyVR0|AOP#g-aIVBi(7j|@IcCweiIDjC}+dTcav(9L#)s8m=L zYo8_FsBUKw#)}}qL^|aPNWiR6XFkA)Ui8_EYhc~H4-C9zSR^S6rE|kvJ0{xcU@BIyx;q(jUU(5I2DjE%xx7P z^p`;Tm%A!LueUZTq$~NTZ5^*jkrPS&})rd;jqo+4s?_| zuya$!(EnvE!VUS1k7l0oiwh5=)Ev943qE zrxTl)j&2n*2;6NJ+Pr$ zdITc7@1`AsE3+D=il=+*2old+4L~-H&;GYu*s#qy;M0qG*rd;P%f%fr0NJqpK#BMB z+lzB~bZPV;>WizyJqa6GA&^$W3HNWH0+8RAB3{wMfa_Q%y3A|>&EFVzfeuYTrz1^Q zr2_HFDh{nl@wUj!KD-FOu!sSRfgn{uHn3K26^5{`CUun^7U2HRa@WnC3*c;d9+? z;2s2(w%d#vO(etH$y1T8_1eh~Czg%ssH}fg!Z$n+o$|#J19F9-H=_suy_>{|Qx>=S-u!tN?U z+K3lC=1)tqx+np7&jHR=XHi_vbdpGAJw;L1yB3+E3n*HD{^~+Y6Ik=gDqsh&3<=0*r z{g}&7WxO3fddB1=8ZANov`_-W?u1zRg_M193)L?ruO)?Th8~Ty@K(}w7wp-1;FOdX zKRv!|K9RY>{xJUrCFze`nC^BU%a8G#q@?wkhrQgFm>GqHRkN3Ps7GffzQ6X9V(AGy zlh&Uz0ujKnpuHg|{Fv*s>m43yBU#+wd3Qi71Tl%K=bEt_RCIkxe9;WUZ1BJWt8RhRgRGcIl#i*>U)ZhSZg5!=`%o3=K449cy~1l604tz*gr zEIrCLT1CEkj`}Cj@t}3U34IKaRPX0nM#+s73Y{%^^%)`$gud!dJxu89H9T_KY&Hg2 zPjC=Mm?@#dEh!fSofp!g*+4NIq3ebvSAQ=+OtKBAtsMHv(?E5OZ!r{!jvS zO2bDUb>RAiKeX>=D}O=!Bb!{@3N*^BfFv5iTI-w3Bf!aVsIhE6ROl#GNS&$t9APo~ z-;8ZavLA(E+;cidosSJaTZ1@u>6b=f`k%poMy7(T2{%H^>|70VCHx+I+IW_#t?E z<@?z|AKUk559k)!UiE}SUJl??njnHSGx4E~@}+>sHFW;{GsWL{!vQze@%H|DK0ZxL zdLl9Zdw4s9NUDbg|EfPj*kcEP@zSB6wu!kDDR5@0xhi$0z7*<>dx54S|ErYp^O9iN zX!{EwuosL;&qi2 z2;6_S);y&C!~IN*Ka-sD*>k*yn?5_4YWIh<4%mT&k0-YQFbO)c)A?5uvfhDJ@&v}s z1qi73t!IEKJK&M)`^lTFh6OsxKHs`Nj)>t)w-bM2S|J`|}QXz83FF3O8@temGbi2sMj;fqB=6rO*M za*j{a>sgd;k2rh2&RBC57PUgGa@Ib6iQ>TPZFCqpog|DHs(Ox5r9*lk&l_qHJ?Tl?a`j*`lh zfsW?QE@HiCxF&VkzWwM`VJalRQSK}#sf{P_(=$}3F4^j^yiwo$JoHv?WnZYu=bh|3PUXrK%q`HiyC5@kO~(-ZMD!+#D|30y=R z5f2rc0FPCtT637c-iSh}vC=k|ZL67Mo6F2I$+_L$5RR+Q^+moE<`^pm#s6DpxLk61 zL$_M;ZC*|~zwD`j%pMy6%kGyNwNNZj(pO6Y(udFGy-xHNjp6C#d~I<+Y$iP&@W)Ah z1Ydlro~g0&d$DW`N81WuUD+$TxY+u>tBCy&6o9MiAvMsPa@=+bVUv5G8;C;B>PVAq&kA_|u8;Z__`Fl1q}HxSyqFXD zY>P~*?!7zjW(}n8n^dh}K%<6B!m03nM{<-L02b5Rjw)PkwQJ$82|<_hjl`|u|9tWB zQFljx1U+#!NBuKsQxijv`vlR}DTNh9A5NysY7) znfJbrD%5lPz>y87cKni&&+HI;6VAs+1m`(q_l#@vQ1V*I%sj)#lYI6q*fNduUL4HHjS^d=lyP8=Y?Oq z{qh^gd;vbo@gqHmk7mjw(LxX zVrr*;=8^G`cZ}0gtgY?Pe8bdk0#D@M?}#PhTYT=SajRKeppLLKMXn@;s! zSN}3S7&n!C1D<=uGnJ01pDuW#0Mj6AQ2Xvn9{9{QV+W7|pFHBg%%L0i4w!+11m`C( ze!EqBlvxoGXlesYe02DNeD_*DUWR5QU9)$nkoD)cx?UJU*i&-K$VIIU6a&kpXc-Zr zLQMPZKS$FZlk3#XaQ{VTnpn8ng69O+lr72xT7p-ugad2mFW}=tY0>!^+dRA~y;5*Y zHk8I@P3>PeD4kmgvQ+5FTzlQwS=V-}dF7HCde(tDH5SPSPrcYcG`iLCdWwonVvSgS z*zIJms7i;KQ~A~E@<$Ma-V5rZ+Y3Q2+!Cpw|7$yg>m`jG~kGT0~f;A&z) z8B&Zr#%w3-wibKP>A^4FJbW_qJK8|0HCGjKEARzg9n8m z7LYZdVLmH_iTePX5bQuEMl3?K>3O(0)%VsrWjN%`Ky6q~u}r~VIy&R3w_!3F$;~<{ zK-K(bpOiE>W>GaB7z_?`@lun90LV1m+xR|3Shl>Eh$iWQ`&gMy3*(kX_+tl=`@ref zI%#~Lu-nUl%Y>tz)L;V}wE(cRNQ{8vNL!zjc3haoLO0&fMp)ShM)P0InB>xw{f5{7BT0o`LmSnp$ucvq8lyaq&Epy6YDbLG5|+5V;3 zRG$=NpRc?uziG!^%lKUjYJA(@eoU{s(eYtmJ~MwjcqkQN-Y4{g?x*3*` zX&BjVS%c&bD6h@%;k(o7$&j|6zRFMt55@RIzp^a$k!Nb=(e%vxwgrJOg<;GUgVKD8 zSjC?(G6YU&Q|h^HJGMt561um0FOtNsFGRym+3M-HUX)xP%=X^$^nRn_&_2e0h6x^g$baNNMN>;gz!4~&!d_ev}K&zU6g=#vkH5%i9Gf; z$1F$we`_*d^8Rm|KOA5_FA0YrTwMncFm`%w(qe}6j_Qlnn2h#A-1Bm~+q|1~A{nvd z%6N4(5J}DH&x1{%ALJOOn!a*)0h8M_u_9X7@cbPC)cdca@WshwixbuY|N zn(WC>-R}G8Z;%6!kNwg&p z#8C(%kNWqso&OFmJCPZr z?7~9n-l}JG%<5NRV=d%q;CLd zm#PPN;^ac}9Q)N)n^d2q<;MqOMduAqnt>hh0uswSd-RHtD;tQ8DRPq9!ycmS*`y%z zeBj{_?^n01!J&ctvdYfYjlwTQ5xHX%*1?ufw1g5eT`og8i@!S`3HobrcZ3Yoh-uG* z3)N;84WqlNXtW>d>f+LJVn!ZL|7}Kg8bA8GkwQWH>HYh@o$%vm5zS>5zTf8~VrvP* zp9K9sX=MtKe*^n}0%r;|zt#tRNJxX7Qx!{hpRr`)zb!l(MZKOmg8L?oaT9ZPQ3`xu z=-Rtgu8kbrHO+czE^|MhKlKo$@{))oz8Sk31EbEb(^&&9_H^Tn1eeV4r|CW8mKi`$ zu1I^MWQf(l3}unl6@&{+EnZn>`!M&6t(xw@F)JX7HG^2TXmetmq66ftTIxg*Qf$K2K_xe^xx)a;yPrGLjr`@o*+1*BLi z%{o1I$<%-V_fxJE}%M~m%(1G>QifuWF4^q&GFKXit-6aUS^hfBP1si zy&}RWbEy{oDlDve1ZVZ(kq$PuS64l|+tl%fqOLkH@`!Joe5cWN5ygI1V0C@6EO+p0 ztvCbTDiuGRO72+XWOPHtUM(6LlPf!o)hN7wwOd*M9{DgSrz=AB8f{^P63z);o)PhU z?xk6|Uc>7@|E9tVCy1ldUKu#0#IWtPbgHwmXVdscXQc8pf0qOMM=#qK(L)t@ymzj6 zfFPdvc%JK&598}9gvHp3bcl;7@G&YEq%qtkCbEBJ>-0Q;P9dxFyq@DyYB?6|`^d-T zRen(px%;)&5BO+M%{4HZ=)j|oeV(>!!)H#F<)Sq3Xy0}2KmxS+q_220+b4#P9wK(^!^<7Q?*bsld#%}8VS5kZYXfw0H(ZYDIZ4|u9j`fdrcDj}T z{Po>-QD@o@nW~zcWsmYOAvEfh+r)Dkttr(McT5}^0CjDMmwvr)g?AIir!Y88^Tt`pH`GY72>se`6#HwRs?{*Egg4!lvY*4Ok= zVkRxMR8L%O4LB*)UJwhUWsl#QrPb~B$`kU4EXyzfZHAX*PiQ~JX;`TxeLzuI`j{wI zkKGX-1_xB|B_UV!3L|8=x(B{!A4|0a@!u0yfw&oN)Sn zGSq*WIs3qIx5#d+uyfkzPYn83Sg;bje35S+AbXz2=fEnyW#~;VZsEG^3TqcIQ#xjo z@>0t0T*yVKp!sZ@!n#}T!JC_TOMpggWZc>JsHlKz#$*DQ&{*1;E;TmFDx%R{PT!H~;U-NNP6E2R!uo`jbnzNKaa+K!uT0 zQ?owo*R&6r2CP+dFsVNKKN_0PiM#p-Wt91V1G9tM>!rXG4o;x91d092BuCw~ClUm2 zwW7f>bYL^rwFTXq7!(*BGef530JQ1_1EGlC9B?x?fZxaZ zC$#bg(<%6N@Njjp9_~6tYIlI4_q|h;kJ3!#o80b8b+W6Ot2~ky8gx++k~jEVdTIaK z_7-?3&dIT5y(G@BQf&6qUG*<5WddJ^CRpF}JinPa@WgN=*djMYu7Q~{!U}f0t%Ve3 zzIqN>p9T8QEZx)f2AHE%QAWIaC!MLuWiUdD&YHKwFZwoiMI<==HrD^%jA=~ID7T>Y z(oSAqUyZPT#^<=+(T(6;!!P?RPs}nStW0y$4hIIQnr715+8QGQjOhI;54XGu#lcB!WoWBkpVv>`60c0jFsYvhZFF)FhbZ6A- z4J>kkZOjY$Q7+1_6Ud+1UE6nd$8t^SnTcCnYdc8Hf)WS&4gj`2;3ZY~o|Y+QpMqVM zFBw_Kcqg_fvzb%FjlrU{k8KZ>R~fxu@Vvy1^zd2u0>ZAGdpcLVQt9G3_ty7JL--07 z!@00_nLH)Ve?}6k)ktYTq z*xR@GW|Kd<^;YEW6{PX&GAR+c>t_Avpbyz&cg|@G??=q_45?PS4iv%U=v{BD>MXZ> zz6KxcsuDjtdabcrehWU`UuibCI0hQAv9kdpYE5N{&Z*8w?jI-3k=c@;P> zFL*FSR!ZLkIVzbXlZ{KNd?G3W1;x%)p`{uQ`=El@*hO?-kF>GBkF`M{BLg>aTTjZH z!o+KgLi3fWUxqV5dQB}R1J^ugXTsh!RApo-n5vg(mS=1^PM#T_mYuCllQ=Zo?xtVf zx#%4&R&rq%-OP&yHcL_Vw}1i|9m#65wO9L8)a7>V(7d*L+rAoKQOWPpK1NMxqSuY z7UlW!;aN}77b3pAIfodI{in)_(EqeY`iH6pmdrI6NkXOLlAPbWAq%9DBNIar^aYy2 zTp}Y708q$Sy&UvM-H}_(w2N1Z8OvJ=AXaF!2bNYGenXkrkRJs-Eqa0bLkB~{Yzvig zYZDQSX@bzz&6>}uBL&^&z**_r7)wl0Vd|s^)L(@zYqw+Fe^DUYd8sL)fUK7qUXv;b!VVn^yp7Pzavdm(!@3ITd zdeT~u1Lw{6)P26U%wY^0qYk~OyoVC1wpdWHtV$Sjp*iJyU0jpn$FY3v6m3N4<4#%R zYKvGDNfo9>{U@;C^~MLbM&=)A`lns(yE#zgn^FBz2r@oUVrYiGLI50cw2{ zsxNZ1Q5;m>;}z+hH!5E9QS2QFmkwA`Z-Il*%O^eSb`8h|cON`@UL%}70fCHURm~sz zs^%Iv_g)ABpn)t6&`mF29%2Dq4fD*!T8{52ge{@mXL6xge8Y$lsjiWLf+v+;hioeP zjBBxwX;QBzZ!m8RAf_}Et^f$OeoLw1XpjX|J6 zzyrxslCVZ#(UxLPBOW5!@$fz=#c|}Zdo5{_;(S)ajq<%1*Bf$e^PqAPum1; z@uZ@67qsszytBlztqV5-?8hSR;(JOEg;7&}iE}uV^07I#OvevFd(7;Rv&p}O#1BVV z7y6XwB_5!yqE_a=y+ZS=uUVg4ohdJIgA7cTLWLfa511=B*2*09v0oB`(+$_FFafv6 zK^GqeowtA*Z%P#gd%F)fE&AQ-(V#N^JI@hkiCC$LsK(s3mF#wZ;%ZaPms7k}!xkZ# zP`x6u9mP%TtZzcLNAR)1xuEXSodNqh`fvW|&IYjKVTPJUA_K#Ys3{Z;R5;{<{Hp9y zNBQODY<-aTgQ9%VjuWHsAp`YxcgI`9gLx>Y$lsAo*WIBsJUs2Y??(zFT ziRpM0&H9(s*9b-?LX;&**@$5ddP|jrTcr9?-xt}#-;Qz+qV>o+Kk2GtPIFrrijHQX z-GaH{4jkcX^mA=zmmhc)QP(V}pW;%V=sN#JbG|4+DmsU6V?{-Cn(Snq^M1N+d<8eV z@q+!40;zn=gv@yO`c?&W+r|COv+gP;4GJ7!T4R$(CO!Oe^m{)- z!bgQY`zdONYw>#-pP=`|H|wXs9v9$)$6%r7y^N;cGQloBM68Y6OJtNQz52L{e_qz;TpfCiZiU(H><| z;>$1)c8#tkG$U_jG9UV2!}>jlJ}WMT`2CA5WlS7pB2Cw z3GRaxp5k|wPwSLD5sJMU54SL#UWK%i)vQo<`L4|rsx$5Tn;kLF=E>Z|k8}(z+CSHE zseo#Og30|wRgA6ku3GMQJ!u~Q2rSA1W8(}vx1X%>aI+o#Hsxr7AL%t++SgMSGQE2W zIgttooaIzM=k)|9^fsJ<=4l%LcsUF2Qsm6ZkIrK5jI{~xwWxU@sCy$lmR>gbBbwUl#98|PogRGwy(AU=FZC&R)O3mw;h=>Q3c=@Wh(KD?~S`b^r z>34~0KtzwUg9&50(Uhz;Se=u!yT5Te))S!Ck@ z((B29GeF3LB6U;6Iy#$vaWVb_0EF7j1{4YtI^OqbbQ(Wy4q>zM0!81#-z4lB3IxXA zq{J98<^lJukY3kSMv{HLeM77OfRQ|hhtTEoox=fwwGm@)liRmSBH?^R-av;R2jtCb zw;0~w?Q{&Y5PY4HF3}%BAWuM5!1q@0fnv$60a6mdPmg0)L@ck}R`|LXAEVZg`*!oH zek&YA(JieI=#U681pzY#9VPzY&!sNfMO5k^IeSGvgK7GkkV?KaW{|4Zg3Vtg6TdC7ar*_Y1kGcdQ@h&|jkS~>7U3`boyza#N(>Q}D?Xg`vU zk47`zAgMVp;BRRps9#-fH;~juFc_5QvBGx%;8UPVBUL03HU_0l>ZWB#oE^|B3(twJ#dCo)CJa+!c46*?G5|?|V8psNQ~mlWKnEkSlnTw8J9}sLxB_C~6eZ^A(kMU_nulB?G#Uu64F&AJ z;?wqB&+hg2*V47ySI0k7wuosH_x-T)_ExyS%}3`dR2nC5cY|K@1Q{C_@X+&xBn$T% zlF|@8|Fsxn8noU8(Y^<~No1oxFp>Xs`+XAS7(z#~-V`nK0_L_8<)Ifm#JqW5pD~9+ zDbR1iEkE?WdFxKhiILkg*o5rm1#d^u)ni2zW74+&Za)}i6;&icce|6OS^O2SqhT64 zPyM*9Dd_RAG-EUBbKwqogeKuzQ9RJFe@ka5Qq$;%OF7)#A?AbtIZA#t>EEB-W5i7E zhEnZ*Ee)R+e#^*%K9`5`B$BGPOzgNy?QwNUva{qF2m`{?Kb3BEv4>r7gR|EDPLgKK zJXl?o(FPmzv_bddU|%=Cd6KIFrPoqh6}nNxCX2S$Fp)oVf2ZiO(v4g1tc~Fh!UGU1 zqkj4b-r1DWrDb3g>n^oTYP6eH`PV6`o#a+@_e)@#IzK!zJ+Xf>F`Ey(o*8rOmf5aej8pet2yr);>As*kA=+{*t9^=XaiTVMBa_bj&CsKWi#-RMa zfJCxQ5dC`80Xd^rX-02-!IoN#D2sVQTTUDBA_3@>U6NfQj5oYZ<;C}jC?s#_RaL!4 z#yqO}5oR;UE!Jt{_E?>NHHjMIdvySWgD{Q!M!??N$>8wLE3-ryft51sq$7f{S7`yB zYVo13^`b^;FeqkbQyNkUBx(8G)6H^b;xOm?x~sP5;#ZeGr#_c+7v|U4>m!2;LjCn6 z;ritI>i-Aq#4j!ldQayrTz#$$uDt?S;^_ni$hHc3h&eBqOU=SsJ(OutGc;V_X;^4F= z{~Cr47DD_+8^N4?j}=bfq2@R`H{w-b2P(CMPx79nSLQo^S)kC(Rnh zrW1epmA(^c;rH*puI1A+J{7iaJ$<;8Pi5Kr1AfJ^Gh3vBq#0waYveqU)x;kct+X2} z%6Qc&7Polap1bNi5qqTgd};P<%-v^9=unz`@@++$VBMSHo3kkf=KpcD@01W>MBnic*;Q1CWrbRE>7B1XgB5}L^K0o9Qj4Q z>MJ^5?G9x;_1$d=*M9E;z%jS$ATX}#wZN{%Wc$w8y<()2Tk$Nm@tp3^o|xDTSqCCe zEYr`2pB3FF^jX`z)A<2Ex_|SR<tgH4y2wMtM&7O*-x<BQ0D(jP5hl^DBn)yl@vM69hMMvKZ!?-&<3GqmX zw&&T*NLr@~@V(OQ>b=i;&%dyMV447gV`{$%z>y1fWc(i$M;m<}IZTs4;{u!?23~f@ zf83|ETxo5{iy@}fFgN|VpEKO&>a-14bSn0v8aCN3 zj3JFh&s%tZhi`8wka>kp?%%uUjXE-|0_?2)X|NR)oZF(4+&r1R$;x?2<9?l(cN6}? zT8}sIa6($yGmkCLGC=84_~fncuk9h}YJ0hHZ@vRYl-l~)iAEg|qPfR<*WasY)A1C3 ztc~%gf76%tUwPo!NqBVO=0xn#2H$pjgOM(Fwe9Pegt(9fWW_OfoM^ah+p1*#fSrrU zp>B@wqPJ02>(NP|o|jv7tH|aX^5#B|ZmZF;##&-U{y;}}3gR&n1Sc&Uy9Dr)M!g<1=+jiAHa0cKHboc7-_E(v0 zCQd*;w#q24;0@Wk2gPHa7f#0L2R(;M2{lQZ!{>|1UUu7#yRXwrw@UI6Penci1~BYl z_H%bs8iP7w)Z%BgjvWI9Q0%SlHIt(}&EG1F2xC2>XgY=4z4>ud+zzl!L2Sk*6@JK3 zYVnxav~ro#`3fjVul+EH2DlvY5>v-4n6&2f-tDOGrj~W58kYHhog=eJ4Zfw?)>Zp{ zcZC0S^~skVz!-~D-BD{~e! zuf;<=HOWlq-N^>;UuUe(IlCbJHePLLki81>0wr^7TavDa*gum?&mj(aEAUF0awGk* z>%qgD2YwERceC<8Cd5Lg=C&=w1Jk z!1uS+x$uIH)TX8^RvgMCdeP?SeEhi{mmXY<8fHa7%0b=N{q6wuRn`+e+Y;B?LvfoD zvu|!+0{fpS4~H&+AY=1I@6*(8}lbX8wt8 zo7JzH)9K@Wa(%#!<+iaHjFUD`h}1cmp{^&7k72%PA64sSXb^1L0DGdE&Y$(g>C@vvH1X&nU|+qwb3qULkk9Ka zFj??hY1Gsibo?|TT+bGEprI2{XyFcfxI~vHzyK=tHeQVGuDpv+`S~l({M;CFO3lfa z(aQ`$cbY8?BX2h|1of(%7;9@qTwKr$ll09#kG<$N=-!AJTwv?co_!9nTEzJ67FK9h z?GQu=zeV()_=d^p5+Ly=-r9c5vijL<5m*7nGH3U8?Gd;jd8-mU_-P~$6@yT+#oL_$ zJLWaNV56V6<^+RvQ+#NxwI1SRmTBwkAG)(F-#s!p?L?W`hS1&)W{L3LqpsFA)iaAs zTnhNbpS9%S3GizlVoL4tDIYhBI!``(8oBWb288Wn@@@C@qV_>nlQL%mQ}oS0KH3WV z5VYKC^bWqUr`GeUee<`AqmvS)5-vtTTy_(2bGsvitIU9+I*1VN=HQ$a)|uv_3aq9r zbB8Y_%>4T!WIB_>d1Hx1?0<^q#<2)jBW8GZ|8C(!IC4c1pi}^0P}5NQuXg(BJFRdB zUWN)H?Q|J@QB32%2hW^5bLeB0>bj7tVYyr_ObZXaD z&hQO0Tr)WZ(Z_N_)&~@5V`QjHA;j5&XxKOvtIHR&VU5MDN=oh4?DlM-K#!32rXMxV z`q}wSDrIbBz>$Mzjz_pyp~ylm3G?tKPh?J_8pxj(FVZzO1)5NPHfdxt0~VXj$;ut| z!&aL{YP35F8Atgzg>;vsh4mNf%1}ZxEebojSe&xNsUplv@5f|I@HjkLH|Cm38ef1n z;_FT3=K?Nm9)*64$%w4rm8O1W%|!49UB~Nh#_;>i-CI~2L5f*qprX1 z29~!QzF$(uJAh0OjDEXE*##!3kGJr9N7)xgN3GhF@arRPNEiKld3YrSq{{)hF_qnK z52_a>p(g~*F_`37%mr-ZnubZXE#0C1gww)FS#c_mh@utQx?JbiWi%7H?mV?0yX~Oxsp)b>&Vn4@7PTAiO;enBAy?hV?z=2K7Uo~5wrl%V z%J-63pb2^KtuYKtEN08?XYc*zcvF(?6Rq;}-Q{hXcx_3+MBEt+g*2P%IPX2Q5@03S zDb1J!uAmz~j&08TBTj>7vni{mkMy?H1%#hvBVCbTM}E+;U?FW{Tl0Tmde&53qXv-a zfvsfmgGC!I3I$GaR7d&#)+x8>7-luy7M|QOHYimB=DmfFSRA|LlM|lzP zpSd9_rhcnHVuPFlOgzUx{fl6!Zdaxd*>Uv!nfEz2gwR&!MTt3FksfQW{0iGMfpENj za67Z_*Am$Bp0Fz34`;@9)U|L=yb)1B%&xIi03n_-qCh@xdz*fmi#d5jYZSrLsXUMD zwozkuYJU5p$>u0Au74p`JQgmr)H3qLdm!PlJDa=4&XXT}EPexzLo~I`I|D7+_%maA z1CgI8gmY=kZp*s62**qPA7R(w&es3^`>9pLDkVxNwJAZZSgqM%v{kDu5;0nP?@?52 zs`egjsZoR$ZLA1lhuWLkdykmE+wVW{dpu9>JI_t-6YqQO`<(N7z0UiHv(=3^Lgk^w zLD>SH*Y>k;-j8a1rI(l+6)3iuBRX^KZ~jUd105L44w&C(B>*i>q2`h&Z@du|hnXt; zzUH^BUya1@*FJyU+A9@@!)b*br(B5E+}1n3jJqNNf0vwBaaSW(+gB$!z{|wpc0z5~ z2StUw8fe#y?;hLNT-yO_@Qc(BBQ~yKnwQcM5V)O{oEPh@us6bw27F)qeMDa)hH`$z zQedu^{-M_n%&t8z>Q?8-D{60kVUD^?al+0Exs^8F73(u+0Xpx^ojh+;AOLotS$-cd zZbEBxNsP-4$a-O_906Ef@P8G=nyUup6vD*#m^T>Y?R{@WL*_ijkHig_X7p)ra_0et z@S)QmdsIb!mM}W+pw#8PA#|FhwJ2!GdxP{wwELTdTQ7Q=<9LPle7^a)yF2tsilWy& zOQG_F3T>pLQgFU{-vd@H#<2gt6wj zZ`4nLCkq{!EBA&kE9mbz-~Z#aQuF$bRB!Yq-4pwuL0QRaWw6khM<(m*o8IbIqISQG zy{sJ3O<(ZItxn|lXMruF`wkTn#Yk4)az(JTTAAcptq4+B7G8{i!(R~1Pki*O8(gCO zyC2|*a}jTEMSI%uD6dBCiY6qT-=D){1U}^mf%(3WIhZ3$>L`$87!nz@xGaa8LIex# z^F)#OIXQ0?oy+~@ZK5> zo4+DOP{|+8MdQ^E&~TZ^?ke6xMH9Y2{Phb_T`*7|>^^ix(>$DX2WcFoR<~F!viC$M zOrfOA=Y_bP2?OM5@{Jgtzjx5^^>lb@ zqB{bw3;vCGp$ZG2ibZ%w^K%-E>uie~Ph{SQJn zh#I&0e8AiuvU@%hDRP`i6SDd|;aLfSYS8%P-KBAAHed1cENd;@3^Jsg(t%?nyv~I8 zBBK~-tm8AccN6`ZzbeAIyjW;^rgf3GAXd&;itCX}hpNL_2suCu~3me3$~>-hy#(yrK&RmRssU_w2h> zB*X3u;5B&uES<;xaD&;?KJ0vP*feFL65$NJ0)1J%&<#3nyf1TLn*B!KAn~>#N)%29Vb&MPDtER#GxuVB=2O786^s!3 z6Jz>JPBU8W((}KYw_Ehvy#}N+)3(Q>9knDu(uGI{5Y3o|=9w(n0F5f_bancihPIdM z+@g?#7gP0kdSK)HL5B{5I&SU`#LcA5$~IT^u6v)m+)Jk6JF#V5qwI8U`3U$5-JBeo zvYScoY4ev3j-q{R_q_CdDiVm}7Z0|SfTN30;!xGjl2vV~!&wS#)(SPQ$CqecTHF31 zc|bRiD1#z%f_Y~nCR1j%@a};(!;zTVt6D%2QE$IF~H19 z9StPOwZ!Ylbc4E2TiqgEk&xoTt6b!kk9^CWNxt6TA{4fUP!*j-6XKYIqu#IDG0^<> z!X4!!pQ{H_9f}A>5Gr5EDTl!Y_7a|&8^G@Ou;~cuI!=Dn)RF=05g0BZ8(&SnKO^9#AIN5ytpIPN$K494l zI1>Wf0m7X~-9Q2hYOW;DMV_)Vj%B4un*QHhF~bwB#nN|2lM5YJGdLZ0$OqULFr#g= z%}v#$Y1SUWHw^CAP+(=16M?9vptS0H|BJA}V~Y7uB`=CTE9`;%#YEw`AzMiNU;CT2 zLu>FaUW%l+S7LU%zkyk8Y8a`1ui2l_mqtTESEz~ALghtFk5pN#zF{2h)D% zGn;9BB`ftp21RwV$*YyT?o;(qD^t1k1DN`X*Cy$oRTX|#axu(3YRLLhTgp;36@-(T zaNYjQyp9ACa%+Oyt(`?bS ze-FWM?`Q|@xdrY)PC@_%kn1DEB>EyyK}vB`H-ntB^9YX@dk+KtUY}pxAYO`=c)zEP zHe7xfJp>}D5#9_2W~)Xx!hxxfL_YZ?K9h44eZE9=e96`Xiu0$$Qc5_@2djK4pN@6v z%ty%L9Dr)*+P81pl3q&ysYY?_PiE12ZmO;r#VQyMk3OYUcnu5;h@Fc2 z@7)mroBo|Lh?ld_{{*b%`f6J}t9@O7iL!1Pv8Y?FjjaO*_vuwQ|2;F4o(=v_ z!5#I~d~D<{W-oJ$OWmw;9Xa=2asp}UEbEa_stwo+Rez%mvy1RtzlcJhTWhOq#wDmB z+xcM-rwFrXeZeu~A|#+kLPnS`<5bPa5SPz zH5zm_K4i3tu+<+k(A@3_tUkiZ;cw&%AWEhWYL7Q z<}s$NC6q82OVIU{nj+;0M(mqRuwKbG?|s@m`){BvIBuKPw+W$w@`@!4Dz;UO>kTm) zA_ntmnrVEIR%FT>0($OfpJv&GA+-o|DbRxcBBt&gmkbf@&$HsCqPQ^hA!mj1@S|Z0 znZ2d5^z=sqanSVJczz<^-jk!vw7r{<{kFJAZ`JQ&fpS{Z-Y4~?80NI3pY7*7x*rNd zBzYbwfs-#ql5^{|f_Hfwz_Yvo;>pAm?~H2Fym`tES?NPnXm(2s4I+&U8AIc(U%@kn zPbZZaFnivO{m)>-5s!LTQ=u%xlaWc{=zhxp2`RQZtXUaDB48Nd8rGw>*LlCLw! zfh|S-4 zFU_&@3J2_eJ~z_fp2zf`gNC-Mi-A^3SECS= z$z9_;q_Br5dy_s z<>KgUM)j{8djcG=c{d#~7(;u`$rN%QB#}5v%%vZD zl*fEjUlbv?w*C>llRNrHp7Y?{2oUCFhh2wF@VEsdoGK@+uwG?UBX5(@pAb8#^~_i% z+^iqEOu|40q|^PH9;C-6+~xD#1X_idbu86C*;QbAV_c>Uoq|&E6u7SZk{rwep0Mu^ z6{i}&*(fnBV9!y)kR(j#;OXKPQmQY0yEt~W>Dy#h4jFP&BKdgu%|reUqiGpe5)F%2 ziZ}}jKB_iXO#$kDbf;Z1uhYfq`0gY_Srpgye{KpCq3hg%;&#|kD&J75AK(VI9yuoczjy zc9>iQvz^=Vf7JWo9Vnoy;xMVI$-Op$Aee57PZ%>I!R&1KUN%NFRCk9s;bp@a=}Xlkq{sLxTK&1Xh1I>bVsiJ>)@2cpWO!AGT4 zCliHSFCpTf=6$pW7OGL>obAdGeR%Mhg?L}j7crV?i*T9)_9z0!>9wYvXW zoZhqx>qF#fX(#&L0wT=CAqx@Pg0`D=$a!hF!pY6ERRdBWQOd?ISvGmS=Zif?&R0_; z04LUM?GnjhJP z=M$9qkl18<^dcY5hnsyUFn48pOQtt=2*@(-En3&ssl z9SUE|G|N&O@X1Hs8*LdYa7Q6W?+d$H;+Kt%l;Xugt`d-YZAN-G zCwG;9kvm3*Q8}BGnt}9I0eq&A3iW;IMHBI|!`}<}2?5WsWde*~!!^l~!0ci%0|YfP zxc8jyAO?220xR5|+@tVd1bhp77{G)z0@IVs#PNX37PCBgCiwmx5gwWs=A~o9y->{E z8xXpgyez=AY2T)=uZ-^JPF1DG=iF!*@=r?l0o+KFn1{p3p*>e}%vgzD9`D zP5rm^Bbjf1Qo;PXLR`P_iD=yI+{v(!Ly7@Kn`_Hhw3`f&oaV*4W4(+$V}G_AC608A zMxCq{y$sl9pWixT>AdpqW1&bNIV_xnam6 zJGh9-e~9=S?*0go)A!b+)s)K2G+0SHf(m}72OTIC|BiqPqS=NKhM*O5CXHQD@8+`? zz|)3~S{eC>3Ng+?pvt!j-Ai!3f%++*fsn>}nON<(>I4UAKVS=+@%;WT2TGXcXh@Z# z75i&cR8PrUavT->{)SKh;(Q96?YJF`P-}YPXwJ$}-Nb-=qw~al18nA8#r|w>1JF@i zoUV&+=-Pd$plo|8%8^?|%^w?NR<$5zRaq!7oCltH{s7;Z=KQ@pu(`Wd+*%K-2Q?Up zRBAp!S){TacUHJAJ5f+Z&*61=^ZmL#@C8xSQI%XPxX{k zWZqv6SWDq_248V!BV>fhE-x9nU-IPD)>CGwjnDrJtCE>SnKL!6wtPR&CY=ZPwA$B9 z{{rzYuM(nUXlack%F^9Z6J-&F_{qT1lzND|kr<+)p`i}-g78QqQAKq`UT11UBEH9ik zw>Zd%_cfhi73)OEJ+68DSKGE0Apa*Dt)QABY}?LGhDyW7)G#ayfgSJa2K56C#;?tuRor!m*CV7&(H|HKnJ z05|=MHp|-4r5=$TmY}#aHo%pWk>{S>2sZdHT2klbx&md}3qI%hpE{4*_9kwxw6TZA zeicY}u*jQ7TEcaJ*IV%PKJz-DrV1MlT5O2?o8P2(n_$SA)DqsW`DQTnm} z1n(HPvnDmop_sZ=^9*b|9tx!1RMCCt>IjB@?{yIgdk^21mNEbmc_Hik#I#Vm%>{PA z-Jo#X;ZP-1Z<04~PceaGQ1Em^Fw<_m-f-?0cxiWKcr}K&$)ZE?{2FG3&WsG#!M3P3 z-21VaQh6@X{rN>3wZ{h26nqo!IB<8_S9rYkdQ%)?5{|AI$z^cJQ!`Qpxc zi}or9U;3mLw&$}E+EcuavSbR_mVl1B#HWSUx=OqRA+e`QQrWFm(io}x+3qylh=mjE`bZ$xCCPw#vUaWZ@v-lj zR3Rz~NwFY%e9j0;YDtWb0+-oT*Dw`)Eo8a5Oq`N6-Fm6H>>(<$13KD}A1h zYkTpU1yn`ydA*q^_x}0BdMe|2`#BRE^~4@0AY63T8BM;bkh;}n9Oiq&@IXrW5~|@p z{QZy1N)aKQHznC5dG%d0$oRBW2wGK^8KIjRIN_V~o|Czh!ci1z_^C z*3lI98Ow9E4Hjg%6WmYagc51y5-r6_9?(2G!w%jmq=*}Q7mq%Fn26L*!&!l&lRg3b zy5FZki&EfTH@4~QHCf=`S5Ly=nVcJD?@rB&1Lcp(CmZ$|fh>O~aS>CSvvsiUlI-n( z!lL)+y~j*{WzgNJtoTgSX%tnT!*eEyhyCg_I+E4q%(XKEv3)QF_af*6ej{YV01Di@ z?ei=bY=#|osMKX-8hG8~?zhQ$4)P=5uDg4Q-~$+R^7KF<_%l7b;1S$|Yc03kvtwx2 zd)UqKUiwZ5r+d!fy)tK_qz{_R{CixbK!=*chVHNfE=$_YxnIZ`$^p+(4E}fa^$@RV~wd?Hz|4zZo!7covNR(z=FW0or8DWqB%`F6Gdh$ zr8H~3M+Dr`5wq8ZjG+cIA5tXr7xWVl72Yg)j9IjYg%J+2guWc1y*25u$+{>%!@Y3+ zGU}lmJ1}67ay~7Liw%)=nY59{SsCs5V3bbv4(?{Tpj91NCbu5nktw*nzTv?7(MJ89 zQCHpPXgjQ_$fk>E@MBcaXqTYg+ks5Mqw+`m7+u+S`LP71ODbMgaz3GwM~W4oOM+m2 zJ4bscuh9Y~k|JiVF4H~0PK0?$)*bMez{#0xk+;z?9=hVs`-A7`KQQqbn|6rHdRiMZ zcQimcly_pxz|<(D%aWkmM#JJ4N&>fMGWAo*o8Kmg4iP5Obkebv#Vk*kcc_?Im_TB0W(byoRl6UX0&{3Bv2l?2blCKl9 z^lp#*4J57hac4QDziogjVa=Lahsq|sKb&r#Zxj5U2yqW=f!C^jUsGZ})Evnr)8lrs zv!5ZRS&ONBAigtG%;XpLVvC~b{yM+{wm&>wO_cl3+s>FnPDv)7?mf4XT?C13}crjcx^bZ<*e-n_7x2vzDpNG^PTMAj!*S zvSCG*{LE0kF?D5z%+OrqhCA|ljz(AW*>64tLYw6FdioAdMuIf=3Oa+fVkZBKUOg?- zZkSqqP+-qsEQ^x3^-GiP4od5cC)Ezzeo*9onhww$1=H$w+16$Oy?*qD zo4|nTKbAu)V`bkC%;Q*UVu8Rjx!pUFDq$DLB{-TpOu;m`LZTxQNAjb-X*h!>am)>1 z)3~o1LvOkNa80un_gngOn^-nt4m%3H`ioGjPM_6UjWQLb^l0YNi0_NACNv46)c6Nd z%yWe&HF{DOg4WBd#r>hQu5<$l@>lbk$r3q6dY^6XKlfG|<2As%VIdy$QeT} zd57|K1&@6E7Ve$qowfW7H1I(40D5YaSmej@IVSDO1!1we6EWoYUwZVdOzT=Z8z1Y! zDx`?Wx7jil9*o%|}P^f2<}`uWH^q6jI!OHJav z>SN8eLruc+phw~LUlVZcwcj-9@-r*fzj35fk3IXnuFL1gu_tjy-2J+d)M|56$FOm! zlB!cB3!2>n3fFCQj~BC*j`~LN+aoW*zEmxugQ_ZovE&wz-Y-rieFc zpU31!|4v_3FuaVlA74S@r0`+D09XB z?9W_?J?#Oh!CV;aUg+F;sR|x?Ksr1h6(P+$-=89;?CJ?%BP$@VPeft+pm=J|Phc}c zoKrxu7z+EAg*l%t z_$Cq%x8A;!fzK1nN}ac-u=xt^+$03y0C>*Te_iUkpO|ryjufyd z@vv{jcJaXv_f0KSP_N@=6k_rB5AGE)(*EV8nb?5=KCl7qk#IV9nDIfOEF?4AAT4K% zIJf$EBv=31(zJi4r&Nyh##Gpf&5_&!Oh4m6ciWv|?Sr(G3l`M+Q+pL@(D`>&FDu@U z)FJg}i9|%(X=u=-b-%R-q!F5k@iX)Y5bz|Ht(`mhQz}n2LO9O2&S)`3X2AOHhSRyv zCe~qK64DA~J7IWj=r594VPz~ow*1j$r2fxxn1||;lSKC2O;qWkh1<&0Qk%d!=zYI- zz2hfhep&%;wBO%Li00MsxQ_OlEjBmBLbyHU_cP;9Mb0Z;bcO~gZRfMu?YSXx37FHH zu|Z-!;SeNpj~aKOvM`jzd6FO2Eg51Y1|ra{@t+tCT90{tLONZaYV?uyyb>Kn8;@Xa zoh=df=}qndVb2CrHo!YyZkVsvRmc)@3dg)-HO4e&}Y@`LrXa92U2n{hpXFaCnf4l<;p|CXdkkZQ*DJ5 z@Sg_}Ghzzp-`kFFqxsg;^qIs!$0R@dr=Uj4h3z5w5HV2WmG<&+-vB7&(6!j!JsTaM z6K`CO!k&%+T92t!r;GOS9quhZo~g!D7#*^oj=tXU(nP+uJO8-#YviHpx9z`fwE->U zQo>+@<{v%xe(^WTDtKzbe7sx6^i1d}yB~+*(0Z%nGfT-AMjs?r1SLC!GU6Tf&s(AA zn97EU-~Owl!yZM+S?5OG@j6dX*mq85p`3*zgcJIJzZPJxwlF_KfMBLv5D4CtAcAd` z8^H4SJT=IaR{6yOGHLO}63HnOVKUX*63nNlNr5_Zh0C_^^vt^_b7An*Do@Y<0#`&N z20EZS_*lMw!9rZtOqz!E5nIUq-er>CN-Wl!NFPvo-Ftbem%*aoGs4Le4M_K-nYTS? z`zy`eR^m4IHZM);CdPE*!NPSP!d*S-1O8d&H-T|1l@$x>m6+R_1=t1<61u}iDdu@x zS0Fc?G@>dciaj5B+3ho{<4bLPZtU0xmu9b|(#U^p9~7D;U279P?_1Wq8_5YFmW_G0 znLJ^lPP`jZ`CM~F^Rboq*xUFs%v;U-WeoXfvN_nO7SQb_|H+Wmjh}GUzNB=DGD!hS z%|^^URjg{PdC8~!7RDSuWnBadieIV!Ty{@Q@#fQ>rk~UyhClDv_G5hdG-LDcPQSbR zBF-WiJnD&XTGGqvQJU!c3}^>?2@$`TO}eC$iR}^tJyz+ae?>4%Z0qMX8%UA<{7*!c z!*%GjClXN#mKQM4`%m56m<8$Cq8?2;r+CkZl)kWk$1=BcljuY zrOdLQdOfkpW@$pC#BFaoc#D)Mx*ZvO`}u2nMVi>W@;h#PC-oz_3&u-n%fZwn*$FEy z`<*tka`lJHu#lDr{z7W9vIL_&=IEOT^#@|S2J^q6ldTKutA}Rb70meW1v9$ux_D3R z$wrl#&!^J8l*eNIw<$|2~- zU#H4~V3f3uRV@ti=*{ugU$;BEclL3wtm2cVYm5&PtvlOqTfBa$90^gp$sJq$ZsjN# z6Ks=8)qUBzSO@z#uxDq@6e zUUojAYE|RQB~w3V2JTT7i{eHv-QjYV>xPnYUkban}TxBl0xxDGnVoB16Z^~#MlnG@grZ*B-Of_^Ct*jG%p#z(L<3$U0H<#Uf^?RhYMcx|9vo zkkid|b}}X46{x*nqj*Q=3)a!3VcNGL@4U16#z;>?G)LeN1cwi9N%wi6#LP21sB$)< zY98gsB8e3P)ioBc^Rtmpo29s~`0uZ5%Mi;J6p%eKhkTjVHXm((xk=aM_CEUCE?<9n zdU4cV?8Aa`F&wxJBKcLLoH5LH9c?HjHrD=NBT9=-HAoE9DvF`vd?p5JnGUr??U;fi zO|<+Eb;Cw6;M}zwTC|M&mrU#M`ZXOR8WObUbKGCIw`-QA9mJry6$yhwZ`7QTn*Qbs zb8Gm+n*pinUWi%OHky9yvP zI+Kk(OVx?Tzk#g=tbo42DS8@FxVL?6?u?0XZT4CQ{&ToD51%NOLC5cmNdPKC{PGi< zmI}Ay(A6dpGp!@^$|-&CX{z3-S`EH&S`9;zY*H^AgCi(B86;UFYw6U>O@B%CF$tB@#TX=+$0eL}3 z4L@%7w}qW-q<1!r>O}{j$IVsVRaCaSeJw?)gGK!7T65D^0=FQuUAqW0?kUo|jl@Wm zf9B)i=aTrK7u}V2MiC3maKvWdiwE#;O#7Y>znFqZzTSAe(q}kxqEYE5UevR6=orp3 z?m?_vNrX#yq`mcxA3J$c*>&@$=Z|{`k}hr+`7V1uUbz+vCN|-@FP|*ONI9uBr+B)& zJYZh7PiGu;r-<0ZvtUUL&o9{hhwzs5w{_<8s!#b1Jq1>0tZ|{zXSX=uSt{qid$*b3ZIDB9^ zdH1?m12XCDOz)#~?Z&Ak*4_IPT&R$830{|ZrN#m|G|$6`$y&O8;@^ujxiD@|*lQM) z>o>k3ywC8gQpfMNZIUw>&omqmQmJLDgpJuZ%JBN7>?GVv*jr zzm#KpO|^yUqIK(adWQH3zG|e4_rnl?N7}pJV?;PRFhu}9@0BWX?Jv`vP}SN+@ug-b zNYobq-1_1a-jMP(mC9kp_QEq9z?Ye5R0uFt+-S4u2QblP}aM@{&{|1}raF*?pbE&kWF-%rc!Qgg36d#5K(Yazto=N|sWZ zHS75o;7t}v(aFGY`R_%m?tPGs6@ly!Xn%|1uM*38<0q2Yoo)S*1)>yiPb6-KhpBPt z7c04_RkGXy12Zi*%v%n0s}ZViE+cQ_O2J<(VYQ>?nj2cVIA; zDVUwIv!!ZwUu6F_z#5x(} zrP}kglZOStY3vCPG)L6Mwa7JwXYKa8N3iD?N0a^{V4}$H_$-|e5jC0M{Q)e&a4S@o z+H#0aik29AI>-|LkiXOJ{EA6&l zw_-in*+f$o?S}$3M;93VtLzUtlAsUFY7u;eBzcP`UlaTSX#4tU64*|H*`qfbCMXA> z$?A6KnjH^3X&tmf-qBpLPK(-Qv3+FgfGSk_lMUxR@8y+-^=Q9-qls zw!ECU4-7rO;xt>DSx$hDRM~jWQJ+sAV)$_HbMj%yAd-N!lx6c{X}`dksP@FT@X+n; zv(4GM<-*(KY%0&wV1$Z$$K;my!2_ErqP5(5 z$#f<<;N8D$Bb`YIIG$!gRX+~xPq9>Q-P>%CHk()tBGFI8Vr!#!A>NXhw= zMceBVSL6%$z8%cbw$XlzW)XEO&1Xv9D~ZgdEw*Txksz>8eP2<6v-VfVnR2lM0FcD1 zY^sFy42pr6*C1s3mz8j^$e?JXtf4uTOkuglpd2eIj$MMey!+n=gkHobF*Dm-iDtv( zAtHl(w+A;dUawXq44eR|YQeaTYx}^H6!ms$0(D4FQBgASys1xSh|@MyM|GyrO-T3t zzieh4Ml^yRm^28>lAl&lWm&uvmD?p2K$;n}Y<1$txxmupjZn9*Em~xSs+(T6e+g>x zkhl0spfx-Bc)vPh8j}m+8^nyJxJoJu|8;xX5)~XrwmGUMpG__xLq7i8GSp;W74!pX zyom9-s>%1pAJtkQ-XO5h+Pigx8Ap(b57X!3iHk31%@t0s#^RlRDsJ_JKaRytEkp1- z1qmSBck5fQUb^FKKuw&zu`tzLwFzK8D8N0zMs51KUZ~=%rXiW5AMve{miI#yzCn~Q+Z4XrZ zJ)R;R<2KKxTGHor_N%yB1J^g+K{c=59*Xtcblf~K4z&UMjhGy*D<%(MJ-7)LcIJ(N+Vb_?`n7oURe1ZCrnsZ}XhAIiA<(rVmo6Xnn;=uya?pw^>NjWQw) zc~mUHN_co8h{~Js0JbM76n%=~H(s1b69`1iJ~n^|vyltijmWvdjLbZ*4f=|_3Jp~n zyQn*EyN_$)FX4`|nNiQ#2!ID5zwK|#S8Q{Ok$*Qlavt?eGQ1Bua7y`C(#J79NAK8e z2R3R^U2%&N>S4S1BwxCqO=;-s{n@Otgq#fLg!0In2Y2`FCZGR&Q56@;3i|}N!og8n z_!*WqgMBMWH!9^0XeL*@pX!(8MbW>%H|3CDotb}yec#|dVei+BHmUhu*YHaf!tOdF zIe|AZFS);X9CeXlBo5-+i=Fb3Tmt+AMHQQw_+nX$8Z7 zgU_I8w@-));o)>W*Q≺n zkaavnKm>f787z1U7V75$3*DZ$rtH1*@4rpo(}&h_is}j%a9Xi|wE10~V&$hdLeq-a zvZ6Kyx0@f5*hd6{Atkr1@J5HB#2!}(kcH10puxz@WeiXDrzJxbCL=*k>{x zl2$TSkGS6cr*S%-$Keg})Yzt$^u)bi#&C>f&@SFWD{^}B&O;0CR}6PdSrM_5`vV%V z#CM%7cENMWznIOpw%6{W9G<}o_WU1&4}{Ml7MkQo7?@PO(fOOs$~q0=nK^b2&sabv zOGRGq8lvE&oJliLoCpg(du0mq;BaawVcXCYWA-AA%k?8ox6FEv41NZh^$ z@v|#(JRD2*)(E6WIzST=vcJjKAfAfr3RzGv#OB`iAC>fW2*&!FYuFM`Ez))Tn<_eA zRe09O^Y4ZtqH^Ke4#&T}keRf!BQ;txsTSZ~g5bF<`M&Eid82qQo!enAuOE_rgORo% zWwLs)hhPVu%$Z5UIs#IhqeOYn)0m(TMrMQTOB}m74Y|jOVsNZJ;Jy2a4-13e0$iIG zKkk`KqBUv3VkeT2;3P`}w#`!7cUkH$DNhmRmjeW>+ z0B1I5{}^FGWldTeK)n8VYiecCgs3I*_Z+m+Ve&PZ=e_<|n*nm1c2@>K;uCJ{_hQ>D z^^q12K_3v4Eyz&;uHa=uhtaU{C8fjF?&p0iDTQBO)o%Gp1JOuBR^czFziqSOLSpxq z!>JwQV!zEK0qQ%38Ho$~q#-DPWK_T)dm<9wdw{XqXYMn)A}-~mMpcug=Q5uVxh1-{ zkHZnao)@5Ae)!Y~fVil=?1_QeMJYh#rZt#Al!c!zxWSil>SjlPvR3H6?rv~=uad(6#@l2ek+qV)Lvi0Ywv!U+*s8;#ckXZI^KJ#5FLx`?^9E-A( zJ-4b{?3eunK*tSurfB~v%g=ZT)`&zB5=>s;qF|oj}QqSm^)Vks#Kf;5&<~o?a_QzbZT?J1ho_EC(jH^^WOx^#R%?7No&ipVFV&eXIm{wn{xh3$_V+`%n?tce>-n#!?Kn<{ z^MvO@5ZfWtA>ZFkHKuO4IfWb1VFwGlA5~)V-ET$z^jb3M_n~S#+Kjv zayzG1;WV)qo)7WzrRFpa>nx1*pZOcs&o)^g_*sn7sq5JCUx@CmiOFG~d~`Ep{d9A> zh-qd>-_RO2i}_tzzNCPwF6AyCTiH>xcn+y@C?NPgy3xh$R!SnwQ5|P_69&+)&xXl- zYd<_1@!H5G_OZgEn;oLF#JKdf{U|Zw9wEL^uG{1u$PK0&urcV)>o(CZvv_gfNc)+N z&-+;Ogwo^$eYqk}l9Usb!a~rY2vCVr;b%j^l1Y(Sva6N$k-ItxvNvO<#CJERzcZ#7 zA`2h%p|?`&-cB80>_kj|IGh4d`21vz=$;Gcu#gJSA^LM*2uElUTl35|G_}0ly?Ah; z^EpDmmML5|25Fa04jZ10)7JX!mn_4mmf4m!FyC`Fx|UC^96hMb|6)7VL=DT7PE9i6 z$f7UBvbSJRq1#*~BN5VZj@#Qq!zJ`-yl>Y*N2xCFcsP2HClnR0#Vps}+Q=`CHm-w0 z(|%9ZGjO;h$0?_B+Ge);N|-SF4POj>xTc|~@o4c;#A&zey;9b0`?VBVbYb1r{fMmoR;%6uU+@F6b7g#$F>p3h^lPRtz&2NRe=kvtG1e0=X{7g%rmdw0ZM?XSiak8n~~1f$35bwD!9EwIbgyE zRBvwP-ftE6pe1QLy^(jl$GN@6cl)kJmt7&ePKNU3yeyD+?f*9f_H_!1J$&-88S5Nw zV}iSCm&a+Cp*)^@#`2`}t)`5I`4E(K~W&ruw<_ikzuf{xy)eFZzPfp<6+Y+_bsDADW=TQ&@fp zv0XE`+xWL-)SWhq)_zbZ)f_zjO}$~NPe^SY>Z(y_(Kg6auhn%^ij@k2}Q;fsjluwc-sA}^LX5^^bo_y^V=yHioO2tOp za>9-6XmN*rILA?w97Yy?OBtCB-uD5yzcW=LmebSU>AFFTN3XFzZT&ov59WKITkxd> zUe|r|SfW)82N#QiC8wk|n^xPIY3;tyqF8YQVtRo+BLf<@(rEfhwqA544b)(qqUN{t z;CAIF^>znY{2wLyqJf~(FL&I&eJNe{i{*`afEU_y+Ku@d_W%I4qr~c0&(9|;z698Y~xz@8kFx)-$P3DjwGfe$Q}dF`U(Flx^D5SHY8&oOwH)TcCR(o#ei z`ar%~2iP=Yo#!aVL?;gbhLx-%f_D==M$vUtZ3EqCu4SM?z=mdKgZ-u+wyN;e{G?|u z06y2*e3^X89L-#gLTb6Om^{spQfrgwHkY1jsEhQ zZErP2$e_k(LYL!V{!lEH3eypjX-FSJV^jmSNFQCeJNHJf@tidIT4~by585L4CZNzR zJBNqB(k9tl(O^Rldh;G8$#Yt^%Dxwlz0mibOrEJJ6hlF}o*`DlB2>cmC+{|vP-l%n z&&&ASej^0L7FlfzyN@=zsP|<8LOq6rm~JLU`!1I}!z`S+; zkJ0!o!NG%O9^A(wJ*d_*>e^7{?b*nk-ySX?tuDybVFA*7nWV>LMRAY;Cuq@(9kT** zm08R<517y8dw83|#76~EP(oPhmG883pz|AMY(l`>wyh6IXPB~{<+j;x=>|SOJfHUR zuZDr&?4Ms!cXNZ^gnUiti1NHXlMt>7s;=!zJ#gixZV;EgA8(9+nZ z=+MqDzon?jPZ@V3`LIDB0}+or6u7fHE$Dn8V|6O!18Ul0 zrMhb78RXdOs*RFjkyJW`|C_s3%wVykBrBP0@wzQ4Oxj^&IQ*hE%Suw|_JLi`;GU6q1q~3ev!QZLMSr4-6a+s$BE|Z+FbzU7C+-jc%4aFS$G*~l=rjQpD6rwCzPB4TK5}?`6=at! zMW_|x?upNxmGzjNQ%bOsmn2vU_S`IpQ32{8NLhb?sRZ?=TTS1gl z%DEHAGt!UhCi-i*dm56l&8@jG?N$oi1hcd0Gv+j}pecirI#50Dern>H)@;}4Pl|Qv zI|jx7mdbF!Z+l97PxmXW2-9z!bl8|6flqgJ?Ri&HE~&h`htszE#Gz>kP45`yRWAFl z0(d;*ifEz$HB)o5BfK@-A!tUK|He0y`uT-3gqd&08&r73^}_=uYi(R>`~J*46Mk10 z*IND8ao5T6IE;JOm|jyEpVHy6(qzU|muG7zB^Im1?ER<$Y22zkOaq|-p-|70FbUDA zxyBE9MR&rZZL$Nhb;}wn+0d)}W0wLA<{I<2RbG5)_J5O7cjCqC$EVs;+D!I)SEAqP zpwF?&pa~^@3i_<2cX)8}5VYnRbryC_LY&IZ%w^tIy-#ZEWS10485DWpEut8$w(c~Z z`+6`Un3ncs<)BY14_WF))Happ5E}ssMZ8p1hG+lBGa=j7fcR{LHW~+8o$9 z5pxmA2*Grg_!+OHpe5jYMP(yC4d97v3u7Dm&H7LFZ=oU5&zDiCiu>*#aPan0b{JOV&!3uo@V77yHES78uMvBX)}%+ z7DiQjBqkc%!g?y$Pzim>!KG1n1;uEPjb2auPyzndOy5Z0% zi9=%5>LC&}H#x#}d5~H0KkAnuhk7D?D!(l~MG&`ms~%U4mzEM%=yhov*Pnl`zrfrA zdThChZk;s8xa9f6X3^AoYO<(vMogevun;6=$^^P<2MWQrAAuO_T7G!mvB9%wA$I{L(f?-C%*bW!Yc#gt(2@T`&ReR{qc;Jc1`=*VuS{6s)AN1)flegS^h4U?pzU`@d zww)>GDb=eVC3>gb5$-!46*1n*>cJDUv~biM`9dzr#$Psywpf2p7+-C=y=C!|myf`6 z;#K*#j8TA!z@vOp!d@L3^C*Ph2=8{5=I{Ts%1@-PUFU8MiLA1*-nLbymQ%>Lk_~I) zWgT`~Q5(Xzyh>uDKF!`Z%SZOnd|Dcq8C!yjGS4lu9-GCAelsbRFG?%0BkDXs&az7t z@NMSq^8UXOW=>5bgWg`5Y)5{1jvcfXQ1XkZ%&|`{&hmSbcgpWEyO7eF+#7{EMnwtt z^tF3^ca5Tx5HK|$pPag}cpa6=hVsixII?T@Jeov(t8^{07l_I89_`tYWW2?{+d4`# z5{ddF(08hj^2M-1^8O3uv_%!9T+Jreax(}spYBWNb{pDMU!U;ZA*v?^ zNexk1?nL8-dTA4tmRJscw6m93uLb+d*_%x~7F-9FZDq($&&PbMW2;(hQ8?S zb(brASw13PnFtRybuG1{LDGWLQgDbZ1iPqUTIC;cPD$)2ut?)Bay!+3x;qbxageJ^ zS-9+Vpmd|d$${G}pN3)7cJ63Zt&Eip=g1N24OjsV=hcN`rD@l)o~;fD?8^;V!lb@q z3hDDmeAsM_KLTHxPkxE@sQfLJU-PKnakZXhNk+jZya(Ts#i{;m+}ES+rW0zU{i!b) z;URyjmAJSiYa`I_DVpsZ|I;kVy!ez9mu~0E*<(XjMZD&vTW#)+__aw!nC{;=TJ^K2 zO{Z3}kNqPx<{{_xEU}+0a6y~=I?ZRu2s;D((o|FjKEdMK`i*2JFNo=*3=)Rxsxg_T zAhJ9lhz@!^F|2)wOR~dx!Du@;(f^pWth0BPny_^(EwS3&d^WJnEJvtRTBP#kv!rHr zXayORJjPn&yfl{4%b6&I6>MgPkmPw^BxTA<=T3JtVaZ!wd91kba9};#Z?- zt6t`9p4=NK7IDE+LvfrGd52)g>VSVO+`#%_r-h^MTa6S8-;P<)`GUX3%$y@=(N`H_ zF~)%_#$c}6b^;~Ob-9gEDP4vobZ5GPye6B4A4_xi0j+pOD464jmLaBi##) zhUWE&lFAWxrG*ZB}{(4I99KXgb zJSmwQ(UQDTUDrPEn!%P_5WWdEM)aUc?TS489Va>pfN375?X~K>)RX5zS$l&^n6jL3 zKxx>|qwaAL0lAL-;$x48epTDi>XN84Bg=yIGXRbnV&bAcDQ)!-L33}&Ufj(>VpksD zkMbLf*EH|=x&{fnKc-YS@ucQnRsGoTTgI~KI{1&7-Hk4hLsQQKZshqvZi_!5x|yaW zX6qz$&!q@u?zrUE+8?Ef(Gjxl;U`K6jjEI>=O>IUr=|%rG!Bf`pRPT0>MOKR{x*0% zpEXezUN&M_j0@|?44Z`s{VsaWd|yjk=(h^9`#t=Nv>aC)?v?R9Y$rF@jxZ#p^k&!_ zvQ_6`m$-U#QL#U8<+{WvCuSk9q8vkRlwEey+F0ZQHA2oy1@3!wAs@RU@r{$pxk}%k zOWA<5S7#qwmSpAZst)X~R|xN-Elg@b#WLxWxuc!*p#R>xT&Yjb3ca@n0k%*%DSZ_MybISqDyJv!shj9NYFYhZz51;{ zM`j`3CNxkZjwXuY6E%tNx8<`1cvr*w^t0I4EUSqD>A+fbtv2n>kf!I_%+`O?vU7;& z;K<>)2!s2x28^7mLJ-<}3mQufXJI@V%pS5*W7EZJ1g7Hu?_R1@R4`vhaqQiM-WKa zyEE>{zXnPa?22|~j)&M_#VcgT7B=*N~BHuw>{tUQOPo)g4)o~Qk6 z`;{wrUsyD*>qeB;=?z#OiT=v+zsIVBP`ztO4_%a2b#JI9h0rdGvZ$4nNh*!sp#u*}f=#{mWvoBGhIjH5a%pP4f^-XyvDqNO}07Lib)l^v>7~TBhpdk@(W~>8@SF4KUnq=4H&=8&_>nTgK;HRi&pQZafZq70z9^FM3zuH!& znPwT;-o_T)RbT4NV#9-w_AxNVf5R9hME(u}cDNQxlNW!5Ht#pmx%}x@70z#C7ZsPW z-!D1QPZ!|2BLpV7LkJg{?UJNr@-TGQMgnlIAT2AlC*){i}I}} zSCIX+p(c-nA>Q9FntzR=a*GC){lW(Piv}(4@`W!{KBE+v3;(7g{)9zf?*4#8!u;`n zeNC5f?_SAxa=xtltsTh3vgG+CJhr5ci7)^01^zT2J>x;ip}O`tdMT6lWzY1E>#ppN z*0Yh(wRz7kem}EIEHo5l<|N__oV=)%WafhD?Z01aNco8yvP{&63n=~gDbphr>>69m zlmWKlxc$L;>bwsNay@?8HByi0|Grc0`b-_Dec}<*t|$&A&lWc{Do_FL;2}e+2~xuL z4ctndz18^fhY_nHMEnso$z2n-t&*)-rP+Jb#FgooaVr&dJiNF6;wJ#~%JlXN2>{b> zR$TjJGq)_1{AE=buUFz}z?P1EL5Dz9se^#zp-SPmZ&+nGDGlJ}tK zb87)FL9V?UuHVe3e{@wNO3XF4$AfLM1C?4uw9Fv+ee;olhawb-T*7rx(hyNh7tkpy zeMOqV<~2b721=)B9Ur`fb((+JDj`vgN>Tb4%+c^}o;^(PsO*E+EIUi_df8DUYWV8<;k?+K3tmP?UpF!D=Zhxg=NQN`DA*tFm1<~7dJs< zSKH6hw`vb^PN|qTCB*ic=ciK>+<>qll}h9KLO->e7DRKiwl8T~GM)~=65P!* zkTdu7kbmddzaVD>!tYJ^FL*Fqv16@nee;UfUjrE}jg9;|ZD?oW0x@ArOkWb+B)ay} z`=TVkDju#k&UtP}(y9a7xYd6#l zn@^=JxFtoxq*=%rDnp%eY?!r6cV-PCo=!3etx9#_x-xT}9vG$N;;`2#$D73+yo($U zj=rejWRc$>(`51nI+5@hk~mXl`q^%bZsh5C_2 zz#dlPz6!_bHW27-<&6~npV(bdUmC8XUZo%4%U z%#5&xS37&LV`L9PtAyWF`BM;$s5%=8>4O_xg`F5(6eMUxZZH-JU8S0lrF+F?~ zN0$71o}>Eoj3V)65C46kP`3m5=al>k9ilYdF3kqJ8|$f8q3`0x4#(CU()O%1S)$Nffn&6EjkOeN2PFtsd^H&Je8W=$jE5{c686oX`jz z;hX##q32(xr}ANKr|DNMAm@x|?d{USFuZ`BRhHw|UEmWg z@wky3?u?M}kCFgG)6l!527>h?S6n_GJAuv9m@Qj0UNs?k8`PM0`KKJV_J0b2_=qdvNA>zPA_1Nne~F4Al}?zo#yfQ%hzHw9sXXMxg!w z?ln=>!2xT;>!e!?Nj6SRQW+nw-a=ECIHJ!Ira>zy`?zbTLlgO%)0P5Vz1S7c(eiA4 z>efi&4G;5WdB1o>KCy@A;0=|EvHBYzsA;P;FSss~hO|q*d5fX=D!nRh^i<~Gzo;f< z+bVt1RJxK^Roqy}c~WnSEzvvuZb{l_F>>BJHwxE%zppz+Lk z*0Ejg{n(l^>92-=>fU5TH!1Jb@^@8ar$h@<%fHKI@w6}f;=P1i2+rgTQ(FdEU0u~a z+~WCsu`aJ+z@!W9OlN7rcDHXo6#ecCFJ5GXUuDTF1nti`R4$(#Zi*)79aXRDf=E2W zTG8>|vCXjiB=>t=o5V_N1%Fe8MlktRydOQp;Mi85F4yE&19vI(ygEbLHX+{+DxT-9 zuTcuct9IzrOt2H5csJXPJGKh}7mA(KPd|}^l97rTM*Ikw+8kPk8ShGH=tKRmXo3sk z80!S(b39FfQH8Bp$9+i!K-Q|z;Cwn8RFl6gclKNs^mpyPR$!Y^7@O1O@H%#B}7u-LP zdOp@_xztLJ)R#tA8X|S^mU)56aUdU41gZ!3GYZ4!U9Q|8nkrjxIHRK0vx>>=yCqm^ zTkV!;k4j5QE_BT!=@@Tn$GzSQo`J5c?&T&OW%2%QMq1d8lQDnfO?P^p&DF0=)wSX% z*vBr*x_88_3-R`?j zz7PS3s^^CD)i4>Ow4{NVbzPAkZd%>DT6D310y`4BX@EOC16quU>mbe!RuHbT=y<@3 zD@JxCr`PWY2#%z#{LOt9aanNW8W{tP5_RtHO_)J(;crfWX)OyO*F4LL7ORO<@TN~H zFlM|rQ^rEpxxxJ=jD~OEwTnQNar<&D9O>%uxKYrcL0;e_lSGY`$$` z#DI-xhK8sRXMYX^&v<-ozfWG}^vI`{$ofuY4*t%DJP6)vUT5el%9LA8ehLMwgj*;Z z=Nb{&iv9m8r)FG))e|8Edp~*^Jbe7XBQsE-!HhtI)eVk3EGI6yx4f)f0Y8>YHQ{&? z+>QTsgr{KbjFNL6-%o{!UazB<1VOrc+q-7zI1dc$^M+uMrA5{8ESb8ZCK5ItO6~;&%V?yh?W} zevjB2c~>?BqXYz|VvNWBSh7t^1LtI=yMxT+FuSt?P_kn4gNw>MZm)X@79K_i}R*gT(`Jf6Z8xR$Vne&bCH9x9p*f?)g4@gXVX8v|-ST-FL$YhQR zbyiSxZk>Ardl$hw7t0l`p<$G0|E`)nlPRFgujgsyZR1RpJY+_+(&g8Lfp)XM^h>%E zEFnS#S&hHT@TBi8PoAX3N0HV`IH$c>~ z)i-vhCO^wa9rOHp&h9MBpV8(1YnVEhZ*9 z+619RO0u8?O9U^z*weecX}sTV&S0D8$%D4$Iq8xE`oJY()o%ksIJz1o z%P>fZZ4c-o)oNl*by|M5gMd9{|F^%x2 z)FcJQBbI_|*zFWv;ZtGPtl^6#gHo*31OtD|Cx<1SXR@K8N^MrXJB`&Jni-TX8V&Hq zvhx_e-1A`EH($skhrlB_SpK&@M?;rfLwEuF*=6A01R|rz5I?NwDLESx6mRe|zX=zk zDFSi#A0b1=vR}<)>Hl!)0zu^+_>5{uWgOu1s)QhxAHVhDnyi$M(Bjk_T1mztJxbkI zmQnp|Lf`rUt6$j&t_M{IcsP`8z)Ucr(Pdp)^%lvT$i~Q}mNRMus*>nSyOfZ=i!cbh zzV(mUnVNaA-r08 z84$9+NM!C2Z(pA4IWA6ojcR%a?`q_@w(t`WM$$2o*jouRcx=hCVhdOL?SYvrc2`t% zyrT%m?hROdLryoHq;5k)H*{dhn+lyaqnw-=t7&=DP4iczC}r4i_kB@Rw^3l@tIWH% zXFKOljx1ozsMIn19}XH;)wQv6&P#lmu2;}Y{WKqcWh&!GYRNBKcgv>u`|s@C)YG~X zuv04F*&Q$wYCH4R6EhOr=RERyWrcN@a3+4cZt-doEN#2^j)GSCfSBHqdE*xQ9^){b zzx*0U-M*^11FgSr1IP1yV(%eMNVNP`M%kSxSV8*L59RKYnU>o}1cF<+&ZUE+F?Vc2 z1Me&pE%pPDThU3VE97qkzuzu)oGe3rBe5p_zS8!??$iRr-9}DM`~GO~jjBt&6ZUZI zPrfD_)?3m34UupoK~q*b-2=7oi`aKnn>~*2&$2UV9KD$Gw&_*NzA655-slL(z4WnX zwQzdPM_9&Mv&hol`2`h;5 zU7SHsLTEc@rklMY147ZBtae>H5&xbTXY<=R4XR=@tra1j%*`PMteXiThx!0Lrx}a0&LiaT zl|tDAi|T|6&0zOTs^Mq0i7fY?RKt5`0B)-cUJZBDt@idpkHzPI|27b{kU^OIEM`*0 zCpQgdB6sAhf&xYg4dFFwK^}^+cWuct|%8v4#-$(aRgl4zJH5%rc?**lRPa z6Sr;Aoz9;Rw$*rk918vwqO3A6HkbVP>PHvvt~QT&A1)!{+K@ifP?;-2FQ*lvN^p!* zp+ibQhU1s%yl9)yzQRkC-xNiNvSy~6VSfr>Yd8(75I}w~yBm!tn2_X@Q;gs0Zi82B8d>9i&2(fSJNV5O zvmdrFAB)P*HAmUWmQc`RR z4)SJu9=B9ow=#Vklj*_$A7U(ho_iktdIE0T7T&vqj<5Ld%S>SCo=MyCTZ2}Pw@{hM z2lUVpD<-VOo2G%^$Ch_%QSK1;_I^^N#%&&tb`9dLs?YvXP`b4SGxZ^R4pL)_|88n` z>7iEO!U&Li^{U{Xvt34LNK7Uy1?9TQ^jIe0yx<}LP%}kC#l)CfDL4c|vEyO-I7dW*D?FXF zO=ky8MSI=oXYqH>rDbfGZAbS-f`SE-*sfL-F&KDi*qU1!AK@86&&AVxq)!-<>1P z{JKlgM(CckNj%jM+ckB&vooQWOut5F)o3=g z@Q2b|yITitn(j!EdU%#`g<}IyC6K}Qtbh0ESo0dv%lz)!yNZRn8a1fJB~9u@dvzdHVoy+H*J^@ zUY5PDU<}PeB(x1bOW9!;6Xt^Sgyh_`$U?|2vDplXP&32)#+xg@-^8Ofgh{(U9; z*H17k)-;z$wQgUqArrq=EO?0?o5Ffx?ivT4QbaF5%;;L6bGbs~`u-J}zddJ|2bujP zyIQ;E#T{&OiQWcgxGTh#0FLl*gzOj=M6vPkge911Li)sZjbx__ zRuSm6d+gxk7f5uv0N#yQKVoh6pt&=RDyY|K|%PyGPVg2xnI4f>BylXx79UJI1Yu< zc%Cr|c3EgHaQtOx57~K)3^|F+p>%74TS!}3ycH>2}7GMz%zIj>EMYx+el3~{a73ci*ys!%%zE{Z2-jsPcE)F|Cwy7=2)GY?B}L1 zq9dAPSgnZ91rY#PaTtVSR}v4`!X_WP?6u2*`B@E%<2LDJ10m)&yUvaGiAOy5mX;W? z3e?Dsc5qGj|1DAN#qD^q0DqUGBTIU<|4xgR@9?%A29WNqEq;y{wnmLKxy#9$`bR3< zn;mOeQUHg^VAFb(@-G%LUrB|gU+l%bd7g}2z)gMTfyL=j@(GI)Z4^5*6>_yr8+*2I zQ+NmqC@^!q6_pF(%0`M#fTndM9uD3GC3sSk1Y)1k9G%~qz6IYV_Pz_tLp|m`CH-Y5~3B!tY!@OZp#F+1l?uSs?FTDN>8u#)|7%;h;Gy9N+t z;>3>&fe5V7Q#<#jzyj6@n7CW&Hi+6!1|I)PI(w%x$B+2fcpC@p6kE*PzbX&}rX$(} zwT%q8&Ww`~XI9XIw`yGKs~4Zb;)`>xq_)9P5vC=*;7-jievwIl0(x!z{jxO;Ow~J4 zjqGkk%v~lM<;kX8q!r;o%WrO&pMCJHHBgUXbBJJ9$w9Q;Nz5()gv_mMSk4OM)JSmM zO6T>vPt-qsK$)`the+ZN+AViFUMcc88@p0kV2yOl0v=PNkIbcU`Jf?1u}%gpD%xa{>e|p)Dyb-~@A#N5ggiE4IaULX@7~5+ z)M!b#7{7AbS}*G=9^zmioEk)HCdYr+y12&hQkh z^?G;|k@*F3BVZ@&Ma;X zm@{XraG@V7&6ihwuK5X#0$aZG)Q4le;7EmjM7GrA_(f-QZ02IbbXkW%Gu*LOGEt$Y zFx%+I%Gu~#blW$|o{Q_GE|n|gUN@}lF4ndiwh?HG8|<+|LNMVnh`xt?zz)TY{;vU< z>TDW&U^?uzY+LhvG#T^_Zb+`EHe@YRQ66a7T(dfyLC&(G-2v&WR9v4H|OiSV&HkeFf+1~K#H_d zNE8(rvLGRf@y-ll-MZfU+ZXCAoKOYes;s?VDP;Y-Rox@`VS2VJ{@s6`Ijj+5+Scsx zWmt){_vSv_aS;((K3U+t)J6H1&`HF;H&2@*=6}THUIT@e-UwVbJ-mRYu`p_fR*lND z=|Rh;KnR6PhtG&hd*^VJda@_Rt@(9RgIrY#xHQ*3h$L`!P7wdpRkj#-j9h!WIgpL1 z@xl7P9db;*=%sXb>7gk71FY6xiuAt_|3A) zZp1F*KO=zNo?M@hkp5sFhB_}(!K1<$4`OiK)c-PBDfZEbbrtTN-|JVwL915sz$PtOqnb%^-0M$?q3Q-!*Iy-Bq5}t4?xZB@R%oDSIz!@A{S-j6Re-X# zJsQl)$@H{^DGCp`de?iEE#8Y)g+xK?yd%Tdh{~jCDf9$Ha89=8~zjV?$SH}mFHu#Z1tt^$VX4qQ}Wy;~sR2-*5MyV!s z)Zhy#NGVIs05i{YR{>L^OVj|O4o(thRRs^(%%~2Xz0Y0II0XwQAIcv4dyrv$ z2J9Y*VUQ54D7snV3rx%0_~D~Pj3g;^Q93pk_ZGUC$7W5zF;n?m(x5>;=TH_n{l5BF zW1nL$*T4MH_zB9=8XxeuRGN<_K?9&ASB_STKJznF3UyxY6of5Nh_Tm;8S`<4i?Nf= zX?diW54v-${iiAcXCc=UVpqfn__VOdMCkUs-{F%SPhBTu)1wZS#0%>-!f{O{c};k& zr&@S}0Aw)Tm}`M0?5KE-a1E$OBey*8+Ym;r$?`I#qfj&+sTI9tQQe5rTkYX?J-RLq zT~&pGhi7j@Ud{}die6Hb%-UVo3hj*m)g~>+n;eNtGdDiCzR10}dW9ogv_~x67b-6p z(Pl%3?zw99aBba1os^WwaBJqz#uAipKvpcPAOrg3h~9Ef5fPyW(Zl7lkM*#)zW3+H zJ1$og)P>hBRsCKV^EA~8j+Lw4O#v13DJx$CmHozsj@4ZgrN NlD-$yFT#aiUNa( z>;iU>(qBYIcHw3s*V9m>KxWK~+(`c=F+Dy~4ll>M<4z!Wp~$~krUN>_h(iui1@}@4 z+Rb@YE!%BBLCL*zRz>4(z0X=(mF6`Lh*a2YEMx48P!wJ({wXF4y-eV%X()jsS-FTn zwo|iFXCdXteesfX)koow2we0Bk*|Zn6mR+_Dn^)?#*zJfffx1yu1>+Q7R3)MOr=qK zaEDq!sab7=!0pl+-5reoeMgkpt0*s8CXS9JA4Yznll3nka1o=njFP$Ioh-Q9-c7fk zN0obQux($`S(?}2{I^|Hp{+iAPf%u&N!n>DW%mxukGnVX^Z{8B*yUIXY#S%xTB3~Kx+2&iot#P9{SRqR`~SjzygL+TROo1pv*BSFz@%|%|!mR71LL}3L#M! z^~fv5Cfpd}6Z7Jeuwr?%P~#%@$`G&};LpFG&yCM!K)XR;)PYk{xWRN3~x>QCUeiAIraY+~BucZ9Qu zl8*AazcN}ERu4&G7&5F^F6Di)xrfZgk|uCwc02{{Ry|yS4b&?nM zu#Oc(KCD_ffR-&C-VML2RP=8laJ3om1yFNhBU?F?L=vv)0--T#7oYoo#Q8`Ya&o9S z-n?%ntcWs3lM|Etb{wnL174#u1!?i{h+;XT=^~wFGiK!v4(huP0YcOzkswX{RIO-5P6sT!g*_3VB&PQ< zz&oG>^^8_#@z?fd>Wez}zZqS;o4bJTh0GvHj9~Is$y2Zn^(XA0MTi(^%!)&=Gi%+h4bD0jj;@$#NThZT=HU59Ge;X(k!)dSe$6HRE8;;yaRv^R7bZAWX zHtJNtsGJIf*!Kp=<}fN2Xc8fKU0v&*5KJKxk;+MUeFdhqna4?MU%eV=F6uM?v)kv^ z3DI@T-MTll&i$==y7!nrg`*|@NT&8M;3$Z%Rs`>wCQCPC*>I*NBoHt1i8uwpY)*)KY0Ox*a_{c^_(>;=VCVf&mdbubiBva94QR|6X#Cy zbRo3pLV|@$1bJX+KD7Tl7`t?9wyB&EuS}TEwR|10(gc6=&TzhTo#mtau;&#b(SoNo zhnko^meHMu5M+y#$nCGBfw(JNoDT!G?tzkvn_-5D~4j3C`*af!cj~F!Hs(r z62kV3h5Ywwd_|OK)RLA!E3%}J?Z5>_5C^M!Q=m@?8d&sNZ}Keq^Z^b0PwDM24wgvI z$i_&khqKEGE&Wj$$Q-V(@-7V6>iVmvf&&9*BL8(*bSt(9mwfFe+>(H&G)B-rU%LrL z_%K%}HWt%FW{{?jKe9S>xfBP5k*P%}P*sEo41XHZGBrDAe_F;$usHLc@pj z$hn8KO1x}v!SfNj0$!Ma{VSvu-at*!`18UsBjl7XYiLNKhY-9OxYAi*#O3yOU_irX ze--BP@@O_y2@2`h)m6PV5%1@KwTU$M3|4{H7;O2UjmOu`)YhbZ9;6N$ThA+-Ssrq` zM{ju;$BuRtLX4dC44vBhHCE`m3;y~|pO8fO&`qXZTFP?}E;SxmMiGd7__&5p@#g02 z;vS|lGPp+naRK4j_)#6ahWa(-qeQ6`4*wYw?dE)wNC37MU}3xs&UuzY@r)k~jP&hJ z9kUTT)!f}ZANonLP#>OLUlE8-O=R(W9wkr+j#mP9e!yX79B+2-zo?jTdVKB)zX9-s z`6w!)PWJShW+nKfIaT4ibu)+=>l_2@??A*&pz{VPVL6iDgE<>cRKrYtAB?Zb+v|7q z&JJ{mvnH(r%)1yv(gA?-{ewB)sTMELS-=RV`w!kN@r5RvQlJ$UKJV^Y*pCQCxB5JO z*=T)CQR&rxtxiA}1b@BtKS}?HbY3@#kM6vYtp12urqi!icXFXs`sPyvThz9a6$7BI58IS?Yo~dxCbIg)*E!AwQA5=S0D= z>OGg-07{+_leoAR@{I=6?6o21=Q6(bff{e^Wa+TCE{QNX#~$xA-MYCr&mI)1JFR4) z*6zK`rnZLf;dE8v=?;-p8@7_(< z1XizShhY}7{vlN!tp-Cb*e&E6CYd;_Qf)sD6$dCN`8X}sWz-4z@{3fir~aXzvtdsi z9{zYB#83T{4{SNTN`6+a?$Al?r5#$3GbCbKK4D;7w|KFa; zGa`R(H)dF}m+!x$;v2pFU|mDiJZ>=fPDb{%a&>yysD&y@K$|Eqp~D;G!;{)Tf#Idg z%uA7SHMqPNJkE_CAR*r(S)AXgxm?M;{VKux&ah+l?=-R*O87{`?k-+^o%{XGAAooy zq_=I2zIu_g zYZodY&X3HZx3n$a==s?)n%_Rbpg$7&u%+a!h3v<&BEiMB6@>2z+g|v`-D8qYQ`LZDg!6cHuQQe7A!e7FGWKk*uB{Dd4(n zhv>5iyesIh<#$%Fq-B{wnHTdj_bIBrMTf%%-y+OamqE9|9%CH*EDpW8D)?xc5(>Yxk=yZ%9M62pQw?W z->J1fPusrF2rMwgu46Y7q&}BD_?GX;aXyHNu|y~QVjO*aC%>tNhn2HpuPmfV@EfK( z`-$KVnUF5*>(czQM>4?B`dq?Wq*>>|bono}NT3O5l`{#f~912ziFW#^2j@k=!P?)bi@@9nAp*Q(KCw7CbQ|_~) zJyyNFNixFA^4JR(4rjFnfSCMK>@5=YuqQ$jv zMPscEMX$tnU>@6{jGHod9tW6vjy8Iv%gC|^aK#yJ)YSVZelP{S93Rhh2H;9k&kn?> zh$p!_V?F#Zzt2tO=^*A`e^+kqV+k$Gt%eb$MVE6Y^Ef(Q^=Na)dLOQuDR35Fg4(Fy z(_;bly;tY)>C~MZ`d=60XoIXqM6iuT;8+_X zW@T_Mb9{$C^0-TkD=)s$q5e3Ohl4pQdB;>IZDg{=W`mA6=eOcCzLja!G+lCMefxbo zY>XN*m7sUjVufuZLp!Jo%*~E%ckd!DZ+RJx*t1oy{l}2rpLWMOGM0?ce@kpi{}@Eqj=F)7@WAioHLTf(nFz0S6FTf4>js)fiHE{Oi;=Xnym}m3 zO0pMsF;C`>teN?bL%{r!!;j7->b(JxHJA7KouXVk)?Z3|Il>?CLRt(UR>yre8OZtA zU~h6l+#l56qqV;F-dwf6ljdSY$s>v>k7DiyWs|FpjfL^T47I$vvc3qHnPgGQ}eFn8cK?lqFw5J(oo#$fGmzrhY=Mf<+LTk?| z<|q=azSvnF8S2V+h@2JNghdG|G9J29bxg)xqp#Pp9tr1SMrrOhRUu$i(B})+be(Py z5TU9Ii5&r^uR=Sx^0v_p^x;`wyV?+Bs)>zBGz0#9gSs@OvTL&Sh8OmXnoIIRX|-R` zP74_fvpGBA()4t^9Bdvph!Iq7_Pb6sV=ktdTzA7Q;I*%E5j9ie_ zY5CTf*+b{1UiZdXrowyD%0xMjM9#SGj8wJ9w2VRDw|ZL^6g_3bBXP&W!85Xc^#U(3 zvoEE3rrcNq_X6`kPoP9?kciNVt;RN^t)S$g85(v^wbmcHWWopXo#)NSr>tWW(^9jS zN(yfp%GET|F@4R*X%*aEm3z@N5r6XxZo+q6R$OjEYf{#OfY4Wy8M1>NooW{_u4$UU zeB*5mMLS(64R@a!*_YPbkh;UCEgGKo9Yt|l4XarG1u?!8ziq|$*&4=)sSD>T-ro=Q zPyf(#T{F@@{aMq0DlH8kwZ2)pJGV@jw{cUs%zKP;#C@jPKt7Zx3E>79&zV->mX8cj z(NHkw9&S8ht(H1vSClBRa~7OOnSWu;LSsd1;V)=DdhO%Buvugr7y6oiVJq>}(xi~Q zd3-m#o}PkspvH?`>UMEgU$Fmc`CW==!CEO%Rx7hQ*JVx<7z}%=vKFk?1&4PTUBeE; z--j35n_(r$LeyVMSm3cKvqIbx}9S{7-5H zfTh^|UH1-Vcv*ZM`&GV9CN39n16|^!3()?_b>We2d4b=37*cJLtBUu2R8aSHi8yB7 zo5AdSF<+9I&`bnz-O4TQ!$r`EZ0b*%;1(f^c(0G3=yA|$e7__vAL;mx$*@V&<6zon zn)iPkopoH3T?2++r9=j(2#l5xq(?}H5-N?-lA{qMN0-zFj1Z760qG$f0s^Bur8`I0 z=<<8~{&9i7!RkEEIp@Bw%eD-+?NuHixoZ>S1*pTakc}ex=!S`nE%71txefvckU0lz zbnQkxj|sUC{A;SCXDNi@8bR5XiQqRVkb6%x!XNIRbxd?ngM#LNbW6;t+{eNcwZx1n z?(>g348g+=-xO^ptrH(P*Ay6X!vlmrG)u4z(U`I%&MYj-)A3N~$Z;kz6(>7P0mbik zw|;u2ETbU-(jS^9c*-%(CZtCnnzb1{C!QK-hxeNv=@1#bzJpGlvg$UnT>ANTM`ej$ z8xCZ71aVsH`3#)^6`KV`@13o6NxeH2bCRFC4&`s#UNxum8$C-84jvfYIM7WX{pPVe z*UC_*()cL>5C&k&+L0R+>qyo%b%v%1!SWti<$$Ya6c%n`e+bG0LCH}=L>M)OKPy-L zuO_tI-*vs3*i&LFcUz9kRvD4(!6fl7%8^JRtJo|4TKx6uZbUM?DHUUtlZ~H{r|$oy zSjDcg7c#J7rm^wN+bu;B@yL62>%ga_toqf@I{GBU8MGzIUymx)O;x6=Z)x{CFiB2a zM@s>dA7w|7&#*v`E*vc-M*4D7B%!)sRm!V|w^RQQU)D_of5N)%j1&jVPwFUcKIS6h z>mL5vH?@9M{-8BLm1sq*zYWaX$%r(jqBN!usZVjD@$(}(^t*|0%G0v%^HIZ1w`34o z&H-xG?h%S!4=)3 zP?SD!Wpw?WnQ_sL&eQh6K9!|j9xHF@l9~t zdpblvaWNKG`#uM9UtN`;0n6lkk^b<)B0h!Vqi*CAew|*P6trMX-RKU-A}_N4X&C44 zpU3MjIzNHmRry4IGQX^{c71-%%PQFQ>L>E&2L_@KhOmQE1BZ96k8J=oM4+aQ;T{l@ zmMXS(aq)Yh#n(8!^{Qy+y20-*eLa2*vwggmkx6gk3v->;mFVKGKtE?d8a0@tB;xq& z3vVpt-kEg73gh?!*RwpCHcvh!;lWlCqb?2f14zLWyzl@KN=ux)fA0EJleAzAa6ArV zB$QqNeOnw~Ymms#Sd0fgRif?g1FZs;_{^Cm7`>)+ck39nGMB0K21|g_V;M7PH}K)t zFNDe_SlS~n9dR7F*40E*-Mj(m(~Tnhj!n;OzaH-{nsF&$(zxc405WDi*XGAE>;sKqM0C3Arm(UnRRRYS;{3r`LN3tg+sxRG) zrtSl`!G+UXCg`CGbv6tY%@7aL3dm<2(PocKZ#tq8rR9Bgq>liqrAB1BnIpST5wu!{ zCL&(M6-_hr&XBzUm0?XC{3pJm@8(cmB+qJ9K|!$onEbl6<^7a=o(3O?HpFlPp%cNk zd|9?p8byA#86LL3n3WnAecD~Dnk@}bEAF;gu>Gc?e92h0Vo|U(NJD%fsrksZ{e`Kw zM;MJp?vHQ!arZx{^k&U{v?0f@r^_~+zG7nbEIQG$i;g#beXO}8nqE^ktI13;Ef54M#m#{za5i&NKO)@V7Ltz#pgl3}>vcq|&+7aKxi z*hbVweiW~>Jt&|Z{PEXH#g`q_M2okjz|_hk+ok8ONzRU;r>YaAsrRT5C{y0hwl5K~ zr}@VfLgm?}qC&5yL6VGA8dLF4$nIJ02TsS4n2>UP@z29ajsxI0Edk0vLG_}82#3J= zMJtZ7qhDDjD8wn$$#3bEl>8LF^3Oq1+U_hD!A*$Jktyg};U+468l2S+dp5?pXdy8c z(ElE=JUBiBperNH7d$-eG~K+?VbL3ua8i`9Sd2|bjIZ9t$v*^woR9a%wFW?Yz9$QP z?w5EJMAPm0B1JC3m(t;x2D#pau4Be3PlYu+fFQXkiT~Q2eE8B&$FkjBg2{Ea7@N!& zLJ1c;8^;*rKsO7D?+)>g-=$$#7wuJ4Hw*I*BrqE=ks;%B-b!Dc6$v$&uKHOv`VUQ4 zarNY7+4&hwJA%Tg3?AERV?n~w3r-n+1-(FClHk*Fa(OJJWg7`EtbS}79X-W|<)e(- za_6=ZBL4+p+YD{AJink!YaV6c^y62o`=S!}ZhVlENRji00@seY@!xkZf12(+?29o< z!W9c7l%mL17&=fKunTd9(o27*SjMn~+i6%8xtMV2QS~&_SrMGFRX~A# z8($LO$_xuSGRS|FFsVSvr#rC?v4eg9GG)~%;JW5ih1~$x=Tive*0TCl;NUuA+>E8wK9$4H)b#%pw z?_6e$g#cUqmFwzMkCQY(L6sKli{-lN%;ald2cGxT>Htfx?ioZlP>rlo(LeJnz-9oI z>-8x6An73K`t@EeL0ijYKR=?Qt5tN*^N-Jw9n8b8z*srG9%?W7W8Px`dxE=Q@D^>U z(UBu}SERt+1JUd$)#X@J`LO&x+b6$L&?=L|^Wn7=g(kmmM`}rtMOL3)Q>N~eKTAh% zc~g<0hj|0Qr}fdQ(ADbG6-_AkZzt_Xe)Y^yuupTbW*dHY3g6{;E(?Z?$x!?o=+l{tvp}xM14uJKJ7iP z7{=yH!*FUO#@_!w+ z$L4i?ForeVXeP8OX|xb}PaHUBaQ;zG1aN7Zt`y@-mwYN!e|lY9G75`6L6OjXpo=bG!QQhRe-OvkADDXAq2j8C8O(P!gS&!(W>-xb9_G^{AAHJ@8Q7JxWM z%6;UP;sKis+E)F$?y$QRH@e1(yIKc;@jz`%DTx zu8GcRFj(0Yi1GZ1;M2jj0vMh(@)YRiG?H*gmB9ILP}f)DplY&avw6e(%x8d~tEc$6 zS)Dr%C{e6gAbrbaqt&Dk%Q-F~j$ev{@zziP@%-ZZ2Dj(XoAPED`o}B6k~U-*gGp zD!B7MJZR;(30htG|1D`_kjpy9)67QIkWv}Shp`T=FV&WRInxQngC*Uyd6FtA12)1U z^Akc!+4hiy%ClTV#%eQ{Xu&*v3gD-RQMKKUni~iYZ361s3(F%d6&t@@Uc7r1E?{Gi(R+N9{$}St|%Eq!1jnGb7&ThNM zhL69q8qclY3_SaEH>FMa{?l1W?M$X?OxRkrpXqdNeZga3A@K(G-bZLmd7ws%Z>__# z^9BXfpJfy8+Z7|Zyrjkrz;?yglw+*NZEwE1KJIV;Ox}e*jg?blp>-nWenn&G72Wo_ zK0DV3pau9)PM9G)<<@1jWid>*_cOu?cS zLszXb=*ukYvS^%YE`E5=THA+YdW7FctK2r^AApZPUwj*snUyMN5ZmO-m$=d2((>F> z@KQdXny!we@1%o;2DuM4ZUPg9i*C}Nv4Y(!EuY7FZWgta136x*c{McP%uGGpoZ4wf zBQc20XioYCAOn_%mjlh7x2aPYHuY_(QvfZSxgZI)Wi~LrgtYd0N3>as3uQ(L0jYTG z!0!kD7U3(qP4kp0j_z4fCi6d9ZC$#@`fvzDQU`G)3+zS)Fj8*Rm{>W84Gof(y31jx zsGXpjmJa~{JWvl_$`WHB#u0Z5y)(xU*jql;0~Sn#1wy3=G8yWUUr$``!j>%Y_4+_B znjuwYOd1V}Vq1)~*~Jq%o2V)*lSYE~Z%7i5^Y8nas_ONip&RDrXM!QECX51({}CM% z{aJ756PwNA_rbsg)*#N+?loOlJ(8<22(8qlbkj7cMw_1yAXUIfk~2NtX6F4aF;HPuVdIUz>tBT0X{zQN16 zoaTJ1Ob8SqeHy0$E=aam>BD`~R9=vA4-e?)!wlxt&>nyxl*iRY+4i;zAYxq|&wY;G zdEqP~-371+w+BxGAQ5^mLIgf z(~u3_RPy1A+}aX7%ykm|=PxQVmWvTbnj3))c#~tKfY~hNO_=gHcaVXTn<=`SqRX6sVXGvK%q$iVxQhbY^c zsbLim34QA*eN(#v_PSTmiXu{L5zSMnXif2_%H^OQ=mY$Rg=Yu71;4;~P_Ff^tJm`V z+17d(JxFDXPpTYQvDtlynDj*ELvgh@&;2=90rw1{zHlpsnEv#96@Ka6o7i92Dut>h z`8G|Hb`AgG7!99)iybM0I4{K)0I9z|`Hmal)| zr;|ws@KY?hOn4JSRwd>Gb&m>Z;4UvXQ9^AdB$(3bol5tOR$6%J-1V*s2!g2m=!79~ z0n24t0gt;7*WD+^IUu4{tLKiB*@gpax7WlFB-m;HazUs?xPrw#-D_jIp~P<(BO4Vp zy#PBx>%_T@L4Dqn{f|o7eqjIg?@7V4Cmj&B8{orkCW*IdHo`d#G_Y|>*M1US+__;0 zjC#f<_vH}_1FsJ@3Mmh-0L}{lP6yH-bT|!OlXE`M{#238c{~0gAJ{L*6gPszx*hl` zx(mScnOVX33j-WCa%T(`jt%*yT|2V?R1T>EY3v@16ed&q95{L7F)8HnPyrU?yT}Uy zHZcuP%gYktwzJ&*S9?CV_FtlV_z8z(b;M!zpX+&OgQ`(5kJvu(*oXR~uG@4gCZx#C z<>7LYGf1KRg>F)tw2wDG==`Z6B^r_@iw*`lNC^22K$Q!m$F4LQv2>WjlH#z!Id@^P zIXU`8Q9C{we8xJAdwPvBO;gKtahHw}H#x8^!)~e{?%E|g1J&?#^DD#DpcXSgL6WuI zV(IB5XLBbt2>+aBdiQ|qNuekiB4f|4nsj3j&RZoDi?8`JeWB2G03*?d{ez+6lh`o; z>t^JK57=_KDSYO#a+`eSW7e3+&^X;i-FV>y%4qrk$dOs69xaVzSe;S=BvN{h*n|n@O%T_q4IZ5FD*o%1?2fVgN>+aPXI?5@ZaKwcM=y zq6Sjsy%Ll5z}-ApS+%=XlU&kUCeZ{e&QN~1l)GDz*@Z5VafW^=JnL<(?^b`*vOD>5 zmpJQ6!;C&D+1PS1BD$JGtg|VNLTV!WP$LIwUwq7#elQIg#;_&byrhsUu(ZA0=;Dy< zv@tD%u`6pX{EMoZ=$~xWP@n>bWP5h_QrcbJ;4~34aee@x z(=B+1_B`KuK`Wrvn2^i`5RT{kxb`B@WPfFJd%G8wOK1;T8>h_D0O5!)3jf=S8+6w* zw#*Uxy}}Auoj7Ge{b1q$fQY|%`L$m?_-F_=t@fV$V7kc$)BZ58^AFlw<ZjLdr++!t^o8OdUON4_XjVj>I+6K-?V*=@&n*|YQ$HDQRw=*gZV|64;Kn~ z4HVap>``kNALyutDV}eDTGNZU+A3Z}AJ=!N?&*D+n{(^k@dhCM<@fsm_8lUjI=j!k zUP-@^Zv;|>QUsI(39e-SHfqWbjwv0K`2hc)ub;2klG7hTCuu-p=3!P3-A`xR_-^Le z{L$n2`A&$LU-6@kcYf)XoRgj0l@N8)t+|SvoP$P&z~xDIO$NJjm0p^*uRi7^CEC5@4);qopN1ZM9 z8{8kL`L$ERURT)bTX5||DFGSH;`iTO;c)bV%i^vGYq|Mo?&kZ+1i;}m*3ar5+^PVo5~98Xr7TeDM*v{WxmwAe(}*mW*RzDEAx3@p_J8@-%5YXiyVWtwgq_Fd zq62R!BQV;F+iA}F#!2mBcJ6<~d7PseUz}#GqQ5lqh>!qilsmFPiiD%bxZnsa0bcp& zvyLd|em3-eKn2W6*(P*!;L&}3?Xi#fDz{!-jQx!mI3m^TTXcfb}rOFyDpUt%8%gikAH z0;ciIpmGu)Gul?Sf}kZMv=1?tk0J=z>{|YXw!*sbHlZGN_u;Sc>}aNCA4M21$&$8l zf$O))enxqNf5v_}DrP|;)p1vKfQD#UBgB7Iy@!{Yr0jbO(G;8XHewprj6j!`+RNG) zM2C5zp8I1FoeE8Z;!7Df{6|kWh&~D;GS0;K-%ka~~> zsYl`+qE#mM^CZR@{r=v%T3?<==YG7q$66e4p{~Z@zj->HmEZ)>v>LQ@@5&#f?}NUj z1|XLGU+o!e>eAX7`q%-1s*t;Oz>&oVNtJB(b0VoW_`(hkAoTaXx<;9P{5QBlKol9zqYt?MwR>6|&+;oW}$9 zZ$jKEw8b3-6*g{09e($sre_K$CwLYW&xXdWk~QL2rg0fzRogI~4=VSsOal{GfMlRu!E2FCt0tSXDco ziYop!)$My(Dc}kgXADpkl!cvJcyd8g{@&yM_TvLdq3CqD0(>5H*25hYqI@G;)I5&Uct8oSVlJV}4YvH{xSb?C zTYMXxYAa8sLNeFxhtIL|1l-|#v`BlTerWg~$m8_FJ72{6-#2;Yk1+nS7~qWHC}*b1 zPGmAGkENk+z_{8e1d^7|{0V`j3?F%oOc?=2gT;3(6Xdr%#m13c`$qM{N89x@8;*4` zb$rlc4Os%#hj46VwxT|7g9+->^Vnc7;=uAx9?3+@k0K6YuU)SBvjjn5QO~$Nb-FZOP4<281GI;B*{m!u2C%r`QURN16DZUbM1kGdDT7 z+33Ud^@qzHRTqGhB{0#r+ym%ArO6HcN=9ZQ>Jq7-N`M^$0PpRw!k>J}A{NaLX91OB zUMacj$5ugHhI?(Wgn!uc8Hzl-48c4thLL3_N zjS*IcCKoJvoHZHZ*R;|~kWZT%rh-mzbbwG#NlV%JeU9NUXIhX_V8i`*7N{rkb^j0Kmy;`6vnw);@c@ohDYCCs3-r`fac51Y!1p40&Qej|09_<7QGx^YZr zh|z6F0-|8qnNd3FQ{sII77&4-$)k1J1mz&7n|lJQD_`(WpGKTgV~%Iwsyn24o@6$5 zGg!xu`0&qSrg_X0K&&y)Grq=$kBb$S-k)WbI;sHAQU>xei|p&J4?6*m4R-Og;if8L zz?>}OH}8vd)aST^iiILrMUCvHuJjuTMuexeJ+9aS?pNVw#U?kyNZI+jJiy)20gC=y z|LWf42a7lRZeWHud*zdr3!k;AJ_54F7orTJz-g@ak9_e;9jZRgc}rSe#0s41d7de! zT4qc0-B|NYwEtzk|IH*|4{pAz{R^0c0fjKeALvLQmx@fF|D#_%J)ZA%2w;uju(b~RPW&y}qlc?^>Bbby>;wJ2-o*ve&FT@l1;WpM=0QTVSBBbF z1kqEsFMvko+S{gdr$y1xkW>WoXb_<`Z(E>v4X@={4le4iE)fpwCKT6wQ#T}vLI1_M z{H8~f7!Ma_x$a(sRqydEDH;+7U$?z3C+du*S;C~@wwblIau&Nd&IcUPQqq!bFuq+z z%QcfAIz)l$hgmwg)}Ga4u?+qH-mdot9)W#+rY|2o0wa~yaqdJVZtu0x{fWB4JR&3n ztrkDDa3bMzX@O)rE3J8wD=(`?5G*?;B05zK=s`-hgWXFYtYZmY#H`4lNNW8@lHdt> znXpENbhO_+fz;b9dXh=HmNLtU{-PyMpzwI-n1K*`hSwD=an$0RQEKe}G`8dceG9>7 zg3jvOjOC~2!mQ;$`4wN<8^cd*57{isZih;tx1JDm=Kcy)h1r;LMcZpt8ncdS^eTAJi5REWhmoZvm(Ts zY44~YWeHgo_dmV|8A}u$&Eds?1aQW1+tkxjL=iv__c1$8_|scNKoO2yNJ*JJ8uthdv$J$SGpZB`(8DDJqMo5gC z^e&JiIrN_Sbr+lrh>n%<(mA+>;8}OB=!-B!rja=pQD<9JY)wFQB&N{D0H@!E_wx3=;!bRq=oKqflX8h)(mHcfDD+N?sR@fiMdsW z5%9k5Ws>zY;8ygC*Me6V<%SK$m(g-XffBv?rrL!M8IX#IuMYhqMK9Q%;4y+m0Qj%Q^ z1A2%tCLcdA@U;y_&MZm4yNV5)?ry30p#Yiq$Q6_R415rR_gPgBGGL#(q!0o1Z-Hof zJ^Z18yE+h5#_{1PF!R%_?sb2TPls!s%;R)z%GD_TtlvEhF?{q!pukJ4=D&N=3uX8e z+uT1>Ni>-!U-faq;BTmw^ej>&9D^hdTGd|mlZX|WP6IfD-;l79*aHobQ>%h=60wD} zd&%`Lefg#x?y&AZHYeH5-9UFhD?+L zYX>A_>;Ng|P+LpbL-;Fm#kwr@z70L7c-tV~+#^}kk8gm(JBLxB`!z&cA+>hKGq!x! zlJed@BV8aN99<|m1XKZW=r=+d9y zdh2TL1E4jF4a1G$Cb}>NrN@#e3W*NRZyzi&Bq0y68vkGeU$D&eBUXT|Qm!kd8RX~} zZi3=)UAYOhhxv!J+m=HVtZt zY?{{bGKec1da+jwykgMpWp&O&wC?jg9Kt7zyZ}iGeHSl`E?a>?>7oFL%1b7vzKLuT zF45p|j%^_0k3@%{X=^xOtZhpVYvXz0O%oyLk)i>au5IZz7f(Jv@skK8z1G>0$*0Dz zo#giAONgplt#-6wD&4&2HIZSsL1 zgkdA z_mMVXvKYQlWxp|~f$?eD=|>Nr5=y$6e!L#<9OnZoN&98OYj8xaWNhP@Cx7 zKgy)2fi@bq&5;CvznuzRB`Z-zgyfA5@*+%7A7~U=xYP&`k2Oj@QVnTa6xiZ{c0MMT zYNeROLYHjgdBEBq6dUO|wSd{#VRg#r(N}%cI^XV7F#J5@#6P2K4AAUS>eh;V%lbJU zw47YPUu6BOLA4R$^Smg6<739*I3+wD`J_}Q^Fq1pX5YL5DEx9i$OFUqKer03S7US6 zq{M?Ern-oJ*VU(>9L*=U?f=3U}nuJK&e#`CCClaNW5tD!Y0_+{AOjVeaB`AGw%uqDQ;hmAB z2y$+=5WD)%=blVr6~jh;vC|)nJzs5&>H+2&;8&S|iBHT`?;z)KUUYnS2CAO(BgDS# z9=@LaP`aBo8Vyz=fwx?n6{NP0z?_b+8r~ytSMN-|7cZOlf2J||6mX;?Ih7#RIQL&$ zeptJzuGuInL+8qt?wBMi`;hRI>*C57Wu#v`HJxAyozXis-fMLrhx?%bV zHpGZ!RC?K$a_=WU(K!z~m9m$beiCC8O^Tq7Z|8;37ngKm{#=3Oe%ulGB0!H!G!gbK z(;htf-tVTryAtD=;0e(tu`Hf*L16J9^q1YIFTZKu>pZvE>=gYG@!x78&=p^Osw~(L za3E%d_RxAW6)d&O-U9Kl9<1VaZ=5PIv+;sN9F~cH&2LephxjxQjx+%k&v5pqbA&pz zzuQ~#i36VF>|bY6vWnr~eF6}0fLq%svjNZz|9s#^-*}*~00Y=0mXh-}RNoda70sPK+%bqCKEVBgJv)CF4OqKAtmW|<8I zEHL>uC779D)MDiA;fzDbf9t`*UH}CCgMF2&yI!&|Ah9WP&EF(d`fZRjJCUx&ze(hB zd4ttBT{>UP-$t*K2K&F7xcYl$Uh=orctXqvZ>~+sXEK1|z-KH@_&5%ri_Zn!yk)pr z3~KgoVK8;7F}(X4o&mPM_31|j0Idhjy{AA6Ls#=$9z&$z!^Kl1yD8Xa^8QrsBAGZy zemuuSgo5T?NX-KPQJSWkrSXp!qyRDSP<#0$^LVRP4UWFw#GADM6v4W)Kl1|&orJfS z3l(6Qk1`e$p%r63FD`7(Z%2v7s7zBh2JO#9j|M7qa68gJO%5Heyd-yfCHE14`b3~` z+$Lx=wK^-(c;Bd$#Q8MH3)dHEFL&`(8D>*Uyw%Y9w;LQG0zy4#R?U{uRz{F7PbzGd z6)Bm>U${Q;thP)7Mf8*Q!SNG9KC;DZ9qgVJlltbUd&yHm57da0zdT*3>|;VDvhg!t zKSEyaKfY?WB5NCqO;^0WLx0=HGb?94Nixd)4Cf({i)&5d zT}0F$Y~6*~+je_`N{rKy@Had5xaU*YmS3Tt`tS4v5yx8+UlAYK9~$P(Lmq|j&~@S) zgGIRmz4X(1^~VcYakEO1T5lTX>Y8(lRmhJQu5?iCU}Dx?pm2(DN6D2dxrdc z88lT|`6mgbwS_lWK~duP(wh`jIU~T?(2di_D$~<0xM8+!MCo`<#^Jm)sdrv(pF{6}{5hAIo})^w4v(!fW3-1@5SsD$M&r}3r(NaFh0 zO&M%1MDNJZID|{v+*dd`oX(VGGbBK{FBP*m5Hcp(5&yX4hZRlfh`q>S>ZX|%G9c%uvfUk2~x)TBrUY2Jv#ZwPr37x0Cenp{=N zcgx3Nurh82D_tUAoY3s2t_!DsN+Q2u`R7q=p*PO3bw&4<^1y$-9GhH0mu+QDJ<0|gR*}}$3NwAMx1%~`h1osC$nwv!8KrU znaKw5bJ*)W?kQbhq?Y#&9C`i2HLaikB8HE@sx*f~<)uiz;f>p2uo zB+V0;bFb6JhLjA{LO8m*?YuT zpJD|_zYtUPJx#xlCD<0@KWA{B6OELAawX@uC8pXr7O*nebm-2QO;;tLyZpH(A?vR? zA}g-XFvQ3-bovr;AVyjTHimhh&k%{w$deaNI<`!|2(R0nYs(`kPQnOzs}S-adGmz2 zT708g1>y|u_kAmUFNa+(qViLc7aU73uPiNeWC zKq2#*tBmD}+JXx|puOEwwZf2vHxP0CMgC8|hw<~l%AzSdu)X-oj9h8fkV9h0Gtcjj zn+SI?CK=@D3iZNYRvJUrp^8=0d03N*PyD zNRdsnI-L4N(L7h(#NX`Wn~3S}G%~d%zKE367_<|wTI--4IBAjXwR<~@RX!BOWp;Ve za?^QWbvi9gx9=qu!jLILd!DVlyer|*@?Z$fSEeDGLo<4G(CXyyV)ga=!v;s!G1FL4 z^94YMG_}eF9HaxL+H{Ntq6)axcaN0V_|l?oWw*?J_{x*QuWQ0Ja!)j@2-BL1iOTKPD) zfVKnBgh?yZ)R|*}yTR?2Zezp}0i7(~WSL}UtA6jLE0Xf3m5lBQ_^*$rBu)lKS;XLx zk@J8QaZ8HKdLSZCepckmVF=!~YIUa6Lmxe82%o!@aD^6_8Pkk6sym}&9KE5P$3ii@ zKE+=PJ4uWbR=N7pOTSRUIr8-5R0NDKCJt)GQldl1makq)r@vHg4XY5eC4WCPveo~C zxopA;zJNoDAQiiA;3(CYF z6m3g*z~qn>IE1EbPN}Pqc5NT0XKDj~26yTvenT8VjfP?IPxlQkWuNhH8X8s^mgY!w zb)mN|aS$_9%N<1nca!Zjz40+$O+RhOH2?(TU%dfnCNTJ&T3e(~Juzl(Hq+|lHU@Xg z)bxI`5YTCVSGp2Dv0^q~kraJ7fCU;f1UIY#8mN87?3_t?!7lGVjACA&D?X*^BcuHE zmFW9-#)MCP_SWV&v44s$F{JqDTJgx9jM>1BUm$q4-Q!r{taZuAK3<^RJg!G2D=gMy z>y7-TeOp%PyZ8hls(wv=kIP^qpxHT7Z^zOZQoU{ z8EGwzgDhaA17e^2RqM#|wG`dtQzwleZQ{0BO+J3N_%V;MYX931Pd89xJlE9H&9Lz!Gp(D3@6xun zt1=D650^fCCZlPajZgAOEf2ebh;y-u{cI@Ua7ZxCo-Jasc;uuE)7NojFM>Wo{SMm$ ztX`p&Q^Be=2c{8wtTl~d(sjhM?cH+MXEIt^wOrKjpL;Ay0Fe!CrKN9Q(m*BBTv+a$ zkr_0U(8RiIAAKV(H}`_p*Nv}yfPG{)j9_)3{j(K0frnez@+R}(nc(&0m;hPWB`6Eg zTVFJ35o`5hFmEB&hKVD$G?iNA`mDEm>Abh4zR-tday4iR59d~xkMkb6m#HN!mPaX_ z?$C6Dd+^9Gr*gb%sIlWRCEphKRL?E!8Dj-WlMongpHttAG={mAw8d#a#IW?e*)1jz zd$V~hf!aY=85;XUEG&XVDICXS&!AKiD34E3;UhUDKxjg>rK1MA1~u%@mn!!H*) zvMx)o!-_UKUXsfu00jF9G*5{W2bEM@9 zAcY19XO*UQ`1QW z`}lJQhk)GxOYHQ+^1l=A-{@?0Tnkeb$OcL$4Bc+_&EC75{D(2q>OW*Gp6UwhQ1>qr zqq81lrv}r?BD1^;h8SOB#1SK?F|uF}=o+=l;Chd^;sY6pYbLX5^CTQ_dGMsC_Zxq? zv{{B<2sFc*)B`WpfQEbAhQk`vDDa`|Jg0pN`yABf~U`VN$oe91W-&?C$v{7Z?# zMt|ENl{vL?%fI^il&p7`@Y~o#uh-sWW#*I~$8T@Pqd4gtE*MW4H<)tLfdig>?r~vo})w z^`8zFapx;nfa!ZFyftb9j->@Y1i zp+;N?db91D_a1FoHn z$YbXI+a+DBgJ|~gP|vqT#=Ayw_)m*(%W1y5WtpF0G%ijVQ0a!vDlxj5=!kje6>Y7m zNDaptCPQuVT!p+XWF`(cM$Hvuh>Yk9H&sJ@u%Y-p>)Fzy^(odf=5rI)$Cd_jOna*j zlYXM38+*5QIl*K5`}wsRk4ipQkoK^rv(3z#W0sOz@((V{nxzeG7Q$_gKa9^T9DV2%>%dThZ?5!lZRPaF~3O=LyM##GqC4(nv zR#JF8BqEI-Z$=F$gZGo}Ulybxp&sIvFd4oi)#ZN=Wath`yXA@7ea_Gs)9Mlhe@!du zzlQZZ89igk4!6sDZ7khaW=Sc4DMB^yRtso9Vi*XYsQX@LtMo+aH+_})piUkoCxRC= zC}M6%SV|yNPO4Tf>+JUxtFj`z7hzVuDzXenIwe*giDHi}4Rk$t%9WCC(Q2yhr>g^y z?j^b8ylKx)s^nc8S+|T41=mE8mgbIDtn>=YYBG8AlWTl$7x&jTlL@#2*R@QLib1@t z!~R!>>095d%qzU3+$fGu60X+S^Q7|!iI*o#(gK|LHP%NP6+Ou4us@t?xMX<;`TO%D zU@L1(08BH#!ptLuQ;8AjS>onQ#MG)w+_sggox?PtYQHCb=6}e^Qfd9g zFycO2!o_PTwNF}c`gDkTK8|#S~hhf=|3V;RwW?gRQ#Hp&LCzvQWvjT`XYC+ViRexMVa@-D*0ulKT!hN z_|ZkJiRgQ_dNUL0*Ul_G>p0hh*`;d|ZGPEystsFoYMP&41J*%Uf9$t+^N=cr5gm6w zFoKXyTR8uBnX~6t?4M~C&ZFegY9Gp<#!O;he12sW0L+;dL>;UK&jO8OVQsJAu0P1E z{!*ChzDe)wX~v@>F?;)+KAVV;tlWCZs@)OZEI+OF7x(h(jVCrAa~6{M7f9IDHqR8= zMjE}okF6pMyFR#^FAQk^!2*fQ*$t@(Bjq))lb3N2cb|4*t+&vVO^r?()7{j}Z?lo$ z5pv?!(&G8=xMUxk^c`OBBm`21d@35FC-3UnqzF+xa~Q#O)!$eRBxDUkXZKODCaESr z86;IM3s0Vz26?xBF6L5ldlHu6n8;)PX_}D9tJM%(ZkoEiN$9>M6Bsc;jPslFQrjJL zl5skhONB2f{CqIFGMZ>#UzJ?O6@YaW75U{;;NCO&wCmM@{IQ-}jr*aw zAW@zez8CM4H?Y4Hjj9tR+xMflC7Qt6aOf$IkX$66H^P}9rY>A}1`8}iKhEgI7^Dv$U zA4jQr(CcmgwK~_=bHF3B?zrqV$+rLdihK@6hcqh$v-P*N>^?4*2 z=V{`0^*6Z@lRb-zy#tVUZ4zfUoq((7LBE*k2SHGj9sR5ab}UU5KV4;0MEYHu`DFs# zIJw~OcTPXZ4B^&ZF)JcxNpwMJHdGc#+5SW}Nmg-K^u<&RoPBjl^br3-&w0T!cXwic&ynzN_ z@cZjStk_t?v$Cw3zg>?~z9zv=-j4*!l}OzEfNJkVfh^bAxfdvdm{#rs+D5PjOui&)wl7WeTooLG0JH*3wLwc3xd2 zKfb*YkC<=9yH=2n?4EN4u@6p__ z_)XOIk&LS0*CBP?cIYK;m*e>3#2(YQ;K`hi9IY;APOta$5|B}C;BR?%ozKUR!tJ^# zGl!s?w}XI%ZA!%AGX{s~h01M@UVj;|Uum-XP0Q2G&ssW1mHFUPmf&eVk<-vfbH{%l z@3*hO>U?@mdWCrKhviSm>15BD$0P^fS=TY&g+$({o1}Yd>abNnI^^AWW{Eu@PJ>vje+u|^MA3=@!_W#XLajQ z*2=Emg*kfe(i(bX(6y~A+3h~Jno^_i&ag8GE3dpLpkk9wbawJ^>pmt2bZc?`p$ovo zh9`-RNw#Jls8y^n@F!l*t%jgk{VA_)fUga!f96}|jQ??T)^Sa}Zy*1CMKKs4pfJh_ zNJxy)H9$p5N<^e%G|~-HQlq;M|X{GM7ktLOazAHfamzU_+#fj+s zd|)Q5M|jS{Hf^jTC}c0-hsl6g6+5k^nu-IoQk!lOgMR+I0%-p`%6oDXc59*YbiFos zAxa8%LAN4-Gg7=p0kweU~-aPwm4vcqGOKdr(-@1&RS%a7Ct@lU!pi5>90;Ol}H{Mj%%V9i>hT4)pb~UVo|7pDR(@UFBghL zjTCBpKq0ONU9j&hiW3UrBj2&nj$iUrWT{y>ixw+aGYqHB)s5-cC-3tdEb!_q;iz}B zi_E}FI0m^)A6LmEt|V#Gia~V zwo*jTJcNITO}`TxJpz!FYn$?FkO)fv0ZG*&gEs_DOwx9MT_B ze15*AkU1umg`Ky-8$bw&?DfL$1d_qo?pK^u&(4!s=q@Mf&Fg9Vt?WHPyo%~*R}eBt zC((wh#rv+*5OD!$xNjt~<0s70m-c=dzb0BoR+jc&E)du_wULRhcI$aN5{|&sn zzDmE|xV{Rkzq$;(TE3FK-o3tPD>?Nod!HX-B^q?2(#Y>sO*Q}@{PJiyg-Hwl)@!BV zr`yGDETW*jbJ}@ac~h>pEv##Z=9?c3PLH#z{}xYN2Nc-QzwUnC=27MeGrs5Gwzlpf z&Vf$1Z#ea<@Hj$<8lfsOaH2o%x!IrXv4gX;{si2c(b(R25X$-q5^~{dK66@GVIlE1 zQ9W)Eri3qDtB+b_GzPBuBw1$J_3Sa`jiAJSE}TR2RxJo_)?#7u)K$1r65?k|#Qt3>6p$ zJp+c)cLBq4p|V+6Mo94xzZ4^IbsPC>j9f0&;fCZ<-f3U&DPr|K{YK93oEZLT>2kF| zhXQ)io)%{i*DXwCj0_7=RL37xUKFWDcU5J^xy2Df{m@Px*rE2my3>K~ zu)M}Dhnq#%4Kw09^&7nwHe{uDHtJgx7~J#)a>}(1rr~ zO}t=eD=oc_hve8aw=3Y00$bEs@$r;!YXA#0NHVLQuwB}kiQTO7hgh4U3?F9vZmO_X z43!@DJHFo6GUR=iX;`Hk9^K8F_P%Hp72Vw$QJcf8dJO%c4FB*u5)OV$4hs9>z`fU06zr%kd)H1R^%1~0uCfZeCwO>STf$bkgLvM}4l#JfFv<#nh zyu(EH;D@N$9nv4L&l_$F_NvFZJQPjt2W*IN!-sW;*$KoT&>PWtH zmYO9y-72DCu_pIb8wm?g1t3Uvyv=y;S9j=9kh%C%<7xRIhzi4brg{T&N~WeUalhSx z_|9GiIy3t8{5=$S3Gd?gHgGkQ8X>EcY9qm)_dk9+b(Fs>fCjVoOT{f7v)KE*IY8ZZ z)FweI+=DyYF+A|Xj=4VZR*ehV$YHQ~fNekV3lXV*n`7a=*{h-1fa3Dl>}9{f?^*l9 zXLU-r(;cLyI2{DQQ>3-MBxPWYk7C;|4S3!{;bK}opLeM^mzhbXwLBEJ2R`m5?tfJW zde$V>77T@RX+TPqwB71^l9lVeNMn@eku2-zDrP18|~cu{3GNK$2jz9R4r`ulrQtzoOtK z3k&W)amL^o^~s^QVXvHfdyV10MOo+Zk*IgL+qG=QghwJCmf6z7cC)G*4WFJocqKCE zE$XWiT9CE^{_t3@EnDSIE!!FH-@1Y_G7EDQO27pN+P4f(yH$y;Qw9Ql5w${3Y6HL! zI^t-VxtPPg;p?eRCN%<_4&GfgSE?XdIWT%=7tmkCiG|yS6BoAp5c|SMvC5ySV!%>% zQW@rcJ55W=_c~x2Ke%OU-Z)8mwqh0DN!*e3ds$kMs2#BLzoq5(GG!D)yg(NuS*yqo z+m5!H8$v&9s|KyHbxD4M8`#g2;>YLbQ$bFaK+XKI-QSX%PLlmcac&CsyvyL+r|S_< z%qiGLW3B&_VC~O94~lg)yEaIyDsgLcsyir(JGUcU=OyS zAJw+7IeeZb5Kc9bAB)oK(emDm{zXSRaoO+h-(zXsoA|(W5JE30+oy>Z;24T;>{0q)~=_IE24xfvcvm`C|#iUxDbzWN1?LtSGL2mIRmJ5xwn z$M8ny<6%_;!~^JZAOL4(us>43u95g zUsIZK`gwnoyrinp7#aOfvavCN!uY#7b_7=%!;G4VdlFoW?fQ4Xs$LIJ$Hv~J4(PDc zK)#RIR@aW0x58P(0=9ztrndz7FCQ_?aP~eHE9-csjtpYiF%|`k%vj#t6;}~ay(PP9 zxoV%mS?p61SiFiH%iGQ!4X-iXi4V z+@F-8LCGAZKYg+?5+BH3MM$a2C`CaScsv;Cl2#Ry{Dmk#5<<<}3;I+89{D#4z|dT4 z+%iyJi>!O!;)2fJMyh?!WJy{L?|I&F6!-a*%F?jAm*OJPUt#S_-H=LKIJEU&tfSY{ z{pI54^H)UP5IQoOVy$bw{hfYjZ6bu<)BF=z>Pl5$qrjN_`HzOxPXLvS+iobASB&eN<5jH-r6u8?gou6_C015 zBXyJD>mYCOXV|8UH10R}B?d%=F z{YjG*xs^R0E9dFBeJx_-C>rD0rKo>>eovAdVoOt8b@1*(z~aiR_xP*RQ?>&8+|Po} z_odJ6&2AcW9cK+cP^bvB_^w)O!|q2+B=_iVw?f);vCG+w`&DUuta)%(!?*xh!%Lkd zl06+`$e!dl3y2PERDq^3`@*fPKE1KAm#1UI=UE`RSi2<*7-@G2O#@u|Vl}9J*X_YJ ze)QIc<>JPTg`nf3cqd+dQ2eL&&*IC8)hvGIuY^FNYoq$dJvVzFPivE^W)uQ!?vzw0 zpv^$8yAY=U9Fw6sb?z+h-_FO=R}XAk+C(nuDrk73_kk>n;l;$^{w1GO`1a6>^re)n zAPBiqU)kp@3hMd$lNfMni|nZXA@c)Ml^9oSDG?2-n&_y{<@?Dv;b%C5uo`bd#kw2v z4caomN`bpZ!7EnuFZYCk51YRjCz$1YANe@8Fp^roj(0kX8HCyRL@>;Y^|;oxxEe?J zd6#Zy}orx%|d!Re81diHE|*vE1L$}f|cLK>K~kxV)kxgt?Z zoV~CAR6eL6TM5fsk}v89_AUA4crX*@rI8Czc$d}l*nlEeerNckj7C$?WH%N9*wYm4 zg4ll8%$I7-Ke1keP>|H6`uhtR{!Q)UV?5m4dcGT?a6uc@ z6AyLG9TxRgIbsZJJ3OMhnT=9Y6>(<^v4jndRaIfL4qWuBN1kx|67jgL{3v$K*)?2- zypbRG@CPDObOxzYpKd(b9K;UwIIA;dxS%6Y283z4FGAT1K9=r&7kDQMipd|m85<|@ z3)UrYE&6v7UOH!v-O4>%pE$>!aw6W{ak)s^&VaIHFNR*1+cMqzQ zlpOWY983BLD_PYVCwau!pFh$BzF?*tEp=cqE#TNowJVcV_2-rJ6Bbj&s! zsmPPZvo#na*<@?AOi}_AKb=S!o&;LAC))Z!Q(Avbu)CWj*!qpkEoXGP zg~ikf99CgJ1g1^Dd*3q;KI?C6769yXEauPqM&XKP`=SZ~BkfBWGK{43gPbL&`)lqA z4!)l0e_Z~Wg6$`BVf$?Aj8b!L8=_HuJEES(H9nPZAd*xfE1s4(AL~`M-o0_Al8%6# zAQ>P6XG-t0<_2!ZJ($sc0q}IyOMmx75Y{D@IOIw9>(`kYqlbW==*6$IVZk_mE2&1m zePZD~)GFA5iVlNbKkRt0EhryMi18U$%tnV0hJ09#lZ|9D=sa@hv<{pQ#&G)7cpwM2 z+0E+KyI0BtZ~JBzKI^@CrpEl+$85KW46AwtE3*SU9lQf3Udkj-hHOU*Zq>l36I7&$+O(BUF@+e!1t-5DhBOq60qPulO2g9s}R&M0s4sw||*^HTRA* zkFyGz92W}p;qCT-?=zHW>>#Ix^Y^|?hvUP3njB~=6u|T>H4S-5MN4O%;a3A$HMpWI zdFAPzG9u5ZB>>{w`Od1?rYYFsd-DDS6N&#MmC)>6`4!3fzN|L|hS(i1){BlEaZY&+0V#D zawd4U5gU9;7P2q)H9m_xL@VU;ZrH^0WARAoDic6ibk~#`q8*J8_fn9`c_lb>H#ZET zGF|)9s82tWDTL2EtsxoMBpS2i)v*lsA_FTB%@T(QCx1*>K$o1{EPQm<_1R2*H#a#Io zT_F&koDM%OG>s(}3Y1IeS39Z(Nz+);ByV5Sj<6+v;OaH?t)}2PsquFQUfJV#_c!yT zTakC8M7^J>v?kkMGw@toS;{)@+1~|vcFAhFT#`vQ>mLuHjHDl?A41RSKArHoj;P=M zph0b^Z$^Cf=EP7Dg`Cy*-XO7EbYoP6@ETQqI{Z77A1la6I@c$duIJ-}_!P@RaqV#0 z1ROk0xb~ohJK}t` zE3WaDS1#g}X4?54u|1`dm#q72r7O)L){;X<9nb1&wQ>S1hn6pBj|{W z=vhh5jGp(%h|p1h-|u}0@m?$?V=tOEhsMTlCW6ReCIS+H=2YB2?|imKT|FXtG4(7~ z~UI zh?BdCs?&+01=|qdH1h3$hSo5wntnFFrS(>JqWfY>4uyZ%`{XZ!skUuJgFe1|bYbkh zleJR*?L)EKLj%>zZa)qRle5P=L{GMBug~6zfNC4&PfOd=;qNWyoS3(V76p`?;6+|e zl0b>%sE2!bbz+DeCV%u`)2~$wD))we&rGyX0v1$)4^Sgle0}>qw!eftdmqbJ#|nbRd*f2D+@5_?{Qs_< z3r7O2aao)=;2o=u%O9wMBAcpEEH zusxmqyabd6w{_E}+%W4UnbGFFfSm>9aTr(5(CRLLAe^g?SSs~)wuZBbLQaJVfWhNu zNxqTM7STytYIFiK3A!SZQUi*<8q1WY8}?CnTVSW<0(xVjcY1e(^7rc=ktPt;Jd=s+ z^*ot4bC>8&Z`9y@%rKOwd(XkzzQB&1=gTXLA>J#_3WI0LF`1K26*}fLd9!Fd+3?8krp9L<11diE>b(7JOZ0a}iQ90+?SRRTLGDATns;pr!#-0*Y7~aPpVftKB zE7~RYypRyDG{GA|Rjt6(zdaW09wrtYz`CWvDCj%W{;Ly)VudS0q!J!6knFCM&oPCc|>B%`Z+ z6*1>$m~nup#x+Qcp2Wyr9HQv1;Sbpa#07Zy7!+`(VAT(cX4*Oo9G8jmGYXt)&ZuBS zA`Rrc6_!tQTz(~-Uruv=yUn#D!FI(=T^N1Nc?&#JrV^+1X(a;dET^8cB}kk0-z>>; zk^L>KJrbLoVw6sEO$)-=uo?*6%l*u|dWW+J`{f1G&N_U;N*Lq;vftcdlbvmo&(`a* z@^)*&G_K`MTp9>G#6DgKj5=S=5T_?aOc6>cQC494mfWfNO9zR#=k?d(sg%suw4Imc zpJ`}#vKZ?2G;lw}kYZLUi15)Ox9xCsF;MNE2G712Qd{^-1s2D0h?pLJiu!NKX6t&AqD>`lff6nl@uiZ=as0rw5Yhv}WGl|`9bif}-6 zj_yqj_-Scw?J~=<22`DC)1|#sWYz@FD(dlff>$WK5Xa_p$&`S4Y6S|{SWqipSfRZH z?lrwojXwmA$Ydv@2{jNHbNC*wds(r!bT- z9d>VNxDh7ECn;ywoa=!IwKn$WLFM6DGd45+=O5Wy68D^!+GFw?Quz~GS(ty{E8G-Y z#O*r3G=8)ZR=Kku+UV{m9lQ^3@T>5N74!%WBs-?*UJu!3H6t+G#1=$&Obm-cY$kM5b+af*F#)GYl%PKg> zMq(p*L zKbB$otnRCJ=0ORUQsE@m5_?ll-sESps_~VjC;cGvIu4o0cST%6yfbywEy3Pu)3?01 zG^MNi!=+MW%`}rW@^$VPqx}sl&|JAgqI;-|l+OYd!XP{+9Y!vjKJu8YYF4z|`+ljq zGTh$_}~xB!Eh2)cYbZYz>2gy+=Bq$@m8z0lNfk{qr; z1D0E{C~3KTeUk=wRXhnKkg+1#G?T zef+H14vhMh){@}Gq0F^i{@GyhhJqJxX)TdEtiefGw@E<>mwnZXL zy`n(T|M;fX|NN)60=}(8_apxst%_-pC|om09&^cU;AGffGI4)5rp$(#-L`L!sZHeF zvhFQ*#rd^1-a$%yoDGc|yq%qYp&jw3-rLZcuZr+BT71Q)lCj&_NZ2VnMxz{0rX_Fg z2YKuS|11+`H;??JbNoeMT*0HvHqy+}^J6{6tg^4pswgC6oHY%MvhLdLwXwuVjQ)I| z;v~V$M7t1XygZACYZd2XhOk;pFO3h+{B|eVAh-ls!L=f4wA(L<^{~XeDttC4oz81k zR*NG0977`V3r&bYY8MVy{8dY|GCwX59nagP*I4Q2}n3w{DYMF0`M-EFdMleiXNDkpw&1@mN{CdDe~1xTZ?Bh95O~#eQ9OW zasc{*+32uE24YnE6!VNYRDt`;gGI{<(_77qatE}Y&LCtRj%5GsK4p#4Usa)11HZCF z21XyViKh7h{}3Vr^*NBjwU@|bg4_k*3cMS9_4);$XO)t5(51bZ`6RHlJn&d_*Ef|l z+WcjI_!M|YEIfVojhJ=Ntx`P&t2Es$DocyBGzl`^uY*yEC_CNP>868mQSZo-_7aDk z?s{M=lAItgpbfvyc2Friej;_ab@HYVz=~qnwvaLPLhP4H1O2ewY4 zAoh3vSo}^0R9E)pduh8Sxy1-@gcl&de|(>^Ag9Vw$7tX* z(C&_wv(Kbj4-4`ek>5-UBs-L_cqCNghj?^0lzg}b9%0m5{vZb0C}`~!hzN)qFWNNu zzOA>&|G;WQpo}*2Boqp=8fh5VGK#uw^(}ypf%IS$nj5w_;%Y{8>w86SZxItX;;`OZ zGjNJaNEMu^2VdJ)u2v>&bvh#>+0_dL6l9zFoNF;c=d*1>pocc!E^Z?fqBE!lN%=v^ z_X_CQ4eogv$~-;ET<3Qck$ksTv3983pyAvKs7-mpP9pp1fVrWvB5GEmZ)I)#M@I1y zNPL7iueRDBU(%*GaDuP-qybEX4_0XX>@MdL_}Fb;Dw~0-3O*=Sey)u03wW_SS{DpV24!#cxPE{!Xp0O2 zp?NQH2IH`YU?3`9FXm-MqqR~;fr7+q&~Yo{UE(}&a) zX8p~_F}uPm#`qpbdDphHTB9QFf zGm}VV9OWA~SUQh#0^l(%8xm&rB(5_2f+iW3T{DG;(>g0XpOv?UkR6*xW%Q?qTA+~O zZGTVVB_RD4Ejl^7NRKnG&nkJ*dzR-%(edlaH&s9R#(T`Ii?2C6Bfkv*?O8rcx8z2f z$2PCWN~RAs1k=+kTXK;(7@uvAP}*Nnw$QacFrd}HguGKQ(M`}rUymUX z)QbF5xlclk2-~T^VqsdWh(D*tfVTinthabd#R1=Tp-$kxO@vyCtnbIMt865hI zMVet1aZMv@gEbQ!QP~RF&}0G$`t-bX!WD@o*zu9Cp8n(X-;tZXB<)TDE>4LThsfUGI#AGCDOC+ zL+e?YCDBxO!$5CTOy>&#y101SDa2#MvwOCQ>${M<-N+>rmxnvwz!jBSfJ;aQ-^H?5Vc572e>+bV^b6FYGAbKc+=br}d28SMVZJoO6CCx+JU0GNEz<^gf+colat{nOB#x~8Lj+%;DbJo z9MmEu0Ov-C!U)(R*WdQHKgci)BGsWhsfB;cioETD|UBSd_ zI-=LBq=|jOy;j$=)%LqNL?xH>$LWC-GPb@(X?V( zUay;yK)9>rYhIB~MrMFqI3{-gYBh_ydt1i~H}XUl3zWy|0JA38~K(~;Qlno;S{?O~x~T;iV_X+_fgw}G-$ z{fR9Jp~F;`$$Z6d32;2dHZ<0r(ztthn$s)fHR2sYn`5) zRveS)O#(!695yomkDZVON^OTsw@BudBDKzJ6)ykTns=saj(qXLKK^X<7C8>nO{1$J zuWuC8*}2^0Y!>+180-D(@ydS@V#wjfHAF3jjC4@PaQ19#`_9?F`C6arsD{WXoUWiy zm?^Hr=0OZSa;Kgk&q|%^SBze*|7_4^Fmb=JG{zN1KU@^Q&4{hze}zyWY!?voLXz%% z-4#1}3_wy~9=TqOGVZ~M*IdM-&1+K_-;b2Bn}4^3_d8VETs8t#f@aZ0U;1v7Xn$_U zk8+z^hc8={&mFh5%7gBuqmBQdF~H~l?mGwc1^yo2erRuMsjoe<2#ffjGx=@exx%I` z4FSMO@c-tO@Y$Oxq~qwU`P@kpQzY<{5xe?_EM)u2eerZG=%Qoz^Ku;r@N2O!Z-l#U z4u3wg-LlB=ol2qa?IBDYZppF0lNw;U^|_=15WuQDXJdk9HDntZB#IVQg8)oA-~@Op zBoY}E5}0-0ALhsMpIso&=&gO?)Qw}6ZQG~ERqfnhnNu-=i*w;XAM<)ND3&uo!=RKB zNI-Z8K=D8v1`3hiZXlchU$E}QMD#|;!AT2Mc#DboZ4P?UhK!T>#a|8dNI_MA&a0L; zae{TGMEZUwlal~oOiq)l6uZQLg?sLJBg0&7NT(a-Hm@z?pWd~P2fY+eadM{^Md-Hn zQv8h@=JBt76gNYZZuLNHLUnv(#qY%sVp4Zce{{$d!$tgMr^Beu*4~{Cu$Ua+sD;{C z-yz6NbHu1&!tKJ9zS$jlL&CHrF6AB8geUPm$Z%fY7Z!C@b`%pPQFmu5!x9_}PN z;NjgIsm%NYTdjhYaj_nV^2bjjK3y|S-n-^e(`H#=Bfu0LqrbU^66(MFontcJy@LX~ zWZTGSbm&^kE^+L<;#@gMV5XbKxj_WrHat&R`DS!Fbj2iOw#Ml?yqzi)kpRv1S2!3v z4;bs&`FC~i!b9U~%*@7Ixksns?mSniFP9J4_AZaVfod(|AW8mRpEQ|(cprQ?*iN6p z4Q_fHbJINI$SxqV?gl_^Jt_T)nKnY+p152Zz9HFU+Dv`v5`~}$#x#*QN3Hmu(Spk- zadi|OFocNg!?Ni*IQDY z0b8xKXC3>i&rCHc-cWRy>fg+@M(VYNi3|SnkFjI?0vBSTp*h_9n;Py5!}EC}K9ybI zSEF43`*K$B=3}p1|3!WiKUjxA!is;~QAfoW5AU+xOW1tG%C0X0H|rYv;jJKgZW zrQ~or5OMc;wYr73i!;Zy+(mBsRU#$;PcR-d5KOub{sS?pPBgu~z9kpAsp(t@9vJKB7?>^3l#c;kTe5xDuUYb8aa3T9FgrdBBM8 zX!ba<`v#VuwNMmRcqyJZ7YW(Epuc*sSa4xH+DlA!Z2XZk!RVBKW_bd zWk9kEd#~wco5sy{pd**eoi5rwE^pH6EDdGmEN^&o0tM0kZR1ed2(qnV#qANt-pk9B zZ~z|EXejXkAOk$Nku7b6{wp_S{Zk-9kFnfCHk^(cb0=~|)L3Enbb15g&D)2z!3f4S zGLkd6lWxH2Q)HfBm*|{5xUVR(H3=>GTqb%3;g$Ook~zpuPkLzEDRg1orF6#2D(85= zvtRMy&w!c7th!^lFOeejr1LU=0h5QrPSXt~Abku;9S`X00fPKgw#d@MjV5sx1KJ;7 z%SQsdT+H0F*9}_eNzF%Jgim*`c9E+*vYeR}<5yp(c==OOxjC`$g@T;y_PH zPS{$Vwjv4Ag1`#mH0xrWb!gVE;+PG=i~~Hcq;o? z;t#j0AO)=NMtQDnU?hzy-Khmw9hOJH zZ#jZucx|^_ktoX4EU~JS^d6WGMRY(#cArx(89yqc$(mK`l z;P}rY!%NPWrq}ei1?Rc>U0%XUV!6^mSS*=PY{oin!+Fk*UZ7)iaV4ep$#NEmq^QLz zZ;jY)>vUM!dEc#fP{-0hQB@>&JgXEQp6LYoLlDAwNnC3I+`KzcwNRq-_@Cy{wtLKE z?UHrc#aqGQ0OYG<(kIaGw{;TNdw z)mnjk$O^Y0XhaC_92IpJ+xMp$i~DsX*Sjt!Wk@+LRl9)^5I5-#2%gURv}8sl1+?{E@*eVuszk?%NJr1; zx(B>wsE)|d3xLq5KN1cyhT&!}&v@NhZps1~A{&z-T-g9~H&GF^1j{N1&5x^a%jRme# z-rbRf?iSU}a7I*Y(j92xJv|Wjb!jo$X>lgtk~8^Db=QE3O)(Umad@am+t*kL=B<`K zKOFlE8A*%SxDEkhKI~*x48M-#Wha;4l&@^$D(s0Gdm5qjy87^9YI^g!qr4)Ddtu7{ zf$2ke-b`f-S%^|aMEc+)3^<+j-B?84=~Hp7j?Fmt%j|AI;_)`|QS{R!_U-RON9$ny zun(YOZu6wFffC!eJZ-(nedP#M`O}vS1XJoSN3bpw+6b^`fm}$8wa#f`Ji@;a*vFKnT6lVrL zq*0JmUFc0F!sYKff%wYO&2zU28KyljB zyRW%oaye>6rv?kyikO!bI1JG;^Qne0cM4JJ?+0AO#|@Rk7?A%MjdoFpM?*9uI|NYy^}?Wm9DIG_K3oy|Sbx`yv3v(nG6(?32lQP8xZTIQ@!)g0 z70&be3MjuBp?~AwJ54sUIOs@s4{gF-DkB`tQ(7Z(0H@EtSKY)A6Wjh(KHU2U_akG| z{9KaANn-g|Gx=ugF$=DG3cITwx%Ic+8@6`mPuB|^%y-jNmas6#cr@+PR3h&0LSJy| zb%>iULaAO*B75rD-A6 z1kmTQ3cpDM3Yj@Hv^4bm`(HP^$31|I%bekY*CM#^wLhTO5gxiXBsh>j$@!V#v@{Wy ziSha#wEXH2SbO*9i~1TQtw>O6t&`*-;>S!rx$i|lYr6DO%TaBx2-;8%6?tIlnYcR92%O*aztyIhx}vC$)MVCFNTjQ9UlhRogfG zH+P>LB8Fm!?SBjkS_|jMObpqFVCL%Dc9}c*?u9@A&G3v7D|kIB6MK3B0fXnCf0OgP7yT%$dh&zu7yU2VY&^+ z<4!|BQ8?9(#;C&FHfz7#0;PC1)Gx5`@AiSbmwYxdSY_LJ>o?dk;7iy0WiolnCrk$i zjbtGY?X}7ifF8xWg;JzEGlh@lpe`8tU);vrK($lmLi{{az{t!uq$2v=>?1Zz%k%ph zqJ%x;e`op!uq4M_$D}Lwd7^<5vNOb*IK(Ws${t=337yG!dXOYHV`;fb0~326j*7MG zVM0-V;Q~LBpYM*XC>D)E+;_tZqUA(D=KkY;%E;%{jkbo=kt?=%j)1%w?fL-;{x?Uv zt_wVSm5**-)8d--i~EaQN224cj{Fe!OCM1$@28w~w(G|ON%lMQ+wJUQ6@&kC|G+L;p$cDp|V@(eV7duOOL;VRnVk zaR5wwtDd?a5twFfU^wc~)nx(hx_3t4GuX5`_P_A|K2X${7z8jAyL7)+SVu|3fypF1 z)i)l4-xaVQVQfYEDrT(Net)$p*(i=Gl3`gIO}P3e>^hbuqOW_eHvthBarZ2{^S%SM z5Ula5W69`l(H|!rM(ezpTi5}>f)*35*8`BkT+#A{Y3B=M=`-W&R)uE#pcnbV1HwZi zLNBTxZyNdIBO-qExn-z{eO)ScVe+lGAE@}(SWSMbx{2e2IchQRV~afap-|Ppuglo@{9LEJY*k7dsx7;@yFV{OC<^j1a(OE7HXDXXXrFJT$on{|(MIt=x^d z(y>&NeCTs1uKd6Dw2g198jq~WMVnJ^Y~Sgb7yVUen-V6_45RWL)jVMV7CEHVq`#ml zschx1D&~eoq1faZ`eHqNu5FIR)f0%+@!+ZfcHJE;rScftV?swt`(*dIcTI`zb45Qh zcS%MVE860>fHO+^)w2g2=_~)m^c6{LcGW$Z=`Yk;u#R6X3a(M#_U>hQ#R~}r+O?GS zyQM8N^-`Ooa{@VUX^^{T>ZLbFPM+AOd?Gj6{%-y$R!@hk_ZcI#S-3dRqLXl6G}HoY zBbWbe|Gmf!2Mcl@9)X#=ihA2Gs+|y=OxBoltL5)Mkt1(`zG;GvOdF~wFuF?5GiE`v z;QK~+V(ORkI#{-KB$w`W?DsSir!*=W!uphE=Cyv9-30eZXQeXP5)+aqxT~*&vG%Qg zf{l6YCQMu`w($fn^FcqM2k2zb9jg$#j*TX8I!hbG6&=(lgq1CXHqEzxiiOZiB~xTh z_rIr-lm?R$Q#4J2m`?@ElP4wPcn*UOhITFfX2^n{Fz>0K%l%*>e9$ZHG&vG@%rQ{l zc%yhus62g=*PKgKeNP!(tO>aUIyzekHp?ttz~dnAVHOD6{DXB_Fw<2dD=bcgFKQuK z=3y&Z!qgR)d-P5Ha;9t|&p)2n)!(b`n{?L06GKOOoDz!06WeohzyGEjRS!RwK4kh1 zl-0P|P~!gz)`BBn#DOMRS?wN2IOosRNkQOKHXn69`=htXH>%?Hg3p)_h+Nvb4MY3F z)q?+xOAAUBHd$To9oenbnYn}hLXU?Ql+^3>-b4>MY$9A&XFcfsO)Svy?)y3KwG2?? z*p{|Ar1X0AbygCfmAcxDph0N*jHOQlJ zABB{p?wx4!eTGY@=5yiPGlt7Do&YhB)%#R>lNf8m!%n?|!woaj3lZV!W<2hKuOv6<@=Pecv!IdNu}SdX<9AvR35#t; zkAv%`ruR=v5xPgutR5kIIj~hDE}mdx#Yu(MxkOIKJ;1kgwxLIO;!{O7S3|?J(?Nu& z#=^qxDs>J-T}V%Nw*Se$VM<&Xxw??R?61QP;faspXEOrBKUb>yjyj#CzCHhbFf@EA znuWhyAP_v&ZQKQSj#%~Q!mQL4(p+RT9xw8g$GnTane?OZ1Vf0gh`7v%! zhur<~Q+{gO^pVJTj@N$IB<57{mbEcId(k8uq!CSOJYUcen|Myc*B784u+ z39ZR#xicv0u3+m=d|TNv4^ZrTF9UR;@H_GS%4T+x3d-F(VEa%JdOtXDzI<2Q zm+++?2+2p?_7XPH29{*i&0mZvIwYaGSG z@sg!K1pyVqWKTBNRDSt+~;Wg)iE0ze9M7h*V$=+PHc^PDXtuzU$g>jmrm_l zrVb8YEQHzZC67()D=Ib{9XdTHWbb1m7^KPhhgb>%MJ&QMb&Rx86vF&=3OUSj!-L$A z(jw{jLdt`COVPQC6WK#=_niL!&Af@_?+bwILNXD4;dIjEf$s`C035A%oRNE?gW=Kt zadg&kO}%Xx*B>QrfP^qwK|sk7(xD3Su64_^btUdkbD07KSe@DF3_YZ z$oTrCH=|jjSpMmvt$cgF4ILgvCA=@zor3Ri&NClASe1B)b^XPkz6o2mGI7|Hmge7Y zGp<)U{Qe2}^}+%(XOc{A`~HBEGG3E(9Cr1tB4!9-U+}VR$yWh$xlaEEOyG@o@9tjn z$4zbiFl#MshmEb2olB1c6P6i>jUiWFK5dTa$E!c`igU$zDrG7szij>}hgBhpLqFgm zPd?7Wp11h0gNV{^JKBda2I=(QaM9s<^&HeSzIVzP1pjSWn`5AXq`{DFlu(h7-2BF2 zQTO{j2!)ksE;R1hs@`Uc+?)_QH`w5Yfot1Q7H6z9rB;19{bq%9a;4k4AQF_kCbk@( zZnGx>-UiPUb}-j2PVj=GEK9c`^+q8@H901Ab_cTCq@uV=|CP3en5FOY|3 zkVyczf;;Muy!{frb%~f zcT4#GIz3dpn-(o|HYfYHX%6+kmQ#R(+QW_Mud)JnH{QyH@bik+BG(7l6@_$4v?i}n z-jlUpjP(guwRpvM%jCfiPBI}+VCMCju^@C_)5P~xJd`6sN@`-aFqVU}-sPk=y1{I=%hloNAJAa zLY0B^(RQip@X*i2$d3*wE#FOo00m6>6VM3A|gHW@E#F4{M0NDs@c-~c*`q%F%?e`tE?zgK zwFHD;CrCS|wGtk0xV)&F-u17$eI0unigw|5@P^vrR-WPIh_YMpxKT;Er0xeqrt18F z`CK_}W2uC8l_h3QG+dYFgo|G-*}nw5H95ja(7OF#F=H1dY2Q;fW5MSW-^Ta3<2ur0 z`>rf+F*n8vulj`Frww6pw0HUNo+2Z`YKa-N5kLf-35beR-~UN9eDRNmp3McUzYAFbZ|X@V9cF%hQ{_ol=zDUQ4&ChY$NoJ2B)lKT z4cKPC=g!1dRk|u|rJ;M)c9xy zXmB|Gp#y_TqsDQpLXyrF@RXfUCQ6@T|5&daRb>7&Prywmw`O|_&#%PAM4;7|{iRad zvc1O}Kym&r$JPbaZ zC-7piDvF7W`Xf%1x|&Kj;)n;qyXwNmPv(Y zy_?7U>VJpnyFZsaiS@v956IH?POZ6Z$)F2HGid59#1(Z`lf=8xy4i;RSYKZH&l1hM z(ZQ?DHbMEiTAU&`IkB;1r-Eu$f}0xupLJatx!uQGLr2-V_M}go)U`>5cBW~W+yzad zsFmX-XI})g&>9v01Qu2rWBV_IROjYf;TmM=J#Qlo87OOq zhA+J(<>GZ7n?tS0N>aiR&uZOP!zX(DMrW0c`!BeNt zpG{7UhHypRT+_$YaexYwTU;@>5PZ6)-{U3AiEKqX(_yg zsh4n&?S^*C*dA_!PJ)3SuTFsE5BRp)0b?Hx!P}or@H}%!rb`l3n^93a<5!U9zkHv2 zLhY3~$P5BWs-x=AY3lM2-xrV2Ycn_@Le}9d{rQF@mn7~PrgZPWtl6gBPiy`iwz%O5AfYb z-y^1vICewuC*vAy6&ah_<|N=dlicpDZ5IOb?*Q*)jB+=SRQ1-5N*BBx=%AbAJ1PB7 zapx21+ZS#{YN<&o(3iYISa?cqPa0WoxqeR{oxPx39Wl`g6D#*HzG%Q=!KHpXJlFPU zHzfN?E57v2K{FzI!v4Me3Oi&(R8b2frwwV$GXN}9J9yoX%g zXYU0af>M6!aE^1;Fcf_dH^BJDQJh1BdnM4Ad%2Q%9UHVz=id`3IRw9uv(@8b1M~^H zEStj73|JHCE^K+3_W{Ho#bL7~X0gau0ZF%miQ8_3;iNy&Ioki)q}pFn;G~WiovQyu z&`Tl7xJOu`W#^ov9(D*I$CaVDZ{28mJ1o0%ak^)?i<6L*d@HJ^jHPGh9`+hE;WjcB4Xo z>^(KnT+)yNJ~NNOfM@$+!_4Ub@gn(QPI9+f?vnVw*~B-U=(kO)qjT9F^JVT|pRo`S zWAd%W$z4BayEHSjj%0>)7hCKXdXxi}7GRx^h^jg*ZmsgI^iOX>jUzq2;l{bt*`xOd z1Q$X@hzc(g$F;GhlDjg|AUZ<57=}l#0As67Z6r*4A>M;f49&jzIZnwQT{RBRFQm zb@&tMy&+>GG*jk5miB1<9Gu;&3<*p}h;nVohyL*4SOtJ`=yEHs6ba-2DT@C|cr)H{ zQmD+E;YfIwX$X%)wga8NBq;CJZZ9M`W-MRdMM`HsjggtNkP??|uHN{}qs;_lK+9{q z6?3pd#UW>HEM7TEYJbsFYBfwni&JU+;tQ4xKk5&hDEvOL4!CmI zm(5+Vm(3vs6IQXi++Yc`I$umYvJFOZ9GZpj=2KW*n@f&j1=3j?Rt1xnnBcqKx>Dj5 zYhMN2E&0@qZx6ngFBVR6fsLBJcgNZ0vp#;iD7x$1!_fAr;`Y|Jt7GX~!YL9CQqU8k z)s3Ac1rDr8Vjmy`n%>wnBuQ{D&~$7DnA{FHx`7S)+acwX)B-Y8)O@^7*qEWr_;SR> zgLKYbWM=irI&P9==_`_kv4W4L4%2R#e>;u>t6_HP{{Hg!Xb?db7R~eOkho2^)?DdN zwmKqzB2*Lpz0x2PJ*TaO18U{ifQAFlb6{o&h+~S|bM_yQjs_*Ne^zQ=kRIl9QhVe_ zN|EZU^f^yG*p~*L$qlY%ZmlP7RRT|Jk5$p$ClHo)`Kb8h=;w|*5jyIGPm@%MPU0rvB6K;`#igm3O=Z*W?FmX3?S=Q?VIBYy(@a^mKC znZ&=qDqO9}Fc7?E4b-M=Jfu-we}DC4&I)kFxr-DY;UD1bP#Fz(Tl zQ$9S~03AhYV=4)xEy97oQ)7wEkPdTmv$&nxk2vb*=B1{{y3Prdxbo|7_x~y0igi}P z=5F7!diTBEC-;j4ceKd7o6L+@eZ#+S8n$MJg=wbP+nqjy%B{+;;7mlp{kfXcQROSI z&nI>7=y~>GwEv1~c@TC?Dp-#Q%RY-G#MuLq3C+_ZbHL6NR)!rh)9`-j*uUneD2d zFG^%aYtTkp4yxQ6=yHO0lY7kM_`~XSx3wD^l()(BPC^hyol?_9-*5twnGAh8TG{UWwpexPeg4A8$p+ga4-ErE?-`6FndCLmF;Wi2Y($WAlK$FGfs zfU0=Uj+|bSuu=T>v-!fDcvsk*4$Z+w1JoP88Ig3J7)D;Gaq%O4-PoD3vy-&(ul#!-)wmaT||5W&zT+w#%9z*%ea9n7p-{C_(MW z>!i7t>yh|d+ZCu}bx|2g^t@0PQQhtp<ArjuN;QP-x>bs7`lo5x;`m;RGRY3KRLUBuuDrl|I_ZPA0VG)S6H3|yH zHI6^|3wNHsZgTL2c^3Dr_1NEw~~Ma~+^kXiTM5g>4q>;z_@2)i1$^k>@MtcWYCja5MobjrN~n zIS&dO9&SohsLH*nkueN{w0xewERZR3N;r${)r=Pv@wozAd>X{uNs29!i_58rkQZ4c zKDT=?wAQZYGq;Oxo+oZFt!CQ@^)?;SUL(1=2JdjmN|tb`!7~~|c_(TS%4{Lb6?>f) z=N1%bR|8F;3#Zz=-y3tp5GfkB+65-774P0!!_V4@j!srXaF?o;fq@WPBTvOF`d_eK z)yBI9n5Sb`zj6LlE)yb0<9_?l)KQWIR-e=Vp|X{81FTRfwsJlrTGplH`axsZVd)crj zF0ddH=6^Au*(-YA()$!q8Wib0DEVr2)GOqn2xobU-c~S!Qe5lf()N|JH5wF-z4H>; z!~ZYlKDc!PUfvCW$4)Uloa5>!@m;%(Q!;(f?YJUqJNjLC=Pk?R&|%-sD70Z!G&o4d z++y-%&)_hifRj2`t-OyGi(l=%;(7AJ<}hbv_uk8ax#NVOTAarb1;Lm0Y~50;dxK8B z^XPXNCH#z)Z>cT@wgLJ=S99w#Vdt@~;TBY51F0+IA_VNP_W-4th0;57I|%T`ACfO+ z8Cn-@rj#Q-}>hN;jMEjR0Yagumg^YN#k2*E` z)6v$x-&0&9{B~e^)%?7>U*+<7VzaoYgr4NgiFK#xU9S)Y+NA5Sa7VhwYa0y^xOXF^ zbJ=bK17#!|Q&Cgh#njh3D1}|J;sZ*oKrUyAXhTdo4>V@7_+3!a>Q!|#d^8N3wu2b0 z=XUQ7ydjg`%a=(wxp=+UrljvVvE_lICeFzj5V+=4IwPA6uGiZ)X-^Hv4KCkvoTnBk z{XTBkvfb(%4lE*#z~U`d82kn5=3-eu!_r%Ic;(*cTGE#K7Y2tH(BPJ`3wi9=xGG4V z>DLPdi-ETe!NYRyVijG|Tl=h_ALXjfH-NSUFBav;rY+aKkd(>N%VsE61p(7U43h7V zz47MGqX7d%ujbzZ2*WkWVn5by;1ft{cg#?E_pwd>&59E&`r+P9CF+F~48rYJ5@!nM z_dgHfRFWRiQA~XHYH87hLMk!~4qde?TycnFXUs1C8sUnD=>cOLNPv8;M->1a_F2Vn+h?dz{Xy-2_a3>)$-+^MM8!7WOJdA0hTnYpS1+I z6WCAftw0KndvH&K6Rc4Fwu55j^H_ULfv>tk1cbmT;Q^2Wy{AqO1c6SMg1hIHIYEsx z-C9%>w!vMno2f}fQYQbztbP$beb z1t>%2olCZfp84Q~-}kMkFS?;3t?j+t`vQ%8REV0$0uE}_7Ra=O5^yoQv;kVbOjyo! z%kRULxFZA2?qZ|yqsL*%wd6?Lf!QJ#6l3&)T@v|1(NrL_c8eGIeT)Gt3}5gB7}-ZX zw*E@*-+}VHce3*A=f>PCjL;qXPf+z#2%WTJ;UNd2cIMX{x95a7s6}=?vX1*hfVYob zvYea8C&BFCdJX)jw7VwC!_C1WVRZBiOq?fMEn%zQVirM4RqM`oBEA z+HNV^s`z^NtYgV;QTL4(jcTVQfA`WPxc;)gx*#|r-V(tm6sH3Rg?IgoJ7F=m((V^t z*9&T+S@4_<9OnBEHz2zFbXaHARDp?nv*5xt1!|Gb8VI+N6{^AEvVi6SyHIc-M?9<+ zbxFX5SHZ&eZ*hS6+~W{#$T>IqxYGMah#X{AxL16(55eu~CGGtOqF?7(B6kR_r&hPA zc322m?hh|9cM%!b4sJrY#e;iQ3V6A15)d%)D)**t|8`O3ZPPdLkwO&;-Ut;Z-fta8DrHds5($C=*e zlACN7)38f=W?2<$5k3mD@qcTv_)$X|hbNi4VDUeVjlQG%qCORc0puyoLkmWRI4;bmqR;*%|K4k%kZyBFBAytn0e#3| zSrV%3ziw?q=7EwztLw^Bei=Mr5+zPuPIGHL8JbWs{ikhD$1Q#b-IncdYktPFWS~hi zW!x78E{|DkhQkrBBJis4DKl8s!?P!idb)$hD|v#NiwmT zU`Vv-?~takxC|!2C#Hr9KoJr1JvOsR)wOXR8u_rHm8NnOQJWyXOKU6`Rr97S(nIKl zh#g(U!?>f?hOA*ktxUR-Zm6oI%XfuduG+&lATNV=+LIpGNf}%fX)wrHLh2s^80EL~ z8hZY{)sg{Va15@wHgr>xY5D7IrJJT-+}3hRW|y?zApu8g#v62oq(I>b1Yy{XYALiO z0Uk>DtBiU|h!lyp-r{4R`t>_j;&uN)`h7oSd(fo0llMszKIZU@!=u`#jlbnv|3<3a zJ~!O@A~)u>ke02^0sZDopv^&M=@GyCU3(p?ye}X0%?uA*7Hl66YpBLPTxwP)lD+)T ziDz@<*`ipeq0=R4MTBMzp(xMrSCFm|!;as?$8CtCmnMYs3p35TUYq=RI#~QS`8T>Q zSigi4Rf&ZvYgF6&-MXUPJd}O%aKY-D<|(_sBs8H@9o{c_IBe)~)K6tFwsyhPyGNfb z_Lr^%v^mp*%cM}3X0F#S42nTsI^zny{{w#ERnI@|qB^GtkQ2c^{+Jnx$XbAnk6uG% zLMb?v-edx5H7Yb9Ld@K-_rm%2t2w>cZ1EOZQz;*0R)o4|Y#ROZ?YqesNlwrn{HmiS z<(c6=BK~z+h``cqABz;h28q)r+jL0Md1_`14AQAvwFksR<8{?;fSShk+`-V@$tNy$n=bWK{ zF)GaX`(pIq!L?S~O>1-Sg5(QJHPs=EBt& zn9&vy*6*@wTWuH{wQ`9fM2PUt@poT25>ZgFI`5@+X>N#58PG@;D~C&p z&M-E}PaF5H;$Gt@&DVrkM+=ab)QfC8&kx9x^(GqSfXD%w;Q!!$Egum{7tjfegconq z+}itvvI)6o|6b(lfT|OG^I>!OjN5Byz7Z(g-@=x+!`TH5u+LiT78DGyR-k<)6=01! zimV42G-*_ECl>OHNsjEb109FMR{>%ylK+ik0>#JNEA}22)L3JS3?=nek`nF# z-k10&@0FeU*0Kn3-wlbKdX2Om^dj)$`QCLQB`UUzHyXJJLui44!w1O8JQcta%Q8LpQ0+Bzw_j2rdn zuHZ5`S~4W`)YN?Ts+h1QnL(U!e)k?zm^9aFt&?VU3~7cXqYprN1?>V86mm%dDkXK_tDg=NsXgq9dj(+- zT)&3KoXU|9Il59lqjXaYf<660A6cOTx3pZoA6F{Er6hc#2K2yDW9AJeY5(8^k2IyX z^>6&7+>x5~`Qg9$G&x5=@1AB$9GZ(dHHJe+{_8i%gq9;n3w7-SF0kmQgC@4UQ;_nY zo>gh`B4{-nDfysj3|iqyHe?@hz=+igu-|**C;L2>;&WUf%OuT+b}yGr`ZFGFQEZSS zx=hp++I8(oo+CPEPfk#Y`{lCWKfB7-p52-%?B!rw!OuAMKildIug1T!XhC~v#i4Bt z9iWyazmIAuy|)FFN#zLO6W?!RZh*HM2MrLd?Jav4j6ccz>?lm@qWT0;(Fq1(W!b&8 z2Rr?VsOu|+tJ~F;wl7!}`&YNkzMb^16_mo+!WG`ukV0zSS5>|B&7n*GF;<@B0i4z3 z9^0PSD8LO`>UAf8!jC$-Wf9|}a7E2_caqWuw#)C(?yyshG&I7r3n@@@;tL0YA+14= z@6a`SynwO>UGdy?fyqBi&l63ng+tSZpy~8!_LtI^!NIO8e{8SLgk+bqpo7U2i3(kh zqlpa9rG~E$6tEDK@%O}X8#-N1X030>uNfWwv9!eXe<{~40l(nDFAqPLBj5e$uq|j^ zdt_sybRs4{1RqT7P6v<_8_>c$d1SLrpU%4~68_AMIRHSQvc$t7Yv!LNj#zn{YvGj* zJq=!9>;ff&D8`R9GAg}mHm>kbWQ1PT%?}29 zgKvOw&IOzCkm;XG_uiL$b)q#L=EEP4w~Lr;h8cxKjh>MB=gIf+DOwp2W-q^$@yEe^ z?oe4u=WkJ#+?Xg0{bTSYxOVJ{xtg{U_cXi!jIQC+XI*gp#yw9$b!i$j_N>u5-I;?P z%c*(4W0L1=Fg}b?m#zJT>ueuq-kT%n%R*K5oNkBstU^j)Lu#TmoYc~13=ch_--XMQ zC%(RSsl7ftp2q8Rv!lvf5;RiyhC5lF&0Wql_XG=7Q_0SD5858-@4^|m3e<{XVCquy zTGxZA{s{#E|yU!-`l6b0U|Kojz3apY&n+w%jy~X#!>a@?*h$Na2@4G z`0`A-i}zEd41`@i{}p)=B>TnyHUBMputcq)uyM_kaK$W95C8bzrYnpV$jb~>-_VbA z1#{M&&K*T{;Nhd2OZF|>RlpQy=@;*+0|1s^!6!@neYnG*7Cl!b`_EESSlg?3aFh@O z+1Mbg!VE2XPc$L2Zt*gXy z^1lOHlPDHdUxUmBSzhR~hFnLTUpWx}r0QI}D_Fj(9wsPqoD2)gCZy9FmkRH9JJJ~B zj}(GdqaPM*Q23*uwA67VfQN{ZWlRWc7~jyQGyd$j{khXIx}WA0|bA?5zc zSIG19y_M{bCNy!)OuavUXlVdvKSDf_4<_qBX+}IyKKGkg+P%~4)?ku706Ls!%1poU zhfjaEyPx3o;LwF}aX^m%ZbZ}y^7$CMfJ!eW0H7^`qP*tDaz38EeV=fG{>?M<037*l z1sWTrIC0OE0q}M>n$D2DprjuqDD^FrWSq)YLcIV>M9E83 zoHraJ<6L6No@}80+&Hvk5j|H4G$Rb3Q9r~A5RaaG=y#EgS0gUFKu^e4 zi-)b-N9hU%HvD;|kM^1o;u6AulCYb*yOaM>LE>vbmt^Tt?cIJ!&;m0(&SA>)vM=8^ zl)sM+`YzE-D}7gCV0_D9Kthm{`lm$-;w$pH%J(K)*aN+yVEc0-5Lo64osAEofcspL zC_*$J;q<94sXtR_Toq<_|AC{o*RSAgDsKmqt(?Jst)Lpy2m}e~SpHK3e)dkvVTP0?PX}s%^N7cJtAUCvz`|yl{x^txN$AHKAM32Sd z2Wwejf6*jX^rwcJOKR8mqpl03s2r@|n&gNX(rW#)b!su>K=`0=@y$;w27lQwNlW9M zd?R~KB%?Enu~)mz@M$$o?L93OT**tGm1D#SUU#`q7k@}d=v!x{T8PmxC;+D!bb-ZV zs0aeC+q|Av_sEunS1wlAYGVn)(NO(ZPh=#V&WGSr$mnZKpgA#46oxH2cXj8)AMnS{ zhHl()oOT^>J;Fq6+fCd^0!)g-UzZ})s=|_a ztt|OIteU2Bw^7`8wPbB*1QX2QkXJPSa!TUj83KJWN_aB~*))Rh zU%GM-?9Ujf=0lVEipRv+6@Wur(7nNP{JErXv#p#+`FhFy58S;EHu?G_urDR{`h0?{ z1N@~nr#3V>Yas~>sl5Jq#qg&AZ2YezNgmOTL~*Ohz;fQecp3tY-hU-@lm1H**wbR> z1AH$^@ORYh6lg66(*#LwyL`(Gog-i&NbNhxYm44`>dH-FL;L__^s!o~*k^ z!&qZZjb~}d4dM_*^e<}feefdE>RL{tzfBM|xaC;)8m6Id4DC-AP-);s_EKhsN^nQz=S#01L)S^`*c4Owd}di2R6gtYYBO1`o8PdO3c?()==% zOlwIPXQ5m;Ub@&V(il{&t}Uy*8^-O)x4@ZjFgbO(c|vw{X~BG@RJL-2g8|x!``PI+ zTw6dL@F)=8Zggh8@H%sz=K}1Num?@vMPg>vn;DmqjAOYxv$o#$ME~j2wxAvKOyu9M zi1$alE#BaMIlkWM#`doZHBCjp8Z-9kR77E>O zFcHz(6_tWc=P)Vve)ZW;OzB5tADEcj;XIC{fAuX>6eg>ZRMoZmtfj7o$<}_;tEH4l zf`?Tn?M~bH!On+5iQw#_V&$s=m5~H6H#;o)SK7_E{5|9f%w|q{u?|8sA5B&fA)5F0 zXArKzUMWKr11rzBjB-;bftlnEkN%t}G*lk`C;+s@u)>hJ zOOcg#Zr2Uju>IT-b5#kBcT3iSZnXczZ*-ipC{7!MWRNaFCG?D~7pw%25>$A&Vi%lm zubS3EqE#-c4W-<<+aeAcWV|pel?L!K8RzLj9+<&NzO8J;?YqBeP(PU6WGAPiZo-Q@ zxii!0E3X?AHYlw&72fF>7s~osDG)2;Bg01h)I&IU=i$&cq-*2JH8`4)YoqhMrnZk_ zm~7&8&(X(AO@=;!YZQ6X2{rI4wt zi8or)9N!RD2Tb^Uz$++8itV`yuE*sgv%Mwo@|p%CNb6iZ&sBRp{{vHRCCiY^4tSVP z>U#596MfeWPcF=boUjHGM}x*CduBy%ubzhQ5MuG#SY=rNWNauUdCb&$h|GY^*Ew4B z8nQv(3uY?4a*a| zL$uD;YP+D^u#X>Y?F;GM#rmquopgSxht}^EOn@x zGH+pQ+hbq)HjNpw!B_cH48koj9#Zr*pbB}t)pO@T!+!*b=#ZyArFwly!1|}&;AE(} zqF;;MYC(5Ea~=%9JrXO%hntmi7%bdz*g{tmRq5 zB)}3m_i|a*-8pzJ`>6RY!Eo{qeQwpxR|q{~VpkY;4vWUHxlS1F?(f&9htLFZ*KI1m zri{rg`-@&E?H8fulJ%0J%GayT_Uhz|v2(_-DA6-W^62sY3h_&F>SMErAV1DI34C_CK;cJh3ms0YdMyi;e>6 zBiXEQG=gfv6tv{m^j1BsDC3|M7FMZn zxYg3M(yD*(3m!@`FRx8gqI!EJm!5>TZozk-oIl|ZBpreOTQ@ym>MP#X@K8O>>L zvwoP%Yr$}23`9bsH4tJ98ZIH*dKiIBW6MYQY9n^$5`cgk7Wp)j64hoD$sos`$jy8$ z@4jp{;p|tVwPO=yHfrI{)pHqjhX~Tp%}pO!+z_0T+PkVa$I$;)w+qRukc_Zqc;;>` z%8ymKKG4$qCh&43uSw8~%0DQv@7aPyR6WN+r_+2)$P^31Ws_nyRz5P6NVBrpmq|qX@MEbU>h$%VzVK!^s*7O_RSBuov>%Jy5^o7?N$7n5yGxXOf#IE1Ck=U&SOa!f^?Nj&@lQ6 z%)g0f90`hbylf6cea%QObsbXg5QtKig-Qw3(}I(=2Sl{9ZD{AzOE$&*(u*>`?25JcIY=mn;0eYqQbYQ~EqGB@R?3-pA)J%>W4&tu%G8aVcwo zdlNU|@3Tq6t)@z-d!+pvpb~02V}7s79=Qa+#Rkpz`Yh29|Aa4Gv^`c=o$lu-I5@sc z1r}yGzYn??noMJ!e~WW|)!xTIEM0GSxOc0q#(JSy{aD?`+c&`}G#^p-RB~lx5Kn}?VkkohNb$a)&8)f$_&Q4 zn6&hmD2X6OT}O(;(%oB1WBky|t-Z40h&nnR`j|xUoc4an=?m068Rh!T1&^|{RG6-v zJV)#!$}(GTH{aH>`?2`0cVlbWyU90K-hAW+%vBf5_@h~Gx4eowNr$*Z*G<1I4Tkx` zP!rl5D(iFMBF1TF&)aDfqw(S7=iStb-kWWgg)a1t5nC^>Onqa3#W5JC@!ZV^x2fvT zSnr4e=c=i?Xd!8};S_J0Dk$q|`4uq=<+BA*d7po&lyj+bDuw6*NTX;EKQ{5rbCyEU zi&~Q_@tp&~WUo8>h_9Jw#yBl)oS}&IC$kj9$=z^+NlH|{({%1<*$cmvN;9pE@!Ph$Z$zy0Xl5md z6Wne^zUk=m1d$Z!k)}b)g~S<2iT6KuB7U{ErIo}L(V&VLjxHk9Oz?g5{yE~_c)<1R zS$+&{i?5m%Txyee4wA%=RU0LZwO`CsEv^_NrKR9JDOW8hgC1S?n}{kXn>iXbw0!TVjy!3+PM;JK^jQi_!dm2yDVG$12~ z-)@Qy5z#yN(l-NuQSX_L%v6&ybK8O$yZdKuMpn^{^MXgO+n$d}kpy*Kit$HsLhX_= zefw)1L1JJ;uSfpmKkCqo;c0YrrMCRLm+$}-*RNl%lHj(c1+Dx0Y=Rf5Cz4+O+6%cK z+<~QSdW@gFB9$f|V3Q{bn5S6mzt$meGyq}p?H!`k3Aq(v!DH-QSI3~z2%BWpcsBLB z=*X*YA7LN`wL5fCn@(DVt)E`%c1gO}Eo*y6TANT=1_DzQS49EXGe~?{*fW460@wHT zMrTDh`tN5mL(4IlhO38_^nJ-x6r2%^RCl_{>CO;Y2Tx5jI4A5$Q*hYGaRn~`32~Vu zx*v&Yjwfvs@;^7f?XlCVES2bOg^zl(#+UPo4=e+(NNCqPvgphMT^i>qqeT~*@1zSM z(O6!v=xxsA^M?6x-Rv)6{Z7aAtL4|136*0(*f>bLvrm5gOt#UgJ-AgLl5}9`6GBA7JK-<$N+~hi4JgCE8!#f*e116FIV8zS zW~Q!+2DPPVQhzUOCm~YAKZs?%NLV_O>J=N1ve>GXqvZG9S&1ExBDmp%$=2VKjTv5B zYk`n+dFy=7F$I>Z8drye%aU+KeC?Z_aH~||8S1vkXO~+Y+7SQUWNdOVvXkdO`L=(a z$Pz63pz7P1enSj|bNlPSv|ZT6?);*G1B<+OowV2DP{7o2_m>F4=C)#RF;f-$+me@s zp}L@AUn@nIB;!Ru;JW-i5)xL}sLvaLHV}|q+Oo<0vqS&)RR(ZJs8jpWG_?T>mi7lo zgg~_!B(~w&))(%)i|Y(SUJ9!meYL=ZKICJcw*89)1cpFMQ{&u#h}5Tbt!E2naAOZ? zcS7o2wxLvqSqo=gNn>?c$-@|6OvT=AN~R*n2@SN&s=ZB%Gg6j1>@`}Ir>;mzMMOGM z|Gn>tH$GqkyDb?-H(J0S(Zptx)h)o2mH7O@HzVB2`b=<zp3wJhhxK<-!TG{m1; zq+xc8W*6qUSkiZ?sv#J^*cMqSiru&dxwp_~ab7mAo6DBG zRbge8oVEt~C5qc9{S$`FxrnN<5%d-*`lXy=ELwZnxe_O>FkoaOs4iPK?x}-w-wdMuY|&zfla(+UeoXHE7KNmfn$Yptt+nO@u`l)PE#He&65_X^b zq2x@Z!~Cwtf|V)fYtwI_P@PZlg}3&sxTZhJ7N|4C=(k*U14 zkOEfiESwL$OR%8}Ixf@u?(twt+&u7*B9&fL>)3>3>rWf7WiR+RIFW;Cf4~oo;}qIk zd>?4bY&J76j2U)*^XvEbRNPDEBY@5-ZdF`aYbCitct0(jcl1g8QO_wo2kMLn3iUHL z?&P?$rEW#vHV;VjOL4K>OV+S=I_YyX-VtkE%R)G?%^2wPfP>3a3>E_|i>rb)7eIf9 z#wS^cB>sN%aiJ?8FOS%@3ReH;+OO8+sY4&s9;y?+IorPQG*Mdy9W^QM>3y9#rJ!1I zUg%cl_9kUCrRqyLG)(JR4rCMZek%P@pyaZix6hqtB(FrM`=I!rPM`qHmBmTQW_)kE zv6Hr=)f0!jq{Yq0JFGmu@FDX!yvbMnAyJ=$|ELN92$^GMY#Ljx)6G^C;^|co45gV4ruxcOsrEo*dZf`23JSQDBW9Pkd`)8RH z>U-U|!*o)bBLQAErrEs+D`efmeqkWy48^k-I98qzORp6aDvLSQf<{D`?6i*cPLTub zt}JlT{`z`!X`<}fTt1Atp9r|=port&ai?u5(h21ZHW;T|2vL{CID^%b{aBfuI@X;n z1Ayw=4?Efe4v`ihiWF5ROHD@Vm(Ul&RaG z6(CiZx(EGa0stG3{=K44wUuvl^qjbf3%blz($>PxvSW1{JDKgBL`PxenT+X9%I^s) zf`EvNTWo<$86X-fLc=p94k=F)lKIrSyXnfjS_|CG3yu5xcTlFhDHRIo_ zWWK5ZI8E&#>$H@1e8J`oWsAoqW0k9y*vm3?n*+0+#v7_F>!eq&uPb{&bG3KGm~*#N z`q*4dl>Sj!{Jy^OhI&(l9(Fs$G?$t#Ke92QBNx`_-8f=H?atk|Fi`+`p4qB)o0Kcn z^A?JY+BTLRddXdQzs)TE6PA_a+6TYYhFQ3tZc0Vy9`$`yF^H5}Wgylvx>>IK*K?k4 z`?L{q^Q4$7@$e1l1kPcUxyH>RFEQ9_A>yj}EFU!0XlvklgIK1T7`@WA*WKtvi`K^Y zAjXU_-?QdNJ+{4Ll9g$CE%$g+|K61P>qFg1ZaiZyivp6v(JUwA`x~SkoSAOFRC0pT>RbkACS((Sd5X5T!_uY%)_n{aiK8ZtG}e zU(0&6&yLZ%KuDsXzWPaQb`(UXFhl8%jewNfyb^EMpC|QhsLn;0{3ju!9ir(wENZvH z#jE8mh;SSG8AgkTTORI)t(|w?!2GV7P_!+c4T4c-ZtX*}KyeE)15iPg&rhx#P6C-M zj2gcpxSPz4X>wN4=;1yYl{`|URr`o)Tl8nNk|A7~9rKRWlY#zL{n;_qNL61VqyzS95YFjF9vfQJ$vOWS47dF#oRCOE+sr zpHx(ciEEr{#7v|k>R?-w{ zinv*30_BH<4o9oqIRhU%5auBm*p2XMpq^a_LZvB<&HRs}vyN-({oDA@FCr=vq(=)P zsMG+dQ7T~(A`;SLgycv8fg!ChN~DC50@4hmo6(JQ$LQ{k=l1!B6Fb0*!#Q_+?(2GA z*0XlqnU-nA8Ah^84u6&!{AcL=+pZl1Gz&2prF8BKkyKw$de3rv&IkAcb1;ioDFbMQ};fD_I`q~sZ?$WfDx>6fMEE^E$m!w23c=7Zf~;Kz$b|$ zLcW^^c`AIrq0D&GvBi*zdJw$a1-Akj%sBCeR6l%`%>l_hwb|*Cw;Nz}>s!dG%|6s- zd6Iq(HQIAO+XnoKLfV3B&L72A@fQGOC^AE4g)cJ3;Y9xFy3r$5(ocRUCOd8k@hy>@ zVSn41vfX&$QC7MeyVWcda%$VME)<>HL>F=zb-s; zW`CnV>o+ZuGTmB{9^<|&n$k?kX|~6hlD~Xz$SX#y1~NYr+0R`ng-?Td?DLdK4yhVL zyQKNXLfx|gPE{u5=ykR8Y4AO_uqX)Nl!}<o2=b2}2C z-_FVyToSKz6(IS>19fNTEnt3~SbJk?$+PsQ8*GAq_{-V(+LPcIfDG}UD7~guvFCGq z@>`J4^XRs~yxq;7kY^Cr+nkI&Bc8bt7;Z)xuvNPYd|*bcYAz*<@4U|Pk#q^Fa~ecP z24>Xaagg#WxcpY%3HYuM`#h`SIJ!*}vcBjI6I!sPKLf5iy?Ae2X%uagE%p`6-O?O! zYnbYV2doP=K^g?H4lPOYwZyidibtEfDf48(utHs5tD!h?m)EkswJ=M~xb?=7E8@f8 zkV2gENrA5=oet0=b}qy#9Iy(V2J?YI|dFI@qF@ z;)*H-v79QGad=N{M*3)dH`fS6FNBo~Nic`JvBI47llolvohq_CUobq=rI#S5bpTg| zi62{Je=DxUpi>K$`nJCJ`eX`zavOP+BK)X5NM^d-zkW79Ig|2MPP-_?hD}QToFsB1Z;l+mA4l@r-AhZt!*K?YCkwf+=+7d< zm2uGmAG(XEV>^Zvq8B9JP>7%DfPty*&zwgkp-6G^c10PeWn`dzLK-IKZ?5noGFm6S z8iOE@pEsMoBGswip=%bE>|1vClg-P5RXH%h}s% z>pDyxbfj5;-#bb}FTr@G4^`N2*fYMP@5(a-dIIBCBrZ$!sUW24IlY-Xu$ESPD?I2X zuX;|E4LB1ne(XYM`;&Vqs5vj7ojvRyOwpq&NaPeMj=A9YY!E9|t9LV3xX-(>mZKHtVe)RoHM~&4|Gd z`?KlSg%UH`V0Y}^F$*{dE0Uy##(Z(eBrW=15hxrnZ{CTbh`=UtC1_0t+pHLS>>7r!Im6q=x7Mx3vJ84{Uf(2p{7N3@K zI|_5LdjmQo_QvuEh0y93%W3bABi)m;b~^12G#Gk}qw4b;`@&#dygT~CO1x5jDZ18~ z^lCyL(IucYTWLEv5_ZxydhzQwC15b#mU&%KDDk!=ellfmpt&i2^07m~S?NsTu-$s( z!uH9`>$3LJcQA-XgStEFwSRK_AWH0py?%<}`7^^-S5+BPXr50{`{>UU2j=zEK}|QB z%Nh7cllJJ*Qp3~kAUNF>?eH_Z+g(4i3Gq3~o@W(|-cK#U7q|t(v}29*OqPerJxv0g z=%cYBZu}0{jf3FCTi-&ySW#rmpoI25riY#n*mz9D8cmwq=FE^4qTbsKr}q31lr0T$7!dUh)8Zj; z06nf2Pa?9BJe?6-#o*c;w;<}zw(&@i$N$+)`WNCyZLa>x1UBeW037RQ7C|oCdXLb4 z$m<`b>ev@-M#=^j-$9%BFeU-w0~N#&EC5;Kg5zJobDb;X(+C&fqtEd{iv*g(?EVZ& z3yeGuYO{Praq`Cq8ltzDM6B~sV07q6f-;Hf4u0Xy3UGr>(6gUOL6Tdt|zN4MZE}Dg{eMi3iI>O8YZHv zs_f~HfUs_?ul2Gr)q}l#NgB+}{+;HlK+w9sImS_QcNng6IAokkaA-vXc2m(F#_0sQ z;y6@cR+AiJKl(4ExB;)WC=c^UPP;7R_RmLd=V~w^+yN2OAI`im!IdG44P@5H@DX;V zoBqp*f14o~z0q~n`VK6@*WM>`GawEh;2YBBO1&P8CA9Y&@Yg&=F8vN>i6?vVDKJtX z960fD$bBXc5%@=~V4vxK;46wzHtrrP%I7K^OdMzqYeHcB4y7Fo4#3M~JH180q^RS+>m3D$Nd-5EOO&+D0P3BBQ|iUA4Z;@{0snD6A^+ z!|0`JS5PmT%*QMDK5+$1BwfM9-cMx^W|7mS@?o5jirJ@FoV16wRQ+#T#6Q=h>EDFTpS0;^av&O5teQ%^#+~l;!4?Ja{=VE!7#W-@Q?xGb9}tgdy?D_X5SzD%vyTU zh3=q5+IX>EAm)EaC1((U_$cH3NSd#)MJ2kOTm};{Ql6_^iOFX4w~HImYV}W6mZw{n zi|H%hXlOk@ZF;AYx*~`tVLSCm)ms0IfG<{kj3h~-^Jk!fD}JYu{Ob^`Z>A;ON$?5l zyVxe6>^G9`Q+}?d`1HkWFe`NJx&p_0h>uQ$6XlzE>lRWWpODVy(!cD$ijE*@QQO@X zx0iLE^Xrb3^Qqdx;#_hEMV+Qod_351)oP9u06@_`(gBDyHWs<=xq0_-0g&?mvs52Z z)EbXaG2CC`KD}EYNW~(+4h8*;`UZ^768f~qRrdTJ&*+$PhcfkhcaoBoOCJJ}r-S0b z&gU1w4vPB-%j1TZJ9ilaj}W85A9i?WK_F=iGU7A&63LqTad)CYRt=~_u{lVejEJ`w zuZQFQdW%tzIIt#c@WLCvS;qLWGSbb-8QV%j|83)Q+#M123h`eFA)(b{XRcqVG>eCu z)zOIb^-V9j^ip08yy0LOsjzfRY||%FArogr7m1MgjlK>&+MR!~S1HkwhIwB*Tofo~ zwKZk~`ktFPY8vaV54?q^RulnpNdw+iHM=0ikFaH=sspU90P@e$u&w9YN5aZ%?=3-U_Qnz2h zUETulaA|Ev0b!6F_6ii%F=6Ukx&%9ct<$JwZz-D&2Z1foX{Yrz7%5D>M*R*^BE6$- zJxuIJd{M6*+A#a%E@sc+i}GE_Fw7J_q-qe2y5*lNGjI|Kk@fuj31DY0VZX0t?*~&2 z|46ENz<9&*^^cRLh6_@>u)I6zFcv(z58A6{%twJVj?$P+uqT`=?~$ri0v9`-|6#lw zoyaF}xG2AmvQtvU8tK)*wA50Le;e-Ngyqj29ME?okVl+7V@bQQ0%Od8M{4%|osp4+7s^x85lszocMKcsF5P=B$RIz3$6SL_U_PWZ_wHCla zeo=10P4QK%G14)ws)CNDjThTw{Hoja5-v<)cb32Dm#yigoST3$_xZ8j%_|@mAFG75 zZW7b5A-fWO-=>)5<{nnn3T7S(cqj7uYnYF{9)yTo?LB=TET&IBQh?H2ik>SLta=99_zZv{N^Ps^_5(uJ!-IMSHyIo_Wo|@46Kh668({!NWz88D4MT`PQd%pI2y}QMs(+{S|J}RgYuodO66 z-cB97&@O}E!e}y&o`z1PwdWa7e~n~GFqM0p^%udRUMAsLsIgh~%&N@hZKl)DbwGn!E*dQ!srN?3i3_0#S&oN>wi5R!lBg-BJMon0M+;T^rGRhBL zeewzgCRQ5lm8Gly=pWd6kMI?rR|QM(zQwJz`v#qg5bH}D%fqJYV{AfSoyo`fW&Q{Z zNg3(8FT-}NAtMRcg#a?4+gz_b1XN^zzp#Kz(qYL5AM42_xy+E1RsPUqtd+9 zhXAVLr)!f-hiAMky&|-r=4^_OE~7VL-;GKLLKN)PbmY}S2b}e&Gl9me z`M!jOW%3cZ|K6l>I*Z$-A?$EX2U@w?$$aDZ1mWG==3jsNcw~kvZcK>XyEqIu2sR&hq)nZ7RP0ag-}Bz! z3J*WtK2OGXE-TAikuW!Vym`=bL5|+!(f$^Rl<^~TULv_4bq0U_5d~R@h@r3UxT=L( zJ++uQ0i6EJ=6h2QV>597|FbeY)3*2b^29?~A=;w9Xe^ID4L2$umF3A)3Vc;3G6>V# za=UH-Sya}d5`5~c;j)T?ur?b92A>J>FI~&hVIW+!#4c44@ZSY3DoAF*Y&Y zIMMpL(#DVjqoB(MK3El=#?E`9qzvf)UtKt10xUAl?`1+o{CFCQ#+ z3mY6KE_FAM_)MBhe$Zh&cakzXFP1s3_;-%L|2vuQiIw-x@E3-80!l+N26mFo64TK` zlSb~J|50wDNGoye1uLf3=ZkBFM!n0l%PwKV;@eI_C+32z-lf*05p79@Db1JM=0(L3 zVXA-Pqm|aOJ*ZY(Dn)V(@@b=g;Vln@gpBh=LL0B+-%1C$cj(yL>BjZqH2ycSWrZe= zh1SwyTq}s{j}MF*MaFrcLoFuV{qsj2Uv3p4#8i4HgwE0$nH@Qk3BxOI@f0*j&3>q* zwH^%34+=@#-aBr0n9p4Xc?2{ZLTKF&oMgPA`3a2^qqOx}SiN76>gU&DmLp-?)#K7e z`s$(sD~}wt+A3g{xZLL%Ao&Y~Txr_Yv2Fsfus6}A?f7*h&4YcU8zn~5b;7|+xpMm) zK6;;7#`=D<&{}WP=BSC0%TJFvW?x>{yf4sZ5$q+GKShN570Xkuah70csAp18WuR!) zM%Yo+Yg34=rdNw-kGmIt?g#wF#$ zk_r6W_eqaF-}wps`yp0Jf)khziVJW^T1@qycIeDa?;TB|70+|^2Zrmxk%4XtI@;Hf z`8nznuHWQghgtN5ZCL@#HTKPyc`s-&wVDmCv$ikstvu8B2mtc+eKOn$%1 zQUgDs06QJgqdwHbR%tA}$eMIPNec?I+kKn;KcQP-M5)A2X+q-|rM(DP8Zr ztE^ixoGWj%UPEm$U24uKfF|d$)2-|^r_Gg4FmW4v8KEqqNQ{+-J`(MX@(uWsxkD=J0VLnp_6+ z?-HC?xR#&P!z>ei4`+M=X@ipCZpuW@KMP)Cs}blFwE4Konq}67>U_^biTaHjZ`g18 z(W>BYLe3OzhWN(DJS9KUzyp=rul0E7$RO2@hE3>AZgjH1184a@y}<4t4)j-9|E$dZ z9)2;lIlet>Z9-vRQ(_d8?YyzFU$(Ptc$ZComcwd24{>2sD1Y(w?iRy6xr@3P9Cq8d z7M+p$3??=xr?$b0bvx>vf{wUrg@2gdta!K1@?{5mZDDVWUJ^Ql*6Y40ahwr;PC|6j z_(+uwa2*j0upmSC0Iw68PxZziSS-%)`^NLTqYIihcIpe>$gNLoNQp8|$IL<7&FJ8r z=S~AkHm)?7Eti5u8Bvbun0X17iOSFJ7yr0NAEjyDTpYCrvy zA1r2~YD&Ui!4yaix^&{N6JgVRy9IQ_Omrt<+xx0D>hayz-~qk$M7obicBy<>Tkc^L z)nV>WAI(I~Xy{8ckl-1=o4=0tS^D~@(>U?B$5=ZDuxhN|OjMX*g$RvuYjzwd(*d1K zd%xclxQXkjfcca($yd5{gm7S5*rZpIXOsz&pFw< zIcSodl}`!QX}LjGRln!ld#c!jp3*W)9^$?1V^Vyb?Xb&+5rQ$_dE?sv6$DJB zzxrnmPcT{UI=R;K$|MHFxGrJsuE`wci72y#v7Pnq92Fn}UL9=aOCiw@2K}lbot<{B zCj2&vMlFqwa;L$ZP#Gt$>4$o-OLp#!46>M31*hm>g#P?1*x{;a`jkrjaYsbVmiTQM z5bwOibe)i|`@Gv^o@?|?4C#e?IEvWwPnbwaN2z3l9HWG>?&Uo;tMzi;D?k(_V(dtb z?>7#WweN^GJBix!iP`w~0fC&?NFqMM@c3SGzC`}|un%t7F7cw_ax6`SqGw9PY$3rm%1N8Jt4jhOLsA5B;wA0NgR~2K9c*xWUnk# zlt5DGU76Z3-F~!Wu)-MyWb0B7I?|I}FTNrNWM6j)cV- zY%G4;nP)ZK%kC2v7>Z(cA{x(rCJaN1N-3QBX$ra8TU*zx(7k7sEU$$95gH6AUP?D` zDc0p`RtZ3u$v@c0z>mGI+ev}X@6~JJkpmY< zT~rE3R>jujmY&h;akmPzjhwp$9nHvf0!}%7>ddy_Q{PitP-Y! zlmPvI;{zrqb@X}}iz{$sc;gn|JF;2>vypwt5RAfKqx#kLj6cOI-{P6%VM9#BD%fF7 z2}UDOh`UpK4{DjzkbOUY=s8ogsBkjlJG9|(TK}!$hftN`216ZMjKOOc^5)+^53&Plh z9t@JzA6pB(-lE1B*s=GZ>HVQRhQb0$(`#Q50)+g&+pvgU95+wAu++_Fehb4P$Jq?m z9SPknwVO=SP=0j4nn$1mfN4Rs412tjAu1Ion|||+F0&%F#kbSXZ@<4E_*TijvO@0HFVa~Si z;W_nojhS5l>`C*#Db~Kk0K# zb4MvI1}jvF@8S2aMO0*Dw)H%A46_LYT*`j#b6FC^oAp>n{T1Eb`aaopujDRHU@v3( zT-#qx?mwOq6U(PXO=!x{x`<|;`wC87Hn3@E8NT)I@_%^;+;~2Uj2<{|t|YN7@m$Jf+KS zhk>j-lRliAHgs*K-}XYbB`~+FTw9$^kvUP3El<69Aya#-hZA7_zAULb%|dr|=XJWt zT{R^3|G>@_+|uYlQNE-cHbPk}ZSs<6luUnB&7z3kEE(G!ZvXVkf0}2(_g1V=p~#VenZKj*4P{+CxeBZrHJv4Y0N7i zr)b^WVmHU058z>*!J_ohbG}7es>kO3&nzsdAfeKpyqjLJAVvFzG=j>*gef#CQUZJU zI#@aeKu0975+av|F8i*;MEl6VWM%H*iIUs?FK&>AnwH2Oe*4u6T6i|!TR}^KtAJaOU z-B^jaj?6@whJ}3C7iPS1xJOOu33Fe*U*Mj07UWxJyA?*q^5M|6aa&7>UzhOtF8or2 zf2d6Q7PH%0Bu(-OH6|mI4L@8tbRJbb*!C`Vm@&7}pL=^a#t|xM)+ zY&UW{>^L+F4XfIO^Ok>z8R-v?C&c1<>>?Mrg`>vu{4Q)y%+&bgtSZ;K|!K?^_Pidf*QPuq-`oRj{b`(-c zz(}hqmZNqMbeDLPlJ_i)n8>?n1Euq?I7>IqL_Vk+-@@3(J~-Jkf#Dtv-LvdLN`X!_ zlnbjpc|Oy=Pg_(*bLEs9crcVGW4J!sx10pmPgQnLkk>K@-bLPFFECx-`fF@hMGeJm zVfW-igr%VRn*<*X6=^zg4M04xjrXj@0jJD&O|jViDu)^axE4M~*QK^2sn#*+q=3C< zbj$2!jiXCAEcusdEi3Wa-)BtUI=W>NP%0wTAme`f-IhBaFpwL`Wk}3(|7(m|w_T5R zeGnl|x943cFwtUojcJpXI+y#zzz+%8O|VPts(q8js(8o$8ulSFe=A(bf9>t1+*;jp`aC7 z(u6r^`EEWz`R6c*E z81ZyBZ=X$Atvv=Vwlu>y-;hw|j$sLT@&r(&)Sg;#HgsRN<=y%t4(le@?SQwJ7xn-I zyX6Nk1AOhCGOk5O@Ad>z;d2gjhkO%(|-!#zNjkh)wu@bQfYY(8$ zFX67V)hdz-x})mlts|~GLU|C22&45+UxWRyu(ex#IGh*D7UjnEEevg-A5Etj4{ zZ%VUecfG*ZadAW@dj{z=s2Ze6+>lOQu1X4h-n1_NVxuKAu(ha_%M`$P7Ftl;b)gR~ zqF7OVq2J~%8Q1?|WCC|PNKY5sQNE)}e-^XL_W)?(Wf(+uS*2Y}$-`}2r> zahXoouv>m`lgs=oS*cT_tuumLdsAsZ{agpOl;Y?j{skP$D-CKR?-do(sb-e;d}XTq z-JzUzoV1WQ;@ezy-)Sr*Gb-Kl`Ht>TH*2&F=k(BN`B(yu%g(Tx$W`%Yr!x-4I9%q z$aDZ9qfBmz3PxaF6w~2G1D9l5w<3MFpkqa9kMlQK^3W#56lcs9?n&dWH!CNXuUDxU zdF`lu?95LGlrkGSw5D1x^62nMjKM}2?ur3_b+%_96W090nmucgWSpa%w9NvlI4W&4 zR?OaAch5W1==C63t{tqPmYlEy_{e41L%=%|mM$h=JxEp(Ym5TYK9UWU?;iRUyHvXI zMfGg{PQIeGEPi`)7kZ`t``*nUIIPawTuaeT56h`U> z(CJSJGZwJ^73V#rj!R@B(qnqvvL@SFw7pk>{wh@e*im1T8HdPE$seutTTWh+EQV7h z2=N#N^yNSNs~)6mQ2cPjif>NT8#$9o8|z~=1cj%LfNYA-9yg=>_;zFC$-ri>As?P1 zV!8#7-Uu|BR{)?cm2nd3dK^D|8cR0hE$@L9evZuZptwSI?Gic6FRigp`^*yhT@kzs z4mDTxT9c%r-?qj=Ng{I7{fh4_@j$bK5!QI|Tj0h|@8%W%PeziPeBxv6n&MM{-oCZ; z`8F`Oxep{mQByatB9Ux5M)E^G!pxP(0zOe@O<)Yvim;0`gywWuQh~vn`*SsM3Fc#8 zk-z1vC+O~@T-Ul9zFpybNW+vdO`e(vq^jewMwHeE|JQ#jP-|aLuq@%J8BvZF5h*!t z%;dbE=skNf7#TQWdE03im)j$J`g8ibVZ50|O?&BaJjzsZC-06oA1B_ndkff|D`T>^ zPT2qs=&nlDTEIQoC6b-SN|Bq6%T&25o0WXG9dn*NA>=wUQvy=r{x@~lK55svcdxm= z4>5KV(YQZq+Kiy(eV3yzMI1C`mTXMtXWlpdh{^SU+H{0-%1UO)PBArzl zLOn?dWAcGjQf6Jnhk7-G%szG->?@m+$n;HBSPpfrSoPI_q*Ovbi$_q-e^Q~>`n4Wu zvu8b(iPTO)LUXzkU-KH~R6w%#q?HJz6`CQ;b#lpsVCHZ)DV1crc3LC7=Z|nQ?h8JM z`-MP9Y0fi_`)v+1@IhFsEHk^Ao1~cf$gC>p4WC~xTPv#osq=z|ELE3~61zY?ePN63 zxqww}`WyP^Z}pBRZM$7?iJQU>+jB4I0H~_!xbHgQ{B1_+g(GU{+re3kTt@BW0|o`?IM9V73YD`rRtfD883R&wL>WAd91~+zVSJ#7X$5>+7PI)OhqtLA{(esrZy%Jm6Fu*|N1%ex!!- zy;n42D%wSMF+8qS_X{aSCP9Ei-7oD}qtzRCbdR$30kQ|eqrvxgFWX_$2Ql1TIQv>W zP-_}myu;#=e05wGODOc*}07yqF;eL81Zqae#B}XWdy(*kn0dh|Og+ zrKV=1a`P-vB2g) zfhi^PVtu0yh!xw&Okn7>m_JPbZoy#rQ=H~n7zw_GX#M(zi+-eMMq)+ns{mI!I=Uo` zqzshln;%gVS<7VJe?ZNIMDmC$i;YO`X6rmz=D^n_?6E^VQDiISmyb7Y_?v7<43{}8 zZIG*Fw7m{d%?>aMI8h>5@f)$@@n!cT_kS=NE9ed;Ma@%RlT}=tXNYAqLj6*{6ZFoA zF$U!=KX>_juQlgw((O(VBbndaAHuR+Co~bq(3wzT=;(msV%ToQ2hqhk{k`(vb2uNc z^m6j>A@q}x-djdz>Zapxwju9b_~HL#5(>GnVA9qS(Y;o|`OoZj#s+=UZVE=TmNbyeK|jE-C~p6vTpX?}VuGQA@2)jf1~J2i?vOv~B}_JvLEk)` zxkyT_`A%Iok{-RA2}m&AbfVP<#VXgD=WLs^i*Nb!le`y^a2u1U_ISQsM(j|&dB1t; z=2X}(v9atyYS@UTzwg*W#z#`@X@}3N9(}RgvfXX!t-5>$e>BaSrkm3&2^d5OR&hVA zfz~eic-VO8WxK-61rAyS$!eUgwHeR~$R7G{g2YD$}_|ELoUm$ew{CxKUy0OiE3qVNP{auIKZBE&7)3 z;$JM@vB2lhRs&ul)YthBu%=r11QpOy<4?+4%hvq@Fc+TDxIHbwIhVzTn^-`c%;t?S z%(;Lfi=Dao4YlYJ?Y`PM($gIU()m07#7u5+AoO!pVJra%C2iB$mhqT+(dzsFFJ(c9 zY26vGzG2lMz1f!$i%$sxM6|QzVmBlx|YSxWrne zyUnj^L(3%86M-nm|L6)>;Vbtp(WQ!Ru&&L1TVC^5fEj6c$E8%Ah`H9m$93$qwWxRk z`G`J?RRz!HG$~v2m;!w_=%UEY zJQSW7n}4k_cxM4V)&tCw$M(z{W^)RDJ-d;yv}{J0DpS_=BqkG?2x*7aQ!dn_fVl5~o*d zl6%H}LUFqt50(VX}Fg#?c&Bd3?Q=qX}vsjj}V) z*2v4)D!d@U58Z0&j&x%Y81mmUWE$-Fil_{m{w4*pZv0^bJ;lp|a+H_Mx_Zq5w7VYo z_sq&hN{$KLUYetB))aecw^}O3PdgDU)y*M!#>;@V zqy=u{^Pxw;e>xYewts0M^v#7Z;Ty8ksdWKq2%Q|69rFmhpa#h$$VfXHLagOc<{_}3 zpk2dpbhX|8oiGXJ&4_y5OO#!P5vl%nB$v_6UpeR_L~uAYLPylw+}&|s9wM-^RC$|k2N%2cLB?#2tR8B&?$@&mO z#GU%?@{W-WosTy^DZ@Wic6;xgIcU&ppQ*sCD+l(UrPu!@C&;)#ZHmlc9c(Dv!NiE@Pg-J~dcn4?I#Fm5<<}gr7}am3%pC z{#$!_bcMfK@I2nSjJsN?J=?k}zT&?kfZZ#ZOVO)6&oh~ewc5-4D`JK}TIyAM&x5eO z2CSl(`&n}v-b!h9tz{P}WDJiIUYWkIg)W&0S{P z7dy=xZS$kZ<9p%(-T8!=@ueNrEt-74BeCkb7?IhQW!oF+^2?6+ zw~Q9dL+@hU!T~#?){sauN}jQaf21yQ0Vq8>$?u4i3_l1YQM*IcH}#qOemXHeN#oPX zeSeQzd)@ByQS&-ofVd+V3|2@x3wUocd+LUj2#|t?TeoAP5YxeO?-$AAQ{GxA5&3&L z=}!7{7JVXxnx?&;X&>|6VK(3bU;gtOQq374sB5Cz28%byaPQzJMz}uy*E)3O|GiEa zemf(cwcV-RLh3V^bW8K|J0Rm8njE+ zdrDDu9XiakBU?}QKeQ8kBf`)W|1@Lc2MVWt(fxAPb$wU1Wvp1}oeN9lxuKT1v>nN% zWX(zaNHG0oof|D!jo81G>^-UPb+D=mtgNyzmyG$Uel%Qg$MN**Y)I+*lCx<54J%c- zw`4*Ia0T-dbl_QIlgT!85xOU|_m>>pGs6e#U~;mf;Zm8myE6{^`lK=h8$QrR7IyT? z-31%+qC}U6x!8M&k{IaAmQCqEc87vzhT*ZTwUNIi0FQ|_()pjZ0|^BFse$w2QP3-Y zubQZP(Ap+%ngjj%8ff>Ca2;wrpOKB+U**lPcVO7wREGx)Gi3QpzO~#jnIQV6Kz}0p zhz?0UEEuT!ss612qe}6X+TXA#XnV#i^^&{$*1u&X&*RR1@^t78$!RWk1B{F=X~LFT zTG+oRBjcVes(t<&HBG5sB-S=!rXP_#u3N=$gW*NQ_L$p?&6{ft%g5af0jJG%W@hs{ah+S+}Fm*(u=f$OJ+Rbvc-RYE4eOKzky_zMDMQ=pZc&RRD6S$#phyI48V zIE{}mF*)Zs%&u{JNLy=#YSVZ;nrzL9>i&>5C1!f2{#={xBueI2(91n>ir6W~K*0Tl z8~yCB|JJANOU6B(W0juXfz`2?(jC-|zD-Inb8ZUBs zk}=ywf-LUuEI@%Z@GnHeN7l3n*@%J~lhv_2$i{sWPo%(Rvr0X!<1>^OC={ z)%|A-pPnmII7n|}t*l$L)ujJ~x7F61Z3*fT2tMo+NuhaX%DG6^=Vl8@?~@)=nR_CG2 z_Sqhzx7O@k!TL7azZfd+E-;eKTb3gasb`Vp8nVj&ZX23R)nRb^)o)u*O@M9wBvJ<3 zCY(td9pCNo^J1MIqKL?;NIa|dpcfd_U!2*<^@MeT#mSiH(YmGcJRtN(OQdU*Q4tFP-DnDS4ZeGaTN3Rj}d?v`(V-CVGdvbR4|L+_rU_fF&BbVg_4$IfHUfVQ_P zxLa-dXc*&ArbxR1$gM7uYgs=S?A|MTGbX>}6<1%5e}D|v1J%Gc2Q6zp#WR25I_dOi z3B8m(NwqTikmx@_qQ6AJ`S0kw?(^ns{%2#t)nv0S->l7tWWEa8=?U^LciIY#$mu?A z(Vvyf*aulLe+)H@j<ItzFdh0PWj z8QkN}kTWaT)LrS|$R{7dT4L$PEiUfH3_1WJ=!DImuM2aXe{*agCA?;lrYCr)hFQ4j zi4W`0Qin0R`I1sis*}&2=Pik#3e&K2*=wfe0=*2F2CbmVJ^xMJ#5wx{W{H4(gusn) z+@6H4>xe8TJTyTSy2g6r-A`7hq{Qm(5d}R1@dx6vPE)_Sr}%#F9WWmWK9EnzV)+|T z4^`x6K6-*Vi5;|LdY8CtGF!PXld35fdC_px5$ zs73Ds)yUE#>7G}AyOym=MPL8hp{D=jCKQRN_xT;uWcI4()jNZf-#3u=rWDaJ>>I0m z8A&|!?@p%$RS)!{6zh#IB5;(~5#GZYvLSyurh}xoT0Fj`FkE(XBOiQC$?99MZQ;~# z+JSF{-6sfFSC6r9zLIfkNPR6nEx_CF_M7P9{=qGMT4&0XY&Lo#DU8vocjVyj0Qls_ zhI%SXmO0K@|ITM<)1L{``(Kh-+P}|jbu;Y4ZsJREqTuS3fVOdYsUPYv?W-rtz%&1| zYNHpwZ?ao}o8fJFknOfGysID+dSXp67BW8OKF7TfKizFeW?wF5_w$QOx{w-gIF$<3 z;?Y}jwG;sg`;b@xhhy1-&w2sxM-$p-Vb>5c2I@A=)Ua1s@xhsfW6|bAQeuivU-r;} zHY$d_(+CnU_hZw})GuBh%5O;&k){_#8f3E)eHbb;$rx7TLGK0^Vp!`>)4QAqJGk}E zOj_MsvcCG4XH4#_Y1zAWt=>CZQ|9$n#;UULPC=(R-WSb5vx-oW4bwk*ha9*Dt9=wU zyEJGP&cA}+w4Zrv-?pD3VW3Z?)S)AK8Ek-fU%1cWlRg2#yr#82A_=;skkf`8{&bh2o#i{)o-x#opm#%kkY+>G_P=hIUjz}V?MCk_ga-Jq6qkk+LGNgrS>M__ z{Ak*BS$$#?QrJ0XW4*Nauw&hlk7O*;X-Ev;75-6zNELPuILP-yt%o#hLIVFx_BY!( zyl<8qX@GMrniZ4H$REOeXSJ(UwTuW}6-f-76$!9@|%+n3k z5jphR2fmjg&|9BXu^uX(?BjG2)wHc4>JzN0D(-$aj@>asA)EkldZGD0bfJ(~2bCgS zXcCMef#lAR2io`;7WFpnMV6UZjpAXU;Uto}d0}1a8sDRiHHW9&$AW_$a8=fDNWrhEKK9F~<5N{-s^7*Y$Xv)U2EM6n*Qt8mn2Z+EH~Z}##DB_0e4zm|w8XcPN~Yf` zVV~rqWg`vb$@YW{_75v+OlWE{3v}l^!r?DGxvRZZBWAXe#3$3FOUjM4Te+r=+^WvI z4!jEGln;*vxS-7Z&GF)QeNy;Sko$_AB*?eAf|DzzVdPd{&)A(7dEZDgoV{%hDy2A? zDeRX^q{|nI!g8AOoQ_-bNGK_y_Tfe3X*u&IIC2wxt%(Gxo#He0Pd+M7_UOymG^q43 zufpz^G|johQ|LtHb@XqA)0p=+(^=m#mtAhMc zl9KBQ_$QBo%!C(Qm$tcHSaA|=(g0UJ{(!k(aFAYSkkf%{TCN`Pcrc$x zvX;l~5=OmfPPZ2Z1?qaW6=N<#n$PRY$orN|3F>9)k*@8~BRff*DN7~`&5LUB`6qq& z8AwT$k|X+7^HcJGeR2oN#`<7Xv}--Jo!wjVxPjPm#knLFvP_4A5;gG0y^ki6VoE`} zchHd>6ugpofuh^+Z$+>~i~SDJ8@6%L{?m&8dg8j5%2-8TapiSjghqwf9?yXH`@O-YGfRt#PyDvZ@e8jev&aD_tTzOFI4;D2C48IGEy!oZJO2FOhmC1bL zp-Xnk#m^2pvCFn;cBoUl0!xACVSaqm{FB2TwgViTkhR)5Enr>3s$-|_ zl#Z%=EcMdnhFhQGH>ObB7bo%GA;QSA(v$YgN&1i`PGn#3td@IAHL(h!-RVSPGcv&P zfk;S`rY1MJ|Lc$eoI3dR_YFlsC8r5G5-dJ>|Fnhhrq0GH|1vf&+2(rJZ9%1zA6up$ zMQXBC<1|mandm?H*FB=|@pTKcDOvc_Z;nu-*?UO_Q(Y@1jq~$bkrdJ$JlFaY5SV69 z)o+x%E71*cyX((_RSdU{exPQnh2@TFS4y|vhaSZK-(T=I@)c3V$ z1ZF6%-nD~?{6Bk1Z<3m5AIPKXBOCwraCzk?H>NwDjdhoWh!UmRE{A>gDBvSeO_4qy>zdSii@4QOFE% zxL^^DhSu*xwHvwP^ENM4<5Q2 ziZM4~*urWm1#~+HwKZg?tDTM_E4Q;&sImO|w6qzrN~W+ILH+c8v!(ikG`H9}HOWpb zj92haWYT#Iie}s{Zv`d-}LfSkd0AR!l1@!(OFkXQphv!m%hDZ ztWb^Gq6_=)P@&~Sah5yt)W}|$v{xRI;B0fUsuDMM z*Y5u~y3VL3nl-E+3L+7d8oHu_V1NWv2vtM`r3zA|g%A+wy@QAlg#aSGOBd-?I)+Fn zfzUfh38DAix$FIt*_qvQvb$$?W}foCGf@Y{fr}=m{Os<6cf>F6J~*?vRr~c|*I3wP zLa>B=TqM|;RoH<*KR&EZXmMjys@f7 zRSSu`UL&|a`89*$G;JK~1wXFhA$1v9=5^27wt@&5D9l=%mYna$clo&i!avj*X&&8I zw)8c3HAtSp#0^@NUV9^+cAN{UH8cFh(K94Q1IQYa4m&f*g@m7+c>%T==+VIOcnFkUUrAGhFiYMGG<~5`rsss+8}N)h zpQXb%EXQN|8?&BroK+W5$1cTmx)i-4seuClqT$~~2i-UVPnrboc7ta<1tH2{Kkq3J z;oC9Pf3NF1BmseRgilz9xS3m)Y%?b0)rU5)7D$ovzXYNy#c(On7+rVDF$43K2V9jA zV*;3#bi*3w$QVnAvE}=Gy{&naobKS*4MH&?B~wy<-jk0UoD8BTw4CT%|zu6fG#F zWH?u2Cjc@?i)6wl3y?d43!An>G1ev)u%lmwUfQ9rdz_6MJ!27gA@qT^@r2OTiiJr#ukldA-kEl$PSm=w0W>!N@zl zN>e#yzo#C65?GiKP617?!2lp2n?iyYowwhmHI;(zH?2e|{t}%MG!q-kT}+JNsEzz} z<4C95&nLlqivIWS+$?(@Dw$T-1y&bXg>XggY|inZ86SI_6Nb{wmU~Et1;$F5N$}!K z)#qeW(4NK#FvCA~kCCtpjejrc6@z;hw(Aa3pTp_;O65wAHFoIfT~Rxh4Cd>YRi@2s zVV*#I;xizHTH#IUN;*7HmL*hrm1%-z0_)J`jphrZSOpcbVQMDvqdo>}_&3{V(1odc zup6cTyBdYTCQ5#TN)cp^$kH8gR=r@KwJ->PHyVSvPeet1(mX}u1Mj}_#msQ{45hFj z_hvXw$+vxm`B(#mn@!fAT7KO_LQCHe-r$WSonXPCJ3<&VCP-vmRe(HW3cKaLq(u3r ziB;u~5jzV8`+Ne`16Csog9mXO67O`FlkIUrfkQtIabwx9qQek%wQc+WOihALf~!`% zVE*UkC}O1|A`epJ?mujSH%QOl`Z&W9o@F|73a{5iE9Jin$HDXtv=x$h&e57r@anB zXN2h**!b_P%LQ4IaO^4GzzVdK9=6DN4x?!ZEfE7#_fOuc!6>~BLtpO1Mui1%rJ|vy z8j>EXb!v!jScm%mB4pAwM?`VTeas%aH5LdFRxV!|M3V_frr84%f6^^?V3ej7Ozg8} zgmd%<4y!diWwxi>$=H4^f7s&g8K>RWQ)Im1b~gIM9E4x#bJIqO8|Ox&(sQiDglyx6 zsoY54&eM@kX?(^Hde2MgJ3*A_dp93WK$5YDask_Bu<>0`**@Lmu7O3$%lK0YP zXzFGx#fjEkI;fwc^;c45f9-_N04;OITceP2)XaQ%@QTJAlJt#+I+ZS0yvQn!q#t5uvexh+R!g zXm^!nN`8R{H<>}sO|Z=zH~|H1B-9XbjpQV5XavRw$orv_Mn7$Vi&)~7mu+UOw}O}g zUFf(|E&UKJCCd8DBVx|gYLQ4eZ{P%pM@58Eo-Gi{92kYGR4qN@%3(%2Y()PA)&(A= zSr0HR@euPeD0BC>zrXUXAxr5Vj#pBXO6g!%Nrxh*WsR)hIuAeAzx5NKCz1Rw^|`D! zVY9Et2a^NBTjb|F3V#mc}PbVI9D_sdzWp@kqbiP@ziDe?@H zO!UWOiKY|%yiVXXni?*93l?5Bilnbm(A5R(u*Nu}_#7e_eXE%oAKQqbiot$CB~vs! z4X2WnlkLXJ-$n7TBIc<$hr|82KKCBQ@B9c;kNe8*{3L0a8n9y4uv8uVn$IJzA_%_KLL zB?F|)J<|$lD~&51>1o}LVUQAi^o#vI4M~`OE1*`jo7mI6tJ6vC^qwAXjJ-b=W&~DV zCKQ^4H6QLkIu8KxcCA5whxB3v@{Rw1n5?x$@vfo@()_w>R+(zhUdP zw{lnmVTF5ytd@And3yLDxXNf;;UWjGVRY)hf38^DS;J=sxK z+_L!29yzmpV*mEQq80|FZYmrKT{^74E&!=j6=G_8t@?u(C4byV0#03M}k*^{TPGe{!vZRK5m*1z|rKw-H1 zP7Wv0^!9_{w=oM0xYS*x=FJn4yPpq_uJrlAM!~BrPPc;LpxD;dv-QoLmQ!}B`y-`x zn&UHQ{*lrm68C-68x!hzfeYu&V~tOM49Z+-P@~(0`ou+3%I9B-e90*DeAZ0Phq@Dk|_B*5eHsPTo_RL z5s^(nIw^*a-t2Iqw3Q8nPSOH__Smejutgl=sP6iIZpYIemyC8q$cj$FMQ;%)> zWU++i&avz@pUlMTP3LLC)4Jnl=C^XZqdac`<=fAycpk3~s2<5^_iOPtP4e(>USB1X z!X)hQ1uqgSoSqc0mZ%k<4pDAK9pBw~G-~xguzP=Su)3N=PX9)D{dJYz)>uEq7lEmC&!)Iw?BtMczbr}-P@2~H5amqyZXT7 zkZV8Mu{%|oW@U+~QN@vRWr?4ZTDXQed1NX3kz>UY?<;|-2XF8g876h`td)V@?vj#3 zsna1%FF)8NYo^VKQTK$w^BLyEJl`XC`S-!VfZM&7Ay+XFjls}BXPZdD}`iOO(*uxJDJkaA#&a_ zj^O0?M(vRf<>}5nBD?Dz>I`&CIGa7JccMrALQ9k5Mu7Hq4=c8=GW5U#Z2)gVV%10* zf`xd~T*pOBi6nPXR-FNyAlDM(qN_Sz(aa^flc|j+d2)o*O2(@CxJM5>Jz$Xds zzn1%vd%p09`5c-k$CQ18mHcq7qKPKAe|Br526_%HG!)q0dGU%?mW*MIL?d@`Hg#0k z7t>nkWc(H0SH8h8j$+m0o{hS9+KsN^nQVcR2EC3Zn7juMl~Y&+pFn@AABjY!&pLg` z)Rk(gja(Jt0h&AyX3}u#Gx--Bo6n?->nc+3955Vc4F6(bph%en+2Hp$kLGG37S|u; zMl`?E)0gVdv>55);k-vIuHtRfYhu+4-;or}m<+j}eB)m4qWO^<<-yW|E@5_)UG6=) zvt(NAW69IF&O?o`fU6QsiC{tD8zkix<>mTE$P%}dsj}J4W79Q>CKA^gWw@|&F?3Qx z21S0?Ny+QSD$)I>v9p0IH!hCD(iHxT9-itF?8J;+SJUKN+KevM^n zs#8=K7NN%)dzlVuNX-3Pds2kAS0f4?xNr^J~ zE|YrsKOF%-LdS$M)8W-g6=rzsZ3>gr;pCdjwE*$w;X9uClYsT;`XUPzP5yuRTW_D{ zUTghFOps;awDEi5rOSAc`}ctcT~IEOWN2U6Z>uMe5LSlj9PZCJfGqBXM+1|x!Z5?bo9Bwqk8r?42fJV zsgjGkoS{-jx0wd?=dW^WOsZVHyVIcm;_`CD*o_FH`q|6({`HXM2xtr0VK3IRcjDsu zag;d(957=c?*7L@gy&C}hQIkbh@fJ6eD}#jIlqSgwyv6S0c2VIdUuSx0oz2E}Ltz!{K7^RyZ@yaIjfGG4KASJDw z_9^XfO3Vt8gUsy&d3$L%1z0E&Oey`IcydeMd$c^LgBouNITS zeCf~Z169vBX8ltyj)okbK+_q2NzR7+fl`Y){3t7}d=QSP@2E?=kg4zVeBxOD=R?BXpIx7ML?4doP2aZ?Fng18?O+5v&kx$e zO|aKqqHKkgXRhN0ESxseqX1q;QU9TXevMNkFj78pii>WcOQF$4>#FhafpKnvn%rzP z1|_4#@^jOd_7xFzCfP&v=5?$>6zG95RtN=LDGXficF*pHZeAn+X8_{cuD_>@w{XD{ z^xwfbOvG%EJl$6RB(K{HR8c_P57F~8Q+JOf*-ea;J?ec?m#PItJ94p~CB&5-LNn-a#eh+QibE8_~p%_`jS{z3dXdsFlJliuqD za;ar(2HQIzYnN^Pz^C*Vc9baXN-80$CymRP&61UpEmsyi=Q@H^_pYU+WLL^>RYV>= zh;EHg9WyR8svc8PU42!4yopn>{4u(b!fl~#8$X!9ZK3+8WQWN~zT(S6_3#tfoE~z? zW3HM765%;b9FZaiekeGnr{~B8CG%o}-Yi_!0`%$6?m%^oFfva+^xed{#0-GLBLjoN zQD`)%_42E;D(SbxoWLcvWdQMS;S~(ehTwE`RJ7^~UN2LmrQk*EV>}>ovV*$vnNeEP z-W0dZ2mQd^^sC?1dT>G{yY#N>x&e{(ZslY7V!qUw-6O@n>y8>Xe4kp1 z$6aCzSGGcP#+dCYY?Zy{?hu%u0ES`-CKt z{(>MqwV@oAdJA`)YGDQC%fYg8&GmYrZCeX!@hsL1_>VzO#sx-T8e+R=sSW~i39`^4 zATcjzmL}ZIhOZ+YfaaD{bp1T-GP)CLYkABMwR5He=y1=q!~)M;^Gxs`Nrl%~{bG0l z%*CfOp!qzUYV%KsL2Vl~etIRNpcyL8<&-!jA&k<$-PoBq&AT>h+-Si?w%sB?M{O&$ zQT;MDc#ZJ=2m&^w6t$H09@P3~B^iS~_fqD`1qYt(2|0PZF;-tKwjK+bsVfVrYce_> z{fiNtI9rngdkeQtPUVp7E(_G0j05o3e!2Q&{7oyQuITGg?SI#e)nH~tbUKet)EQ4n2DgT!*Ne#>|ati~79_;SYcWpLpAZUHAS zUub()|Bmr`%VCoI$imqq+P|(40b1QD@?G4Z-+ElG%xyqF6{d)F4LLY~#!f8Gxmx~1 z7pA_&ufZ}Yjf-FVbPyk5hH%l+de6hME%$pymm#r{$u06#4}I9gYL09pKD{j`KP zeUUunrXRAEgk`}Vt)@e8 z1TA5);}ZT94GeGbxz1N4pv{m@fPDZRE9w&S(`SVLSY^BPk|-MB2GG zS<2eyu;Lu!j`gBz+d|8y`0Z^(af554sI$tIQ;~qN;8|=}utty6H-|+1H=m2##=bnrGS< zZ&F#tKPA?F=BO38I*~#CszA$ig(q^2TkARPJW&~u9!|vEQ z1Q2yzJ^IvFn^P_<;+KOyf2j?Y9mjfP^I%dGA6Hpl3#>5=|K!}nkG;ZrVQisa2RP#} z8#(;d(yXC;;hawAlbWrgMPu$0L6gsjjU*miOk6~%^S(9{sGs_8hdN$YTSPBuo&Rtp zjokj`;<;dh*b7mG1gV@r|CU#A9;bAyae_9*tYiN6zvi((XoXIp33#NTAR8y7lKKgwV~=2Cbs) z?=WgAuO=_09kx~k9Y>`W$7G*!!K7}vwST8W&fiU+I=bTmq#47;zkBPqfV9Wo-Frso ze?V)W!-j)5#XLBfj$p5e@r;-dZc`DM0K_hC{>U*~~-8&8~eC$JwPg8C;ChQ*q zBIwITzsv1^F~bXDKgox_Vv^;j5XHki7m{i(FG|qk6F6ya7XT8|TNb8pKfcexy!Vj~ zY{R;dT49KbD^@HznE0)*)KKWz^ zYOr;|B`KZhm+NIu>CRu;FZw=&4lf~wEQz~F8EGKDL4I#n2bJp9snAN(`Q^S7&Y?wq zhc{{A-Svsz>HH(krkqSkBxl+ETq6T+;^&yXQFp{oSV8xpNLPoMZ>qRWu?z(7pi&1+ zCq3JSn!qJQ`+k8vMD?F0y{HG)kuruDY=UE4)sE1Cu-@$s`e5&)HgtH+OIgv)XBEH} zw=StCyCXL}?&$Wyf{QR=d>q>I3T$}O;@&K}{9#tnh7clP2(j>rsuBh5cbPWovi94c zW@w-2_Ac1iwsP7OWypeF`fV(UGmE&FiR#_2!*~ngzo#V)IXUr zAxn_z>ILsQvqpy^2g|@8;>?Wv$ry+o;EHWSVjz-l+eEPry7Z$&Ew zrQ+!xB5?sTk+uQNLI?Ga6V%V@iAFAsH;@i?y{L5;VH(NWy|)XE;=ndWgm{q!g9(T7 zxVp|z9Sl~i<2Yp_=+p{)zN zFkF#ykJ*oHAIJK=qmAI6ZfZZjM@an~=Z}hN_|Ol1X`-u1dCeeX2}{FR+?SSk3a41% zC_`GC!^-On1;mmW-E)!7C9Pvo^^LM`1Eb5ho%ofnWj_G}TS(hhnd#e9Qx{R(l`s6g z#hVh@5X%uE{)dzzU)Dl2(`-QFt}pc`!6Th~ZGS^cH_Ics>IvWch&qq^(O z1Y&W(asHXUh$}c&QV@fYHGiN9qnx*l$zv!aI@}{BsbHHQRs>nN##FVw2X+1Y39Qqr zDw2Lk$qL(1z8%vZ1Y|YAwV(157;LOtj2|u0RJkrR5BW*d`%xs}R~kF%!&v4Q!@sr{ zqWPm>yV539<@D>2*J;`(t;JHMEq|Z4#>=&Gsm>X-Rut%qB^b* zIYO)-eO%ko%PBB0U1hj3zEFn?7e?M0FZFFC7noQ$=*w{Ft|nP&#tvIbsi<(zp9@C? z3jU5x2}M0dmR!B2X?b!_BK79BSh-T2A#K&AbfuJrHNJSQe>9xM3w~>tSnZlOuj&jQ z^FCFJKA&+T{TTW0lYnd0@f%2t7W1Q_*0DVw{69uOyid71X4AyCv2z-iylY5(QK{Tv z#xa_detrc3S@+03U)5Z&0qt7e3U;)$r#xoJF5u^S68<^3Gj!guG7mjfx;V*dr=TF_ zaU&u14bFehb7=(FJ<&o0JSD^tissE_^UEblPhAABu!ykBN1A(~geKj*J^ThOH>=1N z;*3Te+t8`iXE1628d;5LhoftQ;S?v@UFmT_gxYLhYQw+dJ+5Vd(&Wqn223ux(aOHgEp!^-b|y+c<%xwtm9^jOLV4m98&d8EMB zbB9Ko)O|D93$P}q(#2nta%On*qej^y2cr~iITw|ckewg3& zwxyRCyadb-^k%0LhwO7yNK6aR&Up{$1*S8JeXqWiejmR))Ax5tpybF{^I^yZY?OhaAY)6@r{mesOfM_X7hVz^2j!8cDR zpB(fhtgd+-*Z5d&AEFHX>tSVAKXYqlHsRF}MVL_*2!484%W5;QBLJX4Ydm8{ z(pWV(@GWGYXY(^wNvOpkg_pc$5iPi6t`()>HQ#WJ21!98GA&S1Q z04o+qiltN;kPi0R^*fw`_gMS7+rd7+bL2a=HMUHhzLh1X6Lt9sxOT0DI_P>UT}rn? z2V2Cj9x+U!=^6eq&;P9y^cOT4!n@3rYx!18+6fe|Sby%)P< zDXJR2S5D-lv9mv$Fjq;DlU?zN09;4nFXz3X{u6&V!-?+JEE(Z350EnfyE7Zc1K|pB zfmM(ps7a0|X?RcDh$JF%3zU;=)Q$TkPA_-Q3DIzCQL1Ykd^N!_`ByBtdmdJ0+m& zlxos}@=1Be>FnNY*KZ4*-i6uAyQPvpxjfiF#mJv2JcBzx>;;pg!cU_)5B(9&LHW7o z4{6*AD(M(_+#;?P3timvCvS#iO%Iaw#&|GPqph^%#+ux8Wf7bfXG4}V+RCMz7L%X0 zrVl?yRSgMir3551XA#f)f{~@KfcbbLvp^)r=T4ORdU)+X&D%@9Kp7s_j;QDa=D3f0 zJB0lA<8?4S;bkF|ehHATBptcznzP0vot68RdUH--T-X2E;nGZmoW9Wt61(_tEq$?j z^XX2B;7S~|)^D$oSnXp^&_9JDDU(Yc$ z8nO@jFB35Vax*6te!0LuG)OKr;%->X)YEXU@)pz#p)ydcs~dyTRfM}m*mG0S4RpJ? zC%m0BxtTd=v^U9G;T2Q!xL#%i?UumMwGs%Is6Y#TmzJ6&C|wNTHXViYF>_`!2aXbN zYYpsZ_PYB=wJk8{u7#yl4b@-22BlJrv`YLu{96kZIK2&Ok6@6~_r&-796?+^`s@@Z@HL{DLy7X>>#XD$uhC@#zK z4*M1_hhl=&mp}Nz`bNjf3(#*6{W+o!_ySGi));fZJED}s;&H-A^;1dObwWaxOgl)c zwbysFg5eA%)!A|9aR>2tfsN`M1pm7rS#A!5e5Zz*&b_$}eV8QR3!}6^UH2!Jfn~&; zy=$xi-U`0#qf{4yHc(8VD~zC`d79#$@Cl^hAzDz5S!UF@l;gmliuo%P->k(e5Ga|| zslIJAr}uyal&WDL2?25wS!vRpQnKxIk+{@)ETezT@nXaem#b*T2itL<+fF*-bmBud9(hD_CXTTIL zjk0si7nKzgPROKS`B}JinB~3bE>iI@td*~OYdjQSqAYfWKoq)((j$O+^@H{a-q$A{ zEQRsEHazI+ z>xEXL^Qwes=aQS~>4?5;XY=iQaD?Jp9Pi#s{BN@5**?PbeNb{qS|Op%=;AzdEtVwA zI@xrd>whMEan^LcaIs}_G2Rq@vEqL*bv}M^oCZks+p_0-Y3Kb-w*xZ2ORpBrKk#|W z2(A|4TXnNOeXnbnjC}z4nf=!r9JDF;P^6mNm2BE5%Cns*V|k^h;Lc|b8e#Q=0GXiZ zfaLceHy&Sx;F+8>P_Vz~L*TAwK$Ag;2S2xVyT9!u9f|oVbgKlA?*vSVxt3VYPro)5 zXVKYL32FAYDNrEleGI+heN$l3xbIlc!S%gvG?y9{{0=BAIyC@ULKZVXVn zXUVltu0uAY*E%<^-l9<>eZH*a*EkM8MP}g8N(mS*F;?%JJ)p}U-Oirn2G>AF_L-+o zwRiYI@-dX+{)0Z${eZA>#-aBYbG0&fM;A~R{H$aDLsuRVx-pu<&?X+{?lED{%R_M@W(QvzF7fADIBg z7jUZ9T)j11m4v3T78w{fZTRFTIte_U018%3={!1Ib*� z(0|Umx5PC~>%2)FEh?%a#KMruJLvTV=v;f7H+flcuo#(&r%e1#w5dF;6zl0SP1fUL zq<{xvKFWBOo$<8s52sJx{8U)FoV2r4t zqNpDdW?+sAWdHW~r9Q?(2Yh+@K%gz5iMGW03pe_~lP28oOC9_4BuLf8aaG#EMQIO> z>)HNm17_sNISd;xo`<(y{*z^l{-@e%7V9ssI#S;nb?SF> zMQ*;XX|LX{RI`yXocOzTEar#WaLp@Jr2bRZ_Z$}=cH{1Os}K2kXsLdDV2-af`%>=* zAb(lb0VGyqX2071F`s@`%d?&BKexRrLt%CzvX*1+e@G6&PPCD@c#~b(LhUiTt@=fO zgOe@JpsC`K5toF8-upd2?D|9x>$~4yp|l)dWd>?}L?a&>{A2JJ zN3Xnbp+RSTZ98a*tLZB;okZTEDWw{7nMlEgtG0fuDYE=T;k#juCwwkRV3Bx~ik_C$B5~xiSjMofa zFk{M(W8INPaXEiJpSuqZ^yBK2ZC?rW(-{|$TEBg)zra5wpAG760j_5errDY09&7n7 zkzzl;;9);f{sd|2PuxT}Il=X^!{y_FIG{Aq>m=CDgIqsWKi}-(VI)zf`vAegj3RWVLN7ohIKRhL(NKUXfj<7r*S z4a>I*ITaZBNV{0%mABGlg?-y9i)TzQnQ!Gk3*4xvxK}?knoZQ&lpa|yI{rF5Vijxs;52@dQo=a6T59QOvJ9=GHI=GR-@pN1?70YkxAk2tTywWUpU5U zTO}_d^s{Av7u;!m3*H435B*u^KdT0=d+IXc|7&~%(vi==lP_6XZHO$#$bd&jF6#(rHB{g$9?Rv`I&pz29x1tS+DM3o*bZL&Mn&fIRV$gnxzbg>O^tdS3$n`HzrK9xP z2K@6iYrU7_Jj|{h{Hv@>4Kvy1&^}R2##b7hzN%>dcwh69Z^q3oE35@swvqazTT_RR zU6wkVQ?$cMC=m&>s%P=^EJ#!Ge4Esd2-Kw(mREZC&XLFcbO6^vCFT_}8!RR)PQ0NU zv+M!=W$8%cTvEoZN~bVE%)`IuDlY3P*i}=_wW8 zagw^k$=nAoU;)!Tb^l&)+jajq8PI+n@J*L$>Lm_%!h(NpaqiRS!>Cp0@f3{+3O}V3 z&r?593a24q9CGK6d?>Ry1oBgiPSD`%F*M=%*dom1-GxV+7~6cYojI4^y&M|*mvbtJ z5j{&*_i;v1BM%xN4w4{&RpJ(!$of|maX(Du@8!$Any}6s94!MERH|D%NLq{nHiQ$V z;r80vv^fjceZ?gO;(hPaD($G1ENr(wOd>!_I=VJZSKlr~15s|pw|7F5c9XCk3cW{j zApFBu@OJ?nCDoM=YOy6Z!~z{7MBFvEHk}RUK5FzTS+YY3OYrY#|q;ZtrA#J2sog@t(poUq&_i2 ztgmS^`Am$ z9iOc2K~&v&Aq zH!OZlX6VwQch+clp^*Zy$o3=%%(d<24~0$y=2Igul5%_r&0*mibSXl)P<({sk zHt*?*su*+m;L@J@A=_T_Pi21eD8a28Vfl@tT zJbp@A&y#Z*Ddm1(K6B4*p%&fsh2K(*#m(4yHB{4P-A2Knm+#I5dr)g(unR9IvShe2 zZ=~@#D*3iCa-IIsjyD61?MZ3+30x59Ngs|mZemTnmMvYE3ZFL5z)qPjWH z4GNL}Q9(5oOa2nj;4>@M;5C-<^-h_#wL<)R(5hVAt@08k?2s6cvzw;`%TV#yN^-|^ z3OI2Q?nBnf7e7os0lqJb2cME=td8mmWF;+ou|V8rlR=s?!ULVuj2PJCJeg>C!~x`j zsQc=jbPpkI)R-81F~pczlHpbg8_fKGP*@Y$VEx3m?dW7JVj@c3bacuWDdT4kjI`BE zD+32cu9?Zc7Yn}ow()MC5iP`5ohO%-!g~q`9sEEkV?bkdy?Li?rpsxR$6jHWPOG}R zkrhB0G5yH_UCIg_0(evPw4YEAWu!+zOd?c#wNX|iy;QyxYOewn*4d9X|>!^&G9`%!bfNn)AIj$@w!o^U;I3($D%$?r(Sxsjxm?mOTy= zz-2G@e(muyVY?|~n@|Emc=?By1LwXOJ$w`_(>P%Ksjwi=(O*319@dK?EWOZBR)wUm ztXh9lEeSB=B>QLW5H>UD$BtV$06=tPTAb>Jkcz+2WW0jr$DqAM zy!Hxc`AgdSg=EKXDmz4$8PYCix=qiRXJ4JuwC~0z1%ApCf%uKzptGKHaS2pzdp-#YI&M<7$W>NOr={6LcQ)SBvs9@-LZ~fcx7PCj@t2Kvl0PKizleO4&cj zsrK)2)GOdvCf>2#u6^nr&f`?C+LN*%vC`t9!EPukb6JB|xc>#+e(m=07Ih~~^c3G9 zd(h+GdJ|s3%C{og==9z>Sn|U$$_q+4CEmnP?5+F#{cxi~hY{KMi~b%v6aa`L@i z-d&b|vlUzGaIyd0#6phFKGB!?koue5eE{5_CcD|Qj}o+gaJ9{-QS@%w1J0B?{@?SO z#HfXXA5M2Y)lx@X|2sJtG@6v=mJN7r>Sf$kBiezE%ejwW2}WcK)w{oM63r1$DR`19 zG64)%pK81St-Yhfb8VrUZ6W23eaARH36~~oovizNw)aU113_yw;Is{qvGoRS-0!Un zZ2=QQw88#UpB)}s-oj7mAQXi9--e>Chz`8mKsVA`I3qx#ZC|xfGIsDdt=cj*AARz< zjy zFZTg@>(lya*#m9x!DMTk!cy}{-BmyR=sn!-lHlc)s79yShRhH7Ru2?9%Ca^(izS<0 zUIIv(_}DvpTfeT@crycGKvmuLf_A*ZSkY23@#W;HDzVhd6QHud&c>4?%Lf0Z=552N zu_u40{(=e)T$T7+z!UH^An(uJ>D4M>lfp%iPNINO@H`9WR}$A|K?LT_ulg;i(&|R( ziA3);t#O4qDMe{@NRif<-DuNMm*2~jCH8MLjiV>@pB&S+Z>U6{12jpqiOB5a*)Uz( zQB{6_+I^M@y$WTE#W|9n9FYgWK=q~7LWoW}E-_|b&+c6n&J);3zoFTU+PEOjuKVT1 z<9gHh4B_`T;-mPTEC$ziT=ohFn z0t1I$4Pcluh-rO&VDD$8pE|~#-=6IR3G~9gcd{Dq>P`A};av2t&5^PeCaId4Cdemd zcj4Vrmi*GR!oL&V&}?Ab5l?~>DNZt6=asoAC07YT7|D0KP&9OXodz!F3Spyw%k8#u z<~#0>EU5IE))&y`&>+JHWA^o3ab+U?;a3wR+c`6=TAxIcT>Vz{A|#ko$t;pMiKBIC z3|Y=bimqTKu3d=gK;88kvWR%im1CJ7rB7)xw{m^&SS03PDX8u&Ur9d{mP|+jg6@c9 z-aSWM<5keg9UvafcO*8!vySK_p!|CNzndP^e%go$Yw)mMoXgJKT4>nmph7sjQBylJ zT6-dh@uvhIE{MZjH~XiM37%m?Q#&e_EL8YLo3(FtJ$+R^k1nca3KUEJAuzw54rD^1 zQP=IblalQ6J$QZSixn)_&?kQ02`Xs7U{M;K<6vb4D0*?KKM-#f!s`smh_8Vx1pi#2 z6K9dGYCNsLnx#PXUy}|Ke4VGg%q*aWUjgnK8pOx>#Yg%QwzN$I~j@Xa) zkjq5twlDqViSs<6vV) z#mRQXDycV}{5$VEbq+qnB^*d(t;POF59jkb?^sIxMxR#G(544+Pi&sxpE_T13*cm1 z2(Kcn1lB|~o%Pq%9hX27Sg=OEdP8p)cARftrpjhwVQKhWMd?0=RS}#r=12zz#+3Ly ze)q{7q|*$^?42yVmT!1OEGZQa)GqRQ>;?Jj<>M2(VZ%kkfGYAxoC4ZUvb5oL82$|KsSaBDFE4Lj**n6r_}%bV)ZT9RoyK zIt1yI8a){?xSxExi z1wj@(nVB!2l9)K=2#Z>P(0m|^WvYC*m+0D-`thjI`%+Fqc^#C5r2k!*TT0XCC$OS9 zCVlul)u>^WjoGPOCzy)TP$1M7Wva|s$#c+xjcH%~sMbcS3)3u~ABMR$pxD!L@+Z>vy2chTqcUGG`(oEM;G)4%r zGNVxC6g^1yWgMF=S3Jvk9`2YA)b4JqRAp)pLAf~1Z{ij|X$tx72%|JL>GVym1!xKt zlp%YA3(waf3LbPqOG$A#G|II1KTpX&^UyI=AkYci{sLeoQ__zx{2m>KZALl4)eMi^ ziu$?iV#hCDFKR9BqzOhb!k}-q!X|Ekg zI#s~WGy+Thx|FJvQ?@koYWa3zL?}gS`J^_FOF^niwWi0Xf?kL3uHsT!ocn15ljGgy zeuV>rYiLqqkJ#u~!!#19`GIT)+W-=k&@Vynk9d*QTDFgYsvpv2=7Mla3c!4B&KKV- z;x&SjlnE2&+&W(KkYn0}wwPCaBVWTI(>`)OcHnYxH|731#Uhd#+F1U)a zDnDb@qFRy4vr8{D%29%oInKZ2bE*~Z9TF1YSVi%aI(r9jg%lCtN_#U0zY~LY^qn2u zk%=ONSpEF`@#T&RZdOpz;h#O`tNoUjX1fwonvQ8O*q{VX?DT>(HaM7sng8_qyA$Pb zjXJbR%d_yRE*jI2o?c7T~Z!e8z6 zuTI9#V}%=Cy^`~-soI#fS@y-QRP6+lI-xY{VIEk>@3PDxqtS&&r|>0Q72iegR!(Qa z3T{Sf(YSp|9^8QCI{1IjD}JaisDf;s@-Mh9#V9h?Q+6K#7DvPrLg$46l!;)}+f%lO zT+lFjvqn&WMoP(fy<|4R55FRKON~c&mBe?GmPKx3uX+|XCbrP8bT`_M{bQfF;e((XX#x# z33ohr1T!UTgSxsNl`)-O+fHYW;4Z~0@Rq{Pp3~yW(hcO5Off=vba_22XyeCz9^$`J zs)hS3Kb<9N86?7bjDl&_36Nc*xQ(GOoTs7yZx+TJxisPuoM;7E8kxU*_D#xzNwoCD zFV6$H#Hv6@N|EYHD9Qhss4HQdE`VhWnEYd@;{O(I;bthIs~x8g84j6NSPRh~-nRX; zapA&OyXdU;Zh7_L!K~sQF#bvu1yzDO1KkARQml#kmY|ETb}@Rcxpg9aipndtX%8wX z>*LKJl;1qpMiM}ugUj;WedyF(C;gred>%N_!D;_u(x@QPg`!Oo$FNHeq zX$iKi?Ok^6e|b3XN(oJ0TnoYUFn`_KB(P_QimZ^AHg40tm|k@2rPQfE;}0t7BsGYz zzEmCFY)t}P>zpz8LH65lmSQX z>t!M6?S5*&y{s3keuW-5(GiROZWA104UWS<1!c&@yZ=g-KyR`)UzZmb(Mw0Xsr~9( z(#ZbKA3k~2r({CMT}~oK&tSRj0`&48+n%LgM+(ZvzR_E6zMMCl;Y^K{C2c^eJkp8l zre$gEmS;}!u4PVud%kGA^u7Dm8(Q|I4(k<<@%HDG>_#}Lf?L_qfAyiOkF0Ccrm`O- zALxrZForfp$wMHKf*b28f)5`c*k-d>~fk_GbC6Y zdyd#I{F@`1ATFepD(v|1%Y5sOw0eAi*!?_xb99u0ysW(5vA&u{%AoI#0&)zZfuQ`1Lk=Djn~cFH{NHj%_j0*2TisCgKqo* z{7|uA;IQW;{a!Y`4~HNj#5>UfVuf2`KrlD8HMG$25ML~C^Qa~3N}QayhRXS=##1dM~f(T2*M-&Tc}I9c=w4KlfUle zXqz4bV7%BZRcsTI4kH9s-!qO7o=D(#e}xlDySgAqeUCkm!Ar_tT+3JUjQcL}lOnBm zsVL&w=^J9TAXYrevm&mKrSu;b(BTDhH-mOUcSZbNuFk6=DOPK=% zEYsMQW+R3RXeL!8vNz??0mqa?Z_2$rPM5#Wyu1g;B9|Li?(w7tG{KgYzKUnAnblOC zVm|U9bsTF1V>6b?v`q&h?H77VSKTXp#rR_d^yMje)qR$gDl)~RT}OX-)#m#OmElUN?2$e7A55=3<_rMB#{$1UOnuN-5;rB? ze`qE#LC!MuES!}e`QiCpLC#PvLl?7HoOVHZ$O&YZ)c8k43)49L4n_Ct`*;nm!>~x^ zAAB{sRIOh@>XT+F)nq)T8I_3B5q;@Cn4dWEL*Mw#W@M}?->D)XcA zsf4B@%j<-(Cl^V0j(=}aVKvc`%c4F+;ir!AveK=I(l{pDdiA~=6B6Lgta}E6BeWYh z_jOoEr;1x|W-$Gm+aSdP9x2p&)nk)8>%1|K7WGu}X|-Pp zr}A$L!s45C-dPx})2=liN|fSU#%nt3es+U-=BXxr_rE(;@nPu_UT!FSoWBT@X8e7- z%BU|IbMwsQzak{Lb^tfKNkdP9OqWW53s$tz@$6k&-)~zupB(Jdy}N(m2H<(8LG6Fb zxTA5RX6IM00CpfNbl8bf@=J7Used1_@HC+PFyAZVU<0qN$bozI!R>@^Xz|&HfWd4G zgNEN*zY@o$KDO@Jhi_6^peAcCb#cg|Sy6#7>xqF+LcPPl1W~Ku$e--WAE8pap`rTX zE76%2sX;uL2yp4B^+#xz!T)e1iq@I*2aLhcD__L{&$fLaL?|CTj(iZ>G6EI{;+(Df z9|*tg&Jvp93a3kV0ajK1l*MD&7M`_MxiO}wwDJZPP>y%}#jeCVZ2kA6$S+|VUK+wD zj%8-NPJmmE;Pu`lcN6ls@);PsVX*@aAIg7>$v;mhgbXpi_TrA>u*<4 z8)k#d@mrIN&%D$kkQVYg!AO1>7yzjf+Ux!Sg{I)5E_O}+Ji_Majj(eI4AYskdhq4K zK7MOxg7h4gPCtpeeB@Z^$dAd_X11P^=gv(HoE4lq0x2y47kgt?jTIg|hwJf9@aP;XRSi-K2*8 zlHoci7DSN!U8uIfG8tn<#-1;niw<-}3hJu@t%2;l!}95Ks{8yGans3%cL~RQAt(Gc zN}O&9wQ+0rj>`F__Y8Of{|v0whdE&dBHw^6y8g+n>g?!<9)N-s+i(g+G0f@)a+vIk zSM!P6u19^pNU@oym$w%xuKPd@mPZqAg}VNp><4q)`|%Cvq-T3ek2fU&6rt(RY6X9# z2)RC6A(vFJ@#mCr2S2KFJ~w3@TVYH=kE@&h;qZLh@X!;R9LhFXZittz_Y zQ5q3aA!$mfqkr3)!7k%np( zH?XO_--@)^EkBK_aN-U5hj76#tcJI>PdTpkaG?FN=2yBoYV_mxuPZq@u1I;(MKup3 zNv&)Aa%mb!(#Ab;)9g)Av9H&ha2fY_iTS?5qU5C57rJTtQ^KG%cqD*$->!O8YsvJ8 z%`zO^F+6I>;*ZUE(ww?t&QwotiZ+h(-whNjvD!^ZW z+`C3r??&tl0g7}{8T6{%Qc<4cKbv(8}RO9^$} zkkf#Bod%s@r5&;D;yUCDiT#IGo!5X)@KaH#%y4!P1C@LS@ulW|IX8WMc0VgoYHI|X zm$lDu_DJms*-!Hzw>(aM9nzNOwB032L=)aqt5_Cc9PYN+qtf!F)p0n{AqXd zDHl&xYJ%ZvuO`7LwOcYvrgZbwJL9)0Glr5$cISU}4NdGsKMq<-?>vpBg&i#1zqFw# zt+=bRWOY0tCge7dCMLOX2WW9>KF09q7@H`4wd&65I{RMpQO&vAX0w(zo+iY>F6%JR z5XhX$jU!lY@N@DNq_yP?^K1t5^c{n7@HEO%ldJ6pCOyg*ro;SG>Gm2@i}FAgm+s<` zDj_+(s2_3i^jBc?Q89?|&6dfcvs;Pka-2%fYr=aUXl8EowI&VA=DWj_2;HaOh+O;% zC3}jJ`5H!gwbB&PcnQS;=F2o6G80e&h*9UY^v-a34;J>rSI?w8r)ft7Ws)|u_nxIb`h%>^9Y8mE{{6PPJ(U5u5=;c{@Rr6G zsXtYZ-Y{YAvRrD-$z6pUo-(iPS)T9c3ptz5}a^qp}ev@ z0QSYe;z^!=U2&Z`OQSaEGCO)-E4$nFxVD5wP(QQwwFeM)}8j<^V#3Mlq@=mo>1*0gn| z)p?_CeoB4Ak`?q9<)54vf+p}UMl9hN{1 zE|A+ct9EDv-&9=^;Z?WtpTA%n5U$mR9&w#Z1(YSsR)rKA6;a{pUj4nptb%qs33Cet zZ_s&ieA<6U=aC_ZLFPVeDOBn_V&}0A?S6JJ zgHHD(WFvfkcFypvS0>k~XI}K7?2@11SdQrLd}X!Lo!n1)ubZz})9q)!((G#W2H!6M zg_?#lH{BJ+d%CwV?-rk+ZZ-(zFj9cU-KnfsT=RZwDix-4aVdwR_^DMMu!8pb%l(D_ zRIc7u_{A2FAKFzc&VOV}YfQG#_Px|ulM@=Ri*|j_^V|MIWM@$gw9Myi($SwgJ$_x| zE!|GB0LxSw=Z(>FzE`pur?z==uw5d>LCL_Az&s*++cPMgQbUSYY@_=3z06`fbcQ^|~A3*`}ZB(SKsl$hR?V zC0mSHvO1BQL)BhZ&gclH>@$x4G(LcSZ=T0FJeu;8011XD$W^~!PvJ?H04L})GP%Vu zjQSF8I~fHdi}QLOZgzrPpr-RP9#G_UbO<}5%7T$#go&}Uk=qGPHKO(B17HcXwrkQa zkvvV(nMgIO?<}cIeROs{Q7Bwx-Tr5fYQJbuyxCF+++$VkXm)yOQwK?>)s1kB?#2x+f%H+H+8hG6kM`VFI>^n5zC6+h$M zE-r>r#_PlfLjlZr2KB{;Id*Ui%&tECUA42sed?KRm{$z|!%L`@bSV{VcMNkq+>AC) z1p1^x5>u)Px-A!@p5oxP9Sr5Q0^oKE3-1OHnn z;gmf+u*kqIVMC@TQ0$eO$6?}2=iA9Lt=_RM9!dLqbC4qkGXZbJplS(yvez~8y}VTo zCR`&M_~stlV=NI@rlmTz1|B_Oa_-98Ox*bfgaku=4(IaX!!6ghVzSiWRH?No3%yTW zOkp&n!WB7czA~;2Y)Ixo9-HmSkEaLi%<8$V3;qfi+)+_-;Qqy+cx^gF)1u5!y!{jO zLkqtEe)-!hyu$O~Jb5jKaE%hR<`n)3$wTg1!`STH{b0GJf@1z8e)~M_RCbDHAu%VL zuQGUu9K5X6^Dn(-tln%lM|cv!Q&aR6Px8g9Os2Mq0wtj1A}4^hR>H>XSQrdSKGCCRr| zYEN2mTll#rcXrB`i~A19x+XuaUC?0TF8m6}vLg4%1YWmtfEI)aNNvh{YCL+lRV5%U zRXp>;^zWg5#(=EhVbgw$uh_75h>?Zp_h5T^PPU zBI<1dPH#%0`rqbLz5-XxI1z$66=tJ;gTngnq0(A6xU73_ip6>BI%lKZ4juJ36Q^Cq zeeh`)cR279GUpM*?Q1vyUY?RyklUZ2Uuec)-Y#_xSeXfBq?&kB>TQDCf*m{W}merzoM+ zi;MZ3a5%))4tXZrci;iVCdDnk*e+FDKl)t(7r}Pvu^&>I2Umum9@q479o^G5_8+~G z6(^fqlW;u~C<+Sk8W@nHiSibJE6>;*-=#dBTz9b2OK(FwU1;_! zP&T%v8zM~f)Qx?z(Ql|9$fHv+cGf18d$r<+0tW0Oh);}*i*?hxTP9jeiJ(hfs?4?S zaw}`X8N50(rE3G#A}dcRxuB6maUi?!gh_;npR{4)u6u$Ta+HB4J`4R*InIrnx5FMK zNGd}W5bMWL)fUJ1ZKkW3%5YOdxyL7Ajn#6i3)(G-2v~Y<^NG@bs}_pZvO``wxRpdm z7*A+ofao&Phm4Th!QBt&+Ds$;Wv*KKKJ?i#Vw5T`3 ztY#)B@+(0#IYOP2(9L<78+5TgVkw0>1u&l#rcAD6{%OdOd(C4v%*}fx?*0b*%MRji znPG)L?vkj6f*3!kMe?QG=q(P&rDx5xzeJxP4BHrcsruA;HMJEDcYaTk~?+XPnOnlwaTJhRqn6e~L8nwPo@!A@l0v-*$A4&oLgx%3Z zA*H%S;8l42kRv4GKWnnQcTpuXA%j3Rc$Vlh1**}XqQ_;xlroId&U46R%3{ke_twXk zF3%lp7mrWe8xmAQXJ72#_tzl;Lg~AQR_hBLZ-0nGa@CvFfsLSS;oeCX~8CDcX5r+Y5E2ig79xs(z{AazrJzfOc$$7Uz{~%QhoCD zgJ$$NmsCU~LQp=3Z-Ro->ir{)^<0zMhrf79)#|TeeLg2hGCQsq*VIfxPT%CefZ-ZD zDtq#wj#rg~57Igl6GOj5^BUZUeCXJkmsJqBs4#pOtl$@BdPvk$>HEl)JCdF1^-ht5}XLo{rbH*S{6f1cHhqOH&ys!^kW0*lOq>y*UN9= z^lD-sLAbZtqj#MeiAI1&>fhiqE&zO5LT8N14e@#qwT|f@&A<+(_v4JQ`CoVNH2c+G zXOCV93H3+;;MD`1nauIG@RT++%q-S(YJt_>9dmgI6z7IKT>0zu+Y~K6PMLb#jTBQI^4NwuIH&F(o?|X7EgeEF~o2iAu4#W>ahYo zx4ewHmPzP zno>E9s@e0TmF?^aPo1~c{uwSiZ3M!tL!OYl8v{I664q6fz~T2|kHE2Q=OFnVTV1ml zaV>MoygeYPC(*8xrt}D*_qn&(Q?e!pXyWlAr*>LI1HHHAzi(~TztlWCF1jUKdun%d zVekz>7pDSURkFx08w{}Cv+{SKR3;e6`!cLZF}eSd_fC{q_=w_LSZ8g;KmJNBqxjSV z_x{YShhgIPz6qq>H`&LZ4prgD{H5noN675soA(b~sQt;MIH!0vB|GLuo+(_7tC0|= zJxziFHh*`7hASH-iA2)M5Xw|fzb>Y zNp&|oL8KTib}VK7FI^dQpa}x(2S%Sy%FXu|9B>zVLeRT*np(f^Q@u$hsTv#c577KI z6S{N3@V5cDQs1ORNmDjhIn_R$^iscJ8o#JlL?54Ad}cAZi#Gj>x=bx1?f-l{gs+#- zxs|$GwkMYYdyo-moW)=`<3TIHaCftzZj;Z5>@?=L#5joC zc$8W#30Dth2adS3$EjK?H<}X1hQ!t#bu}^psn-*}@>!)$AP{)cL%NlI#J+^j6K{v2 zPpKPbTBK2GQ4ZI^FR0*buvQCITJucv${HM`qPA&F;!l1dYW-D5{)zvFS#xm;Rc*p} z%CR&O>m;}`R(6h1g(^iW2)$=k!Yc?#L6wvOF>&G#N!;TWARXT$kG}vOT9COR#<%2- zzZPdgjGtq4lh_2c0HMX1@7ZV#yJttp&VnyAgx#n$(Ui}J<$Wo;SeDY5V3?- z*RgRd?`i+9=>ZB(YnM(Bk6HG&Oo?3myn;*J5W68 z8S)f;I_kRvw;yFk^8m!5qr*qQ8EmMg-erJ5(SBv~e_$POwYeElMisPAfN2Pr_t#v- zUQ}Pl*ZA(lQS=V=O?ASp|0H}VERCz{ zy54)o>0AEZG2fq%DahI%Y0A1{E8%7}V{Ok9A!?+m`8IK=KRD z+Ulc&+d!$i^Il2+&jh38bUJ)T$E*-lc&*GeK^5*jzemvIjXUGpmNfnZejk4Q1S^!MycYO;s4F(GSN6j0mS3CT zfmm4Q{bAl5IN|OnwNuo3ymiV7S+ZR_)0xUfa>8pzsz!SN;=ciwCUI)-c*%cSVgGQ# zt0=-CCEn6|g!Cp-_>{Y&!rgxO2X?#W^2cGBMc1Z(Oo-jGXKp0F3g7?^vD zsEBVY1KQ{=X|gC#-AzKx6sd(YCY4RM4_5-TcX4 z@a3%=rS#654qN`S$!M9S(?I^eGC7PtVjU~9FvAaTl9^$0%Av9*8IZ9Ci57FfoqGr5 zY87t>RB*z4B8R+wmU(eE-_`2x0imJv+qI#dzw)5i>ia}&;G}?*_K@e&h?w>7L#fts zD7HdQ^G`ebRLDkldEGG`Pd#lo%K?Jy$lx?hST}T5YqMDz1&>wgJLyL^SuL2b2C!eF zBb?^c%<3*Kr^t<892xEq%(pW}rE-IgX}KsGdK8B!-_zA6^7b6bewRbBE`(v$_&}*0 za6eoO@STw9v`I(-p2IdBQO=Vv7_jm={z?h@pN+@Z><%zX#S8oH*iqz%sYf~jS=+m! z2e#e_h9Llo^+$@!X|~77u7$IEVDqTr-35A!^j~^>A0pq;Ih1Q191nBmJyp%@21!{s z7TdVr0y~>?-w>8V(3pp|-&4-@{IzpYUC?zY-o8+r3!)=f{LbXE=ONZcU0WMH#=?Ge zo*>WQ)K@~7*l*S2(dFBW-m{;N-$@K)1S{>-o}Qz*-w$4(a_G8#Q4X~@m`ZLdhc50QXfX`$XaUaZ)uGdl%RAt{Va^h0GV&oP^#~xeY zZ`tc;04z+{B2cWyL4<^PYr9F&XqjS9oYVF#drDV>t!Y@hAH$6z;<3=?=S1rymGaD` zatBF*9={RE-UjwJ#{0X;+MK$&%Kq=6QIgJAPndDkwtEyPMdf3-%ACe{44|HTLv4N- z1_bzyOmFrlhKh>Ugksug>)i|$_XCL<>1u^GcKy@dFz=?E-2oq$i>aN_cges0RNRLWimqIHG2 z|4o!y_V+kSBO0(mdCacL+z|7*Lspg9ICZx=5X=MLiRYMoMCnncpg;0HUB@+cO3c#h z+KN)KF-=kylo5`knSt|xOUcBD`8stS*I`<2IN?7TW+Tf}xW5MgFjeb<>g7;16v%0E z5Dcnm(Shq4Zq^i`7wOVj(6A2SVSfanYbynih?az z)D$&qR0vnC#uRwMdXmYrJ4?0ybs>E!3IZ8=&TuOimTsk=-v&*j064Q8HO?nNJ8lz_ zC^Eu@{vk2n)HVFWi_4IHkFTh|P#oRlydeq7N`LMp7fg$8(*EYKNiO80#SZv_D5uw& zz(l{X`aM&-TTka>AG0T4OsC7+A5(U*gnEN;i&i&?+&X)Fzoa|2 z$FuIW+s~TSk-SkR+8ktM-qmYo?6L%mc9Hl5b}jntdN}Or@DZw5tkZy6lv*Pr%;S`O zZ1iVCmpb-O4~dFik?&-pWeP^|YG zX;^^M1L}$P)EmT8ngzSZr%`(|9Qe6DI?+bXQ(!6u`B$hTZD@~^pLI2RKOv9n|9f@U z=c^qxQrOUh27Qkhs>t=(Kh4&7_Uq$vVT1yGkN#K?FHBofcNHb%W}+pKQ$|XY<6c$^ zm=t?C#oe0F9v^S(>Vup9WY(V|tfw#9+xNm|RR1KlQk>62@VC!3fk)FQUE*w*+Xt8b zdSWF~g{-?F>~W1gBA@*Jg5@mU{`b9$x5u{m!Uju-rXnBJC&E>&SIjf-E9^Mb|AZ<#j&C?>C8j$>?ZfKbmPQeJg|i<`$wi7FTxn zMr}pO#OI9mM;c)=Q)CPZ?-jf*VQvV1M?c?XV2*2Ty(4g<|N05p-to_7K<^3{6Yxbw z<{^&##Q^_N<9zgt@hvobD7h$j`(c~?}!pO2Ry7OQ>rwp_7~ z?@usjuSQOWldbhLSTorE2`6KItUcaM)tvAp#&HAt5mIh{xF)Fy*e)v!%uKfah~9nx zgGThHzqn$x*chZPDNAzEi;-R=8^8p3geMKe#njj6%omv_agvu{;A ztdlbZ&(N1RVl=8rKTbQXbElG7$UW(Dc%p>SIbV!n$<71Qu zwzQqrzweM-^E>_-CC#W6C`bmGdfPkfa0_&uOxDyIAWjZ0^Zaf%SX)tF(z~U`yCLuX z9VfB|L@dP1*LT`HWof;y(>$J}@`)usim4_HWpf>sMs}jQ@>QXA-hB|5QFC;iY47*9B;V68n(-f&2?9|?({vQ~c9DVCeoQ@Ut{(@lk$Y8Ik7nQt`D-zho zlEZ9mj1m*z7fjH-Ij!l=}tEbxwYXMj+2DxcO5pSp%d{2I__HDE$U^C!rNm zDq7)Q!;VfAw7Iw*2q1-ztSlGBR-e|b`7o@1n4k7K>nb9;jZ~hk+VTG91*yw1$lne+ zW-JF;@jqnhRRz7A46WJdBO9gli})-8znF2wN8e@u1#0 z?0D;1*Ms7US7sr+(GyV;wD~w)h1Jf+j+Vgnxu-Z@EH4@wplV$bx(4o2L)Pu4n+=;n7^ zOC-UL6vt29JaF>cF<6BIMCVPRvAC;3d2KpV(=JqE2}cYJ+gU>zmFe+i z-MHwofp4y7K^zXeWtBa~r;J5nLM12mcJ&{NeY5hn+a`ACi)XppP+nYiu7|lL;f0Pd zU7oS3p-l{DehhBNs@EY&6`ORaNckGRJxz1Axka1ajXAIL^@{% zVRdV0_3Jjjh~-5LIDrszpVr}vXcgy4N950*Ewkf)KYwuI=jJ{F6NwqMF>qpIJOT^f z`9o{XA0j@Hf6hg8egK*X(raXGi>R0F%4^eOwSi8TaDU~1q(P%Obe~PiOJT~rf)R|i zK7wK`|F~!AEX);`HmN_U9$+J?z8T z#|;;ShdS~}>tY<^83w9iqz_+v2$Bo<3W}BOBkS(W`@ckFufA{;s)`)@Ar8D!)seq8 zhJd}6b-smq*lf$r`nB8DB9e8F&G;V&``CFuM~O1DSqH8-;N#(gSS-_R1vC%2h{@0} zL#RHL14rInAEu6feWCmiGmlkVV~uj2%V30)u~-zCl5$cTl1>+ zZ5mIG^Q*aFRjOZOKf7N%P&MV` zcC7jS7QK?4%OY{D-vIY&4STIdqUlRafxGIjcV2A4*N9XDtap95Lvro9arq{(@{3D= zrIwz{4fPSv=c6sSixmf0Sn~SB%AML8fy2 zWGdU&g!%BWNvM3&Fqm1v-&)=R+)(+Z7@4q23btHTkaqx=D7Xgdp(i<*eJb&Q{@{D^ zzdYh`sTBe~N+GU+3{)n*1urIjK`lCO+#4hjk?oz^SUV%0pnC47y45qY2DIKV-KMS# zw2Jx&Nz|p>Fm@yB^68dx$bd?TiT>E=g1YlDPTLe^+$AZhlG@L%X0Rxu95P;G=83j+ zhY8PTHcJiNf1QK@`2gvA(c$CDi)m(&o<`3C-?@}OKFCQrtY+QDaqN}z8y9~uOGlA7 zK9$%A#`o86JT4fuQ!2O6bTqB=`@I|EVXU#y4lU33T6{tgr0QbAh0Leq4dFiRF0KG* z%DawzYT|b7G)m;%7fGQ?~Xyifbn(V9*z8C>9YPAb_g-?Fd*waP`) z>9GOlXZ8XVG5Mz%=I}q|lMqVBEOG*%*WO(ph95W9WGU~F`FlbLJ)#*2G0- z6~7(Frf~<35PDtTva>v;Gq{5w3B_Pp)FRbsNyh;jDDvec?(64+AuO*y@(9#8RST)~ zMFam+t4^+$2gIU9BI`lgkIKf2fO1aF&;K3H-WmK1oN2`3AS?KoeT{{H4ft#6OOONG zl)su5F<`~9zhzSTZp_O&Kber!kbioWkluH@wQJCQ5;a6Isli zH{9xTwXp)SAr(t9QEJBgepI|FC^7FaoK*aCLRZY!mQ##a}l;KA=s>Huk6)?*Fk>Dn+=3>pyHldBT@3@l%J9 zIXJx?*ew2?aq%&l?chsVhhNI?Rt|LQn@0AXl2;zyh$qf@gRLDMPn=`nFzfpiN>9Rh z2Udm*Y#dbp52!+IX8(KYI#}xvH4hcB#At-uyNj!n7&)A9| z|Cx8)#hsvN{AZGHhQf_$T73P_*O;crd2K=%ve*H$Y<5I!9A*p|9GjEfUT}_eLDX_B z<1UhQ!!I#4Z4N671K%Bj!snM@DcSZe# z>TQLkU?18rd+!diu03rH;Q06-2LD`rd;8F)I4O=vo3d-24Wh72)1C+t)ryM}n=Q)? zyGf(fndXutf5WeLy$*5U(Ph*49fYRZKzhKe8g@I_!;GU!xn7f1Hs?h}CpOVqGO)7K z`xIgBZmYyy`H+ z&HSeyU79u8(Hkb$QFAmft3MNDLu$wcy*#C;tsg>{hjxU9C#8&t*_M5iuY7Td(N40 z-jLJkYbZ&kZRPFjQc#MSH={kOz!rDdkqsa7M&3ExV?mP^J=5Cd^jtu92Y&6M49g-v z{yIR5Dt;TsWDp6SrWwVB&CZ|5x=lpZzsPluS6RvB>!q<{Q8%a@Zd8Aotud zVyOnaB@(Au2sec;zW&wZE_z`2)Gg%Oa;5VRnMd_C?qU5~eQ`P$-f3Gp+I&xU&iKyK z8(`?wimOQUY;GxqltR9!W0HYIE%NVKlaDy7JqsmRPmF*cZ4Cy6#Jh&Z?`oRV~zOK8SH;-zpX(;uYUc zRd1~sTJ2%`qBkXvOF5=BbGp$TzlzljHYmI}vj;+=~(x(4a>w?LF|7)^y7|? zQ!Bgorc7;xpl7bRv{ehWzB>XABpy(3C;arqR_il?=E{77`xY87};Ewmw(Z zm7|ZM5dt{-*Y@2NZuuS^xBTZFkj48TQCBmx?~sE<&|#?bs=#`C7Nn_IBF4UcqUtZm z6szubS9jc5+ikxjf^5>2)H$xN{r<*=MfHAbzN@Ej$8N1Hw5;YDw(>KlI+ne1-eTka z-lAodMt!nq5blhXcks3OvE9vArZLZS2Wk4=uWl(I&%CkNV^io0`;KubT*i14vE0-N zf^*8x@41PS60=#77ZHJ)KSkn3DDV8J))uUy~aw6RR3y+Y*Wkl!=na0A)-$2M6 z6yB1wfujC*mHkV6$tynS219n0PS(^EOoJ=iy!E|e>#?k(8$0@c8Y0d`g?z;z8Dd$! zfwvt%NcdAWR;@oV58Yv&H`rfP{hVO2?feq%R$)nlW2hFK$d6Q zR0O7VFsFs*6G!b|mh^*#kUJZLj@Ph>r1oP~AWU84m)_I5bU4~iCudKko@^M#{;+yZ zY~bml!9A7Gv_dB37>vUkDuIakO_pN=CLqt{6OCUUmxw9*tm}JfFLnwa`h#%3Q6I}Y z&?)1s=-@^RY;VY6P#D>y5=2cV0I%SG9#a{ELNKZG72PZhJ*i{5+qcp)S7u&3uc^9& z6G`FbIFHlAk*rJqV2OeH>0lGYuur56w~{qgC?he-1$X_TJf)|D7tS|kqv4a z1QUp3gn0~*@fEA+g3o)SS=>Wa``78m%>i}LtUk5eY#WwY#SWRy=S6wcy!B=XZx0u8 z{w+WqyTW$M)tL*xzOamAY#^y!t@!>+O;65%3Tsw&HlVrEUQIkxqwI|NA?`U(hObEi z@8|~sHpkc3;R@Tt$>FL;kE$Qk%j}m)jwMJ7(Mx5cg?K+ zk~HRwXTw;a&<0>XootKgCs;Q4{2fsr{I1~|tt?{Uj_k6S5>t zH67;BP)m?9B{5(HNY(*gvUMmrx|9SlNW5)yb-e=Kq+T4|DF>QVwe_3`npyc=Q$@@&P|V-?_-%=0|H-Fwp69~3 z`)MQOdj@ppuXJdaT1q;cH79HuJQ;y?2NisJu=e#Lt<0^Aw-{AJ?i$A-D3UlCerEWc zd}V0_`w&fjLpBo)(z2K`6OO(cgG_I}DzF$IEIq3a?PNhuN2YmoKQcTqrN*7-D-%F0 z`}u9$rq*?LhaweX@9wqOwhAi!?+A+#o{eB!s&;I7o(o1#V98A(N)@zO1tZ}hz}!z@ z1FI?wg7k{9N3C`-{hkN+f;|en3ZoC7>L~_TD9q$T8qY6D>3c)Ouey5K%ekbFc=zk7 z>^I}AdXMIa=#}LbVthSaEHIc=>`krSK3~xxc-Q%Ms|=J73N5)EA0 z7)pwsYD)<#&Bp~x*Ow-wLj00i%e)gJ932`YC!0X>QDp`>bfsm}LA>c>#JoTaU7RX3 zuZP-W*GO?i%6!Dm+zA-~R~!DfRp=y|2Cf-u?c%_kOMi z*L~dk`MlrfoY#2<9w8*_<~;@MX1Lyo@cjTj`QM;k3)`-dfa2ozzSOOIAw{lUUnQqX z=p|Y$x~U9Uln*32KGOe6K*oSk99&y}f|s^6XuiV^BopWYc@5zNm)E~Dv}0ty;l28c zgP9t9FX|MZC}+Mgjj=9{wkGwy-S*fXH`C?MF)OeNY7Od|?LIIa8$dEowPJToULGv{ zzU>Y*=JfNp`iA;PPi?NZiuWlmAN}svj#o!^@cv%s#4}g!3B`YP05{*j8vIrQClqd% zE8w5SF-SeHG5X{j&mh%wN&$-IR=ba~2$&SAYdg={U9W}rgo$Dus@Xl_IAR1G&qtzb zp)29br;K2?q8xN(qMfxZo+8^jzVk^*n$b7`bRkoinL!U+<+L|=pCf>!QTuLmv67r% z0D*>7QWBVHfuX!Q9b&f$8Ll4o2jPytSu&&Z%uHI(GIrq^kzgO+`Q$8V982;JBbLco z2>;vZN#z;mm<sjdR3bjR%Kz|UJsWdicu_`O&fR7NN3UI+MOYcs~SIM4G)@suX|h90+m z@E98D@(Yy@0`>YktjQ`M?9&~RiN1qtsy%Ey`xi#&4$;e^2B-0mN7YS*U`h`hhkL?X zp*Rn26?#?oZK* UY1Mt{7uNIZxk zK)`J-&~Vf}GI}n=&W#cn%PA*w(QdWXCV?Dv6t${0Y!tMi&y#(8KTHBQ-l;%4&JswQ zE@T%b^k`UvcT?8nI)L<8i!odA{0oBBvN>G*zt(rmU(*nfwIT0#0uZ5DTfsVoiYc9t#z z;?U^JT>-n$cMU`fIJOQM3gO!owF>q!f$>-rm}!RCm^k9a3vSxb4^6qa1eY@HDt{jz zI=eEKshKPu#$8X=%b{U$%!^w|r5~LXJd*S!POJP0?XV#Sy3Q1KktVR7Bcnges<|&H z!(QLIvy$iL+Az~GDemYI0JDRH5q(ik|5Ko7dt9DL*-J9IC#Gm$_z2AOVENyp#@~PX zEu~3=7Z2EK_2g=;uniLb!kuT7rBJM!`??B1YAT2I@d4ZJyYW)c?$&xDLz8 zO6SBcod8tQCqR^u*Y+&^M~VnrHi9^MNArH)Xz|sbW5YNd^fne)os_+szA+!3cK)iS z`sDK)A24Njz|h3eF5=JIz_i*T6^CMui~W_-Q8S%J>O#w4L|&0a0mm&Hjt0qvbTJwR z!p?P4_Bd2D1OoS#|3P<;e-<)@yzoDzIWY5FWvcOL)-wbk@)m=Ihmz8XNNk2gyLHDY zO$Bgw(JtW$H|!%}8*fS0hq0gM3p>;9jXieSA6o7UTL&FOjn$Slu>JIun#A?7{r1{x zLfH6fE7mrHKRXa&pR;zdTVQ4KKfdXp`M$6pQwUw-N%?DhSt0{XZ{$9hD4sRoE~601 z-iVjV`y#SnAaqDN)=-^5f8ak;>ErZ}YlA#0O>!XgqGdRlX^OGzXrBqRO*p{*@I=*e z_B2V&9fr7fH+_;08wwJfxrI2S;J|H8#jJN-HC6h2JB#z+N_8Wr3VrWS+WKIfC#-GA z%?ybLlu@`etKa9j_`dSB<~U82G^?98tf>%m#ncvSG-|2Nb5;Y*&jh&XKQ zAB0CT$|L*%27@;Ap#EJv%`5;dlv=R255Ke9`#Xzs$9mRn{DHgKNFHS`fr@cp&Om4l zv|Tqb?)K&$OC`QPFs>+2lAxe&5hMTpa`dYzG(6%G!tN$Gp(0{Iqs3_TIR=`X!+jX} zZU$Hs;4u-i#{FGzBP>gz>Q2kKwu}-iaDCLjc$nHX@dqA+L$ZA%Br@4;bHj&-0WO;O z)4K+*`;zkHL(FcFnjQ~=b_rXP+dw8gGzpe_*>v^;R?0odeelz7FjPD4Iq6KF=HPz| zj>c<^HJtbCba3p<15^1CZ?8M3LH5&^?(bwrQ`SLEkeq);&)SAVzKQmT?Q>jZBU%`y*-O&$b?8fV zrXXC;8Gu(~`h&c*jS3nrdWBNRWAqDW*V~IjukbJ3bcvZSNT?$QLQ!6ssX=h9vx1%0 z)4L5+pG)L8Iv$B7F!dj!wrA_r<6M?SDcp$k&!ez7wVf1Sww%o;bFI2pU(+Tx0`ypt9%;v!eoE0+e`10b`;kYiUYgnW&At~nxr*!vmD@3{#!D= z!;N_S#m7WasB8js+j@?rR1e1g6$$sPg8z?gviRcw2*i8rqf@{G>`;G22G!{nU$g?NN+`Q)K{! zTLi!d4pUoPz$zwwO_!;ijChJ_CKdW;0{i2ua({W^1#^$)i^%ewv8)1NBsoGJZ19#W z`ino{4R5zU2W>?fzL{2qc*pje`oA_DuIt7|{TcCGnI5`he={2j0Jl{wHo1wQ$I`a-3^yF?{T<#tNtgCyjTREF2;_`vNxn=esvAAZ1hxB*rsPTcceBe7 zk(yVsd@QeY-3%kxa;k!61oZUX+V29w7cc*dSlFpB!c{A(KeqTy2w8=WL)=r~kTNm< zQt~tuv!tgAKYvbDj=r5sy?GwtJdc8uTVC`@f<=s`I>><#zv-_K>|qA#$2mYQL9Eb# zXqM$w3);Y_^Gwv&eo0R%9pyWLIx=CRw~Ze5W#%s^#SUNpEOlIU7aRJYeio<0*Pnx0 zW-2TWeU!Ev*PUqb;8hFIuSme@4^Dy%dxlsi2!kkw;5!Ky@7_0Pnx$GZ)BoN!`63~c z6DCBtGLX(6Vk&TVQlX6hNL2#2jwt_`3-`A}B#8i8G~4S5${hP6zVD1J$NAv&C9d@I zn`N#S<4K9g-TGaX+kp~cp;OfBpN=7D7}qE_$bFp{c&+KkL#Mq{7$&VJ zHNI>4G2|dWcKMVWgCI%v@f<55BgW_O05yVmM-F7Q#5f}PI-ukJIh>FTiP3|_ zC1l`lM1q%3*m|oWkGdaa%cGNP*E|>i0IrEehQg5)dqKIfYa%B0h;5`VEYo3g`dD0o zM3nOj`{*t*4V zWwBM-#T(yPpu^&lj*mMZm!7n*{BPY=xG$ycz8eV3$Ng6Y22;O|TV26KU?2W0x4qe= z4i=h*H&489we#STE@n@QsJ!~M7yU^x8_)wG62VcOGsY8D4Mzb2?p@&2si=$+ZV)-} zS$zOGuwn>Z244^lC)a%yZ~*LPteJwGOX6_Jp@UyAM(aIzjUqSa^fU4AQ&4cdFVi zxQnMitn}>EA=?$6lyjN8Yu)WST%VE7pk(kvW9({au@^7X0j(1M3LB<5VcsV%gA66!npmfwp^CaOG;glu=VMuV53xWiL=nqDg z$dO5>^JK9A?XVMXw0(DnWK$VO0&7evpWA|jnl9&E=9n#&dR%KJ6aRpNvqU?&vbkic z4s@9BD8o zVW}LLw@*;vB;Q1lShpjsuXAz;>|B79#6t-wY3L~w`sDHs!=*S&kzYg+ePmb5f4#FE zQT^z`>1=gc~P-D|_dqh!)KnDu;T=*X$_70APT$Xa4x%MQO8fSi#oSDPWZj zZ=l|i_e?JqR(UhzuG5~&VMvvp4@5FdepdF^rW*O`KnqL|)jYGgJs02wXI?+ZbtjlE75Yf&p|XtvGaE7V`4i4OZ^kYP8dv#<3|LC96E=wr zG6gjrF0O>2s(IH^xfM&RXq(oWA?RCi>Z2P(RlAvpoC*pQIkWBZ9Y_cK5xSnb&WVrY6-6?Z+GFUkS@xL7Ht{Q%gd2f&6w+5H%{2 zcWLGeSFnkj5-h6q62W^3bk5;U(xe=kxp5~w;D!x%@(pQNz(aU@mslVeCD;5nz zbC_kqP8`v)n(UGzLA*S*-4m~vk=YRR*DQT#xb+9;)+dk?x9Lg29*Hi)?kRdC6|V`Z z`-0)1oEN~wE66si(0|HxN%{3g@Nv>%g>06wWyzW!+eK(!K0== zm)Xp-c=Wayq!c?8wa=c*)SzIT+{=J{7&hv|;(u|BJU_W0P5~&{Im^Xf!`bR#!}-C* zdc#@a#nHtn&jms9jIzRND?Vw5BaO{FiWJ#~n5BR=*fl>NXPUVR&OD_&WZ?bQdToEs zhvp@%i;ZeW^{N#JYmWiFZDH;SV1R01!fs)Y|H-=CIF@ZGhiymR%WQW`u_OL7Lfh6J zSfut2Gy3p>fP+Q=kerKtR@aItffe# zYBWaM_VmTX^Dbf~{Us24bi9g`wbI@cdf+n%(|hb04=z)10>}+0r}#aryd@L%7&Svu zTK$npVZraDSSwRs@wP48cIjD2JCWu_oS)39rJS-Y%k7X|>dgoX!h}*{$}pDLM*;0e zphjA@HdtLGo><8N8X%Tp&-`CCF)aJLPka*2_gncB3=vR47~i~;nse=><&>8hZEfQc z!oEgEI6wC0zREO%2Y*%B?FFL0H}?+KTnCh-rnU) z=0;!Yx3jg>NJ|fzKv{`ri<$!f;Q#mcI*?wf?2ZN+pjYX?rvj57N>7>00V9i+HRf)y6~73DpbLm zFzly0Xz#!qQti)o@dNsasW=4z^ZO+L5ST$M)p}J}cqqG+s8wS2l+*9k_!9{fJfzCpQh$GPqdV2)q944Ql^nhy$@D_f<#*}~rZ`o-4J1!`_3`N^ zsN2U!EDQIgVEUfW-#JprECX108Tr3<|6zY`a*~?2@@b(u0opi}mlBYb^OZ07D8s-m z!%M-YS!;`GL-&{luQJi+leVeC(qQrBETVisn=4h!_|9lh6V%fHcZ$KoNK^Tw#xQ#` z4+i?2kJ9ctqOWpvQ8Vz8$=*gVJCZoq){cdRpD;6!@ZJn^&Xm2Rv9KbcpzfQWLT~%$h>94+m?(m=xN5p*)%gZmHNv z+#t+p%cA#Vot_tKs>y01muii$U~^Sk^-wJWjoSx zO!QH7ZO>B6>%}h3Yt>jPznw$n<%Ww>zwzGqkHEc(`Vf z=F_Lu&`q~`Mb}rLyW4SAjUfe!JA0PRPK!-$6b>Nv-Q{-+=5d$;;VgM$9RW5?h+A456|L~NELp*r>QUYv;WCK(LFy?5MXgdcJ& z?w@Xnd|cCs$%=Z)#KRju5Y2{PeN$@Dq~!X|?L)z6YlwI*GUu7}?hcG}!RRUlRmCbdE=w()?9AOe-V*$JCBuKcNG;A*Dlu6mvn8bqJcQ*$%MtCYd=$j; z@D7lcCA3`rvf5YDLnh<$30-v5^;af@vp6T;j6;-?5|EU}AhjSs%0im=hh2xozSPOA zhLcmiMQ6l#3Bi}pAS(|zLnBUP_=X|`)uu)Rb@OL1&0nO zEZoP|5fHmpwB;O~KU=hh>+!T*-+y(Vl3z)Uyqk;U{q?YUy8nw6GFuZZ>{PARmeJei zFN6}Ky_?4rAP3-=+AB<umYlif=T&wtEz!(|wGLR`vC5~K!i zggZL;ffVEhqqFZ#{qOi`8j)+}9u+0F*OTdgvvmC|H|k2AWwqx_rzt<>Xm@oA`G)24 z(UETBgwF?qJI0*Q@2ob%fjLjyhm%1qPZ)28%4E?EWiT-*DE9C8mz@c|D-z+23Kad^ z9u=iC`Fz)wTNa$oLze}(bK$)i+Zu@MO(Gbaoi|HS2_B>eT}EGHbn=Kz$@Jy|gv`XUs>~0rtV;XQ>eKKfA*0nbDTUZBP^=B?9UXZnwBzU(G1 z-QNXYkJs$%`wG-#!rIo;3cfMxw6j){Wb#XgfxlD}xtrEN)!e2npDGe=&8vPzsd<2j zp3fhob&6mPpe{(zVZt;XOr)qb6P_fn$JNk}I4sbGsKMjZRpi$TF2!7*W zKyg|tx2*RvDUc}&1n!%HoD(*D2w_bP4HUaBEUc(K8a)vO-Qjd!i$~tXTZTQn%EpLosYQg*bbiCz9y~c~ zfi7gd+)rzt2~wJQ)~9A%8|k4_N}bmZ642BDR{rL`WAsGMp&)fjx26yl8!GO}SgjZn zV$giT3M>t>)4EsM5Gfc8$ukS0;?`79=ze% zx12w1+eP+XHqW75N1c0h*3DXnj|w*TZsA*)f1fMP1UI@qVNDWTdkv+A``ZN7QMQ08 z_I#wWXE{TQQxO3#_G25vdFMr2sGG&xIiOl?fDn9PZM7{`IVUba>uLT@VQN>mZG#;w zN*5VGERyIeo|@TB)W-RSiJ#EBw7w`}&L6egaJLpe^ z5*kWYy0zXs8pGT}2J$kjyseTN4j{USGW}A3;=MkWP4-e88i~PZMhC&?2hIK6r5Csz zuy^jR@C;p(Rk*#=$(}>vyzNh+r~&^OYbyeSYU<>jv$)2>@Xm~pKW#zUaZZ)nW`cX% zkowL%4E;&frA!QW$XUyWqvf1+8!&?Oa8mj>)I1p85)aZrvowJO^_x8R&zO`{6XJ~^ zs}2+`-jgFilCtf)D^folI6fj-8r~VywysdOFlELBSfoyB`!;PnxmOt||Ij<$FkG_| zo3LZxS3G=mSKK4X3W*c9oyqM<%A>_eK543rb8zw_wz00Ivf{)Yr$x)W?3cWuq~$e? z8?MwSPWnrQS7mANMwhqbZKYA&91?^~42XABs)}*$yaF(amb4%=E&kphXp{a_(*0K4 zPSFJ*-h8bX^V)gIJg@#%07+BPI07ZcOtJs`}Y{_`X9noq8+DwQ21$^R{!g`B#-q9j9jBjZAAxQ2+T`cgf-$BVYL@$C}vNV-zE>05O z+cBg%SINVTHv;8EYS(bBqgk9?<3aBR%RtO-?ppUeP$Io>X}zo5kcKC;E}W$e+$)wN zs}xE)VNY-;R?Yi8^~r{uA|$q~5>d*7m zE|x<8vZ79NU?jED67*UKVC(|y4#byc$|(p1ZgDwd9D6fjb(J>p`eoIa_}LG=N`9ZF zd*0=Dd`d7zYel_=I?xlo)peO^M721C>vxtYEGwE0qU}xG;ud;j{{%n4b){*jp}L8| z2b{7DfffDO1J1T%Otq+pos0%zf&X)H6bpzl?fV8yMb9M5%)7O6@0oAhf4^CxKe|yY zINcuQ{Jj(*u;uI_nYA9%5L7Yd5m8brA)Lyj!{Pv$S>LY*MqZ`R(zLT;MdR1-#j2S~ z7Nm*R!9h~fC+4?Mg@$Hy8X8zk*;`sm?J6t^zro{&ADL>VvrrO#Fz+890%ns6(k!2x z?@6A$yYM-0ICnaY1>5X%$&0CfIPi6!Q={zDb6jiTPU=KDp(M`C;?F+n3IQ_NZKGd_ z-;1W@WVy>ykVS|rS!0WkAOT6@30vaH(i4@KiO)p;#iiz9E+|(AuRl?jz5BC+$hxeT zSQkkTZ_gp-uukLd1Zf+a{b~92^#p>AA2E?3UwV-h*OuHQ??|5;-g-Qja7evgqRU>X zomCplRKw+$sNP@B7pZ}HM}{9cSvMbYh-V*gIGGehRrd*5D%#mL9?EfQl5iyA|@_{~)vv#$O!lsFmYj0dP-jK*| zirYb@^oGT!p|`D6g^e0E1Hjfh)OW0X6qp!?oE}t@1~^7(IEDA&jX-jUb>K_XbwbcF zzsgaU8uNw;)1$>N_G^t2cAV8PNLU@wYiNGPwBvBb#W(3SR8o2|P7t;Bo{3}GUMqlz zU5A)3;M3nWY75IsJ|YDp;YpR(36uaa9|d#1gxmbZR0>R=?n0@AVmCuy95v~TARrQEdse%&i}+&TQxp=zehw?BECg&)Dye8|fTAm{igtyxw_ zcLy2#B+d4)r900q%zQ>(IPSKYJ6aAOUh^f7<2o(iYAB^)v{OwWj!qP41+Yw5vWO`$ zD!OzD%kw11>(XPQ1GkE<>OZHFM~) zlNg_{TJr+xSNrsA-9X=$X6t6i1Gcj*|Zg#fn=dO0V z`Z8stq`eqg>v(xQlRB|Rbg_7{4<53n159$wpa%^vo(QIS|EvsI% z8B<=Vo+-@%JL?bJ+9`-Tim6?dDr>)4Nu3Y@1;CtjBVK+tJ|p>9^bH3VYNt^(!) zNqOi{dQ=dDPbHDpR(}aAje?wESJ2OZ0y#+@@3kxXR--`%^o~yLT56`1+QT3c3-OPo z8)L(DHQCMWe|NZJU^>oaIYpHB3XBqXcizw%e4y~<+dnSf!tJ~|TD-fJltcdKv!&dzFk4ZC53tFCg>^BPG zSN>XqX8F$MXOZJFno%81;I?7sne1KFTGo!&PL|*-p*&FaFM0ZFJTt$QguRq{@TJ=) zlU-EoQFM}Ta_W^As!DLuTA%ids6Zl93h;K-mbOUgx)HBrlH$> zqNx%#2;DVe2vwrj88w;F?6NOQS>Ob66XVN^7rUP&SkfgRb@x}V`D8Iy@U$pa?^%pn zY$5}n|CBH00-0Gi{;`-d8a!X4eU}7_bVko0G+)W?RWg=Wi+r&K)n05nJRa6dHfpFx zrOCdWI=9!fLYLS+L*dL=DxWOQBp61rKw{i3hrcgOaF+8DGv5C%Ibep%T*A##NQT1% z0Q-bLOlJ8+dIX>s`B)C6!h%`?_wGGyTg67(GU)$MV_{bfTm$9ztANd>mU?!@Z?8io zMy4uI)`7X7+j}EM%dEqZ^VHsVFT&2Ir!n$7A5X$y{G?FL(o2)i??hvCet<;6T5sRc zAkO!UQG~t;py}0*tBwM$J6~R{={cn{=Z17vcE0B?q$|H7CGs&WB?3XY{pq7toeK1n z4J^g!;!E#`A2godZ7>=RifdW^o~LzmkyuWU5s6K_v=ThfM8IdBP9k!| ztXcIYg4r_Jo;x>Ow7O9&=PuaW<5lt* zFL}3vJV;WJvc#BQ@Ex%6y>H@pCzi!o*n1g~_XlXDzla5BP{gjmTIYy%{w8N~qv2`H zvXCy+o2O6(Q*Xwtd{`%mnA+(0HE;OThR>-Q*=8i!5OT-4=I=cB)8IQgaf*RcT_+X! zw*cEft@CNE8prNpchFa81E%wfZU^^DH%(kCx0^;hz4N@}lEROV$6KOQsG^HF8?Wsm z&LUfu-Z7Wj&RHjXXW4S4M{+Trl?VU|qy$BbRp_^F>p=_*tkUl;bT+z(yG3yf*R5-P z7UYc&31y&uSW$@J3^}0QJ)()Csngd=po)k(wW8Z~yZBqRb&KCP=Zf+$2B^#khH}}P_{rGc;xdY^9}VdD z7DegZT($qCZk~3kYX4!;=dR}MV<~?7*j-Z9r`|+>nuTYnx8S&CzK)ebx|f-m8Pf1! zrMat&sa~-}$WBbM`>4w}7Hie~`5q%qrcBq>J1z)jKp%6UmkG{2F$YQhGm&FUG`s>xE9zevZHbVjhZedY7&;6mtpQM>M!Ca7VK)MI* zDmyjk42P<&pxxw1CuQeU@m(c>)CE}W70V+e=}^TR zhBf(}{Q3T;%Das*srqx3Xa>%OT#XikC_$}m)t3|XRXpXVba_p2szTU(B%eb9yeKXf zSIr*%MYlEgZ`+k~2U&Z$u~O0eVjn<-csGX?ja*gz8yCrDD{CKY!e2-&K%fCtF};>l zzd`HMnS(rwk`3m!q~@W;%%*1kHPrDOJJjc|bi(j=q4=(=@oCh`2bD*h{*#+UYC{(wU&7?qV z6m5`ljCOIFpG%&4;MFeLV87k7`H9!6XG>MbQKIVP>Dc4r@o@nsl8iF~cY!F>{KVE} zlmxd_+M1b-HPWtkDC*NcGvS6!o#$@Egk+SKw4YjNm@*|t%Pde$q&nb(RsBYW z9!W^be-a^EHTCrV{KTo8=G(L0%DgtWORCkpuml0`_-ZKjm)YxPV{{QLR-tp2ZFzcO za~#N4G_cMZyB>-jT=lf%i96-%F#HTrJ8tgKinPM?)He)sPnA+LoTTAa7ByF4|3{LB$kpz+j?)Ljraj^EZ|?cP{OY8?soV>} zDZ^tj6PMrUxMdiqfOCHrwi`Gw?h=!j*wYBmVDU&uYA@o!kFS*vRJ{`Zv@yngJu2>2 zr6+jAyob+6I=K_w?WDv)48*Gs#ONfiCdTNP%qc4_T23wFRCZ#ErxnCRRaGY=O>&xpMt~B13x41dF znp*@-RK#Vd;1+_}PoApwdBk8Y@0&N}d^s@IqcSm!AkGddQ?8}vdzn4Zt4!wkb{8x# zlz;Q?9W1HWL)49zmPrOJ4YVjvsBQ=>4g~pr>lc!14ed2@_J8UYDH4IbFM z+IUoa+1QTsYjUGl-yDoDE(wZ%0rM4`04|CI2&MOzDs zBToKpOrN2-ykCqoK-u0Ke*1Yo?7v){9o-5IlcC4AETF@Q4z3`YlR)WojyS1jd|8H) z{5Q;Vt%cS2QY*>Q19x$D^I`?rp>*^7BK>a;r zqLb%)k3qxdufg!|nPI;i?I{spRIOj@fCp3G3Kdi*D0oN=yfJKiUmU_4w;H%Z3?Uw5 zLy=><8@4bAERiqOeF97fu&zz>Z%qPeI^D8GwbP!|X)?0CxFS)kqhDm_Dckq!Uq%JL zhu1yE_!a5SYpLBAyVt1;-V+z2vxJ8W`5?ripsmAGE&bicuMk?}_ zsZTH?aJh|Z{+QytwT!7nS6D~4_GgO!LJ$g zLUtnj)0hnc2rr-t5A7cWbk-Y3pu^p!b&?jzBtM~VwoRueg};XSh)E%IV(RYAeBAjh z1Lj?37`s3^eh3<;8U7U4u<~Alr3SW8)f;46`fkba)+mC#vSMA~gl}Oo=INq8=pkVP zkse+l*QC%jg`4>C>1T@|byZ`E4i(Mnp?Cgl?eFG%5Ws{sBT4F)h_Udu_CLCXNQv>Q z(AESj+z0RP&LFk>15@O&721oBaaDyooV&FF&rdrn!~7-X-CI&poKgaNdU_7sUH%Jf zwX+DXQiZt_bbw$gy9Ba{q53OmMU>5}UUrAwg;&YR15I1v%Fp{|%asfKvAm0Eceb)I zg~;rxjCs=6wV>OTv~*$ZKN098?^zs)JvVCHclTB$rE z_PC}JvlCm+)TEm{gX&ReczO(mJ2UQP7pqk}`^=970bYcXxMIZz?~h?e9w#s>dqw}j zh6A2~C|)S?T}+7{Rh#A!-@bvhSnx5JXIhw(4e@r~f1$lFM;79Z)Xa4dA|*IFU&k^z z^k8L>F`F(;T!*MzaZ;W3?1G>?0|Ol^-*W!C%e^0M!3W?YRsoF;5CzBK&h8DMPXJfoOJ^27k8zDUhAUpp7}GKbImavK}|BW})#6us!ri$j#+ zPV!b0K9urzeqbtJ8f0fy027LP4JBXcU)6F+J^g#086O`8oR$=S}JXc=qi6yTFjF7;rs3l$4UTi`EaJL2Uf;V?>92fPmoqA9izOKE6mI7Pg^}6;za4AsF!XEq)HL3%|eQ zpc7CmLZJU5{X5ih9ec^>@wHqBpr9np#ulpuYBuMd@VbS+=cSH%g?J6!fz32W3!=UT zd1Qu4OiW{or4`D)NAabcUN^nE>KGyp-N_am-b7rN+7uv#aJrrGjVF#s6hXpsW0{mq z!x;tGQA<1S%_Nz|%IeC2%=Z4+ zK#@m>d=oaQCnMP|hn~$4%Q`!>?i`gX?x;9U&4K5TZ^`fv= z=_E8oFPyJb79Vp(#-;XhxVxP4nrquq(oiQ+#N2#u9nTo@>8H4QveKWXL#a)>yY)fK zIC7l$H$sPJ+`fq+=g`BGI;9wD=)pvrm_`V!e#6klN6CQ)nwkMqT4jR_QIe8!3`SM@ zqAs;0PypYPa7?ngl;lW)lQnMBIZEnFZ|FC)eMo!sDo<<@%rxG`9+&;=LR~nb4`||2 z`RQ#>9$wLrXbyV3te!(%N9XXDN(rAm;^U^g&ArkaWFK7r$*)oPEYnl+whPwR?A%f`yt04ud2?Yvfz4Zqa*bXjwCHe1^ zs<@`by)8_f{@G>~=^RtDt9D$OZd3^kmT!i}lsw0~Cg+Nw!zL>`n0rW4NwtK4oNMVF zY`~^nfIA#Q&a$-N_#W*+mWrdRL#vd_uKZ8>FbK8IG@C}=IJ|`VT zLRb-LP{f-&`0i=vz1|Gl-tiL(^!Q{`aTrNC3Eg-gcVdhdCO1Cf=An%0sB3qrVp^#! zb7*>QVZ7hUH+#DtG^`lj9Lemd-TGkrP}ze9fq-JUoXwgmLm0Btxt)3xBc8kb?N@6P zOTI$?p}=bfLjQr=tCKSD6*wv*G=2kj*O#r@g7G1P^;P%J&d!Ln5Css3DB_V;`awtY z;gMc-d1+N+(|m>_qbU6iZ@D$f-%@O4CnM~zJEjbULE5pwM0Lhf8zm~Cxw6(d!<1D0 zq5C@DfT)Ec1?`RF z4^Bsif8F#a0&cx~e!4PTtySG!w*5`qTei3QFxF1s@UNME_wz`29~;+CEq4w((ow-9 zJ{Rvf$fNH|a(u!hR{bwhK4IZ~+;{%`B1Xaci1&W20tV+`xtD2JYqFI2k9EFTO)Xuw zjK_mnUVz<{DfoM-gGd|mhug_O18pd`K9z!W=OxV>FL*fEC4!2)P{lSHMvo-|aY&L@X+;-=jvoC5eWK~}cQDD|bzA+OHfM2Pn5&eRGu1u&S&Qx)Y?M+twfBgD z$M&A_#$m;k7MltTfmCY;!bKOnU>@B>@meV`bj%IE{TaE3M#;Q9;ua~)3ROxj1~sj` z&2CZ+T@Ki_ui>3?_`YBuS2aWBI#SlB*1HrDFNbsTJYz+Njn+CgZ4+?e2i zI)x>++XZRh=A|6bo$HOqdaP{@(twt|t=}=vbh!V>3FOhV!u40MM1!U4NGgtZ_U-{m zXS#p;C){Ej{K{r#l`4~HC%rmDPp9}UQZH_lH(oIL$O)eXZMe;fstL1n`0c>r?%%u5-H-W>8q*~@;)(d_%U|Tsm&4QD5j@!NL=F|`496*gK=V!vwbiJ&pB(v9|O7n^DS+FNLI2bCsxGVt8-ftX|{ z)clEj#XzNMzBsrI-@0^sOCVEqCcFt&C!H)#6yQX&8mWzRj>+Sv5#-G1aqmr-&+ z8m)$5d5*nYGNbbY*qCaSG<6NK+c2xz7~)(A*Z8K}Ih&>S?+1dJOg`rEHu~wZn_BJW zvcGQpb9Xd|{O004$!w{fJ_D3YcQ=vscT zZb^RAR$_2SwSFSiz|b?x2ARLG`|DMpQ^fvERAN$PqB1DBHGWTYQt+bZp`^Et+~*}5 zmTo(GbXI>jK*w2?_R5Di2Je~mphMJt?THWDk#l;;NL#FX8=>f9`8&Sr?5yC&i7HJ` z9r8?@>!n>#qK>5GaH!O5Yxm$q%%)DQ z*H_9MX!)bQ5&ogN9b!|gOsQER zEWQa+yQWFF-WLp!JG-de?`S z{B`46p*__g!!hvUf*E`=&~sv8gGwO2a+=#bhI} z#wpYVu8}0RQStjKA0e-$1n9mMoS}o%fd{#F!)BJ(drMg4wSjC{nkO?SzlMM?>kDOS z+rOo$(wh@fDrTF~Z``LNP?1fI@zpx231xfhS^m{Sr|_c_q2NlLc%RNCi z9g~^F3*4;Aps!B_tt6Q#>U+Hx6nZHY@jn>|2&6RFOC*T*orM4HL(u3ge{1bDm%VEi z!TtX%z*pHL_{u(|Q$S{IfvsiRD0LN+rSa0CbdoqhtI;sMPCwnXpHrQbZj&C4kp zUwaZw`4^1JY~i28j;p|slBPRRo9wPNGY3Cq?Bjz2@NKe!mr0t%bQD^-svKUa!B@05mvD5!e{@8k`)tzlz6RfJfa7CEd=E&1w;;Q8JLA=|PsD$C^ZgY%wy& zt$bLtzPD@*@1EY4bgxyDe=v}fWKrktCQKo$`dy6MODp(Q{h^lwQzZqfGP_w+Pipa8 z1WGnP96|OVH@IkTZWuUI$aN5*pqVOfsrT;dJOA3VW0J_W&DnN~9`?`x$N)?3es~f) z%sJDemMX_FppzxV1NNmg@87LqZc*1fNv}=JX)@DN?*Q=X=BG~-P7>NKK3%w`-l%)1 z5+Nw_XL5WNF}Z(&GF+DO%R{15 zSJ)FI6^@;}-Ya%tqQtn-q78`vq@>RdAm^1Fuyri(31q#Pg+Tx2_Vm>rSE3fQUv|(Z z{A*L^nEebH&z#9=!-G-hp70%9P`%EPx0XiLlkcS>)rtGUtD{@iHgG@Tb5RqRUnM7K zhNUQ|M>k=xZQ7$Ks8;j;2XXrc&i~1?f4Be-*1TL6Xz|cDwXoj4a$s;4LRG6+C2)Tx zqWSYS|FtrK#8k|6#$sNsl{d9h`YJ^>_Ian8ivvJjy3e$u*={LvbkpFwO6cL$L7Pj` zd!2^AsR0SJYQ+LVZ$IVfXuHhmi7@;8?!>QG)p|_8v?cz2e|nbPGNo$%cH*$u=@Fr< zz-@j|yrCBGZu9Jy@RU&jgR^gl<){A|>8e^n3ZxpP)p3GjO3`D4#y=Yjy`1jTuy zBC8!43Ej6Hc%a!%KoUfKfRNFh36a$SBxos&crzOyc%Z`tKc5^qqozl*np}=G$wd4D z5129@yyxP`4_vX|AvM?A8lg76yU#z_*$jP|6ZK)1Nz>VsBYU#z5za$SQ`2Nr%HaG} z_s{RgKZ@A-8&_t({yV5Ek613974>M8?6#ALA&)!2XqX@`7J&6WAfe{?Iz5znZORTO)Y6iQ9|FLz@#80WEq1EPeWKr?F{Fx&7XUsGY81{Aq!9`2JcQIF zzH?}SEoO0OTg#ctYuu>r%s0?>gcqye@$-X7Y1(hlcA}Z@x?@9TK|dCy9Rp*Ryt?1p z@X|vA4ZECt6>9`qb1%mC<(e0X*? zP=?3DqOJ!ft)aUguZfnpu{X_Qyx2j>4Zp~$R4v&UAq*`mEVi;r2U6?_MFPZ#8oGAC zbJ}!x)%erN6~g2mF1fOTnkcnNqjV>rS9Z&X*CH-al!GgQ_3h(=eG*DlL_y_fziRA| z6;!O3zS_G$anN=q8O?m2%xqcwn>O;x0JZ~3i-OEU=kJz}jnU6wtVDu-jv42Oz?SBH zb%z;CVM`kLgnX$fPM^6q#5-CVH;sh?F!HFg=j4Bcx*XnJBhbz~SY$IW{;P%}ojUYU z1i+_hy90SQ@JHTv3G$-=K#)V*cD!#1Z2X02zeJmTl1N2Zroo1a{-#3ag<;qVq`51= zT^QKK=@(o;U|zDiAwIobE{Le`ovXXGl(FJr zH$ui>IsH?t8ldzLd4`*7Z?rt_WaS(<@T4Z%Uv&@?LWP7mvkh1ch~C9wYV=%`>Iw}A zY^mlyGnQH8dH@50o1PqPFT;~k;lnqJ5aFtwI$_kL`G1>bZ(_WVXKQS24Z61o(15n% z-UgsS4uye*3bPb}(x-cF^;_x2*Y9G&1}?t4$2VuB4Blrzny|m(`3;I>!wm!tFXE;s ze!66;Ri9f9V5mCx9&Unjbng&keUgC~aDr^8KC%?XDE!UbIUIi^5wR>bL5Uz8ERjQ1Ma)dWbci$f0zi%@=>T&MF=5n||2xK6-UVLm31Jgl%m2!zQ zU?~}&vql5n;wLYXqb$@?>0#`j1MTrVAj@`ts|+D3GD&RrUy(hZMrOJf_(qqJ<)))M z!!O6=0MoF>bYL&t8s$I+T+4F#GnsE1heqy(zhp3*v4~+ou@vRA&xuB$MSyvSdRcOH zE3_Se{A$F>8axa4r$cqu==kkEyPXz3~wu z^fq9j(^#R;l!{csgM>}k@Xp$>D-YMU6q4dPzCW~_6nvjco00Q~;_a6G*N3<7gvq?K zzsd_VnO8y@I&;Lyh#!^1{h<}2SL(kY78-k6B1(H^yR&}IGw~Kjc5a?dGXJF5 zgCDcM?k&%j^)`#;O*Ni)QdP$1&CS~(^G(IwevntHxOE+G9|;ZQMeASZ^5z}LyiKS* zgMWX&l=@0-9#rNHYX zULP_KeD6c7d}yl5k?kvO#zk+bxj^?ig>SH_$Nf^!z*=Aca`H@scJ*+pM7-ve1+rA-Q5L{#&s^5H9J_;9A09kilEoQ{Z zG;#FzF#gw`9`->s+F!ixi@K9_y7YnM31FO#4^KjZG#UOZ8`%|j=o1GSJC=VkGnmD! z8A*R5_>Ifclqr1s={H_M71rFUz0Pmhr?}UK)S1dubY)U~hShvD z@6Y+Y-XgZ%hikt*`Gj=%_JYr|mFvg)yfK`|rM}NEP1+p!D`yxpp9`g2YT>HLs(TNd zSFS!Z!SQ~S61=O$9(6TpQmDa^V@V091HLBAbkiXwmCnHstHYD;3^lVbd7CC+5{`aW zQXmVC@hvSn!&Jw0GB#|!1`0If{RXDovb#d|&yxn;&rk4PkaG{3pLS{|z!Trr!Tx|D znE<*Ot%|Gycr7a+#;Wyb;R7%;%)N*UQ%Lx^Q{xm##MsimMX*2c4gKsHW3X=<3BmVG zi0GtvIuw;l%_a?nJv)i^OLUrA}i7+eCfe@yx)Hl+WOPx@*Nj$eh&- zjqW$yY@5a7I)0@2PDV5(5|#yA?z9jNeCCHamKajP>&s-~y8QIlmg%$=EALwrDcK zHO<1Y@kVf-mD@Ov(}q!o32aX7%iEV`9GB3Q-n6IT1}o@6HnA2rr5h`~yL?kx&B#ZR zQh!&Y^Y|D=bHlG0Y+D=r`y6hHb0!=7AqJM)?5K_s`Gr@vz|?wod$u*1YM-^?&39!# zC0dgV=RVj5IX&W|=Kkli9aosnOpyCiogc20#xF_qm<&Paa)> zEnX}eRUAQMe1ESb206jlF}|AJ&Hw`S1{ELE(zVhrL=37SIcmqp7NJ$Ve4XWS*Mm=h z3(%A!^!anvjYhv+k~fVL2mVO?Z&)L+ELs`Y^nb@GdTDB3rPOjqFM3 z9h3Rd^Zf}~Q+|_}Bvz3laP85?rJp#_0psih%z4xkUTE_mhKlDE6R<-uovrlVzOR!MCDRX$oGC+~itC za$TL*iiy;5&m48RL;`_nGMmtSyFbF*r{qK#Mq$`#Ox!IQd#f#=H^znppxnMfiOBxI z+~4aGOW!S(r6d+?tPjzm#TKd@r_c|)^&jNlMhiTRJ;7|WqVa_Tz|;7%*;l2xE!}Mb z(cLJkAsiMbR#Ko#tk>TFe~8oduEDJ$!Hr_s1yQp68pS4+Kaf5H`#ls4oAJvpzP({L z575NzJ71FI%S63{VouR=Z4yq`rp~vDtp>NC&l8FAB0e=@^EG78nVQDi3>9{kiWF0v zOh$8nh;a6ttJ}HsHD`Y}^-a22tHSvdg~JaA_1cgJ|LXTHFbKHZS2gHr%k*S4wrVY+ zHTP%7hm~Y3m*~ zi?gkRZN9BZr+2-3>{L8sc&ji_zq)ZoJt4+%egY#Lw3Qj)xW{O0OR;{*n=$Gmb?1XS z=kwL>zUL}R6xhkD#n#RyRTK!0B|cdn_}%U*zVZ1Ut3fC2?=D*j{F{-w4iBo?D)%)f z%!#>13O>u0Nr_84n?1;Yl>JY>b2mn>E?O86=1=EPixC~1CPEY%W;Y21#u5c*9f+&~ zW2Jz^hjxtU8$dQFH!ImwL(zy{>?W9n^Om*!mNo2RvqW&oXyQl22=i0TAb_P?@WEc$ z9(JJzTy|ePf))#CLQOgJyWrzH)}-jt4SMzr8f%$@Hm5rdg40WE>p$#a0e?-?0pX99 zl)arpdk5j?o_1DJ+?ztbAhmwziLAo-t=N~S0VyGci(g4`%Fu4I(5mZ%*jlS08PKACUD;Rp)^bkXiL?f67X{+B07D@nVE^p? z%oYZfOqT#-=b+qoho}Pcq~+s_?*p~)*yWZ-j+IBE)vM!%QBIX&#B6iw1m}(l>#?62dicO_T=g}3-hQ09_toQ&~P^IYXcygyExPC z7V*KwV{FO8@y>?Xi012x{r#j3UheP`YsIRqilvp~;abWVUyo(3zjINA9At_T9zs6^ z&g5{3u!O-eCjlnIfCf$>?_fd+1PBHM6E|FDQoamHOSEGf?)5l-qq{Qtupim(NI=>piI|MCWKTkliV|FGu@Cu$GOKyYj@k z)f1#~RFEIy#dIRrRnU=BA|2q7cVdy|HJYP6jt~Q$OYFgTRfN>J2%NDyl-!AcCN;p3A{MvmZYukWR$-{l9IR;o*? zRRqsN*J4{e(pP7UKz80IaF|j&Hi_i-`J(rd_-}@KczJlaEPdH_3Ap)2088Ix@g>`3 z6(CMqly+GPa;<3$#Cz>N6<6S5r4BYRiB+e_B2OnW8yBm}yy)tdXxVtfQlVqRm5dTr zpEd$nOuf${tJxNH;S#2_IYI9k%1qHF2Zs&8yTjJ5B({G5JOkpMAg(61tb&ig148RI zu;1ryl3j}mn_F;J{MQ3G&LUwpuv@QV&-%Ik1t56=)E_?T(-^jeIwe}4`<5-WpN8U= zjotCMMRjn3T->f1pK3H^HU3wnc@r>@=vy)NwJR8STLYB$Zj+V4JK{^Ol8-VBb1f zU76Ryffb4;?p0kCrz9YHO_Xmm7os4U|MM;D$8slNxR4HW;nqHbX|2T5v63<8w^5WP4`V_i%f%NZ^N z-1_ey7GbpIgq1-LdNvdR4G=?1v>a^}H#cWT_~F{N_2G4LFlPdc@y@Q?!!i0AA};{A zzF*o=C2>8+es7xV}p#tobH$a|lo%($6E`TBNi7SqHSH!E7vCz;ke}{Zb5Prnae= z*}E-o1*4)ib_6guxW{zm0ScL2alz%WboJ-cOFx{DqC&zfA7tqaFs{GEDtn)RphI4u zaT7=^A0gvUS`+E8>XNCce@RO2xe!%iw-bsHt;KM>W+9aJyFrm!fW)~cMJ_?(6|)F> z@f#PE_z}dYzR6R2TX#BVcjI&dZ&dQb?9}MgNsQ$p!$V9caPGIl=|V7yqSS70A_Djy zeR zeGRMJt|dKz?!8y5#tM2NSN>)vs1nx$nu(prlT1dFn`ls*mCiCRS306nvm#gDRL-#< z8J5KVVt_xIT{|^|nW+*nt1b%++{StU>XgLSa)2?F-|)8-2MDhv1&W<`=SMHnrYheo zz{Upy))Ats^$RYE8MIu~4A`-sw}GUJGT%sRlP5>`oSX?^c?V`C8;Y{6#_MQY;4R}4 zk2?gip`ZK`wXji@^BQ??Q$V)H*$AWtm{Wu_=jkl>&`EeTs05SeMC4F z(XNk(qavbs+JT6RUu4E5Hq_`e!IIasBGJyQwQSwUcY=YZbw7`kiB{XKeah6>ZNU#A z({>QhHO<7w@oY&lO>OdxUGu$mnF@c5ws?GgKY1rKwtj{^V2wcNgEUAi^uCS>DGV6} zMj(x><7VOUz<0JztlD~DI;WqJj$W}p*MsUG)bvlEU((2%x8u-+`r!Iqj7De*p5{78ft;R08Va<9WkLS3qbw?=0E+9JR?uTFffC>S>9 z{;{cWTMv*7%9<%MQ=V>9Eo_{Ds_>_*x#nsNuZ$TbY6{;S*jz?V+j#CdkC?%4;1nMFI8^}}PQtt)A)UUqq~i;XDzYIv0a~u zjcQ?cfs5PwS0Bt+(Y5j=62tP9O$bqcskvQ<{eO9zlO^VFn}7Jx$lPUb$qOl5t|>v3 z_TRVLfOG3s|Dt2i=#2@}-il=>^TsV>uM5}Q?TU#@wzPE;1CoR$4A&ha(R2a)LN-hU zc5d6ncs0okh!@C@#G`7`_0XW&?mH)D>;d=qk7GszNe(M)_D8rpP`mtHnWv@z#qdii zpcwDAs|jI?_(fxxGQj1#8>rAnn)KUkQ{CX(RP)Nbns6M;HbIG=b95p+6<0yIJioI- z`)S&MQ1A78-oiDQ%}c`j&M{Ea-@W|PqrCtN9gUC?XUe53%Qy!YaLKO|BiKvgyG`G} z1JGyruf7W(1hQQ3#;Kn}oy!B+HFD_+8#%}%3-SlYn9Ef*t+Snbb-c}&3x#>Ql6L<{ z0VDDa8M30Js`Oe^#2wBF1+Yq(Vp7V$vd=ChP2aJOpRI!3#(6}?xgCs$rRCV>lz)tQ zBOsj9Zt_(kIwv#{34+v`-ytmQupfU^jYc%>Uu?a^L%ecQBkF`8VdnG%z0yB9Z>98d`P)wL*kLC@+UI`w9Hs9L>{fg3js@T*ui770ASbnss(uh9LT-rkCWDLMv z%V>=EW{pyk4G7O&CMAZXp^?Ptz`h};>qLFu*c6jq#5W9kNcl<8J*?a5?nG8kYv~g^ zD^o!F67j5?_f2D$mCDuS=*HLD(eTK1w_bd#8vDp$wg*bt^}`GRf`L=aOlNsOs)`D? zB^%bf*Ub@NGBR;tNErC6nWeS6_!O&P zARQ1^m{bXFAy}#M==a783|14A1c>2J*q(J7p<$mZ)xalQ!t5iKF))b}G1os1%0)DE z48P6y7oty80nI33+80)j$ArY$em*yjC1J95`TIXa$E8IO1427(KO7pnU|3ucmHCN= zAV$BrjeWz^kB@dojZ^v?K>-w|X>=>1EFeqcm0=vy@bPM>lzFVt}fC&kLq@<0>`@!Fp{$ z>(dpegZ*=w_T4T<@Wp;B6S!$q#_MiO5xnB!W-t)?5!Sfc zd?sKW)NE7cHb;Ic%=#DkaZrT)wO&*+IU$T6JCJ|9B?hN-uOul-dJFmWRBOM^3DwQS zY^_w4e}hO{IO>-awf_KY;I0J(yzn{nE$34cmA~~ZBeM9wJ!opCV{^}k9Kb*Tl zkVFK3_C}qmS%_L;$&wZ5yqu0(cJTIdyZei|rR`dIkXoj&YCAp()<_rQp8Ob?!(*+L zSQ~DD9Jq2==gF+t_ipuzo$FUF{`$<{lkNsG;O@A%B9n;*Dk4=HY$WVRn~!2$6E(R3 zS8ki6&aU+(BlO(y$CW3z=eeq*CaJDEb$$24bw8`8s5yx-9RgRXFc20?W~#i}wVQY9 zN(b9Ynbk#eX7)CJkGy7kF)g#8HO|q)dw7ls5fFV_qZvu0y%$TjEx+JWn+)gP2>mwn z6;6X~pIbU@E0O9q;AIhT@HD89O8(D8LA$uISL59MEy`hQi+u>4JMjT1<&Y zut;xFyKKG@U?O;|hdi0u)nz36xPTX%kpb@ZgU9;*sD8LxrV}?xf{%Kr<~os``#nx= zyiHPhCwjIA_;tW5qu?XVY!V71Fl@8`k;Y_jH&aFL(Ppc~CIRDA??ef}pjd%+7 zt7Zn~LF)x#OC73O%hq14gwHGVGS!Fo9G4{9Qe9BSy?dq)WkBtk5vHu;28D^fj=T5#gK3F85` zWUZdTY+omN>z>uQFYZWcO`96dOvD63Deb$a{B7yL-Mr3#xlNrs;>y;)Tk8@b36M@R zti1TP9TIKmV`6#vBO=QoXa_WKB4?6{jxwQGjOC{3Nj>}laQczT#zAe8oiXx<-rmvj zn_uKYE_P+pi~Dwf8-6-Qd9jge8FoE^diqEDb}L0o|eY= zzcRBk=PUz9H3x;b9=OPzPDMG$J1yUB??^Ws`w(WsUZGO-Vx#{fC_4;dsnuN=Jn%yG zyU5|=btiRru|S>PAU6=GGlb#Ex4{*_I8g;v!MUMu*4RDFMml6}byTXAk`f)sa|?gE zp~mJEy=dF}G!`IJh;H&*hAb#%gY9LNzl+(gXw5hBSP3m^u~}AIY)27qEoxbq14r^r zQ;CHus$%kt#@b8e{tY|0m)c9JuVXgRRH_`IVYI+O$m2JNi_JUT`7_Hr-s}@@V+&=I zBR9;nYGI6z6P)zM{B39Wl%(Z>0oEb4lgoGLU*x#Un_3ffn!_=?nU37z?@*kLmri-y zW?i*3Z+hPEvszJ%hB}Q&s+6|+1F$bo*-BMH3Uf|3XG@olC8>L8(8HM`DlUW76GYv6 z!_V&O`R}mzTsb-0WPH!8Kh*|cGbmU6*(Cymt` zR`y*zg(d@B4isiu){$yhZx-R>gP{+^TY)20acTlpBD6`2^5HcNwkzdNuwAGm`6Q-d zy7e=4TsMqfnnL5b+E7V#O}VfRK+~e3t0Dj5eBK%xdN+CR{^C|B&ZTH{Ei9@TmNdKk z5ofV`WN5K#(7hlPc*j}KfA?i3SZw0G1{+2Q4f8)#TZ_UX;E;I0p-h|fW{pVy#u}yv z4*l4P8=&Lq%J`VhS3B62@!gJjqpE%PWkSj52^3p5hsxd9(_;_5y_NfbwIg9SD9K`( z(~)$73>gQSv6s+pRsiYzC3vDU(sV&DS|L-8)hbVV3|u~!{b>c`c#vC;+AB>KuCMZ1 z38=fLs+j>y7R%>IRxOu!)0+(YYlp>Oeg+0E{*>$#{ooGYa&PxvNA!IHK;V$iK;e}h zNj`3$Gsw-_@-ER2PAPA-c?g7cP?Rke{l$F=mv}awRWKj!52mjxPYZmzz;1klrsJeq z;Gx?-Be2eh96~X!TC&(6z0;@6zVvW^2P5qsnIPB$Rz64Orv6x zfQhDXi))iH0UJcwoWn7qsbt@z=y}351ecb2I00Thz29vIIYMTO9r6hr!|b%!INPo+ z$4NQ|v+dXUMNGSN97Yo{kG@qgc|1gl(*Kf191vITLGs5$OoBM#fChmGP4P8^9!kjLE z{7{?9d$ZEqlxhf!7|A4>IjOc@b)LBNK@-^vJF7>Y4DM(IojrNPPIRgU;yAwztaUE|TiE9g;6IbfGoFy1TG|B6?jlM~Q$k z_DDVkwzTD2^ba$;4;$`8jogkr%R zy>*8u@&HPDs&}V{u%t)6xNqM_KSp?87(-+@XwAZTnC~%L#VC(cs;S=PzfcY{SG_|J z$pj0UGZHFcT21~IvoHC7hfxPkoKB3YdSWu{oxb*;NCk$NxA%APG@hg4$< ztN(UkdPaqaGO++->p12nOhj(OwiwBVVy8TQR<~RYkdK8fG(S``>8?Skn!p4L$tpn# zJ0>wk7NLPp!yYKDF%ZPoK#L0^`=_lb{%KA4a{nvD><3L#k_{cO_K!dJ>*fYO3sL=@ z>qFTjJ#hIV-Hw~+5O^0(x$~fG{8|J<(%ca&$$*jK?W-%gX%Adp3h-~;>E0IeOY52< zOjJ4U5w4;6A`f*eT5T&>(xY1bf?!~pzA2L)n>%l{p(mn&(CN{;~X%IWJq2`YTLMZji6uf z^Fqp4gbTJMffrV4{6&*p*LJmQ4et_rvvTe}w#lsdol;^Ed-IVcKfx3Timf64`zjyi zDcND&HfV}Ail2<31 zk|0omx^x2YqL14E6ck!5nwS4K7`w=0&k_g7lI*^o>^SPv4olU+y62qxP-d@%e{IkI z(I$?*0)iKGuzww16XXcWvJ6eu*4n;Bd)qKQ>lOnt4F7u%pg2p!Du<6}4vqVmwmMn8smx?elz35Bssu&<9? z|9ozErnI~|@TDKBl*%l%_nm8W)YbUx4r|wIybH{3MWq8jI!0+(NdKRk4l&PvIYL4K z5axN&1pdtz1c3e}S6(v_dZki(TMd|_aL9g*;rpPbq%nhV{;@OPIQ=1+Wre+hINXR& z@Vcp<-`w%brHgds%Ez61_B1PJ3}TOa>_r7o&%$rJm)W}2qeRy$)qyou$HgVLzEcP5T{)t-;L?Zr zsNBWb=ET94#v24gy;ZC;5`07+q;|c_qRAf$lpKn0_ZHAbee9Kd6H!euPzoQd$+?GZ z^7=KWUEiqmhS0}S+Hp2Z!)CRKPm4^#Yw1xAGGV08Owh3kMm z?aWP5(dS%V-uzM;0)K42jjv|=Rwb3}knWF5Vg) z2Y&n%P_-i)UQYav57QdXU~iM8SN%>ZTpdi^(0#Yl^9GR{-M7q>D9r4&MDCIN+&OBO z8`HNedy-V;Ax+`&$pPh}Q?X-b;i)SKrf$@Fp!{+95VE>27o2D7-rDCns80Nl`B+Sr zPohuE7uE_EoU^?_40Qd77q~&}jqURrIl*LezqY_DE?h(JY^sT}@n0N-%m5a=i%l@2 z3BaJ|!1Z-YSOH>whOV#M^GgtYHlLjK4yVzM`=avITxfVa;+o1k4l5roP{8b?^R3=I zQJ}43=VGn1o6OYPI{r(myDsFg-o=Szc-CsHe|Vk&f(TdklM$dOGb z1=b`s{ktkjgw~!=T#TQClvL3}U{taF;Q9B`vsvcD?6m8|!)lv7TAk>oW>kuq!Kf}f z)K>E*g2Z*5GI05YU6BS(55B-3sV$w^E3yJs9(#P&IWWUku3nhP*L!Vq zQKN}cqOGcl371)u*rUs`r3zO3ue_{b(L2$;L8_bh;oy*TRuhfvHHrK+gv^0|GB>>t z%$8xu0IKAJGd+MjfAe4sD5bf1SBC1SiM{Hh`3W$0ZO48xeiapIiUG-ZxCk&VzhHYX zJCP4#Lx~jOdXKd!f$+@5MEuT=m_YGmJ1PdO3~l4BX(co4%Shk9BT&0DvmD<))`$5? zG)h3QO_?tb-bQ_l{*6a(6!E-oI1B8nj%mDlrA48VvLSu>=}lPlbmGW9;)ZM$HXwh% zUY*cjz!`gif!s9uJm*#v+K!_nhq?ET$x_%&h5~x>wJPxzF%E;JSI~3mXKBltmiL=1 z(jRWp*zfawi}K&4=K0uH+Z9t|K&P}KaqN~cJO*ZqT!dg-!Ap-kMH{ht4;?3NZQ-l8 zB^#eY@YQtEjZfurBMj0}Mt*O=hiDV+{BJ{mkXmm+)VFjgRQTTn^LD^PyGfIa{|5YQ zx#JkRa|)(?Pf>bEK*$~{ZPk#~1FA7?!!Lj8a;}*Xop7za#|o;dl@6Hkq(Z~XToV(x z1DBd%dkUDx?UK%@4Z~1tto=DZBSjS5qh7Flk0Ho1S9d{63n`XBkOw>C3834Wz~UV1 zZFn<)2}(`+Ve*ZHs{X^_>lp#WxC2(jj;aKZ`t0Rh3m9fK;k84xIzGflDG!% z`ZR7+d6^w5d~j;-P9GD8qZTK%mc@kbk9Ihvb#zTCw9QW%I5=QIVRqpSlaHU$QMe7d z?`paDQEHn|oU`|0AIz+{zU@F>#%Oq%Y7m8+;fq8gH0f_0cZb3}8~hPvN}Bh5 zxa+RSH5V)I>6_D^nfQg=%tBUiFcm;0y?vuCl1UvKk9Zea` zX(FKTFz!3uKJe)!kEg7=?&men`je|OvGWKbT+kF%M4AMXwX zFzjl+QZ>1BI#P@#>N2MIKYCH}VkMS|n5(Ou0tF^5KU8S;^rpbW+^>^dGe6s8P+cSd zGt_H1+t&)Wr)J9rIb@?2;^SOnr-$|4)pmvYtZPa5+iE%r_dZJ5vO`v^ zx^IgyUSJ;)*x3S$s|G-wn3$L3U%$A^E_^)h6VYqZLUnvc-cz z=wKUvJ4?2W|Lu%B;caFUqZ&;$3lM!}=E0IHB?fVce4$yW7RcmGj?igR^vDj?IyiN9 zIq%#94%`N;MJRTufOYTe>(GgwLknL7{jb?Uo&jio`ro?B2!n9^{G~Eln!sm{6Ff)9 zS82Zg5PyODpk-yCGg`ZG&17_&ALCR^=TxJfqu-_7o%02t-S1s*LCp^?8t!hVUwq() zx(we&Ku;V{h=o2|ZjPYA(3>v=(DbTwa^f#m(&BKFjg*Dc8cj-02+@(eKp?ACCTaZ< zHl{Vpjfv0%#7F@&0YM5y=ZJo(Rxo5rZ{a-)M|i0rxFGM-*!c+qPWPV6ZCsd z`>q%|*J85^z`SJ&Xhd17B!|Y$Bxg!(rGB;sB3dkZgH{Gx8ZLMNR_x4lrb=j6b5)h@ z_*fIQh~}%tE+5>(0oOk*s$tD1-!p0Q1qNM@pdIEj&;oGLi&7(r;YG;C4qyy-w0f;->apzucPnz zv0uATY8|jATkAeN208ilVA(GH_)b~+{hcQreZBf7O2?OPuk6R+PFCIYGi6owgcL;3DjdF>`|_RVms$|<#`;FO)$eueqnAUK$5kzU$8GP+!DI|e9EyQW zS2Ng>iq3?X7u#>ouXeiHQ~`XDPyu#E)6<=h?Y5t{`+5A1M?67FX%~Nn!dvzOy?GAk zJcPaO>o>W_?1p#w&!}39*IL@Cx-JyBzc8>=sM<8(dXKi*sRL4n3m#8$TI76Nl##fYl-9WtQvtfuP05kIL-JmfbRN}Vp9-}R3I z&A66e-hBULpaBva0@P#Up~^+%dJ8ral+rCtC+>>{ORR`9P>jRFKgUB04@vTO5Y6Bs z-}L+rX7|$zvy>Q)yV4%wnRWGIM+bVfQ_-&toZh#d4d6CbOyGdMP`p2j8Vx~>Y2WPL z{T;i_afa&ATN{X4q%ZMT;AWyeuHIRiy(y2~dKB29Nm(yxqPG(?FJbig(f$STcNDFQ z82nN@8Y$NS0d3%;J~DTQ9xFrQ8g`RJqqk=Kr~8tt9y(E9olFWe`%-oP6OkjzXN1xN zx1RZvd}DsTyekvodWrMMlyWB>1C12^>r5tnQZb;CEezmy@~WPRV4UX44M+Hr5JsGe zTgNZ;zLR5BfI_TD!cY-kFd4gjd0T^Ii((o@S~Sg6BiZzTCJNUI;>RcBfU%kW zWY7X+su6D{LZLQR(+?Q&a7hF2?_#p1@hR_L9zsc^MkM;( z7V}^GUIVTgww{H4sY)MivAx7%u?Y(f2`&DkjR)yFO3eG<`elO^=nK z-sHbtCSY-Y6`sA~J2GaSeQQ%IwCbku2m~W^35_M5KC(NjvoZUI`Rv$*_`Gbg%(L0D zoFq+AcEGbKam;9`9ijifah`*I3kaC1UvEvjrf?-#!KT)Q7lzf{9@Gj&VCD7v%? zfQ;Gj&N$I}P3RqwGg*P0SBEV0|CBSR8uR8b~2auJyIfm9cLb& zk3aj?7PDvuTKbg_ge^7)Nq5C)Goee26HjA~ElHYw{wNP&o>0C=EZfY`NHpIg$cK&! z_qf|Y3{??dOW7rduh7P8V7Ps7`e??=92FYtU3AZ`6fSzRI;-b5Gu!nsrd>i7vJx>xw~?p|HC^8L zn-(4{rBZyar1Q?7ur^v6 z&c?Svhq|>5OboKVvUwIgJ@@U?M{--4S=jo!>&GwQtP3w=xGoRwVwHKP{n)m01S4X| zw+kS7I5FR{HQm@O7NEk;>xs_Hp54fMnN*hh!n-3rtEZVc_CP+n#bSmwqSTz8ODCm2 zqaY~cPO*Ie+q>g_?3~?wM<_rpRd8rYoFwy&)=%%LPvH?yWGued(gn&*B7BTAeIPD? zZGZYYW!$$q33|6`cr1>3Gh-mY1mr{SYM!FwG23rjxVITyZmvLkO#g1Ra39K@Dz&%i zlvpnCX_CjXS|^DN*vRa|#^x|g^zjZ;+?LmdcDR#0gmlHekKe#2(QuM=_3+KcG z6FI4fl2O+5KUi~;g`a};3dqPcdx zZfbpeW{p;tiJhMJ$pJgl960Jm$OBZQ)B7 zB-4+C*|&#U29_U(jg1oV((swB8&mO=Cbh+HXIGru9*4?yq4hFdfh6RD$$p8@F7FUt zP7_i;dAg4oc0m_`hRC z_(kCAs))w%QK8C;J_o73$N_+z9A`4L8G4sJL^<0Jzl3MMbe{=i~)dA~$yX@w+9YmoKLSHOIN}z;@$W3^8#0XfVKry^P+x~0&Zr_#I4E&S7z@sQ%?#%Y< zE;G=&JK#W0gX3N$C8brkDtgpISQz9_y7sx}4YSNntJx$7MR{mJuATZvVIT9hg%`~F zs`(1~4ThLWb)Iz!y8-!L>UwVoB{Pc?yw`7p#}1_Zo%3gjh#d%ecxojZL*@%vsnP@t zv4i*QB-pMkEqfgR%AbAvJCX-%--Nj#{XOioSM7_}z`dX+3{nQ_4&ArP?#~JEyVftd zJO+8zVKKdG9eQV^&4GnEetuzzb>|JaUQDpwS=OhQ9Ft~k73u^xoR~e6K~}+%T}h*J zVOfO$ZykyEDerK=WNTMFJ?jXye!KqWM2{)pOt8BQUlb%?de(Gk-NYT*-b+2ENN_v& z6&FPLsbahOWhkI!CJinBQW}n9D%Fg!US55(MUz zbCOwlKI8L1;44qVo6Gy|2B~O%IliZ)wE-aGYr2-@e+`2Y$~}CI?>yEG$38tNo1&y1_M(5A4lgMPu2g&@oy;-kr5XcMaaGv;hGhatdPB3Gkec# zkIF^Dy<`DRJ zJriz;KJi!!w#g`R{O3DKhtedLL*1|k4u~JnRE+Q0F>eyt@~&y;{(lNn5?cfKex~mE ze7wA#-FCY8u&!!nEKl+1-at0&squ2P1EY7fGZ@omUQhWH%T(#MH<~x?0`qrxxhZla z(*Gaax9lxoPmzdqj&zI0Lbe0K)ZOi$(@-l$5T z2W6I+*^n!@mOZ3+-278FZLgyTVKkH=7ulU~z)1%vY$JZ2Wz3O!$n1!2Gz2YGx=^Zz zZguUpZ6!R-9OMOtbFpiHx$P*79I{Z|xW0K-WO*H#Y9x%^=q}j)K=dOD~j4Mii zbL$FKH8Jp~>4iBr)MIhB-e|}_<*MA~18~MT+v(RA#^biPil-kjTrLSF3yYI!cYkh9 zEmym;aCfOUd!|oT&dT=FVn=xqZ;UT8C#Q7ITRp-L3}5NM*plMNa6jN#5@65PBi4xV zYQ1me_*uYTw-cmv*t7A`{SEm~e)N*gWIi*-c}YJzX{n?{%(-qg$jtw7ykmSba{;M4 zN@{-3-_(4oouOba61U?0V+1I3m@|H`;w>K6TKkkmOwc7B7oSV3E)8!Whv!h^E=N+i zE5eyHf_E4LuTWVvhmJgfS67u@C%3}UM-BKVK&$uSTZOAAY0NM6%Bo53xR@;e_hS;B zwwpEs|a-?6xiUi1`zz66v(0az@=O0o zxvFX)7)zo?2LlpHnoR?nSRw?Uqls$n4_uSECTL)qRg|uHp)I&=NCd0D@W25Q{TGhy zb}tzyWMD6CiEm(B8(!=teNGG)rVF7Q`6Xn;U_v!%IMHX7Dn6EY!j}s<_ci^%DTQjd zGmejeOyR{$9?!%cqTBqOU-)}ao5!HRu|Lz=+wG6P2Kdp2lw=dVVtb50@I5mxdZX*| z4N?vIXUCf!BB1`b&7=ACua_x*W#$Tbq8j!46{K_w@$Umu%90uppW#oJ49cCs>9bEa z2(wXT4Yx75KkK;hKAMQUThG$`$%83Z;x@W=A50~LZ5eA=I*lyOSV&Sebe0>668IL$ zdG>5SK?OEY<@QOLwV!_B?qUDw=|_!CL3NfRW{;FN2=4mh<`dCCGjde&O*&HrjdXnd z&S&RU6%ObO4%)8@bjPsgwH!emKo_ooY>mQ5B}6#))d{9!@Dw0ayS?dJHyS#R4u(`dVT-1u&62Y`bx&)Y4|g~&|G z;=Rm0en3}C+)BKHBk3tI#GJ!+C7kjf%0TY0Q2IbVLr=f!FL?$@mK_k0fUJ+ky~ty~O`KW5F8m z2OjSOmRCEe*y;1jYcfdjlx0o=g0alK>Sw^{#ICESrDDjb9^r$|syMV8=U2L;P zg^i+j5EMn5=J*s1^p(Ov@O5O_+^F?dQkxrqlj0S;fU|9i& zjKL?A`UqonIC6!zd0(AbtkPz>?9J5$AeO?B46%(yHpqe~HU0ikxo-RH|CvYUoo;|~^b}qGl9{oP?0pf0L(m^*)N0#@B2BySaVuMh)<$NjgRzEd_ zPa8MVMseA$XB^#P5N-R37Fcx^c|Mpt_F7j^K~(*ndW_Oz(!ANcH|_NC6ye+Pibl6g zE+E4>cZF`%Nz=wPrmlL3L$m;ML7-pP6fTChG4ZLG!b8JAD1(l?l|x;xtD!2CRCN#$ zk~ZAcI^YFVk6HZxDK~M_OrB2)9*A8Rx^J^k_%GQZ?|d@4?cl%rbFJ<>t$qkVzq?M@ z!d!I@FwV$rmOP}COsM-!uqI~3t&s{=mRi=>Un($zMjYi$m+JxY)U!Q z3FCTBPa#(cJT9(VpN)bSnoi)#cePg%jGGYNwm9FLyj>(a@GBSqek@m)C~@)~hEo4X zSUUW0Jn#Laj^@|VOcmaYA@59KT`eKkOSJ2VyKcVYx}QybEI8oFw{$H5-%B5gx$N&T zv+i1F;eT-!axz{5#^wJ#7n`xxFlZ2PimJ*?s-liB*da(O>oy&B_&luW0=FGHjK^D3 zF)^aFq&+6R-WTs1&EqTzrfjHAZjjMPHFr!+X0#an>XPY&e`F^ym9;UkMw1M>qG6tU zt}(?~1Nr?+uk>w-51bD33J1(lDzdGOb2BzBh9FBAN9Qi0bF5>8u|a!WDI{Ffpq_e7 zxT~5?UEf>qH_eN&v#*|v)2SjOgh|azI+>Ph&6md60|NfnwonR04nxCAV~zeYK#o$Q znyKmuJM~G^r=WWmo$1rXOH69OgQc~z7XfdK4^w_@m1qX*w$4PFONeDm1qRV6gK882 z=(-K^qsG?Zm6G}AwN$Mu3kJ1L^>P3BMGB2CwV3ZBrj%RtQe2^uS|i*x{v6~^XzG65x{akjjBfRvWji@ZUBNG;jWgF4J=#x2SfsV6 zF*QXD8DH35A~uK3titmZuxsm-hmatg1_d6_*m)NZ6Q>W|Qg-&87$mu2O={mv(aICY z^3RvcwkempRTqIUV8`Na!SSWfv%dZQ6okyQXrI6FgGLl-$YA*<4`ycqvT|#ZBVdf7 z%P$f3ch%S5kjCRHe)`|@naqbLVxZ(yYre7F_|zLGT*Qh~-i}rJl^P3~rt87&YhE-5`rI+AGM(L<5jbNsJ>Jn- zhW1*u5@uA1txj<1?MB5AJy(S>LGSYQjqvISH==?m^Y0kW3e>(Q#Jh+hB zn7T8#D`%@f+YjxA;K_g9JH(EOddBU?d@di|DMaV#3;ZPEmn5-i_PSn?#oT$d!FyKh zBAZeGv$A%lJAi-R6lsyz;N?3uj^&mwVm1s zbPseM6jiin>W$gjE%cVCsbAtpI0tm7X^k!1UH`P7%i2nG5SmA_swjI;Ick6ZA# z`{XdW%xQV*d4=1(%#)(WaMUd7zH__r(^RpLSuP}(-{jrUV`L6X)+IMa?nO>a&j#iB z{q`V(pPDf$o~}UQsZ@cxb6kCqtNF7T3+&uT+sFe0`n~(JHZ8*FdD$yRJK#$E++^+N zTqNZqlh7R}6|&^ji_o#4B}=38OF2V()7o^1q?&4kf&mA5Ml=1Y<_D<#HAUQHa&x)$ zRR{j}%MV;N#-Rm!;!BzmO|!$YA+N%&fDS+h(|W>T;K@!n;uiqFmCL<;*?%_fNpf$s zm(SDICz{A9wc{Uh`;Z55UU&c!H9I64ev=D=vXtDoBo~>fhfZm)5nWKLZO&_a1X)t} zXL%J|{1WxT1swqVT-unwsOa=NX^^iJ(RaWk$Aw+3)|q64UEN3vEDT{hQpS4Nx&3@T z=!%zu68Zh4*t=uSE&%tvdVqi=!`d%n`N+=ZVQ3a=g<2hL{-kmROi$@ zgYh520p-ZK*b5d0_*lNmdIjj8hZ{e>K@#YMuM8&wqRX8DMjbpmM8(VLC_}z4j-$@9 z+FW9~Rxy6%AgssdWo8fCMjlH}Z_5GeQ;B6tX?q1WL8B)~9b(r$y>lLmwq3w36f~h3 zze;UB{{S@M+VD45SO!D2JQEUxw(D(4oa3!)kvX~*eaxebD^F?5ozo#si(V;C1dI5{ zO!oV|?iU+t{&|3CbiGDeqaaS_PUWHvs-iUKu?3f4`Aa}I zfig%W_G#|oN@u;Rj$G}UH-0Rp#aKL`XMNlc3eryuwlnBYc6hM*hBh5~A(ZC-!w%N! zJFT6)?v3@mge&=w5-+IvbC@xP8v5FH-+SvgO0d6MhlWvh;k=$P+F$VuujM^sazr)V zNeR#Ni{Bj0Q+?~K(LWd3e&wZfjMRb0?5AgXHITu-%S&PE!K=OUMRFygxTqq@{$^I< zpuBf+Y}==`x115LR}r={p7#VIVbeF7WSL1QzC@RRJ^x$v;}1Y>bs0#G$Co z>g~CKBSag4o8GFWw;4be6!k(SK=H&;*f^cS7r1=p55`0>9+2waEoTd19jbhTU5~(v75S(Uz^whqm;)P-C za13Lz?!@^14KbNtGTFZJu2>?4t3962*}kBPMKkB+-*r!4*bqB!*E1UNKMqok$>kT5 zU*vV0WCK{VL##K)RQw31d^O2SM`2g5nYvn0U%j5r(1!3C~oJ~w95PW z$$*JV+Sh1b7yJ3O+F@xucs;c{4Y_!^_@2q; z-MiNf_`YmGRl^y%zU-}wW8O@&EHA}e0j8btL2*mgO`Yht7(>h(%I@zpza4EE>@1!; zuXT;JtZS@91qTBQj17bSUt*{$fK~eL?<;2;vGXjCt?yjGQLcuz&$qnHRsl*tGsOXr z0Vp7H2)yR%^0=+lbsIPllWcSJ<)F11k+w+L^PO+jWecOw;+!H?4<6Gp?KCo>+WfvX z$ymtxedmyRx(QMCNu_>J^A{jjn~@s=f?W)Mh!A;q%uVl9r;M)!HoYt6-Vt8cOcXyn z4!d&d^vnDrKUpI@!h3Sh`9&i9U4W+9b!1;+Nx4kPy(YxDNFi%ocF_AEL^EQ|jD6z8 zkC?0z3b|@DvSisint&A~Sar5X{=^*Fpe%mnr79iKPVY|XoA^@oue9wOLH}%U!NvpvJ%{JJ!Ul(pQUjB(WE)$mzcd9w93s}O5GDmHc}OSnK2 zs8wfeX6#Xg$PN4ho14NEz=n`~)zBtn9bbYk@wsQgD3ZULz*?9o@CRmoiOF9zI4=JjlRq>L2D?2t zC`{;<2N=MzQ{GqZu+k8!G*Nv!i@)G~Q=iBX&jg=N$*Mw@hLFn+8kXM`h3*MH@7Zhz z*|+)=?upAXjmG@aEd9@aXbIdu;JPM(0%E|2x@g92c$KY4k`XkkyXYwD|NxWr- z>31JGzQXl>+%>kOsy7z89$ZM)Wo|5tP_E`+?*iJ4g@s??*hnG6`E6F85nDY8gE0A6t^{d;7+;J-7|SirmeVYW)u@c8b&?fdR?>EEsEl$1o{iN1yf z*Wl6P;kaQo+nI}Eg7mK&auyc{I*Nw>tQ=0ZE}36HK~n==*J9Tx&krY~Tf{X4-L+5G zJxf#HUX!DAyoRNS%;WQxU=q*qXyy7PzCIAx2<>8%g(- zy}I|!BA=yec+FUGlDWKcP0RgpbW{AhqxR(pH($!D7}ztBcFs_9|um9j{Dl z6nNw?K#pPZI_J1;@1V3AS}pYE-932U)`s%9^i+&KsraQjY9+bo_M2KD+5+L^ZkyK! z`gM11Uj|6$5#V{C?UiBo0mzOI_XJpUUEvRWTmS~Mf`ZyQ!JpngTuejD47mhX+}u8p z`6`D}pe0Yo13JQvrQdg@T@wkElx1ZOsj2onSbfV7M4AQ91+aZ=S%kkAJ(l51g?Ix5 zuoSGMrmhedhe05L6*PHUS8EO;Yk$ivQ;6Yg6Xj$30T}`yXaAx`j9DqxS3+mGkNES8H4Te zBVtmcK!(pujyx|@#2Kt}Oa;XW^@usYEFQL+SaBEIhkI>4gxB7Wjem>=LSqK-NVi>h zU$hoctR7rxnRph{n;%R$0Z|Fj1teXy-)EPOp0besOYg)o*VwY=XPwiKnkHZEH=rf& z8|GGOR$sMV>-eOYy_UESFV!PuipUzIC41;dZ>o;BpnQH-?Bx8yu0z!enME#7>S*)P zbqDodV)UDlU!zPx`pK@nC?^^TUdKeapZK}@@@{z62jJu&tdmx;^_6J_WV&miw(qQu zR(jx-`T*Ycuans8BqW7&>y&-*bKb6`7Yy+fYbEQmc=s;{4Wnd)9CCPdPjq_nV+V7C z9PO#O5|t$b!xX}TG%3N#yBN$k!I)J_>(iPca>v6yY03n>bJ>-uv)<$FU&JVyq)s)u zv~eZkqZ;UGnl(801rW9sb)koN0uUCXaaD7=?5bjhFpZ>SfL3EFkzX4DR*g5b9PL@V zyblbWKGWVEHG!Fyqo&#;>mC5s%}5R)E&ncNsi_pkehl94nB($bKr7U5e*j`hN;g~_ z6r>zSqj(By4tcXF^IZhSF->TmsruJYb zhmE~bG&gn?Pj~9gw%{>K9juol>aT~p8Kj6m)qhkx2b_5NT5%TsPiYjrZyX>*vkK`- zT3xghq+=%5a3LM9%o>Z{mshF^`mXL0G&w_$>iJEm@^%4$Q`bCwRfn%Xi}upeBoOQ_ zxY-Wd*Jkgfc)wKG(FfJ(sxH-i%~=l?FxQQVUtw&k(bv+IE}3WfQMLYBAK9`$Z2id2 zj_NQfNPkz#^X%jCmxJYmmVI3%eZkq6Z8xusyi-4cP3B5;iDE_}^VdV1f5-z`_TT0b zY2q@H};2>Yv5kuhMVcUZ%=@Re6jhhzJWkJiO9I~muToFSCc`9fA{ z2y?;7DkWc&3Ov2XU2Cttc(wz?*Yt=c>F)(-$UjL+A5GG>1B|RpkFK~o?a{v&?=`nS zF}awutkF%|%^78SKRf&K5*W-vGCtcm!wT$vg%Uu9wHx9@Fk9$of_PyfVGqmc-C7o6kW(lPot|B;emTPlUxS*Kxl zc~}&phgYX1_1;a2b7q~>LIKqo3Sf`>cWhZCrnIzV30SxGCPj@PRL@h}Y#EMuFKuRl zr+(7OTc`)jf7hytVVOefbV%ORtZ%c@>Y*gpK549#*cWtC->{cDnq;!O!rg$(5)}h$ zJnuj040wS6-Ce`Esf+{3$<)}=1 z`3NUse)(n?G=i!{N!W@Bk$Y_bmO2`kFKMjMV9rM6PS7esWX^sYHH^UFQC?t8%piUH zzDEw!DH~`3eC|G88^CX#ypX=Q3evCH<-Q5y3?>``QGW5D*~c0(=72Q%v{-fVq1~xz zO!87%>Y1r}YFjFlCsJt=w`8FKIuA#KRbdno?HlB5ARsyq&I~{<`826XrtX*U>`teb ziRFj!AWzU`506&&?Uw6j9h3y@q{2Lt>wfwi;W*V~Yn!85x2feN2{shT*EDQ$6 z@cdbeEepi5R+yf~fHg(pc8pvTF|NJ4k8c~<&FFJ{on`mD4OfYEH@i1t3iP;%8|2RC zw(o(gCIz5oZQh{8CgpjGX{uzha|?@q;Z9y{^jw8iDLYbl5J)oWCTA{wkyal+%~~9vO37_OD$^w9Y6~UxwC$7f9gN%K@USMl+YrDd z`2&^ig~SZ8A z`HeNKifte8A@JK8>KN=vVe4ad7i&|)IiJOoz53(Z({lXV!0Z0{7?}PxQdy_PM1l-` z9p3+}l!fZsZFs+GQPGu+2npUlL_MMV_bL2E(KKL|HA8wdpjAPEnV-h+HIU;u>L!CP z8LeZ4XNA2SNckZJ#2b1n8&$d7<68vkccnT7N%F@QsU~1c!@sGfsn*@Kq2>%W_6p+o zn8y?ZYVOayRpbinKbXH4#sIW$kaX2;I>65Y1VuZxHfZtueFRyC>skICQU}R(S}tZo z%onMn9oQj4S4|uA*d34l{DYe^pk}TJm+ttR7Ml$Hi$$%wN{d=BpS(dGz@?SZIiv$> z&J2~Sd5Fve4<0*ef#lC3oCovh>RVD19PL7?IFQ*n?uh2dJvyo)X=f?H{|JGasK;BW zEf0;+?ztj4_wKMdMm%LWd5s0QFm)GJrM{0+Bmz12H8YryOS2PkjWcg8j;%^ZRgt&c z3Krv?qJwM!&sMbWQMQ2S5~%;A zzq75dFk8FqIdoz2r`~q2uLhDCHvSI`#7|HF_KmYixnK2y*k3CQK66fJlAZp&oD6`!-k!%Eq9M>||Ov~HSVYS2EFWG6%&5-%{@WxrZFr91))iM$n zwhnYP@fI`Fx$S_0>^G_zsYGXJFYlt;S?(oL$u8l{u1bPAvgX%DecPHRHaoBc+@>4j zOs`Df8mzbP0=$n|K1&Xmz;vA(VeWzKbx;wv=83++Z=W-3j6s^dVV=q2H_gZhYZ8(g z)Ry)vF4s1kADMFlxJaKk|D(23wy2|D-vp>{^tzUC;3DukxJo&;1~w@lAhZ%9+bekd z4@vLk)T?braU;RFu+$ZJQnZ4^F*lM-7k4@_i`X;2=tQk?w6y-2TvgRJHj2tTX+gYy zDw)drRkA3>tht+B8+zl+rv=mr$Z&^D6&(b4t3vHXSI65W7Dv^aR$US^0 zt)t`R+za{Svf65yOxbN=xaK7ZA|)V^=x3sR*!IA?T2eDG2leJW6?|$OnX78ZFqy*B z5;KGwU;}56Czvi8Txd9E1EBj->+_5O^W*)GWv(SKwug%bP7Qy8XPc2YceUNHRQTO+ zOVC^X4-VQW98kRWmi@UOmaf~Q~JDRtjA!fsrZGyn{$#mMW={4T?4}%Uq8{tbj{~0 zCce`^Dr3a-xHmbxNylW|&YTVs^nm`Z)XGF&x*DXxA3v3Orx}&Dm;R`_S9Tg4ZunE6 zyH`_SxE4=&Ie&d+hR4hmDN3k$v|55gbKqy2h=R8_4yM+-XPX$LZCa>o(p}_<7JZDo zd#L?A3>GjRgl7l6!f60F%Tfj;{h%mj6uy=xJSRS#^Mp#%%IB->lh$R%2)dFXKkdh~ zx=p}<85DxyRTH;eH2|xOnyZ0lj~s19o`Q;bDSlo$OC^GkTo29e3KAxcg_CliL)q%7 zfDe+O3#NV1{Lia%!@{xkRGq#z$^}r~Fg9H#6D2((3OI1CmCPV#cKN647M1wm@X9dW z)*Emih#^SchWX&R$+tU6v&b@lQ!j60WjJ9T+!hg-uq&YcBC}{QDe-R(cVPnYL*1l60se*kHvhWY% zhG5Pe!gW2%etzkrIUg+-SKnTyli4XJs}%n&6Qg2#q0BNtuDw(<3-mn}Y5=0R>OA%U z1+#0%RHg(LzS@iCb7?*Gr#J`hppE3ES=fWFRA(^X%8U?l>G88y)!%IdgMkoY3Ecus ziD)VABSS$(ouw(j&wA7{Q3;4~mWsnxOx2!(x@t($#q$IJg5>8yhkLN)#IVWH)Jjdk zl3Od^6N4_fa2~01Jx|p3w_5gV{_Oyg3b_M|=6sH$JjmmEA>b&6*f7c#Kwcd=?0Kq%3@c7BrTn@GqKUX7(Sqg1dgXZ%`yoWtw(xFa93 z%}4^X0TL1Tweb(CY=n2WIc*)7C?xUq2?mumGTW@%h-2Pk?UP#W-Unc*H&k5Wf7C2X zAxy~t8tIGra^4Rh{>$&X0A(MoQatGuDto~!q)6H8OJM<@rYcC`4``@sKVZjuD3J1hY%|j#$C967t*0Xa z)!@W;Kx`NwED4D}qQz1N7_OLt0w29kowWNj)%N=|;_30);n*Fd{1Z$~%~H<=gHXtE zgjCJiyZ#Tr^y<~hJW4`TOvfIqO5Mo%+d}mQ?@jD!G4k^Dg5!c_G(US zHV??Jz1Y2nenDWqNFeVLNi}DQw-?)T)jZAq>s(uJ`j;-)wVk%k_6&X?KeCdL`}yyg zBxcJ?ZEDLPIb_rA(F^JDAk%YRN-@DLlh?R=hyQrHz4833j7jaU3Ip#(PjY)&PHy>i zgHl=6^4=}R8(~lT?^pJ-;*fis&x7?Duo>vwdcex{agg*GxP`k z4lp9eYssM8Vz}XY(i1IjR`EJmxAP{qZytAos!z8s_*vRa2n6@5wSw=DbtWw?xo_hHC@ zAnA#zyv;+C1UPkT2$mi+14%d z;5JbTxE)v~LM{o?bl<`XOL@nxk7@lffp z3=mDGT~VH={(N_^5VyTjCo+C{7f!8duL&qBgEE*4tk9ih%HZ|@?`2((l-3F|Dc)%m zhjsh=dv0Sd-Zf7!wq*A7(0IuU4yl?_S*%spgcY`z@h^uL<`f;dOaJFM*7z1&S3*yU zk=(2sS*&FZwFG2>wHSGgylr(*Na%lomoBZfve#JlHTR*Gva9qL%~obOP58ZcGD9^h!L;3fu-QG!`@A}-4+BjP)-5ArnmOi zO`{$PVW^mt+PV_y_w~LwR#+Tka>KfC0?~s)wKWNbvQnk8y9XgF97>l2q>3l+_OGK)AmFRFCcf)j#OIxBw4fEgHtC~ z`$F@TLp=7=*C1cBGoe0(nn1!ElAxn!7Mq<_W~SR6|Xmi7CA)ZS~p{pxEdhMIeumM*O<*Zq-> zU2Cy*`hv;4TT??^SuLG@M;K#j%AB;2zzZ-QN*|0wqk;Kqs_}?U=fc{v#f;LIh}tls z;WL4ayRcx6@bd7HaWFe9Axd{~H_fI}Tr6K!SD|6eVj?bU~iazvlLi|J^g?7m!)C{6KV5uq*J??jzE}Au|y{_0pW5zz%l4 z&&6N^c*;9_K$Vvc8BQhX7E%*+{J4R)CclFf7l`V0>?L%)u6gMm;G4w(5Z`;+f5n1B zI=jx?=&%{gxZKZ@;cr<)ztOaWU1h(yK?8p-LUpL~I{Nwk`%9PiDslkfzRTi0Kt+?R zx`o-O@w3cLv|@y9vykh?88HYuFrNgCT31kEwI%J$7BgxfK#G{SKAzQH*c2ReHZraceLmtV8cddzr*nu?K^El;-DbL54xo>%&MjM3cMV$=2jue)@uJ{)rOoVG5psk>FR$!b}1fG8QU#^ZpvC?^}#oQQPK zmIZRFkmsA37Cx3!?9_FMfRA+5Yi&_dJsa+NGS(`2V~6wI*+Qrp}w3_{ElG1xj!8&nCcE)`7Ke?XmNZGsC>ncRjOB_K5E>akhSI+U$0anq)p?rn+08 zRwaJ9uwyHb_g~7(23~&M$&L%m=zTAbi6m)D>Z?HA+>I&TZ#l?sPAhsPLfRm!jTTjvP<)){{M~XB>f1z_Y&BzEXSq z5|Lq5yEQM_N07JJ3`_>(kH-VG4ni{Vt?pk`x^EM^@bqQMrL`Wg4D7>U{!Na z%9z10J~MzEZs-hnf+z^SFEtUtd5XcJ(>vrRzlmTVl8lTvl>>NLKC`GdH-bo}?bSQq z14EM$1NXlN1Nm$%@xkX=(2vL!wFMTgUJnNwfAJSi{W67LJIcIbn0(v4X|N{piAGRw zz!8zJtEi+7Sl@ek=(XClM~SHvyfb<{n$&j4`VZyJ0D$K^?d5OR9v^qAMSB6L+j`=8@1Q)vNXG9*G8{5?M9$eQn_9Ub<;HA zAqc)*F(rJWu>Nl=abyhYV)^5ppWR9ih}zUa%@s<`CjhZ=%t~s3POZ$K1j8tEKj=#Hj{#AuYwBA?bM6p?DBDSd$5(-_ zr6iK2B7h;970)BK=00;9(1b}}!?v||9a#ws$d`Pj@|2ap!XrwHc=#@+qAQhDzg!-i zT7UDlb<_JWqISLut6}na#@sy^-G&$4aW?5vgh(>5qQ8dFp#MtTy2zG9=G$tJb$r+q z?r{iHBddv+=gd~5t`e)?3!8Vqw%48T*h$e`$BdWkig_OcH-72+-7j#Js@E|n>Wpjg zs-PMn2xkwv*aETuBr5Kf=>DyAVVX_(sr#2Ke55=uZ?Z<_#)JQYRWg7eX>%*&O`fG{ z>!yxQOt&|w&KA>*8pYt&f2cyBcZVdaUp$mJOAMW-fn1Ic8bsm&4O95F2-E^K0>97xvB zgLgBi$6Ll)BzF3GP1oUH?!lNc(d~P+cDdZ;z0glwxG>9p1+r1x+GAjfqoe{iFa@J%7vNs^ZQLox} zxUc^B)d2W6i*!bCc7c9u`bFBaW$?1f4?2mglLVm7;X zL9C>}e5-VysZH7I(R^k&Ncx{zSx@hsJaPU#zoKkBznFu zFPn+^f!+R}n}jBCt=JC$FEwGSd`@pEQ#){zo1BnU>$D<(WNk7)8L%`SKYmi=OTkPd@CzJ&#-OLpxzU> zMtzv$SDaJIWnSN2j{Kk)AM>)sfXWcmEM|q^4sn3ArBZPRrL7Izy1e(kz3h~$R;_0q zsGgoixzC5C#zE7?%Zp4wHJ1i@Da6`49p%7eLk088Wq zhDa5pe^{2F3HvqzC`{`fn@b{rd>uMN;G-ltFOKpYvK|csisu(Kz9lEQt49gqph_kJ2H9yB(AA!`qqyi}EeAj6dbyaef3WHfVFkjjmr( zp^hI3Y+2UU+*VUaBP>$f!8$)Ia(6Dz{aqUu>CP-+IYs)U8K(d`8UAxYmnWJQqXL+R zHpmPONB#(IlOOT8{FpFUQ~jRVL(qbPD59acx2#AEDQ}xz)q~L-%T{pWzrLnwv87z4&=C zpZ9U-7wJ?E%81Dsa#uGaTC8@%+;!o6K#EUQ`;HiN`~MpO=UQOejnEh{_qwj?#nHWn zD!;h+5b$WLpd4ZDpw z7*2x2e1WnT)a8FEQaG7oj|qwe*94A7r?;zMEvR~R7Zrgj*OSh+O>$af#f@U<1@|vH zzT;DOnmiCmAg75rcU=-!Q{h8^!!Ylg*?LM)3PvZ}%>TXao%`BSz&>;h%k3?WQyz>1 zW*>$^X5W^_VYEn?*MjaFp^fgb^r+w6A3}O$(&iPq7Zu(T>hvPr|4NAUZVujxwsoa+ z%Hl?z|J1^BQ(k^^-eAgyPqd8bE&q6(EdWH}tkV(DWm|Y%OE&C%Ou@i*jW z;SkR1!S51Dv@vK_%ECyn9sobJR2pd{!snUiap^z@j5S7iWaUG--{LPfhxdbtyB2Rm zNmX@<04to6CY*-5EOTDkUEWpK40*;Oa;#F^`uap7V%B?5DiD0DQgaw!l57tC3quSl z{xlM^9Hg|`ZL%~O%iajD4Qzh~??xk4eH#H_??^r)dOP4H;-7i!vh9Mg`C0vs>MVaB z_v?;>+|;s5iGqCrg0~1WdiH76w=r>}tt7O)A&y8genr=SD`WUYD0}P^$5yw&U(7m@ zd$*WUTZ|a6;%;C==Y13t(qGBUufQF*7RrER-6ec{SmTgH1~4OC zFw%8hDX_o0@RPy%+itr_y!8j$N748PGT9up?7s3Z0j~{mnnGmeV$jo#KXLM@_t5|K z4ak|&%cz-Mgl0QSMvalcEoJRN_;d{j!<&fogr?i@n3J~)NkBV^B{>{@>!e}tdXlq3 zhtzDV!He7c{Nw}{?nC{A*3-Oe=ym6bKLD4tV&)xLWj&acPH-Y^6hdB-J?`gXeEXZw2jDnWj_LwTwlt zEr*RTL_!r(Jf|6=${5ue?!Q4pTq3Qm#`P=(J~AlaDuH%q2KJ(Y%W^8<54cI4tkOc@ zC4*>1<#`u`Q`6?OqTwDu#xwA(76Psxgj9^;4T9dI^PJn5W6Qhq4Ua9SZnybqCLP_v zvR;EE0I?Y^tS$R{_q(vQ-@^PKe-nngy7|i+m()Toy?)-<94TJvOR016|EL~I- zf&;ik>9uF_BW7Bxn}6dP_97L7L|Z_}!FkcL-rD*JvItiML-s4-WXV!ygKlM)caxim?FD_qRech>_QySMrb};nfDCKE9|%+&_IsbajnEyZ^Bms8 z)Y$gjIoxI$kky6sCt4ZSx6k7@YN)L8Wg4yWz#)S1{xhQUpTHq&NZ7$x@1*1r4 zKBZZzCcfIb4!U__43fUJa&vR>gDQ3dd7PHx_F>-4HJ4y{tl$DUer89wd35+G3;v5K z0xHS6@NsYT?oiofms%qGXSfZ}aaxV{c9UAP&AjYm^_liE(7Ui1z6MMTFE%d=)U)sa<|)sIy46X%mnFP+?Q`g?SylVWn{;3czZW1*O@(X;#5| z^nd6P9Mifd4YpkQ-iY$#_(?!f!s-{hA2}ohdecac3z2Kb^MXj_;5n}U1=$BC`2Qt( z=n*7%A$+O+cvJ`KhC7(EKF+{Knj#y3NzPzRnW89wvG+kI*SP7$J>^tmaM@duFzz@{ zyKWOE8-q1>x+P(K+%XDmcwfR;bW83p?p@0AeK+il`xM3^HrV{rq%3ph;(0=svh3Xx z9sSC(2vdwHV5B~|8G|+DmipMsKC?w{(T(I~b(AH2QT(g`3OW zE()W59dwkKZiv7%XE=7YFH`)M4eQQys|BX|V-cJY^;4K=49B3Ee(QIDS%h)N!!ak6kfbcH558*+BFF2)@5&;_%EB3A zS*tMim1IV~{bYOB;jNhbi4|U~LTEA_w-^ z&j3c0fUa^Z*&FpR29e`8r)llrV)7S4n>ZD)_rf_{&iFn0frGqe&fsgE-l z%c)8GxIX|H=?jZQv2eU6X+w+ZuyDL5>96Sb4(P9VN}Vm4BF<7ulJ=pa-;ZH`?b1Hx z@Xr29qVv)3II!QT?!!Q)8G|#cx_=qQUidLMPpF$PUKYnrm$Ez%JLaFHa#mw-9<`+} zW0B=fM*QER$ni&^e{=ClQWoq@+yq^lW^`$r!aoDO#Qi~KC3a%pDgvU zJC}|7rgTVI)cL@1k)_|6_2|by=cCjo_&GM}oP)^mvN%Vn{sd!C=PdojebbMD&gVrK zmjj*8MVMp^?95!HKK2lVS*kXVx&y`@0G$=V6}Bu4ZFQz>Ecp_~`ipi;-i5J#$9-kV zw=mTh_US1Mzddq~mJeb4VG7%D6NVm)foH;-M+yRCd#ej)uw|TqycmxHg!+^sj6ZNe zeM%R`{iD#QMeF0ygfQMq7RI9qVZ4v?)fclGgFY>nFnmmtXwR4J%Xk7>o&$`%@JkL8 z28W1;GMh&eqMTw3?mfrj-528#kZ|@jy!c*BGX`U@F2Z zvx3ECW;jdb%5UF=v8Ps*-(H0=54*~5Z^C3_Fhf5*|7JKcj!5RO=i_uL(`fbEv(oZ- zU%r`O3}*Uz3$t2TXrITkGKQJ)n|$mZ9uLho!*4Itjpy0Po5{wYeI9SnH)G$> zHl~?rrmcl%0goT&i(0LPICqQ$&M!%{fdbEbA8*>2XE~k-nzrvQjI}i9g{F+P5a;N} zKP;A+v4qmJZyvv{w9Jh42JM^2XY0-Iv2f%WbaS7`H4Mh@2+@Xpy5Aa%MGTDeNouz+ z{@@zl)mLH6Z-8q?55oAp6w2z;9T*t*je|zdcST_QVFl*;UWBnb437Aoh2g#UN#B$a zX>^?!_aS4S_AU(lP7coXeL715!@Gxzd&{1M;ksfT_B{$?=ZrkZpVIu2u}HPl)%lDS zjGgP@EW31-V*zk*mRC-sN;oVHJvHaZs z#h099;~o3+M}JbA85@IEpTE8+X=bo~$6m(jbd7)pqu=9y&SeRlf5MnqmoTC#!#^Vq zInBl?&IhNI-DE7;3Rjh_2xAX05goN`9tI7J1@bDi*SE>nVKCY6`*{{Hjdw8aH-Hsm z-@Z)odwPtEUF1}IL`M5>zl8C-VXQpcbdQMoID>g?U%m`q!jzkP`0WrmeizI3xrMPv z{oKQEmoPrJK!5fqjAfo>pYB;0^Sh;`u&?r67S)}PviIrk3XI=@v3-g#ez%8pXWzd} zb>Cd9J9`y5?stp1ckjaZT^jm*ld?Q01kV)qQ{=dBE_7pW!uZ^Rc0Syvmfywmi_7Nc zX>TwX^AEE-jFB4sHNJfRz_QYd`7f++wB8hlloEXPr-bG+7;0k4x;e{j{`7lIgQ3^O z%~@rev;vIX9P>&09)+>DeB2Wpn=t;q4qhPJbSneK!gKKie?Hj(!;{K0W98bDFl^yK zTmCq|jO|eZXN+SPId<~JFjkw#)ukM+CM(|!&L;(6IBJ-ry&ShNcA7wo<+y}#FJX*` z;aT`%iZS^1a}kE#*p{kqioHw5;^ESkKZ7vr3%(62=d@!4!+jn-=gQ*|7$@E6i?7<4 hQ6G;$=rb68d*Q9a69_ccnfYtO{~vXoH3Fq>8UUTDEwTUr diff --git a/admin/charsets/mapfiles/stdenc.txt.gz b/admin/charsets/mapfiles/stdenc.txt.gz deleted file mode 100644 index 495e61c1cc42789f45cad767dad3af3a96924e0d..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 3190 zcmV-+42km}iwFp!6fa5u19Nm_Wo~0Gba-?Cl~~zw+d2|`M!o_Sza&+*BXPA-Q&YoD zHg6=+S4+03d4NPn;)Eg{X>y#wiSQ3dJjwg0_Nj{=RC|-m)uEHJ_V}eg)C)pC*#Yb zhxs-s`8uIh(Es})ze{2nb5UNV1Fc8to+Ge zds=%*Ya=hoZl5L;1jl*`xk~nl%qlK6g_LT_SXQ#wC7H^;*b{msmPwja59FIC87*Ze zD$02q@+A+~ylRuNrKK;We6;gCgRh;~WRh0TcQQ`Is|=l!3(3no#j*(U&<3qi!|xL+ z#Zs+G{#tECwvkv+EZ1^XC3muMd!NusGCt_>SUeyd2vR2dsx8~J4VqTGLEdPIn7d{J zrC=w1NWRMV$S3*28W6QwP(tt`6Dd5!Nm&)i@}ROoG*%U(Jf;u)P)g zVOtflHq- zBwY^l_x!A#DkBMM-Wzy-o0rvWRS-8g@u?6is%#6w-)ou4LZr0ADv1bqJ^I!1%etbJ z-%5$ny`)`Nms1HsT^U&((h7vcrh1_D*WO?g=_W6TxI3bANh?}DlB5K?i6d`s^F8f* z#R}0*U+%?9zHP9zzc^nVc3}70BM8jAP9OGLCBo(TTP~^^yREAI#}6M+eu}ib6iD>t zD&Kt&W%ePKcQVcQviMLv>?KwHu={YReQvVLZM93A2=bcF#~hYiqC#~H9kshuNu_b3 zqCJ1C%ZU=VPS0sykc3k<-_}u|H)6TpOSSW~r)`5bmARztzNWG^YZS|zl%h=$*u2Zh z3yGdc((wB-Hg9rc*==l$egwaHJ`G>?+fwwN?&!-AK5c~?q_ z-9taBCB1Lx0VdV{kd!C1#9+uOa&jW%HrmBL7T9&qQUOkvPx>laX#MiC20TXBKj$U| z_khsMfAL{blohQlm4aGLod#-N6)lSYt>MB&lCA#H{Cr8m@pq-cN;QAdnv{e;XMA?+cme&dYD({&=KUnPaHoOu=@mfhGkVT=@YNeRV`m;l6FzpPpXe2o zQ0#!w7(HkF&qXwUhWL4)oX5))7@g5W6D`JWFy*uGdP2WthusoKicJQH!RR^Tel!|6 zEhNrU>c23Xj2_aFVCn^v`O!`rW<_xVU@>~mxHBfm%$fM~v)GZnB$~g`di?>@YB=9lx{Mx*aI~1U;iZQXCXdl`#=U4fh67Yr;Jwc@#Ch}W_9mEIjKj$S zlWs|VBy#FB_E|&$)S#zkEnpg|JzR`Nd^V46>x3qG4C9c|gR!H~S8mHxlv}dsJ*I;- zes~?u`S)NN(Jz0=B8RQd^nPoLCUBo;ppvdJU284#FBnwat1&v$^+(IiG{C58OU)ft zgXuT)CWu-wAM+e0?d*+LWk*&s?sQ$s4Ato^5`-hg`EZC@MtULE@|x^ z(>+DA+3aF|<4lg#Pw5~DyU%n~G5B-gj9O~Qp9g`hr3XyMBCcrz6Rn;(*x=A3Ri=ha zAF53n%%1bT77cKV zm=Sb=z@-U5LuL%SK-ka`fy^E=dtD$%%q>8DW_I%FPY@L#jhUT%f(%Rn(wW)GC&<n89oDKGqaOVU&!zUpetr}@(F776`%n#JNfjD z4Br59nAypv?_~H6kjqT>*vw`mCDVYrQ^)%hApRvCeSXNQ>1d|MOwejd+BlsBPkO+T zV8=dS`ponnJ8Fl^WAifuW`bZ|IQ16e;VAgZ9S^Nsb-`7VtdfFGia-vTsaO_$;iFn% z4_Qo&d_|{6bn+`^_1Z{&*T|c2tUj|I$u=81qi52EPHJh)(oRE=v?U-qv-HytgD>hd1&G1y4!&SpfV;NI z><+#_k`91a%eWpzCes{aIy!??%)fg=m8Li*&Td=5d8&+ z%j{N&yv20%?S*I@x2^3l8>}G>nui_~trml&x)9htvme#xq@Sbo*a5RKa2}5Q;3zj$ zlE&%|)MpNg9ZoP$;CJ73;{0A6sx{`I^iQuL%^k$inS+wwMvIAmwBdxG;tPa^V~vA) z4{4ps|7_&Uup8I7dEywRX??TC_~GYpb`nGL5C)|97PLpb2OM7e16o^`bnq|X{D$8| z5h7ZrbZu6yZ03L&v!Gc~vuN4QMQa8xD8qEI@xHYo9}2qKtWb2iS2^H?a~sX((}=Da zM*%J=?o?^E#~kNabU#|SotjM-#-{#`%bX)oE^ec6LNQ$*2Ro-_e{)D^_%5$InTGSa z0}eH9;<>Be_)rT!`f!-zKl)IF``?|^BpkXu;@K^lqYA!KuogB_ zr9(b-=BkVNg!?r;WEP_>Yq;#Y>Z0XbUk4DQSZp?Q3D9txchyC!PT>nceN%UB=7N6X z(D#9fu$$^jAxJI@8H1#Q8s*Z>F`#=MUAdikG<^*vhZb`|$=h(`O{t?FZ?>Wkn?mf> ziZ$litvBr61LYp6?>o%BdQ!gV%f+CBH!9gnQ7X0t%pE)i`nzEi^>L8TT&ES3|Hjdy zwzw{H-Q%eLo29iE4IeLD(DWvnhTo$Jj&H$e6yDY!5oDSs`!XrPMJg`1c#FOmQo5de z2&uODL4E9?RSlUtd@5>P_r6Bc=se|tPS;cCbMSaBqXMbBG}YPzr5tZDe_|G^Lq%rI zvzP~7jUzuChG^=|vFOB6uRi6iQ%Ma)^F8K)Mm5ck^4u!(kajg&3UE3rB%IgP8o0yx36`IZwWL}`?P zhC9rwxdH`f#upHIN)`=uRe$iQKPar5{Q;4Y%m{Zn_%3k!Y-~4>y(9{`vQ+?99)-4qyv<4 z7>q-F-QdyG4=02SCqDJydXMKtyq3G9{_N2=`YhHtaZ% z5t;A}M;)GHw4ky~kRXi>J5E+F(~}<4Lj#5#N3EC1$=l@UZ20Qz^(-|xqV$Js*l}K; c-8j=*bvmVfup=p1rsbRe02*}KVp1Le0M_#+f&c&j diff --git a/admin/charsets/mapfiles/symbol.txt.gz b/admin/charsets/mapfiles/symbol.txt.gz deleted file mode 100644 index 07e35754e40063f628732a3061a2a5768185afd2..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4109 zcmV+o5c2OIiwFp;6fa5u19N$8VsC6Nba-?Cg;{HJ+RC#1Jo{Hn#b1)D*a3-$+56O~ ztEa6BAdUn(k6Y)1fH77@NE}Hxaen<-JtGN$(Y+~>*qSvxJ>9EU&xo5pZaAMud+{f4 z|1q}NTJZ37zs?fwq?>FTr#oI|e3i!dMbND3NB$!6BF<76(C&IPu#DD8`!VOeJBi$dft zVtZFxSU$%Ee~RG+{y*f|OS~0Z9u>Fvb^Ur_=>76pG@G%qw8-)@KJGu<@p(qZHc1rk z3m)Zy?;}8>f&%drm#HYQN|y5|edUJ;vo^;h%K71#AF@KweEu`a^C&H2QSj`EtP%D{ zoNlE(@#_HJ3-|^r@&1s+*aRnka^MW`q2UCO|*`axO|0e z9;a|+AC-uCv*kPPJ@K*$#xq=B3vn9fSxUC{(JmG6p6|srj^0G*BTNWhWC^(i$ZNA{ z85;gGMk?0QEAead9Hl!!4sFGg*p%^$sLcM1;YrFTJ-&@zDIBy(5g*DXZ9%hXc)X*y z!9`kIu>m32M?VDLWCw~TY>^MNYw1u7c%DWHS=z=$naAs+j7EfLQ^pX-z#g8Em;_598p&}>$*cE3*5FDm zZW|9pD?!^BAt^Bv7(C6lidICPoM*6tfAd|G#=oU|1)2N#EaU)%0FHu}1WvP4SY5f# zKly-{(fW2Pl6W6eWS?S@Y>PktxFHbd@B1HkyA)ocGt#}bhb`bfe^7SB)@#Fr}QQ6$3chBWMsdkVl8rLzD;ZV7{ld;2a zRHCH!ZO}*X8&Ztuyi>dQsH`dFI~;^8Bkdy6cU+saS9*?KNF$4Qm(r$-vrt$Wq%lVu z;4742cwEDF^cRieS6TdtV4a zb%!6NOCKtNQ3RB|^LWc*Awebrb;tKFsaPOs6FX&$0$8X3HppnZjVs-fp%KSCJ1zJZ zSK_=qOOKMcOXrG)3uMRg7vBQ!;c>}B?_pj@{sxBaS;mw*Uzg6@b^<8jVN02-+-sG1 z(K5uuSPAX;+?-}pZ&#^1*2=6|Z6?;wl+ zlpRL)g#REKQXokRQ9N>|WTw~CdJLZ%9xe>a!T*x!cy3hB=l-o3IL7BU0IkpPxxs#| zsWCH_ogF#{wt z<~Dwg_6PDK-O?&1)5dsa`SYdW%|mX4eCCi-v|r?%)Pd~WGkk9N)Nz-5VFXz0(Fr~B z2m&S2L_A5@gyD0;6+^DzRO{2U{+MY7`4ujmzzaWfAO0CjpO%fV!8|U0pi@1QO}J>% z9;d6Y*s} z3?Fd9pL+I++%A%+AUE_L(}@+f_uwu0cPH@i%WsiqG}dQ&zZvuAWIjuYD!RsWtr=N< zp-JUWIY(!@ej0fU9GX==<7h&o1Evp}QP*ElV4kvLPGdu+4^Ly>-!$D1AgWnJtV?m_BJn=bqeP8mk=|OgCf> zrv6;!Ajzaflj)SU(3yGlSRwXtGj1{6l8g$&+vTG%uk)1P7);|f(MY>`s(kS%DV-diBLZt|pml*wXGvHSjR{a= z%m#WF)Oz$Nyw5S&9I(Nl3urr2Y19@;NmbArDX=%U0%wLwY{p;++a7iqau%Vd66PF= zSf)!iU~JSiVIf^yC>M1$7?8*(>}@^``plP;j=OQe@csEs5U z4HWXTGs`;b{YH(Hjs(WXvK1MlMSpcFj|03;Aym9ZzbAd1G@`7 zTahju31+i_(*>IoY%XCg8@OFCAGH<8O!=s+TxF`qhP}>A$wbLK-LqjQmu1wb`8-zy z?XzJgmxD*Dli)ccpw5P!Oh$dm?1%AAX5SdFVJDlH28Cc5Q4EYB8+NjF)v$Hdu+`Go z@Wj?|h7MfAU2l%LwJQa=LVPeLY}iR#f95D?b~5@a zMgJ>B-$3*``HT%wmI|3BEM;^7zpE^Lmr3dkO*S;^9vwo#aBeUI!}{z{<*#v?`yoo% zs5K4EWoXr>3!G6@@4*QdXJ%6Mq0NSN)5yDw)!m%(Ll#yGq|N%Q8tOsN0iIrikUf_T ziN#a@3!kd~aZI;3hHPj(_ud(@5s~)tD2YdTME8J1{NnNsfS8zlHtJu`ZY{!5CBml0 zM%r~~CBbXOaBIv)`gNcZ;Ehx_bHGM}>#$mWx0S@2*wXMi^dzw2MA;D=bx>Bx>p?l7 zv(flEtQOZ@C9Wp6bl>5C^i=KKoUqa4I;;}bxDr-u=tM<0b&^&1Mnz;AY-CWXejjZd?T2PZpPy%fIjT9w)iqp7!{iD~%G1(wSO>vK&U$pAe zF3Dn&wK91oA>6z_+nO}izv!8ScGkeUG zms*F|RTFP3cIp<2Mr#uF=<0oYcA2INxVlhlbdxpZ9oJu(Q>WovAvQA38scnLqIJ5f zozt$mvemacd(2E?)oe9gdW$KFPw}r-{-lf#$tzLIW~O}q5%>!~AW&`bkZ1D!d`4db z;4Y*wlUTMul09H-&vhMoJAq%=je55pCENJv2^-P?mIPZ(r>dHdNg_xRTsU@rM)xXW zF@1?bdqqHrQ*(dW-XFaSR8^(n2>C6w$ETMho z*{`}paS%0$RgZq)eWzDAI5|zH-a@@`5lIq56AC(C0cf|iOtPVU%#yTt5qa4hv@i?X zbbaA zhw`-$)IGEbv&K?B;d$stDV7pS?`B0UvYNpxV&-bDhL5Rwey=l&2pO*E1)#I!zFSoX zW*_MvxyU^>WSqk;N)%TEoWa{u2Fx-ms^f;eG8^k)dvRP>D2-W`G;F?Ey@rgKWw#+6 zD_8Iyl0>9*rt+nRGKro|Z+2-I;c{!Y=I1CX!v?7Jm@O$bf0&ZJDBUGgd%ZEUiCl97 zl#$wm3kXedM>v++#HGM_@aV-Q5=sJqoCTgMJ>AjUSp+DLpXw?a*%M|HtIl7YHqqO%UCx zOI_gmG+y1ZFb=-j@+*zmm@{ElU$#_!wO+WiJ#(33bj)kH*qYpO((N&);|Uzb=AY*T?y7rRA=; zaMsnBV_%;%^X&GdeY`!*(wY1&DEf z$>^H-mho>~MZV0g>6e^;2DoUdM5w?$Vu?m diff --git a/admin/charsets/mule-charsets.el b/admin/charsets/mule-charsets.el deleted file mode 100644 index 5ae51b3dcfd..00000000000 --- a/admin/charsets/mule-charsets.el +++ /dev/null @@ -1,57 +0,0 @@ -;; mule-charsets.el -- Generate Mule-orignal charset maps. -;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -;; National Institute of Advanced Industrial Science and Technology (AIST) -;; Registration Number H13PRO009 - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - - -(if (not (or (and (= emacs-major-version 21) (= emacs-minor-version 4)) - (= emacs-major-version 22))) - (error "Use Emacs of version 21.4 or any of version 22")) - -(defun func (start end) - (while (<= start end) - (let ((split (split-char start)) - (unicode (encode-char start 'ucs))) - (if unicode - (if (nth 2 split) - (insert (format "0x%02X%02X 0x%04X\n" - (nth 1 split) (nth 2 split) unicode)) - (insert (format "0x%02X 0x%04X\n" (nth 1 split) unicode))))) - (setq start (1+ start)))) - -(defconst charset-alist - '(("MULE-ethiopic.map" . ethiopic) - ("MULE-ipa.map" . ipa) - ("MULE-is13194.map" . indian-is13194) - ("MULE-sisheng.map" . chinese-sisheng) - ("MULE-tibetan.map" . tibetan) - ("MULE-lviscii.map" . vietnamese-viscii-lower) - ("MULE-uviscii.map" . vietnamese-viscii-upper))) - -(defconst header - (format - "# Generated by running amdin/charsets/mule-charsets.el in Emacs %d.%d.\n" - emacs-major-version emacs-minor-version)) - -(dolist (elt charset-alist) - (with-temp-buffer - (insert header) - (map-charset-chars 'func (cdr elt)) - (write-file (car elt)))) - -;;; arch-tag: 515989d7-2e2d-41cc-9163-05ad472fede4 diff --git a/admin/check-doc-strings b/admin/check-doc-strings deleted file mode 100755 index daed2926b20..00000000000 --- a/admin/check-doc-strings +++ /dev/null @@ -1,304 +0,0 @@ -: #-*- Perl -*- -eval 'exec perl -w -S $0 ${1+"$@"}' # Portability kludge - if 0; - -# Author: Martin Buchholz -# This program is in the public domain. - -use strict; -use POSIX; - -(my $myName = $0) =~ s@.*/@@; my $usage=" -Usage: $myName - -Finds DOCSTRING arg mismatches between -formal parameters, docstrings, and lispref texi. - -This program is in the public domain.\n"; - -die $usage if @ARGV; -die $usage unless -r "src/alloc.c" && -d "CVS" && -d "lisp"; - -my %texi_funtype; -my %texi_arglist; - -my %code_funtype; -my %code_arglist; - -sub FileContents { - local $/ = undef; - open (FILE, "< $_[0]") or die "$_[0]: $!"; - return scalar ; -} - -sub Show_details { - my ($show_details, $function, $parms, $docstring) = @_; - if ($show_details) { - print "function = $function $parms\n$docstring\n", "-" x 70, "\n"; - } -} - -sub Check_texi_function { - my ($function, $funtype, $docstring, @parms) = @_; - my %docstring_parm; - my %docstring_word; - my %arglist_parm; - my $show_details = 0; - - if (exists $texi_funtype{$function}) { - print "duplicate texidoc: $function @parms\n"; - return; # later definition likely bogus package def - } - - $texi_funtype{$function} = $funtype; - $texi_arglist{$function} = "@parms"; - - foreach my $parm (@parms) { - next if $parm eq '&optional' || $parm eq '&rest'; - $arglist_parm{$parm} = 1; - } - - foreach my $parm ($docstring =~ /\@var{([^{}]+)}/g) { - $docstring_parm{$parm} = 1; - } - - foreach my $hit ($docstring =~ /[^\`]\`[A-Za-z-]+\'/g) - { - print "texi \@code missing: $function: $hit\n"; - $show_details = 1; - } - - # (my $raw_docstring = $docstring) =~ s/\@var{[^{}]+}//g; - # $raw_docstring =~ s/[^a-zA-Z_-]+/ /g; - # foreach my $word (split (' ', $raw_docstring)) { - # if ($word =~ /^[A-Z][A-Z-]+$/) { - # print "Missing \@var: $function: $word\n"; - # } - # } - - foreach my $parm (keys %docstring_parm) { - if (! exists $arglist_parm{$parm}) { - print "bogus texi parm: $function: $parm\n"; - $show_details = 1; - } - } - - foreach my $parm (keys %arglist_parm) { - if (! exists $docstring_parm{$parm}) { - print "undocumented texi parm: $function: $parm\n"; - $show_details = 1; - } - } - - Show_details $show_details, $function, "@parms", $docstring; -} - -sub Check_function { - my ($function, $funtype, $docstring, @parms) = @_; - my %docstring_parm; - my %arglist_parm; - my $show_details = 0; - - if (exists $code_funtype{$function}) { - print "duplicate codedef: $function @parms\n"; - return; # later definition likely bogus package def - } - - $code_funtype{$function} = $funtype; - $code_arglist{$function} = "@parms"; - #foreach my $parm ($parms =~ /\b[a-z0-9-]{3,}\b/g) { - # $arglist_parm{$parm} = 1; - #} - foreach my $parm (@parms) { - next if $parm eq '&optional' || $parm eq '&rest'; - $arglist_parm{$parm} = 1; - } - my $doc_tmp = $docstring; - $doc_tmp =~ s/[^A-Za-z0-9_-]/ /g; - foreach my $parm (split (' ', $doc_tmp)) { - if ($parm =~ /^[A-Z][A-Z0-9-]*$/) { - next if $parm =~ /I18N/; - next if $parm =~ /M17N/; - $parm =~ tr[A-Z][a-z]; - $docstring_parm{$parm} = 1; - } - } - # foreach my $parm ($docstring =~ /\b[A-Z0-9-]{1,}\b/g) { - # next if $parm =~ /-$/; - # $parm =~ tr[A-Z][a-z]; - # $docstring_parm{$parm} = 1; - # } - foreach my $parm (keys %docstring_parm) { - next if $parm eq 'tty'; - next if $parm eq 'fsf'; - next if $parm eq 'note'; - next if $parm eq 'warning'; - next if $parm eq 'bug'; - next if $parm eq 'ascii'; - next if $parm eq 'iso'; - next if $parm eq 'and'; - next if $parm eq 'absolutely'; - next if $parm eq 'doc'; - next if $parm eq 'user'; - next if $parm eq 'not'; - next if $parm eq 'must'; - next if $parm eq 'nil'; - next if $parm eq 'esc'; - next if $parm eq 'lfd'; - next if $parm eq 'gpm'; - next if $parm eq 'primary'; - next if $parm eq 'secondary'; - next if $parm eq 'clipboard'; - next if length $parm < 3; - if (! exists $arglist_parm{$parm}) { - print "bogus parm: $function: $parm\n"; - $show_details = 1; - } - } - foreach my $parm (keys %arglist_parm) { - if (! exists $docstring_parm{$parm}) { - print "Undocumented parm: $function: $parm\n"; - $show_details = 1; - } - } - - if ($docstring !~ /[\]}!\)\.]\s*\Z/m && - $docstring =~ /\S/ && - $docstring !~ /Keywords supported/) - { - print "Missing trailing period: $function\n"; - $show_details = 1; - } - - if (exists $texi_arglist{$function} - and "@parms" ne $texi_arglist{$function} - and not ("@parms" eq 'int nargs Lisp-Object *args' - && $texi_arglist{$function} =~ /&rest/)) { - my @texi_parms = split (' ', $texi_arglist{$function}); - my @a = ("@parms" =~ /&optional/g); - my @b = ("@parms" =~ /&rest/g); - my @c = ("@texi_parms" =~ /&optional/g); - my @d = ("@texi_parms" =~ /&rest/g); - if (@parms != @texi_parms - || (@a != @c) || (@b != @d)) { - print "serious mismatch: $function: @parms --- @texi_parms\n"; - } else { - print "texi mismatch: $function: @parms --- $texi_arglist{$function}\n"; - } - $show_details = 1; - } - - if (exists $texi_funtype{$function} - && $texi_funtype{$function} ne $funtype) { - print "interactiveness mismatch: $function: $funtype --- $texi_funtype{$function}\n"; - $show_details = 1; - } - - Show_details $show_details, $function, "@parms", $docstring; -} - -my $lisprefdir; -if (-d "man/lispref") { $lisprefdir = "man/lispref"; } -elsif (-d "lispref") { $lisprefdir = "lispref"; } -else { die "Can't find lispref texi directory.\n"; } - -open (FIND, "find $lisprefdir -name '*.texi' -print |") or die; -while (my $file = ) { - my @matches = ((FileContents $file) =~ - /\@(def(?:fn|un))([^\n]+)\n(.*?)\n\@end def(?:un|fn)/sgo); - # /^\@(def(?:un|fn))\s+(.*)\n([.|\n]*?)^\@end def(?:un|fn)\n/mgo); - while (@matches) { - my ($defform, $defn, $docstring) = splice (@matches, 0, 3); - #print "defform = $defform\n"; - #print "defn = $defn\n"; - #print "docstring = $docstring\n"; - my ($function, @parms, $funtype); - if ($defform eq 'defun') { - ($funtype, $function, @parms) = ('Function', split (' ', $defn)); - } else { - die unless $defform eq 'deffn'; - ($funtype, $function, @parms) = split (' ', $defn); - } - next if $funtype eq '{Syntax' or $funtype eq '{Prefix'; - - Check_texi_function $function, $funtype, $docstring, @parms; - } -} - -open (FIND, "find src -name '*.c' -print |") or die; -while (my $file = ) { - my @matches = - ((FileContents $file) =~ - /\bDEFUN\s*\(\s*\"((?:[^\\\"]|\\.)+)\"\s*,\s*\S+\s*,\s*(\S+)\s*,\s*(\S+)\s*,\s*((?:0|\"(?:(?:[^\\\"]|\\.)*)\"))\s*,\s*\/\*(.*?)\*\/\s*\(([^()]*)\)\)/sgo); - while (@matches) { - my ($function, $minargs, $maxargs, $interactive, $docstring, $parms) = splice (@matches, 0, 6); - $docstring =~ s/^\n+//s; - $docstring =~ s/\n+$//s; - $parms =~ s/,/ /g; - my @parms = split (' ',$parms); - for (@parms) { tr/_/-/; s/-$//; } - if ($parms !~ /Lisp_Object/) { - if ($minargs < @parms) { - if ($maxargs =~ /^\d+$/) { - die unless $maxargs eq @parms; - splice (@parms, $minargs, 0, '&optional'); - } - } - } - my $funtype = ($interactive =~ /\"/ ? 'Command' : 'Function'); - Check_function $function, $funtype, $docstring, @parms; - } -} - -my @pkgs; -if (-d "../xemacs-packages") { - @pkgs = qw (libs/edebug libs/xemacs-base comm/eudc oa/edit-utils); -} else { - @pkgs = (); -} -for (@pkgs) { s@^@../xemacs-packages/@; } -open (FIND, "find lisp @pkgs -name '*.el' -print |") or die; -while (my $file = ) { - my $contents = FileContents $file; - $contents =~ s/(?:\s|;);.*//mog; - my @matches = - ($contents =~ - /\((def(?:un|subst|macro))\s+(\S+)\s+\(([^()]*)\)\s+\"((?:[^\\\"]|\\.)+)\"(.*?)\)/sgo); - while (@matches) { - my ($defform, $function, $parms, $docstring, $code_fragment) = splice (@matches, 0, 5); - - my $funtype = - $defform eq 'defmacro' ? 'Macro' : - $code_fragment =~ /^\s*\(interactive\b/so ? 'Command' : - 'Function'; - - $docstring =~ s/^\n+//s; - $docstring =~ s/\n+$//s; - - my @parms = split (' ', $parms); - - Check_function $function, $funtype, $docstring, @parms; - } -} - -open (FIND, "find lisp @pkgs -name '*.el' -print |") or die; -while (my $file = ) { - my $contents = FileContents $file; - $contents =~ s/(?:\s|;);.*//mog; - - my @matches = ($contents =~ /^\((?:defalias|fset|define-function)\s+\'([A-Za-z0-9_-]+)\s+\'([A-Za-z0-9_-]+)/mog); - while (@matches) { - my ($alias, $aliasee) = splice (@matches, 0, 2); - print "alias $alias aliasee $aliasee\n"; - if (exists $code_funtype{$aliasee}) { $code_funtype{$alias} = $code_funtype{$aliasee}; } - if (exists $code_arglist{$aliasee}) { $code_arglist{$alias} = $code_arglist{$aliasee}; } - } -} - -foreach my $fun (sort keys %texi_funtype) { - if (not exists $code_funtype{$fun}) { - print "nuke-this-doc: $fun $texi_funtype{$fun}\n"; - } -} - -# arch-tag: e75331f5-5d1b-4393-ad5b-b0f87b5d47b0 diff --git a/admin/cus-test.el b/admin/cus-test.el deleted file mode 100644 index 6863163ec4e..00000000000 --- a/admin/cus-test.el +++ /dev/null @@ -1,529 +0,0 @@ -;;; cus-test.el --- tests for custom types and load problems - -;; Copyright (C) 1998, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -;; Free Software Foundation, Inc. - -;; Author: Markus Rost -;; Maintainer: Markus Rost -;; Created: 13 Sep 1998 -;; Keywords: maint - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; This file provides simple tests to detect custom options with -;; incorrect customization types and load problems for custom and -;; autoload dependencies. -;; -;; The basic tests can be run in batch mode. Invoke them with -;; -;; src/emacs -batch -l admin/cus-test.el -f cus-test-opts -;; -;; src/emacs -batch -l admin/cus-test.el -f cus-test-deps -;; -;; src/emacs -batch -l admin/cus-test.el -f cus-test-libs -;; -;; src/emacs -batch -l admin/cus-test.el -f cus-test-noloads -;; -;; in the emacs source directory. -;; -;; For interactive use: Load this file. Then -;; -;; M-x cus-test-apropos REGEXP RET -;; -;; checks the options matching REGEXP. In particular -;; -;; M-x cus-test-apropos RET -;; -;; checks all options. The detected options are stored in the -;; variable `cus-test-errors'. -;; -;; Only those options are checked which have been already loaded. -;; Therefore `cus-test-apropos' is more efficient after loading many -;; libraries. -;; -;; M-x cus-test-load-custom-loads -;; -;; loads all (!) custom dependencies and -;; -;; M-x cus-test-load-libs -;; -;; loads all (!) libraries with autoloads. -;; -;; Options with a custom-get property, usually defined by a :get -;; declaration, are stored in the variable -;; -;; `cus-test-vars-with-custom-get' -;; -;; Options with a state of 'changed ("changed outside the customize -;; buffer") are stored in the variable -;; -;; `cus-test-vars-with-changed-state' -;; -;; These lists are prepared just in case one wants to investigate -;; those options further. -;; -;; The command `cus-test-opts' tests many (all?) custom options. -;; -;; The command `cus-test-deps' is like `cus-test-load-custom-loads' -;; but reports about load errors. -;; -;; The command `cus-test-libs' runs for all libraries with autoloads -;; separate emacs processes of the form "emacs -batch -l LIB". -;; -;; The command `cus-test-noloads' returns a list of variables which -;; are somewhere declared as custom options, but not loaded by -;; `custom-load-symbol'. -;; -;; Some results from October 2002: -;; -;; 4523 options tested -;; The following variables might have problems: -;; ps-mule-font-info-database-default -;; grep-tree-command -;; grep-find-command -;; -;; 288 features required -;; 10 files loaded -;; The following load problems appeared: -;; (killing x-win (file-error Cannot open load file x-win)) -;; Symbol faces has loaddefs as custom dependency -;; (reftex-index-support reftex-vars (void-function reftex-set-dirty)) -;; (eshell-script em-script (void-variable eshell-directory-name)) -;; (pcomplete em-cmpl (void-function eshell-under-windows-p)) -;; (eshell-ext esh-ext (void-function eshell-under-windows-p)) -;; ... -;; -;; 422 libraries had no load errors -;; The following load problems appeared: -;; (eudc-export error 255) -;; (ada-xref error 255) -;; (ada-stmt error 255) -;; -;; The following options were not loaded by custom-load-symbol: -;; edt-bottom-scroll-margin -;; edt-keep-current-page-delimiter -;; edt-top-scroll-margin -;; edt-use-EDT-control-key-bindings -;; edt-word-entities -;; grep-find-use-xargs -;; master-mode-hook -;; outline-level -;; outline-minor-mode-hook -;; refill-mode-hook - - -;;; Code: - -;;; Workarounds. For a smooth run and to avoid some side effects. - -(defvar cus-test-after-load-libs-hook nil - "Used to switch off undesired side effects of loading libraries.") - -(defvar cus-test-skip-list nil - "List of variables to disregard by `cus-test-apropos'.") - -(defvar cus-test-libs-noloads nil - "List of libraries not to load by `cus-test-load-libs'.") - -;; The file eudc-export.el loads libraries "bbdb" and "bbdb-com" which -;; are not part of GNU Emacs: (locate-library "bbdb") => nil -;; We avoid the resulting errors from loading eudc-export.el: -(provide 'bbdb) -(provide 'bbdb-com) - -;; This avoids a hang of `cus-test-apropos' in 21.2. -;; (add-to-list 'cus-test-skip-list 'sh-alias-alist) - -;; Loading dunnet in batch mode leads to a Dead end. -(let (noninteractive) (load "dunnet")) -(add-to-list 'cus-test-libs-noloads "dunnet") - -;; Never Viperize. -(setq viper-mode nil) - -;; Don't create a file `save-place-file'. -(eval-after-load "saveplace" - '(remove-hook 'kill-emacs-hook 'save-place-kill-emacs-hook)) - -;; Don't create a file `abbrev-file-name'. -(setq save-abbrevs nil) - -;; Avoid compile logs from adviced functions. -(eval-after-load "bytecomp" - '(setq ad-default-compilation-action 'never)) - - -;;; Main code: - -;; We want to log all messages. -(setq message-log-max t) - -(require 'cus-edit) -(require 'cus-load) - -(defvar cus-test-errors nil - "List of problematic variables found by `cus-test-apropos'.") - -(defvar cus-test-tested-variables nil - "List of options tested by last call of `cus-test-apropos'.") - -;; I haven't understood this :get stuff. The symbols with a -;; custom-get property are stored here. -(defvar cus-test-vars-with-custom-get nil - "Set by `cus-test-apropos' to a list of options with :get property.") - -(defvar cus-test-vars-with-changed-state nil - "Set by `cus-test-apropos' to a list of options with state 'changed.") - -(defvar cus-test-deps-errors nil - "List of require/load problems found by `cus-test-deps'.") - -(defvar cus-test-deps-required nil - "List of dependencies required by `cus-test-deps'. -Only unloaded features will be require'd.") - -(defvar cus-test-deps-loaded nil - "List of dependencies loaded by `cus-test-deps'.") - -(defvar cus-test-libs-errors nil - "List of load problems found by `cus-test-load-libs' or `cus-test-libs'.") - -(defvar cus-test-libs-loaded nil - "List of files loaded by `cus-test-load-libs' or `cus-test-libs'.") - -(defvar cus-test-vars-not-cus-loaded nil - "A list of options not loaded by `custom-load-symbol'. -Set by `cus-test-noloads'.") - -;; (defvar cus-test-vars-cus-loaded nil -;; "A list of options loaded by `custom-load-symbol'.") - -(defun cus-test-apropos (regexp) - "Check the options matching REGEXP. -The detected problematic options are stored in `cus-test-errors'." - (interactive "sVariable regexp: ") - (setq cus-test-errors nil) - (setq cus-test-tested-variables nil) - (mapc - (lambda (symbol) - (push symbol cus-test-tested-variables) - ;; Be verbose in case we hang. - (message "Cus Test running...%s %s" - (length cus-test-tested-variables) symbol) - (condition-case alpha - (let* ((type (custom-variable-type symbol)) - (conv (widget-convert type)) - (get (or (get symbol 'custom-get) 'default-value)) - values - mismatch) - (when (default-boundp symbol) - (push (funcall get symbol) values) - (push (eval (car (get symbol 'standard-value))) values)) - (if (boundp symbol) - (push (symbol-value symbol) values)) - ;; That does not work. - ;; (push (widget-get conv :value) values) - - ;; Check the values - (mapc (lambda (value) - (unless (widget-apply conv :match value) - (setq mismatch 'mismatch))) - values) - - ;; Store symbols with a custom-get property. - (when (get symbol 'custom-get) - (add-to-list 'cus-test-vars-with-custom-get symbol)) - - ;; Changed outside the customize buffer? - ;; This routine is not very much tested. - (let ((c-value - (or (get symbol 'customized-value) - (get symbol 'saved-value) - (get symbol 'standard-value)))) - (and (consp c-value) - (boundp symbol) - (not (equal (eval (car c-value)) (symbol-value symbol))) - (add-to-list 'cus-test-vars-with-changed-state symbol))) - - (if mismatch - (push symbol cus-test-errors))) - - (error - (push symbol cus-test-errors) - (message "Error for %s: %s" symbol alpha)))) - (cus-test-get-options regexp)) - (message "%s options tested" - (length cus-test-tested-variables)) - (cus-test-errors-display)) - -(defun cus-test-get-options (regexp) - "Return a list of custom options matching REGEXP." - (let (found) - (mapatoms - (lambda (symbol) - (and - (or - ;; (user-variable-p symbol) - (get symbol 'standard-value) - ;; (get symbol 'saved-value) - (get symbol 'custom-type)) - (string-match regexp (symbol-name symbol)) - (not (member symbol cus-test-skip-list)) - (push symbol found)))) - found)) - -(defun cus-test-errors-display () - "Report about the errors found by cus-test." - (with-output-to-temp-buffer "*cus-test-errors*" - (set-buffer standard-output) - (insert (format "Cus Test tested %s variables.\ - See `cus-test-tested-variables'.\n\n" - (length cus-test-tested-variables))) - (if (not cus-test-errors) - (insert "No errors found by cus-test.") - (insert "The following variables seem to have problems:\n\n") - (dolist (e cus-test-errors) - (insert (symbol-name e) "\n"))))) - -(defun cus-test-load-custom-loads () - "Call `custom-load-symbol' on all atoms." - (interactive) - (mapatoms 'custom-load-symbol) - (run-hooks 'cus-test-after-load-libs-hook)) - -(defun cus-test-load-libs () - "Load the libraries with autoloads. -Don't load libraries in `cus-test-libs-noloads'." - (interactive) - (setq cus-test-libs-errors nil) - (setq cus-test-libs-loaded nil) - (mapc - (lambda (file) - (condition-case alpha - (unless (member file cus-test-libs-noloads) - (load file) - (push file cus-test-libs-loaded)) - (error - (push (cons file alpha) cus-test-libs-errors) - (message "Error for %s: %s" file alpha)))) - (cus-test-get-autoload-deps)) - (message "%s libraries loaded successfully" - (length cus-test-libs-loaded)) - (if (not cus-test-libs-errors) - (message "No load problems encountered") - (message "The following load problems appeared:") - (cus-test-message cus-test-libs-errors)) - (run-hooks 'cus-test-after-load-libs-hook)) - -(defun cus-test-get-autoload-deps () - "Return the list of libraries with autoloads." - (with-temp-buffer - (insert-file-contents (locate-library "loaddefs")) - ;; This is from `customize-option'. - (let (deps file) - (while - (search-forward "\n;;; Generated autoloads from " nil t) - (goto-char (match-end 0)) - (setq file (buffer-substring (point) - (progn (end-of-line) (point)))) - (setq file (file-name-nondirectory file)) - (string-match "\\.el\\'" file) - (setq file (substring file 0 (match-beginning 0))) - (setq deps (nconc deps (list file)))) - deps))) - -(defun cus-test-message (list) - "Print the members of LIST line by line." - (dolist (m list) (message "%s" m))) - - -;;; The routines for batch mode: - -(defun cus-test-opts () - "Test custom options. -This function is suitable for batch mode. E.g., invoke - - src/emacs -batch -l admin/cus-test.el -f cus-test-opts - -in the Emacs source directory." - (interactive) - (message "Running %s" 'cus-test-load-libs) - (cus-test-load-libs) - (message "Running %s" 'cus-test-load-custom-loads) - (cus-test-load-custom-loads) - (message "Running %s" 'cus-test-apropos) - (cus-test-apropos "") - (if (not cus-test-errors) - (message "No problems found") - (message "The following options might have problems:") - (cus-test-message cus-test-errors))) - -(defun cus-test-deps () - "Run a verbose version of `custom-load-symbol' on all atoms. -This function is suitable for batch mode. E.g., invoke - - src/emacs -batch -l admin/cus-test.el -f cus-test-deps - -in the Emacs source directory." - (interactive) - (setq cus-test-deps-errors nil) - (setq cus-test-deps-required nil) - (setq cus-test-deps-loaded nil) - (mapatoms - ;; This code is mainly from `custom-load-symbol'. - (lambda (symbol) - (let ((custom-load-recursion t)) - (dolist (load (get symbol 'custom-loads)) - (cond - ((symbolp load) - ;; (condition-case nil (require load) (error nil)) - (condition-case alpha - (unless (featurep load) - (require load) - (push (list symbol load) cus-test-deps-required)) - (error - (push (list symbol load alpha) cus-test-deps-errors) - (message "Require problem: %s %s %s" symbol load alpha)))) - ((equal load "loaddefs") - (push - (message "Symbol %s has loaddefs as custom dependency" symbol) - cus-test-deps-errors)) - ;; This is subsumed by the test below, but it's much - ;; faster. - ((assoc load load-history)) - ;; This was just - ;; (assoc (locate-library load) load-history) - ;; but has been optimized not to load locate-library - ;; if not necessary. - ((let ((regexp (concat "\\(\\`\\|/\\)" (regexp-quote load) - "\\(\\'\\|\\.\\)")) - (found nil)) - (dolist (loaded load-history) - (and (stringp (car loaded)) - (string-match regexp (car loaded)) - (setq found t))) - found)) - ;; Without this, we would load cus-edit recursively. - ;; We are still loading it when we call this, - ;; and it is not in load-history yet. - ((equal load "cus-edit")) - ;; This would ignore load problems with files in - ;; lisp/term/ - ;; ((locate-library (concat term-file-prefix load))) - (t - ;; (condition-case nil (load load) (error nil)) - (condition-case alpha - (progn - (load load) - (push (list symbol load) cus-test-deps-loaded)) - (error - (push (list symbol load alpha) cus-test-deps-errors) - (message "Load Problem: %s %s %s" symbol load alpha)))) - ))))) - (message "%s features required" - (length cus-test-deps-required)) - (message "%s files loaded" - (length cus-test-deps-loaded)) - (if (not cus-test-deps-errors) - (message "No load problems encountered") - (message "The following load problems appeared:") - (cus-test-message cus-test-deps-errors)) - (run-hooks 'cus-test-after-load-libs-hook)) - -(defun cus-test-libs () - "Load the libraries with autoloads in separate processes. -This function is useful to detect load problems of libraries. -It is suitable for batch mode. E.g., invoke - - src/emacs -batch -l admin/cus-test.el -f cus-test-libs - -in the Emacs source directory." - (interactive) - (with-temp-buffer - (setq cus-test-libs-errors nil) - (setq cus-test-libs-loaded nil) - (cd source-directory) - (if (not (file-executable-p "src/emacs")) - (error "No Emacs executable in %ssrc" default-directory)) - (mapc - (lambda (file) - (condition-case alpha - (let (fn cmd status) - (setq fn (locate-library file)) - (if (not fn) - (error "Library %s not found" file)) - (setq cmd (concat "src/emacs -batch -l " fn)) - (setq status (call-process shell-file-name nil nil nil - shell-command-switch cmd)) - (if (equal status 0) - (message "%s" file) - (error "%s" status)) - (push file cus-test-libs-loaded)) - (error - (push (cons file alpha) cus-test-libs-errors) - (message "Error for %s: %s" file alpha)))) - (cus-test-get-autoload-deps)) - (message "Default Directory: %s" default-directory) - (message "%s libraries had no load errors" - (length cus-test-libs-loaded)) - (if (not cus-test-libs-errors) - (message "No load problems encountered") - (message "The following load problems appeared:") - (cus-test-message cus-test-libs-errors)) - (run-hooks 'cus-test-after-load-libs-hook))) - -(defun cus-test-noloads () - "Find custom options not loaded by `custom-load-symbol'. -Calling this function after `cus-test-load-libs' is not meaningful. -It is suitable for batch mode. E.g., invoke - - src/emacs -batch -l admin/cus-test.el -f cus-test-noloads - -in the Emacs source directory." - (interactive) - (let (cus-loaded) - - (message "Running %s" 'cus-test-load-custom-loads) - (cus-test-load-custom-loads) - (setq cus-loaded - (cus-test-get-options "")) - - (message "Running %s" 'cus-test-load-libs) - (cus-test-load-libs) - (setq cus-test-vars-not-cus-loaded - (cus-test-get-options "")) - - (dolist (o cus-loaded) - (setq cus-test-vars-not-cus-loaded - (delete o cus-test-vars-not-cus-loaded))) - - (if (not cus-test-vars-not-cus-loaded) - (message "No options not loaded by custom-load-symbol found") - (message "The following options were not loaded by custom-load-symbol:") - (cus-test-message - (sort cus-test-vars-not-cus-loaded 'string<))))) - -;; And last but not least a quiz: -;; -;; Evaluation of the form (customize-option 'debug-on-error) yields a -;; *Customize* buffer with a mismatch mess. Why? - -(provide 'cus-test) - -;;; arch-tag: a4991a31-548d-48fb-8ba1-1ebbe68eb2e7 -;;; cus-test.el ends here diff --git a/admin/diff-tar-files b/admin/diff-tar-files deleted file mode 100755 index f24723343f7..00000000000 --- a/admin/diff-tar-files +++ /dev/null @@ -1,45 +0,0 @@ -#! /bin/sh - -# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -if [ $# != 2 ]; then - cat < $old_tmp -tar tzf $new_tar | sed -e 's,^[^/]*,,' | sort > $new_tmp -diff -u $old_tmp $new_tmp -rm -f $new_tmp $old_tmp - - -# arch-tag: ef2c96e2-ea67-4668-925c-d9a6f3d205cf diff --git a/admin/emacs-pretesters b/admin/emacs-pretesters deleted file mode 100644 index 4ea98c16dfc..00000000000 --- a/admin/emacs-pretesters +++ /dev/null @@ -1,219 +0,0 @@ -Here are the guidelines for being an Emacs pretester. -If you would like to do this, say so, and I'll add you to -the pretest list. - - - Information for Emacs Pretesters - -The purpose of Emacs pretesting is to verify that the new Emacs -distribution, about to be released, works properly on your system *with -no change whatever*, when installed following the precise -recommendations that come with the Emacs distribution. - -Here are some guidelines on how to do pretesting so as to make it -helpful. All of them follow from common sense together with the -nature of the purpose and the situation. - -Please save this file, and reread it when a new series of pretests -starts. - -* Get the pretest from gnu/emacs/pretest/emacs-MM.0.NN.tar.gz -on alpha.gnu.org. - -* After a few days of testing, if there are no problems, please report -that Emacs works for you and what configuration you are testing it on. - -* If you want to communicate with other pretesters, send mail to -emacs-pretesters@gnu.org. I don't use that mailing list when I send -to you because I've found that mailing lists tend to amplify random -noise into long discussions or even arguments, and that can waste a -lot of time. But when you have a reason to ask other pretesters for -help, you can do it that way. - -* It is absolutely vital that you report even the smallest change or -departure from the standard sources and procedure. - -Otherwise, you are not testing the same program that we asked you to -test. Testing a different program is usually of no use whatever. It -can even cause trouble, if you fail to tell us that you tested some -other program instead of what we are about to release. We might think -that Emacs works, when in fact it has not even been tried, and might -have a glaring fault. - -* Don't use a site-load.el file or a site-init.el file when you pretest. -Using either of those files means you are not testing Emacs as a typical -site would use it. - -Actually, it does no harm to test Emacs with such customizations *as -well as* testing it "out of the box". Anything you do that could find -a bug is useful, as long as you make sure we know exactly what you -did. The important point is that testing with local changes is no -substitute for testing Emacs exactly as it is distributed. - -* Even changing the compilation options counts as a change in the -program. The Emacs sources specify which compilation options to use. -Some of them are specified in makefiles, and some in machine-specific -configuration files. They also give you ways to override this--but if -you do, then you are not testing what ordinary users will do. -Therefore, when pretesting, it is vital to test with the default -compilation options. - -(Testing with a different set of options can be useful *in addition*, -but not *instead of* the default options.) - -* The machine and system configuration files of Emacs are parts of -Emacs. So when you test Emacs, you need to do it with the -configuration files that come with Emacs. - -If Emacs does not come with configuration files for a certain machine, -and you test it with configuration files that don't come with Emacs, -this is effectively changing Emacs. Because the crucial fact about -the planned release is that, without changes, it doesn't work on that -machine. - -To make Emacs work on that machine, we would need to install new -configuration files. That is not out of the question, since it is -safe--it certainly won't break any other machines that already work. -But you will have to rush in the legal papers to give the FSF -permission to use such a large piece of text. - -* Look in the etc/MACHINES file. - -The etc/MACHINES file says which configuration files to use for your -machine, so use the ones that are recommended. If you guess, you might -guess wrong and encounter spurious difficulties. What's more, if you -don't follow etc/MACHINES then you aren't helping to test that its -recommendations are valid. - -The etc/MACHINES file may describe other things that you need to do -to make Emacs work on your machine. If so, you should follow these -recommendations also, for the same reason. - -* Send your problem reports to emacs-pretest-bug@gnu.org, not -bug-gnu-emacs. - -Sometimes we won't know what to do about a system-dependent issue, and -we may need people to say what happens if you try a certain thing on a -certain system. When this happens, we'll send out a query. - -* Don't delay sending information. - -When you test on a system and encounter no problems, please report it -right away. That way, we will know that someone has tested Emacs on -that kind of system. - -Please don't wait for several days "to see if it really works before -you say anything." Tell us right away that Emacs seems basically to -work; then, if you notice a problem a few days later, tell us -immediately about that when you see it. - -It is okay if you double check things before reporting a problem, such -as to see if you can easily fix it. But don't wait very long. A good -rule to use in pretesting is always to report every problem on the -same day you encounter it, even if that means you can't find a -solution before you report the problem. - -I'd much rather hear about a problem today and a solution tomorrow -than get both of them tomorrow at the same time. - -* Make each bug report self-contained. - -If you refer back to another message, whether from you or from someone -else, then it will be necessary for anyone who wants to investigate -the bug to find the other message. This may be difficult, it is -probably time-consuming. - -To help save our time, simply copy the relevant parts of any previous -messages into your own bug report. - -In particular, if we ask you for more information because a bug report -was incomplete, it is best to send me the *entire* collection of -relevant information, all together. If you send just the additional -information, that makes extra work for us. There is even a risk that -we won't remember what question you are sending the answer to. - -* When you encounter a bug that manifests itself as a Lisp error, -try setting debug-on-error to t and making the bug happen again. -Then you will get a Lisp backtrace. Including that in your bug report -is very useful. - -* For advice on debugging, see etc/DEBUG. - -* Debugging optimized code is possible, if you compile with GCC, but -in some cases the optimized code can be confusing. If you are not -accustomed to that, recompile Emacs without -O. One way to do this is - - make clean - make CFLAGS=-g - -* Configure tries to figure out what kind of system you have by -compiling and linking programs which calls various functions and looks -at whether that succeeds. The file config.log contains any messages -produced by compilers while running configure, to aid debugging if -configure makes a mistake. But note that config.cache reads: - -# Giving --cache-file=/dev/null disables caching, for debugging configure. - -or more simply, - -rm config.cache -./configure - -* Don't try changing Emacs *in any way* during pretest unless it fails -to work unchanged. - -* Always be precise when talking about changes you have made. Show -things rather than describing them. Use exact filenames (relative to -the main directory of the distribution), not partial ones. For -example, say "I changed Makefile" rather than "I changed the -makefile". Instead of saying "I defined the MUMBLE macro", send a -diff. - -* Always use `diff -c' to make diffs. If you don't include context, it -may be hard for us to figure out where you propose to make the -changes. So we might ignore your patch. - -* When you write a fix, keep in mind that we can't install a change -that *might* break other systems without the risk that it will fail to -work and therefore require an additional cycle of pretesting. - -People often suggest fixing a problem by changing config.h or -src/Makefile to do something special that a particular system needs. -Sometimes it is totally obvious that such changes would break Emacs -for almost all users. We can't possibly make a change like that. All -we can do is ask you to find a fix that is safe to install. - -Sometimes people send fixes that *might* be an improvement in -general--but it is hard to be sure of this. I can install such -changes some of the time, but not during pretest, when I am trying to -get a new version to work reliably as quickly as possible. - -The safest changes for us to install are changes to the s- and m- -files. At least those can't break other systems. - -Another safe kind of change is one that uses a conditional to make -sure it will apply only to a particular kind of system. Ordinarily, -that is a bad way to solve a problem, and I would want to find a -cleaner alternative. But the virtue of safety can make it superior at -pretest time. - -* Don't suggest changes during pretest to add features or make -something cleaner. Every change risks introducing a bug, so I won't -install a change during pretest unless it is *necessary*. - -* If you would like to suggest changes for purposes other than fixing -user-visible bugs, don't wait till pretest time. Instead, send them -after we have made a release that proves to be stable. That is the -easiest time to consider such suggestions. If you send them at -pretest time, we will have to defer them till later, and that might -mean we forget all about them. - -* In some cases, if you don't follow these guidelines, your -information might still be useful, but we would have to do more work -to make use of it. That might cause it to fall by the wayside. - -Local Variables: -mode: text -End: - -# arch-tag: caf47b2c-b56b-44f7-a760-b5bfbed15fd3 diff --git a/admin/make-announcement b/admin/make-announcement deleted file mode 100755 index 1c27c59ab50..00000000000 --- a/admin/make-announcement +++ /dev/null @@ -1,89 +0,0 @@ -#! /bin/bash - -## Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -## Free Software Foundation, Inc. - -## Author: Francesco Potorti` - -## This file is part of GNU Emacs. - -## GNU Emacs is free software: you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation, either version 3 of the License, or -## (at your option) any later version. - -## GNU Emacs is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. - -## You should have received a copy of the GNU General Public License -## along with GNU Emacs. If not, see . - - -### Code: - -if [ $# -ne 2 ]; then - echo "usage: $0 " >&2 - exit 1 -fi - -if [ ! -f INSTALL -o ! -f configure -o ! -d lib-src ]; then - echo "this script should be run in the emacs root directory" >&2 - exit 2 -fi - -OLD=$1 -NEW=$2 -outfile=emacs-$NEW.announce -oldtag=EMACS_PRETEST_$(echo $OLD|tr . _) -newtag=EMACS_PRETEST_$(echo $NEW|tr . _) - -if [ -f $outfile ]; then - echo "$outfile exists" - echo -n "interrupt to abort, ENTER to overwrite "; read answer -fi - -echo -n "tag name for OLD emacs version $OLD [$oldtag]: "; read answer -if [ "$answer" ]; then oldtag=$answer; fi - -echo -n "tag name for NEW emacs version $NEW [$newtag]: "; read answer -if [ "$answer" ]; then newtag=$answer; fi - -exec > $outfile - -cat < - -Please report results from compiling and running the pretest to -. Your feedback is necessary for us -to know on which platforms the pretest has been tried. - -If you have the tars from the previous pretest, and you have the -\`xdelta' utility, you can instead download the much smaller - - - -You can use a command like - - $ xdelta patch XDELTA PREVIOUS-TAR CURRENT-TAR - -to generate the new tar from the old one, where XDELTA is the xdelta -file you downloaded, PREVIOUS-TAR is the tar file from the previous -pretest, and CURRENT-TAR is the name of the tar file you downloaded. - -Information about xdelta can be found on the GNU ftp site, in -/non-gnu/xdelta.README. - -Changes since $OLD - -EOF - -make-changelog-diff $oldtag $newtag - -echo " announcement created in $outfile" >&2 - -# arch-tag: 605e00c7-7330-4c45-81e1-2ed53a13c39f diff --git a/admin/make-changelog-diff b/admin/make-changelog-diff deleted file mode 100755 index 5ab468c8f5d..00000000000 --- a/admin/make-changelog-diff +++ /dev/null @@ -1,30 +0,0 @@ -#! /bin/bash - -## Author: Francesco Potorti` - -if [ $# -ne 2 ]; then - echo "usage: $0 TAG1 TAG2" >&2 - exit 1 -fi - -if [ ! -f INSTALL -o ! -f configure -o ! -d lib-src ]; then - echo "this script should be run in the emacs root directory" >&2 - exit 2 -fi - -cvs -q diff -b -r $1 -r $2 $(find -name ChangeLog|sort) | - sed -n -e 's/^=\+/======/p' -e 's/^> //p' -e 's/^diff.*//p' \ - -e 's/^RCS file: .cvsroot.emacs.emacs.\(.*\),v/\1/p' | - sed -n -e "/^======$/ { - N - N - h - d - } - H - s/.*// - x - s/^\n// - p" - -# arch-tag: 7604a259-40b4-4f97-86b2-496a9c546f0a diff --git a/admin/make-emacs b/admin/make-emacs deleted file mode 100755 index 818625266ba..00000000000 --- a/admin/make-emacs +++ /dev/null @@ -1,188 +0,0 @@ -#! /usr/bin/perl -# Build Emacs with various options for profiling, debugging, -# with and without warnings enabled etc. - -# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -require 5; -use Getopt::Long; -use File::Basename; -use Cwd; - -# Default CVS sandbox directory. Only used when called from outside -# of the sandbox. - -$root = $ENV{"EMACS_ROOT"}; -$root = "/gd/gnu/emacs" unless $root; - -# Default make command. - -$make = $ENV{"EMACS_MAKE"}; -$make = "gmake" unless $make; - -$rc = GetOptions ("help" => \$help, - "enable-checking" => \$enable_checking, - "no-warn" => \$no_warn, - "check-marked" => \$check_marked, - "all" => \$all, - "no-optim" => \$no_optim, - "union-type" => \$union_type, - "gprof" => \$profile, - "malloc-check" => \$malloc_check, - "no-mcheck" => \$no_mcheck, - "alias" => \$aliasing, - "boot" => \$boot, - "wall" => \$wall, - "gcc3" => \$gcc3, - "trace-selection" => \$trace_selection, - "trace-move" => \$trace_move, - "stabs" => \$use_stabs, - "optim" => \$optim); - -if ($rc == 0 || $help) - { - print <. - - If this is the first pretest of a major release, just comparing - with the previous release may overlook many new files. You can try - something like `find -f | grep -v CVS...etc' in a clean CVS tree, - and compare the results against the new tar contents. - -8. xdelta delta emacs-OLD.tar.gz emacs-NEW.tar.gz emacs-OLD-NEW.xdelta - -9. tar -zxf emacs-NEW.tar.gz; cd emacs-NEW - ./configure && make && make -n install - Use `script' or M-x compile to save the compilation log in - compile-NEW.log and compare it against an old one. The easiest way - to do that is to visit the old log in Emacs, change the version - number of the old Emacs to __, do the same with the new log and do - M-x ediff. Especially check that Info files aren't built. - -10. cd EMACS_ROOT_DIR; cvs tag TAG - TAG is EMACS_PRETEST_XX_YY_ZZZ for a pretest, EMACS_XX_YY for a - release. - - Shortly before the release, cut the branch with the following commands: - - cvs rtag EMACS_`NUMBER'_BASE - cvs rtag -b EMACS_`NUMBER'_RC -r EMACS_`NUMBER'_BASE - - where `NUMBER' is the major version number of the release. This - makes it easier to see what changes have been applied to the - branch with: - - cvs diff -r EMACS_`NUMBER'_BASE -r EMACS_`NUMBER'_RC - - or merge changes back to the trunk with "cvs update -j", if - necessary. - - After doing this, increase the version number on the trunk as per - step 4. - -11. Now you should upload the files to the GNU ftp server. In order to - do that, you must be registered as an Emacs maintainer and have your - GPG key acknowledged by the ftp people. Mail - for instructions. Once you are there, for each file FILE to be - released, create a detached GPG binary signature and a clearsigned - directive file like this: - gpg -b FILE - echo directory: emacs/pretest > FILE.directive (for a pretest) - echo directory: emacs > FILE.directive (for a release) - gpg --clearsign FILE.directive - Upload by anonymous ftp to ftp://ftp-upload.gnu.org/ the files FILE, - FILE.sig, FILE.directive.asc. - For a release, place the files in the /incoming/ftp directory. - For a pretest, place the files in /incoming/alpha instead, so that - they appear on ftp://alpha.gnu.org/. - - For a release, upload a bz2 tarfile as well; this can save a lot - of bandwidth. - -12. After five minutes, verify that the files are visible at - ftp://alpha.gnu.org/gnu/emacs/pretest/ for a pretest, at - ftp://ftp.gnu.org/gnu/emacs/ for a release. - -13. For a pretest, announce it on emacs-devel and BCC the pretesters. - For a release, announce it on info-gnu@gnu.org, - info-gnu-emacs@gnu.org, and emacs-devel. - - -# arch-tag: c23c771f-ca26-4584-8a04-50ecf0989390 diff --git a/admin/notes/BRANCH b/admin/notes/BRANCH deleted file mode 100644 index af403a81cca..00000000000 --- a/admin/notes/BRANCH +++ /dev/null @@ -1,5 +0,0 @@ -This file describes the CVS branch in which it is maintained. -Everything below the line is branch-specific. -________________________________________________________________________ - -This is EMACS_23_1_RC branch, intended to be used for the 23.1 release. diff --git a/admin/notes/bugtracker b/admin/notes/bugtracker deleted file mode 100644 index 030e8f668b6..00000000000 --- a/admin/notes/bugtracker +++ /dev/null @@ -1,312 +0,0 @@ -NOTES ON THE EMACS BUG TRACKER -*- outline -*- - -The Emacs Bug Tracker can be found at http://emacsbugs.donarmstrong.com/ - -For a list of all bugs, see http://emacsbugs.donarmstrong.com/emacs - -** How do I report a bug in Emacs now? -The same way as you always did. Send mail to bug-gnu-emacs@gnu.org, -or use M-x report-emacs-bug. - -The only differences are: - -i) Your report will be assigned a number and generate an automatic reply. - -ii) Optionally, you can set some database parameters when you first -report a bug (see "Setting bug parameters" below). - -iii) If you want to CC: someone, use X-Debbugs-CC: (this is important; -see below). - -Once your report is filed and assigned a number, it is sent out to the -bug mailing list. In some cases, it may be appropriate to just file a -bug, without sending out a copy. To do this, send mail to -quiet@emacsbugs.donarmstrong.com. - -** How do I reply to an existing bug report? -Reply to 123@emacsbugs.donarmstrong.com, replacing 123 with the number -of the bug you are interested in. NB this only sends mail to the -bug-list, it does NOT (?) send a CC to the original bug submitter. -So you need to explicitly CC him/her (and anyone else you like). - -(Many people think the submitter SHOULD be automatically subscribed -to subsequent discussion, but this does not seem to be implemented. -See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=37078) - -Do NOT send a separate copy to the bug list, since this may generate a -new report. The only time to send mail to the bug list is to create a -new report. - -Gnus users can add the following to message-dont-reply-to-names; -similarly with Rmail and rmail-dont-reply-to-names: - -"\\(emacs-pretest-bug\\|bug-gnu-emacs\\)@gnu\\.org\\|\ -\\(\\(submit\\|control\\|owner\\)@emacsbugs\\.\\|bug-submit-list@\\)\ -donarmstrong\\.com" - -The "bug-submit-list@donarmstrong.com" and -"owner@emacsbugs.donarmstrong.com" entries are there because they can -appear in the "Resent-To" and "Resent-CC" headers, respectively. For a -long time Rmail erroneously included these headers in replies. If you -correspond with an Rmail user on a bug, these addresses may end up in -the Cc. Mailing to them does nothing but create duplicates and errors. -(It is possible you might want to have a dialog with the owner -address, outside of normal bug reporting.) - -** When reporting a bug, to send a Cc to another address -(e.g. bug-cc-mode@gnu.org), do NOT just use a Cc: header. -Instead, use "X-Debbugs-CC:". This ensures the Cc address will get a -mail with the bug report number in. If you do not do this, each reply -in the subsequent discussion will end up creating a new bug. This is -annoying. - -Note that the way this feature works is perhaps not ideal (Bug#1720). -If X-Debbugs-CC: was specifed by a real header, that header is removed -in the mail sent out to the bug list, and the addresses merged into -the Resent-CC header (see below). They don't appear as an explicit CC: -header, nor do they appear in the Reply-To: header. So people you -X-Debbugs-CC are not included in any following discussion unless they are -manually cc'd. So this feature really only serves to notify them that -a bug has been filed. It's then up to them to follow any subsequent -discussion. - -If X-Debbugs-CC were merged into the Reply-To header, this might work -more the way people expect. - -** How does Debbugs send out mails? - -The mails are sent out to the bug list with From: and To: unchanged. -Eg if you file a bug with "submit@emacsbugs.donarmstrong.com", that -remains in the To: address. They reach the bug list by being resent. - -Mails arriving at the bug list have the following Resent-* headers: - -Resent-From: person who submitted the bug -Resent-To: bug-submit-list@donarmstrong.com -Resent-CC: maintainer email address, plus any X-Debbugs-CC: entries - -The "maintainer email address" is "Emacs Bugs " -in most cases. - -They also have: - -Reply-To: bug submitter, 123@emacsbugs.donarmstrong.com - -** To not get acknowledgement mail from the tracker, -add an "X-Debbugs-No-Ack:" header (with any value). If you use Gnus, -you can add an element to gnus-posting-styles to do this automatically, eg: - -("gnu-emacs\\(-pretest\\)?-bug" - ("X-Debbugs-No-Ack" "yes")) - -(adjust the regexp according to the name you use for the bug lists) - -** To record a bug in the tracker without sending mail to the bug list. -This can be useful to make a note of something discussed on -emacs-devel that needs fixing. In other words, this can be the -equivalent of adding something to FOR-RELEASE. - -To: quiet@emacsbugs.donarmstrong.com -[headers end] -Package: emacs -Version: 23.0.60 -Severity: minor - -Remember to fix FOO, as discussed on emacs-devel at http://... . - -** Not interested in tracker control messages (tags being set, etc)? -Discard mails matching: - -^X-Emacs-PR-Message: transcript - -When you close a bug, you get a message matching: - -^X-Emacs-PR-Message: closed - -** How to avoid multiple copies of mails. -When you reply to a bug, respect the Reply-To address, ie send mail -only to the submitter address and the numbered bug address. Do not -send mail direct to bug-gnu-emacs or emacs-pretest-bug unless you are -reporting a new bug. - -** To close bug #123 (for example), send mail - -To: 123-done@emacsbugs.donarmstrong.com - -with a brief explanation in the body as to why the bug was closed. - -** Setting bug parameters. -There are two ways to set the parameters of bugs in the database -(tags, severity level, etc). When you report a new bug, you can -provide a "pseudo-header" at the start of the report, eg: - -Package: emacs -Version: 23.0.60 -Severity: minor - -Optionally, add a sub-package, eg Package: emacs,calendar. -This can include tags. Some things (e.g. submitter) don't seem to -work here. - -Otherwise, send mail to the control server, control@emacsbugs.donarmstrong.com. -At the start of the message body, supply the desired commands, one per -line: - -command bug-number [arguments] -... -quit|stop|thank|thanks|thankyou|thank you - -The control server ignores anything after the last line above. So you -can place control commands at the beginning of a reply to a bug -report, and Bcc: the control server (note the commands have no effect -if you just send them to the bug-report number). Bcc: is better than Cc: -in case people use Reply-to-All in response. - -Some useful control commands: - -*** To reopen a closed bug: -reopen 123 - -*** Bugs can be tagged in various ways (eg wontfix, patch, etc). -The available tags are: -patch wontfix moreinfo unreproducible fixed notabug -Note that the list at http://emacsbugs.donarmstrong.com/Developer#tags -is incorrect, at least for Emacs. -The list of tags can be prefixed with +, - or =, meaning to add (the -default), remove, or reset the tags. E.g.: - -tags 123 + wontfix - -*** To merge bugs: -Eg when bad replies create a bunch of new bugs for the same report. -Bugs must all be in the same state (e.g. same package(s) and severity), -but need not have the same tags (tags are merged). E.g.: - -merge 123 124 125 ... - -Note that merging does not affect titles. In particular, a "retitle" -of merged bugs only affects individual bugs, not all of them. - -*** Forcing a merge: -Like `merge', but bugs need not be in the same state. The packages -must still match though. The first one listed is the master. E.g.: - -forcemerge 123 124 125 ... - -Note: you cannot merge with an archived bug - you must unarchive it first. - -*** To unmerge bugs: -To disconnect a bug from all bugs it is merged with: - -unmerge 123 - -This command accepts only one bug number. - -*** To clone bugs: -Useful when one report refers to more than one bug. - -clone 123 -1 [-2 ...] -retitle -1 second bug -retitle -2 third bug - -The negative numbers provide a way to refer to the cloned bugs (which -will be assigned proper numbers). - -NB you cannot clone a merged bug. You'd think that trying to do so -would just give you an unmerged copy of the specified bug number, but no: - -http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=474742 - -You must unmerge, clone, then re-merge. - -*** To set severity: -severity 123 critical|grave|serious|important|normal|minor|wishlist - -See http://emacsbugs.donarmstrong.com/Developer#severities for the meanings. - -*** To set the owner of a bug: -owner 123 A Hacker - -The shorthand `!' means your own address. - -*** To remove the owner of a bug: -noowner 123 - -*** To mark a bug as fixed in a particular version: -fixed 123 23.0.60 - -*** To remove a "fixed" mark: -notfixed 123 23.0.60 - -** To remove spam from the tracker, move it to the `spam' pseudo-package: -reassign 123 spam - -** To change the title of a bug: -retitle 123 Some New Title - -** To change the submitter address: -submitter 123 none@example.com - -Note that it does not seem to work to specify "Submitter:" in the -pseudo-header when first reporting a bug. - -** How does archiving work? -You can still send mail to a bug after it is closed. After 28 days with -no activity, the bug is archived, at which point no more changes can -be made. If you try to send mail to the bug after that (or merge with -it), it will be rejected. To make any changes, you must unarchive it first: - -unarchive 123 - -The bug will be re-archived after the next 28 day period of no activity. - -** The web-page with the list of bugs is slow to load - -It's a function of the number of displayed bugs. You can speed things -up by only looking at the newest 100 bugs: - -http://emacsbugs.donarmstrong.com/cgi-bin/pkgreport.cgi?newest=100;package=emacs - -The above page is accessible from the "Options" section at the end of -the "main list of bugs" page. Select bugs "in package" = emacs; -"newest bugs" = 100. (I have no idea how you get to that Options -section without having to go through the bug list page first...) - -** Mails to the bug tracker disappear - -Apparently it has some kind of spam filter that sometimes silently -discards valid mails. Adding a subject (pointless in control messages) -may help. - -** ChangeLog issues - -*** When you fix a bug, it can be helpful to put the bug number in the -ChangeLog entry, for example: - - * foo.el (foofunc): Fix the `foo' case. (Bug#123) - -Then the relevant bug can be found for easy reference. If it's an -obvious fix (e.g. a typo), there's no need to clutter the log with the -bug number. - -Similarly, when you close a bug, it can be helpful to include the -relevant ChangeLog entry in the message to the bug tracker, so people -can see eaxctly what the fix was. - -*** bug-reference-mode - -Activate `bug-reference-mode' in ChangeLogs to get clickable links to -the bug web-pages. - -** Gnus-specific voodoo - -*** Put point on a bug-number and try: M-x gnus-read-ephemeral-emacs-bug-group - -*** If the above is not available: -(add-hook 'gnus-article-mode-hook - (lambda () - (setq bug-reference-url-format - "http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=%s") - (bug-reference-mode 1))) - -and you can click on the bug number in the subject header. diff --git a/admin/notes/changelogs b/admin/notes/changelogs deleted file mode 100644 index 2c3749244fb..00000000000 --- a/admin/notes/changelogs +++ /dev/null @@ -1,17 +0,0 @@ -http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg00793.html - There is no need to make change log entries for files such as NEWS, - MAINTAINERS, and FOR-RELEASE. - -http://lists.gnu.org/archive/html/emacs-devel/2006-12/msg01135.html - There is no need to indicate regeneration of files such as configure - in ChangeLog. - - -http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00940.html -Preferred form for several entries with the same content: - - * help.el (view-lossage): - * kmacro.el (kmacro-edit-lossage): - * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys. - -(Rather than anything involving "ditto" and suchlike.) diff --git a/admin/notes/copyright b/admin/notes/copyright deleted file mode 100644 index 5ed67fb97cd..00000000000 --- a/admin/notes/copyright +++ /dev/null @@ -1,676 +0,0 @@ -Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. -See the end of the file for license conditions. - - -NOTES ON COPYRIGHTS AND LICENSES - -Some terminology: - -A "copyright notice" consists of one or a few lines of this format: -"Copyright (C) 2006, 2007 Free Software Foundation, Inc." - -A "license notice" is a statement of permissions, and is usually much -longer, eg the text "GNU Emacs is free software...". - - -Summary for the impatient: - -1. Don't add code to Emacs written by someone other than yourself -without thinking about the legal aspect. Even if the changes are -trivial, consider if they combine with previous changes by the same -author to make a non-trivial total. If so, make sure they have an -assignment. If adding a whole file adjust the copyright statements in -the file. - -2. When installing code written by someone else, the ChangeLog entry -should be in the name of the author of the code, not the person who -installs it. I think it is helpful to put the author (if not yourself) -in the CVS log as well; and to not install any of your own changes in -the same commit. - -3. With images, add the legal info to a README file in the directory -containing the image. - -4. If you add a lot of text to a previously trivial file that had no -legal notices, consider if you should add a copyright statement. - -5. Please don't just add an FSF copyright without checking that is the -right thing to do. - - -Every non-trivial file distributed through the Emacs CVS should be -self-explanatory in terms of copyright and license. This includes -files that are not distributed in Emacs releases (for example, the -admin/ directory), because the whole Emacs CVS is publicly -available. - -The definition of triviality is a little vague, but a rule of thumb is -that any file with less than 15 lines of actual content is trivial. If -a file is auto-generated (eg ldefs-boot.el) from another one in the -CVS, then it does not really matter about adding a copyright statement -to the generated file. - -Legal advice says that we could, if we wished, put a license notice -even in trivial files, because copyright law in general looks at the -overall work as a whole. It is not _necessary_ to do so, and rms -prefers that we do not. This means one needs to take care that trivial -files do not grow and become non-trivial without having a license -added. NB consequently, if you add a lot of text to a small file, -consider whether your changes have made the file worthy of a copyright -notice, and if so, please add one. - -It can be helpful to put a reminder comment at the start of a trivial -file, eg: "add a license notice if this grows to > 10 lines of code". - -The years in the copyright notice should be updated every year (see -file "years" in this directory). The PDF versions of refcards etc -should display copyright notices (an exception to the rule about -"generated" files), but these can just display the latest year. The -full list of years should be kept in comments in the source file. If -these are distributed in CVS, check in a regenerated version when the -tex files are updated. - -Copyright changes should be propagated to any associated repositories -(eg Gnus, MH-E), but I think in every case this happens automatically -(?). - -All README (and other such text files) that are non-trivial should -contain copyright statements and GPL license notices, exactly as .el -files do (see e.g. README in the top-level directory). Before 2007, -we used a simple, short statement permitting copying and modification -provided legal notices were retained. In Feb 2007 we switched to the -standard GPL text, on legal advice. Some older text files in etc/ -should, however, keep their current licenses (see below for list). - -For image files, the copyright and license details should be recorded -in a README file in each directory with images. (Legal advice says -that we need not add notices to each image file individually, if they -allow for that.). It is recommended to use the word "convert" to -describe the automatic process of changing an image from one format to -another (http://lists.gnu.org/archive/html/emacs-devel/2007-02/msg00618.html). - - -When installing a file with an "unusual" license (after checking first -it is ok), put a copy of the copyright and license in the file (if -possible. It's ok if this makes the file incompatible with its -original format, if it can still be used by Emacs), or in a README -file in the relevant directory. - -The vast majority of files are copyright FSF and distributed under the -GPL. A few files (mainly related to language and charset support) are -copyright AIST alone, or both AIST and FSF. (Contact Kenichi Handa -with questions about legal issues in such files.) In all these cases, -the copyright years in each file should be updated each year. - -There are some exceptions to the points in the previous paragraph, and -these are listed below for reference, together with any files where -the copyright needs to be updated in "unusual" ways. - -If you find any other such cases, please consult to check they are ok, -and note them in this file. This includes missing copyright notices, -and "odd" copyright holders. In most cases, individual authors should -not appear in copyright statements. Either the copyright has been -assigned (check copyright.list) to the FSF (in which case the original -author should be removed and the year(s) transferred to the FSF); or -else it is possible the file should not be in Emacs at all (please -report!). - -Note that it seems painfully clear that one cannot rely on CVS logs, -or even ChangeLogs, for older changes. People often installed changes -from others, without recording the true authorship. - -[For reference, most of these points were established via email with -rms, 2007/1, "Copyright years".] - - -lisp/version.el # emacs-copyright -lib-src/ebrowse.c # version -lib-src/etags.c # print_version -lib-src/rcs2log # Copyright -Cocoa/Emacs.base/Contents/Info.plist -Cocoa/Emacs.base/Contents/Resources/English.lproj/InfoPlist.strings -GNUstep/Emacs.base/Resources/Info-gnustep.plist - `set-copyright' in admin.el will do all the above. - -/install-sh -lispintro/install-sh - - this file is copyright MIT, which is OK. Leave the copyright alone. - -src/m/news-r6.h - public domain, leave alone. - -etc/refcards/*.tex - also update the \def\year macro for the latest year. - -etc/BABYL, ms-kermit - no notices (see below). - -etc/edt-user.doc - - update BOTH notices in this file - -etc/emacs.csh - - written by Michael DeCorte, who has no assignment. But trivial - enough to not need license. - -etc/future-bug - - doesn't need a humorless disclaimer, because Karl Fogel says we - can consider it part of Emacs, and he has a blanker disclaimer for - Emacs changes. (email to rgm "[Emacs-commit] emacs/etc future-bug", - 2007028) - -etc/letter.pbm,letter.xpm - - trivial, no notice needed. - - -etc/FTP, ORDERS - - trivial (at time of writing), no license needed - -etc/GNU, INTERVIEW, LINUX-GNU, MOTIVATION, SERVICE, THE-GNU-PROJECT, -WHY-FREE - rms: "These are statements of opinion or testimony. Their licenses - should permit verbatim copying only. Please don't change the - licenses that they have. They are distributed with Emacs but they - are not part of Emacs." - -etc/HELLO - standard notices. Just a note that although the file itself is not - really copyrightable, in the wider context of it being part of - Emacs (and written by those with assignments), a standard notice is - fine. - -etc/MAILINGLISTS - rms: simple license is fine for this file - -leim/CXTERM-DIC/4Corner.tit, ARRAY30.tit, CCDOSPY.tit, ECDICT.tit, -ETZY.tit, PY-b5.tit, Punct-b5.tit, Punct.tit, QJ-b5.tit, QJ.tit, -SW.tit, TONEPY.tit, ZOZY.tit - - leave the copyrights alone. - -leim/MISC-DIC/CTLau-b5.html, CTLau.html, cangjie-table.b5, cangjie-table.cns, -pinyin.map, ziranma.cin - - leave the copyright alone. -Note that pinyin.map, ziranma.cin (and hence the generated -leim/quail/PY.el, ZIRANMA.el) are under GPLv1 or later. - -leim/SKK-DIC/SKK-JISYO.L -ja-dic/ja-dic.el - (the latter is auto-generated from the former). Leave the copyright alone. - -lib-src/etags.c - Copyright information is duplicated in etc/ETAGS.README. Update that - file too. - - Until 2007 etags.c was described as being copyright FSF and Ken Arnold. - After some investigation in Feb 2007, then to the best of our - knowledge we believe that the original 1984 Emacs version was based - on the version in BSD4.2. See for example this 1985 post from Ken Arnold: - - I have received enough requests for the current source to ctags - to post it. Here is the latest version (what will go out with - 4.3, modulo any bugs fixed during the beta period). It is the - 4.2 ctags with recognition of yacc and lex tags added. - - See also a 1984 version of ctags (no copyright) posted to net.sources: - - Version of etags.c in emacs-16.56 duplicates comment typos. - - Accordingly, in Feb 2007 we added a 1984 copyright for the - University of California and a revised BSD license. The terms of - this require that the full license details be available in binary - distributions - hence the file etc/ETAGS.README. The fact that the - --version output just says "Copyright FSF" is apparently OK - from a legal point of view. - -lib-src/getopt1.c, getopt_int.h - - these are from the GNU C library. Leave the copyrights alone. - -lisp/play/tetris.el - - no special rules about the copyright. We note here that we believe - (2007/1) there is no problem with our use of the name "tetris" or - the concept. - rms: "My understanding is that game rules as such are not copyrightable." - - rms: Legal advice is that we are ok and need not worry about this. - - -lisp/net/tramp.el - - there are also copyrights in the body of the file. Update these too. - - -lwlib/ -rms (2007/02/17): "lwlib is not assigned to the FSF; we don't consider -it part of Emacs. [...] Therefore non-FSF copyrights are ok in lwlib." - -NB don't change the GPL version used for lwlib .c and .h files (see -below). - -FSF copyrights should only appear in files which have undergone -non-trivial cumulative changes from the original versions in the Lucid -Widget Library. NB this means that if you make non-trivial changes to -a file with no FSF copyright, you should add one. Also, if changes are -reverted to the extent that a file becomes basically the same as the -original version, the FSF copyright should be removed. - -In my (rgm) opinion, as of Feb 2007, all the non-trivial files differ -significantly from the original versions, with the exception of -lwlib-Xm.h. Most of the changes that were made to this file have -subsequently been reverted. Therefore I removed the FSF copyright from -this file (which is arguably too trivial to merit a notice anyway). I -added FSF copyright to the following files which did not have them -already: Makefile.in, lwlib-Xaw.c, lwlib-int.h (borderline), -lwlib-utils.c (borderline), lwlib.c, lwlib.h. - -Copyright years before the advent of public CVS in 2001 were those -when I judged (from the CVS logs) that non-trivial amounts of change -had taken place. I also adjusted the existing FSF years in xlwmenu.c, -xlwmenu.h, and xlwmenuP.h on the same basis. - -Note that until Feb 2007, the following files in lwlib were lacking -notices: lwlib-int.h, lwlib.h, lwlib-Xaw.h, lwlib-Xlw.h, lwlib-utils.h - -The following files did not list a Lucid copyright: xlwmenu.h, -xlwmenuP.h. - -To the best of our knowledge, all the code files in lwlib were -originally part of the Lucid Widget Library, even if they did not say -so explicitly. For example, they were all present in Lucid Emacs 19.1 -in 1992. The exceptions are the two Xaw files, which did not appear -till Lucid Emacs 19.9 in 1994. The file lwlib-Xaw.h is too trivial to -merit a copyright notice, but would presumably have the same one as -lwlib-Xaw.c. We have been unable to find a true standalone version of -LWL, if there was such a thing, to check definitively. - -To clarify the situation, in Feb 2007 we added Lucid copyrights and -GPL notices to those files lacking either that were non-trivial, -namely: lwlib-int.h, lwlib.h, xlwmenu.h, xlwmenuP.h. This represents -our best understanding of the legal status of these files. We also -clarified the notices in Makefile.in, which was originally the -Makefile auto-generated from Lucid's Imakefile. - -As of Feb 2007, the following files are considered too trivial for -notices: lwlib-Xaw.h, lwlib-Xlw.h, lwlib-utils.h. - -The version of lwlib/ first installed in Emacs seems to be the same as -that used in Lucid Emacs 19.8 (released 6-sep-93); except the two Xaw -files, which did not appear till Athena support was added in Lucid -Emacs 19.9. In Lucid Emacs 19.1, all files were under GPLv1 or later, -but by Lucid Emacs 19.8, lwlib.c and xlwmenu.c had been switched to v2 -or later. These are the versions that were first installed in Emacs. -So in GNU Emacs, these two files have been under v2 or later since -1994. - -It seems that it was the intention of Lucid to use v1 or later -(excepting the two files mentioned previously); so this is the license -we have used when adding notices to code that did not have notices -originally. Although we have the legal right to switch to v2 or later, -rms prefers that we do not do so. - - -doc/*/doclicense.texi - - leave the copyright alone in this imported file. - -doc/*/*.texi - All manuals should be under GFDL (but see below), and -should include a copy of it, so that they can be distributed -separately. faq.texi has a different license, for some reason no-one -can remember. -http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg00583.html -http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg00618.html - -doc/misc/mh-e.texi is dual-licensed (GPL and GFDL) per agreement with -FSF (reconfirmed by rms Aug 25 2008). Discussion with -licensing@fsf.org starting on Thu, 07 Aug 2003 with subject: -"[gnu.org #58812] Changing license of MH-E manual" - - -msdos/is_exec.c, sigaction.c - these files are copyright DJ Delorie. -Leave the copyrights alone. Leave the Eli Zaretskii copyright in -is_exec.c alone. See the msdos/README file for the legal history of -these files. - - -oldXMenu/ - Keep the "copyright.h" method used by X11, rather than moving the - licenses into the files. Note that the original X10.h did not use - copyright.h, but had an explicit notice, which we retain. - -If you make non-trivial changes to a file which does not have an FSF -notice, add one and a GPL notice (as per Activate.c). If changes to a -file are reverted such that it becomes essentially the same as the -original X11 version, remove the FSF notice and GPL. - -Only the files which differ significantly from the original X11 -versions should have FSF copyright and GPL notices. At time of writing -(Feb 2007), this is: Activate.c, Create.c, Internal.c. I (rgm) -established this by diff'ing the current files against those in X11R1, -and when I found significant differences looking in the ChangeLog for -the years they originated (the CVS logs are truncated before 1999). I -therefore removed the FSF notices (added in 200x) from the other -files. There are some borderline cases IMO: AddSel.c, InsSel.c, -XMakeAssoc.c, XMenu.h. For these I erred on the side of NOT adding FSF -notices. - -With regards to whether the files we have changed should have GPL -added or not, rms says (2007-02-25, "oldXmenu issues"): - - It does not make much difference, because oldXmenu is obsolete - except for use in Emacs (and it is not normally used in Emacs any - more either). - - So, to make things simple, please put our changes under the GPL. - -insque.c had no copyright notice until 2005. The version of insque.c -added to Emacs 1992-01-27 is essentially the same as insremque.c added -to glic three days later by Roland McGrath, with an FSF copyright and -GPL, but no ChangeLog entry: - -To the best of his recollection, McGrath (who has a copyright -assignment) was the author of this file (email from roland at frob.com -to rms, 2007-02-23, "Where did insque.c come from?"). The FSF -copyright and GPL in this file are therefore correct as far as we -understand it. - -Imakefile had no legal info in Feb 2007, but was obviously based on -the X11 version (which also had no explicit legal info). As it was -unused, I removed it. It would have the same MIT copyright as -Makefile.in does now. - - -src/gmalloc.c - - contains numerous copyrights from the GNU C library. Leave them alone. - -src/acldef.h, chpdef.h, ndir.h - - see comments below. These files are OK to be released with Emacs - 22, but we may want to revisit them afterwards. - - -** Some notes on resolved issues, for historical information only - -etc/TERMS -rms: "surely written either by me or by ESR. (If you can figure out -which year, I can probably tell you which.) Either way, we have papers -for it." It was present in Emacs-16.56 (15-jul-85). rms: "Then I -conclude it was written by me." - -etc/ulimit.hack - Very obsolete file removed March 2007. Doesn't say who the author -is, but web-search suggests Karl Kleinpaste, who has no Emacs -assignment. Trivial anyway. -http://groups.google.com/group/comp.unix.shell/browse_thread/thread/bf3df496994\ -9f1df/7e5922c67b3a98fb -http://groups.google.com/group/comp.unix.questions/msg/cc7e49cacfd1ccb4 - (original 1987 source) - -lisp/term/README - - had no copyright notice till Feb 2007. ChangeLog.3 suggests it was - written by Eric Raymond. When asked by rms on 14 Feb 2007 he said: - - I don't remember writing it, but it reads like my prose and I believe - I wrote the feature(s) it's describing. So I would have been the - likeliest person to write it. - - Odds are that I did, but I'm not certain. - - Accordingly, FSF copyright was added. - -src/unexhp9k800.c - http://lists.gnu.org/archive/html/emacs-devel/2007-02/msg00138.html - - briefly removed due to legal uncertainly Jan-Mar 2007. The - relevant assignment is under "hp9k800" in copyright.list. File was - written by John V. Morris at HP, and disclaimed by the author and - HP. So this file is public domain. - - -K Rodgers changes - It was pointed out that K Rodgers only had assigments for VC and - ps-print, but had changed several other files. We tried to contact - him for a general assignment, but he proved uncommunicative (despite - initially indicating to rms he would sign an assignment). As a result, his - changes were removed and/or rewritten independently. For details, see - threads: -http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg00225.html -http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg00257.html - - But then an assignment arrived before the release of Emacs 22: -http://lists.gnu.org/archive/html/emacs-devel/2007-04/msg01427.html - - -lisp/progmodes/python.el -Dave Love alerted us to a potential legal problem: -http://lists.gnu.org/archive/html/emacs-pretest-bug/2007-04/msg00459.html - -On consultation with a lawyer, we found there was no problem: -http://lists.gnu.org/archive/html/emacs-devel/2007-05/msg00466.html - - -** Issues that are "fixed" for the release of Emacs 22, but we may - wish to revisit later in more detail - - -admin/check-doc-strings - File says it's in the public domain, but that might not make it so. - -etc/BABYL - File written long ago by authors with no assignment. Keep them - without notices for now, try and contact authors if possible. Be - ready to remove these files if the authors ever object. - -etc/ms-kermit -etc/e/eterm-color.ti -src/acldef.h, chpdef.h, ndir.h - On legal advice from Matt Norwood, the following comment was added - to these files in Feb/Mar 2007: - - The code here is forced by the interface, and is not subject to - copyright, constituting the only possible expression of the - algorithm in this format. - - With the addition of this notice, these files are OK for the - upcoming Emacs-22 release. Post-release, we can revisit this issue - and possibly add a list of all authors who have changed these files. - (details in email from Matt Norwood to rms, 2007/02/03). - -etc/ms-7bkermit - Says it was written by Andy Lowry and Joel Spolsky. No entry for -either in copyright.list. NB this file is not "constrained" like -ms-kermit (rms: "We know it isn't. A comment at the front says it has -other bindings which might be handy."). File removed March 2007. -Re-add if clear up status at some point. - -etc/Xkeymap.txt - No info on author. File removed March 2007. rms: "It says it is -RLK's way of remapping his keyboard, so it is not constrained. I think -it was written by RLK. Let's delete it; if we contact RLK again, we -can put it back." Actually, RLK == Robert Krawitz has an Emacs -assignment. So this could be restored if it is still useful, but Jan Djärv -says it is obsolete: - - -src/m/mips4.h, news-risc.h, pmax.h -src/s/aix3-2.h, bsd386.h, hpux8.h, hpux9.h, irix4-0.h, irix5-0.h, -netbsd.h, sol2-3.h, usg5-4-2.h - - all these (not obviously trivial) files were missing copyrights - till Feb 2007, when FSF copyright was added. Matt Norwood advised: - - For now, I think the best policy is to assume that we do have - assignments from the authors (I recall many of these header files - as having been originally written by rms), and to attach an FSF - copyright with GPL notice. We can amend this if and when we - complete the code audit. Any additions to these files by - non-assigned authors are arguably "de minimis" contributions to - Emacs: small changes or suggestions to a work that are subsumed in - the main authors' copyright in the entire work. - -Here is my (rgm) take on the details of the above files: - -mips4.h - might be trivial? started trivial, been added to in tiny changes by - those with FSF assignment, often result of email suggestions by others. - -news-risc.h - started trivial. Grown by tiny additions, plus chunk - from mips.h, which was and is Copyright FSF - -pmax.h - started trivial. grown in tiny changes, except for maybe Jim Wilson's - comment. - -? irix4-0.h - I would say started non-trivial (1992, rms). only tiny changes since - installed. - -? irix5-0.h - I would say started non-trivial (1993, jimb, heavily based - on irix4-0.h). A few borderline non-tiny changes since. - -usg5-4-2.h - started non-trivial, but was heavily based on usg5-4.h, which was and is - copyright FSF. only tiny changes since installed. - -sol2-3.h - started trivial. only non-tiny change (1994) incorporated code from - usg5-4.h, which was and is copyright FSF. - -aix3-2.h, bsd386.h, hpux8.h, hpux9.h, netbsd.h - started trivial, grown in tiny changes. - -netbsd.h: -Roland McGrath said to rms (2007/02/17): "I don't really remember -anything about it. If I put it in without other comment, then probably -I wrote it myself." - - -Someone might want to tweak the copyright years (for dates before -2001) that I used in all these files. - -Note: erring on the side of caution, I also added notices to some -files I thought might be considered non-trivial (if one includes -comment) in s/: - aix4-1.h hpux10.h irix6-0.h irix6-5.h - ptx4.h sol2.h - -(everything with > 30 non-blank lines, which at least is _some_ kind of -system) - - -*** These are copyright issues that need not be fixed until after - Emacs 22 is released (though if they can be fixed before, that is - obviously good): - - -Is it OK to just `cvs remove' a file for legal reasons, or is -something more drastic needed? A removed file is still available from -CVS, if suitable options are applied. (This CVS issue obviously does -not affect a release). - rms: will ask lawyer - - -Make sure that all files with non-standard copyrights or licenses are -noted in this file. - - -REMOVED etc/gnu.xpm, nt/icons/emacs21.ico, nt/icons/sink.ico - - Restore if find legal info. emacs21.ico is not due to Davenport. - Geoff Voelker checked but could not find a record of where it came - from. - - -etc/images - Image files from GTK, Gnome are under GPLv2 (no "or later"?). RMS will - contact image authors in regards to future switch to v3. - - -etc/TUTORIAL* (translations) - switch to GPL (see english TUTORIAL) - rms: "We can leave the TUTORIAL translations alone until their - maintainers update them." - Can adapt short license text from end of GPL translations at: - http://www.gnu.org/licenses/translations.html - Only a few sentences around the license notice need changing from - previous version. -Done: TUTORIAL.eo - - -*** These are copyright issues still to be addressed: - -None known. - - -** NOTES ON RELICENSING TO GPL3 - -The EMACS_22_BASE branch was changed to GPLv3 (or later) 2007/07/25. - -Some notes: -(see http://lists.gnu.org/archive/html/emacs-devel/2007-07/msg01431.html) - -1. There are some files in Emacs CVS which are not part of Emacs (eg -those included from Gnulib). These are all copyright FSF and (at time -of writing) GPL >= 2. rms says may as well leave the licenses of these -alone (may import them from Gnulib again). These are: - - Gnulib: - src/getloadavg.c - src/gmalloc.c - src/md5.c - src/md5.h - src/mktime.c - src/strftime.c - src/termcap.c - src/tparam.c - - Others: - config.guess - config.sub - doc/man/texinfo.tex - -Note _not_ included in the above are src/regex.{c,h} (rms: "That -forked version is only in Emacs, so definitely relicense that."), and -oldXMenu/insque.c (rms: "We wrote that specifically for Emacs, so -definitely relicense that."). - -2. The files that are copyright FSF and AIST, or AIST alone, should be -and were updated, ditto the oldXMenu files with FSF copyright, and -msdos/is_exec.c and sigaction.c. - -3. lwlib/ - -Files originally in Lucid Widget Library were left alone (excludes -ChangeLog, etc), ie remain under GPL v1 or later, or v2 or later. -(rms: "We may as well leave this alone, since we are never going to -change it much.") - -4. There are some files where the FSF holds no copyright. These were -left alone: - - leim/MISC-DIC/CTLau-b5.html >= v2 - leim/MISC-DIC/CTLau.html >= v2 - (above included in lisp/international/titdic-cnv.el) - leim/MISC-DIC/pinyin.map >= v1 - leim/MISC-DIC/ziranma.cin >= v1 - leim/SKK-DIC/SKK-JISYO.L >= v2 - leim/SKK-DIC/README >= v2 - leim/ja-dic/ja-dic.el >= v2 - -5. At time of writing, some non-Emacs icons included from Gnome remain -under GPLv2 (no "or later"). See: - - etc/images/gnus/README - etc/images/mail/README - etc/images/README - nt/icons/README - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/notes/cpp b/admin/notes/cpp deleted file mode 100644 index 275001369d9..00000000000 --- a/admin/notes/cpp +++ /dev/null @@ -1,18 +0,0 @@ -ttn 2003-04-09 - -we use a C preprocesor not only in the normal compilation of .c files -into object files, but also for creating - - src/Makefile - lib-src/Makefile - -(delimited by comment "start of cpp stuff"). some cpp implementations -insert whitespace in between tokens. - -during makefile creation, the preprocessor symbol NOT_C_CODE is defined. -this should not be defined for normal .c file compilation. - -there has been discussion on eliminating this use of cpp and relying -solely on autoconf processing. rms says to leave it be. - -;;; arch-tag: d654291e-9fc8-41b7-ab0c-d3cde842a8e0 diff --git a/admin/notes/cvslogs b/admin/notes/cvslogs deleted file mode 100644 index ff2dcc93ff5..00000000000 --- a/admin/notes/cvslogs +++ /dev/null @@ -1,15 +0,0 @@ -http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html - -From: Eli Zaretskii -Subject: Re: Log messages in CVS -Date: Sat, 29 Dec 2007 16:06:29 +0200 - -I once posted a summary that I know about; see: - - http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00229.html - http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00234.html - http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00312.html - -Richard commented here, basically approving my summary: - - http://lists.gnu.org/archive/html/emacs-devel/2006-11/msg00276.html diff --git a/admin/notes/documentation b/admin/notes/documentation deleted file mode 100644 index f2e2aab73e7..00000000000 --- a/admin/notes/documentation +++ /dev/null @@ -1,114 +0,0 @@ --*- outline -*- - -Some documentation tips culled from emacs-devel postings. - - -** Manual indices - -http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00400.html - -For example, this text: - - @vindex x-gtk-show-hidden-files - @vindex x-gtk-file-dialog-help-text - When Emacs is compiled with GTK+ support, it uses the GTK+ ``file - chooser'' dialog. Emacs adds an additional toggle button to this - dialog, which you can use to enable or disable the display of hidden - files (files starting with a dot) in that dialog. If you want this - toggle to be activated by default, change the variable - @code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds - help text to the GTK+ file chooser dialog; to disable this help text, - change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. - -has index entries for the variables it describes, which is good, but -what if a user looks for this information without knowing the names of -these variables? For those, I added these two concept index entries: - - @cindex hidden files, in GTK+ file chooser - @cindex help text, in GTK+ file chooser - -Thus, if a user types "i hidden files TAB" in Info, she will see the -first entry, and so if she types "i file chooser RET". See why it is -better? - -The way to come up with useful index entries is to put yourself in the -shoes of someone who looks for the information, and think about words -and phrases you'd use to find it. - -One other rule for good indexing is not to have several index entries -that begin with the same substring and point to the same page or -screenful (i.e. to places that are close to one another). Here's a -fictitious example of such redundant entries: - - @cindex foobar, how to use - @cindex foobar rules - - Either leave only one of these, e.g. just "@cindex foobar", or -combine them into a single entry, e.g.: - - @cindex foobar, rules and usage - - -** Point is a proper name - -http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html - -In Emacs tradition, we treat "point" as a proper name when it refers -to the current editing location. It should not have an article. - -Thus, it is incorrect to write, "The point does not move". It should -be, "Point does not move". - -If you see "the point" anywhere in Emacs documentation or comments, -referring to point, please fix it. - - -** Don't use passive verbs - -http://lists.gnu.org/archive/html/emacs-devel/2008-10/msg00414.html - -Documentation is clearer if it avoids the passive voice whenever -possible. For example, rather than saying "Point does not move", say -"This does not move point". If you come across passive verbs in Emacs -documentation or comments, please see if it is possible to make the -text shorter and clearer using the active voice. Usually that does -make an improvement. The explicit subject required by the active voice -often provides important information which makes the text clearer, too. - - -** Antinews nodes - -*** Why Antinews is useful - -http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00893.html - -The usefulness of Antinews is to help people who buy the printed -manual and are still using the previous Emacs version. That's why we -focus on the (eliminated) behavior of the old version rather than on -the new features. - -Of course, we try to make it amusing as well. - -*** Don't mention in Antinews too many features absent in old versions - -http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg01054.html - -Since the purpose of Antinews is to help people use the previous Emacs -version, there is usually no need to mention features that are simply -absent in that version. That situation will be clear enough to users -without help from the manual. - -For instance, this - - @item - Emacs can no longer be started as a daemon. We decided that having an - Emacs sitting silently in the background with no visual manifestation - anywhere in sight is too confusing. - -may not need mentioning, because --daemon will give an error message -saying it's not implemented, and other cases aren't affected. - -The kind of change for which the user really needs help from Antinews -is where a feature works _differently_ in the previous version. -In those cases, the user might have trouble figuring out how to use -the old version without some sort of help. diff --git a/admin/notes/exit-value b/admin/notes/exit-value deleted file mode 100644 index e59bb614b9b..00000000000 --- a/admin/notes/exit-value +++ /dev/null @@ -1,35 +0,0 @@ -ttn 2004-05-09 - -The exit value of a program returning to the shell on unixoid systems is -typically 0 for success, and non-0 (such as 1) for failure. For vms it is -odd (1,3,5...) for success, even (0,2,4...) for failure. - -This holds from the point of view of the "shell" (in quotes because vms has a -different dispatch model that is not explained further here). - -From the point of view of the program, nowadays stdlib.h on both type of -systems provides macros `EXIT_SUCCESS' and `EXIT_FAILURE' that should DTRT. - -NB: The numerical values of these macros DO NOT need to fulfill the the exit -value requirements outlined in the first paragraph! That is the job of the -`exit' function. Thus, this kind of construct shows misunderstanding: - - #ifdef VMS - exit (1); - #else - exit (0); - #endif - -Values aside from EXIT_SUCCESS and EXIT_FAILURE are tricky. - - - -ttn 2004-05-12 - -Values aside from EXIT_SUCCESS and EXIT_FAILURE can be used to indicate -finer gradations of failure. If this is the only information available -to the caller, clamping such values to EXIT_FAILURE loses information. -If there are other ways to indicate the problem to the caller (such as -a message to stderr) it may be ok to clamp. In all cases, it is the -relationship between the program and its caller that must be examined. -[Insert ZAMM quote here.] diff --git a/admin/notes/font-backend b/admin/notes/font-backend deleted file mode 100644 index 5b5fd169727..00000000000 --- a/admin/notes/font-backend +++ /dev/null @@ -1,79 +0,0 @@ -Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - -New font handling mechanism with font backend method ----------------------------------------------------- - -The configure script, if invoked with "--enable-font-backend", checks -if libraries freetype and fontconfig exist. If they are both -available, macro "USE_FONT_BACKEND" is defined in src/config.h. In -that case, the existence of Xft library is checked too. - -The new files are: - font.h -- header providing font-backend related structures - (most important ones are "struct font" and "struct - font_driver"), macros, and etc. - font.c -- main font handling code. - xfont.c -- font-driver on X for X core fonts. - ftfont.c -- generic font-driver for FreeType fonts providing - device-independent methods of struct font_driver. - xftfont.c -- font-driver on X using Xft for FreeType fonts - utilizing methods provided by ftfont.c. - ftxfont.c -- font-driver on X directly using FreeType fonts - utilizing methods provided by ftfont.c. - w32font.c -- font driver on w32 using Windows native fonts, - corresponding to xfont.c - w32uniscribe.c -- font driver on w32, using the uniscribe API - to provide complex script support for opentype fonts on - Windows 2000 and later, or earlier versions of Windows - with uniscribe installed as an add-on. - -So we already have codes for X and w32. For Mac it seems that we need -these files: - atmfont.c -- font-driver on mac using ATM fonts, corresponding - to xfont.c -As BDF fonts are currently used on w32, we may also implement these: - bdffont.c -- generic font-driver for BDF fonts, corresponding to - ftfont.c - bdfw32font.c -- font-driver on w32 using BDF fonts, - corresponding to ftxfont.c -But, as FreeType already supports BDF fonts, if FreeType and -Fontconfig are also available on w32, what we need may be: - ftw32font.c -- font-driver on w32 directly using FreeType fonts - utilizing methods provided by ftfont.c. - -And, for those to work, macterm.c and macfns.c must be changed by the -similar way as xterm.c and xfns.c (the parts "#ifdef USE_FONT_BACKEND" -... "#endif" should be checked). - -It may be interesting if Emacs supports a frame buffer directly and -has these font driver. - ftfbfont.c -- font-driver on FB for FreeType fonts. - bdffbfont.c -- font-driver on FB for BDF fonts. - -Note: The fontset related codes are not yet matured to work well with -the font backend method. So, for instance, even if you start Emacs -as something like this: - % emacs -fn tahoma -Non-ASCII Latin characters will not be displayed by the font "tahoma". -In such a case, please try this: - -(set-fontset-font "fontset-default" 'latin '("tahoma" . "unicode-bmp")) - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/notes/iftc b/admin/notes/iftc deleted file mode 100644 index e8dcdd3a6d6..00000000000 --- a/admin/notes/iftc +++ /dev/null @@ -1,27 +0,0 @@ -Iso-Functional Type Contour - - -This is a term coined to describe "column int->float" change approach, and can -be used whenever low-level types need to change (hopefully not often!) but the -meanings of the values (whose type has changed) do not. - -The premise is that changing a low-level type potentially means lots of code -needs to be changed as well, and the question is how to do this incrementally, -which is the preferred way to change things. - -Say LOW and HIGH are C functions: - - int LOW (void) { return 1; } - void HIGH (void) { int value = LOW (); } - -We want to convert LOW to return float, so we cast HIGH usage: - - float LOW (void) { return 1.0; } - void HIGH (void) { int value = (int) LOW (); } /* iftc */ - -The comment /* iftc */ is used to mark this type of casting to differentiate -it from other casting. We commit the changes and can now go about modifying -LOW and HIGH separately. When HIGH is ready to handle the type change, the -cast can be removed. - -;;; arch-tag: 3309cc41-5d59-421b-b7be-c94b04083bb5 diff --git a/admin/notes/lel-TODO b/admin/notes/lel-TODO deleted file mode 100644 index 4e3ebc8f233..00000000000 --- a/admin/notes/lel-TODO +++ /dev/null @@ -1,125 +0,0 @@ -Some lisp/emacs-lisp/ Features and Where They Are Documented - -Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. -See the end of the file for license conditions. - - -* Status Key - - -- as yet unknown - n/a -- not applicable (internal, uninteresting, etc) - todo -- not documented but should be - NODE -- documented in or under info node NODE - - -* Features - advice (elisp) Advising Functions - advice-preload n/a - assoc - - authors - - autoload (elisp) Autoload - avl-tree - - backquote n/a - benchmark n/a - bindat (elisp) Byte Packing - byte-compile (elisp) Byte Compilation - byte-opt - - bytecomp (elisp) Compilation Functions - checkdoc (elisp) Documentation Tips - cl (cl) - cl-19 n/a - cl-compat n/a - cl-specs n/a - copyright - - crm - - cust-print (elisp) Printing in Edebug - debug (elisp) Debugger - derived (elisp) Derived Modes - disass (elisp) Disassembly - easy-mmode (elisp) Defining Minor Modes - easymenu - - edebug (elisp) Edebug - eldoc - - elint - - elp n/a - ewoc (elisp) Separated Rendering - find-func - - find-gc - - generic (elisp) Generic Modes - gulp n/a - helper - - levents - - lisp-float-type - - lisp-mnt - - lisp-mode n/a - lmenu - - lselect - - lucid - - macroexp (elisp) Expansion - pp (emacs) Program Indent - re-builder - - regexp-opt (elisp) Regexp Functions - regi - - ring (elisp) Rings - rx - - shadow - - sregex - - syntax (elisp) Position Parse - testcover - - timer (elisp) Timers - tq (elisp) Transaction Queues - trace - - unsafep (elisp) Function Safety - warnings (elisp) Warnings - - -* Above list created using default directory lisp/emacs-lisp/ with - (shell-command - "sed '/^(provide '\\''/!d;s// /;s/).*//' *.el | sort | uniq") - - -* How to use this file to improve Emacs - (loop - (let* ((feature (choose-one Features)) - (status (feature-status feature))) - (if (or (eq '- status) (not (verify status))) - (update feature (current-docs feature)) - (case status - (todo (let (doc patch feedback) - (while (not (grok feature)) - (or (play-with feature) - (grep feature Internet) - (grep feature (wisdom-maybe "emacs-devel")))) - (setq doc (write-documentation feature) - patch (diff (current-docs) doc)) - (while (not (and (correct doc) - (well-placed doc) - (well-formed patch))) - (setq doc (revise doc) - patch (diff (current-docs) doc)) - feedback (wisdom-maybe "emacs-devel" patch)) - (when (install patch) - (when (update feature (current-docs feature)) - (job-well-done user-login-name))))) - (n/a (job-well-done user-login-name)))))) - - -* Etc - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . - - Local variables: - mode: outline - End: diff --git a/admin/notes/multi-tty b/admin/notes/multi-tty deleted file mode 100644 index 64c8a900a1e..00000000000 --- a/admin/notes/multi-tty +++ /dev/null @@ -1,1363 +0,0 @@ --*- coding: utf-8; mode: text; -*- - -Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. -See the end of the file for license conditions. - -From README.multi-tty in the multi-tty branch. -Some of this information may be out of date. - - -THANKS ------- - -The following is a (sadly incomplete) list of people who have -contributed to the project by testing, submitting patches, bug -reports, and suggestions. Thanks! - -Bernard Adrian -ARISAWA Akihiro -Vincent Bernat -Han Boetes -Francisco Borges -Damien Cassou -Robert J. Chassell -Romain Francoise -Ami Fischman -Noah Friedman -Friedrich Delgado Friedrichs -Samium Gromoff <_deepfire@mail.ru> -Mikhail Gusarov -Eric Hanchrow -IRIE Tetsuya -Yoshiaki Kasahara -Bas Kok -Jurej Kubelka -David Lichteblau -Richard Lewis -mace -Suresh Madhu -Xavier Mallard -Istvan Marko -Ted Morse -Gergely Nagy -Dan Nicolaescu -Kalle Olavi Niemitalo -Mark Plaksin -Frank Ruell -Tom Schutzer-Weissmann -Joakim Verona -Dan Waber -and many others. - -Richard Stallman was kind enough to review an earlier version of my -patches. - - -STATUS ------- - -It still needs to be ported to Windows/Mac/DOS. Both multiple -tty device support and simultaneous X and tty frame support works -fine. Emacsclient has been extended to support opening new tty and X -frames. It has been changed to open new Emacs frames by default. - -Tested on GNU/Linux, Solaris 8, FreeBSD and OpenBSD. - -Known problems: - - * GTK support. If you compile your Emacs with the GTK - toolkit, some functionality of multi-tty may be lost. In - particular, you may get crashes while working on multiple X - displays at once. Previous releases of GTK had limitations - and bugs that prevented full-blown multi-display support in - Emacs. (GTK crashed when Emacs tries to disconnect from an - X server.) Things are much improved in the current GTK - version, but if you do experience crashes in libgtk, try - compiling Emacs with the Lucid toolkit instead. - - * The single-kboard mode. - - If your multi-tty Emacs session seems to be frozen, you - probably have a recursive editing session or a pending - minibuffer prompt (which is a kind of recursive editing) on - another display. To unfreeze your session, switch to that - display and complete the recursive edit, for example by - pressing C-] (`abort-recursive-edit'). - - I am sorry to say that currently there is no way to break - out of this "single-kboard mode" from a frozen display. If - you are unable to switch to the display that locks the - others (for example because it is on a remote computer), - then you can use emacsclient to break out of all recursive - editing sessions: - - emacsclient -e '(top-level)' - - Note that this (perhaps) unintuitive behavior is by design. - Single-kboard mode is required because of an intrinsic Emacs - limitation that is very hard to eliminate. (This limitation - is related to the single-threaded nature of Emacs.) - - I plan to implement better user notification and support for - breaking out of single-kboard mode from locked displays. - - * Mac and DOS support is broken, doesn't even - compile. Multiple display support will probably not provide - new Emacs features on these systems, but the multi-tty - branch changed a few low-level interfaces, and the - system-dependent source files need to be adapted - accordingly. The changes are mostly trivial, so almost - anyone can help, if only by compiling the branch and - reporting the compiler errors. - - -TESTING -------- - -To test the multi-tty feature, start up the Emacs server with the -following commands: - - emacs - M-x server-start - -and then (from a shell prompt on another terminal) start emacsclient -with - emacsclient -t /optional/file/names... (for a tty frame) - emacsclient /optional/file/names... (for an X frame) - -(Make sure both emacs and emacsclient are multi-tty versions.) -You'll hopefully have two fully working, independent frames on -separate terminals. The new frame is closed automatically when you -finish editing the specified files (C-x #), but delete-frame (C-x 5 0) -also works. Of course, you can create frames on more than two tty -devices. - -Creating new frames on the same tty with C-x 5 2 (make-frame-command) -works, and behaves the same way as in previous Emacs versions. If you -exit emacs, all terminals should be restored to their previous states. - -TIPS & TRICKS -------------- - -I think the best way to use the new Emacs is to have it running inside -a disconnected GNU screen session, and always use emacsclient for -normal work. One advantage of this is that not a single keystroke of -your work will be lost if the display device that you are using -crashes, or the network connection times out, or whatever. (I had an -extremely unstable X server for some time while I was developing these -patches, and running Emacs this way has saved me a number of M-x -recover-session invocations.) - -I use the following two bash scripts to handle my Emacs sessions: - --------------------------------------------------------connect-emacs-- -#!/bin/bash -# Usage: connect-emacs ... -# -# Connects to the Emacs instance called NAME. Starts up the instance -# if it is not already running. The rest of the arguments are passed -# to emacsclient. - -name="$1" -shift - -if [ -z "$name" ]; then - echo "Usage: connect_emacs ..." >&2 - exit 1 -fi -preload-emacs "$name" wait -/usr/bin/emacsclient.emacs-multi-tty -s "$name" "$@" ----------------------------------------------------------------------- - --------------------------------------------------------preload-emacs-- -#!/bin/bash -# Usage: preload-emacs [] -# -# Preloads the Emacs instance called NAME in a detached screen -# session. Does nothing if the instance is already running. If WAITP -# is non-empty, the function waits until the server starts up and -# creates its socket; otherwise it returns immediately. - -name="$1" -waitp="$2" -screendir="/var/run/screen/S-$USER" -serverdir="/tmp/emacs$UID" -emacs=/usr/bin/emacs-multi-tty # Or wherever you installed your multi-tty Emacs - -if [ -z "$name" ]; then - echo "Usage: preload_emacs []" >&2 - exit 1 -fi - -if [ ! -e "$screendir"/*."$name" ]; then - if [ -e "$serverdir/$name" ]; then - # Delete leftover socket (for the wait option) - rm "$serverdir/$name" - fi - screen -dmS "$name" "$emacs" -nw --eval "(setq server-name \"$name\")" -f server-start -fi -if [ ! -z "$waitp" ]; then - while [ ! -e "$serverdir/$name" ]; do sleep 0.1; done -fi ----------------------------------------------------------------------- - -I have the following in my profile to have two instances automatically -preloaded for editing and email: - - preload-emacs editor - preload-emacs gnus - -It is useful to set up short aliases for connect-emacs. I use the -following: - - alias edit="connect-emacs editor" - alias e=edit - alias et="connect-emacs editor -t" - alias gnus="connect-emacs gnus" - - -THINGS TO DO ------------- - -** See if `tty-defined-color-alist' needs to be terminal-local. - Update: Dan says it should be, so convert it. - -** Mikhail Gusarov suggest to add a hook akin to - `after-make-frame-functions' that is called whenever Emacs connects - to a new terminal. Good idea! - -** emacsclient -t on the console does not work after su. You have to - use non-root accounts or start as root to see this. - - Login: root - Password: - # su lorentey - $ emacsclient -t - *ERROR*: Could not open file: /dev/tty1 - - The tty can be opened as /dev/tty by emacsclient, but not by Emacs. - This seems to be a serious problem. Currently my only idea is to - bring back the ugly pty proxy hack from the initial versions of - multi-tty. Suggestions would be appreciated. - - Update: we could change emacsclient to pass its open file - descriptor to the Emacs process. Unfortunately, this requires a - new Lisp-level Emacs API, and as file descriptors are not otherwise - exported to Lisp, this approach seems at least as ugly as the pty - proxy idea. - -** lisp/vc.el depends on the terminal type during load time. - `vc-annotate-color-map' is one example that needs to be fixed. - -** Understand how `quit_throw_to_read_char' works, and fix any bugs - that come to light. - -** See if getcjmp can be eliminated somehow. Why does Emacs allow - asynchronous input processing while it's reading input anyway? - -** `delete-frame' events are handled by `special-event-map' - immediately when read by `read_char'. This is fine but it prevents - higher-level keymaps from binding that event to get notified of the - deleted frame. - - Sometimes it would be useful for Lisp code to be notified of frame - deletions after they have happened, usually because they want to - clean up after the deleted frame. Not all frame-local states can - be stored as a frame parameter. For example, - `display-splash-screen' uses `recursive-edit' with a special keymap - override to create its buffer---and it leads to all kinds of - nastiness if Emacs stays in this recursive edit mode after the - frame containing the splash screen is deleted. Basically, the - splash-screen implementation wants to throw out of the recursive - edit when the frame is deleted; however, it is not legal to throw - from `delete-frame-functions' because `delete-frame' must not fail. - (Introducing `delete-frame-after-functions' would not help either - because `delete-frame' may not fail at that time either.) - - Currently `fancy-splash-screens' installs a - `delete-frame-functions' hook that sets up a timer to exit the - recursive edit. This is an adequate solution, but it would perhaps - be better to have something like a `frame-deleted' event that could - be bound in the normal way. - -** Trouble: `setenv' doesn't actually set environment variables in the - Emacs process. This defeats the purpose of the elaborate - `server-with-environment' magic around the `tgetent' call in - `init_tty'. D'oh. - -** (Possibly) create hooks in struct device for creating frames on a - specific terminal, and eliminate the hackish terminal-related frame - parameters (display, tty, tty-type). - - make_terminal_frame - create_tty_output - -** Decide whether to keep the C implementation of terminal parameters, - or revert to the previous, purely Lisp code. It turned out that - local environments do not need terminal parameters after all. - -** Move Fsend_string_to_terminal to term.c, and declare get_named_tty - as static, removing it from dispextern.h. - Move fatal to emacs.c and declare it somewhere. - -** Search for `suspend-emacs' references and replace them with - `suspend-frame', if necessary. Ditto for `save-buffers-kill-emacs' - vs. `save-buffers-kill-display'. - -** Emacs crashes when a tty frame is resized so that there is no space - for all its windows. (Tom Schutzer-Weissmann) - -** Report GTK multi-display problems to GTK maintainers. For extra - credit, fix them. - - Currently you can not connect to new X displays when you compile - Emacs with GTK support. If you want to play around with GTK - multidisplay (and don't mind core dumps), you can edit src/config.h - and define HAVE_GTK_MULTIDISPLAY there by hand. - - http://bugzilla.gnome.org/show_bug.cgi?id=85715 - - Update: Han reports that GTK+ version 2.8.9 almost gets display - disconnects right. GTK will probably be fully fixed by the time - multi-tty gets into the trunk. - - Update: I am still having problems with GTK+ 2.8.10. I have the - impression that the various multidisplay fixes will only get - released in GTK+ 2.10. - -** Audit `face-valid-attribute-values' usage in customize and - elsewhere. Its return value depends on the current window system. - Replace static initializers using it with runtime functions. For - example, custom's buttons are broken on non-initial device types. - -** Possibly turn off the double C-g feature when there is an X frame. - C.f. (emacs)Emergency Escape. - -** frames-on-display-list should also accept frames. - -** Consider the `tty-type' frame parameter and the `display-tty-type' - function. They serve the exact same purpose. I think it may be - a good idea to eliminate one of them, preferably `tty-type'. - -** The handling of lisp/term/*.el, and frame creation in general, is a - big, big mess. How come the terminal-specific file is loaded by - tty-create-frame-with-faces? I don't think it is necessary to load - these files for each frame; once per terminal should be enough. - Update: lisp/term/*.el is not loaded repeatedly anymore, but - faces.el still needs to be cleaned up. - -** Fix frame-set-background-mode in this branch. It was recently - changed in CVS, and frame.el in multi-tty has not yet been adapted - for the changes. (It needs to look at - default-frame-background-mode.) (Update: maybe it is fixed now; - needs testing.) (Note that the byte compiler has this to say about - term/rxvt.el:) - - term/rxvt.el:309:17:Warning: assignment to free variable - `default-frame-background-mode' - -** I think `(set-)terminal-local-value' and the terminal parameter - mechanism should be integrated into a single framework. - - (Update: `(set-)terminal-local-value' is now eliminated, but the - terminal-local variables should still be accessible as terminal - parameters. This also applies to `display-name' and similar - functions.) - -** Add the following hooks: after-delete-frame-hook (for server.el, - instead of delete-frame-functions), - after-delete-terminal-functions, after-create-terminal-functions. - -** BULK RENAME: The `display-' prefix of new Lisp-level functions - conflicts with stuff like `display-time-mode'. Use `device-' - or `terminal-' instead. I think I prefer `terminal-'. - - It turns out that most of the offending Lisp functions were defined - in the trunk. Therefore, compatibility aliases should be defined - for the following names: - - display-color-cells terminal-color-cells - display-color-p terminal-color-p - display-graphic-p terminal-graphic-p - display-grayscale-p terminal-grayscale-p - display-images-p terminal-images-p - display-mm-height terminal-mm-height - display-mm-width terminal-mm-width - display-mouse-p terminal-mouse-p - display-multi-font-p terminal-multi-font-p - display-multi-frame-p terminal-multi-frame-p - display-pixel-height terminal-pixel-height - display-pixel-width terminal-pixel-width - display-pixels-per-inch terminal-pixels-per-inch - display-planes terminal-planes - display-popup-menus-p terminal-popup-menus-p - display-save-under terminal-save-under - display-screens terminal-screens - display-supports-face-attributes-p terminal-supports-face-attributes-p - display-visual-class terminal-visual-class - framep-on-display framep-on-terminal - frames-on-display-list frames-on-terminal-list - - The following functions were introduced in the multi-tty branch, and - were renamed without aliases: - - delete-display delete-terminal - display-controlling-tty-p controlling-tty-p - display-list terminal-list - display-live-p terminal-live-p - display-name terminal-name - display-tty-type tty-type - frame-display frame-terminal - selected-display selected-terminal - -** The single-keyboard mode of MULTI_KBOARD is extremely confusing - sometimes; Emacs does not respond to stimuli from other keyboards. - At least a beep or a message would be important, if the single-mode - is still required to prevent interference. (Reported by Dan - Nicolaescu.) - - Update: selecting a region with the mouse enables single_kboard - under X. This is very confusing. - - Update: After discussions with Richard Stallman, this will be - resolved by having locked displays warn the user to wait, and - introducing a complex protocol to remotely bail out of - single-kboard mode by pressing C-g. - - Update: Warning the user is not trivial to implement, as Emacs has - only one echo area, shared by all frames. Ideally the warning - should not be displayed on the display that is locking the others. - Perhaps the high probability of user confusion caused by - single_kboard mode deserves a special case in the display code. - Alternatively, it might be good enough to signal single_kboard mode - by changing the modelines or some other frame-local display element - on the locked out displays. - - Update: In fact struct kboard does have an echo_string slot. - -** The session management module is prone to crashes when the X - connection is closed and then later I try to connect to a new X - session: - - #0 0xb7ebc806 in SmcGetIceConnection () from /usr/X11R6/lib/libSM.so.6 - #1 0x080e6641 in x_session_check_input (bufp=0xbf86c9c0) at xsmfns.c:144 - #2 0x080d3bbc in XTread_socket (device=0xa722ff8, expected=1, hold_quit=0xbf86ca90) at xterm.c:7037 - #3 0x080fa404 in read_avail_input (expected=1) at keyboard.c:6696 - #4 0x080fa4ca in handle_async_input () at keyboard.c:6900 - #5 0x080d51fa in x_term_init (display_name=162628899, xrm_option=0x0, resource_name=0x857068c "emacs") at xterm.c:10622 - #6 0x080d920e in x_display_info_for_name (name=162628899) at xfns.c:3975 - #7 0x080d92f9 in check_x_display_info (object=1) at xfns.c:274 - #8 0x080d97b8 in Fx_create_frame (parms=151221485) at xfns.c:3016 - #9 0x0815bf72 in Ffuncall (nargs=2, args=0xbf86ceec) at eval.c:2851 - - I installed a workaround to prevent this. The X session manager is - only contacted when the very first display in the Emacs session is - an X display. Also, x_delete_display() on this display aborts - session management, and XTread_socket only calls - x_session_check_input when it is called for the display that the - session was opened on. While this does not really fix the bug, it - makes it much less frequent, because session manager support will - not normally be enabled when Emacs can survive the shutdown of the - X server. - - See if xsmfns.c should be updated. - -** Hunt down display-related functions in frame.el and extend them all - to accept display ids. - -** rif->flush_display_optional (NULL) calls should be replaced by a - new global function. - -** The set-locale-environment hack (adding the DISPLAY option) should - be replaced with a clean design. - -** standard-display-table should be display-local. - standard-display-european should be display-local. - -** With iswitchb-default-method set to 'always-frame, only frames on - the current display should be considered. This might involve - extending `get-buffer-window'. - -** Have a look at Vlocale_coding_system. Seems like it would be a - tedious job to localize it, although most references use it for - interfacing with libc and are therefore OK with the global - definition. - - Exceptions found so far: x-select-text and - x-cut-buffer-or-selection-value. - -** Have a look at fatal_error_hook. - -** Have a look at set_frame_matrix_frame. - -** Check if we got term-setup-hook right. - -** I think tip_frame should be display-local. - -** Check display reference count handling in x_create_tip_frame. - -** make-frame does not correctly handle extra parameters in its - argument: - - (frame-parameter (make-frame (list (cons 'foobar 42))) 'foobar) - => nil - - (This is likely an error in the CVS trunk.) - -** Dan Nicolaescu suggests that -nw should be added as an alias for -t - in emacsclient. Good idea. (Alas, implementing this is not - trivial, getopt_long does not seem to support two-letter ``short'' - options. Patches are welcome.) - -** Mark Plaksin suggests that emacsclient should accept the same - X-related command-line arguments as Emacs. Most of the X-related - argument-handling is done in Lisp, so this should be quite easy to - implement. (For example, Samium Gromoff wants emacsclient to - support --geometry; implementing this would add that support.) - -** Gergely Nagy suggests that C-x # should only kill the current - frame, not any other emacsclient frame that may have the same file - opened for editing. I think I agree with him. - -** Very strange bug: visible-bell does not work on secondary - terminals in xterm and konsole. The screen does flicker a bit, - but it's so quick it isn't noticable. - - (Update: This is probably some problem with padding or whatnot on - the secondary terminals.) - -** Move baud_rate to struct display. - -** Implement support for starting an interactive Emacs session without - an initial frame. (The user would connect to it and open frames - later, with emacsclient.) - -** Fix Mac support (I can't do this entirely myself). Note that the - current state of Mac-specific source files in the multi-tty tree - are not useful; before starting work on Mac support, revert to - pristine, pre-multi-tty versions. - -** Fix DOS support (I can't do this entirely myself). Note that the - current state of DOS-specific source files in the multi-tty tree - are not useful; before starting work on DOS support, revert to - pristine, pre-multi-tty versions. - -** Fix Windows support. Currently bootstraping works on w32, but Emacs - crashes on startup and none of the multi-tty features are - implemented. Many XXX comments mark things that probably need - updating, ChangeLogs will help in spotting changes to X specific - files that may need porting. - -** Do a grep on XXX and ?? for more issues. - -** flow-ctrl.el must be updated. - -** Fix stuff_char for multi-tty. Doesn't seem to be of high priority. - -DIARY OF CHANGES ----------------- - -(ex-TODO items with explanations.) - --- Introduce a new struct for terminal devices. - - (Done, see struct tty_output. The list of members is not yet - complete.) - --- Change the bootstrap procedure to initialize tty_list. - - (Done, but needs review.) - --- Change make-terminal-frame to support specifying another tty. - - (Done, new frame parameters: `tty' and `tty-type'.) - --- Implement support for reading from multiple terminals. - - (Done, read_avail_input tries to read from each terminal, until one - succeeds. MULTI_KBOARD is not used. Secondary terminals don't send - SIGIO!) - - (Update: They do, now.) - - (Update2: After enabling X, they don't.) - --- other-frame should cycle through the frames on the `current' - terminal only. - - (Done, by trivially modifiying next_frame and prev_frame.) - --- Support different terminal sizes. - - (Done, no problem.) - --- Make sure terminal resizes are handled gracefully. (Could be - problematic.) - - (Done. We don't get automatic SIGWINCH for additional ttys, - though.) - --- Extend emacsclient to automatically open a new tty when it connects - to Emacs. - - (Done. It's an ugly hack, needs more work.) - --- Redisplay must refresh the topmost frame on *all* terminals, not - just the initial terminal. - - (Done, but introduced an ugly redisplay problems. Ugh.) - --- Fix redisplay problems. - - (Done; it turned out that the entire Wcm structure must be moved - inside tty_output. Why didn't I catch this earlier?) - --- Provide a way for emacsclient to tell Emacs that the tty has been - resized. - - (Done, simply forward the SIGWINCH signal.) - --- Each keypress should automatically select the frame corresponding - to the terminal that it was coming from. This means that Emacs - must know from which terminal the last keyboard event came from. - - (Done, it was quite simple, the input event system already - supported multiple frames.) - --- Fix SIGIO issue with secondary terminals. - - (Done, emacsclient signals Emacs after writing to the proxy pseudo - terminal. Note that this means that multi-tty does not work with - raw ttys!) - - (Update: This is bullshit. There is a read_input_waiting function, - extend that somehow.) - - (Update of update: The first update was not right either, extending - read_input_waiting was not necessary. Secondary ttys do seem to - send signals on input.) - - (Update^3: Not any more.) - --- Make make-terminal-frame look up the `tty' and `tty-type' frame - parameters from the currently selected terminal before the global - default. - - (Done.) - --- Put all cached terminal escape sequences into struct tty_output. - Currently, they are still stored in global variables, so we don't - really support multiple terminal types. - - (Done. It was not fun.) - --- Implement sane error handling after initialization. (Currently - emacs exits if you specify a bad terminal type.) The helpful error - messages must still be provided when Emacs starts. - - (Done.) - --- Implement terminal deletion, i.e., deleting local frames, closing - the tty device and restoring its previous state without exiting - Emacs. - - (Done, but at the moment only called when an error happens during - initialization. There is a memory corruption error around this - somewhere.) (Update: now it is fully enabled.) - --- Implement automatic deletion of terminals when the last frame on - that terminal is closed. - - (Done.) - --- Restore tty screen after closing the terminal. - - (Done, we do the same as Emacs 21.2 for all terminals.) - --- 'TERM=dumb src/emacs' does not restore the terminal state. - - (Done.) - --- C-g should work on secondary terminals. - - (Done, but the binding is not configurable.) - --- Deal with SIGHUP in Emacs and in emacsclient. (After this, the - server-frames may be removed from server.el.) - - (Done, nothing to do. It seems that Emacs does not receive SIGHUP - from secondary ttys, which is actually a good thing.) (Update: I - think it would be a bad idea to remove server-frames.) - --- Change emacsclient/server.el to support the -t argument better, - i.e. automatically close the socket when the frame is closed. - - (Seems to be working OK.) - --- Fix mysterious memory corruption error with tty deletion. To - trigger it, try the following shell command: - - while true; do TERM=no-such-terminal-definition emacsclient -h; done - - Emacs usually dumps core after a few dozen iterations. (The bug - seems to be related to the xfreeing or bzeroing of - tty_output.Wcm. Maybe there are outside references to struct Wcm? - Why were these vars collected into a struct before multi-tty - support?) - - (Done. Whew. It turned out that the problem had nothing to do - with hypothetical external references to Wcm, or any other - tty_output component; it was simply that delete_tty closed the - filehandles of secondary ttys twice, resulting in fclose doubly - freeing memory. Utterly trivial matter. I love the C's memory - management, it puts hair on your chest.) - --- Support raw secondary terminals. (Note that SIGIO works only on - the controlling terminal.) Hint: extend read_input_waiting for - multiple ttys and hopefully this will be fixed. - - (Done, it seems to have been working already for some time. It - seems F_SETOWN does work, after all. Not sure what made it fail - earlier, but it seems to be fixed (there were several changes - around request_sigio, maybe one of them did it). - read_input_waiting is only used in sys_select, don't change - it.) (Update: After adding X support, it's broken again.) - (Update^2: No it isn't.) :-) - --- Find out why does Emacs abort when it wants to close its - controlling tty. Hint: chan_process[] array. Hey, maybe - noninterrupt-IO would work, too? Update: no, there is no process - for stdin/out. - - (Done. Added add/delete_keyboard_wait_descriptor to - term_init/delete_tty. The hint was right, in a way.) - --- Issue with SIGIO: it needs to be disabled during redisplay. See if - fcntl kernel behavior could be emulated by emacsclient. - - (Done. Simply disabled the SIGIO emulation hack in emacsclient.) - (Update: it was added back.) (Update^2: and removed again.) - --- server.el: There are issues with saving files in buffers of closed - clients. Try editing a file with emacsclient -f, and (without - saving it) do a delete-frame. The frame is closed without - question, and a surprising confirmation prompt appears in another - frame. - - (Done. delete-frame now asks for confirmation if it still has - pending buffers, and modified buffers don't seem to be deleted.) - --- emacsclient.el, server.el: Handle eval or file open errors when - doing -t. - - (Done.) - --- Make parts of struct tty_output accessible from Lisp. The device - name and the type is sufficient. - - (Done, see frame-tty-name and frame-tty-type.) - --- Export delete_tty to the Lisp environment, for emacsclient. - - (Done, see delete-tty.) - --- Get rid of the accessor macros in termchar.h, or define macros for - all members. - - (Done.) - --- Move device-specific parameters (like costs) commonly used by - device backends to a common, device-dependent structure. - - (Done. See struct display_method in termhooks.h.) - --- Fix X support. - - (Done. Well, it seems to be working.) - --- Allow simultaneous X and tty frames. (Handling input could be - tricky. Or maybe not.) - - (Done. Allowed, that is. It is currently extremely unstable, to - the point of being unusable. The rif variable causes constant - core dumps. Handling input is indeed tricky.) - --- Rewrite multi-tty input in terms of MULTI_KBOARD. - - (Done. In fact, there was no need to rewrite anything, I just - added a kboard member to tty_display_info, and initialized the - frame's kboard from there.) - --- Fix rif issue with X-tty combo sessions. IMHO the best thing to do - is to get rid of that global variable (and use the value value in - display_method, which is guaranteed to be correct). - - (Done, did exactly that. Core dumps during combo sessions became - much rarer. In fact, I have not yet met a single one.) - --- Add multi-tty support to talk.el. - - (Done.) - --- Clean up the source of emacsclient. It is a mess. - - (Done, eliminated stupid proxy-pty kludge.) - --- Fix faces on tty frames during X-tty combo sessions. There is an - init_frame_faces call in init_sys_modes, see if there is a problem - with it. - - (Done, there was a stupid mistake in - Ftty_supports_face_attributes_p. Colors are broken, though.) - --- C-x 5 2, C-x 5 o, C-x 5 0 on an emacsclient frame unexpectedly - exits emacsclient. This is a result of trying to be clever with - delete-frame-functions. - - (Fixed, added delete-tty-after-functions, and changed server.el to - use it.) - --- Something with (maybe) multi-keyboard support broke function keys - and arrows on ttys during X+tty combo sessions. Debug this. - - (I can't reproduce it, maybe the terminal type was wrong.) - --- Fix input from raw ttys (again). - - (Now it seems to work all right.) - --- During an X-tty combo session, a (message "Hello") from a tty frame - goes to the X frame. Fix this. - - (Done. There was a safeguard against writing to the initial - terminal frame during bootstrap which prevented echo_area_display - from working correctly on a tty frame during a combo session.) - --- If there are no frames on its controlling terminal, Emacs should - exit if the user presses C-c there. - - (Done, as far as possible. See the SIGTERM comment in - interrupt_signal on why this seems to be impossible to solve this - in general.) - --- During an X session, Emacs seems to read from stdin. Also, Emacs - fails to start without a controlling tty. - - (Fixed by replacing the troublesome termcap display with a dummy - bootstrap display during bootstrap. - --- Do tty output through struct display, like graphical display - backends. - - (Done.) - --- Define an output_initial value for output_method for the initial - frame that is dumped with Emacs. Checking for this frame (e.g. in - cmd_error_internal) is ugly. - - (Done, breaking interactive temacs.) - --- The command `emacsclient -t -e '(delete-frame)'' fails to exit. - - (Fixed.) - --- frame-creation-function should always create a frame that is on the - same display as the selected frame. Maybe frame-creation-function - should simply be removed and make-frame changed to do the right - thing. - - (Done, with a nice hack. frame-creation-function is now frame-local.) - --- Fix C-g on raw ttys. - - (Done. I disabled the interrupt/quit keys on all secondary - terminals, so Emacs sees C-g as normal input. This looks like an - overkill, because emacsclient has extra code to pass SIGINT to - Emacs, so C-g should remain the interrupt/quit key on emacsclient - frames. See the next entry why implementing this distinction would - be a bad idea.) - --- Make sure C-g goes to the right frame with ttys. This is hard, as - SIGINT doesn't have a tty parameter. :-( - - (Done, the previous change fixes this as a pleasant side effect.) - --- I have seen a case when Emacs with multiple ttys fell into a loop - eating 100% of CPU time. Strace showed this loop: - - getpid() = 30284 - kill(30284, SIGIO) = 0 - --- SIGIO (I/O possible) @ 0 (0) --- - ioctl(6, FIONREAD, [0]) = -1 EIO (Input/output error) - ioctl(5, FIONREAD, [0]) = -1 EIO (Input/output error) - ioctl(0, FIONREAD, [0]) = 0 - sigreturn() = ? (mask now []) - gettimeofday({1072842297, 747760}, NULL) = 0 - gettimeofday({1072842297, 747806}, NULL) = 0 - select(9, [0 3 5 6], NULL, NULL, {0, 0}) = 2 (in [5 6], left {0, 0}) - select(9, [0 3 5 6], NULL, NULL, {0, 0}) = 2 (in [5 6], left {0, 0}) - gettimeofday({1072842297, 748245}, NULL) = 0 - - I have seen something similar with a single X frame, but have not - been able to reproduce it for debugging. - - Update: This may have been caused by checking for nread != 0 - instead of nread > 0 after calling read_socket_hook in - read_avail_input. - - (Fixed. This was caused by unconditionally including stdin in - input_wait_mask in init_process. The select call in - wait_reading_process_input always returned immediately, indicating - that there is pending input from stdin, which nobody read. - - Note that the above strace output seems to be an unrelated but - similar bug. I think that is now fixed.) - --- Exiting Emacs while there are emacsclient frames doesn't restore the - ttys to their default states. - - (This seems to be fixed by some previous change.) - --- Allow opening an X session after -nw. - - (Done.) - --- Fix color handling during tty+X combo sessions. (It seems that tty - sessions automatically convert the face colors to terminal colors - when the face is loaded. This conversion must happen instead on - the fly in write_glyphs, which might be problematic, as color - approximation is currently done in lisp (term/tty-colors.el).) - (Update: hm, colors seem to work fine if I start emacs with -nw and - then create an X frame. Maybe it's just a small buglet somewhere.) - - (Seems to be fixed. The problem was in startup.el, it did not - initialize tty colors when the initial window system was - graphical.) - --- emacs -nw --eval '(y-or-n-p "Foobar")' segfaults. (Reported by - Romain Francoise) - - (Fixed, there was a keyboard initialization problem.) - --- Fix interactive use of temacs. There are face-related SEGVs, most - likely because of changes in realize_default_face, realize_face. - - (Fixed.) - --- Don't exit Emacs when the last X connection fails during a - multi-display session. - - (Fixed.) - --- Dan Nicolaescu noticed that starting emacsclient on the same - terminal device that is the controlling tty of the Emacs process - gives unexpected results. - - (Fixed.) - --- Istvan Marko reported that Emacs hang on ttys if it was started - from a shell script. - - (Fixed. There was a bug in the multi-tty version of - narrow_foreground_group. tcsetpgrp blocks if it is called from a - process that is not in the same process group as the tty.) - --- emacsclient -t from an Emacs term buffer does not work, complains - about face problems. This can even lock up Emacs (if the recursive - frame sets single_kboard). Update: the face problems are caused by - bugs in term.el, not in multi-tty. The lockup is caused by - single_kboard mode, and is not easily resolvable. The best thing to - do is to simply refuse to create a tty frame of type `eterm'. - - (Fixed, changed emacsclient to check for TERM=eterm. The face - complaints seem to be caused by bugs in term.el; they are not - related to multi-tty.) - --- Find out the best way to support suspending Emacs with multiple - ttys. My guess: disable it on the controlling tty, but from other - ttys pass it on to emacsclient somehow. (It is (I hope) trivial to - extend emacsclient to handle suspend/resume. A `kill -STOP' almost - works right now.) - - (Done. I needed to play with signal handling and the server - protocol a bit to make emacsclient behave as a normal UNIX program - wrt foreground/background process groups.) - --- There is a flicker during the startup of `emacs -nw'; it's as if - the terminal is initialized, reset and then initialialized again. - Debug this. (Hint: narrow_foreground_group is called twice during - startup.) - - (This is gone.) - --- Robert Chassell has found serious copy-paste bugs with the - multi-tty branch. There seem to be redisplay bugs while copying - from X to a terminal frame. Copying accented characters do not - work for me. - - (Patch-124 should fix this, by changing the interprogram-*-function - variables to be frame-local, as suggested by Mark Plaksin - (thanks!). I think that the redisplay bugs are in fact not bugs, - but delays caused by single_kboard --> perhaps MULTI_KBOARD should - be removed.) - --- frame-creation-function was removed, which might be a bad idea. - Think up a compatible solution. - - (It was an internal interface that may be changed when necessary.) - --- Change Lisp code not to (getenv "TERM"); use the `tty-type' frame - parameter or the frame-tty-type function instead. (M-x tags-search - "TERM" helps with this.) Update: Actually, all getenv invocations - should be checked for multi-tty compatibility, and an interface - must be implemented to get the remote client's environment. - - (Done. Only getenv calls in lisp/term/*.el were changed; other - calls should be mostly left as they are.) - --- Add an elaborate mechanism for display-local variables. (There are - already a few of these; search for `terminal-local' in the Elisp - manual.) - - (Not needed. Display-local variables could be emulated by - frame-local variables.) - --- Emacs assumes that all terminal frames have the same locale - settings as Emacs itself. This may lead to bogus results in a - multi-locale setup. (E.g., while logging in from a remote client - with a different locale.) - (Update after new bugreport by Friedrich Delgado Friedrichs: - (at least) the structs terminal_coding and keyboard_coding in - coding.c must be moved to struct display, and the Lisp interface - [set-]keyboard-coding-system must be adapted for the change.) - - (Fixed. Emacs now uses the locale settings as seen by the - emacsclient process for server tty frames.) - (Update: Not really; Vlocale_coding_system is still global.) - --- Make `struct display' accessible to Lisp programs. Accessor functions: - - (displayp OBJECT): Returns t if OBJECT is a display. - => Implemented as display-live-p. - - (display-list): Returns list of currently active displays. - => Implemented. - - (selected-display): Returns the display object of the selected frame. - => Not strictly necessary, but implemented anyway. - - (frame-display FRAME): Returns the display object of FRAME. - => Implemented. - - (display-frames DISPLAY): Returns a list of frames on DISPLAY. - => Already implemented, see frames-on-display-list. - - (display-type DISPLAY): Returns the type of DISPLAY, as a - symbol. (See `framep'.) - => Implemented as display-live-p. - - (display-device DISPLAY): Returns the name of the device that - DISPLAY uses, as a string. (E.g: "/dev/pts/16", or - ":0.0") - => Implemented as display-name. - - etc. - - See next issue why this is necessary. - - (Update: The consensus on emacs-devel seems to be to do this via - integer identifiers. That's fine by me.) - - (Done.) - --- The following needs to be supported: - - $ emacsclient -t - C-z - $ emacsclient -t - (This fails now.) - - The cleanest way to solve this is to allow multiple displays on the - same terminal device; each new emacsclient process should create - its own display. As displays are currently identified by their - device names, this is not possible until struct display becomes - accessible as a Lisp-level object. - - (Done.) - --- Miles Bader suggests that C-x C-c on an emacsclient frame should - only close the frame, not exit the entire Emacs session. Update: - see above for a function that does this. Maybe this should be the - new default? - - (Done. This is the new default. No complaints so far.) - --- Clean up the frame-local variable system. I think it's ugly and - error-prone. But maybe I just haven't yet fully understood it. - - (Nothing to do. It doesn't seem ugly any more. It's rather clever.) - --- Support multiple character locales. A version of - `set-locale-environment' needs to be written for setting up - display-local settings on ttys. I think calling - set-display-table-and-terminal-coding-system and - set-keyboard-coding-system would be enough. The language - environment itself should remain a global setting. - - (Done, by an ugly hack.) - --- The terminal customization files in term/*.el tend to change global - parameters, which may confuse Emacs with multiple displays. Change - them to tweak only frame-local settings, if possible. (They tend - to call define-key to set function key sequences a lot.) - - (Done, by making `function-key-map' terminal-local (i.e., part of - struct kboard). This has probably covered all the remaining problems.) - --- Make `function-key-map' and `key-translation-map' terminal-local. - - (Done.) - --- Implement `terminal-local-value' and `set-terminal-local-value' to - allow deterministic access to terminal local bindings. The - encode-kb package can not set up `key-translation-map' without - these. The terminal-local bindings seem to be independent of what - frame is selected. - - (Done.) - --- xt-mouse.el needs to be adapted for multi-tty. It currently - signals an error on kill-emacs under X, which prevents the user - from exiting Emacs. (Reported by Mnemonikk on freenode.) - - (Done, I hope.) - - --- Having {reset,init}_all_sys_modes in set-input-mode breaks arrow - keys on non-selected terminals under screen, and sometimes on other - terminal types as well. The other function keys continue to work - fine. Sometimes faces on these screens become garbled. - - This only seems to affect displays that are of the same terminfo - type as the selected one. Interestingly, in screen Emacs normally - reports the up arrow key as `M-o A', but after the above SNAFU, it - complains about `M-[ a'. UNIX ttys are a complete mystery to me, - but it seems the reset-reinitialize cycle somehow leaves the - non-selected terminals in a different state than usual. I have no - idea how this could happen. - - Currently set-input-mode resets only the currently selected - terminal, which seems to somehow work around the problem. - - Update: - - Dan Nicolaescu writes: - > Some terminals have 2 modes for cursor keys: Application Mode where - > the cursor keys transmit the codes defined in the terminfo entry, and - > Cursor mode. Applications have to send the smkx and rmkx terminfo - > strings to switch between the 2 modes. So Emacs (and emacsclient) have - > to send smkx when initializing and rmkx when quitting (or on - > suspend). - - (I think patch-370 fixed this.) - --- This long-standing bug (first reported by Han Boetes) seems to come - and go all the time. It is time to track it down and fix it. - - emacs - M-x server-start - - # From another xterm: - emacsclient -e '(y-or-n-p "Do you want me to crash? ")' - # Notice how the answer ends up in the *scratch* buffer - M-x garbage-collect - SIGSEGV - - (Fixed in patch-414 after detailed analysis by Kalle Olavi Niemitalo.) - --- normal-erase-is-backspace-mode in simple.el needs to be updated for - multi-tty (rep. by Dan Waber). (The Delete key is broken on X - because of this.) - - (Fixed in patch-427.) - --- I think keyboard-translate-table should be made terminal-local. - - (Done in patch-431.) - --- The semantics of terminal-local variables are confusing; it is not - clear what binding is in effect in any given time. See if - current_kboard (or at least the terminal-local bindings exported to - Lisp) might be changed to be tied to the selected frame instead. - Currently, `function-key-map' and `key-translation-map' may be - accessed reliably only using the hackish - `(set-)terminal-local-value' functions. - - Perhaps there should be a difference between `last-command' &co. - and these more conventional configuration variables. - (E.g. `symbol-value' would use current_kboard to access - `last-command', but SELECTED_FRAME()->display->kboard to get the - value of `function-key-map'. - - (Fixed in patch-434.) - --- If the first key pressed on a new tty terminal is a function key, - it is not recognized correctly. May be related to the bug below. - - (Seems to have been fixed as a side effect of patch-434. "The bug - below" was the set-input-mode madness.) - - (Update: this bug was fixed for good in patch-449. It was tracked - down to a bug in `read_key_sequence': it failed to reinitialize its - local function-key-map/key-translation-map references when it - switched keyboards. I don't understand why did this bug only - appear on brand new frames, though!) - --- Disable connecting to a new X display when we use the GTK toolkit. - - (Disabled in patch-450.) - --- Implement automatic forwarding of client environment variables to - forked processes, as discussed on the multi-tty list. Terminal - parameters are now accessible in C code, so the biggest obstacle is - gone. The `getenv_internal' and `child_setup' functions in - callproc.c must be changed to support the following variable: - - terminal-local-environment-variables is a variable defined in ... - - Enable or disable terminal-local environment variables. - - If set to t, `getenv', `setenv' and subprocess creation - functions use the environment variables of the emacsclient - process that created the selected frame, ignoring - `process-environment'. - - If set to nil, Emacs uses `process-environment' and ignores - the client environment. - - Otherwise, `terminal-local-environment-variables' should be a - list of variable names (represented by Lisp strings) to look - up in the client environment. The rest will come from - `process-environment'. - - (Implemented in patch-461; `terminal-getenv', `terminal-setenv' and - `with-terminal-environment' are now replaced by extensions to - `getenv' and `setenv', and the new `local-environment-variables' - facility. Yay!) - - (Updated in patch-465 to fix the semantics of let-binding - `process-environment'. `process-environment' was changed to - override all local/global environment variables, and a new variable - `global-environment' was introduced to have `process-environment's - old meaning.) - - (Updated in patch-466 to fix the case when two emacsclient sessions - share the same terminal, but have different environment. The local - environment lists are now stored as frame parameters, so the - C-level terminal parameters are not strictly necessary any more.) - --- `Fdelete_frame' is called from various critical places where it is - not acceptable for the frame deletion to fail, e.g. from - x_connection_closed after an X error. `Fdelete_frame' now protects - against `delete-frame-functions' throwing an error and preventing a - frame delete. (patch-475) - --- Fix set-input-mode for multi-tty. It's a truly horrible interface; - what if we'd blow it up into several separate functions (with a - compatibility definition)? - - (Done. See `set-input-interrupt-mode', `set-output-flow-control', - `set-input-meta-mode' and `set-quit-char'.) (patch-457) - --- Let-binding `overriding-terminal-local-map' on a brand new frame - does not seem to work correctly. (See `fancy-splash-screens'.) - The keymap seems to be set up right, but events go to another - terminal. Or is it `unread-command-events' that gets Emacs - confused? Investigate. - - (Emacs was confused because a process filter entered - `recursive-edit' while Emacs was reading input. I added support - for this in the input system.) (patch-489) - --- I smell something funny around pop_kboard's "deleted kboard" case. - Determine what are the circumstances of this case, and fix any - bug that comes to light. - - (It happens simply because single_kboard's terminal is sometimes - deleted while executing a command on it, for example the one that - kills the terminal. There was no bug here, but I rewrote the whole - single_kboard mess anyway.) (patch-489) - --- Understand Emacs's low-level input system (it's black magic) :-) - What exactly does interrupt_input do? I tried to disable it for - raw secondary tty support, but it does not seem to do anything - useful. (Update: Look again. X unconditionally enables this, maybe - that's why raw terminal support is broken again. I really do need - to understand input.) - (Update: I am starting to understand the read_key_sequence->read-char - ->kbd_buffer_get_event->read_avail_input->read_socket_hook path. Yay!) - - (Update: OK, it all seems so easy now (NOT). Input could be done - synchronously (with wait_reading_process_input), or asynchronously - by SIGIO or polling (SIGALRM). C-g either sets the Vquit_flag, - signals a 'quit condition (when immediate_quit), or throws to - `getcjmp' when Emacs was waiting for input when the C-g event - arrived.) - --- Replace wrong_kboard_jmpbuf with a special return value of - read_char. It is absurd that we use setjmp/longjmp just to return - to the immediate caller. - - (Done in patch-500.) - --- `tool-bar-mode', `scroll-bar-mode', `menu-bar-mode' and - 'fringe-mode' are modes global to the entire Emacs session, not - just a single frame or a single terminal. This means that their - status sometimes differs from what's actually displayed on the - screen. As a consequence, the Options | Show/Hide menu sometimes - shows incorrect status, and you have to select an option twice for - it to have any visible effect on the current frame. - - Change Emacs so that the status of the items in the Options | - Show/Hide menu correspond to the current frame. - - (Done in patch-537.) - --- The `default-directory' variable should somehow be set to the - cwd of the emacsclient process when the user runs emacsclient - without file arguments. Perhaps it is OK to just override the - directory of the *scratch* buffer. - - (Done in patch-539.) - --- The borders on tooltip frames on X are messed up. More - specifically, the frame's internal border (internal-border-width - frame parameter) is not filled with the correct background color. - - It seems the border contents are drawn onto by the - update_single_window call in `x-show-tip'. After some debugging, I - think the window's background color is not set up - correctly---calling `x_clear_area' fills the specified area with - black, not light yellow. - - (Done in patch-544. A background_pixel field was defined both in - struct frame and struct x_output, and Emacs got confused between - them.) - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . - -;;; arch-tag: 8da1619e-2e79-41a8-9ac9-a0485daad17d diff --git a/admin/notes/trailing-whitespace b/admin/notes/trailing-whitespace deleted file mode 100644 index e29456b3a2f..00000000000 --- a/admin/notes/trailing-whitespace +++ /dev/null @@ -1,8 +0,0 @@ -ttn 2003-02-14 - -apparently there was a big discussion on emacs-devel wrt trailing whitespace. -there was a mass-change to remove such from various branches in cvs. probably -it's a good idea to avoid adding trailing whitespace in new code/docs and in -changes. - -;;; arch-tag: de441379-c345-4826-a784-352b5413a698 diff --git a/admin/notes/unicode b/admin/notes/unicode deleted file mode 100644 index b3dbaa221b1..00000000000 --- a/admin/notes/unicode +++ /dev/null @@ -1,144 +0,0 @@ - -*-mode: text; coding: latin-1;-*- - -Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - -Problems, fixmes and other unicode-related issues -------------------------------------------------------------- - -Notes by fx to record various things of variable importance. handa -needs to check them -- don't take too seriously, especially with -regard to completeness. - - * SINGLE_BYTE_CHAR_P returns true for Latin-1 characters, which has - undesirable effects. E.g.: - (multibyte-string-p (let ((s "x")) (aset s 0 ?£) s)) => nil - (multibyte-string-p (concat [?£])) => nil - (text-char-description ?£) => "M-#" - - These examples are all fixed by the change of 2002-10-14, but - there still exist questionable SINGLE_BYTE_CHAR_P in the - code (keymap.c and print.c). - - * Rationalize character syntax and its relationship to the Unicode - database. (Applies mainly to symbol an punctuation syntax.) - - * Fontset handling and customization needs work. We want to relate - fonts to scripts, probably based on the Unicode blocks. The - presence of small-repertoire 10646-encoded fonts in XFree 4 is a - pain, not currently worked round. - - With the change on 2002-07-26, multiple fonts can be - specified in a fontset for a specific range of characters. - Each range can also be specified by script. Before using - ISO10646 fonts, Emacs checks their repertories to avoid such - fonts that don't have a glyph for a specific character. - - fx has worked on fontset customization, but was stymied by - basic problems with the way the default face is dealt with - (and something else, I think). This needs revisiting. - - * Work is also needed on charset and coding system priorities. - - * The relevant bits of latin1-disp.el need porting (and probably - re-naming/updating). See also cyril-util.el. - - * Quail files need more work now the encoding is largely irrelevant. - - * What to do with the old coding categories stuff? - - * The preferred-coding-system property of charsets should probably be - junked unless it can be made more useful now. - - * find-multibyte-characters needs looking at. - - * Implement Korean cp949/UHC, BIG5-HKSCS and any other important missing - charsets. - - * Lazy-load tables for unify-charset somehow? - - Actually, Emacs clears out all charset maps and unify-map just - before dumping, and they are loaded again on demand by the - dumped emacs. But, those maps (char tables) generated while - temacs is running can't be removed from the dumped emacs. - - * Translation tables for {en,de}code currently aren't supported. - - This should be fixed by the changes of 2002-10-14. - - * Defining CCL coding systems currently doesn't work. - - This should be fixed by the changes of 2003-01-30. - - * iso-2022 charsets get unified on i/o. - - With the change on 2003-01-06, decoding routines put `charset' - property to decoded text, and iso-2022 encoder pay attention - to it. Thus, for instance, reading and writing by - iso-2022-7bit preserve the original designation sequences. - The property name `preferred-charset' may be better? - - We may have to utilize this property to decide a font. - - * Revisit locale processing: look at treating the language and - charset parts separately. (Language should affect things like - spelling and calendar, but that's not a Unicode issue.) - - * Handle Unicode combining characters usefully, e.g. diacritics, and - handle more scripts specifically (à la Devanagari). There are - issues with canonicalization. - - * Bidi is a separate issue with no support currently. - - * We need tabular input methods, e.g. for maths symbols. (Not - specific to Unicode.) - - * Need multibyte text in menus, e.g. for the above. (Not specific to - Unicode -- see Emacs etc/TODO, but now mostly works with gtk.) - - * There's currently no support for Unicode normalization. - - * Populate char-width-table correctly for Unicode characters and - worry about what happens when double-width charsets covering - non-CJK characters are unified. - - * Emacs 20/21 .elc files are currently not loadable. It may or may - not be possible to do this properly. - - With the change on 2002-07-24, elc files generated by Emacs - 20.3 and later are correctly loaded (including those - containing multibyte characters and compressed). But, elc - files generated by 20.2 and the primer are still not loadable. - Is it really worth working on it? - - * Rmail won't work with non-ASCII text. Encoding issues for Babyl - files need sorting out, but rms says Babyl will go before this is - released. - - * Gnus still needs some attention, and we need to get changes - accepted by Gnus maintainers... - - * There are type errors lurking, e.g. in - Fcheck_coding_systems_region. Define ENABLE_CHECKING to find them. - - * You can grep the code for lots of fixmes. - - * Old auto-save files, and similar files, such as Gnus drafts, - containing non-ASCII characters probably won't be re-read correctly. - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/notes/years b/admin/notes/years deleted file mode 100644 index cdd7cbe4b5f..00000000000 --- a/admin/notes/years +++ /dev/null @@ -1,30 +0,0 @@ -HOW TO MAINTAIN COPYRIGHT YEARS FOR GNU EMACS - -Maintaining copyright years is now very simple: every time a new year -rolls around, add that year to every FSF (and AIST) copyright notice. - -There's no need to worry about whether an individual file has changed -in a given year - it's sufficient that Emacs as a whole has changed. - -For more detailed information on maintaining copyright, see the file -"copyright" in this directory. - -The previous policy was more complex, but is now only of historical -interest (see versions of this file from before 2009). - -The refcards in etc/refcards can print only the latest copyright year, -but should keep the full list in a comment in the source. - - -"Our lawyer says it is ok if we add, to each file that has been in Emacs - since Emacs 21 came out in 2001, all the subsequent years[1]. We don't - need to check whether *that file* was changed in those years. - It's sufficient that *Emacs* was changed in those years (and it was!). - - For those files that have been added since then, we should add - the year it was added to Emacs, and all subsequent years." - - --RMS, 2005-07-13 - -[1] Note that this includes 2001 - see - diff --git a/admin/nt/README-UNDUMP.W32 b/admin/nt/README-UNDUMP.W32 deleted file mode 100644 index bf64d03ac6c..00000000000 --- a/admin/nt/README-UNDUMP.W32 +++ /dev/null @@ -1,59 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - Emacs for Windows - -This README file describes how to dump a bare precompiled version of -GNU Emacs for Windows. This barebin distribution supplements the -standard distribution of Emacs, which you can download from: - - ftp://ftp.gnu.org/gnu/emacs/ - -If you do not have the "bin" or "src" distribution, then you will need -to download one of those before you can use this barebin version. - -An additional feature of the barebin version that is not present in -the bin distribution is that it contains an undumped binary of Emacs -(temacs.exe). This can be used to dump Emacs yourself. Note that you -should only need to dump Emacs yourself if you want to dump Emacs with -more elisp files than are included normally, or to rebuild Emacs after -patching one of the elisp files that is preloaded. - -The dumping process consists of running a bare Emacs, loading up a -number of general elisp files, and then creating a new Emacs executable -preinitialized and ready to run. In the precompiled distributions, -Emacs has already been dumped with the standard configuration. - -To dump Emacs, unpack this distribution into the directory created by -unpacking the corresponding standard src or bin distribution. To -verify that you unpacked in the proper place, check to make sure that -you now have a temacs.exe file in the bin directory. - -Once you have unpacked this distribution, cd into the bin directory and -run dump.bat. This will produce a new bin\emacs.exe executable for you -to use (the original one is renamed to emacs.exe.orig; this is not -overwritten if you run dump more than once). - -For more information about running Emacs, read the README.W32 file -that came with this distribution. If you need help using Emacs on -Windows, including problems with dumping, send email to -. - -Enjoy! - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/nt/README-ftp-server b/admin/nt/README-ftp-server deleted file mode 100644 index 208752d0b0d..00000000000 --- a/admin/nt/README-ftp-server +++ /dev/null @@ -1,281 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - Precompiled Distributions of - Emacs for Windows - - Version 23.0.96 - - July 9, 2009 - - This directory contains precompiled distributions for GNU Emacs on - Windows (versions before Windows 95 and NT4 are not supported). - This port is a part of the standard GNU Emacs distribution from the - Free Software Foundation; the precompiled distributions are provided - here for convenience since the majority of Windows users are not - accustomed to compiling programs themselves. Corresponding source - can be found in the parent directory in emacs-23.0.96.tar.gz. - - If you have access to the World Wide Web, I would recommend pointing - your favorite web browser to the following document (if you haven't - already): - - http://www.gnu.org/software/emacs/windows/ntemacs.html - -* IMPORTANT LEGAL REMINDER - - If you want to redistribute any of the precompiled distributions of - Emacs, be careful to check the implications of the GPL. For instance, - if you put the emacs-23.0.96-bin-i386.tar.gz file from this directory on - an Internet site, you must arrange to distribute the source files of - the SAME version (i.e. ../emacs-23.0.96.tar.gz). - - Making a link to our copy of the source is NOT sufficient, since we - might upgrade to a new version while you are still distributing the - old binaries. - - -* Files in this directory - - + emacs-23.0.96-bin-i386.zip - Windows binaries of Emacs-23.0.96, with all lisp code and documentation - included. - - Download this file if you want a single installation package, and - are not interested in the C source code for Emacs. After - unpacking, you can optionally run the file bin/addpm.exe to have - Emacs add icons to the Start Menu. - - If you need the C source code at a later date, it will be safe to - unpack the source distribution on top of this installation. - - + emacs-23.0.96-barebin-i386.zip - Windows binaries of Emacs-23.0.96, without lisp code or documentation. - - Download this file if you already have the source distribution. - - Unpack this over the top of the source distribution. It contains the - bin subdirectory and etc/DOC file. - - + libxpm-3.5.7-w32-src.zip - Source code required to compile libXpm-3.5.7 on Windows. Contains - a basic Makefile for compiling with mingw32 and a .def file for - generating a DLL with the appropriate exports in addition to the - source code to provide the subset of functionality Emacs uses from - libXpm. This corresponds to the libXpm.dll in emacs-23.0.96-bin-i386.zip - and emacs-23.0.96-barebin-i386.zip. - -* Image support - - Emacs 23.0.96 contains support for images, however for most image formats - supporting libraries are required. This distribution has been tested - with the libraries that are distributed with GTK for Windows, and the - libraries found at http://gnuwin32.sourceforge.net/. The following image - formats are supported: - - PBM/PGM/PPM: Supported natively by Emacs. This format is used for - the black and white versions of the toolbar icons. - - XPM: a Windows port of the XPM library corresponding to the x.org - release of X11R7.3 is included with the binary distribution, but - can be replaced by other versions with the name xpm4.dll, - libxpm-nox4.dll or libxpm.dll. - - PNG: requires the PNG reference library 1.2 or later, which will - be named libpng13d.dll, libpng13.dll, libpng12d.dll, libpng12.dll - or libpng.dll. LibPNG requires zlib, which should come from the same - source as you got libpng. - - JPEG: requires the Independant JPEG Group's libjpeg 6b or later, - which will be called jpeg62.dll, libjpeg.dll, jpeg-62.dll or jpeg.dll. - - TIFF: requires libTIFF 3.0 or later, which will be called libtiff3.dll - or libtiff.dll. - - GIF: requires libungif or giflib 4.1 or later, which will be - called giflib4.dll, libungif4.dll or libungif.dll. - - SVG: not compiled into the binary release, but available if you - compile Emacs yourself if you have development packages for all the - dependencies. Requires many libraries from GTK and Gnome - as well as the base librsvg library. Known to crash Emacs on many - sample images. - -* Distributions in .tar.gz and .zip format - - Emacs is distributed primarily as source code in a large gzipped tar - file (*.tar.gz). Because Emacs is quite large and therefore - difficult to download over unreliable connections, the Windows - binaries are provided in two combinations. The complete lisp source - plus executables (bin), and executables only (barebin) for unpacking - over the top of the source distribution. Formerly, we used the same - .tar.gz format but since there are no longer legal problems with - .zip files, and the latest versions of Windows support these - natively, the Windows binaries of Emacs are now distributed as .zip - files. - -* Distributions for non-x86 platforms - - Distributions for non-x86 platforms are no longer supplied. Older - platforms supported by Windows NT no longer seem to be in demand, - and Emacs is yet to be ported to 64 bit Windows platforms. If you - are willing to help port Emacs 23 to 64 bit versions of Windows, - your contribution will be welcome on the emacs-devel mailing list. - -* Unpacking distributions - - Ports of GNU gzip and GNU tar for handling the source distribution file - format can be found in several places that distribute ports of GNU - programs, for example: - - Cygwin: http://www.cygwin.com/ - GnuWin32: http://gnuwin32.sourceforge.net/ - - Many other popular file compression utilities for Windows are also - able to handle gzipped tar files. 7zip is one free Windows graphical - program that is able to handle many archive formats. - - Open a command prompt (MSDOS) window. Decide on a directory in which - to place Emacs. Move the distribution to that directory, and then - unpack it as follows. - - If you have the gzipped tar version, use gunzip to uncompress the tar - file on the fly, and pipe the output through tar with the "xvf" flags - to extract the files from the tar file: - - % gunzip -c some.tar.gz | tar xvf - - - You may see messages from tar about not being able to change the - modification time on directories, and from gunzip complaining about a - broken pipe. These messages are harmless and you can ignore them. On - Windows NT, unpacking tarballs this way leaves them in compressed - form, taking up less space on disk. Unfortunately, on Windows 95 and - 98, a large temporary file is created, so it is better to use the - djtarnt.exe program, which performs the equivalent operation in one - step: - - % djtarnt -x some.tar.gz - - You may be prompted to rename or overwrite directories when using - djtarnt: simply type return to continue (this is harmless). - - Zip files can be unpacked using unzip.exe from info-zip.org - if you do not already have other tools to do this. - - % unzip some.zip - - The precompiled binaries can be unpacked using unzip.exe from info-zip.org - if you do not already have other tools to do this. - - % unzip some.zip - - Once you have unpacked a precompiled distribution of Emacs, it should - have the following subdirectories: - - bin etc info lisp site-lisp - - -* Unpacking with other tools - - If you do use other utility programs to unpack the distribution, check - the following to be sure the distribution was not corrupted: - - + Be sure to disable the CR/LF translation or the executables will - be unusable. Older versions of WinZip would enable this - translation by default when unpacking .tar files. If you are - using WinZip, disable it. (I don't have WinZip myself, and I do - not know the specific commands necessary to disable it.) - - + Check that filenames were not truncated to 8.3. For example, there - should be a file lisp/abbrevlist.el; if this has been truncated to - abbrevli.el, your distribution has been corrupted while unpacking - and Emacs will not start. - - + Check that filenames were not changed by your web-browser. Some - proprietary web-browsers save .tar.gz files as .tar.tar. You might - like to consider switching to a Free modern browser if your browser - has this bug. - - + I've also had reports that some older "gnuwin32" port of tar - corrupts the executables. Use the latest version from the gnuwin32 - site or another port of tar instead. - - If you believe you have unpacked the distributions correctly and are - still encountering problems, see the section on Further Information - below. - - -* Compiling from source - - If you would like to compile Emacs from source, download the source - distribution, unpack it in the same manner as a precompiled - distribution, and look in the file nt/INSTALL for detailed - directions. It is recommended to use GCC 2.95 or later with MinGW - support to compile the source. The port of GCC included in Cygwin - is supported, but check the nt/INSTALL file if you have trouble - since some builds of GNU make aren't supported. - - -* Further information - - If you have access to the World Wide Web, I would recommend pointing - your favorite web browser to following the document (if you haven't - already): - - http://www.gnu.org/software/emacs/windows/ntemacs.html - - This document serves as an FAQ and a source for further information - about the Windows port and related software packages. Note that as - most of the information in that FAQ is for earlier versions, so some - information may not be relevant to Emacs-23.0.96. - - In addition to the FAQ, there is a mailing list for discussing issues - related to the Windows port of Emacs. For information about the - list, see this Web page: - - http://lists.gnu.org/mailman/listinfo/help-emacs-windows - - To ask questions on the mailing list, send email to - help-emacs-windows@gnu.org. (You don't need to subscribe for that.) - To subscribe to the list or unsubscribe from it, fill the form you - find at http://mail.gnu.org/mailman/listinfo/help-emacs-windows as - explained there. - - Another valuable source of information and help which should not be - overlooked is the various Usenet news groups dedicated to Emacs. - These are particuarly good for help with general issues which aren't - specific to the Windows port of Emacs. The main news groups to use - for seeking help are: - - gnu.emacs.help - comp.emacs - - There are also fairly regular postings and announcements of new or - updated Emacs packages on this group: - - gnu.emacs.sources - - Enjoy! - - Jason Rumney - (jasonr@gnu.org) - - Most of this README was contributed by former maintainer Andrew Innes - (andrewi@gnu.org) - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/nt/README.W32 b/admin/nt/README.W32 deleted file mode 100644 index 28008e97942..00000000000 --- a/admin/nt/README.W32 +++ /dev/null @@ -1,264 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - Emacs for Windows - - This README file describes how to set up and run a precompiled - version of GNU Emacs for Windows. This distribution can be found on - the ftp.gnu.org server and its mirrors: - - ftp://ftp.gnu.org/gnu/emacs/windows/ - - This server contains other distributions, including the full Emacs - source distribution and a barebin distribution which can be installed - over it, as well as older releases of Emacs for Windows. - - Answers to frequently asked questions, and further information about - this port of GNU Emacs and related software packages can be found via - http: - - http://www.gnu.org/software/emacs/windows/ - -* Preliminaries - - Along with this file should be six subdirectories (bin, etc, info, - lisp, leim, site-lisp). If you have downloaded the barebin - distribution, then it will contain only the bin directory and the - built in documentation in etc/DOC-X, the rest of the subdirectories - are in the src distribution, which the barebin distribution is - designed to be used with. - -* Setting up Emacs - - To install Emacs, simply unpack all the files into a directory of - your choice, but note that you might encounter minor problems if - there is a space anywhere in the directory name. To complete the - installation process, you can optionally run the program addpm.exe - in the bin subdirectory. This will put an icon for Emacs in the - Start Menu under "Start -> Programs -> Gnu Emacs". - - Some users have reported that the Start Menu item is not created for - them. If this happens, just create your own shortcut to runemacs.exe, - eg. by dragging it on to the desktop or the Start button. - - Note that running addpm is now an optional step; Emacs is able to - locate all of its files without needing any information to be set in - the environment or the registry, although such settings will still - be obeyed if present. This is convenient for running Emacs on a - machine which disallows registry changes, or on which software - should not be installed. For instance, you can now run Emacs - directly from a CD or USB flash drive without copying or installing - anything on the machine itself. - -* Starting Emacs - - To run Emacs, simply select Emacs from the Start Menu, or invoke - runemacs.exe directly from Explorer or from a command prompt. This - will start Emacs in its default GUI mode, ready to use. If you have - never used Emacs before, you should follow the tutorial at this - point (select Emacs Tutorial from the Help menu), since Emacs is - quite different from ordinary Windows applications in many respects. - - If you want to use Emacs in tty or character mode within a command - window, you can start it by typing "emacs -nw" at the command prompt. - (Obviously, you need to ensure that the Emacs bin subdirectory is in - your PATH first, or specify the path to emacs.exe.) The -nw - (non-windowed) mode of operation is most useful if you have a telnet - server on your machine, allowing you to run Emacs remotely. - -* EXE files included - - Emacs comes with the following executable files in the bin directory. - - + emacs.exe - The main Emacs executable. As this is designed to run - as both a text-mode application (emacs -nw) and as a GUI application, - it will pop up a command prompt window if run directly from Explorer. - - + runemacs.exe - A wrapper for running Emacs as a GUI application - without popping up a command prompt window. - - + emacsclient.exe - A command-line client program that can - communicate with a running Emacs process. See the `Emacs Server' - node of the Emacs manual. - - + emacsclientw.exe - A version of emacsclient that does not open - a command-line window. - - + addpm.exe - A basic installer that creates Start Menu icons for Emacs. - Running this is optional. - - + cmdproxy.exe - Used internally by Emacs to work around problems with - the native shells in various versions of Windows. - - + ctags.exe, etags.exe - Tools for generating tag files. See the - `Tags' node of the Emacs manual. - - + ebrowse.exe - A tool for generating C++ browse information. See the - `Ebrowse' manual. - - + ddeclient.exe - A tool for interacting with DDE servers. - - + hexl.exe - A tool for converting files to hex dumps. See the - `Editing Binary Files' node of the Emacs manual. - - + movemail.exe - A helper application for safely moving mail from - a mail spool or POP server to a local user mailbox. See the - `Movemail' node of the Emacs manual. - - + digest-doc.exe, sorted-doc.exe - Tools for rebuilding the - built-in documentation. - -* Image support - - Emacs has built in support for XBM and PPM/PGM/PBM images, and the - libXpm library is bundled, providing XPM support (required for color - toolbar icons and splash screen). Source for libXpm should be available - on the same place as you got this binary distribution from. The version - of libXpm bundled with this version of Emacs is 3.5.7, based on x.org's - libXpm library from X11R7.3. - - Emacs can also support some other image formats with appropriate - libraries. These libraries are all available as part of GTK, or from - gnuwin32.sourceforge.net. Emacs will find them if the directory they - are installed in is on the PATH. - - PNG: requires the PNG reference library 1.2 or later, which will - be named libpng13d.dll, libpng13.dll, libpng12d.dll, libpng12.dll - or libpng.dll. LibPNG requires zlib, which should come from the same - source as you got libpng. - - JPEG: requires the Independant JPEG Group's libjpeg 6b or later, - which will be called jpeg62.dll, libjpeg.dll, jpeg-62.dll or jpeg.dll. - - TIFF: requires libTIFF 3.0 or later, which will be called libtiff3.dll - or libtiff.dll. - - GIF: requires libungif or giflib 4.1 or later, which will be - called giflib4.dll, libungif4.dll or libungif.dll. - - In addition, Emacs can be compiled to support SVG. This precompiled - distribution has not been compiled that way, since the SVG library - or one or more of its extensive dependencies appear to be - unreliable under Windows. See nt/INSTALL in the src distribution if - you wish to compile Emacs with SVG support. - -* Uninstalling Emacs - - If you should need to uninstall Emacs, simply delete all the files - and subdirectories from the directory where it was unpacked (Emacs - does not install or update any files in system directories or - anywhere else). If you ran the addpm.exe program to create the - registry entries and the Start menu icon, then you can remove the - registry entries using regedit. All of the settings are written - under the Software\GNU\Emacs key in HKEY_LOCAL_MACHINE, or if you - didn't have administrator privileges when you installed, the same - key in HKEY_CURRENT_USER. Just delete the whole Software\GNU\Emacs - key. - - The Start menu entry can be removed by right-clicking on the Task bar - and selecting Properties, then using the Remove option on the Start - Menu Programs page. (If you installed under an account with - administrator privileges, then you need to click the Advanced button - and look for the Gnu Emacs menu item under All Users.) - -* Troubleshooting - - Unpacking the distributions - - If you encounter trouble trying to run Emacs, there are a number of - possible causes. Check the following for indications that the - distribution was not corrupted by the tools used to unpack it: - - * Be sure to disable CR/LF translation or the executables will - be unusable. Older versions of WinZipNT would enable this - translation by default. If you are using WinZipNT, disable it. - (I don't have WinZipNT myself, and I do not know the specific - commands necessary to disable it.) - - * Check that filenames were not truncated to 8.3. For example, - there should be a file lisp\abbrevlist.elc; if this has been - truncated to abbrevli.elc, your distribution has been corrupted - while unpacking and Emacs will not start. - - If you believe you have unpacked the distributions correctly and are - still encountering problems, see the section on Further Information - below. - - Virus scanners - - Some virus scanners interfere with Emacs' use of subprocesses. If you - are unable to use subprocesses and you use Dr. Solomon's WinGuard or - McAfee's Vshield, turn off "Scan all files" (WinGuard) or "boot sector - scanning" (McAfee exclusion properties). - -* Further information - - If you have access to the World Wide Web, I would recommend pointing - your favorite web browser to the following document (if you haven't - already): - - http://www.gnu.org/software/emacs/windows/ - - This document serves as an FAQ and a source for further information - about the Windows port and related software packages. - - In addition to the FAQ, there is a mailing list for discussing issues - related to the Windows port of Emacs. For information about the - list, see this Web page: - - http://lists.gnu.org/mailman/listinfo/help-emacs-windows - - To ask questions on the mailing list, send email to - help-emacs-windows@gnu.org. (You don't need to subscribe for that.) - To subscribe to the list or unsubscribe from it, fill the form you - find at http://lists.gnu.org/mailman/listinfo/help-emacs-windows as - explained there. - - Another valuable source of information and help which should not be - overlooked is the various Usenet news groups dedicated to Emacs. - These are particularly good for help with general issues which aren't - specific to the Windows port of Emacs. The main news groups to use - for seeking help are: - - gnu.emacs.help - comp.emacs - - There are also fairly regular postings and announcements of new or - updated Emacs packages on this group: - - gnu.emacs.sources - -* Reporting bugs - - If you encounter a bug in this port of Emacs, we would like to hear - about it. First check the FAQ on the web page above to see if the bug - is already known and if there are any workarounds. Then check whether - the bug has something to do with code in your .emacs file, e.g. by - invoking Emacs with the "-Q" option. - - If you decide that it is a bug in Emacs, use the built in bug - reporting facility to report it (from the menu; Help -> Send Bug Report). - If you have not yet configured Emacs for mail, then when you press - C-c C-c to send the report, it will ask you to paste the text of the - report into your mail client. If the bug is related to subprocesses, - also specify which shell you are using (e.g., include the values of - `shell-file-name' and `explicit-shell-file-name' in your message). - - Enjoy! - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/admin/nt/dump.bat b/admin/nt/dump.bat deleted file mode 100755 index c0e95426ccb..00000000000 --- a/admin/nt/dump.bat +++ /dev/null @@ -1,23 +0,0 @@ -@echo off -rem Run temacs.exe to recreate the dumped emacs.exe. -rem This is only likely to be useful on systems where the prebuilt -rem emacs.exe crashes on startup. - -rem First save original emacs.exe if present -if exist emacs.exe.orig goto dump -echo Saving original emacs.exe as emacs.exe.orig -ren emacs.exe emacs.exe.orig - -:dump -rem Overwrites emacs.exe if still present -mkdir obj -mkdir obj\i386 -mkdir obj\etc -copy ..\etc\DOC* obj\etc -copy temacs.exe obj\i386 -obj\i386\temacs -batch -l loadup dump -copy obj\i386\emacs.exe . - -goto skipArchTag - arch-tag: 0ca3036d-3a1e-47ea-87c6-9c0845253496 -:skipArchTag diff --git a/admin/nt/makedist.bat b/admin/nt/makedist.bat deleted file mode 100755 index 31679829c95..00000000000 --- a/admin/nt/makedist.bat +++ /dev/null @@ -1,65 +0,0 @@ -@echo off - -rem Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -rem Free Software Foundation, Inc. - -rem Cannot use brackets in andrewi's email below because -rem older Windows shells will treat that as redirection. - -rem Author: Andrew Innes andrewi@gnu.org - -rem This file is part of GNU Emacs. - -rem GNU Emacs is free software: you can redistribute it and/or modify -rem it under the terms of the GNU General Public License as published by -rem the Free Software Foundation, either version 3 of the License, or -rem (at your option) any later version. - -rem GNU Emacs is distributed in the hope that it will be useful, -rem but WITHOUT ANY WARRANTY; without even the implied warranty of -rem MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -rem GNU General Public License for more details. - -rem You should have received a copy of the GNU General Public License -rem along with GNU Emacs. If not, see http://www.gnu.org/licenses/. - - -if (%3) == () goto usage -if not (%4) == () goto %4 - -:bin - -echo Create full bin distribution -copy %3\README.W32 emacs-%1\README.W32 -rem Info-ZIP zip seems to be broken on Windows. -rem It always writes to zip.zip and treats the zipfile argument as one -rem of the files to go in it. -rem zip -9 -r %2-bin-i386 emacs-%1/BUGS emacs-%1/COPYING emacs-%1/README emacs-%1/README.W32 emacs-%1/INSTALL emacs-%1/bin emacs-%1/etc emacs-%1/info emacs-%1/lisp emacs-%1/leim -x emacs.mdp *.pdb *.opt *~ CVS -7z a -tZIP -mx=9 -xr!emacs.mdp -xr!*.pdb -xr!*.opt -xr!*~ -xr!CVS -xr!.arch-inventory %2-bin-i386.zip emacs-%1/BUGS emacs-%1/COPYING emacs-%1/README emacs-%1/README.W32 emacs-%1/INSTALL emacs-%1/bin emacs-%1/etc emacs-%1/info emacs-%1/lisp emacs-%1/leim emacs-%1/site-lisp -del emacs-%1\README.W32 -if not (%4) == () goto end - -:barebin -echo Create archive with just the basic binaries and generated files -echo (the user needs to unpack the full source distribution for -echo everything else) -copy %3\README.W32 emacs-%1\README.W32 -rem Info-ZIP zip seems to be broken on Windows. -rem It always writes to zip.zip and treats the zipfile argument as one -rem of the files to go in it. -rem zip -9 -r %2-barebin-i386.zip emacs-%1/README.W32 emacs-%1/bin emacs-%1/etc/DOC-X emacs-%1/COPYING -7z a -tZIP -mx=9 %2-barebin-i386.zip emacs-%1/README.W32 emacs-%1/bin emacs-%1/etc/DOC-X emacs-%1/COPYING -del emacs-%1\README.W32 -if not (%4) == () goto end - -goto end - -:usage -echo Generate source and binary distributions of emacs. -echo Usage: %0 emacs-version dist-basename distfiles [bin,barebin] -echo (e.g., %0 19.34 emacs-19.34.5 d:\andrewi\distfiles) -:end - -goto skipArchTag - arch-tag: 6e2ddd92-c1c9-4992-b6b5-207aaab72f68 -:skipArchTag diff --git a/admin/quick-install-emacs b/admin/quick-install-emacs deleted file mode 100755 index 88f57b65e80..00000000000 --- a/admin/quick-install-emacs +++ /dev/null @@ -1,378 +0,0 @@ -#!/bin/sh -### quick-install-emacs --- do a halfway-decent job of installing emacs quickly - -## Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -## Free Software Foundation, Inc. - -## Author: Miles Bader - -## This file is part of GNU Emacs. - -## GNU Emacs is free software: you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation, either version 3 of the License, or -## (at your option) any later version. - -## GNU Emacs is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. - -## You should have received a copy of the GNU General Public License -## along with GNU Emacs. If not, see . - - -### Commentary: - -## This script is mainly intended for emacs maintainer or pretesters who -## install emacs very often. See the --help output for more details. - - -PUBLIC_LIBSRC_BINARIES='b2m emacsclient etags ctags ebrowse' -PUBLIC_LIBSRC_SCRIPTS='grep-changelog rcs-checkin' - -AVOID="CVS -DIC README COPYING ChangeLog ~ [.]orig$ [.]rej$ Makefile makefile stamp-subdir [.]cvsignore [.]arch-ids [{]arch[}] [.][cho]$ make-docfile testfile test-distrib" - -# Prune old binaries lying around in the source tree -PRUNE=no -# Re-install files even if they already exist -FORCE=no -# Command verbose flag -VERBOSE='' - -me="`basename $0`" - -# Install commands (if the user specifies the `--verbose' option, it is -# passed to these commands, so that feature only works if these commands -# implement it too) -LINK='cp -lf' -COPY='cp -f' -REMOVE='rm -r' -MKDIR='mkdir -p' - -# Used to execute commands once once we create them -EXEC='sh' - -NAWK=/usr/bin/nawk - -# avoid non-standard command output from non-C locales -unset LANG LC_ALL LC_MESSAGES - -# Some messages -USAGE="Usage: $me [OPTION...] BUILD_TREE [PREFIX]" -TRY="Try "\`"$me --help' for more information." - -# Parse command-line options -while :; do - case "$1" in - -n|--dry-run) - EXEC=cat; shift;; - -p|--prune) - PRUNE=yes; shift;; - -P|--no-prune) - PRUNE=no; shift;; - --prune-only) - PRUNE=only; shift;; - -f|--force) - FORCE=yes; shift;; - -v|--verbose) - VERBOSE="-v"; shift;; - --help) - cat < -EOF - exit 0 - ;; - -[^-]?*) - # split concatenated single-letter options apart - FIRST="$1"; shift - set -- `echo $FIRST | sed 's/-\(.\)\(.*\)/-\1 -\2/'` "$@" - ;; - -*) - echo 1>&2 "$me: unrecognized option "\`"$1'" - echo 1>&2 "$TRY" - exit 1 - ;; - *) - break; - esac -done - -LINK_CMD="$LINK $VERBOSE" -REMOVE_CMD="$REMOVE $VERBOSE" - -case $# in - 1) BUILD="$1";; - 2) BUILD="$1"; prefix="$2";; - *) - echo 1>&2 "$USAGE" - echo 1>&2 "$TRY" - exit 1 - ;; -esac - -if test ! -d "$BUILD"; then - echo 1>&2 "$me: $BUILD: Build tree not found" - exit 2 -elif test ! -r "$BUILD/config.status"; then - echo 1>&2 "$me: $BUILD: Not a proper build tree, config.status not found" - exit 2 -fi - -CONFIG_STATUS="$BUILD/config.status" -get_config_var () -{ - { sed -n "s/^S[[]\"$1\"[]]=\"\([^\"]*\)\"/\1/p" $CONFIG_STATUS | sed q | grep ''; } || - { sed -n "s/^s\(.\)@$1@\1\(|#_!!_#|\)*\(.*\)\1.*$/\3/p" $CONFIG_STATUS | sed q | grep ''; } || - { - echo 1>&2 "$me: $1: Configuration variable not found in $CONFIG_STATUS" - exit 4 - } -} - -test x"$SRC" = x && { SRC="`get_config_var srcdir`" || exit 4 ; } -test x"$prefix" = x && { prefix="`get_config_var prefix`" || exit 4 ; } -test x"$ARCH" = x && { ARCH="`get_config_var host`" || exit 4 ; } - -VERSION=`grep 'defconst[ ]*emacs-version' $SRC/lisp/version.el \ - | sed -e 's/^[^"]*"\([^"]*\)".*$/\1/'` - -DST_SHARE="$prefix/share/emacs/$VERSION" -DST_BIN="$prefix/bin" -DST_LIBEXEC="$prefix/libexec/emacs/$VERSION/$ARCH" - -# There are various common places for the info dir to be, so try to -# use whatever's already there, defaulting to (and preferring) -# .../share/info. -# -DST_INFO='' -for D in "$prefix/share/info" "$prefix/info"; do - if test -d "$D"; then - DST_INFO="$D" - break - fi -done -DST_INFO=${DST_INFO:-"$prefix/share/info"} - -maybe_mkdir () -{ - if ! test -d "$1"; then - $MKDIR $VERBOSE "$1" 2>&1 | sed "s/^mkdir:/$me:/" 1>&2 - fi -} - -maybe_mkdir "$DST_BIN" -maybe_mkdir "$DST_SHARE" -maybe_mkdir "$DST_SHARE/site-lisp" -maybe_mkdir "$DST_LIBEXEC" -maybe_mkdir "$DST_INFO" - -( # start of command-generating sub-shell - -PRUNED="" -if test x"$PRUNE" != xno; then - for D in `ls -1t $BUILD/etc/DOC-* | sed 1d`; do - echo $REMOVE_CMD $D - PRUNED="$PRUNED $D" - done - for D in `ls -1t $BUILD/src/emacs-$VERSION.* | sed 1d`; do - echo $REMOVE_CMD $D - PRUNED="$PRUNED $D" - done -fi - -test x"$PRUNE" = xonly && exit 0 - -maybe_emit_copy () -{ - if test "$FORCE" = yes || ! cmp -s $1 $2; then - echo $LINK_CMD $1 $2 - fi -} - -maybe_emit_copy $BUILD/src/emacs $DST_BIN/emacs -maybe_emit_copy $BUILD/src/emacs $DST_BIN/emacs-$VERSION - -for F in $PUBLIC_LIBSRC_BINARIES; do - maybe_emit_copy $BUILD/lib-src/$F $DST_BIN/$F -done -for F in $PUBLIC_LIBSRC_SCRIPTS; do - maybe_emit_copy $SRC/lib-src/$F $DST_BIN/$F -done - -if test x"$SRC" = x"$BUILD"; then - PFXS="$BUILD" -else - PFXS="$SRC $BUILD" -fi - -for SUBDIR in lisp leim etc lib-src info; do - # defaults - SHARED=no - FORCED='' - AVOID_PAT="`echo "($AVOID)" | tr ' ' '|'`" - - # Set subdir-specific values - case $SUBDIR in - lisp|leim) - DST="$DST_SHARE/$SUBDIR" - ;; - etc) - DST="$DST_SHARE/$SUBDIR" - # COPYING is in the avoid list, but there should be a copy of it in - # the install etc dir, so make that here. - FORCED="$DST/COPYING" - ;; - lib-src) - DST="$DST_LIBEXEC" - AVOID_PAT="`echo "($AVOID ($PUBLIC_LIBSRC_BINARIES $PUBLIC_LIBSRC_SCRIPTS)\$)" | tr ' ' '|'`" - ;; - info) - DST="$DST_INFO" - SHARED=yes - ;; - esac - - for PFX in $PFXS; do - if [ -d $PFX/$SUBDIR ]; then - for DIR in `(cd $PFX/$SUBDIR; find . -type d -print | sed 's@^./@@')`; do - if [ -d $DST/$DIR ]; then - echo Directory $DST/$DIR exists - else - echo Directory $DST/$DIR non-existant - if [ "`echo $DIR | egrep -v "$AVOID_PAT"`" ]; then - maybe_mkdir $DST/$DIR - fi - fi - done - diff -sqr $PFX/$SUBDIR $DST - fi - done | $NAWK ' -BEGIN { - src_pat = "^'"$SRC"'/'"$SUBDIR"'/" - build_pat = "^'"$BUILD"'/'"$SUBDIR"'/" - dst_pat = "^'"$DST"'/" - dst_pfx = "'"$DST"'/" - avoid_pat = "'"$AVOID_PAT"'" - force = ("'"$FORCE"'" == "yes") - shared = ("'"$SHARED"'" == "yes") - init_bool_array(pruned, "'"$PRUNED"'") - init_bool_array(forced, "'"$FORCED"'") -} -function init_bool_array(array, string, a,k) -{ - split (string, a) - for (k in a) - array[a[k]] = 1 -} -function install(src, dst) -{ - if (! (src in pruned)) { - cp[src] = dst; - from[dst] = src; - delete rm[dst]; - } -} -function update(src, dst, copy) -{ - if (src in pruned) { - rm[dst] = 1; - delete from[dst] - } else { - if (copy) - cp[src] = dst; - from[dst] = src; - delete rm[dst]; - } -} -function uninstall(dst) -{ - if (!(dst in from)) - rm[dst] = 1; -} -/^Directory / { - if ($2 ~ avoid_pat) { - if ($NF == "exists") - uninstall($2) - } else - update(0, $2, 0) - next -} -/^Files / { - if ($4 ~ avoid_pat && !($4 in forced)) - uninstall($4) - else if ($NF == "identical") - update($2, $4, force) - else - update($2, $4, 1) - next -} -/^Only / { - pfx = $3 - sub (/:$/, "/", pfx) - - if (pfx ~ dst_pat) { - if (! shared) - uninstall(pfx $4) - } else { - subdir = pfx - if (subdir ~ src_pat) - sub (src_pat, "", subdir) - else - sub (build_pat, "", subdir) - - dst = dst_pfx subdir $4 - if (! (dst ~ avoid_pat)) - install(pfx $4, dst) - } - next -} -END { - for (f in rm) - print "'"$REMOVE_CMD"' " f - for (f in cp) - print "'"$LINK_CMD"' " f " " cp[f] -} -' -done - -) | eval $EXEC - -# arch-tag: 9322b572-9755-4cf7-a67a-21e6505f1477 diff --git a/admin/revdiff b/admin/revdiff deleted file mode 100755 index 9921c35452f..00000000000 --- a/admin/revdiff +++ /dev/null @@ -1,137 +0,0 @@ -#! /usr/bin/perl - -# Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. -# -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -use File::Basename; - -if (@ARGV < 3) -{ - print <', use the Nth revision before the current one for OLD. - -If NEW is + or -, build diffs between revisions OLD -and OLD +/- . - -Examples: - -revdiff FILE - -1 get the latest change of FILE -revdiff FILE -1 +1 also gets the latest change of FILE -revdiff FILE 1.500 +2 get diffs 1.500-1.501 and 1.501-1.502. - -USAGE - exit 1; -} - -$file = shift @ARGV; -$old = shift @ARGV; - -sub diffit -{ - my ($old, $new) = @_; - print "cvs diff -r$old -r$new $file >$file-$old-$new.diff\n"; - system "cvs diff -r$old -r$new $file >$file-$old-$new.diff"; -} - -sub current_revision ($) -{ - my ($file) = @_; - my $dir = dirname ($file); - my $base = basename ($file); - my $entries = "$dir/CVS/Entries"; - die "Can't find $entries" unless -f $entries; - open (IN, "<$entries") or die "Cannot open $entries"; - my $rev; - while ($line = ) - { - if ($line =~ m,/$base/([^/]+),) - { - $rev = $1; - break; - } - } - die "Cannot determine current revision of $file" unless $rev; - close (IN); - return $rev; -} - -if ($old eq "-") - { - $old = current_revision ($file); - } -elsif ($old =~ /^-(\d+)$/) - { - my $offset = $1; - $old = current_revision ($file); - die "Internal error" unless $old =~ /(.*)\.(\d+)$/; - my $minor = $2 - $offset; - $old = sprintf ("%d.%d", $1, $minor); - } - -while (@ARGV) - { - my $new = shift @ARGV; - if ($new =~ /^[+]\d+$/) - { - my $n = $new; - for ($i = 0; $i < $n; ++$i) - { - unless ($old =~ /(.*)\.(\d+)$/) - { - die "Internal error"; - } - my $j = $2 + 1; - $new = "$1.$j"; - diffit ($old, $new); - $old = $new; - } - } - elsif ($new =~ /^[-]\d+$/) - { - my $n = - $new; - for ($i = 0; $i < $n; ++$i) - { - unless ($old =~ /(.*)\.(\d+)$/) - { - die "Internal error"; - } - my $j = $2 - 1; - $new = "$1.$j"; - diffit ($new, $old); - $old = $new; - } - } - else - { - diffit ($old, $new); - $old = $new; - } - } - -# Local Variables: -# mode: cperl -# End: - -# arch-tag: 2798b20d-c7f2-4c78-8378-7bb529c36a09 diff --git a/admin/unidata/.arch-inventory b/admin/unidata/.arch-inventory deleted file mode 100644 index 6dbe37ac041..00000000000 --- a/admin/unidata/.arch-inventory +++ /dev/null @@ -1,4 +0,0 @@ -# Generated at compile time -precious ^unidata\.txt$ - -# arch-tag: 7640ff84-9e72-45e6-a7c7-b7b307b73959 diff --git a/admin/unidata/.cvsignore b/admin/unidata/.cvsignore deleted file mode 100644 index bc9b8b61955..00000000000 --- a/admin/unidata/.cvsignore +++ /dev/null @@ -1,5 +0,0 @@ -charprop.el -uni-*.el -unidata.txt -Makefile.unix -Makefile diff --git a/admin/unidata/Makefile.in b/admin/unidata/Makefile.in deleted file mode 100644 index 769da76ae34..00000000000 --- a/admin/unidata/Makefile.in +++ /dev/null @@ -1,48 +0,0 @@ -# Makefile -- Makefile to generate character property tables. -# Copyright (C) 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 -# -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -EMACS = ../../src/emacs -DSTDIR = ../../lisp/international -RUNEMACS = ${EMACS} -Q --multibyte -batch - -all: ${DSTDIR}/charprop.el - -.el.elc: - ${RUNEMACS} -batch -f batch-byte-compile $< - -unidata.txt: UnicodeData.txt - sed -e 's/\([^;]*\);\(.*\)/(#x\1 "\2")/' -e 's/;/" "/g' < UnicodeData.txt > $@ - -${DSTDIR}/charprop.el: unidata-gen.elc unidata.txt - ELC=`/bin/pwd`/unidata-gen.elc; \ - DATA=`/bin/pwd`/unidata.txt; \ - cd ${DSTDIR}; \ - ${RUNEMACS} -batch --load $${ELC} -f unidata-gen-files $${DATA} - -install: charprop.el - cp charprop.el ${DSTDIR} - cp `sed -n 's/^;; FILE: //p' < charprop.el` ${DSTDIR} - -clean: - if test -f charprop.el; then \ - rm -f `sed -n 's/^;; FILE: //p' < charprop.el`; \ - fi - rm -f charprop.el unidata-gen.elc unidata.txt diff --git a/admin/unidata/README b/admin/unidata/README deleted file mode 100644 index d89f00a3437..00000000000 --- a/admin/unidata/README +++ /dev/null @@ -1,4 +0,0 @@ -The file `UnicodeData.txt' in this directory is a copy of - on 2006.5.23, -and is a part of the Unicode Character Database governed by the "UCD -Terms of Use" shown in the file `copyright.html'. diff --git a/admin/unidata/UnicodeData.txt b/admin/unidata/UnicodeData.txt deleted file mode 100644 index 77db788cf29..00000000000 --- a/admin/unidata/UnicodeData.txt +++ /dev/null @@ -1,19336 +0,0 @@ -0000;;Cc;0;BN;;;;;N;NULL;;;; -0001;;Cc;0;BN;;;;;N;START OF HEADING;;;; -0002;;Cc;0;BN;;;;;N;START OF TEXT;;;; -0003;;Cc;0;BN;;;;;N;END OF TEXT;;;; -0004;;Cc;0;BN;;;;;N;END OF TRANSMISSION;;;; -0005;;Cc;0;BN;;;;;N;ENQUIRY;;;; -0006;;Cc;0;BN;;;;;N;ACKNOWLEDGE;;;; -0007;;Cc;0;BN;;;;;N;BELL;;;; -0008;;Cc;0;BN;;;;;N;BACKSPACE;;;; -0009;;Cc;0;S;;;;;N;CHARACTER TABULATION;;;; -000A;;Cc;0;B;;;;;N;LINE FEED (LF);;;; -000B;;Cc;0;S;;;;;N;LINE TABULATION;;;; -000C;;Cc;0;WS;;;;;N;FORM FEED (FF);;;; -000D;;Cc;0;B;;;;;N;CARRIAGE RETURN (CR);;;; -000E;;Cc;0;BN;;;;;N;SHIFT OUT;;;; -000F;;Cc;0;BN;;;;;N;SHIFT IN;;;; -0010;;Cc;0;BN;;;;;N;DATA LINK ESCAPE;;;; -0011;;Cc;0;BN;;;;;N;DEVICE CONTROL ONE;;;; -0012;;Cc;0;BN;;;;;N;DEVICE CONTROL TWO;;;; -0013;;Cc;0;BN;;;;;N;DEVICE CONTROL THREE;;;; -0014;;Cc;0;BN;;;;;N;DEVICE CONTROL FOUR;;;; -0015;;Cc;0;BN;;;;;N;NEGATIVE ACKNOWLEDGE;;;; -0016;;Cc;0;BN;;;;;N;SYNCHRONOUS IDLE;;;; -0017;;Cc;0;BN;;;;;N;END OF TRANSMISSION BLOCK;;;; -0018;;Cc;0;BN;;;;;N;CANCEL;;;; -0019;;Cc;0;BN;;;;;N;END OF MEDIUM;;;; -001A;;Cc;0;BN;;;;;N;SUBSTITUTE;;;; -001B;;Cc;0;BN;;;;;N;ESCAPE;;;; -001C;;Cc;0;B;;;;;N;INFORMATION SEPARATOR FOUR;;;; -001D;;Cc;0;B;;;;;N;INFORMATION SEPARATOR THREE;;;; -001E;;Cc;0;B;;;;;N;INFORMATION SEPARATOR TWO;;;; -001F;;Cc;0;S;;;;;N;INFORMATION SEPARATOR ONE;;;; -0020;SPACE;Zs;0;WS;;;;;N;;;;; -0021;EXCLAMATION MARK;Po;0;ON;;;;;N;;;;; -0022;QUOTATION MARK;Po;0;ON;;;;;N;;;;; -0023;NUMBER SIGN;Po;0;ET;;;;;N;;;;; -0024;DOLLAR SIGN;Sc;0;ET;;;;;N;;;;; -0025;PERCENT SIGN;Po;0;ET;;;;;N;;;;; -0026;AMPERSAND;Po;0;ON;;;;;N;;;;; -0027;APOSTROPHE;Po;0;ON;;;;;N;APOSTROPHE-QUOTE;;;; -0028;LEFT PARENTHESIS;Ps;0;ON;;;;;Y;OPENING PARENTHESIS;;;; -0029;RIGHT PARENTHESIS;Pe;0;ON;;;;;Y;CLOSING PARENTHESIS;;;; -002A;ASTERISK;Po;0;ON;;;;;N;;;;; -002B;PLUS SIGN;Sm;0;ES;;;;;N;;;;; -002C;COMMA;Po;0;CS;;;;;N;;;;; -002D;HYPHEN-MINUS;Pd;0;ES;;;;;N;;;;; -002E;FULL STOP;Po;0;CS;;;;;N;PERIOD;;;; -002F;SOLIDUS;Po;0;CS;;;;;N;SLASH;;;; -0030;DIGIT ZERO;Nd;0;EN;;0;0;0;N;;;;; -0031;DIGIT ONE;Nd;0;EN;;1;1;1;N;;;;; -0032;DIGIT TWO;Nd;0;EN;;2;2;2;N;;;;; -0033;DIGIT THREE;Nd;0;EN;;3;3;3;N;;;;; -0034;DIGIT FOUR;Nd;0;EN;;4;4;4;N;;;;; -0035;DIGIT FIVE;Nd;0;EN;;5;5;5;N;;;;; -0036;DIGIT SIX;Nd;0;EN;;6;6;6;N;;;;; -0037;DIGIT SEVEN;Nd;0;EN;;7;7;7;N;;;;; -0038;DIGIT EIGHT;Nd;0;EN;;8;8;8;N;;;;; -0039;DIGIT NINE;Nd;0;EN;;9;9;9;N;;;;; -003A;COLON;Po;0;CS;;;;;N;;;;; -003B;SEMICOLON;Po;0;ON;;;;;N;;;;; -003C;LESS-THAN SIGN;Sm;0;ON;;;;;Y;;;;; -003D;EQUALS SIGN;Sm;0;ON;;;;;N;;;;; -003E;GREATER-THAN SIGN;Sm;0;ON;;;;;Y;;;;; -003F;QUESTION MARK;Po;0;ON;;;;;N;;;;; -0040;COMMERCIAL AT;Po;0;ON;;;;;N;;;;; -0041;LATIN CAPITAL LETTER A;Lu;0;L;;;;;N;;;;0061; -0042;LATIN CAPITAL LETTER B;Lu;0;L;;;;;N;;;;0062; -0043;LATIN CAPITAL LETTER C;Lu;0;L;;;;;N;;;;0063; -0044;LATIN CAPITAL LETTER D;Lu;0;L;;;;;N;;;;0064; -0045;LATIN CAPITAL LETTER E;Lu;0;L;;;;;N;;;;0065; -0046;LATIN CAPITAL LETTER F;Lu;0;L;;;;;N;;;;0066; -0047;LATIN CAPITAL LETTER G;Lu;0;L;;;;;N;;;;0067; -0048;LATIN CAPITAL LETTER H;Lu;0;L;;;;;N;;;;0068; -0049;LATIN CAPITAL LETTER I;Lu;0;L;;;;;N;;;;0069; -004A;LATIN CAPITAL LETTER J;Lu;0;L;;;;;N;;;;006A; -004B;LATIN CAPITAL LETTER K;Lu;0;L;;;;;N;;;;006B; -004C;LATIN CAPITAL LETTER L;Lu;0;L;;;;;N;;;;006C; -004D;LATIN CAPITAL LETTER M;Lu;0;L;;;;;N;;;;006D; -004E;LATIN CAPITAL LETTER N;Lu;0;L;;;;;N;;;;006E; -004F;LATIN CAPITAL LETTER O;Lu;0;L;;;;;N;;;;006F; -0050;LATIN CAPITAL LETTER P;Lu;0;L;;;;;N;;;;0070; -0051;LATIN CAPITAL LETTER Q;Lu;0;L;;;;;N;;;;0071; -0052;LATIN CAPITAL LETTER R;Lu;0;L;;;;;N;;;;0072; -0053;LATIN CAPITAL LETTER S;Lu;0;L;;;;;N;;;;0073; -0054;LATIN CAPITAL LETTER T;Lu;0;L;;;;;N;;;;0074; -0055;LATIN CAPITAL LETTER U;Lu;0;L;;;;;N;;;;0075; -0056;LATIN CAPITAL LETTER V;Lu;0;L;;;;;N;;;;0076; -0057;LATIN CAPITAL LETTER W;Lu;0;L;;;;;N;;;;0077; -0058;LATIN CAPITAL LETTER X;Lu;0;L;;;;;N;;;;0078; -0059;LATIN CAPITAL LETTER Y;Lu;0;L;;;;;N;;;;0079; -005A;LATIN CAPITAL LETTER Z;Lu;0;L;;;;;N;;;;007A; -005B;LEFT SQUARE BRACKET;Ps;0;ON;;;;;Y;OPENING SQUARE BRACKET;;;; -005C;REVERSE SOLIDUS;Po;0;ON;;;;;N;BACKSLASH;;;; -005D;RIGHT SQUARE BRACKET;Pe;0;ON;;;;;Y;CLOSING SQUARE BRACKET;;;; -005E;CIRCUMFLEX ACCENT;Sk;0;ON;;;;;N;SPACING CIRCUMFLEX;;;; -005F;LOW LINE;Pc;0;ON;;;;;N;SPACING UNDERSCORE;;;; -0060;GRAVE ACCENT;Sk;0;ON;;;;;N;SPACING GRAVE;;;; -0061;LATIN SMALL LETTER A;Ll;0;L;;;;;N;;;0041;;0041 -0062;LATIN SMALL LETTER B;Ll;0;L;;;;;N;;;0042;;0042 -0063;LATIN SMALL LETTER C;Ll;0;L;;;;;N;;;0043;;0043 -0064;LATIN SMALL LETTER D;Ll;0;L;;;;;N;;;0044;;0044 -0065;LATIN SMALL LETTER E;Ll;0;L;;;;;N;;;0045;;0045 -0066;LATIN SMALL LETTER F;Ll;0;L;;;;;N;;;0046;;0046 -0067;LATIN SMALL LETTER G;Ll;0;L;;;;;N;;;0047;;0047 -0068;LATIN SMALL LETTER H;Ll;0;L;;;;;N;;;0048;;0048 -0069;LATIN SMALL LETTER I;Ll;0;L;;;;;N;;;0049;;0049 -006A;LATIN SMALL LETTER J;Ll;0;L;;;;;N;;;004A;;004A -006B;LATIN SMALL LETTER K;Ll;0;L;;;;;N;;;004B;;004B -006C;LATIN SMALL LETTER L;Ll;0;L;;;;;N;;;004C;;004C -006D;LATIN SMALL LETTER M;Ll;0;L;;;;;N;;;004D;;004D -006E;LATIN SMALL LETTER N;Ll;0;L;;;;;N;;;004E;;004E -006F;LATIN SMALL LETTER O;Ll;0;L;;;;;N;;;004F;;004F -0070;LATIN SMALL LETTER P;Ll;0;L;;;;;N;;;0050;;0050 -0071;LATIN SMALL LETTER Q;Ll;0;L;;;;;N;;;0051;;0051 -0072;LATIN SMALL LETTER R;Ll;0;L;;;;;N;;;0052;;0052 -0073;LATIN SMALL LETTER S;Ll;0;L;;;;;N;;;0053;;0053 -0074;LATIN SMALL LETTER T;Ll;0;L;;;;;N;;;0054;;0054 -0075;LATIN SMALL LETTER U;Ll;0;L;;;;;N;;;0055;;0055 -0076;LATIN SMALL LETTER V;Ll;0;L;;;;;N;;;0056;;0056 -0077;LATIN SMALL LETTER W;Ll;0;L;;;;;N;;;0057;;0057 -0078;LATIN SMALL LETTER X;Ll;0;L;;;;;N;;;0058;;0058 -0079;LATIN SMALL LETTER Y;Ll;0;L;;;;;N;;;0059;;0059 -007A;LATIN SMALL LETTER Z;Ll;0;L;;;;;N;;;005A;;005A -007B;LEFT CURLY BRACKET;Ps;0;ON;;;;;Y;OPENING CURLY BRACKET;;;; -007C;VERTICAL LINE;Sm;0;ON;;;;;N;VERTICAL BAR;;;; -007D;RIGHT CURLY BRACKET;Pe;0;ON;;;;;Y;CLOSING CURLY BRACKET;;;; -007E;TILDE;Sm;0;ON;;;;;N;;;;; -007F;;Cc;0;BN;;;;;N;DELETE;;;; -0080;;Cc;0;BN;;;;;N;;;;; -0081;;Cc;0;BN;;;;;N;;;;; -0082;;Cc;0;BN;;;;;N;BREAK PERMITTED HERE;;;; -0083;;Cc;0;BN;;;;;N;NO BREAK HERE;;;; -0084;;Cc;0;BN;;;;;N;;;;; -0085;;Cc;0;B;;;;;N;NEXT LINE (NEL);;;; -0086;;Cc;0;BN;;;;;N;START OF SELECTED AREA;;;; -0087;;Cc;0;BN;;;;;N;END OF SELECTED AREA;;;; -0088;;Cc;0;BN;;;;;N;CHARACTER TABULATION SET;;;; -0089;;Cc;0;BN;;;;;N;CHARACTER TABULATION WITH JUSTIFICATION;;;; -008A;;Cc;0;BN;;;;;N;LINE TABULATION SET;;;; -008B;;Cc;0;BN;;;;;N;PARTIAL LINE FORWARD;;;; -008C;;Cc;0;BN;;;;;N;PARTIAL LINE BACKWARD;;;; -008D;;Cc;0;BN;;;;;N;REVERSE LINE FEED;;;; -008E;;Cc;0;BN;;;;;N;SINGLE SHIFT TWO;;;; -008F;;Cc;0;BN;;;;;N;SINGLE SHIFT THREE;;;; -0090;;Cc;0;BN;;;;;N;DEVICE CONTROL STRING;;;; -0091;;Cc;0;BN;;;;;N;PRIVATE USE ONE;;;; -0092;;Cc;0;BN;;;;;N;PRIVATE USE TWO;;;; -0093;;Cc;0;BN;;;;;N;SET TRANSMIT STATE;;;; -0094;;Cc;0;BN;;;;;N;CANCEL CHARACTER;;;; -0095;;Cc;0;BN;;;;;N;MESSAGE WAITING;;;; -0096;;Cc;0;BN;;;;;N;START OF GUARDED AREA;;;; -0097;;Cc;0;BN;;;;;N;END OF GUARDED AREA;;;; -0098;;Cc;0;BN;;;;;N;START OF STRING;;;; -0099;;Cc;0;BN;;;;;N;;;;; -009A;;Cc;0;BN;;;;;N;SINGLE CHARACTER INTRODUCER;;;; -009B;;Cc;0;BN;;;;;N;CONTROL SEQUENCE INTRODUCER;;;; -009C;;Cc;0;BN;;;;;N;STRING TERMINATOR;;;; -009D;;Cc;0;BN;;;;;N;OPERATING SYSTEM COMMAND;;;; -009E;;Cc;0;BN;;;;;N;PRIVACY MESSAGE;;;; -009F;;Cc;0;BN;;;;;N;APPLICATION PROGRAM COMMAND;;;; -00A0;NO-BREAK SPACE;Zs;0;CS; 0020;;;;N;NON-BREAKING SPACE;;;; -00A1;INVERTED EXCLAMATION MARK;Po;0;ON;;;;;N;;;;; -00A2;CENT SIGN;Sc;0;ET;;;;;N;;;;; -00A3;POUND SIGN;Sc;0;ET;;;;;N;;;;; -00A4;CURRENCY SIGN;Sc;0;ET;;;;;N;;;;; -00A5;YEN SIGN;Sc;0;ET;;;;;N;;;;; -00A6;BROKEN BAR;So;0;ON;;;;;N;BROKEN VERTICAL BAR;;;; -00A7;SECTION SIGN;So;0;ON;;;;;N;;;;; -00A8;DIAERESIS;Sk;0;ON; 0020 0308;;;;N;SPACING DIAERESIS;;;; -00A9;COPYRIGHT SIGN;So;0;ON;;;;;N;;;;; -00AA;FEMININE ORDINAL INDICATOR;Ll;0;L; 0061;;;;N;;;;; -00AB;LEFT-POINTING DOUBLE ANGLE QUOTATION MARK;Pi;0;ON;;;;;Y;LEFT POINTING GUILLEMET;*;;; -00AC;NOT SIGN;Sm;0;ON;;;;;N;;;;; -00AD;SOFT HYPHEN;Cf;0;BN;;;;;N;;;;; -00AE;REGISTERED SIGN;So;0;ON;;;;;N;REGISTERED TRADE MARK SIGN;;;; -00AF;MACRON;Sk;0;ON; 0020 0304;;;;N;SPACING MACRON;;;; -00B0;DEGREE SIGN;So;0;ET;;;;;N;;;;; -00B1;PLUS-MINUS SIGN;Sm;0;ET;;;;;N;PLUS-OR-MINUS SIGN;;;; -00B2;SUPERSCRIPT TWO;No;0;EN; 0032;;2;2;N;SUPERSCRIPT DIGIT TWO;;;; -00B3;SUPERSCRIPT THREE;No;0;EN; 0033;;3;3;N;SUPERSCRIPT DIGIT THREE;;;; -00B4;ACUTE ACCENT;Sk;0;ON; 0020 0301;;;;N;SPACING ACUTE;;;; -00B5;MICRO SIGN;Ll;0;L; 03BC;;;;N;;;039C;;039C -00B6;PILCROW SIGN;So;0;ON;;;;;N;PARAGRAPH SIGN;;;; -00B7;MIDDLE DOT;Po;0;ON;;;;;N;;;;; -00B8;CEDILLA;Sk;0;ON; 0020 0327;;;;N;SPACING CEDILLA;;;; -00B9;SUPERSCRIPT ONE;No;0;EN; 0031;;1;1;N;SUPERSCRIPT DIGIT ONE;;;; -00BA;MASCULINE ORDINAL INDICATOR;Ll;0;L; 006F;;;;N;;;;; -00BB;RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK;Pf;0;ON;;;;;Y;RIGHT POINTING GUILLEMET;*;;; -00BC;VULGAR FRACTION ONE QUARTER;No;0;ON; 0031 2044 0034;;;1/4;N;FRACTION ONE QUARTER;;;; -00BD;VULGAR FRACTION ONE HALF;No;0;ON; 0031 2044 0032;;;1/2;N;FRACTION ONE HALF;;;; -00BE;VULGAR FRACTION THREE QUARTERS;No;0;ON; 0033 2044 0034;;;3/4;N;FRACTION THREE QUARTERS;;;; -00BF;INVERTED QUESTION MARK;Po;0;ON;;;;;N;;;;; -00C0;LATIN CAPITAL LETTER A WITH GRAVE;Lu;0;L;0041 0300;;;;N;LATIN CAPITAL LETTER A GRAVE;;;00E0; -00C1;LATIN CAPITAL LETTER A WITH ACUTE;Lu;0;L;0041 0301;;;;N;LATIN CAPITAL LETTER A ACUTE;;;00E1; -00C2;LATIN CAPITAL LETTER A WITH CIRCUMFLEX;Lu;0;L;0041 0302;;;;N;LATIN CAPITAL LETTER A CIRCUMFLEX;;;00E2; -00C3;LATIN CAPITAL LETTER A WITH TILDE;Lu;0;L;0041 0303;;;;N;LATIN CAPITAL LETTER A TILDE;;;00E3; -00C4;LATIN CAPITAL LETTER A WITH DIAERESIS;Lu;0;L;0041 0308;;;;N;LATIN CAPITAL LETTER A DIAERESIS;;;00E4; -00C5;LATIN CAPITAL LETTER A WITH RING ABOVE;Lu;0;L;0041 030A;;;;N;LATIN CAPITAL LETTER A RING;;;00E5; -00C6;LATIN CAPITAL LETTER AE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER A E;ash *;;00E6; -00C7;LATIN CAPITAL LETTER C WITH CEDILLA;Lu;0;L;0043 0327;;;;N;LATIN CAPITAL LETTER C CEDILLA;;;00E7; -00C8;LATIN CAPITAL LETTER E WITH GRAVE;Lu;0;L;0045 0300;;;;N;LATIN CAPITAL LETTER E GRAVE;;;00E8; -00C9;LATIN CAPITAL LETTER E WITH ACUTE;Lu;0;L;0045 0301;;;;N;LATIN CAPITAL LETTER E ACUTE;;;00E9; -00CA;LATIN CAPITAL LETTER E WITH CIRCUMFLEX;Lu;0;L;0045 0302;;;;N;LATIN CAPITAL LETTER E CIRCUMFLEX;;;00EA; -00CB;LATIN CAPITAL LETTER E WITH DIAERESIS;Lu;0;L;0045 0308;;;;N;LATIN CAPITAL LETTER E DIAERESIS;;;00EB; -00CC;LATIN CAPITAL LETTER I WITH GRAVE;Lu;0;L;0049 0300;;;;N;LATIN CAPITAL LETTER I GRAVE;;;00EC; -00CD;LATIN CAPITAL LETTER I WITH ACUTE;Lu;0;L;0049 0301;;;;N;LATIN CAPITAL LETTER I ACUTE;;;00ED; -00CE;LATIN CAPITAL LETTER I WITH CIRCUMFLEX;Lu;0;L;0049 0302;;;;N;LATIN CAPITAL LETTER I CIRCUMFLEX;;;00EE; -00CF;LATIN CAPITAL LETTER I WITH DIAERESIS;Lu;0;L;0049 0308;;;;N;LATIN CAPITAL LETTER I DIAERESIS;;;00EF; -00D0;LATIN CAPITAL LETTER ETH;Lu;0;L;;;;;N;;Icelandic;;00F0; -00D1;LATIN CAPITAL LETTER N WITH TILDE;Lu;0;L;004E 0303;;;;N;LATIN CAPITAL LETTER N TILDE;;;00F1; -00D2;LATIN CAPITAL LETTER O WITH GRAVE;Lu;0;L;004F 0300;;;;N;LATIN CAPITAL LETTER O GRAVE;;;00F2; -00D3;LATIN CAPITAL LETTER O WITH ACUTE;Lu;0;L;004F 0301;;;;N;LATIN CAPITAL LETTER O ACUTE;;;00F3; -00D4;LATIN CAPITAL LETTER O WITH CIRCUMFLEX;Lu;0;L;004F 0302;;;;N;LATIN CAPITAL LETTER O CIRCUMFLEX;;;00F4; -00D5;LATIN CAPITAL LETTER O WITH TILDE;Lu;0;L;004F 0303;;;;N;LATIN CAPITAL LETTER O TILDE;;;00F5; -00D6;LATIN CAPITAL LETTER O WITH DIAERESIS;Lu;0;L;004F 0308;;;;N;LATIN CAPITAL LETTER O DIAERESIS;;;00F6; -00D7;MULTIPLICATION SIGN;Sm;0;ON;;;;;N;;;;; -00D8;LATIN CAPITAL LETTER O WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER O SLASH;;;00F8; -00D9;LATIN CAPITAL LETTER U WITH GRAVE;Lu;0;L;0055 0300;;;;N;LATIN CAPITAL LETTER U GRAVE;;;00F9; -00DA;LATIN CAPITAL LETTER U WITH ACUTE;Lu;0;L;0055 0301;;;;N;LATIN CAPITAL LETTER U ACUTE;;;00FA; -00DB;LATIN CAPITAL LETTER U WITH CIRCUMFLEX;Lu;0;L;0055 0302;;;;N;LATIN CAPITAL LETTER U CIRCUMFLEX;;;00FB; -00DC;LATIN CAPITAL LETTER U WITH DIAERESIS;Lu;0;L;0055 0308;;;;N;LATIN CAPITAL LETTER U DIAERESIS;;;00FC; -00DD;LATIN CAPITAL LETTER Y WITH ACUTE;Lu;0;L;0059 0301;;;;N;LATIN CAPITAL LETTER Y ACUTE;;;00FD; -00DE;LATIN CAPITAL LETTER THORN;Lu;0;L;;;;;N;;Icelandic;;00FE; -00DF;LATIN SMALL LETTER SHARP S;Ll;0;L;;;;;N;;German;;; -00E0;LATIN SMALL LETTER A WITH GRAVE;Ll;0;L;0061 0300;;;;N;LATIN SMALL LETTER A GRAVE;;00C0;;00C0 -00E1;LATIN SMALL LETTER A WITH ACUTE;Ll;0;L;0061 0301;;;;N;LATIN SMALL LETTER A ACUTE;;00C1;;00C1 -00E2;LATIN SMALL LETTER A WITH CIRCUMFLEX;Ll;0;L;0061 0302;;;;N;LATIN SMALL LETTER A CIRCUMFLEX;;00C2;;00C2 -00E3;LATIN SMALL LETTER A WITH TILDE;Ll;0;L;0061 0303;;;;N;LATIN SMALL LETTER A TILDE;;00C3;;00C3 -00E4;LATIN SMALL LETTER A WITH DIAERESIS;Ll;0;L;0061 0308;;;;N;LATIN SMALL LETTER A DIAERESIS;;00C4;;00C4 -00E5;LATIN SMALL LETTER A WITH RING ABOVE;Ll;0;L;0061 030A;;;;N;LATIN SMALL LETTER A RING;;00C5;;00C5 -00E6;LATIN SMALL LETTER AE;Ll;0;L;;;;;N;LATIN SMALL LETTER A E;ash *;00C6;;00C6 -00E7;LATIN SMALL LETTER C WITH CEDILLA;Ll;0;L;0063 0327;;;;N;LATIN SMALL LETTER C CEDILLA;;00C7;;00C7 -00E8;LATIN SMALL LETTER E WITH GRAVE;Ll;0;L;0065 0300;;;;N;LATIN SMALL LETTER E GRAVE;;00C8;;00C8 -00E9;LATIN SMALL LETTER E WITH ACUTE;Ll;0;L;0065 0301;;;;N;LATIN SMALL LETTER E ACUTE;;00C9;;00C9 -00EA;LATIN SMALL LETTER E WITH CIRCUMFLEX;Ll;0;L;0065 0302;;;;N;LATIN SMALL LETTER E CIRCUMFLEX;;00CA;;00CA -00EB;LATIN SMALL LETTER E WITH DIAERESIS;Ll;0;L;0065 0308;;;;N;LATIN SMALL LETTER E DIAERESIS;;00CB;;00CB -00EC;LATIN SMALL LETTER I WITH GRAVE;Ll;0;L;0069 0300;;;;N;LATIN SMALL LETTER I GRAVE;;00CC;;00CC -00ED;LATIN SMALL LETTER I WITH ACUTE;Ll;0;L;0069 0301;;;;N;LATIN SMALL LETTER I ACUTE;;00CD;;00CD -00EE;LATIN SMALL LETTER I WITH CIRCUMFLEX;Ll;0;L;0069 0302;;;;N;LATIN SMALL LETTER I CIRCUMFLEX;;00CE;;00CE -00EF;LATIN SMALL LETTER I WITH DIAERESIS;Ll;0;L;0069 0308;;;;N;LATIN SMALL LETTER I DIAERESIS;;00CF;;00CF -00F0;LATIN SMALL LETTER ETH;Ll;0;L;;;;;N;;Icelandic;00D0;;00D0 -00F1;LATIN SMALL LETTER N WITH TILDE;Ll;0;L;006E 0303;;;;N;LATIN SMALL LETTER N TILDE;;00D1;;00D1 -00F2;LATIN SMALL LETTER O WITH GRAVE;Ll;0;L;006F 0300;;;;N;LATIN SMALL LETTER O GRAVE;;00D2;;00D2 -00F3;LATIN SMALL LETTER O WITH ACUTE;Ll;0;L;006F 0301;;;;N;LATIN SMALL LETTER O ACUTE;;00D3;;00D3 -00F4;LATIN SMALL LETTER O WITH CIRCUMFLEX;Ll;0;L;006F 0302;;;;N;LATIN SMALL LETTER O CIRCUMFLEX;;00D4;;00D4 -00F5;LATIN SMALL LETTER O WITH TILDE;Ll;0;L;006F 0303;;;;N;LATIN SMALL LETTER O TILDE;;00D5;;00D5 -00F6;LATIN SMALL LETTER O WITH DIAERESIS;Ll;0;L;006F 0308;;;;N;LATIN SMALL LETTER O DIAERESIS;;00D6;;00D6 -00F7;DIVISION SIGN;Sm;0;ON;;;;;N;;;;; -00F8;LATIN SMALL LETTER O WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER O SLASH;;00D8;;00D8 -00F9;LATIN SMALL LETTER U WITH GRAVE;Ll;0;L;0075 0300;;;;N;LATIN SMALL LETTER U GRAVE;;00D9;;00D9 -00FA;LATIN SMALL LETTER U WITH ACUTE;Ll;0;L;0075 0301;;;;N;LATIN SMALL LETTER U ACUTE;;00DA;;00DA -00FB;LATIN SMALL LETTER U WITH CIRCUMFLEX;Ll;0;L;0075 0302;;;;N;LATIN SMALL LETTER U CIRCUMFLEX;;00DB;;00DB -00FC;LATIN SMALL LETTER U WITH DIAERESIS;Ll;0;L;0075 0308;;;;N;LATIN SMALL LETTER U DIAERESIS;;00DC;;00DC -00FD;LATIN SMALL LETTER Y WITH ACUTE;Ll;0;L;0079 0301;;;;N;LATIN SMALL LETTER Y ACUTE;;00DD;;00DD -00FE;LATIN SMALL LETTER THORN;Ll;0;L;;;;;N;;Icelandic;00DE;;00DE -00FF;LATIN SMALL LETTER Y WITH DIAERESIS;Ll;0;L;0079 0308;;;;N;LATIN SMALL LETTER Y DIAERESIS;;0178;;0178 -0100;LATIN CAPITAL LETTER A WITH MACRON;Lu;0;L;0041 0304;;;;N;LATIN CAPITAL LETTER A MACRON;;;0101; -0101;LATIN SMALL LETTER A WITH MACRON;Ll;0;L;0061 0304;;;;N;LATIN SMALL LETTER A MACRON;;0100;;0100 -0102;LATIN CAPITAL LETTER A WITH BREVE;Lu;0;L;0041 0306;;;;N;LATIN CAPITAL LETTER A BREVE;;;0103; -0103;LATIN SMALL LETTER A WITH BREVE;Ll;0;L;0061 0306;;;;N;LATIN SMALL LETTER A BREVE;;0102;;0102 -0104;LATIN CAPITAL LETTER A WITH OGONEK;Lu;0;L;0041 0328;;;;N;LATIN CAPITAL LETTER A OGONEK;;;0105; -0105;LATIN SMALL LETTER A WITH OGONEK;Ll;0;L;0061 0328;;;;N;LATIN SMALL LETTER A OGONEK;;0104;;0104 -0106;LATIN CAPITAL LETTER C WITH ACUTE;Lu;0;L;0043 0301;;;;N;LATIN CAPITAL LETTER C ACUTE;;;0107; -0107;LATIN SMALL LETTER C WITH ACUTE;Ll;0;L;0063 0301;;;;N;LATIN SMALL LETTER C ACUTE;;0106;;0106 -0108;LATIN CAPITAL LETTER C WITH CIRCUMFLEX;Lu;0;L;0043 0302;;;;N;LATIN CAPITAL LETTER C CIRCUMFLEX;;;0109; -0109;LATIN SMALL LETTER C WITH CIRCUMFLEX;Ll;0;L;0063 0302;;;;N;LATIN SMALL LETTER C CIRCUMFLEX;;0108;;0108 -010A;LATIN CAPITAL LETTER C WITH DOT ABOVE;Lu;0;L;0043 0307;;;;N;LATIN CAPITAL LETTER C DOT;;;010B; -010B;LATIN SMALL LETTER C WITH DOT ABOVE;Ll;0;L;0063 0307;;;;N;LATIN SMALL LETTER C DOT;;010A;;010A -010C;LATIN CAPITAL LETTER C WITH CARON;Lu;0;L;0043 030C;;;;N;LATIN CAPITAL LETTER C HACEK;;;010D; -010D;LATIN SMALL LETTER C WITH CARON;Ll;0;L;0063 030C;;;;N;LATIN SMALL LETTER C HACEK;;010C;;010C -010E;LATIN CAPITAL LETTER D WITH CARON;Lu;0;L;0044 030C;;;;N;LATIN CAPITAL LETTER D HACEK;;;010F; -010F;LATIN SMALL LETTER D WITH CARON;Ll;0;L;0064 030C;;;;N;LATIN SMALL LETTER D HACEK;;010E;;010E -0110;LATIN CAPITAL LETTER D WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER D BAR;;;0111; -0111;LATIN SMALL LETTER D WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER D BAR;;0110;;0110 -0112;LATIN CAPITAL LETTER E WITH MACRON;Lu;0;L;0045 0304;;;;N;LATIN CAPITAL LETTER E MACRON;;;0113; -0113;LATIN SMALL LETTER E WITH MACRON;Ll;0;L;0065 0304;;;;N;LATIN SMALL LETTER E MACRON;;0112;;0112 -0114;LATIN CAPITAL LETTER E WITH BREVE;Lu;0;L;0045 0306;;;;N;LATIN CAPITAL LETTER E BREVE;;;0115; -0115;LATIN SMALL LETTER E WITH BREVE;Ll;0;L;0065 0306;;;;N;LATIN SMALL LETTER E BREVE;;0114;;0114 -0116;LATIN CAPITAL LETTER E WITH DOT ABOVE;Lu;0;L;0045 0307;;;;N;LATIN CAPITAL LETTER E DOT;;;0117; -0117;LATIN SMALL LETTER E WITH DOT ABOVE;Ll;0;L;0065 0307;;;;N;LATIN SMALL LETTER E DOT;;0116;;0116 -0118;LATIN CAPITAL LETTER E WITH OGONEK;Lu;0;L;0045 0328;;;;N;LATIN CAPITAL LETTER E OGONEK;;;0119; -0119;LATIN SMALL LETTER E WITH OGONEK;Ll;0;L;0065 0328;;;;N;LATIN SMALL LETTER E OGONEK;;0118;;0118 -011A;LATIN CAPITAL LETTER E WITH CARON;Lu;0;L;0045 030C;;;;N;LATIN CAPITAL LETTER E HACEK;;;011B; -011B;LATIN SMALL LETTER E WITH CARON;Ll;0;L;0065 030C;;;;N;LATIN SMALL LETTER E HACEK;;011A;;011A -011C;LATIN CAPITAL LETTER G WITH CIRCUMFLEX;Lu;0;L;0047 0302;;;;N;LATIN CAPITAL LETTER G CIRCUMFLEX;;;011D; -011D;LATIN SMALL LETTER G WITH CIRCUMFLEX;Ll;0;L;0067 0302;;;;N;LATIN SMALL LETTER G CIRCUMFLEX;;011C;;011C -011E;LATIN CAPITAL LETTER G WITH BREVE;Lu;0;L;0047 0306;;;;N;LATIN CAPITAL LETTER G BREVE;;;011F; -011F;LATIN SMALL LETTER G WITH BREVE;Ll;0;L;0067 0306;;;;N;LATIN SMALL LETTER G BREVE;;011E;;011E -0120;LATIN CAPITAL LETTER G WITH DOT ABOVE;Lu;0;L;0047 0307;;;;N;LATIN CAPITAL LETTER G DOT;;;0121; -0121;LATIN SMALL LETTER G WITH DOT ABOVE;Ll;0;L;0067 0307;;;;N;LATIN SMALL LETTER G DOT;;0120;;0120 -0122;LATIN CAPITAL LETTER G WITH CEDILLA;Lu;0;L;0047 0327;;;;N;LATIN CAPITAL LETTER G CEDILLA;;;0123; -0123;LATIN SMALL LETTER G WITH CEDILLA;Ll;0;L;0067 0327;;;;N;LATIN SMALL LETTER G CEDILLA;;0122;;0122 -0124;LATIN CAPITAL LETTER H WITH CIRCUMFLEX;Lu;0;L;0048 0302;;;;N;LATIN CAPITAL LETTER H CIRCUMFLEX;;;0125; -0125;LATIN SMALL LETTER H WITH CIRCUMFLEX;Ll;0;L;0068 0302;;;;N;LATIN SMALL LETTER H CIRCUMFLEX;;0124;;0124 -0126;LATIN CAPITAL LETTER H WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER H BAR;;;0127; -0127;LATIN SMALL LETTER H WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER H BAR;;0126;;0126 -0128;LATIN CAPITAL LETTER I WITH TILDE;Lu;0;L;0049 0303;;;;N;LATIN CAPITAL LETTER I TILDE;;;0129; -0129;LATIN SMALL LETTER I WITH TILDE;Ll;0;L;0069 0303;;;;N;LATIN SMALL LETTER I TILDE;;0128;;0128 -012A;LATIN CAPITAL LETTER I WITH MACRON;Lu;0;L;0049 0304;;;;N;LATIN CAPITAL LETTER I MACRON;;;012B; -012B;LATIN SMALL LETTER I WITH MACRON;Ll;0;L;0069 0304;;;;N;LATIN SMALL LETTER I MACRON;;012A;;012A -012C;LATIN CAPITAL LETTER I WITH BREVE;Lu;0;L;0049 0306;;;;N;LATIN CAPITAL LETTER I BREVE;;;012D; -012D;LATIN SMALL LETTER I WITH BREVE;Ll;0;L;0069 0306;;;;N;LATIN SMALL LETTER I BREVE;;012C;;012C -012E;LATIN CAPITAL LETTER I WITH OGONEK;Lu;0;L;0049 0328;;;;N;LATIN CAPITAL LETTER I OGONEK;;;012F; -012F;LATIN SMALL LETTER I WITH OGONEK;Ll;0;L;0069 0328;;;;N;LATIN SMALL LETTER I OGONEK;;012E;;012E -0130;LATIN CAPITAL LETTER I WITH DOT ABOVE;Lu;0;L;0049 0307;;;;N;LATIN CAPITAL LETTER I DOT;;;0069; -0131;LATIN SMALL LETTER DOTLESS I;Ll;0;L;;;;;N;;;0049;;0049 -0132;LATIN CAPITAL LIGATURE IJ;Lu;0;L; 0049 004A;;;;N;LATIN CAPITAL LETTER I J;;;0133; -0133;LATIN SMALL LIGATURE IJ;Ll;0;L; 0069 006A;;;;N;LATIN SMALL LETTER I J;;0132;;0132 -0134;LATIN CAPITAL LETTER J WITH CIRCUMFLEX;Lu;0;L;004A 0302;;;;N;LATIN CAPITAL LETTER J CIRCUMFLEX;;;0135; -0135;LATIN SMALL LETTER J WITH CIRCUMFLEX;Ll;0;L;006A 0302;;;;N;LATIN SMALL LETTER J CIRCUMFLEX;;0134;;0134 -0136;LATIN CAPITAL LETTER K WITH CEDILLA;Lu;0;L;004B 0327;;;;N;LATIN CAPITAL LETTER K CEDILLA;;;0137; -0137;LATIN SMALL LETTER K WITH CEDILLA;Ll;0;L;006B 0327;;;;N;LATIN SMALL LETTER K CEDILLA;;0136;;0136 -0138;LATIN SMALL LETTER KRA;Ll;0;L;;;;;N;;Greenlandic;;; -0139;LATIN CAPITAL LETTER L WITH ACUTE;Lu;0;L;004C 0301;;;;N;LATIN CAPITAL LETTER L ACUTE;;;013A; -013A;LATIN SMALL LETTER L WITH ACUTE;Ll;0;L;006C 0301;;;;N;LATIN SMALL LETTER L ACUTE;;0139;;0139 -013B;LATIN CAPITAL LETTER L WITH CEDILLA;Lu;0;L;004C 0327;;;;N;LATIN CAPITAL LETTER L CEDILLA;;;013C; -013C;LATIN SMALL LETTER L WITH CEDILLA;Ll;0;L;006C 0327;;;;N;LATIN SMALL LETTER L CEDILLA;;013B;;013B -013D;LATIN CAPITAL LETTER L WITH CARON;Lu;0;L;004C 030C;;;;N;LATIN CAPITAL LETTER L HACEK;;;013E; -013E;LATIN SMALL LETTER L WITH CARON;Ll;0;L;006C 030C;;;;N;LATIN SMALL LETTER L HACEK;;013D;;013D -013F;LATIN CAPITAL LETTER L WITH MIDDLE DOT;Lu;0;L; 004C 00B7;;;;N;;;;0140; -0140;LATIN SMALL LETTER L WITH MIDDLE DOT;Ll;0;L; 006C 00B7;;;;N;;;013F;;013F -0141;LATIN CAPITAL LETTER L WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER L SLASH;;;0142; -0142;LATIN SMALL LETTER L WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER L SLASH;;0141;;0141 -0143;LATIN CAPITAL LETTER N WITH ACUTE;Lu;0;L;004E 0301;;;;N;LATIN CAPITAL LETTER N ACUTE;;;0144; -0144;LATIN SMALL LETTER N WITH ACUTE;Ll;0;L;006E 0301;;;;N;LATIN SMALL LETTER N ACUTE;;0143;;0143 -0145;LATIN CAPITAL LETTER N WITH CEDILLA;Lu;0;L;004E 0327;;;;N;LATIN CAPITAL LETTER N CEDILLA;;;0146; -0146;LATIN SMALL LETTER N WITH CEDILLA;Ll;0;L;006E 0327;;;;N;LATIN SMALL LETTER N CEDILLA;;0145;;0145 -0147;LATIN CAPITAL LETTER N WITH CARON;Lu;0;L;004E 030C;;;;N;LATIN CAPITAL LETTER N HACEK;;;0148; -0148;LATIN SMALL LETTER N WITH CARON;Ll;0;L;006E 030C;;;;N;LATIN SMALL LETTER N HACEK;;0147;;0147 -0149;LATIN SMALL LETTER N PRECEDED BY APOSTROPHE;Ll;0;L; 02BC 006E;;;;N;LATIN SMALL LETTER APOSTROPHE N;;;; -014A;LATIN CAPITAL LETTER ENG;Lu;0;L;;;;;N;;Sami;;014B; -014B;LATIN SMALL LETTER ENG;Ll;0;L;;;;;N;;Sami;014A;;014A -014C;LATIN CAPITAL LETTER O WITH MACRON;Lu;0;L;004F 0304;;;;N;LATIN CAPITAL LETTER O MACRON;;;014D; -014D;LATIN SMALL LETTER O WITH MACRON;Ll;0;L;006F 0304;;;;N;LATIN SMALL LETTER O MACRON;;014C;;014C -014E;LATIN CAPITAL LETTER O WITH BREVE;Lu;0;L;004F 0306;;;;N;LATIN CAPITAL LETTER O BREVE;;;014F; -014F;LATIN SMALL LETTER O WITH BREVE;Ll;0;L;006F 0306;;;;N;LATIN SMALL LETTER O BREVE;;014E;;014E -0150;LATIN CAPITAL LETTER O WITH DOUBLE ACUTE;Lu;0;L;004F 030B;;;;N;LATIN CAPITAL LETTER O DOUBLE ACUTE;;;0151; -0151;LATIN SMALL LETTER O WITH DOUBLE ACUTE;Ll;0;L;006F 030B;;;;N;LATIN SMALL LETTER O DOUBLE ACUTE;;0150;;0150 -0152;LATIN CAPITAL LIGATURE OE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER O E;;;0153; -0153;LATIN SMALL LIGATURE OE;Ll;0;L;;;;;N;LATIN SMALL LETTER O E;;0152;;0152 -0154;LATIN CAPITAL LETTER R WITH ACUTE;Lu;0;L;0052 0301;;;;N;LATIN CAPITAL LETTER R ACUTE;;;0155; -0155;LATIN SMALL LETTER R WITH ACUTE;Ll;0;L;0072 0301;;;;N;LATIN SMALL LETTER R ACUTE;;0154;;0154 -0156;LATIN CAPITAL LETTER R WITH CEDILLA;Lu;0;L;0052 0327;;;;N;LATIN CAPITAL LETTER R CEDILLA;;;0157; -0157;LATIN SMALL LETTER R WITH CEDILLA;Ll;0;L;0072 0327;;;;N;LATIN SMALL LETTER R CEDILLA;;0156;;0156 -0158;LATIN CAPITAL LETTER R WITH CARON;Lu;0;L;0052 030C;;;;N;LATIN CAPITAL LETTER R HACEK;;;0159; -0159;LATIN SMALL LETTER R WITH CARON;Ll;0;L;0072 030C;;;;N;LATIN SMALL LETTER R HACEK;;0158;;0158 -015A;LATIN CAPITAL LETTER S WITH ACUTE;Lu;0;L;0053 0301;;;;N;LATIN CAPITAL LETTER S ACUTE;;;015B; -015B;LATIN SMALL LETTER S WITH ACUTE;Ll;0;L;0073 0301;;;;N;LATIN SMALL LETTER S ACUTE;;015A;;015A -015C;LATIN CAPITAL LETTER S WITH CIRCUMFLEX;Lu;0;L;0053 0302;;;;N;LATIN CAPITAL LETTER S CIRCUMFLEX;;;015D; -015D;LATIN SMALL LETTER S WITH CIRCUMFLEX;Ll;0;L;0073 0302;;;;N;LATIN SMALL LETTER S CIRCUMFLEX;;015C;;015C -015E;LATIN CAPITAL LETTER S WITH CEDILLA;Lu;0;L;0053 0327;;;;N;LATIN CAPITAL LETTER S CEDILLA;*;;015F; -015F;LATIN SMALL LETTER S WITH CEDILLA;Ll;0;L;0073 0327;;;;N;LATIN SMALL LETTER S CEDILLA;*;015E;;015E -0160;LATIN CAPITAL LETTER S WITH CARON;Lu;0;L;0053 030C;;;;N;LATIN CAPITAL LETTER S HACEK;;;0161; -0161;LATIN SMALL LETTER S WITH CARON;Ll;0;L;0073 030C;;;;N;LATIN SMALL LETTER S HACEK;;0160;;0160 -0162;LATIN CAPITAL LETTER T WITH CEDILLA;Lu;0;L;0054 0327;;;;N;LATIN CAPITAL LETTER T CEDILLA;*;;0163; -0163;LATIN SMALL LETTER T WITH CEDILLA;Ll;0;L;0074 0327;;;;N;LATIN SMALL LETTER T CEDILLA;*;0162;;0162 -0164;LATIN CAPITAL LETTER T WITH CARON;Lu;0;L;0054 030C;;;;N;LATIN CAPITAL LETTER T HACEK;;;0165; -0165;LATIN SMALL LETTER T WITH CARON;Ll;0;L;0074 030C;;;;N;LATIN SMALL LETTER T HACEK;;0164;;0164 -0166;LATIN CAPITAL LETTER T WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER T BAR;;;0167; -0167;LATIN SMALL LETTER T WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER T BAR;;0166;;0166 -0168;LATIN CAPITAL LETTER U WITH TILDE;Lu;0;L;0055 0303;;;;N;LATIN CAPITAL LETTER U TILDE;;;0169; -0169;LATIN SMALL LETTER U WITH TILDE;Ll;0;L;0075 0303;;;;N;LATIN SMALL LETTER U TILDE;;0168;;0168 -016A;LATIN CAPITAL LETTER U WITH MACRON;Lu;0;L;0055 0304;;;;N;LATIN CAPITAL LETTER U MACRON;;;016B; -016B;LATIN SMALL LETTER U WITH MACRON;Ll;0;L;0075 0304;;;;N;LATIN SMALL LETTER U MACRON;;016A;;016A -016C;LATIN CAPITAL LETTER U WITH BREVE;Lu;0;L;0055 0306;;;;N;LATIN CAPITAL LETTER U BREVE;;;016D; -016D;LATIN SMALL LETTER U WITH BREVE;Ll;0;L;0075 0306;;;;N;LATIN SMALL LETTER U BREVE;;016C;;016C -016E;LATIN CAPITAL LETTER U WITH RING ABOVE;Lu;0;L;0055 030A;;;;N;LATIN CAPITAL LETTER U RING;;;016F; -016F;LATIN SMALL LETTER U WITH RING ABOVE;Ll;0;L;0075 030A;;;;N;LATIN SMALL LETTER U RING;;016E;;016E -0170;LATIN CAPITAL LETTER U WITH DOUBLE ACUTE;Lu;0;L;0055 030B;;;;N;LATIN CAPITAL LETTER U DOUBLE ACUTE;;;0171; -0171;LATIN SMALL LETTER U WITH DOUBLE ACUTE;Ll;0;L;0075 030B;;;;N;LATIN SMALL LETTER U DOUBLE ACUTE;;0170;;0170 -0172;LATIN CAPITAL LETTER U WITH OGONEK;Lu;0;L;0055 0328;;;;N;LATIN CAPITAL LETTER U OGONEK;;;0173; -0173;LATIN SMALL LETTER U WITH OGONEK;Ll;0;L;0075 0328;;;;N;LATIN SMALL LETTER U OGONEK;;0172;;0172 -0174;LATIN CAPITAL LETTER W WITH CIRCUMFLEX;Lu;0;L;0057 0302;;;;N;LATIN CAPITAL LETTER W CIRCUMFLEX;;;0175; -0175;LATIN SMALL LETTER W WITH CIRCUMFLEX;Ll;0;L;0077 0302;;;;N;LATIN SMALL LETTER W CIRCUMFLEX;;0174;;0174 -0176;LATIN CAPITAL LETTER Y WITH CIRCUMFLEX;Lu;0;L;0059 0302;;;;N;LATIN CAPITAL LETTER Y CIRCUMFLEX;;;0177; -0177;LATIN SMALL LETTER Y WITH CIRCUMFLEX;Ll;0;L;0079 0302;;;;N;LATIN SMALL LETTER Y CIRCUMFLEX;;0176;;0176 -0178;LATIN CAPITAL LETTER Y WITH DIAERESIS;Lu;0;L;0059 0308;;;;N;LATIN CAPITAL LETTER Y DIAERESIS;;;00FF; -0179;LATIN CAPITAL LETTER Z WITH ACUTE;Lu;0;L;005A 0301;;;;N;LATIN CAPITAL LETTER Z ACUTE;;;017A; -017A;LATIN SMALL LETTER Z WITH ACUTE;Ll;0;L;007A 0301;;;;N;LATIN SMALL LETTER Z ACUTE;;0179;;0179 -017B;LATIN CAPITAL LETTER Z WITH DOT ABOVE;Lu;0;L;005A 0307;;;;N;LATIN CAPITAL LETTER Z DOT;;;017C; -017C;LATIN SMALL LETTER Z WITH DOT ABOVE;Ll;0;L;007A 0307;;;;N;LATIN SMALL LETTER Z DOT;;017B;;017B -017D;LATIN CAPITAL LETTER Z WITH CARON;Lu;0;L;005A 030C;;;;N;LATIN CAPITAL LETTER Z HACEK;;;017E; -017E;LATIN SMALL LETTER Z WITH CARON;Ll;0;L;007A 030C;;;;N;LATIN SMALL LETTER Z HACEK;;017D;;017D -017F;LATIN SMALL LETTER LONG S;Ll;0;L; 0073;;;;N;;;0053;;0053 -0180;LATIN SMALL LETTER B WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER B BAR;;0243;;0243 -0181;LATIN CAPITAL LETTER B WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER B HOOK;;;0253; -0182;LATIN CAPITAL LETTER B WITH TOPBAR;Lu;0;L;;;;;N;LATIN CAPITAL LETTER B TOPBAR;;;0183; -0183;LATIN SMALL LETTER B WITH TOPBAR;Ll;0;L;;;;;N;LATIN SMALL LETTER B TOPBAR;;0182;;0182 -0184;LATIN CAPITAL LETTER TONE SIX;Lu;0;L;;;;;N;;;;0185; -0185;LATIN SMALL LETTER TONE SIX;Ll;0;L;;;;;N;;;0184;;0184 -0186;LATIN CAPITAL LETTER OPEN O;Lu;0;L;;;;;N;;;;0254; -0187;LATIN CAPITAL LETTER C WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER C HOOK;;;0188; -0188;LATIN SMALL LETTER C WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER C HOOK;;0187;;0187 -0189;LATIN CAPITAL LETTER AFRICAN D;Lu;0;L;;;;;N;;*;;0256; -018A;LATIN CAPITAL LETTER D WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER D HOOK;;;0257; -018B;LATIN CAPITAL LETTER D WITH TOPBAR;Lu;0;L;;;;;N;LATIN CAPITAL LETTER D TOPBAR;;;018C; -018C;LATIN SMALL LETTER D WITH TOPBAR;Ll;0;L;;;;;N;LATIN SMALL LETTER D TOPBAR;;018B;;018B -018D;LATIN SMALL LETTER TURNED DELTA;Ll;0;L;;;;;N;;;;; -018E;LATIN CAPITAL LETTER REVERSED E;Lu;0;L;;;;;N;LATIN CAPITAL LETTER TURNED E;;;01DD; -018F;LATIN CAPITAL LETTER SCHWA;Lu;0;L;;;;;N;;;;0259; -0190;LATIN CAPITAL LETTER OPEN E;Lu;0;L;;;;;N;LATIN CAPITAL LETTER EPSILON;;;025B; -0191;LATIN CAPITAL LETTER F WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER F HOOK;;;0192; -0192;LATIN SMALL LETTER F WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER SCRIPT F;;0191;;0191 -0193;LATIN CAPITAL LETTER G WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER G HOOK;;;0260; -0194;LATIN CAPITAL LETTER GAMMA;Lu;0;L;;;;;N;;;;0263; -0195;LATIN SMALL LETTER HV;Ll;0;L;;;;;N;LATIN SMALL LETTER H V;hwair;01F6;;01F6 -0196;LATIN CAPITAL LETTER IOTA;Lu;0;L;;;;;N;;;;0269; -0197;LATIN CAPITAL LETTER I WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER BARRED I;;;0268; -0198;LATIN CAPITAL LETTER K WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER K HOOK;;;0199; -0199;LATIN SMALL LETTER K WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER K HOOK;;0198;;0198 -019A;LATIN SMALL LETTER L WITH BAR;Ll;0;L;;;;;N;LATIN SMALL LETTER BARRED L;;023D;;023D -019B;LATIN SMALL LETTER LAMBDA WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER BARRED LAMBDA;;;; -019C;LATIN CAPITAL LETTER TURNED M;Lu;0;L;;;;;N;;;;026F; -019D;LATIN CAPITAL LETTER N WITH LEFT HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER N HOOK;;;0272; -019E;LATIN SMALL LETTER N WITH LONG RIGHT LEG;Ll;0;L;;;;;N;;;0220;;0220 -019F;LATIN CAPITAL LETTER O WITH MIDDLE TILDE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER BARRED O;*;;0275; -01A0;LATIN CAPITAL LETTER O WITH HORN;Lu;0;L;004F 031B;;;;N;LATIN CAPITAL LETTER O HORN;;;01A1; -01A1;LATIN SMALL LETTER O WITH HORN;Ll;0;L;006F 031B;;;;N;LATIN SMALL LETTER O HORN;;01A0;;01A0 -01A2;LATIN CAPITAL LETTER OI;Lu;0;L;;;;;N;LATIN CAPITAL LETTER O I;gha;;01A3; -01A3;LATIN SMALL LETTER OI;Ll;0;L;;;;;N;LATIN SMALL LETTER O I;gha;01A2;;01A2 -01A4;LATIN CAPITAL LETTER P WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER P HOOK;;;01A5; -01A5;LATIN SMALL LETTER P WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER P HOOK;;01A4;;01A4 -01A6;LATIN LETTER YR;Lu;0;L;;;;;N;LATIN LETTER Y R;*;;0280; -01A7;LATIN CAPITAL LETTER TONE TWO;Lu;0;L;;;;;N;;;;01A8; -01A8;LATIN SMALL LETTER TONE TWO;Ll;0;L;;;;;N;;;01A7;;01A7 -01A9;LATIN CAPITAL LETTER ESH;Lu;0;L;;;;;N;;;;0283; -01AA;LATIN LETTER REVERSED ESH LOOP;Ll;0;L;;;;;N;;;;; -01AB;LATIN SMALL LETTER T WITH PALATAL HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER T PALATAL HOOK;;;; -01AC;LATIN CAPITAL LETTER T WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER T HOOK;;;01AD; -01AD;LATIN SMALL LETTER T WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER T HOOK;;01AC;;01AC -01AE;LATIN CAPITAL LETTER T WITH RETROFLEX HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER T RETROFLEX HOOK;;;0288; -01AF;LATIN CAPITAL LETTER U WITH HORN;Lu;0;L;0055 031B;;;;N;LATIN CAPITAL LETTER U HORN;;;01B0; -01B0;LATIN SMALL LETTER U WITH HORN;Ll;0;L;0075 031B;;;;N;LATIN SMALL LETTER U HORN;;01AF;;01AF -01B1;LATIN CAPITAL LETTER UPSILON;Lu;0;L;;;;;N;;;;028A; -01B2;LATIN CAPITAL LETTER V WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER SCRIPT V;;;028B; -01B3;LATIN CAPITAL LETTER Y WITH HOOK;Lu;0;L;;;;;N;LATIN CAPITAL LETTER Y HOOK;;;01B4; -01B4;LATIN SMALL LETTER Y WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER Y HOOK;;01B3;;01B3 -01B5;LATIN CAPITAL LETTER Z WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER Z BAR;;;01B6; -01B6;LATIN SMALL LETTER Z WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER Z BAR;;01B5;;01B5 -01B7;LATIN CAPITAL LETTER EZH;Lu;0;L;;;;;N;LATIN CAPITAL LETTER YOGH;;;0292; -01B8;LATIN CAPITAL LETTER EZH REVERSED;Lu;0;L;;;;;N;LATIN CAPITAL LETTER REVERSED YOGH;;;01B9; -01B9;LATIN SMALL LETTER EZH REVERSED;Ll;0;L;;;;;N;LATIN SMALL LETTER REVERSED YOGH;;01B8;;01B8 -01BA;LATIN SMALL LETTER EZH WITH TAIL;Ll;0;L;;;;;N;LATIN SMALL LETTER YOGH WITH TAIL;;;; -01BB;LATIN LETTER TWO WITH STROKE;Lo;0;L;;;;;N;LATIN LETTER TWO BAR;;;; -01BC;LATIN CAPITAL LETTER TONE FIVE;Lu;0;L;;;;;N;;;;01BD; -01BD;LATIN SMALL LETTER TONE FIVE;Ll;0;L;;;;;N;;;01BC;;01BC -01BE;LATIN LETTER INVERTED GLOTTAL STOP WITH STROKE;Ll;0;L;;;;;N;LATIN LETTER INVERTED GLOTTAL STOP BAR;;;; -01BF;LATIN LETTER WYNN;Ll;0;L;;;;;N;;;01F7;;01F7 -01C0;LATIN LETTER DENTAL CLICK;Lo;0;L;;;;;N;LATIN LETTER PIPE;;;; -01C1;LATIN LETTER LATERAL CLICK;Lo;0;L;;;;;N;LATIN LETTER DOUBLE PIPE;;;; -01C2;LATIN LETTER ALVEOLAR CLICK;Lo;0;L;;;;;N;LATIN LETTER PIPE DOUBLE BAR;;;; -01C3;LATIN LETTER RETROFLEX CLICK;Lo;0;L;;;;;N;LATIN LETTER EXCLAMATION MARK;;;; -01C4;LATIN CAPITAL LETTER DZ WITH CARON;Lu;0;L; 0044 017D;;;;N;LATIN CAPITAL LETTER D Z HACEK;;;01C6;01C5 -01C5;LATIN CAPITAL LETTER D WITH SMALL LETTER Z WITH CARON;Lt;0;L; 0044 017E;;;;N;LATIN LETTER CAPITAL D SMALL Z HACEK;;01C4;01C6;01C5 -01C6;LATIN SMALL LETTER DZ WITH CARON;Ll;0;L; 0064 017E;;;;N;LATIN SMALL LETTER D Z HACEK;;01C4;;01C5 -01C7;LATIN CAPITAL LETTER LJ;Lu;0;L; 004C 004A;;;;N;LATIN CAPITAL LETTER L J;;;01C9;01C8 -01C8;LATIN CAPITAL LETTER L WITH SMALL LETTER J;Lt;0;L; 004C 006A;;;;N;LATIN LETTER CAPITAL L SMALL J;;01C7;01C9;01C8 -01C9;LATIN SMALL LETTER LJ;Ll;0;L; 006C 006A;;;;N;LATIN SMALL LETTER L J;;01C7;;01C8 -01CA;LATIN CAPITAL LETTER NJ;Lu;0;L; 004E 004A;;;;N;LATIN CAPITAL LETTER N J;;;01CC;01CB -01CB;LATIN CAPITAL LETTER N WITH SMALL LETTER J;Lt;0;L; 004E 006A;;;;N;LATIN LETTER CAPITAL N SMALL J;;01CA;01CC;01CB -01CC;LATIN SMALL LETTER NJ;Ll;0;L; 006E 006A;;;;N;LATIN SMALL LETTER N J;;01CA;;01CB -01CD;LATIN CAPITAL LETTER A WITH CARON;Lu;0;L;0041 030C;;;;N;LATIN CAPITAL LETTER A HACEK;;;01CE; -01CE;LATIN SMALL LETTER A WITH CARON;Ll;0;L;0061 030C;;;;N;LATIN SMALL LETTER A HACEK;;01CD;;01CD -01CF;LATIN CAPITAL LETTER I WITH CARON;Lu;0;L;0049 030C;;;;N;LATIN CAPITAL LETTER I HACEK;;;01D0; -01D0;LATIN SMALL LETTER I WITH CARON;Ll;0;L;0069 030C;;;;N;LATIN SMALL LETTER I HACEK;;01CF;;01CF -01D1;LATIN CAPITAL LETTER O WITH CARON;Lu;0;L;004F 030C;;;;N;LATIN CAPITAL LETTER O HACEK;;;01D2; -01D2;LATIN SMALL LETTER O WITH CARON;Ll;0;L;006F 030C;;;;N;LATIN SMALL LETTER O HACEK;;01D1;;01D1 -01D3;LATIN CAPITAL LETTER U WITH CARON;Lu;0;L;0055 030C;;;;N;LATIN CAPITAL LETTER U HACEK;;;01D4; -01D4;LATIN SMALL LETTER U WITH CARON;Ll;0;L;0075 030C;;;;N;LATIN SMALL LETTER U HACEK;;01D3;;01D3 -01D5;LATIN CAPITAL LETTER U WITH DIAERESIS AND MACRON;Lu;0;L;00DC 0304;;;;N;LATIN CAPITAL LETTER U DIAERESIS MACRON;;;01D6; -01D6;LATIN SMALL LETTER U WITH DIAERESIS AND MACRON;Ll;0;L;00FC 0304;;;;N;LATIN SMALL LETTER U DIAERESIS MACRON;;01D5;;01D5 -01D7;LATIN CAPITAL LETTER U WITH DIAERESIS AND ACUTE;Lu;0;L;00DC 0301;;;;N;LATIN CAPITAL LETTER U DIAERESIS ACUTE;;;01D8; -01D8;LATIN SMALL LETTER U WITH DIAERESIS AND ACUTE;Ll;0;L;00FC 0301;;;;N;LATIN SMALL LETTER U DIAERESIS ACUTE;;01D7;;01D7 -01D9;LATIN CAPITAL LETTER U WITH DIAERESIS AND CARON;Lu;0;L;00DC 030C;;;;N;LATIN CAPITAL LETTER U DIAERESIS HACEK;;;01DA; -01DA;LATIN SMALL LETTER U WITH DIAERESIS AND CARON;Ll;0;L;00FC 030C;;;;N;LATIN SMALL LETTER U DIAERESIS HACEK;;01D9;;01D9 -01DB;LATIN CAPITAL LETTER U WITH DIAERESIS AND GRAVE;Lu;0;L;00DC 0300;;;;N;LATIN CAPITAL LETTER U DIAERESIS GRAVE;;;01DC; -01DC;LATIN SMALL LETTER U WITH DIAERESIS AND GRAVE;Ll;0;L;00FC 0300;;;;N;LATIN SMALL LETTER U DIAERESIS GRAVE;;01DB;;01DB -01DD;LATIN SMALL LETTER TURNED E;Ll;0;L;;;;;N;;;018E;;018E -01DE;LATIN CAPITAL LETTER A WITH DIAERESIS AND MACRON;Lu;0;L;00C4 0304;;;;N;LATIN CAPITAL LETTER A DIAERESIS MACRON;;;01DF; -01DF;LATIN SMALL LETTER A WITH DIAERESIS AND MACRON;Ll;0;L;00E4 0304;;;;N;LATIN SMALL LETTER A DIAERESIS MACRON;;01DE;;01DE -01E0;LATIN CAPITAL LETTER A WITH DOT ABOVE AND MACRON;Lu;0;L;0226 0304;;;;N;LATIN CAPITAL LETTER A DOT MACRON;;;01E1; -01E1;LATIN SMALL LETTER A WITH DOT ABOVE AND MACRON;Ll;0;L;0227 0304;;;;N;LATIN SMALL LETTER A DOT MACRON;;01E0;;01E0 -01E2;LATIN CAPITAL LETTER AE WITH MACRON;Lu;0;L;00C6 0304;;;;N;LATIN CAPITAL LETTER A E MACRON;ash *;;01E3; -01E3;LATIN SMALL LETTER AE WITH MACRON;Ll;0;L;00E6 0304;;;;N;LATIN SMALL LETTER A E MACRON;ash *;01E2;;01E2 -01E4;LATIN CAPITAL LETTER G WITH STROKE;Lu;0;L;;;;;N;LATIN CAPITAL LETTER G BAR;;;01E5; -01E5;LATIN SMALL LETTER G WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER G BAR;;01E4;;01E4 -01E6;LATIN CAPITAL LETTER G WITH CARON;Lu;0;L;0047 030C;;;;N;LATIN CAPITAL LETTER G HACEK;;;01E7; -01E7;LATIN SMALL LETTER G WITH CARON;Ll;0;L;0067 030C;;;;N;LATIN SMALL LETTER G HACEK;;01E6;;01E6 -01E8;LATIN CAPITAL LETTER K WITH CARON;Lu;0;L;004B 030C;;;;N;LATIN CAPITAL LETTER K HACEK;;;01E9; -01E9;LATIN SMALL LETTER K WITH CARON;Ll;0;L;006B 030C;;;;N;LATIN SMALL LETTER K HACEK;;01E8;;01E8 -01EA;LATIN CAPITAL LETTER O WITH OGONEK;Lu;0;L;004F 0328;;;;N;LATIN CAPITAL LETTER O OGONEK;;;01EB; -01EB;LATIN SMALL LETTER O WITH OGONEK;Ll;0;L;006F 0328;;;;N;LATIN SMALL LETTER O OGONEK;;01EA;;01EA -01EC;LATIN CAPITAL LETTER O WITH OGONEK AND MACRON;Lu;0;L;01EA 0304;;;;N;LATIN CAPITAL LETTER O OGONEK MACRON;;;01ED; -01ED;LATIN SMALL LETTER O WITH OGONEK AND MACRON;Ll;0;L;01EB 0304;;;;N;LATIN SMALL LETTER O OGONEK MACRON;;01EC;;01EC -01EE;LATIN CAPITAL LETTER EZH WITH CARON;Lu;0;L;01B7 030C;;;;N;LATIN CAPITAL LETTER YOGH HACEK;;;01EF; -01EF;LATIN SMALL LETTER EZH WITH CARON;Ll;0;L;0292 030C;;;;N;LATIN SMALL LETTER YOGH HACEK;;01EE;;01EE -01F0;LATIN SMALL LETTER J WITH CARON;Ll;0;L;006A 030C;;;;N;LATIN SMALL LETTER J HACEK;;;; -01F1;LATIN CAPITAL LETTER DZ;Lu;0;L; 0044 005A;;;;N;;;;01F3;01F2 -01F2;LATIN CAPITAL LETTER D WITH SMALL LETTER Z;Lt;0;L; 0044 007A;;;;N;;;01F1;01F3;01F2 -01F3;LATIN SMALL LETTER DZ;Ll;0;L; 0064 007A;;;;N;;;01F1;;01F2 -01F4;LATIN CAPITAL LETTER G WITH ACUTE;Lu;0;L;0047 0301;;;;N;;;;01F5; -01F5;LATIN SMALL LETTER G WITH ACUTE;Ll;0;L;0067 0301;;;;N;;;01F4;;01F4 -01F6;LATIN CAPITAL LETTER HWAIR;Lu;0;L;;;;;N;;;;0195; -01F7;LATIN CAPITAL LETTER WYNN;Lu;0;L;;;;;N;;;;01BF; -01F8;LATIN CAPITAL LETTER N WITH GRAVE;Lu;0;L;004E 0300;;;;N;;;;01F9; -01F9;LATIN SMALL LETTER N WITH GRAVE;Ll;0;L;006E 0300;;;;N;;;01F8;;01F8 -01FA;LATIN CAPITAL LETTER A WITH RING ABOVE AND ACUTE;Lu;0;L;00C5 0301;;;;N;;;;01FB; -01FB;LATIN SMALL LETTER A WITH RING ABOVE AND ACUTE;Ll;0;L;00E5 0301;;;;N;;;01FA;;01FA -01FC;LATIN CAPITAL LETTER AE WITH ACUTE;Lu;0;L;00C6 0301;;;;N;;ash *;;01FD; -01FD;LATIN SMALL LETTER AE WITH ACUTE;Ll;0;L;00E6 0301;;;;N;;ash *;01FC;;01FC -01FE;LATIN CAPITAL LETTER O WITH STROKE AND ACUTE;Lu;0;L;00D8 0301;;;;N;;;;01FF; -01FF;LATIN SMALL LETTER O WITH STROKE AND ACUTE;Ll;0;L;00F8 0301;;;;N;;;01FE;;01FE -0200;LATIN CAPITAL LETTER A WITH DOUBLE GRAVE;Lu;0;L;0041 030F;;;;N;;;;0201; -0201;LATIN SMALL LETTER A WITH DOUBLE GRAVE;Ll;0;L;0061 030F;;;;N;;;0200;;0200 -0202;LATIN CAPITAL LETTER A WITH INVERTED BREVE;Lu;0;L;0041 0311;;;;N;;;;0203; -0203;LATIN SMALL LETTER A WITH INVERTED BREVE;Ll;0;L;0061 0311;;;;N;;;0202;;0202 -0204;LATIN CAPITAL LETTER E WITH DOUBLE GRAVE;Lu;0;L;0045 030F;;;;N;;;;0205; -0205;LATIN SMALL LETTER E WITH DOUBLE GRAVE;Ll;0;L;0065 030F;;;;N;;;0204;;0204 -0206;LATIN CAPITAL LETTER E WITH INVERTED BREVE;Lu;0;L;0045 0311;;;;N;;;;0207; -0207;LATIN SMALL LETTER E WITH INVERTED BREVE;Ll;0;L;0065 0311;;;;N;;;0206;;0206 -0208;LATIN CAPITAL LETTER I WITH DOUBLE GRAVE;Lu;0;L;0049 030F;;;;N;;;;0209; -0209;LATIN SMALL LETTER I WITH DOUBLE GRAVE;Ll;0;L;0069 030F;;;;N;;;0208;;0208 -020A;LATIN CAPITAL LETTER I WITH INVERTED BREVE;Lu;0;L;0049 0311;;;;N;;;;020B; -020B;LATIN SMALL LETTER I WITH INVERTED BREVE;Ll;0;L;0069 0311;;;;N;;;020A;;020A -020C;LATIN CAPITAL LETTER O WITH DOUBLE GRAVE;Lu;0;L;004F 030F;;;;N;;;;020D; -020D;LATIN SMALL LETTER O WITH DOUBLE GRAVE;Ll;0;L;006F 030F;;;;N;;;020C;;020C -020E;LATIN CAPITAL LETTER O WITH INVERTED BREVE;Lu;0;L;004F 0311;;;;N;;;;020F; -020F;LATIN SMALL LETTER O WITH INVERTED BREVE;Ll;0;L;006F 0311;;;;N;;;020E;;020E -0210;LATIN CAPITAL LETTER R WITH DOUBLE GRAVE;Lu;0;L;0052 030F;;;;N;;;;0211; -0211;LATIN SMALL LETTER R WITH DOUBLE GRAVE;Ll;0;L;0072 030F;;;;N;;;0210;;0210 -0212;LATIN CAPITAL LETTER R WITH INVERTED BREVE;Lu;0;L;0052 0311;;;;N;;;;0213; -0213;LATIN SMALL LETTER R WITH INVERTED BREVE;Ll;0;L;0072 0311;;;;N;;;0212;;0212 -0214;LATIN CAPITAL LETTER U WITH DOUBLE GRAVE;Lu;0;L;0055 030F;;;;N;;;;0215; -0215;LATIN SMALL LETTER U WITH DOUBLE GRAVE;Ll;0;L;0075 030F;;;;N;;;0214;;0214 -0216;LATIN CAPITAL LETTER U WITH INVERTED BREVE;Lu;0;L;0055 0311;;;;N;;;;0217; -0217;LATIN SMALL LETTER U WITH INVERTED BREVE;Ll;0;L;0075 0311;;;;N;;;0216;;0216 -0218;LATIN CAPITAL LETTER S WITH COMMA BELOW;Lu;0;L;0053 0326;;;;N;;*;;0219; -0219;LATIN SMALL LETTER S WITH COMMA BELOW;Ll;0;L;0073 0326;;;;N;;*;0218;;0218 -021A;LATIN CAPITAL LETTER T WITH COMMA BELOW;Lu;0;L;0054 0326;;;;N;;*;;021B; -021B;LATIN SMALL LETTER T WITH COMMA BELOW;Ll;0;L;0074 0326;;;;N;;*;021A;;021A -021C;LATIN CAPITAL LETTER YOGH;Lu;0;L;;;;;N;;;;021D; -021D;LATIN SMALL LETTER YOGH;Ll;0;L;;;;;N;;;021C;;021C -021E;LATIN CAPITAL LETTER H WITH CARON;Lu;0;L;0048 030C;;;;N;;;;021F; -021F;LATIN SMALL LETTER H WITH CARON;Ll;0;L;0068 030C;;;;N;;;021E;;021E -0220;LATIN CAPITAL LETTER N WITH LONG RIGHT LEG;Lu;0;L;;;;;N;;;;019E; -0221;LATIN SMALL LETTER D WITH CURL;Ll;0;L;;;;;N;;;;; -0222;LATIN CAPITAL LETTER OU;Lu;0;L;;;;;N;;;;0223; -0223;LATIN SMALL LETTER OU;Ll;0;L;;;;;N;;;0222;;0222 -0224;LATIN CAPITAL LETTER Z WITH HOOK;Lu;0;L;;;;;N;;;;0225; -0225;LATIN SMALL LETTER Z WITH HOOK;Ll;0;L;;;;;N;;;0224;;0224 -0226;LATIN CAPITAL LETTER A WITH DOT ABOVE;Lu;0;L;0041 0307;;;;N;;;;0227; -0227;LATIN SMALL LETTER A WITH DOT ABOVE;Ll;0;L;0061 0307;;;;N;;;0226;;0226 -0228;LATIN CAPITAL LETTER E WITH CEDILLA;Lu;0;L;0045 0327;;;;N;;;;0229; -0229;LATIN SMALL LETTER E WITH CEDILLA;Ll;0;L;0065 0327;;;;N;;;0228;;0228 -022A;LATIN CAPITAL LETTER O WITH DIAERESIS AND MACRON;Lu;0;L;00D6 0304;;;;N;;;;022B; -022B;LATIN SMALL LETTER O WITH DIAERESIS AND MACRON;Ll;0;L;00F6 0304;;;;N;;;022A;;022A -022C;LATIN CAPITAL LETTER O WITH TILDE AND MACRON;Lu;0;L;00D5 0304;;;;N;;;;022D; -022D;LATIN SMALL LETTER O WITH TILDE AND MACRON;Ll;0;L;00F5 0304;;;;N;;;022C;;022C -022E;LATIN CAPITAL LETTER O WITH DOT ABOVE;Lu;0;L;004F 0307;;;;N;;;;022F; -022F;LATIN SMALL LETTER O WITH DOT ABOVE;Ll;0;L;006F 0307;;;;N;;;022E;;022E -0230;LATIN CAPITAL LETTER O WITH DOT ABOVE AND MACRON;Lu;0;L;022E 0304;;;;N;;;;0231; -0231;LATIN SMALL LETTER O WITH DOT ABOVE AND MACRON;Ll;0;L;022F 0304;;;;N;;;0230;;0230 -0232;LATIN CAPITAL LETTER Y WITH MACRON;Lu;0;L;0059 0304;;;;N;;;;0233; -0233;LATIN SMALL LETTER Y WITH MACRON;Ll;0;L;0079 0304;;;;N;;;0232;;0232 -0234;LATIN SMALL LETTER L WITH CURL;Ll;0;L;;;;;N;;;;; -0235;LATIN SMALL LETTER N WITH CURL;Ll;0;L;;;;;N;;;;; -0236;LATIN SMALL LETTER T WITH CURL;Ll;0;L;;;;;N;;;;; -0237;LATIN SMALL LETTER DOTLESS J;Ll;0;L;;;;;N;;;;; -0238;LATIN SMALL LETTER DB DIGRAPH;Ll;0;L;;;;;N;;;;; -0239;LATIN SMALL LETTER QP DIGRAPH;Ll;0;L;;;;;N;;;;; -023A;LATIN CAPITAL LETTER A WITH STROKE;Lu;0;L;;;;;N;;;;2C65; -023B;LATIN CAPITAL LETTER C WITH STROKE;Lu;0;L;;;;;N;;;;023C; -023C;LATIN SMALL LETTER C WITH STROKE;Ll;0;L;;;;;N;;;023B;;023B -023D;LATIN CAPITAL LETTER L WITH BAR;Lu;0;L;;;;;N;;;;019A; -023E;LATIN CAPITAL LETTER T WITH DIAGONAL STROKE;Lu;0;L;;;;;N;;;;2C66; -023F;LATIN SMALL LETTER S WITH SWASH TAIL;Ll;0;L;;;;;N;;;;; -0240;LATIN SMALL LETTER Z WITH SWASH TAIL;Ll;0;L;;;;;N;;;;; -0241;LATIN CAPITAL LETTER GLOTTAL STOP;Lu;0;L;;;;;N;;;;0242; -0242;LATIN SMALL LETTER GLOTTAL STOP;Ll;0;L;;;;;N;;;0241;;0241 -0243;LATIN CAPITAL LETTER B WITH STROKE;Lu;0;L;;;;;N;;;;0180; -0244;LATIN CAPITAL LETTER U BAR;Lu;0;L;;;;;N;;;;0289; -0245;LATIN CAPITAL LETTER TURNED V;Lu;0;L;;;;;N;;;;028C; -0246;LATIN CAPITAL LETTER E WITH STROKE;Lu;0;L;;;;;N;;;;0247; -0247;LATIN SMALL LETTER E WITH STROKE;Ll;0;L;;;;;N;;;0246;;0246 -0248;LATIN CAPITAL LETTER J WITH STROKE;Lu;0;L;;;;;N;;;;0249; -0249;LATIN SMALL LETTER J WITH STROKE;Ll;0;L;;;;;N;;;0248;;0248 -024A;LATIN CAPITAL LETTER SMALL Q WITH HOOK TAIL;Lu;0;L;;;;;N;;;;024B; -024B;LATIN SMALL LETTER Q WITH HOOK TAIL;Ll;0;L;;;;;N;;;024A;;024A -024C;LATIN CAPITAL LETTER R WITH STROKE;Lu;0;L;;;;;N;;;;024D; -024D;LATIN SMALL LETTER R WITH STROKE;Ll;0;L;;;;;N;;;024C;;024C -024E;LATIN CAPITAL LETTER Y WITH STROKE;Lu;0;L;;;;;N;;;;024F; -024F;LATIN SMALL LETTER Y WITH STROKE;Ll;0;L;;;;;N;;;024E;;024E -0250;LATIN SMALL LETTER TURNED A;Ll;0;L;;;;;N;;;2C6F;;2C6F -0251;LATIN SMALL LETTER ALPHA;Ll;0;L;;;;;N;LATIN SMALL LETTER SCRIPT A;;2C6D;;2C6D -0252;LATIN SMALL LETTER TURNED ALPHA;Ll;0;L;;;;;N;LATIN SMALL LETTER TURNED SCRIPT A;;;; -0253;LATIN SMALL LETTER B WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER B HOOK;;0181;;0181 -0254;LATIN SMALL LETTER OPEN O;Ll;0;L;;;;;N;;;0186;;0186 -0255;LATIN SMALL LETTER C WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER C CURL;;;; -0256;LATIN SMALL LETTER D WITH TAIL;Ll;0;L;;;;;N;LATIN SMALL LETTER D RETROFLEX HOOK;;0189;;0189 -0257;LATIN SMALL LETTER D WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER D HOOK;;018A;;018A -0258;LATIN SMALL LETTER REVERSED E;Ll;0;L;;;;;N;;;;; -0259;LATIN SMALL LETTER SCHWA;Ll;0;L;;;;;N;;;018F;;018F -025A;LATIN SMALL LETTER SCHWA WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER SCHWA HOOK;;;; -025B;LATIN SMALL LETTER OPEN E;Ll;0;L;;;;;N;LATIN SMALL LETTER EPSILON;;0190;;0190 -025C;LATIN SMALL LETTER REVERSED OPEN E;Ll;0;L;;;;;N;LATIN SMALL LETTER REVERSED EPSILON;;;; -025D;LATIN SMALL LETTER REVERSED OPEN E WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER REVERSED EPSILON HOOK;;;; -025E;LATIN SMALL LETTER CLOSED REVERSED OPEN E;Ll;0;L;;;;;N;LATIN SMALL LETTER CLOSED REVERSED EPSILON;;;; -025F;LATIN SMALL LETTER DOTLESS J WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER DOTLESS J BAR;;;; -0260;LATIN SMALL LETTER G WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER G HOOK;;0193;;0193 -0261;LATIN SMALL LETTER SCRIPT G;Ll;0;L;;;;;N;;;;; -0262;LATIN LETTER SMALL CAPITAL G;Ll;0;L;;;;;N;;;;; -0263;LATIN SMALL LETTER GAMMA;Ll;0;L;;;;;N;;;0194;;0194 -0264;LATIN SMALL LETTER RAMS HORN;Ll;0;L;;;;;N;LATIN SMALL LETTER BABY GAMMA;;;; -0265;LATIN SMALL LETTER TURNED H;Ll;0;L;;;;;N;;;;; -0266;LATIN SMALL LETTER H WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER H HOOK;;;; -0267;LATIN SMALL LETTER HENG WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER HENG HOOK;;;; -0268;LATIN SMALL LETTER I WITH STROKE;Ll;0;L;;;;;N;LATIN SMALL LETTER BARRED I;;0197;;0197 -0269;LATIN SMALL LETTER IOTA;Ll;0;L;;;;;N;;;0196;;0196 -026A;LATIN LETTER SMALL CAPITAL I;Ll;0;L;;;;;N;;;;; -026B;LATIN SMALL LETTER L WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;2C62;;2C62 -026C;LATIN SMALL LETTER L WITH BELT;Ll;0;L;;;;;N;LATIN SMALL LETTER L BELT;;;; -026D;LATIN SMALL LETTER L WITH RETROFLEX HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER L RETROFLEX HOOK;;;; -026E;LATIN SMALL LETTER LEZH;Ll;0;L;;;;;N;LATIN SMALL LETTER L YOGH;;;; -026F;LATIN SMALL LETTER TURNED M;Ll;0;L;;;;;N;;;019C;;019C -0270;LATIN SMALL LETTER TURNED M WITH LONG LEG;Ll;0;L;;;;;N;;;;; -0271;LATIN SMALL LETTER M WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER M HOOK;;2C6E;;2C6E -0272;LATIN SMALL LETTER N WITH LEFT HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER N HOOK;;019D;;019D -0273;LATIN SMALL LETTER N WITH RETROFLEX HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER N RETROFLEX HOOK;;;; -0274;LATIN LETTER SMALL CAPITAL N;Ll;0;L;;;;;N;;;;; -0275;LATIN SMALL LETTER BARRED O;Ll;0;L;;;;;N;;;019F;;019F -0276;LATIN LETTER SMALL CAPITAL OE;Ll;0;L;;;;;N;LATIN LETTER SMALL CAPITAL O E;;;; -0277;LATIN SMALL LETTER CLOSED OMEGA;Ll;0;L;;;;;N;;;;; -0278;LATIN SMALL LETTER PHI;Ll;0;L;;;;;N;;;;; -0279;LATIN SMALL LETTER TURNED R;Ll;0;L;;;;;N;;;;; -027A;LATIN SMALL LETTER TURNED R WITH LONG LEG;Ll;0;L;;;;;N;;;;; -027B;LATIN SMALL LETTER TURNED R WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER TURNED R HOOK;;;; -027C;LATIN SMALL LETTER R WITH LONG LEG;Ll;0;L;;;;;N;;;;; -027D;LATIN SMALL LETTER R WITH TAIL;Ll;0;L;;;;;N;LATIN SMALL LETTER R HOOK;;2C64;;2C64 -027E;LATIN SMALL LETTER R WITH FISHHOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER FISHHOOK R;;;; -027F;LATIN SMALL LETTER REVERSED R WITH FISHHOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER REVERSED FISHHOOK R;;;; -0280;LATIN LETTER SMALL CAPITAL R;Ll;0;L;;;;;N;;*;01A6;;01A6 -0281;LATIN LETTER SMALL CAPITAL INVERTED R;Ll;0;L;;;;;N;;;;; -0282;LATIN SMALL LETTER S WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER S HOOK;;;; -0283;LATIN SMALL LETTER ESH;Ll;0;L;;;;;N;;;01A9;;01A9 -0284;LATIN SMALL LETTER DOTLESS J WITH STROKE AND HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER DOTLESS J BAR HOOK;;;; -0285;LATIN SMALL LETTER SQUAT REVERSED ESH;Ll;0;L;;;;;N;;;;; -0286;LATIN SMALL LETTER ESH WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER ESH CURL;;;; -0287;LATIN SMALL LETTER TURNED T;Ll;0;L;;;;;N;;;;; -0288;LATIN SMALL LETTER T WITH RETROFLEX HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER T RETROFLEX HOOK;;01AE;;01AE -0289;LATIN SMALL LETTER U BAR;Ll;0;L;;;;;N;;;0244;;0244 -028A;LATIN SMALL LETTER UPSILON;Ll;0;L;;;;;N;;;01B1;;01B1 -028B;LATIN SMALL LETTER V WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER SCRIPT V;;01B2;;01B2 -028C;LATIN SMALL LETTER TURNED V;Ll;0;L;;;;;N;;;0245;;0245 -028D;LATIN SMALL LETTER TURNED W;Ll;0;L;;;;;N;;;;; -028E;LATIN SMALL LETTER TURNED Y;Ll;0;L;;;;;N;;;;; -028F;LATIN LETTER SMALL CAPITAL Y;Ll;0;L;;;;;N;;;;; -0290;LATIN SMALL LETTER Z WITH RETROFLEX HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER Z RETROFLEX HOOK;;;; -0291;LATIN SMALL LETTER Z WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER Z CURL;;;; -0292;LATIN SMALL LETTER EZH;Ll;0;L;;;;;N;LATIN SMALL LETTER YOGH;;01B7;;01B7 -0293;LATIN SMALL LETTER EZH WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER YOGH CURL;;;; -0294;LATIN LETTER GLOTTAL STOP;Lo;0;L;;;;;N;;;;; -0295;LATIN LETTER PHARYNGEAL VOICED FRICATIVE;Ll;0;L;;;;;N;LATIN LETTER REVERSED GLOTTAL STOP;;;; -0296;LATIN LETTER INVERTED GLOTTAL STOP;Ll;0;L;;;;;N;;;;; -0297;LATIN LETTER STRETCHED C;Ll;0;L;;;;;N;;;;; -0298;LATIN LETTER BILABIAL CLICK;Ll;0;L;;;;;N;LATIN LETTER BULLSEYE;;;; -0299;LATIN LETTER SMALL CAPITAL B;Ll;0;L;;;;;N;;;;; -029A;LATIN SMALL LETTER CLOSED OPEN E;Ll;0;L;;;;;N;LATIN SMALL LETTER CLOSED EPSILON;;;; -029B;LATIN LETTER SMALL CAPITAL G WITH HOOK;Ll;0;L;;;;;N;LATIN LETTER SMALL CAPITAL G HOOK;;;; -029C;LATIN LETTER SMALL CAPITAL H;Ll;0;L;;;;;N;;;;; -029D;LATIN SMALL LETTER J WITH CROSSED-TAIL;Ll;0;L;;;;;N;LATIN SMALL LETTER CROSSED-TAIL J;;;; -029E;LATIN SMALL LETTER TURNED K;Ll;0;L;;;;;N;;;;; -029F;LATIN LETTER SMALL CAPITAL L;Ll;0;L;;;;;N;;;;; -02A0;LATIN SMALL LETTER Q WITH HOOK;Ll;0;L;;;;;N;LATIN SMALL LETTER Q HOOK;;;; -02A1;LATIN LETTER GLOTTAL STOP WITH STROKE;Ll;0;L;;;;;N;LATIN LETTER GLOTTAL STOP BAR;;;; -02A2;LATIN LETTER REVERSED GLOTTAL STOP WITH STROKE;Ll;0;L;;;;;N;LATIN LETTER REVERSED GLOTTAL STOP BAR;;;; -02A3;LATIN SMALL LETTER DZ DIGRAPH;Ll;0;L;;;;;N;LATIN SMALL LETTER D Z;;;; -02A4;LATIN SMALL LETTER DEZH DIGRAPH;Ll;0;L;;;;;N;LATIN SMALL LETTER D YOGH;;;; -02A5;LATIN SMALL LETTER DZ DIGRAPH WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER D Z CURL;;;; -02A6;LATIN SMALL LETTER TS DIGRAPH;Ll;0;L;;;;;N;LATIN SMALL LETTER T S;;;; -02A7;LATIN SMALL LETTER TESH DIGRAPH;Ll;0;L;;;;;N;LATIN SMALL LETTER T ESH;;;; -02A8;LATIN SMALL LETTER TC DIGRAPH WITH CURL;Ll;0;L;;;;;N;LATIN SMALL LETTER T C CURL;;;; -02A9;LATIN SMALL LETTER FENG DIGRAPH;Ll;0;L;;;;;N;;;;; -02AA;LATIN SMALL LETTER LS DIGRAPH;Ll;0;L;;;;;N;;;;; -02AB;LATIN SMALL LETTER LZ DIGRAPH;Ll;0;L;;;;;N;;;;; -02AC;LATIN LETTER BILABIAL PERCUSSIVE;Ll;0;L;;;;;N;;;;; -02AD;LATIN LETTER BIDENTAL PERCUSSIVE;Ll;0;L;;;;;N;;;;; -02AE;LATIN SMALL LETTER TURNED H WITH FISHHOOK;Ll;0;L;;;;;N;;;;; -02AF;LATIN SMALL LETTER TURNED H WITH FISHHOOK AND TAIL;Ll;0;L;;;;;N;;;;; -02B0;MODIFIER LETTER SMALL H;Lm;0;L; 0068;;;;N;;;;; -02B1;MODIFIER LETTER SMALL H WITH HOOK;Lm;0;L; 0266;;;;N;MODIFIER LETTER SMALL H HOOK;;;; -02B2;MODIFIER LETTER SMALL J;Lm;0;L; 006A;;;;N;;;;; -02B3;MODIFIER LETTER SMALL R;Lm;0;L; 0072;;;;N;;;;; -02B4;MODIFIER LETTER SMALL TURNED R;Lm;0;L; 0279;;;;N;;;;; -02B5;MODIFIER LETTER SMALL TURNED R WITH HOOK;Lm;0;L; 027B;;;;N;MODIFIER LETTER SMALL TURNED R HOOK;;;; -02B6;MODIFIER LETTER SMALL CAPITAL INVERTED R;Lm;0;L; 0281;;;;N;;;;; -02B7;MODIFIER LETTER SMALL W;Lm;0;L; 0077;;;;N;;;;; -02B8;MODIFIER LETTER SMALL Y;Lm;0;L; 0079;;;;N;;;;; -02B9;MODIFIER LETTER PRIME;Lm;0;ON;;;;;N;;;;; -02BA;MODIFIER LETTER DOUBLE PRIME;Lm;0;ON;;;;;N;;;;; -02BB;MODIFIER LETTER TURNED COMMA;Lm;0;L;;;;;N;;;;; -02BC;MODIFIER LETTER APOSTROPHE;Lm;0;L;;;;;N;;;;; -02BD;MODIFIER LETTER REVERSED COMMA;Lm;0;L;;;;;N;;;;; -02BE;MODIFIER LETTER RIGHT HALF RING;Lm;0;L;;;;;N;;;;; -02BF;MODIFIER LETTER LEFT HALF RING;Lm;0;L;;;;;N;;;;; -02C0;MODIFIER LETTER GLOTTAL STOP;Lm;0;L;;;;;N;;;;; -02C1;MODIFIER LETTER REVERSED GLOTTAL STOP;Lm;0;L;;;;;N;;;;; -02C2;MODIFIER LETTER LEFT ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02C3;MODIFIER LETTER RIGHT ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02C4;MODIFIER LETTER UP ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02C5;MODIFIER LETTER DOWN ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02C6;MODIFIER LETTER CIRCUMFLEX ACCENT;Lm;0;ON;;;;;N;MODIFIER LETTER CIRCUMFLEX;;;; -02C7;CARON;Lm;0;ON;;;;;N;MODIFIER LETTER HACEK;Mandarin Chinese third tone;;; -02C8;MODIFIER LETTER VERTICAL LINE;Lm;0;ON;;;;;N;;;;; -02C9;MODIFIER LETTER MACRON;Lm;0;ON;;;;;N;;Mandarin Chinese first tone;;; -02CA;MODIFIER LETTER ACUTE ACCENT;Lm;0;ON;;;;;N;MODIFIER LETTER ACUTE;Mandarin Chinese second tone;;; -02CB;MODIFIER LETTER GRAVE ACCENT;Lm;0;ON;;;;;N;MODIFIER LETTER GRAVE;Mandarin Chinese fourth tone;;; -02CC;MODIFIER LETTER LOW VERTICAL LINE;Lm;0;ON;;;;;N;;;;; -02CD;MODIFIER LETTER LOW MACRON;Lm;0;ON;;;;;N;;;;; -02CE;MODIFIER LETTER LOW GRAVE ACCENT;Lm;0;ON;;;;;N;MODIFIER LETTER LOW GRAVE;;;; -02CF;MODIFIER LETTER LOW ACUTE ACCENT;Lm;0;ON;;;;;N;MODIFIER LETTER LOW ACUTE;;;; -02D0;MODIFIER LETTER TRIANGULAR COLON;Lm;0;L;;;;;N;;;;; -02D1;MODIFIER LETTER HALF TRIANGULAR COLON;Lm;0;L;;;;;N;;;;; -02D2;MODIFIER LETTER CENTRED RIGHT HALF RING;Sk;0;ON;;;;;N;MODIFIER LETTER CENTERED RIGHT HALF RING;;;; -02D3;MODIFIER LETTER CENTRED LEFT HALF RING;Sk;0;ON;;;;;N;MODIFIER LETTER CENTERED LEFT HALF RING;;;; -02D4;MODIFIER LETTER UP TACK;Sk;0;ON;;;;;N;;;;; -02D5;MODIFIER LETTER DOWN TACK;Sk;0;ON;;;;;N;;;;; -02D6;MODIFIER LETTER PLUS SIGN;Sk;0;ON;;;;;N;;;;; -02D7;MODIFIER LETTER MINUS SIGN;Sk;0;ON;;;;;N;;;;; -02D8;BREVE;Sk;0;ON; 0020 0306;;;;N;SPACING BREVE;;;; -02D9;DOT ABOVE;Sk;0;ON; 0020 0307;;;;N;SPACING DOT ABOVE;Mandarin Chinese light tone;;; -02DA;RING ABOVE;Sk;0;ON; 0020 030A;;;;N;SPACING RING ABOVE;;;; -02DB;OGONEK;Sk;0;ON; 0020 0328;;;;N;SPACING OGONEK;;;; -02DC;SMALL TILDE;Sk;0;ON; 0020 0303;;;;N;SPACING TILDE;;;; -02DD;DOUBLE ACUTE ACCENT;Sk;0;ON; 0020 030B;;;;N;SPACING DOUBLE ACUTE;;;; -02DE;MODIFIER LETTER RHOTIC HOOK;Sk;0;ON;;;;;N;;;;; -02DF;MODIFIER LETTER CROSS ACCENT;Sk;0;ON;;;;;N;;;;; -02E0;MODIFIER LETTER SMALL GAMMA;Lm;0;L; 0263;;;;N;;;;; -02E1;MODIFIER LETTER SMALL L;Lm;0;L; 006C;;;;N;;;;; -02E2;MODIFIER LETTER SMALL S;Lm;0;L; 0073;;;;N;;;;; -02E3;MODIFIER LETTER SMALL X;Lm;0;L; 0078;;;;N;;;;; -02E4;MODIFIER LETTER SMALL REVERSED GLOTTAL STOP;Lm;0;L; 0295;;;;N;;;;; -02E5;MODIFIER LETTER EXTRA-HIGH TONE BAR;Sk;0;ON;;;;;N;;;;; -02E6;MODIFIER LETTER HIGH TONE BAR;Sk;0;ON;;;;;N;;;;; -02E7;MODIFIER LETTER MID TONE BAR;Sk;0;ON;;;;;N;;;;; -02E8;MODIFIER LETTER LOW TONE BAR;Sk;0;ON;;;;;N;;;;; -02E9;MODIFIER LETTER EXTRA-LOW TONE BAR;Sk;0;ON;;;;;N;;;;; -02EA;MODIFIER LETTER YIN DEPARTING TONE MARK;Sk;0;ON;;;;;N;;;;; -02EB;MODIFIER LETTER YANG DEPARTING TONE MARK;Sk;0;ON;;;;;N;;;;; -02EC;MODIFIER LETTER VOICING;Lm;0;ON;;;;;N;;;;; -02ED;MODIFIER LETTER UNASPIRATED;Sk;0;ON;;;;;N;;;;; -02EE;MODIFIER LETTER DOUBLE APOSTROPHE;Lm;0;L;;;;;N;;;;; -02EF;MODIFIER LETTER LOW DOWN ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02F0;MODIFIER LETTER LOW UP ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02F1;MODIFIER LETTER LOW LEFT ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02F2;MODIFIER LETTER LOW RIGHT ARROWHEAD;Sk;0;ON;;;;;N;;;;; -02F3;MODIFIER LETTER LOW RING;Sk;0;ON;;;;;N;;;;; -02F4;MODIFIER LETTER MIDDLE GRAVE ACCENT;Sk;0;ON;;;;;N;;;;; -02F5;MODIFIER LETTER MIDDLE DOUBLE GRAVE ACCENT;Sk;0;ON;;;;;N;;;;; -02F6;MODIFIER LETTER MIDDLE DOUBLE ACUTE ACCENT;Sk;0;ON;;;;;N;;;;; -02F7;MODIFIER LETTER LOW TILDE;Sk;0;ON;;;;;N;;;;; -02F8;MODIFIER LETTER RAISED COLON;Sk;0;ON;;;;;N;;;;; -02F9;MODIFIER LETTER BEGIN HIGH TONE;Sk;0;ON;;;;;N;;;;; -02FA;MODIFIER LETTER END HIGH TONE;Sk;0;ON;;;;;N;;;;; -02FB;MODIFIER LETTER BEGIN LOW TONE;Sk;0;ON;;;;;N;;;;; -02FC;MODIFIER LETTER END LOW TONE;Sk;0;ON;;;;;N;;;;; -02FD;MODIFIER LETTER SHELF;Sk;0;ON;;;;;N;;;;; -02FE;MODIFIER LETTER OPEN SHELF;Sk;0;ON;;;;;N;;;;; -02FF;MODIFIER LETTER LOW LEFT ARROW;Sk;0;ON;;;;;N;;;;; -0300;COMBINING GRAVE ACCENT;Mn;230;NSM;;;;;N;NON-SPACING GRAVE;Varia;;; -0301;COMBINING ACUTE ACCENT;Mn;230;NSM;;;;;N;NON-SPACING ACUTE;Oxia, Tonos;;; -0302;COMBINING CIRCUMFLEX ACCENT;Mn;230;NSM;;;;;N;NON-SPACING CIRCUMFLEX;;;; -0303;COMBINING TILDE;Mn;230;NSM;;;;;N;NON-SPACING TILDE;;;; -0304;COMBINING MACRON;Mn;230;NSM;;;;;N;NON-SPACING MACRON;;;; -0305;COMBINING OVERLINE;Mn;230;NSM;;;;;N;NON-SPACING OVERSCORE;;;; -0306;COMBINING BREVE;Mn;230;NSM;;;;;N;NON-SPACING BREVE;Vrachy;;; -0307;COMBINING DOT ABOVE;Mn;230;NSM;;;;;N;NON-SPACING DOT ABOVE;;;; -0308;COMBINING DIAERESIS;Mn;230;NSM;;;;;N;NON-SPACING DIAERESIS;Dialytika;;; -0309;COMBINING HOOK ABOVE;Mn;230;NSM;;;;;N;NON-SPACING HOOK ABOVE;;;; -030A;COMBINING RING ABOVE;Mn;230;NSM;;;;;N;NON-SPACING RING ABOVE;;;; -030B;COMBINING DOUBLE ACUTE ACCENT;Mn;230;NSM;;;;;N;NON-SPACING DOUBLE ACUTE;;;; -030C;COMBINING CARON;Mn;230;NSM;;;;;N;NON-SPACING HACEK;;;; -030D;COMBINING VERTICAL LINE ABOVE;Mn;230;NSM;;;;;N;NON-SPACING VERTICAL LINE ABOVE;;;; -030E;COMBINING DOUBLE VERTICAL LINE ABOVE;Mn;230;NSM;;;;;N;NON-SPACING DOUBLE VERTICAL LINE ABOVE;;;; -030F;COMBINING DOUBLE GRAVE ACCENT;Mn;230;NSM;;;;;N;NON-SPACING DOUBLE GRAVE;;;; -0310;COMBINING CANDRABINDU;Mn;230;NSM;;;;;N;NON-SPACING CANDRABINDU;;;; -0311;COMBINING INVERTED BREVE;Mn;230;NSM;;;;;N;NON-SPACING INVERTED BREVE;;;; -0312;COMBINING TURNED COMMA ABOVE;Mn;230;NSM;;;;;N;NON-SPACING TURNED COMMA ABOVE;;;; -0313;COMBINING COMMA ABOVE;Mn;230;NSM;;;;;N;NON-SPACING COMMA ABOVE;Psili;;; -0314;COMBINING REVERSED COMMA ABOVE;Mn;230;NSM;;;;;N;NON-SPACING REVERSED COMMA ABOVE;Dasia;;; -0315;COMBINING COMMA ABOVE RIGHT;Mn;232;NSM;;;;;N;NON-SPACING COMMA ABOVE RIGHT;;;; -0316;COMBINING GRAVE ACCENT BELOW;Mn;220;NSM;;;;;N;NON-SPACING GRAVE BELOW;;;; -0317;COMBINING ACUTE ACCENT BELOW;Mn;220;NSM;;;;;N;NON-SPACING ACUTE BELOW;;;; -0318;COMBINING LEFT TACK BELOW;Mn;220;NSM;;;;;N;NON-SPACING LEFT TACK BELOW;;;; -0319;COMBINING RIGHT TACK BELOW;Mn;220;NSM;;;;;N;NON-SPACING RIGHT TACK BELOW;;;; -031A;COMBINING LEFT ANGLE ABOVE;Mn;232;NSM;;;;;N;NON-SPACING LEFT ANGLE ABOVE;;;; -031B;COMBINING HORN;Mn;216;NSM;;;;;N;NON-SPACING HORN;;;; -031C;COMBINING LEFT HALF RING BELOW;Mn;220;NSM;;;;;N;NON-SPACING LEFT HALF RING BELOW;;;; -031D;COMBINING UP TACK BELOW;Mn;220;NSM;;;;;N;NON-SPACING UP TACK BELOW;;;; -031E;COMBINING DOWN TACK BELOW;Mn;220;NSM;;;;;N;NON-SPACING DOWN TACK BELOW;;;; -031F;COMBINING PLUS SIGN BELOW;Mn;220;NSM;;;;;N;NON-SPACING PLUS SIGN BELOW;;;; -0320;COMBINING MINUS SIGN BELOW;Mn;220;NSM;;;;;N;NON-SPACING MINUS SIGN BELOW;;;; -0321;COMBINING PALATALIZED HOOK BELOW;Mn;202;NSM;;;;;N;NON-SPACING PALATALIZED HOOK BELOW;;;; -0322;COMBINING RETROFLEX HOOK BELOW;Mn;202;NSM;;;;;N;NON-SPACING RETROFLEX HOOK BELOW;;;; -0323;COMBINING DOT BELOW;Mn;220;NSM;;;;;N;NON-SPACING DOT BELOW;;;; -0324;COMBINING DIAERESIS BELOW;Mn;220;NSM;;;;;N;NON-SPACING DOUBLE DOT BELOW;;;; -0325;COMBINING RING BELOW;Mn;220;NSM;;;;;N;NON-SPACING RING BELOW;;;; -0326;COMBINING COMMA BELOW;Mn;220;NSM;;;;;N;NON-SPACING COMMA BELOW;;;; -0327;COMBINING CEDILLA;Mn;202;NSM;;;;;N;NON-SPACING CEDILLA;;;; -0328;COMBINING OGONEK;Mn;202;NSM;;;;;N;NON-SPACING OGONEK;;;; -0329;COMBINING VERTICAL LINE BELOW;Mn;220;NSM;;;;;N;NON-SPACING VERTICAL LINE BELOW;;;; -032A;COMBINING BRIDGE BELOW;Mn;220;NSM;;;;;N;NON-SPACING BRIDGE BELOW;;;; -032B;COMBINING INVERTED DOUBLE ARCH BELOW;Mn;220;NSM;;;;;N;NON-SPACING INVERTED DOUBLE ARCH BELOW;;;; -032C;COMBINING CARON BELOW;Mn;220;NSM;;;;;N;NON-SPACING HACEK BELOW;;;; -032D;COMBINING CIRCUMFLEX ACCENT BELOW;Mn;220;NSM;;;;;N;NON-SPACING CIRCUMFLEX BELOW;;;; -032E;COMBINING BREVE BELOW;Mn;220;NSM;;;;;N;NON-SPACING BREVE BELOW;;;; -032F;COMBINING INVERTED BREVE BELOW;Mn;220;NSM;;;;;N;NON-SPACING INVERTED BREVE BELOW;;;; -0330;COMBINING TILDE BELOW;Mn;220;NSM;;;;;N;NON-SPACING TILDE BELOW;;;; -0331;COMBINING MACRON BELOW;Mn;220;NSM;;;;;N;NON-SPACING MACRON BELOW;;;; -0332;COMBINING LOW LINE;Mn;220;NSM;;;;;N;NON-SPACING UNDERSCORE;;;; -0333;COMBINING DOUBLE LOW LINE;Mn;220;NSM;;;;;N;NON-SPACING DOUBLE UNDERSCORE;;;; -0334;COMBINING TILDE OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING TILDE OVERLAY;;;; -0335;COMBINING SHORT STROKE OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING SHORT BAR OVERLAY;;;; -0336;COMBINING LONG STROKE OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING LONG BAR OVERLAY;;;; -0337;COMBINING SHORT SOLIDUS OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING SHORT SLASH OVERLAY;;;; -0338;COMBINING LONG SOLIDUS OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING LONG SLASH OVERLAY;;;; -0339;COMBINING RIGHT HALF RING BELOW;Mn;220;NSM;;;;;N;NON-SPACING RIGHT HALF RING BELOW;;;; -033A;COMBINING INVERTED BRIDGE BELOW;Mn;220;NSM;;;;;N;NON-SPACING INVERTED BRIDGE BELOW;;;; -033B;COMBINING SQUARE BELOW;Mn;220;NSM;;;;;N;NON-SPACING SQUARE BELOW;;;; -033C;COMBINING SEAGULL BELOW;Mn;220;NSM;;;;;N;NON-SPACING SEAGULL BELOW;;;; -033D;COMBINING X ABOVE;Mn;230;NSM;;;;;N;NON-SPACING X ABOVE;;;; -033E;COMBINING VERTICAL TILDE;Mn;230;NSM;;;;;N;NON-SPACING VERTICAL TILDE;;;; -033F;COMBINING DOUBLE OVERLINE;Mn;230;NSM;;;;;N;NON-SPACING DOUBLE OVERSCORE;;;; -0340;COMBINING GRAVE TONE MARK;Mn;230;NSM;0300;;;;N;NON-SPACING GRAVE TONE MARK;Vietnamese;;; -0341;COMBINING ACUTE TONE MARK;Mn;230;NSM;0301;;;;N;NON-SPACING ACUTE TONE MARK;Vietnamese;;; -0342;COMBINING GREEK PERISPOMENI;Mn;230;NSM;;;;;N;;;;; -0343;COMBINING GREEK KORONIS;Mn;230;NSM;0313;;;;N;;;;; -0344;COMBINING GREEK DIALYTIKA TONOS;Mn;230;NSM;0308 0301;;;;N;GREEK NON-SPACING DIAERESIS TONOS;;;; -0345;COMBINING GREEK YPOGEGRAMMENI;Mn;240;NSM;;;;;N;GREEK NON-SPACING IOTA BELOW;;0399;;0399 -0346;COMBINING BRIDGE ABOVE;Mn;230;NSM;;;;;N;;;;; -0347;COMBINING EQUALS SIGN BELOW;Mn;220;NSM;;;;;N;;;;; -0348;COMBINING DOUBLE VERTICAL LINE BELOW;Mn;220;NSM;;;;;N;;;;; -0349;COMBINING LEFT ANGLE BELOW;Mn;220;NSM;;;;;N;;;;; -034A;COMBINING NOT TILDE ABOVE;Mn;230;NSM;;;;;N;;;;; -034B;COMBINING HOMOTHETIC ABOVE;Mn;230;NSM;;;;;N;;;;; -034C;COMBINING ALMOST EQUAL TO ABOVE;Mn;230;NSM;;;;;N;;;;; -034D;COMBINING LEFT RIGHT ARROW BELOW;Mn;220;NSM;;;;;N;;;;; -034E;COMBINING UPWARDS ARROW BELOW;Mn;220;NSM;;;;;N;;;;; -034F;COMBINING GRAPHEME JOINER;Mn;0;NSM;;;;;N;;;;; -0350;COMBINING RIGHT ARROWHEAD ABOVE;Mn;230;NSM;;;;;N;;;;; -0351;COMBINING LEFT HALF RING ABOVE;Mn;230;NSM;;;;;N;;;;; -0352;COMBINING FERMATA;Mn;230;NSM;;;;;N;;;;; -0353;COMBINING X BELOW;Mn;220;NSM;;;;;N;;;;; -0354;COMBINING LEFT ARROWHEAD BELOW;Mn;220;NSM;;;;;N;;;;; -0355;COMBINING RIGHT ARROWHEAD BELOW;Mn;220;NSM;;;;;N;;;;; -0356;COMBINING RIGHT ARROWHEAD AND UP ARROWHEAD BELOW;Mn;220;NSM;;;;;N;;;;; -0357;COMBINING RIGHT HALF RING ABOVE;Mn;230;NSM;;;;;N;;;;; -0358;COMBINING DOT ABOVE RIGHT;Mn;232;NSM;;;;;N;;;;; -0359;COMBINING ASTERISK BELOW;Mn;220;NSM;;;;;N;;;;; -035A;COMBINING DOUBLE RING BELOW;Mn;220;NSM;;;;;N;;;;; -035B;COMBINING ZIGZAG ABOVE;Mn;230;NSM;;;;;N;;;;; -035C;COMBINING DOUBLE BREVE BELOW;Mn;233;NSM;;;;;N;;;;; -035D;COMBINING DOUBLE BREVE;Mn;234;NSM;;;;;N;;;;; -035E;COMBINING DOUBLE MACRON;Mn;234;NSM;;;;;N;;;;; -035F;COMBINING DOUBLE MACRON BELOW;Mn;233;NSM;;;;;N;;;;; -0360;COMBINING DOUBLE TILDE;Mn;234;NSM;;;;;N;;;;; -0361;COMBINING DOUBLE INVERTED BREVE;Mn;234;NSM;;;;;N;;;;; -0362;COMBINING DOUBLE RIGHTWARDS ARROW BELOW;Mn;233;NSM;;;;;N;;;;; -0363;COMBINING LATIN SMALL LETTER A;Mn;230;NSM;;;;;N;;;;; -0364;COMBINING LATIN SMALL LETTER E;Mn;230;NSM;;;;;N;;;;; -0365;COMBINING LATIN SMALL LETTER I;Mn;230;NSM;;;;;N;;;;; -0366;COMBINING LATIN SMALL LETTER O;Mn;230;NSM;;;;;N;;;;; -0367;COMBINING LATIN SMALL LETTER U;Mn;230;NSM;;;;;N;;;;; -0368;COMBINING LATIN SMALL LETTER C;Mn;230;NSM;;;;;N;;;;; -0369;COMBINING LATIN SMALL LETTER D;Mn;230;NSM;;;;;N;;;;; -036A;COMBINING LATIN SMALL LETTER H;Mn;230;NSM;;;;;N;;;;; -036B;COMBINING LATIN SMALL LETTER M;Mn;230;NSM;;;;;N;;;;; -036C;COMBINING LATIN SMALL LETTER R;Mn;230;NSM;;;;;N;;;;; -036D;COMBINING LATIN SMALL LETTER T;Mn;230;NSM;;;;;N;;;;; -036E;COMBINING LATIN SMALL LETTER V;Mn;230;NSM;;;;;N;;;;; -036F;COMBINING LATIN SMALL LETTER X;Mn;230;NSM;;;;;N;;;;; -0370;GREEK CAPITAL LETTER HETA;Lu;0;L;;;;;N;;;;0371; -0371;GREEK SMALL LETTER HETA;Ll;0;L;;;;;N;;;0370;;0370 -0372;GREEK CAPITAL LETTER ARCHAIC SAMPI;Lu;0;L;;;;;N;;;;0373; -0373;GREEK SMALL LETTER ARCHAIC SAMPI;Ll;0;L;;;;;N;;;0372;;0372 -0374;GREEK NUMERAL SIGN;Lm;0;ON;02B9;;;;N;GREEK UPPER NUMERAL SIGN;Dexia keraia;;; -0375;GREEK LOWER NUMERAL SIGN;Sk;0;ON;;;;;N;;Aristeri keraia;;; -0376;GREEK CAPITAL LETTER PAMPHYLIAN DIGAMMA;Lu;0;L;;;;;N;;;;0377; -0377;GREEK SMALL LETTER PAMPHYLIAN DIGAMMA;Ll;0;L;;;;;N;;;0376;;0376 -037A;GREEK YPOGEGRAMMENI;Lm;0;L; 0020 0345;;;;N;GREEK SPACING IOTA BELOW;;;; -037B;GREEK SMALL REVERSED LUNATE SIGMA SYMBOL;Ll;0;L;;;;;N;;;03FD;;03FD -037C;GREEK SMALL DOTTED LUNATE SIGMA SYMBOL;Ll;0;L;;;;;N;;;03FE;;03FE -037D;GREEK SMALL REVERSED DOTTED LUNATE SIGMA SYMBOL;Ll;0;L;;;;;N;;;03FF;;03FF -037E;GREEK QUESTION MARK;Po;0;ON;003B;;;;N;;Erotimatiko;;; -0384;GREEK TONOS;Sk;0;ON; 0020 0301;;;;N;GREEK SPACING TONOS;;;; -0385;GREEK DIALYTIKA TONOS;Sk;0;ON;00A8 0301;;;;N;GREEK SPACING DIAERESIS TONOS;;;; -0386;GREEK CAPITAL LETTER ALPHA WITH TONOS;Lu;0;L;0391 0301;;;;N;GREEK CAPITAL LETTER ALPHA TONOS;;;03AC; -0387;GREEK ANO TELEIA;Po;0;ON;00B7;;;;N;;;;; -0388;GREEK CAPITAL LETTER EPSILON WITH TONOS;Lu;0;L;0395 0301;;;;N;GREEK CAPITAL LETTER EPSILON TONOS;;;03AD; -0389;GREEK CAPITAL LETTER ETA WITH TONOS;Lu;0;L;0397 0301;;;;N;GREEK CAPITAL LETTER ETA TONOS;;;03AE; -038A;GREEK CAPITAL LETTER IOTA WITH TONOS;Lu;0;L;0399 0301;;;;N;GREEK CAPITAL LETTER IOTA TONOS;;;03AF; -038C;GREEK CAPITAL LETTER OMICRON WITH TONOS;Lu;0;L;039F 0301;;;;N;GREEK CAPITAL LETTER OMICRON TONOS;;;03CC; -038E;GREEK CAPITAL LETTER UPSILON WITH TONOS;Lu;0;L;03A5 0301;;;;N;GREEK CAPITAL LETTER UPSILON TONOS;;;03CD; -038F;GREEK CAPITAL LETTER OMEGA WITH TONOS;Lu;0;L;03A9 0301;;;;N;GREEK CAPITAL LETTER OMEGA TONOS;;;03CE; -0390;GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS;Ll;0;L;03CA 0301;;;;N;GREEK SMALL LETTER IOTA DIAERESIS TONOS;;;; -0391;GREEK CAPITAL LETTER ALPHA;Lu;0;L;;;;;N;;;;03B1; -0392;GREEK CAPITAL LETTER BETA;Lu;0;L;;;;;N;;;;03B2; -0393;GREEK CAPITAL LETTER GAMMA;Lu;0;L;;;;;N;;;;03B3; -0394;GREEK CAPITAL LETTER DELTA;Lu;0;L;;;;;N;;;;03B4; -0395;GREEK CAPITAL LETTER EPSILON;Lu;0;L;;;;;N;;;;03B5; -0396;GREEK CAPITAL LETTER ZETA;Lu;0;L;;;;;N;;;;03B6; -0397;GREEK CAPITAL LETTER ETA;Lu;0;L;;;;;N;;;;03B7; -0398;GREEK CAPITAL LETTER THETA;Lu;0;L;;;;;N;;;;03B8; -0399;GREEK CAPITAL LETTER IOTA;Lu;0;L;;;;;N;;;;03B9; -039A;GREEK CAPITAL LETTER KAPPA;Lu;0;L;;;;;N;;;;03BA; -039B;GREEK CAPITAL LETTER LAMDA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER LAMBDA;;;03BB; -039C;GREEK CAPITAL LETTER MU;Lu;0;L;;;;;N;;;;03BC; -039D;GREEK CAPITAL LETTER NU;Lu;0;L;;;;;N;;;;03BD; -039E;GREEK CAPITAL LETTER XI;Lu;0;L;;;;;N;;;;03BE; -039F;GREEK CAPITAL LETTER OMICRON;Lu;0;L;;;;;N;;;;03BF; -03A0;GREEK CAPITAL LETTER PI;Lu;0;L;;;;;N;;;;03C0; -03A1;GREEK CAPITAL LETTER RHO;Lu;0;L;;;;;N;;;;03C1; -03A3;GREEK CAPITAL LETTER SIGMA;Lu;0;L;;;;;N;;;;03C3; -03A4;GREEK CAPITAL LETTER TAU;Lu;0;L;;;;;N;;;;03C4; -03A5;GREEK CAPITAL LETTER UPSILON;Lu;0;L;;;;;N;;;;03C5; -03A6;GREEK CAPITAL LETTER PHI;Lu;0;L;;;;;N;;;;03C6; -03A7;GREEK CAPITAL LETTER CHI;Lu;0;L;;;;;N;;;;03C7; -03A8;GREEK CAPITAL LETTER PSI;Lu;0;L;;;;;N;;;;03C8; -03A9;GREEK CAPITAL LETTER OMEGA;Lu;0;L;;;;;N;;;;03C9; -03AA;GREEK CAPITAL LETTER IOTA WITH DIALYTIKA;Lu;0;L;0399 0308;;;;N;GREEK CAPITAL LETTER IOTA DIAERESIS;;;03CA; -03AB;GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA;Lu;0;L;03A5 0308;;;;N;GREEK CAPITAL LETTER UPSILON DIAERESIS;;;03CB; -03AC;GREEK SMALL LETTER ALPHA WITH TONOS;Ll;0;L;03B1 0301;;;;N;GREEK SMALL LETTER ALPHA TONOS;;0386;;0386 -03AD;GREEK SMALL LETTER EPSILON WITH TONOS;Ll;0;L;03B5 0301;;;;N;GREEK SMALL LETTER EPSILON TONOS;;0388;;0388 -03AE;GREEK SMALL LETTER ETA WITH TONOS;Ll;0;L;03B7 0301;;;;N;GREEK SMALL LETTER ETA TONOS;;0389;;0389 -03AF;GREEK SMALL LETTER IOTA WITH TONOS;Ll;0;L;03B9 0301;;;;N;GREEK SMALL LETTER IOTA TONOS;;038A;;038A -03B0;GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS;Ll;0;L;03CB 0301;;;;N;GREEK SMALL LETTER UPSILON DIAERESIS TONOS;;;; -03B1;GREEK SMALL LETTER ALPHA;Ll;0;L;;;;;N;;;0391;;0391 -03B2;GREEK SMALL LETTER BETA;Ll;0;L;;;;;N;;;0392;;0392 -03B3;GREEK SMALL LETTER GAMMA;Ll;0;L;;;;;N;;;0393;;0393 -03B4;GREEK SMALL LETTER DELTA;Ll;0;L;;;;;N;;;0394;;0394 -03B5;GREEK SMALL LETTER EPSILON;Ll;0;L;;;;;N;;;0395;;0395 -03B6;GREEK SMALL LETTER ZETA;Ll;0;L;;;;;N;;;0396;;0396 -03B7;GREEK SMALL LETTER ETA;Ll;0;L;;;;;N;;;0397;;0397 -03B8;GREEK SMALL LETTER THETA;Ll;0;L;;;;;N;;;0398;;0398 -03B9;GREEK SMALL LETTER IOTA;Ll;0;L;;;;;N;;;0399;;0399 -03BA;GREEK SMALL LETTER KAPPA;Ll;0;L;;;;;N;;;039A;;039A -03BB;GREEK SMALL LETTER LAMDA;Ll;0;L;;;;;N;GREEK SMALL LETTER LAMBDA;;039B;;039B -03BC;GREEK SMALL LETTER MU;Ll;0;L;;;;;N;;;039C;;039C -03BD;GREEK SMALL LETTER NU;Ll;0;L;;;;;N;;;039D;;039D -03BE;GREEK SMALL LETTER XI;Ll;0;L;;;;;N;;;039E;;039E -03BF;GREEK SMALL LETTER OMICRON;Ll;0;L;;;;;N;;;039F;;039F -03C0;GREEK SMALL LETTER PI;Ll;0;L;;;;;N;;;03A0;;03A0 -03C1;GREEK SMALL LETTER RHO;Ll;0;L;;;;;N;;;03A1;;03A1 -03C2;GREEK SMALL LETTER FINAL SIGMA;Ll;0;L;;;;;N;;;03A3;;03A3 -03C3;GREEK SMALL LETTER SIGMA;Ll;0;L;;;;;N;;;03A3;;03A3 -03C4;GREEK SMALL LETTER TAU;Ll;0;L;;;;;N;;;03A4;;03A4 -03C5;GREEK SMALL LETTER UPSILON;Ll;0;L;;;;;N;;;03A5;;03A5 -03C6;GREEK SMALL LETTER PHI;Ll;0;L;;;;;N;;;03A6;;03A6 -03C7;GREEK SMALL LETTER CHI;Ll;0;L;;;;;N;;;03A7;;03A7 -03C8;GREEK SMALL LETTER PSI;Ll;0;L;;;;;N;;;03A8;;03A8 -03C9;GREEK SMALL LETTER OMEGA;Ll;0;L;;;;;N;;;03A9;;03A9 -03CA;GREEK SMALL LETTER IOTA WITH DIALYTIKA;Ll;0;L;03B9 0308;;;;N;GREEK SMALL LETTER IOTA DIAERESIS;;03AA;;03AA -03CB;GREEK SMALL LETTER UPSILON WITH DIALYTIKA;Ll;0;L;03C5 0308;;;;N;GREEK SMALL LETTER UPSILON DIAERESIS;;03AB;;03AB -03CC;GREEK SMALL LETTER OMICRON WITH TONOS;Ll;0;L;03BF 0301;;;;N;GREEK SMALL LETTER OMICRON TONOS;;038C;;038C -03CD;GREEK SMALL LETTER UPSILON WITH TONOS;Ll;0;L;03C5 0301;;;;N;GREEK SMALL LETTER UPSILON TONOS;;038E;;038E -03CE;GREEK SMALL LETTER OMEGA WITH TONOS;Ll;0;L;03C9 0301;;;;N;GREEK SMALL LETTER OMEGA TONOS;;038F;;038F -03CF;GREEK CAPITAL KAI SYMBOL;Lu;0;L;;;;;N;;;;03D7; -03D0;GREEK BETA SYMBOL;Ll;0;L; 03B2;;;;N;GREEK SMALL LETTER CURLED BETA;;0392;;0392 -03D1;GREEK THETA SYMBOL;Ll;0;L; 03B8;;;;N;GREEK SMALL LETTER SCRIPT THETA;;0398;;0398 -03D2;GREEK UPSILON WITH HOOK SYMBOL;Lu;0;L; 03A5;;;;N;GREEK CAPITAL LETTER UPSILON HOOK;;;; -03D3;GREEK UPSILON WITH ACUTE AND HOOK SYMBOL;Lu;0;L;03D2 0301;;;;N;GREEK CAPITAL LETTER UPSILON HOOK TONOS;;;; -03D4;GREEK UPSILON WITH DIAERESIS AND HOOK SYMBOL;Lu;0;L;03D2 0308;;;;N;GREEK CAPITAL LETTER UPSILON HOOK DIAERESIS;;;; -03D5;GREEK PHI SYMBOL;Ll;0;L; 03C6;;;;N;GREEK SMALL LETTER SCRIPT PHI;;03A6;;03A6 -03D6;GREEK PI SYMBOL;Ll;0;L; 03C0;;;;N;GREEK SMALL LETTER OMEGA PI;;03A0;;03A0 -03D7;GREEK KAI SYMBOL;Ll;0;L;;;;;N;;;03CF;;03CF -03D8;GREEK LETTER ARCHAIC KOPPA;Lu;0;L;;;;;N;;*;;03D9; -03D9;GREEK SMALL LETTER ARCHAIC KOPPA;Ll;0;L;;;;;N;;*;03D8;;03D8 -03DA;GREEK LETTER STIGMA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER STIGMA;;;03DB; -03DB;GREEK SMALL LETTER STIGMA;Ll;0;L;;;;;N;;;03DA;;03DA -03DC;GREEK LETTER DIGAMMA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER DIGAMMA;;;03DD; -03DD;GREEK SMALL LETTER DIGAMMA;Ll;0;L;;;;;N;;;03DC;;03DC -03DE;GREEK LETTER KOPPA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER KOPPA;;;03DF; -03DF;GREEK SMALL LETTER KOPPA;Ll;0;L;;;;;N;;;03DE;;03DE -03E0;GREEK LETTER SAMPI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER SAMPI;;;03E1; -03E1;GREEK SMALL LETTER SAMPI;Ll;0;L;;;;;N;;;03E0;;03E0 -03E2;COPTIC CAPITAL LETTER SHEI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER SHEI;;;03E3; -03E3;COPTIC SMALL LETTER SHEI;Ll;0;L;;;;;N;GREEK SMALL LETTER SHEI;;03E2;;03E2 -03E4;COPTIC CAPITAL LETTER FEI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER FEI;;;03E5; -03E5;COPTIC SMALL LETTER FEI;Ll;0;L;;;;;N;GREEK SMALL LETTER FEI;;03E4;;03E4 -03E6;COPTIC CAPITAL LETTER KHEI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER KHEI;;;03E7; -03E7;COPTIC SMALL LETTER KHEI;Ll;0;L;;;;;N;GREEK SMALL LETTER KHEI;;03E6;;03E6 -03E8;COPTIC CAPITAL LETTER HORI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER HORI;;;03E9; -03E9;COPTIC SMALL LETTER HORI;Ll;0;L;;;;;N;GREEK SMALL LETTER HORI;;03E8;;03E8 -03EA;COPTIC CAPITAL LETTER GANGIA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER GANGIA;;;03EB; -03EB;COPTIC SMALL LETTER GANGIA;Ll;0;L;;;;;N;GREEK SMALL LETTER GANGIA;;03EA;;03EA -03EC;COPTIC CAPITAL LETTER SHIMA;Lu;0;L;;;;;N;GREEK CAPITAL LETTER SHIMA;;;03ED; -03ED;COPTIC SMALL LETTER SHIMA;Ll;0;L;;;;;N;GREEK SMALL LETTER SHIMA;;03EC;;03EC -03EE;COPTIC CAPITAL LETTER DEI;Lu;0;L;;;;;N;GREEK CAPITAL LETTER DEI;;;03EF; -03EF;COPTIC SMALL LETTER DEI;Ll;0;L;;;;;N;GREEK SMALL LETTER DEI;;03EE;;03EE -03F0;GREEK KAPPA SYMBOL;Ll;0;L; 03BA;;;;N;GREEK SMALL LETTER SCRIPT KAPPA;;039A;;039A -03F1;GREEK RHO SYMBOL;Ll;0;L; 03C1;;;;N;GREEK SMALL LETTER TAILED RHO;;03A1;;03A1 -03F2;GREEK LUNATE SIGMA SYMBOL;Ll;0;L; 03C2;;;;N;GREEK SMALL LETTER LUNATE SIGMA;;03F9;;03F9 -03F3;GREEK LETTER YOT;Ll;0;L;;;;;N;;;;; -03F4;GREEK CAPITAL THETA SYMBOL;Lu;0;L; 0398;;;;N;;;;03B8; -03F5;GREEK LUNATE EPSILON SYMBOL;Ll;0;L; 03B5;;;;N;;;0395;;0395 -03F6;GREEK REVERSED LUNATE EPSILON SYMBOL;Sm;0;ON;;;;;N;;;;; -03F7;GREEK CAPITAL LETTER SHO;Lu;0;L;;;;;N;;;;03F8; -03F8;GREEK SMALL LETTER SHO;Ll;0;L;;;;;N;;;03F7;;03F7 -03F9;GREEK CAPITAL LUNATE SIGMA SYMBOL;Lu;0;L; 03A3;;;;N;;;;03F2; -03FA;GREEK CAPITAL LETTER SAN;Lu;0;L;;;;;N;;;;03FB; -03FB;GREEK SMALL LETTER SAN;Ll;0;L;;;;;N;;;03FA;;03FA -03FC;GREEK RHO WITH STROKE SYMBOL;Ll;0;L;;;;;N;;;;; -03FD;GREEK CAPITAL REVERSED LUNATE SIGMA SYMBOL;Lu;0;L;;;;;N;;;;037B; -03FE;GREEK CAPITAL DOTTED LUNATE SIGMA SYMBOL;Lu;0;L;;;;;N;;;;037C; -03FF;GREEK CAPITAL REVERSED DOTTED LUNATE SIGMA SYMBOL;Lu;0;L;;;;;N;;;;037D; -0400;CYRILLIC CAPITAL LETTER IE WITH GRAVE;Lu;0;L;0415 0300;;;;N;;;;0450; -0401;CYRILLIC CAPITAL LETTER IO;Lu;0;L;0415 0308;;;;N;;;;0451; -0402;CYRILLIC CAPITAL LETTER DJE;Lu;0;L;;;;;N;;Serbocroatian;;0452; -0403;CYRILLIC CAPITAL LETTER GJE;Lu;0;L;0413 0301;;;;N;;;;0453; -0404;CYRILLIC CAPITAL LETTER UKRAINIAN IE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER E;;;0454; -0405;CYRILLIC CAPITAL LETTER DZE;Lu;0;L;;;;;N;;;;0455; -0406;CYRILLIC CAPITAL LETTER BYELORUSSIAN-UKRAINIAN I;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER I;;;0456; -0407;CYRILLIC CAPITAL LETTER YI;Lu;0;L;0406 0308;;;;N;;Ukrainian;;0457; -0408;CYRILLIC CAPITAL LETTER JE;Lu;0;L;;;;;N;;;;0458; -0409;CYRILLIC CAPITAL LETTER LJE;Lu;0;L;;;;;N;;;;0459; -040A;CYRILLIC CAPITAL LETTER NJE;Lu;0;L;;;;;N;;;;045A; -040B;CYRILLIC CAPITAL LETTER TSHE;Lu;0;L;;;;;N;;Serbocroatian;;045B; -040C;CYRILLIC CAPITAL LETTER KJE;Lu;0;L;041A 0301;;;;N;;;;045C; -040D;CYRILLIC CAPITAL LETTER I WITH GRAVE;Lu;0;L;0418 0300;;;;N;;;;045D; -040E;CYRILLIC CAPITAL LETTER SHORT U;Lu;0;L;0423 0306;;;;N;;Byelorussian;;045E; -040F;CYRILLIC CAPITAL LETTER DZHE;Lu;0;L;;;;;N;;;;045F; -0410;CYRILLIC CAPITAL LETTER A;Lu;0;L;;;;;N;;;;0430; -0411;CYRILLIC CAPITAL LETTER BE;Lu;0;L;;;;;N;;;;0431; -0412;CYRILLIC CAPITAL LETTER VE;Lu;0;L;;;;;N;;;;0432; -0413;CYRILLIC CAPITAL LETTER GHE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER GE;;;0433; -0414;CYRILLIC CAPITAL LETTER DE;Lu;0;L;;;;;N;;;;0434; -0415;CYRILLIC CAPITAL LETTER IE;Lu;0;L;;;;;N;;;;0435; -0416;CYRILLIC CAPITAL LETTER ZHE;Lu;0;L;;;;;N;;;;0436; -0417;CYRILLIC CAPITAL LETTER ZE;Lu;0;L;;;;;N;;;;0437; -0418;CYRILLIC CAPITAL LETTER I;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER II;;;0438; -0419;CYRILLIC CAPITAL LETTER SHORT I;Lu;0;L;0418 0306;;;;N;CYRILLIC CAPITAL LETTER SHORT II;;;0439; -041A;CYRILLIC CAPITAL LETTER KA;Lu;0;L;;;;;N;;;;043A; -041B;CYRILLIC CAPITAL LETTER EL;Lu;0;L;;;;;N;;;;043B; -041C;CYRILLIC CAPITAL LETTER EM;Lu;0;L;;;;;N;;;;043C; -041D;CYRILLIC CAPITAL LETTER EN;Lu;0;L;;;;;N;;;;043D; -041E;CYRILLIC CAPITAL LETTER O;Lu;0;L;;;;;N;;;;043E; -041F;CYRILLIC CAPITAL LETTER PE;Lu;0;L;;;;;N;;;;043F; -0420;CYRILLIC CAPITAL LETTER ER;Lu;0;L;;;;;N;;;;0440; -0421;CYRILLIC CAPITAL LETTER ES;Lu;0;L;;;;;N;;;;0441; -0422;CYRILLIC CAPITAL LETTER TE;Lu;0;L;;;;;N;;;;0442; -0423;CYRILLIC CAPITAL LETTER U;Lu;0;L;;;;;N;;;;0443; -0424;CYRILLIC CAPITAL LETTER EF;Lu;0;L;;;;;N;;;;0444; -0425;CYRILLIC CAPITAL LETTER HA;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KHA;;;0445; -0426;CYRILLIC CAPITAL LETTER TSE;Lu;0;L;;;;;N;;;;0446; -0427;CYRILLIC CAPITAL LETTER CHE;Lu;0;L;;;;;N;;;;0447; -0428;CYRILLIC CAPITAL LETTER SHA;Lu;0;L;;;;;N;;;;0448; -0429;CYRILLIC CAPITAL LETTER SHCHA;Lu;0;L;;;;;N;;;;0449; -042A;CYRILLIC CAPITAL LETTER HARD SIGN;Lu;0;L;;;;;N;;;;044A; -042B;CYRILLIC CAPITAL LETTER YERU;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER YERI;;;044B; -042C;CYRILLIC CAPITAL LETTER SOFT SIGN;Lu;0;L;;;;;N;;;;044C; -042D;CYRILLIC CAPITAL LETTER E;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER REVERSED E;;;044D; -042E;CYRILLIC CAPITAL LETTER YU;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER IU;;;044E; -042F;CYRILLIC CAPITAL LETTER YA;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER IA;;;044F; -0430;CYRILLIC SMALL LETTER A;Ll;0;L;;;;;N;;;0410;;0410 -0431;CYRILLIC SMALL LETTER BE;Ll;0;L;;;;;N;;;0411;;0411 -0432;CYRILLIC SMALL LETTER VE;Ll;0;L;;;;;N;;;0412;;0412 -0433;CYRILLIC SMALL LETTER GHE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER GE;;0413;;0413 -0434;CYRILLIC SMALL LETTER DE;Ll;0;L;;;;;N;;;0414;;0414 -0435;CYRILLIC SMALL LETTER IE;Ll;0;L;;;;;N;;;0415;;0415 -0436;CYRILLIC SMALL LETTER ZHE;Ll;0;L;;;;;N;;;0416;;0416 -0437;CYRILLIC SMALL LETTER ZE;Ll;0;L;;;;;N;;;0417;;0417 -0438;CYRILLIC SMALL LETTER I;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER II;;0418;;0418 -0439;CYRILLIC SMALL LETTER SHORT I;Ll;0;L;0438 0306;;;;N;CYRILLIC SMALL LETTER SHORT II;;0419;;0419 -043A;CYRILLIC SMALL LETTER KA;Ll;0;L;;;;;N;;;041A;;041A -043B;CYRILLIC SMALL LETTER EL;Ll;0;L;;;;;N;;;041B;;041B -043C;CYRILLIC SMALL LETTER EM;Ll;0;L;;;;;N;;;041C;;041C -043D;CYRILLIC SMALL LETTER EN;Ll;0;L;;;;;N;;;041D;;041D -043E;CYRILLIC SMALL LETTER O;Ll;0;L;;;;;N;;;041E;;041E -043F;CYRILLIC SMALL LETTER PE;Ll;0;L;;;;;N;;;041F;;041F -0440;CYRILLIC SMALL LETTER ER;Ll;0;L;;;;;N;;;0420;;0420 -0441;CYRILLIC SMALL LETTER ES;Ll;0;L;;;;;N;;;0421;;0421 -0442;CYRILLIC SMALL LETTER TE;Ll;0;L;;;;;N;;;0422;;0422 -0443;CYRILLIC SMALL LETTER U;Ll;0;L;;;;;N;;;0423;;0423 -0444;CYRILLIC SMALL LETTER EF;Ll;0;L;;;;;N;;;0424;;0424 -0445;CYRILLIC SMALL LETTER HA;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KHA;;0425;;0425 -0446;CYRILLIC SMALL LETTER TSE;Ll;0;L;;;;;N;;;0426;;0426 -0447;CYRILLIC SMALL LETTER CHE;Ll;0;L;;;;;N;;;0427;;0427 -0448;CYRILLIC SMALL LETTER SHA;Ll;0;L;;;;;N;;;0428;;0428 -0449;CYRILLIC SMALL LETTER SHCHA;Ll;0;L;;;;;N;;;0429;;0429 -044A;CYRILLIC SMALL LETTER HARD SIGN;Ll;0;L;;;;;N;;;042A;;042A -044B;CYRILLIC SMALL LETTER YERU;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER YERI;;042B;;042B -044C;CYRILLIC SMALL LETTER SOFT SIGN;Ll;0;L;;;;;N;;;042C;;042C -044D;CYRILLIC SMALL LETTER E;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER REVERSED E;;042D;;042D -044E;CYRILLIC SMALL LETTER YU;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER IU;;042E;;042E -044F;CYRILLIC SMALL LETTER YA;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER IA;;042F;;042F -0450;CYRILLIC SMALL LETTER IE WITH GRAVE;Ll;0;L;0435 0300;;;;N;;;0400;;0400 -0451;CYRILLIC SMALL LETTER IO;Ll;0;L;0435 0308;;;;N;;;0401;;0401 -0452;CYRILLIC SMALL LETTER DJE;Ll;0;L;;;;;N;;Serbocroatian;0402;;0402 -0453;CYRILLIC SMALL LETTER GJE;Ll;0;L;0433 0301;;;;N;;;0403;;0403 -0454;CYRILLIC SMALL LETTER UKRAINIAN IE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER E;;0404;;0404 -0455;CYRILLIC SMALL LETTER DZE;Ll;0;L;;;;;N;;;0405;;0405 -0456;CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER I;;0406;;0406 -0457;CYRILLIC SMALL LETTER YI;Ll;0;L;0456 0308;;;;N;;Ukrainian;0407;;0407 -0458;CYRILLIC SMALL LETTER JE;Ll;0;L;;;;;N;;;0408;;0408 -0459;CYRILLIC SMALL LETTER LJE;Ll;0;L;;;;;N;;;0409;;0409 -045A;CYRILLIC SMALL LETTER NJE;Ll;0;L;;;;;N;;;040A;;040A -045B;CYRILLIC SMALL LETTER TSHE;Ll;0;L;;;;;N;;Serbocroatian;040B;;040B -045C;CYRILLIC SMALL LETTER KJE;Ll;0;L;043A 0301;;;;N;;;040C;;040C -045D;CYRILLIC SMALL LETTER I WITH GRAVE;Ll;0;L;0438 0300;;;;N;;;040D;;040D -045E;CYRILLIC SMALL LETTER SHORT U;Ll;0;L;0443 0306;;;;N;;Byelorussian;040E;;040E -045F;CYRILLIC SMALL LETTER DZHE;Ll;0;L;;;;;N;;;040F;;040F -0460;CYRILLIC CAPITAL LETTER OMEGA;Lu;0;L;;;;;N;;;;0461; -0461;CYRILLIC SMALL LETTER OMEGA;Ll;0;L;;;;;N;;;0460;;0460 -0462;CYRILLIC CAPITAL LETTER YAT;Lu;0;L;;;;;N;;;;0463; -0463;CYRILLIC SMALL LETTER YAT;Ll;0;L;;;;;N;;;0462;;0462 -0464;CYRILLIC CAPITAL LETTER IOTIFIED E;Lu;0;L;;;;;N;;;;0465; -0465;CYRILLIC SMALL LETTER IOTIFIED E;Ll;0;L;;;;;N;;;0464;;0464 -0466;CYRILLIC CAPITAL LETTER LITTLE YUS;Lu;0;L;;;;;N;;;;0467; -0467;CYRILLIC SMALL LETTER LITTLE YUS;Ll;0;L;;;;;N;;;0466;;0466 -0468;CYRILLIC CAPITAL LETTER IOTIFIED LITTLE YUS;Lu;0;L;;;;;N;;;;0469; -0469;CYRILLIC SMALL LETTER IOTIFIED LITTLE YUS;Ll;0;L;;;;;N;;;0468;;0468 -046A;CYRILLIC CAPITAL LETTER BIG YUS;Lu;0;L;;;;;N;;;;046B; -046B;CYRILLIC SMALL LETTER BIG YUS;Ll;0;L;;;;;N;;;046A;;046A -046C;CYRILLIC CAPITAL LETTER IOTIFIED BIG YUS;Lu;0;L;;;;;N;;;;046D; -046D;CYRILLIC SMALL LETTER IOTIFIED BIG YUS;Ll;0;L;;;;;N;;;046C;;046C -046E;CYRILLIC CAPITAL LETTER KSI;Lu;0;L;;;;;N;;;;046F; -046F;CYRILLIC SMALL LETTER KSI;Ll;0;L;;;;;N;;;046E;;046E -0470;CYRILLIC CAPITAL LETTER PSI;Lu;0;L;;;;;N;;;;0471; -0471;CYRILLIC SMALL LETTER PSI;Ll;0;L;;;;;N;;;0470;;0470 -0472;CYRILLIC CAPITAL LETTER FITA;Lu;0;L;;;;;N;;;;0473; -0473;CYRILLIC SMALL LETTER FITA;Ll;0;L;;;;;N;;;0472;;0472 -0474;CYRILLIC CAPITAL LETTER IZHITSA;Lu;0;L;;;;;N;;;;0475; -0475;CYRILLIC SMALL LETTER IZHITSA;Ll;0;L;;;;;N;;;0474;;0474 -0476;CYRILLIC CAPITAL LETTER IZHITSA WITH DOUBLE GRAVE ACCENT;Lu;0;L;0474 030F;;;;N;CYRILLIC CAPITAL LETTER IZHITSA DOUBLE GRAVE;;;0477; -0477;CYRILLIC SMALL LETTER IZHITSA WITH DOUBLE GRAVE ACCENT;Ll;0;L;0475 030F;;;;N;CYRILLIC SMALL LETTER IZHITSA DOUBLE GRAVE;;0476;;0476 -0478;CYRILLIC CAPITAL LETTER UK;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER UK DIGRAPH;;;0479; -0479;CYRILLIC SMALL LETTER UK;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER UK DIGRAPH;;0478;;0478 -047A;CYRILLIC CAPITAL LETTER ROUND OMEGA;Lu;0;L;;;;;N;;;;047B; -047B;CYRILLIC SMALL LETTER ROUND OMEGA;Ll;0;L;;;;;N;;;047A;;047A -047C;CYRILLIC CAPITAL LETTER OMEGA WITH TITLO;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER OMEGA TITLO;;;047D; -047D;CYRILLIC SMALL LETTER OMEGA WITH TITLO;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER OMEGA TITLO;;047C;;047C -047E;CYRILLIC CAPITAL LETTER OT;Lu;0;L;;;;;N;;;;047F; -047F;CYRILLIC SMALL LETTER OT;Ll;0;L;;;;;N;;;047E;;047E -0480;CYRILLIC CAPITAL LETTER KOPPA;Lu;0;L;;;;;N;;;;0481; -0481;CYRILLIC SMALL LETTER KOPPA;Ll;0;L;;;;;N;;;0480;;0480 -0482;CYRILLIC THOUSANDS SIGN;So;0;L;;;;;N;;;;; -0483;COMBINING CYRILLIC TITLO;Mn;230;NSM;;;;;N;CYRILLIC NON-SPACING TITLO;;;; -0484;COMBINING CYRILLIC PALATALIZATION;Mn;230;NSM;;;;;N;CYRILLIC NON-SPACING PALATALIZATION;;;; -0485;COMBINING CYRILLIC DASIA PNEUMATA;Mn;230;NSM;;;;;N;CYRILLIC NON-SPACING DASIA PNEUMATA;;;; -0486;COMBINING CYRILLIC PSILI PNEUMATA;Mn;230;NSM;;;;;N;CYRILLIC NON-SPACING PSILI PNEUMATA;;;; -0487;COMBINING CYRILLIC POKRYTIE;Mn;230;NSM;;;;;N;;;;; -0488;COMBINING CYRILLIC HUNDRED THOUSANDS SIGN;Me;0;NSM;;;;;N;;;;; -0489;COMBINING CYRILLIC MILLIONS SIGN;Me;0;NSM;;;;;N;;;;; -048A;CYRILLIC CAPITAL LETTER SHORT I WITH TAIL;Lu;0;L;;;;;N;;;;048B; -048B;CYRILLIC SMALL LETTER SHORT I WITH TAIL;Ll;0;L;;;;;N;;;048A;;048A -048C;CYRILLIC CAPITAL LETTER SEMISOFT SIGN;Lu;0;L;;;;;N;;;;048D; -048D;CYRILLIC SMALL LETTER SEMISOFT SIGN;Ll;0;L;;;;;N;;;048C;;048C -048E;CYRILLIC CAPITAL LETTER ER WITH TICK;Lu;0;L;;;;;N;;;;048F; -048F;CYRILLIC SMALL LETTER ER WITH TICK;Ll;0;L;;;;;N;;;048E;;048E -0490;CYRILLIC CAPITAL LETTER GHE WITH UPTURN;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER GE WITH UPTURN;;;0491; -0491;CYRILLIC SMALL LETTER GHE WITH UPTURN;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER GE WITH UPTURN;;0490;;0490 -0492;CYRILLIC CAPITAL LETTER GHE WITH STROKE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER GE BAR;;;0493; -0493;CYRILLIC SMALL LETTER GHE WITH STROKE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER GE BAR;;0492;;0492 -0494;CYRILLIC CAPITAL LETTER GHE WITH MIDDLE HOOK;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER GE HOOK;;;0495; -0495;CYRILLIC SMALL LETTER GHE WITH MIDDLE HOOK;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER GE HOOK;;0494;;0494 -0496;CYRILLIC CAPITAL LETTER ZHE WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER ZHE WITH RIGHT DESCENDER;;;0497; -0497;CYRILLIC SMALL LETTER ZHE WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER ZHE WITH RIGHT DESCENDER;;0496;;0496 -0498;CYRILLIC CAPITAL LETTER ZE WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER ZE CEDILLA;;;0499; -0499;CYRILLIC SMALL LETTER ZE WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER ZE CEDILLA;;0498;;0498 -049A;CYRILLIC CAPITAL LETTER KA WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KA WITH RIGHT DESCENDER;;;049B; -049B;CYRILLIC SMALL LETTER KA WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KA WITH RIGHT DESCENDER;;049A;;049A -049C;CYRILLIC CAPITAL LETTER KA WITH VERTICAL STROKE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KA VERTICAL BAR;;;049D; -049D;CYRILLIC SMALL LETTER KA WITH VERTICAL STROKE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KA VERTICAL BAR;;049C;;049C -049E;CYRILLIC CAPITAL LETTER KA WITH STROKE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KA BAR;;;049F; -049F;CYRILLIC SMALL LETTER KA WITH STROKE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KA BAR;;049E;;049E -04A0;CYRILLIC CAPITAL LETTER BASHKIR KA;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER REVERSED GE KA;;;04A1; -04A1;CYRILLIC SMALL LETTER BASHKIR KA;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER REVERSED GE KA;;04A0;;04A0 -04A2;CYRILLIC CAPITAL LETTER EN WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER EN WITH RIGHT DESCENDER;;;04A3; -04A3;CYRILLIC SMALL LETTER EN WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER EN WITH RIGHT DESCENDER;;04A2;;04A2 -04A4;CYRILLIC CAPITAL LIGATURE EN GHE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER EN GE;;;04A5; -04A5;CYRILLIC SMALL LIGATURE EN GHE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER EN GE;;04A4;;04A4 -04A6;CYRILLIC CAPITAL LETTER PE WITH MIDDLE HOOK;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER PE HOOK;Abkhasian;;04A7; -04A7;CYRILLIC SMALL LETTER PE WITH MIDDLE HOOK;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER PE HOOK;Abkhasian;04A6;;04A6 -04A8;CYRILLIC CAPITAL LETTER ABKHASIAN HA;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER O HOOK;;;04A9; -04A9;CYRILLIC SMALL LETTER ABKHASIAN HA;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER O HOOK;;04A8;;04A8 -04AA;CYRILLIC CAPITAL LETTER ES WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER ES CEDILLA;;;04AB; -04AB;CYRILLIC SMALL LETTER ES WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER ES CEDILLA;;04AA;;04AA -04AC;CYRILLIC CAPITAL LETTER TE WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER TE WITH RIGHT DESCENDER;;;04AD; -04AD;CYRILLIC SMALL LETTER TE WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER TE WITH RIGHT DESCENDER;;04AC;;04AC -04AE;CYRILLIC CAPITAL LETTER STRAIGHT U;Lu;0;L;;;;;N;;;;04AF; -04AF;CYRILLIC SMALL LETTER STRAIGHT U;Ll;0;L;;;;;N;;;04AE;;04AE -04B0;CYRILLIC CAPITAL LETTER STRAIGHT U WITH STROKE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER STRAIGHT U BAR;;;04B1; -04B1;CYRILLIC SMALL LETTER STRAIGHT U WITH STROKE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER STRAIGHT U BAR;;04B0;;04B0 -04B2;CYRILLIC CAPITAL LETTER HA WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KHA WITH RIGHT DESCENDER;;;04B3; -04B3;CYRILLIC SMALL LETTER HA WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KHA WITH RIGHT DESCENDER;;04B2;;04B2 -04B4;CYRILLIC CAPITAL LIGATURE TE TSE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER TE TSE;Abkhasian;;04B5; -04B5;CYRILLIC SMALL LIGATURE TE TSE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER TE TSE;Abkhasian;04B4;;04B4 -04B6;CYRILLIC CAPITAL LETTER CHE WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER CHE WITH RIGHT DESCENDER;;;04B7; -04B7;CYRILLIC SMALL LETTER CHE WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER CHE WITH RIGHT DESCENDER;;04B6;;04B6 -04B8;CYRILLIC CAPITAL LETTER CHE WITH VERTICAL STROKE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER CHE VERTICAL BAR;;;04B9; -04B9;CYRILLIC SMALL LETTER CHE WITH VERTICAL STROKE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER CHE VERTICAL BAR;;04B8;;04B8 -04BA;CYRILLIC CAPITAL LETTER SHHA;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER H;;;04BB; -04BB;CYRILLIC SMALL LETTER SHHA;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER H;;04BA;;04BA -04BC;CYRILLIC CAPITAL LETTER ABKHASIAN CHE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER IE HOOK;;;04BD; -04BD;CYRILLIC SMALL LETTER ABKHASIAN CHE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER IE HOOK;;04BC;;04BC -04BE;CYRILLIC CAPITAL LETTER ABKHASIAN CHE WITH DESCENDER;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER IE HOOK OGONEK;;;04BF; -04BF;CYRILLIC SMALL LETTER ABKHASIAN CHE WITH DESCENDER;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER IE HOOK OGONEK;;04BE;;04BE -04C0;CYRILLIC LETTER PALOCHKA;Lu;0;L;;;;;N;CYRILLIC LETTER I;;;04CF; -04C1;CYRILLIC CAPITAL LETTER ZHE WITH BREVE;Lu;0;L;0416 0306;;;;N;CYRILLIC CAPITAL LETTER SHORT ZHE;;;04C2; -04C2;CYRILLIC SMALL LETTER ZHE WITH BREVE;Ll;0;L;0436 0306;;;;N;CYRILLIC SMALL LETTER SHORT ZHE;;04C1;;04C1 -04C3;CYRILLIC CAPITAL LETTER KA WITH HOOK;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER KA HOOK;;;04C4; -04C4;CYRILLIC SMALL LETTER KA WITH HOOK;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER KA HOOK;;04C3;;04C3 -04C5;CYRILLIC CAPITAL LETTER EL WITH TAIL;Lu;0;L;;;;;N;;;;04C6; -04C6;CYRILLIC SMALL LETTER EL WITH TAIL;Ll;0;L;;;;;N;;;04C5;;04C5 -04C7;CYRILLIC CAPITAL LETTER EN WITH HOOK;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER EN HOOK;;;04C8; -04C8;CYRILLIC SMALL LETTER EN WITH HOOK;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER EN HOOK;;04C7;;04C7 -04C9;CYRILLIC CAPITAL LETTER EN WITH TAIL;Lu;0;L;;;;;N;;;;04CA; -04CA;CYRILLIC SMALL LETTER EN WITH TAIL;Ll;0;L;;;;;N;;;04C9;;04C9 -04CB;CYRILLIC CAPITAL LETTER KHAKASSIAN CHE;Lu;0;L;;;;;N;CYRILLIC CAPITAL LETTER CHE WITH LEFT DESCENDER;;;04CC; -04CC;CYRILLIC SMALL LETTER KHAKASSIAN CHE;Ll;0;L;;;;;N;CYRILLIC SMALL LETTER CHE WITH LEFT DESCENDER;;04CB;;04CB -04CD;CYRILLIC CAPITAL LETTER EM WITH TAIL;Lu;0;L;;;;;N;;;;04CE; -04CE;CYRILLIC SMALL LETTER EM WITH TAIL;Ll;0;L;;;;;N;;;04CD;;04CD -04CF;CYRILLIC SMALL LETTER PALOCHKA;Ll;0;L;;;;;N;;;04C0;;04C0 -04D0;CYRILLIC CAPITAL LETTER A WITH BREVE;Lu;0;L;0410 0306;;;;N;;;;04D1; -04D1;CYRILLIC SMALL LETTER A WITH BREVE;Ll;0;L;0430 0306;;;;N;;;04D0;;04D0 -04D2;CYRILLIC CAPITAL LETTER A WITH DIAERESIS;Lu;0;L;0410 0308;;;;N;;;;04D3; -04D3;CYRILLIC SMALL LETTER A WITH DIAERESIS;Ll;0;L;0430 0308;;;;N;;;04D2;;04D2 -04D4;CYRILLIC CAPITAL LIGATURE A IE;Lu;0;L;;;;;N;;;;04D5; -04D5;CYRILLIC SMALL LIGATURE A IE;Ll;0;L;;;;;N;;;04D4;;04D4 -04D6;CYRILLIC CAPITAL LETTER IE WITH BREVE;Lu;0;L;0415 0306;;;;N;;;;04D7; -04D7;CYRILLIC SMALL LETTER IE WITH BREVE;Ll;0;L;0435 0306;;;;N;;;04D6;;04D6 -04D8;CYRILLIC CAPITAL LETTER SCHWA;Lu;0;L;;;;;N;;;;04D9; -04D9;CYRILLIC SMALL LETTER SCHWA;Ll;0;L;;;;;N;;;04D8;;04D8 -04DA;CYRILLIC CAPITAL LETTER SCHWA WITH DIAERESIS;Lu;0;L;04D8 0308;;;;N;;;;04DB; -04DB;CYRILLIC SMALL LETTER SCHWA WITH DIAERESIS;Ll;0;L;04D9 0308;;;;N;;;04DA;;04DA -04DC;CYRILLIC CAPITAL LETTER ZHE WITH DIAERESIS;Lu;0;L;0416 0308;;;;N;;;;04DD; -04DD;CYRILLIC SMALL LETTER ZHE WITH DIAERESIS;Ll;0;L;0436 0308;;;;N;;;04DC;;04DC -04DE;CYRILLIC CAPITAL LETTER ZE WITH DIAERESIS;Lu;0;L;0417 0308;;;;N;;;;04DF; -04DF;CYRILLIC SMALL LETTER ZE WITH DIAERESIS;Ll;0;L;0437 0308;;;;N;;;04DE;;04DE -04E0;CYRILLIC CAPITAL LETTER ABKHASIAN DZE;Lu;0;L;;;;;N;;;;04E1; -04E1;CYRILLIC SMALL LETTER ABKHASIAN DZE;Ll;0;L;;;;;N;;;04E0;;04E0 -04E2;CYRILLIC CAPITAL LETTER I WITH MACRON;Lu;0;L;0418 0304;;;;N;;;;04E3; -04E3;CYRILLIC SMALL LETTER I WITH MACRON;Ll;0;L;0438 0304;;;;N;;;04E2;;04E2 -04E4;CYRILLIC CAPITAL LETTER I WITH DIAERESIS;Lu;0;L;0418 0308;;;;N;;;;04E5; -04E5;CYRILLIC SMALL LETTER I WITH DIAERESIS;Ll;0;L;0438 0308;;;;N;;;04E4;;04E4 -04E6;CYRILLIC CAPITAL LETTER O WITH DIAERESIS;Lu;0;L;041E 0308;;;;N;;;;04E7; -04E7;CYRILLIC SMALL LETTER O WITH DIAERESIS;Ll;0;L;043E 0308;;;;N;;;04E6;;04E6 -04E8;CYRILLIC CAPITAL LETTER BARRED O;Lu;0;L;;;;;N;;;;04E9; -04E9;CYRILLIC SMALL LETTER BARRED O;Ll;0;L;;;;;N;;;04E8;;04E8 -04EA;CYRILLIC CAPITAL LETTER BARRED O WITH DIAERESIS;Lu;0;L;04E8 0308;;;;N;;;;04EB; -04EB;CYRILLIC SMALL LETTER BARRED O WITH DIAERESIS;Ll;0;L;04E9 0308;;;;N;;;04EA;;04EA -04EC;CYRILLIC CAPITAL LETTER E WITH DIAERESIS;Lu;0;L;042D 0308;;;;N;;;;04ED; -04ED;CYRILLIC SMALL LETTER E WITH DIAERESIS;Ll;0;L;044D 0308;;;;N;;;04EC;;04EC -04EE;CYRILLIC CAPITAL LETTER U WITH MACRON;Lu;0;L;0423 0304;;;;N;;;;04EF; -04EF;CYRILLIC SMALL LETTER U WITH MACRON;Ll;0;L;0443 0304;;;;N;;;04EE;;04EE -04F0;CYRILLIC CAPITAL LETTER U WITH DIAERESIS;Lu;0;L;0423 0308;;;;N;;;;04F1; -04F1;CYRILLIC SMALL LETTER U WITH DIAERESIS;Ll;0;L;0443 0308;;;;N;;;04F0;;04F0 -04F2;CYRILLIC CAPITAL LETTER U WITH DOUBLE ACUTE;Lu;0;L;0423 030B;;;;N;;;;04F3; -04F3;CYRILLIC SMALL LETTER U WITH DOUBLE ACUTE;Ll;0;L;0443 030B;;;;N;;;04F2;;04F2 -04F4;CYRILLIC CAPITAL LETTER CHE WITH DIAERESIS;Lu;0;L;0427 0308;;;;N;;;;04F5; -04F5;CYRILLIC SMALL LETTER CHE WITH DIAERESIS;Ll;0;L;0447 0308;;;;N;;;04F4;;04F4 -04F6;CYRILLIC CAPITAL LETTER GHE WITH DESCENDER;Lu;0;L;;;;;N;;;;04F7; -04F7;CYRILLIC SMALL LETTER GHE WITH DESCENDER;Ll;0;L;;;;;N;;;04F6;;04F6 -04F8;CYRILLIC CAPITAL LETTER YERU WITH DIAERESIS;Lu;0;L;042B 0308;;;;N;;;;04F9; -04F9;CYRILLIC SMALL LETTER YERU WITH DIAERESIS;Ll;0;L;044B 0308;;;;N;;;04F8;;04F8 -04FA;CYRILLIC CAPITAL LETTER GHE WITH STROKE AND HOOK;Lu;0;L;;;;;N;;;;04FB; -04FB;CYRILLIC SMALL LETTER GHE WITH STROKE AND HOOK;Ll;0;L;;;;;N;;;04FA;;04FA -04FC;CYRILLIC CAPITAL LETTER HA WITH HOOK;Lu;0;L;;;;;N;;;;04FD; -04FD;CYRILLIC SMALL LETTER HA WITH HOOK;Ll;0;L;;;;;N;;;04FC;;04FC -04FE;CYRILLIC CAPITAL LETTER HA WITH STROKE;Lu;0;L;;;;;N;;;;04FF; -04FF;CYRILLIC SMALL LETTER HA WITH STROKE;Ll;0;L;;;;;N;;;04FE;;04FE -0500;CYRILLIC CAPITAL LETTER KOMI DE;Lu;0;L;;;;;N;;;;0501; -0501;CYRILLIC SMALL LETTER KOMI DE;Ll;0;L;;;;;N;;;0500;;0500 -0502;CYRILLIC CAPITAL LETTER KOMI DJE;Lu;0;L;;;;;N;;;;0503; -0503;CYRILLIC SMALL LETTER KOMI DJE;Ll;0;L;;;;;N;;;0502;;0502 -0504;CYRILLIC CAPITAL LETTER KOMI ZJE;Lu;0;L;;;;;N;;;;0505; -0505;CYRILLIC SMALL LETTER KOMI ZJE;Ll;0;L;;;;;N;;;0504;;0504 -0506;CYRILLIC CAPITAL LETTER KOMI DZJE;Lu;0;L;;;;;N;;;;0507; -0507;CYRILLIC SMALL LETTER KOMI DZJE;Ll;0;L;;;;;N;;;0506;;0506 -0508;CYRILLIC CAPITAL LETTER KOMI LJE;Lu;0;L;;;;;N;;;;0509; -0509;CYRILLIC SMALL LETTER KOMI LJE;Ll;0;L;;;;;N;;;0508;;0508 -050A;CYRILLIC CAPITAL LETTER KOMI NJE;Lu;0;L;;;;;N;;;;050B; -050B;CYRILLIC SMALL LETTER KOMI NJE;Ll;0;L;;;;;N;;;050A;;050A -050C;CYRILLIC CAPITAL LETTER KOMI SJE;Lu;0;L;;;;;N;;;;050D; -050D;CYRILLIC SMALL LETTER KOMI SJE;Ll;0;L;;;;;N;;;050C;;050C -050E;CYRILLIC CAPITAL LETTER KOMI TJE;Lu;0;L;;;;;N;;;;050F; -050F;CYRILLIC SMALL LETTER KOMI TJE;Ll;0;L;;;;;N;;;050E;;050E -0510;CYRILLIC CAPITAL LETTER REVERSED ZE;Lu;0;L;;;;;N;;;;0511; -0511;CYRILLIC SMALL LETTER REVERSED ZE;Ll;0;L;;;;;N;;;0510;;0510 -0512;CYRILLIC CAPITAL LETTER EL WITH HOOK;Lu;0;L;;;;;N;;;;0513; -0513;CYRILLIC SMALL LETTER EL WITH HOOK;Ll;0;L;;;;;N;;;0512;;0512 -0514;CYRILLIC CAPITAL LETTER LHA;Lu;0;L;;;;;N;;;;0515; -0515;CYRILLIC SMALL LETTER LHA;Ll;0;L;;;;;N;;;0514;;0514 -0516;CYRILLIC CAPITAL LETTER RHA;Lu;0;L;;;;;N;;;;0517; -0517;CYRILLIC SMALL LETTER RHA;Ll;0;L;;;;;N;;;0516;;0516 -0518;CYRILLIC CAPITAL LETTER YAE;Lu;0;L;;;;;N;;;;0519; -0519;CYRILLIC SMALL LETTER YAE;Ll;0;L;;;;;N;;;0518;;0518 -051A;CYRILLIC CAPITAL LETTER QA;Lu;0;L;;;;;N;;;;051B; -051B;CYRILLIC SMALL LETTER QA;Ll;0;L;;;;;N;;;051A;;051A -051C;CYRILLIC CAPITAL LETTER WE;Lu;0;L;;;;;N;;;;051D; -051D;CYRILLIC SMALL LETTER WE;Ll;0;L;;;;;N;;;051C;;051C -051E;CYRILLIC CAPITAL LETTER ALEUT KA;Lu;0;L;;;;;N;;;;051F; -051F;CYRILLIC SMALL LETTER ALEUT KA;Ll;0;L;;;;;N;;;051E;;051E -0520;CYRILLIC CAPITAL LETTER EL WITH MIDDLE HOOK;Lu;0;L;;;;;N;;;;0521; -0521;CYRILLIC SMALL LETTER EL WITH MIDDLE HOOK;Ll;0;L;;;;;N;;;0520;;0520 -0522;CYRILLIC CAPITAL LETTER EN WITH MIDDLE HOOK;Lu;0;L;;;;;N;;;;0523; -0523;CYRILLIC SMALL LETTER EN WITH MIDDLE HOOK;Ll;0;L;;;;;N;;;0522;;0522 -0531;ARMENIAN CAPITAL LETTER AYB;Lu;0;L;;;;;N;;;;0561; -0532;ARMENIAN CAPITAL LETTER BEN;Lu;0;L;;;;;N;;;;0562; -0533;ARMENIAN CAPITAL LETTER GIM;Lu;0;L;;;;;N;;;;0563; -0534;ARMENIAN CAPITAL LETTER DA;Lu;0;L;;;;;N;;;;0564; -0535;ARMENIAN CAPITAL LETTER ECH;Lu;0;L;;;;;N;;;;0565; -0536;ARMENIAN CAPITAL LETTER ZA;Lu;0;L;;;;;N;;;;0566; -0537;ARMENIAN CAPITAL LETTER EH;Lu;0;L;;;;;N;;;;0567; -0538;ARMENIAN CAPITAL LETTER ET;Lu;0;L;;;;;N;;;;0568; -0539;ARMENIAN CAPITAL LETTER TO;Lu;0;L;;;;;N;;;;0569; -053A;ARMENIAN CAPITAL LETTER ZHE;Lu;0;L;;;;;N;;;;056A; -053B;ARMENIAN CAPITAL LETTER INI;Lu;0;L;;;;;N;;;;056B; -053C;ARMENIAN CAPITAL LETTER LIWN;Lu;0;L;;;;;N;;;;056C; -053D;ARMENIAN CAPITAL LETTER XEH;Lu;0;L;;;;;N;;;;056D; -053E;ARMENIAN CAPITAL LETTER CA;Lu;0;L;;;;;N;;;;056E; -053F;ARMENIAN CAPITAL LETTER KEN;Lu;0;L;;;;;N;;;;056F; -0540;ARMENIAN CAPITAL LETTER HO;Lu;0;L;;;;;N;;;;0570; -0541;ARMENIAN CAPITAL LETTER JA;Lu;0;L;;;;;N;;;;0571; -0542;ARMENIAN CAPITAL LETTER GHAD;Lu;0;L;;;;;N;ARMENIAN CAPITAL LETTER LAD;;;0572; -0543;ARMENIAN CAPITAL LETTER CHEH;Lu;0;L;;;;;N;;;;0573; -0544;ARMENIAN CAPITAL LETTER MEN;Lu;0;L;;;;;N;;;;0574; -0545;ARMENIAN CAPITAL LETTER YI;Lu;0;L;;;;;N;;;;0575; -0546;ARMENIAN CAPITAL LETTER NOW;Lu;0;L;;;;;N;;;;0576; -0547;ARMENIAN CAPITAL LETTER SHA;Lu;0;L;;;;;N;;;;0577; -0548;ARMENIAN CAPITAL LETTER VO;Lu;0;L;;;;;N;;;;0578; -0549;ARMENIAN CAPITAL LETTER CHA;Lu;0;L;;;;;N;;;;0579; -054A;ARMENIAN CAPITAL LETTER PEH;Lu;0;L;;;;;N;;;;057A; -054B;ARMENIAN CAPITAL LETTER JHEH;Lu;0;L;;;;;N;;;;057B; -054C;ARMENIAN CAPITAL LETTER RA;Lu;0;L;;;;;N;;;;057C; -054D;ARMENIAN CAPITAL LETTER SEH;Lu;0;L;;;;;N;;;;057D; -054E;ARMENIAN CAPITAL LETTER VEW;Lu;0;L;;;;;N;;;;057E; -054F;ARMENIAN CAPITAL LETTER TIWN;Lu;0;L;;;;;N;;;;057F; -0550;ARMENIAN CAPITAL LETTER REH;Lu;0;L;;;;;N;;;;0580; -0551;ARMENIAN CAPITAL LETTER CO;Lu;0;L;;;;;N;;;;0581; -0552;ARMENIAN CAPITAL LETTER YIWN;Lu;0;L;;;;;N;;;;0582; -0553;ARMENIAN CAPITAL LETTER PIWR;Lu;0;L;;;;;N;;;;0583; -0554;ARMENIAN CAPITAL LETTER KEH;Lu;0;L;;;;;N;;;;0584; -0555;ARMENIAN CAPITAL LETTER OH;Lu;0;L;;;;;N;;;;0585; -0556;ARMENIAN CAPITAL LETTER FEH;Lu;0;L;;;;;N;;;;0586; -0559;ARMENIAN MODIFIER LETTER LEFT HALF RING;Lm;0;L;;;;;N;;;;; -055A;ARMENIAN APOSTROPHE;Po;0;L;;;;;N;ARMENIAN MODIFIER LETTER RIGHT HALF RING;;;; -055B;ARMENIAN EMPHASIS MARK;Po;0;L;;;;;N;;;;; -055C;ARMENIAN EXCLAMATION MARK;Po;0;L;;;;;N;;;;; -055D;ARMENIAN COMMA;Po;0;L;;;;;N;;;;; -055E;ARMENIAN QUESTION MARK;Po;0;L;;;;;N;;;;; -055F;ARMENIAN ABBREVIATION MARK;Po;0;L;;;;;N;;;;; -0561;ARMENIAN SMALL LETTER AYB;Ll;0;L;;;;;N;;;0531;;0531 -0562;ARMENIAN SMALL LETTER BEN;Ll;0;L;;;;;N;;;0532;;0532 -0563;ARMENIAN SMALL LETTER GIM;Ll;0;L;;;;;N;;;0533;;0533 -0564;ARMENIAN SMALL LETTER DA;Ll;0;L;;;;;N;;;0534;;0534 -0565;ARMENIAN SMALL LETTER ECH;Ll;0;L;;;;;N;;;0535;;0535 -0566;ARMENIAN SMALL LETTER ZA;Ll;0;L;;;;;N;;;0536;;0536 -0567;ARMENIAN SMALL LETTER EH;Ll;0;L;;;;;N;;;0537;;0537 -0568;ARMENIAN SMALL LETTER ET;Ll;0;L;;;;;N;;;0538;;0538 -0569;ARMENIAN SMALL LETTER TO;Ll;0;L;;;;;N;;;0539;;0539 -056A;ARMENIAN SMALL LETTER ZHE;Ll;0;L;;;;;N;;;053A;;053A -056B;ARMENIAN SMALL LETTER INI;Ll;0;L;;;;;N;;;053B;;053B -056C;ARMENIAN SMALL LETTER LIWN;Ll;0;L;;;;;N;;;053C;;053C -056D;ARMENIAN SMALL LETTER XEH;Ll;0;L;;;;;N;;;053D;;053D -056E;ARMENIAN SMALL LETTER CA;Ll;0;L;;;;;N;;;053E;;053E -056F;ARMENIAN SMALL LETTER KEN;Ll;0;L;;;;;N;;;053F;;053F -0570;ARMENIAN SMALL LETTER HO;Ll;0;L;;;;;N;;;0540;;0540 -0571;ARMENIAN SMALL LETTER JA;Ll;0;L;;;;;N;;;0541;;0541 -0572;ARMENIAN SMALL LETTER GHAD;Ll;0;L;;;;;N;ARMENIAN SMALL LETTER LAD;;0542;;0542 -0573;ARMENIAN SMALL LETTER CHEH;Ll;0;L;;;;;N;;;0543;;0543 -0574;ARMENIAN SMALL LETTER MEN;Ll;0;L;;;;;N;;;0544;;0544 -0575;ARMENIAN SMALL LETTER YI;Ll;0;L;;;;;N;;;0545;;0545 -0576;ARMENIAN SMALL LETTER NOW;Ll;0;L;;;;;N;;;0546;;0546 -0577;ARMENIAN SMALL LETTER SHA;Ll;0;L;;;;;N;;;0547;;0547 -0578;ARMENIAN SMALL LETTER VO;Ll;0;L;;;;;N;;;0548;;0548 -0579;ARMENIAN SMALL LETTER CHA;Ll;0;L;;;;;N;;;0549;;0549 -057A;ARMENIAN SMALL LETTER PEH;Ll;0;L;;;;;N;;;054A;;054A -057B;ARMENIAN SMALL LETTER JHEH;Ll;0;L;;;;;N;;;054B;;054B -057C;ARMENIAN SMALL LETTER RA;Ll;0;L;;;;;N;;;054C;;054C -057D;ARMENIAN SMALL LETTER SEH;Ll;0;L;;;;;N;;;054D;;054D -057E;ARMENIAN SMALL LETTER VEW;Ll;0;L;;;;;N;;;054E;;054E -057F;ARMENIAN SMALL LETTER TIWN;Ll;0;L;;;;;N;;;054F;;054F -0580;ARMENIAN SMALL LETTER REH;Ll;0;L;;;;;N;;;0550;;0550 -0581;ARMENIAN SMALL LETTER CO;Ll;0;L;;;;;N;;;0551;;0551 -0582;ARMENIAN SMALL LETTER YIWN;Ll;0;L;;;;;N;;;0552;;0552 -0583;ARMENIAN SMALL LETTER PIWR;Ll;0;L;;;;;N;;;0553;;0553 -0584;ARMENIAN SMALL LETTER KEH;Ll;0;L;;;;;N;;;0554;;0554 -0585;ARMENIAN SMALL LETTER OH;Ll;0;L;;;;;N;;;0555;;0555 -0586;ARMENIAN SMALL LETTER FEH;Ll;0;L;;;;;N;;;0556;;0556 -0587;ARMENIAN SMALL LIGATURE ECH YIWN;Ll;0;L; 0565 0582;;;;N;;;;; -0589;ARMENIAN FULL STOP;Po;0;L;;;;;N;ARMENIAN PERIOD;;;; -058A;ARMENIAN HYPHEN;Pd;0;ON;;;;;N;;;;; -0591;HEBREW ACCENT ETNAHTA;Mn;220;NSM;;;;;N;;;;; -0592;HEBREW ACCENT SEGOL;Mn;230;NSM;;;;;N;;;;; -0593;HEBREW ACCENT SHALSHELET;Mn;230;NSM;;;;;N;;;;; -0594;HEBREW ACCENT ZAQEF QATAN;Mn;230;NSM;;;;;N;;;;; -0595;HEBREW ACCENT ZAQEF GADOL;Mn;230;NSM;;;;;N;;;;; -0596;HEBREW ACCENT TIPEHA;Mn;220;NSM;;;;;N;;*;;; -0597;HEBREW ACCENT REVIA;Mn;230;NSM;;;;;N;;;;; -0598;HEBREW ACCENT ZARQA;Mn;230;NSM;;;;;N;;*;;; -0599;HEBREW ACCENT PASHTA;Mn;230;NSM;;;;;N;;;;; -059A;HEBREW ACCENT YETIV;Mn;222;NSM;;;;;N;;;;; -059B;HEBREW ACCENT TEVIR;Mn;220;NSM;;;;;N;;;;; -059C;HEBREW ACCENT GERESH;Mn;230;NSM;;;;;N;;;;; -059D;HEBREW ACCENT GERESH MUQDAM;Mn;230;NSM;;;;;N;;;;; -059E;HEBREW ACCENT GERSHAYIM;Mn;230;NSM;;;;;N;;;;; -059F;HEBREW ACCENT QARNEY PARA;Mn;230;NSM;;;;;N;;;;; -05A0;HEBREW ACCENT TELISHA GEDOLA;Mn;230;NSM;;;;;N;;;;; -05A1;HEBREW ACCENT PAZER;Mn;230;NSM;;;;;N;;;;; -05A2;HEBREW ACCENT ATNAH HAFUKH;Mn;220;NSM;;;;;N;;;;; -05A3;HEBREW ACCENT MUNAH;Mn;220;NSM;;;;;N;;;;; -05A4;HEBREW ACCENT MAHAPAKH;Mn;220;NSM;;;;;N;;;;; -05A5;HEBREW ACCENT MERKHA;Mn;220;NSM;;;;;N;;*;;; -05A6;HEBREW ACCENT MERKHA KEFULA;Mn;220;NSM;;;;;N;;;;; -05A7;HEBREW ACCENT DARGA;Mn;220;NSM;;;;;N;;;;; -05A8;HEBREW ACCENT QADMA;Mn;230;NSM;;;;;N;;*;;; -05A9;HEBREW ACCENT TELISHA QETANA;Mn;230;NSM;;;;;N;;;;; -05AA;HEBREW ACCENT YERAH BEN YOMO;Mn;220;NSM;;;;;N;;*;;; -05AB;HEBREW ACCENT OLE;Mn;230;NSM;;;;;N;;;;; -05AC;HEBREW ACCENT ILUY;Mn;230;NSM;;;;;N;;;;; -05AD;HEBREW ACCENT DEHI;Mn;222;NSM;;;;;N;;;;; -05AE;HEBREW ACCENT ZINOR;Mn;228;NSM;;;;;N;;;;; -05AF;HEBREW MARK MASORA CIRCLE;Mn;230;NSM;;;;;N;;;;; -05B0;HEBREW POINT SHEVA;Mn;10;NSM;;;;;N;;;;; -05B1;HEBREW POINT HATAF SEGOL;Mn;11;NSM;;;;;N;;;;; -05B2;HEBREW POINT HATAF PATAH;Mn;12;NSM;;;;;N;;;;; -05B3;HEBREW POINT HATAF QAMATS;Mn;13;NSM;;;;;N;;;;; -05B4;HEBREW POINT HIRIQ;Mn;14;NSM;;;;;N;;;;; -05B5;HEBREW POINT TSERE;Mn;15;NSM;;;;;N;;;;; -05B6;HEBREW POINT SEGOL;Mn;16;NSM;;;;;N;;;;; -05B7;HEBREW POINT PATAH;Mn;17;NSM;;;;;N;;;;; -05B8;HEBREW POINT QAMATS;Mn;18;NSM;;;;;N;;;;; -05B9;HEBREW POINT HOLAM;Mn;19;NSM;;;;;N;;;;; -05BA;HEBREW POINT HOLAM HASER FOR VAV;Mn;19;NSM;;;;;N;;;;; -05BB;HEBREW POINT QUBUTS;Mn;20;NSM;;;;;N;;;;; -05BC;HEBREW POINT DAGESH OR MAPIQ;Mn;21;NSM;;;;;N;HEBREW POINT DAGESH;or shuruq;;; -05BD;HEBREW POINT METEG;Mn;22;NSM;;;;;N;;*;;; -05BE;HEBREW PUNCTUATION MAQAF;Pd;0;R;;;;;N;;;;; -05BF;HEBREW POINT RAFE;Mn;23;NSM;;;;;N;;;;; -05C0;HEBREW PUNCTUATION PASEQ;Po;0;R;;;;;N;HEBREW POINT PASEQ;*;;; -05C1;HEBREW POINT SHIN DOT;Mn;24;NSM;;;;;N;;;;; -05C2;HEBREW POINT SIN DOT;Mn;25;NSM;;;;;N;;;;; -05C3;HEBREW PUNCTUATION SOF PASUQ;Po;0;R;;;;;N;;*;;; -05C4;HEBREW MARK UPPER DOT;Mn;230;NSM;;;;;N;;;;; -05C5;HEBREW MARK LOWER DOT;Mn;220;NSM;;;;;N;;;;; -05C6;HEBREW PUNCTUATION NUN HAFUKHA;Po;0;R;;;;;N;;;;; -05C7;HEBREW POINT QAMATS QATAN;Mn;18;NSM;;;;;N;;;;; -05D0;HEBREW LETTER ALEF;Lo;0;R;;;;;N;;;;; -05D1;HEBREW LETTER BET;Lo;0;R;;;;;N;;;;; -05D2;HEBREW LETTER GIMEL;Lo;0;R;;;;;N;;;;; -05D3;HEBREW LETTER DALET;Lo;0;R;;;;;N;;;;; -05D4;HEBREW LETTER HE;Lo;0;R;;;;;N;;;;; -05D5;HEBREW LETTER VAV;Lo;0;R;;;;;N;;;;; -05D6;HEBREW LETTER ZAYIN;Lo;0;R;;;;;N;;;;; -05D7;HEBREW LETTER HET;Lo;0;R;;;;;N;;;;; -05D8;HEBREW LETTER TET;Lo;0;R;;;;;N;;;;; -05D9;HEBREW LETTER YOD;Lo;0;R;;;;;N;;;;; -05DA;HEBREW LETTER FINAL KAF;Lo;0;R;;;;;N;;;;; -05DB;HEBREW LETTER KAF;Lo;0;R;;;;;N;;;;; -05DC;HEBREW LETTER LAMED;Lo;0;R;;;;;N;;;;; -05DD;HEBREW LETTER FINAL MEM;Lo;0;R;;;;;N;;;;; -05DE;HEBREW LETTER MEM;Lo;0;R;;;;;N;;;;; -05DF;HEBREW LETTER FINAL NUN;Lo;0;R;;;;;N;;;;; -05E0;HEBREW LETTER NUN;Lo;0;R;;;;;N;;;;; -05E1;HEBREW LETTER SAMEKH;Lo;0;R;;;;;N;;;;; -05E2;HEBREW LETTER AYIN;Lo;0;R;;;;;N;;;;; -05E3;HEBREW LETTER FINAL PE;Lo;0;R;;;;;N;;;;; -05E4;HEBREW LETTER PE;Lo;0;R;;;;;N;;;;; -05E5;HEBREW LETTER FINAL TSADI;Lo;0;R;;;;;N;;;;; -05E6;HEBREW LETTER TSADI;Lo;0;R;;;;;N;;;;; -05E7;HEBREW LETTER QOF;Lo;0;R;;;;;N;;;;; -05E8;HEBREW LETTER RESH;Lo;0;R;;;;;N;;;;; -05E9;HEBREW LETTER SHIN;Lo;0;R;;;;;N;;;;; -05EA;HEBREW LETTER TAV;Lo;0;R;;;;;N;;;;; -05F0;HEBREW LIGATURE YIDDISH DOUBLE VAV;Lo;0;R;;;;;N;HEBREW LETTER DOUBLE VAV;;;; -05F1;HEBREW LIGATURE YIDDISH VAV YOD;Lo;0;R;;;;;N;HEBREW LETTER VAV YOD;;;; -05F2;HEBREW LIGATURE YIDDISH DOUBLE YOD;Lo;0;R;;;;;N;HEBREW LETTER DOUBLE YOD;;;; -05F3;HEBREW PUNCTUATION GERESH;Po;0;R;;;;;N;;;;; -05F4;HEBREW PUNCTUATION GERSHAYIM;Po;0;R;;;;;N;;;;; -0600;ARABIC NUMBER SIGN;Cf;0;AN;;;;;N;;;;; -0601;ARABIC SIGN SANAH;Cf;0;AN;;;;;N;;;;; -0602;ARABIC FOOTNOTE MARKER;Cf;0;AN;;;;;N;;;;; -0603;ARABIC SIGN SAFHA;Cf;0;AN;;;;;N;;;;; -0606;ARABIC-INDIC CUBE ROOT;Sm;0;ON;;;;;N;;;;; -0607;ARABIC-INDIC FOURTH ROOT;Sm;0;ON;;;;;N;;;;; -0608;ARABIC RAY;Sm;0;AL;;;;;N;;;;; -0609;ARABIC-INDIC PER MILLE SIGN;Po;0;ET;;;;;N;;;;; -060A;ARABIC-INDIC PER TEN THOUSAND SIGN;Po;0;ET;;;;;N;;;;; -060B;AFGHANI SIGN;Sc;0;AL;;;;;N;;;;; -060C;ARABIC COMMA;Po;0;CS;;;;;N;;;;; -060D;ARABIC DATE SEPARATOR;Po;0;AL;;;;;N;;;;; -060E;ARABIC POETIC VERSE SIGN;So;0;ON;;;;;N;;;;; -060F;ARABIC SIGN MISRA;So;0;ON;;;;;N;;;;; -0610;ARABIC SIGN SALLALLAHOU ALAYHE WASSALLAM;Mn;230;NSM;;;;;N;;;;; -0611;ARABIC SIGN ALAYHE ASSALLAM;Mn;230;NSM;;;;;N;;;;; -0612;ARABIC SIGN RAHMATULLAH ALAYHE;Mn;230;NSM;;;;;N;;;;; -0613;ARABIC SIGN RADI ALLAHOU ANHU;Mn;230;NSM;;;;;N;;;;; -0614;ARABIC SIGN TAKHALLUS;Mn;230;NSM;;;;;N;;;;; -0615;ARABIC SMALL HIGH TAH;Mn;230;NSM;;;;;N;;;;; -0616;ARABIC SMALL HIGH LIGATURE ALEF WITH LAM WITH YEH;Mn;230;NSM;;;;;N;;;;; -0617;ARABIC SMALL HIGH ZAIN;Mn;230;NSM;;;;;N;;;;; -0618;ARABIC SMALL FATHA;Mn;30;NSM;;;;;N;;;;; -0619;ARABIC SMALL DAMMA;Mn;31;NSM;;;;;N;;;;; -061A;ARABIC SMALL KASRA;Mn;32;NSM;;;;;N;;;;; -061B;ARABIC SEMICOLON;Po;0;AL;;;;;N;;;;; -061E;ARABIC TRIPLE DOT PUNCTUATION MARK;Po;0;AL;;;;;N;;;;; -061F;ARABIC QUESTION MARK;Po;0;AL;;;;;N;;;;; -0621;ARABIC LETTER HAMZA;Lo;0;AL;;;;;N;ARABIC LETTER HAMZAH;;;; -0622;ARABIC LETTER ALEF WITH MADDA ABOVE;Lo;0;AL;0627 0653;;;;N;ARABIC LETTER MADDAH ON ALEF;;;; -0623;ARABIC LETTER ALEF WITH HAMZA ABOVE;Lo;0;AL;0627 0654;;;;N;ARABIC LETTER HAMZAH ON ALEF;;;; -0624;ARABIC LETTER WAW WITH HAMZA ABOVE;Lo;0;AL;0648 0654;;;;N;ARABIC LETTER HAMZAH ON WAW;;;; -0625;ARABIC LETTER ALEF WITH HAMZA BELOW;Lo;0;AL;0627 0655;;;;N;ARABIC LETTER HAMZAH UNDER ALEF;;;; -0626;ARABIC LETTER YEH WITH HAMZA ABOVE;Lo;0;AL;064A 0654;;;;N;ARABIC LETTER HAMZAH ON YA;;;; -0627;ARABIC LETTER ALEF;Lo;0;AL;;;;;N;;;;; -0628;ARABIC LETTER BEH;Lo;0;AL;;;;;N;ARABIC LETTER BAA;;;; -0629;ARABIC LETTER TEH MARBUTA;Lo;0;AL;;;;;N;ARABIC LETTER TAA MARBUTAH;;;; -062A;ARABIC LETTER TEH;Lo;0;AL;;;;;N;ARABIC LETTER TAA;;;; -062B;ARABIC LETTER THEH;Lo;0;AL;;;;;N;ARABIC LETTER THAA;;;; -062C;ARABIC LETTER JEEM;Lo;0;AL;;;;;N;;;;; -062D;ARABIC LETTER HAH;Lo;0;AL;;;;;N;ARABIC LETTER HAA;;;; -062E;ARABIC LETTER KHAH;Lo;0;AL;;;;;N;ARABIC LETTER KHAA;;;; -062F;ARABIC LETTER DAL;Lo;0;AL;;;;;N;;;;; -0630;ARABIC LETTER THAL;Lo;0;AL;;;;;N;;;;; -0631;ARABIC LETTER REH;Lo;0;AL;;;;;N;ARABIC LETTER RA;;;; -0632;ARABIC LETTER ZAIN;Lo;0;AL;;;;;N;;;;; -0633;ARABIC LETTER SEEN;Lo;0;AL;;;;;N;;;;; -0634;ARABIC LETTER SHEEN;Lo;0;AL;;;;;N;;;;; -0635;ARABIC LETTER SAD;Lo;0;AL;;;;;N;;;;; -0636;ARABIC LETTER DAD;Lo;0;AL;;;;;N;;;;; -0637;ARABIC LETTER TAH;Lo;0;AL;;;;;N;;;;; -0638;ARABIC LETTER ZAH;Lo;0;AL;;;;;N;ARABIC LETTER DHAH;;;; -0639;ARABIC LETTER AIN;Lo;0;AL;;;;;N;;;;; -063A;ARABIC LETTER GHAIN;Lo;0;AL;;;;;N;;;;; -063B;ARABIC LETTER KEHEH WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -063C;ARABIC LETTER KEHEH WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;;;;; -063D;ARABIC LETTER FARSI YEH WITH INVERTED V;Lo;0;AL;;;;;N;;;;; -063E;ARABIC LETTER FARSI YEH WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -063F;ARABIC LETTER FARSI YEH WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0640;ARABIC TATWEEL;Lm;0;AL;;;;;N;;;;; -0641;ARABIC LETTER FEH;Lo;0;AL;;;;;N;ARABIC LETTER FA;;;; -0642;ARABIC LETTER QAF;Lo;0;AL;;;;;N;;;;; -0643;ARABIC LETTER KAF;Lo;0;AL;;;;;N;ARABIC LETTER CAF;;;; -0644;ARABIC LETTER LAM;Lo;0;AL;;;;;N;;;;; -0645;ARABIC LETTER MEEM;Lo;0;AL;;;;;N;;;;; -0646;ARABIC LETTER NOON;Lo;0;AL;;;;;N;;;;; -0647;ARABIC LETTER HEH;Lo;0;AL;;;;;N;ARABIC LETTER HA;;;; -0648;ARABIC LETTER WAW;Lo;0;AL;;;;;N;;;;; -0649;ARABIC LETTER ALEF MAKSURA;Lo;0;AL;;;;;N;ARABIC LETTER ALEF MAQSURAH;;;; -064A;ARABIC LETTER YEH;Lo;0;AL;;;;;N;ARABIC LETTER YA;;;; -064B;ARABIC FATHATAN;Mn;27;NSM;;;;;N;;;;; -064C;ARABIC DAMMATAN;Mn;28;NSM;;;;;N;;;;; -064D;ARABIC KASRATAN;Mn;29;NSM;;;;;N;;;;; -064E;ARABIC FATHA;Mn;30;NSM;;;;;N;ARABIC FATHAH;;;; -064F;ARABIC DAMMA;Mn;31;NSM;;;;;N;ARABIC DAMMAH;;;; -0650;ARABIC KASRA;Mn;32;NSM;;;;;N;ARABIC KASRAH;;;; -0651;ARABIC SHADDA;Mn;33;NSM;;;;;N;ARABIC SHADDAH;;;; -0652;ARABIC SUKUN;Mn;34;NSM;;;;;N;;;;; -0653;ARABIC MADDAH ABOVE;Mn;230;NSM;;;;;N;;;;; -0654;ARABIC HAMZA ABOVE;Mn;230;NSM;;;;;N;;;;; -0655;ARABIC HAMZA BELOW;Mn;220;NSM;;;;;N;;;;; -0656;ARABIC SUBSCRIPT ALEF;Mn;220;NSM;;;;;N;;;;; -0657;ARABIC INVERTED DAMMA;Mn;230;NSM;;;;;N;;;;; -0658;ARABIC MARK NOON GHUNNA;Mn;230;NSM;;;;;N;;;;; -0659;ARABIC ZWARAKAY;Mn;230;NSM;;;;;N;;;;; -065A;ARABIC VOWEL SIGN SMALL V ABOVE;Mn;230;NSM;;;;;N;;;;; -065B;ARABIC VOWEL SIGN INVERTED SMALL V ABOVE;Mn;230;NSM;;;;;N;;;;; -065C;ARABIC VOWEL SIGN DOT BELOW;Mn;220;NSM;;;;;N;;;;; -065D;ARABIC REVERSED DAMMA;Mn;230;NSM;;;;;N;;;;; -065E;ARABIC FATHA WITH TWO DOTS;Mn;230;NSM;;;;;N;;;;; -0660;ARABIC-INDIC DIGIT ZERO;Nd;0;AN;;0;0;0;N;;;;; -0661;ARABIC-INDIC DIGIT ONE;Nd;0;AN;;1;1;1;N;;;;; -0662;ARABIC-INDIC DIGIT TWO;Nd;0;AN;;2;2;2;N;;;;; -0663;ARABIC-INDIC DIGIT THREE;Nd;0;AN;;3;3;3;N;;;;; -0664;ARABIC-INDIC DIGIT FOUR;Nd;0;AN;;4;4;4;N;;;;; -0665;ARABIC-INDIC DIGIT FIVE;Nd;0;AN;;5;5;5;N;;;;; -0666;ARABIC-INDIC DIGIT SIX;Nd;0;AN;;6;6;6;N;;;;; -0667;ARABIC-INDIC DIGIT SEVEN;Nd;0;AN;;7;7;7;N;;;;; -0668;ARABIC-INDIC DIGIT EIGHT;Nd;0;AN;;8;8;8;N;;;;; -0669;ARABIC-INDIC DIGIT NINE;Nd;0;AN;;9;9;9;N;;;;; -066A;ARABIC PERCENT SIGN;Po;0;ET;;;;;N;;;;; -066B;ARABIC DECIMAL SEPARATOR;Po;0;AN;;;;;N;;;;; -066C;ARABIC THOUSANDS SEPARATOR;Po;0;AN;;;;;N;;;;; -066D;ARABIC FIVE POINTED STAR;Po;0;AL;;;;;N;;;;; -066E;ARABIC LETTER DOTLESS BEH;Lo;0;AL;;;;;N;;;;; -066F;ARABIC LETTER DOTLESS QAF;Lo;0;AL;;;;;N;;;;; -0670;ARABIC LETTER SUPERSCRIPT ALEF;Mn;35;NSM;;;;;N;ARABIC ALEF ABOVE;;;; -0671;ARABIC LETTER ALEF WASLA;Lo;0;AL;;;;;N;ARABIC LETTER HAMZAT WASL ON ALEF;;;; -0672;ARABIC LETTER ALEF WITH WAVY HAMZA ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER WAVY HAMZAH ON ALEF;;;; -0673;ARABIC LETTER ALEF WITH WAVY HAMZA BELOW;Lo;0;AL;;;;;N;ARABIC LETTER WAVY HAMZAH UNDER ALEF;;;; -0674;ARABIC LETTER HIGH HAMZA;Lo;0;AL;;;;;N;ARABIC LETTER HIGH HAMZAH;;;; -0675;ARABIC LETTER HIGH HAMZA ALEF;Lo;0;AL; 0627 0674;;;;N;ARABIC LETTER HIGH HAMZAH ALEF;;;; -0676;ARABIC LETTER HIGH HAMZA WAW;Lo;0;AL; 0648 0674;;;;N;ARABIC LETTER HIGH HAMZAH WAW;;;; -0677;ARABIC LETTER U WITH HAMZA ABOVE;Lo;0;AL; 06C7 0674;;;;N;ARABIC LETTER HIGH HAMZAH WAW WITH DAMMAH;;;; -0678;ARABIC LETTER HIGH HAMZA YEH;Lo;0;AL; 064A 0674;;;;N;ARABIC LETTER HIGH HAMZAH YA;;;; -0679;ARABIC LETTER TTEH;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH SMALL TAH;;;; -067A;ARABIC LETTER TTEHEH;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH TWO DOTS VERTICAL ABOVE;;;; -067B;ARABIC LETTER BEEH;Lo;0;AL;;;;;N;ARABIC LETTER BAA WITH TWO DOTS VERTICAL BELOW;;;; -067C;ARABIC LETTER TEH WITH RING;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH RING;;;; -067D;ARABIC LETTER TEH WITH THREE DOTS ABOVE DOWNWARDS;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH THREE DOTS ABOVE DOWNWARD;;;; -067E;ARABIC LETTER PEH;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH THREE DOTS BELOW;;;; -067F;ARABIC LETTER TEHEH;Lo;0;AL;;;;;N;ARABIC LETTER TAA WITH FOUR DOTS ABOVE;;;; -0680;ARABIC LETTER BEHEH;Lo;0;AL;;;;;N;ARABIC LETTER BAA WITH FOUR DOTS BELOW;;;; -0681;ARABIC LETTER HAH WITH HAMZA ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER HAMZAH ON HAA;;;; -0682;ARABIC LETTER HAH WITH TWO DOTS VERTICAL ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH TWO DOTS VERTICAL ABOVE;;;; -0683;ARABIC LETTER NYEH;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH MIDDLE TWO DOTS;;;; -0684;ARABIC LETTER DYEH;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH MIDDLE TWO DOTS VERTICAL;;;; -0685;ARABIC LETTER HAH WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH THREE DOTS ABOVE;;;; -0686;ARABIC LETTER TCHEH;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH MIDDLE THREE DOTS DOWNWARD;;;; -0687;ARABIC LETTER TCHEHEH;Lo;0;AL;;;;;N;ARABIC LETTER HAA WITH MIDDLE FOUR DOTS;;;; -0688;ARABIC LETTER DDAL;Lo;0;AL;;;;;N;ARABIC LETTER DAL WITH SMALL TAH;;;; -0689;ARABIC LETTER DAL WITH RING;Lo;0;AL;;;;;N;;;;; -068A;ARABIC LETTER DAL WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -068B;ARABIC LETTER DAL WITH DOT BELOW AND SMALL TAH;Lo;0;AL;;;;;N;;;;; -068C;ARABIC LETTER DAHAL;Lo;0;AL;;;;;N;ARABIC LETTER DAL WITH TWO DOTS ABOVE;;;; -068D;ARABIC LETTER DDAHAL;Lo;0;AL;;;;;N;ARABIC LETTER DAL WITH TWO DOTS BELOW;;;; -068E;ARABIC LETTER DUL;Lo;0;AL;;;;;N;ARABIC LETTER DAL WITH THREE DOTS ABOVE;;;; -068F;ARABIC LETTER DAL WITH THREE DOTS ABOVE DOWNWARDS;Lo;0;AL;;;;;N;ARABIC LETTER DAL WITH THREE DOTS ABOVE DOWNWARD;;;; -0690;ARABIC LETTER DAL WITH FOUR DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0691;ARABIC LETTER RREH;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH SMALL TAH;;;; -0692;ARABIC LETTER REH WITH SMALL V;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH SMALL V;;;; -0693;ARABIC LETTER REH WITH RING;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH RING;;;; -0694;ARABIC LETTER REH WITH DOT BELOW;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH DOT BELOW;;;; -0695;ARABIC LETTER REH WITH SMALL V BELOW;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH SMALL V BELOW;;;; -0696;ARABIC LETTER REH WITH DOT BELOW AND DOT ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH DOT BELOW AND DOT ABOVE;;;; -0697;ARABIC LETTER REH WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH TWO DOTS ABOVE;;;; -0698;ARABIC LETTER JEH;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH THREE DOTS ABOVE;;;; -0699;ARABIC LETTER REH WITH FOUR DOTS ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER RA WITH FOUR DOTS ABOVE;;;; -069A;ARABIC LETTER SEEN WITH DOT BELOW AND DOT ABOVE;Lo;0;AL;;;;;N;;;;; -069B;ARABIC LETTER SEEN WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;;;;; -069C;ARABIC LETTER SEEN WITH THREE DOTS BELOW AND THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -069D;ARABIC LETTER SAD WITH TWO DOTS BELOW;Lo;0;AL;;;;;N;;;;; -069E;ARABIC LETTER SAD WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -069F;ARABIC LETTER TAH WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06A0;ARABIC LETTER AIN WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06A1;ARABIC LETTER DOTLESS FEH;Lo;0;AL;;;;;N;ARABIC LETTER DOTLESS FA;;;; -06A2;ARABIC LETTER FEH WITH DOT MOVED BELOW;Lo;0;AL;;;;;N;ARABIC LETTER FA WITH DOT MOVED BELOW;;;; -06A3;ARABIC LETTER FEH WITH DOT BELOW;Lo;0;AL;;;;;N;ARABIC LETTER FA WITH DOT BELOW;;;; -06A4;ARABIC LETTER VEH;Lo;0;AL;;;;;N;ARABIC LETTER FA WITH THREE DOTS ABOVE;;;; -06A5;ARABIC LETTER FEH WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;ARABIC LETTER FA WITH THREE DOTS BELOW;;;; -06A6;ARABIC LETTER PEHEH;Lo;0;AL;;;;;N;ARABIC LETTER FA WITH FOUR DOTS ABOVE;;;; -06A7;ARABIC LETTER QAF WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -06A8;ARABIC LETTER QAF WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06A9;ARABIC LETTER KEHEH;Lo;0;AL;;;;;N;ARABIC LETTER OPEN CAF;;;; -06AA;ARABIC LETTER SWASH KAF;Lo;0;AL;;;;;N;ARABIC LETTER SWASH CAF;;;; -06AB;ARABIC LETTER KAF WITH RING;Lo;0;AL;;;;;N;ARABIC LETTER CAF WITH RING;;;; -06AC;ARABIC LETTER KAF WITH DOT ABOVE;Lo;0;AL;;;;;N;ARABIC LETTER CAF WITH DOT ABOVE;;;; -06AD;ARABIC LETTER NG;Lo;0;AL;;;;;N;ARABIC LETTER CAF WITH THREE DOTS ABOVE;;;; -06AE;ARABIC LETTER KAF WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;ARABIC LETTER CAF WITH THREE DOTS BELOW;;;; -06AF;ARABIC LETTER GAF;Lo;0;AL;;;;;N;;*;;; -06B0;ARABIC LETTER GAF WITH RING;Lo;0;AL;;;;;N;;;;; -06B1;ARABIC LETTER NGOEH;Lo;0;AL;;;;;N;ARABIC LETTER GAF WITH TWO DOTS ABOVE;;;; -06B2;ARABIC LETTER GAF WITH TWO DOTS BELOW;Lo;0;AL;;;;;N;;;;; -06B3;ARABIC LETTER GUEH;Lo;0;AL;;;;;N;ARABIC LETTER GAF WITH TWO DOTS VERTICAL BELOW;;;; -06B4;ARABIC LETTER GAF WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06B5;ARABIC LETTER LAM WITH SMALL V;Lo;0;AL;;;;;N;;;;; -06B6;ARABIC LETTER LAM WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -06B7;ARABIC LETTER LAM WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06B8;ARABIC LETTER LAM WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;;;;; -06B9;ARABIC LETTER NOON WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -06BA;ARABIC LETTER NOON GHUNNA;Lo;0;AL;;;;;N;ARABIC LETTER DOTLESS NOON;;;; -06BB;ARABIC LETTER RNOON;Lo;0;AL;;;;;N;ARABIC LETTER DOTLESS NOON WITH SMALL TAH;;;; -06BC;ARABIC LETTER NOON WITH RING;Lo;0;AL;;;;;N;;;;; -06BD;ARABIC LETTER NOON WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06BE;ARABIC LETTER HEH DOACHASHMEE;Lo;0;AL;;;;;N;ARABIC LETTER KNOTTED HA;;;; -06BF;ARABIC LETTER TCHEH WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -06C0;ARABIC LETTER HEH WITH YEH ABOVE;Lo;0;AL;06D5 0654;;;;N;ARABIC LETTER HAMZAH ON HA;;;; -06C1;ARABIC LETTER HEH GOAL;Lo;0;AL;;;;;N;ARABIC LETTER HA GOAL;;;; -06C2;ARABIC LETTER HEH GOAL WITH HAMZA ABOVE;Lo;0;AL;06C1 0654;;;;N;ARABIC LETTER HAMZAH ON HA GOAL;;;; -06C3;ARABIC LETTER TEH MARBUTA GOAL;Lo;0;AL;;;;;N;ARABIC LETTER TAA MARBUTAH GOAL;;;; -06C4;ARABIC LETTER WAW WITH RING;Lo;0;AL;;;;;N;;;;; -06C5;ARABIC LETTER KIRGHIZ OE;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH BAR;;;; -06C6;ARABIC LETTER OE;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH SMALL V;;;; -06C7;ARABIC LETTER U;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH DAMMAH;;;; -06C8;ARABIC LETTER YU;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH ALEF ABOVE;;;; -06C9;ARABIC LETTER KIRGHIZ YU;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH INVERTED SMALL V;;;; -06CA;ARABIC LETTER WAW WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -06CB;ARABIC LETTER VE;Lo;0;AL;;;;;N;ARABIC LETTER WAW WITH THREE DOTS ABOVE;;;; -06CC;ARABIC LETTER FARSI YEH;Lo;0;AL;;;;;N;ARABIC LETTER DOTLESS YA;;;; -06CD;ARABIC LETTER YEH WITH TAIL;Lo;0;AL;;;;;N;ARABIC LETTER YA WITH TAIL;;;; -06CE;ARABIC LETTER YEH WITH SMALL V;Lo;0;AL;;;;;N;ARABIC LETTER YA WITH SMALL V;;;; -06CF;ARABIC LETTER WAW WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -06D0;ARABIC LETTER E;Lo;0;AL;;;;;N;ARABIC LETTER YA WITH TWO DOTS VERTICAL BELOW;*;;; -06D1;ARABIC LETTER YEH WITH THREE DOTS BELOW;Lo;0;AL;;;;;N;ARABIC LETTER YA WITH THREE DOTS BELOW;;;; -06D2;ARABIC LETTER YEH BARREE;Lo;0;AL;;;;;N;ARABIC LETTER YA BARREE;;;; -06D3;ARABIC LETTER YEH BARREE WITH HAMZA ABOVE;Lo;0;AL;06D2 0654;;;;N;ARABIC LETTER HAMZAH ON YA BARREE;;;; -06D4;ARABIC FULL STOP;Po;0;AL;;;;;N;ARABIC PERIOD;;;; -06D5;ARABIC LETTER AE;Lo;0;AL;;;;;N;;;;; -06D6;ARABIC SMALL HIGH LIGATURE SAD WITH LAM WITH ALEF MAKSURA;Mn;230;NSM;;;;;N;;;;; -06D7;ARABIC SMALL HIGH LIGATURE QAF WITH LAM WITH ALEF MAKSURA;Mn;230;NSM;;;;;N;;;;; -06D8;ARABIC SMALL HIGH MEEM INITIAL FORM;Mn;230;NSM;;;;;N;;;;; -06D9;ARABIC SMALL HIGH LAM ALEF;Mn;230;NSM;;;;;N;;;;; -06DA;ARABIC SMALL HIGH JEEM;Mn;230;NSM;;;;;N;;;;; -06DB;ARABIC SMALL HIGH THREE DOTS;Mn;230;NSM;;;;;N;;;;; -06DC;ARABIC SMALL HIGH SEEN;Mn;230;NSM;;;;;N;;;;; -06DD;ARABIC END OF AYAH;Cf;0;AN;;;;;N;;;;; -06DE;ARABIC START OF RUB EL HIZB;Me;0;NSM;;;;;N;;;;; -06DF;ARABIC SMALL HIGH ROUNDED ZERO;Mn;230;NSM;;;;;N;;;;; -06E0;ARABIC SMALL HIGH UPRIGHT RECTANGULAR ZERO;Mn;230;NSM;;;;;N;;;;; -06E1;ARABIC SMALL HIGH DOTLESS HEAD OF KHAH;Mn;230;NSM;;;;;N;;;;; -06E2;ARABIC SMALL HIGH MEEM ISOLATED FORM;Mn;230;NSM;;;;;N;;;;; -06E3;ARABIC SMALL LOW SEEN;Mn;220;NSM;;;;;N;;;;; -06E4;ARABIC SMALL HIGH MADDA;Mn;230;NSM;;;;;N;;;;; -06E5;ARABIC SMALL WAW;Lm;0;AL;;;;;N;;;;; -06E6;ARABIC SMALL YEH;Lm;0;AL;;;;;N;;;;; -06E7;ARABIC SMALL HIGH YEH;Mn;230;NSM;;;;;N;;;;; -06E8;ARABIC SMALL HIGH NOON;Mn;230;NSM;;;;;N;;;;; -06E9;ARABIC PLACE OF SAJDAH;So;0;ON;;;;;N;;;;; -06EA;ARABIC EMPTY CENTRE LOW STOP;Mn;220;NSM;;;;;N;;;;; -06EB;ARABIC EMPTY CENTRE HIGH STOP;Mn;230;NSM;;;;;N;;;;; -06EC;ARABIC ROUNDED HIGH STOP WITH FILLED CENTRE;Mn;230;NSM;;;;;N;;;;; -06ED;ARABIC SMALL LOW MEEM;Mn;220;NSM;;;;;N;;;;; -06EE;ARABIC LETTER DAL WITH INVERTED V;Lo;0;AL;;;;;N;;;;; -06EF;ARABIC LETTER REH WITH INVERTED V;Lo;0;AL;;;;;N;;;;; -06F0;EXTENDED ARABIC-INDIC DIGIT ZERO;Nd;0;EN;;0;0;0;N;EASTERN ARABIC-INDIC DIGIT ZERO;;;; -06F1;EXTENDED ARABIC-INDIC DIGIT ONE;Nd;0;EN;;1;1;1;N;EASTERN ARABIC-INDIC DIGIT ONE;;;; -06F2;EXTENDED ARABIC-INDIC DIGIT TWO;Nd;0;EN;;2;2;2;N;EASTERN ARABIC-INDIC DIGIT TWO;;;; -06F3;EXTENDED ARABIC-INDIC DIGIT THREE;Nd;0;EN;;3;3;3;N;EASTERN ARABIC-INDIC DIGIT THREE;;;; -06F4;EXTENDED ARABIC-INDIC DIGIT FOUR;Nd;0;EN;;4;4;4;N;EASTERN ARABIC-INDIC DIGIT FOUR;;;; -06F5;EXTENDED ARABIC-INDIC DIGIT FIVE;Nd;0;EN;;5;5;5;N;EASTERN ARABIC-INDIC DIGIT FIVE;;;; -06F6;EXTENDED ARABIC-INDIC DIGIT SIX;Nd;0;EN;;6;6;6;N;EASTERN ARABIC-INDIC DIGIT SIX;;;; -06F7;EXTENDED ARABIC-INDIC DIGIT SEVEN;Nd;0;EN;;7;7;7;N;EASTERN ARABIC-INDIC DIGIT SEVEN;;;; -06F8;EXTENDED ARABIC-INDIC DIGIT EIGHT;Nd;0;EN;;8;8;8;N;EASTERN ARABIC-INDIC DIGIT EIGHT;;;; -06F9;EXTENDED ARABIC-INDIC DIGIT NINE;Nd;0;EN;;9;9;9;N;EASTERN ARABIC-INDIC DIGIT NINE;;;; -06FA;ARABIC LETTER SHEEN WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -06FB;ARABIC LETTER DAD WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -06FC;ARABIC LETTER GHAIN WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -06FD;ARABIC SIGN SINDHI AMPERSAND;So;0;AL;;;;;N;;;;; -06FE;ARABIC SIGN SINDHI POSTPOSITION MEN;So;0;AL;;;;;N;;;;; -06FF;ARABIC LETTER HEH WITH INVERTED V;Lo;0;AL;;;;;N;;;;; -0700;SYRIAC END OF PARAGRAPH;Po;0;AL;;;;;N;;;;; -0701;SYRIAC SUPRALINEAR FULL STOP;Po;0;AL;;;;;N;;;;; -0702;SYRIAC SUBLINEAR FULL STOP;Po;0;AL;;;;;N;;;;; -0703;SYRIAC SUPRALINEAR COLON;Po;0;AL;;;;;N;;;;; -0704;SYRIAC SUBLINEAR COLON;Po;0;AL;;;;;N;;;;; -0705;SYRIAC HORIZONTAL COLON;Po;0;AL;;;;;N;;;;; -0706;SYRIAC COLON SKEWED LEFT;Po;0;AL;;;;;N;;;;; -0707;SYRIAC COLON SKEWED RIGHT;Po;0;AL;;;;;N;;;;; -0708;SYRIAC SUPRALINEAR COLON SKEWED LEFT;Po;0;AL;;;;;N;;;;; -0709;SYRIAC SUBLINEAR COLON SKEWED RIGHT;Po;0;AL;;;;;N;;;;; -070A;SYRIAC CONTRACTION;Po;0;AL;;;;;N;;;;; -070B;SYRIAC HARKLEAN OBELUS;Po;0;AL;;;;;N;;;;; -070C;SYRIAC HARKLEAN METOBELUS;Po;0;AL;;;;;N;;;;; -070D;SYRIAC HARKLEAN ASTERISCUS;Po;0;AL;;;;;N;;;;; -070F;SYRIAC ABBREVIATION MARK;Cf;0;BN;;;;;N;;;;; -0710;SYRIAC LETTER ALAPH;Lo;0;AL;;;;;N;;;;; -0711;SYRIAC LETTER SUPERSCRIPT ALAPH;Mn;36;NSM;;;;;N;;;;; -0712;SYRIAC LETTER BETH;Lo;0;AL;;;;;N;;;;; -0713;SYRIAC LETTER GAMAL;Lo;0;AL;;;;;N;;;;; -0714;SYRIAC LETTER GAMAL GARSHUNI;Lo;0;AL;;;;;N;;;;; -0715;SYRIAC LETTER DALATH;Lo;0;AL;;;;;N;;;;; -0716;SYRIAC LETTER DOTLESS DALATH RISH;Lo;0;AL;;;;;N;;;;; -0717;SYRIAC LETTER HE;Lo;0;AL;;;;;N;;;;; -0718;SYRIAC LETTER WAW;Lo;0;AL;;;;;N;;;;; -0719;SYRIAC LETTER ZAIN;Lo;0;AL;;;;;N;;;;; -071A;SYRIAC LETTER HETH;Lo;0;AL;;;;;N;;;;; -071B;SYRIAC LETTER TETH;Lo;0;AL;;;;;N;;;;; -071C;SYRIAC LETTER TETH GARSHUNI;Lo;0;AL;;;;;N;;;;; -071D;SYRIAC LETTER YUDH;Lo;0;AL;;;;;N;;;;; -071E;SYRIAC LETTER YUDH HE;Lo;0;AL;;;;;N;;;;; -071F;SYRIAC LETTER KAPH;Lo;0;AL;;;;;N;;;;; -0720;SYRIAC LETTER LAMADH;Lo;0;AL;;;;;N;;;;; -0721;SYRIAC LETTER MIM;Lo;0;AL;;;;;N;;;;; -0722;SYRIAC LETTER NUN;Lo;0;AL;;;;;N;;;;; -0723;SYRIAC LETTER SEMKATH;Lo;0;AL;;;;;N;;;;; -0724;SYRIAC LETTER FINAL SEMKATH;Lo;0;AL;;;;;N;;;;; -0725;SYRIAC LETTER E;Lo;0;AL;;;;;N;;;;; -0726;SYRIAC LETTER PE;Lo;0;AL;;;;;N;;;;; -0727;SYRIAC LETTER REVERSED PE;Lo;0;AL;;;;;N;;;;; -0728;SYRIAC LETTER SADHE;Lo;0;AL;;;;;N;;;;; -0729;SYRIAC LETTER QAPH;Lo;0;AL;;;;;N;;;;; -072A;SYRIAC LETTER RISH;Lo;0;AL;;;;;N;;;;; -072B;SYRIAC LETTER SHIN;Lo;0;AL;;;;;N;;;;; -072C;SYRIAC LETTER TAW;Lo;0;AL;;;;;N;;;;; -072D;SYRIAC LETTER PERSIAN BHETH;Lo;0;AL;;;;;N;;;;; -072E;SYRIAC LETTER PERSIAN GHAMAL;Lo;0;AL;;;;;N;;;;; -072F;SYRIAC LETTER PERSIAN DHALATH;Lo;0;AL;;;;;N;;;;; -0730;SYRIAC PTHAHA ABOVE;Mn;230;NSM;;;;;N;;;;; -0731;SYRIAC PTHAHA BELOW;Mn;220;NSM;;;;;N;;;;; -0732;SYRIAC PTHAHA DOTTED;Mn;230;NSM;;;;;N;;;;; -0733;SYRIAC ZQAPHA ABOVE;Mn;230;NSM;;;;;N;;;;; -0734;SYRIAC ZQAPHA BELOW;Mn;220;NSM;;;;;N;;;;; -0735;SYRIAC ZQAPHA DOTTED;Mn;230;NSM;;;;;N;;;;; -0736;SYRIAC RBASA ABOVE;Mn;230;NSM;;;;;N;;;;; -0737;SYRIAC RBASA BELOW;Mn;220;NSM;;;;;N;;;;; -0738;SYRIAC DOTTED ZLAMA HORIZONTAL;Mn;220;NSM;;;;;N;;;;; -0739;SYRIAC DOTTED ZLAMA ANGULAR;Mn;220;NSM;;;;;N;;;;; -073A;SYRIAC HBASA ABOVE;Mn;230;NSM;;;;;N;;;;; -073B;SYRIAC HBASA BELOW;Mn;220;NSM;;;;;N;;;;; -073C;SYRIAC HBASA-ESASA DOTTED;Mn;220;NSM;;;;;N;;;;; -073D;SYRIAC ESASA ABOVE;Mn;230;NSM;;;;;N;;;;; -073E;SYRIAC ESASA BELOW;Mn;220;NSM;;;;;N;;;;; -073F;SYRIAC RWAHA;Mn;230;NSM;;;;;N;;;;; -0740;SYRIAC FEMININE DOT;Mn;230;NSM;;;;;N;;;;; -0741;SYRIAC QUSHSHAYA;Mn;230;NSM;;;;;N;;;;; -0742;SYRIAC RUKKAKHA;Mn;220;NSM;;;;;N;;;;; -0743;SYRIAC TWO VERTICAL DOTS ABOVE;Mn;230;NSM;;;;;N;;;;; -0744;SYRIAC TWO VERTICAL DOTS BELOW;Mn;220;NSM;;;;;N;;;;; -0745;SYRIAC THREE DOTS ABOVE;Mn;230;NSM;;;;;N;;;;; -0746;SYRIAC THREE DOTS BELOW;Mn;220;NSM;;;;;N;;;;; -0747;SYRIAC OBLIQUE LINE ABOVE;Mn;230;NSM;;;;;N;;;;; -0748;SYRIAC OBLIQUE LINE BELOW;Mn;220;NSM;;;;;N;;;;; -0749;SYRIAC MUSIC;Mn;230;NSM;;;;;N;;;;; -074A;SYRIAC BARREKH;Mn;230;NSM;;;;;N;;;;; -074D;SYRIAC LETTER SOGDIAN ZHAIN;Lo;0;AL;;;;;N;;;;; -074E;SYRIAC LETTER SOGDIAN KHAPH;Lo;0;AL;;;;;N;;;;; -074F;SYRIAC LETTER SOGDIAN FE;Lo;0;AL;;;;;N;;;;; -0750;ARABIC LETTER BEH WITH THREE DOTS HORIZONTALLY BELOW;Lo;0;AL;;;;;N;;;;; -0751;ARABIC LETTER BEH WITH DOT BELOW AND THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0752;ARABIC LETTER BEH WITH THREE DOTS POINTING UPWARDS BELOW;Lo;0;AL;;;;;N;;;;; -0753;ARABIC LETTER BEH WITH THREE DOTS POINTING UPWARDS BELOW AND TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0754;ARABIC LETTER BEH WITH TWO DOTS BELOW AND DOT ABOVE;Lo;0;AL;;;;;N;;;;; -0755;ARABIC LETTER BEH WITH INVERTED SMALL V BELOW;Lo;0;AL;;;;;N;;;;; -0756;ARABIC LETTER BEH WITH SMALL V;Lo;0;AL;;;;;N;;;;; -0757;ARABIC LETTER HAH WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0758;ARABIC LETTER HAH WITH THREE DOTS POINTING UPWARDS BELOW;Lo;0;AL;;;;;N;;;;; -0759;ARABIC LETTER DAL WITH TWO DOTS VERTICALLY BELOW AND SMALL TAH;Lo;0;AL;;;;;N;;;;; -075A;ARABIC LETTER DAL WITH INVERTED SMALL V BELOW;Lo;0;AL;;;;;N;;;;; -075B;ARABIC LETTER REH WITH STROKE;Lo;0;AL;;;;;N;;;;; -075C;ARABIC LETTER SEEN WITH FOUR DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -075D;ARABIC LETTER AIN WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -075E;ARABIC LETTER AIN WITH THREE DOTS POINTING DOWNWARDS ABOVE;Lo;0;AL;;;;;N;;;;; -075F;ARABIC LETTER AIN WITH TWO DOTS VERTICALLY ABOVE;Lo;0;AL;;;;;N;;;;; -0760;ARABIC LETTER FEH WITH TWO DOTS BELOW;Lo;0;AL;;;;;N;;;;; -0761;ARABIC LETTER FEH WITH THREE DOTS POINTING UPWARDS BELOW;Lo;0;AL;;;;;N;;;;; -0762;ARABIC LETTER KEHEH WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -0763;ARABIC LETTER KEHEH WITH THREE DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0764;ARABIC LETTER KEHEH WITH THREE DOTS POINTING UPWARDS BELOW;Lo;0;AL;;;;;N;;;;; -0765;ARABIC LETTER MEEM WITH DOT ABOVE;Lo;0;AL;;;;;N;;;;; -0766;ARABIC LETTER MEEM WITH DOT BELOW;Lo;0;AL;;;;;N;;;;; -0767;ARABIC LETTER NOON WITH TWO DOTS BELOW;Lo;0;AL;;;;;N;;;;; -0768;ARABIC LETTER NOON WITH SMALL TAH;Lo;0;AL;;;;;N;;;;; -0769;ARABIC LETTER NOON WITH SMALL V;Lo;0;AL;;;;;N;;;;; -076A;ARABIC LETTER LAM WITH BAR;Lo;0;AL;;;;;N;;;;; -076B;ARABIC LETTER REH WITH TWO DOTS VERTICALLY ABOVE;Lo;0;AL;;;;;N;;;;; -076C;ARABIC LETTER REH WITH HAMZA ABOVE;Lo;0;AL;;;;;N;;;;; -076D;ARABIC LETTER SEEN WITH TWO DOTS VERTICALLY ABOVE;Lo;0;AL;;;;;N;;;;; -076E;ARABIC LETTER HAH WITH SMALL ARABIC LETTER TAH BELOW;Lo;0;AL;;;;;N;;;;; -076F;ARABIC LETTER HAH WITH SMALL ARABIC LETTER TAH AND TWO DOTS;Lo;0;AL;;;;;N;;;;; -0770;ARABIC LETTER SEEN WITH SMALL ARABIC LETTER TAH AND TWO DOTS;Lo;0;AL;;;;;N;;;;; -0771;ARABIC LETTER REH WITH SMALL ARABIC LETTER TAH AND TWO DOTS;Lo;0;AL;;;;;N;;;;; -0772;ARABIC LETTER HAH WITH SMALL ARABIC LETTER TAH ABOVE;Lo;0;AL;;;;;N;;;;; -0773;ARABIC LETTER ALEF WITH EXTENDED ARABIC-INDIC DIGIT TWO ABOVE;Lo;0;AL;;;;;N;;;;; -0774;ARABIC LETTER ALEF WITH EXTENDED ARABIC-INDIC DIGIT THREE ABOVE;Lo;0;AL;;;;;N;;;;; -0775;ARABIC LETTER FARSI YEH WITH EXTENDED ARABIC-INDIC DIGIT TWO ABOVE;Lo;0;AL;;;;;N;;;;; -0776;ARABIC LETTER FARSI YEH WITH EXTENDED ARABIC-INDIC DIGIT THREE ABOVE;Lo;0;AL;;;;;N;;;;; -0777;ARABIC LETTER FARSI YEH WITH EXTENDED ARABIC-INDIC DIGIT FOUR BELOW;Lo;0;AL;;;;;N;;;;; -0778;ARABIC LETTER WAW WITH EXTENDED ARABIC-INDIC DIGIT TWO ABOVE;Lo;0;AL;;;;;N;;;;; -0779;ARABIC LETTER WAW WITH EXTENDED ARABIC-INDIC DIGIT THREE ABOVE;Lo;0;AL;;;;;N;;;;; -077A;ARABIC LETTER YEH BARREE WITH EXTENDED ARABIC-INDIC DIGIT TWO ABOVE;Lo;0;AL;;;;;N;;;;; -077B;ARABIC LETTER YEH BARREE WITH EXTENDED ARABIC-INDIC DIGIT THREE ABOVE;Lo;0;AL;;;;;N;;;;; -077C;ARABIC LETTER HAH WITH EXTENDED ARABIC-INDIC DIGIT FOUR BELOW;Lo;0;AL;;;;;N;;;;; -077D;ARABIC LETTER SEEN WITH EXTENDED ARABIC-INDIC DIGIT FOUR ABOVE;Lo;0;AL;;;;;N;;;;; -077E;ARABIC LETTER SEEN WITH INVERTED V;Lo;0;AL;;;;;N;;;;; -077F;ARABIC LETTER KAF WITH TWO DOTS ABOVE;Lo;0;AL;;;;;N;;;;; -0780;THAANA LETTER HAA;Lo;0;AL;;;;;N;;;;; -0781;THAANA LETTER SHAVIYANI;Lo;0;AL;;;;;N;;;;; -0782;THAANA LETTER NOONU;Lo;0;AL;;;;;N;;;;; -0783;THAANA LETTER RAA;Lo;0;AL;;;;;N;;;;; -0784;THAANA LETTER BAA;Lo;0;AL;;;;;N;;;;; -0785;THAANA LETTER LHAVIYANI;Lo;0;AL;;;;;N;;;;; -0786;THAANA LETTER KAAFU;Lo;0;AL;;;;;N;;;;; -0787;THAANA LETTER ALIFU;Lo;0;AL;;;;;N;;;;; -0788;THAANA LETTER VAAVU;Lo;0;AL;;;;;N;;;;; -0789;THAANA LETTER MEEMU;Lo;0;AL;;;;;N;;;;; -078A;THAANA LETTER FAAFU;Lo;0;AL;;;;;N;;;;; -078B;THAANA LETTER DHAALU;Lo;0;AL;;;;;N;;;;; -078C;THAANA LETTER THAA;Lo;0;AL;;;;;N;;;;; -078D;THAANA LETTER LAAMU;Lo;0;AL;;;;;N;;;;; -078E;THAANA LETTER GAAFU;Lo;0;AL;;;;;N;;;;; -078F;THAANA LETTER GNAVIYANI;Lo;0;AL;;;;;N;;;;; -0790;THAANA LETTER SEENU;Lo;0;AL;;;;;N;;;;; -0791;THAANA LETTER DAVIYANI;Lo;0;AL;;;;;N;;;;; -0792;THAANA LETTER ZAVIYANI;Lo;0;AL;;;;;N;;;;; -0793;THAANA LETTER TAVIYANI;Lo;0;AL;;;;;N;;;;; -0794;THAANA LETTER YAA;Lo;0;AL;;;;;N;;;;; -0795;THAANA LETTER PAVIYANI;Lo;0;AL;;;;;N;;;;; -0796;THAANA LETTER JAVIYANI;Lo;0;AL;;;;;N;;;;; -0797;THAANA LETTER CHAVIYANI;Lo;0;AL;;;;;N;;;;; -0798;THAANA LETTER TTAA;Lo;0;AL;;;;;N;;;;; -0799;THAANA LETTER HHAA;Lo;0;AL;;;;;N;;;;; -079A;THAANA LETTER KHAA;Lo;0;AL;;;;;N;;;;; -079B;THAANA LETTER THAALU;Lo;0;AL;;;;;N;;;;; -079C;THAANA LETTER ZAA;Lo;0;AL;;;;;N;;;;; -079D;THAANA LETTER SHEENU;Lo;0;AL;;;;;N;;;;; -079E;THAANA LETTER SAADHU;Lo;0;AL;;;;;N;;;;; -079F;THAANA LETTER DAADHU;Lo;0;AL;;;;;N;;;;; -07A0;THAANA LETTER TO;Lo;0;AL;;;;;N;;;;; -07A1;THAANA LETTER ZO;Lo;0;AL;;;;;N;;;;; -07A2;THAANA LETTER AINU;Lo;0;AL;;;;;N;;;;; -07A3;THAANA LETTER GHAINU;Lo;0;AL;;;;;N;;;;; -07A4;THAANA LETTER QAAFU;Lo;0;AL;;;;;N;;;;; -07A5;THAANA LETTER WAAVU;Lo;0;AL;;;;;N;;;;; -07A6;THAANA ABAFILI;Mn;0;NSM;;;;;N;;;;; -07A7;THAANA AABAAFILI;Mn;0;NSM;;;;;N;;;;; -07A8;THAANA IBIFILI;Mn;0;NSM;;;;;N;;;;; -07A9;THAANA EEBEEFILI;Mn;0;NSM;;;;;N;;;;; -07AA;THAANA UBUFILI;Mn;0;NSM;;;;;N;;;;; -07AB;THAANA OOBOOFILI;Mn;0;NSM;;;;;N;;;;; -07AC;THAANA EBEFILI;Mn;0;NSM;;;;;N;;;;; -07AD;THAANA EYBEYFILI;Mn;0;NSM;;;;;N;;;;; -07AE;THAANA OBOFILI;Mn;0;NSM;;;;;N;;;;; -07AF;THAANA OABOAFILI;Mn;0;NSM;;;;;N;;;;; -07B0;THAANA SUKUN;Mn;0;NSM;;;;;N;;;;; -07B1;THAANA LETTER NAA;Lo;0;AL;;;;;N;;;;; -07C0;NKO DIGIT ZERO;Nd;0;R;;0;0;0;N;;;;; -07C1;NKO DIGIT ONE;Nd;0;R;;1;1;1;N;;;;; -07C2;NKO DIGIT TWO;Nd;0;R;;2;2;2;N;;;;; -07C3;NKO DIGIT THREE;Nd;0;R;;3;3;3;N;;;;; -07C4;NKO DIGIT FOUR;Nd;0;R;;4;4;4;N;;;;; -07C5;NKO DIGIT FIVE;Nd;0;R;;5;5;5;N;;;;; -07C6;NKO DIGIT SIX;Nd;0;R;;6;6;6;N;;;;; -07C7;NKO DIGIT SEVEN;Nd;0;R;;7;7;7;N;;;;; -07C8;NKO DIGIT EIGHT;Nd;0;R;;8;8;8;N;;;;; -07C9;NKO DIGIT NINE;Nd;0;R;;9;9;9;N;;;;; -07CA;NKO LETTER A;Lo;0;R;;;;;N;;;;; -07CB;NKO LETTER EE;Lo;0;R;;;;;N;;;;; -07CC;NKO LETTER I;Lo;0;R;;;;;N;;;;; -07CD;NKO LETTER E;Lo;0;R;;;;;N;;;;; -07CE;NKO LETTER U;Lo;0;R;;;;;N;;;;; -07CF;NKO LETTER OO;Lo;0;R;;;;;N;;;;; -07D0;NKO LETTER O;Lo;0;R;;;;;N;;;;; -07D1;NKO LETTER DAGBASINNA;Lo;0;R;;;;;N;;;;; -07D2;NKO LETTER N;Lo;0;R;;;;;N;;;;; -07D3;NKO LETTER BA;Lo;0;R;;;;;N;;;;; -07D4;NKO LETTER PA;Lo;0;R;;;;;N;;;;; -07D5;NKO LETTER TA;Lo;0;R;;;;;N;;;;; -07D6;NKO LETTER JA;Lo;0;R;;;;;N;;;;; -07D7;NKO LETTER CHA;Lo;0;R;;;;;N;;;;; -07D8;NKO LETTER DA;Lo;0;R;;;;;N;;;;; -07D9;NKO LETTER RA;Lo;0;R;;;;;N;;;;; -07DA;NKO LETTER RRA;Lo;0;R;;;;;N;;;;; -07DB;NKO LETTER SA;Lo;0;R;;;;;N;;;;; -07DC;NKO LETTER GBA;Lo;0;R;;;;;N;;;;; -07DD;NKO LETTER FA;Lo;0;R;;;;;N;;;;; -07DE;NKO LETTER KA;Lo;0;R;;;;;N;;;;; -07DF;NKO LETTER LA;Lo;0;R;;;;;N;;;;; -07E0;NKO LETTER NA WOLOSO;Lo;0;R;;;;;N;;;;; -07E1;NKO LETTER MA;Lo;0;R;;;;;N;;;;; -07E2;NKO LETTER NYA;Lo;0;R;;;;;N;;;;; -07E3;NKO LETTER NA;Lo;0;R;;;;;N;;;;; -07E4;NKO LETTER HA;Lo;0;R;;;;;N;;;;; -07E5;NKO LETTER WA;Lo;0;R;;;;;N;;;;; -07E6;NKO LETTER YA;Lo;0;R;;;;;N;;;;; -07E7;NKO LETTER NYA WOLOSO;Lo;0;R;;;;;N;;;;; -07E8;NKO LETTER JONA JA;Lo;0;R;;;;;N;;;;; -07E9;NKO LETTER JONA CHA;Lo;0;R;;;;;N;;;;; -07EA;NKO LETTER JONA RA;Lo;0;R;;;;;N;;;;; -07EB;NKO COMBINING SHORT HIGH TONE;Mn;230;NSM;;;;;N;;;;; -07EC;NKO COMBINING SHORT LOW TONE;Mn;230;NSM;;;;;N;;;;; -07ED;NKO COMBINING SHORT RISING TONE;Mn;230;NSM;;;;;N;;;;; -07EE;NKO COMBINING LONG DESCENDING TONE;Mn;230;NSM;;;;;N;;;;; -07EF;NKO COMBINING LONG HIGH TONE;Mn;230;NSM;;;;;N;;;;; -07F0;NKO COMBINING LONG LOW TONE;Mn;230;NSM;;;;;N;;;;; -07F1;NKO COMBINING LONG RISING TONE;Mn;230;NSM;;;;;N;;;;; -07F2;NKO COMBINING NASALIZATION MARK;Mn;220;NSM;;;;;N;;;;; -07F3;NKO COMBINING DOUBLE DOT ABOVE;Mn;230;NSM;;;;;N;;;;; -07F4;NKO HIGH TONE APOSTROPHE;Lm;0;R;;;;;N;;;;; -07F5;NKO LOW TONE APOSTROPHE;Lm;0;R;;;;;N;;;;; -07F6;NKO SYMBOL OO DENNEN;So;0;ON;;;;;N;;;;; -07F7;NKO SYMBOL GBAKURUNEN;Po;0;ON;;;;;N;;;;; -07F8;NKO COMMA;Po;0;ON;;;;;N;;;;; -07F9;NKO EXCLAMATION MARK;Po;0;ON;;;;;N;;;;; -07FA;NKO LAJANYALAN;Lm;0;R;;;;;N;;;;; -0901;DEVANAGARI SIGN CANDRABINDU;Mn;0;NSM;;;;;N;;;;; -0902;DEVANAGARI SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -0903;DEVANAGARI SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0904;DEVANAGARI LETTER SHORT A;Lo;0;L;;;;;N;;;;; -0905;DEVANAGARI LETTER A;Lo;0;L;;;;;N;;;;; -0906;DEVANAGARI LETTER AA;Lo;0;L;;;;;N;;;;; -0907;DEVANAGARI LETTER I;Lo;0;L;;;;;N;;;;; -0908;DEVANAGARI LETTER II;Lo;0;L;;;;;N;;;;; -0909;DEVANAGARI LETTER U;Lo;0;L;;;;;N;;;;; -090A;DEVANAGARI LETTER UU;Lo;0;L;;;;;N;;;;; -090B;DEVANAGARI LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -090C;DEVANAGARI LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -090D;DEVANAGARI LETTER CANDRA E;Lo;0;L;;;;;N;;;;; -090E;DEVANAGARI LETTER SHORT E;Lo;0;L;;;;;N;;;;; -090F;DEVANAGARI LETTER E;Lo;0;L;;;;;N;;;;; -0910;DEVANAGARI LETTER AI;Lo;0;L;;;;;N;;;;; -0911;DEVANAGARI LETTER CANDRA O;Lo;0;L;;;;;N;;;;; -0912;DEVANAGARI LETTER SHORT O;Lo;0;L;;;;;N;;;;; -0913;DEVANAGARI LETTER O;Lo;0;L;;;;;N;;;;; -0914;DEVANAGARI LETTER AU;Lo;0;L;;;;;N;;;;; -0915;DEVANAGARI LETTER KA;Lo;0;L;;;;;N;;;;; -0916;DEVANAGARI LETTER KHA;Lo;0;L;;;;;N;;;;; -0917;DEVANAGARI LETTER GA;Lo;0;L;;;;;N;;;;; -0918;DEVANAGARI LETTER GHA;Lo;0;L;;;;;N;;;;; -0919;DEVANAGARI LETTER NGA;Lo;0;L;;;;;N;;;;; -091A;DEVANAGARI LETTER CA;Lo;0;L;;;;;N;;;;; -091B;DEVANAGARI LETTER CHA;Lo;0;L;;;;;N;;;;; -091C;DEVANAGARI LETTER JA;Lo;0;L;;;;;N;;;;; -091D;DEVANAGARI LETTER JHA;Lo;0;L;;;;;N;;;;; -091E;DEVANAGARI LETTER NYA;Lo;0;L;;;;;N;;;;; -091F;DEVANAGARI LETTER TTA;Lo;0;L;;;;;N;;;;; -0920;DEVANAGARI LETTER TTHA;Lo;0;L;;;;;N;;;;; -0921;DEVANAGARI LETTER DDA;Lo;0;L;;;;;N;;;;; -0922;DEVANAGARI LETTER DDHA;Lo;0;L;;;;;N;;;;; -0923;DEVANAGARI LETTER NNA;Lo;0;L;;;;;N;;;;; -0924;DEVANAGARI LETTER TA;Lo;0;L;;;;;N;;;;; -0925;DEVANAGARI LETTER THA;Lo;0;L;;;;;N;;;;; -0926;DEVANAGARI LETTER DA;Lo;0;L;;;;;N;;;;; -0927;DEVANAGARI LETTER DHA;Lo;0;L;;;;;N;;;;; -0928;DEVANAGARI LETTER NA;Lo;0;L;;;;;N;;;;; -0929;DEVANAGARI LETTER NNNA;Lo;0;L;0928 093C;;;;N;;;;; -092A;DEVANAGARI LETTER PA;Lo;0;L;;;;;N;;;;; -092B;DEVANAGARI LETTER PHA;Lo;0;L;;;;;N;;;;; -092C;DEVANAGARI LETTER BA;Lo;0;L;;;;;N;;;;; -092D;DEVANAGARI LETTER BHA;Lo;0;L;;;;;N;;;;; -092E;DEVANAGARI LETTER MA;Lo;0;L;;;;;N;;;;; -092F;DEVANAGARI LETTER YA;Lo;0;L;;;;;N;;;;; -0930;DEVANAGARI LETTER RA;Lo;0;L;;;;;N;;;;; -0931;DEVANAGARI LETTER RRA;Lo;0;L;0930 093C;;;;N;;;;; -0932;DEVANAGARI LETTER LA;Lo;0;L;;;;;N;;;;; -0933;DEVANAGARI LETTER LLA;Lo;0;L;;;;;N;;;;; -0934;DEVANAGARI LETTER LLLA;Lo;0;L;0933 093C;;;;N;;;;; -0935;DEVANAGARI LETTER VA;Lo;0;L;;;;;N;;;;; -0936;DEVANAGARI LETTER SHA;Lo;0;L;;;;;N;;;;; -0937;DEVANAGARI LETTER SSA;Lo;0;L;;;;;N;;;;; -0938;DEVANAGARI LETTER SA;Lo;0;L;;;;;N;;;;; -0939;DEVANAGARI LETTER HA;Lo;0;L;;;;;N;;;;; -093C;DEVANAGARI SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -093D;DEVANAGARI SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -093E;DEVANAGARI VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -093F;DEVANAGARI VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -0940;DEVANAGARI VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -0941;DEVANAGARI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -0942;DEVANAGARI VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -0943;DEVANAGARI VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -0944;DEVANAGARI VOWEL SIGN VOCALIC RR;Mn;0;NSM;;;;;N;;;;; -0945;DEVANAGARI VOWEL SIGN CANDRA E;Mn;0;NSM;;;;;N;;;;; -0946;DEVANAGARI VOWEL SIGN SHORT E;Mn;0;NSM;;;;;N;;;;; -0947;DEVANAGARI VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -0948;DEVANAGARI VOWEL SIGN AI;Mn;0;NSM;;;;;N;;;;; -0949;DEVANAGARI VOWEL SIGN CANDRA O;Mc;0;L;;;;;N;;;;; -094A;DEVANAGARI VOWEL SIGN SHORT O;Mc;0;L;;;;;N;;;;; -094B;DEVANAGARI VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -094C;DEVANAGARI VOWEL SIGN AU;Mc;0;L;;;;;N;;;;; -094D;DEVANAGARI SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0950;DEVANAGARI OM;Lo;0;L;;;;;N;;;;; -0951;DEVANAGARI STRESS SIGN UDATTA;Mn;230;NSM;;;;;N;;;;; -0952;DEVANAGARI STRESS SIGN ANUDATTA;Mn;220;NSM;;;;;N;;;;; -0953;DEVANAGARI GRAVE ACCENT;Mn;230;NSM;;;;;N;;;;; -0954;DEVANAGARI ACUTE ACCENT;Mn;230;NSM;;;;;N;;;;; -0958;DEVANAGARI LETTER QA;Lo;0;L;0915 093C;;;;N;;;;; -0959;DEVANAGARI LETTER KHHA;Lo;0;L;0916 093C;;;;N;;;;; -095A;DEVANAGARI LETTER GHHA;Lo;0;L;0917 093C;;;;N;;;;; -095B;DEVANAGARI LETTER ZA;Lo;0;L;091C 093C;;;;N;;;;; -095C;DEVANAGARI LETTER DDDHA;Lo;0;L;0921 093C;;;;N;;;;; -095D;DEVANAGARI LETTER RHA;Lo;0;L;0922 093C;;;;N;;;;; -095E;DEVANAGARI LETTER FA;Lo;0;L;092B 093C;;;;N;;;;; -095F;DEVANAGARI LETTER YYA;Lo;0;L;092F 093C;;;;N;;;;; -0960;DEVANAGARI LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0961;DEVANAGARI LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0962;DEVANAGARI VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0963;DEVANAGARI VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0964;DEVANAGARI DANDA;Po;0;L;;;;;N;;;;; -0965;DEVANAGARI DOUBLE DANDA;Po;0;L;;;;;N;;;;; -0966;DEVANAGARI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0967;DEVANAGARI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0968;DEVANAGARI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0969;DEVANAGARI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -096A;DEVANAGARI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -096B;DEVANAGARI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -096C;DEVANAGARI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -096D;DEVANAGARI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -096E;DEVANAGARI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -096F;DEVANAGARI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0970;DEVANAGARI ABBREVIATION SIGN;Po;0;L;;;;;N;;;;; -0971;DEVANAGARI SIGN HIGH SPACING DOT;Lm;0;L;;;;;N;;;;; -0972;DEVANAGARI LETTER CANDRA A;Lo;0;L;;;;;N;;;;; -097B;DEVANAGARI LETTER GGA;Lo;0;L;;;;;N;;;;; -097C;DEVANAGARI LETTER JJA;Lo;0;L;;;;;N;;;;; -097D;DEVANAGARI LETTER GLOTTAL STOP;Lo;0;L;;;;;N;;;;; -097E;DEVANAGARI LETTER DDDA;Lo;0;L;;;;;N;;;;; -097F;DEVANAGARI LETTER BBA;Lo;0;L;;;;;N;;;;; -0981;BENGALI SIGN CANDRABINDU;Mn;0;NSM;;;;;N;;;;; -0982;BENGALI SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -0983;BENGALI SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0985;BENGALI LETTER A;Lo;0;L;;;;;N;;;;; -0986;BENGALI LETTER AA;Lo;0;L;;;;;N;;;;; -0987;BENGALI LETTER I;Lo;0;L;;;;;N;;;;; -0988;BENGALI LETTER II;Lo;0;L;;;;;N;;;;; -0989;BENGALI LETTER U;Lo;0;L;;;;;N;;;;; -098A;BENGALI LETTER UU;Lo;0;L;;;;;N;;;;; -098B;BENGALI LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -098C;BENGALI LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -098F;BENGALI LETTER E;Lo;0;L;;;;;N;;;;; -0990;BENGALI LETTER AI;Lo;0;L;;;;;N;;;;; -0993;BENGALI LETTER O;Lo;0;L;;;;;N;;;;; -0994;BENGALI LETTER AU;Lo;0;L;;;;;N;;;;; -0995;BENGALI LETTER KA;Lo;0;L;;;;;N;;;;; -0996;BENGALI LETTER KHA;Lo;0;L;;;;;N;;;;; -0997;BENGALI LETTER GA;Lo;0;L;;;;;N;;;;; -0998;BENGALI LETTER GHA;Lo;0;L;;;;;N;;;;; -0999;BENGALI LETTER NGA;Lo;0;L;;;;;N;;;;; -099A;BENGALI LETTER CA;Lo;0;L;;;;;N;;;;; -099B;BENGALI LETTER CHA;Lo;0;L;;;;;N;;;;; -099C;BENGALI LETTER JA;Lo;0;L;;;;;N;;;;; -099D;BENGALI LETTER JHA;Lo;0;L;;;;;N;;;;; -099E;BENGALI LETTER NYA;Lo;0;L;;;;;N;;;;; -099F;BENGALI LETTER TTA;Lo;0;L;;;;;N;;;;; -09A0;BENGALI LETTER TTHA;Lo;0;L;;;;;N;;;;; -09A1;BENGALI LETTER DDA;Lo;0;L;;;;;N;;;;; -09A2;BENGALI LETTER DDHA;Lo;0;L;;;;;N;;;;; -09A3;BENGALI LETTER NNA;Lo;0;L;;;;;N;;;;; -09A4;BENGALI LETTER TA;Lo;0;L;;;;;N;;;;; -09A5;BENGALI LETTER THA;Lo;0;L;;;;;N;;;;; -09A6;BENGALI LETTER DA;Lo;0;L;;;;;N;;;;; -09A7;BENGALI LETTER DHA;Lo;0;L;;;;;N;;;;; -09A8;BENGALI LETTER NA;Lo;0;L;;;;;N;;;;; -09AA;BENGALI LETTER PA;Lo;0;L;;;;;N;;;;; -09AB;BENGALI LETTER PHA;Lo;0;L;;;;;N;;;;; -09AC;BENGALI LETTER BA;Lo;0;L;;;;;N;;;;; -09AD;BENGALI LETTER BHA;Lo;0;L;;;;;N;;;;; -09AE;BENGALI LETTER MA;Lo;0;L;;;;;N;;;;; -09AF;BENGALI LETTER YA;Lo;0;L;;;;;N;;;;; -09B0;BENGALI LETTER RA;Lo;0;L;;;;;N;;;;; -09B2;BENGALI LETTER LA;Lo;0;L;;;;;N;;;;; -09B6;BENGALI LETTER SHA;Lo;0;L;;;;;N;;;;; -09B7;BENGALI LETTER SSA;Lo;0;L;;;;;N;;;;; -09B8;BENGALI LETTER SA;Lo;0;L;;;;;N;;;;; -09B9;BENGALI LETTER HA;Lo;0;L;;;;;N;;;;; -09BC;BENGALI SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -09BD;BENGALI SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -09BE;BENGALI VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -09BF;BENGALI VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -09C0;BENGALI VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -09C1;BENGALI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -09C2;BENGALI VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -09C3;BENGALI VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -09C4;BENGALI VOWEL SIGN VOCALIC RR;Mn;0;NSM;;;;;N;;;;; -09C7;BENGALI VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -09C8;BENGALI VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -09CB;BENGALI VOWEL SIGN O;Mc;0;L;09C7 09BE;;;;N;;;;; -09CC;BENGALI VOWEL SIGN AU;Mc;0;L;09C7 09D7;;;;N;;;;; -09CD;BENGALI SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -09CE;BENGALI LETTER KHANDA TA;Lo;0;L;;;;;N;;;;; -09D7;BENGALI AU LENGTH MARK;Mc;0;L;;;;;N;;;;; -09DC;BENGALI LETTER RRA;Lo;0;L;09A1 09BC;;;;N;;;;; -09DD;BENGALI LETTER RHA;Lo;0;L;09A2 09BC;;;;N;;;;; -09DF;BENGALI LETTER YYA;Lo;0;L;09AF 09BC;;;;N;;;;; -09E0;BENGALI LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -09E1;BENGALI LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -09E2;BENGALI VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -09E3;BENGALI VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -09E6;BENGALI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -09E7;BENGALI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -09E8;BENGALI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -09E9;BENGALI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -09EA;BENGALI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -09EB;BENGALI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -09EC;BENGALI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -09ED;BENGALI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -09EE;BENGALI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -09EF;BENGALI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -09F0;BENGALI LETTER RA WITH MIDDLE DIAGONAL;Lo;0;L;;;;;N;;Assamese;;; -09F1;BENGALI LETTER RA WITH LOWER DIAGONAL;Lo;0;L;;;;;N;BENGALI LETTER VA WITH LOWER DIAGONAL;Assamese;;; -09F2;BENGALI RUPEE MARK;Sc;0;ET;;;;;N;;;;; -09F3;BENGALI RUPEE SIGN;Sc;0;ET;;;;;N;;;;; -09F4;BENGALI CURRENCY NUMERATOR ONE;No;0;L;;;;1;N;;;;; -09F5;BENGALI CURRENCY NUMERATOR TWO;No;0;L;;;;2;N;;;;; -09F6;BENGALI CURRENCY NUMERATOR THREE;No;0;L;;;;3;N;;;;; -09F7;BENGALI CURRENCY NUMERATOR FOUR;No;0;L;;;;4;N;;;;; -09F8;BENGALI CURRENCY NUMERATOR ONE LESS THAN THE DENOMINATOR;No;0;L;;;;;N;;;;; -09F9;BENGALI CURRENCY DENOMINATOR SIXTEEN;No;0;L;;;;16;N;;;;; -09FA;BENGALI ISSHAR;So;0;L;;;;;N;;;;; -0A01;GURMUKHI SIGN ADAK BINDI;Mn;0;NSM;;;;;N;;;;; -0A02;GURMUKHI SIGN BINDI;Mn;0;NSM;;;;;N;;;;; -0A03;GURMUKHI SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0A05;GURMUKHI LETTER A;Lo;0;L;;;;;N;;;;; -0A06;GURMUKHI LETTER AA;Lo;0;L;;;;;N;;;;; -0A07;GURMUKHI LETTER I;Lo;0;L;;;;;N;;;;; -0A08;GURMUKHI LETTER II;Lo;0;L;;;;;N;;;;; -0A09;GURMUKHI LETTER U;Lo;0;L;;;;;N;;;;; -0A0A;GURMUKHI LETTER UU;Lo;0;L;;;;;N;;;;; -0A0F;GURMUKHI LETTER EE;Lo;0;L;;;;;N;;;;; -0A10;GURMUKHI LETTER AI;Lo;0;L;;;;;N;;;;; -0A13;GURMUKHI LETTER OO;Lo;0;L;;;;;N;;;;; -0A14;GURMUKHI LETTER AU;Lo;0;L;;;;;N;;;;; -0A15;GURMUKHI LETTER KA;Lo;0;L;;;;;N;;;;; -0A16;GURMUKHI LETTER KHA;Lo;0;L;;;;;N;;;;; -0A17;GURMUKHI LETTER GA;Lo;0;L;;;;;N;;;;; -0A18;GURMUKHI LETTER GHA;Lo;0;L;;;;;N;;;;; -0A19;GURMUKHI LETTER NGA;Lo;0;L;;;;;N;;;;; -0A1A;GURMUKHI LETTER CA;Lo;0;L;;;;;N;;;;; -0A1B;GURMUKHI LETTER CHA;Lo;0;L;;;;;N;;;;; -0A1C;GURMUKHI LETTER JA;Lo;0;L;;;;;N;;;;; -0A1D;GURMUKHI LETTER JHA;Lo;0;L;;;;;N;;;;; -0A1E;GURMUKHI LETTER NYA;Lo;0;L;;;;;N;;;;; -0A1F;GURMUKHI LETTER TTA;Lo;0;L;;;;;N;;;;; -0A20;GURMUKHI LETTER TTHA;Lo;0;L;;;;;N;;;;; -0A21;GURMUKHI LETTER DDA;Lo;0;L;;;;;N;;;;; -0A22;GURMUKHI LETTER DDHA;Lo;0;L;;;;;N;;;;; -0A23;GURMUKHI LETTER NNA;Lo;0;L;;;;;N;;;;; -0A24;GURMUKHI LETTER TA;Lo;0;L;;;;;N;;;;; -0A25;GURMUKHI LETTER THA;Lo;0;L;;;;;N;;;;; -0A26;GURMUKHI LETTER DA;Lo;0;L;;;;;N;;;;; -0A27;GURMUKHI LETTER DHA;Lo;0;L;;;;;N;;;;; -0A28;GURMUKHI LETTER NA;Lo;0;L;;;;;N;;;;; -0A2A;GURMUKHI LETTER PA;Lo;0;L;;;;;N;;;;; -0A2B;GURMUKHI LETTER PHA;Lo;0;L;;;;;N;;;;; -0A2C;GURMUKHI LETTER BA;Lo;0;L;;;;;N;;;;; -0A2D;GURMUKHI LETTER BHA;Lo;0;L;;;;;N;;;;; -0A2E;GURMUKHI LETTER MA;Lo;0;L;;;;;N;;;;; -0A2F;GURMUKHI LETTER YA;Lo;0;L;;;;;N;;;;; -0A30;GURMUKHI LETTER RA;Lo;0;L;;;;;N;;;;; -0A32;GURMUKHI LETTER LA;Lo;0;L;;;;;N;;;;; -0A33;GURMUKHI LETTER LLA;Lo;0;L;0A32 0A3C;;;;N;;;;; -0A35;GURMUKHI LETTER VA;Lo;0;L;;;;;N;;;;; -0A36;GURMUKHI LETTER SHA;Lo;0;L;0A38 0A3C;;;;N;;;;; -0A38;GURMUKHI LETTER SA;Lo;0;L;;;;;N;;;;; -0A39;GURMUKHI LETTER HA;Lo;0;L;;;;;N;;;;; -0A3C;GURMUKHI SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -0A3E;GURMUKHI VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0A3F;GURMUKHI VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -0A40;GURMUKHI VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -0A41;GURMUKHI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -0A42;GURMUKHI VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -0A47;GURMUKHI VOWEL SIGN EE;Mn;0;NSM;;;;;N;;;;; -0A48;GURMUKHI VOWEL SIGN AI;Mn;0;NSM;;;;;N;;;;; -0A4B;GURMUKHI VOWEL SIGN OO;Mn;0;NSM;;;;;N;;;;; -0A4C;GURMUKHI VOWEL SIGN AU;Mn;0;NSM;;;;;N;;;;; -0A4D;GURMUKHI SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0A51;GURMUKHI SIGN UDAAT;Mn;0;NSM;;;;;N;;;;; -0A59;GURMUKHI LETTER KHHA;Lo;0;L;0A16 0A3C;;;;N;;;;; -0A5A;GURMUKHI LETTER GHHA;Lo;0;L;0A17 0A3C;;;;N;;;;; -0A5B;GURMUKHI LETTER ZA;Lo;0;L;0A1C 0A3C;;;;N;;;;; -0A5C;GURMUKHI LETTER RRA;Lo;0;L;;;;;N;;;;; -0A5E;GURMUKHI LETTER FA;Lo;0;L;0A2B 0A3C;;;;N;;;;; -0A66;GURMUKHI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0A67;GURMUKHI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0A68;GURMUKHI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0A69;GURMUKHI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0A6A;GURMUKHI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0A6B;GURMUKHI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0A6C;GURMUKHI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0A6D;GURMUKHI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0A6E;GURMUKHI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0A6F;GURMUKHI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0A70;GURMUKHI TIPPI;Mn;0;NSM;;;;;N;;;;; -0A71;GURMUKHI ADDAK;Mn;0;NSM;;;;;N;;;;; -0A72;GURMUKHI IRI;Lo;0;L;;;;;N;;;;; -0A73;GURMUKHI URA;Lo;0;L;;;;;N;;;;; -0A74;GURMUKHI EK ONKAR;Lo;0;L;;;;;N;;;;; -0A75;GURMUKHI SIGN YAKASH;Mn;0;NSM;;;;;N;;;;; -0A81;GUJARATI SIGN CANDRABINDU;Mn;0;NSM;;;;;N;;;;; -0A82;GUJARATI SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -0A83;GUJARATI SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0A85;GUJARATI LETTER A;Lo;0;L;;;;;N;;;;; -0A86;GUJARATI LETTER AA;Lo;0;L;;;;;N;;;;; -0A87;GUJARATI LETTER I;Lo;0;L;;;;;N;;;;; -0A88;GUJARATI LETTER II;Lo;0;L;;;;;N;;;;; -0A89;GUJARATI LETTER U;Lo;0;L;;;;;N;;;;; -0A8A;GUJARATI LETTER UU;Lo;0;L;;;;;N;;;;; -0A8B;GUJARATI LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -0A8C;GUJARATI LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -0A8D;GUJARATI VOWEL CANDRA E;Lo;0;L;;;;;N;;;;; -0A8F;GUJARATI LETTER E;Lo;0;L;;;;;N;;;;; -0A90;GUJARATI LETTER AI;Lo;0;L;;;;;N;;;;; -0A91;GUJARATI VOWEL CANDRA O;Lo;0;L;;;;;N;;;;; -0A93;GUJARATI LETTER O;Lo;0;L;;;;;N;;;;; -0A94;GUJARATI LETTER AU;Lo;0;L;;;;;N;;;;; -0A95;GUJARATI LETTER KA;Lo;0;L;;;;;N;;;;; -0A96;GUJARATI LETTER KHA;Lo;0;L;;;;;N;;;;; -0A97;GUJARATI LETTER GA;Lo;0;L;;;;;N;;;;; -0A98;GUJARATI LETTER GHA;Lo;0;L;;;;;N;;;;; -0A99;GUJARATI LETTER NGA;Lo;0;L;;;;;N;;;;; -0A9A;GUJARATI LETTER CA;Lo;0;L;;;;;N;;;;; -0A9B;GUJARATI LETTER CHA;Lo;0;L;;;;;N;;;;; -0A9C;GUJARATI LETTER JA;Lo;0;L;;;;;N;;;;; -0A9D;GUJARATI LETTER JHA;Lo;0;L;;;;;N;;;;; -0A9E;GUJARATI LETTER NYA;Lo;0;L;;;;;N;;;;; -0A9F;GUJARATI LETTER TTA;Lo;0;L;;;;;N;;;;; -0AA0;GUJARATI LETTER TTHA;Lo;0;L;;;;;N;;;;; -0AA1;GUJARATI LETTER DDA;Lo;0;L;;;;;N;;;;; -0AA2;GUJARATI LETTER DDHA;Lo;0;L;;;;;N;;;;; -0AA3;GUJARATI LETTER NNA;Lo;0;L;;;;;N;;;;; -0AA4;GUJARATI LETTER TA;Lo;0;L;;;;;N;;;;; -0AA5;GUJARATI LETTER THA;Lo;0;L;;;;;N;;;;; -0AA6;GUJARATI LETTER DA;Lo;0;L;;;;;N;;;;; -0AA7;GUJARATI LETTER DHA;Lo;0;L;;;;;N;;;;; -0AA8;GUJARATI LETTER NA;Lo;0;L;;;;;N;;;;; -0AAA;GUJARATI LETTER PA;Lo;0;L;;;;;N;;;;; -0AAB;GUJARATI LETTER PHA;Lo;0;L;;;;;N;;;;; -0AAC;GUJARATI LETTER BA;Lo;0;L;;;;;N;;;;; -0AAD;GUJARATI LETTER BHA;Lo;0;L;;;;;N;;;;; -0AAE;GUJARATI LETTER MA;Lo;0;L;;;;;N;;;;; -0AAF;GUJARATI LETTER YA;Lo;0;L;;;;;N;;;;; -0AB0;GUJARATI LETTER RA;Lo;0;L;;;;;N;;;;; -0AB2;GUJARATI LETTER LA;Lo;0;L;;;;;N;;;;; -0AB3;GUJARATI LETTER LLA;Lo;0;L;;;;;N;;;;; -0AB5;GUJARATI LETTER VA;Lo;0;L;;;;;N;;;;; -0AB6;GUJARATI LETTER SHA;Lo;0;L;;;;;N;;;;; -0AB7;GUJARATI LETTER SSA;Lo;0;L;;;;;N;;;;; -0AB8;GUJARATI LETTER SA;Lo;0;L;;;;;N;;;;; -0AB9;GUJARATI LETTER HA;Lo;0;L;;;;;N;;;;; -0ABC;GUJARATI SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -0ABD;GUJARATI SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -0ABE;GUJARATI VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0ABF;GUJARATI VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -0AC0;GUJARATI VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -0AC1;GUJARATI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -0AC2;GUJARATI VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -0AC3;GUJARATI VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -0AC4;GUJARATI VOWEL SIGN VOCALIC RR;Mn;0;NSM;;;;;N;;;;; -0AC5;GUJARATI VOWEL SIGN CANDRA E;Mn;0;NSM;;;;;N;;;;; -0AC7;GUJARATI VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -0AC8;GUJARATI VOWEL SIGN AI;Mn;0;NSM;;;;;N;;;;; -0AC9;GUJARATI VOWEL SIGN CANDRA O;Mc;0;L;;;;;N;;;;; -0ACB;GUJARATI VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -0ACC;GUJARATI VOWEL SIGN AU;Mc;0;L;;;;;N;;;;; -0ACD;GUJARATI SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0AD0;GUJARATI OM;Lo;0;L;;;;;N;;;;; -0AE0;GUJARATI LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0AE1;GUJARATI LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0AE2;GUJARATI VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0AE3;GUJARATI VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0AE6;GUJARATI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0AE7;GUJARATI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0AE8;GUJARATI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0AE9;GUJARATI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0AEA;GUJARATI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0AEB;GUJARATI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0AEC;GUJARATI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0AED;GUJARATI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0AEE;GUJARATI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0AEF;GUJARATI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0AF1;GUJARATI RUPEE SIGN;Sc;0;ET;;;;;N;;;;; -0B01;ORIYA SIGN CANDRABINDU;Mn;0;NSM;;;;;N;;;;; -0B02;ORIYA SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -0B03;ORIYA SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0B05;ORIYA LETTER A;Lo;0;L;;;;;N;;;;; -0B06;ORIYA LETTER AA;Lo;0;L;;;;;N;;;;; -0B07;ORIYA LETTER I;Lo;0;L;;;;;N;;;;; -0B08;ORIYA LETTER II;Lo;0;L;;;;;N;;;;; -0B09;ORIYA LETTER U;Lo;0;L;;;;;N;;;;; -0B0A;ORIYA LETTER UU;Lo;0;L;;;;;N;;;;; -0B0B;ORIYA LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -0B0C;ORIYA LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -0B0F;ORIYA LETTER E;Lo;0;L;;;;;N;;;;; -0B10;ORIYA LETTER AI;Lo;0;L;;;;;N;;;;; -0B13;ORIYA LETTER O;Lo;0;L;;;;;N;;;;; -0B14;ORIYA LETTER AU;Lo;0;L;;;;;N;;;;; -0B15;ORIYA LETTER KA;Lo;0;L;;;;;N;;;;; -0B16;ORIYA LETTER KHA;Lo;0;L;;;;;N;;;;; -0B17;ORIYA LETTER GA;Lo;0;L;;;;;N;;;;; -0B18;ORIYA LETTER GHA;Lo;0;L;;;;;N;;;;; -0B19;ORIYA LETTER NGA;Lo;0;L;;;;;N;;;;; -0B1A;ORIYA LETTER CA;Lo;0;L;;;;;N;;;;; -0B1B;ORIYA LETTER CHA;Lo;0;L;;;;;N;;;;; -0B1C;ORIYA LETTER JA;Lo;0;L;;;;;N;;;;; -0B1D;ORIYA LETTER JHA;Lo;0;L;;;;;N;;;;; -0B1E;ORIYA LETTER NYA;Lo;0;L;;;;;N;;;;; -0B1F;ORIYA LETTER TTA;Lo;0;L;;;;;N;;;;; -0B20;ORIYA LETTER TTHA;Lo;0;L;;;;;N;;;;; -0B21;ORIYA LETTER DDA;Lo;0;L;;;;;N;;;;; -0B22;ORIYA LETTER DDHA;Lo;0;L;;;;;N;;;;; -0B23;ORIYA LETTER NNA;Lo;0;L;;;;;N;;;;; -0B24;ORIYA LETTER TA;Lo;0;L;;;;;N;;;;; -0B25;ORIYA LETTER THA;Lo;0;L;;;;;N;;;;; -0B26;ORIYA LETTER DA;Lo;0;L;;;;;N;;;;; -0B27;ORIYA LETTER DHA;Lo;0;L;;;;;N;;;;; -0B28;ORIYA LETTER NA;Lo;0;L;;;;;N;;;;; -0B2A;ORIYA LETTER PA;Lo;0;L;;;;;N;;;;; -0B2B;ORIYA LETTER PHA;Lo;0;L;;;;;N;;;;; -0B2C;ORIYA LETTER BA;Lo;0;L;;;;;N;;;;; -0B2D;ORIYA LETTER BHA;Lo;0;L;;;;;N;;;;; -0B2E;ORIYA LETTER MA;Lo;0;L;;;;;N;;;;; -0B2F;ORIYA LETTER YA;Lo;0;L;;;;;N;;;;; -0B30;ORIYA LETTER RA;Lo;0;L;;;;;N;;;;; -0B32;ORIYA LETTER LA;Lo;0;L;;;;;N;;;;; -0B33;ORIYA LETTER LLA;Lo;0;L;;;;;N;;;;; -0B35;ORIYA LETTER VA;Lo;0;L;;;;;N;;;;; -0B36;ORIYA LETTER SHA;Lo;0;L;;;;;N;;;;; -0B37;ORIYA LETTER SSA;Lo;0;L;;;;;N;;;;; -0B38;ORIYA LETTER SA;Lo;0;L;;;;;N;;;;; -0B39;ORIYA LETTER HA;Lo;0;L;;;;;N;;;;; -0B3C;ORIYA SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -0B3D;ORIYA SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -0B3E;ORIYA VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0B3F;ORIYA VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -0B40;ORIYA VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -0B41;ORIYA VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -0B42;ORIYA VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -0B43;ORIYA VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -0B44;ORIYA VOWEL SIGN VOCALIC RR;Mn;0;NSM;;;;;N;;;;; -0B47;ORIYA VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -0B48;ORIYA VOWEL SIGN AI;Mc;0;L;0B47 0B56;;;;N;;;;; -0B4B;ORIYA VOWEL SIGN O;Mc;0;L;0B47 0B3E;;;;N;;;;; -0B4C;ORIYA VOWEL SIGN AU;Mc;0;L;0B47 0B57;;;;N;;;;; -0B4D;ORIYA SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0B56;ORIYA AI LENGTH MARK;Mn;0;NSM;;;;;N;;;;; -0B57;ORIYA AU LENGTH MARK;Mc;0;L;;;;;N;;;;; -0B5C;ORIYA LETTER RRA;Lo;0;L;0B21 0B3C;;;;N;;;;; -0B5D;ORIYA LETTER RHA;Lo;0;L;0B22 0B3C;;;;N;;;;; -0B5F;ORIYA LETTER YYA;Lo;0;L;;;;;N;;;;; -0B60;ORIYA LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0B61;ORIYA LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0B62;ORIYA VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0B63;ORIYA VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0B66;ORIYA DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0B67;ORIYA DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0B68;ORIYA DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0B69;ORIYA DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0B6A;ORIYA DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0B6B;ORIYA DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0B6C;ORIYA DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0B6D;ORIYA DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0B6E;ORIYA DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0B6F;ORIYA DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0B70;ORIYA ISSHAR;So;0;L;;;;;N;;;;; -0B71;ORIYA LETTER WA;Lo;0;L;;;;;N;;;;; -0B82;TAMIL SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -0B83;TAMIL SIGN VISARGA;Lo;0;L;;;;;N;;;;; -0B85;TAMIL LETTER A;Lo;0;L;;;;;N;;;;; -0B86;TAMIL LETTER AA;Lo;0;L;;;;;N;;;;; -0B87;TAMIL LETTER I;Lo;0;L;;;;;N;;;;; -0B88;TAMIL LETTER II;Lo;0;L;;;;;N;;;;; -0B89;TAMIL LETTER U;Lo;0;L;;;;;N;;;;; -0B8A;TAMIL LETTER UU;Lo;0;L;;;;;N;;;;; -0B8E;TAMIL LETTER E;Lo;0;L;;;;;N;;;;; -0B8F;TAMIL LETTER EE;Lo;0;L;;;;;N;;;;; -0B90;TAMIL LETTER AI;Lo;0;L;;;;;N;;;;; -0B92;TAMIL LETTER O;Lo;0;L;;;;;N;;;;; -0B93;TAMIL LETTER OO;Lo;0;L;;;;;N;;;;; -0B94;TAMIL LETTER AU;Lo;0;L;0B92 0BD7;;;;N;;;;; -0B95;TAMIL LETTER KA;Lo;0;L;;;;;N;;;;; -0B99;TAMIL LETTER NGA;Lo;0;L;;;;;N;;;;; -0B9A;TAMIL LETTER CA;Lo;0;L;;;;;N;;;;; -0B9C;TAMIL LETTER JA;Lo;0;L;;;;;N;;;;; -0B9E;TAMIL LETTER NYA;Lo;0;L;;;;;N;;;;; -0B9F;TAMIL LETTER TTA;Lo;0;L;;;;;N;;;;; -0BA3;TAMIL LETTER NNA;Lo;0;L;;;;;N;;;;; -0BA4;TAMIL LETTER TA;Lo;0;L;;;;;N;;;;; -0BA8;TAMIL LETTER NA;Lo;0;L;;;;;N;;;;; -0BA9;TAMIL LETTER NNNA;Lo;0;L;;;;;N;;;;; -0BAA;TAMIL LETTER PA;Lo;0;L;;;;;N;;;;; -0BAE;TAMIL LETTER MA;Lo;0;L;;;;;N;;;;; -0BAF;TAMIL LETTER YA;Lo;0;L;;;;;N;;;;; -0BB0;TAMIL LETTER RA;Lo;0;L;;;;;N;;;;; -0BB1;TAMIL LETTER RRA;Lo;0;L;;;;;N;;;;; -0BB2;TAMIL LETTER LA;Lo;0;L;;;;;N;;;;; -0BB3;TAMIL LETTER LLA;Lo;0;L;;;;;N;;;;; -0BB4;TAMIL LETTER LLLA;Lo;0;L;;;;;N;;;;; -0BB5;TAMIL LETTER VA;Lo;0;L;;;;;N;;;;; -0BB6;TAMIL LETTER SHA;Lo;0;L;;;;;N;;;;; -0BB7;TAMIL LETTER SSA;Lo;0;L;;;;;N;;;;; -0BB8;TAMIL LETTER SA;Lo;0;L;;;;;N;;;;; -0BB9;TAMIL LETTER HA;Lo;0;L;;;;;N;;;;; -0BBE;TAMIL VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0BBF;TAMIL VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -0BC0;TAMIL VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -0BC1;TAMIL VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -0BC2;TAMIL VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -0BC6;TAMIL VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -0BC7;TAMIL VOWEL SIGN EE;Mc;0;L;;;;;N;;;;; -0BC8;TAMIL VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -0BCA;TAMIL VOWEL SIGN O;Mc;0;L;0BC6 0BBE;;;;N;;;;; -0BCB;TAMIL VOWEL SIGN OO;Mc;0;L;0BC7 0BBE;;;;N;;;;; -0BCC;TAMIL VOWEL SIGN AU;Mc;0;L;0BC6 0BD7;;;;N;;;;; -0BCD;TAMIL SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0BD0;TAMIL OM;Lo;0;L;;;;;N;;;;; -0BD7;TAMIL AU LENGTH MARK;Mc;0;L;;;;;N;;;;; -0BE6;TAMIL DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0BE7;TAMIL DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0BE8;TAMIL DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0BE9;TAMIL DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0BEA;TAMIL DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0BEB;TAMIL DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0BEC;TAMIL DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0BED;TAMIL DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0BEE;TAMIL DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0BEF;TAMIL DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0BF0;TAMIL NUMBER TEN;No;0;L;;;;10;N;;;;; -0BF1;TAMIL NUMBER ONE HUNDRED;No;0;L;;;;100;N;;;;; -0BF2;TAMIL NUMBER ONE THOUSAND;No;0;L;;;;1000;N;;;;; -0BF3;TAMIL DAY SIGN;So;0;ON;;;;;N;;Naal;;; -0BF4;TAMIL MONTH SIGN;So;0;ON;;;;;N;;Maatham;;; -0BF5;TAMIL YEAR SIGN;So;0;ON;;;;;N;;Varudam;;; -0BF6;TAMIL DEBIT SIGN;So;0;ON;;;;;N;;Patru;;; -0BF7;TAMIL CREDIT SIGN;So;0;ON;;;;;N;;Varavu;;; -0BF8;TAMIL AS ABOVE SIGN;So;0;ON;;;;;N;;Merpadi;;; -0BF9;TAMIL RUPEE SIGN;Sc;0;ET;;;;;N;;Rupai;;; -0BFA;TAMIL NUMBER SIGN;So;0;ON;;;;;N;;Enn;;; -0C01;TELUGU SIGN CANDRABINDU;Mc;0;L;;;;;N;;;;; -0C02;TELUGU SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -0C03;TELUGU SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0C05;TELUGU LETTER A;Lo;0;L;;;;;N;;;;; -0C06;TELUGU LETTER AA;Lo;0;L;;;;;N;;;;; -0C07;TELUGU LETTER I;Lo;0;L;;;;;N;;;;; -0C08;TELUGU LETTER II;Lo;0;L;;;;;N;;;;; -0C09;TELUGU LETTER U;Lo;0;L;;;;;N;;;;; -0C0A;TELUGU LETTER UU;Lo;0;L;;;;;N;;;;; -0C0B;TELUGU LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -0C0C;TELUGU LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -0C0E;TELUGU LETTER E;Lo;0;L;;;;;N;;;;; -0C0F;TELUGU LETTER EE;Lo;0;L;;;;;N;;;;; -0C10;TELUGU LETTER AI;Lo;0;L;;;;;N;;;;; -0C12;TELUGU LETTER O;Lo;0;L;;;;;N;;;;; -0C13;TELUGU LETTER OO;Lo;0;L;;;;;N;;;;; -0C14;TELUGU LETTER AU;Lo;0;L;;;;;N;;;;; -0C15;TELUGU LETTER KA;Lo;0;L;;;;;N;;;;; -0C16;TELUGU LETTER KHA;Lo;0;L;;;;;N;;;;; -0C17;TELUGU LETTER GA;Lo;0;L;;;;;N;;;;; -0C18;TELUGU LETTER GHA;Lo;0;L;;;;;N;;;;; -0C19;TELUGU LETTER NGA;Lo;0;L;;;;;N;;;;; -0C1A;TELUGU LETTER CA;Lo;0;L;;;;;N;;;;; -0C1B;TELUGU LETTER CHA;Lo;0;L;;;;;N;;;;; -0C1C;TELUGU LETTER JA;Lo;0;L;;;;;N;;;;; -0C1D;TELUGU LETTER JHA;Lo;0;L;;;;;N;;;;; -0C1E;TELUGU LETTER NYA;Lo;0;L;;;;;N;;;;; -0C1F;TELUGU LETTER TTA;Lo;0;L;;;;;N;;;;; -0C20;TELUGU LETTER TTHA;Lo;0;L;;;;;N;;;;; -0C21;TELUGU LETTER DDA;Lo;0;L;;;;;N;;;;; -0C22;TELUGU LETTER DDHA;Lo;0;L;;;;;N;;;;; -0C23;TELUGU LETTER NNA;Lo;0;L;;;;;N;;;;; -0C24;TELUGU LETTER TA;Lo;0;L;;;;;N;;;;; -0C25;TELUGU LETTER THA;Lo;0;L;;;;;N;;;;; -0C26;TELUGU LETTER DA;Lo;0;L;;;;;N;;;;; -0C27;TELUGU LETTER DHA;Lo;0;L;;;;;N;;;;; -0C28;TELUGU LETTER NA;Lo;0;L;;;;;N;;;;; -0C2A;TELUGU LETTER PA;Lo;0;L;;;;;N;;;;; -0C2B;TELUGU LETTER PHA;Lo;0;L;;;;;N;;;;; -0C2C;TELUGU LETTER BA;Lo;0;L;;;;;N;;;;; -0C2D;TELUGU LETTER BHA;Lo;0;L;;;;;N;;;;; -0C2E;TELUGU LETTER MA;Lo;0;L;;;;;N;;;;; -0C2F;TELUGU LETTER YA;Lo;0;L;;;;;N;;;;; -0C30;TELUGU LETTER RA;Lo;0;L;;;;;N;;;;; -0C31;TELUGU LETTER RRA;Lo;0;L;;;;;N;;;;; -0C32;TELUGU LETTER LA;Lo;0;L;;;;;N;;;;; -0C33;TELUGU LETTER LLA;Lo;0;L;;;;;N;;;;; -0C35;TELUGU LETTER VA;Lo;0;L;;;;;N;;;;; -0C36;TELUGU LETTER SHA;Lo;0;L;;;;;N;;;;; -0C37;TELUGU LETTER SSA;Lo;0;L;;;;;N;;;;; -0C38;TELUGU LETTER SA;Lo;0;L;;;;;N;;;;; -0C39;TELUGU LETTER HA;Lo;0;L;;;;;N;;;;; -0C3D;TELUGU SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -0C3E;TELUGU VOWEL SIGN AA;Mn;0;NSM;;;;;N;;;;; -0C3F;TELUGU VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -0C40;TELUGU VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -0C41;TELUGU VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -0C42;TELUGU VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -0C43;TELUGU VOWEL SIGN VOCALIC R;Mc;0;L;;;;;N;;;;; -0C44;TELUGU VOWEL SIGN VOCALIC RR;Mc;0;L;;;;;N;;;;; -0C46;TELUGU VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -0C47;TELUGU VOWEL SIGN EE;Mn;0;NSM;;;;;N;;;;; -0C48;TELUGU VOWEL SIGN AI;Mn;0;NSM;0C46 0C56;;;;N;;;;; -0C4A;TELUGU VOWEL SIGN O;Mn;0;NSM;;;;;N;;;;; -0C4B;TELUGU VOWEL SIGN OO;Mn;0;NSM;;;;;N;;;;; -0C4C;TELUGU VOWEL SIGN AU;Mn;0;NSM;;;;;N;;;;; -0C4D;TELUGU SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0C55;TELUGU LENGTH MARK;Mn;84;NSM;;;;;N;;;;; -0C56;TELUGU AI LENGTH MARK;Mn;91;NSM;;;;;N;;;;; -0C58;TELUGU LETTER TSA;Lo;0;L;;;;;N;;;;; -0C59;TELUGU LETTER DZA;Lo;0;L;;;;;N;;;;; -0C60;TELUGU LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0C61;TELUGU LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0C62;TELUGU VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0C63;TELUGU VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0C66;TELUGU DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0C67;TELUGU DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0C68;TELUGU DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0C69;TELUGU DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0C6A;TELUGU DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0C6B;TELUGU DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0C6C;TELUGU DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0C6D;TELUGU DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0C6E;TELUGU DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0C6F;TELUGU DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0C78;TELUGU FRACTION DIGIT ZERO FOR ODD POWERS OF FOUR;No;0;ON;;;;0;N;;;;; -0C79;TELUGU FRACTION DIGIT ONE FOR ODD POWERS OF FOUR;No;0;ON;;;;1;N;;;;; -0C7A;TELUGU FRACTION DIGIT TWO FOR ODD POWERS OF FOUR;No;0;ON;;;;2;N;;;;; -0C7B;TELUGU FRACTION DIGIT THREE FOR ODD POWERS OF FOUR;No;0;ON;;;;3;N;;;;; -0C7C;TELUGU FRACTION DIGIT ONE FOR EVEN POWERS OF FOUR;No;0;ON;;;;1;N;;;;; -0C7D;TELUGU FRACTION DIGIT TWO FOR EVEN POWERS OF FOUR;No;0;ON;;;;2;N;;;;; -0C7E;TELUGU FRACTION DIGIT THREE FOR EVEN POWERS OF FOUR;No;0;ON;;;;3;N;;;;; -0C7F;TELUGU SIGN TUUMU;So;0;L;;;;;N;;;;; -0C82;KANNADA SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -0C83;KANNADA SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0C85;KANNADA LETTER A;Lo;0;L;;;;;N;;;;; -0C86;KANNADA LETTER AA;Lo;0;L;;;;;N;;;;; -0C87;KANNADA LETTER I;Lo;0;L;;;;;N;;;;; -0C88;KANNADA LETTER II;Lo;0;L;;;;;N;;;;; -0C89;KANNADA LETTER U;Lo;0;L;;;;;N;;;;; -0C8A;KANNADA LETTER UU;Lo;0;L;;;;;N;;;;; -0C8B;KANNADA LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -0C8C;KANNADA LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -0C8E;KANNADA LETTER E;Lo;0;L;;;;;N;;;;; -0C8F;KANNADA LETTER EE;Lo;0;L;;;;;N;;;;; -0C90;KANNADA LETTER AI;Lo;0;L;;;;;N;;;;; -0C92;KANNADA LETTER O;Lo;0;L;;;;;N;;;;; -0C93;KANNADA LETTER OO;Lo;0;L;;;;;N;;;;; -0C94;KANNADA LETTER AU;Lo;0;L;;;;;N;;;;; -0C95;KANNADA LETTER KA;Lo;0;L;;;;;N;;;;; -0C96;KANNADA LETTER KHA;Lo;0;L;;;;;N;;;;; -0C97;KANNADA LETTER GA;Lo;0;L;;;;;N;;;;; -0C98;KANNADA LETTER GHA;Lo;0;L;;;;;N;;;;; -0C99;KANNADA LETTER NGA;Lo;0;L;;;;;N;;;;; -0C9A;KANNADA LETTER CA;Lo;0;L;;;;;N;;;;; -0C9B;KANNADA LETTER CHA;Lo;0;L;;;;;N;;;;; -0C9C;KANNADA LETTER JA;Lo;0;L;;;;;N;;;;; -0C9D;KANNADA LETTER JHA;Lo;0;L;;;;;N;;;;; -0C9E;KANNADA LETTER NYA;Lo;0;L;;;;;N;;;;; -0C9F;KANNADA LETTER TTA;Lo;0;L;;;;;N;;;;; -0CA0;KANNADA LETTER TTHA;Lo;0;L;;;;;N;;;;; -0CA1;KANNADA LETTER DDA;Lo;0;L;;;;;N;;;;; -0CA2;KANNADA LETTER DDHA;Lo;0;L;;;;;N;;;;; -0CA3;KANNADA LETTER NNA;Lo;0;L;;;;;N;;;;; -0CA4;KANNADA LETTER TA;Lo;0;L;;;;;N;;;;; -0CA5;KANNADA LETTER THA;Lo;0;L;;;;;N;;;;; -0CA6;KANNADA LETTER DA;Lo;0;L;;;;;N;;;;; -0CA7;KANNADA LETTER DHA;Lo;0;L;;;;;N;;;;; -0CA8;KANNADA LETTER NA;Lo;0;L;;;;;N;;;;; -0CAA;KANNADA LETTER PA;Lo;0;L;;;;;N;;;;; -0CAB;KANNADA LETTER PHA;Lo;0;L;;;;;N;;;;; -0CAC;KANNADA LETTER BA;Lo;0;L;;;;;N;;;;; -0CAD;KANNADA LETTER BHA;Lo;0;L;;;;;N;;;;; -0CAE;KANNADA LETTER MA;Lo;0;L;;;;;N;;;;; -0CAF;KANNADA LETTER YA;Lo;0;L;;;;;N;;;;; -0CB0;KANNADA LETTER RA;Lo;0;L;;;;;N;;;;; -0CB1;KANNADA LETTER RRA;Lo;0;L;;;;;N;;;;; -0CB2;KANNADA LETTER LA;Lo;0;L;;;;;N;;;;; -0CB3;KANNADA LETTER LLA;Lo;0;L;;;;;N;;;;; -0CB5;KANNADA LETTER VA;Lo;0;L;;;;;N;;;;; -0CB6;KANNADA LETTER SHA;Lo;0;L;;;;;N;;;;; -0CB7;KANNADA LETTER SSA;Lo;0;L;;;;;N;;;;; -0CB8;KANNADA LETTER SA;Lo;0;L;;;;;N;;;;; -0CB9;KANNADA LETTER HA;Lo;0;L;;;;;N;;;;; -0CBC;KANNADA SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -0CBD;KANNADA SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -0CBE;KANNADA VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0CBF;KANNADA VOWEL SIGN I;Mn;0;L;;;;;N;;;;; -0CC0;KANNADA VOWEL SIGN II;Mc;0;L;0CBF 0CD5;;;;N;;;;; -0CC1;KANNADA VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -0CC2;KANNADA VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -0CC3;KANNADA VOWEL SIGN VOCALIC R;Mc;0;L;;;;;N;;;;; -0CC4;KANNADA VOWEL SIGN VOCALIC RR;Mc;0;L;;;;;N;;;;; -0CC6;KANNADA VOWEL SIGN E;Mn;0;L;;;;;N;;;;; -0CC7;KANNADA VOWEL SIGN EE;Mc;0;L;0CC6 0CD5;;;;N;;;;; -0CC8;KANNADA VOWEL SIGN AI;Mc;0;L;0CC6 0CD6;;;;N;;;;; -0CCA;KANNADA VOWEL SIGN O;Mc;0;L;0CC6 0CC2;;;;N;;;;; -0CCB;KANNADA VOWEL SIGN OO;Mc;0;L;0CCA 0CD5;;;;N;;;;; -0CCC;KANNADA VOWEL SIGN AU;Mn;0;NSM;;;;;N;;;;; -0CCD;KANNADA SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0CD5;KANNADA LENGTH MARK;Mc;0;L;;;;;N;;;;; -0CD6;KANNADA AI LENGTH MARK;Mc;0;L;;;;;N;;;;; -0CDE;KANNADA LETTER FA;Lo;0;L;;;;;N;;;;; -0CE0;KANNADA LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0CE1;KANNADA LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0CE2;KANNADA VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0CE3;KANNADA VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0CE6;KANNADA DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0CE7;KANNADA DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0CE8;KANNADA DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0CE9;KANNADA DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0CEA;KANNADA DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0CEB;KANNADA DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0CEC;KANNADA DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0CED;KANNADA DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0CEE;KANNADA DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0CEF;KANNADA DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0CF1;KANNADA SIGN JIHVAMULIYA;So;0;ON;;;;;N;;;;; -0CF2;KANNADA SIGN UPADHMANIYA;So;0;ON;;;;;N;;;;; -0D02;MALAYALAM SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -0D03;MALAYALAM SIGN VISARGA;Mc;0;L;;;;;N;;;;; -0D05;MALAYALAM LETTER A;Lo;0;L;;;;;N;;;;; -0D06;MALAYALAM LETTER AA;Lo;0;L;;;;;N;;;;; -0D07;MALAYALAM LETTER I;Lo;0;L;;;;;N;;;;; -0D08;MALAYALAM LETTER II;Lo;0;L;;;;;N;;;;; -0D09;MALAYALAM LETTER U;Lo;0;L;;;;;N;;;;; -0D0A;MALAYALAM LETTER UU;Lo;0;L;;;;;N;;;;; -0D0B;MALAYALAM LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -0D0C;MALAYALAM LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -0D0E;MALAYALAM LETTER E;Lo;0;L;;;;;N;;;;; -0D0F;MALAYALAM LETTER EE;Lo;0;L;;;;;N;;;;; -0D10;MALAYALAM LETTER AI;Lo;0;L;;;;;N;;;;; -0D12;MALAYALAM LETTER O;Lo;0;L;;;;;N;;;;; -0D13;MALAYALAM LETTER OO;Lo;0;L;;;;;N;;;;; -0D14;MALAYALAM LETTER AU;Lo;0;L;;;;;N;;;;; -0D15;MALAYALAM LETTER KA;Lo;0;L;;;;;N;;;;; -0D16;MALAYALAM LETTER KHA;Lo;0;L;;;;;N;;;;; -0D17;MALAYALAM LETTER GA;Lo;0;L;;;;;N;;;;; -0D18;MALAYALAM LETTER GHA;Lo;0;L;;;;;N;;;;; -0D19;MALAYALAM LETTER NGA;Lo;0;L;;;;;N;;;;; -0D1A;MALAYALAM LETTER CA;Lo;0;L;;;;;N;;;;; -0D1B;MALAYALAM LETTER CHA;Lo;0;L;;;;;N;;;;; -0D1C;MALAYALAM LETTER JA;Lo;0;L;;;;;N;;;;; -0D1D;MALAYALAM LETTER JHA;Lo;0;L;;;;;N;;;;; -0D1E;MALAYALAM LETTER NYA;Lo;0;L;;;;;N;;;;; -0D1F;MALAYALAM LETTER TTA;Lo;0;L;;;;;N;;;;; -0D20;MALAYALAM LETTER TTHA;Lo;0;L;;;;;N;;;;; -0D21;MALAYALAM LETTER DDA;Lo;0;L;;;;;N;;;;; -0D22;MALAYALAM LETTER DDHA;Lo;0;L;;;;;N;;;;; -0D23;MALAYALAM LETTER NNA;Lo;0;L;;;;;N;;;;; -0D24;MALAYALAM LETTER TA;Lo;0;L;;;;;N;;;;; -0D25;MALAYALAM LETTER THA;Lo;0;L;;;;;N;;;;; -0D26;MALAYALAM LETTER DA;Lo;0;L;;;;;N;;;;; -0D27;MALAYALAM LETTER DHA;Lo;0;L;;;;;N;;;;; -0D28;MALAYALAM LETTER NA;Lo;0;L;;;;;N;;;;; -0D2A;MALAYALAM LETTER PA;Lo;0;L;;;;;N;;;;; -0D2B;MALAYALAM LETTER PHA;Lo;0;L;;;;;N;;;;; -0D2C;MALAYALAM LETTER BA;Lo;0;L;;;;;N;;;;; -0D2D;MALAYALAM LETTER BHA;Lo;0;L;;;;;N;;;;; -0D2E;MALAYALAM LETTER MA;Lo;0;L;;;;;N;;;;; -0D2F;MALAYALAM LETTER YA;Lo;0;L;;;;;N;;;;; -0D30;MALAYALAM LETTER RA;Lo;0;L;;;;;N;;;;; -0D31;MALAYALAM LETTER RRA;Lo;0;L;;;;;N;;;;; -0D32;MALAYALAM LETTER LA;Lo;0;L;;;;;N;;;;; -0D33;MALAYALAM LETTER LLA;Lo;0;L;;;;;N;;;;; -0D34;MALAYALAM LETTER LLLA;Lo;0;L;;;;;N;;;;; -0D35;MALAYALAM LETTER VA;Lo;0;L;;;;;N;;;;; -0D36;MALAYALAM LETTER SHA;Lo;0;L;;;;;N;;;;; -0D37;MALAYALAM LETTER SSA;Lo;0;L;;;;;N;;;;; -0D38;MALAYALAM LETTER SA;Lo;0;L;;;;;N;;;;; -0D39;MALAYALAM LETTER HA;Lo;0;L;;;;;N;;;;; -0D3D;MALAYALAM SIGN AVAGRAHA;Lo;0;L;;;;;N;;;;; -0D3E;MALAYALAM VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -0D3F;MALAYALAM VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -0D40;MALAYALAM VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -0D41;MALAYALAM VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -0D42;MALAYALAM VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -0D43;MALAYALAM VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -0D44;MALAYALAM VOWEL SIGN VOCALIC RR;Mn;0;NSM;;;;;N;;;;; -0D46;MALAYALAM VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -0D47;MALAYALAM VOWEL SIGN EE;Mc;0;L;;;;;N;;;;; -0D48;MALAYALAM VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -0D4A;MALAYALAM VOWEL SIGN O;Mc;0;L;0D46 0D3E;;;;N;;;;; -0D4B;MALAYALAM VOWEL SIGN OO;Mc;0;L;0D47 0D3E;;;;N;;;;; -0D4C;MALAYALAM VOWEL SIGN AU;Mc;0;L;0D46 0D57;;;;N;;;;; -0D4D;MALAYALAM SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -0D57;MALAYALAM AU LENGTH MARK;Mc;0;L;;;;;N;;;;; -0D60;MALAYALAM LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -0D61;MALAYALAM LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -0D62;MALAYALAM VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -0D63;MALAYALAM VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -0D66;MALAYALAM DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0D67;MALAYALAM DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0D68;MALAYALAM DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0D69;MALAYALAM DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0D6A;MALAYALAM DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0D6B;MALAYALAM DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0D6C;MALAYALAM DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0D6D;MALAYALAM DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0D6E;MALAYALAM DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0D6F;MALAYALAM DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0D70;MALAYALAM NUMBER TEN;No;0;L;;;;10;N;;;;; -0D71;MALAYALAM NUMBER ONE HUNDRED;No;0;L;;;;100;N;;;;; -0D72;MALAYALAM NUMBER ONE THOUSAND;No;0;L;;;;1000;N;;;;; -0D73;MALAYALAM FRACTION ONE QUARTER;No;0;L;;;;1/4;N;;;;; -0D74;MALAYALAM FRACTION ONE HALF;No;0;L;;;;1/2;N;;;;; -0D75;MALAYALAM FRACTION THREE QUARTERS;No;0;L;;;;3/4;N;;;;; -0D79;MALAYALAM DATE MARK;So;0;L;;;;;N;;;;; -0D7A;MALAYALAM LETTER CHILLU NN;Lo;0;L;;;;;N;;;;; -0D7B;MALAYALAM LETTER CHILLU N;Lo;0;L;;;;;N;;;;; -0D7C;MALAYALAM LETTER CHILLU RR;Lo;0;L;;;;;N;;;;; -0D7D;MALAYALAM LETTER CHILLU L;Lo;0;L;;;;;N;;;;; -0D7E;MALAYALAM LETTER CHILLU LL;Lo;0;L;;;;;N;;;;; -0D7F;MALAYALAM LETTER CHILLU K;Lo;0;L;;;;;N;;;;; -0D82;SINHALA SIGN ANUSVARAYA;Mc;0;L;;;;;N;;;;; -0D83;SINHALA SIGN VISARGAYA;Mc;0;L;;;;;N;;;;; -0D85;SINHALA LETTER AYANNA;Lo;0;L;;;;;N;;;;; -0D86;SINHALA LETTER AAYANNA;Lo;0;L;;;;;N;;;;; -0D87;SINHALA LETTER AEYANNA;Lo;0;L;;;;;N;;;;; -0D88;SINHALA LETTER AEEYANNA;Lo;0;L;;;;;N;;;;; -0D89;SINHALA LETTER IYANNA;Lo;0;L;;;;;N;;;;; -0D8A;SINHALA LETTER IIYANNA;Lo;0;L;;;;;N;;;;; -0D8B;SINHALA LETTER UYANNA;Lo;0;L;;;;;N;;;;; -0D8C;SINHALA LETTER UUYANNA;Lo;0;L;;;;;N;;;;; -0D8D;SINHALA LETTER IRUYANNA;Lo;0;L;;;;;N;;;;; -0D8E;SINHALA LETTER IRUUYANNA;Lo;0;L;;;;;N;;;;; -0D8F;SINHALA LETTER ILUYANNA;Lo;0;L;;;;;N;;;;; -0D90;SINHALA LETTER ILUUYANNA;Lo;0;L;;;;;N;;;;; -0D91;SINHALA LETTER EYANNA;Lo;0;L;;;;;N;;;;; -0D92;SINHALA LETTER EEYANNA;Lo;0;L;;;;;N;;;;; -0D93;SINHALA LETTER AIYANNA;Lo;0;L;;;;;N;;;;; -0D94;SINHALA LETTER OYANNA;Lo;0;L;;;;;N;;;;; -0D95;SINHALA LETTER OOYANNA;Lo;0;L;;;;;N;;;;; -0D96;SINHALA LETTER AUYANNA;Lo;0;L;;;;;N;;;;; -0D9A;SINHALA LETTER ALPAPRAANA KAYANNA;Lo;0;L;;;;;N;;;;; -0D9B;SINHALA LETTER MAHAAPRAANA KAYANNA;Lo;0;L;;;;;N;;;;; -0D9C;SINHALA LETTER ALPAPRAANA GAYANNA;Lo;0;L;;;;;N;;;;; -0D9D;SINHALA LETTER MAHAAPRAANA GAYANNA;Lo;0;L;;;;;N;;;;; -0D9E;SINHALA LETTER KANTAJA NAASIKYAYA;Lo;0;L;;;;;N;;;;; -0D9F;SINHALA LETTER SANYAKA GAYANNA;Lo;0;L;;;;;N;;;;; -0DA0;SINHALA LETTER ALPAPRAANA CAYANNA;Lo;0;L;;;;;N;;;;; -0DA1;SINHALA LETTER MAHAAPRAANA CAYANNA;Lo;0;L;;;;;N;;;;; -0DA2;SINHALA LETTER ALPAPRAANA JAYANNA;Lo;0;L;;;;;N;;;;; -0DA3;SINHALA LETTER MAHAAPRAANA JAYANNA;Lo;0;L;;;;;N;;;;; -0DA4;SINHALA LETTER TAALUJA NAASIKYAYA;Lo;0;L;;;;;N;;;;; -0DA5;SINHALA LETTER TAALUJA SANYOOGA NAAKSIKYAYA;Lo;0;L;;;;;N;;;;; -0DA6;SINHALA LETTER SANYAKA JAYANNA;Lo;0;L;;;;;N;;;;; -0DA7;SINHALA LETTER ALPAPRAANA TTAYANNA;Lo;0;L;;;;;N;;;;; -0DA8;SINHALA LETTER MAHAAPRAANA TTAYANNA;Lo;0;L;;;;;N;;;;; -0DA9;SINHALA LETTER ALPAPRAANA DDAYANNA;Lo;0;L;;;;;N;;;;; -0DAA;SINHALA LETTER MAHAAPRAANA DDAYANNA;Lo;0;L;;;;;N;;;;; -0DAB;SINHALA LETTER MUURDHAJA NAYANNA;Lo;0;L;;;;;N;;;;; -0DAC;SINHALA LETTER SANYAKA DDAYANNA;Lo;0;L;;;;;N;;;;; -0DAD;SINHALA LETTER ALPAPRAANA TAYANNA;Lo;0;L;;;;;N;;;;; -0DAE;SINHALA LETTER MAHAAPRAANA TAYANNA;Lo;0;L;;;;;N;;;;; -0DAF;SINHALA LETTER ALPAPRAANA DAYANNA;Lo;0;L;;;;;N;;;;; -0DB0;SINHALA LETTER MAHAAPRAANA DAYANNA;Lo;0;L;;;;;N;;;;; -0DB1;SINHALA LETTER DANTAJA NAYANNA;Lo;0;L;;;;;N;;;;; -0DB3;SINHALA LETTER SANYAKA DAYANNA;Lo;0;L;;;;;N;;;;; -0DB4;SINHALA LETTER ALPAPRAANA PAYANNA;Lo;0;L;;;;;N;;;;; -0DB5;SINHALA LETTER MAHAAPRAANA PAYANNA;Lo;0;L;;;;;N;;;;; -0DB6;SINHALA LETTER ALPAPRAANA BAYANNA;Lo;0;L;;;;;N;;;;; -0DB7;SINHALA LETTER MAHAAPRAANA BAYANNA;Lo;0;L;;;;;N;;;;; -0DB8;SINHALA LETTER MAYANNA;Lo;0;L;;;;;N;;;;; -0DB9;SINHALA LETTER AMBA BAYANNA;Lo;0;L;;;;;N;;;;; -0DBA;SINHALA LETTER YAYANNA;Lo;0;L;;;;;N;;;;; -0DBB;SINHALA LETTER RAYANNA;Lo;0;L;;;;;N;;;;; -0DBD;SINHALA LETTER DANTAJA LAYANNA;Lo;0;L;;;;;N;;;;; -0DC0;SINHALA LETTER VAYANNA;Lo;0;L;;;;;N;;;;; -0DC1;SINHALA LETTER TAALUJA SAYANNA;Lo;0;L;;;;;N;;;;; -0DC2;SINHALA LETTER MUURDHAJA SAYANNA;Lo;0;L;;;;;N;;;;; -0DC3;SINHALA LETTER DANTAJA SAYANNA;Lo;0;L;;;;;N;;;;; -0DC4;SINHALA LETTER HAYANNA;Lo;0;L;;;;;N;;;;; -0DC5;SINHALA LETTER MUURDHAJA LAYANNA;Lo;0;L;;;;;N;;;;; -0DC6;SINHALA LETTER FAYANNA;Lo;0;L;;;;;N;;;;; -0DCA;SINHALA SIGN AL-LAKUNA;Mn;9;NSM;;;;;N;;;;; -0DCF;SINHALA VOWEL SIGN AELA-PILLA;Mc;0;L;;;;;N;;;;; -0DD0;SINHALA VOWEL SIGN KETTI AEDA-PILLA;Mc;0;L;;;;;N;;;;; -0DD1;SINHALA VOWEL SIGN DIGA AEDA-PILLA;Mc;0;L;;;;;N;;;;; -0DD2;SINHALA VOWEL SIGN KETTI IS-PILLA;Mn;0;NSM;;;;;N;;;;; -0DD3;SINHALA VOWEL SIGN DIGA IS-PILLA;Mn;0;NSM;;;;;N;;;;; -0DD4;SINHALA VOWEL SIGN KETTI PAA-PILLA;Mn;0;NSM;;;;;N;;;;; -0DD6;SINHALA VOWEL SIGN DIGA PAA-PILLA;Mn;0;NSM;;;;;N;;;;; -0DD8;SINHALA VOWEL SIGN GAETTA-PILLA;Mc;0;L;;;;;N;;;;; -0DD9;SINHALA VOWEL SIGN KOMBUVA;Mc;0;L;;;;;N;;;;; -0DDA;SINHALA VOWEL SIGN DIGA KOMBUVA;Mc;0;L;0DD9 0DCA;;;;N;;;;; -0DDB;SINHALA VOWEL SIGN KOMBU DEKA;Mc;0;L;;;;;N;;;;; -0DDC;SINHALA VOWEL SIGN KOMBUVA HAA AELA-PILLA;Mc;0;L;0DD9 0DCF;;;;N;;;;; -0DDD;SINHALA VOWEL SIGN KOMBUVA HAA DIGA AELA-PILLA;Mc;0;L;0DDC 0DCA;;;;N;;;;; -0DDE;SINHALA VOWEL SIGN KOMBUVA HAA GAYANUKITTA;Mc;0;L;0DD9 0DDF;;;;N;;;;; -0DDF;SINHALA VOWEL SIGN GAYANUKITTA;Mc;0;L;;;;;N;;;;; -0DF2;SINHALA VOWEL SIGN DIGA GAETTA-PILLA;Mc;0;L;;;;;N;;;;; -0DF3;SINHALA VOWEL SIGN DIGA GAYANUKITTA;Mc;0;L;;;;;N;;;;; -0DF4;SINHALA PUNCTUATION KUNDDALIYA;Po;0;L;;;;;N;;;;; -0E01;THAI CHARACTER KO KAI;Lo;0;L;;;;;N;THAI LETTER KO KAI;;;; -0E02;THAI CHARACTER KHO KHAI;Lo;0;L;;;;;N;THAI LETTER KHO KHAI;;;; -0E03;THAI CHARACTER KHO KHUAT;Lo;0;L;;;;;N;THAI LETTER KHO KHUAT;;;; -0E04;THAI CHARACTER KHO KHWAI;Lo;0;L;;;;;N;THAI LETTER KHO KHWAI;;;; -0E05;THAI CHARACTER KHO KHON;Lo;0;L;;;;;N;THAI LETTER KHO KHON;;;; -0E06;THAI CHARACTER KHO RAKHANG;Lo;0;L;;;;;N;THAI LETTER KHO RAKHANG;;;; -0E07;THAI CHARACTER NGO NGU;Lo;0;L;;;;;N;THAI LETTER NGO NGU;;;; -0E08;THAI CHARACTER CHO CHAN;Lo;0;L;;;;;N;THAI LETTER CHO CHAN;;;; -0E09;THAI CHARACTER CHO CHING;Lo;0;L;;;;;N;THAI LETTER CHO CHING;;;; -0E0A;THAI CHARACTER CHO CHANG;Lo;0;L;;;;;N;THAI LETTER CHO CHANG;;;; -0E0B;THAI CHARACTER SO SO;Lo;0;L;;;;;N;THAI LETTER SO SO;;;; -0E0C;THAI CHARACTER CHO CHOE;Lo;0;L;;;;;N;THAI LETTER CHO CHOE;;;; -0E0D;THAI CHARACTER YO YING;Lo;0;L;;;;;N;THAI LETTER YO YING;;;; -0E0E;THAI CHARACTER DO CHADA;Lo;0;L;;;;;N;THAI LETTER DO CHADA;;;; -0E0F;THAI CHARACTER TO PATAK;Lo;0;L;;;;;N;THAI LETTER TO PATAK;;;; -0E10;THAI CHARACTER THO THAN;Lo;0;L;;;;;N;THAI LETTER THO THAN;;;; -0E11;THAI CHARACTER THO NANGMONTHO;Lo;0;L;;;;;N;THAI LETTER THO NANGMONTHO;;;; -0E12;THAI CHARACTER THO PHUTHAO;Lo;0;L;;;;;N;THAI LETTER THO PHUTHAO;;;; -0E13;THAI CHARACTER NO NEN;Lo;0;L;;;;;N;THAI LETTER NO NEN;;;; -0E14;THAI CHARACTER DO DEK;Lo;0;L;;;;;N;THAI LETTER DO DEK;;;; -0E15;THAI CHARACTER TO TAO;Lo;0;L;;;;;N;THAI LETTER TO TAO;;;; -0E16;THAI CHARACTER THO THUNG;Lo;0;L;;;;;N;THAI LETTER THO THUNG;;;; -0E17;THAI CHARACTER THO THAHAN;Lo;0;L;;;;;N;THAI LETTER THO THAHAN;;;; -0E18;THAI CHARACTER THO THONG;Lo;0;L;;;;;N;THAI LETTER THO THONG;;;; -0E19;THAI CHARACTER NO NU;Lo;0;L;;;;;N;THAI LETTER NO NU;;;; -0E1A;THAI CHARACTER BO BAIMAI;Lo;0;L;;;;;N;THAI LETTER BO BAIMAI;;;; -0E1B;THAI CHARACTER PO PLA;Lo;0;L;;;;;N;THAI LETTER PO PLA;;;; -0E1C;THAI CHARACTER PHO PHUNG;Lo;0;L;;;;;N;THAI LETTER PHO PHUNG;;;; -0E1D;THAI CHARACTER FO FA;Lo;0;L;;;;;N;THAI LETTER FO FA;;;; -0E1E;THAI CHARACTER PHO PHAN;Lo;0;L;;;;;N;THAI LETTER PHO PHAN;;;; -0E1F;THAI CHARACTER FO FAN;Lo;0;L;;;;;N;THAI LETTER FO FAN;;;; -0E20;THAI CHARACTER PHO SAMPHAO;Lo;0;L;;;;;N;THAI LETTER PHO SAMPHAO;;;; -0E21;THAI CHARACTER MO MA;Lo;0;L;;;;;N;THAI LETTER MO MA;;;; -0E22;THAI CHARACTER YO YAK;Lo;0;L;;;;;N;THAI LETTER YO YAK;;;; -0E23;THAI CHARACTER RO RUA;Lo;0;L;;;;;N;THAI LETTER RO RUA;;;; -0E24;THAI CHARACTER RU;Lo;0;L;;;;;N;THAI LETTER RU;;;; -0E25;THAI CHARACTER LO LING;Lo;0;L;;;;;N;THAI LETTER LO LING;;;; -0E26;THAI CHARACTER LU;Lo;0;L;;;;;N;THAI LETTER LU;;;; -0E27;THAI CHARACTER WO WAEN;Lo;0;L;;;;;N;THAI LETTER WO WAEN;;;; -0E28;THAI CHARACTER SO SALA;Lo;0;L;;;;;N;THAI LETTER SO SALA;;;; -0E29;THAI CHARACTER SO RUSI;Lo;0;L;;;;;N;THAI LETTER SO RUSI;;;; -0E2A;THAI CHARACTER SO SUA;Lo;0;L;;;;;N;THAI LETTER SO SUA;;;; -0E2B;THAI CHARACTER HO HIP;Lo;0;L;;;;;N;THAI LETTER HO HIP;;;; -0E2C;THAI CHARACTER LO CHULA;Lo;0;L;;;;;N;THAI LETTER LO CHULA;;;; -0E2D;THAI CHARACTER O ANG;Lo;0;L;;;;;N;THAI LETTER O ANG;;;; -0E2E;THAI CHARACTER HO NOKHUK;Lo;0;L;;;;;N;THAI LETTER HO NOK HUK;;;; -0E2F;THAI CHARACTER PAIYANNOI;Lo;0;L;;;;;N;THAI PAI YAN NOI;paiyan noi;;; -0E30;THAI CHARACTER SARA A;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA A;;;; -0E31;THAI CHARACTER MAI HAN-AKAT;Mn;0;NSM;;;;;N;THAI VOWEL SIGN MAI HAN-AKAT;;;; -0E32;THAI CHARACTER SARA AA;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA AA;;;; -0E33;THAI CHARACTER SARA AM;Lo;0;L; 0E4D 0E32;;;;N;THAI VOWEL SIGN SARA AM;;;; -0E34;THAI CHARACTER SARA I;Mn;0;NSM;;;;;N;THAI VOWEL SIGN SARA I;;;; -0E35;THAI CHARACTER SARA II;Mn;0;NSM;;;;;N;THAI VOWEL SIGN SARA II;;;; -0E36;THAI CHARACTER SARA UE;Mn;0;NSM;;;;;N;THAI VOWEL SIGN SARA UE;;;; -0E37;THAI CHARACTER SARA UEE;Mn;0;NSM;;;;;N;THAI VOWEL SIGN SARA UEE;sara uue;;; -0E38;THAI CHARACTER SARA U;Mn;103;NSM;;;;;N;THAI VOWEL SIGN SARA U;;;; -0E39;THAI CHARACTER SARA UU;Mn;103;NSM;;;;;N;THAI VOWEL SIGN SARA UU;;;; -0E3A;THAI CHARACTER PHINTHU;Mn;9;NSM;;;;;N;THAI VOWEL SIGN PHINTHU;;;; -0E3F;THAI CURRENCY SYMBOL BAHT;Sc;0;ET;;;;;N;THAI BAHT SIGN;;;; -0E40;THAI CHARACTER SARA E;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA E;;;; -0E41;THAI CHARACTER SARA AE;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA AE;;;; -0E42;THAI CHARACTER SARA O;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA O;;;; -0E43;THAI CHARACTER SARA AI MAIMUAN;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA MAI MUAN;sara ai mai muan;;; -0E44;THAI CHARACTER SARA AI MAIMALAI;Lo;0;L;;;;;N;THAI VOWEL SIGN SARA MAI MALAI;sara ai mai malai;;; -0E45;THAI CHARACTER LAKKHANGYAO;Lo;0;L;;;;;N;THAI LAK KHANG YAO;lakkhang yao;;; -0E46;THAI CHARACTER MAIYAMOK;Lm;0;L;;;;;N;THAI MAI YAMOK;mai yamok;;; -0E47;THAI CHARACTER MAITAIKHU;Mn;0;NSM;;;;;N;THAI VOWEL SIGN MAI TAI KHU;mai taikhu;;; -0E48;THAI CHARACTER MAI EK;Mn;107;NSM;;;;;N;THAI TONE MAI EK;;;; -0E49;THAI CHARACTER MAI THO;Mn;107;NSM;;;;;N;THAI TONE MAI THO;;;; -0E4A;THAI CHARACTER MAI TRI;Mn;107;NSM;;;;;N;THAI TONE MAI TRI;;;; -0E4B;THAI CHARACTER MAI CHATTAWA;Mn;107;NSM;;;;;N;THAI TONE MAI CHATTAWA;;;; -0E4C;THAI CHARACTER THANTHAKHAT;Mn;0;NSM;;;;;N;THAI THANTHAKHAT;;;; -0E4D;THAI CHARACTER NIKHAHIT;Mn;0;NSM;;;;;N;THAI NIKKHAHIT;nikkhahit;;; -0E4E;THAI CHARACTER YAMAKKAN;Mn;0;NSM;;;;;N;THAI YAMAKKAN;;;; -0E4F;THAI CHARACTER FONGMAN;Po;0;L;;;;;N;THAI FONGMAN;;;; -0E50;THAI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0E51;THAI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0E52;THAI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0E53;THAI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0E54;THAI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0E55;THAI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0E56;THAI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0E57;THAI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0E58;THAI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0E59;THAI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0E5A;THAI CHARACTER ANGKHANKHU;Po;0;L;;;;;N;THAI ANGKHANKHU;;;; -0E5B;THAI CHARACTER KHOMUT;Po;0;L;;;;;N;THAI KHOMUT;;;; -0E81;LAO LETTER KO;Lo;0;L;;;;;N;;;;; -0E82;LAO LETTER KHO SUNG;Lo;0;L;;;;;N;;;;; -0E84;LAO LETTER KHO TAM;Lo;0;L;;;;;N;;;;; -0E87;LAO LETTER NGO;Lo;0;L;;;;;N;;;;; -0E88;LAO LETTER CO;Lo;0;L;;;;;N;;;;; -0E8A;LAO LETTER SO TAM;Lo;0;L;;;;;N;;;;; -0E8D;LAO LETTER NYO;Lo;0;L;;;;;N;;;;; -0E94;LAO LETTER DO;Lo;0;L;;;;;N;;;;; -0E95;LAO LETTER TO;Lo;0;L;;;;;N;;;;; -0E96;LAO LETTER THO SUNG;Lo;0;L;;;;;N;;;;; -0E97;LAO LETTER THO TAM;Lo;0;L;;;;;N;;;;; -0E99;LAO LETTER NO;Lo;0;L;;;;;N;;;;; -0E9A;LAO LETTER BO;Lo;0;L;;;;;N;;;;; -0E9B;LAO LETTER PO;Lo;0;L;;;;;N;;;;; -0E9C;LAO LETTER PHO SUNG;Lo;0;L;;;;;N;;;;; -0E9D;LAO LETTER FO TAM;Lo;0;L;;;;;N;;;;; -0E9E;LAO LETTER PHO TAM;Lo;0;L;;;;;N;;;;; -0E9F;LAO LETTER FO SUNG;Lo;0;L;;;;;N;;;;; -0EA1;LAO LETTER MO;Lo;0;L;;;;;N;;;;; -0EA2;LAO LETTER YO;Lo;0;L;;;;;N;;;;; -0EA3;LAO LETTER LO LING;Lo;0;L;;;;;N;;;;; -0EA5;LAO LETTER LO LOOT;Lo;0;L;;;;;N;;;;; -0EA7;LAO LETTER WO;Lo;0;L;;;;;N;;;;; -0EAA;LAO LETTER SO SUNG;Lo;0;L;;;;;N;;;;; -0EAB;LAO LETTER HO SUNG;Lo;0;L;;;;;N;;;;; -0EAD;LAO LETTER O;Lo;0;L;;;;;N;;;;; -0EAE;LAO LETTER HO TAM;Lo;0;L;;;;;N;;;;; -0EAF;LAO ELLIPSIS;Lo;0;L;;;;;N;;;;; -0EB0;LAO VOWEL SIGN A;Lo;0;L;;;;;N;;;;; -0EB1;LAO VOWEL SIGN MAI KAN;Mn;0;NSM;;;;;N;;;;; -0EB2;LAO VOWEL SIGN AA;Lo;0;L;;;;;N;;;;; -0EB3;LAO VOWEL SIGN AM;Lo;0;L; 0ECD 0EB2;;;;N;;;;; -0EB4;LAO VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -0EB5;LAO VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -0EB6;LAO VOWEL SIGN Y;Mn;0;NSM;;;;;N;;;;; -0EB7;LAO VOWEL SIGN YY;Mn;0;NSM;;;;;N;;;;; -0EB8;LAO VOWEL SIGN U;Mn;118;NSM;;;;;N;;;;; -0EB9;LAO VOWEL SIGN UU;Mn;118;NSM;;;;;N;;;;; -0EBB;LAO VOWEL SIGN MAI KON;Mn;0;NSM;;;;;N;;;;; -0EBC;LAO SEMIVOWEL SIGN LO;Mn;0;NSM;;;;;N;;;;; -0EBD;LAO SEMIVOWEL SIGN NYO;Lo;0;L;;;;;N;;;;; -0EC0;LAO VOWEL SIGN E;Lo;0;L;;;;;N;;;;; -0EC1;LAO VOWEL SIGN EI;Lo;0;L;;;;;N;;;;; -0EC2;LAO VOWEL SIGN O;Lo;0;L;;;;;N;;;;; -0EC3;LAO VOWEL SIGN AY;Lo;0;L;;;;;N;;;;; -0EC4;LAO VOWEL SIGN AI;Lo;0;L;;;;;N;;;;; -0EC6;LAO KO LA;Lm;0;L;;;;;N;;;;; -0EC8;LAO TONE MAI EK;Mn;122;NSM;;;;;N;;;;; -0EC9;LAO TONE MAI THO;Mn;122;NSM;;;;;N;;;;; -0ECA;LAO TONE MAI TI;Mn;122;NSM;;;;;N;;;;; -0ECB;LAO TONE MAI CATAWA;Mn;122;NSM;;;;;N;;;;; -0ECC;LAO CANCELLATION MARK;Mn;0;NSM;;;;;N;;;;; -0ECD;LAO NIGGAHITA;Mn;0;NSM;;;;;N;;;;; -0ED0;LAO DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0ED1;LAO DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0ED2;LAO DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0ED3;LAO DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0ED4;LAO DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0ED5;LAO DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0ED6;LAO DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0ED7;LAO DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0ED8;LAO DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0ED9;LAO DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0EDC;LAO HO NO;Lo;0;L; 0EAB 0E99;;;;N;;;;; -0EDD;LAO HO MO;Lo;0;L; 0EAB 0EA1;;;;N;;;;; -0F00;TIBETAN SYLLABLE OM;Lo;0;L;;;;;N;;;;; -0F01;TIBETAN MARK GTER YIG MGO TRUNCATED A;So;0;L;;;;;N;;ter yik go a thung;;; -0F02;TIBETAN MARK GTER YIG MGO -UM RNAM BCAD MA;So;0;L;;;;;N;;ter yik go wum nam chey ma;;; -0F03;TIBETAN MARK GTER YIG MGO -UM GTER TSHEG MA;So;0;L;;;;;N;;ter yik go wum ter tsek ma;;; -0F04;TIBETAN MARK INITIAL YIG MGO MDUN MA;Po;0;L;;;;;N;TIBETAN SINGLE ORNAMENT;yik go dun ma;;; -0F05;TIBETAN MARK CLOSING YIG MGO SGAB MA;Po;0;L;;;;;N;;yik go kab ma;;; -0F06;TIBETAN MARK CARET YIG MGO PHUR SHAD MA;Po;0;L;;;;;N;;yik go pur shey ma;;; -0F07;TIBETAN MARK YIG MGO TSHEG SHAD MA;Po;0;L;;;;;N;;yik go tsek shey ma;;; -0F08;TIBETAN MARK SBRUL SHAD;Po;0;L;;;;;N;TIBETAN RGYANSHAD;drul shey;;; -0F09;TIBETAN MARK BSKUR YIG MGO;Po;0;L;;;;;N;;kur yik go;;; -0F0A;TIBETAN MARK BKA- SHOG YIG MGO;Po;0;L;;;;;N;;ka sho yik go;;; -0F0B;TIBETAN MARK INTERSYLLABIC TSHEG;Po;0;L;;;;;N;TIBETAN TSEG;tsek;;; -0F0C;TIBETAN MARK DELIMITER TSHEG BSTAR;Po;0;L; 0F0B;;;;N;;tsek tar;;; -0F0D;TIBETAN MARK SHAD;Po;0;L;;;;;N;TIBETAN SHAD;shey;;; -0F0E;TIBETAN MARK NYIS SHAD;Po;0;L;;;;;N;TIBETAN DOUBLE SHAD;nyi shey;;; -0F0F;TIBETAN MARK TSHEG SHAD;Po;0;L;;;;;N;;tsek shey;;; -0F10;TIBETAN MARK NYIS TSHEG SHAD;Po;0;L;;;;;N;;nyi tsek shey;;; -0F11;TIBETAN MARK RIN CHEN SPUNGS SHAD;Po;0;L;;;;;N;TIBETAN RINCHANPHUNGSHAD;rinchen pung shey;;; -0F12;TIBETAN MARK RGYA GRAM SHAD;Po;0;L;;;;;N;;gya tram shey;;; -0F13;TIBETAN MARK CARET -DZUD RTAGS ME LONG CAN;So;0;L;;;;;N;;dzu ta me long chen;;; -0F14;TIBETAN MARK GTER TSHEG;So;0;L;;;;;N;TIBETAN COMMA;ter tsek;;; -0F15;TIBETAN LOGOTYPE SIGN CHAD RTAGS;So;0;L;;;;;N;;che ta;;; -0F16;TIBETAN LOGOTYPE SIGN LHAG RTAGS;So;0;L;;;;;N;;hlak ta;;; -0F17;TIBETAN ASTROLOGICAL SIGN SGRA GCAN -CHAR RTAGS;So;0;L;;;;;N;;trachen char ta;;; -0F18;TIBETAN ASTROLOGICAL SIGN -KHYUD PA;Mn;220;NSM;;;;;N;;kyu pa;;; -0F19;TIBETAN ASTROLOGICAL SIGN SDONG TSHUGS;Mn;220;NSM;;;;;N;;dong tsu;;; -0F1A;TIBETAN SIGN RDEL DKAR GCIG;So;0;L;;;;;N;;deka chig;;; -0F1B;TIBETAN SIGN RDEL DKAR GNYIS;So;0;L;;;;;N;;deka nyi;;; -0F1C;TIBETAN SIGN RDEL DKAR GSUM;So;0;L;;;;;N;;deka sum;;; -0F1D;TIBETAN SIGN RDEL NAG GCIG;So;0;L;;;;;N;;dena chig;;; -0F1E;TIBETAN SIGN RDEL NAG GNYIS;So;0;L;;;;;N;;dena nyi;;; -0F1F;TIBETAN SIGN RDEL DKAR RDEL NAG;So;0;L;;;;;N;;deka dena;;; -0F20;TIBETAN DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -0F21;TIBETAN DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -0F22;TIBETAN DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -0F23;TIBETAN DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -0F24;TIBETAN DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -0F25;TIBETAN DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -0F26;TIBETAN DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -0F27;TIBETAN DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -0F28;TIBETAN DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -0F29;TIBETAN DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -0F2A;TIBETAN DIGIT HALF ONE;No;0;L;;;;1/2;N;;;;; -0F2B;TIBETAN DIGIT HALF TWO;No;0;L;;;;3/2;N;;;;; -0F2C;TIBETAN DIGIT HALF THREE;No;0;L;;;;5/2;N;;;;; -0F2D;TIBETAN DIGIT HALF FOUR;No;0;L;;;;7/2;N;;;;; -0F2E;TIBETAN DIGIT HALF FIVE;No;0;L;;;;9/2;N;;;;; -0F2F;TIBETAN DIGIT HALF SIX;No;0;L;;;;11/2;N;;;;; -0F30;TIBETAN DIGIT HALF SEVEN;No;0;L;;;;13/2;N;;;;; -0F31;TIBETAN DIGIT HALF EIGHT;No;0;L;;;;15/2;N;;;;; -0F32;TIBETAN DIGIT HALF NINE;No;0;L;;;;17/2;N;;;;; -0F33;TIBETAN DIGIT HALF ZERO;No;0;L;;;;-1/2;N;;;;; -0F34;TIBETAN MARK BSDUS RTAGS;So;0;L;;;;;N;;du ta;;; -0F35;TIBETAN MARK NGAS BZUNG NYI ZLA;Mn;220;NSM;;;;;N;TIBETAN HONORIFIC UNDER RING;nge zung nyi da;;; -0F36;TIBETAN MARK CARET -DZUD RTAGS BZHI MIG CAN;So;0;L;;;;;N;;dzu ta shi mig chen;;; -0F37;TIBETAN MARK NGAS BZUNG SGOR RTAGS;Mn;220;NSM;;;;;N;TIBETAN UNDER RING;nge zung gor ta;;; -0F38;TIBETAN MARK CHE MGO;So;0;L;;;;;N;;che go;;; -0F39;TIBETAN MARK TSA -PHRU;Mn;216;NSM;;;;;N;TIBETAN LENITION MARK;tsa tru;;; -0F3A;TIBETAN MARK GUG RTAGS GYON;Ps;0;ON;;;;;Y;;gug ta yun;;; -0F3B;TIBETAN MARK GUG RTAGS GYAS;Pe;0;ON;;;;;Y;;gug ta ye;;; -0F3C;TIBETAN MARK ANG KHANG GYON;Ps;0;ON;;;;;Y;TIBETAN LEFT BRACE;ang kang yun;;; -0F3D;TIBETAN MARK ANG KHANG GYAS;Pe;0;ON;;;;;Y;TIBETAN RIGHT BRACE;ang kang ye;;; -0F3E;TIBETAN SIGN YAR TSHES;Mc;0;L;;;;;N;;yar tse;;; -0F3F;TIBETAN SIGN MAR TSHES;Mc;0;L;;;;;N;;mar tse;;; -0F40;TIBETAN LETTER KA;Lo;0;L;;;;;N;;;;; -0F41;TIBETAN LETTER KHA;Lo;0;L;;;;;N;;;;; -0F42;TIBETAN LETTER GA;Lo;0;L;;;;;N;;;;; -0F43;TIBETAN LETTER GHA;Lo;0;L;0F42 0FB7;;;;N;;;;; -0F44;TIBETAN LETTER NGA;Lo;0;L;;;;;N;;;;; -0F45;TIBETAN LETTER CA;Lo;0;L;;;;;N;;;;; -0F46;TIBETAN LETTER CHA;Lo;0;L;;;;;N;;;;; -0F47;TIBETAN LETTER JA;Lo;0;L;;;;;N;;;;; -0F49;TIBETAN LETTER NYA;Lo;0;L;;;;;N;;;;; -0F4A;TIBETAN LETTER TTA;Lo;0;L;;;;;N;TIBETAN LETTER REVERSED TA;;;; -0F4B;TIBETAN LETTER TTHA;Lo;0;L;;;;;N;TIBETAN LETTER REVERSED THA;;;; -0F4C;TIBETAN LETTER DDA;Lo;0;L;;;;;N;TIBETAN LETTER REVERSED DA;;;; -0F4D;TIBETAN LETTER DDHA;Lo;0;L;0F4C 0FB7;;;;N;;;;; -0F4E;TIBETAN LETTER NNA;Lo;0;L;;;;;N;TIBETAN LETTER REVERSED NA;;;; -0F4F;TIBETAN LETTER TA;Lo;0;L;;;;;N;;;;; -0F50;TIBETAN LETTER THA;Lo;0;L;;;;;N;;;;; -0F51;TIBETAN LETTER DA;Lo;0;L;;;;;N;;;;; -0F52;TIBETAN LETTER DHA;Lo;0;L;0F51 0FB7;;;;N;;;;; -0F53;TIBETAN LETTER NA;Lo;0;L;;;;;N;;;;; -0F54;TIBETAN LETTER PA;Lo;0;L;;;;;N;;;;; -0F55;TIBETAN LETTER PHA;Lo;0;L;;;;;N;;;;; -0F56;TIBETAN LETTER BA;Lo;0;L;;;;;N;;;;; -0F57;TIBETAN LETTER BHA;Lo;0;L;0F56 0FB7;;;;N;;;;; -0F58;TIBETAN LETTER MA;Lo;0;L;;;;;N;;;;; -0F59;TIBETAN LETTER TSA;Lo;0;L;;;;;N;;;;; -0F5A;TIBETAN LETTER TSHA;Lo;0;L;;;;;N;;;;; -0F5B;TIBETAN LETTER DZA;Lo;0;L;;;;;N;;;;; -0F5C;TIBETAN LETTER DZHA;Lo;0;L;0F5B 0FB7;;;;N;;;;; -0F5D;TIBETAN LETTER WA;Lo;0;L;;;;;N;;;;; -0F5E;TIBETAN LETTER ZHA;Lo;0;L;;;;;N;;;;; -0F5F;TIBETAN LETTER ZA;Lo;0;L;;;;;N;;;;; -0F60;TIBETAN LETTER -A;Lo;0;L;;;;;N;TIBETAN LETTER AA;;;; -0F61;TIBETAN LETTER YA;Lo;0;L;;;;;N;;;;; -0F62;TIBETAN LETTER RA;Lo;0;L;;;;;N;;*;;; -0F63;TIBETAN LETTER LA;Lo;0;L;;;;;N;;;;; -0F64;TIBETAN LETTER SHA;Lo;0;L;;;;;N;;;;; -0F65;TIBETAN LETTER SSA;Lo;0;L;;;;;N;TIBETAN LETTER REVERSED SHA;;;; -0F66;TIBETAN LETTER SA;Lo;0;L;;;;;N;;;;; -0F67;TIBETAN LETTER HA;Lo;0;L;;;;;N;;;;; -0F68;TIBETAN LETTER A;Lo;0;L;;;;;N;;;;; -0F69;TIBETAN LETTER KSSA;Lo;0;L;0F40 0FB5;;;;N;;;;; -0F6A;TIBETAN LETTER FIXED-FORM RA;Lo;0;L;;;;;N;;*;;; -0F6B;TIBETAN LETTER KKA;Lo;0;L;;;;;N;;;;; -0F6C;TIBETAN LETTER RRA;Lo;0;L;;;;;N;;;;; -0F71;TIBETAN VOWEL SIGN AA;Mn;129;NSM;;;;;N;;;;; -0F72;TIBETAN VOWEL SIGN I;Mn;130;NSM;;;;;N;;;;; -0F73;TIBETAN VOWEL SIGN II;Mn;0;NSM;0F71 0F72;;;;N;;;;; -0F74;TIBETAN VOWEL SIGN U;Mn;132;NSM;;;;;N;;;;; -0F75;TIBETAN VOWEL SIGN UU;Mn;0;NSM;0F71 0F74;;;;N;;;;; -0F76;TIBETAN VOWEL SIGN VOCALIC R;Mn;0;NSM;0FB2 0F80;;;;N;;;;; -0F77;TIBETAN VOWEL SIGN VOCALIC RR;Mn;0;NSM; 0FB2 0F81;;;;N;;;;; -0F78;TIBETAN VOWEL SIGN VOCALIC L;Mn;0;NSM;0FB3 0F80;;;;N;;;;; -0F79;TIBETAN VOWEL SIGN VOCALIC LL;Mn;0;NSM; 0FB3 0F81;;;;N;;;;; -0F7A;TIBETAN VOWEL SIGN E;Mn;130;NSM;;;;;N;;;;; -0F7B;TIBETAN VOWEL SIGN EE;Mn;130;NSM;;;;;N;TIBETAN VOWEL SIGN AI;;;; -0F7C;TIBETAN VOWEL SIGN O;Mn;130;NSM;;;;;N;;;;; -0F7D;TIBETAN VOWEL SIGN OO;Mn;130;NSM;;;;;N;TIBETAN VOWEL SIGN AU;;;; -0F7E;TIBETAN SIGN RJES SU NGA RO;Mn;0;NSM;;;;;N;TIBETAN ANUSVARA;je su nga ro;;; -0F7F;TIBETAN SIGN RNAM BCAD;Mc;0;L;;;;;N;TIBETAN VISARGA;nam chey;;; -0F80;TIBETAN VOWEL SIGN REVERSED I;Mn;130;NSM;;;;;N;TIBETAN VOWEL SIGN SHORT I;;;; -0F81;TIBETAN VOWEL SIGN REVERSED II;Mn;0;NSM;0F71 0F80;;;;N;;;;; -0F82;TIBETAN SIGN NYI ZLA NAA DA;Mn;230;NSM;;;;;N;TIBETAN CANDRABINDU WITH ORNAMENT;nyi da na da;;; -0F83;TIBETAN SIGN SNA LDAN;Mn;230;NSM;;;;;N;TIBETAN CANDRABINDU;nan de;;; -0F84;TIBETAN MARK HALANTA;Mn;9;NSM;;;;;N;TIBETAN VIRAMA;;;; -0F85;TIBETAN MARK PALUTA;Po;0;L;;;;;N;TIBETAN CHUCHENYIGE;;;; -0F86;TIBETAN SIGN LCI RTAGS;Mn;230;NSM;;;;;N;;ji ta;;; -0F87;TIBETAN SIGN YANG RTAGS;Mn;230;NSM;;;;;N;;yang ta;;; -0F88;TIBETAN SIGN LCE TSA CAN;Lo;0;L;;;;;N;;che tsa chen;;; -0F89;TIBETAN SIGN MCHU CAN;Lo;0;L;;;;;N;;chu chen;;; -0F8A;TIBETAN SIGN GRU CAN RGYINGS;Lo;0;L;;;;;N;;tru chen ging;;; -0F8B;TIBETAN SIGN GRU MED RGYINGS;Lo;0;L;;;;;N;;tru me ging;;; -0F90;TIBETAN SUBJOINED LETTER KA;Mn;0;NSM;;;;;N;;;;; -0F91;TIBETAN SUBJOINED LETTER KHA;Mn;0;NSM;;;;;N;;;;; -0F92;TIBETAN SUBJOINED LETTER GA;Mn;0;NSM;;;;;N;;;;; -0F93;TIBETAN SUBJOINED LETTER GHA;Mn;0;NSM;0F92 0FB7;;;;N;;;;; -0F94;TIBETAN SUBJOINED LETTER NGA;Mn;0;NSM;;;;;N;;;;; -0F95;TIBETAN SUBJOINED LETTER CA;Mn;0;NSM;;;;;N;;;;; -0F96;TIBETAN SUBJOINED LETTER CHA;Mn;0;NSM;;;;;N;;;;; -0F97;TIBETAN SUBJOINED LETTER JA;Mn;0;NSM;;;;;N;;;;; -0F99;TIBETAN SUBJOINED LETTER NYA;Mn;0;NSM;;;;;N;;;;; -0F9A;TIBETAN SUBJOINED LETTER TTA;Mn;0;NSM;;;;;N;;;;; -0F9B;TIBETAN SUBJOINED LETTER TTHA;Mn;0;NSM;;;;;N;;;;; -0F9C;TIBETAN SUBJOINED LETTER DDA;Mn;0;NSM;;;;;N;;;;; -0F9D;TIBETAN SUBJOINED LETTER DDHA;Mn;0;NSM;0F9C 0FB7;;;;N;;;;; -0F9E;TIBETAN SUBJOINED LETTER NNA;Mn;0;NSM;;;;;N;;;;; -0F9F;TIBETAN SUBJOINED LETTER TA;Mn;0;NSM;;;;;N;;;;; -0FA0;TIBETAN SUBJOINED LETTER THA;Mn;0;NSM;;;;;N;;;;; -0FA1;TIBETAN SUBJOINED LETTER DA;Mn;0;NSM;;;;;N;;;;; -0FA2;TIBETAN SUBJOINED LETTER DHA;Mn;0;NSM;0FA1 0FB7;;;;N;;;;; -0FA3;TIBETAN SUBJOINED LETTER NA;Mn;0;NSM;;;;;N;;;;; -0FA4;TIBETAN SUBJOINED LETTER PA;Mn;0;NSM;;;;;N;;;;; -0FA5;TIBETAN SUBJOINED LETTER PHA;Mn;0;NSM;;;;;N;;;;; -0FA6;TIBETAN SUBJOINED LETTER BA;Mn;0;NSM;;;;;N;;;;; -0FA7;TIBETAN SUBJOINED LETTER BHA;Mn;0;NSM;0FA6 0FB7;;;;N;;;;; -0FA8;TIBETAN SUBJOINED LETTER MA;Mn;0;NSM;;;;;N;;;;; -0FA9;TIBETAN SUBJOINED LETTER TSA;Mn;0;NSM;;;;;N;;;;; -0FAA;TIBETAN SUBJOINED LETTER TSHA;Mn;0;NSM;;;;;N;;;;; -0FAB;TIBETAN SUBJOINED LETTER DZA;Mn;0;NSM;;;;;N;;;;; -0FAC;TIBETAN SUBJOINED LETTER DZHA;Mn;0;NSM;0FAB 0FB7;;;;N;;;;; -0FAD;TIBETAN SUBJOINED LETTER WA;Mn;0;NSM;;;;;N;;*;;; -0FAE;TIBETAN SUBJOINED LETTER ZHA;Mn;0;NSM;;;;;N;;;;; -0FAF;TIBETAN SUBJOINED LETTER ZA;Mn;0;NSM;;;;;N;;;;; -0FB0;TIBETAN SUBJOINED LETTER -A;Mn;0;NSM;;;;;N;;;;; -0FB1;TIBETAN SUBJOINED LETTER YA;Mn;0;NSM;;;;;N;;*;;; -0FB2;TIBETAN SUBJOINED LETTER RA;Mn;0;NSM;;;;;N;;*;;; -0FB3;TIBETAN SUBJOINED LETTER LA;Mn;0;NSM;;;;;N;;;;; -0FB4;TIBETAN SUBJOINED LETTER SHA;Mn;0;NSM;;;;;N;;;;; -0FB5;TIBETAN SUBJOINED LETTER SSA;Mn;0;NSM;;;;;N;;;;; -0FB6;TIBETAN SUBJOINED LETTER SA;Mn;0;NSM;;;;;N;;;;; -0FB7;TIBETAN SUBJOINED LETTER HA;Mn;0;NSM;;;;;N;;;;; -0FB8;TIBETAN SUBJOINED LETTER A;Mn;0;NSM;;;;;N;;;;; -0FB9;TIBETAN SUBJOINED LETTER KSSA;Mn;0;NSM;0F90 0FB5;;;;N;;;;; -0FBA;TIBETAN SUBJOINED LETTER FIXED-FORM WA;Mn;0;NSM;;;;;N;;*;;; -0FBB;TIBETAN SUBJOINED LETTER FIXED-FORM YA;Mn;0;NSM;;;;;N;;*;;; -0FBC;TIBETAN SUBJOINED LETTER FIXED-FORM RA;Mn;0;NSM;;;;;N;;*;;; -0FBE;TIBETAN KU RU KHA;So;0;L;;;;;N;;kuruka;;; -0FBF;TIBETAN KU RU KHA BZHI MIG CAN;So;0;L;;;;;N;;kuruka shi mik chen;;; -0FC0;TIBETAN CANTILLATION SIGN HEAVY BEAT;So;0;L;;;;;N;;;;; -0FC1;TIBETAN CANTILLATION SIGN LIGHT BEAT;So;0;L;;;;;N;;;;; -0FC2;TIBETAN CANTILLATION SIGN CANG TE-U;So;0;L;;;;;N;;chang tyu;;; -0FC3;TIBETAN CANTILLATION SIGN SBUB -CHAL;So;0;L;;;;;N;;bub chey;;; -0FC4;TIBETAN SYMBOL DRIL BU;So;0;L;;;;;N;;drilbu;;; -0FC5;TIBETAN SYMBOL RDO RJE;So;0;L;;;;;N;;dorje;;; -0FC6;TIBETAN SYMBOL PADMA GDAN;Mn;220;NSM;;;;;N;;pema den;;; -0FC7;TIBETAN SYMBOL RDO RJE RGYA GRAM;So;0;L;;;;;N;;dorje gya dram;;; -0FC8;TIBETAN SYMBOL PHUR PA;So;0;L;;;;;N;;phurba;;; -0FC9;TIBETAN SYMBOL NOR BU;So;0;L;;;;;N;;norbu;;; -0FCA;TIBETAN SYMBOL NOR BU NYIS -KHYIL;So;0;L;;;;;N;;norbu nyi khyi;;; -0FCB;TIBETAN SYMBOL NOR BU GSUM -KHYIL;So;0;L;;;;;N;;norbu sum khyi;;; -0FCC;TIBETAN SYMBOL NOR BU BZHI -KHYIL;So;0;L;;;;;N;;norbu shi khyi;;; -0FCE;TIBETAN SIGN RDEL NAG RDEL DKAR;So;0;L;;;;;N;;dena deka;;; -0FCF;TIBETAN SIGN RDEL NAG GSUM;So;0;L;;;;;N;;dena sum;;; -0FD0;TIBETAN MARK BSKA- SHOG GI MGO RGYAN;Po;0;L;;;;;N;;ka shog gi go gyen;;; -0FD1;TIBETAN MARK MNYAM YIG GI MGO RGYAN;Po;0;L;;;;;N;;nyam yig gi go gyen;;; -0FD2;TIBETAN MARK NYIS TSHEG;Po;0;L;;;;;N;;nyi tsek;;; -0FD3;TIBETAN MARK INITIAL BRDA RNYING YIG MGO MDUN MA;Po;0;L;;;;;N;;da nying yik go dun ma;;; -0FD4;TIBETAN MARK CLOSING BRDA RNYING YIG MGO SGAB MA;Po;0;L;;;;;N;;da nying yik go kab ma;;; -1000;MYANMAR LETTER KA;Lo;0;L;;;;;N;;;;; -1001;MYANMAR LETTER KHA;Lo;0;L;;;;;N;;;;; -1002;MYANMAR LETTER GA;Lo;0;L;;;;;N;;;;; -1003;MYANMAR LETTER GHA;Lo;0;L;;;;;N;;;;; -1004;MYANMAR LETTER NGA;Lo;0;L;;;;;N;;;;; -1005;MYANMAR LETTER CA;Lo;0;L;;;;;N;;;;; -1006;MYANMAR LETTER CHA;Lo;0;L;;;;;N;;;;; -1007;MYANMAR LETTER JA;Lo;0;L;;;;;N;;;;; -1008;MYANMAR LETTER JHA;Lo;0;L;;;;;N;;;;; -1009;MYANMAR LETTER NYA;Lo;0;L;;;;;N;;;;; -100A;MYANMAR LETTER NNYA;Lo;0;L;;;;;N;;;;; -100B;MYANMAR LETTER TTA;Lo;0;L;;;;;N;;;;; -100C;MYANMAR LETTER TTHA;Lo;0;L;;;;;N;;;;; -100D;MYANMAR LETTER DDA;Lo;0;L;;;;;N;;;;; -100E;MYANMAR LETTER DDHA;Lo;0;L;;;;;N;;;;; -100F;MYANMAR LETTER NNA;Lo;0;L;;;;;N;;;;; -1010;MYANMAR LETTER TA;Lo;0;L;;;;;N;;;;; -1011;MYANMAR LETTER THA;Lo;0;L;;;;;N;;;;; -1012;MYANMAR LETTER DA;Lo;0;L;;;;;N;;;;; -1013;MYANMAR LETTER DHA;Lo;0;L;;;;;N;;;;; -1014;MYANMAR LETTER NA;Lo;0;L;;;;;N;;;;; -1015;MYANMAR LETTER PA;Lo;0;L;;;;;N;;;;; -1016;MYANMAR LETTER PHA;Lo;0;L;;;;;N;;;;; -1017;MYANMAR LETTER BA;Lo;0;L;;;;;N;;;;; -1018;MYANMAR LETTER BHA;Lo;0;L;;;;;N;;;;; -1019;MYANMAR LETTER MA;Lo;0;L;;;;;N;;;;; -101A;MYANMAR LETTER YA;Lo;0;L;;;;;N;;;;; -101B;MYANMAR LETTER RA;Lo;0;L;;;;;N;;;;; -101C;MYANMAR LETTER LA;Lo;0;L;;;;;N;;;;; -101D;MYANMAR LETTER WA;Lo;0;L;;;;;N;;;;; -101E;MYANMAR LETTER SA;Lo;0;L;;;;;N;;;;; -101F;MYANMAR LETTER HA;Lo;0;L;;;;;N;;;;; -1020;MYANMAR LETTER LLA;Lo;0;L;;;;;N;;;;; -1021;MYANMAR LETTER A;Lo;0;L;;;;;N;;;;; -1022;MYANMAR LETTER SHAN A;Lo;0;L;;;;;N;;;;; -1023;MYANMAR LETTER I;Lo;0;L;;;;;N;;;;; -1024;MYANMAR LETTER II;Lo;0;L;;;;;N;;;;; -1025;MYANMAR LETTER U;Lo;0;L;;;;;N;;;;; -1026;MYANMAR LETTER UU;Lo;0;L;1025 102E;;;;N;;;;; -1027;MYANMAR LETTER E;Lo;0;L;;;;;N;;;;; -1028;MYANMAR LETTER MON E;Lo;0;L;;;;;N;;;;; -1029;MYANMAR LETTER O;Lo;0;L;;;;;N;;;;; -102A;MYANMAR LETTER AU;Lo;0;L;;;;;N;;;;; -102B;MYANMAR VOWEL SIGN TALL AA;Mc;0;L;;;;;N;;;;; -102C;MYANMAR VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -102D;MYANMAR VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -102E;MYANMAR VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -102F;MYANMAR VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1030;MYANMAR VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -1031;MYANMAR VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -1032;MYANMAR VOWEL SIGN AI;Mn;0;NSM;;;;;N;;;;; -1033;MYANMAR VOWEL SIGN MON II;Mn;0;NSM;;;;;N;;;;; -1034;MYANMAR VOWEL SIGN MON O;Mn;0;NSM;;;;;N;;;;; -1035;MYANMAR VOWEL SIGN E ABOVE;Mn;0;NSM;;;;;N;;;;; -1036;MYANMAR SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -1037;MYANMAR SIGN DOT BELOW;Mn;7;NSM;;;;;N;;;;; -1038;MYANMAR SIGN VISARGA;Mc;0;L;;;;;N;;;;; -1039;MYANMAR SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -103A;MYANMAR SIGN ASAT;Mn;9;NSM;;;;;N;;;;; -103B;MYANMAR CONSONANT SIGN MEDIAL YA;Mc;0;L;;;;;N;;;;; -103C;MYANMAR CONSONANT SIGN MEDIAL RA;Mc;0;L;;;;;N;;;;; -103D;MYANMAR CONSONANT SIGN MEDIAL WA;Mn;0;NSM;;;;;N;;;;; -103E;MYANMAR CONSONANT SIGN MEDIAL HA;Mn;0;NSM;;;;;N;;;;; -103F;MYANMAR LETTER GREAT SA;Lo;0;L;;;;;N;;;;; -1040;MYANMAR DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1041;MYANMAR DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1042;MYANMAR DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1043;MYANMAR DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1044;MYANMAR DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1045;MYANMAR DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1046;MYANMAR DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1047;MYANMAR DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1048;MYANMAR DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1049;MYANMAR DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -104A;MYANMAR SIGN LITTLE SECTION;Po;0;L;;;;;N;;;;; -104B;MYANMAR SIGN SECTION;Po;0;L;;;;;N;;;;; -104C;MYANMAR SYMBOL LOCATIVE;Po;0;L;;;;;N;;;;; -104D;MYANMAR SYMBOL COMPLETED;Po;0;L;;;;;N;;;;; -104E;MYANMAR SYMBOL AFOREMENTIONED;Po;0;L;;;;;N;;;;; -104F;MYANMAR SYMBOL GENITIVE;Po;0;L;;;;;N;;;;; -1050;MYANMAR LETTER SHA;Lo;0;L;;;;;N;;;;; -1051;MYANMAR LETTER SSA;Lo;0;L;;;;;N;;;;; -1052;MYANMAR LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -1053;MYANMAR LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -1054;MYANMAR LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -1055;MYANMAR LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -1056;MYANMAR VOWEL SIGN VOCALIC R;Mc;0;L;;;;;N;;;;; -1057;MYANMAR VOWEL SIGN VOCALIC RR;Mc;0;L;;;;;N;;;;; -1058;MYANMAR VOWEL SIGN VOCALIC L;Mn;0;NSM;;;;;N;;;;; -1059;MYANMAR VOWEL SIGN VOCALIC LL;Mn;0;NSM;;;;;N;;;;; -105A;MYANMAR LETTER MON NGA;Lo;0;L;;;;;N;;;;; -105B;MYANMAR LETTER MON JHA;Lo;0;L;;;;;N;;;;; -105C;MYANMAR LETTER MON BBA;Lo;0;L;;;;;N;;;;; -105D;MYANMAR LETTER MON BBE;Lo;0;L;;;;;N;;;;; -105E;MYANMAR CONSONANT SIGN MON MEDIAL NA;Mn;0;NSM;;;;;N;;;;; -105F;MYANMAR CONSONANT SIGN MON MEDIAL MA;Mn;0;NSM;;;;;N;;;;; -1060;MYANMAR CONSONANT SIGN MON MEDIAL LA;Mn;0;NSM;;;;;N;;;;; -1061;MYANMAR LETTER SGAW KAREN SHA;Lo;0;L;;;;;N;;;;; -1062;MYANMAR VOWEL SIGN SGAW KAREN EU;Mc;0;L;;;;;N;;;;; -1063;MYANMAR TONE MARK SGAW KAREN HATHI;Mc;0;L;;;;;N;;;;; -1064;MYANMAR TONE MARK SGAW KAREN KE PHO;Mc;0;L;;;;;N;;;;; -1065;MYANMAR LETTER WESTERN PWO KAREN THA;Lo;0;L;;;;;N;;;;; -1066;MYANMAR LETTER WESTERN PWO KAREN PWA;Lo;0;L;;;;;N;;;;; -1067;MYANMAR VOWEL SIGN WESTERN PWO KAREN EU;Mc;0;L;;;;;N;;;;; -1068;MYANMAR VOWEL SIGN WESTERN PWO KAREN UE;Mc;0;L;;;;;N;;;;; -1069;MYANMAR SIGN WESTERN PWO KAREN TONE-1;Mc;0;L;;;;;N;;;;; -106A;MYANMAR SIGN WESTERN PWO KAREN TONE-2;Mc;0;L;;;;;N;;;;; -106B;MYANMAR SIGN WESTERN PWO KAREN TONE-3;Mc;0;L;;;;;N;;;;; -106C;MYANMAR SIGN WESTERN PWO KAREN TONE-4;Mc;0;L;;;;;N;;;;; -106D;MYANMAR SIGN WESTERN PWO KAREN TONE-5;Mc;0;L;;;;;N;;;;; -106E;MYANMAR LETTER EASTERN PWO KAREN NNA;Lo;0;L;;;;;N;;;;; -106F;MYANMAR LETTER EASTERN PWO KAREN YWA;Lo;0;L;;;;;N;;;;; -1070;MYANMAR LETTER EASTERN PWO KAREN GHWA;Lo;0;L;;;;;N;;;;; -1071;MYANMAR VOWEL SIGN GEBA KAREN I;Mn;0;NSM;;;;;N;;;;; -1072;MYANMAR VOWEL SIGN KAYAH OE;Mn;0;NSM;;;;;N;;;;; -1073;MYANMAR VOWEL SIGN KAYAH U;Mn;0;NSM;;;;;N;;;;; -1074;MYANMAR VOWEL SIGN KAYAH EE;Mn;0;NSM;;;;;N;;;;; -1075;MYANMAR LETTER SHAN KA;Lo;0;L;;;;;N;;;;; -1076;MYANMAR LETTER SHAN KHA;Lo;0;L;;;;;N;;;;; -1077;MYANMAR LETTER SHAN GA;Lo;0;L;;;;;N;;;;; -1078;MYANMAR LETTER SHAN CA;Lo;0;L;;;;;N;;;;; -1079;MYANMAR LETTER SHAN ZA;Lo;0;L;;;;;N;;;;; -107A;MYANMAR LETTER SHAN NYA;Lo;0;L;;;;;N;;;;; -107B;MYANMAR LETTER SHAN DA;Lo;0;L;;;;;N;;;;; -107C;MYANMAR LETTER SHAN NA;Lo;0;L;;;;;N;;;;; -107D;MYANMAR LETTER SHAN PHA;Lo;0;L;;;;;N;;;;; -107E;MYANMAR LETTER SHAN FA;Lo;0;L;;;;;N;;;;; -107F;MYANMAR LETTER SHAN BA;Lo;0;L;;;;;N;;;;; -1080;MYANMAR LETTER SHAN THA;Lo;0;L;;;;;N;;;;; -1081;MYANMAR LETTER SHAN HA;Lo;0;L;;;;;N;;;;; -1082;MYANMAR CONSONANT SIGN SHAN MEDIAL WA;Mn;0;NSM;;;;;N;;;;; -1083;MYANMAR VOWEL SIGN SHAN AA;Mc;0;L;;;;;N;;;;; -1084;MYANMAR VOWEL SIGN SHAN E;Mc;0;L;;;;;N;;;;; -1085;MYANMAR VOWEL SIGN SHAN E ABOVE;Mn;0;NSM;;;;;N;;;;; -1086;MYANMAR VOWEL SIGN SHAN FINAL Y;Mn;0;NSM;;;;;N;;;;; -1087;MYANMAR SIGN SHAN TONE-2;Mc;0;L;;;;;N;;;;; -1088;MYANMAR SIGN SHAN TONE-3;Mc;0;L;;;;;N;;;;; -1089;MYANMAR SIGN SHAN TONE-5;Mc;0;L;;;;;N;;;;; -108A;MYANMAR SIGN SHAN TONE-6;Mc;0;L;;;;;N;;;;; -108B;MYANMAR SIGN SHAN COUNCIL TONE-2;Mc;0;L;;;;;N;;;;; -108C;MYANMAR SIGN SHAN COUNCIL TONE-3;Mc;0;L;;;;;N;;;;; -108D;MYANMAR SIGN SHAN COUNCIL EMPHATIC TONE;Mn;220;NSM;;;;;N;;;;; -108E;MYANMAR LETTER RUMAI PALAUNG FA;Lo;0;L;;;;;N;;;;; -108F;MYANMAR SIGN RUMAI PALAUNG TONE-5;Mc;0;L;;;;;N;;;;; -1090;MYANMAR SHAN DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1091;MYANMAR SHAN DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1092;MYANMAR SHAN DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1093;MYANMAR SHAN DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1094;MYANMAR SHAN DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1095;MYANMAR SHAN DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1096;MYANMAR SHAN DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1097;MYANMAR SHAN DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1098;MYANMAR SHAN DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1099;MYANMAR SHAN DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -109E;MYANMAR SYMBOL SHAN ONE;So;0;L;;;;;N;;;;; -109F;MYANMAR SYMBOL SHAN EXCLAMATION;So;0;L;;;;;N;;;;; -10A0;GEORGIAN CAPITAL LETTER AN;Lu;0;L;;;;;N;;Khutsuri;;2D00; -10A1;GEORGIAN CAPITAL LETTER BAN;Lu;0;L;;;;;N;;Khutsuri;;2D01; -10A2;GEORGIAN CAPITAL LETTER GAN;Lu;0;L;;;;;N;;Khutsuri;;2D02; -10A3;GEORGIAN CAPITAL LETTER DON;Lu;0;L;;;;;N;;Khutsuri;;2D03; -10A4;GEORGIAN CAPITAL LETTER EN;Lu;0;L;;;;;N;;Khutsuri;;2D04; -10A5;GEORGIAN CAPITAL LETTER VIN;Lu;0;L;;;;;N;;Khutsuri;;2D05; -10A6;GEORGIAN CAPITAL LETTER ZEN;Lu;0;L;;;;;N;;Khutsuri;;2D06; -10A7;GEORGIAN CAPITAL LETTER TAN;Lu;0;L;;;;;N;;Khutsuri;;2D07; -10A8;GEORGIAN CAPITAL LETTER IN;Lu;0;L;;;;;N;;Khutsuri;;2D08; -10A9;GEORGIAN CAPITAL LETTER KAN;Lu;0;L;;;;;N;;Khutsuri;;2D09; -10AA;GEORGIAN CAPITAL LETTER LAS;Lu;0;L;;;;;N;;Khutsuri;;2D0A; -10AB;GEORGIAN CAPITAL LETTER MAN;Lu;0;L;;;;;N;;Khutsuri;;2D0B; -10AC;GEORGIAN CAPITAL LETTER NAR;Lu;0;L;;;;;N;;Khutsuri;;2D0C; -10AD;GEORGIAN CAPITAL LETTER ON;Lu;0;L;;;;;N;;Khutsuri;;2D0D; -10AE;GEORGIAN CAPITAL LETTER PAR;Lu;0;L;;;;;N;;Khutsuri;;2D0E; -10AF;GEORGIAN CAPITAL LETTER ZHAR;Lu;0;L;;;;;N;;Khutsuri;;2D0F; -10B0;GEORGIAN CAPITAL LETTER RAE;Lu;0;L;;;;;N;;Khutsuri;;2D10; -10B1;GEORGIAN CAPITAL LETTER SAN;Lu;0;L;;;;;N;;Khutsuri;;2D11; -10B2;GEORGIAN CAPITAL LETTER TAR;Lu;0;L;;;;;N;;Khutsuri;;2D12; -10B3;GEORGIAN CAPITAL LETTER UN;Lu;0;L;;;;;N;;Khutsuri;;2D13; -10B4;GEORGIAN CAPITAL LETTER PHAR;Lu;0;L;;;;;N;;Khutsuri;;2D14; -10B5;GEORGIAN CAPITAL LETTER KHAR;Lu;0;L;;;;;N;;Khutsuri;;2D15; -10B6;GEORGIAN CAPITAL LETTER GHAN;Lu;0;L;;;;;N;;Khutsuri;;2D16; -10B7;GEORGIAN CAPITAL LETTER QAR;Lu;0;L;;;;;N;;Khutsuri;;2D17; -10B8;GEORGIAN CAPITAL LETTER SHIN;Lu;0;L;;;;;N;;Khutsuri;;2D18; -10B9;GEORGIAN CAPITAL LETTER CHIN;Lu;0;L;;;;;N;;Khutsuri;;2D19; -10BA;GEORGIAN CAPITAL LETTER CAN;Lu;0;L;;;;;N;;Khutsuri;;2D1A; -10BB;GEORGIAN CAPITAL LETTER JIL;Lu;0;L;;;;;N;;Khutsuri;;2D1B; -10BC;GEORGIAN CAPITAL LETTER CIL;Lu;0;L;;;;;N;;Khutsuri;;2D1C; -10BD;GEORGIAN CAPITAL LETTER CHAR;Lu;0;L;;;;;N;;Khutsuri;;2D1D; -10BE;GEORGIAN CAPITAL LETTER XAN;Lu;0;L;;;;;N;;Khutsuri;;2D1E; -10BF;GEORGIAN CAPITAL LETTER JHAN;Lu;0;L;;;;;N;;Khutsuri;;2D1F; -10C0;GEORGIAN CAPITAL LETTER HAE;Lu;0;L;;;;;N;;Khutsuri;;2D20; -10C1;GEORGIAN CAPITAL LETTER HE;Lu;0;L;;;;;N;;Khutsuri;;2D21; -10C2;GEORGIAN CAPITAL LETTER HIE;Lu;0;L;;;;;N;;Khutsuri;;2D22; -10C3;GEORGIAN CAPITAL LETTER WE;Lu;0;L;;;;;N;;Khutsuri;;2D23; -10C4;GEORGIAN CAPITAL LETTER HAR;Lu;0;L;;;;;N;;Khutsuri;;2D24; -10C5;GEORGIAN CAPITAL LETTER HOE;Lu;0;L;;;;;N;;Khutsuri;;2D25; -10D0;GEORGIAN LETTER AN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER AN;;;; -10D1;GEORGIAN LETTER BAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER BAN;;;; -10D2;GEORGIAN LETTER GAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER GAN;;;; -10D3;GEORGIAN LETTER DON;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER DON;;;; -10D4;GEORGIAN LETTER EN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER EN;;;; -10D5;GEORGIAN LETTER VIN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER VIN;;;; -10D6;GEORGIAN LETTER ZEN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER ZEN;;;; -10D7;GEORGIAN LETTER TAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER TAN;;;; -10D8;GEORGIAN LETTER IN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER IN;;;; -10D9;GEORGIAN LETTER KAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER KAN;;;; -10DA;GEORGIAN LETTER LAS;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER LAS;;;; -10DB;GEORGIAN LETTER MAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER MAN;;;; -10DC;GEORGIAN LETTER NAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER NAR;;;; -10DD;GEORGIAN LETTER ON;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER ON;;;; -10DE;GEORGIAN LETTER PAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER PAR;;;; -10DF;GEORGIAN LETTER ZHAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER ZHAR;;;; -10E0;GEORGIAN LETTER RAE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER RAE;;;; -10E1;GEORGIAN LETTER SAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER SAN;;;; -10E2;GEORGIAN LETTER TAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER TAR;;;; -10E3;GEORGIAN LETTER UN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER UN;;;; -10E4;GEORGIAN LETTER PHAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER PHAR;;;; -10E5;GEORGIAN LETTER KHAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER KHAR;;;; -10E6;GEORGIAN LETTER GHAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER GHAN;;;; -10E7;GEORGIAN LETTER QAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER QAR;;;; -10E8;GEORGIAN LETTER SHIN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER SHIN;;;; -10E9;GEORGIAN LETTER CHIN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER CHIN;;;; -10EA;GEORGIAN LETTER CAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER CAN;;;; -10EB;GEORGIAN LETTER JIL;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER JIL;;;; -10EC;GEORGIAN LETTER CIL;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER CIL;;;; -10ED;GEORGIAN LETTER CHAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER CHAR;;;; -10EE;GEORGIAN LETTER XAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER XAN;;;; -10EF;GEORGIAN LETTER JHAN;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER JHAN;;;; -10F0;GEORGIAN LETTER HAE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER HAE;;;; -10F1;GEORGIAN LETTER HE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER HE;;;; -10F2;GEORGIAN LETTER HIE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER HIE;;;; -10F3;GEORGIAN LETTER WE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER WE;;;; -10F4;GEORGIAN LETTER HAR;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER HAR;;;; -10F5;GEORGIAN LETTER HOE;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER HOE;;;; -10F6;GEORGIAN LETTER FI;Lo;0;L;;;;;N;GEORGIAN SMALL LETTER FI;;;; -10F7;GEORGIAN LETTER YN;Lo;0;L;;;;;N;;;;; -10F8;GEORGIAN LETTER ELIFI;Lo;0;L;;;;;N;;;;; -10F9;GEORGIAN LETTER TURNED GAN;Lo;0;L;;;;;N;;;;; -10FA;GEORGIAN LETTER AIN;Lo;0;L;;;;;N;;;;; -10FB;GEORGIAN PARAGRAPH SEPARATOR;Po;0;L;;;;;N;;;;; -10FC;MODIFIER LETTER GEORGIAN NAR;Lm;0;L; 10DC;;;;N;;;;; -1100;HANGUL CHOSEONG KIYEOK;Lo;0;L;;;;;N;;g *;;; -1101;HANGUL CHOSEONG SSANGKIYEOK;Lo;0;L;;;;;N;;gg *;;; -1102;HANGUL CHOSEONG NIEUN;Lo;0;L;;;;;N;;n *;;; -1103;HANGUL CHOSEONG TIKEUT;Lo;0;L;;;;;N;;d *;;; -1104;HANGUL CHOSEONG SSANGTIKEUT;Lo;0;L;;;;;N;;dd *;;; -1105;HANGUL CHOSEONG RIEUL;Lo;0;L;;;;;N;;r *;;; -1106;HANGUL CHOSEONG MIEUM;Lo;0;L;;;;;N;;m *;;; -1107;HANGUL CHOSEONG PIEUP;Lo;0;L;;;;;N;;b *;;; -1108;HANGUL CHOSEONG SSANGPIEUP;Lo;0;L;;;;;N;;bb *;;; -1109;HANGUL CHOSEONG SIOS;Lo;0;L;;;;;N;;s *;;; -110A;HANGUL CHOSEONG SSANGSIOS;Lo;0;L;;;;;N;;ss *;;; -110B;HANGUL CHOSEONG IEUNG;Lo;0;L;;;;;N;;;;; -110C;HANGUL CHOSEONG CIEUC;Lo;0;L;;;;;N;;j *;;; -110D;HANGUL CHOSEONG SSANGCIEUC;Lo;0;L;;;;;N;;jj *;;; -110E;HANGUL CHOSEONG CHIEUCH;Lo;0;L;;;;;N;;c *;;; -110F;HANGUL CHOSEONG KHIEUKH;Lo;0;L;;;;;N;;k *;;; -1110;HANGUL CHOSEONG THIEUTH;Lo;0;L;;;;;N;;t *;;; -1111;HANGUL CHOSEONG PHIEUPH;Lo;0;L;;;;;N;;p *;;; -1112;HANGUL CHOSEONG HIEUH;Lo;0;L;;;;;N;;h *;;; -1113;HANGUL CHOSEONG NIEUN-KIYEOK;Lo;0;L;;;;;N;;;;; -1114;HANGUL CHOSEONG SSANGNIEUN;Lo;0;L;;;;;N;;;;; -1115;HANGUL CHOSEONG NIEUN-TIKEUT;Lo;0;L;;;;;N;;;;; -1116;HANGUL CHOSEONG NIEUN-PIEUP;Lo;0;L;;;;;N;;;;; -1117;HANGUL CHOSEONG TIKEUT-KIYEOK;Lo;0;L;;;;;N;;;;; -1118;HANGUL CHOSEONG RIEUL-NIEUN;Lo;0;L;;;;;N;;;;; -1119;HANGUL CHOSEONG SSANGRIEUL;Lo;0;L;;;;;N;;;;; -111A;HANGUL CHOSEONG RIEUL-HIEUH;Lo;0;L;;;;;N;;;;; -111B;HANGUL CHOSEONG KAPYEOUNRIEUL;Lo;0;L;;;;;N;;;;; -111C;HANGUL CHOSEONG MIEUM-PIEUP;Lo;0;L;;;;;N;;;;; -111D;HANGUL CHOSEONG KAPYEOUNMIEUM;Lo;0;L;;;;;N;;;;; -111E;HANGUL CHOSEONG PIEUP-KIYEOK;Lo;0;L;;;;;N;;;;; -111F;HANGUL CHOSEONG PIEUP-NIEUN;Lo;0;L;;;;;N;;;;; -1120;HANGUL CHOSEONG PIEUP-TIKEUT;Lo;0;L;;;;;N;;;;; -1121;HANGUL CHOSEONG PIEUP-SIOS;Lo;0;L;;;;;N;;;;; -1122;HANGUL CHOSEONG PIEUP-SIOS-KIYEOK;Lo;0;L;;;;;N;;;;; -1123;HANGUL CHOSEONG PIEUP-SIOS-TIKEUT;Lo;0;L;;;;;N;;;;; -1124;HANGUL CHOSEONG PIEUP-SIOS-PIEUP;Lo;0;L;;;;;N;;;;; -1125;HANGUL CHOSEONG PIEUP-SSANGSIOS;Lo;0;L;;;;;N;;;;; -1126;HANGUL CHOSEONG PIEUP-SIOS-CIEUC;Lo;0;L;;;;;N;;;;; -1127;HANGUL CHOSEONG PIEUP-CIEUC;Lo;0;L;;;;;N;;;;; -1128;HANGUL CHOSEONG PIEUP-CHIEUCH;Lo;0;L;;;;;N;;;;; -1129;HANGUL CHOSEONG PIEUP-THIEUTH;Lo;0;L;;;;;N;;;;; -112A;HANGUL CHOSEONG PIEUP-PHIEUPH;Lo;0;L;;;;;N;;;;; -112B;HANGUL CHOSEONG KAPYEOUNPIEUP;Lo;0;L;;;;;N;;;;; -112C;HANGUL CHOSEONG KAPYEOUNSSANGPIEUP;Lo;0;L;;;;;N;;;;; -112D;HANGUL CHOSEONG SIOS-KIYEOK;Lo;0;L;;;;;N;;;;; -112E;HANGUL CHOSEONG SIOS-NIEUN;Lo;0;L;;;;;N;;;;; -112F;HANGUL CHOSEONG SIOS-TIKEUT;Lo;0;L;;;;;N;;;;; -1130;HANGUL CHOSEONG SIOS-RIEUL;Lo;0;L;;;;;N;;;;; -1131;HANGUL CHOSEONG SIOS-MIEUM;Lo;0;L;;;;;N;;;;; -1132;HANGUL CHOSEONG SIOS-PIEUP;Lo;0;L;;;;;N;;;;; -1133;HANGUL CHOSEONG SIOS-PIEUP-KIYEOK;Lo;0;L;;;;;N;;;;; -1134;HANGUL CHOSEONG SIOS-SSANGSIOS;Lo;0;L;;;;;N;;;;; -1135;HANGUL CHOSEONG SIOS-IEUNG;Lo;0;L;;;;;N;;;;; -1136;HANGUL CHOSEONG SIOS-CIEUC;Lo;0;L;;;;;N;;;;; -1137;HANGUL CHOSEONG SIOS-CHIEUCH;Lo;0;L;;;;;N;;;;; -1138;HANGUL CHOSEONG SIOS-KHIEUKH;Lo;0;L;;;;;N;;;;; -1139;HANGUL CHOSEONG SIOS-THIEUTH;Lo;0;L;;;;;N;;;;; -113A;HANGUL CHOSEONG SIOS-PHIEUPH;Lo;0;L;;;;;N;;;;; -113B;HANGUL CHOSEONG SIOS-HIEUH;Lo;0;L;;;;;N;;;;; -113C;HANGUL CHOSEONG CHITUEUMSIOS;Lo;0;L;;;;;N;;;;; -113D;HANGUL CHOSEONG CHITUEUMSSANGSIOS;Lo;0;L;;;;;N;;;;; -113E;HANGUL CHOSEONG CEONGCHIEUMSIOS;Lo;0;L;;;;;N;;;;; -113F;HANGUL CHOSEONG CEONGCHIEUMSSANGSIOS;Lo;0;L;;;;;N;;;;; -1140;HANGUL CHOSEONG PANSIOS;Lo;0;L;;;;;N;;;;; -1141;HANGUL CHOSEONG IEUNG-KIYEOK;Lo;0;L;;;;;N;;;;; -1142;HANGUL CHOSEONG IEUNG-TIKEUT;Lo;0;L;;;;;N;;;;; -1143;HANGUL CHOSEONG IEUNG-MIEUM;Lo;0;L;;;;;N;;;;; -1144;HANGUL CHOSEONG IEUNG-PIEUP;Lo;0;L;;;;;N;;;;; -1145;HANGUL CHOSEONG IEUNG-SIOS;Lo;0;L;;;;;N;;;;; -1146;HANGUL CHOSEONG IEUNG-PANSIOS;Lo;0;L;;;;;N;;;;; -1147;HANGUL CHOSEONG SSANGIEUNG;Lo;0;L;;;;;N;;;;; -1148;HANGUL CHOSEONG IEUNG-CIEUC;Lo;0;L;;;;;N;;;;; -1149;HANGUL CHOSEONG IEUNG-CHIEUCH;Lo;0;L;;;;;N;;;;; -114A;HANGUL CHOSEONG IEUNG-THIEUTH;Lo;0;L;;;;;N;;;;; -114B;HANGUL CHOSEONG IEUNG-PHIEUPH;Lo;0;L;;;;;N;;;;; -114C;HANGUL CHOSEONG YESIEUNG;Lo;0;L;;;;;N;;;;; -114D;HANGUL CHOSEONG CIEUC-IEUNG;Lo;0;L;;;;;N;;;;; -114E;HANGUL CHOSEONG CHITUEUMCIEUC;Lo;0;L;;;;;N;;;;; -114F;HANGUL CHOSEONG CHITUEUMSSANGCIEUC;Lo;0;L;;;;;N;;;;; -1150;HANGUL CHOSEONG CEONGCHIEUMCIEUC;Lo;0;L;;;;;N;;;;; -1151;HANGUL CHOSEONG CEONGCHIEUMSSANGCIEUC;Lo;0;L;;;;;N;;;;; -1152;HANGUL CHOSEONG CHIEUCH-KHIEUKH;Lo;0;L;;;;;N;;;;; -1153;HANGUL CHOSEONG CHIEUCH-HIEUH;Lo;0;L;;;;;N;;;;; -1154;HANGUL CHOSEONG CHITUEUMCHIEUCH;Lo;0;L;;;;;N;;;;; -1155;HANGUL CHOSEONG CEONGCHIEUMCHIEUCH;Lo;0;L;;;;;N;;;;; -1156;HANGUL CHOSEONG PHIEUPH-PIEUP;Lo;0;L;;;;;N;;;;; -1157;HANGUL CHOSEONG KAPYEOUNPHIEUPH;Lo;0;L;;;;;N;;;;; -1158;HANGUL CHOSEONG SSANGHIEUH;Lo;0;L;;;;;N;;;;; -1159;HANGUL CHOSEONG YEORINHIEUH;Lo;0;L;;;;;N;;;;; -115F;HANGUL CHOSEONG FILLER;Lo;0;L;;;;;N;;;;; -1160;HANGUL JUNGSEONG FILLER;Lo;0;L;;;;;N;;;;; -1161;HANGUL JUNGSEONG A;Lo;0;L;;;;;N;;;;; -1162;HANGUL JUNGSEONG AE;Lo;0;L;;;;;N;;;;; -1163;HANGUL JUNGSEONG YA;Lo;0;L;;;;;N;;;;; -1164;HANGUL JUNGSEONG YAE;Lo;0;L;;;;;N;;;;; -1165;HANGUL JUNGSEONG EO;Lo;0;L;;;;;N;;;;; -1166;HANGUL JUNGSEONG E;Lo;0;L;;;;;N;;;;; -1167;HANGUL JUNGSEONG YEO;Lo;0;L;;;;;N;;;;; -1168;HANGUL JUNGSEONG YE;Lo;0;L;;;;;N;;;;; -1169;HANGUL JUNGSEONG O;Lo;0;L;;;;;N;;;;; -116A;HANGUL JUNGSEONG WA;Lo;0;L;;;;;N;;;;; -116B;HANGUL JUNGSEONG WAE;Lo;0;L;;;;;N;;;;; -116C;HANGUL JUNGSEONG OE;Lo;0;L;;;;;N;;;;; -116D;HANGUL JUNGSEONG YO;Lo;0;L;;;;;N;;;;; -116E;HANGUL JUNGSEONG U;Lo;0;L;;;;;N;;;;; -116F;HANGUL JUNGSEONG WEO;Lo;0;L;;;;;N;;;;; -1170;HANGUL JUNGSEONG WE;Lo;0;L;;;;;N;;;;; -1171;HANGUL JUNGSEONG WI;Lo;0;L;;;;;N;;;;; -1172;HANGUL JUNGSEONG YU;Lo;0;L;;;;;N;;;;; -1173;HANGUL JUNGSEONG EU;Lo;0;L;;;;;N;;;;; -1174;HANGUL JUNGSEONG YI;Lo;0;L;;;;;N;;;;; -1175;HANGUL JUNGSEONG I;Lo;0;L;;;;;N;;;;; -1176;HANGUL JUNGSEONG A-O;Lo;0;L;;;;;N;;;;; -1177;HANGUL JUNGSEONG A-U;Lo;0;L;;;;;N;;;;; -1178;HANGUL JUNGSEONG YA-O;Lo;0;L;;;;;N;;;;; -1179;HANGUL JUNGSEONG YA-YO;Lo;0;L;;;;;N;;;;; -117A;HANGUL JUNGSEONG EO-O;Lo;0;L;;;;;N;;;;; -117B;HANGUL JUNGSEONG EO-U;Lo;0;L;;;;;N;;;;; -117C;HANGUL JUNGSEONG EO-EU;Lo;0;L;;;;;N;;;;; -117D;HANGUL JUNGSEONG YEO-O;Lo;0;L;;;;;N;;;;; -117E;HANGUL JUNGSEONG YEO-U;Lo;0;L;;;;;N;;;;; -117F;HANGUL JUNGSEONG O-EO;Lo;0;L;;;;;N;;;;; -1180;HANGUL JUNGSEONG O-E;Lo;0;L;;;;;N;;;;; -1181;HANGUL JUNGSEONG O-YE;Lo;0;L;;;;;N;;;;; -1182;HANGUL JUNGSEONG O-O;Lo;0;L;;;;;N;;;;; -1183;HANGUL JUNGSEONG O-U;Lo;0;L;;;;;N;;;;; -1184;HANGUL JUNGSEONG YO-YA;Lo;0;L;;;;;N;;;;; -1185;HANGUL JUNGSEONG YO-YAE;Lo;0;L;;;;;N;;;;; -1186;HANGUL JUNGSEONG YO-YEO;Lo;0;L;;;;;N;;;;; -1187;HANGUL JUNGSEONG YO-O;Lo;0;L;;;;;N;;;;; -1188;HANGUL JUNGSEONG YO-I;Lo;0;L;;;;;N;;;;; -1189;HANGUL JUNGSEONG U-A;Lo;0;L;;;;;N;;;;; -118A;HANGUL JUNGSEONG U-AE;Lo;0;L;;;;;N;;;;; -118B;HANGUL JUNGSEONG U-EO-EU;Lo;0;L;;;;;N;;;;; -118C;HANGUL JUNGSEONG U-YE;Lo;0;L;;;;;N;;;;; -118D;HANGUL JUNGSEONG U-U;Lo;0;L;;;;;N;;;;; -118E;HANGUL JUNGSEONG YU-A;Lo;0;L;;;;;N;;;;; -118F;HANGUL JUNGSEONG YU-EO;Lo;0;L;;;;;N;;;;; -1190;HANGUL JUNGSEONG YU-E;Lo;0;L;;;;;N;;;;; -1191;HANGUL JUNGSEONG YU-YEO;Lo;0;L;;;;;N;;;;; -1192;HANGUL JUNGSEONG YU-YE;Lo;0;L;;;;;N;;;;; -1193;HANGUL JUNGSEONG YU-U;Lo;0;L;;;;;N;;;;; -1194;HANGUL JUNGSEONG YU-I;Lo;0;L;;;;;N;;;;; -1195;HANGUL JUNGSEONG EU-U;Lo;0;L;;;;;N;;;;; -1196;HANGUL JUNGSEONG EU-EU;Lo;0;L;;;;;N;;;;; -1197;HANGUL JUNGSEONG YI-U;Lo;0;L;;;;;N;;;;; -1198;HANGUL JUNGSEONG I-A;Lo;0;L;;;;;N;;;;; -1199;HANGUL JUNGSEONG I-YA;Lo;0;L;;;;;N;;;;; -119A;HANGUL JUNGSEONG I-O;Lo;0;L;;;;;N;;;;; -119B;HANGUL JUNGSEONG I-U;Lo;0;L;;;;;N;;;;; -119C;HANGUL JUNGSEONG I-EU;Lo;0;L;;;;;N;;;;; -119D;HANGUL JUNGSEONG I-ARAEA;Lo;0;L;;;;;N;;;;; -119E;HANGUL JUNGSEONG ARAEA;Lo;0;L;;;;;N;;;;; -119F;HANGUL JUNGSEONG ARAEA-EO;Lo;0;L;;;;;N;;;;; -11A0;HANGUL JUNGSEONG ARAEA-U;Lo;0;L;;;;;N;;;;; -11A1;HANGUL JUNGSEONG ARAEA-I;Lo;0;L;;;;;N;;;;; -11A2;HANGUL JUNGSEONG SSANGARAEA;Lo;0;L;;;;;N;;;;; -11A8;HANGUL JONGSEONG KIYEOK;Lo;0;L;;;;;N;;g *;;; -11A9;HANGUL JONGSEONG SSANGKIYEOK;Lo;0;L;;;;;N;;gg *;;; -11AA;HANGUL JONGSEONG KIYEOK-SIOS;Lo;0;L;;;;;N;;gs *;;; -11AB;HANGUL JONGSEONG NIEUN;Lo;0;L;;;;;N;;n *;;; -11AC;HANGUL JONGSEONG NIEUN-CIEUC;Lo;0;L;;;;;N;;nj *;;; -11AD;HANGUL JONGSEONG NIEUN-HIEUH;Lo;0;L;;;;;N;;nh *;;; -11AE;HANGUL JONGSEONG TIKEUT;Lo;0;L;;;;;N;;d *;;; -11AF;HANGUL JONGSEONG RIEUL;Lo;0;L;;;;;N;;l *;;; -11B0;HANGUL JONGSEONG RIEUL-KIYEOK;Lo;0;L;;;;;N;;lg *;;; -11B1;HANGUL JONGSEONG RIEUL-MIEUM;Lo;0;L;;;;;N;;lm *;;; -11B2;HANGUL JONGSEONG RIEUL-PIEUP;Lo;0;L;;;;;N;;lb *;;; -11B3;HANGUL JONGSEONG RIEUL-SIOS;Lo;0;L;;;;;N;;ls *;;; -11B4;HANGUL JONGSEONG RIEUL-THIEUTH;Lo;0;L;;;;;N;;lt *;;; -11B5;HANGUL JONGSEONG RIEUL-PHIEUPH;Lo;0;L;;;;;N;;lp *;;; -11B6;HANGUL JONGSEONG RIEUL-HIEUH;Lo;0;L;;;;;N;;lh *;;; -11B7;HANGUL JONGSEONG MIEUM;Lo;0;L;;;;;N;;m *;;; -11B8;HANGUL JONGSEONG PIEUP;Lo;0;L;;;;;N;;b *;;; -11B9;HANGUL JONGSEONG PIEUP-SIOS;Lo;0;L;;;;;N;;bs *;;; -11BA;HANGUL JONGSEONG SIOS;Lo;0;L;;;;;N;;s *;;; -11BB;HANGUL JONGSEONG SSANGSIOS;Lo;0;L;;;;;N;;ss *;;; -11BC;HANGUL JONGSEONG IEUNG;Lo;0;L;;;;;N;;ng *;;; -11BD;HANGUL JONGSEONG CIEUC;Lo;0;L;;;;;N;;j *;;; -11BE;HANGUL JONGSEONG CHIEUCH;Lo;0;L;;;;;N;;c *;;; -11BF;HANGUL JONGSEONG KHIEUKH;Lo;0;L;;;;;N;;k *;;; -11C0;HANGUL JONGSEONG THIEUTH;Lo;0;L;;;;;N;;t *;;; -11C1;HANGUL JONGSEONG PHIEUPH;Lo;0;L;;;;;N;;p *;;; -11C2;HANGUL JONGSEONG HIEUH;Lo;0;L;;;;;N;;h *;;; -11C3;HANGUL JONGSEONG KIYEOK-RIEUL;Lo;0;L;;;;;N;;;;; -11C4;HANGUL JONGSEONG KIYEOK-SIOS-KIYEOK;Lo;0;L;;;;;N;;;;; -11C5;HANGUL JONGSEONG NIEUN-KIYEOK;Lo;0;L;;;;;N;;;;; -11C6;HANGUL JONGSEONG NIEUN-TIKEUT;Lo;0;L;;;;;N;;;;; -11C7;HANGUL JONGSEONG NIEUN-SIOS;Lo;0;L;;;;;N;;;;; -11C8;HANGUL JONGSEONG NIEUN-PANSIOS;Lo;0;L;;;;;N;;;;; -11C9;HANGUL JONGSEONG NIEUN-THIEUTH;Lo;0;L;;;;;N;;;;; -11CA;HANGUL JONGSEONG TIKEUT-KIYEOK;Lo;0;L;;;;;N;;;;; -11CB;HANGUL JONGSEONG TIKEUT-RIEUL;Lo;0;L;;;;;N;;;;; -11CC;HANGUL JONGSEONG RIEUL-KIYEOK-SIOS;Lo;0;L;;;;;N;;;;; -11CD;HANGUL JONGSEONG RIEUL-NIEUN;Lo;0;L;;;;;N;;;;; -11CE;HANGUL JONGSEONG RIEUL-TIKEUT;Lo;0;L;;;;;N;;;;; -11CF;HANGUL JONGSEONG RIEUL-TIKEUT-HIEUH;Lo;0;L;;;;;N;;;;; -11D0;HANGUL JONGSEONG SSANGRIEUL;Lo;0;L;;;;;N;;;;; -11D1;HANGUL JONGSEONG RIEUL-MIEUM-KIYEOK;Lo;0;L;;;;;N;;;;; -11D2;HANGUL JONGSEONG RIEUL-MIEUM-SIOS;Lo;0;L;;;;;N;;;;; -11D3;HANGUL JONGSEONG RIEUL-PIEUP-SIOS;Lo;0;L;;;;;N;;;;; -11D4;HANGUL JONGSEONG RIEUL-PIEUP-HIEUH;Lo;0;L;;;;;N;;;;; -11D5;HANGUL JONGSEONG RIEUL-KAPYEOUNPIEUP;Lo;0;L;;;;;N;;;;; -11D6;HANGUL JONGSEONG RIEUL-SSANGSIOS;Lo;0;L;;;;;N;;;;; -11D7;HANGUL JONGSEONG RIEUL-PANSIOS;Lo;0;L;;;;;N;;;;; -11D8;HANGUL JONGSEONG RIEUL-KHIEUKH;Lo;0;L;;;;;N;;;;; -11D9;HANGUL JONGSEONG RIEUL-YEORINHIEUH;Lo;0;L;;;;;N;;;;; -11DA;HANGUL JONGSEONG MIEUM-KIYEOK;Lo;0;L;;;;;N;;;;; -11DB;HANGUL JONGSEONG MIEUM-RIEUL;Lo;0;L;;;;;N;;;;; -11DC;HANGUL JONGSEONG MIEUM-PIEUP;Lo;0;L;;;;;N;;;;; -11DD;HANGUL JONGSEONG MIEUM-SIOS;Lo;0;L;;;;;N;;;;; -11DE;HANGUL JONGSEONG MIEUM-SSANGSIOS;Lo;0;L;;;;;N;;;;; -11DF;HANGUL JONGSEONG MIEUM-PANSIOS;Lo;0;L;;;;;N;;;;; -11E0;HANGUL JONGSEONG MIEUM-CHIEUCH;Lo;0;L;;;;;N;;;;; -11E1;HANGUL JONGSEONG MIEUM-HIEUH;Lo;0;L;;;;;N;;;;; -11E2;HANGUL JONGSEONG KAPYEOUNMIEUM;Lo;0;L;;;;;N;;;;; -11E3;HANGUL JONGSEONG PIEUP-RIEUL;Lo;0;L;;;;;N;;;;; -11E4;HANGUL JONGSEONG PIEUP-PHIEUPH;Lo;0;L;;;;;N;;;;; -11E5;HANGUL JONGSEONG PIEUP-HIEUH;Lo;0;L;;;;;N;;;;; -11E6;HANGUL JONGSEONG KAPYEOUNPIEUP;Lo;0;L;;;;;N;;;;; -11E7;HANGUL JONGSEONG SIOS-KIYEOK;Lo;0;L;;;;;N;;;;; -11E8;HANGUL JONGSEONG SIOS-TIKEUT;Lo;0;L;;;;;N;;;;; -11E9;HANGUL JONGSEONG SIOS-RIEUL;Lo;0;L;;;;;N;;;;; -11EA;HANGUL JONGSEONG SIOS-PIEUP;Lo;0;L;;;;;N;;;;; -11EB;HANGUL JONGSEONG PANSIOS;Lo;0;L;;;;;N;;;;; -11EC;HANGUL JONGSEONG IEUNG-KIYEOK;Lo;0;L;;;;;N;;;;; -11ED;HANGUL JONGSEONG IEUNG-SSANGKIYEOK;Lo;0;L;;;;;N;;;;; -11EE;HANGUL JONGSEONG SSANGIEUNG;Lo;0;L;;;;;N;;;;; -11EF;HANGUL JONGSEONG IEUNG-KHIEUKH;Lo;0;L;;;;;N;;;;; -11F0;HANGUL JONGSEONG YESIEUNG;Lo;0;L;;;;;N;;;;; -11F1;HANGUL JONGSEONG YESIEUNG-SIOS;Lo;0;L;;;;;N;;;;; -11F2;HANGUL JONGSEONG YESIEUNG-PANSIOS;Lo;0;L;;;;;N;;;;; -11F3;HANGUL JONGSEONG PHIEUPH-PIEUP;Lo;0;L;;;;;N;;;;; -11F4;HANGUL JONGSEONG KAPYEOUNPHIEUPH;Lo;0;L;;;;;N;;;;; -11F5;HANGUL JONGSEONG HIEUH-NIEUN;Lo;0;L;;;;;N;;;;; -11F6;HANGUL JONGSEONG HIEUH-RIEUL;Lo;0;L;;;;;N;;;;; -11F7;HANGUL JONGSEONG HIEUH-MIEUM;Lo;0;L;;;;;N;;;;; -11F8;HANGUL JONGSEONG HIEUH-PIEUP;Lo;0;L;;;;;N;;;;; -11F9;HANGUL JONGSEONG YEORINHIEUH;Lo;0;L;;;;;N;;;;; -1200;ETHIOPIC SYLLABLE HA;Lo;0;L;;;;;N;;;;; -1201;ETHIOPIC SYLLABLE HU;Lo;0;L;;;;;N;;;;; -1202;ETHIOPIC SYLLABLE HI;Lo;0;L;;;;;N;;;;; -1203;ETHIOPIC SYLLABLE HAA;Lo;0;L;;;;;N;;;;; -1204;ETHIOPIC SYLLABLE HEE;Lo;0;L;;;;;N;;;;; -1205;ETHIOPIC SYLLABLE HE;Lo;0;L;;;;;N;;;;; -1206;ETHIOPIC SYLLABLE HO;Lo;0;L;;;;;N;;;;; -1207;ETHIOPIC SYLLABLE HOA;Lo;0;L;;;;;N;;;;; -1208;ETHIOPIC SYLLABLE LA;Lo;0;L;;;;;N;;;;; -1209;ETHIOPIC SYLLABLE LU;Lo;0;L;;;;;N;;;;; -120A;ETHIOPIC SYLLABLE LI;Lo;0;L;;;;;N;;;;; -120B;ETHIOPIC SYLLABLE LAA;Lo;0;L;;;;;N;;;;; -120C;ETHIOPIC SYLLABLE LEE;Lo;0;L;;;;;N;;;;; -120D;ETHIOPIC SYLLABLE LE;Lo;0;L;;;;;N;;;;; -120E;ETHIOPIC SYLLABLE LO;Lo;0;L;;;;;N;;;;; -120F;ETHIOPIC SYLLABLE LWA;Lo;0;L;;;;;N;;;;; -1210;ETHIOPIC SYLLABLE HHA;Lo;0;L;;;;;N;;;;; -1211;ETHIOPIC SYLLABLE HHU;Lo;0;L;;;;;N;;;;; -1212;ETHIOPIC SYLLABLE HHI;Lo;0;L;;;;;N;;;;; -1213;ETHIOPIC SYLLABLE HHAA;Lo;0;L;;;;;N;;;;; -1214;ETHIOPIC SYLLABLE HHEE;Lo;0;L;;;;;N;;;;; -1215;ETHIOPIC SYLLABLE HHE;Lo;0;L;;;;;N;;;;; -1216;ETHIOPIC SYLLABLE HHO;Lo;0;L;;;;;N;;;;; -1217;ETHIOPIC SYLLABLE HHWA;Lo;0;L;;;;;N;;;;; -1218;ETHIOPIC SYLLABLE MA;Lo;0;L;;;;;N;;;;; -1219;ETHIOPIC SYLLABLE MU;Lo;0;L;;;;;N;;;;; -121A;ETHIOPIC SYLLABLE MI;Lo;0;L;;;;;N;;;;; -121B;ETHIOPIC SYLLABLE MAA;Lo;0;L;;;;;N;;;;; -121C;ETHIOPIC SYLLABLE MEE;Lo;0;L;;;;;N;;;;; -121D;ETHIOPIC SYLLABLE ME;Lo;0;L;;;;;N;;;;; -121E;ETHIOPIC SYLLABLE MO;Lo;0;L;;;;;N;;;;; -121F;ETHIOPIC SYLLABLE MWA;Lo;0;L;;;;;N;;;;; -1220;ETHIOPIC SYLLABLE SZA;Lo;0;L;;;;;N;;;;; -1221;ETHIOPIC SYLLABLE SZU;Lo;0;L;;;;;N;;;;; -1222;ETHIOPIC SYLLABLE SZI;Lo;0;L;;;;;N;;;;; -1223;ETHIOPIC SYLLABLE SZAA;Lo;0;L;;;;;N;;;;; -1224;ETHIOPIC SYLLABLE SZEE;Lo;0;L;;;;;N;;;;; -1225;ETHIOPIC SYLLABLE SZE;Lo;0;L;;;;;N;;;;; -1226;ETHIOPIC SYLLABLE SZO;Lo;0;L;;;;;N;;;;; -1227;ETHIOPIC SYLLABLE SZWA;Lo;0;L;;;;;N;;;;; -1228;ETHIOPIC SYLLABLE RA;Lo;0;L;;;;;N;;;;; -1229;ETHIOPIC SYLLABLE RU;Lo;0;L;;;;;N;;;;; -122A;ETHIOPIC SYLLABLE RI;Lo;0;L;;;;;N;;;;; -122B;ETHIOPIC SYLLABLE RAA;Lo;0;L;;;;;N;;;;; -122C;ETHIOPIC SYLLABLE REE;Lo;0;L;;;;;N;;;;; -122D;ETHIOPIC SYLLABLE RE;Lo;0;L;;;;;N;;;;; -122E;ETHIOPIC SYLLABLE RO;Lo;0;L;;;;;N;;;;; -122F;ETHIOPIC SYLLABLE RWA;Lo;0;L;;;;;N;;;;; -1230;ETHIOPIC SYLLABLE SA;Lo;0;L;;;;;N;;;;; -1231;ETHIOPIC SYLLABLE SU;Lo;0;L;;;;;N;;;;; -1232;ETHIOPIC SYLLABLE SI;Lo;0;L;;;;;N;;;;; -1233;ETHIOPIC SYLLABLE SAA;Lo;0;L;;;;;N;;;;; -1234;ETHIOPIC SYLLABLE SEE;Lo;0;L;;;;;N;;;;; -1235;ETHIOPIC SYLLABLE SE;Lo;0;L;;;;;N;;;;; -1236;ETHIOPIC SYLLABLE SO;Lo;0;L;;;;;N;;;;; -1237;ETHIOPIC SYLLABLE SWA;Lo;0;L;;;;;N;;;;; -1238;ETHIOPIC SYLLABLE SHA;Lo;0;L;;;;;N;;;;; -1239;ETHIOPIC SYLLABLE SHU;Lo;0;L;;;;;N;;;;; -123A;ETHIOPIC SYLLABLE SHI;Lo;0;L;;;;;N;;;;; -123B;ETHIOPIC SYLLABLE SHAA;Lo;0;L;;;;;N;;;;; -123C;ETHIOPIC SYLLABLE SHEE;Lo;0;L;;;;;N;;;;; -123D;ETHIOPIC SYLLABLE SHE;Lo;0;L;;;;;N;;;;; -123E;ETHIOPIC SYLLABLE SHO;Lo;0;L;;;;;N;;;;; -123F;ETHIOPIC SYLLABLE SHWA;Lo;0;L;;;;;N;;;;; -1240;ETHIOPIC SYLLABLE QA;Lo;0;L;;;;;N;;;;; -1241;ETHIOPIC SYLLABLE QU;Lo;0;L;;;;;N;;;;; -1242;ETHIOPIC SYLLABLE QI;Lo;0;L;;;;;N;;;;; -1243;ETHIOPIC SYLLABLE QAA;Lo;0;L;;;;;N;;;;; -1244;ETHIOPIC SYLLABLE QEE;Lo;0;L;;;;;N;;;;; -1245;ETHIOPIC SYLLABLE QE;Lo;0;L;;;;;N;;;;; -1246;ETHIOPIC SYLLABLE QO;Lo;0;L;;;;;N;;;;; -1247;ETHIOPIC SYLLABLE QOA;Lo;0;L;;;;;N;;;;; -1248;ETHIOPIC SYLLABLE QWA;Lo;0;L;;;;;N;;;;; -124A;ETHIOPIC SYLLABLE QWI;Lo;0;L;;;;;N;;;;; -124B;ETHIOPIC SYLLABLE QWAA;Lo;0;L;;;;;N;;;;; -124C;ETHIOPIC SYLLABLE QWEE;Lo;0;L;;;;;N;;;;; -124D;ETHIOPIC SYLLABLE QWE;Lo;0;L;;;;;N;;;;; -1250;ETHIOPIC SYLLABLE QHA;Lo;0;L;;;;;N;;;;; -1251;ETHIOPIC SYLLABLE QHU;Lo;0;L;;;;;N;;;;; -1252;ETHIOPIC SYLLABLE QHI;Lo;0;L;;;;;N;;;;; -1253;ETHIOPIC SYLLABLE QHAA;Lo;0;L;;;;;N;;;;; -1254;ETHIOPIC SYLLABLE QHEE;Lo;0;L;;;;;N;;;;; -1255;ETHIOPIC SYLLABLE QHE;Lo;0;L;;;;;N;;;;; -1256;ETHIOPIC SYLLABLE QHO;Lo;0;L;;;;;N;;;;; -1258;ETHIOPIC SYLLABLE QHWA;Lo;0;L;;;;;N;;;;; -125A;ETHIOPIC SYLLABLE QHWI;Lo;0;L;;;;;N;;;;; -125B;ETHIOPIC SYLLABLE QHWAA;Lo;0;L;;;;;N;;;;; -125C;ETHIOPIC SYLLABLE QHWEE;Lo;0;L;;;;;N;;;;; -125D;ETHIOPIC SYLLABLE QHWE;Lo;0;L;;;;;N;;;;; -1260;ETHIOPIC SYLLABLE BA;Lo;0;L;;;;;N;;;;; -1261;ETHIOPIC SYLLABLE BU;Lo;0;L;;;;;N;;;;; -1262;ETHIOPIC SYLLABLE BI;Lo;0;L;;;;;N;;;;; -1263;ETHIOPIC SYLLABLE BAA;Lo;0;L;;;;;N;;;;; -1264;ETHIOPIC SYLLABLE BEE;Lo;0;L;;;;;N;;;;; -1265;ETHIOPIC SYLLABLE BE;Lo;0;L;;;;;N;;;;; -1266;ETHIOPIC SYLLABLE BO;Lo;0;L;;;;;N;;;;; -1267;ETHIOPIC SYLLABLE BWA;Lo;0;L;;;;;N;;;;; -1268;ETHIOPIC SYLLABLE VA;Lo;0;L;;;;;N;;;;; -1269;ETHIOPIC SYLLABLE VU;Lo;0;L;;;;;N;;;;; -126A;ETHIOPIC SYLLABLE VI;Lo;0;L;;;;;N;;;;; -126B;ETHIOPIC SYLLABLE VAA;Lo;0;L;;;;;N;;;;; -126C;ETHIOPIC SYLLABLE VEE;Lo;0;L;;;;;N;;;;; -126D;ETHIOPIC SYLLABLE VE;Lo;0;L;;;;;N;;;;; -126E;ETHIOPIC SYLLABLE VO;Lo;0;L;;;;;N;;;;; -126F;ETHIOPIC SYLLABLE VWA;Lo;0;L;;;;;N;;;;; -1270;ETHIOPIC SYLLABLE TA;Lo;0;L;;;;;N;;;;; -1271;ETHIOPIC SYLLABLE TU;Lo;0;L;;;;;N;;;;; -1272;ETHIOPIC SYLLABLE TI;Lo;0;L;;;;;N;;;;; -1273;ETHIOPIC SYLLABLE TAA;Lo;0;L;;;;;N;;;;; -1274;ETHIOPIC SYLLABLE TEE;Lo;0;L;;;;;N;;;;; -1275;ETHIOPIC SYLLABLE TE;Lo;0;L;;;;;N;;;;; -1276;ETHIOPIC SYLLABLE TO;Lo;0;L;;;;;N;;;;; -1277;ETHIOPIC SYLLABLE TWA;Lo;0;L;;;;;N;;;;; -1278;ETHIOPIC SYLLABLE CA;Lo;0;L;;;;;N;;;;; -1279;ETHIOPIC SYLLABLE CU;Lo;0;L;;;;;N;;;;; -127A;ETHIOPIC SYLLABLE CI;Lo;0;L;;;;;N;;;;; -127B;ETHIOPIC SYLLABLE CAA;Lo;0;L;;;;;N;;;;; -127C;ETHIOPIC SYLLABLE CEE;Lo;0;L;;;;;N;;;;; -127D;ETHIOPIC SYLLABLE CE;Lo;0;L;;;;;N;;;;; -127E;ETHIOPIC SYLLABLE CO;Lo;0;L;;;;;N;;;;; -127F;ETHIOPIC SYLLABLE CWA;Lo;0;L;;;;;N;;;;; -1280;ETHIOPIC SYLLABLE XA;Lo;0;L;;;;;N;;;;; -1281;ETHIOPIC SYLLABLE XU;Lo;0;L;;;;;N;;;;; -1282;ETHIOPIC SYLLABLE XI;Lo;0;L;;;;;N;;;;; -1283;ETHIOPIC SYLLABLE XAA;Lo;0;L;;;;;N;;;;; -1284;ETHIOPIC SYLLABLE XEE;Lo;0;L;;;;;N;;;;; -1285;ETHIOPIC SYLLABLE XE;Lo;0;L;;;;;N;;;;; -1286;ETHIOPIC SYLLABLE XO;Lo;0;L;;;;;N;;;;; -1287;ETHIOPIC SYLLABLE XOA;Lo;0;L;;;;;N;;;;; -1288;ETHIOPIC SYLLABLE XWA;Lo;0;L;;;;;N;;;;; -128A;ETHIOPIC SYLLABLE XWI;Lo;0;L;;;;;N;;;;; -128B;ETHIOPIC SYLLABLE XWAA;Lo;0;L;;;;;N;;;;; -128C;ETHIOPIC SYLLABLE XWEE;Lo;0;L;;;;;N;;;;; -128D;ETHIOPIC SYLLABLE XWE;Lo;0;L;;;;;N;;;;; -1290;ETHIOPIC SYLLABLE NA;Lo;0;L;;;;;N;;;;; -1291;ETHIOPIC SYLLABLE NU;Lo;0;L;;;;;N;;;;; -1292;ETHIOPIC SYLLABLE NI;Lo;0;L;;;;;N;;;;; -1293;ETHIOPIC SYLLABLE NAA;Lo;0;L;;;;;N;;;;; -1294;ETHIOPIC SYLLABLE NEE;Lo;0;L;;;;;N;;;;; -1295;ETHIOPIC SYLLABLE NE;Lo;0;L;;;;;N;;;;; -1296;ETHIOPIC SYLLABLE NO;Lo;0;L;;;;;N;;;;; -1297;ETHIOPIC SYLLABLE NWA;Lo;0;L;;;;;N;;;;; -1298;ETHIOPIC SYLLABLE NYA;Lo;0;L;;;;;N;;;;; -1299;ETHIOPIC SYLLABLE NYU;Lo;0;L;;;;;N;;;;; -129A;ETHIOPIC SYLLABLE NYI;Lo;0;L;;;;;N;;;;; -129B;ETHIOPIC SYLLABLE NYAA;Lo;0;L;;;;;N;;;;; -129C;ETHIOPIC SYLLABLE NYEE;Lo;0;L;;;;;N;;;;; -129D;ETHIOPIC SYLLABLE NYE;Lo;0;L;;;;;N;;;;; -129E;ETHIOPIC SYLLABLE NYO;Lo;0;L;;;;;N;;;;; -129F;ETHIOPIC SYLLABLE NYWA;Lo;0;L;;;;;N;;;;; -12A0;ETHIOPIC SYLLABLE GLOTTAL A;Lo;0;L;;;;;N;;;;; -12A1;ETHIOPIC SYLLABLE GLOTTAL U;Lo;0;L;;;;;N;;;;; -12A2;ETHIOPIC SYLLABLE GLOTTAL I;Lo;0;L;;;;;N;;;;; -12A3;ETHIOPIC SYLLABLE GLOTTAL AA;Lo;0;L;;;;;N;;;;; -12A4;ETHIOPIC SYLLABLE GLOTTAL EE;Lo;0;L;;;;;N;;;;; -12A5;ETHIOPIC SYLLABLE GLOTTAL E;Lo;0;L;;;;;N;;;;; -12A6;ETHIOPIC SYLLABLE GLOTTAL O;Lo;0;L;;;;;N;;;;; -12A7;ETHIOPIC SYLLABLE GLOTTAL WA;Lo;0;L;;;;;N;;;;; -12A8;ETHIOPIC SYLLABLE KA;Lo;0;L;;;;;N;;;;; -12A9;ETHIOPIC SYLLABLE KU;Lo;0;L;;;;;N;;;;; -12AA;ETHIOPIC SYLLABLE KI;Lo;0;L;;;;;N;;;;; -12AB;ETHIOPIC SYLLABLE KAA;Lo;0;L;;;;;N;;;;; -12AC;ETHIOPIC SYLLABLE KEE;Lo;0;L;;;;;N;;;;; -12AD;ETHIOPIC SYLLABLE KE;Lo;0;L;;;;;N;;;;; -12AE;ETHIOPIC SYLLABLE KO;Lo;0;L;;;;;N;;;;; -12AF;ETHIOPIC SYLLABLE KOA;Lo;0;L;;;;;N;;;;; -12B0;ETHIOPIC SYLLABLE KWA;Lo;0;L;;;;;N;;;;; -12B2;ETHIOPIC SYLLABLE KWI;Lo;0;L;;;;;N;;;;; -12B3;ETHIOPIC SYLLABLE KWAA;Lo;0;L;;;;;N;;;;; -12B4;ETHIOPIC SYLLABLE KWEE;Lo;0;L;;;;;N;;;;; -12B5;ETHIOPIC SYLLABLE KWE;Lo;0;L;;;;;N;;;;; -12B8;ETHIOPIC SYLLABLE KXA;Lo;0;L;;;;;N;;;;; -12B9;ETHIOPIC SYLLABLE KXU;Lo;0;L;;;;;N;;;;; -12BA;ETHIOPIC SYLLABLE KXI;Lo;0;L;;;;;N;;;;; -12BB;ETHIOPIC SYLLABLE KXAA;Lo;0;L;;;;;N;;;;; -12BC;ETHIOPIC SYLLABLE KXEE;Lo;0;L;;;;;N;;;;; -12BD;ETHIOPIC SYLLABLE KXE;Lo;0;L;;;;;N;;;;; -12BE;ETHIOPIC SYLLABLE KXO;Lo;0;L;;;;;N;;;;; -12C0;ETHIOPIC SYLLABLE KXWA;Lo;0;L;;;;;N;;;;; -12C2;ETHIOPIC SYLLABLE KXWI;Lo;0;L;;;;;N;;;;; -12C3;ETHIOPIC SYLLABLE KXWAA;Lo;0;L;;;;;N;;;;; -12C4;ETHIOPIC SYLLABLE KXWEE;Lo;0;L;;;;;N;;;;; -12C5;ETHIOPIC SYLLABLE KXWE;Lo;0;L;;;;;N;;;;; -12C8;ETHIOPIC SYLLABLE WA;Lo;0;L;;;;;N;;;;; -12C9;ETHIOPIC SYLLABLE WU;Lo;0;L;;;;;N;;;;; -12CA;ETHIOPIC SYLLABLE WI;Lo;0;L;;;;;N;;;;; -12CB;ETHIOPIC SYLLABLE WAA;Lo;0;L;;;;;N;;;;; -12CC;ETHIOPIC SYLLABLE WEE;Lo;0;L;;;;;N;;;;; -12CD;ETHIOPIC SYLLABLE WE;Lo;0;L;;;;;N;;;;; -12CE;ETHIOPIC SYLLABLE WO;Lo;0;L;;;;;N;;;;; -12CF;ETHIOPIC SYLLABLE WOA;Lo;0;L;;;;;N;;;;; -12D0;ETHIOPIC SYLLABLE PHARYNGEAL A;Lo;0;L;;;;;N;;;;; -12D1;ETHIOPIC SYLLABLE PHARYNGEAL U;Lo;0;L;;;;;N;;;;; -12D2;ETHIOPIC SYLLABLE PHARYNGEAL I;Lo;0;L;;;;;N;;;;; -12D3;ETHIOPIC SYLLABLE PHARYNGEAL AA;Lo;0;L;;;;;N;;;;; -12D4;ETHIOPIC SYLLABLE PHARYNGEAL EE;Lo;0;L;;;;;N;;;;; -12D5;ETHIOPIC SYLLABLE PHARYNGEAL E;Lo;0;L;;;;;N;;;;; -12D6;ETHIOPIC SYLLABLE PHARYNGEAL O;Lo;0;L;;;;;N;;;;; -12D8;ETHIOPIC SYLLABLE ZA;Lo;0;L;;;;;N;;;;; -12D9;ETHIOPIC SYLLABLE ZU;Lo;0;L;;;;;N;;;;; -12DA;ETHIOPIC SYLLABLE ZI;Lo;0;L;;;;;N;;;;; -12DB;ETHIOPIC SYLLABLE ZAA;Lo;0;L;;;;;N;;;;; -12DC;ETHIOPIC SYLLABLE ZEE;Lo;0;L;;;;;N;;;;; -12DD;ETHIOPIC SYLLABLE ZE;Lo;0;L;;;;;N;;;;; -12DE;ETHIOPIC SYLLABLE ZO;Lo;0;L;;;;;N;;;;; -12DF;ETHIOPIC SYLLABLE ZWA;Lo;0;L;;;;;N;;;;; -12E0;ETHIOPIC SYLLABLE ZHA;Lo;0;L;;;;;N;;;;; -12E1;ETHIOPIC SYLLABLE ZHU;Lo;0;L;;;;;N;;;;; -12E2;ETHIOPIC SYLLABLE ZHI;Lo;0;L;;;;;N;;;;; -12E3;ETHIOPIC SYLLABLE ZHAA;Lo;0;L;;;;;N;;;;; -12E4;ETHIOPIC SYLLABLE ZHEE;Lo;0;L;;;;;N;;;;; -12E5;ETHIOPIC SYLLABLE ZHE;Lo;0;L;;;;;N;;;;; -12E6;ETHIOPIC SYLLABLE ZHO;Lo;0;L;;;;;N;;;;; -12E7;ETHIOPIC SYLLABLE ZHWA;Lo;0;L;;;;;N;;;;; -12E8;ETHIOPIC SYLLABLE YA;Lo;0;L;;;;;N;;;;; -12E9;ETHIOPIC SYLLABLE YU;Lo;0;L;;;;;N;;;;; -12EA;ETHIOPIC SYLLABLE YI;Lo;0;L;;;;;N;;;;; -12EB;ETHIOPIC SYLLABLE YAA;Lo;0;L;;;;;N;;;;; -12EC;ETHIOPIC SYLLABLE YEE;Lo;0;L;;;;;N;;;;; -12ED;ETHIOPIC SYLLABLE YE;Lo;0;L;;;;;N;;;;; -12EE;ETHIOPIC SYLLABLE YO;Lo;0;L;;;;;N;;;;; -12EF;ETHIOPIC SYLLABLE YOA;Lo;0;L;;;;;N;;;;; -12F0;ETHIOPIC SYLLABLE DA;Lo;0;L;;;;;N;;;;; -12F1;ETHIOPIC SYLLABLE DU;Lo;0;L;;;;;N;;;;; -12F2;ETHIOPIC SYLLABLE DI;Lo;0;L;;;;;N;;;;; -12F3;ETHIOPIC SYLLABLE DAA;Lo;0;L;;;;;N;;;;; -12F4;ETHIOPIC SYLLABLE DEE;Lo;0;L;;;;;N;;;;; -12F5;ETHIOPIC SYLLABLE DE;Lo;0;L;;;;;N;;;;; -12F6;ETHIOPIC SYLLABLE DO;Lo;0;L;;;;;N;;;;; -12F7;ETHIOPIC SYLLABLE DWA;Lo;0;L;;;;;N;;;;; -12F8;ETHIOPIC SYLLABLE DDA;Lo;0;L;;;;;N;;;;; -12F9;ETHIOPIC SYLLABLE DDU;Lo;0;L;;;;;N;;;;; -12FA;ETHIOPIC SYLLABLE DDI;Lo;0;L;;;;;N;;;;; -12FB;ETHIOPIC SYLLABLE DDAA;Lo;0;L;;;;;N;;;;; -12FC;ETHIOPIC SYLLABLE DDEE;Lo;0;L;;;;;N;;;;; -12FD;ETHIOPIC SYLLABLE DDE;Lo;0;L;;;;;N;;;;; -12FE;ETHIOPIC SYLLABLE DDO;Lo;0;L;;;;;N;;;;; -12FF;ETHIOPIC SYLLABLE DDWA;Lo;0;L;;;;;N;;;;; -1300;ETHIOPIC SYLLABLE JA;Lo;0;L;;;;;N;;;;; -1301;ETHIOPIC SYLLABLE JU;Lo;0;L;;;;;N;;;;; -1302;ETHIOPIC SYLLABLE JI;Lo;0;L;;;;;N;;;;; -1303;ETHIOPIC SYLLABLE JAA;Lo;0;L;;;;;N;;;;; -1304;ETHIOPIC SYLLABLE JEE;Lo;0;L;;;;;N;;;;; -1305;ETHIOPIC SYLLABLE JE;Lo;0;L;;;;;N;;;;; -1306;ETHIOPIC SYLLABLE JO;Lo;0;L;;;;;N;;;;; -1307;ETHIOPIC SYLLABLE JWA;Lo;0;L;;;;;N;;;;; -1308;ETHIOPIC SYLLABLE GA;Lo;0;L;;;;;N;;;;; -1309;ETHIOPIC SYLLABLE GU;Lo;0;L;;;;;N;;;;; -130A;ETHIOPIC SYLLABLE GI;Lo;0;L;;;;;N;;;;; -130B;ETHIOPIC SYLLABLE GAA;Lo;0;L;;;;;N;;;;; -130C;ETHIOPIC SYLLABLE GEE;Lo;0;L;;;;;N;;;;; -130D;ETHIOPIC SYLLABLE GE;Lo;0;L;;;;;N;;;;; -130E;ETHIOPIC SYLLABLE GO;Lo;0;L;;;;;N;;;;; -130F;ETHIOPIC SYLLABLE GOA;Lo;0;L;;;;;N;;;;; -1310;ETHIOPIC SYLLABLE GWA;Lo;0;L;;;;;N;;;;; -1312;ETHIOPIC SYLLABLE GWI;Lo;0;L;;;;;N;;;;; -1313;ETHIOPIC SYLLABLE GWAA;Lo;0;L;;;;;N;;;;; -1314;ETHIOPIC SYLLABLE GWEE;Lo;0;L;;;;;N;;;;; -1315;ETHIOPIC SYLLABLE GWE;Lo;0;L;;;;;N;;;;; -1318;ETHIOPIC SYLLABLE GGA;Lo;0;L;;;;;N;;;;; -1319;ETHIOPIC SYLLABLE GGU;Lo;0;L;;;;;N;;;;; -131A;ETHIOPIC SYLLABLE GGI;Lo;0;L;;;;;N;;;;; -131B;ETHIOPIC SYLLABLE GGAA;Lo;0;L;;;;;N;;;;; -131C;ETHIOPIC SYLLABLE GGEE;Lo;0;L;;;;;N;;;;; -131D;ETHIOPIC SYLLABLE GGE;Lo;0;L;;;;;N;;;;; -131E;ETHIOPIC SYLLABLE GGO;Lo;0;L;;;;;N;;;;; -131F;ETHIOPIC SYLLABLE GGWAA;Lo;0;L;;;;;N;;;;; -1320;ETHIOPIC SYLLABLE THA;Lo;0;L;;;;;N;;;;; -1321;ETHIOPIC SYLLABLE THU;Lo;0;L;;;;;N;;;;; -1322;ETHIOPIC SYLLABLE THI;Lo;0;L;;;;;N;;;;; -1323;ETHIOPIC SYLLABLE THAA;Lo;0;L;;;;;N;;;;; -1324;ETHIOPIC SYLLABLE THEE;Lo;0;L;;;;;N;;;;; -1325;ETHIOPIC SYLLABLE THE;Lo;0;L;;;;;N;;;;; -1326;ETHIOPIC SYLLABLE THO;Lo;0;L;;;;;N;;;;; -1327;ETHIOPIC SYLLABLE THWA;Lo;0;L;;;;;N;;;;; -1328;ETHIOPIC SYLLABLE CHA;Lo;0;L;;;;;N;;;;; -1329;ETHIOPIC SYLLABLE CHU;Lo;0;L;;;;;N;;;;; -132A;ETHIOPIC SYLLABLE CHI;Lo;0;L;;;;;N;;;;; -132B;ETHIOPIC SYLLABLE CHAA;Lo;0;L;;;;;N;;;;; -132C;ETHIOPIC SYLLABLE CHEE;Lo;0;L;;;;;N;;;;; -132D;ETHIOPIC SYLLABLE CHE;Lo;0;L;;;;;N;;;;; -132E;ETHIOPIC SYLLABLE CHO;Lo;0;L;;;;;N;;;;; -132F;ETHIOPIC SYLLABLE CHWA;Lo;0;L;;;;;N;;;;; -1330;ETHIOPIC SYLLABLE PHA;Lo;0;L;;;;;N;;;;; -1331;ETHIOPIC SYLLABLE PHU;Lo;0;L;;;;;N;;;;; -1332;ETHIOPIC SYLLABLE PHI;Lo;0;L;;;;;N;;;;; -1333;ETHIOPIC SYLLABLE PHAA;Lo;0;L;;;;;N;;;;; -1334;ETHIOPIC SYLLABLE PHEE;Lo;0;L;;;;;N;;;;; -1335;ETHIOPIC SYLLABLE PHE;Lo;0;L;;;;;N;;;;; -1336;ETHIOPIC SYLLABLE PHO;Lo;0;L;;;;;N;;;;; -1337;ETHIOPIC SYLLABLE PHWA;Lo;0;L;;;;;N;;;;; -1338;ETHIOPIC SYLLABLE TSA;Lo;0;L;;;;;N;;;;; -1339;ETHIOPIC SYLLABLE TSU;Lo;0;L;;;;;N;;;;; -133A;ETHIOPIC SYLLABLE TSI;Lo;0;L;;;;;N;;;;; -133B;ETHIOPIC SYLLABLE TSAA;Lo;0;L;;;;;N;;;;; -133C;ETHIOPIC SYLLABLE TSEE;Lo;0;L;;;;;N;;;;; -133D;ETHIOPIC SYLLABLE TSE;Lo;0;L;;;;;N;;;;; -133E;ETHIOPIC SYLLABLE TSO;Lo;0;L;;;;;N;;;;; -133F;ETHIOPIC SYLLABLE TSWA;Lo;0;L;;;;;N;;;;; -1340;ETHIOPIC SYLLABLE TZA;Lo;0;L;;;;;N;;;;; -1341;ETHIOPIC SYLLABLE TZU;Lo;0;L;;;;;N;;;;; -1342;ETHIOPIC SYLLABLE TZI;Lo;0;L;;;;;N;;;;; -1343;ETHIOPIC SYLLABLE TZAA;Lo;0;L;;;;;N;;;;; -1344;ETHIOPIC SYLLABLE TZEE;Lo;0;L;;;;;N;;;;; -1345;ETHIOPIC SYLLABLE TZE;Lo;0;L;;;;;N;;;;; -1346;ETHIOPIC SYLLABLE TZO;Lo;0;L;;;;;N;;;;; -1347;ETHIOPIC SYLLABLE TZOA;Lo;0;L;;;;;N;;;;; -1348;ETHIOPIC SYLLABLE FA;Lo;0;L;;;;;N;;;;; -1349;ETHIOPIC SYLLABLE FU;Lo;0;L;;;;;N;;;;; -134A;ETHIOPIC SYLLABLE FI;Lo;0;L;;;;;N;;;;; -134B;ETHIOPIC SYLLABLE FAA;Lo;0;L;;;;;N;;;;; -134C;ETHIOPIC SYLLABLE FEE;Lo;0;L;;;;;N;;;;; -134D;ETHIOPIC SYLLABLE FE;Lo;0;L;;;;;N;;;;; -134E;ETHIOPIC SYLLABLE FO;Lo;0;L;;;;;N;;;;; -134F;ETHIOPIC SYLLABLE FWA;Lo;0;L;;;;;N;;;;; -1350;ETHIOPIC SYLLABLE PA;Lo;0;L;;;;;N;;;;; -1351;ETHIOPIC SYLLABLE PU;Lo;0;L;;;;;N;;;;; -1352;ETHIOPIC SYLLABLE PI;Lo;0;L;;;;;N;;;;; -1353;ETHIOPIC SYLLABLE PAA;Lo;0;L;;;;;N;;;;; -1354;ETHIOPIC SYLLABLE PEE;Lo;0;L;;;;;N;;;;; -1355;ETHIOPIC SYLLABLE PE;Lo;0;L;;;;;N;;;;; -1356;ETHIOPIC SYLLABLE PO;Lo;0;L;;;;;N;;;;; -1357;ETHIOPIC SYLLABLE PWA;Lo;0;L;;;;;N;;;;; -1358;ETHIOPIC SYLLABLE RYA;Lo;0;L;;;;;N;;;;; -1359;ETHIOPIC SYLLABLE MYA;Lo;0;L;;;;;N;;;;; -135A;ETHIOPIC SYLLABLE FYA;Lo;0;L;;;;;N;;;;; -135F;ETHIOPIC COMBINING GEMINATION MARK;Mn;230;NSM;;;;;N;;;;; -1360;ETHIOPIC SECTION MARK;So;0;L;;;;;N;;;;; -1361;ETHIOPIC WORDSPACE;Po;0;L;;;;;N;;;;; -1362;ETHIOPIC FULL STOP;Po;0;L;;;;;N;;;;; -1363;ETHIOPIC COMMA;Po;0;L;;;;;N;;;;; -1364;ETHIOPIC SEMICOLON;Po;0;L;;;;;N;;;;; -1365;ETHIOPIC COLON;Po;0;L;;;;;N;;;;; -1366;ETHIOPIC PREFACE COLON;Po;0;L;;;;;N;;;;; -1367;ETHIOPIC QUESTION MARK;Po;0;L;;;;;N;;;;; -1368;ETHIOPIC PARAGRAPH SEPARATOR;Po;0;L;;;;;N;;;;; -1369;ETHIOPIC DIGIT ONE;No;0;L;;;1;1;N;;;;; -136A;ETHIOPIC DIGIT TWO;No;0;L;;;2;2;N;;;;; -136B;ETHIOPIC DIGIT THREE;No;0;L;;;3;3;N;;;;; -136C;ETHIOPIC DIGIT FOUR;No;0;L;;;4;4;N;;;;; -136D;ETHIOPIC DIGIT FIVE;No;0;L;;;5;5;N;;;;; -136E;ETHIOPIC DIGIT SIX;No;0;L;;;6;6;N;;;;; -136F;ETHIOPIC DIGIT SEVEN;No;0;L;;;7;7;N;;;;; -1370;ETHIOPIC DIGIT EIGHT;No;0;L;;;8;8;N;;;;; -1371;ETHIOPIC DIGIT NINE;No;0;L;;;9;9;N;;;;; -1372;ETHIOPIC NUMBER TEN;No;0;L;;;;10;N;;;;; -1373;ETHIOPIC NUMBER TWENTY;No;0;L;;;;20;N;;;;; -1374;ETHIOPIC NUMBER THIRTY;No;0;L;;;;30;N;;;;; -1375;ETHIOPIC NUMBER FORTY;No;0;L;;;;40;N;;;;; -1376;ETHIOPIC NUMBER FIFTY;No;0;L;;;;50;N;;;;; -1377;ETHIOPIC NUMBER SIXTY;No;0;L;;;;60;N;;;;; -1378;ETHIOPIC NUMBER SEVENTY;No;0;L;;;;70;N;;;;; -1379;ETHIOPIC NUMBER EIGHTY;No;0;L;;;;80;N;;;;; -137A;ETHIOPIC NUMBER NINETY;No;0;L;;;;90;N;;;;; -137B;ETHIOPIC NUMBER HUNDRED;No;0;L;;;;100;N;;;;; -137C;ETHIOPIC NUMBER TEN THOUSAND;No;0;L;;;;10000;N;;;;; -1380;ETHIOPIC SYLLABLE SEBATBEIT MWA;Lo;0;L;;;;;N;;;;; -1381;ETHIOPIC SYLLABLE MWI;Lo;0;L;;;;;N;;;;; -1382;ETHIOPIC SYLLABLE MWEE;Lo;0;L;;;;;N;;;;; -1383;ETHIOPIC SYLLABLE MWE;Lo;0;L;;;;;N;;;;; -1384;ETHIOPIC SYLLABLE SEBATBEIT BWA;Lo;0;L;;;;;N;;;;; -1385;ETHIOPIC SYLLABLE BWI;Lo;0;L;;;;;N;;;;; -1386;ETHIOPIC SYLLABLE BWEE;Lo;0;L;;;;;N;;;;; -1387;ETHIOPIC SYLLABLE BWE;Lo;0;L;;;;;N;;;;; -1388;ETHIOPIC SYLLABLE SEBATBEIT FWA;Lo;0;L;;;;;N;;;;; -1389;ETHIOPIC SYLLABLE FWI;Lo;0;L;;;;;N;;;;; -138A;ETHIOPIC SYLLABLE FWEE;Lo;0;L;;;;;N;;;;; -138B;ETHIOPIC SYLLABLE FWE;Lo;0;L;;;;;N;;;;; -138C;ETHIOPIC SYLLABLE SEBATBEIT PWA;Lo;0;L;;;;;N;;;;; -138D;ETHIOPIC SYLLABLE PWI;Lo;0;L;;;;;N;;;;; -138E;ETHIOPIC SYLLABLE PWEE;Lo;0;L;;;;;N;;;;; -138F;ETHIOPIC SYLLABLE PWE;Lo;0;L;;;;;N;;;;; -1390;ETHIOPIC TONAL MARK YIZET;So;0;ON;;;;;N;;;;; -1391;ETHIOPIC TONAL MARK DERET;So;0;ON;;;;;N;;;;; -1392;ETHIOPIC TONAL MARK RIKRIK;So;0;ON;;;;;N;;;;; -1393;ETHIOPIC TONAL MARK SHORT RIKRIK;So;0;ON;;;;;N;;;;; -1394;ETHIOPIC TONAL MARK DIFAT;So;0;ON;;;;;N;;;;; -1395;ETHIOPIC TONAL MARK KENAT;So;0;ON;;;;;N;;;;; -1396;ETHIOPIC TONAL MARK CHIRET;So;0;ON;;;;;N;;;;; -1397;ETHIOPIC TONAL MARK HIDET;So;0;ON;;;;;N;;;;; -1398;ETHIOPIC TONAL MARK DERET-HIDET;So;0;ON;;;;;N;;;;; -1399;ETHIOPIC TONAL MARK KURT;So;0;ON;;;;;N;;;;; -13A0;CHEROKEE LETTER A;Lo;0;L;;;;;N;;;;; -13A1;CHEROKEE LETTER E;Lo;0;L;;;;;N;;;;; -13A2;CHEROKEE LETTER I;Lo;0;L;;;;;N;;;;; -13A3;CHEROKEE LETTER O;Lo;0;L;;;;;N;;;;; -13A4;CHEROKEE LETTER U;Lo;0;L;;;;;N;;;;; -13A5;CHEROKEE LETTER V;Lo;0;L;;;;;N;;;;; -13A6;CHEROKEE LETTER GA;Lo;0;L;;;;;N;;;;; -13A7;CHEROKEE LETTER KA;Lo;0;L;;;;;N;;;;; -13A8;CHEROKEE LETTER GE;Lo;0;L;;;;;N;;;;; -13A9;CHEROKEE LETTER GI;Lo;0;L;;;;;N;;;;; -13AA;CHEROKEE LETTER GO;Lo;0;L;;;;;N;;;;; -13AB;CHEROKEE LETTER GU;Lo;0;L;;;;;N;;;;; -13AC;CHEROKEE LETTER GV;Lo;0;L;;;;;N;;;;; -13AD;CHEROKEE LETTER HA;Lo;0;L;;;;;N;;;;; -13AE;CHEROKEE LETTER HE;Lo;0;L;;;;;N;;;;; -13AF;CHEROKEE LETTER HI;Lo;0;L;;;;;N;;;;; -13B0;CHEROKEE LETTER HO;Lo;0;L;;;;;N;;;;; -13B1;CHEROKEE LETTER HU;Lo;0;L;;;;;N;;;;; -13B2;CHEROKEE LETTER HV;Lo;0;L;;;;;N;;;;; -13B3;CHEROKEE LETTER LA;Lo;0;L;;;;;N;;;;; -13B4;CHEROKEE LETTER LE;Lo;0;L;;;;;N;;;;; -13B5;CHEROKEE LETTER LI;Lo;0;L;;;;;N;;;;; -13B6;CHEROKEE LETTER LO;Lo;0;L;;;;;N;;;;; -13B7;CHEROKEE LETTER LU;Lo;0;L;;;;;N;;;;; -13B8;CHEROKEE LETTER LV;Lo;0;L;;;;;N;;;;; -13B9;CHEROKEE LETTER MA;Lo;0;L;;;;;N;;;;; -13BA;CHEROKEE LETTER ME;Lo;0;L;;;;;N;;;;; -13BB;CHEROKEE LETTER MI;Lo;0;L;;;;;N;;;;; -13BC;CHEROKEE LETTER MO;Lo;0;L;;;;;N;;;;; -13BD;CHEROKEE LETTER MU;Lo;0;L;;;;;N;;;;; -13BE;CHEROKEE LETTER NA;Lo;0;L;;;;;N;;;;; -13BF;CHEROKEE LETTER HNA;Lo;0;L;;;;;N;;;;; -13C0;CHEROKEE LETTER NAH;Lo;0;L;;;;;N;;;;; -13C1;CHEROKEE LETTER NE;Lo;0;L;;;;;N;;;;; -13C2;CHEROKEE LETTER NI;Lo;0;L;;;;;N;;;;; -13C3;CHEROKEE LETTER NO;Lo;0;L;;;;;N;;;;; -13C4;CHEROKEE LETTER NU;Lo;0;L;;;;;N;;;;; -13C5;CHEROKEE LETTER NV;Lo;0;L;;;;;N;;;;; -13C6;CHEROKEE LETTER QUA;Lo;0;L;;;;;N;;;;; -13C7;CHEROKEE LETTER QUE;Lo;0;L;;;;;N;;;;; -13C8;CHEROKEE LETTER QUI;Lo;0;L;;;;;N;;;;; -13C9;CHEROKEE LETTER QUO;Lo;0;L;;;;;N;;;;; -13CA;CHEROKEE LETTER QUU;Lo;0;L;;;;;N;;;;; -13CB;CHEROKEE LETTER QUV;Lo;0;L;;;;;N;;;;; -13CC;CHEROKEE LETTER SA;Lo;0;L;;;;;N;;;;; -13CD;CHEROKEE LETTER S;Lo;0;L;;;;;N;;;;; -13CE;CHEROKEE LETTER SE;Lo;0;L;;;;;N;;;;; -13CF;CHEROKEE LETTER SI;Lo;0;L;;;;;N;;;;; -13D0;CHEROKEE LETTER SO;Lo;0;L;;;;;N;;;;; -13D1;CHEROKEE LETTER SU;Lo;0;L;;;;;N;;;;; -13D2;CHEROKEE LETTER SV;Lo;0;L;;;;;N;;;;; -13D3;CHEROKEE LETTER DA;Lo;0;L;;;;;N;;;;; -13D4;CHEROKEE LETTER TA;Lo;0;L;;;;;N;;;;; -13D5;CHEROKEE LETTER DE;Lo;0;L;;;;;N;;;;; -13D6;CHEROKEE LETTER TE;Lo;0;L;;;;;N;;;;; -13D7;CHEROKEE LETTER DI;Lo;0;L;;;;;N;;;;; -13D8;CHEROKEE LETTER TI;Lo;0;L;;;;;N;;;;; -13D9;CHEROKEE LETTER DO;Lo;0;L;;;;;N;;;;; -13DA;CHEROKEE LETTER DU;Lo;0;L;;;;;N;;;;; -13DB;CHEROKEE LETTER DV;Lo;0;L;;;;;N;;;;; -13DC;CHEROKEE LETTER DLA;Lo;0;L;;;;;N;;;;; -13DD;CHEROKEE LETTER TLA;Lo;0;L;;;;;N;;;;; -13DE;CHEROKEE LETTER TLE;Lo;0;L;;;;;N;;;;; -13DF;CHEROKEE LETTER TLI;Lo;0;L;;;;;N;;;;; -13E0;CHEROKEE LETTER TLO;Lo;0;L;;;;;N;;;;; -13E1;CHEROKEE LETTER TLU;Lo;0;L;;;;;N;;;;; -13E2;CHEROKEE LETTER TLV;Lo;0;L;;;;;N;;;;; -13E3;CHEROKEE LETTER TSA;Lo;0;L;;;;;N;;;;; -13E4;CHEROKEE LETTER TSE;Lo;0;L;;;;;N;;;;; -13E5;CHEROKEE LETTER TSI;Lo;0;L;;;;;N;;;;; -13E6;CHEROKEE LETTER TSO;Lo;0;L;;;;;N;;;;; -13E7;CHEROKEE LETTER TSU;Lo;0;L;;;;;N;;;;; -13E8;CHEROKEE LETTER TSV;Lo;0;L;;;;;N;;;;; -13E9;CHEROKEE LETTER WA;Lo;0;L;;;;;N;;;;; -13EA;CHEROKEE LETTER WE;Lo;0;L;;;;;N;;;;; -13EB;CHEROKEE LETTER WI;Lo;0;L;;;;;N;;;;; -13EC;CHEROKEE LETTER WO;Lo;0;L;;;;;N;;;;; -13ED;CHEROKEE LETTER WU;Lo;0;L;;;;;N;;;;; -13EE;CHEROKEE LETTER WV;Lo;0;L;;;;;N;;;;; -13EF;CHEROKEE LETTER YA;Lo;0;L;;;;;N;;;;; -13F0;CHEROKEE LETTER YE;Lo;0;L;;;;;N;;;;; -13F1;CHEROKEE LETTER YI;Lo;0;L;;;;;N;;;;; -13F2;CHEROKEE LETTER YO;Lo;0;L;;;;;N;;;;; -13F3;CHEROKEE LETTER YU;Lo;0;L;;;;;N;;;;; -13F4;CHEROKEE LETTER YV;Lo;0;L;;;;;N;;;;; -1401;CANADIAN SYLLABICS E;Lo;0;L;;;;;N;;;;; -1402;CANADIAN SYLLABICS AAI;Lo;0;L;;;;;N;;;;; -1403;CANADIAN SYLLABICS I;Lo;0;L;;;;;N;;;;; -1404;CANADIAN SYLLABICS II;Lo;0;L;;;;;N;;;;; -1405;CANADIAN SYLLABICS O;Lo;0;L;;;;;N;;;;; -1406;CANADIAN SYLLABICS OO;Lo;0;L;;;;;N;;;;; -1407;CANADIAN SYLLABICS Y-CREE OO;Lo;0;L;;;;;N;;;;; -1408;CANADIAN SYLLABICS CARRIER EE;Lo;0;L;;;;;N;;;;; -1409;CANADIAN SYLLABICS CARRIER I;Lo;0;L;;;;;N;;;;; -140A;CANADIAN SYLLABICS A;Lo;0;L;;;;;N;;;;; -140B;CANADIAN SYLLABICS AA;Lo;0;L;;;;;N;;;;; -140C;CANADIAN SYLLABICS WE;Lo;0;L;;;;;N;;;;; -140D;CANADIAN SYLLABICS WEST-CREE WE;Lo;0;L;;;;;N;;;;; -140E;CANADIAN SYLLABICS WI;Lo;0;L;;;;;N;;;;; -140F;CANADIAN SYLLABICS WEST-CREE WI;Lo;0;L;;;;;N;;;;; -1410;CANADIAN SYLLABICS WII;Lo;0;L;;;;;N;;;;; -1411;CANADIAN SYLLABICS WEST-CREE WII;Lo;0;L;;;;;N;;;;; -1412;CANADIAN SYLLABICS WO;Lo;0;L;;;;;N;;;;; -1413;CANADIAN SYLLABICS WEST-CREE WO;Lo;0;L;;;;;N;;;;; -1414;CANADIAN SYLLABICS WOO;Lo;0;L;;;;;N;;;;; -1415;CANADIAN SYLLABICS WEST-CREE WOO;Lo;0;L;;;;;N;;;;; -1416;CANADIAN SYLLABICS NASKAPI WOO;Lo;0;L;;;;;N;;;;; -1417;CANADIAN SYLLABICS WA;Lo;0;L;;;;;N;;;;; -1418;CANADIAN SYLLABICS WEST-CREE WA;Lo;0;L;;;;;N;;;;; -1419;CANADIAN SYLLABICS WAA;Lo;0;L;;;;;N;;;;; -141A;CANADIAN SYLLABICS WEST-CREE WAA;Lo;0;L;;;;;N;;;;; -141B;CANADIAN SYLLABICS NASKAPI WAA;Lo;0;L;;;;;N;;;;; -141C;CANADIAN SYLLABICS AI;Lo;0;L;;;;;N;;;;; -141D;CANADIAN SYLLABICS Y-CREE W;Lo;0;L;;;;;N;;;;; -141E;CANADIAN SYLLABICS GLOTTAL STOP;Lo;0;L;;;;;N;;;;; -141F;CANADIAN SYLLABICS FINAL ACUTE;Lo;0;L;;;;;N;;;;; -1420;CANADIAN SYLLABICS FINAL GRAVE;Lo;0;L;;;;;N;;;;; -1421;CANADIAN SYLLABICS FINAL BOTTOM HALF RING;Lo;0;L;;;;;N;;;;; -1422;CANADIAN SYLLABICS FINAL TOP HALF RING;Lo;0;L;;;;;N;;;;; -1423;CANADIAN SYLLABICS FINAL RIGHT HALF RING;Lo;0;L;;;;;N;;;;; -1424;CANADIAN SYLLABICS FINAL RING;Lo;0;L;;;;;N;;;;; -1425;CANADIAN SYLLABICS FINAL DOUBLE ACUTE;Lo;0;L;;;;;N;;;;; -1426;CANADIAN SYLLABICS FINAL DOUBLE SHORT VERTICAL STROKES;Lo;0;L;;;;;N;;;;; -1427;CANADIAN SYLLABICS FINAL MIDDLE DOT;Lo;0;L;;;;;N;;;;; -1428;CANADIAN SYLLABICS FINAL SHORT HORIZONTAL STROKE;Lo;0;L;;;;;N;;;;; -1429;CANADIAN SYLLABICS FINAL PLUS;Lo;0;L;;;;;N;;;;; -142A;CANADIAN SYLLABICS FINAL DOWN TACK;Lo;0;L;;;;;N;;;;; -142B;CANADIAN SYLLABICS EN;Lo;0;L;;;;;N;;;;; -142C;CANADIAN SYLLABICS IN;Lo;0;L;;;;;N;;;;; -142D;CANADIAN SYLLABICS ON;Lo;0;L;;;;;N;;;;; -142E;CANADIAN SYLLABICS AN;Lo;0;L;;;;;N;;;;; -142F;CANADIAN SYLLABICS PE;Lo;0;L;;;;;N;;;;; -1430;CANADIAN SYLLABICS PAAI;Lo;0;L;;;;;N;;;;; -1431;CANADIAN SYLLABICS PI;Lo;0;L;;;;;N;;;;; -1432;CANADIAN SYLLABICS PII;Lo;0;L;;;;;N;;;;; -1433;CANADIAN SYLLABICS PO;Lo;0;L;;;;;N;;;;; -1434;CANADIAN SYLLABICS POO;Lo;0;L;;;;;N;;;;; -1435;CANADIAN SYLLABICS Y-CREE POO;Lo;0;L;;;;;N;;;;; -1436;CANADIAN SYLLABICS CARRIER HEE;Lo;0;L;;;;;N;;;;; -1437;CANADIAN SYLLABICS CARRIER HI;Lo;0;L;;;;;N;;;;; -1438;CANADIAN SYLLABICS PA;Lo;0;L;;;;;N;;;;; -1439;CANADIAN SYLLABICS PAA;Lo;0;L;;;;;N;;;;; -143A;CANADIAN SYLLABICS PWE;Lo;0;L;;;;;N;;;;; -143B;CANADIAN SYLLABICS WEST-CREE PWE;Lo;0;L;;;;;N;;;;; -143C;CANADIAN SYLLABICS PWI;Lo;0;L;;;;;N;;;;; -143D;CANADIAN SYLLABICS WEST-CREE PWI;Lo;0;L;;;;;N;;;;; -143E;CANADIAN SYLLABICS PWII;Lo;0;L;;;;;N;;;;; -143F;CANADIAN SYLLABICS WEST-CREE PWII;Lo;0;L;;;;;N;;;;; -1440;CANADIAN SYLLABICS PWO;Lo;0;L;;;;;N;;;;; -1441;CANADIAN SYLLABICS WEST-CREE PWO;Lo;0;L;;;;;N;;;;; -1442;CANADIAN SYLLABICS PWOO;Lo;0;L;;;;;N;;;;; -1443;CANADIAN SYLLABICS WEST-CREE PWOO;Lo;0;L;;;;;N;;;;; -1444;CANADIAN SYLLABICS PWA;Lo;0;L;;;;;N;;;;; -1445;CANADIAN SYLLABICS WEST-CREE PWA;Lo;0;L;;;;;N;;;;; -1446;CANADIAN SYLLABICS PWAA;Lo;0;L;;;;;N;;;;; -1447;CANADIAN SYLLABICS WEST-CREE PWAA;Lo;0;L;;;;;N;;;;; -1448;CANADIAN SYLLABICS Y-CREE PWAA;Lo;0;L;;;;;N;;;;; -1449;CANADIAN SYLLABICS P;Lo;0;L;;;;;N;;;;; -144A;CANADIAN SYLLABICS WEST-CREE P;Lo;0;L;;;;;N;;;;; -144B;CANADIAN SYLLABICS CARRIER H;Lo;0;L;;;;;N;;;;; -144C;CANADIAN SYLLABICS TE;Lo;0;L;;;;;N;;;;; -144D;CANADIAN SYLLABICS TAAI;Lo;0;L;;;;;N;;;;; -144E;CANADIAN SYLLABICS TI;Lo;0;L;;;;;N;;;;; -144F;CANADIAN SYLLABICS TII;Lo;0;L;;;;;N;;;;; -1450;CANADIAN SYLLABICS TO;Lo;0;L;;;;;N;;;;; -1451;CANADIAN SYLLABICS TOO;Lo;0;L;;;;;N;;;;; -1452;CANADIAN SYLLABICS Y-CREE TOO;Lo;0;L;;;;;N;;;;; -1453;CANADIAN SYLLABICS CARRIER DEE;Lo;0;L;;;;;N;;;;; -1454;CANADIAN SYLLABICS CARRIER DI;Lo;0;L;;;;;N;;;;; -1455;CANADIAN SYLLABICS TA;Lo;0;L;;;;;N;;;;; -1456;CANADIAN SYLLABICS TAA;Lo;0;L;;;;;N;;;;; -1457;CANADIAN SYLLABICS TWE;Lo;0;L;;;;;N;;;;; -1458;CANADIAN SYLLABICS WEST-CREE TWE;Lo;0;L;;;;;N;;;;; -1459;CANADIAN SYLLABICS TWI;Lo;0;L;;;;;N;;;;; -145A;CANADIAN SYLLABICS WEST-CREE TWI;Lo;0;L;;;;;N;;;;; -145B;CANADIAN SYLLABICS TWII;Lo;0;L;;;;;N;;;;; -145C;CANADIAN SYLLABICS WEST-CREE TWII;Lo;0;L;;;;;N;;;;; -145D;CANADIAN SYLLABICS TWO;Lo;0;L;;;;;N;;;;; -145E;CANADIAN SYLLABICS WEST-CREE TWO;Lo;0;L;;;;;N;;;;; -145F;CANADIAN SYLLABICS TWOO;Lo;0;L;;;;;N;;;;; -1460;CANADIAN SYLLABICS WEST-CREE TWOO;Lo;0;L;;;;;N;;;;; -1461;CANADIAN SYLLABICS TWA;Lo;0;L;;;;;N;;;;; -1462;CANADIAN SYLLABICS WEST-CREE TWA;Lo;0;L;;;;;N;;;;; -1463;CANADIAN SYLLABICS TWAA;Lo;0;L;;;;;N;;;;; -1464;CANADIAN SYLLABICS WEST-CREE TWAA;Lo;0;L;;;;;N;;;;; -1465;CANADIAN SYLLABICS NASKAPI TWAA;Lo;0;L;;;;;N;;;;; -1466;CANADIAN SYLLABICS T;Lo;0;L;;;;;N;;;;; -1467;CANADIAN SYLLABICS TTE;Lo;0;L;;;;;N;;;;; -1468;CANADIAN SYLLABICS TTI;Lo;0;L;;;;;N;;;;; -1469;CANADIAN SYLLABICS TTO;Lo;0;L;;;;;N;;;;; -146A;CANADIAN SYLLABICS TTA;Lo;0;L;;;;;N;;;;; -146B;CANADIAN SYLLABICS KE;Lo;0;L;;;;;N;;;;; -146C;CANADIAN SYLLABICS KAAI;Lo;0;L;;;;;N;;;;; -146D;CANADIAN SYLLABICS KI;Lo;0;L;;;;;N;;;;; -146E;CANADIAN SYLLABICS KII;Lo;0;L;;;;;N;;;;; -146F;CANADIAN SYLLABICS KO;Lo;0;L;;;;;N;;;;; -1470;CANADIAN SYLLABICS KOO;Lo;0;L;;;;;N;;;;; -1471;CANADIAN SYLLABICS Y-CREE KOO;Lo;0;L;;;;;N;;;;; -1472;CANADIAN SYLLABICS KA;Lo;0;L;;;;;N;;;;; -1473;CANADIAN SYLLABICS KAA;Lo;0;L;;;;;N;;;;; -1474;CANADIAN SYLLABICS KWE;Lo;0;L;;;;;N;;;;; -1475;CANADIAN SYLLABICS WEST-CREE KWE;Lo;0;L;;;;;N;;;;; -1476;CANADIAN SYLLABICS KWI;Lo;0;L;;;;;N;;;;; -1477;CANADIAN SYLLABICS WEST-CREE KWI;Lo;0;L;;;;;N;;;;; -1478;CANADIAN SYLLABICS KWII;Lo;0;L;;;;;N;;;;; -1479;CANADIAN SYLLABICS WEST-CREE KWII;Lo;0;L;;;;;N;;;;; -147A;CANADIAN SYLLABICS KWO;Lo;0;L;;;;;N;;;;; -147B;CANADIAN SYLLABICS WEST-CREE KWO;Lo;0;L;;;;;N;;;;; -147C;CANADIAN SYLLABICS KWOO;Lo;0;L;;;;;N;;;;; -147D;CANADIAN SYLLABICS WEST-CREE KWOO;Lo;0;L;;;;;N;;;;; -147E;CANADIAN SYLLABICS KWA;Lo;0;L;;;;;N;;;;; -147F;CANADIAN SYLLABICS WEST-CREE KWA;Lo;0;L;;;;;N;;;;; -1480;CANADIAN SYLLABICS KWAA;Lo;0;L;;;;;N;;;;; -1481;CANADIAN SYLLABICS WEST-CREE KWAA;Lo;0;L;;;;;N;;;;; -1482;CANADIAN SYLLABICS NASKAPI KWAA;Lo;0;L;;;;;N;;;;; -1483;CANADIAN SYLLABICS K;Lo;0;L;;;;;N;;;;; -1484;CANADIAN SYLLABICS KW;Lo;0;L;;;;;N;;;;; -1485;CANADIAN SYLLABICS SOUTH-SLAVEY KEH;Lo;0;L;;;;;N;;;;; -1486;CANADIAN SYLLABICS SOUTH-SLAVEY KIH;Lo;0;L;;;;;N;;;;; -1487;CANADIAN SYLLABICS SOUTH-SLAVEY KOH;Lo;0;L;;;;;N;;;;; -1488;CANADIAN SYLLABICS SOUTH-SLAVEY KAH;Lo;0;L;;;;;N;;;;; -1489;CANADIAN SYLLABICS CE;Lo;0;L;;;;;N;;;;; -148A;CANADIAN SYLLABICS CAAI;Lo;0;L;;;;;N;;;;; -148B;CANADIAN SYLLABICS CI;Lo;0;L;;;;;N;;;;; -148C;CANADIAN SYLLABICS CII;Lo;0;L;;;;;N;;;;; -148D;CANADIAN SYLLABICS CO;Lo;0;L;;;;;N;;;;; -148E;CANADIAN SYLLABICS COO;Lo;0;L;;;;;N;;;;; -148F;CANADIAN SYLLABICS Y-CREE COO;Lo;0;L;;;;;N;;;;; -1490;CANADIAN SYLLABICS CA;Lo;0;L;;;;;N;;;;; -1491;CANADIAN SYLLABICS CAA;Lo;0;L;;;;;N;;;;; -1492;CANADIAN SYLLABICS CWE;Lo;0;L;;;;;N;;;;; -1493;CANADIAN SYLLABICS WEST-CREE CWE;Lo;0;L;;;;;N;;;;; -1494;CANADIAN SYLLABICS CWI;Lo;0;L;;;;;N;;;;; -1495;CANADIAN SYLLABICS WEST-CREE CWI;Lo;0;L;;;;;N;;;;; -1496;CANADIAN SYLLABICS CWII;Lo;0;L;;;;;N;;;;; -1497;CANADIAN SYLLABICS WEST-CREE CWII;Lo;0;L;;;;;N;;;;; -1498;CANADIAN SYLLABICS CWO;Lo;0;L;;;;;N;;;;; -1499;CANADIAN SYLLABICS WEST-CREE CWO;Lo;0;L;;;;;N;;;;; -149A;CANADIAN SYLLABICS CWOO;Lo;0;L;;;;;N;;;;; -149B;CANADIAN SYLLABICS WEST-CREE CWOO;Lo;0;L;;;;;N;;;;; -149C;CANADIAN SYLLABICS CWA;Lo;0;L;;;;;N;;;;; -149D;CANADIAN SYLLABICS WEST-CREE CWA;Lo;0;L;;;;;N;;;;; -149E;CANADIAN SYLLABICS CWAA;Lo;0;L;;;;;N;;;;; -149F;CANADIAN SYLLABICS WEST-CREE CWAA;Lo;0;L;;;;;N;;;;; -14A0;CANADIAN SYLLABICS NASKAPI CWAA;Lo;0;L;;;;;N;;;;; -14A1;CANADIAN SYLLABICS C;Lo;0;L;;;;;N;;;;; -14A2;CANADIAN SYLLABICS SAYISI TH;Lo;0;L;;;;;N;;;;; -14A3;CANADIAN SYLLABICS ME;Lo;0;L;;;;;N;;;;; -14A4;CANADIAN SYLLABICS MAAI;Lo;0;L;;;;;N;;;;; -14A5;CANADIAN SYLLABICS MI;Lo;0;L;;;;;N;;;;; -14A6;CANADIAN SYLLABICS MII;Lo;0;L;;;;;N;;;;; -14A7;CANADIAN SYLLABICS MO;Lo;0;L;;;;;N;;;;; -14A8;CANADIAN SYLLABICS MOO;Lo;0;L;;;;;N;;;;; -14A9;CANADIAN SYLLABICS Y-CREE MOO;Lo;0;L;;;;;N;;;;; -14AA;CANADIAN SYLLABICS MA;Lo;0;L;;;;;N;;;;; -14AB;CANADIAN SYLLABICS MAA;Lo;0;L;;;;;N;;;;; -14AC;CANADIAN SYLLABICS MWE;Lo;0;L;;;;;N;;;;; -14AD;CANADIAN SYLLABICS WEST-CREE MWE;Lo;0;L;;;;;N;;;;; -14AE;CANADIAN SYLLABICS MWI;Lo;0;L;;;;;N;;;;; -14AF;CANADIAN SYLLABICS WEST-CREE MWI;Lo;0;L;;;;;N;;;;; -14B0;CANADIAN SYLLABICS MWII;Lo;0;L;;;;;N;;;;; -14B1;CANADIAN SYLLABICS WEST-CREE MWII;Lo;0;L;;;;;N;;;;; -14B2;CANADIAN SYLLABICS MWO;Lo;0;L;;;;;N;;;;; -14B3;CANADIAN SYLLABICS WEST-CREE MWO;Lo;0;L;;;;;N;;;;; -14B4;CANADIAN SYLLABICS MWOO;Lo;0;L;;;;;N;;;;; -14B5;CANADIAN SYLLABICS WEST-CREE MWOO;Lo;0;L;;;;;N;;;;; -14B6;CANADIAN SYLLABICS MWA;Lo;0;L;;;;;N;;;;; -14B7;CANADIAN SYLLABICS WEST-CREE MWA;Lo;0;L;;;;;N;;;;; -14B8;CANADIAN SYLLABICS MWAA;Lo;0;L;;;;;N;;;;; -14B9;CANADIAN SYLLABICS WEST-CREE MWAA;Lo;0;L;;;;;N;;;;; -14BA;CANADIAN SYLLABICS NASKAPI MWAA;Lo;0;L;;;;;N;;;;; -14BB;CANADIAN SYLLABICS M;Lo;0;L;;;;;N;;;;; -14BC;CANADIAN SYLLABICS WEST-CREE M;Lo;0;L;;;;;N;;;;; -14BD;CANADIAN SYLLABICS MH;Lo;0;L;;;;;N;;;;; -14BE;CANADIAN SYLLABICS ATHAPASCAN M;Lo;0;L;;;;;N;;;;; -14BF;CANADIAN SYLLABICS SAYISI M;Lo;0;L;;;;;N;;;;; -14C0;CANADIAN SYLLABICS NE;Lo;0;L;;;;;N;;;;; -14C1;CANADIAN SYLLABICS NAAI;Lo;0;L;;;;;N;;;;; -14C2;CANADIAN SYLLABICS NI;Lo;0;L;;;;;N;;;;; -14C3;CANADIAN SYLLABICS NII;Lo;0;L;;;;;N;;;;; -14C4;CANADIAN SYLLABICS NO;Lo;0;L;;;;;N;;;;; -14C5;CANADIAN SYLLABICS NOO;Lo;0;L;;;;;N;;;;; -14C6;CANADIAN SYLLABICS Y-CREE NOO;Lo;0;L;;;;;N;;;;; -14C7;CANADIAN SYLLABICS NA;Lo;0;L;;;;;N;;;;; -14C8;CANADIAN SYLLABICS NAA;Lo;0;L;;;;;N;;;;; -14C9;CANADIAN SYLLABICS NWE;Lo;0;L;;;;;N;;;;; -14CA;CANADIAN SYLLABICS WEST-CREE NWE;Lo;0;L;;;;;N;;;;; -14CB;CANADIAN SYLLABICS NWA;Lo;0;L;;;;;N;;;;; -14CC;CANADIAN SYLLABICS WEST-CREE NWA;Lo;0;L;;;;;N;;;;; -14CD;CANADIAN SYLLABICS NWAA;Lo;0;L;;;;;N;;;;; -14CE;CANADIAN SYLLABICS WEST-CREE NWAA;Lo;0;L;;;;;N;;;;; -14CF;CANADIAN SYLLABICS NASKAPI NWAA;Lo;0;L;;;;;N;;;;; -14D0;CANADIAN SYLLABICS N;Lo;0;L;;;;;N;;;;; -14D1;CANADIAN SYLLABICS CARRIER NG;Lo;0;L;;;;;N;;;;; -14D2;CANADIAN SYLLABICS NH;Lo;0;L;;;;;N;;;;; -14D3;CANADIAN SYLLABICS LE;Lo;0;L;;;;;N;;;;; -14D4;CANADIAN SYLLABICS LAAI;Lo;0;L;;;;;N;;;;; -14D5;CANADIAN SYLLABICS LI;Lo;0;L;;;;;N;;;;; -14D6;CANADIAN SYLLABICS LII;Lo;0;L;;;;;N;;;;; -14D7;CANADIAN SYLLABICS LO;Lo;0;L;;;;;N;;;;; -14D8;CANADIAN SYLLABICS LOO;Lo;0;L;;;;;N;;;;; -14D9;CANADIAN SYLLABICS Y-CREE LOO;Lo;0;L;;;;;N;;;;; -14DA;CANADIAN SYLLABICS LA;Lo;0;L;;;;;N;;;;; -14DB;CANADIAN SYLLABICS LAA;Lo;0;L;;;;;N;;;;; -14DC;CANADIAN SYLLABICS LWE;Lo;0;L;;;;;N;;;;; -14DD;CANADIAN SYLLABICS WEST-CREE LWE;Lo;0;L;;;;;N;;;;; -14DE;CANADIAN SYLLABICS LWI;Lo;0;L;;;;;N;;;;; -14DF;CANADIAN SYLLABICS WEST-CREE LWI;Lo;0;L;;;;;N;;;;; -14E0;CANADIAN SYLLABICS LWII;Lo;0;L;;;;;N;;;;; -14E1;CANADIAN SYLLABICS WEST-CREE LWII;Lo;0;L;;;;;N;;;;; -14E2;CANADIAN SYLLABICS LWO;Lo;0;L;;;;;N;;;;; -14E3;CANADIAN SYLLABICS WEST-CREE LWO;Lo;0;L;;;;;N;;;;; -14E4;CANADIAN SYLLABICS LWOO;Lo;0;L;;;;;N;;;;; -14E5;CANADIAN SYLLABICS WEST-CREE LWOO;Lo;0;L;;;;;N;;;;; -14E6;CANADIAN SYLLABICS LWA;Lo;0;L;;;;;N;;;;; -14E7;CANADIAN SYLLABICS WEST-CREE LWA;Lo;0;L;;;;;N;;;;; -14E8;CANADIAN SYLLABICS LWAA;Lo;0;L;;;;;N;;;;; -14E9;CANADIAN SYLLABICS WEST-CREE LWAA;Lo;0;L;;;;;N;;;;; -14EA;CANADIAN SYLLABICS L;Lo;0;L;;;;;N;;;;; -14EB;CANADIAN SYLLABICS WEST-CREE L;Lo;0;L;;;;;N;;;;; -14EC;CANADIAN SYLLABICS MEDIAL L;Lo;0;L;;;;;N;;;;; -14ED;CANADIAN SYLLABICS SE;Lo;0;L;;;;;N;;;;; -14EE;CANADIAN SYLLABICS SAAI;Lo;0;L;;;;;N;;;;; -14EF;CANADIAN SYLLABICS SI;Lo;0;L;;;;;N;;;;; -14F0;CANADIAN SYLLABICS SII;Lo;0;L;;;;;N;;;;; -14F1;CANADIAN SYLLABICS SO;Lo;0;L;;;;;N;;;;; -14F2;CANADIAN SYLLABICS SOO;Lo;0;L;;;;;N;;;;; -14F3;CANADIAN SYLLABICS Y-CREE SOO;Lo;0;L;;;;;N;;;;; -14F4;CANADIAN SYLLABICS SA;Lo;0;L;;;;;N;;;;; -14F5;CANADIAN SYLLABICS SAA;Lo;0;L;;;;;N;;;;; -14F6;CANADIAN SYLLABICS SWE;Lo;0;L;;;;;N;;;;; -14F7;CANADIAN SYLLABICS WEST-CREE SWE;Lo;0;L;;;;;N;;;;; -14F8;CANADIAN SYLLABICS SWI;Lo;0;L;;;;;N;;;;; -14F9;CANADIAN SYLLABICS WEST-CREE SWI;Lo;0;L;;;;;N;;;;; -14FA;CANADIAN SYLLABICS SWII;Lo;0;L;;;;;N;;;;; -14FB;CANADIAN SYLLABICS WEST-CREE SWII;Lo;0;L;;;;;N;;;;; -14FC;CANADIAN SYLLABICS SWO;Lo;0;L;;;;;N;;;;; -14FD;CANADIAN SYLLABICS WEST-CREE SWO;Lo;0;L;;;;;N;;;;; -14FE;CANADIAN SYLLABICS SWOO;Lo;0;L;;;;;N;;;;; -14FF;CANADIAN SYLLABICS WEST-CREE SWOO;Lo;0;L;;;;;N;;;;; -1500;CANADIAN SYLLABICS SWA;Lo;0;L;;;;;N;;;;; -1501;CANADIAN SYLLABICS WEST-CREE SWA;Lo;0;L;;;;;N;;;;; -1502;CANADIAN SYLLABICS SWAA;Lo;0;L;;;;;N;;;;; -1503;CANADIAN SYLLABICS WEST-CREE SWAA;Lo;0;L;;;;;N;;;;; -1504;CANADIAN SYLLABICS NASKAPI SWAA;Lo;0;L;;;;;N;;;;; -1505;CANADIAN SYLLABICS S;Lo;0;L;;;;;N;;;;; -1506;CANADIAN SYLLABICS ATHAPASCAN S;Lo;0;L;;;;;N;;;;; -1507;CANADIAN SYLLABICS SW;Lo;0;L;;;;;N;;;;; -1508;CANADIAN SYLLABICS BLACKFOOT S;Lo;0;L;;;;;N;;;;; -1509;CANADIAN SYLLABICS MOOSE-CREE SK;Lo;0;L;;;;;N;;;;; -150A;CANADIAN SYLLABICS NASKAPI SKW;Lo;0;L;;;;;N;;;;; -150B;CANADIAN SYLLABICS NASKAPI S-W;Lo;0;L;;;;;N;;;;; -150C;CANADIAN SYLLABICS NASKAPI SPWA;Lo;0;L;;;;;N;;;;; -150D;CANADIAN SYLLABICS NASKAPI STWA;Lo;0;L;;;;;N;;;;; -150E;CANADIAN SYLLABICS NASKAPI SKWA;Lo;0;L;;;;;N;;;;; -150F;CANADIAN SYLLABICS NASKAPI SCWA;Lo;0;L;;;;;N;;;;; -1510;CANADIAN SYLLABICS SHE;Lo;0;L;;;;;N;;;;; -1511;CANADIAN SYLLABICS SHI;Lo;0;L;;;;;N;;;;; -1512;CANADIAN SYLLABICS SHII;Lo;0;L;;;;;N;;;;; -1513;CANADIAN SYLLABICS SHO;Lo;0;L;;;;;N;;;;; -1514;CANADIAN SYLLABICS SHOO;Lo;0;L;;;;;N;;;;; -1515;CANADIAN SYLLABICS SHA;Lo;0;L;;;;;N;;;;; -1516;CANADIAN SYLLABICS SHAA;Lo;0;L;;;;;N;;;;; -1517;CANADIAN SYLLABICS SHWE;Lo;0;L;;;;;N;;;;; -1518;CANADIAN SYLLABICS WEST-CREE SHWE;Lo;0;L;;;;;N;;;;; -1519;CANADIAN SYLLABICS SHWI;Lo;0;L;;;;;N;;;;; -151A;CANADIAN SYLLABICS WEST-CREE SHWI;Lo;0;L;;;;;N;;;;; -151B;CANADIAN SYLLABICS SHWII;Lo;0;L;;;;;N;;;;; -151C;CANADIAN SYLLABICS WEST-CREE SHWII;Lo;0;L;;;;;N;;;;; -151D;CANADIAN SYLLABICS SHWO;Lo;0;L;;;;;N;;;;; -151E;CANADIAN SYLLABICS WEST-CREE SHWO;Lo;0;L;;;;;N;;;;; -151F;CANADIAN SYLLABICS SHWOO;Lo;0;L;;;;;N;;;;; -1520;CANADIAN SYLLABICS WEST-CREE SHWOO;Lo;0;L;;;;;N;;;;; -1521;CANADIAN SYLLABICS SHWA;Lo;0;L;;;;;N;;;;; -1522;CANADIAN SYLLABICS WEST-CREE SHWA;Lo;0;L;;;;;N;;;;; -1523;CANADIAN SYLLABICS SHWAA;Lo;0;L;;;;;N;;;;; -1524;CANADIAN SYLLABICS WEST-CREE SHWAA;Lo;0;L;;;;;N;;;;; -1525;CANADIAN SYLLABICS SH;Lo;0;L;;;;;N;;;;; -1526;CANADIAN SYLLABICS YE;Lo;0;L;;;;;N;;;;; -1527;CANADIAN SYLLABICS YAAI;Lo;0;L;;;;;N;;;;; -1528;CANADIAN SYLLABICS YI;Lo;0;L;;;;;N;;;;; -1529;CANADIAN SYLLABICS YII;Lo;0;L;;;;;N;;;;; -152A;CANADIAN SYLLABICS YO;Lo;0;L;;;;;N;;;;; -152B;CANADIAN SYLLABICS YOO;Lo;0;L;;;;;N;;;;; -152C;CANADIAN SYLLABICS Y-CREE YOO;Lo;0;L;;;;;N;;;;; -152D;CANADIAN SYLLABICS YA;Lo;0;L;;;;;N;;;;; -152E;CANADIAN SYLLABICS YAA;Lo;0;L;;;;;N;;;;; -152F;CANADIAN SYLLABICS YWE;Lo;0;L;;;;;N;;;;; -1530;CANADIAN SYLLABICS WEST-CREE YWE;Lo;0;L;;;;;N;;;;; -1531;CANADIAN SYLLABICS YWI;Lo;0;L;;;;;N;;;;; -1532;CANADIAN SYLLABICS WEST-CREE YWI;Lo;0;L;;;;;N;;;;; -1533;CANADIAN SYLLABICS YWII;Lo;0;L;;;;;N;;;;; -1534;CANADIAN SYLLABICS WEST-CREE YWII;Lo;0;L;;;;;N;;;;; -1535;CANADIAN SYLLABICS YWO;Lo;0;L;;;;;N;;;;; -1536;CANADIAN SYLLABICS WEST-CREE YWO;Lo;0;L;;;;;N;;;;; -1537;CANADIAN SYLLABICS YWOO;Lo;0;L;;;;;N;;;;; -1538;CANADIAN SYLLABICS WEST-CREE YWOO;Lo;0;L;;;;;N;;;;; -1539;CANADIAN SYLLABICS YWA;Lo;0;L;;;;;N;;;;; -153A;CANADIAN SYLLABICS WEST-CREE YWA;Lo;0;L;;;;;N;;;;; -153B;CANADIAN SYLLABICS YWAA;Lo;0;L;;;;;N;;;;; -153C;CANADIAN SYLLABICS WEST-CREE YWAA;Lo;0;L;;;;;N;;;;; -153D;CANADIAN SYLLABICS NASKAPI YWAA;Lo;0;L;;;;;N;;;;; -153E;CANADIAN SYLLABICS Y;Lo;0;L;;;;;N;;;;; -153F;CANADIAN SYLLABICS BIBLE-CREE Y;Lo;0;L;;;;;N;;;;; -1540;CANADIAN SYLLABICS WEST-CREE Y;Lo;0;L;;;;;N;;;;; -1541;CANADIAN SYLLABICS SAYISI YI;Lo;0;L;;;;;N;;;;; -1542;CANADIAN SYLLABICS RE;Lo;0;L;;;;;N;;;;; -1543;CANADIAN SYLLABICS R-CREE RE;Lo;0;L;;;;;N;;;;; -1544;CANADIAN SYLLABICS WEST-CREE LE;Lo;0;L;;;;;N;;;;; -1545;CANADIAN SYLLABICS RAAI;Lo;0;L;;;;;N;;;;; -1546;CANADIAN SYLLABICS RI;Lo;0;L;;;;;N;;;;; -1547;CANADIAN SYLLABICS RII;Lo;0;L;;;;;N;;;;; -1548;CANADIAN SYLLABICS RO;Lo;0;L;;;;;N;;;;; -1549;CANADIAN SYLLABICS ROO;Lo;0;L;;;;;N;;;;; -154A;CANADIAN SYLLABICS WEST-CREE LO;Lo;0;L;;;;;N;;;;; -154B;CANADIAN SYLLABICS RA;Lo;0;L;;;;;N;;;;; -154C;CANADIAN SYLLABICS RAA;Lo;0;L;;;;;N;;;;; -154D;CANADIAN SYLLABICS WEST-CREE LA;Lo;0;L;;;;;N;;;;; -154E;CANADIAN SYLLABICS RWAA;Lo;0;L;;;;;N;;;;; -154F;CANADIAN SYLLABICS WEST-CREE RWAA;Lo;0;L;;;;;N;;;;; -1550;CANADIAN SYLLABICS R;Lo;0;L;;;;;N;;;;; -1551;CANADIAN SYLLABICS WEST-CREE R;Lo;0;L;;;;;N;;;;; -1552;CANADIAN SYLLABICS MEDIAL R;Lo;0;L;;;;;N;;;;; -1553;CANADIAN SYLLABICS FE;Lo;0;L;;;;;N;;;;; -1554;CANADIAN SYLLABICS FAAI;Lo;0;L;;;;;N;;;;; -1555;CANADIAN SYLLABICS FI;Lo;0;L;;;;;N;;;;; -1556;CANADIAN SYLLABICS FII;Lo;0;L;;;;;N;;;;; -1557;CANADIAN SYLLABICS FO;Lo;0;L;;;;;N;;;;; -1558;CANADIAN SYLLABICS FOO;Lo;0;L;;;;;N;;;;; -1559;CANADIAN SYLLABICS FA;Lo;0;L;;;;;N;;;;; -155A;CANADIAN SYLLABICS FAA;Lo;0;L;;;;;N;;;;; -155B;CANADIAN SYLLABICS FWAA;Lo;0;L;;;;;N;;;;; -155C;CANADIAN SYLLABICS WEST-CREE FWAA;Lo;0;L;;;;;N;;;;; -155D;CANADIAN SYLLABICS F;Lo;0;L;;;;;N;;;;; -155E;CANADIAN SYLLABICS THE;Lo;0;L;;;;;N;;;;; -155F;CANADIAN SYLLABICS N-CREE THE;Lo;0;L;;;;;N;;;;; -1560;CANADIAN SYLLABICS THI;Lo;0;L;;;;;N;;;;; -1561;CANADIAN SYLLABICS N-CREE THI;Lo;0;L;;;;;N;;;;; -1562;CANADIAN SYLLABICS THII;Lo;0;L;;;;;N;;;;; -1563;CANADIAN SYLLABICS N-CREE THII;Lo;0;L;;;;;N;;;;; -1564;CANADIAN SYLLABICS THO;Lo;0;L;;;;;N;;;;; -1565;CANADIAN SYLLABICS THOO;Lo;0;L;;;;;N;;;;; -1566;CANADIAN SYLLABICS THA;Lo;0;L;;;;;N;;;;; -1567;CANADIAN SYLLABICS THAA;Lo;0;L;;;;;N;;;;; -1568;CANADIAN SYLLABICS THWAA;Lo;0;L;;;;;N;;;;; -1569;CANADIAN SYLLABICS WEST-CREE THWAA;Lo;0;L;;;;;N;;;;; -156A;CANADIAN SYLLABICS TH;Lo;0;L;;;;;N;;;;; -156B;CANADIAN SYLLABICS TTHE;Lo;0;L;;;;;N;;;;; -156C;CANADIAN SYLLABICS TTHI;Lo;0;L;;;;;N;;;;; -156D;CANADIAN SYLLABICS TTHO;Lo;0;L;;;;;N;;;;; -156E;CANADIAN SYLLABICS TTHA;Lo;0;L;;;;;N;;;;; -156F;CANADIAN SYLLABICS TTH;Lo;0;L;;;;;N;;;;; -1570;CANADIAN SYLLABICS TYE;Lo;0;L;;;;;N;;;;; -1571;CANADIAN SYLLABICS TYI;Lo;0;L;;;;;N;;;;; -1572;CANADIAN SYLLABICS TYO;Lo;0;L;;;;;N;;;;; -1573;CANADIAN SYLLABICS TYA;Lo;0;L;;;;;N;;;;; -1574;CANADIAN SYLLABICS NUNAVIK HE;Lo;0;L;;;;;N;;;;; -1575;CANADIAN SYLLABICS NUNAVIK HI;Lo;0;L;;;;;N;;;;; -1576;CANADIAN SYLLABICS NUNAVIK HII;Lo;0;L;;;;;N;;;;; -1577;CANADIAN SYLLABICS NUNAVIK HO;Lo;0;L;;;;;N;;;;; -1578;CANADIAN SYLLABICS NUNAVIK HOO;Lo;0;L;;;;;N;;;;; -1579;CANADIAN SYLLABICS NUNAVIK HA;Lo;0;L;;;;;N;;;;; -157A;CANADIAN SYLLABICS NUNAVIK HAA;Lo;0;L;;;;;N;;;;; -157B;CANADIAN SYLLABICS NUNAVIK H;Lo;0;L;;;;;N;;;;; -157C;CANADIAN SYLLABICS NUNAVUT H;Lo;0;L;;;;;N;;;;; -157D;CANADIAN SYLLABICS HK;Lo;0;L;;;;;N;;;;; -157E;CANADIAN SYLLABICS QAAI;Lo;0;L;;;;;N;;;;; -157F;CANADIAN SYLLABICS QI;Lo;0;L;;;;;N;;;;; -1580;CANADIAN SYLLABICS QII;Lo;0;L;;;;;N;;;;; -1581;CANADIAN SYLLABICS QO;Lo;0;L;;;;;N;;;;; -1582;CANADIAN SYLLABICS QOO;Lo;0;L;;;;;N;;;;; -1583;CANADIAN SYLLABICS QA;Lo;0;L;;;;;N;;;;; -1584;CANADIAN SYLLABICS QAA;Lo;0;L;;;;;N;;;;; -1585;CANADIAN SYLLABICS Q;Lo;0;L;;;;;N;;;;; -1586;CANADIAN SYLLABICS TLHE;Lo;0;L;;;;;N;;;;; -1587;CANADIAN SYLLABICS TLHI;Lo;0;L;;;;;N;;;;; -1588;CANADIAN SYLLABICS TLHO;Lo;0;L;;;;;N;;;;; -1589;CANADIAN SYLLABICS TLHA;Lo;0;L;;;;;N;;;;; -158A;CANADIAN SYLLABICS WEST-CREE RE;Lo;0;L;;;;;N;;;;; -158B;CANADIAN SYLLABICS WEST-CREE RI;Lo;0;L;;;;;N;;;;; -158C;CANADIAN SYLLABICS WEST-CREE RO;Lo;0;L;;;;;N;;;;; -158D;CANADIAN SYLLABICS WEST-CREE RA;Lo;0;L;;;;;N;;;;; -158E;CANADIAN SYLLABICS NGAAI;Lo;0;L;;;;;N;;;;; -158F;CANADIAN SYLLABICS NGI;Lo;0;L;;;;;N;;;;; -1590;CANADIAN SYLLABICS NGII;Lo;0;L;;;;;N;;;;; -1591;CANADIAN SYLLABICS NGO;Lo;0;L;;;;;N;;;;; -1592;CANADIAN SYLLABICS NGOO;Lo;0;L;;;;;N;;;;; -1593;CANADIAN SYLLABICS NGA;Lo;0;L;;;;;N;;;;; -1594;CANADIAN SYLLABICS NGAA;Lo;0;L;;;;;N;;;;; -1595;CANADIAN SYLLABICS NG;Lo;0;L;;;;;N;;;;; -1596;CANADIAN SYLLABICS NNG;Lo;0;L;;;;;N;;;;; -1597;CANADIAN SYLLABICS SAYISI SHE;Lo;0;L;;;;;N;;;;; -1598;CANADIAN SYLLABICS SAYISI SHI;Lo;0;L;;;;;N;;;;; -1599;CANADIAN SYLLABICS SAYISI SHO;Lo;0;L;;;;;N;;;;; -159A;CANADIAN SYLLABICS SAYISI SHA;Lo;0;L;;;;;N;;;;; -159B;CANADIAN SYLLABICS WOODS-CREE THE;Lo;0;L;;;;;N;;;;; -159C;CANADIAN SYLLABICS WOODS-CREE THI;Lo;0;L;;;;;N;;;;; -159D;CANADIAN SYLLABICS WOODS-CREE THO;Lo;0;L;;;;;N;;;;; -159E;CANADIAN SYLLABICS WOODS-CREE THA;Lo;0;L;;;;;N;;;;; -159F;CANADIAN SYLLABICS WOODS-CREE TH;Lo;0;L;;;;;N;;;;; -15A0;CANADIAN SYLLABICS LHI;Lo;0;L;;;;;N;;;;; -15A1;CANADIAN SYLLABICS LHII;Lo;0;L;;;;;N;;;;; -15A2;CANADIAN SYLLABICS LHO;Lo;0;L;;;;;N;;;;; -15A3;CANADIAN SYLLABICS LHOO;Lo;0;L;;;;;N;;;;; -15A4;CANADIAN SYLLABICS LHA;Lo;0;L;;;;;N;;;;; -15A5;CANADIAN SYLLABICS LHAA;Lo;0;L;;;;;N;;;;; -15A6;CANADIAN SYLLABICS LH;Lo;0;L;;;;;N;;;;; -15A7;CANADIAN SYLLABICS TH-CREE THE;Lo;0;L;;;;;N;;;;; -15A8;CANADIAN SYLLABICS TH-CREE THI;Lo;0;L;;;;;N;;;;; -15A9;CANADIAN SYLLABICS TH-CREE THII;Lo;0;L;;;;;N;;;;; -15AA;CANADIAN SYLLABICS TH-CREE THO;Lo;0;L;;;;;N;;;;; -15AB;CANADIAN SYLLABICS TH-CREE THOO;Lo;0;L;;;;;N;;;;; -15AC;CANADIAN SYLLABICS TH-CREE THA;Lo;0;L;;;;;N;;;;; -15AD;CANADIAN SYLLABICS TH-CREE THAA;Lo;0;L;;;;;N;;;;; -15AE;CANADIAN SYLLABICS TH-CREE TH;Lo;0;L;;;;;N;;;;; -15AF;CANADIAN SYLLABICS AIVILIK B;Lo;0;L;;;;;N;;;;; -15B0;CANADIAN SYLLABICS BLACKFOOT E;Lo;0;L;;;;;N;;;;; -15B1;CANADIAN SYLLABICS BLACKFOOT I;Lo;0;L;;;;;N;;;;; -15B2;CANADIAN SYLLABICS BLACKFOOT O;Lo;0;L;;;;;N;;;;; -15B3;CANADIAN SYLLABICS BLACKFOOT A;Lo;0;L;;;;;N;;;;; -15B4;CANADIAN SYLLABICS BLACKFOOT WE;Lo;0;L;;;;;N;;;;; -15B5;CANADIAN SYLLABICS BLACKFOOT WI;Lo;0;L;;;;;N;;;;; -15B6;CANADIAN SYLLABICS BLACKFOOT WO;Lo;0;L;;;;;N;;;;; -15B7;CANADIAN SYLLABICS BLACKFOOT WA;Lo;0;L;;;;;N;;;;; -15B8;CANADIAN SYLLABICS BLACKFOOT NE;Lo;0;L;;;;;N;;;;; -15B9;CANADIAN SYLLABICS BLACKFOOT NI;Lo;0;L;;;;;N;;;;; -15BA;CANADIAN SYLLABICS BLACKFOOT NO;Lo;0;L;;;;;N;;;;; -15BB;CANADIAN SYLLABICS BLACKFOOT NA;Lo;0;L;;;;;N;;;;; -15BC;CANADIAN SYLLABICS BLACKFOOT KE;Lo;0;L;;;;;N;;;;; -15BD;CANADIAN SYLLABICS BLACKFOOT KI;Lo;0;L;;;;;N;;;;; -15BE;CANADIAN SYLLABICS BLACKFOOT KO;Lo;0;L;;;;;N;;;;; -15BF;CANADIAN SYLLABICS BLACKFOOT KA;Lo;0;L;;;;;N;;;;; -15C0;CANADIAN SYLLABICS SAYISI HE;Lo;0;L;;;;;N;;;;; -15C1;CANADIAN SYLLABICS SAYISI HI;Lo;0;L;;;;;N;;;;; -15C2;CANADIAN SYLLABICS SAYISI HO;Lo;0;L;;;;;N;;;;; -15C3;CANADIAN SYLLABICS SAYISI HA;Lo;0;L;;;;;N;;;;; -15C4;CANADIAN SYLLABICS CARRIER GHU;Lo;0;L;;;;;N;;;;; -15C5;CANADIAN SYLLABICS CARRIER GHO;Lo;0;L;;;;;N;;;;; -15C6;CANADIAN SYLLABICS CARRIER GHE;Lo;0;L;;;;;N;;;;; -15C7;CANADIAN SYLLABICS CARRIER GHEE;Lo;0;L;;;;;N;;;;; -15C8;CANADIAN SYLLABICS CARRIER GHI;Lo;0;L;;;;;N;;;;; -15C9;CANADIAN SYLLABICS CARRIER GHA;Lo;0;L;;;;;N;;;;; -15CA;CANADIAN SYLLABICS CARRIER RU;Lo;0;L;;;;;N;;;;; -15CB;CANADIAN SYLLABICS CARRIER RO;Lo;0;L;;;;;N;;;;; -15CC;CANADIAN SYLLABICS CARRIER RE;Lo;0;L;;;;;N;;;;; -15CD;CANADIAN SYLLABICS CARRIER REE;Lo;0;L;;;;;N;;;;; -15CE;CANADIAN SYLLABICS CARRIER RI;Lo;0;L;;;;;N;;;;; -15CF;CANADIAN SYLLABICS CARRIER RA;Lo;0;L;;;;;N;;;;; -15D0;CANADIAN SYLLABICS CARRIER WU;Lo;0;L;;;;;N;;;;; -15D1;CANADIAN SYLLABICS CARRIER WO;Lo;0;L;;;;;N;;;;; -15D2;CANADIAN SYLLABICS CARRIER WE;Lo;0;L;;;;;N;;;;; -15D3;CANADIAN SYLLABICS CARRIER WEE;Lo;0;L;;;;;N;;;;; -15D4;CANADIAN SYLLABICS CARRIER WI;Lo;0;L;;;;;N;;;;; -15D5;CANADIAN SYLLABICS CARRIER WA;Lo;0;L;;;;;N;;;;; -15D6;CANADIAN SYLLABICS CARRIER HWU;Lo;0;L;;;;;N;;;;; -15D7;CANADIAN SYLLABICS CARRIER HWO;Lo;0;L;;;;;N;;;;; -15D8;CANADIAN SYLLABICS CARRIER HWE;Lo;0;L;;;;;N;;;;; -15D9;CANADIAN SYLLABICS CARRIER HWEE;Lo;0;L;;;;;N;;;;; -15DA;CANADIAN SYLLABICS CARRIER HWI;Lo;0;L;;;;;N;;;;; -15DB;CANADIAN SYLLABICS CARRIER HWA;Lo;0;L;;;;;N;;;;; -15DC;CANADIAN SYLLABICS CARRIER THU;Lo;0;L;;;;;N;;;;; -15DD;CANADIAN SYLLABICS CARRIER THO;Lo;0;L;;;;;N;;;;; -15DE;CANADIAN SYLLABICS CARRIER THE;Lo;0;L;;;;;N;;;;; -15DF;CANADIAN SYLLABICS CARRIER THEE;Lo;0;L;;;;;N;;;;; -15E0;CANADIAN SYLLABICS CARRIER THI;Lo;0;L;;;;;N;;;;; -15E1;CANADIAN SYLLABICS CARRIER THA;Lo;0;L;;;;;N;;;;; -15E2;CANADIAN SYLLABICS CARRIER TTU;Lo;0;L;;;;;N;;;;; -15E3;CANADIAN SYLLABICS CARRIER TTO;Lo;0;L;;;;;N;;;;; -15E4;CANADIAN SYLLABICS CARRIER TTE;Lo;0;L;;;;;N;;;;; -15E5;CANADIAN SYLLABICS CARRIER TTEE;Lo;0;L;;;;;N;;;;; -15E6;CANADIAN SYLLABICS CARRIER TTI;Lo;0;L;;;;;N;;;;; -15E7;CANADIAN SYLLABICS CARRIER TTA;Lo;0;L;;;;;N;;;;; -15E8;CANADIAN SYLLABICS CARRIER PU;Lo;0;L;;;;;N;;;;; -15E9;CANADIAN SYLLABICS CARRIER PO;Lo;0;L;;;;;N;;;;; -15EA;CANADIAN SYLLABICS CARRIER PE;Lo;0;L;;;;;N;;;;; -15EB;CANADIAN SYLLABICS CARRIER PEE;Lo;0;L;;;;;N;;;;; -15EC;CANADIAN SYLLABICS CARRIER PI;Lo;0;L;;;;;N;;;;; -15ED;CANADIAN SYLLABICS CARRIER PA;Lo;0;L;;;;;N;;;;; -15EE;CANADIAN SYLLABICS CARRIER P;Lo;0;L;;;;;N;;;;; -15EF;CANADIAN SYLLABICS CARRIER GU;Lo;0;L;;;;;N;;;;; -15F0;CANADIAN SYLLABICS CARRIER GO;Lo;0;L;;;;;N;;;;; -15F1;CANADIAN SYLLABICS CARRIER GE;Lo;0;L;;;;;N;;;;; -15F2;CANADIAN SYLLABICS CARRIER GEE;Lo;0;L;;;;;N;;;;; -15F3;CANADIAN SYLLABICS CARRIER GI;Lo;0;L;;;;;N;;;;; -15F4;CANADIAN SYLLABICS CARRIER GA;Lo;0;L;;;;;N;;;;; -15F5;CANADIAN SYLLABICS CARRIER KHU;Lo;0;L;;;;;N;;;;; -15F6;CANADIAN SYLLABICS CARRIER KHO;Lo;0;L;;;;;N;;;;; -15F7;CANADIAN SYLLABICS CARRIER KHE;Lo;0;L;;;;;N;;;;; -15F8;CANADIAN SYLLABICS CARRIER KHEE;Lo;0;L;;;;;N;;;;; -15F9;CANADIAN SYLLABICS CARRIER KHI;Lo;0;L;;;;;N;;;;; -15FA;CANADIAN SYLLABICS CARRIER KHA;Lo;0;L;;;;;N;;;;; -15FB;CANADIAN SYLLABICS CARRIER KKU;Lo;0;L;;;;;N;;;;; -15FC;CANADIAN SYLLABICS CARRIER KKO;Lo;0;L;;;;;N;;;;; -15FD;CANADIAN SYLLABICS CARRIER KKE;Lo;0;L;;;;;N;;;;; -15FE;CANADIAN SYLLABICS CARRIER KKEE;Lo;0;L;;;;;N;;;;; -15FF;CANADIAN SYLLABICS CARRIER KKI;Lo;0;L;;;;;N;;;;; -1600;CANADIAN SYLLABICS CARRIER KKA;Lo;0;L;;;;;N;;;;; -1601;CANADIAN SYLLABICS CARRIER KK;Lo;0;L;;;;;N;;;;; -1602;CANADIAN SYLLABICS CARRIER NU;Lo;0;L;;;;;N;;;;; -1603;CANADIAN SYLLABICS CARRIER NO;Lo;0;L;;;;;N;;;;; -1604;CANADIAN SYLLABICS CARRIER NE;Lo;0;L;;;;;N;;;;; -1605;CANADIAN SYLLABICS CARRIER NEE;Lo;0;L;;;;;N;;;;; -1606;CANADIAN SYLLABICS CARRIER NI;Lo;0;L;;;;;N;;;;; -1607;CANADIAN SYLLABICS CARRIER NA;Lo;0;L;;;;;N;;;;; -1608;CANADIAN SYLLABICS CARRIER MU;Lo;0;L;;;;;N;;;;; -1609;CANADIAN SYLLABICS CARRIER MO;Lo;0;L;;;;;N;;;;; -160A;CANADIAN SYLLABICS CARRIER ME;Lo;0;L;;;;;N;;;;; -160B;CANADIAN SYLLABICS CARRIER MEE;Lo;0;L;;;;;N;;;;; -160C;CANADIAN SYLLABICS CARRIER MI;Lo;0;L;;;;;N;;;;; -160D;CANADIAN SYLLABICS CARRIER MA;Lo;0;L;;;;;N;;;;; -160E;CANADIAN SYLLABICS CARRIER YU;Lo;0;L;;;;;N;;;;; -160F;CANADIAN SYLLABICS CARRIER YO;Lo;0;L;;;;;N;;;;; -1610;CANADIAN SYLLABICS CARRIER YE;Lo;0;L;;;;;N;;;;; -1611;CANADIAN SYLLABICS CARRIER YEE;Lo;0;L;;;;;N;;;;; -1612;CANADIAN SYLLABICS CARRIER YI;Lo;0;L;;;;;N;;;;; -1613;CANADIAN SYLLABICS CARRIER YA;Lo;0;L;;;;;N;;;;; -1614;CANADIAN SYLLABICS CARRIER JU;Lo;0;L;;;;;N;;;;; -1615;CANADIAN SYLLABICS SAYISI JU;Lo;0;L;;;;;N;;;;; -1616;CANADIAN SYLLABICS CARRIER JO;Lo;0;L;;;;;N;;;;; -1617;CANADIAN SYLLABICS CARRIER JE;Lo;0;L;;;;;N;;;;; -1618;CANADIAN SYLLABICS CARRIER JEE;Lo;0;L;;;;;N;;;;; -1619;CANADIAN SYLLABICS CARRIER JI;Lo;0;L;;;;;N;;;;; -161A;CANADIAN SYLLABICS SAYISI JI;Lo;0;L;;;;;N;;;;; -161B;CANADIAN SYLLABICS CARRIER JA;Lo;0;L;;;;;N;;;;; -161C;CANADIAN SYLLABICS CARRIER JJU;Lo;0;L;;;;;N;;;;; -161D;CANADIAN SYLLABICS CARRIER JJO;Lo;0;L;;;;;N;;;;; -161E;CANADIAN SYLLABICS CARRIER JJE;Lo;0;L;;;;;N;;;;; -161F;CANADIAN SYLLABICS CARRIER JJEE;Lo;0;L;;;;;N;;;;; -1620;CANADIAN SYLLABICS CARRIER JJI;Lo;0;L;;;;;N;;;;; -1621;CANADIAN SYLLABICS CARRIER JJA;Lo;0;L;;;;;N;;;;; -1622;CANADIAN SYLLABICS CARRIER LU;Lo;0;L;;;;;N;;;;; -1623;CANADIAN SYLLABICS CARRIER LO;Lo;0;L;;;;;N;;;;; -1624;CANADIAN SYLLABICS CARRIER LE;Lo;0;L;;;;;N;;;;; -1625;CANADIAN SYLLABICS CARRIER LEE;Lo;0;L;;;;;N;;;;; -1626;CANADIAN SYLLABICS CARRIER LI;Lo;0;L;;;;;N;;;;; -1627;CANADIAN SYLLABICS CARRIER LA;Lo;0;L;;;;;N;;;;; -1628;CANADIAN SYLLABICS CARRIER DLU;Lo;0;L;;;;;N;;;;; -1629;CANADIAN SYLLABICS CARRIER DLO;Lo;0;L;;;;;N;;;;; -162A;CANADIAN SYLLABICS CARRIER DLE;Lo;0;L;;;;;N;;;;; -162B;CANADIAN SYLLABICS CARRIER DLEE;Lo;0;L;;;;;N;;;;; -162C;CANADIAN SYLLABICS CARRIER DLI;Lo;0;L;;;;;N;;;;; -162D;CANADIAN SYLLABICS CARRIER DLA;Lo;0;L;;;;;N;;;;; -162E;CANADIAN SYLLABICS CARRIER LHU;Lo;0;L;;;;;N;;;;; -162F;CANADIAN SYLLABICS CARRIER LHO;Lo;0;L;;;;;N;;;;; -1630;CANADIAN SYLLABICS CARRIER LHE;Lo;0;L;;;;;N;;;;; -1631;CANADIAN SYLLABICS CARRIER LHEE;Lo;0;L;;;;;N;;;;; -1632;CANADIAN SYLLABICS CARRIER LHI;Lo;0;L;;;;;N;;;;; -1633;CANADIAN SYLLABICS CARRIER LHA;Lo;0;L;;;;;N;;;;; -1634;CANADIAN SYLLABICS CARRIER TLHU;Lo;0;L;;;;;N;;;;; -1635;CANADIAN SYLLABICS CARRIER TLHO;Lo;0;L;;;;;N;;;;; -1636;CANADIAN SYLLABICS CARRIER TLHE;Lo;0;L;;;;;N;;;;; -1637;CANADIAN SYLLABICS CARRIER TLHEE;Lo;0;L;;;;;N;;;;; -1638;CANADIAN SYLLABICS CARRIER TLHI;Lo;0;L;;;;;N;;;;; -1639;CANADIAN SYLLABICS CARRIER TLHA;Lo;0;L;;;;;N;;;;; -163A;CANADIAN SYLLABICS CARRIER TLU;Lo;0;L;;;;;N;;;;; -163B;CANADIAN SYLLABICS CARRIER TLO;Lo;0;L;;;;;N;;;;; -163C;CANADIAN SYLLABICS CARRIER TLE;Lo;0;L;;;;;N;;;;; -163D;CANADIAN SYLLABICS CARRIER TLEE;Lo;0;L;;;;;N;;;;; -163E;CANADIAN SYLLABICS CARRIER TLI;Lo;0;L;;;;;N;;;;; -163F;CANADIAN SYLLABICS CARRIER TLA;Lo;0;L;;;;;N;;;;; -1640;CANADIAN SYLLABICS CARRIER ZU;Lo;0;L;;;;;N;;;;; -1641;CANADIAN SYLLABICS CARRIER ZO;Lo;0;L;;;;;N;;;;; -1642;CANADIAN SYLLABICS CARRIER ZE;Lo;0;L;;;;;N;;;;; -1643;CANADIAN SYLLABICS CARRIER ZEE;Lo;0;L;;;;;N;;;;; -1644;CANADIAN SYLLABICS CARRIER ZI;Lo;0;L;;;;;N;;;;; -1645;CANADIAN SYLLABICS CARRIER ZA;Lo;0;L;;;;;N;;;;; -1646;CANADIAN SYLLABICS CARRIER Z;Lo;0;L;;;;;N;;;;; -1647;CANADIAN SYLLABICS CARRIER INITIAL Z;Lo;0;L;;;;;N;;;;; -1648;CANADIAN SYLLABICS CARRIER DZU;Lo;0;L;;;;;N;;;;; -1649;CANADIAN SYLLABICS CARRIER DZO;Lo;0;L;;;;;N;;;;; -164A;CANADIAN SYLLABICS CARRIER DZE;Lo;0;L;;;;;N;;;;; -164B;CANADIAN SYLLABICS CARRIER DZEE;Lo;0;L;;;;;N;;;;; -164C;CANADIAN SYLLABICS CARRIER DZI;Lo;0;L;;;;;N;;;;; -164D;CANADIAN SYLLABICS CARRIER DZA;Lo;0;L;;;;;N;;;;; -164E;CANADIAN SYLLABICS CARRIER SU;Lo;0;L;;;;;N;;;;; -164F;CANADIAN SYLLABICS CARRIER SO;Lo;0;L;;;;;N;;;;; -1650;CANADIAN SYLLABICS CARRIER SE;Lo;0;L;;;;;N;;;;; -1651;CANADIAN SYLLABICS CARRIER SEE;Lo;0;L;;;;;N;;;;; -1652;CANADIAN SYLLABICS CARRIER SI;Lo;0;L;;;;;N;;;;; -1653;CANADIAN SYLLABICS CARRIER SA;Lo;0;L;;;;;N;;;;; -1654;CANADIAN SYLLABICS CARRIER SHU;Lo;0;L;;;;;N;;;;; -1655;CANADIAN SYLLABICS CARRIER SHO;Lo;0;L;;;;;N;;;;; -1656;CANADIAN SYLLABICS CARRIER SHE;Lo;0;L;;;;;N;;;;; -1657;CANADIAN SYLLABICS CARRIER SHEE;Lo;0;L;;;;;N;;;;; -1658;CANADIAN SYLLABICS CARRIER SHI;Lo;0;L;;;;;N;;;;; -1659;CANADIAN SYLLABICS CARRIER SHA;Lo;0;L;;;;;N;;;;; -165A;CANADIAN SYLLABICS CARRIER SH;Lo;0;L;;;;;N;;;;; -165B;CANADIAN SYLLABICS CARRIER TSU;Lo;0;L;;;;;N;;;;; -165C;CANADIAN SYLLABICS CARRIER TSO;Lo;0;L;;;;;N;;;;; -165D;CANADIAN SYLLABICS CARRIER TSE;Lo;0;L;;;;;N;;;;; -165E;CANADIAN SYLLABICS CARRIER TSEE;Lo;0;L;;;;;N;;;;; -165F;CANADIAN SYLLABICS CARRIER TSI;Lo;0;L;;;;;N;;;;; -1660;CANADIAN SYLLABICS CARRIER TSA;Lo;0;L;;;;;N;;;;; -1661;CANADIAN SYLLABICS CARRIER CHU;Lo;0;L;;;;;N;;;;; -1662;CANADIAN SYLLABICS CARRIER CHO;Lo;0;L;;;;;N;;;;; -1663;CANADIAN SYLLABICS CARRIER CHE;Lo;0;L;;;;;N;;;;; -1664;CANADIAN SYLLABICS CARRIER CHEE;Lo;0;L;;;;;N;;;;; -1665;CANADIAN SYLLABICS CARRIER CHI;Lo;0;L;;;;;N;;;;; -1666;CANADIAN SYLLABICS CARRIER CHA;Lo;0;L;;;;;N;;;;; -1667;CANADIAN SYLLABICS CARRIER TTSU;Lo;0;L;;;;;N;;;;; -1668;CANADIAN SYLLABICS CARRIER TTSO;Lo;0;L;;;;;N;;;;; -1669;CANADIAN SYLLABICS CARRIER TTSE;Lo;0;L;;;;;N;;;;; -166A;CANADIAN SYLLABICS CARRIER TTSEE;Lo;0;L;;;;;N;;;;; -166B;CANADIAN SYLLABICS CARRIER TTSI;Lo;0;L;;;;;N;;;;; -166C;CANADIAN SYLLABICS CARRIER TTSA;Lo;0;L;;;;;N;;;;; -166D;CANADIAN SYLLABICS CHI SIGN;Po;0;L;;;;;N;;;;; -166E;CANADIAN SYLLABICS FULL STOP;Po;0;L;;;;;N;;;;; -166F;CANADIAN SYLLABICS QAI;Lo;0;L;;;;;N;;;;; -1670;CANADIAN SYLLABICS NGAI;Lo;0;L;;;;;N;;;;; -1671;CANADIAN SYLLABICS NNGI;Lo;0;L;;;;;N;;;;; -1672;CANADIAN SYLLABICS NNGII;Lo;0;L;;;;;N;;;;; -1673;CANADIAN SYLLABICS NNGO;Lo;0;L;;;;;N;;;;; -1674;CANADIAN SYLLABICS NNGOO;Lo;0;L;;;;;N;;;;; -1675;CANADIAN SYLLABICS NNGA;Lo;0;L;;;;;N;;;;; -1676;CANADIAN SYLLABICS NNGAA;Lo;0;L;;;;;N;;;;; -1680;OGHAM SPACE MARK;Zs;0;WS;;;;;N;;;;; -1681;OGHAM LETTER BEITH;Lo;0;L;;;;;N;;;;; -1682;OGHAM LETTER LUIS;Lo;0;L;;;;;N;;;;; -1683;OGHAM LETTER FEARN;Lo;0;L;;;;;N;;;;; -1684;OGHAM LETTER SAIL;Lo;0;L;;;;;N;;;;; -1685;OGHAM LETTER NION;Lo;0;L;;;;;N;;;;; -1686;OGHAM LETTER UATH;Lo;0;L;;;;;N;;;;; -1687;OGHAM LETTER DAIR;Lo;0;L;;;;;N;;;;; -1688;OGHAM LETTER TINNE;Lo;0;L;;;;;N;;;;; -1689;OGHAM LETTER COLL;Lo;0;L;;;;;N;;;;; -168A;OGHAM LETTER CEIRT;Lo;0;L;;;;;N;;;;; -168B;OGHAM LETTER MUIN;Lo;0;L;;;;;N;;;;; -168C;OGHAM LETTER GORT;Lo;0;L;;;;;N;;;;; -168D;OGHAM LETTER NGEADAL;Lo;0;L;;;;;N;;;;; -168E;OGHAM LETTER STRAIF;Lo;0;L;;;;;N;;;;; -168F;OGHAM LETTER RUIS;Lo;0;L;;;;;N;;;;; -1690;OGHAM LETTER AILM;Lo;0;L;;;;;N;;;;; -1691;OGHAM LETTER ONN;Lo;0;L;;;;;N;;;;; -1692;OGHAM LETTER UR;Lo;0;L;;;;;N;;;;; -1693;OGHAM LETTER EADHADH;Lo;0;L;;;;;N;;;;; -1694;OGHAM LETTER IODHADH;Lo;0;L;;;;;N;;;;; -1695;OGHAM LETTER EABHADH;Lo;0;L;;;;;N;;;;; -1696;OGHAM LETTER OR;Lo;0;L;;;;;N;;;;; -1697;OGHAM LETTER UILLEANN;Lo;0;L;;;;;N;;;;; -1698;OGHAM LETTER IFIN;Lo;0;L;;;;;N;;;;; -1699;OGHAM LETTER EAMHANCHOLL;Lo;0;L;;;;;N;;;;; -169A;OGHAM LETTER PEITH;Lo;0;L;;;;;N;;;;; -169B;OGHAM FEATHER MARK;Ps;0;ON;;;;;Y;;;;; -169C;OGHAM REVERSED FEATHER MARK;Pe;0;ON;;;;;Y;;;;; -16A0;RUNIC LETTER FEHU FEOH FE F;Lo;0;L;;;;;N;;;;; -16A1;RUNIC LETTER V;Lo;0;L;;;;;N;;;;; -16A2;RUNIC LETTER URUZ UR U;Lo;0;L;;;;;N;;;;; -16A3;RUNIC LETTER YR;Lo;0;L;;;;;N;;;;; -16A4;RUNIC LETTER Y;Lo;0;L;;;;;N;;;;; -16A5;RUNIC LETTER W;Lo;0;L;;;;;N;;;;; -16A6;RUNIC LETTER THURISAZ THURS THORN;Lo;0;L;;;;;N;;;;; -16A7;RUNIC LETTER ETH;Lo;0;L;;;;;N;;;;; -16A8;RUNIC LETTER ANSUZ A;Lo;0;L;;;;;N;;;;; -16A9;RUNIC LETTER OS O;Lo;0;L;;;;;N;;;;; -16AA;RUNIC LETTER AC A;Lo;0;L;;;;;N;;;;; -16AB;RUNIC LETTER AESC;Lo;0;L;;;;;N;;;;; -16AC;RUNIC LETTER LONG-BRANCH-OSS O;Lo;0;L;;;;;N;;;;; -16AD;RUNIC LETTER SHORT-TWIG-OSS O;Lo;0;L;;;;;N;;;;; -16AE;RUNIC LETTER O;Lo;0;L;;;;;N;;;;; -16AF;RUNIC LETTER OE;Lo;0;L;;;;;N;;;;; -16B0;RUNIC LETTER ON;Lo;0;L;;;;;N;;;;; -16B1;RUNIC LETTER RAIDO RAD REID R;Lo;0;L;;;;;N;;;;; -16B2;RUNIC LETTER KAUNA;Lo;0;L;;;;;N;;;;; -16B3;RUNIC LETTER CEN;Lo;0;L;;;;;N;;;;; -16B4;RUNIC LETTER KAUN K;Lo;0;L;;;;;N;;;;; -16B5;RUNIC LETTER G;Lo;0;L;;;;;N;;;;; -16B6;RUNIC LETTER ENG;Lo;0;L;;;;;N;;;;; -16B7;RUNIC LETTER GEBO GYFU G;Lo;0;L;;;;;N;;;;; -16B8;RUNIC LETTER GAR;Lo;0;L;;;;;N;;;;; -16B9;RUNIC LETTER WUNJO WYNN W;Lo;0;L;;;;;N;;;;; -16BA;RUNIC LETTER HAGLAZ H;Lo;0;L;;;;;N;;;;; -16BB;RUNIC LETTER HAEGL H;Lo;0;L;;;;;N;;;;; -16BC;RUNIC LETTER LONG-BRANCH-HAGALL H;Lo;0;L;;;;;N;;;;; -16BD;RUNIC LETTER SHORT-TWIG-HAGALL H;Lo;0;L;;;;;N;;;;; -16BE;RUNIC LETTER NAUDIZ NYD NAUD N;Lo;0;L;;;;;N;;;;; -16BF;RUNIC LETTER SHORT-TWIG-NAUD N;Lo;0;L;;;;;N;;;;; -16C0;RUNIC LETTER DOTTED-N;Lo;0;L;;;;;N;;;;; -16C1;RUNIC LETTER ISAZ IS ISS I;Lo;0;L;;;;;N;;;;; -16C2;RUNIC LETTER E;Lo;0;L;;;;;N;;;;; -16C3;RUNIC LETTER JERAN J;Lo;0;L;;;;;N;;;;; -16C4;RUNIC LETTER GER;Lo;0;L;;;;;N;;;;; -16C5;RUNIC LETTER LONG-BRANCH-AR AE;Lo;0;L;;;;;N;;;;; -16C6;RUNIC LETTER SHORT-TWIG-AR A;Lo;0;L;;;;;N;;;;; -16C7;RUNIC LETTER IWAZ EOH;Lo;0;L;;;;;N;;;;; -16C8;RUNIC LETTER PERTHO PEORTH P;Lo;0;L;;;;;N;;;;; -16C9;RUNIC LETTER ALGIZ EOLHX;Lo;0;L;;;;;N;;;;; -16CA;RUNIC LETTER SOWILO S;Lo;0;L;;;;;N;;;;; -16CB;RUNIC LETTER SIGEL LONG-BRANCH-SOL S;Lo;0;L;;;;;N;;;;; -16CC;RUNIC LETTER SHORT-TWIG-SOL S;Lo;0;L;;;;;N;;;;; -16CD;RUNIC LETTER C;Lo;0;L;;;;;N;;;;; -16CE;RUNIC LETTER Z;Lo;0;L;;;;;N;;;;; -16CF;RUNIC LETTER TIWAZ TIR TYR T;Lo;0;L;;;;;N;;;;; -16D0;RUNIC LETTER SHORT-TWIG-TYR T;Lo;0;L;;;;;N;;;;; -16D1;RUNIC LETTER D;Lo;0;L;;;;;N;;;;; -16D2;RUNIC LETTER BERKANAN BEORC BJARKAN B;Lo;0;L;;;;;N;;;;; -16D3;RUNIC LETTER SHORT-TWIG-BJARKAN B;Lo;0;L;;;;;N;;;;; -16D4;RUNIC LETTER DOTTED-P;Lo;0;L;;;;;N;;;;; -16D5;RUNIC LETTER OPEN-P;Lo;0;L;;;;;N;;;;; -16D6;RUNIC LETTER EHWAZ EH E;Lo;0;L;;;;;N;;;;; -16D7;RUNIC LETTER MANNAZ MAN M;Lo;0;L;;;;;N;;;;; -16D8;RUNIC LETTER LONG-BRANCH-MADR M;Lo;0;L;;;;;N;;;;; -16D9;RUNIC LETTER SHORT-TWIG-MADR M;Lo;0;L;;;;;N;;;;; -16DA;RUNIC LETTER LAUKAZ LAGU LOGR L;Lo;0;L;;;;;N;;;;; -16DB;RUNIC LETTER DOTTED-L;Lo;0;L;;;;;N;;;;; -16DC;RUNIC LETTER INGWAZ;Lo;0;L;;;;;N;;;;; -16DD;RUNIC LETTER ING;Lo;0;L;;;;;N;;;;; -16DE;RUNIC LETTER DAGAZ DAEG D;Lo;0;L;;;;;N;;;;; -16DF;RUNIC LETTER OTHALAN ETHEL O;Lo;0;L;;;;;N;;;;; -16E0;RUNIC LETTER EAR;Lo;0;L;;;;;N;;;;; -16E1;RUNIC LETTER IOR;Lo;0;L;;;;;N;;;;; -16E2;RUNIC LETTER CWEORTH;Lo;0;L;;;;;N;;;;; -16E3;RUNIC LETTER CALC;Lo;0;L;;;;;N;;;;; -16E4;RUNIC LETTER CEALC;Lo;0;L;;;;;N;;;;; -16E5;RUNIC LETTER STAN;Lo;0;L;;;;;N;;;;; -16E6;RUNIC LETTER LONG-BRANCH-YR;Lo;0;L;;;;;N;;;;; -16E7;RUNIC LETTER SHORT-TWIG-YR;Lo;0;L;;;;;N;;;;; -16E8;RUNIC LETTER ICELANDIC-YR;Lo;0;L;;;;;N;;;;; -16E9;RUNIC LETTER Q;Lo;0;L;;;;;N;;;;; -16EA;RUNIC LETTER X;Lo;0;L;;;;;N;;;;; -16EB;RUNIC SINGLE PUNCTUATION;Po;0;L;;;;;N;;;;; -16EC;RUNIC MULTIPLE PUNCTUATION;Po;0;L;;;;;N;;;;; -16ED;RUNIC CROSS PUNCTUATION;Po;0;L;;;;;N;;;;; -16EE;RUNIC ARLAUG SYMBOL;Nl;0;L;;;;17;N;;golden number 17;;; -16EF;RUNIC TVIMADUR SYMBOL;Nl;0;L;;;;18;N;;golden number 18;;; -16F0;RUNIC BELGTHOR SYMBOL;Nl;0;L;;;;19;N;;golden number 19;;; -1700;TAGALOG LETTER A;Lo;0;L;;;;;N;;;;; -1701;TAGALOG LETTER I;Lo;0;L;;;;;N;;;;; -1702;TAGALOG LETTER U;Lo;0;L;;;;;N;;;;; -1703;TAGALOG LETTER KA;Lo;0;L;;;;;N;;;;; -1704;TAGALOG LETTER GA;Lo;0;L;;;;;N;;;;; -1705;TAGALOG LETTER NGA;Lo;0;L;;;;;N;;;;; -1706;TAGALOG LETTER TA;Lo;0;L;;;;;N;;;;; -1707;TAGALOG LETTER DA;Lo;0;L;;;;;N;;;;; -1708;TAGALOG LETTER NA;Lo;0;L;;;;;N;;;;; -1709;TAGALOG LETTER PA;Lo;0;L;;;;;N;;;;; -170A;TAGALOG LETTER BA;Lo;0;L;;;;;N;;;;; -170B;TAGALOG LETTER MA;Lo;0;L;;;;;N;;;;; -170C;TAGALOG LETTER YA;Lo;0;L;;;;;N;;;;; -170E;TAGALOG LETTER LA;Lo;0;L;;;;;N;;;;; -170F;TAGALOG LETTER WA;Lo;0;L;;;;;N;;;;; -1710;TAGALOG LETTER SA;Lo;0;L;;;;;N;;;;; -1711;TAGALOG LETTER HA;Lo;0;L;;;;;N;;;;; -1712;TAGALOG VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -1713;TAGALOG VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1714;TAGALOG SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -1720;HANUNOO LETTER A;Lo;0;L;;;;;N;;;;; -1721;HANUNOO LETTER I;Lo;0;L;;;;;N;;;;; -1722;HANUNOO LETTER U;Lo;0;L;;;;;N;;;;; -1723;HANUNOO LETTER KA;Lo;0;L;;;;;N;;;;; -1724;HANUNOO LETTER GA;Lo;0;L;;;;;N;;;;; -1725;HANUNOO LETTER NGA;Lo;0;L;;;;;N;;;;; -1726;HANUNOO LETTER TA;Lo;0;L;;;;;N;;;;; -1727;HANUNOO LETTER DA;Lo;0;L;;;;;N;;;;; -1728;HANUNOO LETTER NA;Lo;0;L;;;;;N;;;;; -1729;HANUNOO LETTER PA;Lo;0;L;;;;;N;;;;; -172A;HANUNOO LETTER BA;Lo;0;L;;;;;N;;;;; -172B;HANUNOO LETTER MA;Lo;0;L;;;;;N;;;;; -172C;HANUNOO LETTER YA;Lo;0;L;;;;;N;;;;; -172D;HANUNOO LETTER RA;Lo;0;L;;;;;N;;;;; -172E;HANUNOO LETTER LA;Lo;0;L;;;;;N;;;;; -172F;HANUNOO LETTER WA;Lo;0;L;;;;;N;;;;; -1730;HANUNOO LETTER SA;Lo;0;L;;;;;N;;;;; -1731;HANUNOO LETTER HA;Lo;0;L;;;;;N;;;;; -1732;HANUNOO VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -1733;HANUNOO VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1734;HANUNOO SIGN PAMUDPOD;Mn;9;NSM;;;;;N;;;;; -1735;PHILIPPINE SINGLE PUNCTUATION;Po;0;L;;;;;N;;;;; -1736;PHILIPPINE DOUBLE PUNCTUATION;Po;0;L;;;;;N;;;;; -1740;BUHID LETTER A;Lo;0;L;;;;;N;;;;; -1741;BUHID LETTER I;Lo;0;L;;;;;N;;;;; -1742;BUHID LETTER U;Lo;0;L;;;;;N;;;;; -1743;BUHID LETTER KA;Lo;0;L;;;;;N;;;;; -1744;BUHID LETTER GA;Lo;0;L;;;;;N;;;;; -1745;BUHID LETTER NGA;Lo;0;L;;;;;N;;;;; -1746;BUHID LETTER TA;Lo;0;L;;;;;N;;;;; -1747;BUHID LETTER DA;Lo;0;L;;;;;N;;;;; -1748;BUHID LETTER NA;Lo;0;L;;;;;N;;;;; -1749;BUHID LETTER PA;Lo;0;L;;;;;N;;;;; -174A;BUHID LETTER BA;Lo;0;L;;;;;N;;;;; -174B;BUHID LETTER MA;Lo;0;L;;;;;N;;;;; -174C;BUHID LETTER YA;Lo;0;L;;;;;N;;;;; -174D;BUHID LETTER RA;Lo;0;L;;;;;N;;;;; -174E;BUHID LETTER LA;Lo;0;L;;;;;N;;;;; -174F;BUHID LETTER WA;Lo;0;L;;;;;N;;;;; -1750;BUHID LETTER SA;Lo;0;L;;;;;N;;;;; -1751;BUHID LETTER HA;Lo;0;L;;;;;N;;;;; -1752;BUHID VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -1753;BUHID VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1760;TAGBANWA LETTER A;Lo;0;L;;;;;N;;;;; -1761;TAGBANWA LETTER I;Lo;0;L;;;;;N;;;;; -1762;TAGBANWA LETTER U;Lo;0;L;;;;;N;;;;; -1763;TAGBANWA LETTER KA;Lo;0;L;;;;;N;;;;; -1764;TAGBANWA LETTER GA;Lo;0;L;;;;;N;;;;; -1765;TAGBANWA LETTER NGA;Lo;0;L;;;;;N;;;;; -1766;TAGBANWA LETTER TA;Lo;0;L;;;;;N;;;;; -1767;TAGBANWA LETTER DA;Lo;0;L;;;;;N;;;;; -1768;TAGBANWA LETTER NA;Lo;0;L;;;;;N;;;;; -1769;TAGBANWA LETTER PA;Lo;0;L;;;;;N;;;;; -176A;TAGBANWA LETTER BA;Lo;0;L;;;;;N;;;;; -176B;TAGBANWA LETTER MA;Lo;0;L;;;;;N;;;;; -176C;TAGBANWA LETTER YA;Lo;0;L;;;;;N;;;;; -176E;TAGBANWA LETTER LA;Lo;0;L;;;;;N;;;;; -176F;TAGBANWA LETTER WA;Lo;0;L;;;;;N;;;;; -1770;TAGBANWA LETTER SA;Lo;0;L;;;;;N;;;;; -1772;TAGBANWA VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -1773;TAGBANWA VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1780;KHMER LETTER KA;Lo;0;L;;;;;N;;;;; -1781;KHMER LETTER KHA;Lo;0;L;;;;;N;;;;; -1782;KHMER LETTER KO;Lo;0;L;;;;;N;;;;; -1783;KHMER LETTER KHO;Lo;0;L;;;;;N;;;;; -1784;KHMER LETTER NGO;Lo;0;L;;;;;N;;;;; -1785;KHMER LETTER CA;Lo;0;L;;;;;N;;;;; -1786;KHMER LETTER CHA;Lo;0;L;;;;;N;;;;; -1787;KHMER LETTER CO;Lo;0;L;;;;;N;;;;; -1788;KHMER LETTER CHO;Lo;0;L;;;;;N;;;;; -1789;KHMER LETTER NYO;Lo;0;L;;;;;N;;;;; -178A;KHMER LETTER DA;Lo;0;L;;;;;N;;;;; -178B;KHMER LETTER TTHA;Lo;0;L;;;;;N;;;;; -178C;KHMER LETTER DO;Lo;0;L;;;;;N;;;;; -178D;KHMER LETTER TTHO;Lo;0;L;;;;;N;;;;; -178E;KHMER LETTER NNO;Lo;0;L;;;;;N;;;;; -178F;KHMER LETTER TA;Lo;0;L;;;;;N;;;;; -1790;KHMER LETTER THA;Lo;0;L;;;;;N;;;;; -1791;KHMER LETTER TO;Lo;0;L;;;;;N;;;;; -1792;KHMER LETTER THO;Lo;0;L;;;;;N;;;;; -1793;KHMER LETTER NO;Lo;0;L;;;;;N;;;;; -1794;KHMER LETTER BA;Lo;0;L;;;;;N;;;;; -1795;KHMER LETTER PHA;Lo;0;L;;;;;N;;;;; -1796;KHMER LETTER PO;Lo;0;L;;;;;N;;;;; -1797;KHMER LETTER PHO;Lo;0;L;;;;;N;;;;; -1798;KHMER LETTER MO;Lo;0;L;;;;;N;;;;; -1799;KHMER LETTER YO;Lo;0;L;;;;;N;;;;; -179A;KHMER LETTER RO;Lo;0;L;;;;;N;;;;; -179B;KHMER LETTER LO;Lo;0;L;;;;;N;;;;; -179C;KHMER LETTER VO;Lo;0;L;;;;;N;;;;; -179D;KHMER LETTER SHA;Lo;0;L;;;;;N;;;;; -179E;KHMER LETTER SSO;Lo;0;L;;;;;N;;;;; -179F;KHMER LETTER SA;Lo;0;L;;;;;N;;;;; -17A0;KHMER LETTER HA;Lo;0;L;;;;;N;;;;; -17A1;KHMER LETTER LA;Lo;0;L;;;;;N;;;;; -17A2;KHMER LETTER QA;Lo;0;L;;;;;N;;;;; -17A3;KHMER INDEPENDENT VOWEL QAQ;Lo;0;L;;;;;N;;*;;; -17A4;KHMER INDEPENDENT VOWEL QAA;Lo;0;L;;;;;N;;*;;; -17A5;KHMER INDEPENDENT VOWEL QI;Lo;0;L;;;;;N;;;;; -17A6;KHMER INDEPENDENT VOWEL QII;Lo;0;L;;;;;N;;;;; -17A7;KHMER INDEPENDENT VOWEL QU;Lo;0;L;;;;;N;;;;; -17A8;KHMER INDEPENDENT VOWEL QUK;Lo;0;L;;;;;N;;;;; -17A9;KHMER INDEPENDENT VOWEL QUU;Lo;0;L;;;;;N;;;;; -17AA;KHMER INDEPENDENT VOWEL QUUV;Lo;0;L;;;;;N;;;;; -17AB;KHMER INDEPENDENT VOWEL RY;Lo;0;L;;;;;N;;;;; -17AC;KHMER INDEPENDENT VOWEL RYY;Lo;0;L;;;;;N;;;;; -17AD;KHMER INDEPENDENT VOWEL LY;Lo;0;L;;;;;N;;;;; -17AE;KHMER INDEPENDENT VOWEL LYY;Lo;0;L;;;;;N;;;;; -17AF;KHMER INDEPENDENT VOWEL QE;Lo;0;L;;;;;N;;;;; -17B0;KHMER INDEPENDENT VOWEL QAI;Lo;0;L;;;;;N;;;;; -17B1;KHMER INDEPENDENT VOWEL QOO TYPE ONE;Lo;0;L;;;;;N;;;;; -17B2;KHMER INDEPENDENT VOWEL QOO TYPE TWO;Lo;0;L;;;;;N;;;;; -17B3;KHMER INDEPENDENT VOWEL QAU;Lo;0;L;;;;;N;;;;; -17B4;KHMER VOWEL INHERENT AQ;Cf;0;L;;;;;N;;*;;; -17B5;KHMER VOWEL INHERENT AA;Cf;0;L;;;;;N;;*;;; -17B6;KHMER VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -17B7;KHMER VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -17B8;KHMER VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -17B9;KHMER VOWEL SIGN Y;Mn;0;NSM;;;;;N;;;;; -17BA;KHMER VOWEL SIGN YY;Mn;0;NSM;;;;;N;;;;; -17BB;KHMER VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -17BC;KHMER VOWEL SIGN UU;Mn;0;NSM;;;;;N;;;;; -17BD;KHMER VOWEL SIGN UA;Mn;0;NSM;;;;;N;;;;; -17BE;KHMER VOWEL SIGN OE;Mc;0;L;;;;;N;;;;; -17BF;KHMER VOWEL SIGN YA;Mc;0;L;;;;;N;;;;; -17C0;KHMER VOWEL SIGN IE;Mc;0;L;;;;;N;;;;; -17C1;KHMER VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -17C2;KHMER VOWEL SIGN AE;Mc;0;L;;;;;N;;;;; -17C3;KHMER VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -17C4;KHMER VOWEL SIGN OO;Mc;0;L;;;;;N;;;;; -17C5;KHMER VOWEL SIGN AU;Mc;0;L;;;;;N;;;;; -17C6;KHMER SIGN NIKAHIT;Mn;0;NSM;;;;;N;;;;; -17C7;KHMER SIGN REAHMUK;Mc;0;L;;;;;N;;;;; -17C8;KHMER SIGN YUUKALEAPINTU;Mc;0;L;;;;;N;;;;; -17C9;KHMER SIGN MUUSIKATOAN;Mn;0;NSM;;;;;N;;;;; -17CA;KHMER SIGN TRIISAP;Mn;0;NSM;;;;;N;;;;; -17CB;KHMER SIGN BANTOC;Mn;0;NSM;;;;;N;;;;; -17CC;KHMER SIGN ROBAT;Mn;0;NSM;;;;;N;;;;; -17CD;KHMER SIGN TOANDAKHIAT;Mn;0;NSM;;;;;N;;;;; -17CE;KHMER SIGN KAKABAT;Mn;0;NSM;;;;;N;;;;; -17CF;KHMER SIGN AHSDA;Mn;0;NSM;;;;;N;;;;; -17D0;KHMER SIGN SAMYOK SANNYA;Mn;0;NSM;;;;;N;;;;; -17D1;KHMER SIGN VIRIAM;Mn;0;NSM;;;;;N;;;;; -17D2;KHMER SIGN COENG;Mn;9;NSM;;;;;N;;;;; -17D3;KHMER SIGN BATHAMASAT;Mn;0;NSM;;;;;N;;*;;; -17D4;KHMER SIGN KHAN;Po;0;L;;;;;N;;;;; -17D5;KHMER SIGN BARIYOOSAN;Po;0;L;;;;;N;;;;; -17D6;KHMER SIGN CAMNUC PII KUUH;Po;0;L;;;;;N;;;;; -17D7;KHMER SIGN LEK TOO;Lm;0;L;;;;;N;;;;; -17D8;KHMER SIGN BEYYAL;Po;0;L;;;;;N;;*;;; -17D9;KHMER SIGN PHNAEK MUAN;Po;0;L;;;;;N;;;;; -17DA;KHMER SIGN KOOMUUT;Po;0;L;;;;;N;;;;; -17DB;KHMER CURRENCY SYMBOL RIEL;Sc;0;ET;;;;;N;;;;; -17DC;KHMER SIGN AVAKRAHASANYA;Lo;0;L;;;;;N;;;;; -17DD;KHMER SIGN ATTHACAN;Mn;230;NSM;;;;;N;;;;; -17E0;KHMER DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -17E1;KHMER DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -17E2;KHMER DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -17E3;KHMER DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -17E4;KHMER DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -17E5;KHMER DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -17E6;KHMER DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -17E7;KHMER DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -17E8;KHMER DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -17E9;KHMER DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -17F0;KHMER SYMBOL LEK ATTAK SON;No;0;ON;;;;0;N;;;;; -17F1;KHMER SYMBOL LEK ATTAK MUOY;No;0;ON;;;;1;N;;;;; -17F2;KHMER SYMBOL LEK ATTAK PII;No;0;ON;;;;2;N;;;;; -17F3;KHMER SYMBOL LEK ATTAK BEI;No;0;ON;;;;3;N;;;;; -17F4;KHMER SYMBOL LEK ATTAK BUON;No;0;ON;;;;4;N;;;;; -17F5;KHMER SYMBOL LEK ATTAK PRAM;No;0;ON;;;;5;N;;;;; -17F6;KHMER SYMBOL LEK ATTAK PRAM-MUOY;No;0;ON;;;;6;N;;;;; -17F7;KHMER SYMBOL LEK ATTAK PRAM-PII;No;0;ON;;;;7;N;;;;; -17F8;KHMER SYMBOL LEK ATTAK PRAM-BEI;No;0;ON;;;;8;N;;;;; -17F9;KHMER SYMBOL LEK ATTAK PRAM-BUON;No;0;ON;;;;9;N;;;;; -1800;MONGOLIAN BIRGA;Po;0;ON;;;;;N;;;;; -1801;MONGOLIAN ELLIPSIS;Po;0;ON;;;;;N;;;;; -1802;MONGOLIAN COMMA;Po;0;ON;;;;;N;;;;; -1803;MONGOLIAN FULL STOP;Po;0;ON;;;;;N;;;;; -1804;MONGOLIAN COLON;Po;0;ON;;;;;N;;;;; -1805;MONGOLIAN FOUR DOTS;Po;0;ON;;;;;N;;;;; -1806;MONGOLIAN TODO SOFT HYPHEN;Pd;0;ON;;;;;N;;;;; -1807;MONGOLIAN SIBE SYLLABLE BOUNDARY MARKER;Po;0;ON;;;;;N;;;;; -1808;MONGOLIAN MANCHU COMMA;Po;0;ON;;;;;N;;;;; -1809;MONGOLIAN MANCHU FULL STOP;Po;0;ON;;;;;N;;;;; -180A;MONGOLIAN NIRUGU;Po;0;ON;;;;;N;;;;; -180B;MONGOLIAN FREE VARIATION SELECTOR ONE;Mn;0;NSM;;;;;N;;;;; -180C;MONGOLIAN FREE VARIATION SELECTOR TWO;Mn;0;NSM;;;;;N;;;;; -180D;MONGOLIAN FREE VARIATION SELECTOR THREE;Mn;0;NSM;;;;;N;;;;; -180E;MONGOLIAN VOWEL SEPARATOR;Zs;0;WS;;;;;N;;;;; -1810;MONGOLIAN DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1811;MONGOLIAN DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1812;MONGOLIAN DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1813;MONGOLIAN DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1814;MONGOLIAN DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1815;MONGOLIAN DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1816;MONGOLIAN DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1817;MONGOLIAN DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1818;MONGOLIAN DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1819;MONGOLIAN DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1820;MONGOLIAN LETTER A;Lo;0;L;;;;;N;;;;; -1821;MONGOLIAN LETTER E;Lo;0;L;;;;;N;;;;; -1822;MONGOLIAN LETTER I;Lo;0;L;;;;;N;;;;; -1823;MONGOLIAN LETTER O;Lo;0;L;;;;;N;;;;; -1824;MONGOLIAN LETTER U;Lo;0;L;;;;;N;;;;; -1825;MONGOLIAN LETTER OE;Lo;0;L;;;;;N;;;;; -1826;MONGOLIAN LETTER UE;Lo;0;L;;;;;N;;;;; -1827;MONGOLIAN LETTER EE;Lo;0;L;;;;;N;;;;; -1828;MONGOLIAN LETTER NA;Lo;0;L;;;;;N;;;;; -1829;MONGOLIAN LETTER ANG;Lo;0;L;;;;;N;;;;; -182A;MONGOLIAN LETTER BA;Lo;0;L;;;;;N;;;;; -182B;MONGOLIAN LETTER PA;Lo;0;L;;;;;N;;;;; -182C;MONGOLIAN LETTER QA;Lo;0;L;;;;;N;;;;; -182D;MONGOLIAN LETTER GA;Lo;0;L;;;;;N;;;;; -182E;MONGOLIAN LETTER MA;Lo;0;L;;;;;N;;;;; -182F;MONGOLIAN LETTER LA;Lo;0;L;;;;;N;;;;; -1830;MONGOLIAN LETTER SA;Lo;0;L;;;;;N;;;;; -1831;MONGOLIAN LETTER SHA;Lo;0;L;;;;;N;;;;; -1832;MONGOLIAN LETTER TA;Lo;0;L;;;;;N;;;;; -1833;MONGOLIAN LETTER DA;Lo;0;L;;;;;N;;;;; -1834;MONGOLIAN LETTER CHA;Lo;0;L;;;;;N;;;;; -1835;MONGOLIAN LETTER JA;Lo;0;L;;;;;N;;;;; -1836;MONGOLIAN LETTER YA;Lo;0;L;;;;;N;;;;; -1837;MONGOLIAN LETTER RA;Lo;0;L;;;;;N;;;;; -1838;MONGOLIAN LETTER WA;Lo;0;L;;;;;N;;;;; -1839;MONGOLIAN LETTER FA;Lo;0;L;;;;;N;;;;; -183A;MONGOLIAN LETTER KA;Lo;0;L;;;;;N;;;;; -183B;MONGOLIAN LETTER KHA;Lo;0;L;;;;;N;;;;; -183C;MONGOLIAN LETTER TSA;Lo;0;L;;;;;N;;;;; -183D;MONGOLIAN LETTER ZA;Lo;0;L;;;;;N;;;;; -183E;MONGOLIAN LETTER HAA;Lo;0;L;;;;;N;;;;; -183F;MONGOLIAN LETTER ZRA;Lo;0;L;;;;;N;;;;; -1840;MONGOLIAN LETTER LHA;Lo;0;L;;;;;N;;;;; -1841;MONGOLIAN LETTER ZHI;Lo;0;L;;;;;N;;;;; -1842;MONGOLIAN LETTER CHI;Lo;0;L;;;;;N;;;;; -1843;MONGOLIAN LETTER TODO LONG VOWEL SIGN;Lm;0;L;;;;;N;;;;; -1844;MONGOLIAN LETTER TODO E;Lo;0;L;;;;;N;;;;; -1845;MONGOLIAN LETTER TODO I;Lo;0;L;;;;;N;;;;; -1846;MONGOLIAN LETTER TODO O;Lo;0;L;;;;;N;;;;; -1847;MONGOLIAN LETTER TODO U;Lo;0;L;;;;;N;;;;; -1848;MONGOLIAN LETTER TODO OE;Lo;0;L;;;;;N;;;;; -1849;MONGOLIAN LETTER TODO UE;Lo;0;L;;;;;N;;;;; -184A;MONGOLIAN LETTER TODO ANG;Lo;0;L;;;;;N;;;;; -184B;MONGOLIAN LETTER TODO BA;Lo;0;L;;;;;N;;;;; -184C;MONGOLIAN LETTER TODO PA;Lo;0;L;;;;;N;;;;; -184D;MONGOLIAN LETTER TODO QA;Lo;0;L;;;;;N;;;;; -184E;MONGOLIAN LETTER TODO GA;Lo;0;L;;;;;N;;;;; -184F;MONGOLIAN LETTER TODO MA;Lo;0;L;;;;;N;;;;; -1850;MONGOLIAN LETTER TODO TA;Lo;0;L;;;;;N;;;;; -1851;MONGOLIAN LETTER TODO DA;Lo;0;L;;;;;N;;;;; -1852;MONGOLIAN LETTER TODO CHA;Lo;0;L;;;;;N;;;;; -1853;MONGOLIAN LETTER TODO JA;Lo;0;L;;;;;N;;;;; -1854;MONGOLIAN LETTER TODO TSA;Lo;0;L;;;;;N;;;;; -1855;MONGOLIAN LETTER TODO YA;Lo;0;L;;;;;N;;;;; -1856;MONGOLIAN LETTER TODO WA;Lo;0;L;;;;;N;;;;; -1857;MONGOLIAN LETTER TODO KA;Lo;0;L;;;;;N;;;;; -1858;MONGOLIAN LETTER TODO GAA;Lo;0;L;;;;;N;;;;; -1859;MONGOLIAN LETTER TODO HAA;Lo;0;L;;;;;N;;;;; -185A;MONGOLIAN LETTER TODO JIA;Lo;0;L;;;;;N;;;;; -185B;MONGOLIAN LETTER TODO NIA;Lo;0;L;;;;;N;;;;; -185C;MONGOLIAN LETTER TODO DZA;Lo;0;L;;;;;N;;;;; -185D;MONGOLIAN LETTER SIBE E;Lo;0;L;;;;;N;;;;; -185E;MONGOLIAN LETTER SIBE I;Lo;0;L;;;;;N;;;;; -185F;MONGOLIAN LETTER SIBE IY;Lo;0;L;;;;;N;;;;; -1860;MONGOLIAN LETTER SIBE UE;Lo;0;L;;;;;N;;;;; -1861;MONGOLIAN LETTER SIBE U;Lo;0;L;;;;;N;;;;; -1862;MONGOLIAN LETTER SIBE ANG;Lo;0;L;;;;;N;;;;; -1863;MONGOLIAN LETTER SIBE KA;Lo;0;L;;;;;N;;;;; -1864;MONGOLIAN LETTER SIBE GA;Lo;0;L;;;;;N;;;;; -1865;MONGOLIAN LETTER SIBE HA;Lo;0;L;;;;;N;;;;; -1866;MONGOLIAN LETTER SIBE PA;Lo;0;L;;;;;N;;;;; -1867;MONGOLIAN LETTER SIBE SHA;Lo;0;L;;;;;N;;;;; -1868;MONGOLIAN LETTER SIBE TA;Lo;0;L;;;;;N;;;;; -1869;MONGOLIAN LETTER SIBE DA;Lo;0;L;;;;;N;;;;; -186A;MONGOLIAN LETTER SIBE JA;Lo;0;L;;;;;N;;;;; -186B;MONGOLIAN LETTER SIBE FA;Lo;0;L;;;;;N;;;;; -186C;MONGOLIAN LETTER SIBE GAA;Lo;0;L;;;;;N;;;;; -186D;MONGOLIAN LETTER SIBE HAA;Lo;0;L;;;;;N;;;;; -186E;MONGOLIAN LETTER SIBE TSA;Lo;0;L;;;;;N;;;;; -186F;MONGOLIAN LETTER SIBE ZA;Lo;0;L;;;;;N;;;;; -1870;MONGOLIAN LETTER SIBE RAA;Lo;0;L;;;;;N;;;;; -1871;MONGOLIAN LETTER SIBE CHA;Lo;0;L;;;;;N;;;;; -1872;MONGOLIAN LETTER SIBE ZHA;Lo;0;L;;;;;N;;;;; -1873;MONGOLIAN LETTER MANCHU I;Lo;0;L;;;;;N;;;;; -1874;MONGOLIAN LETTER MANCHU KA;Lo;0;L;;;;;N;;;;; -1875;MONGOLIAN LETTER MANCHU RA;Lo;0;L;;;;;N;;;;; -1876;MONGOLIAN LETTER MANCHU FA;Lo;0;L;;;;;N;;;;; -1877;MONGOLIAN LETTER MANCHU ZHA;Lo;0;L;;;;;N;;;;; -1880;MONGOLIAN LETTER ALI GALI ANUSVARA ONE;Lo;0;L;;;;;N;;;;; -1881;MONGOLIAN LETTER ALI GALI VISARGA ONE;Lo;0;L;;;;;N;;;;; -1882;MONGOLIAN LETTER ALI GALI DAMARU;Lo;0;L;;;;;N;;;;; -1883;MONGOLIAN LETTER ALI GALI UBADAMA;Lo;0;L;;;;;N;;;;; -1884;MONGOLIAN LETTER ALI GALI INVERTED UBADAMA;Lo;0;L;;;;;N;;;;; -1885;MONGOLIAN LETTER ALI GALI BALUDA;Lo;0;L;;;;;N;;;;; -1886;MONGOLIAN LETTER ALI GALI THREE BALUDA;Lo;0;L;;;;;N;;;;; -1887;MONGOLIAN LETTER ALI GALI A;Lo;0;L;;;;;N;;;;; -1888;MONGOLIAN LETTER ALI GALI I;Lo;0;L;;;;;N;;;;; -1889;MONGOLIAN LETTER ALI GALI KA;Lo;0;L;;;;;N;;;;; -188A;MONGOLIAN LETTER ALI GALI NGA;Lo;0;L;;;;;N;;;;; -188B;MONGOLIAN LETTER ALI GALI CA;Lo;0;L;;;;;N;;;;; -188C;MONGOLIAN LETTER ALI GALI TTA;Lo;0;L;;;;;N;;;;; -188D;MONGOLIAN LETTER ALI GALI TTHA;Lo;0;L;;;;;N;;;;; -188E;MONGOLIAN LETTER ALI GALI DDA;Lo;0;L;;;;;N;;;;; -188F;MONGOLIAN LETTER ALI GALI NNA;Lo;0;L;;;;;N;;;;; -1890;MONGOLIAN LETTER ALI GALI TA;Lo;0;L;;;;;N;;;;; -1891;MONGOLIAN LETTER ALI GALI DA;Lo;0;L;;;;;N;;;;; -1892;MONGOLIAN LETTER ALI GALI PA;Lo;0;L;;;;;N;;;;; -1893;MONGOLIAN LETTER ALI GALI PHA;Lo;0;L;;;;;N;;;;; -1894;MONGOLIAN LETTER ALI GALI SSA;Lo;0;L;;;;;N;;;;; -1895;MONGOLIAN LETTER ALI GALI ZHA;Lo;0;L;;;;;N;;;;; -1896;MONGOLIAN LETTER ALI GALI ZA;Lo;0;L;;;;;N;;;;; -1897;MONGOLIAN LETTER ALI GALI AH;Lo;0;L;;;;;N;;;;; -1898;MONGOLIAN LETTER TODO ALI GALI TA;Lo;0;L;;;;;N;;;;; -1899;MONGOLIAN LETTER TODO ALI GALI ZHA;Lo;0;L;;;;;N;;;;; -189A;MONGOLIAN LETTER MANCHU ALI GALI GHA;Lo;0;L;;;;;N;;;;; -189B;MONGOLIAN LETTER MANCHU ALI GALI NGA;Lo;0;L;;;;;N;;;;; -189C;MONGOLIAN LETTER MANCHU ALI GALI CA;Lo;0;L;;;;;N;;;;; -189D;MONGOLIAN LETTER MANCHU ALI GALI JHA;Lo;0;L;;;;;N;;;;; -189E;MONGOLIAN LETTER MANCHU ALI GALI TTA;Lo;0;L;;;;;N;;;;; -189F;MONGOLIAN LETTER MANCHU ALI GALI DDHA;Lo;0;L;;;;;N;;;;; -18A0;MONGOLIAN LETTER MANCHU ALI GALI TA;Lo;0;L;;;;;N;;;;; -18A1;MONGOLIAN LETTER MANCHU ALI GALI DHA;Lo;0;L;;;;;N;;;;; -18A2;MONGOLIAN LETTER MANCHU ALI GALI SSA;Lo;0;L;;;;;N;;;;; -18A3;MONGOLIAN LETTER MANCHU ALI GALI CYA;Lo;0;L;;;;;N;;;;; -18A4;MONGOLIAN LETTER MANCHU ALI GALI ZHA;Lo;0;L;;;;;N;;;;; -18A5;MONGOLIAN LETTER MANCHU ALI GALI ZA;Lo;0;L;;;;;N;;;;; -18A6;MONGOLIAN LETTER ALI GALI HALF U;Lo;0;L;;;;;N;;;;; -18A7;MONGOLIAN LETTER ALI GALI HALF YA;Lo;0;L;;;;;N;;;;; -18A8;MONGOLIAN LETTER MANCHU ALI GALI BHA;Lo;0;L;;;;;N;;;;; -18A9;MONGOLIAN LETTER ALI GALI DAGALGA;Mn;228;NSM;;;;;N;;;;; -18AA;MONGOLIAN LETTER MANCHU ALI GALI LHA;Lo;0;L;;;;;N;;;;; -1900;LIMBU VOWEL-CARRIER LETTER;Lo;0;L;;;;;N;;;;; -1901;LIMBU LETTER KA;Lo;0;L;;;;;N;;;;; -1902;LIMBU LETTER KHA;Lo;0;L;;;;;N;;;;; -1903;LIMBU LETTER GA;Lo;0;L;;;;;N;;;;; -1904;LIMBU LETTER GHA;Lo;0;L;;;;;N;;;;; -1905;LIMBU LETTER NGA;Lo;0;L;;;;;N;;;;; -1906;LIMBU LETTER CA;Lo;0;L;;;;;N;;;;; -1907;LIMBU LETTER CHA;Lo;0;L;;;;;N;;;;; -1908;LIMBU LETTER JA;Lo;0;L;;;;;N;;;;; -1909;LIMBU LETTER JHA;Lo;0;L;;;;;N;;;;; -190A;LIMBU LETTER YAN;Lo;0;L;;;;;N;;;;; -190B;LIMBU LETTER TA;Lo;0;L;;;;;N;;;;; -190C;LIMBU LETTER THA;Lo;0;L;;;;;N;;;;; -190D;LIMBU LETTER DA;Lo;0;L;;;;;N;;;;; -190E;LIMBU LETTER DHA;Lo;0;L;;;;;N;;;;; -190F;LIMBU LETTER NA;Lo;0;L;;;;;N;;;;; -1910;LIMBU LETTER PA;Lo;0;L;;;;;N;;;;; -1911;LIMBU LETTER PHA;Lo;0;L;;;;;N;;;;; -1912;LIMBU LETTER BA;Lo;0;L;;;;;N;;;;; -1913;LIMBU LETTER BHA;Lo;0;L;;;;;N;;;;; -1914;LIMBU LETTER MA;Lo;0;L;;;;;N;;;;; -1915;LIMBU LETTER YA;Lo;0;L;;;;;N;;;;; -1916;LIMBU LETTER RA;Lo;0;L;;;;;N;;;;; -1917;LIMBU LETTER LA;Lo;0;L;;;;;N;;;;; -1918;LIMBU LETTER WA;Lo;0;L;;;;;N;;;;; -1919;LIMBU LETTER SHA;Lo;0;L;;;;;N;;;;; -191A;LIMBU LETTER SSA;Lo;0;L;;;;;N;;;;; -191B;LIMBU LETTER SA;Lo;0;L;;;;;N;;;;; -191C;LIMBU LETTER HA;Lo;0;L;;;;;N;;;;; -1920;LIMBU VOWEL SIGN A;Mn;0;NSM;;;;;N;;;;; -1921;LIMBU VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -1922;LIMBU VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -1923;LIMBU VOWEL SIGN EE;Mc;0;L;;;;;N;;;;; -1924;LIMBU VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -1925;LIMBU VOWEL SIGN OO;Mc;0;L;;;;;N;;;;; -1926;LIMBU VOWEL SIGN AU;Mc;0;L;;;;;N;;;;; -1927;LIMBU VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -1928;LIMBU VOWEL SIGN O;Mn;0;NSM;;;;;N;;;;; -1929;LIMBU SUBJOINED LETTER YA;Mc;0;L;;;;;N;;;;; -192A;LIMBU SUBJOINED LETTER RA;Mc;0;L;;;;;N;;;;; -192B;LIMBU SUBJOINED LETTER WA;Mc;0;L;;;;;N;;;;; -1930;LIMBU SMALL LETTER KA;Mc;0;L;;;;;N;;;;; -1931;LIMBU SMALL LETTER NGA;Mc;0;L;;;;;N;;;;; -1932;LIMBU SMALL LETTER ANUSVARA;Mn;0;NSM;;;;;N;;;;; -1933;LIMBU SMALL LETTER TA;Mc;0;L;;;;;N;;;;; -1934;LIMBU SMALL LETTER NA;Mc;0;L;;;;;N;;;;; -1935;LIMBU SMALL LETTER PA;Mc;0;L;;;;;N;;;;; -1936;LIMBU SMALL LETTER MA;Mc;0;L;;;;;N;;;;; -1937;LIMBU SMALL LETTER RA;Mc;0;L;;;;;N;;;;; -1938;LIMBU SMALL LETTER LA;Mc;0;L;;;;;N;;;;; -1939;LIMBU SIGN MUKPHRENG;Mn;222;NSM;;;;;N;;;;; -193A;LIMBU SIGN KEMPHRENG;Mn;230;NSM;;;;;N;;;;; -193B;LIMBU SIGN SA-I;Mn;220;NSM;;;;;N;;;;; -1940;LIMBU SIGN LOO;So;0;ON;;;;;N;;;;; -1944;LIMBU EXCLAMATION MARK;Po;0;ON;;;;;N;;;;; -1945;LIMBU QUESTION MARK;Po;0;ON;;;;;N;;;;; -1946;LIMBU DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1947;LIMBU DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1948;LIMBU DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1949;LIMBU DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -194A;LIMBU DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -194B;LIMBU DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -194C;LIMBU DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -194D;LIMBU DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -194E;LIMBU DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -194F;LIMBU DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1950;TAI LE LETTER KA;Lo;0;L;;;;;N;;;;; -1951;TAI LE LETTER XA;Lo;0;L;;;;;N;;;;; -1952;TAI LE LETTER NGA;Lo;0;L;;;;;N;;;;; -1953;TAI LE LETTER TSA;Lo;0;L;;;;;N;;;;; -1954;TAI LE LETTER SA;Lo;0;L;;;;;N;;;;; -1955;TAI LE LETTER YA;Lo;0;L;;;;;N;;;;; -1956;TAI LE LETTER TA;Lo;0;L;;;;;N;;;;; -1957;TAI LE LETTER THA;Lo;0;L;;;;;N;;;;; -1958;TAI LE LETTER LA;Lo;0;L;;;;;N;;;;; -1959;TAI LE LETTER PA;Lo;0;L;;;;;N;;;;; -195A;TAI LE LETTER PHA;Lo;0;L;;;;;N;;;;; -195B;TAI LE LETTER MA;Lo;0;L;;;;;N;;;;; -195C;TAI LE LETTER FA;Lo;0;L;;;;;N;;;;; -195D;TAI LE LETTER VA;Lo;0;L;;;;;N;;;;; -195E;TAI LE LETTER HA;Lo;0;L;;;;;N;;;;; -195F;TAI LE LETTER QA;Lo;0;L;;;;;N;;;;; -1960;TAI LE LETTER KHA;Lo;0;L;;;;;N;;;;; -1961;TAI LE LETTER TSHA;Lo;0;L;;;;;N;;;;; -1962;TAI LE LETTER NA;Lo;0;L;;;;;N;;;;; -1963;TAI LE LETTER A;Lo;0;L;;;;;N;;;;; -1964;TAI LE LETTER I;Lo;0;L;;;;;N;;;;; -1965;TAI LE LETTER EE;Lo;0;L;;;;;N;;;;; -1966;TAI LE LETTER EH;Lo;0;L;;;;;N;;;;; -1967;TAI LE LETTER U;Lo;0;L;;;;;N;;;;; -1968;TAI LE LETTER OO;Lo;0;L;;;;;N;;;;; -1969;TAI LE LETTER O;Lo;0;L;;;;;N;;;;; -196A;TAI LE LETTER UE;Lo;0;L;;;;;N;;;;; -196B;TAI LE LETTER E;Lo;0;L;;;;;N;;;;; -196C;TAI LE LETTER AUE;Lo;0;L;;;;;N;;;;; -196D;TAI LE LETTER AI;Lo;0;L;;;;;N;;;;; -1970;TAI LE LETTER TONE-2;Lo;0;L;;;;;N;;;;; -1971;TAI LE LETTER TONE-3;Lo;0;L;;;;;N;;;;; -1972;TAI LE LETTER TONE-4;Lo;0;L;;;;;N;;;;; -1973;TAI LE LETTER TONE-5;Lo;0;L;;;;;N;;;;; -1974;TAI LE LETTER TONE-6;Lo;0;L;;;;;N;;;;; -1980;NEW TAI LUE LETTER HIGH QA;Lo;0;L;;;;;N;;;;; -1981;NEW TAI LUE LETTER LOW QA;Lo;0;L;;;;;N;;;;; -1982;NEW TAI LUE LETTER HIGH KA;Lo;0;L;;;;;N;;;;; -1983;NEW TAI LUE LETTER HIGH XA;Lo;0;L;;;;;N;;;;; -1984;NEW TAI LUE LETTER HIGH NGA;Lo;0;L;;;;;N;;;;; -1985;NEW TAI LUE LETTER LOW KA;Lo;0;L;;;;;N;;;;; -1986;NEW TAI LUE LETTER LOW XA;Lo;0;L;;;;;N;;;;; -1987;NEW TAI LUE LETTER LOW NGA;Lo;0;L;;;;;N;;;;; -1988;NEW TAI LUE LETTER HIGH TSA;Lo;0;L;;;;;N;;;;; -1989;NEW TAI LUE LETTER HIGH SA;Lo;0;L;;;;;N;;;;; -198A;NEW TAI LUE LETTER HIGH YA;Lo;0;L;;;;;N;;;;; -198B;NEW TAI LUE LETTER LOW TSA;Lo;0;L;;;;;N;;;;; -198C;NEW TAI LUE LETTER LOW SA;Lo;0;L;;;;;N;;;;; -198D;NEW TAI LUE LETTER LOW YA;Lo;0;L;;;;;N;;;;; -198E;NEW TAI LUE LETTER HIGH TA;Lo;0;L;;;;;N;;;;; -198F;NEW TAI LUE LETTER HIGH THA;Lo;0;L;;;;;N;;;;; -1990;NEW TAI LUE LETTER HIGH NA;Lo;0;L;;;;;N;;;;; -1991;NEW TAI LUE LETTER LOW TA;Lo;0;L;;;;;N;;;;; -1992;NEW TAI LUE LETTER LOW THA;Lo;0;L;;;;;N;;;;; -1993;NEW TAI LUE LETTER LOW NA;Lo;0;L;;;;;N;;;;; -1994;NEW TAI LUE LETTER HIGH PA;Lo;0;L;;;;;N;;;;; -1995;NEW TAI LUE LETTER HIGH PHA;Lo;0;L;;;;;N;;;;; -1996;NEW TAI LUE LETTER HIGH MA;Lo;0;L;;;;;N;;;;; -1997;NEW TAI LUE LETTER LOW PA;Lo;0;L;;;;;N;;;;; -1998;NEW TAI LUE LETTER LOW PHA;Lo;0;L;;;;;N;;;;; -1999;NEW TAI LUE LETTER LOW MA;Lo;0;L;;;;;N;;;;; -199A;NEW TAI LUE LETTER HIGH FA;Lo;0;L;;;;;N;;;;; -199B;NEW TAI LUE LETTER HIGH VA;Lo;0;L;;;;;N;;;;; -199C;NEW TAI LUE LETTER HIGH LA;Lo;0;L;;;;;N;;;;; -199D;NEW TAI LUE LETTER LOW FA;Lo;0;L;;;;;N;;;;; -199E;NEW TAI LUE LETTER LOW VA;Lo;0;L;;;;;N;;;;; -199F;NEW TAI LUE LETTER LOW LA;Lo;0;L;;;;;N;;;;; -19A0;NEW TAI LUE LETTER HIGH HA;Lo;0;L;;;;;N;;;;; -19A1;NEW TAI LUE LETTER HIGH DA;Lo;0;L;;;;;N;;;;; -19A2;NEW TAI LUE LETTER HIGH BA;Lo;0;L;;;;;N;;;;; -19A3;NEW TAI LUE LETTER LOW HA;Lo;0;L;;;;;N;;;;; -19A4;NEW TAI LUE LETTER LOW DA;Lo;0;L;;;;;N;;;;; -19A5;NEW TAI LUE LETTER LOW BA;Lo;0;L;;;;;N;;;;; -19A6;NEW TAI LUE LETTER HIGH KVA;Lo;0;L;;;;;N;;;;; -19A7;NEW TAI LUE LETTER HIGH XVA;Lo;0;L;;;;;N;;;;; -19A8;NEW TAI LUE LETTER LOW KVA;Lo;0;L;;;;;N;;;;; -19A9;NEW TAI LUE LETTER LOW XVA;Lo;0;L;;;;;N;;;;; -19B0;NEW TAI LUE VOWEL SIGN VOWEL SHORTENER;Mc;0;L;;;;;N;;;;; -19B1;NEW TAI LUE VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -19B2;NEW TAI LUE VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -19B3;NEW TAI LUE VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -19B4;NEW TAI LUE VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -19B5;NEW TAI LUE VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -19B6;NEW TAI LUE VOWEL SIGN AE;Mc;0;L;;;;;N;;;;; -19B7;NEW TAI LUE VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -19B8;NEW TAI LUE VOWEL SIGN OA;Mc;0;L;;;;;N;;;;; -19B9;NEW TAI LUE VOWEL SIGN UE;Mc;0;L;;;;;N;;;;; -19BA;NEW TAI LUE VOWEL SIGN AY;Mc;0;L;;;;;N;;;;; -19BB;NEW TAI LUE VOWEL SIGN AAY;Mc;0;L;;;;;N;;;;; -19BC;NEW TAI LUE VOWEL SIGN UY;Mc;0;L;;;;;N;;;;; -19BD;NEW TAI LUE VOWEL SIGN OY;Mc;0;L;;;;;N;;;;; -19BE;NEW TAI LUE VOWEL SIGN OAY;Mc;0;L;;;;;N;;;;; -19BF;NEW TAI LUE VOWEL SIGN UEY;Mc;0;L;;;;;N;;;;; -19C0;NEW TAI LUE VOWEL SIGN IY;Mc;0;L;;;;;N;;;;; -19C1;NEW TAI LUE LETTER FINAL V;Lo;0;L;;;;;N;;;;; -19C2;NEW TAI LUE LETTER FINAL NG;Lo;0;L;;;;;N;;;;; -19C3;NEW TAI LUE LETTER FINAL N;Lo;0;L;;;;;N;;;;; -19C4;NEW TAI LUE LETTER FINAL M;Lo;0;L;;;;;N;;;;; -19C5;NEW TAI LUE LETTER FINAL K;Lo;0;L;;;;;N;;;;; -19C6;NEW TAI LUE LETTER FINAL D;Lo;0;L;;;;;N;;;;; -19C7;NEW TAI LUE LETTER FINAL B;Lo;0;L;;;;;N;;;;; -19C8;NEW TAI LUE TONE MARK-1;Mc;0;L;;;;;N;;;;; -19C9;NEW TAI LUE TONE MARK-2;Mc;0;L;;;;;N;;;;; -19D0;NEW TAI LUE DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -19D1;NEW TAI LUE DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -19D2;NEW TAI LUE DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -19D3;NEW TAI LUE DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -19D4;NEW TAI LUE DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -19D5;NEW TAI LUE DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -19D6;NEW TAI LUE DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -19D7;NEW TAI LUE DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -19D8;NEW TAI LUE DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -19D9;NEW TAI LUE DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -19DE;NEW TAI LUE SIGN LAE;Po;0;ON;;;;;N;;;;; -19DF;NEW TAI LUE SIGN LAEV;Po;0;ON;;;;;N;;;;; -19E0;KHMER SYMBOL PATHAMASAT;So;0;ON;;;;;N;;;;; -19E1;KHMER SYMBOL MUOY KOET;So;0;ON;;;;;N;;;;; -19E2;KHMER SYMBOL PII KOET;So;0;ON;;;;;N;;;;; -19E3;KHMER SYMBOL BEI KOET;So;0;ON;;;;;N;;;;; -19E4;KHMER SYMBOL BUON KOET;So;0;ON;;;;;N;;;;; -19E5;KHMER SYMBOL PRAM KOET;So;0;ON;;;;;N;;;;; -19E6;KHMER SYMBOL PRAM-MUOY KOET;So;0;ON;;;;;N;;;;; -19E7;KHMER SYMBOL PRAM-PII KOET;So;0;ON;;;;;N;;;;; -19E8;KHMER SYMBOL PRAM-BEI KOET;So;0;ON;;;;;N;;;;; -19E9;KHMER SYMBOL PRAM-BUON KOET;So;0;ON;;;;;N;;;;; -19EA;KHMER SYMBOL DAP KOET;So;0;ON;;;;;N;;;;; -19EB;KHMER SYMBOL DAP-MUOY KOET;So;0;ON;;;;;N;;;;; -19EC;KHMER SYMBOL DAP-PII KOET;So;0;ON;;;;;N;;;;; -19ED;KHMER SYMBOL DAP-BEI KOET;So;0;ON;;;;;N;;;;; -19EE;KHMER SYMBOL DAP-BUON KOET;So;0;ON;;;;;N;;;;; -19EF;KHMER SYMBOL DAP-PRAM KOET;So;0;ON;;;;;N;;;;; -19F0;KHMER SYMBOL TUTEYASAT;So;0;ON;;;;;N;;;;; -19F1;KHMER SYMBOL MUOY ROC;So;0;ON;;;;;N;;;;; -19F2;KHMER SYMBOL PII ROC;So;0;ON;;;;;N;;;;; -19F3;KHMER SYMBOL BEI ROC;So;0;ON;;;;;N;;;;; -19F4;KHMER SYMBOL BUON ROC;So;0;ON;;;;;N;;;;; -19F5;KHMER SYMBOL PRAM ROC;So;0;ON;;;;;N;;;;; -19F6;KHMER SYMBOL PRAM-MUOY ROC;So;0;ON;;;;;N;;;;; -19F7;KHMER SYMBOL PRAM-PII ROC;So;0;ON;;;;;N;;;;; -19F8;KHMER SYMBOL PRAM-BEI ROC;So;0;ON;;;;;N;;;;; -19F9;KHMER SYMBOL PRAM-BUON ROC;So;0;ON;;;;;N;;;;; -19FA;KHMER SYMBOL DAP ROC;So;0;ON;;;;;N;;;;; -19FB;KHMER SYMBOL DAP-MUOY ROC;So;0;ON;;;;;N;;;;; -19FC;KHMER SYMBOL DAP-PII ROC;So;0;ON;;;;;N;;;;; -19FD;KHMER SYMBOL DAP-BEI ROC;So;0;ON;;;;;N;;;;; -19FE;KHMER SYMBOL DAP-BUON ROC;So;0;ON;;;;;N;;;;; -19FF;KHMER SYMBOL DAP-PRAM ROC;So;0;ON;;;;;N;;;;; -1A00;BUGINESE LETTER KA;Lo;0;L;;;;;N;;;;; -1A01;BUGINESE LETTER GA;Lo;0;L;;;;;N;;;;; -1A02;BUGINESE LETTER NGA;Lo;0;L;;;;;N;;;;; -1A03;BUGINESE LETTER NGKA;Lo;0;L;;;;;N;;;;; -1A04;BUGINESE LETTER PA;Lo;0;L;;;;;N;;;;; -1A05;BUGINESE LETTER BA;Lo;0;L;;;;;N;;;;; -1A06;BUGINESE LETTER MA;Lo;0;L;;;;;N;;;;; -1A07;BUGINESE LETTER MPA;Lo;0;L;;;;;N;;;;; -1A08;BUGINESE LETTER TA;Lo;0;L;;;;;N;;;;; -1A09;BUGINESE LETTER DA;Lo;0;L;;;;;N;;;;; -1A0A;BUGINESE LETTER NA;Lo;0;L;;;;;N;;;;; -1A0B;BUGINESE LETTER NRA;Lo;0;L;;;;;N;;;;; -1A0C;BUGINESE LETTER CA;Lo;0;L;;;;;N;;;;; -1A0D;BUGINESE LETTER JA;Lo;0;L;;;;;N;;;;; -1A0E;BUGINESE LETTER NYA;Lo;0;L;;;;;N;;;;; -1A0F;BUGINESE LETTER NYCA;Lo;0;L;;;;;N;;;;; -1A10;BUGINESE LETTER YA;Lo;0;L;;;;;N;;;;; -1A11;BUGINESE LETTER RA;Lo;0;L;;;;;N;;;;; -1A12;BUGINESE LETTER LA;Lo;0;L;;;;;N;;;;; -1A13;BUGINESE LETTER VA;Lo;0;L;;;;;N;;;;; -1A14;BUGINESE LETTER SA;Lo;0;L;;;;;N;;;;; -1A15;BUGINESE LETTER A;Lo;0;L;;;;;N;;;;; -1A16;BUGINESE LETTER HA;Lo;0;L;;;;;N;;;;; -1A17;BUGINESE VOWEL SIGN I;Mn;230;NSM;;;;;N;;;;; -1A18;BUGINESE VOWEL SIGN U;Mn;220;NSM;;;;;N;;;;; -1A19;BUGINESE VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -1A1A;BUGINESE VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -1A1B;BUGINESE VOWEL SIGN AE;Mc;0;L;;;;;N;;;;; -1A1E;BUGINESE PALLAWA;Po;0;L;;;;;N;;;;; -1A1F;BUGINESE END OF SECTION;Po;0;L;;;;;N;;;;; -1B00;BALINESE SIGN ULU RICEM;Mn;0;NSM;;;;;N;;ardhacandra;;; -1B01;BALINESE SIGN ULU CANDRA;Mn;0;NSM;;;;;N;;candrabindu;;; -1B02;BALINESE SIGN CECEK;Mn;0;NSM;;;;;N;;anusvara;;; -1B03;BALINESE SIGN SURANG;Mn;0;NSM;;;;;N;;repha;;; -1B04;BALINESE SIGN BISAH;Mc;0;L;;;;;N;;visarga;;; -1B05;BALINESE LETTER AKARA;Lo;0;L;;;;;N;;a;;; -1B06;BALINESE LETTER AKARA TEDUNG;Lo;0;L;1B05 1B35;;;;N;;aa;;; -1B07;BALINESE LETTER IKARA;Lo;0;L;;;;;N;;i;;; -1B08;BALINESE LETTER IKARA TEDUNG;Lo;0;L;1B07 1B35;;;;N;;ii;;; -1B09;BALINESE LETTER UKARA;Lo;0;L;;;;;N;;u;;; -1B0A;BALINESE LETTER UKARA TEDUNG;Lo;0;L;1B09 1B35;;;;N;;uu;;; -1B0B;BALINESE LETTER RA REPA;Lo;0;L;;;;;N;;vocalic r;;; -1B0C;BALINESE LETTER RA REPA TEDUNG;Lo;0;L;1B0B 1B35;;;;N;;vocalic rr;;; -1B0D;BALINESE LETTER LA LENGA;Lo;0;L;;;;;N;;vocalic l;;; -1B0E;BALINESE LETTER LA LENGA TEDUNG;Lo;0;L;1B0D 1B35;;;;N;;vocalic ll;;; -1B0F;BALINESE LETTER EKARA;Lo;0;L;;;;;N;;e;;; -1B10;BALINESE LETTER AIKARA;Lo;0;L;;;;;N;;ai;;; -1B11;BALINESE LETTER OKARA;Lo;0;L;;;;;N;;o;;; -1B12;BALINESE LETTER OKARA TEDUNG;Lo;0;L;1B11 1B35;;;;N;;au;;; -1B13;BALINESE LETTER KA;Lo;0;L;;;;;N;;;;; -1B14;BALINESE LETTER KA MAHAPRANA;Lo;0;L;;;;;N;;kha;;; -1B15;BALINESE LETTER GA;Lo;0;L;;;;;N;;;;; -1B16;BALINESE LETTER GA GORA;Lo;0;L;;;;;N;;gha;;; -1B17;BALINESE LETTER NGA;Lo;0;L;;;;;N;;;;; -1B18;BALINESE LETTER CA;Lo;0;L;;;;;N;;;;; -1B19;BALINESE LETTER CA LACA;Lo;0;L;;;;;N;;cha;;; -1B1A;BALINESE LETTER JA;Lo;0;L;;;;;N;;;;; -1B1B;BALINESE LETTER JA JERA;Lo;0;L;;;;;N;;jha;;; -1B1C;BALINESE LETTER NYA;Lo;0;L;;;;;N;;;;; -1B1D;BALINESE LETTER TA LATIK;Lo;0;L;;;;;N;;tta;;; -1B1E;BALINESE LETTER TA MURDA MAHAPRANA;Lo;0;L;;;;;N;;ttha;;; -1B1F;BALINESE LETTER DA MURDA ALPAPRANA;Lo;0;L;;;;;N;;dda;;; -1B20;BALINESE LETTER DA MURDA MAHAPRANA;Lo;0;L;;;;;N;;ddha;;; -1B21;BALINESE LETTER NA RAMBAT;Lo;0;L;;;;;N;;nna;;; -1B22;BALINESE LETTER TA;Lo;0;L;;;;;N;;;;; -1B23;BALINESE LETTER TA TAWA;Lo;0;L;;;;;N;;tha;;; -1B24;BALINESE LETTER DA;Lo;0;L;;;;;N;;;;; -1B25;BALINESE LETTER DA MADU;Lo;0;L;;;;;N;;dha;;; -1B26;BALINESE LETTER NA;Lo;0;L;;;;;N;;;;; -1B27;BALINESE LETTER PA;Lo;0;L;;;;;N;;;;; -1B28;BALINESE LETTER PA KAPAL;Lo;0;L;;;;;N;;pha;;; -1B29;BALINESE LETTER BA;Lo;0;L;;;;;N;;;;; -1B2A;BALINESE LETTER BA KEMBANG;Lo;0;L;;;;;N;;bha;;; -1B2B;BALINESE LETTER MA;Lo;0;L;;;;;N;;;;; -1B2C;BALINESE LETTER YA;Lo;0;L;;;;;N;;;;; -1B2D;BALINESE LETTER RA;Lo;0;L;;;;;N;;;;; -1B2E;BALINESE LETTER LA;Lo;0;L;;;;;N;;;;; -1B2F;BALINESE LETTER WA;Lo;0;L;;;;;N;;;;; -1B30;BALINESE LETTER SA SAGA;Lo;0;L;;;;;N;;sha;;; -1B31;BALINESE LETTER SA SAPA;Lo;0;L;;;;;N;;ssa;;; -1B32;BALINESE LETTER SA;Lo;0;L;;;;;N;;;;; -1B33;BALINESE LETTER HA;Lo;0;L;;;;;N;;;;; -1B34;BALINESE SIGN REREKAN;Mn;7;NSM;;;;;N;;nukta;;; -1B35;BALINESE VOWEL SIGN TEDUNG;Mc;0;L;;;;;N;;aa;;; -1B36;BALINESE VOWEL SIGN ULU;Mn;0;NSM;;;;;N;;i;;; -1B37;BALINESE VOWEL SIGN ULU SARI;Mn;0;NSM;;;;;N;;ii;;; -1B38;BALINESE VOWEL SIGN SUKU;Mn;0;NSM;;;;;N;;u;;; -1B39;BALINESE VOWEL SIGN SUKU ILUT;Mn;0;NSM;;;;;N;;uu;;; -1B3A;BALINESE VOWEL SIGN RA REPA;Mn;0;NSM;;;;;N;;vocalic r;;; -1B3B;BALINESE VOWEL SIGN RA REPA TEDUNG;Mc;0;L;1B3A 1B35;;;;N;;vocalic rr;;; -1B3C;BALINESE VOWEL SIGN LA LENGA;Mn;0;NSM;;;;;N;;vocalic l;;; -1B3D;BALINESE VOWEL SIGN LA LENGA TEDUNG;Mc;0;L;1B3C 1B35;;;;N;;vocalic ll;;; -1B3E;BALINESE VOWEL SIGN TALING;Mc;0;L;;;;;N;;e;;; -1B3F;BALINESE VOWEL SIGN TALING REPA;Mc;0;L;;;;;N;;ai;;; -1B40;BALINESE VOWEL SIGN TALING TEDUNG;Mc;0;L;1B3E 1B35;;;;N;;o;;; -1B41;BALINESE VOWEL SIGN TALING REPA TEDUNG;Mc;0;L;1B3F 1B35;;;;N;;au;;; -1B42;BALINESE VOWEL SIGN PEPET;Mn;0;NSM;;;;;N;;ae;;; -1B43;BALINESE VOWEL SIGN PEPET TEDUNG;Mc;0;L;1B42 1B35;;;;N;;oe;;; -1B44;BALINESE ADEG ADEG;Mc;9;L;;;;;N;;virama;;; -1B45;BALINESE LETTER KAF SASAK;Lo;0;L;;;;;N;;;;; -1B46;BALINESE LETTER KHOT SASAK;Lo;0;L;;;;;N;;;;; -1B47;BALINESE LETTER TZIR SASAK;Lo;0;L;;;;;N;;;;; -1B48;BALINESE LETTER EF SASAK;Lo;0;L;;;;;N;;;;; -1B49;BALINESE LETTER VE SASAK;Lo;0;L;;;;;N;;;;; -1B4A;BALINESE LETTER ZAL SASAK;Lo;0;L;;;;;N;;;;; -1B4B;BALINESE LETTER ASYURA SASAK;Lo;0;L;;;;;N;;;;; -1B50;BALINESE DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1B51;BALINESE DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1B52;BALINESE DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1B53;BALINESE DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1B54;BALINESE DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1B55;BALINESE DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1B56;BALINESE DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1B57;BALINESE DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1B58;BALINESE DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1B59;BALINESE DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1B5A;BALINESE PANTI;Po;0;L;;;;;N;;section;;; -1B5B;BALINESE PAMADA;Po;0;L;;;;;N;;honorific section;;; -1B5C;BALINESE WINDU;Po;0;L;;;;;N;;punctuation ring;;; -1B5D;BALINESE CARIK PAMUNGKAH;Po;0;L;;;;;N;;colon;;; -1B5E;BALINESE CARIK SIKI;Po;0;L;;;;;N;;danda;;; -1B5F;BALINESE CARIK PAREREN;Po;0;L;;;;;N;;double danda;;; -1B60;BALINESE PAMENENG;Po;0;L;;;;;N;;line-breaking hyphen;;; -1B61;BALINESE MUSICAL SYMBOL DONG;So;0;L;;;;;N;;;;; -1B62;BALINESE MUSICAL SYMBOL DENG;So;0;L;;;;;N;;;;; -1B63;BALINESE MUSICAL SYMBOL DUNG;So;0;L;;;;;N;;;;; -1B64;BALINESE MUSICAL SYMBOL DANG;So;0;L;;;;;N;;;;; -1B65;BALINESE MUSICAL SYMBOL DANG SURANG;So;0;L;;;;;N;;;;; -1B66;BALINESE MUSICAL SYMBOL DING;So;0;L;;;;;N;;;;; -1B67;BALINESE MUSICAL SYMBOL DAENG;So;0;L;;;;;N;;;;; -1B68;BALINESE MUSICAL SYMBOL DEUNG;So;0;L;;;;;N;;;;; -1B69;BALINESE MUSICAL SYMBOL DAING;So;0;L;;;;;N;;;;; -1B6A;BALINESE MUSICAL SYMBOL DANG GEDE;So;0;L;;;;;N;;;;; -1B6B;BALINESE MUSICAL SYMBOL COMBINING TEGEH;Mn;230;NSM;;;;;N;;;;; -1B6C;BALINESE MUSICAL SYMBOL COMBINING ENDEP;Mn;220;NSM;;;;;N;;;;; -1B6D;BALINESE MUSICAL SYMBOL COMBINING KEMPUL;Mn;230;NSM;;;;;N;;;;; -1B6E;BALINESE MUSICAL SYMBOL COMBINING KEMPLI;Mn;230;NSM;;;;;N;;;;; -1B6F;BALINESE MUSICAL SYMBOL COMBINING JEGOGAN;Mn;230;NSM;;;;;N;;;;; -1B70;BALINESE MUSICAL SYMBOL COMBINING KEMPUL WITH JEGOGAN;Mn;230;NSM;;;;;N;;;;; -1B71;BALINESE MUSICAL SYMBOL COMBINING KEMPLI WITH JEGOGAN;Mn;230;NSM;;;;;N;;;;; -1B72;BALINESE MUSICAL SYMBOL COMBINING BENDE;Mn;230;NSM;;;;;N;;;;; -1B73;BALINESE MUSICAL SYMBOL COMBINING GONG;Mn;230;NSM;;;;;N;;;;; -1B74;BALINESE MUSICAL SYMBOL RIGHT-HAND OPEN DUG;So;0;L;;;;;N;;;;; -1B75;BALINESE MUSICAL SYMBOL RIGHT-HAND OPEN DAG;So;0;L;;;;;N;;;;; -1B76;BALINESE MUSICAL SYMBOL RIGHT-HAND CLOSED TUK;So;0;L;;;;;N;;;;; -1B77;BALINESE MUSICAL SYMBOL RIGHT-HAND CLOSED TAK;So;0;L;;;;;N;;;;; -1B78;BALINESE MUSICAL SYMBOL LEFT-HAND OPEN PANG;So;0;L;;;;;N;;;;; -1B79;BALINESE MUSICAL SYMBOL LEFT-HAND OPEN PUNG;So;0;L;;;;;N;;;;; -1B7A;BALINESE MUSICAL SYMBOL LEFT-HAND CLOSED PLAK;So;0;L;;;;;N;;;;; -1B7B;BALINESE MUSICAL SYMBOL LEFT-HAND CLOSED PLUK;So;0;L;;;;;N;;;;; -1B7C;BALINESE MUSICAL SYMBOL LEFT-HAND OPEN PING;So;0;L;;;;;N;;;;; -1B80;SUNDANESE SIGN PANYECEK;Mn;0;NSM;;;;;N;;;;; -1B81;SUNDANESE SIGN PANGLAYAR;Mn;0;NSM;;;;;N;;;;; -1B82;SUNDANESE SIGN PANGWISAD;Mc;0;L;;;;;N;;;;; -1B83;SUNDANESE LETTER A;Lo;0;L;;;;;N;;;;; -1B84;SUNDANESE LETTER I;Lo;0;L;;;;;N;;;;; -1B85;SUNDANESE LETTER U;Lo;0;L;;;;;N;;;;; -1B86;SUNDANESE LETTER AE;Lo;0;L;;;;;N;;;;; -1B87;SUNDANESE LETTER O;Lo;0;L;;;;;N;;;;; -1B88;SUNDANESE LETTER E;Lo;0;L;;;;;N;;;;; -1B89;SUNDANESE LETTER EU;Lo;0;L;;;;;N;;;;; -1B8A;SUNDANESE LETTER KA;Lo;0;L;;;;;N;;;;; -1B8B;SUNDANESE LETTER QA;Lo;0;L;;;;;N;;;;; -1B8C;SUNDANESE LETTER GA;Lo;0;L;;;;;N;;;;; -1B8D;SUNDANESE LETTER NGA;Lo;0;L;;;;;N;;;;; -1B8E;SUNDANESE LETTER CA;Lo;0;L;;;;;N;;;;; -1B8F;SUNDANESE LETTER JA;Lo;0;L;;;;;N;;;;; -1B90;SUNDANESE LETTER ZA;Lo;0;L;;;;;N;;;;; -1B91;SUNDANESE LETTER NYA;Lo;0;L;;;;;N;;;;; -1B92;SUNDANESE LETTER TA;Lo;0;L;;;;;N;;;;; -1B93;SUNDANESE LETTER DA;Lo;0;L;;;;;N;;;;; -1B94;SUNDANESE LETTER NA;Lo;0;L;;;;;N;;;;; -1B95;SUNDANESE LETTER PA;Lo;0;L;;;;;N;;;;; -1B96;SUNDANESE LETTER FA;Lo;0;L;;;;;N;;;;; -1B97;SUNDANESE LETTER VA;Lo;0;L;;;;;N;;;;; -1B98;SUNDANESE LETTER BA;Lo;0;L;;;;;N;;;;; -1B99;SUNDANESE LETTER MA;Lo;0;L;;;;;N;;;;; -1B9A;SUNDANESE LETTER YA;Lo;0;L;;;;;N;;;;; -1B9B;SUNDANESE LETTER RA;Lo;0;L;;;;;N;;;;; -1B9C;SUNDANESE LETTER LA;Lo;0;L;;;;;N;;;;; -1B9D;SUNDANESE LETTER WA;Lo;0;L;;;;;N;;;;; -1B9E;SUNDANESE LETTER SA;Lo;0;L;;;;;N;;;;; -1B9F;SUNDANESE LETTER XA;Lo;0;L;;;;;N;;;;; -1BA0;SUNDANESE LETTER HA;Lo;0;L;;;;;N;;;;; -1BA1;SUNDANESE CONSONANT SIGN PAMINGKAL;Mc;0;L;;;;;N;;;;; -1BA2;SUNDANESE CONSONANT SIGN PANYAKRA;Mn;0;NSM;;;;;N;;;;; -1BA3;SUNDANESE CONSONANT SIGN PANYIKU;Mn;0;NSM;;;;;N;;;;; -1BA4;SUNDANESE VOWEL SIGN PANGHULU;Mn;0;NSM;;;;;N;;;;; -1BA5;SUNDANESE VOWEL SIGN PANYUKU;Mn;0;NSM;;;;;N;;;;; -1BA6;SUNDANESE VOWEL SIGN PANAELAENG;Mc;0;L;;;;;N;;;;; -1BA7;SUNDANESE VOWEL SIGN PANOLONG;Mc;0;L;;;;;N;;;;; -1BA8;SUNDANESE VOWEL SIGN PAMEPET;Mn;0;NSM;;;;;N;;;;; -1BA9;SUNDANESE VOWEL SIGN PANEULEUNG;Mn;0;NSM;;;;;N;;;;; -1BAA;SUNDANESE SIGN PAMAAEH;Mc;9;L;;;;;N;;;;; -1BAE;SUNDANESE LETTER KHA;Lo;0;L;;;;;N;;;;; -1BAF;SUNDANESE LETTER SYA;Lo;0;L;;;;;N;;;;; -1BB0;SUNDANESE DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1BB1;SUNDANESE DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1BB2;SUNDANESE DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1BB3;SUNDANESE DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1BB4;SUNDANESE DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1BB5;SUNDANESE DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1BB6;SUNDANESE DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1BB7;SUNDANESE DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1BB8;SUNDANESE DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1BB9;SUNDANESE DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1C00;LEPCHA LETTER KA;Lo;0;L;;;;;N;;;;; -1C01;LEPCHA LETTER KLA;Lo;0;L;;;;;N;;;;; -1C02;LEPCHA LETTER KHA;Lo;0;L;;;;;N;;;;; -1C03;LEPCHA LETTER GA;Lo;0;L;;;;;N;;;;; -1C04;LEPCHA LETTER GLA;Lo;0;L;;;;;N;;;;; -1C05;LEPCHA LETTER NGA;Lo;0;L;;;;;N;;;;; -1C06;LEPCHA LETTER CA;Lo;0;L;;;;;N;;;;; -1C07;LEPCHA LETTER CHA;Lo;0;L;;;;;N;;;;; -1C08;LEPCHA LETTER JA;Lo;0;L;;;;;N;;;;; -1C09;LEPCHA LETTER NYA;Lo;0;L;;;;;N;;;;; -1C0A;LEPCHA LETTER TA;Lo;0;L;;;;;N;;;;; -1C0B;LEPCHA LETTER THA;Lo;0;L;;;;;N;;;;; -1C0C;LEPCHA LETTER DA;Lo;0;L;;;;;N;;;;; -1C0D;LEPCHA LETTER NA;Lo;0;L;;;;;N;;;;; -1C0E;LEPCHA LETTER PA;Lo;0;L;;;;;N;;;;; -1C0F;LEPCHA LETTER PLA;Lo;0;L;;;;;N;;;;; -1C10;LEPCHA LETTER PHA;Lo;0;L;;;;;N;;;;; -1C11;LEPCHA LETTER FA;Lo;0;L;;;;;N;;;;; -1C12;LEPCHA LETTER FLA;Lo;0;L;;;;;N;;;;; -1C13;LEPCHA LETTER BA;Lo;0;L;;;;;N;;;;; -1C14;LEPCHA LETTER BLA;Lo;0;L;;;;;N;;;;; -1C15;LEPCHA LETTER MA;Lo;0;L;;;;;N;;;;; -1C16;LEPCHA LETTER MLA;Lo;0;L;;;;;N;;;;; -1C17;LEPCHA LETTER TSA;Lo;0;L;;;;;N;;;;; -1C18;LEPCHA LETTER TSHA;Lo;0;L;;;;;N;;;;; -1C19;LEPCHA LETTER DZA;Lo;0;L;;;;;N;;;;; -1C1A;LEPCHA LETTER YA;Lo;0;L;;;;;N;;;;; -1C1B;LEPCHA LETTER RA;Lo;0;L;;;;;N;;;;; -1C1C;LEPCHA LETTER LA;Lo;0;L;;;;;N;;;;; -1C1D;LEPCHA LETTER HA;Lo;0;L;;;;;N;;;;; -1C1E;LEPCHA LETTER HLA;Lo;0;L;;;;;N;;;;; -1C1F;LEPCHA LETTER VA;Lo;0;L;;;;;N;;;;; -1C20;LEPCHA LETTER SA;Lo;0;L;;;;;N;;;;; -1C21;LEPCHA LETTER SHA;Lo;0;L;;;;;N;;;;; -1C22;LEPCHA LETTER WA;Lo;0;L;;;;;N;;;;; -1C23;LEPCHA LETTER A;Lo;0;L;;;;;N;;;;; -1C24;LEPCHA SUBJOINED LETTER YA;Mc;0;L;;;;;N;;;;; -1C25;LEPCHA SUBJOINED LETTER RA;Mc;0;L;;;;;N;;;;; -1C26;LEPCHA VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -1C27;LEPCHA VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -1C28;LEPCHA VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -1C29;LEPCHA VOWEL SIGN OO;Mc;0;L;;;;;N;;;;; -1C2A;LEPCHA VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -1C2B;LEPCHA VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -1C2C;LEPCHA VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -1C2D;LEPCHA CONSONANT SIGN K;Mn;0;NSM;;;;;N;;;;; -1C2E;LEPCHA CONSONANT SIGN M;Mn;0;NSM;;;;;N;;;;; -1C2F;LEPCHA CONSONANT SIGN L;Mn;0;NSM;;;;;N;;;;; -1C30;LEPCHA CONSONANT SIGN N;Mn;0;NSM;;;;;N;;;;; -1C31;LEPCHA CONSONANT SIGN P;Mn;0;NSM;;;;;N;;;;; -1C32;LEPCHA CONSONANT SIGN R;Mn;0;NSM;;;;;N;;;;; -1C33;LEPCHA CONSONANT SIGN T;Mn;0;NSM;;;;;N;;;;; -1C34;LEPCHA CONSONANT SIGN NYIN-DO;Mc;0;L;;;;;N;;;;; -1C35;LEPCHA CONSONANT SIGN KANG;Mc;0;L;;;;;N;;;;; -1C36;LEPCHA SIGN RAN;Mn;0;NSM;;;;;N;;;;; -1C37;LEPCHA SIGN NUKTA;Mn;7;NSM;;;;;N;;;;; -1C3B;LEPCHA PUNCTUATION TA-ROL;Po;0;L;;;;;N;;;;; -1C3C;LEPCHA PUNCTUATION NYET THYOOM TA-ROL;Po;0;L;;;;;N;;;;; -1C3D;LEPCHA PUNCTUATION CER-WA;Po;0;L;;;;;N;;;;; -1C3E;LEPCHA PUNCTUATION TSHOOK CER-WA;Po;0;L;;;;;N;;;;; -1C3F;LEPCHA PUNCTUATION TSHOOK;Po;0;L;;;;;N;;;;; -1C40;LEPCHA DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1C41;LEPCHA DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1C42;LEPCHA DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1C43;LEPCHA DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1C44;LEPCHA DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1C45;LEPCHA DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1C46;LEPCHA DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1C47;LEPCHA DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1C48;LEPCHA DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1C49;LEPCHA DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1C4D;LEPCHA LETTER TTA;Lo;0;L;;;;;N;;;;; -1C4E;LEPCHA LETTER TTHA;Lo;0;L;;;;;N;;;;; -1C4F;LEPCHA LETTER DDA;Lo;0;L;;;;;N;;;;; -1C50;OL CHIKI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -1C51;OL CHIKI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -1C52;OL CHIKI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -1C53;OL CHIKI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -1C54;OL CHIKI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -1C55;OL CHIKI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -1C56;OL CHIKI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -1C57;OL CHIKI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -1C58;OL CHIKI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -1C59;OL CHIKI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -1C5A;OL CHIKI LETTER LA;Lo;0;L;;;;;N;;;;; -1C5B;OL CHIKI LETTER AT;Lo;0;L;;;;;N;;;;; -1C5C;OL CHIKI LETTER AG;Lo;0;L;;;;;N;;;;; -1C5D;OL CHIKI LETTER ANG;Lo;0;L;;;;;N;;;;; -1C5E;OL CHIKI LETTER AL;Lo;0;L;;;;;N;;;;; -1C5F;OL CHIKI LETTER LAA;Lo;0;L;;;;;N;;;;; -1C60;OL CHIKI LETTER AAK;Lo;0;L;;;;;N;;;;; -1C61;OL CHIKI LETTER AAJ;Lo;0;L;;;;;N;;;;; -1C62;OL CHIKI LETTER AAM;Lo;0;L;;;;;N;;;;; -1C63;OL CHIKI LETTER AAW;Lo;0;L;;;;;N;;;;; -1C64;OL CHIKI LETTER LI;Lo;0;L;;;;;N;;;;; -1C65;OL CHIKI LETTER IS;Lo;0;L;;;;;N;;;;; -1C66;OL CHIKI LETTER IH;Lo;0;L;;;;;N;;;;; -1C67;OL CHIKI LETTER INY;Lo;0;L;;;;;N;;;;; -1C68;OL CHIKI LETTER IR;Lo;0;L;;;;;N;;;;; -1C69;OL CHIKI LETTER LU;Lo;0;L;;;;;N;;;;; -1C6A;OL CHIKI LETTER UC;Lo;0;L;;;;;N;;;;; -1C6B;OL CHIKI LETTER UD;Lo;0;L;;;;;N;;;;; -1C6C;OL CHIKI LETTER UNN;Lo;0;L;;;;;N;;;;; -1C6D;OL CHIKI LETTER UY;Lo;0;L;;;;;N;;;;; -1C6E;OL CHIKI LETTER LE;Lo;0;L;;;;;N;;;;; -1C6F;OL CHIKI LETTER EP;Lo;0;L;;;;;N;;;;; -1C70;OL CHIKI LETTER EDD;Lo;0;L;;;;;N;;;;; -1C71;OL CHIKI LETTER EN;Lo;0;L;;;;;N;;;;; -1C72;OL CHIKI LETTER ERR;Lo;0;L;;;;;N;;;;; -1C73;OL CHIKI LETTER LO;Lo;0;L;;;;;N;;;;; -1C74;OL CHIKI LETTER OTT;Lo;0;L;;;;;N;;;;; -1C75;OL CHIKI LETTER OB;Lo;0;L;;;;;N;;;;; -1C76;OL CHIKI LETTER OV;Lo;0;L;;;;;N;;;;; -1C77;OL CHIKI LETTER OH;Lo;0;L;;;;;N;;;;; -1C78;OL CHIKI MU TTUDDAG;Lm;0;L;;;;;N;;;;; -1C79;OL CHIKI GAAHLAA TTUDDAAG;Lm;0;L;;;;;N;;;;; -1C7A;OL CHIKI MU-GAAHLAA TTUDDAAG;Lm;0;L;;;;;N;;;;; -1C7B;OL CHIKI RELAA;Lm;0;L;;;;;N;;;;; -1C7C;OL CHIKI PHAARKAA;Lm;0;L;;;;;N;;;;; -1C7D;OL CHIKI AHAD;Lm;0;L;;;;;N;;;;; -1C7E;OL CHIKI PUNCTUATION MUCAAD;Po;0;L;;;;;N;;;;; -1C7F;OL CHIKI PUNCTUATION DOUBLE MUCAAD;Po;0;L;;;;;N;;;;; -1D00;LATIN LETTER SMALL CAPITAL A;Ll;0;L;;;;;N;;;;; -1D01;LATIN LETTER SMALL CAPITAL AE;Ll;0;L;;;;;N;;;;; -1D02;LATIN SMALL LETTER TURNED AE;Ll;0;L;;;;;N;;;;; -1D03;LATIN LETTER SMALL CAPITAL BARRED B;Ll;0;L;;;;;N;;;;; -1D04;LATIN LETTER SMALL CAPITAL C;Ll;0;L;;;;;N;;;;; -1D05;LATIN LETTER SMALL CAPITAL D;Ll;0;L;;;;;N;;;;; -1D06;LATIN LETTER SMALL CAPITAL ETH;Ll;0;L;;;;;N;;;;; -1D07;LATIN LETTER SMALL CAPITAL E;Ll;0;L;;;;;N;;;;; -1D08;LATIN SMALL LETTER TURNED OPEN E;Ll;0;L;;;;;N;;;;; -1D09;LATIN SMALL LETTER TURNED I;Ll;0;L;;;;;N;;;;; -1D0A;LATIN LETTER SMALL CAPITAL J;Ll;0;L;;;;;N;;;;; -1D0B;LATIN LETTER SMALL CAPITAL K;Ll;0;L;;;;;N;;;;; -1D0C;LATIN LETTER SMALL CAPITAL L WITH STROKE;Ll;0;L;;;;;N;;;;; -1D0D;LATIN LETTER SMALL CAPITAL M;Ll;0;L;;;;;N;;;;; -1D0E;LATIN LETTER SMALL CAPITAL REVERSED N;Ll;0;L;;;;;N;;;;; -1D0F;LATIN LETTER SMALL CAPITAL O;Ll;0;L;;;;;N;;;;; -1D10;LATIN LETTER SMALL CAPITAL OPEN O;Ll;0;L;;;;;N;;;;; -1D11;LATIN SMALL LETTER SIDEWAYS O;Ll;0;L;;;;;N;;;;; -1D12;LATIN SMALL LETTER SIDEWAYS OPEN O;Ll;0;L;;;;;N;;;;; -1D13;LATIN SMALL LETTER SIDEWAYS O WITH STROKE;Ll;0;L;;;;;N;;;;; -1D14;LATIN SMALL LETTER TURNED OE;Ll;0;L;;;;;N;;;;; -1D15;LATIN LETTER SMALL CAPITAL OU;Ll;0;L;;;;;N;;;;; -1D16;LATIN SMALL LETTER TOP HALF O;Ll;0;L;;;;;N;;;;; -1D17;LATIN SMALL LETTER BOTTOM HALF O;Ll;0;L;;;;;N;;;;; -1D18;LATIN LETTER SMALL CAPITAL P;Ll;0;L;;;;;N;;;;; -1D19;LATIN LETTER SMALL CAPITAL REVERSED R;Ll;0;L;;;;;N;;;;; -1D1A;LATIN LETTER SMALL CAPITAL TURNED R;Ll;0;L;;;;;N;;;;; -1D1B;LATIN LETTER SMALL CAPITAL T;Ll;0;L;;;;;N;;;;; -1D1C;LATIN LETTER SMALL CAPITAL U;Ll;0;L;;;;;N;;;;; -1D1D;LATIN SMALL LETTER SIDEWAYS U;Ll;0;L;;;;;N;;;;; -1D1E;LATIN SMALL LETTER SIDEWAYS DIAERESIZED U;Ll;0;L;;;;;N;;;;; -1D1F;LATIN SMALL LETTER SIDEWAYS TURNED M;Ll;0;L;;;;;N;;;;; -1D20;LATIN LETTER SMALL CAPITAL V;Ll;0;L;;;;;N;;;;; -1D21;LATIN LETTER SMALL CAPITAL W;Ll;0;L;;;;;N;;;;; -1D22;LATIN LETTER SMALL CAPITAL Z;Ll;0;L;;;;;N;;;;; -1D23;LATIN LETTER SMALL CAPITAL EZH;Ll;0;L;;;;;N;;;;; -1D24;LATIN LETTER VOICED LARYNGEAL SPIRANT;Ll;0;L;;;;;N;;;;; -1D25;LATIN LETTER AIN;Ll;0;L;;;;;N;;;;; -1D26;GREEK LETTER SMALL CAPITAL GAMMA;Ll;0;L;;;;;N;;;;; -1D27;GREEK LETTER SMALL CAPITAL LAMDA;Ll;0;L;;;;;N;;;;; -1D28;GREEK LETTER SMALL CAPITAL PI;Ll;0;L;;;;;N;;;;; -1D29;GREEK LETTER SMALL CAPITAL RHO;Ll;0;L;;;;;N;;;;; -1D2A;GREEK LETTER SMALL CAPITAL PSI;Ll;0;L;;;;;N;;;;; -1D2B;CYRILLIC LETTER SMALL CAPITAL EL;Ll;0;L;;;;;N;;;;; -1D2C;MODIFIER LETTER CAPITAL A;Lm;0;L; 0041;;;;N;;;;; -1D2D;MODIFIER LETTER CAPITAL AE;Lm;0;L; 00C6;;;;N;;;;; -1D2E;MODIFIER LETTER CAPITAL B;Lm;0;L; 0042;;;;N;;;;; -1D2F;MODIFIER LETTER CAPITAL BARRED B;Lm;0;L;;;;;N;;;;; -1D30;MODIFIER LETTER CAPITAL D;Lm;0;L; 0044;;;;N;;;;; -1D31;MODIFIER LETTER CAPITAL E;Lm;0;L; 0045;;;;N;;;;; -1D32;MODIFIER LETTER CAPITAL REVERSED E;Lm;0;L; 018E;;;;N;;;;; -1D33;MODIFIER LETTER CAPITAL G;Lm;0;L; 0047;;;;N;;;;; -1D34;MODIFIER LETTER CAPITAL H;Lm;0;L; 0048;;;;N;;;;; -1D35;MODIFIER LETTER CAPITAL I;Lm;0;L; 0049;;;;N;;;;; -1D36;MODIFIER LETTER CAPITAL J;Lm;0;L; 004A;;;;N;;;;; -1D37;MODIFIER LETTER CAPITAL K;Lm;0;L; 004B;;;;N;;;;; -1D38;MODIFIER LETTER CAPITAL L;Lm;0;L; 004C;;;;N;;;;; -1D39;MODIFIER LETTER CAPITAL M;Lm;0;L; 004D;;;;N;;;;; -1D3A;MODIFIER LETTER CAPITAL N;Lm;0;L; 004E;;;;N;;;;; -1D3B;MODIFIER LETTER CAPITAL REVERSED N;Lm;0;L;;;;;N;;;;; -1D3C;MODIFIER LETTER CAPITAL O;Lm;0;L; 004F;;;;N;;;;; -1D3D;MODIFIER LETTER CAPITAL OU;Lm;0;L; 0222;;;;N;;;;; -1D3E;MODIFIER LETTER CAPITAL P;Lm;0;L; 0050;;;;N;;;;; -1D3F;MODIFIER LETTER CAPITAL R;Lm;0;L; 0052;;;;N;;;;; -1D40;MODIFIER LETTER CAPITAL T;Lm;0;L; 0054;;;;N;;;;; -1D41;MODIFIER LETTER CAPITAL U;Lm;0;L; 0055;;;;N;;;;; -1D42;MODIFIER LETTER CAPITAL W;Lm;0;L; 0057;;;;N;;;;; -1D43;MODIFIER LETTER SMALL A;Lm;0;L; 0061;;;;N;;;;; -1D44;MODIFIER LETTER SMALL TURNED A;Lm;0;L; 0250;;;;N;;;;; -1D45;MODIFIER LETTER SMALL ALPHA;Lm;0;L; 0251;;;;N;;;;; -1D46;MODIFIER LETTER SMALL TURNED AE;Lm;0;L; 1D02;;;;N;;;;; -1D47;MODIFIER LETTER SMALL B;Lm;0;L; 0062;;;;N;;;;; -1D48;MODIFIER LETTER SMALL D;Lm;0;L; 0064;;;;N;;;;; -1D49;MODIFIER LETTER SMALL E;Lm;0;L; 0065;;;;N;;;;; -1D4A;MODIFIER LETTER SMALL SCHWA;Lm;0;L; 0259;;;;N;;;;; -1D4B;MODIFIER LETTER SMALL OPEN E;Lm;0;L; 025B;;;;N;;;;; -1D4C;MODIFIER LETTER SMALL TURNED OPEN E;Lm;0;L; 025C;;;;N;;;;; -1D4D;MODIFIER LETTER SMALL G;Lm;0;L; 0067;;;;N;;;;; -1D4E;MODIFIER LETTER SMALL TURNED I;Lm;0;L;;;;;N;;;;; -1D4F;MODIFIER LETTER SMALL K;Lm;0;L; 006B;;;;N;;;;; -1D50;MODIFIER LETTER SMALL M;Lm;0;L; 006D;;;;N;;;;; -1D51;MODIFIER LETTER SMALL ENG;Lm;0;L; 014B;;;;N;;;;; -1D52;MODIFIER LETTER SMALL O;Lm;0;L; 006F;;;;N;;;;; -1D53;MODIFIER LETTER SMALL OPEN O;Lm;0;L; 0254;;;;N;;;;; -1D54;MODIFIER LETTER SMALL TOP HALF O;Lm;0;L; 1D16;;;;N;;;;; -1D55;MODIFIER LETTER SMALL BOTTOM HALF O;Lm;0;L; 1D17;;;;N;;;;; -1D56;MODIFIER LETTER SMALL P;Lm;0;L; 0070;;;;N;;;;; -1D57;MODIFIER LETTER SMALL T;Lm;0;L; 0074;;;;N;;;;; -1D58;MODIFIER LETTER SMALL U;Lm;0;L; 0075;;;;N;;;;; -1D59;MODIFIER LETTER SMALL SIDEWAYS U;Lm;0;L; 1D1D;;;;N;;;;; -1D5A;MODIFIER LETTER SMALL TURNED M;Lm;0;L; 026F;;;;N;;;;; -1D5B;MODIFIER LETTER SMALL V;Lm;0;L; 0076;;;;N;;;;; -1D5C;MODIFIER LETTER SMALL AIN;Lm;0;L; 1D25;;;;N;;;;; -1D5D;MODIFIER LETTER SMALL BETA;Lm;0;L; 03B2;;;;N;;;;; -1D5E;MODIFIER LETTER SMALL GREEK GAMMA;Lm;0;L; 03B3;;;;N;;;;; -1D5F;MODIFIER LETTER SMALL DELTA;Lm;0;L; 03B4;;;;N;;;;; -1D60;MODIFIER LETTER SMALL GREEK PHI;Lm;0;L; 03C6;;;;N;;;;; -1D61;MODIFIER LETTER SMALL CHI;Lm;0;L; 03C7;;;;N;;;;; -1D62;LATIN SUBSCRIPT SMALL LETTER I;Ll;0;L; 0069;;;;N;;;;; -1D63;LATIN SUBSCRIPT SMALL LETTER R;Ll;0;L; 0072;;;;N;;;;; -1D64;LATIN SUBSCRIPT SMALL LETTER U;Ll;0;L; 0075;;;;N;;;;; -1D65;LATIN SUBSCRIPT SMALL LETTER V;Ll;0;L; 0076;;;;N;;;;; -1D66;GREEK SUBSCRIPT SMALL LETTER BETA;Ll;0;L; 03B2;;;;N;;;;; -1D67;GREEK SUBSCRIPT SMALL LETTER GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D68;GREEK SUBSCRIPT SMALL LETTER RHO;Ll;0;L; 03C1;;;;N;;;;; -1D69;GREEK SUBSCRIPT SMALL LETTER PHI;Ll;0;L; 03C6;;;;N;;;;; -1D6A;GREEK SUBSCRIPT SMALL LETTER CHI;Ll;0;L; 03C7;;;;N;;;;; -1D6B;LATIN SMALL LETTER UE;Ll;0;L;;;;;N;;;;; -1D6C;LATIN SMALL LETTER B WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D6D;LATIN SMALL LETTER D WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D6E;LATIN SMALL LETTER F WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D6F;LATIN SMALL LETTER M WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D70;LATIN SMALL LETTER N WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D71;LATIN SMALL LETTER P WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D72;LATIN SMALL LETTER R WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D73;LATIN SMALL LETTER R WITH FISHHOOK AND MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D74;LATIN SMALL LETTER S WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D75;LATIN SMALL LETTER T WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D76;LATIN SMALL LETTER Z WITH MIDDLE TILDE;Ll;0;L;;;;;N;;;;; -1D77;LATIN SMALL LETTER TURNED G;Ll;0;L;;;;;N;;;;; -1D78;MODIFIER LETTER CYRILLIC EN;Lm;0;L; 043D;;;;N;;;;; -1D79;LATIN SMALL LETTER INSULAR G;Ll;0;L;;;;;N;;;A77D;;A77D -1D7A;LATIN SMALL LETTER TH WITH STRIKETHROUGH;Ll;0;L;;;;;N;;;;; -1D7B;LATIN SMALL CAPITAL LETTER I WITH STROKE;Ll;0;L;;;;;N;;;;; -1D7C;LATIN SMALL LETTER IOTA WITH STROKE;Ll;0;L;;;;;N;;;;; -1D7D;LATIN SMALL LETTER P WITH STROKE;Ll;0;L;;;;;N;;;2C63;;2C63 -1D7E;LATIN SMALL CAPITAL LETTER U WITH STROKE;Ll;0;L;;;;;N;;;;; -1D7F;LATIN SMALL LETTER UPSILON WITH STROKE;Ll;0;L;;;;;N;;;;; -1D80;LATIN SMALL LETTER B WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D81;LATIN SMALL LETTER D WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D82;LATIN SMALL LETTER F WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D83;LATIN SMALL LETTER G WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D84;LATIN SMALL LETTER K WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D85;LATIN SMALL LETTER L WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D86;LATIN SMALL LETTER M WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D87;LATIN SMALL LETTER N WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D88;LATIN SMALL LETTER P WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D89;LATIN SMALL LETTER R WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8A;LATIN SMALL LETTER S WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8B;LATIN SMALL LETTER ESH WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8C;LATIN SMALL LETTER V WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8D;LATIN SMALL LETTER X WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8E;LATIN SMALL LETTER Z WITH PALATAL HOOK;Ll;0;L;;;;;N;;;;; -1D8F;LATIN SMALL LETTER A WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D90;LATIN SMALL LETTER ALPHA WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D91;LATIN SMALL LETTER D WITH HOOK AND TAIL;Ll;0;L;;;;;N;;;;; -1D92;LATIN SMALL LETTER E WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D93;LATIN SMALL LETTER OPEN E WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D94;LATIN SMALL LETTER REVERSED OPEN E WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D95;LATIN SMALL LETTER SCHWA WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D96;LATIN SMALL LETTER I WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D97;LATIN SMALL LETTER OPEN O WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D98;LATIN SMALL LETTER ESH WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D99;LATIN SMALL LETTER U WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D9A;LATIN SMALL LETTER EZH WITH RETROFLEX HOOK;Ll;0;L;;;;;N;;;;; -1D9B;MODIFIER LETTER SMALL TURNED ALPHA;Lm;0;L; 0252;;;;N;;;;; -1D9C;MODIFIER LETTER SMALL C;Lm;0;L; 0063;;;;N;;;;; -1D9D;MODIFIER LETTER SMALL C WITH CURL;Lm;0;L; 0255;;;;N;;;;; -1D9E;MODIFIER LETTER SMALL ETH;Lm;0;L; 00F0;;;;N;;;;; -1D9F;MODIFIER LETTER SMALL REVERSED OPEN E;Lm;0;L; 025C;;;;N;;;;; -1DA0;MODIFIER LETTER SMALL F;Lm;0;L; 0066;;;;N;;;;; -1DA1;MODIFIER LETTER SMALL DOTLESS J WITH STROKE;Lm;0;L; 025F;;;;N;;;;; -1DA2;MODIFIER LETTER SMALL SCRIPT G;Lm;0;L; 0261;;;;N;;;;; -1DA3;MODIFIER LETTER SMALL TURNED H;Lm;0;L; 0265;;;;N;;;;; -1DA4;MODIFIER LETTER SMALL I WITH STROKE;Lm;0;L; 0268;;;;N;;;;; -1DA5;MODIFIER LETTER SMALL IOTA;Lm;0;L; 0269;;;;N;;;;; -1DA6;MODIFIER LETTER SMALL CAPITAL I;Lm;0;L; 026A;;;;N;;;;; -1DA7;MODIFIER LETTER SMALL CAPITAL I WITH STROKE;Lm;0;L; 1D7B;;;;N;;;;; -1DA8;MODIFIER LETTER SMALL J WITH CROSSED-TAIL;Lm;0;L; 029D;;;;N;;;;; -1DA9;MODIFIER LETTER SMALL L WITH RETROFLEX HOOK;Lm;0;L; 026D;;;;N;;;;; -1DAA;MODIFIER LETTER SMALL L WITH PALATAL HOOK;Lm;0;L; 1D85;;;;N;;;;; -1DAB;MODIFIER LETTER SMALL CAPITAL L;Lm;0;L; 029F;;;;N;;;;; -1DAC;MODIFIER LETTER SMALL M WITH HOOK;Lm;0;L; 0271;;;;N;;;;; -1DAD;MODIFIER LETTER SMALL TURNED M WITH LONG LEG;Lm;0;L; 0270;;;;N;;;;; -1DAE;MODIFIER LETTER SMALL N WITH LEFT HOOK;Lm;0;L; 0272;;;;N;;;;; -1DAF;MODIFIER LETTER SMALL N WITH RETROFLEX HOOK;Lm;0;L; 0273;;;;N;;;;; -1DB0;MODIFIER LETTER SMALL CAPITAL N;Lm;0;L; 0274;;;;N;;;;; -1DB1;MODIFIER LETTER SMALL BARRED O;Lm;0;L; 0275;;;;N;;;;; -1DB2;MODIFIER LETTER SMALL PHI;Lm;0;L; 0278;;;;N;;;;; -1DB3;MODIFIER LETTER SMALL S WITH HOOK;Lm;0;L; 0282;;;;N;;;;; -1DB4;MODIFIER LETTER SMALL ESH;Lm;0;L; 0283;;;;N;;;;; -1DB5;MODIFIER LETTER SMALL T WITH PALATAL HOOK;Lm;0;L; 01AB;;;;N;;;;; -1DB6;MODIFIER LETTER SMALL U BAR;Lm;0;L; 0289;;;;N;;;;; -1DB7;MODIFIER LETTER SMALL UPSILON;Lm;0;L; 028A;;;;N;;;;; -1DB8;MODIFIER LETTER SMALL CAPITAL U;Lm;0;L; 1D1C;;;;N;;;;; -1DB9;MODIFIER LETTER SMALL V WITH HOOK;Lm;0;L; 028B;;;;N;;;;; -1DBA;MODIFIER LETTER SMALL TURNED V;Lm;0;L; 028C;;;;N;;;;; -1DBB;MODIFIER LETTER SMALL Z;Lm;0;L; 007A;;;;N;;;;; -1DBC;MODIFIER LETTER SMALL Z WITH RETROFLEX HOOK;Lm;0;L; 0290;;;;N;;;;; -1DBD;MODIFIER LETTER SMALL Z WITH CURL;Lm;0;L; 0291;;;;N;;;;; -1DBE;MODIFIER LETTER SMALL EZH;Lm;0;L; 0292;;;;N;;;;; -1DBF;MODIFIER LETTER SMALL THETA;Lm;0;L; 03B8;;;;N;;;;; -1DC0;COMBINING DOTTED GRAVE ACCENT;Mn;230;NSM;;;;;N;;;;; -1DC1;COMBINING DOTTED ACUTE ACCENT;Mn;230;NSM;;;;;N;;;;; -1DC2;COMBINING SNAKE BELOW;Mn;220;NSM;;;;;N;;;;; -1DC3;COMBINING SUSPENSION MARK;Mn;230;NSM;;;;;N;;;;; -1DC4;COMBINING MACRON-ACUTE;Mn;230;NSM;;;;;N;;;;; -1DC5;COMBINING GRAVE-MACRON;Mn;230;NSM;;;;;N;;;;; -1DC6;COMBINING MACRON-GRAVE;Mn;230;NSM;;;;;N;;;;; -1DC7;COMBINING ACUTE-MACRON;Mn;230;NSM;;;;;N;;;;; -1DC8;COMBINING GRAVE-ACUTE-GRAVE;Mn;230;NSM;;;;;N;;;;; -1DC9;COMBINING ACUTE-GRAVE-ACUTE;Mn;230;NSM;;;;;N;;;;; -1DCA;COMBINING LATIN SMALL LETTER R BELOW;Mn;220;NSM;;;;;N;;;;; -1DCB;COMBINING BREVE-MACRON;Mn;230;NSM;;;;;N;;;;; -1DCC;COMBINING MACRON-BREVE;Mn;230;NSM;;;;;N;;;;; -1DCD;COMBINING DOUBLE CIRCUMFLEX ABOVE;Mn;234;NSM;;;;;N;;;;; -1DCE;COMBINING OGONEK ABOVE;Mn;214;NSM;;;;;N;;;;; -1DCF;COMBINING ZIGZAG BELOW;Mn;220;NSM;;;;;N;;;;; -1DD0;COMBINING IS BELOW;Mn;202;NSM;;;;;N;;;;; -1DD1;COMBINING UR ABOVE;Mn;230;NSM;;;;;N;;;;; -1DD2;COMBINING US ABOVE;Mn;230;NSM;;;;;N;;;;; -1DD3;COMBINING LATIN SMALL LETTER FLATTENED OPEN A ABOVE;Mn;230;NSM;;;;;N;;;;; -1DD4;COMBINING LATIN SMALL LETTER AE;Mn;230;NSM;;;;;N;;;;; -1DD5;COMBINING LATIN SMALL LETTER AO;Mn;230;NSM;;;;;N;;;;; -1DD6;COMBINING LATIN SMALL LETTER AV;Mn;230;NSM;;;;;N;;;;; -1DD7;COMBINING LATIN SMALL LETTER C CEDILLA;Mn;230;NSM;;;;;N;;;;; -1DD8;COMBINING LATIN SMALL LETTER INSULAR D;Mn;230;NSM;;;;;N;;;;; -1DD9;COMBINING LATIN SMALL LETTER ETH;Mn;230;NSM;;;;;N;;;;; -1DDA;COMBINING LATIN SMALL LETTER G;Mn;230;NSM;;;;;N;;;;; -1DDB;COMBINING LATIN LETTER SMALL CAPITAL G;Mn;230;NSM;;;;;N;;;;; -1DDC;COMBINING LATIN SMALL LETTER K;Mn;230;NSM;;;;;N;;;;; -1DDD;COMBINING LATIN SMALL LETTER L;Mn;230;NSM;;;;;N;;;;; -1DDE;COMBINING LATIN LETTER SMALL CAPITAL L;Mn;230;NSM;;;;;N;;;;; -1DDF;COMBINING LATIN LETTER SMALL CAPITAL M;Mn;230;NSM;;;;;N;;;;; -1DE0;COMBINING LATIN SMALL LETTER N;Mn;230;NSM;;;;;N;;;;; -1DE1;COMBINING LATIN LETTER SMALL CAPITAL N;Mn;230;NSM;;;;;N;;;;; -1DE2;COMBINING LATIN LETTER SMALL CAPITAL R;Mn;230;NSM;;;;;N;;;;; -1DE3;COMBINING LATIN SMALL LETTER R ROTUNDA;Mn;230;NSM;;;;;N;;;;; -1DE4;COMBINING LATIN SMALL LETTER S;Mn;230;NSM;;;;;N;;;;; -1DE5;COMBINING LATIN SMALL LETTER LONG S;Mn;230;NSM;;;;;N;;;;; -1DE6;COMBINING LATIN SMALL LETTER Z;Mn;230;NSM;;;;;N;;;;; -1DFE;COMBINING LEFT ARROWHEAD ABOVE;Mn;230;NSM;;;;;N;;;;; -1DFF;COMBINING RIGHT ARROWHEAD AND DOWN ARROWHEAD BELOW;Mn;220;NSM;;;;;N;;;;; -1E00;LATIN CAPITAL LETTER A WITH RING BELOW;Lu;0;L;0041 0325;;;;N;;;;1E01; -1E01;LATIN SMALL LETTER A WITH RING BELOW;Ll;0;L;0061 0325;;;;N;;;1E00;;1E00 -1E02;LATIN CAPITAL LETTER B WITH DOT ABOVE;Lu;0;L;0042 0307;;;;N;;;;1E03; -1E03;LATIN SMALL LETTER B WITH DOT ABOVE;Ll;0;L;0062 0307;;;;N;;;1E02;;1E02 -1E04;LATIN CAPITAL LETTER B WITH DOT BELOW;Lu;0;L;0042 0323;;;;N;;;;1E05; -1E05;LATIN SMALL LETTER B WITH DOT BELOW;Ll;0;L;0062 0323;;;;N;;;1E04;;1E04 -1E06;LATIN CAPITAL LETTER B WITH LINE BELOW;Lu;0;L;0042 0331;;;;N;;;;1E07; -1E07;LATIN SMALL LETTER B WITH LINE BELOW;Ll;0;L;0062 0331;;;;N;;;1E06;;1E06 -1E08;LATIN CAPITAL LETTER C WITH CEDILLA AND ACUTE;Lu;0;L;00C7 0301;;;;N;;;;1E09; -1E09;LATIN SMALL LETTER C WITH CEDILLA AND ACUTE;Ll;0;L;00E7 0301;;;;N;;;1E08;;1E08 -1E0A;LATIN CAPITAL LETTER D WITH DOT ABOVE;Lu;0;L;0044 0307;;;;N;;;;1E0B; -1E0B;LATIN SMALL LETTER D WITH DOT ABOVE;Ll;0;L;0064 0307;;;;N;;;1E0A;;1E0A -1E0C;LATIN CAPITAL LETTER D WITH DOT BELOW;Lu;0;L;0044 0323;;;;N;;;;1E0D; -1E0D;LATIN SMALL LETTER D WITH DOT BELOW;Ll;0;L;0064 0323;;;;N;;;1E0C;;1E0C -1E0E;LATIN CAPITAL LETTER D WITH LINE BELOW;Lu;0;L;0044 0331;;;;N;;;;1E0F; -1E0F;LATIN SMALL LETTER D WITH LINE BELOW;Ll;0;L;0064 0331;;;;N;;;1E0E;;1E0E -1E10;LATIN CAPITAL LETTER D WITH CEDILLA;Lu;0;L;0044 0327;;;;N;;;;1E11; -1E11;LATIN SMALL LETTER D WITH CEDILLA;Ll;0;L;0064 0327;;;;N;;;1E10;;1E10 -1E12;LATIN CAPITAL LETTER D WITH CIRCUMFLEX BELOW;Lu;0;L;0044 032D;;;;N;;;;1E13; -1E13;LATIN SMALL LETTER D WITH CIRCUMFLEX BELOW;Ll;0;L;0064 032D;;;;N;;;1E12;;1E12 -1E14;LATIN CAPITAL LETTER E WITH MACRON AND GRAVE;Lu;0;L;0112 0300;;;;N;;;;1E15; -1E15;LATIN SMALL LETTER E WITH MACRON AND GRAVE;Ll;0;L;0113 0300;;;;N;;;1E14;;1E14 -1E16;LATIN CAPITAL LETTER E WITH MACRON AND ACUTE;Lu;0;L;0112 0301;;;;N;;;;1E17; -1E17;LATIN SMALL LETTER E WITH MACRON AND ACUTE;Ll;0;L;0113 0301;;;;N;;;1E16;;1E16 -1E18;LATIN CAPITAL LETTER E WITH CIRCUMFLEX BELOW;Lu;0;L;0045 032D;;;;N;;;;1E19; -1E19;LATIN SMALL LETTER E WITH CIRCUMFLEX BELOW;Ll;0;L;0065 032D;;;;N;;;1E18;;1E18 -1E1A;LATIN CAPITAL LETTER E WITH TILDE BELOW;Lu;0;L;0045 0330;;;;N;;;;1E1B; -1E1B;LATIN SMALL LETTER E WITH TILDE BELOW;Ll;0;L;0065 0330;;;;N;;;1E1A;;1E1A -1E1C;LATIN CAPITAL LETTER E WITH CEDILLA AND BREVE;Lu;0;L;0228 0306;;;;N;;;;1E1D; -1E1D;LATIN SMALL LETTER E WITH CEDILLA AND BREVE;Ll;0;L;0229 0306;;;;N;;;1E1C;;1E1C -1E1E;LATIN CAPITAL LETTER F WITH DOT ABOVE;Lu;0;L;0046 0307;;;;N;;;;1E1F; -1E1F;LATIN SMALL LETTER F WITH DOT ABOVE;Ll;0;L;0066 0307;;;;N;;;1E1E;;1E1E -1E20;LATIN CAPITAL LETTER G WITH MACRON;Lu;0;L;0047 0304;;;;N;;;;1E21; -1E21;LATIN SMALL LETTER G WITH MACRON;Ll;0;L;0067 0304;;;;N;;;1E20;;1E20 -1E22;LATIN CAPITAL LETTER H WITH DOT ABOVE;Lu;0;L;0048 0307;;;;N;;;;1E23; -1E23;LATIN SMALL LETTER H WITH DOT ABOVE;Ll;0;L;0068 0307;;;;N;;;1E22;;1E22 -1E24;LATIN CAPITAL LETTER H WITH DOT BELOW;Lu;0;L;0048 0323;;;;N;;;;1E25; -1E25;LATIN SMALL LETTER H WITH DOT BELOW;Ll;0;L;0068 0323;;;;N;;;1E24;;1E24 -1E26;LATIN CAPITAL LETTER H WITH DIAERESIS;Lu;0;L;0048 0308;;;;N;;;;1E27; -1E27;LATIN SMALL LETTER H WITH DIAERESIS;Ll;0;L;0068 0308;;;;N;;;1E26;;1E26 -1E28;LATIN CAPITAL LETTER H WITH CEDILLA;Lu;0;L;0048 0327;;;;N;;;;1E29; -1E29;LATIN SMALL LETTER H WITH CEDILLA;Ll;0;L;0068 0327;;;;N;;;1E28;;1E28 -1E2A;LATIN CAPITAL LETTER H WITH BREVE BELOW;Lu;0;L;0048 032E;;;;N;;;;1E2B; -1E2B;LATIN SMALL LETTER H WITH BREVE BELOW;Ll;0;L;0068 032E;;;;N;;;1E2A;;1E2A -1E2C;LATIN CAPITAL LETTER I WITH TILDE BELOW;Lu;0;L;0049 0330;;;;N;;;;1E2D; -1E2D;LATIN SMALL LETTER I WITH TILDE BELOW;Ll;0;L;0069 0330;;;;N;;;1E2C;;1E2C -1E2E;LATIN CAPITAL LETTER I WITH DIAERESIS AND ACUTE;Lu;0;L;00CF 0301;;;;N;;;;1E2F; -1E2F;LATIN SMALL LETTER I WITH DIAERESIS AND ACUTE;Ll;0;L;00EF 0301;;;;N;;;1E2E;;1E2E -1E30;LATIN CAPITAL LETTER K WITH ACUTE;Lu;0;L;004B 0301;;;;N;;;;1E31; -1E31;LATIN SMALL LETTER K WITH ACUTE;Ll;0;L;006B 0301;;;;N;;;1E30;;1E30 -1E32;LATIN CAPITAL LETTER K WITH DOT BELOW;Lu;0;L;004B 0323;;;;N;;;;1E33; -1E33;LATIN SMALL LETTER K WITH DOT BELOW;Ll;0;L;006B 0323;;;;N;;;1E32;;1E32 -1E34;LATIN CAPITAL LETTER K WITH LINE BELOW;Lu;0;L;004B 0331;;;;N;;;;1E35; -1E35;LATIN SMALL LETTER K WITH LINE BELOW;Ll;0;L;006B 0331;;;;N;;;1E34;;1E34 -1E36;LATIN CAPITAL LETTER L WITH DOT BELOW;Lu;0;L;004C 0323;;;;N;;;;1E37; -1E37;LATIN SMALL LETTER L WITH DOT BELOW;Ll;0;L;006C 0323;;;;N;;;1E36;;1E36 -1E38;LATIN CAPITAL LETTER L WITH DOT BELOW AND MACRON;Lu;0;L;1E36 0304;;;;N;;;;1E39; -1E39;LATIN SMALL LETTER L WITH DOT BELOW AND MACRON;Ll;0;L;1E37 0304;;;;N;;;1E38;;1E38 -1E3A;LATIN CAPITAL LETTER L WITH LINE BELOW;Lu;0;L;004C 0331;;;;N;;;;1E3B; -1E3B;LATIN SMALL LETTER L WITH LINE BELOW;Ll;0;L;006C 0331;;;;N;;;1E3A;;1E3A -1E3C;LATIN CAPITAL LETTER L WITH CIRCUMFLEX BELOW;Lu;0;L;004C 032D;;;;N;;;;1E3D; -1E3D;LATIN SMALL LETTER L WITH CIRCUMFLEX BELOW;Ll;0;L;006C 032D;;;;N;;;1E3C;;1E3C -1E3E;LATIN CAPITAL LETTER M WITH ACUTE;Lu;0;L;004D 0301;;;;N;;;;1E3F; -1E3F;LATIN SMALL LETTER M WITH ACUTE;Ll;0;L;006D 0301;;;;N;;;1E3E;;1E3E -1E40;LATIN CAPITAL LETTER M WITH DOT ABOVE;Lu;0;L;004D 0307;;;;N;;;;1E41; -1E41;LATIN SMALL LETTER M WITH DOT ABOVE;Ll;0;L;006D 0307;;;;N;;;1E40;;1E40 -1E42;LATIN CAPITAL LETTER M WITH DOT BELOW;Lu;0;L;004D 0323;;;;N;;;;1E43; -1E43;LATIN SMALL LETTER M WITH DOT BELOW;Ll;0;L;006D 0323;;;;N;;;1E42;;1E42 -1E44;LATIN CAPITAL LETTER N WITH DOT ABOVE;Lu;0;L;004E 0307;;;;N;;;;1E45; -1E45;LATIN SMALL LETTER N WITH DOT ABOVE;Ll;0;L;006E 0307;;;;N;;;1E44;;1E44 -1E46;LATIN CAPITAL LETTER N WITH DOT BELOW;Lu;0;L;004E 0323;;;;N;;;;1E47; -1E47;LATIN SMALL LETTER N WITH DOT BELOW;Ll;0;L;006E 0323;;;;N;;;1E46;;1E46 -1E48;LATIN CAPITAL LETTER N WITH LINE BELOW;Lu;0;L;004E 0331;;;;N;;;;1E49; -1E49;LATIN SMALL LETTER N WITH LINE BELOW;Ll;0;L;006E 0331;;;;N;;;1E48;;1E48 -1E4A;LATIN CAPITAL LETTER N WITH CIRCUMFLEX BELOW;Lu;0;L;004E 032D;;;;N;;;;1E4B; -1E4B;LATIN SMALL LETTER N WITH CIRCUMFLEX BELOW;Ll;0;L;006E 032D;;;;N;;;1E4A;;1E4A -1E4C;LATIN CAPITAL LETTER O WITH TILDE AND ACUTE;Lu;0;L;00D5 0301;;;;N;;;;1E4D; -1E4D;LATIN SMALL LETTER O WITH TILDE AND ACUTE;Ll;0;L;00F5 0301;;;;N;;;1E4C;;1E4C -1E4E;LATIN CAPITAL LETTER O WITH TILDE AND DIAERESIS;Lu;0;L;00D5 0308;;;;N;;;;1E4F; -1E4F;LATIN SMALL LETTER O WITH TILDE AND DIAERESIS;Ll;0;L;00F5 0308;;;;N;;;1E4E;;1E4E -1E50;LATIN CAPITAL LETTER O WITH MACRON AND GRAVE;Lu;0;L;014C 0300;;;;N;;;;1E51; -1E51;LATIN SMALL LETTER O WITH MACRON AND GRAVE;Ll;0;L;014D 0300;;;;N;;;1E50;;1E50 -1E52;LATIN CAPITAL LETTER O WITH MACRON AND ACUTE;Lu;0;L;014C 0301;;;;N;;;;1E53; -1E53;LATIN SMALL LETTER O WITH MACRON AND ACUTE;Ll;0;L;014D 0301;;;;N;;;1E52;;1E52 -1E54;LATIN CAPITAL LETTER P WITH ACUTE;Lu;0;L;0050 0301;;;;N;;;;1E55; -1E55;LATIN SMALL LETTER P WITH ACUTE;Ll;0;L;0070 0301;;;;N;;;1E54;;1E54 -1E56;LATIN CAPITAL LETTER P WITH DOT ABOVE;Lu;0;L;0050 0307;;;;N;;;;1E57; -1E57;LATIN SMALL LETTER P WITH DOT ABOVE;Ll;0;L;0070 0307;;;;N;;;1E56;;1E56 -1E58;LATIN CAPITAL LETTER R WITH DOT ABOVE;Lu;0;L;0052 0307;;;;N;;;;1E59; -1E59;LATIN SMALL LETTER R WITH DOT ABOVE;Ll;0;L;0072 0307;;;;N;;;1E58;;1E58 -1E5A;LATIN CAPITAL LETTER R WITH DOT BELOW;Lu;0;L;0052 0323;;;;N;;;;1E5B; -1E5B;LATIN SMALL LETTER R WITH DOT BELOW;Ll;0;L;0072 0323;;;;N;;;1E5A;;1E5A -1E5C;LATIN CAPITAL LETTER R WITH DOT BELOW AND MACRON;Lu;0;L;1E5A 0304;;;;N;;;;1E5D; -1E5D;LATIN SMALL LETTER R WITH DOT BELOW AND MACRON;Ll;0;L;1E5B 0304;;;;N;;;1E5C;;1E5C -1E5E;LATIN CAPITAL LETTER R WITH LINE BELOW;Lu;0;L;0052 0331;;;;N;;;;1E5F; -1E5F;LATIN SMALL LETTER R WITH LINE BELOW;Ll;0;L;0072 0331;;;;N;;;1E5E;;1E5E -1E60;LATIN CAPITAL LETTER S WITH DOT ABOVE;Lu;0;L;0053 0307;;;;N;;;;1E61; -1E61;LATIN SMALL LETTER S WITH DOT ABOVE;Ll;0;L;0073 0307;;;;N;;;1E60;;1E60 -1E62;LATIN CAPITAL LETTER S WITH DOT BELOW;Lu;0;L;0053 0323;;;;N;;;;1E63; -1E63;LATIN SMALL LETTER S WITH DOT BELOW;Ll;0;L;0073 0323;;;;N;;;1E62;;1E62 -1E64;LATIN CAPITAL LETTER S WITH ACUTE AND DOT ABOVE;Lu;0;L;015A 0307;;;;N;;;;1E65; -1E65;LATIN SMALL LETTER S WITH ACUTE AND DOT ABOVE;Ll;0;L;015B 0307;;;;N;;;1E64;;1E64 -1E66;LATIN CAPITAL LETTER S WITH CARON AND DOT ABOVE;Lu;0;L;0160 0307;;;;N;;;;1E67; -1E67;LATIN SMALL LETTER S WITH CARON AND DOT ABOVE;Ll;0;L;0161 0307;;;;N;;;1E66;;1E66 -1E68;LATIN CAPITAL LETTER S WITH DOT BELOW AND DOT ABOVE;Lu;0;L;1E62 0307;;;;N;;;;1E69; -1E69;LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE;Ll;0;L;1E63 0307;;;;N;;;1E68;;1E68 -1E6A;LATIN CAPITAL LETTER T WITH DOT ABOVE;Lu;0;L;0054 0307;;;;N;;;;1E6B; -1E6B;LATIN SMALL LETTER T WITH DOT ABOVE;Ll;0;L;0074 0307;;;;N;;;1E6A;;1E6A -1E6C;LATIN CAPITAL LETTER T WITH DOT BELOW;Lu;0;L;0054 0323;;;;N;;;;1E6D; -1E6D;LATIN SMALL LETTER T WITH DOT BELOW;Ll;0;L;0074 0323;;;;N;;;1E6C;;1E6C -1E6E;LATIN CAPITAL LETTER T WITH LINE BELOW;Lu;0;L;0054 0331;;;;N;;;;1E6F; -1E6F;LATIN SMALL LETTER T WITH LINE BELOW;Ll;0;L;0074 0331;;;;N;;;1E6E;;1E6E -1E70;LATIN CAPITAL LETTER T WITH CIRCUMFLEX BELOW;Lu;0;L;0054 032D;;;;N;;;;1E71; -1E71;LATIN SMALL LETTER T WITH CIRCUMFLEX BELOW;Ll;0;L;0074 032D;;;;N;;;1E70;;1E70 -1E72;LATIN CAPITAL LETTER U WITH DIAERESIS BELOW;Lu;0;L;0055 0324;;;;N;;;;1E73; -1E73;LATIN SMALL LETTER U WITH DIAERESIS BELOW;Ll;0;L;0075 0324;;;;N;;;1E72;;1E72 -1E74;LATIN CAPITAL LETTER U WITH TILDE BELOW;Lu;0;L;0055 0330;;;;N;;;;1E75; -1E75;LATIN SMALL LETTER U WITH TILDE BELOW;Ll;0;L;0075 0330;;;;N;;;1E74;;1E74 -1E76;LATIN CAPITAL LETTER U WITH CIRCUMFLEX BELOW;Lu;0;L;0055 032D;;;;N;;;;1E77; -1E77;LATIN SMALL LETTER U WITH CIRCUMFLEX BELOW;Ll;0;L;0075 032D;;;;N;;;1E76;;1E76 -1E78;LATIN CAPITAL LETTER U WITH TILDE AND ACUTE;Lu;0;L;0168 0301;;;;N;;;;1E79; -1E79;LATIN SMALL LETTER U WITH TILDE AND ACUTE;Ll;0;L;0169 0301;;;;N;;;1E78;;1E78 -1E7A;LATIN CAPITAL LETTER U WITH MACRON AND DIAERESIS;Lu;0;L;016A 0308;;;;N;;;;1E7B; -1E7B;LATIN SMALL LETTER U WITH MACRON AND DIAERESIS;Ll;0;L;016B 0308;;;;N;;;1E7A;;1E7A -1E7C;LATIN CAPITAL LETTER V WITH TILDE;Lu;0;L;0056 0303;;;;N;;;;1E7D; -1E7D;LATIN SMALL LETTER V WITH TILDE;Ll;0;L;0076 0303;;;;N;;;1E7C;;1E7C -1E7E;LATIN CAPITAL LETTER V WITH DOT BELOW;Lu;0;L;0056 0323;;;;N;;;;1E7F; -1E7F;LATIN SMALL LETTER V WITH DOT BELOW;Ll;0;L;0076 0323;;;;N;;;1E7E;;1E7E -1E80;LATIN CAPITAL LETTER W WITH GRAVE;Lu;0;L;0057 0300;;;;N;;;;1E81; -1E81;LATIN SMALL LETTER W WITH GRAVE;Ll;0;L;0077 0300;;;;N;;;1E80;;1E80 -1E82;LATIN CAPITAL LETTER W WITH ACUTE;Lu;0;L;0057 0301;;;;N;;;;1E83; -1E83;LATIN SMALL LETTER W WITH ACUTE;Ll;0;L;0077 0301;;;;N;;;1E82;;1E82 -1E84;LATIN CAPITAL LETTER W WITH DIAERESIS;Lu;0;L;0057 0308;;;;N;;;;1E85; -1E85;LATIN SMALL LETTER W WITH DIAERESIS;Ll;0;L;0077 0308;;;;N;;;1E84;;1E84 -1E86;LATIN CAPITAL LETTER W WITH DOT ABOVE;Lu;0;L;0057 0307;;;;N;;;;1E87; -1E87;LATIN SMALL LETTER W WITH DOT ABOVE;Ll;0;L;0077 0307;;;;N;;;1E86;;1E86 -1E88;LATIN CAPITAL LETTER W WITH DOT BELOW;Lu;0;L;0057 0323;;;;N;;;;1E89; -1E89;LATIN SMALL LETTER W WITH DOT BELOW;Ll;0;L;0077 0323;;;;N;;;1E88;;1E88 -1E8A;LATIN CAPITAL LETTER X WITH DOT ABOVE;Lu;0;L;0058 0307;;;;N;;;;1E8B; -1E8B;LATIN SMALL LETTER X WITH DOT ABOVE;Ll;0;L;0078 0307;;;;N;;;1E8A;;1E8A -1E8C;LATIN CAPITAL LETTER X WITH DIAERESIS;Lu;0;L;0058 0308;;;;N;;;;1E8D; -1E8D;LATIN SMALL LETTER X WITH DIAERESIS;Ll;0;L;0078 0308;;;;N;;;1E8C;;1E8C -1E8E;LATIN CAPITAL LETTER Y WITH DOT ABOVE;Lu;0;L;0059 0307;;;;N;;;;1E8F; -1E8F;LATIN SMALL LETTER Y WITH DOT ABOVE;Ll;0;L;0079 0307;;;;N;;;1E8E;;1E8E -1E90;LATIN CAPITAL LETTER Z WITH CIRCUMFLEX;Lu;0;L;005A 0302;;;;N;;;;1E91; -1E91;LATIN SMALL LETTER Z WITH CIRCUMFLEX;Ll;0;L;007A 0302;;;;N;;;1E90;;1E90 -1E92;LATIN CAPITAL LETTER Z WITH DOT BELOW;Lu;0;L;005A 0323;;;;N;;;;1E93; -1E93;LATIN SMALL LETTER Z WITH DOT BELOW;Ll;0;L;007A 0323;;;;N;;;1E92;;1E92 -1E94;LATIN CAPITAL LETTER Z WITH LINE BELOW;Lu;0;L;005A 0331;;;;N;;;;1E95; -1E95;LATIN SMALL LETTER Z WITH LINE BELOW;Ll;0;L;007A 0331;;;;N;;;1E94;;1E94 -1E96;LATIN SMALL LETTER H WITH LINE BELOW;Ll;0;L;0068 0331;;;;N;;;;; -1E97;LATIN SMALL LETTER T WITH DIAERESIS;Ll;0;L;0074 0308;;;;N;;;;; -1E98;LATIN SMALL LETTER W WITH RING ABOVE;Ll;0;L;0077 030A;;;;N;;;;; -1E99;LATIN SMALL LETTER Y WITH RING ABOVE;Ll;0;L;0079 030A;;;;N;;;;; -1E9A;LATIN SMALL LETTER A WITH RIGHT HALF RING;Ll;0;L; 0061 02BE;;;;N;;;;; -1E9B;LATIN SMALL LETTER LONG S WITH DOT ABOVE;Ll;0;L;017F 0307;;;;N;;;1E60;;1E60 -1E9C;LATIN SMALL LETTER LONG S WITH DIAGONAL STROKE;Ll;0;L;;;;;N;;;;; -1E9D;LATIN SMALL LETTER LONG S WITH HIGH STROKE;Ll;0;L;;;;;N;;;;; -1E9E;LATIN CAPITAL LETTER SHARP S;Lu;0;L;;;;;N;;;;00DF; -1E9F;LATIN SMALL LETTER DELTA;Ll;0;L;;;;;N;;;;; -1EA0;LATIN CAPITAL LETTER A WITH DOT BELOW;Lu;0;L;0041 0323;;;;N;;;;1EA1; -1EA1;LATIN SMALL LETTER A WITH DOT BELOW;Ll;0;L;0061 0323;;;;N;;;1EA0;;1EA0 -1EA2;LATIN CAPITAL LETTER A WITH HOOK ABOVE;Lu;0;L;0041 0309;;;;N;;;;1EA3; -1EA3;LATIN SMALL LETTER A WITH HOOK ABOVE;Ll;0;L;0061 0309;;;;N;;;1EA2;;1EA2 -1EA4;LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND ACUTE;Lu;0;L;00C2 0301;;;;N;;;;1EA5; -1EA5;LATIN SMALL LETTER A WITH CIRCUMFLEX AND ACUTE;Ll;0;L;00E2 0301;;;;N;;;1EA4;;1EA4 -1EA6;LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND GRAVE;Lu;0;L;00C2 0300;;;;N;;;;1EA7; -1EA7;LATIN SMALL LETTER A WITH CIRCUMFLEX AND GRAVE;Ll;0;L;00E2 0300;;;;N;;;1EA6;;1EA6 -1EA8;LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND HOOK ABOVE;Lu;0;L;00C2 0309;;;;N;;;;1EA9; -1EA9;LATIN SMALL LETTER A WITH CIRCUMFLEX AND HOOK ABOVE;Ll;0;L;00E2 0309;;;;N;;;1EA8;;1EA8 -1EAA;LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND TILDE;Lu;0;L;00C2 0303;;;;N;;;;1EAB; -1EAB;LATIN SMALL LETTER A WITH CIRCUMFLEX AND TILDE;Ll;0;L;00E2 0303;;;;N;;;1EAA;;1EAA -1EAC;LATIN CAPITAL LETTER A WITH CIRCUMFLEX AND DOT BELOW;Lu;0;L;1EA0 0302;;;;N;;;;1EAD; -1EAD;LATIN SMALL LETTER A WITH CIRCUMFLEX AND DOT BELOW;Ll;0;L;1EA1 0302;;;;N;;;1EAC;;1EAC -1EAE;LATIN CAPITAL LETTER A WITH BREVE AND ACUTE;Lu;0;L;0102 0301;;;;N;;;;1EAF; -1EAF;LATIN SMALL LETTER A WITH BREVE AND ACUTE;Ll;0;L;0103 0301;;;;N;;;1EAE;;1EAE -1EB0;LATIN CAPITAL LETTER A WITH BREVE AND GRAVE;Lu;0;L;0102 0300;;;;N;;;;1EB1; -1EB1;LATIN SMALL LETTER A WITH BREVE AND GRAVE;Ll;0;L;0103 0300;;;;N;;;1EB0;;1EB0 -1EB2;LATIN CAPITAL LETTER A WITH BREVE AND HOOK ABOVE;Lu;0;L;0102 0309;;;;N;;;;1EB3; -1EB3;LATIN SMALL LETTER A WITH BREVE AND HOOK ABOVE;Ll;0;L;0103 0309;;;;N;;;1EB2;;1EB2 -1EB4;LATIN CAPITAL LETTER A WITH BREVE AND TILDE;Lu;0;L;0102 0303;;;;N;;;;1EB5; -1EB5;LATIN SMALL LETTER A WITH BREVE AND TILDE;Ll;0;L;0103 0303;;;;N;;;1EB4;;1EB4 -1EB6;LATIN CAPITAL LETTER A WITH BREVE AND DOT BELOW;Lu;0;L;1EA0 0306;;;;N;;;;1EB7; -1EB7;LATIN SMALL LETTER A WITH BREVE AND DOT BELOW;Ll;0;L;1EA1 0306;;;;N;;;1EB6;;1EB6 -1EB8;LATIN CAPITAL LETTER E WITH DOT BELOW;Lu;0;L;0045 0323;;;;N;;;;1EB9; -1EB9;LATIN SMALL LETTER E WITH DOT BELOW;Ll;0;L;0065 0323;;;;N;;;1EB8;;1EB8 -1EBA;LATIN CAPITAL LETTER E WITH HOOK ABOVE;Lu;0;L;0045 0309;;;;N;;;;1EBB; -1EBB;LATIN SMALL LETTER E WITH HOOK ABOVE;Ll;0;L;0065 0309;;;;N;;;1EBA;;1EBA -1EBC;LATIN CAPITAL LETTER E WITH TILDE;Lu;0;L;0045 0303;;;;N;;;;1EBD; -1EBD;LATIN SMALL LETTER E WITH TILDE;Ll;0;L;0065 0303;;;;N;;;1EBC;;1EBC -1EBE;LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE;Lu;0;L;00CA 0301;;;;N;;;;1EBF; -1EBF;LATIN SMALL LETTER E WITH CIRCUMFLEX AND ACUTE;Ll;0;L;00EA 0301;;;;N;;;1EBE;;1EBE -1EC0;LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND GRAVE;Lu;0;L;00CA 0300;;;;N;;;;1EC1; -1EC1;LATIN SMALL LETTER E WITH CIRCUMFLEX AND GRAVE;Ll;0;L;00EA 0300;;;;N;;;1EC0;;1EC0 -1EC2;LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE;Lu;0;L;00CA 0309;;;;N;;;;1EC3; -1EC3;LATIN SMALL LETTER E WITH CIRCUMFLEX AND HOOK ABOVE;Ll;0;L;00EA 0309;;;;N;;;1EC2;;1EC2 -1EC4;LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND TILDE;Lu;0;L;00CA 0303;;;;N;;;;1EC5; -1EC5;LATIN SMALL LETTER E WITH CIRCUMFLEX AND TILDE;Ll;0;L;00EA 0303;;;;N;;;1EC4;;1EC4 -1EC6;LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND DOT BELOW;Lu;0;L;1EB8 0302;;;;N;;;;1EC7; -1EC7;LATIN SMALL LETTER E WITH CIRCUMFLEX AND DOT BELOW;Ll;0;L;1EB9 0302;;;;N;;;1EC6;;1EC6 -1EC8;LATIN CAPITAL LETTER I WITH HOOK ABOVE;Lu;0;L;0049 0309;;;;N;;;;1EC9; -1EC9;LATIN SMALL LETTER I WITH HOOK ABOVE;Ll;0;L;0069 0309;;;;N;;;1EC8;;1EC8 -1ECA;LATIN CAPITAL LETTER I WITH DOT BELOW;Lu;0;L;0049 0323;;;;N;;;;1ECB; -1ECB;LATIN SMALL LETTER I WITH DOT BELOW;Ll;0;L;0069 0323;;;;N;;;1ECA;;1ECA -1ECC;LATIN CAPITAL LETTER O WITH DOT BELOW;Lu;0;L;004F 0323;;;;N;;;;1ECD; -1ECD;LATIN SMALL LETTER O WITH DOT BELOW;Ll;0;L;006F 0323;;;;N;;;1ECC;;1ECC -1ECE;LATIN CAPITAL LETTER O WITH HOOK ABOVE;Lu;0;L;004F 0309;;;;N;;;;1ECF; -1ECF;LATIN SMALL LETTER O WITH HOOK ABOVE;Ll;0;L;006F 0309;;;;N;;;1ECE;;1ECE -1ED0;LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND ACUTE;Lu;0;L;00D4 0301;;;;N;;;;1ED1; -1ED1;LATIN SMALL LETTER O WITH CIRCUMFLEX AND ACUTE;Ll;0;L;00F4 0301;;;;N;;;1ED0;;1ED0 -1ED2;LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND GRAVE;Lu;0;L;00D4 0300;;;;N;;;;1ED3; -1ED3;LATIN SMALL LETTER O WITH CIRCUMFLEX AND GRAVE;Ll;0;L;00F4 0300;;;;N;;;1ED2;;1ED2 -1ED4;LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND HOOK ABOVE;Lu;0;L;00D4 0309;;;;N;;;;1ED5; -1ED5;LATIN SMALL LETTER O WITH CIRCUMFLEX AND HOOK ABOVE;Ll;0;L;00F4 0309;;;;N;;;1ED4;;1ED4 -1ED6;LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND TILDE;Lu;0;L;00D4 0303;;;;N;;;;1ED7; -1ED7;LATIN SMALL LETTER O WITH CIRCUMFLEX AND TILDE;Ll;0;L;00F4 0303;;;;N;;;1ED6;;1ED6 -1ED8;LATIN CAPITAL LETTER O WITH CIRCUMFLEX AND DOT BELOW;Lu;0;L;1ECC 0302;;;;N;;;;1ED9; -1ED9;LATIN SMALL LETTER O WITH CIRCUMFLEX AND DOT BELOW;Ll;0;L;1ECD 0302;;;;N;;;1ED8;;1ED8 -1EDA;LATIN CAPITAL LETTER O WITH HORN AND ACUTE;Lu;0;L;01A0 0301;;;;N;;;;1EDB; -1EDB;LATIN SMALL LETTER O WITH HORN AND ACUTE;Ll;0;L;01A1 0301;;;;N;;;1EDA;;1EDA -1EDC;LATIN CAPITAL LETTER O WITH HORN AND GRAVE;Lu;0;L;01A0 0300;;;;N;;;;1EDD; -1EDD;LATIN SMALL LETTER O WITH HORN AND GRAVE;Ll;0;L;01A1 0300;;;;N;;;1EDC;;1EDC -1EDE;LATIN CAPITAL LETTER O WITH HORN AND HOOK ABOVE;Lu;0;L;01A0 0309;;;;N;;;;1EDF; -1EDF;LATIN SMALL LETTER O WITH HORN AND HOOK ABOVE;Ll;0;L;01A1 0309;;;;N;;;1EDE;;1EDE -1EE0;LATIN CAPITAL LETTER O WITH HORN AND TILDE;Lu;0;L;01A0 0303;;;;N;;;;1EE1; -1EE1;LATIN SMALL LETTER O WITH HORN AND TILDE;Ll;0;L;01A1 0303;;;;N;;;1EE0;;1EE0 -1EE2;LATIN CAPITAL LETTER O WITH HORN AND DOT BELOW;Lu;0;L;01A0 0323;;;;N;;;;1EE3; -1EE3;LATIN SMALL LETTER O WITH HORN AND DOT BELOW;Ll;0;L;01A1 0323;;;;N;;;1EE2;;1EE2 -1EE4;LATIN CAPITAL LETTER U WITH DOT BELOW;Lu;0;L;0055 0323;;;;N;;;;1EE5; -1EE5;LATIN SMALL LETTER U WITH DOT BELOW;Ll;0;L;0075 0323;;;;N;;;1EE4;;1EE4 -1EE6;LATIN CAPITAL LETTER U WITH HOOK ABOVE;Lu;0;L;0055 0309;;;;N;;;;1EE7; -1EE7;LATIN SMALL LETTER U WITH HOOK ABOVE;Ll;0;L;0075 0309;;;;N;;;1EE6;;1EE6 -1EE8;LATIN CAPITAL LETTER U WITH HORN AND ACUTE;Lu;0;L;01AF 0301;;;;N;;;;1EE9; -1EE9;LATIN SMALL LETTER U WITH HORN AND ACUTE;Ll;0;L;01B0 0301;;;;N;;;1EE8;;1EE8 -1EEA;LATIN CAPITAL LETTER U WITH HORN AND GRAVE;Lu;0;L;01AF 0300;;;;N;;;;1EEB; -1EEB;LATIN SMALL LETTER U WITH HORN AND GRAVE;Ll;0;L;01B0 0300;;;;N;;;1EEA;;1EEA -1EEC;LATIN CAPITAL LETTER U WITH HORN AND HOOK ABOVE;Lu;0;L;01AF 0309;;;;N;;;;1EED; -1EED;LATIN SMALL LETTER U WITH HORN AND HOOK ABOVE;Ll;0;L;01B0 0309;;;;N;;;1EEC;;1EEC -1EEE;LATIN CAPITAL LETTER U WITH HORN AND TILDE;Lu;0;L;01AF 0303;;;;N;;;;1EEF; -1EEF;LATIN SMALL LETTER U WITH HORN AND TILDE;Ll;0;L;01B0 0303;;;;N;;;1EEE;;1EEE -1EF0;LATIN CAPITAL LETTER U WITH HORN AND DOT BELOW;Lu;0;L;01AF 0323;;;;N;;;;1EF1; -1EF1;LATIN SMALL LETTER U WITH HORN AND DOT BELOW;Ll;0;L;01B0 0323;;;;N;;;1EF0;;1EF0 -1EF2;LATIN CAPITAL LETTER Y WITH GRAVE;Lu;0;L;0059 0300;;;;N;;;;1EF3; -1EF3;LATIN SMALL LETTER Y WITH GRAVE;Ll;0;L;0079 0300;;;;N;;;1EF2;;1EF2 -1EF4;LATIN CAPITAL LETTER Y WITH DOT BELOW;Lu;0;L;0059 0323;;;;N;;;;1EF5; -1EF5;LATIN SMALL LETTER Y WITH DOT BELOW;Ll;0;L;0079 0323;;;;N;;;1EF4;;1EF4 -1EF6;LATIN CAPITAL LETTER Y WITH HOOK ABOVE;Lu;0;L;0059 0309;;;;N;;;;1EF7; -1EF7;LATIN SMALL LETTER Y WITH HOOK ABOVE;Ll;0;L;0079 0309;;;;N;;;1EF6;;1EF6 -1EF8;LATIN CAPITAL LETTER Y WITH TILDE;Lu;0;L;0059 0303;;;;N;;;;1EF9; -1EF9;LATIN SMALL LETTER Y WITH TILDE;Ll;0;L;0079 0303;;;;N;;;1EF8;;1EF8 -1EFA;LATIN CAPITAL LETTER MIDDLE-WELSH LL;Lu;0;L;;;;;N;;;;1EFB; -1EFB;LATIN SMALL LETTER MIDDLE-WELSH LL;Ll;0;L;;;;;N;;;1EFA;;1EFA -1EFC;LATIN CAPITAL LETTER MIDDLE-WELSH V;Lu;0;L;;;;;N;;;;1EFD; -1EFD;LATIN SMALL LETTER MIDDLE-WELSH V;Ll;0;L;;;;;N;;;1EFC;;1EFC -1EFE;LATIN CAPITAL LETTER Y WITH LOOP;Lu;0;L;;;;;N;;;;1EFF; -1EFF;LATIN SMALL LETTER Y WITH LOOP;Ll;0;L;;;;;N;;;1EFE;;1EFE -1F00;GREEK SMALL LETTER ALPHA WITH PSILI;Ll;0;L;03B1 0313;;;;N;;;1F08;;1F08 -1F01;GREEK SMALL LETTER ALPHA WITH DASIA;Ll;0;L;03B1 0314;;;;N;;;1F09;;1F09 -1F02;GREEK SMALL LETTER ALPHA WITH PSILI AND VARIA;Ll;0;L;1F00 0300;;;;N;;;1F0A;;1F0A -1F03;GREEK SMALL LETTER ALPHA WITH DASIA AND VARIA;Ll;0;L;1F01 0300;;;;N;;;1F0B;;1F0B -1F04;GREEK SMALL LETTER ALPHA WITH PSILI AND OXIA;Ll;0;L;1F00 0301;;;;N;;;1F0C;;1F0C -1F05;GREEK SMALL LETTER ALPHA WITH DASIA AND OXIA;Ll;0;L;1F01 0301;;;;N;;;1F0D;;1F0D -1F06;GREEK SMALL LETTER ALPHA WITH PSILI AND PERISPOMENI;Ll;0;L;1F00 0342;;;;N;;;1F0E;;1F0E -1F07;GREEK SMALL LETTER ALPHA WITH DASIA AND PERISPOMENI;Ll;0;L;1F01 0342;;;;N;;;1F0F;;1F0F -1F08;GREEK CAPITAL LETTER ALPHA WITH PSILI;Lu;0;L;0391 0313;;;;N;;;;1F00; -1F09;GREEK CAPITAL LETTER ALPHA WITH DASIA;Lu;0;L;0391 0314;;;;N;;;;1F01; -1F0A;GREEK CAPITAL LETTER ALPHA WITH PSILI AND VARIA;Lu;0;L;1F08 0300;;;;N;;;;1F02; -1F0B;GREEK CAPITAL LETTER ALPHA WITH DASIA AND VARIA;Lu;0;L;1F09 0300;;;;N;;;;1F03; -1F0C;GREEK CAPITAL LETTER ALPHA WITH PSILI AND OXIA;Lu;0;L;1F08 0301;;;;N;;;;1F04; -1F0D;GREEK CAPITAL LETTER ALPHA WITH DASIA AND OXIA;Lu;0;L;1F09 0301;;;;N;;;;1F05; -1F0E;GREEK CAPITAL LETTER ALPHA WITH PSILI AND PERISPOMENI;Lu;0;L;1F08 0342;;;;N;;;;1F06; -1F0F;GREEK CAPITAL LETTER ALPHA WITH DASIA AND PERISPOMENI;Lu;0;L;1F09 0342;;;;N;;;;1F07; -1F10;GREEK SMALL LETTER EPSILON WITH PSILI;Ll;0;L;03B5 0313;;;;N;;;1F18;;1F18 -1F11;GREEK SMALL LETTER EPSILON WITH DASIA;Ll;0;L;03B5 0314;;;;N;;;1F19;;1F19 -1F12;GREEK SMALL LETTER EPSILON WITH PSILI AND VARIA;Ll;0;L;1F10 0300;;;;N;;;1F1A;;1F1A -1F13;GREEK SMALL LETTER EPSILON WITH DASIA AND VARIA;Ll;0;L;1F11 0300;;;;N;;;1F1B;;1F1B -1F14;GREEK SMALL LETTER EPSILON WITH PSILI AND OXIA;Ll;0;L;1F10 0301;;;;N;;;1F1C;;1F1C -1F15;GREEK SMALL LETTER EPSILON WITH DASIA AND OXIA;Ll;0;L;1F11 0301;;;;N;;;1F1D;;1F1D -1F18;GREEK CAPITAL LETTER EPSILON WITH PSILI;Lu;0;L;0395 0313;;;;N;;;;1F10; -1F19;GREEK CAPITAL LETTER EPSILON WITH DASIA;Lu;0;L;0395 0314;;;;N;;;;1F11; -1F1A;GREEK CAPITAL LETTER EPSILON WITH PSILI AND VARIA;Lu;0;L;1F18 0300;;;;N;;;;1F12; -1F1B;GREEK CAPITAL LETTER EPSILON WITH DASIA AND VARIA;Lu;0;L;1F19 0300;;;;N;;;;1F13; -1F1C;GREEK CAPITAL LETTER EPSILON WITH PSILI AND OXIA;Lu;0;L;1F18 0301;;;;N;;;;1F14; -1F1D;GREEK CAPITAL LETTER EPSILON WITH DASIA AND OXIA;Lu;0;L;1F19 0301;;;;N;;;;1F15; -1F20;GREEK SMALL LETTER ETA WITH PSILI;Ll;0;L;03B7 0313;;;;N;;;1F28;;1F28 -1F21;GREEK SMALL LETTER ETA WITH DASIA;Ll;0;L;03B7 0314;;;;N;;;1F29;;1F29 -1F22;GREEK SMALL LETTER ETA WITH PSILI AND VARIA;Ll;0;L;1F20 0300;;;;N;;;1F2A;;1F2A -1F23;GREEK SMALL LETTER ETA WITH DASIA AND VARIA;Ll;0;L;1F21 0300;;;;N;;;1F2B;;1F2B -1F24;GREEK SMALL LETTER ETA WITH PSILI AND OXIA;Ll;0;L;1F20 0301;;;;N;;;1F2C;;1F2C -1F25;GREEK SMALL LETTER ETA WITH DASIA AND OXIA;Ll;0;L;1F21 0301;;;;N;;;1F2D;;1F2D -1F26;GREEK SMALL LETTER ETA WITH PSILI AND PERISPOMENI;Ll;0;L;1F20 0342;;;;N;;;1F2E;;1F2E -1F27;GREEK SMALL LETTER ETA WITH DASIA AND PERISPOMENI;Ll;0;L;1F21 0342;;;;N;;;1F2F;;1F2F -1F28;GREEK CAPITAL LETTER ETA WITH PSILI;Lu;0;L;0397 0313;;;;N;;;;1F20; -1F29;GREEK CAPITAL LETTER ETA WITH DASIA;Lu;0;L;0397 0314;;;;N;;;;1F21; -1F2A;GREEK CAPITAL LETTER ETA WITH PSILI AND VARIA;Lu;0;L;1F28 0300;;;;N;;;;1F22; -1F2B;GREEK CAPITAL LETTER ETA WITH DASIA AND VARIA;Lu;0;L;1F29 0300;;;;N;;;;1F23; -1F2C;GREEK CAPITAL LETTER ETA WITH PSILI AND OXIA;Lu;0;L;1F28 0301;;;;N;;;;1F24; -1F2D;GREEK CAPITAL LETTER ETA WITH DASIA AND OXIA;Lu;0;L;1F29 0301;;;;N;;;;1F25; -1F2E;GREEK CAPITAL LETTER ETA WITH PSILI AND PERISPOMENI;Lu;0;L;1F28 0342;;;;N;;;;1F26; -1F2F;GREEK CAPITAL LETTER ETA WITH DASIA AND PERISPOMENI;Lu;0;L;1F29 0342;;;;N;;;;1F27; -1F30;GREEK SMALL LETTER IOTA WITH PSILI;Ll;0;L;03B9 0313;;;;N;;;1F38;;1F38 -1F31;GREEK SMALL LETTER IOTA WITH DASIA;Ll;0;L;03B9 0314;;;;N;;;1F39;;1F39 -1F32;GREEK SMALL LETTER IOTA WITH PSILI AND VARIA;Ll;0;L;1F30 0300;;;;N;;;1F3A;;1F3A -1F33;GREEK SMALL LETTER IOTA WITH DASIA AND VARIA;Ll;0;L;1F31 0300;;;;N;;;1F3B;;1F3B -1F34;GREEK SMALL LETTER IOTA WITH PSILI AND OXIA;Ll;0;L;1F30 0301;;;;N;;;1F3C;;1F3C -1F35;GREEK SMALL LETTER IOTA WITH DASIA AND OXIA;Ll;0;L;1F31 0301;;;;N;;;1F3D;;1F3D -1F36;GREEK SMALL LETTER IOTA WITH PSILI AND PERISPOMENI;Ll;0;L;1F30 0342;;;;N;;;1F3E;;1F3E -1F37;GREEK SMALL LETTER IOTA WITH DASIA AND PERISPOMENI;Ll;0;L;1F31 0342;;;;N;;;1F3F;;1F3F -1F38;GREEK CAPITAL LETTER IOTA WITH PSILI;Lu;0;L;0399 0313;;;;N;;;;1F30; -1F39;GREEK CAPITAL LETTER IOTA WITH DASIA;Lu;0;L;0399 0314;;;;N;;;;1F31; -1F3A;GREEK CAPITAL LETTER IOTA WITH PSILI AND VARIA;Lu;0;L;1F38 0300;;;;N;;;;1F32; -1F3B;GREEK CAPITAL LETTER IOTA WITH DASIA AND VARIA;Lu;0;L;1F39 0300;;;;N;;;;1F33; -1F3C;GREEK CAPITAL LETTER IOTA WITH PSILI AND OXIA;Lu;0;L;1F38 0301;;;;N;;;;1F34; -1F3D;GREEK CAPITAL LETTER IOTA WITH DASIA AND OXIA;Lu;0;L;1F39 0301;;;;N;;;;1F35; -1F3E;GREEK CAPITAL LETTER IOTA WITH PSILI AND PERISPOMENI;Lu;0;L;1F38 0342;;;;N;;;;1F36; -1F3F;GREEK CAPITAL LETTER IOTA WITH DASIA AND PERISPOMENI;Lu;0;L;1F39 0342;;;;N;;;;1F37; -1F40;GREEK SMALL LETTER OMICRON WITH PSILI;Ll;0;L;03BF 0313;;;;N;;;1F48;;1F48 -1F41;GREEK SMALL LETTER OMICRON WITH DASIA;Ll;0;L;03BF 0314;;;;N;;;1F49;;1F49 -1F42;GREEK SMALL LETTER OMICRON WITH PSILI AND VARIA;Ll;0;L;1F40 0300;;;;N;;;1F4A;;1F4A -1F43;GREEK SMALL LETTER OMICRON WITH DASIA AND VARIA;Ll;0;L;1F41 0300;;;;N;;;1F4B;;1F4B -1F44;GREEK SMALL LETTER OMICRON WITH PSILI AND OXIA;Ll;0;L;1F40 0301;;;;N;;;1F4C;;1F4C -1F45;GREEK SMALL LETTER OMICRON WITH DASIA AND OXIA;Ll;0;L;1F41 0301;;;;N;;;1F4D;;1F4D -1F48;GREEK CAPITAL LETTER OMICRON WITH PSILI;Lu;0;L;039F 0313;;;;N;;;;1F40; -1F49;GREEK CAPITAL LETTER OMICRON WITH DASIA;Lu;0;L;039F 0314;;;;N;;;;1F41; -1F4A;GREEK CAPITAL LETTER OMICRON WITH PSILI AND VARIA;Lu;0;L;1F48 0300;;;;N;;;;1F42; -1F4B;GREEK CAPITAL LETTER OMICRON WITH DASIA AND VARIA;Lu;0;L;1F49 0300;;;;N;;;;1F43; -1F4C;GREEK CAPITAL LETTER OMICRON WITH PSILI AND OXIA;Lu;0;L;1F48 0301;;;;N;;;;1F44; -1F4D;GREEK CAPITAL LETTER OMICRON WITH DASIA AND OXIA;Lu;0;L;1F49 0301;;;;N;;;;1F45; -1F50;GREEK SMALL LETTER UPSILON WITH PSILI;Ll;0;L;03C5 0313;;;;N;;;;; -1F51;GREEK SMALL LETTER UPSILON WITH DASIA;Ll;0;L;03C5 0314;;;;N;;;1F59;;1F59 -1F52;GREEK SMALL LETTER UPSILON WITH PSILI AND VARIA;Ll;0;L;1F50 0300;;;;N;;;;; -1F53;GREEK SMALL LETTER UPSILON WITH DASIA AND VARIA;Ll;0;L;1F51 0300;;;;N;;;1F5B;;1F5B -1F54;GREEK SMALL LETTER UPSILON WITH PSILI AND OXIA;Ll;0;L;1F50 0301;;;;N;;;;; -1F55;GREEK SMALL LETTER UPSILON WITH DASIA AND OXIA;Ll;0;L;1F51 0301;;;;N;;;1F5D;;1F5D -1F56;GREEK SMALL LETTER UPSILON WITH PSILI AND PERISPOMENI;Ll;0;L;1F50 0342;;;;N;;;;; -1F57;GREEK SMALL LETTER UPSILON WITH DASIA AND PERISPOMENI;Ll;0;L;1F51 0342;;;;N;;;1F5F;;1F5F -1F59;GREEK CAPITAL LETTER UPSILON WITH DASIA;Lu;0;L;03A5 0314;;;;N;;;;1F51; -1F5B;GREEK CAPITAL LETTER UPSILON WITH DASIA AND VARIA;Lu;0;L;1F59 0300;;;;N;;;;1F53; -1F5D;GREEK CAPITAL LETTER UPSILON WITH DASIA AND OXIA;Lu;0;L;1F59 0301;;;;N;;;;1F55; -1F5F;GREEK CAPITAL LETTER UPSILON WITH DASIA AND PERISPOMENI;Lu;0;L;1F59 0342;;;;N;;;;1F57; -1F60;GREEK SMALL LETTER OMEGA WITH PSILI;Ll;0;L;03C9 0313;;;;N;;;1F68;;1F68 -1F61;GREEK SMALL LETTER OMEGA WITH DASIA;Ll;0;L;03C9 0314;;;;N;;;1F69;;1F69 -1F62;GREEK SMALL LETTER OMEGA WITH PSILI AND VARIA;Ll;0;L;1F60 0300;;;;N;;;1F6A;;1F6A -1F63;GREEK SMALL LETTER OMEGA WITH DASIA AND VARIA;Ll;0;L;1F61 0300;;;;N;;;1F6B;;1F6B -1F64;GREEK SMALL LETTER OMEGA WITH PSILI AND OXIA;Ll;0;L;1F60 0301;;;;N;;;1F6C;;1F6C -1F65;GREEK SMALL LETTER OMEGA WITH DASIA AND OXIA;Ll;0;L;1F61 0301;;;;N;;;1F6D;;1F6D -1F66;GREEK SMALL LETTER OMEGA WITH PSILI AND PERISPOMENI;Ll;0;L;1F60 0342;;;;N;;;1F6E;;1F6E -1F67;GREEK SMALL LETTER OMEGA WITH DASIA AND PERISPOMENI;Ll;0;L;1F61 0342;;;;N;;;1F6F;;1F6F -1F68;GREEK CAPITAL LETTER OMEGA WITH PSILI;Lu;0;L;03A9 0313;;;;N;;;;1F60; -1F69;GREEK CAPITAL LETTER OMEGA WITH DASIA;Lu;0;L;03A9 0314;;;;N;;;;1F61; -1F6A;GREEK CAPITAL LETTER OMEGA WITH PSILI AND VARIA;Lu;0;L;1F68 0300;;;;N;;;;1F62; -1F6B;GREEK CAPITAL LETTER OMEGA WITH DASIA AND VARIA;Lu;0;L;1F69 0300;;;;N;;;;1F63; -1F6C;GREEK CAPITAL LETTER OMEGA WITH PSILI AND OXIA;Lu;0;L;1F68 0301;;;;N;;;;1F64; -1F6D;GREEK CAPITAL LETTER OMEGA WITH DASIA AND OXIA;Lu;0;L;1F69 0301;;;;N;;;;1F65; -1F6E;GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI;Lu;0;L;1F68 0342;;;;N;;;;1F66; -1F6F;GREEK CAPITAL LETTER OMEGA WITH DASIA AND PERISPOMENI;Lu;0;L;1F69 0342;;;;N;;;;1F67; -1F70;GREEK SMALL LETTER ALPHA WITH VARIA;Ll;0;L;03B1 0300;;;;N;;;1FBA;;1FBA -1F71;GREEK SMALL LETTER ALPHA WITH OXIA;Ll;0;L;03AC;;;;N;;;1FBB;;1FBB -1F72;GREEK SMALL LETTER EPSILON WITH VARIA;Ll;0;L;03B5 0300;;;;N;;;1FC8;;1FC8 -1F73;GREEK SMALL LETTER EPSILON WITH OXIA;Ll;0;L;03AD;;;;N;;;1FC9;;1FC9 -1F74;GREEK SMALL LETTER ETA WITH VARIA;Ll;0;L;03B7 0300;;;;N;;;1FCA;;1FCA -1F75;GREEK SMALL LETTER ETA WITH OXIA;Ll;0;L;03AE;;;;N;;;1FCB;;1FCB -1F76;GREEK SMALL LETTER IOTA WITH VARIA;Ll;0;L;03B9 0300;;;;N;;;1FDA;;1FDA -1F77;GREEK SMALL LETTER IOTA WITH OXIA;Ll;0;L;03AF;;;;N;;;1FDB;;1FDB -1F78;GREEK SMALL LETTER OMICRON WITH VARIA;Ll;0;L;03BF 0300;;;;N;;;1FF8;;1FF8 -1F79;GREEK SMALL LETTER OMICRON WITH OXIA;Ll;0;L;03CC;;;;N;;;1FF9;;1FF9 -1F7A;GREEK SMALL LETTER UPSILON WITH VARIA;Ll;0;L;03C5 0300;;;;N;;;1FEA;;1FEA -1F7B;GREEK SMALL LETTER UPSILON WITH OXIA;Ll;0;L;03CD;;;;N;;;1FEB;;1FEB -1F7C;GREEK SMALL LETTER OMEGA WITH VARIA;Ll;0;L;03C9 0300;;;;N;;;1FFA;;1FFA -1F7D;GREEK SMALL LETTER OMEGA WITH OXIA;Ll;0;L;03CE;;;;N;;;1FFB;;1FFB -1F80;GREEK SMALL LETTER ALPHA WITH PSILI AND YPOGEGRAMMENI;Ll;0;L;1F00 0345;;;;N;;;1F88;;1F88 -1F81;GREEK SMALL LETTER ALPHA WITH DASIA AND YPOGEGRAMMENI;Ll;0;L;1F01 0345;;;;N;;;1F89;;1F89 -1F82;GREEK SMALL LETTER ALPHA WITH PSILI AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F02 0345;;;;N;;;1F8A;;1F8A -1F83;GREEK SMALL LETTER ALPHA WITH DASIA AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F03 0345;;;;N;;;1F8B;;1F8B -1F84;GREEK SMALL LETTER ALPHA WITH PSILI AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F04 0345;;;;N;;;1F8C;;1F8C -1F85;GREEK SMALL LETTER ALPHA WITH DASIA AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F05 0345;;;;N;;;1F8D;;1F8D -1F86;GREEK SMALL LETTER ALPHA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F06 0345;;;;N;;;1F8E;;1F8E -1F87;GREEK SMALL LETTER ALPHA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F07 0345;;;;N;;;1F8F;;1F8F -1F88;GREEK CAPITAL LETTER ALPHA WITH PSILI AND PROSGEGRAMMENI;Lt;0;L;1F08 0345;;;;N;;;;1F80; -1F89;GREEK CAPITAL LETTER ALPHA WITH DASIA AND PROSGEGRAMMENI;Lt;0;L;1F09 0345;;;;N;;;;1F81; -1F8A;GREEK CAPITAL LETTER ALPHA WITH PSILI AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F0A 0345;;;;N;;;;1F82; -1F8B;GREEK CAPITAL LETTER ALPHA WITH DASIA AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F0B 0345;;;;N;;;;1F83; -1F8C;GREEK CAPITAL LETTER ALPHA WITH PSILI AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F0C 0345;;;;N;;;;1F84; -1F8D;GREEK CAPITAL LETTER ALPHA WITH DASIA AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F0D 0345;;;;N;;;;1F85; -1F8E;GREEK CAPITAL LETTER ALPHA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F0E 0345;;;;N;;;;1F86; -1F8F;GREEK CAPITAL LETTER ALPHA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F0F 0345;;;;N;;;;1F87; -1F90;GREEK SMALL LETTER ETA WITH PSILI AND YPOGEGRAMMENI;Ll;0;L;1F20 0345;;;;N;;;1F98;;1F98 -1F91;GREEK SMALL LETTER ETA WITH DASIA AND YPOGEGRAMMENI;Ll;0;L;1F21 0345;;;;N;;;1F99;;1F99 -1F92;GREEK SMALL LETTER ETA WITH PSILI AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F22 0345;;;;N;;;1F9A;;1F9A -1F93;GREEK SMALL LETTER ETA WITH DASIA AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F23 0345;;;;N;;;1F9B;;1F9B -1F94;GREEK SMALL LETTER ETA WITH PSILI AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F24 0345;;;;N;;;1F9C;;1F9C -1F95;GREEK SMALL LETTER ETA WITH DASIA AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F25 0345;;;;N;;;1F9D;;1F9D -1F96;GREEK SMALL LETTER ETA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F26 0345;;;;N;;;1F9E;;1F9E -1F97;GREEK SMALL LETTER ETA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F27 0345;;;;N;;;1F9F;;1F9F -1F98;GREEK CAPITAL LETTER ETA WITH PSILI AND PROSGEGRAMMENI;Lt;0;L;1F28 0345;;;;N;;;;1F90; -1F99;GREEK CAPITAL LETTER ETA WITH DASIA AND PROSGEGRAMMENI;Lt;0;L;1F29 0345;;;;N;;;;1F91; -1F9A;GREEK CAPITAL LETTER ETA WITH PSILI AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F2A 0345;;;;N;;;;1F92; -1F9B;GREEK CAPITAL LETTER ETA WITH DASIA AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F2B 0345;;;;N;;;;1F93; -1F9C;GREEK CAPITAL LETTER ETA WITH PSILI AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F2C 0345;;;;N;;;;1F94; -1F9D;GREEK CAPITAL LETTER ETA WITH DASIA AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F2D 0345;;;;N;;;;1F95; -1F9E;GREEK CAPITAL LETTER ETA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F2E 0345;;;;N;;;;1F96; -1F9F;GREEK CAPITAL LETTER ETA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F2F 0345;;;;N;;;;1F97; -1FA0;GREEK SMALL LETTER OMEGA WITH PSILI AND YPOGEGRAMMENI;Ll;0;L;1F60 0345;;;;N;;;1FA8;;1FA8 -1FA1;GREEK SMALL LETTER OMEGA WITH DASIA AND YPOGEGRAMMENI;Ll;0;L;1F61 0345;;;;N;;;1FA9;;1FA9 -1FA2;GREEK SMALL LETTER OMEGA WITH PSILI AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F62 0345;;;;N;;;1FAA;;1FAA -1FA3;GREEK SMALL LETTER OMEGA WITH DASIA AND VARIA AND YPOGEGRAMMENI;Ll;0;L;1F63 0345;;;;N;;;1FAB;;1FAB -1FA4;GREEK SMALL LETTER OMEGA WITH PSILI AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F64 0345;;;;N;;;1FAC;;1FAC -1FA5;GREEK SMALL LETTER OMEGA WITH DASIA AND OXIA AND YPOGEGRAMMENI;Ll;0;L;1F65 0345;;;;N;;;1FAD;;1FAD -1FA6;GREEK SMALL LETTER OMEGA WITH PSILI AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F66 0345;;;;N;;;1FAE;;1FAE -1FA7;GREEK SMALL LETTER OMEGA WITH DASIA AND PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1F67 0345;;;;N;;;1FAF;;1FAF -1FA8;GREEK CAPITAL LETTER OMEGA WITH PSILI AND PROSGEGRAMMENI;Lt;0;L;1F68 0345;;;;N;;;;1FA0; -1FA9;GREEK CAPITAL LETTER OMEGA WITH DASIA AND PROSGEGRAMMENI;Lt;0;L;1F69 0345;;;;N;;;;1FA1; -1FAA;GREEK CAPITAL LETTER OMEGA WITH PSILI AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F6A 0345;;;;N;;;;1FA2; -1FAB;GREEK CAPITAL LETTER OMEGA WITH DASIA AND VARIA AND PROSGEGRAMMENI;Lt;0;L;1F6B 0345;;;;N;;;;1FA3; -1FAC;GREEK CAPITAL LETTER OMEGA WITH PSILI AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F6C 0345;;;;N;;;;1FA4; -1FAD;GREEK CAPITAL LETTER OMEGA WITH DASIA AND OXIA AND PROSGEGRAMMENI;Lt;0;L;1F6D 0345;;;;N;;;;1FA5; -1FAE;GREEK CAPITAL LETTER OMEGA WITH PSILI AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F6E 0345;;;;N;;;;1FA6; -1FAF;GREEK CAPITAL LETTER OMEGA WITH DASIA AND PERISPOMENI AND PROSGEGRAMMENI;Lt;0;L;1F6F 0345;;;;N;;;;1FA7; -1FB0;GREEK SMALL LETTER ALPHA WITH VRACHY;Ll;0;L;03B1 0306;;;;N;;;1FB8;;1FB8 -1FB1;GREEK SMALL LETTER ALPHA WITH MACRON;Ll;0;L;03B1 0304;;;;N;;;1FB9;;1FB9 -1FB2;GREEK SMALL LETTER ALPHA WITH VARIA AND YPOGEGRAMMENI;Ll;0;L;1F70 0345;;;;N;;;;; -1FB3;GREEK SMALL LETTER ALPHA WITH YPOGEGRAMMENI;Ll;0;L;03B1 0345;;;;N;;;1FBC;;1FBC -1FB4;GREEK SMALL LETTER ALPHA WITH OXIA AND YPOGEGRAMMENI;Ll;0;L;03AC 0345;;;;N;;;;; -1FB6;GREEK SMALL LETTER ALPHA WITH PERISPOMENI;Ll;0;L;03B1 0342;;;;N;;;;; -1FB7;GREEK SMALL LETTER ALPHA WITH PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1FB6 0345;;;;N;;;;; -1FB8;GREEK CAPITAL LETTER ALPHA WITH VRACHY;Lu;0;L;0391 0306;;;;N;;;;1FB0; -1FB9;GREEK CAPITAL LETTER ALPHA WITH MACRON;Lu;0;L;0391 0304;;;;N;;;;1FB1; -1FBA;GREEK CAPITAL LETTER ALPHA WITH VARIA;Lu;0;L;0391 0300;;;;N;;;;1F70; -1FBB;GREEK CAPITAL LETTER ALPHA WITH OXIA;Lu;0;L;0386;;;;N;;;;1F71; -1FBC;GREEK CAPITAL LETTER ALPHA WITH PROSGEGRAMMENI;Lt;0;L;0391 0345;;;;N;;;;1FB3; -1FBD;GREEK KORONIS;Sk;0;ON; 0020 0313;;;;N;;;;; -1FBE;GREEK PROSGEGRAMMENI;Ll;0;L;03B9;;;;N;;;0399;;0399 -1FBF;GREEK PSILI;Sk;0;ON; 0020 0313;;;;N;;;;; -1FC0;GREEK PERISPOMENI;Sk;0;ON; 0020 0342;;;;N;;;;; -1FC1;GREEK DIALYTIKA AND PERISPOMENI;Sk;0;ON;00A8 0342;;;;N;;;;; -1FC2;GREEK SMALL LETTER ETA WITH VARIA AND YPOGEGRAMMENI;Ll;0;L;1F74 0345;;;;N;;;;; -1FC3;GREEK SMALL LETTER ETA WITH YPOGEGRAMMENI;Ll;0;L;03B7 0345;;;;N;;;1FCC;;1FCC -1FC4;GREEK SMALL LETTER ETA WITH OXIA AND YPOGEGRAMMENI;Ll;0;L;03AE 0345;;;;N;;;;; -1FC6;GREEK SMALL LETTER ETA WITH PERISPOMENI;Ll;0;L;03B7 0342;;;;N;;;;; -1FC7;GREEK SMALL LETTER ETA WITH PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1FC6 0345;;;;N;;;;; -1FC8;GREEK CAPITAL LETTER EPSILON WITH VARIA;Lu;0;L;0395 0300;;;;N;;;;1F72; -1FC9;GREEK CAPITAL LETTER EPSILON WITH OXIA;Lu;0;L;0388;;;;N;;;;1F73; -1FCA;GREEK CAPITAL LETTER ETA WITH VARIA;Lu;0;L;0397 0300;;;;N;;;;1F74; -1FCB;GREEK CAPITAL LETTER ETA WITH OXIA;Lu;0;L;0389;;;;N;;;;1F75; -1FCC;GREEK CAPITAL LETTER ETA WITH PROSGEGRAMMENI;Lt;0;L;0397 0345;;;;N;;;;1FC3; -1FCD;GREEK PSILI AND VARIA;Sk;0;ON;1FBF 0300;;;;N;;;;; -1FCE;GREEK PSILI AND OXIA;Sk;0;ON;1FBF 0301;;;;N;;;;; -1FCF;GREEK PSILI AND PERISPOMENI;Sk;0;ON;1FBF 0342;;;;N;;;;; -1FD0;GREEK SMALL LETTER IOTA WITH VRACHY;Ll;0;L;03B9 0306;;;;N;;;1FD8;;1FD8 -1FD1;GREEK SMALL LETTER IOTA WITH MACRON;Ll;0;L;03B9 0304;;;;N;;;1FD9;;1FD9 -1FD2;GREEK SMALL LETTER IOTA WITH DIALYTIKA AND VARIA;Ll;0;L;03CA 0300;;;;N;;;;; -1FD3;GREEK SMALL LETTER IOTA WITH DIALYTIKA AND OXIA;Ll;0;L;0390;;;;N;;;;; -1FD6;GREEK SMALL LETTER IOTA WITH PERISPOMENI;Ll;0;L;03B9 0342;;;;N;;;;; -1FD7;GREEK SMALL LETTER IOTA WITH DIALYTIKA AND PERISPOMENI;Ll;0;L;03CA 0342;;;;N;;;;; -1FD8;GREEK CAPITAL LETTER IOTA WITH VRACHY;Lu;0;L;0399 0306;;;;N;;;;1FD0; -1FD9;GREEK CAPITAL LETTER IOTA WITH MACRON;Lu;0;L;0399 0304;;;;N;;;;1FD1; -1FDA;GREEK CAPITAL LETTER IOTA WITH VARIA;Lu;0;L;0399 0300;;;;N;;;;1F76; -1FDB;GREEK CAPITAL LETTER IOTA WITH OXIA;Lu;0;L;038A;;;;N;;;;1F77; -1FDD;GREEK DASIA AND VARIA;Sk;0;ON;1FFE 0300;;;;N;;;;; -1FDE;GREEK DASIA AND OXIA;Sk;0;ON;1FFE 0301;;;;N;;;;; -1FDF;GREEK DASIA AND PERISPOMENI;Sk;0;ON;1FFE 0342;;;;N;;;;; -1FE0;GREEK SMALL LETTER UPSILON WITH VRACHY;Ll;0;L;03C5 0306;;;;N;;;1FE8;;1FE8 -1FE1;GREEK SMALL LETTER UPSILON WITH MACRON;Ll;0;L;03C5 0304;;;;N;;;1FE9;;1FE9 -1FE2;GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND VARIA;Ll;0;L;03CB 0300;;;;N;;;;; -1FE3;GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND OXIA;Ll;0;L;03B0;;;;N;;;;; -1FE4;GREEK SMALL LETTER RHO WITH PSILI;Ll;0;L;03C1 0313;;;;N;;;;; -1FE5;GREEK SMALL LETTER RHO WITH DASIA;Ll;0;L;03C1 0314;;;;N;;;1FEC;;1FEC -1FE6;GREEK SMALL LETTER UPSILON WITH PERISPOMENI;Ll;0;L;03C5 0342;;;;N;;;;; -1FE7;GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND PERISPOMENI;Ll;0;L;03CB 0342;;;;N;;;;; -1FE8;GREEK CAPITAL LETTER UPSILON WITH VRACHY;Lu;0;L;03A5 0306;;;;N;;;;1FE0; -1FE9;GREEK CAPITAL LETTER UPSILON WITH MACRON;Lu;0;L;03A5 0304;;;;N;;;;1FE1; -1FEA;GREEK CAPITAL LETTER UPSILON WITH VARIA;Lu;0;L;03A5 0300;;;;N;;;;1F7A; -1FEB;GREEK CAPITAL LETTER UPSILON WITH OXIA;Lu;0;L;038E;;;;N;;;;1F7B; -1FEC;GREEK CAPITAL LETTER RHO WITH DASIA;Lu;0;L;03A1 0314;;;;N;;;;1FE5; -1FED;GREEK DIALYTIKA AND VARIA;Sk;0;ON;00A8 0300;;;;N;;;;; -1FEE;GREEK DIALYTIKA AND OXIA;Sk;0;ON;0385;;;;N;;;;; -1FEF;GREEK VARIA;Sk;0;ON;0060;;;;N;;;;; -1FF2;GREEK SMALL LETTER OMEGA WITH VARIA AND YPOGEGRAMMENI;Ll;0;L;1F7C 0345;;;;N;;;;; -1FF3;GREEK SMALL LETTER OMEGA WITH YPOGEGRAMMENI;Ll;0;L;03C9 0345;;;;N;;;1FFC;;1FFC -1FF4;GREEK SMALL LETTER OMEGA WITH OXIA AND YPOGEGRAMMENI;Ll;0;L;03CE 0345;;;;N;;;;; -1FF6;GREEK SMALL LETTER OMEGA WITH PERISPOMENI;Ll;0;L;03C9 0342;;;;N;;;;; -1FF7;GREEK SMALL LETTER OMEGA WITH PERISPOMENI AND YPOGEGRAMMENI;Ll;0;L;1FF6 0345;;;;N;;;;; -1FF8;GREEK CAPITAL LETTER OMICRON WITH VARIA;Lu;0;L;039F 0300;;;;N;;;;1F78; -1FF9;GREEK CAPITAL LETTER OMICRON WITH OXIA;Lu;0;L;038C;;;;N;;;;1F79; -1FFA;GREEK CAPITAL LETTER OMEGA WITH VARIA;Lu;0;L;03A9 0300;;;;N;;;;1F7C; -1FFB;GREEK CAPITAL LETTER OMEGA WITH OXIA;Lu;0;L;038F;;;;N;;;;1F7D; -1FFC;GREEK CAPITAL LETTER OMEGA WITH PROSGEGRAMMENI;Lt;0;L;03A9 0345;;;;N;;;;1FF3; -1FFD;GREEK OXIA;Sk;0;ON;00B4;;;;N;;;;; -1FFE;GREEK DASIA;Sk;0;ON; 0020 0314;;;;N;;;;; -2000;EN QUAD;Zs;0;WS;2002;;;;N;;;;; -2001;EM QUAD;Zs;0;WS;2003;;;;N;;;;; -2002;EN SPACE;Zs;0;WS; 0020;;;;N;;;;; -2003;EM SPACE;Zs;0;WS; 0020;;;;N;;;;; -2004;THREE-PER-EM SPACE;Zs;0;WS; 0020;;;;N;;;;; -2005;FOUR-PER-EM SPACE;Zs;0;WS; 0020;;;;N;;;;; -2006;SIX-PER-EM SPACE;Zs;0;WS; 0020;;;;N;;;;; -2007;FIGURE SPACE;Zs;0;WS; 0020;;;;N;;;;; -2008;PUNCTUATION SPACE;Zs;0;WS; 0020;;;;N;;;;; -2009;THIN SPACE;Zs;0;WS; 0020;;;;N;;;;; -200A;HAIR SPACE;Zs;0;WS; 0020;;;;N;;;;; -200B;ZERO WIDTH SPACE;Cf;0;BN;;;;;N;;;;; -200C;ZERO WIDTH NON-JOINER;Cf;0;BN;;;;;N;;;;; -200D;ZERO WIDTH JOINER;Cf;0;BN;;;;;N;;;;; -200E;LEFT-TO-RIGHT MARK;Cf;0;L;;;;;N;;;;; -200F;RIGHT-TO-LEFT MARK;Cf;0;R;;;;;N;;;;; -2010;HYPHEN;Pd;0;ON;;;;;N;;;;; -2011;NON-BREAKING HYPHEN;Pd;0;ON; 2010;;;;N;;;;; -2012;FIGURE DASH;Pd;0;ON;;;;;N;;;;; -2013;EN DASH;Pd;0;ON;;;;;N;;;;; -2014;EM DASH;Pd;0;ON;;;;;N;;;;; -2015;HORIZONTAL BAR;Pd;0;ON;;;;;N;QUOTATION DASH;;;; -2016;DOUBLE VERTICAL LINE;Po;0;ON;;;;;N;DOUBLE VERTICAL BAR;;;; -2017;DOUBLE LOW LINE;Po;0;ON; 0020 0333;;;;N;SPACING DOUBLE UNDERSCORE;;;; -2018;LEFT SINGLE QUOTATION MARK;Pi;0;ON;;;;;N;SINGLE TURNED COMMA QUOTATION MARK;;;; -2019;RIGHT SINGLE QUOTATION MARK;Pf;0;ON;;;;;N;SINGLE COMMA QUOTATION MARK;;;; -201A;SINGLE LOW-9 QUOTATION MARK;Ps;0;ON;;;;;N;LOW SINGLE COMMA QUOTATION MARK;;;; -201B;SINGLE HIGH-REVERSED-9 QUOTATION MARK;Pi;0;ON;;;;;N;SINGLE REVERSED COMMA QUOTATION MARK;;;; -201C;LEFT DOUBLE QUOTATION MARK;Pi;0;ON;;;;;N;DOUBLE TURNED COMMA QUOTATION MARK;;;; -201D;RIGHT DOUBLE QUOTATION MARK;Pf;0;ON;;;;;N;DOUBLE COMMA QUOTATION MARK;;;; -201E;DOUBLE LOW-9 QUOTATION MARK;Ps;0;ON;;;;;N;LOW DOUBLE COMMA QUOTATION MARK;;;; -201F;DOUBLE HIGH-REVERSED-9 QUOTATION MARK;Pi;0;ON;;;;;N;DOUBLE REVERSED COMMA QUOTATION MARK;;;; -2020;DAGGER;Po;0;ON;;;;;N;;;;; -2021;DOUBLE DAGGER;Po;0;ON;;;;;N;;;;; -2022;BULLET;Po;0;ON;;;;;N;;;;; -2023;TRIANGULAR BULLET;Po;0;ON;;;;;N;;;;; -2024;ONE DOT LEADER;Po;0;ON; 002E;;;;N;;;;; -2025;TWO DOT LEADER;Po;0;ON; 002E 002E;;;;N;;;;; -2026;HORIZONTAL ELLIPSIS;Po;0;ON; 002E 002E 002E;;;;N;;;;; -2027;HYPHENATION POINT;Po;0;ON;;;;;N;;;;; -2028;LINE SEPARATOR;Zl;0;WS;;;;;N;;;;; -2029;PARAGRAPH SEPARATOR;Zp;0;B;;;;;N;;;;; -202A;LEFT-TO-RIGHT EMBEDDING;Cf;0;LRE;;;;;N;;;;; -202B;RIGHT-TO-LEFT EMBEDDING;Cf;0;RLE;;;;;N;;;;; -202C;POP DIRECTIONAL FORMATTING;Cf;0;PDF;;;;;N;;;;; -202D;LEFT-TO-RIGHT OVERRIDE;Cf;0;LRO;;;;;N;;;;; -202E;RIGHT-TO-LEFT OVERRIDE;Cf;0;RLO;;;;;N;;;;; -202F;NARROW NO-BREAK SPACE;Zs;0;CS; 0020;;;;N;;;;; -2030;PER MILLE SIGN;Po;0;ET;;;;;N;;;;; -2031;PER TEN THOUSAND SIGN;Po;0;ET;;;;;N;;;;; -2032;PRIME;Po;0;ET;;;;;N;;;;; -2033;DOUBLE PRIME;Po;0;ET; 2032 2032;;;;N;;;;; -2034;TRIPLE PRIME;Po;0;ET; 2032 2032 2032;;;;N;;;;; -2035;REVERSED PRIME;Po;0;ON;;;;;N;;;;; -2036;REVERSED DOUBLE PRIME;Po;0;ON; 2035 2035;;;;N;;;;; -2037;REVERSED TRIPLE PRIME;Po;0;ON; 2035 2035 2035;;;;N;;;;; -2038;CARET;Po;0;ON;;;;;N;;;;; -2039;SINGLE LEFT-POINTING ANGLE QUOTATION MARK;Pi;0;ON;;;;;Y;LEFT POINTING SINGLE GUILLEMET;;;; -203A;SINGLE RIGHT-POINTING ANGLE QUOTATION MARK;Pf;0;ON;;;;;Y;RIGHT POINTING SINGLE GUILLEMET;;;; -203B;REFERENCE MARK;Po;0;ON;;;;;N;;;;; -203C;DOUBLE EXCLAMATION MARK;Po;0;ON; 0021 0021;;;;N;;;;; -203D;INTERROBANG;Po;0;ON;;;;;N;;;;; -203E;OVERLINE;Po;0;ON; 0020 0305;;;;N;SPACING OVERSCORE;;;; -203F;UNDERTIE;Pc;0;ON;;;;;N;;Enotikon;;; -2040;CHARACTER TIE;Pc;0;ON;;;;;N;;;;; -2041;CARET INSERTION POINT;Po;0;ON;;;;;N;;;;; -2042;ASTERISM;Po;0;ON;;;;;N;;;;; -2043;HYPHEN BULLET;Po;0;ON;;;;;N;;;;; -2044;FRACTION SLASH;Sm;0;CS;;;;;N;;;;; -2045;LEFT SQUARE BRACKET WITH QUILL;Ps;0;ON;;;;;Y;;;;; -2046;RIGHT SQUARE BRACKET WITH QUILL;Pe;0;ON;;;;;Y;;;;; -2047;DOUBLE QUESTION MARK;Po;0;ON; 003F 003F;;;;N;;;;; -2048;QUESTION EXCLAMATION MARK;Po;0;ON; 003F 0021;;;;N;;;;; -2049;EXCLAMATION QUESTION MARK;Po;0;ON; 0021 003F;;;;N;;;;; -204A;TIRONIAN SIGN ET;Po;0;ON;;;;;N;;;;; -204B;REVERSED PILCROW SIGN;Po;0;ON;;;;;N;;;;; -204C;BLACK LEFTWARDS BULLET;Po;0;ON;;;;;N;;;;; -204D;BLACK RIGHTWARDS BULLET;Po;0;ON;;;;;N;;;;; -204E;LOW ASTERISK;Po;0;ON;;;;;N;;;;; -204F;REVERSED SEMICOLON;Po;0;ON;;;;;N;;;;; -2050;CLOSE UP;Po;0;ON;;;;;N;;;;; -2051;TWO ASTERISKS ALIGNED VERTICALLY;Po;0;ON;;;;;N;;;;; -2052;COMMERCIAL MINUS SIGN;Sm;0;ON;;;;;N;;;;; -2053;SWUNG DASH;Po;0;ON;;;;;N;;;;; -2054;INVERTED UNDERTIE;Pc;0;ON;;;;;N;;;;; -2055;FLOWER PUNCTUATION MARK;Po;0;ON;;;;;N;;;;; -2056;THREE DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -2057;QUADRUPLE PRIME;Po;0;ON; 2032 2032 2032 2032;;;;N;;;;; -2058;FOUR DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -2059;FIVE DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -205A;TWO DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -205B;FOUR DOT MARK;Po;0;ON;;;;;N;;;;; -205C;DOTTED CROSS;Po;0;ON;;;;;N;;;;; -205D;TRICOLON;Po;0;ON;;;;;N;;;;; -205E;VERTICAL FOUR DOTS;Po;0;ON;;;;;N;;;;; -205F;MEDIUM MATHEMATICAL SPACE;Zs;0;WS; 0020;;;;N;;;;; -2060;WORD JOINER;Cf;0;BN;;;;;N;;;;; -2061;FUNCTION APPLICATION;Cf;0;BN;;;;;N;;;;; -2062;INVISIBLE TIMES;Cf;0;BN;;;;;N;;;;; -2063;INVISIBLE SEPARATOR;Cf;0;BN;;;;;N;;;;; -2064;INVISIBLE PLUS;Cf;0;BN;;;;;N;;;;; -206A;INHIBIT SYMMETRIC SWAPPING;Cf;0;BN;;;;;N;;;;; -206B;ACTIVATE SYMMETRIC SWAPPING;Cf;0;BN;;;;;N;;;;; -206C;INHIBIT ARABIC FORM SHAPING;Cf;0;BN;;;;;N;;;;; -206D;ACTIVATE ARABIC FORM SHAPING;Cf;0;BN;;;;;N;;;;; -206E;NATIONAL DIGIT SHAPES;Cf;0;BN;;;;;N;;;;; -206F;NOMINAL DIGIT SHAPES;Cf;0;BN;;;;;N;;;;; -2070;SUPERSCRIPT ZERO;No;0;EN; 0030;;0;0;N;SUPERSCRIPT DIGIT ZERO;;;; -2071;SUPERSCRIPT LATIN SMALL LETTER I;Ll;0;L; 0069;;;;N;;;;; -2074;SUPERSCRIPT FOUR;No;0;EN; 0034;;4;4;N;SUPERSCRIPT DIGIT FOUR;;;; -2075;SUPERSCRIPT FIVE;No;0;EN; 0035;;5;5;N;SUPERSCRIPT DIGIT FIVE;;;; -2076;SUPERSCRIPT SIX;No;0;EN; 0036;;6;6;N;SUPERSCRIPT DIGIT SIX;;;; -2077;SUPERSCRIPT SEVEN;No;0;EN; 0037;;7;7;N;SUPERSCRIPT DIGIT SEVEN;;;; -2078;SUPERSCRIPT EIGHT;No;0;EN; 0038;;8;8;N;SUPERSCRIPT DIGIT EIGHT;;;; -2079;SUPERSCRIPT NINE;No;0;EN; 0039;;9;9;N;SUPERSCRIPT DIGIT NINE;;;; -207A;SUPERSCRIPT PLUS SIGN;Sm;0;ES; 002B;;;;N;;;;; -207B;SUPERSCRIPT MINUS;Sm;0;ES; 2212;;;;N;SUPERSCRIPT HYPHEN-MINUS;;;; -207C;SUPERSCRIPT EQUALS SIGN;Sm;0;ON; 003D;;;;N;;;;; -207D;SUPERSCRIPT LEFT PARENTHESIS;Ps;0;ON; 0028;;;;Y;SUPERSCRIPT OPENING PARENTHESIS;;;; -207E;SUPERSCRIPT RIGHT PARENTHESIS;Pe;0;ON; 0029;;;;Y;SUPERSCRIPT CLOSING PARENTHESIS;;;; -207F;SUPERSCRIPT LATIN SMALL LETTER N;Ll;0;L; 006E;;;;N;;;;; -2080;SUBSCRIPT ZERO;No;0;EN; 0030;;0;0;N;SUBSCRIPT DIGIT ZERO;;;; -2081;SUBSCRIPT ONE;No;0;EN; 0031;;1;1;N;SUBSCRIPT DIGIT ONE;;;; -2082;SUBSCRIPT TWO;No;0;EN; 0032;;2;2;N;SUBSCRIPT DIGIT TWO;;;; -2083;SUBSCRIPT THREE;No;0;EN; 0033;;3;3;N;SUBSCRIPT DIGIT THREE;;;; -2084;SUBSCRIPT FOUR;No;0;EN; 0034;;4;4;N;SUBSCRIPT DIGIT FOUR;;;; -2085;SUBSCRIPT FIVE;No;0;EN; 0035;;5;5;N;SUBSCRIPT DIGIT FIVE;;;; -2086;SUBSCRIPT SIX;No;0;EN; 0036;;6;6;N;SUBSCRIPT DIGIT SIX;;;; -2087;SUBSCRIPT SEVEN;No;0;EN; 0037;;7;7;N;SUBSCRIPT DIGIT SEVEN;;;; -2088;SUBSCRIPT EIGHT;No;0;EN; 0038;;8;8;N;SUBSCRIPT DIGIT EIGHT;;;; -2089;SUBSCRIPT NINE;No;0;EN; 0039;;9;9;N;SUBSCRIPT DIGIT NINE;;;; -208A;SUBSCRIPT PLUS SIGN;Sm;0;ES; 002B;;;;N;;;;; -208B;SUBSCRIPT MINUS;Sm;0;ES; 2212;;;;N;SUBSCRIPT HYPHEN-MINUS;;;; -208C;SUBSCRIPT EQUALS SIGN;Sm;0;ON; 003D;;;;N;;;;; -208D;SUBSCRIPT LEFT PARENTHESIS;Ps;0;ON; 0028;;;;Y;SUBSCRIPT OPENING PARENTHESIS;;;; -208E;SUBSCRIPT RIGHT PARENTHESIS;Pe;0;ON; 0029;;;;Y;SUBSCRIPT CLOSING PARENTHESIS;;;; -2090;LATIN SUBSCRIPT SMALL LETTER A;Lm;0;L; 0061;;;;N;;;;; -2091;LATIN SUBSCRIPT SMALL LETTER E;Lm;0;L; 0065;;;;N;;;;; -2092;LATIN SUBSCRIPT SMALL LETTER O;Lm;0;L; 006F;;;;N;;;;; -2093;LATIN SUBSCRIPT SMALL LETTER X;Lm;0;L; 0078;;;;N;;;;; -2094;LATIN SUBSCRIPT SMALL LETTER SCHWA;Lm;0;L; 0259;;;;N;;;;; -20A0;EURO-CURRENCY SIGN;Sc;0;ET;;;;;N;;;;; -20A1;COLON SIGN;Sc;0;ET;;;;;N;;;;; -20A2;CRUZEIRO SIGN;Sc;0;ET;;;;;N;;;;; -20A3;FRENCH FRANC SIGN;Sc;0;ET;;;;;N;;;;; -20A4;LIRA SIGN;Sc;0;ET;;;;;N;;;;; -20A5;MILL SIGN;Sc;0;ET;;;;;N;;;;; -20A6;NAIRA SIGN;Sc;0;ET;;;;;N;;;;; -20A7;PESETA SIGN;Sc;0;ET;;;;;N;;;;; -20A8;RUPEE SIGN;Sc;0;ET; 0052 0073;;;;N;;;;; -20A9;WON SIGN;Sc;0;ET;;;;;N;;;;; -20AA;NEW SHEQEL SIGN;Sc;0;ET;;;;;N;;;;; -20AB;DONG SIGN;Sc;0;ET;;;;;N;;;;; -20AC;EURO SIGN;Sc;0;ET;;;;;N;;;;; -20AD;KIP SIGN;Sc;0;ET;;;;;N;;;;; -20AE;TUGRIK SIGN;Sc;0;ET;;;;;N;;;;; -20AF;DRACHMA SIGN;Sc;0;ET;;;;;N;;;;; -20B0;GERMAN PENNY SIGN;Sc;0;ET;;;;;N;;;;; -20B1;PESO SIGN;Sc;0;ET;;;;;N;;;;; -20B2;GUARANI SIGN;Sc;0;ET;;;;;N;;;;; -20B3;AUSTRAL SIGN;Sc;0;ET;;;;;N;;;;; -20B4;HRYVNIA SIGN;Sc;0;ET;;;;;N;;;;; -20B5;CEDI SIGN;Sc;0;ET;;;;;N;;;;; -20D0;COMBINING LEFT HARPOON ABOVE;Mn;230;NSM;;;;;N;NON-SPACING LEFT HARPOON ABOVE;;;; -20D1;COMBINING RIGHT HARPOON ABOVE;Mn;230;NSM;;;;;N;NON-SPACING RIGHT HARPOON ABOVE;;;; -20D2;COMBINING LONG VERTICAL LINE OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING LONG VERTICAL BAR OVERLAY;;;; -20D3;COMBINING SHORT VERTICAL LINE OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING SHORT VERTICAL BAR OVERLAY;;;; -20D4;COMBINING ANTICLOCKWISE ARROW ABOVE;Mn;230;NSM;;;;;N;NON-SPACING ANTICLOCKWISE ARROW ABOVE;;;; -20D5;COMBINING CLOCKWISE ARROW ABOVE;Mn;230;NSM;;;;;N;NON-SPACING CLOCKWISE ARROW ABOVE;;;; -20D6;COMBINING LEFT ARROW ABOVE;Mn;230;NSM;;;;;N;NON-SPACING LEFT ARROW ABOVE;;;; -20D7;COMBINING RIGHT ARROW ABOVE;Mn;230;NSM;;;;;N;NON-SPACING RIGHT ARROW ABOVE;;;; -20D8;COMBINING RING OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING RING OVERLAY;;;; -20D9;COMBINING CLOCKWISE RING OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING CLOCKWISE RING OVERLAY;;;; -20DA;COMBINING ANTICLOCKWISE RING OVERLAY;Mn;1;NSM;;;;;N;NON-SPACING ANTICLOCKWISE RING OVERLAY;;;; -20DB;COMBINING THREE DOTS ABOVE;Mn;230;NSM;;;;;N;NON-SPACING THREE DOTS ABOVE;;;; -20DC;COMBINING FOUR DOTS ABOVE;Mn;230;NSM;;;;;N;NON-SPACING FOUR DOTS ABOVE;;;; -20DD;COMBINING ENCLOSING CIRCLE;Me;0;NSM;;;;;N;ENCLOSING CIRCLE;;;; -20DE;COMBINING ENCLOSING SQUARE;Me;0;NSM;;;;;N;ENCLOSING SQUARE;;;; -20DF;COMBINING ENCLOSING DIAMOND;Me;0;NSM;;;;;N;ENCLOSING DIAMOND;;;; -20E0;COMBINING ENCLOSING CIRCLE BACKSLASH;Me;0;NSM;;;;;N;ENCLOSING CIRCLE SLASH;;;; -20E1;COMBINING LEFT RIGHT ARROW ABOVE;Mn;230;NSM;;;;;N;NON-SPACING LEFT RIGHT ARROW ABOVE;;;; -20E2;COMBINING ENCLOSING SCREEN;Me;0;NSM;;;;;N;;;;; -20E3;COMBINING ENCLOSING KEYCAP;Me;0;NSM;;;;;N;;;;; -20E4;COMBINING ENCLOSING UPWARD POINTING TRIANGLE;Me;0;NSM;;;;;N;;;;; -20E5;COMBINING REVERSE SOLIDUS OVERLAY;Mn;1;NSM;;;;;N;;;;; -20E6;COMBINING DOUBLE VERTICAL STROKE OVERLAY;Mn;1;NSM;;;;;N;;;;; -20E7;COMBINING ANNUITY SYMBOL;Mn;230;NSM;;;;;N;;;;; -20E8;COMBINING TRIPLE UNDERDOT;Mn;220;NSM;;;;;N;;;;; -20E9;COMBINING WIDE BRIDGE ABOVE;Mn;230;NSM;;;;;N;;;;; -20EA;COMBINING LEFTWARDS ARROW OVERLAY;Mn;1;NSM;;;;;N;;;;; -20EB;COMBINING LONG DOUBLE SOLIDUS OVERLAY;Mn;1;NSM;;;;;N;;;;; -20EC;COMBINING RIGHTWARDS HARPOON WITH BARB DOWNWARDS;Mn;220;NSM;;;;;N;;;;; -20ED;COMBINING LEFTWARDS HARPOON WITH BARB DOWNWARDS;Mn;220;NSM;;;;;N;;;;; -20EE;COMBINING LEFT ARROW BELOW;Mn;220;NSM;;;;;N;;;;; -20EF;COMBINING RIGHT ARROW BELOW;Mn;220;NSM;;;;;N;;;;; -20F0;COMBINING ASTERISK ABOVE;Mn;230;NSM;;;;;N;;;;; -2100;ACCOUNT OF;So;0;ON; 0061 002F 0063;;;;N;;;;; -2101;ADDRESSED TO THE SUBJECT;So;0;ON; 0061 002F 0073;;;;N;;;;; -2102;DOUBLE-STRUCK CAPITAL C;Lu;0;L; 0043;;;;N;DOUBLE-STRUCK C;;;; -2103;DEGREE CELSIUS;So;0;ON; 00B0 0043;;;;N;DEGREES CENTIGRADE;;;; -2104;CENTRE LINE SYMBOL;So;0;ON;;;;;N;C L SYMBOL;;;; -2105;CARE OF;So;0;ON; 0063 002F 006F;;;;N;;;;; -2106;CADA UNA;So;0;ON; 0063 002F 0075;;;;N;;;;; -2107;EULER CONSTANT;Lu;0;L; 0190;;;;N;EULERS;;;; -2108;SCRUPLE;So;0;ON;;;;;N;;;;; -2109;DEGREE FAHRENHEIT;So;0;ON; 00B0 0046;;;;N;DEGREES FAHRENHEIT;;;; -210A;SCRIPT SMALL G;Ll;0;L; 0067;;;;N;;;;; -210B;SCRIPT CAPITAL H;Lu;0;L; 0048;;;;N;SCRIPT H;;;; -210C;BLACK-LETTER CAPITAL H;Lu;0;L; 0048;;;;N;BLACK-LETTER H;;;; -210D;DOUBLE-STRUCK CAPITAL H;Lu;0;L; 0048;;;;N;DOUBLE-STRUCK H;;;; -210E;PLANCK CONSTANT;Ll;0;L; 0068;;;;N;;;;; -210F;PLANCK CONSTANT OVER TWO PI;Ll;0;L; 0127;;;;N;PLANCK CONSTANT OVER 2 PI;;;; -2110;SCRIPT CAPITAL I;Lu;0;L; 0049;;;;N;SCRIPT I;;;; -2111;BLACK-LETTER CAPITAL I;Lu;0;L; 0049;;;;N;BLACK-LETTER I;;;; -2112;SCRIPT CAPITAL L;Lu;0;L; 004C;;;;N;SCRIPT L;;;; -2113;SCRIPT SMALL L;Ll;0;L; 006C;;;;N;;;;; -2114;L B BAR SYMBOL;So;0;ON;;;;;N;;;;; -2115;DOUBLE-STRUCK CAPITAL N;Lu;0;L; 004E;;;;N;DOUBLE-STRUCK N;;;; -2116;NUMERO SIGN;So;0;ON; 004E 006F;;;;N;NUMERO;;;; -2117;SOUND RECORDING COPYRIGHT;So;0;ON;;;;;N;;;;; -2118;SCRIPT CAPITAL P;So;0;ON;;;;;N;SCRIPT P;;;; -2119;DOUBLE-STRUCK CAPITAL P;Lu;0;L; 0050;;;;N;DOUBLE-STRUCK P;;;; -211A;DOUBLE-STRUCK CAPITAL Q;Lu;0;L; 0051;;;;N;DOUBLE-STRUCK Q;;;; -211B;SCRIPT CAPITAL R;Lu;0;L; 0052;;;;N;SCRIPT R;;;; -211C;BLACK-LETTER CAPITAL R;Lu;0;L; 0052;;;;N;BLACK-LETTER R;;;; -211D;DOUBLE-STRUCK CAPITAL R;Lu;0;L; 0052;;;;N;DOUBLE-STRUCK R;;;; -211E;PRESCRIPTION TAKE;So;0;ON;;;;;N;;;;; -211F;RESPONSE;So;0;ON;;;;;N;;;;; -2120;SERVICE MARK;So;0;ON; 0053 004D;;;;N;;;;; -2121;TELEPHONE SIGN;So;0;ON; 0054 0045 004C;;;;N;T E L SYMBOL;;;; -2122;TRADE MARK SIGN;So;0;ON; 0054 004D;;;;N;TRADEMARK;;;; -2123;VERSICLE;So;0;ON;;;;;N;;;;; -2124;DOUBLE-STRUCK CAPITAL Z;Lu;0;L; 005A;;;;N;DOUBLE-STRUCK Z;;;; -2125;OUNCE SIGN;So;0;ON;;;;;N;OUNCE;;;; -2126;OHM SIGN;Lu;0;L;03A9;;;;N;OHM;;;03C9; -2127;INVERTED OHM SIGN;So;0;ON;;;;;N;MHO;;;; -2128;BLACK-LETTER CAPITAL Z;Lu;0;L; 005A;;;;N;BLACK-LETTER Z;;;; -2129;TURNED GREEK SMALL LETTER IOTA;So;0;ON;;;;;N;;;;; -212A;KELVIN SIGN;Lu;0;L;004B;;;;N;DEGREES KELVIN;;;006B; -212B;ANGSTROM SIGN;Lu;0;L;00C5;;;;N;ANGSTROM UNIT;;;00E5; -212C;SCRIPT CAPITAL B;Lu;0;L; 0042;;;;N;SCRIPT B;;;; -212D;BLACK-LETTER CAPITAL C;Lu;0;L; 0043;;;;N;BLACK-LETTER C;;;; -212E;ESTIMATED SYMBOL;So;0;ET;;;;;N;;;;; -212F;SCRIPT SMALL E;Ll;0;L; 0065;;;;N;;;;; -2130;SCRIPT CAPITAL E;Lu;0;L; 0045;;;;N;SCRIPT E;;;; -2131;SCRIPT CAPITAL F;Lu;0;L; 0046;;;;N;SCRIPT F;;;; -2132;TURNED CAPITAL F;Lu;0;L;;;;;N;TURNED F;;;214E; -2133;SCRIPT CAPITAL M;Lu;0;L; 004D;;;;N;SCRIPT M;;;; -2134;SCRIPT SMALL O;Ll;0;L; 006F;;;;N;;;;; -2135;ALEF SYMBOL;Lo;0;L; 05D0;;;;N;FIRST TRANSFINITE CARDINAL;;;; -2136;BET SYMBOL;Lo;0;L; 05D1;;;;N;SECOND TRANSFINITE CARDINAL;;;; -2137;GIMEL SYMBOL;Lo;0;L; 05D2;;;;N;THIRD TRANSFINITE CARDINAL;;;; -2138;DALET SYMBOL;Lo;0;L; 05D3;;;;N;FOURTH TRANSFINITE CARDINAL;;;; -2139;INFORMATION SOURCE;Ll;0;L; 0069;;;;N;;;;; -213A;ROTATED CAPITAL Q;So;0;ON;;;;;N;;;;; -213B;FACSIMILE SIGN;So;0;ON; 0046 0041 0058;;;;N;;;;; -213C;DOUBLE-STRUCK SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -213D;DOUBLE-STRUCK SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -213E;DOUBLE-STRUCK CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -213F;DOUBLE-STRUCK CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -2140;DOUBLE-STRUCK N-ARY SUMMATION;Sm;0;ON; 2211;;;;Y;;;;; -2141;TURNED SANS-SERIF CAPITAL G;Sm;0;ON;;;;;N;;;;; -2142;TURNED SANS-SERIF CAPITAL L;Sm;0;ON;;;;;N;;;;; -2143;REVERSED SANS-SERIF CAPITAL L;Sm;0;ON;;;;;N;;;;; -2144;TURNED SANS-SERIF CAPITAL Y;Sm;0;ON;;;;;N;;;;; -2145;DOUBLE-STRUCK ITALIC CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -2146;DOUBLE-STRUCK ITALIC SMALL D;Ll;0;L; 0064;;;;N;;;;; -2147;DOUBLE-STRUCK ITALIC SMALL E;Ll;0;L; 0065;;;;N;;;;; -2148;DOUBLE-STRUCK ITALIC SMALL I;Ll;0;L; 0069;;;;N;;;;; -2149;DOUBLE-STRUCK ITALIC SMALL J;Ll;0;L; 006A;;;;N;;;;; -214A;PROPERTY LINE;So;0;ON;;;;;N;;;;; -214B;TURNED AMPERSAND;Sm;0;ON;;;;;N;;;;; -214C;PER SIGN;So;0;ON;;;;;N;;;;; -214D;AKTIESELSKAB;So;0;ON;;;;;N;;;;; -214E;TURNED SMALL F;Ll;0;L;;;;;N;;;2132;;2132 -214F;SYMBOL FOR SAMARITAN SOURCE;So;0;L;;;;;N;;;;; -2153;VULGAR FRACTION ONE THIRD;No;0;ON; 0031 2044 0033;;;1/3;N;FRACTION ONE THIRD;;;; -2154;VULGAR FRACTION TWO THIRDS;No;0;ON; 0032 2044 0033;;;2/3;N;FRACTION TWO THIRDS;;;; -2155;VULGAR FRACTION ONE FIFTH;No;0;ON; 0031 2044 0035;;;1/5;N;FRACTION ONE FIFTH;;;; -2156;VULGAR FRACTION TWO FIFTHS;No;0;ON; 0032 2044 0035;;;2/5;N;FRACTION TWO FIFTHS;;;; -2157;VULGAR FRACTION THREE FIFTHS;No;0;ON; 0033 2044 0035;;;3/5;N;FRACTION THREE FIFTHS;;;; -2158;VULGAR FRACTION FOUR FIFTHS;No;0;ON; 0034 2044 0035;;;4/5;N;FRACTION FOUR FIFTHS;;;; -2159;VULGAR FRACTION ONE SIXTH;No;0;ON; 0031 2044 0036;;;1/6;N;FRACTION ONE SIXTH;;;; -215A;VULGAR FRACTION FIVE SIXTHS;No;0;ON; 0035 2044 0036;;;5/6;N;FRACTION FIVE SIXTHS;;;; -215B;VULGAR FRACTION ONE EIGHTH;No;0;ON; 0031 2044 0038;;;1/8;N;FRACTION ONE EIGHTH;;;; -215C;VULGAR FRACTION THREE EIGHTHS;No;0;ON; 0033 2044 0038;;;3/8;N;FRACTION THREE EIGHTHS;;;; -215D;VULGAR FRACTION FIVE EIGHTHS;No;0;ON; 0035 2044 0038;;;5/8;N;FRACTION FIVE EIGHTHS;;;; -215E;VULGAR FRACTION SEVEN EIGHTHS;No;0;ON; 0037 2044 0038;;;7/8;N;FRACTION SEVEN EIGHTHS;;;; -215F;FRACTION NUMERATOR ONE;No;0;ON; 0031 2044;;;1;N;;;;; -2160;ROMAN NUMERAL ONE;Nl;0;L; 0049;;;1;N;;;;2170; -2161;ROMAN NUMERAL TWO;Nl;0;L; 0049 0049;;;2;N;;;;2171; -2162;ROMAN NUMERAL THREE;Nl;0;L; 0049 0049 0049;;;3;N;;;;2172; -2163;ROMAN NUMERAL FOUR;Nl;0;L; 0049 0056;;;4;N;;;;2173; -2164;ROMAN NUMERAL FIVE;Nl;0;L; 0056;;;5;N;;;;2174; -2165;ROMAN NUMERAL SIX;Nl;0;L; 0056 0049;;;6;N;;;;2175; -2166;ROMAN NUMERAL SEVEN;Nl;0;L; 0056 0049 0049;;;7;N;;;;2176; -2167;ROMAN NUMERAL EIGHT;Nl;0;L; 0056 0049 0049 0049;;;8;N;;;;2177; -2168;ROMAN NUMERAL NINE;Nl;0;L; 0049 0058;;;9;N;;;;2178; -2169;ROMAN NUMERAL TEN;Nl;0;L; 0058;;;10;N;;;;2179; -216A;ROMAN NUMERAL ELEVEN;Nl;0;L; 0058 0049;;;11;N;;;;217A; -216B;ROMAN NUMERAL TWELVE;Nl;0;L; 0058 0049 0049;;;12;N;;;;217B; -216C;ROMAN NUMERAL FIFTY;Nl;0;L; 004C;;;50;N;;;;217C; -216D;ROMAN NUMERAL ONE HUNDRED;Nl;0;L; 0043;;;100;N;;;;217D; -216E;ROMAN NUMERAL FIVE HUNDRED;Nl;0;L; 0044;;;500;N;;;;217E; -216F;ROMAN NUMERAL ONE THOUSAND;Nl;0;L; 004D;;;1000;N;;;;217F; -2170;SMALL ROMAN NUMERAL ONE;Nl;0;L; 0069;;;1;N;;;2160;;2160 -2171;SMALL ROMAN NUMERAL TWO;Nl;0;L; 0069 0069;;;2;N;;;2161;;2161 -2172;SMALL ROMAN NUMERAL THREE;Nl;0;L; 0069 0069 0069;;;3;N;;;2162;;2162 -2173;SMALL ROMAN NUMERAL FOUR;Nl;0;L; 0069 0076;;;4;N;;;2163;;2163 -2174;SMALL ROMAN NUMERAL FIVE;Nl;0;L; 0076;;;5;N;;;2164;;2164 -2175;SMALL ROMAN NUMERAL SIX;Nl;0;L; 0076 0069;;;6;N;;;2165;;2165 -2176;SMALL ROMAN NUMERAL SEVEN;Nl;0;L; 0076 0069 0069;;;7;N;;;2166;;2166 -2177;SMALL ROMAN NUMERAL EIGHT;Nl;0;L; 0076 0069 0069 0069;;;8;N;;;2167;;2167 -2178;SMALL ROMAN NUMERAL NINE;Nl;0;L; 0069 0078;;;9;N;;;2168;;2168 -2179;SMALL ROMAN NUMERAL TEN;Nl;0;L; 0078;;;10;N;;;2169;;2169 -217A;SMALL ROMAN NUMERAL ELEVEN;Nl;0;L; 0078 0069;;;11;N;;;216A;;216A -217B;SMALL ROMAN NUMERAL TWELVE;Nl;0;L; 0078 0069 0069;;;12;N;;;216B;;216B -217C;SMALL ROMAN NUMERAL FIFTY;Nl;0;L; 006C;;;50;N;;;216C;;216C -217D;SMALL ROMAN NUMERAL ONE HUNDRED;Nl;0;L; 0063;;;100;N;;;216D;;216D -217E;SMALL ROMAN NUMERAL FIVE HUNDRED;Nl;0;L; 0064;;;500;N;;;216E;;216E -217F;SMALL ROMAN NUMERAL ONE THOUSAND;Nl;0;L; 006D;;;1000;N;;;216F;;216F -2180;ROMAN NUMERAL ONE THOUSAND C D;Nl;0;L;;;;1000;N;;;;; -2181;ROMAN NUMERAL FIVE THOUSAND;Nl;0;L;;;;5000;N;;;;; -2182;ROMAN NUMERAL TEN THOUSAND;Nl;0;L;;;;10000;N;;;;; -2183;ROMAN NUMERAL REVERSED ONE HUNDRED;Lu;0;L;;;;;N;;;;2184; -2184;LATIN SMALL LETTER REVERSED C;Ll;0;L;;;;;N;;;2183;;2183 -2185;ROMAN NUMERAL SIX LATE FORM;Nl;0;L;;;;6;N;;;;; -2186;ROMAN NUMERAL FIFTY EARLY FORM;Nl;0;L;;;;50;N;;;;; -2187;ROMAN NUMERAL FIFTY THOUSAND;Nl;0;L;;;;50000;N;;;;; -2188;ROMAN NUMERAL ONE HUNDRED THOUSAND;Nl;0;L;;;;100000;N;;;;; -2190;LEFTWARDS ARROW;Sm;0;ON;;;;;N;LEFT ARROW;;;; -2191;UPWARDS ARROW;Sm;0;ON;;;;;N;UP ARROW;;;; -2192;RIGHTWARDS ARROW;Sm;0;ON;;;;;N;RIGHT ARROW;;;; -2193;DOWNWARDS ARROW;Sm;0;ON;;;;;N;DOWN ARROW;;;; -2194;LEFT RIGHT ARROW;Sm;0;ON;;;;;N;;;;; -2195;UP DOWN ARROW;So;0;ON;;;;;N;;;;; -2196;NORTH WEST ARROW;So;0;ON;;;;;N;UPPER LEFT ARROW;;;; -2197;NORTH EAST ARROW;So;0;ON;;;;;N;UPPER RIGHT ARROW;;;; -2198;SOUTH EAST ARROW;So;0;ON;;;;;N;LOWER RIGHT ARROW;;;; -2199;SOUTH WEST ARROW;So;0;ON;;;;;N;LOWER LEFT ARROW;;;; -219A;LEFTWARDS ARROW WITH STROKE;Sm;0;ON;2190 0338;;;;N;LEFT ARROW WITH STROKE;;;; -219B;RIGHTWARDS ARROW WITH STROKE;Sm;0;ON;2192 0338;;;;N;RIGHT ARROW WITH STROKE;;;; -219C;LEFTWARDS WAVE ARROW;So;0;ON;;;;;N;LEFT WAVE ARROW;;;; -219D;RIGHTWARDS WAVE ARROW;So;0;ON;;;;;N;RIGHT WAVE ARROW;;;; -219E;LEFTWARDS TWO HEADED ARROW;So;0;ON;;;;;N;LEFT TWO HEADED ARROW;;;; -219F;UPWARDS TWO HEADED ARROW;So;0;ON;;;;;N;UP TWO HEADED ARROW;;;; -21A0;RIGHTWARDS TWO HEADED ARROW;Sm;0;ON;;;;;N;RIGHT TWO HEADED ARROW;;;; -21A1;DOWNWARDS TWO HEADED ARROW;So;0;ON;;;;;N;DOWN TWO HEADED ARROW;;;; -21A2;LEFTWARDS ARROW WITH TAIL;So;0;ON;;;;;N;LEFT ARROW WITH TAIL;;;; -21A3;RIGHTWARDS ARROW WITH TAIL;Sm;0;ON;;;;;N;RIGHT ARROW WITH TAIL;;;; -21A4;LEFTWARDS ARROW FROM BAR;So;0;ON;;;;;N;LEFT ARROW FROM BAR;;;; -21A5;UPWARDS ARROW FROM BAR;So;0;ON;;;;;N;UP ARROW FROM BAR;;;; -21A6;RIGHTWARDS ARROW FROM BAR;Sm;0;ON;;;;;N;RIGHT ARROW FROM BAR;;;; -21A7;DOWNWARDS ARROW FROM BAR;So;0;ON;;;;;N;DOWN ARROW FROM BAR;;;; -21A8;UP DOWN ARROW WITH BASE;So;0;ON;;;;;N;;;;; -21A9;LEFTWARDS ARROW WITH HOOK;So;0;ON;;;;;N;LEFT ARROW WITH HOOK;;;; -21AA;RIGHTWARDS ARROW WITH HOOK;So;0;ON;;;;;N;RIGHT ARROW WITH HOOK;;;; -21AB;LEFTWARDS ARROW WITH LOOP;So;0;ON;;;;;N;LEFT ARROW WITH LOOP;;;; -21AC;RIGHTWARDS ARROW WITH LOOP;So;0;ON;;;;;N;RIGHT ARROW WITH LOOP;;;; -21AD;LEFT RIGHT WAVE ARROW;So;0;ON;;;;;N;;;;; -21AE;LEFT RIGHT ARROW WITH STROKE;Sm;0;ON;2194 0338;;;;N;;;;; -21AF;DOWNWARDS ZIGZAG ARROW;So;0;ON;;;;;N;DOWN ZIGZAG ARROW;;;; -21B0;UPWARDS ARROW WITH TIP LEFTWARDS;So;0;ON;;;;;N;UP ARROW WITH TIP LEFT;;;; -21B1;UPWARDS ARROW WITH TIP RIGHTWARDS;So;0;ON;;;;;N;UP ARROW WITH TIP RIGHT;;;; -21B2;DOWNWARDS ARROW WITH TIP LEFTWARDS;So;0;ON;;;;;N;DOWN ARROW WITH TIP LEFT;;;; -21B3;DOWNWARDS ARROW WITH TIP RIGHTWARDS;So;0;ON;;;;;N;DOWN ARROW WITH TIP RIGHT;;;; -21B4;RIGHTWARDS ARROW WITH CORNER DOWNWARDS;So;0;ON;;;;;N;RIGHT ARROW WITH CORNER DOWN;;;; -21B5;DOWNWARDS ARROW WITH CORNER LEFTWARDS;So;0;ON;;;;;N;DOWN ARROW WITH CORNER LEFT;;;; -21B6;ANTICLOCKWISE TOP SEMICIRCLE ARROW;So;0;ON;;;;;N;;;;; -21B7;CLOCKWISE TOP SEMICIRCLE ARROW;So;0;ON;;;;;N;;;;; -21B8;NORTH WEST ARROW TO LONG BAR;So;0;ON;;;;;N;UPPER LEFT ARROW TO LONG BAR;;;; -21B9;LEFTWARDS ARROW TO BAR OVER RIGHTWARDS ARROW TO BAR;So;0;ON;;;;;N;LEFT ARROW TO BAR OVER RIGHT ARROW TO BAR;;;; -21BA;ANTICLOCKWISE OPEN CIRCLE ARROW;So;0;ON;;;;;N;;;;; -21BB;CLOCKWISE OPEN CIRCLE ARROW;So;0;ON;;;;;N;;;;; -21BC;LEFTWARDS HARPOON WITH BARB UPWARDS;So;0;ON;;;;;N;LEFT HARPOON WITH BARB UP;;;; -21BD;LEFTWARDS HARPOON WITH BARB DOWNWARDS;So;0;ON;;;;;N;LEFT HARPOON WITH BARB DOWN;;;; -21BE;UPWARDS HARPOON WITH BARB RIGHTWARDS;So;0;ON;;;;;N;UP HARPOON WITH BARB RIGHT;;;; -21BF;UPWARDS HARPOON WITH BARB LEFTWARDS;So;0;ON;;;;;N;UP HARPOON WITH BARB LEFT;;;; -21C0;RIGHTWARDS HARPOON WITH BARB UPWARDS;So;0;ON;;;;;N;RIGHT HARPOON WITH BARB UP;;;; -21C1;RIGHTWARDS HARPOON WITH BARB DOWNWARDS;So;0;ON;;;;;N;RIGHT HARPOON WITH BARB DOWN;;;; -21C2;DOWNWARDS HARPOON WITH BARB RIGHTWARDS;So;0;ON;;;;;N;DOWN HARPOON WITH BARB RIGHT;;;; -21C3;DOWNWARDS HARPOON WITH BARB LEFTWARDS;So;0;ON;;;;;N;DOWN HARPOON WITH BARB LEFT;;;; -21C4;RIGHTWARDS ARROW OVER LEFTWARDS ARROW;So;0;ON;;;;;N;RIGHT ARROW OVER LEFT ARROW;;;; -21C5;UPWARDS ARROW LEFTWARDS OF DOWNWARDS ARROW;So;0;ON;;;;;N;UP ARROW LEFT OF DOWN ARROW;;;; -21C6;LEFTWARDS ARROW OVER RIGHTWARDS ARROW;So;0;ON;;;;;N;LEFT ARROW OVER RIGHT ARROW;;;; -21C7;LEFTWARDS PAIRED ARROWS;So;0;ON;;;;;N;LEFT PAIRED ARROWS;;;; -21C8;UPWARDS PAIRED ARROWS;So;0;ON;;;;;N;UP PAIRED ARROWS;;;; -21C9;RIGHTWARDS PAIRED ARROWS;So;0;ON;;;;;N;RIGHT PAIRED ARROWS;;;; -21CA;DOWNWARDS PAIRED ARROWS;So;0;ON;;;;;N;DOWN PAIRED ARROWS;;;; -21CB;LEFTWARDS HARPOON OVER RIGHTWARDS HARPOON;So;0;ON;;;;;N;LEFT HARPOON OVER RIGHT HARPOON;;;; -21CC;RIGHTWARDS HARPOON OVER LEFTWARDS HARPOON;So;0;ON;;;;;N;RIGHT HARPOON OVER LEFT HARPOON;;;; -21CD;LEFTWARDS DOUBLE ARROW WITH STROKE;So;0;ON;21D0 0338;;;;N;LEFT DOUBLE ARROW WITH STROKE;;;; -21CE;LEFT RIGHT DOUBLE ARROW WITH STROKE;Sm;0;ON;21D4 0338;;;;N;;;;; -21CF;RIGHTWARDS DOUBLE ARROW WITH STROKE;Sm;0;ON;21D2 0338;;;;N;RIGHT DOUBLE ARROW WITH STROKE;;;; -21D0;LEFTWARDS DOUBLE ARROW;So;0;ON;;;;;N;LEFT DOUBLE ARROW;;;; -21D1;UPWARDS DOUBLE ARROW;So;0;ON;;;;;N;UP DOUBLE ARROW;;;; -21D2;RIGHTWARDS DOUBLE ARROW;Sm;0;ON;;;;;N;RIGHT DOUBLE ARROW;;;; -21D3;DOWNWARDS DOUBLE ARROW;So;0;ON;;;;;N;DOWN DOUBLE ARROW;;;; -21D4;LEFT RIGHT DOUBLE ARROW;Sm;0;ON;;;;;N;;;;; -21D5;UP DOWN DOUBLE ARROW;So;0;ON;;;;;N;;;;; -21D6;NORTH WEST DOUBLE ARROW;So;0;ON;;;;;N;UPPER LEFT DOUBLE ARROW;;;; -21D7;NORTH EAST DOUBLE ARROW;So;0;ON;;;;;N;UPPER RIGHT DOUBLE ARROW;;;; -21D8;SOUTH EAST DOUBLE ARROW;So;0;ON;;;;;N;LOWER RIGHT DOUBLE ARROW;;;; -21D9;SOUTH WEST DOUBLE ARROW;So;0;ON;;;;;N;LOWER LEFT DOUBLE ARROW;;;; -21DA;LEFTWARDS TRIPLE ARROW;So;0;ON;;;;;N;LEFT TRIPLE ARROW;;;; -21DB;RIGHTWARDS TRIPLE ARROW;So;0;ON;;;;;N;RIGHT TRIPLE ARROW;;;; -21DC;LEFTWARDS SQUIGGLE ARROW;So;0;ON;;;;;N;LEFT SQUIGGLE ARROW;;;; -21DD;RIGHTWARDS SQUIGGLE ARROW;So;0;ON;;;;;N;RIGHT SQUIGGLE ARROW;;;; -21DE;UPWARDS ARROW WITH DOUBLE STROKE;So;0;ON;;;;;N;UP ARROW WITH DOUBLE STROKE;;;; -21DF;DOWNWARDS ARROW WITH DOUBLE STROKE;So;0;ON;;;;;N;DOWN ARROW WITH DOUBLE STROKE;;;; -21E0;LEFTWARDS DASHED ARROW;So;0;ON;;;;;N;LEFT DASHED ARROW;;;; -21E1;UPWARDS DASHED ARROW;So;0;ON;;;;;N;UP DASHED ARROW;;;; -21E2;RIGHTWARDS DASHED ARROW;So;0;ON;;;;;N;RIGHT DASHED ARROW;;;; -21E3;DOWNWARDS DASHED ARROW;So;0;ON;;;;;N;DOWN DASHED ARROW;;;; -21E4;LEFTWARDS ARROW TO BAR;So;0;ON;;;;;N;LEFT ARROW TO BAR;;;; -21E5;RIGHTWARDS ARROW TO BAR;So;0;ON;;;;;N;RIGHT ARROW TO BAR;;;; -21E6;LEFTWARDS WHITE ARROW;So;0;ON;;;;;N;WHITE LEFT ARROW;;;; -21E7;UPWARDS WHITE ARROW;So;0;ON;;;;;N;WHITE UP ARROW;;;; -21E8;RIGHTWARDS WHITE ARROW;So;0;ON;;;;;N;WHITE RIGHT ARROW;;;; -21E9;DOWNWARDS WHITE ARROW;So;0;ON;;;;;N;WHITE DOWN ARROW;;;; -21EA;UPWARDS WHITE ARROW FROM BAR;So;0;ON;;;;;N;WHITE UP ARROW FROM BAR;;;; -21EB;UPWARDS WHITE ARROW ON PEDESTAL;So;0;ON;;;;;N;;;;; -21EC;UPWARDS WHITE ARROW ON PEDESTAL WITH HORIZONTAL BAR;So;0;ON;;;;;N;;;;; -21ED;UPWARDS WHITE ARROW ON PEDESTAL WITH VERTICAL BAR;So;0;ON;;;;;N;;;;; -21EE;UPWARDS WHITE DOUBLE ARROW;So;0;ON;;;;;N;;;;; -21EF;UPWARDS WHITE DOUBLE ARROW ON PEDESTAL;So;0;ON;;;;;N;;;;; -21F0;RIGHTWARDS WHITE ARROW FROM WALL;So;0;ON;;;;;N;;;;; -21F1;NORTH WEST ARROW TO CORNER;So;0;ON;;;;;N;;;;; -21F2;SOUTH EAST ARROW TO CORNER;So;0;ON;;;;;N;;;;; -21F3;UP DOWN WHITE ARROW;So;0;ON;;;;;N;;;;; -21F4;RIGHT ARROW WITH SMALL CIRCLE;Sm;0;ON;;;;;N;;;;; -21F5;DOWNWARDS ARROW LEFTWARDS OF UPWARDS ARROW;Sm;0;ON;;;;;N;;;;; -21F6;THREE RIGHTWARDS ARROWS;Sm;0;ON;;;;;N;;;;; -21F7;LEFTWARDS ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21F8;RIGHTWARDS ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21F9;LEFT RIGHT ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21FA;LEFTWARDS ARROW WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21FB;RIGHTWARDS ARROW WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21FC;LEFT RIGHT ARROW WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -21FD;LEFTWARDS OPEN-HEADED ARROW;Sm;0;ON;;;;;N;;;;; -21FE;RIGHTWARDS OPEN-HEADED ARROW;Sm;0;ON;;;;;N;;;;; -21FF;LEFT RIGHT OPEN-HEADED ARROW;Sm;0;ON;;;;;N;;;;; -2200;FOR ALL;Sm;0;ON;;;;;N;;;;; -2201;COMPLEMENT;Sm;0;ON;;;;;Y;;;;; -2202;PARTIAL DIFFERENTIAL;Sm;0;ON;;;;;Y;;;;; -2203;THERE EXISTS;Sm;0;ON;;;;;Y;;;;; -2204;THERE DOES NOT EXIST;Sm;0;ON;2203 0338;;;;Y;;;;; -2205;EMPTY SET;Sm;0;ON;;;;;N;;;;; -2206;INCREMENT;Sm;0;ON;;;;;N;;;;; -2207;NABLA;Sm;0;ON;;;;;N;;;;; -2208;ELEMENT OF;Sm;0;ON;;;;;Y;;;;; -2209;NOT AN ELEMENT OF;Sm;0;ON;2208 0338;;;;Y;;;;; -220A;SMALL ELEMENT OF;Sm;0;ON;;;;;Y;;;;; -220B;CONTAINS AS MEMBER;Sm;0;ON;;;;;Y;;;;; -220C;DOES NOT CONTAIN AS MEMBER;Sm;0;ON;220B 0338;;;;Y;;;;; -220D;SMALL CONTAINS AS MEMBER;Sm;0;ON;;;;;Y;;;;; -220E;END OF PROOF;Sm;0;ON;;;;;N;;;;; -220F;N-ARY PRODUCT;Sm;0;ON;;;;;N;;;;; -2210;N-ARY COPRODUCT;Sm;0;ON;;;;;N;;;;; -2211;N-ARY SUMMATION;Sm;0;ON;;;;;Y;;;;; -2212;MINUS SIGN;Sm;0;ES;;;;;N;;;;; -2213;MINUS-OR-PLUS SIGN;Sm;0;ET;;;;;N;;;;; -2214;DOT PLUS;Sm;0;ON;;;;;N;;;;; -2215;DIVISION SLASH;Sm;0;ON;;;;;Y;;;;; -2216;SET MINUS;Sm;0;ON;;;;;Y;;;;; -2217;ASTERISK OPERATOR;Sm;0;ON;;;;;N;;;;; -2218;RING OPERATOR;Sm;0;ON;;;;;N;;;;; -2219;BULLET OPERATOR;Sm;0;ON;;;;;N;;;;; -221A;SQUARE ROOT;Sm;0;ON;;;;;Y;;;;; -221B;CUBE ROOT;Sm;0;ON;;;;;Y;;;;; -221C;FOURTH ROOT;Sm;0;ON;;;;;Y;;;;; -221D;PROPORTIONAL TO;Sm;0;ON;;;;;Y;;;;; -221E;INFINITY;Sm;0;ON;;;;;N;;;;; -221F;RIGHT ANGLE;Sm;0;ON;;;;;Y;;;;; -2220;ANGLE;Sm;0;ON;;;;;Y;;;;; -2221;MEASURED ANGLE;Sm;0;ON;;;;;Y;;;;; -2222;SPHERICAL ANGLE;Sm;0;ON;;;;;Y;;;;; -2223;DIVIDES;Sm;0;ON;;;;;N;;;;; -2224;DOES NOT DIVIDE;Sm;0;ON;2223 0338;;;;Y;;;;; -2225;PARALLEL TO;Sm;0;ON;;;;;N;;;;; -2226;NOT PARALLEL TO;Sm;0;ON;2225 0338;;;;Y;;;;; -2227;LOGICAL AND;Sm;0;ON;;;;;N;;;;; -2228;LOGICAL OR;Sm;0;ON;;;;;N;;;;; -2229;INTERSECTION;Sm;0;ON;;;;;N;;;;; -222A;UNION;Sm;0;ON;;;;;N;;;;; -222B;INTEGRAL;Sm;0;ON;;;;;Y;;;;; -222C;DOUBLE INTEGRAL;Sm;0;ON; 222B 222B;;;;Y;;;;; -222D;TRIPLE INTEGRAL;Sm;0;ON; 222B 222B 222B;;;;Y;;;;; -222E;CONTOUR INTEGRAL;Sm;0;ON;;;;;Y;;;;; -222F;SURFACE INTEGRAL;Sm;0;ON; 222E 222E;;;;Y;;;;; -2230;VOLUME INTEGRAL;Sm;0;ON; 222E 222E 222E;;;;Y;;;;; -2231;CLOCKWISE INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2232;CLOCKWISE CONTOUR INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2233;ANTICLOCKWISE CONTOUR INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2234;THEREFORE;Sm;0;ON;;;;;N;;;;; -2235;BECAUSE;Sm;0;ON;;;;;N;;;;; -2236;RATIO;Sm;0;ON;;;;;N;;;;; -2237;PROPORTION;Sm;0;ON;;;;;N;;;;; -2238;DOT MINUS;Sm;0;ON;;;;;N;;;;; -2239;EXCESS;Sm;0;ON;;;;;Y;;;;; -223A;GEOMETRIC PROPORTION;Sm;0;ON;;;;;N;;;;; -223B;HOMOTHETIC;Sm;0;ON;;;;;Y;;;;; -223C;TILDE OPERATOR;Sm;0;ON;;;;;Y;;;;; -223D;REVERSED TILDE;Sm;0;ON;;;;;Y;;lazy S;;; -223E;INVERTED LAZY S;Sm;0;ON;;;;;Y;;;;; -223F;SINE WAVE;Sm;0;ON;;;;;Y;;;;; -2240;WREATH PRODUCT;Sm;0;ON;;;;;Y;;;;; -2241;NOT TILDE;Sm;0;ON;223C 0338;;;;Y;;;;; -2242;MINUS TILDE;Sm;0;ON;;;;;Y;;;;; -2243;ASYMPTOTICALLY EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2244;NOT ASYMPTOTICALLY EQUAL TO;Sm;0;ON;2243 0338;;;;Y;;;;; -2245;APPROXIMATELY EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2246;APPROXIMATELY BUT NOT ACTUALLY EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2247;NEITHER APPROXIMATELY NOR ACTUALLY EQUAL TO;Sm;0;ON;2245 0338;;;;Y;;;;; -2248;ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2249;NOT ALMOST EQUAL TO;Sm;0;ON;2248 0338;;;;Y;;;;; -224A;ALMOST EQUAL OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -224B;TRIPLE TILDE;Sm;0;ON;;;;;Y;;;;; -224C;ALL EQUAL TO;Sm;0;ON;;;;;Y;;;;; -224D;EQUIVALENT TO;Sm;0;ON;;;;;N;;;;; -224E;GEOMETRICALLY EQUIVALENT TO;Sm;0;ON;;;;;N;;;;; -224F;DIFFERENCE BETWEEN;Sm;0;ON;;;;;N;;;;; -2250;APPROACHES THE LIMIT;Sm;0;ON;;;;;N;;;;; -2251;GEOMETRICALLY EQUAL TO;Sm;0;ON;;;;;N;;;;; -2252;APPROXIMATELY EQUAL TO OR THE IMAGE OF;Sm;0;ON;;;;;Y;;;;; -2253;IMAGE OF OR APPROXIMATELY EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2254;COLON EQUALS;Sm;0;ON;;;;;Y;COLON EQUAL;;;; -2255;EQUALS COLON;Sm;0;ON;;;;;Y;EQUAL COLON;;;; -2256;RING IN EQUAL TO;Sm;0;ON;;;;;N;;;;; -2257;RING EQUAL TO;Sm;0;ON;;;;;N;;;;; -2258;CORRESPONDS TO;Sm;0;ON;;;;;N;;;;; -2259;ESTIMATES;Sm;0;ON;;;;;N;;;;; -225A;EQUIANGULAR TO;Sm;0;ON;;;;;N;;;;; -225B;STAR EQUALS;Sm;0;ON;;;;;N;;;;; -225C;DELTA EQUAL TO;Sm;0;ON;;;;;N;;;;; -225D;EQUAL TO BY DEFINITION;Sm;0;ON;;;;;N;;;;; -225E;MEASURED BY;Sm;0;ON;;;;;N;;;;; -225F;QUESTIONED EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2260;NOT EQUAL TO;Sm;0;ON;003D 0338;;;;Y;;;;; -2261;IDENTICAL TO;Sm;0;ON;;;;;N;;;;; -2262;NOT IDENTICAL TO;Sm;0;ON;2261 0338;;;;Y;;;;; -2263;STRICTLY EQUIVALENT TO;Sm;0;ON;;;;;N;;;;; -2264;LESS-THAN OR EQUAL TO;Sm;0;ON;;;;;Y;LESS THAN OR EQUAL TO;;;; -2265;GREATER-THAN OR EQUAL TO;Sm;0;ON;;;;;Y;GREATER THAN OR EQUAL TO;;;; -2266;LESS-THAN OVER EQUAL TO;Sm;0;ON;;;;;Y;LESS THAN OVER EQUAL TO;;;; -2267;GREATER-THAN OVER EQUAL TO;Sm;0;ON;;;;;Y;GREATER THAN OVER EQUAL TO;;;; -2268;LESS-THAN BUT NOT EQUAL TO;Sm;0;ON;;;;;Y;LESS THAN BUT NOT EQUAL TO;;;; -2269;GREATER-THAN BUT NOT EQUAL TO;Sm;0;ON;;;;;Y;GREATER THAN BUT NOT EQUAL TO;;;; -226A;MUCH LESS-THAN;Sm;0;ON;;;;;Y;MUCH LESS THAN;;;; -226B;MUCH GREATER-THAN;Sm;0;ON;;;;;Y;MUCH GREATER THAN;;;; -226C;BETWEEN;Sm;0;ON;;;;;N;;;;; -226D;NOT EQUIVALENT TO;Sm;0;ON;224D 0338;;;;N;;;;; -226E;NOT LESS-THAN;Sm;0;ON;003C 0338;;;;Y;NOT LESS THAN;;;; -226F;NOT GREATER-THAN;Sm;0;ON;003E 0338;;;;Y;NOT GREATER THAN;;;; -2270;NEITHER LESS-THAN NOR EQUAL TO;Sm;0;ON;2264 0338;;;;Y;NEITHER LESS THAN NOR EQUAL TO;;;; -2271;NEITHER GREATER-THAN NOR EQUAL TO;Sm;0;ON;2265 0338;;;;Y;NEITHER GREATER THAN NOR EQUAL TO;;;; -2272;LESS-THAN OR EQUIVALENT TO;Sm;0;ON;;;;;Y;LESS THAN OR EQUIVALENT TO;;;; -2273;GREATER-THAN OR EQUIVALENT TO;Sm;0;ON;;;;;Y;GREATER THAN OR EQUIVALENT TO;;;; -2274;NEITHER LESS-THAN NOR EQUIVALENT TO;Sm;0;ON;2272 0338;;;;Y;NEITHER LESS THAN NOR EQUIVALENT TO;;;; -2275;NEITHER GREATER-THAN NOR EQUIVALENT TO;Sm;0;ON;2273 0338;;;;Y;NEITHER GREATER THAN NOR EQUIVALENT TO;;;; -2276;LESS-THAN OR GREATER-THAN;Sm;0;ON;;;;;Y;LESS THAN OR GREATER THAN;;;; -2277;GREATER-THAN OR LESS-THAN;Sm;0;ON;;;;;Y;GREATER THAN OR LESS THAN;;;; -2278;NEITHER LESS-THAN NOR GREATER-THAN;Sm;0;ON;2276 0338;;;;Y;NEITHER LESS THAN NOR GREATER THAN;;;; -2279;NEITHER GREATER-THAN NOR LESS-THAN;Sm;0;ON;2277 0338;;;;Y;NEITHER GREATER THAN NOR LESS THAN;;;; -227A;PRECEDES;Sm;0;ON;;;;;Y;;;;; -227B;SUCCEEDS;Sm;0;ON;;;;;Y;;;;; -227C;PRECEDES OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -227D;SUCCEEDS OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -227E;PRECEDES OR EQUIVALENT TO;Sm;0;ON;;;;;Y;;;;; -227F;SUCCEEDS OR EQUIVALENT TO;Sm;0;ON;;;;;Y;;;;; -2280;DOES NOT PRECEDE;Sm;0;ON;227A 0338;;;;Y;;;;; -2281;DOES NOT SUCCEED;Sm;0;ON;227B 0338;;;;Y;;;;; -2282;SUBSET OF;Sm;0;ON;;;;;Y;;;;; -2283;SUPERSET OF;Sm;0;ON;;;;;Y;;;;; -2284;NOT A SUBSET OF;Sm;0;ON;2282 0338;;;;Y;;;;; -2285;NOT A SUPERSET OF;Sm;0;ON;2283 0338;;;;Y;;;;; -2286;SUBSET OF OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2287;SUPERSET OF OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2288;NEITHER A SUBSET OF NOR EQUAL TO;Sm;0;ON;2286 0338;;;;Y;;;;; -2289;NEITHER A SUPERSET OF NOR EQUAL TO;Sm;0;ON;2287 0338;;;;Y;;;;; -228A;SUBSET OF WITH NOT EQUAL TO;Sm;0;ON;;;;;Y;SUBSET OF OR NOT EQUAL TO;;;; -228B;SUPERSET OF WITH NOT EQUAL TO;Sm;0;ON;;;;;Y;SUPERSET OF OR NOT EQUAL TO;;;; -228C;MULTISET;Sm;0;ON;;;;;Y;;;;; -228D;MULTISET MULTIPLICATION;Sm;0;ON;;;;;N;;;;; -228E;MULTISET UNION;Sm;0;ON;;;;;N;;;;; -228F;SQUARE IMAGE OF;Sm;0;ON;;;;;Y;;;;; -2290;SQUARE ORIGINAL OF;Sm;0;ON;;;;;Y;;;;; -2291;SQUARE IMAGE OF OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2292;SQUARE ORIGINAL OF OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2293;SQUARE CAP;Sm;0;ON;;;;;N;;;;; -2294;SQUARE CUP;Sm;0;ON;;;;;N;;;;; -2295;CIRCLED PLUS;Sm;0;ON;;;;;N;;;;; -2296;CIRCLED MINUS;Sm;0;ON;;;;;N;;;;; -2297;CIRCLED TIMES;Sm;0;ON;;;;;N;;;;; -2298;CIRCLED DIVISION SLASH;Sm;0;ON;;;;;Y;;;;; -2299;CIRCLED DOT OPERATOR;Sm;0;ON;;;;;N;;;;; -229A;CIRCLED RING OPERATOR;Sm;0;ON;;;;;N;;;;; -229B;CIRCLED ASTERISK OPERATOR;Sm;0;ON;;;;;N;;;;; -229C;CIRCLED EQUALS;Sm;0;ON;;;;;N;;;;; -229D;CIRCLED DASH;Sm;0;ON;;;;;N;;;;; -229E;SQUARED PLUS;Sm;0;ON;;;;;N;;;;; -229F;SQUARED MINUS;Sm;0;ON;;;;;N;;;;; -22A0;SQUARED TIMES;Sm;0;ON;;;;;N;;;;; -22A1;SQUARED DOT OPERATOR;Sm;0;ON;;;;;N;;;;; -22A2;RIGHT TACK;Sm;0;ON;;;;;Y;;;;; -22A3;LEFT TACK;Sm;0;ON;;;;;Y;;;;; -22A4;DOWN TACK;Sm;0;ON;;;;;N;;;;; -22A5;UP TACK;Sm;0;ON;;;;;N;;;;; -22A6;ASSERTION;Sm;0;ON;;;;;Y;;;;; -22A7;MODELS;Sm;0;ON;;;;;Y;;;;; -22A8;TRUE;Sm;0;ON;;;;;Y;;;;; -22A9;FORCES;Sm;0;ON;;;;;Y;;;;; -22AA;TRIPLE VERTICAL BAR RIGHT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -22AB;DOUBLE VERTICAL BAR DOUBLE RIGHT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -22AC;DOES NOT PROVE;Sm;0;ON;22A2 0338;;;;Y;;;;; -22AD;NOT TRUE;Sm;0;ON;22A8 0338;;;;Y;;;;; -22AE;DOES NOT FORCE;Sm;0;ON;22A9 0338;;;;Y;;;;; -22AF;NEGATED DOUBLE VERTICAL BAR DOUBLE RIGHT TURNSTILE;Sm;0;ON;22AB 0338;;;;Y;;;;; -22B0;PRECEDES UNDER RELATION;Sm;0;ON;;;;;Y;;;;; -22B1;SUCCEEDS UNDER RELATION;Sm;0;ON;;;;;Y;;;;; -22B2;NORMAL SUBGROUP OF;Sm;0;ON;;;;;Y;;;;; -22B3;CONTAINS AS NORMAL SUBGROUP;Sm;0;ON;;;;;Y;;;;; -22B4;NORMAL SUBGROUP OF OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -22B5;CONTAINS AS NORMAL SUBGROUP OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -22B6;ORIGINAL OF;Sm;0;ON;;;;;Y;;;;; -22B7;IMAGE OF;Sm;0;ON;;;;;Y;;;;; -22B8;MULTIMAP;Sm;0;ON;;;;;Y;;;;; -22B9;HERMITIAN CONJUGATE MATRIX;Sm;0;ON;;;;;N;;;;; -22BA;INTERCALATE;Sm;0;ON;;;;;N;;;;; -22BB;XOR;Sm;0;ON;;;;;N;;;;; -22BC;NAND;Sm;0;ON;;;;;N;;;;; -22BD;NOR;Sm;0;ON;;;;;N;;;;; -22BE;RIGHT ANGLE WITH ARC;Sm;0;ON;;;;;Y;;;;; -22BF;RIGHT TRIANGLE;Sm;0;ON;;;;;Y;;;;; -22C0;N-ARY LOGICAL AND;Sm;0;ON;;;;;N;;;;; -22C1;N-ARY LOGICAL OR;Sm;0;ON;;;;;N;;;;; -22C2;N-ARY INTERSECTION;Sm;0;ON;;;;;N;;;;; -22C3;N-ARY UNION;Sm;0;ON;;;;;N;;;;; -22C4;DIAMOND OPERATOR;Sm;0;ON;;;;;N;;;;; -22C5;DOT OPERATOR;Sm;0;ON;;;;;N;;;;; -22C6;STAR OPERATOR;Sm;0;ON;;;;;N;;;;; -22C7;DIVISION TIMES;Sm;0;ON;;;;;N;;;;; -22C8;BOWTIE;Sm;0;ON;;;;;N;;;;; -22C9;LEFT NORMAL FACTOR SEMIDIRECT PRODUCT;Sm;0;ON;;;;;Y;;;;; -22CA;RIGHT NORMAL FACTOR SEMIDIRECT PRODUCT;Sm;0;ON;;;;;Y;;;;; -22CB;LEFT SEMIDIRECT PRODUCT;Sm;0;ON;;;;;Y;;;;; -22CC;RIGHT SEMIDIRECT PRODUCT;Sm;0;ON;;;;;Y;;;;; -22CD;REVERSED TILDE EQUALS;Sm;0;ON;;;;;Y;;;;; -22CE;CURLY LOGICAL OR;Sm;0;ON;;;;;N;;;;; -22CF;CURLY LOGICAL AND;Sm;0;ON;;;;;N;;;;; -22D0;DOUBLE SUBSET;Sm;0;ON;;;;;Y;;;;; -22D1;DOUBLE SUPERSET;Sm;0;ON;;;;;Y;;;;; -22D2;DOUBLE INTERSECTION;Sm;0;ON;;;;;N;;;;; -22D3;DOUBLE UNION;Sm;0;ON;;;;;N;;;;; -22D4;PITCHFORK;Sm;0;ON;;;;;N;;;;; -22D5;EQUAL AND PARALLEL TO;Sm;0;ON;;;;;N;;;;; -22D6;LESS-THAN WITH DOT;Sm;0;ON;;;;;Y;LESS THAN WITH DOT;;;; -22D7;GREATER-THAN WITH DOT;Sm;0;ON;;;;;Y;GREATER THAN WITH DOT;;;; -22D8;VERY MUCH LESS-THAN;Sm;0;ON;;;;;Y;VERY MUCH LESS THAN;;;; -22D9;VERY MUCH GREATER-THAN;Sm;0;ON;;;;;Y;VERY MUCH GREATER THAN;;;; -22DA;LESS-THAN EQUAL TO OR GREATER-THAN;Sm;0;ON;;;;;Y;LESS THAN EQUAL TO OR GREATER THAN;;;; -22DB;GREATER-THAN EQUAL TO OR LESS-THAN;Sm;0;ON;;;;;Y;GREATER THAN EQUAL TO OR LESS THAN;;;; -22DC;EQUAL TO OR LESS-THAN;Sm;0;ON;;;;;Y;EQUAL TO OR LESS THAN;;;; -22DD;EQUAL TO OR GREATER-THAN;Sm;0;ON;;;;;Y;EQUAL TO OR GREATER THAN;;;; -22DE;EQUAL TO OR PRECEDES;Sm;0;ON;;;;;Y;;;;; -22DF;EQUAL TO OR SUCCEEDS;Sm;0;ON;;;;;Y;;;;; -22E0;DOES NOT PRECEDE OR EQUAL;Sm;0;ON;227C 0338;;;;Y;;;;; -22E1;DOES NOT SUCCEED OR EQUAL;Sm;0;ON;227D 0338;;;;Y;;;;; -22E2;NOT SQUARE IMAGE OF OR EQUAL TO;Sm;0;ON;2291 0338;;;;Y;;;;; -22E3;NOT SQUARE ORIGINAL OF OR EQUAL TO;Sm;0;ON;2292 0338;;;;Y;;;;; -22E4;SQUARE IMAGE OF OR NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -22E5;SQUARE ORIGINAL OF OR NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -22E6;LESS-THAN BUT NOT EQUIVALENT TO;Sm;0;ON;;;;;Y;LESS THAN BUT NOT EQUIVALENT TO;;;; -22E7;GREATER-THAN BUT NOT EQUIVALENT TO;Sm;0;ON;;;;;Y;GREATER THAN BUT NOT EQUIVALENT TO;;;; -22E8;PRECEDES BUT NOT EQUIVALENT TO;Sm;0;ON;;;;;Y;;;;; -22E9;SUCCEEDS BUT NOT EQUIVALENT TO;Sm;0;ON;;;;;Y;;;;; -22EA;NOT NORMAL SUBGROUP OF;Sm;0;ON;22B2 0338;;;;Y;;;;; -22EB;DOES NOT CONTAIN AS NORMAL SUBGROUP;Sm;0;ON;22B3 0338;;;;Y;;;;; -22EC;NOT NORMAL SUBGROUP OF OR EQUAL TO;Sm;0;ON;22B4 0338;;;;Y;;;;; -22ED;DOES NOT CONTAIN AS NORMAL SUBGROUP OR EQUAL;Sm;0;ON;22B5 0338;;;;Y;;;;; -22EE;VERTICAL ELLIPSIS;Sm;0;ON;;;;;N;;;;; -22EF;MIDLINE HORIZONTAL ELLIPSIS;Sm;0;ON;;;;;N;;;;; -22F0;UP RIGHT DIAGONAL ELLIPSIS;Sm;0;ON;;;;;Y;;;;; -22F1;DOWN RIGHT DIAGONAL ELLIPSIS;Sm;0;ON;;;;;Y;;;;; -22F2;ELEMENT OF WITH LONG HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22F3;ELEMENT OF WITH VERTICAL BAR AT END OF HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22F4;SMALL ELEMENT OF WITH VERTICAL BAR AT END OF HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22F5;ELEMENT OF WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -22F6;ELEMENT OF WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -22F7;SMALL ELEMENT OF WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -22F8;ELEMENT OF WITH UNDERBAR;Sm;0;ON;;;;;Y;;;;; -22F9;ELEMENT OF WITH TWO HORIZONTAL STROKES;Sm;0;ON;;;;;Y;;;;; -22FA;CONTAINS WITH LONG HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22FB;CONTAINS WITH VERTICAL BAR AT END OF HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22FC;SMALL CONTAINS WITH VERTICAL BAR AT END OF HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -22FD;CONTAINS WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -22FE;SMALL CONTAINS WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -22FF;Z NOTATION BAG MEMBERSHIP;Sm;0;ON;;;;;Y;;;;; -2300;DIAMETER SIGN;So;0;ON;;;;;N;;;;; -2301;ELECTRIC ARROW;So;0;ON;;;;;N;;;;; -2302;HOUSE;So;0;ON;;;;;N;;;;; -2303;UP ARROWHEAD;So;0;ON;;;;;N;;;;; -2304;DOWN ARROWHEAD;So;0;ON;;;;;N;;;;; -2305;PROJECTIVE;So;0;ON;;;;;N;;;;; -2306;PERSPECTIVE;So;0;ON;;;;;N;;;;; -2307;WAVY LINE;So;0;ON;;;;;N;;;;; -2308;LEFT CEILING;Sm;0;ON;;;;;Y;;;;; -2309;RIGHT CEILING;Sm;0;ON;;;;;Y;;;;; -230A;LEFT FLOOR;Sm;0;ON;;;;;Y;;;;; -230B;RIGHT FLOOR;Sm;0;ON;;;;;Y;;;;; -230C;BOTTOM RIGHT CROP;So;0;ON;;;;;N;;;;; -230D;BOTTOM LEFT CROP;So;0;ON;;;;;N;;;;; -230E;TOP RIGHT CROP;So;0;ON;;;;;N;;;;; -230F;TOP LEFT CROP;So;0;ON;;;;;N;;;;; -2310;REVERSED NOT SIGN;So;0;ON;;;;;N;;;;; -2311;SQUARE LOZENGE;So;0;ON;;;;;N;;;;; -2312;ARC;So;0;ON;;;;;N;;;;; -2313;SEGMENT;So;0;ON;;;;;N;;;;; -2314;SECTOR;So;0;ON;;;;;N;;;;; -2315;TELEPHONE RECORDER;So;0;ON;;;;;N;;;;; -2316;POSITION INDICATOR;So;0;ON;;;;;N;;;;; -2317;VIEWDATA SQUARE;So;0;ON;;;;;N;;;;; -2318;PLACE OF INTEREST SIGN;So;0;ON;;;;;N;COMMAND KEY;;;; -2319;TURNED NOT SIGN;So;0;ON;;;;;N;;;;; -231A;WATCH;So;0;ON;;;;;N;;;;; -231B;HOURGLASS;So;0;ON;;;;;N;;;;; -231C;TOP LEFT CORNER;So;0;ON;;;;;N;;;;; -231D;TOP RIGHT CORNER;So;0;ON;;;;;N;;;;; -231E;BOTTOM LEFT CORNER;So;0;ON;;;;;N;;;;; -231F;BOTTOM RIGHT CORNER;So;0;ON;;;;;N;;;;; -2320;TOP HALF INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2321;BOTTOM HALF INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2322;FROWN;So;0;ON;;;;;N;;;;; -2323;SMILE;So;0;ON;;;;;N;;;;; -2324;UP ARROWHEAD BETWEEN TWO HORIZONTAL BARS;So;0;ON;;;;;N;ENTER KEY;;;; -2325;OPTION KEY;So;0;ON;;;;;N;;;;; -2326;ERASE TO THE RIGHT;So;0;ON;;;;;N;DELETE TO THE RIGHT KEY;;;; -2327;X IN A RECTANGLE BOX;So;0;ON;;;;;N;CLEAR KEY;;;; -2328;KEYBOARD;So;0;ON;;;;;N;;;;; -2329;LEFT-POINTING ANGLE BRACKET;Ps;0;ON;3008;;;;Y;BRA;;;; -232A;RIGHT-POINTING ANGLE BRACKET;Pe;0;ON;3009;;;;Y;KET;;;; -232B;ERASE TO THE LEFT;So;0;ON;;;;;N;DELETE TO THE LEFT KEY;;;; -232C;BENZENE RING;So;0;ON;;;;;N;;;;; -232D;CYLINDRICITY;So;0;ON;;;;;N;;;;; -232E;ALL AROUND-PROFILE;So;0;ON;;;;;N;;;;; -232F;SYMMETRY;So;0;ON;;;;;N;;;;; -2330;TOTAL RUNOUT;So;0;ON;;;;;N;;;;; -2331;DIMENSION ORIGIN;So;0;ON;;;;;N;;;;; -2332;CONICAL TAPER;So;0;ON;;;;;N;;;;; -2333;SLOPE;So;0;ON;;;;;N;;;;; -2334;COUNTERBORE;So;0;ON;;;;;N;;;;; -2335;COUNTERSINK;So;0;ON;;;;;N;;;;; -2336;APL FUNCTIONAL SYMBOL I-BEAM;So;0;L;;;;;N;;;;; -2337;APL FUNCTIONAL SYMBOL SQUISH QUAD;So;0;L;;;;;N;;;;; -2338;APL FUNCTIONAL SYMBOL QUAD EQUAL;So;0;L;;;;;N;;;;; -2339;APL FUNCTIONAL SYMBOL QUAD DIVIDE;So;0;L;;;;;N;;;;; -233A;APL FUNCTIONAL SYMBOL QUAD DIAMOND;So;0;L;;;;;N;;;;; -233B;APL FUNCTIONAL SYMBOL QUAD JOT;So;0;L;;;;;N;;;;; -233C;APL FUNCTIONAL SYMBOL QUAD CIRCLE;So;0;L;;;;;N;;;;; -233D;APL FUNCTIONAL SYMBOL CIRCLE STILE;So;0;L;;;;;N;;;;; -233E;APL FUNCTIONAL SYMBOL CIRCLE JOT;So;0;L;;;;;N;;;;; -233F;APL FUNCTIONAL SYMBOL SLASH BAR;So;0;L;;;;;N;;;;; -2340;APL FUNCTIONAL SYMBOL BACKSLASH BAR;So;0;L;;;;;N;;;;; -2341;APL FUNCTIONAL SYMBOL QUAD SLASH;So;0;L;;;;;N;;;;; -2342;APL FUNCTIONAL SYMBOL QUAD BACKSLASH;So;0;L;;;;;N;;;;; -2343;APL FUNCTIONAL SYMBOL QUAD LESS-THAN;So;0;L;;;;;N;;;;; -2344;APL FUNCTIONAL SYMBOL QUAD GREATER-THAN;So;0;L;;;;;N;;;;; -2345;APL FUNCTIONAL SYMBOL LEFTWARDS VANE;So;0;L;;;;;N;;;;; -2346;APL FUNCTIONAL SYMBOL RIGHTWARDS VANE;So;0;L;;;;;N;;;;; -2347;APL FUNCTIONAL SYMBOL QUAD LEFTWARDS ARROW;So;0;L;;;;;N;;;;; -2348;APL FUNCTIONAL SYMBOL QUAD RIGHTWARDS ARROW;So;0;L;;;;;N;;;;; -2349;APL FUNCTIONAL SYMBOL CIRCLE BACKSLASH;So;0;L;;;;;N;;;;; -234A;APL FUNCTIONAL SYMBOL DOWN TACK UNDERBAR;So;0;L;;;;;N;;*;;; -234B;APL FUNCTIONAL SYMBOL DELTA STILE;So;0;L;;;;;N;;;;; -234C;APL FUNCTIONAL SYMBOL QUAD DOWN CARET;So;0;L;;;;;N;;;;; -234D;APL FUNCTIONAL SYMBOL QUAD DELTA;So;0;L;;;;;N;;;;; -234E;APL FUNCTIONAL SYMBOL DOWN TACK JOT;So;0;L;;;;;N;;*;;; -234F;APL FUNCTIONAL SYMBOL UPWARDS VANE;So;0;L;;;;;N;;;;; -2350;APL FUNCTIONAL SYMBOL QUAD UPWARDS ARROW;So;0;L;;;;;N;;;;; -2351;APL FUNCTIONAL SYMBOL UP TACK OVERBAR;So;0;L;;;;;N;;*;;; -2352;APL FUNCTIONAL SYMBOL DEL STILE;So;0;L;;;;;N;;;;; -2353;APL FUNCTIONAL SYMBOL QUAD UP CARET;So;0;L;;;;;N;;;;; -2354;APL FUNCTIONAL SYMBOL QUAD DEL;So;0;L;;;;;N;;;;; -2355;APL FUNCTIONAL SYMBOL UP TACK JOT;So;0;L;;;;;N;;*;;; -2356;APL FUNCTIONAL SYMBOL DOWNWARDS VANE;So;0;L;;;;;N;;;;; -2357;APL FUNCTIONAL SYMBOL QUAD DOWNWARDS ARROW;So;0;L;;;;;N;;;;; -2358;APL FUNCTIONAL SYMBOL QUOTE UNDERBAR;So;0;L;;;;;N;;;;; -2359;APL FUNCTIONAL SYMBOL DELTA UNDERBAR;So;0;L;;;;;N;;;;; -235A;APL FUNCTIONAL SYMBOL DIAMOND UNDERBAR;So;0;L;;;;;N;;;;; -235B;APL FUNCTIONAL SYMBOL JOT UNDERBAR;So;0;L;;;;;N;;;;; -235C;APL FUNCTIONAL SYMBOL CIRCLE UNDERBAR;So;0;L;;;;;N;;;;; -235D;APL FUNCTIONAL SYMBOL UP SHOE JOT;So;0;L;;;;;N;;;;; -235E;APL FUNCTIONAL SYMBOL QUOTE QUAD;So;0;L;;;;;N;;;;; -235F;APL FUNCTIONAL SYMBOL CIRCLE STAR;So;0;L;;;;;N;;;;; -2360;APL FUNCTIONAL SYMBOL QUAD COLON;So;0;L;;;;;N;;;;; -2361;APL FUNCTIONAL SYMBOL UP TACK DIAERESIS;So;0;L;;;;;N;;*;;; -2362;APL FUNCTIONAL SYMBOL DEL DIAERESIS;So;0;L;;;;;N;;;;; -2363;APL FUNCTIONAL SYMBOL STAR DIAERESIS;So;0;L;;;;;N;;;;; -2364;APL FUNCTIONAL SYMBOL JOT DIAERESIS;So;0;L;;;;;N;;;;; -2365;APL FUNCTIONAL SYMBOL CIRCLE DIAERESIS;So;0;L;;;;;N;;;;; -2366;APL FUNCTIONAL SYMBOL DOWN SHOE STILE;So;0;L;;;;;N;;;;; -2367;APL FUNCTIONAL SYMBOL LEFT SHOE STILE;So;0;L;;;;;N;;;;; -2368;APL FUNCTIONAL SYMBOL TILDE DIAERESIS;So;0;L;;;;;N;;;;; -2369;APL FUNCTIONAL SYMBOL GREATER-THAN DIAERESIS;So;0;L;;;;;N;;;;; -236A;APL FUNCTIONAL SYMBOL COMMA BAR;So;0;L;;;;;N;;;;; -236B;APL FUNCTIONAL SYMBOL DEL TILDE;So;0;L;;;;;N;;;;; -236C;APL FUNCTIONAL SYMBOL ZILDE;So;0;L;;;;;N;;;;; -236D;APL FUNCTIONAL SYMBOL STILE TILDE;So;0;L;;;;;N;;;;; -236E;APL FUNCTIONAL SYMBOL SEMICOLON UNDERBAR;So;0;L;;;;;N;;;;; -236F;APL FUNCTIONAL SYMBOL QUAD NOT EQUAL;So;0;L;;;;;N;;;;; -2370;APL FUNCTIONAL SYMBOL QUAD QUESTION;So;0;L;;;;;N;;;;; -2371;APL FUNCTIONAL SYMBOL DOWN CARET TILDE;So;0;L;;;;;N;;;;; -2372;APL FUNCTIONAL SYMBOL UP CARET TILDE;So;0;L;;;;;N;;;;; -2373;APL FUNCTIONAL SYMBOL IOTA;So;0;L;;;;;N;;;;; -2374;APL FUNCTIONAL SYMBOL RHO;So;0;L;;;;;N;;;;; -2375;APL FUNCTIONAL SYMBOL OMEGA;So;0;L;;;;;N;;;;; -2376;APL FUNCTIONAL SYMBOL ALPHA UNDERBAR;So;0;L;;;;;N;;;;; -2377;APL FUNCTIONAL SYMBOL EPSILON UNDERBAR;So;0;L;;;;;N;;;;; -2378;APL FUNCTIONAL SYMBOL IOTA UNDERBAR;So;0;L;;;;;N;;;;; -2379;APL FUNCTIONAL SYMBOL OMEGA UNDERBAR;So;0;L;;;;;N;;;;; -237A;APL FUNCTIONAL SYMBOL ALPHA;So;0;L;;;;;N;;;;; -237B;NOT CHECK MARK;So;0;ON;;;;;N;;;;; -237C;RIGHT ANGLE WITH DOWNWARDS ZIGZAG ARROW;Sm;0;ON;;;;;N;;;;; -237D;SHOULDERED OPEN BOX;So;0;ON;;;;;N;;;;; -237E;BELL SYMBOL;So;0;ON;;;;;N;;;;; -237F;VERTICAL LINE WITH MIDDLE DOT;So;0;ON;;;;;N;;;;; -2380;INSERTION SYMBOL;So;0;ON;;;;;N;;;;; -2381;CONTINUOUS UNDERLINE SYMBOL;So;0;ON;;;;;N;;;;; -2382;DISCONTINUOUS UNDERLINE SYMBOL;So;0;ON;;;;;N;;;;; -2383;EMPHASIS SYMBOL;So;0;ON;;;;;N;;;;; -2384;COMPOSITION SYMBOL;So;0;ON;;;;;N;;;;; -2385;WHITE SQUARE WITH CENTRE VERTICAL LINE;So;0;ON;;;;;N;;;;; -2386;ENTER SYMBOL;So;0;ON;;;;;N;;;;; -2387;ALTERNATIVE KEY SYMBOL;So;0;ON;;;;;N;;;;; -2388;HELM SYMBOL;So;0;ON;;;;;N;;;;; -2389;CIRCLED HORIZONTAL BAR WITH NOTCH;So;0;ON;;;;;N;;pause;;; -238A;CIRCLED TRIANGLE DOWN;So;0;ON;;;;;N;;break;;; -238B;BROKEN CIRCLE WITH NORTHWEST ARROW;So;0;ON;;;;;N;;escape;;; -238C;UNDO SYMBOL;So;0;ON;;;;;N;;;;; -238D;MONOSTABLE SYMBOL;So;0;ON;;;;;N;;;;; -238E;HYSTERESIS SYMBOL;So;0;ON;;;;;N;;;;; -238F;OPEN-CIRCUIT-OUTPUT H-TYPE SYMBOL;So;0;ON;;;;;N;;;;; -2390;OPEN-CIRCUIT-OUTPUT L-TYPE SYMBOL;So;0;ON;;;;;N;;;;; -2391;PASSIVE-PULL-DOWN-OUTPUT SYMBOL;So;0;ON;;;;;N;;;;; -2392;PASSIVE-PULL-UP-OUTPUT SYMBOL;So;0;ON;;;;;N;;;;; -2393;DIRECT CURRENT SYMBOL FORM TWO;So;0;ON;;;;;N;;;;; -2394;SOFTWARE-FUNCTION SYMBOL;So;0;ON;;;;;N;;;;; -2395;APL FUNCTIONAL SYMBOL QUAD;So;0;L;;;;;N;;;;; -2396;DECIMAL SEPARATOR KEY SYMBOL;So;0;ON;;;;;N;;;;; -2397;PREVIOUS PAGE;So;0;ON;;;;;N;;;;; -2398;NEXT PAGE;So;0;ON;;;;;N;;;;; -2399;PRINT SCREEN SYMBOL;So;0;ON;;;;;N;;;;; -239A;CLEAR SCREEN SYMBOL;So;0;ON;;;;;N;;;;; -239B;LEFT PARENTHESIS UPPER HOOK;Sm;0;ON;;;;;N;;;;; -239C;LEFT PARENTHESIS EXTENSION;Sm;0;ON;;;;;N;;;;; -239D;LEFT PARENTHESIS LOWER HOOK;Sm;0;ON;;;;;N;;;;; -239E;RIGHT PARENTHESIS UPPER HOOK;Sm;0;ON;;;;;N;;;;; -239F;RIGHT PARENTHESIS EXTENSION;Sm;0;ON;;;;;N;;;;; -23A0;RIGHT PARENTHESIS LOWER HOOK;Sm;0;ON;;;;;N;;;;; -23A1;LEFT SQUARE BRACKET UPPER CORNER;Sm;0;ON;;;;;N;;;;; -23A2;LEFT SQUARE BRACKET EXTENSION;Sm;0;ON;;;;;N;;;;; -23A3;LEFT SQUARE BRACKET LOWER CORNER;Sm;0;ON;;;;;N;;;;; -23A4;RIGHT SQUARE BRACKET UPPER CORNER;Sm;0;ON;;;;;N;;;;; -23A5;RIGHT SQUARE BRACKET EXTENSION;Sm;0;ON;;;;;N;;;;; -23A6;RIGHT SQUARE BRACKET LOWER CORNER;Sm;0;ON;;;;;N;;;;; -23A7;LEFT CURLY BRACKET UPPER HOOK;Sm;0;ON;;;;;N;;;;; -23A8;LEFT CURLY BRACKET MIDDLE PIECE;Sm;0;ON;;;;;N;;;;; -23A9;LEFT CURLY BRACKET LOWER HOOK;Sm;0;ON;;;;;N;;;;; -23AA;CURLY BRACKET EXTENSION;Sm;0;ON;;;;;N;;;;; -23AB;RIGHT CURLY BRACKET UPPER HOOK;Sm;0;ON;;;;;N;;;;; -23AC;RIGHT CURLY BRACKET MIDDLE PIECE;Sm;0;ON;;;;;N;;;;; -23AD;RIGHT CURLY BRACKET LOWER HOOK;Sm;0;ON;;;;;N;;;;; -23AE;INTEGRAL EXTENSION;Sm;0;ON;;;;;N;;;;; -23AF;HORIZONTAL LINE EXTENSION;Sm;0;ON;;;;;N;;;;; -23B0;UPPER LEFT OR LOWER RIGHT CURLY BRACKET SECTION;Sm;0;ON;;;;;N;;;;; -23B1;UPPER RIGHT OR LOWER LEFT CURLY BRACKET SECTION;Sm;0;ON;;;;;N;;;;; -23B2;SUMMATION TOP;Sm;0;ON;;;;;N;;;;; -23B3;SUMMATION BOTTOM;Sm;0;ON;;;;;N;;;;; -23B4;TOP SQUARE BRACKET;So;0;ON;;;;;N;;;;; -23B5;BOTTOM SQUARE BRACKET;So;0;ON;;;;;N;;;;; -23B6;BOTTOM SQUARE BRACKET OVER TOP SQUARE BRACKET;So;0;ON;;;;;N;;;;; -23B7;RADICAL SYMBOL BOTTOM;So;0;ON;;;;;N;;;;; -23B8;LEFT VERTICAL BOX LINE;So;0;ON;;;;;N;;;;; -23B9;RIGHT VERTICAL BOX LINE;So;0;ON;;;;;N;;;;; -23BA;HORIZONTAL SCAN LINE-1;So;0;ON;;;;;N;;;;; -23BB;HORIZONTAL SCAN LINE-3;So;0;ON;;;;;N;;;;; -23BC;HORIZONTAL SCAN LINE-7;So;0;ON;;;;;N;;;;; -23BD;HORIZONTAL SCAN LINE-9;So;0;ON;;;;;N;;;;; -23BE;DENTISTRY SYMBOL LIGHT VERTICAL AND TOP RIGHT;So;0;ON;;;;;N;;;;; -23BF;DENTISTRY SYMBOL LIGHT VERTICAL AND BOTTOM RIGHT;So;0;ON;;;;;N;;;;; -23C0;DENTISTRY SYMBOL LIGHT VERTICAL WITH CIRCLE;So;0;ON;;;;;N;;;;; -23C1;DENTISTRY SYMBOL LIGHT DOWN AND HORIZONTAL WITH CIRCLE;So;0;ON;;;;;N;;;;; -23C2;DENTISTRY SYMBOL LIGHT UP AND HORIZONTAL WITH CIRCLE;So;0;ON;;;;;N;;;;; -23C3;DENTISTRY SYMBOL LIGHT VERTICAL WITH TRIANGLE;So;0;ON;;;;;N;;;;; -23C4;DENTISTRY SYMBOL LIGHT DOWN AND HORIZONTAL WITH TRIANGLE;So;0;ON;;;;;N;;;;; -23C5;DENTISTRY SYMBOL LIGHT UP AND HORIZONTAL WITH TRIANGLE;So;0;ON;;;;;N;;;;; -23C6;DENTISTRY SYMBOL LIGHT VERTICAL AND WAVE;So;0;ON;;;;;N;;;;; -23C7;DENTISTRY SYMBOL LIGHT DOWN AND HORIZONTAL WITH WAVE;So;0;ON;;;;;N;;;;; -23C8;DENTISTRY SYMBOL LIGHT UP AND HORIZONTAL WITH WAVE;So;0;ON;;;;;N;;;;; -23C9;DENTISTRY SYMBOL LIGHT DOWN AND HORIZONTAL;So;0;ON;;;;;N;;;;; -23CA;DENTISTRY SYMBOL LIGHT UP AND HORIZONTAL;So;0;ON;;;;;N;;;;; -23CB;DENTISTRY SYMBOL LIGHT VERTICAL AND TOP LEFT;So;0;ON;;;;;N;;;;; -23CC;DENTISTRY SYMBOL LIGHT VERTICAL AND BOTTOM LEFT;So;0;ON;;;;;N;;;;; -23CD;SQUARE FOOT;So;0;ON;;;;;N;;;;; -23CE;RETURN SYMBOL;So;0;ON;;;;;N;;;;; -23CF;EJECT SYMBOL;So;0;ON;;;;;N;;;;; -23D0;VERTICAL LINE EXTENSION;So;0;ON;;;;;N;;;;; -23D1;METRICAL BREVE;So;0;ON;;;;;N;;;;; -23D2;METRICAL LONG OVER SHORT;So;0;ON;;;;;N;;;;; -23D3;METRICAL SHORT OVER LONG;So;0;ON;;;;;N;;;;; -23D4;METRICAL LONG OVER TWO SHORTS;So;0;ON;;;;;N;;;;; -23D5;METRICAL TWO SHORTS OVER LONG;So;0;ON;;;;;N;;;;; -23D6;METRICAL TWO SHORTS JOINED;So;0;ON;;;;;N;;;;; -23D7;METRICAL TRISEME;So;0;ON;;;;;N;;;;; -23D8;METRICAL TETRASEME;So;0;ON;;;;;N;;;;; -23D9;METRICAL PENTASEME;So;0;ON;;;;;N;;;;; -23DA;EARTH GROUND;So;0;ON;;;;;N;;;;; -23DB;FUSE;So;0;ON;;;;;N;;;;; -23DC;TOP PARENTHESIS;Sm;0;ON;;;;;N;;mathematical use;;; -23DD;BOTTOM PARENTHESIS;Sm;0;ON;;;;;N;;mathematical use;;; -23DE;TOP CURLY BRACKET;Sm;0;ON;;;;;N;;mathematical use;;; -23DF;BOTTOM CURLY BRACKET;Sm;0;ON;;;;;N;;mathematical use;;; -23E0;TOP TORTOISE SHELL BRACKET;Sm;0;ON;;;;;N;;mathematical use;;; -23E1;BOTTOM TORTOISE SHELL BRACKET;Sm;0;ON;;;;;N;;mathematical use;;; -23E2;WHITE TRAPEZIUM;So;0;ON;;;;;N;;;;; -23E3;BENZENE RING WITH CIRCLE;So;0;ON;;;;;N;;;;; -23E4;STRAIGHTNESS;So;0;ON;;;;;N;;;;; -23E5;FLATNESS;So;0;ON;;;;;N;;;;; -23E6;AC CURRENT;So;0;ON;;;;;N;;;;; -23E7;ELECTRICAL INTERSECTION;So;0;ON;;;;;N;;;;; -2400;SYMBOL FOR NULL;So;0;ON;;;;;N;GRAPHIC FOR NULL;;;; -2401;SYMBOL FOR START OF HEADING;So;0;ON;;;;;N;GRAPHIC FOR START OF HEADING;;;; -2402;SYMBOL FOR START OF TEXT;So;0;ON;;;;;N;GRAPHIC FOR START OF TEXT;;;; -2403;SYMBOL FOR END OF TEXT;So;0;ON;;;;;N;GRAPHIC FOR END OF TEXT;;;; -2404;SYMBOL FOR END OF TRANSMISSION;So;0;ON;;;;;N;GRAPHIC FOR END OF TRANSMISSION;;;; -2405;SYMBOL FOR ENQUIRY;So;0;ON;;;;;N;GRAPHIC FOR ENQUIRY;;;; -2406;SYMBOL FOR ACKNOWLEDGE;So;0;ON;;;;;N;GRAPHIC FOR ACKNOWLEDGE;;;; -2407;SYMBOL FOR BELL;So;0;ON;;;;;N;GRAPHIC FOR BELL;;;; -2408;SYMBOL FOR BACKSPACE;So;0;ON;;;;;N;GRAPHIC FOR BACKSPACE;;;; -2409;SYMBOL FOR HORIZONTAL TABULATION;So;0;ON;;;;;N;GRAPHIC FOR HORIZONTAL TABULATION;;;; -240A;SYMBOL FOR LINE FEED;So;0;ON;;;;;N;GRAPHIC FOR LINE FEED;;;; -240B;SYMBOL FOR VERTICAL TABULATION;So;0;ON;;;;;N;GRAPHIC FOR VERTICAL TABULATION;;;; -240C;SYMBOL FOR FORM FEED;So;0;ON;;;;;N;GRAPHIC FOR FORM FEED;;;; -240D;SYMBOL FOR CARRIAGE RETURN;So;0;ON;;;;;N;GRAPHIC FOR CARRIAGE RETURN;;;; -240E;SYMBOL FOR SHIFT OUT;So;0;ON;;;;;N;GRAPHIC FOR SHIFT OUT;;;; -240F;SYMBOL FOR SHIFT IN;So;0;ON;;;;;N;GRAPHIC FOR SHIFT IN;;;; -2410;SYMBOL FOR DATA LINK ESCAPE;So;0;ON;;;;;N;GRAPHIC FOR DATA LINK ESCAPE;;;; -2411;SYMBOL FOR DEVICE CONTROL ONE;So;0;ON;;;;;N;GRAPHIC FOR DEVICE CONTROL ONE;;;; -2412;SYMBOL FOR DEVICE CONTROL TWO;So;0;ON;;;;;N;GRAPHIC FOR DEVICE CONTROL TWO;;;; -2413;SYMBOL FOR DEVICE CONTROL THREE;So;0;ON;;;;;N;GRAPHIC FOR DEVICE CONTROL THREE;;;; -2414;SYMBOL FOR DEVICE CONTROL FOUR;So;0;ON;;;;;N;GRAPHIC FOR DEVICE CONTROL FOUR;;;; -2415;SYMBOL FOR NEGATIVE ACKNOWLEDGE;So;0;ON;;;;;N;GRAPHIC FOR NEGATIVE ACKNOWLEDGE;;;; -2416;SYMBOL FOR SYNCHRONOUS IDLE;So;0;ON;;;;;N;GRAPHIC FOR SYNCHRONOUS IDLE;;;; -2417;SYMBOL FOR END OF TRANSMISSION BLOCK;So;0;ON;;;;;N;GRAPHIC FOR END OF TRANSMISSION BLOCK;;;; -2418;SYMBOL FOR CANCEL;So;0;ON;;;;;N;GRAPHIC FOR CANCEL;;;; -2419;SYMBOL FOR END OF MEDIUM;So;0;ON;;;;;N;GRAPHIC FOR END OF MEDIUM;;;; -241A;SYMBOL FOR SUBSTITUTE;So;0;ON;;;;;N;GRAPHIC FOR SUBSTITUTE;;;; -241B;SYMBOL FOR ESCAPE;So;0;ON;;;;;N;GRAPHIC FOR ESCAPE;;;; -241C;SYMBOL FOR FILE SEPARATOR;So;0;ON;;;;;N;GRAPHIC FOR FILE SEPARATOR;;;; -241D;SYMBOL FOR GROUP SEPARATOR;So;0;ON;;;;;N;GRAPHIC FOR GROUP SEPARATOR;;;; -241E;SYMBOL FOR RECORD SEPARATOR;So;0;ON;;;;;N;GRAPHIC FOR RECORD SEPARATOR;;;; -241F;SYMBOL FOR UNIT SEPARATOR;So;0;ON;;;;;N;GRAPHIC FOR UNIT SEPARATOR;;;; -2420;SYMBOL FOR SPACE;So;0;ON;;;;;N;GRAPHIC FOR SPACE;;;; -2421;SYMBOL FOR DELETE;So;0;ON;;;;;N;GRAPHIC FOR DELETE;;;; -2422;BLANK SYMBOL;So;0;ON;;;;;N;BLANK;;;; -2423;OPEN BOX;So;0;ON;;;;;N;;;;; -2424;SYMBOL FOR NEWLINE;So;0;ON;;;;;N;GRAPHIC FOR NEWLINE;;;; -2425;SYMBOL FOR DELETE FORM TWO;So;0;ON;;;;;N;;;;; -2426;SYMBOL FOR SUBSTITUTE FORM TWO;So;0;ON;;;;;N;;;;; -2440;OCR HOOK;So;0;ON;;;;;N;;;;; -2441;OCR CHAIR;So;0;ON;;;;;N;;;;; -2442;OCR FORK;So;0;ON;;;;;N;;;;; -2443;OCR INVERTED FORK;So;0;ON;;;;;N;;;;; -2444;OCR BELT BUCKLE;So;0;ON;;;;;N;;;;; -2445;OCR BOW TIE;So;0;ON;;;;;N;;;;; -2446;OCR BRANCH BANK IDENTIFICATION;So;0;ON;;;;;N;;;;; -2447;OCR AMOUNT OF CHECK;So;0;ON;;;;;N;;;;; -2448;OCR DASH;So;0;ON;;;;;N;;;;; -2449;OCR CUSTOMER ACCOUNT NUMBER;So;0;ON;;;;;N;;;;; -244A;OCR DOUBLE BACKSLASH;So;0;ON;;;;;N;;;;; -2460;CIRCLED DIGIT ONE;No;0;ON; 0031;;1;1;N;;;;; -2461;CIRCLED DIGIT TWO;No;0;ON; 0032;;2;2;N;;;;; -2462;CIRCLED DIGIT THREE;No;0;ON; 0033;;3;3;N;;;;; -2463;CIRCLED DIGIT FOUR;No;0;ON; 0034;;4;4;N;;;;; -2464;CIRCLED DIGIT FIVE;No;0;ON; 0035;;5;5;N;;;;; -2465;CIRCLED DIGIT SIX;No;0;ON; 0036;;6;6;N;;;;; -2466;CIRCLED DIGIT SEVEN;No;0;ON; 0037;;7;7;N;;;;; -2467;CIRCLED DIGIT EIGHT;No;0;ON; 0038;;8;8;N;;;;; -2468;CIRCLED DIGIT NINE;No;0;ON; 0039;;9;9;N;;;;; -2469;CIRCLED NUMBER TEN;No;0;ON; 0031 0030;;;10;N;;;;; -246A;CIRCLED NUMBER ELEVEN;No;0;ON; 0031 0031;;;11;N;;;;; -246B;CIRCLED NUMBER TWELVE;No;0;ON; 0031 0032;;;12;N;;;;; -246C;CIRCLED NUMBER THIRTEEN;No;0;ON; 0031 0033;;;13;N;;;;; -246D;CIRCLED NUMBER FOURTEEN;No;0;ON; 0031 0034;;;14;N;;;;; -246E;CIRCLED NUMBER FIFTEEN;No;0;ON; 0031 0035;;;15;N;;;;; -246F;CIRCLED NUMBER SIXTEEN;No;0;ON; 0031 0036;;;16;N;;;;; -2470;CIRCLED NUMBER SEVENTEEN;No;0;ON; 0031 0037;;;17;N;;;;; -2471;CIRCLED NUMBER EIGHTEEN;No;0;ON; 0031 0038;;;18;N;;;;; -2472;CIRCLED NUMBER NINETEEN;No;0;ON; 0031 0039;;;19;N;;;;; -2473;CIRCLED NUMBER TWENTY;No;0;ON; 0032 0030;;;20;N;;;;; -2474;PARENTHESIZED DIGIT ONE;No;0;ON; 0028 0031 0029;;1;1;N;;;;; -2475;PARENTHESIZED DIGIT TWO;No;0;ON; 0028 0032 0029;;2;2;N;;;;; -2476;PARENTHESIZED DIGIT THREE;No;0;ON; 0028 0033 0029;;3;3;N;;;;; -2477;PARENTHESIZED DIGIT FOUR;No;0;ON; 0028 0034 0029;;4;4;N;;;;; -2478;PARENTHESIZED DIGIT FIVE;No;0;ON; 0028 0035 0029;;5;5;N;;;;; -2479;PARENTHESIZED DIGIT SIX;No;0;ON; 0028 0036 0029;;6;6;N;;;;; -247A;PARENTHESIZED DIGIT SEVEN;No;0;ON; 0028 0037 0029;;7;7;N;;;;; -247B;PARENTHESIZED DIGIT EIGHT;No;0;ON; 0028 0038 0029;;8;8;N;;;;; -247C;PARENTHESIZED DIGIT NINE;No;0;ON; 0028 0039 0029;;9;9;N;;;;; -247D;PARENTHESIZED NUMBER TEN;No;0;ON; 0028 0031 0030 0029;;;10;N;;;;; -247E;PARENTHESIZED NUMBER ELEVEN;No;0;ON; 0028 0031 0031 0029;;;11;N;;;;; -247F;PARENTHESIZED NUMBER TWELVE;No;0;ON; 0028 0031 0032 0029;;;12;N;;;;; -2480;PARENTHESIZED NUMBER THIRTEEN;No;0;ON; 0028 0031 0033 0029;;;13;N;;;;; -2481;PARENTHESIZED NUMBER FOURTEEN;No;0;ON; 0028 0031 0034 0029;;;14;N;;;;; -2482;PARENTHESIZED NUMBER FIFTEEN;No;0;ON; 0028 0031 0035 0029;;;15;N;;;;; -2483;PARENTHESIZED NUMBER SIXTEEN;No;0;ON; 0028 0031 0036 0029;;;16;N;;;;; -2484;PARENTHESIZED NUMBER SEVENTEEN;No;0;ON; 0028 0031 0037 0029;;;17;N;;;;; -2485;PARENTHESIZED NUMBER EIGHTEEN;No;0;ON; 0028 0031 0038 0029;;;18;N;;;;; -2486;PARENTHESIZED NUMBER NINETEEN;No;0;ON; 0028 0031 0039 0029;;;19;N;;;;; -2487;PARENTHESIZED NUMBER TWENTY;No;0;ON; 0028 0032 0030 0029;;;20;N;;;;; -2488;DIGIT ONE FULL STOP;No;0;EN; 0031 002E;;1;1;N;DIGIT ONE PERIOD;;;; -2489;DIGIT TWO FULL STOP;No;0;EN; 0032 002E;;2;2;N;DIGIT TWO PERIOD;;;; -248A;DIGIT THREE FULL STOP;No;0;EN; 0033 002E;;3;3;N;DIGIT THREE PERIOD;;;; -248B;DIGIT FOUR FULL STOP;No;0;EN; 0034 002E;;4;4;N;DIGIT FOUR PERIOD;;;; -248C;DIGIT FIVE FULL STOP;No;0;EN; 0035 002E;;5;5;N;DIGIT FIVE PERIOD;;;; -248D;DIGIT SIX FULL STOP;No;0;EN; 0036 002E;;6;6;N;DIGIT SIX PERIOD;;;; -248E;DIGIT SEVEN FULL STOP;No;0;EN; 0037 002E;;7;7;N;DIGIT SEVEN PERIOD;;;; -248F;DIGIT EIGHT FULL STOP;No;0;EN; 0038 002E;;8;8;N;DIGIT EIGHT PERIOD;;;; -2490;DIGIT NINE FULL STOP;No;0;EN; 0039 002E;;9;9;N;DIGIT NINE PERIOD;;;; -2491;NUMBER TEN FULL STOP;No;0;EN; 0031 0030 002E;;;10;N;NUMBER TEN PERIOD;;;; -2492;NUMBER ELEVEN FULL STOP;No;0;EN; 0031 0031 002E;;;11;N;NUMBER ELEVEN PERIOD;;;; -2493;NUMBER TWELVE FULL STOP;No;0;EN; 0031 0032 002E;;;12;N;NUMBER TWELVE PERIOD;;;; -2494;NUMBER THIRTEEN FULL STOP;No;0;EN; 0031 0033 002E;;;13;N;NUMBER THIRTEEN PERIOD;;;; -2495;NUMBER FOURTEEN FULL STOP;No;0;EN; 0031 0034 002E;;;14;N;NUMBER FOURTEEN PERIOD;;;; -2496;NUMBER FIFTEEN FULL STOP;No;0;EN; 0031 0035 002E;;;15;N;NUMBER FIFTEEN PERIOD;;;; -2497;NUMBER SIXTEEN FULL STOP;No;0;EN; 0031 0036 002E;;;16;N;NUMBER SIXTEEN PERIOD;;;; -2498;NUMBER SEVENTEEN FULL STOP;No;0;EN; 0031 0037 002E;;;17;N;NUMBER SEVENTEEN PERIOD;;;; -2499;NUMBER EIGHTEEN FULL STOP;No;0;EN; 0031 0038 002E;;;18;N;NUMBER EIGHTEEN PERIOD;;;; -249A;NUMBER NINETEEN FULL STOP;No;0;EN; 0031 0039 002E;;;19;N;NUMBER NINETEEN PERIOD;;;; -249B;NUMBER TWENTY FULL STOP;No;0;EN; 0032 0030 002E;;;20;N;NUMBER TWENTY PERIOD;;;; -249C;PARENTHESIZED LATIN SMALL LETTER A;So;0;L; 0028 0061 0029;;;;N;;;;; -249D;PARENTHESIZED LATIN SMALL LETTER B;So;0;L; 0028 0062 0029;;;;N;;;;; -249E;PARENTHESIZED LATIN SMALL LETTER C;So;0;L; 0028 0063 0029;;;;N;;;;; -249F;PARENTHESIZED LATIN SMALL LETTER D;So;0;L; 0028 0064 0029;;;;N;;;;; -24A0;PARENTHESIZED LATIN SMALL LETTER E;So;0;L; 0028 0065 0029;;;;N;;;;; -24A1;PARENTHESIZED LATIN SMALL LETTER F;So;0;L; 0028 0066 0029;;;;N;;;;; -24A2;PARENTHESIZED LATIN SMALL LETTER G;So;0;L; 0028 0067 0029;;;;N;;;;; -24A3;PARENTHESIZED LATIN SMALL LETTER H;So;0;L; 0028 0068 0029;;;;N;;;;; -24A4;PARENTHESIZED LATIN SMALL LETTER I;So;0;L; 0028 0069 0029;;;;N;;;;; -24A5;PARENTHESIZED LATIN SMALL LETTER J;So;0;L; 0028 006A 0029;;;;N;;;;; -24A6;PARENTHESIZED LATIN SMALL LETTER K;So;0;L; 0028 006B 0029;;;;N;;;;; -24A7;PARENTHESIZED LATIN SMALL LETTER L;So;0;L; 0028 006C 0029;;;;N;;;;; -24A8;PARENTHESIZED LATIN SMALL LETTER M;So;0;L; 0028 006D 0029;;;;N;;;;; -24A9;PARENTHESIZED LATIN SMALL LETTER N;So;0;L; 0028 006E 0029;;;;N;;;;; -24AA;PARENTHESIZED LATIN SMALL LETTER O;So;0;L; 0028 006F 0029;;;;N;;;;; -24AB;PARENTHESIZED LATIN SMALL LETTER P;So;0;L; 0028 0070 0029;;;;N;;;;; -24AC;PARENTHESIZED LATIN SMALL LETTER Q;So;0;L; 0028 0071 0029;;;;N;;;;; -24AD;PARENTHESIZED LATIN SMALL LETTER R;So;0;L; 0028 0072 0029;;;;N;;;;; -24AE;PARENTHESIZED LATIN SMALL LETTER S;So;0;L; 0028 0073 0029;;;;N;;;;; -24AF;PARENTHESIZED LATIN SMALL LETTER T;So;0;L; 0028 0074 0029;;;;N;;;;; -24B0;PARENTHESIZED LATIN SMALL LETTER U;So;0;L; 0028 0075 0029;;;;N;;;;; -24B1;PARENTHESIZED LATIN SMALL LETTER V;So;0;L; 0028 0076 0029;;;;N;;;;; -24B2;PARENTHESIZED LATIN SMALL LETTER W;So;0;L; 0028 0077 0029;;;;N;;;;; -24B3;PARENTHESIZED LATIN SMALL LETTER X;So;0;L; 0028 0078 0029;;;;N;;;;; -24B4;PARENTHESIZED LATIN SMALL LETTER Y;So;0;L; 0028 0079 0029;;;;N;;;;; -24B5;PARENTHESIZED LATIN SMALL LETTER Z;So;0;L; 0028 007A 0029;;;;N;;;;; -24B6;CIRCLED LATIN CAPITAL LETTER A;So;0;L; 0041;;;;N;;;;24D0; -24B7;CIRCLED LATIN CAPITAL LETTER B;So;0;L; 0042;;;;N;;;;24D1; -24B8;CIRCLED LATIN CAPITAL LETTER C;So;0;L; 0043;;;;N;;;;24D2; -24B9;CIRCLED LATIN CAPITAL LETTER D;So;0;L; 0044;;;;N;;;;24D3; -24BA;CIRCLED LATIN CAPITAL LETTER E;So;0;L; 0045;;;;N;;;;24D4; -24BB;CIRCLED LATIN CAPITAL LETTER F;So;0;L; 0046;;;;N;;;;24D5; -24BC;CIRCLED LATIN CAPITAL LETTER G;So;0;L; 0047;;;;N;;;;24D6; -24BD;CIRCLED LATIN CAPITAL LETTER H;So;0;L; 0048;;;;N;;;;24D7; -24BE;CIRCLED LATIN CAPITAL LETTER I;So;0;L; 0049;;;;N;;;;24D8; -24BF;CIRCLED LATIN CAPITAL LETTER J;So;0;L; 004A;;;;N;;;;24D9; -24C0;CIRCLED LATIN CAPITAL LETTER K;So;0;L; 004B;;;;N;;;;24DA; -24C1;CIRCLED LATIN CAPITAL LETTER L;So;0;L; 004C;;;;N;;;;24DB; -24C2;CIRCLED LATIN CAPITAL LETTER M;So;0;L; 004D;;;;N;;;;24DC; -24C3;CIRCLED LATIN CAPITAL LETTER N;So;0;L; 004E;;;;N;;;;24DD; -24C4;CIRCLED LATIN CAPITAL LETTER O;So;0;L; 004F;;;;N;;;;24DE; -24C5;CIRCLED LATIN CAPITAL LETTER P;So;0;L; 0050;;;;N;;;;24DF; -24C6;CIRCLED LATIN CAPITAL LETTER Q;So;0;L; 0051;;;;N;;;;24E0; -24C7;CIRCLED LATIN CAPITAL LETTER R;So;0;L; 0052;;;;N;;;;24E1; -24C8;CIRCLED LATIN CAPITAL LETTER S;So;0;L; 0053;;;;N;;;;24E2; -24C9;CIRCLED LATIN CAPITAL LETTER T;So;0;L; 0054;;;;N;;;;24E3; -24CA;CIRCLED LATIN CAPITAL LETTER U;So;0;L; 0055;;;;N;;;;24E4; -24CB;CIRCLED LATIN CAPITAL LETTER V;So;0;L; 0056;;;;N;;;;24E5; -24CC;CIRCLED LATIN CAPITAL LETTER W;So;0;L; 0057;;;;N;;;;24E6; -24CD;CIRCLED LATIN CAPITAL LETTER X;So;0;L; 0058;;;;N;;;;24E7; -24CE;CIRCLED LATIN CAPITAL LETTER Y;So;0;L; 0059;;;;N;;;;24E8; -24CF;CIRCLED LATIN CAPITAL LETTER Z;So;0;L; 005A;;;;N;;;;24E9; -24D0;CIRCLED LATIN SMALL LETTER A;So;0;L; 0061;;;;N;;;24B6;;24B6 -24D1;CIRCLED LATIN SMALL LETTER B;So;0;L; 0062;;;;N;;;24B7;;24B7 -24D2;CIRCLED LATIN SMALL LETTER C;So;0;L; 0063;;;;N;;;24B8;;24B8 -24D3;CIRCLED LATIN SMALL LETTER D;So;0;L; 0064;;;;N;;;24B9;;24B9 -24D4;CIRCLED LATIN SMALL LETTER E;So;0;L; 0065;;;;N;;;24BA;;24BA -24D5;CIRCLED LATIN SMALL LETTER F;So;0;L; 0066;;;;N;;;24BB;;24BB -24D6;CIRCLED LATIN SMALL LETTER G;So;0;L; 0067;;;;N;;;24BC;;24BC -24D7;CIRCLED LATIN SMALL LETTER H;So;0;L; 0068;;;;N;;;24BD;;24BD -24D8;CIRCLED LATIN SMALL LETTER I;So;0;L; 0069;;;;N;;;24BE;;24BE -24D9;CIRCLED LATIN SMALL LETTER J;So;0;L; 006A;;;;N;;;24BF;;24BF -24DA;CIRCLED LATIN SMALL LETTER K;So;0;L; 006B;;;;N;;;24C0;;24C0 -24DB;CIRCLED LATIN SMALL LETTER L;So;0;L; 006C;;;;N;;;24C1;;24C1 -24DC;CIRCLED LATIN SMALL LETTER M;So;0;L; 006D;;;;N;;;24C2;;24C2 -24DD;CIRCLED LATIN SMALL LETTER N;So;0;L; 006E;;;;N;;;24C3;;24C3 -24DE;CIRCLED LATIN SMALL LETTER O;So;0;L; 006F;;;;N;;;24C4;;24C4 -24DF;CIRCLED LATIN SMALL LETTER P;So;0;L; 0070;;;;N;;;24C5;;24C5 -24E0;CIRCLED LATIN SMALL LETTER Q;So;0;L; 0071;;;;N;;;24C6;;24C6 -24E1;CIRCLED LATIN SMALL LETTER R;So;0;L; 0072;;;;N;;;24C7;;24C7 -24E2;CIRCLED LATIN SMALL LETTER S;So;0;L; 0073;;;;N;;;24C8;;24C8 -24E3;CIRCLED LATIN SMALL LETTER T;So;0;L; 0074;;;;N;;;24C9;;24C9 -24E4;CIRCLED LATIN SMALL LETTER U;So;0;L; 0075;;;;N;;;24CA;;24CA -24E5;CIRCLED LATIN SMALL LETTER V;So;0;L; 0076;;;;N;;;24CB;;24CB -24E6;CIRCLED LATIN SMALL LETTER W;So;0;L; 0077;;;;N;;;24CC;;24CC -24E7;CIRCLED LATIN SMALL LETTER X;So;0;L; 0078;;;;N;;;24CD;;24CD -24E8;CIRCLED LATIN SMALL LETTER Y;So;0;L; 0079;;;;N;;;24CE;;24CE -24E9;CIRCLED LATIN SMALL LETTER Z;So;0;L; 007A;;;;N;;;24CF;;24CF -24EA;CIRCLED DIGIT ZERO;No;0;ON; 0030;;0;0;N;;;;; -24EB;NEGATIVE CIRCLED NUMBER ELEVEN;No;0;ON;;;;11;N;;;;; -24EC;NEGATIVE CIRCLED NUMBER TWELVE;No;0;ON;;;;12;N;;;;; -24ED;NEGATIVE CIRCLED NUMBER THIRTEEN;No;0;ON;;;;13;N;;;;; -24EE;NEGATIVE CIRCLED NUMBER FOURTEEN;No;0;ON;;;;14;N;;;;; -24EF;NEGATIVE CIRCLED NUMBER FIFTEEN;No;0;ON;;;;15;N;;;;; -24F0;NEGATIVE CIRCLED NUMBER SIXTEEN;No;0;ON;;;;16;N;;;;; -24F1;NEGATIVE CIRCLED NUMBER SEVENTEEN;No;0;ON;;;;17;N;;;;; -24F2;NEGATIVE CIRCLED NUMBER EIGHTEEN;No;0;ON;;;;18;N;;;;; -24F3;NEGATIVE CIRCLED NUMBER NINETEEN;No;0;ON;;;;19;N;;;;; -24F4;NEGATIVE CIRCLED NUMBER TWENTY;No;0;ON;;;;20;N;;;;; -24F5;DOUBLE CIRCLED DIGIT ONE;No;0;ON;;;1;1;N;;;;; -24F6;DOUBLE CIRCLED DIGIT TWO;No;0;ON;;;2;2;N;;;;; -24F7;DOUBLE CIRCLED DIGIT THREE;No;0;ON;;;3;3;N;;;;; -24F8;DOUBLE CIRCLED DIGIT FOUR;No;0;ON;;;4;4;N;;;;; -24F9;DOUBLE CIRCLED DIGIT FIVE;No;0;ON;;;5;5;N;;;;; -24FA;DOUBLE CIRCLED DIGIT SIX;No;0;ON;;;6;6;N;;;;; -24FB;DOUBLE CIRCLED DIGIT SEVEN;No;0;ON;;;7;7;N;;;;; -24FC;DOUBLE CIRCLED DIGIT EIGHT;No;0;ON;;;8;8;N;;;;; -24FD;DOUBLE CIRCLED DIGIT NINE;No;0;ON;;;9;9;N;;;;; -24FE;DOUBLE CIRCLED NUMBER TEN;No;0;ON;;;;10;N;;;;; -24FF;NEGATIVE CIRCLED DIGIT ZERO;No;0;ON;;;0;0;N;;;;; -2500;BOX DRAWINGS LIGHT HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT HORIZONTAL;;;; -2501;BOX DRAWINGS HEAVY HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY HORIZONTAL;;;; -2502;BOX DRAWINGS LIGHT VERTICAL;So;0;ON;;;;;N;FORMS LIGHT VERTICAL;;;; -2503;BOX DRAWINGS HEAVY VERTICAL;So;0;ON;;;;;N;FORMS HEAVY VERTICAL;;;; -2504;BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT TRIPLE DASH HORIZONTAL;;;; -2505;BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY TRIPLE DASH HORIZONTAL;;;; -2506;BOX DRAWINGS LIGHT TRIPLE DASH VERTICAL;So;0;ON;;;;;N;FORMS LIGHT TRIPLE DASH VERTICAL;;;; -2507;BOX DRAWINGS HEAVY TRIPLE DASH VERTICAL;So;0;ON;;;;;N;FORMS HEAVY TRIPLE DASH VERTICAL;;;; -2508;BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT QUADRUPLE DASH HORIZONTAL;;;; -2509;BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY QUADRUPLE DASH HORIZONTAL;;;; -250A;BOX DRAWINGS LIGHT QUADRUPLE DASH VERTICAL;So;0;ON;;;;;N;FORMS LIGHT QUADRUPLE DASH VERTICAL;;;; -250B;BOX DRAWINGS HEAVY QUADRUPLE DASH VERTICAL;So;0;ON;;;;;N;FORMS HEAVY QUADRUPLE DASH VERTICAL;;;; -250C;BOX DRAWINGS LIGHT DOWN AND RIGHT;So;0;ON;;;;;N;FORMS LIGHT DOWN AND RIGHT;;;; -250D;BOX DRAWINGS DOWN LIGHT AND RIGHT HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND RIGHT HEAVY;;;; -250E;BOX DRAWINGS DOWN HEAVY AND RIGHT LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND RIGHT LIGHT;;;; -250F;BOX DRAWINGS HEAVY DOWN AND RIGHT;So;0;ON;;;;;N;FORMS HEAVY DOWN AND RIGHT;;;; -2510;BOX DRAWINGS LIGHT DOWN AND LEFT;So;0;ON;;;;;N;FORMS LIGHT DOWN AND LEFT;;;; -2511;BOX DRAWINGS DOWN LIGHT AND LEFT HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND LEFT HEAVY;;;; -2512;BOX DRAWINGS DOWN HEAVY AND LEFT LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND LEFT LIGHT;;;; -2513;BOX DRAWINGS HEAVY DOWN AND LEFT;So;0;ON;;;;;N;FORMS HEAVY DOWN AND LEFT;;;; -2514;BOX DRAWINGS LIGHT UP AND RIGHT;So;0;ON;;;;;N;FORMS LIGHT UP AND RIGHT;;;; -2515;BOX DRAWINGS UP LIGHT AND RIGHT HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND RIGHT HEAVY;;;; -2516;BOX DRAWINGS UP HEAVY AND RIGHT LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND RIGHT LIGHT;;;; -2517;BOX DRAWINGS HEAVY UP AND RIGHT;So;0;ON;;;;;N;FORMS HEAVY UP AND RIGHT;;;; -2518;BOX DRAWINGS LIGHT UP AND LEFT;So;0;ON;;;;;N;FORMS LIGHT UP AND LEFT;;;; -2519;BOX DRAWINGS UP LIGHT AND LEFT HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND LEFT HEAVY;;;; -251A;BOX DRAWINGS UP HEAVY AND LEFT LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND LEFT LIGHT;;;; -251B;BOX DRAWINGS HEAVY UP AND LEFT;So;0;ON;;;;;N;FORMS HEAVY UP AND LEFT;;;; -251C;BOX DRAWINGS LIGHT VERTICAL AND RIGHT;So;0;ON;;;;;N;FORMS LIGHT VERTICAL AND RIGHT;;;; -251D;BOX DRAWINGS VERTICAL LIGHT AND RIGHT HEAVY;So;0;ON;;;;;N;FORMS VERTICAL LIGHT AND RIGHT HEAVY;;;; -251E;BOX DRAWINGS UP HEAVY AND RIGHT DOWN LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND RIGHT DOWN LIGHT;;;; -251F;BOX DRAWINGS DOWN HEAVY AND RIGHT UP LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND RIGHT UP LIGHT;;;; -2520;BOX DRAWINGS VERTICAL HEAVY AND RIGHT LIGHT;So;0;ON;;;;;N;FORMS VERTICAL HEAVY AND RIGHT LIGHT;;;; -2521;BOX DRAWINGS DOWN LIGHT AND RIGHT UP HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND RIGHT UP HEAVY;;;; -2522;BOX DRAWINGS UP LIGHT AND RIGHT DOWN HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND RIGHT DOWN HEAVY;;;; -2523;BOX DRAWINGS HEAVY VERTICAL AND RIGHT;So;0;ON;;;;;N;FORMS HEAVY VERTICAL AND RIGHT;;;; -2524;BOX DRAWINGS LIGHT VERTICAL AND LEFT;So;0;ON;;;;;N;FORMS LIGHT VERTICAL AND LEFT;;;; -2525;BOX DRAWINGS VERTICAL LIGHT AND LEFT HEAVY;So;0;ON;;;;;N;FORMS VERTICAL LIGHT AND LEFT HEAVY;;;; -2526;BOX DRAWINGS UP HEAVY AND LEFT DOWN LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND LEFT DOWN LIGHT;;;; -2527;BOX DRAWINGS DOWN HEAVY AND LEFT UP LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND LEFT UP LIGHT;;;; -2528;BOX DRAWINGS VERTICAL HEAVY AND LEFT LIGHT;So;0;ON;;;;;N;FORMS VERTICAL HEAVY AND LEFT LIGHT;;;; -2529;BOX DRAWINGS DOWN LIGHT AND LEFT UP HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND LEFT UP HEAVY;;;; -252A;BOX DRAWINGS UP LIGHT AND LEFT DOWN HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND LEFT DOWN HEAVY;;;; -252B;BOX DRAWINGS HEAVY VERTICAL AND LEFT;So;0;ON;;;;;N;FORMS HEAVY VERTICAL AND LEFT;;;; -252C;BOX DRAWINGS LIGHT DOWN AND HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT DOWN AND HORIZONTAL;;;; -252D;BOX DRAWINGS LEFT HEAVY AND RIGHT DOWN LIGHT;So;0;ON;;;;;N;FORMS LEFT HEAVY AND RIGHT DOWN LIGHT;;;; -252E;BOX DRAWINGS RIGHT HEAVY AND LEFT DOWN LIGHT;So;0;ON;;;;;N;FORMS RIGHT HEAVY AND LEFT DOWN LIGHT;;;; -252F;BOX DRAWINGS DOWN LIGHT AND HORIZONTAL HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND HORIZONTAL HEAVY;;;; -2530;BOX DRAWINGS DOWN HEAVY AND HORIZONTAL LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND HORIZONTAL LIGHT;;;; -2531;BOX DRAWINGS RIGHT LIGHT AND LEFT DOWN HEAVY;So;0;ON;;;;;N;FORMS RIGHT LIGHT AND LEFT DOWN HEAVY;;;; -2532;BOX DRAWINGS LEFT LIGHT AND RIGHT DOWN HEAVY;So;0;ON;;;;;N;FORMS LEFT LIGHT AND RIGHT DOWN HEAVY;;;; -2533;BOX DRAWINGS HEAVY DOWN AND HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY DOWN AND HORIZONTAL;;;; -2534;BOX DRAWINGS LIGHT UP AND HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT UP AND HORIZONTAL;;;; -2535;BOX DRAWINGS LEFT HEAVY AND RIGHT UP LIGHT;So;0;ON;;;;;N;FORMS LEFT HEAVY AND RIGHT UP LIGHT;;;; -2536;BOX DRAWINGS RIGHT HEAVY AND LEFT UP LIGHT;So;0;ON;;;;;N;FORMS RIGHT HEAVY AND LEFT UP LIGHT;;;; -2537;BOX DRAWINGS UP LIGHT AND HORIZONTAL HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND HORIZONTAL HEAVY;;;; -2538;BOX DRAWINGS UP HEAVY AND HORIZONTAL LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND HORIZONTAL LIGHT;;;; -2539;BOX DRAWINGS RIGHT LIGHT AND LEFT UP HEAVY;So;0;ON;;;;;N;FORMS RIGHT LIGHT AND LEFT UP HEAVY;;;; -253A;BOX DRAWINGS LEFT LIGHT AND RIGHT UP HEAVY;So;0;ON;;;;;N;FORMS LEFT LIGHT AND RIGHT UP HEAVY;;;; -253B;BOX DRAWINGS HEAVY UP AND HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY UP AND HORIZONTAL;;;; -253C;BOX DRAWINGS LIGHT VERTICAL AND HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT VERTICAL AND HORIZONTAL;;;; -253D;BOX DRAWINGS LEFT HEAVY AND RIGHT VERTICAL LIGHT;So;0;ON;;;;;N;FORMS LEFT HEAVY AND RIGHT VERTICAL LIGHT;;;; -253E;BOX DRAWINGS RIGHT HEAVY AND LEFT VERTICAL LIGHT;So;0;ON;;;;;N;FORMS RIGHT HEAVY AND LEFT VERTICAL LIGHT;;;; -253F;BOX DRAWINGS VERTICAL LIGHT AND HORIZONTAL HEAVY;So;0;ON;;;;;N;FORMS VERTICAL LIGHT AND HORIZONTAL HEAVY;;;; -2540;BOX DRAWINGS UP HEAVY AND DOWN HORIZONTAL LIGHT;So;0;ON;;;;;N;FORMS UP HEAVY AND DOWN HORIZONTAL LIGHT;;;; -2541;BOX DRAWINGS DOWN HEAVY AND UP HORIZONTAL LIGHT;So;0;ON;;;;;N;FORMS DOWN HEAVY AND UP HORIZONTAL LIGHT;;;; -2542;BOX DRAWINGS VERTICAL HEAVY AND HORIZONTAL LIGHT;So;0;ON;;;;;N;FORMS VERTICAL HEAVY AND HORIZONTAL LIGHT;;;; -2543;BOX DRAWINGS LEFT UP HEAVY AND RIGHT DOWN LIGHT;So;0;ON;;;;;N;FORMS LEFT UP HEAVY AND RIGHT DOWN LIGHT;;;; -2544;BOX DRAWINGS RIGHT UP HEAVY AND LEFT DOWN LIGHT;So;0;ON;;;;;N;FORMS RIGHT UP HEAVY AND LEFT DOWN LIGHT;;;; -2545;BOX DRAWINGS LEFT DOWN HEAVY AND RIGHT UP LIGHT;So;0;ON;;;;;N;FORMS LEFT DOWN HEAVY AND RIGHT UP LIGHT;;;; -2546;BOX DRAWINGS RIGHT DOWN HEAVY AND LEFT UP LIGHT;So;0;ON;;;;;N;FORMS RIGHT DOWN HEAVY AND LEFT UP LIGHT;;;; -2547;BOX DRAWINGS DOWN LIGHT AND UP HORIZONTAL HEAVY;So;0;ON;;;;;N;FORMS DOWN LIGHT AND UP HORIZONTAL HEAVY;;;; -2548;BOX DRAWINGS UP LIGHT AND DOWN HORIZONTAL HEAVY;So;0;ON;;;;;N;FORMS UP LIGHT AND DOWN HORIZONTAL HEAVY;;;; -2549;BOX DRAWINGS RIGHT LIGHT AND LEFT VERTICAL HEAVY;So;0;ON;;;;;N;FORMS RIGHT LIGHT AND LEFT VERTICAL HEAVY;;;; -254A;BOX DRAWINGS LEFT LIGHT AND RIGHT VERTICAL HEAVY;So;0;ON;;;;;N;FORMS LEFT LIGHT AND RIGHT VERTICAL HEAVY;;;; -254B;BOX DRAWINGS HEAVY VERTICAL AND HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY VERTICAL AND HORIZONTAL;;;; -254C;BOX DRAWINGS LIGHT DOUBLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS LIGHT DOUBLE DASH HORIZONTAL;;;; -254D;BOX DRAWINGS HEAVY DOUBLE DASH HORIZONTAL;So;0;ON;;;;;N;FORMS HEAVY DOUBLE DASH HORIZONTAL;;;; -254E;BOX DRAWINGS LIGHT DOUBLE DASH VERTICAL;So;0;ON;;;;;N;FORMS LIGHT DOUBLE DASH VERTICAL;;;; -254F;BOX DRAWINGS HEAVY DOUBLE DASH VERTICAL;So;0;ON;;;;;N;FORMS HEAVY DOUBLE DASH VERTICAL;;;; -2550;BOX DRAWINGS DOUBLE HORIZONTAL;So;0;ON;;;;;N;FORMS DOUBLE HORIZONTAL;;;; -2551;BOX DRAWINGS DOUBLE VERTICAL;So;0;ON;;;;;N;FORMS DOUBLE VERTICAL;;;; -2552;BOX DRAWINGS DOWN SINGLE AND RIGHT DOUBLE;So;0;ON;;;;;N;FORMS DOWN SINGLE AND RIGHT DOUBLE;;;; -2553;BOX DRAWINGS DOWN DOUBLE AND RIGHT SINGLE;So;0;ON;;;;;N;FORMS DOWN DOUBLE AND RIGHT SINGLE;;;; -2554;BOX DRAWINGS DOUBLE DOWN AND RIGHT;So;0;ON;;;;;N;FORMS DOUBLE DOWN AND RIGHT;;;; -2555;BOX DRAWINGS DOWN SINGLE AND LEFT DOUBLE;So;0;ON;;;;;N;FORMS DOWN SINGLE AND LEFT DOUBLE;;;; -2556;BOX DRAWINGS DOWN DOUBLE AND LEFT SINGLE;So;0;ON;;;;;N;FORMS DOWN DOUBLE AND LEFT SINGLE;;;; -2557;BOX DRAWINGS DOUBLE DOWN AND LEFT;So;0;ON;;;;;N;FORMS DOUBLE DOWN AND LEFT;;;; -2558;BOX DRAWINGS UP SINGLE AND RIGHT DOUBLE;So;0;ON;;;;;N;FORMS UP SINGLE AND RIGHT DOUBLE;;;; -2559;BOX DRAWINGS UP DOUBLE AND RIGHT SINGLE;So;0;ON;;;;;N;FORMS UP DOUBLE AND RIGHT SINGLE;;;; -255A;BOX DRAWINGS DOUBLE UP AND RIGHT;So;0;ON;;;;;N;FORMS DOUBLE UP AND RIGHT;;;; -255B;BOX DRAWINGS UP SINGLE AND LEFT DOUBLE;So;0;ON;;;;;N;FORMS UP SINGLE AND LEFT DOUBLE;;;; -255C;BOX DRAWINGS UP DOUBLE AND LEFT SINGLE;So;0;ON;;;;;N;FORMS UP DOUBLE AND LEFT SINGLE;;;; -255D;BOX DRAWINGS DOUBLE UP AND LEFT;So;0;ON;;;;;N;FORMS DOUBLE UP AND LEFT;;;; -255E;BOX DRAWINGS VERTICAL SINGLE AND RIGHT DOUBLE;So;0;ON;;;;;N;FORMS VERTICAL SINGLE AND RIGHT DOUBLE;;;; -255F;BOX DRAWINGS VERTICAL DOUBLE AND RIGHT SINGLE;So;0;ON;;;;;N;FORMS VERTICAL DOUBLE AND RIGHT SINGLE;;;; -2560;BOX DRAWINGS DOUBLE VERTICAL AND RIGHT;So;0;ON;;;;;N;FORMS DOUBLE VERTICAL AND RIGHT;;;; -2561;BOX DRAWINGS VERTICAL SINGLE AND LEFT DOUBLE;So;0;ON;;;;;N;FORMS VERTICAL SINGLE AND LEFT DOUBLE;;;; -2562;BOX DRAWINGS VERTICAL DOUBLE AND LEFT SINGLE;So;0;ON;;;;;N;FORMS VERTICAL DOUBLE AND LEFT SINGLE;;;; -2563;BOX DRAWINGS DOUBLE VERTICAL AND LEFT;So;0;ON;;;;;N;FORMS DOUBLE VERTICAL AND LEFT;;;; -2564;BOX DRAWINGS DOWN SINGLE AND HORIZONTAL DOUBLE;So;0;ON;;;;;N;FORMS DOWN SINGLE AND HORIZONTAL DOUBLE;;;; -2565;BOX DRAWINGS DOWN DOUBLE AND HORIZONTAL SINGLE;So;0;ON;;;;;N;FORMS DOWN DOUBLE AND HORIZONTAL SINGLE;;;; -2566;BOX DRAWINGS DOUBLE DOWN AND HORIZONTAL;So;0;ON;;;;;N;FORMS DOUBLE DOWN AND HORIZONTAL;;;; -2567;BOX DRAWINGS UP SINGLE AND HORIZONTAL DOUBLE;So;0;ON;;;;;N;FORMS UP SINGLE AND HORIZONTAL DOUBLE;;;; -2568;BOX DRAWINGS UP DOUBLE AND HORIZONTAL SINGLE;So;0;ON;;;;;N;FORMS UP DOUBLE AND HORIZONTAL SINGLE;;;; -2569;BOX DRAWINGS DOUBLE UP AND HORIZONTAL;So;0;ON;;;;;N;FORMS DOUBLE UP AND HORIZONTAL;;;; -256A;BOX DRAWINGS VERTICAL SINGLE AND HORIZONTAL DOUBLE;So;0;ON;;;;;N;FORMS VERTICAL SINGLE AND HORIZONTAL DOUBLE;;;; -256B;BOX DRAWINGS VERTICAL DOUBLE AND HORIZONTAL SINGLE;So;0;ON;;;;;N;FORMS VERTICAL DOUBLE AND HORIZONTAL SINGLE;;;; -256C;BOX DRAWINGS DOUBLE VERTICAL AND HORIZONTAL;So;0;ON;;;;;N;FORMS DOUBLE VERTICAL AND HORIZONTAL;;;; -256D;BOX DRAWINGS LIGHT ARC DOWN AND RIGHT;So;0;ON;;;;;N;FORMS LIGHT ARC DOWN AND RIGHT;;;; -256E;BOX DRAWINGS LIGHT ARC DOWN AND LEFT;So;0;ON;;;;;N;FORMS LIGHT ARC DOWN AND LEFT;;;; -256F;BOX DRAWINGS LIGHT ARC UP AND LEFT;So;0;ON;;;;;N;FORMS LIGHT ARC UP AND LEFT;;;; -2570;BOX DRAWINGS LIGHT ARC UP AND RIGHT;So;0;ON;;;;;N;FORMS LIGHT ARC UP AND RIGHT;;;; -2571;BOX DRAWINGS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT;So;0;ON;;;;;N;FORMS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT;;;; -2572;BOX DRAWINGS LIGHT DIAGONAL UPPER LEFT TO LOWER RIGHT;So;0;ON;;;;;N;FORMS LIGHT DIAGONAL UPPER LEFT TO LOWER RIGHT;;;; -2573;BOX DRAWINGS LIGHT DIAGONAL CROSS;So;0;ON;;;;;N;FORMS LIGHT DIAGONAL CROSS;;;; -2574;BOX DRAWINGS LIGHT LEFT;So;0;ON;;;;;N;FORMS LIGHT LEFT;;;; -2575;BOX DRAWINGS LIGHT UP;So;0;ON;;;;;N;FORMS LIGHT UP;;;; -2576;BOX DRAWINGS LIGHT RIGHT;So;0;ON;;;;;N;FORMS LIGHT RIGHT;;;; -2577;BOX DRAWINGS LIGHT DOWN;So;0;ON;;;;;N;FORMS LIGHT DOWN;;;; -2578;BOX DRAWINGS HEAVY LEFT;So;0;ON;;;;;N;FORMS HEAVY LEFT;;;; -2579;BOX DRAWINGS HEAVY UP;So;0;ON;;;;;N;FORMS HEAVY UP;;;; -257A;BOX DRAWINGS HEAVY RIGHT;So;0;ON;;;;;N;FORMS HEAVY RIGHT;;;; -257B;BOX DRAWINGS HEAVY DOWN;So;0;ON;;;;;N;FORMS HEAVY DOWN;;;; -257C;BOX DRAWINGS LIGHT LEFT AND HEAVY RIGHT;So;0;ON;;;;;N;FORMS LIGHT LEFT AND HEAVY RIGHT;;;; -257D;BOX DRAWINGS LIGHT UP AND HEAVY DOWN;So;0;ON;;;;;N;FORMS LIGHT UP AND HEAVY DOWN;;;; -257E;BOX DRAWINGS HEAVY LEFT AND LIGHT RIGHT;So;0;ON;;;;;N;FORMS HEAVY LEFT AND LIGHT RIGHT;;;; -257F;BOX DRAWINGS HEAVY UP AND LIGHT DOWN;So;0;ON;;;;;N;FORMS HEAVY UP AND LIGHT DOWN;;;; -2580;UPPER HALF BLOCK;So;0;ON;;;;;N;;;;; -2581;LOWER ONE EIGHTH BLOCK;So;0;ON;;;;;N;;;;; -2582;LOWER ONE QUARTER BLOCK;So;0;ON;;;;;N;;;;; -2583;LOWER THREE EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -2584;LOWER HALF BLOCK;So;0;ON;;;;;N;;;;; -2585;LOWER FIVE EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -2586;LOWER THREE QUARTERS BLOCK;So;0;ON;;;;;N;LOWER THREE QUARTER BLOCK;;;; -2587;LOWER SEVEN EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -2588;FULL BLOCK;So;0;ON;;;;;N;;;;; -2589;LEFT SEVEN EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -258A;LEFT THREE QUARTERS BLOCK;So;0;ON;;;;;N;LEFT THREE QUARTER BLOCK;;;; -258B;LEFT FIVE EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -258C;LEFT HALF BLOCK;So;0;ON;;;;;N;;;;; -258D;LEFT THREE EIGHTHS BLOCK;So;0;ON;;;;;N;;;;; -258E;LEFT ONE QUARTER BLOCK;So;0;ON;;;;;N;;;;; -258F;LEFT ONE EIGHTH BLOCK;So;0;ON;;;;;N;;;;; -2590;RIGHT HALF BLOCK;So;0;ON;;;;;N;;;;; -2591;LIGHT SHADE;So;0;ON;;;;;N;;;;; -2592;MEDIUM SHADE;So;0;ON;;;;;N;;;;; -2593;DARK SHADE;So;0;ON;;;;;N;;;;; -2594;UPPER ONE EIGHTH BLOCK;So;0;ON;;;;;N;;;;; -2595;RIGHT ONE EIGHTH BLOCK;So;0;ON;;;;;N;;;;; -2596;QUADRANT LOWER LEFT;So;0;ON;;;;;N;;;;; -2597;QUADRANT LOWER RIGHT;So;0;ON;;;;;N;;;;; -2598;QUADRANT UPPER LEFT;So;0;ON;;;;;N;;;;; -2599;QUADRANT UPPER LEFT AND LOWER LEFT AND LOWER RIGHT;So;0;ON;;;;;N;;;;; -259A;QUADRANT UPPER LEFT AND LOWER RIGHT;So;0;ON;;;;;N;;;;; -259B;QUADRANT UPPER LEFT AND UPPER RIGHT AND LOWER LEFT;So;0;ON;;;;;N;;;;; -259C;QUADRANT UPPER LEFT AND UPPER RIGHT AND LOWER RIGHT;So;0;ON;;;;;N;;;;; -259D;QUADRANT UPPER RIGHT;So;0;ON;;;;;N;;;;; -259E;QUADRANT UPPER RIGHT AND LOWER LEFT;So;0;ON;;;;;N;;;;; -259F;QUADRANT UPPER RIGHT AND LOWER LEFT AND LOWER RIGHT;So;0;ON;;;;;N;;;;; -25A0;BLACK SQUARE;So;0;ON;;;;;N;;;;; -25A1;WHITE SQUARE;So;0;ON;;;;;N;;;;; -25A2;WHITE SQUARE WITH ROUNDED CORNERS;So;0;ON;;;;;N;;;;; -25A3;WHITE SQUARE CONTAINING BLACK SMALL SQUARE;So;0;ON;;;;;N;;;;; -25A4;SQUARE WITH HORIZONTAL FILL;So;0;ON;;;;;N;;;;; -25A5;SQUARE WITH VERTICAL FILL;So;0;ON;;;;;N;;;;; -25A6;SQUARE WITH ORTHOGONAL CROSSHATCH FILL;So;0;ON;;;;;N;;;;; -25A7;SQUARE WITH UPPER LEFT TO LOWER RIGHT FILL;So;0;ON;;;;;N;;;;; -25A8;SQUARE WITH UPPER RIGHT TO LOWER LEFT FILL;So;0;ON;;;;;N;;;;; -25A9;SQUARE WITH DIAGONAL CROSSHATCH FILL;So;0;ON;;;;;N;;;;; -25AA;BLACK SMALL SQUARE;So;0;ON;;;;;N;;;;; -25AB;WHITE SMALL SQUARE;So;0;ON;;;;;N;;;;; -25AC;BLACK RECTANGLE;So;0;ON;;;;;N;;;;; -25AD;WHITE RECTANGLE;So;0;ON;;;;;N;;;;; -25AE;BLACK VERTICAL RECTANGLE;So;0;ON;;;;;N;;;;; -25AF;WHITE VERTICAL RECTANGLE;So;0;ON;;;;;N;;;;; -25B0;BLACK PARALLELOGRAM;So;0;ON;;;;;N;;;;; -25B1;WHITE PARALLELOGRAM;So;0;ON;;;;;N;;;;; -25B2;BLACK UP-POINTING TRIANGLE;So;0;ON;;;;;N;BLACK UP POINTING TRIANGLE;;;; -25B3;WHITE UP-POINTING TRIANGLE;So;0;ON;;;;;N;WHITE UP POINTING TRIANGLE;;;; -25B4;BLACK UP-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;BLACK UP POINTING SMALL TRIANGLE;;;; -25B5;WHITE UP-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;WHITE UP POINTING SMALL TRIANGLE;;;; -25B6;BLACK RIGHT-POINTING TRIANGLE;So;0;ON;;;;;N;BLACK RIGHT POINTING TRIANGLE;;;; -25B7;WHITE RIGHT-POINTING TRIANGLE;Sm;0;ON;;;;;N;WHITE RIGHT POINTING TRIANGLE;;;; -25B8;BLACK RIGHT-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;BLACK RIGHT POINTING SMALL TRIANGLE;;;; -25B9;WHITE RIGHT-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;WHITE RIGHT POINTING SMALL TRIANGLE;;;; -25BA;BLACK RIGHT-POINTING POINTER;So;0;ON;;;;;N;BLACK RIGHT POINTING POINTER;;;; -25BB;WHITE RIGHT-POINTING POINTER;So;0;ON;;;;;N;WHITE RIGHT POINTING POINTER;;;; -25BC;BLACK DOWN-POINTING TRIANGLE;So;0;ON;;;;;N;BLACK DOWN POINTING TRIANGLE;;;; -25BD;WHITE DOWN-POINTING TRIANGLE;So;0;ON;;;;;N;WHITE DOWN POINTING TRIANGLE;;;; -25BE;BLACK DOWN-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;BLACK DOWN POINTING SMALL TRIANGLE;;;; -25BF;WHITE DOWN-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;WHITE DOWN POINTING SMALL TRIANGLE;;;; -25C0;BLACK LEFT-POINTING TRIANGLE;So;0;ON;;;;;N;BLACK LEFT POINTING TRIANGLE;;;; -25C1;WHITE LEFT-POINTING TRIANGLE;Sm;0;ON;;;;;N;WHITE LEFT POINTING TRIANGLE;;;; -25C2;BLACK LEFT-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;BLACK LEFT POINTING SMALL TRIANGLE;;;; -25C3;WHITE LEFT-POINTING SMALL TRIANGLE;So;0;ON;;;;;N;WHITE LEFT POINTING SMALL TRIANGLE;;;; -25C4;BLACK LEFT-POINTING POINTER;So;0;ON;;;;;N;BLACK LEFT POINTING POINTER;;;; -25C5;WHITE LEFT-POINTING POINTER;So;0;ON;;;;;N;WHITE LEFT POINTING POINTER;;;; -25C6;BLACK DIAMOND;So;0;ON;;;;;N;;;;; -25C7;WHITE DIAMOND;So;0;ON;;;;;N;;;;; -25C8;WHITE DIAMOND CONTAINING BLACK SMALL DIAMOND;So;0;ON;;;;;N;;;;; -25C9;FISHEYE;So;0;ON;;;;;N;;;;; -25CA;LOZENGE;So;0;ON;;;;;N;;;;; -25CB;WHITE CIRCLE;So;0;ON;;;;;N;;;;; -25CC;DOTTED CIRCLE;So;0;ON;;;;;N;;;;; -25CD;CIRCLE WITH VERTICAL FILL;So;0;ON;;;;;N;;;;; -25CE;BULLSEYE;So;0;ON;;;;;N;;;;; -25CF;BLACK CIRCLE;So;0;ON;;;;;N;;;;; -25D0;CIRCLE WITH LEFT HALF BLACK;So;0;ON;;;;;N;;;;; -25D1;CIRCLE WITH RIGHT HALF BLACK;So;0;ON;;;;;N;;;;; -25D2;CIRCLE WITH LOWER HALF BLACK;So;0;ON;;;;;N;;;;; -25D3;CIRCLE WITH UPPER HALF BLACK;So;0;ON;;;;;N;;;;; -25D4;CIRCLE WITH UPPER RIGHT QUADRANT BLACK;So;0;ON;;;;;N;;;;; -25D5;CIRCLE WITH ALL BUT UPPER LEFT QUADRANT BLACK;So;0;ON;;;;;N;;;;; -25D6;LEFT HALF BLACK CIRCLE;So;0;ON;;;;;N;;;;; -25D7;RIGHT HALF BLACK CIRCLE;So;0;ON;;;;;N;;;;; -25D8;INVERSE BULLET;So;0;ON;;;;;N;;;;; -25D9;INVERSE WHITE CIRCLE;So;0;ON;;;;;N;;;;; -25DA;UPPER HALF INVERSE WHITE CIRCLE;So;0;ON;;;;;N;;;;; -25DB;LOWER HALF INVERSE WHITE CIRCLE;So;0;ON;;;;;N;;;;; -25DC;UPPER LEFT QUADRANT CIRCULAR ARC;So;0;ON;;;;;N;;;;; -25DD;UPPER RIGHT QUADRANT CIRCULAR ARC;So;0;ON;;;;;N;;;;; -25DE;LOWER RIGHT QUADRANT CIRCULAR ARC;So;0;ON;;;;;N;;;;; -25DF;LOWER LEFT QUADRANT CIRCULAR ARC;So;0;ON;;;;;N;;;;; -25E0;UPPER HALF CIRCLE;So;0;ON;;;;;N;;;;; -25E1;LOWER HALF CIRCLE;So;0;ON;;;;;N;;;;; -25E2;BLACK LOWER RIGHT TRIANGLE;So;0;ON;;;;;N;;;;; -25E3;BLACK LOWER LEFT TRIANGLE;So;0;ON;;;;;N;;;;; -25E4;BLACK UPPER LEFT TRIANGLE;So;0;ON;;;;;N;;;;; -25E5;BLACK UPPER RIGHT TRIANGLE;So;0;ON;;;;;N;;;;; -25E6;WHITE BULLET;So;0;ON;;;;;N;;;;; -25E7;SQUARE WITH LEFT HALF BLACK;So;0;ON;;;;;N;;;;; -25E8;SQUARE WITH RIGHT HALF BLACK;So;0;ON;;;;;N;;;;; -25E9;SQUARE WITH UPPER LEFT DIAGONAL HALF BLACK;So;0;ON;;;;;N;;;;; -25EA;SQUARE WITH LOWER RIGHT DIAGONAL HALF BLACK;So;0;ON;;;;;N;;;;; -25EB;WHITE SQUARE WITH VERTICAL BISECTING LINE;So;0;ON;;;;;N;;;;; -25EC;WHITE UP-POINTING TRIANGLE WITH DOT;So;0;ON;;;;;N;WHITE UP POINTING TRIANGLE WITH DOT;;;; -25ED;UP-POINTING TRIANGLE WITH LEFT HALF BLACK;So;0;ON;;;;;N;UP POINTING TRIANGLE WITH LEFT HALF BLACK;;;; -25EE;UP-POINTING TRIANGLE WITH RIGHT HALF BLACK;So;0;ON;;;;;N;UP POINTING TRIANGLE WITH RIGHT HALF BLACK;;;; -25EF;LARGE CIRCLE;So;0;ON;;;;;N;;;;; -25F0;WHITE SQUARE WITH UPPER LEFT QUADRANT;So;0;ON;;;;;N;;;;; -25F1;WHITE SQUARE WITH LOWER LEFT QUADRANT;So;0;ON;;;;;N;;;;; -25F2;WHITE SQUARE WITH LOWER RIGHT QUADRANT;So;0;ON;;;;;N;;;;; -25F3;WHITE SQUARE WITH UPPER RIGHT QUADRANT;So;0;ON;;;;;N;;;;; -25F4;WHITE CIRCLE WITH UPPER LEFT QUADRANT;So;0;ON;;;;;N;;;;; -25F5;WHITE CIRCLE WITH LOWER LEFT QUADRANT;So;0;ON;;;;;N;;;;; -25F6;WHITE CIRCLE WITH LOWER RIGHT QUADRANT;So;0;ON;;;;;N;;;;; -25F7;WHITE CIRCLE WITH UPPER RIGHT QUADRANT;So;0;ON;;;;;N;;;;; -25F8;UPPER LEFT TRIANGLE;Sm;0;ON;;;;;N;;;;; -25F9;UPPER RIGHT TRIANGLE;Sm;0;ON;;;;;N;;;;; -25FA;LOWER LEFT TRIANGLE;Sm;0;ON;;;;;N;;;;; -25FB;WHITE MEDIUM SQUARE;Sm;0;ON;;;;;N;;;;; -25FC;BLACK MEDIUM SQUARE;Sm;0;ON;;;;;N;;;;; -25FD;WHITE MEDIUM SMALL SQUARE;Sm;0;ON;;;;;N;;;;; -25FE;BLACK MEDIUM SMALL SQUARE;Sm;0;ON;;;;;N;;;;; -25FF;LOWER RIGHT TRIANGLE;Sm;0;ON;;;;;N;;;;; -2600;BLACK SUN WITH RAYS;So;0;ON;;;;;N;;;;; -2601;CLOUD;So;0;ON;;;;;N;;;;; -2602;UMBRELLA;So;0;ON;;;;;N;;;;; -2603;SNOWMAN;So;0;ON;;;;;N;;;;; -2604;COMET;So;0;ON;;;;;N;;;;; -2605;BLACK STAR;So;0;ON;;;;;N;;;;; -2606;WHITE STAR;So;0;ON;;;;;N;;;;; -2607;LIGHTNING;So;0;ON;;;;;N;;;;; -2608;THUNDERSTORM;So;0;ON;;;;;N;;;;; -2609;SUN;So;0;ON;;;;;N;;;;; -260A;ASCENDING NODE;So;0;ON;;;;;N;;;;; -260B;DESCENDING NODE;So;0;ON;;;;;N;;;;; -260C;CONJUNCTION;So;0;ON;;;;;N;;;;; -260D;OPPOSITION;So;0;ON;;;;;N;;;;; -260E;BLACK TELEPHONE;So;0;ON;;;;;N;;;;; -260F;WHITE TELEPHONE;So;0;ON;;;;;N;;;;; -2610;BALLOT BOX;So;0;ON;;;;;N;;;;; -2611;BALLOT BOX WITH CHECK;So;0;ON;;;;;N;;;;; -2612;BALLOT BOX WITH X;So;0;ON;;;;;N;;;;; -2613;SALTIRE;So;0;ON;;;;;N;;;;; -2614;UMBRELLA WITH RAIN DROPS;So;0;ON;;;;;N;;;;; -2615;HOT BEVERAGE;So;0;ON;;;;;N;;;;; -2616;WHITE SHOGI PIECE;So;0;ON;;;;;N;;;;; -2617;BLACK SHOGI PIECE;So;0;ON;;;;;N;;;;; -2618;SHAMROCK;So;0;ON;;;;;N;;;;; -2619;REVERSED ROTATED FLORAL HEART BULLET;So;0;ON;;;;;N;;;;; -261A;BLACK LEFT POINTING INDEX;So;0;ON;;;;;N;;;;; -261B;BLACK RIGHT POINTING INDEX;So;0;ON;;;;;N;;;;; -261C;WHITE LEFT POINTING INDEX;So;0;ON;;;;;N;;;;; -261D;WHITE UP POINTING INDEX;So;0;ON;;;;;N;;;;; -261E;WHITE RIGHT POINTING INDEX;So;0;ON;;;;;N;;;;; -261F;WHITE DOWN POINTING INDEX;So;0;ON;;;;;N;;;;; -2620;SKULL AND CROSSBONES;So;0;ON;;;;;N;;;;; -2621;CAUTION SIGN;So;0;ON;;;;;N;;;;; -2622;RADIOACTIVE SIGN;So;0;ON;;;;;N;;;;; -2623;BIOHAZARD SIGN;So;0;ON;;;;;N;;;;; -2624;CADUCEUS;So;0;ON;;;;;N;;;;; -2625;ANKH;So;0;ON;;;;;N;;;;; -2626;ORTHODOX CROSS;So;0;ON;;;;;N;;;;; -2627;CHI RHO;So;0;ON;;;;;N;;;;; -2628;CROSS OF LORRAINE;So;0;ON;;;;;N;;;;; -2629;CROSS OF JERUSALEM;So;0;ON;;;;;N;;;;; -262A;STAR AND CRESCENT;So;0;ON;;;;;N;;;;; -262B;FARSI SYMBOL;So;0;ON;;;;;N;SYMBOL OF IRAN;;;; -262C;ADI SHAKTI;So;0;ON;;;;;N;;;;; -262D;HAMMER AND SICKLE;So;0;ON;;;;;N;;;;; -262E;PEACE SYMBOL;So;0;ON;;;;;N;;;;; -262F;YIN YANG;So;0;ON;;;;;N;;;;; -2630;TRIGRAM FOR HEAVEN;So;0;ON;;;;;N;;;;; -2631;TRIGRAM FOR LAKE;So;0;ON;;;;;N;;;;; -2632;TRIGRAM FOR FIRE;So;0;ON;;;;;N;;;;; -2633;TRIGRAM FOR THUNDER;So;0;ON;;;;;N;;;;; -2634;TRIGRAM FOR WIND;So;0;ON;;;;;N;;;;; -2635;TRIGRAM FOR WATER;So;0;ON;;;;;N;;;;; -2636;TRIGRAM FOR MOUNTAIN;So;0;ON;;;;;N;;;;; -2637;TRIGRAM FOR EARTH;So;0;ON;;;;;N;;;;; -2638;WHEEL OF DHARMA;So;0;ON;;;;;N;;;;; -2639;WHITE FROWNING FACE;So;0;ON;;;;;N;;;;; -263A;WHITE SMILING FACE;So;0;ON;;;;;N;;;;; -263B;BLACK SMILING FACE;So;0;ON;;;;;N;;;;; -263C;WHITE SUN WITH RAYS;So;0;ON;;;;;N;;;;; -263D;FIRST QUARTER MOON;So;0;ON;;;;;N;;;;; -263E;LAST QUARTER MOON;So;0;ON;;;;;N;;;;; -263F;MERCURY;So;0;ON;;;;;N;;;;; -2640;FEMALE SIGN;So;0;ON;;;;;N;;;;; -2641;EARTH;So;0;ON;;;;;N;;;;; -2642;MALE SIGN;So;0;ON;;;;;N;;;;; -2643;JUPITER;So;0;ON;;;;;N;;;;; -2644;SATURN;So;0;ON;;;;;N;;;;; -2645;URANUS;So;0;ON;;;;;N;;;;; -2646;NEPTUNE;So;0;ON;;;;;N;;;;; -2647;PLUTO;So;0;ON;;;;;N;;;;; -2648;ARIES;So;0;ON;;;;;N;;;;; -2649;TAURUS;So;0;ON;;;;;N;;;;; -264A;GEMINI;So;0;ON;;;;;N;;;;; -264B;CANCER;So;0;ON;;;;;N;;;;; -264C;LEO;So;0;ON;;;;;N;;;;; -264D;VIRGO;So;0;ON;;;;;N;;;;; -264E;LIBRA;So;0;ON;;;;;N;;;;; -264F;SCORPIUS;So;0;ON;;;;;N;;;;; -2650;SAGITTARIUS;So;0;ON;;;;;N;;;;; -2651;CAPRICORN;So;0;ON;;;;;N;;;;; -2652;AQUARIUS;So;0;ON;;;;;N;;;;; -2653;PISCES;So;0;ON;;;;;N;;;;; -2654;WHITE CHESS KING;So;0;ON;;;;;N;;;;; -2655;WHITE CHESS QUEEN;So;0;ON;;;;;N;;;;; -2656;WHITE CHESS ROOK;So;0;ON;;;;;N;;;;; -2657;WHITE CHESS BISHOP;So;0;ON;;;;;N;;;;; -2658;WHITE CHESS KNIGHT;So;0;ON;;;;;N;;;;; -2659;WHITE CHESS PAWN;So;0;ON;;;;;N;;;;; -265A;BLACK CHESS KING;So;0;ON;;;;;N;;;;; -265B;BLACK CHESS QUEEN;So;0;ON;;;;;N;;;;; -265C;BLACK CHESS ROOK;So;0;ON;;;;;N;;;;; -265D;BLACK CHESS BISHOP;So;0;ON;;;;;N;;;;; -265E;BLACK CHESS KNIGHT;So;0;ON;;;;;N;;;;; -265F;BLACK CHESS PAWN;So;0;ON;;;;;N;;;;; -2660;BLACK SPADE SUIT;So;0;ON;;;;;N;;;;; -2661;WHITE HEART SUIT;So;0;ON;;;;;N;;;;; -2662;WHITE DIAMOND SUIT;So;0;ON;;;;;N;;;;; -2663;BLACK CLUB SUIT;So;0;ON;;;;;N;;;;; -2664;WHITE SPADE SUIT;So;0;ON;;;;;N;;;;; -2665;BLACK HEART SUIT;So;0;ON;;;;;N;;;;; -2666;BLACK DIAMOND SUIT;So;0;ON;;;;;N;;;;; -2667;WHITE CLUB SUIT;So;0;ON;;;;;N;;;;; -2668;HOT SPRINGS;So;0;ON;;;;;N;;;;; -2669;QUARTER NOTE;So;0;ON;;;;;N;;;;; -266A;EIGHTH NOTE;So;0;ON;;;;;N;;;;; -266B;BEAMED EIGHTH NOTES;So;0;ON;;;;;N;BARRED EIGHTH NOTES;;;; -266C;BEAMED SIXTEENTH NOTES;So;0;ON;;;;;N;BARRED SIXTEENTH NOTES;;;; -266D;MUSIC FLAT SIGN;So;0;ON;;;;;N;FLAT;;;; -266E;MUSIC NATURAL SIGN;So;0;ON;;;;;N;NATURAL;;;; -266F;MUSIC SHARP SIGN;Sm;0;ON;;;;;N;SHARP;;;; -2670;WEST SYRIAC CROSS;So;0;ON;;;;;N;;;;; -2671;EAST SYRIAC CROSS;So;0;ON;;;;;N;;;;; -2672;UNIVERSAL RECYCLING SYMBOL;So;0;ON;;;;;N;;;;; -2673;RECYCLING SYMBOL FOR TYPE-1 PLASTICS;So;0;ON;;;;;N;;pete;;; -2674;RECYCLING SYMBOL FOR TYPE-2 PLASTICS;So;0;ON;;;;;N;;hdpe;;; -2675;RECYCLING SYMBOL FOR TYPE-3 PLASTICS;So;0;ON;;;;;N;;pvc;;; -2676;RECYCLING SYMBOL FOR TYPE-4 PLASTICS;So;0;ON;;;;;N;;ldpe;;; -2677;RECYCLING SYMBOL FOR TYPE-5 PLASTICS;So;0;ON;;;;;N;;pp;;; -2678;RECYCLING SYMBOL FOR TYPE-6 PLASTICS;So;0;ON;;;;;N;;ps;;; -2679;RECYCLING SYMBOL FOR TYPE-7 PLASTICS;So;0;ON;;;;;N;;other;;; -267A;RECYCLING SYMBOL FOR GENERIC MATERIALS;So;0;ON;;;;;N;;;;; -267B;BLACK UNIVERSAL RECYCLING SYMBOL;So;0;ON;;;;;N;;;;; -267C;RECYCLED PAPER SYMBOL;So;0;ON;;;;;N;;;;; -267D;PARTIALLY-RECYCLED PAPER SYMBOL;So;0;ON;;;;;N;;;;; -267E;PERMANENT PAPER SIGN;So;0;ON;;;;;N;;;;; -267F;WHEELCHAIR SYMBOL;So;0;ON;;;;;N;;;;; -2680;DIE FACE-1;So;0;ON;;;;;N;;;;; -2681;DIE FACE-2;So;0;ON;;;;;N;;;;; -2682;DIE FACE-3;So;0;ON;;;;;N;;;;; -2683;DIE FACE-4;So;0;ON;;;;;N;;;;; -2684;DIE FACE-5;So;0;ON;;;;;N;;;;; -2685;DIE FACE-6;So;0;ON;;;;;N;;;;; -2686;WHITE CIRCLE WITH DOT RIGHT;So;0;ON;;;;;N;;;;; -2687;WHITE CIRCLE WITH TWO DOTS;So;0;ON;;;;;N;;;;; -2688;BLACK CIRCLE WITH WHITE DOT RIGHT;So;0;ON;;;;;N;;;;; -2689;BLACK CIRCLE WITH TWO WHITE DOTS;So;0;ON;;;;;N;;;;; -268A;MONOGRAM FOR YANG;So;0;ON;;;;;N;;;;; -268B;MONOGRAM FOR YIN;So;0;ON;;;;;N;;;;; -268C;DIGRAM FOR GREATER YANG;So;0;ON;;;;;N;;;;; -268D;DIGRAM FOR LESSER YIN;So;0;ON;;;;;N;;;;; -268E;DIGRAM FOR LESSER YANG;So;0;ON;;;;;N;;;;; -268F;DIGRAM FOR GREATER YIN;So;0;ON;;;;;N;;;;; -2690;WHITE FLAG;So;0;ON;;;;;N;;;;; -2691;BLACK FLAG;So;0;ON;;;;;N;;;;; -2692;HAMMER AND PICK;So;0;ON;;;;;N;;;;; -2693;ANCHOR;So;0;ON;;;;;N;;;;; -2694;CROSSED SWORDS;So;0;ON;;;;;N;;;;; -2695;STAFF OF AESCULAPIUS;So;0;ON;;;;;N;;;;; -2696;SCALES;So;0;ON;;;;;N;;;;; -2697;ALEMBIC;So;0;ON;;;;;N;;;;; -2698;FLOWER;So;0;ON;;;;;N;;;;; -2699;GEAR;So;0;ON;;;;;N;;;;; -269A;STAFF OF HERMES;So;0;ON;;;;;N;;;;; -269B;ATOM SYMBOL;So;0;ON;;;;;N;;;;; -269C;FLEUR-DE-LIS;So;0;ON;;;;;N;;;;; -269D;OUTLINED WHITE STAR;So;0;ON;;;;;N;;;;; -26A0;WARNING SIGN;So;0;ON;;;;;N;;;;; -26A1;HIGH VOLTAGE SIGN;So;0;ON;;;;;N;;;;; -26A2;DOUBLED FEMALE SIGN;So;0;ON;;;;;N;;;;; -26A3;DOUBLED MALE SIGN;So;0;ON;;;;;N;;;;; -26A4;INTERLOCKED FEMALE AND MALE SIGN;So;0;ON;;;;;N;;;;; -26A5;MALE AND FEMALE SIGN;So;0;ON;;;;;N;;;;; -26A6;MALE WITH STROKE SIGN;So;0;ON;;;;;N;;;;; -26A7;MALE WITH STROKE AND MALE AND FEMALE SIGN;So;0;ON;;;;;N;;;;; -26A8;VERTICAL MALE WITH STROKE SIGN;So;0;ON;;;;;N;;;;; -26A9;HORIZONTAL MALE WITH STROKE SIGN;So;0;ON;;;;;N;;;;; -26AA;MEDIUM WHITE CIRCLE;So;0;ON;;;;;N;;;;; -26AB;MEDIUM BLACK CIRCLE;So;0;ON;;;;;N;;;;; -26AC;MEDIUM SMALL WHITE CIRCLE;So;0;L;;;;;N;;;;; -26AD;MARRIAGE SYMBOL;So;0;ON;;;;;N;;;;; -26AE;DIVORCE SYMBOL;So;0;ON;;;;;N;;;;; -26AF;UNMARRIED PARTNERSHIP SYMBOL;So;0;ON;;;;;N;;;;; -26B0;COFFIN;So;0;ON;;;;;N;;;;; -26B1;FUNERAL URN;So;0;ON;;;;;N;;;;; -26B2;NEUTER;So;0;ON;;;;;N;;;;; -26B3;CERES;So;0;ON;;;;;N;;;;; -26B4;PALLAS;So;0;ON;;;;;N;;;;; -26B5;JUNO;So;0;ON;;;;;N;;;;; -26B6;VESTA;So;0;ON;;;;;N;;;;; -26B7;CHIRON;So;0;ON;;;;;N;;;;; -26B8;BLACK MOON LILITH;So;0;ON;;;;;N;;;;; -26B9;SEXTILE;So;0;ON;;;;;N;;;;; -26BA;SEMISEXTILE;So;0;ON;;;;;N;;;;; -26BB;QUINCUNX;So;0;ON;;;;;N;;;;; -26BC;SESQUIQUADRATE;So;0;ON;;;;;N;;;;; -26C0;WHITE DRAUGHTS MAN;So;0;ON;;;;;N;;;;; -26C1;WHITE DRAUGHTS KING;So;0;ON;;;;;N;;;;; -26C2;BLACK DRAUGHTS MAN;So;0;ON;;;;;N;;;;; -26C3;BLACK DRAUGHTS KING;So;0;ON;;;;;N;;;;; -2701;UPPER BLADE SCISSORS;So;0;ON;;;;;N;;;;; -2702;BLACK SCISSORS;So;0;ON;;;;;N;;;;; -2703;LOWER BLADE SCISSORS;So;0;ON;;;;;N;;;;; -2704;WHITE SCISSORS;So;0;ON;;;;;N;;;;; -2706;TELEPHONE LOCATION SIGN;So;0;ON;;;;;N;;;;; -2707;TAPE DRIVE;So;0;ON;;;;;N;;;;; -2708;AIRPLANE;So;0;ON;;;;;N;;;;; -2709;ENVELOPE;So;0;ON;;;;;N;;;;; -270C;VICTORY HAND;So;0;ON;;;;;N;;;;; -270D;WRITING HAND;So;0;ON;;;;;N;;;;; -270E;LOWER RIGHT PENCIL;So;0;ON;;;;;N;;;;; -270F;PENCIL;So;0;ON;;;;;N;;;;; -2710;UPPER RIGHT PENCIL;So;0;ON;;;;;N;;;;; -2711;WHITE NIB;So;0;ON;;;;;N;;;;; -2712;BLACK NIB;So;0;ON;;;;;N;;;;; -2713;CHECK MARK;So;0;ON;;;;;N;;;;; -2714;HEAVY CHECK MARK;So;0;ON;;;;;N;;;;; -2715;MULTIPLICATION X;So;0;ON;;;;;N;;;;; -2716;HEAVY MULTIPLICATION X;So;0;ON;;;;;N;;;;; -2717;BALLOT X;So;0;ON;;;;;N;;;;; -2718;HEAVY BALLOT X;So;0;ON;;;;;N;;;;; -2719;OUTLINED GREEK CROSS;So;0;ON;;;;;N;;;;; -271A;HEAVY GREEK CROSS;So;0;ON;;;;;N;;;;; -271B;OPEN CENTRE CROSS;So;0;ON;;;;;N;OPEN CENTER CROSS;;;; -271C;HEAVY OPEN CENTRE CROSS;So;0;ON;;;;;N;HEAVY OPEN CENTER CROSS;;;; -271D;LATIN CROSS;So;0;ON;;;;;N;;;;; -271E;SHADOWED WHITE LATIN CROSS;So;0;ON;;;;;N;;;;; -271F;OUTLINED LATIN CROSS;So;0;ON;;;;;N;;;;; -2720;MALTESE CROSS;So;0;ON;;;;;N;;;;; -2721;STAR OF DAVID;So;0;ON;;;;;N;;;;; -2722;FOUR TEARDROP-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -2723;FOUR BALLOON-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -2724;HEAVY FOUR BALLOON-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -2725;FOUR CLUB-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -2726;BLACK FOUR POINTED STAR;So;0;ON;;;;;N;;;;; -2727;WHITE FOUR POINTED STAR;So;0;ON;;;;;N;;;;; -2729;STRESS OUTLINED WHITE STAR;So;0;ON;;;;;N;;;;; -272A;CIRCLED WHITE STAR;So;0;ON;;;;;N;;;;; -272B;OPEN CENTRE BLACK STAR;So;0;ON;;;;;N;OPEN CENTER BLACK STAR;;;; -272C;BLACK CENTRE WHITE STAR;So;0;ON;;;;;N;BLACK CENTER WHITE STAR;;;; -272D;OUTLINED BLACK STAR;So;0;ON;;;;;N;;;;; -272E;HEAVY OUTLINED BLACK STAR;So;0;ON;;;;;N;;;;; -272F;PINWHEEL STAR;So;0;ON;;;;;N;;;;; -2730;SHADOWED WHITE STAR;So;0;ON;;;;;N;;;;; -2731;HEAVY ASTERISK;So;0;ON;;;;;N;;;;; -2732;OPEN CENTRE ASTERISK;So;0;ON;;;;;N;OPEN CENTER ASTERISK;;;; -2733;EIGHT SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -2734;EIGHT POINTED BLACK STAR;So;0;ON;;;;;N;;;;; -2735;EIGHT POINTED PINWHEEL STAR;So;0;ON;;;;;N;;;;; -2736;SIX POINTED BLACK STAR;So;0;ON;;;;;N;;;;; -2737;EIGHT POINTED RECTILINEAR BLACK STAR;So;0;ON;;;;;N;;;;; -2738;HEAVY EIGHT POINTED RECTILINEAR BLACK STAR;So;0;ON;;;;;N;;;;; -2739;TWELVE POINTED BLACK STAR;So;0;ON;;;;;N;;;;; -273A;SIXTEEN POINTED ASTERISK;So;0;ON;;;;;N;;;;; -273B;TEARDROP-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -273C;OPEN CENTRE TEARDROP-SPOKED ASTERISK;So;0;ON;;;;;N;OPEN CENTER TEARDROP-SPOKED ASTERISK;;;; -273D;HEAVY TEARDROP-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -273E;SIX PETALLED BLACK AND WHITE FLORETTE;So;0;ON;;;;;N;;;;; -273F;BLACK FLORETTE;So;0;ON;;;;;N;;;;; -2740;WHITE FLORETTE;So;0;ON;;;;;N;;;;; -2741;EIGHT PETALLED OUTLINED BLACK FLORETTE;So;0;ON;;;;;N;;;;; -2742;CIRCLED OPEN CENTRE EIGHT POINTED STAR;So;0;ON;;;;;N;CIRCLED OPEN CENTER EIGHT POINTED STAR;;;; -2743;HEAVY TEARDROP-SPOKED PINWHEEL ASTERISK;So;0;ON;;;;;N;;;;; -2744;SNOWFLAKE;So;0;ON;;;;;N;;;;; -2745;TIGHT TRIFOLIATE SNOWFLAKE;So;0;ON;;;;;N;;;;; -2746;HEAVY CHEVRON SNOWFLAKE;So;0;ON;;;;;N;;;;; -2747;SPARKLE;So;0;ON;;;;;N;;;;; -2748;HEAVY SPARKLE;So;0;ON;;;;;N;;;;; -2749;BALLOON-SPOKED ASTERISK;So;0;ON;;;;;N;;;;; -274A;EIGHT TEARDROP-SPOKED PROPELLER ASTERISK;So;0;ON;;;;;N;;;;; -274B;HEAVY EIGHT TEARDROP-SPOKED PROPELLER ASTERISK;So;0;ON;;;;;N;;;;; -274D;SHADOWED WHITE CIRCLE;So;0;ON;;;;;N;;;;; -274F;LOWER RIGHT DROP-SHADOWED WHITE SQUARE;So;0;ON;;;;;N;;;;; -2750;UPPER RIGHT DROP-SHADOWED WHITE SQUARE;So;0;ON;;;;;N;;;;; -2751;LOWER RIGHT SHADOWED WHITE SQUARE;So;0;ON;;;;;N;;;;; -2752;UPPER RIGHT SHADOWED WHITE SQUARE;So;0;ON;;;;;N;;;;; -2756;BLACK DIAMOND MINUS WHITE X;So;0;ON;;;;;N;;;;; -2758;LIGHT VERTICAL BAR;So;0;ON;;;;;N;;;;; -2759;MEDIUM VERTICAL BAR;So;0;ON;;;;;N;;;;; -275A;HEAVY VERTICAL BAR;So;0;ON;;;;;N;;;;; -275B;HEAVY SINGLE TURNED COMMA QUOTATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -275C;HEAVY SINGLE COMMA QUOTATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -275D;HEAVY DOUBLE TURNED COMMA QUOTATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -275E;HEAVY DOUBLE COMMA QUOTATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -2761;CURVED STEM PARAGRAPH SIGN ORNAMENT;So;0;ON;;;;;N;;;;; -2762;HEAVY EXCLAMATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -2763;HEAVY HEART EXCLAMATION MARK ORNAMENT;So;0;ON;;;;;N;;;;; -2764;HEAVY BLACK HEART;So;0;ON;;;;;N;;;;; -2765;ROTATED HEAVY BLACK HEART BULLET;So;0;ON;;;;;N;;;;; -2766;FLORAL HEART;So;0;ON;;;;;N;;;;; -2767;ROTATED FLORAL HEART BULLET;So;0;ON;;;;;N;;;;; -2768;MEDIUM LEFT PARENTHESIS ORNAMENT;Ps;0;ON;;;;;Y;;;;; -2769;MEDIUM RIGHT PARENTHESIS ORNAMENT;Pe;0;ON;;;;;Y;;;;; -276A;MEDIUM FLATTENED LEFT PARENTHESIS ORNAMENT;Ps;0;ON;;;;;Y;;;;; -276B;MEDIUM FLATTENED RIGHT PARENTHESIS ORNAMENT;Pe;0;ON;;;;;Y;;;;; -276C;MEDIUM LEFT-POINTING ANGLE BRACKET ORNAMENT;Ps;0;ON;;;;;Y;;;;; -276D;MEDIUM RIGHT-POINTING ANGLE BRACKET ORNAMENT;Pe;0;ON;;;;;Y;;;;; -276E;HEAVY LEFT-POINTING ANGLE QUOTATION MARK ORNAMENT;Ps;0;ON;;;;;Y;;;;; -276F;HEAVY RIGHT-POINTING ANGLE QUOTATION MARK ORNAMENT;Pe;0;ON;;;;;Y;;;;; -2770;HEAVY LEFT-POINTING ANGLE BRACKET ORNAMENT;Ps;0;ON;;;;;Y;;;;; -2771;HEAVY RIGHT-POINTING ANGLE BRACKET ORNAMENT;Pe;0;ON;;;;;Y;;;;; -2772;LIGHT LEFT TORTOISE SHELL BRACKET ORNAMENT;Ps;0;ON;;;;;Y;;;;; -2773;LIGHT RIGHT TORTOISE SHELL BRACKET ORNAMENT;Pe;0;ON;;;;;Y;;;;; -2774;MEDIUM LEFT CURLY BRACKET ORNAMENT;Ps;0;ON;;;;;Y;;;;; -2775;MEDIUM RIGHT CURLY BRACKET ORNAMENT;Pe;0;ON;;;;;Y;;;;; -2776;DINGBAT NEGATIVE CIRCLED DIGIT ONE;No;0;ON;;;1;1;N;INVERSE CIRCLED DIGIT ONE;;;; -2777;DINGBAT NEGATIVE CIRCLED DIGIT TWO;No;0;ON;;;2;2;N;INVERSE CIRCLED DIGIT TWO;;;; -2778;DINGBAT NEGATIVE CIRCLED DIGIT THREE;No;0;ON;;;3;3;N;INVERSE CIRCLED DIGIT THREE;;;; -2779;DINGBAT NEGATIVE CIRCLED DIGIT FOUR;No;0;ON;;;4;4;N;INVERSE CIRCLED DIGIT FOUR;;;; -277A;DINGBAT NEGATIVE CIRCLED DIGIT FIVE;No;0;ON;;;5;5;N;INVERSE CIRCLED DIGIT FIVE;;;; -277B;DINGBAT NEGATIVE CIRCLED DIGIT SIX;No;0;ON;;;6;6;N;INVERSE CIRCLED DIGIT SIX;;;; -277C;DINGBAT NEGATIVE CIRCLED DIGIT SEVEN;No;0;ON;;;7;7;N;INVERSE CIRCLED DIGIT SEVEN;;;; -277D;DINGBAT NEGATIVE CIRCLED DIGIT EIGHT;No;0;ON;;;8;8;N;INVERSE CIRCLED DIGIT EIGHT;;;; -277E;DINGBAT NEGATIVE CIRCLED DIGIT NINE;No;0;ON;;;9;9;N;INVERSE CIRCLED DIGIT NINE;;;; -277F;DINGBAT NEGATIVE CIRCLED NUMBER TEN;No;0;ON;;;;10;N;INVERSE CIRCLED NUMBER TEN;;;; -2780;DINGBAT CIRCLED SANS-SERIF DIGIT ONE;No;0;ON;;;1;1;N;CIRCLED SANS-SERIF DIGIT ONE;;;; -2781;DINGBAT CIRCLED SANS-SERIF DIGIT TWO;No;0;ON;;;2;2;N;CIRCLED SANS-SERIF DIGIT TWO;;;; -2782;DINGBAT CIRCLED SANS-SERIF DIGIT THREE;No;0;ON;;;3;3;N;CIRCLED SANS-SERIF DIGIT THREE;;;; -2783;DINGBAT CIRCLED SANS-SERIF DIGIT FOUR;No;0;ON;;;4;4;N;CIRCLED SANS-SERIF DIGIT FOUR;;;; -2784;DINGBAT CIRCLED SANS-SERIF DIGIT FIVE;No;0;ON;;;5;5;N;CIRCLED SANS-SERIF DIGIT FIVE;;;; -2785;DINGBAT CIRCLED SANS-SERIF DIGIT SIX;No;0;ON;;;6;6;N;CIRCLED SANS-SERIF DIGIT SIX;;;; -2786;DINGBAT CIRCLED SANS-SERIF DIGIT SEVEN;No;0;ON;;;7;7;N;CIRCLED SANS-SERIF DIGIT SEVEN;;;; -2787;DINGBAT CIRCLED SANS-SERIF DIGIT EIGHT;No;0;ON;;;8;8;N;CIRCLED SANS-SERIF DIGIT EIGHT;;;; -2788;DINGBAT CIRCLED SANS-SERIF DIGIT NINE;No;0;ON;;;9;9;N;CIRCLED SANS-SERIF DIGIT NINE;;;; -2789;DINGBAT CIRCLED SANS-SERIF NUMBER TEN;No;0;ON;;;;10;N;CIRCLED SANS-SERIF NUMBER TEN;;;; -278A;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT ONE;No;0;ON;;;1;1;N;INVERSE CIRCLED SANS-SERIF DIGIT ONE;;;; -278B;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT TWO;No;0;ON;;;2;2;N;INVERSE CIRCLED SANS-SERIF DIGIT TWO;;;; -278C;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT THREE;No;0;ON;;;3;3;N;INVERSE CIRCLED SANS-SERIF DIGIT THREE;;;; -278D;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT FOUR;No;0;ON;;;4;4;N;INVERSE CIRCLED SANS-SERIF DIGIT FOUR;;;; -278E;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT FIVE;No;0;ON;;;5;5;N;INVERSE CIRCLED SANS-SERIF DIGIT FIVE;;;; -278F;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT SIX;No;0;ON;;;6;6;N;INVERSE CIRCLED SANS-SERIF DIGIT SIX;;;; -2790;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT SEVEN;No;0;ON;;;7;7;N;INVERSE CIRCLED SANS-SERIF DIGIT SEVEN;;;; -2791;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT EIGHT;No;0;ON;;;8;8;N;INVERSE CIRCLED SANS-SERIF DIGIT EIGHT;;;; -2792;DINGBAT NEGATIVE CIRCLED SANS-SERIF DIGIT NINE;No;0;ON;;;9;9;N;INVERSE CIRCLED SANS-SERIF DIGIT NINE;;;; -2793;DINGBAT NEGATIVE CIRCLED SANS-SERIF NUMBER TEN;No;0;ON;;;;10;N;INVERSE CIRCLED SANS-SERIF NUMBER TEN;;;; -2794;HEAVY WIDE-HEADED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY WIDE-HEADED RIGHT ARROW;;;; -2798;HEAVY SOUTH EAST ARROW;So;0;ON;;;;;N;HEAVY LOWER RIGHT ARROW;;;; -2799;HEAVY RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY RIGHT ARROW;;;; -279A;HEAVY NORTH EAST ARROW;So;0;ON;;;;;N;HEAVY UPPER RIGHT ARROW;;;; -279B;DRAFTING POINT RIGHTWARDS ARROW;So;0;ON;;;;;N;DRAFTING POINT RIGHT ARROW;;;; -279C;HEAVY ROUND-TIPPED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY ROUND-TIPPED RIGHT ARROW;;;; -279D;TRIANGLE-HEADED RIGHTWARDS ARROW;So;0;ON;;;;;N;TRIANGLE-HEADED RIGHT ARROW;;;; -279E;HEAVY TRIANGLE-HEADED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY TRIANGLE-HEADED RIGHT ARROW;;;; -279F;DASHED TRIANGLE-HEADED RIGHTWARDS ARROW;So;0;ON;;;;;N;DASHED TRIANGLE-HEADED RIGHT ARROW;;;; -27A0;HEAVY DASHED TRIANGLE-HEADED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY DASHED TRIANGLE-HEADED RIGHT ARROW;;;; -27A1;BLACK RIGHTWARDS ARROW;So;0;ON;;;;;N;BLACK RIGHT ARROW;;;; -27A2;THREE-D TOP-LIGHTED RIGHTWARDS ARROWHEAD;So;0;ON;;;;;N;THREE-D TOP-LIGHTED RIGHT ARROWHEAD;;;; -27A3;THREE-D BOTTOM-LIGHTED RIGHTWARDS ARROWHEAD;So;0;ON;;;;;N;THREE-D BOTTOM-LIGHTED RIGHT ARROWHEAD;;;; -27A4;BLACK RIGHTWARDS ARROWHEAD;So;0;ON;;;;;N;BLACK RIGHT ARROWHEAD;;;; -27A5;HEAVY BLACK CURVED DOWNWARDS AND RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY BLACK CURVED DOWN AND RIGHT ARROW;;;; -27A6;HEAVY BLACK CURVED UPWARDS AND RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY BLACK CURVED UP AND RIGHT ARROW;;;; -27A7;SQUAT BLACK RIGHTWARDS ARROW;So;0;ON;;;;;N;SQUAT BLACK RIGHT ARROW;;;; -27A8;HEAVY CONCAVE-POINTED BLACK RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY CONCAVE-POINTED BLACK RIGHT ARROW;;;; -27A9;RIGHT-SHADED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;RIGHT-SHADED WHITE RIGHT ARROW;;;; -27AA;LEFT-SHADED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;LEFT-SHADED WHITE RIGHT ARROW;;;; -27AB;BACK-TILTED SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;BACK-TILTED SHADOWED WHITE RIGHT ARROW;;;; -27AC;FRONT-TILTED SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;FRONT-TILTED SHADOWED WHITE RIGHT ARROW;;;; -27AD;HEAVY LOWER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY LOWER RIGHT-SHADOWED WHITE RIGHT ARROW;;;; -27AE;HEAVY UPPER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY UPPER RIGHT-SHADOWED WHITE RIGHT ARROW;;;; -27AF;NOTCHED LOWER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;NOTCHED LOWER RIGHT-SHADOWED WHITE RIGHT ARROW;;;; -27B1;NOTCHED UPPER RIGHT-SHADOWED WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;NOTCHED UPPER RIGHT-SHADOWED WHITE RIGHT ARROW;;;; -27B2;CIRCLED HEAVY WHITE RIGHTWARDS ARROW;So;0;ON;;;;;N;CIRCLED HEAVY WHITE RIGHT ARROW;;;; -27B3;WHITE-FEATHERED RIGHTWARDS ARROW;So;0;ON;;;;;N;WHITE-FEATHERED RIGHT ARROW;;;; -27B4;BLACK-FEATHERED SOUTH EAST ARROW;So;0;ON;;;;;N;BLACK-FEATHERED LOWER RIGHT ARROW;;;; -27B5;BLACK-FEATHERED RIGHTWARDS ARROW;So;0;ON;;;;;N;BLACK-FEATHERED RIGHT ARROW;;;; -27B6;BLACK-FEATHERED NORTH EAST ARROW;So;0;ON;;;;;N;BLACK-FEATHERED UPPER RIGHT ARROW;;;; -27B7;HEAVY BLACK-FEATHERED SOUTH EAST ARROW;So;0;ON;;;;;N;HEAVY BLACK-FEATHERED LOWER RIGHT ARROW;;;; -27B8;HEAVY BLACK-FEATHERED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY BLACK-FEATHERED RIGHT ARROW;;;; -27B9;HEAVY BLACK-FEATHERED NORTH EAST ARROW;So;0;ON;;;;;N;HEAVY BLACK-FEATHERED UPPER RIGHT ARROW;;;; -27BA;TEARDROP-BARBED RIGHTWARDS ARROW;So;0;ON;;;;;N;TEARDROP-BARBED RIGHT ARROW;;;; -27BB;HEAVY TEARDROP-SHANKED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY TEARDROP-SHANKED RIGHT ARROW;;;; -27BC;WEDGE-TAILED RIGHTWARDS ARROW;So;0;ON;;;;;N;WEDGE-TAILED RIGHT ARROW;;;; -27BD;HEAVY WEDGE-TAILED RIGHTWARDS ARROW;So;0;ON;;;;;N;HEAVY WEDGE-TAILED RIGHT ARROW;;;; -27BE;OPEN-OUTLINED RIGHTWARDS ARROW;So;0;ON;;;;;N;OPEN-OUTLINED RIGHT ARROW;;;; -27C0;THREE DIMENSIONAL ANGLE;Sm;0;ON;;;;;Y;;;;; -27C1;WHITE TRIANGLE CONTAINING SMALL WHITE TRIANGLE;Sm;0;ON;;;;;N;;;;; -27C2;PERPENDICULAR;Sm;0;ON;;;;;N;;;;; -27C3;OPEN SUBSET;Sm;0;ON;;;;;Y;;;;; -27C4;OPEN SUPERSET;Sm;0;ON;;;;;Y;;;;; -27C5;LEFT S-SHAPED BAG DELIMITER;Ps;0;ON;;;;;Y;;;;; -27C6;RIGHT S-SHAPED BAG DELIMITER;Pe;0;ON;;;;;Y;;;;; -27C7;OR WITH DOT INSIDE;Sm;0;ON;;;;;N;;;;; -27C8;REVERSE SOLIDUS PRECEDING SUBSET;Sm;0;ON;;;;;Y;;;;; -27C9;SUPERSET PRECEDING SOLIDUS;Sm;0;ON;;;;;Y;;;;; -27CA;VERTICAL BAR WITH HORIZONTAL STROKE;Sm;0;ON;;;;;N;;;;; -27CC;LONG DIVISION;Sm;0;ON;;;;;Y;;;;; -27D0;WHITE DIAMOND WITH CENTRED DOT;Sm;0;ON;;;;;N;;;;; -27D1;AND WITH DOT;Sm;0;ON;;;;;N;;;;; -27D2;ELEMENT OF OPENING UPWARDS;Sm;0;ON;;;;;N;;;;; -27D3;LOWER RIGHT CORNER WITH DOT;Sm;0;ON;;;;;Y;;;;; -27D4;UPPER LEFT CORNER WITH DOT;Sm;0;ON;;;;;Y;;;;; -27D5;LEFT OUTER JOIN;Sm;0;ON;;;;;Y;;;;; -27D6;RIGHT OUTER JOIN;Sm;0;ON;;;;;Y;;;;; -27D7;FULL OUTER JOIN;Sm;0;ON;;;;;N;;;;; -27D8;LARGE UP TACK;Sm;0;ON;;;;;N;;;;; -27D9;LARGE DOWN TACK;Sm;0;ON;;;;;N;;;;; -27DA;LEFT AND RIGHT DOUBLE TURNSTILE;Sm;0;ON;;;;;N;;;;; -27DB;LEFT AND RIGHT TACK;Sm;0;ON;;;;;N;;;;; -27DC;LEFT MULTIMAP;Sm;0;ON;;;;;Y;;;;; -27DD;LONG RIGHT TACK;Sm;0;ON;;;;;Y;;;;; -27DE;LONG LEFT TACK;Sm;0;ON;;;;;Y;;;;; -27DF;UP TACK WITH CIRCLE ABOVE;Sm;0;ON;;;;;N;;;;; -27E0;LOZENGE DIVIDED BY HORIZONTAL RULE;Sm;0;ON;;;;;N;;;;; -27E1;WHITE CONCAVE-SIDED DIAMOND;Sm;0;ON;;;;;N;;;;; -27E2;WHITE CONCAVE-SIDED DIAMOND WITH LEFTWARDS TICK;Sm;0;ON;;;;;Y;;;;; -27E3;WHITE CONCAVE-SIDED DIAMOND WITH RIGHTWARDS TICK;Sm;0;ON;;;;;Y;;;;; -27E4;WHITE SQUARE WITH LEFTWARDS TICK;Sm;0;ON;;;;;Y;;;;; -27E5;WHITE SQUARE WITH RIGHTWARDS TICK;Sm;0;ON;;;;;Y;;;;; -27E6;MATHEMATICAL LEFT WHITE SQUARE BRACKET;Ps;0;ON;;;;;Y;;;;; -27E7;MATHEMATICAL RIGHT WHITE SQUARE BRACKET;Pe;0;ON;;;;;Y;;;;; -27E8;MATHEMATICAL LEFT ANGLE BRACKET;Ps;0;ON;;;;;Y;;;;; -27E9;MATHEMATICAL RIGHT ANGLE BRACKET;Pe;0;ON;;;;;Y;;;;; -27EA;MATHEMATICAL LEFT DOUBLE ANGLE BRACKET;Ps;0;ON;;;;;Y;;;;; -27EB;MATHEMATICAL RIGHT DOUBLE ANGLE BRACKET;Pe;0;ON;;;;;Y;;;;; -27EC;MATHEMATICAL LEFT WHITE TORTOISE SHELL BRACKET;Ps;0;ON;;;;;Y;;;;; -27ED;MATHEMATICAL RIGHT WHITE TORTOISE SHELL BRACKET;Pe;0;ON;;;;;Y;;;;; -27EE;MATHEMATICAL LEFT FLATTENED PARENTHESIS;Ps;0;ON;;;;;Y;;;;; -27EF;MATHEMATICAL RIGHT FLATTENED PARENTHESIS;Pe;0;ON;;;;;Y;;;;; -27F0;UPWARDS QUADRUPLE ARROW;Sm;0;ON;;;;;N;;;;; -27F1;DOWNWARDS QUADRUPLE ARROW;Sm;0;ON;;;;;N;;;;; -27F2;ANTICLOCKWISE GAPPED CIRCLE ARROW;Sm;0;ON;;;;;N;;;;; -27F3;CLOCKWISE GAPPED CIRCLE ARROW;Sm;0;ON;;;;;N;;;;; -27F4;RIGHT ARROW WITH CIRCLED PLUS;Sm;0;ON;;;;;N;;;;; -27F5;LONG LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -27F6;LONG RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -27F7;LONG LEFT RIGHT ARROW;Sm;0;ON;;;;;N;;;;; -27F8;LONG LEFTWARDS DOUBLE ARROW;Sm;0;ON;;;;;N;;;;; -27F9;LONG RIGHTWARDS DOUBLE ARROW;Sm;0;ON;;;;;N;;;;; -27FA;LONG LEFT RIGHT DOUBLE ARROW;Sm;0;ON;;;;;N;;;;; -27FB;LONG LEFTWARDS ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -27FC;LONG RIGHTWARDS ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -27FD;LONG LEFTWARDS DOUBLE ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -27FE;LONG RIGHTWARDS DOUBLE ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -27FF;LONG RIGHTWARDS SQUIGGLE ARROW;Sm;0;ON;;;;;N;;;;; -2800;BRAILLE PATTERN BLANK;So;0;L;;;;;N;;;;; -2801;BRAILLE PATTERN DOTS-1;So;0;L;;;;;N;;;;; -2802;BRAILLE PATTERN DOTS-2;So;0;L;;;;;N;;;;; -2803;BRAILLE PATTERN DOTS-12;So;0;L;;;;;N;;;;; -2804;BRAILLE PATTERN DOTS-3;So;0;L;;;;;N;;;;; -2805;BRAILLE PATTERN DOTS-13;So;0;L;;;;;N;;;;; -2806;BRAILLE PATTERN DOTS-23;So;0;L;;;;;N;;;;; -2807;BRAILLE PATTERN DOTS-123;So;0;L;;;;;N;;;;; -2808;BRAILLE PATTERN DOTS-4;So;0;L;;;;;N;;;;; -2809;BRAILLE PATTERN DOTS-14;So;0;L;;;;;N;;;;; -280A;BRAILLE PATTERN DOTS-24;So;0;L;;;;;N;;;;; -280B;BRAILLE PATTERN DOTS-124;So;0;L;;;;;N;;;;; -280C;BRAILLE PATTERN DOTS-34;So;0;L;;;;;N;;;;; -280D;BRAILLE PATTERN DOTS-134;So;0;L;;;;;N;;;;; -280E;BRAILLE PATTERN DOTS-234;So;0;L;;;;;N;;;;; -280F;BRAILLE PATTERN DOTS-1234;So;0;L;;;;;N;;;;; -2810;BRAILLE PATTERN DOTS-5;So;0;L;;;;;N;;;;; -2811;BRAILLE PATTERN DOTS-15;So;0;L;;;;;N;;;;; -2812;BRAILLE PATTERN DOTS-25;So;0;L;;;;;N;;;;; -2813;BRAILLE PATTERN DOTS-125;So;0;L;;;;;N;;;;; -2814;BRAILLE PATTERN DOTS-35;So;0;L;;;;;N;;;;; -2815;BRAILLE PATTERN DOTS-135;So;0;L;;;;;N;;;;; -2816;BRAILLE PATTERN DOTS-235;So;0;L;;;;;N;;;;; -2817;BRAILLE PATTERN DOTS-1235;So;0;L;;;;;N;;;;; -2818;BRAILLE PATTERN DOTS-45;So;0;L;;;;;N;;;;; -2819;BRAILLE PATTERN DOTS-145;So;0;L;;;;;N;;;;; -281A;BRAILLE PATTERN DOTS-245;So;0;L;;;;;N;;;;; -281B;BRAILLE PATTERN DOTS-1245;So;0;L;;;;;N;;;;; -281C;BRAILLE PATTERN DOTS-345;So;0;L;;;;;N;;;;; -281D;BRAILLE PATTERN DOTS-1345;So;0;L;;;;;N;;;;; -281E;BRAILLE PATTERN DOTS-2345;So;0;L;;;;;N;;;;; -281F;BRAILLE PATTERN DOTS-12345;So;0;L;;;;;N;;;;; -2820;BRAILLE PATTERN DOTS-6;So;0;L;;;;;N;;;;; -2821;BRAILLE PATTERN DOTS-16;So;0;L;;;;;N;;;;; -2822;BRAILLE PATTERN DOTS-26;So;0;L;;;;;N;;;;; -2823;BRAILLE PATTERN DOTS-126;So;0;L;;;;;N;;;;; -2824;BRAILLE PATTERN DOTS-36;So;0;L;;;;;N;;;;; -2825;BRAILLE PATTERN DOTS-136;So;0;L;;;;;N;;;;; -2826;BRAILLE PATTERN DOTS-236;So;0;L;;;;;N;;;;; -2827;BRAILLE PATTERN DOTS-1236;So;0;L;;;;;N;;;;; -2828;BRAILLE PATTERN DOTS-46;So;0;L;;;;;N;;;;; -2829;BRAILLE PATTERN DOTS-146;So;0;L;;;;;N;;;;; -282A;BRAILLE PATTERN DOTS-246;So;0;L;;;;;N;;;;; -282B;BRAILLE PATTERN DOTS-1246;So;0;L;;;;;N;;;;; -282C;BRAILLE PATTERN DOTS-346;So;0;L;;;;;N;;;;; -282D;BRAILLE PATTERN DOTS-1346;So;0;L;;;;;N;;;;; -282E;BRAILLE PATTERN DOTS-2346;So;0;L;;;;;N;;;;; -282F;BRAILLE PATTERN DOTS-12346;So;0;L;;;;;N;;;;; -2830;BRAILLE PATTERN DOTS-56;So;0;L;;;;;N;;;;; -2831;BRAILLE PATTERN DOTS-156;So;0;L;;;;;N;;;;; -2832;BRAILLE PATTERN DOTS-256;So;0;L;;;;;N;;;;; -2833;BRAILLE PATTERN DOTS-1256;So;0;L;;;;;N;;;;; -2834;BRAILLE PATTERN DOTS-356;So;0;L;;;;;N;;;;; -2835;BRAILLE PATTERN DOTS-1356;So;0;L;;;;;N;;;;; -2836;BRAILLE PATTERN DOTS-2356;So;0;L;;;;;N;;;;; -2837;BRAILLE PATTERN DOTS-12356;So;0;L;;;;;N;;;;; -2838;BRAILLE PATTERN DOTS-456;So;0;L;;;;;N;;;;; -2839;BRAILLE PATTERN DOTS-1456;So;0;L;;;;;N;;;;; -283A;BRAILLE PATTERN DOTS-2456;So;0;L;;;;;N;;;;; -283B;BRAILLE PATTERN DOTS-12456;So;0;L;;;;;N;;;;; -283C;BRAILLE PATTERN DOTS-3456;So;0;L;;;;;N;;;;; -283D;BRAILLE PATTERN DOTS-13456;So;0;L;;;;;N;;;;; -283E;BRAILLE PATTERN DOTS-23456;So;0;L;;;;;N;;;;; -283F;BRAILLE PATTERN DOTS-123456;So;0;L;;;;;N;;;;; -2840;BRAILLE PATTERN DOTS-7;So;0;L;;;;;N;;;;; -2841;BRAILLE PATTERN DOTS-17;So;0;L;;;;;N;;;;; -2842;BRAILLE PATTERN DOTS-27;So;0;L;;;;;N;;;;; -2843;BRAILLE PATTERN DOTS-127;So;0;L;;;;;N;;;;; -2844;BRAILLE PATTERN DOTS-37;So;0;L;;;;;N;;;;; -2845;BRAILLE PATTERN DOTS-137;So;0;L;;;;;N;;;;; -2846;BRAILLE PATTERN DOTS-237;So;0;L;;;;;N;;;;; -2847;BRAILLE PATTERN DOTS-1237;So;0;L;;;;;N;;;;; -2848;BRAILLE PATTERN DOTS-47;So;0;L;;;;;N;;;;; -2849;BRAILLE PATTERN DOTS-147;So;0;L;;;;;N;;;;; -284A;BRAILLE PATTERN DOTS-247;So;0;L;;;;;N;;;;; -284B;BRAILLE PATTERN DOTS-1247;So;0;L;;;;;N;;;;; -284C;BRAILLE PATTERN DOTS-347;So;0;L;;;;;N;;;;; -284D;BRAILLE PATTERN DOTS-1347;So;0;L;;;;;N;;;;; -284E;BRAILLE PATTERN DOTS-2347;So;0;L;;;;;N;;;;; -284F;BRAILLE PATTERN DOTS-12347;So;0;L;;;;;N;;;;; -2850;BRAILLE PATTERN DOTS-57;So;0;L;;;;;N;;;;; -2851;BRAILLE PATTERN DOTS-157;So;0;L;;;;;N;;;;; -2852;BRAILLE PATTERN DOTS-257;So;0;L;;;;;N;;;;; -2853;BRAILLE PATTERN DOTS-1257;So;0;L;;;;;N;;;;; -2854;BRAILLE PATTERN DOTS-357;So;0;L;;;;;N;;;;; -2855;BRAILLE PATTERN DOTS-1357;So;0;L;;;;;N;;;;; -2856;BRAILLE PATTERN DOTS-2357;So;0;L;;;;;N;;;;; -2857;BRAILLE PATTERN DOTS-12357;So;0;L;;;;;N;;;;; -2858;BRAILLE PATTERN DOTS-457;So;0;L;;;;;N;;;;; -2859;BRAILLE PATTERN DOTS-1457;So;0;L;;;;;N;;;;; -285A;BRAILLE PATTERN DOTS-2457;So;0;L;;;;;N;;;;; -285B;BRAILLE PATTERN DOTS-12457;So;0;L;;;;;N;;;;; -285C;BRAILLE PATTERN DOTS-3457;So;0;L;;;;;N;;;;; -285D;BRAILLE PATTERN DOTS-13457;So;0;L;;;;;N;;;;; -285E;BRAILLE PATTERN DOTS-23457;So;0;L;;;;;N;;;;; -285F;BRAILLE PATTERN DOTS-123457;So;0;L;;;;;N;;;;; -2860;BRAILLE PATTERN DOTS-67;So;0;L;;;;;N;;;;; -2861;BRAILLE PATTERN DOTS-167;So;0;L;;;;;N;;;;; -2862;BRAILLE PATTERN DOTS-267;So;0;L;;;;;N;;;;; -2863;BRAILLE PATTERN DOTS-1267;So;0;L;;;;;N;;;;; -2864;BRAILLE PATTERN DOTS-367;So;0;L;;;;;N;;;;; -2865;BRAILLE PATTERN DOTS-1367;So;0;L;;;;;N;;;;; -2866;BRAILLE PATTERN DOTS-2367;So;0;L;;;;;N;;;;; -2867;BRAILLE PATTERN DOTS-12367;So;0;L;;;;;N;;;;; -2868;BRAILLE PATTERN DOTS-467;So;0;L;;;;;N;;;;; -2869;BRAILLE PATTERN DOTS-1467;So;0;L;;;;;N;;;;; -286A;BRAILLE PATTERN DOTS-2467;So;0;L;;;;;N;;;;; -286B;BRAILLE PATTERN DOTS-12467;So;0;L;;;;;N;;;;; -286C;BRAILLE PATTERN DOTS-3467;So;0;L;;;;;N;;;;; -286D;BRAILLE PATTERN DOTS-13467;So;0;L;;;;;N;;;;; -286E;BRAILLE PATTERN DOTS-23467;So;0;L;;;;;N;;;;; -286F;BRAILLE PATTERN DOTS-123467;So;0;L;;;;;N;;;;; -2870;BRAILLE PATTERN DOTS-567;So;0;L;;;;;N;;;;; -2871;BRAILLE PATTERN DOTS-1567;So;0;L;;;;;N;;;;; -2872;BRAILLE PATTERN DOTS-2567;So;0;L;;;;;N;;;;; -2873;BRAILLE PATTERN DOTS-12567;So;0;L;;;;;N;;;;; -2874;BRAILLE PATTERN DOTS-3567;So;0;L;;;;;N;;;;; -2875;BRAILLE PATTERN DOTS-13567;So;0;L;;;;;N;;;;; -2876;BRAILLE PATTERN DOTS-23567;So;0;L;;;;;N;;;;; -2877;BRAILLE PATTERN DOTS-123567;So;0;L;;;;;N;;;;; -2878;BRAILLE PATTERN DOTS-4567;So;0;L;;;;;N;;;;; -2879;BRAILLE PATTERN DOTS-14567;So;0;L;;;;;N;;;;; -287A;BRAILLE PATTERN DOTS-24567;So;0;L;;;;;N;;;;; -287B;BRAILLE PATTERN DOTS-124567;So;0;L;;;;;N;;;;; -287C;BRAILLE PATTERN DOTS-34567;So;0;L;;;;;N;;;;; -287D;BRAILLE PATTERN DOTS-134567;So;0;L;;;;;N;;;;; -287E;BRAILLE PATTERN DOTS-234567;So;0;L;;;;;N;;;;; -287F;BRAILLE PATTERN DOTS-1234567;So;0;L;;;;;N;;;;; -2880;BRAILLE PATTERN DOTS-8;So;0;L;;;;;N;;;;; -2881;BRAILLE PATTERN DOTS-18;So;0;L;;;;;N;;;;; -2882;BRAILLE PATTERN DOTS-28;So;0;L;;;;;N;;;;; -2883;BRAILLE PATTERN DOTS-128;So;0;L;;;;;N;;;;; -2884;BRAILLE PATTERN DOTS-38;So;0;L;;;;;N;;;;; -2885;BRAILLE PATTERN DOTS-138;So;0;L;;;;;N;;;;; -2886;BRAILLE PATTERN DOTS-238;So;0;L;;;;;N;;;;; -2887;BRAILLE PATTERN DOTS-1238;So;0;L;;;;;N;;;;; -2888;BRAILLE PATTERN DOTS-48;So;0;L;;;;;N;;;;; -2889;BRAILLE PATTERN DOTS-148;So;0;L;;;;;N;;;;; -288A;BRAILLE PATTERN DOTS-248;So;0;L;;;;;N;;;;; -288B;BRAILLE PATTERN DOTS-1248;So;0;L;;;;;N;;;;; -288C;BRAILLE PATTERN DOTS-348;So;0;L;;;;;N;;;;; -288D;BRAILLE PATTERN DOTS-1348;So;0;L;;;;;N;;;;; -288E;BRAILLE PATTERN DOTS-2348;So;0;L;;;;;N;;;;; -288F;BRAILLE PATTERN DOTS-12348;So;0;L;;;;;N;;;;; -2890;BRAILLE PATTERN DOTS-58;So;0;L;;;;;N;;;;; -2891;BRAILLE PATTERN DOTS-158;So;0;L;;;;;N;;;;; -2892;BRAILLE PATTERN DOTS-258;So;0;L;;;;;N;;;;; -2893;BRAILLE PATTERN DOTS-1258;So;0;L;;;;;N;;;;; -2894;BRAILLE PATTERN DOTS-358;So;0;L;;;;;N;;;;; -2895;BRAILLE PATTERN DOTS-1358;So;0;L;;;;;N;;;;; -2896;BRAILLE PATTERN DOTS-2358;So;0;L;;;;;N;;;;; -2897;BRAILLE PATTERN DOTS-12358;So;0;L;;;;;N;;;;; -2898;BRAILLE PATTERN DOTS-458;So;0;L;;;;;N;;;;; -2899;BRAILLE PATTERN DOTS-1458;So;0;L;;;;;N;;;;; -289A;BRAILLE PATTERN DOTS-2458;So;0;L;;;;;N;;;;; -289B;BRAILLE PATTERN DOTS-12458;So;0;L;;;;;N;;;;; -289C;BRAILLE PATTERN DOTS-3458;So;0;L;;;;;N;;;;; -289D;BRAILLE PATTERN DOTS-13458;So;0;L;;;;;N;;;;; -289E;BRAILLE PATTERN DOTS-23458;So;0;L;;;;;N;;;;; -289F;BRAILLE PATTERN DOTS-123458;So;0;L;;;;;N;;;;; -28A0;BRAILLE PATTERN DOTS-68;So;0;L;;;;;N;;;;; -28A1;BRAILLE PATTERN DOTS-168;So;0;L;;;;;N;;;;; -28A2;BRAILLE PATTERN DOTS-268;So;0;L;;;;;N;;;;; -28A3;BRAILLE PATTERN DOTS-1268;So;0;L;;;;;N;;;;; -28A4;BRAILLE PATTERN DOTS-368;So;0;L;;;;;N;;;;; -28A5;BRAILLE PATTERN DOTS-1368;So;0;L;;;;;N;;;;; -28A6;BRAILLE PATTERN DOTS-2368;So;0;L;;;;;N;;;;; -28A7;BRAILLE PATTERN DOTS-12368;So;0;L;;;;;N;;;;; -28A8;BRAILLE PATTERN DOTS-468;So;0;L;;;;;N;;;;; -28A9;BRAILLE PATTERN DOTS-1468;So;0;L;;;;;N;;;;; -28AA;BRAILLE PATTERN DOTS-2468;So;0;L;;;;;N;;;;; -28AB;BRAILLE PATTERN DOTS-12468;So;0;L;;;;;N;;;;; -28AC;BRAILLE PATTERN DOTS-3468;So;0;L;;;;;N;;;;; -28AD;BRAILLE PATTERN DOTS-13468;So;0;L;;;;;N;;;;; -28AE;BRAILLE PATTERN DOTS-23468;So;0;L;;;;;N;;;;; -28AF;BRAILLE PATTERN DOTS-123468;So;0;L;;;;;N;;;;; -28B0;BRAILLE PATTERN DOTS-568;So;0;L;;;;;N;;;;; -28B1;BRAILLE PATTERN DOTS-1568;So;0;L;;;;;N;;;;; -28B2;BRAILLE PATTERN DOTS-2568;So;0;L;;;;;N;;;;; -28B3;BRAILLE PATTERN DOTS-12568;So;0;L;;;;;N;;;;; -28B4;BRAILLE PATTERN DOTS-3568;So;0;L;;;;;N;;;;; -28B5;BRAILLE PATTERN DOTS-13568;So;0;L;;;;;N;;;;; -28B6;BRAILLE PATTERN DOTS-23568;So;0;L;;;;;N;;;;; -28B7;BRAILLE PATTERN DOTS-123568;So;0;L;;;;;N;;;;; -28B8;BRAILLE PATTERN DOTS-4568;So;0;L;;;;;N;;;;; -28B9;BRAILLE PATTERN DOTS-14568;So;0;L;;;;;N;;;;; -28BA;BRAILLE PATTERN DOTS-24568;So;0;L;;;;;N;;;;; -28BB;BRAILLE PATTERN DOTS-124568;So;0;L;;;;;N;;;;; -28BC;BRAILLE PATTERN DOTS-34568;So;0;L;;;;;N;;;;; -28BD;BRAILLE PATTERN DOTS-134568;So;0;L;;;;;N;;;;; -28BE;BRAILLE PATTERN DOTS-234568;So;0;L;;;;;N;;;;; -28BF;BRAILLE PATTERN DOTS-1234568;So;0;L;;;;;N;;;;; -28C0;BRAILLE PATTERN DOTS-78;So;0;L;;;;;N;;;;; -28C1;BRAILLE PATTERN DOTS-178;So;0;L;;;;;N;;;;; -28C2;BRAILLE PATTERN DOTS-278;So;0;L;;;;;N;;;;; -28C3;BRAILLE PATTERN DOTS-1278;So;0;L;;;;;N;;;;; -28C4;BRAILLE PATTERN DOTS-378;So;0;L;;;;;N;;;;; -28C5;BRAILLE PATTERN DOTS-1378;So;0;L;;;;;N;;;;; -28C6;BRAILLE PATTERN DOTS-2378;So;0;L;;;;;N;;;;; -28C7;BRAILLE PATTERN DOTS-12378;So;0;L;;;;;N;;;;; -28C8;BRAILLE PATTERN DOTS-478;So;0;L;;;;;N;;;;; -28C9;BRAILLE PATTERN DOTS-1478;So;0;L;;;;;N;;;;; -28CA;BRAILLE PATTERN DOTS-2478;So;0;L;;;;;N;;;;; -28CB;BRAILLE PATTERN DOTS-12478;So;0;L;;;;;N;;;;; -28CC;BRAILLE PATTERN DOTS-3478;So;0;L;;;;;N;;;;; -28CD;BRAILLE PATTERN DOTS-13478;So;0;L;;;;;N;;;;; -28CE;BRAILLE PATTERN DOTS-23478;So;0;L;;;;;N;;;;; -28CF;BRAILLE PATTERN DOTS-123478;So;0;L;;;;;N;;;;; -28D0;BRAILLE PATTERN DOTS-578;So;0;L;;;;;N;;;;; -28D1;BRAILLE PATTERN DOTS-1578;So;0;L;;;;;N;;;;; -28D2;BRAILLE PATTERN DOTS-2578;So;0;L;;;;;N;;;;; -28D3;BRAILLE PATTERN DOTS-12578;So;0;L;;;;;N;;;;; -28D4;BRAILLE PATTERN DOTS-3578;So;0;L;;;;;N;;;;; -28D5;BRAILLE PATTERN DOTS-13578;So;0;L;;;;;N;;;;; -28D6;BRAILLE PATTERN DOTS-23578;So;0;L;;;;;N;;;;; -28D7;BRAILLE PATTERN DOTS-123578;So;0;L;;;;;N;;;;; -28D8;BRAILLE PATTERN DOTS-4578;So;0;L;;;;;N;;;;; -28D9;BRAILLE PATTERN DOTS-14578;So;0;L;;;;;N;;;;; -28DA;BRAILLE PATTERN DOTS-24578;So;0;L;;;;;N;;;;; -28DB;BRAILLE PATTERN DOTS-124578;So;0;L;;;;;N;;;;; -28DC;BRAILLE PATTERN DOTS-34578;So;0;L;;;;;N;;;;; -28DD;BRAILLE PATTERN DOTS-134578;So;0;L;;;;;N;;;;; -28DE;BRAILLE PATTERN DOTS-234578;So;0;L;;;;;N;;;;; -28DF;BRAILLE PATTERN DOTS-1234578;So;0;L;;;;;N;;;;; -28E0;BRAILLE PATTERN DOTS-678;So;0;L;;;;;N;;;;; -28E1;BRAILLE PATTERN DOTS-1678;So;0;L;;;;;N;;;;; -28E2;BRAILLE PATTERN DOTS-2678;So;0;L;;;;;N;;;;; -28E3;BRAILLE PATTERN DOTS-12678;So;0;L;;;;;N;;;;; -28E4;BRAILLE PATTERN DOTS-3678;So;0;L;;;;;N;;;;; -28E5;BRAILLE PATTERN DOTS-13678;So;0;L;;;;;N;;;;; -28E6;BRAILLE PATTERN DOTS-23678;So;0;L;;;;;N;;;;; -28E7;BRAILLE PATTERN DOTS-123678;So;0;L;;;;;N;;;;; -28E8;BRAILLE PATTERN DOTS-4678;So;0;L;;;;;N;;;;; -28E9;BRAILLE PATTERN DOTS-14678;So;0;L;;;;;N;;;;; -28EA;BRAILLE PATTERN DOTS-24678;So;0;L;;;;;N;;;;; -28EB;BRAILLE PATTERN DOTS-124678;So;0;L;;;;;N;;;;; -28EC;BRAILLE PATTERN DOTS-34678;So;0;L;;;;;N;;;;; -28ED;BRAILLE PATTERN DOTS-134678;So;0;L;;;;;N;;;;; -28EE;BRAILLE PATTERN DOTS-234678;So;0;L;;;;;N;;;;; -28EF;BRAILLE PATTERN DOTS-1234678;So;0;L;;;;;N;;;;; -28F0;BRAILLE PATTERN DOTS-5678;So;0;L;;;;;N;;;;; -28F1;BRAILLE PATTERN DOTS-15678;So;0;L;;;;;N;;;;; -28F2;BRAILLE PATTERN DOTS-25678;So;0;L;;;;;N;;;;; -28F3;BRAILLE PATTERN DOTS-125678;So;0;L;;;;;N;;;;; -28F4;BRAILLE PATTERN DOTS-35678;So;0;L;;;;;N;;;;; -28F5;BRAILLE PATTERN DOTS-135678;So;0;L;;;;;N;;;;; -28F6;BRAILLE PATTERN DOTS-235678;So;0;L;;;;;N;;;;; -28F7;BRAILLE PATTERN DOTS-1235678;So;0;L;;;;;N;;;;; -28F8;BRAILLE PATTERN DOTS-45678;So;0;L;;;;;N;;;;; -28F9;BRAILLE PATTERN DOTS-145678;So;0;L;;;;;N;;;;; -28FA;BRAILLE PATTERN DOTS-245678;So;0;L;;;;;N;;;;; -28FB;BRAILLE PATTERN DOTS-1245678;So;0;L;;;;;N;;;;; -28FC;BRAILLE PATTERN DOTS-345678;So;0;L;;;;;N;;;;; -28FD;BRAILLE PATTERN DOTS-1345678;So;0;L;;;;;N;;;;; -28FE;BRAILLE PATTERN DOTS-2345678;So;0;L;;;;;N;;;;; -28FF;BRAILLE PATTERN DOTS-12345678;So;0;L;;;;;N;;;;; -2900;RIGHTWARDS TWO-HEADED ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2901;RIGHTWARDS TWO-HEADED ARROW WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2902;LEFTWARDS DOUBLE ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2903;RIGHTWARDS DOUBLE ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2904;LEFT RIGHT DOUBLE ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2905;RIGHTWARDS TWO-HEADED ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -2906;LEFTWARDS DOUBLE ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -2907;RIGHTWARDS DOUBLE ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -2908;DOWNWARDS ARROW WITH HORIZONTAL STROKE;Sm;0;ON;;;;;N;;;;; -2909;UPWARDS ARROW WITH HORIZONTAL STROKE;Sm;0;ON;;;;;N;;;;; -290A;UPWARDS TRIPLE ARROW;Sm;0;ON;;;;;N;;;;; -290B;DOWNWARDS TRIPLE ARROW;Sm;0;ON;;;;;N;;;;; -290C;LEFTWARDS DOUBLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -290D;RIGHTWARDS DOUBLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -290E;LEFTWARDS TRIPLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -290F;RIGHTWARDS TRIPLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -2910;RIGHTWARDS TWO-HEADED TRIPLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -2911;RIGHTWARDS ARROW WITH DOTTED STEM;Sm;0;ON;;;;;N;;;;; -2912;UPWARDS ARROW TO BAR;Sm;0;ON;;;;;N;;;;; -2913;DOWNWARDS ARROW TO BAR;Sm;0;ON;;;;;N;;;;; -2914;RIGHTWARDS ARROW WITH TAIL WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2915;RIGHTWARDS ARROW WITH TAIL WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2916;RIGHTWARDS TWO-HEADED ARROW WITH TAIL;Sm;0;ON;;;;;N;;;;; -2917;RIGHTWARDS TWO-HEADED ARROW WITH TAIL WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2918;RIGHTWARDS TWO-HEADED ARROW WITH TAIL WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2919;LEFTWARDS ARROW-TAIL;Sm;0;ON;;;;;N;;;;; -291A;RIGHTWARDS ARROW-TAIL;Sm;0;ON;;;;;N;;;;; -291B;LEFTWARDS DOUBLE ARROW-TAIL;Sm;0;ON;;;;;N;;;;; -291C;RIGHTWARDS DOUBLE ARROW-TAIL;Sm;0;ON;;;;;N;;;;; -291D;LEFTWARDS ARROW TO BLACK DIAMOND;Sm;0;ON;;;;;N;;;;; -291E;RIGHTWARDS ARROW TO BLACK DIAMOND;Sm;0;ON;;;;;N;;;;; -291F;LEFTWARDS ARROW FROM BAR TO BLACK DIAMOND;Sm;0;ON;;;;;N;;;;; -2920;RIGHTWARDS ARROW FROM BAR TO BLACK DIAMOND;Sm;0;ON;;;;;N;;;;; -2921;NORTH WEST AND SOUTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2922;NORTH EAST AND SOUTH WEST ARROW;Sm;0;ON;;;;;N;;;;; -2923;NORTH WEST ARROW WITH HOOK;Sm;0;ON;;;;;N;;;;; -2924;NORTH EAST ARROW WITH HOOK;Sm;0;ON;;;;;N;;;;; -2925;SOUTH EAST ARROW WITH HOOK;Sm;0;ON;;;;;N;;;;; -2926;SOUTH WEST ARROW WITH HOOK;Sm;0;ON;;;;;N;;;;; -2927;NORTH WEST ARROW AND NORTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2928;NORTH EAST ARROW AND SOUTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2929;SOUTH EAST ARROW AND SOUTH WEST ARROW;Sm;0;ON;;;;;N;;;;; -292A;SOUTH WEST ARROW AND NORTH WEST ARROW;Sm;0;ON;;;;;N;;;;; -292B;RISING DIAGONAL CROSSING FALLING DIAGONAL;Sm;0;ON;;;;;N;;;;; -292C;FALLING DIAGONAL CROSSING RISING DIAGONAL;Sm;0;ON;;;;;N;;;;; -292D;SOUTH EAST ARROW CROSSING NORTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -292E;NORTH EAST ARROW CROSSING SOUTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -292F;FALLING DIAGONAL CROSSING NORTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2930;RISING DIAGONAL CROSSING SOUTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2931;NORTH EAST ARROW CROSSING NORTH WEST ARROW;Sm;0;ON;;;;;N;;;;; -2932;NORTH WEST ARROW CROSSING NORTH EAST ARROW;Sm;0;ON;;;;;N;;;;; -2933;WAVE ARROW POINTING DIRECTLY RIGHT;Sm;0;ON;;;;;N;;;;; -2934;ARROW POINTING RIGHTWARDS THEN CURVING UPWARDS;Sm;0;ON;;;;;N;;;;; -2935;ARROW POINTING RIGHTWARDS THEN CURVING DOWNWARDS;Sm;0;ON;;;;;N;;;;; -2936;ARROW POINTING DOWNWARDS THEN CURVING LEFTWARDS;Sm;0;ON;;;;;N;;;;; -2937;ARROW POINTING DOWNWARDS THEN CURVING RIGHTWARDS;Sm;0;ON;;;;;N;;;;; -2938;RIGHT-SIDE ARC CLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -2939;LEFT-SIDE ARC ANTICLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -293A;TOP ARC ANTICLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -293B;BOTTOM ARC ANTICLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -293C;TOP ARC CLOCKWISE ARROW WITH MINUS;Sm;0;ON;;;;;N;;;;; -293D;TOP ARC ANTICLOCKWISE ARROW WITH PLUS;Sm;0;ON;;;;;N;;;;; -293E;LOWER RIGHT SEMICIRCULAR CLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -293F;LOWER LEFT SEMICIRCULAR ANTICLOCKWISE ARROW;Sm;0;ON;;;;;N;;;;; -2940;ANTICLOCKWISE CLOSED CIRCLE ARROW;Sm;0;ON;;;;;N;;;;; -2941;CLOCKWISE CLOSED CIRCLE ARROW;Sm;0;ON;;;;;N;;;;; -2942;RIGHTWARDS ARROW ABOVE SHORT LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2943;LEFTWARDS ARROW ABOVE SHORT RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2944;SHORT RIGHTWARDS ARROW ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2945;RIGHTWARDS ARROW WITH PLUS BELOW;Sm;0;ON;;;;;N;;;;; -2946;LEFTWARDS ARROW WITH PLUS BELOW;Sm;0;ON;;;;;N;;;;; -2947;RIGHTWARDS ARROW THROUGH X;Sm;0;ON;;;;;N;;;;; -2948;LEFT RIGHT ARROW THROUGH SMALL CIRCLE;Sm;0;ON;;;;;N;;;;; -2949;UPWARDS TWO-HEADED ARROW FROM SMALL CIRCLE;Sm;0;ON;;;;;N;;;;; -294A;LEFT BARB UP RIGHT BARB DOWN HARPOON;Sm;0;ON;;;;;N;;;;; -294B;LEFT BARB DOWN RIGHT BARB UP HARPOON;Sm;0;ON;;;;;N;;;;; -294C;UP BARB RIGHT DOWN BARB LEFT HARPOON;Sm;0;ON;;;;;N;;;;; -294D;UP BARB LEFT DOWN BARB RIGHT HARPOON;Sm;0;ON;;;;;N;;;;; -294E;LEFT BARB UP RIGHT BARB UP HARPOON;Sm;0;ON;;;;;N;;;;; -294F;UP BARB RIGHT DOWN BARB RIGHT HARPOON;Sm;0;ON;;;;;N;;;;; -2950;LEFT BARB DOWN RIGHT BARB DOWN HARPOON;Sm;0;ON;;;;;N;;;;; -2951;UP BARB LEFT DOWN BARB LEFT HARPOON;Sm;0;ON;;;;;N;;;;; -2952;LEFTWARDS HARPOON WITH BARB UP TO BAR;Sm;0;ON;;;;;N;;;;; -2953;RIGHTWARDS HARPOON WITH BARB UP TO BAR;Sm;0;ON;;;;;N;;;;; -2954;UPWARDS HARPOON WITH BARB RIGHT TO BAR;Sm;0;ON;;;;;N;;;;; -2955;DOWNWARDS HARPOON WITH BARB RIGHT TO BAR;Sm;0;ON;;;;;N;;;;; -2956;LEFTWARDS HARPOON WITH BARB DOWN TO BAR;Sm;0;ON;;;;;N;;;;; -2957;RIGHTWARDS HARPOON WITH BARB DOWN TO BAR;Sm;0;ON;;;;;N;;;;; -2958;UPWARDS HARPOON WITH BARB LEFT TO BAR;Sm;0;ON;;;;;N;;;;; -2959;DOWNWARDS HARPOON WITH BARB LEFT TO BAR;Sm;0;ON;;;;;N;;;;; -295A;LEFTWARDS HARPOON WITH BARB UP FROM BAR;Sm;0;ON;;;;;N;;;;; -295B;RIGHTWARDS HARPOON WITH BARB UP FROM BAR;Sm;0;ON;;;;;N;;;;; -295C;UPWARDS HARPOON WITH BARB RIGHT FROM BAR;Sm;0;ON;;;;;N;;;;; -295D;DOWNWARDS HARPOON WITH BARB RIGHT FROM BAR;Sm;0;ON;;;;;N;;;;; -295E;LEFTWARDS HARPOON WITH BARB DOWN FROM BAR;Sm;0;ON;;;;;N;;;;; -295F;RIGHTWARDS HARPOON WITH BARB DOWN FROM BAR;Sm;0;ON;;;;;N;;;;; -2960;UPWARDS HARPOON WITH BARB LEFT FROM BAR;Sm;0;ON;;;;;N;;;;; -2961;DOWNWARDS HARPOON WITH BARB LEFT FROM BAR;Sm;0;ON;;;;;N;;;;; -2962;LEFTWARDS HARPOON WITH BARB UP ABOVE LEFTWARDS HARPOON WITH BARB DOWN;Sm;0;ON;;;;;N;;;;; -2963;UPWARDS HARPOON WITH BARB LEFT BESIDE UPWARDS HARPOON WITH BARB RIGHT;Sm;0;ON;;;;;N;;;;; -2964;RIGHTWARDS HARPOON WITH BARB UP ABOVE RIGHTWARDS HARPOON WITH BARB DOWN;Sm;0;ON;;;;;N;;;;; -2965;DOWNWARDS HARPOON WITH BARB LEFT BESIDE DOWNWARDS HARPOON WITH BARB RIGHT;Sm;0;ON;;;;;N;;;;; -2966;LEFTWARDS HARPOON WITH BARB UP ABOVE RIGHTWARDS HARPOON WITH BARB UP;Sm;0;ON;;;;;N;;;;; -2967;LEFTWARDS HARPOON WITH BARB DOWN ABOVE RIGHTWARDS HARPOON WITH BARB DOWN;Sm;0;ON;;;;;N;;;;; -2968;RIGHTWARDS HARPOON WITH BARB UP ABOVE LEFTWARDS HARPOON WITH BARB UP;Sm;0;ON;;;;;N;;;;; -2969;RIGHTWARDS HARPOON WITH BARB DOWN ABOVE LEFTWARDS HARPOON WITH BARB DOWN;Sm;0;ON;;;;;N;;;;; -296A;LEFTWARDS HARPOON WITH BARB UP ABOVE LONG DASH;Sm;0;ON;;;;;N;;;;; -296B;LEFTWARDS HARPOON WITH BARB DOWN BELOW LONG DASH;Sm;0;ON;;;;;N;;;;; -296C;RIGHTWARDS HARPOON WITH BARB UP ABOVE LONG DASH;Sm;0;ON;;;;;N;;;;; -296D;RIGHTWARDS HARPOON WITH BARB DOWN BELOW LONG DASH;Sm;0;ON;;;;;N;;;;; -296E;UPWARDS HARPOON WITH BARB LEFT BESIDE DOWNWARDS HARPOON WITH BARB RIGHT;Sm;0;ON;;;;;N;;;;; -296F;DOWNWARDS HARPOON WITH BARB LEFT BESIDE UPWARDS HARPOON WITH BARB RIGHT;Sm;0;ON;;;;;N;;;;; -2970;RIGHT DOUBLE ARROW WITH ROUNDED HEAD;Sm;0;ON;;;;;N;;;;; -2971;EQUALS SIGN ABOVE RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2972;TILDE OPERATOR ABOVE RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2973;LEFTWARDS ARROW ABOVE TILDE OPERATOR;Sm;0;ON;;;;;N;;;;; -2974;RIGHTWARDS ARROW ABOVE TILDE OPERATOR;Sm;0;ON;;;;;N;;;;; -2975;RIGHTWARDS ARROW ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;N;;;;; -2976;LESS-THAN ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2977;LEFTWARDS ARROW THROUGH LESS-THAN;Sm;0;ON;;;;;N;;;;; -2978;GREATER-THAN ABOVE RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2979;SUBSET ABOVE RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -297A;LEFTWARDS ARROW THROUGH SUBSET;Sm;0;ON;;;;;N;;;;; -297B;SUPERSET ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -297C;LEFT FISH TAIL;Sm;0;ON;;;;;N;;;;; -297D;RIGHT FISH TAIL;Sm;0;ON;;;;;N;;;;; -297E;UP FISH TAIL;Sm;0;ON;;;;;N;;;;; -297F;DOWN FISH TAIL;Sm;0;ON;;;;;N;;;;; -2980;TRIPLE VERTICAL BAR DELIMITER;Sm;0;ON;;;;;N;;;;; -2981;Z NOTATION SPOT;Sm;0;ON;;;;;N;;;;; -2982;Z NOTATION TYPE COLON;Sm;0;ON;;;;;N;;;;; -2983;LEFT WHITE CURLY BRACKET;Ps;0;ON;;;;;Y;;;;; -2984;RIGHT WHITE CURLY BRACKET;Pe;0;ON;;;;;Y;;;;; -2985;LEFT WHITE PARENTHESIS;Ps;0;ON;;;;;Y;;;;; -2986;RIGHT WHITE PARENTHESIS;Pe;0;ON;;;;;Y;;;;; -2987;Z NOTATION LEFT IMAGE BRACKET;Ps;0;ON;;;;;Y;;;;; -2988;Z NOTATION RIGHT IMAGE BRACKET;Pe;0;ON;;;;;Y;;;;; -2989;Z NOTATION LEFT BINDING BRACKET;Ps;0;ON;;;;;Y;;;;; -298A;Z NOTATION RIGHT BINDING BRACKET;Pe;0;ON;;;;;Y;;;;; -298B;LEFT SQUARE BRACKET WITH UNDERBAR;Ps;0;ON;;;;;Y;;;;; -298C;RIGHT SQUARE BRACKET WITH UNDERBAR;Pe;0;ON;;;;;Y;;;;; -298D;LEFT SQUARE BRACKET WITH TICK IN TOP CORNER;Ps;0;ON;;;;;Y;;;;; -298E;RIGHT SQUARE BRACKET WITH TICK IN BOTTOM CORNER;Pe;0;ON;;;;;Y;;;;; -298F;LEFT SQUARE BRACKET WITH TICK IN BOTTOM CORNER;Ps;0;ON;;;;;Y;;;;; -2990;RIGHT SQUARE BRACKET WITH TICK IN TOP CORNER;Pe;0;ON;;;;;Y;;;;; -2991;LEFT ANGLE BRACKET WITH DOT;Ps;0;ON;;;;;Y;;;;; -2992;RIGHT ANGLE BRACKET WITH DOT;Pe;0;ON;;;;;Y;;;;; -2993;LEFT ARC LESS-THAN BRACKET;Ps;0;ON;;;;;Y;;;;; -2994;RIGHT ARC GREATER-THAN BRACKET;Pe;0;ON;;;;;Y;;;;; -2995;DOUBLE LEFT ARC GREATER-THAN BRACKET;Ps;0;ON;;;;;Y;;;;; -2996;DOUBLE RIGHT ARC LESS-THAN BRACKET;Pe;0;ON;;;;;Y;;;;; -2997;LEFT BLACK TORTOISE SHELL BRACKET;Ps;0;ON;;;;;Y;;;;; -2998;RIGHT BLACK TORTOISE SHELL BRACKET;Pe;0;ON;;;;;Y;;;;; -2999;DOTTED FENCE;Sm;0;ON;;;;;N;;;;; -299A;VERTICAL ZIGZAG LINE;Sm;0;ON;;;;;N;;;;; -299B;MEASURED ANGLE OPENING LEFT;Sm;0;ON;;;;;Y;;;;; -299C;RIGHT ANGLE VARIANT WITH SQUARE;Sm;0;ON;;;;;Y;;;;; -299D;MEASURED RIGHT ANGLE WITH DOT;Sm;0;ON;;;;;Y;;;;; -299E;ANGLE WITH S INSIDE;Sm;0;ON;;;;;Y;;;;; -299F;ACUTE ANGLE;Sm;0;ON;;;;;Y;;;;; -29A0;SPHERICAL ANGLE OPENING LEFT;Sm;0;ON;;;;;Y;;;;; -29A1;SPHERICAL ANGLE OPENING UP;Sm;0;ON;;;;;Y;;;;; -29A2;TURNED ANGLE;Sm;0;ON;;;;;Y;;;;; -29A3;REVERSED ANGLE;Sm;0;ON;;;;;Y;;;;; -29A4;ANGLE WITH UNDERBAR;Sm;0;ON;;;;;Y;;;;; -29A5;REVERSED ANGLE WITH UNDERBAR;Sm;0;ON;;;;;Y;;;;; -29A6;OBLIQUE ANGLE OPENING UP;Sm;0;ON;;;;;Y;;;;; -29A7;OBLIQUE ANGLE OPENING DOWN;Sm;0;ON;;;;;Y;;;;; -29A8;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING UP AND RIGHT;Sm;0;ON;;;;;Y;;;;; -29A9;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING UP AND LEFT;Sm;0;ON;;;;;Y;;;;; -29AA;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING DOWN AND RIGHT;Sm;0;ON;;;;;Y;;;;; -29AB;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING DOWN AND LEFT;Sm;0;ON;;;;;Y;;;;; -29AC;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING RIGHT AND UP;Sm;0;ON;;;;;Y;;;;; -29AD;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING LEFT AND UP;Sm;0;ON;;;;;Y;;;;; -29AE;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING RIGHT AND DOWN;Sm;0;ON;;;;;Y;;;;; -29AF;MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW POINTING LEFT AND DOWN;Sm;0;ON;;;;;Y;;;;; -29B0;REVERSED EMPTY SET;Sm;0;ON;;;;;N;;;;; -29B1;EMPTY SET WITH OVERBAR;Sm;0;ON;;;;;N;;;;; -29B2;EMPTY SET WITH SMALL CIRCLE ABOVE;Sm;0;ON;;;;;N;;;;; -29B3;EMPTY SET WITH RIGHT ARROW ABOVE;Sm;0;ON;;;;;N;;;;; -29B4;EMPTY SET WITH LEFT ARROW ABOVE;Sm;0;ON;;;;;N;;;;; -29B5;CIRCLE WITH HORIZONTAL BAR;Sm;0;ON;;;;;N;;;;; -29B6;CIRCLED VERTICAL BAR;Sm;0;ON;;;;;N;;;;; -29B7;CIRCLED PARALLEL;Sm;0;ON;;;;;N;;;;; -29B8;CIRCLED REVERSE SOLIDUS;Sm;0;ON;;;;;Y;;;;; -29B9;CIRCLED PERPENDICULAR;Sm;0;ON;;;;;N;;;;; -29BA;CIRCLE DIVIDED BY HORIZONTAL BAR AND TOP HALF DIVIDED BY VERTICAL BAR;Sm;0;ON;;;;;N;;;;; -29BB;CIRCLE WITH SUPERIMPOSED X;Sm;0;ON;;;;;N;;;;; -29BC;CIRCLED ANTICLOCKWISE-ROTATED DIVISION SIGN;Sm;0;ON;;;;;N;;;;; -29BD;UP ARROW THROUGH CIRCLE;Sm;0;ON;;;;;N;;;;; -29BE;CIRCLED WHITE BULLET;Sm;0;ON;;;;;N;;;;; -29BF;CIRCLED BULLET;Sm;0;ON;;;;;N;;;;; -29C0;CIRCLED LESS-THAN;Sm;0;ON;;;;;Y;;;;; -29C1;CIRCLED GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -29C2;CIRCLE WITH SMALL CIRCLE TO THE RIGHT;Sm;0;ON;;;;;Y;;;;; -29C3;CIRCLE WITH TWO HORIZONTAL STROKES TO THE RIGHT;Sm;0;ON;;;;;Y;;;;; -29C4;SQUARED RISING DIAGONAL SLASH;Sm;0;ON;;;;;Y;;;;; -29C5;SQUARED FALLING DIAGONAL SLASH;Sm;0;ON;;;;;Y;;;;; -29C6;SQUARED ASTERISK;Sm;0;ON;;;;;N;;;;; -29C7;SQUARED SMALL CIRCLE;Sm;0;ON;;;;;N;;;;; -29C8;SQUARED SQUARE;Sm;0;ON;;;;;N;;;;; -29C9;TWO JOINED SQUARES;Sm;0;ON;;;;;Y;;;;; -29CA;TRIANGLE WITH DOT ABOVE;Sm;0;ON;;;;;N;;;;; -29CB;TRIANGLE WITH UNDERBAR;Sm;0;ON;;;;;N;;;;; -29CC;S IN TRIANGLE;Sm;0;ON;;;;;N;;;;; -29CD;TRIANGLE WITH SERIFS AT BOTTOM;Sm;0;ON;;;;;N;;;;; -29CE;RIGHT TRIANGLE ABOVE LEFT TRIANGLE;Sm;0;ON;;;;;Y;;;;; -29CF;LEFT TRIANGLE BESIDE VERTICAL BAR;Sm;0;ON;;;;;Y;;;;; -29D0;VERTICAL BAR BESIDE RIGHT TRIANGLE;Sm;0;ON;;;;;Y;;;;; -29D1;BOWTIE WITH LEFT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29D2;BOWTIE WITH RIGHT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29D3;BLACK BOWTIE;Sm;0;ON;;;;;N;;;;; -29D4;TIMES WITH LEFT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29D5;TIMES WITH RIGHT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29D6;WHITE HOURGLASS;Sm;0;ON;;;;;N;;;;; -29D7;BLACK HOURGLASS;Sm;0;ON;;;;;N;;;;; -29D8;LEFT WIGGLY FENCE;Ps;0;ON;;;;;Y;;;;; -29D9;RIGHT WIGGLY FENCE;Pe;0;ON;;;;;Y;;;;; -29DA;LEFT DOUBLE WIGGLY FENCE;Ps;0;ON;;;;;Y;;;;; -29DB;RIGHT DOUBLE WIGGLY FENCE;Pe;0;ON;;;;;Y;;;;; -29DC;INCOMPLETE INFINITY;Sm;0;ON;;;;;Y;;;;; -29DD;TIE OVER INFINITY;Sm;0;ON;;;;;N;;;;; -29DE;INFINITY NEGATED WITH VERTICAL BAR;Sm;0;ON;;;;;N;;;;; -29DF;DOUBLE-ENDED MULTIMAP;Sm;0;ON;;;;;N;;;;; -29E0;SQUARE WITH CONTOURED OUTLINE;Sm;0;ON;;;;;N;;;;; -29E1;INCREASES AS;Sm;0;ON;;;;;Y;;;;; -29E2;SHUFFLE PRODUCT;Sm;0;ON;;;;;N;;;;; -29E3;EQUALS SIGN AND SLANTED PARALLEL;Sm;0;ON;;;;;Y;;;;; -29E4;EQUALS SIGN AND SLANTED PARALLEL WITH TILDE ABOVE;Sm;0;ON;;;;;Y;;;;; -29E5;IDENTICAL TO AND SLANTED PARALLEL;Sm;0;ON;;;;;Y;;;;; -29E6;GLEICH STARK;Sm;0;ON;;;;;N;;;;; -29E7;THERMODYNAMIC;Sm;0;ON;;;;;N;;;;; -29E8;DOWN-POINTING TRIANGLE WITH LEFT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29E9;DOWN-POINTING TRIANGLE WITH RIGHT HALF BLACK;Sm;0;ON;;;;;Y;;;;; -29EA;BLACK DIAMOND WITH DOWN ARROW;Sm;0;ON;;;;;N;;;;; -29EB;BLACK LOZENGE;Sm;0;ON;;;;;N;;;;; -29EC;WHITE CIRCLE WITH DOWN ARROW;Sm;0;ON;;;;;N;;;;; -29ED;BLACK CIRCLE WITH DOWN ARROW;Sm;0;ON;;;;;N;;;;; -29EE;ERROR-BARRED WHITE SQUARE;Sm;0;ON;;;;;N;;;;; -29EF;ERROR-BARRED BLACK SQUARE;Sm;0;ON;;;;;N;;;;; -29F0;ERROR-BARRED WHITE DIAMOND;Sm;0;ON;;;;;N;;;;; -29F1;ERROR-BARRED BLACK DIAMOND;Sm;0;ON;;;;;N;;;;; -29F2;ERROR-BARRED WHITE CIRCLE;Sm;0;ON;;;;;N;;;;; -29F3;ERROR-BARRED BLACK CIRCLE;Sm;0;ON;;;;;N;;;;; -29F4;RULE-DELAYED;Sm;0;ON;;;;;Y;;;;; -29F5;REVERSE SOLIDUS OPERATOR;Sm;0;ON;;;;;Y;;;;; -29F6;SOLIDUS WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -29F7;REVERSE SOLIDUS WITH HORIZONTAL STROKE;Sm;0;ON;;;;;Y;;;;; -29F8;BIG SOLIDUS;Sm;0;ON;;;;;Y;;;;; -29F9;BIG REVERSE SOLIDUS;Sm;0;ON;;;;;Y;;;;; -29FA;DOUBLE PLUS;Sm;0;ON;;;;;N;;;;; -29FB;TRIPLE PLUS;Sm;0;ON;;;;;N;;;;; -29FC;LEFT-POINTING CURVED ANGLE BRACKET;Ps;0;ON;;;;;Y;;;;; -29FD;RIGHT-POINTING CURVED ANGLE BRACKET;Pe;0;ON;;;;;Y;;;;; -29FE;TINY;Sm;0;ON;;;;;N;;;;; -29FF;MINY;Sm;0;ON;;;;;N;;;;; -2A00;N-ARY CIRCLED DOT OPERATOR;Sm;0;ON;;;;;N;;;;; -2A01;N-ARY CIRCLED PLUS OPERATOR;Sm;0;ON;;;;;N;;;;; -2A02;N-ARY CIRCLED TIMES OPERATOR;Sm;0;ON;;;;;N;;;;; -2A03;N-ARY UNION OPERATOR WITH DOT;Sm;0;ON;;;;;N;;;;; -2A04;N-ARY UNION OPERATOR WITH PLUS;Sm;0;ON;;;;;N;;;;; -2A05;N-ARY SQUARE INTERSECTION OPERATOR;Sm;0;ON;;;;;N;;;;; -2A06;N-ARY SQUARE UNION OPERATOR;Sm;0;ON;;;;;N;;;;; -2A07;TWO LOGICAL AND OPERATOR;Sm;0;ON;;;;;N;;;;; -2A08;TWO LOGICAL OR OPERATOR;Sm;0;ON;;;;;N;;;;; -2A09;N-ARY TIMES OPERATOR;Sm;0;ON;;;;;N;;;;; -2A0A;MODULO TWO SUM;Sm;0;ON;;;;;Y;;;;; -2A0B;SUMMATION WITH INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2A0C;QUADRUPLE INTEGRAL OPERATOR;Sm;0;ON; 222B 222B 222B 222B;;;;Y;;;;; -2A0D;FINITE PART INTEGRAL;Sm;0;ON;;;;;Y;;;;; -2A0E;INTEGRAL WITH DOUBLE STROKE;Sm;0;ON;;;;;Y;;;;; -2A0F;INTEGRAL AVERAGE WITH SLASH;Sm;0;ON;;;;;Y;;;;; -2A10;CIRCULATION FUNCTION;Sm;0;ON;;;;;Y;;;;; -2A11;ANTICLOCKWISE INTEGRATION;Sm;0;ON;;;;;Y;;;;; -2A12;LINE INTEGRATION WITH RECTANGULAR PATH AROUND POLE;Sm;0;ON;;;;;Y;;;;; -2A13;LINE INTEGRATION WITH SEMICIRCULAR PATH AROUND POLE;Sm;0;ON;;;;;Y;;;;; -2A14;LINE INTEGRATION NOT INCLUDING THE POLE;Sm;0;ON;;;;;Y;;;;; -2A15;INTEGRAL AROUND A POINT OPERATOR;Sm;0;ON;;;;;Y;;;;; -2A16;QUATERNION INTEGRAL OPERATOR;Sm;0;ON;;;;;Y;;;;; -2A17;INTEGRAL WITH LEFTWARDS ARROW WITH HOOK;Sm;0;ON;;;;;Y;;;;; -2A18;INTEGRAL WITH TIMES SIGN;Sm;0;ON;;;;;Y;;;;; -2A19;INTEGRAL WITH INTERSECTION;Sm;0;ON;;;;;Y;;;;; -2A1A;INTEGRAL WITH UNION;Sm;0;ON;;;;;Y;;;;; -2A1B;INTEGRAL WITH OVERBAR;Sm;0;ON;;;;;Y;;;;; -2A1C;INTEGRAL WITH UNDERBAR;Sm;0;ON;;;;;Y;;;;; -2A1D;JOIN;Sm;0;ON;;;;;N;;;;; -2A1E;LARGE LEFT TRIANGLE OPERATOR;Sm;0;ON;;;;;Y;;;;; -2A1F;Z NOTATION SCHEMA COMPOSITION;Sm;0;ON;;;;;Y;;;;; -2A20;Z NOTATION SCHEMA PIPING;Sm;0;ON;;;;;Y;;;;; -2A21;Z NOTATION SCHEMA PROJECTION;Sm;0;ON;;;;;Y;;;;; -2A22;PLUS SIGN WITH SMALL CIRCLE ABOVE;Sm;0;ON;;;;;N;;;;; -2A23;PLUS SIGN WITH CIRCUMFLEX ACCENT ABOVE;Sm;0;ON;;;;;N;;;;; -2A24;PLUS SIGN WITH TILDE ABOVE;Sm;0;ON;;;;;Y;;;;; -2A25;PLUS SIGN WITH DOT BELOW;Sm;0;ON;;;;;N;;;;; -2A26;PLUS SIGN WITH TILDE BELOW;Sm;0;ON;;;;;Y;;;;; -2A27;PLUS SIGN WITH SUBSCRIPT TWO;Sm;0;ON;;;;;N;;;;; -2A28;PLUS SIGN WITH BLACK TRIANGLE;Sm;0;ON;;;;;N;;;;; -2A29;MINUS SIGN WITH COMMA ABOVE;Sm;0;ON;;;;;Y;;;;; -2A2A;MINUS SIGN WITH DOT BELOW;Sm;0;ON;;;;;N;;;;; -2A2B;MINUS SIGN WITH FALLING DOTS;Sm;0;ON;;;;;Y;;;;; -2A2C;MINUS SIGN WITH RISING DOTS;Sm;0;ON;;;;;Y;;;;; -2A2D;PLUS SIGN IN LEFT HALF CIRCLE;Sm;0;ON;;;;;Y;;;;; -2A2E;PLUS SIGN IN RIGHT HALF CIRCLE;Sm;0;ON;;;;;Y;;;;; -2A2F;VECTOR OR CROSS PRODUCT;Sm;0;ON;;;;;N;;;;; -2A30;MULTIPLICATION SIGN WITH DOT ABOVE;Sm;0;ON;;;;;N;;;;; -2A31;MULTIPLICATION SIGN WITH UNDERBAR;Sm;0;ON;;;;;N;;;;; -2A32;SEMIDIRECT PRODUCT WITH BOTTOM CLOSED;Sm;0;ON;;;;;N;;;;; -2A33;SMASH PRODUCT;Sm;0;ON;;;;;N;;;;; -2A34;MULTIPLICATION SIGN IN LEFT HALF CIRCLE;Sm;0;ON;;;;;Y;;;;; -2A35;MULTIPLICATION SIGN IN RIGHT HALF CIRCLE;Sm;0;ON;;;;;Y;;;;; -2A36;CIRCLED MULTIPLICATION SIGN WITH CIRCUMFLEX ACCENT;Sm;0;ON;;;;;N;;;;; -2A37;MULTIPLICATION SIGN IN DOUBLE CIRCLE;Sm;0;ON;;;;;N;;;;; -2A38;CIRCLED DIVISION SIGN;Sm;0;ON;;;;;N;;;;; -2A39;PLUS SIGN IN TRIANGLE;Sm;0;ON;;;;;N;;;;; -2A3A;MINUS SIGN IN TRIANGLE;Sm;0;ON;;;;;N;;;;; -2A3B;MULTIPLICATION SIGN IN TRIANGLE;Sm;0;ON;;;;;N;;;;; -2A3C;INTERIOR PRODUCT;Sm;0;ON;;;;;Y;;;;; -2A3D;RIGHTHAND INTERIOR PRODUCT;Sm;0;ON;;;;;Y;;;;; -2A3E;Z NOTATION RELATIONAL COMPOSITION;Sm;0;ON;;;;;Y;;;;; -2A3F;AMALGAMATION OR COPRODUCT;Sm;0;ON;;;;;N;;;;; -2A40;INTERSECTION WITH DOT;Sm;0;ON;;;;;N;;;;; -2A41;UNION WITH MINUS SIGN;Sm;0;ON;;;;;N;;;;; -2A42;UNION WITH OVERBAR;Sm;0;ON;;;;;N;;;;; -2A43;INTERSECTION WITH OVERBAR;Sm;0;ON;;;;;N;;;;; -2A44;INTERSECTION WITH LOGICAL AND;Sm;0;ON;;;;;N;;;;; -2A45;UNION WITH LOGICAL OR;Sm;0;ON;;;;;N;;;;; -2A46;UNION ABOVE INTERSECTION;Sm;0;ON;;;;;N;;;;; -2A47;INTERSECTION ABOVE UNION;Sm;0;ON;;;;;N;;;;; -2A48;UNION ABOVE BAR ABOVE INTERSECTION;Sm;0;ON;;;;;N;;;;; -2A49;INTERSECTION ABOVE BAR ABOVE UNION;Sm;0;ON;;;;;N;;;;; -2A4A;UNION BESIDE AND JOINED WITH UNION;Sm;0;ON;;;;;N;;;;; -2A4B;INTERSECTION BESIDE AND JOINED WITH INTERSECTION;Sm;0;ON;;;;;N;;;;; -2A4C;CLOSED UNION WITH SERIFS;Sm;0;ON;;;;;N;;;;; -2A4D;CLOSED INTERSECTION WITH SERIFS;Sm;0;ON;;;;;N;;;;; -2A4E;DOUBLE SQUARE INTERSECTION;Sm;0;ON;;;;;N;;;;; -2A4F;DOUBLE SQUARE UNION;Sm;0;ON;;;;;N;;;;; -2A50;CLOSED UNION WITH SERIFS AND SMASH PRODUCT;Sm;0;ON;;;;;N;;;;; -2A51;LOGICAL AND WITH DOT ABOVE;Sm;0;ON;;;;;N;;;;; -2A52;LOGICAL OR WITH DOT ABOVE;Sm;0;ON;;;;;N;;;;; -2A53;DOUBLE LOGICAL AND;Sm;0;ON;;;;;N;;;;; -2A54;DOUBLE LOGICAL OR;Sm;0;ON;;;;;N;;;;; -2A55;TWO INTERSECTING LOGICAL AND;Sm;0;ON;;;;;N;;;;; -2A56;TWO INTERSECTING LOGICAL OR;Sm;0;ON;;;;;N;;;;; -2A57;SLOPING LARGE OR;Sm;0;ON;;;;;Y;;;;; -2A58;SLOPING LARGE AND;Sm;0;ON;;;;;Y;;;;; -2A59;LOGICAL OR OVERLAPPING LOGICAL AND;Sm;0;ON;;;;;N;;;;; -2A5A;LOGICAL AND WITH MIDDLE STEM;Sm;0;ON;;;;;N;;;;; -2A5B;LOGICAL OR WITH MIDDLE STEM;Sm;0;ON;;;;;N;;;;; -2A5C;LOGICAL AND WITH HORIZONTAL DASH;Sm;0;ON;;;;;N;;;;; -2A5D;LOGICAL OR WITH HORIZONTAL DASH;Sm;0;ON;;;;;N;;;;; -2A5E;LOGICAL AND WITH DOUBLE OVERBAR;Sm;0;ON;;;;;N;;;;; -2A5F;LOGICAL AND WITH UNDERBAR;Sm;0;ON;;;;;N;;;;; -2A60;LOGICAL AND WITH DOUBLE UNDERBAR;Sm;0;ON;;;;;N;;;;; -2A61;SMALL VEE WITH UNDERBAR;Sm;0;ON;;;;;N;;;;; -2A62;LOGICAL OR WITH DOUBLE OVERBAR;Sm;0;ON;;;;;N;;;;; -2A63;LOGICAL OR WITH DOUBLE UNDERBAR;Sm;0;ON;;;;;N;;;;; -2A64;Z NOTATION DOMAIN ANTIRESTRICTION;Sm;0;ON;;;;;Y;;;;; -2A65;Z NOTATION RANGE ANTIRESTRICTION;Sm;0;ON;;;;;Y;;;;; -2A66;EQUALS SIGN WITH DOT BELOW;Sm;0;ON;;;;;N;;;;; -2A67;IDENTICAL WITH DOT ABOVE;Sm;0;ON;;;;;N;;;;; -2A68;TRIPLE HORIZONTAL BAR WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2A69;TRIPLE HORIZONTAL BAR WITH TRIPLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2A6A;TILDE OPERATOR WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2A6B;TILDE OPERATOR WITH RISING DOTS;Sm;0;ON;;;;;Y;;;;; -2A6C;SIMILAR MINUS SIMILAR;Sm;0;ON;;;;;Y;;;;; -2A6D;CONGRUENT WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2A6E;EQUALS WITH ASTERISK;Sm;0;ON;;;;;N;;;;; -2A6F;ALMOST EQUAL TO WITH CIRCUMFLEX ACCENT;Sm;0;ON;;;;;Y;;;;; -2A70;APPROXIMATELY EQUAL OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2A71;EQUALS SIGN ABOVE PLUS SIGN;Sm;0;ON;;;;;N;;;;; -2A72;PLUS SIGN ABOVE EQUALS SIGN;Sm;0;ON;;;;;N;;;;; -2A73;EQUALS SIGN ABOVE TILDE OPERATOR;Sm;0;ON;;;;;Y;;;;; -2A74;DOUBLE COLON EQUAL;Sm;0;ON; 003A 003A 003D;;;;Y;;;;; -2A75;TWO CONSECUTIVE EQUALS SIGNS;Sm;0;ON; 003D 003D;;;;N;;;;; -2A76;THREE CONSECUTIVE EQUALS SIGNS;Sm;0;ON; 003D 003D 003D;;;;N;;;;; -2A77;EQUALS SIGN WITH TWO DOTS ABOVE AND TWO DOTS BELOW;Sm;0;ON;;;;;N;;;;; -2A78;EQUIVALENT WITH FOUR DOTS ABOVE;Sm;0;ON;;;;;N;;;;; -2A79;LESS-THAN WITH CIRCLE INSIDE;Sm;0;ON;;;;;Y;;;;; -2A7A;GREATER-THAN WITH CIRCLE INSIDE;Sm;0;ON;;;;;Y;;;;; -2A7B;LESS-THAN WITH QUESTION MARK ABOVE;Sm;0;ON;;;;;Y;;;;; -2A7C;GREATER-THAN WITH QUESTION MARK ABOVE;Sm;0;ON;;;;;Y;;;;; -2A7D;LESS-THAN OR SLANTED EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2A7E;GREATER-THAN OR SLANTED EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2A7F;LESS-THAN OR SLANTED EQUAL TO WITH DOT INSIDE;Sm;0;ON;;;;;Y;;;;; -2A80;GREATER-THAN OR SLANTED EQUAL TO WITH DOT INSIDE;Sm;0;ON;;;;;Y;;;;; -2A81;LESS-THAN OR SLANTED EQUAL TO WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2A82;GREATER-THAN OR SLANTED EQUAL TO WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2A83;LESS-THAN OR SLANTED EQUAL TO WITH DOT ABOVE RIGHT;Sm;0;ON;;;;;Y;;;;; -2A84;GREATER-THAN OR SLANTED EQUAL TO WITH DOT ABOVE LEFT;Sm;0;ON;;;;;Y;;;;; -2A85;LESS-THAN OR APPROXIMATE;Sm;0;ON;;;;;Y;;;;; -2A86;GREATER-THAN OR APPROXIMATE;Sm;0;ON;;;;;Y;;;;; -2A87;LESS-THAN AND SINGLE-LINE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2A88;GREATER-THAN AND SINGLE-LINE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2A89;LESS-THAN AND NOT APPROXIMATE;Sm;0;ON;;;;;Y;;;;; -2A8A;GREATER-THAN AND NOT APPROXIMATE;Sm;0;ON;;;;;Y;;;;; -2A8B;LESS-THAN ABOVE DOUBLE-LINE EQUAL ABOVE GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A8C;GREATER-THAN ABOVE DOUBLE-LINE EQUAL ABOVE LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A8D;LESS-THAN ABOVE SIMILAR OR EQUAL;Sm;0;ON;;;;;Y;;;;; -2A8E;GREATER-THAN ABOVE SIMILAR OR EQUAL;Sm;0;ON;;;;;Y;;;;; -2A8F;LESS-THAN ABOVE SIMILAR ABOVE GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A90;GREATER-THAN ABOVE SIMILAR ABOVE LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A91;LESS-THAN ABOVE GREATER-THAN ABOVE DOUBLE-LINE EQUAL;Sm;0;ON;;;;;Y;;;;; -2A92;GREATER-THAN ABOVE LESS-THAN ABOVE DOUBLE-LINE EQUAL;Sm;0;ON;;;;;Y;;;;; -2A93;LESS-THAN ABOVE SLANTED EQUAL ABOVE GREATER-THAN ABOVE SLANTED EQUAL;Sm;0;ON;;;;;Y;;;;; -2A94;GREATER-THAN ABOVE SLANTED EQUAL ABOVE LESS-THAN ABOVE SLANTED EQUAL;Sm;0;ON;;;;;Y;;;;; -2A95;SLANTED EQUAL TO OR LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A96;SLANTED EQUAL TO OR GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A97;SLANTED EQUAL TO OR LESS-THAN WITH DOT INSIDE;Sm;0;ON;;;;;Y;;;;; -2A98;SLANTED EQUAL TO OR GREATER-THAN WITH DOT INSIDE;Sm;0;ON;;;;;Y;;;;; -2A99;DOUBLE-LINE EQUAL TO OR LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A9A;DOUBLE-LINE EQUAL TO OR GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A9B;DOUBLE-LINE SLANTED EQUAL TO OR LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A9C;DOUBLE-LINE SLANTED EQUAL TO OR GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A9D;SIMILAR OR LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2A9E;SIMILAR OR GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2A9F;SIMILAR ABOVE LESS-THAN ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AA0;SIMILAR ABOVE GREATER-THAN ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AA1;DOUBLE NESTED LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2AA2;DOUBLE NESTED GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2AA3;DOUBLE NESTED LESS-THAN WITH UNDERBAR;Sm;0;ON;;;;;Y;;;;; -2AA4;GREATER-THAN OVERLAPPING LESS-THAN;Sm;0;ON;;;;;N;;;;; -2AA5;GREATER-THAN BESIDE LESS-THAN;Sm;0;ON;;;;;N;;;;; -2AA6;LESS-THAN CLOSED BY CURVE;Sm;0;ON;;;;;Y;;;;; -2AA7;GREATER-THAN CLOSED BY CURVE;Sm;0;ON;;;;;Y;;;;; -2AA8;LESS-THAN CLOSED BY CURVE ABOVE SLANTED EQUAL;Sm;0;ON;;;;;Y;;;;; -2AA9;GREATER-THAN CLOSED BY CURVE ABOVE SLANTED EQUAL;Sm;0;ON;;;;;Y;;;;; -2AAA;SMALLER THAN;Sm;0;ON;;;;;Y;;;;; -2AAB;LARGER THAN;Sm;0;ON;;;;;Y;;;;; -2AAC;SMALLER THAN OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AAD;LARGER THAN OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AAE;EQUALS SIGN WITH BUMPY ABOVE;Sm;0;ON;;;;;N;;;;; -2AAF;PRECEDES ABOVE SINGLE-LINE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AB0;SUCCEEDS ABOVE SINGLE-LINE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AB1;PRECEDES ABOVE SINGLE-LINE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB2;SUCCEEDS ABOVE SINGLE-LINE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB3;PRECEDES ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AB4;SUCCEEDS ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AB5;PRECEDES ABOVE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB6;SUCCEEDS ABOVE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB7;PRECEDES ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB8;SUCCEEDS ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AB9;PRECEDES ABOVE NOT ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ABA;SUCCEEDS ABOVE NOT ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ABB;DOUBLE PRECEDES;Sm;0;ON;;;;;Y;;;;; -2ABC;DOUBLE SUCCEEDS;Sm;0;ON;;;;;Y;;;;; -2ABD;SUBSET WITH DOT;Sm;0;ON;;;;;Y;;;;; -2ABE;SUPERSET WITH DOT;Sm;0;ON;;;;;Y;;;;; -2ABF;SUBSET WITH PLUS SIGN BELOW;Sm;0;ON;;;;;Y;;;;; -2AC0;SUPERSET WITH PLUS SIGN BELOW;Sm;0;ON;;;;;Y;;;;; -2AC1;SUBSET WITH MULTIPLICATION SIGN BELOW;Sm;0;ON;;;;;Y;;;;; -2AC2;SUPERSET WITH MULTIPLICATION SIGN BELOW;Sm;0;ON;;;;;Y;;;;; -2AC3;SUBSET OF OR EQUAL TO WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2AC4;SUPERSET OF OR EQUAL TO WITH DOT ABOVE;Sm;0;ON;;;;;Y;;;;; -2AC5;SUBSET OF ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AC6;SUPERSET OF ABOVE EQUALS SIGN;Sm;0;ON;;;;;Y;;;;; -2AC7;SUBSET OF ABOVE TILDE OPERATOR;Sm;0;ON;;;;;Y;;;;; -2AC8;SUPERSET OF ABOVE TILDE OPERATOR;Sm;0;ON;;;;;Y;;;;; -2AC9;SUBSET OF ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ACA;SUPERSET OF ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ACB;SUBSET OF ABOVE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ACC;SUPERSET OF ABOVE NOT EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2ACD;SQUARE LEFT OPEN BOX OPERATOR;Sm;0;ON;;;;;Y;;;;; -2ACE;SQUARE RIGHT OPEN BOX OPERATOR;Sm;0;ON;;;;;Y;;;;; -2ACF;CLOSED SUBSET;Sm;0;ON;;;;;Y;;;;; -2AD0;CLOSED SUPERSET;Sm;0;ON;;;;;Y;;;;; -2AD1;CLOSED SUBSET OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AD2;CLOSED SUPERSET OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AD3;SUBSET ABOVE SUPERSET;Sm;0;ON;;;;;Y;;;;; -2AD4;SUPERSET ABOVE SUBSET;Sm;0;ON;;;;;Y;;;;; -2AD5;SUBSET ABOVE SUBSET;Sm;0;ON;;;;;Y;;;;; -2AD6;SUPERSET ABOVE SUPERSET;Sm;0;ON;;;;;Y;;;;; -2AD7;SUPERSET BESIDE SUBSET;Sm;0;ON;;;;;N;;;;; -2AD8;SUPERSET BESIDE AND JOINED BY DASH WITH SUBSET;Sm;0;ON;;;;;N;;;;; -2AD9;ELEMENT OF OPENING DOWNWARDS;Sm;0;ON;;;;;N;;;;; -2ADA;PITCHFORK WITH TEE TOP;Sm;0;ON;;;;;N;;;;; -2ADB;TRANSVERSAL INTERSECTION;Sm;0;ON;;;;;N;;;;; -2ADC;FORKING;Sm;0;ON;2ADD 0338;;;;Y;;not independent;;; -2ADD;NONFORKING;Sm;0;ON;;;;;N;;independent;;; -2ADE;SHORT LEFT TACK;Sm;0;ON;;;;;Y;;;;; -2ADF;SHORT DOWN TACK;Sm;0;ON;;;;;N;;;;; -2AE0;SHORT UP TACK;Sm;0;ON;;;;;N;;;;; -2AE1;PERPENDICULAR WITH S;Sm;0;ON;;;;;N;;;;; -2AE2;VERTICAL BAR TRIPLE RIGHT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -2AE3;DOUBLE VERTICAL BAR LEFT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -2AE4;VERTICAL BAR DOUBLE LEFT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -2AE5;DOUBLE VERTICAL BAR DOUBLE LEFT TURNSTILE;Sm;0;ON;;;;;Y;;;;; -2AE6;LONG DASH FROM LEFT MEMBER OF DOUBLE VERTICAL;Sm;0;ON;;;;;Y;;;;; -2AE7;SHORT DOWN TACK WITH OVERBAR;Sm;0;ON;;;;;N;;;;; -2AE8;SHORT UP TACK WITH UNDERBAR;Sm;0;ON;;;;;N;;;;; -2AE9;SHORT UP TACK ABOVE SHORT DOWN TACK;Sm;0;ON;;;;;N;;;;; -2AEA;DOUBLE DOWN TACK;Sm;0;ON;;;;;N;;;;; -2AEB;DOUBLE UP TACK;Sm;0;ON;;;;;N;;;;; -2AEC;DOUBLE STROKE NOT SIGN;Sm;0;ON;;;;;Y;;;;; -2AED;REVERSED DOUBLE STROKE NOT SIGN;Sm;0;ON;;;;;Y;;;;; -2AEE;DOES NOT DIVIDE WITH REVERSED NEGATION SLASH;Sm;0;ON;;;;;Y;;;;; -2AEF;VERTICAL LINE WITH CIRCLE ABOVE;Sm;0;ON;;;;;N;;;;; -2AF0;VERTICAL LINE WITH CIRCLE BELOW;Sm;0;ON;;;;;N;;;;; -2AF1;DOWN TACK WITH CIRCLE BELOW;Sm;0;ON;;;;;N;;;;; -2AF2;PARALLEL WITH HORIZONTAL STROKE;Sm;0;ON;;;;;N;;;;; -2AF3;PARALLEL WITH TILDE OPERATOR;Sm;0;ON;;;;;Y;;;;; -2AF4;TRIPLE VERTICAL BAR BINARY RELATION;Sm;0;ON;;;;;N;;;;; -2AF5;TRIPLE VERTICAL BAR WITH HORIZONTAL STROKE;Sm;0;ON;;;;;N;;;;; -2AF6;TRIPLE COLON OPERATOR;Sm;0;ON;;;;;N;;;;; -2AF7;TRIPLE NESTED LESS-THAN;Sm;0;ON;;;;;Y;;;;; -2AF8;TRIPLE NESTED GREATER-THAN;Sm;0;ON;;;;;Y;;;;; -2AF9;DOUBLE-LINE SLANTED LESS-THAN OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AFA;DOUBLE-LINE SLANTED GREATER-THAN OR EQUAL TO;Sm;0;ON;;;;;Y;;;;; -2AFB;TRIPLE SOLIDUS BINARY RELATION;Sm;0;ON;;;;;Y;;;;; -2AFC;LARGE TRIPLE VERTICAL BAR OPERATOR;Sm;0;ON;;;;;N;;;;; -2AFD;DOUBLE SOLIDUS OPERATOR;Sm;0;ON;;;;;Y;;;;; -2AFE;WHITE VERTICAL BAR;Sm;0;ON;;;;;N;;;;; -2AFF;N-ARY WHITE VERTICAL BAR;Sm;0;ON;;;;;N;;;;; -2B00;NORTH EAST WHITE ARROW;So;0;ON;;;;;N;;;;; -2B01;NORTH WEST WHITE ARROW;So;0;ON;;;;;N;;;;; -2B02;SOUTH EAST WHITE ARROW;So;0;ON;;;;;N;;;;; -2B03;SOUTH WEST WHITE ARROW;So;0;ON;;;;;N;;;;; -2B04;LEFT RIGHT WHITE ARROW;So;0;ON;;;;;N;;;;; -2B05;LEFTWARDS BLACK ARROW;So;0;ON;;;;;N;;;;; -2B06;UPWARDS BLACK ARROW;So;0;ON;;;;;N;;;;; -2B07;DOWNWARDS BLACK ARROW;So;0;ON;;;;;N;;;;; -2B08;NORTH EAST BLACK ARROW;So;0;ON;;;;;N;;;;; -2B09;NORTH WEST BLACK ARROW;So;0;ON;;;;;N;;;;; -2B0A;SOUTH EAST BLACK ARROW;So;0;ON;;;;;N;;;;; -2B0B;SOUTH WEST BLACK ARROW;So;0;ON;;;;;N;;;;; -2B0C;LEFT RIGHT BLACK ARROW;So;0;ON;;;;;N;;;;; -2B0D;UP DOWN BLACK ARROW;So;0;ON;;;;;N;;;;; -2B0E;RIGHTWARDS ARROW WITH TIP DOWNWARDS;So;0;ON;;;;;N;;;;; -2B0F;RIGHTWARDS ARROW WITH TIP UPWARDS;So;0;ON;;;;;N;;;;; -2B10;LEFTWARDS ARROW WITH TIP DOWNWARDS;So;0;ON;;;;;N;;;;; -2B11;LEFTWARDS ARROW WITH TIP UPWARDS;So;0;ON;;;;;N;;;;; -2B12;SQUARE WITH TOP HALF BLACK;So;0;ON;;;;;N;;;;; -2B13;SQUARE WITH BOTTOM HALF BLACK;So;0;ON;;;;;N;;;;; -2B14;SQUARE WITH UPPER RIGHT DIAGONAL HALF BLACK;So;0;ON;;;;;N;;;;; -2B15;SQUARE WITH LOWER LEFT DIAGONAL HALF BLACK;So;0;ON;;;;;N;;;;; -2B16;DIAMOND WITH LEFT HALF BLACK;So;0;ON;;;;;N;;;;; -2B17;DIAMOND WITH RIGHT HALF BLACK;So;0;ON;;;;;N;;;;; -2B18;DIAMOND WITH TOP HALF BLACK;So;0;ON;;;;;N;;;;; -2B19;DIAMOND WITH BOTTOM HALF BLACK;So;0;ON;;;;;N;;;;; -2B1A;DOTTED SQUARE;So;0;ON;;;;;N;;;;; -2B1B;BLACK LARGE SQUARE;So;0;ON;;;;;N;;;;; -2B1C;WHITE LARGE SQUARE;So;0;ON;;;;;N;;;;; -2B1D;BLACK VERY SMALL SQUARE;So;0;ON;;;;;N;;;;; -2B1E;WHITE VERY SMALL SQUARE;So;0;ON;;;;;N;;;;; -2B1F;BLACK PENTAGON;So;0;ON;;;;;N;;;;; -2B20;WHITE PENTAGON;So;0;ON;;;;;N;;;;; -2B21;WHITE HEXAGON;So;0;ON;;;;;N;;;;; -2B22;BLACK HEXAGON;So;0;ON;;;;;N;;;;; -2B23;HORIZONTAL BLACK HEXAGON;So;0;ON;;;;;N;;;;; -2B24;BLACK LARGE CIRCLE;So;0;ON;;;;;N;;;;; -2B25;BLACK MEDIUM DIAMOND;So;0;ON;;;;;N;;;;; -2B26;WHITE MEDIUM DIAMOND;So;0;ON;;;;;N;;;;; -2B27;BLACK MEDIUM LOZENGE;So;0;ON;;;;;N;;;;; -2B28;WHITE MEDIUM LOZENGE;So;0;ON;;;;;N;;;;; -2B29;BLACK SMALL DIAMOND;So;0;ON;;;;;N;;;;; -2B2A;BLACK SMALL LOZENGE;So;0;ON;;;;;N;;;;; -2B2B;WHITE SMALL LOZENGE;So;0;ON;;;;;N;;;;; -2B2C;BLACK HORIZONTAL ELLIPSE;So;0;ON;;;;;N;;;;; -2B2D;WHITE HORIZONTAL ELLIPSE;So;0;ON;;;;;N;;;;; -2B2E;BLACK VERTICAL ELLIPSE;So;0;ON;;;;;N;;;;; -2B2F;WHITE VERTICAL ELLIPSE;So;0;ON;;;;;N;;;;; -2B30;LEFT ARROW WITH SMALL CIRCLE;Sm;0;ON;;;;;N;;;;; -2B31;THREE LEFTWARDS ARROWS;Sm;0;ON;;;;;N;;;;; -2B32;LEFT ARROW WITH CIRCLED PLUS;Sm;0;ON;;;;;N;;;;; -2B33;LONG LEFTWARDS SQUIGGLE ARROW;Sm;0;ON;;;;;N;;;;; -2B34;LEFTWARDS TWO-HEADED ARROW WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B35;LEFTWARDS TWO-HEADED ARROW WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B36;LEFTWARDS TWO-HEADED ARROW FROM BAR;Sm;0;ON;;;;;N;;;;; -2B37;LEFTWARDS TWO-HEADED TRIPLE DASH ARROW;Sm;0;ON;;;;;N;;;;; -2B38;LEFTWARDS ARROW WITH DOTTED STEM;Sm;0;ON;;;;;N;;;;; -2B39;LEFTWARDS ARROW WITH TAIL WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B3A;LEFTWARDS ARROW WITH TAIL WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B3B;LEFTWARDS TWO-HEADED ARROW WITH TAIL;Sm;0;ON;;;;;N;;;;; -2B3C;LEFTWARDS TWO-HEADED ARROW WITH TAIL WITH VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B3D;LEFTWARDS TWO-HEADED ARROW WITH TAIL WITH DOUBLE VERTICAL STROKE;Sm;0;ON;;;;;N;;;;; -2B3E;LEFTWARDS ARROW THROUGH X;Sm;0;ON;;;;;N;;;;; -2B3F;WAVE ARROW POINTING DIRECTLY LEFT;Sm;0;ON;;;;;N;;;;; -2B40;EQUALS SIGN ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2B41;REVERSE TILDE OPERATOR ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2B42;LEFTWARDS ARROW ABOVE REVERSE ALMOST EQUAL TO;Sm;0;ON;;;;;N;;;;; -2B43;RIGHTWARDS ARROW THROUGH GREATER-THAN;Sm;0;ON;;;;;N;;;;; -2B44;RIGHTWARDS ARROW THROUGH SUPERSET;Sm;0;ON;;;;;N;;;;; -2B45;LEFTWARDS QUADRUPLE ARROW;So;0;ON;;;;;N;;;;; -2B46;RIGHTWARDS QUADRUPLE ARROW;So;0;ON;;;;;N;;;;; -2B47;REVERSE TILDE OPERATOR ABOVE RIGHTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2B48;RIGHTWARDS ARROW ABOVE REVERSE ALMOST EQUAL TO;Sm;0;ON;;;;;N;;;;; -2B49;TILDE OPERATOR ABOVE LEFTWARDS ARROW;Sm;0;ON;;;;;N;;;;; -2B4A;LEFTWARDS ARROW ABOVE ALMOST EQUAL TO;Sm;0;ON;;;;;N;;;;; -2B4B;LEFTWARDS ARROW ABOVE REVERSE TILDE OPERATOR;Sm;0;ON;;;;;N;;;;; -2B4C;RIGHTWARDS ARROW ABOVE REVERSE TILDE OPERATOR;Sm;0;ON;;;;;N;;;;; -2B50;WHITE MEDIUM STAR;So;0;ON;;;;;N;;;;; -2B51;BLACK SMALL STAR;So;0;ON;;;;;N;;;;; -2B52;WHITE SMALL STAR;So;0;ON;;;;;N;;;;; -2B53;BLACK RIGHT-POINTING PENTAGON;So;0;ON;;;;;N;;;;; -2B54;WHITE RIGHT-POINTING PENTAGON;So;0;ON;;;;;N;;;;; -2C00;GLAGOLITIC CAPITAL LETTER AZU;Lu;0;L;;;;;N;;;;2C30; -2C01;GLAGOLITIC CAPITAL LETTER BUKY;Lu;0;L;;;;;N;;;;2C31; -2C02;GLAGOLITIC CAPITAL LETTER VEDE;Lu;0;L;;;;;N;;;;2C32; -2C03;GLAGOLITIC CAPITAL LETTER GLAGOLI;Lu;0;L;;;;;N;;;;2C33; -2C04;GLAGOLITIC CAPITAL LETTER DOBRO;Lu;0;L;;;;;N;;;;2C34; -2C05;GLAGOLITIC CAPITAL LETTER YESTU;Lu;0;L;;;;;N;;;;2C35; -2C06;GLAGOLITIC CAPITAL LETTER ZHIVETE;Lu;0;L;;;;;N;;;;2C36; -2C07;GLAGOLITIC CAPITAL LETTER DZELO;Lu;0;L;;;;;N;;;;2C37; -2C08;GLAGOLITIC CAPITAL LETTER ZEMLJA;Lu;0;L;;;;;N;;;;2C38; -2C09;GLAGOLITIC CAPITAL LETTER IZHE;Lu;0;L;;;;;N;;;;2C39; -2C0A;GLAGOLITIC CAPITAL LETTER INITIAL IZHE;Lu;0;L;;;;;N;;;;2C3A; -2C0B;GLAGOLITIC CAPITAL LETTER I;Lu;0;L;;;;;N;;;;2C3B; -2C0C;GLAGOLITIC CAPITAL LETTER DJERVI;Lu;0;L;;;;;N;;;;2C3C; -2C0D;GLAGOLITIC CAPITAL LETTER KAKO;Lu;0;L;;;;;N;;;;2C3D; -2C0E;GLAGOLITIC CAPITAL LETTER LJUDIJE;Lu;0;L;;;;;N;;;;2C3E; -2C0F;GLAGOLITIC CAPITAL LETTER MYSLITE;Lu;0;L;;;;;N;;;;2C3F; -2C10;GLAGOLITIC CAPITAL LETTER NASHI;Lu;0;L;;;;;N;;;;2C40; -2C11;GLAGOLITIC CAPITAL LETTER ONU;Lu;0;L;;;;;N;;;;2C41; -2C12;GLAGOLITIC CAPITAL LETTER POKOJI;Lu;0;L;;;;;N;;;;2C42; -2C13;GLAGOLITIC CAPITAL LETTER RITSI;Lu;0;L;;;;;N;;;;2C43; -2C14;GLAGOLITIC CAPITAL LETTER SLOVO;Lu;0;L;;;;;N;;;;2C44; -2C15;GLAGOLITIC CAPITAL LETTER TVRIDO;Lu;0;L;;;;;N;;;;2C45; -2C16;GLAGOLITIC CAPITAL LETTER UKU;Lu;0;L;;;;;N;;;;2C46; -2C17;GLAGOLITIC CAPITAL LETTER FRITU;Lu;0;L;;;;;N;;;;2C47; -2C18;GLAGOLITIC CAPITAL LETTER HERU;Lu;0;L;;;;;N;;;;2C48; -2C19;GLAGOLITIC CAPITAL LETTER OTU;Lu;0;L;;;;;N;;;;2C49; -2C1A;GLAGOLITIC CAPITAL LETTER PE;Lu;0;L;;;;;N;;;;2C4A; -2C1B;GLAGOLITIC CAPITAL LETTER SHTA;Lu;0;L;;;;;N;;;;2C4B; -2C1C;GLAGOLITIC CAPITAL LETTER TSI;Lu;0;L;;;;;N;;;;2C4C; -2C1D;GLAGOLITIC CAPITAL LETTER CHRIVI;Lu;0;L;;;;;N;;;;2C4D; -2C1E;GLAGOLITIC CAPITAL LETTER SHA;Lu;0;L;;;;;N;;;;2C4E; -2C1F;GLAGOLITIC CAPITAL LETTER YERU;Lu;0;L;;;;;N;;;;2C4F; -2C20;GLAGOLITIC CAPITAL LETTER YERI;Lu;0;L;;;;;N;;;;2C50; -2C21;GLAGOLITIC CAPITAL LETTER YATI;Lu;0;L;;;;;N;;;;2C51; -2C22;GLAGOLITIC CAPITAL LETTER SPIDERY HA;Lu;0;L;;;;;N;;;;2C52; -2C23;GLAGOLITIC CAPITAL LETTER YU;Lu;0;L;;;;;N;;;;2C53; -2C24;GLAGOLITIC CAPITAL LETTER SMALL YUS;Lu;0;L;;;;;N;;;;2C54; -2C25;GLAGOLITIC CAPITAL LETTER SMALL YUS WITH TAIL;Lu;0;L;;;;;N;;;;2C55; -2C26;GLAGOLITIC CAPITAL LETTER YO;Lu;0;L;;;;;N;;;;2C56; -2C27;GLAGOLITIC CAPITAL LETTER IOTATED SMALL YUS;Lu;0;L;;;;;N;;;;2C57; -2C28;GLAGOLITIC CAPITAL LETTER BIG YUS;Lu;0;L;;;;;N;;;;2C58; -2C29;GLAGOLITIC CAPITAL LETTER IOTATED BIG YUS;Lu;0;L;;;;;N;;;;2C59; -2C2A;GLAGOLITIC CAPITAL LETTER FITA;Lu;0;L;;;;;N;;;;2C5A; -2C2B;GLAGOLITIC CAPITAL LETTER IZHITSA;Lu;0;L;;;;;N;;;;2C5B; -2C2C;GLAGOLITIC CAPITAL LETTER SHTAPIC;Lu;0;L;;;;;N;;;;2C5C; -2C2D;GLAGOLITIC CAPITAL LETTER TROKUTASTI A;Lu;0;L;;;;;N;;;;2C5D; -2C2E;GLAGOLITIC CAPITAL LETTER LATINATE MYSLITE;Lu;0;L;;;;;N;;;;2C5E; -2C30;GLAGOLITIC SMALL LETTER AZU;Ll;0;L;;;;;N;;;2C00;;2C00 -2C31;GLAGOLITIC SMALL LETTER BUKY;Ll;0;L;;;;;N;;;2C01;;2C01 -2C32;GLAGOLITIC SMALL LETTER VEDE;Ll;0;L;;;;;N;;;2C02;;2C02 -2C33;GLAGOLITIC SMALL LETTER GLAGOLI;Ll;0;L;;;;;N;;;2C03;;2C03 -2C34;GLAGOLITIC SMALL LETTER DOBRO;Ll;0;L;;;;;N;;;2C04;;2C04 -2C35;GLAGOLITIC SMALL LETTER YESTU;Ll;0;L;;;;;N;;;2C05;;2C05 -2C36;GLAGOLITIC SMALL LETTER ZHIVETE;Ll;0;L;;;;;N;;;2C06;;2C06 -2C37;GLAGOLITIC SMALL LETTER DZELO;Ll;0;L;;;;;N;;;2C07;;2C07 -2C38;GLAGOLITIC SMALL LETTER ZEMLJA;Ll;0;L;;;;;N;;;2C08;;2C08 -2C39;GLAGOLITIC SMALL LETTER IZHE;Ll;0;L;;;;;N;;;2C09;;2C09 -2C3A;GLAGOLITIC SMALL LETTER INITIAL IZHE;Ll;0;L;;;;;N;;;2C0A;;2C0A -2C3B;GLAGOLITIC SMALL LETTER I;Ll;0;L;;;;;N;;;2C0B;;2C0B -2C3C;GLAGOLITIC SMALL LETTER DJERVI;Ll;0;L;;;;;N;;;2C0C;;2C0C -2C3D;GLAGOLITIC SMALL LETTER KAKO;Ll;0;L;;;;;N;;;2C0D;;2C0D -2C3E;GLAGOLITIC SMALL LETTER LJUDIJE;Ll;0;L;;;;;N;;;2C0E;;2C0E -2C3F;GLAGOLITIC SMALL LETTER MYSLITE;Ll;0;L;;;;;N;;;2C0F;;2C0F -2C40;GLAGOLITIC SMALL LETTER NASHI;Ll;0;L;;;;;N;;;2C10;;2C10 -2C41;GLAGOLITIC SMALL LETTER ONU;Ll;0;L;;;;;N;;;2C11;;2C11 -2C42;GLAGOLITIC SMALL LETTER POKOJI;Ll;0;L;;;;;N;;;2C12;;2C12 -2C43;GLAGOLITIC SMALL LETTER RITSI;Ll;0;L;;;;;N;;;2C13;;2C13 -2C44;GLAGOLITIC SMALL LETTER SLOVO;Ll;0;L;;;;;N;;;2C14;;2C14 -2C45;GLAGOLITIC SMALL LETTER TVRIDO;Ll;0;L;;;;;N;;;2C15;;2C15 -2C46;GLAGOLITIC SMALL LETTER UKU;Ll;0;L;;;;;N;;;2C16;;2C16 -2C47;GLAGOLITIC SMALL LETTER FRITU;Ll;0;L;;;;;N;;;2C17;;2C17 -2C48;GLAGOLITIC SMALL LETTER HERU;Ll;0;L;;;;;N;;;2C18;;2C18 -2C49;GLAGOLITIC SMALL LETTER OTU;Ll;0;L;;;;;N;;;2C19;;2C19 -2C4A;GLAGOLITIC SMALL LETTER PE;Ll;0;L;;;;;N;;;2C1A;;2C1A -2C4B;GLAGOLITIC SMALL LETTER SHTA;Ll;0;L;;;;;N;;;2C1B;;2C1B -2C4C;GLAGOLITIC SMALL LETTER TSI;Ll;0;L;;;;;N;;;2C1C;;2C1C -2C4D;GLAGOLITIC SMALL LETTER CHRIVI;Ll;0;L;;;;;N;;;2C1D;;2C1D -2C4E;GLAGOLITIC SMALL LETTER SHA;Ll;0;L;;;;;N;;;2C1E;;2C1E -2C4F;GLAGOLITIC SMALL LETTER YERU;Ll;0;L;;;;;N;;;2C1F;;2C1F -2C50;GLAGOLITIC SMALL LETTER YERI;Ll;0;L;;;;;N;;;2C20;;2C20 -2C51;GLAGOLITIC SMALL LETTER YATI;Ll;0;L;;;;;N;;;2C21;;2C21 -2C52;GLAGOLITIC SMALL LETTER SPIDERY HA;Ll;0;L;;;;;N;;;2C22;;2C22 -2C53;GLAGOLITIC SMALL LETTER YU;Ll;0;L;;;;;N;;;2C23;;2C23 -2C54;GLAGOLITIC SMALL LETTER SMALL YUS;Ll;0;L;;;;;N;;;2C24;;2C24 -2C55;GLAGOLITIC SMALL LETTER SMALL YUS WITH TAIL;Ll;0;L;;;;;N;;;2C25;;2C25 -2C56;GLAGOLITIC SMALL LETTER YO;Ll;0;L;;;;;N;;;2C26;;2C26 -2C57;GLAGOLITIC SMALL LETTER IOTATED SMALL YUS;Ll;0;L;;;;;N;;;2C27;;2C27 -2C58;GLAGOLITIC SMALL LETTER BIG YUS;Ll;0;L;;;;;N;;;2C28;;2C28 -2C59;GLAGOLITIC SMALL LETTER IOTATED BIG YUS;Ll;0;L;;;;;N;;;2C29;;2C29 -2C5A;GLAGOLITIC SMALL LETTER FITA;Ll;0;L;;;;;N;;;2C2A;;2C2A -2C5B;GLAGOLITIC SMALL LETTER IZHITSA;Ll;0;L;;;;;N;;;2C2B;;2C2B -2C5C;GLAGOLITIC SMALL LETTER SHTAPIC;Ll;0;L;;;;;N;;;2C2C;;2C2C -2C5D;GLAGOLITIC SMALL LETTER TROKUTASTI A;Ll;0;L;;;;;N;;;2C2D;;2C2D -2C5E;GLAGOLITIC SMALL LETTER LATINATE MYSLITE;Ll;0;L;;;;;N;;;2C2E;;2C2E -2C60;LATIN CAPITAL LETTER L WITH DOUBLE BAR;Lu;0;L;;;;;N;;;;2C61; -2C61;LATIN SMALL LETTER L WITH DOUBLE BAR;Ll;0;L;;;;;N;;;2C60;;2C60 -2C62;LATIN CAPITAL LETTER L WITH MIDDLE TILDE;Lu;0;L;;;;;N;;;;026B; -2C63;LATIN CAPITAL LETTER P WITH STROKE;Lu;0;L;;;;;N;;;;1D7D; -2C64;LATIN CAPITAL LETTER R WITH TAIL;Lu;0;L;;;;;N;;;;027D; -2C65;LATIN SMALL LETTER A WITH STROKE;Ll;0;L;;;;;N;;;023A;;023A -2C66;LATIN SMALL LETTER T WITH DIAGONAL STROKE;Ll;0;L;;;;;N;;;023E;;023E -2C67;LATIN CAPITAL LETTER H WITH DESCENDER;Lu;0;L;;;;;N;;;;2C68; -2C68;LATIN SMALL LETTER H WITH DESCENDER;Ll;0;L;;;;;N;;;2C67;;2C67 -2C69;LATIN CAPITAL LETTER K WITH DESCENDER;Lu;0;L;;;;;N;;;;2C6A; -2C6A;LATIN SMALL LETTER K WITH DESCENDER;Ll;0;L;;;;;N;;;2C69;;2C69 -2C6B;LATIN CAPITAL LETTER Z WITH DESCENDER;Lu;0;L;;;;;N;;;;2C6C; -2C6C;LATIN SMALL LETTER Z WITH DESCENDER;Ll;0;L;;;;;N;;;2C6B;;2C6B -2C6D;LATIN CAPITAL LETTER ALPHA;Lu;0;L;;;;;N;;;;0251; -2C6E;LATIN CAPITAL LETTER M WITH HOOK;Lu;0;L;;;;;N;;;;0271; -2C6F;LATIN CAPITAL LETTER TURNED A;Lu;0;L;;;;;N;;;;0250; -2C71;LATIN SMALL LETTER V WITH RIGHT HOOK;Ll;0;L;;;;;N;;;;; -2C72;LATIN CAPITAL LETTER W WITH HOOK;Lu;0;L;;;;;N;;;;2C73; -2C73;LATIN SMALL LETTER W WITH HOOK;Ll;0;L;;;;;N;;;2C72;;2C72 -2C74;LATIN SMALL LETTER V WITH CURL;Ll;0;L;;;;;N;;;;; -2C75;LATIN CAPITAL LETTER HALF H;Lu;0;L;;;;;N;;;;2C76; -2C76;LATIN SMALL LETTER HALF H;Ll;0;L;;;;;N;;;2C75;;2C75 -2C77;LATIN SMALL LETTER TAILLESS PHI;Ll;0;L;;;;;N;;;;; -2C78;LATIN SMALL LETTER E WITH NOTCH;Ll;0;L;;;;;N;;;;; -2C79;LATIN SMALL LETTER TURNED R WITH TAIL;Ll;0;L;;;;;N;;;;; -2C7A;LATIN SMALL LETTER O WITH LOW RING INSIDE;Ll;0;L;;;;;N;;;;; -2C7B;LATIN LETTER SMALL CAPITAL TURNED E;Ll;0;L;;;;;N;;;;; -2C7C;LATIN SUBSCRIPT SMALL LETTER J;Ll;0;L; 006A;;;;N;;;;; -2C7D;MODIFIER LETTER CAPITAL V;Lm;0;L; 0056;;;;N;;;;; -2C80;COPTIC CAPITAL LETTER ALFA;Lu;0;L;;;;;N;;;;2C81; -2C81;COPTIC SMALL LETTER ALFA;Ll;0;L;;;;;N;;;2C80;;2C80 -2C82;COPTIC CAPITAL LETTER VIDA;Lu;0;L;;;;;N;;;;2C83; -2C83;COPTIC SMALL LETTER VIDA;Ll;0;L;;;;;N;;;2C82;;2C82 -2C84;COPTIC CAPITAL LETTER GAMMA;Lu;0;L;;;;;N;;;;2C85; -2C85;COPTIC SMALL LETTER GAMMA;Ll;0;L;;;;;N;;;2C84;;2C84 -2C86;COPTIC CAPITAL LETTER DALDA;Lu;0;L;;;;;N;;;;2C87; -2C87;COPTIC SMALL LETTER DALDA;Ll;0;L;;;;;N;;;2C86;;2C86 -2C88;COPTIC CAPITAL LETTER EIE;Lu;0;L;;;;;N;;;;2C89; -2C89;COPTIC SMALL LETTER EIE;Ll;0;L;;;;;N;;;2C88;;2C88 -2C8A;COPTIC CAPITAL LETTER SOU;Lu;0;L;;;;;N;;;;2C8B; -2C8B;COPTIC SMALL LETTER SOU;Ll;0;L;;;;;N;;;2C8A;;2C8A -2C8C;COPTIC CAPITAL LETTER ZATA;Lu;0;L;;;;;N;;;;2C8D; -2C8D;COPTIC SMALL LETTER ZATA;Ll;0;L;;;;;N;;;2C8C;;2C8C -2C8E;COPTIC CAPITAL LETTER HATE;Lu;0;L;;;;;N;;;;2C8F; -2C8F;COPTIC SMALL LETTER HATE;Ll;0;L;;;;;N;;;2C8E;;2C8E -2C90;COPTIC CAPITAL LETTER THETHE;Lu;0;L;;;;;N;;;;2C91; -2C91;COPTIC SMALL LETTER THETHE;Ll;0;L;;;;;N;;;2C90;;2C90 -2C92;COPTIC CAPITAL LETTER IAUDA;Lu;0;L;;;;;N;;;;2C93; -2C93;COPTIC SMALL LETTER IAUDA;Ll;0;L;;;;;N;;;2C92;;2C92 -2C94;COPTIC CAPITAL LETTER KAPA;Lu;0;L;;;;;N;;;;2C95; -2C95;COPTIC SMALL LETTER KAPA;Ll;0;L;;;;;N;;;2C94;;2C94 -2C96;COPTIC CAPITAL LETTER LAULA;Lu;0;L;;;;;N;;;;2C97; -2C97;COPTIC SMALL LETTER LAULA;Ll;0;L;;;;;N;;;2C96;;2C96 -2C98;COPTIC CAPITAL LETTER MI;Lu;0;L;;;;;N;;;;2C99; -2C99;COPTIC SMALL LETTER MI;Ll;0;L;;;;;N;;;2C98;;2C98 -2C9A;COPTIC CAPITAL LETTER NI;Lu;0;L;;;;;N;;;;2C9B; -2C9B;COPTIC SMALL LETTER NI;Ll;0;L;;;;;N;;;2C9A;;2C9A -2C9C;COPTIC CAPITAL LETTER KSI;Lu;0;L;;;;;N;;;;2C9D; -2C9D;COPTIC SMALL LETTER KSI;Ll;0;L;;;;;N;;;2C9C;;2C9C -2C9E;COPTIC CAPITAL LETTER O;Lu;0;L;;;;;N;;;;2C9F; -2C9F;COPTIC SMALL LETTER O;Ll;0;L;;;;;N;;;2C9E;;2C9E -2CA0;COPTIC CAPITAL LETTER PI;Lu;0;L;;;;;N;;;;2CA1; -2CA1;COPTIC SMALL LETTER PI;Ll;0;L;;;;;N;;;2CA0;;2CA0 -2CA2;COPTIC CAPITAL LETTER RO;Lu;0;L;;;;;N;;;;2CA3; -2CA3;COPTIC SMALL LETTER RO;Ll;0;L;;;;;N;;;2CA2;;2CA2 -2CA4;COPTIC CAPITAL LETTER SIMA;Lu;0;L;;;;;N;;;;2CA5; -2CA5;COPTIC SMALL LETTER SIMA;Ll;0;L;;;;;N;;;2CA4;;2CA4 -2CA6;COPTIC CAPITAL LETTER TAU;Lu;0;L;;;;;N;;;;2CA7; -2CA7;COPTIC SMALL LETTER TAU;Ll;0;L;;;;;N;;;2CA6;;2CA6 -2CA8;COPTIC CAPITAL LETTER UA;Lu;0;L;;;;;N;;;;2CA9; -2CA9;COPTIC SMALL LETTER UA;Ll;0;L;;;;;N;;;2CA8;;2CA8 -2CAA;COPTIC CAPITAL LETTER FI;Lu;0;L;;;;;N;;;;2CAB; -2CAB;COPTIC SMALL LETTER FI;Ll;0;L;;;;;N;;;2CAA;;2CAA -2CAC;COPTIC CAPITAL LETTER KHI;Lu;0;L;;;;;N;;;;2CAD; -2CAD;COPTIC SMALL LETTER KHI;Ll;0;L;;;;;N;;;2CAC;;2CAC -2CAE;COPTIC CAPITAL LETTER PSI;Lu;0;L;;;;;N;;;;2CAF; -2CAF;COPTIC SMALL LETTER PSI;Ll;0;L;;;;;N;;;2CAE;;2CAE -2CB0;COPTIC CAPITAL LETTER OOU;Lu;0;L;;;;;N;;;;2CB1; -2CB1;COPTIC SMALL LETTER OOU;Ll;0;L;;;;;N;;;2CB0;;2CB0 -2CB2;COPTIC CAPITAL LETTER DIALECT-P ALEF;Lu;0;L;;;;;N;;;;2CB3; -2CB3;COPTIC SMALL LETTER DIALECT-P ALEF;Ll;0;L;;;;;N;;;2CB2;;2CB2 -2CB4;COPTIC CAPITAL LETTER OLD COPTIC AIN;Lu;0;L;;;;;N;;;;2CB5; -2CB5;COPTIC SMALL LETTER OLD COPTIC AIN;Ll;0;L;;;;;N;;;2CB4;;2CB4 -2CB6;COPTIC CAPITAL LETTER CRYPTOGRAMMIC EIE;Lu;0;L;;;;;N;;;;2CB7; -2CB7;COPTIC SMALL LETTER CRYPTOGRAMMIC EIE;Ll;0;L;;;;;N;;;2CB6;;2CB6 -2CB8;COPTIC CAPITAL LETTER DIALECT-P KAPA;Lu;0;L;;;;;N;;;;2CB9; -2CB9;COPTIC SMALL LETTER DIALECT-P KAPA;Ll;0;L;;;;;N;;;2CB8;;2CB8 -2CBA;COPTIC CAPITAL LETTER DIALECT-P NI;Lu;0;L;;;;;N;;;;2CBB; -2CBB;COPTIC SMALL LETTER DIALECT-P NI;Ll;0;L;;;;;N;;;2CBA;;2CBA -2CBC;COPTIC CAPITAL LETTER CRYPTOGRAMMIC NI;Lu;0;L;;;;;N;;;;2CBD; -2CBD;COPTIC SMALL LETTER CRYPTOGRAMMIC NI;Ll;0;L;;;;;N;;;2CBC;;2CBC -2CBE;COPTIC CAPITAL LETTER OLD COPTIC OOU;Lu;0;L;;;;;N;;;;2CBF; -2CBF;COPTIC SMALL LETTER OLD COPTIC OOU;Ll;0;L;;;;;N;;;2CBE;;2CBE -2CC0;COPTIC CAPITAL LETTER SAMPI;Lu;0;L;;;;;N;;;;2CC1; -2CC1;COPTIC SMALL LETTER SAMPI;Ll;0;L;;;;;N;;;2CC0;;2CC0 -2CC2;COPTIC CAPITAL LETTER CROSSED SHEI;Lu;0;L;;;;;N;;;;2CC3; -2CC3;COPTIC SMALL LETTER CROSSED SHEI;Ll;0;L;;;;;N;;;2CC2;;2CC2 -2CC4;COPTIC CAPITAL LETTER OLD COPTIC SHEI;Lu;0;L;;;;;N;;;;2CC5; -2CC5;COPTIC SMALL LETTER OLD COPTIC SHEI;Ll;0;L;;;;;N;;;2CC4;;2CC4 -2CC6;COPTIC CAPITAL LETTER OLD COPTIC ESH;Lu;0;L;;;;;N;;;;2CC7; -2CC7;COPTIC SMALL LETTER OLD COPTIC ESH;Ll;0;L;;;;;N;;;2CC6;;2CC6 -2CC8;COPTIC CAPITAL LETTER AKHMIMIC KHEI;Lu;0;L;;;;;N;;;;2CC9; -2CC9;COPTIC SMALL LETTER AKHMIMIC KHEI;Ll;0;L;;;;;N;;;2CC8;;2CC8 -2CCA;COPTIC CAPITAL LETTER DIALECT-P HORI;Lu;0;L;;;;;N;;;;2CCB; -2CCB;COPTIC SMALL LETTER DIALECT-P HORI;Ll;0;L;;;;;N;;;2CCA;;2CCA -2CCC;COPTIC CAPITAL LETTER OLD COPTIC HORI;Lu;0;L;;;;;N;;;;2CCD; -2CCD;COPTIC SMALL LETTER OLD COPTIC HORI;Ll;0;L;;;;;N;;;2CCC;;2CCC -2CCE;COPTIC CAPITAL LETTER OLD COPTIC HA;Lu;0;L;;;;;N;;;;2CCF; -2CCF;COPTIC SMALL LETTER OLD COPTIC HA;Ll;0;L;;;;;N;;;2CCE;;2CCE -2CD0;COPTIC CAPITAL LETTER L-SHAPED HA;Lu;0;L;;;;;N;;;;2CD1; -2CD1;COPTIC SMALL LETTER L-SHAPED HA;Ll;0;L;;;;;N;;;2CD0;;2CD0 -2CD2;COPTIC CAPITAL LETTER OLD COPTIC HEI;Lu;0;L;;;;;N;;;;2CD3; -2CD3;COPTIC SMALL LETTER OLD COPTIC HEI;Ll;0;L;;;;;N;;;2CD2;;2CD2 -2CD4;COPTIC CAPITAL LETTER OLD COPTIC HAT;Lu;0;L;;;;;N;;;;2CD5; -2CD5;COPTIC SMALL LETTER OLD COPTIC HAT;Ll;0;L;;;;;N;;;2CD4;;2CD4 -2CD6;COPTIC CAPITAL LETTER OLD COPTIC GANGIA;Lu;0;L;;;;;N;;;;2CD7; -2CD7;COPTIC SMALL LETTER OLD COPTIC GANGIA;Ll;0;L;;;;;N;;;2CD6;;2CD6 -2CD8;COPTIC CAPITAL LETTER OLD COPTIC DJA;Lu;0;L;;;;;N;;;;2CD9; -2CD9;COPTIC SMALL LETTER OLD COPTIC DJA;Ll;0;L;;;;;N;;;2CD8;;2CD8 -2CDA;COPTIC CAPITAL LETTER OLD COPTIC SHIMA;Lu;0;L;;;;;N;;;;2CDB; -2CDB;COPTIC SMALL LETTER OLD COPTIC SHIMA;Ll;0;L;;;;;N;;;2CDA;;2CDA -2CDC;COPTIC CAPITAL LETTER OLD NUBIAN SHIMA;Lu;0;L;;;;;N;;;;2CDD; -2CDD;COPTIC SMALL LETTER OLD NUBIAN SHIMA;Ll;0;L;;;;;N;;;2CDC;;2CDC -2CDE;COPTIC CAPITAL LETTER OLD NUBIAN NGI;Lu;0;L;;;;;N;;;;2CDF; -2CDF;COPTIC SMALL LETTER OLD NUBIAN NGI;Ll;0;L;;;;;N;;;2CDE;;2CDE -2CE0;COPTIC CAPITAL LETTER OLD NUBIAN NYI;Lu;0;L;;;;;N;;;;2CE1; -2CE1;COPTIC SMALL LETTER OLD NUBIAN NYI;Ll;0;L;;;;;N;;;2CE0;;2CE0 -2CE2;COPTIC CAPITAL LETTER OLD NUBIAN WAU;Lu;0;L;;;;;N;;;;2CE3; -2CE3;COPTIC SMALL LETTER OLD NUBIAN WAU;Ll;0;L;;;;;N;;;2CE2;;2CE2 -2CE4;COPTIC SYMBOL KAI;Ll;0;L;;;;;N;;;;; -2CE5;COPTIC SYMBOL MI RO;So;0;ON;;;;;N;;;;; -2CE6;COPTIC SYMBOL PI RO;So;0;ON;;;;;N;;;;; -2CE7;COPTIC SYMBOL STAUROS;So;0;ON;;;;;N;;;;; -2CE8;COPTIC SYMBOL TAU RO;So;0;ON;;;;;N;;;;; -2CE9;COPTIC SYMBOL KHI RO;So;0;ON;;;;;N;;;;; -2CEA;COPTIC SYMBOL SHIMA SIMA;So;0;ON;;;;;N;;;;; -2CF9;COPTIC OLD NUBIAN FULL STOP;Po;0;ON;;;;;N;;;;; -2CFA;COPTIC OLD NUBIAN DIRECT QUESTION MARK;Po;0;ON;;;;;N;;;;; -2CFB;COPTIC OLD NUBIAN INDIRECT QUESTION MARK;Po;0;ON;;;;;N;;;;; -2CFC;COPTIC OLD NUBIAN VERSE DIVIDER;Po;0;ON;;;;;N;;;;; -2CFD;COPTIC FRACTION ONE HALF;No;0;ON;;;;1/2;N;;;;; -2CFE;COPTIC FULL STOP;Po;0;ON;;;;;N;;;;; -2CFF;COPTIC MORPHOLOGICAL DIVIDER;Po;0;ON;;;;;N;;;;; -2D00;GEORGIAN SMALL LETTER AN;Ll;0;L;;;;;N;;Khutsuri;10A0;;10A0 -2D01;GEORGIAN SMALL LETTER BAN;Ll;0;L;;;;;N;;Khutsuri;10A1;;10A1 -2D02;GEORGIAN SMALL LETTER GAN;Ll;0;L;;;;;N;;Khutsuri;10A2;;10A2 -2D03;GEORGIAN SMALL LETTER DON;Ll;0;L;;;;;N;;Khutsuri;10A3;;10A3 -2D04;GEORGIAN SMALL LETTER EN;Ll;0;L;;;;;N;;Khutsuri;10A4;;10A4 -2D05;GEORGIAN SMALL LETTER VIN;Ll;0;L;;;;;N;;Khutsuri;10A5;;10A5 -2D06;GEORGIAN SMALL LETTER ZEN;Ll;0;L;;;;;N;;Khutsuri;10A6;;10A6 -2D07;GEORGIAN SMALL LETTER TAN;Ll;0;L;;;;;N;;Khutsuri;10A7;;10A7 -2D08;GEORGIAN SMALL LETTER IN;Ll;0;L;;;;;N;;Khutsuri;10A8;;10A8 -2D09;GEORGIAN SMALL LETTER KAN;Ll;0;L;;;;;N;;Khutsuri;10A9;;10A9 -2D0A;GEORGIAN SMALL LETTER LAS;Ll;0;L;;;;;N;;Khutsuri;10AA;;10AA -2D0B;GEORGIAN SMALL LETTER MAN;Ll;0;L;;;;;N;;Khutsuri;10AB;;10AB -2D0C;GEORGIAN SMALL LETTER NAR;Ll;0;L;;;;;N;;Khutsuri;10AC;;10AC -2D0D;GEORGIAN SMALL LETTER ON;Ll;0;L;;;;;N;;Khutsuri;10AD;;10AD -2D0E;GEORGIAN SMALL LETTER PAR;Ll;0;L;;;;;N;;Khutsuri;10AE;;10AE -2D0F;GEORGIAN SMALL LETTER ZHAR;Ll;0;L;;;;;N;;Khutsuri;10AF;;10AF -2D10;GEORGIAN SMALL LETTER RAE;Ll;0;L;;;;;N;;Khutsuri;10B0;;10B0 -2D11;GEORGIAN SMALL LETTER SAN;Ll;0;L;;;;;N;;Khutsuri;10B1;;10B1 -2D12;GEORGIAN SMALL LETTER TAR;Ll;0;L;;;;;N;;Khutsuri;10B2;;10B2 -2D13;GEORGIAN SMALL LETTER UN;Ll;0;L;;;;;N;;Khutsuri;10B3;;10B3 -2D14;GEORGIAN SMALL LETTER PHAR;Ll;0;L;;;;;N;;Khutsuri;10B4;;10B4 -2D15;GEORGIAN SMALL LETTER KHAR;Ll;0;L;;;;;N;;Khutsuri;10B5;;10B5 -2D16;GEORGIAN SMALL LETTER GHAN;Ll;0;L;;;;;N;;Khutsuri;10B6;;10B6 -2D17;GEORGIAN SMALL LETTER QAR;Ll;0;L;;;;;N;;Khutsuri;10B7;;10B7 -2D18;GEORGIAN SMALL LETTER SHIN;Ll;0;L;;;;;N;;Khutsuri;10B8;;10B8 -2D19;GEORGIAN SMALL LETTER CHIN;Ll;0;L;;;;;N;;Khutsuri;10B9;;10B9 -2D1A;GEORGIAN SMALL LETTER CAN;Ll;0;L;;;;;N;;Khutsuri;10BA;;10BA -2D1B;GEORGIAN SMALL LETTER JIL;Ll;0;L;;;;;N;;Khutsuri;10BB;;10BB -2D1C;GEORGIAN SMALL LETTER CIL;Ll;0;L;;;;;N;;Khutsuri;10BC;;10BC -2D1D;GEORGIAN SMALL LETTER CHAR;Ll;0;L;;;;;N;;Khutsuri;10BD;;10BD -2D1E;GEORGIAN SMALL LETTER XAN;Ll;0;L;;;;;N;;Khutsuri;10BE;;10BE -2D1F;GEORGIAN SMALL LETTER JHAN;Ll;0;L;;;;;N;;Khutsuri;10BF;;10BF -2D20;GEORGIAN SMALL LETTER HAE;Ll;0;L;;;;;N;;Khutsuri;10C0;;10C0 -2D21;GEORGIAN SMALL LETTER HE;Ll;0;L;;;;;N;;Khutsuri;10C1;;10C1 -2D22;GEORGIAN SMALL LETTER HIE;Ll;0;L;;;;;N;;Khutsuri;10C2;;10C2 -2D23;GEORGIAN SMALL LETTER WE;Ll;0;L;;;;;N;;Khutsuri;10C3;;10C3 -2D24;GEORGIAN SMALL LETTER HAR;Ll;0;L;;;;;N;;Khutsuri;10C4;;10C4 -2D25;GEORGIAN SMALL LETTER HOE;Ll;0;L;;;;;N;;Khutsuri;10C5;;10C5 -2D30;TIFINAGH LETTER YA;Lo;0;L;;;;;N;;;;; -2D31;TIFINAGH LETTER YAB;Lo;0;L;;;;;N;;;;; -2D32;TIFINAGH LETTER YABH;Lo;0;L;;;;;N;;;;; -2D33;TIFINAGH LETTER YAG;Lo;0;L;;;;;N;;;;; -2D34;TIFINAGH LETTER YAGHH;Lo;0;L;;;;;N;;;;; -2D35;TIFINAGH LETTER BERBER ACADEMY YAJ;Lo;0;L;;;;;N;;;;; -2D36;TIFINAGH LETTER YAJ;Lo;0;L;;;;;N;;;;; -2D37;TIFINAGH LETTER YAD;Lo;0;L;;;;;N;;;;; -2D38;TIFINAGH LETTER YADH;Lo;0;L;;;;;N;;;;; -2D39;TIFINAGH LETTER YADD;Lo;0;L;;;;;N;;;;; -2D3A;TIFINAGH LETTER YADDH;Lo;0;L;;;;;N;;;;; -2D3B;TIFINAGH LETTER YEY;Lo;0;L;;;;;N;;;;; -2D3C;TIFINAGH LETTER YAF;Lo;0;L;;;;;N;;;;; -2D3D;TIFINAGH LETTER YAK;Lo;0;L;;;;;N;;;;; -2D3E;TIFINAGH LETTER TUAREG YAK;Lo;0;L;;;;;N;;;;; -2D3F;TIFINAGH LETTER YAKHH;Lo;0;L;;;;;N;;;;; -2D40;TIFINAGH LETTER YAH;Lo;0;L;;;;;N;;Tuareg yab;;; -2D41;TIFINAGH LETTER BERBER ACADEMY YAH;Lo;0;L;;;;;N;;;;; -2D42;TIFINAGH LETTER TUAREG YAH;Lo;0;L;;;;;N;;;;; -2D43;TIFINAGH LETTER YAHH;Lo;0;L;;;;;N;;;;; -2D44;TIFINAGH LETTER YAA;Lo;0;L;;;;;N;;;;; -2D45;TIFINAGH LETTER YAKH;Lo;0;L;;;;;N;;;;; -2D46;TIFINAGH LETTER TUAREG YAKH;Lo;0;L;;;;;N;;;;; -2D47;TIFINAGH LETTER YAQ;Lo;0;L;;;;;N;;;;; -2D48;TIFINAGH LETTER TUAREG YAQ;Lo;0;L;;;;;N;;;;; -2D49;TIFINAGH LETTER YI;Lo;0;L;;;;;N;;;;; -2D4A;TIFINAGH LETTER YAZH;Lo;0;L;;;;;N;;;;; -2D4B;TIFINAGH LETTER AHAGGAR YAZH;Lo;0;L;;;;;N;;;;; -2D4C;TIFINAGH LETTER TUAREG YAZH;Lo;0;L;;;;;N;;;;; -2D4D;TIFINAGH LETTER YAL;Lo;0;L;;;;;N;;;;; -2D4E;TIFINAGH LETTER YAM;Lo;0;L;;;;;N;;;;; -2D4F;TIFINAGH LETTER YAN;Lo;0;L;;;;;N;;;;; -2D50;TIFINAGH LETTER TUAREG YAGN;Lo;0;L;;;;;N;;;;; -2D51;TIFINAGH LETTER TUAREG YANG;Lo;0;L;;;;;N;;;;; -2D52;TIFINAGH LETTER YAP;Lo;0;L;;;;;N;;;;; -2D53;TIFINAGH LETTER YU;Lo;0;L;;;;;N;;Tuareg yaw;;; -2D54;TIFINAGH LETTER YAR;Lo;0;L;;;;;N;;;;; -2D55;TIFINAGH LETTER YARR;Lo;0;L;;;;;N;;;;; -2D56;TIFINAGH LETTER YAGH;Lo;0;L;;;;;N;;;;; -2D57;TIFINAGH LETTER TUAREG YAGH;Lo;0;L;;;;;N;;;;; -2D58;TIFINAGH LETTER AYER YAGH;Lo;0;L;;;;;N;;Adrar yaj;;; -2D59;TIFINAGH LETTER YAS;Lo;0;L;;;;;N;;;;; -2D5A;TIFINAGH LETTER YASS;Lo;0;L;;;;;N;;;;; -2D5B;TIFINAGH LETTER YASH;Lo;0;L;;;;;N;;;;; -2D5C;TIFINAGH LETTER YAT;Lo;0;L;;;;;N;;;;; -2D5D;TIFINAGH LETTER YATH;Lo;0;L;;;;;N;;;;; -2D5E;TIFINAGH LETTER YACH;Lo;0;L;;;;;N;;;;; -2D5F;TIFINAGH LETTER YATT;Lo;0;L;;;;;N;;;;; -2D60;TIFINAGH LETTER YAV;Lo;0;L;;;;;N;;;;; -2D61;TIFINAGH LETTER YAW;Lo;0;L;;;;;N;;;;; -2D62;TIFINAGH LETTER YAY;Lo;0;L;;;;;N;;;;; -2D63;TIFINAGH LETTER YAZ;Lo;0;L;;;;;N;;;;; -2D64;TIFINAGH LETTER TAWELLEMET YAZ;Lo;0;L;;;;;N;;harpoon yaz;;; -2D65;TIFINAGH LETTER YAZZ;Lo;0;L;;;;;N;;;;; -2D6F;TIFINAGH MODIFIER LETTER LABIALIZATION MARK;Lm;0;L; 2D61;;;;N;;tamatart;;; -2D80;ETHIOPIC SYLLABLE LOA;Lo;0;L;;;;;N;;;;; -2D81;ETHIOPIC SYLLABLE MOA;Lo;0;L;;;;;N;;;;; -2D82;ETHIOPIC SYLLABLE ROA;Lo;0;L;;;;;N;;;;; -2D83;ETHIOPIC SYLLABLE SOA;Lo;0;L;;;;;N;;;;; -2D84;ETHIOPIC SYLLABLE SHOA;Lo;0;L;;;;;N;;;;; -2D85;ETHIOPIC SYLLABLE BOA;Lo;0;L;;;;;N;;;;; -2D86;ETHIOPIC SYLLABLE TOA;Lo;0;L;;;;;N;;;;; -2D87;ETHIOPIC SYLLABLE COA;Lo;0;L;;;;;N;;;;; -2D88;ETHIOPIC SYLLABLE NOA;Lo;0;L;;;;;N;;;;; -2D89;ETHIOPIC SYLLABLE NYOA;Lo;0;L;;;;;N;;;;; -2D8A;ETHIOPIC SYLLABLE GLOTTAL OA;Lo;0;L;;;;;N;;;;; -2D8B;ETHIOPIC SYLLABLE ZOA;Lo;0;L;;;;;N;;;;; -2D8C;ETHIOPIC SYLLABLE DOA;Lo;0;L;;;;;N;;;;; -2D8D;ETHIOPIC SYLLABLE DDOA;Lo;0;L;;;;;N;;;;; -2D8E;ETHIOPIC SYLLABLE JOA;Lo;0;L;;;;;N;;;;; -2D8F;ETHIOPIC SYLLABLE THOA;Lo;0;L;;;;;N;;;;; -2D90;ETHIOPIC SYLLABLE CHOA;Lo;0;L;;;;;N;;;;; -2D91;ETHIOPIC SYLLABLE PHOA;Lo;0;L;;;;;N;;;;; -2D92;ETHIOPIC SYLLABLE POA;Lo;0;L;;;;;N;;;;; -2D93;ETHIOPIC SYLLABLE GGWA;Lo;0;L;;;;;N;;;;; -2D94;ETHIOPIC SYLLABLE GGWI;Lo;0;L;;;;;N;;;;; -2D95;ETHIOPIC SYLLABLE GGWEE;Lo;0;L;;;;;N;;;;; -2D96;ETHIOPIC SYLLABLE GGWE;Lo;0;L;;;;;N;;;;; -2DA0;ETHIOPIC SYLLABLE SSA;Lo;0;L;;;;;N;;;;; -2DA1;ETHIOPIC SYLLABLE SSU;Lo;0;L;;;;;N;;;;; -2DA2;ETHIOPIC SYLLABLE SSI;Lo;0;L;;;;;N;;;;; -2DA3;ETHIOPIC SYLLABLE SSAA;Lo;0;L;;;;;N;;;;; -2DA4;ETHIOPIC SYLLABLE SSEE;Lo;0;L;;;;;N;;;;; -2DA5;ETHIOPIC SYLLABLE SSE;Lo;0;L;;;;;N;;;;; -2DA6;ETHIOPIC SYLLABLE SSO;Lo;0;L;;;;;N;;;;; -2DA8;ETHIOPIC SYLLABLE CCA;Lo;0;L;;;;;N;;;;; -2DA9;ETHIOPIC SYLLABLE CCU;Lo;0;L;;;;;N;;;;; -2DAA;ETHIOPIC SYLLABLE CCI;Lo;0;L;;;;;N;;;;; -2DAB;ETHIOPIC SYLLABLE CCAA;Lo;0;L;;;;;N;;;;; -2DAC;ETHIOPIC SYLLABLE CCEE;Lo;0;L;;;;;N;;;;; -2DAD;ETHIOPIC SYLLABLE CCE;Lo;0;L;;;;;N;;;;; -2DAE;ETHIOPIC SYLLABLE CCO;Lo;0;L;;;;;N;;;;; -2DB0;ETHIOPIC SYLLABLE ZZA;Lo;0;L;;;;;N;;;;; -2DB1;ETHIOPIC SYLLABLE ZZU;Lo;0;L;;;;;N;;;;; -2DB2;ETHIOPIC SYLLABLE ZZI;Lo;0;L;;;;;N;;;;; -2DB3;ETHIOPIC SYLLABLE ZZAA;Lo;0;L;;;;;N;;;;; -2DB4;ETHIOPIC SYLLABLE ZZEE;Lo;0;L;;;;;N;;;;; -2DB5;ETHIOPIC SYLLABLE ZZE;Lo;0;L;;;;;N;;;;; -2DB6;ETHIOPIC SYLLABLE ZZO;Lo;0;L;;;;;N;;;;; -2DB8;ETHIOPIC SYLLABLE CCHA;Lo;0;L;;;;;N;;;;; -2DB9;ETHIOPIC SYLLABLE CCHU;Lo;0;L;;;;;N;;;;; -2DBA;ETHIOPIC SYLLABLE CCHI;Lo;0;L;;;;;N;;;;; -2DBB;ETHIOPIC SYLLABLE CCHAA;Lo;0;L;;;;;N;;;;; -2DBC;ETHIOPIC SYLLABLE CCHEE;Lo;0;L;;;;;N;;;;; -2DBD;ETHIOPIC SYLLABLE CCHE;Lo;0;L;;;;;N;;;;; -2DBE;ETHIOPIC SYLLABLE CCHO;Lo;0;L;;;;;N;;;;; -2DC0;ETHIOPIC SYLLABLE QYA;Lo;0;L;;;;;N;;;;; -2DC1;ETHIOPIC SYLLABLE QYU;Lo;0;L;;;;;N;;;;; -2DC2;ETHIOPIC SYLLABLE QYI;Lo;0;L;;;;;N;;;;; -2DC3;ETHIOPIC SYLLABLE QYAA;Lo;0;L;;;;;N;;;;; -2DC4;ETHIOPIC SYLLABLE QYEE;Lo;0;L;;;;;N;;;;; -2DC5;ETHIOPIC SYLLABLE QYE;Lo;0;L;;;;;N;;;;; -2DC6;ETHIOPIC SYLLABLE QYO;Lo;0;L;;;;;N;;;;; -2DC8;ETHIOPIC SYLLABLE KYA;Lo;0;L;;;;;N;;;;; -2DC9;ETHIOPIC SYLLABLE KYU;Lo;0;L;;;;;N;;;;; -2DCA;ETHIOPIC SYLLABLE KYI;Lo;0;L;;;;;N;;;;; -2DCB;ETHIOPIC SYLLABLE KYAA;Lo;0;L;;;;;N;;;;; -2DCC;ETHIOPIC SYLLABLE KYEE;Lo;0;L;;;;;N;;;;; -2DCD;ETHIOPIC SYLLABLE KYE;Lo;0;L;;;;;N;;;;; -2DCE;ETHIOPIC SYLLABLE KYO;Lo;0;L;;;;;N;;;;; -2DD0;ETHIOPIC SYLLABLE XYA;Lo;0;L;;;;;N;;;;; -2DD1;ETHIOPIC SYLLABLE XYU;Lo;0;L;;;;;N;;;;; -2DD2;ETHIOPIC SYLLABLE XYI;Lo;0;L;;;;;N;;;;; -2DD3;ETHIOPIC SYLLABLE XYAA;Lo;0;L;;;;;N;;;;; -2DD4;ETHIOPIC SYLLABLE XYEE;Lo;0;L;;;;;N;;;;; -2DD5;ETHIOPIC SYLLABLE XYE;Lo;0;L;;;;;N;;;;; -2DD6;ETHIOPIC SYLLABLE XYO;Lo;0;L;;;;;N;;;;; -2DD8;ETHIOPIC SYLLABLE GYA;Lo;0;L;;;;;N;;;;; -2DD9;ETHIOPIC SYLLABLE GYU;Lo;0;L;;;;;N;;;;; -2DDA;ETHIOPIC SYLLABLE GYI;Lo;0;L;;;;;N;;;;; -2DDB;ETHIOPIC SYLLABLE GYAA;Lo;0;L;;;;;N;;;;; -2DDC;ETHIOPIC SYLLABLE GYEE;Lo;0;L;;;;;N;;;;; -2DDD;ETHIOPIC SYLLABLE GYE;Lo;0;L;;;;;N;;;;; -2DDE;ETHIOPIC SYLLABLE GYO;Lo;0;L;;;;;N;;;;; -2DE0;COMBINING CYRILLIC LETTER BE;Mn;230;NSM;;;;;N;;;;; -2DE1;COMBINING CYRILLIC LETTER VE;Mn;230;NSM;;;;;N;;;;; -2DE2;COMBINING CYRILLIC LETTER GHE;Mn;230;NSM;;;;;N;;;;; -2DE3;COMBINING CYRILLIC LETTER DE;Mn;230;NSM;;;;;N;;;;; -2DE4;COMBINING CYRILLIC LETTER ZHE;Mn;230;NSM;;;;;N;;;;; -2DE5;COMBINING CYRILLIC LETTER ZE;Mn;230;NSM;;;;;N;;;;; -2DE6;COMBINING CYRILLIC LETTER KA;Mn;230;NSM;;;;;N;;;;; -2DE7;COMBINING CYRILLIC LETTER EL;Mn;230;NSM;;;;;N;;;;; -2DE8;COMBINING CYRILLIC LETTER EM;Mn;230;NSM;;;;;N;;;;; -2DE9;COMBINING CYRILLIC LETTER EN;Mn;230;NSM;;;;;N;;;;; -2DEA;COMBINING CYRILLIC LETTER O;Mn;230;NSM;;;;;N;;;;; -2DEB;COMBINING CYRILLIC LETTER PE;Mn;230;NSM;;;;;N;;;;; -2DEC;COMBINING CYRILLIC LETTER ER;Mn;230;NSM;;;;;N;;;;; -2DED;COMBINING CYRILLIC LETTER ES;Mn;230;NSM;;;;;N;;;;; -2DEE;COMBINING CYRILLIC LETTER TE;Mn;230;NSM;;;;;N;;;;; -2DEF;COMBINING CYRILLIC LETTER HA;Mn;230;NSM;;;;;N;;;;; -2DF0;COMBINING CYRILLIC LETTER TSE;Mn;230;NSM;;;;;N;;;;; -2DF1;COMBINING CYRILLIC LETTER CHE;Mn;230;NSM;;;;;N;;;;; -2DF2;COMBINING CYRILLIC LETTER SHA;Mn;230;NSM;;;;;N;;;;; -2DF3;COMBINING CYRILLIC LETTER SHCHA;Mn;230;NSM;;;;;N;;;;; -2DF4;COMBINING CYRILLIC LETTER FITA;Mn;230;NSM;;;;;N;;;;; -2DF5;COMBINING CYRILLIC LETTER ES-TE;Mn;230;NSM;;;;;N;;;;; -2DF6;COMBINING CYRILLIC LETTER A;Mn;230;NSM;;;;;N;;;;; -2DF7;COMBINING CYRILLIC LETTER IE;Mn;230;NSM;;;;;N;;;;; -2DF8;COMBINING CYRILLIC LETTER DJERV;Mn;230;NSM;;;;;N;;;;; -2DF9;COMBINING CYRILLIC LETTER MONOGRAPH UK;Mn;230;NSM;;;;;N;;;;; -2DFA;COMBINING CYRILLIC LETTER YAT;Mn;230;NSM;;;;;N;;;;; -2DFB;COMBINING CYRILLIC LETTER YU;Mn;230;NSM;;;;;N;;;;; -2DFC;COMBINING CYRILLIC LETTER IOTIFIED A;Mn;230;NSM;;;;;N;;;;; -2DFD;COMBINING CYRILLIC LETTER LITTLE YUS;Mn;230;NSM;;;;;N;;;;; -2DFE;COMBINING CYRILLIC LETTER BIG YUS;Mn;230;NSM;;;;;N;;;;; -2DFF;COMBINING CYRILLIC LETTER IOTIFIED BIG YUS;Mn;230;NSM;;;;;N;;;;; -2E00;RIGHT ANGLE SUBSTITUTION MARKER;Po;0;ON;;;;;N;;;;; -2E01;RIGHT ANGLE DOTTED SUBSTITUTION MARKER;Po;0;ON;;;;;N;;;;; -2E02;LEFT SUBSTITUTION BRACKET;Pi;0;ON;;;;;Y;;;;; -2E03;RIGHT SUBSTITUTION BRACKET;Pf;0;ON;;;;;Y;;;;; -2E04;LEFT DOTTED SUBSTITUTION BRACKET;Pi;0;ON;;;;;Y;;;;; -2E05;RIGHT DOTTED SUBSTITUTION BRACKET;Pf;0;ON;;;;;Y;;;;; -2E06;RAISED INTERPOLATION MARKER;Po;0;ON;;;;;N;;;;; -2E07;RAISED DOTTED INTERPOLATION MARKER;Po;0;ON;;;;;N;;;;; -2E08;DOTTED TRANSPOSITION MARKER;Po;0;ON;;;;;N;;;;; -2E09;LEFT TRANSPOSITION BRACKET;Pi;0;ON;;;;;Y;;;;; -2E0A;RIGHT TRANSPOSITION BRACKET;Pf;0;ON;;;;;Y;;;;; -2E0B;RAISED SQUARE;Po;0;ON;;;;;N;;;;; -2E0C;LEFT RAISED OMISSION BRACKET;Pi;0;ON;;;;;Y;;;;; -2E0D;RIGHT RAISED OMISSION BRACKET;Pf;0;ON;;;;;Y;;;;; -2E0E;EDITORIAL CORONIS;Po;0;ON;;;;;N;;;;; -2E0F;PARAGRAPHOS;Po;0;ON;;;;;N;;;;; -2E10;FORKED PARAGRAPHOS;Po;0;ON;;;;;N;;;;; -2E11;REVERSED FORKED PARAGRAPHOS;Po;0;ON;;;;;N;;;;; -2E12;HYPODIASTOLE;Po;0;ON;;;;;N;;;;; -2E13;DOTTED OBELOS;Po;0;ON;;;;;N;;;;; -2E14;DOWNWARDS ANCORA;Po;0;ON;;;;;N;;;;; -2E15;UPWARDS ANCORA;Po;0;ON;;;;;N;;;;; -2E16;DOTTED RIGHT-POINTING ANGLE;Po;0;ON;;;;;N;;;;; -2E17;DOUBLE OBLIQUE HYPHEN;Pd;0;ON;;;;;N;;;;; -2E18;INVERTED INTERROBANG;Po;0;ON;;;;;N;;;;; -2E19;PALM BRANCH;Po;0;ON;;;;;N;;;;; -2E1A;HYPHEN WITH DIAERESIS;Pd;0;ON;;;;;N;;;;; -2E1B;TILDE WITH RING ABOVE;Po;0;ON;;;;;N;;;;; -2E1C;LEFT LOW PARAPHRASE BRACKET;Pi;0;ON;;;;;Y;;;;; -2E1D;RIGHT LOW PARAPHRASE BRACKET;Pf;0;ON;;;;;Y;;;;; -2E1E;TILDE WITH DOT ABOVE;Po;0;ON;;;;;N;;;;; -2E1F;TILDE WITH DOT BELOW;Po;0;ON;;;;;N;;;;; -2E20;LEFT VERTICAL BAR WITH QUILL;Pi;0;ON;;;;;Y;;;;; -2E21;RIGHT VERTICAL BAR WITH QUILL;Pf;0;ON;;;;;Y;;;;; -2E22;TOP LEFT HALF BRACKET;Ps;0;ON;;;;;Y;;;;; -2E23;TOP RIGHT HALF BRACKET;Pe;0;ON;;;;;Y;;;;; -2E24;BOTTOM LEFT HALF BRACKET;Ps;0;ON;;;;;Y;;;;; -2E25;BOTTOM RIGHT HALF BRACKET;Pe;0;ON;;;;;Y;;;;; -2E26;LEFT SIDEWAYS U BRACKET;Ps;0;ON;;;;;Y;;;;; -2E27;RIGHT SIDEWAYS U BRACKET;Pe;0;ON;;;;;Y;;;;; -2E28;LEFT DOUBLE PARENTHESIS;Ps;0;ON;;;;;Y;;;;; -2E29;RIGHT DOUBLE PARENTHESIS;Pe;0;ON;;;;;Y;;;;; -2E2A;TWO DOTS OVER ONE DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -2E2B;ONE DOT OVER TWO DOTS PUNCTUATION;Po;0;ON;;;;;N;;;;; -2E2C;SQUARED FOUR DOT PUNCTUATION;Po;0;ON;;;;;N;;;;; -2E2D;FIVE DOT MARK;Po;0;ON;;;;;N;;;;; -2E2E;REVERSED QUESTION MARK;Po;0;ON;;;;;N;;;;; -2E2F;VERTICAL TILDE;Lm;0;ON;;;;;N;;;;; -2E30;RING POINT;Po;0;ON;;;;;N;;;;; -2E80;CJK RADICAL REPEAT;So;0;ON;;;;;N;;;;; -2E81;CJK RADICAL CLIFF;So;0;ON;;;;;N;;;;; -2E82;CJK RADICAL SECOND ONE;So;0;ON;;;;;N;;;;; -2E83;CJK RADICAL SECOND TWO;So;0;ON;;;;;N;;;;; -2E84;CJK RADICAL SECOND THREE;So;0;ON;;;;;N;;;;; -2E85;CJK RADICAL PERSON;So;0;ON;;;;;N;;;;; -2E86;CJK RADICAL BOX;So;0;ON;;;;;N;;;;; -2E87;CJK RADICAL TABLE;So;0;ON;;;;;N;;;;; -2E88;CJK RADICAL KNIFE ONE;So;0;ON;;;;;N;;;;; -2E89;CJK RADICAL KNIFE TWO;So;0;ON;;;;;N;;;;; -2E8A;CJK RADICAL DIVINATION;So;0;ON;;;;;N;;;;; -2E8B;CJK RADICAL SEAL;So;0;ON;;;;;N;;;;; -2E8C;CJK RADICAL SMALL ONE;So;0;ON;;;;;N;;;;; -2E8D;CJK RADICAL SMALL TWO;So;0;ON;;;;;N;;;;; -2E8E;CJK RADICAL LAME ONE;So;0;ON;;;;;N;;;;; -2E8F;CJK RADICAL LAME TWO;So;0;ON;;;;;N;;;;; -2E90;CJK RADICAL LAME THREE;So;0;ON;;;;;N;;;;; -2E91;CJK RADICAL LAME FOUR;So;0;ON;;;;;N;;;;; -2E92;CJK RADICAL SNAKE;So;0;ON;;;;;N;;;;; -2E93;CJK RADICAL THREAD;So;0;ON;;;;;N;;;;; -2E94;CJK RADICAL SNOUT ONE;So;0;ON;;;;;N;;;;; -2E95;CJK RADICAL SNOUT TWO;So;0;ON;;;;;N;;;;; -2E96;CJK RADICAL HEART ONE;So;0;ON;;;;;N;;;;; -2E97;CJK RADICAL HEART TWO;So;0;ON;;;;;N;;;;; -2E98;CJK RADICAL HAND;So;0;ON;;;;;N;;;;; -2E99;CJK RADICAL RAP;So;0;ON;;;;;N;;;;; -2E9B;CJK RADICAL CHOKE;So;0;ON;;;;;N;;;;; -2E9C;CJK RADICAL SUN;So;0;ON;;;;;N;;;;; -2E9D;CJK RADICAL MOON;So;0;ON;;;;;N;;;;; -2E9E;CJK RADICAL DEATH;So;0;ON;;;;;N;;;;; -2E9F;CJK RADICAL MOTHER;So;0;ON; 6BCD;;;;N;;;;; -2EA0;CJK RADICAL CIVILIAN;So;0;ON;;;;;N;;;;; -2EA1;CJK RADICAL WATER ONE;So;0;ON;;;;;N;;;;; -2EA2;CJK RADICAL WATER TWO;So;0;ON;;;;;N;;;;; -2EA3;CJK RADICAL FIRE;So;0;ON;;;;;N;;;;; -2EA4;CJK RADICAL PAW ONE;So;0;ON;;;;;N;;;;; -2EA5;CJK RADICAL PAW TWO;So;0;ON;;;;;N;;;;; -2EA6;CJK RADICAL SIMPLIFIED HALF TREE TRUNK;So;0;ON;;;;;N;;;;; -2EA7;CJK RADICAL COW;So;0;ON;;;;;N;;;;; -2EA8;CJK RADICAL DOG;So;0;ON;;;;;N;;;;; -2EA9;CJK RADICAL JADE;So;0;ON;;;;;N;;;;; -2EAA;CJK RADICAL BOLT OF CLOTH;So;0;ON;;;;;N;;;;; -2EAB;CJK RADICAL EYE;So;0;ON;;;;;N;;;;; -2EAC;CJK RADICAL SPIRIT ONE;So;0;ON;;;;;N;;;;; -2EAD;CJK RADICAL SPIRIT TWO;So;0;ON;;;;;N;;;;; -2EAE;CJK RADICAL BAMBOO;So;0;ON;;;;;N;;;;; -2EAF;CJK RADICAL SILK;So;0;ON;;;;;N;;;;; -2EB0;CJK RADICAL C-SIMPLIFIED SILK;So;0;ON;;;;;N;;;;; -2EB1;CJK RADICAL NET ONE;So;0;ON;;;;;N;;;;; -2EB2;CJK RADICAL NET TWO;So;0;ON;;;;;N;;;;; -2EB3;CJK RADICAL NET THREE;So;0;ON;;;;;N;;;;; -2EB4;CJK RADICAL NET FOUR;So;0;ON;;;;;N;;;;; -2EB5;CJK RADICAL MESH;So;0;ON;;;;;N;;;;; -2EB6;CJK RADICAL SHEEP;So;0;ON;;;;;N;;;;; -2EB7;CJK RADICAL RAM;So;0;ON;;;;;N;;;;; -2EB8;CJK RADICAL EWE;So;0;ON;;;;;N;;;;; -2EB9;CJK RADICAL OLD;So;0;ON;;;;;N;;;;; -2EBA;CJK RADICAL BRUSH ONE;So;0;ON;;;;;N;;;;; -2EBB;CJK RADICAL BRUSH TWO;So;0;ON;;;;;N;;;;; -2EBC;CJK RADICAL MEAT;So;0;ON;;;;;N;;;;; -2EBD;CJK RADICAL MORTAR;So;0;ON;;;;;N;;;;; -2EBE;CJK RADICAL GRASS ONE;So;0;ON;;;;;N;;;;; -2EBF;CJK RADICAL GRASS TWO;So;0;ON;;;;;N;;;;; -2EC0;CJK RADICAL GRASS THREE;So;0;ON;;;;;N;;;;; -2EC1;CJK RADICAL TIGER;So;0;ON;;;;;N;;;;; -2EC2;CJK RADICAL CLOTHES;So;0;ON;;;;;N;;;;; -2EC3;CJK RADICAL WEST ONE;So;0;ON;;;;;N;;;;; -2EC4;CJK RADICAL WEST TWO;So;0;ON;;;;;N;;;;; -2EC5;CJK RADICAL C-SIMPLIFIED SEE;So;0;ON;;;;;N;;;;; -2EC6;CJK RADICAL SIMPLIFIED HORN;So;0;ON;;;;;N;;;;; -2EC7;CJK RADICAL HORN;So;0;ON;;;;;N;;;;; -2EC8;CJK RADICAL C-SIMPLIFIED SPEECH;So;0;ON;;;;;N;;;;; -2EC9;CJK RADICAL C-SIMPLIFIED SHELL;So;0;ON;;;;;N;;;;; -2ECA;CJK RADICAL FOOT;So;0;ON;;;;;N;;;;; -2ECB;CJK RADICAL C-SIMPLIFIED CART;So;0;ON;;;;;N;;;;; -2ECC;CJK RADICAL SIMPLIFIED WALK;So;0;ON;;;;;N;;;;; -2ECD;CJK RADICAL WALK ONE;So;0;ON;;;;;N;;;;; -2ECE;CJK RADICAL WALK TWO;So;0;ON;;;;;N;;;;; -2ECF;CJK RADICAL CITY;So;0;ON;;;;;N;;;;; -2ED0;CJK RADICAL C-SIMPLIFIED GOLD;So;0;ON;;;;;N;;;;; -2ED1;CJK RADICAL LONG ONE;So;0;ON;;;;;N;;;;; -2ED2;CJK RADICAL LONG TWO;So;0;ON;;;;;N;;;;; -2ED3;CJK RADICAL C-SIMPLIFIED LONG;So;0;ON;;;;;N;;;;; -2ED4;CJK RADICAL C-SIMPLIFIED GATE;So;0;ON;;;;;N;;;;; -2ED5;CJK RADICAL MOUND ONE;So;0;ON;;;;;N;;;;; -2ED6;CJK RADICAL MOUND TWO;So;0;ON;;;;;N;;;;; -2ED7;CJK RADICAL RAIN;So;0;ON;;;;;N;;;;; -2ED8;CJK RADICAL BLUE;So;0;ON;;;;;N;;;;; -2ED9;CJK RADICAL C-SIMPLIFIED TANNED LEATHER;So;0;ON;;;;;N;;;;; -2EDA;CJK RADICAL C-SIMPLIFIED LEAF;So;0;ON;;;;;N;;;;; -2EDB;CJK RADICAL C-SIMPLIFIED WIND;So;0;ON;;;;;N;;;;; -2EDC;CJK RADICAL C-SIMPLIFIED FLY;So;0;ON;;;;;N;;;;; -2EDD;CJK RADICAL EAT ONE;So;0;ON;;;;;N;;;;; -2EDE;CJK RADICAL EAT TWO;So;0;ON;;;;;N;;;;; -2EDF;CJK RADICAL EAT THREE;So;0;ON;;;;;N;;;;; -2EE0;CJK RADICAL C-SIMPLIFIED EAT;So;0;ON;;;;;N;;;;; -2EE1;CJK RADICAL HEAD;So;0;ON;;;;;N;;;;; -2EE2;CJK RADICAL C-SIMPLIFIED HORSE;So;0;ON;;;;;N;;;;; -2EE3;CJK RADICAL BONE;So;0;ON;;;;;N;;;;; -2EE4;CJK RADICAL GHOST;So;0;ON;;;;;N;;;;; -2EE5;CJK RADICAL C-SIMPLIFIED FISH;So;0;ON;;;;;N;;;;; -2EE6;CJK RADICAL C-SIMPLIFIED BIRD;So;0;ON;;;;;N;;;;; -2EE7;CJK RADICAL C-SIMPLIFIED SALT;So;0;ON;;;;;N;;;;; -2EE8;CJK RADICAL SIMPLIFIED WHEAT;So;0;ON;;;;;N;;;;; -2EE9;CJK RADICAL SIMPLIFIED YELLOW;So;0;ON;;;;;N;;;;; -2EEA;CJK RADICAL C-SIMPLIFIED FROG;So;0;ON;;;;;N;;;;; -2EEB;CJK RADICAL J-SIMPLIFIED EVEN;So;0;ON;;;;;N;;;;; -2EEC;CJK RADICAL C-SIMPLIFIED EVEN;So;0;ON;;;;;N;;;;; -2EED;CJK RADICAL J-SIMPLIFIED TOOTH;So;0;ON;;;;;N;;;;; -2EEE;CJK RADICAL C-SIMPLIFIED TOOTH;So;0;ON;;;;;N;;;;; -2EEF;CJK RADICAL J-SIMPLIFIED DRAGON;So;0;ON;;;;;N;;;;; -2EF0;CJK RADICAL C-SIMPLIFIED DRAGON;So;0;ON;;;;;N;;;;; -2EF1;CJK RADICAL TURTLE;So;0;ON;;;;;N;;;;; -2EF2;CJK RADICAL J-SIMPLIFIED TURTLE;So;0;ON;;;;;N;;;;; -2EF3;CJK RADICAL C-SIMPLIFIED TURTLE;So;0;ON; 9F9F;;;;N;;;;; -2F00;KANGXI RADICAL ONE;So;0;ON; 4E00;;;;N;;;;; -2F01;KANGXI RADICAL LINE;So;0;ON; 4E28;;;;N;;;;; -2F02;KANGXI RADICAL DOT;So;0;ON; 4E36;;;;N;;;;; -2F03;KANGXI RADICAL SLASH;So;0;ON; 4E3F;;;;N;;;;; -2F04;KANGXI RADICAL SECOND;So;0;ON; 4E59;;;;N;;;;; -2F05;KANGXI RADICAL HOOK;So;0;ON; 4E85;;;;N;;;;; -2F06;KANGXI RADICAL TWO;So;0;ON; 4E8C;;;;N;;;;; -2F07;KANGXI RADICAL LID;So;0;ON; 4EA0;;;;N;;;;; -2F08;KANGXI RADICAL MAN;So;0;ON; 4EBA;;;;N;;;;; -2F09;KANGXI RADICAL LEGS;So;0;ON; 513F;;;;N;;;;; -2F0A;KANGXI RADICAL ENTER;So;0;ON; 5165;;;;N;;;;; -2F0B;KANGXI RADICAL EIGHT;So;0;ON; 516B;;;;N;;;;; -2F0C;KANGXI RADICAL DOWN BOX;So;0;ON; 5182;;;;N;;;;; -2F0D;KANGXI RADICAL COVER;So;0;ON; 5196;;;;N;;;;; -2F0E;KANGXI RADICAL ICE;So;0;ON; 51AB;;;;N;;;;; -2F0F;KANGXI RADICAL TABLE;So;0;ON; 51E0;;;;N;;;;; -2F10;KANGXI RADICAL OPEN BOX;So;0;ON; 51F5;;;;N;;;;; -2F11;KANGXI RADICAL KNIFE;So;0;ON; 5200;;;;N;;;;; -2F12;KANGXI RADICAL POWER;So;0;ON; 529B;;;;N;;;;; -2F13;KANGXI RADICAL WRAP;So;0;ON; 52F9;;;;N;;;;; -2F14;KANGXI RADICAL SPOON;So;0;ON; 5315;;;;N;;;;; -2F15;KANGXI RADICAL RIGHT OPEN BOX;So;0;ON; 531A;;;;N;;;;; -2F16;KANGXI RADICAL HIDING ENCLOSURE;So;0;ON; 5338;;;;N;;;;; -2F17;KANGXI RADICAL TEN;So;0;ON; 5341;;;;N;;;;; -2F18;KANGXI RADICAL DIVINATION;So;0;ON; 535C;;;;N;;;;; -2F19;KANGXI RADICAL SEAL;So;0;ON; 5369;;;;N;;;;; -2F1A;KANGXI RADICAL CLIFF;So;0;ON; 5382;;;;N;;;;; -2F1B;KANGXI RADICAL PRIVATE;So;0;ON; 53B6;;;;N;;;;; -2F1C;KANGXI RADICAL AGAIN;So;0;ON; 53C8;;;;N;;;;; -2F1D;KANGXI RADICAL MOUTH;So;0;ON; 53E3;;;;N;;;;; -2F1E;KANGXI RADICAL ENCLOSURE;So;0;ON; 56D7;;;;N;;;;; -2F1F;KANGXI RADICAL EARTH;So;0;ON; 571F;;;;N;;;;; -2F20;KANGXI RADICAL SCHOLAR;So;0;ON; 58EB;;;;N;;;;; -2F21;KANGXI RADICAL GO;So;0;ON; 5902;;;;N;;;;; -2F22;KANGXI RADICAL GO SLOWLY;So;0;ON; 590A;;;;N;;;;; -2F23;KANGXI RADICAL EVENING;So;0;ON; 5915;;;;N;;;;; -2F24;KANGXI RADICAL BIG;So;0;ON; 5927;;;;N;;;;; -2F25;KANGXI RADICAL WOMAN;So;0;ON; 5973;;;;N;;;;; -2F26;KANGXI RADICAL CHILD;So;0;ON; 5B50;;;;N;;;;; -2F27;KANGXI RADICAL ROOF;So;0;ON; 5B80;;;;N;;;;; -2F28;KANGXI RADICAL INCH;So;0;ON; 5BF8;;;;N;;;;; -2F29;KANGXI RADICAL SMALL;So;0;ON; 5C0F;;;;N;;;;; -2F2A;KANGXI RADICAL LAME;So;0;ON; 5C22;;;;N;;;;; -2F2B;KANGXI RADICAL CORPSE;So;0;ON; 5C38;;;;N;;;;; -2F2C;KANGXI RADICAL SPROUT;So;0;ON; 5C6E;;;;N;;;;; -2F2D;KANGXI RADICAL MOUNTAIN;So;0;ON; 5C71;;;;N;;;;; -2F2E;KANGXI RADICAL RIVER;So;0;ON; 5DDB;;;;N;;;;; -2F2F;KANGXI RADICAL WORK;So;0;ON; 5DE5;;;;N;;;;; -2F30;KANGXI RADICAL ONESELF;So;0;ON; 5DF1;;;;N;;;;; -2F31;KANGXI RADICAL TURBAN;So;0;ON; 5DFE;;;;N;;;;; -2F32;KANGXI RADICAL DRY;So;0;ON; 5E72;;;;N;;;;; -2F33;KANGXI RADICAL SHORT THREAD;So;0;ON; 5E7A;;;;N;;;;; -2F34;KANGXI RADICAL DOTTED CLIFF;So;0;ON; 5E7F;;;;N;;;;; -2F35;KANGXI RADICAL LONG STRIDE;So;0;ON; 5EF4;;;;N;;;;; -2F36;KANGXI RADICAL TWO HANDS;So;0;ON; 5EFE;;;;N;;;;; -2F37;KANGXI RADICAL SHOOT;So;0;ON; 5F0B;;;;N;;;;; -2F38;KANGXI RADICAL BOW;So;0;ON; 5F13;;;;N;;;;; -2F39;KANGXI RADICAL SNOUT;So;0;ON; 5F50;;;;N;;;;; -2F3A;KANGXI RADICAL BRISTLE;So;0;ON; 5F61;;;;N;;;;; -2F3B;KANGXI RADICAL STEP;So;0;ON; 5F73;;;;N;;;;; -2F3C;KANGXI RADICAL HEART;So;0;ON; 5FC3;;;;N;;;;; -2F3D;KANGXI RADICAL HALBERD;So;0;ON; 6208;;;;N;;;;; -2F3E;KANGXI RADICAL DOOR;So;0;ON; 6236;;;;N;;;;; -2F3F;KANGXI RADICAL HAND;So;0;ON; 624B;;;;N;;;;; -2F40;KANGXI RADICAL BRANCH;So;0;ON; 652F;;;;N;;;;; -2F41;KANGXI RADICAL RAP;So;0;ON; 6534;;;;N;;;;; -2F42;KANGXI RADICAL SCRIPT;So;0;ON; 6587;;;;N;;;;; -2F43;KANGXI RADICAL DIPPER;So;0;ON; 6597;;;;N;;;;; -2F44;KANGXI RADICAL AXE;So;0;ON; 65A4;;;;N;;;;; -2F45;KANGXI RADICAL SQUARE;So;0;ON; 65B9;;;;N;;;;; -2F46;KANGXI RADICAL NOT;So;0;ON; 65E0;;;;N;;;;; -2F47;KANGXI RADICAL SUN;So;0;ON; 65E5;;;;N;;;;; -2F48;KANGXI RADICAL SAY;So;0;ON; 66F0;;;;N;;;;; -2F49;KANGXI RADICAL MOON;So;0;ON; 6708;;;;N;;;;; -2F4A;KANGXI RADICAL TREE;So;0;ON; 6728;;;;N;;;;; -2F4B;KANGXI RADICAL LACK;So;0;ON; 6B20;;;;N;;;;; -2F4C;KANGXI RADICAL STOP;So;0;ON; 6B62;;;;N;;;;; -2F4D;KANGXI RADICAL DEATH;So;0;ON; 6B79;;;;N;;;;; -2F4E;KANGXI RADICAL WEAPON;So;0;ON; 6BB3;;;;N;;;;; -2F4F;KANGXI RADICAL DO NOT;So;0;ON; 6BCB;;;;N;;;;; -2F50;KANGXI RADICAL COMPARE;So;0;ON; 6BD4;;;;N;;;;; -2F51;KANGXI RADICAL FUR;So;0;ON; 6BDB;;;;N;;;;; -2F52;KANGXI RADICAL CLAN;So;0;ON; 6C0F;;;;N;;;;; -2F53;KANGXI RADICAL STEAM;So;0;ON; 6C14;;;;N;;;;; -2F54;KANGXI RADICAL WATER;So;0;ON; 6C34;;;;N;;;;; -2F55;KANGXI RADICAL FIRE;So;0;ON; 706B;;;;N;;;;; -2F56;KANGXI RADICAL CLAW;So;0;ON; 722A;;;;N;;;;; -2F57;KANGXI RADICAL FATHER;So;0;ON; 7236;;;;N;;;;; -2F58;KANGXI RADICAL DOUBLE X;So;0;ON; 723B;;;;N;;;;; -2F59;KANGXI RADICAL HALF TREE TRUNK;So;0;ON; 723F;;;;N;;;;; -2F5A;KANGXI RADICAL SLICE;So;0;ON; 7247;;;;N;;;;; -2F5B;KANGXI RADICAL FANG;So;0;ON; 7259;;;;N;;;;; -2F5C;KANGXI RADICAL COW;So;0;ON; 725B;;;;N;;;;; -2F5D;KANGXI RADICAL DOG;So;0;ON; 72AC;;;;N;;;;; -2F5E;KANGXI RADICAL PROFOUND;So;0;ON; 7384;;;;N;;;;; -2F5F;KANGXI RADICAL JADE;So;0;ON; 7389;;;;N;;;;; -2F60;KANGXI RADICAL MELON;So;0;ON; 74DC;;;;N;;;;; -2F61;KANGXI RADICAL TILE;So;0;ON; 74E6;;;;N;;;;; -2F62;KANGXI RADICAL SWEET;So;0;ON; 7518;;;;N;;;;; -2F63;KANGXI RADICAL LIFE;So;0;ON; 751F;;;;N;;;;; -2F64;KANGXI RADICAL USE;So;0;ON; 7528;;;;N;;;;; -2F65;KANGXI RADICAL FIELD;So;0;ON; 7530;;;;N;;;;; -2F66;KANGXI RADICAL BOLT OF CLOTH;So;0;ON; 758B;;;;N;;;;; -2F67;KANGXI RADICAL SICKNESS;So;0;ON; 7592;;;;N;;;;; -2F68;KANGXI RADICAL DOTTED TENT;So;0;ON; 7676;;;;N;;;;; -2F69;KANGXI RADICAL WHITE;So;0;ON; 767D;;;;N;;;;; -2F6A;KANGXI RADICAL SKIN;So;0;ON; 76AE;;;;N;;;;; -2F6B;KANGXI RADICAL DISH;So;0;ON; 76BF;;;;N;;;;; -2F6C;KANGXI RADICAL EYE;So;0;ON; 76EE;;;;N;;;;; -2F6D;KANGXI RADICAL SPEAR;So;0;ON; 77DB;;;;N;;;;; -2F6E;KANGXI RADICAL ARROW;So;0;ON; 77E2;;;;N;;;;; -2F6F;KANGXI RADICAL STONE;So;0;ON; 77F3;;;;N;;;;; -2F70;KANGXI RADICAL SPIRIT;So;0;ON; 793A;;;;N;;;;; -2F71;KANGXI RADICAL TRACK;So;0;ON; 79B8;;;;N;;;;; -2F72;KANGXI RADICAL GRAIN;So;0;ON; 79BE;;;;N;;;;; -2F73;KANGXI RADICAL CAVE;So;0;ON; 7A74;;;;N;;;;; -2F74;KANGXI RADICAL STAND;So;0;ON; 7ACB;;;;N;;;;; -2F75;KANGXI RADICAL BAMBOO;So;0;ON; 7AF9;;;;N;;;;; -2F76;KANGXI RADICAL RICE;So;0;ON; 7C73;;;;N;;;;; -2F77;KANGXI RADICAL SILK;So;0;ON; 7CF8;;;;N;;;;; -2F78;KANGXI RADICAL JAR;So;0;ON; 7F36;;;;N;;;;; -2F79;KANGXI RADICAL NET;So;0;ON; 7F51;;;;N;;;;; -2F7A;KANGXI RADICAL SHEEP;So;0;ON; 7F8A;;;;N;;;;; -2F7B;KANGXI RADICAL FEATHER;So;0;ON; 7FBD;;;;N;;;;; -2F7C;KANGXI RADICAL OLD;So;0;ON; 8001;;;;N;;;;; -2F7D;KANGXI RADICAL AND;So;0;ON; 800C;;;;N;;;;; -2F7E;KANGXI RADICAL PLOW;So;0;ON; 8012;;;;N;;;;; -2F7F;KANGXI RADICAL EAR;So;0;ON; 8033;;;;N;;;;; -2F80;KANGXI RADICAL BRUSH;So;0;ON; 807F;;;;N;;;;; -2F81;KANGXI RADICAL MEAT;So;0;ON; 8089;;;;N;;;;; -2F82;KANGXI RADICAL MINISTER;So;0;ON; 81E3;;;;N;;;;; -2F83;KANGXI RADICAL SELF;So;0;ON; 81EA;;;;N;;;;; -2F84;KANGXI RADICAL ARRIVE;So;0;ON; 81F3;;;;N;;;;; -2F85;KANGXI RADICAL MORTAR;So;0;ON; 81FC;;;;N;;;;; -2F86;KANGXI RADICAL TONGUE;So;0;ON; 820C;;;;N;;;;; -2F87;KANGXI RADICAL OPPOSE;So;0;ON; 821B;;;;N;;;;; -2F88;KANGXI RADICAL BOAT;So;0;ON; 821F;;;;N;;;;; -2F89;KANGXI RADICAL STOPPING;So;0;ON; 826E;;;;N;;;;; -2F8A;KANGXI RADICAL COLOR;So;0;ON; 8272;;;;N;;;;; -2F8B;KANGXI RADICAL GRASS;So;0;ON; 8278;;;;N;;;;; -2F8C;KANGXI RADICAL TIGER;So;0;ON; 864D;;;;N;;;;; -2F8D;KANGXI RADICAL INSECT;So;0;ON; 866B;;;;N;;;;; -2F8E;KANGXI RADICAL BLOOD;So;0;ON; 8840;;;;N;;;;; -2F8F;KANGXI RADICAL WALK ENCLOSURE;So;0;ON; 884C;;;;N;;;;; -2F90;KANGXI RADICAL CLOTHES;So;0;ON; 8863;;;;N;;;;; -2F91;KANGXI RADICAL WEST;So;0;ON; 897E;;;;N;;;;; -2F92;KANGXI RADICAL SEE;So;0;ON; 898B;;;;N;;;;; -2F93;KANGXI RADICAL HORN;So;0;ON; 89D2;;;;N;;;;; -2F94;KANGXI RADICAL SPEECH;So;0;ON; 8A00;;;;N;;;;; -2F95;KANGXI RADICAL VALLEY;So;0;ON; 8C37;;;;N;;;;; -2F96;KANGXI RADICAL BEAN;So;0;ON; 8C46;;;;N;;;;; -2F97;KANGXI RADICAL PIG;So;0;ON; 8C55;;;;N;;;;; -2F98;KANGXI RADICAL BADGER;So;0;ON; 8C78;;;;N;;;;; -2F99;KANGXI RADICAL SHELL;So;0;ON; 8C9D;;;;N;;;;; -2F9A;KANGXI RADICAL RED;So;0;ON; 8D64;;;;N;;;;; -2F9B;KANGXI RADICAL RUN;So;0;ON; 8D70;;;;N;;;;; -2F9C;KANGXI RADICAL FOOT;So;0;ON; 8DB3;;;;N;;;;; -2F9D;KANGXI RADICAL BODY;So;0;ON; 8EAB;;;;N;;;;; -2F9E;KANGXI RADICAL CART;So;0;ON; 8ECA;;;;N;;;;; -2F9F;KANGXI RADICAL BITTER;So;0;ON; 8F9B;;;;N;;;;; -2FA0;KANGXI RADICAL MORNING;So;0;ON; 8FB0;;;;N;;;;; -2FA1;KANGXI RADICAL WALK;So;0;ON; 8FB5;;;;N;;;;; -2FA2;KANGXI RADICAL CITY;So;0;ON; 9091;;;;N;;;;; -2FA3;KANGXI RADICAL WINE;So;0;ON; 9149;;;;N;;;;; -2FA4;KANGXI RADICAL DISTINGUISH;So;0;ON; 91C6;;;;N;;;;; -2FA5;KANGXI RADICAL VILLAGE;So;0;ON; 91CC;;;;N;;;;; -2FA6;KANGXI RADICAL GOLD;So;0;ON; 91D1;;;;N;;;;; -2FA7;KANGXI RADICAL LONG;So;0;ON; 9577;;;;N;;;;; -2FA8;KANGXI RADICAL GATE;So;0;ON; 9580;;;;N;;;;; -2FA9;KANGXI RADICAL MOUND;So;0;ON; 961C;;;;N;;;;; -2FAA;KANGXI RADICAL SLAVE;So;0;ON; 96B6;;;;N;;;;; -2FAB;KANGXI RADICAL SHORT TAILED BIRD;So;0;ON; 96B9;;;;N;;;;; -2FAC;KANGXI RADICAL RAIN;So;0;ON; 96E8;;;;N;;;;; -2FAD;KANGXI RADICAL BLUE;So;0;ON; 9751;;;;N;;;;; -2FAE;KANGXI RADICAL WRONG;So;0;ON; 975E;;;;N;;;;; -2FAF;KANGXI RADICAL FACE;So;0;ON; 9762;;;;N;;;;; -2FB0;KANGXI RADICAL LEATHER;So;0;ON; 9769;;;;N;;;;; -2FB1;KANGXI RADICAL TANNED LEATHER;So;0;ON; 97CB;;;;N;;;;; -2FB2;KANGXI RADICAL LEEK;So;0;ON; 97ED;;;;N;;;;; -2FB3;KANGXI RADICAL SOUND;So;0;ON; 97F3;;;;N;;;;; -2FB4;KANGXI RADICAL LEAF;So;0;ON; 9801;;;;N;;;;; -2FB5;KANGXI RADICAL WIND;So;0;ON; 98A8;;;;N;;;;; -2FB6;KANGXI RADICAL FLY;So;0;ON; 98DB;;;;N;;;;; -2FB7;KANGXI RADICAL EAT;So;0;ON; 98DF;;;;N;;;;; -2FB8;KANGXI RADICAL HEAD;So;0;ON; 9996;;;;N;;;;; -2FB9;KANGXI RADICAL FRAGRANT;So;0;ON; 9999;;;;N;;;;; -2FBA;KANGXI RADICAL HORSE;So;0;ON; 99AC;;;;N;;;;; -2FBB;KANGXI RADICAL BONE;So;0;ON; 9AA8;;;;N;;;;; -2FBC;KANGXI RADICAL TALL;So;0;ON; 9AD8;;;;N;;;;; -2FBD;KANGXI RADICAL HAIR;So;0;ON; 9ADF;;;;N;;;;; -2FBE;KANGXI RADICAL FIGHT;So;0;ON; 9B25;;;;N;;;;; -2FBF;KANGXI RADICAL SACRIFICIAL WINE;So;0;ON; 9B2F;;;;N;;;;; -2FC0;KANGXI RADICAL CAULDRON;So;0;ON; 9B32;;;;N;;;;; -2FC1;KANGXI RADICAL GHOST;So;0;ON; 9B3C;;;;N;;;;; -2FC2;KANGXI RADICAL FISH;So;0;ON; 9B5A;;;;N;;;;; -2FC3;KANGXI RADICAL BIRD;So;0;ON; 9CE5;;;;N;;;;; -2FC4;KANGXI RADICAL SALT;So;0;ON; 9E75;;;;N;;;;; -2FC5;KANGXI RADICAL DEER;So;0;ON; 9E7F;;;;N;;;;; -2FC6;KANGXI RADICAL WHEAT;So;0;ON; 9EA5;;;;N;;;;; -2FC7;KANGXI RADICAL HEMP;So;0;ON; 9EBB;;;;N;;;;; -2FC8;KANGXI RADICAL YELLOW;So;0;ON; 9EC3;;;;N;;;;; -2FC9;KANGXI RADICAL MILLET;So;0;ON; 9ECD;;;;N;;;;; -2FCA;KANGXI RADICAL BLACK;So;0;ON; 9ED1;;;;N;;;;; -2FCB;KANGXI RADICAL EMBROIDERY;So;0;ON; 9EF9;;;;N;;;;; -2FCC;KANGXI RADICAL FROG;So;0;ON; 9EFD;;;;N;;;;; -2FCD;KANGXI RADICAL TRIPOD;So;0;ON; 9F0E;;;;N;;;;; -2FCE;KANGXI RADICAL DRUM;So;0;ON; 9F13;;;;N;;;;; -2FCF;KANGXI RADICAL RAT;So;0;ON; 9F20;;;;N;;;;; -2FD0;KANGXI RADICAL NOSE;So;0;ON; 9F3B;;;;N;;;;; -2FD1;KANGXI RADICAL EVEN;So;0;ON; 9F4A;;;;N;;;;; -2FD2;KANGXI RADICAL TOOTH;So;0;ON; 9F52;;;;N;;;;; -2FD3;KANGXI RADICAL DRAGON;So;0;ON; 9F8D;;;;N;;;;; -2FD4;KANGXI RADICAL TURTLE;So;0;ON; 9F9C;;;;N;;;;; -2FD5;KANGXI RADICAL FLUTE;So;0;ON; 9FA0;;;;N;;;;; -2FF0;IDEOGRAPHIC DESCRIPTION CHARACTER LEFT TO RIGHT;So;0;ON;;;;;N;;;;; -2FF1;IDEOGRAPHIC DESCRIPTION CHARACTER ABOVE TO BELOW;So;0;ON;;;;;N;;;;; -2FF2;IDEOGRAPHIC DESCRIPTION CHARACTER LEFT TO MIDDLE AND RIGHT;So;0;ON;;;;;N;;;;; -2FF3;IDEOGRAPHIC DESCRIPTION CHARACTER ABOVE TO MIDDLE AND BELOW;So;0;ON;;;;;N;;;;; -2FF4;IDEOGRAPHIC DESCRIPTION CHARACTER FULL SURROUND;So;0;ON;;;;;N;;;;; -2FF5;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM ABOVE;So;0;ON;;;;;N;;;;; -2FF6;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM BELOW;So;0;ON;;;;;N;;;;; -2FF7;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM LEFT;So;0;ON;;;;;N;;;;; -2FF8;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM UPPER LEFT;So;0;ON;;;;;N;;;;; -2FF9;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM UPPER RIGHT;So;0;ON;;;;;N;;;;; -2FFA;IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM LOWER LEFT;So;0;ON;;;;;N;;;;; -2FFB;IDEOGRAPHIC DESCRIPTION CHARACTER OVERLAID;So;0;ON;;;;;N;;;;; -3000;IDEOGRAPHIC SPACE;Zs;0;WS; 0020;;;;N;;;;; -3001;IDEOGRAPHIC COMMA;Po;0;ON;;;;;N;;;;; -3002;IDEOGRAPHIC FULL STOP;Po;0;ON;;;;;N;IDEOGRAPHIC PERIOD;;;; -3003;DITTO MARK;Po;0;ON;;;;;N;;;;; -3004;JAPANESE INDUSTRIAL STANDARD SYMBOL;So;0;ON;;;;;N;;;;; -3005;IDEOGRAPHIC ITERATION MARK;Lm;0;L;;;;;N;;;;; -3006;IDEOGRAPHIC CLOSING MARK;Lo;0;L;;;;;N;;;;; -3007;IDEOGRAPHIC NUMBER ZERO;Nl;0;L;;;;0;N;;;;; -3008;LEFT ANGLE BRACKET;Ps;0;ON;;;;;Y;OPENING ANGLE BRACKET;;;; -3009;RIGHT ANGLE BRACKET;Pe;0;ON;;;;;Y;CLOSING ANGLE BRACKET;;;; -300A;LEFT DOUBLE ANGLE BRACKET;Ps;0;ON;;;;;Y;OPENING DOUBLE ANGLE BRACKET;;;; -300B;RIGHT DOUBLE ANGLE BRACKET;Pe;0;ON;;;;;Y;CLOSING DOUBLE ANGLE BRACKET;;;; -300C;LEFT CORNER BRACKET;Ps;0;ON;;;;;Y;OPENING CORNER BRACKET;;;; -300D;RIGHT CORNER BRACKET;Pe;0;ON;;;;;Y;CLOSING CORNER BRACKET;;;; -300E;LEFT WHITE CORNER BRACKET;Ps;0;ON;;;;;Y;OPENING WHITE CORNER BRACKET;;;; -300F;RIGHT WHITE CORNER BRACKET;Pe;0;ON;;;;;Y;CLOSING WHITE CORNER BRACKET;;;; -3010;LEFT BLACK LENTICULAR BRACKET;Ps;0;ON;;;;;Y;OPENING BLACK LENTICULAR BRACKET;;;; -3011;RIGHT BLACK LENTICULAR BRACKET;Pe;0;ON;;;;;Y;CLOSING BLACK LENTICULAR BRACKET;;;; -3012;POSTAL MARK;So;0;ON;;;;;N;;;;; -3013;GETA MARK;So;0;ON;;;;;N;;;;; -3014;LEFT TORTOISE SHELL BRACKET;Ps;0;ON;;;;;Y;OPENING TORTOISE SHELL BRACKET;;;; -3015;RIGHT TORTOISE SHELL BRACKET;Pe;0;ON;;;;;Y;CLOSING TORTOISE SHELL BRACKET;;;; -3016;LEFT WHITE LENTICULAR BRACKET;Ps;0;ON;;;;;Y;OPENING WHITE LENTICULAR BRACKET;;;; -3017;RIGHT WHITE LENTICULAR BRACKET;Pe;0;ON;;;;;Y;CLOSING WHITE LENTICULAR BRACKET;;;; -3018;LEFT WHITE TORTOISE SHELL BRACKET;Ps;0;ON;;;;;Y;OPENING WHITE TORTOISE SHELL BRACKET;;;; -3019;RIGHT WHITE TORTOISE SHELL BRACKET;Pe;0;ON;;;;;Y;CLOSING WHITE TORTOISE SHELL BRACKET;;;; -301A;LEFT WHITE SQUARE BRACKET;Ps;0;ON;;;;;Y;OPENING WHITE SQUARE BRACKET;;;; -301B;RIGHT WHITE SQUARE BRACKET;Pe;0;ON;;;;;Y;CLOSING WHITE SQUARE BRACKET;;;; -301C;WAVE DASH;Pd;0;ON;;;;;N;;;;; -301D;REVERSED DOUBLE PRIME QUOTATION MARK;Ps;0;ON;;;;;N;;;;; -301E;DOUBLE PRIME QUOTATION MARK;Pe;0;ON;;;;;N;;;;; -301F;LOW DOUBLE PRIME QUOTATION MARK;Pe;0;ON;;;;;N;;;;; -3020;POSTAL MARK FACE;So;0;ON;;;;;N;;;;; -3021;HANGZHOU NUMERAL ONE;Nl;0;L;;;;1;N;;;;; -3022;HANGZHOU NUMERAL TWO;Nl;0;L;;;;2;N;;;;; -3023;HANGZHOU NUMERAL THREE;Nl;0;L;;;;3;N;;;;; -3024;HANGZHOU NUMERAL FOUR;Nl;0;L;;;;4;N;;;;; -3025;HANGZHOU NUMERAL FIVE;Nl;0;L;;;;5;N;;;;; -3026;HANGZHOU NUMERAL SIX;Nl;0;L;;;;6;N;;;;; -3027;HANGZHOU NUMERAL SEVEN;Nl;0;L;;;;7;N;;;;; -3028;HANGZHOU NUMERAL EIGHT;Nl;0;L;;;;8;N;;;;; -3029;HANGZHOU NUMERAL NINE;Nl;0;L;;;;9;N;;;;; -302A;IDEOGRAPHIC LEVEL TONE MARK;Mn;218;NSM;;;;;N;;;;; -302B;IDEOGRAPHIC RISING TONE MARK;Mn;228;NSM;;;;;N;;;;; -302C;IDEOGRAPHIC DEPARTING TONE MARK;Mn;232;NSM;;;;;N;;;;; -302D;IDEOGRAPHIC ENTERING TONE MARK;Mn;222;NSM;;;;;N;;;;; -302E;HANGUL SINGLE DOT TONE MARK;Mn;224;NSM;;;;;N;;;;; -302F;HANGUL DOUBLE DOT TONE MARK;Mn;224;NSM;;;;;N;;;;; -3030;WAVY DASH;Pd;0;ON;;;;;N;;;;; -3031;VERTICAL KANA REPEAT MARK;Lm;0;L;;;;;N;;;;; -3032;VERTICAL KANA REPEAT WITH VOICED SOUND MARK;Lm;0;L;;;;;N;;;;; -3033;VERTICAL KANA REPEAT MARK UPPER HALF;Lm;0;L;;;;;N;;;;; -3034;VERTICAL KANA REPEAT WITH VOICED SOUND MARK UPPER HALF;Lm;0;L;;;;;N;;;;; -3035;VERTICAL KANA REPEAT MARK LOWER HALF;Lm;0;L;;;;;N;;;;; -3036;CIRCLED POSTAL MARK;So;0;ON; 3012;;;;N;;;;; -3037;IDEOGRAPHIC TELEGRAPH LINE FEED SEPARATOR SYMBOL;So;0;ON;;;;;N;;;;; -3038;HANGZHOU NUMERAL TEN;Nl;0;L; 5341;;;10;N;;;;; -3039;HANGZHOU NUMERAL TWENTY;Nl;0;L; 5344;;;20;N;;;;; -303A;HANGZHOU NUMERAL THIRTY;Nl;0;L; 5345;;;30;N;;;;; -303B;VERTICAL IDEOGRAPHIC ITERATION MARK;Lm;0;L;;;;;N;;;;; -303C;MASU MARK;Lo;0;L;;;;;N;;;;; -303D;PART ALTERNATION MARK;Po;0;ON;;;;;N;;;;; -303E;IDEOGRAPHIC VARIATION INDICATOR;So;0;ON;;;;;N;;;;; -303F;IDEOGRAPHIC HALF FILL SPACE;So;0;ON;;;;;N;;;;; -3041;HIRAGANA LETTER SMALL A;Lo;0;L;;;;;N;;;;; -3042;HIRAGANA LETTER A;Lo;0;L;;;;;N;;;;; -3043;HIRAGANA LETTER SMALL I;Lo;0;L;;;;;N;;;;; -3044;HIRAGANA LETTER I;Lo;0;L;;;;;N;;;;; -3045;HIRAGANA LETTER SMALL U;Lo;0;L;;;;;N;;;;; -3046;HIRAGANA LETTER U;Lo;0;L;;;;;N;;;;; -3047;HIRAGANA LETTER SMALL E;Lo;0;L;;;;;N;;;;; -3048;HIRAGANA LETTER E;Lo;0;L;;;;;N;;;;; -3049;HIRAGANA LETTER SMALL O;Lo;0;L;;;;;N;;;;; -304A;HIRAGANA LETTER O;Lo;0;L;;;;;N;;;;; -304B;HIRAGANA LETTER KA;Lo;0;L;;;;;N;;;;; -304C;HIRAGANA LETTER GA;Lo;0;L;304B 3099;;;;N;;;;; -304D;HIRAGANA LETTER KI;Lo;0;L;;;;;N;;;;; -304E;HIRAGANA LETTER GI;Lo;0;L;304D 3099;;;;N;;;;; -304F;HIRAGANA LETTER KU;Lo;0;L;;;;;N;;;;; -3050;HIRAGANA LETTER GU;Lo;0;L;304F 3099;;;;N;;;;; -3051;HIRAGANA LETTER KE;Lo;0;L;;;;;N;;;;; -3052;HIRAGANA LETTER GE;Lo;0;L;3051 3099;;;;N;;;;; -3053;HIRAGANA LETTER KO;Lo;0;L;;;;;N;;;;; -3054;HIRAGANA LETTER GO;Lo;0;L;3053 3099;;;;N;;;;; -3055;HIRAGANA LETTER SA;Lo;0;L;;;;;N;;;;; -3056;HIRAGANA LETTER ZA;Lo;0;L;3055 3099;;;;N;;;;; -3057;HIRAGANA LETTER SI;Lo;0;L;;;;;N;;;;; -3058;HIRAGANA LETTER ZI;Lo;0;L;3057 3099;;;;N;;;;; -3059;HIRAGANA LETTER SU;Lo;0;L;;;;;N;;;;; -305A;HIRAGANA LETTER ZU;Lo;0;L;3059 3099;;;;N;;;;; -305B;HIRAGANA LETTER SE;Lo;0;L;;;;;N;;;;; -305C;HIRAGANA LETTER ZE;Lo;0;L;305B 3099;;;;N;;;;; -305D;HIRAGANA LETTER SO;Lo;0;L;;;;;N;;;;; -305E;HIRAGANA LETTER ZO;Lo;0;L;305D 3099;;;;N;;;;; -305F;HIRAGANA LETTER TA;Lo;0;L;;;;;N;;;;; -3060;HIRAGANA LETTER DA;Lo;0;L;305F 3099;;;;N;;;;; -3061;HIRAGANA LETTER TI;Lo;0;L;;;;;N;;;;; -3062;HIRAGANA LETTER DI;Lo;0;L;3061 3099;;;;N;;;;; -3063;HIRAGANA LETTER SMALL TU;Lo;0;L;;;;;N;;;;; -3064;HIRAGANA LETTER TU;Lo;0;L;;;;;N;;;;; -3065;HIRAGANA LETTER DU;Lo;0;L;3064 3099;;;;N;;;;; -3066;HIRAGANA LETTER TE;Lo;0;L;;;;;N;;;;; -3067;HIRAGANA LETTER DE;Lo;0;L;3066 3099;;;;N;;;;; -3068;HIRAGANA LETTER TO;Lo;0;L;;;;;N;;;;; -3069;HIRAGANA LETTER DO;Lo;0;L;3068 3099;;;;N;;;;; -306A;HIRAGANA LETTER NA;Lo;0;L;;;;;N;;;;; -306B;HIRAGANA LETTER NI;Lo;0;L;;;;;N;;;;; -306C;HIRAGANA LETTER NU;Lo;0;L;;;;;N;;;;; -306D;HIRAGANA LETTER NE;Lo;0;L;;;;;N;;;;; -306E;HIRAGANA LETTER NO;Lo;0;L;;;;;N;;;;; -306F;HIRAGANA LETTER HA;Lo;0;L;;;;;N;;;;; -3070;HIRAGANA LETTER BA;Lo;0;L;306F 3099;;;;N;;;;; -3071;HIRAGANA LETTER PA;Lo;0;L;306F 309A;;;;N;;;;; -3072;HIRAGANA LETTER HI;Lo;0;L;;;;;N;;;;; -3073;HIRAGANA LETTER BI;Lo;0;L;3072 3099;;;;N;;;;; -3074;HIRAGANA LETTER PI;Lo;0;L;3072 309A;;;;N;;;;; -3075;HIRAGANA LETTER HU;Lo;0;L;;;;;N;;;;; -3076;HIRAGANA LETTER BU;Lo;0;L;3075 3099;;;;N;;;;; -3077;HIRAGANA LETTER PU;Lo;0;L;3075 309A;;;;N;;;;; -3078;HIRAGANA LETTER HE;Lo;0;L;;;;;N;;;;; -3079;HIRAGANA LETTER BE;Lo;0;L;3078 3099;;;;N;;;;; -307A;HIRAGANA LETTER PE;Lo;0;L;3078 309A;;;;N;;;;; -307B;HIRAGANA LETTER HO;Lo;0;L;;;;;N;;;;; -307C;HIRAGANA LETTER BO;Lo;0;L;307B 3099;;;;N;;;;; -307D;HIRAGANA LETTER PO;Lo;0;L;307B 309A;;;;N;;;;; -307E;HIRAGANA LETTER MA;Lo;0;L;;;;;N;;;;; -307F;HIRAGANA LETTER MI;Lo;0;L;;;;;N;;;;; -3080;HIRAGANA LETTER MU;Lo;0;L;;;;;N;;;;; -3081;HIRAGANA LETTER ME;Lo;0;L;;;;;N;;;;; -3082;HIRAGANA LETTER MO;Lo;0;L;;;;;N;;;;; -3083;HIRAGANA LETTER SMALL YA;Lo;0;L;;;;;N;;;;; -3084;HIRAGANA LETTER YA;Lo;0;L;;;;;N;;;;; -3085;HIRAGANA LETTER SMALL YU;Lo;0;L;;;;;N;;;;; -3086;HIRAGANA LETTER YU;Lo;0;L;;;;;N;;;;; -3087;HIRAGANA LETTER SMALL YO;Lo;0;L;;;;;N;;;;; -3088;HIRAGANA LETTER YO;Lo;0;L;;;;;N;;;;; -3089;HIRAGANA LETTER RA;Lo;0;L;;;;;N;;;;; -308A;HIRAGANA LETTER RI;Lo;0;L;;;;;N;;;;; -308B;HIRAGANA LETTER RU;Lo;0;L;;;;;N;;;;; -308C;HIRAGANA LETTER RE;Lo;0;L;;;;;N;;;;; -308D;HIRAGANA LETTER RO;Lo;0;L;;;;;N;;;;; -308E;HIRAGANA LETTER SMALL WA;Lo;0;L;;;;;N;;;;; -308F;HIRAGANA LETTER WA;Lo;0;L;;;;;N;;;;; -3090;HIRAGANA LETTER WI;Lo;0;L;;;;;N;;;;; -3091;HIRAGANA LETTER WE;Lo;0;L;;;;;N;;;;; -3092;HIRAGANA LETTER WO;Lo;0;L;;;;;N;;;;; -3093;HIRAGANA LETTER N;Lo;0;L;;;;;N;;;;; -3094;HIRAGANA LETTER VU;Lo;0;L;3046 3099;;;;N;;;;; -3095;HIRAGANA LETTER SMALL KA;Lo;0;L;;;;;N;;;;; -3096;HIRAGANA LETTER SMALL KE;Lo;0;L;;;;;N;;;;; -3099;COMBINING KATAKANA-HIRAGANA VOICED SOUND MARK;Mn;8;NSM;;;;;N;NON-SPACING KATAKANA-HIRAGANA VOICED SOUND MARK;;;; -309A;COMBINING KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK;Mn;8;NSM;;;;;N;NON-SPACING KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK;;;; -309B;KATAKANA-HIRAGANA VOICED SOUND MARK;Sk;0;ON; 0020 3099;;;;N;;;;; -309C;KATAKANA-HIRAGANA SEMI-VOICED SOUND MARK;Sk;0;ON; 0020 309A;;;;N;;;;; -309D;HIRAGANA ITERATION MARK;Lm;0;L;;;;;N;;;;; -309E;HIRAGANA VOICED ITERATION MARK;Lm;0;L;309D 3099;;;;N;;;;; -309F;HIRAGANA DIGRAPH YORI;Lo;0;L; 3088 308A;;;;N;;;;; -30A0;KATAKANA-HIRAGANA DOUBLE HYPHEN;Pd;0;ON;;;;;N;;;;; -30A1;KATAKANA LETTER SMALL A;Lo;0;L;;;;;N;;;;; -30A2;KATAKANA LETTER A;Lo;0;L;;;;;N;;;;; -30A3;KATAKANA LETTER SMALL I;Lo;0;L;;;;;N;;;;; -30A4;KATAKANA LETTER I;Lo;0;L;;;;;N;;;;; -30A5;KATAKANA LETTER SMALL U;Lo;0;L;;;;;N;;;;; -30A6;KATAKANA LETTER U;Lo;0;L;;;;;N;;;;; -30A7;KATAKANA LETTER SMALL E;Lo;0;L;;;;;N;;;;; -30A8;KATAKANA LETTER E;Lo;0;L;;;;;N;;;;; -30A9;KATAKANA LETTER SMALL O;Lo;0;L;;;;;N;;;;; -30AA;KATAKANA LETTER O;Lo;0;L;;;;;N;;;;; -30AB;KATAKANA LETTER KA;Lo;0;L;;;;;N;;;;; -30AC;KATAKANA LETTER GA;Lo;0;L;30AB 3099;;;;N;;;;; -30AD;KATAKANA LETTER KI;Lo;0;L;;;;;N;;;;; -30AE;KATAKANA LETTER GI;Lo;0;L;30AD 3099;;;;N;;;;; -30AF;KATAKANA LETTER KU;Lo;0;L;;;;;N;;;;; -30B0;KATAKANA LETTER GU;Lo;0;L;30AF 3099;;;;N;;;;; -30B1;KATAKANA LETTER KE;Lo;0;L;;;;;N;;;;; -30B2;KATAKANA LETTER GE;Lo;0;L;30B1 3099;;;;N;;;;; -30B3;KATAKANA LETTER KO;Lo;0;L;;;;;N;;;;; -30B4;KATAKANA LETTER GO;Lo;0;L;30B3 3099;;;;N;;;;; -30B5;KATAKANA LETTER SA;Lo;0;L;;;;;N;;;;; -30B6;KATAKANA LETTER ZA;Lo;0;L;30B5 3099;;;;N;;;;; -30B7;KATAKANA LETTER SI;Lo;0;L;;;;;N;;;;; -30B8;KATAKANA LETTER ZI;Lo;0;L;30B7 3099;;;;N;;;;; -30B9;KATAKANA LETTER SU;Lo;0;L;;;;;N;;;;; -30BA;KATAKANA LETTER ZU;Lo;0;L;30B9 3099;;;;N;;;;; -30BB;KATAKANA LETTER SE;Lo;0;L;;;;;N;;;;; -30BC;KATAKANA LETTER ZE;Lo;0;L;30BB 3099;;;;N;;;;; -30BD;KATAKANA LETTER SO;Lo;0;L;;;;;N;;;;; -30BE;KATAKANA LETTER ZO;Lo;0;L;30BD 3099;;;;N;;;;; -30BF;KATAKANA LETTER TA;Lo;0;L;;;;;N;;;;; -30C0;KATAKANA LETTER DA;Lo;0;L;30BF 3099;;;;N;;;;; -30C1;KATAKANA LETTER TI;Lo;0;L;;;;;N;;;;; -30C2;KATAKANA LETTER DI;Lo;0;L;30C1 3099;;;;N;;;;; -30C3;KATAKANA LETTER SMALL TU;Lo;0;L;;;;;N;;;;; -30C4;KATAKANA LETTER TU;Lo;0;L;;;;;N;;;;; -30C5;KATAKANA LETTER DU;Lo;0;L;30C4 3099;;;;N;;;;; -30C6;KATAKANA LETTER TE;Lo;0;L;;;;;N;;;;; -30C7;KATAKANA LETTER DE;Lo;0;L;30C6 3099;;;;N;;;;; -30C8;KATAKANA LETTER TO;Lo;0;L;;;;;N;;;;; -30C9;KATAKANA LETTER DO;Lo;0;L;30C8 3099;;;;N;;;;; -30CA;KATAKANA LETTER NA;Lo;0;L;;;;;N;;;;; -30CB;KATAKANA LETTER NI;Lo;0;L;;;;;N;;;;; -30CC;KATAKANA LETTER NU;Lo;0;L;;;;;N;;;;; -30CD;KATAKANA LETTER NE;Lo;0;L;;;;;N;;;;; -30CE;KATAKANA LETTER NO;Lo;0;L;;;;;N;;;;; -30CF;KATAKANA LETTER HA;Lo;0;L;;;;;N;;;;; -30D0;KATAKANA LETTER BA;Lo;0;L;30CF 3099;;;;N;;;;; -30D1;KATAKANA LETTER PA;Lo;0;L;30CF 309A;;;;N;;;;; -30D2;KATAKANA LETTER HI;Lo;0;L;;;;;N;;;;; -30D3;KATAKANA LETTER BI;Lo;0;L;30D2 3099;;;;N;;;;; -30D4;KATAKANA LETTER PI;Lo;0;L;30D2 309A;;;;N;;;;; -30D5;KATAKANA LETTER HU;Lo;0;L;;;;;N;;;;; -30D6;KATAKANA LETTER BU;Lo;0;L;30D5 3099;;;;N;;;;; -30D7;KATAKANA LETTER PU;Lo;0;L;30D5 309A;;;;N;;;;; -30D8;KATAKANA LETTER HE;Lo;0;L;;;;;N;;;;; -30D9;KATAKANA LETTER BE;Lo;0;L;30D8 3099;;;;N;;;;; -30DA;KATAKANA LETTER PE;Lo;0;L;30D8 309A;;;;N;;;;; -30DB;KATAKANA LETTER HO;Lo;0;L;;;;;N;;;;; -30DC;KATAKANA LETTER BO;Lo;0;L;30DB 3099;;;;N;;;;; -30DD;KATAKANA LETTER PO;Lo;0;L;30DB 309A;;;;N;;;;; -30DE;KATAKANA LETTER MA;Lo;0;L;;;;;N;;;;; -30DF;KATAKANA LETTER MI;Lo;0;L;;;;;N;;;;; -30E0;KATAKANA LETTER MU;Lo;0;L;;;;;N;;;;; -30E1;KATAKANA LETTER ME;Lo;0;L;;;;;N;;;;; -30E2;KATAKANA LETTER MO;Lo;0;L;;;;;N;;;;; -30E3;KATAKANA LETTER SMALL YA;Lo;0;L;;;;;N;;;;; -30E4;KATAKANA LETTER YA;Lo;0;L;;;;;N;;;;; -30E5;KATAKANA LETTER SMALL YU;Lo;0;L;;;;;N;;;;; -30E6;KATAKANA LETTER YU;Lo;0;L;;;;;N;;;;; -30E7;KATAKANA LETTER SMALL YO;Lo;0;L;;;;;N;;;;; -30E8;KATAKANA LETTER YO;Lo;0;L;;;;;N;;;;; -30E9;KATAKANA LETTER RA;Lo;0;L;;;;;N;;;;; -30EA;KATAKANA LETTER RI;Lo;0;L;;;;;N;;;;; -30EB;KATAKANA LETTER RU;Lo;0;L;;;;;N;;;;; -30EC;KATAKANA LETTER RE;Lo;0;L;;;;;N;;;;; -30ED;KATAKANA LETTER RO;Lo;0;L;;;;;N;;;;; -30EE;KATAKANA LETTER SMALL WA;Lo;0;L;;;;;N;;;;; -30EF;KATAKANA LETTER WA;Lo;0;L;;;;;N;;;;; -30F0;KATAKANA LETTER WI;Lo;0;L;;;;;N;;;;; -30F1;KATAKANA LETTER WE;Lo;0;L;;;;;N;;;;; -30F2;KATAKANA LETTER WO;Lo;0;L;;;;;N;;;;; -30F3;KATAKANA LETTER N;Lo;0;L;;;;;N;;;;; -30F4;KATAKANA LETTER VU;Lo;0;L;30A6 3099;;;;N;;;;; -30F5;KATAKANA LETTER SMALL KA;Lo;0;L;;;;;N;;;;; -30F6;KATAKANA LETTER SMALL KE;Lo;0;L;;;;;N;;;;; -30F7;KATAKANA LETTER VA;Lo;0;L;30EF 3099;;;;N;;;;; -30F8;KATAKANA LETTER VI;Lo;0;L;30F0 3099;;;;N;;;;; -30F9;KATAKANA LETTER VE;Lo;0;L;30F1 3099;;;;N;;;;; -30FA;KATAKANA LETTER VO;Lo;0;L;30F2 3099;;;;N;;;;; -30FB;KATAKANA MIDDLE DOT;Po;0;ON;;;;;N;;;;; -30FC;KATAKANA-HIRAGANA PROLONGED SOUND MARK;Lm;0;L;;;;;N;;;;; -30FD;KATAKANA ITERATION MARK;Lm;0;L;;;;;N;;;;; -30FE;KATAKANA VOICED ITERATION MARK;Lm;0;L;30FD 3099;;;;N;;;;; -30FF;KATAKANA DIGRAPH KOTO;Lo;0;L; 30B3 30C8;;;;N;;;;; -3105;BOPOMOFO LETTER B;Lo;0;L;;;;;N;;;;; -3106;BOPOMOFO LETTER P;Lo;0;L;;;;;N;;;;; -3107;BOPOMOFO LETTER M;Lo;0;L;;;;;N;;;;; -3108;BOPOMOFO LETTER F;Lo;0;L;;;;;N;;;;; -3109;BOPOMOFO LETTER D;Lo;0;L;;;;;N;;;;; -310A;BOPOMOFO LETTER T;Lo;0;L;;;;;N;;;;; -310B;BOPOMOFO LETTER N;Lo;0;L;;;;;N;;;;; -310C;BOPOMOFO LETTER L;Lo;0;L;;;;;N;;;;; -310D;BOPOMOFO LETTER G;Lo;0;L;;;;;N;;;;; -310E;BOPOMOFO LETTER K;Lo;0;L;;;;;N;;;;; -310F;BOPOMOFO LETTER H;Lo;0;L;;;;;N;;;;; -3110;BOPOMOFO LETTER J;Lo;0;L;;;;;N;;;;; -3111;BOPOMOFO LETTER Q;Lo;0;L;;;;;N;;;;; -3112;BOPOMOFO LETTER X;Lo;0;L;;;;;N;;;;; -3113;BOPOMOFO LETTER ZH;Lo;0;L;;;;;N;;;;; -3114;BOPOMOFO LETTER CH;Lo;0;L;;;;;N;;;;; -3115;BOPOMOFO LETTER SH;Lo;0;L;;;;;N;;;;; -3116;BOPOMOFO LETTER R;Lo;0;L;;;;;N;;;;; -3117;BOPOMOFO LETTER Z;Lo;0;L;;;;;N;;;;; -3118;BOPOMOFO LETTER C;Lo;0;L;;;;;N;;;;; -3119;BOPOMOFO LETTER S;Lo;0;L;;;;;N;;;;; -311A;BOPOMOFO LETTER A;Lo;0;L;;;;;N;;;;; -311B;BOPOMOFO LETTER O;Lo;0;L;;;;;N;;;;; -311C;BOPOMOFO LETTER E;Lo;0;L;;;;;N;;;;; -311D;BOPOMOFO LETTER EH;Lo;0;L;;;;;N;;;;; -311E;BOPOMOFO LETTER AI;Lo;0;L;;;;;N;;;;; -311F;BOPOMOFO LETTER EI;Lo;0;L;;;;;N;;;;; -3120;BOPOMOFO LETTER AU;Lo;0;L;;;;;N;;;;; -3121;BOPOMOFO LETTER OU;Lo;0;L;;;;;N;;;;; -3122;BOPOMOFO LETTER AN;Lo;0;L;;;;;N;;;;; -3123;BOPOMOFO LETTER EN;Lo;0;L;;;;;N;;;;; -3124;BOPOMOFO LETTER ANG;Lo;0;L;;;;;N;;;;; -3125;BOPOMOFO LETTER ENG;Lo;0;L;;;;;N;;;;; -3126;BOPOMOFO LETTER ER;Lo;0;L;;;;;N;;;;; -3127;BOPOMOFO LETTER I;Lo;0;L;;;;;N;;;;; -3128;BOPOMOFO LETTER U;Lo;0;L;;;;;N;;;;; -3129;BOPOMOFO LETTER IU;Lo;0;L;;;;;N;;;;; -312A;BOPOMOFO LETTER V;Lo;0;L;;;;;N;;;;; -312B;BOPOMOFO LETTER NG;Lo;0;L;;;;;N;;;;; -312C;BOPOMOFO LETTER GN;Lo;0;L;;;;;N;;;;; -312D;BOPOMOFO LETTER IH;Lo;0;L;;;;;N;;;;; -3131;HANGUL LETTER KIYEOK;Lo;0;L; 1100;;;;N;HANGUL LETTER GIYEOG;;;; -3132;HANGUL LETTER SSANGKIYEOK;Lo;0;L; 1101;;;;N;HANGUL LETTER SSANG GIYEOG;;;; -3133;HANGUL LETTER KIYEOK-SIOS;Lo;0;L; 11AA;;;;N;HANGUL LETTER GIYEOG SIOS;;;; -3134;HANGUL LETTER NIEUN;Lo;0;L; 1102;;;;N;;;;; -3135;HANGUL LETTER NIEUN-CIEUC;Lo;0;L; 11AC;;;;N;HANGUL LETTER NIEUN JIEUJ;;;; -3136;HANGUL LETTER NIEUN-HIEUH;Lo;0;L; 11AD;;;;N;HANGUL LETTER NIEUN HIEUH;;;; -3137;HANGUL LETTER TIKEUT;Lo;0;L; 1103;;;;N;HANGUL LETTER DIGEUD;;;; -3138;HANGUL LETTER SSANGTIKEUT;Lo;0;L; 1104;;;;N;HANGUL LETTER SSANG DIGEUD;;;; -3139;HANGUL LETTER RIEUL;Lo;0;L; 1105;;;;N;HANGUL LETTER LIEUL;;;; -313A;HANGUL LETTER RIEUL-KIYEOK;Lo;0;L; 11B0;;;;N;HANGUL LETTER LIEUL GIYEOG;;;; -313B;HANGUL LETTER RIEUL-MIEUM;Lo;0;L; 11B1;;;;N;HANGUL LETTER LIEUL MIEUM;;;; -313C;HANGUL LETTER RIEUL-PIEUP;Lo;0;L; 11B2;;;;N;HANGUL LETTER LIEUL BIEUB;;;; -313D;HANGUL LETTER RIEUL-SIOS;Lo;0;L; 11B3;;;;N;HANGUL LETTER LIEUL SIOS;;;; -313E;HANGUL LETTER RIEUL-THIEUTH;Lo;0;L; 11B4;;;;N;HANGUL LETTER LIEUL TIEUT;;;; -313F;HANGUL LETTER RIEUL-PHIEUPH;Lo;0;L; 11B5;;;;N;HANGUL LETTER LIEUL PIEUP;;;; -3140;HANGUL LETTER RIEUL-HIEUH;Lo;0;L; 111A;;;;N;HANGUL LETTER LIEUL HIEUH;;;; -3141;HANGUL LETTER MIEUM;Lo;0;L; 1106;;;;N;;;;; -3142;HANGUL LETTER PIEUP;Lo;0;L; 1107;;;;N;HANGUL LETTER BIEUB;;;; -3143;HANGUL LETTER SSANGPIEUP;Lo;0;L; 1108;;;;N;HANGUL LETTER SSANG BIEUB;;;; -3144;HANGUL LETTER PIEUP-SIOS;Lo;0;L; 1121;;;;N;HANGUL LETTER BIEUB SIOS;;;; -3145;HANGUL LETTER SIOS;Lo;0;L; 1109;;;;N;;;;; -3146;HANGUL LETTER SSANGSIOS;Lo;0;L; 110A;;;;N;HANGUL LETTER SSANG SIOS;;;; -3147;HANGUL LETTER IEUNG;Lo;0;L; 110B;;;;N;;;;; -3148;HANGUL LETTER CIEUC;Lo;0;L; 110C;;;;N;HANGUL LETTER JIEUJ;;;; -3149;HANGUL LETTER SSANGCIEUC;Lo;0;L; 110D;;;;N;HANGUL LETTER SSANG JIEUJ;;;; -314A;HANGUL LETTER CHIEUCH;Lo;0;L; 110E;;;;N;HANGUL LETTER CIEUC;;;; -314B;HANGUL LETTER KHIEUKH;Lo;0;L; 110F;;;;N;HANGUL LETTER KIYEOK;;;; -314C;HANGUL LETTER THIEUTH;Lo;0;L; 1110;;;;N;HANGUL LETTER TIEUT;;;; -314D;HANGUL LETTER PHIEUPH;Lo;0;L; 1111;;;;N;HANGUL LETTER PIEUP;;;; -314E;HANGUL LETTER HIEUH;Lo;0;L; 1112;;;;N;;;;; -314F;HANGUL LETTER A;Lo;0;L; 1161;;;;N;;;;; -3150;HANGUL LETTER AE;Lo;0;L; 1162;;;;N;;;;; -3151;HANGUL LETTER YA;Lo;0;L; 1163;;;;N;;;;; -3152;HANGUL LETTER YAE;Lo;0;L; 1164;;;;N;;;;; -3153;HANGUL LETTER EO;Lo;0;L; 1165;;;;N;;;;; -3154;HANGUL LETTER E;Lo;0;L; 1166;;;;N;;;;; -3155;HANGUL LETTER YEO;Lo;0;L; 1167;;;;N;;;;; -3156;HANGUL LETTER YE;Lo;0;L; 1168;;;;N;;;;; -3157;HANGUL LETTER O;Lo;0;L; 1169;;;;N;;;;; -3158;HANGUL LETTER WA;Lo;0;L; 116A;;;;N;;;;; -3159;HANGUL LETTER WAE;Lo;0;L; 116B;;;;N;;;;; -315A;HANGUL LETTER OE;Lo;0;L; 116C;;;;N;;;;; -315B;HANGUL LETTER YO;Lo;0;L; 116D;;;;N;;;;; -315C;HANGUL LETTER U;Lo;0;L; 116E;;;;N;;;;; -315D;HANGUL LETTER WEO;Lo;0;L; 116F;;;;N;;;;; -315E;HANGUL LETTER WE;Lo;0;L; 1170;;;;N;;;;; -315F;HANGUL LETTER WI;Lo;0;L; 1171;;;;N;;;;; -3160;HANGUL LETTER YU;Lo;0;L; 1172;;;;N;;;;; -3161;HANGUL LETTER EU;Lo;0;L; 1173;;;;N;;;;; -3162;HANGUL LETTER YI;Lo;0;L; 1174;;;;N;;;;; -3163;HANGUL LETTER I;Lo;0;L; 1175;;;;N;;;;; -3164;HANGUL FILLER;Lo;0;L; 1160;;;;N;HANGUL CAE OM;;;; -3165;HANGUL LETTER SSANGNIEUN;Lo;0;L; 1114;;;;N;HANGUL LETTER SSANG NIEUN;;;; -3166;HANGUL LETTER NIEUN-TIKEUT;Lo;0;L; 1115;;;;N;HANGUL LETTER NIEUN DIGEUD;;;; -3167;HANGUL LETTER NIEUN-SIOS;Lo;0;L; 11C7;;;;N;HANGUL LETTER NIEUN SIOS;;;; -3168;HANGUL LETTER NIEUN-PANSIOS;Lo;0;L; 11C8;;;;N;HANGUL LETTER NIEUN BAN CHI EUM;;;; -3169;HANGUL LETTER RIEUL-KIYEOK-SIOS;Lo;0;L; 11CC;;;;N;HANGUL LETTER LIEUL GIYEOG SIOS;;;; -316A;HANGUL LETTER RIEUL-TIKEUT;Lo;0;L; 11CE;;;;N;HANGUL LETTER LIEUL DIGEUD;;;; -316B;HANGUL LETTER RIEUL-PIEUP-SIOS;Lo;0;L; 11D3;;;;N;HANGUL LETTER LIEUL BIEUB SIOS;;;; -316C;HANGUL LETTER RIEUL-PANSIOS;Lo;0;L; 11D7;;;;N;HANGUL LETTER LIEUL BAN CHI EUM;;;; -316D;HANGUL LETTER RIEUL-YEORINHIEUH;Lo;0;L; 11D9;;;;N;HANGUL LETTER LIEUL YEOLIN HIEUH;;;; -316E;HANGUL LETTER MIEUM-PIEUP;Lo;0;L; 111C;;;;N;HANGUL LETTER MIEUM BIEUB;;;; -316F;HANGUL LETTER MIEUM-SIOS;Lo;0;L; 11DD;;;;N;HANGUL LETTER MIEUM SIOS;;;; -3170;HANGUL LETTER MIEUM-PANSIOS;Lo;0;L; 11DF;;;;N;HANGUL LETTER BIEUB BAN CHI EUM;;;; -3171;HANGUL LETTER KAPYEOUNMIEUM;Lo;0;L; 111D;;;;N;HANGUL LETTER MIEUM SUN GYEONG EUM;;;; -3172;HANGUL LETTER PIEUP-KIYEOK;Lo;0;L; 111E;;;;N;HANGUL LETTER BIEUB GIYEOG;;;; -3173;HANGUL LETTER PIEUP-TIKEUT;Lo;0;L; 1120;;;;N;HANGUL LETTER BIEUB DIGEUD;;;; -3174;HANGUL LETTER PIEUP-SIOS-KIYEOK;Lo;0;L; 1122;;;;N;HANGUL LETTER BIEUB SIOS GIYEOG;;;; -3175;HANGUL LETTER PIEUP-SIOS-TIKEUT;Lo;0;L; 1123;;;;N;HANGUL LETTER BIEUB SIOS DIGEUD;;;; -3176;HANGUL LETTER PIEUP-CIEUC;Lo;0;L; 1127;;;;N;HANGUL LETTER BIEUB JIEUJ;;;; -3177;HANGUL LETTER PIEUP-THIEUTH;Lo;0;L; 1129;;;;N;HANGUL LETTER BIEUB TIEUT;;;; -3178;HANGUL LETTER KAPYEOUNPIEUP;Lo;0;L; 112B;;;;N;HANGUL LETTER BIEUB SUN GYEONG EUM;;;; -3179;HANGUL LETTER KAPYEOUNSSANGPIEUP;Lo;0;L; 112C;;;;N;HANGUL LETTER SSANG BIEUB SUN GYEONG EUM;;;; -317A;HANGUL LETTER SIOS-KIYEOK;Lo;0;L; 112D;;;;N;HANGUL LETTER SIOS GIYEOG;;;; -317B;HANGUL LETTER SIOS-NIEUN;Lo;0;L; 112E;;;;N;HANGUL LETTER SIOS NIEUN;;;; -317C;HANGUL LETTER SIOS-TIKEUT;Lo;0;L; 112F;;;;N;HANGUL LETTER SIOS DIGEUD;;;; -317D;HANGUL LETTER SIOS-PIEUP;Lo;0;L; 1132;;;;N;HANGUL LETTER SIOS BIEUB;;;; -317E;HANGUL LETTER SIOS-CIEUC;Lo;0;L; 1136;;;;N;HANGUL LETTER SIOS JIEUJ;;;; -317F;HANGUL LETTER PANSIOS;Lo;0;L; 1140;;;;N;HANGUL LETTER BAN CHI EUM;;;; -3180;HANGUL LETTER SSANGIEUNG;Lo;0;L; 1147;;;;N;HANGUL LETTER SSANG IEUNG;;;; -3181;HANGUL LETTER YESIEUNG;Lo;0;L; 114C;;;;N;HANGUL LETTER NGIEUNG;;;; -3182;HANGUL LETTER YESIEUNG-SIOS;Lo;0;L; 11F1;;;;N;HANGUL LETTER NGIEUNG SIOS;;;; -3183;HANGUL LETTER YESIEUNG-PANSIOS;Lo;0;L; 11F2;;;;N;HANGUL LETTER NGIEUNG BAN CHI EUM;;;; -3184;HANGUL LETTER KAPYEOUNPHIEUPH;Lo;0;L; 1157;;;;N;HANGUL LETTER PIEUP SUN GYEONG EUM;;;; -3185;HANGUL LETTER SSANGHIEUH;Lo;0;L; 1158;;;;N;HANGUL LETTER SSANG HIEUH;;;; -3186;HANGUL LETTER YEORINHIEUH;Lo;0;L; 1159;;;;N;HANGUL LETTER YEOLIN HIEUH;;;; -3187;HANGUL LETTER YO-YA;Lo;0;L; 1184;;;;N;HANGUL LETTER YOYA;;;; -3188;HANGUL LETTER YO-YAE;Lo;0;L; 1185;;;;N;HANGUL LETTER YOYAE;;;; -3189;HANGUL LETTER YO-I;Lo;0;L; 1188;;;;N;HANGUL LETTER YOI;;;; -318A;HANGUL LETTER YU-YEO;Lo;0;L; 1191;;;;N;HANGUL LETTER YUYEO;;;; -318B;HANGUL LETTER YU-YE;Lo;0;L; 1192;;;;N;HANGUL LETTER YUYE;;;; -318C;HANGUL LETTER YU-I;Lo;0;L; 1194;;;;N;HANGUL LETTER YUI;;;; -318D;HANGUL LETTER ARAEA;Lo;0;L; 119E;;;;N;HANGUL LETTER ALAE A;;;; -318E;HANGUL LETTER ARAEAE;Lo;0;L; 11A1;;;;N;HANGUL LETTER ALAE AE;;;; -3190;IDEOGRAPHIC ANNOTATION LINKING MARK;So;0;L;;;;;N;KANBUN TATETEN;Kanbun Tateten;;; -3191;IDEOGRAPHIC ANNOTATION REVERSE MARK;So;0;L;;;;;N;KAERITEN RE;Kaeriten;;; -3192;IDEOGRAPHIC ANNOTATION ONE MARK;No;0;L; 4E00;;;1;N;KAERITEN ITI;Kaeriten;;; -3193;IDEOGRAPHIC ANNOTATION TWO MARK;No;0;L; 4E8C;;;2;N;KAERITEN NI;Kaeriten;;; -3194;IDEOGRAPHIC ANNOTATION THREE MARK;No;0;L; 4E09;;;3;N;KAERITEN SAN;Kaeriten;;; -3195;IDEOGRAPHIC ANNOTATION FOUR MARK;No;0;L; 56DB;;;4;N;KAERITEN SI;Kaeriten;;; -3196;IDEOGRAPHIC ANNOTATION TOP MARK;So;0;L; 4E0A;;;;N;KAERITEN ZYOU;Kaeriten;;; -3197;IDEOGRAPHIC ANNOTATION MIDDLE MARK;So;0;L; 4E2D;;;;N;KAERITEN TYUU;Kaeriten;;; -3198;IDEOGRAPHIC ANNOTATION BOTTOM MARK;So;0;L; 4E0B;;;;N;KAERITEN GE;Kaeriten;;; -3199;IDEOGRAPHIC ANNOTATION FIRST MARK;So;0;L; 7532;;;;N;KAERITEN KOU;Kaeriten;;; -319A;IDEOGRAPHIC ANNOTATION SECOND MARK;So;0;L; 4E59;;;;N;KAERITEN OTU;Kaeriten;;; -319B;IDEOGRAPHIC ANNOTATION THIRD MARK;So;0;L; 4E19;;;;N;KAERITEN HEI;Kaeriten;;; -319C;IDEOGRAPHIC ANNOTATION FOURTH MARK;So;0;L; 4E01;;;;N;KAERITEN TEI;Kaeriten;;; -319D;IDEOGRAPHIC ANNOTATION HEAVEN MARK;So;0;L; 5929;;;;N;KAERITEN TEN;Kaeriten;;; -319E;IDEOGRAPHIC ANNOTATION EARTH MARK;So;0;L; 5730;;;;N;KAERITEN TI;Kaeriten;;; -319F;IDEOGRAPHIC ANNOTATION MAN MARK;So;0;L; 4EBA;;;;N;KAERITEN ZIN;Kaeriten;;; -31A0;BOPOMOFO LETTER BU;Lo;0;L;;;;;N;;;;; -31A1;BOPOMOFO LETTER ZI;Lo;0;L;;;;;N;;;;; -31A2;BOPOMOFO LETTER JI;Lo;0;L;;;;;N;;;;; -31A3;BOPOMOFO LETTER GU;Lo;0;L;;;;;N;;;;; -31A4;BOPOMOFO LETTER EE;Lo;0;L;;;;;N;;;;; -31A5;BOPOMOFO LETTER ENN;Lo;0;L;;;;;N;;;;; -31A6;BOPOMOFO LETTER OO;Lo;0;L;;;;;N;;;;; -31A7;BOPOMOFO LETTER ONN;Lo;0;L;;;;;N;;;;; -31A8;BOPOMOFO LETTER IR;Lo;0;L;;;;;N;;;;; -31A9;BOPOMOFO LETTER ANN;Lo;0;L;;;;;N;;;;; -31AA;BOPOMOFO LETTER INN;Lo;0;L;;;;;N;;;;; -31AB;BOPOMOFO LETTER UNN;Lo;0;L;;;;;N;;;;; -31AC;BOPOMOFO LETTER IM;Lo;0;L;;;;;N;;;;; -31AD;BOPOMOFO LETTER NGG;Lo;0;L;;;;;N;;;;; -31AE;BOPOMOFO LETTER AINN;Lo;0;L;;;;;N;;;;; -31AF;BOPOMOFO LETTER AUNN;Lo;0;L;;;;;N;;;;; -31B0;BOPOMOFO LETTER AM;Lo;0;L;;;;;N;;;;; -31B1;BOPOMOFO LETTER OM;Lo;0;L;;;;;N;;;;; -31B2;BOPOMOFO LETTER ONG;Lo;0;L;;;;;N;;;;; -31B3;BOPOMOFO LETTER INNN;Lo;0;L;;;;;N;;;;; -31B4;BOPOMOFO FINAL LETTER P;Lo;0;L;;;;;N;;;;; -31B5;BOPOMOFO FINAL LETTER T;Lo;0;L;;;;;N;;;;; -31B6;BOPOMOFO FINAL LETTER K;Lo;0;L;;;;;N;;;;; -31B7;BOPOMOFO FINAL LETTER H;Lo;0;L;;;;;N;;;;; -31C0;CJK STROKE T;So;0;ON;;;;;N;;;;; -31C1;CJK STROKE WG;So;0;ON;;;;;N;;;;; -31C2;CJK STROKE XG;So;0;ON;;;;;N;;;;; -31C3;CJK STROKE BXG;So;0;ON;;;;;N;;;;; -31C4;CJK STROKE SW;So;0;ON;;;;;N;;;;; -31C5;CJK STROKE HZZ;So;0;ON;;;;;N;;;;; -31C6;CJK STROKE HZG;So;0;ON;;;;;N;;;;; -31C7;CJK STROKE HP;So;0;ON;;;;;N;;;;; -31C8;CJK STROKE HZWG;So;0;ON;;;;;N;;;;; -31C9;CJK STROKE SZWG;So;0;ON;;;;;N;;;;; -31CA;CJK STROKE HZT;So;0;ON;;;;;N;;;;; -31CB;CJK STROKE HZZP;So;0;ON;;;;;N;;;;; -31CC;CJK STROKE HPWG;So;0;ON;;;;;N;;;;; -31CD;CJK STROKE HZW;So;0;ON;;;;;N;;;;; -31CE;CJK STROKE HZZZ;So;0;ON;;;;;N;;;;; -31CF;CJK STROKE N;So;0;ON;;;;;N;;;;; -31D0;CJK STROKE H;So;0;ON;;;;;N;;;;; -31D1;CJK STROKE S;So;0;ON;;;;;N;;;;; -31D2;CJK STROKE P;So;0;ON;;;;;N;;;;; -31D3;CJK STROKE SP;So;0;ON;;;;;N;;;;; -31D4;CJK STROKE D;So;0;ON;;;;;N;;;;; -31D5;CJK STROKE HZ;So;0;ON;;;;;N;;;;; -31D6;CJK STROKE HG;So;0;ON;;;;;N;;;;; -31D7;CJK STROKE SZ;So;0;ON;;;;;N;;;;; -31D8;CJK STROKE SWZ;So;0;ON;;;;;N;;;;; -31D9;CJK STROKE ST;So;0;ON;;;;;N;;;;; -31DA;CJK STROKE SG;So;0;ON;;;;;N;;;;; -31DB;CJK STROKE PD;So;0;ON;;;;;N;;;;; -31DC;CJK STROKE PZ;So;0;ON;;;;;N;;;;; -31DD;CJK STROKE TN;So;0;ON;;;;;N;;;;; -31DE;CJK STROKE SZZ;So;0;ON;;;;;N;;;;; -31DF;CJK STROKE SWG;So;0;ON;;;;;N;;;;; -31E0;CJK STROKE HXWG;So;0;ON;;;;;N;;;;; -31E1;CJK STROKE HZZZG;So;0;ON;;;;;N;;;;; -31E2;CJK STROKE PG;So;0;ON;;;;;N;;;;; -31E3;CJK STROKE Q;So;0;ON;;;;;N;;;;; -31F0;KATAKANA LETTER SMALL KU;Lo;0;L;;;;;N;;;;; -31F1;KATAKANA LETTER SMALL SI;Lo;0;L;;;;;N;;;;; -31F2;KATAKANA LETTER SMALL SU;Lo;0;L;;;;;N;;;;; -31F3;KATAKANA LETTER SMALL TO;Lo;0;L;;;;;N;;;;; -31F4;KATAKANA LETTER SMALL NU;Lo;0;L;;;;;N;;;;; -31F5;KATAKANA LETTER SMALL HA;Lo;0;L;;;;;N;;;;; -31F6;KATAKANA LETTER SMALL HI;Lo;0;L;;;;;N;;;;; -31F7;KATAKANA LETTER SMALL HU;Lo;0;L;;;;;N;;;;; -31F8;KATAKANA LETTER SMALL HE;Lo;0;L;;;;;N;;;;; -31F9;KATAKANA LETTER SMALL HO;Lo;0;L;;;;;N;;;;; -31FA;KATAKANA LETTER SMALL MU;Lo;0;L;;;;;N;;;;; -31FB;KATAKANA LETTER SMALL RA;Lo;0;L;;;;;N;;;;; -31FC;KATAKANA LETTER SMALL RI;Lo;0;L;;;;;N;;;;; -31FD;KATAKANA LETTER SMALL RU;Lo;0;L;;;;;N;;;;; -31FE;KATAKANA LETTER SMALL RE;Lo;0;L;;;;;N;;;;; -31FF;KATAKANA LETTER SMALL RO;Lo;0;L;;;;;N;;;;; -3200;PARENTHESIZED HANGUL KIYEOK;So;0;L; 0028 1100 0029;;;;N;PARENTHESIZED HANGUL GIYEOG;;;; -3201;PARENTHESIZED HANGUL NIEUN;So;0;L; 0028 1102 0029;;;;N;;;;; -3202;PARENTHESIZED HANGUL TIKEUT;So;0;L; 0028 1103 0029;;;;N;PARENTHESIZED HANGUL DIGEUD;;;; -3203;PARENTHESIZED HANGUL RIEUL;So;0;L; 0028 1105 0029;;;;N;PARENTHESIZED HANGUL LIEUL;;;; -3204;PARENTHESIZED HANGUL MIEUM;So;0;L; 0028 1106 0029;;;;N;;;;; -3205;PARENTHESIZED HANGUL PIEUP;So;0;L; 0028 1107 0029;;;;N;PARENTHESIZED HANGUL BIEUB;;;; -3206;PARENTHESIZED HANGUL SIOS;So;0;L; 0028 1109 0029;;;;N;;;;; -3207;PARENTHESIZED HANGUL IEUNG;So;0;L; 0028 110B 0029;;;;N;;;;; -3208;PARENTHESIZED HANGUL CIEUC;So;0;L; 0028 110C 0029;;;;N;PARENTHESIZED HANGUL JIEUJ;;;; -3209;PARENTHESIZED HANGUL CHIEUCH;So;0;L; 0028 110E 0029;;;;N;PARENTHESIZED HANGUL CIEUC;;;; -320A;PARENTHESIZED HANGUL KHIEUKH;So;0;L; 0028 110F 0029;;;;N;PARENTHESIZED HANGUL KIYEOK;;;; -320B;PARENTHESIZED HANGUL THIEUTH;So;0;L; 0028 1110 0029;;;;N;PARENTHESIZED HANGUL TIEUT;;;; -320C;PARENTHESIZED HANGUL PHIEUPH;So;0;L; 0028 1111 0029;;;;N;PARENTHESIZED HANGUL PIEUP;;;; -320D;PARENTHESIZED HANGUL HIEUH;So;0;L; 0028 1112 0029;;;;N;;;;; -320E;PARENTHESIZED HANGUL KIYEOK A;So;0;L; 0028 1100 1161 0029;;;;N;PARENTHESIZED HANGUL GA;;;; -320F;PARENTHESIZED HANGUL NIEUN A;So;0;L; 0028 1102 1161 0029;;;;N;PARENTHESIZED HANGUL NA;;;; -3210;PARENTHESIZED HANGUL TIKEUT A;So;0;L; 0028 1103 1161 0029;;;;N;PARENTHESIZED HANGUL DA;;;; -3211;PARENTHESIZED HANGUL RIEUL A;So;0;L; 0028 1105 1161 0029;;;;N;PARENTHESIZED HANGUL LA;;;; -3212;PARENTHESIZED HANGUL MIEUM A;So;0;L; 0028 1106 1161 0029;;;;N;PARENTHESIZED HANGUL MA;;;; -3213;PARENTHESIZED HANGUL PIEUP A;So;0;L; 0028 1107 1161 0029;;;;N;PARENTHESIZED HANGUL BA;;;; -3214;PARENTHESIZED HANGUL SIOS A;So;0;L; 0028 1109 1161 0029;;;;N;PARENTHESIZED HANGUL SA;;;; -3215;PARENTHESIZED HANGUL IEUNG A;So;0;L; 0028 110B 1161 0029;;;;N;PARENTHESIZED HANGUL A;;;; -3216;PARENTHESIZED HANGUL CIEUC A;So;0;L; 0028 110C 1161 0029;;;;N;PARENTHESIZED HANGUL JA;;;; -3217;PARENTHESIZED HANGUL CHIEUCH A;So;0;L; 0028 110E 1161 0029;;;;N;PARENTHESIZED HANGUL CA;;;; -3218;PARENTHESIZED HANGUL KHIEUKH A;So;0;L; 0028 110F 1161 0029;;;;N;PARENTHESIZED HANGUL KA;;;; -3219;PARENTHESIZED HANGUL THIEUTH A;So;0;L; 0028 1110 1161 0029;;;;N;PARENTHESIZED HANGUL TA;;;; -321A;PARENTHESIZED HANGUL PHIEUPH A;So;0;L; 0028 1111 1161 0029;;;;N;PARENTHESIZED HANGUL PA;;;; -321B;PARENTHESIZED HANGUL HIEUH A;So;0;L; 0028 1112 1161 0029;;;;N;PARENTHESIZED HANGUL HA;;;; -321C;PARENTHESIZED HANGUL CIEUC U;So;0;L; 0028 110C 116E 0029;;;;N;PARENTHESIZED HANGUL JU;;;; -321D;PARENTHESIZED KOREAN CHARACTER OJEON;So;0;ON; 0028 110B 1169 110C 1165 11AB 0029;;;;N;;;;; -321E;PARENTHESIZED KOREAN CHARACTER O HU;So;0;ON; 0028 110B 1169 1112 116E 0029;;;;N;;;;; -3220;PARENTHESIZED IDEOGRAPH ONE;No;0;L; 0028 4E00 0029;;;1;N;;;;; -3221;PARENTHESIZED IDEOGRAPH TWO;No;0;L; 0028 4E8C 0029;;;2;N;;;;; -3222;PARENTHESIZED IDEOGRAPH THREE;No;0;L; 0028 4E09 0029;;;3;N;;;;; -3223;PARENTHESIZED IDEOGRAPH FOUR;No;0;L; 0028 56DB 0029;;;4;N;;;;; -3224;PARENTHESIZED IDEOGRAPH FIVE;No;0;L; 0028 4E94 0029;;;5;N;;;;; -3225;PARENTHESIZED IDEOGRAPH SIX;No;0;L; 0028 516D 0029;;;6;N;;;;; -3226;PARENTHESIZED IDEOGRAPH SEVEN;No;0;L; 0028 4E03 0029;;;7;N;;;;; -3227;PARENTHESIZED IDEOGRAPH EIGHT;No;0;L; 0028 516B 0029;;;8;N;;;;; -3228;PARENTHESIZED IDEOGRAPH NINE;No;0;L; 0028 4E5D 0029;;;9;N;;;;; -3229;PARENTHESIZED IDEOGRAPH TEN;No;0;L; 0028 5341 0029;;;10;N;;;;; -322A;PARENTHESIZED IDEOGRAPH MOON;So;0;L; 0028 6708 0029;;;;N;;;;; -322B;PARENTHESIZED IDEOGRAPH FIRE;So;0;L; 0028 706B 0029;;;;N;;;;; -322C;PARENTHESIZED IDEOGRAPH WATER;So;0;L; 0028 6C34 0029;;;;N;;;;; -322D;PARENTHESIZED IDEOGRAPH WOOD;So;0;L; 0028 6728 0029;;;;N;;;;; -322E;PARENTHESIZED IDEOGRAPH METAL;So;0;L; 0028 91D1 0029;;;;N;;;;; -322F;PARENTHESIZED IDEOGRAPH EARTH;So;0;L; 0028 571F 0029;;;;N;;;;; -3230;PARENTHESIZED IDEOGRAPH SUN;So;0;L; 0028 65E5 0029;;;;N;;;;; -3231;PARENTHESIZED IDEOGRAPH STOCK;So;0;L; 0028 682A 0029;;;;N;;;;; -3232;PARENTHESIZED IDEOGRAPH HAVE;So;0;L; 0028 6709 0029;;;;N;;;;; -3233;PARENTHESIZED IDEOGRAPH SOCIETY;So;0;L; 0028 793E 0029;;;;N;;;;; -3234;PARENTHESIZED IDEOGRAPH NAME;So;0;L; 0028 540D 0029;;;;N;;;;; -3235;PARENTHESIZED IDEOGRAPH SPECIAL;So;0;L; 0028 7279 0029;;;;N;;;;; -3236;PARENTHESIZED IDEOGRAPH FINANCIAL;So;0;L; 0028 8CA1 0029;;;;N;;;;; -3237;PARENTHESIZED IDEOGRAPH CONGRATULATION;So;0;L; 0028 795D 0029;;;;N;;;;; -3238;PARENTHESIZED IDEOGRAPH LABOR;So;0;L; 0028 52B4 0029;;;;N;;;;; -3239;PARENTHESIZED IDEOGRAPH REPRESENT;So;0;L; 0028 4EE3 0029;;;;N;;;;; -323A;PARENTHESIZED IDEOGRAPH CALL;So;0;L; 0028 547C 0029;;;;N;;;;; -323B;PARENTHESIZED IDEOGRAPH STUDY;So;0;L; 0028 5B66 0029;;;;N;;;;; -323C;PARENTHESIZED IDEOGRAPH SUPERVISE;So;0;L; 0028 76E3 0029;;;;N;;;;; -323D;PARENTHESIZED IDEOGRAPH ENTERPRISE;So;0;L; 0028 4F01 0029;;;;N;;;;; -323E;PARENTHESIZED IDEOGRAPH RESOURCE;So;0;L; 0028 8CC7 0029;;;;N;;;;; -323F;PARENTHESIZED IDEOGRAPH ALLIANCE;So;0;L; 0028 5354 0029;;;;N;;;;; -3240;PARENTHESIZED IDEOGRAPH FESTIVAL;So;0;L; 0028 796D 0029;;;;N;;;;; -3241;PARENTHESIZED IDEOGRAPH REST;So;0;L; 0028 4F11 0029;;;;N;;;;; -3242;PARENTHESIZED IDEOGRAPH SELF;So;0;L; 0028 81EA 0029;;;;N;;;;; -3243;PARENTHESIZED IDEOGRAPH REACH;So;0;L; 0028 81F3 0029;;;;N;;;;; -3250;PARTNERSHIP SIGN;So;0;ON; 0050 0054 0045;;;;N;;;;; -3251;CIRCLED NUMBER TWENTY ONE;No;0;ON; 0032 0031;;;21;N;;;;; -3252;CIRCLED NUMBER TWENTY TWO;No;0;ON; 0032 0032;;;22;N;;;;; -3253;CIRCLED NUMBER TWENTY THREE;No;0;ON; 0032 0033;;;23;N;;;;; -3254;CIRCLED NUMBER TWENTY FOUR;No;0;ON; 0032 0034;;;24;N;;;;; -3255;CIRCLED NUMBER TWENTY FIVE;No;0;ON; 0032 0035;;;25;N;;;;; -3256;CIRCLED NUMBER TWENTY SIX;No;0;ON; 0032 0036;;;26;N;;;;; -3257;CIRCLED NUMBER TWENTY SEVEN;No;0;ON; 0032 0037;;;27;N;;;;; -3258;CIRCLED NUMBER TWENTY EIGHT;No;0;ON; 0032 0038;;;28;N;;;;; -3259;CIRCLED NUMBER TWENTY NINE;No;0;ON; 0032 0039;;;29;N;;;;; -325A;CIRCLED NUMBER THIRTY;No;0;ON; 0033 0030;;;30;N;;;;; -325B;CIRCLED NUMBER THIRTY ONE;No;0;ON; 0033 0031;;;31;N;;;;; -325C;CIRCLED NUMBER THIRTY TWO;No;0;ON; 0033 0032;;;32;N;;;;; -325D;CIRCLED NUMBER THIRTY THREE;No;0;ON; 0033 0033;;;33;N;;;;; -325E;CIRCLED NUMBER THIRTY FOUR;No;0;ON; 0033 0034;;;34;N;;;;; -325F;CIRCLED NUMBER THIRTY FIVE;No;0;ON; 0033 0035;;;35;N;;;;; -3260;CIRCLED HANGUL KIYEOK;So;0;L; 1100;;;;N;CIRCLED HANGUL GIYEOG;;;; -3261;CIRCLED HANGUL NIEUN;So;0;L; 1102;;;;N;;;;; -3262;CIRCLED HANGUL TIKEUT;So;0;L; 1103;;;;N;CIRCLED HANGUL DIGEUD;;;; -3263;CIRCLED HANGUL RIEUL;So;0;L; 1105;;;;N;CIRCLED HANGUL LIEUL;;;; -3264;CIRCLED HANGUL MIEUM;So;0;L; 1106;;;;N;;;;; -3265;CIRCLED HANGUL PIEUP;So;0;L; 1107;;;;N;CIRCLED HANGUL BIEUB;;;; -3266;CIRCLED HANGUL SIOS;So;0;L; 1109;;;;N;;;;; -3267;CIRCLED HANGUL IEUNG;So;0;L; 110B;;;;N;;;;; -3268;CIRCLED HANGUL CIEUC;So;0;L; 110C;;;;N;CIRCLED HANGUL JIEUJ;;;; -3269;CIRCLED HANGUL CHIEUCH;So;0;L; 110E;;;;N;CIRCLED HANGUL CIEUC;;;; -326A;CIRCLED HANGUL KHIEUKH;So;0;L; 110F;;;;N;CIRCLED HANGUL KIYEOK;;;; -326B;CIRCLED HANGUL THIEUTH;So;0;L; 1110;;;;N;CIRCLED HANGUL TIEUT;;;; -326C;CIRCLED HANGUL PHIEUPH;So;0;L; 1111;;;;N;CIRCLED HANGUL PIEUP;;;; -326D;CIRCLED HANGUL HIEUH;So;0;L; 1112;;;;N;;;;; -326E;CIRCLED HANGUL KIYEOK A;So;0;L; 1100 1161;;;;N;CIRCLED HANGUL GA;;;; -326F;CIRCLED HANGUL NIEUN A;So;0;L; 1102 1161;;;;N;CIRCLED HANGUL NA;;;; -3270;CIRCLED HANGUL TIKEUT A;So;0;L; 1103 1161;;;;N;CIRCLED HANGUL DA;;;; -3271;CIRCLED HANGUL RIEUL A;So;0;L; 1105 1161;;;;N;CIRCLED HANGUL LA;;;; -3272;CIRCLED HANGUL MIEUM A;So;0;L; 1106 1161;;;;N;CIRCLED HANGUL MA;;;; -3273;CIRCLED HANGUL PIEUP A;So;0;L; 1107 1161;;;;N;CIRCLED HANGUL BA;;;; -3274;CIRCLED HANGUL SIOS A;So;0;L; 1109 1161;;;;N;CIRCLED HANGUL SA;;;; -3275;CIRCLED HANGUL IEUNG A;So;0;L; 110B 1161;;;;N;CIRCLED HANGUL A;;;; -3276;CIRCLED HANGUL CIEUC A;So;0;L; 110C 1161;;;;N;CIRCLED HANGUL JA;;;; -3277;CIRCLED HANGUL CHIEUCH A;So;0;L; 110E 1161;;;;N;CIRCLED HANGUL CA;;;; -3278;CIRCLED HANGUL KHIEUKH A;So;0;L; 110F 1161;;;;N;CIRCLED HANGUL KA;;;; -3279;CIRCLED HANGUL THIEUTH A;So;0;L; 1110 1161;;;;N;CIRCLED HANGUL TA;;;; -327A;CIRCLED HANGUL PHIEUPH A;So;0;L; 1111 1161;;;;N;CIRCLED HANGUL PA;;;; -327B;CIRCLED HANGUL HIEUH A;So;0;L; 1112 1161;;;;N;CIRCLED HANGUL HA;;;; -327C;CIRCLED KOREAN CHARACTER CHAMKO;So;0;ON; 110E 1161 11B7 1100 1169;;;;N;;;;; -327D;CIRCLED KOREAN CHARACTER JUEUI;So;0;ON; 110C 116E 110B 1174;;;;N;;;;; -327E;CIRCLED HANGUL IEUNG U;So;0;ON; 110B 116E;;;;N;;;;; -327F;KOREAN STANDARD SYMBOL;So;0;L;;;;;N;;;;; -3280;CIRCLED IDEOGRAPH ONE;No;0;L; 4E00;;;1;N;;;;; -3281;CIRCLED IDEOGRAPH TWO;No;0;L; 4E8C;;;2;N;;;;; -3282;CIRCLED IDEOGRAPH THREE;No;0;L; 4E09;;;3;N;;;;; -3283;CIRCLED IDEOGRAPH FOUR;No;0;L; 56DB;;;4;N;;;;; -3284;CIRCLED IDEOGRAPH FIVE;No;0;L; 4E94;;;5;N;;;;; -3285;CIRCLED IDEOGRAPH SIX;No;0;L; 516D;;;6;N;;;;; -3286;CIRCLED IDEOGRAPH SEVEN;No;0;L; 4E03;;;7;N;;;;; -3287;CIRCLED IDEOGRAPH EIGHT;No;0;L; 516B;;;8;N;;;;; -3288;CIRCLED IDEOGRAPH NINE;No;0;L; 4E5D;;;9;N;;;;; -3289;CIRCLED IDEOGRAPH TEN;No;0;L; 5341;;;10;N;;;;; -328A;CIRCLED IDEOGRAPH MOON;So;0;L; 6708;;;;N;;;;; -328B;CIRCLED IDEOGRAPH FIRE;So;0;L; 706B;;;;N;;;;; -328C;CIRCLED IDEOGRAPH WATER;So;0;L; 6C34;;;;N;;;;; -328D;CIRCLED IDEOGRAPH WOOD;So;0;L; 6728;;;;N;;;;; -328E;CIRCLED IDEOGRAPH METAL;So;0;L; 91D1;;;;N;;;;; -328F;CIRCLED IDEOGRAPH EARTH;So;0;L; 571F;;;;N;;;;; -3290;CIRCLED IDEOGRAPH SUN;So;0;L; 65E5;;;;N;;;;; -3291;CIRCLED IDEOGRAPH STOCK;So;0;L; 682A;;;;N;;;;; -3292;CIRCLED IDEOGRAPH HAVE;So;0;L; 6709;;;;N;;;;; -3293;CIRCLED IDEOGRAPH SOCIETY;So;0;L; 793E;;;;N;;;;; -3294;CIRCLED IDEOGRAPH NAME;So;0;L; 540D;;;;N;;;;; -3295;CIRCLED IDEOGRAPH SPECIAL;So;0;L; 7279;;;;N;;;;; -3296;CIRCLED IDEOGRAPH FINANCIAL;So;0;L; 8CA1;;;;N;;;;; -3297;CIRCLED IDEOGRAPH CONGRATULATION;So;0;L; 795D;;;;N;;;;; -3298;CIRCLED IDEOGRAPH LABOR;So;0;L; 52B4;;;;N;;;;; -3299;CIRCLED IDEOGRAPH SECRET;So;0;L; 79D8;;;;N;;;;; -329A;CIRCLED IDEOGRAPH MALE;So;0;L; 7537;;;;N;;;;; -329B;CIRCLED IDEOGRAPH FEMALE;So;0;L; 5973;;;;N;;;;; -329C;CIRCLED IDEOGRAPH SUITABLE;So;0;L; 9069;;;;N;;;;; -329D;CIRCLED IDEOGRAPH EXCELLENT;So;0;L; 512A;;;;N;;;;; -329E;CIRCLED IDEOGRAPH PRINT;So;0;L; 5370;;;;N;;;;; -329F;CIRCLED IDEOGRAPH ATTENTION;So;0;L; 6CE8;;;;N;;;;; -32A0;CIRCLED IDEOGRAPH ITEM;So;0;L; 9805;;;;N;;;;; -32A1;CIRCLED IDEOGRAPH REST;So;0;L; 4F11;;;;N;;;;; -32A2;CIRCLED IDEOGRAPH COPY;So;0;L; 5199;;;;N;;;;; -32A3;CIRCLED IDEOGRAPH CORRECT;So;0;L; 6B63;;;;N;;;;; -32A4;CIRCLED IDEOGRAPH HIGH;So;0;L; 4E0A;;;;N;;;;; -32A5;CIRCLED IDEOGRAPH CENTRE;So;0;L; 4E2D;;;;N;CIRCLED IDEOGRAPH CENTER;;;; -32A6;CIRCLED IDEOGRAPH LOW;So;0;L; 4E0B;;;;N;;;;; -32A7;CIRCLED IDEOGRAPH LEFT;So;0;L; 5DE6;;;;N;;;;; -32A8;CIRCLED IDEOGRAPH RIGHT;So;0;L; 53F3;;;;N;;;;; -32A9;CIRCLED IDEOGRAPH MEDICINE;So;0;L; 533B;;;;N;;;;; -32AA;CIRCLED IDEOGRAPH RELIGION;So;0;L; 5B97;;;;N;;;;; -32AB;CIRCLED IDEOGRAPH STUDY;So;0;L; 5B66;;;;N;;;;; -32AC;CIRCLED IDEOGRAPH SUPERVISE;So;0;L; 76E3;;;;N;;;;; -32AD;CIRCLED IDEOGRAPH ENTERPRISE;So;0;L; 4F01;;;;N;;;;; -32AE;CIRCLED IDEOGRAPH RESOURCE;So;0;L; 8CC7;;;;N;;;;; -32AF;CIRCLED IDEOGRAPH ALLIANCE;So;0;L; 5354;;;;N;;;;; -32B0;CIRCLED IDEOGRAPH NIGHT;So;0;L; 591C;;;;N;;;;; -32B1;CIRCLED NUMBER THIRTY SIX;No;0;ON; 0033 0036;;;36;N;;;;; -32B2;CIRCLED NUMBER THIRTY SEVEN;No;0;ON; 0033 0037;;;37;N;;;;; -32B3;CIRCLED NUMBER THIRTY EIGHT;No;0;ON; 0033 0038;;;38;N;;;;; -32B4;CIRCLED NUMBER THIRTY NINE;No;0;ON; 0033 0039;;;39;N;;;;; -32B5;CIRCLED NUMBER FORTY;No;0;ON; 0034 0030;;;40;N;;;;; -32B6;CIRCLED NUMBER FORTY ONE;No;0;ON; 0034 0031;;;41;N;;;;; -32B7;CIRCLED NUMBER FORTY TWO;No;0;ON; 0034 0032;;;42;N;;;;; -32B8;CIRCLED NUMBER FORTY THREE;No;0;ON; 0034 0033;;;43;N;;;;; -32B9;CIRCLED NUMBER FORTY FOUR;No;0;ON; 0034 0034;;;44;N;;;;; -32BA;CIRCLED NUMBER FORTY FIVE;No;0;ON; 0034 0035;;;45;N;;;;; -32BB;CIRCLED NUMBER FORTY SIX;No;0;ON; 0034 0036;;;46;N;;;;; -32BC;CIRCLED NUMBER FORTY SEVEN;No;0;ON; 0034 0037;;;47;N;;;;; -32BD;CIRCLED NUMBER FORTY EIGHT;No;0;ON; 0034 0038;;;48;N;;;;; -32BE;CIRCLED NUMBER FORTY NINE;No;0;ON; 0034 0039;;;49;N;;;;; -32BF;CIRCLED NUMBER FIFTY;No;0;ON; 0035 0030;;;50;N;;;;; -32C0;IDEOGRAPHIC TELEGRAPH SYMBOL FOR JANUARY;So;0;L; 0031 6708;;;;N;;;;; -32C1;IDEOGRAPHIC TELEGRAPH SYMBOL FOR FEBRUARY;So;0;L; 0032 6708;;;;N;;;;; -32C2;IDEOGRAPHIC TELEGRAPH SYMBOL FOR MARCH;So;0;L; 0033 6708;;;;N;;;;; -32C3;IDEOGRAPHIC TELEGRAPH SYMBOL FOR APRIL;So;0;L; 0034 6708;;;;N;;;;; -32C4;IDEOGRAPHIC TELEGRAPH SYMBOL FOR MAY;So;0;L; 0035 6708;;;;N;;;;; -32C5;IDEOGRAPHIC TELEGRAPH SYMBOL FOR JUNE;So;0;L; 0036 6708;;;;N;;;;; -32C6;IDEOGRAPHIC TELEGRAPH SYMBOL FOR JULY;So;0;L; 0037 6708;;;;N;;;;; -32C7;IDEOGRAPHIC TELEGRAPH SYMBOL FOR AUGUST;So;0;L; 0038 6708;;;;N;;;;; -32C8;IDEOGRAPHIC TELEGRAPH SYMBOL FOR SEPTEMBER;So;0;L; 0039 6708;;;;N;;;;; -32C9;IDEOGRAPHIC TELEGRAPH SYMBOL FOR OCTOBER;So;0;L; 0031 0030 6708;;;;N;;;;; -32CA;IDEOGRAPHIC TELEGRAPH SYMBOL FOR NOVEMBER;So;0;L; 0031 0031 6708;;;;N;;;;; -32CB;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DECEMBER;So;0;L; 0031 0032 6708;;;;N;;;;; -32CC;SQUARE HG;So;0;ON; 0048 0067;;;;N;;;;; -32CD;SQUARE ERG;So;0;ON; 0065 0072 0067;;;;N;;;;; -32CE;SQUARE EV;So;0;ON; 0065 0056;;;;N;;;;; -32CF;LIMITED LIABILITY SIGN;So;0;ON; 004C 0054 0044;;;;N;;;;; -32D0;CIRCLED KATAKANA A;So;0;L; 30A2;;;;N;;;;; -32D1;CIRCLED KATAKANA I;So;0;L; 30A4;;;;N;;;;; -32D2;CIRCLED KATAKANA U;So;0;L; 30A6;;;;N;;;;; -32D3;CIRCLED KATAKANA E;So;0;L; 30A8;;;;N;;;;; -32D4;CIRCLED KATAKANA O;So;0;L; 30AA;;;;N;;;;; -32D5;CIRCLED KATAKANA KA;So;0;L; 30AB;;;;N;;;;; -32D6;CIRCLED KATAKANA KI;So;0;L; 30AD;;;;N;;;;; -32D7;CIRCLED KATAKANA KU;So;0;L; 30AF;;;;N;;;;; -32D8;CIRCLED KATAKANA KE;So;0;L; 30B1;;;;N;;;;; -32D9;CIRCLED KATAKANA KO;So;0;L; 30B3;;;;N;;;;; -32DA;CIRCLED KATAKANA SA;So;0;L; 30B5;;;;N;;;;; -32DB;CIRCLED KATAKANA SI;So;0;L; 30B7;;;;N;;;;; -32DC;CIRCLED KATAKANA SU;So;0;L; 30B9;;;;N;;;;; -32DD;CIRCLED KATAKANA SE;So;0;L; 30BB;;;;N;;;;; -32DE;CIRCLED KATAKANA SO;So;0;L; 30BD;;;;N;;;;; -32DF;CIRCLED KATAKANA TA;So;0;L; 30BF;;;;N;;;;; -32E0;CIRCLED KATAKANA TI;So;0;L; 30C1;;;;N;;;;; -32E1;CIRCLED KATAKANA TU;So;0;L; 30C4;;;;N;;;;; -32E2;CIRCLED KATAKANA TE;So;0;L; 30C6;;;;N;;;;; -32E3;CIRCLED KATAKANA TO;So;0;L; 30C8;;;;N;;;;; -32E4;CIRCLED KATAKANA NA;So;0;L; 30CA;;;;N;;;;; -32E5;CIRCLED KATAKANA NI;So;0;L; 30CB;;;;N;;;;; -32E6;CIRCLED KATAKANA NU;So;0;L; 30CC;;;;N;;;;; -32E7;CIRCLED KATAKANA NE;So;0;L; 30CD;;;;N;;;;; -32E8;CIRCLED KATAKANA NO;So;0;L; 30CE;;;;N;;;;; -32E9;CIRCLED KATAKANA HA;So;0;L; 30CF;;;;N;;;;; -32EA;CIRCLED KATAKANA HI;So;0;L; 30D2;;;;N;;;;; -32EB;CIRCLED KATAKANA HU;So;0;L; 30D5;;;;N;;;;; -32EC;CIRCLED KATAKANA HE;So;0;L; 30D8;;;;N;;;;; -32ED;CIRCLED KATAKANA HO;So;0;L; 30DB;;;;N;;;;; -32EE;CIRCLED KATAKANA MA;So;0;L; 30DE;;;;N;;;;; -32EF;CIRCLED KATAKANA MI;So;0;L; 30DF;;;;N;;;;; -32F0;CIRCLED KATAKANA MU;So;0;L; 30E0;;;;N;;;;; -32F1;CIRCLED KATAKANA ME;So;0;L; 30E1;;;;N;;;;; -32F2;CIRCLED KATAKANA MO;So;0;L; 30E2;;;;N;;;;; -32F3;CIRCLED KATAKANA YA;So;0;L; 30E4;;;;N;;;;; -32F4;CIRCLED KATAKANA YU;So;0;L; 30E6;;;;N;;;;; -32F5;CIRCLED KATAKANA YO;So;0;L; 30E8;;;;N;;;;; -32F6;CIRCLED KATAKANA RA;So;0;L; 30E9;;;;N;;;;; -32F7;CIRCLED KATAKANA RI;So;0;L; 30EA;;;;N;;;;; -32F8;CIRCLED KATAKANA RU;So;0;L; 30EB;;;;N;;;;; -32F9;CIRCLED KATAKANA RE;So;0;L; 30EC;;;;N;;;;; -32FA;CIRCLED KATAKANA RO;So;0;L; 30ED;;;;N;;;;; -32FB;CIRCLED KATAKANA WA;So;0;L; 30EF;;;;N;;;;; -32FC;CIRCLED KATAKANA WI;So;0;L; 30F0;;;;N;;;;; -32FD;CIRCLED KATAKANA WE;So;0;L; 30F1;;;;N;;;;; -32FE;CIRCLED KATAKANA WO;So;0;L; 30F2;;;;N;;;;; -3300;SQUARE APAATO;So;0;L; 30A2 30D1 30FC 30C8;;;;N;SQUARED APAATO;;;; -3301;SQUARE ARUHUA;So;0;L; 30A2 30EB 30D5 30A1;;;;N;SQUARED ARUHUA;;;; -3302;SQUARE ANPEA;So;0;L; 30A2 30F3 30DA 30A2;;;;N;SQUARED ANPEA;;;; -3303;SQUARE AARU;So;0;L; 30A2 30FC 30EB;;;;N;SQUARED AARU;;;; -3304;SQUARE ININGU;So;0;L; 30A4 30CB 30F3 30B0;;;;N;SQUARED ININGU;;;; -3305;SQUARE INTI;So;0;L; 30A4 30F3 30C1;;;;N;SQUARED INTI;;;; -3306;SQUARE UON;So;0;L; 30A6 30A9 30F3;;;;N;SQUARED UON;;;; -3307;SQUARE ESUKUUDO;So;0;L; 30A8 30B9 30AF 30FC 30C9;;;;N;SQUARED ESUKUUDO;;;; -3308;SQUARE EEKAA;So;0;L; 30A8 30FC 30AB 30FC;;;;N;SQUARED EEKAA;;;; -3309;SQUARE ONSU;So;0;L; 30AA 30F3 30B9;;;;N;SQUARED ONSU;;;; -330A;SQUARE OOMU;So;0;L; 30AA 30FC 30E0;;;;N;SQUARED OOMU;;;; -330B;SQUARE KAIRI;So;0;L; 30AB 30A4 30EA;;;;N;SQUARED KAIRI;;;; -330C;SQUARE KARATTO;So;0;L; 30AB 30E9 30C3 30C8;;;;N;SQUARED KARATTO;;;; -330D;SQUARE KARORII;So;0;L; 30AB 30ED 30EA 30FC;;;;N;SQUARED KARORII;;;; -330E;SQUARE GARON;So;0;L; 30AC 30ED 30F3;;;;N;SQUARED GARON;;;; -330F;SQUARE GANMA;So;0;L; 30AC 30F3 30DE;;;;N;SQUARED GANMA;;;; -3310;SQUARE GIGA;So;0;L; 30AE 30AC;;;;N;SQUARED GIGA;;;; -3311;SQUARE GINII;So;0;L; 30AE 30CB 30FC;;;;N;SQUARED GINII;;;; -3312;SQUARE KYURII;So;0;L; 30AD 30E5 30EA 30FC;;;;N;SQUARED KYURII;;;; -3313;SQUARE GIRUDAA;So;0;L; 30AE 30EB 30C0 30FC;;;;N;SQUARED GIRUDAA;;;; -3314;SQUARE KIRO;So;0;L; 30AD 30ED;;;;N;SQUARED KIRO;;;; -3315;SQUARE KIROGURAMU;So;0;L; 30AD 30ED 30B0 30E9 30E0;;;;N;SQUARED KIROGURAMU;;;; -3316;SQUARE KIROMEETORU;So;0;L; 30AD 30ED 30E1 30FC 30C8 30EB;;;;N;SQUARED KIROMEETORU;;;; -3317;SQUARE KIROWATTO;So;0;L; 30AD 30ED 30EF 30C3 30C8;;;;N;SQUARED KIROWATTO;;;; -3318;SQUARE GURAMU;So;0;L; 30B0 30E9 30E0;;;;N;SQUARED GURAMU;;;; -3319;SQUARE GURAMUTON;So;0;L; 30B0 30E9 30E0 30C8 30F3;;;;N;SQUARED GURAMUTON;;;; -331A;SQUARE KURUZEIRO;So;0;L; 30AF 30EB 30BC 30A4 30ED;;;;N;SQUARED KURUZEIRO;;;; -331B;SQUARE KUROONE;So;0;L; 30AF 30ED 30FC 30CD;;;;N;SQUARED KUROONE;;;; -331C;SQUARE KEESU;So;0;L; 30B1 30FC 30B9;;;;N;SQUARED KEESU;;;; -331D;SQUARE KORUNA;So;0;L; 30B3 30EB 30CA;;;;N;SQUARED KORUNA;;;; -331E;SQUARE KOOPO;So;0;L; 30B3 30FC 30DD;;;;N;SQUARED KOOPO;;;; -331F;SQUARE SAIKURU;So;0;L; 30B5 30A4 30AF 30EB;;;;N;SQUARED SAIKURU;;;; -3320;SQUARE SANTIIMU;So;0;L; 30B5 30F3 30C1 30FC 30E0;;;;N;SQUARED SANTIIMU;;;; -3321;SQUARE SIRINGU;So;0;L; 30B7 30EA 30F3 30B0;;;;N;SQUARED SIRINGU;;;; -3322;SQUARE SENTI;So;0;L; 30BB 30F3 30C1;;;;N;SQUARED SENTI;;;; -3323;SQUARE SENTO;So;0;L; 30BB 30F3 30C8;;;;N;SQUARED SENTO;;;; -3324;SQUARE DAASU;So;0;L; 30C0 30FC 30B9;;;;N;SQUARED DAASU;;;; -3325;SQUARE DESI;So;0;L; 30C7 30B7;;;;N;SQUARED DESI;;;; -3326;SQUARE DORU;So;0;L; 30C9 30EB;;;;N;SQUARED DORU;;;; -3327;SQUARE TON;So;0;L; 30C8 30F3;;;;N;SQUARED TON;;;; -3328;SQUARE NANO;So;0;L; 30CA 30CE;;;;N;SQUARED NANO;;;; -3329;SQUARE NOTTO;So;0;L; 30CE 30C3 30C8;;;;N;SQUARED NOTTO;;;; -332A;SQUARE HAITU;So;0;L; 30CF 30A4 30C4;;;;N;SQUARED HAITU;;;; -332B;SQUARE PAASENTO;So;0;L; 30D1 30FC 30BB 30F3 30C8;;;;N;SQUARED PAASENTO;;;; -332C;SQUARE PAATU;So;0;L; 30D1 30FC 30C4;;;;N;SQUARED PAATU;;;; -332D;SQUARE BAARERU;So;0;L; 30D0 30FC 30EC 30EB;;;;N;SQUARED BAARERU;;;; -332E;SQUARE PIASUTORU;So;0;L; 30D4 30A2 30B9 30C8 30EB;;;;N;SQUARED PIASUTORU;;;; -332F;SQUARE PIKURU;So;0;L; 30D4 30AF 30EB;;;;N;SQUARED PIKURU;;;; -3330;SQUARE PIKO;So;0;L; 30D4 30B3;;;;N;SQUARED PIKO;;;; -3331;SQUARE BIRU;So;0;L; 30D3 30EB;;;;N;SQUARED BIRU;;;; -3332;SQUARE HUARADDO;So;0;L; 30D5 30A1 30E9 30C3 30C9;;;;N;SQUARED HUARADDO;;;; -3333;SQUARE HUIITO;So;0;L; 30D5 30A3 30FC 30C8;;;;N;SQUARED HUIITO;;;; -3334;SQUARE BUSSYERU;So;0;L; 30D6 30C3 30B7 30A7 30EB;;;;N;SQUARED BUSSYERU;;;; -3335;SQUARE HURAN;So;0;L; 30D5 30E9 30F3;;;;N;SQUARED HURAN;;;; -3336;SQUARE HEKUTAARU;So;0;L; 30D8 30AF 30BF 30FC 30EB;;;;N;SQUARED HEKUTAARU;;;; -3337;SQUARE PESO;So;0;L; 30DA 30BD;;;;N;SQUARED PESO;;;; -3338;SQUARE PENIHI;So;0;L; 30DA 30CB 30D2;;;;N;SQUARED PENIHI;;;; -3339;SQUARE HERUTU;So;0;L; 30D8 30EB 30C4;;;;N;SQUARED HERUTU;;;; -333A;SQUARE PENSU;So;0;L; 30DA 30F3 30B9;;;;N;SQUARED PENSU;;;; -333B;SQUARE PEEZI;So;0;L; 30DA 30FC 30B8;;;;N;SQUARED PEEZI;;;; -333C;SQUARE BEETA;So;0;L; 30D9 30FC 30BF;;;;N;SQUARED BEETA;;;; -333D;SQUARE POINTO;So;0;L; 30DD 30A4 30F3 30C8;;;;N;SQUARED POINTO;;;; -333E;SQUARE BORUTO;So;0;L; 30DC 30EB 30C8;;;;N;SQUARED BORUTO;;;; -333F;SQUARE HON;So;0;L; 30DB 30F3;;;;N;SQUARED HON;;;; -3340;SQUARE PONDO;So;0;L; 30DD 30F3 30C9;;;;N;SQUARED PONDO;;;; -3341;SQUARE HOORU;So;0;L; 30DB 30FC 30EB;;;;N;SQUARED HOORU;;;; -3342;SQUARE HOON;So;0;L; 30DB 30FC 30F3;;;;N;SQUARED HOON;;;; -3343;SQUARE MAIKURO;So;0;L; 30DE 30A4 30AF 30ED;;;;N;SQUARED MAIKURO;;;; -3344;SQUARE MAIRU;So;0;L; 30DE 30A4 30EB;;;;N;SQUARED MAIRU;;;; -3345;SQUARE MAHHA;So;0;L; 30DE 30C3 30CF;;;;N;SQUARED MAHHA;;;; -3346;SQUARE MARUKU;So;0;L; 30DE 30EB 30AF;;;;N;SQUARED MARUKU;;;; -3347;SQUARE MANSYON;So;0;L; 30DE 30F3 30B7 30E7 30F3;;;;N;SQUARED MANSYON;;;; -3348;SQUARE MIKURON;So;0;L; 30DF 30AF 30ED 30F3;;;;N;SQUARED MIKURON;;;; -3349;SQUARE MIRI;So;0;L; 30DF 30EA;;;;N;SQUARED MIRI;;;; -334A;SQUARE MIRIBAARU;So;0;L; 30DF 30EA 30D0 30FC 30EB;;;;N;SQUARED MIRIBAARU;;;; -334B;SQUARE MEGA;So;0;L; 30E1 30AC;;;;N;SQUARED MEGA;;;; -334C;SQUARE MEGATON;So;0;L; 30E1 30AC 30C8 30F3;;;;N;SQUARED MEGATON;;;; -334D;SQUARE MEETORU;So;0;L; 30E1 30FC 30C8 30EB;;;;N;SQUARED MEETORU;;;; -334E;SQUARE YAADO;So;0;L; 30E4 30FC 30C9;;;;N;SQUARED YAADO;;;; -334F;SQUARE YAARU;So;0;L; 30E4 30FC 30EB;;;;N;SQUARED YAARU;;;; -3350;SQUARE YUAN;So;0;L; 30E6 30A2 30F3;;;;N;SQUARED YUAN;;;; -3351;SQUARE RITTORU;So;0;L; 30EA 30C3 30C8 30EB;;;;N;SQUARED RITTORU;;;; -3352;SQUARE RIRA;So;0;L; 30EA 30E9;;;;N;SQUARED RIRA;;;; -3353;SQUARE RUPII;So;0;L; 30EB 30D4 30FC;;;;N;SQUARED RUPII;;;; -3354;SQUARE RUUBURU;So;0;L; 30EB 30FC 30D6 30EB;;;;N;SQUARED RUUBURU;;;; -3355;SQUARE REMU;So;0;L; 30EC 30E0;;;;N;SQUARED REMU;;;; -3356;SQUARE RENTOGEN;So;0;L; 30EC 30F3 30C8 30B2 30F3;;;;N;SQUARED RENTOGEN;;;; -3357;SQUARE WATTO;So;0;L; 30EF 30C3 30C8;;;;N;SQUARED WATTO;;;; -3358;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR ZERO;So;0;L; 0030 70B9;;;;N;;;;; -3359;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR ONE;So;0;L; 0031 70B9;;;;N;;;;; -335A;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWO;So;0;L; 0032 70B9;;;;N;;;;; -335B;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR THREE;So;0;L; 0033 70B9;;;;N;;;;; -335C;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR FOUR;So;0;L; 0034 70B9;;;;N;;;;; -335D;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR FIVE;So;0;L; 0035 70B9;;;;N;;;;; -335E;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR SIX;So;0;L; 0036 70B9;;;;N;;;;; -335F;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR SEVEN;So;0;L; 0037 70B9;;;;N;;;;; -3360;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR EIGHT;So;0;L; 0038 70B9;;;;N;;;;; -3361;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR NINE;So;0;L; 0039 70B9;;;;N;;;;; -3362;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TEN;So;0;L; 0031 0030 70B9;;;;N;;;;; -3363;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR ELEVEN;So;0;L; 0031 0031 70B9;;;;N;;;;; -3364;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWELVE;So;0;L; 0031 0032 70B9;;;;N;;;;; -3365;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR THIRTEEN;So;0;L; 0031 0033 70B9;;;;N;;;;; -3366;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR FOURTEEN;So;0;L; 0031 0034 70B9;;;;N;;;;; -3367;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR FIFTEEN;So;0;L; 0031 0035 70B9;;;;N;;;;; -3368;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR SIXTEEN;So;0;L; 0031 0036 70B9;;;;N;;;;; -3369;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR SEVENTEEN;So;0;L; 0031 0037 70B9;;;;N;;;;; -336A;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR EIGHTEEN;So;0;L; 0031 0038 70B9;;;;N;;;;; -336B;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR NINETEEN;So;0;L; 0031 0039 70B9;;;;N;;;;; -336C;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY;So;0;L; 0032 0030 70B9;;;;N;;;;; -336D;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY-ONE;So;0;L; 0032 0031 70B9;;;;N;;;;; -336E;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY-TWO;So;0;L; 0032 0032 70B9;;;;N;;;;; -336F;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY-THREE;So;0;L; 0032 0033 70B9;;;;N;;;;; -3370;IDEOGRAPHIC TELEGRAPH SYMBOL FOR HOUR TWENTY-FOUR;So;0;L; 0032 0034 70B9;;;;N;;;;; -3371;SQUARE HPA;So;0;L; 0068 0050 0061;;;;N;;;;; -3372;SQUARE DA;So;0;L; 0064 0061;;;;N;;;;; -3373;SQUARE AU;So;0;L; 0041 0055;;;;N;;;;; -3374;SQUARE BAR;So;0;L; 0062 0061 0072;;;;N;;;;; -3375;SQUARE OV;So;0;L; 006F 0056;;;;N;;;;; -3376;SQUARE PC;So;0;L; 0070 0063;;;;N;;;;; -3377;SQUARE DM;So;0;ON; 0064 006D;;;;N;;;;; -3378;SQUARE DM SQUARED;So;0;ON; 0064 006D 00B2;;;;N;;;;; -3379;SQUARE DM CUBED;So;0;ON; 0064 006D 00B3;;;;N;;;;; -337A;SQUARE IU;So;0;ON; 0049 0055;;;;N;;;;; -337B;SQUARE ERA NAME HEISEI;So;0;L; 5E73 6210;;;;N;SQUARED TWO IDEOGRAPHS ERA NAME HEISEI;;;; -337C;SQUARE ERA NAME SYOUWA;So;0;L; 662D 548C;;;;N;SQUARED TWO IDEOGRAPHS ERA NAME SYOUWA;;;; -337D;SQUARE ERA NAME TAISYOU;So;0;L; 5927 6B63;;;;N;SQUARED TWO IDEOGRAPHS ERA NAME TAISYOU;;;; -337E;SQUARE ERA NAME MEIZI;So;0;L; 660E 6CBB;;;;N;SQUARED TWO IDEOGRAPHS ERA NAME MEIZI;;;; -337F;SQUARE CORPORATION;So;0;L; 682A 5F0F 4F1A 793E;;;;N;SQUARED FOUR IDEOGRAPHS CORPORATION;;;; -3380;SQUARE PA AMPS;So;0;L; 0070 0041;;;;N;SQUARED PA AMPS;;;; -3381;SQUARE NA;So;0;L; 006E 0041;;;;N;SQUARED NA;;;; -3382;SQUARE MU A;So;0;L; 03BC 0041;;;;N;SQUARED MU A;;;; -3383;SQUARE MA;So;0;L; 006D 0041;;;;N;SQUARED MA;;;; -3384;SQUARE KA;So;0;L; 006B 0041;;;;N;SQUARED KA;;;; -3385;SQUARE KB;So;0;L; 004B 0042;;;;N;SQUARED KB;;;; -3386;SQUARE MB;So;0;L; 004D 0042;;;;N;SQUARED MB;;;; -3387;SQUARE GB;So;0;L; 0047 0042;;;;N;SQUARED GB;;;; -3388;SQUARE CAL;So;0;L; 0063 0061 006C;;;;N;SQUARED CAL;;;; -3389;SQUARE KCAL;So;0;L; 006B 0063 0061 006C;;;;N;SQUARED KCAL;;;; -338A;SQUARE PF;So;0;L; 0070 0046;;;;N;SQUARED PF;;;; -338B;SQUARE NF;So;0;L; 006E 0046;;;;N;SQUARED NF;;;; -338C;SQUARE MU F;So;0;L; 03BC 0046;;;;N;SQUARED MU F;;;; -338D;SQUARE MU G;So;0;L; 03BC 0067;;;;N;SQUARED MU G;;;; -338E;SQUARE MG;So;0;L; 006D 0067;;;;N;SQUARED MG;;;; -338F;SQUARE KG;So;0;L; 006B 0067;;;;N;SQUARED KG;;;; -3390;SQUARE HZ;So;0;L; 0048 007A;;;;N;SQUARED HZ;;;; -3391;SQUARE KHZ;So;0;L; 006B 0048 007A;;;;N;SQUARED KHZ;;;; -3392;SQUARE MHZ;So;0;L; 004D 0048 007A;;;;N;SQUARED MHZ;;;; -3393;SQUARE GHZ;So;0;L; 0047 0048 007A;;;;N;SQUARED GHZ;;;; -3394;SQUARE THZ;So;0;L; 0054 0048 007A;;;;N;SQUARED THZ;;;; -3395;SQUARE MU L;So;0;L; 03BC 2113;;;;N;SQUARED MU L;;;; -3396;SQUARE ML;So;0;L; 006D 2113;;;;N;SQUARED ML;;;; -3397;SQUARE DL;So;0;L; 0064 2113;;;;N;SQUARED DL;;;; -3398;SQUARE KL;So;0;L; 006B 2113;;;;N;SQUARED KL;;;; -3399;SQUARE FM;So;0;L; 0066 006D;;;;N;SQUARED FM;;;; -339A;SQUARE NM;So;0;L; 006E 006D;;;;N;SQUARED NM;;;; -339B;SQUARE MU M;So;0;L; 03BC 006D;;;;N;SQUARED MU M;;;; -339C;SQUARE MM;So;0;L; 006D 006D;;;;N;SQUARED MM;;;; -339D;SQUARE CM;So;0;L; 0063 006D;;;;N;SQUARED CM;;;; -339E;SQUARE KM;So;0;L; 006B 006D;;;;N;SQUARED KM;;;; -339F;SQUARE MM SQUARED;So;0;L; 006D 006D 00B2;;;;N;SQUARED MM SQUARED;;;; -33A0;SQUARE CM SQUARED;So;0;L; 0063 006D 00B2;;;;N;SQUARED CM SQUARED;;;; -33A1;SQUARE M SQUARED;So;0;L; 006D 00B2;;;;N;SQUARED M SQUARED;;;; -33A2;SQUARE KM SQUARED;So;0;L; 006B 006D 00B2;;;;N;SQUARED KM SQUARED;;;; -33A3;SQUARE MM CUBED;So;0;L; 006D 006D 00B3;;;;N;SQUARED MM CUBED;;;; -33A4;SQUARE CM CUBED;So;0;L; 0063 006D 00B3;;;;N;SQUARED CM CUBED;;;; -33A5;SQUARE M CUBED;So;0;L; 006D 00B3;;;;N;SQUARED M CUBED;;;; -33A6;SQUARE KM CUBED;So;0;L; 006B 006D 00B3;;;;N;SQUARED KM CUBED;;;; -33A7;SQUARE M OVER S;So;0;L; 006D 2215 0073;;;;N;SQUARED M OVER S;;;; -33A8;SQUARE M OVER S SQUARED;So;0;L; 006D 2215 0073 00B2;;;;N;SQUARED M OVER S SQUARED;;;; -33A9;SQUARE PA;So;0;L; 0050 0061;;;;N;SQUARED PA;;;; -33AA;SQUARE KPA;So;0;L; 006B 0050 0061;;;;N;SQUARED KPA;;;; -33AB;SQUARE MPA;So;0;L; 004D 0050 0061;;;;N;SQUARED MPA;;;; -33AC;SQUARE GPA;So;0;L; 0047 0050 0061;;;;N;SQUARED GPA;;;; -33AD;SQUARE RAD;So;0;L; 0072 0061 0064;;;;N;SQUARED RAD;;;; -33AE;SQUARE RAD OVER S;So;0;L; 0072 0061 0064 2215 0073;;;;N;SQUARED RAD OVER S;;;; -33AF;SQUARE RAD OVER S SQUARED;So;0;L; 0072 0061 0064 2215 0073 00B2;;;;N;SQUARED RAD OVER S SQUARED;;;; -33B0;SQUARE PS;So;0;L; 0070 0073;;;;N;SQUARED PS;;;; -33B1;SQUARE NS;So;0;L; 006E 0073;;;;N;SQUARED NS;;;; -33B2;SQUARE MU S;So;0;L; 03BC 0073;;;;N;SQUARED MU S;;;; -33B3;SQUARE MS;So;0;L; 006D 0073;;;;N;SQUARED MS;;;; -33B4;SQUARE PV;So;0;L; 0070 0056;;;;N;SQUARED PV;;;; -33B5;SQUARE NV;So;0;L; 006E 0056;;;;N;SQUARED NV;;;; -33B6;SQUARE MU V;So;0;L; 03BC 0056;;;;N;SQUARED MU V;;;; -33B7;SQUARE MV;So;0;L; 006D 0056;;;;N;SQUARED MV;;;; -33B8;SQUARE KV;So;0;L; 006B 0056;;;;N;SQUARED KV;;;; -33B9;SQUARE MV MEGA;So;0;L; 004D 0056;;;;N;SQUARED MV MEGA;;;; -33BA;SQUARE PW;So;0;L; 0070 0057;;;;N;SQUARED PW;;;; -33BB;SQUARE NW;So;0;L; 006E 0057;;;;N;SQUARED NW;;;; -33BC;SQUARE MU W;So;0;L; 03BC 0057;;;;N;SQUARED MU W;;;; -33BD;SQUARE MW;So;0;L; 006D 0057;;;;N;SQUARED MW;;;; -33BE;SQUARE KW;So;0;L; 006B 0057;;;;N;SQUARED KW;;;; -33BF;SQUARE MW MEGA;So;0;L; 004D 0057;;;;N;SQUARED MW MEGA;;;; -33C0;SQUARE K OHM;So;0;L; 006B 03A9;;;;N;SQUARED K OHM;;;; -33C1;SQUARE M OHM;So;0;L; 004D 03A9;;;;N;SQUARED M OHM;;;; -33C2;SQUARE AM;So;0;L; 0061 002E 006D 002E;;;;N;SQUARED AM;;;; -33C3;SQUARE BQ;So;0;L; 0042 0071;;;;N;SQUARED BQ;;;; -33C4;SQUARE CC;So;0;L; 0063 0063;;;;N;SQUARED CC;;;; -33C5;SQUARE CD;So;0;L; 0063 0064;;;;N;SQUARED CD;;;; -33C6;SQUARE C OVER KG;So;0;L; 0043 2215 006B 0067;;;;N;SQUARED C OVER KG;;;; -33C7;SQUARE CO;So;0;L; 0043 006F 002E;;;;N;SQUARED CO;;;; -33C8;SQUARE DB;So;0;L; 0064 0042;;;;N;SQUARED DB;;;; -33C9;SQUARE GY;So;0;L; 0047 0079;;;;N;SQUARED GY;;;; -33CA;SQUARE HA;So;0;L; 0068 0061;;;;N;SQUARED HA;;;; -33CB;SQUARE HP;So;0;L; 0048 0050;;;;N;SQUARED HP;;;; -33CC;SQUARE IN;So;0;L; 0069 006E;;;;N;SQUARED IN;;;; -33CD;SQUARE KK;So;0;L; 004B 004B;;;;N;SQUARED KK;;;; -33CE;SQUARE KM CAPITAL;So;0;L; 004B 004D;;;;N;SQUARED KM CAPITAL;;;; -33CF;SQUARE KT;So;0;L; 006B 0074;;;;N;SQUARED KT;;;; -33D0;SQUARE LM;So;0;L; 006C 006D;;;;N;SQUARED LM;;;; -33D1;SQUARE LN;So;0;L; 006C 006E;;;;N;SQUARED LN;;;; -33D2;SQUARE LOG;So;0;L; 006C 006F 0067;;;;N;SQUARED LOG;;;; -33D3;SQUARE LX;So;0;L; 006C 0078;;;;N;SQUARED LX;;;; -33D4;SQUARE MB SMALL;So;0;L; 006D 0062;;;;N;SQUARED MB SMALL;;;; -33D5;SQUARE MIL;So;0;L; 006D 0069 006C;;;;N;SQUARED MIL;;;; -33D6;SQUARE MOL;So;0;L; 006D 006F 006C;;;;N;SQUARED MOL;;;; -33D7;SQUARE PH;So;0;L; 0050 0048;;;;N;SQUARED PH;;;; -33D8;SQUARE PM;So;0;L; 0070 002E 006D 002E;;;;N;SQUARED PM;;;; -33D9;SQUARE PPM;So;0;L; 0050 0050 004D;;;;N;SQUARED PPM;;;; -33DA;SQUARE PR;So;0;L; 0050 0052;;;;N;SQUARED PR;;;; -33DB;SQUARE SR;So;0;L; 0073 0072;;;;N;SQUARED SR;;;; -33DC;SQUARE SV;So;0;L; 0053 0076;;;;N;SQUARED SV;;;; -33DD;SQUARE WB;So;0;L; 0057 0062;;;;N;SQUARED WB;;;; -33DE;SQUARE V OVER M;So;0;ON; 0056 2215 006D;;;;N;;;;; -33DF;SQUARE A OVER M;So;0;ON; 0041 2215 006D;;;;N;;;;; -33E0;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY ONE;So;0;L; 0031 65E5;;;;N;;;;; -33E1;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWO;So;0;L; 0032 65E5;;;;N;;;;; -33E2;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY THREE;So;0;L; 0033 65E5;;;;N;;;;; -33E3;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY FOUR;So;0;L; 0034 65E5;;;;N;;;;; -33E4;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY FIVE;So;0;L; 0035 65E5;;;;N;;;;; -33E5;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY SIX;So;0;L; 0036 65E5;;;;N;;;;; -33E6;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY SEVEN;So;0;L; 0037 65E5;;;;N;;;;; -33E7;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY EIGHT;So;0;L; 0038 65E5;;;;N;;;;; -33E8;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY NINE;So;0;L; 0039 65E5;;;;N;;;;; -33E9;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TEN;So;0;L; 0031 0030 65E5;;;;N;;;;; -33EA;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY ELEVEN;So;0;L; 0031 0031 65E5;;;;N;;;;; -33EB;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWELVE;So;0;L; 0031 0032 65E5;;;;N;;;;; -33EC;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY THIRTEEN;So;0;L; 0031 0033 65E5;;;;N;;;;; -33ED;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY FOURTEEN;So;0;L; 0031 0034 65E5;;;;N;;;;; -33EE;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY FIFTEEN;So;0;L; 0031 0035 65E5;;;;N;;;;; -33EF;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY SIXTEEN;So;0;L; 0031 0036 65E5;;;;N;;;;; -33F0;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY SEVENTEEN;So;0;L; 0031 0037 65E5;;;;N;;;;; -33F1;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY EIGHTEEN;So;0;L; 0031 0038 65E5;;;;N;;;;; -33F2;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY NINETEEN;So;0;L; 0031 0039 65E5;;;;N;;;;; -33F3;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY;So;0;L; 0032 0030 65E5;;;;N;;;;; -33F4;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-ONE;So;0;L; 0032 0031 65E5;;;;N;;;;; -33F5;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-TWO;So;0;L; 0032 0032 65E5;;;;N;;;;; -33F6;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-THREE;So;0;L; 0032 0033 65E5;;;;N;;;;; -33F7;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-FOUR;So;0;L; 0032 0034 65E5;;;;N;;;;; -33F8;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-FIVE;So;0;L; 0032 0035 65E5;;;;N;;;;; -33F9;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-SIX;So;0;L; 0032 0036 65E5;;;;N;;;;; -33FA;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-SEVEN;So;0;L; 0032 0037 65E5;;;;N;;;;; -33FB;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-EIGHT;So;0;L; 0032 0038 65E5;;;;N;;;;; -33FC;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY TWENTY-NINE;So;0;L; 0032 0039 65E5;;;;N;;;;; -33FD;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY THIRTY;So;0;L; 0033 0030 65E5;;;;N;;;;; -33FE;IDEOGRAPHIC TELEGRAPH SYMBOL FOR DAY THIRTY-ONE;So;0;L; 0033 0031 65E5;;;;N;;;;; -33FF;SQUARE GAL;So;0;ON; 0067 0061 006C;;;;N;;;;; -3400;;Lo;0;L;;;;;N;;;;; -4DB5;;Lo;0;L;;;;;N;;;;; -4DC0;HEXAGRAM FOR THE CREATIVE HEAVEN;So;0;ON;;;;;N;;;;; -4DC1;HEXAGRAM FOR THE RECEPTIVE EARTH;So;0;ON;;;;;N;;;;; -4DC2;HEXAGRAM FOR DIFFICULTY AT THE BEGINNING;So;0;ON;;;;;N;;;;; -4DC3;HEXAGRAM FOR YOUTHFUL FOLLY;So;0;ON;;;;;N;;;;; -4DC4;HEXAGRAM FOR WAITING;So;0;ON;;;;;N;;;;; -4DC5;HEXAGRAM FOR CONFLICT;So;0;ON;;;;;N;;;;; -4DC6;HEXAGRAM FOR THE ARMY;So;0;ON;;;;;N;;;;; -4DC7;HEXAGRAM FOR HOLDING TOGETHER;So;0;ON;;;;;N;;;;; -4DC8;HEXAGRAM FOR SMALL TAMING;So;0;ON;;;;;N;;;;; -4DC9;HEXAGRAM FOR TREADING;So;0;ON;;;;;N;;;;; -4DCA;HEXAGRAM FOR PEACE;So;0;ON;;;;;N;;;;; -4DCB;HEXAGRAM FOR STANDSTILL;So;0;ON;;;;;N;;;;; -4DCC;HEXAGRAM FOR FELLOWSHIP;So;0;ON;;;;;N;;;;; -4DCD;HEXAGRAM FOR GREAT POSSESSION;So;0;ON;;;;;N;;;;; -4DCE;HEXAGRAM FOR MODESTY;So;0;ON;;;;;N;;;;; -4DCF;HEXAGRAM FOR ENTHUSIASM;So;0;ON;;;;;N;;;;; -4DD0;HEXAGRAM FOR FOLLOWING;So;0;ON;;;;;N;;;;; -4DD1;HEXAGRAM FOR WORK ON THE DECAYED;So;0;ON;;;;;N;;;;; -4DD2;HEXAGRAM FOR APPROACH;So;0;ON;;;;;N;;;;; -4DD3;HEXAGRAM FOR CONTEMPLATION;So;0;ON;;;;;N;;;;; -4DD4;HEXAGRAM FOR BITING THROUGH;So;0;ON;;;;;N;;;;; -4DD5;HEXAGRAM FOR GRACE;So;0;ON;;;;;N;;;;; -4DD6;HEXAGRAM FOR SPLITTING APART;So;0;ON;;;;;N;;;;; -4DD7;HEXAGRAM FOR RETURN;So;0;ON;;;;;N;;;;; -4DD8;HEXAGRAM FOR INNOCENCE;So;0;ON;;;;;N;;;;; -4DD9;HEXAGRAM FOR GREAT TAMING;So;0;ON;;;;;N;;;;; -4DDA;HEXAGRAM FOR MOUTH CORNERS;So;0;ON;;;;;N;;;;; -4DDB;HEXAGRAM FOR GREAT PREPONDERANCE;So;0;ON;;;;;N;;;;; -4DDC;HEXAGRAM FOR THE ABYSMAL WATER;So;0;ON;;;;;N;;;;; -4DDD;HEXAGRAM FOR THE CLINGING FIRE;So;0;ON;;;;;N;;;;; -4DDE;HEXAGRAM FOR INFLUENCE;So;0;ON;;;;;N;;;;; -4DDF;HEXAGRAM FOR DURATION;So;0;ON;;;;;N;;;;; -4DE0;HEXAGRAM FOR RETREAT;So;0;ON;;;;;N;;;;; -4DE1;HEXAGRAM FOR GREAT POWER;So;0;ON;;;;;N;;;;; -4DE2;HEXAGRAM FOR PROGRESS;So;0;ON;;;;;N;;;;; -4DE3;HEXAGRAM FOR DARKENING OF THE LIGHT;So;0;ON;;;;;N;;;;; -4DE4;HEXAGRAM FOR THE FAMILY;So;0;ON;;;;;N;;;;; -4DE5;HEXAGRAM FOR OPPOSITION;So;0;ON;;;;;N;;;;; -4DE6;HEXAGRAM FOR OBSTRUCTION;So;0;ON;;;;;N;;;;; -4DE7;HEXAGRAM FOR DELIVERANCE;So;0;ON;;;;;N;;;;; -4DE8;HEXAGRAM FOR DECREASE;So;0;ON;;;;;N;;;;; -4DE9;HEXAGRAM FOR INCREASE;So;0;ON;;;;;N;;;;; -4DEA;HEXAGRAM FOR BREAKTHROUGH;So;0;ON;;;;;N;;;;; -4DEB;HEXAGRAM FOR COMING TO MEET;So;0;ON;;;;;N;;;;; -4DEC;HEXAGRAM FOR GATHERING TOGETHER;So;0;ON;;;;;N;;;;; -4DED;HEXAGRAM FOR PUSHING UPWARD;So;0;ON;;;;;N;;;;; -4DEE;HEXAGRAM FOR OPPRESSION;So;0;ON;;;;;N;;;;; -4DEF;HEXAGRAM FOR THE WELL;So;0;ON;;;;;N;;;;; -4DF0;HEXAGRAM FOR REVOLUTION;So;0;ON;;;;;N;;;;; -4DF1;HEXAGRAM FOR THE CAULDRON;So;0;ON;;;;;N;;;;; -4DF2;HEXAGRAM FOR THE AROUSING THUNDER;So;0;ON;;;;;N;;;;; -4DF3;HEXAGRAM FOR THE KEEPING STILL MOUNTAIN;So;0;ON;;;;;N;;;;; -4DF4;HEXAGRAM FOR DEVELOPMENT;So;0;ON;;;;;N;;;;; -4DF5;HEXAGRAM FOR THE MARRYING MAIDEN;So;0;ON;;;;;N;;;;; -4DF6;HEXAGRAM FOR ABUNDANCE;So;0;ON;;;;;N;;;;; -4DF7;HEXAGRAM FOR THE WANDERER;So;0;ON;;;;;N;;;;; -4DF8;HEXAGRAM FOR THE GENTLE WIND;So;0;ON;;;;;N;;;;; -4DF9;HEXAGRAM FOR THE JOYOUS LAKE;So;0;ON;;;;;N;;;;; -4DFA;HEXAGRAM FOR DISPERSION;So;0;ON;;;;;N;;;;; -4DFB;HEXAGRAM FOR LIMITATION;So;0;ON;;;;;N;;;;; -4DFC;HEXAGRAM FOR INNER TRUTH;So;0;ON;;;;;N;;;;; -4DFD;HEXAGRAM FOR SMALL PREPONDERANCE;So;0;ON;;;;;N;;;;; -4DFE;HEXAGRAM FOR AFTER COMPLETION;So;0;ON;;;;;N;;;;; -4DFF;HEXAGRAM FOR BEFORE COMPLETION;So;0;ON;;;;;N;;;;; -4E00;;Lo;0;L;;;;;N;;;;; -9FC3;;Lo;0;L;;;;;N;;;;; -A000;YI SYLLABLE IT;Lo;0;L;;;;;N;;;;; -A001;YI SYLLABLE IX;Lo;0;L;;;;;N;;;;; -A002;YI SYLLABLE I;Lo;0;L;;;;;N;;;;; -A003;YI SYLLABLE IP;Lo;0;L;;;;;N;;;;; -A004;YI SYLLABLE IET;Lo;0;L;;;;;N;;;;; -A005;YI SYLLABLE IEX;Lo;0;L;;;;;N;;;;; -A006;YI SYLLABLE IE;Lo;0;L;;;;;N;;;;; -A007;YI SYLLABLE IEP;Lo;0;L;;;;;N;;;;; -A008;YI SYLLABLE AT;Lo;0;L;;;;;N;;;;; -A009;YI SYLLABLE AX;Lo;0;L;;;;;N;;;;; -A00A;YI SYLLABLE A;Lo;0;L;;;;;N;;;;; -A00B;YI SYLLABLE AP;Lo;0;L;;;;;N;;;;; -A00C;YI SYLLABLE UOX;Lo;0;L;;;;;N;;;;; -A00D;YI SYLLABLE UO;Lo;0;L;;;;;N;;;;; -A00E;YI SYLLABLE UOP;Lo;0;L;;;;;N;;;;; -A00F;YI SYLLABLE OT;Lo;0;L;;;;;N;;;;; -A010;YI SYLLABLE OX;Lo;0;L;;;;;N;;;;; -A011;YI SYLLABLE O;Lo;0;L;;;;;N;;;;; -A012;YI SYLLABLE OP;Lo;0;L;;;;;N;;;;; -A013;YI SYLLABLE EX;Lo;0;L;;;;;N;;;;; -A014;YI SYLLABLE E;Lo;0;L;;;;;N;;;;; -A015;YI SYLLABLE WU;Lm;0;L;;;;;N;;;;; -A016;YI SYLLABLE BIT;Lo;0;L;;;;;N;;;;; -A017;YI SYLLABLE BIX;Lo;0;L;;;;;N;;;;; -A018;YI SYLLABLE BI;Lo;0;L;;;;;N;;;;; -A019;YI SYLLABLE BIP;Lo;0;L;;;;;N;;;;; -A01A;YI SYLLABLE BIET;Lo;0;L;;;;;N;;;;; -A01B;YI SYLLABLE BIEX;Lo;0;L;;;;;N;;;;; -A01C;YI SYLLABLE BIE;Lo;0;L;;;;;N;;;;; -A01D;YI SYLLABLE BIEP;Lo;0;L;;;;;N;;;;; -A01E;YI SYLLABLE BAT;Lo;0;L;;;;;N;;;;; -A01F;YI SYLLABLE BAX;Lo;0;L;;;;;N;;;;; -A020;YI SYLLABLE BA;Lo;0;L;;;;;N;;;;; -A021;YI SYLLABLE BAP;Lo;0;L;;;;;N;;;;; -A022;YI SYLLABLE BUOX;Lo;0;L;;;;;N;;;;; -A023;YI SYLLABLE BUO;Lo;0;L;;;;;N;;;;; -A024;YI SYLLABLE BUOP;Lo;0;L;;;;;N;;;;; -A025;YI SYLLABLE BOT;Lo;0;L;;;;;N;;;;; -A026;YI SYLLABLE BOX;Lo;0;L;;;;;N;;;;; -A027;YI SYLLABLE BO;Lo;0;L;;;;;N;;;;; -A028;YI SYLLABLE BOP;Lo;0;L;;;;;N;;;;; -A029;YI SYLLABLE BEX;Lo;0;L;;;;;N;;;;; -A02A;YI SYLLABLE BE;Lo;0;L;;;;;N;;;;; -A02B;YI SYLLABLE BEP;Lo;0;L;;;;;N;;;;; -A02C;YI SYLLABLE BUT;Lo;0;L;;;;;N;;;;; -A02D;YI SYLLABLE BUX;Lo;0;L;;;;;N;;;;; -A02E;YI SYLLABLE BU;Lo;0;L;;;;;N;;;;; -A02F;YI SYLLABLE BUP;Lo;0;L;;;;;N;;;;; -A030;YI SYLLABLE BURX;Lo;0;L;;;;;N;;;;; -A031;YI SYLLABLE BUR;Lo;0;L;;;;;N;;;;; -A032;YI SYLLABLE BYT;Lo;0;L;;;;;N;;;;; -A033;YI SYLLABLE BYX;Lo;0;L;;;;;N;;;;; -A034;YI SYLLABLE BY;Lo;0;L;;;;;N;;;;; -A035;YI SYLLABLE BYP;Lo;0;L;;;;;N;;;;; -A036;YI SYLLABLE BYRX;Lo;0;L;;;;;N;;;;; -A037;YI SYLLABLE BYR;Lo;0;L;;;;;N;;;;; -A038;YI SYLLABLE PIT;Lo;0;L;;;;;N;;;;; -A039;YI SYLLABLE PIX;Lo;0;L;;;;;N;;;;; -A03A;YI SYLLABLE PI;Lo;0;L;;;;;N;;;;; -A03B;YI SYLLABLE PIP;Lo;0;L;;;;;N;;;;; -A03C;YI SYLLABLE PIEX;Lo;0;L;;;;;N;;;;; -A03D;YI SYLLABLE PIE;Lo;0;L;;;;;N;;;;; -A03E;YI SYLLABLE PIEP;Lo;0;L;;;;;N;;;;; -A03F;YI SYLLABLE PAT;Lo;0;L;;;;;N;;;;; -A040;YI SYLLABLE PAX;Lo;0;L;;;;;N;;;;; -A041;YI SYLLABLE PA;Lo;0;L;;;;;N;;;;; -A042;YI SYLLABLE PAP;Lo;0;L;;;;;N;;;;; -A043;YI SYLLABLE PUOX;Lo;0;L;;;;;N;;;;; -A044;YI SYLLABLE PUO;Lo;0;L;;;;;N;;;;; -A045;YI SYLLABLE PUOP;Lo;0;L;;;;;N;;;;; -A046;YI SYLLABLE POT;Lo;0;L;;;;;N;;;;; -A047;YI SYLLABLE POX;Lo;0;L;;;;;N;;;;; -A048;YI SYLLABLE PO;Lo;0;L;;;;;N;;;;; -A049;YI SYLLABLE POP;Lo;0;L;;;;;N;;;;; -A04A;YI SYLLABLE PUT;Lo;0;L;;;;;N;;;;; -A04B;YI SYLLABLE PUX;Lo;0;L;;;;;N;;;;; -A04C;YI SYLLABLE PU;Lo;0;L;;;;;N;;;;; -A04D;YI SYLLABLE PUP;Lo;0;L;;;;;N;;;;; -A04E;YI SYLLABLE PURX;Lo;0;L;;;;;N;;;;; -A04F;YI SYLLABLE PUR;Lo;0;L;;;;;N;;;;; -A050;YI SYLLABLE PYT;Lo;0;L;;;;;N;;;;; -A051;YI SYLLABLE PYX;Lo;0;L;;;;;N;;;;; -A052;YI SYLLABLE PY;Lo;0;L;;;;;N;;;;; -A053;YI SYLLABLE PYP;Lo;0;L;;;;;N;;;;; -A054;YI SYLLABLE PYRX;Lo;0;L;;;;;N;;;;; -A055;YI SYLLABLE PYR;Lo;0;L;;;;;N;;;;; -A056;YI SYLLABLE BBIT;Lo;0;L;;;;;N;;;;; -A057;YI SYLLABLE BBIX;Lo;0;L;;;;;N;;;;; -A058;YI SYLLABLE BBI;Lo;0;L;;;;;N;;;;; -A059;YI SYLLABLE BBIP;Lo;0;L;;;;;N;;;;; -A05A;YI SYLLABLE BBIET;Lo;0;L;;;;;N;;;;; -A05B;YI SYLLABLE BBIEX;Lo;0;L;;;;;N;;;;; -A05C;YI SYLLABLE BBIE;Lo;0;L;;;;;N;;;;; -A05D;YI SYLLABLE BBIEP;Lo;0;L;;;;;N;;;;; -A05E;YI SYLLABLE BBAT;Lo;0;L;;;;;N;;;;; -A05F;YI SYLLABLE BBAX;Lo;0;L;;;;;N;;;;; -A060;YI SYLLABLE BBA;Lo;0;L;;;;;N;;;;; -A061;YI SYLLABLE BBAP;Lo;0;L;;;;;N;;;;; -A062;YI SYLLABLE BBUOX;Lo;0;L;;;;;N;;;;; -A063;YI SYLLABLE BBUO;Lo;0;L;;;;;N;;;;; -A064;YI SYLLABLE BBUOP;Lo;0;L;;;;;N;;;;; -A065;YI SYLLABLE BBOT;Lo;0;L;;;;;N;;;;; -A066;YI SYLLABLE BBOX;Lo;0;L;;;;;N;;;;; -A067;YI SYLLABLE BBO;Lo;0;L;;;;;N;;;;; -A068;YI SYLLABLE BBOP;Lo;0;L;;;;;N;;;;; -A069;YI SYLLABLE BBEX;Lo;0;L;;;;;N;;;;; -A06A;YI SYLLABLE BBE;Lo;0;L;;;;;N;;;;; -A06B;YI SYLLABLE BBEP;Lo;0;L;;;;;N;;;;; -A06C;YI SYLLABLE BBUT;Lo;0;L;;;;;N;;;;; -A06D;YI SYLLABLE BBUX;Lo;0;L;;;;;N;;;;; -A06E;YI SYLLABLE BBU;Lo;0;L;;;;;N;;;;; -A06F;YI SYLLABLE BBUP;Lo;0;L;;;;;N;;;;; -A070;YI SYLLABLE BBURX;Lo;0;L;;;;;N;;;;; -A071;YI SYLLABLE BBUR;Lo;0;L;;;;;N;;;;; -A072;YI SYLLABLE BBYT;Lo;0;L;;;;;N;;;;; -A073;YI SYLLABLE BBYX;Lo;0;L;;;;;N;;;;; -A074;YI SYLLABLE BBY;Lo;0;L;;;;;N;;;;; -A075;YI SYLLABLE BBYP;Lo;0;L;;;;;N;;;;; -A076;YI SYLLABLE NBIT;Lo;0;L;;;;;N;;;;; -A077;YI SYLLABLE NBIX;Lo;0;L;;;;;N;;;;; -A078;YI SYLLABLE NBI;Lo;0;L;;;;;N;;;;; -A079;YI SYLLABLE NBIP;Lo;0;L;;;;;N;;;;; -A07A;YI SYLLABLE NBIEX;Lo;0;L;;;;;N;;;;; -A07B;YI SYLLABLE NBIE;Lo;0;L;;;;;N;;;;; -A07C;YI SYLLABLE NBIEP;Lo;0;L;;;;;N;;;;; -A07D;YI SYLLABLE NBAT;Lo;0;L;;;;;N;;;;; -A07E;YI SYLLABLE NBAX;Lo;0;L;;;;;N;;;;; -A07F;YI SYLLABLE NBA;Lo;0;L;;;;;N;;;;; -A080;YI SYLLABLE NBAP;Lo;0;L;;;;;N;;;;; -A081;YI SYLLABLE NBOT;Lo;0;L;;;;;N;;;;; -A082;YI SYLLABLE NBOX;Lo;0;L;;;;;N;;;;; -A083;YI SYLLABLE NBO;Lo;0;L;;;;;N;;;;; -A084;YI SYLLABLE NBOP;Lo;0;L;;;;;N;;;;; -A085;YI SYLLABLE NBUT;Lo;0;L;;;;;N;;;;; -A086;YI SYLLABLE NBUX;Lo;0;L;;;;;N;;;;; -A087;YI SYLLABLE NBU;Lo;0;L;;;;;N;;;;; -A088;YI SYLLABLE NBUP;Lo;0;L;;;;;N;;;;; -A089;YI SYLLABLE NBURX;Lo;0;L;;;;;N;;;;; -A08A;YI SYLLABLE NBUR;Lo;0;L;;;;;N;;;;; -A08B;YI SYLLABLE NBYT;Lo;0;L;;;;;N;;;;; -A08C;YI SYLLABLE NBYX;Lo;0;L;;;;;N;;;;; -A08D;YI SYLLABLE NBY;Lo;0;L;;;;;N;;;;; -A08E;YI SYLLABLE NBYP;Lo;0;L;;;;;N;;;;; -A08F;YI SYLLABLE NBYRX;Lo;0;L;;;;;N;;;;; -A090;YI SYLLABLE NBYR;Lo;0;L;;;;;N;;;;; -A091;YI SYLLABLE HMIT;Lo;0;L;;;;;N;;;;; -A092;YI SYLLABLE HMIX;Lo;0;L;;;;;N;;;;; -A093;YI SYLLABLE HMI;Lo;0;L;;;;;N;;;;; -A094;YI SYLLABLE HMIP;Lo;0;L;;;;;N;;;;; -A095;YI SYLLABLE HMIEX;Lo;0;L;;;;;N;;;;; -A096;YI SYLLABLE HMIE;Lo;0;L;;;;;N;;;;; -A097;YI SYLLABLE HMIEP;Lo;0;L;;;;;N;;;;; -A098;YI SYLLABLE HMAT;Lo;0;L;;;;;N;;;;; -A099;YI SYLLABLE HMAX;Lo;0;L;;;;;N;;;;; -A09A;YI SYLLABLE HMA;Lo;0;L;;;;;N;;;;; -A09B;YI SYLLABLE HMAP;Lo;0;L;;;;;N;;;;; -A09C;YI SYLLABLE HMUOX;Lo;0;L;;;;;N;;;;; -A09D;YI SYLLABLE HMUO;Lo;0;L;;;;;N;;;;; -A09E;YI SYLLABLE HMUOP;Lo;0;L;;;;;N;;;;; -A09F;YI SYLLABLE HMOT;Lo;0;L;;;;;N;;;;; -A0A0;YI SYLLABLE HMOX;Lo;0;L;;;;;N;;;;; -A0A1;YI SYLLABLE HMO;Lo;0;L;;;;;N;;;;; -A0A2;YI SYLLABLE HMOP;Lo;0;L;;;;;N;;;;; -A0A3;YI SYLLABLE HMUT;Lo;0;L;;;;;N;;;;; -A0A4;YI SYLLABLE HMUX;Lo;0;L;;;;;N;;;;; -A0A5;YI SYLLABLE HMU;Lo;0;L;;;;;N;;;;; -A0A6;YI SYLLABLE HMUP;Lo;0;L;;;;;N;;;;; -A0A7;YI SYLLABLE HMURX;Lo;0;L;;;;;N;;;;; -A0A8;YI SYLLABLE HMUR;Lo;0;L;;;;;N;;;;; -A0A9;YI SYLLABLE HMYX;Lo;0;L;;;;;N;;;;; -A0AA;YI SYLLABLE HMY;Lo;0;L;;;;;N;;;;; -A0AB;YI SYLLABLE HMYP;Lo;0;L;;;;;N;;;;; -A0AC;YI SYLLABLE HMYRX;Lo;0;L;;;;;N;;;;; -A0AD;YI SYLLABLE HMYR;Lo;0;L;;;;;N;;;;; -A0AE;YI SYLLABLE MIT;Lo;0;L;;;;;N;;;;; -A0AF;YI SYLLABLE MIX;Lo;0;L;;;;;N;;;;; -A0B0;YI SYLLABLE MI;Lo;0;L;;;;;N;;;;; -A0B1;YI SYLLABLE MIP;Lo;0;L;;;;;N;;;;; -A0B2;YI SYLLABLE MIEX;Lo;0;L;;;;;N;;;;; -A0B3;YI SYLLABLE MIE;Lo;0;L;;;;;N;;;;; -A0B4;YI SYLLABLE MIEP;Lo;0;L;;;;;N;;;;; -A0B5;YI SYLLABLE MAT;Lo;0;L;;;;;N;;;;; -A0B6;YI SYLLABLE MAX;Lo;0;L;;;;;N;;;;; -A0B7;YI SYLLABLE MA;Lo;0;L;;;;;N;;;;; -A0B8;YI SYLLABLE MAP;Lo;0;L;;;;;N;;;;; -A0B9;YI SYLLABLE MUOT;Lo;0;L;;;;;N;;;;; -A0BA;YI SYLLABLE MUOX;Lo;0;L;;;;;N;;;;; -A0BB;YI SYLLABLE MUO;Lo;0;L;;;;;N;;;;; -A0BC;YI SYLLABLE MUOP;Lo;0;L;;;;;N;;;;; -A0BD;YI SYLLABLE MOT;Lo;0;L;;;;;N;;;;; -A0BE;YI SYLLABLE MOX;Lo;0;L;;;;;N;;;;; -A0BF;YI SYLLABLE MO;Lo;0;L;;;;;N;;;;; -A0C0;YI SYLLABLE MOP;Lo;0;L;;;;;N;;;;; -A0C1;YI SYLLABLE MEX;Lo;0;L;;;;;N;;;;; -A0C2;YI SYLLABLE ME;Lo;0;L;;;;;N;;;;; -A0C3;YI SYLLABLE MUT;Lo;0;L;;;;;N;;;;; -A0C4;YI SYLLABLE MUX;Lo;0;L;;;;;N;;;;; -A0C5;YI SYLLABLE MU;Lo;0;L;;;;;N;;;;; -A0C6;YI SYLLABLE MUP;Lo;0;L;;;;;N;;;;; -A0C7;YI SYLLABLE MURX;Lo;0;L;;;;;N;;;;; -A0C8;YI SYLLABLE MUR;Lo;0;L;;;;;N;;;;; -A0C9;YI SYLLABLE MYT;Lo;0;L;;;;;N;;;;; -A0CA;YI SYLLABLE MYX;Lo;0;L;;;;;N;;;;; -A0CB;YI SYLLABLE MY;Lo;0;L;;;;;N;;;;; -A0CC;YI SYLLABLE MYP;Lo;0;L;;;;;N;;;;; -A0CD;YI SYLLABLE FIT;Lo;0;L;;;;;N;;;;; -A0CE;YI SYLLABLE FIX;Lo;0;L;;;;;N;;;;; -A0CF;YI SYLLABLE FI;Lo;0;L;;;;;N;;;;; -A0D0;YI SYLLABLE FIP;Lo;0;L;;;;;N;;;;; -A0D1;YI SYLLABLE FAT;Lo;0;L;;;;;N;;;;; -A0D2;YI SYLLABLE FAX;Lo;0;L;;;;;N;;;;; -A0D3;YI SYLLABLE FA;Lo;0;L;;;;;N;;;;; -A0D4;YI SYLLABLE FAP;Lo;0;L;;;;;N;;;;; -A0D5;YI SYLLABLE FOX;Lo;0;L;;;;;N;;;;; -A0D6;YI SYLLABLE FO;Lo;0;L;;;;;N;;;;; -A0D7;YI SYLLABLE FOP;Lo;0;L;;;;;N;;;;; -A0D8;YI SYLLABLE FUT;Lo;0;L;;;;;N;;;;; -A0D9;YI SYLLABLE FUX;Lo;0;L;;;;;N;;;;; -A0DA;YI SYLLABLE FU;Lo;0;L;;;;;N;;;;; -A0DB;YI SYLLABLE FUP;Lo;0;L;;;;;N;;;;; -A0DC;YI SYLLABLE FURX;Lo;0;L;;;;;N;;;;; -A0DD;YI SYLLABLE FUR;Lo;0;L;;;;;N;;;;; -A0DE;YI SYLLABLE FYT;Lo;0;L;;;;;N;;;;; -A0DF;YI SYLLABLE FYX;Lo;0;L;;;;;N;;;;; -A0E0;YI SYLLABLE FY;Lo;0;L;;;;;N;;;;; -A0E1;YI SYLLABLE FYP;Lo;0;L;;;;;N;;;;; -A0E2;YI SYLLABLE VIT;Lo;0;L;;;;;N;;;;; -A0E3;YI SYLLABLE VIX;Lo;0;L;;;;;N;;;;; -A0E4;YI SYLLABLE VI;Lo;0;L;;;;;N;;;;; -A0E5;YI SYLLABLE VIP;Lo;0;L;;;;;N;;;;; -A0E6;YI SYLLABLE VIET;Lo;0;L;;;;;N;;;;; -A0E7;YI SYLLABLE VIEX;Lo;0;L;;;;;N;;;;; -A0E8;YI SYLLABLE VIE;Lo;0;L;;;;;N;;;;; -A0E9;YI SYLLABLE VIEP;Lo;0;L;;;;;N;;;;; -A0EA;YI SYLLABLE VAT;Lo;0;L;;;;;N;;;;; -A0EB;YI SYLLABLE VAX;Lo;0;L;;;;;N;;;;; -A0EC;YI SYLLABLE VA;Lo;0;L;;;;;N;;;;; -A0ED;YI SYLLABLE VAP;Lo;0;L;;;;;N;;;;; -A0EE;YI SYLLABLE VOT;Lo;0;L;;;;;N;;;;; -A0EF;YI SYLLABLE VOX;Lo;0;L;;;;;N;;;;; -A0F0;YI SYLLABLE VO;Lo;0;L;;;;;N;;;;; -A0F1;YI SYLLABLE VOP;Lo;0;L;;;;;N;;;;; -A0F2;YI SYLLABLE VEX;Lo;0;L;;;;;N;;;;; -A0F3;YI SYLLABLE VEP;Lo;0;L;;;;;N;;;;; -A0F4;YI SYLLABLE VUT;Lo;0;L;;;;;N;;;;; -A0F5;YI SYLLABLE VUX;Lo;0;L;;;;;N;;;;; -A0F6;YI SYLLABLE VU;Lo;0;L;;;;;N;;;;; -A0F7;YI SYLLABLE VUP;Lo;0;L;;;;;N;;;;; -A0F8;YI SYLLABLE VURX;Lo;0;L;;;;;N;;;;; -A0F9;YI SYLLABLE VUR;Lo;0;L;;;;;N;;;;; -A0FA;YI SYLLABLE VYT;Lo;0;L;;;;;N;;;;; -A0FB;YI SYLLABLE VYX;Lo;0;L;;;;;N;;;;; -A0FC;YI SYLLABLE VY;Lo;0;L;;;;;N;;;;; -A0FD;YI SYLLABLE VYP;Lo;0;L;;;;;N;;;;; -A0FE;YI SYLLABLE VYRX;Lo;0;L;;;;;N;;;;; -A0FF;YI SYLLABLE VYR;Lo;0;L;;;;;N;;;;; -A100;YI SYLLABLE DIT;Lo;0;L;;;;;N;;;;; -A101;YI SYLLABLE DIX;Lo;0;L;;;;;N;;;;; -A102;YI SYLLABLE DI;Lo;0;L;;;;;N;;;;; -A103;YI SYLLABLE DIP;Lo;0;L;;;;;N;;;;; -A104;YI SYLLABLE DIEX;Lo;0;L;;;;;N;;;;; -A105;YI SYLLABLE DIE;Lo;0;L;;;;;N;;;;; -A106;YI SYLLABLE DIEP;Lo;0;L;;;;;N;;;;; -A107;YI SYLLABLE DAT;Lo;0;L;;;;;N;;;;; -A108;YI SYLLABLE DAX;Lo;0;L;;;;;N;;;;; -A109;YI SYLLABLE DA;Lo;0;L;;;;;N;;;;; -A10A;YI SYLLABLE DAP;Lo;0;L;;;;;N;;;;; -A10B;YI SYLLABLE DUOX;Lo;0;L;;;;;N;;;;; -A10C;YI SYLLABLE DUO;Lo;0;L;;;;;N;;;;; -A10D;YI SYLLABLE DOT;Lo;0;L;;;;;N;;;;; -A10E;YI SYLLABLE DOX;Lo;0;L;;;;;N;;;;; -A10F;YI SYLLABLE DO;Lo;0;L;;;;;N;;;;; -A110;YI SYLLABLE DOP;Lo;0;L;;;;;N;;;;; -A111;YI SYLLABLE DEX;Lo;0;L;;;;;N;;;;; -A112;YI SYLLABLE DE;Lo;0;L;;;;;N;;;;; -A113;YI SYLLABLE DEP;Lo;0;L;;;;;N;;;;; -A114;YI SYLLABLE DUT;Lo;0;L;;;;;N;;;;; -A115;YI SYLLABLE DUX;Lo;0;L;;;;;N;;;;; -A116;YI SYLLABLE DU;Lo;0;L;;;;;N;;;;; -A117;YI SYLLABLE DUP;Lo;0;L;;;;;N;;;;; -A118;YI SYLLABLE DURX;Lo;0;L;;;;;N;;;;; -A119;YI SYLLABLE DUR;Lo;0;L;;;;;N;;;;; -A11A;YI SYLLABLE TIT;Lo;0;L;;;;;N;;;;; -A11B;YI SYLLABLE TIX;Lo;0;L;;;;;N;;;;; -A11C;YI SYLLABLE TI;Lo;0;L;;;;;N;;;;; -A11D;YI SYLLABLE TIP;Lo;0;L;;;;;N;;;;; -A11E;YI SYLLABLE TIEX;Lo;0;L;;;;;N;;;;; -A11F;YI SYLLABLE TIE;Lo;0;L;;;;;N;;;;; -A120;YI SYLLABLE TIEP;Lo;0;L;;;;;N;;;;; -A121;YI SYLLABLE TAT;Lo;0;L;;;;;N;;;;; -A122;YI SYLLABLE TAX;Lo;0;L;;;;;N;;;;; -A123;YI SYLLABLE TA;Lo;0;L;;;;;N;;;;; -A124;YI SYLLABLE TAP;Lo;0;L;;;;;N;;;;; -A125;YI SYLLABLE TUOT;Lo;0;L;;;;;N;;;;; -A126;YI SYLLABLE TUOX;Lo;0;L;;;;;N;;;;; -A127;YI SYLLABLE TUO;Lo;0;L;;;;;N;;;;; -A128;YI SYLLABLE TUOP;Lo;0;L;;;;;N;;;;; -A129;YI SYLLABLE TOT;Lo;0;L;;;;;N;;;;; -A12A;YI SYLLABLE TOX;Lo;0;L;;;;;N;;;;; -A12B;YI SYLLABLE TO;Lo;0;L;;;;;N;;;;; -A12C;YI SYLLABLE TOP;Lo;0;L;;;;;N;;;;; -A12D;YI SYLLABLE TEX;Lo;0;L;;;;;N;;;;; -A12E;YI SYLLABLE TE;Lo;0;L;;;;;N;;;;; -A12F;YI SYLLABLE TEP;Lo;0;L;;;;;N;;;;; -A130;YI SYLLABLE TUT;Lo;0;L;;;;;N;;;;; -A131;YI SYLLABLE TUX;Lo;0;L;;;;;N;;;;; -A132;YI SYLLABLE TU;Lo;0;L;;;;;N;;;;; -A133;YI SYLLABLE TUP;Lo;0;L;;;;;N;;;;; -A134;YI SYLLABLE TURX;Lo;0;L;;;;;N;;;;; -A135;YI SYLLABLE TUR;Lo;0;L;;;;;N;;;;; -A136;YI SYLLABLE DDIT;Lo;0;L;;;;;N;;;;; -A137;YI SYLLABLE DDIX;Lo;0;L;;;;;N;;;;; -A138;YI SYLLABLE DDI;Lo;0;L;;;;;N;;;;; -A139;YI SYLLABLE DDIP;Lo;0;L;;;;;N;;;;; -A13A;YI SYLLABLE DDIEX;Lo;0;L;;;;;N;;;;; -A13B;YI SYLLABLE DDIE;Lo;0;L;;;;;N;;;;; -A13C;YI SYLLABLE DDIEP;Lo;0;L;;;;;N;;;;; -A13D;YI SYLLABLE DDAT;Lo;0;L;;;;;N;;;;; -A13E;YI SYLLABLE DDAX;Lo;0;L;;;;;N;;;;; -A13F;YI SYLLABLE DDA;Lo;0;L;;;;;N;;;;; -A140;YI SYLLABLE DDAP;Lo;0;L;;;;;N;;;;; -A141;YI SYLLABLE DDUOX;Lo;0;L;;;;;N;;;;; -A142;YI SYLLABLE DDUO;Lo;0;L;;;;;N;;;;; -A143;YI SYLLABLE DDUOP;Lo;0;L;;;;;N;;;;; -A144;YI SYLLABLE DDOT;Lo;0;L;;;;;N;;;;; -A145;YI SYLLABLE DDOX;Lo;0;L;;;;;N;;;;; -A146;YI SYLLABLE DDO;Lo;0;L;;;;;N;;;;; -A147;YI SYLLABLE DDOP;Lo;0;L;;;;;N;;;;; -A148;YI SYLLABLE DDEX;Lo;0;L;;;;;N;;;;; -A149;YI SYLLABLE DDE;Lo;0;L;;;;;N;;;;; -A14A;YI SYLLABLE DDEP;Lo;0;L;;;;;N;;;;; -A14B;YI SYLLABLE DDUT;Lo;0;L;;;;;N;;;;; -A14C;YI SYLLABLE DDUX;Lo;0;L;;;;;N;;;;; -A14D;YI SYLLABLE DDU;Lo;0;L;;;;;N;;;;; -A14E;YI SYLLABLE DDUP;Lo;0;L;;;;;N;;;;; -A14F;YI SYLLABLE DDURX;Lo;0;L;;;;;N;;;;; -A150;YI SYLLABLE DDUR;Lo;0;L;;;;;N;;;;; -A151;YI SYLLABLE NDIT;Lo;0;L;;;;;N;;;;; -A152;YI SYLLABLE NDIX;Lo;0;L;;;;;N;;;;; -A153;YI SYLLABLE NDI;Lo;0;L;;;;;N;;;;; -A154;YI SYLLABLE NDIP;Lo;0;L;;;;;N;;;;; -A155;YI SYLLABLE NDIEX;Lo;0;L;;;;;N;;;;; -A156;YI SYLLABLE NDIE;Lo;0;L;;;;;N;;;;; -A157;YI SYLLABLE NDAT;Lo;0;L;;;;;N;;;;; -A158;YI SYLLABLE NDAX;Lo;0;L;;;;;N;;;;; -A159;YI SYLLABLE NDA;Lo;0;L;;;;;N;;;;; -A15A;YI SYLLABLE NDAP;Lo;0;L;;;;;N;;;;; -A15B;YI SYLLABLE NDOT;Lo;0;L;;;;;N;;;;; -A15C;YI SYLLABLE NDOX;Lo;0;L;;;;;N;;;;; -A15D;YI SYLLABLE NDO;Lo;0;L;;;;;N;;;;; -A15E;YI SYLLABLE NDOP;Lo;0;L;;;;;N;;;;; -A15F;YI SYLLABLE NDEX;Lo;0;L;;;;;N;;;;; -A160;YI SYLLABLE NDE;Lo;0;L;;;;;N;;;;; -A161;YI SYLLABLE NDEP;Lo;0;L;;;;;N;;;;; -A162;YI SYLLABLE NDUT;Lo;0;L;;;;;N;;;;; -A163;YI SYLLABLE NDUX;Lo;0;L;;;;;N;;;;; -A164;YI SYLLABLE NDU;Lo;0;L;;;;;N;;;;; -A165;YI SYLLABLE NDUP;Lo;0;L;;;;;N;;;;; -A166;YI SYLLABLE NDURX;Lo;0;L;;;;;N;;;;; -A167;YI SYLLABLE NDUR;Lo;0;L;;;;;N;;;;; -A168;YI SYLLABLE HNIT;Lo;0;L;;;;;N;;;;; -A169;YI SYLLABLE HNIX;Lo;0;L;;;;;N;;;;; -A16A;YI SYLLABLE HNI;Lo;0;L;;;;;N;;;;; -A16B;YI SYLLABLE HNIP;Lo;0;L;;;;;N;;;;; -A16C;YI SYLLABLE HNIET;Lo;0;L;;;;;N;;;;; -A16D;YI SYLLABLE HNIEX;Lo;0;L;;;;;N;;;;; -A16E;YI SYLLABLE HNIE;Lo;0;L;;;;;N;;;;; -A16F;YI SYLLABLE HNIEP;Lo;0;L;;;;;N;;;;; -A170;YI SYLLABLE HNAT;Lo;0;L;;;;;N;;;;; -A171;YI SYLLABLE HNAX;Lo;0;L;;;;;N;;;;; -A172;YI SYLLABLE HNA;Lo;0;L;;;;;N;;;;; -A173;YI SYLLABLE HNAP;Lo;0;L;;;;;N;;;;; -A174;YI SYLLABLE HNUOX;Lo;0;L;;;;;N;;;;; -A175;YI SYLLABLE HNUO;Lo;0;L;;;;;N;;;;; -A176;YI SYLLABLE HNOT;Lo;0;L;;;;;N;;;;; -A177;YI SYLLABLE HNOX;Lo;0;L;;;;;N;;;;; -A178;YI SYLLABLE HNOP;Lo;0;L;;;;;N;;;;; -A179;YI SYLLABLE HNEX;Lo;0;L;;;;;N;;;;; -A17A;YI SYLLABLE HNE;Lo;0;L;;;;;N;;;;; -A17B;YI SYLLABLE HNEP;Lo;0;L;;;;;N;;;;; -A17C;YI SYLLABLE HNUT;Lo;0;L;;;;;N;;;;; -A17D;YI SYLLABLE NIT;Lo;0;L;;;;;N;;;;; -A17E;YI SYLLABLE NIX;Lo;0;L;;;;;N;;;;; -A17F;YI SYLLABLE NI;Lo;0;L;;;;;N;;;;; -A180;YI SYLLABLE NIP;Lo;0;L;;;;;N;;;;; -A181;YI SYLLABLE NIEX;Lo;0;L;;;;;N;;;;; -A182;YI SYLLABLE NIE;Lo;0;L;;;;;N;;;;; -A183;YI SYLLABLE NIEP;Lo;0;L;;;;;N;;;;; -A184;YI SYLLABLE NAX;Lo;0;L;;;;;N;;;;; -A185;YI SYLLABLE NA;Lo;0;L;;;;;N;;;;; -A186;YI SYLLABLE NAP;Lo;0;L;;;;;N;;;;; -A187;YI SYLLABLE NUOX;Lo;0;L;;;;;N;;;;; -A188;YI SYLLABLE NUO;Lo;0;L;;;;;N;;;;; -A189;YI SYLLABLE NUOP;Lo;0;L;;;;;N;;;;; -A18A;YI SYLLABLE NOT;Lo;0;L;;;;;N;;;;; -A18B;YI SYLLABLE NOX;Lo;0;L;;;;;N;;;;; -A18C;YI SYLLABLE NO;Lo;0;L;;;;;N;;;;; -A18D;YI SYLLABLE NOP;Lo;0;L;;;;;N;;;;; -A18E;YI SYLLABLE NEX;Lo;0;L;;;;;N;;;;; -A18F;YI SYLLABLE NE;Lo;0;L;;;;;N;;;;; -A190;YI SYLLABLE NEP;Lo;0;L;;;;;N;;;;; -A191;YI SYLLABLE NUT;Lo;0;L;;;;;N;;;;; -A192;YI SYLLABLE NUX;Lo;0;L;;;;;N;;;;; -A193;YI SYLLABLE NU;Lo;0;L;;;;;N;;;;; -A194;YI SYLLABLE NUP;Lo;0;L;;;;;N;;;;; -A195;YI SYLLABLE NURX;Lo;0;L;;;;;N;;;;; -A196;YI SYLLABLE NUR;Lo;0;L;;;;;N;;;;; -A197;YI SYLLABLE HLIT;Lo;0;L;;;;;N;;;;; -A198;YI SYLLABLE HLIX;Lo;0;L;;;;;N;;;;; -A199;YI SYLLABLE HLI;Lo;0;L;;;;;N;;;;; -A19A;YI SYLLABLE HLIP;Lo;0;L;;;;;N;;;;; -A19B;YI SYLLABLE HLIEX;Lo;0;L;;;;;N;;;;; -A19C;YI SYLLABLE HLIE;Lo;0;L;;;;;N;;;;; -A19D;YI SYLLABLE HLIEP;Lo;0;L;;;;;N;;;;; -A19E;YI SYLLABLE HLAT;Lo;0;L;;;;;N;;;;; -A19F;YI SYLLABLE HLAX;Lo;0;L;;;;;N;;;;; -A1A0;YI SYLLABLE HLA;Lo;0;L;;;;;N;;;;; -A1A1;YI SYLLABLE HLAP;Lo;0;L;;;;;N;;;;; -A1A2;YI SYLLABLE HLUOX;Lo;0;L;;;;;N;;;;; -A1A3;YI SYLLABLE HLUO;Lo;0;L;;;;;N;;;;; -A1A4;YI SYLLABLE HLUOP;Lo;0;L;;;;;N;;;;; -A1A5;YI SYLLABLE HLOX;Lo;0;L;;;;;N;;;;; -A1A6;YI SYLLABLE HLO;Lo;0;L;;;;;N;;;;; -A1A7;YI SYLLABLE HLOP;Lo;0;L;;;;;N;;;;; -A1A8;YI SYLLABLE HLEX;Lo;0;L;;;;;N;;;;; -A1A9;YI SYLLABLE HLE;Lo;0;L;;;;;N;;;;; -A1AA;YI SYLLABLE HLEP;Lo;0;L;;;;;N;;;;; -A1AB;YI SYLLABLE HLUT;Lo;0;L;;;;;N;;;;; -A1AC;YI SYLLABLE HLUX;Lo;0;L;;;;;N;;;;; -A1AD;YI SYLLABLE HLU;Lo;0;L;;;;;N;;;;; -A1AE;YI SYLLABLE HLUP;Lo;0;L;;;;;N;;;;; -A1AF;YI SYLLABLE HLURX;Lo;0;L;;;;;N;;;;; -A1B0;YI SYLLABLE HLUR;Lo;0;L;;;;;N;;;;; -A1B1;YI SYLLABLE HLYT;Lo;0;L;;;;;N;;;;; -A1B2;YI SYLLABLE HLYX;Lo;0;L;;;;;N;;;;; -A1B3;YI SYLLABLE HLY;Lo;0;L;;;;;N;;;;; -A1B4;YI SYLLABLE HLYP;Lo;0;L;;;;;N;;;;; -A1B5;YI SYLLABLE HLYRX;Lo;0;L;;;;;N;;;;; -A1B6;YI SYLLABLE HLYR;Lo;0;L;;;;;N;;;;; -A1B7;YI SYLLABLE LIT;Lo;0;L;;;;;N;;;;; -A1B8;YI SYLLABLE LIX;Lo;0;L;;;;;N;;;;; -A1B9;YI SYLLABLE LI;Lo;0;L;;;;;N;;;;; -A1BA;YI SYLLABLE LIP;Lo;0;L;;;;;N;;;;; -A1BB;YI SYLLABLE LIET;Lo;0;L;;;;;N;;;;; -A1BC;YI SYLLABLE LIEX;Lo;0;L;;;;;N;;;;; -A1BD;YI SYLLABLE LIE;Lo;0;L;;;;;N;;;;; -A1BE;YI SYLLABLE LIEP;Lo;0;L;;;;;N;;;;; -A1BF;YI SYLLABLE LAT;Lo;0;L;;;;;N;;;;; -A1C0;YI SYLLABLE LAX;Lo;0;L;;;;;N;;;;; -A1C1;YI SYLLABLE LA;Lo;0;L;;;;;N;;;;; -A1C2;YI SYLLABLE LAP;Lo;0;L;;;;;N;;;;; -A1C3;YI SYLLABLE LUOT;Lo;0;L;;;;;N;;;;; -A1C4;YI SYLLABLE LUOX;Lo;0;L;;;;;N;;;;; -A1C5;YI SYLLABLE LUO;Lo;0;L;;;;;N;;;;; -A1C6;YI SYLLABLE LUOP;Lo;0;L;;;;;N;;;;; -A1C7;YI SYLLABLE LOT;Lo;0;L;;;;;N;;;;; -A1C8;YI SYLLABLE LOX;Lo;0;L;;;;;N;;;;; -A1C9;YI SYLLABLE LO;Lo;0;L;;;;;N;;;;; -A1CA;YI SYLLABLE LOP;Lo;0;L;;;;;N;;;;; -A1CB;YI SYLLABLE LEX;Lo;0;L;;;;;N;;;;; -A1CC;YI SYLLABLE LE;Lo;0;L;;;;;N;;;;; -A1CD;YI SYLLABLE LEP;Lo;0;L;;;;;N;;;;; -A1CE;YI SYLLABLE LUT;Lo;0;L;;;;;N;;;;; -A1CF;YI SYLLABLE LUX;Lo;0;L;;;;;N;;;;; -A1D0;YI SYLLABLE LU;Lo;0;L;;;;;N;;;;; -A1D1;YI SYLLABLE LUP;Lo;0;L;;;;;N;;;;; -A1D2;YI SYLLABLE LURX;Lo;0;L;;;;;N;;;;; -A1D3;YI SYLLABLE LUR;Lo;0;L;;;;;N;;;;; -A1D4;YI SYLLABLE LYT;Lo;0;L;;;;;N;;;;; -A1D5;YI SYLLABLE LYX;Lo;0;L;;;;;N;;;;; -A1D6;YI SYLLABLE LY;Lo;0;L;;;;;N;;;;; -A1D7;YI SYLLABLE LYP;Lo;0;L;;;;;N;;;;; -A1D8;YI SYLLABLE LYRX;Lo;0;L;;;;;N;;;;; -A1D9;YI SYLLABLE LYR;Lo;0;L;;;;;N;;;;; -A1DA;YI SYLLABLE GIT;Lo;0;L;;;;;N;;;;; -A1DB;YI SYLLABLE GIX;Lo;0;L;;;;;N;;;;; -A1DC;YI SYLLABLE GI;Lo;0;L;;;;;N;;;;; -A1DD;YI SYLLABLE GIP;Lo;0;L;;;;;N;;;;; -A1DE;YI SYLLABLE GIET;Lo;0;L;;;;;N;;;;; -A1DF;YI SYLLABLE GIEX;Lo;0;L;;;;;N;;;;; -A1E0;YI SYLLABLE GIE;Lo;0;L;;;;;N;;;;; -A1E1;YI SYLLABLE GIEP;Lo;0;L;;;;;N;;;;; -A1E2;YI SYLLABLE GAT;Lo;0;L;;;;;N;;;;; -A1E3;YI SYLLABLE GAX;Lo;0;L;;;;;N;;;;; -A1E4;YI SYLLABLE GA;Lo;0;L;;;;;N;;;;; -A1E5;YI SYLLABLE GAP;Lo;0;L;;;;;N;;;;; -A1E6;YI SYLLABLE GUOT;Lo;0;L;;;;;N;;;;; -A1E7;YI SYLLABLE GUOX;Lo;0;L;;;;;N;;;;; -A1E8;YI SYLLABLE GUO;Lo;0;L;;;;;N;;;;; -A1E9;YI SYLLABLE GUOP;Lo;0;L;;;;;N;;;;; -A1EA;YI SYLLABLE GOT;Lo;0;L;;;;;N;;;;; -A1EB;YI SYLLABLE GOX;Lo;0;L;;;;;N;;;;; -A1EC;YI SYLLABLE GO;Lo;0;L;;;;;N;;;;; -A1ED;YI SYLLABLE GOP;Lo;0;L;;;;;N;;;;; -A1EE;YI SYLLABLE GET;Lo;0;L;;;;;N;;;;; -A1EF;YI SYLLABLE GEX;Lo;0;L;;;;;N;;;;; -A1F0;YI SYLLABLE GE;Lo;0;L;;;;;N;;;;; -A1F1;YI SYLLABLE GEP;Lo;0;L;;;;;N;;;;; -A1F2;YI SYLLABLE GUT;Lo;0;L;;;;;N;;;;; -A1F3;YI SYLLABLE GUX;Lo;0;L;;;;;N;;;;; -A1F4;YI SYLLABLE GU;Lo;0;L;;;;;N;;;;; -A1F5;YI SYLLABLE GUP;Lo;0;L;;;;;N;;;;; -A1F6;YI SYLLABLE GURX;Lo;0;L;;;;;N;;;;; -A1F7;YI SYLLABLE GUR;Lo;0;L;;;;;N;;;;; -A1F8;YI SYLLABLE KIT;Lo;0;L;;;;;N;;;;; -A1F9;YI SYLLABLE KIX;Lo;0;L;;;;;N;;;;; -A1FA;YI SYLLABLE KI;Lo;0;L;;;;;N;;;;; -A1FB;YI SYLLABLE KIP;Lo;0;L;;;;;N;;;;; -A1FC;YI SYLLABLE KIEX;Lo;0;L;;;;;N;;;;; -A1FD;YI SYLLABLE KIE;Lo;0;L;;;;;N;;;;; -A1FE;YI SYLLABLE KIEP;Lo;0;L;;;;;N;;;;; -A1FF;YI SYLLABLE KAT;Lo;0;L;;;;;N;;;;; -A200;YI SYLLABLE KAX;Lo;0;L;;;;;N;;;;; -A201;YI SYLLABLE KA;Lo;0;L;;;;;N;;;;; -A202;YI SYLLABLE KAP;Lo;0;L;;;;;N;;;;; -A203;YI SYLLABLE KUOX;Lo;0;L;;;;;N;;;;; -A204;YI SYLLABLE KUO;Lo;0;L;;;;;N;;;;; -A205;YI SYLLABLE KUOP;Lo;0;L;;;;;N;;;;; -A206;YI SYLLABLE KOT;Lo;0;L;;;;;N;;;;; -A207;YI SYLLABLE KOX;Lo;0;L;;;;;N;;;;; -A208;YI SYLLABLE KO;Lo;0;L;;;;;N;;;;; -A209;YI SYLLABLE KOP;Lo;0;L;;;;;N;;;;; -A20A;YI SYLLABLE KET;Lo;0;L;;;;;N;;;;; -A20B;YI SYLLABLE KEX;Lo;0;L;;;;;N;;;;; -A20C;YI SYLLABLE KE;Lo;0;L;;;;;N;;;;; -A20D;YI SYLLABLE KEP;Lo;0;L;;;;;N;;;;; -A20E;YI SYLLABLE KUT;Lo;0;L;;;;;N;;;;; -A20F;YI SYLLABLE KUX;Lo;0;L;;;;;N;;;;; -A210;YI SYLLABLE KU;Lo;0;L;;;;;N;;;;; -A211;YI SYLLABLE KUP;Lo;0;L;;;;;N;;;;; -A212;YI SYLLABLE KURX;Lo;0;L;;;;;N;;;;; -A213;YI SYLLABLE KUR;Lo;0;L;;;;;N;;;;; -A214;YI SYLLABLE GGIT;Lo;0;L;;;;;N;;;;; -A215;YI SYLLABLE GGIX;Lo;0;L;;;;;N;;;;; -A216;YI SYLLABLE GGI;Lo;0;L;;;;;N;;;;; -A217;YI SYLLABLE GGIEX;Lo;0;L;;;;;N;;;;; -A218;YI SYLLABLE GGIE;Lo;0;L;;;;;N;;;;; -A219;YI SYLLABLE GGIEP;Lo;0;L;;;;;N;;;;; -A21A;YI SYLLABLE GGAT;Lo;0;L;;;;;N;;;;; -A21B;YI SYLLABLE GGAX;Lo;0;L;;;;;N;;;;; -A21C;YI SYLLABLE GGA;Lo;0;L;;;;;N;;;;; -A21D;YI SYLLABLE GGAP;Lo;0;L;;;;;N;;;;; -A21E;YI SYLLABLE GGUOT;Lo;0;L;;;;;N;;;;; -A21F;YI SYLLABLE GGUOX;Lo;0;L;;;;;N;;;;; -A220;YI SYLLABLE GGUO;Lo;0;L;;;;;N;;;;; -A221;YI SYLLABLE GGUOP;Lo;0;L;;;;;N;;;;; -A222;YI SYLLABLE GGOT;Lo;0;L;;;;;N;;;;; -A223;YI SYLLABLE GGOX;Lo;0;L;;;;;N;;;;; -A224;YI SYLLABLE GGO;Lo;0;L;;;;;N;;;;; -A225;YI SYLLABLE GGOP;Lo;0;L;;;;;N;;;;; -A226;YI SYLLABLE GGET;Lo;0;L;;;;;N;;;;; -A227;YI SYLLABLE GGEX;Lo;0;L;;;;;N;;;;; -A228;YI SYLLABLE GGE;Lo;0;L;;;;;N;;;;; -A229;YI SYLLABLE GGEP;Lo;0;L;;;;;N;;;;; -A22A;YI SYLLABLE GGUT;Lo;0;L;;;;;N;;;;; -A22B;YI SYLLABLE GGUX;Lo;0;L;;;;;N;;;;; -A22C;YI SYLLABLE GGU;Lo;0;L;;;;;N;;;;; -A22D;YI SYLLABLE GGUP;Lo;0;L;;;;;N;;;;; -A22E;YI SYLLABLE GGURX;Lo;0;L;;;;;N;;;;; -A22F;YI SYLLABLE GGUR;Lo;0;L;;;;;N;;;;; -A230;YI SYLLABLE MGIEX;Lo;0;L;;;;;N;;;;; -A231;YI SYLLABLE MGIE;Lo;0;L;;;;;N;;;;; -A232;YI SYLLABLE MGAT;Lo;0;L;;;;;N;;;;; -A233;YI SYLLABLE MGAX;Lo;0;L;;;;;N;;;;; -A234;YI SYLLABLE MGA;Lo;0;L;;;;;N;;;;; -A235;YI SYLLABLE MGAP;Lo;0;L;;;;;N;;;;; -A236;YI SYLLABLE MGUOX;Lo;0;L;;;;;N;;;;; -A237;YI SYLLABLE MGUO;Lo;0;L;;;;;N;;;;; -A238;YI SYLLABLE MGUOP;Lo;0;L;;;;;N;;;;; -A239;YI SYLLABLE MGOT;Lo;0;L;;;;;N;;;;; -A23A;YI SYLLABLE MGOX;Lo;0;L;;;;;N;;;;; -A23B;YI SYLLABLE MGO;Lo;0;L;;;;;N;;;;; -A23C;YI SYLLABLE MGOP;Lo;0;L;;;;;N;;;;; -A23D;YI SYLLABLE MGEX;Lo;0;L;;;;;N;;;;; -A23E;YI SYLLABLE MGE;Lo;0;L;;;;;N;;;;; -A23F;YI SYLLABLE MGEP;Lo;0;L;;;;;N;;;;; -A240;YI SYLLABLE MGUT;Lo;0;L;;;;;N;;;;; -A241;YI SYLLABLE MGUX;Lo;0;L;;;;;N;;;;; -A242;YI SYLLABLE MGU;Lo;0;L;;;;;N;;;;; -A243;YI SYLLABLE MGUP;Lo;0;L;;;;;N;;;;; -A244;YI SYLLABLE MGURX;Lo;0;L;;;;;N;;;;; -A245;YI SYLLABLE MGUR;Lo;0;L;;;;;N;;;;; -A246;YI SYLLABLE HXIT;Lo;0;L;;;;;N;;;;; -A247;YI SYLLABLE HXIX;Lo;0;L;;;;;N;;;;; -A248;YI SYLLABLE HXI;Lo;0;L;;;;;N;;;;; -A249;YI SYLLABLE HXIP;Lo;0;L;;;;;N;;;;; -A24A;YI SYLLABLE HXIET;Lo;0;L;;;;;N;;;;; -A24B;YI SYLLABLE HXIEX;Lo;0;L;;;;;N;;;;; -A24C;YI SYLLABLE HXIE;Lo;0;L;;;;;N;;;;; -A24D;YI SYLLABLE HXIEP;Lo;0;L;;;;;N;;;;; -A24E;YI SYLLABLE HXAT;Lo;0;L;;;;;N;;;;; -A24F;YI SYLLABLE HXAX;Lo;0;L;;;;;N;;;;; -A250;YI SYLLABLE HXA;Lo;0;L;;;;;N;;;;; -A251;YI SYLLABLE HXAP;Lo;0;L;;;;;N;;;;; -A252;YI SYLLABLE HXUOT;Lo;0;L;;;;;N;;;;; -A253;YI SYLLABLE HXUOX;Lo;0;L;;;;;N;;;;; -A254;YI SYLLABLE HXUO;Lo;0;L;;;;;N;;;;; -A255;YI SYLLABLE HXUOP;Lo;0;L;;;;;N;;;;; -A256;YI SYLLABLE HXOT;Lo;0;L;;;;;N;;;;; -A257;YI SYLLABLE HXOX;Lo;0;L;;;;;N;;;;; -A258;YI SYLLABLE HXO;Lo;0;L;;;;;N;;;;; -A259;YI SYLLABLE HXOP;Lo;0;L;;;;;N;;;;; -A25A;YI SYLLABLE HXEX;Lo;0;L;;;;;N;;;;; -A25B;YI SYLLABLE HXE;Lo;0;L;;;;;N;;;;; -A25C;YI SYLLABLE HXEP;Lo;0;L;;;;;N;;;;; -A25D;YI SYLLABLE NGIEX;Lo;0;L;;;;;N;;;;; -A25E;YI SYLLABLE NGIE;Lo;0;L;;;;;N;;;;; -A25F;YI SYLLABLE NGIEP;Lo;0;L;;;;;N;;;;; -A260;YI SYLLABLE NGAT;Lo;0;L;;;;;N;;;;; -A261;YI SYLLABLE NGAX;Lo;0;L;;;;;N;;;;; -A262;YI SYLLABLE NGA;Lo;0;L;;;;;N;;;;; -A263;YI SYLLABLE NGAP;Lo;0;L;;;;;N;;;;; -A264;YI SYLLABLE NGUOT;Lo;0;L;;;;;N;;;;; -A265;YI SYLLABLE NGUOX;Lo;0;L;;;;;N;;;;; -A266;YI SYLLABLE NGUO;Lo;0;L;;;;;N;;;;; -A267;YI SYLLABLE NGOT;Lo;0;L;;;;;N;;;;; -A268;YI SYLLABLE NGOX;Lo;0;L;;;;;N;;;;; -A269;YI SYLLABLE NGO;Lo;0;L;;;;;N;;;;; -A26A;YI SYLLABLE NGOP;Lo;0;L;;;;;N;;;;; -A26B;YI SYLLABLE NGEX;Lo;0;L;;;;;N;;;;; -A26C;YI SYLLABLE NGE;Lo;0;L;;;;;N;;;;; -A26D;YI SYLLABLE NGEP;Lo;0;L;;;;;N;;;;; -A26E;YI SYLLABLE HIT;Lo;0;L;;;;;N;;;;; -A26F;YI SYLLABLE HIEX;Lo;0;L;;;;;N;;;;; -A270;YI SYLLABLE HIE;Lo;0;L;;;;;N;;;;; -A271;YI SYLLABLE HAT;Lo;0;L;;;;;N;;;;; -A272;YI SYLLABLE HAX;Lo;0;L;;;;;N;;;;; -A273;YI SYLLABLE HA;Lo;0;L;;;;;N;;;;; -A274;YI SYLLABLE HAP;Lo;0;L;;;;;N;;;;; -A275;YI SYLLABLE HUOT;Lo;0;L;;;;;N;;;;; -A276;YI SYLLABLE HUOX;Lo;0;L;;;;;N;;;;; -A277;YI SYLLABLE HUO;Lo;0;L;;;;;N;;;;; -A278;YI SYLLABLE HUOP;Lo;0;L;;;;;N;;;;; -A279;YI SYLLABLE HOT;Lo;0;L;;;;;N;;;;; -A27A;YI SYLLABLE HOX;Lo;0;L;;;;;N;;;;; -A27B;YI SYLLABLE HO;Lo;0;L;;;;;N;;;;; -A27C;YI SYLLABLE HOP;Lo;0;L;;;;;N;;;;; -A27D;YI SYLLABLE HEX;Lo;0;L;;;;;N;;;;; -A27E;YI SYLLABLE HE;Lo;0;L;;;;;N;;;;; -A27F;YI SYLLABLE HEP;Lo;0;L;;;;;N;;;;; -A280;YI SYLLABLE WAT;Lo;0;L;;;;;N;;;;; -A281;YI SYLLABLE WAX;Lo;0;L;;;;;N;;;;; -A282;YI SYLLABLE WA;Lo;0;L;;;;;N;;;;; -A283;YI SYLLABLE WAP;Lo;0;L;;;;;N;;;;; -A284;YI SYLLABLE WUOX;Lo;0;L;;;;;N;;;;; -A285;YI SYLLABLE WUO;Lo;0;L;;;;;N;;;;; -A286;YI SYLLABLE WUOP;Lo;0;L;;;;;N;;;;; -A287;YI SYLLABLE WOX;Lo;0;L;;;;;N;;;;; -A288;YI SYLLABLE WO;Lo;0;L;;;;;N;;;;; -A289;YI SYLLABLE WOP;Lo;0;L;;;;;N;;;;; -A28A;YI SYLLABLE WEX;Lo;0;L;;;;;N;;;;; -A28B;YI SYLLABLE WE;Lo;0;L;;;;;N;;;;; -A28C;YI SYLLABLE WEP;Lo;0;L;;;;;N;;;;; -A28D;YI SYLLABLE ZIT;Lo;0;L;;;;;N;;;;; -A28E;YI SYLLABLE ZIX;Lo;0;L;;;;;N;;;;; -A28F;YI SYLLABLE ZI;Lo;0;L;;;;;N;;;;; -A290;YI SYLLABLE ZIP;Lo;0;L;;;;;N;;;;; -A291;YI SYLLABLE ZIEX;Lo;0;L;;;;;N;;;;; -A292;YI SYLLABLE ZIE;Lo;0;L;;;;;N;;;;; -A293;YI SYLLABLE ZIEP;Lo;0;L;;;;;N;;;;; -A294;YI SYLLABLE ZAT;Lo;0;L;;;;;N;;;;; -A295;YI SYLLABLE ZAX;Lo;0;L;;;;;N;;;;; -A296;YI SYLLABLE ZA;Lo;0;L;;;;;N;;;;; -A297;YI SYLLABLE ZAP;Lo;0;L;;;;;N;;;;; -A298;YI SYLLABLE ZUOX;Lo;0;L;;;;;N;;;;; -A299;YI SYLLABLE ZUO;Lo;0;L;;;;;N;;;;; -A29A;YI SYLLABLE ZUOP;Lo;0;L;;;;;N;;;;; -A29B;YI SYLLABLE ZOT;Lo;0;L;;;;;N;;;;; -A29C;YI SYLLABLE ZOX;Lo;0;L;;;;;N;;;;; -A29D;YI SYLLABLE ZO;Lo;0;L;;;;;N;;;;; -A29E;YI SYLLABLE ZOP;Lo;0;L;;;;;N;;;;; -A29F;YI SYLLABLE ZEX;Lo;0;L;;;;;N;;;;; -A2A0;YI SYLLABLE ZE;Lo;0;L;;;;;N;;;;; -A2A1;YI SYLLABLE ZEP;Lo;0;L;;;;;N;;;;; -A2A2;YI SYLLABLE ZUT;Lo;0;L;;;;;N;;;;; -A2A3;YI SYLLABLE ZUX;Lo;0;L;;;;;N;;;;; -A2A4;YI SYLLABLE ZU;Lo;0;L;;;;;N;;;;; -A2A5;YI SYLLABLE ZUP;Lo;0;L;;;;;N;;;;; -A2A6;YI SYLLABLE ZURX;Lo;0;L;;;;;N;;;;; -A2A7;YI SYLLABLE ZUR;Lo;0;L;;;;;N;;;;; -A2A8;YI SYLLABLE ZYT;Lo;0;L;;;;;N;;;;; -A2A9;YI SYLLABLE ZYX;Lo;0;L;;;;;N;;;;; -A2AA;YI SYLLABLE ZY;Lo;0;L;;;;;N;;;;; -A2AB;YI SYLLABLE ZYP;Lo;0;L;;;;;N;;;;; -A2AC;YI SYLLABLE ZYRX;Lo;0;L;;;;;N;;;;; -A2AD;YI SYLLABLE ZYR;Lo;0;L;;;;;N;;;;; -A2AE;YI SYLLABLE CIT;Lo;0;L;;;;;N;;;;; -A2AF;YI SYLLABLE CIX;Lo;0;L;;;;;N;;;;; -A2B0;YI SYLLABLE CI;Lo;0;L;;;;;N;;;;; -A2B1;YI SYLLABLE CIP;Lo;0;L;;;;;N;;;;; -A2B2;YI SYLLABLE CIET;Lo;0;L;;;;;N;;;;; -A2B3;YI SYLLABLE CIEX;Lo;0;L;;;;;N;;;;; -A2B4;YI SYLLABLE CIE;Lo;0;L;;;;;N;;;;; -A2B5;YI SYLLABLE CIEP;Lo;0;L;;;;;N;;;;; -A2B6;YI SYLLABLE CAT;Lo;0;L;;;;;N;;;;; -A2B7;YI SYLLABLE CAX;Lo;0;L;;;;;N;;;;; -A2B8;YI SYLLABLE CA;Lo;0;L;;;;;N;;;;; -A2B9;YI SYLLABLE CAP;Lo;0;L;;;;;N;;;;; -A2BA;YI SYLLABLE CUOX;Lo;0;L;;;;;N;;;;; -A2BB;YI SYLLABLE CUO;Lo;0;L;;;;;N;;;;; -A2BC;YI SYLLABLE CUOP;Lo;0;L;;;;;N;;;;; -A2BD;YI SYLLABLE COT;Lo;0;L;;;;;N;;;;; -A2BE;YI SYLLABLE COX;Lo;0;L;;;;;N;;;;; -A2BF;YI SYLLABLE CO;Lo;0;L;;;;;N;;;;; -A2C0;YI SYLLABLE COP;Lo;0;L;;;;;N;;;;; -A2C1;YI SYLLABLE CEX;Lo;0;L;;;;;N;;;;; -A2C2;YI SYLLABLE CE;Lo;0;L;;;;;N;;;;; -A2C3;YI SYLLABLE CEP;Lo;0;L;;;;;N;;;;; -A2C4;YI SYLLABLE CUT;Lo;0;L;;;;;N;;;;; -A2C5;YI SYLLABLE CUX;Lo;0;L;;;;;N;;;;; -A2C6;YI SYLLABLE CU;Lo;0;L;;;;;N;;;;; -A2C7;YI SYLLABLE CUP;Lo;0;L;;;;;N;;;;; -A2C8;YI SYLLABLE CURX;Lo;0;L;;;;;N;;;;; -A2C9;YI SYLLABLE CUR;Lo;0;L;;;;;N;;;;; -A2CA;YI SYLLABLE CYT;Lo;0;L;;;;;N;;;;; -A2CB;YI SYLLABLE CYX;Lo;0;L;;;;;N;;;;; -A2CC;YI SYLLABLE CY;Lo;0;L;;;;;N;;;;; -A2CD;YI SYLLABLE CYP;Lo;0;L;;;;;N;;;;; -A2CE;YI SYLLABLE CYRX;Lo;0;L;;;;;N;;;;; -A2CF;YI SYLLABLE CYR;Lo;0;L;;;;;N;;;;; -A2D0;YI SYLLABLE ZZIT;Lo;0;L;;;;;N;;;;; -A2D1;YI SYLLABLE ZZIX;Lo;0;L;;;;;N;;;;; -A2D2;YI SYLLABLE ZZI;Lo;0;L;;;;;N;;;;; -A2D3;YI SYLLABLE ZZIP;Lo;0;L;;;;;N;;;;; -A2D4;YI SYLLABLE ZZIET;Lo;0;L;;;;;N;;;;; -A2D5;YI SYLLABLE ZZIEX;Lo;0;L;;;;;N;;;;; -A2D6;YI SYLLABLE ZZIE;Lo;0;L;;;;;N;;;;; -A2D7;YI SYLLABLE ZZIEP;Lo;0;L;;;;;N;;;;; -A2D8;YI SYLLABLE ZZAT;Lo;0;L;;;;;N;;;;; -A2D9;YI SYLLABLE ZZAX;Lo;0;L;;;;;N;;;;; -A2DA;YI SYLLABLE ZZA;Lo;0;L;;;;;N;;;;; -A2DB;YI SYLLABLE ZZAP;Lo;0;L;;;;;N;;;;; -A2DC;YI SYLLABLE ZZOX;Lo;0;L;;;;;N;;;;; -A2DD;YI SYLLABLE ZZO;Lo;0;L;;;;;N;;;;; -A2DE;YI SYLLABLE ZZOP;Lo;0;L;;;;;N;;;;; -A2DF;YI SYLLABLE ZZEX;Lo;0;L;;;;;N;;;;; -A2E0;YI SYLLABLE ZZE;Lo;0;L;;;;;N;;;;; -A2E1;YI SYLLABLE ZZEP;Lo;0;L;;;;;N;;;;; -A2E2;YI SYLLABLE ZZUX;Lo;0;L;;;;;N;;;;; -A2E3;YI SYLLABLE ZZU;Lo;0;L;;;;;N;;;;; -A2E4;YI SYLLABLE ZZUP;Lo;0;L;;;;;N;;;;; -A2E5;YI SYLLABLE ZZURX;Lo;0;L;;;;;N;;;;; -A2E6;YI SYLLABLE ZZUR;Lo;0;L;;;;;N;;;;; -A2E7;YI SYLLABLE ZZYT;Lo;0;L;;;;;N;;;;; -A2E8;YI SYLLABLE ZZYX;Lo;0;L;;;;;N;;;;; -A2E9;YI SYLLABLE ZZY;Lo;0;L;;;;;N;;;;; -A2EA;YI SYLLABLE ZZYP;Lo;0;L;;;;;N;;;;; -A2EB;YI SYLLABLE ZZYRX;Lo;0;L;;;;;N;;;;; -A2EC;YI SYLLABLE ZZYR;Lo;0;L;;;;;N;;;;; -A2ED;YI SYLLABLE NZIT;Lo;0;L;;;;;N;;;;; -A2EE;YI SYLLABLE NZIX;Lo;0;L;;;;;N;;;;; -A2EF;YI SYLLABLE NZI;Lo;0;L;;;;;N;;;;; -A2F0;YI SYLLABLE NZIP;Lo;0;L;;;;;N;;;;; -A2F1;YI SYLLABLE NZIEX;Lo;0;L;;;;;N;;;;; -A2F2;YI SYLLABLE NZIE;Lo;0;L;;;;;N;;;;; -A2F3;YI SYLLABLE NZIEP;Lo;0;L;;;;;N;;;;; -A2F4;YI SYLLABLE NZAT;Lo;0;L;;;;;N;;;;; -A2F5;YI SYLLABLE NZAX;Lo;0;L;;;;;N;;;;; -A2F6;YI SYLLABLE NZA;Lo;0;L;;;;;N;;;;; -A2F7;YI SYLLABLE NZAP;Lo;0;L;;;;;N;;;;; -A2F8;YI SYLLABLE NZUOX;Lo;0;L;;;;;N;;;;; -A2F9;YI SYLLABLE NZUO;Lo;0;L;;;;;N;;;;; -A2FA;YI SYLLABLE NZOX;Lo;0;L;;;;;N;;;;; -A2FB;YI SYLLABLE NZOP;Lo;0;L;;;;;N;;;;; -A2FC;YI SYLLABLE NZEX;Lo;0;L;;;;;N;;;;; -A2FD;YI SYLLABLE NZE;Lo;0;L;;;;;N;;;;; -A2FE;YI SYLLABLE NZUX;Lo;0;L;;;;;N;;;;; -A2FF;YI SYLLABLE NZU;Lo;0;L;;;;;N;;;;; -A300;YI SYLLABLE NZUP;Lo;0;L;;;;;N;;;;; -A301;YI SYLLABLE NZURX;Lo;0;L;;;;;N;;;;; -A302;YI SYLLABLE NZUR;Lo;0;L;;;;;N;;;;; -A303;YI SYLLABLE NZYT;Lo;0;L;;;;;N;;;;; -A304;YI SYLLABLE NZYX;Lo;0;L;;;;;N;;;;; -A305;YI SYLLABLE NZY;Lo;0;L;;;;;N;;;;; -A306;YI SYLLABLE NZYP;Lo;0;L;;;;;N;;;;; -A307;YI SYLLABLE NZYRX;Lo;0;L;;;;;N;;;;; -A308;YI SYLLABLE NZYR;Lo;0;L;;;;;N;;;;; -A309;YI SYLLABLE SIT;Lo;0;L;;;;;N;;;;; -A30A;YI SYLLABLE SIX;Lo;0;L;;;;;N;;;;; -A30B;YI SYLLABLE SI;Lo;0;L;;;;;N;;;;; -A30C;YI SYLLABLE SIP;Lo;0;L;;;;;N;;;;; -A30D;YI SYLLABLE SIEX;Lo;0;L;;;;;N;;;;; -A30E;YI SYLLABLE SIE;Lo;0;L;;;;;N;;;;; -A30F;YI SYLLABLE SIEP;Lo;0;L;;;;;N;;;;; -A310;YI SYLLABLE SAT;Lo;0;L;;;;;N;;;;; -A311;YI SYLLABLE SAX;Lo;0;L;;;;;N;;;;; -A312;YI SYLLABLE SA;Lo;0;L;;;;;N;;;;; -A313;YI SYLLABLE SAP;Lo;0;L;;;;;N;;;;; -A314;YI SYLLABLE SUOX;Lo;0;L;;;;;N;;;;; -A315;YI SYLLABLE SUO;Lo;0;L;;;;;N;;;;; -A316;YI SYLLABLE SUOP;Lo;0;L;;;;;N;;;;; -A317;YI SYLLABLE SOT;Lo;0;L;;;;;N;;;;; -A318;YI SYLLABLE SOX;Lo;0;L;;;;;N;;;;; -A319;YI SYLLABLE SO;Lo;0;L;;;;;N;;;;; -A31A;YI SYLLABLE SOP;Lo;0;L;;;;;N;;;;; -A31B;YI SYLLABLE SEX;Lo;0;L;;;;;N;;;;; -A31C;YI SYLLABLE SE;Lo;0;L;;;;;N;;;;; -A31D;YI SYLLABLE SEP;Lo;0;L;;;;;N;;;;; -A31E;YI SYLLABLE SUT;Lo;0;L;;;;;N;;;;; -A31F;YI SYLLABLE SUX;Lo;0;L;;;;;N;;;;; -A320;YI SYLLABLE SU;Lo;0;L;;;;;N;;;;; -A321;YI SYLLABLE SUP;Lo;0;L;;;;;N;;;;; -A322;YI SYLLABLE SURX;Lo;0;L;;;;;N;;;;; -A323;YI SYLLABLE SUR;Lo;0;L;;;;;N;;;;; -A324;YI SYLLABLE SYT;Lo;0;L;;;;;N;;;;; -A325;YI SYLLABLE SYX;Lo;0;L;;;;;N;;;;; -A326;YI SYLLABLE SY;Lo;0;L;;;;;N;;;;; -A327;YI SYLLABLE SYP;Lo;0;L;;;;;N;;;;; -A328;YI SYLLABLE SYRX;Lo;0;L;;;;;N;;;;; -A329;YI SYLLABLE SYR;Lo;0;L;;;;;N;;;;; -A32A;YI SYLLABLE SSIT;Lo;0;L;;;;;N;;;;; -A32B;YI SYLLABLE SSIX;Lo;0;L;;;;;N;;;;; -A32C;YI SYLLABLE SSI;Lo;0;L;;;;;N;;;;; -A32D;YI SYLLABLE SSIP;Lo;0;L;;;;;N;;;;; -A32E;YI SYLLABLE SSIEX;Lo;0;L;;;;;N;;;;; -A32F;YI SYLLABLE SSIE;Lo;0;L;;;;;N;;;;; -A330;YI SYLLABLE SSIEP;Lo;0;L;;;;;N;;;;; -A331;YI SYLLABLE SSAT;Lo;0;L;;;;;N;;;;; -A332;YI SYLLABLE SSAX;Lo;0;L;;;;;N;;;;; -A333;YI SYLLABLE SSA;Lo;0;L;;;;;N;;;;; -A334;YI SYLLABLE SSAP;Lo;0;L;;;;;N;;;;; -A335;YI SYLLABLE SSOT;Lo;0;L;;;;;N;;;;; -A336;YI SYLLABLE SSOX;Lo;0;L;;;;;N;;;;; -A337;YI SYLLABLE SSO;Lo;0;L;;;;;N;;;;; -A338;YI SYLLABLE SSOP;Lo;0;L;;;;;N;;;;; -A339;YI SYLLABLE SSEX;Lo;0;L;;;;;N;;;;; -A33A;YI SYLLABLE SSE;Lo;0;L;;;;;N;;;;; -A33B;YI SYLLABLE SSEP;Lo;0;L;;;;;N;;;;; -A33C;YI SYLLABLE SSUT;Lo;0;L;;;;;N;;;;; -A33D;YI SYLLABLE SSUX;Lo;0;L;;;;;N;;;;; -A33E;YI SYLLABLE SSU;Lo;0;L;;;;;N;;;;; -A33F;YI SYLLABLE SSUP;Lo;0;L;;;;;N;;;;; -A340;YI SYLLABLE SSYT;Lo;0;L;;;;;N;;;;; -A341;YI SYLLABLE SSYX;Lo;0;L;;;;;N;;;;; -A342;YI SYLLABLE SSY;Lo;0;L;;;;;N;;;;; -A343;YI SYLLABLE SSYP;Lo;0;L;;;;;N;;;;; -A344;YI SYLLABLE SSYRX;Lo;0;L;;;;;N;;;;; -A345;YI SYLLABLE SSYR;Lo;0;L;;;;;N;;;;; -A346;YI SYLLABLE ZHAT;Lo;0;L;;;;;N;;;;; -A347;YI SYLLABLE ZHAX;Lo;0;L;;;;;N;;;;; -A348;YI SYLLABLE ZHA;Lo;0;L;;;;;N;;;;; -A349;YI SYLLABLE ZHAP;Lo;0;L;;;;;N;;;;; -A34A;YI SYLLABLE ZHUOX;Lo;0;L;;;;;N;;;;; -A34B;YI SYLLABLE ZHUO;Lo;0;L;;;;;N;;;;; -A34C;YI SYLLABLE ZHUOP;Lo;0;L;;;;;N;;;;; -A34D;YI SYLLABLE ZHOT;Lo;0;L;;;;;N;;;;; -A34E;YI SYLLABLE ZHOX;Lo;0;L;;;;;N;;;;; -A34F;YI SYLLABLE ZHO;Lo;0;L;;;;;N;;;;; -A350;YI SYLLABLE ZHOP;Lo;0;L;;;;;N;;;;; -A351;YI SYLLABLE ZHET;Lo;0;L;;;;;N;;;;; -A352;YI SYLLABLE ZHEX;Lo;0;L;;;;;N;;;;; -A353;YI SYLLABLE ZHE;Lo;0;L;;;;;N;;;;; -A354;YI SYLLABLE ZHEP;Lo;0;L;;;;;N;;;;; -A355;YI SYLLABLE ZHUT;Lo;0;L;;;;;N;;;;; -A356;YI SYLLABLE ZHUX;Lo;0;L;;;;;N;;;;; -A357;YI SYLLABLE ZHU;Lo;0;L;;;;;N;;;;; -A358;YI SYLLABLE ZHUP;Lo;0;L;;;;;N;;;;; -A359;YI SYLLABLE ZHURX;Lo;0;L;;;;;N;;;;; -A35A;YI SYLLABLE ZHUR;Lo;0;L;;;;;N;;;;; -A35B;YI SYLLABLE ZHYT;Lo;0;L;;;;;N;;;;; -A35C;YI SYLLABLE ZHYX;Lo;0;L;;;;;N;;;;; -A35D;YI SYLLABLE ZHY;Lo;0;L;;;;;N;;;;; -A35E;YI SYLLABLE ZHYP;Lo;0;L;;;;;N;;;;; -A35F;YI SYLLABLE ZHYRX;Lo;0;L;;;;;N;;;;; -A360;YI SYLLABLE ZHYR;Lo;0;L;;;;;N;;;;; -A361;YI SYLLABLE CHAT;Lo;0;L;;;;;N;;;;; -A362;YI SYLLABLE CHAX;Lo;0;L;;;;;N;;;;; -A363;YI SYLLABLE CHA;Lo;0;L;;;;;N;;;;; -A364;YI SYLLABLE CHAP;Lo;0;L;;;;;N;;;;; -A365;YI SYLLABLE CHUOT;Lo;0;L;;;;;N;;;;; -A366;YI SYLLABLE CHUOX;Lo;0;L;;;;;N;;;;; -A367;YI SYLLABLE CHUO;Lo;0;L;;;;;N;;;;; -A368;YI SYLLABLE CHUOP;Lo;0;L;;;;;N;;;;; -A369;YI SYLLABLE CHOT;Lo;0;L;;;;;N;;;;; -A36A;YI SYLLABLE CHOX;Lo;0;L;;;;;N;;;;; -A36B;YI SYLLABLE CHO;Lo;0;L;;;;;N;;;;; -A36C;YI SYLLABLE CHOP;Lo;0;L;;;;;N;;;;; -A36D;YI SYLLABLE CHET;Lo;0;L;;;;;N;;;;; -A36E;YI SYLLABLE CHEX;Lo;0;L;;;;;N;;;;; -A36F;YI SYLLABLE CHE;Lo;0;L;;;;;N;;;;; -A370;YI SYLLABLE CHEP;Lo;0;L;;;;;N;;;;; -A371;YI SYLLABLE CHUX;Lo;0;L;;;;;N;;;;; -A372;YI SYLLABLE CHU;Lo;0;L;;;;;N;;;;; -A373;YI SYLLABLE CHUP;Lo;0;L;;;;;N;;;;; -A374;YI SYLLABLE CHURX;Lo;0;L;;;;;N;;;;; -A375;YI SYLLABLE CHUR;Lo;0;L;;;;;N;;;;; -A376;YI SYLLABLE CHYT;Lo;0;L;;;;;N;;;;; -A377;YI SYLLABLE CHYX;Lo;0;L;;;;;N;;;;; -A378;YI SYLLABLE CHY;Lo;0;L;;;;;N;;;;; -A379;YI SYLLABLE CHYP;Lo;0;L;;;;;N;;;;; -A37A;YI SYLLABLE CHYRX;Lo;0;L;;;;;N;;;;; -A37B;YI SYLLABLE CHYR;Lo;0;L;;;;;N;;;;; -A37C;YI SYLLABLE RRAX;Lo;0;L;;;;;N;;;;; -A37D;YI SYLLABLE RRA;Lo;0;L;;;;;N;;;;; -A37E;YI SYLLABLE RRUOX;Lo;0;L;;;;;N;;;;; -A37F;YI SYLLABLE RRUO;Lo;0;L;;;;;N;;;;; -A380;YI SYLLABLE RROT;Lo;0;L;;;;;N;;;;; -A381;YI SYLLABLE RROX;Lo;0;L;;;;;N;;;;; -A382;YI SYLLABLE RRO;Lo;0;L;;;;;N;;;;; -A383;YI SYLLABLE RROP;Lo;0;L;;;;;N;;;;; -A384;YI SYLLABLE RRET;Lo;0;L;;;;;N;;;;; -A385;YI SYLLABLE RREX;Lo;0;L;;;;;N;;;;; -A386;YI SYLLABLE RRE;Lo;0;L;;;;;N;;;;; -A387;YI SYLLABLE RREP;Lo;0;L;;;;;N;;;;; -A388;YI SYLLABLE RRUT;Lo;0;L;;;;;N;;;;; -A389;YI SYLLABLE RRUX;Lo;0;L;;;;;N;;;;; -A38A;YI SYLLABLE RRU;Lo;0;L;;;;;N;;;;; -A38B;YI SYLLABLE RRUP;Lo;0;L;;;;;N;;;;; -A38C;YI SYLLABLE RRURX;Lo;0;L;;;;;N;;;;; -A38D;YI SYLLABLE RRUR;Lo;0;L;;;;;N;;;;; -A38E;YI SYLLABLE RRYT;Lo;0;L;;;;;N;;;;; -A38F;YI SYLLABLE RRYX;Lo;0;L;;;;;N;;;;; -A390;YI SYLLABLE RRY;Lo;0;L;;;;;N;;;;; -A391;YI SYLLABLE RRYP;Lo;0;L;;;;;N;;;;; -A392;YI SYLLABLE RRYRX;Lo;0;L;;;;;N;;;;; -A393;YI SYLLABLE RRYR;Lo;0;L;;;;;N;;;;; -A394;YI SYLLABLE NRAT;Lo;0;L;;;;;N;;;;; -A395;YI SYLLABLE NRAX;Lo;0;L;;;;;N;;;;; -A396;YI SYLLABLE NRA;Lo;0;L;;;;;N;;;;; -A397;YI SYLLABLE NRAP;Lo;0;L;;;;;N;;;;; -A398;YI SYLLABLE NROX;Lo;0;L;;;;;N;;;;; -A399;YI SYLLABLE NRO;Lo;0;L;;;;;N;;;;; -A39A;YI SYLLABLE NROP;Lo;0;L;;;;;N;;;;; -A39B;YI SYLLABLE NRET;Lo;0;L;;;;;N;;;;; -A39C;YI SYLLABLE NREX;Lo;0;L;;;;;N;;;;; -A39D;YI SYLLABLE NRE;Lo;0;L;;;;;N;;;;; -A39E;YI SYLLABLE NREP;Lo;0;L;;;;;N;;;;; -A39F;YI SYLLABLE NRUT;Lo;0;L;;;;;N;;;;; -A3A0;YI SYLLABLE NRUX;Lo;0;L;;;;;N;;;;; -A3A1;YI SYLLABLE NRU;Lo;0;L;;;;;N;;;;; -A3A2;YI SYLLABLE NRUP;Lo;0;L;;;;;N;;;;; -A3A3;YI SYLLABLE NRURX;Lo;0;L;;;;;N;;;;; -A3A4;YI SYLLABLE NRUR;Lo;0;L;;;;;N;;;;; -A3A5;YI SYLLABLE NRYT;Lo;0;L;;;;;N;;;;; -A3A6;YI SYLLABLE NRYX;Lo;0;L;;;;;N;;;;; -A3A7;YI SYLLABLE NRY;Lo;0;L;;;;;N;;;;; -A3A8;YI SYLLABLE NRYP;Lo;0;L;;;;;N;;;;; -A3A9;YI SYLLABLE NRYRX;Lo;0;L;;;;;N;;;;; -A3AA;YI SYLLABLE NRYR;Lo;0;L;;;;;N;;;;; -A3AB;YI SYLLABLE SHAT;Lo;0;L;;;;;N;;;;; -A3AC;YI SYLLABLE SHAX;Lo;0;L;;;;;N;;;;; -A3AD;YI SYLLABLE SHA;Lo;0;L;;;;;N;;;;; -A3AE;YI SYLLABLE SHAP;Lo;0;L;;;;;N;;;;; -A3AF;YI SYLLABLE SHUOX;Lo;0;L;;;;;N;;;;; -A3B0;YI SYLLABLE SHUO;Lo;0;L;;;;;N;;;;; -A3B1;YI SYLLABLE SHUOP;Lo;0;L;;;;;N;;;;; -A3B2;YI SYLLABLE SHOT;Lo;0;L;;;;;N;;;;; -A3B3;YI SYLLABLE SHOX;Lo;0;L;;;;;N;;;;; -A3B4;YI SYLLABLE SHO;Lo;0;L;;;;;N;;;;; -A3B5;YI SYLLABLE SHOP;Lo;0;L;;;;;N;;;;; -A3B6;YI SYLLABLE SHET;Lo;0;L;;;;;N;;;;; -A3B7;YI SYLLABLE SHEX;Lo;0;L;;;;;N;;;;; -A3B8;YI SYLLABLE SHE;Lo;0;L;;;;;N;;;;; -A3B9;YI SYLLABLE SHEP;Lo;0;L;;;;;N;;;;; -A3BA;YI SYLLABLE SHUT;Lo;0;L;;;;;N;;;;; -A3BB;YI SYLLABLE SHUX;Lo;0;L;;;;;N;;;;; -A3BC;YI SYLLABLE SHU;Lo;0;L;;;;;N;;;;; -A3BD;YI SYLLABLE SHUP;Lo;0;L;;;;;N;;;;; -A3BE;YI SYLLABLE SHURX;Lo;0;L;;;;;N;;;;; -A3BF;YI SYLLABLE SHUR;Lo;0;L;;;;;N;;;;; -A3C0;YI SYLLABLE SHYT;Lo;0;L;;;;;N;;;;; -A3C1;YI SYLLABLE SHYX;Lo;0;L;;;;;N;;;;; -A3C2;YI SYLLABLE SHY;Lo;0;L;;;;;N;;;;; -A3C3;YI SYLLABLE SHYP;Lo;0;L;;;;;N;;;;; -A3C4;YI SYLLABLE SHYRX;Lo;0;L;;;;;N;;;;; -A3C5;YI SYLLABLE SHYR;Lo;0;L;;;;;N;;;;; -A3C6;YI SYLLABLE RAT;Lo;0;L;;;;;N;;;;; -A3C7;YI SYLLABLE RAX;Lo;0;L;;;;;N;;;;; -A3C8;YI SYLLABLE RA;Lo;0;L;;;;;N;;;;; -A3C9;YI SYLLABLE RAP;Lo;0;L;;;;;N;;;;; -A3CA;YI SYLLABLE RUOX;Lo;0;L;;;;;N;;;;; -A3CB;YI SYLLABLE RUO;Lo;0;L;;;;;N;;;;; -A3CC;YI SYLLABLE RUOP;Lo;0;L;;;;;N;;;;; -A3CD;YI SYLLABLE ROT;Lo;0;L;;;;;N;;;;; -A3CE;YI SYLLABLE ROX;Lo;0;L;;;;;N;;;;; -A3CF;YI SYLLABLE RO;Lo;0;L;;;;;N;;;;; -A3D0;YI SYLLABLE ROP;Lo;0;L;;;;;N;;;;; -A3D1;YI SYLLABLE REX;Lo;0;L;;;;;N;;;;; -A3D2;YI SYLLABLE RE;Lo;0;L;;;;;N;;;;; -A3D3;YI SYLLABLE REP;Lo;0;L;;;;;N;;;;; -A3D4;YI SYLLABLE RUT;Lo;0;L;;;;;N;;;;; -A3D5;YI SYLLABLE RUX;Lo;0;L;;;;;N;;;;; -A3D6;YI SYLLABLE RU;Lo;0;L;;;;;N;;;;; -A3D7;YI SYLLABLE RUP;Lo;0;L;;;;;N;;;;; -A3D8;YI SYLLABLE RURX;Lo;0;L;;;;;N;;;;; -A3D9;YI SYLLABLE RUR;Lo;0;L;;;;;N;;;;; -A3DA;YI SYLLABLE RYT;Lo;0;L;;;;;N;;;;; -A3DB;YI SYLLABLE RYX;Lo;0;L;;;;;N;;;;; -A3DC;YI SYLLABLE RY;Lo;0;L;;;;;N;;;;; -A3DD;YI SYLLABLE RYP;Lo;0;L;;;;;N;;;;; -A3DE;YI SYLLABLE RYRX;Lo;0;L;;;;;N;;;;; -A3DF;YI SYLLABLE RYR;Lo;0;L;;;;;N;;;;; -A3E0;YI SYLLABLE JIT;Lo;0;L;;;;;N;;;;; -A3E1;YI SYLLABLE JIX;Lo;0;L;;;;;N;;;;; -A3E2;YI SYLLABLE JI;Lo;0;L;;;;;N;;;;; -A3E3;YI SYLLABLE JIP;Lo;0;L;;;;;N;;;;; -A3E4;YI SYLLABLE JIET;Lo;0;L;;;;;N;;;;; -A3E5;YI SYLLABLE JIEX;Lo;0;L;;;;;N;;;;; -A3E6;YI SYLLABLE JIE;Lo;0;L;;;;;N;;;;; -A3E7;YI SYLLABLE JIEP;Lo;0;L;;;;;N;;;;; -A3E8;YI SYLLABLE JUOT;Lo;0;L;;;;;N;;;;; -A3E9;YI SYLLABLE JUOX;Lo;0;L;;;;;N;;;;; -A3EA;YI SYLLABLE JUO;Lo;0;L;;;;;N;;;;; -A3EB;YI SYLLABLE JUOP;Lo;0;L;;;;;N;;;;; -A3EC;YI SYLLABLE JOT;Lo;0;L;;;;;N;;;;; -A3ED;YI SYLLABLE JOX;Lo;0;L;;;;;N;;;;; -A3EE;YI SYLLABLE JO;Lo;0;L;;;;;N;;;;; -A3EF;YI SYLLABLE JOP;Lo;0;L;;;;;N;;;;; -A3F0;YI SYLLABLE JUT;Lo;0;L;;;;;N;;;;; -A3F1;YI SYLLABLE JUX;Lo;0;L;;;;;N;;;;; -A3F2;YI SYLLABLE JU;Lo;0;L;;;;;N;;;;; -A3F3;YI SYLLABLE JUP;Lo;0;L;;;;;N;;;;; -A3F4;YI SYLLABLE JURX;Lo;0;L;;;;;N;;;;; -A3F5;YI SYLLABLE JUR;Lo;0;L;;;;;N;;;;; -A3F6;YI SYLLABLE JYT;Lo;0;L;;;;;N;;;;; -A3F7;YI SYLLABLE JYX;Lo;0;L;;;;;N;;;;; -A3F8;YI SYLLABLE JY;Lo;0;L;;;;;N;;;;; -A3F9;YI SYLLABLE JYP;Lo;0;L;;;;;N;;;;; -A3FA;YI SYLLABLE JYRX;Lo;0;L;;;;;N;;;;; -A3FB;YI SYLLABLE JYR;Lo;0;L;;;;;N;;;;; -A3FC;YI SYLLABLE QIT;Lo;0;L;;;;;N;;;;; -A3FD;YI SYLLABLE QIX;Lo;0;L;;;;;N;;;;; -A3FE;YI SYLLABLE QI;Lo;0;L;;;;;N;;;;; -A3FF;YI SYLLABLE QIP;Lo;0;L;;;;;N;;;;; -A400;YI SYLLABLE QIET;Lo;0;L;;;;;N;;;;; -A401;YI SYLLABLE QIEX;Lo;0;L;;;;;N;;;;; -A402;YI SYLLABLE QIE;Lo;0;L;;;;;N;;;;; -A403;YI SYLLABLE QIEP;Lo;0;L;;;;;N;;;;; -A404;YI SYLLABLE QUOT;Lo;0;L;;;;;N;;;;; -A405;YI SYLLABLE QUOX;Lo;0;L;;;;;N;;;;; -A406;YI SYLLABLE QUO;Lo;0;L;;;;;N;;;;; -A407;YI SYLLABLE QUOP;Lo;0;L;;;;;N;;;;; -A408;YI SYLLABLE QOT;Lo;0;L;;;;;N;;;;; -A409;YI SYLLABLE QOX;Lo;0;L;;;;;N;;;;; -A40A;YI SYLLABLE QO;Lo;0;L;;;;;N;;;;; -A40B;YI SYLLABLE QOP;Lo;0;L;;;;;N;;;;; -A40C;YI SYLLABLE QUT;Lo;0;L;;;;;N;;;;; -A40D;YI SYLLABLE QUX;Lo;0;L;;;;;N;;;;; -A40E;YI SYLLABLE QU;Lo;0;L;;;;;N;;;;; -A40F;YI SYLLABLE QUP;Lo;0;L;;;;;N;;;;; -A410;YI SYLLABLE QURX;Lo;0;L;;;;;N;;;;; -A411;YI SYLLABLE QUR;Lo;0;L;;;;;N;;;;; -A412;YI SYLLABLE QYT;Lo;0;L;;;;;N;;;;; -A413;YI SYLLABLE QYX;Lo;0;L;;;;;N;;;;; -A414;YI SYLLABLE QY;Lo;0;L;;;;;N;;;;; -A415;YI SYLLABLE QYP;Lo;0;L;;;;;N;;;;; -A416;YI SYLLABLE QYRX;Lo;0;L;;;;;N;;;;; -A417;YI SYLLABLE QYR;Lo;0;L;;;;;N;;;;; -A418;YI SYLLABLE JJIT;Lo;0;L;;;;;N;;;;; -A419;YI SYLLABLE JJIX;Lo;0;L;;;;;N;;;;; -A41A;YI SYLLABLE JJI;Lo;0;L;;;;;N;;;;; -A41B;YI SYLLABLE JJIP;Lo;0;L;;;;;N;;;;; -A41C;YI SYLLABLE JJIET;Lo;0;L;;;;;N;;;;; -A41D;YI SYLLABLE JJIEX;Lo;0;L;;;;;N;;;;; -A41E;YI SYLLABLE JJIE;Lo;0;L;;;;;N;;;;; -A41F;YI SYLLABLE JJIEP;Lo;0;L;;;;;N;;;;; -A420;YI SYLLABLE JJUOX;Lo;0;L;;;;;N;;;;; -A421;YI SYLLABLE JJUO;Lo;0;L;;;;;N;;;;; -A422;YI SYLLABLE JJUOP;Lo;0;L;;;;;N;;;;; -A423;YI SYLLABLE JJOT;Lo;0;L;;;;;N;;;;; -A424;YI SYLLABLE JJOX;Lo;0;L;;;;;N;;;;; -A425;YI SYLLABLE JJO;Lo;0;L;;;;;N;;;;; -A426;YI SYLLABLE JJOP;Lo;0;L;;;;;N;;;;; -A427;YI SYLLABLE JJUT;Lo;0;L;;;;;N;;;;; -A428;YI SYLLABLE JJUX;Lo;0;L;;;;;N;;;;; -A429;YI SYLLABLE JJU;Lo;0;L;;;;;N;;;;; -A42A;YI SYLLABLE JJUP;Lo;0;L;;;;;N;;;;; -A42B;YI SYLLABLE JJURX;Lo;0;L;;;;;N;;;;; -A42C;YI SYLLABLE JJUR;Lo;0;L;;;;;N;;;;; -A42D;YI SYLLABLE JJYT;Lo;0;L;;;;;N;;;;; -A42E;YI SYLLABLE JJYX;Lo;0;L;;;;;N;;;;; -A42F;YI SYLLABLE JJY;Lo;0;L;;;;;N;;;;; -A430;YI SYLLABLE JJYP;Lo;0;L;;;;;N;;;;; -A431;YI SYLLABLE NJIT;Lo;0;L;;;;;N;;;;; -A432;YI SYLLABLE NJIX;Lo;0;L;;;;;N;;;;; -A433;YI SYLLABLE NJI;Lo;0;L;;;;;N;;;;; -A434;YI SYLLABLE NJIP;Lo;0;L;;;;;N;;;;; -A435;YI SYLLABLE NJIET;Lo;0;L;;;;;N;;;;; -A436;YI SYLLABLE NJIEX;Lo;0;L;;;;;N;;;;; -A437;YI SYLLABLE NJIE;Lo;0;L;;;;;N;;;;; -A438;YI SYLLABLE NJIEP;Lo;0;L;;;;;N;;;;; -A439;YI SYLLABLE NJUOX;Lo;0;L;;;;;N;;;;; -A43A;YI SYLLABLE NJUO;Lo;0;L;;;;;N;;;;; -A43B;YI SYLLABLE NJOT;Lo;0;L;;;;;N;;;;; -A43C;YI SYLLABLE NJOX;Lo;0;L;;;;;N;;;;; -A43D;YI SYLLABLE NJO;Lo;0;L;;;;;N;;;;; -A43E;YI SYLLABLE NJOP;Lo;0;L;;;;;N;;;;; -A43F;YI SYLLABLE NJUX;Lo;0;L;;;;;N;;;;; -A440;YI SYLLABLE NJU;Lo;0;L;;;;;N;;;;; -A441;YI SYLLABLE NJUP;Lo;0;L;;;;;N;;;;; -A442;YI SYLLABLE NJURX;Lo;0;L;;;;;N;;;;; -A443;YI SYLLABLE NJUR;Lo;0;L;;;;;N;;;;; -A444;YI SYLLABLE NJYT;Lo;0;L;;;;;N;;;;; -A445;YI SYLLABLE NJYX;Lo;0;L;;;;;N;;;;; -A446;YI SYLLABLE NJY;Lo;0;L;;;;;N;;;;; -A447;YI SYLLABLE NJYP;Lo;0;L;;;;;N;;;;; -A448;YI SYLLABLE NJYRX;Lo;0;L;;;;;N;;;;; -A449;YI SYLLABLE NJYR;Lo;0;L;;;;;N;;;;; -A44A;YI SYLLABLE NYIT;Lo;0;L;;;;;N;;;;; -A44B;YI SYLLABLE NYIX;Lo;0;L;;;;;N;;;;; -A44C;YI SYLLABLE NYI;Lo;0;L;;;;;N;;;;; -A44D;YI SYLLABLE NYIP;Lo;0;L;;;;;N;;;;; -A44E;YI SYLLABLE NYIET;Lo;0;L;;;;;N;;;;; -A44F;YI SYLLABLE NYIEX;Lo;0;L;;;;;N;;;;; -A450;YI SYLLABLE NYIE;Lo;0;L;;;;;N;;;;; -A451;YI SYLLABLE NYIEP;Lo;0;L;;;;;N;;;;; -A452;YI SYLLABLE NYUOX;Lo;0;L;;;;;N;;;;; -A453;YI SYLLABLE NYUO;Lo;0;L;;;;;N;;;;; -A454;YI SYLLABLE NYUOP;Lo;0;L;;;;;N;;;;; -A455;YI SYLLABLE NYOT;Lo;0;L;;;;;N;;;;; -A456;YI SYLLABLE NYOX;Lo;0;L;;;;;N;;;;; -A457;YI SYLLABLE NYO;Lo;0;L;;;;;N;;;;; -A458;YI SYLLABLE NYOP;Lo;0;L;;;;;N;;;;; -A459;YI SYLLABLE NYUT;Lo;0;L;;;;;N;;;;; -A45A;YI SYLLABLE NYUX;Lo;0;L;;;;;N;;;;; -A45B;YI SYLLABLE NYU;Lo;0;L;;;;;N;;;;; -A45C;YI SYLLABLE NYUP;Lo;0;L;;;;;N;;;;; -A45D;YI SYLLABLE XIT;Lo;0;L;;;;;N;;;;; -A45E;YI SYLLABLE XIX;Lo;0;L;;;;;N;;;;; -A45F;YI SYLLABLE XI;Lo;0;L;;;;;N;;;;; -A460;YI SYLLABLE XIP;Lo;0;L;;;;;N;;;;; -A461;YI SYLLABLE XIET;Lo;0;L;;;;;N;;;;; -A462;YI SYLLABLE XIEX;Lo;0;L;;;;;N;;;;; -A463;YI SYLLABLE XIE;Lo;0;L;;;;;N;;;;; -A464;YI SYLLABLE XIEP;Lo;0;L;;;;;N;;;;; -A465;YI SYLLABLE XUOX;Lo;0;L;;;;;N;;;;; -A466;YI SYLLABLE XUO;Lo;0;L;;;;;N;;;;; -A467;YI SYLLABLE XOT;Lo;0;L;;;;;N;;;;; -A468;YI SYLLABLE XOX;Lo;0;L;;;;;N;;;;; -A469;YI SYLLABLE XO;Lo;0;L;;;;;N;;;;; -A46A;YI SYLLABLE XOP;Lo;0;L;;;;;N;;;;; -A46B;YI SYLLABLE XYT;Lo;0;L;;;;;N;;;;; -A46C;YI SYLLABLE XYX;Lo;0;L;;;;;N;;;;; -A46D;YI SYLLABLE XY;Lo;0;L;;;;;N;;;;; -A46E;YI SYLLABLE XYP;Lo;0;L;;;;;N;;;;; -A46F;YI SYLLABLE XYRX;Lo;0;L;;;;;N;;;;; -A470;YI SYLLABLE XYR;Lo;0;L;;;;;N;;;;; -A471;YI SYLLABLE YIT;Lo;0;L;;;;;N;;;;; -A472;YI SYLLABLE YIX;Lo;0;L;;;;;N;;;;; -A473;YI SYLLABLE YI;Lo;0;L;;;;;N;;;;; -A474;YI SYLLABLE YIP;Lo;0;L;;;;;N;;;;; -A475;YI SYLLABLE YIET;Lo;0;L;;;;;N;;;;; -A476;YI SYLLABLE YIEX;Lo;0;L;;;;;N;;;;; -A477;YI SYLLABLE YIE;Lo;0;L;;;;;N;;;;; -A478;YI SYLLABLE YIEP;Lo;0;L;;;;;N;;;;; -A479;YI SYLLABLE YUOT;Lo;0;L;;;;;N;;;;; -A47A;YI SYLLABLE YUOX;Lo;0;L;;;;;N;;;;; -A47B;YI SYLLABLE YUO;Lo;0;L;;;;;N;;;;; -A47C;YI SYLLABLE YUOP;Lo;0;L;;;;;N;;;;; -A47D;YI SYLLABLE YOT;Lo;0;L;;;;;N;;;;; -A47E;YI SYLLABLE YOX;Lo;0;L;;;;;N;;;;; -A47F;YI SYLLABLE YO;Lo;0;L;;;;;N;;;;; -A480;YI SYLLABLE YOP;Lo;0;L;;;;;N;;;;; -A481;YI SYLLABLE YUT;Lo;0;L;;;;;N;;;;; -A482;YI SYLLABLE YUX;Lo;0;L;;;;;N;;;;; -A483;YI SYLLABLE YU;Lo;0;L;;;;;N;;;;; -A484;YI SYLLABLE YUP;Lo;0;L;;;;;N;;;;; -A485;YI SYLLABLE YURX;Lo;0;L;;;;;N;;;;; -A486;YI SYLLABLE YUR;Lo;0;L;;;;;N;;;;; -A487;YI SYLLABLE YYT;Lo;0;L;;;;;N;;;;; -A488;YI SYLLABLE YYX;Lo;0;L;;;;;N;;;;; -A489;YI SYLLABLE YY;Lo;0;L;;;;;N;;;;; -A48A;YI SYLLABLE YYP;Lo;0;L;;;;;N;;;;; -A48B;YI SYLLABLE YYRX;Lo;0;L;;;;;N;;;;; -A48C;YI SYLLABLE YYR;Lo;0;L;;;;;N;;;;; -A490;YI RADICAL QOT;So;0;ON;;;;;N;;;;; -A491;YI RADICAL LI;So;0;ON;;;;;N;;;;; -A492;YI RADICAL KIT;So;0;ON;;;;;N;;;;; -A493;YI RADICAL NYIP;So;0;ON;;;;;N;;;;; -A494;YI RADICAL CYP;So;0;ON;;;;;N;;;;; -A495;YI RADICAL SSI;So;0;ON;;;;;N;;;;; -A496;YI RADICAL GGOP;So;0;ON;;;;;N;;;;; -A497;YI RADICAL GEP;So;0;ON;;;;;N;;;;; -A498;YI RADICAL MI;So;0;ON;;;;;N;;;;; -A499;YI RADICAL HXIT;So;0;ON;;;;;N;;;;; -A49A;YI RADICAL LYR;So;0;ON;;;;;N;;;;; -A49B;YI RADICAL BBUT;So;0;ON;;;;;N;;;;; -A49C;YI RADICAL MOP;So;0;ON;;;;;N;;;;; -A49D;YI RADICAL YO;So;0;ON;;;;;N;;;;; -A49E;YI RADICAL PUT;So;0;ON;;;;;N;;;;; -A49F;YI RADICAL HXUO;So;0;ON;;;;;N;;;;; -A4A0;YI RADICAL TAT;So;0;ON;;;;;N;;;;; -A4A1;YI RADICAL GA;So;0;ON;;;;;N;;;;; -A4A2;YI RADICAL ZUP;So;0;ON;;;;;N;;;;; -A4A3;YI RADICAL CYT;So;0;ON;;;;;N;;;;; -A4A4;YI RADICAL DDUR;So;0;ON;;;;;N;;;;; -A4A5;YI RADICAL BUR;So;0;ON;;;;;N;;;;; -A4A6;YI RADICAL GGUO;So;0;ON;;;;;N;;;;; -A4A7;YI RADICAL NYOP;So;0;ON;;;;;N;;;;; -A4A8;YI RADICAL TU;So;0;ON;;;;;N;;;;; -A4A9;YI RADICAL OP;So;0;ON;;;;;N;;;;; -A4AA;YI RADICAL JJUT;So;0;ON;;;;;N;;;;; -A4AB;YI RADICAL ZOT;So;0;ON;;;;;N;;;;; -A4AC;YI RADICAL PYT;So;0;ON;;;;;N;;;;; -A4AD;YI RADICAL HMO;So;0;ON;;;;;N;;;;; -A4AE;YI RADICAL YIT;So;0;ON;;;;;N;;;;; -A4AF;YI RADICAL VUR;So;0;ON;;;;;N;;;;; -A4B0;YI RADICAL SHY;So;0;ON;;;;;N;;;;; -A4B1;YI RADICAL VEP;So;0;ON;;;;;N;;;;; -A4B2;YI RADICAL ZA;So;0;ON;;;;;N;;;;; -A4B3;YI RADICAL JO;So;0;ON;;;;;N;;;;; -A4B4;YI RADICAL NZUP;So;0;ON;;;;;N;;;;; -A4B5;YI RADICAL JJY;So;0;ON;;;;;N;;;;; -A4B6;YI RADICAL GOT;So;0;ON;;;;;N;;;;; -A4B7;YI RADICAL JJIE;So;0;ON;;;;;N;;;;; -A4B8;YI RADICAL WO;So;0;ON;;;;;N;;;;; -A4B9;YI RADICAL DU;So;0;ON;;;;;N;;;;; -A4BA;YI RADICAL SHUR;So;0;ON;;;;;N;;;;; -A4BB;YI RADICAL LIE;So;0;ON;;;;;N;;;;; -A4BC;YI RADICAL CY;So;0;ON;;;;;N;;;;; -A4BD;YI RADICAL CUOP;So;0;ON;;;;;N;;;;; -A4BE;YI RADICAL CIP;So;0;ON;;;;;N;;;;; -A4BF;YI RADICAL HXOP;So;0;ON;;;;;N;;;;; -A4C0;YI RADICAL SHAT;So;0;ON;;;;;N;;;;; -A4C1;YI RADICAL ZUR;So;0;ON;;;;;N;;;;; -A4C2;YI RADICAL SHOP;So;0;ON;;;;;N;;;;; -A4C3;YI RADICAL CHE;So;0;ON;;;;;N;;;;; -A4C4;YI RADICAL ZZIET;So;0;ON;;;;;N;;;;; -A4C5;YI RADICAL NBIE;So;0;ON;;;;;N;;;;; -A4C6;YI RADICAL KE;So;0;ON;;;;;N;;;;; -A500;VAI SYLLABLE EE;Lo;0;L;;;;;N;;;;; -A501;VAI SYLLABLE EEN;Lo;0;L;;;;;N;;;;; -A502;VAI SYLLABLE HEE;Lo;0;L;;;;;N;;;;; -A503;VAI SYLLABLE WEE;Lo;0;L;;;;;N;;;;; -A504;VAI SYLLABLE WEEN;Lo;0;L;;;;;N;;;;; -A505;VAI SYLLABLE PEE;Lo;0;L;;;;;N;;;;; -A506;VAI SYLLABLE BHEE;Lo;0;L;;;;;N;;;;; -A507;VAI SYLLABLE BEE;Lo;0;L;;;;;N;;;;; -A508;VAI SYLLABLE MBEE;Lo;0;L;;;;;N;;;;; -A509;VAI SYLLABLE KPEE;Lo;0;L;;;;;N;;;;; -A50A;VAI SYLLABLE MGBEE;Lo;0;L;;;;;N;;;;; -A50B;VAI SYLLABLE GBEE;Lo;0;L;;;;;N;;;;; -A50C;VAI SYLLABLE FEE;Lo;0;L;;;;;N;;;;; -A50D;VAI SYLLABLE VEE;Lo;0;L;;;;;N;;;;; -A50E;VAI SYLLABLE TEE;Lo;0;L;;;;;N;;;;; -A50F;VAI SYLLABLE THEE;Lo;0;L;;;;;N;;;;; -A510;VAI SYLLABLE DHEE;Lo;0;L;;;;;N;;;;; -A511;VAI SYLLABLE DHHEE;Lo;0;L;;;;;N;;;;; -A512;VAI SYLLABLE LEE;Lo;0;L;;;;;N;;;;; -A513;VAI SYLLABLE REE;Lo;0;L;;;;;N;;;;; -A514;VAI SYLLABLE DEE;Lo;0;L;;;;;N;;;;; -A515;VAI SYLLABLE NDEE;Lo;0;L;;;;;N;;;;; -A516;VAI SYLLABLE SEE;Lo;0;L;;;;;N;;;;; -A517;VAI SYLLABLE SHEE;Lo;0;L;;;;;N;;;;; -A518;VAI SYLLABLE ZEE;Lo;0;L;;;;;N;;;;; -A519;VAI SYLLABLE ZHEE;Lo;0;L;;;;;N;;;;; -A51A;VAI SYLLABLE CEE;Lo;0;L;;;;;N;;;;; -A51B;VAI SYLLABLE JEE;Lo;0;L;;;;;N;;;;; -A51C;VAI SYLLABLE NJEE;Lo;0;L;;;;;N;;;;; -A51D;VAI SYLLABLE YEE;Lo;0;L;;;;;N;;;;; -A51E;VAI SYLLABLE KEE;Lo;0;L;;;;;N;;;;; -A51F;VAI SYLLABLE NGGEE;Lo;0;L;;;;;N;;;;; -A520;VAI SYLLABLE GEE;Lo;0;L;;;;;N;;;;; -A521;VAI SYLLABLE MEE;Lo;0;L;;;;;N;;;;; -A522;VAI SYLLABLE NEE;Lo;0;L;;;;;N;;;;; -A523;VAI SYLLABLE NYEE;Lo;0;L;;;;;N;;;;; -A524;VAI SYLLABLE I;Lo;0;L;;;;;N;;;;; -A525;VAI SYLLABLE IN;Lo;0;L;;;;;N;;;;; -A526;VAI SYLLABLE HI;Lo;0;L;;;;;N;;;;; -A527;VAI SYLLABLE HIN;Lo;0;L;;;;;N;;;;; -A528;VAI SYLLABLE WI;Lo;0;L;;;;;N;;;;; -A529;VAI SYLLABLE WIN;Lo;0;L;;;;;N;;;;; -A52A;VAI SYLLABLE PI;Lo;0;L;;;;;N;;;;; -A52B;VAI SYLLABLE BHI;Lo;0;L;;;;;N;;;;; -A52C;VAI SYLLABLE BI;Lo;0;L;;;;;N;;;;; -A52D;VAI SYLLABLE MBI;Lo;0;L;;;;;N;;;;; -A52E;VAI SYLLABLE KPI;Lo;0;L;;;;;N;;;;; -A52F;VAI SYLLABLE MGBI;Lo;0;L;;;;;N;;;;; -A530;VAI SYLLABLE GBI;Lo;0;L;;;;;N;;;;; -A531;VAI SYLLABLE FI;Lo;0;L;;;;;N;;;;; -A532;VAI SYLLABLE VI;Lo;0;L;;;;;N;;;;; -A533;VAI SYLLABLE TI;Lo;0;L;;;;;N;;;;; -A534;VAI SYLLABLE THI;Lo;0;L;;;;;N;;;;; -A535;VAI SYLLABLE DHI;Lo;0;L;;;;;N;;;;; -A536;VAI SYLLABLE DHHI;Lo;0;L;;;;;N;;;;; -A537;VAI SYLLABLE LI;Lo;0;L;;;;;N;;;;; -A538;VAI SYLLABLE RI;Lo;0;L;;;;;N;;;;; -A539;VAI SYLLABLE DI;Lo;0;L;;;;;N;;;;; -A53A;VAI SYLLABLE NDI;Lo;0;L;;;;;N;;;;; -A53B;VAI SYLLABLE SI;Lo;0;L;;;;;N;;;;; -A53C;VAI SYLLABLE SHI;Lo;0;L;;;;;N;;;;; -A53D;VAI SYLLABLE ZI;Lo;0;L;;;;;N;;;;; -A53E;VAI SYLLABLE ZHI;Lo;0;L;;;;;N;;;;; -A53F;VAI SYLLABLE CI;Lo;0;L;;;;;N;;;;; -A540;VAI SYLLABLE JI;Lo;0;L;;;;;N;;;;; -A541;VAI SYLLABLE NJI;Lo;0;L;;;;;N;;;;; -A542;VAI SYLLABLE YI;Lo;0;L;;;;;N;;;;; -A543;VAI SYLLABLE KI;Lo;0;L;;;;;N;;;;; -A544;VAI SYLLABLE NGGI;Lo;0;L;;;;;N;;;;; -A545;VAI SYLLABLE GI;Lo;0;L;;;;;N;;;;; -A546;VAI SYLLABLE MI;Lo;0;L;;;;;N;;;;; -A547;VAI SYLLABLE NI;Lo;0;L;;;;;N;;;;; -A548;VAI SYLLABLE NYI;Lo;0;L;;;;;N;;;;; -A549;VAI SYLLABLE A;Lo;0;L;;;;;N;;;;; -A54A;VAI SYLLABLE AN;Lo;0;L;;;;;N;;;;; -A54B;VAI SYLLABLE NGAN;Lo;0;L;;;;;N;;;;; -A54C;VAI SYLLABLE HA;Lo;0;L;;;;;N;;;;; -A54D;VAI SYLLABLE HAN;Lo;0;L;;;;;N;;;;; -A54E;VAI SYLLABLE WA;Lo;0;L;;;;;N;;;;; -A54F;VAI SYLLABLE WAN;Lo;0;L;;;;;N;;;;; -A550;VAI SYLLABLE PA;Lo;0;L;;;;;N;;;;; -A551;VAI SYLLABLE BHA;Lo;0;L;;;;;N;;;;; -A552;VAI SYLLABLE BA;Lo;0;L;;;;;N;;;;; -A553;VAI SYLLABLE MBA;Lo;0;L;;;;;N;;;;; -A554;VAI SYLLABLE KPA;Lo;0;L;;;;;N;;;;; -A555;VAI SYLLABLE KPAN;Lo;0;L;;;;;N;;;;; -A556;VAI SYLLABLE MGBA;Lo;0;L;;;;;N;;;;; -A557;VAI SYLLABLE GBA;Lo;0;L;;;;;N;;;;; -A558;VAI SYLLABLE FA;Lo;0;L;;;;;N;;;;; -A559;VAI SYLLABLE VA;Lo;0;L;;;;;N;;;;; -A55A;VAI SYLLABLE TA;Lo;0;L;;;;;N;;;;; -A55B;VAI SYLLABLE THA;Lo;0;L;;;;;N;;;;; -A55C;VAI SYLLABLE DHA;Lo;0;L;;;;;N;;;;; -A55D;VAI SYLLABLE DHHA;Lo;0;L;;;;;N;;;;; -A55E;VAI SYLLABLE LA;Lo;0;L;;;;;N;;;;; -A55F;VAI SYLLABLE RA;Lo;0;L;;;;;N;;;;; -A560;VAI SYLLABLE DA;Lo;0;L;;;;;N;;;;; -A561;VAI SYLLABLE NDA;Lo;0;L;;;;;N;;;;; -A562;VAI SYLLABLE SA;Lo;0;L;;;;;N;;;;; -A563;VAI SYLLABLE SHA;Lo;0;L;;;;;N;;;;; -A564;VAI SYLLABLE ZA;Lo;0;L;;;;;N;;;;; -A565;VAI SYLLABLE ZHA;Lo;0;L;;;;;N;;;;; -A566;VAI SYLLABLE CA;Lo;0;L;;;;;N;;;;; -A567;VAI SYLLABLE JA;Lo;0;L;;;;;N;;;;; -A568;VAI SYLLABLE NJA;Lo;0;L;;;;;N;;;;; -A569;VAI SYLLABLE YA;Lo;0;L;;;;;N;;;;; -A56A;VAI SYLLABLE KA;Lo;0;L;;;;;N;;;;; -A56B;VAI SYLLABLE KAN;Lo;0;L;;;;;N;;;;; -A56C;VAI SYLLABLE NGGA;Lo;0;L;;;;;N;;;;; -A56D;VAI SYLLABLE GA;Lo;0;L;;;;;N;;;;; -A56E;VAI SYLLABLE MA;Lo;0;L;;;;;N;;;;; -A56F;VAI SYLLABLE NA;Lo;0;L;;;;;N;;;;; -A570;VAI SYLLABLE NYA;Lo;0;L;;;;;N;;;;; -A571;VAI SYLLABLE OO;Lo;0;L;;;;;N;;;;; -A572;VAI SYLLABLE OON;Lo;0;L;;;;;N;;;;; -A573;VAI SYLLABLE HOO;Lo;0;L;;;;;N;;;;; -A574;VAI SYLLABLE WOO;Lo;0;L;;;;;N;;;;; -A575;VAI SYLLABLE WOON;Lo;0;L;;;;;N;;;;; -A576;VAI SYLLABLE POO;Lo;0;L;;;;;N;;;;; -A577;VAI SYLLABLE BHOO;Lo;0;L;;;;;N;;;;; -A578;VAI SYLLABLE BOO;Lo;0;L;;;;;N;;;;; -A579;VAI SYLLABLE MBOO;Lo;0;L;;;;;N;;;;; -A57A;VAI SYLLABLE KPOO;Lo;0;L;;;;;N;;;;; -A57B;VAI SYLLABLE MGBOO;Lo;0;L;;;;;N;;;;; -A57C;VAI SYLLABLE GBOO;Lo;0;L;;;;;N;;;;; -A57D;VAI SYLLABLE FOO;Lo;0;L;;;;;N;;;;; -A57E;VAI SYLLABLE VOO;Lo;0;L;;;;;N;;;;; -A57F;VAI SYLLABLE TOO;Lo;0;L;;;;;N;;;;; -A580;VAI SYLLABLE THOO;Lo;0;L;;;;;N;;;;; -A581;VAI SYLLABLE DHOO;Lo;0;L;;;;;N;;;;; -A582;VAI SYLLABLE DHHOO;Lo;0;L;;;;;N;;;;; -A583;VAI SYLLABLE LOO;Lo;0;L;;;;;N;;;;; -A584;VAI SYLLABLE ROO;Lo;0;L;;;;;N;;;;; -A585;VAI SYLLABLE DOO;Lo;0;L;;;;;N;;;;; -A586;VAI SYLLABLE NDOO;Lo;0;L;;;;;N;;;;; -A587;VAI SYLLABLE SOO;Lo;0;L;;;;;N;;;;; -A588;VAI SYLLABLE SHOO;Lo;0;L;;;;;N;;;;; -A589;VAI SYLLABLE ZOO;Lo;0;L;;;;;N;;;;; -A58A;VAI SYLLABLE ZHOO;Lo;0;L;;;;;N;;;;; -A58B;VAI SYLLABLE COO;Lo;0;L;;;;;N;;;;; -A58C;VAI SYLLABLE JOO;Lo;0;L;;;;;N;;;;; -A58D;VAI SYLLABLE NJOO;Lo;0;L;;;;;N;;;;; -A58E;VAI SYLLABLE YOO;Lo;0;L;;;;;N;;;;; -A58F;VAI SYLLABLE KOO;Lo;0;L;;;;;N;;;;; -A590;VAI SYLLABLE NGGOO;Lo;0;L;;;;;N;;;;; -A591;VAI SYLLABLE GOO;Lo;0;L;;;;;N;;;;; -A592;VAI SYLLABLE MOO;Lo;0;L;;;;;N;;;;; -A593;VAI SYLLABLE NOO;Lo;0;L;;;;;N;;;;; -A594;VAI SYLLABLE NYOO;Lo;0;L;;;;;N;;;;; -A595;VAI SYLLABLE U;Lo;0;L;;;;;N;;;;; -A596;VAI SYLLABLE UN;Lo;0;L;;;;;N;;;;; -A597;VAI SYLLABLE HU;Lo;0;L;;;;;N;;;;; -A598;VAI SYLLABLE HUN;Lo;0;L;;;;;N;;;;; -A599;VAI SYLLABLE WU;Lo;0;L;;;;;N;;;;; -A59A;VAI SYLLABLE WUN;Lo;0;L;;;;;N;;;;; -A59B;VAI SYLLABLE PU;Lo;0;L;;;;;N;;;;; -A59C;VAI SYLLABLE BHU;Lo;0;L;;;;;N;;;;; -A59D;VAI SYLLABLE BU;Lo;0;L;;;;;N;;;;; -A59E;VAI SYLLABLE MBU;Lo;0;L;;;;;N;;;;; -A59F;VAI SYLLABLE KPU;Lo;0;L;;;;;N;;;;; -A5A0;VAI SYLLABLE MGBU;Lo;0;L;;;;;N;;;;; -A5A1;VAI SYLLABLE GBU;Lo;0;L;;;;;N;;;;; -A5A2;VAI SYLLABLE FU;Lo;0;L;;;;;N;;;;; -A5A3;VAI SYLLABLE VU;Lo;0;L;;;;;N;;;;; -A5A4;VAI SYLLABLE TU;Lo;0;L;;;;;N;;;;; -A5A5;VAI SYLLABLE THU;Lo;0;L;;;;;N;;;;; -A5A6;VAI SYLLABLE DHU;Lo;0;L;;;;;N;;;;; -A5A7;VAI SYLLABLE DHHU;Lo;0;L;;;;;N;;;;; -A5A8;VAI SYLLABLE LU;Lo;0;L;;;;;N;;;;; -A5A9;VAI SYLLABLE RU;Lo;0;L;;;;;N;;;;; -A5AA;VAI SYLLABLE DU;Lo;0;L;;;;;N;;;;; -A5AB;VAI SYLLABLE NDU;Lo;0;L;;;;;N;;;;; -A5AC;VAI SYLLABLE SU;Lo;0;L;;;;;N;;;;; -A5AD;VAI SYLLABLE SHU;Lo;0;L;;;;;N;;;;; -A5AE;VAI SYLLABLE ZU;Lo;0;L;;;;;N;;;;; -A5AF;VAI SYLLABLE ZHU;Lo;0;L;;;;;N;;;;; -A5B0;VAI SYLLABLE CU;Lo;0;L;;;;;N;;;;; -A5B1;VAI SYLLABLE JU;Lo;0;L;;;;;N;;;;; -A5B2;VAI SYLLABLE NJU;Lo;0;L;;;;;N;;;;; -A5B3;VAI SYLLABLE YU;Lo;0;L;;;;;N;;;;; -A5B4;VAI SYLLABLE KU;Lo;0;L;;;;;N;;;;; -A5B5;VAI SYLLABLE NGGU;Lo;0;L;;;;;N;;;;; -A5B6;VAI SYLLABLE GU;Lo;0;L;;;;;N;;;;; -A5B7;VAI SYLLABLE MU;Lo;0;L;;;;;N;;;;; -A5B8;VAI SYLLABLE NU;Lo;0;L;;;;;N;;;;; -A5B9;VAI SYLLABLE NYU;Lo;0;L;;;;;N;;;;; -A5BA;VAI SYLLABLE O;Lo;0;L;;;;;N;;;;; -A5BB;VAI SYLLABLE ON;Lo;0;L;;;;;N;;;;; -A5BC;VAI SYLLABLE NGON;Lo;0;L;;;;;N;;;;; -A5BD;VAI SYLLABLE HO;Lo;0;L;;;;;N;;;;; -A5BE;VAI SYLLABLE HON;Lo;0;L;;;;;N;;;;; -A5BF;VAI SYLLABLE WO;Lo;0;L;;;;;N;;;;; -A5C0;VAI SYLLABLE WON;Lo;0;L;;;;;N;;;;; -A5C1;VAI SYLLABLE PO;Lo;0;L;;;;;N;;;;; -A5C2;VAI SYLLABLE BHO;Lo;0;L;;;;;N;;;;; -A5C3;VAI SYLLABLE BO;Lo;0;L;;;;;N;;;;; -A5C4;VAI SYLLABLE MBO;Lo;0;L;;;;;N;;;;; -A5C5;VAI SYLLABLE KPO;Lo;0;L;;;;;N;;;;; -A5C6;VAI SYLLABLE MGBO;Lo;0;L;;;;;N;;;;; -A5C7;VAI SYLLABLE GBO;Lo;0;L;;;;;N;;;;; -A5C8;VAI SYLLABLE GBON;Lo;0;L;;;;;N;;;;; -A5C9;VAI SYLLABLE FO;Lo;0;L;;;;;N;;;;; -A5CA;VAI SYLLABLE VO;Lo;0;L;;;;;N;;;;; -A5CB;VAI SYLLABLE TO;Lo;0;L;;;;;N;;;;; -A5CC;VAI SYLLABLE THO;Lo;0;L;;;;;N;;;;; -A5CD;VAI SYLLABLE DHO;Lo;0;L;;;;;N;;;;; -A5CE;VAI SYLLABLE DHHO;Lo;0;L;;;;;N;;;;; -A5CF;VAI SYLLABLE LO;Lo;0;L;;;;;N;;;;; -A5D0;VAI SYLLABLE RO;Lo;0;L;;;;;N;;;;; -A5D1;VAI SYLLABLE DO;Lo;0;L;;;;;N;;;;; -A5D2;VAI SYLLABLE NDO;Lo;0;L;;;;;N;;;;; -A5D3;VAI SYLLABLE SO;Lo;0;L;;;;;N;;;;; -A5D4;VAI SYLLABLE SHO;Lo;0;L;;;;;N;;;;; -A5D5;VAI SYLLABLE ZO;Lo;0;L;;;;;N;;;;; -A5D6;VAI SYLLABLE ZHO;Lo;0;L;;;;;N;;;;; -A5D7;VAI SYLLABLE CO;Lo;0;L;;;;;N;;;;; -A5D8;VAI SYLLABLE JO;Lo;0;L;;;;;N;;;;; -A5D9;VAI SYLLABLE NJO;Lo;0;L;;;;;N;;;;; -A5DA;VAI SYLLABLE YO;Lo;0;L;;;;;N;;;;; -A5DB;VAI SYLLABLE KO;Lo;0;L;;;;;N;;;;; -A5DC;VAI SYLLABLE NGGO;Lo;0;L;;;;;N;;;;; -A5DD;VAI SYLLABLE GO;Lo;0;L;;;;;N;;;;; -A5DE;VAI SYLLABLE MO;Lo;0;L;;;;;N;;;;; -A5DF;VAI SYLLABLE NO;Lo;0;L;;;;;N;;;;; -A5E0;VAI SYLLABLE NYO;Lo;0;L;;;;;N;;;;; -A5E1;VAI SYLLABLE E;Lo;0;L;;;;;N;;;;; -A5E2;VAI SYLLABLE EN;Lo;0;L;;;;;N;;;;; -A5E3;VAI SYLLABLE NGEN;Lo;0;L;;;;;N;;;;; -A5E4;VAI SYLLABLE HE;Lo;0;L;;;;;N;;;;; -A5E5;VAI SYLLABLE HEN;Lo;0;L;;;;;N;;;;; -A5E6;VAI SYLLABLE WE;Lo;0;L;;;;;N;;;;; -A5E7;VAI SYLLABLE WEN;Lo;0;L;;;;;N;;;;; -A5E8;VAI SYLLABLE PE;Lo;0;L;;;;;N;;;;; -A5E9;VAI SYLLABLE BHE;Lo;0;L;;;;;N;;;;; -A5EA;VAI SYLLABLE BE;Lo;0;L;;;;;N;;;;; -A5EB;VAI SYLLABLE MBE;Lo;0;L;;;;;N;;;;; -A5EC;VAI SYLLABLE KPE;Lo;0;L;;;;;N;;;;; -A5ED;VAI SYLLABLE KPEN;Lo;0;L;;;;;N;;;;; -A5EE;VAI SYLLABLE MGBE;Lo;0;L;;;;;N;;;;; -A5EF;VAI SYLLABLE GBE;Lo;0;L;;;;;N;;;;; -A5F0;VAI SYLLABLE GBEN;Lo;0;L;;;;;N;;;;; -A5F1;VAI SYLLABLE FE;Lo;0;L;;;;;N;;;;; -A5F2;VAI SYLLABLE VE;Lo;0;L;;;;;N;;;;; -A5F3;VAI SYLLABLE TE;Lo;0;L;;;;;N;;;;; -A5F4;VAI SYLLABLE THE;Lo;0;L;;;;;N;;;;; -A5F5;VAI SYLLABLE DHE;Lo;0;L;;;;;N;;;;; -A5F6;VAI SYLLABLE DHHE;Lo;0;L;;;;;N;;;;; -A5F7;VAI SYLLABLE LE;Lo;0;L;;;;;N;;;;; -A5F8;VAI SYLLABLE RE;Lo;0;L;;;;;N;;;;; -A5F9;VAI SYLLABLE DE;Lo;0;L;;;;;N;;;;; -A5FA;VAI SYLLABLE NDE;Lo;0;L;;;;;N;;;;; -A5FB;VAI SYLLABLE SE;Lo;0;L;;;;;N;;;;; -A5FC;VAI SYLLABLE SHE;Lo;0;L;;;;;N;;;;; -A5FD;VAI SYLLABLE ZE;Lo;0;L;;;;;N;;;;; -A5FE;VAI SYLLABLE ZHE;Lo;0;L;;;;;N;;;;; -A5FF;VAI SYLLABLE CE;Lo;0;L;;;;;N;;;;; -A600;VAI SYLLABLE JE;Lo;0;L;;;;;N;;;;; -A601;VAI SYLLABLE NJE;Lo;0;L;;;;;N;;;;; -A602;VAI SYLLABLE YE;Lo;0;L;;;;;N;;;;; -A603;VAI SYLLABLE KE;Lo;0;L;;;;;N;;;;; -A604;VAI SYLLABLE NGGE;Lo;0;L;;;;;N;;;;; -A605;VAI SYLLABLE NGGEN;Lo;0;L;;;;;N;;;;; -A606;VAI SYLLABLE GE;Lo;0;L;;;;;N;;;;; -A607;VAI SYLLABLE GEN;Lo;0;L;;;;;N;;;;; -A608;VAI SYLLABLE ME;Lo;0;L;;;;;N;;;;; -A609;VAI SYLLABLE NE;Lo;0;L;;;;;N;;;;; -A60A;VAI SYLLABLE NYE;Lo;0;L;;;;;N;;;;; -A60B;VAI SYLLABLE NG;Lo;0;L;;;;;N;;;;; -A60C;VAI SYLLABLE LENGTHENER;Lm;0;L;;;;;N;;;;; -A60D;VAI COMMA;Po;0;ON;;;;;N;;;;; -A60E;VAI FULL STOP;Po;0;ON;;;;;N;;;;; -A60F;VAI QUESTION MARK;Po;0;ON;;;;;N;;;;; -A610;VAI SYLLABLE NDOLE FA;Lo;0;L;;;;;N;;;;; -A611;VAI SYLLABLE NDOLE KA;Lo;0;L;;;;;N;;;;; -A612;VAI SYLLABLE NDOLE SOO;Lo;0;L;;;;;N;;;;; -A613;VAI SYMBOL FEENG;Lo;0;L;;;;;N;;;;; -A614;VAI SYMBOL KEENG;Lo;0;L;;;;;N;;;;; -A615;VAI SYMBOL TING;Lo;0;L;;;;;N;;;;; -A616;VAI SYMBOL NII;Lo;0;L;;;;;N;;;;; -A617;VAI SYMBOL BANG;Lo;0;L;;;;;N;;;;; -A618;VAI SYMBOL FAA;Lo;0;L;;;;;N;;;;; -A619;VAI SYMBOL TAA;Lo;0;L;;;;;N;;;;; -A61A;VAI SYMBOL DANG;Lo;0;L;;;;;N;;;;; -A61B;VAI SYMBOL DOONG;Lo;0;L;;;;;N;;;;; -A61C;VAI SYMBOL KUNG;Lo;0;L;;;;;N;;;;; -A61D;VAI SYMBOL TONG;Lo;0;L;;;;;N;;;;; -A61E;VAI SYMBOL DO-O;Lo;0;L;;;;;N;;;;; -A61F;VAI SYMBOL JONG;Lo;0;L;;;;;N;;;;; -A620;VAI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -A621;VAI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -A622;VAI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -A623;VAI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -A624;VAI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -A625;VAI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -A626;VAI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -A627;VAI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -A628;VAI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -A629;VAI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -A62A;VAI SYLLABLE NDOLE MA;Lo;0;L;;;;;N;;;;; -A62B;VAI SYLLABLE NDOLE DO;Lo;0;L;;;;;N;;;;; -A640;CYRILLIC CAPITAL LETTER ZEMLYA;Lu;0;L;;;;;N;;;;A641; -A641;CYRILLIC SMALL LETTER ZEMLYA;Ll;0;L;;;;;N;;;A640;;A640 -A642;CYRILLIC CAPITAL LETTER DZELO;Lu;0;L;;;;;N;;;;A643; -A643;CYRILLIC SMALL LETTER DZELO;Ll;0;L;;;;;N;;;A642;;A642 -A644;CYRILLIC CAPITAL LETTER REVERSED DZE;Lu;0;L;;;;;N;;;;A645; -A645;CYRILLIC SMALL LETTER REVERSED DZE;Ll;0;L;;;;;N;;;A644;;A644 -A646;CYRILLIC CAPITAL LETTER IOTA;Lu;0;L;;;;;N;;;;A647; -A647;CYRILLIC SMALL LETTER IOTA;Ll;0;L;;;;;N;;;A646;;A646 -A648;CYRILLIC CAPITAL LETTER DJERV;Lu;0;L;;;;;N;;;;A649; -A649;CYRILLIC SMALL LETTER DJERV;Ll;0;L;;;;;N;;;A648;;A648 -A64A;CYRILLIC CAPITAL LETTER MONOGRAPH UK;Lu;0;L;;;;;N;;;;A64B; -A64B;CYRILLIC SMALL LETTER MONOGRAPH UK;Ll;0;L;;;;;N;;;A64A;;A64A -A64C;CYRILLIC CAPITAL LETTER BROAD OMEGA;Lu;0;L;;;;;N;;;;A64D; -A64D;CYRILLIC SMALL LETTER BROAD OMEGA;Ll;0;L;;;;;N;;;A64C;;A64C -A64E;CYRILLIC CAPITAL LETTER NEUTRAL YER;Lu;0;L;;;;;N;;;;A64F; -A64F;CYRILLIC SMALL LETTER NEUTRAL YER;Ll;0;L;;;;;N;;;A64E;;A64E -A650;CYRILLIC CAPITAL LETTER YERU WITH BACK YER;Lu;0;L;;;;;N;;;;A651; -A651;CYRILLIC SMALL LETTER YERU WITH BACK YER;Ll;0;L;;;;;N;;;A650;;A650 -A652;CYRILLIC CAPITAL LETTER IOTIFIED YAT;Lu;0;L;;;;;N;;;;A653; -A653;CYRILLIC SMALL LETTER IOTIFIED YAT;Ll;0;L;;;;;N;;;A652;;A652 -A654;CYRILLIC CAPITAL LETTER REVERSED YU;Lu;0;L;;;;;N;;;;A655; -A655;CYRILLIC SMALL LETTER REVERSED YU;Ll;0;L;;;;;N;;;A654;;A654 -A656;CYRILLIC CAPITAL LETTER IOTIFIED A;Lu;0;L;;;;;N;;;;A657; -A657;CYRILLIC SMALL LETTER IOTIFIED A;Ll;0;L;;;;;N;;;A656;;A656 -A658;CYRILLIC CAPITAL LETTER CLOSED LITTLE YUS;Lu;0;L;;;;;N;;;;A659; -A659;CYRILLIC SMALL LETTER CLOSED LITTLE YUS;Ll;0;L;;;;;N;;;A658;;A658 -A65A;CYRILLIC CAPITAL LETTER BLENDED YUS;Lu;0;L;;;;;N;;;;A65B; -A65B;CYRILLIC SMALL LETTER BLENDED YUS;Ll;0;L;;;;;N;;;A65A;;A65A -A65C;CYRILLIC CAPITAL LETTER IOTIFIED CLOSED LITTLE YUS;Lu;0;L;;;;;N;;;;A65D; -A65D;CYRILLIC SMALL LETTER IOTIFIED CLOSED LITTLE YUS;Ll;0;L;;;;;N;;;A65C;;A65C -A65E;CYRILLIC CAPITAL LETTER YN;Lu;0;L;;;;;N;;;;A65F; -A65F;CYRILLIC SMALL LETTER YN;Ll;0;L;;;;;N;;;A65E;;A65E -A662;CYRILLIC CAPITAL LETTER SOFT DE;Lu;0;L;;;;;N;;;;A663; -A663;CYRILLIC SMALL LETTER SOFT DE;Ll;0;L;;;;;N;;;A662;;A662 -A664;CYRILLIC CAPITAL LETTER SOFT EL;Lu;0;L;;;;;N;;;;A665; -A665;CYRILLIC SMALL LETTER SOFT EL;Ll;0;L;;;;;N;;;A664;;A664 -A666;CYRILLIC CAPITAL LETTER SOFT EM;Lu;0;L;;;;;N;;;;A667; -A667;CYRILLIC SMALL LETTER SOFT EM;Ll;0;L;;;;;N;;;A666;;A666 -A668;CYRILLIC CAPITAL LETTER MONOCULAR O;Lu;0;L;;;;;N;;;;A669; -A669;CYRILLIC SMALL LETTER MONOCULAR O;Ll;0;L;;;;;N;;;A668;;A668 -A66A;CYRILLIC CAPITAL LETTER BINOCULAR O;Lu;0;L;;;;;N;;;;A66B; -A66B;CYRILLIC SMALL LETTER BINOCULAR O;Ll;0;L;;;;;N;;;A66A;;A66A -A66C;CYRILLIC CAPITAL LETTER DOUBLE MONOCULAR O;Lu;0;L;;;;;N;;;;A66D; -A66D;CYRILLIC SMALL LETTER DOUBLE MONOCULAR O;Ll;0;L;;;;;N;;;A66C;;A66C -A66E;CYRILLIC LETTER MULTIOCULAR O;Lo;0;L;;;;;N;;;;; -A66F;COMBINING CYRILLIC VZMET;Mn;230;NSM;;;;;N;;;;; -A670;COMBINING CYRILLIC TEN MILLIONS SIGN;Me;0;NSM;;;;;N;;;;; -A671;COMBINING CYRILLIC HUNDRED MILLIONS SIGN;Me;0;NSM;;;;;N;;;;; -A672;COMBINING CYRILLIC THOUSAND MILLIONS SIGN;Me;0;NSM;;;;;N;;;;; -A673;SLAVONIC ASTERISK;Po;0;ON;;;;;N;;;;; -A67C;COMBINING CYRILLIC KAVYKA;Mn;230;NSM;;;;;N;;;;; -A67D;COMBINING CYRILLIC PAYEROK;Mn;230;NSM;;;;;N;;;;; -A67E;CYRILLIC KAVYKA;Po;0;ON;;;;;N;;;;; -A67F;CYRILLIC PAYEROK;Lm;0;ON;;;;;N;;;;; -A680;CYRILLIC CAPITAL LETTER DWE;Lu;0;L;;;;;N;;;;A681; -A681;CYRILLIC SMALL LETTER DWE;Ll;0;L;;;;;N;;;A680;;A680 -A682;CYRILLIC CAPITAL LETTER DZWE;Lu;0;L;;;;;N;;;;A683; -A683;CYRILLIC SMALL LETTER DZWE;Ll;0;L;;;;;N;;;A682;;A682 -A684;CYRILLIC CAPITAL LETTER ZHWE;Lu;0;L;;;;;N;;;;A685; -A685;CYRILLIC SMALL LETTER ZHWE;Ll;0;L;;;;;N;;;A684;;A684 -A686;CYRILLIC CAPITAL LETTER CCHE;Lu;0;L;;;;;N;;;;A687; -A687;CYRILLIC SMALL LETTER CCHE;Ll;0;L;;;;;N;;;A686;;A686 -A688;CYRILLIC CAPITAL LETTER DZZE;Lu;0;L;;;;;N;;;;A689; -A689;CYRILLIC SMALL LETTER DZZE;Ll;0;L;;;;;N;;;A688;;A688 -A68A;CYRILLIC CAPITAL LETTER TE WITH MIDDLE HOOK;Lu;0;L;;;;;N;;;;A68B; -A68B;CYRILLIC SMALL LETTER TE WITH MIDDLE HOOK;Ll;0;L;;;;;N;;;A68A;;A68A -A68C;CYRILLIC CAPITAL LETTER TWE;Lu;0;L;;;;;N;;;;A68D; -A68D;CYRILLIC SMALL LETTER TWE;Ll;0;L;;;;;N;;;A68C;;A68C -A68E;CYRILLIC CAPITAL LETTER TSWE;Lu;0;L;;;;;N;;;;A68F; -A68F;CYRILLIC SMALL LETTER TSWE;Ll;0;L;;;;;N;;;A68E;;A68E -A690;CYRILLIC CAPITAL LETTER TSSE;Lu;0;L;;;;;N;;;;A691; -A691;CYRILLIC SMALL LETTER TSSE;Ll;0;L;;;;;N;;;A690;;A690 -A692;CYRILLIC CAPITAL LETTER TCHE;Lu;0;L;;;;;N;;;;A693; -A693;CYRILLIC SMALL LETTER TCHE;Ll;0;L;;;;;N;;;A692;;A692 -A694;CYRILLIC CAPITAL LETTER HWE;Lu;0;L;;;;;N;;;;A695; -A695;CYRILLIC SMALL LETTER HWE;Ll;0;L;;;;;N;;;A694;;A694 -A696;CYRILLIC CAPITAL LETTER SHWE;Lu;0;L;;;;;N;;;;A697; -A697;CYRILLIC SMALL LETTER SHWE;Ll;0;L;;;;;N;;;A696;;A696 -A700;MODIFIER LETTER CHINESE TONE YIN PING;Sk;0;ON;;;;;N;;;;; -A701;MODIFIER LETTER CHINESE TONE YANG PING;Sk;0;ON;;;;;N;;;;; -A702;MODIFIER LETTER CHINESE TONE YIN SHANG;Sk;0;ON;;;;;N;;;;; -A703;MODIFIER LETTER CHINESE TONE YANG SHANG;Sk;0;ON;;;;;N;;;;; -A704;MODIFIER LETTER CHINESE TONE YIN QU;Sk;0;ON;;;;;N;;;;; -A705;MODIFIER LETTER CHINESE TONE YANG QU;Sk;0;ON;;;;;N;;;;; -A706;MODIFIER LETTER CHINESE TONE YIN RU;Sk;0;ON;;;;;N;;;;; -A707;MODIFIER LETTER CHINESE TONE YANG RU;Sk;0;ON;;;;;N;;;;; -A708;MODIFIER LETTER EXTRA-HIGH DOTTED TONE BAR;Sk;0;ON;;;;;N;;;;; -A709;MODIFIER LETTER HIGH DOTTED TONE BAR;Sk;0;ON;;;;;N;;;;; -A70A;MODIFIER LETTER MID DOTTED TONE BAR;Sk;0;ON;;;;;N;;;;; -A70B;MODIFIER LETTER LOW DOTTED TONE BAR;Sk;0;ON;;;;;N;;;;; -A70C;MODIFIER LETTER EXTRA-LOW DOTTED TONE BAR;Sk;0;ON;;;;;N;;;;; -A70D;MODIFIER LETTER EXTRA-HIGH DOTTED LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A70E;MODIFIER LETTER HIGH DOTTED LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A70F;MODIFIER LETTER MID DOTTED LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A710;MODIFIER LETTER LOW DOTTED LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A711;MODIFIER LETTER EXTRA-LOW DOTTED LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A712;MODIFIER LETTER EXTRA-HIGH LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A713;MODIFIER LETTER HIGH LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A714;MODIFIER LETTER MID LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A715;MODIFIER LETTER LOW LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A716;MODIFIER LETTER EXTRA-LOW LEFT-STEM TONE BAR;Sk;0;ON;;;;;N;;;;; -A717;MODIFIER LETTER DOT VERTICAL BAR;Lm;0;ON;;;;;N;;;;; -A718;MODIFIER LETTER DOT SLASH;Lm;0;ON;;;;;N;;;;; -A719;MODIFIER LETTER DOT HORIZONTAL BAR;Lm;0;ON;;;;;N;;;;; -A71A;MODIFIER LETTER LOWER RIGHT CORNER ANGLE;Lm;0;ON;;;;;N;;;;; -A71B;MODIFIER LETTER RAISED UP ARROW;Lm;0;ON;;;;;N;;;;; -A71C;MODIFIER LETTER RAISED DOWN ARROW;Lm;0;ON;;;;;N;;;;; -A71D;MODIFIER LETTER RAISED EXCLAMATION MARK;Lm;0;ON;;;;;N;;;;; -A71E;MODIFIER LETTER RAISED INVERTED EXCLAMATION MARK;Lm;0;ON;;;;;N;;;;; -A71F;MODIFIER LETTER LOW INVERTED EXCLAMATION MARK;Lm;0;ON;;;;;N;;;;; -A720;MODIFIER LETTER STRESS AND HIGH TONE;Sk;0;ON;;;;;N;;;;; -A721;MODIFIER LETTER STRESS AND LOW TONE;Sk;0;ON;;;;;N;;;;; -A722;LATIN CAPITAL LETTER EGYPTOLOGICAL ALEF;Lu;0;L;;;;;N;;;;A723; -A723;LATIN SMALL LETTER EGYPTOLOGICAL ALEF;Ll;0;L;;;;;N;;;A722;;A722 -A724;LATIN CAPITAL LETTER EGYPTOLOGICAL AIN;Lu;0;L;;;;;N;;;;A725; -A725;LATIN SMALL LETTER EGYPTOLOGICAL AIN;Ll;0;L;;;;;N;;;A724;;A724 -A726;LATIN CAPITAL LETTER HENG;Lu;0;L;;;;;N;;;;A727; -A727;LATIN SMALL LETTER HENG;Ll;0;L;;;;;N;;;A726;;A726 -A728;LATIN CAPITAL LETTER TZ;Lu;0;L;;;;;N;;;;A729; -A729;LATIN SMALL LETTER TZ;Ll;0;L;;;;;N;;;A728;;A728 -A72A;LATIN CAPITAL LETTER TRESILLO;Lu;0;L;;;;;N;;;;A72B; -A72B;LATIN SMALL LETTER TRESILLO;Ll;0;L;;;;;N;;;A72A;;A72A -A72C;LATIN CAPITAL LETTER CUATRILLO;Lu;0;L;;;;;N;;;;A72D; -A72D;LATIN SMALL LETTER CUATRILLO;Ll;0;L;;;;;N;;;A72C;;A72C -A72E;LATIN CAPITAL LETTER CUATRILLO WITH COMMA;Lu;0;L;;;;;N;;;;A72F; -A72F;LATIN SMALL LETTER CUATRILLO WITH COMMA;Ll;0;L;;;;;N;;;A72E;;A72E -A730;LATIN LETTER SMALL CAPITAL F;Ll;0;L;;;;;N;;;;; -A731;LATIN LETTER SMALL CAPITAL S;Ll;0;L;;;;;N;;;;; -A732;LATIN CAPITAL LETTER AA;Lu;0;L;;;;;N;;;;A733; -A733;LATIN SMALL LETTER AA;Ll;0;L;;;;;N;;;A732;;A732 -A734;LATIN CAPITAL LETTER AO;Lu;0;L;;;;;N;;;;A735; -A735;LATIN SMALL LETTER AO;Ll;0;L;;;;;N;;;A734;;A734 -A736;LATIN CAPITAL LETTER AU;Lu;0;L;;;;;N;;;;A737; -A737;LATIN SMALL LETTER AU;Ll;0;L;;;;;N;;;A736;;A736 -A738;LATIN CAPITAL LETTER AV;Lu;0;L;;;;;N;;;;A739; -A739;LATIN SMALL LETTER AV;Ll;0;L;;;;;N;;;A738;;A738 -A73A;LATIN CAPITAL LETTER AV WITH HORIZONTAL BAR;Lu;0;L;;;;;N;;;;A73B; -A73B;LATIN SMALL LETTER AV WITH HORIZONTAL BAR;Ll;0;L;;;;;N;;;A73A;;A73A -A73C;LATIN CAPITAL LETTER AY;Lu;0;L;;;;;N;;;;A73D; -A73D;LATIN SMALL LETTER AY;Ll;0;L;;;;;N;;;A73C;;A73C -A73E;LATIN CAPITAL LETTER REVERSED C WITH DOT;Lu;0;L;;;;;N;;;;A73F; -A73F;LATIN SMALL LETTER REVERSED C WITH DOT;Ll;0;L;;;;;N;;;A73E;;A73E -A740;LATIN CAPITAL LETTER K WITH STROKE;Lu;0;L;;;;;N;;;;A741; -A741;LATIN SMALL LETTER K WITH STROKE;Ll;0;L;;;;;N;;;A740;;A740 -A742;LATIN CAPITAL LETTER K WITH DIAGONAL STROKE;Lu;0;L;;;;;N;;;;A743; -A743;LATIN SMALL LETTER K WITH DIAGONAL STROKE;Ll;0;L;;;;;N;;;A742;;A742 -A744;LATIN CAPITAL LETTER K WITH STROKE AND DIAGONAL STROKE;Lu;0;L;;;;;N;;;;A745; -A745;LATIN SMALL LETTER K WITH STROKE AND DIAGONAL STROKE;Ll;0;L;;;;;N;;;A744;;A744 -A746;LATIN CAPITAL LETTER BROKEN L;Lu;0;L;;;;;N;;;;A747; -A747;LATIN SMALL LETTER BROKEN L;Ll;0;L;;;;;N;;;A746;;A746 -A748;LATIN CAPITAL LETTER L WITH HIGH STROKE;Lu;0;L;;;;;N;;;;A749; -A749;LATIN SMALL LETTER L WITH HIGH STROKE;Ll;0;L;;;;;N;;;A748;;A748 -A74A;LATIN CAPITAL LETTER O WITH LONG STROKE OVERLAY;Lu;0;L;;;;;N;;;;A74B; -A74B;LATIN SMALL LETTER O WITH LONG STROKE OVERLAY;Ll;0;L;;;;;N;;;A74A;;A74A -A74C;LATIN CAPITAL LETTER O WITH LOOP;Lu;0;L;;;;;N;;;;A74D; -A74D;LATIN SMALL LETTER O WITH LOOP;Ll;0;L;;;;;N;;;A74C;;A74C -A74E;LATIN CAPITAL LETTER OO;Lu;0;L;;;;;N;;;;A74F; -A74F;LATIN SMALL LETTER OO;Ll;0;L;;;;;N;;;A74E;;A74E -A750;LATIN CAPITAL LETTER P WITH STROKE THROUGH DESCENDER;Lu;0;L;;;;;N;;;;A751; -A751;LATIN SMALL LETTER P WITH STROKE THROUGH DESCENDER;Ll;0;L;;;;;N;;;A750;;A750 -A752;LATIN CAPITAL LETTER P WITH FLOURISH;Lu;0;L;;;;;N;;;;A753; -A753;LATIN SMALL LETTER P WITH FLOURISH;Ll;0;L;;;;;N;;;A752;;A752 -A754;LATIN CAPITAL LETTER P WITH SQUIRREL TAIL;Lu;0;L;;;;;N;;;;A755; -A755;LATIN SMALL LETTER P WITH SQUIRREL TAIL;Ll;0;L;;;;;N;;;A754;;A754 -A756;LATIN CAPITAL LETTER Q WITH STROKE THROUGH DESCENDER;Lu;0;L;;;;;N;;;;A757; -A757;LATIN SMALL LETTER Q WITH STROKE THROUGH DESCENDER;Ll;0;L;;;;;N;;;A756;;A756 -A758;LATIN CAPITAL LETTER Q WITH DIAGONAL STROKE;Lu;0;L;;;;;N;;;;A759; -A759;LATIN SMALL LETTER Q WITH DIAGONAL STROKE;Ll;0;L;;;;;N;;;A758;;A758 -A75A;LATIN CAPITAL LETTER R ROTUNDA;Lu;0;L;;;;;N;;;;A75B; -A75B;LATIN SMALL LETTER R ROTUNDA;Ll;0;L;;;;;N;;;A75A;;A75A -A75C;LATIN CAPITAL LETTER RUM ROTUNDA;Lu;0;L;;;;;N;;;;A75D; -A75D;LATIN SMALL LETTER RUM ROTUNDA;Ll;0;L;;;;;N;;;A75C;;A75C -A75E;LATIN CAPITAL LETTER V WITH DIAGONAL STROKE;Lu;0;L;;;;;N;;;;A75F; -A75F;LATIN SMALL LETTER V WITH DIAGONAL STROKE;Ll;0;L;;;;;N;;;A75E;;A75E -A760;LATIN CAPITAL LETTER VY;Lu;0;L;;;;;N;;;;A761; -A761;LATIN SMALL LETTER VY;Ll;0;L;;;;;N;;;A760;;A760 -A762;LATIN CAPITAL LETTER VISIGOTHIC Z;Lu;0;L;;;;;N;;;;A763; -A763;LATIN SMALL LETTER VISIGOTHIC Z;Ll;0;L;;;;;N;;;A762;;A762 -A764;LATIN CAPITAL LETTER THORN WITH STROKE;Lu;0;L;;;;;N;;;;A765; -A765;LATIN SMALL LETTER THORN WITH STROKE;Ll;0;L;;;;;N;;;A764;;A764 -A766;LATIN CAPITAL LETTER THORN WITH STROKE THROUGH DESCENDER;Lu;0;L;;;;;N;;;;A767; -A767;LATIN SMALL LETTER THORN WITH STROKE THROUGH DESCENDER;Ll;0;L;;;;;N;;;A766;;A766 -A768;LATIN CAPITAL LETTER VEND;Lu;0;L;;;;;N;;;;A769; -A769;LATIN SMALL LETTER VEND;Ll;0;L;;;;;N;;;A768;;A768 -A76A;LATIN CAPITAL LETTER ET;Lu;0;L;;;;;N;;;;A76B; -A76B;LATIN SMALL LETTER ET;Ll;0;L;;;;;N;;;A76A;;A76A -A76C;LATIN CAPITAL LETTER IS;Lu;0;L;;;;;N;;;;A76D; -A76D;LATIN SMALL LETTER IS;Ll;0;L;;;;;N;;;A76C;;A76C -A76E;LATIN CAPITAL LETTER CON;Lu;0;L;;;;;N;;;;A76F; -A76F;LATIN SMALL LETTER CON;Ll;0;L;;;;;N;;;A76E;;A76E -A770;MODIFIER LETTER US;Lm;0;L; A76F;;;;N;;;;; -A771;LATIN SMALL LETTER DUM;Ll;0;L;;;;;N;;;;; -A772;LATIN SMALL LETTER LUM;Ll;0;L;;;;;N;;;;; -A773;LATIN SMALL LETTER MUM;Ll;0;L;;;;;N;;;;; -A774;LATIN SMALL LETTER NUM;Ll;0;L;;;;;N;;;;; -A775;LATIN SMALL LETTER RUM;Ll;0;L;;;;;N;;;;; -A776;LATIN LETTER SMALL CAPITAL RUM;Ll;0;L;;;;;N;;;;; -A777;LATIN SMALL LETTER TUM;Ll;0;L;;;;;N;;;;; -A778;LATIN SMALL LETTER UM;Ll;0;L;;;;;N;;;;; -A779;LATIN CAPITAL LETTER INSULAR D;Lu;0;L;;;;;N;;;;A77A; -A77A;LATIN SMALL LETTER INSULAR D;Ll;0;L;;;;;N;;;A779;;A779 -A77B;LATIN CAPITAL LETTER INSULAR F;Lu;0;L;;;;;N;;;;A77C; -A77C;LATIN SMALL LETTER INSULAR F;Ll;0;L;;;;;N;;;A77B;;A77B -A77D;LATIN CAPITAL LETTER INSULAR G;Lu;0;L;;;;;N;;;;1D79; -A77E;LATIN CAPITAL LETTER TURNED INSULAR G;Lu;0;L;;;;;N;;;;A77F; -A77F;LATIN SMALL LETTER TURNED INSULAR G;Ll;0;L;;;;;N;;;A77E;;A77E -A780;LATIN CAPITAL LETTER TURNED L;Lu;0;L;;;;;N;;;;A781; -A781;LATIN SMALL LETTER TURNED L;Ll;0;L;;;;;N;;;A780;;A780 -A782;LATIN CAPITAL LETTER INSULAR R;Lu;0;L;;;;;N;;;;A783; -A783;LATIN SMALL LETTER INSULAR R;Ll;0;L;;;;;N;;;A782;;A782 -A784;LATIN CAPITAL LETTER INSULAR S;Lu;0;L;;;;;N;;;;A785; -A785;LATIN SMALL LETTER INSULAR S;Ll;0;L;;;;;N;;;A784;;A784 -A786;LATIN CAPITAL LETTER INSULAR T;Lu;0;L;;;;;N;;;;A787; -A787;LATIN SMALL LETTER INSULAR T;Ll;0;L;;;;;N;;;A786;;A786 -A788;MODIFIER LETTER LOW CIRCUMFLEX ACCENT;Lm;0;ON;;;;;N;;;;; -A789;MODIFIER LETTER COLON;Sk;0;L;;;;;N;;;;; -A78A;MODIFIER LETTER SHORT EQUALS SIGN;Sk;0;L;;;;;N;;;;; -A78B;LATIN CAPITAL LETTER SALTILLO;Lu;0;L;;;;;N;;;;A78C; -A78C;LATIN SMALL LETTER SALTILLO;Ll;0;L;;;;;N;;;A78B;;A78B -A7FB;LATIN EPIGRAPHIC LETTER REVERSED F;Lo;0;L;;;;;N;;;;; -A7FC;LATIN EPIGRAPHIC LETTER REVERSED P;Lo;0;L;;;;;N;;;;; -A7FD;LATIN EPIGRAPHIC LETTER INVERTED M;Lo;0;L;;;;;N;;;;; -A7FE;LATIN EPIGRAPHIC LETTER I LONGA;Lo;0;L;;;;;N;;;;; -A7FF;LATIN EPIGRAPHIC LETTER ARCHAIC M;Lo;0;L;;;;;N;;;;; -A800;SYLOTI NAGRI LETTER A;Lo;0;L;;;;;N;;;;; -A801;SYLOTI NAGRI LETTER I;Lo;0;L;;;;;N;;;;; -A802;SYLOTI NAGRI SIGN DVISVARA;Mn;0;NSM;;;;;N;;;;; -A803;SYLOTI NAGRI LETTER U;Lo;0;L;;;;;N;;;;; -A804;SYLOTI NAGRI LETTER E;Lo;0;L;;;;;N;;;;; -A805;SYLOTI NAGRI LETTER O;Lo;0;L;;;;;N;;;;; -A806;SYLOTI NAGRI SIGN HASANTA;Mn;9;NSM;;;;;N;;;;; -A807;SYLOTI NAGRI LETTER KO;Lo;0;L;;;;;N;;;;; -A808;SYLOTI NAGRI LETTER KHO;Lo;0;L;;;;;N;;;;; -A809;SYLOTI NAGRI LETTER GO;Lo;0;L;;;;;N;;;;; -A80A;SYLOTI NAGRI LETTER GHO;Lo;0;L;;;;;N;;;;; -A80B;SYLOTI NAGRI SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -A80C;SYLOTI NAGRI LETTER CO;Lo;0;L;;;;;N;;;;; -A80D;SYLOTI NAGRI LETTER CHO;Lo;0;L;;;;;N;;;;; -A80E;SYLOTI NAGRI LETTER JO;Lo;0;L;;;;;N;;;;; -A80F;SYLOTI NAGRI LETTER JHO;Lo;0;L;;;;;N;;;;; -A810;SYLOTI NAGRI LETTER TTO;Lo;0;L;;;;;N;;;;; -A811;SYLOTI NAGRI LETTER TTHO;Lo;0;L;;;;;N;;;;; -A812;SYLOTI NAGRI LETTER DDO;Lo;0;L;;;;;N;;;;; -A813;SYLOTI NAGRI LETTER DDHO;Lo;0;L;;;;;N;;;;; -A814;SYLOTI NAGRI LETTER TO;Lo;0;L;;;;;N;;;;; -A815;SYLOTI NAGRI LETTER THO;Lo;0;L;;;;;N;;;;; -A816;SYLOTI NAGRI LETTER DO;Lo;0;L;;;;;N;;;;; -A817;SYLOTI NAGRI LETTER DHO;Lo;0;L;;;;;N;;;;; -A818;SYLOTI NAGRI LETTER NO;Lo;0;L;;;;;N;;;;; -A819;SYLOTI NAGRI LETTER PO;Lo;0;L;;;;;N;;;;; -A81A;SYLOTI NAGRI LETTER PHO;Lo;0;L;;;;;N;;;;; -A81B;SYLOTI NAGRI LETTER BO;Lo;0;L;;;;;N;;;;; -A81C;SYLOTI NAGRI LETTER BHO;Lo;0;L;;;;;N;;;;; -A81D;SYLOTI NAGRI LETTER MO;Lo;0;L;;;;;N;;;;; -A81E;SYLOTI NAGRI LETTER RO;Lo;0;L;;;;;N;;;;; -A81F;SYLOTI NAGRI LETTER LO;Lo;0;L;;;;;N;;;;; -A820;SYLOTI NAGRI LETTER RRO;Lo;0;L;;;;;N;;;;; -A821;SYLOTI NAGRI LETTER SO;Lo;0;L;;;;;N;;;;; -A822;SYLOTI NAGRI LETTER HO;Lo;0;L;;;;;N;;;;; -A823;SYLOTI NAGRI VOWEL SIGN A;Mc;0;L;;;;;N;;;;; -A824;SYLOTI NAGRI VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -A825;SYLOTI NAGRI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -A826;SYLOTI NAGRI VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -A827;SYLOTI NAGRI VOWEL SIGN OO;Mc;0;L;;;;;N;;;;; -A828;SYLOTI NAGRI POETRY MARK-1;So;0;ON;;;;;N;;;;; -A829;SYLOTI NAGRI POETRY MARK-2;So;0;ON;;;;;N;;;;; -A82A;SYLOTI NAGRI POETRY MARK-3;So;0;ON;;;;;N;;;;; -A82B;SYLOTI NAGRI POETRY MARK-4;So;0;ON;;;;;N;;;;; -A840;PHAGS-PA LETTER KA;Lo;0;L;;;;;N;;;;; -A841;PHAGS-PA LETTER KHA;Lo;0;L;;;;;N;;;;; -A842;PHAGS-PA LETTER GA;Lo;0;L;;;;;N;;;;; -A843;PHAGS-PA LETTER NGA;Lo;0;L;;;;;N;;;;; -A844;PHAGS-PA LETTER CA;Lo;0;L;;;;;N;;;;; -A845;PHAGS-PA LETTER CHA;Lo;0;L;;;;;N;;;;; -A846;PHAGS-PA LETTER JA;Lo;0;L;;;;;N;;;;; -A847;PHAGS-PA LETTER NYA;Lo;0;L;;;;;N;;;;; -A848;PHAGS-PA LETTER TA;Lo;0;L;;;;;N;;;;; -A849;PHAGS-PA LETTER THA;Lo;0;L;;;;;N;;;;; -A84A;PHAGS-PA LETTER DA;Lo;0;L;;;;;N;;;;; -A84B;PHAGS-PA LETTER NA;Lo;0;L;;;;;N;;;;; -A84C;PHAGS-PA LETTER PA;Lo;0;L;;;;;N;;;;; -A84D;PHAGS-PA LETTER PHA;Lo;0;L;;;;;N;;;;; -A84E;PHAGS-PA LETTER BA;Lo;0;L;;;;;N;;;;; -A84F;PHAGS-PA LETTER MA;Lo;0;L;;;;;N;;;;; -A850;PHAGS-PA LETTER TSA;Lo;0;L;;;;;N;;;;; -A851;PHAGS-PA LETTER TSHA;Lo;0;L;;;;;N;;;;; -A852;PHAGS-PA LETTER DZA;Lo;0;L;;;;;N;;;;; -A853;PHAGS-PA LETTER WA;Lo;0;L;;;;;N;;;;; -A854;PHAGS-PA LETTER ZHA;Lo;0;L;;;;;N;;;;; -A855;PHAGS-PA LETTER ZA;Lo;0;L;;;;;N;;;;; -A856;PHAGS-PA LETTER SMALL A;Lo;0;L;;;;;N;;;;; -A857;PHAGS-PA LETTER YA;Lo;0;L;;;;;N;;;;; -A858;PHAGS-PA LETTER RA;Lo;0;L;;;;;N;;;;; -A859;PHAGS-PA LETTER LA;Lo;0;L;;;;;N;;;;; -A85A;PHAGS-PA LETTER SHA;Lo;0;L;;;;;N;;;;; -A85B;PHAGS-PA LETTER SA;Lo;0;L;;;;;N;;;;; -A85C;PHAGS-PA LETTER HA;Lo;0;L;;;;;N;;;;; -A85D;PHAGS-PA LETTER A;Lo;0;L;;;;;N;;;;; -A85E;PHAGS-PA LETTER I;Lo;0;L;;;;;N;;;;; -A85F;PHAGS-PA LETTER U;Lo;0;L;;;;;N;;;;; -A860;PHAGS-PA LETTER E;Lo;0;L;;;;;N;;;;; -A861;PHAGS-PA LETTER O;Lo;0;L;;;;;N;;;;; -A862;PHAGS-PA LETTER QA;Lo;0;L;;;;;N;;;;; -A863;PHAGS-PA LETTER XA;Lo;0;L;;;;;N;;;;; -A864;PHAGS-PA LETTER FA;Lo;0;L;;;;;N;;;;; -A865;PHAGS-PA LETTER GGA;Lo;0;L;;;;;N;;;;; -A866;PHAGS-PA LETTER EE;Lo;0;L;;;;;N;;;;; -A867;PHAGS-PA SUBJOINED LETTER WA;Lo;0;L;;;;;N;;;;; -A868;PHAGS-PA SUBJOINED LETTER YA;Lo;0;L;;;;;N;;;;; -A869;PHAGS-PA LETTER TTA;Lo;0;L;;;;;N;;;;; -A86A;PHAGS-PA LETTER TTHA;Lo;0;L;;;;;N;;;;; -A86B;PHAGS-PA LETTER DDA;Lo;0;L;;;;;N;;;;; -A86C;PHAGS-PA LETTER NNA;Lo;0;L;;;;;N;;;;; -A86D;PHAGS-PA LETTER ALTERNATE YA;Lo;0;L;;;;;N;;;;; -A86E;PHAGS-PA LETTER VOICELESS SHA;Lo;0;L;;;;;N;;;;; -A86F;PHAGS-PA LETTER VOICED HA;Lo;0;L;;;;;N;;;;; -A870;PHAGS-PA LETTER ASPIRATED FA;Lo;0;L;;;;;N;;;;; -A871;PHAGS-PA SUBJOINED LETTER RA;Lo;0;L;;;;;N;;;;; -A872;PHAGS-PA SUPERFIXED LETTER RA;Lo;0;L;;;;;N;;;;; -A873;PHAGS-PA LETTER CANDRABINDU;Lo;0;L;;;;;N;;;;; -A874;PHAGS-PA SINGLE HEAD MARK;Po;0;ON;;;;;N;;;;; -A875;PHAGS-PA DOUBLE HEAD MARK;Po;0;ON;;;;;N;;;;; -A876;PHAGS-PA MARK SHAD;Po;0;ON;;;;;N;;;;; -A877;PHAGS-PA MARK DOUBLE SHAD;Po;0;ON;;;;;N;;;;; -A880;SAURASHTRA SIGN ANUSVARA;Mc;0;L;;;;;N;;;;; -A881;SAURASHTRA SIGN VISARGA;Mc;0;L;;;;;N;;;;; -A882;SAURASHTRA LETTER A;Lo;0;L;;;;;N;;;;; -A883;SAURASHTRA LETTER AA;Lo;0;L;;;;;N;;;;; -A884;SAURASHTRA LETTER I;Lo;0;L;;;;;N;;;;; -A885;SAURASHTRA LETTER II;Lo;0;L;;;;;N;;;;; -A886;SAURASHTRA LETTER U;Lo;0;L;;;;;N;;;;; -A887;SAURASHTRA LETTER UU;Lo;0;L;;;;;N;;;;; -A888;SAURASHTRA LETTER VOCALIC R;Lo;0;L;;;;;N;;;;; -A889;SAURASHTRA LETTER VOCALIC RR;Lo;0;L;;;;;N;;;;; -A88A;SAURASHTRA LETTER VOCALIC L;Lo;0;L;;;;;N;;;;; -A88B;SAURASHTRA LETTER VOCALIC LL;Lo;0;L;;;;;N;;;;; -A88C;SAURASHTRA LETTER E;Lo;0;L;;;;;N;;;;; -A88D;SAURASHTRA LETTER EE;Lo;0;L;;;;;N;;;;; -A88E;SAURASHTRA LETTER AI;Lo;0;L;;;;;N;;;;; -A88F;SAURASHTRA LETTER O;Lo;0;L;;;;;N;;;;; -A890;SAURASHTRA LETTER OO;Lo;0;L;;;;;N;;;;; -A891;SAURASHTRA LETTER AU;Lo;0;L;;;;;N;;;;; -A892;SAURASHTRA LETTER KA;Lo;0;L;;;;;N;;;;; -A893;SAURASHTRA LETTER KHA;Lo;0;L;;;;;N;;;;; -A894;SAURASHTRA LETTER GA;Lo;0;L;;;;;N;;;;; -A895;SAURASHTRA LETTER GHA;Lo;0;L;;;;;N;;;;; -A896;SAURASHTRA LETTER NGA;Lo;0;L;;;;;N;;;;; -A897;SAURASHTRA LETTER CA;Lo;0;L;;;;;N;;;;; -A898;SAURASHTRA LETTER CHA;Lo;0;L;;;;;N;;;;; -A899;SAURASHTRA LETTER JA;Lo;0;L;;;;;N;;;;; -A89A;SAURASHTRA LETTER JHA;Lo;0;L;;;;;N;;;;; -A89B;SAURASHTRA LETTER NYA;Lo;0;L;;;;;N;;;;; -A89C;SAURASHTRA LETTER TTA;Lo;0;L;;;;;N;;;;; -A89D;SAURASHTRA LETTER TTHA;Lo;0;L;;;;;N;;;;; -A89E;SAURASHTRA LETTER DDA;Lo;0;L;;;;;N;;;;; -A89F;SAURASHTRA LETTER DDHA;Lo;0;L;;;;;N;;;;; -A8A0;SAURASHTRA LETTER NNA;Lo;0;L;;;;;N;;;;; -A8A1;SAURASHTRA LETTER TA;Lo;0;L;;;;;N;;;;; -A8A2;SAURASHTRA LETTER THA;Lo;0;L;;;;;N;;;;; -A8A3;SAURASHTRA LETTER DA;Lo;0;L;;;;;N;;;;; -A8A4;SAURASHTRA LETTER DHA;Lo;0;L;;;;;N;;;;; -A8A5;SAURASHTRA LETTER NA;Lo;0;L;;;;;N;;;;; -A8A6;SAURASHTRA LETTER PA;Lo;0;L;;;;;N;;;;; -A8A7;SAURASHTRA LETTER PHA;Lo;0;L;;;;;N;;;;; -A8A8;SAURASHTRA LETTER BA;Lo;0;L;;;;;N;;;;; -A8A9;SAURASHTRA LETTER BHA;Lo;0;L;;;;;N;;;;; -A8AA;SAURASHTRA LETTER MA;Lo;0;L;;;;;N;;;;; -A8AB;SAURASHTRA LETTER YA;Lo;0;L;;;;;N;;;;; -A8AC;SAURASHTRA LETTER RA;Lo;0;L;;;;;N;;;;; -A8AD;SAURASHTRA LETTER LA;Lo;0;L;;;;;N;;;;; -A8AE;SAURASHTRA LETTER VA;Lo;0;L;;;;;N;;;;; -A8AF;SAURASHTRA LETTER SHA;Lo;0;L;;;;;N;;;;; -A8B0;SAURASHTRA LETTER SSA;Lo;0;L;;;;;N;;;;; -A8B1;SAURASHTRA LETTER SA;Lo;0;L;;;;;N;;;;; -A8B2;SAURASHTRA LETTER HA;Lo;0;L;;;;;N;;;;; -A8B3;SAURASHTRA LETTER LLA;Lo;0;L;;;;;N;;;;; -A8B4;SAURASHTRA CONSONANT SIGN HAARU;Mc;0;L;;;;;N;;;;; -A8B5;SAURASHTRA VOWEL SIGN AA;Mc;0;L;;;;;N;;;;; -A8B6;SAURASHTRA VOWEL SIGN I;Mc;0;L;;;;;N;;;;; -A8B7;SAURASHTRA VOWEL SIGN II;Mc;0;L;;;;;N;;;;; -A8B8;SAURASHTRA VOWEL SIGN U;Mc;0;L;;;;;N;;;;; -A8B9;SAURASHTRA VOWEL SIGN UU;Mc;0;L;;;;;N;;;;; -A8BA;SAURASHTRA VOWEL SIGN VOCALIC R;Mc;0;L;;;;;N;;;;; -A8BB;SAURASHTRA VOWEL SIGN VOCALIC RR;Mc;0;L;;;;;N;;;;; -A8BC;SAURASHTRA VOWEL SIGN VOCALIC L;Mc;0;L;;;;;N;;;;; -A8BD;SAURASHTRA VOWEL SIGN VOCALIC LL;Mc;0;L;;;;;N;;;;; -A8BE;SAURASHTRA VOWEL SIGN E;Mc;0;L;;;;;N;;;;; -A8BF;SAURASHTRA VOWEL SIGN EE;Mc;0;L;;;;;N;;;;; -A8C0;SAURASHTRA VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -A8C1;SAURASHTRA VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -A8C2;SAURASHTRA VOWEL SIGN OO;Mc;0;L;;;;;N;;;;; -A8C3;SAURASHTRA VOWEL SIGN AU;Mc;0;L;;;;;N;;;;; -A8C4;SAURASHTRA SIGN VIRAMA;Mn;9;NSM;;;;;N;;;;; -A8CE;SAURASHTRA DANDA;Po;0;L;;;;;N;;;;; -A8CF;SAURASHTRA DOUBLE DANDA;Po;0;L;;;;;N;;;;; -A8D0;SAURASHTRA DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -A8D1;SAURASHTRA DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -A8D2;SAURASHTRA DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -A8D3;SAURASHTRA DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -A8D4;SAURASHTRA DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -A8D5;SAURASHTRA DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -A8D6;SAURASHTRA DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -A8D7;SAURASHTRA DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -A8D8;SAURASHTRA DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -A8D9;SAURASHTRA DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -A900;KAYAH LI DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -A901;KAYAH LI DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -A902;KAYAH LI DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -A903;KAYAH LI DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -A904;KAYAH LI DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -A905;KAYAH LI DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -A906;KAYAH LI DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -A907;KAYAH LI DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -A908;KAYAH LI DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -A909;KAYAH LI DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -A90A;KAYAH LI LETTER KA;Lo;0;L;;;;;N;;;;; -A90B;KAYAH LI LETTER KHA;Lo;0;L;;;;;N;;;;; -A90C;KAYAH LI LETTER GA;Lo;0;L;;;;;N;;;;; -A90D;KAYAH LI LETTER NGA;Lo;0;L;;;;;N;;;;; -A90E;KAYAH LI LETTER SA;Lo;0;L;;;;;N;;;;; -A90F;KAYAH LI LETTER SHA;Lo;0;L;;;;;N;;;;; -A910;KAYAH LI LETTER ZA;Lo;0;L;;;;;N;;;;; -A911;KAYAH LI LETTER NYA;Lo;0;L;;;;;N;;;;; -A912;KAYAH LI LETTER TA;Lo;0;L;;;;;N;;;;; -A913;KAYAH LI LETTER HTA;Lo;0;L;;;;;N;;;;; -A914;KAYAH LI LETTER NA;Lo;0;L;;;;;N;;;;; -A915;KAYAH LI LETTER PA;Lo;0;L;;;;;N;;;;; -A916;KAYAH LI LETTER PHA;Lo;0;L;;;;;N;;;;; -A917;KAYAH LI LETTER MA;Lo;0;L;;;;;N;;;;; -A918;KAYAH LI LETTER DA;Lo;0;L;;;;;N;;;;; -A919;KAYAH LI LETTER BA;Lo;0;L;;;;;N;;;;; -A91A;KAYAH LI LETTER RA;Lo;0;L;;;;;N;;;;; -A91B;KAYAH LI LETTER YA;Lo;0;L;;;;;N;;;;; -A91C;KAYAH LI LETTER LA;Lo;0;L;;;;;N;;;;; -A91D;KAYAH LI LETTER WA;Lo;0;L;;;;;N;;;;; -A91E;KAYAH LI LETTER THA;Lo;0;L;;;;;N;;;;; -A91F;KAYAH LI LETTER HA;Lo;0;L;;;;;N;;;;; -A920;KAYAH LI LETTER VA;Lo;0;L;;;;;N;;;;; -A921;KAYAH LI LETTER CA;Lo;0;L;;;;;N;;;;; -A922;KAYAH LI LETTER A;Lo;0;L;;;;;N;;;;; -A923;KAYAH LI LETTER OE;Lo;0;L;;;;;N;;;;; -A924;KAYAH LI LETTER I;Lo;0;L;;;;;N;;;;; -A925;KAYAH LI LETTER OO;Lo;0;L;;;;;N;;;;; -A926;KAYAH LI VOWEL UE;Mn;0;NSM;;;;;N;;;;; -A927;KAYAH LI VOWEL E;Mn;0;NSM;;;;;N;;;;; -A928;KAYAH LI VOWEL U;Mn;0;NSM;;;;;N;;;;; -A929;KAYAH LI VOWEL EE;Mn;0;NSM;;;;;N;;;;; -A92A;KAYAH LI VOWEL O;Mn;0;NSM;;;;;N;;;;; -A92B;KAYAH LI TONE PLOPHU;Mn;220;NSM;;;;;N;;;;; -A92C;KAYAH LI TONE CALYA;Mn;220;NSM;;;;;N;;;;; -A92D;KAYAH LI TONE CALYA PLOPHU;Mn;220;NSM;;;;;N;;;;; -A92E;KAYAH LI SIGN CWI;Po;0;L;;;;;N;;;;; -A92F;KAYAH LI SIGN SHYA;Po;0;L;;;;;N;;;;; -A930;REJANG LETTER KA;Lo;0;L;;;;;N;;;;; -A931;REJANG LETTER GA;Lo;0;L;;;;;N;;;;; -A932;REJANG LETTER NGA;Lo;0;L;;;;;N;;;;; -A933;REJANG LETTER TA;Lo;0;L;;;;;N;;;;; -A934;REJANG LETTER DA;Lo;0;L;;;;;N;;;;; -A935;REJANG LETTER NA;Lo;0;L;;;;;N;;;;; -A936;REJANG LETTER PA;Lo;0;L;;;;;N;;;;; -A937;REJANG LETTER BA;Lo;0;L;;;;;N;;;;; -A938;REJANG LETTER MA;Lo;0;L;;;;;N;;;;; -A939;REJANG LETTER CA;Lo;0;L;;;;;N;;;;; -A93A;REJANG LETTER JA;Lo;0;L;;;;;N;;;;; -A93B;REJANG LETTER NYA;Lo;0;L;;;;;N;;;;; -A93C;REJANG LETTER SA;Lo;0;L;;;;;N;;;;; -A93D;REJANG LETTER RA;Lo;0;L;;;;;N;;;;; -A93E;REJANG LETTER LA;Lo;0;L;;;;;N;;;;; -A93F;REJANG LETTER YA;Lo;0;L;;;;;N;;;;; -A940;REJANG LETTER WA;Lo;0;L;;;;;N;;;;; -A941;REJANG LETTER HA;Lo;0;L;;;;;N;;;;; -A942;REJANG LETTER MBA;Lo;0;L;;;;;N;;;;; -A943;REJANG LETTER NGGA;Lo;0;L;;;;;N;;;;; -A944;REJANG LETTER NDA;Lo;0;L;;;;;N;;;;; -A945;REJANG LETTER NYJA;Lo;0;L;;;;;N;;;;; -A946;REJANG LETTER A;Lo;0;L;;;;;N;;;;; -A947;REJANG VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -A948;REJANG VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -A949;REJANG VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -A94A;REJANG VOWEL SIGN AI;Mn;0;NSM;;;;;N;;;;; -A94B;REJANG VOWEL SIGN O;Mn;0;NSM;;;;;N;;;;; -A94C;REJANG VOWEL SIGN AU;Mn;0;NSM;;;;;N;;;;; -A94D;REJANG VOWEL SIGN EU;Mn;0;NSM;;;;;N;;;;; -A94E;REJANG VOWEL SIGN EA;Mn;0;NSM;;;;;N;;;;; -A94F;REJANG CONSONANT SIGN NG;Mn;0;NSM;;;;;N;;;;; -A950;REJANG CONSONANT SIGN N;Mn;0;NSM;;;;;N;;;;; -A951;REJANG CONSONANT SIGN R;Mn;0;NSM;;;;;N;;;;; -A952;REJANG CONSONANT SIGN H;Mc;0;L;;;;;N;;;;; -A953;REJANG VIRAMA;Mc;9;L;;;;;N;;;;; -A95F;REJANG SECTION MARK;Po;0;L;;;;;N;;;;; -AA00;CHAM LETTER A;Lo;0;L;;;;;N;;;;; -AA01;CHAM LETTER I;Lo;0;L;;;;;N;;;;; -AA02;CHAM LETTER U;Lo;0;L;;;;;N;;;;; -AA03;CHAM LETTER E;Lo;0;L;;;;;N;;;;; -AA04;CHAM LETTER AI;Lo;0;L;;;;;N;;;;; -AA05;CHAM LETTER O;Lo;0;L;;;;;N;;;;; -AA06;CHAM LETTER KA;Lo;0;L;;;;;N;;;;; -AA07;CHAM LETTER KHA;Lo;0;L;;;;;N;;;;; -AA08;CHAM LETTER GA;Lo;0;L;;;;;N;;;;; -AA09;CHAM LETTER GHA;Lo;0;L;;;;;N;;;;; -AA0A;CHAM LETTER NGUE;Lo;0;L;;;;;N;;;;; -AA0B;CHAM LETTER NGA;Lo;0;L;;;;;N;;;;; -AA0C;CHAM LETTER CHA;Lo;0;L;;;;;N;;;;; -AA0D;CHAM LETTER CHHA;Lo;0;L;;;;;N;;;;; -AA0E;CHAM LETTER JA;Lo;0;L;;;;;N;;;;; -AA0F;CHAM LETTER JHA;Lo;0;L;;;;;N;;;;; -AA10;CHAM LETTER NHUE;Lo;0;L;;;;;N;;;;; -AA11;CHAM LETTER NHA;Lo;0;L;;;;;N;;;;; -AA12;CHAM LETTER NHJA;Lo;0;L;;;;;N;;;;; -AA13;CHAM LETTER TA;Lo;0;L;;;;;N;;;;; -AA14;CHAM LETTER THA;Lo;0;L;;;;;N;;;;; -AA15;CHAM LETTER DA;Lo;0;L;;;;;N;;;;; -AA16;CHAM LETTER DHA;Lo;0;L;;;;;N;;;;; -AA17;CHAM LETTER NUE;Lo;0;L;;;;;N;;;;; -AA18;CHAM LETTER NA;Lo;0;L;;;;;N;;;;; -AA19;CHAM LETTER DDA;Lo;0;L;;;;;N;;;;; -AA1A;CHAM LETTER PA;Lo;0;L;;;;;N;;;;; -AA1B;CHAM LETTER PPA;Lo;0;L;;;;;N;;;;; -AA1C;CHAM LETTER PHA;Lo;0;L;;;;;N;;;;; -AA1D;CHAM LETTER BA;Lo;0;L;;;;;N;;;;; -AA1E;CHAM LETTER BHA;Lo;0;L;;;;;N;;;;; -AA1F;CHAM LETTER MUE;Lo;0;L;;;;;N;;;;; -AA20;CHAM LETTER MA;Lo;0;L;;;;;N;;;;; -AA21;CHAM LETTER BBA;Lo;0;L;;;;;N;;;;; -AA22;CHAM LETTER YA;Lo;0;L;;;;;N;;;;; -AA23;CHAM LETTER RA;Lo;0;L;;;;;N;;;;; -AA24;CHAM LETTER LA;Lo;0;L;;;;;N;;;;; -AA25;CHAM LETTER VA;Lo;0;L;;;;;N;;;;; -AA26;CHAM LETTER SSA;Lo;0;L;;;;;N;;;;; -AA27;CHAM LETTER SA;Lo;0;L;;;;;N;;;;; -AA28;CHAM LETTER HA;Lo;0;L;;;;;N;;;;; -AA29;CHAM VOWEL SIGN AA;Mn;0;NSM;;;;;N;;;;; -AA2A;CHAM VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -AA2B;CHAM VOWEL SIGN II;Mn;0;NSM;;;;;N;;;;; -AA2C;CHAM VOWEL SIGN EI;Mn;0;NSM;;;;;N;;;;; -AA2D;CHAM VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -AA2E;CHAM VOWEL SIGN OE;Mn;0;NSM;;;;;N;;;;; -AA2F;CHAM VOWEL SIGN O;Mc;0;L;;;;;N;;;;; -AA30;CHAM VOWEL SIGN AI;Mc;0;L;;;;;N;;;;; -AA31;CHAM VOWEL SIGN AU;Mn;0;NSM;;;;;N;;;;; -AA32;CHAM VOWEL SIGN UE;Mn;0;NSM;;;;;N;;;;; -AA33;CHAM CONSONANT SIGN YA;Mc;0;L;;;;;N;;;;; -AA34;CHAM CONSONANT SIGN RA;Mc;0;L;;;;;N;;;;; -AA35;CHAM CONSONANT SIGN LA;Mn;0;NSM;;;;;N;;;;; -AA36;CHAM CONSONANT SIGN WA;Mn;0;NSM;;;;;N;;;;; -AA40;CHAM LETTER FINAL K;Lo;0;L;;;;;N;;;;; -AA41;CHAM LETTER FINAL G;Lo;0;L;;;;;N;;;;; -AA42;CHAM LETTER FINAL NG;Lo;0;L;;;;;N;;;;; -AA43;CHAM CONSONANT SIGN FINAL NG;Mn;0;NSM;;;;;N;;;;; -AA44;CHAM LETTER FINAL CH;Lo;0;L;;;;;N;;;;; -AA45;CHAM LETTER FINAL T;Lo;0;L;;;;;N;;;;; -AA46;CHAM LETTER FINAL N;Lo;0;L;;;;;N;;;;; -AA47;CHAM LETTER FINAL P;Lo;0;L;;;;;N;;;;; -AA48;CHAM LETTER FINAL Y;Lo;0;L;;;;;N;;;;; -AA49;CHAM LETTER FINAL R;Lo;0;L;;;;;N;;;;; -AA4A;CHAM LETTER FINAL L;Lo;0;L;;;;;N;;;;; -AA4B;CHAM LETTER FINAL SS;Lo;0;L;;;;;N;;;;; -AA4C;CHAM CONSONANT SIGN FINAL M;Mn;0;NSM;;;;;N;;;;; -AA4D;CHAM CONSONANT SIGN FINAL H;Mc;0;L;;;;;N;;;;; -AA50;CHAM DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -AA51;CHAM DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -AA52;CHAM DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -AA53;CHAM DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -AA54;CHAM DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -AA55;CHAM DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -AA56;CHAM DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -AA57;CHAM DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -AA58;CHAM DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -AA59;CHAM DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -AA5C;CHAM PUNCTUATION SPIRAL;Po;0;L;;;;;N;;;;; -AA5D;CHAM PUNCTUATION DANDA;Po;0;L;;;;;N;;;;; -AA5E;CHAM PUNCTUATION DOUBLE DANDA;Po;0;L;;;;;N;;;;; -AA5F;CHAM PUNCTUATION TRIPLE DANDA;Po;0;L;;;;;N;;;;; -AC00;;Lo;0;L;;;;;N;;;;; -D7A3;;Lo;0;L;;;;;N;;;;; -D800;;Cs;0;L;;;;;N;;;;; -DB7F;;Cs;0;L;;;;;N;;;;; -DB80;;Cs;0;L;;;;;N;;;;; -DBFF;;Cs;0;L;;;;;N;;;;; -DC00;;Cs;0;L;;;;;N;;;;; -DFFF;;Cs;0;L;;;;;N;;;;; -E000;;Co;0;L;;;;;N;;;;; -F8FF;;Co;0;L;;;;;N;;;;; -F900;CJK COMPATIBILITY IDEOGRAPH-F900;Lo;0;L;8C48;;;;N;;;;; -F901;CJK COMPATIBILITY IDEOGRAPH-F901;Lo;0;L;66F4;;;;N;;;;; -F902;CJK COMPATIBILITY IDEOGRAPH-F902;Lo;0;L;8ECA;;;;N;;;;; -F903;CJK COMPATIBILITY IDEOGRAPH-F903;Lo;0;L;8CC8;;;;N;;;;; -F904;CJK COMPATIBILITY IDEOGRAPH-F904;Lo;0;L;6ED1;;;;N;;;;; -F905;CJK COMPATIBILITY IDEOGRAPH-F905;Lo;0;L;4E32;;;;N;;;;; -F906;CJK COMPATIBILITY IDEOGRAPH-F906;Lo;0;L;53E5;;;;N;;;;; -F907;CJK COMPATIBILITY IDEOGRAPH-F907;Lo;0;L;9F9C;;;;N;;;;; -F908;CJK COMPATIBILITY IDEOGRAPH-F908;Lo;0;L;9F9C;;;;N;;;;; -F909;CJK COMPATIBILITY IDEOGRAPH-F909;Lo;0;L;5951;;;;N;;;;; -F90A;CJK COMPATIBILITY IDEOGRAPH-F90A;Lo;0;L;91D1;;;;N;;;;; -F90B;CJK COMPATIBILITY IDEOGRAPH-F90B;Lo;0;L;5587;;;;N;;;;; -F90C;CJK COMPATIBILITY IDEOGRAPH-F90C;Lo;0;L;5948;;;;N;;;;; -F90D;CJK COMPATIBILITY IDEOGRAPH-F90D;Lo;0;L;61F6;;;;N;;;;; -F90E;CJK COMPATIBILITY IDEOGRAPH-F90E;Lo;0;L;7669;;;;N;;;;; -F90F;CJK COMPATIBILITY IDEOGRAPH-F90F;Lo;0;L;7F85;;;;N;;;;; -F910;CJK COMPATIBILITY IDEOGRAPH-F910;Lo;0;L;863F;;;;N;;;;; -F911;CJK COMPATIBILITY IDEOGRAPH-F911;Lo;0;L;87BA;;;;N;;;;; -F912;CJK COMPATIBILITY IDEOGRAPH-F912;Lo;0;L;88F8;;;;N;;;;; -F913;CJK COMPATIBILITY IDEOGRAPH-F913;Lo;0;L;908F;;;;N;;;;; -F914;CJK COMPATIBILITY IDEOGRAPH-F914;Lo;0;L;6A02;;;;N;;;;; -F915;CJK COMPATIBILITY IDEOGRAPH-F915;Lo;0;L;6D1B;;;;N;;;;; -F916;CJK COMPATIBILITY IDEOGRAPH-F916;Lo;0;L;70D9;;;;N;;;;; -F917;CJK COMPATIBILITY IDEOGRAPH-F917;Lo;0;L;73DE;;;;N;;;;; -F918;CJK COMPATIBILITY IDEOGRAPH-F918;Lo;0;L;843D;;;;N;;;;; -F919;CJK COMPATIBILITY IDEOGRAPH-F919;Lo;0;L;916A;;;;N;;;;; -F91A;CJK COMPATIBILITY IDEOGRAPH-F91A;Lo;0;L;99F1;;;;N;;;;; -F91B;CJK COMPATIBILITY IDEOGRAPH-F91B;Lo;0;L;4E82;;;;N;;;;; -F91C;CJK COMPATIBILITY IDEOGRAPH-F91C;Lo;0;L;5375;;;;N;;;;; -F91D;CJK COMPATIBILITY IDEOGRAPH-F91D;Lo;0;L;6B04;;;;N;;;;; -F91E;CJK COMPATIBILITY IDEOGRAPH-F91E;Lo;0;L;721B;;;;N;;;;; -F91F;CJK COMPATIBILITY IDEOGRAPH-F91F;Lo;0;L;862D;;;;N;;;;; -F920;CJK COMPATIBILITY IDEOGRAPH-F920;Lo;0;L;9E1E;;;;N;;;;; -F921;CJK COMPATIBILITY IDEOGRAPH-F921;Lo;0;L;5D50;;;;N;;;;; -F922;CJK COMPATIBILITY IDEOGRAPH-F922;Lo;0;L;6FEB;;;;N;;;;; -F923;CJK COMPATIBILITY IDEOGRAPH-F923;Lo;0;L;85CD;;;;N;;;;; -F924;CJK COMPATIBILITY IDEOGRAPH-F924;Lo;0;L;8964;;;;N;;;;; -F925;CJK COMPATIBILITY IDEOGRAPH-F925;Lo;0;L;62C9;;;;N;;;;; -F926;CJK COMPATIBILITY IDEOGRAPH-F926;Lo;0;L;81D8;;;;N;;;;; -F927;CJK COMPATIBILITY IDEOGRAPH-F927;Lo;0;L;881F;;;;N;;;;; -F928;CJK COMPATIBILITY IDEOGRAPH-F928;Lo;0;L;5ECA;;;;N;;;;; -F929;CJK COMPATIBILITY IDEOGRAPH-F929;Lo;0;L;6717;;;;N;;;;; -F92A;CJK COMPATIBILITY IDEOGRAPH-F92A;Lo;0;L;6D6A;;;;N;;;;; -F92B;CJK COMPATIBILITY IDEOGRAPH-F92B;Lo;0;L;72FC;;;;N;;;;; -F92C;CJK COMPATIBILITY IDEOGRAPH-F92C;Lo;0;L;90CE;;;;N;;;;; -F92D;CJK COMPATIBILITY IDEOGRAPH-F92D;Lo;0;L;4F86;;;;N;;;;; -F92E;CJK COMPATIBILITY IDEOGRAPH-F92E;Lo;0;L;51B7;;;;N;;;;; -F92F;CJK COMPATIBILITY IDEOGRAPH-F92F;Lo;0;L;52DE;;;;N;;;;; -F930;CJK COMPATIBILITY IDEOGRAPH-F930;Lo;0;L;64C4;;;;N;;;;; -F931;CJK COMPATIBILITY IDEOGRAPH-F931;Lo;0;L;6AD3;;;;N;;;;; -F932;CJK COMPATIBILITY IDEOGRAPH-F932;Lo;0;L;7210;;;;N;;;;; -F933;CJK COMPATIBILITY IDEOGRAPH-F933;Lo;0;L;76E7;;;;N;;;;; -F934;CJK COMPATIBILITY IDEOGRAPH-F934;Lo;0;L;8001;;;;N;;;;; -F935;CJK COMPATIBILITY IDEOGRAPH-F935;Lo;0;L;8606;;;;N;;;;; -F936;CJK COMPATIBILITY IDEOGRAPH-F936;Lo;0;L;865C;;;;N;;;;; -F937;CJK COMPATIBILITY IDEOGRAPH-F937;Lo;0;L;8DEF;;;;N;;;;; -F938;CJK COMPATIBILITY IDEOGRAPH-F938;Lo;0;L;9732;;;;N;;;;; -F939;CJK COMPATIBILITY IDEOGRAPH-F939;Lo;0;L;9B6F;;;;N;;;;; -F93A;CJK COMPATIBILITY IDEOGRAPH-F93A;Lo;0;L;9DFA;;;;N;;;;; -F93B;CJK COMPATIBILITY IDEOGRAPH-F93B;Lo;0;L;788C;;;;N;;;;; -F93C;CJK COMPATIBILITY IDEOGRAPH-F93C;Lo;0;L;797F;;;;N;;;;; -F93D;CJK COMPATIBILITY IDEOGRAPH-F93D;Lo;0;L;7DA0;;;;N;;;;; -F93E;CJK COMPATIBILITY IDEOGRAPH-F93E;Lo;0;L;83C9;;;;N;;;;; -F93F;CJK COMPATIBILITY IDEOGRAPH-F93F;Lo;0;L;9304;;;;N;;;;; -F940;CJK COMPATIBILITY IDEOGRAPH-F940;Lo;0;L;9E7F;;;;N;;;;; -F941;CJK COMPATIBILITY IDEOGRAPH-F941;Lo;0;L;8AD6;;;;N;;;;; -F942;CJK COMPATIBILITY IDEOGRAPH-F942;Lo;0;L;58DF;;;;N;;;;; -F943;CJK COMPATIBILITY IDEOGRAPH-F943;Lo;0;L;5F04;;;;N;;;;; -F944;CJK COMPATIBILITY IDEOGRAPH-F944;Lo;0;L;7C60;;;;N;;;;; -F945;CJK COMPATIBILITY IDEOGRAPH-F945;Lo;0;L;807E;;;;N;;;;; -F946;CJK COMPATIBILITY IDEOGRAPH-F946;Lo;0;L;7262;;;;N;;;;; -F947;CJK COMPATIBILITY IDEOGRAPH-F947;Lo;0;L;78CA;;;;N;;;;; -F948;CJK COMPATIBILITY IDEOGRAPH-F948;Lo;0;L;8CC2;;;;N;;;;; -F949;CJK COMPATIBILITY IDEOGRAPH-F949;Lo;0;L;96F7;;;;N;;;;; -F94A;CJK COMPATIBILITY IDEOGRAPH-F94A;Lo;0;L;58D8;;;;N;;;;; -F94B;CJK COMPATIBILITY IDEOGRAPH-F94B;Lo;0;L;5C62;;;;N;;;;; -F94C;CJK COMPATIBILITY IDEOGRAPH-F94C;Lo;0;L;6A13;;;;N;;;;; -F94D;CJK COMPATIBILITY IDEOGRAPH-F94D;Lo;0;L;6DDA;;;;N;;;;; -F94E;CJK COMPATIBILITY IDEOGRAPH-F94E;Lo;0;L;6F0F;;;;N;;;;; -F94F;CJK COMPATIBILITY IDEOGRAPH-F94F;Lo;0;L;7D2F;;;;N;;;;; -F950;CJK COMPATIBILITY IDEOGRAPH-F950;Lo;0;L;7E37;;;;N;;;;; -F951;CJK COMPATIBILITY IDEOGRAPH-F951;Lo;0;L;964B;;;;N;;;;; -F952;CJK COMPATIBILITY IDEOGRAPH-F952;Lo;0;L;52D2;;;;N;;;;; -F953;CJK COMPATIBILITY IDEOGRAPH-F953;Lo;0;L;808B;;;;N;;;;; -F954;CJK COMPATIBILITY IDEOGRAPH-F954;Lo;0;L;51DC;;;;N;;;;; -F955;CJK COMPATIBILITY IDEOGRAPH-F955;Lo;0;L;51CC;;;;N;;;;; -F956;CJK COMPATIBILITY IDEOGRAPH-F956;Lo;0;L;7A1C;;;;N;;;;; -F957;CJK COMPATIBILITY IDEOGRAPH-F957;Lo;0;L;7DBE;;;;N;;;;; -F958;CJK COMPATIBILITY IDEOGRAPH-F958;Lo;0;L;83F1;;;;N;;;;; -F959;CJK COMPATIBILITY IDEOGRAPH-F959;Lo;0;L;9675;;;;N;;;;; -F95A;CJK COMPATIBILITY IDEOGRAPH-F95A;Lo;0;L;8B80;;;;N;;;;; -F95B;CJK COMPATIBILITY IDEOGRAPH-F95B;Lo;0;L;62CF;;;;N;;;;; -F95C;CJK COMPATIBILITY IDEOGRAPH-F95C;Lo;0;L;6A02;;;;N;;;;; -F95D;CJK COMPATIBILITY IDEOGRAPH-F95D;Lo;0;L;8AFE;;;;N;;;;; -F95E;CJK COMPATIBILITY IDEOGRAPH-F95E;Lo;0;L;4E39;;;;N;;;;; -F95F;CJK COMPATIBILITY IDEOGRAPH-F95F;Lo;0;L;5BE7;;;;N;;;;; -F960;CJK COMPATIBILITY IDEOGRAPH-F960;Lo;0;L;6012;;;;N;;;;; -F961;CJK COMPATIBILITY IDEOGRAPH-F961;Lo;0;L;7387;;;;N;;;;; -F962;CJK COMPATIBILITY IDEOGRAPH-F962;Lo;0;L;7570;;;;N;;;;; -F963;CJK COMPATIBILITY IDEOGRAPH-F963;Lo;0;L;5317;;;;N;;;;; -F964;CJK COMPATIBILITY IDEOGRAPH-F964;Lo;0;L;78FB;;;;N;;;;; -F965;CJK COMPATIBILITY IDEOGRAPH-F965;Lo;0;L;4FBF;;;;N;;;;; -F966;CJK COMPATIBILITY IDEOGRAPH-F966;Lo;0;L;5FA9;;;;N;;;;; -F967;CJK COMPATIBILITY IDEOGRAPH-F967;Lo;0;L;4E0D;;;;N;;;;; -F968;CJK COMPATIBILITY IDEOGRAPH-F968;Lo;0;L;6CCC;;;;N;;;;; -F969;CJK COMPATIBILITY IDEOGRAPH-F969;Lo;0;L;6578;;;;N;;;;; -F96A;CJK COMPATIBILITY IDEOGRAPH-F96A;Lo;0;L;7D22;;;;N;;;;; -F96B;CJK COMPATIBILITY IDEOGRAPH-F96B;Lo;0;L;53C3;;;3;N;;;;; -F96C;CJK COMPATIBILITY IDEOGRAPH-F96C;Lo;0;L;585E;;;;N;;;;; -F96D;CJK COMPATIBILITY IDEOGRAPH-F96D;Lo;0;L;7701;;;;N;;;;; -F96E;CJK COMPATIBILITY IDEOGRAPH-F96E;Lo;0;L;8449;;;;N;;;;; -F96F;CJK COMPATIBILITY IDEOGRAPH-F96F;Lo;0;L;8AAA;;;;N;;;;; -F970;CJK COMPATIBILITY IDEOGRAPH-F970;Lo;0;L;6BBA;;;;N;;;;; -F971;CJK COMPATIBILITY IDEOGRAPH-F971;Lo;0;L;8FB0;;;;N;;;;; -F972;CJK COMPATIBILITY IDEOGRAPH-F972;Lo;0;L;6C88;;;;N;;;;; -F973;CJK COMPATIBILITY IDEOGRAPH-F973;Lo;0;L;62FE;;;10;N;;;;; -F974;CJK COMPATIBILITY IDEOGRAPH-F974;Lo;0;L;82E5;;;;N;;;;; -F975;CJK COMPATIBILITY IDEOGRAPH-F975;Lo;0;L;63A0;;;;N;;;;; -F976;CJK COMPATIBILITY IDEOGRAPH-F976;Lo;0;L;7565;;;;N;;;;; -F977;CJK COMPATIBILITY IDEOGRAPH-F977;Lo;0;L;4EAE;;;;N;;;;; -F978;CJK COMPATIBILITY IDEOGRAPH-F978;Lo;0;L;5169;;;2;N;;;;; -F979;CJK COMPATIBILITY IDEOGRAPH-F979;Lo;0;L;51C9;;;;N;;;;; -F97A;CJK COMPATIBILITY IDEOGRAPH-F97A;Lo;0;L;6881;;;;N;;;;; -F97B;CJK COMPATIBILITY IDEOGRAPH-F97B;Lo;0;L;7CE7;;;;N;;;;; -F97C;CJK COMPATIBILITY IDEOGRAPH-F97C;Lo;0;L;826F;;;;N;;;;; -F97D;CJK COMPATIBILITY IDEOGRAPH-F97D;Lo;0;L;8AD2;;;;N;;;;; -F97E;CJK COMPATIBILITY IDEOGRAPH-F97E;Lo;0;L;91CF;;;;N;;;;; -F97F;CJK COMPATIBILITY IDEOGRAPH-F97F;Lo;0;L;52F5;;;;N;;;;; -F980;CJK COMPATIBILITY IDEOGRAPH-F980;Lo;0;L;5442;;;;N;;;;; -F981;CJK COMPATIBILITY IDEOGRAPH-F981;Lo;0;L;5973;;;;N;;;;; -F982;CJK COMPATIBILITY IDEOGRAPH-F982;Lo;0;L;5EEC;;;;N;;;;; -F983;CJK COMPATIBILITY IDEOGRAPH-F983;Lo;0;L;65C5;;;;N;;;;; -F984;CJK COMPATIBILITY IDEOGRAPH-F984;Lo;0;L;6FFE;;;;N;;;;; -F985;CJK COMPATIBILITY IDEOGRAPH-F985;Lo;0;L;792A;;;;N;;;;; -F986;CJK COMPATIBILITY IDEOGRAPH-F986;Lo;0;L;95AD;;;;N;;;;; -F987;CJK COMPATIBILITY IDEOGRAPH-F987;Lo;0;L;9A6A;;;;N;;;;; -F988;CJK COMPATIBILITY IDEOGRAPH-F988;Lo;0;L;9E97;;;;N;;;;; -F989;CJK COMPATIBILITY IDEOGRAPH-F989;Lo;0;L;9ECE;;;;N;;;;; -F98A;CJK COMPATIBILITY IDEOGRAPH-F98A;Lo;0;L;529B;;;;N;;;;; -F98B;CJK COMPATIBILITY IDEOGRAPH-F98B;Lo;0;L;66C6;;;;N;;;;; -F98C;CJK COMPATIBILITY IDEOGRAPH-F98C;Lo;0;L;6B77;;;;N;;;;; -F98D;CJK COMPATIBILITY IDEOGRAPH-F98D;Lo;0;L;8F62;;;;N;;;;; -F98E;CJK COMPATIBILITY IDEOGRAPH-F98E;Lo;0;L;5E74;;;;N;;;;; -F98F;CJK COMPATIBILITY IDEOGRAPH-F98F;Lo;0;L;6190;;;;N;;;;; -F990;CJK COMPATIBILITY IDEOGRAPH-F990;Lo;0;L;6200;;;;N;;;;; -F991;CJK COMPATIBILITY IDEOGRAPH-F991;Lo;0;L;649A;;;;N;;;;; -F992;CJK COMPATIBILITY IDEOGRAPH-F992;Lo;0;L;6F23;;;;N;;;;; -F993;CJK COMPATIBILITY IDEOGRAPH-F993;Lo;0;L;7149;;;;N;;;;; -F994;CJK COMPATIBILITY IDEOGRAPH-F994;Lo;0;L;7489;;;;N;;;;; -F995;CJK COMPATIBILITY IDEOGRAPH-F995;Lo;0;L;79CA;;;;N;;;;; -F996;CJK COMPATIBILITY IDEOGRAPH-F996;Lo;0;L;7DF4;;;;N;;;;; -F997;CJK COMPATIBILITY IDEOGRAPH-F997;Lo;0;L;806F;;;;N;;;;; -F998;CJK COMPATIBILITY IDEOGRAPH-F998;Lo;0;L;8F26;;;;N;;;;; -F999;CJK COMPATIBILITY IDEOGRAPH-F999;Lo;0;L;84EE;;;;N;;;;; -F99A;CJK COMPATIBILITY IDEOGRAPH-F99A;Lo;0;L;9023;;;;N;;;;; -F99B;CJK COMPATIBILITY IDEOGRAPH-F99B;Lo;0;L;934A;;;;N;;;;; -F99C;CJK COMPATIBILITY IDEOGRAPH-F99C;Lo;0;L;5217;;;;N;;;;; -F99D;CJK COMPATIBILITY IDEOGRAPH-F99D;Lo;0;L;52A3;;;;N;;;;; -F99E;CJK COMPATIBILITY IDEOGRAPH-F99E;Lo;0;L;54BD;;;;N;;;;; -F99F;CJK COMPATIBILITY IDEOGRAPH-F99F;Lo;0;L;70C8;;;;N;;;;; -F9A0;CJK COMPATIBILITY IDEOGRAPH-F9A0;Lo;0;L;88C2;;;;N;;;;; -F9A1;CJK COMPATIBILITY IDEOGRAPH-F9A1;Lo;0;L;8AAA;;;;N;;;;; -F9A2;CJK COMPATIBILITY IDEOGRAPH-F9A2;Lo;0;L;5EC9;;;;N;;;;; -F9A3;CJK COMPATIBILITY IDEOGRAPH-F9A3;Lo;0;L;5FF5;;;;N;;;;; -F9A4;CJK COMPATIBILITY IDEOGRAPH-F9A4;Lo;0;L;637B;;;;N;;;;; -F9A5;CJK COMPATIBILITY IDEOGRAPH-F9A5;Lo;0;L;6BAE;;;;N;;;;; -F9A6;CJK COMPATIBILITY IDEOGRAPH-F9A6;Lo;0;L;7C3E;;;;N;;;;; -F9A7;CJK COMPATIBILITY IDEOGRAPH-F9A7;Lo;0;L;7375;;;;N;;;;; -F9A8;CJK COMPATIBILITY IDEOGRAPH-F9A8;Lo;0;L;4EE4;;;;N;;;;; -F9A9;CJK COMPATIBILITY IDEOGRAPH-F9A9;Lo;0;L;56F9;;;;N;;;;; -F9AA;CJK COMPATIBILITY IDEOGRAPH-F9AA;Lo;0;L;5BE7;;;;N;;;;; -F9AB;CJK COMPATIBILITY IDEOGRAPH-F9AB;Lo;0;L;5DBA;;;;N;;;;; -F9AC;CJK COMPATIBILITY IDEOGRAPH-F9AC;Lo;0;L;601C;;;;N;;;;; -F9AD;CJK COMPATIBILITY IDEOGRAPH-F9AD;Lo;0;L;73B2;;;;N;;;;; -F9AE;CJK COMPATIBILITY IDEOGRAPH-F9AE;Lo;0;L;7469;;;;N;;;;; -F9AF;CJK COMPATIBILITY IDEOGRAPH-F9AF;Lo;0;L;7F9A;;;;N;;;;; -F9B0;CJK COMPATIBILITY IDEOGRAPH-F9B0;Lo;0;L;8046;;;;N;;;;; -F9B1;CJK COMPATIBILITY IDEOGRAPH-F9B1;Lo;0;L;9234;;;;N;;;;; -F9B2;CJK COMPATIBILITY IDEOGRAPH-F9B2;Lo;0;L;96F6;;;0;N;;;;; -F9B3;CJK COMPATIBILITY IDEOGRAPH-F9B3;Lo;0;L;9748;;;;N;;;;; -F9B4;CJK COMPATIBILITY IDEOGRAPH-F9B4;Lo;0;L;9818;;;;N;;;;; -F9B5;CJK COMPATIBILITY IDEOGRAPH-F9B5;Lo;0;L;4F8B;;;;N;;;;; -F9B6;CJK COMPATIBILITY IDEOGRAPH-F9B6;Lo;0;L;79AE;;;;N;;;;; -F9B7;CJK COMPATIBILITY IDEOGRAPH-F9B7;Lo;0;L;91B4;;;;N;;;;; -F9B8;CJK COMPATIBILITY IDEOGRAPH-F9B8;Lo;0;L;96B8;;;;N;;;;; -F9B9;CJK COMPATIBILITY IDEOGRAPH-F9B9;Lo;0;L;60E1;;;;N;;;;; -F9BA;CJK COMPATIBILITY IDEOGRAPH-F9BA;Lo;0;L;4E86;;;;N;;;;; -F9BB;CJK COMPATIBILITY IDEOGRAPH-F9BB;Lo;0;L;50DA;;;;N;;;;; -F9BC;CJK COMPATIBILITY IDEOGRAPH-F9BC;Lo;0;L;5BEE;;;;N;;;;; -F9BD;CJK COMPATIBILITY IDEOGRAPH-F9BD;Lo;0;L;5C3F;;;;N;;;;; -F9BE;CJK COMPATIBILITY IDEOGRAPH-F9BE;Lo;0;L;6599;;;;N;;;;; -F9BF;CJK COMPATIBILITY IDEOGRAPH-F9BF;Lo;0;L;6A02;;;;N;;;;; -F9C0;CJK COMPATIBILITY IDEOGRAPH-F9C0;Lo;0;L;71CE;;;;N;;;;; -F9C1;CJK COMPATIBILITY IDEOGRAPH-F9C1;Lo;0;L;7642;;;;N;;;;; -F9C2;CJK COMPATIBILITY IDEOGRAPH-F9C2;Lo;0;L;84FC;;;;N;;;;; -F9C3;CJK COMPATIBILITY IDEOGRAPH-F9C3;Lo;0;L;907C;;;;N;;;;; -F9C4;CJK COMPATIBILITY IDEOGRAPH-F9C4;Lo;0;L;9F8D;;;;N;;;;; -F9C5;CJK COMPATIBILITY IDEOGRAPH-F9C5;Lo;0;L;6688;;;;N;;;;; -F9C6;CJK COMPATIBILITY IDEOGRAPH-F9C6;Lo;0;L;962E;;;;N;;;;; -F9C7;CJK COMPATIBILITY IDEOGRAPH-F9C7;Lo;0;L;5289;;;;N;;;;; -F9C8;CJK COMPATIBILITY IDEOGRAPH-F9C8;Lo;0;L;677B;;;;N;;;;; -F9C9;CJK COMPATIBILITY IDEOGRAPH-F9C9;Lo;0;L;67F3;;;;N;;;;; -F9CA;CJK COMPATIBILITY IDEOGRAPH-F9CA;Lo;0;L;6D41;;;;N;;;;; -F9CB;CJK COMPATIBILITY IDEOGRAPH-F9CB;Lo;0;L;6E9C;;;;N;;;;; -F9CC;CJK COMPATIBILITY IDEOGRAPH-F9CC;Lo;0;L;7409;;;;N;;;;; -F9CD;CJK COMPATIBILITY IDEOGRAPH-F9CD;Lo;0;L;7559;;;;N;;;;; -F9CE;CJK COMPATIBILITY IDEOGRAPH-F9CE;Lo;0;L;786B;;;;N;;;;; -F9CF;CJK COMPATIBILITY IDEOGRAPH-F9CF;Lo;0;L;7D10;;;;N;;;;; -F9D0;CJK COMPATIBILITY IDEOGRAPH-F9D0;Lo;0;L;985E;;;;N;;;;; -F9D1;CJK COMPATIBILITY IDEOGRAPH-F9D1;Lo;0;L;516D;;;6;N;;;;; -F9D2;CJK COMPATIBILITY IDEOGRAPH-F9D2;Lo;0;L;622E;;;;N;;;;; -F9D3;CJK COMPATIBILITY IDEOGRAPH-F9D3;Lo;0;L;9678;;;6;N;;;;; -F9D4;CJK COMPATIBILITY IDEOGRAPH-F9D4;Lo;0;L;502B;;;;N;;;;; -F9D5;CJK COMPATIBILITY IDEOGRAPH-F9D5;Lo;0;L;5D19;;;;N;;;;; -F9D6;CJK COMPATIBILITY IDEOGRAPH-F9D6;Lo;0;L;6DEA;;;;N;;;;; -F9D7;CJK COMPATIBILITY IDEOGRAPH-F9D7;Lo;0;L;8F2A;;;;N;;;;; -F9D8;CJK COMPATIBILITY IDEOGRAPH-F9D8;Lo;0;L;5F8B;;;;N;;;;; -F9D9;CJK COMPATIBILITY IDEOGRAPH-F9D9;Lo;0;L;6144;;;;N;;;;; -F9DA;CJK COMPATIBILITY IDEOGRAPH-F9DA;Lo;0;L;6817;;;;N;;;;; -F9DB;CJK COMPATIBILITY IDEOGRAPH-F9DB;Lo;0;L;7387;;;;N;;;;; -F9DC;CJK COMPATIBILITY IDEOGRAPH-F9DC;Lo;0;L;9686;;;;N;;;;; -F9DD;CJK COMPATIBILITY IDEOGRAPH-F9DD;Lo;0;L;5229;;;;N;;;;; -F9DE;CJK COMPATIBILITY IDEOGRAPH-F9DE;Lo;0;L;540F;;;;N;;;;; -F9DF;CJK COMPATIBILITY IDEOGRAPH-F9DF;Lo;0;L;5C65;;;;N;;;;; -F9E0;CJK COMPATIBILITY IDEOGRAPH-F9E0;Lo;0;L;6613;;;;N;;;;; -F9E1;CJK COMPATIBILITY IDEOGRAPH-F9E1;Lo;0;L;674E;;;;N;;;;; -F9E2;CJK COMPATIBILITY IDEOGRAPH-F9E2;Lo;0;L;68A8;;;;N;;;;; -F9E3;CJK COMPATIBILITY IDEOGRAPH-F9E3;Lo;0;L;6CE5;;;;N;;;;; -F9E4;CJK COMPATIBILITY IDEOGRAPH-F9E4;Lo;0;L;7406;;;;N;;;;; -F9E5;CJK COMPATIBILITY IDEOGRAPH-F9E5;Lo;0;L;75E2;;;;N;;;;; -F9E6;CJK COMPATIBILITY IDEOGRAPH-F9E6;Lo;0;L;7F79;;;;N;;;;; -F9E7;CJK COMPATIBILITY IDEOGRAPH-F9E7;Lo;0;L;88CF;;;;N;;;;; -F9E8;CJK COMPATIBILITY IDEOGRAPH-F9E8;Lo;0;L;88E1;;;;N;;;;; -F9E9;CJK COMPATIBILITY IDEOGRAPH-F9E9;Lo;0;L;91CC;;;;N;;;;; -F9EA;CJK COMPATIBILITY IDEOGRAPH-F9EA;Lo;0;L;96E2;;;;N;;;;; -F9EB;CJK COMPATIBILITY IDEOGRAPH-F9EB;Lo;0;L;533F;;;;N;;;;; -F9EC;CJK COMPATIBILITY IDEOGRAPH-F9EC;Lo;0;L;6EBA;;;;N;;;;; -F9ED;CJK COMPATIBILITY IDEOGRAPH-F9ED;Lo;0;L;541D;;;;N;;;;; -F9EE;CJK COMPATIBILITY IDEOGRAPH-F9EE;Lo;0;L;71D0;;;;N;;;;; -F9EF;CJK COMPATIBILITY IDEOGRAPH-F9EF;Lo;0;L;7498;;;;N;;;;; -F9F0;CJK COMPATIBILITY IDEOGRAPH-F9F0;Lo;0;L;85FA;;;;N;;;;; -F9F1;CJK COMPATIBILITY IDEOGRAPH-F9F1;Lo;0;L;96A3;;;;N;;;;; -F9F2;CJK COMPATIBILITY IDEOGRAPH-F9F2;Lo;0;L;9C57;;;;N;;;;; -F9F3;CJK COMPATIBILITY IDEOGRAPH-F9F3;Lo;0;L;9E9F;;;;N;;;;; -F9F4;CJK COMPATIBILITY IDEOGRAPH-F9F4;Lo;0;L;6797;;;;N;;;;; -F9F5;CJK COMPATIBILITY IDEOGRAPH-F9F5;Lo;0;L;6DCB;;;;N;;;;; -F9F6;CJK COMPATIBILITY IDEOGRAPH-F9F6;Lo;0;L;81E8;;;;N;;;;; -F9F7;CJK COMPATIBILITY IDEOGRAPH-F9F7;Lo;0;L;7ACB;;;;N;;;;; -F9F8;CJK COMPATIBILITY IDEOGRAPH-F9F8;Lo;0;L;7B20;;;;N;;;;; -F9F9;CJK COMPATIBILITY IDEOGRAPH-F9F9;Lo;0;L;7C92;;;;N;;;;; -F9FA;CJK COMPATIBILITY IDEOGRAPH-F9FA;Lo;0;L;72C0;;;;N;;;;; -F9FB;CJK COMPATIBILITY IDEOGRAPH-F9FB;Lo;0;L;7099;;;;N;;;;; -F9FC;CJK COMPATIBILITY IDEOGRAPH-F9FC;Lo;0;L;8B58;;;;N;;;;; -F9FD;CJK COMPATIBILITY IDEOGRAPH-F9FD;Lo;0;L;4EC0;;;10;N;;;;; -F9FE;CJK COMPATIBILITY IDEOGRAPH-F9FE;Lo;0;L;8336;;;;N;;;;; -F9FF;CJK COMPATIBILITY IDEOGRAPH-F9FF;Lo;0;L;523A;;;;N;;;;; -FA00;CJK COMPATIBILITY IDEOGRAPH-FA00;Lo;0;L;5207;;;;N;;;;; -FA01;CJK COMPATIBILITY IDEOGRAPH-FA01;Lo;0;L;5EA6;;;;N;;;;; -FA02;CJK COMPATIBILITY IDEOGRAPH-FA02;Lo;0;L;62D3;;;;N;;;;; -FA03;CJK COMPATIBILITY IDEOGRAPH-FA03;Lo;0;L;7CD6;;;;N;;;;; -FA04;CJK COMPATIBILITY IDEOGRAPH-FA04;Lo;0;L;5B85;;;;N;;;;; -FA05;CJK COMPATIBILITY IDEOGRAPH-FA05;Lo;0;L;6D1E;;;;N;;;;; -FA06;CJK COMPATIBILITY IDEOGRAPH-FA06;Lo;0;L;66B4;;;;N;;;;; -FA07;CJK COMPATIBILITY IDEOGRAPH-FA07;Lo;0;L;8F3B;;;;N;;;;; -FA08;CJK COMPATIBILITY IDEOGRAPH-FA08;Lo;0;L;884C;;;;N;;;;; -FA09;CJK COMPATIBILITY IDEOGRAPH-FA09;Lo;0;L;964D;;;;N;;;;; -FA0A;CJK COMPATIBILITY IDEOGRAPH-FA0A;Lo;0;L;898B;;;;N;;;;; -FA0B;CJK COMPATIBILITY IDEOGRAPH-FA0B;Lo;0;L;5ED3;;;;N;;;;; -FA0C;CJK COMPATIBILITY IDEOGRAPH-FA0C;Lo;0;L;5140;;;;N;;;;; -FA0D;CJK COMPATIBILITY IDEOGRAPH-FA0D;Lo;0;L;55C0;;;;N;;;;; -FA0E;CJK COMPATIBILITY IDEOGRAPH-FA0E;Lo;0;L;;;;;N;;;;; -FA0F;CJK COMPATIBILITY IDEOGRAPH-FA0F;Lo;0;L;;;;;N;;;;; -FA10;CJK COMPATIBILITY IDEOGRAPH-FA10;Lo;0;L;585A;;;;N;;;;; -FA11;CJK COMPATIBILITY IDEOGRAPH-FA11;Lo;0;L;;;;;N;;;;; -FA12;CJK COMPATIBILITY IDEOGRAPH-FA12;Lo;0;L;6674;;;;N;;;;; -FA13;CJK COMPATIBILITY IDEOGRAPH-FA13;Lo;0;L;;;;;N;;;;; -FA14;CJK COMPATIBILITY IDEOGRAPH-FA14;Lo;0;L;;;;;N;;;;; -FA15;CJK COMPATIBILITY IDEOGRAPH-FA15;Lo;0;L;51DE;;;;N;;;;; -FA16;CJK COMPATIBILITY IDEOGRAPH-FA16;Lo;0;L;732A;;;;N;;;;; -FA17;CJK COMPATIBILITY IDEOGRAPH-FA17;Lo;0;L;76CA;;;;N;;;;; -FA18;CJK COMPATIBILITY IDEOGRAPH-FA18;Lo;0;L;793C;;;;N;;;;; -FA19;CJK COMPATIBILITY IDEOGRAPH-FA19;Lo;0;L;795E;;;;N;;;;; -FA1A;CJK COMPATIBILITY IDEOGRAPH-FA1A;Lo;0;L;7965;;;;N;;;;; -FA1B;CJK COMPATIBILITY IDEOGRAPH-FA1B;Lo;0;L;798F;;;;N;;;;; -FA1C;CJK COMPATIBILITY IDEOGRAPH-FA1C;Lo;0;L;9756;;;;N;;;;; -FA1D;CJK COMPATIBILITY IDEOGRAPH-FA1D;Lo;0;L;7CBE;;;;N;;;;; -FA1E;CJK COMPATIBILITY IDEOGRAPH-FA1E;Lo;0;L;7FBD;;;;N;;;;; -FA1F;CJK COMPATIBILITY IDEOGRAPH-FA1F;Lo;0;L;;;;;N;;*;;; -FA20;CJK COMPATIBILITY IDEOGRAPH-FA20;Lo;0;L;8612;;;;N;;;;; -FA21;CJK COMPATIBILITY IDEOGRAPH-FA21;Lo;0;L;;;;;N;;;;; -FA22;CJK COMPATIBILITY IDEOGRAPH-FA22;Lo;0;L;8AF8;;;;N;;;;; -FA23;CJK COMPATIBILITY IDEOGRAPH-FA23;Lo;0;L;;;;;N;;*;;; -FA24;CJK COMPATIBILITY IDEOGRAPH-FA24;Lo;0;L;;;;;N;;;;; -FA25;CJK COMPATIBILITY IDEOGRAPH-FA25;Lo;0;L;9038;;;;N;;;;; -FA26;CJK COMPATIBILITY IDEOGRAPH-FA26;Lo;0;L;90FD;;;;N;;;;; -FA27;CJK COMPATIBILITY IDEOGRAPH-FA27;Lo;0;L;;;;;N;;;;; -FA28;CJK COMPATIBILITY IDEOGRAPH-FA28;Lo;0;L;;;;;N;;;;; -FA29;CJK COMPATIBILITY IDEOGRAPH-FA29;Lo;0;L;;;;;N;;;;; -FA2A;CJK COMPATIBILITY IDEOGRAPH-FA2A;Lo;0;L;98EF;;;;N;;;;; -FA2B;CJK COMPATIBILITY IDEOGRAPH-FA2B;Lo;0;L;98FC;;;;N;;;;; -FA2C;CJK COMPATIBILITY IDEOGRAPH-FA2C;Lo;0;L;9928;;;;N;;;;; -FA2D;CJK COMPATIBILITY IDEOGRAPH-FA2D;Lo;0;L;9DB4;;;;N;;;;; -FA30;CJK COMPATIBILITY IDEOGRAPH-FA30;Lo;0;L;4FAE;;;;N;;;;; -FA31;CJK COMPATIBILITY IDEOGRAPH-FA31;Lo;0;L;50E7;;;;N;;;;; -FA32;CJK COMPATIBILITY IDEOGRAPH-FA32;Lo;0;L;514D;;;;N;;;;; -FA33;CJK COMPATIBILITY IDEOGRAPH-FA33;Lo;0;L;52C9;;;;N;;;;; -FA34;CJK COMPATIBILITY IDEOGRAPH-FA34;Lo;0;L;52E4;;;;N;;;;; -FA35;CJK COMPATIBILITY IDEOGRAPH-FA35;Lo;0;L;5351;;;;N;;;;; -FA36;CJK COMPATIBILITY IDEOGRAPH-FA36;Lo;0;L;559D;;;;N;;;;; -FA37;CJK COMPATIBILITY IDEOGRAPH-FA37;Lo;0;L;5606;;;;N;;;;; -FA38;CJK COMPATIBILITY IDEOGRAPH-FA38;Lo;0;L;5668;;;;N;;;;; -FA39;CJK COMPATIBILITY IDEOGRAPH-FA39;Lo;0;L;5840;;;;N;;;;; -FA3A;CJK COMPATIBILITY IDEOGRAPH-FA3A;Lo;0;L;58A8;;;;N;;;;; -FA3B;CJK COMPATIBILITY IDEOGRAPH-FA3B;Lo;0;L;5C64;;;;N;;;;; -FA3C;CJK COMPATIBILITY IDEOGRAPH-FA3C;Lo;0;L;5C6E;;;;N;;;;; -FA3D;CJK COMPATIBILITY IDEOGRAPH-FA3D;Lo;0;L;6094;;;;N;;;;; -FA3E;CJK COMPATIBILITY IDEOGRAPH-FA3E;Lo;0;L;6168;;;;N;;;;; -FA3F;CJK COMPATIBILITY IDEOGRAPH-FA3F;Lo;0;L;618E;;;;N;;;;; -FA40;CJK COMPATIBILITY IDEOGRAPH-FA40;Lo;0;L;61F2;;;;N;;;;; -FA41;CJK COMPATIBILITY IDEOGRAPH-FA41;Lo;0;L;654F;;;;N;;;;; -FA42;CJK COMPATIBILITY IDEOGRAPH-FA42;Lo;0;L;65E2;;;;N;;;;; -FA43;CJK COMPATIBILITY IDEOGRAPH-FA43;Lo;0;L;6691;;;;N;;;;; -FA44;CJK COMPATIBILITY IDEOGRAPH-FA44;Lo;0;L;6885;;;;N;;;;; -FA45;CJK COMPATIBILITY IDEOGRAPH-FA45;Lo;0;L;6D77;;;;N;;;;; -FA46;CJK COMPATIBILITY IDEOGRAPH-FA46;Lo;0;L;6E1A;;;;N;;;;; -FA47;CJK COMPATIBILITY IDEOGRAPH-FA47;Lo;0;L;6F22;;;;N;;;;; -FA48;CJK COMPATIBILITY IDEOGRAPH-FA48;Lo;0;L;716E;;;;N;;;;; -FA49;CJK COMPATIBILITY IDEOGRAPH-FA49;Lo;0;L;722B;;;;N;;;;; -FA4A;CJK COMPATIBILITY IDEOGRAPH-FA4A;Lo;0;L;7422;;;;N;;;;; -FA4B;CJK COMPATIBILITY IDEOGRAPH-FA4B;Lo;0;L;7891;;;;N;;;;; -FA4C;CJK COMPATIBILITY IDEOGRAPH-FA4C;Lo;0;L;793E;;;;N;;;;; -FA4D;CJK COMPATIBILITY IDEOGRAPH-FA4D;Lo;0;L;7949;;;;N;;;;; -FA4E;CJK COMPATIBILITY IDEOGRAPH-FA4E;Lo;0;L;7948;;;;N;;;;; -FA4F;CJK COMPATIBILITY IDEOGRAPH-FA4F;Lo;0;L;7950;;;;N;;;;; -FA50;CJK COMPATIBILITY IDEOGRAPH-FA50;Lo;0;L;7956;;;;N;;;;; -FA51;CJK COMPATIBILITY IDEOGRAPH-FA51;Lo;0;L;795D;;;;N;;;;; -FA52;CJK COMPATIBILITY IDEOGRAPH-FA52;Lo;0;L;798D;;;;N;;;;; -FA53;CJK COMPATIBILITY IDEOGRAPH-FA53;Lo;0;L;798E;;;;N;;;;; -FA54;CJK COMPATIBILITY IDEOGRAPH-FA54;Lo;0;L;7A40;;;;N;;;;; -FA55;CJK COMPATIBILITY IDEOGRAPH-FA55;Lo;0;L;7A81;;;;N;;;;; -FA56;CJK COMPATIBILITY IDEOGRAPH-FA56;Lo;0;L;7BC0;;;;N;;;;; -FA57;CJK COMPATIBILITY IDEOGRAPH-FA57;Lo;0;L;7DF4;;;;N;;;;; -FA58;CJK COMPATIBILITY IDEOGRAPH-FA58;Lo;0;L;7E09;;;;N;;;;; -FA59;CJK COMPATIBILITY IDEOGRAPH-FA59;Lo;0;L;7E41;;;;N;;;;; -FA5A;CJK COMPATIBILITY IDEOGRAPH-FA5A;Lo;0;L;7F72;;;;N;;;;; -FA5B;CJK COMPATIBILITY IDEOGRAPH-FA5B;Lo;0;L;8005;;;;N;;;;; -FA5C;CJK COMPATIBILITY IDEOGRAPH-FA5C;Lo;0;L;81ED;;;;N;;;;; -FA5D;CJK COMPATIBILITY IDEOGRAPH-FA5D;Lo;0;L;8279;;;;N;;;;; -FA5E;CJK COMPATIBILITY IDEOGRAPH-FA5E;Lo;0;L;8279;;;;N;;;;; -FA5F;CJK COMPATIBILITY IDEOGRAPH-FA5F;Lo;0;L;8457;;;;N;;;;; -FA60;CJK COMPATIBILITY IDEOGRAPH-FA60;Lo;0;L;8910;;;;N;;;;; -FA61;CJK COMPATIBILITY IDEOGRAPH-FA61;Lo;0;L;8996;;;;N;;;;; -FA62;CJK COMPATIBILITY IDEOGRAPH-FA62;Lo;0;L;8B01;;;;N;;;;; -FA63;CJK COMPATIBILITY IDEOGRAPH-FA63;Lo;0;L;8B39;;;;N;;;;; -FA64;CJK COMPATIBILITY IDEOGRAPH-FA64;Lo;0;L;8CD3;;;;N;;;;; -FA65;CJK COMPATIBILITY IDEOGRAPH-FA65;Lo;0;L;8D08;;;;N;;;;; -FA66;CJK COMPATIBILITY IDEOGRAPH-FA66;Lo;0;L;8FB6;;;;N;;;;; -FA67;CJK COMPATIBILITY IDEOGRAPH-FA67;Lo;0;L;9038;;;;N;;;;; -FA68;CJK COMPATIBILITY IDEOGRAPH-FA68;Lo;0;L;96E3;;;;N;;;;; -FA69;CJK COMPATIBILITY IDEOGRAPH-FA69;Lo;0;L;97FF;;;;N;;;;; -FA6A;CJK COMPATIBILITY IDEOGRAPH-FA6A;Lo;0;L;983B;;;;N;;;;; -FA70;CJK COMPATIBILITY IDEOGRAPH-FA70;Lo;0;L;4E26;;;;N;;;;; -FA71;CJK COMPATIBILITY IDEOGRAPH-FA71;Lo;0;L;51B5;;;;N;;;;; -FA72;CJK COMPATIBILITY IDEOGRAPH-FA72;Lo;0;L;5168;;;;N;;;;; -FA73;CJK COMPATIBILITY IDEOGRAPH-FA73;Lo;0;L;4F80;;;;N;;;;; -FA74;CJK COMPATIBILITY IDEOGRAPH-FA74;Lo;0;L;5145;;;;N;;;;; -FA75;CJK COMPATIBILITY IDEOGRAPH-FA75;Lo;0;L;5180;;;;N;;;;; -FA76;CJK COMPATIBILITY IDEOGRAPH-FA76;Lo;0;L;52C7;;;;N;;;;; -FA77;CJK COMPATIBILITY IDEOGRAPH-FA77;Lo;0;L;52FA;;;;N;;;;; -FA78;CJK COMPATIBILITY IDEOGRAPH-FA78;Lo;0;L;559D;;;;N;;;;; -FA79;CJK COMPATIBILITY IDEOGRAPH-FA79;Lo;0;L;5555;;;;N;;;;; -FA7A;CJK COMPATIBILITY IDEOGRAPH-FA7A;Lo;0;L;5599;;;;N;;;;; -FA7B;CJK COMPATIBILITY IDEOGRAPH-FA7B;Lo;0;L;55E2;;;;N;;;;; -FA7C;CJK COMPATIBILITY IDEOGRAPH-FA7C;Lo;0;L;585A;;;;N;;;;; -FA7D;CJK COMPATIBILITY IDEOGRAPH-FA7D;Lo;0;L;58B3;;;;N;;;;; -FA7E;CJK COMPATIBILITY IDEOGRAPH-FA7E;Lo;0;L;5944;;;;N;;;;; -FA7F;CJK COMPATIBILITY IDEOGRAPH-FA7F;Lo;0;L;5954;;;;N;;;;; -FA80;CJK COMPATIBILITY IDEOGRAPH-FA80;Lo;0;L;5A62;;;;N;;;;; -FA81;CJK COMPATIBILITY IDEOGRAPH-FA81;Lo;0;L;5B28;;;;N;;;;; -FA82;CJK COMPATIBILITY IDEOGRAPH-FA82;Lo;0;L;5ED2;;;;N;;;;; -FA83;CJK COMPATIBILITY IDEOGRAPH-FA83;Lo;0;L;5ED9;;;;N;;;;; -FA84;CJK COMPATIBILITY IDEOGRAPH-FA84;Lo;0;L;5F69;;;;N;;;;; -FA85;CJK COMPATIBILITY IDEOGRAPH-FA85;Lo;0;L;5FAD;;;;N;;;;; -FA86;CJK COMPATIBILITY IDEOGRAPH-FA86;Lo;0;L;60D8;;;;N;;;;; -FA87;CJK COMPATIBILITY IDEOGRAPH-FA87;Lo;0;L;614E;;;;N;;;;; -FA88;CJK COMPATIBILITY IDEOGRAPH-FA88;Lo;0;L;6108;;;;N;;;;; -FA89;CJK COMPATIBILITY IDEOGRAPH-FA89;Lo;0;L;618E;;;;N;;;;; -FA8A;CJK COMPATIBILITY IDEOGRAPH-FA8A;Lo;0;L;6160;;;;N;;;;; -FA8B;CJK COMPATIBILITY IDEOGRAPH-FA8B;Lo;0;L;61F2;;;;N;;;;; -FA8C;CJK COMPATIBILITY IDEOGRAPH-FA8C;Lo;0;L;6234;;;;N;;;;; -FA8D;CJK COMPATIBILITY IDEOGRAPH-FA8D;Lo;0;L;63C4;;;;N;;;;; -FA8E;CJK COMPATIBILITY IDEOGRAPH-FA8E;Lo;0;L;641C;;;;N;;;;; -FA8F;CJK COMPATIBILITY IDEOGRAPH-FA8F;Lo;0;L;6452;;;;N;;;;; -FA90;CJK COMPATIBILITY IDEOGRAPH-FA90;Lo;0;L;6556;;;;N;;;;; -FA91;CJK COMPATIBILITY IDEOGRAPH-FA91;Lo;0;L;6674;;;;N;;;;; -FA92;CJK COMPATIBILITY IDEOGRAPH-FA92;Lo;0;L;6717;;;;N;;;;; -FA93;CJK COMPATIBILITY IDEOGRAPH-FA93;Lo;0;L;671B;;;;N;;;;; -FA94;CJK COMPATIBILITY IDEOGRAPH-FA94;Lo;0;L;6756;;;;N;;;;; -FA95;CJK COMPATIBILITY IDEOGRAPH-FA95;Lo;0;L;6B79;;;;N;;;;; -FA96;CJK COMPATIBILITY IDEOGRAPH-FA96;Lo;0;L;6BBA;;;;N;;;;; -FA97;CJK COMPATIBILITY IDEOGRAPH-FA97;Lo;0;L;6D41;;;;N;;;;; -FA98;CJK COMPATIBILITY IDEOGRAPH-FA98;Lo;0;L;6EDB;;;;N;;;;; -FA99;CJK COMPATIBILITY IDEOGRAPH-FA99;Lo;0;L;6ECB;;;;N;;;;; -FA9A;CJK COMPATIBILITY IDEOGRAPH-FA9A;Lo;0;L;6F22;;;;N;;;;; -FA9B;CJK COMPATIBILITY IDEOGRAPH-FA9B;Lo;0;L;701E;;;;N;;;;; -FA9C;CJK COMPATIBILITY IDEOGRAPH-FA9C;Lo;0;L;716E;;;;N;;;;; -FA9D;CJK COMPATIBILITY IDEOGRAPH-FA9D;Lo;0;L;77A7;;;;N;;;;; -FA9E;CJK COMPATIBILITY IDEOGRAPH-FA9E;Lo;0;L;7235;;;;N;;;;; -FA9F;CJK COMPATIBILITY IDEOGRAPH-FA9F;Lo;0;L;72AF;;;;N;;;;; -FAA0;CJK COMPATIBILITY IDEOGRAPH-FAA0;Lo;0;L;732A;;;;N;;;;; -FAA1;CJK COMPATIBILITY IDEOGRAPH-FAA1;Lo;0;L;7471;;;;N;;;;; -FAA2;CJK COMPATIBILITY IDEOGRAPH-FAA2;Lo;0;L;7506;;;;N;;;;; -FAA3;CJK COMPATIBILITY IDEOGRAPH-FAA3;Lo;0;L;753B;;;;N;;;;; -FAA4;CJK COMPATIBILITY IDEOGRAPH-FAA4;Lo;0;L;761D;;;;N;;;;; -FAA5;CJK COMPATIBILITY IDEOGRAPH-FAA5;Lo;0;L;761F;;;;N;;;;; -FAA6;CJK COMPATIBILITY IDEOGRAPH-FAA6;Lo;0;L;76CA;;;;N;;;;; -FAA7;CJK COMPATIBILITY IDEOGRAPH-FAA7;Lo;0;L;76DB;;;;N;;;;; -FAA8;CJK COMPATIBILITY IDEOGRAPH-FAA8;Lo;0;L;76F4;;;;N;;;;; -FAA9;CJK COMPATIBILITY IDEOGRAPH-FAA9;Lo;0;L;774A;;;;N;;;;; -FAAA;CJK COMPATIBILITY IDEOGRAPH-FAAA;Lo;0;L;7740;;;;N;;;;; -FAAB;CJK COMPATIBILITY IDEOGRAPH-FAAB;Lo;0;L;78CC;;;;N;;;;; -FAAC;CJK COMPATIBILITY IDEOGRAPH-FAAC;Lo;0;L;7AB1;;;;N;;;;; -FAAD;CJK COMPATIBILITY IDEOGRAPH-FAAD;Lo;0;L;7BC0;;;;N;;;;; -FAAE;CJK COMPATIBILITY IDEOGRAPH-FAAE;Lo;0;L;7C7B;;;;N;;;;; -FAAF;CJK COMPATIBILITY IDEOGRAPH-FAAF;Lo;0;L;7D5B;;;;N;;;;; -FAB0;CJK COMPATIBILITY IDEOGRAPH-FAB0;Lo;0;L;7DF4;;;;N;;;;; -FAB1;CJK COMPATIBILITY IDEOGRAPH-FAB1;Lo;0;L;7F3E;;;;N;;;;; -FAB2;CJK COMPATIBILITY IDEOGRAPH-FAB2;Lo;0;L;8005;;;;N;;;;; -FAB3;CJK COMPATIBILITY IDEOGRAPH-FAB3;Lo;0;L;8352;;;;N;;;;; -FAB4;CJK COMPATIBILITY IDEOGRAPH-FAB4;Lo;0;L;83EF;;;;N;;;;; -FAB5;CJK COMPATIBILITY IDEOGRAPH-FAB5;Lo;0;L;8779;;;;N;;;;; -FAB6;CJK COMPATIBILITY IDEOGRAPH-FAB6;Lo;0;L;8941;;;;N;;;;; -FAB7;CJK COMPATIBILITY IDEOGRAPH-FAB7;Lo;0;L;8986;;;;N;;;;; -FAB8;CJK COMPATIBILITY IDEOGRAPH-FAB8;Lo;0;L;8996;;;;N;;;;; -FAB9;CJK COMPATIBILITY IDEOGRAPH-FAB9;Lo;0;L;8ABF;;;;N;;;;; -FABA;CJK COMPATIBILITY IDEOGRAPH-FABA;Lo;0;L;8AF8;;;;N;;;;; -FABB;CJK COMPATIBILITY IDEOGRAPH-FABB;Lo;0;L;8ACB;;;;N;;;;; -FABC;CJK COMPATIBILITY IDEOGRAPH-FABC;Lo;0;L;8B01;;;;N;;;;; -FABD;CJK COMPATIBILITY IDEOGRAPH-FABD;Lo;0;L;8AFE;;;;N;;;;; -FABE;CJK COMPATIBILITY IDEOGRAPH-FABE;Lo;0;L;8AED;;;;N;;;;; -FABF;CJK COMPATIBILITY IDEOGRAPH-FABF;Lo;0;L;8B39;;;;N;;;;; -FAC0;CJK COMPATIBILITY IDEOGRAPH-FAC0;Lo;0;L;8B8A;;;;N;;;;; -FAC1;CJK COMPATIBILITY IDEOGRAPH-FAC1;Lo;0;L;8D08;;;;N;;;;; -FAC2;CJK COMPATIBILITY IDEOGRAPH-FAC2;Lo;0;L;8F38;;;;N;;;;; -FAC3;CJK COMPATIBILITY IDEOGRAPH-FAC3;Lo;0;L;9072;;;;N;;;;; -FAC4;CJK COMPATIBILITY IDEOGRAPH-FAC4;Lo;0;L;9199;;;;N;;;;; -FAC5;CJK COMPATIBILITY IDEOGRAPH-FAC5;Lo;0;L;9276;;;;N;;;;; -FAC6;CJK COMPATIBILITY IDEOGRAPH-FAC6;Lo;0;L;967C;;;;N;;;;; -FAC7;CJK COMPATIBILITY IDEOGRAPH-FAC7;Lo;0;L;96E3;;;;N;;;;; -FAC8;CJK COMPATIBILITY IDEOGRAPH-FAC8;Lo;0;L;9756;;;;N;;;;; -FAC9;CJK COMPATIBILITY IDEOGRAPH-FAC9;Lo;0;L;97DB;;;;N;;;;; -FACA;CJK COMPATIBILITY IDEOGRAPH-FACA;Lo;0;L;97FF;;;;N;;;;; -FACB;CJK COMPATIBILITY IDEOGRAPH-FACB;Lo;0;L;980B;;;;N;;;;; -FACC;CJK COMPATIBILITY IDEOGRAPH-FACC;Lo;0;L;983B;;;;N;;;;; -FACD;CJK COMPATIBILITY IDEOGRAPH-FACD;Lo;0;L;9B12;;;;N;;;;; -FACE;CJK COMPATIBILITY IDEOGRAPH-FACE;Lo;0;L;9F9C;;;;N;;;;; -FACF;CJK COMPATIBILITY IDEOGRAPH-FACF;Lo;0;L;2284A;;;;N;;;;; -FAD0;CJK COMPATIBILITY IDEOGRAPH-FAD0;Lo;0;L;22844;;;;N;;;;; -FAD1;CJK COMPATIBILITY IDEOGRAPH-FAD1;Lo;0;L;233D5;;;;N;;;;; -FAD2;CJK COMPATIBILITY IDEOGRAPH-FAD2;Lo;0;L;3B9D;;;;N;;;;; -FAD3;CJK COMPATIBILITY IDEOGRAPH-FAD3;Lo;0;L;4018;;;;N;;;;; -FAD4;CJK COMPATIBILITY IDEOGRAPH-FAD4;Lo;0;L;4039;;;;N;;;;; -FAD5;CJK COMPATIBILITY IDEOGRAPH-FAD5;Lo;0;L;25249;;;;N;;;;; -FAD6;CJK COMPATIBILITY IDEOGRAPH-FAD6;Lo;0;L;25CD0;;;;N;;;;; -FAD7;CJK COMPATIBILITY IDEOGRAPH-FAD7;Lo;0;L;27ED3;;;;N;;;;; -FAD8;CJK COMPATIBILITY IDEOGRAPH-FAD8;Lo;0;L;9F43;;;;N;;;;; -FAD9;CJK COMPATIBILITY IDEOGRAPH-FAD9;Lo;0;L;9F8E;;;;N;;;;; -FB00;LATIN SMALL LIGATURE FF;Ll;0;L; 0066 0066;;;;N;;;;; -FB01;LATIN SMALL LIGATURE FI;Ll;0;L; 0066 0069;;;;N;;;;; -FB02;LATIN SMALL LIGATURE FL;Ll;0;L; 0066 006C;;;;N;;;;; -FB03;LATIN SMALL LIGATURE FFI;Ll;0;L; 0066 0066 0069;;;;N;;;;; -FB04;LATIN SMALL LIGATURE FFL;Ll;0;L; 0066 0066 006C;;;;N;;;;; -FB05;LATIN SMALL LIGATURE LONG S T;Ll;0;L; 017F 0074;;;;N;;;;; -FB06;LATIN SMALL LIGATURE ST;Ll;0;L; 0073 0074;;;;N;;;;; -FB13;ARMENIAN SMALL LIGATURE MEN NOW;Ll;0;L; 0574 0576;;;;N;;;;; -FB14;ARMENIAN SMALL LIGATURE MEN ECH;Ll;0;L; 0574 0565;;;;N;;;;; -FB15;ARMENIAN SMALL LIGATURE MEN INI;Ll;0;L; 0574 056B;;;;N;;;;; -FB16;ARMENIAN SMALL LIGATURE VEW NOW;Ll;0;L; 057E 0576;;;;N;;;;; -FB17;ARMENIAN SMALL LIGATURE MEN XEH;Ll;0;L; 0574 056D;;;;N;;;;; -FB1D;HEBREW LETTER YOD WITH HIRIQ;Lo;0;R;05D9 05B4;;;;N;;;;; -FB1E;HEBREW POINT JUDEO-SPANISH VARIKA;Mn;26;NSM;;;;;N;HEBREW POINT VARIKA;;;; -FB1F;HEBREW LIGATURE YIDDISH YOD YOD PATAH;Lo;0;R;05F2 05B7;;;;N;;;;; -FB20;HEBREW LETTER ALTERNATIVE AYIN;Lo;0;R; 05E2;;;;N;;;;; -FB21;HEBREW LETTER WIDE ALEF;Lo;0;R; 05D0;;;;N;;;;; -FB22;HEBREW LETTER WIDE DALET;Lo;0;R; 05D3;;;;N;;;;; -FB23;HEBREW LETTER WIDE HE;Lo;0;R; 05D4;;;;N;;;;; -FB24;HEBREW LETTER WIDE KAF;Lo;0;R; 05DB;;;;N;;;;; -FB25;HEBREW LETTER WIDE LAMED;Lo;0;R; 05DC;;;;N;;;;; -FB26;HEBREW LETTER WIDE FINAL MEM;Lo;0;R; 05DD;;;;N;;;;; -FB27;HEBREW LETTER WIDE RESH;Lo;0;R; 05E8;;;;N;;;;; -FB28;HEBREW LETTER WIDE TAV;Lo;0;R; 05EA;;;;N;;;;; -FB29;HEBREW LETTER ALTERNATIVE PLUS SIGN;Sm;0;ES; 002B;;;;N;;;;; -FB2A;HEBREW LETTER SHIN WITH SHIN DOT;Lo;0;R;05E9 05C1;;;;N;;;;; -FB2B;HEBREW LETTER SHIN WITH SIN DOT;Lo;0;R;05E9 05C2;;;;N;;;;; -FB2C;HEBREW LETTER SHIN WITH DAGESH AND SHIN DOT;Lo;0;R;FB49 05C1;;;;N;;;;; -FB2D;HEBREW LETTER SHIN WITH DAGESH AND SIN DOT;Lo;0;R;FB49 05C2;;;;N;;;;; -FB2E;HEBREW LETTER ALEF WITH PATAH;Lo;0;R;05D0 05B7;;;;N;;;;; -FB2F;HEBREW LETTER ALEF WITH QAMATS;Lo;0;R;05D0 05B8;;;;N;;;;; -FB30;HEBREW LETTER ALEF WITH MAPIQ;Lo;0;R;05D0 05BC;;;;N;;;;; -FB31;HEBREW LETTER BET WITH DAGESH;Lo;0;R;05D1 05BC;;;;N;;;;; -FB32;HEBREW LETTER GIMEL WITH DAGESH;Lo;0;R;05D2 05BC;;;;N;;;;; -FB33;HEBREW LETTER DALET WITH DAGESH;Lo;0;R;05D3 05BC;;;;N;;;;; -FB34;HEBREW LETTER HE WITH MAPIQ;Lo;0;R;05D4 05BC;;;;N;;;;; -FB35;HEBREW LETTER VAV WITH DAGESH;Lo;0;R;05D5 05BC;;;;N;;;;; -FB36;HEBREW LETTER ZAYIN WITH DAGESH;Lo;0;R;05D6 05BC;;;;N;;;;; -FB38;HEBREW LETTER TET WITH DAGESH;Lo;0;R;05D8 05BC;;;;N;;;;; -FB39;HEBREW LETTER YOD WITH DAGESH;Lo;0;R;05D9 05BC;;;;N;;;;; -FB3A;HEBREW LETTER FINAL KAF WITH DAGESH;Lo;0;R;05DA 05BC;;;;N;;;;; -FB3B;HEBREW LETTER KAF WITH DAGESH;Lo;0;R;05DB 05BC;;;;N;;;;; -FB3C;HEBREW LETTER LAMED WITH DAGESH;Lo;0;R;05DC 05BC;;;;N;;;;; -FB3E;HEBREW LETTER MEM WITH DAGESH;Lo;0;R;05DE 05BC;;;;N;;;;; -FB40;HEBREW LETTER NUN WITH DAGESH;Lo;0;R;05E0 05BC;;;;N;;;;; -FB41;HEBREW LETTER SAMEKH WITH DAGESH;Lo;0;R;05E1 05BC;;;;N;;;;; -FB43;HEBREW LETTER FINAL PE WITH DAGESH;Lo;0;R;05E3 05BC;;;;N;;;;; -FB44;HEBREW LETTER PE WITH DAGESH;Lo;0;R;05E4 05BC;;;;N;;;;; -FB46;HEBREW LETTER TSADI WITH DAGESH;Lo;0;R;05E6 05BC;;;;N;;;;; -FB47;HEBREW LETTER QOF WITH DAGESH;Lo;0;R;05E7 05BC;;;;N;;;;; -FB48;HEBREW LETTER RESH WITH DAGESH;Lo;0;R;05E8 05BC;;;;N;;;;; -FB49;HEBREW LETTER SHIN WITH DAGESH;Lo;0;R;05E9 05BC;;;;N;;;;; -FB4A;HEBREW LETTER TAV WITH DAGESH;Lo;0;R;05EA 05BC;;;;N;;;;; -FB4B;HEBREW LETTER VAV WITH HOLAM;Lo;0;R;05D5 05B9;;;;N;;;;; -FB4C;HEBREW LETTER BET WITH RAFE;Lo;0;R;05D1 05BF;;;;N;;;;; -FB4D;HEBREW LETTER KAF WITH RAFE;Lo;0;R;05DB 05BF;;;;N;;;;; -FB4E;HEBREW LETTER PE WITH RAFE;Lo;0;R;05E4 05BF;;;;N;;;;; -FB4F;HEBREW LIGATURE ALEF LAMED;Lo;0;R; 05D0 05DC;;;;N;;;;; -FB50;ARABIC LETTER ALEF WASLA ISOLATED FORM;Lo;0;AL; 0671;;;;N;;;;; -FB51;ARABIC LETTER ALEF WASLA FINAL FORM;Lo;0;AL; 0671;;;;N;;;;; -FB52;ARABIC LETTER BEEH ISOLATED FORM;Lo;0;AL; 067B;;;;N;;;;; -FB53;ARABIC LETTER BEEH FINAL FORM;Lo;0;AL; 067B;;;;N;;;;; -FB54;ARABIC LETTER BEEH INITIAL FORM;Lo;0;AL; 067B;;;;N;;;;; -FB55;ARABIC LETTER BEEH MEDIAL FORM;Lo;0;AL; 067B;;;;N;;;;; -FB56;ARABIC LETTER PEH ISOLATED FORM;Lo;0;AL; 067E;;;;N;;;;; -FB57;ARABIC LETTER PEH FINAL FORM;Lo;0;AL; 067E;;;;N;;;;; -FB58;ARABIC LETTER PEH INITIAL FORM;Lo;0;AL; 067E;;;;N;;;;; -FB59;ARABIC LETTER PEH MEDIAL FORM;Lo;0;AL; 067E;;;;N;;;;; -FB5A;ARABIC LETTER BEHEH ISOLATED FORM;Lo;0;AL; 0680;;;;N;;;;; -FB5B;ARABIC LETTER BEHEH FINAL FORM;Lo;0;AL; 0680;;;;N;;;;; -FB5C;ARABIC LETTER BEHEH INITIAL FORM;Lo;0;AL; 0680;;;;N;;;;; -FB5D;ARABIC LETTER BEHEH MEDIAL FORM;Lo;0;AL; 0680;;;;N;;;;; -FB5E;ARABIC LETTER TTEHEH ISOLATED FORM;Lo;0;AL; 067A;;;;N;;;;; -FB5F;ARABIC LETTER TTEHEH FINAL FORM;Lo;0;AL; 067A;;;;N;;;;; -FB60;ARABIC LETTER TTEHEH INITIAL FORM;Lo;0;AL; 067A;;;;N;;;;; -FB61;ARABIC LETTER TTEHEH MEDIAL FORM;Lo;0;AL; 067A;;;;N;;;;; -FB62;ARABIC LETTER TEHEH ISOLATED FORM;Lo;0;AL; 067F;;;;N;;;;; -FB63;ARABIC LETTER TEHEH FINAL FORM;Lo;0;AL; 067F;;;;N;;;;; -FB64;ARABIC LETTER TEHEH INITIAL FORM;Lo;0;AL; 067F;;;;N;;;;; -FB65;ARABIC LETTER TEHEH MEDIAL FORM;Lo;0;AL; 067F;;;;N;;;;; -FB66;ARABIC LETTER TTEH ISOLATED FORM;Lo;0;AL; 0679;;;;N;;;;; -FB67;ARABIC LETTER TTEH FINAL FORM;Lo;0;AL; 0679;;;;N;;;;; -FB68;ARABIC LETTER TTEH INITIAL FORM;Lo;0;AL; 0679;;;;N;;;;; -FB69;ARABIC LETTER TTEH MEDIAL FORM;Lo;0;AL; 0679;;;;N;;;;; -FB6A;ARABIC LETTER VEH ISOLATED FORM;Lo;0;AL; 06A4;;;;N;;;;; -FB6B;ARABIC LETTER VEH FINAL FORM;Lo;0;AL; 06A4;;;;N;;;;; -FB6C;ARABIC LETTER VEH INITIAL FORM;Lo;0;AL; 06A4;;;;N;;;;; -FB6D;ARABIC LETTER VEH MEDIAL FORM;Lo;0;AL; 06A4;;;;N;;;;; -FB6E;ARABIC LETTER PEHEH ISOLATED FORM;Lo;0;AL; 06A6;;;;N;;;;; -FB6F;ARABIC LETTER PEHEH FINAL FORM;Lo;0;AL; 06A6;;;;N;;;;; -FB70;ARABIC LETTER PEHEH INITIAL FORM;Lo;0;AL; 06A6;;;;N;;;;; -FB71;ARABIC LETTER PEHEH MEDIAL FORM;Lo;0;AL; 06A6;;;;N;;;;; -FB72;ARABIC LETTER DYEH ISOLATED FORM;Lo;0;AL; 0684;;;;N;;;;; -FB73;ARABIC LETTER DYEH FINAL FORM;Lo;0;AL; 0684;;;;N;;;;; -FB74;ARABIC LETTER DYEH INITIAL FORM;Lo;0;AL; 0684;;;;N;;;;; -FB75;ARABIC LETTER DYEH MEDIAL FORM;Lo;0;AL; 0684;;;;N;;;;; -FB76;ARABIC LETTER NYEH ISOLATED FORM;Lo;0;AL; 0683;;;;N;;;;; -FB77;ARABIC LETTER NYEH FINAL FORM;Lo;0;AL; 0683;;;;N;;;;; -FB78;ARABIC LETTER NYEH INITIAL FORM;Lo;0;AL; 0683;;;;N;;;;; -FB79;ARABIC LETTER NYEH MEDIAL FORM;Lo;0;AL; 0683;;;;N;;;;; -FB7A;ARABIC LETTER TCHEH ISOLATED FORM;Lo;0;AL; 0686;;;;N;;;;; -FB7B;ARABIC LETTER TCHEH FINAL FORM;Lo;0;AL; 0686;;;;N;;;;; -FB7C;ARABIC LETTER TCHEH INITIAL FORM;Lo;0;AL; 0686;;;;N;;;;; -FB7D;ARABIC LETTER TCHEH MEDIAL FORM;Lo;0;AL; 0686;;;;N;;;;; -FB7E;ARABIC LETTER TCHEHEH ISOLATED FORM;Lo;0;AL; 0687;;;;N;;;;; -FB7F;ARABIC LETTER TCHEHEH FINAL FORM;Lo;0;AL; 0687;;;;N;;;;; -FB80;ARABIC LETTER TCHEHEH INITIAL FORM;Lo;0;AL; 0687;;;;N;;;;; -FB81;ARABIC LETTER TCHEHEH MEDIAL FORM;Lo;0;AL; 0687;;;;N;;;;; -FB82;ARABIC LETTER DDAHAL ISOLATED FORM;Lo;0;AL; 068D;;;;N;;;;; -FB83;ARABIC LETTER DDAHAL FINAL FORM;Lo;0;AL; 068D;;;;N;;;;; -FB84;ARABIC LETTER DAHAL ISOLATED FORM;Lo;0;AL; 068C;;;;N;;;;; -FB85;ARABIC LETTER DAHAL FINAL FORM;Lo;0;AL; 068C;;;;N;;;;; -FB86;ARABIC LETTER DUL ISOLATED FORM;Lo;0;AL; 068E;;;;N;;;;; -FB87;ARABIC LETTER DUL FINAL FORM;Lo;0;AL; 068E;;;;N;;;;; -FB88;ARABIC LETTER DDAL ISOLATED FORM;Lo;0;AL; 0688;;;;N;;;;; -FB89;ARABIC LETTER DDAL FINAL FORM;Lo;0;AL; 0688;;;;N;;;;; -FB8A;ARABIC LETTER JEH ISOLATED FORM;Lo;0;AL; 0698;;;;N;;;;; -FB8B;ARABIC LETTER JEH FINAL FORM;Lo;0;AL; 0698;;;;N;;;;; -FB8C;ARABIC LETTER RREH ISOLATED FORM;Lo;0;AL; 0691;;;;N;;;;; -FB8D;ARABIC LETTER RREH FINAL FORM;Lo;0;AL; 0691;;;;N;;;;; -FB8E;ARABIC LETTER KEHEH ISOLATED FORM;Lo;0;AL; 06A9;;;;N;;;;; -FB8F;ARABIC LETTER KEHEH FINAL FORM;Lo;0;AL; 06A9;;;;N;;;;; -FB90;ARABIC LETTER KEHEH INITIAL FORM;Lo;0;AL; 06A9;;;;N;;;;; -FB91;ARABIC LETTER KEHEH MEDIAL FORM;Lo;0;AL; 06A9;;;;N;;;;; -FB92;ARABIC LETTER GAF ISOLATED FORM;Lo;0;AL; 06AF;;;;N;;;;; -FB93;ARABIC LETTER GAF FINAL FORM;Lo;0;AL; 06AF;;;;N;;;;; -FB94;ARABIC LETTER GAF INITIAL FORM;Lo;0;AL; 06AF;;;;N;;;;; -FB95;ARABIC LETTER GAF MEDIAL FORM;Lo;0;AL; 06AF;;;;N;;;;; -FB96;ARABIC LETTER GUEH ISOLATED FORM;Lo;0;AL; 06B3;;;;N;;;;; -FB97;ARABIC LETTER GUEH FINAL FORM;Lo;0;AL; 06B3;;;;N;;;;; -FB98;ARABIC LETTER GUEH INITIAL FORM;Lo;0;AL; 06B3;;;;N;;;;; -FB99;ARABIC LETTER GUEH MEDIAL FORM;Lo;0;AL; 06B3;;;;N;;;;; -FB9A;ARABIC LETTER NGOEH ISOLATED FORM;Lo;0;AL; 06B1;;;;N;;;;; -FB9B;ARABIC LETTER NGOEH FINAL FORM;Lo;0;AL; 06B1;;;;N;;;;; -FB9C;ARABIC LETTER NGOEH INITIAL FORM;Lo;0;AL; 06B1;;;;N;;;;; -FB9D;ARABIC LETTER NGOEH MEDIAL FORM;Lo;0;AL; 06B1;;;;N;;;;; -FB9E;ARABIC LETTER NOON GHUNNA ISOLATED FORM;Lo;0;AL; 06BA;;;;N;;;;; -FB9F;ARABIC LETTER NOON GHUNNA FINAL FORM;Lo;0;AL; 06BA;;;;N;;;;; -FBA0;ARABIC LETTER RNOON ISOLATED FORM;Lo;0;AL; 06BB;;;;N;;;;; -FBA1;ARABIC LETTER RNOON FINAL FORM;Lo;0;AL; 06BB;;;;N;;;;; -FBA2;ARABIC LETTER RNOON INITIAL FORM;Lo;0;AL; 06BB;;;;N;;;;; -FBA3;ARABIC LETTER RNOON MEDIAL FORM;Lo;0;AL; 06BB;;;;N;;;;; -FBA4;ARABIC LETTER HEH WITH YEH ABOVE ISOLATED FORM;Lo;0;AL; 06C0;;;;N;;;;; -FBA5;ARABIC LETTER HEH WITH YEH ABOVE FINAL FORM;Lo;0;AL; 06C0;;;;N;;;;; -FBA6;ARABIC LETTER HEH GOAL ISOLATED FORM;Lo;0;AL; 06C1;;;;N;;;;; -FBA7;ARABIC LETTER HEH GOAL FINAL FORM;Lo;0;AL; 06C1;;;;N;;;;; -FBA8;ARABIC LETTER HEH GOAL INITIAL FORM;Lo;0;AL; 06C1;;;;N;;;;; -FBA9;ARABIC LETTER HEH GOAL MEDIAL FORM;Lo;0;AL; 06C1;;;;N;;;;; -FBAA;ARABIC LETTER HEH DOACHASHMEE ISOLATED FORM;Lo;0;AL; 06BE;;;;N;;;;; -FBAB;ARABIC LETTER HEH DOACHASHMEE FINAL FORM;Lo;0;AL; 06BE;;;;N;;;;; -FBAC;ARABIC LETTER HEH DOACHASHMEE INITIAL FORM;Lo;0;AL; 06BE;;;;N;;;;; -FBAD;ARABIC LETTER HEH DOACHASHMEE MEDIAL FORM;Lo;0;AL; 06BE;;;;N;;;;; -FBAE;ARABIC LETTER YEH BARREE ISOLATED FORM;Lo;0;AL; 06D2;;;;N;;;;; -FBAF;ARABIC LETTER YEH BARREE FINAL FORM;Lo;0;AL; 06D2;;;;N;;;;; -FBB0;ARABIC LETTER YEH BARREE WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 06D3;;;;N;;;;; -FBB1;ARABIC LETTER YEH BARREE WITH HAMZA ABOVE FINAL FORM;Lo;0;AL; 06D3;;;;N;;;;; -FBD3;ARABIC LETTER NG ISOLATED FORM;Lo;0;AL; 06AD;;;;N;;;;; -FBD4;ARABIC LETTER NG FINAL FORM;Lo;0;AL; 06AD;;;;N;;;;; -FBD5;ARABIC LETTER NG INITIAL FORM;Lo;0;AL; 06AD;;;;N;;;;; -FBD6;ARABIC LETTER NG MEDIAL FORM;Lo;0;AL; 06AD;;;;N;;;;; -FBD7;ARABIC LETTER U ISOLATED FORM;Lo;0;AL; 06C7;;;;N;;;;; -FBD8;ARABIC LETTER U FINAL FORM;Lo;0;AL; 06C7;;;;N;;;;; -FBD9;ARABIC LETTER OE ISOLATED FORM;Lo;0;AL; 06C6;;;;N;;;;; -FBDA;ARABIC LETTER OE FINAL FORM;Lo;0;AL; 06C6;;;;N;;;;; -FBDB;ARABIC LETTER YU ISOLATED FORM;Lo;0;AL; 06C8;;;;N;;;;; -FBDC;ARABIC LETTER YU FINAL FORM;Lo;0;AL; 06C8;;;;N;;;;; -FBDD;ARABIC LETTER U WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 0677;;;;N;;;;; -FBDE;ARABIC LETTER VE ISOLATED FORM;Lo;0;AL; 06CB;;;;N;;;;; -FBDF;ARABIC LETTER VE FINAL FORM;Lo;0;AL; 06CB;;;;N;;;;; -FBE0;ARABIC LETTER KIRGHIZ OE ISOLATED FORM;Lo;0;AL; 06C5;;;;N;;;;; -FBE1;ARABIC LETTER KIRGHIZ OE FINAL FORM;Lo;0;AL; 06C5;;;;N;;;;; -FBE2;ARABIC LETTER KIRGHIZ YU ISOLATED FORM;Lo;0;AL; 06C9;;;;N;;;;; -FBE3;ARABIC LETTER KIRGHIZ YU FINAL FORM;Lo;0;AL; 06C9;;;;N;;;;; -FBE4;ARABIC LETTER E ISOLATED FORM;Lo;0;AL; 06D0;;;;N;;;;; -FBE5;ARABIC LETTER E FINAL FORM;Lo;0;AL; 06D0;;;;N;;;;; -FBE6;ARABIC LETTER E INITIAL FORM;Lo;0;AL; 06D0;;;;N;;;;; -FBE7;ARABIC LETTER E MEDIAL FORM;Lo;0;AL; 06D0;;;;N;;;;; -FBE8;ARABIC LETTER UIGHUR KAZAKH KIRGHIZ ALEF MAKSURA INITIAL FORM;Lo;0;AL; 0649;;;;N;;;;; -FBE9;ARABIC LETTER UIGHUR KAZAKH KIRGHIZ ALEF MAKSURA MEDIAL FORM;Lo;0;AL; 0649;;;;N;;;;; -FBEA;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH ALEF ISOLATED FORM;Lo;0;AL; 0626 0627;;;;N;;;;; -FBEB;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH ALEF FINAL FORM;Lo;0;AL; 0626 0627;;;;N;;;;; -FBEC;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH AE ISOLATED FORM;Lo;0;AL; 0626 06D5;;;;N;;;;; -FBED;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH AE FINAL FORM;Lo;0;AL; 0626 06D5;;;;N;;;;; -FBEE;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH WAW ISOLATED FORM;Lo;0;AL; 0626 0648;;;;N;;;;; -FBEF;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH WAW FINAL FORM;Lo;0;AL; 0626 0648;;;;N;;;;; -FBF0;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH U ISOLATED FORM;Lo;0;AL; 0626 06C7;;;;N;;;;; -FBF1;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH U FINAL FORM;Lo;0;AL; 0626 06C7;;;;N;;;;; -FBF2;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH OE ISOLATED FORM;Lo;0;AL; 0626 06C6;;;;N;;;;; -FBF3;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH OE FINAL FORM;Lo;0;AL; 0626 06C6;;;;N;;;;; -FBF4;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH YU ISOLATED FORM;Lo;0;AL; 0626 06C8;;;;N;;;;; -FBF5;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH YU FINAL FORM;Lo;0;AL; 0626 06C8;;;;N;;;;; -FBF6;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH E ISOLATED FORM;Lo;0;AL; 0626 06D0;;;;N;;;;; -FBF7;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH E FINAL FORM;Lo;0;AL; 0626 06D0;;;;N;;;;; -FBF8;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH E INITIAL FORM;Lo;0;AL; 0626 06D0;;;;N;;;;; -FBF9;ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA ABOVE WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0626 0649;;;;N;;;;; -FBFA;ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA ABOVE WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0626 0649;;;;N;;;;; -FBFB;ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA ABOVE WITH ALEF MAKSURA INITIAL FORM;Lo;0;AL; 0626 0649;;;;N;;;;; -FBFC;ARABIC LETTER FARSI YEH ISOLATED FORM;Lo;0;AL; 06CC;;;;N;;;;; -FBFD;ARABIC LETTER FARSI YEH FINAL FORM;Lo;0;AL; 06CC;;;;N;;;;; -FBFE;ARABIC LETTER FARSI YEH INITIAL FORM;Lo;0;AL; 06CC;;;;N;;;;; -FBFF;ARABIC LETTER FARSI YEH MEDIAL FORM;Lo;0;AL; 06CC;;;;N;;;;; -FC00;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH JEEM ISOLATED FORM;Lo;0;AL; 0626 062C;;;;N;;;;; -FC01;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH HAH ISOLATED FORM;Lo;0;AL; 0626 062D;;;;N;;;;; -FC02;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH MEEM ISOLATED FORM;Lo;0;AL; 0626 0645;;;;N;;;;; -FC03;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0626 0649;;;;N;;;;; -FC04;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH YEH ISOLATED FORM;Lo;0;AL; 0626 064A;;;;N;;;;; -FC05;ARABIC LIGATURE BEH WITH JEEM ISOLATED FORM;Lo;0;AL; 0628 062C;;;;N;;;;; -FC06;ARABIC LIGATURE BEH WITH HAH ISOLATED FORM;Lo;0;AL; 0628 062D;;;;N;;;;; -FC07;ARABIC LIGATURE BEH WITH KHAH ISOLATED FORM;Lo;0;AL; 0628 062E;;;;N;;;;; -FC08;ARABIC LIGATURE BEH WITH MEEM ISOLATED FORM;Lo;0;AL; 0628 0645;;;;N;;;;; -FC09;ARABIC LIGATURE BEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0628 0649;;;;N;;;;; -FC0A;ARABIC LIGATURE BEH WITH YEH ISOLATED FORM;Lo;0;AL; 0628 064A;;;;N;;;;; -FC0B;ARABIC LIGATURE TEH WITH JEEM ISOLATED FORM;Lo;0;AL; 062A 062C;;;;N;;;;; -FC0C;ARABIC LIGATURE TEH WITH HAH ISOLATED FORM;Lo;0;AL; 062A 062D;;;;N;;;;; -FC0D;ARABIC LIGATURE TEH WITH KHAH ISOLATED FORM;Lo;0;AL; 062A 062E;;;;N;;;;; -FC0E;ARABIC LIGATURE TEH WITH MEEM ISOLATED FORM;Lo;0;AL; 062A 0645;;;;N;;;;; -FC0F;ARABIC LIGATURE TEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 062A 0649;;;;N;;;;; -FC10;ARABIC LIGATURE TEH WITH YEH ISOLATED FORM;Lo;0;AL; 062A 064A;;;;N;;;;; -FC11;ARABIC LIGATURE THEH WITH JEEM ISOLATED FORM;Lo;0;AL; 062B 062C;;;;N;;;;; -FC12;ARABIC LIGATURE THEH WITH MEEM ISOLATED FORM;Lo;0;AL; 062B 0645;;;;N;;;;; -FC13;ARABIC LIGATURE THEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 062B 0649;;;;N;;;;; -FC14;ARABIC LIGATURE THEH WITH YEH ISOLATED FORM;Lo;0;AL; 062B 064A;;;;N;;;;; -FC15;ARABIC LIGATURE JEEM WITH HAH ISOLATED FORM;Lo;0;AL; 062C 062D;;;;N;;;;; -FC16;ARABIC LIGATURE JEEM WITH MEEM ISOLATED FORM;Lo;0;AL; 062C 0645;;;;N;;;;; -FC17;ARABIC LIGATURE HAH WITH JEEM ISOLATED FORM;Lo;0;AL; 062D 062C;;;;N;;;;; -FC18;ARABIC LIGATURE HAH WITH MEEM ISOLATED FORM;Lo;0;AL; 062D 0645;;;;N;;;;; -FC19;ARABIC LIGATURE KHAH WITH JEEM ISOLATED FORM;Lo;0;AL; 062E 062C;;;;N;;;;; -FC1A;ARABIC LIGATURE KHAH WITH HAH ISOLATED FORM;Lo;0;AL; 062E 062D;;;;N;;;;; -FC1B;ARABIC LIGATURE KHAH WITH MEEM ISOLATED FORM;Lo;0;AL; 062E 0645;;;;N;;;;; -FC1C;ARABIC LIGATURE SEEN WITH JEEM ISOLATED FORM;Lo;0;AL; 0633 062C;;;;N;;;;; -FC1D;ARABIC LIGATURE SEEN WITH HAH ISOLATED FORM;Lo;0;AL; 0633 062D;;;;N;;;;; -FC1E;ARABIC LIGATURE SEEN WITH KHAH ISOLATED FORM;Lo;0;AL; 0633 062E;;;;N;;;;; -FC1F;ARABIC LIGATURE SEEN WITH MEEM ISOLATED FORM;Lo;0;AL; 0633 0645;;;;N;;;;; -FC20;ARABIC LIGATURE SAD WITH HAH ISOLATED FORM;Lo;0;AL; 0635 062D;;;;N;;;;; -FC21;ARABIC LIGATURE SAD WITH MEEM ISOLATED FORM;Lo;0;AL; 0635 0645;;;;N;;;;; -FC22;ARABIC LIGATURE DAD WITH JEEM ISOLATED FORM;Lo;0;AL; 0636 062C;;;;N;;;;; -FC23;ARABIC LIGATURE DAD WITH HAH ISOLATED FORM;Lo;0;AL; 0636 062D;;;;N;;;;; -FC24;ARABIC LIGATURE DAD WITH KHAH ISOLATED FORM;Lo;0;AL; 0636 062E;;;;N;;;;; -FC25;ARABIC LIGATURE DAD WITH MEEM ISOLATED FORM;Lo;0;AL; 0636 0645;;;;N;;;;; -FC26;ARABIC LIGATURE TAH WITH HAH ISOLATED FORM;Lo;0;AL; 0637 062D;;;;N;;;;; -FC27;ARABIC LIGATURE TAH WITH MEEM ISOLATED FORM;Lo;0;AL; 0637 0645;;;;N;;;;; -FC28;ARABIC LIGATURE ZAH WITH MEEM ISOLATED FORM;Lo;0;AL; 0638 0645;;;;N;;;;; -FC29;ARABIC LIGATURE AIN WITH JEEM ISOLATED FORM;Lo;0;AL; 0639 062C;;;;N;;;;; -FC2A;ARABIC LIGATURE AIN WITH MEEM ISOLATED FORM;Lo;0;AL; 0639 0645;;;;N;;;;; -FC2B;ARABIC LIGATURE GHAIN WITH JEEM ISOLATED FORM;Lo;0;AL; 063A 062C;;;;N;;;;; -FC2C;ARABIC LIGATURE GHAIN WITH MEEM ISOLATED FORM;Lo;0;AL; 063A 0645;;;;N;;;;; -FC2D;ARABIC LIGATURE FEH WITH JEEM ISOLATED FORM;Lo;0;AL; 0641 062C;;;;N;;;;; -FC2E;ARABIC LIGATURE FEH WITH HAH ISOLATED FORM;Lo;0;AL; 0641 062D;;;;N;;;;; -FC2F;ARABIC LIGATURE FEH WITH KHAH ISOLATED FORM;Lo;0;AL; 0641 062E;;;;N;;;;; -FC30;ARABIC LIGATURE FEH WITH MEEM ISOLATED FORM;Lo;0;AL; 0641 0645;;;;N;;;;; -FC31;ARABIC LIGATURE FEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0641 0649;;;;N;;;;; -FC32;ARABIC LIGATURE FEH WITH YEH ISOLATED FORM;Lo;0;AL; 0641 064A;;;;N;;;;; -FC33;ARABIC LIGATURE QAF WITH HAH ISOLATED FORM;Lo;0;AL; 0642 062D;;;;N;;;;; -FC34;ARABIC LIGATURE QAF WITH MEEM ISOLATED FORM;Lo;0;AL; 0642 0645;;;;N;;;;; -FC35;ARABIC LIGATURE QAF WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0642 0649;;;;N;;;;; -FC36;ARABIC LIGATURE QAF WITH YEH ISOLATED FORM;Lo;0;AL; 0642 064A;;;;N;;;;; -FC37;ARABIC LIGATURE KAF WITH ALEF ISOLATED FORM;Lo;0;AL; 0643 0627;;;;N;;;;; -FC38;ARABIC LIGATURE KAF WITH JEEM ISOLATED FORM;Lo;0;AL; 0643 062C;;;;N;;;;; -FC39;ARABIC LIGATURE KAF WITH HAH ISOLATED FORM;Lo;0;AL; 0643 062D;;;;N;;;;; -FC3A;ARABIC LIGATURE KAF WITH KHAH ISOLATED FORM;Lo;0;AL; 0643 062E;;;;N;;;;; -FC3B;ARABIC LIGATURE KAF WITH LAM ISOLATED FORM;Lo;0;AL; 0643 0644;;;;N;;;;; -FC3C;ARABIC LIGATURE KAF WITH MEEM ISOLATED FORM;Lo;0;AL; 0643 0645;;;;N;;;;; -FC3D;ARABIC LIGATURE KAF WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0643 0649;;;;N;;;;; -FC3E;ARABIC LIGATURE KAF WITH YEH ISOLATED FORM;Lo;0;AL; 0643 064A;;;;N;;;;; -FC3F;ARABIC LIGATURE LAM WITH JEEM ISOLATED FORM;Lo;0;AL; 0644 062C;;;;N;;;;; -FC40;ARABIC LIGATURE LAM WITH HAH ISOLATED FORM;Lo;0;AL; 0644 062D;;;;N;;;;; -FC41;ARABIC LIGATURE LAM WITH KHAH ISOLATED FORM;Lo;0;AL; 0644 062E;;;;N;;;;; -FC42;ARABIC LIGATURE LAM WITH MEEM ISOLATED FORM;Lo;0;AL; 0644 0645;;;;N;;;;; -FC43;ARABIC LIGATURE LAM WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0644 0649;;;;N;;;;; -FC44;ARABIC LIGATURE LAM WITH YEH ISOLATED FORM;Lo;0;AL; 0644 064A;;;;N;;;;; -FC45;ARABIC LIGATURE MEEM WITH JEEM ISOLATED FORM;Lo;0;AL; 0645 062C;;;;N;;;;; -FC46;ARABIC LIGATURE MEEM WITH HAH ISOLATED FORM;Lo;0;AL; 0645 062D;;;;N;;;;; -FC47;ARABIC LIGATURE MEEM WITH KHAH ISOLATED FORM;Lo;0;AL; 0645 062E;;;;N;;;;; -FC48;ARABIC LIGATURE MEEM WITH MEEM ISOLATED FORM;Lo;0;AL; 0645 0645;;;;N;;;;; -FC49;ARABIC LIGATURE MEEM WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0645 0649;;;;N;;;;; -FC4A;ARABIC LIGATURE MEEM WITH YEH ISOLATED FORM;Lo;0;AL; 0645 064A;;;;N;;;;; -FC4B;ARABIC LIGATURE NOON WITH JEEM ISOLATED FORM;Lo;0;AL; 0646 062C;;;;N;;;;; -FC4C;ARABIC LIGATURE NOON WITH HAH ISOLATED FORM;Lo;0;AL; 0646 062D;;;;N;;;;; -FC4D;ARABIC LIGATURE NOON WITH KHAH ISOLATED FORM;Lo;0;AL; 0646 062E;;;;N;;;;; -FC4E;ARABIC LIGATURE NOON WITH MEEM ISOLATED FORM;Lo;0;AL; 0646 0645;;;;N;;;;; -FC4F;ARABIC LIGATURE NOON WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0646 0649;;;;N;;;;; -FC50;ARABIC LIGATURE NOON WITH YEH ISOLATED FORM;Lo;0;AL; 0646 064A;;;;N;;;;; -FC51;ARABIC LIGATURE HEH WITH JEEM ISOLATED FORM;Lo;0;AL; 0647 062C;;;;N;;;;; -FC52;ARABIC LIGATURE HEH WITH MEEM ISOLATED FORM;Lo;0;AL; 0647 0645;;;;N;;;;; -FC53;ARABIC LIGATURE HEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0647 0649;;;;N;;;;; -FC54;ARABIC LIGATURE HEH WITH YEH ISOLATED FORM;Lo;0;AL; 0647 064A;;;;N;;;;; -FC55;ARABIC LIGATURE YEH WITH JEEM ISOLATED FORM;Lo;0;AL; 064A 062C;;;;N;;;;; -FC56;ARABIC LIGATURE YEH WITH HAH ISOLATED FORM;Lo;0;AL; 064A 062D;;;;N;;;;; -FC57;ARABIC LIGATURE YEH WITH KHAH ISOLATED FORM;Lo;0;AL; 064A 062E;;;;N;;;;; -FC58;ARABIC LIGATURE YEH WITH MEEM ISOLATED FORM;Lo;0;AL; 064A 0645;;;;N;;;;; -FC59;ARABIC LIGATURE YEH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 064A 0649;;;;N;;;;; -FC5A;ARABIC LIGATURE YEH WITH YEH ISOLATED FORM;Lo;0;AL; 064A 064A;;;;N;;;;; -FC5B;ARABIC LIGATURE THAL WITH SUPERSCRIPT ALEF ISOLATED FORM;Lo;0;AL; 0630 0670;;;;N;;;;; -FC5C;ARABIC LIGATURE REH WITH SUPERSCRIPT ALEF ISOLATED FORM;Lo;0;AL; 0631 0670;;;;N;;;;; -FC5D;ARABIC LIGATURE ALEF MAKSURA WITH SUPERSCRIPT ALEF ISOLATED FORM;Lo;0;AL; 0649 0670;;;;N;;;;; -FC5E;ARABIC LIGATURE SHADDA WITH DAMMATAN ISOLATED FORM;Lo;0;AL; 0020 064C 0651;;;;N;;;;; -FC5F;ARABIC LIGATURE SHADDA WITH KASRATAN ISOLATED FORM;Lo;0;AL; 0020 064D 0651;;;;N;;;;; -FC60;ARABIC LIGATURE SHADDA WITH FATHA ISOLATED FORM;Lo;0;AL; 0020 064E 0651;;;;N;;;;; -FC61;ARABIC LIGATURE SHADDA WITH DAMMA ISOLATED FORM;Lo;0;AL; 0020 064F 0651;;;;N;;;;; -FC62;ARABIC LIGATURE SHADDA WITH KASRA ISOLATED FORM;Lo;0;AL; 0020 0650 0651;;;;N;;;;; -FC63;ARABIC LIGATURE SHADDA WITH SUPERSCRIPT ALEF ISOLATED FORM;Lo;0;AL; 0020 0651 0670;;;;N;;;;; -FC64;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH REH FINAL FORM;Lo;0;AL; 0626 0631;;;;N;;;;; -FC65;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH ZAIN FINAL FORM;Lo;0;AL; 0626 0632;;;;N;;;;; -FC66;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH MEEM FINAL FORM;Lo;0;AL; 0626 0645;;;;N;;;;; -FC67;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH NOON FINAL FORM;Lo;0;AL; 0626 0646;;;;N;;;;; -FC68;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0626 0649;;;;N;;;;; -FC69;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH YEH FINAL FORM;Lo;0;AL; 0626 064A;;;;N;;;;; -FC6A;ARABIC LIGATURE BEH WITH REH FINAL FORM;Lo;0;AL; 0628 0631;;;;N;;;;; -FC6B;ARABIC LIGATURE BEH WITH ZAIN FINAL FORM;Lo;0;AL; 0628 0632;;;;N;;;;; -FC6C;ARABIC LIGATURE BEH WITH MEEM FINAL FORM;Lo;0;AL; 0628 0645;;;;N;;;;; -FC6D;ARABIC LIGATURE BEH WITH NOON FINAL FORM;Lo;0;AL; 0628 0646;;;;N;;;;; -FC6E;ARABIC LIGATURE BEH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0628 0649;;;;N;;;;; -FC6F;ARABIC LIGATURE BEH WITH YEH FINAL FORM;Lo;0;AL; 0628 064A;;;;N;;;;; -FC70;ARABIC LIGATURE TEH WITH REH FINAL FORM;Lo;0;AL; 062A 0631;;;;N;;;;; -FC71;ARABIC LIGATURE TEH WITH ZAIN FINAL FORM;Lo;0;AL; 062A 0632;;;;N;;;;; -FC72;ARABIC LIGATURE TEH WITH MEEM FINAL FORM;Lo;0;AL; 062A 0645;;;;N;;;;; -FC73;ARABIC LIGATURE TEH WITH NOON FINAL FORM;Lo;0;AL; 062A 0646;;;;N;;;;; -FC74;ARABIC LIGATURE TEH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062A 0649;;;;N;;;;; -FC75;ARABIC LIGATURE TEH WITH YEH FINAL FORM;Lo;0;AL; 062A 064A;;;;N;;;;; -FC76;ARABIC LIGATURE THEH WITH REH FINAL FORM;Lo;0;AL; 062B 0631;;;;N;;;;; -FC77;ARABIC LIGATURE THEH WITH ZAIN FINAL FORM;Lo;0;AL; 062B 0632;;;;N;;;;; -FC78;ARABIC LIGATURE THEH WITH MEEM FINAL FORM;Lo;0;AL; 062B 0645;;;;N;;;;; -FC79;ARABIC LIGATURE THEH WITH NOON FINAL FORM;Lo;0;AL; 062B 0646;;;;N;;;;; -FC7A;ARABIC LIGATURE THEH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062B 0649;;;;N;;;;; -FC7B;ARABIC LIGATURE THEH WITH YEH FINAL FORM;Lo;0;AL; 062B 064A;;;;N;;;;; -FC7C;ARABIC LIGATURE FEH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0641 0649;;;;N;;;;; -FC7D;ARABIC LIGATURE FEH WITH YEH FINAL FORM;Lo;0;AL; 0641 064A;;;;N;;;;; -FC7E;ARABIC LIGATURE QAF WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0642 0649;;;;N;;;;; -FC7F;ARABIC LIGATURE QAF WITH YEH FINAL FORM;Lo;0;AL; 0642 064A;;;;N;;;;; -FC80;ARABIC LIGATURE KAF WITH ALEF FINAL FORM;Lo;0;AL; 0643 0627;;;;N;;;;; -FC81;ARABIC LIGATURE KAF WITH LAM FINAL FORM;Lo;0;AL; 0643 0644;;;;N;;;;; -FC82;ARABIC LIGATURE KAF WITH MEEM FINAL FORM;Lo;0;AL; 0643 0645;;;;N;;;;; -FC83;ARABIC LIGATURE KAF WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0643 0649;;;;N;;;;; -FC84;ARABIC LIGATURE KAF WITH YEH FINAL FORM;Lo;0;AL; 0643 064A;;;;N;;;;; -FC85;ARABIC LIGATURE LAM WITH MEEM FINAL FORM;Lo;0;AL; 0644 0645;;;;N;;;;; -FC86;ARABIC LIGATURE LAM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0644 0649;;;;N;;;;; -FC87;ARABIC LIGATURE LAM WITH YEH FINAL FORM;Lo;0;AL; 0644 064A;;;;N;;;;; -FC88;ARABIC LIGATURE MEEM WITH ALEF FINAL FORM;Lo;0;AL; 0645 0627;;;;N;;;;; -FC89;ARABIC LIGATURE MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0645 0645;;;;N;;;;; -FC8A;ARABIC LIGATURE NOON WITH REH FINAL FORM;Lo;0;AL; 0646 0631;;;;N;;;;; -FC8B;ARABIC LIGATURE NOON WITH ZAIN FINAL FORM;Lo;0;AL; 0646 0632;;;;N;;;;; -FC8C;ARABIC LIGATURE NOON WITH MEEM FINAL FORM;Lo;0;AL; 0646 0645;;;;N;;;;; -FC8D;ARABIC LIGATURE NOON WITH NOON FINAL FORM;Lo;0;AL; 0646 0646;;;;N;;;;; -FC8E;ARABIC LIGATURE NOON WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0646 0649;;;;N;;;;; -FC8F;ARABIC LIGATURE NOON WITH YEH FINAL FORM;Lo;0;AL; 0646 064A;;;;N;;;;; -FC90;ARABIC LIGATURE ALEF MAKSURA WITH SUPERSCRIPT ALEF FINAL FORM;Lo;0;AL; 0649 0670;;;;N;;;;; -FC91;ARABIC LIGATURE YEH WITH REH FINAL FORM;Lo;0;AL; 064A 0631;;;;N;;;;; -FC92;ARABIC LIGATURE YEH WITH ZAIN FINAL FORM;Lo;0;AL; 064A 0632;;;;N;;;;; -FC93;ARABIC LIGATURE YEH WITH MEEM FINAL FORM;Lo;0;AL; 064A 0645;;;;N;;;;; -FC94;ARABIC LIGATURE YEH WITH NOON FINAL FORM;Lo;0;AL; 064A 0646;;;;N;;;;; -FC95;ARABIC LIGATURE YEH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 064A 0649;;;;N;;;;; -FC96;ARABIC LIGATURE YEH WITH YEH FINAL FORM;Lo;0;AL; 064A 064A;;;;N;;;;; -FC97;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH JEEM INITIAL FORM;Lo;0;AL; 0626 062C;;;;N;;;;; -FC98;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH HAH INITIAL FORM;Lo;0;AL; 0626 062D;;;;N;;;;; -FC99;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH KHAH INITIAL FORM;Lo;0;AL; 0626 062E;;;;N;;;;; -FC9A;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH MEEM INITIAL FORM;Lo;0;AL; 0626 0645;;;;N;;;;; -FC9B;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH HEH INITIAL FORM;Lo;0;AL; 0626 0647;;;;N;;;;; -FC9C;ARABIC LIGATURE BEH WITH JEEM INITIAL FORM;Lo;0;AL; 0628 062C;;;;N;;;;; -FC9D;ARABIC LIGATURE BEH WITH HAH INITIAL FORM;Lo;0;AL; 0628 062D;;;;N;;;;; -FC9E;ARABIC LIGATURE BEH WITH KHAH INITIAL FORM;Lo;0;AL; 0628 062E;;;;N;;;;; -FC9F;ARABIC LIGATURE BEH WITH MEEM INITIAL FORM;Lo;0;AL; 0628 0645;;;;N;;;;; -FCA0;ARABIC LIGATURE BEH WITH HEH INITIAL FORM;Lo;0;AL; 0628 0647;;;;N;;;;; -FCA1;ARABIC LIGATURE TEH WITH JEEM INITIAL FORM;Lo;0;AL; 062A 062C;;;;N;;;;; -FCA2;ARABIC LIGATURE TEH WITH HAH INITIAL FORM;Lo;0;AL; 062A 062D;;;;N;;;;; -FCA3;ARABIC LIGATURE TEH WITH KHAH INITIAL FORM;Lo;0;AL; 062A 062E;;;;N;;;;; -FCA4;ARABIC LIGATURE TEH WITH MEEM INITIAL FORM;Lo;0;AL; 062A 0645;;;;N;;;;; -FCA5;ARABIC LIGATURE TEH WITH HEH INITIAL FORM;Lo;0;AL; 062A 0647;;;;N;;;;; -FCA6;ARABIC LIGATURE THEH WITH MEEM INITIAL FORM;Lo;0;AL; 062B 0645;;;;N;;;;; -FCA7;ARABIC LIGATURE JEEM WITH HAH INITIAL FORM;Lo;0;AL; 062C 062D;;;;N;;;;; -FCA8;ARABIC LIGATURE JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 062C 0645;;;;N;;;;; -FCA9;ARABIC LIGATURE HAH WITH JEEM INITIAL FORM;Lo;0;AL; 062D 062C;;;;N;;;;; -FCAA;ARABIC LIGATURE HAH WITH MEEM INITIAL FORM;Lo;0;AL; 062D 0645;;;;N;;;;; -FCAB;ARABIC LIGATURE KHAH WITH JEEM INITIAL FORM;Lo;0;AL; 062E 062C;;;;N;;;;; -FCAC;ARABIC LIGATURE KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 062E 0645;;;;N;;;;; -FCAD;ARABIC LIGATURE SEEN WITH JEEM INITIAL FORM;Lo;0;AL; 0633 062C;;;;N;;;;; -FCAE;ARABIC LIGATURE SEEN WITH HAH INITIAL FORM;Lo;0;AL; 0633 062D;;;;N;;;;; -FCAF;ARABIC LIGATURE SEEN WITH KHAH INITIAL FORM;Lo;0;AL; 0633 062E;;;;N;;;;; -FCB0;ARABIC LIGATURE SEEN WITH MEEM INITIAL FORM;Lo;0;AL; 0633 0645;;;;N;;;;; -FCB1;ARABIC LIGATURE SAD WITH HAH INITIAL FORM;Lo;0;AL; 0635 062D;;;;N;;;;; -FCB2;ARABIC LIGATURE SAD WITH KHAH INITIAL FORM;Lo;0;AL; 0635 062E;;;;N;;;;; -FCB3;ARABIC LIGATURE SAD WITH MEEM INITIAL FORM;Lo;0;AL; 0635 0645;;;;N;;;;; -FCB4;ARABIC LIGATURE DAD WITH JEEM INITIAL FORM;Lo;0;AL; 0636 062C;;;;N;;;;; -FCB5;ARABIC LIGATURE DAD WITH HAH INITIAL FORM;Lo;0;AL; 0636 062D;;;;N;;;;; -FCB6;ARABIC LIGATURE DAD WITH KHAH INITIAL FORM;Lo;0;AL; 0636 062E;;;;N;;;;; -FCB7;ARABIC LIGATURE DAD WITH MEEM INITIAL FORM;Lo;0;AL; 0636 0645;;;;N;;;;; -FCB8;ARABIC LIGATURE TAH WITH HAH INITIAL FORM;Lo;0;AL; 0637 062D;;;;N;;;;; -FCB9;ARABIC LIGATURE ZAH WITH MEEM INITIAL FORM;Lo;0;AL; 0638 0645;;;;N;;;;; -FCBA;ARABIC LIGATURE AIN WITH JEEM INITIAL FORM;Lo;0;AL; 0639 062C;;;;N;;;;; -FCBB;ARABIC LIGATURE AIN WITH MEEM INITIAL FORM;Lo;0;AL; 0639 0645;;;;N;;;;; -FCBC;ARABIC LIGATURE GHAIN WITH JEEM INITIAL FORM;Lo;0;AL; 063A 062C;;;;N;;;;; -FCBD;ARABIC LIGATURE GHAIN WITH MEEM INITIAL FORM;Lo;0;AL; 063A 0645;;;;N;;;;; -FCBE;ARABIC LIGATURE FEH WITH JEEM INITIAL FORM;Lo;0;AL; 0641 062C;;;;N;;;;; -FCBF;ARABIC LIGATURE FEH WITH HAH INITIAL FORM;Lo;0;AL; 0641 062D;;;;N;;;;; -FCC0;ARABIC LIGATURE FEH WITH KHAH INITIAL FORM;Lo;0;AL; 0641 062E;;;;N;;;;; -FCC1;ARABIC LIGATURE FEH WITH MEEM INITIAL FORM;Lo;0;AL; 0641 0645;;;;N;;;;; -FCC2;ARABIC LIGATURE QAF WITH HAH INITIAL FORM;Lo;0;AL; 0642 062D;;;;N;;;;; -FCC3;ARABIC LIGATURE QAF WITH MEEM INITIAL FORM;Lo;0;AL; 0642 0645;;;;N;;;;; -FCC4;ARABIC LIGATURE KAF WITH JEEM INITIAL FORM;Lo;0;AL; 0643 062C;;;;N;;;;; -FCC5;ARABIC LIGATURE KAF WITH HAH INITIAL FORM;Lo;0;AL; 0643 062D;;;;N;;;;; -FCC6;ARABIC LIGATURE KAF WITH KHAH INITIAL FORM;Lo;0;AL; 0643 062E;;;;N;;;;; -FCC7;ARABIC LIGATURE KAF WITH LAM INITIAL FORM;Lo;0;AL; 0643 0644;;;;N;;;;; -FCC8;ARABIC LIGATURE KAF WITH MEEM INITIAL FORM;Lo;0;AL; 0643 0645;;;;N;;;;; -FCC9;ARABIC LIGATURE LAM WITH JEEM INITIAL FORM;Lo;0;AL; 0644 062C;;;;N;;;;; -FCCA;ARABIC LIGATURE LAM WITH HAH INITIAL FORM;Lo;0;AL; 0644 062D;;;;N;;;;; -FCCB;ARABIC LIGATURE LAM WITH KHAH INITIAL FORM;Lo;0;AL; 0644 062E;;;;N;;;;; -FCCC;ARABIC LIGATURE LAM WITH MEEM INITIAL FORM;Lo;0;AL; 0644 0645;;;;N;;;;; -FCCD;ARABIC LIGATURE LAM WITH HEH INITIAL FORM;Lo;0;AL; 0644 0647;;;;N;;;;; -FCCE;ARABIC LIGATURE MEEM WITH JEEM INITIAL FORM;Lo;0;AL; 0645 062C;;;;N;;;;; -FCCF;ARABIC LIGATURE MEEM WITH HAH INITIAL FORM;Lo;0;AL; 0645 062D;;;;N;;;;; -FCD0;ARABIC LIGATURE MEEM WITH KHAH INITIAL FORM;Lo;0;AL; 0645 062E;;;;N;;;;; -FCD1;ARABIC LIGATURE MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0645 0645;;;;N;;;;; -FCD2;ARABIC LIGATURE NOON WITH JEEM INITIAL FORM;Lo;0;AL; 0646 062C;;;;N;;;;; -FCD3;ARABIC LIGATURE NOON WITH HAH INITIAL FORM;Lo;0;AL; 0646 062D;;;;N;;;;; -FCD4;ARABIC LIGATURE NOON WITH KHAH INITIAL FORM;Lo;0;AL; 0646 062E;;;;N;;;;; -FCD5;ARABIC LIGATURE NOON WITH MEEM INITIAL FORM;Lo;0;AL; 0646 0645;;;;N;;;;; -FCD6;ARABIC LIGATURE NOON WITH HEH INITIAL FORM;Lo;0;AL; 0646 0647;;;;N;;;;; -FCD7;ARABIC LIGATURE HEH WITH JEEM INITIAL FORM;Lo;0;AL; 0647 062C;;;;N;;;;; -FCD8;ARABIC LIGATURE HEH WITH MEEM INITIAL FORM;Lo;0;AL; 0647 0645;;;;N;;;;; -FCD9;ARABIC LIGATURE HEH WITH SUPERSCRIPT ALEF INITIAL FORM;Lo;0;AL; 0647 0670;;;;N;;;;; -FCDA;ARABIC LIGATURE YEH WITH JEEM INITIAL FORM;Lo;0;AL; 064A 062C;;;;N;;;;; -FCDB;ARABIC LIGATURE YEH WITH HAH INITIAL FORM;Lo;0;AL; 064A 062D;;;;N;;;;; -FCDC;ARABIC LIGATURE YEH WITH KHAH INITIAL FORM;Lo;0;AL; 064A 062E;;;;N;;;;; -FCDD;ARABIC LIGATURE YEH WITH MEEM INITIAL FORM;Lo;0;AL; 064A 0645;;;;N;;;;; -FCDE;ARABIC LIGATURE YEH WITH HEH INITIAL FORM;Lo;0;AL; 064A 0647;;;;N;;;;; -FCDF;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH MEEM MEDIAL FORM;Lo;0;AL; 0626 0645;;;;N;;;;; -FCE0;ARABIC LIGATURE YEH WITH HAMZA ABOVE WITH HEH MEDIAL FORM;Lo;0;AL; 0626 0647;;;;N;;;;; -FCE1;ARABIC LIGATURE BEH WITH MEEM MEDIAL FORM;Lo;0;AL; 0628 0645;;;;N;;;;; -FCE2;ARABIC LIGATURE BEH WITH HEH MEDIAL FORM;Lo;0;AL; 0628 0647;;;;N;;;;; -FCE3;ARABIC LIGATURE TEH WITH MEEM MEDIAL FORM;Lo;0;AL; 062A 0645;;;;N;;;;; -FCE4;ARABIC LIGATURE TEH WITH HEH MEDIAL FORM;Lo;0;AL; 062A 0647;;;;N;;;;; -FCE5;ARABIC LIGATURE THEH WITH MEEM MEDIAL FORM;Lo;0;AL; 062B 0645;;;;N;;;;; -FCE6;ARABIC LIGATURE THEH WITH HEH MEDIAL FORM;Lo;0;AL; 062B 0647;;;;N;;;;; -FCE7;ARABIC LIGATURE SEEN WITH MEEM MEDIAL FORM;Lo;0;AL; 0633 0645;;;;N;;;;; -FCE8;ARABIC LIGATURE SEEN WITH HEH MEDIAL FORM;Lo;0;AL; 0633 0647;;;;N;;;;; -FCE9;ARABIC LIGATURE SHEEN WITH MEEM MEDIAL FORM;Lo;0;AL; 0634 0645;;;;N;;;;; -FCEA;ARABIC LIGATURE SHEEN WITH HEH MEDIAL FORM;Lo;0;AL; 0634 0647;;;;N;;;;; -FCEB;ARABIC LIGATURE KAF WITH LAM MEDIAL FORM;Lo;0;AL; 0643 0644;;;;N;;;;; -FCEC;ARABIC LIGATURE KAF WITH MEEM MEDIAL FORM;Lo;0;AL; 0643 0645;;;;N;;;;; -FCED;ARABIC LIGATURE LAM WITH MEEM MEDIAL FORM;Lo;0;AL; 0644 0645;;;;N;;;;; -FCEE;ARABIC LIGATURE NOON WITH MEEM MEDIAL FORM;Lo;0;AL; 0646 0645;;;;N;;;;; -FCEF;ARABIC LIGATURE NOON WITH HEH MEDIAL FORM;Lo;0;AL; 0646 0647;;;;N;;;;; -FCF0;ARABIC LIGATURE YEH WITH MEEM MEDIAL FORM;Lo;0;AL; 064A 0645;;;;N;;;;; -FCF1;ARABIC LIGATURE YEH WITH HEH MEDIAL FORM;Lo;0;AL; 064A 0647;;;;N;;;;; -FCF2;ARABIC LIGATURE SHADDA WITH FATHA MEDIAL FORM;Lo;0;AL; 0640 064E 0651;;;;N;;;;; -FCF3;ARABIC LIGATURE SHADDA WITH DAMMA MEDIAL FORM;Lo;0;AL; 0640 064F 0651;;;;N;;;;; -FCF4;ARABIC LIGATURE SHADDA WITH KASRA MEDIAL FORM;Lo;0;AL; 0640 0650 0651;;;;N;;;;; -FCF5;ARABIC LIGATURE TAH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0637 0649;;;;N;;;;; -FCF6;ARABIC LIGATURE TAH WITH YEH ISOLATED FORM;Lo;0;AL; 0637 064A;;;;N;;;;; -FCF7;ARABIC LIGATURE AIN WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0639 0649;;;;N;;;;; -FCF8;ARABIC LIGATURE AIN WITH YEH ISOLATED FORM;Lo;0;AL; 0639 064A;;;;N;;;;; -FCF9;ARABIC LIGATURE GHAIN WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 063A 0649;;;;N;;;;; -FCFA;ARABIC LIGATURE GHAIN WITH YEH ISOLATED FORM;Lo;0;AL; 063A 064A;;;;N;;;;; -FCFB;ARABIC LIGATURE SEEN WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0633 0649;;;;N;;;;; -FCFC;ARABIC LIGATURE SEEN WITH YEH ISOLATED FORM;Lo;0;AL; 0633 064A;;;;N;;;;; -FCFD;ARABIC LIGATURE SHEEN WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0634 0649;;;;N;;;;; -FCFE;ARABIC LIGATURE SHEEN WITH YEH ISOLATED FORM;Lo;0;AL; 0634 064A;;;;N;;;;; -FCFF;ARABIC LIGATURE HAH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 062D 0649;;;;N;;;;; -FD00;ARABIC LIGATURE HAH WITH YEH ISOLATED FORM;Lo;0;AL; 062D 064A;;;;N;;;;; -FD01;ARABIC LIGATURE JEEM WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 062C 0649;;;;N;;;;; -FD02;ARABIC LIGATURE JEEM WITH YEH ISOLATED FORM;Lo;0;AL; 062C 064A;;;;N;;;;; -FD03;ARABIC LIGATURE KHAH WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 062E 0649;;;;N;;;;; -FD04;ARABIC LIGATURE KHAH WITH YEH ISOLATED FORM;Lo;0;AL; 062E 064A;;;;N;;;;; -FD05;ARABIC LIGATURE SAD WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0635 0649;;;;N;;;;; -FD06;ARABIC LIGATURE SAD WITH YEH ISOLATED FORM;Lo;0;AL; 0635 064A;;;;N;;;;; -FD07;ARABIC LIGATURE DAD WITH ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0636 0649;;;;N;;;;; -FD08;ARABIC LIGATURE DAD WITH YEH ISOLATED FORM;Lo;0;AL; 0636 064A;;;;N;;;;; -FD09;ARABIC LIGATURE SHEEN WITH JEEM ISOLATED FORM;Lo;0;AL; 0634 062C;;;;N;;;;; -FD0A;ARABIC LIGATURE SHEEN WITH HAH ISOLATED FORM;Lo;0;AL; 0634 062D;;;;N;;;;; -FD0B;ARABIC LIGATURE SHEEN WITH KHAH ISOLATED FORM;Lo;0;AL; 0634 062E;;;;N;;;;; -FD0C;ARABIC LIGATURE SHEEN WITH MEEM ISOLATED FORM;Lo;0;AL; 0634 0645;;;;N;;;;; -FD0D;ARABIC LIGATURE SHEEN WITH REH ISOLATED FORM;Lo;0;AL; 0634 0631;;;;N;;;;; -FD0E;ARABIC LIGATURE SEEN WITH REH ISOLATED FORM;Lo;0;AL; 0633 0631;;;;N;;;;; -FD0F;ARABIC LIGATURE SAD WITH REH ISOLATED FORM;Lo;0;AL; 0635 0631;;;;N;;;;; -FD10;ARABIC LIGATURE DAD WITH REH ISOLATED FORM;Lo;0;AL; 0636 0631;;;;N;;;;; -FD11;ARABIC LIGATURE TAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0637 0649;;;;N;;;;; -FD12;ARABIC LIGATURE TAH WITH YEH FINAL FORM;Lo;0;AL; 0637 064A;;;;N;;;;; -FD13;ARABIC LIGATURE AIN WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0639 0649;;;;N;;;;; -FD14;ARABIC LIGATURE AIN WITH YEH FINAL FORM;Lo;0;AL; 0639 064A;;;;N;;;;; -FD15;ARABIC LIGATURE GHAIN WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 063A 0649;;;;N;;;;; -FD16;ARABIC LIGATURE GHAIN WITH YEH FINAL FORM;Lo;0;AL; 063A 064A;;;;N;;;;; -FD17;ARABIC LIGATURE SEEN WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0633 0649;;;;N;;;;; -FD18;ARABIC LIGATURE SEEN WITH YEH FINAL FORM;Lo;0;AL; 0633 064A;;;;N;;;;; -FD19;ARABIC LIGATURE SHEEN WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0634 0649;;;;N;;;;; -FD1A;ARABIC LIGATURE SHEEN WITH YEH FINAL FORM;Lo;0;AL; 0634 064A;;;;N;;;;; -FD1B;ARABIC LIGATURE HAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062D 0649;;;;N;;;;; -FD1C;ARABIC LIGATURE HAH WITH YEH FINAL FORM;Lo;0;AL; 062D 064A;;;;N;;;;; -FD1D;ARABIC LIGATURE JEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062C 0649;;;;N;;;;; -FD1E;ARABIC LIGATURE JEEM WITH YEH FINAL FORM;Lo;0;AL; 062C 064A;;;;N;;;;; -FD1F;ARABIC LIGATURE KHAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062E 0649;;;;N;;;;; -FD20;ARABIC LIGATURE KHAH WITH YEH FINAL FORM;Lo;0;AL; 062E 064A;;;;N;;;;; -FD21;ARABIC LIGATURE SAD WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0635 0649;;;;N;;;;; -FD22;ARABIC LIGATURE SAD WITH YEH FINAL FORM;Lo;0;AL; 0635 064A;;;;N;;;;; -FD23;ARABIC LIGATURE DAD WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0636 0649;;;;N;;;;; -FD24;ARABIC LIGATURE DAD WITH YEH FINAL FORM;Lo;0;AL; 0636 064A;;;;N;;;;; -FD25;ARABIC LIGATURE SHEEN WITH JEEM FINAL FORM;Lo;0;AL; 0634 062C;;;;N;;;;; -FD26;ARABIC LIGATURE SHEEN WITH HAH FINAL FORM;Lo;0;AL; 0634 062D;;;;N;;;;; -FD27;ARABIC LIGATURE SHEEN WITH KHAH FINAL FORM;Lo;0;AL; 0634 062E;;;;N;;;;; -FD28;ARABIC LIGATURE SHEEN WITH MEEM FINAL FORM;Lo;0;AL; 0634 0645;;;;N;;;;; -FD29;ARABIC LIGATURE SHEEN WITH REH FINAL FORM;Lo;0;AL; 0634 0631;;;;N;;;;; -FD2A;ARABIC LIGATURE SEEN WITH REH FINAL FORM;Lo;0;AL; 0633 0631;;;;N;;;;; -FD2B;ARABIC LIGATURE SAD WITH REH FINAL FORM;Lo;0;AL; 0635 0631;;;;N;;;;; -FD2C;ARABIC LIGATURE DAD WITH REH FINAL FORM;Lo;0;AL; 0636 0631;;;;N;;;;; -FD2D;ARABIC LIGATURE SHEEN WITH JEEM INITIAL FORM;Lo;0;AL; 0634 062C;;;;N;;;;; -FD2E;ARABIC LIGATURE SHEEN WITH HAH INITIAL FORM;Lo;0;AL; 0634 062D;;;;N;;;;; -FD2F;ARABIC LIGATURE SHEEN WITH KHAH INITIAL FORM;Lo;0;AL; 0634 062E;;;;N;;;;; -FD30;ARABIC LIGATURE SHEEN WITH MEEM INITIAL FORM;Lo;0;AL; 0634 0645;;;;N;;;;; -FD31;ARABIC LIGATURE SEEN WITH HEH INITIAL FORM;Lo;0;AL; 0633 0647;;;;N;;;;; -FD32;ARABIC LIGATURE SHEEN WITH HEH INITIAL FORM;Lo;0;AL; 0634 0647;;;;N;;;;; -FD33;ARABIC LIGATURE TAH WITH MEEM INITIAL FORM;Lo;0;AL; 0637 0645;;;;N;;;;; -FD34;ARABIC LIGATURE SEEN WITH JEEM MEDIAL FORM;Lo;0;AL; 0633 062C;;;;N;;;;; -FD35;ARABIC LIGATURE SEEN WITH HAH MEDIAL FORM;Lo;0;AL; 0633 062D;;;;N;;;;; -FD36;ARABIC LIGATURE SEEN WITH KHAH MEDIAL FORM;Lo;0;AL; 0633 062E;;;;N;;;;; -FD37;ARABIC LIGATURE SHEEN WITH JEEM MEDIAL FORM;Lo;0;AL; 0634 062C;;;;N;;;;; -FD38;ARABIC LIGATURE SHEEN WITH HAH MEDIAL FORM;Lo;0;AL; 0634 062D;;;;N;;;;; -FD39;ARABIC LIGATURE SHEEN WITH KHAH MEDIAL FORM;Lo;0;AL; 0634 062E;;;;N;;;;; -FD3A;ARABIC LIGATURE TAH WITH MEEM MEDIAL FORM;Lo;0;AL; 0637 0645;;;;N;;;;; -FD3B;ARABIC LIGATURE ZAH WITH MEEM MEDIAL FORM;Lo;0;AL; 0638 0645;;;;N;;;;; -FD3C;ARABIC LIGATURE ALEF WITH FATHATAN FINAL FORM;Lo;0;AL; 0627 064B;;;;N;;;;; -FD3D;ARABIC LIGATURE ALEF WITH FATHATAN ISOLATED FORM;Lo;0;AL; 0627 064B;;;;N;;;;; -FD3E;ORNATE LEFT PARENTHESIS;Ps;0;ON;;;;;N;;;;; -FD3F;ORNATE RIGHT PARENTHESIS;Pe;0;ON;;;;;N;;;;; -FD50;ARABIC LIGATURE TEH WITH JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 062A 062C 0645;;;;N;;;;; -FD51;ARABIC LIGATURE TEH WITH HAH WITH JEEM FINAL FORM;Lo;0;AL; 062A 062D 062C;;;;N;;;;; -FD52;ARABIC LIGATURE TEH WITH HAH WITH JEEM INITIAL FORM;Lo;0;AL; 062A 062D 062C;;;;N;;;;; -FD53;ARABIC LIGATURE TEH WITH HAH WITH MEEM INITIAL FORM;Lo;0;AL; 062A 062D 0645;;;;N;;;;; -FD54;ARABIC LIGATURE TEH WITH KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 062A 062E 0645;;;;N;;;;; -FD55;ARABIC LIGATURE TEH WITH MEEM WITH JEEM INITIAL FORM;Lo;0;AL; 062A 0645 062C;;;;N;;;;; -FD56;ARABIC LIGATURE TEH WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 062A 0645 062D;;;;N;;;;; -FD57;ARABIC LIGATURE TEH WITH MEEM WITH KHAH INITIAL FORM;Lo;0;AL; 062A 0645 062E;;;;N;;;;; -FD58;ARABIC LIGATURE JEEM WITH MEEM WITH HAH FINAL FORM;Lo;0;AL; 062C 0645 062D;;;;N;;;;; -FD59;ARABIC LIGATURE JEEM WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 062C 0645 062D;;;;N;;;;; -FD5A;ARABIC LIGATURE HAH WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 062D 0645 064A;;;;N;;;;; -FD5B;ARABIC LIGATURE HAH WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062D 0645 0649;;;;N;;;;; -FD5C;ARABIC LIGATURE SEEN WITH HAH WITH JEEM INITIAL FORM;Lo;0;AL; 0633 062D 062C;;;;N;;;;; -FD5D;ARABIC LIGATURE SEEN WITH JEEM WITH HAH INITIAL FORM;Lo;0;AL; 0633 062C 062D;;;;N;;;;; -FD5E;ARABIC LIGATURE SEEN WITH JEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0633 062C 0649;;;;N;;;;; -FD5F;ARABIC LIGATURE SEEN WITH MEEM WITH HAH FINAL FORM;Lo;0;AL; 0633 0645 062D;;;;N;;;;; -FD60;ARABIC LIGATURE SEEN WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 0633 0645 062D;;;;N;;;;; -FD61;ARABIC LIGATURE SEEN WITH MEEM WITH JEEM INITIAL FORM;Lo;0;AL; 0633 0645 062C;;;;N;;;;; -FD62;ARABIC LIGATURE SEEN WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0633 0645 0645;;;;N;;;;; -FD63;ARABIC LIGATURE SEEN WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0633 0645 0645;;;;N;;;;; -FD64;ARABIC LIGATURE SAD WITH HAH WITH HAH FINAL FORM;Lo;0;AL; 0635 062D 062D;;;;N;;;;; -FD65;ARABIC LIGATURE SAD WITH HAH WITH HAH INITIAL FORM;Lo;0;AL; 0635 062D 062D;;;;N;;;;; -FD66;ARABIC LIGATURE SAD WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0635 0645 0645;;;;N;;;;; -FD67;ARABIC LIGATURE SHEEN WITH HAH WITH MEEM FINAL FORM;Lo;0;AL; 0634 062D 0645;;;;N;;;;; -FD68;ARABIC LIGATURE SHEEN WITH HAH WITH MEEM INITIAL FORM;Lo;0;AL; 0634 062D 0645;;;;N;;;;; -FD69;ARABIC LIGATURE SHEEN WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 0634 062C 064A;;;;N;;;;; -FD6A;ARABIC LIGATURE SHEEN WITH MEEM WITH KHAH FINAL FORM;Lo;0;AL; 0634 0645 062E;;;;N;;;;; -FD6B;ARABIC LIGATURE SHEEN WITH MEEM WITH KHAH INITIAL FORM;Lo;0;AL; 0634 0645 062E;;;;N;;;;; -FD6C;ARABIC LIGATURE SHEEN WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0634 0645 0645;;;;N;;;;; -FD6D;ARABIC LIGATURE SHEEN WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0634 0645 0645;;;;N;;;;; -FD6E;ARABIC LIGATURE DAD WITH HAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0636 062D 0649;;;;N;;;;; -FD6F;ARABIC LIGATURE DAD WITH KHAH WITH MEEM FINAL FORM;Lo;0;AL; 0636 062E 0645;;;;N;;;;; -FD70;ARABIC LIGATURE DAD WITH KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 0636 062E 0645;;;;N;;;;; -FD71;ARABIC LIGATURE TAH WITH MEEM WITH HAH FINAL FORM;Lo;0;AL; 0637 0645 062D;;;;N;;;;; -FD72;ARABIC LIGATURE TAH WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 0637 0645 062D;;;;N;;;;; -FD73;ARABIC LIGATURE TAH WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0637 0645 0645;;;;N;;;;; -FD74;ARABIC LIGATURE TAH WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0637 0645 064A;;;;N;;;;; -FD75;ARABIC LIGATURE AIN WITH JEEM WITH MEEM FINAL FORM;Lo;0;AL; 0639 062C 0645;;;;N;;;;; -FD76;ARABIC LIGATURE AIN WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0639 0645 0645;;;;N;;;;; -FD77;ARABIC LIGATURE AIN WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0639 0645 0645;;;;N;;;;; -FD78;ARABIC LIGATURE AIN WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0639 0645 0649;;;;N;;;;; -FD79;ARABIC LIGATURE GHAIN WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 063A 0645 0645;;;;N;;;;; -FD7A;ARABIC LIGATURE GHAIN WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 063A 0645 064A;;;;N;;;;; -FD7B;ARABIC LIGATURE GHAIN WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 063A 0645 0649;;;;N;;;;; -FD7C;ARABIC LIGATURE FEH WITH KHAH WITH MEEM FINAL FORM;Lo;0;AL; 0641 062E 0645;;;;N;;;;; -FD7D;ARABIC LIGATURE FEH WITH KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 0641 062E 0645;;;;N;;;;; -FD7E;ARABIC LIGATURE QAF WITH MEEM WITH HAH FINAL FORM;Lo;0;AL; 0642 0645 062D;;;;N;;;;; -FD7F;ARABIC LIGATURE QAF WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0642 0645 0645;;;;N;;;;; -FD80;ARABIC LIGATURE LAM WITH HAH WITH MEEM FINAL FORM;Lo;0;AL; 0644 062D 0645;;;;N;;;;; -FD81;ARABIC LIGATURE LAM WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0644 062D 064A;;;;N;;;;; -FD82;ARABIC LIGATURE LAM WITH HAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0644 062D 0649;;;;N;;;;; -FD83;ARABIC LIGATURE LAM WITH JEEM WITH JEEM INITIAL FORM;Lo;0;AL; 0644 062C 062C;;;;N;;;;; -FD84;ARABIC LIGATURE LAM WITH JEEM WITH JEEM FINAL FORM;Lo;0;AL; 0644 062C 062C;;;;N;;;;; -FD85;ARABIC LIGATURE LAM WITH KHAH WITH MEEM FINAL FORM;Lo;0;AL; 0644 062E 0645;;;;N;;;;; -FD86;ARABIC LIGATURE LAM WITH KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 0644 062E 0645;;;;N;;;;; -FD87;ARABIC LIGATURE LAM WITH MEEM WITH HAH FINAL FORM;Lo;0;AL; 0644 0645 062D;;;;N;;;;; -FD88;ARABIC LIGATURE LAM WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 0644 0645 062D;;;;N;;;;; -FD89;ARABIC LIGATURE MEEM WITH HAH WITH JEEM INITIAL FORM;Lo;0;AL; 0645 062D 062C;;;;N;;;;; -FD8A;ARABIC LIGATURE MEEM WITH HAH WITH MEEM INITIAL FORM;Lo;0;AL; 0645 062D 0645;;;;N;;;;; -FD8B;ARABIC LIGATURE MEEM WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0645 062D 064A;;;;N;;;;; -FD8C;ARABIC LIGATURE MEEM WITH JEEM WITH HAH INITIAL FORM;Lo;0;AL; 0645 062C 062D;;;;N;;;;; -FD8D;ARABIC LIGATURE MEEM WITH JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0645 062C 0645;;;;N;;;;; -FD8E;ARABIC LIGATURE MEEM WITH KHAH WITH JEEM INITIAL FORM;Lo;0;AL; 0645 062E 062C;;;;N;;;;; -FD8F;ARABIC LIGATURE MEEM WITH KHAH WITH MEEM INITIAL FORM;Lo;0;AL; 0645 062E 0645;;;;N;;;;; -FD92;ARABIC LIGATURE MEEM WITH JEEM WITH KHAH INITIAL FORM;Lo;0;AL; 0645 062C 062E;;;;N;;;;; -FD93;ARABIC LIGATURE HEH WITH MEEM WITH JEEM INITIAL FORM;Lo;0;AL; 0647 0645 062C;;;;N;;;;; -FD94;ARABIC LIGATURE HEH WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0647 0645 0645;;;;N;;;;; -FD95;ARABIC LIGATURE NOON WITH HAH WITH MEEM INITIAL FORM;Lo;0;AL; 0646 062D 0645;;;;N;;;;; -FD96;ARABIC LIGATURE NOON WITH HAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0646 062D 0649;;;;N;;;;; -FD97;ARABIC LIGATURE NOON WITH JEEM WITH MEEM FINAL FORM;Lo;0;AL; 0646 062C 0645;;;;N;;;;; -FD98;ARABIC LIGATURE NOON WITH JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0646 062C 0645;;;;N;;;;; -FD99;ARABIC LIGATURE NOON WITH JEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0646 062C 0649;;;;N;;;;; -FD9A;ARABIC LIGATURE NOON WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0646 0645 064A;;;;N;;;;; -FD9B;ARABIC LIGATURE NOON WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0646 0645 0649;;;;N;;;;; -FD9C;ARABIC LIGATURE YEH WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 064A 0645 0645;;;;N;;;;; -FD9D;ARABIC LIGATURE YEH WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 064A 0645 0645;;;;N;;;;; -FD9E;ARABIC LIGATURE BEH WITH KHAH WITH YEH FINAL FORM;Lo;0;AL; 0628 062E 064A;;;;N;;;;; -FD9F;ARABIC LIGATURE TEH WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 062A 062C 064A;;;;N;;;;; -FDA0;ARABIC LIGATURE TEH WITH JEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062A 062C 0649;;;;N;;;;; -FDA1;ARABIC LIGATURE TEH WITH KHAH WITH YEH FINAL FORM;Lo;0;AL; 062A 062E 064A;;;;N;;;;; -FDA2;ARABIC LIGATURE TEH WITH KHAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062A 062E 0649;;;;N;;;;; -FDA3;ARABIC LIGATURE TEH WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 062A 0645 064A;;;;N;;;;; -FDA4;ARABIC LIGATURE TEH WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062A 0645 0649;;;;N;;;;; -FDA5;ARABIC LIGATURE JEEM WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 062C 0645 064A;;;;N;;;;; -FDA6;ARABIC LIGATURE JEEM WITH HAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062C 062D 0649;;;;N;;;;; -FDA7;ARABIC LIGATURE JEEM WITH MEEM WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 062C 0645 0649;;;;N;;;;; -FDA8;ARABIC LIGATURE SEEN WITH KHAH WITH ALEF MAKSURA FINAL FORM;Lo;0;AL; 0633 062E 0649;;;;N;;;;; -FDA9;ARABIC LIGATURE SAD WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0635 062D 064A;;;;N;;;;; -FDAA;ARABIC LIGATURE SHEEN WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0634 062D 064A;;;;N;;;;; -FDAB;ARABIC LIGATURE DAD WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0636 062D 064A;;;;N;;;;; -FDAC;ARABIC LIGATURE LAM WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 0644 062C 064A;;;;N;;;;; -FDAD;ARABIC LIGATURE LAM WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0644 0645 064A;;;;N;;;;; -FDAE;ARABIC LIGATURE YEH WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 064A 062D 064A;;;;N;;;;; -FDAF;ARABIC LIGATURE YEH WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 064A 062C 064A;;;;N;;;;; -FDB0;ARABIC LIGATURE YEH WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 064A 0645 064A;;;;N;;;;; -FDB1;ARABIC LIGATURE MEEM WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0645 0645 064A;;;;N;;;;; -FDB2;ARABIC LIGATURE QAF WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0642 0645 064A;;;;N;;;;; -FDB3;ARABIC LIGATURE NOON WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0646 062D 064A;;;;N;;;;; -FDB4;ARABIC LIGATURE QAF WITH MEEM WITH HAH INITIAL FORM;Lo;0;AL; 0642 0645 062D;;;;N;;;;; -FDB5;ARABIC LIGATURE LAM WITH HAH WITH MEEM INITIAL FORM;Lo;0;AL; 0644 062D 0645;;;;N;;;;; -FDB6;ARABIC LIGATURE AIN WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0639 0645 064A;;;;N;;;;; -FDB7;ARABIC LIGATURE KAF WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0643 0645 064A;;;;N;;;;; -FDB8;ARABIC LIGATURE NOON WITH JEEM WITH HAH INITIAL FORM;Lo;0;AL; 0646 062C 062D;;;;N;;;;; -FDB9;ARABIC LIGATURE MEEM WITH KHAH WITH YEH FINAL FORM;Lo;0;AL; 0645 062E 064A;;;;N;;;;; -FDBA;ARABIC LIGATURE LAM WITH JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0644 062C 0645;;;;N;;;;; -FDBB;ARABIC LIGATURE KAF WITH MEEM WITH MEEM FINAL FORM;Lo;0;AL; 0643 0645 0645;;;;N;;;;; -FDBC;ARABIC LIGATURE LAM WITH JEEM WITH MEEM FINAL FORM;Lo;0;AL; 0644 062C 0645;;;;N;;;;; -FDBD;ARABIC LIGATURE NOON WITH JEEM WITH HAH FINAL FORM;Lo;0;AL; 0646 062C 062D;;;;N;;;;; -FDBE;ARABIC LIGATURE JEEM WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 062C 062D 064A;;;;N;;;;; -FDBF;ARABIC LIGATURE HAH WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 062D 062C 064A;;;;N;;;;; -FDC0;ARABIC LIGATURE MEEM WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 0645 062C 064A;;;;N;;;;; -FDC1;ARABIC LIGATURE FEH WITH MEEM WITH YEH FINAL FORM;Lo;0;AL; 0641 0645 064A;;;;N;;;;; -FDC2;ARABIC LIGATURE BEH WITH HAH WITH YEH FINAL FORM;Lo;0;AL; 0628 062D 064A;;;;N;;;;; -FDC3;ARABIC LIGATURE KAF WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0643 0645 0645;;;;N;;;;; -FDC4;ARABIC LIGATURE AIN WITH JEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0639 062C 0645;;;;N;;;;; -FDC5;ARABIC LIGATURE SAD WITH MEEM WITH MEEM INITIAL FORM;Lo;0;AL; 0635 0645 0645;;;;N;;;;; -FDC6;ARABIC LIGATURE SEEN WITH KHAH WITH YEH FINAL FORM;Lo;0;AL; 0633 062E 064A;;;;N;;;;; -FDC7;ARABIC LIGATURE NOON WITH JEEM WITH YEH FINAL FORM;Lo;0;AL; 0646 062C 064A;;;;N;;;;; -FDF0;ARABIC LIGATURE SALLA USED AS KORANIC STOP SIGN ISOLATED FORM;Lo;0;AL; 0635 0644 06D2;;;;N;;;;; -FDF1;ARABIC LIGATURE QALA USED AS KORANIC STOP SIGN ISOLATED FORM;Lo;0;AL; 0642 0644 06D2;;;;N;;;;; -FDF2;ARABIC LIGATURE ALLAH ISOLATED FORM;Lo;0;AL; 0627 0644 0644 0647;;;;N;;;;; -FDF3;ARABIC LIGATURE AKBAR ISOLATED FORM;Lo;0;AL; 0627 0643 0628 0631;;;;N;;;;; -FDF4;ARABIC LIGATURE MOHAMMAD ISOLATED FORM;Lo;0;AL; 0645 062D 0645 062F;;;;N;;;;; -FDF5;ARABIC LIGATURE SALAM ISOLATED FORM;Lo;0;AL; 0635 0644 0639 0645;;;;N;;;;; -FDF6;ARABIC LIGATURE RASOUL ISOLATED FORM;Lo;0;AL; 0631 0633 0648 0644;;;;N;;;;; -FDF7;ARABIC LIGATURE ALAYHE ISOLATED FORM;Lo;0;AL; 0639 0644 064A 0647;;;;N;;;;; -FDF8;ARABIC LIGATURE WASALLAM ISOLATED FORM;Lo;0;AL; 0648 0633 0644 0645;;;;N;;;;; -FDF9;ARABIC LIGATURE SALLA ISOLATED FORM;Lo;0;AL; 0635 0644 0649;;;;N;;;;; -FDFA;ARABIC LIGATURE SALLALLAHOU ALAYHE WASALLAM;Lo;0;AL; 0635 0644 0649 0020 0627 0644 0644 0647 0020 0639 0644 064A 0647 0020 0648 0633 0644 0645;;;;N;ARABIC LETTER SALLALLAHOU ALAYHE WASALLAM;;;; -FDFB;ARABIC LIGATURE JALLAJALALOUHOU;Lo;0;AL; 062C 0644 0020 062C 0644 0627 0644 0647;;;;N;ARABIC LETTER JALLAJALALOUHOU;;;; -FDFC;RIAL SIGN;Sc;0;AL; 0631 06CC 0627 0644;;;;N;;;;; -FDFD;ARABIC LIGATURE BISMILLAH AR-RAHMAN AR-RAHEEM;So;0;ON;;;;;N;;;;; -FE00;VARIATION SELECTOR-1;Mn;0;NSM;;;;;N;;;;; -FE01;VARIATION SELECTOR-2;Mn;0;NSM;;;;;N;;;;; -FE02;VARIATION SELECTOR-3;Mn;0;NSM;;;;;N;;;;; -FE03;VARIATION SELECTOR-4;Mn;0;NSM;;;;;N;;;;; -FE04;VARIATION SELECTOR-5;Mn;0;NSM;;;;;N;;;;; -FE05;VARIATION SELECTOR-6;Mn;0;NSM;;;;;N;;;;; -FE06;VARIATION SELECTOR-7;Mn;0;NSM;;;;;N;;;;; -FE07;VARIATION SELECTOR-8;Mn;0;NSM;;;;;N;;;;; -FE08;VARIATION SELECTOR-9;Mn;0;NSM;;;;;N;;;;; -FE09;VARIATION SELECTOR-10;Mn;0;NSM;;;;;N;;;;; -FE0A;VARIATION SELECTOR-11;Mn;0;NSM;;;;;N;;;;; -FE0B;VARIATION SELECTOR-12;Mn;0;NSM;;;;;N;;;;; -FE0C;VARIATION SELECTOR-13;Mn;0;NSM;;;;;N;;;;; -FE0D;VARIATION SELECTOR-14;Mn;0;NSM;;;;;N;;;;; -FE0E;VARIATION SELECTOR-15;Mn;0;NSM;;;;;N;;;;; -FE0F;VARIATION SELECTOR-16;Mn;0;NSM;;;;;N;;;;; -FE10;PRESENTATION FORM FOR VERTICAL COMMA;Po;0;ON; 002C;;;;N;;;;; -FE11;PRESENTATION FORM FOR VERTICAL IDEOGRAPHIC COMMA;Po;0;ON; 3001;;;;N;;;;; -FE12;PRESENTATION FORM FOR VERTICAL IDEOGRAPHIC FULL STOP;Po;0;ON; 3002;;;;N;;;;; -FE13;PRESENTATION FORM FOR VERTICAL COLON;Po;0;ON; 003A;;;;N;;;;; -FE14;PRESENTATION FORM FOR VERTICAL SEMICOLON;Po;0;ON; 003B;;;;N;;;;; -FE15;PRESENTATION FORM FOR VERTICAL EXCLAMATION MARK;Po;0;ON; 0021;;;;N;;;;; -FE16;PRESENTATION FORM FOR VERTICAL QUESTION MARK;Po;0;ON; 003F;;;;N;;;;; -FE17;PRESENTATION FORM FOR VERTICAL LEFT WHITE LENTICULAR BRACKET;Ps;0;ON; 3016;;;;N;;;;; -FE18;PRESENTATION FORM FOR VERTICAL RIGHT WHITE LENTICULAR BRAKCET;Pe;0;ON; 3017;;;;N;;;;; -FE19;PRESENTATION FORM FOR VERTICAL HORIZONTAL ELLIPSIS;Po;0;ON; 2026;;;;N;;;;; -FE20;COMBINING LIGATURE LEFT HALF;Mn;230;NSM;;;;;N;;;;; -FE21;COMBINING LIGATURE RIGHT HALF;Mn;230;NSM;;;;;N;;;;; -FE22;COMBINING DOUBLE TILDE LEFT HALF;Mn;230;NSM;;;;;N;;;;; -FE23;COMBINING DOUBLE TILDE RIGHT HALF;Mn;230;NSM;;;;;N;;;;; -FE24;COMBINING MACRON LEFT HALF;Mn;230;NSM;;;;;N;;;;; -FE25;COMBINING MACRON RIGHT HALF;Mn;230;NSM;;;;;N;;;;; -FE26;COMBINING CONJOINING MACRON;Mn;230;NSM;;;;;N;;;;; -FE30;PRESENTATION FORM FOR VERTICAL TWO DOT LEADER;Po;0;ON; 2025;;;;N;GLYPH FOR VERTICAL TWO DOT LEADER;;;; -FE31;PRESENTATION FORM FOR VERTICAL EM DASH;Pd;0;ON; 2014;;;;N;GLYPH FOR VERTICAL EM DASH;;;; -FE32;PRESENTATION FORM FOR VERTICAL EN DASH;Pd;0;ON; 2013;;;;N;GLYPH FOR VERTICAL EN DASH;;;; -FE33;PRESENTATION FORM FOR VERTICAL LOW LINE;Pc;0;ON; 005F;;;;N;GLYPH FOR VERTICAL SPACING UNDERSCORE;;;; -FE34;PRESENTATION FORM FOR VERTICAL WAVY LOW LINE;Pc;0;ON; 005F;;;;N;GLYPH FOR VERTICAL SPACING WAVY UNDERSCORE;;;; -FE35;PRESENTATION FORM FOR VERTICAL LEFT PARENTHESIS;Ps;0;ON; 0028;;;;N;GLYPH FOR VERTICAL OPENING PARENTHESIS;;;; -FE36;PRESENTATION FORM FOR VERTICAL RIGHT PARENTHESIS;Pe;0;ON; 0029;;;;N;GLYPH FOR VERTICAL CLOSING PARENTHESIS;;;; -FE37;PRESENTATION FORM FOR VERTICAL LEFT CURLY BRACKET;Ps;0;ON; 007B;;;;N;GLYPH FOR VERTICAL OPENING CURLY BRACKET;;;; -FE38;PRESENTATION FORM FOR VERTICAL RIGHT CURLY BRACKET;Pe;0;ON; 007D;;;;N;GLYPH FOR VERTICAL CLOSING CURLY BRACKET;;;; -FE39;PRESENTATION FORM FOR VERTICAL LEFT TORTOISE SHELL BRACKET;Ps;0;ON; 3014;;;;N;GLYPH FOR VERTICAL OPENING TORTOISE SHELL BRACKET;;;; -FE3A;PRESENTATION FORM FOR VERTICAL RIGHT TORTOISE SHELL BRACKET;Pe;0;ON; 3015;;;;N;GLYPH FOR VERTICAL CLOSING TORTOISE SHELL BRACKET;;;; -FE3B;PRESENTATION FORM FOR VERTICAL LEFT BLACK LENTICULAR BRACKET;Ps;0;ON; 3010;;;;N;GLYPH FOR VERTICAL OPENING BLACK LENTICULAR BRACKET;;;; -FE3C;PRESENTATION FORM FOR VERTICAL RIGHT BLACK LENTICULAR BRACKET;Pe;0;ON; 3011;;;;N;GLYPH FOR VERTICAL CLOSING BLACK LENTICULAR BRACKET;;;; -FE3D;PRESENTATION FORM FOR VERTICAL LEFT DOUBLE ANGLE BRACKET;Ps;0;ON; 300A;;;;N;GLYPH FOR VERTICAL OPENING DOUBLE ANGLE BRACKET;;;; -FE3E;PRESENTATION FORM FOR VERTICAL RIGHT DOUBLE ANGLE BRACKET;Pe;0;ON; 300B;;;;N;GLYPH FOR VERTICAL CLOSING DOUBLE ANGLE BRACKET;;;; -FE3F;PRESENTATION FORM FOR VERTICAL LEFT ANGLE BRACKET;Ps;0;ON; 3008;;;;N;GLYPH FOR VERTICAL OPENING ANGLE BRACKET;;;; -FE40;PRESENTATION FORM FOR VERTICAL RIGHT ANGLE BRACKET;Pe;0;ON; 3009;;;;N;GLYPH FOR VERTICAL CLOSING ANGLE BRACKET;;;; -FE41;PRESENTATION FORM FOR VERTICAL LEFT CORNER BRACKET;Ps;0;ON; 300C;;;;N;GLYPH FOR VERTICAL OPENING CORNER BRACKET;;;; -FE42;PRESENTATION FORM FOR VERTICAL RIGHT CORNER BRACKET;Pe;0;ON; 300D;;;;N;GLYPH FOR VERTICAL CLOSING CORNER BRACKET;;;; -FE43;PRESENTATION FORM FOR VERTICAL LEFT WHITE CORNER BRACKET;Ps;0;ON; 300E;;;;N;GLYPH FOR VERTICAL OPENING WHITE CORNER BRACKET;;;; -FE44;PRESENTATION FORM FOR VERTICAL RIGHT WHITE CORNER BRACKET;Pe;0;ON; 300F;;;;N;GLYPH FOR VERTICAL CLOSING WHITE CORNER BRACKET;;;; -FE45;SESAME DOT;Po;0;ON;;;;;N;;;;; -FE46;WHITE SESAME DOT;Po;0;ON;;;;;N;;;;; -FE47;PRESENTATION FORM FOR VERTICAL LEFT SQUARE BRACKET;Ps;0;ON; 005B;;;;N;;;;; -FE48;PRESENTATION FORM FOR VERTICAL RIGHT SQUARE BRACKET;Pe;0;ON; 005D;;;;N;;;;; -FE49;DASHED OVERLINE;Po;0;ON; 203E;;;;N;SPACING DASHED OVERSCORE;;;; -FE4A;CENTRELINE OVERLINE;Po;0;ON; 203E;;;;N;SPACING CENTERLINE OVERSCORE;;;; -FE4B;WAVY OVERLINE;Po;0;ON; 203E;;;;N;SPACING WAVY OVERSCORE;;;; -FE4C;DOUBLE WAVY OVERLINE;Po;0;ON; 203E;;;;N;SPACING DOUBLE WAVY OVERSCORE;;;; -FE4D;DASHED LOW LINE;Pc;0;ON; 005F;;;;N;SPACING DASHED UNDERSCORE;;;; -FE4E;CENTRELINE LOW LINE;Pc;0;ON; 005F;;;;N;SPACING CENTERLINE UNDERSCORE;;;; -FE4F;WAVY LOW LINE;Pc;0;ON; 005F;;;;N;SPACING WAVY UNDERSCORE;;;; -FE50;SMALL COMMA;Po;0;CS; 002C;;;;N;;;;; -FE51;SMALL IDEOGRAPHIC COMMA;Po;0;ON; 3001;;;;N;;;;; -FE52;SMALL FULL STOP;Po;0;CS; 002E;;;;N;SMALL PERIOD;;;; -FE54;SMALL SEMICOLON;Po;0;ON; 003B;;;;N;;;;; -FE55;SMALL COLON;Po;0;CS; 003A;;;;N;;;;; -FE56;SMALL QUESTION MARK;Po;0;ON; 003F;;;;N;;;;; -FE57;SMALL EXCLAMATION MARK;Po;0;ON; 0021;;;;N;;;;; -FE58;SMALL EM DASH;Pd;0;ON; 2014;;;;N;;;;; -FE59;SMALL LEFT PARENTHESIS;Ps;0;ON; 0028;;;;Y;SMALL OPENING PARENTHESIS;;;; -FE5A;SMALL RIGHT PARENTHESIS;Pe;0;ON; 0029;;;;Y;SMALL CLOSING PARENTHESIS;;;; -FE5B;SMALL LEFT CURLY BRACKET;Ps;0;ON; 007B;;;;Y;SMALL OPENING CURLY BRACKET;;;; -FE5C;SMALL RIGHT CURLY BRACKET;Pe;0;ON; 007D;;;;Y;SMALL CLOSING CURLY BRACKET;;;; -FE5D;SMALL LEFT TORTOISE SHELL BRACKET;Ps;0;ON; 3014;;;;Y;SMALL OPENING TORTOISE SHELL BRACKET;;;; -FE5E;SMALL RIGHT TORTOISE SHELL BRACKET;Pe;0;ON; 3015;;;;Y;SMALL CLOSING TORTOISE SHELL BRACKET;;;; -FE5F;SMALL NUMBER SIGN;Po;0;ET; 0023;;;;N;;;;; -FE60;SMALL AMPERSAND;Po;0;ON; 0026;;;;N;;;;; -FE61;SMALL ASTERISK;Po;0;ON; 002A;;;;N;;;;; -FE62;SMALL PLUS SIGN;Sm;0;ES; 002B;;;;N;;;;; -FE63;SMALL HYPHEN-MINUS;Pd;0;ES; 002D;;;;N;;;;; -FE64;SMALL LESS-THAN SIGN;Sm;0;ON; 003C;;;;Y;;;;; -FE65;SMALL GREATER-THAN SIGN;Sm;0;ON; 003E;;;;Y;;;;; -FE66;SMALL EQUALS SIGN;Sm;0;ON; 003D;;;;N;;;;; -FE68;SMALL REVERSE SOLIDUS;Po;0;ON; 005C;;;;N;SMALL BACKSLASH;;;; -FE69;SMALL DOLLAR SIGN;Sc;0;ET; 0024;;;;N;;;;; -FE6A;SMALL PERCENT SIGN;Po;0;ET; 0025;;;;N;;;;; -FE6B;SMALL COMMERCIAL AT;Po;0;ON; 0040;;;;N;;;;; -FE70;ARABIC FATHATAN ISOLATED FORM;Lo;0;AL; 0020 064B;;;;N;ARABIC SPACING FATHATAN;;;; -FE71;ARABIC TATWEEL WITH FATHATAN ABOVE;Lo;0;AL; 0640 064B;;;;N;ARABIC FATHATAN ON TATWEEL;;;; -FE72;ARABIC DAMMATAN ISOLATED FORM;Lo;0;AL; 0020 064C;;;;N;ARABIC SPACING DAMMATAN;;;; -FE73;ARABIC TAIL FRAGMENT;Lo;0;AL;;;;;N;;;;; -FE74;ARABIC KASRATAN ISOLATED FORM;Lo;0;AL; 0020 064D;;;;N;ARABIC SPACING KASRATAN;;;; -FE76;ARABIC FATHA ISOLATED FORM;Lo;0;AL; 0020 064E;;;;N;ARABIC SPACING FATHAH;;;; -FE77;ARABIC FATHA MEDIAL FORM;Lo;0;AL; 0640 064E;;;;N;ARABIC FATHAH ON TATWEEL;;;; -FE78;ARABIC DAMMA ISOLATED FORM;Lo;0;AL; 0020 064F;;;;N;ARABIC SPACING DAMMAH;;;; -FE79;ARABIC DAMMA MEDIAL FORM;Lo;0;AL; 0640 064F;;;;N;ARABIC DAMMAH ON TATWEEL;;;; -FE7A;ARABIC KASRA ISOLATED FORM;Lo;0;AL; 0020 0650;;;;N;ARABIC SPACING KASRAH;;;; -FE7B;ARABIC KASRA MEDIAL FORM;Lo;0;AL; 0640 0650;;;;N;ARABIC KASRAH ON TATWEEL;;;; -FE7C;ARABIC SHADDA ISOLATED FORM;Lo;0;AL; 0020 0651;;;;N;ARABIC SPACING SHADDAH;;;; -FE7D;ARABIC SHADDA MEDIAL FORM;Lo;0;AL; 0640 0651;;;;N;ARABIC SHADDAH ON TATWEEL;;;; -FE7E;ARABIC SUKUN ISOLATED FORM;Lo;0;AL; 0020 0652;;;;N;ARABIC SPACING SUKUN;;;; -FE7F;ARABIC SUKUN MEDIAL FORM;Lo;0;AL; 0640 0652;;;;N;ARABIC SUKUN ON TATWEEL;;;; -FE80;ARABIC LETTER HAMZA ISOLATED FORM;Lo;0;AL; 0621;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH;;;; -FE81;ARABIC LETTER ALEF WITH MADDA ABOVE ISOLATED FORM;Lo;0;AL; 0622;;;;N;GLYPH FOR ISOLATE ARABIC MADDAH ON ALEF;;;; -FE82;ARABIC LETTER ALEF WITH MADDA ABOVE FINAL FORM;Lo;0;AL; 0622;;;;N;GLYPH FOR FINAL ARABIC MADDAH ON ALEF;;;; -FE83;ARABIC LETTER ALEF WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 0623;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH ON ALEF;;;; -FE84;ARABIC LETTER ALEF WITH HAMZA ABOVE FINAL FORM;Lo;0;AL; 0623;;;;N;GLYPH FOR FINAL ARABIC HAMZAH ON ALEF;;;; -FE85;ARABIC LETTER WAW WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 0624;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH ON WAW;;;; -FE86;ARABIC LETTER WAW WITH HAMZA ABOVE FINAL FORM;Lo;0;AL; 0624;;;;N;GLYPH FOR FINAL ARABIC HAMZAH ON WAW;;;; -FE87;ARABIC LETTER ALEF WITH HAMZA BELOW ISOLATED FORM;Lo;0;AL; 0625;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH UNDER ALEF;;;; -FE88;ARABIC LETTER ALEF WITH HAMZA BELOW FINAL FORM;Lo;0;AL; 0625;;;;N;GLYPH FOR FINAL ARABIC HAMZAH UNDER ALEF;;;; -FE89;ARABIC LETTER YEH WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 0626;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH ON YA;;;; -FE8A;ARABIC LETTER YEH WITH HAMZA ABOVE FINAL FORM;Lo;0;AL; 0626;;;;N;GLYPH FOR FINAL ARABIC HAMZAH ON YA;;;; -FE8B;ARABIC LETTER YEH WITH HAMZA ABOVE INITIAL FORM;Lo;0;AL; 0626;;;;N;GLYPH FOR INITIAL ARABIC HAMZAH ON YA;;;; -FE8C;ARABIC LETTER YEH WITH HAMZA ABOVE MEDIAL FORM;Lo;0;AL; 0626;;;;N;GLYPH FOR MEDIAL ARABIC HAMZAH ON YA;;;; -FE8D;ARABIC LETTER ALEF ISOLATED FORM;Lo;0;AL; 0627;;;;N;GLYPH FOR ISOLATE ARABIC ALEF;;;; -FE8E;ARABIC LETTER ALEF FINAL FORM;Lo;0;AL; 0627;;;;N;GLYPH FOR FINAL ARABIC ALEF;;;; -FE8F;ARABIC LETTER BEH ISOLATED FORM;Lo;0;AL; 0628;;;;N;GLYPH FOR ISOLATE ARABIC BAA;;;; -FE90;ARABIC LETTER BEH FINAL FORM;Lo;0;AL; 0628;;;;N;GLYPH FOR FINAL ARABIC BAA;;;; -FE91;ARABIC LETTER BEH INITIAL FORM;Lo;0;AL; 0628;;;;N;GLYPH FOR INITIAL ARABIC BAA;;;; -FE92;ARABIC LETTER BEH MEDIAL FORM;Lo;0;AL; 0628;;;;N;GLYPH FOR MEDIAL ARABIC BAA;;;; -FE93;ARABIC LETTER TEH MARBUTA ISOLATED FORM;Lo;0;AL; 0629;;;;N;GLYPH FOR ISOLATE ARABIC TAA MARBUTAH;;;; -FE94;ARABIC LETTER TEH MARBUTA FINAL FORM;Lo;0;AL; 0629;;;;N;GLYPH FOR FINAL ARABIC TAA MARBUTAH;;;; -FE95;ARABIC LETTER TEH ISOLATED FORM;Lo;0;AL; 062A;;;;N;GLYPH FOR ISOLATE ARABIC TAA;;;; -FE96;ARABIC LETTER TEH FINAL FORM;Lo;0;AL; 062A;;;;N;GLYPH FOR FINAL ARABIC TAA;;;; -FE97;ARABIC LETTER TEH INITIAL FORM;Lo;0;AL; 062A;;;;N;GLYPH FOR INITIAL ARABIC TAA;;;; -FE98;ARABIC LETTER TEH MEDIAL FORM;Lo;0;AL; 062A;;;;N;GLYPH FOR MEDIAL ARABIC TAA;;;; -FE99;ARABIC LETTER THEH ISOLATED FORM;Lo;0;AL; 062B;;;;N;GLYPH FOR ISOLATE ARABIC THAA;;;; -FE9A;ARABIC LETTER THEH FINAL FORM;Lo;0;AL; 062B;;;;N;GLYPH FOR FINAL ARABIC THAA;;;; -FE9B;ARABIC LETTER THEH INITIAL FORM;Lo;0;AL; 062B;;;;N;GLYPH FOR INITIAL ARABIC THAA;;;; -FE9C;ARABIC LETTER THEH MEDIAL FORM;Lo;0;AL; 062B;;;;N;GLYPH FOR MEDIAL ARABIC THAA;;;; -FE9D;ARABIC LETTER JEEM ISOLATED FORM;Lo;0;AL; 062C;;;;N;GLYPH FOR ISOLATE ARABIC JEEM;;;; -FE9E;ARABIC LETTER JEEM FINAL FORM;Lo;0;AL; 062C;;;;N;GLYPH FOR FINAL ARABIC JEEM;;;; -FE9F;ARABIC LETTER JEEM INITIAL FORM;Lo;0;AL; 062C;;;;N;GLYPH FOR INITIAL ARABIC JEEM;;;; -FEA0;ARABIC LETTER JEEM MEDIAL FORM;Lo;0;AL; 062C;;;;N;GLYPH FOR MEDIAL ARABIC JEEM;;;; -FEA1;ARABIC LETTER HAH ISOLATED FORM;Lo;0;AL; 062D;;;;N;GLYPH FOR ISOLATE ARABIC HAA;;;; -FEA2;ARABIC LETTER HAH FINAL FORM;Lo;0;AL; 062D;;;;N;GLYPH FOR FINAL ARABIC HAA;;;; -FEA3;ARABIC LETTER HAH INITIAL FORM;Lo;0;AL; 062D;;;;N;GLYPH FOR INITIAL ARABIC HAA;;;; -FEA4;ARABIC LETTER HAH MEDIAL FORM;Lo;0;AL; 062D;;;;N;GLYPH FOR MEDIAL ARABIC HAA;;;; -FEA5;ARABIC LETTER KHAH ISOLATED FORM;Lo;0;AL; 062E;;;;N;GLYPH FOR ISOLATE ARABIC KHAA;;;; -FEA6;ARABIC LETTER KHAH FINAL FORM;Lo;0;AL; 062E;;;;N;GLYPH FOR FINAL ARABIC KHAA;;;; -FEA7;ARABIC LETTER KHAH INITIAL FORM;Lo;0;AL; 062E;;;;N;GLYPH FOR INITIAL ARABIC KHAA;;;; -FEA8;ARABIC LETTER KHAH MEDIAL FORM;Lo;0;AL; 062E;;;;N;GLYPH FOR MEDIAL ARABIC KHAA;;;; -FEA9;ARABIC LETTER DAL ISOLATED FORM;Lo;0;AL; 062F;;;;N;GLYPH FOR ISOLATE ARABIC DAL;;;; -FEAA;ARABIC LETTER DAL FINAL FORM;Lo;0;AL; 062F;;;;N;GLYPH FOR FINAL ARABIC DAL;;;; -FEAB;ARABIC LETTER THAL ISOLATED FORM;Lo;0;AL; 0630;;;;N;GLYPH FOR ISOLATE ARABIC THAL;;;; -FEAC;ARABIC LETTER THAL FINAL FORM;Lo;0;AL; 0630;;;;N;GLYPH FOR FINAL ARABIC THAL;;;; -FEAD;ARABIC LETTER REH ISOLATED FORM;Lo;0;AL; 0631;;;;N;GLYPH FOR ISOLATE ARABIC RA;;;; -FEAE;ARABIC LETTER REH FINAL FORM;Lo;0;AL; 0631;;;;N;GLYPH FOR FINAL ARABIC RA;;;; -FEAF;ARABIC LETTER ZAIN ISOLATED FORM;Lo;0;AL; 0632;;;;N;GLYPH FOR ISOLATE ARABIC ZAIN;;;; -FEB0;ARABIC LETTER ZAIN FINAL FORM;Lo;0;AL; 0632;;;;N;GLYPH FOR FINAL ARABIC ZAIN;;;; -FEB1;ARABIC LETTER SEEN ISOLATED FORM;Lo;0;AL; 0633;;;;N;GLYPH FOR ISOLATE ARABIC SEEN;;;; -FEB2;ARABIC LETTER SEEN FINAL FORM;Lo;0;AL; 0633;;;;N;GLYPH FOR FINAL ARABIC SEEN;;;; -FEB3;ARABIC LETTER SEEN INITIAL FORM;Lo;0;AL; 0633;;;;N;GLYPH FOR INITIAL ARABIC SEEN;;;; -FEB4;ARABIC LETTER SEEN MEDIAL FORM;Lo;0;AL; 0633;;;;N;GLYPH FOR MEDIAL ARABIC SEEN;;;; -FEB5;ARABIC LETTER SHEEN ISOLATED FORM;Lo;0;AL; 0634;;;;N;GLYPH FOR ISOLATE ARABIC SHEEN;;;; -FEB6;ARABIC LETTER SHEEN FINAL FORM;Lo;0;AL; 0634;;;;N;GLYPH FOR FINAL ARABIC SHEEN;;;; -FEB7;ARABIC LETTER SHEEN INITIAL FORM;Lo;0;AL; 0634;;;;N;GLYPH FOR INITIAL ARABIC SHEEN;;;; -FEB8;ARABIC LETTER SHEEN MEDIAL FORM;Lo;0;AL; 0634;;;;N;GLYPH FOR MEDIAL ARABIC SHEEN;;;; -FEB9;ARABIC LETTER SAD ISOLATED FORM;Lo;0;AL; 0635;;;;N;GLYPH FOR ISOLATE ARABIC SAD;;;; -FEBA;ARABIC LETTER SAD FINAL FORM;Lo;0;AL; 0635;;;;N;GLYPH FOR FINAL ARABIC SAD;;;; -FEBB;ARABIC LETTER SAD INITIAL FORM;Lo;0;AL; 0635;;;;N;GLYPH FOR INITIAL ARABIC SAD;;;; -FEBC;ARABIC LETTER SAD MEDIAL FORM;Lo;0;AL; 0635;;;;N;GLYPH FOR MEDIAL ARABIC SAD;;;; -FEBD;ARABIC LETTER DAD ISOLATED FORM;Lo;0;AL; 0636;;;;N;GLYPH FOR ISOLATE ARABIC DAD;;;; -FEBE;ARABIC LETTER DAD FINAL FORM;Lo;0;AL; 0636;;;;N;GLYPH FOR FINAL ARABIC DAD;;;; -FEBF;ARABIC LETTER DAD INITIAL FORM;Lo;0;AL; 0636;;;;N;GLYPH FOR INITIAL ARABIC DAD;;;; -FEC0;ARABIC LETTER DAD MEDIAL FORM;Lo;0;AL; 0636;;;;N;GLYPH FOR MEDIAL ARABIC DAD;;;; -FEC1;ARABIC LETTER TAH ISOLATED FORM;Lo;0;AL; 0637;;;;N;GLYPH FOR ISOLATE ARABIC TAH;;;; -FEC2;ARABIC LETTER TAH FINAL FORM;Lo;0;AL; 0637;;;;N;GLYPH FOR FINAL ARABIC TAH;;;; -FEC3;ARABIC LETTER TAH INITIAL FORM;Lo;0;AL; 0637;;;;N;GLYPH FOR INITIAL ARABIC TAH;;;; -FEC4;ARABIC LETTER TAH MEDIAL FORM;Lo;0;AL; 0637;;;;N;GLYPH FOR MEDIAL ARABIC TAH;;;; -FEC5;ARABIC LETTER ZAH ISOLATED FORM;Lo;0;AL; 0638;;;;N;GLYPH FOR ISOLATE ARABIC DHAH;;;; -FEC6;ARABIC LETTER ZAH FINAL FORM;Lo;0;AL; 0638;;;;N;GLYPH FOR FINAL ARABIC DHAH;;;; -FEC7;ARABIC LETTER ZAH INITIAL FORM;Lo;0;AL; 0638;;;;N;GLYPH FOR INITIAL ARABIC DHAH;;;; -FEC8;ARABIC LETTER ZAH MEDIAL FORM;Lo;0;AL; 0638;;;;N;GLYPH FOR MEDIAL ARABIC DHAH;;;; -FEC9;ARABIC LETTER AIN ISOLATED FORM;Lo;0;AL; 0639;;;;N;GLYPH FOR ISOLATE ARABIC AIN;;;; -FECA;ARABIC LETTER AIN FINAL FORM;Lo;0;AL; 0639;;;;N;GLYPH FOR FINAL ARABIC AIN;;;; -FECB;ARABIC LETTER AIN INITIAL FORM;Lo;0;AL; 0639;;;;N;GLYPH FOR INITIAL ARABIC AIN;;;; -FECC;ARABIC LETTER AIN MEDIAL FORM;Lo;0;AL; 0639;;;;N;GLYPH FOR MEDIAL ARABIC AIN;;;; -FECD;ARABIC LETTER GHAIN ISOLATED FORM;Lo;0;AL; 063A;;;;N;GLYPH FOR ISOLATE ARABIC GHAIN;;;; -FECE;ARABIC LETTER GHAIN FINAL FORM;Lo;0;AL; 063A;;;;N;GLYPH FOR FINAL ARABIC GHAIN;;;; -FECF;ARABIC LETTER GHAIN INITIAL FORM;Lo;0;AL; 063A;;;;N;GLYPH FOR INITIAL ARABIC GHAIN;;;; -FED0;ARABIC LETTER GHAIN MEDIAL FORM;Lo;0;AL; 063A;;;;N;GLYPH FOR MEDIAL ARABIC GHAIN;;;; -FED1;ARABIC LETTER FEH ISOLATED FORM;Lo;0;AL; 0641;;;;N;GLYPH FOR ISOLATE ARABIC FA;;;; -FED2;ARABIC LETTER FEH FINAL FORM;Lo;0;AL; 0641;;;;N;GLYPH FOR FINAL ARABIC FA;;;; -FED3;ARABIC LETTER FEH INITIAL FORM;Lo;0;AL; 0641;;;;N;GLYPH FOR INITIAL ARABIC FA;;;; -FED4;ARABIC LETTER FEH MEDIAL FORM;Lo;0;AL; 0641;;;;N;GLYPH FOR MEDIAL ARABIC FA;;;; -FED5;ARABIC LETTER QAF ISOLATED FORM;Lo;0;AL; 0642;;;;N;GLYPH FOR ISOLATE ARABIC QAF;;;; -FED6;ARABIC LETTER QAF FINAL FORM;Lo;0;AL; 0642;;;;N;GLYPH FOR FINAL ARABIC QAF;;;; -FED7;ARABIC LETTER QAF INITIAL FORM;Lo;0;AL; 0642;;;;N;GLYPH FOR INITIAL ARABIC QAF;;;; -FED8;ARABIC LETTER QAF MEDIAL FORM;Lo;0;AL; 0642;;;;N;GLYPH FOR MEDIAL ARABIC QAF;;;; -FED9;ARABIC LETTER KAF ISOLATED FORM;Lo;0;AL; 0643;;;;N;GLYPH FOR ISOLATE ARABIC CAF;;;; -FEDA;ARABIC LETTER KAF FINAL FORM;Lo;0;AL; 0643;;;;N;GLYPH FOR FINAL ARABIC CAF;;;; -FEDB;ARABIC LETTER KAF INITIAL FORM;Lo;0;AL; 0643;;;;N;GLYPH FOR INITIAL ARABIC CAF;;;; -FEDC;ARABIC LETTER KAF MEDIAL FORM;Lo;0;AL; 0643;;;;N;GLYPH FOR MEDIAL ARABIC CAF;;;; -FEDD;ARABIC LETTER LAM ISOLATED FORM;Lo;0;AL; 0644;;;;N;GLYPH FOR ISOLATE ARABIC LAM;;;; -FEDE;ARABIC LETTER LAM FINAL FORM;Lo;0;AL; 0644;;;;N;GLYPH FOR FINAL ARABIC LAM;;;; -FEDF;ARABIC LETTER LAM INITIAL FORM;Lo;0;AL; 0644;;;;N;GLYPH FOR INITIAL ARABIC LAM;;;; -FEE0;ARABIC LETTER LAM MEDIAL FORM;Lo;0;AL; 0644;;;;N;GLYPH FOR MEDIAL ARABIC LAM;;;; -FEE1;ARABIC LETTER MEEM ISOLATED FORM;Lo;0;AL; 0645;;;;N;GLYPH FOR ISOLATE ARABIC MEEM;;;; -FEE2;ARABIC LETTER MEEM FINAL FORM;Lo;0;AL; 0645;;;;N;GLYPH FOR FINAL ARABIC MEEM;;;; -FEE3;ARABIC LETTER MEEM INITIAL FORM;Lo;0;AL; 0645;;;;N;GLYPH FOR INITIAL ARABIC MEEM;;;; -FEE4;ARABIC LETTER MEEM MEDIAL FORM;Lo;0;AL; 0645;;;;N;GLYPH FOR MEDIAL ARABIC MEEM;;;; -FEE5;ARABIC LETTER NOON ISOLATED FORM;Lo;0;AL; 0646;;;;N;GLYPH FOR ISOLATE ARABIC NOON;;;; -FEE6;ARABIC LETTER NOON FINAL FORM;Lo;0;AL; 0646;;;;N;GLYPH FOR FINAL ARABIC NOON;;;; -FEE7;ARABIC LETTER NOON INITIAL FORM;Lo;0;AL; 0646;;;;N;GLYPH FOR INITIAL ARABIC NOON;;;; -FEE8;ARABIC LETTER NOON MEDIAL FORM;Lo;0;AL; 0646;;;;N;GLYPH FOR MEDIAL ARABIC NOON;;;; -FEE9;ARABIC LETTER HEH ISOLATED FORM;Lo;0;AL; 0647;;;;N;GLYPH FOR ISOLATE ARABIC HA;;;; -FEEA;ARABIC LETTER HEH FINAL FORM;Lo;0;AL; 0647;;;;N;GLYPH FOR FINAL ARABIC HA;;;; -FEEB;ARABIC LETTER HEH INITIAL FORM;Lo;0;AL; 0647;;;;N;GLYPH FOR INITIAL ARABIC HA;;;; -FEEC;ARABIC LETTER HEH MEDIAL FORM;Lo;0;AL; 0647;;;;N;GLYPH FOR MEDIAL ARABIC HA;;;; -FEED;ARABIC LETTER WAW ISOLATED FORM;Lo;0;AL; 0648;;;;N;GLYPH FOR ISOLATE ARABIC WAW;;;; -FEEE;ARABIC LETTER WAW FINAL FORM;Lo;0;AL; 0648;;;;N;GLYPH FOR FINAL ARABIC WAW;;;; -FEEF;ARABIC LETTER ALEF MAKSURA ISOLATED FORM;Lo;0;AL; 0649;;;;N;GLYPH FOR ISOLATE ARABIC ALEF MAQSURAH;;;; -FEF0;ARABIC LETTER ALEF MAKSURA FINAL FORM;Lo;0;AL; 0649;;;;N;GLYPH FOR FINAL ARABIC ALEF MAQSURAH;;;; -FEF1;ARABIC LETTER YEH ISOLATED FORM;Lo;0;AL; 064A;;;;N;GLYPH FOR ISOLATE ARABIC YA;;;; -FEF2;ARABIC LETTER YEH FINAL FORM;Lo;0;AL; 064A;;;;N;GLYPH FOR FINAL ARABIC YA;;;; -FEF3;ARABIC LETTER YEH INITIAL FORM;Lo;0;AL; 064A;;;;N;GLYPH FOR INITIAL ARABIC YA;;;; -FEF4;ARABIC LETTER YEH MEDIAL FORM;Lo;0;AL; 064A;;;;N;GLYPH FOR MEDIAL ARABIC YA;;;; -FEF5;ARABIC LIGATURE LAM WITH ALEF WITH MADDA ABOVE ISOLATED FORM;Lo;0;AL; 0644 0622;;;;N;GLYPH FOR ISOLATE ARABIC MADDAH ON LIGATURE LAM ALEF;;;; -FEF6;ARABIC LIGATURE LAM WITH ALEF WITH MADDA ABOVE FINAL FORM;Lo;0;AL; 0644 0622;;;;N;GLYPH FOR FINAL ARABIC MADDAH ON LIGATURE LAM ALEF;;;; -FEF7;ARABIC LIGATURE LAM WITH ALEF WITH HAMZA ABOVE ISOLATED FORM;Lo;0;AL; 0644 0623;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH ON LIGATURE LAM ALEF;;;; -FEF8;ARABIC LIGATURE LAM WITH ALEF WITH HAMZA ABOVE FINAL FORM;Lo;0;AL; 0644 0623;;;;N;GLYPH FOR FINAL ARABIC HAMZAH ON LIGATURE LAM ALEF;;;; -FEF9;ARABIC LIGATURE LAM WITH ALEF WITH HAMZA BELOW ISOLATED FORM;Lo;0;AL; 0644 0625;;;;N;GLYPH FOR ISOLATE ARABIC HAMZAH UNDER LIGATURE LAM ALEF;;;; -FEFA;ARABIC LIGATURE LAM WITH ALEF WITH HAMZA BELOW FINAL FORM;Lo;0;AL; 0644 0625;;;;N;GLYPH FOR FINAL ARABIC HAMZAH UNDER LIGATURE LAM ALEF;;;; -FEFB;ARABIC LIGATURE LAM WITH ALEF ISOLATED FORM;Lo;0;AL; 0644 0627;;;;N;GLYPH FOR ISOLATE ARABIC LIGATURE LAM ALEF;;;; -FEFC;ARABIC LIGATURE LAM WITH ALEF FINAL FORM;Lo;0;AL; 0644 0627;;;;N;GLYPH FOR FINAL ARABIC LIGATURE LAM ALEF;;;; -FEFF;ZERO WIDTH NO-BREAK SPACE;Cf;0;BN;;;;;N;BYTE ORDER MARK;;;; -FF01;FULLWIDTH EXCLAMATION MARK;Po;0;ON; 0021;;;;N;;;;; -FF02;FULLWIDTH QUOTATION MARK;Po;0;ON; 0022;;;;N;;;;; -FF03;FULLWIDTH NUMBER SIGN;Po;0;ET; 0023;;;;N;;;;; -FF04;FULLWIDTH DOLLAR SIGN;Sc;0;ET; 0024;;;;N;;;;; -FF05;FULLWIDTH PERCENT SIGN;Po;0;ET; 0025;;;;N;;;;; -FF06;FULLWIDTH AMPERSAND;Po;0;ON; 0026;;;;N;;;;; -FF07;FULLWIDTH APOSTROPHE;Po;0;ON; 0027;;;;N;;;;; -FF08;FULLWIDTH LEFT PARENTHESIS;Ps;0;ON; 0028;;;;Y;FULLWIDTH OPENING PARENTHESIS;;;; -FF09;FULLWIDTH RIGHT PARENTHESIS;Pe;0;ON; 0029;;;;Y;FULLWIDTH CLOSING PARENTHESIS;;;; -FF0A;FULLWIDTH ASTERISK;Po;0;ON; 002A;;;;N;;;;; -FF0B;FULLWIDTH PLUS SIGN;Sm;0;ES; 002B;;;;N;;;;; -FF0C;FULLWIDTH COMMA;Po;0;CS; 002C;;;;N;;;;; -FF0D;FULLWIDTH HYPHEN-MINUS;Pd;0;ES; 002D;;;;N;;;;; -FF0E;FULLWIDTH FULL STOP;Po;0;CS; 002E;;;;N;FULLWIDTH PERIOD;;;; -FF0F;FULLWIDTH SOLIDUS;Po;0;CS; 002F;;;;N;FULLWIDTH SLASH;;;; -FF10;FULLWIDTH DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -FF11;FULLWIDTH DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -FF12;FULLWIDTH DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -FF13;FULLWIDTH DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -FF14;FULLWIDTH DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -FF15;FULLWIDTH DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -FF16;FULLWIDTH DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -FF17;FULLWIDTH DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -FF18;FULLWIDTH DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -FF19;FULLWIDTH DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -FF1A;FULLWIDTH COLON;Po;0;CS; 003A;;;;N;;;;; -FF1B;FULLWIDTH SEMICOLON;Po;0;ON; 003B;;;;N;;;;; -FF1C;FULLWIDTH LESS-THAN SIGN;Sm;0;ON; 003C;;;;Y;;;;; -FF1D;FULLWIDTH EQUALS SIGN;Sm;0;ON; 003D;;;;N;;;;; -FF1E;FULLWIDTH GREATER-THAN SIGN;Sm;0;ON; 003E;;;;Y;;;;; -FF1F;FULLWIDTH QUESTION MARK;Po;0;ON; 003F;;;;N;;;;; -FF20;FULLWIDTH COMMERCIAL AT;Po;0;ON; 0040;;;;N;;;;; -FF21;FULLWIDTH LATIN CAPITAL LETTER A;Lu;0;L; 0041;;;;N;;;;FF41; -FF22;FULLWIDTH LATIN CAPITAL LETTER B;Lu;0;L; 0042;;;;N;;;;FF42; -FF23;FULLWIDTH LATIN CAPITAL LETTER C;Lu;0;L; 0043;;;;N;;;;FF43; -FF24;FULLWIDTH LATIN CAPITAL LETTER D;Lu;0;L; 0044;;;;N;;;;FF44; -FF25;FULLWIDTH LATIN CAPITAL LETTER E;Lu;0;L; 0045;;;;N;;;;FF45; -FF26;FULLWIDTH LATIN CAPITAL LETTER F;Lu;0;L; 0046;;;;N;;;;FF46; -FF27;FULLWIDTH LATIN CAPITAL LETTER G;Lu;0;L; 0047;;;;N;;;;FF47; -FF28;FULLWIDTH LATIN CAPITAL LETTER H;Lu;0;L; 0048;;;;N;;;;FF48; -FF29;FULLWIDTH LATIN CAPITAL LETTER I;Lu;0;L; 0049;;;;N;;;;FF49; -FF2A;FULLWIDTH LATIN CAPITAL LETTER J;Lu;0;L; 004A;;;;N;;;;FF4A; -FF2B;FULLWIDTH LATIN CAPITAL LETTER K;Lu;0;L; 004B;;;;N;;;;FF4B; -FF2C;FULLWIDTH LATIN CAPITAL LETTER L;Lu;0;L; 004C;;;;N;;;;FF4C; -FF2D;FULLWIDTH LATIN CAPITAL LETTER M;Lu;0;L; 004D;;;;N;;;;FF4D; -FF2E;FULLWIDTH LATIN CAPITAL LETTER N;Lu;0;L; 004E;;;;N;;;;FF4E; -FF2F;FULLWIDTH LATIN CAPITAL LETTER O;Lu;0;L; 004F;;;;N;;;;FF4F; -FF30;FULLWIDTH LATIN CAPITAL LETTER P;Lu;0;L; 0050;;;;N;;;;FF50; -FF31;FULLWIDTH LATIN CAPITAL LETTER Q;Lu;0;L; 0051;;;;N;;;;FF51; -FF32;FULLWIDTH LATIN CAPITAL LETTER R;Lu;0;L; 0052;;;;N;;;;FF52; -FF33;FULLWIDTH LATIN CAPITAL LETTER S;Lu;0;L; 0053;;;;N;;;;FF53; -FF34;FULLWIDTH LATIN CAPITAL LETTER T;Lu;0;L; 0054;;;;N;;;;FF54; -FF35;FULLWIDTH LATIN CAPITAL LETTER U;Lu;0;L; 0055;;;;N;;;;FF55; -FF36;FULLWIDTH LATIN CAPITAL LETTER V;Lu;0;L; 0056;;;;N;;;;FF56; -FF37;FULLWIDTH LATIN CAPITAL LETTER W;Lu;0;L; 0057;;;;N;;;;FF57; -FF38;FULLWIDTH LATIN CAPITAL LETTER X;Lu;0;L; 0058;;;;N;;;;FF58; -FF39;FULLWIDTH LATIN CAPITAL LETTER Y;Lu;0;L; 0059;;;;N;;;;FF59; -FF3A;FULLWIDTH LATIN CAPITAL LETTER Z;Lu;0;L; 005A;;;;N;;;;FF5A; -FF3B;FULLWIDTH LEFT SQUARE BRACKET;Ps;0;ON; 005B;;;;Y;FULLWIDTH OPENING SQUARE BRACKET;;;; -FF3C;FULLWIDTH REVERSE SOLIDUS;Po;0;ON; 005C;;;;N;FULLWIDTH BACKSLASH;;;; -FF3D;FULLWIDTH RIGHT SQUARE BRACKET;Pe;0;ON; 005D;;;;Y;FULLWIDTH CLOSING SQUARE BRACKET;;;; -FF3E;FULLWIDTH CIRCUMFLEX ACCENT;Sk;0;ON; 005E;;;;N;FULLWIDTH SPACING CIRCUMFLEX;;;; -FF3F;FULLWIDTH LOW LINE;Pc;0;ON; 005F;;;;N;FULLWIDTH SPACING UNDERSCORE;;;; -FF40;FULLWIDTH GRAVE ACCENT;Sk;0;ON; 0060;;;;N;FULLWIDTH SPACING GRAVE;;;; -FF41;FULLWIDTH LATIN SMALL LETTER A;Ll;0;L; 0061;;;;N;;;FF21;;FF21 -FF42;FULLWIDTH LATIN SMALL LETTER B;Ll;0;L; 0062;;;;N;;;FF22;;FF22 -FF43;FULLWIDTH LATIN SMALL LETTER C;Ll;0;L; 0063;;;;N;;;FF23;;FF23 -FF44;FULLWIDTH LATIN SMALL LETTER D;Ll;0;L; 0064;;;;N;;;FF24;;FF24 -FF45;FULLWIDTH LATIN SMALL LETTER E;Ll;0;L; 0065;;;;N;;;FF25;;FF25 -FF46;FULLWIDTH LATIN SMALL LETTER F;Ll;0;L; 0066;;;;N;;;FF26;;FF26 -FF47;FULLWIDTH LATIN SMALL LETTER G;Ll;0;L; 0067;;;;N;;;FF27;;FF27 -FF48;FULLWIDTH LATIN SMALL LETTER H;Ll;0;L; 0068;;;;N;;;FF28;;FF28 -FF49;FULLWIDTH LATIN SMALL LETTER I;Ll;0;L; 0069;;;;N;;;FF29;;FF29 -FF4A;FULLWIDTH LATIN SMALL LETTER J;Ll;0;L; 006A;;;;N;;;FF2A;;FF2A -FF4B;FULLWIDTH LATIN SMALL LETTER K;Ll;0;L; 006B;;;;N;;;FF2B;;FF2B -FF4C;FULLWIDTH LATIN SMALL LETTER L;Ll;0;L; 006C;;;;N;;;FF2C;;FF2C -FF4D;FULLWIDTH LATIN SMALL LETTER M;Ll;0;L; 006D;;;;N;;;FF2D;;FF2D -FF4E;FULLWIDTH LATIN SMALL LETTER N;Ll;0;L; 006E;;;;N;;;FF2E;;FF2E -FF4F;FULLWIDTH LATIN SMALL LETTER O;Ll;0;L; 006F;;;;N;;;FF2F;;FF2F -FF50;FULLWIDTH LATIN SMALL LETTER P;Ll;0;L; 0070;;;;N;;;FF30;;FF30 -FF51;FULLWIDTH LATIN SMALL LETTER Q;Ll;0;L; 0071;;;;N;;;FF31;;FF31 -FF52;FULLWIDTH LATIN SMALL LETTER R;Ll;0;L; 0072;;;;N;;;FF32;;FF32 -FF53;FULLWIDTH LATIN SMALL LETTER S;Ll;0;L; 0073;;;;N;;;FF33;;FF33 -FF54;FULLWIDTH LATIN SMALL LETTER T;Ll;0;L; 0074;;;;N;;;FF34;;FF34 -FF55;FULLWIDTH LATIN SMALL LETTER U;Ll;0;L; 0075;;;;N;;;FF35;;FF35 -FF56;FULLWIDTH LATIN SMALL LETTER V;Ll;0;L; 0076;;;;N;;;FF36;;FF36 -FF57;FULLWIDTH LATIN SMALL LETTER W;Ll;0;L; 0077;;;;N;;;FF37;;FF37 -FF58;FULLWIDTH LATIN SMALL LETTER X;Ll;0;L; 0078;;;;N;;;FF38;;FF38 -FF59;FULLWIDTH LATIN SMALL LETTER Y;Ll;0;L; 0079;;;;N;;;FF39;;FF39 -FF5A;FULLWIDTH LATIN SMALL LETTER Z;Ll;0;L; 007A;;;;N;;;FF3A;;FF3A -FF5B;FULLWIDTH LEFT CURLY BRACKET;Ps;0;ON; 007B;;;;Y;FULLWIDTH OPENING CURLY BRACKET;;;; -FF5C;FULLWIDTH VERTICAL LINE;Sm;0;ON; 007C;;;;N;FULLWIDTH VERTICAL BAR;;;; -FF5D;FULLWIDTH RIGHT CURLY BRACKET;Pe;0;ON; 007D;;;;Y;FULLWIDTH CLOSING CURLY BRACKET;;;; -FF5E;FULLWIDTH TILDE;Sm;0;ON; 007E;;;;N;FULLWIDTH SPACING TILDE;;;; -FF5F;FULLWIDTH LEFT WHITE PARENTHESIS;Ps;0;ON; 2985;;;;Y;;*;;; -FF60;FULLWIDTH RIGHT WHITE PARENTHESIS;Pe;0;ON; 2986;;;;Y;;*;;; -FF61;HALFWIDTH IDEOGRAPHIC FULL STOP;Po;0;ON; 3002;;;;N;HALFWIDTH IDEOGRAPHIC PERIOD;;;; -FF62;HALFWIDTH LEFT CORNER BRACKET;Ps;0;ON; 300C;;;;Y;HALFWIDTH OPENING CORNER BRACKET;;;; -FF63;HALFWIDTH RIGHT CORNER BRACKET;Pe;0;ON; 300D;;;;Y;HALFWIDTH CLOSING CORNER BRACKET;;;; -FF64;HALFWIDTH IDEOGRAPHIC COMMA;Po;0;ON; 3001;;;;N;;;;; -FF65;HALFWIDTH KATAKANA MIDDLE DOT;Po;0;ON; 30FB;;;;N;;;;; -FF66;HALFWIDTH KATAKANA LETTER WO;Lo;0;L; 30F2;;;;N;;;;; -FF67;HALFWIDTH KATAKANA LETTER SMALL A;Lo;0;L; 30A1;;;;N;;;;; -FF68;HALFWIDTH KATAKANA LETTER SMALL I;Lo;0;L; 30A3;;;;N;;;;; -FF69;HALFWIDTH KATAKANA LETTER SMALL U;Lo;0;L; 30A5;;;;N;;;;; -FF6A;HALFWIDTH KATAKANA LETTER SMALL E;Lo;0;L; 30A7;;;;N;;;;; -FF6B;HALFWIDTH KATAKANA LETTER SMALL O;Lo;0;L; 30A9;;;;N;;;;; -FF6C;HALFWIDTH KATAKANA LETTER SMALL YA;Lo;0;L; 30E3;;;;N;;;;; -FF6D;HALFWIDTH KATAKANA LETTER SMALL YU;Lo;0;L; 30E5;;;;N;;;;; -FF6E;HALFWIDTH KATAKANA LETTER SMALL YO;Lo;0;L; 30E7;;;;N;;;;; -FF6F;HALFWIDTH KATAKANA LETTER SMALL TU;Lo;0;L; 30C3;;;;N;;;;; -FF70;HALFWIDTH KATAKANA-HIRAGANA PROLONGED SOUND MARK;Lm;0;L; 30FC;;;;N;;;;; -FF71;HALFWIDTH KATAKANA LETTER A;Lo;0;L; 30A2;;;;N;;;;; -FF72;HALFWIDTH KATAKANA LETTER I;Lo;0;L; 30A4;;;;N;;;;; -FF73;HALFWIDTH KATAKANA LETTER U;Lo;0;L; 30A6;;;;N;;;;; -FF74;HALFWIDTH KATAKANA LETTER E;Lo;0;L; 30A8;;;;N;;;;; -FF75;HALFWIDTH KATAKANA LETTER O;Lo;0;L; 30AA;;;;N;;;;; -FF76;HALFWIDTH KATAKANA LETTER KA;Lo;0;L; 30AB;;;;N;;;;; -FF77;HALFWIDTH KATAKANA LETTER KI;Lo;0;L; 30AD;;;;N;;;;; -FF78;HALFWIDTH KATAKANA LETTER KU;Lo;0;L; 30AF;;;;N;;;;; -FF79;HALFWIDTH KATAKANA LETTER KE;Lo;0;L; 30B1;;;;N;;;;; -FF7A;HALFWIDTH KATAKANA LETTER KO;Lo;0;L; 30B3;;;;N;;;;; -FF7B;HALFWIDTH KATAKANA LETTER SA;Lo;0;L; 30B5;;;;N;;;;; -FF7C;HALFWIDTH KATAKANA LETTER SI;Lo;0;L; 30B7;;;;N;;;;; -FF7D;HALFWIDTH KATAKANA LETTER SU;Lo;0;L; 30B9;;;;N;;;;; -FF7E;HALFWIDTH KATAKANA LETTER SE;Lo;0;L; 30BB;;;;N;;;;; -FF7F;HALFWIDTH KATAKANA LETTER SO;Lo;0;L; 30BD;;;;N;;;;; -FF80;HALFWIDTH KATAKANA LETTER TA;Lo;0;L; 30BF;;;;N;;;;; -FF81;HALFWIDTH KATAKANA LETTER TI;Lo;0;L; 30C1;;;;N;;;;; -FF82;HALFWIDTH KATAKANA LETTER TU;Lo;0;L; 30C4;;;;N;;;;; -FF83;HALFWIDTH KATAKANA LETTER TE;Lo;0;L; 30C6;;;;N;;;;; -FF84;HALFWIDTH KATAKANA LETTER TO;Lo;0;L; 30C8;;;;N;;;;; -FF85;HALFWIDTH KATAKANA LETTER NA;Lo;0;L; 30CA;;;;N;;;;; -FF86;HALFWIDTH KATAKANA LETTER NI;Lo;0;L; 30CB;;;;N;;;;; -FF87;HALFWIDTH KATAKANA LETTER NU;Lo;0;L; 30CC;;;;N;;;;; -FF88;HALFWIDTH KATAKANA LETTER NE;Lo;0;L; 30CD;;;;N;;;;; -FF89;HALFWIDTH KATAKANA LETTER NO;Lo;0;L; 30CE;;;;N;;;;; -FF8A;HALFWIDTH KATAKANA LETTER HA;Lo;0;L; 30CF;;;;N;;;;; -FF8B;HALFWIDTH KATAKANA LETTER HI;Lo;0;L; 30D2;;;;N;;;;; -FF8C;HALFWIDTH KATAKANA LETTER HU;Lo;0;L; 30D5;;;;N;;;;; -FF8D;HALFWIDTH KATAKANA LETTER HE;Lo;0;L; 30D8;;;;N;;;;; -FF8E;HALFWIDTH KATAKANA LETTER HO;Lo;0;L; 30DB;;;;N;;;;; -FF8F;HALFWIDTH KATAKANA LETTER MA;Lo;0;L; 30DE;;;;N;;;;; -FF90;HALFWIDTH KATAKANA LETTER MI;Lo;0;L; 30DF;;;;N;;;;; -FF91;HALFWIDTH KATAKANA LETTER MU;Lo;0;L; 30E0;;;;N;;;;; -FF92;HALFWIDTH KATAKANA LETTER ME;Lo;0;L; 30E1;;;;N;;;;; -FF93;HALFWIDTH KATAKANA LETTER MO;Lo;0;L; 30E2;;;;N;;;;; -FF94;HALFWIDTH KATAKANA LETTER YA;Lo;0;L; 30E4;;;;N;;;;; -FF95;HALFWIDTH KATAKANA LETTER YU;Lo;0;L; 30E6;;;;N;;;;; -FF96;HALFWIDTH KATAKANA LETTER YO;Lo;0;L; 30E8;;;;N;;;;; -FF97;HALFWIDTH KATAKANA LETTER RA;Lo;0;L; 30E9;;;;N;;;;; -FF98;HALFWIDTH KATAKANA LETTER RI;Lo;0;L; 30EA;;;;N;;;;; -FF99;HALFWIDTH KATAKANA LETTER RU;Lo;0;L; 30EB;;;;N;;;;; -FF9A;HALFWIDTH KATAKANA LETTER RE;Lo;0;L; 30EC;;;;N;;;;; -FF9B;HALFWIDTH KATAKANA LETTER RO;Lo;0;L; 30ED;;;;N;;;;; -FF9C;HALFWIDTH KATAKANA LETTER WA;Lo;0;L; 30EF;;;;N;;;;; -FF9D;HALFWIDTH KATAKANA LETTER N;Lo;0;L; 30F3;;;;N;;;;; -FF9E;HALFWIDTH KATAKANA VOICED SOUND MARK;Lm;0;L; 3099;;;;N;;halfwidth katakana-hiragana voiced sound mark;;; -FF9F;HALFWIDTH KATAKANA SEMI-VOICED SOUND MARK;Lm;0;L; 309A;;;;N;;halfwidth katakana-hiragana semi-voiced sound mark;;; -FFA0;HALFWIDTH HANGUL FILLER;Lo;0;L; 3164;;;;N;HALFWIDTH HANGUL CAE OM;;;; -FFA1;HALFWIDTH HANGUL LETTER KIYEOK;Lo;0;L; 3131;;;;N;HALFWIDTH HANGUL LETTER GIYEOG;;;; -FFA2;HALFWIDTH HANGUL LETTER SSANGKIYEOK;Lo;0;L; 3132;;;;N;HALFWIDTH HANGUL LETTER SSANG GIYEOG;;;; -FFA3;HALFWIDTH HANGUL LETTER KIYEOK-SIOS;Lo;0;L; 3133;;;;N;HALFWIDTH HANGUL LETTER GIYEOG SIOS;;;; -FFA4;HALFWIDTH HANGUL LETTER NIEUN;Lo;0;L; 3134;;;;N;;;;; -FFA5;HALFWIDTH HANGUL LETTER NIEUN-CIEUC;Lo;0;L; 3135;;;;N;HALFWIDTH HANGUL LETTER NIEUN JIEUJ;;;; -FFA6;HALFWIDTH HANGUL LETTER NIEUN-HIEUH;Lo;0;L; 3136;;;;N;HALFWIDTH HANGUL LETTER NIEUN HIEUH;;;; -FFA7;HALFWIDTH HANGUL LETTER TIKEUT;Lo;0;L; 3137;;;;N;HALFWIDTH HANGUL LETTER DIGEUD;;;; -FFA8;HALFWIDTH HANGUL LETTER SSANGTIKEUT;Lo;0;L; 3138;;;;N;HALFWIDTH HANGUL LETTER SSANG DIGEUD;;;; -FFA9;HALFWIDTH HANGUL LETTER RIEUL;Lo;0;L; 3139;;;;N;HALFWIDTH HANGUL LETTER LIEUL;;;; -FFAA;HALFWIDTH HANGUL LETTER RIEUL-KIYEOK;Lo;0;L; 313A;;;;N;HALFWIDTH HANGUL LETTER LIEUL GIYEOG;;;; -FFAB;HALFWIDTH HANGUL LETTER RIEUL-MIEUM;Lo;0;L; 313B;;;;N;HALFWIDTH HANGUL LETTER LIEUL MIEUM;;;; -FFAC;HALFWIDTH HANGUL LETTER RIEUL-PIEUP;Lo;0;L; 313C;;;;N;HALFWIDTH HANGUL LETTER LIEUL BIEUB;;;; -FFAD;HALFWIDTH HANGUL LETTER RIEUL-SIOS;Lo;0;L; 313D;;;;N;HALFWIDTH HANGUL LETTER LIEUL SIOS;;;; -FFAE;HALFWIDTH HANGUL LETTER RIEUL-THIEUTH;Lo;0;L; 313E;;;;N;HALFWIDTH HANGUL LETTER LIEUL TIEUT;;;; -FFAF;HALFWIDTH HANGUL LETTER RIEUL-PHIEUPH;Lo;0;L; 313F;;;;N;HALFWIDTH HANGUL LETTER LIEUL PIEUP;;;; -FFB0;HALFWIDTH HANGUL LETTER RIEUL-HIEUH;Lo;0;L; 3140;;;;N;HALFWIDTH HANGUL LETTER LIEUL HIEUH;;;; -FFB1;HALFWIDTH HANGUL LETTER MIEUM;Lo;0;L; 3141;;;;N;;;;; -FFB2;HALFWIDTH HANGUL LETTER PIEUP;Lo;0;L; 3142;;;;N;HALFWIDTH HANGUL LETTER BIEUB;;;; -FFB3;HALFWIDTH HANGUL LETTER SSANGPIEUP;Lo;0;L; 3143;;;;N;HALFWIDTH HANGUL LETTER SSANG BIEUB;;;; -FFB4;HALFWIDTH HANGUL LETTER PIEUP-SIOS;Lo;0;L; 3144;;;;N;HALFWIDTH HANGUL LETTER BIEUB SIOS;;;; -FFB5;HALFWIDTH HANGUL LETTER SIOS;Lo;0;L; 3145;;;;N;;;;; -FFB6;HALFWIDTH HANGUL LETTER SSANGSIOS;Lo;0;L; 3146;;;;N;HALFWIDTH HANGUL LETTER SSANG SIOS;;;; -FFB7;HALFWIDTH HANGUL LETTER IEUNG;Lo;0;L; 3147;;;;N;;;;; -FFB8;HALFWIDTH HANGUL LETTER CIEUC;Lo;0;L; 3148;;;;N;HALFWIDTH HANGUL LETTER JIEUJ;;;; -FFB9;HALFWIDTH HANGUL LETTER SSANGCIEUC;Lo;0;L; 3149;;;;N;HALFWIDTH HANGUL LETTER SSANG JIEUJ;;;; -FFBA;HALFWIDTH HANGUL LETTER CHIEUCH;Lo;0;L; 314A;;;;N;HALFWIDTH HANGUL LETTER CIEUC;;;; -FFBB;HALFWIDTH HANGUL LETTER KHIEUKH;Lo;0;L; 314B;;;;N;HALFWIDTH HANGUL LETTER KIYEOK;;;; -FFBC;HALFWIDTH HANGUL LETTER THIEUTH;Lo;0;L; 314C;;;;N;HALFWIDTH HANGUL LETTER TIEUT;;;; -FFBD;HALFWIDTH HANGUL LETTER PHIEUPH;Lo;0;L; 314D;;;;N;HALFWIDTH HANGUL LETTER PIEUP;;;; -FFBE;HALFWIDTH HANGUL LETTER HIEUH;Lo;0;L; 314E;;;;N;;;;; -FFC2;HALFWIDTH HANGUL LETTER A;Lo;0;L; 314F;;;;N;;;;; -FFC3;HALFWIDTH HANGUL LETTER AE;Lo;0;L; 3150;;;;N;;;;; -FFC4;HALFWIDTH HANGUL LETTER YA;Lo;0;L; 3151;;;;N;;;;; -FFC5;HALFWIDTH HANGUL LETTER YAE;Lo;0;L; 3152;;;;N;;;;; -FFC6;HALFWIDTH HANGUL LETTER EO;Lo;0;L; 3153;;;;N;;;;; -FFC7;HALFWIDTH HANGUL LETTER E;Lo;0;L; 3154;;;;N;;;;; -FFCA;HALFWIDTH HANGUL LETTER YEO;Lo;0;L; 3155;;;;N;;;;; -FFCB;HALFWIDTH HANGUL LETTER YE;Lo;0;L; 3156;;;;N;;;;; -FFCC;HALFWIDTH HANGUL LETTER O;Lo;0;L; 3157;;;;N;;;;; -FFCD;HALFWIDTH HANGUL LETTER WA;Lo;0;L; 3158;;;;N;;;;; -FFCE;HALFWIDTH HANGUL LETTER WAE;Lo;0;L; 3159;;;;N;;;;; -FFCF;HALFWIDTH HANGUL LETTER OE;Lo;0;L; 315A;;;;N;;;;; -FFD2;HALFWIDTH HANGUL LETTER YO;Lo;0;L; 315B;;;;N;;;;; -FFD3;HALFWIDTH HANGUL LETTER U;Lo;0;L; 315C;;;;N;;;;; -FFD4;HALFWIDTH HANGUL LETTER WEO;Lo;0;L; 315D;;;;N;;;;; -FFD5;HALFWIDTH HANGUL LETTER WE;Lo;0;L; 315E;;;;N;;;;; -FFD6;HALFWIDTH HANGUL LETTER WI;Lo;0;L; 315F;;;;N;;;;; -FFD7;HALFWIDTH HANGUL LETTER YU;Lo;0;L; 3160;;;;N;;;;; -FFDA;HALFWIDTH HANGUL LETTER EU;Lo;0;L; 3161;;;;N;;;;; -FFDB;HALFWIDTH HANGUL LETTER YI;Lo;0;L; 3162;;;;N;;;;; -FFDC;HALFWIDTH HANGUL LETTER I;Lo;0;L; 3163;;;;N;;;;; -FFE0;FULLWIDTH CENT SIGN;Sc;0;ET; 00A2;;;;N;;;;; -FFE1;FULLWIDTH POUND SIGN;Sc;0;ET; 00A3;;;;N;;;;; -FFE2;FULLWIDTH NOT SIGN;Sm;0;ON; 00AC;;;;N;;;;; -FFE3;FULLWIDTH MACRON;Sk;0;ON; 00AF;;;;N;FULLWIDTH SPACING MACRON;*;;; -FFE4;FULLWIDTH BROKEN BAR;So;0;ON; 00A6;;;;N;FULLWIDTH BROKEN VERTICAL BAR;;;; -FFE5;FULLWIDTH YEN SIGN;Sc;0;ET; 00A5;;;;N;;;;; -FFE6;FULLWIDTH WON SIGN;Sc;0;ET; 20A9;;;;N;;;;; -FFE8;HALFWIDTH FORMS LIGHT VERTICAL;So;0;ON; 2502;;;;N;;;;; -FFE9;HALFWIDTH LEFTWARDS ARROW;Sm;0;ON; 2190;;;;N;;;;; -FFEA;HALFWIDTH UPWARDS ARROW;Sm;0;ON; 2191;;;;N;;;;; -FFEB;HALFWIDTH RIGHTWARDS ARROW;Sm;0;ON; 2192;;;;N;;;;; -FFEC;HALFWIDTH DOWNWARDS ARROW;Sm;0;ON; 2193;;;;N;;;;; -FFED;HALFWIDTH BLACK SQUARE;So;0;ON; 25A0;;;;N;;;;; -FFEE;HALFWIDTH WHITE CIRCLE;So;0;ON; 25CB;;;;N;;;;; -FFF9;INTERLINEAR ANNOTATION ANCHOR;Cf;0;ON;;;;;N;;;;; -FFFA;INTERLINEAR ANNOTATION SEPARATOR;Cf;0;ON;;;;;N;;;;; -FFFB;INTERLINEAR ANNOTATION TERMINATOR;Cf;0;ON;;;;;N;;;;; -FFFC;OBJECT REPLACEMENT CHARACTER;So;0;ON;;;;;N;;;;; -FFFD;REPLACEMENT CHARACTER;So;0;ON;;;;;N;;;;; -10000;LINEAR B SYLLABLE B008 A;Lo;0;L;;;;;N;;;;; -10001;LINEAR B SYLLABLE B038 E;Lo;0;L;;;;;N;;;;; -10002;LINEAR B SYLLABLE B028 I;Lo;0;L;;;;;N;;;;; -10003;LINEAR B SYLLABLE B061 O;Lo;0;L;;;;;N;;;;; -10004;LINEAR B SYLLABLE B010 U;Lo;0;L;;;;;N;;;;; -10005;LINEAR B SYLLABLE B001 DA;Lo;0;L;;;;;N;;;;; -10006;LINEAR B SYLLABLE B045 DE;Lo;0;L;;;;;N;;;;; -10007;LINEAR B SYLLABLE B007 DI;Lo;0;L;;;;;N;;;;; -10008;LINEAR B SYLLABLE B014 DO;Lo;0;L;;;;;N;;;;; -10009;LINEAR B SYLLABLE B051 DU;Lo;0;L;;;;;N;;;;; -1000A;LINEAR B SYLLABLE B057 JA;Lo;0;L;;;;;N;;;;; -1000B;LINEAR B SYLLABLE B046 JE;Lo;0;L;;;;;N;;;;; -1000D;LINEAR B SYLLABLE B036 JO;Lo;0;L;;;;;N;;;;; -1000E;LINEAR B SYLLABLE B065 JU;Lo;0;L;;;;;N;;;;; -1000F;LINEAR B SYLLABLE B077 KA;Lo;0;L;;;;;N;;;;; -10010;LINEAR B SYLLABLE B044 KE;Lo;0;L;;;;;N;;;;; -10011;LINEAR B SYLLABLE B067 KI;Lo;0;L;;;;;N;;;;; -10012;LINEAR B SYLLABLE B070 KO;Lo;0;L;;;;;N;;;;; -10013;LINEAR B SYLLABLE B081 KU;Lo;0;L;;;;;N;;;;; -10014;LINEAR B SYLLABLE B080 MA;Lo;0;L;;;;;N;;;;; -10015;LINEAR B SYLLABLE B013 ME;Lo;0;L;;;;;N;;;;; -10016;LINEAR B SYLLABLE B073 MI;Lo;0;L;;;;;N;;;;; -10017;LINEAR B SYLLABLE B015 MO;Lo;0;L;;;;;N;;;;; -10018;LINEAR B SYLLABLE B023 MU;Lo;0;L;;;;;N;;;;; -10019;LINEAR B SYLLABLE B006 NA;Lo;0;L;;;;;N;;;;; -1001A;LINEAR B SYLLABLE B024 NE;Lo;0;L;;;;;N;;;;; -1001B;LINEAR B SYLLABLE B030 NI;Lo;0;L;;;;;N;;;;; -1001C;LINEAR B SYLLABLE B052 NO;Lo;0;L;;;;;N;;;;; -1001D;LINEAR B SYLLABLE B055 NU;Lo;0;L;;;;;N;;;;; -1001E;LINEAR B SYLLABLE B003 PA;Lo;0;L;;;;;N;;;;; -1001F;LINEAR B SYLLABLE B072 PE;Lo;0;L;;;;;N;;;;; -10020;LINEAR B SYLLABLE B039 PI;Lo;0;L;;;;;N;;;;; -10021;LINEAR B SYLLABLE B011 PO;Lo;0;L;;;;;N;;;;; -10022;LINEAR B SYLLABLE B050 PU;Lo;0;L;;;;;N;;;;; -10023;LINEAR B SYLLABLE B016 QA;Lo;0;L;;;;;N;;;;; -10024;LINEAR B SYLLABLE B078 QE;Lo;0;L;;;;;N;;;;; -10025;LINEAR B SYLLABLE B021 QI;Lo;0;L;;;;;N;;;;; -10026;LINEAR B SYLLABLE B032 QO;Lo;0;L;;;;;N;;;;; -10028;LINEAR B SYLLABLE B060 RA;Lo;0;L;;;;;N;;;;; -10029;LINEAR B SYLLABLE B027 RE;Lo;0;L;;;;;N;;;;; -1002A;LINEAR B SYLLABLE B053 RI;Lo;0;L;;;;;N;;;;; -1002B;LINEAR B SYLLABLE B002 RO;Lo;0;L;;;;;N;;;;; -1002C;LINEAR B SYLLABLE B026 RU;Lo;0;L;;;;;N;;;;; -1002D;LINEAR B SYLLABLE B031 SA;Lo;0;L;;;;;N;;;;; -1002E;LINEAR B SYLLABLE B009 SE;Lo;0;L;;;;;N;;;;; -1002F;LINEAR B SYLLABLE B041 SI;Lo;0;L;;;;;N;;;;; -10030;LINEAR B SYLLABLE B012 SO;Lo;0;L;;;;;N;;;;; -10031;LINEAR B SYLLABLE B058 SU;Lo;0;L;;;;;N;;;;; -10032;LINEAR B SYLLABLE B059 TA;Lo;0;L;;;;;N;;;;; -10033;LINEAR B SYLLABLE B004 TE;Lo;0;L;;;;;N;;;;; -10034;LINEAR B SYLLABLE B037 TI;Lo;0;L;;;;;N;;;;; -10035;LINEAR B SYLLABLE B005 TO;Lo;0;L;;;;;N;;;;; -10036;LINEAR B SYLLABLE B069 TU;Lo;0;L;;;;;N;;;;; -10037;LINEAR B SYLLABLE B054 WA;Lo;0;L;;;;;N;;;;; -10038;LINEAR B SYLLABLE B075 WE;Lo;0;L;;;;;N;;;;; -10039;LINEAR B SYLLABLE B040 WI;Lo;0;L;;;;;N;;;;; -1003A;LINEAR B SYLLABLE B042 WO;Lo;0;L;;;;;N;;;;; -1003C;LINEAR B SYLLABLE B017 ZA;Lo;0;L;;;;;N;;;;; -1003D;LINEAR B SYLLABLE B074 ZE;Lo;0;L;;;;;N;;;;; -1003F;LINEAR B SYLLABLE B020 ZO;Lo;0;L;;;;;N;;;;; -10040;LINEAR B SYLLABLE B025 A2;Lo;0;L;;;;;N;;;;; -10041;LINEAR B SYLLABLE B043 A3;Lo;0;L;;;;;N;;;;; -10042;LINEAR B SYLLABLE B085 AU;Lo;0;L;;;;;N;;;;; -10043;LINEAR B SYLLABLE B071 DWE;Lo;0;L;;;;;N;;;;; -10044;LINEAR B SYLLABLE B090 DWO;Lo;0;L;;;;;N;;;;; -10045;LINEAR B SYLLABLE B048 NWA;Lo;0;L;;;;;N;;;;; -10046;LINEAR B SYLLABLE B029 PU2;Lo;0;L;;;;;N;;;;; -10047;LINEAR B SYLLABLE B062 PTE;Lo;0;L;;;;;N;;;;; -10048;LINEAR B SYLLABLE B076 RA2;Lo;0;L;;;;;N;;;;; -10049;LINEAR B SYLLABLE B033 RA3;Lo;0;L;;;;;N;;;;; -1004A;LINEAR B SYLLABLE B068 RO2;Lo;0;L;;;;;N;;;;; -1004B;LINEAR B SYLLABLE B066 TA2;Lo;0;L;;;;;N;;;;; -1004C;LINEAR B SYLLABLE B087 TWE;Lo;0;L;;;;;N;;;;; -1004D;LINEAR B SYLLABLE B091 TWO;Lo;0;L;;;;;N;;;;; -10050;LINEAR B SYMBOL B018;Lo;0;L;;;;;N;;;;; -10051;LINEAR B SYMBOL B019;Lo;0;L;;;;;N;;;;; -10052;LINEAR B SYMBOL B022;Lo;0;L;;;;;N;;;;; -10053;LINEAR B SYMBOL B034;Lo;0;L;;;;;N;;;;; -10054;LINEAR B SYMBOL B047;Lo;0;L;;;;;N;;;;; -10055;LINEAR B SYMBOL B049;Lo;0;L;;;;;N;;;;; -10056;LINEAR B SYMBOL B056;Lo;0;L;;;;;N;;;;; -10057;LINEAR B SYMBOL B063;Lo;0;L;;;;;N;;;;; -10058;LINEAR B SYMBOL B064;Lo;0;L;;;;;N;;;;; -10059;LINEAR B SYMBOL B079;Lo;0;L;;;;;N;;;;; -1005A;LINEAR B SYMBOL B082;Lo;0;L;;;;;N;;;;; -1005B;LINEAR B SYMBOL B083;Lo;0;L;;;;;N;;;;; -1005C;LINEAR B SYMBOL B086;Lo;0;L;;;;;N;;;;; -1005D;LINEAR B SYMBOL B089;Lo;0;L;;;;;N;;;;; -10080;LINEAR B IDEOGRAM B100 MAN;Lo;0;L;;;;;N;;;;; -10081;LINEAR B IDEOGRAM B102 WOMAN;Lo;0;L;;;;;N;;;;; -10082;LINEAR B IDEOGRAM B104 DEER;Lo;0;L;;;;;N;;;;; -10083;LINEAR B IDEOGRAM B105 EQUID;Lo;0;L;;;;;N;;;;; -10084;LINEAR B IDEOGRAM B105F MARE;Lo;0;L;;;;;N;;;;; -10085;LINEAR B IDEOGRAM B105M STALLION;Lo;0;L;;;;;N;;;;; -10086;LINEAR B IDEOGRAM B106F EWE;Lo;0;L;;;;;N;;;;; -10087;LINEAR B IDEOGRAM B106M RAM;Lo;0;L;;;;;N;;;;; -10088;LINEAR B IDEOGRAM B107F SHE-GOAT;Lo;0;L;;;;;N;;;;; -10089;LINEAR B IDEOGRAM B107M HE-GOAT;Lo;0;L;;;;;N;;;;; -1008A;LINEAR B IDEOGRAM B108F SOW;Lo;0;L;;;;;N;;;;; -1008B;LINEAR B IDEOGRAM B108M BOAR;Lo;0;L;;;;;N;;;;; -1008C;LINEAR B IDEOGRAM B109F COW;Lo;0;L;;;;;N;;;;; -1008D;LINEAR B IDEOGRAM B109M BULL;Lo;0;L;;;;;N;;;;; -1008E;LINEAR B IDEOGRAM B120 WHEAT;Lo;0;L;;;;;N;;;;; -1008F;LINEAR B IDEOGRAM B121 BARLEY;Lo;0;L;;;;;N;;;;; -10090;LINEAR B IDEOGRAM B122 OLIVE;Lo;0;L;;;;;N;;;;; -10091;LINEAR B IDEOGRAM B123 SPICE;Lo;0;L;;;;;N;;;;; -10092;LINEAR B IDEOGRAM B125 CYPERUS;Lo;0;L;;;;;N;;;;; -10093;LINEAR B MONOGRAM B127 KAPO;Lo;0;L;;;;;N;;;;; -10094;LINEAR B MONOGRAM B128 KANAKO;Lo;0;L;;;;;N;;;;; -10095;LINEAR B IDEOGRAM B130 OIL;Lo;0;L;;;;;N;;;;; -10096;LINEAR B IDEOGRAM B131 WINE;Lo;0;L;;;;;N;;;;; -10097;LINEAR B IDEOGRAM B132;Lo;0;L;;;;;N;;;;; -10098;LINEAR B MONOGRAM B133 AREPA;Lo;0;L;;;;;N;;;;; -10099;LINEAR B MONOGRAM B135 MERI;Lo;0;L;;;;;N;;;;; -1009A;LINEAR B IDEOGRAM B140 BRONZE;Lo;0;L;;;;;N;;;;; -1009B;LINEAR B IDEOGRAM B141 GOLD;Lo;0;L;;;;;N;;;;; -1009C;LINEAR B IDEOGRAM B142;Lo;0;L;;;;;N;;;;; -1009D;LINEAR B IDEOGRAM B145 WOOL;Lo;0;L;;;;;N;;;;; -1009E;LINEAR B IDEOGRAM B146;Lo;0;L;;;;;N;;;;; -1009F;LINEAR B IDEOGRAM B150;Lo;0;L;;;;;N;;;;; -100A0;LINEAR B IDEOGRAM B151 HORN;Lo;0;L;;;;;N;;;;; -100A1;LINEAR B IDEOGRAM B152;Lo;0;L;;;;;N;;;;; -100A2;LINEAR B IDEOGRAM B153;Lo;0;L;;;;;N;;;;; -100A3;LINEAR B IDEOGRAM B154;Lo;0;L;;;;;N;;;;; -100A4;LINEAR B MONOGRAM B156 TURO2;Lo;0;L;;;;;N;;;;; -100A5;LINEAR B IDEOGRAM B157;Lo;0;L;;;;;N;;;;; -100A6;LINEAR B IDEOGRAM B158;Lo;0;L;;;;;N;;;;; -100A7;LINEAR B IDEOGRAM B159 CLOTH;Lo;0;L;;;;;N;;;;; -100A8;LINEAR B IDEOGRAM B160;Lo;0;L;;;;;N;;;;; -100A9;LINEAR B IDEOGRAM B161;Lo;0;L;;;;;N;;;;; -100AA;LINEAR B IDEOGRAM B162 GARMENT;Lo;0;L;;;;;N;;;;; -100AB;LINEAR B IDEOGRAM B163 ARMOUR;Lo;0;L;;;;;N;;;;; -100AC;LINEAR B IDEOGRAM B164;Lo;0;L;;;;;N;;;;; -100AD;LINEAR B IDEOGRAM B165;Lo;0;L;;;;;N;;;;; -100AE;LINEAR B IDEOGRAM B166;Lo;0;L;;;;;N;;;;; -100AF;LINEAR B IDEOGRAM B167;Lo;0;L;;;;;N;;;;; -100B0;LINEAR B IDEOGRAM B168;Lo;0;L;;;;;N;;;;; -100B1;LINEAR B IDEOGRAM B169;Lo;0;L;;;;;N;;;;; -100B2;LINEAR B IDEOGRAM B170;Lo;0;L;;;;;N;;;;; -100B3;LINEAR B IDEOGRAM B171;Lo;0;L;;;;;N;;;;; -100B4;LINEAR B IDEOGRAM B172;Lo;0;L;;;;;N;;;;; -100B5;LINEAR B IDEOGRAM B173 MONTH;Lo;0;L;;;;;N;;;;; -100B6;LINEAR B IDEOGRAM B174;Lo;0;L;;;;;N;;;;; -100B7;LINEAR B IDEOGRAM B176 TREE;Lo;0;L;;;;;N;;;;; -100B8;LINEAR B IDEOGRAM B177;Lo;0;L;;;;;N;;;;; -100B9;LINEAR B IDEOGRAM B178;Lo;0;L;;;;;N;;;;; -100BA;LINEAR B IDEOGRAM B179;Lo;0;L;;;;;N;;;;; -100BB;LINEAR B IDEOGRAM B180;Lo;0;L;;;;;N;;;;; -100BC;LINEAR B IDEOGRAM B181;Lo;0;L;;;;;N;;;;; -100BD;LINEAR B IDEOGRAM B182;Lo;0;L;;;;;N;;;;; -100BE;LINEAR B IDEOGRAM B183;Lo;0;L;;;;;N;;;;; -100BF;LINEAR B IDEOGRAM B184;Lo;0;L;;;;;N;;;;; -100C0;LINEAR B IDEOGRAM B185;Lo;0;L;;;;;N;;;;; -100C1;LINEAR B IDEOGRAM B189;Lo;0;L;;;;;N;;;;; -100C2;LINEAR B IDEOGRAM B190;Lo;0;L;;;;;N;;;;; -100C3;LINEAR B IDEOGRAM B191 HELMET;Lo;0;L;;;;;N;;;;; -100C4;LINEAR B IDEOGRAM B220 FOOTSTOOL;Lo;0;L;;;;;N;;;;; -100C5;LINEAR B IDEOGRAM B225 BATHTUB;Lo;0;L;;;;;N;;;;; -100C6;LINEAR B IDEOGRAM B230 SPEAR;Lo;0;L;;;;;N;;;;; -100C7;LINEAR B IDEOGRAM B231 ARROW;Lo;0;L;;;;;N;;;;; -100C8;LINEAR B IDEOGRAM B232;Lo;0;L;;;;;N;;;;; -100C9;LINEAR B IDEOGRAM B233 SWORD;Lo;0;L;;;;;N;;pug;;; -100CA;LINEAR B IDEOGRAM B234;Lo;0;L;;;;;N;;;;; -100CB;LINEAR B IDEOGRAM B236;Lo;0;L;;;;;N;;gup;;; -100CC;LINEAR B IDEOGRAM B240 WHEELED CHARIOT;Lo;0;L;;;;;N;;;;; -100CD;LINEAR B IDEOGRAM B241 CHARIOT;Lo;0;L;;;;;N;;;;; -100CE;LINEAR B IDEOGRAM B242 CHARIOT FRAME;Lo;0;L;;;;;N;;;;; -100CF;LINEAR B IDEOGRAM B243 WHEEL;Lo;0;L;;;;;N;;;;; -100D0;LINEAR B IDEOGRAM B245;Lo;0;L;;;;;N;;;;; -100D1;LINEAR B IDEOGRAM B246;Lo;0;L;;;;;N;;;;; -100D2;LINEAR B MONOGRAM B247 DIPTE;Lo;0;L;;;;;N;;;;; -100D3;LINEAR B IDEOGRAM B248;Lo;0;L;;;;;N;;;;; -100D4;LINEAR B IDEOGRAM B249;Lo;0;L;;;;;N;;;;; -100D5;LINEAR B IDEOGRAM B251;Lo;0;L;;;;;N;;;;; -100D6;LINEAR B IDEOGRAM B252;Lo;0;L;;;;;N;;;;; -100D7;LINEAR B IDEOGRAM B253;Lo;0;L;;;;;N;;;;; -100D8;LINEAR B IDEOGRAM B254 DART;Lo;0;L;;;;;N;;;;; -100D9;LINEAR B IDEOGRAM B255;Lo;0;L;;;;;N;;;;; -100DA;LINEAR B IDEOGRAM B256;Lo;0;L;;;;;N;;;;; -100DB;LINEAR B IDEOGRAM B257;Lo;0;L;;;;;N;;;;; -100DC;LINEAR B IDEOGRAM B258;Lo;0;L;;;;;N;;;;; -100DD;LINEAR B IDEOGRAM B259;Lo;0;L;;;;;N;;;;; -100DE;LINEAR B IDEOGRAM VESSEL B155;Lo;0;L;;;;;N;;;;; -100DF;LINEAR B IDEOGRAM VESSEL B200;Lo;0;L;;;;;N;;;;; -100E0;LINEAR B IDEOGRAM VESSEL B201;Lo;0;L;;;;;N;;;;; -100E1;LINEAR B IDEOGRAM VESSEL B202;Lo;0;L;;;;;N;;;;; -100E2;LINEAR B IDEOGRAM VESSEL B203;Lo;0;L;;;;;N;;;;; -100E3;LINEAR B IDEOGRAM VESSEL B204;Lo;0;L;;;;;N;;;;; -100E4;LINEAR B IDEOGRAM VESSEL B205;Lo;0;L;;;;;N;;;;; -100E5;LINEAR B IDEOGRAM VESSEL B206;Lo;0;L;;;;;N;;;;; -100E6;LINEAR B IDEOGRAM VESSEL B207;Lo;0;L;;;;;N;;;;; -100E7;LINEAR B IDEOGRAM VESSEL B208;Lo;0;L;;;;;N;;;;; -100E8;LINEAR B IDEOGRAM VESSEL B209;Lo;0;L;;;;;N;;;;; -100E9;LINEAR B IDEOGRAM VESSEL B210;Lo;0;L;;;;;N;;;;; -100EA;LINEAR B IDEOGRAM VESSEL B211;Lo;0;L;;;;;N;;;;; -100EB;LINEAR B IDEOGRAM VESSEL B212;Lo;0;L;;;;;N;;;;; -100EC;LINEAR B IDEOGRAM VESSEL B213;Lo;0;L;;;;;N;;;;; -100ED;LINEAR B IDEOGRAM VESSEL B214;Lo;0;L;;;;;N;;;;; -100EE;LINEAR B IDEOGRAM VESSEL B215;Lo;0;L;;;;;N;;;;; -100EF;LINEAR B IDEOGRAM VESSEL B216;Lo;0;L;;;;;N;;;;; -100F0;LINEAR B IDEOGRAM VESSEL B217;Lo;0;L;;;;;N;;;;; -100F1;LINEAR B IDEOGRAM VESSEL B218;Lo;0;L;;;;;N;;;;; -100F2;LINEAR B IDEOGRAM VESSEL B219;Lo;0;L;;;;;N;;;;; -100F3;LINEAR B IDEOGRAM VESSEL B221;Lo;0;L;;;;;N;;;;; -100F4;LINEAR B IDEOGRAM VESSEL B222;Lo;0;L;;;;;N;;;;; -100F5;LINEAR B IDEOGRAM VESSEL B226;Lo;0;L;;;;;N;;;;; -100F6;LINEAR B IDEOGRAM VESSEL B227;Lo;0;L;;;;;N;;;;; -100F7;LINEAR B IDEOGRAM VESSEL B228;Lo;0;L;;;;;N;;;;; -100F8;LINEAR B IDEOGRAM VESSEL B229;Lo;0;L;;;;;N;;;;; -100F9;LINEAR B IDEOGRAM VESSEL B250;Lo;0;L;;;;;N;;;;; -100FA;LINEAR B IDEOGRAM VESSEL B305;Lo;0;L;;;;;N;;;;; -10100;AEGEAN WORD SEPARATOR LINE;Po;0;L;;;;;N;;;;; -10101;AEGEAN WORD SEPARATOR DOT;Po;0;ON;;;;;N;;;;; -10102;AEGEAN CHECK MARK;So;0;L;;;;;N;;;;; -10107;AEGEAN NUMBER ONE;No;0;L;;;;1;N;;;;; -10108;AEGEAN NUMBER TWO;No;0;L;;;;2;N;;;;; -10109;AEGEAN NUMBER THREE;No;0;L;;;;3;N;;;;; -1010A;AEGEAN NUMBER FOUR;No;0;L;;;;4;N;;;;; -1010B;AEGEAN NUMBER FIVE;No;0;L;;;;5;N;;;;; -1010C;AEGEAN NUMBER SIX;No;0;L;;;;6;N;;;;; -1010D;AEGEAN NUMBER SEVEN;No;0;L;;;;7;N;;;;; -1010E;AEGEAN NUMBER EIGHT;No;0;L;;;;8;N;;;;; -1010F;AEGEAN NUMBER NINE;No;0;L;;;;9;N;;;;; -10110;AEGEAN NUMBER TEN;No;0;L;;;;10;N;;;;; -10111;AEGEAN NUMBER TWENTY;No;0;L;;;;20;N;;;;; -10112;AEGEAN NUMBER THIRTY;No;0;L;;;;30;N;;;;; -10113;AEGEAN NUMBER FORTY;No;0;L;;;;40;N;;;;; -10114;AEGEAN NUMBER FIFTY;No;0;L;;;;50;N;;;;; -10115;AEGEAN NUMBER SIXTY;No;0;L;;;;60;N;;;;; -10116;AEGEAN NUMBER SEVENTY;No;0;L;;;;70;N;;;;; -10117;AEGEAN NUMBER EIGHTY;No;0;L;;;;80;N;;;;; -10118;AEGEAN NUMBER NINETY;No;0;L;;;;90;N;;;;; -10119;AEGEAN NUMBER ONE HUNDRED;No;0;L;;;;100;N;;;;; -1011A;AEGEAN NUMBER TWO HUNDRED;No;0;L;;;;200;N;;;;; -1011B;AEGEAN NUMBER THREE HUNDRED;No;0;L;;;;300;N;;;;; -1011C;AEGEAN NUMBER FOUR HUNDRED;No;0;L;;;;400;N;;;;; -1011D;AEGEAN NUMBER FIVE HUNDRED;No;0;L;;;;500;N;;;;; -1011E;AEGEAN NUMBER SIX HUNDRED;No;0;L;;;;600;N;;;;; -1011F;AEGEAN NUMBER SEVEN HUNDRED;No;0;L;;;;700;N;;;;; -10120;AEGEAN NUMBER EIGHT HUNDRED;No;0;L;;;;800;N;;;;; -10121;AEGEAN NUMBER NINE HUNDRED;No;0;L;;;;900;N;;;;; -10122;AEGEAN NUMBER ONE THOUSAND;No;0;L;;;;1000;N;;;;; -10123;AEGEAN NUMBER TWO THOUSAND;No;0;L;;;;2000;N;;;;; -10124;AEGEAN NUMBER THREE THOUSAND;No;0;L;;;;3000;N;;;;; -10125;AEGEAN NUMBER FOUR THOUSAND;No;0;L;;;;4000;N;;;;; -10126;AEGEAN NUMBER FIVE THOUSAND;No;0;L;;;;5000;N;;;;; -10127;AEGEAN NUMBER SIX THOUSAND;No;0;L;;;;6000;N;;;;; -10128;AEGEAN NUMBER SEVEN THOUSAND;No;0;L;;;;7000;N;;;;; -10129;AEGEAN NUMBER EIGHT THOUSAND;No;0;L;;;;8000;N;;;;; -1012A;AEGEAN NUMBER NINE THOUSAND;No;0;L;;;;9000;N;;;;; -1012B;AEGEAN NUMBER TEN THOUSAND;No;0;L;;;;10000;N;;;;; -1012C;AEGEAN NUMBER TWENTY THOUSAND;No;0;L;;;;20000;N;;;;; -1012D;AEGEAN NUMBER THIRTY THOUSAND;No;0;L;;;;30000;N;;;;; -1012E;AEGEAN NUMBER FORTY THOUSAND;No;0;L;;;;40000;N;;;;; -1012F;AEGEAN NUMBER FIFTY THOUSAND;No;0;L;;;;50000;N;;;;; -10130;AEGEAN NUMBER SIXTY THOUSAND;No;0;L;;;;60000;N;;;;; -10131;AEGEAN NUMBER SEVENTY THOUSAND;No;0;L;;;;70000;N;;;;; -10132;AEGEAN NUMBER EIGHTY THOUSAND;No;0;L;;;;80000;N;;;;; -10133;AEGEAN NUMBER NINETY THOUSAND;No;0;L;;;;90000;N;;;;; -10137;AEGEAN WEIGHT BASE UNIT;So;0;L;;;;;N;;;;; -10138;AEGEAN WEIGHT FIRST SUBUNIT;So;0;L;;;;;N;;;;; -10139;AEGEAN WEIGHT SECOND SUBUNIT;So;0;L;;;;;N;;;;; -1013A;AEGEAN WEIGHT THIRD SUBUNIT;So;0;L;;;;;N;;;;; -1013B;AEGEAN WEIGHT FOURTH SUBUNIT;So;0;L;;;;;N;;;;; -1013C;AEGEAN DRY MEASURE FIRST SUBUNIT;So;0;L;;;;;N;;;;; -1013D;AEGEAN LIQUID MEASURE FIRST SUBUNIT;So;0;L;;;;;N;;;;; -1013E;AEGEAN MEASURE SECOND SUBUNIT;So;0;L;;;;;N;;;;; -1013F;AEGEAN MEASURE THIRD SUBUNIT;So;0;L;;;;;N;;;;; -10140;GREEK ACROPHONIC ATTIC ONE QUARTER;Nl;0;ON;;;;1/4;N;;;;; -10141;GREEK ACROPHONIC ATTIC ONE HALF;Nl;0;ON;;;;1/2;N;;;;; -10142;GREEK ACROPHONIC ATTIC ONE DRACHMA;Nl;0;ON;;;;1;N;;;;; -10143;GREEK ACROPHONIC ATTIC FIVE;Nl;0;ON;;;;5;N;;;;; -10144;GREEK ACROPHONIC ATTIC FIFTY;Nl;0;ON;;;;50;N;;;;; -10145;GREEK ACROPHONIC ATTIC FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -10146;GREEK ACROPHONIC ATTIC FIVE THOUSAND;Nl;0;ON;;;;5000;N;;;;; -10147;GREEK ACROPHONIC ATTIC FIFTY THOUSAND;Nl;0;ON;;;;50000;N;;;;; -10148;GREEK ACROPHONIC ATTIC FIVE TALENTS;Nl;0;ON;;;;5;N;;;;; -10149;GREEK ACROPHONIC ATTIC TEN TALENTS;Nl;0;ON;;;;10;N;;;;; -1014A;GREEK ACROPHONIC ATTIC FIFTY TALENTS;Nl;0;ON;;;;50;N;;;;; -1014B;GREEK ACROPHONIC ATTIC ONE HUNDRED TALENTS;Nl;0;ON;;;;100;N;;;;; -1014C;GREEK ACROPHONIC ATTIC FIVE HUNDRED TALENTS;Nl;0;ON;;;;500;N;;;;; -1014D;GREEK ACROPHONIC ATTIC ONE THOUSAND TALENTS;Nl;0;ON;;;;1000;N;;;;; -1014E;GREEK ACROPHONIC ATTIC FIVE THOUSAND TALENTS;Nl;0;ON;;;;5000;N;;;;; -1014F;GREEK ACROPHONIC ATTIC FIVE STATERS;Nl;0;ON;;;;5;N;;;;; -10150;GREEK ACROPHONIC ATTIC TEN STATERS;Nl;0;ON;;;;10;N;;;;; -10151;GREEK ACROPHONIC ATTIC FIFTY STATERS;Nl;0;ON;;;;50;N;;;;; -10152;GREEK ACROPHONIC ATTIC ONE HUNDRED STATERS;Nl;0;ON;;;;100;N;;;;; -10153;GREEK ACROPHONIC ATTIC FIVE HUNDRED STATERS;Nl;0;ON;;;;500;N;;;;; -10154;GREEK ACROPHONIC ATTIC ONE THOUSAND STATERS;Nl;0;ON;;;;1000;N;;;;; -10155;GREEK ACROPHONIC ATTIC TEN THOUSAND STATERS;Nl;0;ON;;;;10000;N;;;;; -10156;GREEK ACROPHONIC ATTIC FIFTY THOUSAND STATERS;Nl;0;ON;;;;50000;N;;;;; -10157;GREEK ACROPHONIC ATTIC TEN MNAS;Nl;0;ON;;;;10;N;;;;; -10158;GREEK ACROPHONIC HERAEUM ONE PLETHRON;Nl;0;ON;;;;1;N;;;;; -10159;GREEK ACROPHONIC THESPIAN ONE;Nl;0;ON;;;;1;N;;;;; -1015A;GREEK ACROPHONIC HERMIONIAN ONE;Nl;0;ON;;;;1;N;;;;; -1015B;GREEK ACROPHONIC EPIDAUREAN TWO;Nl;0;ON;;;;2;N;;;;; -1015C;GREEK ACROPHONIC THESPIAN TWO;Nl;0;ON;;;;2;N;;;;; -1015D;GREEK ACROPHONIC CYRENAIC TWO DRACHMAS;Nl;0;ON;;;;2;N;;;;; -1015E;GREEK ACROPHONIC EPIDAUREAN TWO DRACHMAS;Nl;0;ON;;;;2;N;;;;; -1015F;GREEK ACROPHONIC TROEZENIAN FIVE;Nl;0;ON;;;;5;N;;;;; -10160;GREEK ACROPHONIC TROEZENIAN TEN;Nl;0;ON;;;;10;N;;;;; -10161;GREEK ACROPHONIC TROEZENIAN TEN ALTERNATE FORM;Nl;0;ON;;;;10;N;;;;; -10162;GREEK ACROPHONIC HERMIONIAN TEN;Nl;0;ON;;;;10;N;;;;; -10163;GREEK ACROPHONIC MESSENIAN TEN;Nl;0;ON;;;;10;N;;;;; -10164;GREEK ACROPHONIC THESPIAN TEN;Nl;0;ON;;;;10;N;;;;; -10165;GREEK ACROPHONIC THESPIAN THIRTY;Nl;0;ON;;;;30;N;;;;; -10166;GREEK ACROPHONIC TROEZENIAN FIFTY;Nl;0;ON;;;;50;N;;;;; -10167;GREEK ACROPHONIC TROEZENIAN FIFTY ALTERNATE FORM;Nl;0;ON;;;;50;N;;;;; -10168;GREEK ACROPHONIC HERMIONIAN FIFTY;Nl;0;ON;;;;50;N;;;;; -10169;GREEK ACROPHONIC THESPIAN FIFTY;Nl;0;ON;;;;50;N;;;;; -1016A;GREEK ACROPHONIC THESPIAN ONE HUNDRED;Nl;0;ON;;;;100;N;;;;; -1016B;GREEK ACROPHONIC THESPIAN THREE HUNDRED;Nl;0;ON;;;;300;N;;;;; -1016C;GREEK ACROPHONIC EPIDAUREAN FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -1016D;GREEK ACROPHONIC TROEZENIAN FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -1016E;GREEK ACROPHONIC THESPIAN FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -1016F;GREEK ACROPHONIC CARYSTIAN FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -10170;GREEK ACROPHONIC NAXIAN FIVE HUNDRED;Nl;0;ON;;;;500;N;;;;; -10171;GREEK ACROPHONIC THESPIAN ONE THOUSAND;Nl;0;ON;;;;1000;N;;;;; -10172;GREEK ACROPHONIC THESPIAN FIVE THOUSAND;Nl;0;ON;;;;5000;N;;;;; -10173;GREEK ACROPHONIC DELPHIC FIVE MNAS;Nl;0;ON;;;;5;N;;;;; -10174;GREEK ACROPHONIC STRATIAN FIFTY MNAS;Nl;0;ON;;;;50;N;;;;; -10175;GREEK ONE HALF SIGN;No;0;ON;;;;1/2;N;;;;; -10176;GREEK ONE HALF SIGN ALTERNATE FORM;No;0;ON;;;;1/2;N;;;;; -10177;GREEK TWO THIRDS SIGN;No;0;ON;;;;2/3;N;;;;; -10178;GREEK THREE QUARTERS SIGN;No;0;ON;;;;3/4;N;;;;; -10179;GREEK YEAR SIGN;So;0;ON;;;;;N;;;;; -1017A;GREEK TALENT SIGN;So;0;ON;;;;;N;;;;; -1017B;GREEK DRACHMA SIGN;So;0;ON;;;;;N;;;;; -1017C;GREEK OBOL SIGN;So;0;ON;;;;;N;;;;; -1017D;GREEK TWO OBOLS SIGN;So;0;ON;;;;;N;;;;; -1017E;GREEK THREE OBOLS SIGN;So;0;ON;;;;;N;;;;; -1017F;GREEK FOUR OBOLS SIGN;So;0;ON;;;;;N;;;;; -10180;GREEK FIVE OBOLS SIGN;So;0;ON;;;;;N;;;;; -10181;GREEK METRETES SIGN;So;0;ON;;;;;N;;;;; -10182;GREEK KYATHOS BASE SIGN;So;0;ON;;;;;N;;;;; -10183;GREEK LITRA SIGN;So;0;ON;;;;;N;;;;; -10184;GREEK OUNKIA SIGN;So;0;ON;;;;;N;;;;; -10185;GREEK XESTES SIGN;So;0;ON;;;;;N;;;;; -10186;GREEK ARTABE SIGN;So;0;ON;;;;;N;;;;; -10187;GREEK AROURA SIGN;So;0;ON;;;;;N;;;;; -10188;GREEK GRAMMA SIGN;So;0;ON;;;;;N;;;;; -10189;GREEK TRYBLION BASE SIGN;So;0;ON;;;;;N;;;;; -1018A;GREEK ZERO SIGN;No;0;ON;;;;0;N;;;;; -10190;ROMAN SEXTANS SIGN;So;0;ON;;;;;N;;;;; -10191;ROMAN UNCIA SIGN;So;0;ON;;;;;N;;;;; -10192;ROMAN SEMUNCIA SIGN;So;0;ON;;;;;N;;;;; -10193;ROMAN SEXTULA SIGN;So;0;ON;;;;;N;;;;; -10194;ROMAN DIMIDIA SEXTULA SIGN;So;0;ON;;;;;N;;;;; -10195;ROMAN SILIQUA SIGN;So;0;ON;;;;;N;;;;; -10196;ROMAN DENARIUS SIGN;So;0;ON;;;;;N;;;;; -10197;ROMAN QUINARIUS SIGN;So;0;ON;;;;;N;;;;; -10198;ROMAN SESTERTIUS SIGN;So;0;ON;;;;;N;;;;; -10199;ROMAN DUPONDIUS SIGN;So;0;ON;;;;;N;;;;; -1019A;ROMAN AS SIGN;So;0;ON;;;;;N;;;;; -1019B;ROMAN CENTURIAL SIGN;So;0;ON;;;;;N;;;;; -101D0;PHAISTOS DISC SIGN PEDESTRIAN;So;0;L;;;;;N;;;;; -101D1;PHAISTOS DISC SIGN PLUMED HEAD;So;0;L;;;;;N;;;;; -101D2;PHAISTOS DISC SIGN TATTOOED HEAD;So;0;L;;;;;N;;;;; -101D3;PHAISTOS DISC SIGN CAPTIVE;So;0;L;;;;;N;;;;; -101D4;PHAISTOS DISC SIGN CHILD;So;0;L;;;;;N;;;;; -101D5;PHAISTOS DISC SIGN WOMAN;So;0;L;;;;;N;;;;; -101D6;PHAISTOS DISC SIGN HELMET;So;0;L;;;;;N;;;;; -101D7;PHAISTOS DISC SIGN GAUNTLET;So;0;L;;;;;N;;;;; -101D8;PHAISTOS DISC SIGN TIARA;So;0;L;;;;;N;;;;; -101D9;PHAISTOS DISC SIGN ARROW;So;0;L;;;;;N;;;;; -101DA;PHAISTOS DISC SIGN BOW;So;0;L;;;;;N;;;;; -101DB;PHAISTOS DISC SIGN SHIELD;So;0;L;;;;;N;;;;; -101DC;PHAISTOS DISC SIGN CLUB;So;0;L;;;;;N;;;;; -101DD;PHAISTOS DISC SIGN MANACLES;So;0;L;;;;;N;;;;; -101DE;PHAISTOS DISC SIGN MATTOCK;So;0;L;;;;;N;;;;; -101DF;PHAISTOS DISC SIGN SAW;So;0;L;;;;;N;;;;; -101E0;PHAISTOS DISC SIGN LID;So;0;L;;;;;N;;;;; -101E1;PHAISTOS DISC SIGN BOOMERANG;So;0;L;;;;;N;;;;; -101E2;PHAISTOS DISC SIGN CARPENTRY PLANE;So;0;L;;;;;N;;;;; -101E3;PHAISTOS DISC SIGN DOLIUM;So;0;L;;;;;N;;;;; -101E4;PHAISTOS DISC SIGN COMB;So;0;L;;;;;N;;;;; -101E5;PHAISTOS DISC SIGN SLING;So;0;L;;;;;N;;;;; -101E6;PHAISTOS DISC SIGN COLUMN;So;0;L;;;;;N;;;;; -101E7;PHAISTOS DISC SIGN BEEHIVE;So;0;L;;;;;N;;;;; -101E8;PHAISTOS DISC SIGN SHIP;So;0;L;;;;;N;;;;; -101E9;PHAISTOS DISC SIGN HORN;So;0;L;;;;;N;;;;; -101EA;PHAISTOS DISC SIGN HIDE;So;0;L;;;;;N;;;;; -101EB;PHAISTOS DISC SIGN BULLS LEG;So;0;L;;;;;N;;;;; -101EC;PHAISTOS DISC SIGN CAT;So;0;L;;;;;N;;;;; -101ED;PHAISTOS DISC SIGN RAM;So;0;L;;;;;N;;;;; -101EE;PHAISTOS DISC SIGN EAGLE;So;0;L;;;;;N;;;;; -101EF;PHAISTOS DISC SIGN DOVE;So;0;L;;;;;N;;;;; -101F0;PHAISTOS DISC SIGN TUNNY;So;0;L;;;;;N;;;;; -101F1;PHAISTOS DISC SIGN BEE;So;0;L;;;;;N;;;;; -101F2;PHAISTOS DISC SIGN PLANE TREE;So;0;L;;;;;N;;;;; -101F3;PHAISTOS DISC SIGN VINE;So;0;L;;;;;N;;;;; -101F4;PHAISTOS DISC SIGN PAPYRUS;So;0;L;;;;;N;;;;; -101F5;PHAISTOS DISC SIGN ROSETTE;So;0;L;;;;;N;;;;; -101F6;PHAISTOS DISC SIGN LILY;So;0;L;;;;;N;;;;; -101F7;PHAISTOS DISC SIGN OX BACK;So;0;L;;;;;N;;;;; -101F8;PHAISTOS DISC SIGN FLUTE;So;0;L;;;;;N;;;;; -101F9;PHAISTOS DISC SIGN GRATER;So;0;L;;;;;N;;;;; -101FA;PHAISTOS DISC SIGN STRAINER;So;0;L;;;;;N;;;;; -101FB;PHAISTOS DISC SIGN SMALL AXE;So;0;L;;;;;N;;;;; -101FC;PHAISTOS DISC SIGN WAVY BAND;So;0;L;;;;;N;;;;; -101FD;PHAISTOS DISC SIGN COMBINING OBLIQUE STROKE;Mn;220;NSM;;;;;N;;;;; -10280;LYCIAN LETTER A;Lo;0;L;;;;;N;;;;; -10281;LYCIAN LETTER E;Lo;0;L;;;;;N;;;;; -10282;LYCIAN LETTER B;Lo;0;L;;;;;N;;;;; -10283;LYCIAN LETTER BH;Lo;0;L;;;;;N;;;;; -10284;LYCIAN LETTER G;Lo;0;L;;;;;N;;;;; -10285;LYCIAN LETTER D;Lo;0;L;;;;;N;;;;; -10286;LYCIAN LETTER I;Lo;0;L;;;;;N;;;;; -10287;LYCIAN LETTER W;Lo;0;L;;;;;N;;;;; -10288;LYCIAN LETTER Z;Lo;0;L;;;;;N;;;;; -10289;LYCIAN LETTER TH;Lo;0;L;;;;;N;;;;; -1028A;LYCIAN LETTER J;Lo;0;L;;;;;N;;;;; -1028B;LYCIAN LETTER K;Lo;0;L;;;;;N;;;;; -1028C;LYCIAN LETTER Q;Lo;0;L;;;;;N;;;;; -1028D;LYCIAN LETTER L;Lo;0;L;;;;;N;;;;; -1028E;LYCIAN LETTER M;Lo;0;L;;;;;N;;;;; -1028F;LYCIAN LETTER N;Lo;0;L;;;;;N;;;;; -10290;LYCIAN LETTER MM;Lo;0;L;;;;;N;;;;; -10291;LYCIAN LETTER NN;Lo;0;L;;;;;N;;;;; -10292;LYCIAN LETTER U;Lo;0;L;;;;;N;;;;; -10293;LYCIAN LETTER P;Lo;0;L;;;;;N;;;;; -10294;LYCIAN LETTER KK;Lo;0;L;;;;;N;;;;; -10295;LYCIAN LETTER R;Lo;0;L;;;;;N;;;;; -10296;LYCIAN LETTER S;Lo;0;L;;;;;N;;;;; -10297;LYCIAN LETTER T;Lo;0;L;;;;;N;;;;; -10298;LYCIAN LETTER TT;Lo;0;L;;;;;N;;;;; -10299;LYCIAN LETTER AN;Lo;0;L;;;;;N;;;;; -1029A;LYCIAN LETTER EN;Lo;0;L;;;;;N;;;;; -1029B;LYCIAN LETTER H;Lo;0;L;;;;;N;;;;; -1029C;LYCIAN LETTER X;Lo;0;L;;;;;N;;;;; -102A0;CARIAN LETTER A;Lo;0;L;;;;;N;;;;; -102A1;CARIAN LETTER P2;Lo;0;L;;;;;N;;;;; -102A2;CARIAN LETTER D;Lo;0;L;;;;;N;;;;; -102A3;CARIAN LETTER L;Lo;0;L;;;;;N;;;;; -102A4;CARIAN LETTER UUU;Lo;0;L;;;;;N;;;;; -102A5;CARIAN LETTER R;Lo;0;L;;;;;N;;;;; -102A6;CARIAN LETTER LD;Lo;0;L;;;;;N;;;;; -102A7;CARIAN LETTER A2;Lo;0;L;;;;;N;;;;; -102A8;CARIAN LETTER Q;Lo;0;L;;;;;N;;;;; -102A9;CARIAN LETTER B;Lo;0;L;;;;;N;;;;; -102AA;CARIAN LETTER M;Lo;0;L;;;;;N;;;;; -102AB;CARIAN LETTER O;Lo;0;L;;;;;N;;;;; -102AC;CARIAN LETTER D2;Lo;0;L;;;;;N;;;;; -102AD;CARIAN LETTER T;Lo;0;L;;;;;N;;;;; -102AE;CARIAN LETTER SH;Lo;0;L;;;;;N;;;;; -102AF;CARIAN LETTER SH2;Lo;0;L;;;;;N;;;;; -102B0;CARIAN LETTER S;Lo;0;L;;;;;N;;;;; -102B1;CARIAN LETTER C-18;Lo;0;L;;;;;N;;;;; -102B2;CARIAN LETTER U;Lo;0;L;;;;;N;;;;; -102B3;CARIAN LETTER NN;Lo;0;L;;;;;N;;;;; -102B4;CARIAN LETTER X;Lo;0;L;;;;;N;;;;; -102B5;CARIAN LETTER N;Lo;0;L;;;;;N;;;;; -102B6;CARIAN LETTER TT2;Lo;0;L;;;;;N;;;;; -102B7;CARIAN LETTER P;Lo;0;L;;;;;N;;;;; -102B8;CARIAN LETTER SS;Lo;0;L;;;;;N;;;;; -102B9;CARIAN LETTER I;Lo;0;L;;;;;N;;;;; -102BA;CARIAN LETTER E;Lo;0;L;;;;;N;;;;; -102BB;CARIAN LETTER UUUU;Lo;0;L;;;;;N;;;;; -102BC;CARIAN LETTER K;Lo;0;L;;;;;N;;;;; -102BD;CARIAN LETTER K2;Lo;0;L;;;;;N;;;;; -102BE;CARIAN LETTER ND;Lo;0;L;;;;;N;;;;; -102BF;CARIAN LETTER UU;Lo;0;L;;;;;N;;;;; -102C0;CARIAN LETTER G;Lo;0;L;;;;;N;;;;; -102C1;CARIAN LETTER G2;Lo;0;L;;;;;N;;;;; -102C2;CARIAN LETTER ST;Lo;0;L;;;;;N;;;;; -102C3;CARIAN LETTER ST2;Lo;0;L;;;;;N;;;;; -102C4;CARIAN LETTER NG;Lo;0;L;;;;;N;;;;; -102C5;CARIAN LETTER II;Lo;0;L;;;;;N;;;;; -102C6;CARIAN LETTER C-39;Lo;0;L;;;;;N;;;;; -102C7;CARIAN LETTER TT;Lo;0;L;;;;;N;;;;; -102C8;CARIAN LETTER UUU2;Lo;0;L;;;;;N;;;;; -102C9;CARIAN LETTER RR;Lo;0;L;;;;;N;;;;; -102CA;CARIAN LETTER MB;Lo;0;L;;;;;N;;;;; -102CB;CARIAN LETTER MB2;Lo;0;L;;;;;N;;;;; -102CC;CARIAN LETTER MB3;Lo;0;L;;;;;N;;;;; -102CD;CARIAN LETTER MB4;Lo;0;L;;;;;N;;;;; -102CE;CARIAN LETTER LD2;Lo;0;L;;;;;N;;;;; -102CF;CARIAN LETTER E2;Lo;0;L;;;;;N;;;;; -102D0;CARIAN LETTER UUU3;Lo;0;L;;;;;N;;;;; -10300;OLD ITALIC LETTER A;Lo;0;L;;;;;N;;;;; -10301;OLD ITALIC LETTER BE;Lo;0;L;;;;;N;;;;; -10302;OLD ITALIC LETTER KE;Lo;0;L;;;;;N;;;;; -10303;OLD ITALIC LETTER DE;Lo;0;L;;;;;N;;;;; -10304;OLD ITALIC LETTER E;Lo;0;L;;;;;N;;;;; -10305;OLD ITALIC LETTER VE;Lo;0;L;;;;;N;;;;; -10306;OLD ITALIC LETTER ZE;Lo;0;L;;;;;N;;;;; -10307;OLD ITALIC LETTER HE;Lo;0;L;;;;;N;;;;; -10308;OLD ITALIC LETTER THE;Lo;0;L;;;;;N;;;;; -10309;OLD ITALIC LETTER I;Lo;0;L;;;;;N;;;;; -1030A;OLD ITALIC LETTER KA;Lo;0;L;;;;;N;;;;; -1030B;OLD ITALIC LETTER EL;Lo;0;L;;;;;N;;;;; -1030C;OLD ITALIC LETTER EM;Lo;0;L;;;;;N;;;;; -1030D;OLD ITALIC LETTER EN;Lo;0;L;;;;;N;;;;; -1030E;OLD ITALIC LETTER ESH;Lo;0;L;;;;;N;;;;; -1030F;OLD ITALIC LETTER O;Lo;0;L;;;;;N;;Faliscan;;; -10310;OLD ITALIC LETTER PE;Lo;0;L;;;;;N;;;;; -10311;OLD ITALIC LETTER SHE;Lo;0;L;;;;;N;;;;; -10312;OLD ITALIC LETTER KU;Lo;0;L;;;;;N;;;;; -10313;OLD ITALIC LETTER ER;Lo;0;L;;;;;N;;;;; -10314;OLD ITALIC LETTER ES;Lo;0;L;;;;;N;;;;; -10315;OLD ITALIC LETTER TE;Lo;0;L;;;;;N;;;;; -10316;OLD ITALIC LETTER U;Lo;0;L;;;;;N;;;;; -10317;OLD ITALIC LETTER EKS;Lo;0;L;;;;;N;;Faliscan;;; -10318;OLD ITALIC LETTER PHE;Lo;0;L;;;;;N;;;;; -10319;OLD ITALIC LETTER KHE;Lo;0;L;;;;;N;;;;; -1031A;OLD ITALIC LETTER EF;Lo;0;L;;;;;N;;;;; -1031B;OLD ITALIC LETTER ERS;Lo;0;L;;;;;N;;Umbrian;;; -1031C;OLD ITALIC LETTER CHE;Lo;0;L;;;;;N;;Umbrian;;; -1031D;OLD ITALIC LETTER II;Lo;0;L;;;;;N;;Oscan;;; -1031E;OLD ITALIC LETTER UU;Lo;0;L;;;;;N;;Oscan;;; -10320;OLD ITALIC NUMERAL ONE;No;0;L;;;;1;N;;;;; -10321;OLD ITALIC NUMERAL FIVE;No;0;L;;;;5;N;;;;; -10322;OLD ITALIC NUMERAL TEN;No;0;L;;;;10;N;;;;; -10323;OLD ITALIC NUMERAL FIFTY;No;0;L;;;;50;N;;;;; -10330;GOTHIC LETTER AHSA;Lo;0;L;;;;;N;;;;; -10331;GOTHIC LETTER BAIRKAN;Lo;0;L;;;;;N;;;;; -10332;GOTHIC LETTER GIBA;Lo;0;L;;;;;N;;;;; -10333;GOTHIC LETTER DAGS;Lo;0;L;;;;;N;;;;; -10334;GOTHIC LETTER AIHVUS;Lo;0;L;;;;;N;;;;; -10335;GOTHIC LETTER QAIRTHRA;Lo;0;L;;;;;N;;;;; -10336;GOTHIC LETTER IUJA;Lo;0;L;;;;;N;;;;; -10337;GOTHIC LETTER HAGL;Lo;0;L;;;;;N;;;;; -10338;GOTHIC LETTER THIUTH;Lo;0;L;;;;;N;;;;; -10339;GOTHIC LETTER EIS;Lo;0;L;;;;;N;;;;; -1033A;GOTHIC LETTER KUSMA;Lo;0;L;;;;;N;;;;; -1033B;GOTHIC LETTER LAGUS;Lo;0;L;;;;;N;;;;; -1033C;GOTHIC LETTER MANNA;Lo;0;L;;;;;N;;;;; -1033D;GOTHIC LETTER NAUTHS;Lo;0;L;;;;;N;;;;; -1033E;GOTHIC LETTER JER;Lo;0;L;;;;;N;;;;; -1033F;GOTHIC LETTER URUS;Lo;0;L;;;;;N;;;;; -10340;GOTHIC LETTER PAIRTHRA;Lo;0;L;;;;;N;;;;; -10341;GOTHIC LETTER NINETY;Nl;0;L;;;;90;N;;;;; -10342;GOTHIC LETTER RAIDA;Lo;0;L;;;;;N;;;;; -10343;GOTHIC LETTER SAUIL;Lo;0;L;;;;;N;;;;; -10344;GOTHIC LETTER TEIWS;Lo;0;L;;;;;N;;;;; -10345;GOTHIC LETTER WINJA;Lo;0;L;;;;;N;;;;; -10346;GOTHIC LETTER FAIHU;Lo;0;L;;;;;N;;;;; -10347;GOTHIC LETTER IGGWS;Lo;0;L;;;;;N;;;;; -10348;GOTHIC LETTER HWAIR;Lo;0;L;;;;;N;;;;; -10349;GOTHIC LETTER OTHAL;Lo;0;L;;;;;N;;;;; -1034A;GOTHIC LETTER NINE HUNDRED;Nl;0;L;;;;900;N;;;;; -10380;UGARITIC LETTER ALPA;Lo;0;L;;;;;N;;;;; -10381;UGARITIC LETTER BETA;Lo;0;L;;;;;N;;;;; -10382;UGARITIC LETTER GAMLA;Lo;0;L;;;;;N;;;;; -10383;UGARITIC LETTER KHA;Lo;0;L;;;;;N;;;;; -10384;UGARITIC LETTER DELTA;Lo;0;L;;;;;N;;;;; -10385;UGARITIC LETTER HO;Lo;0;L;;;;;N;;;;; -10386;UGARITIC LETTER WO;Lo;0;L;;;;;N;;;;; -10387;UGARITIC LETTER ZETA;Lo;0;L;;;;;N;;;;; -10388;UGARITIC LETTER HOTA;Lo;0;L;;;;;N;;;;; -10389;UGARITIC LETTER TET;Lo;0;L;;;;;N;;;;; -1038A;UGARITIC LETTER YOD;Lo;0;L;;;;;N;;;;; -1038B;UGARITIC LETTER KAF;Lo;0;L;;;;;N;;;;; -1038C;UGARITIC LETTER SHIN;Lo;0;L;;;;;N;;;;; -1038D;UGARITIC LETTER LAMDA;Lo;0;L;;;;;N;;;;; -1038E;UGARITIC LETTER MEM;Lo;0;L;;;;;N;;;;; -1038F;UGARITIC LETTER DHAL;Lo;0;L;;;;;N;;;;; -10390;UGARITIC LETTER NUN;Lo;0;L;;;;;N;;;;; -10391;UGARITIC LETTER ZU;Lo;0;L;;;;;N;;;;; -10392;UGARITIC LETTER SAMKA;Lo;0;L;;;;;N;;;;; -10393;UGARITIC LETTER AIN;Lo;0;L;;;;;N;;;;; -10394;UGARITIC LETTER PU;Lo;0;L;;;;;N;;;;; -10395;UGARITIC LETTER SADE;Lo;0;L;;;;;N;;;;; -10396;UGARITIC LETTER QOPA;Lo;0;L;;;;;N;;;;; -10397;UGARITIC LETTER RASHA;Lo;0;L;;;;;N;;;;; -10398;UGARITIC LETTER THANNA;Lo;0;L;;;;;N;;;;; -10399;UGARITIC LETTER GHAIN;Lo;0;L;;;;;N;;;;; -1039A;UGARITIC LETTER TO;Lo;0;L;;;;;N;;;;; -1039B;UGARITIC LETTER I;Lo;0;L;;;;;N;;;;; -1039C;UGARITIC LETTER U;Lo;0;L;;;;;N;;;;; -1039D;UGARITIC LETTER SSU;Lo;0;L;;;;;N;;;;; -1039F;UGARITIC WORD DIVIDER;Po;0;L;;;;;N;;;;; -103A0;OLD PERSIAN SIGN A;Lo;0;L;;;;;N;;;;; -103A1;OLD PERSIAN SIGN I;Lo;0;L;;;;;N;;;;; -103A2;OLD PERSIAN SIGN U;Lo;0;L;;;;;N;;;;; -103A3;OLD PERSIAN SIGN KA;Lo;0;L;;;;;N;;;;; -103A4;OLD PERSIAN SIGN KU;Lo;0;L;;;;;N;;;;; -103A5;OLD PERSIAN SIGN GA;Lo;0;L;;;;;N;;;;; -103A6;OLD PERSIAN SIGN GU;Lo;0;L;;;;;N;;;;; -103A7;OLD PERSIAN SIGN XA;Lo;0;L;;;;;N;;;;; -103A8;OLD PERSIAN SIGN CA;Lo;0;L;;;;;N;;;;; -103A9;OLD PERSIAN SIGN JA;Lo;0;L;;;;;N;;;;; -103AA;OLD PERSIAN SIGN JI;Lo;0;L;;;;;N;;;;; -103AB;OLD PERSIAN SIGN TA;Lo;0;L;;;;;N;;;;; -103AC;OLD PERSIAN SIGN TU;Lo;0;L;;;;;N;;;;; -103AD;OLD PERSIAN SIGN DA;Lo;0;L;;;;;N;;;;; -103AE;OLD PERSIAN SIGN DI;Lo;0;L;;;;;N;;;;; -103AF;OLD PERSIAN SIGN DU;Lo;0;L;;;;;N;;;;; -103B0;OLD PERSIAN SIGN THA;Lo;0;L;;;;;N;;;;; -103B1;OLD PERSIAN SIGN PA;Lo;0;L;;;;;N;;;;; -103B2;OLD PERSIAN SIGN BA;Lo;0;L;;;;;N;;;;; -103B3;OLD PERSIAN SIGN FA;Lo;0;L;;;;;N;;;;; -103B4;OLD PERSIAN SIGN NA;Lo;0;L;;;;;N;;;;; -103B5;OLD PERSIAN SIGN NU;Lo;0;L;;;;;N;;;;; -103B6;OLD PERSIAN SIGN MA;Lo;0;L;;;;;N;;;;; -103B7;OLD PERSIAN SIGN MI;Lo;0;L;;;;;N;;;;; -103B8;OLD PERSIAN SIGN MU;Lo;0;L;;;;;N;;;;; -103B9;OLD PERSIAN SIGN YA;Lo;0;L;;;;;N;;;;; -103BA;OLD PERSIAN SIGN VA;Lo;0;L;;;;;N;;;;; -103BB;OLD PERSIAN SIGN VI;Lo;0;L;;;;;N;;;;; -103BC;OLD PERSIAN SIGN RA;Lo;0;L;;;;;N;;;;; -103BD;OLD PERSIAN SIGN RU;Lo;0;L;;;;;N;;;;; -103BE;OLD PERSIAN SIGN LA;Lo;0;L;;;;;N;;;;; -103BF;OLD PERSIAN SIGN SA;Lo;0;L;;;;;N;;;;; -103C0;OLD PERSIAN SIGN ZA;Lo;0;L;;;;;N;;;;; -103C1;OLD PERSIAN SIGN SHA;Lo;0;L;;;;;N;;;;; -103C2;OLD PERSIAN SIGN SSA;Lo;0;L;;;;;N;;;;; -103C3;OLD PERSIAN SIGN HA;Lo;0;L;;;;;N;;;;; -103C8;OLD PERSIAN SIGN AURAMAZDAA;Lo;0;L;;;;;N;;;;; -103C9;OLD PERSIAN SIGN AURAMAZDAA-2;Lo;0;L;;;;;N;;;;; -103CA;OLD PERSIAN SIGN AURAMAZDAAHA;Lo;0;L;;;;;N;;;;; -103CB;OLD PERSIAN SIGN XSHAAYATHIYA;Lo;0;L;;;;;N;;;;; -103CC;OLD PERSIAN SIGN DAHYAAUSH;Lo;0;L;;;;;N;;;;; -103CD;OLD PERSIAN SIGN DAHYAAUSH-2;Lo;0;L;;;;;N;;;;; -103CE;OLD PERSIAN SIGN BAGA;Lo;0;L;;;;;N;;;;; -103CF;OLD PERSIAN SIGN BUUMISH;Lo;0;L;;;;;N;;;;; -103D0;OLD PERSIAN WORD DIVIDER;Po;0;L;;;;;N;;;;; -103D1;OLD PERSIAN NUMBER ONE;Nl;0;L;;;;1;N;;;;; -103D2;OLD PERSIAN NUMBER TWO;Nl;0;L;;;;2;N;;;;; -103D3;OLD PERSIAN NUMBER TEN;Nl;0;L;;;;10;N;;;;; -103D4;OLD PERSIAN NUMBER TWENTY;Nl;0;L;;;;20;N;;;;; -103D5;OLD PERSIAN NUMBER HUNDRED;Nl;0;L;;;;100;N;;;;; -10400;DESERET CAPITAL LETTER LONG I;Lu;0;L;;;;;N;;;;10428; -10401;DESERET CAPITAL LETTER LONG E;Lu;0;L;;;;;N;;;;10429; -10402;DESERET CAPITAL LETTER LONG A;Lu;0;L;;;;;N;;;;1042A; -10403;DESERET CAPITAL LETTER LONG AH;Lu;0;L;;;;;N;;;;1042B; -10404;DESERET CAPITAL LETTER LONG O;Lu;0;L;;;;;N;;;;1042C; -10405;DESERET CAPITAL LETTER LONG OO;Lu;0;L;;;;;N;;;;1042D; -10406;DESERET CAPITAL LETTER SHORT I;Lu;0;L;;;;;N;;;;1042E; -10407;DESERET CAPITAL LETTER SHORT E;Lu;0;L;;;;;N;;;;1042F; -10408;DESERET CAPITAL LETTER SHORT A;Lu;0;L;;;;;N;;;;10430; -10409;DESERET CAPITAL LETTER SHORT AH;Lu;0;L;;;;;N;;;;10431; -1040A;DESERET CAPITAL LETTER SHORT O;Lu;0;L;;;;;N;;;;10432; -1040B;DESERET CAPITAL LETTER SHORT OO;Lu;0;L;;;;;N;;;;10433; -1040C;DESERET CAPITAL LETTER AY;Lu;0;L;;;;;N;;;;10434; -1040D;DESERET CAPITAL LETTER OW;Lu;0;L;;;;;N;;;;10435; -1040E;DESERET CAPITAL LETTER WU;Lu;0;L;;;;;N;;;;10436; -1040F;DESERET CAPITAL LETTER YEE;Lu;0;L;;;;;N;;;;10437; -10410;DESERET CAPITAL LETTER H;Lu;0;L;;;;;N;;;;10438; -10411;DESERET CAPITAL LETTER PEE;Lu;0;L;;;;;N;;;;10439; -10412;DESERET CAPITAL LETTER BEE;Lu;0;L;;;;;N;;;;1043A; -10413;DESERET CAPITAL LETTER TEE;Lu;0;L;;;;;N;;;;1043B; -10414;DESERET CAPITAL LETTER DEE;Lu;0;L;;;;;N;;;;1043C; -10415;DESERET CAPITAL LETTER CHEE;Lu;0;L;;;;;N;;;;1043D; -10416;DESERET CAPITAL LETTER JEE;Lu;0;L;;;;;N;;;;1043E; -10417;DESERET CAPITAL LETTER KAY;Lu;0;L;;;;;N;;;;1043F; -10418;DESERET CAPITAL LETTER GAY;Lu;0;L;;;;;N;;;;10440; -10419;DESERET CAPITAL LETTER EF;Lu;0;L;;;;;N;;;;10441; -1041A;DESERET CAPITAL LETTER VEE;Lu;0;L;;;;;N;;;;10442; -1041B;DESERET CAPITAL LETTER ETH;Lu;0;L;;;;;N;;;;10443; -1041C;DESERET CAPITAL LETTER THEE;Lu;0;L;;;;;N;;;;10444; -1041D;DESERET CAPITAL LETTER ES;Lu;0;L;;;;;N;;;;10445; -1041E;DESERET CAPITAL LETTER ZEE;Lu;0;L;;;;;N;;;;10446; -1041F;DESERET CAPITAL LETTER ESH;Lu;0;L;;;;;N;;;;10447; -10420;DESERET CAPITAL LETTER ZHEE;Lu;0;L;;;;;N;;;;10448; -10421;DESERET CAPITAL LETTER ER;Lu;0;L;;;;;N;;;;10449; -10422;DESERET CAPITAL LETTER EL;Lu;0;L;;;;;N;;;;1044A; -10423;DESERET CAPITAL LETTER EM;Lu;0;L;;;;;N;;;;1044B; -10424;DESERET CAPITAL LETTER EN;Lu;0;L;;;;;N;;;;1044C; -10425;DESERET CAPITAL LETTER ENG;Lu;0;L;;;;;N;;;;1044D; -10426;DESERET CAPITAL LETTER OI;Lu;0;L;;;;;N;;;;1044E; -10427;DESERET CAPITAL LETTER EW;Lu;0;L;;;;;N;;;;1044F; -10428;DESERET SMALL LETTER LONG I;Ll;0;L;;;;;N;;;10400;;10400 -10429;DESERET SMALL LETTER LONG E;Ll;0;L;;;;;N;;;10401;;10401 -1042A;DESERET SMALL LETTER LONG A;Ll;0;L;;;;;N;;;10402;;10402 -1042B;DESERET SMALL LETTER LONG AH;Ll;0;L;;;;;N;;;10403;;10403 -1042C;DESERET SMALL LETTER LONG O;Ll;0;L;;;;;N;;;10404;;10404 -1042D;DESERET SMALL LETTER LONG OO;Ll;0;L;;;;;N;;;10405;;10405 -1042E;DESERET SMALL LETTER SHORT I;Ll;0;L;;;;;N;;;10406;;10406 -1042F;DESERET SMALL LETTER SHORT E;Ll;0;L;;;;;N;;;10407;;10407 -10430;DESERET SMALL LETTER SHORT A;Ll;0;L;;;;;N;;;10408;;10408 -10431;DESERET SMALL LETTER SHORT AH;Ll;0;L;;;;;N;;;10409;;10409 -10432;DESERET SMALL LETTER SHORT O;Ll;0;L;;;;;N;;;1040A;;1040A -10433;DESERET SMALL LETTER SHORT OO;Ll;0;L;;;;;N;;;1040B;;1040B -10434;DESERET SMALL LETTER AY;Ll;0;L;;;;;N;;;1040C;;1040C -10435;DESERET SMALL LETTER OW;Ll;0;L;;;;;N;;;1040D;;1040D -10436;DESERET SMALL LETTER WU;Ll;0;L;;;;;N;;;1040E;;1040E -10437;DESERET SMALL LETTER YEE;Ll;0;L;;;;;N;;;1040F;;1040F -10438;DESERET SMALL LETTER H;Ll;0;L;;;;;N;;;10410;;10410 -10439;DESERET SMALL LETTER PEE;Ll;0;L;;;;;N;;;10411;;10411 -1043A;DESERET SMALL LETTER BEE;Ll;0;L;;;;;N;;;10412;;10412 -1043B;DESERET SMALL LETTER TEE;Ll;0;L;;;;;N;;;10413;;10413 -1043C;DESERET SMALL LETTER DEE;Ll;0;L;;;;;N;;;10414;;10414 -1043D;DESERET SMALL LETTER CHEE;Ll;0;L;;;;;N;;;10415;;10415 -1043E;DESERET SMALL LETTER JEE;Ll;0;L;;;;;N;;;10416;;10416 -1043F;DESERET SMALL LETTER KAY;Ll;0;L;;;;;N;;;10417;;10417 -10440;DESERET SMALL LETTER GAY;Ll;0;L;;;;;N;;;10418;;10418 -10441;DESERET SMALL LETTER EF;Ll;0;L;;;;;N;;;10419;;10419 -10442;DESERET SMALL LETTER VEE;Ll;0;L;;;;;N;;;1041A;;1041A -10443;DESERET SMALL LETTER ETH;Ll;0;L;;;;;N;;;1041B;;1041B -10444;DESERET SMALL LETTER THEE;Ll;0;L;;;;;N;;;1041C;;1041C -10445;DESERET SMALL LETTER ES;Ll;0;L;;;;;N;;;1041D;;1041D -10446;DESERET SMALL LETTER ZEE;Ll;0;L;;;;;N;;;1041E;;1041E -10447;DESERET SMALL LETTER ESH;Ll;0;L;;;;;N;;;1041F;;1041F -10448;DESERET SMALL LETTER ZHEE;Ll;0;L;;;;;N;;;10420;;10420 -10449;DESERET SMALL LETTER ER;Ll;0;L;;;;;N;;;10421;;10421 -1044A;DESERET SMALL LETTER EL;Ll;0;L;;;;;N;;;10422;;10422 -1044B;DESERET SMALL LETTER EM;Ll;0;L;;;;;N;;;10423;;10423 -1044C;DESERET SMALL LETTER EN;Ll;0;L;;;;;N;;;10424;;10424 -1044D;DESERET SMALL LETTER ENG;Ll;0;L;;;;;N;;;10425;;10425 -1044E;DESERET SMALL LETTER OI;Ll;0;L;;;;;N;;;10426;;10426 -1044F;DESERET SMALL LETTER EW;Ll;0;L;;;;;N;;;10427;;10427 -10450;SHAVIAN LETTER PEEP;Lo;0;L;;;;;N;;;;; -10451;SHAVIAN LETTER TOT;Lo;0;L;;;;;N;;;;; -10452;SHAVIAN LETTER KICK;Lo;0;L;;;;;N;;;;; -10453;SHAVIAN LETTER FEE;Lo;0;L;;;;;N;;;;; -10454;SHAVIAN LETTER THIGH;Lo;0;L;;;;;N;;;;; -10455;SHAVIAN LETTER SO;Lo;0;L;;;;;N;;;;; -10456;SHAVIAN LETTER SURE;Lo;0;L;;;;;N;;;;; -10457;SHAVIAN LETTER CHURCH;Lo;0;L;;;;;N;;;;; -10458;SHAVIAN LETTER YEA;Lo;0;L;;;;;N;;;;; -10459;SHAVIAN LETTER HUNG;Lo;0;L;;;;;N;;;;; -1045A;SHAVIAN LETTER BIB;Lo;0;L;;;;;N;;;;; -1045B;SHAVIAN LETTER DEAD;Lo;0;L;;;;;N;;;;; -1045C;SHAVIAN LETTER GAG;Lo;0;L;;;;;N;;;;; -1045D;SHAVIAN LETTER VOW;Lo;0;L;;;;;N;;;;; -1045E;SHAVIAN LETTER THEY;Lo;0;L;;;;;N;;;;; -1045F;SHAVIAN LETTER ZOO;Lo;0;L;;;;;N;;;;; -10460;SHAVIAN LETTER MEASURE;Lo;0;L;;;;;N;;;;; -10461;SHAVIAN LETTER JUDGE;Lo;0;L;;;;;N;;;;; -10462;SHAVIAN LETTER WOE;Lo;0;L;;;;;N;;;;; -10463;SHAVIAN LETTER HA-HA;Lo;0;L;;;;;N;;;;; -10464;SHAVIAN LETTER LOLL;Lo;0;L;;;;;N;;;;; -10465;SHAVIAN LETTER MIME;Lo;0;L;;;;;N;;;;; -10466;SHAVIAN LETTER IF;Lo;0;L;;;;;N;;;;; -10467;SHAVIAN LETTER EGG;Lo;0;L;;;;;N;;;;; -10468;SHAVIAN LETTER ASH;Lo;0;L;;;;;N;;;;; -10469;SHAVIAN LETTER ADO;Lo;0;L;;;;;N;;;;; -1046A;SHAVIAN LETTER ON;Lo;0;L;;;;;N;;;;; -1046B;SHAVIAN LETTER WOOL;Lo;0;L;;;;;N;;;;; -1046C;SHAVIAN LETTER OUT;Lo;0;L;;;;;N;;;;; -1046D;SHAVIAN LETTER AH;Lo;0;L;;;;;N;;;;; -1046E;SHAVIAN LETTER ROAR;Lo;0;L;;;;;N;;;;; -1046F;SHAVIAN LETTER NUN;Lo;0;L;;;;;N;;;;; -10470;SHAVIAN LETTER EAT;Lo;0;L;;;;;N;;;;; -10471;SHAVIAN LETTER AGE;Lo;0;L;;;;;N;;;;; -10472;SHAVIAN LETTER ICE;Lo;0;L;;;;;N;;;;; -10473;SHAVIAN LETTER UP;Lo;0;L;;;;;N;;;;; -10474;SHAVIAN LETTER OAK;Lo;0;L;;;;;N;;;;; -10475;SHAVIAN LETTER OOZE;Lo;0;L;;;;;N;;;;; -10476;SHAVIAN LETTER OIL;Lo;0;L;;;;;N;;;;; -10477;SHAVIAN LETTER AWE;Lo;0;L;;;;;N;;;;; -10478;SHAVIAN LETTER ARE;Lo;0;L;;;;;N;;;;; -10479;SHAVIAN LETTER OR;Lo;0;L;;;;;N;;;;; -1047A;SHAVIAN LETTER AIR;Lo;0;L;;;;;N;;;;; -1047B;SHAVIAN LETTER ERR;Lo;0;L;;;;;N;;;;; -1047C;SHAVIAN LETTER ARRAY;Lo;0;L;;;;;N;;;;; -1047D;SHAVIAN LETTER EAR;Lo;0;L;;;;;N;;;;; -1047E;SHAVIAN LETTER IAN;Lo;0;L;;;;;N;;;;; -1047F;SHAVIAN LETTER YEW;Lo;0;L;;;;;N;;;;; -10480;OSMANYA LETTER ALEF;Lo;0;L;;;;;N;;;;; -10481;OSMANYA LETTER BA;Lo;0;L;;;;;N;;;;; -10482;OSMANYA LETTER TA;Lo;0;L;;;;;N;;;;; -10483;OSMANYA LETTER JA;Lo;0;L;;;;;N;;;;; -10484;OSMANYA LETTER XA;Lo;0;L;;;;;N;;;;; -10485;OSMANYA LETTER KHA;Lo;0;L;;;;;N;;;;; -10486;OSMANYA LETTER DEEL;Lo;0;L;;;;;N;;;;; -10487;OSMANYA LETTER RA;Lo;0;L;;;;;N;;;;; -10488;OSMANYA LETTER SA;Lo;0;L;;;;;N;;;;; -10489;OSMANYA LETTER SHIIN;Lo;0;L;;;;;N;;;;; -1048A;OSMANYA LETTER DHA;Lo;0;L;;;;;N;;;;; -1048B;OSMANYA LETTER CAYN;Lo;0;L;;;;;N;;;;; -1048C;OSMANYA LETTER GA;Lo;0;L;;;;;N;;;;; -1048D;OSMANYA LETTER FA;Lo;0;L;;;;;N;;;;; -1048E;OSMANYA LETTER QAAF;Lo;0;L;;;;;N;;;;; -1048F;OSMANYA LETTER KAAF;Lo;0;L;;;;;N;;;;; -10490;OSMANYA LETTER LAAN;Lo;0;L;;;;;N;;;;; -10491;OSMANYA LETTER MIIN;Lo;0;L;;;;;N;;;;; -10492;OSMANYA LETTER NUUN;Lo;0;L;;;;;N;;;;; -10493;OSMANYA LETTER WAW;Lo;0;L;;;;;N;;;;; -10494;OSMANYA LETTER HA;Lo;0;L;;;;;N;;;;; -10495;OSMANYA LETTER YA;Lo;0;L;;;;;N;;;;; -10496;OSMANYA LETTER A;Lo;0;L;;;;;N;;;;; -10497;OSMANYA LETTER E;Lo;0;L;;;;;N;;;;; -10498;OSMANYA LETTER I;Lo;0;L;;;;;N;;;;; -10499;OSMANYA LETTER O;Lo;0;L;;;;;N;;;;; -1049A;OSMANYA LETTER U;Lo;0;L;;;;;N;;;;; -1049B;OSMANYA LETTER AA;Lo;0;L;;;;;N;;;;; -1049C;OSMANYA LETTER EE;Lo;0;L;;;;;N;;;;; -1049D;OSMANYA LETTER OO;Lo;0;L;;;;;N;;;;; -104A0;OSMANYA DIGIT ZERO;Nd;0;L;;0;0;0;N;;;;; -104A1;OSMANYA DIGIT ONE;Nd;0;L;;1;1;1;N;;;;; -104A2;OSMANYA DIGIT TWO;Nd;0;L;;2;2;2;N;;;;; -104A3;OSMANYA DIGIT THREE;Nd;0;L;;3;3;3;N;;;;; -104A4;OSMANYA DIGIT FOUR;Nd;0;L;;4;4;4;N;;;;; -104A5;OSMANYA DIGIT FIVE;Nd;0;L;;5;5;5;N;;;;; -104A6;OSMANYA DIGIT SIX;Nd;0;L;;6;6;6;N;;;;; -104A7;OSMANYA DIGIT SEVEN;Nd;0;L;;7;7;7;N;;;;; -104A8;OSMANYA DIGIT EIGHT;Nd;0;L;;8;8;8;N;;;;; -104A9;OSMANYA DIGIT NINE;Nd;0;L;;9;9;9;N;;;;; -10800;CYPRIOT SYLLABLE A;Lo;0;R;;;;;N;;;;; -10801;CYPRIOT SYLLABLE E;Lo;0;R;;;;;N;;;;; -10802;CYPRIOT SYLLABLE I;Lo;0;R;;;;;N;;;;; -10803;CYPRIOT SYLLABLE O;Lo;0;R;;;;;N;;;;; -10804;CYPRIOT SYLLABLE U;Lo;0;R;;;;;N;;;;; -10805;CYPRIOT SYLLABLE JA;Lo;0;R;;;;;N;;;;; -10808;CYPRIOT SYLLABLE JO;Lo;0;R;;;;;N;;;;; -1080A;CYPRIOT SYLLABLE KA;Lo;0;R;;;;;N;;;;; -1080B;CYPRIOT SYLLABLE KE;Lo;0;R;;;;;N;;;;; -1080C;CYPRIOT SYLLABLE KI;Lo;0;R;;;;;N;;;;; -1080D;CYPRIOT SYLLABLE KO;Lo;0;R;;;;;N;;;;; -1080E;CYPRIOT SYLLABLE KU;Lo;0;R;;;;;N;;;;; -1080F;CYPRIOT SYLLABLE LA;Lo;0;R;;;;;N;;;;; -10810;CYPRIOT SYLLABLE LE;Lo;0;R;;;;;N;;;;; -10811;CYPRIOT SYLLABLE LI;Lo;0;R;;;;;N;;;;; -10812;CYPRIOT SYLLABLE LO;Lo;0;R;;;;;N;;;;; -10813;CYPRIOT SYLLABLE LU;Lo;0;R;;;;;N;;;;; -10814;CYPRIOT SYLLABLE MA;Lo;0;R;;;;;N;;;;; -10815;CYPRIOT SYLLABLE ME;Lo;0;R;;;;;N;;;;; -10816;CYPRIOT SYLLABLE MI;Lo;0;R;;;;;N;;;;; -10817;CYPRIOT SYLLABLE MO;Lo;0;R;;;;;N;;;;; -10818;CYPRIOT SYLLABLE MU;Lo;0;R;;;;;N;;;;; -10819;CYPRIOT SYLLABLE NA;Lo;0;R;;;;;N;;;;; -1081A;CYPRIOT SYLLABLE NE;Lo;0;R;;;;;N;;;;; -1081B;CYPRIOT SYLLABLE NI;Lo;0;R;;;;;N;;;;; -1081C;CYPRIOT SYLLABLE NO;Lo;0;R;;;;;N;;;;; -1081D;CYPRIOT SYLLABLE NU;Lo;0;R;;;;;N;;;;; -1081E;CYPRIOT SYLLABLE PA;Lo;0;R;;;;;N;;;;; -1081F;CYPRIOT SYLLABLE PE;Lo;0;R;;;;;N;;;;; -10820;CYPRIOT SYLLABLE PI;Lo;0;R;;;;;N;;;;; -10821;CYPRIOT SYLLABLE PO;Lo;0;R;;;;;N;;;;; -10822;CYPRIOT SYLLABLE PU;Lo;0;R;;;;;N;;;;; -10823;CYPRIOT SYLLABLE RA;Lo;0;R;;;;;N;;;;; -10824;CYPRIOT SYLLABLE RE;Lo;0;R;;;;;N;;;;; -10825;CYPRIOT SYLLABLE RI;Lo;0;R;;;;;N;;;;; -10826;CYPRIOT SYLLABLE RO;Lo;0;R;;;;;N;;;;; -10827;CYPRIOT SYLLABLE RU;Lo;0;R;;;;;N;;;;; -10828;CYPRIOT SYLLABLE SA;Lo;0;R;;;;;N;;;;; -10829;CYPRIOT SYLLABLE SE;Lo;0;R;;;;;N;;;;; -1082A;CYPRIOT SYLLABLE SI;Lo;0;R;;;;;N;;;;; -1082B;CYPRIOT SYLLABLE SO;Lo;0;R;;;;;N;;;;; -1082C;CYPRIOT SYLLABLE SU;Lo;0;R;;;;;N;;;;; -1082D;CYPRIOT SYLLABLE TA;Lo;0;R;;;;;N;;;;; -1082E;CYPRIOT SYLLABLE TE;Lo;0;R;;;;;N;;;;; -1082F;CYPRIOT SYLLABLE TI;Lo;0;R;;;;;N;;;;; -10830;CYPRIOT SYLLABLE TO;Lo;0;R;;;;;N;;;;; -10831;CYPRIOT SYLLABLE TU;Lo;0;R;;;;;N;;;;; -10832;CYPRIOT SYLLABLE WA;Lo;0;R;;;;;N;;;;; -10833;CYPRIOT SYLLABLE WE;Lo;0;R;;;;;N;;;;; -10834;CYPRIOT SYLLABLE WI;Lo;0;R;;;;;N;;;;; -10835;CYPRIOT SYLLABLE WO;Lo;0;R;;;;;N;;;;; -10837;CYPRIOT SYLLABLE XA;Lo;0;R;;;;;N;;;;; -10838;CYPRIOT SYLLABLE XE;Lo;0;R;;;;;N;;;;; -1083C;CYPRIOT SYLLABLE ZA;Lo;0;R;;;;;N;;;;; -1083F;CYPRIOT SYLLABLE ZO;Lo;0;R;;;;;N;;;;; -10900;PHOENICIAN LETTER ALF;Lo;0;R;;;;;N;;;;; -10901;PHOENICIAN LETTER BET;Lo;0;R;;;;;N;;;;; -10902;PHOENICIAN LETTER GAML;Lo;0;R;;;;;N;;;;; -10903;PHOENICIAN LETTER DELT;Lo;0;R;;;;;N;;;;; -10904;PHOENICIAN LETTER HE;Lo;0;R;;;;;N;;;;; -10905;PHOENICIAN LETTER WAU;Lo;0;R;;;;;N;;;;; -10906;PHOENICIAN LETTER ZAI;Lo;0;R;;;;;N;;;;; -10907;PHOENICIAN LETTER HET;Lo;0;R;;;;;N;;;;; -10908;PHOENICIAN LETTER TET;Lo;0;R;;;;;N;;;;; -10909;PHOENICIAN LETTER YOD;Lo;0;R;;;;;N;;;;; -1090A;PHOENICIAN LETTER KAF;Lo;0;R;;;;;N;;;;; -1090B;PHOENICIAN LETTER LAMD;Lo;0;R;;;;;N;;;;; -1090C;PHOENICIAN LETTER MEM;Lo;0;R;;;;;N;;;;; -1090D;PHOENICIAN LETTER NUN;Lo;0;R;;;;;N;;;;; -1090E;PHOENICIAN LETTER SEMK;Lo;0;R;;;;;N;;;;; -1090F;PHOENICIAN LETTER AIN;Lo;0;R;;;;;N;;;;; -10910;PHOENICIAN LETTER PE;Lo;0;R;;;;;N;;;;; -10911;PHOENICIAN LETTER SADE;Lo;0;R;;;;;N;;;;; -10912;PHOENICIAN LETTER QOF;Lo;0;R;;;;;N;;;;; -10913;PHOENICIAN LETTER ROSH;Lo;0;R;;;;;N;;;;; -10914;PHOENICIAN LETTER SHIN;Lo;0;R;;;;;N;;;;; -10915;PHOENICIAN LETTER TAU;Lo;0;R;;;;;N;;;;; -10916;PHOENICIAN NUMBER ONE;No;0;R;;;;1;N;;;;; -10917;PHOENICIAN NUMBER TEN;No;0;R;;;;10;N;;;;; -10918;PHOENICIAN NUMBER TWENTY;No;0;R;;;;20;N;;;;; -10919;PHOENICIAN NUMBER ONE HUNDRED;No;0;R;;;;100;N;;;;; -1091F;PHOENICIAN WORD SEPARATOR;Po;0;ON;;;;;N;;;;; -10920;LYDIAN LETTER A;Lo;0;R;;;;;N;;;;; -10921;LYDIAN LETTER B;Lo;0;R;;;;;N;;;;; -10922;LYDIAN LETTER G;Lo;0;R;;;;;N;;;;; -10923;LYDIAN LETTER D;Lo;0;R;;;;;N;;;;; -10924;LYDIAN LETTER E;Lo;0;R;;;;;N;;;;; -10925;LYDIAN LETTER V;Lo;0;R;;;;;N;;;;; -10926;LYDIAN LETTER I;Lo;0;R;;;;;N;;;;; -10927;LYDIAN LETTER Y;Lo;0;R;;;;;N;;;;; -10928;LYDIAN LETTER K;Lo;0;R;;;;;N;;;;; -10929;LYDIAN LETTER L;Lo;0;R;;;;;N;;;;; -1092A;LYDIAN LETTER M;Lo;0;R;;;;;N;;;;; -1092B;LYDIAN LETTER N;Lo;0;R;;;;;N;;;;; -1092C;LYDIAN LETTER O;Lo;0;R;;;;;N;;;;; -1092D;LYDIAN LETTER R;Lo;0;R;;;;;N;;;;; -1092E;LYDIAN LETTER SS;Lo;0;R;;;;;N;;;;; -1092F;LYDIAN LETTER T;Lo;0;R;;;;;N;;;;; -10930;LYDIAN LETTER U;Lo;0;R;;;;;N;;;;; -10931;LYDIAN LETTER F;Lo;0;R;;;;;N;;;;; -10932;LYDIAN LETTER Q;Lo;0;R;;;;;N;;;;; -10933;LYDIAN LETTER S;Lo;0;R;;;;;N;;;;; -10934;LYDIAN LETTER TT;Lo;0;R;;;;;N;;;;; -10935;LYDIAN LETTER AN;Lo;0;R;;;;;N;;;;; -10936;LYDIAN LETTER EN;Lo;0;R;;;;;N;;;;; -10937;LYDIAN LETTER LY;Lo;0;R;;;;;N;;;;; -10938;LYDIAN LETTER NN;Lo;0;R;;;;;N;;;;; -10939;LYDIAN LETTER C;Lo;0;R;;;;;N;;;;; -1093F;LYDIAN TRIANGULAR MARK;Po;0;R;;;;;N;;;;; -10A00;KHAROSHTHI LETTER A;Lo;0;R;;;;;N;;;;; -10A01;KHAROSHTHI VOWEL SIGN I;Mn;0;NSM;;;;;N;;;;; -10A02;KHAROSHTHI VOWEL SIGN U;Mn;0;NSM;;;;;N;;;;; -10A03;KHAROSHTHI VOWEL SIGN VOCALIC R;Mn;0;NSM;;;;;N;;;;; -10A05;KHAROSHTHI VOWEL SIGN E;Mn;0;NSM;;;;;N;;;;; -10A06;KHAROSHTHI VOWEL SIGN O;Mn;0;NSM;;;;;N;;;;; -10A0C;KHAROSHTHI VOWEL LENGTH MARK;Mn;0;NSM;;;;;N;;;;; -10A0D;KHAROSHTHI SIGN DOUBLE RING BELOW;Mn;220;NSM;;;;;N;;;;; -10A0E;KHAROSHTHI SIGN ANUSVARA;Mn;0;NSM;;;;;N;;;;; -10A0F;KHAROSHTHI SIGN VISARGA;Mn;230;NSM;;;;;N;;;;; -10A10;KHAROSHTHI LETTER KA;Lo;0;R;;;;;N;;;;; -10A11;KHAROSHTHI LETTER KHA;Lo;0;R;;;;;N;;;;; -10A12;KHAROSHTHI LETTER GA;Lo;0;R;;;;;N;;;;; -10A13;KHAROSHTHI LETTER GHA;Lo;0;R;;;;;N;;;;; -10A15;KHAROSHTHI LETTER CA;Lo;0;R;;;;;N;;;;; -10A16;KHAROSHTHI LETTER CHA;Lo;0;R;;;;;N;;;;; -10A17;KHAROSHTHI LETTER JA;Lo;0;R;;;;;N;;;;; -10A19;KHAROSHTHI LETTER NYA;Lo;0;R;;;;;N;;;;; -10A1A;KHAROSHTHI LETTER TTA;Lo;0;R;;;;;N;;;;; -10A1B;KHAROSHTHI LETTER TTHA;Lo;0;R;;;;;N;;;;; -10A1C;KHAROSHTHI LETTER DDA;Lo;0;R;;;;;N;;;;; -10A1D;KHAROSHTHI LETTER DDHA;Lo;0;R;;;;;N;;;;; -10A1E;KHAROSHTHI LETTER NNA;Lo;0;R;;;;;N;;;;; -10A1F;KHAROSHTHI LETTER TA;Lo;0;R;;;;;N;;;;; -10A20;KHAROSHTHI LETTER THA;Lo;0;R;;;;;N;;;;; -10A21;KHAROSHTHI LETTER DA;Lo;0;R;;;;;N;;;;; -10A22;KHAROSHTHI LETTER DHA;Lo;0;R;;;;;N;;;;; -10A23;KHAROSHTHI LETTER NA;Lo;0;R;;;;;N;;;;; -10A24;KHAROSHTHI LETTER PA;Lo;0;R;;;;;N;;;;; -10A25;KHAROSHTHI LETTER PHA;Lo;0;R;;;;;N;;;;; -10A26;KHAROSHTHI LETTER BA;Lo;0;R;;;;;N;;;;; -10A27;KHAROSHTHI LETTER BHA;Lo;0;R;;;;;N;;;;; -10A28;KHAROSHTHI LETTER MA;Lo;0;R;;;;;N;;;;; -10A29;KHAROSHTHI LETTER YA;Lo;0;R;;;;;N;;;;; -10A2A;KHAROSHTHI LETTER RA;Lo;0;R;;;;;N;;;;; -10A2B;KHAROSHTHI LETTER LA;Lo;0;R;;;;;N;;;;; -10A2C;KHAROSHTHI LETTER VA;Lo;0;R;;;;;N;;;;; -10A2D;KHAROSHTHI LETTER SHA;Lo;0;R;;;;;N;;;;; -10A2E;KHAROSHTHI LETTER SSA;Lo;0;R;;;;;N;;;;; -10A2F;KHAROSHTHI LETTER SA;Lo;0;R;;;;;N;;;;; -10A30;KHAROSHTHI LETTER ZA;Lo;0;R;;;;;N;;;;; -10A31;KHAROSHTHI LETTER HA;Lo;0;R;;;;;N;;;;; -10A32;KHAROSHTHI LETTER KKA;Lo;0;R;;;;;N;;;;; -10A33;KHAROSHTHI LETTER TTTHA;Lo;0;R;;;;;N;;;;; -10A38;KHAROSHTHI SIGN BAR ABOVE;Mn;230;NSM;;;;;N;;;;; -10A39;KHAROSHTHI SIGN CAUDA;Mn;1;NSM;;;;;N;;;;; -10A3A;KHAROSHTHI SIGN DOT BELOW;Mn;220;NSM;;;;;N;;;;; -10A3F;KHAROSHTHI VIRAMA;Mn;9;NSM;;;;;N;;;;; -10A40;KHAROSHTHI DIGIT ONE;No;0;R;;;1;1;N;;;;; -10A41;KHAROSHTHI DIGIT TWO;No;0;R;;;2;2;N;;;;; -10A42;KHAROSHTHI DIGIT THREE;No;0;R;;;3;3;N;;;;; -10A43;KHAROSHTHI DIGIT FOUR;No;0;R;;;4;4;N;;;;; -10A44;KHAROSHTHI NUMBER TEN;No;0;R;;;;10;N;;;;; -10A45;KHAROSHTHI NUMBER TWENTY;No;0;R;;;;20;N;;;;; -10A46;KHAROSHTHI NUMBER ONE HUNDRED;No;0;R;;;;100;N;;;;; -10A47;KHAROSHTHI NUMBER ONE THOUSAND;No;0;R;;;;1000;N;;;;; -10A50;KHAROSHTHI PUNCTUATION DOT;Po;0;R;;;;;N;;;;; -10A51;KHAROSHTHI PUNCTUATION SMALL CIRCLE;Po;0;R;;;;;N;;;;; -10A52;KHAROSHTHI PUNCTUATION CIRCLE;Po;0;R;;;;;N;;;;; -10A53;KHAROSHTHI PUNCTUATION CRESCENT BAR;Po;0;R;;;;;N;;;;; -10A54;KHAROSHTHI PUNCTUATION MANGALAM;Po;0;R;;;;;N;;;;; -10A55;KHAROSHTHI PUNCTUATION LOTUS;Po;0;R;;;;;N;;;;; -10A56;KHAROSHTHI PUNCTUATION DANDA;Po;0;R;;;;;N;;;;; -10A57;KHAROSHTHI PUNCTUATION DOUBLE DANDA;Po;0;R;;;;;N;;;;; -10A58;KHAROSHTHI PUNCTUATION LINES;Po;0;R;;;;;N;;;;; -12000;CUNEIFORM SIGN A;Lo;0;L;;;;;N;;;;; -12001;CUNEIFORM SIGN A TIMES A;Lo;0;L;;;;;N;;;;; -12002;CUNEIFORM SIGN A TIMES BAD;Lo;0;L;;;;;N;;;;; -12003;CUNEIFORM SIGN A TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -12004;CUNEIFORM SIGN A TIMES HA;Lo;0;L;;;;;N;;;;; -12005;CUNEIFORM SIGN A TIMES IGI;Lo;0;L;;;;;N;;;;; -12006;CUNEIFORM SIGN A TIMES LAGAR GUNU;Lo;0;L;;;;;N;;;;; -12007;CUNEIFORM SIGN A TIMES MUSH;Lo;0;L;;;;;N;;;;; -12008;CUNEIFORM SIGN A TIMES SAG;Lo;0;L;;;;;N;;;;; -12009;CUNEIFORM SIGN A2;Lo;0;L;;;;;N;;;;; -1200A;CUNEIFORM SIGN AB;Lo;0;L;;;;;N;;;;; -1200B;CUNEIFORM SIGN AB TIMES ASH2;Lo;0;L;;;;;N;;;;; -1200C;CUNEIFORM SIGN AB TIMES DUN3 GUNU;Lo;0;L;;;;;N;;;;; -1200D;CUNEIFORM SIGN AB TIMES GAL;Lo;0;L;;;;;N;;;;; -1200E;CUNEIFORM SIGN AB TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -1200F;CUNEIFORM SIGN AB TIMES HA;Lo;0;L;;;;;N;;;;; -12010;CUNEIFORM SIGN AB TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -12011;CUNEIFORM SIGN AB TIMES IMIN;Lo;0;L;;;;;N;;;;; -12012;CUNEIFORM SIGN AB TIMES LAGAB;Lo;0;L;;;;;N;;;;; -12013;CUNEIFORM SIGN AB TIMES SHESH;Lo;0;L;;;;;N;;;;; -12014;CUNEIFORM SIGN AB TIMES U PLUS U PLUS U;Lo;0;L;;;;;N;;;;; -12015;CUNEIFORM SIGN AB GUNU;Lo;0;L;;;;;N;;;;; -12016;CUNEIFORM SIGN AB2;Lo;0;L;;;;;N;;;;; -12017;CUNEIFORM SIGN AB2 TIMES BALAG;Lo;0;L;;;;;N;;;;; -12018;CUNEIFORM SIGN AB2 TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -12019;CUNEIFORM SIGN AB2 TIMES ME PLUS EN;Lo;0;L;;;;;N;;;;; -1201A;CUNEIFORM SIGN AB2 TIMES SHA3;Lo;0;L;;;;;N;;;;; -1201B;CUNEIFORM SIGN AB2 TIMES TAK4;Lo;0;L;;;;;N;;;;; -1201C;CUNEIFORM SIGN AD;Lo;0;L;;;;;N;;;;; -1201D;CUNEIFORM SIGN AK;Lo;0;L;;;;;N;;;;; -1201E;CUNEIFORM SIGN AK TIMES ERIN2;Lo;0;L;;;;;N;;;;; -1201F;CUNEIFORM SIGN AK TIMES SHITA PLUS GISH;Lo;0;L;;;;;N;;;;; -12020;CUNEIFORM SIGN AL;Lo;0;L;;;;;N;;;;; -12021;CUNEIFORM SIGN AL TIMES AL;Lo;0;L;;;;;N;;;;; -12022;CUNEIFORM SIGN AL TIMES DIM2;Lo;0;L;;;;;N;;;;; -12023;CUNEIFORM SIGN AL TIMES GISH;Lo;0;L;;;;;N;;;;; -12024;CUNEIFORM SIGN AL TIMES HA;Lo;0;L;;;;;N;;;;; -12025;CUNEIFORM SIGN AL TIMES KAD3;Lo;0;L;;;;;N;;;;; -12026;CUNEIFORM SIGN AL TIMES KI;Lo;0;L;;;;;N;;;;; -12027;CUNEIFORM SIGN AL TIMES SHE;Lo;0;L;;;;;N;;;;; -12028;CUNEIFORM SIGN AL TIMES USH;Lo;0;L;;;;;N;;;;; -12029;CUNEIFORM SIGN ALAN;Lo;0;L;;;;;N;;;;; -1202A;CUNEIFORM SIGN ALEPH;Lo;0;L;;;;;N;;;;; -1202B;CUNEIFORM SIGN AMAR;Lo;0;L;;;;;N;;;;; -1202C;CUNEIFORM SIGN AMAR TIMES SHE;Lo;0;L;;;;;N;;;;; -1202D;CUNEIFORM SIGN AN;Lo;0;L;;;;;N;;;;; -1202E;CUNEIFORM SIGN AN OVER AN;Lo;0;L;;;;;N;;;;; -1202F;CUNEIFORM SIGN AN THREE TIMES;Lo;0;L;;;;;N;;;;; -12030;CUNEIFORM SIGN AN PLUS NAGA OPPOSING AN PLUS NAGA;Lo;0;L;;;;;N;;;;; -12031;CUNEIFORM SIGN AN PLUS NAGA SQUARED;Lo;0;L;;;;;N;;;;; -12032;CUNEIFORM SIGN ANSHE;Lo;0;L;;;;;N;;;;; -12033;CUNEIFORM SIGN APIN;Lo;0;L;;;;;N;;;;; -12034;CUNEIFORM SIGN ARAD;Lo;0;L;;;;;N;;;;; -12035;CUNEIFORM SIGN ARAD TIMES KUR;Lo;0;L;;;;;N;;;;; -12036;CUNEIFORM SIGN ARKAB;Lo;0;L;;;;;N;;;;; -12037;CUNEIFORM SIGN ASAL2;Lo;0;L;;;;;N;;;;; -12038;CUNEIFORM SIGN ASH;Lo;0;L;;;;;N;;;;; -12039;CUNEIFORM SIGN ASH ZIDA TENU;Lo;0;L;;;;;N;;;;; -1203A;CUNEIFORM SIGN ASH KABA TENU;Lo;0;L;;;;;N;;;;; -1203B;CUNEIFORM SIGN ASH OVER ASH TUG2 OVER TUG2 TUG2 OVER TUG2 PAP;Lo;0;L;;;;;N;;;;; -1203C;CUNEIFORM SIGN ASH OVER ASH OVER ASH;Lo;0;L;;;;;N;;;;; -1203D;CUNEIFORM SIGN ASH OVER ASH OVER ASH CROSSING ASH OVER ASH OVER ASH;Lo;0;L;;;;;N;;;;; -1203E;CUNEIFORM SIGN ASH2;Lo;0;L;;;;;N;;;;; -1203F;CUNEIFORM SIGN ASHGAB;Lo;0;L;;;;;N;;;;; -12040;CUNEIFORM SIGN BA;Lo;0;L;;;;;N;;;;; -12041;CUNEIFORM SIGN BAD;Lo;0;L;;;;;N;;;;; -12042;CUNEIFORM SIGN BAG3;Lo;0;L;;;;;N;;;;; -12043;CUNEIFORM SIGN BAHAR2;Lo;0;L;;;;;N;;;;; -12044;CUNEIFORM SIGN BAL;Lo;0;L;;;;;N;;;;; -12045;CUNEIFORM SIGN BAL OVER BAL;Lo;0;L;;;;;N;;;;; -12046;CUNEIFORM SIGN BALAG;Lo;0;L;;;;;N;;;;; -12047;CUNEIFORM SIGN BAR;Lo;0;L;;;;;N;;;;; -12048;CUNEIFORM SIGN BARA2;Lo;0;L;;;;;N;;;;; -12049;CUNEIFORM SIGN BI;Lo;0;L;;;;;N;;;;; -1204A;CUNEIFORM SIGN BI TIMES A;Lo;0;L;;;;;N;;;;; -1204B;CUNEIFORM SIGN BI TIMES GAR;Lo;0;L;;;;;N;;;;; -1204C;CUNEIFORM SIGN BI TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -1204D;CUNEIFORM SIGN BU;Lo;0;L;;;;;N;;;;; -1204E;CUNEIFORM SIGN BU OVER BU AB;Lo;0;L;;;;;N;;;;; -1204F;CUNEIFORM SIGN BU OVER BU UN;Lo;0;L;;;;;N;;;;; -12050;CUNEIFORM SIGN BU CROSSING BU;Lo;0;L;;;;;N;;;;; -12051;CUNEIFORM SIGN BULUG;Lo;0;L;;;;;N;;;;; -12052;CUNEIFORM SIGN BULUG OVER BULUG;Lo;0;L;;;;;N;;;;; -12053;CUNEIFORM SIGN BUR;Lo;0;L;;;;;N;;;;; -12054;CUNEIFORM SIGN BUR2;Lo;0;L;;;;;N;;;;; -12055;CUNEIFORM SIGN DA;Lo;0;L;;;;;N;;;;; -12056;CUNEIFORM SIGN DAG;Lo;0;L;;;;;N;;;;; -12057;CUNEIFORM SIGN DAG KISIM5 TIMES A PLUS MASH;Lo;0;L;;;;;N;;;;; -12058;CUNEIFORM SIGN DAG KISIM5 TIMES AMAR;Lo;0;L;;;;;N;;;;; -12059;CUNEIFORM SIGN DAG KISIM5 TIMES BALAG;Lo;0;L;;;;;N;;;;; -1205A;CUNEIFORM SIGN DAG KISIM5 TIMES BI;Lo;0;L;;;;;N;;;;; -1205B;CUNEIFORM SIGN DAG KISIM5 TIMES GA;Lo;0;L;;;;;N;;;;; -1205C;CUNEIFORM SIGN DAG KISIM5 TIMES GA PLUS MASH;Lo;0;L;;;;;N;;;;; -1205D;CUNEIFORM SIGN DAG KISIM5 TIMES GI;Lo;0;L;;;;;N;;;;; -1205E;CUNEIFORM SIGN DAG KISIM5 TIMES GIR2;Lo;0;L;;;;;N;;;;; -1205F;CUNEIFORM SIGN DAG KISIM5 TIMES GUD;Lo;0;L;;;;;N;;;;; -12060;CUNEIFORM SIGN DAG KISIM5 TIMES HA;Lo;0;L;;;;;N;;;;; -12061;CUNEIFORM SIGN DAG KISIM5 TIMES IR;Lo;0;L;;;;;N;;;;; -12062;CUNEIFORM SIGN DAG KISIM5 TIMES IR PLUS LU;Lo;0;L;;;;;N;;;;; -12063;CUNEIFORM SIGN DAG KISIM5 TIMES KAK;Lo;0;L;;;;;N;;;;; -12064;CUNEIFORM SIGN DAG KISIM5 TIMES LA;Lo;0;L;;;;;N;;;;; -12065;CUNEIFORM SIGN DAG KISIM5 TIMES LU;Lo;0;L;;;;;N;;;;; -12066;CUNEIFORM SIGN DAG KISIM5 TIMES LU PLUS MASH2;Lo;0;L;;;;;N;;;;; -12067;CUNEIFORM SIGN DAG KISIM5 TIMES LUM;Lo;0;L;;;;;N;;;;; -12068;CUNEIFORM SIGN DAG KISIM5 TIMES NE;Lo;0;L;;;;;N;;;;; -12069;CUNEIFORM SIGN DAG KISIM5 TIMES PAP PLUS PAP;Lo;0;L;;;;;N;;;;; -1206A;CUNEIFORM SIGN DAG KISIM5 TIMES SI;Lo;0;L;;;;;N;;;;; -1206B;CUNEIFORM SIGN DAG KISIM5 TIMES TAK4;Lo;0;L;;;;;N;;;;; -1206C;CUNEIFORM SIGN DAG KISIM5 TIMES U2 PLUS GIR2;Lo;0;L;;;;;N;;;;; -1206D;CUNEIFORM SIGN DAG KISIM5 TIMES USH;Lo;0;L;;;;;N;;;;; -1206E;CUNEIFORM SIGN DAM;Lo;0;L;;;;;N;;;;; -1206F;CUNEIFORM SIGN DAR;Lo;0;L;;;;;N;;;;; -12070;CUNEIFORM SIGN DARA3;Lo;0;L;;;;;N;;;;; -12071;CUNEIFORM SIGN DARA4;Lo;0;L;;;;;N;;;;; -12072;CUNEIFORM SIGN DI;Lo;0;L;;;;;N;;;;; -12073;CUNEIFORM SIGN DIB;Lo;0;L;;;;;N;;;;; -12074;CUNEIFORM SIGN DIM;Lo;0;L;;;;;N;;;;; -12075;CUNEIFORM SIGN DIM TIMES SHE;Lo;0;L;;;;;N;;;;; -12076;CUNEIFORM SIGN DIM2;Lo;0;L;;;;;N;;;;; -12077;CUNEIFORM SIGN DIN;Lo;0;L;;;;;N;;;;; -12078;CUNEIFORM SIGN DIN KASKAL U GUNU DISH;Lo;0;L;;;;;N;;;;; -12079;CUNEIFORM SIGN DISH;Lo;0;L;;;;;N;;;;; -1207A;CUNEIFORM SIGN DU;Lo;0;L;;;;;N;;;;; -1207B;CUNEIFORM SIGN DU OVER DU;Lo;0;L;;;;;N;;;;; -1207C;CUNEIFORM SIGN DU GUNU;Lo;0;L;;;;;N;;;;; -1207D;CUNEIFORM SIGN DU SHESHIG;Lo;0;L;;;;;N;;;;; -1207E;CUNEIFORM SIGN DUB;Lo;0;L;;;;;N;;;;; -1207F;CUNEIFORM SIGN DUB TIMES ESH2;Lo;0;L;;;;;N;;;;; -12080;CUNEIFORM SIGN DUB2;Lo;0;L;;;;;N;;;;; -12081;CUNEIFORM SIGN DUG;Lo;0;L;;;;;N;;;;; -12082;CUNEIFORM SIGN DUGUD;Lo;0;L;;;;;N;;;;; -12083;CUNEIFORM SIGN DUH;Lo;0;L;;;;;N;;;;; -12084;CUNEIFORM SIGN DUN;Lo;0;L;;;;;N;;;;; -12085;CUNEIFORM SIGN DUN3;Lo;0;L;;;;;N;;;;; -12086;CUNEIFORM SIGN DUN3 GUNU;Lo;0;L;;;;;N;;;;; -12087;CUNEIFORM SIGN DUN3 GUNU GUNU;Lo;0;L;;;;;N;;;;; -12088;CUNEIFORM SIGN DUN4;Lo;0;L;;;;;N;;;;; -12089;CUNEIFORM SIGN DUR2;Lo;0;L;;;;;N;;;;; -1208A;CUNEIFORM SIGN E;Lo;0;L;;;;;N;;;;; -1208B;CUNEIFORM SIGN E TIMES PAP;Lo;0;L;;;;;N;;;;; -1208C;CUNEIFORM SIGN E OVER E NUN OVER NUN;Lo;0;L;;;;;N;;;;; -1208D;CUNEIFORM SIGN E2;Lo;0;L;;;;;N;;;;; -1208E;CUNEIFORM SIGN E2 TIMES A PLUS HA PLUS DA;Lo;0;L;;;;;N;;;;; -1208F;CUNEIFORM SIGN E2 TIMES GAR;Lo;0;L;;;;;N;;;;; -12090;CUNEIFORM SIGN E2 TIMES MI;Lo;0;L;;;;;N;;;;; -12091;CUNEIFORM SIGN E2 TIMES SAL;Lo;0;L;;;;;N;;;;; -12092;CUNEIFORM SIGN E2 TIMES SHE;Lo;0;L;;;;;N;;;;; -12093;CUNEIFORM SIGN E2 TIMES U;Lo;0;L;;;;;N;;;;; -12094;CUNEIFORM SIGN EDIN;Lo;0;L;;;;;N;;;;; -12095;CUNEIFORM SIGN EGIR;Lo;0;L;;;;;N;;;;; -12096;CUNEIFORM SIGN EL;Lo;0;L;;;;;N;;;;; -12097;CUNEIFORM SIGN EN;Lo;0;L;;;;;N;;;;; -12098;CUNEIFORM SIGN EN TIMES GAN2;Lo;0;L;;;;;N;;;;; -12099;CUNEIFORM SIGN EN TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -1209A;CUNEIFORM SIGN EN TIMES ME;Lo;0;L;;;;;N;;;;; -1209B;CUNEIFORM SIGN EN CROSSING EN;Lo;0;L;;;;;N;;;;; -1209C;CUNEIFORM SIGN EN OPPOSING EN;Lo;0;L;;;;;N;;;;; -1209D;CUNEIFORM SIGN EN SQUARED;Lo;0;L;;;;;N;;;;; -1209E;CUNEIFORM SIGN EREN;Lo;0;L;;;;;N;;;;; -1209F;CUNEIFORM SIGN ERIN2;Lo;0;L;;;;;N;;;;; -120A0;CUNEIFORM SIGN ESH2;Lo;0;L;;;;;N;;;;; -120A1;CUNEIFORM SIGN EZEN;Lo;0;L;;;;;N;;;;; -120A2;CUNEIFORM SIGN EZEN TIMES A;Lo;0;L;;;;;N;;;;; -120A3;CUNEIFORM SIGN EZEN TIMES A PLUS LAL;Lo;0;L;;;;;N;;;;; -120A4;CUNEIFORM SIGN EZEN TIMES A PLUS LAL TIMES LAL;Lo;0;L;;;;;N;;;;; -120A5;CUNEIFORM SIGN EZEN TIMES AN;Lo;0;L;;;;;N;;;;; -120A6;CUNEIFORM SIGN EZEN TIMES BAD;Lo;0;L;;;;;N;;;;; -120A7;CUNEIFORM SIGN EZEN TIMES DUN3 GUNU;Lo;0;L;;;;;N;;;;; -120A8;CUNEIFORM SIGN EZEN TIMES DUN3 GUNU GUNU;Lo;0;L;;;;;N;;;;; -120A9;CUNEIFORM SIGN EZEN TIMES HA;Lo;0;L;;;;;N;;;;; -120AA;CUNEIFORM SIGN EZEN TIMES HA GUNU;Lo;0;L;;;;;N;;;;; -120AB;CUNEIFORM SIGN EZEN TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -120AC;CUNEIFORM SIGN EZEN TIMES KASKAL;Lo;0;L;;;;;N;;;;; -120AD;CUNEIFORM SIGN EZEN TIMES KASKAL SQUARED;Lo;0;L;;;;;N;;;;; -120AE;CUNEIFORM SIGN EZEN TIMES KU3;Lo;0;L;;;;;N;;;;; -120AF;CUNEIFORM SIGN EZEN TIMES LA;Lo;0;L;;;;;N;;;;; -120B0;CUNEIFORM SIGN EZEN TIMES LAL TIMES LAL;Lo;0;L;;;;;N;;;;; -120B1;CUNEIFORM SIGN EZEN TIMES LI;Lo;0;L;;;;;N;;;;; -120B2;CUNEIFORM SIGN EZEN TIMES LU;Lo;0;L;;;;;N;;;;; -120B3;CUNEIFORM SIGN EZEN TIMES U2;Lo;0;L;;;;;N;;;;; -120B4;CUNEIFORM SIGN EZEN TIMES UD;Lo;0;L;;;;;N;;;;; -120B5;CUNEIFORM SIGN GA;Lo;0;L;;;;;N;;;;; -120B6;CUNEIFORM SIGN GA GUNU;Lo;0;L;;;;;N;;;;; -120B7;CUNEIFORM SIGN GA2;Lo;0;L;;;;;N;;;;; -120B8;CUNEIFORM SIGN GA2 TIMES A PLUS DA PLUS HA;Lo;0;L;;;;;N;;;;; -120B9;CUNEIFORM SIGN GA2 TIMES A PLUS HA;Lo;0;L;;;;;N;;;;; -120BA;CUNEIFORM SIGN GA2 TIMES A PLUS IGI;Lo;0;L;;;;;N;;;;; -120BB;CUNEIFORM SIGN GA2 TIMES AB2 TENU PLUS TAB;Lo;0;L;;;;;N;;;;; -120BC;CUNEIFORM SIGN GA2 TIMES AN;Lo;0;L;;;;;N;;;;; -120BD;CUNEIFORM SIGN GA2 TIMES ASH;Lo;0;L;;;;;N;;;;; -120BE;CUNEIFORM SIGN GA2 TIMES ASH2 PLUS GAL;Lo;0;L;;;;;N;;;;; -120BF;CUNEIFORM SIGN GA2 TIMES BAD;Lo;0;L;;;;;N;;;;; -120C0;CUNEIFORM SIGN GA2 TIMES BAR PLUS RA;Lo;0;L;;;;;N;;;;; -120C1;CUNEIFORM SIGN GA2 TIMES BUR;Lo;0;L;;;;;N;;;;; -120C2;CUNEIFORM SIGN GA2 TIMES BUR PLUS RA;Lo;0;L;;;;;N;;;;; -120C3;CUNEIFORM SIGN GA2 TIMES DA;Lo;0;L;;;;;N;;;;; -120C4;CUNEIFORM SIGN GA2 TIMES DI;Lo;0;L;;;;;N;;;;; -120C5;CUNEIFORM SIGN GA2 TIMES DIM TIMES SHE;Lo;0;L;;;;;N;;;;; -120C6;CUNEIFORM SIGN GA2 TIMES DUB;Lo;0;L;;;;;N;;;;; -120C7;CUNEIFORM SIGN GA2 TIMES EL;Lo;0;L;;;;;N;;;;; -120C8;CUNEIFORM SIGN GA2 TIMES EL PLUS LA;Lo;0;L;;;;;N;;;;; -120C9;CUNEIFORM SIGN GA2 TIMES EN;Lo;0;L;;;;;N;;;;; -120CA;CUNEIFORM SIGN GA2 TIMES EN TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -120CB;CUNEIFORM SIGN GA2 TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -120CC;CUNEIFORM SIGN GA2 TIMES GAR;Lo;0;L;;;;;N;;;;; -120CD;CUNEIFORM SIGN GA2 TIMES GI;Lo;0;L;;;;;N;;;;; -120CE;CUNEIFORM SIGN GA2 TIMES GI4;Lo;0;L;;;;;N;;;;; -120CF;CUNEIFORM SIGN GA2 TIMES GI4 PLUS A;Lo;0;L;;;;;N;;;;; -120D0;CUNEIFORM SIGN GA2 TIMES GIR2 PLUS SU;Lo;0;L;;;;;N;;;;; -120D1;CUNEIFORM SIGN GA2 TIMES HA PLUS LU PLUS ESH2;Lo;0;L;;;;;N;;;;; -120D2;CUNEIFORM SIGN GA2 TIMES HAL;Lo;0;L;;;;;N;;;;; -120D3;CUNEIFORM SIGN GA2 TIMES HAL PLUS LA;Lo;0;L;;;;;N;;;;; -120D4;CUNEIFORM SIGN GA2 TIMES HI PLUS LI;Lo;0;L;;;;;N;;;;; -120D5;CUNEIFORM SIGN GA2 TIMES HUB2;Lo;0;L;;;;;N;;;;; -120D6;CUNEIFORM SIGN GA2 TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -120D7;CUNEIFORM SIGN GA2 TIMES ISH PLUS HU PLUS ASH;Lo;0;L;;;;;N;;;;; -120D8;CUNEIFORM SIGN GA2 TIMES KAK;Lo;0;L;;;;;N;;;;; -120D9;CUNEIFORM SIGN GA2 TIMES KASKAL;Lo;0;L;;;;;N;;;;; -120DA;CUNEIFORM SIGN GA2 TIMES KID;Lo;0;L;;;;;N;;;;; -120DB;CUNEIFORM SIGN GA2 TIMES KID PLUS LAL;Lo;0;L;;;;;N;;;;; -120DC;CUNEIFORM SIGN GA2 TIMES KU3 PLUS AN;Lo;0;L;;;;;N;;;;; -120DD;CUNEIFORM SIGN GA2 TIMES LA;Lo;0;L;;;;;N;;;;; -120DE;CUNEIFORM SIGN GA2 TIMES ME PLUS EN;Lo;0;L;;;;;N;;;;; -120DF;CUNEIFORM SIGN GA2 TIMES MI;Lo;0;L;;;;;N;;;;; -120E0;CUNEIFORM SIGN GA2 TIMES NUN;Lo;0;L;;;;;N;;;;; -120E1;CUNEIFORM SIGN GA2 TIMES NUN OVER NUN;Lo;0;L;;;;;N;;;;; -120E2;CUNEIFORM SIGN GA2 TIMES PA;Lo;0;L;;;;;N;;;;; -120E3;CUNEIFORM SIGN GA2 TIMES SAL;Lo;0;L;;;;;N;;;;; -120E4;CUNEIFORM SIGN GA2 TIMES SAR;Lo;0;L;;;;;N;;;;; -120E5;CUNEIFORM SIGN GA2 TIMES SHE;Lo;0;L;;;;;N;;;;; -120E6;CUNEIFORM SIGN GA2 TIMES SHE PLUS TUR;Lo;0;L;;;;;N;;;;; -120E7;CUNEIFORM SIGN GA2 TIMES SHID;Lo;0;L;;;;;N;;;;; -120E8;CUNEIFORM SIGN GA2 TIMES SUM;Lo;0;L;;;;;N;;;;; -120E9;CUNEIFORM SIGN GA2 TIMES TAK4;Lo;0;L;;;;;N;;;;; -120EA;CUNEIFORM SIGN GA2 TIMES U;Lo;0;L;;;;;N;;;;; -120EB;CUNEIFORM SIGN GA2 TIMES UD;Lo;0;L;;;;;N;;;;; -120EC;CUNEIFORM SIGN GA2 TIMES UD PLUS DU;Lo;0;L;;;;;N;;;;; -120ED;CUNEIFORM SIGN GA2 OVER GA2;Lo;0;L;;;;;N;;;;; -120EE;CUNEIFORM SIGN GABA;Lo;0;L;;;;;N;;;;; -120EF;CUNEIFORM SIGN GABA CROSSING GABA;Lo;0;L;;;;;N;;;;; -120F0;CUNEIFORM SIGN GAD;Lo;0;L;;;;;N;;;;; -120F1;CUNEIFORM SIGN GAD OVER GAD GAR OVER GAR;Lo;0;L;;;;;N;;;;; -120F2;CUNEIFORM SIGN GAL;Lo;0;L;;;;;N;;;;; -120F3;CUNEIFORM SIGN GAL GAD OVER GAD GAR OVER GAR;Lo;0;L;;;;;N;;;;; -120F4;CUNEIFORM SIGN GALAM;Lo;0;L;;;;;N;;;;; -120F5;CUNEIFORM SIGN GAM;Lo;0;L;;;;;N;;;;; -120F6;CUNEIFORM SIGN GAN;Lo;0;L;;;;;N;;;;; -120F7;CUNEIFORM SIGN GAN2;Lo;0;L;;;;;N;;;;; -120F8;CUNEIFORM SIGN GAN2 TENU;Lo;0;L;;;;;N;;;;; -120F9;CUNEIFORM SIGN GAN2 OVER GAN2;Lo;0;L;;;;;N;;;;; -120FA;CUNEIFORM SIGN GAN2 CROSSING GAN2;Lo;0;L;;;;;N;;;;; -120FB;CUNEIFORM SIGN GAR;Lo;0;L;;;;;N;;;;; -120FC;CUNEIFORM SIGN GAR3;Lo;0;L;;;;;N;;;;; -120FD;CUNEIFORM SIGN GASHAN;Lo;0;L;;;;;N;;;;; -120FE;CUNEIFORM SIGN GESHTIN;Lo;0;L;;;;;N;;;;; -120FF;CUNEIFORM SIGN GESHTIN TIMES KUR;Lo;0;L;;;;;N;;;;; -12100;CUNEIFORM SIGN GI;Lo;0;L;;;;;N;;;;; -12101;CUNEIFORM SIGN GI TIMES E;Lo;0;L;;;;;N;;;;; -12102;CUNEIFORM SIGN GI TIMES U;Lo;0;L;;;;;N;;;;; -12103;CUNEIFORM SIGN GI CROSSING GI;Lo;0;L;;;;;N;;;;; -12104;CUNEIFORM SIGN GI4;Lo;0;L;;;;;N;;;;; -12105;CUNEIFORM SIGN GI4 OVER GI4;Lo;0;L;;;;;N;;;;; -12106;CUNEIFORM SIGN GI4 CROSSING GI4;Lo;0;L;;;;;N;;;;; -12107;CUNEIFORM SIGN GIDIM;Lo;0;L;;;;;N;;;;; -12108;CUNEIFORM SIGN GIR2;Lo;0;L;;;;;N;;;;; -12109;CUNEIFORM SIGN GIR2 GUNU;Lo;0;L;;;;;N;;;;; -1210A;CUNEIFORM SIGN GIR3;Lo;0;L;;;;;N;;;;; -1210B;CUNEIFORM SIGN GIR3 TIMES A PLUS IGI;Lo;0;L;;;;;N;;;;; -1210C;CUNEIFORM SIGN GIR3 TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -1210D;CUNEIFORM SIGN GIR3 TIMES IGI;Lo;0;L;;;;;N;;;;; -1210E;CUNEIFORM SIGN GIR3 TIMES LU PLUS IGI;Lo;0;L;;;;;N;;;;; -1210F;CUNEIFORM SIGN GIR3 TIMES PA;Lo;0;L;;;;;N;;;;; -12110;CUNEIFORM SIGN GISAL;Lo;0;L;;;;;N;;;;; -12111;CUNEIFORM SIGN GISH;Lo;0;L;;;;;N;;;;; -12112;CUNEIFORM SIGN GISH CROSSING GISH;Lo;0;L;;;;;N;;;;; -12113;CUNEIFORM SIGN GISH TIMES BAD;Lo;0;L;;;;;N;;;;; -12114;CUNEIFORM SIGN GISH TIMES TAK4;Lo;0;L;;;;;N;;;;; -12115;CUNEIFORM SIGN GISH TENU;Lo;0;L;;;;;N;;;;; -12116;CUNEIFORM SIGN GU;Lo;0;L;;;;;N;;;;; -12117;CUNEIFORM SIGN GU CROSSING GU;Lo;0;L;;;;;N;;;;; -12118;CUNEIFORM SIGN GU2;Lo;0;L;;;;;N;;;;; -12119;CUNEIFORM SIGN GU2 TIMES KAK;Lo;0;L;;;;;N;;;;; -1211A;CUNEIFORM SIGN GU2 TIMES KAK TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -1211B;CUNEIFORM SIGN GU2 TIMES NUN;Lo;0;L;;;;;N;;;;; -1211C;CUNEIFORM SIGN GU2 TIMES SAL PLUS TUG2;Lo;0;L;;;;;N;;;;; -1211D;CUNEIFORM SIGN GU2 GUNU;Lo;0;L;;;;;N;;;;; -1211E;CUNEIFORM SIGN GUD;Lo;0;L;;;;;N;;;;; -1211F;CUNEIFORM SIGN GUD TIMES A PLUS KUR;Lo;0;L;;;;;N;;;;; -12120;CUNEIFORM SIGN GUD TIMES KUR;Lo;0;L;;;;;N;;;;; -12121;CUNEIFORM SIGN GUD OVER GUD LUGAL;Lo;0;L;;;;;N;;;;; -12122;CUNEIFORM SIGN GUL;Lo;0;L;;;;;N;;;;; -12123;CUNEIFORM SIGN GUM;Lo;0;L;;;;;N;;;;; -12124;CUNEIFORM SIGN GUM TIMES SHE;Lo;0;L;;;;;N;;;;; -12125;CUNEIFORM SIGN GUR;Lo;0;L;;;;;N;;;;; -12126;CUNEIFORM SIGN GUR7;Lo;0;L;;;;;N;;;;; -12127;CUNEIFORM SIGN GURUN;Lo;0;L;;;;;N;;;;; -12128;CUNEIFORM SIGN GURUSH;Lo;0;L;;;;;N;;;;; -12129;CUNEIFORM SIGN HA;Lo;0;L;;;;;N;;;;; -1212A;CUNEIFORM SIGN HA TENU;Lo;0;L;;;;;N;;;;; -1212B;CUNEIFORM SIGN HA GUNU;Lo;0;L;;;;;N;;;;; -1212C;CUNEIFORM SIGN HAL;Lo;0;L;;;;;N;;;;; -1212D;CUNEIFORM SIGN HI;Lo;0;L;;;;;N;;;;; -1212E;CUNEIFORM SIGN HI TIMES ASH;Lo;0;L;;;;;N;;;;; -1212F;CUNEIFORM SIGN HI TIMES ASH2;Lo;0;L;;;;;N;;;;; -12130;CUNEIFORM SIGN HI TIMES BAD;Lo;0;L;;;;;N;;;;; -12131;CUNEIFORM SIGN HI TIMES DISH;Lo;0;L;;;;;N;;;;; -12132;CUNEIFORM SIGN HI TIMES GAD;Lo;0;L;;;;;N;;;;; -12133;CUNEIFORM SIGN HI TIMES KIN;Lo;0;L;;;;;N;;;;; -12134;CUNEIFORM SIGN HI TIMES NUN;Lo;0;L;;;;;N;;;;; -12135;CUNEIFORM SIGN HI TIMES SHE;Lo;0;L;;;;;N;;;;; -12136;CUNEIFORM SIGN HI TIMES U;Lo;0;L;;;;;N;;;;; -12137;CUNEIFORM SIGN HU;Lo;0;L;;;;;N;;;;; -12138;CUNEIFORM SIGN HUB2;Lo;0;L;;;;;N;;;;; -12139;CUNEIFORM SIGN HUB2 TIMES AN;Lo;0;L;;;;;N;;;;; -1213A;CUNEIFORM SIGN HUB2 TIMES HAL;Lo;0;L;;;;;N;;;;; -1213B;CUNEIFORM SIGN HUB2 TIMES KASKAL;Lo;0;L;;;;;N;;;;; -1213C;CUNEIFORM SIGN HUB2 TIMES LISH;Lo;0;L;;;;;N;;;;; -1213D;CUNEIFORM SIGN HUB2 TIMES UD;Lo;0;L;;;;;N;;;;; -1213E;CUNEIFORM SIGN HUL2;Lo;0;L;;;;;N;;;;; -1213F;CUNEIFORM SIGN I;Lo;0;L;;;;;N;;;;; -12140;CUNEIFORM SIGN I A;Lo;0;L;;;;;N;;;;; -12141;CUNEIFORM SIGN IB;Lo;0;L;;;;;N;;;;; -12142;CUNEIFORM SIGN IDIM;Lo;0;L;;;;;N;;;;; -12143;CUNEIFORM SIGN IDIM OVER IDIM BUR;Lo;0;L;;;;;N;;;;; -12144;CUNEIFORM SIGN IDIM OVER IDIM SQUARED;Lo;0;L;;;;;N;;;;; -12145;CUNEIFORM SIGN IG;Lo;0;L;;;;;N;;;;; -12146;CUNEIFORM SIGN IGI;Lo;0;L;;;;;N;;;;; -12147;CUNEIFORM SIGN IGI DIB;Lo;0;L;;;;;N;;;;; -12148;CUNEIFORM SIGN IGI RI;Lo;0;L;;;;;N;;;;; -12149;CUNEIFORM SIGN IGI OVER IGI SHIR OVER SHIR UD OVER UD;Lo;0;L;;;;;N;;;;; -1214A;CUNEIFORM SIGN IGI GUNU;Lo;0;L;;;;;N;;;;; -1214B;CUNEIFORM SIGN IL;Lo;0;L;;;;;N;;;;; -1214C;CUNEIFORM SIGN IL TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -1214D;CUNEIFORM SIGN IL2;Lo;0;L;;;;;N;;;;; -1214E;CUNEIFORM SIGN IM;Lo;0;L;;;;;N;;;;; -1214F;CUNEIFORM SIGN IM TIMES TAK4;Lo;0;L;;;;;N;;;;; -12150;CUNEIFORM SIGN IM CROSSING IM;Lo;0;L;;;;;N;;;;; -12151;CUNEIFORM SIGN IM OPPOSING IM;Lo;0;L;;;;;N;;;;; -12152;CUNEIFORM SIGN IM SQUARED;Lo;0;L;;;;;N;;;;; -12153;CUNEIFORM SIGN IMIN;Lo;0;L;;;;;N;;;;; -12154;CUNEIFORM SIGN IN;Lo;0;L;;;;;N;;;;; -12155;CUNEIFORM SIGN IR;Lo;0;L;;;;;N;;;;; -12156;CUNEIFORM SIGN ISH;Lo;0;L;;;;;N;;;;; -12157;CUNEIFORM SIGN KA;Lo;0;L;;;;;N;;;;; -12158;CUNEIFORM SIGN KA TIMES A;Lo;0;L;;;;;N;;;;; -12159;CUNEIFORM SIGN KA TIMES AD;Lo;0;L;;;;;N;;;;; -1215A;CUNEIFORM SIGN KA TIMES AD PLUS KU3;Lo;0;L;;;;;N;;;;; -1215B;CUNEIFORM SIGN KA TIMES ASH2;Lo;0;L;;;;;N;;;;; -1215C;CUNEIFORM SIGN KA TIMES BAD;Lo;0;L;;;;;N;;;;; -1215D;CUNEIFORM SIGN KA TIMES BALAG;Lo;0;L;;;;;N;;;;; -1215E;CUNEIFORM SIGN KA TIMES BAR;Lo;0;L;;;;;N;;;;; -1215F;CUNEIFORM SIGN KA TIMES BI;Lo;0;L;;;;;N;;;;; -12160;CUNEIFORM SIGN KA TIMES ERIN2;Lo;0;L;;;;;N;;;;; -12161;CUNEIFORM SIGN KA TIMES ESH2;Lo;0;L;;;;;N;;;;; -12162;CUNEIFORM SIGN KA TIMES GA;Lo;0;L;;;;;N;;;;; -12163;CUNEIFORM SIGN KA TIMES GAL;Lo;0;L;;;;;N;;;;; -12164;CUNEIFORM SIGN KA TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -12165;CUNEIFORM SIGN KA TIMES GAR;Lo;0;L;;;;;N;;;;; -12166;CUNEIFORM SIGN KA TIMES GAR PLUS SHA3 PLUS A;Lo;0;L;;;;;N;;;;; -12167;CUNEIFORM SIGN KA TIMES GI;Lo;0;L;;;;;N;;;;; -12168;CUNEIFORM SIGN KA TIMES GIR2;Lo;0;L;;;;;N;;;;; -12169;CUNEIFORM SIGN KA TIMES GISH PLUS SAR;Lo;0;L;;;;;N;;;;; -1216A;CUNEIFORM SIGN KA TIMES GISH CROSSING GISH;Lo;0;L;;;;;N;;;;; -1216B;CUNEIFORM SIGN KA TIMES GU;Lo;0;L;;;;;N;;;;; -1216C;CUNEIFORM SIGN KA TIMES GUR7;Lo;0;L;;;;;N;;;;; -1216D;CUNEIFORM SIGN KA TIMES IGI;Lo;0;L;;;;;N;;;;; -1216E;CUNEIFORM SIGN KA TIMES IM;Lo;0;L;;;;;N;;;;; -1216F;CUNEIFORM SIGN KA TIMES KAK;Lo;0;L;;;;;N;;;;; -12170;CUNEIFORM SIGN KA TIMES KI;Lo;0;L;;;;;N;;;;; -12171;CUNEIFORM SIGN KA TIMES KID;Lo;0;L;;;;;N;;;;; -12172;CUNEIFORM SIGN KA TIMES LI;Lo;0;L;;;;;N;;;;; -12173;CUNEIFORM SIGN KA TIMES LU;Lo;0;L;;;;;N;;;;; -12174;CUNEIFORM SIGN KA TIMES ME;Lo;0;L;;;;;N;;;;; -12175;CUNEIFORM SIGN KA TIMES ME PLUS DU;Lo;0;L;;;;;N;;;;; -12176;CUNEIFORM SIGN KA TIMES ME PLUS GI;Lo;0;L;;;;;N;;;;; -12177;CUNEIFORM SIGN KA TIMES ME PLUS TE;Lo;0;L;;;;;N;;;;; -12178;CUNEIFORM SIGN KA TIMES MI;Lo;0;L;;;;;N;;;;; -12179;CUNEIFORM SIGN KA TIMES MI PLUS NUNUZ;Lo;0;L;;;;;N;;;;; -1217A;CUNEIFORM SIGN KA TIMES NE;Lo;0;L;;;;;N;;;;; -1217B;CUNEIFORM SIGN KA TIMES NUN;Lo;0;L;;;;;N;;;;; -1217C;CUNEIFORM SIGN KA TIMES PI;Lo;0;L;;;;;N;;;;; -1217D;CUNEIFORM SIGN KA TIMES RU;Lo;0;L;;;;;N;;;;; -1217E;CUNEIFORM SIGN KA TIMES SA;Lo;0;L;;;;;N;;;;; -1217F;CUNEIFORM SIGN KA TIMES SAR;Lo;0;L;;;;;N;;;;; -12180;CUNEIFORM SIGN KA TIMES SHA;Lo;0;L;;;;;N;;;;; -12181;CUNEIFORM SIGN KA TIMES SHE;Lo;0;L;;;;;N;;;;; -12182;CUNEIFORM SIGN KA TIMES SHID;Lo;0;L;;;;;N;;;;; -12183;CUNEIFORM SIGN KA TIMES SHU;Lo;0;L;;;;;N;;;;; -12184;CUNEIFORM SIGN KA TIMES SIG;Lo;0;L;;;;;N;;;;; -12185;CUNEIFORM SIGN KA TIMES SUHUR;Lo;0;L;;;;;N;;;;; -12186;CUNEIFORM SIGN KA TIMES TAR;Lo;0;L;;;;;N;;;;; -12187;CUNEIFORM SIGN KA TIMES U;Lo;0;L;;;;;N;;;;; -12188;CUNEIFORM SIGN KA TIMES U2;Lo;0;L;;;;;N;;;;; -12189;CUNEIFORM SIGN KA TIMES UD;Lo;0;L;;;;;N;;;;; -1218A;CUNEIFORM SIGN KA TIMES UMUM TIMES PA;Lo;0;L;;;;;N;;;;; -1218B;CUNEIFORM SIGN KA TIMES USH;Lo;0;L;;;;;N;;;;; -1218C;CUNEIFORM SIGN KA TIMES ZI;Lo;0;L;;;;;N;;;;; -1218D;CUNEIFORM SIGN KA2;Lo;0;L;;;;;N;;;;; -1218E;CUNEIFORM SIGN KA2 CROSSING KA2;Lo;0;L;;;;;N;;;;; -1218F;CUNEIFORM SIGN KAB;Lo;0;L;;;;;N;;;;; -12190;CUNEIFORM SIGN KAD2;Lo;0;L;;;;;N;;;;; -12191;CUNEIFORM SIGN KAD3;Lo;0;L;;;;;N;;;;; -12192;CUNEIFORM SIGN KAD4;Lo;0;L;;;;;N;;;;; -12193;CUNEIFORM SIGN KAD5;Lo;0;L;;;;;N;;;;; -12194;CUNEIFORM SIGN KAD5 OVER KAD5;Lo;0;L;;;;;N;;;;; -12195;CUNEIFORM SIGN KAK;Lo;0;L;;;;;N;;;;; -12196;CUNEIFORM SIGN KAK TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -12197;CUNEIFORM SIGN KAL;Lo;0;L;;;;;N;;;;; -12198;CUNEIFORM SIGN KAL TIMES BAD;Lo;0;L;;;;;N;;;;; -12199;CUNEIFORM SIGN KAL CROSSING KAL;Lo;0;L;;;;;N;;;;; -1219A;CUNEIFORM SIGN KAM2;Lo;0;L;;;;;N;;;;; -1219B;CUNEIFORM SIGN KAM4;Lo;0;L;;;;;N;;;;; -1219C;CUNEIFORM SIGN KASKAL;Lo;0;L;;;;;N;;;;; -1219D;CUNEIFORM SIGN KASKAL LAGAB TIMES U OVER LAGAB TIMES U;Lo;0;L;;;;;N;;;;; -1219E;CUNEIFORM SIGN KASKAL OVER KASKAL LAGAB TIMES U OVER LAGAB TIMES U;Lo;0;L;;;;;N;;;;; -1219F;CUNEIFORM SIGN KESH2;Lo;0;L;;;;;N;;;;; -121A0;CUNEIFORM SIGN KI;Lo;0;L;;;;;N;;;;; -121A1;CUNEIFORM SIGN KI TIMES BAD;Lo;0;L;;;;;N;;;;; -121A2;CUNEIFORM SIGN KI TIMES U;Lo;0;L;;;;;N;;;;; -121A3;CUNEIFORM SIGN KI TIMES UD;Lo;0;L;;;;;N;;;;; -121A4;CUNEIFORM SIGN KID;Lo;0;L;;;;;N;;;;; -121A5;CUNEIFORM SIGN KIN;Lo;0;L;;;;;N;;;;; -121A6;CUNEIFORM SIGN KISAL;Lo;0;L;;;;;N;;;;; -121A7;CUNEIFORM SIGN KISH;Lo;0;L;;;;;N;;;;; -121A8;CUNEIFORM SIGN KISIM5;Lo;0;L;;;;;N;;;;; -121A9;CUNEIFORM SIGN KISIM5 OVER KISIM5;Lo;0;L;;;;;N;;;;; -121AA;CUNEIFORM SIGN KU;Lo;0;L;;;;;N;;;;; -121AB;CUNEIFORM SIGN KU OVER HI TIMES ASH2 KU OVER HI TIMES ASH2;Lo;0;L;;;;;N;;;;; -121AC;CUNEIFORM SIGN KU3;Lo;0;L;;;;;N;;;;; -121AD;CUNEIFORM SIGN KU4;Lo;0;L;;;;;N;;;;; -121AE;CUNEIFORM SIGN KU4 VARIANT FORM;Lo;0;L;;;;;N;;;;; -121AF;CUNEIFORM SIGN KU7;Lo;0;L;;;;;N;;;;; -121B0;CUNEIFORM SIGN KUL;Lo;0;L;;;;;N;;;;; -121B1;CUNEIFORM SIGN KUL GUNU;Lo;0;L;;;;;N;;;;; -121B2;CUNEIFORM SIGN KUN;Lo;0;L;;;;;N;;;;; -121B3;CUNEIFORM SIGN KUR;Lo;0;L;;;;;N;;;;; -121B4;CUNEIFORM SIGN KUR OPPOSING KUR;Lo;0;L;;;;;N;;;;; -121B5;CUNEIFORM SIGN KUSHU2;Lo;0;L;;;;;N;;;;; -121B6;CUNEIFORM SIGN KWU318;Lo;0;L;;;;;N;;;;; -121B7;CUNEIFORM SIGN LA;Lo;0;L;;;;;N;;;;; -121B8;CUNEIFORM SIGN LAGAB;Lo;0;L;;;;;N;;;;; -121B9;CUNEIFORM SIGN LAGAB TIMES A;Lo;0;L;;;;;N;;;;; -121BA;CUNEIFORM SIGN LAGAB TIMES A PLUS DA PLUS HA;Lo;0;L;;;;;N;;;;; -121BB;CUNEIFORM SIGN LAGAB TIMES A PLUS GAR;Lo;0;L;;;;;N;;;;; -121BC;CUNEIFORM SIGN LAGAB TIMES A PLUS LAL;Lo;0;L;;;;;N;;;;; -121BD;CUNEIFORM SIGN LAGAB TIMES AL;Lo;0;L;;;;;N;;;;; -121BE;CUNEIFORM SIGN LAGAB TIMES AN;Lo;0;L;;;;;N;;;;; -121BF;CUNEIFORM SIGN LAGAB TIMES ASH ZIDA TENU;Lo;0;L;;;;;N;;;;; -121C0;CUNEIFORM SIGN LAGAB TIMES BAD;Lo;0;L;;;;;N;;;;; -121C1;CUNEIFORM SIGN LAGAB TIMES BI;Lo;0;L;;;;;N;;;;; -121C2;CUNEIFORM SIGN LAGAB TIMES DAR;Lo;0;L;;;;;N;;;;; -121C3;CUNEIFORM SIGN LAGAB TIMES EN;Lo;0;L;;;;;N;;;;; -121C4;CUNEIFORM SIGN LAGAB TIMES GA;Lo;0;L;;;;;N;;;;; -121C5;CUNEIFORM SIGN LAGAB TIMES GAR;Lo;0;L;;;;;N;;;;; -121C6;CUNEIFORM SIGN LAGAB TIMES GUD;Lo;0;L;;;;;N;;;;; -121C7;CUNEIFORM SIGN LAGAB TIMES GUD PLUS GUD;Lo;0;L;;;;;N;;;;; -121C8;CUNEIFORM SIGN LAGAB TIMES HA;Lo;0;L;;;;;N;;;;; -121C9;CUNEIFORM SIGN LAGAB TIMES HAL;Lo;0;L;;;;;N;;;;; -121CA;CUNEIFORM SIGN LAGAB TIMES HI TIMES NUN;Lo;0;L;;;;;N;;;;; -121CB;CUNEIFORM SIGN LAGAB TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -121CC;CUNEIFORM SIGN LAGAB TIMES IM;Lo;0;L;;;;;N;;;;; -121CD;CUNEIFORM SIGN LAGAB TIMES IM PLUS HA;Lo;0;L;;;;;N;;;;; -121CE;CUNEIFORM SIGN LAGAB TIMES IM PLUS LU;Lo;0;L;;;;;N;;;;; -121CF;CUNEIFORM SIGN LAGAB TIMES KI;Lo;0;L;;;;;N;;;;; -121D0;CUNEIFORM SIGN LAGAB TIMES KIN;Lo;0;L;;;;;N;;;;; -121D1;CUNEIFORM SIGN LAGAB TIMES KU3;Lo;0;L;;;;;N;;;;; -121D2;CUNEIFORM SIGN LAGAB TIMES KUL;Lo;0;L;;;;;N;;;;; -121D3;CUNEIFORM SIGN LAGAB TIMES KUL PLUS HI PLUS A;Lo;0;L;;;;;N;;;;; -121D4;CUNEIFORM SIGN LAGAB TIMES LAGAB;Lo;0;L;;;;;N;;;;; -121D5;CUNEIFORM SIGN LAGAB TIMES LISH;Lo;0;L;;;;;N;;;;; -121D6;CUNEIFORM SIGN LAGAB TIMES LU;Lo;0;L;;;;;N;;;;; -121D7;CUNEIFORM SIGN LAGAB TIMES LUL;Lo;0;L;;;;;N;;;;; -121D8;CUNEIFORM SIGN LAGAB TIMES ME;Lo;0;L;;;;;N;;;;; -121D9;CUNEIFORM SIGN LAGAB TIMES ME PLUS EN;Lo;0;L;;;;;N;;;;; -121DA;CUNEIFORM SIGN LAGAB TIMES MUSH;Lo;0;L;;;;;N;;;;; -121DB;CUNEIFORM SIGN LAGAB TIMES NE;Lo;0;L;;;;;N;;;;; -121DC;CUNEIFORM SIGN LAGAB TIMES SHE PLUS SUM;Lo;0;L;;;;;N;;;;; -121DD;CUNEIFORM SIGN LAGAB TIMES SHITA PLUS GISH PLUS ERIN2;Lo;0;L;;;;;N;;;;; -121DE;CUNEIFORM SIGN LAGAB TIMES SHITA PLUS GISH TENU;Lo;0;L;;;;;N;;;;; -121DF;CUNEIFORM SIGN LAGAB TIMES SHU2;Lo;0;L;;;;;N;;;;; -121E0;CUNEIFORM SIGN LAGAB TIMES SHU2 PLUS SHU2;Lo;0;L;;;;;N;;;;; -121E1;CUNEIFORM SIGN LAGAB TIMES SUM;Lo;0;L;;;;;N;;;;; -121E2;CUNEIFORM SIGN LAGAB TIMES TAG;Lo;0;L;;;;;N;;;;; -121E3;CUNEIFORM SIGN LAGAB TIMES TAK4;Lo;0;L;;;;;N;;;;; -121E4;CUNEIFORM SIGN LAGAB TIMES TE PLUS A PLUS SU PLUS NA;Lo;0;L;;;;;N;;;;; -121E5;CUNEIFORM SIGN LAGAB TIMES U;Lo;0;L;;;;;N;;;;; -121E6;CUNEIFORM SIGN LAGAB TIMES U PLUS A;Lo;0;L;;;;;N;;;;; -121E7;CUNEIFORM SIGN LAGAB TIMES U PLUS U PLUS U;Lo;0;L;;;;;N;;;;; -121E8;CUNEIFORM SIGN LAGAB TIMES U2 PLUS ASH;Lo;0;L;;;;;N;;;;; -121E9;CUNEIFORM SIGN LAGAB TIMES UD;Lo;0;L;;;;;N;;;;; -121EA;CUNEIFORM SIGN LAGAB TIMES USH;Lo;0;L;;;;;N;;;;; -121EB;CUNEIFORM SIGN LAGAB SQUARED;Lo;0;L;;;;;N;;;;; -121EC;CUNEIFORM SIGN LAGAR;Lo;0;L;;;;;N;;;;; -121ED;CUNEIFORM SIGN LAGAR TIMES SHE;Lo;0;L;;;;;N;;;;; -121EE;CUNEIFORM SIGN LAGAR TIMES SHE PLUS SUM;Lo;0;L;;;;;N;;;;; -121EF;CUNEIFORM SIGN LAGAR GUNU;Lo;0;L;;;;;N;;;;; -121F0;CUNEIFORM SIGN LAGAR GUNU OVER LAGAR GUNU SHE;Lo;0;L;;;;;N;;;;; -121F1;CUNEIFORM SIGN LAHSHU;Lo;0;L;;;;;N;;;;; -121F2;CUNEIFORM SIGN LAL;Lo;0;L;;;;;N;;;;; -121F3;CUNEIFORM SIGN LAL TIMES LAL;Lo;0;L;;;;;N;;;;; -121F4;CUNEIFORM SIGN LAM;Lo;0;L;;;;;N;;;;; -121F5;CUNEIFORM SIGN LAM TIMES KUR;Lo;0;L;;;;;N;;;;; -121F6;CUNEIFORM SIGN LAM TIMES KUR PLUS RU;Lo;0;L;;;;;N;;;;; -121F7;CUNEIFORM SIGN LI;Lo;0;L;;;;;N;;;;; -121F8;CUNEIFORM SIGN LIL;Lo;0;L;;;;;N;;;;; -121F9;CUNEIFORM SIGN LIMMU2;Lo;0;L;;;;;N;;;;; -121FA;CUNEIFORM SIGN LISH;Lo;0;L;;;;;N;;;;; -121FB;CUNEIFORM SIGN LU;Lo;0;L;;;;;N;;;;; -121FC;CUNEIFORM SIGN LU TIMES BAD;Lo;0;L;;;;;N;;;;; -121FD;CUNEIFORM SIGN LU2;Lo;0;L;;;;;N;;;;; -121FE;CUNEIFORM SIGN LU2 TIMES AL;Lo;0;L;;;;;N;;;;; -121FF;CUNEIFORM SIGN LU2 TIMES BAD;Lo;0;L;;;;;N;;;;; -12200;CUNEIFORM SIGN LU2 TIMES ESH2;Lo;0;L;;;;;N;;;;; -12201;CUNEIFORM SIGN LU2 TIMES ESH2 TENU;Lo;0;L;;;;;N;;;;; -12202;CUNEIFORM SIGN LU2 TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -12203;CUNEIFORM SIGN LU2 TIMES HI TIMES BAD;Lo;0;L;;;;;N;;;;; -12204;CUNEIFORM SIGN LU2 TIMES IM;Lo;0;L;;;;;N;;;;; -12205;CUNEIFORM SIGN LU2 TIMES KAD2;Lo;0;L;;;;;N;;;;; -12206;CUNEIFORM SIGN LU2 TIMES KAD3;Lo;0;L;;;;;N;;;;; -12207;CUNEIFORM SIGN LU2 TIMES KAD3 PLUS ASH;Lo;0;L;;;;;N;;;;; -12208;CUNEIFORM SIGN LU2 TIMES KI;Lo;0;L;;;;;N;;;;; -12209;CUNEIFORM SIGN LU2 TIMES LA PLUS ASH;Lo;0;L;;;;;N;;;;; -1220A;CUNEIFORM SIGN LU2 TIMES LAGAB;Lo;0;L;;;;;N;;;;; -1220B;CUNEIFORM SIGN LU2 TIMES ME PLUS EN;Lo;0;L;;;;;N;;;;; -1220C;CUNEIFORM SIGN LU2 TIMES NE;Lo;0;L;;;;;N;;;;; -1220D;CUNEIFORM SIGN LU2 TIMES NU;Lo;0;L;;;;;N;;;;; -1220E;CUNEIFORM SIGN LU2 TIMES SI PLUS ASH;Lo;0;L;;;;;N;;;;; -1220F;CUNEIFORM SIGN LU2 TIMES SIK2 PLUS BU;Lo;0;L;;;;;N;;;;; -12210;CUNEIFORM SIGN LU2 TIMES TUG2;Lo;0;L;;;;;N;;;;; -12211;CUNEIFORM SIGN LU2 TENU;Lo;0;L;;;;;N;;;;; -12212;CUNEIFORM SIGN LU2 CROSSING LU2;Lo;0;L;;;;;N;;;;; -12213;CUNEIFORM SIGN LU2 OPPOSING LU2;Lo;0;L;;;;;N;;;;; -12214;CUNEIFORM SIGN LU2 SQUARED;Lo;0;L;;;;;N;;;;; -12215;CUNEIFORM SIGN LU2 SHESHIG;Lo;0;L;;;;;N;;;;; -12216;CUNEIFORM SIGN LU3;Lo;0;L;;;;;N;;;;; -12217;CUNEIFORM SIGN LUGAL;Lo;0;L;;;;;N;;;;; -12218;CUNEIFORM SIGN LUGAL OVER LUGAL;Lo;0;L;;;;;N;;;;; -12219;CUNEIFORM SIGN LUGAL OPPOSING LUGAL;Lo;0;L;;;;;N;;;;; -1221A;CUNEIFORM SIGN LUGAL SHESHIG;Lo;0;L;;;;;N;;;;; -1221B;CUNEIFORM SIGN LUH;Lo;0;L;;;;;N;;;;; -1221C;CUNEIFORM SIGN LUL;Lo;0;L;;;;;N;;;;; -1221D;CUNEIFORM SIGN LUM;Lo;0;L;;;;;N;;;;; -1221E;CUNEIFORM SIGN LUM OVER LUM;Lo;0;L;;;;;N;;;;; -1221F;CUNEIFORM SIGN LUM OVER LUM GAR OVER GAR;Lo;0;L;;;;;N;;;;; -12220;CUNEIFORM SIGN MA;Lo;0;L;;;;;N;;;;; -12221;CUNEIFORM SIGN MA TIMES TAK4;Lo;0;L;;;;;N;;;;; -12222;CUNEIFORM SIGN MA GUNU;Lo;0;L;;;;;N;;;;; -12223;CUNEIFORM SIGN MA2;Lo;0;L;;;;;N;;;;; -12224;CUNEIFORM SIGN MAH;Lo;0;L;;;;;N;;;;; -12225;CUNEIFORM SIGN MAR;Lo;0;L;;;;;N;;;;; -12226;CUNEIFORM SIGN MASH;Lo;0;L;;;;;N;;;;; -12227;CUNEIFORM SIGN MASH2;Lo;0;L;;;;;N;;;;; -12228;CUNEIFORM SIGN ME;Lo;0;L;;;;;N;;;;; -12229;CUNEIFORM SIGN MES;Lo;0;L;;;;;N;;;;; -1222A;CUNEIFORM SIGN MI;Lo;0;L;;;;;N;;;;; -1222B;CUNEIFORM SIGN MIN;Lo;0;L;;;;;N;;;;; -1222C;CUNEIFORM SIGN MU;Lo;0;L;;;;;N;;;;; -1222D;CUNEIFORM SIGN MU OVER MU;Lo;0;L;;;;;N;;;;; -1222E;CUNEIFORM SIGN MUG;Lo;0;L;;;;;N;;;;; -1222F;CUNEIFORM SIGN MUG GUNU;Lo;0;L;;;;;N;;;;; -12230;CUNEIFORM SIGN MUNSUB;Lo;0;L;;;;;N;;;;; -12231;CUNEIFORM SIGN MURGU2;Lo;0;L;;;;;N;;;;; -12232;CUNEIFORM SIGN MUSH;Lo;0;L;;;;;N;;;;; -12233;CUNEIFORM SIGN MUSH TIMES A;Lo;0;L;;;;;N;;;;; -12234;CUNEIFORM SIGN MUSH TIMES KUR;Lo;0;L;;;;;N;;;;; -12235;CUNEIFORM SIGN MUSH TIMES ZA;Lo;0;L;;;;;N;;;;; -12236;CUNEIFORM SIGN MUSH OVER MUSH;Lo;0;L;;;;;N;;;;; -12237;CUNEIFORM SIGN MUSH OVER MUSH TIMES A PLUS NA;Lo;0;L;;;;;N;;;;; -12238;CUNEIFORM SIGN MUSH CROSSING MUSH;Lo;0;L;;;;;N;;;;; -12239;CUNEIFORM SIGN MUSH3;Lo;0;L;;;;;N;;;;; -1223A;CUNEIFORM SIGN MUSH3 TIMES A;Lo;0;L;;;;;N;;;;; -1223B;CUNEIFORM SIGN MUSH3 TIMES A PLUS DI;Lo;0;L;;;;;N;;;;; -1223C;CUNEIFORM SIGN MUSH3 TIMES DI;Lo;0;L;;;;;N;;;;; -1223D;CUNEIFORM SIGN MUSH3 GUNU;Lo;0;L;;;;;N;;;;; -1223E;CUNEIFORM SIGN NA;Lo;0;L;;;;;N;;;;; -1223F;CUNEIFORM SIGN NA2;Lo;0;L;;;;;N;;;;; -12240;CUNEIFORM SIGN NAGA;Lo;0;L;;;;;N;;;;; -12241;CUNEIFORM SIGN NAGA INVERTED;Lo;0;L;;;;;N;;;;; -12242;CUNEIFORM SIGN NAGA TIMES SHU TENU;Lo;0;L;;;;;N;;;;; -12243;CUNEIFORM SIGN NAGA OPPOSING NAGA;Lo;0;L;;;;;N;;;;; -12244;CUNEIFORM SIGN NAGAR;Lo;0;L;;;;;N;;;;; -12245;CUNEIFORM SIGN NAM NUTILLU;Lo;0;L;;;;;N;;;;; -12246;CUNEIFORM SIGN NAM;Lo;0;L;;;;;N;;;;; -12247;CUNEIFORM SIGN NAM2;Lo;0;L;;;;;N;;;;; -12248;CUNEIFORM SIGN NE;Lo;0;L;;;;;N;;;;; -12249;CUNEIFORM SIGN NE TIMES A;Lo;0;L;;;;;N;;;;; -1224A;CUNEIFORM SIGN NE TIMES UD;Lo;0;L;;;;;N;;;;; -1224B;CUNEIFORM SIGN NE SHESHIG;Lo;0;L;;;;;N;;;;; -1224C;CUNEIFORM SIGN NI;Lo;0;L;;;;;N;;;;; -1224D;CUNEIFORM SIGN NI TIMES E;Lo;0;L;;;;;N;;;;; -1224E;CUNEIFORM SIGN NI2;Lo;0;L;;;;;N;;;;; -1224F;CUNEIFORM SIGN NIM;Lo;0;L;;;;;N;;;;; -12250;CUNEIFORM SIGN NIM TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -12251;CUNEIFORM SIGN NIM TIMES GAR PLUS GAN2 TENU;Lo;0;L;;;;;N;;;;; -12252;CUNEIFORM SIGN NINDA2;Lo;0;L;;;;;N;;;;; -12253;CUNEIFORM SIGN NINDA2 TIMES AN;Lo;0;L;;;;;N;;;;; -12254;CUNEIFORM SIGN NINDA2 TIMES ASH;Lo;0;L;;;;;N;;;;; -12255;CUNEIFORM SIGN NINDA2 TIMES ASH PLUS ASH;Lo;0;L;;;;;N;;;;; -12256;CUNEIFORM SIGN NINDA2 TIMES GUD;Lo;0;L;;;;;N;;;;; -12257;CUNEIFORM SIGN NINDA2 TIMES ME PLUS GAN2 TENU;Lo;0;L;;;;;N;;;;; -12258;CUNEIFORM SIGN NINDA2 TIMES NE;Lo;0;L;;;;;N;;;;; -12259;CUNEIFORM SIGN NINDA2 TIMES NUN;Lo;0;L;;;;;N;;;;; -1225A;CUNEIFORM SIGN NINDA2 TIMES SHE;Lo;0;L;;;;;N;;;;; -1225B;CUNEIFORM SIGN NINDA2 TIMES SHE PLUS A AN;Lo;0;L;;;;;N;;;;; -1225C;CUNEIFORM SIGN NINDA2 TIMES SHE PLUS ASH;Lo;0;L;;;;;N;;;;; -1225D;CUNEIFORM SIGN NINDA2 TIMES SHE PLUS ASH PLUS ASH;Lo;0;L;;;;;N;;;;; -1225E;CUNEIFORM SIGN NINDA2 TIMES U2 PLUS ASH;Lo;0;L;;;;;N;;;;; -1225F;CUNEIFORM SIGN NINDA2 TIMES USH;Lo;0;L;;;;;N;;;;; -12260;CUNEIFORM SIGN NISAG;Lo;0;L;;;;;N;;;;; -12261;CUNEIFORM SIGN NU;Lo;0;L;;;;;N;;;;; -12262;CUNEIFORM SIGN NU11;Lo;0;L;;;;;N;;;;; -12263;CUNEIFORM SIGN NUN;Lo;0;L;;;;;N;;;;; -12264;CUNEIFORM SIGN NUN LAGAR TIMES GAR;Lo;0;L;;;;;N;;;;; -12265;CUNEIFORM SIGN NUN LAGAR TIMES MASH;Lo;0;L;;;;;N;;;;; -12266;CUNEIFORM SIGN NUN LAGAR TIMES SAL;Lo;0;L;;;;;N;;;;; -12267;CUNEIFORM SIGN NUN LAGAR TIMES SAL OVER NUN LAGAR TIMES SAL;Lo;0;L;;;;;N;;;;; -12268;CUNEIFORM SIGN NUN LAGAR TIMES USH;Lo;0;L;;;;;N;;;;; -12269;CUNEIFORM SIGN NUN TENU;Lo;0;L;;;;;N;;;;; -1226A;CUNEIFORM SIGN NUN OVER NUN;Lo;0;L;;;;;N;;;;; -1226B;CUNEIFORM SIGN NUN CROSSING NUN;Lo;0;L;;;;;N;;;;; -1226C;CUNEIFORM SIGN NUN CROSSING NUN LAGAR OVER LAGAR;Lo;0;L;;;;;N;;;;; -1226D;CUNEIFORM SIGN NUNUZ;Lo;0;L;;;;;N;;;;; -1226E;CUNEIFORM SIGN NUNUZ AB2 TIMES ASHGAB;Lo;0;L;;;;;N;;;;; -1226F;CUNEIFORM SIGN NUNUZ AB2 TIMES BI;Lo;0;L;;;;;N;;;;; -12270;CUNEIFORM SIGN NUNUZ AB2 TIMES DUG;Lo;0;L;;;;;N;;;;; -12271;CUNEIFORM SIGN NUNUZ AB2 TIMES GUD;Lo;0;L;;;;;N;;;;; -12272;CUNEIFORM SIGN NUNUZ AB2 TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -12273;CUNEIFORM SIGN NUNUZ AB2 TIMES KAD3;Lo;0;L;;;;;N;;;;; -12274;CUNEIFORM SIGN NUNUZ AB2 TIMES LA;Lo;0;L;;;;;N;;;;; -12275;CUNEIFORM SIGN NUNUZ AB2 TIMES NE;Lo;0;L;;;;;N;;;;; -12276;CUNEIFORM SIGN NUNUZ AB2 TIMES SILA3;Lo;0;L;;;;;N;;;;; -12277;CUNEIFORM SIGN NUNUZ AB2 TIMES U2;Lo;0;L;;;;;N;;;;; -12278;CUNEIFORM SIGN NUNUZ KISIM5 TIMES BI;Lo;0;L;;;;;N;;;;; -12279;CUNEIFORM SIGN NUNUZ KISIM5 TIMES BI U;Lo;0;L;;;;;N;;;;; -1227A;CUNEIFORM SIGN PA;Lo;0;L;;;;;N;;;;; -1227B;CUNEIFORM SIGN PAD;Lo;0;L;;;;;N;;;;; -1227C;CUNEIFORM SIGN PAN;Lo;0;L;;;;;N;;;;; -1227D;CUNEIFORM SIGN PAP;Lo;0;L;;;;;N;;;;; -1227E;CUNEIFORM SIGN PESH2;Lo;0;L;;;;;N;;;;; -1227F;CUNEIFORM SIGN PI;Lo;0;L;;;;;N;;;;; -12280;CUNEIFORM SIGN PI TIMES A;Lo;0;L;;;;;N;;;;; -12281;CUNEIFORM SIGN PI TIMES AB;Lo;0;L;;;;;N;;;;; -12282;CUNEIFORM SIGN PI TIMES BI;Lo;0;L;;;;;N;;;;; -12283;CUNEIFORM SIGN PI TIMES BU;Lo;0;L;;;;;N;;;;; -12284;CUNEIFORM SIGN PI TIMES E;Lo;0;L;;;;;N;;;;; -12285;CUNEIFORM SIGN PI TIMES I;Lo;0;L;;;;;N;;;;; -12286;CUNEIFORM SIGN PI TIMES IB;Lo;0;L;;;;;N;;;;; -12287;CUNEIFORM SIGN PI TIMES U;Lo;0;L;;;;;N;;;;; -12288;CUNEIFORM SIGN PI TIMES U2;Lo;0;L;;;;;N;;;;; -12289;CUNEIFORM SIGN PI CROSSING PI;Lo;0;L;;;;;N;;;;; -1228A;CUNEIFORM SIGN PIRIG;Lo;0;L;;;;;N;;;;; -1228B;CUNEIFORM SIGN PIRIG TIMES KAL;Lo;0;L;;;;;N;;;;; -1228C;CUNEIFORM SIGN PIRIG TIMES UD;Lo;0;L;;;;;N;;;;; -1228D;CUNEIFORM SIGN PIRIG TIMES ZA;Lo;0;L;;;;;N;;;;; -1228E;CUNEIFORM SIGN PIRIG OPPOSING PIRIG;Lo;0;L;;;;;N;;;;; -1228F;CUNEIFORM SIGN RA;Lo;0;L;;;;;N;;;;; -12290;CUNEIFORM SIGN RAB;Lo;0;L;;;;;N;;;;; -12291;CUNEIFORM SIGN RI;Lo;0;L;;;;;N;;;;; -12292;CUNEIFORM SIGN RU;Lo;0;L;;;;;N;;;;; -12293;CUNEIFORM SIGN SA;Lo;0;L;;;;;N;;;;; -12294;CUNEIFORM SIGN SAG NUTILLU;Lo;0;L;;;;;N;;;;; -12295;CUNEIFORM SIGN SAG;Lo;0;L;;;;;N;;;;; -12296;CUNEIFORM SIGN SAG TIMES A;Lo;0;L;;;;;N;;;;; -12297;CUNEIFORM SIGN SAG TIMES DU;Lo;0;L;;;;;N;;;;; -12298;CUNEIFORM SIGN SAG TIMES DUB;Lo;0;L;;;;;N;;;;; -12299;CUNEIFORM SIGN SAG TIMES HA;Lo;0;L;;;;;N;;;;; -1229A;CUNEIFORM SIGN SAG TIMES KAK;Lo;0;L;;;;;N;;;;; -1229B;CUNEIFORM SIGN SAG TIMES KUR;Lo;0;L;;;;;N;;;;; -1229C;CUNEIFORM SIGN SAG TIMES LUM;Lo;0;L;;;;;N;;;;; -1229D;CUNEIFORM SIGN SAG TIMES MI;Lo;0;L;;;;;N;;;;; -1229E;CUNEIFORM SIGN SAG TIMES NUN;Lo;0;L;;;;;N;;;;; -1229F;CUNEIFORM SIGN SAG TIMES SAL;Lo;0;L;;;;;N;;;;; -122A0;CUNEIFORM SIGN SAG TIMES SHID;Lo;0;L;;;;;N;;;;; -122A1;CUNEIFORM SIGN SAG TIMES TAB;Lo;0;L;;;;;N;;;;; -122A2;CUNEIFORM SIGN SAG TIMES U2;Lo;0;L;;;;;N;;;;; -122A3;CUNEIFORM SIGN SAG TIMES UB;Lo;0;L;;;;;N;;;;; -122A4;CUNEIFORM SIGN SAG TIMES UM;Lo;0;L;;;;;N;;;;; -122A5;CUNEIFORM SIGN SAG TIMES UR;Lo;0;L;;;;;N;;;;; -122A6;CUNEIFORM SIGN SAG TIMES USH;Lo;0;L;;;;;N;;;;; -122A7;CUNEIFORM SIGN SAG OVER SAG;Lo;0;L;;;;;N;;;;; -122A8;CUNEIFORM SIGN SAG GUNU;Lo;0;L;;;;;N;;;;; -122A9;CUNEIFORM SIGN SAL;Lo;0;L;;;;;N;;;;; -122AA;CUNEIFORM SIGN SAL LAGAB TIMES ASH2;Lo;0;L;;;;;N;;;;; -122AB;CUNEIFORM SIGN SANGA2;Lo;0;L;;;;;N;;;;; -122AC;CUNEIFORM SIGN SAR;Lo;0;L;;;;;N;;;;; -122AD;CUNEIFORM SIGN SHA;Lo;0;L;;;;;N;;;;; -122AE;CUNEIFORM SIGN SHA3;Lo;0;L;;;;;N;;;;; -122AF;CUNEIFORM SIGN SHA3 TIMES A;Lo;0;L;;;;;N;;;;; -122B0;CUNEIFORM SIGN SHA3 TIMES BAD;Lo;0;L;;;;;N;;;;; -122B1;CUNEIFORM SIGN SHA3 TIMES GISH;Lo;0;L;;;;;N;;;;; -122B2;CUNEIFORM SIGN SHA3 TIMES NE;Lo;0;L;;;;;N;;;;; -122B3;CUNEIFORM SIGN SHA3 TIMES SHU2;Lo;0;L;;;;;N;;;;; -122B4;CUNEIFORM SIGN SHA3 TIMES TUR;Lo;0;L;;;;;N;;;;; -122B5;CUNEIFORM SIGN SHA3 TIMES U;Lo;0;L;;;;;N;;;;; -122B6;CUNEIFORM SIGN SHA3 TIMES U PLUS A;Lo;0;L;;;;;N;;;;; -122B7;CUNEIFORM SIGN SHA6;Lo;0;L;;;;;N;;;;; -122B8;CUNEIFORM SIGN SHAB6;Lo;0;L;;;;;N;;;;; -122B9;CUNEIFORM SIGN SHAR2;Lo;0;L;;;;;N;;;;; -122BA;CUNEIFORM SIGN SHE;Lo;0;L;;;;;N;;;;; -122BB;CUNEIFORM SIGN SHE HU;Lo;0;L;;;;;N;;;;; -122BC;CUNEIFORM SIGN SHE OVER SHE GAD OVER GAD GAR OVER GAR;Lo;0;L;;;;;N;;;;; -122BD;CUNEIFORM SIGN SHE OVER SHE TAB OVER TAB GAR OVER GAR;Lo;0;L;;;;;N;;;;; -122BE;CUNEIFORM SIGN SHEG9;Lo;0;L;;;;;N;;;;; -122BF;CUNEIFORM SIGN SHEN;Lo;0;L;;;;;N;;;;; -122C0;CUNEIFORM SIGN SHESH;Lo;0;L;;;;;N;;;;; -122C1;CUNEIFORM SIGN SHESH2;Lo;0;L;;;;;N;;;;; -122C2;CUNEIFORM SIGN SHESHLAM;Lo;0;L;;;;;N;;;;; -122C3;CUNEIFORM SIGN SHID;Lo;0;L;;;;;N;;;;; -122C4;CUNEIFORM SIGN SHID TIMES A;Lo;0;L;;;;;N;;;;; -122C5;CUNEIFORM SIGN SHID TIMES IM;Lo;0;L;;;;;N;;;;; -122C6;CUNEIFORM SIGN SHIM;Lo;0;L;;;;;N;;;;; -122C7;CUNEIFORM SIGN SHIM TIMES A;Lo;0;L;;;;;N;;;;; -122C8;CUNEIFORM SIGN SHIM TIMES BAL;Lo;0;L;;;;;N;;;;; -122C9;CUNEIFORM SIGN SHIM TIMES BULUG;Lo;0;L;;;;;N;;;;; -122CA;CUNEIFORM SIGN SHIM TIMES DIN;Lo;0;L;;;;;N;;;;; -122CB;CUNEIFORM SIGN SHIM TIMES GAR;Lo;0;L;;;;;N;;;;; -122CC;CUNEIFORM SIGN SHIM TIMES IGI;Lo;0;L;;;;;N;;;;; -122CD;CUNEIFORM SIGN SHIM TIMES IGI GUNU;Lo;0;L;;;;;N;;;;; -122CE;CUNEIFORM SIGN SHIM TIMES KUSHU2;Lo;0;L;;;;;N;;;;; -122CF;CUNEIFORM SIGN SHIM TIMES LUL;Lo;0;L;;;;;N;;;;; -122D0;CUNEIFORM SIGN SHIM TIMES MUG;Lo;0;L;;;;;N;;;;; -122D1;CUNEIFORM SIGN SHIM TIMES SAL;Lo;0;L;;;;;N;;;;; -122D2;CUNEIFORM SIGN SHINIG;Lo;0;L;;;;;N;;;;; -122D3;CUNEIFORM SIGN SHIR;Lo;0;L;;;;;N;;;;; -122D4;CUNEIFORM SIGN SHIR TENU;Lo;0;L;;;;;N;;;;; -122D5;CUNEIFORM SIGN SHIR OVER SHIR BUR OVER BUR;Lo;0;L;;;;;N;;;;; -122D6;CUNEIFORM SIGN SHITA;Lo;0;L;;;;;N;;;;; -122D7;CUNEIFORM SIGN SHU;Lo;0;L;;;;;N;;;;; -122D8;CUNEIFORM SIGN SHU OVER INVERTED SHU;Lo;0;L;;;;;N;;;;; -122D9;CUNEIFORM SIGN SHU2;Lo;0;L;;;;;N;;;;; -122DA;CUNEIFORM SIGN SHUBUR;Lo;0;L;;;;;N;;;;; -122DB;CUNEIFORM SIGN SI;Lo;0;L;;;;;N;;;;; -122DC;CUNEIFORM SIGN SI GUNU;Lo;0;L;;;;;N;;;;; -122DD;CUNEIFORM SIGN SIG;Lo;0;L;;;;;N;;;;; -122DE;CUNEIFORM SIGN SIG4;Lo;0;L;;;;;N;;;;; -122DF;CUNEIFORM SIGN SIG4 OVER SIG4 SHU2;Lo;0;L;;;;;N;;;;; -122E0;CUNEIFORM SIGN SIK2;Lo;0;L;;;;;N;;;;; -122E1;CUNEIFORM SIGN SILA3;Lo;0;L;;;;;N;;;;; -122E2;CUNEIFORM SIGN SU;Lo;0;L;;;;;N;;;;; -122E3;CUNEIFORM SIGN SU OVER SU;Lo;0;L;;;;;N;;;;; -122E4;CUNEIFORM SIGN SUD;Lo;0;L;;;;;N;;;;; -122E5;CUNEIFORM SIGN SUD2;Lo;0;L;;;;;N;;;;; -122E6;CUNEIFORM SIGN SUHUR;Lo;0;L;;;;;N;;;;; -122E7;CUNEIFORM SIGN SUM;Lo;0;L;;;;;N;;;;; -122E8;CUNEIFORM SIGN SUMASH;Lo;0;L;;;;;N;;;;; -122E9;CUNEIFORM SIGN SUR;Lo;0;L;;;;;N;;;;; -122EA;CUNEIFORM SIGN SUR9;Lo;0;L;;;;;N;;;;; -122EB;CUNEIFORM SIGN TA;Lo;0;L;;;;;N;;;;; -122EC;CUNEIFORM SIGN TA ASTERISK;Lo;0;L;;;;;N;;;;; -122ED;CUNEIFORM SIGN TA TIMES HI;Lo;0;L;;;;;N;;;;; -122EE;CUNEIFORM SIGN TA TIMES MI;Lo;0;L;;;;;N;;;;; -122EF;CUNEIFORM SIGN TA GUNU;Lo;0;L;;;;;N;;;;; -122F0;CUNEIFORM SIGN TAB;Lo;0;L;;;;;N;;;;; -122F1;CUNEIFORM SIGN TAB OVER TAB NI OVER NI DISH OVER DISH;Lo;0;L;;;;;N;;;;; -122F2;CUNEIFORM SIGN TAB SQUARED;Lo;0;L;;;;;N;;;;; -122F3;CUNEIFORM SIGN TAG;Lo;0;L;;;;;N;;;;; -122F4;CUNEIFORM SIGN TAG TIMES BI;Lo;0;L;;;;;N;;;;; -122F5;CUNEIFORM SIGN TAG TIMES GUD;Lo;0;L;;;;;N;;;;; -122F6;CUNEIFORM SIGN TAG TIMES SHE;Lo;0;L;;;;;N;;;;; -122F7;CUNEIFORM SIGN TAG TIMES SHU;Lo;0;L;;;;;N;;;;; -122F8;CUNEIFORM SIGN TAG TIMES TUG2;Lo;0;L;;;;;N;;;;; -122F9;CUNEIFORM SIGN TAG TIMES UD;Lo;0;L;;;;;N;;;;; -122FA;CUNEIFORM SIGN TAK4;Lo;0;L;;;;;N;;;;; -122FB;CUNEIFORM SIGN TAR;Lo;0;L;;;;;N;;;;; -122FC;CUNEIFORM SIGN TE;Lo;0;L;;;;;N;;;;; -122FD;CUNEIFORM SIGN TE GUNU;Lo;0;L;;;;;N;;;;; -122FE;CUNEIFORM SIGN TI;Lo;0;L;;;;;N;;;;; -122FF;CUNEIFORM SIGN TI TENU;Lo;0;L;;;;;N;;;;; -12300;CUNEIFORM SIGN TIL;Lo;0;L;;;;;N;;;;; -12301;CUNEIFORM SIGN TIR;Lo;0;L;;;;;N;;;;; -12302;CUNEIFORM SIGN TIR TIMES TAK4;Lo;0;L;;;;;N;;;;; -12303;CUNEIFORM SIGN TIR OVER TIR;Lo;0;L;;;;;N;;;;; -12304;CUNEIFORM SIGN TIR OVER TIR GAD OVER GAD GAR OVER GAR;Lo;0;L;;;;;N;;;;; -12305;CUNEIFORM SIGN TU;Lo;0;L;;;;;N;;;;; -12306;CUNEIFORM SIGN TUG2;Lo;0;L;;;;;N;;;;; -12307;CUNEIFORM SIGN TUK;Lo;0;L;;;;;N;;;;; -12308;CUNEIFORM SIGN TUM;Lo;0;L;;;;;N;;;;; -12309;CUNEIFORM SIGN TUR;Lo;0;L;;;;;N;;;;; -1230A;CUNEIFORM SIGN TUR OVER TUR ZA OVER ZA;Lo;0;L;;;;;N;;;;; -1230B;CUNEIFORM SIGN U;Lo;0;L;;;;;N;;;;; -1230C;CUNEIFORM SIGN U GUD;Lo;0;L;;;;;N;;;;; -1230D;CUNEIFORM SIGN U U U;Lo;0;L;;;;;N;;;;; -1230E;CUNEIFORM SIGN U OVER U PA OVER PA GAR OVER GAR;Lo;0;L;;;;;N;;;;; -1230F;CUNEIFORM SIGN U OVER U SUR OVER SUR;Lo;0;L;;;;;N;;;;; -12310;CUNEIFORM SIGN U OVER U U REVERSED OVER U REVERSED;Lo;0;L;;;;;N;;;;; -12311;CUNEIFORM SIGN U2;Lo;0;L;;;;;N;;;;; -12312;CUNEIFORM SIGN UB;Lo;0;L;;;;;N;;;;; -12313;CUNEIFORM SIGN UD;Lo;0;L;;;;;N;;;;; -12314;CUNEIFORM SIGN UD KUSHU2;Lo;0;L;;;;;N;;;;; -12315;CUNEIFORM SIGN UD TIMES BAD;Lo;0;L;;;;;N;;;;; -12316;CUNEIFORM SIGN UD TIMES MI;Lo;0;L;;;;;N;;;;; -12317;CUNEIFORM SIGN UD TIMES U PLUS U PLUS U;Lo;0;L;;;;;N;;;;; -12318;CUNEIFORM SIGN UD TIMES U PLUS U PLUS U GUNU;Lo;0;L;;;;;N;;;;; -12319;CUNEIFORM SIGN UD GUNU;Lo;0;L;;;;;N;;;;; -1231A;CUNEIFORM SIGN UD SHESHIG;Lo;0;L;;;;;N;;;;; -1231B;CUNEIFORM SIGN UD SHESHIG TIMES BAD;Lo;0;L;;;;;N;;;;; -1231C;CUNEIFORM SIGN UDUG;Lo;0;L;;;;;N;;;;; -1231D;CUNEIFORM SIGN UM;Lo;0;L;;;;;N;;;;; -1231E;CUNEIFORM SIGN UM TIMES LAGAB;Lo;0;L;;;;;N;;;;; -1231F;CUNEIFORM SIGN UM TIMES ME PLUS DA;Lo;0;L;;;;;N;;;;; -12320;CUNEIFORM SIGN UM TIMES SHA3;Lo;0;L;;;;;N;;;;; -12321;CUNEIFORM SIGN UM TIMES U;Lo;0;L;;;;;N;;;;; -12322;CUNEIFORM SIGN UMBIN;Lo;0;L;;;;;N;;;;; -12323;CUNEIFORM SIGN UMUM;Lo;0;L;;;;;N;;;;; -12324;CUNEIFORM SIGN UMUM TIMES KASKAL;Lo;0;L;;;;;N;;;;; -12325;CUNEIFORM SIGN UMUM TIMES PA;Lo;0;L;;;;;N;;;;; -12326;CUNEIFORM SIGN UN;Lo;0;L;;;;;N;;;;; -12327;CUNEIFORM SIGN UN GUNU;Lo;0;L;;;;;N;;;;; -12328;CUNEIFORM SIGN UR;Lo;0;L;;;;;N;;;;; -12329;CUNEIFORM SIGN UR CROSSING UR;Lo;0;L;;;;;N;;;;; -1232A;CUNEIFORM SIGN UR SHESHIG;Lo;0;L;;;;;N;;;;; -1232B;CUNEIFORM SIGN UR2;Lo;0;L;;;;;N;;;;; -1232C;CUNEIFORM SIGN UR2 TIMES A PLUS HA;Lo;0;L;;;;;N;;;;; -1232D;CUNEIFORM SIGN UR2 TIMES A PLUS NA;Lo;0;L;;;;;N;;;;; -1232E;CUNEIFORM SIGN UR2 TIMES AL;Lo;0;L;;;;;N;;;;; -1232F;CUNEIFORM SIGN UR2 TIMES HA;Lo;0;L;;;;;N;;;;; -12330;CUNEIFORM SIGN UR2 TIMES NUN;Lo;0;L;;;;;N;;;;; -12331;CUNEIFORM SIGN UR2 TIMES U2;Lo;0;L;;;;;N;;;;; -12332;CUNEIFORM SIGN UR2 TIMES U2 PLUS ASH;Lo;0;L;;;;;N;;;;; -12333;CUNEIFORM SIGN UR2 TIMES U2 PLUS BI;Lo;0;L;;;;;N;;;;; -12334;CUNEIFORM SIGN UR4;Lo;0;L;;;;;N;;;;; -12335;CUNEIFORM SIGN URI;Lo;0;L;;;;;N;;;;; -12336;CUNEIFORM SIGN URI3;Lo;0;L;;;;;N;;;;; -12337;CUNEIFORM SIGN URU;Lo;0;L;;;;;N;;;;; -12338;CUNEIFORM SIGN URU TIMES A;Lo;0;L;;;;;N;;;;; -12339;CUNEIFORM SIGN URU TIMES ASHGAB;Lo;0;L;;;;;N;;;;; -1233A;CUNEIFORM SIGN URU TIMES BAR;Lo;0;L;;;;;N;;;;; -1233B;CUNEIFORM SIGN URU TIMES DUN;Lo;0;L;;;;;N;;;;; -1233C;CUNEIFORM SIGN URU TIMES GA;Lo;0;L;;;;;N;;;;; -1233D;CUNEIFORM SIGN URU TIMES GAL;Lo;0;L;;;;;N;;;;; -1233E;CUNEIFORM SIGN URU TIMES GAN2 TENU;Lo;0;L;;;;;N;;;;; -1233F;CUNEIFORM SIGN URU TIMES GAR;Lo;0;L;;;;;N;;;;; -12340;CUNEIFORM SIGN URU TIMES GU;Lo;0;L;;;;;N;;;;; -12341;CUNEIFORM SIGN URU TIMES HA;Lo;0;L;;;;;N;;;;; -12342;CUNEIFORM SIGN URU TIMES IGI;Lo;0;L;;;;;N;;;;; -12343;CUNEIFORM SIGN URU TIMES IM;Lo;0;L;;;;;N;;;;; -12344;CUNEIFORM SIGN URU TIMES ISH;Lo;0;L;;;;;N;;;;; -12345;CUNEIFORM SIGN URU TIMES KI;Lo;0;L;;;;;N;;;;; -12346;CUNEIFORM SIGN URU TIMES LUM;Lo;0;L;;;;;N;;;;; -12347;CUNEIFORM SIGN URU TIMES MIN;Lo;0;L;;;;;N;;;;; -12348;CUNEIFORM SIGN URU TIMES PA;Lo;0;L;;;;;N;;;;; -12349;CUNEIFORM SIGN URU TIMES SHE;Lo;0;L;;;;;N;;;;; -1234A;CUNEIFORM SIGN URU TIMES SIG4;Lo;0;L;;;;;N;;;;; -1234B;CUNEIFORM SIGN URU TIMES TU;Lo;0;L;;;;;N;;;;; -1234C;CUNEIFORM SIGN URU TIMES U PLUS GUD;Lo;0;L;;;;;N;;;;; -1234D;CUNEIFORM SIGN URU TIMES UD;Lo;0;L;;;;;N;;;;; -1234E;CUNEIFORM SIGN URU TIMES URUDA;Lo;0;L;;;;;N;;;;; -1234F;CUNEIFORM SIGN URUDA;Lo;0;L;;;;;N;;;;; -12350;CUNEIFORM SIGN URUDA TIMES U;Lo;0;L;;;;;N;;;;; -12351;CUNEIFORM SIGN USH;Lo;0;L;;;;;N;;;;; -12352;CUNEIFORM SIGN USH TIMES A;Lo;0;L;;;;;N;;;;; -12353;CUNEIFORM SIGN USH TIMES KU;Lo;0;L;;;;;N;;;;; -12354;CUNEIFORM SIGN USH TIMES KUR;Lo;0;L;;;;;N;;;;; -12355;CUNEIFORM SIGN USH TIMES TAK4;Lo;0;L;;;;;N;;;;; -12356;CUNEIFORM SIGN USHX;Lo;0;L;;;;;N;;;;; -12357;CUNEIFORM SIGN USH2;Lo;0;L;;;;;N;;;;; -12358;CUNEIFORM SIGN USHUMX;Lo;0;L;;;;;N;;;;; -12359;CUNEIFORM SIGN UTUKI;Lo;0;L;;;;;N;;;;; -1235A;CUNEIFORM SIGN UZ3;Lo;0;L;;;;;N;;;;; -1235B;CUNEIFORM SIGN UZ3 TIMES KASKAL;Lo;0;L;;;;;N;;;;; -1235C;CUNEIFORM SIGN UZU;Lo;0;L;;;;;N;;;;; -1235D;CUNEIFORM SIGN ZA;Lo;0;L;;;;;N;;;;; -1235E;CUNEIFORM SIGN ZA TENU;Lo;0;L;;;;;N;;;;; -1235F;CUNEIFORM SIGN ZA SQUARED TIMES KUR;Lo;0;L;;;;;N;;;;; -12360;CUNEIFORM SIGN ZAG;Lo;0;L;;;;;N;;;;; -12361;CUNEIFORM SIGN ZAMX;Lo;0;L;;;;;N;;;;; -12362;CUNEIFORM SIGN ZE2;Lo;0;L;;;;;N;;;;; -12363;CUNEIFORM SIGN ZI;Lo;0;L;;;;;N;;;;; -12364;CUNEIFORM SIGN ZI OVER ZI;Lo;0;L;;;;;N;;;;; -12365;CUNEIFORM SIGN ZI3;Lo;0;L;;;;;N;;;;; -12366;CUNEIFORM SIGN ZIB;Lo;0;L;;;;;N;;;;; -12367;CUNEIFORM SIGN ZIB KABA TENU;Lo;0;L;;;;;N;;;;; -12368;CUNEIFORM SIGN ZIG;Lo;0;L;;;;;N;;;;; -12369;CUNEIFORM SIGN ZIZ2;Lo;0;L;;;;;N;;;;; -1236A;CUNEIFORM SIGN ZU;Lo;0;L;;;;;N;;;;; -1236B;CUNEIFORM SIGN ZU5;Lo;0;L;;;;;N;;;;; -1236C;CUNEIFORM SIGN ZU5 TIMES A;Lo;0;L;;;;;N;;;;; -1236D;CUNEIFORM SIGN ZUBUR;Lo;0;L;;;;;N;;;;; -1236E;CUNEIFORM SIGN ZUM;Lo;0;L;;;;;N;;;;; -12400;CUNEIFORM NUMERIC SIGN TWO ASH;Nl;0;L;;;;2;N;;;;; -12401;CUNEIFORM NUMERIC SIGN THREE ASH;Nl;0;L;;;;3;N;;;;; -12402;CUNEIFORM NUMERIC SIGN FOUR ASH;Nl;0;L;;;;4;N;;;;; -12403;CUNEIFORM NUMERIC SIGN FIVE ASH;Nl;0;L;;;;5;N;;;;; -12404;CUNEIFORM NUMERIC SIGN SIX ASH;Nl;0;L;;;;6;N;;;;; -12405;CUNEIFORM NUMERIC SIGN SEVEN ASH;Nl;0;L;;;;7;N;;;;; -12406;CUNEIFORM NUMERIC SIGN EIGHT ASH;Nl;0;L;;;;8;N;;;;; -12407;CUNEIFORM NUMERIC SIGN NINE ASH;Nl;0;L;;;;9;N;;;;; -12408;CUNEIFORM NUMERIC SIGN THREE DISH;Nl;0;L;;;;3;N;;;;; -12409;CUNEIFORM NUMERIC SIGN FOUR DISH;Nl;0;L;;;;4;N;;;;; -1240A;CUNEIFORM NUMERIC SIGN FIVE DISH;Nl;0;L;;;;5;N;;;;; -1240B;CUNEIFORM NUMERIC SIGN SIX DISH;Nl;0;L;;;;6;N;;;;; -1240C;CUNEIFORM NUMERIC SIGN SEVEN DISH;Nl;0;L;;;;7;N;;;;; -1240D;CUNEIFORM NUMERIC SIGN EIGHT DISH;Nl;0;L;;;;8;N;;;;; -1240E;CUNEIFORM NUMERIC SIGN NINE DISH;Nl;0;L;;;;9;N;;;;; -1240F;CUNEIFORM NUMERIC SIGN FOUR U;Nl;0;L;;;;4;N;;;;; -12410;CUNEIFORM NUMERIC SIGN FIVE U;Nl;0;L;;;;5;N;;;;; -12411;CUNEIFORM NUMERIC SIGN SIX U;Nl;0;L;;;;6;N;;;;; -12412;CUNEIFORM NUMERIC SIGN SEVEN U;Nl;0;L;;;;7;N;;;;; -12413;CUNEIFORM NUMERIC SIGN EIGHT U;Nl;0;L;;;;8;N;;;;; -12414;CUNEIFORM NUMERIC SIGN NINE U;Nl;0;L;;;;9;N;;;;; -12415;CUNEIFORM NUMERIC SIGN ONE GESH2;Nl;0;L;;;;1;N;;;;; -12416;CUNEIFORM NUMERIC SIGN TWO GESH2;Nl;0;L;;;;2;N;;;;; -12417;CUNEIFORM NUMERIC SIGN THREE GESH2;Nl;0;L;;;;3;N;;;;; -12418;CUNEIFORM NUMERIC SIGN FOUR GESH2;Nl;0;L;;;;4;N;;;;; -12419;CUNEIFORM NUMERIC SIGN FIVE GESH2;Nl;0;L;;;;5;N;;;;; -1241A;CUNEIFORM NUMERIC SIGN SIX GESH2;Nl;0;L;;;;6;N;;;;; -1241B;CUNEIFORM NUMERIC SIGN SEVEN GESH2;Nl;0;L;;;;7;N;;;;; -1241C;CUNEIFORM NUMERIC SIGN EIGHT GESH2;Nl;0;L;;;;8;N;;;;; -1241D;CUNEIFORM NUMERIC SIGN NINE GESH2;Nl;0;L;;;;9;N;;;;; -1241E;CUNEIFORM NUMERIC SIGN ONE GESHU;Nl;0;L;;;;1;N;;;;; -1241F;CUNEIFORM NUMERIC SIGN TWO GESHU;Nl;0;L;;;;2;N;;;;; -12420;CUNEIFORM NUMERIC SIGN THREE GESHU;Nl;0;L;;;;3;N;;;;; -12421;CUNEIFORM NUMERIC SIGN FOUR GESHU;Nl;0;L;;;;4;N;;;;; -12422;CUNEIFORM NUMERIC SIGN FIVE GESHU;Nl;0;L;;;;5;N;;;;; -12423;CUNEIFORM NUMERIC SIGN TWO SHAR2;Nl;0;L;;;;2;N;;;;; -12424;CUNEIFORM NUMERIC SIGN THREE SHAR2;Nl;0;L;;;;3;N;;;;; -12425;CUNEIFORM NUMERIC SIGN THREE SHAR2 VARIANT FORM;Nl;0;L;;;;3;N;;;;; -12426;CUNEIFORM NUMERIC SIGN FOUR SHAR2;Nl;0;L;;;;4;N;;;;; -12427;CUNEIFORM NUMERIC SIGN FIVE SHAR2;Nl;0;L;;;;5;N;;;;; -12428;CUNEIFORM NUMERIC SIGN SIX SHAR2;Nl;0;L;;;;6;N;;;;; -12429;CUNEIFORM NUMERIC SIGN SEVEN SHAR2;Nl;0;L;;;;7;N;;;;; -1242A;CUNEIFORM NUMERIC SIGN EIGHT SHAR2;Nl;0;L;;;;8;N;;;;; -1242B;CUNEIFORM NUMERIC SIGN NINE SHAR2;Nl;0;L;;;;9;N;;;;; -1242C;CUNEIFORM NUMERIC SIGN ONE SHARU;Nl;0;L;;;;1;N;;;;; -1242D;CUNEIFORM NUMERIC SIGN TWO SHARU;Nl;0;L;;;;2;N;;;;; -1242E;CUNEIFORM NUMERIC SIGN THREE SHARU;Nl;0;L;;;;3;N;;;;; -1242F;CUNEIFORM NUMERIC SIGN THREE SHARU VARIANT FORM;Nl;0;L;;;;3;N;;;;; -12430;CUNEIFORM NUMERIC SIGN FOUR SHARU;Nl;0;L;;;;4;N;;;;; -12431;CUNEIFORM NUMERIC SIGN FIVE SHARU;Nl;0;L;;;;5;N;;;;; -12432;CUNEIFORM NUMERIC SIGN SHAR2 TIMES GAL PLUS DISH;Nl;0;L;;;;;N;;;;; -12433;CUNEIFORM NUMERIC SIGN SHAR2 TIMES GAL PLUS MIN;Nl;0;L;;;;;N;;;;; -12434;CUNEIFORM NUMERIC SIGN ONE BURU;Nl;0;L;;;;1;N;;;;; -12435;CUNEIFORM NUMERIC SIGN TWO BURU;Nl;0;L;;;;2;N;;;;; -12436;CUNEIFORM NUMERIC SIGN THREE BURU;Nl;0;L;;;;3;N;;;;; -12437;CUNEIFORM NUMERIC SIGN THREE BURU VARIANT FORM;Nl;0;L;;;;3;N;;;;; -12438;CUNEIFORM NUMERIC SIGN FOUR BURU;Nl;0;L;;;;4;N;;;;; -12439;CUNEIFORM NUMERIC SIGN FIVE BURU;Nl;0;L;;;;5;N;;;;; -1243A;CUNEIFORM NUMERIC SIGN THREE VARIANT FORM ESH16;Nl;0;L;;;;3;N;;;;; -1243B;CUNEIFORM NUMERIC SIGN THREE VARIANT FORM ESH21;Nl;0;L;;;;3;N;;;;; -1243C;CUNEIFORM NUMERIC SIGN FOUR VARIANT FORM LIMMU;Nl;0;L;;;;4;N;;;;; -1243D;CUNEIFORM NUMERIC SIGN FOUR VARIANT FORM LIMMU4;Nl;0;L;;;;4;N;;;;; -1243E;CUNEIFORM NUMERIC SIGN FOUR VARIANT FORM LIMMU A;Nl;0;L;;;;4;N;;;;; -1243F;CUNEIFORM NUMERIC SIGN FOUR VARIANT FORM LIMMU B;Nl;0;L;;;;4;N;;;;; -12440;CUNEIFORM NUMERIC SIGN SIX VARIANT FORM ASH9;Nl;0;L;;;;6;N;;;;; -12441;CUNEIFORM NUMERIC SIGN SEVEN VARIANT FORM IMIN3;Nl;0;L;;;;7;N;;;;; -12442;CUNEIFORM NUMERIC SIGN SEVEN VARIANT FORM IMIN A;Nl;0;L;;;;7;N;;;;; -12443;CUNEIFORM NUMERIC SIGN SEVEN VARIANT FORM IMIN B;Nl;0;L;;;;7;N;;;;; -12444;CUNEIFORM NUMERIC SIGN EIGHT VARIANT FORM USSU;Nl;0;L;;;;8;N;;;;; -12445;CUNEIFORM NUMERIC SIGN EIGHT VARIANT FORM USSU3;Nl;0;L;;;;8;N;;;;; -12446;CUNEIFORM NUMERIC SIGN NINE VARIANT FORM ILIMMU;Nl;0;L;;;;9;N;;;;; -12447;CUNEIFORM NUMERIC SIGN NINE VARIANT FORM ILIMMU3;Nl;0;L;;;;9;N;;;;; -12448;CUNEIFORM NUMERIC SIGN NINE VARIANT FORM ILIMMU4;Nl;0;L;;;;9;N;;;;; -12449;CUNEIFORM NUMERIC SIGN NINE VARIANT FORM ILIMMU A;Nl;0;L;;;;9;N;;;;; -1244A;CUNEIFORM NUMERIC SIGN TWO ASH TENU;Nl;0;L;;;;2;N;;;;; -1244B;CUNEIFORM NUMERIC SIGN THREE ASH TENU;Nl;0;L;;;;3;N;;;;; -1244C;CUNEIFORM NUMERIC SIGN FOUR ASH TENU;Nl;0;L;;;;4;N;;;;; -1244D;CUNEIFORM NUMERIC SIGN FIVE ASH TENU;Nl;0;L;;;;5;N;;;;; -1244E;CUNEIFORM NUMERIC SIGN SIX ASH TENU;Nl;0;L;;;;6;N;;;;; -1244F;CUNEIFORM NUMERIC SIGN ONE BAN2;Nl;0;L;;;;1;N;;;;; -12450;CUNEIFORM NUMERIC SIGN TWO BAN2;Nl;0;L;;;;2;N;;;;; -12451;CUNEIFORM NUMERIC SIGN THREE BAN2;Nl;0;L;;;;3;N;;;;; -12452;CUNEIFORM NUMERIC SIGN FOUR BAN2;Nl;0;L;;;;4;N;;;;; -12453;CUNEIFORM NUMERIC SIGN FOUR BAN2 VARIANT FORM;Nl;0;L;;;;4;N;;;;; -12454;CUNEIFORM NUMERIC SIGN FIVE BAN2;Nl;0;L;;;;5;N;;;;; -12455;CUNEIFORM NUMERIC SIGN FIVE BAN2 VARIANT FORM;Nl;0;L;;;;5;N;;;;; -12456;CUNEIFORM NUMERIC SIGN NIGIDAMIN;Nl;0;L;;;;;N;;;;; -12457;CUNEIFORM NUMERIC SIGN NIGIDAESH;Nl;0;L;;;;;N;;;;; -12458;CUNEIFORM NUMERIC SIGN ONE ESHE3;Nl;0;L;;;;1;N;;;;; -12459;CUNEIFORM NUMERIC SIGN TWO ESHE3;Nl;0;L;;;;2;N;;;;; -1245A;CUNEIFORM NUMERIC SIGN ONE THIRD DISH;Nl;0;L;;;;1/3;N;;;;; -1245B;CUNEIFORM NUMERIC SIGN TWO THIRDS DISH;Nl;0;L;;;;2/3;N;;;;; -1245C;CUNEIFORM NUMERIC SIGN FIVE SIXTHS DISH;Nl;0;L;;;;5/6;N;;;;; -1245D;CUNEIFORM NUMERIC SIGN ONE THIRD VARIANT FORM A;Nl;0;L;;;;1/3;N;;;;; -1245E;CUNEIFORM NUMERIC SIGN TWO THIRDS VARIANT FORM A;Nl;0;L;;;;2/3;N;;;;; -1245F;CUNEIFORM NUMERIC SIGN ONE EIGHTH ASH;Nl;0;L;;;;1/8;N;;;;; -12460;CUNEIFORM NUMERIC SIGN ONE QUARTER ASH;Nl;0;L;;;;1/4;N;;;;; -12461;CUNEIFORM NUMERIC SIGN OLD ASSYRIAN ONE SIXTH;Nl;0;L;;;;1/6;N;;;;; -12462;CUNEIFORM NUMERIC SIGN OLD ASSYRIAN ONE QUARTER;Nl;0;L;;;;1/4;N;;;;; -12470;CUNEIFORM PUNCTUATION SIGN OLD ASSYRIAN WORD DIVIDER;Po;0;L;;;;;N;;;;; -12471;CUNEIFORM PUNCTUATION SIGN VERTICAL COLON;Po;0;L;;;;;N;;;;; -12472;CUNEIFORM PUNCTUATION SIGN DIAGONAL COLON;Po;0;L;;;;;N;;;;; -12473;CUNEIFORM PUNCTUATION SIGN DIAGONAL TRICOLON;Po;0;L;;;;;N;;;;; -1D000;BYZANTINE MUSICAL SYMBOL PSILI;So;0;L;;;;;N;;;;; -1D001;BYZANTINE MUSICAL SYMBOL DASEIA;So;0;L;;;;;N;;;;; -1D002;BYZANTINE MUSICAL SYMBOL PERISPOMENI;So;0;L;;;;;N;;;;; -1D003;BYZANTINE MUSICAL SYMBOL OXEIA EKFONITIKON;So;0;L;;;;;N;;;;; -1D004;BYZANTINE MUSICAL SYMBOL OXEIA DIPLI;So;0;L;;;;;N;;;;; -1D005;BYZANTINE MUSICAL SYMBOL VAREIA EKFONITIKON;So;0;L;;;;;N;;;;; -1D006;BYZANTINE MUSICAL SYMBOL VAREIA DIPLI;So;0;L;;;;;N;;;;; -1D007;BYZANTINE MUSICAL SYMBOL KATHISTI;So;0;L;;;;;N;;;;; -1D008;BYZANTINE MUSICAL SYMBOL SYRMATIKI;So;0;L;;;;;N;;;;; -1D009;BYZANTINE MUSICAL SYMBOL PARAKLITIKI;So;0;L;;;;;N;;;;; -1D00A;BYZANTINE MUSICAL SYMBOL YPOKRISIS;So;0;L;;;;;N;;;;; -1D00B;BYZANTINE MUSICAL SYMBOL YPOKRISIS DIPLI;So;0;L;;;;;N;;;;; -1D00C;BYZANTINE MUSICAL SYMBOL KREMASTI;So;0;L;;;;;N;;;;; -1D00D;BYZANTINE MUSICAL SYMBOL APESO EKFONITIKON;So;0;L;;;;;N;;;;; -1D00E;BYZANTINE MUSICAL SYMBOL EXO EKFONITIKON;So;0;L;;;;;N;;;;; -1D00F;BYZANTINE MUSICAL SYMBOL TELEIA;So;0;L;;;;;N;;;;; -1D010;BYZANTINE MUSICAL SYMBOL KENTIMATA;So;0;L;;;;;N;;;;; -1D011;BYZANTINE MUSICAL SYMBOL APOSTROFOS;So;0;L;;;;;N;;;;; -1D012;BYZANTINE MUSICAL SYMBOL APOSTROFOS DIPLI;So;0;L;;;;;N;;;;; -1D013;BYZANTINE MUSICAL SYMBOL SYNEVMA;So;0;L;;;;;N;;;;; -1D014;BYZANTINE MUSICAL SYMBOL THITA;So;0;L;;;;;N;;;;; -1D015;BYZANTINE MUSICAL SYMBOL OLIGON ARCHAION;So;0;L;;;;;N;;;;; -1D016;BYZANTINE MUSICAL SYMBOL GORGON ARCHAION;So;0;L;;;;;N;;;;; -1D017;BYZANTINE MUSICAL SYMBOL PSILON;So;0;L;;;;;N;;;;; -1D018;BYZANTINE MUSICAL SYMBOL CHAMILON;So;0;L;;;;;N;;;;; -1D019;BYZANTINE MUSICAL SYMBOL VATHY;So;0;L;;;;;N;;;;; -1D01A;BYZANTINE MUSICAL SYMBOL ISON ARCHAION;So;0;L;;;;;N;;;;; -1D01B;BYZANTINE MUSICAL SYMBOL KENTIMA ARCHAION;So;0;L;;;;;N;;;;; -1D01C;BYZANTINE MUSICAL SYMBOL KENTIMATA ARCHAION;So;0;L;;;;;N;;;;; -1D01D;BYZANTINE MUSICAL SYMBOL SAXIMATA;So;0;L;;;;;N;;;;; -1D01E;BYZANTINE MUSICAL SYMBOL PARICHON;So;0;L;;;;;N;;;;; -1D01F;BYZANTINE MUSICAL SYMBOL STAVROS APODEXIA;So;0;L;;;;;N;;;;; -1D020;BYZANTINE MUSICAL SYMBOL OXEIAI ARCHAION;So;0;L;;;;;N;;;;; -1D021;BYZANTINE MUSICAL SYMBOL VAREIAI ARCHAION;So;0;L;;;;;N;;;;; -1D022;BYZANTINE MUSICAL SYMBOL APODERMA ARCHAION;So;0;L;;;;;N;;;;; -1D023;BYZANTINE MUSICAL SYMBOL APOTHEMA;So;0;L;;;;;N;;;;; -1D024;BYZANTINE MUSICAL SYMBOL KLASMA;So;0;L;;;;;N;;;;; -1D025;BYZANTINE MUSICAL SYMBOL REVMA;So;0;L;;;;;N;;;;; -1D026;BYZANTINE MUSICAL SYMBOL PIASMA ARCHAION;So;0;L;;;;;N;;;;; -1D027;BYZANTINE MUSICAL SYMBOL TINAGMA;So;0;L;;;;;N;;;;; -1D028;BYZANTINE MUSICAL SYMBOL ANATRICHISMA;So;0;L;;;;;N;;;;; -1D029;BYZANTINE MUSICAL SYMBOL SEISMA;So;0;L;;;;;N;;;;; -1D02A;BYZANTINE MUSICAL SYMBOL SYNAGMA ARCHAION;So;0;L;;;;;N;;;;; -1D02B;BYZANTINE MUSICAL SYMBOL SYNAGMA META STAVROU;So;0;L;;;;;N;;;;; -1D02C;BYZANTINE MUSICAL SYMBOL OYRANISMA ARCHAION;So;0;L;;;;;N;;;;; -1D02D;BYZANTINE MUSICAL SYMBOL THEMA;So;0;L;;;;;N;;;;; -1D02E;BYZANTINE MUSICAL SYMBOL LEMOI;So;0;L;;;;;N;;;;; -1D02F;BYZANTINE MUSICAL SYMBOL DYO;So;0;L;;;;;N;;;;; -1D030;BYZANTINE MUSICAL SYMBOL TRIA;So;0;L;;;;;N;;;;; -1D031;BYZANTINE MUSICAL SYMBOL TESSERA;So;0;L;;;;;N;;;;; -1D032;BYZANTINE MUSICAL SYMBOL KRATIMATA;So;0;L;;;;;N;;;;; -1D033;BYZANTINE MUSICAL SYMBOL APESO EXO NEO;So;0;L;;;;;N;;;;; -1D034;BYZANTINE MUSICAL SYMBOL FTHORA ARCHAION;So;0;L;;;;;N;;;;; -1D035;BYZANTINE MUSICAL SYMBOL IMIFTHORA;So;0;L;;;;;N;;;;; -1D036;BYZANTINE MUSICAL SYMBOL TROMIKON ARCHAION;So;0;L;;;;;N;;;;; -1D037;BYZANTINE MUSICAL SYMBOL KATAVA TROMIKON;So;0;L;;;;;N;;;;; -1D038;BYZANTINE MUSICAL SYMBOL PELASTON;So;0;L;;;;;N;;;;; -1D039;BYZANTINE MUSICAL SYMBOL PSIFISTON;So;0;L;;;;;N;;;;; -1D03A;BYZANTINE MUSICAL SYMBOL KONTEVMA;So;0;L;;;;;N;;;;; -1D03B;BYZANTINE MUSICAL SYMBOL CHOREVMA ARCHAION;So;0;L;;;;;N;;;;; -1D03C;BYZANTINE MUSICAL SYMBOL RAPISMA;So;0;L;;;;;N;;;;; -1D03D;BYZANTINE MUSICAL SYMBOL PARAKALESMA ARCHAION;So;0;L;;;;;N;;;;; -1D03E;BYZANTINE MUSICAL SYMBOL PARAKLITIKI ARCHAION;So;0;L;;;;;N;;;;; -1D03F;BYZANTINE MUSICAL SYMBOL ICHADIN;So;0;L;;;;;N;;;;; -1D040;BYZANTINE MUSICAL SYMBOL NANA;So;0;L;;;;;N;;;;; -1D041;BYZANTINE MUSICAL SYMBOL PETASMA;So;0;L;;;;;N;;;;; -1D042;BYZANTINE MUSICAL SYMBOL KONTEVMA ALLO;So;0;L;;;;;N;;;;; -1D043;BYZANTINE MUSICAL SYMBOL TROMIKON ALLO;So;0;L;;;;;N;;;;; -1D044;BYZANTINE MUSICAL SYMBOL STRAGGISMATA;So;0;L;;;;;N;;;;; -1D045;BYZANTINE MUSICAL SYMBOL GRONTHISMATA;So;0;L;;;;;N;;;;; -1D046;BYZANTINE MUSICAL SYMBOL ISON NEO;So;0;L;;;;;N;;;;; -1D047;BYZANTINE MUSICAL SYMBOL OLIGON NEO;So;0;L;;;;;N;;;;; -1D048;BYZANTINE MUSICAL SYMBOL OXEIA NEO;So;0;L;;;;;N;;;;; -1D049;BYZANTINE MUSICAL SYMBOL PETASTI;So;0;L;;;;;N;;;;; -1D04A;BYZANTINE MUSICAL SYMBOL KOUFISMA;So;0;L;;;;;N;;;;; -1D04B;BYZANTINE MUSICAL SYMBOL PETASTOKOUFISMA;So;0;L;;;;;N;;;;; -1D04C;BYZANTINE MUSICAL SYMBOL KRATIMOKOUFISMA;So;0;L;;;;;N;;;;; -1D04D;BYZANTINE MUSICAL SYMBOL PELASTON NEO;So;0;L;;;;;N;;;;; -1D04E;BYZANTINE MUSICAL SYMBOL KENTIMATA NEO ANO;So;0;L;;;;;N;;;;; -1D04F;BYZANTINE MUSICAL SYMBOL KENTIMA NEO ANO;So;0;L;;;;;N;;;;; -1D050;BYZANTINE MUSICAL SYMBOL YPSILI;So;0;L;;;;;N;;;;; -1D051;BYZANTINE MUSICAL SYMBOL APOSTROFOS NEO;So;0;L;;;;;N;;;;; -1D052;BYZANTINE MUSICAL SYMBOL APOSTROFOI SYNDESMOS NEO;So;0;L;;;;;N;;;;; -1D053;BYZANTINE MUSICAL SYMBOL YPORROI;So;0;L;;;;;N;;;;; -1D054;BYZANTINE MUSICAL SYMBOL KRATIMOYPORROON;So;0;L;;;;;N;;;;; -1D055;BYZANTINE MUSICAL SYMBOL ELAFRON;So;0;L;;;;;N;;;;; -1D056;BYZANTINE MUSICAL SYMBOL CHAMILI;So;0;L;;;;;N;;;;; -1D057;BYZANTINE MUSICAL SYMBOL MIKRON ISON;So;0;L;;;;;N;;;;; -1D058;BYZANTINE MUSICAL SYMBOL VAREIA NEO;So;0;L;;;;;N;;;;; -1D059;BYZANTINE MUSICAL SYMBOL PIASMA NEO;So;0;L;;;;;N;;;;; -1D05A;BYZANTINE MUSICAL SYMBOL PSIFISTON NEO;So;0;L;;;;;N;;;;; -1D05B;BYZANTINE MUSICAL SYMBOL OMALON;So;0;L;;;;;N;;;;; -1D05C;BYZANTINE MUSICAL SYMBOL ANTIKENOMA;So;0;L;;;;;N;;;;; -1D05D;BYZANTINE MUSICAL SYMBOL LYGISMA;So;0;L;;;;;N;;;;; -1D05E;BYZANTINE MUSICAL SYMBOL PARAKLITIKI NEO;So;0;L;;;;;N;;;;; -1D05F;BYZANTINE MUSICAL SYMBOL PARAKALESMA NEO;So;0;L;;;;;N;;;;; -1D060;BYZANTINE MUSICAL SYMBOL ETERON PARAKALESMA;So;0;L;;;;;N;;;;; -1D061;BYZANTINE MUSICAL SYMBOL KYLISMA;So;0;L;;;;;N;;;;; -1D062;BYZANTINE MUSICAL SYMBOL ANTIKENOKYLISMA;So;0;L;;;;;N;;;;; -1D063;BYZANTINE MUSICAL SYMBOL TROMIKON NEO;So;0;L;;;;;N;;;;; -1D064;BYZANTINE MUSICAL SYMBOL EKSTREPTON;So;0;L;;;;;N;;;;; -1D065;BYZANTINE MUSICAL SYMBOL SYNAGMA NEO;So;0;L;;;;;N;;;;; -1D066;BYZANTINE MUSICAL SYMBOL SYRMA;So;0;L;;;;;N;;;;; -1D067;BYZANTINE MUSICAL SYMBOL CHOREVMA NEO;So;0;L;;;;;N;;;;; -1D068;BYZANTINE MUSICAL SYMBOL EPEGERMA;So;0;L;;;;;N;;;;; -1D069;BYZANTINE MUSICAL SYMBOL SEISMA NEO;So;0;L;;;;;N;;;;; -1D06A;BYZANTINE MUSICAL SYMBOL XIRON KLASMA;So;0;L;;;;;N;;;;; -1D06B;BYZANTINE MUSICAL SYMBOL TROMIKOPSIFISTON;So;0;L;;;;;N;;;;; -1D06C;BYZANTINE MUSICAL SYMBOL PSIFISTOLYGISMA;So;0;L;;;;;N;;;;; -1D06D;BYZANTINE MUSICAL SYMBOL TROMIKOLYGISMA;So;0;L;;;;;N;;;;; -1D06E;BYZANTINE MUSICAL SYMBOL TROMIKOPARAKALESMA;So;0;L;;;;;N;;;;; -1D06F;BYZANTINE MUSICAL SYMBOL PSIFISTOPARAKALESMA;So;0;L;;;;;N;;;;; -1D070;BYZANTINE MUSICAL SYMBOL TROMIKOSYNAGMA;So;0;L;;;;;N;;;;; -1D071;BYZANTINE MUSICAL SYMBOL PSIFISTOSYNAGMA;So;0;L;;;;;N;;;;; -1D072;BYZANTINE MUSICAL SYMBOL GORGOSYNTHETON;So;0;L;;;;;N;;;;; -1D073;BYZANTINE MUSICAL SYMBOL ARGOSYNTHETON;So;0;L;;;;;N;;;;; -1D074;BYZANTINE MUSICAL SYMBOL ETERON ARGOSYNTHETON;So;0;L;;;;;N;;;;; -1D075;BYZANTINE MUSICAL SYMBOL OYRANISMA NEO;So;0;L;;;;;N;;;;; -1D076;BYZANTINE MUSICAL SYMBOL THEMATISMOS ESO;So;0;L;;;;;N;;;;; -1D077;BYZANTINE MUSICAL SYMBOL THEMATISMOS EXO;So;0;L;;;;;N;;;;; -1D078;BYZANTINE MUSICAL SYMBOL THEMA APLOUN;So;0;L;;;;;N;;;;; -1D079;BYZANTINE MUSICAL SYMBOL THES KAI APOTHES;So;0;L;;;;;N;;;;; -1D07A;BYZANTINE MUSICAL SYMBOL KATAVASMA;So;0;L;;;;;N;;;;; -1D07B;BYZANTINE MUSICAL SYMBOL ENDOFONON;So;0;L;;;;;N;;;;; -1D07C;BYZANTINE MUSICAL SYMBOL YFEN KATO;So;0;L;;;;;N;;;;; -1D07D;BYZANTINE MUSICAL SYMBOL YFEN ANO;So;0;L;;;;;N;;;;; -1D07E;BYZANTINE MUSICAL SYMBOL STAVROS;So;0;L;;;;;N;;;;; -1D07F;BYZANTINE MUSICAL SYMBOL KLASMA ANO;So;0;L;;;;;N;;;;; -1D080;BYZANTINE MUSICAL SYMBOL DIPLI ARCHAION;So;0;L;;;;;N;;;;; -1D081;BYZANTINE MUSICAL SYMBOL KRATIMA ARCHAION;So;0;L;;;;;N;;;;; -1D082;BYZANTINE MUSICAL SYMBOL KRATIMA ALLO;So;0;L;;;;;N;;;;; -1D083;BYZANTINE MUSICAL SYMBOL KRATIMA NEO;So;0;L;;;;;N;;;;; -1D084;BYZANTINE MUSICAL SYMBOL APODERMA NEO;So;0;L;;;;;N;;;;; -1D085;BYZANTINE MUSICAL SYMBOL APLI;So;0;L;;;;;N;;;;; -1D086;BYZANTINE MUSICAL SYMBOL DIPLI;So;0;L;;;;;N;;;;; -1D087;BYZANTINE MUSICAL SYMBOL TRIPLI;So;0;L;;;;;N;;;;; -1D088;BYZANTINE MUSICAL SYMBOL TETRAPLI;So;0;L;;;;;N;;;;; -1D089;BYZANTINE MUSICAL SYMBOL KORONIS;So;0;L;;;;;N;;;;; -1D08A;BYZANTINE MUSICAL SYMBOL LEIMMA ENOS CHRONOU;So;0;L;;;;;N;;;;; -1D08B;BYZANTINE MUSICAL SYMBOL LEIMMA DYO CHRONON;So;0;L;;;;;N;;;;; -1D08C;BYZANTINE MUSICAL SYMBOL LEIMMA TRION CHRONON;So;0;L;;;;;N;;;;; -1D08D;BYZANTINE MUSICAL SYMBOL LEIMMA TESSARON CHRONON;So;0;L;;;;;N;;;;; -1D08E;BYZANTINE MUSICAL SYMBOL LEIMMA IMISEOS CHRONOU;So;0;L;;;;;N;;;;; -1D08F;BYZANTINE MUSICAL SYMBOL GORGON NEO ANO;So;0;L;;;;;N;;;;; -1D090;BYZANTINE MUSICAL SYMBOL GORGON PARESTIGMENON ARISTERA;So;0;L;;;;;N;;;;; -1D091;BYZANTINE MUSICAL SYMBOL GORGON PARESTIGMENON DEXIA;So;0;L;;;;;N;;;;; -1D092;BYZANTINE MUSICAL SYMBOL DIGORGON;So;0;L;;;;;N;;;;; -1D093;BYZANTINE MUSICAL SYMBOL DIGORGON PARESTIGMENON ARISTERA KATO;So;0;L;;;;;N;;;;; -1D094;BYZANTINE MUSICAL SYMBOL DIGORGON PARESTIGMENON ARISTERA ANO;So;0;L;;;;;N;;;;; -1D095;BYZANTINE MUSICAL SYMBOL DIGORGON PARESTIGMENON DEXIA;So;0;L;;;;;N;;;;; -1D096;BYZANTINE MUSICAL SYMBOL TRIGORGON;So;0;L;;;;;N;;;;; -1D097;BYZANTINE MUSICAL SYMBOL ARGON;So;0;L;;;;;N;;;;; -1D098;BYZANTINE MUSICAL SYMBOL IMIDIARGON;So;0;L;;;;;N;;;;; -1D099;BYZANTINE MUSICAL SYMBOL DIARGON;So;0;L;;;;;N;;;;; -1D09A;BYZANTINE MUSICAL SYMBOL AGOGI POLI ARGI;So;0;L;;;;;N;;;;; -1D09B;BYZANTINE MUSICAL SYMBOL AGOGI ARGOTERI;So;0;L;;;;;N;;;;; -1D09C;BYZANTINE MUSICAL SYMBOL AGOGI ARGI;So;0;L;;;;;N;;;;; -1D09D;BYZANTINE MUSICAL SYMBOL AGOGI METRIA;So;0;L;;;;;N;;;;; -1D09E;BYZANTINE MUSICAL SYMBOL AGOGI MESI;So;0;L;;;;;N;;;;; -1D09F;BYZANTINE MUSICAL SYMBOL AGOGI GORGI;So;0;L;;;;;N;;;;; -1D0A0;BYZANTINE MUSICAL SYMBOL AGOGI GORGOTERI;So;0;L;;;;;N;;;;; -1D0A1;BYZANTINE MUSICAL SYMBOL AGOGI POLI GORGI;So;0;L;;;;;N;;;;; -1D0A2;BYZANTINE MUSICAL SYMBOL MARTYRIA PROTOS ICHOS;So;0;L;;;;;N;;;;; -1D0A3;BYZANTINE MUSICAL SYMBOL MARTYRIA ALLI PROTOS ICHOS;So;0;L;;;;;N;;;;; -1D0A4;BYZANTINE MUSICAL SYMBOL MARTYRIA DEYTEROS ICHOS;So;0;L;;;;;N;;;;; -1D0A5;BYZANTINE MUSICAL SYMBOL MARTYRIA ALLI DEYTEROS ICHOS;So;0;L;;;;;N;;;;; -1D0A6;BYZANTINE MUSICAL SYMBOL MARTYRIA TRITOS ICHOS;So;0;L;;;;;N;;;;; -1D0A7;BYZANTINE MUSICAL SYMBOL MARTYRIA TRIFONIAS;So;0;L;;;;;N;;;;; -1D0A8;BYZANTINE MUSICAL SYMBOL MARTYRIA TETARTOS ICHOS;So;0;L;;;;;N;;;;; -1D0A9;BYZANTINE MUSICAL SYMBOL MARTYRIA TETARTOS LEGETOS ICHOS;So;0;L;;;;;N;;;;; -1D0AA;BYZANTINE MUSICAL SYMBOL MARTYRIA LEGETOS ICHOS;So;0;L;;;;;N;;;;; -1D0AB;BYZANTINE MUSICAL SYMBOL MARTYRIA PLAGIOS ICHOS;So;0;L;;;;;N;;;;; -1D0AC;BYZANTINE MUSICAL SYMBOL ISAKIA TELOUS ICHIMATOS;So;0;L;;;;;N;;;;; -1D0AD;BYZANTINE MUSICAL SYMBOL APOSTROFOI TELOUS ICHIMATOS;So;0;L;;;;;N;;;;; -1D0AE;BYZANTINE MUSICAL SYMBOL FANEROSIS TETRAFONIAS;So;0;L;;;;;N;;;;; -1D0AF;BYZANTINE MUSICAL SYMBOL FANEROSIS MONOFONIAS;So;0;L;;;;;N;;;;; -1D0B0;BYZANTINE MUSICAL SYMBOL FANEROSIS DIFONIAS;So;0;L;;;;;N;;;;; -1D0B1;BYZANTINE MUSICAL SYMBOL MARTYRIA VARYS ICHOS;So;0;L;;;;;N;;;;; -1D0B2;BYZANTINE MUSICAL SYMBOL MARTYRIA PROTOVARYS ICHOS;So;0;L;;;;;N;;;;; -1D0B3;BYZANTINE MUSICAL SYMBOL MARTYRIA PLAGIOS TETARTOS ICHOS;So;0;L;;;;;N;;;;; -1D0B4;BYZANTINE MUSICAL SYMBOL GORTHMIKON N APLOUN;So;0;L;;;;;N;;;;; -1D0B5;BYZANTINE MUSICAL SYMBOL GORTHMIKON N DIPLOUN;So;0;L;;;;;N;;;;; -1D0B6;BYZANTINE MUSICAL SYMBOL ENARXIS KAI FTHORA VOU;So;0;L;;;;;N;;;;; -1D0B7;BYZANTINE MUSICAL SYMBOL IMIFONON;So;0;L;;;;;N;;;;; -1D0B8;BYZANTINE MUSICAL SYMBOL IMIFTHORON;So;0;L;;;;;N;;;;; -1D0B9;BYZANTINE MUSICAL SYMBOL FTHORA ARCHAION DEYTEROU ICHOU;So;0;L;;;;;N;;;;; -1D0BA;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI PA;So;0;L;;;;;N;;;;; -1D0BB;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI NANA;So;0;L;;;;;N;;;;; -1D0BC;BYZANTINE MUSICAL SYMBOL FTHORA NAOS ICHOS;So;0;L;;;;;N;;;;; -1D0BD;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI DI;So;0;L;;;;;N;;;;; -1D0BE;BYZANTINE MUSICAL SYMBOL FTHORA SKLIRON DIATONON DI;So;0;L;;;;;N;;;;; -1D0BF;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI KE;So;0;L;;;;;N;;;;; -1D0C0;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI ZO;So;0;L;;;;;N;;;;; -1D0C1;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI NI KATO;So;0;L;;;;;N;;;;; -1D0C2;BYZANTINE MUSICAL SYMBOL FTHORA DIATONIKI NI ANO;So;0;L;;;;;N;;;;; -1D0C3;BYZANTINE MUSICAL SYMBOL FTHORA MALAKON CHROMA DIFONIAS;So;0;L;;;;;N;;;;; -1D0C4;BYZANTINE MUSICAL SYMBOL FTHORA MALAKON CHROMA MONOFONIAS;So;0;L;;;;;N;;;;; -1D0C5;BYZANTINE MUSICAL SYMBOL FHTORA SKLIRON CHROMA VASIS;So;0;L;;;;;N;;;;; -1D0C6;BYZANTINE MUSICAL SYMBOL FTHORA SKLIRON CHROMA SYNAFI;So;0;L;;;;;N;;;;; -1D0C7;BYZANTINE MUSICAL SYMBOL FTHORA NENANO;So;0;L;;;;;N;;;;; -1D0C8;BYZANTINE MUSICAL SYMBOL CHROA ZYGOS;So;0;L;;;;;N;;;;; -1D0C9;BYZANTINE MUSICAL SYMBOL CHROA KLITON;So;0;L;;;;;N;;;;; -1D0CA;BYZANTINE MUSICAL SYMBOL CHROA SPATHI;So;0;L;;;;;N;;;;; -1D0CB;BYZANTINE MUSICAL SYMBOL FTHORA I YFESIS TETARTIMORION;So;0;L;;;;;N;;;;; -1D0CC;BYZANTINE MUSICAL SYMBOL FTHORA ENARMONIOS ANTIFONIA;So;0;L;;;;;N;;;;; -1D0CD;BYZANTINE MUSICAL SYMBOL YFESIS TRITIMORION;So;0;L;;;;;N;;;;; -1D0CE;BYZANTINE MUSICAL SYMBOL DIESIS TRITIMORION;So;0;L;;;;;N;;;;; -1D0CF;BYZANTINE MUSICAL SYMBOL DIESIS TETARTIMORION;So;0;L;;;;;N;;;;; -1D0D0;BYZANTINE MUSICAL SYMBOL DIESIS APLI DYO DODEKATA;So;0;L;;;;;N;;;;; -1D0D1;BYZANTINE MUSICAL SYMBOL DIESIS MONOGRAMMOS TESSERA DODEKATA;So;0;L;;;;;N;;;;; -1D0D2;BYZANTINE MUSICAL SYMBOL DIESIS DIGRAMMOS EX DODEKATA;So;0;L;;;;;N;;;;; -1D0D3;BYZANTINE MUSICAL SYMBOL DIESIS TRIGRAMMOS OKTO DODEKATA;So;0;L;;;;;N;;;;; -1D0D4;BYZANTINE MUSICAL SYMBOL YFESIS APLI DYO DODEKATA;So;0;L;;;;;N;;;;; -1D0D5;BYZANTINE MUSICAL SYMBOL YFESIS MONOGRAMMOS TESSERA DODEKATA;So;0;L;;;;;N;;;;; -1D0D6;BYZANTINE MUSICAL SYMBOL YFESIS DIGRAMMOS EX DODEKATA;So;0;L;;;;;N;;;;; -1D0D7;BYZANTINE MUSICAL SYMBOL YFESIS TRIGRAMMOS OKTO DODEKATA;So;0;L;;;;;N;;;;; -1D0D8;BYZANTINE MUSICAL SYMBOL GENIKI DIESIS;So;0;L;;;;;N;;;;; -1D0D9;BYZANTINE MUSICAL SYMBOL GENIKI YFESIS;So;0;L;;;;;N;;;;; -1D0DA;BYZANTINE MUSICAL SYMBOL DIASTOLI APLI MIKRI;So;0;L;;;;;N;;;;; -1D0DB;BYZANTINE MUSICAL SYMBOL DIASTOLI APLI MEGALI;So;0;L;;;;;N;;;;; -1D0DC;BYZANTINE MUSICAL SYMBOL DIASTOLI DIPLI;So;0;L;;;;;N;;;;; -1D0DD;BYZANTINE MUSICAL SYMBOL DIASTOLI THESEOS;So;0;L;;;;;N;;;;; -1D0DE;BYZANTINE MUSICAL SYMBOL SIMANSIS THESEOS;So;0;L;;;;;N;;;;; -1D0DF;BYZANTINE MUSICAL SYMBOL SIMANSIS THESEOS DISIMOU;So;0;L;;;;;N;;;;; -1D0E0;BYZANTINE MUSICAL SYMBOL SIMANSIS THESEOS TRISIMOU;So;0;L;;;;;N;;;;; -1D0E1;BYZANTINE MUSICAL SYMBOL SIMANSIS THESEOS TETRASIMOU;So;0;L;;;;;N;;;;; -1D0E2;BYZANTINE MUSICAL SYMBOL SIMANSIS ARSEOS;So;0;L;;;;;N;;;;; -1D0E3;BYZANTINE MUSICAL SYMBOL SIMANSIS ARSEOS DISIMOU;So;0;L;;;;;N;;;;; -1D0E4;BYZANTINE MUSICAL SYMBOL SIMANSIS ARSEOS TRISIMOU;So;0;L;;;;;N;;;;; -1D0E5;BYZANTINE MUSICAL SYMBOL SIMANSIS ARSEOS TETRASIMOU;So;0;L;;;;;N;;;;; -1D0E6;BYZANTINE MUSICAL SYMBOL DIGRAMMA GG;So;0;L;;;;;N;;;;; -1D0E7;BYZANTINE MUSICAL SYMBOL DIFTOGGOS OU;So;0;L;;;;;N;;;;; -1D0E8;BYZANTINE MUSICAL SYMBOL STIGMA;So;0;L;;;;;N;;;;; -1D0E9;BYZANTINE MUSICAL SYMBOL ARKTIKO PA;So;0;L;;;;;N;;;;; -1D0EA;BYZANTINE MUSICAL SYMBOL ARKTIKO VOU;So;0;L;;;;;N;;;;; -1D0EB;BYZANTINE MUSICAL SYMBOL ARKTIKO GA;So;0;L;;;;;N;;;;; -1D0EC;BYZANTINE MUSICAL SYMBOL ARKTIKO DI;So;0;L;;;;;N;;;;; -1D0ED;BYZANTINE MUSICAL SYMBOL ARKTIKO KE;So;0;L;;;;;N;;;;; -1D0EE;BYZANTINE MUSICAL SYMBOL ARKTIKO ZO;So;0;L;;;;;N;;;;; -1D0EF;BYZANTINE MUSICAL SYMBOL ARKTIKO NI;So;0;L;;;;;N;;;;; -1D0F0;BYZANTINE MUSICAL SYMBOL KENTIMATA NEO MESO;So;0;L;;;;;N;;;;; -1D0F1;BYZANTINE MUSICAL SYMBOL KENTIMA NEO MESO;So;0;L;;;;;N;;;;; -1D0F2;BYZANTINE MUSICAL SYMBOL KENTIMATA NEO KATO;So;0;L;;;;;N;;;;; -1D0F3;BYZANTINE MUSICAL SYMBOL KENTIMA NEO KATO;So;0;L;;;;;N;;;;; -1D0F4;BYZANTINE MUSICAL SYMBOL KLASMA KATO;So;0;L;;;;;N;;;;; -1D0F5;BYZANTINE MUSICAL SYMBOL GORGON NEO KATO;So;0;L;;;;;N;;;;; -1D100;MUSICAL SYMBOL SINGLE BARLINE;So;0;L;;;;;N;;;;; -1D101;MUSICAL SYMBOL DOUBLE BARLINE;So;0;L;;;;;N;;;;; -1D102;MUSICAL SYMBOL FINAL BARLINE;So;0;L;;;;;N;;;;; -1D103;MUSICAL SYMBOL REVERSE FINAL BARLINE;So;0;L;;;;;N;;;;; -1D104;MUSICAL SYMBOL DASHED BARLINE;So;0;L;;;;;N;;;;; -1D105;MUSICAL SYMBOL SHORT BARLINE;So;0;L;;;;;N;;;;; -1D106;MUSICAL SYMBOL LEFT REPEAT SIGN;So;0;L;;;;;N;;;;; -1D107;MUSICAL SYMBOL RIGHT REPEAT SIGN;So;0;L;;;;;N;;;;; -1D108;MUSICAL SYMBOL REPEAT DOTS;So;0;L;;;;;N;;;;; -1D109;MUSICAL SYMBOL DAL SEGNO;So;0;L;;;;;N;;;;; -1D10A;MUSICAL SYMBOL DA CAPO;So;0;L;;;;;N;;;;; -1D10B;MUSICAL SYMBOL SEGNO;So;0;L;;;;;N;;;;; -1D10C;MUSICAL SYMBOL CODA;So;0;L;;;;;N;;;;; -1D10D;MUSICAL SYMBOL REPEATED FIGURE-1;So;0;L;;;;;N;;;;; -1D10E;MUSICAL SYMBOL REPEATED FIGURE-2;So;0;L;;;;;N;;;;; -1D10F;MUSICAL SYMBOL REPEATED FIGURE-3;So;0;L;;;;;N;;;;; -1D110;MUSICAL SYMBOL FERMATA;So;0;L;;;;;N;;;;; -1D111;MUSICAL SYMBOL FERMATA BELOW;So;0;L;;;;;N;;;;; -1D112;MUSICAL SYMBOL BREATH MARK;So;0;L;;;;;N;;;;; -1D113;MUSICAL SYMBOL CAESURA;So;0;L;;;;;N;;;;; -1D114;MUSICAL SYMBOL BRACE;So;0;L;;;;;N;;;;; -1D115;MUSICAL SYMBOL BRACKET;So;0;L;;;;;N;;;;; -1D116;MUSICAL SYMBOL ONE-LINE STAFF;So;0;L;;;;;N;;;;; -1D117;MUSICAL SYMBOL TWO-LINE STAFF;So;0;L;;;;;N;;;;; -1D118;MUSICAL SYMBOL THREE-LINE STAFF;So;0;L;;;;;N;;;;; -1D119;MUSICAL SYMBOL FOUR-LINE STAFF;So;0;L;;;;;N;;;;; -1D11A;MUSICAL SYMBOL FIVE-LINE STAFF;So;0;L;;;;;N;;;;; -1D11B;MUSICAL SYMBOL SIX-LINE STAFF;So;0;L;;;;;N;;;;; -1D11C;MUSICAL SYMBOL SIX-STRING FRETBOARD;So;0;L;;;;;N;;;;; -1D11D;MUSICAL SYMBOL FOUR-STRING FRETBOARD;So;0;L;;;;;N;;;;; -1D11E;MUSICAL SYMBOL G CLEF;So;0;L;;;;;N;;;;; -1D11F;MUSICAL SYMBOL G CLEF OTTAVA ALTA;So;0;L;;;;;N;;;;; -1D120;MUSICAL SYMBOL G CLEF OTTAVA BASSA;So;0;L;;;;;N;;;;; -1D121;MUSICAL SYMBOL C CLEF;So;0;L;;;;;N;;;;; -1D122;MUSICAL SYMBOL F CLEF;So;0;L;;;;;N;;;;; -1D123;MUSICAL SYMBOL F CLEF OTTAVA ALTA;So;0;L;;;;;N;;;;; -1D124;MUSICAL SYMBOL F CLEF OTTAVA BASSA;So;0;L;;;;;N;;;;; -1D125;MUSICAL SYMBOL DRUM CLEF-1;So;0;L;;;;;N;;;;; -1D126;MUSICAL SYMBOL DRUM CLEF-2;So;0;L;;;;;N;;;;; -1D129;MUSICAL SYMBOL MULTIPLE MEASURE REST;So;0;L;;;;;N;;;;; -1D12A;MUSICAL SYMBOL DOUBLE SHARP;So;0;L;;;;;N;;;;; -1D12B;MUSICAL SYMBOL DOUBLE FLAT;So;0;L;;;;;N;;;;; -1D12C;MUSICAL SYMBOL FLAT UP;So;0;L;;;;;N;;;;; -1D12D;MUSICAL SYMBOL FLAT DOWN;So;0;L;;;;;N;;;;; -1D12E;MUSICAL SYMBOL NATURAL UP;So;0;L;;;;;N;;;;; -1D12F;MUSICAL SYMBOL NATURAL DOWN;So;0;L;;;;;N;;;;; -1D130;MUSICAL SYMBOL SHARP UP;So;0;L;;;;;N;;;;; -1D131;MUSICAL SYMBOL SHARP DOWN;So;0;L;;;;;N;;;;; -1D132;MUSICAL SYMBOL QUARTER TONE SHARP;So;0;L;;;;;N;;;;; -1D133;MUSICAL SYMBOL QUARTER TONE FLAT;So;0;L;;;;;N;;;;; -1D134;MUSICAL SYMBOL COMMON TIME;So;0;L;;;;;N;;;;; -1D135;MUSICAL SYMBOL CUT TIME;So;0;L;;;;;N;;;;; -1D136;MUSICAL SYMBOL OTTAVA ALTA;So;0;L;;;;;N;;;;; -1D137;MUSICAL SYMBOL OTTAVA BASSA;So;0;L;;;;;N;;;;; -1D138;MUSICAL SYMBOL QUINDICESIMA ALTA;So;0;L;;;;;N;;;;; -1D139;MUSICAL SYMBOL QUINDICESIMA BASSA;So;0;L;;;;;N;;;;; -1D13A;MUSICAL SYMBOL MULTI REST;So;0;L;;;;;N;;;;; -1D13B;MUSICAL SYMBOL WHOLE REST;So;0;L;;;;;N;;;;; -1D13C;MUSICAL SYMBOL HALF REST;So;0;L;;;;;N;;;;; -1D13D;MUSICAL SYMBOL QUARTER REST;So;0;L;;;;;N;;;;; -1D13E;MUSICAL SYMBOL EIGHTH REST;So;0;L;;;;;N;;;;; -1D13F;MUSICAL SYMBOL SIXTEENTH REST;So;0;L;;;;;N;;;;; -1D140;MUSICAL SYMBOL THIRTY-SECOND REST;So;0;L;;;;;N;;;;; -1D141;MUSICAL SYMBOL SIXTY-FOURTH REST;So;0;L;;;;;N;;;;; -1D142;MUSICAL SYMBOL ONE HUNDRED TWENTY-EIGHTH REST;So;0;L;;;;;N;;;;; -1D143;MUSICAL SYMBOL X NOTEHEAD;So;0;L;;;;;N;;;;; -1D144;MUSICAL SYMBOL PLUS NOTEHEAD;So;0;L;;;;;N;;;;; -1D145;MUSICAL SYMBOL CIRCLE X NOTEHEAD;So;0;L;;;;;N;;;;; -1D146;MUSICAL SYMBOL SQUARE NOTEHEAD WHITE;So;0;L;;;;;N;;;;; -1D147;MUSICAL SYMBOL SQUARE NOTEHEAD BLACK;So;0;L;;;;;N;;;;; -1D148;MUSICAL SYMBOL TRIANGLE NOTEHEAD UP WHITE;So;0;L;;;;;N;;;;; -1D149;MUSICAL SYMBOL TRIANGLE NOTEHEAD UP BLACK;So;0;L;;;;;N;;;;; -1D14A;MUSICAL SYMBOL TRIANGLE NOTEHEAD LEFT WHITE;So;0;L;;;;;N;;;;; -1D14B;MUSICAL SYMBOL TRIANGLE NOTEHEAD LEFT BLACK;So;0;L;;;;;N;;;;; -1D14C;MUSICAL SYMBOL TRIANGLE NOTEHEAD RIGHT WHITE;So;0;L;;;;;N;;;;; -1D14D;MUSICAL SYMBOL TRIANGLE NOTEHEAD RIGHT BLACK;So;0;L;;;;;N;;;;; -1D14E;MUSICAL SYMBOL TRIANGLE NOTEHEAD DOWN WHITE;So;0;L;;;;;N;;;;; -1D14F;MUSICAL SYMBOL TRIANGLE NOTEHEAD DOWN BLACK;So;0;L;;;;;N;;;;; -1D150;MUSICAL SYMBOL TRIANGLE NOTEHEAD UP RIGHT WHITE;So;0;L;;;;;N;;;;; -1D151;MUSICAL SYMBOL TRIANGLE NOTEHEAD UP RIGHT BLACK;So;0;L;;;;;N;;;;; -1D152;MUSICAL SYMBOL MOON NOTEHEAD WHITE;So;0;L;;;;;N;;;;; -1D153;MUSICAL SYMBOL MOON NOTEHEAD BLACK;So;0;L;;;;;N;;;;; -1D154;MUSICAL SYMBOL TRIANGLE-ROUND NOTEHEAD DOWN WHITE;So;0;L;;;;;N;;;;; -1D155;MUSICAL SYMBOL TRIANGLE-ROUND NOTEHEAD DOWN BLACK;So;0;L;;;;;N;;;;; -1D156;MUSICAL SYMBOL PARENTHESIS NOTEHEAD;So;0;L;;;;;N;;;;; -1D157;MUSICAL SYMBOL VOID NOTEHEAD;So;0;L;;;;;N;;;;; -1D158;MUSICAL SYMBOL NOTEHEAD BLACK;So;0;L;;;;;N;;;;; -1D159;MUSICAL SYMBOL NULL NOTEHEAD;So;0;L;;;;;N;;;;; -1D15A;MUSICAL SYMBOL CLUSTER NOTEHEAD WHITE;So;0;L;;;;;N;;;;; -1D15B;MUSICAL SYMBOL CLUSTER NOTEHEAD BLACK;So;0;L;;;;;N;;;;; -1D15C;MUSICAL SYMBOL BREVE;So;0;L;;;;;N;;;;; -1D15D;MUSICAL SYMBOL WHOLE NOTE;So;0;L;;;;;N;;;;; -1D15E;MUSICAL SYMBOL HALF NOTE;So;0;L;1D157 1D165;;;;N;;;;; -1D15F;MUSICAL SYMBOL QUARTER NOTE;So;0;L;1D158 1D165;;;;N;;;;; -1D160;MUSICAL SYMBOL EIGHTH NOTE;So;0;L;1D15F 1D16E;;;;N;;;;; -1D161;MUSICAL SYMBOL SIXTEENTH NOTE;So;0;L;1D15F 1D16F;;;;N;;;;; -1D162;MUSICAL SYMBOL THIRTY-SECOND NOTE;So;0;L;1D15F 1D170;;;;N;;;;; -1D163;MUSICAL SYMBOL SIXTY-FOURTH NOTE;So;0;L;1D15F 1D171;;;;N;;;;; -1D164;MUSICAL SYMBOL ONE HUNDRED TWENTY-EIGHTH NOTE;So;0;L;1D15F 1D172;;;;N;;;;; -1D165;MUSICAL SYMBOL COMBINING STEM;Mc;216;L;;;;;N;;;;; -1D166;MUSICAL SYMBOL COMBINING SPRECHGESANG STEM;Mc;216;L;;;;;N;;;;; -1D167;MUSICAL SYMBOL COMBINING TREMOLO-1;Mn;1;NSM;;;;;N;;;;; -1D168;MUSICAL SYMBOL COMBINING TREMOLO-2;Mn;1;NSM;;;;;N;;;;; -1D169;MUSICAL SYMBOL COMBINING TREMOLO-3;Mn;1;NSM;;;;;N;;;;; -1D16A;MUSICAL SYMBOL FINGERED TREMOLO-1;So;0;L;;;;;N;;;;; -1D16B;MUSICAL SYMBOL FINGERED TREMOLO-2;So;0;L;;;;;N;;;;; -1D16C;MUSICAL SYMBOL FINGERED TREMOLO-3;So;0;L;;;;;N;;;;; -1D16D;MUSICAL SYMBOL COMBINING AUGMENTATION DOT;Mc;226;L;;;;;N;;;;; -1D16E;MUSICAL SYMBOL COMBINING FLAG-1;Mc;216;L;;;;;N;;;;; -1D16F;MUSICAL SYMBOL COMBINING FLAG-2;Mc;216;L;;;;;N;;;;; -1D170;MUSICAL SYMBOL COMBINING FLAG-3;Mc;216;L;;;;;N;;;;; -1D171;MUSICAL SYMBOL COMBINING FLAG-4;Mc;216;L;;;;;N;;;;; -1D172;MUSICAL SYMBOL COMBINING FLAG-5;Mc;216;L;;;;;N;;;;; -1D173;MUSICAL SYMBOL BEGIN BEAM;Cf;0;BN;;;;;N;;;;; -1D174;MUSICAL SYMBOL END BEAM;Cf;0;BN;;;;;N;;;;; -1D175;MUSICAL SYMBOL BEGIN TIE;Cf;0;BN;;;;;N;;;;; -1D176;MUSICAL SYMBOL END TIE;Cf;0;BN;;;;;N;;;;; -1D177;MUSICAL SYMBOL BEGIN SLUR;Cf;0;BN;;;;;N;;;;; -1D178;MUSICAL SYMBOL END SLUR;Cf;0;BN;;;;;N;;;;; -1D179;MUSICAL SYMBOL BEGIN PHRASE;Cf;0;BN;;;;;N;;;;; -1D17A;MUSICAL SYMBOL END PHRASE;Cf;0;BN;;;;;N;;;;; -1D17B;MUSICAL SYMBOL COMBINING ACCENT;Mn;220;NSM;;;;;N;;;;; -1D17C;MUSICAL SYMBOL COMBINING STACCATO;Mn;220;NSM;;;;;N;;;;; -1D17D;MUSICAL SYMBOL COMBINING TENUTO;Mn;220;NSM;;;;;N;;;;; -1D17E;MUSICAL SYMBOL COMBINING STACCATISSIMO;Mn;220;NSM;;;;;N;;;;; -1D17F;MUSICAL SYMBOL COMBINING MARCATO;Mn;220;NSM;;;;;N;;;;; -1D180;MUSICAL SYMBOL COMBINING MARCATO-STACCATO;Mn;220;NSM;;;;;N;;;;; -1D181;MUSICAL SYMBOL COMBINING ACCENT-STACCATO;Mn;220;NSM;;;;;N;;;;; -1D182;MUSICAL SYMBOL COMBINING LOURE;Mn;220;NSM;;;;;N;;;;; -1D183;MUSICAL SYMBOL ARPEGGIATO UP;So;0;L;;;;;N;;;;; -1D184;MUSICAL SYMBOL ARPEGGIATO DOWN;So;0;L;;;;;N;;;;; -1D185;MUSICAL SYMBOL COMBINING DOIT;Mn;230;NSM;;;;;N;;;;; -1D186;MUSICAL SYMBOL COMBINING RIP;Mn;230;NSM;;;;;N;;;;; -1D187;MUSICAL SYMBOL COMBINING FLIP;Mn;230;NSM;;;;;N;;;;; -1D188;MUSICAL SYMBOL COMBINING SMEAR;Mn;230;NSM;;;;;N;;;;; -1D189;MUSICAL SYMBOL COMBINING BEND;Mn;230;NSM;;;;;N;;;;; -1D18A;MUSICAL SYMBOL COMBINING DOUBLE TONGUE;Mn;220;NSM;;;;;N;;;;; -1D18B;MUSICAL SYMBOL COMBINING TRIPLE TONGUE;Mn;220;NSM;;;;;N;;;;; -1D18C;MUSICAL SYMBOL RINFORZANDO;So;0;L;;;;;N;;;;; -1D18D;MUSICAL SYMBOL SUBITO;So;0;L;;;;;N;;;;; -1D18E;MUSICAL SYMBOL Z;So;0;L;;;;;N;;;;; -1D18F;MUSICAL SYMBOL PIANO;So;0;L;;;;;N;;;;; -1D190;MUSICAL SYMBOL MEZZO;So;0;L;;;;;N;;;;; -1D191;MUSICAL SYMBOL FORTE;So;0;L;;;;;N;;;;; -1D192;MUSICAL SYMBOL CRESCENDO;So;0;L;;;;;N;;;;; -1D193;MUSICAL SYMBOL DECRESCENDO;So;0;L;;;;;N;;;;; -1D194;MUSICAL SYMBOL GRACE NOTE SLASH;So;0;L;;;;;N;;;;; -1D195;MUSICAL SYMBOL GRACE NOTE NO SLASH;So;0;L;;;;;N;;;;; -1D196;MUSICAL SYMBOL TR;So;0;L;;;;;N;;;;; -1D197;MUSICAL SYMBOL TURN;So;0;L;;;;;N;;;;; -1D198;MUSICAL SYMBOL INVERTED TURN;So;0;L;;;;;N;;;;; -1D199;MUSICAL SYMBOL TURN SLASH;So;0;L;;;;;N;;;;; -1D19A;MUSICAL SYMBOL TURN UP;So;0;L;;;;;N;;;;; -1D19B;MUSICAL SYMBOL ORNAMENT STROKE-1;So;0;L;;;;;N;;;;; -1D19C;MUSICAL SYMBOL ORNAMENT STROKE-2;So;0;L;;;;;N;;;;; -1D19D;MUSICAL SYMBOL ORNAMENT STROKE-3;So;0;L;;;;;N;;;;; -1D19E;MUSICAL SYMBOL ORNAMENT STROKE-4;So;0;L;;;;;N;;;;; -1D19F;MUSICAL SYMBOL ORNAMENT STROKE-5;So;0;L;;;;;N;;;;; -1D1A0;MUSICAL SYMBOL ORNAMENT STROKE-6;So;0;L;;;;;N;;;;; -1D1A1;MUSICAL SYMBOL ORNAMENT STROKE-7;So;0;L;;;;;N;;;;; -1D1A2;MUSICAL SYMBOL ORNAMENT STROKE-8;So;0;L;;;;;N;;;;; -1D1A3;MUSICAL SYMBOL ORNAMENT STROKE-9;So;0;L;;;;;N;;;;; -1D1A4;MUSICAL SYMBOL ORNAMENT STROKE-10;So;0;L;;;;;N;;;;; -1D1A5;MUSICAL SYMBOL ORNAMENT STROKE-11;So;0;L;;;;;N;;;;; -1D1A6;MUSICAL SYMBOL HAUPTSTIMME;So;0;L;;;;;N;;;;; -1D1A7;MUSICAL SYMBOL NEBENSTIMME;So;0;L;;;;;N;;;;; -1D1A8;MUSICAL SYMBOL END OF STIMME;So;0;L;;;;;N;;;;; -1D1A9;MUSICAL SYMBOL DEGREE SLASH;So;0;L;;;;;N;;;;; -1D1AA;MUSICAL SYMBOL COMBINING DOWN BOW;Mn;230;NSM;;;;;N;;;;; -1D1AB;MUSICAL SYMBOL COMBINING UP BOW;Mn;230;NSM;;;;;N;;;;; -1D1AC;MUSICAL SYMBOL COMBINING HARMONIC;Mn;230;NSM;;;;;N;;;;; -1D1AD;MUSICAL SYMBOL COMBINING SNAP PIZZICATO;Mn;230;NSM;;;;;N;;;;; -1D1AE;MUSICAL SYMBOL PEDAL MARK;So;0;L;;;;;N;;;;; -1D1AF;MUSICAL SYMBOL PEDAL UP MARK;So;0;L;;;;;N;;;;; -1D1B0;MUSICAL SYMBOL HALF PEDAL MARK;So;0;L;;;;;N;;;;; -1D1B1;MUSICAL SYMBOL GLISSANDO UP;So;0;L;;;;;N;;;;; -1D1B2;MUSICAL SYMBOL GLISSANDO DOWN;So;0;L;;;;;N;;;;; -1D1B3;MUSICAL SYMBOL WITH FINGERNAILS;So;0;L;;;;;N;;;;; -1D1B4;MUSICAL SYMBOL DAMP;So;0;L;;;;;N;;;;; -1D1B5;MUSICAL SYMBOL DAMP ALL;So;0;L;;;;;N;;;;; -1D1B6;MUSICAL SYMBOL MAXIMA;So;0;L;;;;;N;;;;; -1D1B7;MUSICAL SYMBOL LONGA;So;0;L;;;;;N;;;;; -1D1B8;MUSICAL SYMBOL BREVIS;So;0;L;;;;;N;;;;; -1D1B9;MUSICAL SYMBOL SEMIBREVIS WHITE;So;0;L;;;;;N;;;;; -1D1BA;MUSICAL SYMBOL SEMIBREVIS BLACK;So;0;L;;;;;N;;;;; -1D1BB;MUSICAL SYMBOL MINIMA;So;0;L;1D1B9 1D165;;;;N;;;;; -1D1BC;MUSICAL SYMBOL MINIMA BLACK;So;0;L;1D1BA 1D165;;;;N;;;;; -1D1BD;MUSICAL SYMBOL SEMIMINIMA WHITE;So;0;L;1D1BB 1D16E;;;;N;;;;; -1D1BE;MUSICAL SYMBOL SEMIMINIMA BLACK;So;0;L;1D1BC 1D16E;;;;N;;;;; -1D1BF;MUSICAL SYMBOL FUSA WHITE;So;0;L;1D1BB 1D16F;;;;N;;;;; -1D1C0;MUSICAL SYMBOL FUSA BLACK;So;0;L;1D1BC 1D16F;;;;N;;;;; -1D1C1;MUSICAL SYMBOL LONGA PERFECTA REST;So;0;L;;;;;N;;;;; -1D1C2;MUSICAL SYMBOL LONGA IMPERFECTA REST;So;0;L;;;;;N;;;;; -1D1C3;MUSICAL SYMBOL BREVIS REST;So;0;L;;;;;N;;;;; -1D1C4;MUSICAL SYMBOL SEMIBREVIS REST;So;0;L;;;;;N;;;;; -1D1C5;MUSICAL SYMBOL MINIMA REST;So;0;L;;;;;N;;;;; -1D1C6;MUSICAL SYMBOL SEMIMINIMA REST;So;0;L;;;;;N;;;;; -1D1C7;MUSICAL SYMBOL TEMPUS PERFECTUM CUM PROLATIONE PERFECTA;So;0;L;;;;;N;;;;; -1D1C8;MUSICAL SYMBOL TEMPUS PERFECTUM CUM PROLATIONE IMPERFECTA;So;0;L;;;;;N;;;;; -1D1C9;MUSICAL SYMBOL TEMPUS PERFECTUM CUM PROLATIONE PERFECTA DIMINUTION-1;So;0;L;;;;;N;;;;; -1D1CA;MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE PERFECTA;So;0;L;;;;;N;;;;; -1D1CB;MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE IMPERFECTA;So;0;L;;;;;N;;;;; -1D1CC;MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE IMPERFECTA DIMINUTION-1;So;0;L;;;;;N;;;;; -1D1CD;MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE IMPERFECTA DIMINUTION-2;So;0;L;;;;;N;;;;; -1D1CE;MUSICAL SYMBOL TEMPUS IMPERFECTUM CUM PROLATIONE IMPERFECTA DIMINUTION-3;So;0;L;;;;;N;;;;; -1D1CF;MUSICAL SYMBOL CROIX;So;0;L;;;;;N;;;;; -1D1D0;MUSICAL SYMBOL GREGORIAN C CLEF;So;0;L;;;;;N;;;;; -1D1D1;MUSICAL SYMBOL GREGORIAN F CLEF;So;0;L;;;;;N;;;;; -1D1D2;MUSICAL SYMBOL SQUARE B;So;0;L;;;;;N;;;;; -1D1D3;MUSICAL SYMBOL VIRGA;So;0;L;;;;;N;;;;; -1D1D4;MUSICAL SYMBOL PODATUS;So;0;L;;;;;N;;;;; -1D1D5;MUSICAL SYMBOL CLIVIS;So;0;L;;;;;N;;;;; -1D1D6;MUSICAL SYMBOL SCANDICUS;So;0;L;;;;;N;;;;; -1D1D7;MUSICAL SYMBOL CLIMACUS;So;0;L;;;;;N;;;;; -1D1D8;MUSICAL SYMBOL TORCULUS;So;0;L;;;;;N;;;;; -1D1D9;MUSICAL SYMBOL PORRECTUS;So;0;L;;;;;N;;;;; -1D1DA;MUSICAL SYMBOL PORRECTUS FLEXUS;So;0;L;;;;;N;;;;; -1D1DB;MUSICAL SYMBOL SCANDICUS FLEXUS;So;0;L;;;;;N;;;;; -1D1DC;MUSICAL SYMBOL TORCULUS RESUPINUS;So;0;L;;;;;N;;;;; -1D1DD;MUSICAL SYMBOL PES SUBPUNCTIS;So;0;L;;;;;N;;;;; -1D200;GREEK VOCAL NOTATION SYMBOL-1;So;0;ON;;;;;N;;;;; -1D201;GREEK VOCAL NOTATION SYMBOL-2;So;0;ON;;;;;N;;;;; -1D202;GREEK VOCAL NOTATION SYMBOL-3;So;0;ON;;;;;N;;;;; -1D203;GREEK VOCAL NOTATION SYMBOL-4;So;0;ON;;;;;N;;;;; -1D204;GREEK VOCAL NOTATION SYMBOL-5;So;0;ON;;;;;N;;;;; -1D205;GREEK VOCAL NOTATION SYMBOL-6;So;0;ON;;;;;N;;;;; -1D206;GREEK VOCAL NOTATION SYMBOL-7;So;0;ON;;;;;N;;;;; -1D207;GREEK VOCAL NOTATION SYMBOL-8;So;0;ON;;;;;N;;;;; -1D208;GREEK VOCAL NOTATION SYMBOL-9;So;0;ON;;;;;N;;;;; -1D209;GREEK VOCAL NOTATION SYMBOL-10;So;0;ON;;;;;N;;;;; -1D20A;GREEK VOCAL NOTATION SYMBOL-11;So;0;ON;;;;;N;;;;; -1D20B;GREEK VOCAL NOTATION SYMBOL-12;So;0;ON;;;;;N;;;;; -1D20C;GREEK VOCAL NOTATION SYMBOL-13;So;0;ON;;;;;N;;;;; -1D20D;GREEK VOCAL NOTATION SYMBOL-14;So;0;ON;;;;;N;;;;; -1D20E;GREEK VOCAL NOTATION SYMBOL-15;So;0;ON;;;;;N;;;;; -1D20F;GREEK VOCAL NOTATION SYMBOL-16;So;0;ON;;;;;N;;;;; -1D210;GREEK VOCAL NOTATION SYMBOL-17;So;0;ON;;;;;N;;;;; -1D211;GREEK VOCAL NOTATION SYMBOL-18;So;0;ON;;;;;N;;;;; -1D212;GREEK VOCAL NOTATION SYMBOL-19;So;0;ON;;;;;N;;;;; -1D213;GREEK VOCAL NOTATION SYMBOL-20;So;0;ON;;;;;N;;;;; -1D214;GREEK VOCAL NOTATION SYMBOL-21;So;0;ON;;;;;N;;;;; -1D215;GREEK VOCAL NOTATION SYMBOL-22;So;0;ON;;;;;N;;;;; -1D216;GREEK VOCAL NOTATION SYMBOL-23;So;0;ON;;;;;N;;;;; -1D217;GREEK VOCAL NOTATION SYMBOL-24;So;0;ON;;;;;N;;;;; -1D218;GREEK VOCAL NOTATION SYMBOL-50;So;0;ON;;;;;N;;;;; -1D219;GREEK VOCAL NOTATION SYMBOL-51;So;0;ON;;;;;N;;;;; -1D21A;GREEK VOCAL NOTATION SYMBOL-52;So;0;ON;;;;;N;;;;; -1D21B;GREEK VOCAL NOTATION SYMBOL-53;So;0;ON;;;;;N;;;;; -1D21C;GREEK VOCAL NOTATION SYMBOL-54;So;0;ON;;;;;N;;;;; -1D21D;GREEK INSTRUMENTAL NOTATION SYMBOL-1;So;0;ON;;;;;N;;;;; -1D21E;GREEK INSTRUMENTAL NOTATION SYMBOL-2;So;0;ON;;;;;N;;;;; -1D21F;GREEK INSTRUMENTAL NOTATION SYMBOL-4;So;0;ON;;;;;N;;;;; -1D220;GREEK INSTRUMENTAL NOTATION SYMBOL-5;So;0;ON;;;;;N;;;;; -1D221;GREEK INSTRUMENTAL NOTATION SYMBOL-7;So;0;ON;;;;;N;;;;; -1D222;GREEK INSTRUMENTAL NOTATION SYMBOL-8;So;0;ON;;;;;N;;;;; -1D223;GREEK INSTRUMENTAL NOTATION SYMBOL-11;So;0;ON;;;;;N;;;;; -1D224;GREEK INSTRUMENTAL NOTATION SYMBOL-12;So;0;ON;;;;;N;;;;; -1D225;GREEK INSTRUMENTAL NOTATION SYMBOL-13;So;0;ON;;;;;N;;;;; -1D226;GREEK INSTRUMENTAL NOTATION SYMBOL-14;So;0;ON;;;;;N;;;;; -1D227;GREEK INSTRUMENTAL NOTATION SYMBOL-17;So;0;ON;;;;;N;;;;; -1D228;GREEK INSTRUMENTAL NOTATION SYMBOL-18;So;0;ON;;;;;N;;;;; -1D229;GREEK INSTRUMENTAL NOTATION SYMBOL-19;So;0;ON;;;;;N;;;;; -1D22A;GREEK INSTRUMENTAL NOTATION SYMBOL-23;So;0;ON;;;;;N;;;;; -1D22B;GREEK INSTRUMENTAL NOTATION SYMBOL-24;So;0;ON;;;;;N;;;;; -1D22C;GREEK INSTRUMENTAL NOTATION SYMBOL-25;So;0;ON;;;;;N;;;;; -1D22D;GREEK INSTRUMENTAL NOTATION SYMBOL-26;So;0;ON;;;;;N;;;;; -1D22E;GREEK INSTRUMENTAL NOTATION SYMBOL-27;So;0;ON;;;;;N;;;;; -1D22F;GREEK INSTRUMENTAL NOTATION SYMBOL-29;So;0;ON;;;;;N;;;;; -1D230;GREEK INSTRUMENTAL NOTATION SYMBOL-30;So;0;ON;;;;;N;;;;; -1D231;GREEK INSTRUMENTAL NOTATION SYMBOL-32;So;0;ON;;;;;N;;;;; -1D232;GREEK INSTRUMENTAL NOTATION SYMBOL-36;So;0;ON;;;;;N;;;;; -1D233;GREEK INSTRUMENTAL NOTATION SYMBOL-37;So;0;ON;;;;;N;;;;; -1D234;GREEK INSTRUMENTAL NOTATION SYMBOL-38;So;0;ON;;;;;N;;;;; -1D235;GREEK INSTRUMENTAL NOTATION SYMBOL-39;So;0;ON;;;;;N;;;;; -1D236;GREEK INSTRUMENTAL NOTATION SYMBOL-40;So;0;ON;;;;;N;;;;; -1D237;GREEK INSTRUMENTAL NOTATION SYMBOL-42;So;0;ON;;;;;N;;;;; -1D238;GREEK INSTRUMENTAL NOTATION SYMBOL-43;So;0;ON;;;;;N;;;;; -1D239;GREEK INSTRUMENTAL NOTATION SYMBOL-45;So;0;ON;;;;;N;;;;; -1D23A;GREEK INSTRUMENTAL NOTATION SYMBOL-47;So;0;ON;;;;;N;;;;; -1D23B;GREEK INSTRUMENTAL NOTATION SYMBOL-48;So;0;ON;;;;;N;;;;; -1D23C;GREEK INSTRUMENTAL NOTATION SYMBOL-49;So;0;ON;;;;;N;;;;; -1D23D;GREEK INSTRUMENTAL NOTATION SYMBOL-50;So;0;ON;;;;;N;;;;; -1D23E;GREEK INSTRUMENTAL NOTATION SYMBOL-51;So;0;ON;;;;;N;;;;; -1D23F;GREEK INSTRUMENTAL NOTATION SYMBOL-52;So;0;ON;;;;;N;;;;; -1D240;GREEK INSTRUMENTAL NOTATION SYMBOL-53;So;0;ON;;;;;N;;;;; -1D241;GREEK INSTRUMENTAL NOTATION SYMBOL-54;So;0;ON;;;;;N;;;;; -1D242;COMBINING GREEK MUSICAL TRISEME;Mn;230;NSM;;;;;N;;;;; -1D243;COMBINING GREEK MUSICAL TETRASEME;Mn;230;NSM;;;;;N;;;;; -1D244;COMBINING GREEK MUSICAL PENTASEME;Mn;230;NSM;;;;;N;;;;; -1D245;GREEK MUSICAL LEIMMA;So;0;ON;;;;;N;;;;; -1D300;MONOGRAM FOR EARTH;So;0;ON;;;;;N;;ren *;;; -1D301;DIGRAM FOR HEAVENLY EARTH;So;0;ON;;;;;N;;tian ren *;;; -1D302;DIGRAM FOR HUMAN EARTH;So;0;ON;;;;;N;;di ren *;;; -1D303;DIGRAM FOR EARTHLY HEAVEN;So;0;ON;;;;;N;;ren tian *;;; -1D304;DIGRAM FOR EARTHLY HUMAN;So;0;ON;;;;;N;;ren di *;;; -1D305;DIGRAM FOR EARTH;So;0;ON;;;;;N;;ren ren *;;; -1D306;TETRAGRAM FOR CENTRE;So;0;ON;;;;;N;;;;; -1D307;TETRAGRAM FOR FULL CIRCLE;So;0;ON;;;;;N;;;;; -1D308;TETRAGRAM FOR MIRED;So;0;ON;;;;;N;;;;; -1D309;TETRAGRAM FOR BARRIER;So;0;ON;;;;;N;;;;; -1D30A;TETRAGRAM FOR KEEPING SMALL;So;0;ON;;;;;N;;;;; -1D30B;TETRAGRAM FOR CONTRARIETY;So;0;ON;;;;;N;;;;; -1D30C;TETRAGRAM FOR ASCENT;So;0;ON;;;;;N;;;;; -1D30D;TETRAGRAM FOR OPPOSITION;So;0;ON;;;;;N;;;;; -1D30E;TETRAGRAM FOR BRANCHING OUT;So;0;ON;;;;;N;;;;; -1D30F;TETRAGRAM FOR DEFECTIVENESS OR DISTORTION;So;0;ON;;;;;N;;;;; -1D310;TETRAGRAM FOR DIVERGENCE;So;0;ON;;;;;N;;;;; -1D311;TETRAGRAM FOR YOUTHFULNESS;So;0;ON;;;;;N;;;;; -1D312;TETRAGRAM FOR INCREASE;So;0;ON;;;;;N;;;;; -1D313;TETRAGRAM FOR PENETRATION;So;0;ON;;;;;N;;;;; -1D314;TETRAGRAM FOR REACH;So;0;ON;;;;;N;;;;; -1D315;TETRAGRAM FOR CONTACT;So;0;ON;;;;;N;;;;; -1D316;TETRAGRAM FOR HOLDING BACK;So;0;ON;;;;;N;;;;; -1D317;TETRAGRAM FOR WAITING;So;0;ON;;;;;N;;;;; -1D318;TETRAGRAM FOR FOLLOWING;So;0;ON;;;;;N;;;;; -1D319;TETRAGRAM FOR ADVANCE;So;0;ON;;;;;N;;;;; -1D31A;TETRAGRAM FOR RELEASE;So;0;ON;;;;;N;;;;; -1D31B;TETRAGRAM FOR RESISTANCE;So;0;ON;;;;;N;;;;; -1D31C;TETRAGRAM FOR EASE;So;0;ON;;;;;N;;;;; -1D31D;TETRAGRAM FOR JOY;So;0;ON;;;;;N;;;;; -1D31E;TETRAGRAM FOR CONTENTION;So;0;ON;;;;;N;;;;; -1D31F;TETRAGRAM FOR ENDEAVOUR;So;0;ON;;;;;N;;;;; -1D320;TETRAGRAM FOR DUTIES;So;0;ON;;;;;N;;;;; -1D321;TETRAGRAM FOR CHANGE;So;0;ON;;;;;N;;;;; -1D322;TETRAGRAM FOR DECISIVENESS;So;0;ON;;;;;N;;;;; -1D323;TETRAGRAM FOR BOLD RESOLUTION;So;0;ON;;;;;N;;;;; -1D324;TETRAGRAM FOR PACKING;So;0;ON;;;;;N;;;;; -1D325;TETRAGRAM FOR LEGION;So;0;ON;;;;;N;;;;; -1D326;TETRAGRAM FOR CLOSENESS;So;0;ON;;;;;N;;;;; -1D327;TETRAGRAM FOR KINSHIP;So;0;ON;;;;;N;;;;; -1D328;TETRAGRAM FOR GATHERING;So;0;ON;;;;;N;;;;; -1D329;TETRAGRAM FOR STRENGTH;So;0;ON;;;;;N;;;;; -1D32A;TETRAGRAM FOR PURITY;So;0;ON;;;;;N;;;;; -1D32B;TETRAGRAM FOR FULLNESS;So;0;ON;;;;;N;;;;; -1D32C;TETRAGRAM FOR RESIDENCE;So;0;ON;;;;;N;;;;; -1D32D;TETRAGRAM FOR LAW OR MODEL;So;0;ON;;;;;N;;;;; -1D32E;TETRAGRAM FOR RESPONSE;So;0;ON;;;;;N;;;;; -1D32F;TETRAGRAM FOR GOING TO MEET;So;0;ON;;;;;N;;;;; -1D330;TETRAGRAM FOR ENCOUNTERS;So;0;ON;;;;;N;;;;; -1D331;TETRAGRAM FOR STOVE;So;0;ON;;;;;N;;;;; -1D332;TETRAGRAM FOR GREATNESS;So;0;ON;;;;;N;;;;; -1D333;TETRAGRAM FOR ENLARGEMENT;So;0;ON;;;;;N;;;;; -1D334;TETRAGRAM FOR PATTERN;So;0;ON;;;;;N;;;;; -1D335;TETRAGRAM FOR RITUAL;So;0;ON;;;;;N;;;;; -1D336;TETRAGRAM FOR FLIGHT;So;0;ON;;;;;N;;;;; -1D337;TETRAGRAM FOR VASTNESS OR WASTING;So;0;ON;;;;;N;;;;; -1D338;TETRAGRAM FOR CONSTANCY;So;0;ON;;;;;N;;;;; -1D339;TETRAGRAM FOR MEASURE;So;0;ON;;;;;N;;;;; -1D33A;TETRAGRAM FOR ETERNITY;So;0;ON;;;;;N;;;;; -1D33B;TETRAGRAM FOR UNITY;So;0;ON;;;;;N;;;;; -1D33C;TETRAGRAM FOR DIMINISHMENT;So;0;ON;;;;;N;;;;; -1D33D;TETRAGRAM FOR CLOSED MOUTH;So;0;ON;;;;;N;;;;; -1D33E;TETRAGRAM FOR GUARDEDNESS;So;0;ON;;;;;N;;;;; -1D33F;TETRAGRAM FOR GATHERING IN;So;0;ON;;;;;N;;;;; -1D340;TETRAGRAM FOR MASSING;So;0;ON;;;;;N;;;;; -1D341;TETRAGRAM FOR ACCUMULATION;So;0;ON;;;;;N;;;;; -1D342;TETRAGRAM FOR EMBELLISHMENT;So;0;ON;;;;;N;;;;; -1D343;TETRAGRAM FOR DOUBT;So;0;ON;;;;;N;;;;; -1D344;TETRAGRAM FOR WATCH;So;0;ON;;;;;N;;;;; -1D345;TETRAGRAM FOR SINKING;So;0;ON;;;;;N;;;;; -1D346;TETRAGRAM FOR INNER;So;0;ON;;;;;N;;;;; -1D347;TETRAGRAM FOR DEPARTURE;So;0;ON;;;;;N;;;;; -1D348;TETRAGRAM FOR DARKENING;So;0;ON;;;;;N;;;;; -1D349;TETRAGRAM FOR DIMMING;So;0;ON;;;;;N;;;;; -1D34A;TETRAGRAM FOR EXHAUSTION;So;0;ON;;;;;N;;;;; -1D34B;TETRAGRAM FOR SEVERANCE;So;0;ON;;;;;N;;;;; -1D34C;TETRAGRAM FOR STOPPAGE;So;0;ON;;;;;N;;;;; -1D34D;TETRAGRAM FOR HARDNESS;So;0;ON;;;;;N;;;;; -1D34E;TETRAGRAM FOR COMPLETION;So;0;ON;;;;;N;;;;; -1D34F;TETRAGRAM FOR CLOSURE;So;0;ON;;;;;N;;;;; -1D350;TETRAGRAM FOR FAILURE;So;0;ON;;;;;N;;;;; -1D351;TETRAGRAM FOR AGGRAVATION;So;0;ON;;;;;N;;;;; -1D352;TETRAGRAM FOR COMPLIANCE;So;0;ON;;;;;N;;;;; -1D353;TETRAGRAM FOR ON THE VERGE;So;0;ON;;;;;N;;;;; -1D354;TETRAGRAM FOR DIFFICULTIES;So;0;ON;;;;;N;;;;; -1D355;TETRAGRAM FOR LABOURING;So;0;ON;;;;;N;;;;; -1D356;TETRAGRAM FOR FOSTERING;So;0;ON;;;;;N;;;;; -1D360;COUNTING ROD UNIT DIGIT ONE;No;0;L;;;;1;N;;;;; -1D361;COUNTING ROD UNIT DIGIT TWO;No;0;L;;;;2;N;;;;; -1D362;COUNTING ROD UNIT DIGIT THREE;No;0;L;;;;3;N;;;;; -1D363;COUNTING ROD UNIT DIGIT FOUR;No;0;L;;;;4;N;;;;; -1D364;COUNTING ROD UNIT DIGIT FIVE;No;0;L;;;;5;N;;;;; -1D365;COUNTING ROD UNIT DIGIT SIX;No;0;L;;;;6;N;;;;; -1D366;COUNTING ROD UNIT DIGIT SEVEN;No;0;L;;;;7;N;;;;; -1D367;COUNTING ROD UNIT DIGIT EIGHT;No;0;L;;;;8;N;;;;; -1D368;COUNTING ROD UNIT DIGIT NINE;No;0;L;;;;9;N;;;;; -1D369;COUNTING ROD TENS DIGIT ONE;No;0;L;;;;10;N;;;;; -1D36A;COUNTING ROD TENS DIGIT TWO;No;0;L;;;;20;N;;;;; -1D36B;COUNTING ROD TENS DIGIT THREE;No;0;L;;;;30;N;;;;; -1D36C;COUNTING ROD TENS DIGIT FOUR;No;0;L;;;;40;N;;;;; -1D36D;COUNTING ROD TENS DIGIT FIVE;No;0;L;;;;50;N;;;;; -1D36E;COUNTING ROD TENS DIGIT SIX;No;0;L;;;;60;N;;;;; -1D36F;COUNTING ROD TENS DIGIT SEVEN;No;0;L;;;;70;N;;;;; -1D370;COUNTING ROD TENS DIGIT EIGHT;No;0;L;;;;80;N;;;;; -1D371;COUNTING ROD TENS DIGIT NINE;No;0;L;;;;90;N;;;;; -1D400;MATHEMATICAL BOLD CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D401;MATHEMATICAL BOLD CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D402;MATHEMATICAL BOLD CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D403;MATHEMATICAL BOLD CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D404;MATHEMATICAL BOLD CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D405;MATHEMATICAL BOLD CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D406;MATHEMATICAL BOLD CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D407;MATHEMATICAL BOLD CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D408;MATHEMATICAL BOLD CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D409;MATHEMATICAL BOLD CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D40A;MATHEMATICAL BOLD CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D40B;MATHEMATICAL BOLD CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D40C;MATHEMATICAL BOLD CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D40D;MATHEMATICAL BOLD CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D40E;MATHEMATICAL BOLD CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D40F;MATHEMATICAL BOLD CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D410;MATHEMATICAL BOLD CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D411;MATHEMATICAL BOLD CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D412;MATHEMATICAL BOLD CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D413;MATHEMATICAL BOLD CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D414;MATHEMATICAL BOLD CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D415;MATHEMATICAL BOLD CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D416;MATHEMATICAL BOLD CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D417;MATHEMATICAL BOLD CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D418;MATHEMATICAL BOLD CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D419;MATHEMATICAL BOLD CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D41A;MATHEMATICAL BOLD SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D41B;MATHEMATICAL BOLD SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D41C;MATHEMATICAL BOLD SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D41D;MATHEMATICAL BOLD SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D41E;MATHEMATICAL BOLD SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D41F;MATHEMATICAL BOLD SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D420;MATHEMATICAL BOLD SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D421;MATHEMATICAL BOLD SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D422;MATHEMATICAL BOLD SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D423;MATHEMATICAL BOLD SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D424;MATHEMATICAL BOLD SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D425;MATHEMATICAL BOLD SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D426;MATHEMATICAL BOLD SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D427;MATHEMATICAL BOLD SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D428;MATHEMATICAL BOLD SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D429;MATHEMATICAL BOLD SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D42A;MATHEMATICAL BOLD SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D42B;MATHEMATICAL BOLD SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D42C;MATHEMATICAL BOLD SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D42D;MATHEMATICAL BOLD SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D42E;MATHEMATICAL BOLD SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D42F;MATHEMATICAL BOLD SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D430;MATHEMATICAL BOLD SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D431;MATHEMATICAL BOLD SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D432;MATHEMATICAL BOLD SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D433;MATHEMATICAL BOLD SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D434;MATHEMATICAL ITALIC CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D435;MATHEMATICAL ITALIC CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D436;MATHEMATICAL ITALIC CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D437;MATHEMATICAL ITALIC CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D438;MATHEMATICAL ITALIC CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D439;MATHEMATICAL ITALIC CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D43A;MATHEMATICAL ITALIC CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D43B;MATHEMATICAL ITALIC CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D43C;MATHEMATICAL ITALIC CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D43D;MATHEMATICAL ITALIC CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D43E;MATHEMATICAL ITALIC CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D43F;MATHEMATICAL ITALIC CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D440;MATHEMATICAL ITALIC CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D441;MATHEMATICAL ITALIC CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D442;MATHEMATICAL ITALIC CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D443;MATHEMATICAL ITALIC CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D444;MATHEMATICAL ITALIC CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D445;MATHEMATICAL ITALIC CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D446;MATHEMATICAL ITALIC CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D447;MATHEMATICAL ITALIC CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D448;MATHEMATICAL ITALIC CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D449;MATHEMATICAL ITALIC CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D44A;MATHEMATICAL ITALIC CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D44B;MATHEMATICAL ITALIC CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D44C;MATHEMATICAL ITALIC CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D44D;MATHEMATICAL ITALIC CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D44E;MATHEMATICAL ITALIC SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D44F;MATHEMATICAL ITALIC SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D450;MATHEMATICAL ITALIC SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D451;MATHEMATICAL ITALIC SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D452;MATHEMATICAL ITALIC SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D453;MATHEMATICAL ITALIC SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D454;MATHEMATICAL ITALIC SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D456;MATHEMATICAL ITALIC SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D457;MATHEMATICAL ITALIC SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D458;MATHEMATICAL ITALIC SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D459;MATHEMATICAL ITALIC SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D45A;MATHEMATICAL ITALIC SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D45B;MATHEMATICAL ITALIC SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D45C;MATHEMATICAL ITALIC SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D45D;MATHEMATICAL ITALIC SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D45E;MATHEMATICAL ITALIC SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D45F;MATHEMATICAL ITALIC SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D460;MATHEMATICAL ITALIC SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D461;MATHEMATICAL ITALIC SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D462;MATHEMATICAL ITALIC SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D463;MATHEMATICAL ITALIC SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D464;MATHEMATICAL ITALIC SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D465;MATHEMATICAL ITALIC SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D466;MATHEMATICAL ITALIC SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D467;MATHEMATICAL ITALIC SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D468;MATHEMATICAL BOLD ITALIC CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D469;MATHEMATICAL BOLD ITALIC CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D46A;MATHEMATICAL BOLD ITALIC CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D46B;MATHEMATICAL BOLD ITALIC CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D46C;MATHEMATICAL BOLD ITALIC CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D46D;MATHEMATICAL BOLD ITALIC CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D46E;MATHEMATICAL BOLD ITALIC CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D46F;MATHEMATICAL BOLD ITALIC CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D470;MATHEMATICAL BOLD ITALIC CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D471;MATHEMATICAL BOLD ITALIC CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D472;MATHEMATICAL BOLD ITALIC CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D473;MATHEMATICAL BOLD ITALIC CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D474;MATHEMATICAL BOLD ITALIC CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D475;MATHEMATICAL BOLD ITALIC CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D476;MATHEMATICAL BOLD ITALIC CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D477;MATHEMATICAL BOLD ITALIC CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D478;MATHEMATICAL BOLD ITALIC CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D479;MATHEMATICAL BOLD ITALIC CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D47A;MATHEMATICAL BOLD ITALIC CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D47B;MATHEMATICAL BOLD ITALIC CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D47C;MATHEMATICAL BOLD ITALIC CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D47D;MATHEMATICAL BOLD ITALIC CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D47E;MATHEMATICAL BOLD ITALIC CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D47F;MATHEMATICAL BOLD ITALIC CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D480;MATHEMATICAL BOLD ITALIC CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D481;MATHEMATICAL BOLD ITALIC CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D482;MATHEMATICAL BOLD ITALIC SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D483;MATHEMATICAL BOLD ITALIC SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D484;MATHEMATICAL BOLD ITALIC SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D485;MATHEMATICAL BOLD ITALIC SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D486;MATHEMATICAL BOLD ITALIC SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D487;MATHEMATICAL BOLD ITALIC SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D488;MATHEMATICAL BOLD ITALIC SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D489;MATHEMATICAL BOLD ITALIC SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D48A;MATHEMATICAL BOLD ITALIC SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D48B;MATHEMATICAL BOLD ITALIC SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D48C;MATHEMATICAL BOLD ITALIC SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D48D;MATHEMATICAL BOLD ITALIC SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D48E;MATHEMATICAL BOLD ITALIC SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D48F;MATHEMATICAL BOLD ITALIC SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D490;MATHEMATICAL BOLD ITALIC SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D491;MATHEMATICAL BOLD ITALIC SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D492;MATHEMATICAL BOLD ITALIC SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D493;MATHEMATICAL BOLD ITALIC SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D494;MATHEMATICAL BOLD ITALIC SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D495;MATHEMATICAL BOLD ITALIC SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D496;MATHEMATICAL BOLD ITALIC SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D497;MATHEMATICAL BOLD ITALIC SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D498;MATHEMATICAL BOLD ITALIC SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D499;MATHEMATICAL BOLD ITALIC SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D49A;MATHEMATICAL BOLD ITALIC SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D49B;MATHEMATICAL BOLD ITALIC SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D49C;MATHEMATICAL SCRIPT CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D49E;MATHEMATICAL SCRIPT CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D49F;MATHEMATICAL SCRIPT CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D4A2;MATHEMATICAL SCRIPT CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D4A5;MATHEMATICAL SCRIPT CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D4A6;MATHEMATICAL SCRIPT CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D4A9;MATHEMATICAL SCRIPT CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D4AA;MATHEMATICAL SCRIPT CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D4AB;MATHEMATICAL SCRIPT CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D4AC;MATHEMATICAL SCRIPT CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D4AE;MATHEMATICAL SCRIPT CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D4AF;MATHEMATICAL SCRIPT CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D4B0;MATHEMATICAL SCRIPT CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D4B1;MATHEMATICAL SCRIPT CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D4B2;MATHEMATICAL SCRIPT CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D4B3;MATHEMATICAL SCRIPT CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D4B4;MATHEMATICAL SCRIPT CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D4B5;MATHEMATICAL SCRIPT CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D4B6;MATHEMATICAL SCRIPT SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D4B7;MATHEMATICAL SCRIPT SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D4B8;MATHEMATICAL SCRIPT SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D4B9;MATHEMATICAL SCRIPT SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D4BB;MATHEMATICAL SCRIPT SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D4BD;MATHEMATICAL SCRIPT SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D4BE;MATHEMATICAL SCRIPT SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D4BF;MATHEMATICAL SCRIPT SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D4C0;MATHEMATICAL SCRIPT SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D4C1;MATHEMATICAL SCRIPT SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D4C2;MATHEMATICAL SCRIPT SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D4C3;MATHEMATICAL SCRIPT SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D4C5;MATHEMATICAL SCRIPT SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D4C6;MATHEMATICAL SCRIPT SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D4C7;MATHEMATICAL SCRIPT SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D4C8;MATHEMATICAL SCRIPT SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D4C9;MATHEMATICAL SCRIPT SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D4CA;MATHEMATICAL SCRIPT SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D4CB;MATHEMATICAL SCRIPT SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D4CC;MATHEMATICAL SCRIPT SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D4CD;MATHEMATICAL SCRIPT SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D4CE;MATHEMATICAL SCRIPT SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D4CF;MATHEMATICAL SCRIPT SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D4D0;MATHEMATICAL BOLD SCRIPT CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D4D1;MATHEMATICAL BOLD SCRIPT CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D4D2;MATHEMATICAL BOLD SCRIPT CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D4D3;MATHEMATICAL BOLD SCRIPT CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D4D4;MATHEMATICAL BOLD SCRIPT CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D4D5;MATHEMATICAL BOLD SCRIPT CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D4D6;MATHEMATICAL BOLD SCRIPT CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D4D7;MATHEMATICAL BOLD SCRIPT CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D4D8;MATHEMATICAL BOLD SCRIPT CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D4D9;MATHEMATICAL BOLD SCRIPT CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D4DA;MATHEMATICAL BOLD SCRIPT CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D4DB;MATHEMATICAL BOLD SCRIPT CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D4DC;MATHEMATICAL BOLD SCRIPT CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D4DD;MATHEMATICAL BOLD SCRIPT CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D4DE;MATHEMATICAL BOLD SCRIPT CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D4DF;MATHEMATICAL BOLD SCRIPT CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D4E0;MATHEMATICAL BOLD SCRIPT CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D4E1;MATHEMATICAL BOLD SCRIPT CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D4E2;MATHEMATICAL BOLD SCRIPT CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D4E3;MATHEMATICAL BOLD SCRIPT CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D4E4;MATHEMATICAL BOLD SCRIPT CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D4E5;MATHEMATICAL BOLD SCRIPT CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D4E6;MATHEMATICAL BOLD SCRIPT CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D4E7;MATHEMATICAL BOLD SCRIPT CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D4E8;MATHEMATICAL BOLD SCRIPT CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D4E9;MATHEMATICAL BOLD SCRIPT CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D4EA;MATHEMATICAL BOLD SCRIPT SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D4EB;MATHEMATICAL BOLD SCRIPT SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D4EC;MATHEMATICAL BOLD SCRIPT SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D4ED;MATHEMATICAL BOLD SCRIPT SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D4EE;MATHEMATICAL BOLD SCRIPT SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D4EF;MATHEMATICAL BOLD SCRIPT SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D4F0;MATHEMATICAL BOLD SCRIPT SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D4F1;MATHEMATICAL BOLD SCRIPT SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D4F2;MATHEMATICAL BOLD SCRIPT SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D4F3;MATHEMATICAL BOLD SCRIPT SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D4F4;MATHEMATICAL BOLD SCRIPT SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D4F5;MATHEMATICAL BOLD SCRIPT SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D4F6;MATHEMATICAL BOLD SCRIPT SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D4F7;MATHEMATICAL BOLD SCRIPT SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D4F8;MATHEMATICAL BOLD SCRIPT SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D4F9;MATHEMATICAL BOLD SCRIPT SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D4FA;MATHEMATICAL BOLD SCRIPT SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D4FB;MATHEMATICAL BOLD SCRIPT SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D4FC;MATHEMATICAL BOLD SCRIPT SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D4FD;MATHEMATICAL BOLD SCRIPT SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D4FE;MATHEMATICAL BOLD SCRIPT SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D4FF;MATHEMATICAL BOLD SCRIPT SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D500;MATHEMATICAL BOLD SCRIPT SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D501;MATHEMATICAL BOLD SCRIPT SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D502;MATHEMATICAL BOLD SCRIPT SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D503;MATHEMATICAL BOLD SCRIPT SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D504;MATHEMATICAL FRAKTUR CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D505;MATHEMATICAL FRAKTUR CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D507;MATHEMATICAL FRAKTUR CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D508;MATHEMATICAL FRAKTUR CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D509;MATHEMATICAL FRAKTUR CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D50A;MATHEMATICAL FRAKTUR CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D50D;MATHEMATICAL FRAKTUR CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D50E;MATHEMATICAL FRAKTUR CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D50F;MATHEMATICAL FRAKTUR CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D510;MATHEMATICAL FRAKTUR CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D511;MATHEMATICAL FRAKTUR CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D512;MATHEMATICAL FRAKTUR CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D513;MATHEMATICAL FRAKTUR CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D514;MATHEMATICAL FRAKTUR CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D516;MATHEMATICAL FRAKTUR CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D517;MATHEMATICAL FRAKTUR CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D518;MATHEMATICAL FRAKTUR CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D519;MATHEMATICAL FRAKTUR CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D51A;MATHEMATICAL FRAKTUR CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D51B;MATHEMATICAL FRAKTUR CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D51C;MATHEMATICAL FRAKTUR CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D51E;MATHEMATICAL FRAKTUR SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D51F;MATHEMATICAL FRAKTUR SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D520;MATHEMATICAL FRAKTUR SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D521;MATHEMATICAL FRAKTUR SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D522;MATHEMATICAL FRAKTUR SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D523;MATHEMATICAL FRAKTUR SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D524;MATHEMATICAL FRAKTUR SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D525;MATHEMATICAL FRAKTUR SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D526;MATHEMATICAL FRAKTUR SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D527;MATHEMATICAL FRAKTUR SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D528;MATHEMATICAL FRAKTUR SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D529;MATHEMATICAL FRAKTUR SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D52A;MATHEMATICAL FRAKTUR SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D52B;MATHEMATICAL FRAKTUR SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D52C;MATHEMATICAL FRAKTUR SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D52D;MATHEMATICAL FRAKTUR SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D52E;MATHEMATICAL FRAKTUR SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D52F;MATHEMATICAL FRAKTUR SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D530;MATHEMATICAL FRAKTUR SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D531;MATHEMATICAL FRAKTUR SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D532;MATHEMATICAL FRAKTUR SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D533;MATHEMATICAL FRAKTUR SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D534;MATHEMATICAL FRAKTUR SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D535;MATHEMATICAL FRAKTUR SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D536;MATHEMATICAL FRAKTUR SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D537;MATHEMATICAL FRAKTUR SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D538;MATHEMATICAL DOUBLE-STRUCK CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D539;MATHEMATICAL DOUBLE-STRUCK CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D53B;MATHEMATICAL DOUBLE-STRUCK CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D53C;MATHEMATICAL DOUBLE-STRUCK CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D53D;MATHEMATICAL DOUBLE-STRUCK CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D53E;MATHEMATICAL DOUBLE-STRUCK CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D540;MATHEMATICAL DOUBLE-STRUCK CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D541;MATHEMATICAL DOUBLE-STRUCK CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D542;MATHEMATICAL DOUBLE-STRUCK CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D543;MATHEMATICAL DOUBLE-STRUCK CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D544;MATHEMATICAL DOUBLE-STRUCK CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D546;MATHEMATICAL DOUBLE-STRUCK CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D54A;MATHEMATICAL DOUBLE-STRUCK CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D54B;MATHEMATICAL DOUBLE-STRUCK CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D54C;MATHEMATICAL DOUBLE-STRUCK CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D54D;MATHEMATICAL DOUBLE-STRUCK CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D54E;MATHEMATICAL DOUBLE-STRUCK CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D54F;MATHEMATICAL DOUBLE-STRUCK CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D550;MATHEMATICAL DOUBLE-STRUCK CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D552;MATHEMATICAL DOUBLE-STRUCK SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D553;MATHEMATICAL DOUBLE-STRUCK SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D554;MATHEMATICAL DOUBLE-STRUCK SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D555;MATHEMATICAL DOUBLE-STRUCK SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D556;MATHEMATICAL DOUBLE-STRUCK SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D557;MATHEMATICAL DOUBLE-STRUCK SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D558;MATHEMATICAL DOUBLE-STRUCK SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D559;MATHEMATICAL DOUBLE-STRUCK SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D55A;MATHEMATICAL DOUBLE-STRUCK SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D55B;MATHEMATICAL DOUBLE-STRUCK SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D55C;MATHEMATICAL DOUBLE-STRUCK SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D55D;MATHEMATICAL DOUBLE-STRUCK SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D55E;MATHEMATICAL DOUBLE-STRUCK SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D55F;MATHEMATICAL DOUBLE-STRUCK SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D560;MATHEMATICAL DOUBLE-STRUCK SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D561;MATHEMATICAL DOUBLE-STRUCK SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D562;MATHEMATICAL DOUBLE-STRUCK SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D563;MATHEMATICAL DOUBLE-STRUCK SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D564;MATHEMATICAL DOUBLE-STRUCK SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D565;MATHEMATICAL DOUBLE-STRUCK SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D566;MATHEMATICAL DOUBLE-STRUCK SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D567;MATHEMATICAL DOUBLE-STRUCK SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D568;MATHEMATICAL DOUBLE-STRUCK SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D569;MATHEMATICAL DOUBLE-STRUCK SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D56A;MATHEMATICAL DOUBLE-STRUCK SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D56B;MATHEMATICAL DOUBLE-STRUCK SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D56C;MATHEMATICAL BOLD FRAKTUR CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D56D;MATHEMATICAL BOLD FRAKTUR CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D56E;MATHEMATICAL BOLD FRAKTUR CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D56F;MATHEMATICAL BOLD FRAKTUR CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D570;MATHEMATICAL BOLD FRAKTUR CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D571;MATHEMATICAL BOLD FRAKTUR CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D572;MATHEMATICAL BOLD FRAKTUR CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D573;MATHEMATICAL BOLD FRAKTUR CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D574;MATHEMATICAL BOLD FRAKTUR CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D575;MATHEMATICAL BOLD FRAKTUR CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D576;MATHEMATICAL BOLD FRAKTUR CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D577;MATHEMATICAL BOLD FRAKTUR CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D578;MATHEMATICAL BOLD FRAKTUR CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D579;MATHEMATICAL BOLD FRAKTUR CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D57A;MATHEMATICAL BOLD FRAKTUR CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D57B;MATHEMATICAL BOLD FRAKTUR CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D57C;MATHEMATICAL BOLD FRAKTUR CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D57D;MATHEMATICAL BOLD FRAKTUR CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D57E;MATHEMATICAL BOLD FRAKTUR CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D57F;MATHEMATICAL BOLD FRAKTUR CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D580;MATHEMATICAL BOLD FRAKTUR CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D581;MATHEMATICAL BOLD FRAKTUR CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D582;MATHEMATICAL BOLD FRAKTUR CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D583;MATHEMATICAL BOLD FRAKTUR CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D584;MATHEMATICAL BOLD FRAKTUR CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D585;MATHEMATICAL BOLD FRAKTUR CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D586;MATHEMATICAL BOLD FRAKTUR SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D587;MATHEMATICAL BOLD FRAKTUR SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D588;MATHEMATICAL BOLD FRAKTUR SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D589;MATHEMATICAL BOLD FRAKTUR SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D58A;MATHEMATICAL BOLD FRAKTUR SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D58B;MATHEMATICAL BOLD FRAKTUR SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D58C;MATHEMATICAL BOLD FRAKTUR SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D58D;MATHEMATICAL BOLD FRAKTUR SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D58E;MATHEMATICAL BOLD FRAKTUR SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D58F;MATHEMATICAL BOLD FRAKTUR SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D590;MATHEMATICAL BOLD FRAKTUR SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D591;MATHEMATICAL BOLD FRAKTUR SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D592;MATHEMATICAL BOLD FRAKTUR SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D593;MATHEMATICAL BOLD FRAKTUR SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D594;MATHEMATICAL BOLD FRAKTUR SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D595;MATHEMATICAL BOLD FRAKTUR SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D596;MATHEMATICAL BOLD FRAKTUR SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D597;MATHEMATICAL BOLD FRAKTUR SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D598;MATHEMATICAL BOLD FRAKTUR SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D599;MATHEMATICAL BOLD FRAKTUR SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D59A;MATHEMATICAL BOLD FRAKTUR SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D59B;MATHEMATICAL BOLD FRAKTUR SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D59C;MATHEMATICAL BOLD FRAKTUR SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D59D;MATHEMATICAL BOLD FRAKTUR SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D59E;MATHEMATICAL BOLD FRAKTUR SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D59F;MATHEMATICAL BOLD FRAKTUR SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D5A0;MATHEMATICAL SANS-SERIF CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D5A1;MATHEMATICAL SANS-SERIF CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D5A2;MATHEMATICAL SANS-SERIF CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D5A3;MATHEMATICAL SANS-SERIF CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D5A4;MATHEMATICAL SANS-SERIF CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D5A5;MATHEMATICAL SANS-SERIF CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D5A6;MATHEMATICAL SANS-SERIF CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D5A7;MATHEMATICAL SANS-SERIF CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D5A8;MATHEMATICAL SANS-SERIF CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D5A9;MATHEMATICAL SANS-SERIF CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D5AA;MATHEMATICAL SANS-SERIF CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D5AB;MATHEMATICAL SANS-SERIF CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D5AC;MATHEMATICAL SANS-SERIF CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D5AD;MATHEMATICAL SANS-SERIF CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D5AE;MATHEMATICAL SANS-SERIF CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D5AF;MATHEMATICAL SANS-SERIF CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D5B0;MATHEMATICAL SANS-SERIF CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D5B1;MATHEMATICAL SANS-SERIF CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D5B2;MATHEMATICAL SANS-SERIF CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D5B3;MATHEMATICAL SANS-SERIF CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D5B4;MATHEMATICAL SANS-SERIF CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D5B5;MATHEMATICAL SANS-SERIF CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D5B6;MATHEMATICAL SANS-SERIF CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D5B7;MATHEMATICAL SANS-SERIF CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D5B8;MATHEMATICAL SANS-SERIF CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D5B9;MATHEMATICAL SANS-SERIF CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D5BA;MATHEMATICAL SANS-SERIF SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D5BB;MATHEMATICAL SANS-SERIF SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D5BC;MATHEMATICAL SANS-SERIF SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D5BD;MATHEMATICAL SANS-SERIF SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D5BE;MATHEMATICAL SANS-SERIF SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D5BF;MATHEMATICAL SANS-SERIF SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D5C0;MATHEMATICAL SANS-SERIF SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D5C1;MATHEMATICAL SANS-SERIF SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D5C2;MATHEMATICAL SANS-SERIF SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D5C3;MATHEMATICAL SANS-SERIF SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D5C4;MATHEMATICAL SANS-SERIF SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D5C5;MATHEMATICAL SANS-SERIF SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D5C6;MATHEMATICAL SANS-SERIF SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D5C7;MATHEMATICAL SANS-SERIF SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D5C8;MATHEMATICAL SANS-SERIF SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D5C9;MATHEMATICAL SANS-SERIF SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D5CA;MATHEMATICAL SANS-SERIF SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D5CB;MATHEMATICAL SANS-SERIF SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D5CC;MATHEMATICAL SANS-SERIF SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D5CD;MATHEMATICAL SANS-SERIF SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D5CE;MATHEMATICAL SANS-SERIF SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D5CF;MATHEMATICAL SANS-SERIF SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D5D0;MATHEMATICAL SANS-SERIF SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D5D1;MATHEMATICAL SANS-SERIF SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D5D2;MATHEMATICAL SANS-SERIF SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D5D3;MATHEMATICAL SANS-SERIF SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D5D4;MATHEMATICAL SANS-SERIF BOLD CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D5D5;MATHEMATICAL SANS-SERIF BOLD CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D5D6;MATHEMATICAL SANS-SERIF BOLD CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D5D7;MATHEMATICAL SANS-SERIF BOLD CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D5D8;MATHEMATICAL SANS-SERIF BOLD CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D5D9;MATHEMATICAL SANS-SERIF BOLD CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D5DA;MATHEMATICAL SANS-SERIF BOLD CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D5DB;MATHEMATICAL SANS-SERIF BOLD CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D5DC;MATHEMATICAL SANS-SERIF BOLD CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D5DD;MATHEMATICAL SANS-SERIF BOLD CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D5DE;MATHEMATICAL SANS-SERIF BOLD CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D5DF;MATHEMATICAL SANS-SERIF BOLD CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D5E0;MATHEMATICAL SANS-SERIF BOLD CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D5E1;MATHEMATICAL SANS-SERIF BOLD CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D5E2;MATHEMATICAL SANS-SERIF BOLD CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D5E3;MATHEMATICAL SANS-SERIF BOLD CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D5E4;MATHEMATICAL SANS-SERIF BOLD CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D5E5;MATHEMATICAL SANS-SERIF BOLD CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D5E6;MATHEMATICAL SANS-SERIF BOLD CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D5E7;MATHEMATICAL SANS-SERIF BOLD CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D5E8;MATHEMATICAL SANS-SERIF BOLD CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D5E9;MATHEMATICAL SANS-SERIF BOLD CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D5EA;MATHEMATICAL SANS-SERIF BOLD CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D5EB;MATHEMATICAL SANS-SERIF BOLD CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D5EC;MATHEMATICAL SANS-SERIF BOLD CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D5ED;MATHEMATICAL SANS-SERIF BOLD CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D5EE;MATHEMATICAL SANS-SERIF BOLD SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D5EF;MATHEMATICAL SANS-SERIF BOLD SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D5F0;MATHEMATICAL SANS-SERIF BOLD SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D5F1;MATHEMATICAL SANS-SERIF BOLD SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D5F2;MATHEMATICAL SANS-SERIF BOLD SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D5F3;MATHEMATICAL SANS-SERIF BOLD SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D5F4;MATHEMATICAL SANS-SERIF BOLD SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D5F5;MATHEMATICAL SANS-SERIF BOLD SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D5F6;MATHEMATICAL SANS-SERIF BOLD SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D5F7;MATHEMATICAL SANS-SERIF BOLD SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D5F8;MATHEMATICAL SANS-SERIF BOLD SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D5F9;MATHEMATICAL SANS-SERIF BOLD SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D5FA;MATHEMATICAL SANS-SERIF BOLD SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D5FB;MATHEMATICAL SANS-SERIF BOLD SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D5FC;MATHEMATICAL SANS-SERIF BOLD SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D5FD;MATHEMATICAL SANS-SERIF BOLD SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D5FE;MATHEMATICAL SANS-SERIF BOLD SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D5FF;MATHEMATICAL SANS-SERIF BOLD SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D600;MATHEMATICAL SANS-SERIF BOLD SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D601;MATHEMATICAL SANS-SERIF BOLD SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D602;MATHEMATICAL SANS-SERIF BOLD SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D603;MATHEMATICAL SANS-SERIF BOLD SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D604;MATHEMATICAL SANS-SERIF BOLD SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D605;MATHEMATICAL SANS-SERIF BOLD SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D606;MATHEMATICAL SANS-SERIF BOLD SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D607;MATHEMATICAL SANS-SERIF BOLD SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D608;MATHEMATICAL SANS-SERIF ITALIC CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D609;MATHEMATICAL SANS-SERIF ITALIC CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D60A;MATHEMATICAL SANS-SERIF ITALIC CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D60B;MATHEMATICAL SANS-SERIF ITALIC CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D60C;MATHEMATICAL SANS-SERIF ITALIC CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D60D;MATHEMATICAL SANS-SERIF ITALIC CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D60E;MATHEMATICAL SANS-SERIF ITALIC CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D60F;MATHEMATICAL SANS-SERIF ITALIC CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D610;MATHEMATICAL SANS-SERIF ITALIC CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D611;MATHEMATICAL SANS-SERIF ITALIC CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D612;MATHEMATICAL SANS-SERIF ITALIC CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D613;MATHEMATICAL SANS-SERIF ITALIC CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D614;MATHEMATICAL SANS-SERIF ITALIC CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D615;MATHEMATICAL SANS-SERIF ITALIC CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D616;MATHEMATICAL SANS-SERIF ITALIC CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D617;MATHEMATICAL SANS-SERIF ITALIC CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D618;MATHEMATICAL SANS-SERIF ITALIC CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D619;MATHEMATICAL SANS-SERIF ITALIC CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D61A;MATHEMATICAL SANS-SERIF ITALIC CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D61B;MATHEMATICAL SANS-SERIF ITALIC CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D61C;MATHEMATICAL SANS-SERIF ITALIC CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D61D;MATHEMATICAL SANS-SERIF ITALIC CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D61E;MATHEMATICAL SANS-SERIF ITALIC CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D61F;MATHEMATICAL SANS-SERIF ITALIC CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D620;MATHEMATICAL SANS-SERIF ITALIC CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D621;MATHEMATICAL SANS-SERIF ITALIC CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D622;MATHEMATICAL SANS-SERIF ITALIC SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D623;MATHEMATICAL SANS-SERIF ITALIC SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D624;MATHEMATICAL SANS-SERIF ITALIC SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D625;MATHEMATICAL SANS-SERIF ITALIC SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D626;MATHEMATICAL SANS-SERIF ITALIC SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D627;MATHEMATICAL SANS-SERIF ITALIC SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D628;MATHEMATICAL SANS-SERIF ITALIC SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D629;MATHEMATICAL SANS-SERIF ITALIC SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D62A;MATHEMATICAL SANS-SERIF ITALIC SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D62B;MATHEMATICAL SANS-SERIF ITALIC SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D62C;MATHEMATICAL SANS-SERIF ITALIC SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D62D;MATHEMATICAL SANS-SERIF ITALIC SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D62E;MATHEMATICAL SANS-SERIF ITALIC SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D62F;MATHEMATICAL SANS-SERIF ITALIC SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D630;MATHEMATICAL SANS-SERIF ITALIC SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D631;MATHEMATICAL SANS-SERIF ITALIC SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D632;MATHEMATICAL SANS-SERIF ITALIC SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D633;MATHEMATICAL SANS-SERIF ITALIC SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D634;MATHEMATICAL SANS-SERIF ITALIC SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D635;MATHEMATICAL SANS-SERIF ITALIC SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D636;MATHEMATICAL SANS-SERIF ITALIC SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D637;MATHEMATICAL SANS-SERIF ITALIC SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D638;MATHEMATICAL SANS-SERIF ITALIC SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D639;MATHEMATICAL SANS-SERIF ITALIC SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D63A;MATHEMATICAL SANS-SERIF ITALIC SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D63B;MATHEMATICAL SANS-SERIF ITALIC SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D63C;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D63D;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D63E;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D63F;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D640;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D641;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D642;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D643;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D644;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D645;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D646;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D647;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D648;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D649;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D64A;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D64B;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D64C;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D64D;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D64E;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D64F;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D650;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D651;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D652;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D653;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D654;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D655;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D656;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D657;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D658;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D659;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D65A;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D65B;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D65C;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D65D;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D65E;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D65F;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D660;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D661;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D662;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D663;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D664;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D665;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D666;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D667;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D668;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D669;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D66A;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D66B;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D66C;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D66D;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D66E;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D66F;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D670;MATHEMATICAL MONOSPACE CAPITAL A;Lu;0;L; 0041;;;;N;;;;; -1D671;MATHEMATICAL MONOSPACE CAPITAL B;Lu;0;L; 0042;;;;N;;;;; -1D672;MATHEMATICAL MONOSPACE CAPITAL C;Lu;0;L; 0043;;;;N;;;;; -1D673;MATHEMATICAL MONOSPACE CAPITAL D;Lu;0;L; 0044;;;;N;;;;; -1D674;MATHEMATICAL MONOSPACE CAPITAL E;Lu;0;L; 0045;;;;N;;;;; -1D675;MATHEMATICAL MONOSPACE CAPITAL F;Lu;0;L; 0046;;;;N;;;;; -1D676;MATHEMATICAL MONOSPACE CAPITAL G;Lu;0;L; 0047;;;;N;;;;; -1D677;MATHEMATICAL MONOSPACE CAPITAL H;Lu;0;L; 0048;;;;N;;;;; -1D678;MATHEMATICAL MONOSPACE CAPITAL I;Lu;0;L; 0049;;;;N;;;;; -1D679;MATHEMATICAL MONOSPACE CAPITAL J;Lu;0;L; 004A;;;;N;;;;; -1D67A;MATHEMATICAL MONOSPACE CAPITAL K;Lu;0;L; 004B;;;;N;;;;; -1D67B;MATHEMATICAL MONOSPACE CAPITAL L;Lu;0;L; 004C;;;;N;;;;; -1D67C;MATHEMATICAL MONOSPACE CAPITAL M;Lu;0;L; 004D;;;;N;;;;; -1D67D;MATHEMATICAL MONOSPACE CAPITAL N;Lu;0;L; 004E;;;;N;;;;; -1D67E;MATHEMATICAL MONOSPACE CAPITAL O;Lu;0;L; 004F;;;;N;;;;; -1D67F;MATHEMATICAL MONOSPACE CAPITAL P;Lu;0;L; 0050;;;;N;;;;; -1D680;MATHEMATICAL MONOSPACE CAPITAL Q;Lu;0;L; 0051;;;;N;;;;; -1D681;MATHEMATICAL MONOSPACE CAPITAL R;Lu;0;L; 0052;;;;N;;;;; -1D682;MATHEMATICAL MONOSPACE CAPITAL S;Lu;0;L; 0053;;;;N;;;;; -1D683;MATHEMATICAL MONOSPACE CAPITAL T;Lu;0;L; 0054;;;;N;;;;; -1D684;MATHEMATICAL MONOSPACE CAPITAL U;Lu;0;L; 0055;;;;N;;;;; -1D685;MATHEMATICAL MONOSPACE CAPITAL V;Lu;0;L; 0056;;;;N;;;;; -1D686;MATHEMATICAL MONOSPACE CAPITAL W;Lu;0;L; 0057;;;;N;;;;; -1D687;MATHEMATICAL MONOSPACE CAPITAL X;Lu;0;L; 0058;;;;N;;;;; -1D688;MATHEMATICAL MONOSPACE CAPITAL Y;Lu;0;L; 0059;;;;N;;;;; -1D689;MATHEMATICAL MONOSPACE CAPITAL Z;Lu;0;L; 005A;;;;N;;;;; -1D68A;MATHEMATICAL MONOSPACE SMALL A;Ll;0;L; 0061;;;;N;;;;; -1D68B;MATHEMATICAL MONOSPACE SMALL B;Ll;0;L; 0062;;;;N;;;;; -1D68C;MATHEMATICAL MONOSPACE SMALL C;Ll;0;L; 0063;;;;N;;;;; -1D68D;MATHEMATICAL MONOSPACE SMALL D;Ll;0;L; 0064;;;;N;;;;; -1D68E;MATHEMATICAL MONOSPACE SMALL E;Ll;0;L; 0065;;;;N;;;;; -1D68F;MATHEMATICAL MONOSPACE SMALL F;Ll;0;L; 0066;;;;N;;;;; -1D690;MATHEMATICAL MONOSPACE SMALL G;Ll;0;L; 0067;;;;N;;;;; -1D691;MATHEMATICAL MONOSPACE SMALL H;Ll;0;L; 0068;;;;N;;;;; -1D692;MATHEMATICAL MONOSPACE SMALL I;Ll;0;L; 0069;;;;N;;;;; -1D693;MATHEMATICAL MONOSPACE SMALL J;Ll;0;L; 006A;;;;N;;;;; -1D694;MATHEMATICAL MONOSPACE SMALL K;Ll;0;L; 006B;;;;N;;;;; -1D695;MATHEMATICAL MONOSPACE SMALL L;Ll;0;L; 006C;;;;N;;;;; -1D696;MATHEMATICAL MONOSPACE SMALL M;Ll;0;L; 006D;;;;N;;;;; -1D697;MATHEMATICAL MONOSPACE SMALL N;Ll;0;L; 006E;;;;N;;;;; -1D698;MATHEMATICAL MONOSPACE SMALL O;Ll;0;L; 006F;;;;N;;;;; -1D699;MATHEMATICAL MONOSPACE SMALL P;Ll;0;L; 0070;;;;N;;;;; -1D69A;MATHEMATICAL MONOSPACE SMALL Q;Ll;0;L; 0071;;;;N;;;;; -1D69B;MATHEMATICAL MONOSPACE SMALL R;Ll;0;L; 0072;;;;N;;;;; -1D69C;MATHEMATICAL MONOSPACE SMALL S;Ll;0;L; 0073;;;;N;;;;; -1D69D;MATHEMATICAL MONOSPACE SMALL T;Ll;0;L; 0074;;;;N;;;;; -1D69E;MATHEMATICAL MONOSPACE SMALL U;Ll;0;L; 0075;;;;N;;;;; -1D69F;MATHEMATICAL MONOSPACE SMALL V;Ll;0;L; 0076;;;;N;;;;; -1D6A0;MATHEMATICAL MONOSPACE SMALL W;Ll;0;L; 0077;;;;N;;;;; -1D6A1;MATHEMATICAL MONOSPACE SMALL X;Ll;0;L; 0078;;;;N;;;;; -1D6A2;MATHEMATICAL MONOSPACE SMALL Y;Ll;0;L; 0079;;;;N;;;;; -1D6A3;MATHEMATICAL MONOSPACE SMALL Z;Ll;0;L; 007A;;;;N;;;;; -1D6A4;MATHEMATICAL ITALIC SMALL DOTLESS I;Ll;0;L; 0131;;;;N;;;;; -1D6A5;MATHEMATICAL ITALIC SMALL DOTLESS J;Ll;0;L; 0237;;;;N;;;;; -1D6A8;MATHEMATICAL BOLD CAPITAL ALPHA;Lu;0;L; 0391;;;;N;;;;; -1D6A9;MATHEMATICAL BOLD CAPITAL BETA;Lu;0;L; 0392;;;;N;;;;; -1D6AA;MATHEMATICAL BOLD CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -1D6AB;MATHEMATICAL BOLD CAPITAL DELTA;Lu;0;L; 0394;;;;N;;;;; -1D6AC;MATHEMATICAL BOLD CAPITAL EPSILON;Lu;0;L; 0395;;;;N;;;;; -1D6AD;MATHEMATICAL BOLD CAPITAL ZETA;Lu;0;L; 0396;;;;N;;;;; -1D6AE;MATHEMATICAL BOLD CAPITAL ETA;Lu;0;L; 0397;;;;N;;;;; -1D6AF;MATHEMATICAL BOLD CAPITAL THETA;Lu;0;L; 0398;;;;N;;;;; -1D6B0;MATHEMATICAL BOLD CAPITAL IOTA;Lu;0;L; 0399;;;;N;;;;; -1D6B1;MATHEMATICAL BOLD CAPITAL KAPPA;Lu;0;L; 039A;;;;N;;;;; -1D6B2;MATHEMATICAL BOLD CAPITAL LAMDA;Lu;0;L; 039B;;;;N;;;;; -1D6B3;MATHEMATICAL BOLD CAPITAL MU;Lu;0;L; 039C;;;;N;;;;; -1D6B4;MATHEMATICAL BOLD CAPITAL NU;Lu;0;L; 039D;;;;N;;;;; -1D6B5;MATHEMATICAL BOLD CAPITAL XI;Lu;0;L; 039E;;;;N;;;;; -1D6B6;MATHEMATICAL BOLD CAPITAL OMICRON;Lu;0;L; 039F;;;;N;;;;; -1D6B7;MATHEMATICAL BOLD CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -1D6B8;MATHEMATICAL BOLD CAPITAL RHO;Lu;0;L; 03A1;;;;N;;;;; -1D6B9;MATHEMATICAL BOLD CAPITAL THETA SYMBOL;Lu;0;L; 03F4;;;;N;;;;; -1D6BA;MATHEMATICAL BOLD CAPITAL SIGMA;Lu;0;L; 03A3;;;;N;;;;; -1D6BB;MATHEMATICAL BOLD CAPITAL TAU;Lu;0;L; 03A4;;;;N;;;;; -1D6BC;MATHEMATICAL BOLD CAPITAL UPSILON;Lu;0;L; 03A5;;;;N;;;;; -1D6BD;MATHEMATICAL BOLD CAPITAL PHI;Lu;0;L; 03A6;;;;N;;;;; -1D6BE;MATHEMATICAL BOLD CAPITAL CHI;Lu;0;L; 03A7;;;;N;;;;; -1D6BF;MATHEMATICAL BOLD CAPITAL PSI;Lu;0;L; 03A8;;;;N;;;;; -1D6C0;MATHEMATICAL BOLD CAPITAL OMEGA;Lu;0;L; 03A9;;;;N;;;;; -1D6C1;MATHEMATICAL BOLD NABLA;Sm;0;L; 2207;;;;N;;;;; -1D6C2;MATHEMATICAL BOLD SMALL ALPHA;Ll;0;L; 03B1;;;;N;;;;; -1D6C3;MATHEMATICAL BOLD SMALL BETA;Ll;0;L; 03B2;;;;N;;;;; -1D6C4;MATHEMATICAL BOLD SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D6C5;MATHEMATICAL BOLD SMALL DELTA;Ll;0;L; 03B4;;;;N;;;;; -1D6C6;MATHEMATICAL BOLD SMALL EPSILON;Ll;0;L; 03B5;;;;N;;;;; -1D6C7;MATHEMATICAL BOLD SMALL ZETA;Ll;0;L; 03B6;;;;N;;;;; -1D6C8;MATHEMATICAL BOLD SMALL ETA;Ll;0;L; 03B7;;;;N;;;;; -1D6C9;MATHEMATICAL BOLD SMALL THETA;Ll;0;L; 03B8;;;;N;;;;; -1D6CA;MATHEMATICAL BOLD SMALL IOTA;Ll;0;L; 03B9;;;;N;;;;; -1D6CB;MATHEMATICAL BOLD SMALL KAPPA;Ll;0;L; 03BA;;;;N;;;;; -1D6CC;MATHEMATICAL BOLD SMALL LAMDA;Ll;0;L; 03BB;;;;N;;;;; -1D6CD;MATHEMATICAL BOLD SMALL MU;Ll;0;L; 03BC;;;;N;;;;; -1D6CE;MATHEMATICAL BOLD SMALL NU;Ll;0;L; 03BD;;;;N;;;;; -1D6CF;MATHEMATICAL BOLD SMALL XI;Ll;0;L; 03BE;;;;N;;;;; -1D6D0;MATHEMATICAL BOLD SMALL OMICRON;Ll;0;L; 03BF;;;;N;;;;; -1D6D1;MATHEMATICAL BOLD SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -1D6D2;MATHEMATICAL BOLD SMALL RHO;Ll;0;L; 03C1;;;;N;;;;; -1D6D3;MATHEMATICAL BOLD SMALL FINAL SIGMA;Ll;0;L; 03C2;;;;N;;;;; -1D6D4;MATHEMATICAL BOLD SMALL SIGMA;Ll;0;L; 03C3;;;;N;;;;; -1D6D5;MATHEMATICAL BOLD SMALL TAU;Ll;0;L; 03C4;;;;N;;;;; -1D6D6;MATHEMATICAL BOLD SMALL UPSILON;Ll;0;L; 03C5;;;;N;;;;; -1D6D7;MATHEMATICAL BOLD SMALL PHI;Ll;0;L; 03C6;;;;N;;;;; -1D6D8;MATHEMATICAL BOLD SMALL CHI;Ll;0;L; 03C7;;;;N;;;;; -1D6D9;MATHEMATICAL BOLD SMALL PSI;Ll;0;L; 03C8;;;;N;;;;; -1D6DA;MATHEMATICAL BOLD SMALL OMEGA;Ll;0;L; 03C9;;;;N;;;;; -1D6DB;MATHEMATICAL BOLD PARTIAL DIFFERENTIAL;Sm;0;L; 2202;;;;Y;;;;; -1D6DC;MATHEMATICAL BOLD EPSILON SYMBOL;Ll;0;L; 03F5;;;;N;;;;; -1D6DD;MATHEMATICAL BOLD THETA SYMBOL;Ll;0;L; 03D1;;;;N;;;;; -1D6DE;MATHEMATICAL BOLD KAPPA SYMBOL;Ll;0;L; 03F0;;;;N;;;;; -1D6DF;MATHEMATICAL BOLD PHI SYMBOL;Ll;0;L; 03D5;;;;N;;;;; -1D6E0;MATHEMATICAL BOLD RHO SYMBOL;Ll;0;L; 03F1;;;;N;;;;; -1D6E1;MATHEMATICAL BOLD PI SYMBOL;Ll;0;L; 03D6;;;;N;;;;; -1D6E2;MATHEMATICAL ITALIC CAPITAL ALPHA;Lu;0;L; 0391;;;;N;;;;; -1D6E3;MATHEMATICAL ITALIC CAPITAL BETA;Lu;0;L; 0392;;;;N;;;;; -1D6E4;MATHEMATICAL ITALIC CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -1D6E5;MATHEMATICAL ITALIC CAPITAL DELTA;Lu;0;L; 0394;;;;N;;;;; -1D6E6;MATHEMATICAL ITALIC CAPITAL EPSILON;Lu;0;L; 0395;;;;N;;;;; -1D6E7;MATHEMATICAL ITALIC CAPITAL ZETA;Lu;0;L; 0396;;;;N;;;;; -1D6E8;MATHEMATICAL ITALIC CAPITAL ETA;Lu;0;L; 0397;;;;N;;;;; -1D6E9;MATHEMATICAL ITALIC CAPITAL THETA;Lu;0;L; 0398;;;;N;;;;; -1D6EA;MATHEMATICAL ITALIC CAPITAL IOTA;Lu;0;L; 0399;;;;N;;;;; -1D6EB;MATHEMATICAL ITALIC CAPITAL KAPPA;Lu;0;L; 039A;;;;N;;;;; -1D6EC;MATHEMATICAL ITALIC CAPITAL LAMDA;Lu;0;L; 039B;;;;N;;;;; -1D6ED;MATHEMATICAL ITALIC CAPITAL MU;Lu;0;L; 039C;;;;N;;;;; -1D6EE;MATHEMATICAL ITALIC CAPITAL NU;Lu;0;L; 039D;;;;N;;;;; -1D6EF;MATHEMATICAL ITALIC CAPITAL XI;Lu;0;L; 039E;;;;N;;;;; -1D6F0;MATHEMATICAL ITALIC CAPITAL OMICRON;Lu;0;L; 039F;;;;N;;;;; -1D6F1;MATHEMATICAL ITALIC CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -1D6F2;MATHEMATICAL ITALIC CAPITAL RHO;Lu;0;L; 03A1;;;;N;;;;; -1D6F3;MATHEMATICAL ITALIC CAPITAL THETA SYMBOL;Lu;0;L; 03F4;;;;N;;;;; -1D6F4;MATHEMATICAL ITALIC CAPITAL SIGMA;Lu;0;L; 03A3;;;;N;;;;; -1D6F5;MATHEMATICAL ITALIC CAPITAL TAU;Lu;0;L; 03A4;;;;N;;;;; -1D6F6;MATHEMATICAL ITALIC CAPITAL UPSILON;Lu;0;L; 03A5;;;;N;;;;; -1D6F7;MATHEMATICAL ITALIC CAPITAL PHI;Lu;0;L; 03A6;;;;N;;;;; -1D6F8;MATHEMATICAL ITALIC CAPITAL CHI;Lu;0;L; 03A7;;;;N;;;;; -1D6F9;MATHEMATICAL ITALIC CAPITAL PSI;Lu;0;L; 03A8;;;;N;;;;; -1D6FA;MATHEMATICAL ITALIC CAPITAL OMEGA;Lu;0;L; 03A9;;;;N;;;;; -1D6FB;MATHEMATICAL ITALIC NABLA;Sm;0;L; 2207;;;;N;;;;; -1D6FC;MATHEMATICAL ITALIC SMALL ALPHA;Ll;0;L; 03B1;;;;N;;;;; -1D6FD;MATHEMATICAL ITALIC SMALL BETA;Ll;0;L; 03B2;;;;N;;;;; -1D6FE;MATHEMATICAL ITALIC SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D6FF;MATHEMATICAL ITALIC SMALL DELTA;Ll;0;L; 03B4;;;;N;;;;; -1D700;MATHEMATICAL ITALIC SMALL EPSILON;Ll;0;L; 03B5;;;;N;;;;; -1D701;MATHEMATICAL ITALIC SMALL ZETA;Ll;0;L; 03B6;;;;N;;;;; -1D702;MATHEMATICAL ITALIC SMALL ETA;Ll;0;L; 03B7;;;;N;;;;; -1D703;MATHEMATICAL ITALIC SMALL THETA;Ll;0;L; 03B8;;;;N;;;;; -1D704;MATHEMATICAL ITALIC SMALL IOTA;Ll;0;L; 03B9;;;;N;;;;; -1D705;MATHEMATICAL ITALIC SMALL KAPPA;Ll;0;L; 03BA;;;;N;;;;; -1D706;MATHEMATICAL ITALIC SMALL LAMDA;Ll;0;L; 03BB;;;;N;;;;; -1D707;MATHEMATICAL ITALIC SMALL MU;Ll;0;L; 03BC;;;;N;;;;; -1D708;MATHEMATICAL ITALIC SMALL NU;Ll;0;L; 03BD;;;;N;;;;; -1D709;MATHEMATICAL ITALIC SMALL XI;Ll;0;L; 03BE;;;;N;;;;; -1D70A;MATHEMATICAL ITALIC SMALL OMICRON;Ll;0;L; 03BF;;;;N;;;;; -1D70B;MATHEMATICAL ITALIC SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -1D70C;MATHEMATICAL ITALIC SMALL RHO;Ll;0;L; 03C1;;;;N;;;;; -1D70D;MATHEMATICAL ITALIC SMALL FINAL SIGMA;Ll;0;L; 03C2;;;;N;;;;; -1D70E;MATHEMATICAL ITALIC SMALL SIGMA;Ll;0;L; 03C3;;;;N;;;;; -1D70F;MATHEMATICAL ITALIC SMALL TAU;Ll;0;L; 03C4;;;;N;;;;; -1D710;MATHEMATICAL ITALIC SMALL UPSILON;Ll;0;L; 03C5;;;;N;;;;; -1D711;MATHEMATICAL ITALIC SMALL PHI;Ll;0;L; 03C6;;;;N;;;;; -1D712;MATHEMATICAL ITALIC SMALL CHI;Ll;0;L; 03C7;;;;N;;;;; -1D713;MATHEMATICAL ITALIC SMALL PSI;Ll;0;L; 03C8;;;;N;;;;; -1D714;MATHEMATICAL ITALIC SMALL OMEGA;Ll;0;L; 03C9;;;;N;;;;; -1D715;MATHEMATICAL ITALIC PARTIAL DIFFERENTIAL;Sm;0;L; 2202;;;;Y;;;;; -1D716;MATHEMATICAL ITALIC EPSILON SYMBOL;Ll;0;L; 03F5;;;;N;;;;; -1D717;MATHEMATICAL ITALIC THETA SYMBOL;Ll;0;L; 03D1;;;;N;;;;; -1D718;MATHEMATICAL ITALIC KAPPA SYMBOL;Ll;0;L; 03F0;;;;N;;;;; -1D719;MATHEMATICAL ITALIC PHI SYMBOL;Ll;0;L; 03D5;;;;N;;;;; -1D71A;MATHEMATICAL ITALIC RHO SYMBOL;Ll;0;L; 03F1;;;;N;;;;; -1D71B;MATHEMATICAL ITALIC PI SYMBOL;Ll;0;L; 03D6;;;;N;;;;; -1D71C;MATHEMATICAL BOLD ITALIC CAPITAL ALPHA;Lu;0;L; 0391;;;;N;;;;; -1D71D;MATHEMATICAL BOLD ITALIC CAPITAL BETA;Lu;0;L; 0392;;;;N;;;;; -1D71E;MATHEMATICAL BOLD ITALIC CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -1D71F;MATHEMATICAL BOLD ITALIC CAPITAL DELTA;Lu;0;L; 0394;;;;N;;;;; -1D720;MATHEMATICAL BOLD ITALIC CAPITAL EPSILON;Lu;0;L; 0395;;;;N;;;;; -1D721;MATHEMATICAL BOLD ITALIC CAPITAL ZETA;Lu;0;L; 0396;;;;N;;;;; -1D722;MATHEMATICAL BOLD ITALIC CAPITAL ETA;Lu;0;L; 0397;;;;N;;;;; -1D723;MATHEMATICAL BOLD ITALIC CAPITAL THETA;Lu;0;L; 0398;;;;N;;;;; -1D724;MATHEMATICAL BOLD ITALIC CAPITAL IOTA;Lu;0;L; 0399;;;;N;;;;; -1D725;MATHEMATICAL BOLD ITALIC CAPITAL KAPPA;Lu;0;L; 039A;;;;N;;;;; -1D726;MATHEMATICAL BOLD ITALIC CAPITAL LAMDA;Lu;0;L; 039B;;;;N;;;;; -1D727;MATHEMATICAL BOLD ITALIC CAPITAL MU;Lu;0;L; 039C;;;;N;;;;; -1D728;MATHEMATICAL BOLD ITALIC CAPITAL NU;Lu;0;L; 039D;;;;N;;;;; -1D729;MATHEMATICAL BOLD ITALIC CAPITAL XI;Lu;0;L; 039E;;;;N;;;;; -1D72A;MATHEMATICAL BOLD ITALIC CAPITAL OMICRON;Lu;0;L; 039F;;;;N;;;;; -1D72B;MATHEMATICAL BOLD ITALIC CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -1D72C;MATHEMATICAL BOLD ITALIC CAPITAL RHO;Lu;0;L; 03A1;;;;N;;;;; -1D72D;MATHEMATICAL BOLD ITALIC CAPITAL THETA SYMBOL;Lu;0;L; 03F4;;;;N;;;;; -1D72E;MATHEMATICAL BOLD ITALIC CAPITAL SIGMA;Lu;0;L; 03A3;;;;N;;;;; -1D72F;MATHEMATICAL BOLD ITALIC CAPITAL TAU;Lu;0;L; 03A4;;;;N;;;;; -1D730;MATHEMATICAL BOLD ITALIC CAPITAL UPSILON;Lu;0;L; 03A5;;;;N;;;;; -1D731;MATHEMATICAL BOLD ITALIC CAPITAL PHI;Lu;0;L; 03A6;;;;N;;;;; -1D732;MATHEMATICAL BOLD ITALIC CAPITAL CHI;Lu;0;L; 03A7;;;;N;;;;; -1D733;MATHEMATICAL BOLD ITALIC CAPITAL PSI;Lu;0;L; 03A8;;;;N;;;;; -1D734;MATHEMATICAL BOLD ITALIC CAPITAL OMEGA;Lu;0;L; 03A9;;;;N;;;;; -1D735;MATHEMATICAL BOLD ITALIC NABLA;Sm;0;L; 2207;;;;N;;;;; -1D736;MATHEMATICAL BOLD ITALIC SMALL ALPHA;Ll;0;L; 03B1;;;;N;;;;; -1D737;MATHEMATICAL BOLD ITALIC SMALL BETA;Ll;0;L; 03B2;;;;N;;;;; -1D738;MATHEMATICAL BOLD ITALIC SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D739;MATHEMATICAL BOLD ITALIC SMALL DELTA;Ll;0;L; 03B4;;;;N;;;;; -1D73A;MATHEMATICAL BOLD ITALIC SMALL EPSILON;Ll;0;L; 03B5;;;;N;;;;; -1D73B;MATHEMATICAL BOLD ITALIC SMALL ZETA;Ll;0;L; 03B6;;;;N;;;;; -1D73C;MATHEMATICAL BOLD ITALIC SMALL ETA;Ll;0;L; 03B7;;;;N;;;;; -1D73D;MATHEMATICAL BOLD ITALIC SMALL THETA;Ll;0;L; 03B8;;;;N;;;;; -1D73E;MATHEMATICAL BOLD ITALIC SMALL IOTA;Ll;0;L; 03B9;;;;N;;;;; -1D73F;MATHEMATICAL BOLD ITALIC SMALL KAPPA;Ll;0;L; 03BA;;;;N;;;;; -1D740;MATHEMATICAL BOLD ITALIC SMALL LAMDA;Ll;0;L; 03BB;;;;N;;;;; -1D741;MATHEMATICAL BOLD ITALIC SMALL MU;Ll;0;L; 03BC;;;;N;;;;; -1D742;MATHEMATICAL BOLD ITALIC SMALL NU;Ll;0;L; 03BD;;;;N;;;;; -1D743;MATHEMATICAL BOLD ITALIC SMALL XI;Ll;0;L; 03BE;;;;N;;;;; -1D744;MATHEMATICAL BOLD ITALIC SMALL OMICRON;Ll;0;L; 03BF;;;;N;;;;; -1D745;MATHEMATICAL BOLD ITALIC SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -1D746;MATHEMATICAL BOLD ITALIC SMALL RHO;Ll;0;L; 03C1;;;;N;;;;; -1D747;MATHEMATICAL BOLD ITALIC SMALL FINAL SIGMA;Ll;0;L; 03C2;;;;N;;;;; -1D748;MATHEMATICAL BOLD ITALIC SMALL SIGMA;Ll;0;L; 03C3;;;;N;;;;; -1D749;MATHEMATICAL BOLD ITALIC SMALL TAU;Ll;0;L; 03C4;;;;N;;;;; -1D74A;MATHEMATICAL BOLD ITALIC SMALL UPSILON;Ll;0;L; 03C5;;;;N;;;;; -1D74B;MATHEMATICAL BOLD ITALIC SMALL PHI;Ll;0;L; 03C6;;;;N;;;;; -1D74C;MATHEMATICAL BOLD ITALIC SMALL CHI;Ll;0;L; 03C7;;;;N;;;;; -1D74D;MATHEMATICAL BOLD ITALIC SMALL PSI;Ll;0;L; 03C8;;;;N;;;;; -1D74E;MATHEMATICAL BOLD ITALIC SMALL OMEGA;Ll;0;L; 03C9;;;;N;;;;; -1D74F;MATHEMATICAL BOLD ITALIC PARTIAL DIFFERENTIAL;Sm;0;L; 2202;;;;Y;;;;; -1D750;MATHEMATICAL BOLD ITALIC EPSILON SYMBOL;Ll;0;L; 03F5;;;;N;;;;; -1D751;MATHEMATICAL BOLD ITALIC THETA SYMBOL;Ll;0;L; 03D1;;;;N;;;;; -1D752;MATHEMATICAL BOLD ITALIC KAPPA SYMBOL;Ll;0;L; 03F0;;;;N;;;;; -1D753;MATHEMATICAL BOLD ITALIC PHI SYMBOL;Ll;0;L; 03D5;;;;N;;;;; -1D754;MATHEMATICAL BOLD ITALIC RHO SYMBOL;Ll;0;L; 03F1;;;;N;;;;; -1D755;MATHEMATICAL BOLD ITALIC PI SYMBOL;Ll;0;L; 03D6;;;;N;;;;; -1D756;MATHEMATICAL SANS-SERIF BOLD CAPITAL ALPHA;Lu;0;L; 0391;;;;N;;;;; -1D757;MATHEMATICAL SANS-SERIF BOLD CAPITAL BETA;Lu;0;L; 0392;;;;N;;;;; -1D758;MATHEMATICAL SANS-SERIF BOLD CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -1D759;MATHEMATICAL SANS-SERIF BOLD CAPITAL DELTA;Lu;0;L; 0394;;;;N;;;;; -1D75A;MATHEMATICAL SANS-SERIF BOLD CAPITAL EPSILON;Lu;0;L; 0395;;;;N;;;;; -1D75B;MATHEMATICAL SANS-SERIF BOLD CAPITAL ZETA;Lu;0;L; 0396;;;;N;;;;; -1D75C;MATHEMATICAL SANS-SERIF BOLD CAPITAL ETA;Lu;0;L; 0397;;;;N;;;;; -1D75D;MATHEMATICAL SANS-SERIF BOLD CAPITAL THETA;Lu;0;L; 0398;;;;N;;;;; -1D75E;MATHEMATICAL SANS-SERIF BOLD CAPITAL IOTA;Lu;0;L; 0399;;;;N;;;;; -1D75F;MATHEMATICAL SANS-SERIF BOLD CAPITAL KAPPA;Lu;0;L; 039A;;;;N;;;;; -1D760;MATHEMATICAL SANS-SERIF BOLD CAPITAL LAMDA;Lu;0;L; 039B;;;;N;;;;; -1D761;MATHEMATICAL SANS-SERIF BOLD CAPITAL MU;Lu;0;L; 039C;;;;N;;;;; -1D762;MATHEMATICAL SANS-SERIF BOLD CAPITAL NU;Lu;0;L; 039D;;;;N;;;;; -1D763;MATHEMATICAL SANS-SERIF BOLD CAPITAL XI;Lu;0;L; 039E;;;;N;;;;; -1D764;MATHEMATICAL SANS-SERIF BOLD CAPITAL OMICRON;Lu;0;L; 039F;;;;N;;;;; -1D765;MATHEMATICAL SANS-SERIF BOLD CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -1D766;MATHEMATICAL SANS-SERIF BOLD CAPITAL RHO;Lu;0;L; 03A1;;;;N;;;;; -1D767;MATHEMATICAL SANS-SERIF BOLD CAPITAL THETA SYMBOL;Lu;0;L; 03F4;;;;N;;;;; -1D768;MATHEMATICAL SANS-SERIF BOLD CAPITAL SIGMA;Lu;0;L; 03A3;;;;N;;;;; -1D769;MATHEMATICAL SANS-SERIF BOLD CAPITAL TAU;Lu;0;L; 03A4;;;;N;;;;; -1D76A;MATHEMATICAL SANS-SERIF BOLD CAPITAL UPSILON;Lu;0;L; 03A5;;;;N;;;;; -1D76B;MATHEMATICAL SANS-SERIF BOLD CAPITAL PHI;Lu;0;L; 03A6;;;;N;;;;; -1D76C;MATHEMATICAL SANS-SERIF BOLD CAPITAL CHI;Lu;0;L; 03A7;;;;N;;;;; -1D76D;MATHEMATICAL SANS-SERIF BOLD CAPITAL PSI;Lu;0;L; 03A8;;;;N;;;;; -1D76E;MATHEMATICAL SANS-SERIF BOLD CAPITAL OMEGA;Lu;0;L; 03A9;;;;N;;;;; -1D76F;MATHEMATICAL SANS-SERIF BOLD NABLA;Sm;0;L; 2207;;;;N;;;;; -1D770;MATHEMATICAL SANS-SERIF BOLD SMALL ALPHA;Ll;0;L; 03B1;;;;N;;;;; -1D771;MATHEMATICAL SANS-SERIF BOLD SMALL BETA;Ll;0;L; 03B2;;;;N;;;;; -1D772;MATHEMATICAL SANS-SERIF BOLD SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D773;MATHEMATICAL SANS-SERIF BOLD SMALL DELTA;Ll;0;L; 03B4;;;;N;;;;; -1D774;MATHEMATICAL SANS-SERIF BOLD SMALL EPSILON;Ll;0;L; 03B5;;;;N;;;;; -1D775;MATHEMATICAL SANS-SERIF BOLD SMALL ZETA;Ll;0;L; 03B6;;;;N;;;;; -1D776;MATHEMATICAL SANS-SERIF BOLD SMALL ETA;Ll;0;L; 03B7;;;;N;;;;; -1D777;MATHEMATICAL SANS-SERIF BOLD SMALL THETA;Ll;0;L; 03B8;;;;N;;;;; -1D778;MATHEMATICAL SANS-SERIF BOLD SMALL IOTA;Ll;0;L; 03B9;;;;N;;;;; -1D779;MATHEMATICAL SANS-SERIF BOLD SMALL KAPPA;Ll;0;L; 03BA;;;;N;;;;; -1D77A;MATHEMATICAL SANS-SERIF BOLD SMALL LAMDA;Ll;0;L; 03BB;;;;N;;;;; -1D77B;MATHEMATICAL SANS-SERIF BOLD SMALL MU;Ll;0;L; 03BC;;;;N;;;;; -1D77C;MATHEMATICAL SANS-SERIF BOLD SMALL NU;Ll;0;L; 03BD;;;;N;;;;; -1D77D;MATHEMATICAL SANS-SERIF BOLD SMALL XI;Ll;0;L; 03BE;;;;N;;;;; -1D77E;MATHEMATICAL SANS-SERIF BOLD SMALL OMICRON;Ll;0;L; 03BF;;;;N;;;;; -1D77F;MATHEMATICAL SANS-SERIF BOLD SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -1D780;MATHEMATICAL SANS-SERIF BOLD SMALL RHO;Ll;0;L; 03C1;;;;N;;;;; -1D781;MATHEMATICAL SANS-SERIF BOLD SMALL FINAL SIGMA;Ll;0;L; 03C2;;;;N;;;;; -1D782;MATHEMATICAL SANS-SERIF BOLD SMALL SIGMA;Ll;0;L; 03C3;;;;N;;;;; -1D783;MATHEMATICAL SANS-SERIF BOLD SMALL TAU;Ll;0;L; 03C4;;;;N;;;;; -1D784;MATHEMATICAL SANS-SERIF BOLD SMALL UPSILON;Ll;0;L; 03C5;;;;N;;;;; -1D785;MATHEMATICAL SANS-SERIF BOLD SMALL PHI;Ll;0;L; 03C6;;;;N;;;;; -1D786;MATHEMATICAL SANS-SERIF BOLD SMALL CHI;Ll;0;L; 03C7;;;;N;;;;; -1D787;MATHEMATICAL SANS-SERIF BOLD SMALL PSI;Ll;0;L; 03C8;;;;N;;;;; -1D788;MATHEMATICAL SANS-SERIF BOLD SMALL OMEGA;Ll;0;L; 03C9;;;;N;;;;; -1D789;MATHEMATICAL SANS-SERIF BOLD PARTIAL DIFFERENTIAL;Sm;0;L; 2202;;;;Y;;;;; -1D78A;MATHEMATICAL SANS-SERIF BOLD EPSILON SYMBOL;Ll;0;L; 03F5;;;;N;;;;; -1D78B;MATHEMATICAL SANS-SERIF BOLD THETA SYMBOL;Ll;0;L; 03D1;;;;N;;;;; -1D78C;MATHEMATICAL SANS-SERIF BOLD KAPPA SYMBOL;Ll;0;L; 03F0;;;;N;;;;; -1D78D;MATHEMATICAL SANS-SERIF BOLD PHI SYMBOL;Ll;0;L; 03D5;;;;N;;;;; -1D78E;MATHEMATICAL SANS-SERIF BOLD RHO SYMBOL;Ll;0;L; 03F1;;;;N;;;;; -1D78F;MATHEMATICAL SANS-SERIF BOLD PI SYMBOL;Ll;0;L; 03D6;;;;N;;;;; -1D790;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL ALPHA;Lu;0;L; 0391;;;;N;;;;; -1D791;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL BETA;Lu;0;L; 0392;;;;N;;;;; -1D792;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL GAMMA;Lu;0;L; 0393;;;;N;;;;; -1D793;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL DELTA;Lu;0;L; 0394;;;;N;;;;; -1D794;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL EPSILON;Lu;0;L; 0395;;;;N;;;;; -1D795;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL ZETA;Lu;0;L; 0396;;;;N;;;;; -1D796;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL ETA;Lu;0;L; 0397;;;;N;;;;; -1D797;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL THETA;Lu;0;L; 0398;;;;N;;;;; -1D798;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL IOTA;Lu;0;L; 0399;;;;N;;;;; -1D799;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL KAPPA;Lu;0;L; 039A;;;;N;;;;; -1D79A;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL LAMDA;Lu;0;L; 039B;;;;N;;;;; -1D79B;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL MU;Lu;0;L; 039C;;;;N;;;;; -1D79C;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL NU;Lu;0;L; 039D;;;;N;;;;; -1D79D;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL XI;Lu;0;L; 039E;;;;N;;;;; -1D79E;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL OMICRON;Lu;0;L; 039F;;;;N;;;;; -1D79F;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL PI;Lu;0;L; 03A0;;;;N;;;;; -1D7A0;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL RHO;Lu;0;L; 03A1;;;;N;;;;; -1D7A1;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL THETA SYMBOL;Lu;0;L; 03F4;;;;N;;;;; -1D7A2;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL SIGMA;Lu;0;L; 03A3;;;;N;;;;; -1D7A3;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL TAU;Lu;0;L; 03A4;;;;N;;;;; -1D7A4;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL UPSILON;Lu;0;L; 03A5;;;;N;;;;; -1D7A5;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL PHI;Lu;0;L; 03A6;;;;N;;;;; -1D7A6;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL CHI;Lu;0;L; 03A7;;;;N;;;;; -1D7A7;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL PSI;Lu;0;L; 03A8;;;;N;;;;; -1D7A8;MATHEMATICAL SANS-SERIF BOLD ITALIC CAPITAL OMEGA;Lu;0;L; 03A9;;;;N;;;;; -1D7A9;MATHEMATICAL SANS-SERIF BOLD ITALIC NABLA;Sm;0;L; 2207;;;;N;;;;; -1D7AA;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL ALPHA;Ll;0;L; 03B1;;;;N;;;;; -1D7AB;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL BETA;Ll;0;L; 03B2;;;;N;;;;; -1D7AC;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL GAMMA;Ll;0;L; 03B3;;;;N;;;;; -1D7AD;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL DELTA;Ll;0;L; 03B4;;;;N;;;;; -1D7AE;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL EPSILON;Ll;0;L; 03B5;;;;N;;;;; -1D7AF;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL ZETA;Ll;0;L; 03B6;;;;N;;;;; -1D7B0;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL ETA;Ll;0;L; 03B7;;;;N;;;;; -1D7B1;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL THETA;Ll;0;L; 03B8;;;;N;;;;; -1D7B2;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL IOTA;Ll;0;L; 03B9;;;;N;;;;; -1D7B3;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL KAPPA;Ll;0;L; 03BA;;;;N;;;;; -1D7B4;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL LAMDA;Ll;0;L; 03BB;;;;N;;;;; -1D7B5;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL MU;Ll;0;L; 03BC;;;;N;;;;; -1D7B6;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL NU;Ll;0;L; 03BD;;;;N;;;;; -1D7B7;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL XI;Ll;0;L; 03BE;;;;N;;;;; -1D7B8;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL OMICRON;Ll;0;L; 03BF;;;;N;;;;; -1D7B9;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL PI;Ll;0;L; 03C0;;;;N;;;;; -1D7BA;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL RHO;Ll;0;L; 03C1;;;;N;;;;; -1D7BB;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL FINAL SIGMA;Ll;0;L; 03C2;;;;N;;;;; -1D7BC;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL SIGMA;Ll;0;L; 03C3;;;;N;;;;; -1D7BD;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL TAU;Ll;0;L; 03C4;;;;N;;;;; -1D7BE;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL UPSILON;Ll;0;L; 03C5;;;;N;;;;; -1D7BF;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL PHI;Ll;0;L; 03C6;;;;N;;;;; -1D7C0;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL CHI;Ll;0;L; 03C7;;;;N;;;;; -1D7C1;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL PSI;Ll;0;L; 03C8;;;;N;;;;; -1D7C2;MATHEMATICAL SANS-SERIF BOLD ITALIC SMALL OMEGA;Ll;0;L; 03C9;;;;N;;;;; -1D7C3;MATHEMATICAL SANS-SERIF BOLD ITALIC PARTIAL DIFFERENTIAL;Sm;0;L; 2202;;;;Y;;;;; -1D7C4;MATHEMATICAL SANS-SERIF BOLD ITALIC EPSILON SYMBOL;Ll;0;L; 03F5;;;;N;;;;; -1D7C5;MATHEMATICAL SANS-SERIF BOLD ITALIC THETA SYMBOL;Ll;0;L; 03D1;;;;N;;;;; -1D7C6;MATHEMATICAL SANS-SERIF BOLD ITALIC KAPPA SYMBOL;Ll;0;L; 03F0;;;;N;;;;; -1D7C7;MATHEMATICAL SANS-SERIF BOLD ITALIC PHI SYMBOL;Ll;0;L; 03D5;;;;N;;;;; -1D7C8;MATHEMATICAL SANS-SERIF BOLD ITALIC RHO SYMBOL;Ll;0;L; 03F1;;;;N;;;;; -1D7C9;MATHEMATICAL SANS-SERIF BOLD ITALIC PI SYMBOL;Ll;0;L; 03D6;;;;N;;;;; -1D7CA;MATHEMATICAL BOLD CAPITAL DIGAMMA;Lu;0;L; 03DC;;;;N;;;;; -1D7CB;MATHEMATICAL BOLD SMALL DIGAMMA;Ll;0;L; 03DD;;;;N;;;;; -1D7CE;MATHEMATICAL BOLD DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -1D7CF;MATHEMATICAL BOLD DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -1D7D0;MATHEMATICAL BOLD DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -1D7D1;MATHEMATICAL BOLD DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -1D7D2;MATHEMATICAL BOLD DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -1D7D3;MATHEMATICAL BOLD DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -1D7D4;MATHEMATICAL BOLD DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -1D7D5;MATHEMATICAL BOLD DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -1D7D6;MATHEMATICAL BOLD DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -1D7D7;MATHEMATICAL BOLD DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -1D7D8;MATHEMATICAL DOUBLE-STRUCK DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -1D7D9;MATHEMATICAL DOUBLE-STRUCK DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -1D7DA;MATHEMATICAL DOUBLE-STRUCK DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -1D7DB;MATHEMATICAL DOUBLE-STRUCK DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -1D7DC;MATHEMATICAL DOUBLE-STRUCK DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -1D7DD;MATHEMATICAL DOUBLE-STRUCK DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -1D7DE;MATHEMATICAL DOUBLE-STRUCK DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -1D7DF;MATHEMATICAL DOUBLE-STRUCK DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -1D7E0;MATHEMATICAL DOUBLE-STRUCK DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -1D7E1;MATHEMATICAL DOUBLE-STRUCK DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -1D7E2;MATHEMATICAL SANS-SERIF DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -1D7E3;MATHEMATICAL SANS-SERIF DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -1D7E4;MATHEMATICAL SANS-SERIF DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -1D7E5;MATHEMATICAL SANS-SERIF DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -1D7E6;MATHEMATICAL SANS-SERIF DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -1D7E7;MATHEMATICAL SANS-SERIF DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -1D7E8;MATHEMATICAL SANS-SERIF DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -1D7E9;MATHEMATICAL SANS-SERIF DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -1D7EA;MATHEMATICAL SANS-SERIF DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -1D7EB;MATHEMATICAL SANS-SERIF DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -1D7EC;MATHEMATICAL SANS-SERIF BOLD DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -1D7ED;MATHEMATICAL SANS-SERIF BOLD DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -1D7EE;MATHEMATICAL SANS-SERIF BOLD DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -1D7EF;MATHEMATICAL SANS-SERIF BOLD DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -1D7F0;MATHEMATICAL SANS-SERIF BOLD DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -1D7F1;MATHEMATICAL SANS-SERIF BOLD DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -1D7F2;MATHEMATICAL SANS-SERIF BOLD DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -1D7F3;MATHEMATICAL SANS-SERIF BOLD DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -1D7F4;MATHEMATICAL SANS-SERIF BOLD DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -1D7F5;MATHEMATICAL SANS-SERIF BOLD DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -1D7F6;MATHEMATICAL MONOSPACE DIGIT ZERO;Nd;0;EN; 0030;0;0;0;N;;;;; -1D7F7;MATHEMATICAL MONOSPACE DIGIT ONE;Nd;0;EN; 0031;1;1;1;N;;;;; -1D7F8;MATHEMATICAL MONOSPACE DIGIT TWO;Nd;0;EN; 0032;2;2;2;N;;;;; -1D7F9;MATHEMATICAL MONOSPACE DIGIT THREE;Nd;0;EN; 0033;3;3;3;N;;;;; -1D7FA;MATHEMATICAL MONOSPACE DIGIT FOUR;Nd;0;EN; 0034;4;4;4;N;;;;; -1D7FB;MATHEMATICAL MONOSPACE DIGIT FIVE;Nd;0;EN; 0035;5;5;5;N;;;;; -1D7FC;MATHEMATICAL MONOSPACE DIGIT SIX;Nd;0;EN; 0036;6;6;6;N;;;;; -1D7FD;MATHEMATICAL MONOSPACE DIGIT SEVEN;Nd;0;EN; 0037;7;7;7;N;;;;; -1D7FE;MATHEMATICAL MONOSPACE DIGIT EIGHT;Nd;0;EN; 0038;8;8;8;N;;;;; -1D7FF;MATHEMATICAL MONOSPACE DIGIT NINE;Nd;0;EN; 0039;9;9;9;N;;;;; -1F000;MAHJONG TILE EAST WIND;So;0;ON;;;;;N;;;;; -1F001;MAHJONG TILE SOUTH WIND;So;0;ON;;;;;N;;;;; -1F002;MAHJONG TILE WEST WIND;So;0;ON;;;;;N;;;;; -1F003;MAHJONG TILE NORTH WIND;So;0;ON;;;;;N;;;;; -1F004;MAHJONG TILE RED DRAGON;So;0;ON;;;;;N;;;;; -1F005;MAHJONG TILE GREEN DRAGON;So;0;ON;;;;;N;;;;; -1F006;MAHJONG TILE WHITE DRAGON;So;0;ON;;;;;N;;;;; -1F007;MAHJONG TILE ONE OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F008;MAHJONG TILE TWO OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F009;MAHJONG TILE THREE OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00A;MAHJONG TILE FOUR OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00B;MAHJONG TILE FIVE OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00C;MAHJONG TILE SIX OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00D;MAHJONG TILE SEVEN OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00E;MAHJONG TILE EIGHT OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F00F;MAHJONG TILE NINE OF CHARACTERS;So;0;ON;;;;;N;;;;; -1F010;MAHJONG TILE ONE OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F011;MAHJONG TILE TWO OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F012;MAHJONG TILE THREE OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F013;MAHJONG TILE FOUR OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F014;MAHJONG TILE FIVE OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F015;MAHJONG TILE SIX OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F016;MAHJONG TILE SEVEN OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F017;MAHJONG TILE EIGHT OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F018;MAHJONG TILE NINE OF BAMBOOS;So;0;ON;;;;;N;;;;; -1F019;MAHJONG TILE ONE OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01A;MAHJONG TILE TWO OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01B;MAHJONG TILE THREE OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01C;MAHJONG TILE FOUR OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01D;MAHJONG TILE FIVE OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01E;MAHJONG TILE SIX OF CIRCLES;So;0;ON;;;;;N;;;;; -1F01F;MAHJONG TILE SEVEN OF CIRCLES;So;0;ON;;;;;N;;;;; -1F020;MAHJONG TILE EIGHT OF CIRCLES;So;0;ON;;;;;N;;;;; -1F021;MAHJONG TILE NINE OF CIRCLES;So;0;ON;;;;;N;;;;; -1F022;MAHJONG TILE PLUM;So;0;ON;;;;;N;;;;; -1F023;MAHJONG TILE ORCHID;So;0;ON;;;;;N;;;;; -1F024;MAHJONG TILE BAMBOO;So;0;ON;;;;;N;;;;; -1F025;MAHJONG TILE CHRYSANTHEMUM;So;0;ON;;;;;N;;;;; -1F026;MAHJONG TILE SPRING;So;0;ON;;;;;N;;;;; -1F027;MAHJONG TILE SUMMER;So;0;ON;;;;;N;;;;; -1F028;MAHJONG TILE AUTUMN;So;0;ON;;;;;N;;;;; -1F029;MAHJONG TILE WINTER;So;0;ON;;;;;N;;;;; -1F02A;MAHJONG TILE JOKER;So;0;ON;;;;;N;;;;; -1F02B;MAHJONG TILE BACK;So;0;ON;;;;;N;;;;; -1F030;DOMINO TILE HORIZONTAL BACK;So;0;ON;;;;;N;;;;; -1F031;DOMINO TILE HORIZONTAL-00-00;So;0;ON;;;;;N;;;;; -1F032;DOMINO TILE HORIZONTAL-00-01;So;0;ON;;;;;N;;;;; -1F033;DOMINO TILE HORIZONTAL-00-02;So;0;ON;;;;;N;;;;; -1F034;DOMINO TILE HORIZONTAL-00-03;So;0;ON;;;;;N;;;;; -1F035;DOMINO TILE HORIZONTAL-00-04;So;0;ON;;;;;N;;;;; -1F036;DOMINO TILE HORIZONTAL-00-05;So;0;ON;;;;;N;;;;; -1F037;DOMINO TILE HORIZONTAL-00-06;So;0;ON;;;;;N;;;;; -1F038;DOMINO TILE HORIZONTAL-01-00;So;0;ON;;;;;N;;;;; -1F039;DOMINO TILE HORIZONTAL-01-01;So;0;ON;;;;;N;;;;; -1F03A;DOMINO TILE HORIZONTAL-01-02;So;0;ON;;;;;N;;;;; -1F03B;DOMINO TILE HORIZONTAL-01-03;So;0;ON;;;;;N;;;;; -1F03C;DOMINO TILE HORIZONTAL-01-04;So;0;ON;;;;;N;;;;; -1F03D;DOMINO TILE HORIZONTAL-01-05;So;0;ON;;;;;N;;;;; -1F03E;DOMINO TILE HORIZONTAL-01-06;So;0;ON;;;;;N;;;;; -1F03F;DOMINO TILE HORIZONTAL-02-00;So;0;ON;;;;;N;;;;; -1F040;DOMINO TILE HORIZONTAL-02-01;So;0;ON;;;;;N;;;;; -1F041;DOMINO TILE HORIZONTAL-02-02;So;0;ON;;;;;N;;;;; -1F042;DOMINO TILE HORIZONTAL-02-03;So;0;ON;;;;;N;;;;; -1F043;DOMINO TILE HORIZONTAL-02-04;So;0;ON;;;;;N;;;;; -1F044;DOMINO TILE HORIZONTAL-02-05;So;0;ON;;;;;N;;;;; -1F045;DOMINO TILE HORIZONTAL-02-06;So;0;ON;;;;;N;;;;; -1F046;DOMINO TILE HORIZONTAL-03-00;So;0;ON;;;;;N;;;;; -1F047;DOMINO TILE HORIZONTAL-03-01;So;0;ON;;;;;N;;;;; -1F048;DOMINO TILE HORIZONTAL-03-02;So;0;ON;;;;;N;;;;; -1F049;DOMINO TILE HORIZONTAL-03-03;So;0;ON;;;;;N;;;;; -1F04A;DOMINO TILE HORIZONTAL-03-04;So;0;ON;;;;;N;;;;; -1F04B;DOMINO TILE HORIZONTAL-03-05;So;0;ON;;;;;N;;;;; -1F04C;DOMINO TILE HORIZONTAL-03-06;So;0;ON;;;;;N;;;;; -1F04D;DOMINO TILE HORIZONTAL-04-00;So;0;ON;;;;;N;;;;; -1F04E;DOMINO TILE HORIZONTAL-04-01;So;0;ON;;;;;N;;;;; -1F04F;DOMINO TILE HORIZONTAL-04-02;So;0;ON;;;;;N;;;;; -1F050;DOMINO TILE HORIZONTAL-04-03;So;0;ON;;;;;N;;;;; -1F051;DOMINO TILE HORIZONTAL-04-04;So;0;ON;;;;;N;;;;; -1F052;DOMINO TILE HORIZONTAL-04-05;So;0;ON;;;;;N;;;;; -1F053;DOMINO TILE HORIZONTAL-04-06;So;0;ON;;;;;N;;;;; -1F054;DOMINO TILE HORIZONTAL-05-00;So;0;ON;;;;;N;;;;; -1F055;DOMINO TILE HORIZONTAL-05-01;So;0;ON;;;;;N;;;;; -1F056;DOMINO TILE HORIZONTAL-05-02;So;0;ON;;;;;N;;;;; -1F057;DOMINO TILE HORIZONTAL-05-03;So;0;ON;;;;;N;;;;; -1F058;DOMINO TILE HORIZONTAL-05-04;So;0;ON;;;;;N;;;;; -1F059;DOMINO TILE HORIZONTAL-05-05;So;0;ON;;;;;N;;;;; -1F05A;DOMINO TILE HORIZONTAL-05-06;So;0;ON;;;;;N;;;;; -1F05B;DOMINO TILE HORIZONTAL-06-00;So;0;ON;;;;;N;;;;; -1F05C;DOMINO TILE HORIZONTAL-06-01;So;0;ON;;;;;N;;;;; -1F05D;DOMINO TILE HORIZONTAL-06-02;So;0;ON;;;;;N;;;;; -1F05E;DOMINO TILE HORIZONTAL-06-03;So;0;ON;;;;;N;;;;; -1F05F;DOMINO TILE HORIZONTAL-06-04;So;0;ON;;;;;N;;;;; -1F060;DOMINO TILE HORIZONTAL-06-05;So;0;ON;;;;;N;;;;; -1F061;DOMINO TILE HORIZONTAL-06-06;So;0;ON;;;;;N;;;;; -1F062;DOMINO TILE VERTICAL BACK;So;0;ON;;;;;N;;;;; -1F063;DOMINO TILE VERTICAL-00-00;So;0;ON;;;;;N;;;;; -1F064;DOMINO TILE VERTICAL-00-01;So;0;ON;;;;;N;;;;; -1F065;DOMINO TILE VERTICAL-00-02;So;0;ON;;;;;N;;;;; -1F066;DOMINO TILE VERTICAL-00-03;So;0;ON;;;;;N;;;;; -1F067;DOMINO TILE VERTICAL-00-04;So;0;ON;;;;;N;;;;; -1F068;DOMINO TILE VERTICAL-00-05;So;0;ON;;;;;N;;;;; -1F069;DOMINO TILE VERTICAL-00-06;So;0;ON;;;;;N;;;;; -1F06A;DOMINO TILE VERTICAL-01-00;So;0;ON;;;;;N;;;;; -1F06B;DOMINO TILE VERTICAL-01-01;So;0;ON;;;;;N;;;;; -1F06C;DOMINO TILE VERTICAL-01-02;So;0;ON;;;;;N;;;;; -1F06D;DOMINO TILE VERTICAL-01-03;So;0;ON;;;;;N;;;;; -1F06E;DOMINO TILE VERTICAL-01-04;So;0;ON;;;;;N;;;;; -1F06F;DOMINO TILE VERTICAL-01-05;So;0;ON;;;;;N;;;;; -1F070;DOMINO TILE VERTICAL-01-06;So;0;ON;;;;;N;;;;; -1F071;DOMINO TILE VERTICAL-02-00;So;0;ON;;;;;N;;;;; -1F072;DOMINO TILE VERTICAL-02-01;So;0;ON;;;;;N;;;;; -1F073;DOMINO TILE VERTICAL-02-02;So;0;ON;;;;;N;;;;; -1F074;DOMINO TILE VERTICAL-02-03;So;0;ON;;;;;N;;;;; -1F075;DOMINO TILE VERTICAL-02-04;So;0;ON;;;;;N;;;;; -1F076;DOMINO TILE VERTICAL-02-05;So;0;ON;;;;;N;;;;; -1F077;DOMINO TILE VERTICAL-02-06;So;0;ON;;;;;N;;;;; -1F078;DOMINO TILE VERTICAL-03-00;So;0;ON;;;;;N;;;;; -1F079;DOMINO TILE VERTICAL-03-01;So;0;ON;;;;;N;;;;; -1F07A;DOMINO TILE VERTICAL-03-02;So;0;ON;;;;;N;;;;; -1F07B;DOMINO TILE VERTICAL-03-03;So;0;ON;;;;;N;;;;; -1F07C;DOMINO TILE VERTICAL-03-04;So;0;ON;;;;;N;;;;; -1F07D;DOMINO TILE VERTICAL-03-05;So;0;ON;;;;;N;;;;; -1F07E;DOMINO TILE VERTICAL-03-06;So;0;ON;;;;;N;;;;; -1F07F;DOMINO TILE VERTICAL-04-00;So;0;ON;;;;;N;;;;; -1F080;DOMINO TILE VERTICAL-04-01;So;0;ON;;;;;N;;;;; -1F081;DOMINO TILE VERTICAL-04-02;So;0;ON;;;;;N;;;;; -1F082;DOMINO TILE VERTICAL-04-03;So;0;ON;;;;;N;;;;; -1F083;DOMINO TILE VERTICAL-04-04;So;0;ON;;;;;N;;;;; -1F084;DOMINO TILE VERTICAL-04-05;So;0;ON;;;;;N;;;;; -1F085;DOMINO TILE VERTICAL-04-06;So;0;ON;;;;;N;;;;; -1F086;DOMINO TILE VERTICAL-05-00;So;0;ON;;;;;N;;;;; -1F087;DOMINO TILE VERTICAL-05-01;So;0;ON;;;;;N;;;;; -1F088;DOMINO TILE VERTICAL-05-02;So;0;ON;;;;;N;;;;; -1F089;DOMINO TILE VERTICAL-05-03;So;0;ON;;;;;N;;;;; -1F08A;DOMINO TILE VERTICAL-05-04;So;0;ON;;;;;N;;;;; -1F08B;DOMINO TILE VERTICAL-05-05;So;0;ON;;;;;N;;;;; -1F08C;DOMINO TILE VERTICAL-05-06;So;0;ON;;;;;N;;;;; -1F08D;DOMINO TILE VERTICAL-06-00;So;0;ON;;;;;N;;;;; -1F08E;DOMINO TILE VERTICAL-06-01;So;0;ON;;;;;N;;;;; -1F08F;DOMINO TILE VERTICAL-06-02;So;0;ON;;;;;N;;;;; -1F090;DOMINO TILE VERTICAL-06-03;So;0;ON;;;;;N;;;;; -1F091;DOMINO TILE VERTICAL-06-04;So;0;ON;;;;;N;;;;; -1F092;DOMINO TILE VERTICAL-06-05;So;0;ON;;;;;N;;;;; -1F093;DOMINO TILE VERTICAL-06-06;So;0;ON;;;;;N;;;;; -20000;;Lo;0;L;;;;;N;;;;; -2A6D6;;Lo;0;L;;;;;N;;;;; -2F800;CJK COMPATIBILITY IDEOGRAPH-2F800;Lo;0;L;4E3D;;;;N;;;;; -2F801;CJK COMPATIBILITY IDEOGRAPH-2F801;Lo;0;L;4E38;;;;N;;;;; -2F802;CJK COMPATIBILITY IDEOGRAPH-2F802;Lo;0;L;4E41;;;;N;;;;; -2F803;CJK COMPATIBILITY IDEOGRAPH-2F803;Lo;0;L;20122;;;;N;;;;; -2F804;CJK COMPATIBILITY IDEOGRAPH-2F804;Lo;0;L;4F60;;;;N;;;;; -2F805;CJK COMPATIBILITY IDEOGRAPH-2F805;Lo;0;L;4FAE;;;;N;;;;; -2F806;CJK COMPATIBILITY IDEOGRAPH-2F806;Lo;0;L;4FBB;;;;N;;;;; -2F807;CJK COMPATIBILITY IDEOGRAPH-2F807;Lo;0;L;5002;;;;N;;;;; -2F808;CJK COMPATIBILITY IDEOGRAPH-2F808;Lo;0;L;507A;;;;N;;;;; -2F809;CJK COMPATIBILITY IDEOGRAPH-2F809;Lo;0;L;5099;;;;N;;;;; -2F80A;CJK COMPATIBILITY IDEOGRAPH-2F80A;Lo;0;L;50E7;;;;N;;;;; -2F80B;CJK COMPATIBILITY IDEOGRAPH-2F80B;Lo;0;L;50CF;;;;N;;;;; -2F80C;CJK COMPATIBILITY IDEOGRAPH-2F80C;Lo;0;L;349E;;;;N;;;;; -2F80D;CJK COMPATIBILITY IDEOGRAPH-2F80D;Lo;0;L;2063A;;;;N;;;;; -2F80E;CJK COMPATIBILITY IDEOGRAPH-2F80E;Lo;0;L;514D;;;;N;;;;; -2F80F;CJK COMPATIBILITY IDEOGRAPH-2F80F;Lo;0;L;5154;;;;N;;;;; -2F810;CJK COMPATIBILITY IDEOGRAPH-2F810;Lo;0;L;5164;;;;N;;;;; -2F811;CJK COMPATIBILITY IDEOGRAPH-2F811;Lo;0;L;5177;;;;N;;;;; -2F812;CJK COMPATIBILITY IDEOGRAPH-2F812;Lo;0;L;2051C;;;;N;;;;; -2F813;CJK COMPATIBILITY IDEOGRAPH-2F813;Lo;0;L;34B9;;;;N;;;;; -2F814;CJK COMPATIBILITY IDEOGRAPH-2F814;Lo;0;L;5167;;;;N;;;;; -2F815;CJK COMPATIBILITY IDEOGRAPH-2F815;Lo;0;L;518D;;;;N;;;;; -2F816;CJK COMPATIBILITY IDEOGRAPH-2F816;Lo;0;L;2054B;;;;N;;;;; -2F817;CJK COMPATIBILITY IDEOGRAPH-2F817;Lo;0;L;5197;;;;N;;;;; -2F818;CJK COMPATIBILITY IDEOGRAPH-2F818;Lo;0;L;51A4;;;;N;;;;; -2F819;CJK COMPATIBILITY IDEOGRAPH-2F819;Lo;0;L;4ECC;;;;N;;;;; -2F81A;CJK COMPATIBILITY IDEOGRAPH-2F81A;Lo;0;L;51AC;;;;N;;;;; -2F81B;CJK COMPATIBILITY IDEOGRAPH-2F81B;Lo;0;L;51B5;;;;N;;;;; -2F81C;CJK COMPATIBILITY IDEOGRAPH-2F81C;Lo;0;L;291DF;;;;N;;;;; -2F81D;CJK COMPATIBILITY IDEOGRAPH-2F81D;Lo;0;L;51F5;;;;N;;;;; -2F81E;CJK COMPATIBILITY IDEOGRAPH-2F81E;Lo;0;L;5203;;;;N;;;;; -2F81F;CJK COMPATIBILITY IDEOGRAPH-2F81F;Lo;0;L;34DF;;;;N;;;;; -2F820;CJK COMPATIBILITY IDEOGRAPH-2F820;Lo;0;L;523B;;;;N;;;;; -2F821;CJK COMPATIBILITY IDEOGRAPH-2F821;Lo;0;L;5246;;;;N;;;;; -2F822;CJK COMPATIBILITY IDEOGRAPH-2F822;Lo;0;L;5272;;;;N;;;;; -2F823;CJK COMPATIBILITY IDEOGRAPH-2F823;Lo;0;L;5277;;;;N;;;;; -2F824;CJK COMPATIBILITY IDEOGRAPH-2F824;Lo;0;L;3515;;;;N;;;;; -2F825;CJK COMPATIBILITY IDEOGRAPH-2F825;Lo;0;L;52C7;;;;N;;;;; -2F826;CJK COMPATIBILITY IDEOGRAPH-2F826;Lo;0;L;52C9;;;;N;;;;; -2F827;CJK COMPATIBILITY IDEOGRAPH-2F827;Lo;0;L;52E4;;;;N;;;;; -2F828;CJK COMPATIBILITY IDEOGRAPH-2F828;Lo;0;L;52FA;;;;N;;;;; -2F829;CJK COMPATIBILITY IDEOGRAPH-2F829;Lo;0;L;5305;;;;N;;;;; -2F82A;CJK COMPATIBILITY IDEOGRAPH-2F82A;Lo;0;L;5306;;;;N;;;;; -2F82B;CJK COMPATIBILITY IDEOGRAPH-2F82B;Lo;0;L;5317;;;;N;;;;; -2F82C;CJK COMPATIBILITY IDEOGRAPH-2F82C;Lo;0;L;5349;;;;N;;;;; -2F82D;CJK COMPATIBILITY IDEOGRAPH-2F82D;Lo;0;L;5351;;;;N;;;;; -2F82E;CJK COMPATIBILITY IDEOGRAPH-2F82E;Lo;0;L;535A;;;;N;;;;; -2F82F;CJK COMPATIBILITY IDEOGRAPH-2F82F;Lo;0;L;5373;;;;N;;;;; -2F830;CJK COMPATIBILITY IDEOGRAPH-2F830;Lo;0;L;537D;;;;N;;;;; -2F831;CJK COMPATIBILITY IDEOGRAPH-2F831;Lo;0;L;537F;;;;N;;;;; -2F832;CJK COMPATIBILITY IDEOGRAPH-2F832;Lo;0;L;537F;;;;N;;;;; -2F833;CJK COMPATIBILITY IDEOGRAPH-2F833;Lo;0;L;537F;;;;N;;;;; -2F834;CJK COMPATIBILITY IDEOGRAPH-2F834;Lo;0;L;20A2C;;;;N;;;;; -2F835;CJK COMPATIBILITY IDEOGRAPH-2F835;Lo;0;L;7070;;;;N;;;;; -2F836;CJK COMPATIBILITY IDEOGRAPH-2F836;Lo;0;L;53CA;;;;N;;;;; -2F837;CJK COMPATIBILITY IDEOGRAPH-2F837;Lo;0;L;53DF;;;;N;;;;; -2F838;CJK COMPATIBILITY IDEOGRAPH-2F838;Lo;0;L;20B63;;;;N;;;;; -2F839;CJK COMPATIBILITY IDEOGRAPH-2F839;Lo;0;L;53EB;;;;N;;;;; -2F83A;CJK COMPATIBILITY IDEOGRAPH-2F83A;Lo;0;L;53F1;;;;N;;;;; -2F83B;CJK COMPATIBILITY IDEOGRAPH-2F83B;Lo;0;L;5406;;;;N;;;;; -2F83C;CJK COMPATIBILITY IDEOGRAPH-2F83C;Lo;0;L;549E;;;;N;;;;; -2F83D;CJK COMPATIBILITY IDEOGRAPH-2F83D;Lo;0;L;5438;;;;N;;;;; -2F83E;CJK COMPATIBILITY IDEOGRAPH-2F83E;Lo;0;L;5448;;;;N;;;;; -2F83F;CJK COMPATIBILITY IDEOGRAPH-2F83F;Lo;0;L;5468;;;;N;;;;; -2F840;CJK COMPATIBILITY IDEOGRAPH-2F840;Lo;0;L;54A2;;;;N;;;;; -2F841;CJK COMPATIBILITY IDEOGRAPH-2F841;Lo;0;L;54F6;;;;N;;;;; -2F842;CJK COMPATIBILITY IDEOGRAPH-2F842;Lo;0;L;5510;;;;N;;;;; -2F843;CJK COMPATIBILITY IDEOGRAPH-2F843;Lo;0;L;5553;;;;N;;;;; -2F844;CJK COMPATIBILITY IDEOGRAPH-2F844;Lo;0;L;5563;;;;N;;;;; -2F845;CJK COMPATIBILITY IDEOGRAPH-2F845;Lo;0;L;5584;;;;N;;;;; -2F846;CJK COMPATIBILITY IDEOGRAPH-2F846;Lo;0;L;5584;;;;N;;;;; -2F847;CJK COMPATIBILITY IDEOGRAPH-2F847;Lo;0;L;5599;;;;N;;;;; -2F848;CJK COMPATIBILITY IDEOGRAPH-2F848;Lo;0;L;55AB;;;;N;;;;; -2F849;CJK COMPATIBILITY IDEOGRAPH-2F849;Lo;0;L;55B3;;;;N;;;;; -2F84A;CJK COMPATIBILITY IDEOGRAPH-2F84A;Lo;0;L;55C2;;;;N;;;;; -2F84B;CJK COMPATIBILITY IDEOGRAPH-2F84B;Lo;0;L;5716;;;;N;;;;; -2F84C;CJK COMPATIBILITY IDEOGRAPH-2F84C;Lo;0;L;5606;;;;N;;;;; -2F84D;CJK COMPATIBILITY IDEOGRAPH-2F84D;Lo;0;L;5717;;;;N;;;;; -2F84E;CJK COMPATIBILITY IDEOGRAPH-2F84E;Lo;0;L;5651;;;;N;;;;; -2F84F;CJK COMPATIBILITY IDEOGRAPH-2F84F;Lo;0;L;5674;;;;N;;;;; -2F850;CJK COMPATIBILITY IDEOGRAPH-2F850;Lo;0;L;5207;;;;N;;;;; -2F851;CJK COMPATIBILITY IDEOGRAPH-2F851;Lo;0;L;58EE;;;;N;;;;; -2F852;CJK COMPATIBILITY IDEOGRAPH-2F852;Lo;0;L;57CE;;;;N;;;;; -2F853;CJK COMPATIBILITY IDEOGRAPH-2F853;Lo;0;L;57F4;;;;N;;;;; -2F854;CJK COMPATIBILITY IDEOGRAPH-2F854;Lo;0;L;580D;;;;N;;;;; -2F855;CJK COMPATIBILITY IDEOGRAPH-2F855;Lo;0;L;578B;;;;N;;;;; -2F856;CJK COMPATIBILITY IDEOGRAPH-2F856;Lo;0;L;5832;;;;N;;;;; -2F857;CJK COMPATIBILITY IDEOGRAPH-2F857;Lo;0;L;5831;;;;N;;;;; -2F858;CJK COMPATIBILITY IDEOGRAPH-2F858;Lo;0;L;58AC;;;;N;;;;; -2F859;CJK COMPATIBILITY IDEOGRAPH-2F859;Lo;0;L;214E4;;;;N;;;;; -2F85A;CJK COMPATIBILITY IDEOGRAPH-2F85A;Lo;0;L;58F2;;;;N;;;;; -2F85B;CJK COMPATIBILITY IDEOGRAPH-2F85B;Lo;0;L;58F7;;;;N;;;;; -2F85C;CJK COMPATIBILITY IDEOGRAPH-2F85C;Lo;0;L;5906;;;;N;;;;; -2F85D;CJK COMPATIBILITY IDEOGRAPH-2F85D;Lo;0;L;591A;;;;N;;;;; -2F85E;CJK COMPATIBILITY IDEOGRAPH-2F85E;Lo;0;L;5922;;;;N;;;;; -2F85F;CJK COMPATIBILITY IDEOGRAPH-2F85F;Lo;0;L;5962;;;;N;;;;; -2F860;CJK COMPATIBILITY IDEOGRAPH-2F860;Lo;0;L;216A8;;;;N;;;;; -2F861;CJK COMPATIBILITY IDEOGRAPH-2F861;Lo;0;L;216EA;;;;N;;;;; -2F862;CJK COMPATIBILITY IDEOGRAPH-2F862;Lo;0;L;59EC;;;;N;;;;; -2F863;CJK COMPATIBILITY IDEOGRAPH-2F863;Lo;0;L;5A1B;;;;N;;;;; -2F864;CJK COMPATIBILITY IDEOGRAPH-2F864;Lo;0;L;5A27;;;;N;;;;; -2F865;CJK COMPATIBILITY IDEOGRAPH-2F865;Lo;0;L;59D8;;;;N;;;;; -2F866;CJK COMPATIBILITY IDEOGRAPH-2F866;Lo;0;L;5A66;;;;N;;;;; -2F867;CJK COMPATIBILITY IDEOGRAPH-2F867;Lo;0;L;36EE;;;;N;;;;; -2F868;CJK COMPATIBILITY IDEOGRAPH-2F868;Lo;0;L;36FC;;;;N;;;;; -2F869;CJK COMPATIBILITY IDEOGRAPH-2F869;Lo;0;L;5B08;;;;N;;;;; -2F86A;CJK COMPATIBILITY IDEOGRAPH-2F86A;Lo;0;L;5B3E;;;;N;;;;; -2F86B;CJK COMPATIBILITY IDEOGRAPH-2F86B;Lo;0;L;5B3E;;;;N;;;;; -2F86C;CJK COMPATIBILITY IDEOGRAPH-2F86C;Lo;0;L;219C8;;;;N;;;;; -2F86D;CJK COMPATIBILITY IDEOGRAPH-2F86D;Lo;0;L;5BC3;;;;N;;;;; -2F86E;CJK COMPATIBILITY IDEOGRAPH-2F86E;Lo;0;L;5BD8;;;;N;;;;; -2F86F;CJK COMPATIBILITY IDEOGRAPH-2F86F;Lo;0;L;5BE7;;;;N;;;;; -2F870;CJK COMPATIBILITY IDEOGRAPH-2F870;Lo;0;L;5BF3;;;;N;;;;; -2F871;CJK COMPATIBILITY IDEOGRAPH-2F871;Lo;0;L;21B18;;;;N;;;;; -2F872;CJK COMPATIBILITY IDEOGRAPH-2F872;Lo;0;L;5BFF;;;;N;;;;; -2F873;CJK COMPATIBILITY IDEOGRAPH-2F873;Lo;0;L;5C06;;;;N;;;;; -2F874;CJK COMPATIBILITY IDEOGRAPH-2F874;Lo;0;L;5F53;;;;N;;;;; -2F875;CJK COMPATIBILITY IDEOGRAPH-2F875;Lo;0;L;5C22;;;;N;;;;; -2F876;CJK COMPATIBILITY IDEOGRAPH-2F876;Lo;0;L;3781;;;;N;;;;; -2F877;CJK COMPATIBILITY IDEOGRAPH-2F877;Lo;0;L;5C60;;;;N;;;;; -2F878;CJK COMPATIBILITY IDEOGRAPH-2F878;Lo;0;L;5C6E;;;;N;;;;; -2F879;CJK COMPATIBILITY IDEOGRAPH-2F879;Lo;0;L;5CC0;;;;N;;;;; -2F87A;CJK COMPATIBILITY IDEOGRAPH-2F87A;Lo;0;L;5C8D;;;;N;;;;; -2F87B;CJK COMPATIBILITY IDEOGRAPH-2F87B;Lo;0;L;21DE4;;;;N;;;;; -2F87C;CJK COMPATIBILITY IDEOGRAPH-2F87C;Lo;0;L;5D43;;;;N;;;;; -2F87D;CJK COMPATIBILITY IDEOGRAPH-2F87D;Lo;0;L;21DE6;;;;N;;;;; -2F87E;CJK COMPATIBILITY IDEOGRAPH-2F87E;Lo;0;L;5D6E;;;;N;;;;; -2F87F;CJK COMPATIBILITY IDEOGRAPH-2F87F;Lo;0;L;5D6B;;;;N;;;;; -2F880;CJK COMPATIBILITY IDEOGRAPH-2F880;Lo;0;L;5D7C;;;;N;;;;; -2F881;CJK COMPATIBILITY IDEOGRAPH-2F881;Lo;0;L;5DE1;;;;N;;;;; -2F882;CJK COMPATIBILITY IDEOGRAPH-2F882;Lo;0;L;5DE2;;;;N;;;;; -2F883;CJK COMPATIBILITY IDEOGRAPH-2F883;Lo;0;L;382F;;;;N;;;;; -2F884;CJK COMPATIBILITY IDEOGRAPH-2F884;Lo;0;L;5DFD;;;;N;;;;; -2F885;CJK COMPATIBILITY IDEOGRAPH-2F885;Lo;0;L;5E28;;;;N;;;;; -2F886;CJK COMPATIBILITY IDEOGRAPH-2F886;Lo;0;L;5E3D;;;;N;;;;; -2F887;CJK COMPATIBILITY IDEOGRAPH-2F887;Lo;0;L;5E69;;;;N;;;;; -2F888;CJK COMPATIBILITY IDEOGRAPH-2F888;Lo;0;L;3862;;;;N;;;;; -2F889;CJK COMPATIBILITY IDEOGRAPH-2F889;Lo;0;L;22183;;;;N;;;;; -2F88A;CJK COMPATIBILITY IDEOGRAPH-2F88A;Lo;0;L;387C;;;;N;;;;; -2F88B;CJK COMPATIBILITY IDEOGRAPH-2F88B;Lo;0;L;5EB0;;;;N;;;;; -2F88C;CJK COMPATIBILITY IDEOGRAPH-2F88C;Lo;0;L;5EB3;;;;N;;;;; -2F88D;CJK COMPATIBILITY IDEOGRAPH-2F88D;Lo;0;L;5EB6;;;;N;;;;; -2F88E;CJK COMPATIBILITY IDEOGRAPH-2F88E;Lo;0;L;5ECA;;;;N;;;;; -2F88F;CJK COMPATIBILITY IDEOGRAPH-2F88F;Lo;0;L;2A392;;;;N;;;;; -2F890;CJK COMPATIBILITY IDEOGRAPH-2F890;Lo;0;L;5EFE;;;9;N;;;;; -2F891;CJK COMPATIBILITY IDEOGRAPH-2F891;Lo;0;L;22331;;;;N;;;;; -2F892;CJK COMPATIBILITY IDEOGRAPH-2F892;Lo;0;L;22331;;;;N;;;;; -2F893;CJK COMPATIBILITY IDEOGRAPH-2F893;Lo;0;L;8201;;;;N;;;;; -2F894;CJK COMPATIBILITY IDEOGRAPH-2F894;Lo;0;L;5F22;;;;N;;;;; -2F895;CJK COMPATIBILITY IDEOGRAPH-2F895;Lo;0;L;5F22;;;;N;;;;; -2F896;CJK COMPATIBILITY IDEOGRAPH-2F896;Lo;0;L;38C7;;;;N;;;;; -2F897;CJK COMPATIBILITY IDEOGRAPH-2F897;Lo;0;L;232B8;;;;N;;;;; -2F898;CJK COMPATIBILITY IDEOGRAPH-2F898;Lo;0;L;261DA;;;;N;;;;; -2F899;CJK COMPATIBILITY IDEOGRAPH-2F899;Lo;0;L;5F62;;;;N;;;;; -2F89A;CJK COMPATIBILITY IDEOGRAPH-2F89A;Lo;0;L;5F6B;;;;N;;;;; -2F89B;CJK COMPATIBILITY IDEOGRAPH-2F89B;Lo;0;L;38E3;;;;N;;;;; -2F89C;CJK COMPATIBILITY IDEOGRAPH-2F89C;Lo;0;L;5F9A;;;;N;;;;; -2F89D;CJK COMPATIBILITY IDEOGRAPH-2F89D;Lo;0;L;5FCD;;;;N;;;;; -2F89E;CJK COMPATIBILITY IDEOGRAPH-2F89E;Lo;0;L;5FD7;;;;N;;;;; -2F89F;CJK COMPATIBILITY IDEOGRAPH-2F89F;Lo;0;L;5FF9;;;;N;;;;; -2F8A0;CJK COMPATIBILITY IDEOGRAPH-2F8A0;Lo;0;L;6081;;;;N;;;;; -2F8A1;CJK COMPATIBILITY IDEOGRAPH-2F8A1;Lo;0;L;393A;;;;N;;;;; -2F8A2;CJK COMPATIBILITY IDEOGRAPH-2F8A2;Lo;0;L;391C;;;;N;;;;; -2F8A3;CJK COMPATIBILITY IDEOGRAPH-2F8A3;Lo;0;L;6094;;;;N;;;;; -2F8A4;CJK COMPATIBILITY IDEOGRAPH-2F8A4;Lo;0;L;226D4;;;;N;;;;; -2F8A5;CJK COMPATIBILITY IDEOGRAPH-2F8A5;Lo;0;L;60C7;;;;N;;;;; -2F8A6;CJK COMPATIBILITY IDEOGRAPH-2F8A6;Lo;0;L;6148;;;;N;;;;; -2F8A7;CJK COMPATIBILITY IDEOGRAPH-2F8A7;Lo;0;L;614C;;;;N;;;;; -2F8A8;CJK COMPATIBILITY IDEOGRAPH-2F8A8;Lo;0;L;614E;;;;N;;;;; -2F8A9;CJK COMPATIBILITY IDEOGRAPH-2F8A9;Lo;0;L;614C;;;;N;;;;; -2F8AA;CJK COMPATIBILITY IDEOGRAPH-2F8AA;Lo;0;L;617A;;;;N;;;;; -2F8AB;CJK COMPATIBILITY IDEOGRAPH-2F8AB;Lo;0;L;618E;;;;N;;;;; -2F8AC;CJK COMPATIBILITY IDEOGRAPH-2F8AC;Lo;0;L;61B2;;;;N;;;;; -2F8AD;CJK COMPATIBILITY IDEOGRAPH-2F8AD;Lo;0;L;61A4;;;;N;;;;; -2F8AE;CJK COMPATIBILITY IDEOGRAPH-2F8AE;Lo;0;L;61AF;;;;N;;;;; -2F8AF;CJK COMPATIBILITY IDEOGRAPH-2F8AF;Lo;0;L;61DE;;;;N;;;;; -2F8B0;CJK COMPATIBILITY IDEOGRAPH-2F8B0;Lo;0;L;61F2;;;;N;;;;; -2F8B1;CJK COMPATIBILITY IDEOGRAPH-2F8B1;Lo;0;L;61F6;;;;N;;;;; -2F8B2;CJK COMPATIBILITY IDEOGRAPH-2F8B2;Lo;0;L;6210;;;;N;;;;; -2F8B3;CJK COMPATIBILITY IDEOGRAPH-2F8B3;Lo;0;L;621B;;;;N;;;;; -2F8B4;CJK COMPATIBILITY IDEOGRAPH-2F8B4;Lo;0;L;625D;;;;N;;;;; -2F8B5;CJK COMPATIBILITY IDEOGRAPH-2F8B5;Lo;0;L;62B1;;;;N;;;;; -2F8B6;CJK COMPATIBILITY IDEOGRAPH-2F8B6;Lo;0;L;62D4;;;;N;;;;; -2F8B7;CJK COMPATIBILITY IDEOGRAPH-2F8B7;Lo;0;L;6350;;;;N;;;;; -2F8B8;CJK COMPATIBILITY IDEOGRAPH-2F8B8;Lo;0;L;22B0C;;;;N;;;;; -2F8B9;CJK COMPATIBILITY IDEOGRAPH-2F8B9;Lo;0;L;633D;;;;N;;;;; -2F8BA;CJK COMPATIBILITY IDEOGRAPH-2F8BA;Lo;0;L;62FC;;;;N;;;;; -2F8BB;CJK COMPATIBILITY IDEOGRAPH-2F8BB;Lo;0;L;6368;;;;N;;;;; -2F8BC;CJK COMPATIBILITY IDEOGRAPH-2F8BC;Lo;0;L;6383;;;;N;;;;; -2F8BD;CJK COMPATIBILITY IDEOGRAPH-2F8BD;Lo;0;L;63E4;;;;N;;;;; -2F8BE;CJK COMPATIBILITY IDEOGRAPH-2F8BE;Lo;0;L;22BF1;;;;N;;;;; -2F8BF;CJK COMPATIBILITY IDEOGRAPH-2F8BF;Lo;0;L;6422;;;;N;;;;; -2F8C0;CJK COMPATIBILITY IDEOGRAPH-2F8C0;Lo;0;L;63C5;;;;N;;;;; -2F8C1;CJK COMPATIBILITY IDEOGRAPH-2F8C1;Lo;0;L;63A9;;;;N;;;;; -2F8C2;CJK COMPATIBILITY IDEOGRAPH-2F8C2;Lo;0;L;3A2E;;;;N;;;;; -2F8C3;CJK COMPATIBILITY IDEOGRAPH-2F8C3;Lo;0;L;6469;;;;N;;;;; -2F8C4;CJK COMPATIBILITY IDEOGRAPH-2F8C4;Lo;0;L;647E;;;;N;;;;; -2F8C5;CJK COMPATIBILITY IDEOGRAPH-2F8C5;Lo;0;L;649D;;;;N;;;;; -2F8C6;CJK COMPATIBILITY IDEOGRAPH-2F8C6;Lo;0;L;6477;;;;N;;;;; -2F8C7;CJK COMPATIBILITY IDEOGRAPH-2F8C7;Lo;0;L;3A6C;;;;N;;;;; -2F8C8;CJK COMPATIBILITY IDEOGRAPH-2F8C8;Lo;0;L;654F;;;;N;;;;; -2F8C9;CJK COMPATIBILITY IDEOGRAPH-2F8C9;Lo;0;L;656C;;;;N;;;;; -2F8CA;CJK COMPATIBILITY IDEOGRAPH-2F8CA;Lo;0;L;2300A;;;;N;;;;; -2F8CB;CJK COMPATIBILITY IDEOGRAPH-2F8CB;Lo;0;L;65E3;;;;N;;;;; -2F8CC;CJK COMPATIBILITY IDEOGRAPH-2F8CC;Lo;0;L;66F8;;;;N;;;;; -2F8CD;CJK COMPATIBILITY IDEOGRAPH-2F8CD;Lo;0;L;6649;;;;N;;;;; -2F8CE;CJK COMPATIBILITY IDEOGRAPH-2F8CE;Lo;0;L;3B19;;;;N;;;;; -2F8CF;CJK COMPATIBILITY IDEOGRAPH-2F8CF;Lo;0;L;6691;;;;N;;;;; -2F8D0;CJK COMPATIBILITY IDEOGRAPH-2F8D0;Lo;0;L;3B08;;;;N;;;;; -2F8D1;CJK COMPATIBILITY IDEOGRAPH-2F8D1;Lo;0;L;3AE4;;;;N;;;;; -2F8D2;CJK COMPATIBILITY IDEOGRAPH-2F8D2;Lo;0;L;5192;;;;N;;;;; -2F8D3;CJK COMPATIBILITY IDEOGRAPH-2F8D3;Lo;0;L;5195;;;;N;;;;; -2F8D4;CJK COMPATIBILITY IDEOGRAPH-2F8D4;Lo;0;L;6700;;;;N;;;;; -2F8D5;CJK COMPATIBILITY IDEOGRAPH-2F8D5;Lo;0;L;669C;;;;N;;;;; -2F8D6;CJK COMPATIBILITY IDEOGRAPH-2F8D6;Lo;0;L;80AD;;;;N;;;;; -2F8D7;CJK COMPATIBILITY IDEOGRAPH-2F8D7;Lo;0;L;43D9;;;;N;;;;; -2F8D8;CJK COMPATIBILITY IDEOGRAPH-2F8D8;Lo;0;L;6717;;;;N;;;;; -2F8D9;CJK COMPATIBILITY IDEOGRAPH-2F8D9;Lo;0;L;671B;;;;N;;;;; -2F8DA;CJK COMPATIBILITY IDEOGRAPH-2F8DA;Lo;0;L;6721;;;;N;;;;; -2F8DB;CJK COMPATIBILITY IDEOGRAPH-2F8DB;Lo;0;L;675E;;;;N;;;;; -2F8DC;CJK COMPATIBILITY IDEOGRAPH-2F8DC;Lo;0;L;6753;;;;N;;;;; -2F8DD;CJK COMPATIBILITY IDEOGRAPH-2F8DD;Lo;0;L;233C3;;;;N;;;;; -2F8DE;CJK COMPATIBILITY IDEOGRAPH-2F8DE;Lo;0;L;3B49;;;;N;;;;; -2F8DF;CJK COMPATIBILITY IDEOGRAPH-2F8DF;Lo;0;L;67FA;;;;N;;;;; -2F8E0;CJK COMPATIBILITY IDEOGRAPH-2F8E0;Lo;0;L;6785;;;;N;;;;; -2F8E1;CJK COMPATIBILITY IDEOGRAPH-2F8E1;Lo;0;L;6852;;;;N;;;;; -2F8E2;CJK COMPATIBILITY IDEOGRAPH-2F8E2;Lo;0;L;6885;;;;N;;;;; -2F8E3;CJK COMPATIBILITY IDEOGRAPH-2F8E3;Lo;0;L;2346D;;;;N;;;;; -2F8E4;CJK COMPATIBILITY IDEOGRAPH-2F8E4;Lo;0;L;688E;;;;N;;;;; -2F8E5;CJK COMPATIBILITY IDEOGRAPH-2F8E5;Lo;0;L;681F;;;;N;;;;; -2F8E6;CJK COMPATIBILITY IDEOGRAPH-2F8E6;Lo;0;L;6914;;;;N;;;;; -2F8E7;CJK COMPATIBILITY IDEOGRAPH-2F8E7;Lo;0;L;3B9D;;;;N;;;;; -2F8E8;CJK COMPATIBILITY IDEOGRAPH-2F8E8;Lo;0;L;6942;;;;N;;;;; -2F8E9;CJK COMPATIBILITY IDEOGRAPH-2F8E9;Lo;0;L;69A3;;;;N;;;;; -2F8EA;CJK COMPATIBILITY IDEOGRAPH-2F8EA;Lo;0;L;69EA;;;;N;;;;; -2F8EB;CJK COMPATIBILITY IDEOGRAPH-2F8EB;Lo;0;L;6AA8;;;;N;;;;; -2F8EC;CJK COMPATIBILITY IDEOGRAPH-2F8EC;Lo;0;L;236A3;;;;N;;;;; -2F8ED;CJK COMPATIBILITY IDEOGRAPH-2F8ED;Lo;0;L;6ADB;;;;N;;;;; -2F8EE;CJK COMPATIBILITY IDEOGRAPH-2F8EE;Lo;0;L;3C18;;;;N;;;;; -2F8EF;CJK COMPATIBILITY IDEOGRAPH-2F8EF;Lo;0;L;6B21;;;;N;;;;; -2F8F0;CJK COMPATIBILITY IDEOGRAPH-2F8F0;Lo;0;L;238A7;;;;N;;;;; -2F8F1;CJK COMPATIBILITY IDEOGRAPH-2F8F1;Lo;0;L;6B54;;;;N;;;;; -2F8F2;CJK COMPATIBILITY IDEOGRAPH-2F8F2;Lo;0;L;3C4E;;;;N;;;;; -2F8F3;CJK COMPATIBILITY IDEOGRAPH-2F8F3;Lo;0;L;6B72;;;;N;;;;; -2F8F4;CJK COMPATIBILITY IDEOGRAPH-2F8F4;Lo;0;L;6B9F;;;;N;;;;; -2F8F5;CJK COMPATIBILITY IDEOGRAPH-2F8F5;Lo;0;L;6BBA;;;;N;;;;; -2F8F6;CJK COMPATIBILITY IDEOGRAPH-2F8F6;Lo;0;L;6BBB;;;;N;;;;; -2F8F7;CJK COMPATIBILITY IDEOGRAPH-2F8F7;Lo;0;L;23A8D;;;;N;;;;; -2F8F8;CJK COMPATIBILITY IDEOGRAPH-2F8F8;Lo;0;L;21D0B;;;;N;;;;; -2F8F9;CJK COMPATIBILITY IDEOGRAPH-2F8F9;Lo;0;L;23AFA;;;;N;;;;; -2F8FA;CJK COMPATIBILITY IDEOGRAPH-2F8FA;Lo;0;L;6C4E;;;;N;;;;; -2F8FB;CJK COMPATIBILITY IDEOGRAPH-2F8FB;Lo;0;L;23CBC;;;;N;;;;; -2F8FC;CJK COMPATIBILITY IDEOGRAPH-2F8FC;Lo;0;L;6CBF;;;;N;;;;; -2F8FD;CJK COMPATIBILITY IDEOGRAPH-2F8FD;Lo;0;L;6CCD;;;;N;;;;; -2F8FE;CJK COMPATIBILITY IDEOGRAPH-2F8FE;Lo;0;L;6C67;;;;N;;;;; -2F8FF;CJK COMPATIBILITY IDEOGRAPH-2F8FF;Lo;0;L;6D16;;;;N;;;;; -2F900;CJK COMPATIBILITY IDEOGRAPH-2F900;Lo;0;L;6D3E;;;;N;;;;; -2F901;CJK COMPATIBILITY IDEOGRAPH-2F901;Lo;0;L;6D77;;;;N;;;;; -2F902;CJK COMPATIBILITY IDEOGRAPH-2F902;Lo;0;L;6D41;;;;N;;;;; -2F903;CJK COMPATIBILITY IDEOGRAPH-2F903;Lo;0;L;6D69;;;;N;;;;; -2F904;CJK COMPATIBILITY IDEOGRAPH-2F904;Lo;0;L;6D78;;;;N;;;;; -2F905;CJK COMPATIBILITY IDEOGRAPH-2F905;Lo;0;L;6D85;;;;N;;;;; -2F906;CJK COMPATIBILITY IDEOGRAPH-2F906;Lo;0;L;23D1E;;;;N;;;;; -2F907;CJK COMPATIBILITY IDEOGRAPH-2F907;Lo;0;L;6D34;;;;N;;;;; -2F908;CJK COMPATIBILITY IDEOGRAPH-2F908;Lo;0;L;6E2F;;;;N;;;;; -2F909;CJK COMPATIBILITY IDEOGRAPH-2F909;Lo;0;L;6E6E;;;;N;;;;; -2F90A;CJK COMPATIBILITY IDEOGRAPH-2F90A;Lo;0;L;3D33;;;;N;;;;; -2F90B;CJK COMPATIBILITY IDEOGRAPH-2F90B;Lo;0;L;6ECB;;;;N;;;;; -2F90C;CJK COMPATIBILITY IDEOGRAPH-2F90C;Lo;0;L;6EC7;;;;N;;;;; -2F90D;CJK COMPATIBILITY IDEOGRAPH-2F90D;Lo;0;L;23ED1;;;;N;;;;; -2F90E;CJK COMPATIBILITY IDEOGRAPH-2F90E;Lo;0;L;6DF9;;;;N;;;;; -2F90F;CJK COMPATIBILITY IDEOGRAPH-2F90F;Lo;0;L;6F6E;;;;N;;;;; -2F910;CJK COMPATIBILITY IDEOGRAPH-2F910;Lo;0;L;23F5E;;;;N;;;;; -2F911;CJK COMPATIBILITY IDEOGRAPH-2F911;Lo;0;L;23F8E;;;;N;;;;; -2F912;CJK COMPATIBILITY IDEOGRAPH-2F912;Lo;0;L;6FC6;;;;N;;;;; -2F913;CJK COMPATIBILITY IDEOGRAPH-2F913;Lo;0;L;7039;;;;N;;;;; -2F914;CJK COMPATIBILITY IDEOGRAPH-2F914;Lo;0;L;701E;;;;N;;;;; -2F915;CJK COMPATIBILITY IDEOGRAPH-2F915;Lo;0;L;701B;;;;N;;;;; -2F916;CJK COMPATIBILITY IDEOGRAPH-2F916;Lo;0;L;3D96;;;;N;;;;; -2F917;CJK COMPATIBILITY IDEOGRAPH-2F917;Lo;0;L;704A;;;;N;;;;; -2F918;CJK COMPATIBILITY IDEOGRAPH-2F918;Lo;0;L;707D;;;;N;;;;; -2F919;CJK COMPATIBILITY IDEOGRAPH-2F919;Lo;0;L;7077;;;;N;;;;; -2F91A;CJK COMPATIBILITY IDEOGRAPH-2F91A;Lo;0;L;70AD;;;;N;;;;; -2F91B;CJK COMPATIBILITY IDEOGRAPH-2F91B;Lo;0;L;20525;;;;N;;;;; -2F91C;CJK COMPATIBILITY IDEOGRAPH-2F91C;Lo;0;L;7145;;;;N;;;;; -2F91D;CJK COMPATIBILITY IDEOGRAPH-2F91D;Lo;0;L;24263;;;;N;;;;; -2F91E;CJK COMPATIBILITY IDEOGRAPH-2F91E;Lo;0;L;719C;;;;N;;;;; -2F91F;CJK COMPATIBILITY IDEOGRAPH-2F91F;Lo;0;L;243AB;;;;N;;;;; -2F920;CJK COMPATIBILITY IDEOGRAPH-2F920;Lo;0;L;7228;;;;N;;;;; -2F921;CJK COMPATIBILITY IDEOGRAPH-2F921;Lo;0;L;7235;;;;N;;;;; -2F922;CJK COMPATIBILITY IDEOGRAPH-2F922;Lo;0;L;7250;;;;N;;;;; -2F923;CJK COMPATIBILITY IDEOGRAPH-2F923;Lo;0;L;24608;;;;N;;;;; -2F924;CJK COMPATIBILITY IDEOGRAPH-2F924;Lo;0;L;7280;;;;N;;;;; -2F925;CJK COMPATIBILITY IDEOGRAPH-2F925;Lo;0;L;7295;;;;N;;;;; -2F926;CJK COMPATIBILITY IDEOGRAPH-2F926;Lo;0;L;24735;;;;N;;;;; -2F927;CJK COMPATIBILITY IDEOGRAPH-2F927;Lo;0;L;24814;;;;N;;;;; -2F928;CJK COMPATIBILITY IDEOGRAPH-2F928;Lo;0;L;737A;;;;N;;;;; -2F929;CJK COMPATIBILITY IDEOGRAPH-2F929;Lo;0;L;738B;;;;N;;;;; -2F92A;CJK COMPATIBILITY IDEOGRAPH-2F92A;Lo;0;L;3EAC;;;;N;;;;; -2F92B;CJK COMPATIBILITY IDEOGRAPH-2F92B;Lo;0;L;73A5;;;;N;;;;; -2F92C;CJK COMPATIBILITY IDEOGRAPH-2F92C;Lo;0;L;3EB8;;;;N;;;;; -2F92D;CJK COMPATIBILITY IDEOGRAPH-2F92D;Lo;0;L;3EB8;;;;N;;;;; -2F92E;CJK COMPATIBILITY IDEOGRAPH-2F92E;Lo;0;L;7447;;;;N;;;;; -2F92F;CJK COMPATIBILITY IDEOGRAPH-2F92F;Lo;0;L;745C;;;;N;;;;; -2F930;CJK COMPATIBILITY IDEOGRAPH-2F930;Lo;0;L;7471;;;;N;;;;; -2F931;CJK COMPATIBILITY IDEOGRAPH-2F931;Lo;0;L;7485;;;;N;;;;; -2F932;CJK COMPATIBILITY IDEOGRAPH-2F932;Lo;0;L;74CA;;;;N;;;;; -2F933;CJK COMPATIBILITY IDEOGRAPH-2F933;Lo;0;L;3F1B;;;;N;;;;; -2F934;CJK COMPATIBILITY IDEOGRAPH-2F934;Lo;0;L;7524;;;;N;;;;; -2F935;CJK COMPATIBILITY IDEOGRAPH-2F935;Lo;0;L;24C36;;;;N;;;;; -2F936;CJK COMPATIBILITY IDEOGRAPH-2F936;Lo;0;L;753E;;;;N;;;;; -2F937;CJK COMPATIBILITY IDEOGRAPH-2F937;Lo;0;L;24C92;;;;N;;;;; -2F938;CJK COMPATIBILITY IDEOGRAPH-2F938;Lo;0;L;7570;;;;N;;;;; -2F939;CJK COMPATIBILITY IDEOGRAPH-2F939;Lo;0;L;2219F;;;;N;;;;; -2F93A;CJK COMPATIBILITY IDEOGRAPH-2F93A;Lo;0;L;7610;;;;N;;;;; -2F93B;CJK COMPATIBILITY IDEOGRAPH-2F93B;Lo;0;L;24FA1;;;;N;;;;; -2F93C;CJK COMPATIBILITY IDEOGRAPH-2F93C;Lo;0;L;24FB8;;;;N;;;;; -2F93D;CJK COMPATIBILITY IDEOGRAPH-2F93D;Lo;0;L;25044;;;;N;;;;; -2F93E;CJK COMPATIBILITY IDEOGRAPH-2F93E;Lo;0;L;3FFC;;;;N;;;;; -2F93F;CJK COMPATIBILITY IDEOGRAPH-2F93F;Lo;0;L;4008;;;;N;;;;; -2F940;CJK COMPATIBILITY IDEOGRAPH-2F940;Lo;0;L;76F4;;;;N;;;;; -2F941;CJK COMPATIBILITY IDEOGRAPH-2F941;Lo;0;L;250F3;;;;N;;;;; -2F942;CJK COMPATIBILITY IDEOGRAPH-2F942;Lo;0;L;250F2;;;;N;;;;; -2F943;CJK COMPATIBILITY IDEOGRAPH-2F943;Lo;0;L;25119;;;;N;;;;; -2F944;CJK COMPATIBILITY IDEOGRAPH-2F944;Lo;0;L;25133;;;;N;;;;; -2F945;CJK COMPATIBILITY IDEOGRAPH-2F945;Lo;0;L;771E;;;;N;;;;; -2F946;CJK COMPATIBILITY IDEOGRAPH-2F946;Lo;0;L;771F;;;;N;;;;; -2F947;CJK COMPATIBILITY IDEOGRAPH-2F947;Lo;0;L;771F;;;;N;;;;; -2F948;CJK COMPATIBILITY IDEOGRAPH-2F948;Lo;0;L;774A;;;;N;;;;; -2F949;CJK COMPATIBILITY IDEOGRAPH-2F949;Lo;0;L;4039;;;;N;;;;; -2F94A;CJK COMPATIBILITY IDEOGRAPH-2F94A;Lo;0;L;778B;;;;N;;;;; -2F94B;CJK COMPATIBILITY IDEOGRAPH-2F94B;Lo;0;L;4046;;;;N;;;;; -2F94C;CJK COMPATIBILITY IDEOGRAPH-2F94C;Lo;0;L;4096;;;;N;;;;; -2F94D;CJK COMPATIBILITY IDEOGRAPH-2F94D;Lo;0;L;2541D;;;;N;;;;; -2F94E;CJK COMPATIBILITY IDEOGRAPH-2F94E;Lo;0;L;784E;;;;N;;;;; -2F94F;CJK COMPATIBILITY IDEOGRAPH-2F94F;Lo;0;L;788C;;;;N;;;;; -2F950;CJK COMPATIBILITY IDEOGRAPH-2F950;Lo;0;L;78CC;;;;N;;;;; -2F951;CJK COMPATIBILITY IDEOGRAPH-2F951;Lo;0;L;40E3;;;;N;;;;; -2F952;CJK COMPATIBILITY IDEOGRAPH-2F952;Lo;0;L;25626;;;;N;;;;; -2F953;CJK COMPATIBILITY IDEOGRAPH-2F953;Lo;0;L;7956;;;;N;;;;; -2F954;CJK COMPATIBILITY IDEOGRAPH-2F954;Lo;0;L;2569A;;;;N;;;;; -2F955;CJK COMPATIBILITY IDEOGRAPH-2F955;Lo;0;L;256C5;;;;N;;;;; -2F956;CJK COMPATIBILITY IDEOGRAPH-2F956;Lo;0;L;798F;;;;N;;;;; -2F957;CJK COMPATIBILITY IDEOGRAPH-2F957;Lo;0;L;79EB;;;;N;;;;; -2F958;CJK COMPATIBILITY IDEOGRAPH-2F958;Lo;0;L;412F;;;;N;;;;; -2F959;CJK COMPATIBILITY IDEOGRAPH-2F959;Lo;0;L;7A40;;;;N;;;;; -2F95A;CJK COMPATIBILITY IDEOGRAPH-2F95A;Lo;0;L;7A4A;;;;N;;;;; -2F95B;CJK COMPATIBILITY IDEOGRAPH-2F95B;Lo;0;L;7A4F;;;;N;;;;; -2F95C;CJK COMPATIBILITY IDEOGRAPH-2F95C;Lo;0;L;2597C;;;;N;;;;; -2F95D;CJK COMPATIBILITY IDEOGRAPH-2F95D;Lo;0;L;25AA7;;;;N;;;;; -2F95E;CJK COMPATIBILITY IDEOGRAPH-2F95E;Lo;0;L;25AA7;;;;N;;;;; -2F95F;CJK COMPATIBILITY IDEOGRAPH-2F95F;Lo;0;L;7AEE;;;;N;;;;; -2F960;CJK COMPATIBILITY IDEOGRAPH-2F960;Lo;0;L;4202;;;;N;;;;; -2F961;CJK COMPATIBILITY IDEOGRAPH-2F961;Lo;0;L;25BAB;;;;N;;;;; -2F962;CJK COMPATIBILITY IDEOGRAPH-2F962;Lo;0;L;7BC6;;;;N;;;;; -2F963;CJK COMPATIBILITY IDEOGRAPH-2F963;Lo;0;L;7BC9;;;;N;;;;; -2F964;CJK COMPATIBILITY IDEOGRAPH-2F964;Lo;0;L;4227;;;;N;;;;; -2F965;CJK COMPATIBILITY IDEOGRAPH-2F965;Lo;0;L;25C80;;;;N;;;;; -2F966;CJK COMPATIBILITY IDEOGRAPH-2F966;Lo;0;L;7CD2;;;;N;;;;; -2F967;CJK COMPATIBILITY IDEOGRAPH-2F967;Lo;0;L;42A0;;;;N;;;;; -2F968;CJK COMPATIBILITY IDEOGRAPH-2F968;Lo;0;L;7CE8;;;;N;;;;; -2F969;CJK COMPATIBILITY IDEOGRAPH-2F969;Lo;0;L;7CE3;;;;N;;;;; -2F96A;CJK COMPATIBILITY IDEOGRAPH-2F96A;Lo;0;L;7D00;;;;N;;;;; -2F96B;CJK COMPATIBILITY IDEOGRAPH-2F96B;Lo;0;L;25F86;;;;N;;;;; -2F96C;CJK COMPATIBILITY IDEOGRAPH-2F96C;Lo;0;L;7D63;;;;N;;;;; -2F96D;CJK COMPATIBILITY IDEOGRAPH-2F96D;Lo;0;L;4301;;;;N;;;;; -2F96E;CJK COMPATIBILITY IDEOGRAPH-2F96E;Lo;0;L;7DC7;;;;N;;;;; -2F96F;CJK COMPATIBILITY IDEOGRAPH-2F96F;Lo;0;L;7E02;;;;N;;;;; -2F970;CJK COMPATIBILITY IDEOGRAPH-2F970;Lo;0;L;7E45;;;;N;;;;; -2F971;CJK COMPATIBILITY IDEOGRAPH-2F971;Lo;0;L;4334;;;;N;;;;; -2F972;CJK COMPATIBILITY IDEOGRAPH-2F972;Lo;0;L;26228;;;;N;;;;; -2F973;CJK COMPATIBILITY IDEOGRAPH-2F973;Lo;0;L;26247;;;;N;;;;; -2F974;CJK COMPATIBILITY IDEOGRAPH-2F974;Lo;0;L;4359;;;;N;;;;; -2F975;CJK COMPATIBILITY IDEOGRAPH-2F975;Lo;0;L;262D9;;;;N;;;;; -2F976;CJK COMPATIBILITY IDEOGRAPH-2F976;Lo;0;L;7F7A;;;;N;;;;; -2F977;CJK COMPATIBILITY IDEOGRAPH-2F977;Lo;0;L;2633E;;;;N;;;;; -2F978;CJK COMPATIBILITY IDEOGRAPH-2F978;Lo;0;L;7F95;;;;N;;;;; -2F979;CJK COMPATIBILITY IDEOGRAPH-2F979;Lo;0;L;7FFA;;;;N;;;;; -2F97A;CJK COMPATIBILITY IDEOGRAPH-2F97A;Lo;0;L;8005;;;;N;;;;; -2F97B;CJK COMPATIBILITY IDEOGRAPH-2F97B;Lo;0;L;264DA;;;;N;;;;; -2F97C;CJK COMPATIBILITY IDEOGRAPH-2F97C;Lo;0;L;26523;;;;N;;;;; -2F97D;CJK COMPATIBILITY IDEOGRAPH-2F97D;Lo;0;L;8060;;;;N;;;;; -2F97E;CJK COMPATIBILITY IDEOGRAPH-2F97E;Lo;0;L;265A8;;;;N;;;;; -2F97F;CJK COMPATIBILITY IDEOGRAPH-2F97F;Lo;0;L;8070;;;;N;;;;; -2F980;CJK COMPATIBILITY IDEOGRAPH-2F980;Lo;0;L;2335F;;;;N;;;;; -2F981;CJK COMPATIBILITY IDEOGRAPH-2F981;Lo;0;L;43D5;;;;N;;;;; -2F982;CJK COMPATIBILITY IDEOGRAPH-2F982;Lo;0;L;80B2;;;;N;;;;; -2F983;CJK COMPATIBILITY IDEOGRAPH-2F983;Lo;0;L;8103;;;;N;;;;; -2F984;CJK COMPATIBILITY IDEOGRAPH-2F984;Lo;0;L;440B;;;;N;;;;; -2F985;CJK COMPATIBILITY IDEOGRAPH-2F985;Lo;0;L;813E;;;;N;;;;; -2F986;CJK COMPATIBILITY IDEOGRAPH-2F986;Lo;0;L;5AB5;;;;N;;;;; -2F987;CJK COMPATIBILITY IDEOGRAPH-2F987;Lo;0;L;267A7;;;;N;;;;; -2F988;CJK COMPATIBILITY IDEOGRAPH-2F988;Lo;0;L;267B5;;;;N;;;;; -2F989;CJK COMPATIBILITY IDEOGRAPH-2F989;Lo;0;L;23393;;;;N;;;;; -2F98A;CJK COMPATIBILITY IDEOGRAPH-2F98A;Lo;0;L;2339C;;;;N;;;;; -2F98B;CJK COMPATIBILITY IDEOGRAPH-2F98B;Lo;0;L;8201;;;;N;;;;; -2F98C;CJK COMPATIBILITY IDEOGRAPH-2F98C;Lo;0;L;8204;;;;N;;;;; -2F98D;CJK COMPATIBILITY IDEOGRAPH-2F98D;Lo;0;L;8F9E;;;;N;;;;; -2F98E;CJK COMPATIBILITY IDEOGRAPH-2F98E;Lo;0;L;446B;;;;N;;;;; -2F98F;CJK COMPATIBILITY IDEOGRAPH-2F98F;Lo;0;L;8291;;;;N;;;;; -2F990;CJK COMPATIBILITY IDEOGRAPH-2F990;Lo;0;L;828B;;;;N;;;;; -2F991;CJK COMPATIBILITY IDEOGRAPH-2F991;Lo;0;L;829D;;;;N;;;;; -2F992;CJK COMPATIBILITY IDEOGRAPH-2F992;Lo;0;L;52B3;;;;N;;;;; -2F993;CJK COMPATIBILITY IDEOGRAPH-2F993;Lo;0;L;82B1;;;;N;;;;; -2F994;CJK COMPATIBILITY IDEOGRAPH-2F994;Lo;0;L;82B3;;;;N;;;;; -2F995;CJK COMPATIBILITY IDEOGRAPH-2F995;Lo;0;L;82BD;;;;N;;;;; -2F996;CJK COMPATIBILITY IDEOGRAPH-2F996;Lo;0;L;82E6;;;;N;;;;; -2F997;CJK COMPATIBILITY IDEOGRAPH-2F997;Lo;0;L;26B3C;;;;N;;;;; -2F998;CJK COMPATIBILITY IDEOGRAPH-2F998;Lo;0;L;82E5;;;;N;;;;; -2F999;CJK COMPATIBILITY IDEOGRAPH-2F999;Lo;0;L;831D;;;;N;;;;; -2F99A;CJK COMPATIBILITY IDEOGRAPH-2F99A;Lo;0;L;8363;;;;N;;;;; -2F99B;CJK COMPATIBILITY IDEOGRAPH-2F99B;Lo;0;L;83AD;;;;N;;;;; -2F99C;CJK COMPATIBILITY IDEOGRAPH-2F99C;Lo;0;L;8323;;;;N;;;;; -2F99D;CJK COMPATIBILITY IDEOGRAPH-2F99D;Lo;0;L;83BD;;;;N;;;;; -2F99E;CJK COMPATIBILITY IDEOGRAPH-2F99E;Lo;0;L;83E7;;;;N;;;;; -2F99F;CJK COMPATIBILITY IDEOGRAPH-2F99F;Lo;0;L;8457;;;;N;;;;; -2F9A0;CJK COMPATIBILITY IDEOGRAPH-2F9A0;Lo;0;L;8353;;;;N;;;;; -2F9A1;CJK COMPATIBILITY IDEOGRAPH-2F9A1;Lo;0;L;83CA;;;;N;;;;; -2F9A2;CJK COMPATIBILITY IDEOGRAPH-2F9A2;Lo;0;L;83CC;;;;N;;;;; -2F9A3;CJK COMPATIBILITY IDEOGRAPH-2F9A3;Lo;0;L;83DC;;;;N;;;;; -2F9A4;CJK COMPATIBILITY IDEOGRAPH-2F9A4;Lo;0;L;26C36;;;;N;;;;; -2F9A5;CJK COMPATIBILITY IDEOGRAPH-2F9A5;Lo;0;L;26D6B;;;;N;;;;; -2F9A6;CJK COMPATIBILITY IDEOGRAPH-2F9A6;Lo;0;L;26CD5;;;;N;;;;; -2F9A7;CJK COMPATIBILITY IDEOGRAPH-2F9A7;Lo;0;L;452B;;;;N;;;;; -2F9A8;CJK COMPATIBILITY IDEOGRAPH-2F9A8;Lo;0;L;84F1;;;;N;;;;; -2F9A9;CJK COMPATIBILITY IDEOGRAPH-2F9A9;Lo;0;L;84F3;;;;N;;;;; -2F9AA;CJK COMPATIBILITY IDEOGRAPH-2F9AA;Lo;0;L;8516;;;;N;;;;; -2F9AB;CJK COMPATIBILITY IDEOGRAPH-2F9AB;Lo;0;L;273CA;;;;N;;;;; -2F9AC;CJK COMPATIBILITY IDEOGRAPH-2F9AC;Lo;0;L;8564;;;;N;;;;; -2F9AD;CJK COMPATIBILITY IDEOGRAPH-2F9AD;Lo;0;L;26F2C;;;;N;;;;; -2F9AE;CJK COMPATIBILITY IDEOGRAPH-2F9AE;Lo;0;L;455D;;;;N;;;;; -2F9AF;CJK COMPATIBILITY IDEOGRAPH-2F9AF;Lo;0;L;4561;;;;N;;;;; -2F9B0;CJK COMPATIBILITY IDEOGRAPH-2F9B0;Lo;0;L;26FB1;;;;N;;;;; -2F9B1;CJK COMPATIBILITY IDEOGRAPH-2F9B1;Lo;0;L;270D2;;;;N;;;;; -2F9B2;CJK COMPATIBILITY IDEOGRAPH-2F9B2;Lo;0;L;456B;;;;N;;;;; -2F9B3;CJK COMPATIBILITY IDEOGRAPH-2F9B3;Lo;0;L;8650;;;;N;;;;; -2F9B4;CJK COMPATIBILITY IDEOGRAPH-2F9B4;Lo;0;L;865C;;;;N;;;;; -2F9B5;CJK COMPATIBILITY IDEOGRAPH-2F9B5;Lo;0;L;8667;;;;N;;;;; -2F9B6;CJK COMPATIBILITY IDEOGRAPH-2F9B6;Lo;0;L;8669;;;;N;;;;; -2F9B7;CJK COMPATIBILITY IDEOGRAPH-2F9B7;Lo;0;L;86A9;;;;N;;;;; -2F9B8;CJK COMPATIBILITY IDEOGRAPH-2F9B8;Lo;0;L;8688;;;;N;;;;; -2F9B9;CJK COMPATIBILITY IDEOGRAPH-2F9B9;Lo;0;L;870E;;;;N;;;;; -2F9BA;CJK COMPATIBILITY IDEOGRAPH-2F9BA;Lo;0;L;86E2;;;;N;;;;; -2F9BB;CJK COMPATIBILITY IDEOGRAPH-2F9BB;Lo;0;L;8779;;;;N;;;;; -2F9BC;CJK COMPATIBILITY IDEOGRAPH-2F9BC;Lo;0;L;8728;;;;N;;;;; -2F9BD;CJK COMPATIBILITY IDEOGRAPH-2F9BD;Lo;0;L;876B;;;;N;;;;; -2F9BE;CJK COMPATIBILITY IDEOGRAPH-2F9BE;Lo;0;L;8786;;;;N;;;;; -2F9BF;CJK COMPATIBILITY IDEOGRAPH-2F9BF;Lo;0;L;45D7;;;;N;;;;; -2F9C0;CJK COMPATIBILITY IDEOGRAPH-2F9C0;Lo;0;L;87E1;;;;N;;;;; -2F9C1;CJK COMPATIBILITY IDEOGRAPH-2F9C1;Lo;0;L;8801;;;;N;;;;; -2F9C2;CJK COMPATIBILITY IDEOGRAPH-2F9C2;Lo;0;L;45F9;;;;N;;;;; -2F9C3;CJK COMPATIBILITY IDEOGRAPH-2F9C3;Lo;0;L;8860;;;;N;;;;; -2F9C4;CJK COMPATIBILITY IDEOGRAPH-2F9C4;Lo;0;L;8863;;;;N;;;;; -2F9C5;CJK COMPATIBILITY IDEOGRAPH-2F9C5;Lo;0;L;27667;;;;N;;;;; -2F9C6;CJK COMPATIBILITY IDEOGRAPH-2F9C6;Lo;0;L;88D7;;;;N;;;;; -2F9C7;CJK COMPATIBILITY IDEOGRAPH-2F9C7;Lo;0;L;88DE;;;;N;;;;; -2F9C8;CJK COMPATIBILITY IDEOGRAPH-2F9C8;Lo;0;L;4635;;;;N;;;;; -2F9C9;CJK COMPATIBILITY IDEOGRAPH-2F9C9;Lo;0;L;88FA;;;;N;;;;; -2F9CA;CJK COMPATIBILITY IDEOGRAPH-2F9CA;Lo;0;L;34BB;;;;N;;;;; -2F9CB;CJK COMPATIBILITY IDEOGRAPH-2F9CB;Lo;0;L;278AE;;;;N;;;;; -2F9CC;CJK COMPATIBILITY IDEOGRAPH-2F9CC;Lo;0;L;27966;;;;N;;;;; -2F9CD;CJK COMPATIBILITY IDEOGRAPH-2F9CD;Lo;0;L;46BE;;;;N;;;;; -2F9CE;CJK COMPATIBILITY IDEOGRAPH-2F9CE;Lo;0;L;46C7;;;;N;;;;; -2F9CF;CJK COMPATIBILITY IDEOGRAPH-2F9CF;Lo;0;L;8AA0;;;;N;;;;; -2F9D0;CJK COMPATIBILITY IDEOGRAPH-2F9D0;Lo;0;L;8AED;;;;N;;;;; -2F9D1;CJK COMPATIBILITY IDEOGRAPH-2F9D1;Lo;0;L;8B8A;;;;N;;;;; -2F9D2;CJK COMPATIBILITY IDEOGRAPH-2F9D2;Lo;0;L;8C55;;;;N;;;;; -2F9D3;CJK COMPATIBILITY IDEOGRAPH-2F9D3;Lo;0;L;27CA8;;;;N;;;;; -2F9D4;CJK COMPATIBILITY IDEOGRAPH-2F9D4;Lo;0;L;8CAB;;;;N;;;;; -2F9D5;CJK COMPATIBILITY IDEOGRAPH-2F9D5;Lo;0;L;8CC1;;;;N;;;;; -2F9D6;CJK COMPATIBILITY IDEOGRAPH-2F9D6;Lo;0;L;8D1B;;;;N;;;;; -2F9D7;CJK COMPATIBILITY IDEOGRAPH-2F9D7;Lo;0;L;8D77;;;;N;;;;; -2F9D8;CJK COMPATIBILITY IDEOGRAPH-2F9D8;Lo;0;L;27F2F;;;;N;;;;; -2F9D9;CJK COMPATIBILITY IDEOGRAPH-2F9D9;Lo;0;L;20804;;;;N;;;;; -2F9DA;CJK COMPATIBILITY IDEOGRAPH-2F9DA;Lo;0;L;8DCB;;;;N;;;;; -2F9DB;CJK COMPATIBILITY IDEOGRAPH-2F9DB;Lo;0;L;8DBC;;;;N;;;;; -2F9DC;CJK COMPATIBILITY IDEOGRAPH-2F9DC;Lo;0;L;8DF0;;;;N;;;;; -2F9DD;CJK COMPATIBILITY IDEOGRAPH-2F9DD;Lo;0;L;208DE;;;;N;;;;; -2F9DE;CJK COMPATIBILITY IDEOGRAPH-2F9DE;Lo;0;L;8ED4;;;;N;;;;; -2F9DF;CJK COMPATIBILITY IDEOGRAPH-2F9DF;Lo;0;L;8F38;;;;N;;;;; -2F9E0;CJK COMPATIBILITY IDEOGRAPH-2F9E0;Lo;0;L;285D2;;;;N;;;;; -2F9E1;CJK COMPATIBILITY IDEOGRAPH-2F9E1;Lo;0;L;285ED;;;;N;;;;; -2F9E2;CJK COMPATIBILITY IDEOGRAPH-2F9E2;Lo;0;L;9094;;;;N;;;;; -2F9E3;CJK COMPATIBILITY IDEOGRAPH-2F9E3;Lo;0;L;90F1;;;;N;;;;; -2F9E4;CJK COMPATIBILITY IDEOGRAPH-2F9E4;Lo;0;L;9111;;;;N;;;;; -2F9E5;CJK COMPATIBILITY IDEOGRAPH-2F9E5;Lo;0;L;2872E;;;;N;;;;; -2F9E6;CJK COMPATIBILITY IDEOGRAPH-2F9E6;Lo;0;L;911B;;;;N;;;;; -2F9E7;CJK COMPATIBILITY IDEOGRAPH-2F9E7;Lo;0;L;9238;;;;N;;;;; -2F9E8;CJK COMPATIBILITY IDEOGRAPH-2F9E8;Lo;0;L;92D7;;;;N;;;;; -2F9E9;CJK COMPATIBILITY IDEOGRAPH-2F9E9;Lo;0;L;92D8;;;;N;;;;; -2F9EA;CJK COMPATIBILITY IDEOGRAPH-2F9EA;Lo;0;L;927C;;;;N;;;;; -2F9EB;CJK COMPATIBILITY IDEOGRAPH-2F9EB;Lo;0;L;93F9;;;;N;;;;; -2F9EC;CJK COMPATIBILITY IDEOGRAPH-2F9EC;Lo;0;L;9415;;;;N;;;;; -2F9ED;CJK COMPATIBILITY IDEOGRAPH-2F9ED;Lo;0;L;28BFA;;;;N;;;;; -2F9EE;CJK COMPATIBILITY IDEOGRAPH-2F9EE;Lo;0;L;958B;;;;N;;;;; -2F9EF;CJK COMPATIBILITY IDEOGRAPH-2F9EF;Lo;0;L;4995;;;;N;;;;; -2F9F0;CJK COMPATIBILITY IDEOGRAPH-2F9F0;Lo;0;L;95B7;;;;N;;;;; -2F9F1;CJK COMPATIBILITY IDEOGRAPH-2F9F1;Lo;0;L;28D77;;;;N;;;;; -2F9F2;CJK COMPATIBILITY IDEOGRAPH-2F9F2;Lo;0;L;49E6;;;;N;;;;; -2F9F3;CJK COMPATIBILITY IDEOGRAPH-2F9F3;Lo;0;L;96C3;;;;N;;;;; -2F9F4;CJK COMPATIBILITY IDEOGRAPH-2F9F4;Lo;0;L;5DB2;;;;N;;;;; -2F9F5;CJK COMPATIBILITY IDEOGRAPH-2F9F5;Lo;0;L;9723;;;;N;;;;; -2F9F6;CJK COMPATIBILITY IDEOGRAPH-2F9F6;Lo;0;L;29145;;;;N;;;;; -2F9F7;CJK COMPATIBILITY IDEOGRAPH-2F9F7;Lo;0;L;2921A;;;;N;;;;; -2F9F8;CJK COMPATIBILITY IDEOGRAPH-2F9F8;Lo;0;L;4A6E;;;;N;;;;; -2F9F9;CJK COMPATIBILITY IDEOGRAPH-2F9F9;Lo;0;L;4A76;;;;N;;;;; -2F9FA;CJK COMPATIBILITY IDEOGRAPH-2F9FA;Lo;0;L;97E0;;;;N;;;;; -2F9FB;CJK COMPATIBILITY IDEOGRAPH-2F9FB;Lo;0;L;2940A;;;;N;;;;; -2F9FC;CJK COMPATIBILITY IDEOGRAPH-2F9FC;Lo;0;L;4AB2;;;;N;;;;; -2F9FD;CJK COMPATIBILITY IDEOGRAPH-2F9FD;Lo;0;L;29496;;;;N;;;;; -2F9FE;CJK COMPATIBILITY IDEOGRAPH-2F9FE;Lo;0;L;980B;;;;N;;;;; -2F9FF;CJK COMPATIBILITY IDEOGRAPH-2F9FF;Lo;0;L;980B;;;;N;;;;; -2FA00;CJK COMPATIBILITY IDEOGRAPH-2FA00;Lo;0;L;9829;;;;N;;;;; -2FA01;CJK COMPATIBILITY IDEOGRAPH-2FA01;Lo;0;L;295B6;;;;N;;;;; -2FA02;CJK COMPATIBILITY IDEOGRAPH-2FA02;Lo;0;L;98E2;;;;N;;;;; -2FA03;CJK COMPATIBILITY IDEOGRAPH-2FA03;Lo;0;L;4B33;;;;N;;;;; -2FA04;CJK COMPATIBILITY IDEOGRAPH-2FA04;Lo;0;L;9929;;;;N;;;;; -2FA05;CJK COMPATIBILITY IDEOGRAPH-2FA05;Lo;0;L;99A7;;;;N;;;;; -2FA06;CJK COMPATIBILITY IDEOGRAPH-2FA06;Lo;0;L;99C2;;;;N;;;;; -2FA07;CJK COMPATIBILITY IDEOGRAPH-2FA07;Lo;0;L;99FE;;;;N;;;;; -2FA08;CJK COMPATIBILITY IDEOGRAPH-2FA08;Lo;0;L;4BCE;;;;N;;;;; -2FA09;CJK COMPATIBILITY IDEOGRAPH-2FA09;Lo;0;L;29B30;;;;N;;;;; -2FA0A;CJK COMPATIBILITY IDEOGRAPH-2FA0A;Lo;0;L;9B12;;;;N;;;;; -2FA0B;CJK COMPATIBILITY IDEOGRAPH-2FA0B;Lo;0;L;9C40;;;;N;;;;; -2FA0C;CJK COMPATIBILITY IDEOGRAPH-2FA0C;Lo;0;L;9CFD;;;;N;;;;; -2FA0D;CJK COMPATIBILITY IDEOGRAPH-2FA0D;Lo;0;L;4CCE;;;;N;;;;; -2FA0E;CJK COMPATIBILITY IDEOGRAPH-2FA0E;Lo;0;L;4CED;;;;N;;;;; -2FA0F;CJK COMPATIBILITY IDEOGRAPH-2FA0F;Lo;0;L;9D67;;;;N;;;;; -2FA10;CJK COMPATIBILITY IDEOGRAPH-2FA10;Lo;0;L;2A0CE;;;;N;;;;; -2FA11;CJK COMPATIBILITY IDEOGRAPH-2FA11;Lo;0;L;4CF8;;;;N;;;;; -2FA12;CJK COMPATIBILITY IDEOGRAPH-2FA12;Lo;0;L;2A105;;;;N;;;;; -2FA13;CJK COMPATIBILITY IDEOGRAPH-2FA13;Lo;0;L;2A20E;;;;N;;;;; -2FA14;CJK COMPATIBILITY IDEOGRAPH-2FA14;Lo;0;L;2A291;;;;N;;;;; -2FA15;CJK COMPATIBILITY IDEOGRAPH-2FA15;Lo;0;L;9EBB;;;;N;;;;; -2FA16;CJK COMPATIBILITY IDEOGRAPH-2FA16;Lo;0;L;4D56;;;;N;;;;; -2FA17;CJK COMPATIBILITY IDEOGRAPH-2FA17;Lo;0;L;9EF9;;;;N;;;;; -2FA18;CJK COMPATIBILITY IDEOGRAPH-2FA18;Lo;0;L;9EFE;;;;N;;;;; -2FA19;CJK COMPATIBILITY IDEOGRAPH-2FA19;Lo;0;L;9F05;;;;N;;;;; -2FA1A;CJK COMPATIBILITY IDEOGRAPH-2FA1A;Lo;0;L;9F0F;;;;N;;;;; -2FA1B;CJK COMPATIBILITY IDEOGRAPH-2FA1B;Lo;0;L;9F16;;;;N;;;;; -2FA1C;CJK COMPATIBILITY IDEOGRAPH-2FA1C;Lo;0;L;9F3B;;;;N;;;;; -2FA1D;CJK COMPATIBILITY IDEOGRAPH-2FA1D;Lo;0;L;2A600;;;;N;;;;; -E0001;LANGUAGE TAG;Cf;0;BN;;;;;N;;;;; -E0020;TAG SPACE;Cf;0;BN;;;;;N;;;;; -E0021;TAG EXCLAMATION MARK;Cf;0;BN;;;;;N;;;;; -E0022;TAG QUOTATION MARK;Cf;0;BN;;;;;N;;;;; -E0023;TAG NUMBER SIGN;Cf;0;BN;;;;;N;;;;; -E0024;TAG DOLLAR SIGN;Cf;0;BN;;;;;N;;;;; -E0025;TAG PERCENT SIGN;Cf;0;BN;;;;;N;;;;; -E0026;TAG AMPERSAND;Cf;0;BN;;;;;N;;;;; -E0027;TAG APOSTROPHE;Cf;0;BN;;;;;N;;;;; -E0028;TAG LEFT PARENTHESIS;Cf;0;BN;;;;;N;;;;; -E0029;TAG RIGHT PARENTHESIS;Cf;0;BN;;;;;N;;;;; -E002A;TAG ASTERISK;Cf;0;BN;;;;;N;;;;; -E002B;TAG PLUS SIGN;Cf;0;BN;;;;;N;;;;; -E002C;TAG COMMA;Cf;0;BN;;;;;N;;;;; -E002D;TAG HYPHEN-MINUS;Cf;0;BN;;;;;N;;;;; -E002E;TAG FULL STOP;Cf;0;BN;;;;;N;;;;; -E002F;TAG SOLIDUS;Cf;0;BN;;;;;N;;;;; -E0030;TAG DIGIT ZERO;Cf;0;BN;;;;;N;;;;; -E0031;TAG DIGIT ONE;Cf;0;BN;;;;;N;;;;; -E0032;TAG DIGIT TWO;Cf;0;BN;;;;;N;;;;; -E0033;TAG DIGIT THREE;Cf;0;BN;;;;;N;;;;; -E0034;TAG DIGIT FOUR;Cf;0;BN;;;;;N;;;;; -E0035;TAG DIGIT FIVE;Cf;0;BN;;;;;N;;;;; -E0036;TAG DIGIT SIX;Cf;0;BN;;;;;N;;;;; -E0037;TAG DIGIT SEVEN;Cf;0;BN;;;;;N;;;;; -E0038;TAG DIGIT EIGHT;Cf;0;BN;;;;;N;;;;; -E0039;TAG DIGIT NINE;Cf;0;BN;;;;;N;;;;; -E003A;TAG COLON;Cf;0;BN;;;;;N;;;;; -E003B;TAG SEMICOLON;Cf;0;BN;;;;;N;;;;; -E003C;TAG LESS-THAN SIGN;Cf;0;BN;;;;;N;;;;; -E003D;TAG EQUALS SIGN;Cf;0;BN;;;;;N;;;;; -E003E;TAG GREATER-THAN SIGN;Cf;0;BN;;;;;N;;;;; -E003F;TAG QUESTION MARK;Cf;0;BN;;;;;N;;;;; -E0040;TAG COMMERCIAL AT;Cf;0;BN;;;;;N;;;;; -E0041;TAG LATIN CAPITAL LETTER A;Cf;0;BN;;;;;N;;;;; -E0042;TAG LATIN CAPITAL LETTER B;Cf;0;BN;;;;;N;;;;; -E0043;TAG LATIN CAPITAL LETTER C;Cf;0;BN;;;;;N;;;;; -E0044;TAG LATIN CAPITAL LETTER D;Cf;0;BN;;;;;N;;;;; -E0045;TAG LATIN CAPITAL LETTER E;Cf;0;BN;;;;;N;;;;; -E0046;TAG LATIN CAPITAL LETTER F;Cf;0;BN;;;;;N;;;;; -E0047;TAG LATIN CAPITAL LETTER G;Cf;0;BN;;;;;N;;;;; -E0048;TAG LATIN CAPITAL LETTER H;Cf;0;BN;;;;;N;;;;; -E0049;TAG LATIN CAPITAL LETTER I;Cf;0;BN;;;;;N;;;;; -E004A;TAG LATIN CAPITAL LETTER J;Cf;0;BN;;;;;N;;;;; -E004B;TAG LATIN CAPITAL LETTER K;Cf;0;BN;;;;;N;;;;; -E004C;TAG LATIN CAPITAL LETTER L;Cf;0;BN;;;;;N;;;;; -E004D;TAG LATIN CAPITAL LETTER M;Cf;0;BN;;;;;N;;;;; -E004E;TAG LATIN CAPITAL LETTER N;Cf;0;BN;;;;;N;;;;; -E004F;TAG LATIN CAPITAL LETTER O;Cf;0;BN;;;;;N;;;;; -E0050;TAG LATIN CAPITAL LETTER P;Cf;0;BN;;;;;N;;;;; -E0051;TAG LATIN CAPITAL LETTER Q;Cf;0;BN;;;;;N;;;;; -E0052;TAG LATIN CAPITAL LETTER R;Cf;0;BN;;;;;N;;;;; -E0053;TAG LATIN CAPITAL LETTER S;Cf;0;BN;;;;;N;;;;; -E0054;TAG LATIN CAPITAL LETTER T;Cf;0;BN;;;;;N;;;;; -E0055;TAG LATIN CAPITAL LETTER U;Cf;0;BN;;;;;N;;;;; -E0056;TAG LATIN CAPITAL LETTER V;Cf;0;BN;;;;;N;;;;; -E0057;TAG LATIN CAPITAL LETTER W;Cf;0;BN;;;;;N;;;;; -E0058;TAG LATIN CAPITAL LETTER X;Cf;0;BN;;;;;N;;;;; -E0059;TAG LATIN CAPITAL LETTER Y;Cf;0;BN;;;;;N;;;;; -E005A;TAG LATIN CAPITAL LETTER Z;Cf;0;BN;;;;;N;;;;; -E005B;TAG LEFT SQUARE BRACKET;Cf;0;BN;;;;;N;;;;; -E005C;TAG REVERSE SOLIDUS;Cf;0;BN;;;;;N;;;;; -E005D;TAG RIGHT SQUARE BRACKET;Cf;0;BN;;;;;N;;;;; -E005E;TAG CIRCUMFLEX ACCENT;Cf;0;BN;;;;;N;;;;; -E005F;TAG LOW LINE;Cf;0;BN;;;;;N;;;;; -E0060;TAG GRAVE ACCENT;Cf;0;BN;;;;;N;;;;; -E0061;TAG LATIN SMALL LETTER A;Cf;0;BN;;;;;N;;;;; -E0062;TAG LATIN SMALL LETTER B;Cf;0;BN;;;;;N;;;;; -E0063;TAG LATIN SMALL LETTER C;Cf;0;BN;;;;;N;;;;; -E0064;TAG LATIN SMALL LETTER D;Cf;0;BN;;;;;N;;;;; -E0065;TAG LATIN SMALL LETTER E;Cf;0;BN;;;;;N;;;;; -E0066;TAG LATIN SMALL LETTER F;Cf;0;BN;;;;;N;;;;; -E0067;TAG LATIN SMALL LETTER G;Cf;0;BN;;;;;N;;;;; -E0068;TAG LATIN SMALL LETTER H;Cf;0;BN;;;;;N;;;;; -E0069;TAG LATIN SMALL LETTER I;Cf;0;BN;;;;;N;;;;; -E006A;TAG LATIN SMALL LETTER J;Cf;0;BN;;;;;N;;;;; -E006B;TAG LATIN SMALL LETTER K;Cf;0;BN;;;;;N;;;;; -E006C;TAG LATIN SMALL LETTER L;Cf;0;BN;;;;;N;;;;; -E006D;TAG LATIN SMALL LETTER M;Cf;0;BN;;;;;N;;;;; -E006E;TAG LATIN SMALL LETTER N;Cf;0;BN;;;;;N;;;;; -E006F;TAG LATIN SMALL LETTER O;Cf;0;BN;;;;;N;;;;; -E0070;TAG LATIN SMALL LETTER P;Cf;0;BN;;;;;N;;;;; -E0071;TAG LATIN SMALL LETTER Q;Cf;0;BN;;;;;N;;;;; -E0072;TAG LATIN SMALL LETTER R;Cf;0;BN;;;;;N;;;;; -E0073;TAG LATIN SMALL LETTER S;Cf;0;BN;;;;;N;;;;; -E0074;TAG LATIN SMALL LETTER T;Cf;0;BN;;;;;N;;;;; -E0075;TAG LATIN SMALL LETTER U;Cf;0;BN;;;;;N;;;;; -E0076;TAG LATIN SMALL LETTER V;Cf;0;BN;;;;;N;;;;; -E0077;TAG LATIN SMALL LETTER W;Cf;0;BN;;;;;N;;;;; -E0078;TAG LATIN SMALL LETTER X;Cf;0;BN;;;;;N;;;;; -E0079;TAG LATIN SMALL LETTER Y;Cf;0;BN;;;;;N;;;;; -E007A;TAG LATIN SMALL LETTER Z;Cf;0;BN;;;;;N;;;;; -E007B;TAG LEFT CURLY BRACKET;Cf;0;BN;;;;;N;;;;; -E007C;TAG VERTICAL LINE;Cf;0;BN;;;;;N;;;;; -E007D;TAG RIGHT CURLY BRACKET;Cf;0;BN;;;;;N;;;;; -E007E;TAG TILDE;Cf;0;BN;;;;;N;;;;; -E007F;CANCEL TAG;Cf;0;BN;;;;;N;;;;; -E0100;VARIATION SELECTOR-17;Mn;0;NSM;;;;;N;;;;; -E0101;VARIATION SELECTOR-18;Mn;0;NSM;;;;;N;;;;; -E0102;VARIATION SELECTOR-19;Mn;0;NSM;;;;;N;;;;; -E0103;VARIATION SELECTOR-20;Mn;0;NSM;;;;;N;;;;; -E0104;VARIATION SELECTOR-21;Mn;0;NSM;;;;;N;;;;; -E0105;VARIATION SELECTOR-22;Mn;0;NSM;;;;;N;;;;; -E0106;VARIATION SELECTOR-23;Mn;0;NSM;;;;;N;;;;; -E0107;VARIATION SELECTOR-24;Mn;0;NSM;;;;;N;;;;; -E0108;VARIATION SELECTOR-25;Mn;0;NSM;;;;;N;;;;; -E0109;VARIATION SELECTOR-26;Mn;0;NSM;;;;;N;;;;; -E010A;VARIATION SELECTOR-27;Mn;0;NSM;;;;;N;;;;; -E010B;VARIATION SELECTOR-28;Mn;0;NSM;;;;;N;;;;; -E010C;VARIATION SELECTOR-29;Mn;0;NSM;;;;;N;;;;; -E010D;VARIATION SELECTOR-30;Mn;0;NSM;;;;;N;;;;; -E010E;VARIATION SELECTOR-31;Mn;0;NSM;;;;;N;;;;; -E010F;VARIATION SELECTOR-32;Mn;0;NSM;;;;;N;;;;; -E0110;VARIATION SELECTOR-33;Mn;0;NSM;;;;;N;;;;; -E0111;VARIATION SELECTOR-34;Mn;0;NSM;;;;;N;;;;; -E0112;VARIATION SELECTOR-35;Mn;0;NSM;;;;;N;;;;; -E0113;VARIATION SELECTOR-36;Mn;0;NSM;;;;;N;;;;; -E0114;VARIATION SELECTOR-37;Mn;0;NSM;;;;;N;;;;; -E0115;VARIATION SELECTOR-38;Mn;0;NSM;;;;;N;;;;; -E0116;VARIATION SELECTOR-39;Mn;0;NSM;;;;;N;;;;; -E0117;VARIATION SELECTOR-40;Mn;0;NSM;;;;;N;;;;; -E0118;VARIATION SELECTOR-41;Mn;0;NSM;;;;;N;;;;; -E0119;VARIATION SELECTOR-42;Mn;0;NSM;;;;;N;;;;; -E011A;VARIATION SELECTOR-43;Mn;0;NSM;;;;;N;;;;; -E011B;VARIATION SELECTOR-44;Mn;0;NSM;;;;;N;;;;; -E011C;VARIATION SELECTOR-45;Mn;0;NSM;;;;;N;;;;; -E011D;VARIATION SELECTOR-46;Mn;0;NSM;;;;;N;;;;; -E011E;VARIATION SELECTOR-47;Mn;0;NSM;;;;;N;;;;; -E011F;VARIATION SELECTOR-48;Mn;0;NSM;;;;;N;;;;; -E0120;VARIATION SELECTOR-49;Mn;0;NSM;;;;;N;;;;; -E0121;VARIATION SELECTOR-50;Mn;0;NSM;;;;;N;;;;; -E0122;VARIATION SELECTOR-51;Mn;0;NSM;;;;;N;;;;; -E0123;VARIATION SELECTOR-52;Mn;0;NSM;;;;;N;;;;; -E0124;VARIATION SELECTOR-53;Mn;0;NSM;;;;;N;;;;; -E0125;VARIATION SELECTOR-54;Mn;0;NSM;;;;;N;;;;; -E0126;VARIATION SELECTOR-55;Mn;0;NSM;;;;;N;;;;; -E0127;VARIATION SELECTOR-56;Mn;0;NSM;;;;;N;;;;; -E0128;VARIATION SELECTOR-57;Mn;0;NSM;;;;;N;;;;; -E0129;VARIATION SELECTOR-58;Mn;0;NSM;;;;;N;;;;; -E012A;VARIATION SELECTOR-59;Mn;0;NSM;;;;;N;;;;; -E012B;VARIATION SELECTOR-60;Mn;0;NSM;;;;;N;;;;; -E012C;VARIATION SELECTOR-61;Mn;0;NSM;;;;;N;;;;; -E012D;VARIATION SELECTOR-62;Mn;0;NSM;;;;;N;;;;; -E012E;VARIATION SELECTOR-63;Mn;0;NSM;;;;;N;;;;; -E012F;VARIATION SELECTOR-64;Mn;0;NSM;;;;;N;;;;; -E0130;VARIATION SELECTOR-65;Mn;0;NSM;;;;;N;;;;; -E0131;VARIATION SELECTOR-66;Mn;0;NSM;;;;;N;;;;; -E0132;VARIATION SELECTOR-67;Mn;0;NSM;;;;;N;;;;; -E0133;VARIATION SELECTOR-68;Mn;0;NSM;;;;;N;;;;; -E0134;VARIATION SELECTOR-69;Mn;0;NSM;;;;;N;;;;; -E0135;VARIATION SELECTOR-70;Mn;0;NSM;;;;;N;;;;; -E0136;VARIATION SELECTOR-71;Mn;0;NSM;;;;;N;;;;; -E0137;VARIATION SELECTOR-72;Mn;0;NSM;;;;;N;;;;; -E0138;VARIATION SELECTOR-73;Mn;0;NSM;;;;;N;;;;; -E0139;VARIATION SELECTOR-74;Mn;0;NSM;;;;;N;;;;; -E013A;VARIATION SELECTOR-75;Mn;0;NSM;;;;;N;;;;; -E013B;VARIATION SELECTOR-76;Mn;0;NSM;;;;;N;;;;; -E013C;VARIATION SELECTOR-77;Mn;0;NSM;;;;;N;;;;; -E013D;VARIATION SELECTOR-78;Mn;0;NSM;;;;;N;;;;; -E013E;VARIATION SELECTOR-79;Mn;0;NSM;;;;;N;;;;; -E013F;VARIATION SELECTOR-80;Mn;0;NSM;;;;;N;;;;; -E0140;VARIATION SELECTOR-81;Mn;0;NSM;;;;;N;;;;; -E0141;VARIATION SELECTOR-82;Mn;0;NSM;;;;;N;;;;; -E0142;VARIATION SELECTOR-83;Mn;0;NSM;;;;;N;;;;; -E0143;VARIATION SELECTOR-84;Mn;0;NSM;;;;;N;;;;; -E0144;VARIATION SELECTOR-85;Mn;0;NSM;;;;;N;;;;; -E0145;VARIATION SELECTOR-86;Mn;0;NSM;;;;;N;;;;; -E0146;VARIATION SELECTOR-87;Mn;0;NSM;;;;;N;;;;; -E0147;VARIATION SELECTOR-88;Mn;0;NSM;;;;;N;;;;; -E0148;VARIATION SELECTOR-89;Mn;0;NSM;;;;;N;;;;; -E0149;VARIATION SELECTOR-90;Mn;0;NSM;;;;;N;;;;; -E014A;VARIATION SELECTOR-91;Mn;0;NSM;;;;;N;;;;; -E014B;VARIATION SELECTOR-92;Mn;0;NSM;;;;;N;;;;; -E014C;VARIATION SELECTOR-93;Mn;0;NSM;;;;;N;;;;; -E014D;VARIATION SELECTOR-94;Mn;0;NSM;;;;;N;;;;; -E014E;VARIATION SELECTOR-95;Mn;0;NSM;;;;;N;;;;; -E014F;VARIATION SELECTOR-96;Mn;0;NSM;;;;;N;;;;; -E0150;VARIATION SELECTOR-97;Mn;0;NSM;;;;;N;;;;; -E0151;VARIATION SELECTOR-98;Mn;0;NSM;;;;;N;;;;; -E0152;VARIATION SELECTOR-99;Mn;0;NSM;;;;;N;;;;; -E0153;VARIATION SELECTOR-100;Mn;0;NSM;;;;;N;;;;; -E0154;VARIATION SELECTOR-101;Mn;0;NSM;;;;;N;;;;; -E0155;VARIATION SELECTOR-102;Mn;0;NSM;;;;;N;;;;; -E0156;VARIATION SELECTOR-103;Mn;0;NSM;;;;;N;;;;; -E0157;VARIATION SELECTOR-104;Mn;0;NSM;;;;;N;;;;; -E0158;VARIATION SELECTOR-105;Mn;0;NSM;;;;;N;;;;; -E0159;VARIATION SELECTOR-106;Mn;0;NSM;;;;;N;;;;; -E015A;VARIATION SELECTOR-107;Mn;0;NSM;;;;;N;;;;; -E015B;VARIATION SELECTOR-108;Mn;0;NSM;;;;;N;;;;; -E015C;VARIATION SELECTOR-109;Mn;0;NSM;;;;;N;;;;; -E015D;VARIATION SELECTOR-110;Mn;0;NSM;;;;;N;;;;; -E015E;VARIATION SELECTOR-111;Mn;0;NSM;;;;;N;;;;; -E015F;VARIATION SELECTOR-112;Mn;0;NSM;;;;;N;;;;; -E0160;VARIATION SELECTOR-113;Mn;0;NSM;;;;;N;;;;; -E0161;VARIATION SELECTOR-114;Mn;0;NSM;;;;;N;;;;; -E0162;VARIATION SELECTOR-115;Mn;0;NSM;;;;;N;;;;; -E0163;VARIATION SELECTOR-116;Mn;0;NSM;;;;;N;;;;; -E0164;VARIATION SELECTOR-117;Mn;0;NSM;;;;;N;;;;; -E0165;VARIATION SELECTOR-118;Mn;0;NSM;;;;;N;;;;; -E0166;VARIATION SELECTOR-119;Mn;0;NSM;;;;;N;;;;; -E0167;VARIATION SELECTOR-120;Mn;0;NSM;;;;;N;;;;; -E0168;VARIATION SELECTOR-121;Mn;0;NSM;;;;;N;;;;; -E0169;VARIATION SELECTOR-122;Mn;0;NSM;;;;;N;;;;; -E016A;VARIATION SELECTOR-123;Mn;0;NSM;;;;;N;;;;; -E016B;VARIATION SELECTOR-124;Mn;0;NSM;;;;;N;;;;; -E016C;VARIATION SELECTOR-125;Mn;0;NSM;;;;;N;;;;; -E016D;VARIATION SELECTOR-126;Mn;0;NSM;;;;;N;;;;; -E016E;VARIATION SELECTOR-127;Mn;0;NSM;;;;;N;;;;; -E016F;VARIATION SELECTOR-128;Mn;0;NSM;;;;;N;;;;; -E0170;VARIATION SELECTOR-129;Mn;0;NSM;;;;;N;;;;; -E0171;VARIATION SELECTOR-130;Mn;0;NSM;;;;;N;;;;; -E0172;VARIATION SELECTOR-131;Mn;0;NSM;;;;;N;;;;; -E0173;VARIATION SELECTOR-132;Mn;0;NSM;;;;;N;;;;; -E0174;VARIATION SELECTOR-133;Mn;0;NSM;;;;;N;;;;; -E0175;VARIATION SELECTOR-134;Mn;0;NSM;;;;;N;;;;; -E0176;VARIATION SELECTOR-135;Mn;0;NSM;;;;;N;;;;; -E0177;VARIATION SELECTOR-136;Mn;0;NSM;;;;;N;;;;; -E0178;VARIATION SELECTOR-137;Mn;0;NSM;;;;;N;;;;; -E0179;VARIATION SELECTOR-138;Mn;0;NSM;;;;;N;;;;; -E017A;VARIATION SELECTOR-139;Mn;0;NSM;;;;;N;;;;; -E017B;VARIATION SELECTOR-140;Mn;0;NSM;;;;;N;;;;; -E017C;VARIATION SELECTOR-141;Mn;0;NSM;;;;;N;;;;; -E017D;VARIATION SELECTOR-142;Mn;0;NSM;;;;;N;;;;; -E017E;VARIATION SELECTOR-143;Mn;0;NSM;;;;;N;;;;; -E017F;VARIATION SELECTOR-144;Mn;0;NSM;;;;;N;;;;; -E0180;VARIATION SELECTOR-145;Mn;0;NSM;;;;;N;;;;; -E0181;VARIATION SELECTOR-146;Mn;0;NSM;;;;;N;;;;; -E0182;VARIATION SELECTOR-147;Mn;0;NSM;;;;;N;;;;; -E0183;VARIATION SELECTOR-148;Mn;0;NSM;;;;;N;;;;; -E0184;VARIATION SELECTOR-149;Mn;0;NSM;;;;;N;;;;; -E0185;VARIATION SELECTOR-150;Mn;0;NSM;;;;;N;;;;; -E0186;VARIATION SELECTOR-151;Mn;0;NSM;;;;;N;;;;; -E0187;VARIATION SELECTOR-152;Mn;0;NSM;;;;;N;;;;; -E0188;VARIATION SELECTOR-153;Mn;0;NSM;;;;;N;;;;; -E0189;VARIATION SELECTOR-154;Mn;0;NSM;;;;;N;;;;; -E018A;VARIATION SELECTOR-155;Mn;0;NSM;;;;;N;;;;; -E018B;VARIATION SELECTOR-156;Mn;0;NSM;;;;;N;;;;; -E018C;VARIATION SELECTOR-157;Mn;0;NSM;;;;;N;;;;; -E018D;VARIATION SELECTOR-158;Mn;0;NSM;;;;;N;;;;; -E018E;VARIATION SELECTOR-159;Mn;0;NSM;;;;;N;;;;; -E018F;VARIATION SELECTOR-160;Mn;0;NSM;;;;;N;;;;; -E0190;VARIATION SELECTOR-161;Mn;0;NSM;;;;;N;;;;; -E0191;VARIATION SELECTOR-162;Mn;0;NSM;;;;;N;;;;; -E0192;VARIATION SELECTOR-163;Mn;0;NSM;;;;;N;;;;; -E0193;VARIATION SELECTOR-164;Mn;0;NSM;;;;;N;;;;; -E0194;VARIATION SELECTOR-165;Mn;0;NSM;;;;;N;;;;; -E0195;VARIATION SELECTOR-166;Mn;0;NSM;;;;;N;;;;; -E0196;VARIATION SELECTOR-167;Mn;0;NSM;;;;;N;;;;; -E0197;VARIATION SELECTOR-168;Mn;0;NSM;;;;;N;;;;; -E0198;VARIATION SELECTOR-169;Mn;0;NSM;;;;;N;;;;; -E0199;VARIATION SELECTOR-170;Mn;0;NSM;;;;;N;;;;; -E019A;VARIATION SELECTOR-171;Mn;0;NSM;;;;;N;;;;; -E019B;VARIATION SELECTOR-172;Mn;0;NSM;;;;;N;;;;; -E019C;VARIATION SELECTOR-173;Mn;0;NSM;;;;;N;;;;; -E019D;VARIATION SELECTOR-174;Mn;0;NSM;;;;;N;;;;; -E019E;VARIATION SELECTOR-175;Mn;0;NSM;;;;;N;;;;; -E019F;VARIATION SELECTOR-176;Mn;0;NSM;;;;;N;;;;; -E01A0;VARIATION SELECTOR-177;Mn;0;NSM;;;;;N;;;;; -E01A1;VARIATION SELECTOR-178;Mn;0;NSM;;;;;N;;;;; -E01A2;VARIATION SELECTOR-179;Mn;0;NSM;;;;;N;;;;; -E01A3;VARIATION SELECTOR-180;Mn;0;NSM;;;;;N;;;;; -E01A4;VARIATION SELECTOR-181;Mn;0;NSM;;;;;N;;;;; -E01A5;VARIATION SELECTOR-182;Mn;0;NSM;;;;;N;;;;; -E01A6;VARIATION SELECTOR-183;Mn;0;NSM;;;;;N;;;;; -E01A7;VARIATION SELECTOR-184;Mn;0;NSM;;;;;N;;;;; -E01A8;VARIATION SELECTOR-185;Mn;0;NSM;;;;;N;;;;; -E01A9;VARIATION SELECTOR-186;Mn;0;NSM;;;;;N;;;;; -E01AA;VARIATION SELECTOR-187;Mn;0;NSM;;;;;N;;;;; -E01AB;VARIATION SELECTOR-188;Mn;0;NSM;;;;;N;;;;; -E01AC;VARIATION SELECTOR-189;Mn;0;NSM;;;;;N;;;;; -E01AD;VARIATION SELECTOR-190;Mn;0;NSM;;;;;N;;;;; -E01AE;VARIATION SELECTOR-191;Mn;0;NSM;;;;;N;;;;; -E01AF;VARIATION SELECTOR-192;Mn;0;NSM;;;;;N;;;;; -E01B0;VARIATION SELECTOR-193;Mn;0;NSM;;;;;N;;;;; -E01B1;VARIATION SELECTOR-194;Mn;0;NSM;;;;;N;;;;; -E01B2;VARIATION SELECTOR-195;Mn;0;NSM;;;;;N;;;;; -E01B3;VARIATION SELECTOR-196;Mn;0;NSM;;;;;N;;;;; -E01B4;VARIATION SELECTOR-197;Mn;0;NSM;;;;;N;;;;; -E01B5;VARIATION SELECTOR-198;Mn;0;NSM;;;;;N;;;;; -E01B6;VARIATION SELECTOR-199;Mn;0;NSM;;;;;N;;;;; -E01B7;VARIATION SELECTOR-200;Mn;0;NSM;;;;;N;;;;; -E01B8;VARIATION SELECTOR-201;Mn;0;NSM;;;;;N;;;;; -E01B9;VARIATION SELECTOR-202;Mn;0;NSM;;;;;N;;;;; -E01BA;VARIATION SELECTOR-203;Mn;0;NSM;;;;;N;;;;; -E01BB;VARIATION SELECTOR-204;Mn;0;NSM;;;;;N;;;;; -E01BC;VARIATION SELECTOR-205;Mn;0;NSM;;;;;N;;;;; -E01BD;VARIATION SELECTOR-206;Mn;0;NSM;;;;;N;;;;; -E01BE;VARIATION SELECTOR-207;Mn;0;NSM;;;;;N;;;;; -E01BF;VARIATION SELECTOR-208;Mn;0;NSM;;;;;N;;;;; -E01C0;VARIATION SELECTOR-209;Mn;0;NSM;;;;;N;;;;; -E01C1;VARIATION SELECTOR-210;Mn;0;NSM;;;;;N;;;;; -E01C2;VARIATION SELECTOR-211;Mn;0;NSM;;;;;N;;;;; -E01C3;VARIATION SELECTOR-212;Mn;0;NSM;;;;;N;;;;; -E01C4;VARIATION SELECTOR-213;Mn;0;NSM;;;;;N;;;;; -E01C5;VARIATION SELECTOR-214;Mn;0;NSM;;;;;N;;;;; -E01C6;VARIATION SELECTOR-215;Mn;0;NSM;;;;;N;;;;; -E01C7;VARIATION SELECTOR-216;Mn;0;NSM;;;;;N;;;;; -E01C8;VARIATION SELECTOR-217;Mn;0;NSM;;;;;N;;;;; -E01C9;VARIATION SELECTOR-218;Mn;0;NSM;;;;;N;;;;; -E01CA;VARIATION SELECTOR-219;Mn;0;NSM;;;;;N;;;;; -E01CB;VARIATION SELECTOR-220;Mn;0;NSM;;;;;N;;;;; -E01CC;VARIATION SELECTOR-221;Mn;0;NSM;;;;;N;;;;; -E01CD;VARIATION SELECTOR-222;Mn;0;NSM;;;;;N;;;;; -E01CE;VARIATION SELECTOR-223;Mn;0;NSM;;;;;N;;;;; -E01CF;VARIATION SELECTOR-224;Mn;0;NSM;;;;;N;;;;; -E01D0;VARIATION SELECTOR-225;Mn;0;NSM;;;;;N;;;;; -E01D1;VARIATION SELECTOR-226;Mn;0;NSM;;;;;N;;;;; -E01D2;VARIATION SELECTOR-227;Mn;0;NSM;;;;;N;;;;; -E01D3;VARIATION SELECTOR-228;Mn;0;NSM;;;;;N;;;;; -E01D4;VARIATION SELECTOR-229;Mn;0;NSM;;;;;N;;;;; -E01D5;VARIATION SELECTOR-230;Mn;0;NSM;;;;;N;;;;; -E01D6;VARIATION SELECTOR-231;Mn;0;NSM;;;;;N;;;;; -E01D7;VARIATION SELECTOR-232;Mn;0;NSM;;;;;N;;;;; -E01D8;VARIATION SELECTOR-233;Mn;0;NSM;;;;;N;;;;; -E01D9;VARIATION SELECTOR-234;Mn;0;NSM;;;;;N;;;;; -E01DA;VARIATION SELECTOR-235;Mn;0;NSM;;;;;N;;;;; -E01DB;VARIATION SELECTOR-236;Mn;0;NSM;;;;;N;;;;; -E01DC;VARIATION SELECTOR-237;Mn;0;NSM;;;;;N;;;;; -E01DD;VARIATION SELECTOR-238;Mn;0;NSM;;;;;N;;;;; -E01DE;VARIATION SELECTOR-239;Mn;0;NSM;;;;;N;;;;; -E01DF;VARIATION SELECTOR-240;Mn;0;NSM;;;;;N;;;;; -E01E0;VARIATION SELECTOR-241;Mn;0;NSM;;;;;N;;;;; -E01E1;VARIATION SELECTOR-242;Mn;0;NSM;;;;;N;;;;; -E01E2;VARIATION SELECTOR-243;Mn;0;NSM;;;;;N;;;;; -E01E3;VARIATION SELECTOR-244;Mn;0;NSM;;;;;N;;;;; -E01E4;VARIATION SELECTOR-245;Mn;0;NSM;;;;;N;;;;; -E01E5;VARIATION SELECTOR-246;Mn;0;NSM;;;;;N;;;;; -E01E6;VARIATION SELECTOR-247;Mn;0;NSM;;;;;N;;;;; -E01E7;VARIATION SELECTOR-248;Mn;0;NSM;;;;;N;;;;; -E01E8;VARIATION SELECTOR-249;Mn;0;NSM;;;;;N;;;;; -E01E9;VARIATION SELECTOR-250;Mn;0;NSM;;;;;N;;;;; -E01EA;VARIATION SELECTOR-251;Mn;0;NSM;;;;;N;;;;; -E01EB;VARIATION SELECTOR-252;Mn;0;NSM;;;;;N;;;;; -E01EC;VARIATION SELECTOR-253;Mn;0;NSM;;;;;N;;;;; -E01ED;VARIATION SELECTOR-254;Mn;0;NSM;;;;;N;;;;; -E01EE;VARIATION SELECTOR-255;Mn;0;NSM;;;;;N;;;;; -E01EF;VARIATION SELECTOR-256;Mn;0;NSM;;;;;N;;;;; -F0000;;Co;0;L;;;;;N;;;;; -FFFFD;;Co;0;L;;;;;N;;;;; -100000;;Co;0;L;;;;;N;;;;; -10FFFD;;Co;0;L;;;;;N;;;;; diff --git a/admin/unidata/copyright.html b/admin/unidata/copyright.html deleted file mode 100644 index 57a6d3945c1..00000000000 --- a/admin/unidata/copyright.html +++ /dev/null @@ -1,345 +0,0 @@ - - - - - - - - - - - - - - - - - - -Unicode Terms of Use - - - - - - - - - - - -

- - - - - - - - - - - - - - - -
- - - - - - - - -
[Unicode]  Terms of - UseHome - | Site Map | - Search
-
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Contents
Unicode Copyright
Restricted Rights - Legend
Warranties & - Disclaimers
Waiver of Damages
Trademarks
Miscellaneous
Data Files and - Software License Agreement (Exhibit 1)
 
- - - - - - - - - - - - - -
Related Links
- The - Unicode® Consortium Trademarks and Logo Policy
- Unicode - Policies
- - - - - 		- -
-

Unicode Terms of Use

- -

For the general privacy policy governing access to this site, see - the  - - Unicode Privacy Policy. For trademark usage, see - the - Unicode Consortium® Trademarks and Logo Policy.

- - - - - - - - - -
    -
  1. Unicode Copyright. -
      -
    1. Copyright © 1991-2006 Unicode, Inc. All rights reserved.
      2. -
    2. Certain documents and files on this website contain a legend - indicating that "Modification is permitted." Any person is - hereby authorized, without fee, to modify such documents and - files to create derivative works conforming to the Unicode® - Standard, subject to Terms and Conditions herein.
      3. -
    3. Any person is hereby authorized, without fee, to view, use, - reproduce, and distribute all documents and files solely for - informational purposes in the creation of products supporting - the Unicode Standard, subject to the Terms and Conditions - herein.
      4. -
    4. Further specifications of rights and restrictions pertaining - to the use of the particular set of data files known as the - "Unicode Character Database" can be found in - Exhibit 1.
      5. -
    5. Each version of the Unicode Standard has further specifications of rights and restrictions - of use. For the book editions, these are found on the back of - the - - title page. For the online edition, certain files (such as - the PDF files for book chapters and code charts) carry specific - restrictions. All other files are covered under these general - Terms of Use.  To request a permission to reproduce any - part of the Unicode Standard, please - contact the - Unicode Consortium.
      6. -
    6. No license is granted to "mirror" the Unicode website where - a fee is charged for access to the "mirror" site.
      7. -
    7. Modification is not permitted with respect to this document. - All copies of this document must be verbatim.
      8. -
    -
    2. -
  2. Restricted Rights Legend. Any technical - data or software which is licensed to the United States of - America, its agencies and/or instrumentalities under this - Agreement is commercial technical data or commercial computer - software developed exclusively at private expense as defined in - FAR 2.101, or DFARS 252.227-7014 (June 1995), as applicable. For - technical data, use, duplication, or disclosure by the Government - is subject to restrictions as set forth in DFARS 202.227-7015 - Technical Data, Commercial and Items (Nov 1995) and this - Agreement. For Software, in accordance with FAR 12-212 or DFARS - 227-7202, as applicable, use, duplication or disclosure by the - Government is subject to the restrictions set forth in this - Agreement.
    3. -
  3. Warranties and Disclaimers. -
      -
    1. This publication and/or website may include technical or - typographical errors or other inaccuracies . Changes are - periodically added to the information herein; these changes will - be incorporated in new editions of the publication and/or - website. Unicode may make improvements and/or changes in the - product(s) and/or program(s) described in this publication - and/or website at any time.
      2. -
    2. If this file has been purchased on magnetic or optical media - from Unicode, Inc. the sole and exclusive remedy for any claim - will be exchange of the defective media within ninety (90) days - of original purchase.
      3. -
    3. EXCEPT AS PROVIDED IN SECTION C.2, THIS PUBLICATION AND/OR - SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND EITHER - EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, - ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR - PURPOSE, OR NON-INFRINGEMENT. UNICODE AND ITS LICENSORS ASSUME - NO RESPONSIBILITY FOR ERRORS OR OMISSIONS IN THIS PUBLICATION - AND/OR SOFTWARE OR OTHER DOCUMENTS WHICH ARE REFERENCED BY OR - LINKED TO THIS PUBLICATION OR THE UNICODE WEBSITE.
      4. -
    -
    4. -
  4. Waiver of Damages. In no event shall - Unicode or its licensors be liable for any special, incidental, - indirect or consequential damages of any kind, or any damages - whatsoever, whether or not Unicode was advised of the possibility - of the damage, including, without limitation, those resulting from - the following: loss of use, data or profits, in connection with - the use, modification or distribution of this information or its - derivatives.
    5. -
  5. Trademarks. -
      -
    1. Unicode and the Unicode logo are registered trademarks of - Unicode, Inc. 
      2. -
    2. This site contains product names and corporate names of - other companies. All product names and company names and logos - mentioned herein are the trademarks or registered trademarks of - their respective owners. Other products and corporate names - mentioned herein which are trademarks of a third party are used - only for explanation and for the owners' benefit and with no - intent to infringe.
      3. -
    3. Use of third party products or information referred to - herein is at the user’s risk.
      4. -
    -
    6. - -
  6. Miscellaneous. -
      -
    1. Jurisdiction and Venue. This server is operated from - a location in the State of California, United States of America. - Unicode makes no representation that the materials are - appropriate for use in other locations. If you access this - server from other locations, you are responsible for compliance - with local laws. This Agreement, all use of this site and any - claims and damages resulting from use of this site are governed - solely by the laws of the State of California without regard to - any principles which would apply the laws of a different - jurisdiction. The user agrees that any disputes regarding this - site shall be resolved solely in the courts located in Santa - Clara County, California. The user agrees said courts have - personal jurisdiction and agree to waive any right to transfer - the dispute to any other forum.
      2. -
    2. Modification by Unicode Unicode shall have the right - to modify this Agreement at any time by posting it to this site. - The user may not assign any part of this Agreement without - Unicode’s prior written consent.
      3. -
    3. Taxes. The user agrees to pay any taxes arising from - access to this website or use of the information herein, except - for those based on Unicode’s net income.
      4. -
    4. Severability.  If any provision of this - Agreement is declared invalid or unenforceable, the remaining - provisions of this Agreement shall remain in effect.
      5. -
    5. Entire Agreement. This Agreement constitutes the - entire agreement between the parties. 
      6. -
    -
    7. -
-
-
- -

EXHIBIT 1
-UNICODE, INC. LICENSE AGREEMENT - DATA FILES AND SOFTWARE

-
-

Unicode Data Files include all data files under the directories -http://www.unicode.org/Public/, -http://www.unicode.org/reports/, -and - -http://www.unicode.org/cldr/data/ . Unicode Software includes any source code -published in the Unicode Standard or under the directories -http://www.unicode.org/Public/, -http://www.unicode.org/reports/, -and - -http://www.unicode.org/cldr/data/.

- -

NOTICE TO USER: Carefully read the following legal agreement. BY DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING UNICODE INC.'S DATA FILES ("DATA FILES"), AND/OR SOFTWARE ("SOFTWARE"), YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.

-

COPYRIGHT AND PERMISSION NOTICE

- -

Copyright © 1991-2005 Unicode, Inc. All rights reserved. Distributed under the Terms of Use in -http://www.unicode.org/copyright.html.

- -

Permission is hereby granted, free of charge, to any person obtaining a copy of the Unicode data files and -any associated documentation (the "Data Files") or Unicode software and any associated documentation (the "Software") to deal in the Data Files or Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Data Files or Software, and to permit persons to whom the Data Files or Software are furnished to do so, provided that (a) the above copyright notice(s) and this permission notice appear -with all copies of the Data Files or Software, (b) both the above copyright notice(s) and this permission notice appear in associated documentation, and (c) there is clear notice in each modified Data File or in the Software as well as in the documentation associated with the Data File(s) or Software that the data or software has been modified.

- -

THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -PERFORMANCE OF THE DATA FILES OR SOFTWARE.

- -

Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in these Data Files or Software without prior written authorization of the copyright holder.

- -
- -

Unicode and the Unicode logo are trademarks of Unicode, Inc., and may be registered in some jurisdictions. All other trademarks and registered trademarks mentioned herein are the property of their respective owners.

- - -
- - -
-
-
- - - - -
- Access to Copyright and terms of use
- - - -
-
- -
- - - - - - - - - - - - diff --git a/admin/unidata/makefile.w32-in b/admin/unidata/makefile.w32-in deleted file mode 100644 index 792c2c2d105..00000000000 --- a/admin/unidata/makefile.w32-in +++ /dev/null @@ -1,55 +0,0 @@ -# makefile.w32-in -- W32 -*- Makefile -*- to generate character property tables. -# Copyright (C) 2005, 2006, 2007, 2008, 2009 -# National Institute of Advanced Industrial Science and Technology (AIST) -# Registration Number H13PRO009 -# -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -EMACS = ../../src/$(BLD)/emacs.exe -DSTDIR = ../../lisp/international -lisp = $(CURDIR)/../../lisp -# EMACSLOADPATH should include international, so Emacs finds encoded-kb. -# It should include emacs-lisp, so Emacs finds bytecomp. This is because -# lisp/subdirs.el is not generated yet when the commands below run. -EMACSLOADPATH = $(lisp);$(lisp)/international;$(lisp)/emacs-lisp -# Quote EMACS so it could be a file name with embedded whitespace -RUNEMACS = "$(EMACS)" -Q --multibyte -batch - -all: $(DSTDIR)/charprop.el - -.el.elc: - $(RUNEMACS) -f batch-byte-compile $< - -unidata.txt: UnicodeData.txt - sed -e \ - $(ARGQUOTE)s/\([^;]*\);\(.*\)/(#x\1 $(DQUOTE)\2$(DQUOTE))/$(ARGQUOTE)\ - -e $(ARGQUOTE)s/;/$(DQUOTE) $(DQUOTE)/g$(ARGQUOTE) < UnicodeData.txt > $@ - -charprop-SH: unidata-gen.elc unidata.txt - ELC=$(CURDIR)/unidata-gen.elc; \ - DATA=$(CURDIR)/unidata.txt; \ - cd $(DSTDIR); \ - $(RUNEMACS) --load $${ELC} -f unidata-gen-files $${DATA} - -charprop-CMD: unidata-gen.elc unidata.txt - $(RUNEMACS) --eval $(ARGQUOTE)(cd $(DQUOTE)$(DSTDIR)$(DQUOTE))$(ARGQUOTE) --load $(CURDIR)/unidata-gen.elc -f unidata-gen-files $(CURDIR)/unidata.txt - -${DSTDIR}/charprop.el: charprop-$(SHELLTYPE) - -clean: - - $(DEL) unidata-gen.elc unidata.txt - diff --git a/admin/unidata/unidata-gen.el b/admin/unidata/unidata-gen.el deleted file mode 100644 index 9fee8e46c80..00000000000 --- a/admin/unidata/unidata-gen.el +++ /dev/null @@ -1,1238 +0,0 @@ -;; unidata-gen.el -- Create files containing character property data. -;; Copyright (C) 2005, 2006, 2007, 2008, 2009 -;; National Institute of Advanced Industrial Science and Technology (AIST) -;; Registration Number H13PRO009 - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; SPECIAL NOTICE -;; -;; This file must be byte-compilable/loadable by `temacs' and also -;; the entry function `unidata-gen-files' must be runnable by -;; `temacs'. - -;; FILES TO BE GENERATED -;; -;; The entry function `unidata-gen-files' generates these files in -;; the current directory. -;; -;; charprop.el -;; It contains a series of forms of this format: -;; (char-code-property-register PROP FILE) -;; where PROP is a symbol representing a character property -;; (name, generic-category, etc), and FILE is a name of one of -;; the following files. -;; -;; uni-name.el, uni-category.el, uni-combining.el, uni-bidi.el, -;; uni-decomposition.el, uni-decimal.el, uni-digit.el, uni-numeric.el, -;; uni-mirrored.el, uni-old-name.el, uni-comment.el, uni-uppercase.el, -;; uni-lowercase.el, uni-titlecase.el -;; They each contain a single form of this format: -;; (char-code-property-register PROP CHAR-TABLE) -;; where PROP is the same as above, and CHAR-TABLE is a -;; char-table containing property values in a compressed format. -;; -;; When they are installed in .../lisp/international/, the file -;; "charprop.el" is preloaded in loadup.el. The other files are -;; automatically loaded when the functions `get-char-code-property' -;; and `put-char-code-property' are called. -;; -;; FORMAT OF A CHAR TABLE -;; -;; We want to make a file size containing a char-table small. We -;; also want to load the file and get a property value fast. We -;; also want to reduce the used memory after loading it. So, -;; instead of naively storing a property value for each character in -;; a char-table (and write it out into a file), we store compressed -;; data in a char-table as below. -;; -;; If succeeding 128*N characters have the same property value, we -;; store that value for them. Otherwise, compress values for -;; succeeding 128 characters into a single string and store it as a -;; value for those characters. The way of compression depends on a -;; property. See the section "SIMPLE TABLE", "RUN-LENGTH TABLE", -;; and "WORD-LIST TABLE". - -;; The char table has four extra slots: -;; 1st: property symbol -;; 2nd: function to call to get a property value -;; 3nd: function to call to put a property value -;; 4th: function to call to get a description of a property value -;; 5th: data referred by the above functions - -;; List of elements of this form: -;; (CHAR-or-RANGE PROP1 PROP2 ... PROPn) -;; CHAR-or-RANGE: a character code or a cons of character codes -;; PROPn: string representing the nth property value - -(defvar unidata-list nil) - -(defun unidata-setup-list (unidata-text-file) - (let* ((table (list nil)) - (tail table) - (block-names '(("^;Lo;0;L;;;;;N;;;;; - ;; 9FA5;;Lo;0;L;;;;;N;;;;; - (if (and (= (aref name 0) ?<) - (string-match ", First>$" name)) - (let ((first char) - (l block-names) - block-name) - (setq val (read (current-buffer)) - char (car val) - block-name (cadr val) - name nil) - (while l - (if (string-match (caar l) block-name) - (setq name (cdar l) l nil) - (setq l (cdr l)))) - (if (not name) - ;; As this is a surrogate pair range, ignore it. - (setq val nil) - (setcar val (cons first char)) - (setcar (cdr val) name)))) - - (when val - (setcdr tail (list val)) - (setq tail (cdr tail)))) - (error nil))) - (setq unidata-list (cdr table)))) - -;; Alist of this form: -;; (PROP INDEX GENERATOR FILENAME) -;; PROP: character property -;; INDEX: index to each element of unidata-list for PROP -;; GENERATOR: function to generate a char-table -;; FILENAME: filename to store the char-table -;; DESCRIBER: function to call to get a description string of property value - -(defconst unidata-prop-alist - '((name - 1 unidata-gen-table-name "uni-name.el" - "Unicode character name. -Property value is a string.") - (general-category - 2 unidata-gen-table-symbol "uni-category.el" - "Unicode general category. -Property value is one of the following symbols: - Lu, Ll, Lt, Lm, Lo, Mn, Mc, Me, Nd, Nl, No, Pc, Pd, Ps, Pe, Pi, Pf, Po, - Sm, Sc, Sk, So, Zs, Zl, Zp, Cc, Cf, Cs, Co, Cn" - unidata-describe-general-category) - (canonical-combining-class - 3 unidata-gen-table-integer "uni-combining.el" - "Unicode canonical combining class. -Property value is an integer." - unidata-describe-canonical-combining-class) - (bidi-class - 4 unidata-gen-table-symbol "uni-bidi.el" - "Unicode bidi class. -Property value is one of the following symbols: - L, LRE, LRO, R, AL, RLE, RLO, PDF, EN, ES, ET, - AN, CS, NSM, BN, B, S, WS, ON" - unidata-describe-bidi-class) - (decomposition - 5 unidata-gen-table-decomposition "uni-decomposition.el" - "Unicode decomposition mapping. -Property value is a list of characters. The first element may be -one of these symbols representing compatibility formatting tag: - font, noBreak, initial, medial, final, isolated, circle, super, - sub, vertical, wide, narrow, small, square, fraction, compat" - unidata-describe-decomposition) - (decimal-digit-value - 6 unidata-gen-table-integer "uni-decimal.el" - "Unicode numeric value (decimal digit). -Property value is an integer.") - (digit-value - 7 unidata-gen-table-integer "uni-digit.el" - "Unicode numeric value (digit). -Property value is an integer.") - (numeric-value - 8 unidata-gen-table-numeric "uni-numeric.el" - "Unicode numeric value (numeric). -Property value is an integer or a floating point.") - (mirrored - 9 unidata-gen-table-symbol "uni-mirrored.el" - "Unicode bidi mirrored flag. -Property value is a symbol `Y' or `N'.") - (old-name - 10 unidata-gen-table-name "uni-old-name.el" - "Unicode old names as published in Unicode 1.0. -Property value is a string.") - (iso-10646-comment - 11 unidata-gen-table-name "uni-comment.el" - "Unicode ISO 10646 comment. -Property value is a string.") - (uppercase - 12 unidata-gen-table-character "uni-uppercase.el" - "Unicode simple uppercase mapping. -Property value is a character." - string) - (lowercase - 13 unidata-gen-table-character "uni-lowercase.el" - "Unicode simple lowercase mapping. -Property value is a character." - string) - (titlecase - 14 unidata-gen-table-character "uni-titlecase.el" - "Unicode simple titlecase mapping. -Property value is a character." - string))) - -;; Functions to access the above data. -(defsubst unidata-prop-index (prop) (nth 1 (assq prop unidata-prop-alist))) -(defsubst unidata-prop-generator (prop) (nth 2 (assq prop unidata-prop-alist))) -(defsubst unidata-prop-file (prop) (nth 3 (assq prop unidata-prop-alist))) -(defsubst unidata-prop-docstring (prop) (nth 4 (assq prop unidata-prop-alist))) -(defsubst unidata-prop-describer (prop) (nth 5 (assq prop unidata-prop-alist))) - - -;; SIMPLE TABLE -;; -;; If the type of character property value is character, and the -;; values of succeeding character codes are usually different, we use -;; a char-table described here to store such values. -;; -;; If succeeding 128 characters has no property, a char-table has the -;; symbol t is for them. Otherwise a char-table has a string of the -;; following format for them. -;; -;; The first character of the string is FIRST-INDEX. -;; The Nth (N > 0) character of the string is a property value of the -;; character (BLOCK-HEAD + FIRST-INDEX + N - 1), where BLOCK-HEAD is -;; the first of the characters in the block. -;; -;; The 4th extra slot of a char-table is nil. - -(defun unidata-get-character (char val table) - (cond - ((characterp val) - val) - - ((stringp val) - (let* ((len (length val)) - (block-head (lsh (lsh char -7) 7)) - (vec (make-vector 128 nil)) - (first-index (aref val 0))) - (dotimes (i (1- len)) - (let ((elt (aref val (1+ i)))) - (if (> elt 0) - (aset vec (+ first-index i) elt)))) - (dotimes (i 128) - (aset table (+ block-head i) (aref vec i))) - (aref vec (- char block-head)))))) - -(defun unidata-put-character (char val table) - (or (characterp val) - (not val) - (error "Not a character nor nil: %S" val)) - (let ((current-val (aref table char))) - (unless (eq current-val val) - (if (stringp current-val) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val)))) - -(defun unidata-gen-table-character (prop) - (let ((table (make-char-table 'char-code-property-table)) - (prop-idx (unidata-prop-index prop)) - (vec (make-vector 128 0)) - (tail unidata-list) - elt range val idx slot) - (set-char-table-range table (cons 0 (max-char)) t) - (while tail - (setq elt (car tail) tail (cdr tail)) - (setq range (car elt) - val (nth prop-idx elt)) - (if (= (length val) 0) - (setq val nil) - (setq val (string-to-number val 16))) - (if (consp range) - (if val - (set-char-table-range table range val)) - (let* ((start (lsh (lsh range -7) 7)) - (limit (+ start 127)) - first-index last-index) - (fillarray vec 0) - (if val - (aset vec (setq last-index (setq first-index (- range start))) - val)) - (while (and (setq elt (car tail) range (car elt)) - (integerp range) - (<= range limit)) - (setq val (nth prop-idx elt)) - (when (> (length val) 0) - (aset vec (setq last-index (- range start)) - (string-to-number val 16)) - (or first-index - (setq first-index last-index))) - (setq tail (cdr tail))) - (when first-index - (let ((str (string first-index)) - c) - (while (<= first-index last-index) - (setq str (format "%s%c" str (or (aref vec first-index) 0)) - first-index (1+ first-index))) - (set-char-table-range table (cons start limit) str)))))) - - (set-char-table-extra-slot table 0 prop) - (byte-compile 'unidata-get-character) - (byte-compile 'unidata-put-character) - (set-char-table-extra-slot table 1 (symbol-function 'unidata-get-character)) - (set-char-table-extra-slot table 2 (symbol-function 'unidata-put-character)) - - table)) - - - -;; RUN-LENGTH TABLE -;; -;; If the type of character property value is symbol, integer, -;; boolean, or character, we use a char-table described here to store -;; the values. -;; -;; The 4th extra slot is a vector of property values (VAL-TABLE), and -;; values for succeeding 128 characters are encoded into this -;; character sequence: -;; ( VAL-CODE RUN-LENGTH ? ) + -;; where: -;; VAL-CODE (0..127): -;; (VAL-CODE - 1) is an index into VAL-TABLE. -;; The value 0 means no-value. -;; RUN-LENGTH (130..255): -;; (RUN-LENGTH - 128) specifies how many characters have the same -;; value. If omitted, it means 1. - - -;; Return a symbol-type character property value of CHAR. VAL is the -;; current value of (aref TABLE CHAR). - -(defun unidata-get-symbol (char val table) - (let ((val-table (char-table-extra-slot table 4))) - (cond ((symbolp val) - val) - ((stringp val) - (let ((first-char (lsh (lsh char -7) 7)) - (str val) - (len (length val)) - (idx 0) - this-val count) - (set-char-table-range table (cons first-char (+ first-char 127)) - nil) - (while (< idx len) - (setq val (aref str idx) idx (1+ idx) - count (if (< idx len) (aref str idx) 1)) - (setq val (and (> val 0) (aref val-table (1- val))) - count (if (< count 128) - 1 - (prog1 (- count 128) (setq idx (1+ idx))))) - (dotimes (i count) - (if val - (aset table first-char val)) - (if (= first-char char) - (setq this-val val)) - (setq first-char (1+ first-char)))) - this-val)) - ((> val 0) - (aref val-table (1- val)))))) - -;; Return a integer-type character property value of CHAR. VAL is the -;; current value of (aref TABLE CHAR). - -(defun unidata-get-integer (char val table) - (let ((val-table (char-table-extra-slot table 4))) - (cond ((integerp val) - val) - ((stringp val) - (let ((first-char (lsh (lsh char -7) 7)) - (str val) - (len (length val)) - (idx 0) - this-val count) - (while (< idx len) - (setq val (aref str idx) idx (1+ idx) - count (if (< idx len) (aref str idx) 1)) - (setq val (and (> val 0) (aref val-table (1- val))) - count (if (< count 128) - 1 - (prog1 (- count 128) (setq idx (1+ idx))))) - (dotimes (i count) - (aset table first-char val) - (if (= first-char char) - (setq this-val val)) - (setq first-char (1+ first-char)))) - this-val))))) - -;; Return a numeric-type (integer or float) character property value -;; of CHAR. VAL is the current value of (aref TABLE CHAR). - -(defun unidata-get-numeric (char val table) - (cond - ((numberp val) - val) - ((stringp val) - (let ((val-table (char-table-extra-slot table 4)) - (first-char (lsh (lsh char -7) 7)) - (str val) - (len (length val)) - (idx 0) - this-val count) - (while (< idx len) - (setq val (aref str idx) idx (1+ idx) - count (if (< idx len) (aref str idx) 1)) - (setq val (and (> val 0) (aref val-table (1- val))) - count (if (< count 128) - 1 - (prog1 (- count 128) (setq idx (1+ idx))))) - (dotimes (i count) - (aset table first-char val) - (if (= first-char char) - (setq this-val val)) - (setq first-char (1+ first-char)))) - this-val)))) - -;; Store VAL (symbol) as a character property value of CHAR in TABLE. - -(defun unidata-put-symbol (char val table) - (or (symbolp val) - (error "Not a symbol: %S" val)) - (let ((current-val (aref table char))) - (unless (eq current-val val) - (if (stringp current-val) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val)))) - -;; Store VAL (integer) as a character property value of CHAR in TABLE. - -(defun unidata-put-integer (char val table) - (or (integerp val) - (not val) - (error "Not an integer nor nil: %S" val)) - (let ((current-val (aref table char))) - (unless (eq current-val val) - (if (stringp current-val) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val)))) - -;; Store VAL (integer or float) as a character property value of CHAR -;; in TABLE. - -(defun unidata-put-numeric (char val table) - (or (numberp val) - (not val) - (error "Not a number nor nil: %S" val)) - (let ((current-val (aref table char))) - (unless (equal current-val val) - (if (stringp current-val) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val)))) - -;; Encode the character property value VAL into an integer value by -;; VAL-LIST. By side effect, VAL-LIST is modified. -;; VAL-LIST has this form: -;; (t (VAL1 . VAL-CODE1) (VAL2 . VAL-CODE2) ...) -;; If VAL is one of VALn, just return VAL-CODEn. Otherwise, -;; VAL-LIST is modified to this: -;; (t (VAL . (1+ VAL-CODE1)) (VAL1 . VAL-CODE1) (VAL2 . VAL-CODE2) ...) - -(defun unidata-encode-val (val-list val) - (let ((slot (assoc val val-list)) - val-code) - (if slot - (cdr slot) - (setq val-code (if (cdr val-list) (1+ (cdr (nth 1 val-list))) 1)) - (setcdr val-list (cons (cons val val-code) (cdr val-list))) - val-code))) - -;; Generate a char-table for the character property PROP. - -(defun unidata-gen-table (prop val-func default-value) - (let ((table (make-char-table 'char-code-property-table)) - (prop-idx (unidata-prop-index prop)) - (val-list (list t)) - (vec (make-vector 128 0)) - tail elt range val val-code idx slot) - (set-char-table-range table (cons 0 (max-char)) default-value) - (setq tail unidata-list) - (while tail - (setq elt (car tail) tail (cdr tail)) - (setq range (car elt) - val (funcall val-func (nth prop-idx elt))) - (setq val-code (if val (unidata-encode-val val-list val))) - (if (consp range) - (if val-code - (set-char-table-range table range val)) - (let* ((start (lsh (lsh range -7) 7)) - (limit (+ start 127)) - str count new-val) - (fillarray vec 0) - (if val-code - (aset vec (- range start) val-code)) - (while (and (setq elt (car tail) range (car elt)) - (integerp range) - (<= range limit)) - (setq new-val (funcall val-func (nth prop-idx elt))) - (if (not (eq val new-val)) - (setq val new-val - val-code (if val (unidata-encode-val val-list val)))) - (if val-code - (aset vec (- range start) val-code)) - (setq tail (cdr tail))) - (setq str "" val-code -1 count 0) - (mapc #'(lambda (x) - (if (= val-code x) - (setq count (1+ count)) - (if (> count 2) - (setq str (concat str (string val-code - (+ count 128)))) - (if (= count 2) - (setq str (concat str (string val-code val-code))) - (if (= count 1) - (setq str (concat str (string val-code)))))) - (setq val-code x count 1))) - vec) - (if (= count 128) - (if val - (set-char-table-range table (cons start limit) val)) - (if (= val-code 0) - (set-char-table-range table (cons start limit) str) - (if (> count 2) - (setq str (concat str (string val-code (+ count 128)))) - (if (= count 2) - (setq str (concat str (string val-code val-code))) - (setq str (concat str (string val-code))))) - (set-char-table-range table (cons start limit) str)))))) - - (setq val-list (nreverse (cdr val-list))) - (set-char-table-extra-slot table 0 prop) - (set-char-table-extra-slot table 4 (vconcat (mapcar 'car val-list))) - table)) - -(defun unidata-gen-table-symbol (prop) - (let ((table (unidata-gen-table prop - #'(lambda (x) (and (> (length x) 0) - (intern x))) - 0))) - (byte-compile 'unidata-get-symbol) - (byte-compile 'unidata-put-symbol) - (set-char-table-extra-slot table 1 (symbol-function 'unidata-get-symbol)) - (set-char-table-extra-slot table 2 (symbol-function 'unidata-put-symbol)) - table)) - -(defun unidata-gen-table-integer (prop) - (let ((table (unidata-gen-table prop - #'(lambda (x) (and (> (length x) 0) - (string-to-number x))) - t))) - (byte-compile 'unidata-get-integer) - (byte-compile 'unidata-put-integer) - (set-char-table-extra-slot table 1 (symbol-function 'unidata-get-integer)) - (set-char-table-extra-slot table 2 (symbol-function 'unidata-put-integer)) - table)) - -(defun unidata-gen-table-numeric (prop) - (let ((table (unidata-gen-table prop - #'(lambda (x) - (if (string-match "/" x) - (/ (float (string-to-number x)) - (string-to-number - (substring x (match-end 0)))) - (if (> (length x) 0) - (string-to-number x)))) - t))) - (byte-compile 'unidata-get-numeric) - (byte-compile 'unidata-put-numeric) - (set-char-table-extra-slot table 1 (symbol-function 'unidata-get-numeric)) - (set-char-table-extra-slot table 2 (symbol-function 'unidata-put-numeric)) - table)) - - -;; WORD-LIST TABLE - -;; If the table is for `name' property, each character in the string -;; is one of these: -;; DIFF-HEAD-CODE (0, 1, or 2): -;; specifies how to decode the following characters. -;; WORD-CODE (3..#x7FF excluding '-', '0'..'9', 'A'..'Z'): -;; specifies an index number into WORD-TABLE (see below) -;; Otherwise (' ', '-', '0'..'9', 'A'..'Z'): -;; specifies a literal word. -;; -;; The 4th slots is a vector: -;; [ WORD-TABLE BLOCK-NAME HANGUL-JAMO-TABLE ] -;; WORD-TABLE is a vector of word symbols. -;; BLOCK-NAME is a vector of name symbols for a block of characters. -;; HANGUL-JAMO-TABLE is `unidata-name-jamo-name-table'. - -;; Return the difference of symbol list L1 and L2 in this form: -;; (DIFF-HEAD SYM1 SYM2 ...) -;; DIFF-HEAD is ((SAME-HEAD-LENGTH * 16) + SAME-TAIL-LENGTH). -;; Ex: If L1 is (a b c d e f) and L2 is (a g h e f), this function -;; returns ((+ (* 1 16) 2) g h). -;; It means that we can get L2 from L1 by prepending the first element -;; of L1 and appending the last 2 elements of L1 to the list (g h). -;; If L1 and L2 don't have common elements at the head and tail, -;; set DIFF-HEAD to -1 and SYM1 ... to the elements of L2. - -(defun unidata-word-list-diff (l1 l2) - (let ((beg 0) - (end 0) - (len1 (length l1)) - (len2 (length l2)) - result) - (when (< len1 16) - (while (and l1 (eq (car l1) (car l2))) - (setq beg (1+ beg) - l1 (cdr l1) len1 (1- len1) l2 (cdr l2) len2 (1- len2))) - (while (and (< end len1) (< end len2) - (eq (nth (- len1 end 1) l1) (nth (- len2 end 1) l2))) - (setq end (1+ end)))) - (if (= (+ beg end) 0) - (setq result (list -1)) - (setq result (list (+ (* beg 16) (+ beg (- len1 end)))))) - (while (< end len2) - (setcdr result (cons (nth (- len2 end 1) l2) (cdr result))) - (setq end (1+ end))) - result)) - -;; Return a compressed form of the vector VEC. Each element of VEC is -;; a list of symbols of which names can be concatenated to form a -;; character name. This function changes those elements into -;; compressed forms by utilizing the fact that diff of consecutive -;; elements is usually small. - -(defun unidata-word-list-compress (vec) - (let (last-elt last-idx diff-head tail elt val) - (dotimes (i 128) - (setq elt (aref vec i)) - (when elt - (if (null last-elt) - (setq diff-head -1 - val (cons 0 elt)) - (setq val (unidata-word-list-diff last-elt elt)) - (if (= (car val) -1) - (setq diff-head -1 - val (cons 0 (cdr val))) - (if (eq diff-head (car val)) - (setq val (cons 2 (cdr val))) - (setq diff-head (car val)) - (if (>= diff-head 0) - (setq val (cons 1 val)))))) - (aset vec i val) - (setq last-idx i last-elt elt))) - (if (not last-idx) - (setq vec nil) - (if (< last-idx 127) - (let ((shorter (make-vector (1+ last-idx) nil))) - (dotimes (i (1+ last-idx)) - (aset shorter i (aref vec i))) - (setq vec shorter)))) - vec)) - -;; Encode the word index IDX into a characters code that can be -;; embedded in a string. - -(defsubst unidata-encode-word (idx) - ;; Exclude 0, 1, 2. - (+ idx 3)) - -;; Decode the character code CODE (that is embedded in a string) into -;; the corresponding word name by looking up WORD-TABLE. - -(defsubst unidata-decode-word (code word-table) - (setq code (- code 3)) - (if (< code (length word-table)) - (aref word-table code))) - -;; Table of short transliterated name symbols of Hangul Jamo divided -;; into Choseong, Jungseong, and Jongseong. - -(defconst unidata-name-jamo-name-table - [[G GG N D DD R M B BB S SS nil J JJ C K T P H] - [A AE YA YAE EO E YEO YE O WA WAE OE YO U WEO WE WI YU EU YI I] - [G GG GS N NJ NH D L LG LM LB LS LT LP LH M B BS S SS NG J C K T P H]]) - -;; Return a name of CHAR. VAL is the current value of (aref TABLE -;; CHAR). - -(defun unidata-get-name (char val table) - (cond - ((stringp val) - (if (> (aref val 0) 0) - val - (let* ((first-char (lsh (lsh char -7) 7)) - (word-table (aref (char-table-extra-slot table 4) 0)) - (i 1) - (len (length val)) - (vec (make-vector 128 nil)) - (idx 0) - (case-fold-search nil) - c word-list tail-list last-list word diff-head) - (while (< i len) - (setq c (aref val i)) - (if (< c 3) - (progn - (if (or word-list tail-list) - (aset vec idx - (setq last-list (nconc word-list tail-list)))) - (setq i (1+ i) idx (1+ idx) - word-list nil tail-list nil) - (if (> c 0) - (let ((l last-list)) - (if (= c 1) - (setq diff-head - (prog1 (aref val i) (setq i (1+ i))))) - (setq tail-list (nthcdr (% diff-head 16) last-list)) - (dotimes (i (/ diff-head 16)) - (setq word-list (nconc word-list (list (car l))) - l (cdr l)))))) - (setq word-list - (nconc word-list - (list (symbol-name - (unidata-decode-word c word-table)))) - i (1+ i)))) - (if (or word-list tail-list) - (aset vec idx (nconc word-list tail-list))) - (setq val nil) - (dotimes (i 128) - (setq c (+ first-char i)) - (let ((name (aref vec i))) - (if name - (let ((tail (cdr (setq name (copy-sequence name)))) - elt) - (while tail - (setq elt (car tail)) - (or (string= elt "-") - (progn - (setcdr tail (cons elt (cdr tail))) - (setcar tail " "))) - (setq tail (cddr tail))) - (setq name (apply 'concat name)))) - (aset table c name) - (if (= c char) - (setq val name)))) - val))) - - ((and (integerp val) (> val 0)) - (let* ((symbol-table (aref (char-table-extra-slot table 4) 1)) - (sym (aref symbol-table (1- val)))) - (cond ((eq sym 'HANGUL\ SYLLABLE) - (let ((jamo-name-table (aref (char-table-extra-slot table 4) 2))) - ;; SIndex = S - SBase - (setq char (- char #xAC00)) - (let ( ;; LIndex = SIndex / NCount - (L (/ char 588)) - ;; VIndex = (SIndex % NCount) * TCount - (V (/ (% char 588) 28)) - ;; TIndex = SIndex % TCount - (T (% char 28))) - (format "HANGUL SYLLABLE %s%s%s" - ;; U+110B is nil in this table. - (or (aref (aref jamo-name-table 0) L) "") - (aref (aref jamo-name-table 1) V) - (if (= T 0) "" - (aref (aref jamo-name-table 2) (1- T))))))) - ((eq sym 'CJK\ IDEOGRAPH) - (format "%s-%04X" sym char)) - ((eq sym 'CJK\ COMPATIBILITY\ IDEOGRAPH) - (format "%s-%04X" sym char)) - ((eq sym 'VARIATION\ SELECTOR) - (format "%s-%d" sym (+ (- char #xe0100) 17)))))))) - -;; Store VAL as the name of CHAR in TABLE. - -(defun unidata-put-name (char val table) - (let ((current-val (aref table char))) - (if (and (stringp current-val) (= (aref current-val 0) 0)) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val))) - -(defun unidata-get-decomposition (char val table) - (cond - ((consp val) - val) - - ((stringp val) - (if (> (aref val 0) 0) - val - (let* ((first-char (lsh (lsh char -7) 7)) - (word-table (char-table-extra-slot table 4)) - (i 1) - (len (length val)) - (vec (make-vector 128 nil)) - (idx 0) - (case-fold-search nil) - c word-list tail-list last-list word diff-head) - (while (< i len) - (setq c (aref val i)) - (if (< c 3) - (progn - (if (or word-list tail-list) - (aset vec idx - (setq last-list (nconc word-list tail-list)))) - (setq i (1+ i) idx (1+ idx) - word-list nil tail-list nil) - (if (> c 0) - (let ((l last-list)) - (if (= c 1) - (setq diff-head - (prog1 (aref val i) (setq i (1+ i))))) - (setq tail-list (nthcdr (% diff-head 16) last-list)) - (dotimes (i (/ diff-head 16)) - (setq word-list (nconc word-list (list (car l))) - l (cdr l)))))) - (setq word-list - (nconc word-list - (list (or (unidata-decode-word c word-table) c))) - i (1+ i)))) - (if (or word-list tail-list) - (aset vec idx (nconc word-list tail-list))) - (dotimes (i 128) - (aset table (+ first-char i) (aref vec i))) - (aref vec (- char first-char))))) - - ;; Hangul syllable - ((and (eq val 0) (>= char #xAC00) (<= char #xD7A3)) - ;; SIndex = S (char) - SBase (#xAC00) - (setq char (- char #xAC00)) - (let (;; L = LBase + SIndex / NCount - (L (+ #x1100 (/ char 588))) - ;; V = VBase + (SIndex % NCount) * TCount - (V (+ #x1161 (/ (% char 588) 28))) - ;; LV = SBase + (SIndex / TCount) * TCount - (LV (+ #xAC00 (* (/ char 28) 28))) - ;; T = TBase + SIndex % TCount - (T (+ #x11A7 (% char 28)))) - (if (= T #x11A7) - (list L V) - (list LV T)))) - - )) - -;; Store VAL as the decomposition information of CHAR in TABLE. - -(defun unidata-put-decomposition (char val table) - (let ((current-val (aref table char))) - (if (and (stringp current-val) (= (aref current-val 0) 0)) - (funcall (char-table-extra-slot table 1) char current-val table)) - (aset table char val))) - -;; UnicodeData.txt contains these lines: -;; 0000;;Cc;0;BN;;;;;N;NULL;;;; -;; ... -;; 0020;SPACE;Zs;0;WS;;;;;N;;;;; -;; ... -;; The following command yields a file of about 96K bytes. -;; % gawk -F ';' '{print $1,$2;}' < UnicodeData.txt | gzip > temp.gz -;; With the following function, we can get a file of almost the same -;; the size. - -;; Generate a char-table for character names. - -(defun unidata-gen-table-word-list (prop val-func) - (let ((table (make-char-table 'char-code-property-table)) - (prop-idx (unidata-prop-index prop)) - (word-list (list nil)) - word-table - block-list block-word-table block-end - tail elt range val idx slot) - (set-char-table-range table (cons 0 (max-char)) 0) - (setq tail unidata-list) - (setq block-end -1) - (while tail - (setq elt (car tail) tail (cdr tail)) - (setq range (car elt) - val (funcall val-func (nth prop-idx elt))) - ;; Treat the sequence of "CJK COMPATIBILITY IDEOGRAPH-XXXX" and - ;; "VARIATION SELECTOR-XXX" as a block. - (if (and (consp val) (eq prop 'name) - (or (and (eq (car val) 'CJK) - (eq (nth 1 val) 'COMPATIBILITY)) - (and (>= range #xe0100) - (eq (car val) 'VARIATION) - (eq (nth 1 val) 'SELECTOR)))) - (let ((first (car val)) - (second (nth 1 val)) - (start range)) - (while (and (setq elt (car tail) range (car elt) - val (funcall val-func (nth prop-idx elt))) - (consp val) - (eq first (car val)) - (eq second (nth 1 val))) - (setq block-end range - tail (cdr tail))) - (setq range (cons start block-end) - val (if (eq first 'CJK) 'CJK\ COMPATIBILITY\ IDEOGRAPH - 'VARIATION\ SELECTOR)))) - - (if (consp range) - (if val - (let ((slot (assq val block-list))) - (setq range (cons (car range) (cdr range))) - (setq block-end (cdr range)) - (if slot - (nconc slot (list range)) - (push (list val range) block-list)))) - (let* ((start (lsh (lsh range -7) 7)) - (limit (+ start 127)) - (first tail) - (vec (make-vector 128 nil)) - c name len) - (if (<= start block-end) - ;; START overlap with the previous block. - (aset table range (nth prop-idx elt)) - (if val - (aset vec (- range start) val)) - (while (and (setq elt (car tail) range (car elt)) - (integerp range) - (<= range limit)) - (setq val (funcall val-func (nth prop-idx elt))) - (if val - (aset vec (- range start) val)) - (setq tail (cdr tail))) - (setq vec (unidata-word-list-compress vec)) - (when vec - (dotimes (i (length vec)) - (dolist (elt (aref vec i)) - (if (symbolp elt) - (let ((slot (assq elt word-list))) - (if slot - (setcdr slot (1+ (cdr slot))) - (setcdr word-list - (cons (cons elt 1) (cdr word-list)))))))) - (set-char-table-range table (cons start limit) vec)))))) - (setq word-list (sort (cdr word-list) - #'(lambda (x y) (> (cdr x) (cdr y))))) - (setq tail word-list idx 0) - (while tail - (setcdr (car tail) (unidata-encode-word idx)) - (setq idx (1+ idx) tail (cdr tail))) - (setq word-table (make-vector (length word-list) nil)) - (setq idx 0) - (dolist (elt word-list) - (aset word-table idx (car elt)) - (setq idx (1+ idx))) - - (if (and (eq prop 'decomposition) - (> idx 32)) - (error "Too many symbols in decomposition data")) - - (dotimes (i (/ #x110000 128)) - (let* ((idx (* i 128)) - (vec (aref table idx))) - (when (vectorp vec) - (dotimes (i (length vec)) - (let ((tail (aref vec i)) - elt code) - (if (not tail) - (aset vec i "\0") - (while tail - (setq elt (car tail) - code (if (integerp elt) elt - (cdr (assq elt word-list)))) - (setcar tail (string code)) - (setq tail (cdr tail))) - (aset vec i (mapconcat 'identity (aref vec i) ""))))) - (set-char-table-range - table (cons idx (+ idx 127)) - (mapconcat 'identity vec ""))))) - - (setq block-word-table (make-vector (length block-list) nil)) - (setq idx 0) - (dolist (elt block-list) - (dolist (e (cdr elt)) - (set-char-table-range table e (1+ idx))) - (aset block-word-table idx (car elt)) - (setq idx (1+ idx))) - - (set-char-table-extra-slot table 0 prop) - (set-char-table-extra-slot table 4 (cons word-table block-word-table)) - table)) - -(defun unidata-split-name (str) - (if (symbolp str) - str - (let ((len (length str)) - (l nil) - (idx 0) - c) - (if (= len 0) - nil - (dotimes (i len) - (setq c (aref str i)) - (if (= c 32) - (setq l (cons (intern (substring str idx i)) l) - idx (1+ i)) - (if (and (= c ?-) (< idx i) - (< (1+ i) len) (/= (aref str (1+ i)) 32)) - (setq l (cons '- (cons (intern (substring str idx i)) l)) - idx (1+ i))))) - (nreverse (cons (intern (substring str idx)) l)))))) - -(defun unidata-gen-table-name (prop) - (let* ((table (unidata-gen-table-word-list prop 'unidata-split-name)) - (word-tables (char-table-extra-slot table 4))) - (byte-compile 'unidata-get-name) - (byte-compile 'unidata-put-name) - (set-char-table-extra-slot table 1 (symbol-function 'unidata-get-name)) - (set-char-table-extra-slot table 2 (symbol-function 'unidata-put-name)) - - (if (eq prop 'name) - (set-char-table-extra-slot table 4 - (vector (car word-tables) - (cdr word-tables) - unidata-name-jamo-name-table)) - (set-char-table-extra-slot table 4 - (vector (car word-tables)))) - table)) - -(defun unidata-split-decomposition (str) - (if (symbolp str) - str - (let ((len (length str)) - (l nil) - (idx 0) - c) - (if (= len 0) - nil - (dotimes (i len) - (setq c (aref str i)) - (if (= c 32) - (setq l (if (= (aref str idx) ?<) - (cons (intern (substring str (1+ idx) (1- i))) l) - (cons (string-to-number (substring str idx i) 16) l)) - idx (1+ i)))) - (if (= (aref str idx) ?<) - (setq l (cons (intern (substring str (1+ idx) (1- len))) l)) - (setq l (cons (string-to-number (substring str idx len) 16) l))) - (nreverse l))))) - - -(defun unidata-gen-table-decomposition (prop) - (let* ((table (unidata-gen-table-word-list prop 'unidata-split-decomposition)) - (word-tables (char-table-extra-slot table 4))) - (byte-compile 'unidata-get-decomposition) - (byte-compile 'unidata-put-decomposition) - (set-char-table-extra-slot table 1 - (symbol-function 'unidata-get-decomposition)) - (set-char-table-extra-slot table 2 - (symbol-function 'unidata-put-decomposition)) - (set-char-table-extra-slot table 4 (car word-tables)) - table)) - - - -(defun unidata-describe-general-category (val) - (cdr (assq val - '((Lu . "Letter, Uppercase") - (Ll . "Letter, Lowercase") - (Lt . "Letter, Titlecase") - (Lm . "Letter, Modifier") - (Lo . "Letter, Other") - (Mn . "Mark, Nonspacing") - (Mc . "Mark, Spacing Combining") - (Me . "Mark, Enclosing") - (Nd . "Number, Decimal Digit") - (Nl . "Number, Letter") - (No . "Number, Other") - (Pc . "Punctuation, Connector") - (Pd . "Punctuation, Dash") - (Ps . "Punctuation, Open") - (Pe . "Punctuation, Close") - (Pi . "Punctuation, Initial quote") - (Pf . "Punctuation, Final quote") - (Po . "Punctuation, Other") - (Sm . "Symbol, Math") - (Sc . "Symbol, Currency") - (Sk . "Symbol, Modifier") - (So . "Symbol, Other") - (Zs . "Separator, Space") - (Zl . "Separator, Line") - (Zp . "Separator, Paragraph") - (Cc . "Other, Control") - (Cf . "Other, Format") - (Cs . "Other, Surrogate") - (Co . "Other, Private Use") - (Cn . "Other, Not Assigned"))))) - -(defun unidata-describe-canonical-combining-class (val) - (cdr (assq val - '((0 . "Spacing, split, enclosing, reordrant, and Tibetan subjoined") - (1 . "Overlays and interior") - (7 . "Nuktas") - (8 . "Hiragana/Katakana voicing marks") - (9 . "Viramas") - (10 . "Start of fixed position classes") - (199 . "End of fixed position classes") - (200 . "Below left attached") - (202 . "Below attached") - (204 . "Below right attached") - (208 . "Left attached (reordrant around single base character)") - (210 . "Right attached") - (212 . "Above left attached") - (214 . "Above attached") - (216 . "Above right attached") - (218 . "Below left") - (220 . "Below") - (222 . "Below right") - (224 . "Left (reordrant around single base character)") - (226 . "Right") - (228 . "Above left") - (230 . "Above") - (232 . "Above right") - (233 . "Double below") - (234 . "Double above") - (240 . "Below (iota subscript)"))))) - -(defun unidata-describe-bidi-class (val) - (cdr (assq val - '((L . "Left-to-Right") - (LRE . "Left-to-Right Embedding") - (LRO . "Left-to-Right Override") - (R . "Right-to-Left") - (AL . "Right-to-Left Arabic") - (RLE . "Right-to-Left Embedding") - (RLO . "Right-to-Left Override") - (PDF . "Pop Directional Format") - (EN . "European Number") - (ES . "European Number Separator") - (ET . "European Number Terminator") - (AN . "Arabic Number") - (CS . "Common Number Separator") - (NSM . "Non-Spacing Mark") - (BN . "Boundary Neutral") - (B . "Paragraph Separator") - (S . "Segment Separator") - (WS . "Whitespace") - (ON . "Other Neutrals"))))) - -(defun unidata-describe-decomposition (val) - (mapconcat - #'(lambda (x) - (if (symbolp x) (symbol-name x) - (concat (string ?') - (compose-string (string x) 0 1 (string ?\t x ?\t)) - (string ?')))) - val " ")) - -;; Verify if we can retrieve correct values from the generated -;; char-tables. - -(defun unidata-check () - (dolist (elt unidata-prop-alist) - (let* ((prop (car elt)) - (index (unidata-prop-index prop)) - (generator (unidata-prop-generator prop)) - (table (progn - (message "Generating %S table..." prop) - (funcall generator prop))) - (decoder (char-table-extra-slot table 1)) - (check #x400)) - (dolist (e unidata-list) - (let ((char (car e)) - (val1 (nth index e)) - val2) - (if (and (stringp val1) (= (length val1) 0)) - (setq val1 nil)) - (unless (consp char) - (setq val2 (funcall decoder char (aref table char) table)) - (if val1 - (cond ((eq generator 'unidata-gen-table-symbol) - (setq val1 (intern val1))) - ((eq generator 'unidata-gen-table-integer) - (setq val1 (string-to-number val1))) - ((eq generator 'unidata-gen-table-character) - (setq val1 (string-to-number val1 16))) - ((eq generator 'unidata-gen-table-decomposition) - (setq val1 (unidata-split-decomposition val1))))) - (when (>= char check) - (message "%S %04X" prop check) - (setq check (+ check #x400))) - (or (equal val1 val2) - (insert (format "> %04X %S\n< %04X %S\n" - char val1 char val2))) - (sit-for 0))))))) - -;; The entry function. It generates files described in the header -;; comment of this file. - -(defun unidata-gen-files (&optional unidata-text-file) - (or unidata-text-file - (setq unidata-text-file (car command-line-args-left) - command-line-args-left (cdr command-line-args-left))) - (unidata-setup-list unidata-text-file) - (let ((coding-system-for-write 'utf-8-unix) - (charprop-file "charprop.el")) - (with-temp-file charprop-file - (insert ";; Automatically generated by unidata-gen.el.\n") - (dolist (elt unidata-prop-alist) - (let* ((prop (car elt)) - (generator (unidata-prop-generator prop)) - (file (unidata-prop-file prop)) - (docstring (unidata-prop-docstring prop)) - (describer (unidata-prop-describer prop)) - table) - ;; Filename in this comment line is extracted by sed in - ;; Makefile. - (insert (format ";; FILE: %s\n" file)) - (insert (format "(define-char-code-property '%S %S\n %S)\n" - prop file docstring)) - (with-temp-file file - (message "Generating %s..." file) - (setq table (funcall generator prop)) - (when describer - (unless (subrp (symbol-function describer)) - (byte-compile describer) - (setq describer (symbol-function describer))) - (set-char-table-extra-slot table 3 describer)) - (insert ";; Copyright (C) 1991-2009 Unicode, Inc. -;; This file was generated from the Unicode data file at -;; http://www.unicode.org/Public/UNIDATA/UnicodeData.txt. -;; See lisp/international/README for the copyright and permission notice.\n" - (format "(define-char-code-property '%S %S %S)\n" - prop table docstring) - ";; Local Variables:\n" - ";; coding: utf-8\n" - ";; no-byte-compile: t\n" - ";; End:\n\n" - (format ";; %s ends here\n" file))))) - (message "Writing %s..." charprop-file) - (insert ";; Local Variables:\n" - ";; coding: utf-8\n" - ";; no-byte-compile: t\n" - ";; End:\n\n" - (format ";; %s ends here\n" charprop-file))))) - - - -;; arch-tag: 961c862e-b821-447e-9b8a-bfbab9c2d525 -;;; unidata-gen.el ends here diff --git a/autogen.sh b/autogen.sh deleted file mode 100755 index 0fe7ef32fc2..00000000000 --- a/autogen.sh +++ /dev/null @@ -1,9 +0,0 @@ -#!/bin/sh - -echo "Please read INSTALL.CVS for instructions on how to build Emacs from CVS." - -# Exit with failure, since people may have generic build scripts that -# try things like "autogen.sh && ./configure && make". -exit 1 - -# arch-tag: a123408c-fada-4bf7-98a0-a786cff918f0 diff --git a/doc/emacs/.cvsignore b/doc/emacs/.cvsignore deleted file mode 100644 index 3ff56b474dd..00000000000 --- a/doc/emacs/.cvsignore +++ /dev/null @@ -1,23 +0,0 @@ -*.aux -*.cp -*.cps -*.dvi -*.fn -*.fns -*.ky -*.kys -*.log -*.op -*.ops -*.pdf -*.pg -*.pgs -*.ps -*.tmp -*.toc -*.tp -*.tps -*.vr -*.vrs -Makefile -makefile diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog deleted file mode 100644 index cc6715b6a27..00000000000 --- a/doc/emacs/ChangeLog +++ /dev/null @@ -1,6809 +0,0 @@ -2009-07-29 Chong Yidong - - * Version 23.1 released. - -2009-07-28 Chong Yidong - - * building.texi (Lisp Libraries): Clarify meaning of autoloading. - -2009-07-22 Richard Stallman - - * glossary.texi (GNU, Daemon): Update information. - -2009-07-21 Chong Yidong - - * frames.texi (Cut/Paste Other App): Remove discussion of - select-active-regions for 23.1, as it is not fully functional. - -2009-07-15 Chong Yidong - - * macos.texi (Mac OS / GNUstep): Add note about stability. - -2009-07-15 Glenn Morris - - * misc.texi (Gnus): Remove widow. - -2009-07-11 Glenn Morris - - * arevert-xtra.texi (Autorevert): Add menu descriptions. - - * display.texi (Horizontal Scrolling): Re-word to remove widow. - - * emacs.texi (Top): Info can be read from other places than Emacs. - Don't print the copying notice twice in the printed version. - Update the menu and detailmenu. - (Preface): The meaning of "on-line" has changed. - Correct name for "Common Problems" chapter. - (Distrib): Update FSF shop URL. - (Intro): Showing two files at once is not so exciting. - - * macos.texi (Mac OS / GNUstep): Fix spelling and cross-reference. - (Mac / GNUstep Basics): Minor grammar changes. - (Mac / GNUstep Events): Fix typo. - (GNUstep Support): CANNOT_DUMP no longer applies. - - * misc.texi (Document View): Fix typos. - - * dired.texi (Dired): - * help.texi (Help): - * macos.texi (Mac OS / GNUstep): - * maintaining.texi (Version Control, Introduction to VC): - End menu descriptions with a period. - -2009-07-10 Eli Zaretskii - - * msdog.texi (Windows Files) : Don't be - so categorical in saying that the option is only useful on NTFS. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): New variable, with location of texinfo.tex. - (ENVADD): Add texinfodir to TEXINPUTS. - - * emacs.texi (Top): Fix cross-reference. - - * maintaining.texi (VC Directory Buffer): Fix cross-reference. - - * vc1-xtra.texi (Revision Tags): Fix typo. - -2009-07-03 Glenn Morris - - * emerge-xtra.texi (Emerge): Tweak Misc menu description. - (Submodes of Emerge): Skip Prefers is only relevant with an ancestor. - (Merge Commands): `.' does not seem to work in A or B buffer. - `l' can recreate the 3-window display. - - * glossary.texi (Glossary): Minor phrasing changes throughout. - Add more internal cross-references. - : You can't really autoload a variable. - : Move details here from `M-C-' item. - : Refer to `Truncation.' - : - : New entries. - : Mention recycle bins. - : Mention ``folders.'' - : Don't mention ``type-ahead.'' - : Refer to the manual node. - : Can be global or local. - : There are other checkers besides Ispell. - -2009-07-02 Glenn Morris - - * anti.texi (Antinews): Minor changes in phrasing. - - * cal-xtra.texi, fortran-xtra.texi: Re-order a few things to reduce - some underfull lines in dvi output. - - * emacs-xtra.texi (Introduction): Mention included in info Emacs manual. - - * sending.texi (Mail Sending): Add a tiny bit on mailclient. - - * vc-xtra.texi (Advanced VC Usage): End all menu items with a period. - -2009-07-01 Chong Yidong - - * anti.texi (Antinews): Correct the list of removed platforms. - -2009-06-28 Glenn Morris - - * arevert-xtra.texi: Minor language tweaks. - - * dired-xtra.texi: Minor revisions. - -2009-06-17 Kenichi Handa - - * mule.texi (Charsets): Update the description for the new charset. - (list-character-sets): New findex. - (Language Environments): Add @anchor{Describe Language Environment}. - -2009-06-10 Chong Yidong - - * basic.texi (Moving Point): Fix tag. - - * picture-xtra.texi (Insert in Picture): Use and . - - * mini.texi (Completion Commands): Decapitalize and , and - use camel-case for PageUp and PageDown. - - * display.texi (Scrolling): Decapitalize and , and use - camel-case for PageUp and PageDown. - - * calendar.texi (Scroll Calendar): Decapitalize and . - - * search.texi (Isearch Scroll): Add isearch-allow-scroll to index. - (Isearch Scroll): Decapitalize and . - -2009-06-09 Agustín Martín - - * fixit.texi (Spelling): Set default dictionary. Improve - descriptions (Bug#2554) - -2009-06-08 David Reitter - - * macos.texi (Color panel, Font panel): Remove mention of Save Options, - since saving colors and faces set this way is not implemented. - (Environment variables): Remove mention of mac-fix-env, which is - scheduled to be removed. - -2009-06-04 Chong Yidong - - * custom.texi (Init Examples): Add example of changing load-path. - - * building.texi (Lisp Libraries): Add example of changing - load-path (Bug#3446). - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Further clarifications. - (Setting Mark): Emphasize that C-SPC activates the mark. - -2009-05-28 Chong Yidong - - * mark.texi (Mark): Clarify introduction. Mention disabling Transient - Mark mode. - (Using Region, Persistent Mark): Use "active mark" instead of "active - region". - -2009-05-16 Ari Roponen (tiny change) - - * mule.texi (Select Input Method): Fix typo. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Document completion changes. Some additional - copyedits and rearrangement of entries. - -2009-05-12 Chong Yidong - - * misc.texi (Interactive Shell, Saving Emacs Sessions) - (Shell History Copying, Terminal emulator): Copyedits. - - * xresources.texi (Resources): Simplify descriptions. Shorten - description of editres, which is not very useful these days. - (Table of Resources): Document fontBackend resource. - - * trouble.texi (Quitting): Add other undo bindings to table. - (DEL Does Not Delete): Note that the erasure key is usually labelled - "Backspace". Remove discussion of obscure Xmodmap issue. - -2009-05-07 Chong Yidong - - * files.texi (Visiting): Copyedits. - -2009-05-06 Chong Yidong - - * basic.texi (Inserting Text): Document ucs-insert. - - * mule.texi (International Chars): Define "multibyte". Note that - internal representation is unicode-based. Simplify definition of raw - bytes. Mention ucs-insert. - (Enabling Multibyte): Remove obsolete discussion. Copyedits. - (Language Environments): Add language environments new to Emacs 23. - (Multibyte Conversion): Node deleted. - (Coding Systems): Remove obsolete unify-8859-on-decoding-mode. Don't - mention obsolete emacs-mule coding system. - (Output Coding): Copyedits. - - * emacs.texi (Top): Update node listing. - -2009-05-05 Per Starbäck (tiny change) - - * trouble.texi (Lossage): Use new binding of view-emacs-problems. - -2009-04-28 Stefan Monnier - - * building.texi (Lisp Libraries): `load-library' does offer completion. - -2009-04-28 Chong Yidong - - * frames.texi (Text-Only Mouse): Mention gpm-mouse-mode instead of - t-mouse-mode. Suggested by Per Starbäck (Bug#3126). - -2009-04-25 Eli Zaretskii - - * maintaining.texi (Tags): Clarify text. (Bug#3101) - -2009-04-22 Chong Yidong - - * entering.texi (Entering Emacs): Document initial-buffer-choice. - - * building.texi (Lisp Interaction): Document initial-scratch-message. - -2009-04-18 Juanma Barranquero - - * msdog.texi (Windows Fonts): Fix typos. - - * files.texi (Save Commands): Fix pxref. - -2009-04-18 Chong Yidong - - * files.texi (Save Commands): Mention diff-buffer-with-file. - (Comparing Files): Document diff-buffer-with-file. Suggested by Magnus - Henoch (Bug#3036). - -2009-03-15 Glenn Morris - - * sending.texi (Mail Format): Replace "Sender" with "Message-Id", since - the former is not always used. - (Mail Headers): Use active voice. Add "Mail-reply-to". - Change case of "Id". Avoid repeated "appropriate". - (Mail Aliases): Fix previous change - use an example with a ".", so it - does actually get quoted when expanded. - (Mail Sending): Mailclient is the default on some systems. - (Citing Mail): Mention mail-indentation-spaces. - (Mail Mode Misc): Add an @dfn for "mail signature". - -2009-03-15 Chong Yidong - - * mini.texi (Completion Commands): Describe Emacs 23 completion rules. - (Completion Options): Document read-file-name-completion-ignore-case, - read-buffer-completion-ignore-case, and completion-styles. Remove - description of partial-completion-mode. - -2009-03-14 Glenn Morris - - * sending.texi (Mail Format): Fix typo. Add index entry for - mail-header-separator. - (Mail Headers): Put info about initialization and changing in one place - at the start. Update FCC section for mbox Rmail. Clarify From - section, mention mail-setup-with-from. Clarify Reply-to section. - Add Mail-followup-to and mail-mailing-lists. Clarify References - section. - (Mail Aliases): Update example, make less contentious. - Update for name change of mail-interactive-insert-alias. - (Mail Mode): Remove mention of `%' as a word separator. - (Mail Sending): Mention mail-send-hook. Mention Mailclient. - (Header Editing): Add reply-to, mail-reply-to, and mail-followup-to - commands. Clarify FCC handling. In mail-complete, add reference to - Mail Aliases section, and mention mail-complete-function. - (Citing Mail): Mention mail-yank-ignored-headers and mail-citation-hook. - (Mail Mode Misc): Clarify the mail-signature function. Add basic - signature netiquette. Explain how the mail hooks work when continuing - a composition. - (Mail Amusements): Internationalize the spook section a bit. - Remove the spook mail-setup-hook example, since it doesn't work well. - Mention fortune-file. - (Mail Methods): Mention read-mail-command. - -2009-03-14 David Reitter - - * macos.texi (Mac / GNUstep Basics): Remove references to Prefs panel - and NS resources following recent changes. - -2009-03-10 Jason Rumney - - * msdog.texi (Windows Misc): Remove doc for obsolete variable. Modify - w32-use-visible-system-caret doc to indicate that it should get set - automatically. - (Windows Fonts): Add doc for the uniscribe backend. - -2009-03-08 Dan Nicolaescu - - * maintaining.texi (VC Directory Commands): Fix doc for the x key in - vc-dir. (Bug#2598) - -2009-03-05 Reiner Steib - - * fixit.texi (Spelling): Add turn-on-flyspell. (Bug#2517) - -2009-03-05 Glenn Morris - - * rmail.texi (Rmail Basics): Add reference to sorting. - (Rmail Scrolling, Rmail Motion, Rmail Reply, Rmail Display): - Minor re-wordings. - (Rmail Motion): Mention rmail-next-same-subject. - (Rmail Deletion): Expunging is not the only way to change the numbers. - (Rmail Labels): Labels can also be used in sorting. - (Rmail Summary Edit): Mention rmail-summary-next-same-subject. - (Rmail Display): Mention rmail-mime. - -2009-03-04 Glenn Morris - - * rmail.texi (Rmail Sorting): Add the keybindings associated with each - sort command. Fix `rmail-sort-by-labels' name. Mention sorting from - summary. Mention sorts cannot be undone. - (Rmail Display): Give an example of how to use goto-address-mode. - (Rmail Editing): It's keybindings that are redefined, not commands. - Fix some typos. - (Movemail): Some minor rewording. - (Remote Mailboxes): Emacs movemail supports pop by default. - Fix some minor grammatical issues. The "two alternative ways" to - specify a POP mailbox are really just one. Remove all reference to the - variables rmail-pop-password and rmail-pop-password-required, obsolete - since Emacs 22.1. Clarify the four password steps. Emacs movemail - can support Kerberos. - -2009-03-03 Glenn Morris - - * rmail.texi (Rmail Deletion): Revert previous change, which was - describing the Rmail summary versions. - (Rmail Reply): Give more details of rmail-dont-reply-to-names. - Minor re-wording for rmail-resend. - (Rmail Make Summary): Summaries apply to buffers rather than files. - : Headers includes the subject. - : Give more - details, including prefix arguments. - Mention rmail-summary-by-senders on C-M-f. - Not counting lines might be faster. - (Rmail Summary Edit): More details on the delete commands. - Mention rmail-summary-undelete-many, rmail-summary-bury, and C-M-n/p. - Name the commands bound to the various keys. Mention prefix argument - for searching. - (Rmail Display): Mention rmail-displayed-headers. Fix typo. - Simplify rmail-highlighted-headers description. Update face name. - -2009-03-02 Juanma Barranquero - - * mark.texi (Marking Objects): Fix typo. - -2009-03-01 Chong Yidong - - * abbrevs.texi (Expanding Abbrevs): Mention abbrev-expand-functions - instead of obsolete pre-abbrev-expand-hook. Link to elisp manual. - -2009-03-01 Glenn Morris - - * rmail.texi (Rmail): Fix some typos. Use consistent case in menu. - (Rmail Motion): - M-s searches from the end of messages. - (Rmail Deletion): Minor clarification. Fix numeric argument - description. - (Rmail Inbox): Fix default inbox description. Mention `mbox' by name. - newmail and RMAILOSE files need not be in home-directory. - (Rmail Files): Mention I/O menus are unselectable if no files match. - Mention `MAIL' env-var. - -2009-02-24 Jason Rumney - - * mule.texi (Fontsets): Mention fontset-default, font specs and - fallback fontsets. - (Defining Fontsets): Mention ns and w32 variants of - standard-fontset-spec. Update description of startup fontset to match - Emacs 23 behavior. - (Modifying Fontsets): New section. (Bug#656) - (International): Link to Modifying Fontsets. - -2009-02-23 Adrian Robert - - * macos.texi (Mac / GNUstep Basics, Mac / GNUstep Customization): - Mention ns-extended-platform-support-mode. - -2009-02-22 Karl Berry - - * macos.texi (Mac / GNUstep Customization): One more duplicate "the". - -2009-02-19 Juanma Barranquero - - * basic.texi (Moving Point, Position Info): - * files.texi (Visiting): - * mini.texi (Completion Options): - * text.texi (HTML Mode): Remove duplicate words. - -2009-02-20 Glenn Morris - - * rmail.texi: Minor updates for mbox rather than Babyl. - -2009-02-17 Karl Berry - - * emacs.texi (Top): Add @insertcopying before master menu. (Bug#1988) - -2009-02-17 Richard M Stallman - - * anti.texi (Antinews): Mention Babyl format. - - * emacs.texi (Top): Delete `Out of Rmail' from subnode menu. - - * rmail.texi: Update for mbox format. - Various small fixes, as well as the following. - (Out of Rmail): Node deleted. - (Rmail): Update menu. - (Rmail Files): Comment out set-rmail-inbox-list. - Document rmail-inbox-list instead. - (Rmail Output): Substantial changes since C-o is now - rmail-output-as-seen and o is rmail-output. - (Rmail Attributes): Delete `stored', add `retried'. - (Rmail Display): Editing headers works in all cases. - -2009-02-17 Glenn Morris - - * basic.texi (Position Info): M-x count-lines-region is not always on - M-=. (Bug#2269) - -2009-02-09 Glenn Morris - - * calendar.texi (Holidays, Displaying the Diary): Update for new marker - defaults. - -2009-02-07 Eli Zaretskii - - * rmail.texi (Rmail Coding) : Remove stale - documentation of possible problems with redecoding. - -2009-02-03 Glenn Morris - - * rmail.texi (Out of Rmail): Mention b2m.pl. - -2009-01-31 Glenn Morris - - * rmail.texi (Out of Rmail): Correct b2m location. - -2009-01-27 Chong Yidong - - * fixit.texi (Undo): Update undo limit values. - -2009-01-27 Glenn Morris - - * emacs.texi (Top): Fix Antinews menu entry. - -2009-01-25 Karl Berry - - * text.texi (Foldout): Use @itemize @w{} to make an itemize - item with no marker, instead of the syntactically incorrect - @itemize @asis. - -2009-01-25 Juri Linkov - - * building.texi (Grep Searching): Fix index entry for lgrep. - -2009-01-24 Eli Zaretskii - - * msdog.texi (Windows Printing): Add an index entry for Ghostscript. - -2009-01-21 Adrian Robert - - * macos.texi (Preferences Panel): Update description of font setting to - reflect that prior frame selection is no longer needed. - -2009-01-20 Nick Roberts - - * building.texi (Debuggers): Revert some of 2008-10-31 change to - raise GUD subsections. - -2009-01-15 Glenn Morris - - * ack.texi (Acknowledgments): Another update based mainly on AUTHORS. - -2009-01-10 Glenn Morris - - * ack.texi (Acknowledgments): Some more updates based on AUTHORS. - -2009-01-04 Chong Yidong - - * display.texi (Visual Line Mode): M-] and M-[ no longer move by - logical lines. - -2008-12-29 Juri Linkov - - * mini.texi (Minibuffer History): Add a link to `Isearch Minibuffer'. - - * text.texi (Fill Commands): Replace `M-s' with `M-o M-s'. - -2008-12-28 Chong Yidong - - * misc.texi (Goto Address mode): Rename from Goto-address. Refer to - goto-address-mode instead of goto-address. - - * rmail.texi (Rmail Display): Goto-address renamed to Goto Address - mode. - - * emacs.texi (Top): Update node listing. - -2008-12-26 Eli Zaretskii - - * custom.texi (Directory Variables): Explain what is a "project". - Add indexing. Improve wording. Add a footnote about using - _dir-locals.el on MS-DOS. - -2008-12-24 Dan Nicolaescu - - * files.texi (Misc File Ops): Mention chmod as an alias for - set-file-modes. - -2008-12-24 Martin Rudalics - - * help.texi (Help): Fix typos and reword. - (Help Summary): Add entries for C-h n and C-h r, reorder - entries, and do some minor fixes. - (Name Help): Say that C-h F works for commands only. - (Misc Help): Say that view-lossage displays 300 keystrokes. - -2008-12-20 Glenn Morris - - * ack.texi (Acknowledgments): General update based on AUTHORS, - including removal of some stuff no longer distributed. - -2008-12-19 Agustin Martin - - * fixit.texi: Mention hunspell - -2008-12-19 Glenn Morris - - * ack.texi (Acknowledgments): Small grammar fix. - Consolidate explanatory text at start. - - * display.texi (Text Display): - * indent.texi (Indentation): Use @acronym with ASCII. - -2008-12-18 Glenn Morris - - * ack.texi: Various small updates and fixes. - -2008-12-18 Juri Linkov - - * search.texi (Word Search): Replace `C-s RET C-w' with `M-s w RET' - as a key binding to start a forward nonincremental word search. - Replace `C-r RET C-w' with `M-s w C-r RET' as a key binding to start - a backward nonincremental word search. Add index for `M-s w' - `isearch-forward-word'. - (Regexp Search): Add a short summary of regexp key commands like - in the node "Basic Isearch". - (Other Repeating Search): Fix typo. - -2008-12-14 Vinicius Jose Latorre - - * misc.texi (PostScript Variables): Fix doc. - -2008-12-10 Chong Yidong - - * programs.texi (Program Modes): Mention Ruby mode. - -2008-12-10 Dan Nicolaescu - - * misc.texi (emacsclient Options): Describe what an empty string - argument does for --alternate-editor. - -2008-12-09 Frank Schmitt - - * cmdargs.texi (Font X): Distinguish between client-side and - server-side fonts. List valid Fontconfig properties. Add reference to - Fontconfig manual. List valid GTK font properties. Explain use of - fc-list. - -2008-12-09 Chong Yidong - - * cmdargs.texi (Font X): Move discussion of quoting to top. - -2008-12-06 Glenn Morris - - * maintaining.texi (Old Revisions): Improve previous change. - -2008-12-05 Richard M Stallman - - * anti.texi (Antinews): Minor fixes. - -2008-12-03 Glenn Morris - - * maintaining.texi (Old Revisions): Fix diff-switches description. - -2008-12-01 Martin Rudalics - - * emacs.texi (Top): Fix typo. - -2008-11-30 Chong Yidong - - * misc.texi (Document View): Explain dependence on gs at the top. - Copyedits. - - * emacs.texi (Top): Add DocView nodes to detailed node listing. - - * programs.texi (Other C Commands): Document hide-ifdef-shadow. - (Comment Commands): Discuss region-active behavior of M-; first. - -2008-11-29 Martin Rudalics - - * display.texi (Line Truncation): Add reference to Continuation - Lines. - - * windows.texi (Pop Up Window): Mention split-height-threshold - and split-width-threshold. - (Split Window): Add reference to Continuation Lines. - -2008-11-28 Adrian Robert - - * macos.texi: Change references to "Mac" to "Mac / GNUstep". - (GNUstep Support): New node. - * anti.texi: - * emacs.texi: - * msdog.texi: Change reference to Mac OS node to Mac OS / GNUstep. - - -2008-11-28 Richard M Stallman - - * misc.texi (Dissociated Press): Minor cleanups. - - * dired.texi (Image-Dired): Avoid passive. - -2008-11-28 Eli Zaretskii - - * anti.texi (Antinews): Add stuff about Unicode vs emacs-mule - representation. - -2008-11-26 Richard M. Stallman - - * files.texi (Visiting): Rewrite paragraph for clarity. - - * buffers.texi (Select Buffer): Rewrite paragraphs using active voice. - -2008-11-25 Alan Mackenzie - - * programs.texi (Moving by Parens): Clarify that parens inside strings - and comments are ignored, and that the commands assume the starting - point isn't in a string or comment. - -2008-11-26 Adrian Robert - - * macos.texi: Add Prev/Next/Top pointers to all nodes. - (Mac Basics): Merge in Grabbing Environment Variables from earlier - version. - (Mac Customization): Rewrite Preferences Panel section and merge in to - this node, add Open files by dragging to an Emacs window. - - * emacs.texi: Remove TOC reference to Mac Preferences Panel section. - -2008-11-26 Chong Yidong - - * files.texi (Misc File Ops): Document set-file-modes. - - * windows.texi (Split Window): Document integer values of - truncate-partial-width-windows. - - * text.texi (Text): Simplify description of markup languages. - (TeX Mode): Simplify introduction. Mention BibTeX mode. - (TeX Editing): Note that `""' inserts one `"' character. - (HTML Mode): Note in the introduction that XML mode is an alias for - SGML mode. Mention nXML mode. - -2008-11-25 Chong Yidong - - * building.texi (Watch Expressions): Fix typo. - -2008-11-24 Chong Yidong - - * files.texi (Visiting): Document new behavior of - confirm-nonexistent-file-or-buffer. - - * buffers.texi (Select Buffer): Document - confirm-nonexistent-file-or-buffer. - - * picture-xtra.texi (Picture Mode): Use picture-mode instead of - edit-picture. - - * text.texi (Text): Simplify introduction. Discard mention of `M-x - edit-picture', since that is just an alias for picture-mode. - (Sentences): Note that repeated M-@ extends the region. - (Pages): Make terminology more consistent. Link to Regexps node. - (Longlines): Discuss relationship with Visual Line mode. - (Text Mode): Remove extraneous discussion of other modes, since they - were already introduced in the parent node. - -2008-11-23 Chong Yidong - - * anti.texi (Antinews): Rewrite. - - * entering.texi (Exiting): Mention "minimize" terminology. - - * frames.texi (Frame Commands): Mention "minimize" terminology. - - * cmdargs.texi (Font X): Document Fontconfig and GTK font specification - formats. - (Icons X): Mention "minimize" terminology and use of icons in taskbar. - (Misc X): Don't document useless -hb option. - -2008-11-22 Juri Linkov - - * dired.texi (Dired Navigation): Change normal file name search option - from `non-nil' to `t'. Add `dwim' option. - -2008-11-22 Juri Linkov - - * custom.texi (Directory Variables): Rename ".dir-settings.el" to - ".dir-locals.el". Rename `define-project-bindings' to - `dir-locals-set-class-variables'. Rename `set-directory-project' to - `dir-locals-set-directory-class'. - -2008-11-22 Lute Kamstra - - * buffers.texi (Select Buffer): Index goto-line. - * basic.texi (Moving Point): Mention the use of a numeric prefix - argument with goto-line and refer to Select Buffer for the use of a - plain prefix argument. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * emacs.texi, emacs-xtra.texi: Relicense under FDL 1.3 or later. - -2008-11-17 Chong Yidong - - * custom.texi (Minor Modes): Define mode commands and mode variables - more precisely. Recommend using mode commands instead of setting - variables directly. Put minor modes in a list, and add more modes. - (Easy Customization): Use "init file" instead of .emacs. - (Customization Groups): Update to new Custom buffer appearance. - (Saving Customizations): Copyedits. Update example. - (Variables): Give example of variable type-sensitivity. - (Examining): Update example. - (Hooks): Copyedits. - (Specifying File Variables): Use C comments instead of an artificial - Lisp for the example. - (Keymaps): Move internals discussion to Prefix Keymaps. - (Rebinding): Remove redundant paragraph (stated in Key Binding). - (Init Rebinding): Document kbd macro. - (Init File): Link to Find Init. - - * mark.texi (Using Region): Document Delete Selection Mode more - thoroughly. - - * frames.texi (Mouse Commands): Move most of the description of Delete - Selection Mode to Using Region, and link to it. - (Clipboard): Note that paste is bound to clipboard-yank. - - * building.texi (Compilation): Document first-error value of - compilation-scroll-output. - (Compilation Mode): Note that compilation-auto-jump-to-first-error - works as soon as an error is available. Suggested by Juri Linkov. - - * mini.texi (Passwords): New node. - - * files.texi (Remote Files): Link to Passwords node. - - * emacs.texi (Top): Update node listings. - -2008-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Some updating of credits. - - * emacs.texi (Acknowledgments): Add a couple more names. - - * dired.texi (Dired Deletion): Document delete-by-moving-to-trash. - - * files.texi (Directories): Describe delete-directory in text. - (Misc File Ops): Document use of trash. - -2008-11-16 Juanma Barranquero - - * macos.texi (Mac Customization): Fix typos. - -2008-11-14 Chong Yidong - - * macos.texi (Mac OS): Move Cocoa manual from ns-emacs.texi to here, - replacing previous contents. Numerous copyedits to adapt ns-emacs to - the conventions of the main Emacs manual. - - * emacs.texi (Top): Update node listings. - -2008-11-12 Chong Yidong - - * cmdargs.texi (Emacs Invocation): Link to Emacs Server. Note that - command-line-args is processed during startup. - (Action Arguments): Correctly describe how file arguments interact with - the startup screen. Link to Lisp Interaction for scratch buffer. - (Initial Options): Link to Command Example for -batch option. - (Environment): Document initial-environment. - - * entering.texi (Entering Emacs): Note that inhibit-startup-screen - can't be changed in the site-start file. - -2008-11-07 Chong Yidong - - * dired.texi (Dired): Mention C-x C-d too. - (Dired Enter): Document M-n in the Dired minibuffer. - (Dired Navigation): Explain dired-goto-file more clearly. Document - dired-isearch-filenames. - (Dired Deletion): Remove unnecessary "expunged" terminology. - (Flagging Many Files): & is now rebound to `% &'. - (Shell Commands in Dired): Document dired-do-async-shell-command. - Clarify how multi-file arguments are passed. - (Misc Dired Features): Document dired-do-isearch. - -2008-11-06 Chong Yidong - - * entering.texi (Entering Emacs): Document inhibit-startup-screen. - -2008-11-03 Chong Yidong - - * search.texi (Other Repeating Search): Remove obsolete findex entries. - -2008-11-01 Chong Yidong - - * programs.texi (Program Modes): Link to Program Indent node. - (Left Margin Paren): Explain consequences of changing - open-paren-in-column-0-is-defun-start more concisely. - (Which Function, Program Indent, Info Lookup): Minor edits. - (Basic Indent): If region is active, TAB indents the region. - (Multi-line Indent): If region is active, TAB indents the region. Note - that indent-region is useful when Transient Mark mode is off. - (Matching): The delimiter at the cursor is highlighted---the character - changes color. - (Symbol Completion): Link to Completion node. - - * misc.texi (Invoking emacsclient): Describe how to use Emacs server in - a strictly text-only system. - - * abbrevs.texi (Saving Abbrevs): Note that abbrev file is not loaded in - batch mode. - -2008-11-01 Richard M. Stallman - - * misc.texi (Document View): Major rewrite. - - * maintaining.texi (Types of Log File): Change logs are older than - version control. - (VCS Concepts): Simplify and rearrange. - (Version Control Systems): Make it clear that Linux is only the kernel. - (VC Mode Line): Shorten reference to menu item. - (Basic VC Editing): Clarify VC fileset. Shorten and simplify. - (VC Directory Mode): Minor cleanup. - Unchanged files are hidden, not omitted. - (VC Directory Commands): Shorten and simplify. - (Change Log Commands): New node, split from Change Logs. - (VC Directory Buffer): New node, split from VC Directory Mode. - -2008-10-31 Chong Yidong - - * misc.texi (Document View): Renamed from Document Files, moved here - from files.texi. - - * files.texi (Version Control): Moved to maintaining.texi. Subnodes - moved as well. - (Document Files): Moved to misc.texi. - - * maintaining.texi (Change Log): Document log-edit-insert-changelog and - vc-update-change-log. - (Version Control): Move here from files.texi. - (Format of ChangeLog): Make it a subnode of Change Log. - - * emacs.texi (Top): Update node listing. - -2008-10-31 Tassilo Horn - - * files.texi (Files): Add a section about document - files (doc-view-mode). - -2008-10-31 Chong Yidong - - * building.texi (Compilation Mode): Document - compilation-auto-jump-to-first-error. - (Debuggers): Lower GUD subsections to subsubsections. - (Starting GUD): Add cindex. - (Lisp Interaction): Note that scratch is no longer the initial buffer. - -2008-10-30 Chong Yidong - - * indent.texi (Indentation): Link to Program Indent. - - * misc.texi (Invoking emacsclient): If Emacs has no available frame, it - now uses emacsclient's terminal. - -2008-10-29 Chong Yidong - - * mark.texi (Using Region): Document use-empty-active-region. - - * emacs.texi (Top): Update node listings. - - * misc.texi (Emacs Server): Rewrite. Document daemon-mode. Don't - mention obsolete emacs.bash script. - (Invoking emacsclient): Rewrite, moving optional arguments to - emacsclient Options. - (emacsclient Options): New node. Document server-use-tcp and - server-host. - -2008-10-28 Chong Yidong - - * indent.texi (Indentation): Replace list with paragraphed text, - putting description of syntax-driven indentation first. Document new - effect of active regions on tab. - (Tab Stops): Note that editable tab stops affect indentation commands. - -2008-10-27 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document -daemon=SERVER_NAME. - -2008-10-23 Chong Yidong - - * custom.texi (Function Keys): Note that modified keypad keys are not - translated. - - * basic.texi (Arguments): Explain how to insert multiple digits. - -2008-10-22 Michael Albinus - - * files.texi (Remote Files): Precise selection of default method. - Rewrite paragraph about disabling remote file names. - -2008-10-22 Chong Yidong - - * search.texi (Special Isearch): Document M-TAB is isearch. - - * files.texi (VC Mode Line): Use @kbd instead of @key for mouse - command. - - * frames.texi: Use @kbd instead of @key for mouse commands throughout. - -2008-10-22 Tassilo Horn - - * emacs.texi (Acknowledgments): Added myself to Acknowledgments - section. - -2008-10-21 Chong Yidong - - * vc1-xtra.texi: Move nodes VC Directory Mode and VC Directory Commands - to files.texi. Move contents of vc2-xtra.texi here. - - * vc2-xtra.texi: File removed. - - * vc-xtra.texi (Advanced VC Usage): Remove VC Directory Mode and VC - Directory Commands from the submenu. Don't include deleted file - vc2-xtra.texi. - - * files.texi (Visiting): Document find-file-confirm-nonexistent-file. - (Version Control): Add VC Directory Mode and VC Directory Commands to - the submenu. - (Why Version Control?): Use table format. - (Version Control Systems): Note that Meta-CVS support is gone. - (VCS Concepts): Note precisely when VC started supporting filesets. - Remove bogus xref to CVS Options node. - (Types of Log File): Copyedits. - (VC Mode Line): Document tooltips and mouse-1 on VC indicator. - (Basic VC Editing): Content moved from Selecting A Fileset and Doing - The Right Thing. - (Selecting A Fileset, Doing The Right Thing): Nodes deleted. - (Log Buffer): Reorganize node, putting C-c C-c description first. - (Old Revisions): Use CVS for example, not RCS. - (Secondary VC Commands): Remove VC Directory Mode and VC Directory - Commands from the submenu, putting them under Version Control. - (VC Directory Mode): Move node contents here from vc1-xtra.texi; we - need to include it in the manual unconditionally, since it is now - crucial to using distributed version control systems. - (Comparing Files): Note that diff uses the minibuffer, and that the - output is shown using Diff mode. - (Diff Mode): Explain what "patch" and "hunk" mean. Document - diff-update-on-the-fly, diff-refine-hunk, and - diff-show-trailing-whitespaces. - (File Archives): Add rar support. - - * major.texi (Choosing Modes): Make mode selection sequence more - obvious by describing the steps in order of priority. Note that - magic-mode-alist is nil by default. Document - magic-fallback-mode-alist. - -2008-10-20 Chong Yidong - - * frames.texi (Mouse References): Copyedits. - -2008-10-20 Tassilo Horn - - * ack.texi (Acknowledgments): Add myself as doc-view author. - -2008-10-20 Eli Zaretskii - - * frames.texi (Dialog Boxes): Add @cindex entries. - -2008-10-20 Chong Yidong - - * frames.texi (Dialog Boxes): Clarify description of GTK+ file chooser. - (Text-Only Mouse): Copyedit. - -2008-10-19 Chong Yidong - - * frames.texi: Use @key throughout for mouse clicks. - (Cut/Paste Other App): Document yank-pop-change-selection. - (Secondary Selection): Fix modified mouse click syntax. - (Clipboard): Describe Cut, Copy and Paste commands. - (Mouse References): Not all references are in read-only buffers. - Copyedits. - (Creating Frames): Add xref to Init File. - (Frame Commands): Add xref to Exiting. - (Scroll Bars): Document GTK vs toolkit behavior. - -2008-10-15 Chong Yidong - - * files.texi (Version Control): Copyedits. Add Bazaar. - (Version Control Systems): List different VCS's using an itemized list. - Add Bazaar. - (VCS Concepts): Copyedits. Tweak description of file merging. - - * frames.texi (Mouse Commands, Cut/Paste Other App): Rewrite. - (Cut/Paste Other App): Document select-active-regions and - x-select-enable-primary. - -2008-10-13 Chong Yidong - - * mark.texi (Shift Selection): Correct case in node name. - - * emacs.texi (Top): Update node order in Mark chapter. - -2008-10-12 Eli Zaretskii - - * msdog-xtra.texi (MS-DOS): Fix bad pxref. - - * mini.texi (Minibuffer File): Fix markup in last change. Refer to - elsewhere in the manual instead of describing yet again the intricacies - of $HOME on MS-Windows and MS-DOS. - -2008-10-12 Chong Yidong - - * mini.texi (Minibuffer File): Add xref to File Names. - (Minibuffer File): Add discussion of `~' in file names. Add - insert-default-directory index reference. - - * files.texi (File Names): Reorganize description. - (Visiting): Add xref to Mode Line. Copyedits. - (Save Commands): Mention prefix behavior of C-x C-s. - (Numbered Backups): Node deleted. - (Backup Names): Contents of Numbered Backups moved here. State default - of version-control variable. - (Reverting): Copyedits. - (Version Control): Add additional version control systems. - - * emacs.texi (Top): Delete Numbered Backups node. - - * cmdargs.texi (General Variables): Change Numbered Backups xref to - Backup Names. - (Initial Options): Document renamed variable inhibit-startup-screen. - -2008-10-11 Romain Francoise - - * kmacro.texi (Edit Keyboard Macro): Lossage is now 300 keys. - -2008-10-11 Chong Yidong - - * buffers.texi (Buffers): Add xrefs to Mode Line and Lisp Interaction. - (Select Buffer): Mention use of minibuffer history. Describe default - value of default-major-mode. Mention that C-x 4 b selects the other - window. - (List Buffers): Document CRM indicators in the order they appear. - (Kill Buffer): Document new command kill-matching buffers. - (Several Buffers): Move explanation of the relationship between buffer - list and buffer menu to the top. - (Indirect Buffers): Document new variable clone-indirect-buffer-hook. - -2008-10-10 Chong Yidong - - * entering.texi (Exiting): Document change of C-x C-c to - save-buffers-kill-terminal. Document kill-emacs. - -2008-09-30 Eli Zaretskii - - * mule.texi (Coding Systems): Don't mention codepage-setup. - - * msdog-xtra.texi (MS-DOS Printing, MS-DOS and MULE): No need to create - cpNNN coding systems anymore. - (MS-DOS and MULE): Don't mention code-pages.el. Don't mention support - for unibyte mode. Don't mention line-drawing characters. Don't - mention dos-unsupported-char-glyph. - -2008-09-25 Chong Yidong - - * search.texi (Search): Shorten introduction. - (Basic Isearch): Add command table. Discuss reverse isearch and - isearch highlighting. - (Repeat Isearch): Move lazy highlighting discussion here. Add search - ring to cindex. - (Special Isearch): Move input methods discussion here. - (Non-ASCII Isearch): Node deleted, merged with Special Isearch. - (Isearch Yank): Node deleted, and contents moved into Basic Isearch and - Repeat Isearch. - (Isearch Minibuffer): New node. - (Word Search): Document new word search commands. - (Regexp Example): Simplify example using sentence-end-base variable. - (Replace): Reword introduction. - (Unconditional Replace): Remove unnecessary example. - (Other Repeating Search): Document new `M-s o' binding. - - * emacs.texi (Top): Update node listings. - -2008-09-22 Juanma Barranquero - - * emacs.texi (Top): Remove Kill Errors from menu. - -2008-09-22 Chong Yidong - - * kmacro.texi (Basic Keyboard Macro): Make F3 and F4 the preferred - interface for defining macros. Simplify examples. Note that C-g quits - macro definitions. - (Keyboard Macro Counter): Document using F3 to insert counter. Give - usage example. - (Keyboard Macro Query): Organize query responses in a table. - - * fixit.texi (Fixit): Favor C-/ keybinding for undo throughout. Link - to Erasing node. - (Undo): Reorganize paragraphs for logical flow. Move keybinding - rationale to a footnote. - (Kill Errors): Remove node, due to redundancy with Erasing. - (Spelling): Move discussion of flyspell to end. Note new behavior of - M-$ in active region. Remove non-ispell-specific keybindings from - table. - -2008-09-21 Dan Nicolaescu - - * cmdargs.texi (Initial Options): Document --daemon. - -2008-09-20 Glenn Morris - - * files.texi (Numbered Backups): Mention that some modes set - version-control. - -2008-09-20 Jim Blandy - - * files.texi (Numbered Backups): Reference File Variables, as well. - Remove discussion of Rmail's implementation. - -2008-09-06 Chong Yidong - - * misc.texi (Recursive Edit): Note that top-level exits active - minibuffers. - - * trouble.texi (Quitting): Likewise. - -2008-08-31 Chong Yidong - - * emacs.texi (Top): Add Temporary Face Changes xref. - - * display.texi (Display): Move Temporary Face Changes node to just - after Standard Faces. - (Scrolling): Document recenter-top-bottom instead of recenter. - (Horizontal Scrolling): Move auto hscroll discussion to the top. - (Faces, Standard Faces, Temporary Face Changes, Useless Whitespace) - (Display Custom): Copyedits. - (Optional Mode Line): Document display-battery-mode. - -2008-08-27 Romain Francoise - - * custom.texi (Directory Variables): Minor fix. - -2008-08-27 Glenn Morris - - * cal-xtra.texi (Advanced Calendar/Diary Usage): Tweak some menu - descriptions. - (Calendar Customizing): Tweak layout description. - Move calendar-today-marker and calendar-today face to the other - markers. Condense calendar-star-date and calendar-mark-today - description. - (Holiday Customizing): Add oriental and solar holidays. - Add index entries for Baha'i, Christian, Hebrew and Islamic holidays. - Fix holiday-float description. Use zerop in examples. Be less verbose. - (Date Display Format): Change ISO format. Be less verbose. - (Diary Customizing): Mention day and month abbrev arrays. - Mention the date-form variables by name. Update European example. - (Non-Gregorian Diary): Change node name. Mention Baha'i functions. - Condense examples. Mention diary-entry-symbols by name. - Condense table for insertion commands. - (Fancy Diary Display): Mention diary-include-string and - diary-sexp-entry-symbol. Condense example. Add Chinese, Coptic, - Ethiopic, Persian date functions. Condense descriptions. - - * calendar.texi (Format of Diary File): Mention diary-nonmarking-symbol. - (Adding to Diary): Adapt for changed node name. - -2008-08-26 Glenn Morris - - * cal-xtra.texi (Non-Gregorian Diary Entries): New name for - node "Hebrew/Islamic Entries". - - * calendar.texi (Specified Dates): Fix names of iso functions. - (General Calendar): There may not be another window. - (Writing Calendar Files, Holidays): Tweak intro. - (Holidays): Mention Baha'i and Chinese holidays. - (Sunrise/Sunset): Add M-x calendar-sunrise-sunset-month. - (Lunar Phases): Remove incorrect reference to calendar-time-zone. - (To Other Calendar): Add calendar-print-other-dates. - Refer to "graphic display" rather than "X. - (From Other Calendar): Add calendar-bahai-goto-date. Fix reference. - (Displaying the Diary): Fix whitespace after reference. - Fix `diary-number-of-entries' reference. - (Date Formats): Explicitly mention that day names can be abbreviated. - (Adding to Diary): Add some references to other sections. - (Special Diary Entries): Fix reference. - (Appointments): Simplify appt-message-warning-time entry. - Clarify where times must be. - (Importing Diary): Comment out icalendar paragraph that does not apply. - (Time Intervals): Simplify entry for timeclock-ask-before-exiting. - -2008-08-23 Glenn Morris - - * fortran-xtra.texi (Fortran): Change description of free form and - fixed form a bit. Mention hideshow and imenu. - (Fortran Motion): Mention fortran-end-of-subprogram, - fortran-beginning-of-subprogram, fortran-mark-do, fortran-mark-if. - (Fortran Indent): Minor re-word. - (ForIndent Commands): Mention fortran-fill-paragraph and - fortran-fill-statement. - (ForIndent Cont): Mention fortran-tab-mode-string. - (Fortran Comments): Mention fortran-comment-line-start-skip. - (Fortran Columns): Mention font-locking. - (Fortran Abbrev): Word syntax not relevant with new-style abbrev. - -2008-08-23 Johan Bockgard - - * basic.texi (Moving Point): Fix / confusion. - -2008-08-22 Chong Yidong - - * mini.texi (Minibuffer): Simplify introduction. - (Minibuffer File): Document tilde in minibuffer filenames. - (Minibuffer Edit): Mention that the prompt is read-only. Describe how - to enter tabs, spaces, and question marks. Describe behavior of C-a. - (Completion Example): Update example to current command list. - (Completion Options): Document `lazy' value of completion-auto-help. - Update contents of completion-ignored-extensions. - (Minibuffer History): Describe "future history" list. State default - value of history-delete-duplicates. - -2008-08-21 Glenn Morris - - * fortran-xtra.texi (Fortran Columns): Document `fortran-line-length'. - (Fortran Comments): Replace fortran-indent-comment with comment-dwim. - -2008-08-17 Chong Yidong - - * regs.texi (Registers): Clarify valid register names. - (RegPos): Note that buffer is saved and restored too. - (RegText): Note that mark is reactivated/deactivated. - (RegConfig): Xref to Windows node. - -2008-08-16 Chong Yidong - - * basic.texi (Inserting Text): Provide command name for C-q. - - * killing.texi (Killing): Copyedit. Define read-only text. - (Deletion): DEL and C-d were already explained in Erasing; xref there. - (Killing by Lines): Copyedit. - (Other Kill Commands): Move M-w description here. - (Yanking): Move M-w to Other Kill Commands. - (Kill Ring): Also mention saving text in registers. Link to Text - Properties in elisp manual. - (Accumulating Text): Copyedit. - (CUA Bindings): Shift selection is now the default. - -2008-08-12 Teodor Zlatanov - - * maintaining.texi (Change Log): Mention next-error is available. - -2008-08-10 Glenn Morris - - * cal-xtra.texi (Calendar Customizing): Mention whitespace variables - and intermonth text. - (Holiday Customizing): Add holiday-chinese. - -2008-08-08 Eli Zaretskii - - * files.texi (Log Buffer, Diff Mode): Fix last changes. Add indexing. - -2008-08-07 Dan Nicolaescu - - * files.texi (Log Buffer): Describe C-c C-d. - (Diff Mode): Describe C-x 4 A. - -2008-08-06 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode): Fix last change. - -2008-08-06 Dan Nicolaescu - - * files.texi (Old Revisions): Update the keys used by vc-annotate and - describe the new bindings to show the changeset diff, toggle annotation - visibility, show revisions. - (VC Status): Describe key bindings for modifying the change comments, - displaying changeset diffs and annotations. - - * vc1-xtra.texi (VC Directory Mode): Talk about multiple VC systems. - -2008-08-05 Nick Roberts - - * vc1-xtra.texi (VC Directory Mode): Fix typo. - -2008-08-02 Eli Zaretskii - - * vc1-xtra.texi (VC Directory Mode, VC Directory Commands): Fix English - and wording. - -2008-08-02 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Fix and improve the info about - marking/unmarking. Add descriptions for the multiple file search - commands. Improve some old info. - -2008-07-31 Chong Yidong - - * display.texi (Visual Line Mode): New node. - - * basic.texi (Inserting Text): Move DEL to deletion node. - (Moving Point): Add additional alternative key bindings. Describe - line-move-visual. - (Erasing): Describe DEL. - (Basic Undo, Blank Lines, Arguments): Copyedit. - (Continuation Lines): Mention Visual Line mode. - (Position Info): Move extended discussion to mule.texi. - - * mule.texi (International Chars): Describe C-x =. - - * emacs.texi (Top): Add Visual Line Mode node. - -2008-07-31 Dan Nicolaescu - - * emacs.texi: Remove VMS support. - -2008-07-30 Dan Nicolaescu - - * vc1-xtra.texi (VC Directory Mode): Update the display format and fix - the vc-dir command name. - -2008-07-27 Dan Nicolaescu - - * xresources.texi: Remove mentions of Mac Carbon. - -2008-07-19 Andreas Schwab - - * ns-emacs.texi: Move to ../misc. - -2008-07-15 Chong Yidong - - * entering.texi (Exiting): Don't describe text-only terminals as the - default. Describe the new startup screen. - (Exiting): Describe how to kill Emacs first. Change description of - iconification to handle modern window systems. - -2008-07-15 Adrian Robert - - * ns-emacs.texi: New file, documents features of Emacs port under - NeXTstep windowing. - -2008-07-15 Chong Yidong - - * entering.texi (Entering Emacs): Update prev node. - - * glossary.texi (Glossary): Remove xref to Text Characters. - - * commands.texi (User Input): Rewrite. Describe Emacs' behavior - directly, rather than in the context of ASCII. Move description of - special properties of modifier key to new Modifier Keys node. - (Keys): Copyedit. - (Text Characters): Delete node. Multibyte is the default nowadays, and - the node contents are obsolete. - - * custom.texi (Modifier Keys): New node. - - * emacs.texi (Top): Update node list. - -2008-07-13 Chong Yidong - - * emacs.texi (Intro): Increase conciseness slightly. Remove paragraph - saying that Emacs provides menus and mouse support (which is par for - the course). - - * screen.texi (Screen): Copyedit. Define "buffer" and "current buffer" - early on. - (Point): Copyedit. Relegate historical trivia to a footnote. - (Mode Line): Explain mode-line format more consistently. - (Menu Bar): Copyedit. - -2008-06-27 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): - * calendar.texi (Lunar Phases): Update for lunar.el name changes. - -2008-06-26 Chong Yidong - - * mark.texi (Shift selection): New node. - (Mark): Copyedits. - (Persistent Mark): Move to the end of the chapter. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Add an entry for gud-gdb. - (GDB Graphical Interface): Explain that gud-gdb is now needed for text - command mode. - -2008-06-17 Glenn Morris - - * calendar.texi: Fix references to mouse-2 and mouse-3 in calendar. - -2008-06-17 Nick Roberts - - * building.texi (Starting GUD): Expand on remote debugging. - (Other GDB-UI Buffers): Mention new keyboard bindings. - -2008-06-15 Glenn Morris - - * gnu.texi: Use a verbatim license for this invariant section, - as per etc/GNU. - -2008-06-13 Daniel Engeler - - * emacs.texi, misc.texi: Add documentation about serial port access. - -2008-06-13 Glenn Morris - - * emacs-xtra.texi, emacs.texi: Update Back-Cover text per - maintain.info. - -2008-06-05 Miles Bader - - * display.texi (Temporary Face Changes): Update to reflect function - renamings in face-remap.el. - -2008-06-04 Miles Bader - - * display.texi (Temporary Face Changes): Add - `adjust-buffer-face-height'. Rewrite description of - `increase-buffer-face-height' and `decrease-default-face-height' now - that they aren't bound by default. - -2008-06-03 Miles Bader - - * display.texi (Temporary Face Changes): New node. - -2008-05-31 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Fix text added on 2008-05-29. - -2008-05-31 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Simplify. - -2008-05-30 Glenn Morris - - * cal-xtra.texi (Fancy Diary Display): Update for - diary-display-function replacing diary-display-hook. - -2008-05-29 Drew Adams - - * msdog.texi (Windows Keyboard): Add descriptions of - w32-register-hot-key and w32-unregister-hot-key. - -2008-05-21 Tom Tromey - - * custom.texi (Directory Variables): Grammar fix. Link to Safe File - Variables node. - -2008-05-19 Tom Tromey - - * custom.texi (Variables): Add Directory Variables to menu. - (Directory Variables): New node. - -2008-05-16 Eric S. Raymond - - * vc2-xtra.texi: Modify an example so it reflects what vc.el now does. - -2008-05-15 Eric S. Raymond - - * vc2-xtra.texi, emacs.texi, files.texi: Snapshots node renamed to - Revision Tags and rewritten. Section now uses modern terminology, - (tags rather than snapshots) and describes post-SCCS systems more - accurately. - -2008-05-10 Eli Zaretskii - - * msdog.texi (Windows Files): Update documentation of - w32-get-true-file-attributes. - -2008-05-09 Eric S. Raymond - - * files.texi, vc-xtra.texi, vc1-xtra.texi: Document the new VC - directory mode. - -2008-05-08 Chong Yidong - - * killing.texi (Appending Kills): Remove a strangely off-topic index - entry "television". - -2008-05-07 Eric S. Raymond - - * ack.texi, files.texi, vc2-xtra.texi: Meta-CVS is no longer supported. - -2008-05-02 Eric S. Raymond - - * emacs/buffers.texi, emacs/files.texi (Version-control): - vc-toggle-read-only is no longer a good idea... - -2008-04-29 Glenn Morris - - * cal-xtra.texi (Sexp Diary Entries): Clarify diary-float. - -2008-04-22 Juri Linkov - - * dired.texi (Subdirectories in Dired): Describe using `^' - to return to the parent directory. - -2008-04-22 Nick Roberts - - * building.texi (GDB-UI Layout, Other GDB-UI Buffers): Update for - recent changes. - -2008-04-19 Nick Roberts - - * building.texi (GDB-UI Layout, Breakpoints Buffer) - (Other GDB-UI Buffers): Update for recent thread related changes. - -2008-04-11 Mirko Vukovic (tiny change) - - * maintaining.texi (Maintaining): - * emacs.texi (Top): Typo. - -2008-04-08 Stefan Monnier - - * display.texi (Font Lock): Prefer add-hook to using a non-nil `mode' - arg in `font-lock-add-keywords'. - -2008-04-08 Glenn Morris - - * cal-xtra.texi, calendar.texi: Update for calendar name changes. - Also add Baha'i calendar references where appropriate. - -2008-04-05 Glenn Morris - - * custom.texi (Init File): Byte-compiling .emacs is bad. - -2008-04-04 Stefan Monnier - - * mini.texi (Minibuffer Edit) : Adjust default. - -2008-03-29 Glenn Morris - - * calendar.texi: Update for `calendar-date-style' replacing - `european-calendar'. - -2008-03-28 Jason Rumney - - * display.texi (Display Custom): Mention overlay-margin in text. - -2008-03-12 Reiner Steib - - * custom.texi, dired.texi, mini.texi, mule.texi: Add `referenced in the - tutorial' comments. - -2008-03-28 Chong Yidong - - * mark.texi (Mark): Rearrange nodes. - (Persistent Mark): Rename from Transient Mark. - (Mark, Setting Mark, Marking Objects, Persistent Mark, Mark Ring): - Describe Transient Mark mode as the default. - - * basic.texi (Basic Undo): Don't mention setting the mark, which isn't - the default behavior with Transient Mark mode off. - (Position Info): Fix typo. - - * display.texi (Standard Faces): Reference the Mark node. - Remove discussion of the region face, which is discussed there. - - * emacs.texi (Top): Update node listings. - - * files.texi (Diff Mode, Misc File Ops): Describe Transient Mark mode - as the default. - - * fixit.texi (Undo): Standardize choice of undo key sequence. - (Undo, Spelling): Describe Transient Mark mode as the default. - - * frames.texi (Mouse Commands): Treat Transient Mark mode as the - default. - - * glossary.texi (Glossary): Treat Transient Mark mode as the default. - - * killing.texi (Kill Ring, Accumulating Text): Assume Transient Mark - mode is the default, and note that the mark is not activated when set. - - * programs.texi (Moving by Defuns, Expressions, Comment Commands): - Describe Transient Mark mode as the default. - - * search.texi (Basic Isearch): Reference the Mark Ring node. - (Replace, Unconditional Replace, Other Repeating Search): - Describe Transient Mark mode as the default. - - * text.texi (Words, Pages, Fill Commands, HTML Mode): Describe - Transient Mark mode as the default. - (Paragraphs): Describe how M-h behaves when region is active. - - * trouble.texi (Quitting): Clarify effects of C-g. - -2008-03-13 Glenn Morris - - * emacs.texi (EMACSVER): Set to 23.0.60. - -2008-03-05 Glenn Morris - - * dired.texi (Hiding Subdirectories): Fix previous change. - -2008-03-05 Drew Adams - - * dired.texi (Hiding Subdirectories): Document `dired-hide-subdir'. - -2008-02-28 Kim F. Storm - - * help.texi (Help Files): Move describe-gnu-project to C-h g. - Move describe-distribution to C-h C-o. - Move view-emacs-problems to C-h C-p. - Add view-emacs-debugging on C-h C-d. - Add view-external-packages on C-h C-e. - Add view-order-manuals on C-h C-m. - -2008-02-17 Ulrich Mueller - - * msdog-xtra.texi (MS-DOS): Docstring fix. - -2008-02-09 Eli Zaretskii - - * msdog.texi (Windows Fonts): Use a @table for describing font - properties. - -2008-02-07 Jason Rumney - - * msdog.texi (Windows Files): w32-get-true-file-attributes default - value has changed. - (Windows HOME): Clarify what is meant by "if that fails as well". - (Windows Fonts): New section. - -2008-02-07 D. E. Evans (tiny change) - - * basic.texi (Basic Undo): Remove duplicate "you can". - -2008-02-02 Eli Zaretskii - - * maintaining.texi (Tags): Fix last change. - -2008-02-02 Michael Albinus - - * tramp.texi: Use new FSF's Back-Cover Text. - -2008-01-31 Nick Roberts - - * trouble.texi (Checklist): Direct users to emacs-devel@gnu.org. - -2008-01-26 Richard Stallman - - * maintaining.texi (Tags): Delete redundant index entry. - -2008-01-26 Eli Zaretskii - - * programs.texi (Imenu): Move "@cindex tags" from here... - * maintaining.texi (Tags): ...to here. - -2008-01-23 Kevin Ryde - - * custom.texi (Mouse Buttons): Update elisp xref to "Click Events" on - click count. - -2008-01-21 Juanma Barranquero - - * entering.texi (Exiting): Fix typo. - Reported by D. E. Evans . - -2007-12-31 Martin Rudalics - - * glossary.texi (Glossary): Fix typo. - -2007-12-27 Richard Stallman - - * text.texi (Formatted Text): Improve menu tag. - (Editing Format Info): In Info, add duplicate menu of nodes - about the submenus. - (Format Faces): Say where Faces menu is found. Mention Other. - (Format Colors): Say where these submenus are found. - (Format Indentation, Format Justification): Likewise. - (Format Properties): Likewise. - -2007-12-22 Richard Stallman - - * search.texi (Query Replace): Make exp of query-replace more - self-contained, and clarify. - - * cc-mode.texi (Getting Started): Change @ref to @pxref. - -2007-12-15 Richard Stallman - - * files.texi (Auto Save): Clarify definition of auto-saving. - -2007-11-26 Richard Stallman - - * help.texi (Help Echo): Cleanups. - -2007-11-23 Thien-Thi Nguyen - - * files.texi (Why Version Control?): Fix typo. - (VCS Concepts): Fix typos; small tense fix. - (Selecting a Fileset): Fix typos; small rewording. - (Log Buffer): Likewise. - (Old Revisions): Likewise. - -2007-11-17 Eli Zaretskii - - * mule.texi (Communication Coding): Fix wording of last change. - -2007-11-16 Werner Lemberg - - * custom.texi (Specifying File Variables): - * major.texi (Choosing Modes): Mention '\" in man pages. - -2007-11-16 Kenichi Handa - - * mule.texi (Communication Coding): Document x-select-request-type. - - * frames.texi (Cut/Paste Other App): Mention x-select-request-type. - -2007-11-15 Francesco Potortì - - * maintaining.texi (TEXTAGS): Note that you can use "-" for stdout with - --output=file. - -2007-11-13 Martin Rudalics - - * help.texi (Help Summary, Apropos, Misc Help): Fix typos. - (Help Echo): Avoid mentioning the term "region" here and - consistently use the term "active text". - -2007-11-11 Glenn Morris - - * calendar.texi (Special Diary Entries): Fix Thanksgiving example. - -2007-11-10 Paul Pogonyshev - - * search.texi (Query Replace): Mention - `query-replace-show-replacement'. - -2007-11-09 Nick Roberts - - * building.texi (Watch Expressions): Remove obscure sentence. - -2007-11-06 Kenichi Handa - - * mule.texi (Select Input Method): Describe how to activate an input - method in the text mode. - -2007-11-01 Dan Nicolaescu - - * cmdargs.texi (Misc Variables): Remove Sun windows info. - -2007-10-30 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-delete-out-of-scope. - -2007-10-30 Glenn Morris - - * misc.texi (Directory Tracking): Explain a bit more about - dirtrack-mode. - -2007-10-25 Glenn Morris - - * fortran-xtra.texi (Fortran): F90 mode handles F2003. - -2007-10-24 Richard Stallman - - * misc.texi (Interactive Shell): Cleanup last change. - -2007-10-22 Juri Linkov - - * mini.texi (Minibuffer History): Add text about a list of minibuffer - default values. - -2007-10-20 Eric S. Raymond - - * files.texi: Disambiguate two slightly different uses of the term - 'filesets'. - -2007-10-18 Martin Rudalics - - * trouble.texi (Quitting): Fix typo. - -2007-10-18 Glenn Morris - - * frames.texi (Mode Line Mouse): Mention minor mode names. - -2007-10-17 Juri Linkov - - * text.texi (Fill Commands): Undocument fill-paragraph-or-region. - fill-paragraph operates on the active region in Transient Mark mode. - (Fill Prefix, Format Indentation): Replace fill-paragraph-or-region - with fill-paragraph. - - * basic.texi (Arguments): Replace fill-paragraph-or-region with - fill-paragraph. - - * fixit.texi (Spelling): ispell-word operates on the active region - in Transient Mark mode. - -2007-10-17 Aaron S. Hawley - - * building.texi (Source Buffers): - * custom.texi (Init Non-ASCII): - * glossary.texi (Glossary): Use "key binding" consistently. - -2007-10-17 Juanma Barranquero - - * calendar.texi (Diary): Fix directive. - -2007-10-16 Richard Stallman - - * calendar.texi (Diary): Clarify text about diary file example. - -2007-10-13 Eric S. Raymond - - * files.texi: Capitalize node names according to convention. - -2007-10-13 Glenn Morris - - * misc.texi (Interactive Shell): Correct INSIDE_EMACS reference. - -2007-10-11 Eric S. Raymond - - * emacs.texi: - * files.texi (Version Systems): Minor fixes to version-control material - suggested by RMS and Robert J. Chassell. - -2007-10-10 Eric S. Raymond - - * files.texi (Version Systems): - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: Merge in changes for new VC with fileset-oriented - operations. Change of terminology from `version' to `revision'. - Revise text for adequate description of VCSes with monotonic IDs. - * emacs.texi: Change of terminology from `version' to `revision'. - -2007-10-09 Eric S. Raymond - - * files.texi (Version Systems): Describe newer VCses. - Reorder the descriptions to be chronological. - -2007-10-09 Richard Stallman - - * display.texi (Cursor Display): Correct how cursor appears - in nonselected windows. - -2007-10-04 Nick Roberts - - * building.texi (GDB Graphical Interface): Remove references to gdba - and mention gud-gdb. - -2007-08-31 Eli Zaretskii - - * rmail.texi (Rmail Sorting): Improve indexing. - -2007-10-06 Juri Linkov - - * text.texi (Fill Commands): Document fill-paragraph-or-region. - (Fill Prefix, Format Indentation): Replace fill-paragraph with - fill-paragraph-or-region. - - * basic.texi (Arguments): Replace fill-paragraph with - fill-paragraph-or-region. - -2007-10-06 Eric S. Raymond - - * files.texi: Update the section on version control for 2007 - conditions. None of these changes are new-VC-specific; that - will come later. - -2007-09-15 Glenn Morris - - * calendar.texi (Holidays): Change all instances of `holiday-list' back - to `list-holidays'. - -2007-09-14 Glenn Morris - - * calendar.texi: Update all instances of mark-calendar-holidays, - list-calendar-holidays, list-holidays with the new names. - -2007-09-06 Glenn Morris - - Move manual sources from man/ to subdirectories of doc/. - Split into the Emacs manual in emacs/, and other manuals in misc/. - * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (infodir): New variable. - (info): Use $infodir. - (emacsman): Delete target, not needed any more. - Move all targets that are not the Emacs manual to misc/Makefile.in. - (mostlyclean): Remove `gnustmp'. - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs - manual. - (MULTI_INSTALL_INFO, ENVADD, infodir): Go up one more level. - (emacsman): Delete target, not needed any more. - (clean): Remove all info files but Emacs manual. - Move all targets that are not the Emacs manual to misc/Makefile.in. - * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. - - * Makefile.in (INFOSOURCES): Delete. - (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. - (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs - *.vrs *.toc here... - (maintainer-clean): ...from here. - -2007-09-05 Glenn Morris - - * custom.texi (Safe File Variables): Clarify `!' and risky variables. - -2007-08-29 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 23.0.50. - -2007-08-27 Richard Stallman - - * emacs.texi (Top): Clarify menu item for Glossary. - - * display.texi (Faces): Change secn title. - Clarify not all fonts come from Font Lock. - -2007-08-17 Eli Zaretskii - - * basic.texi (Position Info): Add index entry for face at point. - Mention that character faces are also displayed by "C-u C-x =". - -2007-08-08 Glenn Morris - - * glossary.texi (Glossary): Deprecate `iff'. - -2007-08-07 Chong Yidong - - * files.texi (File Conveniences): Document point motion keys in Image - mode. - -2007-07-27 Glenn Morris - - * emacs.texi (Copying): Include license text from gpl.texi, rather than - in-line. - - * gpl.texi: New file with text of GPL. - * Makefile.in (EMACSSOURCES): Add gpl.texi. - -2007-07-26 Dan Nicolaescu - - * vc2-xtra.texi (Customizing VC): Add GIT and HG. - - * dired.texi (Wdired): Mention C-x C-q key binding. - -2007-07-28 Nick Roberts - - * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". - -2007-07-25 Glenn Morris - - * emacs.texi (Copying): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Glenn Morris - - * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work - for some calendars. - -2007-07-23 Nick Roberts - - * screen.texi (Mode Line): Describe new mode-line flag that shows if - default-directory for the current buffer is on a remote machine. - -2007-07-21 Eli Zaretskii - - * vc2-xtra.texi (Customizing VC) : Update the - default value. - -2007-07-21 Richard Stallman - - * files.texi (Why Version Control?): Improve previous change. - -2007-07-18 Eric S. Raymond - - * files.texi (Why Version Control?): New node. - -2007-07-12 Nick Roberts - - * building.texi (Starting GUD): Add xref to this anchor. - -2007-06-24 Karl Berry - - * emacs.texi: New Back-Cover Text. - -2007-06-07 Alan Mackenzie - - * display.texi (Optional Mode Line): Document the new form of - line+column numbers, "(561,2)". - -2007-06-06 Juanma Barranquero - - * maintaining.texi (Create Tags Table): Fix typos. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-05-07 Karl Berry - - * emacs.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * maintaining.texi (Create Tags Table): Clean up previous change. - -2007-05-05 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add text about the dangers of - making symbolic links to tags files. - -2007-05-04 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. - -2007-05-03 Karl Berry - - * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. - - * .cvsignore (*.pdf): New entry. - - * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black - for printing. - -2007-05-01 Richard Stallman - - * cmdargs.texi (Initial Options): Under --batch, mention --eval. - -2007-04-28 Glenn Morris - - * ack.texi (Acknowledgments): - * anti.texi (Antinews): - * programs.texi (Program Modes): Restore mention of python.el pending - consideration of legal status. - -2007-04-28 Richard Stallman - - * files.texi (File Names): Fixes to ~ description on MS systems. - -2007-04-26 Glenn Morris - - * emacs.texi (EMACSVER): Increase to 22.1.50. - -2007-04-25 Karl Berry - - * emacs.texi: Improve line breaks on copyright page, - similar layout to lispref, 8.5x11 by default. - - * dired.texi (Image-Dired): Improve line break, fix typo. - -2007-04-24 Chong Yidong - - * programs.texi (Program Modes): - * anti.texi (Antinews): - * ack.texi (Acknowledgments): python.el removed. - -2007-04-23 Chong Yidong - - * display.texi (Highlight Interactively): Correct description of - hi-lock-file-patterns-policy. - - * files.texi (File Archives): Mention self-extracting executables. - -2007-04-23 Eli Zaretskii - - * search.texi (Unconditional Replace, Query Replace): Add xref to - "Replacement and Case". - -2007-04-22 Chong Yidong - - * dired.texi (Image-Dired): Move from Thumbnails node. - * misc.texi (Thumbnails): Node deleted. - * emacs.texi (Top): Update node listing. - - * files.texi (File Conveniences): - * ack.texi (Acknowledgments): Rename "tumme" to "image-dired". - -2007-04-21 Richard Stallman - - * display.texi (Highlight Interactively): Correct previous change. - Clarify doc of hi-lock-find-patterns, and move new features into it. - -2007-04-20 David Koppelman - - * display.texi (Highlight Interactively): Document - hi-lock-file-patterns-policy. - -2007-04-20 Martin Rudalics - - * display.texi (Scrolling): Fix typo. - -2007-04-15 Chong Yidong - - * doclicense.texi: Remove node heading, so that it can be included by - other files. - - * emacs.texi: Insert node heading for GFDL. - -2007-04-14 Eli Zaretskii - - * cmdargs.texi (Colors): Qualify "color of window" index entry by - "command line". - - * display.texi (Faces): Refer to "Creating Frames" for face - and other frame customizations in .emacs. - - * frames.texi (Creating Frames): Mention that face customizations can - be put in .emacs. Add index entries. - -2007-04-12 Richard Stallman - - * glossary.texi (Glossary): Explain `iff'. - -2007-04-11 Karl Berry - - * gnu.texi (Top), - * macos.texi (Mac Font Specs), - * anti.texi (Antinews), - * xresources.texi (Resources), - * misc.texi (Emulation), - * calendar.texi (Daylight Saving), - * dired.texi (Dired and Find), - * rmail.texi (Remote Mailboxes), - * sending.texi (Mail Headers), - * programs.texi (Which Function), - * files.texi (Recover), - * buffers.texi (Uniquify), - * frames.texi (Wheeled Mice), - * killing.texi (Rectangles): Wording to improve breaks in - 8.5x11 format. - * mule.texi (Language Environments): \hbadness=10000 since there's - no way to reword. - * emacs.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * files.texi (File Conveniences): Add xref to Tumme. - Delete text about Thumbnail mode. - -2007-04-09 Alan Mackenzie - - * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its - new name. Insert concept index entries. - -2007-04-08 Chong Yidong - - * display.texi (Standard Faces): Document prefix arg for - list-faces-display. - - * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. - -2007-04-07 Chong Yidong - - * killing.texi (Deletion): Rewrite description of M-\ prefix argument. - - * files.texi (Misc File Ops): Rewrite description of - insert-file-literally. - -2007-03-31 Eli Zaretskii - - * misc.texi (Printing): Postscript -> PostScript. - - * ack.texi (Acknowledgments): Postscript -> PostScript. - - * custom.texi (Init File, Init Non-ASCII): Fix last change. - - * emacs.texi (Top): Fix the menu due to the change in custom.texi - below. - -2007-03-30 Chong Yidong - - * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to - Init Non-ASCII. - (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. - (Init Non-ASCII): New node. - -2007-03-28 YAMAMOTO Mitsuharu - - * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. - -2007-03-12 Glenn Morris - - * calendar.texi, emacs.texi (Daylight Saving): Rename node from - "Daylight Savings". - - * calendar.texi: Replace "daylight savings" with "daylight - saving" in text throughout. - -2007-03-04 Richard Stallman - - * custom.texi (Safe File Variables): Minor correction. - -2007-02-28 Thien-Thi Nguyen - - * rmail.texi (Movemail): Add internal ref. - Don't indent the intro for the PROTO table. - Format PROTO table items with @code. - -2007-02-26 Nick Roberts - - * building.texi: Remove references to bashdb. - -2007-02-19 Juanma Barranquero - - * mule.texi (Language Environments): Update list of supported language - environments. - -2007-02-14 Kim F. Storm - - * building.texi (Grep Searching): Fix lgrep doc. - -2007-02-12 Chong Yidong - - * back.texi: Remove unused file. - -2007-02-05 Francesco Potortì - - * maintaining.texi (Tag Syntax): Now --members is the default for - etags, not for ctags yet. - -2007-02-03 Eli Zaretskii - - * emacs.texi (Top): Update the top-level menus. Make the detailed menu - headers compliant with Texinfo guidelines and with what texnfo-upd.el - expects. Add comments to prevent people from inadvertently modifying - the key parts needed by `texinfo-multiple-files-update'. - -2007-01-29 Chong Yidong - - * frames.texi (Secondary Selection): Window clicked does not matter - when mouse-yank-at-point is non-nil. - -2007-01-16 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Describe how to disable a - system abbrev. - -2007-01-11 Richard Stallman - - * msdog.texi (Windows Keyboard): Another small cleanup. - -2007-01-10 Richard Stallman - - * msdog.texi (Windows Keyboard): Yet another try to make - everyone happy with that passage. - -2007-01-05 Richard Stallman - - * anti.texi (Antinews): Mention M-x shell scrolling. - -2007-01-05 Nick Roberts - - * building.texi (Watch Expressions): Describe gdb-max-children. - -2007-01-04 Richard Stallman - - * msdog.texi (Windows Keyboard): Clarify previous change. - -2007-01-02 Richard Stallman - - * custom.texi (Changing a Variable): Minor clarification. - (Specific Customization): customize-customized => customize-unsaved. - - * entering.texi (Entering Emacs): Clean up text about restarting - Emacs for each file. - - * misc.texi (Shell Options): Minor cleanup. - - * msdog.texi (Windows Keyboard): Explain that Windows was incompatible - with Emacs, not vice versa. - - * programs.texi (Symbol Completion): Recommend customizing - window manager. - - * xresources.texi (Resources): Minor fix. - -2007-01-01 Jan Djärv - - * xresources.texi (Table of Resources): Add scrollBarWidth resource. - -2007-01-01 Richard Stallman - - * commands.texi (User Input): Document keys stolen by window mangers. - -2006-12-31 Richard Stallman - - * custom.texi (Specific Customization): Document customize-option - instead of customize-variable. - -2006-12-31 Kim F. Storm - - * major.texi (Choosing Modes): Document auto-mode-case-fold. - -2006-12-30 Kim F. Storm - - * killing.texi (CUA Bindings): Fix typo. - - * xresources.texi (Table of Resources): Mention grow-only value for - auto-resize-tool-bars. - -2006-12-27 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, - and how to get them back. - -2006-12-26 Richard Stallman - - * calendar.texi (Holidays): Holiday listing is based on current - practice, but DST is not. - -2006-12-25 Richard Stallman - - * emacs.texi (Top): Update subnode menus. - - * mark.texi (Transient Mark): Fix xref. - - * killing.texi (Graphical Kill): Node deleted. - (Killing): Add xref to Cut and Paste. - (CUA Bindings): Update xref. - - * frames.texi (Cut and Paste): New section to hold other nodes. - (Mouse Commands): Node demoted. - (Cut/Paste Other App): Split out from Mouse Commands. - (Word and Line Mouse): Likewise. - (Secondary Selection, Clipboard): Nodes demoted. - -2006-12-24 Kevin Ryde - - * calendar.texi (Holidays): US daylight saving begins second Sunday - in March for 2007 onwards. - (Daylight Savings): Show new US default daylight saving rules, 2nd - Sun in Mar to 1st Sun in Nov, now in cal-dst.el. - -2006-12-23 Chong Yidong - - * calendar.texi (Scroll Calendar): < and > are switched. - -2006-12-23 Kevin Rodgers - - * killing.texi (Deletion): Describe M-\ prefix argument. - -2006-12-23 Richard Stallman - - * search.texi (Regexp Search): Explain why forward and reverse regexp - search are not mirror images. - -2006-12-19 Kim F. Storm - - * major.texi (Choosing Modes): Describe match-function elements for - magic-mode-alist. - -2006-12-18 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys - peculiarities. - -2006-12-18 Richard Stallman - - * abbrevs.texi (Editing Abbrevs): Fix previous change. - -2006-12-17 Alan Mackenzie - - * programs.texi (Left Margin Paren): Remove the bit which says - that CC Mode sets open-paren-in-column-0-is-defun-start to nil. - Discuss some of the issues of setting this option to nil. - -2006-12-17 Glenn Morris - - * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. - -2006-12-16 Eli Zaretskii - - * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. - (Windows Files): `w32-get-true-file-attributes' is only relevant for - NTFS volumes. - (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS - volumes. - -2006-12-15 Eli Zaretskii - - * text.texi (HTML Mode): Fix "C-c TAB". - -2006-12-09 Richard Stallman - - * misc.texi (Invoking emacsclient): Simplify TCP file text. - -2006-12-08 Kevin Rodgers - - * files.texi (Misc File Ops): Document insert-file-literally. - -2006-12-08 Eli Zaretskii - - * cmdargs.texi (Colors): Note that --color is intended for overriding - the terminal defaults, not for normal invocation. - - * misc.texi (Emacs Server): Improve wording. Don't mention the - ``server program''. Add a cross-reference to "Init File" node. - (Invoking emacsclient): Add index entries. Document both short and - long versions of command-line options. Document the -f option. - -2006-12-06 Richard Stallman - - * text.texi (Outline Format): Say to set outline-regexp - and outline-level with major modes and file local variables. - -2006-12-05 Michaël Cadilhac - - * anti.texi (Antinews): Mention the alternative to - `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. - - * misc.texi (Interactive Shell): Ditto. - -2006-12-04 Eli Zaretskii - - * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - - * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. - -2006-12-01 Eli Zaretskii - - * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a - colon in the mode line. - - * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. - -2006-11-26 Nick Roberts - - * building.texi (Watch Expressions): Mention SPC for expanding/ - contracting watch expressions. - -2006-11-26 Kim F. Storm - - * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. - -2006-11-26 Nick Roberts - - * building.texi (Debugger Operation): Define text command mode. - Clarify how tooltips work. - (GDB Graphical Interface): Explain how to run in text command mode - more clearly. - -2006-11-25 Juanma Barranquero - - * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. - -2006-11-22 Juanma Barranquero - - * anti.texi (Antinews): Mention --server-file and TCP sockets. - -2006-11-18 Chong Yidong - - * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, - and EMACS is deprecated. - -2006-11-18 Juanma Barranquero - - * makefile.w32-in (emacs.dvi): Remove xresmini.texi. - -2006-11-18 Jan Djärv - - * Makefile.in (emacs.dvi): Remove xresmini.texi. - - * emacs.texi: Include xresources.texi both for info and dvi. - - * xresources.texi: Merge text from xresmini.texi. - -2006-11-12 Roberto Rodríguez (tiny change) - - * glossary.texi: Fix typos. - -2006-11-06 Richard Stallman - - * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. - - * ack.texi (Acknowledgments): Fix name spelling. - -2006-11-01 Juri Linkov - - * search.texi (Word Search): Document incremental word search. - -2006-10-28 Glenn Morris - - * ack.texi (Acknowledgments): Add cal-html author. - - * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX - Calendar"). Describe new package cal-html. - * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing - Calendar Files." - -2006-10-23 Richard Stallman - - * abbrevs.texi (Expanding Abbrevs): Expansion happens only when - Abbrev mode is enabled. - -2006-10-16 Richard Stallman - - * emacs.texi: Update ISBN. - -2006-10-11 Kim F. Storm - - * emacs.texi (Acknowledgments): Use @dotless{i}. - -2006-10-08 Nick Roberts - - * building.texi (Breakpoints Buffer): Mention catchpoints. - -2006-10-08 Kim F. Storm - - * ack.texi (Acknowledgments): Update. - - * emacs.texi (Acknowledgments): Fix bad @/ form. - -2006-10-05 Kim F. Storm - - * emacs.texi (Acknowledgments): Add more contributors. - -2006-10-03 Richard Stallman - - * emacs.texi (Acknowledgments): Update version and edition. - -2006-10-01 Karl Berry - - * custom.texi (Customization Groups): Page break to keep example buffer - on one page. - -2006-09-30 Karl Berry - - * programs.texi (Basic Indent): @need to improve page break. - * text.texi: Rewording to improve page breaks, and use @LaTeX{}. - -2006-09-29 Glenn Morris - - * calendar.texi (Date Formats): Doc fix for european-calendar-style. - -2006-09-29 Karl Berry - - * windows.texi (Basic Window): Remove forced @break, no longer - desirable. - * frames.texi (Frame Commands), - * mark.texi (Marking Objects): Reword to avoid bad page break. - * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. - -2006-09-19 Richard Stallman - - * frames.texi (Dialog Boxes): Clean up wording: avoid passive, - stick to present tense. - -2006-09-18 Jan Djärv - - * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog - to x-gtk-use-old-file-dialog. - (Dialog Boxes): Document x-gtk-file-dialog-help-text. - -2006-09-15 Jay Belanger - - * emacs.texi (GNU GENERAL PUBLIC LICENSE): - Change "Library Public License" to "Lesser Public License" - throughout. Use "yyyy" to represent year. - -2006-09-12 Reiner Steib - - * files.texi (Visiting): Add index entry "open file". - -2006-09-11 Richard Stallman - - * building.texi (Compilation Mode): Clarification. - (Grep Searching): Add xref to Compilation Mode. - -2006-09-08 Richard Stallman - - * search.texi (Search): Ref multi-file search commands here. - (Other Repeating Search): Not here. - -2006-08-28 Richard Stallman - - * windows.texi (Split Window): Update xref. - - * basic.texi (Continuation Lines): Update xref. - - * indent.texi (Tab Stops): Update xref. - - * emacs.texi (Top): Update subnode menu. - - * display.texi (Line Truncation, Displaying Boundaries): New nodes, - split out of Display Custom. - -2006-08-25 Kim F. Storm - - * display.texi (Display Custom): Add variables overline-margin - and x-underline-at-descent-line. - -2006-08-25 Richard Stallman - - * entering.texi (Exiting): Rewrite to give graphical displays - priority over text terminals. - - * search.texi (Incremental Search): Move index entries. - -2006-08-23 Chong Yidong - - * custom.texi (Init File): Reference Find Init to avoid "home - directory" confusion. - -2006-08-22 Nick Roberts - - * building.texi (Other GDB-UI Buffers): Describe how to edit - a value in the locals buffer. - -2006-08-21 Richard Stallman - - * search.texi (Basic Isearch): Add `isearch' index entry. - -2006-08-16 Richard Stallman - - * misc.texi (Saving Emacs Sessions): Clean up wording. - - * mark.texi (Marking Objects): Mention term "select all". - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Move node up in file. - -2006-08-15 Nick Roberts - - * building.texi (Stack Buffer): Explain fringe arrow. - -2006-08-12 Eli Zaretskii - - * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored - on startup. - -2006-08-11 Romain Francoise - - * ack.texi (Acknowledgments): Delete mention to zone-mode.el. - -2006-08-10 Sven Joachim (tiny change) - - * mule.texi (Recognize Coding, Text Coding): Fix typos. - -2006-08-10 Richard Stallman - - * text.texi (Format Faces): Substantial rewrites to deal - with face merging. Empty regions don't count. Clarify - face property inheritance. - -2006-08-08 Romain Francoise - - * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen - . - -2006-08-04 Eli Zaretskii - - * cmdargs.texi (Window Size X) <--geometry>: Only width and height - apply to all frames. - -2006-08-01 Richard Stallman - - * help.texi (Name Help): Add index entries for describe-variable. - -2006-08-01 Nick Roberts - - * building.texi (GDB Graphical Interface): Shorten node names. - (GDB-UI Layout): Use GDB-related. - (Other GDB-UI Buffers): Simplify English. - -2006-07-31 Richard Stallman - - * search.texi (Query Replace): Add xref for Dired's Q command. - -2006-07-31 Nick Roberts - - * building.texi (GDB commands in Fringe): Rename to... - (Source Buffers): ..this and move forward. Describe hollow arrow and - new option gdb-find-source-frame. - -2006-07-29 Richard Stallman - - * dired.texi (Operating on Files): Simplify previous change - and fix Texinfo usage. - -2006-07-29 Eli Zaretskii - - * dired.texi (Operating on Files): Add cross-references. State the - Unix commands that do similar things. - -2006-07-28 Richard Stallman - - * mark.texi (Transient Mark): Clarify that region never disappears - when Transient Mark mode is off, and not when it is on. - -2006-07-27 Richard Stallman - - * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. - -2006-07-24 Richard Stallman - - * xresources.texi (GTK styles): Fix texinfo usage. - - * commands.texi (User Input): Explain why we teach keyboard cmds. - - * xresources.texi, xresmini.texi, search.texi, programs.texi: - * misc.texi, kmacro.texi, killing.texi, glossary.texi: - * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: - * doclicense.texi, display.texi, dired.texi, basic.texi: - * anti.texi, ack.texi: Move periods and commas inside quotes. - -2006-07-22 Eli Zaretskii - - * cmdargs.texi (General Variables): Document EMAIL. - -2006-07-21 Eli Zaretskii - - * frames.texi (Frame Commands): Mention that focus-follows-mouse - doesn't have effect on MS-Windows. - -2006-07-17 Richard Stallman - - * building.texi (Grep Searching): Explain about chaining grep commands. - -2006-07-10 Nick Roberts - - * killing.texi, mini.texi: Fix typos. - -2006-07-09 Chong Yidong - - * misc.texi (Invoking emacsclient): Document behavior when emacsclient - is invoked for multiple files. - -2006-07-08 Eli Zaretskii - - * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the - on-line manual for the rest of this node. - (Windows Mouse) : Include - unconditionally. - (Windows Processes) : Include unconditionally. - Improve wording. - (Windows Printing): Improve wording. - (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the - rest of this node. - -2006-07-05 Thien-Thi Nguyen - - * building.texi (Lisp Eval): Throughout, replace eval-current-buffer - with eval-buffer. - -2006-07-05 Nick Roberts - - * mule.texi (Coding Systems, Specify Coding): Link descriptions - of character translation. - -2006-07-04 Nick Roberts - - * rmail.texi (Remote Mailboxes): Add missing @code keyword. - -2006-07-03 Karl Berry - - * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by - not-too-underfull hboxes in the TeX output. - * abbrevs.texi, buffers.texi, building.texi, calendar.texi, - * cmdargs.texi, custom.texi, dired.texi, macos.texi, - * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, - * sending.texi, text.texi: Fix overfull/underfull boxes. - -2006-07-03 Romain Francoise - - * m-x.texi (M-x): Fix. - -2006-07-03 Richard Stallman - - * search.texi (Other Repeating Search): filename -> file name. - - * misc.texi (Narrowing): Minor cleanups. - - * files.texi (Visiting): filename -> file name. - - * emacs.texi (Top): Update subnode menus. - - * mule.texi (Coding Systems): Move char translation stuff here. - (Specify Coding, Output Coding): New nodes, out of Recognize Coding. - (Recognize Coding): Substantial local rewrites. - (International): Update menu. - - * display.texi (Auto Scrolling): New node, broken out of Scrolling. - (Scrolling): Substantial local rewrites. - (Display): Update menu and intro. - - * dired.texi: filename -> file name. - - * custom.texi (Safe File Variables): Texinfo usage fix. - -2006-07-03 Teodor Zlatanov - - * help.texi, m-x.texi: Lots of cleanups. - -2006-06-30 Eli Zaretskii - - * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) - (Windows Processes, Windows Misc): Shorten the printed version by - selectively conditioning less important portions by @ifnottex. - -2006-06-27 Richard Stallman - - * mini.texi (Minibuffer File): Minor cleanup. - -2006-06-25 Nick Roberts - - * frames.texi (XTerm Mouse): Rename to... - (Text-Only Mouse): ...this. Mention t-mouse-mode. - - * emacs.texi (Top): Use new node name. - -2006-06-24 Eli Zaretskii - - * emacs.texi (Top): Update the detailed menu according to changes in - msdog.texi. - - * msdog.texi (Windows Keyboard): New section. - (Windows Mouse): New section. - (Windows System Menu): Remove section (text merged with "Windows - Keyboard"). - (Windows Misc): New section. - - * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. - - * msdog.texi (ls in Lisp): New section. - - * files.texi (Visiting): Document case-insensitive wildcard matching - under find-file-wildcards. - -2006-06-16 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Add description of mac-function-modifier. - Now Unicode keyboard layouts work. - -2006-06-10 Richard Stallman - - * mule.texi (Recognize Coding): Clarify previous change. - -2006-06-09 Kenichi Handa - - * mule.texi (Recognize Coding): Describe the convention of "CODING!" - notation. - -2006-06-07 Kevin Ryde - - * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main - manual for @ifnottex, but in emacs-extra for @iftex. - - * cmdargs.texi (General Variables): Fix smtpmail xref. - -2006-05-29 Stefan Monnier - - * programs.texi (Comment Commands): - * custom.texi (Specifying File Variables): - Use ;; instead of ;;; to better follow coding conventions. - -2006-06-07 Nick Roberts - - * building.texi (Watch Expressions): Move node to end. - (GDB Graphical Interface): Move description of clicks in fringe... - (GDB commands in the Fringe): ...to here. New node. - -2006-06-05 Romain Francoise - - * xresmini.texi (GTK resources): Fix various typos. - -2006-06-05 Nick Roberts - - * building.texi (GDB Graphical Interface): Update bindings. - (Commands of GUD): Add gud-print. Remove gud-run. - Restate availability more generally. - -2006-06-03 Teodor Zlatanov - - * mini.texi: Lots of cleanups. - -2006-06-01 Luc Teirlinck - - * misc.texi (Shell History Copying): Update descriptions of `C-c RET' - and Mouse-2. - -2006-06-01 Jan Djärv - - * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. - -2006-05-31 Richard Stallman - - * basic.texi (Moving Point): Fix previous change. - -2006-05-29 Jan Djärv - - * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. - -2006-05-28 Teodor Zlatanov - - * basic.texi: Many simplifications and improvements in wording. - -2006-05-26 Nick Roberts - - * anti.texi (Antinews): Create a node for gdb-ui. - -2006-05-22 Reiner Steib - - * frames.texi (Menu Bars, Tool Bars): Add index entries. - -2006-05-20 Richard Stallman - - * dired.texi (Dired Navigation): dired-goto-file is now j. - -2006-05-20 Eli Zaretskii - - * mule.texi (Coding Systems): Mention the undecided-* coding systems - and their aliases. - - * msdog.texi (Windows Printing): Mention non-support of plain text - printing with some el-cheapo printers, and suggest a workaround. - -2006-05-20 Kevin Ryde - - * text.texi (TeX Print): tex-dvi-view-command has a default value, - remove the bit saying you must set it. - -2006-05-19 Luc Teirlinck - - * trouble.texi (Checklist): - * text.texi (Text, Auto Fill, Text Mode): - * search.texi (Nonincremental Search): - * rmail.texi (Rmail Labels): - * mule.texi (Input Methods, Multibyte Conversion): - * misc.texi (Gnus, Where to Look, PostScript): - * maintaining.texi (Create Tags Table): - * indent.texi (Indentation Commands): - * fixit.texi (Spelling): - * emacs.texi (Copying): - * custom.texi (Init File): ifinfo -> ifnottex. - -2006-05-17 Richard Stallman - - * files.texi (Diff Mode): Mention C-x `. - -2006-05-08 Richard Stallman - - * custom.texi (Disabling): Textual cleanups. - -2006-05-12 Glenn Morris - - * calendar.texi (Displaying the Diary, Format of Diary File): - Refer to diary-view-entries, diary-list-entries, - diary-show-all-entries rather than obsolete aliases. - -2006-05-12 Eli Zaretskii - - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * building.texi (Compilation Shell): - * buffers.texi (Several Buffers) [iftex]: Replace @xref's to - emacs-xtra with @inforef's. - - * files.texi (Visiting): Fix wording. - - * mule.texi (Coding Systems, Text Coding): More indexing. - Mention that C-x RET f can set eol conversion. - -2006-05-07 Jan Djärv - - * xresmini.texi (GTK resources): Insert GTK description. - - * xresources.texi (GTK resources): metafont should be menufont. - -2006-05-06 Michael Albinus - - * mini.texi (Completion Options): Completion of remote files' - method, user name and host name is active only in partial - completion mode. - -2006-05-06 Eli Zaretskii - - * makefile.w32-in (emacs.dvi): - * Makefile.in (emacs.dvi): Add xresmini.texi. - - * xresmini.texi (Table of Resources): Remove xref to non-existent - node "LessTif Resources". - - * msdog.texi (Microsoft Windows): - * calendar.texi (Calendar/Diary, Displaying the Diary) - (Special Diary Entries, Importing Diary, Holidays): - * programs.texi (Program Modes): - * text.texi (Text): - * buffers.texi (Several Buffers): - * files.texi (Comparing Files): Fix cross-references to emacs-xtra. - -2006-05-06 Eli Zaretskii - - The following changes merge the emacs-xtra manual into the main - manual, but only for on-line version of the manual. - - * vc2-xtra.texi (Version Backups, Local Version Control) - (Making Snapshots, Change Logs and VC, Version Headers) - (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for - on-line manual. - - * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's - for on-line manual. - - * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) - (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) - (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's - for on-line manual. - - * fortran-xtra.texi (Fortran, Fortran Autofill) - (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's - for on-line manual. - - * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: - Conditional xref's for on-line manual. - - * emerge-xtra.texi (Emerge, Overview of Emerge) - (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line - manual. - - * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - (../info/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. - (EMACS_XTRA): New variable, lists the new *-xtra.texi files. - (EMACSSOURCES): Use EMACS_XTRA. - ($(infodir)/emacs-xtra): Remove. - (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. - - * trouble.texi (Quitting): - * text.texi (Text): - * programs.texi (Program Modes): - * msdog.texi (Microsoft Windows): - * frames.texi (Frames): - * files.texi (Backup, Version Control, VC Concepts) - (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) - (Registering, VC Status, VC Undo, Multi-User Branching) - (Comparing Files): - * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) - (Displaying the Diary, Special Diary Entries, Importing Diary): - * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by - conditional xref's, depending on @iftex/@ifnottex. - - * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for - "MS-DOS". @include msdog-xtra.texi. - - * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". - [ifnottex]: @include fortran-xtra.texi. - - * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries - for vc-xtra.texi subsections. - (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. - (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. - - * sending.texi (Sending Mail): A @node line without explicit Prev, - Next, and Up links. - - * abbrevs.texi (Abbrevs): A @node line without explicit Prev, - Next, and Up links. - - * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" - and its sections. @include picture-xtra.texi. - - * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for - "Emerge". - (List Tags) [ifnottex]: @include emerge-xtra.texi. - - * cal-xtra.texi (Daylight Savings): Remove this node: it is an - exact duplicate of its name-sake in calendar.texi. - - * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for - "Advanced Calendar/Diary Usage". - (Time Intervals) [ifnottex]: @include cal-xtra.texi. - - * dired.texi (Subdirectories in Dired) [ifnottex]: @include - dired-xtra.texi. - (Dired) [ifnottex]: Add menu entry for "Subdir Switches". - - * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. - (Files) [ifnottex]: Add menu entry for Autorevert. - - * emacs-xtra.texi (Introduction): Reword to make consistent with - printed version only. - : Remove the body of all chapters and move them to the - new *-xtra.texi files. Use @raisesections and @lowersections to - convert sections to chapters etc. - - * msdog-xtra.texi: - * fortran-xtra.texi: - * vc-xtra.texi: - * vc1-xtra.texi: - * vc2-xtra.texi: - * emerge-xtra.texi: - * cal-xtra.texi: - * dired-xtra.texi: - * arevert-xtra.texi: New files, with text from respective chapters - of emacs-xtra.texi. Convert each @chapter into @section, @section - into @subsection, etc. - - * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references - updated. - - * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft - Windows". All references updated. - -2006-05-06 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Mention input from Character Palette. - (Mac Font Specs): Fix typo. - -2006-05-05 Richard Stallman - - * files.texi (Diff Mode): Minor cleanup. - -2006-05-05 Karl Berry - - * emacs.texi: Call @fonttextsize 10, inside @tex to avoid - errors from the current release of makeinfo (4.8). - * help.texi (Library Keywords): Change widest word in multitable - template from `emulations' to `convenience'. (Not sure if this is - related to the font change.) - -2006-05-05 Eli Zaretskii - - * files.texi (File Names): Add a footnote about limited support of - ~USER on MS-Windows. - - * cmdargs.texi (Initial Options): Add a footnote about limited - support of ~USER on MS-Windows. - -2006-05-03 Richard Stallman - - * files.texi (Diff Mode): Node moved here. - (Comparing Files): Delete what duplicates new node. - (Files): Put Diff Mode in menu. - - * misc.texi (Diff Mode): Moved to files.texi. - - * emacs.texi (Top): Update menu for Diff Mode. - - * trouble.texi (Emergency Escape): Simplify. - - * emacs.texi (Top): Minor clarification. - -2006-05-03 Teodor Zlatanov - - * commands.texi, entering.texi, screen.texi: Many simplifications. - -2006-05-03 Richard Stallman - - * commands.texi (Text Characters): Delete paragraph about unibyte - non-ASCII printing chars. - - * killing.texi (Killing): Say "graphical displays". - * display.texi: Say "graphical displays". - - * cmdargs.texi (Misc X): Say "graphical displays". - -2006-05-01 Richard Stallman - - * emacs.texi (Top): Add Diff Mode to menu. - -2006-05-01 Aaron S. Hawley - - * misc.texi (Diff Mode): New node. - -2006-05-01 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. - (Mac Environment Variables): Shorten example line. - (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. - -2006-05-01 Nick Roberts - - * building.texi (GUD Customization): Describe cases %d and %c. - Update description for %e. - -2006-04-30 Glenn Morris - - * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. - -2006-04-29 Dan Nicolaescu - - * custom.texi (Examining): Update C-h v output example. - -2006-04-29 Kim F. Storm - - * building.texi (Grep Searching): Add lgrep and rgrep. - -2006-04-23 Richard Stallman - - * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. - - * xresmini.texi: New file. - - * xresources.texi (Face Resources): Split table into font resources - and the rest. Combine similar attributes for brevity. - -2006-04-21 Eli Zaretskii - - * emacs-xtra.texi (MS-DOS File Names): Remove section about - backslashes and case-insensitivity in file names (moved to the - main manual). - (MS-DOS Printing): Move most of the text to the main manual. - - * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): - New nodes. - (Windows Processes, Windows System Menu): Add index entries and - fix wording. - -2006-04-18 J.D. Smith - - * misc.texi (Shell Ring): Add notes on saved input when - navigating off the end of the history list. - -2006-04-18 Chong Yidong - - * misc.texi (Shell Options): Correct default value of - comint-scroll-show-maximum-output. - -2006-04-18 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2006-04-12 Richard Stallman - - * search.texi: Clean up previous change. - -2006-04-12 Eli Zaretskii - - * search.texi (Regexp Backslash, Regexp Replace): Add index - entries for ``back reference'' and mention the term itself in the - text. - -2006-04-11 Richard Stallman - - * custom.texi (Safe File Variables): - Document enable-local-variables = :safe. - -2006-04-11 Karl Berry - - * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) - (Remote Repositories, Version Backups, Local Version Control) - (Snapshots, Making and Using Snapshots, Snapshot Caveats) - (Miscellaneous Commands and Features of VC, Change Logs and VC) - (Renaming VC Work Files and Master Files) - (Inserting Version Control Headers, Customizing VC, General Options) - (Options for RCS and SCCS, Options specific for CVS): Move all - these nodes to emacs-xtra.texi, for brevity. - * cmdargs.texi, files.texi: Change cross-references. - -2006-04-11 J.D. Smith - - * files.texi (Old Versions): Update description of vc-annotate's - use of color to indicate date ranges. - -2006-04-09 Kevin Ryde - - * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, - put info and printed manual names the right way around. - -2006-04-09 Karl Berry - - * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to - emacs-xtra.texi, leaving only MS Windows information. - * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, - * msdog.texi, mule.texi, trouble.texi: Change cross-references and - node names. - - * emacs.texi: Move @summarycontents and @contents to the beginning - of the file. - -2006-04-08 Kevin Ryde - - * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. - -2006-04-07 Richard Stallman - - * programs.texi (Comments, Comment Commands, Options for Comments) - (Multi-Line Comments): "Align", not "indent". - (Basic Indent): C-j deletes trailing whitespace before the newline. - -2006-04-06 Richard Stallman - - * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. - -2006-04-06 Eli Zaretskii - - * killing.texi (Rectangles): Add index entry for marking a rectangle. - -2006-04-05 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * trouble.texi (Unasked-for Search): Node deleted. - (Lossage): Delete from menu. - -2006-04-04 Richard Stallman - - * trouble.texi: Various cleanups. - (Checklist): Don't bother saying how to snail a bug report. - (Emergency Escape): Much rewriting. - (After a Crash): Rename the core dump immediately. - (Total Frustration): Call it a psychotherapist. - (Bug Criteria): Avoid "illegal instruction". - (Sending Patches): We always put the contributor's name in. - - * misc.texi (Thumbnails): Minor correction. - -2006-04-03 Richard Stallman - - * misc.texi (Thumbnails): Minor cleanup. - -2006-04-02 Karl Berry - - * sending.texi (Mail Sending): pxref to Top needs five args. - - * texinfo.tex: Update to current version (2006-03-21.13). - -2006-03-31 Richard Stallman - - * emacs.texi (Top): Update subnode menu. - - * help.texi (Help Mode): Cleanup. - - * dired.texi: Many cleanups. - (Dired Deletion): Describe dired-recursive-deletes. - (Operating on Files): dired-create-directory moved. - (Misc Dired Features): Move to here. - (Tumme): Node moved to misc.texi. - - * custom.texi: Many cleanups. - (Minor Modes): Don't mention ISO Accents Mode. - (Examining): Update C-h v output example. - (Hooks): Add index and xref for add-hook. - (Locals): Delete list of vars that are always per-buffer. Rearrange. - (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. - - * misc.texi: Many cleanups. - (beginning): Add to summary of topics. - (Shell): Put eshell xref at the end. Remove eshell from table. - (Thumbnails): New node. - -2006-03-28 Eli Zaretskii - - * files.texi (File Name Cache): Make it clear that the cache is - not persistent. - -2006-03-25 Karl Berry - - * emacs-xtra.texi, emacs.texi, gnu.texi: - (1) use @copyright{} instead of (C) in typeset text; - (2) do not indent copyright year list (or anything else). - -2006-03-21 Juanma Barranquero - - * files.texi (VC Dired Mode): Remove misplaced brackets. - -2006-03-21 Andre Spiegel - - * files.texi: Various updates and clarifications in the VC chapter. - -2006-03-19 Luc Teirlinck - - * help.texi (Help Mode): Document "C-c C-c". - -2006-03-16 Luc Teirlinck - - * emacs-xtra.texi (Top): Avoid ugly continuation line in - menu in the standalone Info reader. - -2006-03-15 Chong Yidong - - * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, - moved here from Emacs manual. - - * programs.texi (Fortran): Section moved to emacs-xtra. - (Program Modes): Xref to Fortran in emacs-xtra. - - * maintaining.texi (Emerge): Move to emacs-xtra. - * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. - - * picture.texi: File deleted. - * Makefile.in: - * makefile.w32-in: Remove picture.texi. - - * text.texi (Text): Xref to Picture Mode in emacs-xtra. - * abbrevs.texi (Abbrevs): - * sending.texi (Sending Mail): Picture node removed. - - * emacs.texi (Top): Update node listings. - -2006-03-12 Richard Stallman - - * calendar.texi: Various cleanups. - -2006-03-11 Luc Teirlinck - - * search.texi (Regexps): Use @samp for regexp that is not in Lisp - syntax. - -2006-03-08 Luc Teirlinck - - * search.texi (Regexps): More accurately describe which characters - are special in which situations. Recommend _not_ to quote `]' or - `-' when they are not special. - -2006-02-28 Andre Spiegel - - * files.texi (Old Versions): Clarify operation of C-x v =. - -2006-02-21 Nick Roberts - - * building.texi (Watch Expressions): Update and describe - gdb-speedbar-auto-raise. - -2006-02-19 Richard M. Stallman - - * emacs.texi: Use @smallbook. - (Top): Update ref to Emacs paper, delete ref to Cookbook. - Update subnode menu. - - * building.texi (Lisp Interaction): Minor addition. - -2006-02-18 Nick Roberts - - * building.texi (Watch Expressions): Update and be more precise. - -2006-02-15 Francesco Potortì - - * maintaining.texi (Create Tags Table): Explain why the - exception when etags writes to files under the /dev tree. - -2006-02-14 Richard M. Stallman - - * custom.texi (Safe File Variables): Lots of clarification. - Renamed from Unsafe File Variables. - -2006-02-14 Chong Yidong - - * custom.texi (Unsafe File Variables): File variable confirmation - assumed denied in batch mode. - -2006-02-14 Richard M. Stallman - - * building.texi (GDB User Interface Layout): Don't say `inferior' - for program being debugged. - -2006-02-15 Nick Roberts - - * building.texi (GDB Graphical Interface): - Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. - -2006-02-13 Chong Yidong - - * custom.texi (Specifying File Variables, Unsafe File Variables): - New nodes, split from File Variables. Document new file local - variable behavior. - -2006-02-13 YAMAMOTO Mitsuharu - - * display.texi (Standard Faces): - * files.texi (Visiting): - * frames.texi (Clipboard): - * glossary.texi (Glossary) : - * xresources.texi (X Resources): Mention Mac OS port. - -2006-02-12 Richard M. Stallman - - * building.texi (Building): Clarify topic in intro. - - * maintaining.texi (Maintaining): Change title; clarify topic. - Delete duplicate index entries. - - * building.texi (Other GDB User Interface Buffers): Clarifications. - - * text.texi (Cell Commands): Clarifications. - - * programs.texi (Defuns): Delete duplicate explanation of - left-margin paren convention. - (Hungry Delete): Minor cleanup. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): More tumme documentation. - -2006-02-11 Alan Mackenzie - - * programs.texi ("Hungry Delete"): Correct the appellation of the - backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. - -2006-02-11 Mathias Dahl - - * dired.texi (Tumme): Fix small bug. - -2006-02-10 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Rename "fontset-mac" to - "fontset-standard". - -2006-02-09 Mathias Dahl - - * dired.texi (Tumme): Basic documentation for Tumme added. - -2006-02-07 Luc Teirlinck - - * mule.texi (International): - * programs.texi (Basic Indent): Fix typos. - - * custom.texi (Minor Modes): - * display.texi (Text Display): - * commands.texi (Text Characters): Update xrefs. - -2006-02-07 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - Update info on old Emacs papers. - (Intro): "Graphical display", not window system. - - * xresources.texi (GTK styles): Minor clarifications. - - * trouble.texi: "Graphical display", not window system. - (Stuck Recursive): Minor clarification. - - * text.texi: Minor clarifications. - (Sentences): Explain why two-space convention is better. - Explain sentence-end-without-period here. - (Fill Commands): Not here. - (Refill): Node moved down. - (Filling): Update menu. - (Table Creation, Cell Justification, Column Commands): Clarify. - - * sending.texi: Minor clarifications. - - * search.texi (Regexp Backslash): Clarification. - - * rmail.texi: Minor cleanups. - (Rmail): Delete digression about `rmail-mode'. - (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. - (Rmail Files): Mention C-u M-x rmail. - (Rmail Reply): Mention References. - (Rmail Display): Mention rmail-nonignored-headers. - - * programs.texi: Minor cleanups. - (Comment Commands): Mention momentary Transient Mark mode. - (Matching): Be more specific about customizing show-paren-mode. - (Info Lookup): Don't list the modes that support C-h S. - Just say what it does in an unsupported mode. - (Man Page): Delete excessive info on customizing woman. - (Motion in C): Don't mention c-for/backward-into-nomenclature. - - * abbrevs.texi: Minor clarifications. - (Dabbrev Customization): Talk about "dynamic abbrev expansion", - not "dynamic abbrevs" as if they were a kind of abbrev. - - * picture.texi (Picture): Minor cleanup. - - * mule.texi (Communication Coding): Say "other applications". - (Fontsets): Not specific to X. Add xref to X Resources. - (Unibyte Mode): Rename from Single-Byte Character Support. - "Graphical display", not window system. - (International): Update menu. - - * maintaining.texi (Format of ChangeLog): - New node, split out from ChangeLog. - (ChangeLog): Clarifications in the remaining text. - (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. - (Find Tag): Add @w. - (Tags Search): Explain tag table order here. Simplify grep ref. - (List Tags): tags-tag-face is a variable, not a face. - (Emerge): Cleanups. - - * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. - (Keyboard Macros): Avoid "the user". - - * killing.texi: "Graphical display", not window system. - - * help.texi (Help Echo): "Graphical display", not window system. - - * glossary.texi: Say "you", not "the user". Say "graphical display". - - * frames.texi: Minor cleanups. "Graphical display", not window system. - - * files.texi (Visiting): Make drag-and-drop not X-specific. - - * custom.texi: Minor cleanups. "Graphical display", not window system. - - * cmdargs.texi: Minor cleanups. - - * building.texi (Compilation): Move and split kill-compilation para. - Add para about multiple compilers. - (Compilation Mode): Commands also available in grep mode and others. - Mention C-u C-x ` more tutorially. Clarify C-x `. - (Compilation Shell): Clarify. Put Bash example first. - (Grep Searching): Minor cleanups; add @w. - (Debuggers): Minor cleanups. - (Starting GUD): Make GDB xgraphical mode issue clearer. - (Debugger Operation): Lots of clarifications including - GDB tooltip side-effect issue. - (Commands of GUD): Clarify. - (GUD Customization): Add bashdb-mode-hook. - (GDB Graphical Interface): Rewrite for clarity. - (GDB User Interface Layout): Rewrite for clarity. - (Stack Buffer, Watch Expressions): Likewise. - (Other GDB User Interface Buffers): Cleanups. - (Lisp Libraries, External Lisp): Cleanup. - - * basic.texi (Position Info): "Graphical displays", rather than - window systems. - - * anti.texi: Minor cleanup. - -2006-02-03 Eli Zaretskii - - * custom.texi (Init File, Find Init): Add cross-references to - where $HOME is described. - -2006-02-01 Luc Teirlinck - - * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it - is not inside the @table. - - * emacs.texi (Top): Correct node name. - - * files.texi (File Names): Fix @xref. - (Reverting): Fix typo. - - * mule.texi (International): Correct node name. - - * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. - -2006-02-01 Richard M. Stallman - - * emacs.texi (Top): Update subnode menu. - - * mule.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Text Coding): Rename from Specify Coding. - (Communication Coding, File Name Coding, Terminal Coding): - New nodes split out from Text Coding. - - * kmacro.texi: Minor clarifications. - (Keyboard Macro Ring): Comment out some excessive commands. - (Basic Keyboard Macro): Split up the table, putting part in each node. - - * major.texi: Minor clarifications. - - * misc.texi (Single Shell, Interactive Shell): Fix xrefs. - - * windows.texi: Minor clarifications. - (Change Window): Don't describe mode-line mouse cmds here. - Add xref to Mode Line Mouse. - - * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. - - * macos.texi (Mac International): Fix xref. - - * indent.texi: Minor clarifications. - - * frames.texi: Minor clarifications. - Reduce the specific references to X Windows. - Refer to "graphical" terminals, rather than window systems. - (Frame Parameters): Don't mention commands like - set-foreground-color. Just say to customize a face. - (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. - - * files.texi: Minor clarifications. - (Numbered Backups): New node, split out from Backup Names. - - * display.texi (Font Lock): C mode no longer depends on (-in-col-0. - - * cmdargs.texi (General Variables): Fix xref. - - * buffers.texi: Minor clarifications. - -2006-01-31 Richard M. Stallman - - * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): - Nodes moved to top. - - * display.texi: Minor clarifications. - (Display): Rearrange menu. - (Standard Faces): Mention query-replace face. - (Faces): Simplify. - (Font Lock): Simplify face customization info. - (Highlight Changes): Node merged into Highlight Interactively. - (Highlight Interactively): Much rewriting and cleanup. - (Optional Mode Line): Narrowed line number not good for goto-line. - Simplify face customization advice. - (Text Display): Mention use of escape-glyph face. - Move ctl-arrow and tab-width here. - (Display Custom): Move no-redraw-on-reenter to end of node. - - * search.texi: Minor clarifications. - (Isearch Scroll): Simplify. - (Other Repeating Search): Document multi-occur-in-matching-buffers. - - * regs.texi (Registers): Mention bookmarks here. - - * mark.texi: Minor clarifications. - (Selective Undo): Node deleted. - - * m-x.texi: Minor clarifications. - - * killing.texi: Minor clarifications. - Refer to "graphical" terminals, rather than window systems. - - * help.texi: Clarifications. - (Help): Don't describe C-h F and C-h K here. - (Key Help): Describe C-h K here. - (Name Help): Mention Emacs Lisp Intro. - Describe C-h F here. - (Misc Help): Mention C-h F and C-h K only briefly. - - * fixit.texi (Undo): New node, mostly copied from basic.texi. - Selective undo text merged in. - (Spelling): Mention Aspell along with Ispell. - - * emacs.texi (Top): Update subnode menus. - - * basic.texi (Basic Undo): Rename from Undo. Most of text - moved to new Undo node. - -2006-01-29 Chong Yidong - - * basic.texi (Continuation Lines, Inserting Text): - Mention longlines mode. - -2006-01-29 Richard M. Stallman - - * screen.texi: Minor cleanups. - (Screen): Clean up the intro paragraphs. - (Mode Line): Lots of rewriting. Handle frame-name better. - eol-mnemonic-... vars moved out. - - * emacs.texi (Top): Change menu item for MS-DOS node. - Update subnode menu. - - * msdog.texi (MS-DOS): Rewrite intro to explain how this - chapter relates to Windows. Title changed. - - * mini.texi: Minor cleanups. - - * mark.texi (Selective Undo): New node, text moved from basic.texi. - (Mark): Put it in the menu. - - * entering.texi: Minor cleanups. - - * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. - (Intro): Refer to "graphical" terminals, rather than X. - - * display.texi (Display Custom): Add xref to Variables. - (Optional Mode Line): eol-mnemonic-... vars moved here. - - * commands.texi: Minor cleanups. Refer to "graphical" terminals, - rather than X. - - * basic.texi: Minor cleanups. - (Undo): selective-undo moved. - -2006-01-25 Luc Teirlinck - - * anti.texi (Antinews): Various corrections and additions. - -2006-01-23 Juri Linkov - - * custom.texi (Easy Customization, Customization Groups) - (Browsing Custom): Mention links along with buttons. - -2006-01-21 Eli Zaretskii - - * text.texi (TeX Print): Use @key for TAB. - - * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. - -2006-01-15 Sven Joachim (tiny change) - - * files.texi (File Aliases): Don't claim that usually separate - buffers are created for two file names that name the same data. - Mention additional situations where different names mean the same - file on disk. - -2006-01-19 Richard M. Stallman - - * killing.texi (Deletion): Upcase @key argument. - - * custom.texi (Custom Themes): Minor cleanup. - - * programs.texi (Hungry Delete): Upcase @key argument. - -2006-01-16 Juri Linkov - - * display.texi (Standard Faces): Add `mode-line-buffer-id'. - Move `mode-line-highlight' before `mode-line-buffer-id'. - -2006-01-14 Richard M. Stallman - - * basic.texi (Inserting Text): Minor cleanup. - -2006-01-11 Luc Teirlinck - - * custom.texi (Changing a Variable, Face Customization): - Update for changes in Custom menus. - -2006-01-05 YAMAMOTO Mitsuharu - - * macos.texi (Mac International): Undo last change. - -2006-01-02 Chong Yidong - - * custom.texi (Custom Themes): Describe the new - customize-create-theme interface. - -2005-12-30 Juri Linkov - - * basic.texi (Position Info): Update example. - -2005-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. - -2005-12-24 Chong Yidong - - * custom.texi (Custom Themes): `load-theme' always loads. - -2005-12-23 Juri Linkov - - * display.texi (Highlight Interactively): Use double space to - separate sentences. Replace C-p with M-p, and C-n with M-n. - -2005-12-22 Richard M. Stallman - - * custom.texi (Easy Customization and subnodes): - Replace "active field" with "button". - Use "user option" only for variables. - Use "setting" for variable-or-face. - -2005-12-22 Luc Teirlinck - - * buffers.texi (Select Buffer): Change order in table to make - "Similar" refer to the correct item. - (Indirect Buffers): Minor rewording. - -2005-12-20 Juri Linkov - - * files.texi (VC Status): Put P and N near p and n. - -2005-12-19 Richard M. Stallman - - * programs.texi (Electric C): Delete the info about newline control. - (Other C Commands): Minor cleanup. - (Left Margin Paren): Minor cleanup. - -2005-12-19 Luc Teirlinck - - * custom.texi (Easy Customization): Add "Browsing Custom" to menu. - (Customization Groups): Delete text moved to "Browsing Custom". - (Browsing Custom): New node. - (Specific Customization): Clarify which commands only work for - loaded options. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Shorten text of previous change. - -2005-12-18 Aaron S. Hawley - - * files.texi (VC Status): Document log-view mode. - -2005-12-18 Bill Wohler - - * frames.texi (Tool Bars): Mention that you can turn off tool bars - permanently via the customize interface. - -2005-12-16 Ralf Angeli - - * killing.texi (Killing by Lines): Document `kill-whole-line' - function. - -2005-12-16 Lőrentey Károly - - * buffers.texi (Select Buffer): Change `prev-buffer' to - `previous-buffer'. Indicate that these functions use a frame - local buffer list. - -2005-12-12 Richard M. Stallman - - * custom.texi (Easy Customization): Change menu comment. - (Prefix Keymaps): Fix spelling of Control-X-prefix. - - * help.texi (Apropos): Rewrite. Talk about "apropos patterns". - (Help): Among the Apropos commands, describe only C-h a here. - -2005-12-11 Richard M. Stallman - - * programs.texi (Options for Comments): Comment-end starts with space. - - * glossary.texi (Glossary): Minor cleanup. - - * files.texi (Old Versions): Use @table. - -2005-12-10 David Koppelman - - * display.texi (Highlight Interactively): Include - global-hi-lock-mode. Add miscellaneous details and elaborations. - -2005-12-09 Richard M. Stallman - - * display.texi (Font Lock): Delete the Global FL menu item. - -2005-12-09 Luc Teirlinck - - * custom.texi (Minibuffer Maps): Mention the maps for file name - completion. - -2005-12-09 Kim F. Storm - - * killing.texi (CUA Bindings): Describe how to use C-x and C-c as - prefix keys even when mark is active. Describe that RET moves - cursor to next corner in rectangle; clarify insert around rectangle. - -2005-12-08 Luc Teirlinck - - * custom.texi (Customization): Use xref to elisp manual for - non-TeX output. - (Minor Modes): Update. - (Customization Groups, Changing a Variable, Face Customization): - Update for new appearance of Custom buffers. - (Changing a Variable): `custom-buffer-done-function' has been - replaced by `custom-buffer-done-kill'. - (Specific Customization): In the `customize-group' buffer, a - subgroup's contents are not "hidden". They are not included at - all. They have no [Show] button. - (Mouse Buttons): Add pxref to description of mouse event lists in - Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. - (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of - ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). - -2005-12-08 Richard M. Stallman - - * mini.texi (Completion Commands, Completion): - In file name input, SPC does not do completion. - -2005-12-08 Nick Roberts - - * building.texi (GDB Graphical Interface): Explain screen size - setting. - (Other GDB User Interface Buffers): Describe features specific to - GDB 6.4. - -2005-12-01 Nick Roberts - - * building.texi (GDB User Interface Layout): Describe how to - kill associated buffers. - (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. - (Watch Expressions): Be more precise. - (Other GDB User Interface Buffers): Describe how to change a - register value. - -2005-11-24 YAMAMOTO Mitsuharu - - * macos.texi (Mac Input): Remove description of - mac-command-key-is-meta. Add descriptions of - mac-control-modifier, mac-command-modifier, and - mac-option-modifier. - (Mac International): Fix description of conversion of clipboard data. - (Mac Font Specs): Add example of font customization by face attributes. - -2005-11-22 Nick Roberts - - * building.texi (Watch Expressions): Expand description. - (Other GDB User Interface Buffers): Describe local map for - gud-watch. - -2005-11-21 Chong Yidong - - * display.texi (Font Lock): Font lock is enabled by default now. - -2005-11-20 Juri Linkov - - * basic.texi (Position Info): Update examples of the output. - Remove the fact that examples are produced in the TeXinfo buffer, - because in the Info reader users will get a different output from - `C-x ='. - - * building.texi (Compilation Mode): Remove paragraph duplicated - from the node `Compilation'. Add `compilation-skip-threshold'. - - * display.texi (Font Lock): Suggest more user-friendly method of - finding all Font Lock faces (M-x customize-group RET font-lock-faces). - -2005-11-18 Richard M. Stallman - - * files.texi (Registering): Mention @@ in mode line. - - * mini.texi (Minibuffer File): Clarify previous change. Add @findex. - -2005-11-08 Aaron S. Hawley - - * files.texi (Renaming and VC): Some back-ends don't - handle renaming. - -2005-11-17 Juri Linkov - - * emacs.texi (Top): - * display.texi (Highlight Interactively): Put this font-lock based - mode near Font Lock node. - -2005-11-16 Chong Yidong - - * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs - icons. - -2005-11-12 Kim F. Storm - - * help.texi (Help): Fix C-h a entry. Add C-h d entry. - (Help Summary): Add C-h d and C-h e. - (Apropos): Clarify that all apropos commands may search for either - list of words or a regexp. Add C-h d for apropos-documentation. - Describe apropos-documentation-sort-by-scores user option. - -2005-11-09 Luc Teirlinck - - * killing.texi (CUA Bindings): Add @section. - -2005-11-10 Kim F. Storm - - * emacs.texi (Top): Add CUA Bindings entry to menu. - - * killing.texi (CUA Bindings): New node. Moved here from - misc.texi and extended with info on rectangle commands and - rectangle highlighting, interface to registers, and the global - mark feature. - - * misc.texi (Emulation): Move CUA bindings item to killing.texi. - - * regs.texi: Prev link points to CUA Bindings node. - -2005-11-07 Luc Teirlinck - - * help.texi (Help Echo): By default, help echos are only shown on - mouse-over, not on point-over. - -2005-11-04 Jérôme Marant - - * misc.texi (Shell Mode): Describe how to activate password echoing. - -2005-11-04 Romain Francoise - - * mark.texi (Mark Ring): Fix typo. - -2005-11-03 Richard M. Stallman - - * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. - -2005-11-01 Bill Wohler - - * help.texi (Help Mode): Fix typo. - -2005-11-01 Nick Roberts - - * building.texi (Other GDB User Interface Buffers): Describe - the command gdb-use-inferior-io-buffer. - -2005-10-31 Romain Francoise - - * files.texi (Compressed Files): Fix typo. - - * buffers.texi (Misc Buffer): Downcase `*shell*'. - - * windows.texi (Force Same Window): Likewise. - -2005-10-30 Bill Wohler - - * help.texi (Help Mode): URLs viewed with browse-url. - -2005-10-31 Nick Roberts - - * building.texi (GDB Graphical Interface): Don't reference - gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until - must stay in same frame. - -2005-10-29 Chong Yidong - - * custom.texi (Init File): Document ~/.emacs.d/init.el. - - * anti.texi (Antinews): Likewise. - -2005-10-28 Bill Wohler - - * help.texi (Help): Help mode now creates hyperlinks for URLs. - -2005-10-28 Richard M. Stallman - - * files.texi (Visiting): Explain how to enter ? in a file name. - - * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. - -2005-10-25 Nick Roberts - - * building.texi (GDB Graphical Interface): Describe - gdb-mouse-until. - -2005-10-23 Richard M. Stallman - - * custom.texi (Init File): Recommend when to use site-start.el. - -2005-10-21 Juri Linkov - - * custom.texi (Examining): Mention accessing the old variable - value via M-n in set-variable. - -2005-10-18 Romain Francoise - - * files.texi (Version Systems): Capitalize GNU. - -2005-10-18 Nick Roberts - - * building.texi (Compilation Mode): Remove redundant paragraph. - (Watch Expressions): Remove paragraph to reflect code change. - -2005-10-16 Richard M. Stallman - - * building.texi (Compilation Mode, Compilation): Clarified. - -2005-10-15 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Mention savehist library. - -2005-10-13 Kenichi Handa - - * basic.texi (Position Info): Fix previous change. - -2005-10-12 Jan Djärv - - * cmdargs.texi (Icons X): Fix typo. - -2005-10-12 Kenichi Handa - - * basic.texi (Position Info): Describe the case that Emacs shows - "part of display ...". - -2005-10-10 Jan Djärv - - * cmdargs.texi (Icons X): -nb => -nbi. - -2005-10-10 Chong Yidong - - * frames.texi (Speedbar): A couple more clarifications. - -2005-10-11 Nick Roberts - - * building.texi (GDB User Interface Layout): Improve diagram. - (Watch Expressions): Explain how to make speedbar global. - (Other GDB User Interface Buffers): Make references more precise. - -2005-10-09 Richard M. Stallman - - * frames.texi (Speedbar): Clarify the text. - -2005-10-09 Chong Yidong - - * frames.texi (Speedbar): Add information on keybindings, - dismissing the speedbar, and buffer display mode. Link to - speedbar manual. - -2005-10-09 Jan Djärv - - * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type, - added -nb, --no-bitmap-icon. - -2005-10-07 Nick Roberts - - * building.texi (GDB Graphical Interface): Add variables and - functions to indices. Be more precise. - -2005-10-03 Jan Djärv - - * frames.texi (Drag and Drop): Remove the x- from - x-dnd-open-file-other-window and xdnd-protocol-alist. - -2005-09-30 Romain Francoise - - * mini.texi (Minibuffer): The default value now appears before the - colon in minibuffer prompts. - -2005-09-25 Richard M. Stallman - - * search.texi (Regexp Search): Doc search-whitespace-regexp. - -2005-09-20 Emanuele Giaquinta (tiny change) - - * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. - -2005-09-21 YAMAMOTO Mitsuharu - - * emacs.texi (Top): Update submenus from macos.texi. - - * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. - (Mac OS): Update feature support status. - (Mac Input): List supported input scripts. Remove description - about `mac-keyboard-text-encoding'. Mention mouse button - emulation and related variables. - (Mac International): Mention Central European and Cyrillic - support. Now `keyboard-coding-system' is dynamically changed. - Add description about coding system for selection. Add - description about language environment. - (Mac Environment Variables): Mention - `~/.MacOSX/environment.plist'. Give example of command line - arguments. Add Preferences support. - (Mac Directories): Explicitly state that this node is for Mac OS - Classic only. - (Mac Font Specs): Mention specification for scalable fonts. List - supported charsets. Add preferred way of creating fontsets. Add - description about `mac-allow-anti-aliasing'. - (Mac Functions): Add descriptions about `mac-set-file-creator', - `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', - and `mac-get-preference'. - -2005-09-16 Romain Francoise - - Update all files to specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Richard M. Stallman - - * buffers.texi (List Buffers): Fix xref. - - * rmail.texi (Rmail Basics): Fix xref. - - * emacs.texi (Top): Update subnode menus. - - * files.texi (Saving Commands): New node, broken out of Saving. - (Customize Save): New node, broken out of Saving. - Clarify effect of write-region-inhibit-fsync. - (Misc File Ops): Say write-region-inhibit-fsync affects write-region. - -2005-09-14 Romain Francoise - - * files.texi (Saving): Mention write-region-inhibit-fsync. - -2005-09-05 Chong Yidong - - * custom.texi (Custom Themes): New node. - -2005-09-03 Richard M. Stallman - - * search.texi (Search Case): Mention vars that control - case-fold-search for various operations. - -2005-08-22 Juri Linkov - - * display.texi (Standard Faces): Merge the text from - `(elisp)Standard Faces' into this node. - -2005-08-18 Luc Teirlinck - - * emacs.texi (Top): Delete menu item for deleted node - Keyboard Translations. - -2005-08-18 Richard M. Stallman - - * trouble.texi (Unasked-for Search): - Delete xref to Keyboard Translations. - - * glossary.texi (Glossary): Delete xref. - - * custom.texi (Minor Modes): Say that the list here is not complete. - (Keyboard Translations): Node deleted. - (Disabling): Delete xref to it. - (Customization Groups): Fix Custom buffer example. - (Hooks): Mention remove-hooks. - -2005-08-17 Luc Teirlinck - - * building.texi (GDB Graphical Interface): Improve filling of menu - item. - -2005-08-18 Nick Roberts - - * building.texi (GDB Graphical Interface): Use better node names. - -2005-08-14 Richard M. Stallman - - * text.texi (Sentences): Fix xref. - -2005-08-14 Juri Linkov - - * building.texi (Compilation, Grep Searching): Move grep command - headings from `Compilation' to `Grep Searching'. - - * dired.texi (Dired and Find): - * maintaining.texi (Tags Search): Replace grep xref to - `Compilation' node with `Grep Searching'. - - * files.texi (Comparing Files): Replace xref to `Compilation' with - `Compilation Mode'. - -2005-08-13 Alan Mackenzie - - * search.texi (Non-ASCII Isearch): Correct a typo. - (Replacement Commands): Mention query-replace key binding. - -2005-08-11 Richard M. Stallman - - * programs.texi (Options for Comments): Fix xref. - - * search.texi (Regexp Backslash, Regexp Example): New nodes split - out of Regexps. - -2005-08-09 Juri Linkov - - * building.texi (Compilation): Use `itemx' instead of `item'. - (Grep Searching): Simplify phrase. - - * display.texi (Standard Faces): Describe vertical-border on - window systems. - - * windows.texi (Split Window): Simplify phrase and mention - vertical-border face. - -2005-08-09 Richard M. Stallman - - * files.texi (Comparing Files): Clarify compare-windows. - - * calendar.texi (Scroll Calendar): Document < and > in calendar. - -2005-08-06 Eli Zaretskii - - * mule.texi (Coding Systems): Rephrase the paragraph about - codepages: no need for "M-x codepage-setup" anymore, except on - MS-DOS. - - * msdog.texi (MS-DOS and MULE): Clarify that this section is for - the MS-DOS port only. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run multi-install-info.bat. - ($(infodir)/dir): New target, produced by running - multi-install-info.bat. - -2005-07-22 Eli Zaretskii - - * files.texi (Quoted File Names): Add index entry. - -2005-07-19 Juri Linkov - - * files.texi (Comparing Files): Mention resync for `compare-windows'. - -2005-07-18 Juri Linkov - - * custom.texi (Easy Customization): - * files.texi (Old Versions): - * frames.texi (Wheeled Mice): - * mule.texi (Specify Coding): - * text.texi (Cell Justification): - * trouble.texi (After a Crash): - * xresources.texi (GTK styles): - Delete duplicate duplicate words. - -2005-07-17 Richard M. Stallman - - * frames.texi (Creating Frames): Fix foreground color example. - - * custom.texi (Init Examples): Clean up text about conditionals. - -2005-07-16 Richard M. Stallman - - * mini.texi (Completion Commands): Fix command name for ?. - -2005-07-16 Eli Zaretskii - - * display.texi (Standard Faces): Explain that customization of - `menu' face has no effect on w32 and with GTK. Add - cross-references. - - * cmdargs.texi (General Variables): Clarify the default location - of $HOME on w32 systems. - -2005-07-15 Jason Rumney - - * cmdargs.texi (General Variables): Default HOME on MS Windows has - changed. - -2005-07-08 Kenichi Handa - - * mule.texi (Recognize Coding): Recommend - revert-buffer-with-coding-system instead of revert-buffer. - -2005-07-07 Richard M. Stallman - - * anti.texi (Antinews): Mention mode-line-inverse-video. - - * files.texi (Saving): Minor correction about C-x C-w. - - * display.texi (Display Custom): Don't mention mode-line-inverse-video. - -2005-07-07 Luc Teirlinck - - * search.texi (Isearch Scroll): Add example of using the - `isearch-scroll' property. - (Slow Isearch): Reference anchor for `baud-rate' instead of entire - `Display Custom' node. - (Regexp Replace): Put text that requires Emacs Lisp knowledge last - and de-emphasize it. - (Other Repeating Search): `occur' currently can not correctly - handle multiline matches. Correct, clarify and update description - of `flush-lines' and `keep-lines'. - - * display.texi (Display Custom): Add anchor for `baud-rate'. - -2005-07-07 Richard M. Stallman - - * gnu.texi: Update where to get GNU status; add refs for how to help. - Add footnotes 6 and 7. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * trouble.texi (Checklist): Update FSF's address. - -2005-06-24 Richard M. Stallman - - * display.texi (Text Display): Change index entries. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in - Makefile.in. - -2005-06-23 Richard M. Stallman - - * anti.texi (Antinews): Renamed show-nonbreak-escape to - nobreak-char-display. - - * emacs.texi (Top): Update detailed node listing. - - * display.texi (Text Display): Renamed show-nonbreak-escape - to nobreak-char-display and no-break-space to nobreak-space. - (Standard Faces): Split up the list of standard faces - and put it in a separate node. Add nobreak-space and - escape-glyph. - -2005-06-23 Lute Kamstra - - * mule.texi (Select Input Method): Fix typo. - -2005-06-23 Kenichi Handa - - * mule.texi (International): List all supported scripts. Adjust - text for that leim is now included in the normal Emacs - distribution. - (Language Environments): List all language environments. - Intlfonts contains fonts for most supported scripts, not all.. - (Select Input Method): Refer to C-u C-x = to see how to type to - input a specific character. - (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. - -2005-06-23 Juanma Barranquero - - * building.texi (Grep Searching): Texinfo usage fix. - -2005-06-22 Miles Bader - - * display.texi (Faces): Change `vertical-divider' to `vertical-border'. - -2005-06-20 Miles Bader - - * display.texi (Faces): Add `vertical-divider'. - -2005-06-17 Richard M. Stallman - - * text.texi (Adaptive Fill): Minor clarification. - -2005-06-10 Lute Kamstra - - * emacs.texi (Top): Correct version number. - * anti.texi (Antinews): Correct version number. Use EMACSVER to - refer to the current version of Emacs. - -2005-06-08 Luc Teirlinck - - * files.texi (Log Buffer): Document when there can be more than - one file to be committed. - -2005-06-08 Juri Linkov - - * display.texi (Faces): Add `shadow' face. - -2005-06-07 Masatake YAMATO - - * display.texi (Faces): Write about mode-line-highlight. - -2005-06-06 Richard M. Stallman - - * misc.texi (Printing Package): Explain how to initialize - printing package. - - * cmdargs.texi (Action Arguments): Clarify directory default for -l. - -2005-06-05 Chong Yidong - - * emacs.texi: Rename Hardcopy to Printing. - Make PostScript and PostScript Variables subnodes of it. - - * misc.texi (Printing): Rename node from Hardcopy. - Mention menu bar options. - Move PostScript and PostScript Variables to submenu. - (Printing package): New node. - - * mark.texi (Using Region): Change Hardcopy xref to Printing. - - * dired.texi (Operating on Files): Likewise. - - * calendar.texi (Displaying the Diary): Likewise. - - * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. - - * glossary.texi (Glossary): Likewise. - - * frames.texi (Mode Line Mouse): Mention mode-line-highlight - effect. - -2005-06-04 Richard M. Stallman - - * trouble.texi (After a Crash): Polish previous change. - -2005-05-30 Noah Friedman - - * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a - recovery mechanism. - -2005-05-28 Nick Roberts - - * building.texi (Other Buffers): SPC toggles display of - floating point registers. - -2005-05-27 Nick Roberts - - * files.texi (Log Buffer): Merge in description of Log Edit - mode from pcl-cvs.texi. - -2005-05-26 Richard M. Stallman - - * building.texi (Lisp Eval): C-M-x with arg runs Edebug. - -2005-05-24 Luc Teirlinck - - * fixit.texi (Spelling): Delete confusing sentence; flyspell is - not enabled by default. - When not on a word, `ispell-word' by default checks the word - before point. - -2005-05-24 Nick Roberts - - * building.texi (Debugger Operation): Simplify last sentence. - -2005-05-23 Lute Kamstra - - * emacs.texi: Update FSF's address throughout. - (Preface): Use @cite. - (Distrib): Add cross reference to the node "Copying". Mention the - FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of - printed manuals. - (Intro): Use @xref for the Emacs Lisp Intro. - -2005-05-18 Luc Teirlinck - - * buffers.texi (Select Buffer): Document `C-u M-g M-g'. - - * basic.texi (Moving Point): Mention default for `goto-line'. - - * programs.texi (Lisp Doc): Eldoc mode shows only the first line - of a variable's docstring. - -2005-05-18 Lute Kamstra - - * maintaining.texi (Overview of Emerge): Add cross reference. - Remove duplication. - - * emacs.texi (Top): Update to the current structure of the manual. - * misc.texi (Emacs Server): Add menu description. - * files.texi (Saving): Fix menu. - * custom.texi (Customization): Fix menu. - * mule.texi (International): Fix menu. - * kmacro.texi (Keyboard Macros): Fix menu. - -2005-05-16 Luc Teirlinck - - * display.texi: Various minor changes. - (Faces): Delete text that is repeated in the next section. - -2005-05-16 Nick Roberts - - * building.texi (Debugger Operation): Mention GUD tooltips are - disabled with GDB in text command mode. - -2005-05-16 Nick Roberts - - * building.texi: Replace toolbar with "tool bar" for consistency. - (Compilation Mode): Describe compilation-context-lines - and use of arrow in compilation buffer. - (Debugger Operation): Replace help text with variable's value. - - * frames.texi (Tooltips): Replace toolbar with "tool bar" for - consistency. - -2005-05-15 Luc Teirlinck - - * major.texi (Choosing Modes): normal-mode processes the -*- line. - Add xref. - -2005-05-14 Luc Teirlinck - - * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. - (Position Info): Delete discussion of `goto-line'. It is already - described in `Moving point'. - - * mini.texi (Completion Commands): Correct reference. - (Completion Options): Fix typo. - - * killing.texi (Deletion): Complete description of `C-x C-o'. - -2005-05-10 Richard M. Stallman - - * building.texi (Compilation): Clarify recompile's directory choice. - - * frames.texi (Tooltips): Cleanups. - - * basic.texi (Arguments): Fix punctuation. - -2005-05-09 Luc Teirlinck - - * screen.texi (Menu Bar): The up and down (not left and right) - arrow keys move through a keyboard menu. - -2005-05-08 Luc Teirlinck - - * basic.texi: Various typo and grammar fixes. - (Moving Point): C-a now runs move-beginning-of-line. - -2005-05-08 Nick Roberts - - * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. - - * frames.texi (Tooltips): Describe help tooltips and GUD tooltips - as different animals. - -2005-05-07 Luc Teirlinck - - * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. - Correct index entry. - -2005-05-07 Nick Roberts - - * building.texi (Debugger Operation): Update to reflect changes - in GUD tooltips. - -2005-04-30 Richard M. Stallman - - * files.texi (Compressed Files): Auto Compression normally enabled. - - * building.texi (Debugger Operation): Clarify previous change. - -2005-04-28 Nick Roberts - - * building.texi (Debugger Operation): Add description for - GUD tooltips when program is not running. - -2005-04-26 Luc Teirlinck - - * misc.texi (Shell): Add `Shell Prompts' to menu. - (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' - description. Delete remarks moved to new node. - (Shell Prompts): New node. - (History References): Replace remarks moved to `Shell Prompts' - with xref to that node. - (Remote Host): Clarify how to specify the terminal type when - logging in to a different machine. - -2005-04-26 Richard M. Stallman - - * emacs.texi (Top): Update submenus from files.texi. - - * files.texi (Filesets): Clarify previous change. - - * dired.texi (Misc Dired Features): Clarify previous change. - -2005-04-25 Chong Yidong - - * ack.texi (Acknowledgments): Delete info about iso-acc.el. - - * dired.texi (Misc Dired Features): Document - dired-compare-directories. - - * files.texi (Filesets): New node. - (File Conveniences): Document Image mode. - - * text.texi (TeX Print): Document tex-compile. - -2005-04-25 Luc Teirlinck - - * frames.texi (Tooltips): Tooltip mode is enabled by default. - Delete redundant reference to tooltip Custom group. It is - referred too again in the next paragraph. - -2005-04-24 Richard M. Stallman - - * ack.texi: Delete info about lazy-lock.el and fast-lock.el. - -2005-04-19 Kim F. Storm - - * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. - -2005-04-18 Lars Hansen - - * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now - turns off desktop-save-mode. - -2005-04-17 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled - by default in terminals compatible with xterm. Mention that - xterm-mouse-mode is a minor mode and put in pxref to Minor Modes - node. - -2005-04-12 Luc Teirlinck - - * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. - -2005-04-12 Jan Djärv - - * xresources.texi (Table of Resources): Add cursorBlink. - -2005-04-11 Luc Teirlinck - - * rmail.texi (Rmail Summary Edit): Explain numeric arguments to - `d', `C-d' and `u'. - -2005-04-11 Richard M. Stallman - - * cmdargs.texi (Initial Options): -Q is now --quick, and does less. - (Misc X): Add -D, --basic-display. - - * maintaining.texi (Change Log): Correct the description of - the example. - - * major.texi (Choosing Modes): Document magic-mode-alist. - -2005-04-10 Luc Teirlinck - - * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. - (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. - (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. - (Rmail Output): Clarify which statements apply to `o', `C-o' and - `w', respectively. - (Rmail Labels): Mention `l'. - (Rmail Attributes): Correct pxref. Mention `stored' attribute. - (Rmail Summary Edit): Describe `j' and RET. - -2005-04-10 Jan Djärv - - * xresources.texi (Lucid Resources): Add fontSet resource. - -2005-04-09 Luc Teirlinck - - * display.texi (Useless Whitespace): `indicate-unused-lines' is - now called `indicate-empty-lines'. - -2005-04-06 Kim F. Storm - - * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. - -2005-04-04 Luc Teirlinck - - * dired.texi (Dired Visiting): `dired-view-command-alist' has been - deleted. - (Marks vs Flags): Add some convenient key bindings. - (Hiding Subdirectories): Delete redundant and inaccurate sentence. - (Misc Dired Features): Correct and expand description of `w' command. - - * frames.texi (XTerm Mouse): Delete apparently false info. - The GNU/Linux console currently does not appear to support - `xterm-mouse-mode'. - -2005-04-03 Glenn Morris - - * calendar.texi (Diary): Mention shell utility `calendar'. - -2005-04-01 Richard M. Stallman - - * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. - -2005-04-01 Lute Kamstra - - * maintaining.texi (Change Log): add-change-log-entry uses - add-log-mailing-address. - -2005-03-31 Luc Teirlinck - - * files.texi (Reverting): Move `auto-revert-check-vc-info' to - `VC Mode Line' and put in an xref to that node. - (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify - its description. - -2005-03-31 Paul Eggert - - * calendar.texi (Calendar Systems): Say that the Persian calendar - implemented here is the arithmetical one championed by Birashk. - -2005-03-30 Glenn Morris - - * programs.texi (Fortran Motion): Fix previous change. - -2005-03-29 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. - -2005-03-29 Chong Yidong - - * text.texi (Refill): Refer to Long Lines Mode. - (Longlines): New node. - (Auto Fill): Don't index "word wrap" here. - (Filling): Add Longlines to menu. - -2005-03-29 Richard M. Stallman - - * xresources.texi: Minor fixes. - - * misc.texi (Emacs Server): Fix Texinfo usage. - - * emacs.texi (Top): Don't use a real section heading for - "Detailed Node Listing". Fake it instead. - - * basic.texi (Position Info): Minor cleanup. - - * mule.texi (Input Methods): Minor cleanup. - -2005-03-29 Glenn Morris - - * programs.texi (ForIndent Vars): `fortran-if-indent' does other - constructs as well. - (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. - -2005-03-29 Kenichi Handa - - * mule.texi (Input Methods): Refer to the command C-u C-x =. - - * basic.texi (Position Info): Update the description about the - command C-u C-x =. - -2005-03-28 Richard M. Stallman - - * emacs.texi (Top): Use @section for the detailed node listing. - - * calendar.texi: Minor fixes to previous change. - - * programs.texi (Fortran): Small fixes to previous changes. - - * emacs.texi (Top): Update list of subnodes of Dired. - Likewise for building.texi. - - * files.texi (File Conveniences): Delete Auto Image File mode. - -2005-03-28 Chong Yidong - - * building.texi (Flymake): New node. - - * custom.texi (Function Keys): Document kp- event types and - keypad-setup package. - - * dired.texi (Wdired): New node. - - * files.texi (File Conveniences): Reorder entries. - Explain how to turn on Auto-image-file mode. - Document Thumbs mode. - - * mule.texi (Specify Coding): Document recode-region and - recode-file-name. - - * programs.texi (Program Modes): Add Conf mode and DNS mode. - -2005-03-27 Luc Teirlinck - - * commands.texi (Keys): M-o is now a prefix key. - -2005-03-27 Glenn Morris - - * programs.texi: Reformat and update copyright years. - (Fortran): Update section. - -2005-03-26 Luc Teirlinck - - * files.texi: Several small changes in addition to: - (Visiting): Change xref for Dialog Boxes to ref. - (Version Headers): Replace references to obsolete var - `vc-header-alist' with `vc-BACKEND-header'. - (Customizing VC): Update value of `vc-handled-backends'. - -2005-03-26 Glenn Morris - - * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; - move here from Emacs Lisp Reference Manual. - * calendar.texi (Calendar/Diary, Diary Commands) - (Special Diary Entries, Importing Diary): Change some xrefs to - point to emacs-xtra rather than elisp. - - * emacs-xtra.texi (Calendar Customizing): - Move view-diary-entries-initially, view-calendar-holidays-initially, - mark-diary-entries-in-calendar, mark-holidays-in-calendar to main - Emacs Manual. - (Appt Customizing): Merge entire section into main Emacs Manual. - * calendar.texi (Holidays): Move view-calendar-holidays-initially, - mark-holidays-in-calendar here from emacs-xtra. - (Displaying the Diary): Move view-diary-entries-initially, - mark-diary-entries-in-calendar here from emacs-xtra. - (Appointments): Move appt-display-mode-line, - appt-display-duration, appt-disp-window-function, - appt-delete-window-function here from emacs-xtra. - - * calendar.texi: Update and reformat copyright. - Change all @xrefs to the non-printing emacs-xtra to @inforefs. - (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. - (Diary): Refer to `diary-file' rather than ~/diary. - (Diary Commands): Rename node to "Displaying the Diary". - * emacs.texi (Top): Rename "Diary Commands" section. - * misc.texi (Hardcopy): Rename "Diary Commands" xref. - -2005-03-26 Eli Zaretskii - - * misc.texi (Emacs Server): Fix the command for setting - server-name. Add an xref to Invoking emacsclient. - - * help.texi (Help Summary): Clarify when "C-h ." will do something - nontrivial. - (Apropos): Add cindex entry for apropos-sort-by-scores. - - * display.texi (Text Display): Add index entries for how no-break - characters are displayed. - -2005-03-26 Eli Zaretskii - - * files.texi (Visiting): Fix cross-references introduced with the - last change. - - * xresources.texi (GTK resources): Fix last change. - -2005-03-25 Chong Yidong - - * xresources.texi (X Resources): GTK options documented too. - (Resources): Clarify meaning of program name. - (Table of Resources): Add visualClass. - (GTK resources): Rewrite. - (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. - - * display.texi (Text Display): Mention non-breaking spaces. - - * files.texi (Reverting): Document auto-revert-check-vc-info. - - * frames.texi (Mouse Commands): Document - x-mouse-click-focus-ignore-position and mouse-drag-copy-region. - - * help.texi (Help Summary): Add `C-h .'. - (Apropos): Apropos accepts a list of search terms. - Document apropos-sort-by-scores. - (Help Echo): Document display-local-help. - - * misc.texi (Emacs Server): Document server-name. - (Invoking emacsclient): Document -s option for server names. - - * text.texi (Outline Visibility): Introduce "current heading - line" (commands can be called with point on a body line). - Re-order table to follow the sequence of discussion. - hide-body won't hide lines before first header line. - (TeX Mode): Add DocTeX mode. - -2005-03-24 Richard M. Stallman - - * mule.texi (Single-Byte Character Support): Delete mention - of iso-acc.el and iso-transl.el. - -2005-03-23 Lute Kamstra - - * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. - -2005-03-23 Richard M. Stallman - - * search.texi: Delete explicit node pointers. - (Incremental Search): New menu. - (Basic Isearch, Repeat Isearch, Error in Isearch) - (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) - (Slow Isearch): New subnodes. - (Configuring Scrolling): Node deleted. - (Search Case): Doc default-case-fold-search. - (Regexp Replace): Move replace-regexp doc here. - - * rmail.texi (Movemail): Put commas inside closequotes. - - * picture.texi (Insert in Picture): Document C-c arrow combos. - (Basic Picture): Clarify erasure. - - * display.texi (Font Lock): Put commas inside closequotes. - - * cmdargs.texi (General Variables): Put commas inside closequotes. - -2005-03-23 Nick Roberts - - * building.texi (Stack Buffer): Mention reverse contrast for - *selected* frame (might not be current frame). - -2005-03-21 Richard M. Stallman - - * building.texi (Starting GUD): Add bashdb. - -2005-03-20 Chong Yidong - - * basic.texi (Moving Point): Add M-g M-g binding. - (Undo): Document undo-only. - (Position Info): Document M-g M-g and C-u M-g M-g. - - * building.texi (Building): Put Grep Searching after Compilation - Shell. - (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. - Document next-error-highlight. - (Grep Searching): Document grep-highlight-matches. - (Lisp Eval): Typing C-x C-e twice prints integers specially. - - * calendar.texi (Importing Diary): Rename node from iCalendar. - Document diary-from-outlook. - - * dired.texi (Misc Dired Features): Rename node from Misc Dired - Commands. - Mention effect of X drag and drop on Dired buffers. - - * files.texi (Visiting): Document large-file-warning-threshold. - Move paragraph on file-selection dialog. - Mention visiting files using X drag and drop. - (Reverting): Mention using Auto-Revert mode to tail files. - Document auto-revert-tail-mode. - (Version Systems): Minor correction. - (Comparing Files): Diff-mode is no longer based on Compilation - mode. - Document compare-ignore-whitespace. - (Misc File Ops): Explain passing a directory to rename-file. - Likewise for copy-file and make-symbolic-link. - - * frames.texi (Wheeled Mice): Mouse wheel support on by default. - Document mouse-wheel-progressive speed. - - * help.texi (Misc Help): Document numeric argument for C-h i. - Correctly explain the effect of just C-u as argument. - - * killing.texi (Deletion): Document numeric argument for - just-one-space. - - * mini.texi (Completion): Completion acts on text before point. - - * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. - (Emulation): CUA mode replaces pc-bindings-mode, - pc-selection-mode, and s-region. - - * mule.texi (Input Methods): Leim is now built-in. - (Select Input Method): Document quail-show-key. - (Specify Coding): Document revert-buffer-with-coding-system. - - * programs.texi (Fortran Motion): Document f90-next-statement, - f90-previous-statement, f90-next-block, f90-previous-block, - f90-end-of-block, and f90-beginning-of-block. - - * text.texi (Format Faces): Replace old M-g key prefix with M-o. - - * emacs.texi (Acknowledgments): Updated. - - * anti.texi: Total rewrite. - -2005-03-19 Chong Yidong - - * ack.texi (Acknowledgments): Update. - -2005-03-19 Eli Zaretskii - - * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update - copyright years. - -2005-03-14 Nick Roberts - - * building.texi (Commands of GUD): Move paragraph on setting - breakpoints with mouse to the GDB Graphical Interface node. - -2005-03-07 Richard M. Stallman - - * misc.texi (Single Shell, Shell Options): Fix previous change. - - * building.texi (Debugger Operation): Update GUD tooltip enable info. - -2005-03-06 Richard M. Stallman - - * building.texi (Starting GUD): Don't explain text vs graphical - GDB here. Just mention it and xref. - Delete "just one debugger process". - (Debugger Operation): Move GUD tooltip info here. - (GUD Tooltips): Node deleted. - (GDB Graphical Interface): Explain the two GDB modes here. - - * sending.texi (Sending Mail): Minor cleanup. - (Mail Aliases): Explain quoting conventions. - Update key rebinding example. - (Header Editing): C-M-i is like M-TAB. - (Mail Mode Misc): mail-attach-file does not do MIME. - - * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes - that really belongs here. - (Remote Mailboxes): Text moved to Rmail Inbox. - (Rmail Display): Mention Mouse-1. - (Movemail): Clarify two movemail versions. - Clarify rmail-movemail-program. - - * misc.texi (Single Shell): Replace uudecode example with gpg example. - Document async shell commands. - (Shell History): Clarify. - (Shell Ring): Mention C-UP an C-DOWN. - (Shell Options): Add comint-prompt-read-only. - (Invoking emacsclient): Set EDITOR to run Emacs. - (Sorting): No need to explain what region is. - (Saving Emacs Sessions): Fix typo. - (Recursive Edit): Fix punctuation. - (Emulation): Don't mention "PC bindings" which are standard. - (Hyperlinking): Explain Mouse-1 convention here. - (Find Func): Node deleted. - - * help.texi (Name Help): Xref to Hyperlinking. - - * glossary.texi (Glossary): - Rename "Balance Parentheses" to "Balancing...". - Add "Byte Compilation". Correct "Copyleft". - New xref in "Customization". - Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". - Add "Graphical Terminal" "Keybinding", "Margin", "Window System". - Rename "Registers" to "Register". - Replace "Selecting" with "Selected Frame", - "Selected Window", and "Selecting a Buffer". - - * files.texi (Types of Log File): Explain how projects' - methods can vary. - - * display.texi (Faces): Delete "Emacs 21". - - * custom.texi (Changing a Variable): C-M-i like M-TAB. - * fixit.texi (Spelling): C-M-i like M-TAB. - * mini.texi (Completion Options): C-M-i like M-TAB. - * programs.texi (Symbol Completion): C-M-i like M-TAB. - * text.texi (Text Mode): C-M-i like M-TAB. - - * commands.texi (Keys): Mention F1 and F2 in list of prefixes. - - * calendar.texi (Specified Dates): Mention `g w'. - (Appointments): appt-activate toggles with no arg. - -2005-03-05 Juri Linkov - - * cmdargs.texi (Emacs Invocation): Add cindex - "invocation (command line arguments)" - (Misc X): Add -nbc, --no-blinking-cursor. - -2005-03-04 Ulf Jasper - - * calendar.texi (iCalendar): No need to require it now. - -2005-03-03 Nick Roberts - - * trouble.texi (Contributing): Mention Savannah. Direct users to - emacs-devel. - -2005-03-01 Glenn Morris - - * calendar.texi (Adding to Diary): Mention redrawing of calendar - window. - -2005-02-27 Richard M. Stallman - - * building.texi (Compilation): Update mode line status info. - -2005-02-27 Matt Hodges - - * calendar.texi (General Calendar): Document binding of - scroll-other-window-down. - (Mayan Calendar): Fix earliest date. - (Time Intervals): Document timeclock-change. - Fix timeclock-ask-before-exiting documentation. - -2005-02-26 Kim F. Storm - - * frames.texi (Mouse References): - Add mouse-1-click-in-non-selected-windows. - -2005-02-25 Richard M. Stallman - - * screen.texi (Screen): Explain better about cursors and mode lines; - don't presuppose text terminals. - (Point): Don't assume just one cursor. - Clarify explanation of cursors. - (Echo Area, Menu Bar): Cleanups. - - * mini.texi (Minibuffer): Prompts are highlighted. - (Minibuffer Edit): Newline = C-j only on text terminals. - Clarify resize-mini-windows values. - Mention M-PAGEUP and M-PAGEDOWN. - (Completion Commands): Mouse-1 like Mouse-2. - (Minibuffer History): Explain history commands better. - (Repetition): Add xref to Incremental Search. - - * mark.texi (Setting Mark): Clarify info about displaying mark. - Clarify explanation of C-@ and C-SPC. - (Transient Mark): Mention Delete Selection mode. - (Marking Objects): Clean up text about extending the region. - - * m-x.texi (M-x): One C-g doesn't always go to top level. - No delay before suggest-key-bindings output. - - * fixit.texi (Fixit): Mention C-/ for undo. - (Spelling): Mention ESC TAB like M-TAB. - Replacement words with r and R are rechecked. - Say where C-g leaves point. Mention ? as input. - -2005-02-23 Lute Kamstra - - * cmdargs.texi (Initial Options): Add cross reference. - -2005-02-16 Luc Teirlinck - - * emacs.texi (Top): Update menu for splitting of node in - msdog.texi. - * frames.texi (Frames): Update xref for splitting of node in - msdog.texi. - * trouble.texi (Quitting): Ditto. - -2005-02-16 Richard M. Stallman - - * windows.texi (Split Window): Simplify line truncation info - and xref to Display Custom. - - * trouble.texi (Quitting): Emergency escape only for text terminal. - (Screen Garbled): C-l for ungarbling is only for text terminal. - - * text.texi (Text Mode): ESC TAB alternative for M-TAB. - - * sending.texi (Header Editing): ESC TAB alternative for M-TAB. - - * programs.texi (Program Modes): Mention Python mode. - (Moving by Defuns): Repeating C-M-h extends region. - (Basic Indent): Clarify. - (Custom C Indent): Clarify. - (Expressions): Repeating C-M-@ extends region. - (Info Lookup): Clarify for C-h S. - (Symbol Completion): ESC TAB alternative for M-TAB. - (Electric C): Clarify. - - * emacs.texi (Top): Update display.texi and frames.texi submenu data. - - * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from - MS-DOS Input node. - (MS-DOS Keyboard): Start with explaining DEL and BREAK. - (MS-DOS and MULE): Clarify. - (MS-DOS Processes, Windows Processes): Fix typos. - - * major.texi (Choosing Modes): Clarify. - - * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. - (Keyboard Macro Step-Edit): Clarify. - - * indent.texi (Indentation): Clarifications. - - * help.texi (Help): Correct error about C-h in query-replace. - Clarify apropos vs C-h a. Fix how to search in FAQ. - (Key Help): Describe C-h w here. - (Name Help): Minor cleanup. C-h w moved to Key Help. - Clarify the "object" joke. - (Apropos): Clarify. Mouse-1 like Mouse-2. - (Help Mode): Mouse-1 like Mouse-2. - - * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. - - * display.texi (Display): Reorder menu. - (Faces): Cleanup. - (Font Lock): Cleanup. Mention Options menu. - Delete obsolete text. - (Scrolling): For C-l, don't presume text terminal. - (Horizontal Scrolling): Simplify intro. - (Follow Mode): Clarify. - (Cursor Display): Moved before Display Custom. - (Display Custom): Explain no-redraw-on-reenter is for text terminals. - Doc default-tab-width. Doc line truncation more thoroughly. - - * dired.texi (Dired Enter): C-x C-f can run Dired. - (Dired Visiting): Comment out `a' command. - Mouse-1 is like Mouse-2. - (Shell Commands in Dired): ? can be used more than once. - - * basic.texi (Continuation Lines): Simplify description of truncation, - and refer to Display Custom for the rest of it. - -2005-02-06 Lute Kamstra - - * basic.texi (Undo): Fix typo. - - * cmdargs.texi (Emacs Invocation): Fix typo. - - * custom.texi (Init Examples): Fix typo. - - * abbrevs.texi (Expanding Abbrevs): Fix typo. - -2005-02-06 Richard M. Stallman - - * regs.texi (Registers): Registers can hold numbers, too. - - * killing.texi (Other Kill Commands): Cleanup. - Delete redundant explanation of kill in read-only buffer. - (Yanking): Mention term "copying". - (Accumulating Text): Fix typo. - - * entering.texi (Entering Emacs): Update rationale at start. - (Exiting): Treat iconifying on a par with suspension. - - * custom.texi (Minor Modes): Fix typo. - (Easy Customization): Fix menu style. - (Variables): Add xref. - (Examining): Setting for future sessions works through .emacs. - (Keymaps): "Text terminals", not "Many". - (Init Rebinding): Explain \C-. Show example of \M-. - Fix minor wording errors. - (Function Keys): Explain vector syntax just once. - (Named ASCII Chars): Clarify history of TAB/C-i connection. - (Init File): Mention .emacs.d directory. - (Init Examples): Add xref. - (Find Init): Mention .emacs.d directory. - - * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. - (Action Arguments): Explain which kinds of -l args are found how. - (Initial Options): --batch does not inhibit site-start. - Add xrefs. - (Command Example): Use --batch, not -batch. - - * basic.texi (Inserting Text): Cleanup wording. - (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. - C-n is not error at end of buffer. - (Undo): Doc C-/ like C-_. Add xrefs. - (Arguments): META key may be labeled ALT. - Peculiar arg meanings are explained in doc strings. - - * abbrevs.texi (Expanding Abbrevs): Clarify. - -2005-02-05 Eli Zaretskii - - * frames.texi (Frame Parameters): Add an xref to the description - of list-colors-display. Add a pointer to the X docs about colors. - - * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. - Improve docs of list-colors-display. - -2005-02-03 Lute Kamstra - - * frames.texi (Frames, Drag and Drop): Fix typos. - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Window): Mention color-change in mode line. - (Change Window): Explain dragging vertical boundaries. - - * text.texi (Sentences): Clarify. - (Paragraphs): Explain M-a and blank lines. - (Outline Mode): Clarify text and menu. - (Hard and Soft Newlines): Mention use-hard-newlines. - - * frames.texi (Frames): Delete unnecessary mention of Windows. - (Mouse Commands): Likewise. Mention xterm mouse support. - (Clipboard): Clarify. - (Mouse References): Mention use of Mouse-1 for following links. - (Menu Mouse Clicks): Clarify. - (Mode Line Mouse): Clarify. - (Drag and Drop): Rewrite. - - * fixit.texi (Spelling): Fix typo. - - * files.texi (File Names): Clarify. - (Visiting): Update conditions for use of file dialog. Clarify. - (Saving): Doc d as answer in save-some-buffers. - (Remote Files): Clean up the text. - - * dired.texi (Misc Dired Commands): Delete dired-marked-files. - - * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. - (List Buffers): Clarify. - (Several Buffers): Doc T command. - (Buffer Convenience): Clarify menu. - - * basic.texi (Undo): Clarify last change. - -2005-02-02 Matt Hodges - - * fixit.texi (Spelling): Fix typo. - -2005-02-01 Luc Teirlinck - - * basic.texi (Undo): Update description of `undo-outer-limit'. - -2005-02-01 Nick Roberts - - * building.texi: Update documentation relating to GDB Graphical - Interface. - -2005-01-30 Luc Teirlinck - - * custom.texi (Easy Customization): Adapt menu to node name change. - -2005-01-30 Richard M. Stallman - - * custom.texi (Easy Customization): Defn of "User Option" now - includes faces. Don't say just "option" when talking about variables. - Do say just "options" to mean "anything customizable". - (Specific Customization): Describe `customize-variable', - not `customize-option'. - - * glossary.texi (Glossary) : Add xref. - : Change definition--include faces. Change xref. - - * picture.texi (Picture): Mention artist.el. - - * sending.texi, screen.texi, programs.texi, misc.texi: - * mini.texi, major.texi, maintaining.texi, macos.texi: - * help.texi, frames.texi, files.texi: - Don't say just "option" when talking about variables. - - * display.texi, mule.texi: Don't say just "option" when talking - about variables. Other minor cleanups. - -2005-01-26 Lute Kamstra - - * cmdargs.texi (Initial Options): Add a cross reference to `Init - File'. Mention the `-Q' option at the `--no-site-file' option. - -2005-01-22 David Kastrup - - * building.texi (Grep Searching): Mention alias `find-grep' for - `grep-find'. - -2005-01-20 Richard M. Stallman - - * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. - -2005-01-15 Sergey Poznyakoff - - * rmail.texi (Movemail): Explain differences - between standard and mailutils versions of movemail. - Describe command line and configuration options introduced - with the latter. - Explain the notion of mailbox URL, provide examples and - cross-references to mailutils documentation. - Describe various methods of specifying mailbox names, - user names and user passwords for rmail. - (Remote Mailboxes): New section. Describe - how movemail handles remote mailboxes. Describe configuration - options used to control its behavior. - (Other Mailbox Formats): Explain handling of various mailbox - formats. - -2005-01-13 Richard M. Stallman - - * commands.texi (Commands): Clarification. - -2005-01-11 Richard M. Stallman - - * programs.texi (Multi-line Indent): Fix previous change. - (Fortran Autofill): Simplify description of fortran-auto-fill-mode. - -2005-01-08 Richard M. Stallman - - * display.texi (Faces): isearch-lazy-highlight-face renamed to - lazy-highlight. - - * search.texi (Query Replace): Mention faces query-replace - and lazy-highlight. - (Incremental Search): Update isearch highlighting info. - -2005-01-04 Richard M. Stallman - - * custom.texi (Saving Customizations): Minor improvement. - -2005-01-03 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs no longer loads - `custom-file' after .emacs. No longer mention customizing through - Custom. - -2005-01-01 Andreas Schwab - - * killing.texi (Graphical Kill): Move up under node Killing, - change @section to @subsection. - -2005-01-01 Richard M. Stallman - - * custom.texi (Face Customization): Mention hex color specs. - - * emacs.texi (Top): Update Killing submenu. - - * killing.texi (Killing): Reorganize section. - No more TeX-only text; put the node command at start of chapter. - But the first section heading is used only in TeX. - Rewrite the text to read better in this mode. - (Graphical Kill): New subnode gets some of the text that - used to be in the first section. - -2004-12-31 Richard M. Stallman - - * dired.texi (Shell Commands in Dired): Delete the ? example. - - * display.texi (Scrolling): Correct scroll-preserve-screen-position. - - * files.texi (Saving): Describe new require-final-newline features - and mode-require-final-newline. - -2004-12-29 Richard M. Stallman - - * custom.texi (File Variables): Clarify previous change. - -2004-12-27 Jan Djärv - - * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is - out now. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * basic.texi (Moving Point): C-e now runs move-end-of-line. - (Undo): Doc undo-outer-limit. - -2004-12-15 Juri Linkov - - * mark.texi (Transient Mark, Mark Ring): M-< and other - movement commands don't set mark in Transient Mark mode - if mark is active. - -2004-12-12 Juri Linkov - - * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, - C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. - - * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. - (Misc Dired Commands): Add @r{(Dired)} to w. - -2004-12-12 Juri Linkov - - * mark.texi (Marking Objects): Marking commands also extend the - region when mark is active in Transient Mark mode. - -2004-12-08 Luc Teirlinck - - * custom.texi (Saving Customizations): Emacs only loads the custom - file automatically after the init file in version 22.1 or later. - Adapt text and examples to this fact. - -2004-12-07 Luc Teirlinck - - * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to - be set through Custom. Otherwise, it has no effect. - -2004-12-05 Richard M. Stallman - - * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: - * entering.texi: Rename Command Line to Emacs Invocation. - - * misc.texi (Term Mode): Correctly describe C-c. - - * custom.texi (Easy Customization): Move up to section level, - before Variables. Avoid using the term "variable"; say "option". - New initial explanation. - (Variables): In initial explanation, connect "variable" to the - already-explained "user option". - - * emacs.texi (Top): Fix ref to Command Line. - Move reference to Easy Customization. - - * xresources.texi (X Resources): Fix From link. - - * doclicense.texi (GNU Free Documentation License): Fix To link. - - * entering.texi (Entering Emacs): Fix xref, now to Command Line. - - * cmdargs.texi (Command Line): Node renamed from Command Arguments. - -2004-12-03 Richard M. Stallman - - * cmdargs.texi (Initial Options): Clarify batch mode i/o. - -2004-12-01 Luc Teirlinck - - * kmacro.texi: Several small changes in addition to the following. - (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when - defining a keyboard macro. - Mention `kmacro-ring-max'. - (Keyboard Macro Counter): Clarify description of - `kmacro-insert-counter', `kmacro-set-counter', - `kmacro-add-counter' and `kmacro-set-format'. - -2004-11-29 Reiner Steib - - * custom.texi (File Variables): Add `unibyte' and make it more - clear that `unibyte' and `coding' are special. Suggested by Simon - Krahnke . - - * mule.texi (Enabling Multibyte): Refer to File Variables. - Suggested by Simon Krahnke . - -2004-11-26 Jan Djärv - - * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to - x-use-old-gtk-file-dialog. - -2004-11-20 Richard M. Stallman - - * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. - -2004-11-09 Lars Brinkhoff - - * building.texi (Lisp Eval): Delete hyphen in section name. - -2004-11-19 Thien-Thi Nguyen - - * files.texi (Old Versions): - No longer document annotation as "CVS only". - -2004-11-10 Andre Spiegel - - * files.texi (Version Control): Rewrite the introduction about - version systems, mentioning the new ones that we support. Thanks - to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for - suggestions. - -2004-11-03 Jan Djärv - - * frames.texi (Dialog Boxes): Replace non-nil with non-@code{nil}. - -2004-11-02 Jan Djärv - - * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. - -2004-10-23 Eli Zaretskii - - * text.texi (Text Based Tables, Table Definition) - (Table Creation, Table Recognition, Cell Commands) - (Cell Justification, Row Commands, Column Commands) - (Fixed Width Mode, Table Conversion, Measuring Tables) - (Table Misc): New nodes, documenting the Table Mode. - -2004-10-19 Jason Rumney - - * makefile.w32-in (info): Change order of arguments to makeinfo. - -2004-10-19 Ulf Jasper - - * calendar.texi (iCalendar): Update for package changes. - -2004-10-09 Luc Teirlinck - - * files.texi (Misc File Ops): View mode is a minor mode. - -2004-10-08 Glenn Morris - - * calendar.texi (iCalendar): Style changes. - -2004-10-07 Luc Teirlinck - - * search.texi (Regexps): The regexp described in the example is no - longer stored in the variable `sentence-end'. - -2004-10-06 Nick Roberts - - * building.texi (Starting GUD): Note that multiple debugging - sessions requires `gdb --fullname'. - -2004-10-05 Ulf Jasper - - * calendar.texi (iCalendar): New section for a new package. - -2004-10-05 Luc Teirlinck - - * text.texi: Various small changes in addition to the following. - (Text): Replace xref for autotype with inforef. - (Sentences): Explain nil value for `sentence-end'. - (Paragraphs): Update default values for `paragraph-start' and - `paragraph-separate'. - (Text Mode): Correct description of Text mode's effect on the - syntax table. - (Outline Visibility): `hide-other' does not hide top level headings. - `selective-display-ellipses' no longer has an effect on Outline mode. - (TeX Misc): Add missing @cindex. - Replace xref for RefTeX with inforef. - (Requesting Formatted Text): The variable - `enriched-fill-after-visiting' no longer exists. - (Editing Format Info): Update names of menu items and commands. - (Format Faces): Mention special effect of specifying the default face. - Describe inheritance of text properties. - Correct description of `fixed' face. - (Format Indentation): Correct description of effect of setting - margins. Mention `set-left-margin' and `set-right-margin'. - (Format Justification): Update names of menu items. - `set-justification-full' is now bound to `M-j b'. - Mention that `default-justification' is a per buffer variable. - (Format Properties): Update name of menu item. - (Forcing Enriched Mode): `format-decode-buffer' automatically - turns on Enriched mode if the buffer is in text/enriched format. - -2004-10-05 Emilio C. Lopes - - * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. - -2004-09-28 Kim F. Storm - - * display.texi (Display Custom) : - Align with new functionality. - -2004-09-22 Luc Teirlinck - - * display.texi (Display Custom): Remove stray `@end defvar'. - -2004-09-23 Kim F. Storm - - * display.texi (Display Custom): Add `overflow-newline-into-fringe', - `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. - -2004-09-20 Richard M. Stallman - - * custom.texi (Hooks): Explain using setq to clear out a hook. - (File Variables): Explain multiline string constants. - (Non-ASCII Rebinding): Explain when you need to update - non-ASCII char codes in .emacs. - - * building.texi (Compilation): Explain how to make a silent - subprocess that won't be terminated. Explain compilation-environment. - -2004-09-13 Kim F. Storm - - * mini.texi (Repetition): Rename isearch-resume-enabled to - isearch-resume-in-command-history and change default to disabled. - -2004-09-09 Kim F. Storm - - * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' - with new `kmacro-name-last-macro'. - -2004-09-08 Juri Linkov - - * mini.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-03 Juri Linkov - - * search.texi (Incremental Search): Update wording for M-%. - -2004-09-02 Luc Teirlinck - - * killing.texi (Killing): Correct description of kill commands in - read-only buffer. - -2004-09-02 Teodor Zlatanov - - * building.texi (Compilation Mode): Add a paragraph about rules - for finding the compilation buffer for `next-error'. - - * search.texi (Other Repeating Search): Mention that Occur mode - supports the next-error functionality. - -2004-09-02 Juri Linkov - - * search.texi (Regexp Replace): Add missing backslash to \footnote. - -2004-08-31 Luc Teirlinck - - * kmacro.texi (Basic Keyboard Macro): - `apply-macro-to-region-lines' now operates on all lines that begin - in the region, rather than on all complete lines in the region. - -2004-08-31 Jan Djärv - - * frames.texi (Drag and drop): Add documentation about - x-dnd-test-function and x-dnd-known-types. - -2004-08-30 Luc Teirlinck - - * indent.texi: Various minor changes in addition to: - (Indentation Commands): Correct description of `indent-relative'. - (Tab Stops): is no longer bound to `tab-to-tab-stop' in Text - mode. The *Tab Stops* buffer uses Overwrite Mode. - (Just Spaces): `tabify' converts sequences of at least two spaces - to tabs. - -2004-08-27 Luc Teirlinck - - * frames.texi (Secondary Selection): Setting the secondary - selection with M-Drag-Mouse-1 does not alter the kill ring, - setting it with M-Mouse-1 and M-Mouse-3 does. - (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for - toolkit scroll bars. - (Scroll Bars): Ditto. - - * windows.texi (Basic Window): When using a window system, the value - of point in a non-selected window is indicated by a hollow box. - (Split Window): Side by side windows are separated by a scroll bar, - if scroll bars are used. - C-Mouse-2 on scroll bar now also works for toolkit scroll bars. - (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. - (Window Convenience): Update bindings for `winner-undo' and - `winner-redo'. - - * ack.texi (Acknowledgments): Use `@unnumbered'. - * misc.texi: Adapt sectioning in Info to the node structure. - (Invoking emacsclient): Make "Invoking emacsclient" a subsection - of "Using Emacs as a Server". - * building.texi (Building): Interchange nodes (for correct numbering). - * programs.texi (Programs): Interchange nodes (for correct numbering). - * killing.texi, entering.texi, commands.texi: Adapt sectioning in - Info to the node structure. - * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. - Rearrange order of nodes and sections such that both "GNU GENERAL - PUBLIC LICENSE" and "GNU Free Documentation License" appear at the - end, as appropriate for appendices. - (Acknowledgments): Put inside @iftex instead of @ifnotinfo. - Use `@unnumberedsec'. - * trouble.texi: Adapt sectioning in Info to the node structure. - Adapt node pointers to change in emacs.texi. - * cmdargs.texi, doclicense.texi: Adapt node pointers. - -2004-08-25 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): Fix and simplify the - description for unibyte mode. - -2004-08-23 Luc Teirlinck - - * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. - - * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. - (Configuring Scrolling): Correct invalid (for hardcopy) @xref. - (Regexp Replace): Standardize reference to hardcopy Elisp Manual - in @pxref. - -2004-08-22 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): - Change section names. - -2004-08-21 Luc Teirlinck - - * kmacro.texi (Keyboard Macro Ring): Rename section. - Emacs treats the head of the macro ring as the `last keyboard macro'. - (Keyboard Macro Counter): Minor change. - (Save Keyboard Macro): Some clarifications. - (Edit Keyboard Macro): Rename section. - - * buffers.texi (Buffers): Maximum buffer size is now 256M on - 32-bit machines. - (Several Buffers): Clarify which buffer is selected if `2' is - pressed in the Buffer Menu. - Auto Revert mode can be used to update the Buffer Menu - automatically. - -2004-08-21 Eli Zaretskii - - * help.texi (Misc Help): Add an index entry for finding an Info - manual by its file name. - -2004-08-20 Luc Teirlinck - - * files.texi (Backup Deletion): Correct description of - `delete-old-versions'. - (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. - (Auto Save Files): Recommend `auto-save-mode' to reenable - auto-saving, rather than the abbreviation `auto-save'. - -2004-08-17 Luc Teirlinck - - * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms - for "killing" and "yanking" in main menu. - -2004-08-16 Richard M. Stallman - - * killing.texi (Yanking, Killing): Minor cleanups. - - * mark.texi (Momentary Mark): Minor cleanups. - -2004-08-15 Kenichi Handa - - * custom.texi (Non-ASCII Rebinding): - C-q always inserts the right code to pass to global-set-key. - -2004-08-13 Luc Teirlinck - - * regs.texi (RegNumbers): Mention `C-x r i' binding for - `insert-register', instead of `C-x r g' binding, for consistency. - -2004-08-12 Luc Teirlinck - - * fixit.texi (Spelling): Fix typo. - -2004-08-11 Luc Teirlinck - - * help.texi (Help): Fix Texinfo usage. - -2004-07-24 Richard M. Stallman - - * text.texi (Paragraphs): Update how paragraphs are separated - and the default for paragraph-separate. - - * search.texi (Regexp Replace): Further update text for new - replacement operators. - -2004-07-18 Luc Teirlinck - - * emacs-xtra.texi (Subdir switches): Dired does not remember the - `R' switch. - - * dired.texi (Dired Updating): `k' only deletes inserted - subdirectories from the Dired buffer if a prefix argument was given. - - * search.texi (Regexps): Delete redundant definition of `symbol' in - description of `\_>'. It already occurs in the description of `\_<'. - -2004-07-01 Juri Linkov - - * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. - (Regexp Search): Add M-r. - -2004-06-30 Luc Teirlinck - - * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. - -2004-06-29 Jesper Harder - - * search.texi, calendar.texi: Markup fixes. - -2004-06-25 Richard M. Stallman - - * search.texi (Regexp Replace): Rewrite description of \# \, and \?. - -2004-06-25 David Kastrup - - * search.texi (Regexp Replace): Some typo corrections and - rearrangement. - -2004-06-24 David Kastrup - - * search.texi (Unconditional Replace): Use replace-string instead - of query-replace in example. - (Regexp Replace): Add explanations for `\,', `\#' and `\?' - sequences. - (Query Replace): Correct explanation of `^' which does not use - the mark stack. - -2004-06-21 Nick Roberts - - * misc.texi (Shell History Copying): Document comint-insert-input. - (Shell Ring): Describe comint-dynamic-list-input-ring here. - -2004-06-20 Jesper Harder - - * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. - * custom.texi (Customization): Do. - * anti.texi (Antinews): Do. - * abbrevs.texi (Defining Abbrevs): Do. - - * programs.texi (Info Lookup): Fix keybinding for - info-lookup-symbol. - -2004-06-16 Juanma Barranquero - - * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): - Add emacs-xtra. - ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. - (clean): Add emacs-xtra and flymake. Remove redundancies. - -2004-06-15 Luc Teirlinck - - * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): - Add emacs-xtra. - * emacs-xtra.texi: New file. - -2004-06-14 Luc Teirlinck - - * dired.texi (Dired Enter): Mention conditions on `ls' switches. - (Dired and Find): Mention differences with ordinary Dired buffers. - -2004-06-13 Richard M. Stallman - - * custom.texi (Init Syntax): Explain about vars that do special - things when set with setq or with Custom. - (Init Examples): Add line-number-mode example. - -2004-06-12 Juri Linkov - - * dired.texi (Operating on Files): Add dired-do-touch. - -2004-06-10 Juri Linkov - - * building.texi (Lisp Eval): Add C-M-x on defface. - -2004-06-08 Luc Teirlinck - - * files.texi (Reverting): Auto-Revert mode and - Global Auto-Revert mode no longer revert remote files. - -2004-05-29 Richard M. Stallman - - * custom.texi (Init File): Two dashes start --no-site-file. - -2004-05-29 Alan Mackenzie - - * programs.texi: Update for CC Mode 5.30 and incidental amendments. - ("AWK"): Is consistently thus spelled throughout. - (AWK, Pike): Document as "C-like modes". - (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. - (M-x man): Supersedes M-x manual-entry. - Add numerous index entries. Correct "ESC a/e" to "M-a/e". - - ("Comments in C"): Delete node; the info is in CC Mode manual. - (c-comment-only-line-offset): Remove description. - - (C-c ., C-c C-c): Describe new C Mode bindings. - - (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) - (@dfn{Style}, c-default-style, comment-column, comment-padding) - (c-up-conditional, c-beginning-of-statement, c-end-of-statement): - Amend definitions. - - (c-beginning-of-defun, c-end-of-defun, c-context-line-break): - Describe functions. - - (c-comment-start-regexp, c-hanging-comment-ender-p) - (c-hanging-comment-starter-p): Remove obsolete definitions. - - * emacs.texi: Remove the menu entry "Comments in C". - -2004-05-27 Luc Teirlinck - - * dired.texi (Dired and Find): `find-ls-option' does not apply to - `M-x locate'. - -2004-05-16 Karl Berry - - * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, - makeinfo --html fails. - * help.texi (Help Summary) [@ifnottex]: Likewise. - -2004-05-13 Nick Roberts - - * building.texi (GDB Graphical Interface): Update and describe - layout first. - -2004-05-04 Jason Rumney - - * makefile.w32-in: Revert last change. - -2004-05-03 Jason Rumney - - * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Juri Linkov - - * fixit.texi (Spelling): Remove file extension from ispell xref. - -2004-04-15 Kim F. Storm - - * cmdargs.texi (Initial Options): Add -Q. - -2004-04-05 Kim F. Storm - - * custom.texi (File Variables): Add safe-local-eval-forms. - -2004-04-02 Luc Teirlinck - - * files.texi (Reverting): Correct description of revert-buffer's - handling of point. - -2004-03-22 Juri Linkov - - * emacs.texi (Top): Add `Misc X'. - - * trouble.texi: Fix help key bindings. - - * glossary.texi: Improve references. - - * help.texi: Sync keywords with finder.el. - - * mini.texi (Completion): Add description for menu items. - - * misc.texi (Browse-URL, FFAP): Add information about keywords. - - * sending.texi (Mail Methods): Fix xref to Message manual. - -2004-03-12 Richard M. Stallman - - * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. - -2004-03-04 Richard M. Stallman - - * search.texi (Regexps): Explain that ^ and $ have their - special meanings only in certain contexts. - - * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. - - * mule.texi (Specify Coding): Doc C-x RET F. - - * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely - for multiple compile and grep buffers. - (Indirect Buffers): Don't recommand clone-indirect-buffer - for multiple compile and grep buffers. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2004-02-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - -2004-02-21 Juri Linkov - - * cmdargs.texi (Action Arguments): Add alias --find-file. Add - --directory, --help, --version. Move text about command-line-args - to Command Arguments. - (Initial Options): Add @cindex for --script. Fix @cindex for -q. - Add --no-desktop. Add alias --no-multibyte, --no-unibyte. - (Window Size X): Join -g and --geometry. Add @cindex. - (Borders X): Fix @cindex for -ib. Add @cindex for -bw. - (Title X): Remove alias -title. - (Misc X): New node. - -2004-02-15 Jan Djärv - - * frames.texi (Drag and drop): Add Motif to list of supported - protocols. - -2004-02-03 Jan Djärv - - * frames.texi (Drag and drop): New section. - -2004-01-24 Richard M. Stallman - - * emacs.texi (Acknowledgments): Renamed from Acknowledgements. - Include it only @ifnotinfo. Patch the preceding and following - node headers to point to each other. - -2004-01-11 Glenn Morris - - * calendar.texi (Appointments): Update section. - -2003-12-29 Kevin Ryde - - * programs.texi (C Modes): Fix the xref. - -2003-12-23 Nick Roberts - - * building.texi (Watch Expressions): Update. - (Commands of GUD): Include use of toolbar + breakpoints set from - fringe/margin. - -2003-12-03 Andre Spiegel - - * files.texi: Say how to disable VC. Suggested by Alan Mackenzie - . - -2003-11-29 Jan Djärv - - * frames.texi (Dialog Boxes): Add use-file-dialog. - -2003-11-22 Martin Stjernholm - - * ack.texi: Note that Alan Mackenzie contributed the AWK support - in CC Mode. - -2003-11-02 Jesper Harder (tiny change) - - * man/ack.texi, man/basic.texi, man/cmdargs.texi: - * man/commands.texi, man/custom.texi, man/display.texi: - * man/emacs.texi, man/files.texi: - * man/frames.texi, man/glossary.texi, man/killing.texi: - * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: - * man/mule.texi, man/rmail.texi, man/search.texi: - * man/sending.texi, man/text.texi, man/trouble.texi: - Replace @sc{ascii} and ASCII with @acronym{ASCII}. - -2003-11-01 Alan Mackenzie - - * search.texi (Scrolling During Incremental Search): Document a - new scrolling facility in isearch mode. - -2003-10-22 Miles Bader - - * Makefile.in (info): Move before $(top_srcdir)/info. - -2003-10-22 Nick Roberts - - * building.texi (Watch Expressions): Update section on data display - to reflect code changes (GDB Graphical Interface). - -2003-10-13 Richard M. Stallman - - * xresources.texi (GTK resources): Clean up previous change. - -2003-10-12 Jan Djärv - - * xresources.texi (GTK resources): Add a note that some themes - disallow customizations. Add scroll theme example. - -2003-09-30 Richard M. Stallman - - * cmdargs.texi (General Variables): Remove MAILRC envvar. - - * misc.texi (Saving Emacs Sessions): Shorten the section, - collapsing back into one node. - -2003-09-30 Lars Hansen - - * misc.texi: Section "Saving Emacs Sessions" rewritten. - -2003-09-29 Jan Djärv - - * xresources.texi (GTK names in Emacs): Correct typo. - -2003-09-24 Luc Teirlinck - - * cmdargs.texi (Font X): Mention new default font. More - fully describe long font names, wildcard patterns and the - problems involved. (Result of discussion on emacs-devel.) - -2003-09-22 Luc Teirlinck - - * emacs.texi (Acknowledgements): Correct typo. - -2003-09-22 Richard M. Stallman - - * dired.texi (Misc Dired Commands): New node. - (Dired Navigation): Add dired-goto-file. - - * files.texi (File Aliases, Misc File Ops): Add @cindex entries. - - * emacs.texi (Acknowledgements): New node, split from Distribution. - - * cmdargs.texi (Action Arguments): -f reads interactive args. - -2003-09-08 Lute Kamstra - - * screen.texi (Mode Line): Say that POS comes before LINE. - Mention `size-indication-mode'. - * display.texi (Optional Mode Line): Document - `size-indication-mode'. - * basic.texi (Position Info): Mention `size-indication-mode'. - -2003-09-07 Luc Teirlinck - - * xresources.texi (Resources): Refer to `editres' man page. - (Lucid Resources): Update defaults. Expand description of - `shadowThickness'. - -2003-09-04 Miles Bader - - * Makefile.in (top_srcdir): New variable. - ($(top_srcdir)/info): New rule. - (info): Depend on it. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * misc.texi (Saving Emacs Sessions): Correct previous change. - -2003-08-19 Luc Teirlinck - - * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. - (Intro): Include kmacro.texi after fixit.texi instead of after - custom.texi. (As suggested by Kim Storm.) - -2003-08-18 Luc Teirlinck - - * fixit.texi (Fixit): Update `Next' pointer. - * files.texi (Files): Update `Previous' pointer. - * kmacro.texi (Keyboard Macros): Remove redundant node and section. - * emacs.texi (Intro): Include kmacro.texi after custom.texi. - (Suggested by Kim Storm.) - * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) - -2003-08-18 Kim F. Storm - - * kmacro.texi: New file describing enhanced keyboard macro - functionality. Replaces old description in custom.texi. - - * custom.texi (Customization): Add xref to Keyboard Macros chapter. - (Keyboard Macros): Move to new kmacro.texi file. - - * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. - -2003-08-17 Edward M. Reingold - - * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. - -2003-08-17 Alex Schroeder - - * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not - required. - -2003-08-05 Richard M. Stallman - - * programs.texi (Lisp Indent): Don't describe - lisp-indent-function property here. Use xref to Lisp Manual. - -2003-08-03 Glenn Morris - - * calendar.texi (Date Formats): Document changed behavior of - abbreviations. - -2003-07-24 Markus Rost - - * buffers.texi (List Buffers): Fix previous change. - -2003-07-13 Markus Rost - - * buffers.texi (List Buffers): Adjust to new format of *Buffer - List*. - -2003-07-07 Luc Teirlinck - - * display.texi (Font Lock): Fix typo. - -2003-07-07 Richard M. Stallman - - * display.texi (Font Lock): Add xref for format info on - font-lock-remove-keywords. - - * building.texi (Compilation): Document what happens with asynch - children of compiler process. - - * help.texi (Library Keywords): Use @multitable. - -2003-06-04 Richard M. Stallman - - * programs.texi (Expressions): Delete C-M-DEL. - - * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. - comint-move-point-for-output renamed from - comint-scroll-to-bottom-on-output. - - * custom.texi (Init Rebinding): Replace previous change with xref. - (Non-ASCII Rebinding): Explain that issue more briefly here. - -2003-05-28 Richard M. Stallman - - * indent.texi (Indentation): Condense, simplify, clarify prev change. - -2003-05-28 Nick Roberts - - * building.texi (GDB Graphical Interface): New node. - (Rewritten somewhat by RMS.) - -2003-05-28 Kai Großjohann - - * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for - non-English letters. Explain how to set coding systems correctly - and how to include the right coding cookie in the file. - -2003-05-22 Kai Großjohann - - * indent.texi (Indentation): Explain the concepts. - (Just Spaces): Explain why preventing tabs for indentation might - be useful. - -2003-04-16 Richard M. Stallman - - * search.texi (Regexps): Ref to Lisp manual for more regexp features. - -2003-02-22 Alex Schroeder - - * cmdargs.texi (General Variables): Document SMTPSERVER. - - * sending.texi: Remove SMTP node. - (Mail Sending): Describe `send-mail-function'. Link to SMTP - library. - -2003-02-22 Alex Schroeder - - * sending.texi (Sending via SMTP): Explain MTA/MUA. - -2003-02-22 Simon Josefsson - - * sending.texi (Mail Methods): Add node about SMTP. - -2003-02-17 Jan Djärv - - * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. - -2003-02-01 Kevin Ryde - - * glossary.texi (Glossary): Correction to cl cross reference. - -2003-01-20 Richard M. Stallman - - * killing.texi (Rectangles): Document C-x c r. - -2003-01-19 Jan Djärv - - * xresources.texi (GTK resources): New node. - (GTK widget names): New node. - (GTK names in Emacs): New node. - (GTK styles): New node. - -2003-01-09 Francesco Potortì - - * maintaining.texi (Create Tags Table): Add reference to the new - `etags --help --lang=LANG' option. - -2002-10-02 Karl Berry - - * emacs.texi: Per rms, update all manuals to use @copying instead of - @ifinfo. Also use @ifnottex instead of @ifinfo around the top node, - where needed for the sake of the HTML output. - -2001-12-20 Eli Zaretskii - - * Makefile.in (EMACSSOURCES): Update the list of Emacs manual - source files. - -2001-11-16 Eli Zaretskii - - * Makefile.in (emacsman): New target. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-05 Gerd Moellmann - - * Branch for 21.1. - -2001-03-05 Gerd Moellmann - - * Makefile.in (mostlyclean, maintainer-clean): Delete more files. - -2000-05-31 Stefan Monnier - - * .cvsignore (*.tmp): New entry. Seems to be used for @macro. - -1999-07-12 Richard Stallman - - * Version 20.4 released. - -1998-12-04 Markus Rost - - * Makefile.in (INFO_TARGETS): Delete customize.info. - (DVI_TARGETS): Delete customize.dvi. - (../info/customize, customize.dvi): Targets deleted. - -1998-08-19 Richard Stallman - - * Version 20.3 released. - -1998-05-06 Richard Stallman - - * Makefile.in (EMACSSOURCES): Add mule.texi. - Add msdog.texi, ack.texi. Remove gnu1.texi. - -1998-04-06 Andreas Schwab - - * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use - it in dvi targets. - -1997-09-23 Paul Eggert - - * Makefile.in: Merge changes mistakenly made to `Makefile'. - (INFO_TARGETS): Change ../info/custom to ../info/customize. - (../info/customize): Rename from ../info/custom. - -1997-09-19 Richard Stallman - - * Version 20.2 released. - -1997-09-15 Richard Stallman - - * Version 20.1 released. - -1997-08-24 Richard Stallman - - * Makefile (../info/customize, customize.dvi): New targets. - (INFO_TARGETS): Add ../info/customize. - (DVI_TARGETS): Add customize.dvi. - -1996-08-11 Richard Stallman - - * Version 19.33 released. - -1996-07-31 Richard Stallman - - * Version 19.32 released. - -1996-06-20 Richard Stallman - - * Makefile.in (All info targets): cd $(srcdir) to do the work. - -1996-06-19 Richard Stallman - - * Makefile.in (All info targets): Specify $(srcdir) in input files. - Specify -I option. - (All dvi targets): Set the TEXINPUTS variable. - -1996-05-25 Karl Heuer - - * Version 19.31 released. - -1995-11-24 Richard Stallman - - * Version 19.30 released. - -1995-02-07 Richard Stallman - - * Makefile.in (maintainer-clean): Rename from realclean. - -1994-11-23 Richard Stallman - - * Makefile.in: New file. - * Makefile: File deleted. - -1994-11-19 Richard Stallman - - * Makefile (TEXINDEX_OBJS): Variable deleted. - (texindex, texindex.o, getopt.o): Rules deleted. - All deps on texindex deleted. - (distclean): Don't delete texindex. - (mostlyclean): Don't delete *.o. - * texindex.c, getopt.c: Files deleted. - -1994-09-07 Richard Stallman - - * Version 19.26 released. - -1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) - - * Makefile (EMACSSOURCES): Exclude undo.texi. - -1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.25 released. - -1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.24 released. - -1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.23 released. - -1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Delete spurious tab. - -1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (.SUFFIXES): New rule. - -1993-12-04 Richard Stallman (rms@srarc2) - - * getopt.c: New file. - * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. - (getopt.o): New rule. - (dvi): Don't depend on texindex. - (emacs.dvi): Depend on texindex. - -1993-12-03 Richard Stallman (rms@srarc2) - - * Makefile (TEXI2DVI): New variable. - (emacs.dvi): Add explicit command. - (TEXINDEX_OBJS): Delete duplicate getopt.o. - -1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.22 released. - -1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (TEXINDEX_OBJS): Delete spurious period. - -1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.21 released. - -1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (realclean): Don't delete the Info files. - -1993-10-25 Brian J. Fox (bfox@albert.gnu.ai.mit.edu) - - * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x - 4' where appropriate. - -1993-10-20 Brian J. Fox (bfox@ai.mit.edu) - - * Makefile: Fix targets for texindex. - - * texindex.c: Include "../src/config.h" if building in emacs. - - * Makefile: Change all files to FILENAME.texi, force all targets - to be FILENAME, not FILENAME.info. - Add target to build texindex.c, defining `emacs'. - -1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.19 released. - -1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.18 released. - -1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile: Fix source file names of the separate manuals. - -1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Version 19.17 released. - -1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * split-man: Fix typos in last change. - -1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.16 released. - -1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * version 19.15 released. - -1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Makefile (distclean): It's rm, not rf. - -1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.14 released. - -1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile: New file. - -1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.13 released. - -1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.9 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Version 19.8 released. - -1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * cmdargs.texi: Document the -i, -itype, and -iconic options. - - * trouble.texi: It's `enable-flow-control-on', not - `evade-flow-control-on'. - -1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * display.texi: Document standard-display-european. - -1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) - - * Version 19.7 released. - - * emacs.texi: Add a sentence to the top menu mentioning the - specific version of Emacs this manual applies to. - -1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * basic.texi: Document next-line-add-lines variable used to - implement down-arrow. - - * killing.texi: Document kill-whole-line. - -1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * text.texi: Update unix TeX ordering information. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * news.texi: Mention fill-rectangle in keybinding list. - - * killing.texi: Document fill-rectangle. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * vc.texi: Bring the docs up to date with VC 5.2. - -1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * emacs.tex: Mention blackbox and gomoku under Amusements. - Assembler mode is now mentioned and appropriately indexed - under Programming Modes. - -1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) - - * emacs.tex: Update TeX ordering information. - -1990-06-26 David Lawrence (tale@geech) - - * emacs.tex: Note that completion-ignored-extensions is not used - to filter out names when all completions are displayed in - *Completions*. - -1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. - -1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) - - * emacs.tex: Add @findex grep. - -1988-08-16 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Correct two typos. No other changes before - Version 19 will be made. - -1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) - - * emacs.tex: Update information for obtaining TeX distribution from the - University of Washington. - -;; Local Variables: -;; coding: utf-8 -;; fill-column: 79 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, - 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . - -;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in deleted file mode 100644 index edb845b3eac..00000000000 --- a/doc/emacs/Makefile.in +++ /dev/null @@ -1,159 +0,0 @@ -#### Makefile for the Emacs Manual - -# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -# 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Where to find the source code. $(srcdir) will be the man -# subdirectory of the source tree. This is -# set by the configure script's `--srcdir' option. -srcdir=@srcdir@ -top_srcdir=@top_srcdir@ - -# Tell make where to find source files; this is needed for the makefiles. -VPATH=@srcdir@ - -## Where the output files go. -## Note that the setfilename command in the .texi files assumes this. -infodir=../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -# The makeinfo program is part of the Texinfo distribution. -# Use --force so that it generates output even if there are errors. -MAKEINFO = makeinfo --force - -INFO_TARGETS = $(infodir)/emacs -DVI_TARGETS = emacs.dvi - - -TEXI2DVI = texi2dvi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - $(TEXI2DVI) $< - -ENVADD = TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)" - - -EMACS_XTRA=\ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - ${srcdir}/emacs.texi \ - ${srcdir}/doclicense.texi \ - ${srcdir}/gpl.texi \ - ${srcdir}/screen.texi \ - ${srcdir}/commands.texi \ - ${srcdir}/entering.texi \ - ${srcdir}/basic.texi \ - ${srcdir}/mini.texi \ - ${srcdir}/m-x.texi \ - ${srcdir}/help.texi \ - ${srcdir}/mark.texi \ - ${srcdir}/killing.texi \ - ${srcdir}/regs.texi \ - ${srcdir}/display.texi \ - ${srcdir}/search.texi \ - ${srcdir}/fixit.texi \ - ${srcdir}/files.texi \ - ${srcdir}/buffers.texi \ - ${srcdir}/windows.texi \ - ${srcdir}/frames.texi \ - ${srcdir}/mule.texi \ - ${srcdir}/major.texi \ - ${srcdir}/indent.texi \ - ${srcdir}/text.texi \ - ${srcdir}/programs.texi \ - ${srcdir}/building.texi \ - ${srcdir}/maintaining.texi \ - ${srcdir}/abbrevs.texi \ - ${srcdir}/sending.texi \ - ${srcdir}/rmail.texi \ - ${srcdir}/dired.texi \ - ${srcdir}/calendar.texi \ - ${srcdir}/misc.texi \ - ${srcdir}/custom.texi \ - ${srcdir}/trouble.texi \ - ${srcdir}/cmdargs.texi \ - ${srcdir}/xresources.texi \ - ${srcdir}/anti.texi \ - ${srcdir}/macos.texi \ - ${srcdir}/msdog.texi \ - ${srcdir}/gnu.texi \ - ${srcdir}/glossary.texi \ - ${srcdir}/ack.texi \ - ${srcdir}/kmacro.texi \ - $(EMACS_XTRA) - -info: $(infodir) $(INFO_TARGETS) - -$(infodir): - mkdir $@ - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -emacs : $(infodir)/emacs - -$(infodir)/emacs: ${EMACSSOURCES} - cd $(srcdir); $(MAKEINFO) emacs.texi - -emacs.dvi: ${EMACSSOURCES} - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi - - -emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi - - -mostlyclean: - rm -f *.log *.cp *.fn *.ky *.op *.ops *.pg *.vr core *.tp *.core - rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -clean: mostlyclean - rm -f *.dvi - -distclean: clean -# rm -f Makefile - -maintainer-clean: distclean - for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. - - -### Makefile ends here diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi deleted file mode 100644 index 0740e067505..00000000000 --- a/doc/emacs/abbrevs.texi +++ /dev/null @@ -1,461 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Abbrevs -@chapter Abbrevs -@cindex abbrevs -@cindex expansion (of abbrevs) - - A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert -it, into some different text. Abbrevs are defined by the user to expand -in specific ways. For example, you might define @samp{foo} as an abbrev -expanding to @samp{find outer otter}. Then you could insert -@samp{find outer otter } into the buffer by typing @kbd{f o o -@key{SPC}}. - - A second kind of abbreviation facility is called @dfn{dynamic abbrev -expansion}. You use dynamic abbrev expansion with an explicit command -to expand the letters in the buffer before point by looking for other -words in the buffer that start with those letters. @xref{Dynamic -Abbrevs}. - - ``Hippie'' expansion generalizes abbreviation expansion. -@xref{Hippie Expand, , Hippie Expansion, autotype, Features for -Automatic Typing}. - -@menu -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. -@end menu - -@node Abbrev Concepts -@section Abbrev Concepts - - An @dfn{abbrev} is a word which has been defined to @dfn{expand} into -a specified @dfn{expansion}. When you insert a word-separator character -following the abbrev, that expands the abbrev---replacing the abbrev -with its expansion. For example, if @samp{foo} is defined as an abbrev -expanding to @samp{find outer otter}, then you can insert @samp{find -outer otter.} into the buffer by typing @kbd{f o o .}. - -@findex abbrev-mode -@vindex abbrev-mode -@cindex Abbrev mode -@cindex mode, Abbrev - Abbrevs expand only when Abbrev mode (a minor mode) is enabled. -Disabling Abbrev mode does not cause abbrev definitions to be forgotten, -but they do not expand until Abbrev mode is enabled again. The command -@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it -turns Abbrev mode on if the argument is positive, off otherwise. -@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is -on when the variable is non-@code{nil}. The variable @code{abbrev-mode} -automatically becomes local to the current buffer when it is set. - - Abbrevs can have @dfn{mode-specific} definitions, active only in one major -mode. Abbrevs can also have @dfn{global} definitions that are active in -all major modes. The same abbrev can have a global definition and various -mode-specific definitions for different major modes. A mode-specific -definition for the current major mode overrides a global definition. - - You can define abbrevs interactively during the editing session. You -can also save lists of abbrev definitions in files for use in later -sessions. Some users keep extensive lists of abbrevs that they load -in every session. - -@node Defining Abbrevs -@section Defining Abbrevs - -@table @kbd -@item C-x a g -Define an abbrev, using one or more words before point as its expansion -(@code{add-global-abbrev}). -@item C-x a l -Similar, but define an abbrev specific to the current major mode -(@code{add-mode-abbrev}). -@item C-x a i g -Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). -@item C-x a i l -Define a word in the buffer as a mode-specific abbrev -(@code{inverse-add-mode-abbrev}). -@item M-x define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as an abbrev expanding into @var{exp}. -@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} -Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. -@item M-x kill-all-abbrevs -Discard all abbrev definitions, leaving a blank slate. -@end table - -@kindex C-x a g -@findex add-global-abbrev - The usual way to define an abbrev is to enter the text you want the -abbrev to expand to, position point after it, and type @kbd{C-x a g} -(@code{add-global-abbrev}). This reads the abbrev itself using the -minibuffer, and then defines it as an abbrev for one or more words before -point. Use a numeric argument to say how many words before point should be -taken as the expansion. For example, to define the abbrev @samp{foo} as -mentioned above, insert the text @samp{find outer otter} and then type -@kbd{C-u 3 C-x a g f o o @key{RET}}. - - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. - -@kindex C-x a l -@findex add-mode-abbrev - The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but -defines a mode-specific abbrev. Mode-specific abbrevs are active only in a -particular major mode. @kbd{C-x a l} defines an abbrev for the major mode -in effect at the time @kbd{C-x a l} is typed. The arguments work the same -as for @kbd{C-x a g}. - -@kindex C-x a i g -@findex inverse-add-global-abbrev -@kindex C-x a i l -@findex inverse-add-mode-abbrev - If the abbrev text itself is already in the buffer, you can use the -commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and -@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an -abbrev by specify the expansion in the minibuffer. These commands are -called ``inverse'' because they invert the meaning of the two text -strings they use (one from the buffer and one read with the -minibuffer). - -@findex define-mode-abbrev -@findex define-global-abbrev - You can define an abbrev without inserting either the abbrev or its -expansion in the buffer using the command @code{define-global-abbrev}. -It reads two arguments---the abbrev, and its expansion. The command -@code{define-mode-abbrev} does likewise for a mode-specific abbrev. - - To change the definition of an abbrev, just define a new definition. -When the abbrev has a prior definition, the abbrev definition commands -ask for confirmation before replacing it. - -@findex kill-all-abbrevs - To remove an abbrev definition, give a negative argument to the -abbrev definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. -The former removes a global definition, while the latter removes a -mode-specific definition. @kbd{M-x kill-all-abbrevs} removes all -abbrev definitions, both global and local. - -@node Expanding Abbrevs -@section Controlling Abbrev Expansion - - When Abbrev mode is enabled, an abbrev expands whenever it is -present in the buffer just before point and you type a self-inserting -whitespace or punctuation character (@key{SPC}, comma, etc.@:). More -precisely, any character that is not a word constituent expands an -abbrev, and any word-constituent character can be part of an abbrev. -The most common way to use an abbrev is to insert it and then insert a -punctuation or whitespace character to expand it. - -@vindex abbrev-all-caps - Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find -outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into -@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the -variable @code{abbrev-all-caps} (setting it non-@code{nil} specifies -@samp{FIND OUTER OTTER}). - - These commands are used to control abbrev expansion: - -@table @kbd -@item M-' -Separate a prefix from a following abbrev to be expanded -(@code{abbrev-prefix-mark}). -@item C-x a e -@findex expand-abbrev -Expand the abbrev before point (@code{expand-abbrev}). -This is effective even when Abbrev mode is not enabled. -@item M-x expand-region-abbrevs -Expand some or all abbrevs found in the region. -@end table - -@kindex M-' -@findex abbrev-prefix-mark - You may wish to expand an abbrev and attach a prefix to the expansion; -for example, if @samp{cnst} expands into @samp{construction}, you might want -to use it to enter @samp{reconstruction}. It does not work to type -@kbd{recnst}, because that is not necessarily a defined abbrev. What -you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in -between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert -@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to -indicate that it has done its work. Then insert the abbrev @samp{cnst}; -the buffer now contains @samp{re-cnst}. Now insert a non-word character -to expand the abbrev @samp{cnst} into @samp{construction}. This -expansion step also deletes the hyphen that indicated @kbd{M-'} had been -used. The result is the desired @samp{reconstruction}. - - If you actually want the text of the abbrev in the buffer, rather than -its expansion, you can accomplish this by inserting the following -punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in -the buffer, not expanding it. - -@findex unexpand-abbrev - If you expand an abbrev by mistake, you can undo the expansion and -bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). -This also undoes the insertion of the non-word character that expanded -the abbrev. If the result you want is the terminating non-word -character plus the unexpanded abbrev, you must reinsert the terminating -character, quoting it with @kbd{C-q}. You can also use the command -@kbd{M-x unexpand-abbrev} to cancel the last expansion without -deleting the terminating character. - -@findex expand-region-abbrevs - @kbd{M-x expand-region-abbrevs} searches through the region for defined -abbrevs, and for each one found offers to replace it with its expansion. -This command is useful if you have typed in text using abbrevs but forgot -to turn on Abbrev mode first. It may also be useful together with a -special set of abbrev definitions for making several global replacements at -once. This command is effective even if Abbrev mode is not enabled. - - Expanding any abbrev runs @code{abbrev-expand-functions}, a special -hook. Functions in this special hook can make arbitrary changes to -the abbrev expansion. @xref{Abbrev Expansion,,, elisp, The Emacs Lisp -Reference Manual}. - -@node Editing Abbrevs -@section Examining and Editing Abbrevs - -@table @kbd -@item M-x list-abbrevs -Display a list of all abbrev definitions. With a numeric argument, list -only local abbrevs. -@item M-x edit-abbrevs -Edit a list of abbrevs; you can add, alter or remove definitions. -@end table - -@findex list-abbrevs - The output from @kbd{M-x list-abbrevs} looks like this: - -@example -@var{various other tables@dots{}} -(lisp-mode-abbrev-table) -"dk" 0 "define-key" -(global-abbrev-table) -"dfn" 0 "definition" -@end example - -@noindent -(Some blank lines of no semantic significance, and some other abbrev -tables, have been omitted.) - - A line containing a name in parentheses is the header for abbrevs in a -particular abbrev table; @code{global-abbrev-table} contains all the global -abbrevs, and the other abbrev tables that are named after major modes -contain the mode-specific abbrevs. - - Within each abbrev table, each nonblank line defines one abbrev. The -word at the beginning of the line is the abbrev. The number that -follows is the number of times the abbrev has been expanded. Emacs -keeps track of this to help you see which abbrevs you actually use, so -that you can eliminate those that you don't use often. The string at -the end of the line is the expansion. - - Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs -(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are -pre-defined by various modes, and are not saved to your abbrev file. -To disable a ``system'' abbrev, define an abbrev of the same name that -expands to itself, and save it to your abbrev file. - -@findex edit-abbrevs -@kindex C-c C-c @r{(Edit Abbrevs)} - @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev -definitions by editing a list of them in an Emacs buffer. The list has -the same format described above. The buffer of abbrevs is called -@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in -this buffer to install the abbrev definitions as specified in the -buffer---and delete any abbrev definitions not listed. - - The command @code{edit-abbrevs} is actually the same as -@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} -whereas @code{list-abbrevs} merely displays it in another window. - -@node Saving Abbrevs -@section Saving Abbrevs - - These commands allow you to keep abbrev definitions between editing -sessions. - -@table @kbd -@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} -Write a file @var{file} describing all defined abbrevs. -@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} -Read the file @var{file} and define abbrevs as specified therein. -@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} -Similar but do not display a message about what is going on. -@item M-x define-abbrevs -Define abbrevs from definitions in current buffer. -@item M-x insert-abbrevs -Insert all abbrevs and their expansions into current buffer. -@end table - -@findex write-abbrev-file - @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and -then writes a description of all current abbrev definitions into that -file. This is used to save abbrev definitions for use in a later -session. The text stored in the file is a series of Lisp expressions -that, when executed, define the same abbrevs that you currently have. - -@findex read-abbrev-file -@findex quietly-read-abbrev-file -@vindex abbrev-file-name -@cindex abbrev file - @kbd{M-x read-abbrev-file} reads a file name using the minibuffer -and then reads the file, defining abbrevs according to the contents of -the file. The function @code{quietly-read-abbrev-file} is similar -except that it does not display a message in the echo area; you cannot -invoke it interactively, and it is used primarily in the @file{.emacs} -file. If either of these functions is called with @code{nil} as the -argument, it uses the file name specified in the variable -@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. -That file is your standard abbrev definition file, and Emacs loads -abbrevs from it automatically when it starts up. (As an exception, -Emacs does not load the abbrev file when it is started in batch mode. -@xref{Initial Options}, for a description of batch mode.) - -@vindex save-abbrevs - Emacs will offer to save abbrevs automatically if you have changed -any of them, whenever it offers to save all files (for @kbd{C-x s} or -@kbd{C-x C-c}). It saves them in the file specified by -@code{abbrev-file-name}. This feature can be inhibited by setting the -variable @code{save-abbrevs} to @code{nil}. - -@findex insert-abbrevs -@findex define-abbrevs - The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are -similar to the previous commands but work on text in an Emacs buffer. -@kbd{M-x insert-abbrevs} inserts text into the current buffer after point, -describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses -the entire current buffer and defines abbrevs accordingly. - -@node Dynamic Abbrevs -@section Dynamic Abbrev Expansion - - The abbrev facility described above operates automatically as you -insert text, but all abbrevs must be defined explicitly. By contrast, -@dfn{dynamic abbrevs} allow the meanings of abbreviations to be -determined automatically from the contents of the buffer, but dynamic -abbrev expansion happens only when you request it explicitly. - -@kindex M-/ -@kindex C-M-/ -@findex dabbrev-expand -@findex dabbrev-completion -@table @kbd -@item M-/ -Expand the word in the buffer before point as a @dfn{dynamic abbrev}, -by searching in the buffer for words starting with that abbreviation -(@code{dabbrev-expand}). - -@item C-M-/ -Complete the word before point as a dynamic abbrev -(@code{dabbrev-completion}). -@end table - -@vindex dabbrev-limit - For example, if the buffer contains @samp{does this follow } and you -type @kbd{f o M-/}, the effect is to insert @samp{follow} because that -is the last word in the buffer that starts with @samp{fo}. A numeric -argument to @kbd{M-/} says to take the second, third, etc.@: distinct -expansion found looking backward from point. Repeating @kbd{M-/} -searches for an alternative expansion by looking farther back. After -scanning all the text before point, it searches the text after point. -The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far -away in the buffer to search for an expansion. - -@vindex dabbrev-check-all-buffers - After scanning the current buffer, @kbd{M-/} normally searches other -buffers, unless you have set @code{dabbrev-check-all-buffers} to -@code{nil}. - -@vindex dabbrev-ignored-buffer-regexps - For finer control over which buffers to scan, customize the variable -@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular -expressions. If a buffer's name matches any of these regular -expressions, dynamic abbrev expansion skips that buffer. - - A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to -search first for expansions after point, then other buffers, and -consider expansions before point only as a last resort. If you repeat -the @kbd{M-/} to look for another expansion, do not specify an -argument. Repeating @kbd{M-/} cycles through all the expansions after -point and then the expansions before point. - - After you have expanded a dynamic abbrev, you can copy additional -words that follow the expansion in its original context. Simply type -@kbd{@key{SPC} M-/} for each additional word you want to copy. The -spacing and punctuation between words is copied along with the words. - - The command @kbd{C-M-/} (@code{dabbrev-completion}) performs -completion of a dynamic abbrev. Instead of trying the possible -expansions one by one, it finds all of them, then inserts the text -that they have in common. If they have nothing in common, @kbd{C-M-/} -displays a list of completions, from which you can select a choice in -the usual manner. @xref{Completion}. - - Dynamic abbrev expansion is completely independent of Abbrev mode; the -expansion of a word with @kbd{M-/} is completely independent of whether -it has a definition as an ordinary abbrev. - -@node Dabbrev Customization -@section Customizing Dynamic Abbreviation - - Normally, dynamic abbrev expansion ignores case when searching for -expansions. That is, the expansion need not agree in case with the word -you are expanding. - -@vindex dabbrev-case-fold-search - This feature is controlled by the variable -@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in -this search; if it is @code{nil}, the word and the expansion must match -in case. If the value of @code{dabbrev-case-fold-search} is -@code{case-fold-search}, which is true by default, then the variable -@code{case-fold-search} controls whether to ignore case while searching -for expansions. - -@vindex dabbrev-case-replace - Normally, dynamic abbrev expansion preserves the case pattern -@emph{of the dynamic abbrev you are expanding}, by converting the -expansion to that case pattern. - -@vindex dabbrev-case-fold-search - The variable @code{dabbrev-case-replace} controls whether to -preserve the case pattern of the dynamic abbrev. If it is @code{t}, -the dynamic abbrev's case pattern is preserved in most cases; if it is -@code{nil}, the expansion is always copied verbatim. If the value of -@code{dabbrev-case-replace} is @code{case-replace}, which is true by -default, then the variable @code{case-replace} controls whether to -copy the expansion verbatim. - - However, if the expansion contains a complex mixed case pattern, and -the dynamic abbrev matches this pattern as far as it goes, then the -expansion is always copied verbatim, regardless of those variables. -Thus, for example, if the buffer contains -@code{variableWithSillyCasePattern}, and you type @kbd{v a M-/}, it -copies the expansion verbatim including its case pattern. - -@vindex dabbrev-abbrev-char-regexp - The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, -controls which characters are considered part of a word, for dynamic expansion -purposes. The regular expression must match just one character, never -two or more. The same regular expression also determines which -characters are part of an expansion. The value @code{nil} has a special -meaning: dynamic abbrevs are made of word characters, but expansions are -made of word and symbol characters. - -@vindex dabbrev-abbrev-skip-leading-regexp - In shell scripts and makefiles, a variable name is sometimes prefixed -with @samp{$} and sometimes not. Major modes for this kind of text can -customize dynamic abbrev expansion to handle optional prefixes by setting -the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value -should be a regular expression that matches the optional prefix that -dynamic abbrev expression should ignore. - -@ignore - arch-tag: 638e0079-9540-48ec-9166-414083e16445 -@end ignore diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi deleted file mode 100644 index 6981774b534..00000000000 --- a/doc/emacs/ack.texi +++ /dev/null @@ -1,1402 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@node Acknowledgments, Screen, Concept Index, Top -@unnumbered Acknowledgments - -Many people have contributed code included in the Free Software -Foundation's distribution of GNU Emacs. To show our appreciation for -their public spirit, we list here in alphabetical order those who have -written substantial portions. Others too numerous to mention have -reported and fixed bugs, and added features to many parts of Emacs. -We thank them for their generosity as well. - -This list is intended to mention every contributor of a major package or -feature we currently distribute; if you know of someone we have omitted, -please report that as a manual bug. More comprehensive information is -available in the @file{ChangeLog} files, summarized in the file -@file{etc/AUTHORS} in the distribution. - -@c We should list here anyone who has contributed a new package, -@c and anyone who has made major enhancements in Emacs -@c that many users would notice and consider important. -@c Remove things that are no longer distributed. -@c Note this file is only used ifnottex; otherwise a shorter version in -@c emacs.texi is used. - -@itemize @bullet -@item -Per Abrahamsen wrote the customization facilities, as well as -@file{double.el}, for typing accented characters not normally available -from the keyboard; @file{xt-mouse.el}, which allows mouse commands -through Xterm; @file{gnus-cus.el}, which implements customization -commands for Gnus; @file{gnus-cite.el}, a citation-parsing facility for -news articles); @file{gnus-score.el}, scoring for Gnus; @file{cpp.el}, -which hides or highlights parts of C programs according to preprocessor -conditionals; and the widget library files @file{wid-browse.el}, -@file{wid-edit.el}, @file{widget.el}. He also co-wrote -@file{gnus-soup.el}. - -@item -Tomas Abrahamsson wrote @file{artist.el}, a package for producing -@acronym{ASCII} art with a mouse or with keyboard keys. - -@item -Jay K.@: Adams wrote @file{jka-compr.el} and @file{jka-cmpr-hook.el}, -providing automatic decompression and recompression for compressed -files. - -@item -Michael Albinus wrote @file{dbus.el}, a package that implements the -D-Bus message bus protocol; @file{zeroconf.el}, a mode for browsing -Avahi services; and @file{xesam.el}, a Xesam-based search engine -interface. He and Kai Gro@ss{}johann wrote the Tramp package, which -provides transparent remote file editing using rcp, ssh, ftp, and -other network protocols. He and Daniel Pittman wrote -@file{tramp-cache.el}. - -@item -Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the -point vertically fixed by scrolling the window when moving up and down -in the buffer. - -@item -Joe Arceneaux wrote the original text property implementation, and -implemented support for X11. - -@item -Miles Bader wrote @file{image-file.el}, support code for visiting image -files; @file{minibuf-eldef.el}, a minor mode that hides the minibuffer -default value when appropriate; @file{rfn-eshadow.el}, shadowing of -@code{read-file-name} input; @file{mb-depth.el}, display of minibuffer -depth; @file{button.el}, the library that implements clickable buttons; -@file{face-remap.el}, a package for changing the default face in -individual buffers; and @file{macroexp.el} for macro-expansion. - -@item -David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by -moving the mouse in particular patterns. - -@item -Eli Barzilay wrote @file{calculator.el}, a desktop calculator for -Emacs. - -@item -Steven L.@: Baur wrote @file{footnote.el} which lets you include -footnotes in email messages; and @file{gnus-audio.el} and -@file{earcon.el}, which provide sound effects for Gnus. He also wrote -@file{gnus-setup.el}. - -@item -Alexander L.@: Belikoff, Sergey Berezin, Sacha Chua, David Edmondson, -Noah Friedman, Andreas Fuchs, Mario Lang, Ben Mesander, Lawrence -Mitchell, Gergely Nagy, Michael Olson, Per Persson, Jorgen Schaefer, -Alex Schroeder, and Tom Tromey wrote ERC, an advanced Internet Relay -Chat client (for more information, see the file @file{CREDITS} in the -ERC distribution). - -@item -Scott Bender, Michael Brouwer, Christophe de Dinechin, Carl Edman, -Christian Limpach and Adrian Robert developed and maintained the -NeXTstep port of Emacs. - -@item -Anna M.@: Bigatti wrote @file{cal-html.el}, which produces HTML calendars. - -@item -Ray Blaak and Simon South wrote @file{delphi.el}, a mode for editing -Delphi (Object Pascal) source code. - -@item -Martin Blais, Stefan Merten, and David Goodger wrote @file{rst.el}, a -mode for editing reStructuredText documents. - -@item -Jim Blandy wrote Emacs 19's input system, brought its configuration and -build process up to the GNU coding standards, and contributed to the -frame support and multi-face support. Jim also wrote @file{tvi970.el}, -terminal support for the TeleVideo 970 terminals; and co-wrote -@file{wyse50.el} (q.v.@:). - -@item -Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs -buffer. - -@item -Terrence M.@: Brannon wrote @file{landmark.el}, a neural-network robot -that learns landmarks. - -@item -Frank Bresz wrote @file{diff.el}, a program to display @code{diff} -output. - -@item -Peter Breton implemented @file{dirtrack.el}, a library for tracking -directory changes in shell buffers; @file{filecache.el}, which records -which directories your files are in; @file{locate.el}, which -interfaces to the @code{locate} command; @file{find-lisp.el}, an Emacs -Lisp emulation of the @command{find} program; @file{net-utils.el}; and -the ``generic mode'' feature. - -@item -Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs; and -@file{ada-prj.el}, editing of Ada mode project files, as well as -co-authoring @file{ada-mode.el} and @file{ada-xref.el}. - -@item -Kevin Broadey wrote @file{foldout.el}, providing folding extensions to -Emacs's outline modes. - -@item -David M.@: Brown wrote @file{array.el}, for editing arrays and other -tabular data. - -@item -W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for -changing the encoding of Polish characters. - -@item -Bill Carpenter provided @file{feedmail.el}, a package for massaging -outgoing mail messages and sending them through various popular mailers. - -@item -Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for -manipulating object collections. Per Cederqvist, Inge Wallin, and -Thomas Bellman wrote @file{avl-tree.el}, for balanced binary trees. - -@item -Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for -Emacs Lisp functions; and @file{trace.el}, a tracing facility for Emacs -Lisp. - -@item -Chris Chase, Carsten Dominik, and J.@: D.@: Smith wrote IDLWAVE mode, -for editing IDL and WAVE CL. - -@item -Bob Chassell wrote @file{texnfo-upd.el}, @file{texinfo.el}, and -@file{makeinfo.el}, modes and utilities for working with Texinfo files; -and @file{page-ext.el}, commands for extended page handling. - -@item -Jihyun Cho wrote @file{hanja-util.el} and @file{hangul.el}, utilities -for Korean Hanja. - -@item -Andrew Choi and Yamamoto Mitsuharu wrote the Carbon support, used -prior to Emacs 23 for Mac OS. - -@item -Chong Yidong was the Emacs co-maintainer for Emacs 23. He made many -improvements to the Emacs display engine; and, together with Kai -Gro@ss{}johann and Alex Schroeder, wrote @file{longlines.el}, a minor -mode for wrapping long lines. - -@item -James Clark wrote SGML mode, a mode for editing SGML documents; and -nXML mode, a mode for editing XML documents. He also contributed to -Emacs's dumping procedures. - -@item -Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. - -@item -Glynn Clements provided @file{gamegrid.el} and a couple of games that -use it, Snake and Tetris. - -@item -Andrew Cohen wrote @file{spam-wash.el}, to decode and clean email before -it is analysed for spam. - -@item -Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a -package for easy definition of major and minor modes. - -@item -Andrew Csillag wrote M4 mode (@file{m4-mode.el}). - -@item -Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler -for compiled Emacs Lisp code. - -@item -Mathias Dahl wrote @file{image-dired.el}, a package for viewing image -files as ``thumbnails.'' - -@item -Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a -new Emacs job, or restarts a paused Emacs if one exists. - -@item -Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the -@file{/usr/uci/post} mailer. - -@item -Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed -text replace the current selection. - -@item -Eric Ding wrote @file{goto-addr.el}, - -@item -Jan Dj@"{a}rv added support for the GTK+ toolkit and X drag-and-drop. - -@item -Carsten Dominik wrote Ref@TeX{}, a package for setting up labels and -cross-references in La@TeX{} documents; and co-wrote IDLWAVE mode -(q.v.@:). He was the main author of Org mode, for maintaining notes, -todo lists, and project planning. Thomas Baumann, Bastien Guerry, -Tassilo Horn, Philip Jackson, Tokuya Kameshima, Eric Schulte, Andy -Stewart, David O'Toole, John Wiegley, and Piotr Zielinski also wrote -various Org mode components. - -@item -Scott Draves wrote @file{tq.el}, help functions for maintaining -transaction queues between Emacs and its subprocesses. - -@item -Benjamin Drieu wrote @file{pong.el}, an implementation of the classical -pong game. - -@item -Viktor Dukhovni wrote support for dumping under SunOS version 4. - -@item -John Eaton and Kurt Hornik wrote Octave mode. - -@item -Rolf Ebert co-wrote Ada mode. - -@item -Stephen Eglen wrote @file{mspools.el}, which tells you which Procmail -folders have mail waiting in them; and @file{iswitchb.el}, a feature -for incremental reading and completion of buffer names. - -@item -Torbj@"orn Einarsson wrote @file{f90.el}, a mode for Fortran 90 files. - -@item -Tsugutomo Enami co-wrote the support for international character sets. - -@item -David Engster wrote @file{mairix.el} and @file{nnmairix.el}, an -interface to the Mairix indexing tool. - -@item -Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 -code. - -@item -Michael Ernst wrote @file{reposition.el}, a command for recentering a -function's source code and preceding comment on the screen. - -@item -Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data -Language source code. - -@item -Frederick Farnbach implemented @file{morse.el}, which converts text to -Morse code. - -@item -Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which -is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and -@file{ldap.el}, the LDAP client interface. - -@item -Fred Fish wrote the support for dumping COFF executable files. - -@item -Karl Fogel wrote @file{bookmark.el}, which implements named -placeholders; @file{mail-hist.el}, a history mechanism for outgoing -mail messages; and @file{saveplace.el}, for preserving point's -location in files between editing sessions. - -@item -Gary Foster wrote @file{crisp.el}, the emulation for CRiSP and Brief -editors; and @file{scroll-all.el}, a mode for scrolling several buffers -together. - -@item -Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, -@file{type-break.el}, which reminds you to take periodic breaks from -typing, and @code{eldoc-mode}, a mode to show the defined parameters or -the doc string for the Lisp function near point. - -@item -Shigeru Fukaya wrote a testsuite for the byte-compiler. - -@item -Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. - -@item -Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote -@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF -flow control. - -@item -Kevin Gallo added multiple-frame support for Windows NT and wrote -@file{w32-win.el}, support functions for the MS-Windows window system. - -@item -Juan Le@'{o}n Lahoz Garc@'{i}a wrote @file{wdired.el}, a package for -performing file operations by directly editing Dired buffers. - -@item -Howard Gayle wrote much of the C and Lisp code for display tables and -case tables. He also wrote @file{rot13.el}, a command to display the -plain-text form of a buffer encoded with the Caesar cipher; -@file{vt100-led.el}, a package for controlling the LEDs on -VT100-compatible terminals; and much of the support for ISO-8859 -European character sets (which includes @file{iso-ascii.el}, -@file{iso-insert.el}, @file{iso-swed.el}, -@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}). - -@item -Stephen Gildea made the Emacs quick reference card, and made many -contributions for @file{time-stamp.el}, a package for maintaining -last-change time stamps in files. - -@item -Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for -Gnus. - -@item -David Gillespie wrote the Common Lisp compatibility packages; -@code{Calc}, an advanced calculator and mathematical tool, since -maintained and developed by Jay Belanger; @file{complete.el}, a partial -completion mechanism; and @file{edmacro.el}, a package for editing -keyboard macros. - -@item -Bob Glickstein wrote @file{sregex.el}, a facility for writing regexps -using a Lisp-like syntax. - -@item -Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse -cursor out of the way of the text cursor; @file{shadowfile.el}, a -package for keeping identical copies of files in more than one place; -@file{format.el}, a package for reading and writing files in various -formats; @file{enriched.el}, a package for saving text properties in -files; @file{facemenu.el}, a package for specifying faces; and -@file{descr-text.el}, describing text and character properties. - -@item -Michelangelo Grigni wrote @file{ffap.el} which visits a file, -taking the file name from the buffer. - -@item -Odd Gripenstam wrote @file{dcl-mode.el} for editing DCL command files. - -@item -Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between -the ISO 8859-1 character set and the notations for non-@acronym{ASCII} -characters used by @TeX{} and net tradition. - -@item -Bastien Guerry wrote @file{gnus-bookmark.el}, bookmark support for Gnus; -as well as contributing to Org mode (q.v.@:). - -@item -Henry Guillaume wrote @file{find-file.el}, a package to visit files -related to the currently visited file. - -@item -Doug Gwyn wrote the portable @code{alloca} implementation. - -@item -Ken'ichi Handa implemented most of the support for international -character sets, and wrote most of the Emacs 23 font handling code. He -also wrote @file{composite.el}, which provides a minor mode that -composes characters automatically when they are displayed; -@file{isearch-x.el}, a facility for searching non-@acronym{ASCII} -text; and @file{ps-bdf.el}, a BDF font support for printing -non-@acronym{ASCII} text on a PostScript printer. Together with Naoto -Takahashi, he wrote @file{quail.el}, an input facility for typing -non-@acronym{ASCII} text from an @acronym{ASCII} keyboard. - -@item -Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. - -@item -K. Shane Hartman wrote @file{chistory.el} and @file{echistory.el}, -packages for browsing command history lists; @file{electric.el} and -@file{helper.el}, which provide an alternative command loop and -appropriate help facilities; @file{emacsbug.el}, a package for -reporting Emacs bugs; @file{picture.el}, a mode for editing -@acronym{ASCII} pictures; and @file{view.el}, a package for perusing -files and buffers without editing them. - -@item -John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, -which provide alternative mouse-based editing and scrolling features. - -@item -Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation -format of Unicode. - -@item -Markus Heritsch co-wrote Ada mode. - -@item -Karl Heuer wrote the original blessmail script, implemented the -@code{intangible} text property, and rearranged the structure of the -@code{Lisp_Object} type to allow for more data bits. - -@item -Manabu Higashida ported Emacs to MS-DOS. - -@item -Anders Holst wrote @file{hippie-exp.el}, a versatile completion and -expansion package. - -@item -Tassilo Horn wrote DocView mode, allowing viewing of PDF, PostScript and -DVI documents. - -@item -Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} -template instantiations. - -@item -Joakim Hove wrote @file{html2text.el}, a html to plain text converter. - -@item -Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW -browser to display a URL. - -@item -Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and -wrote many of its parts. Several of these are now general components of -Emacs: @file{dns.el} for Domain Name Service lookups; -@file{format-spec.el} for formatting arbitrary format strings; -@file{netrc.el} for parsing of @file{.netrc} files; and -@file{time-date.el} for general date and time handling. Components of -Gnus have also been written by: Nagy Andras, David Blacka, Scott Byer, -Kevin Greiner, Kai Gro@ss{}johann, Joe Hildebrand, Paul Jarc, Sascha -L@"{u}decke, David Moore, Jim Radford, Benjamin Rutt, Raymond Scholz, -Thomas Steffen, Reiner Steib, Didier Verna, Ilja Weis, Katsumi Yamaoka, -Teodor Zlatanov, and others (@pxref{Contributors,,,gnus, the Gnus Manual}). - -@item -Andrew Innes contributed extensively to the MS-Windows support. - -@item -Seiichiro Inoue improved Emacs's XIM support. - -@item -Philip Jackson wrote @file{find-cmd.el}, to build a @code{find} -command-line. - -@item -Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs -diary entries to and from the iCalendar format; -@file{newsticker.el}, an RSS and Atom based Newsticker; and -@file{bubbles.el}, a puzzle game. - -@item -Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game. - -@item -Terry Jones wrote @file{shadow.el}, a package for finding potential -load-path problems when some Lisp file ``shadows'' another. - -@item -Simon Josefsson wrote @file{dns-mode.el}, an editing mode for Domain -Name System master files; @file{dig.el}, a Domain Name System interface; -@file{flow-fill.el}, a package for interpreting RFC2646 formatted text -in messages; @file{fringe.el}, a package for customizing the fringe; -@file{imap.el}, an Emacs Lisp library for talking to IMAP servers; -@file{password-cache.el}, a password reader; @file{nnimap.el}, the IMAP -back-end for Gnus; @file{url-imap.el} for the URL library; -@file{rfc2104.el}, a hashed message authentication facility; the Gnus -S/MIME and Sieve components; and @file{tls.el} and @file{starttls.el} -for the Transport Layer Security protocol. - -@item -Arne J@o{}rgensen wrote @file{latexenc.el}, a package to -automatically guess the correct coding system in LaTeX files. - -@item -Alexandre Julliard wrote @file{vc-git.el}, support for the Git version -control system. - -@item -Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out -mail with SMTP. - -@item -Ivan Kanis wrote @file{vc-hg.el}, support for the Mercurial version -control system. - -@item -Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining -bibliography databases compatible with @code{refer} (the @code{troff} -version) and @code{lookbib}, and @file{refbib.el}, a package to convert -those databases to the format used by the LaTeX text formatting package. - -@item -Taichi Kawabata added support for Devanagari script and the Indian -languages. - -@item -Taro Kawagishi implented the MD4 Message Digest Algorithm in Lisp; and -wrote @file{ntlm.el} and @file{sasl-ntlm.el} for NT LanManager -authentication support. - -@item -Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs -buffers. - -@item -Michael Kifer wrote @code{ediff}, an interactive interface to the -@command{diff}, @command{patch}, and @command{merge} programs; and -Viper, the newest emulation for VI. - -@item -Richard King wrote the first version of @file{userlock.el} and -@file{filelock.c}, which provide simple support for multiple users -editing the same file. He also wrote the initial version of -@file{uniquify.el}, a facility to make buffer names unique by adding -parts of the file's name to the buffer name. - -@item -Peter Kleiweg wrote @file{ps-mode.el}, a mode for editing PostScript -files and running a PostScript interpreter interactively from within -Emacs. - -@item -Shuhei Kobayashi wrote @file{hex-util.el}, for operating on hexadecimal -strings; support for HMAC (Keyed-Hashing for Message Authentication); -and a Lisp implementation of the SHA1 Secure Hash Algorithm. - -@item -Pavel Kobyakov wrote @file{flymake.el}, a minor mode for performing -on-the-fly syntax checking. - -@item -Larry K.@: Kolodney wrote @file{cvtmail.c}, a program to convert the mail -directories used by Gosling Emacs into RMAIL format. - -@item -David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for -interactive automatic highlighting of parts of the buffer text. - -@item -Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying -inline images. - -@item -Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up -menu support. - -@item -Sebastian Kremer wrote @code{dired-mode}, with contributions by Lawrence -R.@: Dodd. He also wrote @file{ls-lisp.el}, a Lisp emulation of the -@code{ls} command for platforms which don't have @code{ls} as a standard -program. - -@item -Geoff Kuenning and Ken Stevens wrote @file{ispell.el}, a spell-checker -interface. - -@item -David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for -easy insertion of boilerplate text and other common constructions. - -@item -Daniel LaLiberte wrote @file{edebug.el}, a source-level debugger for -Emacs Lisp; @file{cl-specs.el}, specifications to help @code{edebug} -debug code written using David Gillespie's Common Lisp support; -@file{cust-print.el}, a customizable package for printing lisp -objects; and @file{isearch.el}, Emacs's incremental search minor mode. -He also co-wrote @file{hideif.el} (q.v.@:). - -@item -Vinicius Jose Latorre wrote the Emacs printing facilities, as well as -@code{ps-print} (with Jim Thompson, Jacques Duthen, and Kenichi Handa), -a package for pretty-printing Emacs buffers to PostScript printers; -@file{delim-col.el}, a package to arrange text into columns; -@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic -chart that can be printed to a PostScript printer; and -@file{whitespace.el}, a package that detects and cleans up excess -whitespace in a file. The previous version of @file{whitespace.el}, -used prior to Emacs 23, was written by Rajesh Vaidheeswarran. - -@item -Frederic Lepied wrote @file{expand.el}, which uses the abbrev -mechanism for inserting programming constructs. - -@item -Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for -Emacs Lisp programs. - -@item -Lars Lindberg wrote @file{msb.el}, which provides more flexible menus -for buffer selection; co-wrote @file{imenu.el} (q.v.@:); and rewrote -@file{dabbrev.el}, originally written by Don Morrison. - -@item -Anders Lindgren wrote @file{autorevert.el}, a package for automatically -reverting files visited by Emacs that were changed on disk; -@file{cwarn.el}, a package to highlight suspicious C and C@t{++} -constructs; and @file{follow.el}, a minor mode to synchronize windows -that show the same buffer. - -@item -Thomas Link wrote @file{filesets.el}, a package for handling sets of -files. - -@item -Juri Linkov wrote @file{misearch.el}, extending isearch to multi-buffer -searches. - -@item -K@'{a}roly L@"{o}rentey wrote the ``multi-terminal'' code, which -allows Emacs to run on graphical and text-only terminals -simultaneously. - -@item -Martin Lorentzon wrote @file{vc-annotate.el}, support for version -control annotation. - -@item -Dave Love wrote much of the code dealing with Unicode support and -Latin-N unification. He added support for many coding systems, -including the various UTF-7 and UTF-16 coding systems. He also wrote -@code{autoarg-mode}, a global minor mode whereby digit keys supply -prefix arguments; @code{autoarg-kp-mode}, which redefines the keypad -numeric keys to digit arguments; @file{autoconf.el}, a mode for editing -Autoconf files; @file{cfengine.el}, a mode for editing Cfengine files; -@file{elide-head.el}, a package for eliding boilerplate text from file -headers; @file{hl-line.el}, a minor mode for highlighting the line in -the current window on which point is; @file{cap-words.el}, a minor mode -for motion in ``CapitalizedWordIdentifiers''; @file{latin1-disp.el}, a -package that lets you display ISO 8859 characters on Latin-1 terminals -by setting up appropriate display tables; @file{python.el}, a major mode -for the Python programming language; @file{refill.el}, a mode for -automatic paragraph refilling, akin to typical word processors; -@file{smiley.el}, a facility for displaying smiley faces; -@file{sym-comp.el}, a library for performing mode-dependent symbol -completion; @file{benchmark.el} for timing code execution; and -@file{tool-bar.el}, a mode to control the display of the Emacs tool bar. -With Riccardo Murri he wrote @file{vc-bzr.el}, support for the Bazaar -version control system. - -@item -Eric Ludlam wrote the Speedbar package. He also wrote -@file{checkdoc.el}, for checking doc strings in Emacs Lisp programs; -@file{dframe.el}, providing dedicatd frame support modes; and -@file{ezimage.el}, a generalized way to place images over text. - -@item -Alan Mackenzie wrote the integrated AWK support in CC Mode, and -maintained CC Mode from Emacs 22 onwards. - -@item -Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking -simple substitution ciphers. - -@item -Neil M.@: Mager wrote @file{appt.el}, functions to notify users of their -appointments. It finds appointments recorded in the diary files -used by the @code{calendar} package. - -@item -Ken Manheimer wrote @file{allout.el}, a mode for manipulating and -formatting outlines, and @file{icomplete.el}, which provides incremental -completion feedback in the minibuffer. - -@item -Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. - -@item -Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for -hiding selected code within C @code{#ifdef} clauses. - -@item -Simon Marshall wrote @file{regexp-opt.el}, which generates a regular -expression from a list of strings; and the fast-lock and lazy-lock -font-lock support modes. He also extended @file{comint.el} and -@file{shell.el}, originally written by Olin Shivers. - -@item -Bengt Martensson, Dirk Herrmann, Marc Shapiro, Mike Newton, Aaron Larson, -and Stefan Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} -bibliography files. - -@item -Charlie Martin wrote @file{autoinsert.el}, which provides automatic -mode-sensitive insertion of text into new files. - -@item -Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode. - -@item -Thomas May wrote @file{blackbox.el}, a version of the traditional -blackbox game. - -@item -Roland McGrath wrote @file{compile.el} (since updated by Daniel -Pfeiffer), a package for running compilations in a buffer, and then -visiting the locations reported in error messages; @file{etags.el}, a -package for jumping to function definitions and searching or replacing -in all the files mentioned in a @file{TAGS} file; @file{find-dired.el}, -for using @code{dired} commands on output from the @code{find} program, -with Sebastian Kremer; @file{grep.el} for running the @code{grep} -command; @file{map-ynp.el}, a general purpose boolean question-asker; -@file{autoload.el}, providing semi-automatic maintenance of autoload -files. - -@item -Michael McNamara and Wilson Snyder wrote Verilog mode. - -@item -David Megginson wrote @file{derived.el}, which allows one to define new -major modes by inheriting key bindings and commands from existing major -modes. - -@item -Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding -command with its arguments. - -@item -Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting -Common Lisp code; @file{ebuff-menu.el}, an ``electric'' browser for -buffer listings; @file{ehelp.el}, bindings for browsing help screens; -@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles; @file{terminal.el}, a -terminal emulator for Emacs subprocesses; and @file{yow.el}, an -essential utility. - -@item -Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 -development until the release of 21.1. He wrote the new display -engine used from Emacs 21 onwards, and the asynchronous timers -facility. He also wrote @code{ebrowse}, the C@t{++} browser; -@file{jit-lock.el}, the Just-In-Time font-lock support mode; -@file{tooltip.el}, a package for displaying tooltips; -@file{authors.el}, a package for maintaining the @file{AUTHORS} file; -and @file{rx.el}, a regular expression constructor. - -@item -Stefan Monnier was the Emacs co-maintainer for Emacs 23. He added -support for Arch and Subversion to VC, re-wrote much of the Emacs server -to use the built-in networking primitives, and re-wrote the abbrev and -minibuffer completion code for Emacs 23. He also wrote @code{PCL-CVS}, -a directory-level front end to the CVS version control system; -@file{reveal.el}, a minor mode for automatically revealing invisible -text; @file{smerge-mode.el}, a minor mode for resolving @code{diff3} -conflicts; @file{diff-mode.el}, a mode for viewing and editing context -diffs; @file{css-mode.el} for Cascading Style Sheets; and -@file{bibtex-style.el} for BibTeX Style files. - -@item -Morioka Tomohiko wrote several packages for MIME support in Gnus and -elsewhere. - -@item -Takahashi Naoto co-wrote @file{quail.el} (q.v.@:), and wrote -@file{robin.el}, another input method. - -@item -Sen Nagata wrote @file{crm.el}, a package for reading multiple strings -with completion, and @file{rfc2368.el}, support for @code{mailto:} -URLs. - -@item -Erik Naggum wrote the time-conversion functions. He also wrote -@file{disp-table.el}, a package for dealing with display tables; -@file{mailheader.el}, a package for parsing email headers; and -@file{parse-time.el}, a package for parsing time strings. - -@item -Thomas Neumann and Eric Raymond wrote @file{make-mode.el}, -a mode for editing makefiles. - -@item -Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor -mode for selectively displaying blocks of text. - -@item -Dan Nicolaescu added support for running Emacs as a daemon. He also -wrote @file{romanian.el}, support for editing Romanian text; -@file{iris-ansi.el}, support for running Emacs on SGI's @code{xwsh} -and @code{winterm} terminal emulators; and @file{vc-dir.el}, displaying -the status of version-controlled directories. - -@item -Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. - -@item -Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer -history between Emacs sessions. - -@item -Jeff Norden wrote @file{kermit.el}, a package to help the Kermit -dialup communications program run comfortably in an Emacs shell buffer. - -@item -Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP -support. - -@item -Edward O'Connor wrote @file{json.el}, a file for parsing and -generating JSON files. - -@item -Kentaro Ohkouchi created the Emacs icons used beginning with Emacs 23. - -@item -Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail -splitting mechanism. - -@item -Takaaki Ota wrote @file{table.el}, a package for creating and editing -embedded text-based tables. - -@item -Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for -the MIX assembly language. - -@item -David Pearson wrote @file{quickurl.el}, a simple method of inserting a -URL into the current buffer based on text at point; @file{5x5.el}, a -game to fill all squares on the field. - -@item -Jeff Peck wrote @file{sun.el}, key bindings for sunterm keys. - -@item -Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of -the ``Towers of Hanoi'' puzzle. - -@item -William M.@: Perry wrote @file{mailcap.el} (with Lars Magne -Ingebrigtsen), a MIME media types configuration facility; -@file{mwheel.el}, a package for supporting mouse wheels; co-wrote (with -Dave Love) @file{socks.el}, a Socks v5 client; and developed the URL -package. - -@item -Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. - -@item -Jens Petersen wrote @file{find-func.el}, which makes it easy to find -the source code for an Emacs Lisp function or variable. - -@item -Daniel Pfeiffer wrote @file{conf-mode.el}, a mode for editing -configuration files; @file{copyright.el}, a package for updating -copyright notices in files; @file{executable.el}, a package for -executing interpreter scripts; @file{sh-script.el}, a mode for editing -shell scripts; @file{skeleton.el}, implementing a concise language for -writing statement skeletons; and @file{two-column.el}, a minor mode -for simultaneous two-column editing. - -Daniel also rewrote @file{apropos.el} (originally written by Joe Wells), -for finding commands, functions, and variables matching a regular -expression; and, together with Jim Blandy, co-authored @file{wyse50.el}, -support for Wyse 50 terminals. He also co-wrote @file{compile.el} -(q.v.@:) and @file{ada-stmt.el}. - -@item -Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC -1460) interface for Emacs. - -@item -Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit -widgets. - -@item -Fran@,{c}ois Pinard, Greg McGary, and Bruno Haible wrote @file{po.el}, -support for PO translation files. - -@item -Christian Plaunt wrote @file{soundex.el}, an implementation of the -Soundex algorithm for comparing English words by their pronunciation. - -@item -David Ponce wrote @file{recentf.el}, a package that puts a menu of -recently visited files in the Emacs menu bar; @file{ruler-mode.el}, a -minor mode for displaying a ruler in the header line; and -@file{tree-widget.el}, a package to display hierarchical data -structures. - -@item -Francesco A.@: Potorti wrote @file{cmacexp.el}, providing a command which -runs the C preprocessor on a region of a file and displays the results. -He also expanded and redesigned the @code{etags} program. - -@item -Michael D.@: Prange and Steven A.@: Wood wrote @file{fortran.el}, a mode -for editing Fortran code. - -@item -Ashwin Ram wrote @file{refer.el}, commands to look up references in -bibliography files by keyword. - -@item -Eric S.@: Raymond wrote @file{vc.el}, an interface to the RCS and SCCS -source code version control systems, with Paul Eggert; @file{gud.el}, -a package for running source-level debuggers like GDB and SDB in -Emacs; @file{asm-mode.el}, a mode for editing assembly language code; -@file{AT386.el}, terminal support package for IBM's AT keyboards; -@file{cookie1.el}, support for ``fortune-cookie'' programs like -@file{yow.el} and @file{spook.el}; @file{finder.el}, a package for -finding Emacs Lisp packages by keyword and topic; @file{keyswap.el}, -code to swap the @key{BS} and @key{DEL} keys; @file{loadhist.el}, -functions for loading and unloading Emacs features; -@file{lisp-mnt.el}, functions for working with the special headers -used in Emacs Lisp library files; and code to set and make use of the -@code{load-history} lisp variable, which records the source file from -which each lisp function loaded into Emacs came. - -@item -Edward M.@: Reingold wrote the extensive calendar and diary support, -with contributions from Stewart Clamen (@file{cal-mayan.el}), Nachum -Dershowitz (@file{cal-hebrew.el}), Paul Eggert (@file{cal-dst.el}), -Steve Fisk (@file{cal-tex.el}), Michael Kifer (@file{cal-x.el}), Lara -Rios (@file{cal-menu.el}), and Denis B.@: Roegel (@file{solar.el}). -Andy Oram contributed to its documentation. Reingold also contributed -to @file{tex-mode.el}, a mode for editing @TeX{} files, as did William -F.@: Schelter, Dick King, Stephen Gildea, Michael Prange, and Jacob -Gore. - -@item -David Reitter wrote @file{mailclient.el} which can send mail via the -system's designated mail client. - -@item -Alex Rezinsky wrote @file{which-func.el}, a mode that shows the name -of the current function in the mode line. - -@item -Rob Riepel wrote @file{tpu-edt.el} and its associated files, providing -an emulation of the VMS TPU text editor emulating the VMS EDT editor, -and @file{vt-control.el}, providing some control functions for the DEC -VT line of terminals. - -@item -Nick Roberts wrote @file{gdb-ui.el}, the graphical user interface to -GDB; and @file{t-mouse.el}, mouse support in text terminals. - -@item -Danny Roozendaal implemented @file{handwrite.el}, which converts text -into ``handwriting.'' - -@item -Markus Rost wrote @file{cus-test.el}, a testing framework for customize. - -@item -Guillermo J.@: Rozas wrote @file{scheme.el}, a mode for editing Scheme and -DSSSL code, and @file{fakemail.c}, an interface to the System V mailer. - -@item -Ivar Rummelhoff wrote @file{winner.el}, which records recent window -configurations so you can move back to them. - -@item -Jason Rumney ported the Emacs 21 display engine to MS-Windows, and has -contributed extensively to the MS-Windows port of Emacs. - -@item -Wolfgang Rupprecht wrote Emacs 19's floating-point support (including -@file{float-sup.el} and @file{floatfns.c}), and @file{sup-mouse.el}, -support for the Supdup mouse on lisp machines. - -@item -Kevin Ryde wrote @file{info-xref.el}, a library for checking -references in Info files. - -@item -James B.@: Salem and Brewster Kahle wrote @file{completion.el}, providing -dynamic word completion. - -@item -Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. - -@item -Holger Schauer wrote @file{fortune.el}, a package for using fortune in -message signatures. - -@item -William Schelter wrote @file{telnet.el}, support for @code{telnet} -sessions within Emacs. - -@item -Ralph Schleicher wrote @file{battery.el}, a package for displaying -laptop computer battery status, and @file{info-look.el}, a package for -looking up Info documentation for symbols in the buffer. - -@item -Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for -editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. - -@item -Ronald S.@: Schnell wrote @file{dunnet.el}, a text adventure game. - -@item -Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played -against Emacs; and @file{mpuz.el}, a multiplication puzzle. - -@item -Rainer Schoepf contributed to Alpha and OSF1 support. - -@item -Jan Schormann wrote @file{solitaire.el}, an implementation of the -Solitaire game. - -@item -Alex Schroeder wrote @file{ansi-color.el}, a package for translating -ANSI color escape sequences to Emacs faces; @file{sql.el}, a package -for interactively running an SQL interpreter in an Emacs buffer; -@file{cus-theme.el}, an interface for custom themes; @file{master.el}, a -package for making a buffer @samp{master} over another; and -@file{spam-stat.el}, for statistical detection of junk email. He also -wrote parts of the IRC client ERC (q.v.@:). - -@item -Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. - -@item -Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining -@file{TODO} list files. - -@item -Manuel Serrano wrote the Flyspell package, which does spell checking -as you type. - -@item -Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting -windows based on their geometrical position on the frame. - -@item -Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited -commercial email. - -@item -Richard Sharman wrote @file{hilit-chg.el}, which uses colors to show -recent editing changes. - -@item -Olin Shivers wrote @file{comint.el}, a library for modes running -interactive command-line-oriented subprocesses, and @file{shell.el}, for -running inferior shells (both since extended by Simon Marshall); -@file{cmuscheme.el}, for running inferior Scheme processes; -@file{inf-lisp.el}, for running inferior Lisp process. - -@item -Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. - -@item -Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating -mostly-constant data. - -@item -Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive -help for key bindings. - -@item -Chris Smith wrote @file{icon.el}, a mode for editing Icon code. - -@item -David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs -Lisp interpreter as a subprocess. - -@item -Paul D.@: Smith wrote @file{snmp-mode.el}. - -@item -William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe -files, and @file{server.el}, a package allowing programs to send files -to an extant Emacs job to be edited. - -@item -Andre Spiegel made many contributions to the Emacs Version Control -package, and in particular made it support multiple back ends. - -@item -Michael Staats wrote @file{pc-select.el}, which rebinds keys for -selecting regions to follow many other systems. - -@item -Richard Stallman invented Emacs. He is the original author of GNU -Emacs, and has been Emacs maintainer over several non-contiguous -periods. In addition to much of the ``core'' Emacs code, he has -written @file{easymenu.el}, a facility for defining Emacs menus; -@file{image-mode.el}, support for visiting image files; -@file{menu-bar.el}, the Emacs menu bar support code; -@file{paren.el}, a package to make matching parentheses stand out in -color; and also co-authored portions of CC mode. - -@item -Sam Steingold wrote @file{gulp.el}, a facility for asking package -maintainers for updated versions of their packages via e-mail, and -@file{midnight.el}, a package for running a command every midnight. - -@item -Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for -browsing indices made from buffer contents. - -@item -Peter Stephenson wrote @file{vcursor.el}, which implements a ``virtual -cursor'' that you can move with the keyboard and use for copying text. - -@item -Ken Stevens wrote the initial version of @file{ispell.el} and maintains -that package since Ispell 3.1 release. - -@item -Kim F.@: Storm made many improvements to the Emacs display engine, -process support, and networking support. He also wrote -@file{bindat.el}, a package for encoding and decoding binary data; -CUA mode, which allows Emacs to emulate the standard CUA key -bindings; @file{ido.el}, a package for selecting buffers and files -quickly; @file{keypad.el} for simplified keypad bindings; and -@file{kmacro.el}, the keyboard macro facility. - -@item -Martin Stjernholm co-authored CC Mode, a major editing mode for C, -C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. - -@item -Steve Strassman did not write @file{spook.el}, and even if he did, he -really didn't mean for you to use it in an anarchistic way. - -@item -Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs -buffers. - -@item -Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for -editing text in Slovak language. - -@item -Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through -the keyboard. - -@item -Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing -image files as ``thumbnails.'' - -@item -Spencer Thomas wrote the original @file{dabbrev.el}, providing a command -which completes the partial word before point, based on other nearby -words for which it is a prefix. He also wrote the original dumping -support. - -@item -Toru Tomabechi contributed to Tibetan support. - -@item -Markus Triska wrote @file{linum.el}, a minor mode that displays line -numbers in the left margin. - -@item -Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a mode for editing -Tcl/Tk source files and running a Tcl interpreter as an Emacs -subprocess. - -@item -Tom Tromey wrote @file{bug-reference.el}, providing clickable links to -bug reports. - -@item -Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. - -@item -Daiki Ueno wrote @file{starttls.el}, support for Transport Layer -Security protocol; @file{sasl-cram.el} and @file{sasl-digest.el} (with -Kenichi Okada), and @file{sasl.el}, support for Simple Authentication -and Security Layer (SASL); and the EasyPG (and its predecessor PGG) -package, for GnuPG and PGP support. - -@item -Masanobu Umeda wrote GNUS, a feature-rich reader for Usenet news that -was the ancestor of the current Gnus package. He also wrote -@file{prolog.el}, a mode for editing Prolog code; @file{rmailsort.el}, a -package for sorting messages in RMAIL folders; @file{metamail.el}, an -interface to the Metamail program; @file{gnus-kill.el}, the Kill File -mode for Gnus; @file{gnus-mh.el}, an mh-e interface for Gnus; -@file{gnus-msg.el}, a mail and post interface for Gnus; and -@file{timezone.el}, providing functions for dealing with time zones. - -@item -Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package. - -@item -Didier Verna wrote @file{rect.el}, a package of functions for -operations on rectangle regions of text. He also contributed to Gnus -(q.v.@:). - -@item -Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. - -@item -Geoffrey Voelker wrote the Windows NT support. He also wrote -@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports -of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. - -@item -Johan Vromans wrote @file{forms.el} and its associated files, a mode for -filling in forms. He also wrote @file{iso-acc.el}, a minor mode -providing electric accent keys. - -@item -Colin Walters wrote Ibuffer, an enhanced buffer menu. - -@item -Barry Warsaw wrote @file{assoc.el}, a set of utility functions for -working with association lists; @file{cc-mode.el}, a mode for editing -C, C@t{++}, and Java code, based on earlier work by Dave Detlefs, -Stewart Clamen, and Richard Stallman; @file{elp.el}, a profiler -for Emacs Lisp programs; @file{man.el}, a mode for reading UNIX manual -pages; @file{regi.el}, providing an AWK-like functionality for use in -lisp programs; @file{reporter.el}, providing customizable bug -reporting for lisp packages; and @file{supercite.el}, a minor mode for -quoting sections of mail messages and news articles. - -@item -Christoph Wedler wrote @file{antlr-mode.el}, a major mode for ANTLR -grammar files. - -@item -Morten Welinder helped port Emacs to MS-DOS, and introduced face -support into the MS-DOS port of Emacs. He also wrote -@file{desktop.el}, facilities for saving some of Emacs's state between -sessions; @file{timer.el}, the Emacs facility to run commands at a -given time or frequency, or when Emacs is idle, and its C-level -support code; @file{pc-win.el}, the MS-DOS ``window-system'' support; -@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS -port of Emacs; @file{arc-mode.el}, the mode for editing compressed -archives; @file{s-region.el}, commands for setting the region using -the shift key and motion commands; and @file{dos-fns.el}, functions -for use under MS-DOS. - -@item -Joe Wells wrote the original version of @file{apropos.el} (q.v.@:); -@file{resume.el}, support for processing command-line arguments after -resuming a suspended Emacs job; and @file{mail-extr.el}, a package for -extracting names and addresses from mail headers, with contributions -from Jamie Zawinski. - -@item -Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}, a major -mode for editing VHDL source code. - -@item -John Wiegley wrote @file{align.el}, a set of commands for aligning text -according to regular-expression based rules; @file{isearchb.el} for fast -buffer switching; @file{timeclock.el}, a package for keeping track of -time spent on projects; the Baha'i calendar support; -@file{pcomplete.el}, a programmable completion facility; -@file{remember.el}, a mode for jotting down things to remember; -@file{eudcb-mab.el}, an address book backend for the Emacs Unified -Directory Client; and @code{eshell}, a command shell implemented -entirely in Emacs Lisp. He also contributed to Org mode (q.v.@:). - -@item -Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from -RMAIL format to Unix @code{mbox} format. - -@item -Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse -selection; and @file{thingatpt.el}, a library of functions for finding -the ``thing'' (word, line, s-expression) containing point. - -@item -Roland Winkler wrote @file{proced.el}, a system process editor. - -@item -Bill Wohler wrote MH-E, the Emacs interface to the MH mail system; -making use of earlier work by James R.@: Larus. Satyaki Das, Peter S.@: -Galbraith, Stephen Gildea, and Jeffrey C.@: Honig also wrote various -MH-E components. - -@item -Dale R.@: Worley wrote @file{emerge.el}, a package for interactively -merging two versions of a file. - -@item -Francis J.@: Wright wrote @file{woman.el}, a package for browsing -manual pages without the @code{man} command. - -@item -Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder -to exit with valuable buffers unsaved. - -@item -Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU -linker scripts, and contributed subword handling in CC mode. - -@item -Jonathan Yavner wrote @file{testcover.el}, a package for keeping track -of the testing status of Emacs Lisp code; @file{unsafep.el} to determine -if a Lisp form is safe; and the SES spreadsheet package. - -@item -Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. - -@item -Ilya Zakharevich and Bob Olson wrote @file{cperl-mode.el}, a major -mode for editing Perl code. Ilya Zakharevich also wrote -@file{tmm.el}, a mode for accessing the Emacs menu bar on a text-mode -terminal. - -@item -Milan Zamazal wrote @file{czech.el}, support for editing Czech text; -@file{glasses.el}, a package for easier reading of source code that -uses illegible identifier names; and @file{tildify.el}, commands for -adding hard spaces to text, @TeX{}, and SGML/HTML files. - -@item -Victor Zandy wrote @file{zone.el}, a package for people who like to -zone out in front of Emacs. - -@item -Eli Zaretskii made many standard Emacs features work on MS-DOS and -Microsoft Windows. He also wrote @file{tty-colors.el}, which -implements transparent mapping of X colors to tty colors; and -@file{rxvt.el}. - -@item -Jamie Zawinski wrote much of the support for faces and X selections. -With Hallvard Furuseth, he wrote the optimizing byte compiler used -from Emacs 19 onwards. He also wrote @file{mailabbrev.el}, a package -that provides automatic expansion of mail aliases, and -@file{tar-mode.el}, which provides simple viewing and editing commands -for tar files. - -@item -Andrew Zhilin created the Emacs 22 icons. - -@item -Shenghuo Zhu wrote @file{binhex.el}, a package for reading and writing -binhex files; @file{mm-partial.el}, message/partial support for MIME -messages; @file{rfc1843.el}, an HZ decoding package; -@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data; and -@file{webmail.el}, an interface to Web mail. He also wrote several -other Gnus components. - -@item -Ian T.@: Zimmerman wrote @file{gametree.el}. - -@item -Reto Zimmermann wrote @file{vera-mode.el}. - -@item -Neal Ziring and Felix S.@: T.@: Wu wrote @file{vi.el}, an emulation of the -VI text editor. - -@item -Detlev Zundel wrote @file{re-builder.el}, a package for building regexps -with visual feedback. - -@end itemize - -@ignore - arch-tag: bb1d0fa4-0240-4992-b5d4-8602d1e3d4ba -@end ignore diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi deleted file mode 100644 index ae9e723db8a..00000000000 --- a/doc/emacs/anti.texi +++ /dev/null @@ -1,141 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Antinews, Mac OS / GNUstep, X Resources, Top -@appendix Emacs 22 Antinews -@c Update the emacs.texi Antinews menu entry with the above version number. - - For those users who live backwards in time, here is information -about downgrading to Emacs version 22.3. We hope you will enjoy the -greater simplicity that results from the absence of many Emacs -@value{EMACSVER} features. - -@itemize @bullet - -@item -We have switched to a character representation specially designed for -Emacs. Rather than forcing all the widely used scripts into artificial -alignment, as Unicode does, Emacs treats them all equally, giving -each one a place in the space of character codes. We have eliminated -the confusing practice, in Emacs 23, whereby one character can belong -to multiple character sets. Now each script has its own variant, and -they all are different as far as Emacs is concerned. For example, -there's a Latin-1 c-cedilla character, and there's a Latin-2 -c-cedilla; searching a buffer for the Latin-1 variant only finds that -variant, but not the others. - -@item -Emacs now uses its own special internal encoding for non-@acronym{ASCII} -characters, known as @samp{emacs-mule}. This was imperative to -support several different variants of the same character, each one -belonging to its own script: @samp{emacs-mule} marks each character -with its script, to better discern them from one another. - -@item -For simplicity, the functions @code{encode-coding-region} and -@code{decode-coding-region} no longer accept an argument saying where -to store the result of their conversions. The result always replaces -the original, so there's no need to look for it elsewhere. - -@item -Emacs no longer performs font anti-aliasing. If your fonts look ugly, -try choosing a larger font and increasing the screen resolution. -Admittedly, this becomes difficult as you go further back in time, -since available screen resolutions will decrease. - -@item -The Fontconfig font library is no longer supported. To specify a -font, you must use an XLFD (X Logical Font Descriptor). The other -ways of specifying fonts---so-called ``Fontconfig'' and ``GTK'' font -names---are redundant, so they have been removed. - -@item -Transient Mark mode is now disabled by default. Furthermore, some -commands that operate specifically on the region when it is active and -Transient Mark mode is enabled (such as @code{fill-paragraph} -@code{ispell-word}, and @code{indent-for-tab-command}), no longer do -so. - -@item -Holding @key{shift} while typing a motion command no longer creates a -temporarily active region, since that's inconsistent with how Emacs -normally handles keybindings. The variable @code{shift-select-mode} -has been deleted. You can, however, still create temporarily active -regions by dragging the mouse. - -@item -The line motion commands, @kbd{C-n} and @kbd{C-p}, now move by logical -text lines, not screen lines. Even if a long text line is continued -over multiple screen lines, @kbd{C-n} and @kbd{C-p} treat it as a -single line, because that's ultimately what it is. - -@item -Visual Line mode, which provides ``word wrap'' functionality, has been -removed. You can still use Long Lines mode to gain an approximation -of word wrapping, though this has some drawbacks---for instance, -syntax highlighting often doesn't work well on wrapped lines. - -@item -@kbd{C-l} now runs @code{recenter} instead of -@code{recenter-top-bottom}. This always sets the current line at the -center of the window, instead of cycling through the center, top, and -bottom of the window on successive invocations. This lets you type -@kbd{C-l C-l C-l C-l} to be @emph{absolutely sure} that you have -recentered the line. - -@item -The way Emacs generates possible minibuffer completions is now much -simpler to understand. It matches alternatives to the text before -point, ignoring the text after point; it also does not attempt to -perform partial completion if the first completion attempt fails. - -@item -Typing @kbd{M-n} at the start of the minibuffer history list no longer -attempts to generate guesses of possible minibuffer input. It instead -does the straightforward thing, by issuing the message @samp{End of -history; no default available}. - -@item -Individual buffers can no longer display faces specially. The text -scaling commands @kbd{C-x C-+}, @kbd{C-x C--}, and @kbd{C-x C-0} have -been removed, and so has the buffer face menu bound to -@kbd{S-down-mouse-1}. - -@item -VC no longer supports fileset-based operations on distributed version -control systems (DVCSs) such as Arch, Bazaar, Subversion, Mercurial, -and Git. For instance, multi-file commits will be performed by -committing one file at a time. As you go further back in time, we -will remove DVCS support entirely, so you should migrate your projects -to CVS. - -@item -Rmail now uses a special file format, Babyl format, specifically designed -for storing and editing mail. When you visit a file in Rmail, or get new -mail, Rmail converts it automatically to Babyl format. - -@item -Emacs can no longer display frames on X windows and text terminals -(ttys) simultaneously. If you start Emacs as an X application, it -can only create X frames; if you start Emacs on a tty, it can only use -that tty. No more confusion about which type of frame -@command{emacsclient} will use in any given Emacs session! - -@item -Emacs can no longer be started as a daemon. You can be sure that if -you don't see Emacs, then it's not running. - -@item -Emacs has added support for many soon-to-be-non-obsolete platforms, -including VMS, DECstation, SCO Unix, and systems lacking alloca. -Support for Sun windows has been added. - -@item -To keep up with decreasing computer memory capacity and disk space, many -other functions and files have been eliminated in Emacs 22.3. -@end itemize - -@ignore - arch-tag: 32932bd9-46f5-41b2-8a0e-fb0cc4caeb29 -@end ignore diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi deleted file mode 100644 index 94d7dfc3e10..00000000000 --- a/doc/emacs/arevert-xtra.texi +++ /dev/null @@ -1,192 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Autorevert -@section Auto Reverting Non-File Buffers - -Global Auto Revert Mode normally only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: enabling Auto Revert -Mode in those buffers (using @kbd{M-x auto-revert-mode}); and setting -@code{global-auto-revert-non-file-buffers} non-@code{nil}. The latter -enables Auto Reverting for all types of buffers for which it is -implemented (listed in the menu below). - -Like file buffers, non-file buffers should normally not revert while -you are working on them, or while they contain information that might -get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file -buffer should be marked modified is usually more difficult than for -file buffers. - -Another tricky detail is that, for efficiency reasons, Auto Revert -often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling -auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up-to-date, and does not necessarily -make manual reverts useless. - -At the other extreme, certain buffers automatically revert every -@code{auto-revert-interval} seconds. (This currently only applies to -the Buffer Menu.) In this case, Auto Revert does not print any -messages while reverting, even when @code{auto-revert-verbose} is -non-@code{nil}. - -The details depend on the particular types of buffers and are -explained in the corresponding sections. - -@menu -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. -@end menu - -@node Auto Reverting the Buffer Menu -@subsection Auto Reverting the Buffer Menu - -If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) - -If the Buffer Menu inappropriately gets marked modified, just revert -it manually using @kbd{g} and auto-reverting will resume. However, if -you marked certain buffers to get deleted or to be displayed, you have -to be careful, because reverting erases all marks. The fact that -adding marks sets the buffer's modified flag prevents Auto Revert from -automatically erasing the marks. - -@node Auto Reverting Dired -@subsection Auto Reverting Dired buffers - -Auto-reverting Dired buffers currently works on GNU or Unix style -operating systems. It may not work satisfactorily on some other -systems. - -Dired buffers only auto-revert when the file list of the buffer's main -directory changes (e.g. when a new file is added). They do not -auto-revert when information about a particular file changes -(e.g. when the size changes) or when inserted subdirectories change. -To be sure that @emph{all} listed information is up to date, you have -to manually revert using @kbd{g}, @emph{even} if auto-reverting is -enabled in the Dired buffer. Sometimes, you might get the impression -that modifying or saving files listed in the main directory actually -does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself; for -instance, through backup files or auto-save files. However, this is -not guaranteed. - -If the Dired buffer is marked modified and there are no changes you -want to protect, then most of the time you can make auto-reverting -resume by manually reverting the buffer using @kbd{g}. There is one -exception. If you flag or mark files, you can safely revert the -buffer. This will not erase the flags or marks (unless the marked -file has been deleted, of course). However, the buffer will stay -modified, even after reverting, and auto-reverting will not resume. -This is because, if you flag or mark files, you may be working on the -buffer and you might not want the buffer to change without warning. -If you want auto-reverting to resume in the presence of marks and -flags, mark the buffer non-modified using @kbd{M-~}. However, adding, -deleting or changing marks or flags will mark it modified again. - -Remote Dired buffers are not auto-reverted (because it may be slow). -Neither are Dired buffers for which you used shell wildcards or file -arguments to list only some of the files. @samp{*Find*} and -@samp{*Locate*} buffers do not auto-revert either. - -@node Supporting additional buffers -@subsection Adding Support for Auto-Reverting additional Buffers. - -This section is intended for Elisp programmers who would like to add -support for auto-reverting new types of buffers. - -To support auto-reverting the buffer must first of all have a -@code{revert-buffer-function}. @xref{Definition of -revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. - -In addition, it @emph{must} have a @code{buffer-stale-function}. - -@defvar buffer-stale-function -The value of this variable is a function to check whether a non-file -buffer needs reverting. This should be a function with one optional -argument @var{noconfirm}. The function should return non-@code{nil} -if the buffer should be reverted. The buffer is current when this -function is called. - -While this function is mainly intended for use in auto-reverting, it -could be used for other purposes as well. For instance, if -auto-reverting is not enabled, it could be used to warn the user that -the buffer needs reverting. The idea behind the @var{noconfirm} -argument is that it should be @code{t} if the buffer is going to be -reverted without asking the user and @code{nil} if the function is -just going to be used to warn the user that the buffer is out of date. -In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. -If the function is only going to be used for auto-reverting, you can -ignore the @var{noconfirm} argument. - -If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds (like the Buffer Menu), use: - -@example -(set (make-local-variable 'buffer-stale-function) - #'(lambda (&optional noconfirm) 'fast)) -@end example - -@noindent -in the buffer's mode function. - -The special return value @samp{fast} tells the caller that the need -for reverting was not checked, but that reverting the buffer is fast. -It also tells Auto Revert not to print any revert messages, even if -@code{auto-revert-verbose} is non-@code{nil}. This is important, as -getting revert messages every @code{auto-revert-interval} seconds can -be very annoying. The information provided by this return value could -also be useful if the function is consulted for purposes other than -auto-reverting. -@end defvar - -Once the buffer has a @code{revert-buffer-function} and a -@code{buffer-stale-function}, several problems usually remain. - -The buffer will only auto-revert if it is marked unmodified. Hence, -you will have to make sure that various functions mark the buffer -modified if and only if either the buffer contains information that -might be lost by reverting, or there is reason to believe that the user -might be inconvenienced by auto-reverting, because he is actively -working on the buffer. The user can always override this by manually -adjusting the modified status of the buffer. To support this, calling -the @code{revert-buffer-function} on a buffer that is marked -unmodified should always keep the buffer marked unmodified. - -It is important to assure that point does not continuously jump around -as a consequence of auto-reverting. Of course, moving point might be -inevitable if the buffer radically changes. - -You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages, -displayed if @code{auto-revert-verbose} is @code{t}, and effectively -override a @code{nil} value for @code{auto-revert-verbose}. Hence, -adapting a mode for auto-reverting often involves getting rid of such -messages. This is especially important for buffers that automatically -revert every @code{auto-revert-interval} seconds. - -If the new auto-reverting is part of Emacs, you should mention it -in the documentation string of @code{global-auto-revert-non-file-buffers}. - -@ifinfo -Similarly, you should add a node to this chapter's menu. This node -@end ifinfo -@ifnotinfo -Similarly, you should add a section to this chapter. This section -@end ifnotinfo -should at the very least make clear whether enabling auto-reverting -for the buffer reliably assures that all information in the buffer is -completely up to date (or will be after @code{auto-revert-interval} -seconds). - -@ignore - arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e -@end ignore diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi deleted file mode 100644 index 4973b4a96d0..00000000000 --- a/doc/emacs/basic.texi +++ /dev/null @@ -1,724 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Basic, Minibuffer, Exiting, Top -@chapter Basic Editing Commands - -@kindex C-h t -@findex help-with-tutorial - Here we explain the basics of how to enter text, make corrections, -and save the text in a file. If this material is new to you, we -suggest you first run the Emacs learn-by-doing tutorial, by typing -@kbd{Control-h t} inside Emacs. (@code{help-with-tutorial}). - -@menu - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Files: Basic Files. Visiting, creating, and saving files. -* Help: Basic Help. Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What page, line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. -@end menu - -@node Inserting Text -@section Inserting Text - -@cindex insertion -@cindex graphic characters - You can insert an ordinary @dfn{graphic character} (e.g., @samp{a}, -@samp{B}, @samp{3}, and @samp{=}) by typing the associated key. This -adds the character to the buffer at point. Insertion moves point -forward, so that point remains just after the inserted text. -@xref{Point}. - -@kindex RET -@cindex newline - To end a line and start a new one, type @key{RET}. This key may be -labeled @key{Return} or @key{Enter} on your keyboard, but we refer to -it as @key{RET} in this manual. Pressing it inserts a newline -character in the buffer. If point is at the end of the line, this -creates a new blank line after it; if point is in the middle of a -line, the line is split at that position. - - As we explain later in this manual, you can change the way Emacs -handles text insertion by turning on @dfn{minor modes}. For instance, -if you turn on a minor mode called @dfn{Auto Fill} mode, Emacs can -split lines automatically when they become too long (@pxref{Filling}). -If you turn on a minor mode called @dfn{Overwrite} mode, inserted -characters replace (overwrite) existing text, instead of shoving it to -the right. @xref{Minor Modes}. - -@cindex quoting -@kindex C-q -@findex quoted-insert - Only graphic characters can be inserted by typing the associated -key; other keys act as editing commands and do not insert themselves. -For instance, @kbd{DEL} runs the command @code{delete-backward-char} -by default (some modes bind it to a different command); it does not -insert a literal @samp{DEL} character (@acronym{ASCII} character code -127). - - To insert a non-graphic character, or a character that your keyboard -does not support, first @dfn{quote} it by typing @kbd{C-q} -(@code{quoted-insert}). There are two ways to use @kbd{C-q}: - -@itemize @bullet -@item -@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) -inserts that character. For instance, @kbd{C-q @key{DEL}} inserts a -literal @samp{DEL} character. - -@item -@kbd{C-q} followed by a sequence of octal digits inserts the character -with the specified octal character code. You can use any number of -octal digits; any non-digit terminates the sequence. If the -terminating character is @key{RET}, it serves only to terminate the -sequence. Any other non-digit terminates the sequence and then acts -as normal input---thus, @kbd{C-q 1 0 1 B} inserts @samp{AB}. - -The use of octal sequences is disabled in ordinary non-binary -Overwrite mode, to give you a convenient way to insert a digit instead -of overwriting with it. -@end itemize - -@vindex read-quoted-char-radix -@noindent -To use decimal or hexadecimal instead of octal, set the variable -@code{read-quoted-char-radix} to 10 or 16. If the radix is greater -than 10, some letters starting with @kbd{a} serve as part of a -character code, just like digits. - - A numeric argument tells @kbd{C-q} how many copies of the quoted -character to insert (@pxref{Arguments}). - -@findex ucs-insert -@cindex Unicode - Instead of @kbd{C-q}, you can use @kbd{C-x 8 @key{RET}} -(@code{ucs-insert}) to insert a character based on its Unicode name or -code-point. This commands prompts for a character to insert, using -the minibuffer; you can specify the character using either (i) the -character's name in the Unicode standard, or (ii) the character's -code-point in the Unicode standard. - -@node Moving Point -@section Changing the Location of Point - -@cindex arrow keys -@cindex moving point -@cindex movement -@cindex cursor motion -@cindex moving the cursor - To do more than insert characters, you have to know how to move -point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, and @kbd{C-p} move point to the right, left, up and down -respectively. These are equivalent to the commands @kbd{@key{right}}, -@kbd{@key{left}}, @kbd{@key{down}}, and @kbd{@key{up}}, entered using -the @dfn{arrow keys} present on many keyboards. Many Emacs users find -that it is slower to use the arrow keys than the equivalent control -keys. You can also click the left mouse button to move point to the -position clicked. Emacs also provides a variety of additional -keyboard commands that move point in more sophisticated ways. - -@kindex C-a -@kindex C-e -@kindex C-f -@kindex C-b -@kindex C-n -@kindex C-p -@kindex M-> -@kindex M-< -@kindex M-r -@kindex LEFT -@kindex RIGHT -@kindex UP -@kindex DOWN -@findex move-beginning-of-line -@findex move-end-of-line -@findex forward-char -@findex backward-char -@findex next-line -@findex previous-line -@findex beginning-of-buffer -@findex end-of-buffer -@findex goto-char -@findex goto-line -@findex move-to-window-line -@table @kbd -@item C-a -@itemx @key{Home} -Move to the beginning of the line (@code{move-beginning-of-line}). -@item C-e -@itemx @key{End} -Move to the end of the line (@code{move-end-of-line}). -@item C-f -@itemx @key{right} -Move forward one character (@code{forward-char}). -@item C-b -@itemx @key{left} -Move backward one character (@code{backward-char}). -@item M-f -@itemx M-@key{right} -@itemx C-@key{right} -Move forward one word (@code{forward-word}). -@item M-b -@itemx M-@key{left} -@itemx C-@key{left} -Move backward one word (@code{backward-word}). -@item C-n -@itemx @key{down} -Move down one screen line (@code{next-line}). This command attempts -to keep the horizontal position unchanged, so if you start in the -middle of one line, you move to the middle of the next. -@item C-p -@itemx @key{up} -Move up one screen line (@code{previous-line}). This command -preserves position within the line, like @kbd{C-n}. -@item M-r -Move point to left margin, vertically centered in the window -(@code{move-to-window-line}). Text does not move on the screen. -A numeric argument says which screen line to place point on, counting -downward from the top of the window (zero means the top line). A -negative argument counts lines up from the bottom (@minus{}1 means the -bottom line). -@item M-< -Move to the top of the buffer (@code{beginning-of-buffer}). With -numeric argument @var{n}, move to @var{n}/10 of the way from the top. -@xref{Arguments}, for more information on numeric arguments.@refill -@item M-> -Move to the end of the buffer (@code{end-of-buffer}). -@item C-v -@itemx @key{PageDown} -@itemx @key{next} -Scroll the display one screen forward, and move point if necessary to -put it on the screen (@code{scroll-up}). If your keyboard has a -@key{PageDown} key (sometimes labelled @key{next}), it does the same -thing as @key{C-v}. Scrolling commands are described further in -@ref{Scrolling}. -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Scroll one screen backward, and move point if necessary to put it on -the screen (@code{scroll-down}). If your keyboard has a @key{PageUp} -key (sometimes labelled @key{prior}), it does the same thing as -@kbd{M-v}. -@item M-x goto-char -Read a number @var{n} and move point to buffer position @var{n}. -Position 1 is the beginning of the buffer. -@item M-g M-g -@itemx M-g g -Read a number @var{n} and move point to the beginning of line number -@var{n} (@code{goto-line}). Line 1 is the beginning of the buffer. If -point is on or just after a number in the buffer, that is the default -for @var{n}. Just type @key{RET} in the minibuffer to use it. You can -also specify @var{n} by giving @kbd{M-g M-g} a numeric prefix argument. -@xref{Select Buffer}, for the behavior of @kbd{M-g M-g} when you give it -a plain prefix argument. -@item C-x C-n -@findex set-goal-column -@kindex C-x C-n -Use the current column of point as the @dfn{semipermanent goal column} -for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). When a -semipermanent goal column is in effect, those commands always try to -move to this column, or as close as possible to it, after moving -vertically. The goal column remains in effect until canceled. -@item C-u C-x C-n -Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to -preserve the horizontal position, as usual. -@end table - -@vindex line-move-visual - When a line of text in the buffer is longer than the width of the -window, Emacs usually displays it on two or more @dfn{screen lines}. -For convenience, @kbd{C-n} and @kbd{C-p} move point by screen lines, -as do the equivalent keys @kbd{@key{down}} and @kbd{@key{up}}. You -can force these commands to move according to @dfn{logical lines} -(i.e., according to the text lines in the buffer) by setting the -variable @code{line-move-visual} to @code{nil}; if a logical line -occupies multiple screen lines, the cursor then skips over the -additional screen lines. Moving by logical lines was the default -behavior prior to Emacs 23.1. For details, see @ref{Continuation -Lines}. @xref{Variables}, for how to set variables such as -@code{line-move-visual}. - - Unlike @kbd{C-n} and @kbd{C-p}, most of the Emacs commands that work -on lines work on @emph{logical} lines. For instance, @kbd{C-a} -(@code{move-beginning-of-line}) and @kbd{C-e} -(@code{move-end-of-line}) respectively move to the beginning and end -of the logical line. Whenever we encounter commands that work on -screen lines, such as @kbd{C-n} and @kbd{C-p}, we will point these -out. - -@vindex track-eol - When @code{line-move-visual} is @code{nil}, you can also set the -variable @code{track-eol} to a non-@code{nil} value. Then @kbd{C-n} -and @kbd{C-p}, when starting at the end of the logical line, move to -the end of the next logical line. Normally, @code{track-eol} is -@code{nil}. - -@vindex next-line-add-newlines - @kbd{C-n} normally stops at the end of the buffer when you use it on -the last line of the buffer. However, if you set the variable -@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on -the last line of a buffer creates an additional line at the end and -moves down into it. - -@node Erasing -@section Erasing Text - -@table @kbd -@item @key{DEL} -@itemx @key{Backspace} -Delete the character before point (@code{delete-backward-char}). -@item C-d -@itemx @key{Delete} -Delete the character after point (@code{delete-char}). -@item C-k -Kill to the end of the line (@code{kill-line}). -@item M-d -Kill forward to the end of the next word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of the previous word -(@code{backward-kill-word}). -@end table - - The key @kbd{@key{DEL}} (@code{delete-backward-char}) removes the -character before point, moving the cursor and all the characters after -it backwards. On most keyboards, @key{DEL} is labelled -@key{Backspace}, but we refer to it as @key{DEL} in this manual. Do -not confuse @key{DEL} with another key, labelled @key{Delete}, that -exists on many keyboards; we will discuss @key{Delete} momentarily. - - Typing @key{DEL} when the cursor is at the beginning of a line -deletes the preceding newline character, joining the line with the one -before it. - - On some text-only terminals, Emacs may not recognize the @key{DEL} -key properly. If @key{DEL} does not do the right thing (e.g., if it -deletes characters forwards), see @ref{DEL Does Not Delete}. - -@cindex killing characters and lines -@cindex deleting characters and lines -@cindex erasing characters and lines - The key @kbd{C-d} (@code{delete-char}) deletes the character after -point, i.e., the character under the cursor. This shifts the rest of -the text on the line to the left. If you type @kbd{C-d} at the end of -a line, it joins that line with the following line. This command is -also bound to the key labelled @key{Delete} on many keyboards. - - To erase a larger amount of text, use the @kbd{C-k} key, which -erases (kills) a line at a time. If you type @kbd{C-k} at the -beginning or middle of a line, it kills all the text up to the end of -the line. If you type @kbd{C-k} at the end of a line, it joins that -line with the following line. - - To learn more about killing text, see @ref{Killing}. - -@node Basic Undo -@section Undoing Changes - -@table @kbd -@item C-/ -Undo one entry of the undo records---usually, one command worth -(@code{undo}). -@itemx C-x u -@item C-_ -The same. -@end table - - Emacs records a list of changes made in the buffer text, so you can -undo recent changes. This is done using the @code{undo} command, -which is bound to @kbd{C-/} (as well as @kbd{C-x u} and @kbd{C-_}). -Normally, this command undoes the last change, moving point back to -where it was before the change. The undo command applies only to -changes in the buffer; you can't use it to undo cursor motion. - - Although each editing command usually makes a separate entry in the -undo records, very simple commands may be grouped together. -Sometimes, an entry may cover just part of a complex command. - - If you repeat @kbd{C-/} (or its aliases), each repetition undoes -another, earlier change, back to the limit of the undo information -available. If all recorded changes have already been undone, the undo -command displays an error message and does nothing. - - To learn more about the @code{undo} command, see @ref{Undo}. - -@node Basic Files -@section Files - - Text that you insert in an Emacs buffer lasts only as long as the -Emacs session. To keep any text permanently, you must put it in a -@dfn{file}. Files are named units of text which are stored by the -operating system for you to retrieve later by name. To use the -contents of a file in any way, including editing it with Emacs, you -must specify the file name. - - Suppose there is a file named @file{test.emacs} in your home -directory. To begin editing this file in Emacs, type - -@example -C-x C-f test.emacs @key{RET} -@end example - -@noindent -Here the file name is given as an @dfn{argument} to the command @kbd{C-x -C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to -read the argument, and you type @key{RET} to terminate the argument -(@pxref{Minibuffer}). - - Emacs obeys this command by @dfn{visiting} the file: it creates a -buffer, copies the contents of the file into the buffer, and then -displays the buffer for editing. If you alter the text, you can -@dfn{save} the new text in the file by typing @kbd{C-x C-s} -(@code{save-buffer}). This copies the altered buffer contents back -into the file @file{test.emacs}, making them permanent. Until you -save, the changed text exists only inside Emacs, and the file -@file{test.emacs} is unaltered. - - To create a file, just visit it with @kbd{C-x C-f} as if it already -existed. This creates an empty buffer, in which you can insert the -text you want to put in the file. Emacs actually creates the file the -first time you save this buffer with @kbd{C-x C-s}. - - To learn more about using files in Emacs, see @ref{Files}. - -@node Basic Help -@section Help - -@cindex getting help with keys - If you forget what a key does, you can find out with the Help -character, which is @kbd{C-h} (or @key{F1}, which is an alias for -@kbd{C-h}). Type @kbd{C-h k}, followed by the key of interest; for -example, @kbd{C-h k C-n} tells you what @kbd{C-n} does. @kbd{C-h} is -a prefix key; @kbd{C-h k} is just one of its subcommands (the command -@code{describe-key}). The other subcommands of @kbd{C-h} provide -different kinds of help. Type @kbd{C-h} twice to get a description of -all the help facilities. @xref{Help}. - -@node Blank Lines -@section Blank Lines - -@cindex inserting blank lines -@cindex deleting blank lines - Here are special commands and techniques for inserting and deleting -blank lines. - -@table @kbd -@item C-o -Insert a blank line after the cursor (@code{open-line}). -@item C-x C-o -Delete all but one of many consecutive blank lines -(@code{delete-blank-lines}). -@end table - -@kindex C-o -@kindex C-x C-o -@cindex blank lines -@findex open-line -@findex delete-blank-lines - We have seen how @kbd{@key{RET}} (@code{newline}) starts a new line -of text. However, it may be easier to see what you are doing if you -first make a blank line and then insert the desired text into it. -This is easy to do using the key @kbd{C-o} (@code{open-line}), which -inserts a newline after point but leaves point in front of the -newline. After @kbd{C-o}, type the text for the new line. - - You can make several blank lines by typing @kbd{C-o} several times, or -by giving it a numeric argument specifying how many blank lines to make. -@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} -command inserts the fill prefix on the new line, if typed at the -beginning of a line. @xref{Fill Prefix}. - - The easy way to get rid of extra blank lines is with the command -@kbd{C-x C-o} (@code{delete-blank-lines}). If point lies within a run -of several blank lines, @kbd{C-x C-o} deletes all but one of them. If -point is on a single blank line, @kbd{C-x C-o} deletes it. If point -is on a nonblank line, @kbd{C-x C-o} deletes all following blank -lines, if any exists. - -@node Continuation Lines -@section Continuation Lines - -@cindex continuation line -@cindex wrapping -@cindex line wrapping -@cindex fringes, and continuation lines - Sometimes, a line of text in the buffer---a @dfn{logical line}---is -too long to fit in the window, and Emacs displays it as two or more -@dfn{screen lines}. This is called @dfn{line wrapping} or -@dfn{continuation}, and the long logical line is called a -@dfn{continued line}. On a graphical display, Emacs indicates line -wrapping with small bent arrows in the left and right window fringes. -On a text-only terminal, Emacs indicates line wrapping by displaying a -@samp{\} character at the right margin. - - Most commands that act on lines act on logical lines, not screen -lines. For instance, @kbd{C-k} kills a logical line. As described -earlier, @kbd{C-n} (@code{next-line}) and @kbd{C-p} -(@code{previous-line}) are special exceptions: they move point down -and up, respectively, by one screen line (@pxref{Moving Point}). - -@cindex truncation -@cindex line truncation, and fringes - Emacs can optionally @dfn{truncate} long logical lines instead of -continuing them. This means that every logical line occupies a single -screen line; if it is longer than the width of the window, the rest of -the line is not displayed. On a graphical display, a truncated line -is indicated by a small straight arrow in the right fringe; on a -text-only terminal, it is indicated by a @samp{$} character in the -right margin. @xref{Line Truncation}. - - By default, continued lines are wrapped at the right window edge. -Since the wrapping may occur in the middle of a word, continued lines -can be difficult to read. The usual solution is to break your lines -before they get too long, by inserting newlines. If you prefer, you -can make Emacs insert a newline automatically when a line gets too -long, by using Auto Fill mode. @xref{Filling}. - -@cindex word wrap - Sometimes, you may need to edit files containing many long logical -lines, and it may not be practical to break them all up by adding -newlines. In that case, you can use Visual Line mode, which enables -@dfn{word wrapping}: instead of wrapping long lines exactly at the -right window edge, Emacs wraps them at the word boundaries (i.e., -space or tab characters) nearest to the right window edge. Visual -Line mode also redefines editing commands such as @code{C-a}, -@code{C-n}, and @code{C-k} to operate on screen lines rather than -logical lines. @xref{Visual Line Mode}. - -@node Position Info -@section Cursor Position Information - - Here are commands to get information about the size and position of -parts of the buffer, and to count lines. - -@table @kbd -@item M-x what-page -Display the page number of point, and the line number within that page. -@item M-x what-line -Display the line number of point in the whole buffer. -@item M-x line-number-mode -@itemx M-x column-number-mode -Toggle automatic display of the current line number or column number. -@xref{Optional Mode Line}. -@item M-x count-lines-region -Display the number of lines in the current region. Normally bound to -@kbd{M-=}, except in a few specialist modes. @xref{Mark}, for -information about the region. -@item C-x = -Display the character code of character after point, character position of -point, and column of point (@code{what-cursor-position}). -@item M-x hl-line-mode -Enable or disable highlighting of the current line. @xref{Cursor -Display}. -@item M-x size-indication-mode -Toggle automatic display of the size of the buffer. -@xref{Optional Mode Line}. -@end table - -@findex what-page -@findex what-line -@cindex line number commands -@cindex location of point -@cindex cursor location -@cindex point location - @kbd{M-x what-line} displays the current line number in the echo -area. This command is usually redundant, because the current line -number is shown in the mode line (@pxref{Mode Line}). However, if you -narrow the buffer, the mode line shows the line number relative to -the accessible portion (@pxref{Narrowing}). By contrast, -@code{what-line} displays both the line number relative to the -narrowed region and the line number relative to the whole buffer. - - @kbd{M-x what-page} counts pages from the beginning of the file, and -counts lines within the page, showing both numbers in the echo area. -@xref{Pages}. - -@kindex M-= -@findex count-lines-region - Use @kbd{M-x count-lines-region} (normally bound to @kbd{M-=}) to -display the number of lines in the region (@pxref{Mark}). @xref{Pages}, -for the command @kbd{C-x l} which counts the lines in the current page. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the current cursor position and the buffer contents -at that position. It displays a line in the echo area that looks like -this: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - After @samp{Char:}, this shows the character in the buffer at point. -The text inside the parenthesis shows the corresponding decimal, octal -and hex character codes; for more information about how @kbd{C-x =} -displays character information, see @ref{International Chars}. After -@samp{point=} is the position of point as a character count (the first -character in the buffer is position 1, the second character is -position 2, and so on). The number after that is the total number of -characters in the buffer, and the number in parenthesis expresses the -position as a percentage of the total. After @samp{column=} is the -horizontal position of point, in columns counting from the left edge -of the window. - - If the buffer has been narrowed, making some of the text at the -beginning and the end temporarily inaccessible, @kbd{C-x =} displays -additional text describing the currently accessible range. For -example, it might display this: - -@smallexample -Char: C (67, #o103, #x43) point=252 of 889 (28%) <231-599> column=0 -@end smallexample - -@noindent -where the two extra numbers give the smallest and largest character -position that point is allowed to assume. The characters between -those two positions are the accessible ones. @xref{Narrowing}. - -@node Arguments -@section Numeric Arguments -@cindex numeric arguments -@cindex prefix arguments -@cindex arguments to commands - - In the terminology of mathematics and computing, @dfn{argument} -means ``data provided to a function or operation.'' You can give any -Emacs command a @dfn{numeric argument} (also called a @dfn{prefix -argument}). Some commands interpret the argument as a repetition -count. For example, giving @kbd{C-f} an argument of ten causes it to -move point forward by ten characters instead of one. With these -commands, no argument is equivalent to an argument of one, and -negative arguments cause them to move or act in the opposite -direction. - -@kindex M-1 -@kindex M-@t{-} -@findex digit-argument -@findex negative-argument - The easiest way to specify a numeric argument is to type a digit -and/or a minus sign while holding down the @key{META} key. For -example, - -@example -M-5 C-n -@end example - -@noindent -moves down five lines. The keys @kbd{M-1}, @kbd{M-2}, and so on, as -well as @kbd{M--}, are bound to commands (@code{digit-argument} and -@code{negative-argument}) that set up an argument for the next -command. @kbd{Meta--} without digits normally means @minus{}1. - -If you enter more than one digit, you need not hold down the -@key{META} key for the second and subsequent digits. Thus, to move -down fifty lines, type - -@example -M-5 0 C-n -@end example - -@noindent -Note that this @emph{does not} insert five copies of @samp{0} and move -down one line, as you might expect---the @samp{0} is treated as part -of the prefix argument. - -(What if you do want to insert five copies of @samp{0}? Type @kbd{M-5 -C-u 0}. Here, @kbd{C-u} ``terminates'' the prefix argument, so that -the next keystroke begins the command that you want to execute. Note -that this meaning of @kbd{C-u} applies only to this case. For the -usual role of @kbd{C-u}, see below.) - -@kindex C-u -@findex universal-argument - Instead of typing @kbd{M-1}, @kbd{M-2}, and so on, another way to -specify a numeric argument is to type @kbd{C-u} -(@code{universal-argument}) followed by some digits, or (for a -negative argument) a minus sign followed by digits. A minus sign -without digits normally means @minus{}1. - - @kbd{C-u} alone has the special meaning of ``four times'': it -multiplies the argument for the next command by four. @kbd{C-u C-u} -multiplies it by sixteen. Thus, @kbd{C-u C-u C-f} moves forward -sixteen characters. Other useful combinations are @kbd{C-u C-n}, -@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u -C-u C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four -lines). - - You can use a numeric argument before a self-inserting character to -insert multiple copies of it. This is straightforward when the -character is not a digit; for example, @kbd{C-u 6 4 a} inserts 64 -copies of the character @samp{a}. But this does not work for -inserting digits; @kbd{C-u 6 4 1} specifies an argument of 641. You -can separate the argument from the digit to insert with another -@kbd{C-u}; for example, @kbd{C-u 6 4 C-u 1} does insert 64 copies of -the character @samp{1}. - - Some commands care whether there is an argument, but ignore its -value. For example, the command @kbd{M-q} (@code{fill-paragraph}) -fills text; with an argument, it justifies the text as well. -(@xref{Filling}, for more information on @kbd{M-q}.) For these -commands, it is enough to the argument with a single @kbd{C-u}. - - Some commands use the value of the argument as a repeat count, but -do something special when there is no argument. For example, the -command @kbd{C-k} (@code{kill-line}) with argument @var{n} kills -@var{n} lines, including their terminating newlines. But @kbd{C-k} -with no argument is special: it kills the text up to the next newline, -or, if point is right at the end of the line, it kills the newline -itself. Thus, two @kbd{C-k} commands with no arguments can kill a -nonblank line, just like @kbd{C-k} with an argument of one. -(@xref{Killing}, for more information on @kbd{C-k}.) - - A few commands treat a plain @kbd{C-u} differently from an ordinary -argument. A few others may treat an argument of just a minus sign -differently from an argument of @minus{}1. These unusual cases are -described when they come up; they exist to make an individual command -more convenient, and they are documented in that command's -documentation string. - - We use the term ``prefix argument'' as well as ``numeric argument,'' -to emphasize that you type these argument before the command, and to -distinguish them from minibuffer arguments that come after the -command. - -@node Repeating -@section Repeating a Command -@cindex repeating a command - - Many simple commands, such as those invoked with a single key or -with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by -invoking them with a numeric argument that serves as a repeat count -(@pxref{Arguments}). However, if the command you want to repeat -prompts for input, or uses a numeric argument in another way, that -method won't work. - -@kindex C-x z -@findex repeat - The command @kbd{C-x z} (@code{repeat}) provides another way to repeat -an Emacs command many times. This command repeats the previous Emacs -command, whatever that was. Repeating a command uses the same arguments -that were used before; it does not read new arguments each time. - - To repeat the command more than once, type additional @kbd{z}'s: each -@kbd{z} repeats the command one more time. Repetition ends when you -type a character other than @kbd{z}, or press a mouse button. - - For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 -characters. You can repeat that command (including its argument) three -additional times, to delete a total of 80 characters, by typing @kbd{C-x -z z z}. The first @kbd{C-x z} repeats the command once, and each -subsequent @kbd{z} repeats it once again. - -@ignore - arch-tag: cda8952a-c439-41c1-aecf-4bc0d6482956 -@end ignore diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi deleted file mode 100644 index 848d1333a3c..00000000000 --- a/doc/emacs/buffers.texi +++ /dev/null @@ -1,678 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Buffers, Windows, Files, Top -@chapter Using Multiple Buffers - -@cindex buffers - The text you are editing in Emacs resides in an object called a -@dfn{buffer}. Each time you visit a file, a buffer is created to hold the -file's text. Each time you invoke Dired, a buffer is created to hold the -directory listing. If you send a message with @kbd{C-x m}, a buffer named -@samp{*mail*} is used to hold the text of the message. When you ask for a -command's documentation, that appears in a buffer called @samp{*Help*}. - - Each buffer has a unique name, which can be of any length. When a -buffer is displayed in a window, its name is shown in the mode line -(@pxref{Mode Line}). The distinction between upper and lower case -matters in buffer names. Most buffers are made by visiting files, and -their names are derived from the files' names; however, you can also -create an empty buffer with any name you want. A newly started Emacs -has a buffer named @samp{*scratch*}, which is not associated with any -file and can be used for evaluating Lisp expressions in Emacs -(@pxref{Lisp Interaction}). - -@cindex selected buffer -@cindex current buffer - At any time, one and only one buffer is @dfn{current}. This is also -called the @dfn{selected buffer}. We often say that a command -operates on ``the buffer''; this really means that the command -operates on the current buffer (most commands do). When there is only -one Emacs window, the buffer displayed in that window is current. -When there are multiple windows present, the buffer displayed in the -@dfn{selected window} is current. @xref{Windows}. - - Each buffer records individually what file it is visiting (if any), -whether it is modified, and what major mode and minor modes are in -effect (@pxref{Major Modes}). Any Emacs variable can be made -@dfn{local to} a particular buffer, meaning its value in that buffer -can be different from the value in other buffers. @xref{Locals}. - -@cindex buffer size, maximum - A buffer's size cannot be larger than some maximum, which is defined -by the largest buffer position representable by the @dfn{Emacs integer} -data type. This is because Emacs tracks buffer positions using that -data type. For 32-bit machines, the largest buffer size is 256 -megabytes. - -@menu -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. -@end menu - -@node Select Buffer -@section Creating and Selecting Buffers -@cindex change buffers -@cindex switch buffers - -@table @kbd -@item C-x b @var{buffer} @key{RET} -Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). -@item C-x 4 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in another window -(@code{switch-to-buffer-other-window}). -@item C-x 5 b @var{buffer} @key{RET} -Similar, but select @var{buffer} in a separate frame -(@code{switch-to-buffer-other-frame}). -@item C-x @key{LEFT} -Select the previous buffer in the list of existing buffers. -@item C-x @key{RIGHT} -Select the next buffer in the list of existing buffers. -@item C-u M-g M-g -@itemx C-u M-g g -Read a number @var{n} and move to line @var{n} in the most recently -selected buffer other than the current buffer. -@end table - -@kindex C-x b -@findex switch-to-buffer - To select the buffer named @var{bufname}, type @kbd{C-x b -@var{bufname} @key{RET}}. This runs the command -@code{switch-to-buffer} with argument @var{bufname}. While entering -the buffer name, you can use the usual minibuffer completion and -history commands (@pxref{Minibuffer}). An empty argument to @kbd{C-x -b} specifies the buffer that was current most recently among those not -now displayed in any window. - -@cindex minibuffer confirmation -@cindex confirming in the minibuffer - If you specify a buffer that does not exist, @kbd{C-x b} creates a -new, empty buffer that is not visiting any file, and selects it for -editing. First, however, Emacs might prompt you for confirmation, in -case you entered the wrong buffer name. Emacs asks for confirmation -only if the last key you typed, before submitting the minibuffer input -with @key{RET}, was @key{TAB} (@code{minibuffer-complete}). This -catches a common mistake, in which one types @key{RET} before -realizing that @key{TAB} did not complete far enough to yield the -desired buffer name (@pxref{Completion}). Emacs asks for confirmation -by putting the message @samp{[Confirm]} in the minibuffer; type -@key{RET} again to confirm and visit the buffer. - -@vindex confirm-nonexistent-file-or-buffer - The variable @code{confirm-nonexistent-file-or-buffer} controls -whether Emacs asks for confirmation before visiting a buffer that did -not previously exist. The default value, @code{after-completion}, -gives the behavior we have just described. If the value is -@code{nil}, Emacs never asks for confirmation; for any other -non-@code{nil} value, Emacs always asks for confirmation. This -variable also affects the @code{find-file} command (@pxref{Visiting}). - - One reason to create a new buffer is to use it for making temporary -notes. If you try to save it, Emacs asks for the file name to use. -The variable @code{default-major-mode} determines the new buffer's -major mode; the default value is Fundamental mode. @xref{Major -Modes}. - -@kindex C-x @key{LEFT} -@kindex C-x @key{RIGHT} -@findex next-buffer -@findex previous-buffer - For conveniently switching between a few buffers, use the commands -@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}} -(@code{previous-buffer}) selects the previous buffer (following the order -of most recent selection in the current frame), while @kbd{C-x @key{LEFT}} -(@code{next-buffer}) moves through buffers in the reverse direction. - -@kindex C-x 4 b -@findex switch-to-buffer-other-window -@vindex even-window-heights - To select a buffer in a window other than the current one, type -@kbd{C-x 4 b} (@code{switch-to-buffer-other-window}). This prompts -for a buffer name using the minibuffer, displays that buffer in -another window, and selects that window. By default, if displaying -the buffer causes two vertically adjacent windows to be displayed, the -heights of those windows are evened out; to countermand that and -preserve the window configuration, set the variable -@code{even-window-heights} to @code{nil}. - -@kindex C-x 5 b -@findex switch-to-buffer-other-frame - Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame}) -prompts for a buffer name, displays that buffer in another frame, and -selects that frame. - - In addition, @kbd{C-x C-f}, and any other command for visiting a -file, can also be used to switch to an existing file-visiting buffer. -@xref{Visiting}. - -@vindex display-buffer-reuse-frames - You can control how certain buffers are handled by these commands by -customizing the variables @code{special-display-buffer-names}, -@code{special-display-regexps}, @code{same-window-buffer-names}, and -@code{same-window-regexps}. See @ref{Force Same Window}, and -@ref{Special Buffer Frames}, for more about these variables. In -addition, if the value of @code{display-buffer-reuse-frames} is -non-@code{nil}, and the buffer you want to switch to is already -displayed in some frame, Emacs will just raise that frame. - -@findex goto-line - @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix -argument, reads a number @var{n} using the minibuffer, selects the -most recently selected buffer other than the current buffer in another -window, and then moves point to the beginning of line number @var{n} -in that buffer. This is mainly useful in a buffer that refers to line -numbers in another buffer: if point is on or just after a number, -@code{goto-line} uses that number as the default for @var{n}. Note -that prefix arguments other than just @kbd{C-u} behave differently. -@kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} buffer, -without reading a number from the minibuffer. (Remember that @kbd{M-g -M-g} without prefix argument reads a number @var{n} and then moves to -line number @var{n} in the current buffer. @xref{Moving Point}.) - - Emacs uses buffer names that start with a space for internal purposes. -It treats these buffers specially in minor ways---for example, by -default they do not record undo information. It is best to avoid using -such buffer names yourself. - -@node List Buffers -@section Listing Existing Buffers - -@table @kbd -@item C-x C-b -List the existing buffers (@code{list-buffers}). -@end table - -@cindex listing current buffers -@kindex C-x C-b -@findex list-buffers - To display a list of existing buffers, type @kbd{C-x C-b}. Each -line in the list shows one buffer's name, major mode and visited file. -The buffers are listed in the order that they were current; the -buffers that were current most recently come first. - - @samp{.} in the first field of a line indicates that the buffer is -current. @samp{%} indicates a read-only buffer. @samp{*} indicates -that the buffer is ``modified.'' If several buffers are modified, it -may be time to save some with @kbd{C-x s} (@pxref{Save Commands}). -Here is an example of a buffer list: - -@smallexample -CRM Buffer Size Mode File -. * .emacs 3294 Emacs-Lisp ~/.emacs - % *Help* 101 Help - search.c 86055 C ~/cvs/emacs/src/search.c - % src 20959 Dired by name ~/cvs/emacs/src/ - * *mail* 42 Mail - % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO - % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS - *scratch* 191 Lisp Interaction - * *Messages* 1554 Fundamental -@end smallexample - -@noindent -The buffer @samp{*Help*} was made by a help request (@pxref{Help}); it -is not visiting any file. The buffer @code{src} was made by Dired on -the directory @file{~/cvs/emacs/src/}. You can list only buffers that -are visiting files by giving the command a prefix argument, as in -@kbd{C-u C-x C-b}. - - @code{list-buffers} omits buffers whose names begin with a space, -unless they visit files: such buffers are used internally by Emacs. - -@node Misc Buffer -@section Miscellaneous Buffer Operations - -@table @kbd -@item C-x C-q -Toggle read-only status of buffer (@code{toggle-read-only}). -@item M-x rename-buffer @key{RET} @var{name} @key{RET} -Change the name of the current buffer. -@item M-x rename-uniquely -Rename the current buffer by adding @samp{<@var{number}>} to the end. -@item M-x view-buffer @key{RET} @var{buffer} @key{RET} -Scroll through buffer @var{buffer}. -@end table - -@kindex C-x C-q -@vindex buffer-read-only -@cindex read-only buffer - A buffer can be @dfn{read-only}, which means that commands to change -its contents are not allowed. The mode line indicates read-only -buffers with @samp{%%} or @samp{%*} near the left margin. Read-only -buffers are usually made by subsystems such as Dired and Rmail that -have special commands to operate on the text; also by visiting a file -whose access control says you cannot write it. - -@findex toggle-read-only - If you wish to make changes in a read-only buffer, use the command -@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer -writable, and makes a writable buffer read-only. This -works by setting the variable @code{buffer-read-only}, which has a local -value in each buffer and makes the buffer read-only if its value is -non-@code{nil}. If you have files under version control, you may find -it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only} -instead. This will guard you against an operation that will confuse -most modern version-conmtrol systems. @xref{Version Control}. - -@findex rename-buffer - @kbd{M-x rename-buffer} changes the name of the current buffer. You -specify the new name as a minibuffer argument; there is no default. -If you specify a name that is in use for some other buffer, an error -happens and no renaming is done. - -@findex rename-uniquely - @kbd{M-x rename-uniquely} renames the current buffer to a similar -name with a numeric suffix added to make it both different and unique. -This command does not need an argument. It is useful for creating -multiple shell buffers: if you rename the @samp{*shell*} buffer, then -do @kbd{M-x shell} again, it makes a new shell buffer named -@samp{*shell*}; meanwhile, the old shell buffer continues to exist -under its new name. This method is also good for mail buffers, -compilation buffers, and most Emacs features that create special -buffers with particular names. (With some of these features, such as -@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to -switch to some other buffer before using the command, in order for it -to make a different buffer.) - -@findex view-buffer - @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc -File Ops}) except that it examines an already existing Emacs buffer. -View mode provides commands for scrolling through the buffer -conveniently but not for changing it. When you exit View mode with -@kbd{q}, that switches back to the buffer (and the position) which was -previously displayed in the window. Alternatively, if you exit View -mode with @kbd{e}, the buffer and the value of point that resulted from -your perusal remain in effect. - - The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} -can be used to copy text from one buffer to another. @xref{Accumulating -Text}. - -@node Kill Buffer -@section Killing Buffers - -@cindex killing buffers - If you continue an Emacs session for a while, you may accumulate a -large number of buffers. You may then find it convenient to @dfn{kill} -the buffers you no longer need. On most operating systems, killing a -buffer releases its space back to the operating system so that other -programs can use it. Here are some commands for killing buffers: - -@table @kbd -@item C-x k @var{bufname} @key{RET} -Kill buffer @var{bufname} (@code{kill-buffer}). -@item M-x kill-some-buffers -Offer to kill each buffer, one by one. -@item M-x kill-matching-buffers -Offer to kill all buffers matching a regular expression. -@end table - -@findex kill-buffer -@kindex C-x k - @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you -specify in the minibuffer. The default, used if you type just -@key{RET} in the minibuffer, is to kill the current buffer. If you -kill the current buffer, another buffer becomes current: one that was -current in the recent past but is not displayed in any window now. If -you ask to kill a file-visiting buffer that is modified, then you must -confirm with @kbd{yes} before the buffer is killed. - -@findex kill-some-buffers - The command @kbd{M-x kill-some-buffers} asks about each buffer, one -by one. An answer of @kbd{y} means to kill the buffer, just like -@code{kill-buffer}. This command ignores buffers whose names begin -with a space, which are used internally by Emacs. - -@findex kill-matching-buffers - The command @kbd{M-x kill-matching-buffers} prompts for a regular -expression and kills all buffers whose names match that expression. -@xref{Regexps}. Like @code{kill-some-buffers}, it asks for -confirmation before each kill. This command normally ignores buffers -whose names begin with a space, which are used internally by Emacs. -To kill internal buffers as well, call @code{kill-matching-buffers} -with a prefix argument. - - The buffer menu feature is also convenient for killing various -buffers. @xref{Several Buffers}. - -@vindex kill-buffer-hook - If you want to do something special every time a buffer is killed, you -can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). - -@findex clean-buffer-list - If you run one Emacs session for a period of days, as many people do, -it can fill up with buffers that you used several days ago. The command -@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills -all the unmodified buffers that you have not used for a long time. An -ordinary buffer is killed if it has not been displayed for three days; -however, you can specify certain buffers that should never be killed -automatically, and others that should be killed if they have been unused -for a mere hour. - -@cindex Midnight mode -@vindex midnight-mode -@vindex midnight-hook - You can also have this buffer purging done for you, every day at -midnight, by enabling Midnight mode. Midnight mode operates each day -at midnight; at that time, it runs @code{clean-buffer-list}, or -whichever functions you have placed in the normal hook -@code{midnight-hook} (@pxref{Hooks}). To enable Midnight mode, use -the Customization buffer to set the variable @code{midnight-mode} to -@code{t}. @xref{Easy Customization}. - -@node Several Buffers -@section Operating on Several Buffers -@cindex buffer menu - -@table @kbd -@item M-x buffer-menu -Begin editing a buffer listing all Emacs buffers. -@item M-x buffer-menu-other-window. -Similar, but do it in another window. -@end table - - The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers}) -does not merely list buffers. It also allows you to perform various -operations on buffers, through an interface similar to Dired -(@pxref{Dired}). You can save buffers, kill them (here called -@dfn{deleting} them, for consistency with Dired), or display them. - -@findex buffer-menu -@findex buffer-menu-other-window - To use the buffer menu, type @kbd{C-x C-b} and switch to the window -displaying the @samp{*Buffer List*} buffer. You can also type -@kbd{M-x buffer-menu} to open the buffer menu in the selected window. -Alternatively, the command @kbd{M-x buffer-menu-other-window} opens -the buffer menu in another window, and selects that window. - - The buffer menu is a read-only buffer, and can be changed only -through the special commands described in this section. The usual -Emacs cursor motion commands can be used in this buffer. The -following commands apply to the buffer described on the current line: - -@table @kbd -@item d -Request to delete (kill) the buffer, then move down. The request -shows as a @samp{D} on the line, before the buffer name. Requested -deletions take place when you type the @kbd{x} command. -@item C-d -Like @kbd{d} but move up afterwards instead of down. -@item s -Request to save the buffer. The request shows as an @samp{S} on the -line. Requested saves take place when you type the @kbd{x} command. -You may request both saving and deletion for the same buffer. -@item x -Perform previously requested deletions and saves. -@item u -Remove any request made for the current line, and move down. -@item @key{DEL} -Move to previous line and remove any request made for that line. -@end table - - The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove -flags also move down (or up) one line. They accept a numeric argument -as a repeat count. - - These commands operate immediately on the buffer listed on the current -line: - -@table @kbd -@item ~ -Mark the buffer ``unmodified.'' The command @kbd{~} does this -immediately when you type it. -@item % -Toggle the buffer's read-only flag. The command @kbd{%} does -this immediately when you type it. -@item t -Visit the buffer as a tags table. @xref{Select Tags Table}. -@end table - - There are also commands to select another buffer or buffers: - -@table @kbd -@item q -Quit the buffer menu---immediately display the most recent formerly -visible buffer in its place. -@item @key{RET} -@itemx f -Immediately select this line's buffer in place of the @samp{*Buffer -List*} buffer. -@item o -Immediately select this line's buffer in another window as if by -@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible. -@item C-o -Immediately display this line's buffer in another window, but don't -select the window. -@item 1 -Immediately select this line's buffer in a full-screen window. -@item 2 -Immediately set up two windows, with this line's buffer selected in -one, and the previously current buffer (aside from the buffer -@samp{*Buffer List*}) displayed in the other. -@item b -Bury the buffer listed on this line. -@item m -Mark this line's buffer to be displayed in another window if you exit -with the @kbd{v} command. The request shows as a @samp{>} at the -beginning of the line. (A single buffer may not have both a delete -request and a display request.) -@item v -Immediately select this line's buffer, and also display in other windows -any buffers previously marked with the @kbd{m} command. If you have not -marked any buffers, this command is equivalent to @kbd{1}. -@end table - - There is also a command that affects the entire buffer list: - -@table @kbd -@item T -Delete, or reinsert, lines for non-file buffers. This command toggles -the inclusion of such buffers in the buffer list. -@end table - - What @code{buffer-menu} actually does is create and switch to a -suitable buffer, and turn on Buffer Menu mode in it. Everything else -described above is implemented by the special commands provided in -Buffer Menu mode. One consequence of this is that you can switch from -the @samp{*Buffer List*} buffer to another Emacs buffer, and edit -there. You can reselect the @samp{*Buffer List*} buffer later, to -perform the operations already requested, or you can kill it, or pay -no further attention to it. - - Normally, the buffer @samp{*Buffer List*} is not updated -automatically when buffers are created and killed; its contents are -just text. If you have created, deleted or renamed buffers, the way -to update @samp{*Buffer List*} to show what you have done is to type -@kbd{g} (@code{revert-buffer}). You can make this happen regularly -every @code{auto-revert-interval} seconds if you enable Auto Revert -mode in this buffer, as long as it is not marked modified. Global -Auto Revert mode applies to the @samp{*Buffer List*} buffer only if -@code{global-auto-revert-non-file-buffers} is non-@code{nil}. -@iftex -@inforef{Autorevert,, emacs-xtra}, for details. -@end iftex -@ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. -@end ifnottex - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffer -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link between files. - -@table @kbd -@findex make-indirect-buffer -@item M-x make-indirect-buffer @key{RET} @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} -Create an indirect buffer named @var{indirect-name} whose base buffer -is @var{base-buffer}. -@findex clone-indirect-buffer -@item M-x clone-indirect-buffer @key{RET} -Create an indirect buffer that is a twin copy of the current buffer. -@item C-x 4 c -@kindex C-x 4 c -@findex clone-indirect-buffer-other-window -Create an indirect buffer that is a twin copy of the current buffer, and -select it in another window (@code{clone-indirect-buffer-other-window}). -@end table - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. But in all other respects, the indirect buffer and its -base buffer are completely separate. They can have different names, -different values of point, different narrowing, different markers, -different major modes, and different local variables. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. Killing the base buffer effectively kills the indirect -buffer, but killing an indirect buffer has no effect on its base buffer. - - One way to use indirect buffers is to display multiple views of an -outline. @xref{Outline Views}. - -@vindex clone-indirect-buffer-hook - A quick and handy way to make an indirect buffer is with the command -@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect -buffer whose base buffer is the current buffer. With a numeric -argument, it prompts for the name of the indirect buffer; otherwise it -uses the name of the current buffer, with a @samp{<@var{n}>} suffix -added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) -works like @kbd{M-x clone-indirect-buffer}, but it selects the new -buffer in another window. These functions run the hook -@code{clone-indirect-buffer-hook} after creating the indirect buffer. - - The more general way to make an indirect buffer is with the command -@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from -buffer @var{base-buffer}, under the name @var{indirect-name}. It -prompts for both @var{base-buffer} and @var{indirect-name} using the -minibuffer. - -@node Buffer Convenience -@section Convenience Features and Customization of Buffer Handling - - This section describes several modes and features that make it more -convenient to switch between buffers. - -@menu -* Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. -@end menu - -@node Uniquify -@subsection Making Buffer Names Unique - -@cindex unique buffer names -@cindex directories in buffer names - When several buffers visit identically-named files, Emacs must give -the buffers distinct names. The usual method for making buffer names -unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer -names (all but one of them). - -@vindex uniquify-buffer-name-style - Other methods work by adding parts of each file's directory to the -buffer name. To select one, customize the variable -@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). - - To begin with, the @code{forward} naming method includes part of the -file's directory name at the beginning of the buffer name; using this -method, buffers visiting the files @file{/u/rms/tmp/Makefile} and -@file{/usr/projects/zaphod/Makefile} would be named -@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead -of @samp{Makefile} and @samp{Makefile<2>}). - - In contrast, the @code{post-forward} naming method would call the -buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the -@code{reverse} naming method would call them @samp{Makefile\tmp} and -@samp{Makefile\zaphod}. The nontrivial difference between -@code{post-forward} and @code{reverse} occurs when just one directory -name is not enough to distinguish two files; then @code{reverse} puts -the directory names in reverse order, so that @file{/top/middle/file} -becomes @samp{file\middle\top}, while @code{post-forward} puts them in -forward order after the file name, as in @samp{file|top/middle}. - - Which rule to follow for putting the directory names in the buffer -name is not very important if you are going to @emph{look} at the -buffer names before you type one. But as an experienced user, if you -know the rule, you won't have to look. And then you may find that one -rule or another is easier for you to remember and apply quickly. - -@node Iswitchb -@subsection Switching Between Buffers using Substrings - -@findex iswitchb-mode -@cindex Iswitchb mode -@cindex mode, Iswitchb -@kindex C-x b @r{(Iswitchb mode)} -@kindex C-x 4 b @r{(Iswitchb mode)} -@kindex C-x 5 b @r{(Iswitchb mode)} -@kindex C-x 4 C-o @r{(Iswitchb mode)} - - Iswitchb global minor mode provides convenient switching between -buffers using substrings of their names. It replaces the normal -definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x -4 C-o} with alternative commands that are somewhat ``smarter.'' - - When one of these commands prompts you for a buffer name, you can -type in just a substring of the name you want to choose. As you enter -the substring, Iswitchb mode continuously displays a list of buffers -that match the substring you have typed. - - At any time, you can type @key{RET} to select the first buffer in -the list. So the way to select a particular buffer is to make it the -first in the list. There are two ways to do this. You can type more -of the buffer name and thus narrow down the list, excluding unwanted -buffers above the desired one. Alternatively, you can use @kbd{C-s} -and @kbd{C-r} to rotate the list until the desired buffer is first. - - @key{TAB} while entering the buffer name performs completion on the -string you have entered, based on the displayed list of buffers. - - To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize -the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy -Customization}). - -@node Buffer Menus -@subsection Customizing Buffer Menus - -@findex bs-show -@cindex buffer list, customizable -@table @kbd -@item M-x bs-show -Make a list of buffers similarly to @kbd{M-x list-buffers} but -customizable. -@end table - - @kbd{M-x bs-show} pops up a buffer list similar to the one normally -displayed by @kbd{C-x C-b} but which you can customize. If you prefer -this to the usual buffer list, you can bind this command to @kbd{C-x -C-b}. To customize this buffer list, use the @code{bs} Custom group -(@pxref{Easy Customization}). - -@findex msb-mode -@cindex mode, MSB -@cindex MSB mode -@cindex buffer menu -@findex mouse-buffer-menu -@kindex C-Down-Mouse-1 - MSB global minor mode (``MSB'' stands for ``mouse select buffer'') -provides a different and customizable mouse buffer menu which you may -prefer. It replaces the bindings of @code{mouse-buffer-menu}, -normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You -can customize the menu in the @code{msb} Custom group. - -@ignore - arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695 -@end ignore diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi deleted file mode 100644 index 2eb714b826d..00000000000 --- a/doc/emacs/building.texi +++ /dev/null @@ -1,1484 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Building, Maintaining, Programs, Top -@chapter Compiling and Testing Programs -@cindex building programs -@cindex program building -@cindex running Lisp functions - - The previous chapter discusses the Emacs commands that are useful for -making changes in programs. This chapter deals with commands that assist -in the larger process of compiling and testing programs. - -@menu -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. -* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. -* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. -@end menu - -@node Compilation -@section Running Compilations under Emacs -@cindex inferior process -@cindex make -@cindex compilation errors -@cindex error log - - Emacs can run compilers for noninteractive languages such as C and -Fortran as inferior processes, feeding the error log into an Emacs buffer. -It can also parse the error messages and show you the source lines where -compilation errors occurred. - -@table @kbd -@item M-x compile -Run a compiler asynchronously under Emacs, with error messages going to -the @samp{*compilation*} buffer. -@item M-x recompile -Invoke a compiler with the same command as in the last invocation of -@kbd{M-x compile}. -@item M-x kill-compilation -Kill the running compilation subprocess. -@end table - -@findex compile - To run @code{make} or another compilation command, do @kbd{M-x -compile}. This command reads a shell command line using the minibuffer, -and then executes the command in an inferior shell, putting output in -the buffer named @samp{*compilation*}. The current buffer's default -directory is used as the working directory for the execution of the -command; normally, therefore, the compilation happens in this -directory. - -@vindex compile-command - The default for the compilation command is normally @samp{make -k}, -which is correct most of the time for nontrivial programs. -@xref{Top,, Make, make, GNU Make Manual}. If you have done @kbd{M-x -compile} before, the default each time is the command you used the -previous time. @code{compile} stores this command in the variable -@code{compile-command}, so setting that variable specifies the default -for the next use of @kbd{M-x compile}. If a file specifies a file -local value for @code{compile-command}, that provides the default when -you type @kbd{M-x compile} in that file's buffer. @xref{File -Variables}. - - Starting a compilation displays the buffer @samp{*compilation*} in -another window but does not select it. The buffer's mode line tells -you whether compilation is finished, with the word @samp{run}, -@samp{signal} or @samp{exit} inside the parentheses. You do not have -to keep this buffer visible; compilation continues in any case. While -a compilation is going on, the string @samp{Compiling} appears in the -mode lines of all windows. When this string disappears, the -compilation is finished. - - If you want to watch the compilation transcript as it appears, switch -to the @samp{*compilation*} buffer and move point to the end of the -buffer. When point is at the end, new compilation output is inserted -above point, which remains at the end. If point is not at the end of -the buffer, it remains fixed while more compilation output is added at -the end of the buffer. - -@cindex compilation buffer, keeping point at end -@vindex compilation-scroll-output - If you change the variable @code{compilation-scroll-output} to a -non-@code{nil} value, the compilation buffer will scroll automatically -to follow the output as it comes in. If the value is -@code{first-error}, the scrolling stops at the first error that -appears, leaving point at that error. For any other non-@code{nil} -value, the buffer continues scrolling until there is no more output. - -@findex recompile - To rerun the last compilation with the same command, type @kbd{M-x -recompile}. This automatically reuses the compilation command from -the last invocation of @kbd{M-x compile}. It also reuses the -@samp{*compilation*} buffer and starts the compilation in its default -directory, which is the directory in which the previous compilation -was started. - - When the compiler process terminates, for whatever reason, the mode -line of the @samp{*compilation*} buffer changes to say @samp{exit} -(followed by the exit code, @samp{[0]} for a normal exit), or -@samp{signal} (if a signal terminated the process), instead of -@samp{run}. - -@findex kill-compilation - Starting a new compilation also kills any compilation already -running in @samp{*compilation*}, as the buffer can only handle one -compilation at any time. However, @kbd{M-x compile} asks for -confirmation before actually killing a compilation that is running. -You can also kill the compilation process with @kbd{M-x -kill-compilation}. - - If you want to run two compilations at once, you should start the -first one, then rename the @samp{*compilation*} buffer (perhaps using -@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other -compilation. That will create a new @samp{*compilation*} buffer. - - Emacs does not expect a compiler process to launch asynchronous -subprocesses; if it does, and they keep running after the main -compiler process has terminated, Emacs may kill them or their output -may not arrive in Emacs. To avoid this problem, make the main process -wait for its subprocesses to finish. In a shell script, you can do this -using @samp{$!} and @samp{wait}, like this: - -@example -(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} -echo first message -wait $pid # @r{Wait for subprocess} -@end example - - If the background process does not output to the compilation buffer, -so you only need to prevent it from being killed when the main -compilation process terminates, this is sufficient: - -@example -nohup @var{command}; sleep 1 -@end example - -@vindex compilation-environment - You can control the environment passed to the compilation command -with the variable @code{compilation-environment}. Its value is a list -of environment variable settings; each element should be a string of -the form @code{"@var{envvarname}=@var{value}"}. These environment -variable settings override the usual ones. - -@node Compilation Mode -@section Compilation Mode - -@cindex Compilation mode -@cindex mode, Compilation - The @samp{*compilation*} buffer uses a special major mode, -Compilation mode, whose main feature is to provide a convenient way to -visit the source line corresponding to an error message. These -commands are also available in other special buffers that list -locations in files, including those made by @kbd{M-x grep} and -@kbd{M-x occur}. - -@table @kbd -@item M-g M-n -@itemx M-g n -@itemx C-x ` -Visit the locus of the next error message or match. -@item M-g M-p -@itemx M-g p -Visit the locus of the previous error message or match. -@item @key{RET} -Visit the locus of the error message that point is on. -This command is used in the compilation buffer. -@item Mouse-2 -Visit the locus of the error message that you click on. -@item M-n -Find and highlight the locus of the next error message, without -selecting the source buffer. -@item M-p -Find and highlight the locus of the previous error message, without -selecting the source buffer. -@item M-@} -Move point to the next error for a different file than the current -one. -@item M-@{ -Move point to the previous error for a different file than the current -one. -@item C-c C-f -Toggle Next Error Follow minor mode, which makes cursor motion in the -compilation buffer produce automatic source display. -@end table - -@findex compile-goto-error -@vindex compilation-auto-jump-to-first-error - You can visit the source for any particular error message by moving -point in the @samp{*compilation*} buffer to that error message and -typing @key{RET} (@code{compile-goto-error}). Alternatively, you can -click @kbd{Mouse-2} on the error message; you need not switch to the -@samp{*compilation*} buffer first. If you set the variable -@code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, -Emacs automatically jumps to the first error, if any, as soon as it -appears in the @samp{*compilation*} buffer. - -@kindex M-g M-n -@kindex M-g n -@kindex C-x ` -@findex next-error -@vindex next-error-highlight - To parse the compiler error messages sequentially, type @kbd{C-x `} -(@code{next-error}). The character following the @kbd{C-x} is the -backquote or ``grave accent,'' not the single-quote. This command is -available in all buffers, not just in @samp{*compilation*}; it -displays the next error message at the top of one window and source -location of the error in another window. It also temporarily -highlights the relevant source line, for a period controlled by the -variable @code{next-error-highlight}. - - The first time @w{@kbd{C-x `}} is used after the start of a compilation, -it moves to the first error's location. Subsequent uses of @kbd{C-x -`} advance down to subsequent errors. If you visit a specific error -message with @key{RET} or @kbd{Mouse-2}, subsequent @w{@kbd{C-x `}} -commands advance from there. When @w{@kbd{C-x `}} gets to the end of the -buffer and finds no more error messages to visit, it fails and signals -an Emacs error. @w{@kbd{C-u C-x `}} starts scanning from the beginning of -the compilation buffer, and goes to the first error's location. - -@vindex compilation-skip-threshold - By default, @w{@kbd{C-x `}} skips less important messages. The variable -@code{compilation-skip-threshold} controls this. If its value is 2, -@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less -than warning, and 0 doesn't skip any messages. The default is 1. - - When the window has a left fringe, an arrow in the fringe points to -the current message in the compilation buffer. The variable -@code{compilation-context-lines} controls the number of lines of -leading context to display before the current message. Going to an -error message location scrolls the @samp{*compilation*} buffer to put -the message that far down from the top. The value @code{nil} is -special: if there's a left fringe, the window doesn't scroll at all -if the message is already visible. If there is no left fringe, -@code{nil} means display the message at the top of the window. - - If you're not in the compilation buffer when you run -@code{next-error}, Emacs will look for a buffer that contains error -messages. First, it looks for one displayed in the selected frame, -then for one that previously had @code{next-error} called on it, and -then at the current buffer. Finally, Emacs looks at all the remaining -buffers. @code{next-error} signals an error if it can't find any such -buffer. - -@vindex compilation-error-regexp-alist -@vindex grep-regexp-alist - To parse messages from the compiler, Compilation mode uses the -variable @code{compilation-error-regexp-alist} which lists various -formats of error messages and tells Emacs how to extract the source file -and the line number from the text of a message. If your compiler isn't -supported, you can tailor Compilation mode to it by adding elements to -that list. A similar variable @code{grep-regexp-alist} tells Emacs how -to parse output of a @code{grep} command. - -@findex compilation-next-error -@findex compilation-previous-error -@findex compilation-next-file -@findex compilation-previous-file - Compilation mode also redefines the keys @key{SPC} and @key{DEL} to -scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) -and @kbd{M-p} (@code{compilation-previous-error}) to move to the next -or previous error message. You can also use @kbd{M-@{} -(@code{compilation-next-file} and @kbd{M-@}} -(@code{compilation-previous-file}) to move up or down to an error -message for a different source file. - -@cindex Next Error Follow mode -@findex next-error-follow-minor-mode - You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In -this minor mode, ordinary cursor motion in the compilation buffer -automatically updates the source buffer. For instance, moving the -cursor to the next error message causes the location of that error to -be displayed immediately. - - The features of Compilation mode are also available in a minor mode -called Compilation Minor mode. This lets you parse error messages in -any buffer, not just a normal compilation output buffer. Type @kbd{M-x -compilation-minor-mode} to enable the minor mode. This defines the keys -@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. - - Compilation minor mode works in any buffer, as long as the contents -are in a format that it understands. In an Rlogin buffer (@pxref{Remote -Host}), Compilation minor mode automatically accesses remote source -files by FTP (@pxref{File Names}). - -@node Compilation Shell -@section Subshells for Compilation - - Emacs uses a shell to run the compilation command, but specifies the -option for a noninteractive shell. This means, in particular, that -the shell should start with no prompt. If you find your usual shell -prompt making an unsightly appearance in the @samp{*compilation*} -buffer, it means you have made a mistake in your shell's init file by -setting the prompt unconditionally. (This init file's name may be -@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or -various other things, depending on the shell you use.) The shell init -file should set the prompt only if there already is a prompt. Here's -how to do it in bash: - -@example -if [ "$@{PS1+set@}" = set ] -then PS1=@dots{} -fi -@end example - -@noindent -And here's how to do it in csh: - -@example -if ($?prompt) set prompt = @dots{} -@end example - - There may well be other things that your shell's init file -ought to do only for an interactive shell. You can use the same -method to conditionalize them. - - The MS-DOS ``operating system'' does not support asynchronous -subprocesses; to work around this lack, @kbd{M-x compile} runs the -compilation command synchronously on MS-DOS. As a consequence, you must -wait until the command finishes before you can do anything else in -Emacs. -@iftex -@inforef{MS-DOS,,emacs-xtra}. -@end iftex -@ifnottex -@xref{MS-DOS}. -@end ifnottex - -@node Grep Searching -@section Searching with Grep under Emacs - - Just as you can run a compiler from Emacs and then visit the lines -with compilation errors, you can also run @code{grep} and then visit -the lines on which matches were found. This works by treating the -matches reported by @code{grep} as if they were ``errors.'' The -buffer of matches uses Grep mode, which is a variant of Compilation -mode (@pxref{Compilation Mode}). - -@table @kbd -@item M-x grep -@itemx M-x lgrep -Run @code{grep} asynchronously under Emacs, with matching lines -listed in the buffer named @samp{*grep*}. -@item M-x grep-find -@itemx M-x find-grep -@itemx M-x rgrep -Run @code{grep} via @code{find}, with user-specified arguments, and -collect output in the buffer named @samp{*grep*}. -@item M-x kill-grep -Kill the running @code{grep} subprocess. -@end table - -@findex grep - To run @code{grep}, type @kbd{M-x grep}, then enter a command line -that specifies how to run @code{grep}. Use the same arguments you -would give @code{grep} when running it normally: a @code{grep}-style -regexp (usually in single-quotes to quote the shell's special -characters) followed by file names, which may use wildcards. If you -specify a prefix argument for @kbd{M-x grep}, it finds the tag -(@pxref{Tags}) in the buffer around point, and puts that into the -default @code{grep} command. - - Your command need not simply run @code{grep}; you can use any shell -command that produces output in the same format. For instance, you -can chain @code{grep} commands, like this: - -@example -grep -nH -e foo *.el | grep bar | grep toto -@end example - - The output from @code{grep} goes in the @samp{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. - - Some grep programs accept a @samp{--color} option to output special -markers around matches for the purpose of highlighting. You can make -use of this feature by setting @code{grep-highlight-matches} to -@code{t}. When displaying a match in the source buffer, the exact -match will be highlighted, instead of the entire source line. - -@findex grep-find -@findex find-grep - The command @kbd{M-x grep-find} (also available as @kbd{M-x -find-grep}) is similar to @kbd{M-x grep}, but it supplies a different -initial default for the command---one that runs both @code{find} and -@code{grep}, so as to search every file in a directory tree. See also -the @code{find-grep-dired} command, in @ref{Dired and Find}. - -@findex lgrep -@findex rgrep - The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} -(recursive grep) are more user-friendly versions of @code{grep} and -@code{grep-find}, which prompt separately for the regular expression -to match, the files to search, and the base directory for the search. -Case sensitivity of the search is controlled by the -current value of @code{case-fold-search}. - -These commands build the shell commands based on the variables -@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} -(for @code{rgrep}). - -The files to search can use aliases defined in the variable -@code{grep-files-aliases}. - -Subdirectories listed in the variable -@code{grep-find-ignored-directories} such as those typically used by -various version control systems, like CVS and arch, are automatically -skipped by @code{rgrep}. - -@node Flymake -@section Finding Syntax Errors On The Fly -@cindex checking syntax - - Flymake mode is a minor mode that performs on-the-fly syntax -checking for many programming and markup languages, including C, C++, -Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell -mode, which performs spell checking for ordinary human languages in a -similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode -runs an appropriate syntax checking tool in the background, using a -temporary copy of the buffer. It then parses the error and warning -messages, and highlights the erroneous lines in the buffer. The -syntax checking tool used depends on the language; for example, for -C/C++ files this is usually the C compiler. Flymake can also use -build tools such as @code{make} for checking complicated projects. - - To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move -to the errors spotted by Flymake mode with @kbd{M-x -flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To -display any error messages associated with the current line, use -@kbd{M-x flymake-display-err-menu-for-current-line}. - - For more details about using Flymake, see @ref{Top, Flymake, -Flymake, flymake, The Flymake Manual}. - -@node Debuggers -@section Running Debuggers Under Emacs -@cindex debuggers -@cindex GUD library -@cindex GDB -@cindex DBX -@cindex SDB -@cindex XDB -@cindex Perldb -@cindex JDB -@cindex PDB - -@c Do you believe in GUD? -The GUD (Grand Unified Debugger) library provides an Emacs interface -to a wide variety of symbolic debuggers. Unlike the GDB graphical -interface, which only runs GDB (@pxref{GDB Graphical Interface}), GUD -can also run DBX, SDB, XDB, Perl's debugging mode, the Python debugger -PDB, or the Java Debugger JDB. - - In addition, Emacs contains a built-in system for debugging Emacs -Lisp programs. @xref{Debugging,, The Lisp Debugger, elisp, the Emacs -Lisp Reference Manual}, for information on the Emacs Lisp debugger. - -@menu -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment through - Emacs. -@end menu - -@node Starting GUD -@subsection Starting GUD - - There are several commands for starting a debugger under GUD, each -corresponding to a particular debugger program. - -@table @kbd -@item M-x gdb @key{RET} @var{file} @key{RET} -@findex gdb -Run GDB as a subprocess of Emacs. This uses an IDE-like graphical -interface; see @ref{GDB Graphical Interface}. Only GDB works with the -graphical interface. - -@item M-x gud-gdb @key{RET} @var{file} @key{RET} -@findex gud-gdb -Run GDB as a subprocess of Emacs. This command creates a buffer for -input and output to GDB, and switches to it. If a GDB buffer already -exists, it just switches to that buffer. - -@item M-x dbx @key{RET} @var{file} @key{RET} -@findex dbx -Run DBX as a subprocess of Emacs. Since Emacs does not implement a -graphical interface for DBX, communication with DBX works by typing -commands in the GUD interaction buffer. The same is true for all -the other supported debuggers. - -@item M-x xdb @key{RET} @var{file} @key{RET} -@findex xdb -@vindex gud-xdb-directories -Run XDB as a subprocess of Emacs. Use the variable -@code{gud-xdb-directories} to specify directories to search for source -files. - -@item M-x sdb @key{RET} @var{file} @key{RET} -@findex sdb -Run SDB as a subprocess of Emacs. - -Some versions of SDB do not mention source file names in their -messages. When you use them, you need to have a valid tags table -(@pxref{Tags}) in order for GUD to find functions in the source code. -If you have not visited a tags table or the tags table doesn't list -one of the functions, you get a message saying @samp{The sdb support -requires a valid tags table to work}. If this happens, generate a -valid tags table in the working directory and try again. - -@item M-x perldb @key{RET} @var{file} @key{RET} -@findex perldb -Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. - -@item M-x jdb @key{RET} @var{file} @key{RET} -@findex jdb -Run the Java debugger to debug @var{file}. - -@item M-x pdb @key{RET} @var{file} @key{RET} -@findex pdb -Run the Python debugger to debug @var{file}. -@end table - - Each of these commands takes one argument: a command line to invoke -the debugger. In the simplest case, specify just the name of the -executable file you want to debug. You may also use options that the -debugger supports. However, shell wildcards and variables are not -allowed. GUD assumes that the first argument not starting with a -@samp{-} is the executable file name. - -@cindex remote host, debugging on -Tramp provides a facility to debug programs on remote hosts -(@pxref{Running a debugger on a remote host, Running a debugger on a -remote host,, tramp, The Tramp Manual}), whereby both the debugger and -the program being debugged are on the same remote host. This should -not be confused with debugging programs remotely, where the program -and the debugger run on different machines, as can be done using the -GDB remote debugging feature, for example (@pxref{Remote Debugging,, -Debugging Remote Programs, gdb, The GNU debugger}). - -@node Debugger Operation -@subsection Debugger Operation - -@cindex fringes, and current execution line in GUD - Generally when you run a debugger with GUD, the debugger uses an Emacs -buffer for its ordinary input and output. This is called the GUD -buffer. Input and output from the program you are debugging also use -this buffer. We call this @dfn{text command mode}. The GDB Graphical -Interface can use further buffers (@pxref{GDB Graphical Interface}). - - The debugger displays the source files of the program by visiting -them in Emacs buffers. An arrow in the left fringe indicates the -current execution line.@footnote{On a text-only terminal, the arrow -appears as @samp{=>} and overlays the first two text columns.} Moving -point in this buffer does not move the arrow. The arrow is not part -of the file's text; it appears only on the screen. - - You can start editing these source files at any time in the buffers -that display them. If you do modify a source file, keep in mind that -inserting or deleting lines will throw off the arrow's positioning; -GUD has no way of figuring out which line corresponded before your -changes to the line number in a debugger message. Also, you'll -typically have to recompile and restart the program for your changes -to be reflected in the debugger's tables. - -@cindex tooltips with GUD -@vindex tooltip-gud-modes -@vindex gud-tooltip-mode -@vindex gud-tooltip-echo-area - The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. -You activate this feature by turning on the minor mode -@code{gud-tooltip-mode}. Then you can display a variable's value in a -tooltip simply by pointing at it with the mouse. This operates in the -GUD buffer and in source buffers with major modes in the list -@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} -is non-@code{nil} then the variable's value is displayed in the echo -area. When debugging a C program using the GDB Graphical Interface, you -can also display macro definitions associated with an identifier when -the program is not executing. - - GUD tooltips are disabled when you use GDB in text command mode -(@pxref{GDB Graphical Interface}), because displaying an expression's -value in GDB can sometimes expand a macro and result in a side effect -that interferes with the program's operation. The GDB graphical -interface supports GUD tooltips and assures they will not cause side -effects. - -@node Commands of GUD -@subsection Commands of GUD - - The GUD interaction buffer uses a variant of Shell mode, so the -Emacs commands of Shell mode are available (@pxref{Shell Mode}). All -the usual commands for your debugger are available, and you can use -the Shell mode history commands to repeat them. If you wish, you can -control your debugger process entirely through this buffer. - - GUD mode also provides commands for setting and clearing -breakpoints, for selecting stack frames, and for stepping through the -program. These commands are available both in the GUD buffer and -globally, but with different key bindings. It also has its own tool -bar from which you can invoke the more common commands by clicking on -the appropriate icon. This is particularly useful for repetitive -commands like @code{gud-next} and @code{gud-step}, and allows you to -keep the GUD buffer hidden. - - The breakpoint commands are normally used in source file buffers, -because that is the easiest way to specify where to set or clear the -breakpoint. Here's the global command to set a breakpoint: - -@table @kbd -@item C-x @key{SPC} -@kindex C-x SPC -Set a breakpoint on the source line that point is on. -@end table - -@kindex C-x C-a @r{(GUD)} - Here are the other special commands provided by GUD@. The keys -starting with @kbd{C-c} are available only in the GUD interaction -buffer. The key bindings that start with @kbd{C-x C-a} are available -in the GUD interaction buffer and also in source files. Some of these -commands are not available to all the supported debuggers. - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(GUD)} -@itemx C-x C-a C-l -@findex gud-refresh -Display in another window the last line referred to in the GUD -buffer (that is, the line indicated in the last location message). -This runs the command @code{gud-refresh}. - -@item C-c C-s -@kindex C-c C-s @r{(GUD)} -@itemx C-x C-a C-s -@findex gud-step -Execute a single line of code (@code{gud-step}). If the line contains -a function call, execution stops after entering the called function. - -@item C-c C-n -@kindex C-c C-n @r{(GUD)} -@itemx C-x C-a C-n -@findex gud-next -Execute a single line of code, stepping across entire function calls -at full speed (@code{gud-next}). - -@item C-c C-i -@kindex C-c C-i @r{(GUD)} -@itemx C-x C-a C-i -@findex gud-stepi -Execute a single machine instruction (@code{gud-stepi}). - -@item C-c C-p -@kindex C-c C-p @r{(GUD)} -@itemx C-x C-a C-p -@findex gud-print -Evaluate the expression at point (@code{gud-print}). If Emacs -does not print the exact expression that you want, mark it as a region -first. - -@need 3000 -@item C-c C-r -@kindex C-c C-r @r{(GUD)} -@itemx C-x C-a C-r -@findex gud-cont -Continue execution without specifying any stopping point. The program -will run until it hits a breakpoint, terminates, or gets a signal that -the debugger is checking for (@code{gud-cont}). - -@need 1000 -@item C-c C-d -@kindex C-c C-d @r{(GUD)} -@itemx C-x C-a C-d -@findex gud-remove -Delete the breakpoint(s) on the current source line, if any -(@code{gud-remove}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c C-t -@kindex C-c C-t @r{(GUD)} -@itemx C-x C-a C-t -@findex gud-tbreak -Set a temporary breakpoint on the current source line, if any -(@code{gud-tbreak}). If you use this command in the GUD interaction -buffer, it applies to the line where the program last stopped. - -@item C-c < -@kindex C-c < @r{(GUD)} -@itemx C-x C-a < -@findex gud-up -Select the next enclosing stack frame (@code{gud-up}). This is -equivalent to the GDB command @samp{up}. - -@item C-c > -@kindex C-c > @r{(GUD)} -@itemx C-x C-a > -@findex gud-down -Select the next inner stack frame (@code{gud-down}). This is -equivalent to the GDB command @samp{down}. - -@item C-c C-u -@kindex C-c C-u @r{(GUD)} -@itemx C-x C-a C-u -@findex gud-until -Continue execution to the current line (@code{gud-until}). The -program will run until it hits a breakpoint, terminates, gets a signal -that the debugger is checking for, or reaches the line on which the -cursor currently sits. - -@item C-c C-f -@kindex C-c C-f @r{(GUD)} -@itemx C-x C-a C-f -@findex gud-finish -Run the program until the selected stack frame returns or -stops for some other reason (@code{gud-finish}). -@end table - - If you are using GDB, these additional key bindings are available: - -@table @kbd -@item C-x C-a C-j -@kindex C-x C-a C-j @r{(GUD)} -@findex gud-jump -Only useful in a source buffer, @code{gud-jump} transfers the -program's execution point to the current line. In other words, the -next line that the program executes will be the one where you gave the -command. If the new execution line is in a different function from -the previously one, GDB prompts for confirmation since the results may -be bizarre. See the GDB manual entry regarding @code{jump} for -details. - -@item @key{TAB} -@kindex TAB @r{(GUD)} -@findex gud-gdb-complete-command -With GDB, complete a symbol name (@code{gud-gdb-complete-command}). -This key is available only in the GUD interaction buffer. -@end table - - These commands interpret a numeric argument as a repeat count, when -that makes sense. - - Because @key{TAB} serves as a completion command, you can't use it to -enter a tab as input to the program you are debugging with GDB. -Instead, type @kbd{C-q @key{TAB}} to enter a tab. - -@node GUD Customization -@subsection GUD Customization - -@vindex gdb-mode-hook -@vindex dbx-mode-hook -@vindex sdb-mode-hook -@vindex xdb-mode-hook -@vindex perldb-mode-hook -@vindex pdb-mode-hook -@vindex jdb-mode-hook - On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, -if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; -@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you -are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; -@code{pdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can -use these hooks to define custom key bindings for the debugger -interaction buffer. @xref{Hooks}. - - Here is a convenient way to define a command that sends a particular -command string to the debugger, and set up a key binding for it in the -debugger interaction buffer: - -@findex gud-def -@example -(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) -@end example - - This defines a command named @var{function} which sends -@var{cmdstring} to the debugger process, and gives it the documentation -string @var{docstring}. You can then use the command @var{function} in any -buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds -the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to -@kbd{C-x C-a @var{binding}} generally. - - The command string @var{cmdstring} may contain certain -@samp{%}-sequences that stand for data to be filled in at the time -@var{function} is called: - -@table @samp -@item %f -The name of the current source file. If the current buffer is the GUD -buffer, then the ``current source file'' is the file that the program -stopped in. - -@item %l -The number of the current source line. If the current buffer is the GUD -buffer, then the ``current source line'' is the line that the program -stopped in. - -@item %e -In transient-mark-mode the text in the region, if it is active. -Otherwise the text of the C lvalue or function-call expression at or -adjacent to point. - -@item %a -The text of the hexadecimal address at or adjacent to point. - -@item %p -The numeric argument of the called function, as a decimal number. If -the command is used without a numeric argument, @samp{%p} stands for the -empty string. - -If you don't use @samp{%p} in the command string, the command you define -ignores any numeric argument. - -@item %d -The name of the directory of the current source file. - -@item %c -Fully qualified class name derived from the expression surrounding point -(jdb only). -@end table - -@node GDB Graphical Interface -@subsection GDB Graphical Interface - - The command @code{gdb} starts GDB in a graphical interface, using -Emacs windows for display program state information. In effect, this -makes Emacs into an IDE (interactive development environment). With -it, you do not need to use textual GDB commands; you can control the -debugging session with the mouse. For example, you can click in the -fringe of a source buffer to set a breakpoint there, or on a stack -frame in the stack buffer to select that frame. - - This mode requires telling GDB that its ``screen size'' is -unlimited, so it sets the height and width accordingly. For correct -operation you must not change these values during the GDB session. - -@vindex gud-gdb-command-name - To run GDB in text command mode, like the other debuggers in Emacs, -use @kbd{M-x gud-gdb}. You need to use text command mode to debug -multiple programs within one Emacs session. - -@menu -* GDB-UI Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB-UI Buffers:: Input/output, locals, registers, - assembler, threads and memory buffers. -* Watch Expressions:: Monitor variable values in the speedbar. -@end menu - -@node GDB-UI Layout -@subsubsection GDB User Interface Layout -@cindex GDB User Interface layout - -@vindex gdb-many-windows - If the variable @code{gdb-many-windows} is @code{nil} (the default -value) then @kbd{M-x gdb} normally displays only the GUD buffer. -However, if the variable @code{gdb-show-main} is also non-@code{nil}, -it starts with two windows: one displaying the GUD buffer, and the -other showing the source for the @code{main} function of the program -you are debugging. - - If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} -displays the following frame layout: - -@smallexample -@group -+--------------------------------+--------------------------------+ -| GUD buffer (I/O of GDB) | Locals/Registers buffer | -|--------------------------------+--------------------------------+ -| Primary Source buffer | I/O buffer for debugged pgm | -|--------------------------------+--------------------------------+ -| Stack buffer | Breakpoints/thread buffer | -+--------------------------------+--------------------------------+ -@end group -@end smallexample - - However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O -buffer does not appear and the primary source buffer occupies the full -width of the frame. - -@findex gdb-restore-windows - If you change the window layout, for example, while editing and -re-compiling your program, then you can restore this standard window -layout with the command @code{gdb-restore-windows}. - -@findex gdb-many-windows - To switch between this standard layout and a simple layout -containing just the GUD buffer and a source file, type @kbd{M-x -gdb-many-windows}. - - You may also specify additional GDB-related buffers to display, -either in the same frame or a different one. Select the buffers you -want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} -sub-menus. If the menu-bar is unavailable, type @code{M-x -gdb-display-@var{buffertype}-buffer} or @code{M-x -gdb-frame-@var{buffertype}-buffer} respectively, where -@var{buffertype} is the relevant buffer type, such as -@samp{breakpoints}. Most of these buffers are read-only, and typing -@kbd{q} in them kills them. - - When you finish debugging, kill the GUD buffer with @kbd{C-x k}, -which will also kill all the buffers associated with the session. -However you need not do this if, after editing and re-compiling your -source code within Emacs, you wish continue debugging. When you -restart execution, GDB will automatically find your new executable. -Keeping the GUD buffer has the advantage of keeping the shell history -as well as GDB's breakpoints. You do need to check that the -breakpoints in recently edited source files are still in the right -places. - -@node Source Buffers -@subsubsection Source Buffers -@cindex GDB commands in Fringe - -@c @findex gdb-mouse-set-clear-breakpoint -@c @findex gdb-mouse-toggle-breakpoint -Many GDB commands can be entered using key bindings or the tool bar but -sometimes it is quicker to use the fringe. These commands either -manipulate breakpoints or control program execution. When there is no -fringe, you can use the margin but this is only present when the -source file already has a breakpoint. - -You can click @kbd{Mouse-1} in the fringe or display margin of a -source buffer to set a breakpoint there and, on a graphical display, a -red bullet will appear on that line. If a breakpoint already exists -on that line, the same click will remove it. You can also enable or -disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. - -A solid arrow in the left fringe of a source buffer indicates the line -of the innermost frame where the debugged program has stopped. A -hollow arrow indicates the current execution line of higher level -frames. - -If you drag the arrow in the fringe with @kbd{Mouse-1} -(@code{gdb-mouse-until}), execution will continue to the line where -you release the button, provided it is still in the same frame. -Alternatively, you can click @kbd{Mouse-3} at some point in the fringe -of this buffer and execution will advance to there. A similar command -(@code{gdb-mouse-jump}) allows you to jump to a source line without -executing the intermediate lines by clicking @kbd{C-Mouse-3}. This -command allows you to go backwards which can be useful for running -through code that has already executed, in order to examine its -execution in more detail. - -@table @kbd -@item Mouse-1 -Set or clear a breakpoint. - -@item C-Mouse-1 -Enable or disable a breakpoint. - -@item Mouse-3 -Continue execution to here. - -@item C-Mouse-3 -Jump to here. -@end table - -If the variable @code{gdb-find-source-frame} is non-@code{nil} and -execution stops in a frame for which there is no source code e.g after -an interrupt, then Emacs finds and displays the first frame further up -stack for which there is source. If it is @code{nil} then the source -buffer continues to display the last frame which maybe more useful, -for example, when re-setting a breakpoint. - -@node Breakpoints Buffer -@subsubsection Breakpoints Buffer - - The breakpoints buffer shows the existing breakpoints, watchpoints and -catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has -these special commands, which mostly apply to the @dfn{current -breakpoint}, the breakpoint which point is on. - -@table @kbd -@item @key{SPC} -@kindex SPC @r{(GDB breakpoints buffer)} -@findex gdb-toggle-breakpoint -Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). -On a graphical display, this changes the color of a bullet in the -margin of a source buffer at the relevant line. This is red when -the breakpoint is enabled and grey when it is disabled. Text-only -terminals correspondingly display a @samp{B} or @samp{b}. - -@item D -@kindex D @r{(GDB breakpoints buffer)} -@findex gdb-delete-breakpoint -Delete the current breakpoint (@code{gdb-delete-breakpoint}). - -@item @key{RET} -@kindex RET @r{(GDB breakpoints buffer)} -@findex gdb-goto-breakpoint -Visit the source line for the current breakpoint -(@code{gdb-goto-breakpoint}). - -@item Mouse-2 -@kindex Mouse-2 @r{(GDB breakpoints buffer)} -Visit the source line for the breakpoint you click on. -@end table - -When @code{gdb-many-windows} is non-@code{nil}, the breakpoints buffer -shares its window with the threads buffer. To switch from one to the -other click with @kbd{mouse-1} on the relevant button in the header -line. - -@node Stack Buffer -@subsubsection Stack Buffer - - The stack buffer displays a @dfn{call stack}, with one line for each -of the nested subroutine calls (@dfn{stack frames}) now active in the -program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. - -@findex gdb-frames-select -An arrow in the fringe points to the selected frame or, if the fringe is -not present, the number of the selected frame is displayed in reverse -contrast. To select a frame in GDB, move point in the stack buffer to -that stack frame and type @key{RET} (@code{gdb-frames-select}), or click -@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, -selecting a stack frame updates it to display the local variables of the -new frame. - -@node Other GDB-UI Buffers -@subsubsection Other Buffers - -@table @asis -@item Input/Output Buffer -@vindex gdb-use-separate-io-buffer -If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, -the program being debugged takes its input and displays its output -here. Otherwise it uses the GUD buffer for that. To toggle whether -GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. -This takes effect when you next restart the program you are debugging. - -The history and replay commands from Shell mode are available here, -as are the commands to send signals to the debugged program. -@xref{Shell Mode}. - -@item Locals Buffer -The locals buffer displays the values of local variables of the -current frame for simple data types (@pxref{Frame Info, Frame Info, -Information on a frame, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on the value if you want to edit it. - -Arrays and structures display their type only. With GDB 6.4 or later, -move point to their name and press @key{RET}, or alternatively click -@kbd{Mouse-2} there, to examine their values. With earlier versions -of GDB, use @kbd{Mouse-2} or @key{RET} on the type description -(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. - -@item Registers Buffer -@findex toggle-gdb-all-registers -The registers buffer displays the values held by the registers -(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or -click @kbd{Mouse-2} on a register if you want to edit its value. -With GDB 6.4 or later, recently changed register values display with -@code{font-lock-warning-face}. With earlier versions of GDB, you can -press @key{SPC} to toggle the display of floating point registers -(@code{toggle-gdb-all-registers}). - -@item Assembler Buffer -The assembler buffer displays the current frame as machine code. An -arrow points to the current instruction, and you can set and remove -breakpoints as in a source buffer. Breakpoint icons also appear in -the fringe or margin. - -@item Threads Buffer -@findex gdb-threads-select -The threads buffer displays a summary of all threads currently in your -program (@pxref{Threads, Threads, Debugging programs with multiple -threads, gdb, The GNU debugger}). Move point to any thread in the -list and press @key{RET} to select it (@code{gdb-threads-select}) and -display the associated source in the primary source buffer. -Alternatively, click @kbd{Mouse-2} on a thread to select it. If the -locals buffer is visible, its contents update to display the variables -that are local in the new thread. - -When there is more than one main thread and the threads buffer is -present, Emacs displays the selected thread number in the mode line of -many of the GDB-UI Buffers. - -@item Memory Buffer -The memory buffer lets you examine sections of program memory -(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). -Click @kbd{Mouse-1} on the appropriate part of the header line to -change the starting address or number of data items that the buffer -displays. Alternatively, use @kbd{S} or @kbd{N} respectively. Click -@kbd{Mouse-3} on the header line to select the display format or unit -size for these data items. -@end table - -When @code{gdb-many-windows} is non-@code{nil}, the threads buffer -shares its window with the breakpoints buffer, and the locals buffer -with the registers buffer. To switch from one to the other click with -@kbd{mouse-1} on the relevant button in the header line. - -@node Watch Expressions -@subsubsection Watch Expressions -@cindex Watching expressions in GDB - -@findex gud-watch -@kindex C-x C-a C-w @r{(GUD)} - If you want to see how a variable changes each time your program -stops, move point into the variable name and click on the watch icon -in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you -specify a prefix argument, you can enter the variable name in the -minibuffer. - - Each watch expression is displayed in the speedbar. Complex data -types, such as arrays, structures and unions are represented in a tree -format. Leaves and simple data types show the name of the expression -and its value and, when the speedbar frame is selected, display the -type as a tooltip. Higher levels show the name, type and address -value for pointers and just the name and type otherwise. Root expressions -also display the frame address as a tooltip to help identify the frame -in which they were defined. - - To expand or contract a complex data type, click @kbd{Mouse-2} or -press @key{SPC} on the tag to the left of the expression. Emacs asks -for confirmation before expanding the expression if its number of -immediate children exceeds the value of the variable -@code{gdb-max-children}. - -@kindex D @r{(GDB speedbar)} -@findex gdb-var-delete - To delete a complex watch expression, move point to the root -expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). - -@kindex RET @r{(GDB speedbar)} -@findex gdb-edit-value - To edit a variable with a simple data type, or a simple element of a -complex data type, move point there in the speedbar and type @key{RET} -(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to -edit it. Either way, this reads the new value using the minibuffer. - -@vindex gdb-show-changed-values - If you set the variable @code{gdb-show-changed-values} to -non-@code{nil} (the default value), Emacs uses -@code{font-lock-warning-face} to highlight values that have recently -changed and @code{shadow} face to make variables which have gone out of -scope less noticeable. When a variable goes out of scope you can't -edit its value. - -@vindex gdb-delete-out-of-scope - If the variable @code{gdb-delete-out-of-scope} is non-@code{nil} -(the default value), Emacs automatically deletes watch expressions -which go out of scope. Sometimes, when re-entering the same function, -it may be useful to set this value to @code{nil} so that you don't -need to recreate the watch expression. - -@vindex gdb-use-colon-colon-notation - If the variable @code{gdb-use-colon-colon-notation} is -non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} -format. This allows the user to display watch expressions which share -the same variable name. The default value is @code{nil}. - -@vindex gdb-speedbar-auto-raise -To automatically raise the speedbar every time the display of watch -expressions updates, set @code{gdb-speedbar-auto-raise} to -non-@code{nil}. This can be useful if you are debugging with a full -screen Emacs frame. - -@node Executing Lisp -@section Executing Lisp Expressions - - Emacs has several different major modes for Lisp and Scheme. They are -the same in terms of editing commands, but differ in the commands for -executing Lisp expressions. Each mode has its own purpose. - -@table @asis -@item Emacs-Lisp mode -The mode for editing source files of programs to run in Emacs Lisp. -This mode defines @kbd{C-M-x} to evaluate the current defun. -@xref{Lisp Libraries}. -@item Lisp Interaction mode -The mode for an interactive session with Emacs Lisp. It defines -@kbd{C-j} to evaluate the sexp before point and insert its value in the -buffer. @xref{Lisp Interaction}. -@item Lisp mode -The mode for editing source files of programs that run in Lisps other -than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun -to an inferior Lisp process. @xref{External Lisp}. -@item Inferior Lisp mode -The mode for an interactive session with an inferior Lisp process. -This mode combines the special features of Lisp mode and Shell mode -(@pxref{Shell Mode}). -@item Scheme mode -Like Lisp mode but for Scheme programs. -@item Inferior Scheme mode -The mode for an interactive session with an inferior Scheme process. -@end table - - Most editing commands for working with Lisp programs are in fact -available globally. @xref{Programs}. - -@node Lisp Libraries -@section Libraries of Lisp Code for Emacs -@cindex libraries -@cindex loading Lisp code - - Lisp code for Emacs editing commands is stored in files whose names -conventionally end in @file{.el}. This ending tells Emacs to edit them in -Emacs-Lisp mode (@pxref{Executing Lisp}). - -@cindex byte code - Emacs Lisp code can be compiled into byte-code, which loads faster, -takes up less space, and executes faster. @xref{Byte Compilation,, -Byte Compilation, elisp, the Emacs Lisp Reference Manual}. By -convention, the compiled code for a library goes in a separate file -whose name ends in @samp{.elc}. Thus, the compiled code for -@file{foo.el} goes in @file{foo.elc}. - -@findex load-file - To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This -command reads a file name using the minibuffer and then executes the -contents of that file as Lisp code. It is not necessary to visit the -file first; in any case, this command reads the file as found on disk, -not text in an Emacs buffer. - -@findex load -@findex load-library - Once a file of Lisp code is installed in the Emacs Lisp library -directories, users can load it using @kbd{M-x load-library}. Programs -can load it by calling @code{load}, a more primitive function that is -similar but accepts some additional arguments. - - @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it -searches a sequence of directories and tries three file names in each -directory. Suppose your argument is @var{lib}; the three names are -@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just -@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention -the result of compiling @file{@var{lib}.el}; it is better to load the -compiled file, since it will load and run faster. - - If @code{load-library} finds that @file{@var{lib}.el} is newer than -@file{@var{lib}.elc} file, it issues a warning, because it's likely -that somebody made changes to the @file{.el} file and forgot to -recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is -because people often leave unfinished edits the source file, and don't -recompile it until they think it is ready to use. - -@vindex load-path - The variable @code{load-path} specifies the sequence of directories -searched by @kbd{M-x load-library}. Its value should be a list of -strings that are directory names; in addition, @code{nil} in this list -stands for the current default directory. (Generally, it is not a -good idea to put @code{nil} in the list; if you find yourself wishing -that @code{nil} were in the list, most likely what you really want is -to do @kbd{M-x load-file} this once.) - - The default value of @code{load-path} is a list of directories where -the Lisp code for Emacs itself is stored. If you have libraries of -your own, put them in a single directory and add that directory to -@code{load-path}, by adding a line like this to your init file -(@pxref{Init File}): - -@example -(add-to-list 'load-path "/path/to/lisp/libraries") -@end example - -@cindex autoload - Some commands are @dfn{autoloaded}: when you run them, Emacs will -automatically load the associated library first. For instance, the -@code{compile} and @code{compilation-mode} commands -(@pxref{Compilation}) are autoloaded; if you call either command, -Emacs automatically loads the @code{compile} library. In contrast, -the command @code{recompile} is not autoloaded, so it is unavailable -until you load the @code{compile} library. - -@vindex load-dangerous-libraries -@cindex Lisp files byte-compiled by XEmacs - By default, Emacs refuses to load compiled Lisp files which were -compiled with XEmacs, a modified versions of Emacs---they can cause -Emacs to crash. Set the variable @code{load-dangerous-libraries} to -@code{t} if you want to try loading them. - -@node Lisp Eval -@section Evaluating Emacs Lisp Expressions -@cindex Emacs-Lisp mode -@cindex mode, Emacs-Lisp - -@findex emacs-lisp-mode - Lisp programs intended to be run in Emacs should be edited in -Emacs-Lisp mode; this happens automatically for file names ending in -@file{.el}. By contrast, Lisp mode itself is used for editing Lisp -programs intended for other Lisp systems. To switch to Emacs-Lisp mode -explicitly, use the command @kbd{M-x emacs-lisp-mode}. - - For testing of Lisp programs to run in Emacs, it is often useful to -evaluate part of the program as it is found in the Emacs buffer. For -example, after changing the text of a Lisp function definition, -evaluating the definition installs the change for future calls to the -function. Evaluation of Lisp expressions is also useful in any kind of -editing, for invoking noninteractive functions (functions that are -not commands). - -@table @kbd -@item M-: -Read a single Lisp expression in the minibuffer, evaluate it, and print -the value in the echo area (@code{eval-expression}). -@item C-x C-e -Evaluate the Lisp expression before point, and print the value in the -echo area (@code{eval-last-sexp}). -@item C-M-x -Evaluate the defun containing or after point, and print the value in -the echo area (@code{eval-defun}). -@item M-x eval-region -Evaluate all the Lisp expressions in the region. -@item M-x eval-buffer -Evaluate all the Lisp expressions in the buffer. -@end table - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@kindex M-@key{colon} -@end ifinfo -@ifnotinfo -@kindex M-: -@end ifnotinfo -@findex eval-expression - @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating -a Lisp expression interactively. It reads the expression using the -minibuffer, so you can execute any expression on a buffer regardless of -what the buffer contains. When the expression is evaluated, the current -buffer is once again the buffer that was current when @kbd{M-:} was -typed. - -@kindex C-M-x @r{(Emacs-Lisp mode)} -@findex eval-defun - In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command -@code{eval-defun}, which parses the defun containing or following point -as a Lisp expression and evaluates it. The value is printed in the echo -area. This command is convenient for installing in the Lisp environment -changes that you have just made in the text of a function definition. - - @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, -evaluating a @code{defvar} expression does nothing if the variable it -defines already has a value. But @kbd{C-M-x} unconditionally resets the -variable to the initial value specified in the @code{defvar} expression. -@code{defcustom} expressions are treated similarly. -This special feature is convenient for debugging Lisp programs. -Typing @kbd{C-M-x} on a @code{defface} expression reinitializes -the face according to the @code{defface} specification. - -@kindex C-x C-e -@findex eval-last-sexp - The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp -expression preceding point in the buffer, and displays the value in the -echo area. It is available in all major modes, not just Emacs-Lisp -mode. It does not treat @code{defvar} specially. - - When the result of an evaluation is an integer, you can type -@kbd{C-x C-e} a second time to display the value of the integer result -in additional formats (octal, hexadecimal, and character). - - If @kbd{C-x C-e}, or @kbd{M-:} is given a numeric argument, it -inserts the value into the current buffer at point, rather than -displaying it in the echo area. The argument's value does not matter. -@kbd{C-M-x} with a numeric argument instruments the function -definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). - -@findex eval-region -@findex eval-buffer - The most general command for evaluating Lisp expressions from a buffer -is @code{eval-region}. @kbd{M-x eval-region} parses the text of the -region as one or more Lisp expressions, evaluating them one by one. -@kbd{M-x eval-buffer} is similar but evaluates the entire -buffer. This is a reasonable way to install the contents of a file of -Lisp code that you are ready to test. Later, as you find bugs and -change individual functions, use @kbd{C-M-x} on each function that you -change. This keeps the Lisp world in step with the source file. - -@vindex eval-expression-print-level -@vindex eval-expression-print-length -@vindex eval-expression-debug-on-error - The two customizable variables @code{eval-expression-print-level} and -@code{eval-expression-print-length} control the maximum depth and length -of lists to print in the result of the evaluation commands before -abbreviating them. @code{eval-expression-debug-on-error} controls -whether evaluation errors invoke the debugger when these commands are -used; its default is @code{t}. - -@node Lisp Interaction -@section Lisp Interaction Buffers - - When Emacs starts up, it contains a buffer named @samp{*scratch*}, -which is provided for evaluating Lisp expressions interactively inside -Emacs. Its major mode is Lisp Interaction mode. - -@findex eval-print-last-sexp -@kindex C-j @r{(Lisp Interaction mode)} - The simplest way to use the @samp{*scratch*} buffer is to insert -Lisp expressions and type @kbd{C-j} (@code{eval-print-last-sexp}) -after each expression. This command reads the Lisp expression before -point, evaluates it, and inserts the value in printed representation -before point. The result is a complete typescript of the expressions -you have evaluated and their values. - -@vindex initial-scratch-message - At startup, the @samp{*scratch*} buffer contains a short message, in -the form of a Lisp comment, that explains what it is for. This -message is controlled by the variable @code{initial-scratch-message}, -which should be either a string or @code{nil}. If you set it to the -empty string, or @code{nil}, the initial message is suppressed. - -@findex lisp-interaction-mode - All other commands in Lisp Interaction mode are the same as in Emacs -Lisp mode. You can enable Lisp Interaction mode by typing @kbd{M-x -lisp-interaction-mode}. - -@findex ielm - An alternative way of evaluating Emacs Lisp expressions interactively -is to use Inferior Emacs-Lisp mode, which provides an interface rather -like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp -expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer -which uses this mode. For more information see that command's -documentation. - -@node External Lisp -@section Running an External Lisp - - Emacs has facilities for running programs in other Lisp systems. You can -run a Lisp process as an inferior of Emacs, and pass expressions to it to -be evaluated. You can also pass changed function definitions directly from -the Emacs buffers in which you edit the Lisp programs to the inferior Lisp -process. - -@findex run-lisp -@vindex inferior-lisp-program -@kindex C-x C-z - To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs -the program named @code{lisp}, the same program you would run by typing -@code{lisp} as a shell command, with both input and output going through -an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal -output'' from Lisp will go into the buffer, advancing point, and any -``terminal input'' for Lisp comes from text in the buffer. (You can -change the name of the Lisp executable file by setting the variable -@code{inferior-lisp-program}.) - - To give input to Lisp, go to the end of the buffer and type the input, -terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp -mode, which combines the special characteristics of Lisp mode with most -of the features of Shell mode (@pxref{Shell Mode}). The definition of -@key{RET} to send a line to a subprocess is one of the features of Shell -mode. - -@findex lisp-mode - For the source files of programs to run in external Lisps, use Lisp -mode. You can switch to this mode with @kbd{M-x lisp-mode}, and it is -used automatically for files whose names end in @file{.l}, -@file{.lsp}, or @file{.lisp}. - -@kindex C-M-x @r{(Lisp mode)} -@findex lisp-eval-defun - When you edit a function in a Lisp program you are running, the easiest -way to send the changed definition to the inferior Lisp process is the key -@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun}, -which finds the defun around or following point and sends it as input to -the Lisp process. (Emacs can send input to any inferior process regardless -of what buffer is current.) - - Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing -programs to be run in another Lisp system) and Emacs-Lisp mode (for -editing Lisp programs to be run in Emacs; see @pxref{Lisp Eval}): in -both modes it has the effect of installing the function definition -that point is in, but the way of doing so is different according to -where the relevant Lisp environment is found. - - -@ignore - arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed -@end ignore diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi deleted file mode 100644 index 38809ef19bf..00000000000 --- a/doc/emacs/cal-xtra.texi +++ /dev/null @@ -1,864 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. -@node Advanced Calendar/Diary Usage -@section Customizing the Calendar and Diary - - There are many customizations that you can use to make the calendar and -diary suit your personal tastes. - -@menu -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. -@end menu - -@node Calendar Customizing -@subsection Customizing the Calendar - -@vindex calendar-intermonth-text -@cindex calendar layout -@cindex calendar week numbers - The calendar display unfortunately cannot be changed from three -months, but you can customize the whitespace used by setting the -variables: @code{calendar-left-margin}, -@code{calendar-day-header-width}, @code{calendar-day-digit-width}, -@code{calendar-column-width}, and @code{calendar-intermonth-spacing}. -To display text @emph{between} the months, for example week numbers, -customize the variables @code{calendar-intermonth-header} and -@code{calendar-intermonth-text} as described in their documentation. - -@vindex calendar-holiday-marker -@vindex diary-entry-marker -@vindex calenday-today-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date as being a holiday. Its value may be a single-character string to -insert next to the date, or a face name to use for displaying the date. -Likewise, the variable @code{diary-entry-marker} specifies how to mark a -date that has diary entries, and @code{calenday-today-marker} is used by -the function @code{calendar-mark-today} to mark today's date. By -default, the calendar uses faces named @code{holiday}, @code{diary}, and -@code{calendar-today} for these purposes. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex calendar-initial-window-hook - Starting the calendar runs the normal hook -@code{calendar-initial-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill - -@vindex calendar-today-visible-hook -@findex calendar-star-date - The variable @code{calendar-today-visible-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar when the -current date is visible in the window. One use of this hook is to -mark today's date; to do that use either of the functions -@code{calendar-mark-today} or @code{calendar-star-date}: - -@findex calendar-mark-today -@smallexample -(add-hook 'calendar-today-visible-hook 'calendar-mark-today) -@end smallexample - -@vindex calendar-today-invisible-hook -@noindent - A similar normal hook, @code{calendar-today-invisible-hook} is run if -the current date is @emph{not} visible in the window. - -@vindex calendar-move-hook - Each of the calendar cursor motion commands runs the hook -@code{calendar-move-hook} after it moves the cursor. - -@node Holiday Customizing -@subsection Customizing the Holidays - -@vindex calendar-holidays -@vindex holiday-oriental-holidays -@vindex holiday-solar-holidays - Emacs knows about holidays defined by entries on one of several lists. -The lists of holidays that Emacs uses are for -general holidays (@code{holiday-general-holidays}), -local holidays (@code{holiday-local-holidays}), -sun- and moon-related holidays (@code{holiday-solar-holidays}), -Baha'i holidays (@code{holiday-bahai-holidays}), -Christian holidays (@code{holiday-christian-holidays}), -Hebrew (Jewish) holidays (@code{holiday-hebrew-holidays}), -Islamic (Muslim) holidays (@code{holiday-islamic-holidays}), -Oriental holidays (@code{holiday-oriental-holidays}), -and other holidays (@code{holiday-other-holidays}). - -You can customize these lists of holidays to your own needs, deleting or -adding holidays as described below. Set any of them to @code{nil} to -eliminate the associated holidays. - -@vindex holiday-general-holidays - The general holidays are, by default, holidays common throughout the -United States. - -@vindex holiday-local-holidays - There are no default local holidays, but your site may supply some. - -@vindex holiday-bahai-holidays -@vindex holiday-christian-holidays -@vindex holiday-hebrew-holidays -@vindex holiday-islamic-holidays -@vindex calendar-bahai-all-holidays-flag -@vindex calendar-christian-all-holidays-flag -@vindex calendar-hebrew-all-holidays-flag -@vindex calendar-islamic-all-holidays-flag - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{calendar-bahai-all-holidays-flag}, -@code{calendar-christian-all-holidays-flag}, -@code{calendar-hebrew-all-holidays-flag}, or -@code{calendar-islamic-all-holidays-flag} to @code{t}. - -@vindex holiday-other-holidays - You can set the variable @code{holiday-other-holidays} to any list of -holidays. This list, normally empty, is intended for individual use. - -@cindex holiday forms - Each of the holiday variables is a list of @dfn{holiday forms}, each -form describing a holiday (or sometimes a list of holidays). - - Here is a table of the possible kinds of holiday form. Day numbers -and month numbers count starting from 1, but ``dayname'' numbers -count Sunday as 0. The element @var{string} is always the -description of the holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string} - &optional @var{day}) -The @var{k}th @var{dayname} (@var{dayname}=0 for Sunday, and so on) -after or before Gregorian date @var{month}, @var{day}. Negative @var{k} -means count back from the end of the month. Optional @var{day} defaults -to 1 if @var{k} is positive, and the last day of @var{month} otherwise. - -@item (holiday-chinese @var{month} @var{day} @var{string}) -A fixed date on the Chinese calendar. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday in the form of a list @code{(@var{month} @var{day} @var{year})}, -or @code{nil} if the holiday doesn't happen this year. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14 (i.e., the fourteenth day of the seventh month). You -can do this as follows: - -@smallexample -(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Baha'i, -Chinese, Hebrew, Islamic, and Julian calendars too. For example, - -@smallexample -(setq other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} -or the @code{holiday-sexp} form. For example, American presidential -elections occur on the first Tuesday after the first Monday in November -of years divisible by 4: - -@smallexample -(holiday-sexp '(if (zerop (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year))))))) - "US Presidential Election") -@end smallexample - -@noindent -or - -@smallexample -(if (zerop (% displayed-year 4)) - (holiday-fixed 11 - (calendar-extract-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{holiday-other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) -@end smallexample - -@node Date Display Format -@subsection Date Display Format -@vindex calendar-date-display-form - - You can customize the manner of displaying dates in the diary, in mode -lines, and in messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The default ISO date representation is: - -@smallexample -((format "%s-%.2d-%.2d" year (string-to-number month) - (string-to-number day))) -@end smallexample - -@noindent -This specifies a typical American format: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@subsection Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value is: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -Note that few calendar functions return a time of day (at present, only -solar functions). - -@node Diary Customizing -@subsection Customizing the Diary - -@vindex diary-show-holidays-flag - Ordinarily, the mode line of the diary window indicates any holidays -that fall on the date of the diary entries. The process of checking for -holidays can be slow, depending on the defined holidays. In that case, -setting @code{diary-show-holidays-flag} to @code{nil} will speed up the -diary display. - -@vindex diary-number-of-entries - The variable @code{diary-number-of-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{calendar-view-diary-initially-flag} is -@code{t}, as well as the command @kbd{M-x diary}. For example, a value -of 1 (the default) displays only the current day's diary entries, -whereas a value of 2 will also show the next day's entries. The value -can also be a vector of seven integers: for example, if the value is -@code{[0 2 2 2 2 4 1]} then no diary entries appear on Sunday, the -current date's and the next day's diary entries appear Monday through -Thursday, Friday through Monday's entries appear on Friday, while on -Saturday only that day's entries appear. - -@vindex diary-print-entries-hook -@findex diary-print-entries - The variable @code{diary-print-entries-hook} is a normal hook run -after preparation of a temporary buffer containing just the diary -entries currently visible in the diary buffer. (The other, irrelevant -diary entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command @code{lpr-buffer}. If you want to use a -different command to do the printing, just change the value of this -hook. Other uses might include, for example, rearranging the lines into -order by day and time. - -@vindex diary-date-forms - You can customize the form of dates in your diary file by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs -Lisp Reference Manual}) or the symbols @code{month}, @code{day}, -@code{year}, @code{monthname}, and @code{dayname}. All these elements -serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern, as a whole, to match, all of its elements -must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -capitalization and abbreviation (as specified by -@code{calendar-month-abbrev-array} and -@code{calendar-day-abbrev-array}). All the symbols can match @samp{*}; -since @samp{*} in a diary entry means ``any day'', ``any month'', and so -on, it should match regardless of the date being considered. - - The default value of @code{diary-date-forms} in the American style is -provided by @code{diary-american-date-forms}: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Other default styles are provided by @code{diary-european-date-forms} -and @code{diary-iso-date-forms}. - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. For example, the default value of -@code{diary-european-date-forms} is: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Non-Gregorian Diary -@subsection Diary Entries Using non-Gregorian Calendars - - As well as entries based on the standard Gregorian calendar, your -diary can have entries based on Baha'i, Hebrew, or Islamic dates. -Recognition of such entries can be time-consuming, however, and since -most people don't use them, you must explicitly enable their use. If -you want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex diary-nongregorian-listing-hook -@vindex diary-nongregorian-marking-hook -@findex diary-hebrew-list-entries -@findex diary-hebrew-mark-entries -@findex diary-islamic-list-entries -@findex diary-islamic-mark-entries -@findex diary-bahai-list-entries -@findex diary-bahai-mark-entries -@smallexample -(add-hook 'diary-nongregorian-listing-hook 'diary-hebrew-list-entries) -(add-hook 'diary-nongregorian-marking-hook 'diary-hebrew-mark-entries) -@end smallexample - -@noindent -Similarly, for Islamic and Baha'i entries, add -@code{diary-islamic-list-entries} and @code{diary-islamic-mark-entries}, or -@code{diary-bahai-list-entries} and @code{diary-bahai-mark-entries}. - -@vindex diary-bahai-entry-symbol -@vindex diary-hebrew-entry-symbol -@vindex diary-islamic-entry-symbol - These diary entries have the same formats as Gregorian-date diary -entries; except that @code{diary-bahai-entry-symbol} (default @samp{B}) -must precede a Baha'i date, @code{diary-hebrew-entry-symbol} (default -@samp{H}) a Hebrew date, and @code{diary-islamic-entry-symbol} (default -@samp{I}) an Islamic date. Moreover, non-Gregorian month names may not -be abbreviated (because the first three letters are often not unique). -For example, a diary entry for the Hebrew date Heshvan 25 could look -like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is an Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, non-Gregorian entries are -nonmarking if preceded by @code{diary-nonmarking-symbol} (default -@samp{&}). - - Here is a table of commands used in the calendar to create diary -entries that match the selected date and other dates that are similar in -the Baha'i, Hebrew, or Islamic calendars: - -@table @kbd -@item i h d -@code{diary-hebrew-insert-entry} -@item i h m -@code{diary-hebrew-insert-monthly-entry} -@item i h y -@code{diary-hebrew-insert-yearly-entry} -@item i i d -@code{diary-islamic-insert-entry} -@item i i m -@code{diary-islamic-insert-monthly-entry} -@item i i y -@code{diary-islamic-insert-yearly-entry} -@item i B d -@code{diary-bahai-insert-entry} -@item i B m -@code{diary-bahai-insert-monthly-entry} -@item i B y -@code{diary-bahai-insert-yearly-entry} -@end table - -@findex diary-hebrew-insert-entry -@findex diary-hebrew-insert-monthly-entry -@findex diary-hebrew-insert-yearly-entry -@findex diary-islamic-insert-entry -@findex diary-islamic-insert-monthly-entry -@findex diary-islamic-insert-yearly-entry -@findex diary-bahai-insert-entry -@findex diary-bahai-insert-monthly-entry -@findex diary-bahai-insert-yearly-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary -entry at the end of your diary file. You must then insert the rest of -the diary entry. The basic commands add an entry for the specific -non-Gregorian date, the @samp{monthly} commands for the given -non-Gregorian day-within-month in every month, and the @samp{yearly} -commands for the given non-Gregorian day and month in every year. - -@node Fancy Diary Display -@subsection Fancy Diary Display -@vindex diary-display-function -@findex diary-simple-display -@findex diary-fancy-display -@cindex diary buffer - - Diary display works by preparing the diary buffer and then running the -function specified by the variable @code{diary-display-function}. The -default value (@code{diary-simple-display}) hides the irrelevant diary -entries and then displays the buffer. The alternative -@code{diary-fancy-display} displays diary entries and holidays by -copying them into a special buffer that exists only for the sake of -display. Copying to a separate buffer provides an opportunity to change -the displayed text to make it prettier---for example, to sort the -entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with @code{diary-print-entries}. To print a hard copy of a day-by-day -diary for a week, position point on Sunday of that week, type -@kbd{7 d}, and then do @kbd{M-x diary-print-entries}. As usual, the -inclusion of the holidays slows down the display slightly; you can speed -things up by setting the variable @code{diary-show-holidays-flag} to -@code{nil}. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there are -no diary entries, even if that day is a holiday. If you want such days to be -shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill - -@cindex sorting diary entries - If you use the fancy diary display, you can use the normal hook -@code{diary-list-entries-hook} to sort each day's diary entries by their -time of day. Here's how: - -@findex diary-sort-entries -@example -(add-hook 'diary-list-entries-hook 'diary-sort-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. - -@vindex diary-include-string - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file starting with -@code{diary-include-string}: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -include the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included -files can include other files, and so on (you must be careful not to -have a cycle of inclusions, of course). Here is how to enable the -include facility: - -@vindex diary-list-entries-hook -@vindex diary-mark-entries-hook -@findex diary-include-other-diary-files -@findex diary-mark-included-diary-files -@smallexample -(add-hook 'diary-list-entries-hook 'diary-include-other-diary-files) -(add-hook 'diary-mark-entries-hook 'diary-mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -ordinary diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@subsection Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - -@vindex diary-sexp-entry-symbol - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. Sexp entries should be -preceded by @code{diary-sexp-entry-symbol} (default @samp{%%}) in the -diary file. If you use the fancy diary display, sexp entries can -generate the text of the entry depending on the date itself. - -For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this diary entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 8, 1990. - - There is an early reminder diary sexp that includes its entry in the -diary not only on the date of occurrence, but also on earlier dates. -For example, if you want a reminder a week before your anniversary, you -can use - -@findex diary-remind -@smallexample -%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary -@end smallexample - -@noindent -and the fancy diary will show @samp{Ed's anniversary} both on December -15 and on December 22. - -@findex diary-date - The function @code{diary-date} applies to dates described by a month, -day, year combination, each of which can be an integer, a list of -integers, or @code{t} (meaning all values). For example, - -@smallexample -%%(diary-date '(10 11 12) 22 t) Rake leaves -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Rake leaves -@end smallexample - -@noindent -on October 22, November 22, and December 22 of every year. - -@findex diary-float - The function @code{diary-float} allows you to describe diary entries -that apply to dates like the third Friday of November, or the last -Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} -after the first day of @var{month}, where @var{dayname}=0 means Sunday, -1 means Monday, and so on. If @var{n} is negative it counts backward -from the end of @var{month}. The value of @var{month} can be a list of -months, a single month, or @code{t} to specify all months. You can also -use an optional parameter @var{day} to specify the @var{n}th -@var{dayname} on or after/before @var{day} of @var{month}; the value of -@var{day} defaults to 1 if @var{n} is positive and to the last day of -@var{month} if @var{n} is negative. For example, - -@smallexample -%%(diary-float t 1 -1) Pay rent -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Pay rent -@end smallexample - -@noindent -on the last Monday of every month. - - The generality of sexp diary entries lets you specify any diary -entry that you can describe algorithmically. A sexp diary entry -contains an expression that computes whether the entry applies to any -given date. If its value is non-@code{nil}, the entry applies to that -date; otherwise, it does not. The expression can use the variable -@code{date} to find the date being considered; its value is a list -(@var{month} @var{day} @var{year}) that refers to the Gregorian -calendar. - - The sexp diary entry applies to a date when the expression's value -is non-@code{nil}, but some values have more specific meanings. If -the value is a string, that string is a description of the event which -occurs on that date. The value can also have the form -@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to -mark the date in the calendar, and @var{string} is the description of -the event. If @var{mark} is a single-character string, that character -appears next to the date in the calendar. If @var{mark} is a face -name, the date is displayed in that face. If @var{mark} is -@code{nil}, that specifies no particular highlighting for the date. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (cadr date))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-lunar-phases -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-bahai-date -@findex diary-chinese-date -@findex diary-coptic-date -@findex diary-ethiopic-date -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@findex diary-persian-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for today's local times of sunrise and sunset. -@item %%(diary-lunar-phases) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent Julian calendar date. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-bahai-date) -Make a diary entry with today's equivalent Baha'i calendar date. -@item %%(diary-chinese-date) -Make a diary entry with today's equivalent Chinese calendar date. -@item %%(diary-coptic-date) -Make a diary entry with today's equivalent Coptic calendar date. -@item %%(diary-ethiopic-date) -Make a diary entry with today's equivalent Ethiopic calendar date. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent Hebrew calendar date. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent Islamic calendar date. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent Mayan calendar date. -@item %%(diary-persian-date) -Make a diary entry with today's equivalent Persian calendar date. -@end table - -@noindent -For example, including the diary entry - -@smallexample -&%%(diary-hebrew-date) -@end smallexample - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the literal line @samp{&%%(diary-hebrew-date)} appears in -the diary for any date.) - - This function has been used to construct certain standard Hebrew sexp -diary entries: - -@cindex rosh hodesh -@findex diary-hebrew-rosh-hodesh -@cindex parasha, weekly -@findex diary-hebrew-parasha -@cindex candle lighting times -@findex diary-hebrew-sabbath-candles -@cindex omer count -@findex diary-hebrew-omer -@cindex yahrzeits -@findex diary-hebrew-yahrzeit -@table @code -@item %%(diary-hebrew-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-hebrew-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-hebrew-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-hebrew-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-hebrew-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (The -order of the parameters changes according to the calendar date style; -for example in the European style to @var{day}, @var{month}, @var{year}.) -@end table - - All the functions documented above take an optional argument -@var{mark} which specifies how to mark the date in the calendar display. -If one of these functions decides that it applies to a certain date, -it returns a value that contains @var{mark}, as described above. - -@ignore - arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 -@end ignore diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi deleted file mode 100644 index 8b56b656a3f..00000000000 --- a/doc/emacs/calendar.texi +++ /dev/null @@ -1,1715 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Calendar/Diary, Document View, Dired, Top -@chapter The Calendar and the Diary -@cindex calendar -@findex calendar - - Emacs provides the functions of a desk calendar, with a diary of -planned or past events. It also has facilities for managing your -appointments, and keeping track of how much time you spend working on -certain projects. - - To enter the calendar, type @kbd{M-x calendar}; this displays a -three-month calendar centered on the current month, with point on the -current date. With a numeric argument, as in @kbd{C-u M-x calendar}, it -prompts you for the month and year to be the center of the three-month -calendar. The calendar uses its own buffer, whose major mode is -Calendar mode. - - @kbd{Mouse-3} in the calendar brings up a menu of operations on a -particular date; @kbd{Mouse-2} brings up a menu of commonly used -calendar features that are independent of any particular date. To exit -the calendar, type @kbd{q}. - -@iftex - This chapter describes the basic calendar features. -@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information -about more specialized features. -@end iftex - -@menu -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -@ifnottex -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -@end ifnottex -@end menu - -@node Calendar Motion -@section Movement in the Calendar - -@cindex moving inside the calendar - Calendar mode provides commands to move through the calendar in -logical units of time such as days, weeks, months, and years. If you -move outside the three months originally displayed, the calendar -display ``scrolls'' automatically through time to make the selected -date visible. Moving to a date lets you view its holidays or diary -entries, or convert it to other calendars; moving by long time periods -is also useful simply to scroll the calendar. - -@menu -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. -@end menu - -@node Calendar Unit Motion -@subsection Motion by Standard Lengths of Time - - The commands for movement in the calendar buffer parallel the -commands for movement in text. You can move forward and backward by -days, weeks, months, and years. - -@table @kbd -@item C-f -Move point one day forward (@code{calendar-forward-day}). -@item C-b -Move point one day backward (@code{calendar-backward-day}). -@item C-n -Move point one week forward (@code{calendar-forward-week}). -@item C-p -Move point one week backward (@code{calendar-backward-week}). -@item M-@} -Move point one month forward (@code{calendar-forward-month}). -@item M-@{ -Move point one month backward (@code{calendar-backward-month}). -@item C-x ] -Move point one year forward (@code{calendar-forward-year}). -@item C-x [ -Move point one year backward (@code{calendar-backward-year}). -@end table - -@kindex C-f @r{(Calendar mode)} -@findex calendar-forward-day -@kindex C-b @r{(Calendar mode)} -@findex calendar-backward-day -@kindex C-n @r{(Calendar mode)} -@findex calendar-forward-week -@kindex C-p @r{(Calendar mode)} -@findex calendar-backward-week - The day and week commands are natural analogues of the usual Emacs -commands for moving by characters and by lines. Just as @kbd{C-n} -usually moves to the same column in the following line, in Calendar -mode it moves to the same day in the following week. And @kbd{C-p} -moves to the same day in the previous week. - - The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and -@kbd{C-p}, just as they normally are in other modes. - -@kindex M-@} @r{(Calendar mode)} -@findex calendar-forward-month -@kindex M-@{ @r{(Calendar mode)} -@findex calendar-backward-month -@kindex C-x ] @r{(Calendar mode)} -@findex calendar-forward-year -@kindex C-x [ @r{(Calendar mode)} -@findex calendar-forward-year - The commands for motion by months and years work like those for -weeks, but move a larger distance. The month commands @kbd{M-@}} and -@kbd{M-@{} move forward or backward by an entire month. The year -commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a -whole year. - - The easiest way to remember these commands is to consider months and -years analogous to paragraphs and pages of text, respectively. But -the commands themselves are not quite analogous. The ordinary Emacs -paragraph commands move to the beginning or end of a paragraph, -whereas these month and year commands move by an entire month or an -entire year, keeping the same date within the month or year. - - All these commands accept a numeric argument as a repeat count. -For convenience, the digit keys and the minus sign specify numeric -arguments in Calendar mode even without the Meta modifier. For example, -@kbd{100 C-f} moves point 100 days forward from its present location. - -@node Move to Beginning or End -@subsection Beginning or End of Week, Month or Year - - A week (or month, or year) is not just a quantity of days; we think of -weeks (months, years) as starting on particular dates. So Calendar mode -provides commands to move to the beginning or end of a week, month or -year: - -@table @kbd -@kindex C-a @r{(Calendar mode)} -@findex calendar-beginning-of-week -@item C-a -Move point to start of week (@code{calendar-beginning-of-week}). -@kindex C-e @r{(Calendar mode)} -@findex calendar-end-of-week -@item C-e -Move point to end of week (@code{calendar-end-of-week}). -@kindex M-a @r{(Calendar mode)} -@findex calendar-beginning-of-month -@item M-a -Move point to start of month (@code{calendar-beginning-of-month}). -@kindex M-e @r{(Calendar mode)} -@findex calendar-end-of-month -@item M-e -Move point to end of month (@code{calendar-end-of-month}). -@kindex M-< @r{(Calendar mode)} -@findex calendar-beginning-of-year -@item M-< -Move point to start of year (@code{calendar-beginning-of-year}). -@kindex M-> @r{(Calendar mode)} -@findex calendar-end-of-year -@item M-> -Move point to end of year (@code{calendar-end-of-year}). -@end table - - These commands also take numeric arguments as repeat counts, with the -repeat count indicating how many weeks, months, or years to move -backward or forward. - -@vindex calendar-week-start-day -@cindex weeks, which day they start on -@cindex calendar, first day of week - By default, weeks begin on Sunday. To make them begin on Monday -instead, set the variable @code{calendar-week-start-day} to 1. - -@node Specified Dates -@subsection Specified Dates - - Calendar mode provides commands for moving to a particular date -specified in various ways. - -@table @kbd -@item g d -Move point to specified date (@code{calendar-goto-date}). -@item g D -Move point to specified day of year (@code{calendar-goto-day-of-year}). -@item g w -Move point to specified week of year (@code{calendar-iso-goto-week}). -@item o -Center calendar around specified month (@code{calendar-other-month}). -@item . -Move point to today's date (@code{calendar-goto-today}). -@end table - -@kindex g d @r{(Calendar mode)} -@findex calendar-goto-date - @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day -of the month, and then moves to that date. Because the calendar includes all -dates from the beginning of the current era, you must type the year in its -entirety; that is, type @samp{1990}, not @samp{90}. - -@kindex g D @r{(Calendar mode)} -@findex calendar-goto-day-of-year -@kindex g w @r{(Calendar mode)} -@findex calendar-iso-goto-week - @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and -day number, and moves to that date. Negative day numbers count -backward from the end of the year. @kbd{g w} -(@code{calendar-iso-goto-week}) prompts for a year and week number, -and moves to that week. - -@kindex o @r{(Calendar mode)} -@findex calendar-other-month - @kbd{o} (@code{calendar-other-month}) prompts for a month and year, -then centers the three-month calendar around that month. - -@kindex . @r{(Calendar mode)} -@findex calendar-goto-today - You can return to today's date with @kbd{.}@: -(@code{calendar-goto-today}). - -@node Scroll Calendar -@section Scrolling in the Calendar - -@cindex scrolling in the calendar - The calendar display scrolls automatically through time when you -move out of the visible portion. You can also scroll it manually. -Imagine that the calendar window contains a long strip of paper with -the months on it. Scrolling the calendar means moving the strip -horizontally, so that new months become visible in the window. - -@table @kbd -@item > -Scroll calendar one month forward (@code{calendar-scroll-left}). -@item < -Scroll calendar one month backward (@code{calendar-scroll-right}). -@item C-v -@itemx @key{next} -Scroll calendar three months forward -(@code{calendar-scroll-left-three-months}). -@item M-v -@itemx @key{prior} -Scroll calendar three months backward -(@code{calendar-scroll-right-three-months}). -@end table - -@kindex > @r{(Calendar mode)} -@findex calendar-scroll-left -@kindex < @r{(Calendar mode)} -@findex calendar-scroll-right - The most basic calendar scroll commands scroll by one month at a -time. This means that there are two months of overlap between the -display before the command and the display after. @kbd{>} scrolls the -calendar contents one month forward in time. @kbd{<} scrolls the -contents one month backwards in time. - -@kindex C-v @r{(Calendar mode)} -@findex calendar-scroll-left-three-months -@kindex M-v @r{(Calendar mode)} -@findex calendar-scroll-right-three-months - The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire -``screenful''---three months---in analogy with the usual meaning of -these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes -earlier dates visible. These commands take a numeric argument as a -repeat count; in particular, since @kbd{C-u} multiplies the next command -by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and -typing @kbd{C-u M-v} scrolls the calendar backward by a year. - - The function keys @key{next} and @key{prior} are equivalent to -@kbd{C-v} and @kbd{M-v}, just as they are in other modes. - -@node Counting Days -@section Counting Days - -@table @kbd -@item M-= -Display the number of days in the current region -(@code{calendar-count-days-region}). -@end table - -@kindex M-= @r{(Calendar mode)} -@findex calendar-count-days-region - To determine the number of days in the region, type @kbd{M-=} -(@code{calendar-count-days-region}). The numbers of days shown is -@emph{inclusive}; that is, it includes the days specified by mark and -point. - -@node General Calendar -@section Miscellaneous Calendar Commands - -@table @kbd -@item p d -Display day-in-year (@code{calendar-print-day-of-year}). -@item C-c C-l -Regenerate the calendar window (@code{calendar-redraw}). -@item SPC -Scroll the next window up (@code{scroll-other-window}). -@item DEL -Scroll the next window down (@code{scroll-other-window-down}). -@item q -Exit from calendar (@code{calendar-exit}). -@end table - -@kindex p d @r{(Calendar mode)} -@cindex day of year -@findex calendar-print-day-of-year - To display the number of days elapsed since the start of the year, or -the number of days remaining in the year, type the @kbd{p d} command -(@code{calendar-print-day-of-year}). This displays both of those -numbers in the echo area. The count of days elapsed includes the -selected date. The count of days remaining does not include that -date. - -@kindex C-c C-l @r{(Calendar mode)} -@findex calendar-redraw - If the calendar window text gets corrupted, type @kbd{C-c C-l} -(@code{calendar-redraw}) to redraw it. (This can only happen if you use -non-Calendar-mode editing commands.) - -@kindex SPC @r{(Calendar mode)} - In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) -and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other -window (if there is one) up or down, respectively. This is handy when -you display a list of holidays or diary entries in another window. - -@kindex q @r{(Calendar mode)} -@findex exit-calendar -@vindex calendar-remove-frame-by-deleting - To exit from the calendar, type @kbd{q} (@code{calendar-exit}). This -buries all buffers related to the calendar, selecting other buffers. -(If a frame contains a dedicated calendar window, exiting from the -calendar deletes or iconifies that frame depending on the value of -@code{calendar-remove-frame-by-deleting}.) - -@node Writing Calendar Files -@section Writing Calendar Files - - You can write calendars and diary entries to HTML and La@TeX{} files. - -@cindex calendar and HTML - The Calendar HTML commands produce files of HTML code that contain -calendar and diary entries. Each file applies to one month, and has a -name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and -@var{mm} are the four-digit year and two-digit month, respectively. The -variable @code{cal-html-directory} specifies the default output -directory for the HTML files. - -@vindex cal-html-css-default - Diary entries enclosed by @code{<} and @code{>} are interpreted as -HTML tags (for example: this is a diary entry with some red text). You can change the overall -appearance of the displayed HTML pages (for example, the color of -various page elements, header styles) via a stylesheet @file{cal.css} in -the directory containing the HTML files (see the value of the variable -@code{cal-html-css-default} for relevant style settings). - -@kindex t @r{(Calendar mode)} -@table @kbd -@item H m -Generate a one-month calendar (@code{cal-html-cursor-month}). -@item H y -Generate a calendar file for each month of a year, as well as an index -page (@code{cal-html-cursor-year}). By default, this command writes -files to a @var{yyyy} subdirectory - if this is altered some hyperlinks -between years will not work. -@end table - - If the variable @code{cal-html-print-day-number-flag} is -non-@code{nil}, then the monthly calendars show the day-of-the-year -number. The variable @code{cal-html-year-index-cols} specifies the -number of columns in the yearly index page. - -@cindex calendar and La@TeX{} - The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that -prints as a calendar. Depending on the command you use, the printed -calendar covers the day, week, month or year that point is in. - -@kindex t @r{(Calendar mode)} -@table @kbd -@item t m -Generate a one-month calendar (@code{cal-tex-cursor-month}). -@item t M -Generate a sideways-printing one-month calendar -(@code{cal-tex-cursor-month-landscape}). -@item t d -Generate a one-day calendar -(@code{cal-tex-cursor-day}). -@item t w 1 -Generate a one-page calendar for one week -(@code{cal-tex-cursor-week}). -@item t w 2 -Generate a two-page calendar for one week -(@code{cal-tex-cursor-week2}). -@item t w 3 -Generate an ISO-style calendar for one week -(@code{cal-tex-cursor-week-iso}). -@item t w 4 -Generate a calendar for one Monday-starting week -(@code{cal-tex-cursor-week-monday}). -@item t f w -Generate a Filofax-style two-weeks-at-a-glance calendar -(@code{cal-tex-cursor-filofax-2week}). -@item t f W -Generate a Filofax-style one-week-at-a-glance calendar -(@code{cal-tex-cursor-filofax-week}). -@item t y -Generate a calendar for one year -(@code{cal-tex-cursor-year}). -@item t Y -Generate a sideways-printing calendar for one year -(@code{cal-tex-cursor-year-landscape}). -@item t f y -Generate a Filofax-style calendar for one year -(@code{cal-tex-cursor-filofax-year}). -@end table - - Some of these commands print the calendar sideways (in ``landscape -mode''), so it can be wider than it is long. Some of them use Filofax -paper size (3.75in x 6.75in). All of these commands accept a prefix -argument which specifies how many days, weeks, months or years to print -(starting always with the selected one). - - If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), -then the printed calendars show the holidays in @code{calendar-holidays}. -If the variable @code{cal-tex-diary} is non-@code{nil} (the default is -@code{nil}), diary entries are included also (in monthly, filofax, and -iso-week calendars only). If the variable @code{cal-tex-rules} is -non-@code{nil} (the default is @code{nil}), the calendar displays ruled -pages in styles that have sufficient room. Consult the documentation of -the individual cal-tex functions to see which calendars support which -features. - - You can use the variable @code{cal-tex-preamble-extra} to insert extra -La@TeX{} commands in the preamble of the generated document if you need -to. - -@node Holidays -@section Holidays -@cindex holidays - - The Emacs calendar knows about many major and minor holidays, -and can display them. You can add your own holidays to the default list. - -@table @kbd -@item h -Display holidays for the selected date -(@code{calendar-cursor-holidays}). -@item Mouse-3 Holidays -Display any holidays for the date you click on. -@item x -Mark holidays in the calendar window (@code{calendar-mark-holidays}). -@item u -Unmark calendar window (@code{calendar-unmark}). -@item a -List all holidays for the displayed three months in another window -(@code{calendar-list-holidays}). -@item M-x holidays -List all holidays for three months around today's date in another -window. -@item M-x list-holidays -List holidays in another window for a specified range of years. -@end table - -@kindex h @r{(Calendar mode)} -@findex calendar-cursor-holidays -@vindex calendar-view-holidays-initially-flag - To see if any holidays fall on a given date, position point on that -date in the calendar window and use the @kbd{h} command. Alternatively, -click on that date with @kbd{Mouse-3} and then choose @kbd{Holidays} -from the menu that appears. Either way, this displays the holidays for -that date, in the echo area if they fit there, otherwise in a separate -window. - -@kindex x @r{(Calendar mode)} -@findex calendar-mark-holidays -@kindex u @r{(Calendar mode)} -@findex calendar-unmark -@vindex calendar-mark-holidays-flag - To view the distribution of holidays for all the dates shown in the -calendar, use the @kbd{x} command. This displays the dates that are -holidays in a different face. -@iftex -@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing, calendar-holiday-marker}. -@end ifnottex - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -erases any diary marks (@pxref{Diary}). If the variable -@code{calendar-mark-holidays-flag} is non-@code{nil}, creating or -updating the calendar marks holidays automatically. - -@kindex a @r{(Calendar mode)} -@findex calendar-list-holidays - To get even more detailed information, use the @kbd{a} command, which -displays a separate buffer containing a list of all holidays in the -current three-month range. You can use @key{SPC} and @key{DEL} in the -calendar window to scroll that list up and down, respectively. - -@findex holidays - The command @kbd{M-x holidays} displays the list of holidays for the -current month and the preceding and succeeding months; this works even -if you don't have a calendar window. If the variable -@code{calendar-view-holidays-initially-flag} is non-@code{nil}, creating -the calendar displays holidays in this way. If you want the list of -holidays centered around a different month, use @kbd{C-u M-x -holidays}, which prompts for the month and year. - - The holidays known to Emacs include United States holidays and the -major Baha'i, Chinese, Christian, Islamic, and Jewish holidays; also the -solstices and equinoxes. - -@findex list-holidays - The command @kbd{M-x holiday-list} displays the list of holidays for -a range of years. This function asks you for the starting and stopping -years, and allows you to choose all the holidays or one of several -categories of holidays. You can use this command even if you don't have -a calendar window. - - The dates used by Emacs for holidays are based on @emph{current -practice}, not historical fact. For example Veteran's Day began in -1919, but is shown in earlier years. - -@node Sunrise/Sunset -@section Times of Sunrise and Sunset -@cindex sunrise and sunset - - Special calendar commands can tell you, to within a minute or two, the -times of sunrise and sunset for any date. - -@table @kbd -@item S -Display times of sunrise and sunset for the selected date -(@code{calendar-sunrise-sunset}). -@item Mouse-3 Sunrise/sunset -Display times of sunrise and sunset for the date you click on. -@item M-x sunrise-sunset -Display times of sunrise and sunset for today's date. -@item C-u M-x sunrise-sunset -Display times of sunrise and sunset for a specified date. -@item M-x calendar-sunrise-sunset-month -Display times of sunrise and sunset for the selected month. -@end table - -@kindex S @r{(Calendar mode)} -@findex calendar-sunrise-sunset -@findex sunrise-sunset - Within the calendar, to display the @emph{local times} of sunrise and -sunset in the echo area, move point to the date you want, and type -@kbd{S}. Alternatively, click @kbd{Mouse-3} on the date, then choose -@samp{Sunrise/sunset} from the menu that appears. The command @kbd{M-x -sunrise-sunset} is available outside the calendar to display this -information for today's date or a specified date. To specify a date -other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for -the year, month, and day. - - You can display the times of sunrise and sunset for any location and -any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a -longitude, latitude, number of minutes difference from Coordinated -Universal Time, and date, and then tells you the times of sunrise and -sunset for that location on that date. - - Because the times of sunrise and sunset depend on the location on -earth, you need to tell Emacs your latitude, longitude, and location -name before using these commands. Here is an example of what to set: - -@vindex calendar-location-name -@vindex calendar-longitude -@vindex calendar-latitude -@example -(setq calendar-latitude 40.1) -(setq calendar-longitude -88.2) -(setq calendar-location-name "Urbana, IL") -@end example - -@noindent -Use one decimal place in the values of @code{calendar-latitude} and -@code{calendar-longitude}. - - Your time zone also affects the local time of sunrise and sunset. -Emacs usually gets time zone information from the operating system, but -if these values are not what you want (or if the operating system does -not supply them), you must set them yourself. Here is an example: - -@vindex calendar-time-zone -@vindex calendar-standard-time-zone-name -@vindex calendar-daylight-time-zone-name -@example -(setq calendar-time-zone -360) -(setq calendar-standard-time-zone-name "CST") -(setq calendar-daylight-time-zone-name "CDT") -@end example - -@noindent -The value of @code{calendar-time-zone} is the number of minutes -difference between your local standard time and Coordinated Universal -Time (Greenwich time). The values of -@code{calendar-standard-time-zone-name} and -@code{calendar-daylight-time-zone-name} are the abbreviations used in -your time zone. Emacs displays the times of sunrise and sunset -@emph{corrected for daylight saving time}. @xref{Daylight Saving}, -for how daylight saving time is determined. - - As a user, you might find it convenient to set the calendar location -variables for your usual physical location in your @file{.emacs} file. -And when you install Emacs on a machine, you can create a -@file{default.el} file which sets them properly for the typical location -of most users of that machine. @xref{Init File}. - -@node Lunar Phases -@section Phases of the Moon -@cindex phases of the moon -@cindex moon, phases of - - These calendar commands display the dates and times of the phases of -the moon (new moon, first quarter, full moon, last quarter). This -feature is useful for debugging problems that ``depend on the phase of -the moon.'' - -@table @kbd -@item M -Display the dates and times for all the quarters of the moon for the -three-month period shown (@code{calendar-lunar-phases}). -@item M-x lunar-phases -Display dates and times of the quarters of the moon for three months around -today's date. -@end table - -@kindex M @r{(Calendar mode)} -@findex calendar-lunar-phases - Within the calendar, use the @kbd{M} command to display a separate -buffer of the phases of the moon for the current three-month range. The -dates and times listed are accurate to within a few minutes. - -@findex lunar-phases - Outside the calendar, use the command @kbd{M-x lunar-phases} to -display the list of the phases of the moon for the current month and the -preceding and succeeding months. For information about a different -month, use @kbd{C-u M-x lunar-phases}, which prompts for the month and -year. - - The dates and times given for the phases of the moon are given in -local time (corrected for daylight saving, when appropriate). -See the discussion in the previous section. @xref{Sunrise/Sunset}. - -@node Other Calendars -@section Conversion To and From Other Calendars - -@cindex Gregorian calendar - The Emacs calendar displayed is @emph{always} the Gregorian calendar, -sometimes called the ``new style'' calendar, which is used in most of -the world today. However, this calendar did not exist before the -sixteenth century and was not widely used before the eighteenth century; -it did not fully displace the Julian calendar and gain universal -acceptance until the early twentieth century. The Emacs calendar can -display any month since January, year 1 of the current era, but the -calendar displayed is the Gregorian, even for a date at which the -Gregorian calendar did not exist. - - While Emacs cannot display other calendars, it can convert dates to -and from several other calendars. - -@menu -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. -@end menu - -@node Calendar Systems -@subsection Supported Calendar Systems - -@cindex ISO commercial calendar - The ISO commercial calendar is used largely in Europe. - -@cindex Julian calendar - The Julian calendar, named after Julius Caesar, was the one used in Europe -throughout medieval times, and in many countries up until the nineteenth -century. - -@cindex Julian day numbers -@cindex astronomical day numbers - Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed -is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. - -@cindex Hebrew calendar - The Hebrew calendar is used by tradition in the Jewish religion. The -Emacs calendar program uses the Hebrew calendar to determine the dates -of Jewish holidays. Hebrew calendar dates begin and end at sunset. - -@cindex Islamic calendar - The Islamic calendar is used in many predominantly Islamic countries. -Emacs uses it to determine the dates of Islamic holidays. There is no -universal agreement in the Islamic world about the calendar; Emacs uses -a widely accepted version, but the precise dates of Islamic holidays -often depend on proclamation by religious authorities, not on -calculations. As a consequence, the actual dates of observance can vary -slightly from the dates computed by Emacs. Islamic calendar dates begin -and end at sunset. - -@cindex French Revolutionary calendar - The French Revolutionary calendar was created by the Jacobins after the 1789 -revolution, to represent a more secular and nature-based view of the annual -cycle, and to install a 10-day week in a rationalization measure similar to -the metric system. The French government officially abandoned this -calendar at the end of 1805. - -@cindex Mayan calendar - The Maya of Central America used three separate, overlapping calendar -systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. -Emacs knows about all three of these calendars. Experts dispute the -exact correlation between the Mayan calendar and our calendar; Emacs uses the -Goodman-Martinez-Thompson correlation in its calculations. - -@cindex Coptic calendar -@cindex Ethiopic calendar - The Copts use a calendar based on the ancient Egyptian solar calendar. -Their calendar consists of twelve 30-day months followed by an extra -five-day period. Once every fourth year they add a leap day to this -extra period to make it six days. The Ethiopic calendar is identical in -structure, but has different year numbers and month names. - -@cindex Persian calendar - The Persians use a solar calendar based on a design of Omar Khayyam. -Their calendar consists of twelve months of which the first six have 31 -days, the next five have 30 days, and the last has 29 in ordinary years -and 30 in leap years. Leap years occur in a complicated pattern every -four or five years. -The calendar implemented here is the arithmetical Persian calendar -championed by Birashk, based on a 2,820-year cycle. It differs from -the astronomical Persian calendar, which is based on astronomical -events. As of this writing the first future discrepancy is projected -to occur on March 20, 2025. It is currently not clear what the -official calendar of Iran will be that far into the future. - -@cindex Chinese calendar - The Chinese calendar is a complicated system of lunar months arranged -into solar years. The years go in cycles of sixty, each year containing -either twelve months in an ordinary year or thirteen months in a leap -year; each month has either 29 or 30 days. Years, ordinary months, and -days are named by combining one of ten ``celestial stems'' with one of -twelve ``terrestrial branches'' for a total of sixty names that are -repeated in a cycle of sixty. - -@cindex Baha'i calendar - The Baha'i calendar system is based on a solar cycle of 19 months with -19 days each. The four remaining ``intercalary'' days are placed -between the 18th and 19th months. - -@node To Other Calendar -@subsection Converting To Other Calendars - - The following commands describe the selected date (the date at point) -in various other calendar systems: - -@table @kbd -@item Mouse-3 Other calendars -Display the date that you click on, expressed in various other calendars. -@kindex p @r{(Calendar mode)} -@findex calendar-print-other-dates -@item p o -Display the selected date in various other calendars. -(@code{calendar-print-other-dates}). -@findex calendar-iso-print-date -@item p c -Display ISO commercial calendar equivalent for selected day -(@code{calendar-iso-print-date}). -@findex calendar-julian-print-date -@item p j -Display Julian date for selected day (@code{calendar-julian-print-date}). -@findex calendar-astro-print-day-number -@item p a -Display astronomical (Julian) day number for selected day -(@code{calendar-astro-print-day-number}). -@findex calendar-hebrew-print-date -@item p h -Display Hebrew date for selected day (@code{calendar-hebrew-print-date}). -@findex calendar-islamic-print-date -@item p i -Display Islamic date for selected day (@code{calendar-islamic-print-date}). -@findex calendar-french-print-date -@item p f -Display French Revolutionary date for selected day -(@code{calendar-french-print-date}). -@findex calendar-bahai-print-date -@item p b -Display Baha'i date for selected day -(@code{calendar-bahai-print-date}). -@findex calendar-chinese-print-date -@item p C -Display Chinese date for selected day -(@code{calendar-chinese-print-date}). -@findex calendar-coptic-print-date -@item p k -Display Coptic date for selected day -(@code{calendar-coptic-print-date}). -@findex calendar-ethiopic-print-date -@item p e -Display Ethiopic date for selected day -(@code{calendar-ethiopic-print-date}). -@findex calendar-persian-print-date -@item p p -Display Persian date for selected day -(@code{calendar-persian-print-date}). -@findex calendar-mayan-print-date -@item p m -Display Mayan date for selected day (@code{calendar-mayan-print-date}). -@end table - - If you are using a graphic display, the easiest way to translate a -date into other calendars is to click on it with @kbd{Mouse-3}, then -choose @kbd{Other calendars} from the menu that appears. This displays -the equivalent forms of the date in all the calendars Emacs understands, -in the form of a menu. (Choosing an alternative from this menu doesn't -actually do anything---the menu is used only for display.) - - Otherwise, move point to the date you want to convert, then type the -appropriate command starting with @kbd{p} from the table above. The -prefix @kbd{p} is a mnemonic for ``print,'' since Emacs ``prints'' the -equivalent date in the echo area. @kbd{p o} displays the -date in all forms known to Emacs. - -@node From Other Calendar -@subsection Converting From Other Calendars - - You can use the other supported calendars to specify a date to move -to. This section describes the commands for doing this using calendars -other than Mayan; for the Mayan calendar, see the following section. - -@kindex g @var{char} @r{(Calendar mode)} -@findex calendar-iso-goto-date -@findex calendar-iso-goto-week -@findex calendar-julian-goto-date -@findex calendar-astro-goto-day-number -@findex calendar-bahai-goto-date -@findex calendar-hebrew-goto-date -@findex calendar-islamic-goto-date -@findex calendar-french-goto-date -@findex calendar-chinese-goto-date -@findex calendar-persian-goto-date -@findex calendar-coptic-goto-date -@findex calendar-ethiopic-goto-date -@table @kbd -@item g c -Move to a date specified in the ISO commercial calendar -(@code{calendar-iso-goto-date}). -@item g w -Move to a week specified in the ISO commercial calendar -(@code{calendar-iso-goto-week}). -@item g j -Move to a date specified in the Julian calendar -(@code{calendar-julian-goto-date}). -@item g a -Move to a date specified with an astronomical (Julian) day number -(@code{calendar-astro-goto-day-number}). -@item g b -Move to a date specified in the Baha'i calendar -(@code{calendar-bahai-goto-date}). -@item g h -Move to a date specified in the Hebrew calendar -(@code{calendar-hebrew-goto-date}). -@item g i -Move to a date specified in the Islamic calendar -(@code{calendar-islamic-goto-date}). -@item g f -Move to a date specified in the French Revolutionary calendar -(@code{calendar-french-goto-date}). -@item g C -Move to a date specified in the Chinese calendar -(@code{calendar-chinese-goto-date}). -@item g p -Move to a date specified in the Persian calendar -(@code{calendar-persian-goto-date}). -@item g k -Move to a date specified in the Coptic calendar -(@code{calendar-coptic-goto-date}). -@item g e -Move to a date specified in the Ethiopic calendar -(@code{calendar-ethiopic-goto-date}). -@end table - - These commands ask you for a date on the other calendar, move point to -the Gregorian calendar date equivalent to that date, and display the -other calendar's date in the echo area. Emacs uses strict completion -(@pxref{Strict Completion}) whenever it asks you to type a month name, so you -don't have to worry about the spelling of Hebrew, Islamic, or French names. - -@c FIXME move? -@findex calendar-hebrew-list-yahrzeits -@cindex yahrzeits - One common question concerning the Hebrew calendar is the computation -of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs -calendar includes a facility for such calculations. If you are in the -calendar, the command @kbd{M-x calendar-hebrew-list-yahrzeits} asks you for -a range of years and then displays a list of the yahrzeit dates for those -years for the date given by point. If you are not in the calendar, -this command first asks you for the date of death and the range of -years, and then displays the list of yahrzeit dates. - -@node Mayan Calendar -@subsection Converting from the Mayan Calendar - - Here are the commands to select dates based on the Mayan calendar: - -@table @kbd -@item g m l -Move to a date specified by the long count calendar -(@code{calendar-mayan-goto-long-count-date}). -@item g m n t -Move to the next occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-next-tzolkin-date}). -@item g m p t -Move to the previous occurrence of a place in the -tzolkin calendar (@code{calendar-mayan-previous-tzolkin-date}). -@item g m n h -Move to the next occurrence of a place in the -haab calendar (@code{calendar-mayan-next-haab-date}). -@item g m p h -Move to the previous occurrence of a place in the -haab calendar (@code{calendar-mayan-previous-haab-date}). -@item g m n c -Move to the next occurrence of a place in the -calendar round (@code{calendar-mayan-next-calendar-round-date}). -@item g m p c -Move to the previous occurrence of a place in the -calendar round (@code{calendar-mayan-previous-calendar-round-date}). -@end table - -@cindex Mayan long count - To understand these commands, you need to understand the Mayan calendars. -The @dfn{long count} is a counting of days with these units: - -@display -1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal -1 katun = 20 tun@ @ @ 1 baktun = 20 katun -@end display - -@kindex g m @r{(Calendar mode)} -@findex calendar-mayan-goto-long-count-date -@noindent -Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 -tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long -count dates as early as 7.17.18.13.3, but no earlier. When you use the -@kbd{g m l} command, type the Mayan long count date with the baktun, -katun, tun, uinal, and kin separated by periods. - -@findex calendar-mayan-previous-tzolkin-date -@findex calendar-mayan-next-tzolkin-date -@cindex Mayan tzolkin calendar - The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of -independent cycles of 13 and 20 days. Since this cycle repeats -endlessly, Emacs provides commands to move backward and forward to the -previous or next point in the cycle. Type @kbd{g m p t} to go to the -previous tzolkin date; Emacs asks you for a tzolkin date and moves point -to the previous occurrence of that date. Similarly, type @kbd{g m n t} -to go to the next occurrence of a tzolkin date. - -@findex calendar-mayan-previous-haab-date -@findex calendar-mayan-next-haab-date -@cindex Mayan haab calendar - The Mayan haab calendar is a cycle of 365 days arranged as 18 months -of 20 days each, followed a 5-day monthless period. Like the tzolkin -cycle, this cycle repeats endlessly, and there are commands to move -backward and forward to the previous or next point in the cycle. Type -@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab -date and moves point to the previous occurrence of that date. -Similarly, type @kbd{g m n h} to go to the next occurrence of a haab -date. - -@c This is omitted because it is too long for smallbook format. -@c @findex calendar-mayan-previous-calendar-round-date -@findex calendar-mayan-next-calendar-round-date -@cindex Mayan calendar round - The Maya also used the combination of the tzolkin date and the haab -date. This combination is a cycle of about 52 years called a -@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for -both a haab and a tzolkin date and then moves point to the previous -occurrence of that combination. Use @kbd{g m n c} to move point to the -next occurrence of a combination. These commands signal an error if the -haab/tzolkin date combination you have typed is impossible. - - Emacs uses strict completion (@pxref{Strict Completion}) whenever it -asks you to type a Mayan name, so you don't have to worry about -spelling. - -@node Diary -@section The Diary -@cindex diary - - The Emacs diary keeps track of appointments or other events on a daily -basis, in conjunction with the calendar. To use the diary feature, you -must first create a @dfn{diary file} containing a list of events and -their dates. Then Emacs can automatically pick out and display the -events for today, for the immediate future, or for any specified -date. - - The name of the diary file is specified by the variable -@code{diary-file}; @file{~/diary} is the default. Here's an example -showing what that file looks like: - -@example -12/22/1988 Twentieth wedding anniversary!! -&1/1. Happy New Year! -10/22 Ruth's birthday. -* 21, *: Payday -Tuesday--weekly meeting with grad students at 10am - Supowit, Shen, Bitner, and Kapoor to attend. -1/13/89 Friday the thirteenth!! -&thu 4pm squash game with Lloyd. -mar 16 Dad's birthday -April 15, 1989 Income tax due. -&* 15 time cards due. -@end example - -@noindent -This format is essentially the same as the one used by the system's -@command{calendar} utility. This example uses extra spaces to align -the event descriptions of most of the entries. Such formatting is -purely a matter of taste. - - Although you probably will start by creating a diary manually, Emacs -provides a number of commands to let you view, add, and change diary -entries. - -@menu -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. -@end menu - -@node Displaying the Diary -@subsection Displaying the Diary - - Once you have created a diary file, you can use the calendar to view -it. You can also view today's events outside of Calendar mode. - -@table @kbd -@item d -Display all diary entries for the selected date -(@code{diary-view-entries}). -@item Mouse-3 Diary -Display all diary entries for the date you click on. -@item s -Display the entire diary file (@code{diary-show-all-entries}). -@item m -Mark all visible dates that have diary entries -(@code{diary-mark-entries}). -@item u -Unmark the calendar window (@code{calendar-unmark}). -@item M-x diary-print-entries -Print hard copy of the diary display as it appears. -@item M-x diary -Display all diary entries for today's date. -@item M-x diary-mail-entries -Mail yourself email reminders about upcoming diary entries. -@end table - -@kindex d @r{(Calendar mode)} -@findex diary-view-entries -@vindex calendar-view-diary-initially-flag - Displaying the diary entries with @kbd{d} shows in a separate window -the diary entries for the selected date in the calendar. The mode line -of the new window shows the date of the diary entries and any holidays -that fall on that date. If you specify a numeric argument with @kbd{d}, -it shows all the diary entries for that many successive days. Thus, -@kbd{2 d} displays all the entries for the selected date and for the -following day. - - Another way to display the diary entries for a date is to click -@kbd{Mouse-3} on the date, and then choose @kbd{Diary entries} from -the menu that appears. If the variable -@code{calendar-view-diary-initially-flag} is non-@code{nil}, creating the -calendar lists the diary entries for the current date (provided the -current date is visible). - -@kindex m @r{(Calendar mode)} -@findex diary-mark-entries -@vindex calendar-mark-diary-entries-flag - To get a broader view of which days are mentioned in the diary, use -the @kbd{m} command. This displays the dates that have diary entries in -a different face. -@iftex -@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing, diary-entry-marker}. -@end ifnottex - - The command applies both to the currently visible months and to -other months that subsequently become visible by scrolling. To turn -marking off and erase the current marks, type @kbd{u}, which also -turns off holiday marks (@pxref{Holidays}). If the variable -@code{calendar-mark-diary-entries-flag} is non-@code{nil}, creating or -updating the calendar marks diary dates automatically. - -@kindex s @r{(Calendar mode)} -@findex diary-show-all-entries - To see the full diary file, rather than just some of the entries, use -the @kbd{s} command. - - Display of selected diary entries uses invisible text to hide entries -that don't apply. The diary buffer as you see it is an illusion, so -simply printing the buffer does not print what you see on your screen. -There is a special command to print hard copy of the diary buffer -@emph{as it appears}; this command is @kbd{M-x diary-print-entries}. -It sends the data directly to the printer. You can customize it -like @code{lpr-region} (@pxref{Printing}). - -@findex diary - The command @kbd{M-x diary} displays the diary entries for the current -date, independently of the calendar display, and optionally for the next -few days as well; the variable @code{diary-number-of-entries} specifies -how many days to include. -@iftex -@inforef{Diary Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Diary Customizing, diary-number-of-entries}. -@end ifnottex - - If you put @code{(diary)} in your @file{.emacs} file, this -automatically displays a window with the day's diary entries, when you -enter Emacs. The mode line of the displayed window shows the date and -any holidays that fall on that date. - -@findex diary-mail-entries -@vindex diary-mail-days - Many users like to receive notice of events in their diary as email. -To send such mail to yourself, use the command @kbd{M-x -diary-mail-entries}. A prefix argument specifies how many days -(starting with today) to check; otherwise, the variable -@code{diary-mail-days} says how many days. - -@node Format of Diary File -@subsection The Diary File -@cindex diary file - -@vindex diary-file - Your @dfn{diary file} is a file that records events associated with -particular dates. The name of the diary file is specified by the -variable @code{diary-file}; @file{~/diary} is the default. The -@code{calendar} utility program supports a subset of the format allowed -by the Emacs diary facilities, so you can use that utility to view the -diary file, with reasonable results aside from the entries it cannot -understand. - - Each entry in the diary file describes one event and consists of one -or more lines. An entry always begins with a date specification at the -left margin. The rest of the entry is simply text to describe the -event. If the entry has more than one line, then the lines after the -first must begin with whitespace to indicate they continue a previous -entry. Lines that do not begin with valid dates and do not continue a -preceding entry are ignored. - -@vindex diary-nonmarking-symbol - You can inhibit the marking of certain diary entries in the calendar -window; to do this, insert an ampersand @code{diary-nonmarking-symbol} -(default @samp{&}) at the beginning of the entry, before the date. This -has no effect on display of the entry in the diary window; it affects -only marks on dates in the calendar window. Nonmarking entries are -especially useful for generic entries that would otherwise mark many -different dates. - - If the first line of a diary entry consists only of the date or day -name with no following blanks or punctuation, then the diary window -display doesn't include that line; only the continuation lines appear. -For example, this entry: - -@example -02/11/1989 - Bill B. visits Princeton today - 2pm Cognitive Studies Committee meeting - 2:30-5:30 Liz at Lawrenceville - 4:00pm Dentist appt - 7:30pm Dinner at George's - 8:00-10:00pm concert -@end example - -@noindent -appears in the diary window without the date line at the beginning. -This style of entry looks neater when you display just a single day's -entries, but can cause confusion if you ask for more than one day's -entries. - - You can edit the diary entries as they appear in the window, but it is -important to remember that the buffer displayed contains the @emph{entire} -diary file, with portions of it concealed from view. This means, for -instance, that the @kbd{C-f} (@code{forward-char}) command can put point -at what appears to be the end of the line, but what is in reality the -middle of some concealed line. - - @emph{Be careful when editing the diary entries!} Inserting -additional lines or adding/deleting characters in the middle of a -visible line cannot cause problems, but editing at the end of a line may -not do what you expect. Deleting a line may delete other invisible -entries that follow it. Before editing the diary, it is best to display -the entire file with @kbd{s} (@code{diary-show-all-entries}). - -@node Date Formats -@subsection Date Formats - - Here are some sample diary entries, illustrating different ways of -formatting a date. The examples all show dates in American order -(month, day, year), but Calendar mode supports European order (day, -month, year) and ISO order (year, month, day) as options. - -@example -4/20/93 Switch-over to new tabulation system -apr. 25 Start tabulating annual results -4/30 Results for April are due -*/25 Monthly cycle finishes -Friday Don't leave without backing up files -@end example - - The first entry appears only once, on April 20, 1993. The second and -third appear every year on the specified dates, and the fourth uses a -wildcard (asterisk) for the month, so it appears on the 25th of every -month. The final entry appears every week on Friday. - - You can use just numbers to express a date, as in -@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. -This must be followed by a nondigit. In the date itself, @var{month} -and @var{day} are numbers of one or two digits. The optional @var{year} -is also a number, and may be abbreviated to the last two digits; that -is, you can use @samp{11/12/1989} or @samp{11/12/89}. - - Dates can also have the form @samp{@var{monthname} @var{day}} or -@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can -be spelled in full or abbreviated (with or without a period). The -preferred abbreviations for month and day names can be set using -the variables @code{calendar-abbrev-length}, -@code{calendar-month-abbrev-array}, and -@code{calendar-day-abbrev-array}. The default is to use the first three -letters of a name as its abbreviation. Case is not significant. - - A date may be @dfn{generic}; that is, partially unspecified. Then the -entry applies to all dates that match the specification. If the date -does not contain a year, it is generic and applies to any year. -Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*}; -this matches any month, day, or year, respectively. Thus, a diary entry -@samp{3/*/*} matches any day in March of any year; so does @samp{march -*}. - -@vindex calendar-date-style -@findex calendar-set-date-style - If you prefer the European style of writing dates (in which the day -comes before the month), or the ISO style (in which the order is year, -month, day), type @kbd{M-x calendar-set-date-style} while in the -calendar, or customize the variable @code{calendar-date-style}. This -affects how diary dates are interpreted, date display, and the order in -which some commands expect their arguments to be given. - - You can use the name of a day of the week as a generic date which -applies to any date falling on that day of the week. You can abbreviate -the day of the week as described above, or spell it in full; case is not -significant. - -@node Adding to Diary -@subsection Commands to Add to the Diary - - While in the calendar, there are several commands to create diary -entries. The basic commands are listed here; more sophisticated -commands are in the next section (@pxref{Special Diary Entries}). -Entries can also be based on non-Gregorian calendars. -@iftex -@inforef{Non-Gregorian Diary,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Non-Gregorian Diary}. -@end ifnottex - -@table @kbd -@item i d -Add a diary entry for the selected date (@code{diary-insert-entry}). -@item i w -Add a diary entry for the selected day of the week (@code{diary-insert-weekly-entry}). -@item i m -Add a diary entry for the selected day of the month (@code{diary-insert-monthly-entry}). -@item i y -Add a diary entry for the selected day of the year (@code{diary-insert-yearly-entry}). -@end table - -@kindex i d @r{(Calendar mode)} -@findex diary-insert-entry - You can make a diary entry for a specific date by selecting that date -in the calendar window and typing the @kbd{i d} command. This command -displays the end of your diary file in another window and inserts the -date; you can then type the rest of the diary entry. - -@kindex i w @r{(Calendar mode)} -@findex diary-insert-weekly-entry -@kindex i m @r{(Calendar mode)} -@findex diary-insert-monthly-entry -@kindex i y @r{(Calendar mode)} -@findex diary-insert-yearly-entry - If you want to make a diary entry that applies to a specific day of -the week, select that day of the week (any occurrence will do) and type -@kbd{i w}. This inserts the day-of-week as a generic date; you can then -type the rest of the diary entry. You can make a monthly diary entry in -the same fashion: select the day of the month, use the @kbd{i m} -command, and type the rest of the entry. Similarly, you can insert a -yearly diary entry with the @kbd{i y} command. - - All of the above commands make marking diary entries by default. To -make a nonmarking diary entry, give a numeric argument to the command. -For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. - - When you modify the diary file, be sure to save the file before -exiting Emacs. Saving the diary file after using any of the above -insertion commands will automatically update the diary marks in the -calendar window, if appropriate. You can use the command -@code{calendar-redraw} to force an update at any time. - -@node Special Diary Entries -@subsection Special Diary Entries - - In addition to entries based on calendar dates, the diary file can -contain @dfn{sexp entries} for regular events such as anniversaries. -These entries are based on Lisp expressions (sexps) that Emacs evaluates -as it scans the diary file. Instead of a date, a sexp entry contains -@samp{%%} followed by a Lisp expression which must begin and end with -parentheses. The Lisp expression determines which dates the entry -applies to. - - Calendar mode provides commands to insert certain commonly used -sexp entries: - -@table @kbd -@item i a -Add an anniversary diary entry for the selected date -(@code{diary-insert-anniversary-entry}). -@item i b -Add a block diary entry for the current region -(@code{diary-insert-block-entry}). -@item i c -Add a cyclic diary entry starting at the date -(@code{diary-insert-cyclic-entry}). -@end table - -@kindex i a @r{(Calendar mode)} -@findex diary-insert-anniversary-entry - If you want to make a diary entry that applies to the anniversary of a -specific date, move point to that date and use the @kbd{i a} command. -This displays the end of your diary file in another window and inserts -the anniversary description; you can then type the rest of the diary -entry. The entry looks like this: - -@findex diary-anniversary -@example -%%(diary-anniversary 10 31 1948) Arthur's birthday -@end example - -@noindent -This entry applies to October 31 in any year after 1948; @samp{10 31 -1948} specifies the date. (If you are using the European or ISO -calendar style, the input order of month, day and year is different.) -The reason this expression requires a beginning year is that advanced -diary functions can use it to calculate the number of elapsed years. - - A @dfn{block} diary entry applies to a specified range of consecutive -dates. Here is a block diary entry that applies to all dates from June -24, 1990 through July 10, 1990: - -@findex diary-block -@example -%%(diary-block 6 24 1990 7 10 1990) Vacation -@end example - -@noindent -The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990} -indicates the stopping date. (Again, if you are using the European or ISO -calendar style, the input order of month, day and year is different.) - -@kindex i b @r{(Calendar mode)} -@findex diary-insert-block-entry - To insert a block entry, place point and the mark on the two -dates that begin and end the range, and type @kbd{i b}. This command -displays the end of your diary file in another window and inserts the -block description; you can then type the diary entry. - -@kindex i c @r{(Calendar mode)} -@findex diary-insert-cyclic-entry - @dfn{Cyclic} diary entries repeat after a fixed interval of days. To -create one, select the starting date and use the @kbd{i c} command. The -command prompts for the length of interval, then inserts the entry, -which looks like this: - -@findex diary-cyclic -@example -%%(diary-cyclic 50 3 1 1990) Renew medication -@end example - -@noindent -This entry applies to March 1, 1990 and every 50th day following; -@samp{3 1 1990} specifies the starting date. (If you are using the -European or ISO calendar style, the input order of month, day and year -is different.) - - All three of these commands make marking diary entries. To insert a -nonmarking entry, give a numeric argument to the command. For example, -@kbd{C-u i a} makes a nonmarking anniversary diary entry. - - Marking sexp diary entries in the calendar is @emph{extremely} -time-consuming, since every date visible in the calendar window must be -individually checked. So it's a good idea to make sexp diary entries -nonmarking (with @samp{&}) when possible. - - Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, -specifies a regularly occurring event by offsets specified in days, -weeks, and months. It is comparable to a crontab entry interpreted by -the @code{cron} utility. Here is a nonmarking, floating diary entry -that applies to the fourth Thursday in November: - -@findex diary-float -@example -&%%(diary-float 11 4 4) American Thanksgiving -@end example - -@noindent -The 11 specifies November (the eleventh month), the 4 specifies Thursday -(the fourth day of the week, where Sunday is numbered zero), and the -second 4 specifies the fourth Thursday (1 would mean ``first,'' 2 would -mean ``second,'' @minus{}2 would mean ``second-to-last,'' and so on). -The month can be a single month or a list of months. Thus you could change -the 11 above to @samp{'(1 2 3)} and have the entry apply to the last -Thursday of January, February, and March. If the month is @code{t}, the -entry applies to all months of the year.@refill - - Each of the standard sexp diary entries takes an optional parameter -specifying the name of a face or a single-character string to use when -marking the entry in the calendar. Most generally, sexp diary entries -can perform arbitrary computations to determine when they apply. -@iftex -@inforef{Sexp Diary Entries,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Sexp Diary Entries}. -@end ifnottex - -@node Appointments -@section Appointments -@cindex appointment notification - -@vindex appt-display-format -@vindex appt-audible -@vindex appt-display-mode-line - If you have a diary entry for an appointment, and that diary entry -begins with a recognizable time of day, Emacs can warn you several -minutes beforehand that that appointment is pending. Emacs alerts you -to the appointment by displaying a message in your chosen format, as -specified by the variable @code{appt-display-format}. If the value of -@code{appt-audible} is non-@code{nil}, the warning includes an audible -reminder. In addition, if @code{appt-display-mode-line} is -non-@code{nil}, Emacs displays the number of minutes to the -appointment on the mode line. - -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex appt-delete-window-function - If @code{appt-display-format} has the value @code{window}, then the -variable @code{appt-display-duration} controls how long the reminder -window is visible for; and the variables -@code{appt-disp-window-function} and @code{appt-delete-window-function} -give the names of functions used to create and destroy the window, -respectively. - -@findex appt-activate - To enable appointment notification, use the command @kbd{M-x -appt-activate}. With a positive argument, it enables notification; -with a negative argument, it disables notification; with no argument, -it toggles. Enabling notification also sets up an appointment list -for today from the diary file, giving all diary entries found with -recognizable times of day, and reminds you just before each of them. - - For example, suppose the diary file contains these lines: - -@example -Monday - 9:30am Coffee break - 12:00pm Lunch -@end example - -@vindex appt-message-warning-time -@noindent -Then on Mondays, you will be reminded at around 9:20am about your -coffee break and at around 11:50am about lunch. The variable -@code{appt-message-warning-time} specifies how many minutes (default 12) -in advance to warn you. - - You can write times in am/pm style (with @samp{12:00am} standing -for midnight and @samp{12:00pm} standing for noon), or 24-hour -European/military style. You need not be consistent; your diary file -can have a mixture of the two styles. Times must be at the beginning of -diary entries if they are to be recognized. - -@vindex appt-display-diary - Emacs updates the appointments list from the diary file -automatically just after midnight. You can force an update at any -time by re-enabling appointment notification. Both these actions also -display the day's diary buffer, unless you set -@code{appt-display-diary} to @code{nil}. The appointments list is -also updated whenever the diary file is saved. - -@findex appt-add -@findex appt-delete -@cindex alarm clock - You can also use the appointment notification facility like an alarm -clock. The command @kbd{M-x appt-add} adds entries to the appointment -list without affecting your diary file. You delete entries from the -appointment list with @kbd{M-x appt-delete}. - -@node Importing Diary -@section Importing and Exporting Diary Entries - - You can transfer diary entries between Emacs diary files and a -variety of other formats. - -@vindex diary-outlook-formats - You can import diary entries from Outlook-generated appointment -messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x -diary-from-outlook} to import the entry. You can make this command -recognize additional appointment message formats by customizing the -variable @code{diary-outlook-formats}. - -@cindex iCalendar support - The icalendar package allows you to transfer data between your Emacs -diary file and iCalendar files, which are defined in ``RFC -2445---Internet Calendaring and Scheduling Core Object Specification -(iCalendar)'' (as well as the earlier vCalendar format). - -@c Importing works for ``ordinary'' (i.e. non-recurring) events, but -@c (at present) may not work correctly (if at all) for recurring events. -@c Exporting of diary files into iCalendar files should work correctly -@c for most diary entries. This feature is a work in progress, so the -@c commands may evolve in future. - -@findex icalendar-import-buffer - The command @code{icalendar-import-buffer} extracts -iCalendar data from the current buffer and adds it to your (default) -diary file. This function is also suitable for automatic extraction of -iCalendar data; for example with the Rmail mail client one could use: - -@example -(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) -@end example - -@findex icalendar-import-file - The command @code{icalendar-import-file} imports an iCalendar file -and adds the results to an Emacs diary file. For example: - -@example -(icalendar-import-file "/here/is/calendar.ics" - "/there/goes/ical-diary") -@end example - -@noindent -You can use an @code{#include} directive to add the import file contents -to the main diary file, if these are different files. -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display}. -@end ifnottex - - -@findex icalendar-export-file, icalendar-export-region - Use @code{icalendar-export-file} to interactively export an entire -Emacs diary file to iCalendar format. To export only a part of a diary -file, mark the relevant area, and call @code{icalendar-export-region}. -In both cases the result is appended to the target file. - -@node Daylight Saving -@section Daylight Saving Time -@cindex daylight saving time - - Emacs understands the difference between standard time and daylight -saving time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight saving time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts. If the resulting rules are not what you want, -you can tell Emacs the rules to use by setting certain variables: -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. - - These values should be Lisp expressions that refer to the variable -@code{year}, and evaluate to the Gregorian date on which daylight -saving time starts or (respectively) ends, in the form of a list -@code{(@var{month} @var{day} @var{year})}. The values should be -@code{nil} if your area does not use daylight saving time. - - Emacs uses these expressions to determine the starting date of -daylight saving time for the holiday list and for correcting times of -day in the solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -(calendar-nth-named-day 2 0 3 year) -(calendar-nth-named-day 1 0 11 year) -@end example - -@noindent -That is, the second 0th day (Sunday) of the third month (March) in -the year specified by @code{year}, and the first Sunday of the eleventh month -(November) of that year. If daylight saving time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - If there is no daylight saving time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight saving time and standard time, measured in -minutes. The value for Cambridge, Massachusetts is 60. - -@c @vindex calendar-daylight-savings-starts-time too long! -@vindex calendar-daylight-savings-ends-time - Finally, the two variables -@code{calendar-daylight-savings-starts-time} and -@code{calendar-daylight-savings-ends-time} specify the number of -minutes after midnight local time when the transition to and from -daylight saving time should occur. For Cambridge, Massachusetts both -variables' values are 120. - -@node Time Intervals -@section Summing Time Intervals -@cindex time intervals, summing -@cindex summing time intervals -@cindex timeclock - - The timeclock package adds up time intervals, so you can (for -instance) keep track of how much time you spend working on particular -projects. - -@findex timeclock-in -@findex timeclock-out -@findex timeclock-change -@findex timeclock-workday-remaining -@findex timeclock-when-to-leave - Use the @kbd{M-x timeclock-in} command when you start working on a -project, and @kbd{M-x timeclock-out} command when you're done. Each -time you do this, it adds one time interval to the record of the -project. You can change to working on a different project with @kbd{M-x -timeclock-change}. - - Once you've collected data from a number of time intervals, you can use -@kbd{M-x timeclock-workday-remaining} to see how much time is left to -work today (assuming a typical average of 8 hours a day), and @kbd{M-x -timeclock-when-to-leave} which will calculate when you're ``done.'' - -@vindex timeclock-modeline-display -@findex timeclock-modeline-display - If you want Emacs to display the amount of time ``left'' of your -workday in the mode line, either customize the -@code{timeclock-modeline-display} variable and set its value to -@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. - -@vindex timeclock-ask-before-exiting - Terminating the current Emacs session might or might not mean that -you have stopped working on the project and, by default, Emacs asks -you. You can, however, set customize the value of the variable -@code{timeclock-ask-before-exiting} to @code{nil} to avoid the question; -then, only an explicit @kbd{M-x timeclock-out} or @kbd{M-x -timeclock-change} will tell Emacs that the current interval is over. - -@cindex @file{.timelog} file -@vindex timeclock-file -@findex timeclock-reread-log - The timeclock functions work by accumulating the data in a file -called @file{.timelog} in your home directory. You can specify a -different name for this file by customizing the variable -@code{timeclock-file}. If you edit the timeclock file manually, or if -you change the value of any of timeclock's customizable variables, you -should run the command @kbd{M-x timeclock-reread-log} to update the -data in Emacs from the file. - -@ifnottex -@include cal-xtra.texi -@end ifnottex - -@ignore - arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 -@end ignore diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi deleted file mode 100644 index 2d4d8b3d1a1..00000000000 --- a/doc/emacs/cmdargs.texi +++ /dev/null @@ -1,1414 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Emacs Invocation, X Resources, GNU Free Documentation License, Top -@appendix Command Line Arguments for Emacs Invocation -@cindex command line arguments -@cindex arguments (command line) -@cindex options (command line) -@cindex switches (command line) -@cindex startup (command line arguments) -@cindex invocation (command line arguments) - - Emacs supports command line arguments to request various actions -when invoking Emacs. These are for compatibility with other editors -and for sophisticated activities. We don't recommend using them for -ordinary editing (@xref{Emacs Server}, for a way to access an existing -Emacs job from the command line). - - Arguments starting with @samp{-} are @dfn{options}, and so is -@samp{+@var{linenum}}. All other arguments specify files to visit. -Emacs visits the specified files while it starts up. The last file -specified on the command line becomes the current buffer; the other -files are also visited in other buffers. As with most programs, the -special argument @samp{--} says that all subsequent arguments are file -names, not options, even if they start with @samp{-}. - - Emacs command options can specify many things, such as the size and -position of the X window Emacs uses, its colors, and so on. A few -options support advanced usage, such as running Lisp functions on files -in batch mode. The sections of this chapter describe the available -options, arranged according to their purpose. - - There are two ways of writing options: the short forms that start with -a single @samp{-}, and the long forms that start with @samp{--}. For -example, @samp{-d} is a short form and @samp{--display} is the -corresponding long form. - - The long forms with @samp{--} are easier to remember, but longer to -type. However, you don't have to spell out the whole option name; any -unambiguous abbreviation is enough. When a long option takes an -argument, you can use either a space or an equal sign to separate the -option name and the argument. Thus, you can write either -@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. -We recommend an equal sign because it makes the relationship clearer, -and the tables below always show an equal sign. - -@cindex initial options (command line) -@cindex action options (command line) -@vindex command-line-args - Most options specify how to initialize Emacs, or set parameters for -the Emacs session. We call them @dfn{initial options}. A few options -specify things to do, such as loading libraries or calling Lisp -functions. These are called @dfn{action options}. These and file -names together are called @dfn{action arguments}. The action -arguments are stored as a list of strings in the variable -@code{command-line-args}. (Actually, when Emacs starts up, -@code{command-line-args} contains all the arguments passed from the -command line; during initialization, the initial arguments are removed -from this list when they are processed, leaving only the action -arguments.) - -@menu -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Resume Arguments:: Specifying arguments when you resume a running Emacs. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. -@end menu - -@node Action Arguments -@appendixsec Action Arguments - - Here is a table of action arguments: - -@table @samp -@item @var{file} -@opindex --file -@itemx --file=@var{file} -@opindex --find-file -@itemx --find-file=@var{file} -@opindex --visit -@itemx --visit=@var{file} -@cindex visiting files, command-line argument -@vindex inhibit-startup-buffer-menu -Visit @var{file} using @code{find-file}. @xref{Visiting}. - -When Emacs starts up, it displays the startup buffer in one window, -and the buffer visiting @var{file} in another window -(@pxref{Windows}). If you supply more than one file argument, the -displayed file is the last one specified on the command line; the -other files are visited but their buffers are not shown. - -If the startup buffer is disabled (@pxref{Entering Emacs}), then -@var{file} is visited in a single window if one file argument was -supplied; with two file arguments, Emacs displays the files in two -different windows; with more than two file argument, Emacs displays -the last file specified in one window, plus a Buffer Menu in a -different window (@pxref{Several Buffers}). To inhibit using the -Buffer Menu for this, change the variable -@code{inhibit-startup-buffer-menu} to @code{t}. - -@item +@var{linenum} @var{file} -@opindex +@var{linenum} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} in it. - -@item +@var{linenum}:@var{columnnum} @var{file} -Visit @var{file} using @code{find-file}, then go to line number -@var{linenum} and put point at column number @var{columnnum}. - -@item -l @var{file} -@opindex -l -@itemx --load=@var{file} -@opindex --load -@cindex loading Lisp libraries, command-line argument -Load a Lisp library named @var{file} with the function @code{load}. -@xref{Lisp Libraries}. If @var{file} is not an absolute file name, -the library can be found either in the current directory, or in the -Emacs library search path as specified with @env{EMACSLOADPATH} -(@pxref{General Variables}). - -@strong{Warning:} If previous command-line arguments have visited -files, the current directory is the directory of the last file -visited. - -@item -L @var{dir} -@opindex -L -@itemx --directory=@var{dir} -@opindex --directory -Add directory @var{dir} to the variable @code{load-path}. - -@item -f @var{function} -@opindex -f -@itemx --funcall=@var{function} -@opindex --funcall -@cindex call Lisp functions, command-line argument -Call Lisp function @var{function}. If it is an interactive function -(a command), it reads the arguments interactively just as if you had -called the same function with a key sequence. Otherwise, it calls the -function with no arguments. - -@item --eval=@var{expression} -@opindex --eval -@itemx --execute=@var{expression} -@opindex --execute -@cindex evaluate expression, command-line argument -Evaluate Lisp expression @var{expression}. - -@item --insert=@var{file} -@opindex --insert -@cindex insert file contents, command-line argument -Insert the contents of @var{file} into the @samp{*scratch*} buffer -(@pxref{Lisp Interaction}). This is like what @kbd{M-x insert-file} -does (@pxref{Misc File Ops}). - -@item --kill -@opindex --kill -Exit from Emacs without asking for confirmation. - -@item --help -@opindex --help -Print a usage message listing all available options, then exit -successfully. - -@item --version -@opindex --version -Print Emacs version, then exit successfully. -@end table - -@node Initial Options -@appendixsec Initial Options - - The initial options specify parameters for the Emacs session. This -section describes the more general initial options; some other options -specifically related to the X Window System appear in the following -sections. - - Some initial options affect the loading of the initialization file. -The normal actions of Emacs are to first load @file{site-start.el} if -it exists, then your own initialization file @file{~/.emacs} if it -exists, and finally @file{default.el} if it exists. @xref{Init File}. -Certain options prevent loading of some of these files or substitute -other files for them. - -@table @samp -@item -t @var{device} -@opindex -t -@itemx --terminal=@var{device} -@opindex --terminal -@cindex device for Emacs terminal I/O -Use @var{device} as the device for terminal input and output. -@samp{--terminal} implies @samp{--no-window-system}. - -@item -d @var{display} -@opindex -d -@itemx --display=@var{display} -@opindex --display -@cindex display for Emacs frame -Use the X Window System and use the display named @var{display} to open -the initial Emacs frame. @xref{Display X}, for more details. - -@item -nw -@opindex -nw -@itemx --no-window-system -@opindex --no-window-system -@cindex disable window system -Don't communicate directly with the window system, disregarding the -@env{DISPLAY} environment variable even if it is set. This means that -Emacs uses the terminal from which it was launched for all its display -and input. - -@cindex batch mode -@item -batch -@opindex --batch -@itemx --batch -Run Emacs in @dfn{batch mode}. Batch mode is used for running -programs written in Emacs Lisp from shell scripts, makefiles, and so -on. To invoke a Lisp program, use the @samp{-batch} option in -conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval} -(@pxref{Action Arguments}). @xref{Command Example}, for an example. - -In batch mode, Emacs does not display the text being edited, and the -standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} -have their usual effect. Emacs functions that normally print a -message in the echo area will print to either the standard output -stream (@code{stdout}) or the standard error stream (@code{stderr}) -instead. (To be precise, functions like @code{prin1}, @code{princ} -and @code{print} print to @code{stdout}, while @code{message} and -@code{error} print to @code{stderr}.) Functions that normally read -keyboard input from the minibuffer take their input from the -terminal's standard input stream (@code{stdin}) instead. - -@samp{--batch} implies @samp{-q} (do not load an initialization file), -but @file{site-start.el} is loaded nonetheless. It also causes Emacs -to exit after processing all the command options. In addition, it -disables auto-saving except in buffers for which it has been -explicitly requested. - -@item --script @var{file} -@opindex --script -@cindex script mode -Run Emacs in batch mode, like @samp{--batch}, and then read and -execute the Lisp code in @var{file}. - -The normal use of this option is in executable script files that run -Emacs. They can start with this text on the first line - -@example -#!/usr/bin/emacs --script -@end example - -@noindent -which will invoke Emacs with @samp{--script} and supply the name of -the script file as @var{file}. Emacs Lisp then treats @samp{#!} as a -comment delimiter. - -@item -q -@opindex -q -@itemx --no-init-file -@opindex --no-init-file -@cindex bypassing init and @file{default.el} file -@cindex init file, not loading -@cindex @file{default.el} file, not loading -Do not load your Emacs initialization file, and do not load the file -@file{default.el} either (@pxref{Init File}). Regardless of this -switch, @file{site-start.el} is still loaded. When Emacs is invoked -like this, the Customize facility does not allow options to be saved -(@pxref{Easy Customization}). - -@item --no-site-file -@opindex --no-site-file -@cindex @file{site-start.el} file, not loading -Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u} -and @samp{--batch} have no effect on the loading of this file---this -option and @samp{-Q} are the only options that block it. - -@item --no-splash -@opindex --no-splash -@vindex inhibit-startup-screen -@cindex splash screen -@cindex startup message -Do not display a startup screen. You can also achieve this effect by -setting the variable @code{inhibit-startup-screen} to non-@code{nil} -in your initialization file (@pxref{Entering Emacs}). - -@item -Q -@opindex -Q -@itemx --quick -@opindex --quick -Start emacs with minimum customizations. This is like using -@samp{-q}, @samp{--no-site-file}, and @samp{--no-splash} together. - -@item -daemon -@opindex -daemon -@itemx --daemon -@opindex --daemon -Start Emacs as a daemon---after Emacs starts up, it starts the Emacs -server and disconnects from the terminal without opening any frames. -You can then use the @command{emacsclient} command to connect to Emacs -for editing. @xref{Emacs Server}, for information about using Emacs -as a daemon. - -@item -daemon=@var{SERVER-NAME} -Start emacs in background as a daemon, and use @var{SERVER-NAME} as -the server name. - -@item --no-desktop -@opindex --no-desktop -Do not reload any saved desktop. @xref{Saving Emacs Sessions}. - -@item -u @var{user} -@opindex -u -@itemx --user=@var{user} -@opindex --user -@cindex load init file of another user -Load @var{user}'s initialization file instead of your -own@footnote{This option has no effect on MS-Windows.}. - -@item --debug-init -@opindex --debug-init -@cindex errors in init file -Enable the Emacs Lisp debugger for errors in the init file. -@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The -GNU Emacs Lisp Reference Manual}. - -@item --unibyte -@opindex --unibyte -@itemx --no-multibyte -@opindex --no-multibyte -@cindex unibyte operation, command-line argument -Do almost everything with single-byte buffers and strings. -All buffers and strings are unibyte unless you (or a Lisp program) -explicitly ask for a multibyte buffer or string. (Note that Emacs -always loads Lisp files in multibyte mode, even if @samp{--unibyte} is -specified; see @ref{Enabling Multibyte}.) Setting the environment -variable @env{EMACS_UNIBYTE} has the same effect -(@pxref{General Variables}). - -@item --multibyte -@opindex --multibyte -@itemx --no-unibyte -@opindex --no-unibyte -Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs -uses multibyte characters by default, as usual. -@end table - -@node Command Example -@appendixsec Command Argument Example - - Here is an example of using Emacs with arguments and options. It -assumes you have a Lisp program file called @file{hack-c.el} which, when -loaded, performs some useful operation on the current buffer, expected -to be a C program. - -@example -emacs --batch foo.c -l hack-c -f save-buffer >& log -@end example - -@noindent -This says to visit @file{foo.c}, load @file{hack-c.el} (which makes -changes in the visited file), save @file{foo.c} (note that -@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and -then exit back to the shell (because of @samp{--batch}). @samp{--batch} -also guarantees there will be no problem redirecting output to -@file{log}, because Emacs will not assume that it has a display terminal -to work with. - -@node Resume Arguments -@appendixsec Resuming Emacs with Arguments - - You can specify action arguments for Emacs when you resume it after -a suspension. To prepare for this, put the following code in your -@file{.emacs} file (@pxref{Hooks}): - -@c `resume-suspend-hook' is correct. It is the name of a function. -@example -(add-hook 'suspend-hook 'resume-suspend-hook) -(add-hook 'suspend-resume-hook 'resume-process-args) -@end example - - As further preparation, you must execute the shell script -@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} -(if you use bash as your shell). These scripts define an alias named -@code{edit}, which will resume Emacs giving it new command line -arguments such as files to visit. The scripts are found in the -@file{etc} subdirectory of the Emacs distribution. - - Only action arguments work properly when you resume Emacs. Initial -arguments are not recognized---it's too late to execute them anyway. - - Note that resuming Emacs (with or without arguments) must be done from -within the shell that is the parent of the Emacs job. This is why -@code{edit} is an alias rather than a program or a shell script. It is -not possible to implement a resumption command that could be run from -other subjobs of the shell; there is no way to define a command that could -be made the value of @env{EDITOR}, for example. Therefore, this feature -does not take the place of the Emacs Server feature (@pxref{Emacs -Server}). - - The aliases use the Emacs Server feature if you appear to have a -server Emacs running. However, they cannot determine this with complete -accuracy. They may think that a server is still running when in -actuality you have killed that Emacs, because the file -@file{/tmp/esrv@dots{}} still exists. If this happens, find that -file and delete it. - -@node Environment -@appendixsec Environment Variables -@cindex environment variables - - The @dfn{environment} is a feature of the operating system; it -consists of a collection of variables with names and values. Each -variable is called an @dfn{environment variable}; environment variable -names are case-sensitive, and it is conventional to use upper case -letters only. The values are all text strings. - - What makes the environment useful is that subprocesses inherit the -environment automatically from their parent process. This means you -can set up an environment variable in your login shell, and all the -programs you run (including Emacs) will automatically see it. -Subprocesses of Emacs (such as shells, compilers, and version-control -software) inherit the environment from Emacs, too. - -@findex setenv -@findex getenv -@vindex initial-environment - Inside Emacs, the command @kbd{M-x getenv} gets the value of an -environment variable. @kbd{M-x setenv} sets a variable in the Emacs -environment. (Environment variable substitutions with @samp{$} work -in the value just as in file names; see @ref{File Names with $}.) The -variable @code{initial-environment} stores the initial environment -inherited by Emacs. - - The way to set environment variables outside of Emacs depends on the -operating system, and especially the shell that you are using. For -example, here's how to set the environment variable @env{ORGANIZATION} -to @samp{not very much} using Bash: - -@example -export ORGANIZATION="not very much" -@end example - -@noindent -and here's how to do it in csh or tcsh: - -@example -setenv ORGANIZATION "not very much" -@end example - - When Emacs is using the X Window System, various environment -variables that control X work for Emacs as well. See the X -documentation for more information. - -@menu -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. -@end menu - -@node General Variables -@appendixsubsec General Variables - - Here is an alphabetical list of environment variables that have -special meanings in Emacs. Most of these variables are also used by -some other programs. Emacs does not require any of these environment -variables to be set, but it uses their values if they are set. - -@table @env -@item CDPATH -Used by the @code{cd} command to search for the directory you specify, -when you specify a relative directory name. -@item EMACS_UNIBYTE -@cindex unibyte operation, environment variable -Defining this environment variable with a nonempty value directs Emacs -to do almost everything with single-byte buffers and strings. It is -equivalent to using the @samp{--unibyte} command-line option on each -invocation. @xref{Initial Options}. -@item EMACSDATA -Directory for the architecture-independent files that come with Emacs. -This is used to initialize the Lisp variable @code{data-directory}. -@item EMACSDOC -Directory for the documentation string file, -@file{DOC-@var{emacsversion}}. This is used to initialize the Lisp -variable @code{doc-directory}. -@item EMACSLOADPATH -A colon-separated list of directories@footnote{ -Here and below, whenever we say ``colon-separated list of directories,'' -it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, -the directories are separated by semi-colons instead, since DOS/Windows -file names might include a colon after a drive letter.} -to search for Emacs Lisp files---used to initialize @code{load-path}. -@item EMACSPATH -A colon-separated list of directories to search for executable -files---used to initialize @code{exec-path}. -@item EMAIL -@vindex user-mail-address@r{, initialization} -Your email address; used to initialize the Lisp variable -@code{user-mail-address}, which the Emacs mail interface puts into -the @samp{From} header of outgoing messages (@pxref{Mail Headers}). -@item ESHELL -Used for shell-mode to override the @env{SHELL} environment variable. -@item HISTFILE -The name of the file that shell commands are saved in between logins. -This variable defaults to @file{~/.bash_history} if you use Bash, to -@file{~/.sh_history} if you use ksh, and to @file{~/.history} -otherwise. -@item HOME -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is -@file{C:/Documents and Settings/@var{username}/Application Data}, -where @var{username} is your user name), though for backwards -compatibility @file{C:/} will be used instead if a @file{.emacs} file -is found there. -@item HOSTNAME -The name of the machine that Emacs is running on. -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@item INFOPATH -A colon-separated list of directories in which to search for Info files. -@item LC_ALL -@itemx LC_COLLATE -@itemx LC_CTYPE -@itemx LC_MESSAGES -@itemx LC_MONETARY -@itemx LC_NUMERIC -@itemx LC_TIME -@itemx LANG -The user's preferred locale. The locale has six categories, specified -by the environment variables @env{LC_COLLATE} for sorting, -@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system -messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for -numbers, and @env{LC_TIME} for dates and times. If one of these -variables is not set, the category defaults to the value of the -@env{LANG} environment variable, or to the default @samp{C} locale if -@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides -the settings of all the other locale environment variables. - -On MS-Windows, if @env{LANG} is not already set in the environment -when Emacs starts, Emacs sets it based on the system-wide default -language, which you can set in the @samp{Regional Settings} Control Panel -on some versions of MS-Windows. - -The value of the @env{LC_CTYPE} category is -matched against entries in @code{locale-language-names}, -@code{locale-charset-language-names}, and -@code{locale-preferred-coding-systems}, to select a default language -environment and coding system. @xref{Language Environments}. -@item LOGNAME -The user's login name. See also @env{USER}. -@item MAIL -The name of your system mail inbox. -@item MH -Name of setup file for the mh system. (The default is @file{~/.mh_profile}.) -@item NAME -Your real-world name. -@item NNTPSERVER -The name of the news server. Used by the mh and Gnus packages. -@item ORGANIZATION -The name of the organization to which you belong. Used for setting the -`Organization:' header in your posts from the Gnus package. -@item PATH -A colon-separated list of directories in which executables reside. This -is used to initialize the Emacs Lisp variable @code{exec-path}. -@item PWD -If set, this should be the default directory when Emacs was started. -@item REPLYTO -If set, this specifies an initial value for the variable -@code{mail-default-reply-to}. @xref{Mail Headers}. -@item SAVEDIR -The name of a directory in which news articles are saved by default. -Used by the Gnus package. -@item SHELL -The name of an interpreter used to parse and execute programs run from -inside Emacs. -@item SMTPSERVER -The name of the outgoing mail server. Used by the SMTP library -(@pxref{Top,,,smtpmail,Sending mail via SMTP}). -@cindex background mode, on @command{xterm} -@item TERM -The type of the terminal that Emacs is using. This variable must be -set unless Emacs is run in batch mode. On MS-DOS, it defaults to -@samp{internal}, which specifies a built-in terminal emulation that -handles the machine's own display. If the value of @env{TERM} indicates -that Emacs runs in non-windowed mode from @command{xterm} or a similar -terminal emulator, the background mode defaults to @samp{light}, and -Emacs will choose colors that are appropriate for a light background. -@item TERMCAP -The name of the termcap library file describing how to program the -terminal specified by the @env{TERM} variable. This defaults to -@file{/etc/termcap}. -@item TMPDIR -Used by the Emerge package as a prefix for temporary files. -@item TZ -This specifies the current time zone and possibly also daylight -saving time information. On MS-DOS, if @env{TZ} is not set in the -environment when Emacs starts, Emacs defines a default value as -appropriate for the country code returned by DOS. On MS-Windows, Emacs -does not use @env{TZ} at all. -@item USER -The user's login name. See also @env{LOGNAME}. On MS-DOS, this -defaults to @samp{root}. -@item VERSION_CONTROL -Used to initialize the @code{version-control} variable (@pxref{Backup Names}). -@end table - -@node Misc Variables -@appendixsubsec Miscellaneous Variables - -These variables are used only on particular configurations: - -@table @env -@item COMSPEC -On MS-DOS and MS-Windows, the name of the command interpreter to use -when invoking batch files and commands internal to the shell. On MS-DOS -this is also used to make a default value for the @env{SHELL} environment -variable. - -@item NAME -On MS-DOS, this variable defaults to the value of the @env{USER} -variable. - -@item TEMP -@itemx TMP -On MS-DOS and MS-Windows, these specify the name of the directory for -storing temporary files in. - -@item EMACSTEST -On MS-DOS, this specifies a file to use to log the operation of the -internal terminal emulator. This feature is useful for submitting bug -reports. - -@item EMACSCOLORS -On MS-DOS, this specifies the screen colors. It is useful to set them -this way, since otherwise Emacs would display the default colors -momentarily when it starts up. - -The value of this variable should be the two-character encoding of the -foreground (the first character) and the background (the second -character) colors of the default face. Each character should be the -hexadecimal code for the desired color on a standard PC text-mode -display. For example, to get blue text on a light gray background, -specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and -7 is the code of the light gray color. - -The PC display usually supports only eight background colors. However, -Emacs switches the DOS display to a mode where all 16 colors can be used -for the background, so all four bits of the background color are -actually used. - -@item PRELOAD_WINSOCK -On MS-Windows, if you set this variable, Emacs will load and initialize -the network library at startup, instead of waiting until the first -time it is required. - -@item emacs_dir -On MS-Windows, @env{emacs_dir} is a special environment variable, which -indicates the full path of the directory in which Emacs is installed. -If Emacs is installed in the standard directory structure, it -calculates this value automatically. It is not much use setting this -variable yourself unless your installation is non-standard, since -unlike other environment variables, it will be overridden by Emacs at -startup. When setting other environment variables, such as -@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} -rather than hard-coding an absolute path. This allows multiple -versions of Emacs to share the same environment variable settings, and -it allows you to move the Emacs installation directory, without -changing any environment or registry settings. -@end table - -@node MS-Windows Registry -@appendixsubsec The MS-Windows System Registry -@pindex addpm, MS-Windows installation program -@cindex registry, setting environment variables and resources on MS-Windows - -Under MS-Windows, the installation program @command{addpm.exe} adds -values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, -@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the -@file{HKEY_LOCAL_MACHINE} section of the system registry, under -@file{/Software/GNU/Emacs}. It does this because there is no standard -place to set environment variables across different versions of -Windows. Running @command{addpm.exe} is no longer strictly necessary -in recent versions of Emacs, but if you are upgrading from an older -version, running @command{addpm.exe} ensures that you do not have -older registry entries from a previous installation, which may not be -compatible with the latest version of Emacs. - -When Emacs starts, as well as checking the environment, it also checks -the System Registry for those variables and for @env{HOME}, @env{LANG} -and @env{PRELOAD_WINSOCK}. - -To determine the value of those variables, Emacs goes through the -following procedure. First, the environment is checked. If the -variable is not found there, Emacs looks for registry keys by that -name under @file{/Software/GNU/Emacs}; first in the -@file{HKEY_CURRENT_USER} section of the registry, and if not found -there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs -still cannot determine the values, compiled-in defaults are used. - -In addition to the environment variables above, you can also add many -of the settings which on X belong in the @file{.Xdefaults} file -(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. -Settings you add to the @file{HKEY_LOCAL_MACHINE} section will affect -all users of the machine. Settings you add to the -@file{HKEY_CURRENT_USER} section will only affect you, and will -override machine wide settings. - -@node Display X -@appendixsec Specifying the Display Name -@cindex display name (X Window System) -@cindex @env{DISPLAY} environment variable - - The environment variable @env{DISPLAY} tells all X clients, including -Emacs, where to display their windows. Its value is set by default -in ordinary circumstances, when you start an X server and run jobs -locally. Occasionally you may need to specify the display yourself; for -example, if you do a remote login and want to run a client program -remotely, displaying on your local screen. - - With Emacs, the main reason people change the default display is to -let them log into another system, run Emacs on that system, but have the -window displayed at their local terminal. You might need to log in -to another system because the files you want to edit are there, or -because the Emacs executable file you want to run is there. - - The syntax of the @env{DISPLAY} environment variable is -@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the -host name of the X Window System server machine, @var{display} is an -arbitrarily-assigned number that distinguishes your server (X terminal) -from other servers on the same machine, and @var{screen} is a -rarely-used field that allows an X server to control multiple terminal -screens. The period and the @var{screen} field are optional. If -included, @var{screen} is usually zero. - - For example, if your host is named @samp{glasperle} and your server is -the first (or perhaps the only) server listed in the configuration, your -@env{DISPLAY} is @samp{glasperle:0.0}. - - You can specify the display name explicitly when you run Emacs, either -by changing the @env{DISPLAY} variable, or with the option @samp{-d -@var{display}} or @samp{--display=@var{display}}. Here is an example: - -@smallexample -emacs --display=glasperle:0 & -@end smallexample - - You can inhibit the direct use of the window system and GUI with the -@samp{-nw} option. It tells Emacs to display using ordinary @acronym{ASCII} on -its controlling terminal. This is also an initial option. - - Sometimes, security arrangements prevent a program on a remote system -from displaying on your local system. In this case, trying to run Emacs -produces messages like this: - -@smallexample -Xlib: connection to "glasperle:0.0" refused by server -@end smallexample - -@noindent -You might be able to overcome this problem by using the @command{xhost} -command on the local system to give permission for access from your -remote machine. - -@node Font X -@appendixsec Font Specification Options -@cindex font name (X Window System) - - By default, Emacs displays text in X using a twelve point monospace -font. You can specify a different font using the command line option -@samp{-fn @var{font}} (or @samp{--font}, which is an alias for -@samp{-fn}). - -@table @samp -@item -fn @var{font} -@opindex -fn -@itemx --font=@var{font} -@opindex --font -@cindex specify default font from the command line -Use @var{font} as the default font. -@end table - -When passing a font specification to Emacs on the command line, you -may need to ``quote'' it, by enclosing it in quotation marks, if it -contains characters that the shell treats specially (e.g. spaces). -Here is an example: - -@smallexample -emacs -fn "DejaVu Sans Mono-12" -@end smallexample - -@cindex X defaults file -@cindex X resources file - You can also specify the font using your X resources file (usually a -file named @file{.Xdefaults} or @file{.Xresources} in your home -directory), by adding a line like this: - -@smallexample -emacs.font: @var{font} -@end smallexample - -@noindent -You must restart X, or use the @command{xrdb} command, for the X -resources file to take effect. @xref{Resources}. When specifying a -font in your X resources file, you should not quote it. - -@cindex fontconfig - Emacs recognizes two types of fonts: @dfn{client-side} fonts, which -are provided by the Xft and Fontconfig libraries, and -@dfn{server-side} fonts, which are provided by the X server itself. -Most client-side fonts support advanced font features such as -antialiasing and subpixel hinting, while server-side fonts do not. - - There are four different ways to express a ``font name''. The first -format consists of @dfn{Fontconfig patterns}. Fontconfig patterns -match only client-side fonts provided by Xft and Fontconfig, and have -the following form: - -@smallexample -@var{fontname}[-@var{fontsize}][:@var{name1}=@var{values1}][:@var{name2}=@var{values2}]... -@end smallexample - -@noindent -Within this format, any of the elements in braces may be omitted. -Here, @var{fontname} is the ``family name'' of the font, such as -@samp{Monospace} or @samp{DejaVu Serif}; @var{fontsize} is the ``point -size'' of the font (one ``printer's point'' is about 1/72 of an inch); -and the @samp{@var{name}=@var{values}} entries specify settings such -as the slant and weight of the font. Each @var{values} may be a -single value, or a list of values separated by commas. In addition, -some property values are valid with only one kind of property name, in -which case the @samp{@var{name}=} part may be omitted. - -Here is a list of common font properties: - -@table @samp -@item slant -One of @samp{italic}, @samp{oblique} or @samp{roman}. - -@item weight -One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or -@samp{black}. - -@item style -Some fonts define special styles which are a combination of slant and -weight. For instance, the font @samp{Dejavu Sans} defines the style -@samp{book}. This property, if specified, overrides the slant and -weight properties. - -@item width -One of @samp{condensed}, @samp{normal}, or @samp{expanded}. - -@item spacing -One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or -@samp{charcell}. -@end table - -@noindent -Here are some examples of Fontconfig patterns: - -@smallexample -Monospace -Monospace-12 -Monospace-12:bold -DejaVu Sans Mono:bold:italic -Monospace-12:weight=bold:slant=italic -@end smallexample - -See the Fontconfig manual for a more detailed description of -Fontconfig patterns. This manual is located in the file -@file{fontconfig-user.html}, which is distributed with Fontconfig. It -is also available online at -@url{http://fontconfig.org/fontconfig-user.html}. In particular, the -manual describes additional font properties that influence how the -font is hinted, antialiased, or scaled. - - The second way to specify a font is to use a @dfn{GTK font -description}. Like Fontconfig patterns, GTK font descriptions match -only client-side fonts provided by Xft and Fontconfig. They have the -syntax - -@smallexample -@var{fontname} [@var{properties}] [@var{fontsize}] -@end smallexample - -@noindent -where @var{fontname} is the family name, @var{properties} is a list of -property values separated by spaces, and @var{fontsize} is the point -size. The properties that you may specify are as follows: - -@table @samp -@item style -One of @samp{roman}, @samp{italic} or @samp{oblique}. If omitted, the -@samp{roman} style is used. -@item weight -One of @samp{medium}, @samp{ultra-light}, @samp{light}, -@samp{semi-bold}, or @samp{bold}. If omitted, @samp{medium} weight is -used. -@end table - -@noindent -Here are some examples of GTK font descriptions: - -@smallexample -Monospace 12 -Monospace Bold Italic 12 -@end smallexample - -@cindex XLFD -@cindex X Logical Font Description - The third way to specify a font is to use an @dfn{XLFD} (@dfn{X -Logical Font Description}), which is the traditional method for -specifying fonts under X. Each XLFD consists of fourteen words or -numbers, separated by dashes, like this: - -@smallexample --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end smallexample - -@noindent -A wildcard character (@samp{*}) in an XLFD matches any sequence of -characters (including none), and @samp{?} matches any single -character. However, matching is implementation-dependent, and can be -inaccurate when wildcards match dashes in a long name. For reliable -results, supply all 14 dashes and use wildcards only within a field. -Case is insignificant in an XLFD. The syntax for an XLFD is as -follows: - -@smallexample --@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} -@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{registry}-@var{encoding} -@end smallexample - -@noindent -The entries have the following meanings: - -@table @var -@item maker -The name of the font manufacturer. -@item family -The name of the font family (e.g. @samp{courier}). -@item weight -The font weight---normally either @samp{bold}, @samp{medium} or -@samp{light}. Some font names support other values. -@item slant -The font slant---normally @samp{r} (roman), @samp{i} (italic), -@samp{o} (oblique), @samp{ri} (reverse italic), or @samp{ot} (other). -Some font names support other values. -@item widthtype -The font width---normally @samp{condensed}, @samp{extended}, -@samp{semicondensed} or @samp{normal} (some font names support other -values). -@item style -An optional additional style name. Usually it is empty---most long -font names have two hyphens in a row at this point. -@item pixels -The font height, in pixels. -@item height -The font height on the screen, measured in tenths of a printer's -point. This is the point size of the font, times ten. For a given -vertical resolution, @var{height} and @var{pixels} are proportional; -therefore, it is common to specify just one of them and use @samp{*} -for the other. -@item horiz -The horizontal resolution, in pixels per inch, of the screen for which -the font is intended. -@item vert -The vertical resolution, in pixels per inch, of the screen for which -the font is intended. Normally the resolution of the fonts on your -system is the right value for your screen; therefore, you normally -specify @samp{*} for this and @var{horiz}. -@item spacing -This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} -(character cell). -@item width -The average character width, in pixels, multiplied by ten. -@item registry -@itemx encoding -The X font character set that the font depicts. (X font character -sets are not the same as Emacs character sets, but they are similar.) -You can use the @command{xfontsel} program to check which choices you -have. Normally you should use @samp{iso8859} for @var{registry} and -@samp{1} for @var{encoding}. -@end table - - Some fonts have shorter nicknames, which you can use instead of a -normal font specification. For instance, - -@smallexample --misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 -@end smallexample - -@noindent -is equivalent to @samp{6x13}. This is the fourth and final method of -specifying a font. - -@cindex listing system fonts - You will probably want to use a fixed-width default font---that is, -a font in which all characters have the same width. Here's how to use -the @command{fc-list} command to list all fixed-width Xft and -Fontconfig fonts available on your system: - -@example -fc-list :spacing=mono -fc-list :spacing=charcell -@end example - - For server-side X fonts, any font with @samp{m} or @samp{c} in the -@var{spacing} field of the XLFD is a fixed-width font. Here's how to -use the @command{xlsfonts} program to list all the fixed-width fonts -available on your system: - -@example -xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' -xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' -@end example - -@noindent -To see what a particular font looks like, use the @command{xfd} command. -For example: - -@example -xfd -fn 6x13 -@end example - -@noindent -displays the entire font @samp{6x13}. - - While running Emacs, you can set the font of a specific kind of text -(@pxref{Faces}), or of a particular frame (@pxref{Frame Parameters}). - -@node Colors -@appendixsec Window Color Options -@cindex color of window, from command line -@cindex text colors, from command line - -@findex list-colors-display -@cindex available colors - On a color display, you can specify which color to use for various -parts of the Emacs display. To find out what colors are available on -your system, type @kbd{M-x list-colors-display}, or press -@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. -(A particular window system might support many more colors, but the -list displayed by @code{list-colors-display} shows their portable -subset that can be safely used on any display supported by Emacs.) -If you do not specify colors, on windowed displays the default for the -background is white and the default for all other colors is black. On a -monochrome display, the foreground is black, the background is white, -and the border is gray if the display supports that. On terminals, the -background is usually black and the foreground is white. - - Here is a list of the command-line options for specifying colors: - -@table @samp -@item -fg @var{color} -@opindex -fg -@itemx --foreground-color=@var{color} -@opindex --foreground-color -@cindex foreground color, command-line argument -Specify the foreground color. @var{color} should be a standard color -name, or a numeric specification of the color's red, green, and blue -components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. -@item -bg @var{color} -@opindex -bg -@itemx --background-color=@var{color} -@opindex --background-color -@cindex background color, command-line argument -Specify the background color. -@item -bd @var{color} -@opindex -bd -@itemx --border-color=@var{color} -@opindex --border-color -@cindex border color, command-line argument -Specify the color of the border of the X window. -@item -cr @var{color} -@opindex -cr -@itemx --cursor-color=@var{color} -@opindex --cursor-color -@cindex cursor color, command-line argument -Specify the color of the Emacs cursor which indicates where point is. -@item -ms @var{color} -@opindex -ms -@itemx --mouse-color=@var{color} -@opindex --mouse-color -@cindex mouse pointer color, command-line argument -Specify the color for the mouse cursor when the mouse is in the Emacs window. -@item -r -@opindex -r -@itemx -rv -@opindex -rv -@itemx --reverse-video -@opindex --reverse-video -@cindex reverse video, command-line argument -Reverse video---swap the foreground and background colors. -@item --color=@var{mode} -@opindex --color -@cindex standard colors on a character terminal -@cindex override character terminal color support -For a character terminal only, specify the mode of color support. -This option is intended for overriding the number of supported colors -that the character terminal advertises in its @code{termcap} or -@code{terminfo} database. The parameter @var{mode} can be one of the -following: -@table @samp -@item never -@itemx no -Don't use colors even if the terminal's capabilities specify color -support. -@item default -@itemx auto -Same as when @option{--color} is not used at all: Emacs detects at -startup whether the terminal supports colors, and if it does, turns on -colored display. -@item always -@itemx yes -@itemx ansi8 -Turn on the color support unconditionally, and use color commands -specified by the ANSI escape sequences for the 8 standard colors. -@item @var{num} -Use color mode for @var{num} colors. If @var{num} is -1, turn off -color support (equivalent to @samp{never}); if it is 0, use the -default color support for this terminal (equivalent to @samp{auto}); -otherwise use an appropriate standard mode for @var{num} colors. -Depending on your terminal's capabilities, Emacs might be able to turn -on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If -there is no mode that supports @var{num} colors, Emacs acts as if -@var{num} were 0, i.e.@: it uses the terminal's default color support -mode. -@end table -If @var{mode} is omitted, it defaults to @var{ansi8}. -@end table - - For example, to use a coral mouse cursor and a slate blue text cursor, -enter: - -@example -emacs -ms coral -cr 'slate blue' & -@end example - - You can reverse the foreground and background colors through the -@samp{-rv} option or with the X resource @samp{reverseVideo}. - - The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on -text-only terminals as well as on graphical displays. - -@node Window Size X -@appendixsec Options for Window Size and Position -@cindex geometry of Emacs window -@cindex position and size of Emacs frame -@cindex width and height of Emacs frame -@cindex specifying fullscreen for Emacs frame - - Here is a list of the command-line options for specifying size and -position of the initial Emacs frame: - -@table @samp -@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex -g -@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} -@opindex --geometry -@cindex geometry, command-line argument -Specify the size @var{width} and @var{height} (measured in character -columns and lines), and positions @var{xoffset} and @var{yoffset} -(measured in pixels). The @var{width} and @var{height} parameters -apply to all frames, whereas @var{xoffset} and @var{yoffset} only to -the initial frame. - -@item -fs -@opindex -fs -@itemx --fullscreen -@opindex --fullscreen -@cindex fullscreen, command-line argument -Specify that width and height shall be the size of the screen. - -@item -fh -@opindex -fh -@itemx --fullheight -@opindex --fullheight -@cindex fullheight, command-line argument -Specify that the height shall be the height of the screen. - -@item -fw -@opindex -fw -@itemx --fullwidth -@opindex --fullwidth -@cindex fullwidth, command-line argument -Specify that the width shall be the width of the screen. -@end table - -@noindent -In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus - sign or a minus sign. A plus -sign before @var{xoffset} means it is the distance from the left side of -the screen; a minus sign means it counts from the right side. A plus -sign before @var{yoffset} means it is the distance from the top of the -screen, and a minus sign there indicates the distance from the bottom. -The values @var{xoffset} and @var{yoffset} may themselves be positive or -negative, but that doesn't change their meaning, only their direction. - - Emacs uses the same units as @command{xterm} does to interpret the geometry. -The @var{width} and @var{height} are measured in characters, so a large font -creates a larger frame than a small font. (If you specify a proportional -font, Emacs uses its maximum bounds width as the width unit.) The -@var{xoffset} and @var{yoffset} are measured in pixels. - - You do not have to specify all of the fields in the geometry -specification. If you omit both @var{xoffset} and @var{yoffset}, the -window manager decides where to put the Emacs frame, possibly by -letting you place it with the mouse. For example, @samp{164x55} -specifies a window 164 columns wide, enough for two ordinary width -windows side by side, and 55 lines tall. - - The default frame width is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If -you start the geometry with an integer, Emacs interprets it as the -width. If you start with an @samp{x} followed by an integer, Emacs -interprets it as the height. Thus, @samp{81} specifies just the -width; @samp{x45} specifies just the height. - - If you start with @samp{+} or @samp{-}, that introduces an offset, -which means both sizes are omitted. Thus, @samp{-3} specifies the -@var{xoffset} only. (If you give just one offset, it is always -@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the -@var{yoffset}, placing the frame near the bottom left of the screen. - - You can specify a default for any or all of the fields in your X -resource file (@pxref{Resources}), and then override selected fields -with a @samp{--geometry} option. - - Since the mode line and the echo area occupy the last 2 lines of the -frame, the height of the initial text window is 2 less than the height -specified in your geometry. In non-X-toolkit versions of Emacs, the -menu bar also takes one line of the specified number. But in the X -toolkit version, the menu bar is additional and does not count against -the specified height. The tool bar, if present, is also additional. - - Enabling or disabling the menu bar or tool bar alters the amount of -space available for ordinary text. Therefore, if Emacs starts up with -a tool bar (which is the default), and handles the geometry -specification assuming there is a tool bar, and then your -initialization file disables the tool bar, you will end up with a -frame geometry different from what you asked for. To get the intended -size with no tool bar, use an X resource to specify ``no tool bar'' -(@pxref{Table of Resources}); then Emacs will already know there's no -tool bar when it processes the specified geometry. - - When using one of @samp{--fullscreen}, @samp{--fullwidth} or -@samp{--fullheight} there may be some space around the frame -anyway. That is because Emacs rounds the sizes so they are an -even number of character heights and widths. - - Some window managers have options that can make them ignore both -program-specified and user-specified positions. If these are set, -Emacs fails to position the window correctly. - -@node Borders X -@appendixsec Internal and External Borders -@cindex borders (X Window System) - - An Emacs frame has an internal border and an external border. The -internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. - -@table @samp -@item -ib @var{width} -@opindex -ib -@itemx --internal-border=@var{width} -@opindex --internal-border -@cindex internal border width, command-line argument -Specify @var{width} as the width of the internal border (between the text -and the main border), in pixels. - -@item -bw @var{width} -@opindex -bw -@itemx --border-width=@var{width} -@opindex --border-width -@cindex main border width, command-line argument -Specify @var{width} as the width of the main border, in pixels. -@end table - - When you specify the size of the frame, that does not count the -borders. The frame's position is measured from the outside edge of the -external border. - - Use the @samp{-ib @var{n}} option to specify an internal border -@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. - -@node Title X -@appendixsec Frame Titles - - An Emacs frame may or may not have a specified title. The frame -title, if specified, appears in window decorations and icons as the -name of the frame. If an Emacs frame has no specified title, the -default title has the form @samp{@var{invocation-name}@@@var{machine}} -(if there is only one frame) or the selected window's buffer name (if -there is more than one frame). - - You can specify a title for the initial Emacs frame with a command -line option: - -@table @samp -@item -T @var{title} -@opindex -T -@itemx --title=@var{title} -@opindex --title -@cindex frame title, command-line argument -Specify @var{title} as the title for the initial Emacs frame. -@end table - - The @samp{--name} option (@pxref{Resources}) also specifies the title -for the initial Emacs frame. - -@node Icons X -@appendixsec Icons -@cindex icons (X Window System) -@cindex minimizing a frame at startup - -@table @samp -@item -iconic -@opindex --iconic -@itemx --iconic -@cindex start iconified, command-line argument -Start Emacs in an iconified (``minimized'') state. - -@item -nbi -@opindex -nbi -@itemx --no-bitmap-icon -@opindex --no-bitmap-icon -@cindex Emacs icon, a gnu -Do not use a picture of a gnu as the Emacs icon. -@end table - - Most window managers allow you to ``iconify'' (or ``minimize'') an -Emacs frame, hiding it from sight. Some window managers replace -iconified windows with tiny ``icons'', while others remove them -entirely from sight. The @samp{-iconic} option tells Emacs to begin -running in an iconified state, rather than showing a frame right away. -The text frame doesn't appear until you deiconify (or ``un-minimize'') -it. - - By default, Emacs uses an icon containing the Emacs logo. On -desktop environments such as Gnome, this icon is also displayed on the -``taskbar''. The @samp{-nbi} or @samp{--no-bitmap-icon} option tells -Emacs to let the window manager choose what sort of icon to -use---usually just a small rectangle containing the frame's title. - -@node Misc X -@appendixsec Other Display Options - -@table @samp -@c @item -hb -@c @opindex -hb -@c @itemx --horizontal-scroll-bars -@c @opindex --horizontal-scroll-bars -@c @c @cindex horizontal scroll bars, command-line argument -@c Enable horizontal scroll bars. Since horizontal scroll bars -@c are not yet implemented, this actually does nothing. - -@item -vb -@opindex -vb -@itemx --vertical-scroll-bars -@opindex --vertical-scroll-bars -@cindex vertical scroll bars, command-line argument -Enable vertical scroll bars. - -@item -lsp @var{pixels} -@opindex -lsp -@itemx --line-spacing=@var{pixels} -@opindex --line-spacing -@cindex line spacing, command-line argument -Specify @var{pixels} as additional space to put between lines, in pixels. - -@item -nbc -@opindex -nbc -@itemx --no-blinking-cursor -@opindex --no-blinking-cursor -@cindex blinking cursor disable, command-line argument -Disable the blinking cursor on graphical displays. - -@item -D -@opindex -D -@itemx --basic-display -@opindex --basic-display -Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, -and turn off the blinking cursor. This can be useful for making a -test case that simplifies debugging of display problems. -@end table - - The @samp{--xrm} option (@pxref{Resources}) specifies additional -X resource values. - -@ignore - arch-tag: fffecd9e-7329-4a51-a3cc-dd4a9889340e -@end ignore diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi deleted file mode 100644 index eee844c3381..00000000000 --- a/doc/emacs/commands.texi +++ /dev/null @@ -1,201 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Characters, Keys and Commands - - This chapter explains the character sets used by Emacs for input -commands, and the fundamental concepts of @dfn{keys} and -@dfn{commands}, whereby Emacs interprets your keyboard and mouse -input. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node User Input, Keys, Screen, Top -@section Kinds of User Input -@cindex input with the keyboard -@cindex keyboard input -@cindex character set (keyboard) -@cindex @acronym{ASCII} -@cindex C- -@cindex Control -@cindex control characters - - GNU Emacs is primarily designed for use with the keyboard. While it -is possible to use the mouse to issue editing commands through the -menu bar and tool bar, that is not as efficient as using the keyboard. -Therefore, this manual mainly documents how to edit with the keyboard. - - Keyboard input into Emacs is based on a heavily-extended version of -@acronym{ASCII}. The simplest characters that you can input into -Emacs correspond to graphic symbols such as @samp{a}, @samp{B}, -@samp{3}, @samp{=}, the space character (conventionally denoted as -@key{SPC}), and so on. Entering these using the keyboard is -straightforward. Certain characters found on non-English keyboards -also fall into this category (@pxref{International}). - - In addition to these simple characters, Emacs recognizes -@dfn{control characters} such as @key{RET}, @key{TAB}, @key{DEL}, -@key{ESC}, @key{F1}, @key{Home}, @key{left}, etc. Most keyboards have -special keys for entering these. - -@cindex modifier keys -@cindex Control -@cindex C- -@cindex Meta -@cindex M- - Emacs also recognizes control characters that are entered using -@dfn{modifier keys}. Two commonly-used modifier keys are -@key{Control} (which is usually labelled as @key{Ctrl}), and -@key{Meta} (which is usually labeled as @key{Alt})@footnote{We refer -to @key{Alt} as @key{Meta} for historical reasons.}. For example, -@kbd{Control-a} is entered by holding down the @key{Ctrl} key while -pressing @kbd{a}; we will refer to this as @kbd{C-a} for short. -Similarly @kbd{Meta-a}, or @kbd{M-a} for short, is entered by holding -down the @key{Alt} key and pressing @kbd{a}. - -@cindex @key{ESC} replacing @key{Meta} key - You can also type Meta characters using two-character sequences -starting with @key{ESC}. Thus, you can enter @kbd{M-a} by typing -@kbd{@key{ESC} a}. You can enter @kbd{C-M-a} by typing @kbd{@key{ESC} -C-a}. Unlike @key{Meta}, @key{ESC} is entered as a separate -character. You don't hold down @key{ESC} while typing the next -character; instead, press @key{ESC} and release it, then enter the -next character. This feature is useful on certain text-only terminals -where the @key{Meta} key does not function reliably. - - Modifier keys can apply not only to alphanumerical characters, but -also to special input characters, such as the arrow keys and mouse -buttons. - -@cindex input event - @xref{Input Events,,, elisp, The Emacs Lisp Reference Manual}, for -the full Lisp-level details about keyboard and mouse input, which are -collectively referred to as @dfn{input events}. If you are not doing -Lisp programming, but simply want to redefine the meaning of some -characters or non-character events, see @ref{Customization}. - -@cindex keys stolen by window manager -@cindex window manager, keys stolen by - On graphical displays, the window manager is likely to block the -character @kbd{M-@key{TAB}} before Emacs can see it. It may also -block @kbd{M-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have -these problems, we recommend that you customize your window manager to -turn off those commands, or put them on key combinations that Emacs -does not use. - -@node Keys, Commands, User Input, Top -@section Keys - - Some Emacs commands are invoked by just one input event; for -example, @kbd{C-f} moves forward one character in the buffer. But -Emacs also has commands that take two or more input events to invoke, -such as @kbd{C-x C-f} and @kbd{C-x 4 C-f}. - -@cindex key -@cindex key sequence -@cindex complete key -@cindex prefix key - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that is meaningful as a unit. If a key sequence -invokes a command, we call it a @dfn{complete key}; for example, -@kbd{C-f}, @kbd{C-x C-f} and @kbd{C-x 4 C-f} are all complete keys. -If a key sequence isn't long enough to invoke a command, we call it a -@dfn{prefix key}; from the preceding example, we see that @kbd{C-x} -and @kbd{C-x 4} are prefix keys. Every key is either a complete key -or a prefix key. - - A prefix key combines with the following input event to make a -longer key sequence, which may itself be complete or a prefix. For -example, @kbd{C-x} is a prefix key, so @kbd{C-x} and the next input -event combine to make a two-event key sequence. This two-event key -sequence could itself be a prefix key (such as @kbd{C-x 4}), or a -complete key (such as @kbd{C-x C-f}). There is no limit to the length -of a key sequence, but in practice people rarely use sequences longer -than three or four input events. - - You can't add input events onto a complete key. For example, the -two-event sequence @kbd{C-f C-k} is not a key, because the @kbd{C-f} -is a complete key in itself, so @kbd{C-f C-k} cannot have an -independent meaning as a command. @kbd{C-f C-k} is two key sequences, -not one.@refill - - By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, -@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x -n}, @kbd{C-x r}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, -@key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and @key{F2} are -aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in -stone; if you customize Emacs, you can make new prefix keys. You -could even eliminate some of the standard ones, though this is not -recommended for most users; for example, if you remove the prefix -definition of @kbd{C-x 4}, then @kbd{C-x 4 @var{anything}} would -become an invalid key sequence. @xref{Key Bindings}. - - Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key -displays a list of the commands starting with that prefix. The sole -exception to this rule is @key{ESC}: @kbd{@key{ESC}C-h} is equivalent -to @kbd{C-M-h}, which does something else entirely. You can, however, -use @key{F1} to displays a list of the commands starting with -@key{ESC}. - -@node Commands, Entering Emacs, Keys, Top -@section Keys and Commands - -@cindex binding -@cindex command -@cindex function definition - This manual is full of passages that tell you what particular keys -do. But Emacs does not assign meanings to keys directly. Instead, -Emacs assigns meanings to named @dfn{commands}, and then gives keys -their meanings by @dfn{binding} them to commands. - - Every command has a name chosen by a programmer. The name is -usually made of a few English words separated by dashes; for example, -@code{next-line} or @code{forward-word}. A command also has a -@dfn{function definition} which is a Lisp program; this is how the -command does its work. In Emacs Lisp, a command is a Lisp function -with special properties that make it suitable for interactive use. -For more information on commands and functions, see @ref{What Is a -Function,, What Is a Function, elisp, The Emacs Lisp Reference -Manual}. - - The bindings between keys and commands are recorded in tables called -@dfn{keymaps}. @xref{Keymaps}. - - When we say that ``@kbd{C-n} moves down vertically one line'' we are -glossing over a subtle distinction that is irrelevant in ordinary use, -but vital for Emacs customization. The command @code{next-line} does -a vertical move downward. @kbd{C-n} has this effect @emph{because} it -is bound to @code{next-line}. If you rebind @kbd{C-n} to the command -@code{forward-word}, @kbd{C-n} will move forward one word instead. - - In this manual, we will often speak of keys like @kbd{C-n} as -commands, even though strictly speaking the key is bound to a command. -Usually we state the name of the command which really does the work in -parentheses after mentioning the key that runs it. For example, we -will say that ``The command @kbd{C-n} (@code{next-line}) moves point -vertically down,'' meaning that the command @code{next-line} moves -vertically down, and the key @kbd{C-n} is normally bound to it. - - Since we are discussing customization, we should tell you about -@dfn{variables}. Often the description of a command will say, ``To -change this, set the variable @code{mumble-foo}.'' A variable is a -name used to store a value. Most of the variables documented in this -manual are meant for customization: some command or other part of -Emacs examines the variable and behaves differently according to the -value that you set. You can ignore the information about variables -until you are interested in customizing them. Then read the basic -information on variables (@pxref{Variables}) and the information about -specific variables will make sense. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45 -@end ignore diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi deleted file mode 100644 index f0a63855f2d..00000000000 --- a/doc/emacs/custom.texi +++ /dev/null @@ -1,2579 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Customization, Quitting, Amusements, Top -@chapter Customization -@cindex customization - - This chapter describes some simple methods to customize the behavior -of Emacs. - - Apart from the methods described here, see @ref{X Resources} for -information about using X resources to customize Emacs, and see -@ref{Keyboard Macros} for information about recording and replaying -keyboard macros. Making more far-reaching and open-ended changes -involves writing Emacs Lisp code; see -@iftex -@cite{The Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp -Reference Manual}. -@end ifnottex - -@menu -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Syntax:: The syntax table controls how words and - expressions are parsed. -* Init File:: How to write common customizations in the - @file{.emacs} file. -@end menu - -@node Minor Modes -@section Minor Modes -@cindex minor modes -@cindex mode, minor - - Minor modes are optional features which you can turn on or off. For -example, Auto Fill mode is a minor mode in which @key{SPC} breaks -lines between words as you type. Minor modes are independent of one -another and of the selected major mode. Most minor modes say in the -mode line when they are enabled; for example, @samp{Fill} in the mode -line means that Auto Fill mode is enabled. - - Each minor mode is associated with a command, called the @dfn{mode -command}, which turns it on or off. The name of this command consists -of the name of the minor mode, followed by @samp{-mode}; for instance, -the mode command for Auto Fill mode is @code{auto-fill-mode}. Calling -the minor mode command with no prefix argument @dfn{toggles} the mode, -turning it on if it was off, and off if it was on. A positive -argument always turns the mode on, and a zero or negative argument -always turns it off. Mode commands are usually invoked with -@kbd{M-x}, but you can bind keys to them if you wish (@pxref{Key -Bindings}). - - Most minor modes also have a @dfn{mode variable}, with the same name -as the mode command. Its value is non-@code{nil} if the mode is -enabled, and @code{nil} if it is disabled. In some minor modes---but -not all---the value of the variable alone determines whether the mode -is active: the mode command works simply by setting the variable, and -changing the value of the variable has the same effect as calling the -mode command. Because not all minor modes work this way, we recommend -that you avoid changing the mode variables directly; use the mode -commands instead. - - Some minor modes are @dfn{buffer-local}: they apply only to the -current buffer, so you can enable the mode in certain buffers and not -others. Other minor modes are @dfn{global}: while enabled, they -affect everything you do in the Emacs session, in all buffers. Some -global minor modes are enabled by default. - - The following is a list of some buffer-local minor modes: - -@itemize @bullet -@item -Abbrev mode automatically expands text based on pre-defined -abbreviation definitions. @xref{Abbrevs}. - -@item -Auto Fill mode inserts newlines as you type to prevent lines from -becoming too long. @xref{Filling}. - -@item -Auto Save mode saves the buffer contents periodically to reduce the -amount of work you can lose in case of a crash. @xref{Auto Save}. - -@item -Enriched mode enables editing and saving of formatted text. -@xref{Formatted Text}. - -@item -Flyspell mode automatically highlights misspelled words. -@xref{Spelling}. - -@item -Font-Lock mode automatically highlights certain textual units found in -programs. It is enabled globally by default, but you can disable it -in individual buffers. @xref{Faces}. - -@findex linum-mode -@cindex Linum mode -@item -Linum mode displays each line's line number in the window's left -margin. Its mode command is @code{linum-mode}. - -@item -Outline minor mode provides similar facilities to the major mode -called Outline mode. @xref{Outline Mode}. - -@cindex Overwrite mode -@cindex mode, Overwrite -@findex overwrite-mode -@kindex INSERT -@item -Overwrite mode causes ordinary printing characters to replace existing -text instead of shoving it to the right. For example, if point is in -front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing -a @kbd{G} changes it to @samp{FOOGAR}, instead of producing -@samp{FOOGBAR} as usual. In Overwrite mode, the command @kbd{C-q} -inserts the next character whatever it may be, even if it is a -digit---this gives you a way to insert a character instead of -replacing an existing character. The mode command, -@code{overwrite-mode}, is bound to the @key{Insert} key. - -@findex binary-overwrite-mode -@item -Binary Overwrite mode is a variant of Overwrite mode for editing -binary files; it treats newlines and tabs like other characters, so -that they overwrite other characters and can be overwritten by them. -In Binary Overwrite mode, digits after @kbd{C-q} specify an octal -character code, as usual. - -@item -Visual Line mode performs ``word wrapping'', causing long lines to be -wrapped at word boundaries. @xref{Visual Line Mode}. -@end itemize - - Here are some useful global minor modes. Since Line Number mode and -Transient Mark mode can be enabled or disabled just by setting the -value of the minor mode variable, you @emph{can} set them differently -for particular buffers, by explicitly making the corresponding -variable local in those buffers. @xref{Locals}. - -@itemize @bullet -@item -Column Number mode enables display of the current column number in the -mode line. @xref{Mode Line}. - -@item -Delete Selection mode causes text insertion to first delete the text -in the region, if the region is active. @xref{Using Region}. - -@item -Icomplete mode displays an indication of available completions when -you are in the minibuffer and completion is active. @xref{Completion -Options}. - -@item -Line Number mode enables display of the current line number in the -mode line. It is enabled by default. @xref{Mode Line}. - -@item -Menu Bar mode gives each frame a menu bar. It is enabled by default. -@xref{Menu Bars}. - -@item -Scroll Bar mode gives each window a scroll bar. It is enabled by -default, but the scroll bar is only displayed on graphical terminals. -@xref{Scroll Bars}. - -@item -Tool Bar mode gives each frame a tool bar. It is enabled by default, -but the tool bar is only displayed on graphical terminals. @xref{Tool -Bars}. - -@item -Transient Mark mode highlights the region, and makes many Emacs -commands operate on the region when the mark is active. It is enabled -by default. @xref{Mark}. -@end itemize - -@node Easy Customization -@section Easy Customization Interface - -@cindex settings - Emacs has many @dfn{settings} which have values that you can change. -Many are documented in this manual. Most settings are @dfn{user -options}---that is to say, Lisp variables (@pxref{Variables})---and -their names appear in the Variable Index (@pxref{Variable Index}). -The other settings are faces and their attributes (@pxref{Faces}). - -@findex customize -@cindex customization buffer - You can browse settings and change them using @kbd{M-x customize}. -This creates a @dfn{customization buffer}, which lets you navigate -through a logically organized list of settings, edit and set their -values, and save them permanently in your initialization file -(@pxref{Init File}). - -@menu -* Customization Groups:: How settings are classified in a structure. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Specifying the file for saving customizations. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Making a customization buffer for specific - variables, faces, or groups. -* Custom Themes:: How to define collections of customized options - that can be loaded and unloaded together. -@end menu - -@node Customization Groups -@subsection Customization Groups -@cindex customization groups - - For customization purposes, settings are organized into @dfn{groups} -to help you find them. Groups are collected into bigger groups, all -the way up to a master group called @code{Emacs}. - - @kbd{M-x customize} creates a customization buffer that shows the -top-level @code{Emacs} group and the second-level groups immediately -under it. It looks like this, in part: - -@c we want the buffer example to all be on one page, but unfortunately -@c that's quite a bit of text, so force all space to the bottom. -@page -@smallexample -@group -/- Emacs group: Customization of the One True Editor. -------------\ - [State]: visible group members are all at standard values. - - See also [Manual]. - -[Editing] : Basic text editing facilities. - -[External] : Interfacing to external utilities. - -@var{more second-level groups} - -\- Emacs group end ------------------------------------------------/ -@end group -@end smallexample - -@noindent -This says that the buffer displays the contents of the @code{Emacs} -group. The other groups are listed because they are its contents. But -they are listed differently, without indentation and dashes, because -@emph{their} contents are not included. Each group has a single-line -documentation string; the @code{Emacs} group also has a @samp{[State]} -line. - -@cindex editable fields (customization buffer) -@cindex buttons (customization buffer) -@cindex links (customization buffer) - Most of the text in the customization buffer is read-only, but it -typically includes some @dfn{editable fields} that you can edit. -There are also @dfn{buttons} and @dfn{links}, which do something when -you @dfn{invoke} them. To invoke a button or a link, either click on -it with @kbd{Mouse-1}, or move point to it and type @key{RET}. - - For example, the phrase @samp{[State]} that appears in a -second-level group is a button. It operates on the same customization -buffer. Each group name, such as @samp{[Editing]}, is a hypertext -link to that group; invoking it creates a new customization buffer, -showing the group and its contents. - - The @code{Emacs} group only contains other groups. These groups, in -turn, can contain settings or still more groups. By browsing the -hierarchy of groups, you will eventually find the feature you are -interested in customizing. Then you can use the customization buffer -to set that feature's settings. You can also go straight to a -particular group by name, using the command @kbd{M-x customize-group}. - -@node Browsing Custom -@subsection Browsing and Searching for Options and Faces -@findex customize-browse - - @kbd{M-x customize-browse} is another way to browse the available -settings. This command creates a special customization buffer which -shows only the names of groups and settings, and puts them in a -structure. - - In this buffer, you can show the contents of a group by invoking the -@samp{[+]} button. When the group contents are visible, this button -changes to @samp{[-]}; invoking that hides the group contents again. - - Each group or setting in this buffer has a link which says -@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link -creates an ordinary customization buffer showing just that group and -its contents, just that user option, or just that face. This is the -way to change settings that you find with @kbd{M-x customize-browse}. - - If you can guess part of the name of the settings you are interested -in, @kbd{M-x customize-apropos} is another way to search for settings. -However, unlike @code{customize} and @code{customize-browse}, -@code{customize-apropos} can only find groups and settings that are -loaded in the current Emacs session. @xref{Specific Customization,, -Customizing Specific Items}. - -@node Changing a Variable -@subsection Changing a Variable - - Here is an example of what a variable (a user option) looks like in -the customization buffer: - -@smallexample -Kill Ring Max: [Hide Value] 60 - [State]: STANDARD. -Maximum length of kill ring before oldest elements are thrown away. -@end smallexample - - The text following @samp{[Hide Value]}, @samp{60} in this case, indicates -the current value of the variable. If you see @samp{[Show Value]} instead of -@samp{[Hide Value]}, it means that the value is hidden; the customization -buffer initially hides values that take up several lines. Invoke -@samp{[Show Value]} to show the value. - - The line after the variable name indicates the @dfn{customization -state} of the variable: in the example above, it says you have not -changed the option yet. The @samp{[State]} button at the beginning of -this line gives you a menu of various operations for customizing the -variable. - - The line after the @samp{[State]} line displays the beginning of the -variable's documentation string. If there are more lines of -documentation, this line ends with a @samp{[More]} button; invoke that -to show the full documentation string. - - To enter a new value for @samp{Kill Ring Max}, move point to the -value and edit it textually. For example, you can type @kbd{M-d}, -then insert another number. As you begin to alter the text, you will -see the @samp{[State]} line change to say that you have edited the -value: - -@smallexample -[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} - save it. -@end smallexample - -@cindex user options, how to set -@cindex variables, how to set -@cindex settings, how to set - Editing the value does not actually set the variable. To do that, -you must @dfn{set} the variable. To do this, invoke the -@samp{[State]} button and choose @samp{Set for Current Session}. - - The state of the variable changes visibly when you set it: - -@smallexample -[State]: SET for current session only. -@end smallexample - - You don't have to worry about specifying a value that is not valid; -the @samp{Set for Current Session} operation checks for validity and -will not install an unacceptable value. - -@kindex M-TAB @r{(customization buffer)} -@findex widget-complete - While editing a field that is a file name, directory name, -command name, or anything else for which completion is defined, you -can type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. -(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) - - Some variables have a small fixed set of possible legitimate values. -These variables don't let you edit the value textually. Instead, a -@samp{[Value Menu]} button appears before the value; invoke this -button to change the value. For a boolean ``on or off'' value, the -button says @samp{[Toggle]}, and it changes to the other value. -@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the -changes take real effect when you use the @samp{Set for Current -Session} operation. - - Some variables have values with complex structure. For example, the -value of @code{file-coding-system-alist} is an association list. Here -is how it appears in the customization buffer: - -@smallexample -File Coding System Alist: [Hide Value] -[INS] [DEL] File regexp: \.elc\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: emacs-mule - Encoding: emacs-mule -[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: raw-text - Encoding: raw-text-unix -[INS] [DEL] File regexp: \.tar\' - Choice: [Value Menu] Encoding/decoding pair: - Decoding: no-conversion - Encoding: no-conversion -[INS] [DEL] File regexp: - Choice: [Value Menu] Encoding/decoding pair: - Decoding: undecided - Encoding: nil -[INS] - [State]: STANDARD. -Alist to decide a coding system to use for a file I/O @r{@dots{}} - operation. [Hide Rest] -The format is ((PATTERN . VAL) ...), -where PATTERN is a regular expression matching a file name, -@r{[@dots{}more lines of documentation@dots{}]} -@end smallexample - -@noindent -Each association in the list appears on four lines, with several -editable fields and/or buttons. You can edit the regexps and coding -systems using ordinary editing commands. You can also invoke -@samp{[Value Menu]} to switch to a different kind of value---for -instance, to specify a function instead of a pair of coding systems. - -To delete an association from the list, invoke the @samp{[DEL]} button -for that item. To add an association, invoke @samp{[INS]} at the -position where you want to add it. There is an @samp{[INS]} button -between each pair of associations, another at the beginning and another -at the end, so you can add a new association at any position in the -list. - -@kindex TAB @r{(customization buffer)} -@kindex S-TAB @r{(customization buffer)} -@findex widget-forward -@findex widget-backward - Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful -for moving through the customization buffer. @key{TAB} -(@code{widget-forward}) moves forward to the next button or editable -field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to -the previous button or editable field. - - Typing @key{RET} on an editable field also moves forward, just like -@key{TAB}. You can thus type @key{RET} when you are finished editing -a field, to move on to the next button or field. To insert a newline -within an editable field, use @kbd{C-o} or @kbd{C-q C-j}. - -@cindex saving a setting -@cindex settings, how to save - Setting the variable changes its value in the current Emacs session; -@dfn{saving} the value changes it for future sessions as well. To -save the variable, invoke @samp{[State]} and select the @samp{Save for -Future Sessions} operation. This works by writing code so as to set -the variable again, each time you start Emacs (@pxref{Saving -Customizations}). - - You can also restore the variable to its standard value by invoking -@samp{[State]} and selecting the @samp{Erase Customization} operation. -There are actually four reset operations: - -@table @samp -@item Undo Edits -If you have made some modifications and not yet set the variable, -this restores the text in the customization buffer to match -the actual value. - -@item Reset to Saved -This restores the value of the variable to the last saved value, -and updates the text accordingly. - -@item Erase Customization -This sets the variable to its standard value, and updates the text -accordingly. This also eliminates any saved value for the variable, -so that you will get the standard value in future Emacs sessions. - -@item Set to Backup Value -This sets the variable to a previous value that was set in the -customization buffer in this session. If you customize a variable -and then reset it, which discards the customized value, -you can get the discarded value back again with this operation. -@end table - -@cindex comments on customized settings - Sometimes it is useful to record a comment about a specific -customization. Use the @samp{Add Comment} item from the -@samp{[State]} menu to create a field for entering the comment. The -comment you enter will be saved, and displayed again if you again view -the same variable in a customization buffer, even in another session. - - The state of a group indicates whether anything in that group has been -edited, set or saved. - - Near the top of the customization buffer there are two lines of buttons: - -@smallexample - [Set for Current Session] [Save for Future Sessions] - [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] -@end smallexample - -@vindex custom-buffer-done-function -@noindent -Invoking @samp{[Finish]} either buries or kills this customization -buffer according to the setting of the option -@code{custom-buffer-done-kill}; the default is to bury the buffer. -Each of the other buttons performs an operation---set, save or -reset---on each of the settings in the buffer that could meaningfully -be set, saved or reset. They do not operate on settings whose values -are hidden, nor on subgroups which are hidden or not visible in the buffer. - -@node Saving Customizations -@subsection Saving Customizations - -@vindex custom-file - Saving customizations from the customization buffer works by writing -code to a file. By reading this code, future sessions can set up the -customizations again. Normally, the code is saved in your -initialization file (@pxref{Init File}). - - You can choose to save your customizations in a file other than your -initialization file. To make this work, you must add a couple of -lines of code to your initialization file, to set the variable -@code{custom-file} to the name of the desired file, and to load that -file. For example: - -@example -(setq custom-file "~/.emacs-custom.el") -(load custom-file) -@end example - - You can use @code{custom-file} to specify different customization -files for different Emacs versions, like this: - -@example -(cond ((< emacs-major-version 22) - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) - ((and (= emacs-major-version 22) (< emacs-minor-version 3)) - ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.custom-22.el")) - (t - ;; @r{Emacs version 22.3 or later.} - (setq custom-file "~/.emacs-custom.el"))) - -(load custom-file) -@end example - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not let you save your -customizations in your initialization file. This is because saving -customizations from such a session would wipe out all the other -customizations you might have on your initialization file. - -@node Face Customization -@subsection Customizing Faces -@cindex customizing faces -@cindex bold font -@cindex italic font -@cindex fonts and faces - - In addition to variables, some customization groups also include -faces. When you show the contents of a group, both the variables and -the faces in the group appear in the customization buffer. Here is an -example of how a face looks: - -@smallexample -Custom Changed Face:(sample) [Hide Face] - [State]: STANDARD. -Face used when the customize item has been changed. -Parent groups: [Custom Magic Faces] -Attributes: [ ] Font Family: * - [ ] Width: * - [ ] Height: * - [ ] Weight: * - [ ] Slant: * - [ ] Underline: * - [ ] Overline: * - [ ] Strike-through: * - [ ] Box around text: * - [ ] Inverse-video: * - [X] Foreground: white (sample) - [X] Background: blue (sample) - [ ] Stipple: * - [ ] Inherit: * -@end smallexample - - Each face attribute has its own line. The @samp{[@var{x}]} button -before the attribute name indicates whether the attribute is -@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} -means that it's disabled. You can enable or disable the attribute by -clicking that button. When the attribute is enabled, you can change -the attribute value in the usual ways. - - For the colors, you can specify a color name (use @kbd{M-x -list-colors-display} for a list of them) or a hexadecimal color -specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. -(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is -green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) On a -black-and-white display, the colors you can use for the background are -@samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, and -@samp{gray3}. Emacs supports these shades of gray by using background -stipple patterns instead of a color. - - Setting, saving and resetting a face work like the same operations for -variables (@pxref{Changing a Variable}). - - A face can specify different appearances for different types of -display. For example, a face can make text red on a color display, but -use a bold font on a monochrome display. To specify multiple -appearances for a face, select @samp{For All Kinds of Displays} in the -menu you get from invoking @samp{[State]}. - -@findex modify-face - Another more basic way to set the attributes of a specific face is -with @kbd{M-x modify-face}. This command reads the name of a face, then -reads the attributes one by one. For the color and stipple attributes, -the attribute's current value is the default---type just @key{RET} if -you don't want to change that attribute. Type @samp{none} if you want -to clear out the attribute. - -@node Specific Customization -@subsection Customizing Specific Items - - Instead of finding the setting you want to change by navigating the -structure of groups, here are other ways to specify the settings that -you want to customize. - -@table @kbd -@item M-x customize-option @key{RET} @var{option} @key{RET} -Set up a customization buffer with just one user option variable, -@var{option}. -@item M-x customize-face @key{RET} @var{face} @key{RET} -Set up a customization buffer with just one face, @var{face}. -@item M-x customize-group @key{RET} @var{group} @key{RET} -Set up a customization buffer with just one group, @var{group}. -@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} -Set up a customization buffer with all the settings and groups that -match @var{regexp}. -@item M-x customize-changed @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the settings and groups -whose meaning has changed since Emacs version @var{version}. -@item M-x customize-saved -Set up a customization buffer containing all settings that you -have saved with customization buffers. -@item M-x customize-unsaved -Set up a customization buffer containing all settings that you have -set but not saved. -@end table - -@findex customize-option - If you want to alter a particular user option with the customization -buffer, and you know its name, you can use the command @kbd{M-x -customize-option} and specify the user option (variable) name. This -sets up the customization buffer with just one user option---the one -that you asked for. Editing, setting and saving the value work as -described above, but only for the specified user option. Minibuffer -completion is handy if you only know part of the name. However, this -command can only see options that have been loaded in the current -Emacs session. - -@findex customize-face - Likewise, you can modify a specific face, chosen by name, using -@kbd{M-x customize-face}. By default it operates on the face used -on the character after point. - -@findex customize-group - You can also set up the customization buffer with a specific group, -using @kbd{M-x customize-group}. The immediate contents of the chosen -group, including settings (user options and faces), and other groups, -all appear as well (even if not already loaded). However, the -subgroups' own contents are not included. - -@findex customize-apropos - For a more general way of controlling what to customize, you can use -@kbd{M-x customize-apropos}. You specify a regular expression as -argument; then all @emph{loaded} settings and groups whose names match -this regular expression are set up in the customization buffer. If -you specify an empty regular expression, this includes @emph{all} -loaded groups and settings---which takes a long time to set up. - -@findex customize-changed - When you upgrade to a new Emacs version, you might want to consider -customizing new settings, and settings whose meanings or default -values have changed. To do this, use @kbd{M-x customize-changed} and -specify a previous Emacs version number using the minibuffer. It -creates a customization buffer which shows all the settings and groups -whose definitions have been changed since the specified version, -loading them if necessary. - -@findex customize-saved -@findex customize-unsaved - If you change settings and then decide the change was a mistake, you -can use two special commands to revisit your previous changes. Use -@kbd{M-x customize-saved} to look at the settings that you have saved. -Use @kbd{M-x customize-unsaved} to look at the settings that you -have set but not saved. - -@node Custom Themes -@subsection Customization Themes -@cindex custom themes - - @dfn{Custom themes} are collections of settings that can be enabled -or disabled as a unit. You can use Custom themes to switch quickly -and easily between various collections of settings, and to transfer -such collections from one computer to another. - -@findex customize-create-theme - To define a Custom theme, use @kbd{M-x customize-create-theme}, -which brings up a buffer named @samp{*New Custom Theme*}. At the top -of the buffer is an editable field where you can specify the name of -the theme. Click on the button labelled @samp{Insert Variable} to add -a variable to the theme, and click on @samp{Insert Face} to add a -face. You can edit these values in the @samp{*New Custom Theme*} -buffer like in an ordinary Customize buffer. To remove an option from -the theme, click on its @samp{State} button and select @samp{Delete}. - -@vindex custom-theme-directory - After adding the desired options, click on @samp{Save Theme} to save -the Custom theme. This writes the theme definition to a file -@file{@var{foo}-theme.el} (where @var{foo} is the theme name you -supplied), in the directory @file{~/.emacs.d/}. You can specify the -directory by setting @code{custom-theme-directory}. - - You can view and edit the settings of a previously-defined theme by -clicking on @samp{Visit Theme} and specifying the theme name. You can -also import the variables and faces that you have set using Customize -by visiting the ``special'' theme named @samp{user}. This theme, which -records all the options that you set in the ordinary customization -buffer, is always enabled, and always takes precedence over all other -enabled Custom themes. Additionally, the @samp{user} theme is -recorded with code in your @file{.emacs} file, rather than a -@file{user-theme.el} file. - -@vindex custom-enabled-themes - Once you have defined a Custom theme, you can use it by customizing -the variable @code{custom-enabled-themes}. This is a list of Custom -themes that are @dfn{enabled}, or put into effect. If you set -@code{custom-enabled-themes} using the Customize interface, the theme -definitions are automatically loaded from the theme files, if they -aren't already. If you save the value of @code{custom-enabled-themes} -for future Emacs sessions, those Custom themes will be enabled -whenever Emacs is started up. - - If two enabled themes specify different values for an option, the -theme occurring earlier in @code{custom-enabled-themes} takes effect. - -@findex load-theme -@findex enable-theme -@findex disable-theme - You can temporarily enable a Custom theme with @kbd{M-x -enable-theme}. This prompts for a theme name in the minibuffer, loads -the theme from the theme file if necessary, and enables the theme. -You can @dfn{disable} any enabled theme with the command @kbd{M-x -disable-theme}; this returns the options specified in the theme to -their original values. To re-enable the theme, type @kbd{M-x -enable-theme} again. If a theme file is changed during your Emacs -session, you can reload it by typing @kbd{M-x load-theme}. (This also -enables the theme.) - -@node Variables -@section Variables -@cindex variable -@cindex option, user -@cindex user option - - A @dfn{variable} is a Lisp symbol which has a value. The symbol's -name is also called the @dfn{variable name}. A variable name can -contain any characters that can appear in a file, but most variable -names consist of ordinary words separated by hyphens. - - The name of the variable serves as a compact description of its -role. Most variables also have a @dfn{documentation string}, which -describes what the variable's purpose is, what kind of value it should -have, and how the value will be used. You can view this documentation -using the help command @kbd{C-h v} (@code{describe-variable}). -@xref{Examining}. - - Emacs uses many Lisp variables for internal record keeping, but the -most interesting variables for a non-programmer user are those meant -for users to change---these are called @dfn{user options}. @xref{Easy -Customization}, for information about using the Customize facility to -set user options. In the following sections, we describe will other -aspects of Emacs variables, such as how to set them outside Customize. - - Emacs Lisp allows any variable (with a few exceptions) to have any -kind of value. However, many variables are meaningful only if -assigned values of a certain type. For example, only numbers are -meaningful values for @code{kill-ring-max}, which specifies the -maximum length of the kill ring (@pxref{Earlier Kills}); if you give -@code{kill-ring-max} a string value, commands such as @kbd{C-y} -(@code{yank}) will signal an error. On the other hand, some variables -don't care about type; for instance, if a variable has one effect for -@code{nil} values and another effect for ``non-@code{nil}'' values, -then any value that is not the symbol @code{nil} induces the second -effect, regardless of its type (by convention, we usually use the -value @code{t}---a symbol which stands for ``true''---to specify a -non-@code{nil} value). If you set a variable using the customization -buffer, you need not worry about giving it an invalid type: the -customization buffer usually only allows you to enter meaningful -values. When in doubt, use @kbd{C-h v} (@code{describe-variable}) to -check the variable's documentation string to see kind of value it -expects (@pxref{Examining}). - -@menu -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. -@end menu - -@node Examining -@subsection Examining and Setting Variables -@cindex setting variables - -@table @kbd -@item C-h v @var{var} @key{RET} -Display the value and documentation of variable @var{var} -(@code{describe-variable}). -@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} -Change the value of variable @var{var} to @var{value}. -@end table - - To examine the value of a single variable, use @kbd{C-h v} -(@code{describe-variable}), which reads a variable name using the -minibuffer, with completion. It displays both the value and the -documentation of the variable. For example, - -@example -C-h v fill-column @key{RET} -@end example - -@noindent -displays something like this: - -@smallexample -fill-column is a variable defined in `C source code'. -fill-column's value is 70 -Local in buffer custom.texi; global value is 70 -Automatically becomes buffer-local when set in any fashion. - - Automatically becomes buffer-local when set in any fashion. - This variable is safe as a file local variable if its value - satisfies the predicate `integerp'. - -Documentation: -*Column beyond which automatic line-wrapping should happen. -Interactively, you can set the buffer local value using C-x f. - -You can customize this variable. -@end smallexample - -@noindent -The line that says ``You can customize the variable'' indicates that -this variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows any variable name. - -@findex set-variable - The most convenient way to set a specific user option variable is -with @kbd{M-x set-variable}. This reads the variable name with the -minibuffer (with completion), and then reads a Lisp expression for the -new value using the minibuffer a second time (you can insert the old -value into the minibuffer for editing via @kbd{M-n}). For example, - -@example -M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} -@end example - -@noindent -sets @code{fill-column} to 75. - - @kbd{M-x set-variable} is limited to user option variables, but you can -set any variable with a Lisp expression, using the function @code{setq}. -Here is a @code{setq} expression to set @code{fill-column}: - -@example -(setq fill-column 75) -@end example - - To execute an expression like this one, go to the @samp{*scratch*} -buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp -Interaction}. - - Setting variables, like all means of customizing Emacs except where -otherwise stated, affects only the current Emacs session. The only -way to alter the variable in future sessions is to put something in -your initialization file to set it those sessions (@pxref{Init File}). - -@node Hooks -@subsection Hooks -@cindex hook -@cindex running a hook - - @dfn{Hooks} are an important mechanism for customizing Emacs. A -hook is a Lisp variable which holds a list of functions, to be called -on some well-defined occasion. (This is called @dfn{running the -hook}.) The individual functions in the list are called the @dfn{hook -functions} of the hook. With rare exceptions, hooks in Emacs are -empty when Emacs starts up, so the only hook functions in any given -hook are the ones you explicitly put there as customization. - - Most major modes run one or more @dfn{mode hooks} as the last step -of initialization. This makes it easy for you to customize the -behavior of the mode, by setting up a hook function to override the -local variable assignments already made by the mode. But hooks are -also used in other contexts. For example, the hook -@code{kill-emacs-hook} runs just before quitting the Emacs job -(@pxref{Exiting}). - -@cindex normal hook - Most Emacs hooks are @dfn{normal hooks}. This means that running the -hook operates by calling all the hook functions, unconditionally, with -no arguments. We have made an effort to keep most hooks normal so that -you can use them in a uniform way. Every variable in Emacs whose name -ends in @samp{-hook} is a normal hook. - -@cindex abnormal hook - There are also a few @dfn{abnormal hooks}. These variables' names end -in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What -makes these hooks abnormal is that there is something peculiar about the -way its functions are called---perhaps they are given arguments, or -perhaps the values they return are used in some way. For example, -@code{find-file-not-found-functions} (@pxref{Visiting}) is abnormal because -as soon as one hook function returns a non-@code{nil} value, the rest -are not called at all. The documentation of each abnormal hook variable -explains in detail what is peculiar about it. - -@findex add-hook - You can set a hook variable with @code{setq} like any other Lisp -variable, but the recommended way to add a hook function to a hook -(either normal or abnormal) is by calling @code{add-hook}. -@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. - - For example, here's how to set up a hook to turn on Auto Fill mode -when entering Text mode and other modes based on Text mode: - -@example -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end example - - The next example shows how to use a hook to customize the indentation -of C code. (People often have strong personal preferences for one -format compared to another.) Here the hook function is an anonymous -lambda expression. - -@example -@group -(setq my-c-style - '((c-comment-only-line-offset . 4) -@end group -@group - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) -@end group -@group - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0))))) -@end group - -@group -(add-hook 'c-mode-common-hook - '(lambda () - (c-add-style "my-style" my-c-style t))) -@end group -@end example - - It is best to design your hook functions so that the order in which -they are executed does not matter. Any dependence on the order is -``asking for trouble.'' However, the order is predictable: the most -recently added hook functions are executed first. - -@findex remove-hook - If you play with adding various different versions of a hook -function by calling @code{add-hook} over and over, remember that all -the versions you added will remain in the hook variable together. You -can clear out individual functions by calling @code{remove-hook}, or -do @code{(setq @var{hook-variable} nil)} to remove everything. - -@node Locals -@subsection Local Variables - -@table @kbd -@item M-x make-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} have a local value in the current buffer. -@item M-x kill-local-variable @key{RET} @var{var} @key{RET} -Make variable @var{var} use its global value in the current buffer. -@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} -Mark variable @var{var} so that setting it will make it local to the -buffer that is current at that time. -@end table - -@cindex local variables - Almost any variable can be made @dfn{local} to a specific Emacs -buffer. This means that its value in that buffer is independent of its -value in other buffers. A few variables are always local in every -buffer. Every other Emacs variable has a @dfn{global} value which is in -effect in all buffers that have not made the variable local. - -@findex make-local-variable - @kbd{M-x make-local-variable} reads the name of a variable and makes -it local to the current buffer. Changing its value subsequently in -this buffer will not affect others, and changes in its global value -will not affect this buffer. - -@findex make-variable-buffer-local -@cindex per-buffer variables - @kbd{M-x make-variable-buffer-local} marks a variable so it will -become local automatically whenever it is set. More precisely, once a -variable has been marked in this way, the usual ways of setting the -variable automatically do @code{make-local-variable} first. We call -such variables @dfn{per-buffer} variables. Many variables in Emacs -are normally per-buffer; the variable's document string tells you when -this is so. A per-buffer variable's global value is normally never -effective in any buffer, but it still has a meaning: it is the initial -value of the variable for each new buffer. - - Major modes (@pxref{Major Modes}) always make variables local to the -buffer before setting the variables. This is why changing major modes -in one buffer has no effect on other buffers. Minor modes also work -by setting variables---normally, each minor mode has one controlling -variable which is non-@code{nil} when the mode is enabled -(@pxref{Minor Modes}). For many minor modes, the controlling variable -is per buffer, and thus always buffer-local. Otherwise, you can make -it local in a specific buffer like any other variable. - - A few variables cannot be local to a buffer because they are always -local to each display instead (@pxref{Multiple Displays}). If you try to -make one of these variables buffer-local, you'll get an error message. - -@findex kill-local-variable - @kbd{M-x kill-local-variable} makes a specified variable cease to be -local to the current buffer. The global value of the variable -henceforth is in effect in this buffer. Setting the major mode kills -all the local variables of the buffer except for a few variables -specially marked as @dfn{permanent locals}. - -@findex setq-default - To set the global value of a variable, regardless of whether the -variable has a local value in the current buffer, you can use the Lisp -construct @code{setq-default}. This construct is used just like -@code{setq}, but it sets variables' global values instead of their local -values (if any). When the current buffer does have a local value, the -new global value may not be visible until you switch to another buffer. -Here is an example: - -@example -(setq-default fill-column 75) -@end example - -@noindent -@code{setq-default} is the only way to set the global value of a variable -that has been marked with @code{make-variable-buffer-local}. - -@findex default-value - Lisp programs can use @code{default-value} to look at a variable's -default value. This function takes a symbol as argument and returns its -default value. The argument is evaluated; usually you must quote it -explicitly. For example, here's how to obtain the default value of -@code{fill-column}: - -@example -(default-value 'fill-column) -@end example - -@node File Variables -@subsection Local Variables in Files -@cindex local variables in files -@cindex file local variables - - A file can specify local variable values for use when you edit the -file with Emacs. Visiting the file checks for local variable -specifications; it automatically makes these variables local to the -buffer, and sets them to the values specified in the file. - -@menu -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. -@end menu - -@node Specifying File Variables -@subsubsection Specifying File Variables - - There are two ways to specify file local variable values: in the first -line, or with a local variables list. Here's how to specify them in the -first line: - -@example --*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- -@end example - -@noindent -You can specify any number of variables/value pairs in this way, each -pair with a colon and semicolon as shown above. @code{mode: -@var{modename};} specifies the major mode; this should come first in the -line. The @var{value}s are not evaluated; they are used literally. -Here is an example that specifies Lisp mode and sets two variables with -numeric values: - -@smallexample -;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*- -@end smallexample - - You can also specify the coding system for a file in this way: just -specify a value for the ``variable'' named @code{coding}. The ``value'' -must be a coding system name that Emacs recognizes. @xref{Coding -Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a -particular Lisp file. @xref{Enabling Multibyte}. - - The @code{eval} pseudo-variable, described below, can be specified in -the first line as well. - -@cindex shell scripts, and local file variables -@cindex man pages, and local file variables - In shell scripts, the first line is used to identify the script -interpreter, so you cannot put any local variables there. To -accommodate this, Emacs looks for local variable specifications in the -@emph{second} line when the first line specifies an interpreter. -The same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors (not all do, -however). - - A @dfn{local variables list} goes near the end of the file. It -starts with a line containing the string @samp{Local Variables:}, and -ends with a line containing the string @samp{End:}. In between come -the variable names and values, one set per line, as -@samp{@var{variable}:@: @var{value}}. The @var{value}s are not -evaluated; they are used literally. If a file has both a local -variables list and a @samp{-*-} line, Emacs processes -@emph{everything} in the @samp{-*-} line first, and @emph{everything} -in the local variables list afterward. - - Here is an example of a local variables list: - -@example -/* Local Variables: */ -/* mode:c */ -/* comment-column:0 */ -/* End: */ -@end example - - In this example, each line starts with the prefix @samp{/*} and each -line ends with the suffix @samp{*/}. Emacs recognizes these as the -prefix and suffix by finding them surrounding the magic string -@samp{Local Variables:}, on the first line of the list; it then -automatically discards them from the other lines of the list. - - The usual reason for using a prefix and/or suffix is to embed the -local variables list in a comment, so it won't confuse other programs -that the file is intended as input for. The example above is for the -C programming language, where comment lines start with @samp{/*} and -end with @samp{*/}. Don't use a prefix (or a suffix) if you don't -need one. - - If you write a multi-line string value, you should put the prefix -and suffix on each line, even lines that start or end within the -string. They will be stripped off for processing the list. If you -want to split a long string across multiple lines of the file, you can -use backslash-newline, which is ignored in Lisp string constants. -Here's an example of doing this: - -@example -# Local Variables: -# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ -# -Dmumble=blaah" -# End: -@end example - - Some ``variable names'' have special meanings in a local variables -list. Specifying the ``variable'' @code{mode} really sets the major -mode, while any value specified for the ``variable'' @code{eval} is -simply evaluated as an expression (its value is ignored). A value for -@code{coding} specifies the coding system for character code -conversion of this file, and a value of @code{t} for @code{unibyte} -says to visit the file in a unibyte buffer. These four ``variables'' -are not really variables; setting them in any other context has no -special meaning. - - @emph{If @code{mode} is used to set a major mode, it should be the -first ``variable'' in the list.} Otherwise, the entries that precede -it will usually be ignored, since most modes kill all local variables -as part of their initialization. - - You can use the @code{mode} ``variable'' to set minor modes as well -as the major modes; in fact, you can use it more than once, first to -set the major mode and then to set minor modes which are specific to -particular buffers. But most minor modes should not be specified in -the file at all, because they represent user preferences. - - For example, you may be tempted to try to turn on Auto Fill mode with -a local variable list. That is a mistake. The choice of Auto Fill mode -or not is a matter of individual taste, not a matter of the contents of -particular files. If you want to use Auto Fill, set up major mode hooks -with your @file{.emacs} file to turn it on (when appropriate) for you -alone (@pxref{Init File}). Don't use a local variable list to impose -your taste on everyone. - - The start of the local variables list must be no more than 3000 -characters from the end of the file, and must be in the last page if -the file is divided into pages. Otherwise, Emacs will not notice it -is there. The purpose of this rule is so that Emacs need not take the -time to search the whole file. - - Use the command @code{normal-mode} to reset the local variables and -major mode of a buffer according to the file name and contents, -including the local variables list if any. @xref{Choosing Modes}. - -@node Safe File Variables -@subsubsection Safety of File Variables - - File-local variables can be dangerous; when you visit someone else's -file, there's no telling what its local variables list could do to -your Emacs. Improper values of the @code{eval} ``variable,'' and -other variables such as @code{load-path}, could execute Lisp code you -didn't intend to run. - - Therefore, whenever Emacs encounters file local variable values that -are not known to be safe, it displays the file's entire local -variables list, and asks you for confirmation before setting them. -You can type @kbd{y} or @key{SPC} to put the local variables list into -effect, or @kbd{n} to ignore it. When Emacs is run in batch mode -(@pxref{Initial Options}), it can't really ask you, so it assumes the -answer @kbd{n}. - - Emacs normally recognizes certain variables/value pairs as safe. -For instance, it is safe to give @code{comment-column} or -@code{fill-column} any integer value. If a file specifies only -known-safe variable/value pairs, Emacs does not ask for confirmation -before setting them. Otherwise, you can tell Emacs to record all the -variable/value pairs in this file as safe, by typing @kbd{!} at the -confirmation prompt. When Emacs encounters these variable/value pairs -subsequently, in the same file or others, it will assume they are -safe. - -@vindex safe-local-variable-values -@cindex risky variable - Some variables, such as @code{load-path}, are considered -particularly @dfn{risky}: there is seldom any reason to specify them -as local variables, and changing them can be dangerous. If a file -contains only risky local variables, Emacs neither offers nor accepts -@kbd{!} as input at the confirmation prompt. If some of the local -variables in a file are risky, and some are only potentially unsafe, you -can enter @kbd{!} at the prompt. It applies all the variables, but only -marks the non-risky ones as safe for the future. If you really want to -record safe values for risky variables, do it directly by customizing -@samp{safe-local-variable-values} (@pxref{Easy Customization}). - -@vindex enable-local-variables - The variable @code{enable-local-variables} allows you to change the -way Emacs processes local variables. Its default value is @code{t}, -which specifies the behavior described above. If it is @code{nil}, -Emacs simply ignores all file local variables. @code{:safe} means use -only the safe values and ignore the rest. Any other value says to -query you about each file that has local variables, without trying to -determine whether the values are known to be safe. - -@vindex enable-local-eval - The variable @code{enable-local-eval} controls whether Emacs -processes @code{eval} variables. The three possibilities for the -variable's value are @code{t}, @code{nil}, and anything else, just as -for @code{enable-local-variables}. The default is @code{maybe}, which -is neither @code{t} nor @code{nil}, so normally Emacs does ask for -confirmation about processing @code{eval} variables. - -@vindex safe-local-eval-forms - But there is an exception. The @code{safe-local-eval-forms} is a -customizable list of eval forms which are safe. Emacs does not ask -for confirmation when it finds these forms for the @code{eval} -variable. - -@node Directory Variables -@subsection Per-Directory Local Variables -@cindex local variables, for all files in a directory -@cindex directory local variables -@cindex per-directory local variables - - A @dfn{project} is a collection of files on which you work together. -Usually, the project's files are kept in one or more directories. -Occasionally, you may wish to define Emacs settings that are common to -all the files that belong to the project. - - Emacs provides two ways to specify settings that are applicable to -files in a specific directory: you can put a special file in that -directory, or you can define a @dfn{project class} for that directory. - -@cindex @file{.dir-locals.el} file - If you put a file with a special name @file{.dir-locals.el}@footnote{ -On MS-DOS, the name of this file should be @file{_dir-locals.el}, due -to limitations of the DOS filesystems. If the filesystem is limited -to 8+3 file names, the name of the file will be truncated by the OS to -@file{_dir-loc.el}. -} in a directory, Emacs will read it when it visits any file in that -directory or any of its subdirectories, and apply the settings it -specifies to the file's buffer. Emacs searches for -@file{.dir-locals.el} starting in the directory of the visited file, -and moving up the directory tree. (To avoid slowdown, this search is -skipped for remote files.) - - The @file{.dir-locals.el} file should hold a specially-constructed -list. This list maps Emacs mode names (symbols) to alists; each alist -specifies values for variables to use when the respective mode is -turned on. The special mode name @samp{nil} means that its alist -applies to any mode. Instead of a mode name, you can specify a string -that is a name of a subdirectory of the project's directory; then the -corresponding alist applies to all the files in that subdirectory. - - Here's an example of a @file{.dir-locals.el} file: - -@example -((nil . ((indent-tabs-mode . t) - (tab-width . 4) - (fill-column . 80))) - (c-mode . ((c-file-style . "BSD"))) - (java-mode . ((c-file-style . "BSD"))) - ("src/imported" - . ((nil . ((change-log-default-name . "ChangeLog.local")))))) -@end example - -@noindent -This example shows some settings for a hypothetical project. It sets -@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for -any file in the project's directory tree, and it sets the indentation -style for any C or Java source file. Finally, it specifies a different -@file{ChangeLog} file name for any file in the @file{src/imported} -subdirectory of the directory where you put the @file{.dir-locals.el} -file. - -@findex dir-locals-set-class-variables -@findex dir-locals-set-directory-class - Another method of specifying directory-local variables is to explicitly -define a project class using @code{dir-locals-set-class-variables}, and -then tell Emacs which directories correspond to that class, using -@code{dir-locals-set-directory-class}. You can put calls to these functions -in your @file{~/.emacs} init file; this can be useful when you can't put -@file{.dir-locals.el} in the directory for some reason, or if you want -to keep in a single place settings for several directories that don't -have a common parent. For example, you could apply settings to an -unwritable directory this way: - -@example -(dir-locals-set-class-variables 'unwritable-directory - '((nil . ((some-useful-setting . value))))) - -(dir-locals-set-directory-class - "/usr/include/" 'unwritable-directory) -@end example - - Unsafe directory-local variables are handled in the same way as -unsafe file-local variables (@pxref{Safe File Variables}). - -@node Key Bindings -@section Customizing Key Bindings -@cindex key bindings - - This section describes @dfn{key bindings}, which map keys to commands, -and @dfn{keymaps}, which record key bindings. It also explains how -to customize key bindings. - - Recall that a command is a Lisp function whose definition provides for -interactive use. Like every Lisp function, a command has a function -name, which usually consists of lower-case letters and hyphens. - -@menu -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. -@end menu - -@node Keymaps -@subsection Keymaps -@cindex keymap - - The bindings between key sequences and command functions are recorded -in data structures called @dfn{keymaps}. Emacs has many of these, each -used on particular occasions. - - A @dfn{key sequence} (@dfn{key}, for short) is a sequence of -@dfn{input events} that have a meaning as a unit. Input events -include characters, function keys and mouse buttons---all the inputs -that you can send to the computer with your terminal. A key sequence -gets its meaning from its @dfn{binding}, which says what command it -runs. The role of keymaps is to record these bindings. - -@cindex global keymap - The @dfn{global} keymap is the most important keymap because it is -always in effect. The global keymap defines keys for Fundamental mode; -most of these definitions are common to most or all major modes. Each -major or minor mode can have its own keymap which overrides the global -definitions of some keys. - - For example, a self-inserting character such as @kbd{g} is -self-inserting because the global keymap binds it to the command -@code{self-insert-command}. The standard Emacs editing characters such -as @kbd{C-a} also get their standard meanings from the global keymap. -Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work -by storing the new binding in the proper place in the global map. -@xref{Rebinding}. - -@cindex function key - Most modern keyboards have function keys as well as character keys. -Function keys send input events just as character keys do, and keymaps -can have bindings for them. On text terminals, typing a function key -actually sends the computer a sequence of characters; the precise -details of the sequence depends on which function key and on the model -of terminal you are using. (Often the sequence starts with -@kbd{@key{ESC} [}.) If Emacs understands your terminal type properly, -it recognizes the character sequences forming function keys wherever -they occur in a key sequence. Thus, for most purposes, you can -pretend the function keys reach Emacs directly and ignore their -encoding as character sequences. - - Key sequences can mix function keys and characters. For example, if -your keyboard has a @key{Home} function key, Emacs also recognizes key -sequences like @kbd{C-x @key{Home}}. You can even mix mouse events -with keyboard events, but we recommend against it, because such key -sequences are inconvenient to use. - - As a user, you can redefine any key, but it is usually best to stick -to key sequences that consist of @kbd{C-c} followed by a letter (upper -or lower case). These keys are ``reserved for users,'' so they won't -conflict with any properly designed Emacs extension. The function -keys @key{F5} through @key{F9} are also reserved for users. If you -redefine some other key, your definition may be overridden by certain -extensions or major modes which redefine the same key. - -@node Prefix Keymaps -@subsection Prefix Keymaps - - Internally, Emacs records only single events in each keymap. -Interpreting a key sequence of multiple events involves a chain of -keymaps: the first keymap gives a definition for the first event, -which is another keymap, which is used to look up the second event in -the sequence, and so on. Thus, a prefix key such as @kbd{C-x} or -@key{ESC} has its own keymap, which holds the definition for the event -that immediately follows that prefix. - - The definition of a prefix key is usually the keymap to use for -looking up the following event. The definition can also be a Lisp -symbol whose function definition is the following keymap; the effect is -the same, but it provides a command name for the prefix key that can be -used as a description of what the prefix key is for. Thus, the binding -of @kbd{C-x} is the symbol @code{Control-X-prefix}, whose function -definition is the keymap for @kbd{C-x} commands. The definitions of -@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in -the global map, so these prefix keys are always available. - - Aside from ordinary prefix keys, there is a fictitious ``prefix key'' -which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp -Reference Manual}, for special information about menu bar key bindings. -Mouse button events that invoke pop-up menus are also prefix keys; see -@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more -details. - - Some prefix keymaps are stored in variables with names: - -@itemize @bullet -@item -@vindex ctl-x-map -@code{ctl-x-map} is the variable name for the map used for characters that -follow @kbd{C-x}. -@item -@vindex help-map -@code{help-map} is for characters that follow @kbd{C-h}. -@item -@vindex esc-map -@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta -characters are actually defined by this map. -@item -@vindex ctl-x-4-map -@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. -@item -@vindex mode-specific-map -@code{mode-specific-map} is for characters that follow @kbd{C-c}. -@end itemize - -@node Local Keymaps -@subsection Local Keymaps - -@cindex local keymap - So far we have explained the ins and outs of the global map. Major -modes customize Emacs by providing their own key bindings in @dfn{local -keymaps}. For example, C mode overrides @key{TAB} to make it indent the -current line for C code. Portions of text in the buffer can specify -their own keymaps to substitute for the keymap of the buffer's major -mode. - -@cindex minor mode keymap - Minor modes can also have local keymaps. Whenever a minor mode is -in effect, the definitions in its keymap override both the major -mode's local keymap and the global keymap. - - A local keymap can locally redefine a key as a prefix key by defining -it as a prefix keymap. If the key is also defined globally as a prefix, -then its local and global definitions (both keymaps) effectively -combine: both of them are used to look up the event that follows the -prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as -another keymap, and that keymap defines @kbd{C-z} as a command, this -provides a local meaning for @kbd{C-c C-z}. This does not affect other -sequences that start with @kbd{C-c}; if those sequences don't have their -own local bindings, their global bindings remain in effect. - - Another way to think of this is that Emacs handles a multi-event key -sequence by looking in several keymaps, one by one, for a binding of the -whole key sequence. First it checks the minor mode keymaps for minor -modes that are enabled, then it checks the major mode's keymap, and then -it checks the global keymap. This is not precisely how key lookup -works, but it's good enough for understanding the results in ordinary -circumstances. - -@cindex rebinding major mode keys - Most major modes construct their keymaps when the mode is used for -the first time in a session. If you wish to change one of these -keymaps, you must use the major mode's @dfn{mode hook} -(@pxref{Hooks}). - -@findex define-key - For example, the command @code{texinfo-mode} to select Texinfo mode -runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook -to add local bindings (not very useful, we admit) for @kbd{C-c n} and -@kbd{C-c p} in Texinfo mode: - -@example -(add-hook 'texinfo-mode-hook - '(lambda () - (define-key texinfo-mode-map "\C-cp" - 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" - 'forward-paragraph))) -@end example - -@node Minibuffer Maps -@subsection Minibuffer Keymaps - -@cindex minibuffer keymaps -@vindex minibuffer-local-map -@vindex minibuffer-local-ns-map -@vindex minibuffer-local-completion-map -@vindex minibuffer-local-must-match-map -@vindex minibuffer-local-filename-completion-map -@vindex minibuffer-local-must-match-filename-map - The minibuffer has its own set of local keymaps; they contain various -completion and exit commands. - -@itemize @bullet -@item -@code{minibuffer-local-map} is used for ordinary input (no completion). -@item -@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits -just like @key{RET}. This is used mainly for Mocklisp compatibility. -@item -@code{minibuffer-local-completion-map} is for permissive completion. -@item -@code{minibuffer-local-must-match-map} is for strict completion and -for cautious completion. -@item -Finally, @code{minibuffer-local-filename-completion-map} and -@code{minibuffer-local-must-match-filename-map} are like the two -previous ones, but they are specifically for file name completion. -They do not bind @key{SPC}. -@end itemize - -@node Rebinding -@subsection Changing Key Bindings Interactively -@cindex key rebinding, this session -@cindex redefining keys, this session - - The way to redefine an Emacs key is to change its entry in a keymap. -You can change the global keymap, in which case the change is effective in -all major modes (except those that have their own overriding local -definitions for the same key). Or you can change the current buffer's -local map, which affects all buffers using the same major mode. - -@findex global-set-key -@findex local-set-key -@findex global-unset-key -@findex local-unset-key -@table @kbd -@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} globally to run @var{cmd}. -@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} -Define @var{key} locally (in the major mode now in effect) to run -@var{cmd}. -@item M-x global-unset-key @key{RET} @var{key} -Make @var{key} undefined in the global map. -@item M-x local-unset-key @key{RET} @var{key} -Make @var{key} undefined locally (in the major mode now in effect). -@end table - - For example, suppose you like to execute commands in a subshell within -an Emacs buffer, instead of suspending Emacs and executing commands in -your login shell. Normally, @kbd{C-z} is bound to the function -@code{suspend-emacs} (when not using the X Window System), but you can -change @kbd{C-z} to invoke an interactive subshell within Emacs, by -binding it to @code{shell} as follows: - -@example -M-x global-set-key @key{RET} C-z shell @key{RET} -@end example - -@noindent -@code{global-set-key} reads the command name after the key. After you -press the key, a message like this appears so that you can confirm that -you are binding the key you want: - -@example -Set key C-z to command: -@end example - - You can redefine function keys and mouse events in the same way; just -type the function key or click the mouse when it's time to specify the -key to rebind. - - You can rebind a key that contains more than one event in the same -way. Emacs keeps reading the key to rebind until it is a complete key -(that is, not a prefix key). Thus, if you type @kbd{C-f} for -@var{key}, that's the end; it enters the minibuffer immediately to -read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it -reads another character; if that is @kbd{4}, another prefix character, -it reads one more character, and so on. For example, - -@example -M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} -@end example - -@noindent -redefines @kbd{C-x 4 $} to run the (fictitious) command -@code{spell-other-window}. - - You can remove the global definition of a key with -@code{global-unset-key}. This makes the key @dfn{undefined}; if you -type it, Emacs will just beep. Similarly, @code{local-unset-key} makes -a key undefined in the current major mode keymap, which makes the global -definition (or lack of one) come back into effect in that major mode. - - If you have redefined (or undefined) a key and you subsequently wish -to retract the change, undefining the key will not do the job---you need -to redefine the key with its standard definition. To find the name of -the standard definition of a key, go to a Fundamental mode buffer in a -fresh Emacs and use @kbd{C-h c}. The documentation of keys in this -manual also lists their command names. - - If you want to prevent yourself from invoking a command by mistake, it -is better to disable the command than to undefine the key. A disabled -command is less work to invoke when you really want to. -@xref{Disabling}. - -@node Init Rebinding -@subsection Rebinding Keys in Your Init File -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) - - If you have a set of key bindings that you like to use all the time, -you can specify them in your initialization file by writing Lisp code -(@pxref{Init File}). - -@findex kbd - There are several ways to write a key binding using Lisp. The -simplest is to use the @code{kbd} macro, which converts a textual -representation of a key sequence---similar to how we have written key -sequences in this manual---into a form that can be passed as an -argument to @code{global-set-key}. For example, here's how to bind -@kbd{C-z} to @code{shell} (@pxref{Interactive Shell}): - -@example -(global-set-key (kbd "C-z") 'shell) -@end example - -@noindent -The single-quote before the command name, @code{shell}, marks it as a -constant symbol rather than a variable. If you omit the quote, Emacs -would try to evaluate @code{shell} as a variable. This probably -causes an error; it certainly isn't what you want. - - Here are some additional examples, including binding function keys -and mouse events: - -@example -(global-set-key (kbd "C-c y") 'clipboard-yank) -(global-set-key (kbd "C-M-q") 'query-replace) -(global-set-key (kbd "") 'flyspell-mode) -(global-set-key (kbd "C-") 'linum-mode) -(global-set-key (kbd "C-") 'forward-sentence) -(global-set-key (kbd "") 'mouse-save-then-kill) -(global-set-key (kbd "C-") 'mouse-yank-at-click) -@end example - - Instead of using the @code{kbd} macro, you can use a Lisp string or -vector to specify the key sequence. Using a string is simpler, but -only works for @acronym{ASCII} characters and Meta-modified -@acronym{ASCII} characters. For example, here's how to bind @kbd{C-x -M-l} to @code{make-symbolic-link} (@pxref{Misc File Ops}): - -@example -(global-set-key "\C-x\M-l" 'make-symbolic-link) -@end example - - To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the string, -use the Emacs Lisp escape sequences @samp{\t}, @samp{\r}, @samp{\e}, -and @samp{\d} respectively. Here is an example which binds @kbd{C-x -@key{TAB}} to @code{indent-rigidly} (@pxref{Indentation}): - -@example -(global-set-key "\C-x\t" 'indent-rigidly) -@end example - - When the key sequence includes function keys or mouse button events, -or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, -you must use a vector to specify the key sequence. Each element in -the vector stands for an input event; the elements are separated by -spaces and surrounded by a pair of square brackets. If an element is -a symbol, simply write the symbol's name---no other delimiters or -punctuation are needed. If a vector element is a character, write it -as a Lisp character constant: @samp{?} followed by the character as it -would appear in a string. Here are some examples: - -@example -(global-set-key [?\C-=] 'make-symbolic-link) -(global-set-key [?\M-\C-=] 'make-symbolic-link) -(global-set-key [?\H-a] 'make-symbolic-link) -(global-set-key [f7] 'make-symbolic-link) -(global-set-key [C-mouse-1] 'make-symbolic-link) -@end example - -@noindent -You can use a vector for the simple cases too: - -@example -(global-set-key [?\C-z ?\M-l] 'make-symbolic-link) -@end example - - Language and coding systems may cause problems with key bindings for -non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. - -@node Modifier Keys -@subsection Modifier Keys -@cindex modifier keys - - The default key bindings in Emacs are set up so that modified -alphabetical characters are case-insensitive. In other words, -@kbd{C-A} does the same thing as @kbd{C-a}, and @kbd{M-A} does the -same thing as @kbd{M-a}. This concerns only alphabetical characters, -and does not apply to ``shifted'' versions of other keys; for -instance, @kbd{C-@@} is not the same as @kbd{C-2}. - - When you customize Emacs, you can make modified alphabetical -characters case-sensitive. For instance, you could make @kbd{M-a} and -@kbd{M-A} run different commands. - - As a special exception, a @key{Control}-modified alphabetical -character is always case-insensitive, for historical reasons: Emacs -always treats @kbd{C-A} as @kbd{C-a}, @kbd{C-B} as @kbd{C-b}, and so -forth. - - Although only the @key{Control} and @key{Meta} modifier keys are -commonly used, Emacs supports three other modifier keys. These are -called @key{Super}, @key{Hyper} and @key{Alt}. Few terminals provide -ways to use these modifiers; the key labeled @key{Alt} on most -keyboards usually issues the @key{Meta} modifier, not @key{Alt}. The -standard key bindings in Emacs do not include any characters with -these modifiers. However, you can customize Emacs to assign meanings -to them. The modifier bits are labelled as @samp{s-}, @samp{H-} and -@samp{A-} respectively. - - Even if your keyboard lacks these additional modifier keys, you can -enter it using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to -the next character, @kbd{C-x @@ s} adds the ``super'' flag, and -@kbd{C-x @@ a} adds the ``alt'' flag. For instance, @kbd{C-x @@ h -C-a} is a way to enter @kbd{Hyper-Control-a}. (Unfortunately, there -is no way to add two modifiers by using @kbd{C-x @@} twice for the -same character, because the first one goes to work on the @kbd{C-x}.) - -@node Function Keys -@subsection Rebinding Function Keys - - Key sequences can contain function keys as well as ordinary -characters. Just as Lisp characters (actually integers) represent -keyboard characters, Lisp symbols represent function keys. If the -function key has a word as its label, then that word is also the name of -the corresponding Lisp symbol. Here are the conventional Lisp names for -common function keys: - -@table @asis -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys. - -@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} -Other cursor repositioning keys. - -@item @code{select}, @code{print}, @code{execute}, @code{backtab} -@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} -@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar} -Miscellaneous function keys. - -@item @code{f1}, @code{f2}, @dots{} @code{f35} -Numbered function keys (across the top of the keyboard). - -@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} -@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} -@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} -Keypad keys (to the right of the regular keyboard), with names or punctuation. - -@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} -Keypad keys with digits. - -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@end table - - These names are conventional, but some systems (especially when using -X) may use different names. To make certain what symbol is used for a -given function key on your terminal, type @kbd{C-h c} followed by that -key. - - @xref{Init Rebinding}, for examples of binding function keys. - -@cindex keypad - Many keyboards have a ``numeric keypad'' on the right hand side. -The numeric keys in the keypad double up as cursor motion keys, -toggled by a key labeled @samp{Num Lock}. By default, Emacs -translates these keys to the corresponding keys in the main keyboard. -For example, when @samp{Num Lock} is on, the key labeled @samp{8} on -the numeric keypad produces @code{kp-8}, which is translated to -@kbd{8}; when @samp{Num Lock} is off, the same key produces -@code{kp-up}, which is translated to @key{UP}. If you rebind a key -such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. -However, if you rebind a @samp{kp-} key directly, that won't affect -its non-keypad equivalent. Note that the modified keys are not -translated: for instance, if you hold down the @key{META} key while -pressing the @samp{8} key on the numeric keypad, that generates -@kbd{M-@key{kp-8}}. - - Emacs provides a convenient method for binding the numeric keypad -keys, using the variables @code{keypad-setup}, -@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and -@code{keypad-numlock-shifted-setup}. These can be found in the -@samp{keyboard} customization group (@pxref{Easy Customization}). You -can rebind the keys to perform other tasks, such as issuing numeric -prefix arguments. - -@node Named ASCII Chars -@subsection Named @acronym{ASCII} Control Characters - - @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} -started out as names for certain @acronym{ASCII} control characters, -used so often that they have special keys of their own. For instance, -@key{TAB} was another name for @kbd{C-i}. Later, users found it -convenient to distinguish in Emacs between these keys and the ``same'' -control characters typed with the @key{CTRL} key. Therefore, on most -modern terminals, they are no longer the same: @key{TAB} is different -from @kbd{C-i}. - - Emacs can distinguish these two kinds of input if the keyboard does. -It treats the ``special'' keys as function keys named @code{tab}, -@code{return}, @code{backspace}, @code{linefeed}, @code{escape}, and -@code{delete}. These function keys translate automatically into the -corresponding @acronym{ASCII} characters @emph{if} they have no -bindings of their own. As a result, neither users nor Lisp programs -need to pay attention to the distinction unless they care to. - - If you do not want to distinguish between (for example) @key{TAB} and -@kbd{C-i}, make just one binding, for the @acronym{ASCII} character @key{TAB} -(octal code 011). If you do want to distinguish, make one binding for -this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. - - With an ordinary @acronym{ASCII} terminal, there is no way to distinguish -between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), -because the terminal sends the same character in both cases. - -@node Mouse Buttons -@subsection Rebinding Mouse Buttons -@cindex mouse button events -@cindex rebinding mouse buttons -@cindex click events -@cindex drag events -@cindex down events -@cindex button down events - - Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary -mouse events in Emacs are @dfn{click} events; these happen when you -press a button and release it without moving the mouse. You can also -get @dfn{drag} events, when you move the mouse while holding the button -down. Drag events happen when you finally let go of the button. - - The symbols for basic click events are @code{mouse-1} for the leftmost -button, @code{mouse-2} for the next, and so on. Here is how you can -redefine the second mouse button to split the current window: - -@example -(global-set-key [mouse-2] 'split-window-vertically) -@end example - - The symbols for drag events are similar, but have the prefix -@samp{drag-} before the word @samp{mouse}. For example, dragging the -first button generates a @code{drag-mouse-1} event. - - You can also define bindings for events that occur when a mouse button -is pressed down. These events start with @samp{down-} instead of -@samp{drag-}. Such events are generated only if they have key bindings. -When you get a button-down event, a corresponding click or drag event -will always follow. - -@cindex double clicks -@cindex triple clicks - If you wish, you can distinguish single, double, and triple clicks. A -double click means clicking a mouse button twice in approximately the -same place. The first click generates an ordinary click event. The -second click, if it comes soon enough, generates a double-click event -instead. The event type for a double-click event starts with -@samp{double-}: for example, @code{double-mouse-3}. - - This means that you can give a special meaning to the second click at -the same place, but it must act on the assumption that the ordinary -single click definition has run when the first click was received. - - This constrains what you can do with double clicks, but user interface -designers say that this constraint ought to be followed in any case. A -double click should do something similar to the single click, only -``more so.'' The command for the double-click event should perform the -extra work for the double click. - - If a double-click event has no binding, it changes to the -corresponding single-click event. Thus, if you don't define a -particular double click specially, it executes the single-click command -twice. - - Emacs also supports triple-click events whose names start with -@samp{triple-}. Emacs does not distinguish quadruple clicks as event -types; clicks beyond the third generate additional triple-click events. -However, the full number of clicks is recorded in the event list, so -if you know Emacs Lisp you can distinguish if you really want to -(@pxref{Click Events,,, elisp, The Emacs Lisp Reference Manual}). -We don't recommend distinct meanings for more than three clicks, but -sometimes it is useful for subsequent clicks to cycle through the same -set of three meanings, so that four clicks are equivalent to one -click, five are equivalent to two, and six are equivalent to three. - - Emacs also records multiple presses in drag and button-down events. -For example, when you press a button twice, then move the mouse while -holding the button, Emacs gets a @samp{double-drag-} event. And at the -moment when you press it down for the second time, Emacs gets a -@samp{double-down-} event (which is ignored, like all button-down -events, if it has no binding). - -@vindex double-click-time - The variable @code{double-click-time} specifies how much time can -elapse between clicks and still allow them to be grouped as a multiple -click. Its value is in units of milliseconds. If the value is -@code{nil}, double clicks are not detected at all. If the value is -@code{t}, then there is no time limit. The default is 500. - -@vindex double-click-fuzz - The variable @code{double-click-fuzz} specifies how much the mouse -can move between clicks and still allow them to be grouped as a multiple -click. Its value is in units of pixels on windowed displays and in -units of 1/8 of a character cell on text-mode terminals; the default is -3. - - The symbols for mouse events also indicate the status of the modifier -keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, -@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} -or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. - - A frame includes areas that don't show text from the buffer, such as -the mode line and the scroll bar. You can tell whether a mouse button -comes from a special area of the screen by means of dummy ``prefix -keys.'' For example, if you click the mouse in the mode line, you get -the prefix key @code{mode-line} before the ordinary mouse-button symbol. -Thus, here is how to define the command for clicking the first button in -a mode line to run @code{scroll-up}: - -@example -(global-set-key [mode-line mouse-1] 'scroll-up) -@end example - - Here is the complete list of these dummy prefix keys and their -meanings: - -@table @code -@item mode-line -The mouse was in the mode line of a window. -@item vertical-line -The mouse was in the vertical line separating side-by-side windows. (If -you use scroll bars, they appear in place of these vertical lines.) -@item vertical-scroll-bar -The mouse was in a vertical scroll bar. (This is the only kind of -scroll bar Emacs currently supports.) -@item menu-bar -The mouse was in the menu bar. -@item header-line -The mouse was in a header line. -@ignore -@item horizontal-scroll-bar -The mouse was in a horizontal scroll bar. Horizontal scroll bars do -horizontal scrolling, and people don't use them often. -@end ignore -@end table - - You can put more than one mouse button in a key sequence, but it isn't -usual to do so. - -@node Disabling -@subsection Disabling Commands -@cindex disabled command - - Disabling a command means that invoking it interactively asks for -confirmation from the user. The purpose of disabling a command is to -prevent users from executing it by accident; we do this for commands -that might be confusing to the uninitiated. - - Attempting to invoke a disabled command interactively in Emacs -displays a window containing the command's name, its documentation, -and some instructions on what to do immediately; then Emacs asks for -input saying whether to execute the command as requested, enable it -and execute it, or cancel. If you decide to enable the command, you -must then answer another question---whether to do this permanently, or -just for the current session. (Enabling permanently works by -automatically editing your @file{.emacs} file.) You can also type -@kbd{!} to enable @emph{all} commands, for the current session only. - - The direct mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. Here is the Lisp program to do this: - -@example -(put 'delete-region 'disabled t) -@end example - - If the value of the @code{disabled} property is a string, that string -is included in the message displayed when the command is used: - -@example -(put 'delete-region 'disabled - "It's better to use `kill-region' instead.\n") -@end example - -@findex disable-command -@findex enable-command - You can make a command disabled either by editing the @file{.emacs} -file directly, or with the command @kbd{M-x disable-command}, which edits -the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} -edits @file{.emacs} to enable a command permanently. @xref{Init File}. - - If Emacs was invoked with the @option{-q} or @option{--no-init-file} -options (@pxref{Initial Options}), it will not edit your -@file{~/.emacs} init file. Doing so could lose information -because Emacs has not read your init file. - - Whether a command is disabled is independent of what key is used to -invoke it; disabling also applies if the command is invoked using -@kbd{M-x}. However, disabling a command has no effect on calling it -as a function from Lisp programs. - -@node Syntax -@section The Syntax Table -@cindex syntax table - - All the Emacs commands which parse words or balance parentheses are -controlled by the @dfn{syntax table}. The syntax table says which -characters are opening delimiters, which are parts of words, which are -string quotes, and so on. It does this by assigning each character to -one of fifteen-odd @dfn{syntax classes}. In some cases it specifies -some additional information also. - - Each major mode has its own syntax table (though related major modes -sometimes share one syntax table), which it installs in each buffer -that uses the mode. The syntax table installed in the current buffer -is the one that all commands use, so we call it ``the'' syntax table. - -@kindex C-h s -@findex describe-syntax - To display a description of the contents of the current syntax -table, type @kbd{C-h s} (@code{describe-syntax}). The description of -each character includes the string you would have to give to -@code{modify-syntax-entry} to set up that character's current syntax, -starting with the character which designates its syntax class, plus -some English text to explain its meaning. - - A syntax table is actually a Lisp object, a char-table, whose -elements are cons cells. For full information on the syntax table, -see @ref{Syntax Tables,, Syntax Tables, elisp, The Emacs Lisp -Reference Manual}. - -@node Init File -@section The Init File, @file{~/.emacs} -@cindex init file -@cindex Emacs initialization file -@cindex key rebinding, permanent -@cindex rebinding keys, permanently -@cindex startup (init file) - - When Emacs is started, it normally tries to load a Lisp program from -an @dfn{initialization file}, or @dfn{init file} for short. This -file, if it exists, specifies how to initialize Emacs for you. Emacs -looks for your init file using the filenames @file{~/.emacs}, -@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to -use any one of these three names (@pxref{Find Init}). Here, @file{~/} -stands for your home directory. - - You can use the command line switch @samp{-q} to prevent loading -your init file, and @samp{-u} (or @samp{--user}) to specify a -different user's init file (@pxref{Initial Options}). - -@cindex @file{default.el}, the default init file - There can also be a @dfn{default init file}, which is the library -named @file{default.el}, found via the standard search path for -libraries. The Emacs distribution contains no such library; your site -may create one for local customizations. If this library exists, it is -loaded whenever you start Emacs (except when you specify @samp{-q}). -But your init file, if any, is loaded first; if it sets -@code{inhibit-default-init} non-@code{nil}, then @file{default} is not -loaded. - -@cindex site init file -@cindex @file{site-start.el}, the site startup file - Your site may also have a @dfn{site startup file}; this is named -@file{site-start.el}, if it exists. Like @file{default.el}, Emacs -finds this file via the standard search path for Lisp libraries. -Emacs loads this library before it loads your init file. To inhibit -loading of this library, use the option @samp{--no-site-file}. -@xref{Initial Options}. We recommend against using -@file{site-start.el} for changes that some users may not like. It is -better to put them in @file{default.el}, so that users can more easily -override them. - - You can place @file{default.el} and @file{site-start.el} in any of -the directories which Emacs searches for Lisp libraries. The variable -@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. -Many sites put these files in the @file{site-lisp} subdirectory of the -Emacs installation directory, typically -@file{/usr/local/share/emacs/site-lisp}. - - Byte-compiling your init file is not recommended (@pxref{Byte -Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference -Manual}). It generally does not speed up startup very much, and often -leads to problems when you forget to recompile the file. A better -solution is to use the Emacs server to reduce the number of times you -have to start Emacs (@pxref{Emacs Server}). If your init file defines -many functions, consider moving them to a separate (byte-compiled) -file that you load in your init file. - - If you are going to write actual Emacs Lisp programs that go beyond -minor customization, you should read the @cite{Emacs Lisp Reference Manual}. -@ifnottex -@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference -Manual}. -@end ifnottex - -@menu -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. -@end menu - -@node Init Syntax -@subsection Init File Syntax - - The init file contains one or more Lisp expressions. Each of these -consists of a function name followed by arguments, all surrounded by -parentheses. For example, @code{(setq fill-column 60)} calls the -function @code{setq} to set the variable @code{fill-column} -(@pxref{Filling}) to 60. - - You can set any Lisp variable with @code{setq}, but with certain -variables @code{setq} won't do what you probably want in the -@file{.emacs} file. Some variables automatically become buffer-local -when set with @code{setq}; what you want in @file{.emacs} is to set -the default value, using @code{setq-default}. Some customizable minor -mode variables do special things to enable the mode when you set them -with Customize, but ordinary @code{setq} won't do that; to enable the -mode in your @file{.emacs} file, call the minor mode command. The -following section has examples of both of these methods. - - The second argument to @code{setq} is an expression for the new -value of the variable. This can be a constant, a variable, or a -function call expression. In @file{.emacs}, constants are used most -of the time. They can be: - -@table @asis -@item Numbers: -Numbers are written in decimal, with an optional initial minus sign. - -@item Strings: -@cindex Lisp string syntax -@cindex string syntax -Lisp string syntax is the same as C string syntax with a few extra -features. Use a double-quote character to begin and end a string constant. - -In a string, you can include newlines and special characters literally. -But often it is cleaner to use backslash sequences for them: @samp{\n} -for newline, @samp{\b} for backspace, @samp{\r} for carriage return, -@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for -escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or -@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. -Backslash and double-quote are the only characters for which backslash -sequences are mandatory. - -@samp{\C-} can be used as a prefix for a control character, as in -@samp{\C-s} for @acronym{ASCII} control-S, and @samp{\M-} can be used as a prefix for -a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for -@kbd{Control-Meta-A}.@refill - -@xref{Init Non-ASCII}, for information about including -non-@acronym{ASCII} in your init file. - -@item Characters: -Lisp character constant syntax consists of a @samp{?} followed by -either a character or an escape sequence starting with @samp{\}. -Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that -strings and characters are not interchangeable in Lisp; some contexts -require one and some contexts require the other. - -@xref{Init Non-ASCII}, for information about binding commands to -keys which send non-@acronym{ASCII} characters. - -@item True: -@code{t} stands for `true'. - -@item False: -@code{nil} stands for `false'. - -@item Other Lisp objects: -Write a single-quote (@code{'}) followed by the Lisp object you want. -@end table - -@node Init Examples -@subsection Init File Examples - - Here are some examples of doing certain commonly desired things with -Lisp expressions: - -@itemize @bullet -@item -Add a directory to the variable @code{load-path}. You can then put -Lisp libraries that are not included with Emacs in this directory, and -load them with @kbd{M-x load-library}. @xref{Lisp Libraries}. - -@example -(add-to-list 'load-path "/path/to/lisp/libraries") -@end example - -@item -Make @key{TAB} in C mode just insert a tab if point is in the middle of a -line. - -@example -(setq c-tab-always-indent nil) -@end example - -Here we have a variable whose value is normally @code{t} for `true' -and the alternative is @code{nil} for `false'. - -@item -Make searches case sensitive by default (in all buffers that do not -override this). - -@example -(setq-default case-fold-search nil) -@end example - -This sets the default value, which is effective in all buffers that do -not have local values for the variable. Setting @code{case-fold-search} -with @code{setq} affects only the current buffer's local value, which -is not what you probably want to do in an init file. - -@item -@vindex user-mail-address -Specify your own email address, if Emacs can't figure it out correctly. - -@example -(setq user-mail-address "rumsfeld@@torture.gov") -@end example - -Various Emacs packages that need your own email address use the value of -@code{user-mail-address}. - -@item -Make Text mode the default mode for new buffers. - -@example -(setq default-major-mode 'text-mode) -@end example - -Note that @code{text-mode} is used because it is the command for -entering Text mode. The single-quote before it makes the symbol a -constant; otherwise, @code{text-mode} would be treated as a variable -name. - -@need 1500 -@item -Set up defaults for the Latin-1 character set -which supports most of the languages of Western Europe. - -@example -(set-language-environment "Latin-1") -@end example - -@need 1500 -@item -Turn off Line Number mode, a global minor mode. - -@example -(line-number-mode 0) -@end example - -@need 1500 -@item -Turn on Auto Fill mode automatically in Text mode and related modes. - -@example -(add-hook 'text-mode-hook - '(lambda () (auto-fill-mode 1))) -@end example - -This shows how to add a hook function to a normal hook variable -(@pxref{Hooks}). The function we supply is a list starting with -@code{lambda}, with a single-quote in front of it to make it a list -constant rather than an expression. - -It's beyond the scope of this manual to explain Lisp functions, but for -this example it is enough to know that the effect is to execute -@code{(auto-fill-mode 1)} when Text mode is entered. You can replace -that with any other expression that you like, or with several -expressions in a row. - -Emacs comes with a function named @code{turn-on-auto-fill} whose -definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler -way to write the above example is as follows: - -@example -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end example - -@item -Load the installed Lisp library named @file{foo} (actually a file -@file{foo.elc} or @file{foo.el} in a standard Emacs directory). - -@example -(load "foo") -@end example - -When the argument to @code{load} is a relative file name, not starting -with @samp{/} or @samp{~}, @code{load} searches the directories in -@code{load-path} (@pxref{Lisp Libraries}). - -@item -Load the compiled Lisp file @file{foo.elc} from your home directory. - -@example -(load "~/foo.elc") -@end example - -Here an absolute file name is used, so no searching is done. - -@item -@cindex loading Lisp libraries automatically -@cindex autoload Lisp libraries -Tell Emacs to find the definition for the function @code{myfunction} -by loading a Lisp library named @file{mypackage} (i.e.@: a file -@file{mypackage.elc} or @file{mypackage.el}): - -@example -(autoload 'myfunction "mypackage" "Do what I say." t) -@end example - -@noindent -Here the string @code{"Do what I say."} is the function's -documentation string. You specify it in the @code{autoload} -definition so it will be available for help commands even when the -package is not loaded. The last argument, @code{t}, indicates that -this function is interactive; that is, it can be invoked interactively -by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. -If the function is not interactive, omit the @code{t} or use -@code{nil}. - -@item -Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} -(@pxref{Init Rebinding}). - -@example -(global-set-key "\C-xl" 'make-symbolic-link) -@end example - -or - -@example -(define-key global-map "\C-xl" 'make-symbolic-link) -@end example - -Note once again the single-quote used to refer to the symbol -@code{make-symbolic-link} instead of its value as a variable. - -@item -Do the same thing for Lisp mode only. - -@example -(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) -@end example - -@item -Redefine all keys which now run @code{next-line} in Fundamental mode -so that they run @code{forward-line} instead. - -@findex substitute-key-definition -@example -(substitute-key-definition 'next-line 'forward-line - global-map) -@end example - -@item -Make @kbd{C-x C-v} undefined. - -@example -(global-unset-key "\C-x\C-v") -@end example - -One reason to undefine a key is so that you can make it a prefix. -Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a -prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix -definition. - -@item -Make @samp{$} have the syntax of punctuation in Text mode. -Note the use of a character constant for @samp{$}. - -@example -(modify-syntax-entry ?\$ "." text-mode-syntax-table) -@end example - -@item -Enable the use of the command @code{narrow-to-region} without confirmation. - -@example -(put 'narrow-to-region 'disabled nil) -@end example - -@item -Adjusting the configuration to various platforms and Emacs versions. - -Users typically want Emacs to behave the same on all systems, so the -same init file is right for all platforms. However, sometimes it -happens that a function you use for customizing Emacs is not available -on some platforms or in older Emacs versions. To deal with that -situation, put the customization inside a conditional that tests whether -the function or facility is available, like this: - -@example -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode 0)) - -(if (boundp 'coding-category-utf-8) - (set-coding-priority '(coding-category-utf-8))) -@end example - -@noindent -You can also simply disregard the errors that occur if the -function is not defined. - -@example -(condition case () - (set-face-background 'region "grey75") - (error nil)) -@end example - -A @code{setq} on a variable which does not exist is generally -harmless, so those do not need a conditional. -@end itemize - -@node Terminal Init -@subsection Terminal-specific Initialization - - Each terminal type can have a Lisp library to be loaded into Emacs when -it is run on that type of terminal. For a terminal type named -@var{termtype}, the library is called @file{term/@var{termtype}} and it is -found by searching the directories @code{load-path} as usual and trying the -suffixes @samp{.elc} and @samp{.el}. Normally it appears in the -subdirectory @file{term} of the directory where most Emacs libraries are -kept.@refill - - The usual purpose of the terminal-specific library is to map the -escape sequences used by the terminal's function keys onto more -meaningful names, using @code{input-decode-map} (or -@code{function-key-map} before it). See the file -@file{term/lk201.el} for an example of how this is done. Many function -keys are mapped automatically according to the information in the -Termcap data base; the terminal-specific library needs to map only the -function keys that Termcap does not specify. - - When the terminal type contains a hyphen, only the part of the name -before the first hyphen is significant in choosing the library name. -Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use -the library @file{term/aaa}. The code in the library can use -@code{(getenv "TERM")} to find the full terminal type name.@refill - -@vindex term-file-prefix - The library's name is constructed by concatenating the value of the -variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} -file can prevent the loading of the terminal-specific library by setting -@code{term-file-prefix} to @code{nil}. - -@vindex term-setup-hook - Emacs runs the hook @code{term-setup-hook} at the end of -initialization, after both your @file{.emacs} file and any -terminal-specific library have been read in. Add hook functions to this -hook if you wish to override part of any of the terminal-specific -libraries and to define initializations for terminals that do not have a -library. @xref{Hooks}. - -@node Find Init -@subsection How Emacs Finds Your Init File - - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). - - However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are -currently pretending to be. The idea is that you should get your own -editor customizations even if you are running as the super user. - - More precisely, Emacs first determines which user's init file to use. -It gets your user name from the environment variables @env{LOGNAME} and -@env{USER}; if neither of those exists, it uses effective user-ID. -If that user name matches the real user-ID, then Emacs uses @env{HOME}; -otherwise, it looks up the home directory corresponding to that user -name in the system's data base of users. -@c LocalWords: backtab - -@node Init Non-ASCII -@subsection Non-@acronym{ASCII} Characters in Init Files -@cindex international characters in @file{.emacs} -@cindex non-@acronym{ASCII} characters in @file{.emacs} -@cindex non-@acronym{ASCII} keys, binding -@cindex rebinding non-@acronym{ASCII} keys - - Language and coding systems may cause problems if your init file -contains non-@acronym{ASCII} characters, such as accented letters, in -strings or key bindings. - - If you want to use non-@acronym{ASCII} characters in your init file, -you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on -the first line of the init file, and specify a coding system that -supports the character(s) in question. @xref{Recognize Coding}. This -is because the defaults for decoding non-@acronym{ASCII} text might -not yet be set up by the time Emacs reads those parts of your init -file which use such strings, possibly leading Emacs to decode those -strings incorrectly. You should then avoid adding Emacs Lisp code -that modifies the coding system in other ways, such as calls to -@code{set-language-environment}. - - To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init -Rebinding}). The string syntax cannot be used, since the -non-@acronym{ASCII} characters will be interpreted as meta keys. For -instance: - -@example -(global-set-key [?@var{char}] 'some-function) -@end example - -@noindent -Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - - @strong{Warning:} if you change the keyboard encoding, or change -between multibyte and unibyte mode, or anything that would alter which -code @kbd{C-q} would insert for that character, this key binding may -stop working. It is therefore advisable to use one and only one -coding system, for your init file as well as the files you edit. For -example, don't mix the @samp{latin-1} and @samp{latin-9} coding -systems. - -@ignore - arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 -@end ignore diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi deleted file mode 100644 index 5d800f9aaf5..00000000000 --- a/doc/emacs/dired-xtra.texi +++ /dev/null @@ -1,48 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Subdir Switches -@section Subdirectory Switches in Dired - -You can insert subdirectories with specified @code{ls} switches in -Dired buffers using @kbd{C-u i}. You can change the @code{ls} -switches of an already inserted subdirectory using @kbd{C-u l}. - -Dired preserves the switches if you revert the buffer. Deleting a -subdirectory forgets about its switches. - -Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) -to reinsert or delete subdirectories that were inserted with explicit -switches can bypass Dired's machinery for remembering (or forgetting) -switches. Deleting a subdirectory using @code{dired-undo} does not -forget its switches. When later reinserted using @kbd{i}, it will be -reinserted using its old switches. Using @code{dired-undo} to -reinsert a subdirectory that was deleted using the regular -Dired commands (not @code{dired-undo}) will originally insert it with -its old switches. Reverting the buffer, however, will relist it using -the buffer's default switches. If any of this yields problems, you -can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. - -Dired does not remember the @code{R} switch. Inserting a subdirectory -with switches that include the @code{R} switch is equivalent to -inserting each of its subdirectories using all remaining switches. -For instance, updating or killing a subdirectory that was inserted -with the @code{R} switch will not update or kill its subdirectories. - -The buffer's default switches do not affect subdirectories that were -inserted using explicitly specified switches. In particular, -commands such as @kbd{s} that change the buffer's switches do not -affect such subdirectories. (They do, however, affect subdirectories -without explicitly assigned switches.) - -You can make Dired forget about all subdirectory switches and relist -all subdirectories with the buffer's default switches using -@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. - -@ignore - arch-tag: e3865701-9179-4ffb-bc34-d321111c688d -@end ignore diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi deleted file mode 100644 index e58a0d72ff4..00000000000 --- a/doc/emacs/dired.texi +++ /dev/null @@ -1,1368 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Dired, Calendar/Diary, Rmail, Top -@chapter Dired, the Directory Editor -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex Dired -@cindex file management - - Dired makes an Emacs buffer containing a listing of a directory, and -optionally some of its subdirectories as well. You can use the normal -Emacs commands to move around in this buffer, and special Dired -commands to operate on the listed files. - - The Dired buffer is ``read-only,'' and inserting text in it is not -allowed. Ordinary printing characters such as @kbd{d} and @kbd{x} are -redefined for special Dired commands. Some Dired commands @dfn{mark} -or @dfn{flag} the @dfn{current file} (that is, the file on the current -line); other commands operate on the marked files or on the flagged -files. You first mark certain files in order to operate on all of -them with one command. - - The Dired-X package provides various extra features for Dired mode. -@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. - - You can also view a list of files in a directory with @kbd{C-x C-d} -(@code{list-directory}). Unlike Dired, this command does not allow -you to operate on the listed files. @xref{Directories}. - -@menu -* Enter: Dired Enter. How to invoke Dired. -* Navigation: Dired Navigation. Special motion commands in the Dired buffer. -* Deletion: Dired Deletion. Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Visit: Dired Visiting. Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running `diff' by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -@ifnottex -* Subdir Switches:: Subdirectory switches in Dired. -@end ifnottex -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Updating: Dired Updating. Discarding lines for files of no interest. -* Find: Dired and Find. Using `find' to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc: Misc Dired Features. Various other features. -@end menu - -@node Dired Enter -@section Entering Dired - -@findex dired -@kindex C-x d -@vindex dired-listing-switches - To invoke Dired, type @kbd{C-x d} (@code{dired}). This reads a -directory name using the minibuffer, and opens a @dfn{Dired buffer} -listing the files in that directory. You can also supply a wildcard -file name pattern as the minibuffer argument, in which case the Dired -buffer lists all files matching that pattern. The usual history and -completion commands can be used in the minibuffer; in particular, -@kbd{M-n} puts the name of the visited file (if any) in the minibuffer -(@pxref{Minibuffer History}). - - You can also invoke Dired by giving @kbd{C-x C-f} (@code{find-file}) -a directory name. - - The variable @code{dired-listing-switches} specifies the options to -give to @code{ls} for listing the directory; this string @emph{must} -contain @samp{-l}. If you use a numeric prefix argument with the -@code{dired} command, you can specify the @code{ls} switches with the -minibuffer before you enter the directory specification. No matter -how they are specified, the @code{ls} switches can include short -options (that is, single characters) requiring no arguments, and long -options (starting with @samp{--}) whose arguments are specified with -@samp{=}. - - On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; -see @ref{ls in Lisp}, for options and peculiarities of that emulation. - -@findex dired-other-window -@kindex C-x 4 d -@findex dired-other-frame -@kindex C-x 5 d - To display the Dired buffer in another window rather than in the -selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead -of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a -separate frame to display the Dired buffer. - -@node Dired Navigation -@section Navigation in the Dired Buffer - -@kindex C-n @r{(Dired)} -@kindex C-p @r{(Dired)} - All the usual Emacs cursor motion commands are available in Dired -buffers. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the -cursor at the beginning of the file name on the line, rather than at -the beginning of the line. - -@kindex SPC @r{(Dired)} - For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent -to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines -is so common in Dired that it deserves to be easy to type.) @key{DEL} -(move up and unflag) is also often useful simply for moving up -(@pxref{Dired Deletion}). - -@findex dired-goto-file -@kindex j @r{(Dired)} - @kbd{j} (@code{dired-goto-file}) prompts for a file name using the -minibuffer, and moves point to the line in the Dired buffer describing -that file. - -@cindex searching Dired buffers -@vindex dired-isearch-filenames - @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward -incremental search in the Dired buffer, looking for matches only -amongst the file names and ignoring the rest of the text in the -buffer. @kbd{M-s f M-C-s} (@code{dired-isearch-filenames-regexp}) -does the same, using a regular expression search. If you change the -variable @var{dired-isearch-filenames} to @code{t}, then the -usual search commands also limit themselves to the file names; for -instance, @kbd{C-s} behaves like @kbd{M-s f C-s}. If the value is -@code{dwim}, then search commands match the file names only when point -was on a file name initially. @xref{Search}, for information about -incremental search. - - Some additional navigation commands are available when the Dired -buffer includes several directories. @xref{Subdirectory Motion}. - -@node Dired Deletion -@section Deleting Files with Dired -@cindex flagging files (in Dired) -@cindex deleting files (in Dired) - - One of the most frequent uses of Dired is to first @dfn{flag} files for -deletion, then delete the files that were flagged. - -@table @kbd -@item d -Flag this file for deletion. -@item u -Remove deletion flag on this line. -@item @key{DEL} -Move point to previous line and remove the deletion flag on that line. -@item x -Delete the files that are flagged for deletion. -@end table - -@kindex d @r{(Dired)} -@findex dired-flag-file-deletion - You can flag a file for deletion by moving to the line describing -the file and typing @kbd{d} (@code{dired-flag-file-deletion}). The -deletion flag is visible as a @samp{D} at the beginning of the line. -This command moves point to the next line, so that repeated @kbd{d} -commands flag successive files. A numeric argument serves as a repeat -count. - -@kindex u @r{(Dired deletion)} -@kindex DEL @r{(Dired)} - The reason for flagging files for deletion, rather than deleting -files immediately, is to reduce the danger of deleting a file -accidentally. Until you direct Dired to delete the flagged files, you -can remove deletion flags using the commands @kbd{u} and @key{DEL}. -@kbd{u} (@code{dired-unmark}) works just like @kbd{d}, but removes -flags rather than making flags. @key{DEL} -(@code{dired-unmark-backward}) moves upward, removing flags; it is -like @kbd{u} with argument @minus{}1. - -@kindex x @r{(Dired)} -@findex dired-do-flagged-delete - To delete the flagged files, type @kbd{x} -(@code{dired-do-flagged-delete}). This command first displays a list -of all the file names flagged for deletion, and requests confirmation -with @kbd{yes}. If you confirm, Dired deletes the flagged files, then -deletes their lines from the text of the Dired buffer. The Dired -buffer, with somewhat fewer lines, remains selected. - - If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you -return immediately to Dired, with the deletion flags still present in -the buffer, and no files actually deleted. - -@cindex recursive deletion -@vindex dired-recursive-deletes - You can delete empty directories just like other files, but normally -Dired cannot delete directories that are nonempty. If the variable -@code{dired-recursive-deletes} is non-@code{nil}, then Dired can -delete nonempty directories including all their contents. That can -be somewhat risky. - -@vindex delete-by-moving-to-trash - On some systems, there is a facility called the ``Trash'' or -``Recycle Bin'', but Emacs does @emph{not} use it by default. Thus, -when you delete a file in Dired, it is gone forever. However, you can -tell Emacs to use the Trash for file deletion, by changing the -variable @code{delete-by-moving-to-trash} to @code{t}. @xref{Misc -File Ops}, for more information about the Trash. - -@node Flagging Many Files -@section Flagging Many Files at Once -@cindex flagging many files for deletion (in Dired) - - The @kbd{#}, @kbd{~}, @kbd{.}, @kbd{% &}, and @kbd{% d} commands -flag many files for deletion, based on their file names: - -@table @kbd -@item # -Flag all auto-save files (files whose names start and end with @samp{#}) -for deletion (@pxref{Auto Save}). - -@item ~ -Flag all backup files (files whose names end with @samp{~}) for deletion -(@pxref{Backup}). - -@item .@: @r{(Period)} -Flag excess numeric backup files for deletion. The oldest and newest -few backup files of any one file are exempt; the middle ones are -flagged. - -@item % & -Flag for deletion all files with certain kinds of names which suggest -you could easily create those files again. - -@item % d @var{regexp} @key{RET} -Flag for deletion all files whose names match the regular expression -@var{regexp}. -@end table - -@kindex # @r{(Dired)} -@findex dired-flag-auto-save-files -@cindex deleting auto-save files - @kbd{#} (@code{dired-flag-auto-save-files}) flags all files whose -names look like auto-save files---that is, files whose names begin and -end with @samp{#}. @xref{Auto Save}. - -@kindex ~ @r{(Dired)} -@findex dired-flag-backup-files - @kbd{~} (@code{dired-flag-backup-files}) flags all files whose names -say they are backup files---that is, files whose names end in -@samp{~}. @xref{Backup}. - -@kindex . @r{(Dired)} -@vindex dired-kept-versions -@findex dired-clean-directory - @kbd{.} (period, @code{dired-clean-directory}) flags just some of -the backup files for deletion: all but the oldest few and newest few -backups of any one file. Normally, the number of newest versions kept -for each file is given by the variable @code{dired-kept-versions} -(@strong{not} @code{kept-new-versions}; that applies only when -saving). The number of oldest versions to keep is given by the -variable @code{kept-old-versions}. - - Period with a positive numeric argument, as in @kbd{C-u 3 .}, -specifies the number of newest versions to keep, overriding -@code{dired-kept-versions}. A negative numeric argument overrides -@code{kept-old-versions}, using minus the value of the argument to -specify the number of oldest versions of each file to keep. - -@kindex % & @r{(Dired)} -@findex dired-flag-garbage-files -@vindex dired-garbage-files-regexp -@cindex deleting some backup files - @kbd{% &} (@code{dired-flag-garbage-files}) flags files whose names -match the regular expression specified by the variable -@code{dired-garbage-files-regexp}. By default, this matches certain -files produced by @TeX{}, @samp{.bak} files, and the @samp{.orig} and -@samp{.rej} files produced by @code{patch}. - -@findex dired-flag-files-regexp -@kindex % d @r{(Dired)} - @kbd{% d} flags all files whose names match a specified regular -expression (@code{dired-flag-files-regexp}). Only the non-directory -part of the file name is used in matching. You can use @samp{^} and -@samp{$} to anchor matches. You can exclude certain subdirectories -from marking by hiding them while you use @kbd{% d}. @xref{Hiding -Subdirectories}. - -@node Dired Visiting -@section Visiting Files in Dired - - There are several Dired commands for visiting or examining the files -listed in the Dired buffer. All of them apply to the current line's -file; if that file is really a directory, these commands invoke Dired on -that subdirectory (making a separate Dired buffer). - -@table @kbd -@item f -@kindex f @r{(Dired)} -@findex dired-find-file -Visit the file described on the current line, like typing @kbd{C-x C-f} -and supplying that file name (@code{dired-find-file}). @xref{Visiting}. - -@item @key{RET} -@itemx e -@kindex RET @r{(Dired)} -@kindex e @r{(Dired)} -Equivalent to @kbd{f}. - -@ignore @c This command seems too risky to document at all. -@item a -@kindex a @r{(Dired)} -@findex dired-find-alternate-file -Like @kbd{f}, but replaces the contents of the Dired buffer with -that of an alternate file or directory (@code{dired-find-alternate-file}). -@end ignore - -@item o -@kindex o @r{(Dired)} -@findex dired-find-file-other-window -Like @kbd{f}, but uses another window to display the file's buffer -(@code{dired-find-file-other-window}). The Dired buffer remains visible -in the first window. This is like using @kbd{C-x 4 C-f} to visit the -file. @xref{Windows}. - -@item C-o -@kindex C-o @r{(Dired)} -@findex dired-display-file -Visit the file described on the current line, and display the buffer in -another window, but do not select that window (@code{dired-display-file}). - -@item Mouse-1 -@itemx Mouse-2 -@findex dired-mouse-find-file-other-window -Visit the file named by the line you click on -(@code{dired-mouse-find-file-other-window}). This uses another window -to display the file, like the @kbd{o} command. - -@item v -@kindex v @r{(Dired)} -@findex dired-view-file -View the file described on the current line, using @kbd{M-x view-file} -(@code{dired-view-file}). Viewing a file with @code{view-file} is -like visiting it, but is slanted toward moving around in the file -conveniently and does not allow changing the file. @xref{Misc File -Ops, View File, Miscellaneous File Operations}. - -@item ^ -@kindex ^ @r{(Dired)} -@findex dired-up-directory -Visit the parent directory of the current directory -(@code{dired-up-directory}). This is equivalent to moving to the line -for @file{..} and typing @kbd{f} there. -@end table - -@node Marks vs Flags -@section Dired Marks vs. Flags - -@cindex marking many files (in Dired) - Instead of flagging a file with @samp{D}, you can @dfn{mark} the -file with some other character (usually @samp{*}). Most Dired -commands to operate on files use the files marked with @samp{*}. The -only command that operates on flagged files is @kbd{x}, which deletes -them. - - Here are some commands for marking with @samp{*}, for unmarking, and -for operating on marks. (@xref{Dired Deletion}, for commands to flag -and unflag files.) - -@table @kbd -@item m -@itemx * m -@kindex m @r{(Dired)} -@kindex * m @r{(Dired)} -@findex dired-mark -Mark the current file with @samp{*} (@code{dired-mark}). With a numeric -argument @var{n}, mark the next @var{n} files starting with the current -file. (If @var{n} is negative, mark the previous @minus{}@var{n} -files.) - -@item * * -@kindex * * @r{(Dired)} -@findex dired-mark-executables -@cindex marking executable files (in Dired) -Mark all executable files with @samp{*} -(@code{dired-mark-executables}). With a numeric argument, unmark all -those files. - -@item * @@ -@kindex * @@ @r{(Dired)} -@findex dired-mark-symlinks -@cindex marking symbolic links (in Dired) -Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). -With a numeric argument, unmark all those files. - -@item * / -@kindex * / @r{(Dired)} -@findex dired-mark-directories -@cindex marking subdirectories (in Dired) -Mark with @samp{*} all files which are directories, except for -@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric -argument, unmark all those files. - -@item * s -@kindex * s @r{(Dired)} -@findex dired-mark-subdir-files -Mark all the files in the current subdirectory, aside from @file{.} -and @file{..} (@code{dired-mark-subdir-files}). - -@item u -@itemx * u -@kindex u @r{(Dired)} -@kindex * u @r{(Dired)} -@findex dired-unmark -Remove any mark on this line (@code{dired-unmark}). - -@item @key{DEL} -@itemx * @key{DEL} -@kindex * DEL @r{(Dired)} -@findex dired-unmark-backward -@cindex unmarking files (in Dired) -Move point to previous line and remove any mark on that line -(@code{dired-unmark-backward}). - -@item * ! -@itemx U -@kindex * ! @r{(Dired)} -@kindex U @r{(Dired)} -@findex dired-unmark-all-marks -Remove all marks from all the files in this Dired buffer -(@code{dired-unmark-all-marks}). - -@item * ? @var{markchar} -@itemx M-@key{DEL} -@kindex * ? @r{(Dired)} -@kindex M-DEL @r{(Dired)} -@findex dired-unmark-all-files -Remove all marks that use the character @var{markchar} -(@code{dired-unmark-all-files}). The argument is a single -character---do not use @key{RET} to terminate it. See the description -of the @kbd{* c} command below, which lets you replace one mark -character with another. - -With a numeric argument, this command queries about each marked file, -asking whether to remove its mark. You can answer @kbd{y} meaning yes, -@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining -files without asking about them. - -@item * C-n -@itemx M-@} -@findex dired-next-marked-file -@kindex * C-n @r{(Dired)} -@kindex M-@} @r{(Dired)} -Move down to the next marked file (@code{dired-next-marked-file}) -A file is ``marked'' if it has any kind of mark. - -@item * C-p -@itemx M-@{ -@findex dired-prev-marked-file -@kindex * C-p @r{(Dired)} -@kindex M-@{ @r{(Dired)} -Move up to the previous marked file (@code{dired-prev-marked-file}) - -@item t -@itemx * t -@kindex t @r{(Dired)} -@kindex * t @r{(Dired)} -@findex dired-toggle-marks -@cindex toggling marks (in Dired) -Toggle all marks (@code{dired-toggle-marks}): files marked with @samp{*} -become unmarked, and unmarked files are marked with @samp{*}. Files -marked in any other way are not affected. - -@item * c @var{old-markchar} @var{new-markchar} -@kindex * c @r{(Dired)} -@findex dired-change-marks -Replace all marks that use the character @var{old-markchar} with marks -that use the character @var{new-markchar} (@code{dired-change-marks}). -This command is the primary way to create or use marks other than -@samp{*} or @samp{D}. The arguments are single characters---do not use -@key{RET} to terminate them. - -You can use almost any character as a mark character by means of this -command, to distinguish various classes of files. If @var{old-markchar} -is a space (@samp{ }), then the command operates on all unmarked files; -if @var{new-markchar} is a space, then the command unmarks the files it -acts on. - -To illustrate the power of this command, here is how to put @samp{D} -flags on all the files that have no marks, while unflagging all those -that already have @samp{D} flags: - -@example -* c D t * c SPC D * c t SPC -@end example - -This assumes that no files were already marked with @samp{t}. - -@item % m @var{regexp} @key{RET} -@itemx * % @var{regexp} @key{RET} -@findex dired-mark-files-regexp -@kindex % m @r{(Dired)} -@kindex * % @r{(Dired)} -Mark (with @samp{*}) all files whose names match the regular expression -@var{regexp} (@code{dired-mark-files-regexp}). This command is like -@kbd{% d}, except that it marks files with @samp{*} instead of flagging -with @samp{D}. - -Only the non-directory part of the file name is used in matching. Use -@samp{^} and @samp{$} to anchor matches. You can exclude -subdirectories by temporarily hiding them (@pxref{Hiding -Subdirectories}). - -@item % g @var{regexp} @key{RET} -@findex dired-mark-files-containing-regexp -@kindex % g @r{(Dired)} -@cindex finding files containing regexp matches (in Dired) -Mark (with @samp{*}) all files whose @emph{contents} contain a match for -the regular expression @var{regexp} -(@code{dired-mark-files-containing-regexp}). This command is like -@kbd{% m}, except that it searches the file contents instead of the file -name. - -@item C-x u -@itemx C-_ -@itemx C-/ -@kindex C-_ @r{(Dired)} -@findex dired-undo -Undo changes in the Dired buffer, such as adding or removing -marks (@code{dired-undo}). @emph{This command does not revert the -actual file operations, nor recover lost files!} It just undoes -changes in the buffer itself. - -In some cases, using this after commands that operate on files can -cause trouble. For example, after renaming one or more files, -@code{dired-undo} restores the original names in the Dired buffer, -which gets the Dired buffer out of sync with the actual contents of -the directory. -@end table - -@node Operating on Files -@section Operating on Files -@cindex operating on files in Dired - - This section describes the basic Dired commands to operate on one file -or several files. All of these commands are capital letters; all of -them use the minibuffer, either to read an argument or to ask for -confirmation, before they act. All of them let you specify the -files to manipulate in these ways: - -@itemize @bullet -@item -If you give the command a numeric prefix argument @var{n}, it operates -on the next @var{n} files, starting with the current file. (If @var{n} -is negative, the command operates on the @minus{}@var{n} files preceding -the current line.) - -@item -Otherwise, if some files are marked with @samp{*}, the command operates -on all those files. - -@item -Otherwise, the command operates on the current file only. -@end itemize - -@noindent -Certain other Dired commands, such as @kbd{!} and the @samp{%} -commands, use the same conventions to decide which files to work on. - -@vindex dired-dwim-target -@cindex two directories (in Dired) - Commands which ask for a destination directory, such as those which -copy and rename files or create links for them, try to guess the default -target directory for the operation. Normally, they suggest the Dired -buffer's default directory, but if the variable @code{dired-dwim-target} -is non-@code{nil}, and if there is another Dired buffer displayed in the -next window, that other buffer's directory is suggested instead. - - Here are the file-manipulating Dired commands that operate on files. - -@table @kbd -@findex dired-do-copy -@kindex C @r{(Dired)} -@cindex copying files (in Dired) -@item C @var{new} @key{RET} -Copy the specified files (@code{dired-do-copy}). The argument @var{new} -is the directory to copy into, or (if copying a single file) the new -name. This is like the shell command @code{cp}. - -@vindex dired-copy-preserve-time -If @code{dired-copy-preserve-time} is non-@code{nil}, then copying -with this command preserves the modification time of the old file in -the copy, like @samp{cp -p}. - -@vindex dired-recursive-copies -@cindex recursive copying -The variable @code{dired-recursive-copies} controls whether to copy -directories recursively (like @samp{cp -r}). The default is -@code{nil}, which means that directories cannot be copied. - -@item D -@findex dired-do-delete -@kindex D @r{(Dired)} -Delete the specified files (@code{dired-do-delete}). This is like the -shell command @code{rm}. - -Like the other commands in this section, this command operates on the -@emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} -(@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. - -@findex dired-do-rename -@kindex R @r{(Dired)} -@cindex renaming files (in Dired) -@cindex moving files (in Dired) -@item R @var{new} @key{RET} -Rename the specified files (@code{dired-do-rename}). If you rename a -single file, the argument @var{new} is the new name of the file. If -you rename several files, the argument @var{new} is the directory into -which to move the files (this is like the shell command @code{mv}). - -Dired automatically changes the visited file name of buffers associated -with renamed files so that they refer to the new names. - -@findex dired-do-hardlink -@kindex H @r{(Dired)} -@cindex hard links (in Dired) -@item H @var{new} @key{RET} -Make hard links to the specified files (@code{dired-do-hardlink}). -This is like the shell command @code{ln}. The argument @var{new} is -the directory to make the links in, or (if making just one link) the -name to give the link. - -@findex dired-do-symlink -@kindex S @r{(Dired)} -@cindex symbolic links (creation in Dired) -@item S @var{new} @key{RET} -Make symbolic links to the specified files (@code{dired-do-symlink}). -This is like @samp{ln -s}. The argument @var{new} is the directory to -make the links in, or (if making just one link) the name to give the -link. - -@findex dired-do-chmod -@kindex M @r{(Dired)} -@cindex changing file permissions (in Dired) -@item M @var{modespec} @key{RET} -Change the mode (also called ``permission bits'') of the specified files -(@code{dired-do-chmod}). This uses the @code{chmod} program, so -@var{modespec} can be any argument that @code{chmod} can handle. - -@findex dired-do-chgrp -@kindex G @r{(Dired)} -@cindex changing file group (in Dired) -@item G @var{newgroup} @key{RET} -Change the group of the specified files to @var{newgroup} -(@code{dired-do-chgrp}). - -@findex dired-do-chown -@kindex O @r{(Dired)} -@cindex changing file owner (in Dired) -@item O @var{newowner} @key{RET} -Change the owner of the specified files to @var{newowner} -(@code{dired-do-chown}). (On most systems, only the superuser can do -this.) - -@vindex dired-chown-program -The variable @code{dired-chown-program} specifies the name of the -program to use to do the work (different systems put @code{chown} in -different places). - -@findex dired-do-touch -@kindex T @r{(Dired)} -@cindex changing file time (in Dired) -@item T @var{timestamp} @key{RET} -Touch the specified files (@code{dired-do-touch}). This means -updating their modification times to the present time. This is like -the shell command @code{touch}. - -@findex dired-do-print -@kindex P @r{(Dired)} -@cindex printing files (in Dired) -@item P @var{command} @key{RET} -Print the specified files (@code{dired-do-print}). You must specify the -command to print them with, but the minibuffer starts out with a -suitable guess made using the variables @code{lpr-command} and -@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; -@pxref{Printing}). - -@findex dired-do-compress -@kindex Z @r{(Dired)} -@cindex compressing files (in Dired) -@item Z -Compress the specified files (@code{dired-do-compress}). If the file -appears to be a compressed file already, uncompress it instead. - -@findex dired-do-load -@kindex L @r{(Dired)} -@cindex loading several files (in Dired) -@item L -Load the specified Emacs Lisp files (@code{dired-do-load}). -@xref{Lisp Libraries}. - -@findex dired-do-byte-compile -@kindex B @r{(Dired)} -@cindex byte-compiling several files (in Dired) -@item B -Byte compile the specified Emacs Lisp files -(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte -Compilation, elisp, The Emacs Lisp Reference Manual}. - -@kindex A @r{(Dired)} -@findex dired-do-search -@cindex search multiple files (in Dired) -@item A @var{regexp} @key{RET} -Search all the specified files for the regular expression @var{regexp} -(@code{dired-do-search}). - -This command is a variant of @code{tags-search}. The search stops at -the first match it finds; use @kbd{M-,} to resume the search and find -the next match. @xref{Tags Search}. - -@kindex Q @r{(Dired)} -@findex dired-do-query-replace-regexp -@cindex search and replace in multiple files (in Dired) -@item Q @var{regexp} @key{RET} @var{to} @key{RET} -Perform @code{query-replace-regexp} on each of the specified files, -replacing matches for @var{regexp} with the string -@var{to} (@code{dired-do-query-replace-regexp}). - -This command is a variant of @code{tags-query-replace}. If you exit the -query replace loop, you can use @kbd{M-,} to resume the scan and replace -more matches. @xref{Tags Search}. -@end table - -@node Shell Commands in Dired -@section Shell Commands in Dired -@cindex shell commands, Dired - -@findex dired-do-shell-command -@kindex ! @r{(Dired)} -@kindex X @r{(Dired)} -The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a -shell command string in the minibuffer and runs that shell command on -one or more files. The files that the shell command operates on are -determined in the usual way for Dired commands (@pxref{Operating on -Files}). The command @kbd{X} is a synonym for @kbd{!}. - - The command @kbd{&} (@code{dired-do-async-shell-command}) does the -same, except that it runs the shell command asynchronously. You can -also do this with @kbd{!}, by appending a @samp{&} character to the -end of the shell command. - - For both @kbd{!} and @kbd{&}, the working directory for the shell -command is the top-level directory of the Dired buffer. - - If you tell @kbd{!} or @kbd{&} to operate on more than one file, the -shell command string determines how those files are passed to the -shell command: - -@itemize @bullet -@item -If you use @samp{*} surrounded by whitespace in the command string, -then the command runs just once, with the list of file names -substituted for the @samp{*}. The order of file names is the order of -appearance in the Dired buffer. - -Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire -list of file names, putting them into one tar file @file{foo.tar}. - -If you want to use @samp{*} as a shell wildcard with whitespace around -it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; -but since the @samp{*} is not surrounded by whitespace, Dired does not -treat it specially. - -@item -Otherwise, if the command string contains @samp{?} surrounded by -whitespace, Emacs runs the shell command once @emph{for each file}, -substituting the current file name for @samp{?} each time. You can -use @samp{?} more than once in the command; the same file name -replaces each occurrence. - -@item -If the command string contains neither @samp{*} nor @samp{?}, Emacs -runs the shell command once for each file, adding the file name is -added at the end. For example, @kbd{! uudecode @key{RET}} runs -@code{uudecode} on each file. -@end itemize - - To iterate over the file names in a more complicated fashion, use an -explicit shell loop. For example, here is how to uuencode each file, -making the output file name by appending @samp{.uu} to the input file -name: - -@example -for file in * ; do uuencode "$file" "$file" >"$file".uu; done -@end example - - The @kbd{!} and @kbd{&} commands do not attempt to update the Dired -buffer to show new or modified files, because they don't know what -files will be changed. Use the @kbd{g} command to update the Dired -buffer (@pxref{Dired Updating}). - - @xref{Single Shell}, for information about running shell commands -outside Dired. - -@node Transforming File Names -@section Transforming File Names in Dired - - This section describes Dired commands which alter file names in a -systematic way. Each command operates on some or all of the marked -files, using a new name made by transforming the existing name. - - Like the basic Dired file-manipulation commands (@pxref{Operating on -Files}), the commands described here operate either on the next -@var{n} files, or on all files marked with @samp{*}, or on the current -file. (To mark files, use the commands described in @ref{Marks vs -Flags}.) - - All of the commands described in this section work -@emph{interactively}: they ask you to confirm the operation for each -candidate file. Thus, you can select more files than you actually -need to operate on (e.g., with a regexp that matches many files), and -then filter the selected names by typing @kbd{y} or @kbd{n} when the -command prompts for confirmation. - -@table @kbd -@findex dired-upcase -@kindex % u @r{(Dired)} -@cindex upcase file names -@item % u -Rename each of the selected files to an upper-case name -(@code{dired-upcase}). If the old file names are @file{Foo} -and @file{bar}, the new names are @file{FOO} and @file{BAR}. - -@item % l -@findex dired-downcase -@kindex % l @r{(Dired)} -@cindex downcase file names -Rename each of the selected files to a lower-case name -(@code{dired-downcase}). If the old file names are @file{Foo} and -@file{bar}, the new names are @file{foo} and @file{bar}. - -@item % R @var{from} @key{RET} @var{to} @key{RET} -@kindex % R @r{(Dired)} -@findex dired-do-rename-regexp -@itemx % C @var{from} @key{RET} @var{to} @key{RET} -@kindex % C @r{(Dired)} -@findex dired-do-copy-regexp -@itemx % H @var{from} @key{RET} @var{to} @key{RET} -@kindex % H @r{(Dired)} -@findex dired-do-hardlink-regexp -@itemx % S @var{from} @key{RET} @var{to} @key{RET} -@kindex % S @r{(Dired)} -@findex dired-do-symlink-regexp -These four commands rename, copy, make hard links and make soft links, -in each case computing the new name by regular-expression substitution -from the name of the old file. -@end table - - The four regular-expression substitution commands effectively -perform a search-and-replace on the selected file names. They read -two arguments: a regular expression @var{from}, and a substitution -pattern @var{to}; they match each ``old'' file name against -@var{from}, and then replace the matching part with @var{to}. You can -use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to all or -part of what the pattern matched in the old file name, as in -@code{replace-regexp} (@pxref{Regexp Replace}). If the regular -expression matches more than once in a file name, only the first match -is replaced. - - For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each -selected file by prepending @samp{x-} to its name. The inverse of this, -removing @samp{x-} from the front of each file name, is also possible: -one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is -@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor -matches that should span the whole file name.) - - Normally, the replacement process does not consider the files' -directory names; it operates on the file name within the directory. If -you specify a numeric argument of zero, then replacement affects the -entire absolute file name including directory name. (A non-zero -argument specifies the number of files to operate on.) - - You may want to select the set of files to operate on using the same -regexp @var{from} that you will use to operate on them. To do this, -mark those files with @kbd{% m @var{from} @key{RET}}, then use the -same regular expression in the command to operate on the files. To -make this more convenient, the @kbd{%} commands to operate on files -use the last regular expression specified in any @kbd{%} command as a -default. - -@node Comparison in Dired -@section File Comparison with Dired -@cindex file comparison (in Dired) -@cindex compare files (in Dired) - - Here are two Dired commands that compare specified files using -@code{diff}. They show the output in a buffer using Diff mode -(@pxref{Comparing Files}). - -@table @kbd -@item = -@findex dired-diff -@kindex = @r{(Dired)} -Compare the current file (the file at point) with another file (the -file at the mark) using the @code{diff} program (@code{dired-diff}). -The file at the mark is the first argument of @code{diff}, and the -file at point is the second argument. This refers to the ordinary -Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} -(@code{set-mark-command}) to set the mark at the first file's line -(@pxref{Setting Mark}). - -@findex dired-backup-diff -@kindex M-= @r{(Dired)} -@item M-= -Compare the current file with its latest backup file -(@code{dired-backup-diff}). If the current file is itself a backup, -compare it with the file it is a backup of; this way, you can compare -a file with any one of its backups. - -The backup file is the first file given to @code{diff}. -@end table - -@node Subdirectories in Dired -@section Subdirectories in Dired -@cindex subdirectories in Dired -@cindex expanding subdirectories in Dired - - A Dired buffer displays just one directory in the normal case; -but you can optionally include its subdirectories as well. - - The simplest way to include multiple directories in one Dired buffer is -to specify the options @samp{-lR} for running @code{ls}. (If you give a -numeric argument when you run Dired, then you can specify these options -in the minibuffer.) That produces a recursive directory listing showing -all subdirectories at all levels. - - More often, you will want to show only specific subdirectories. You -can do this with the @kbd{i} command: - -@table @kbd -@findex dired-maybe-insert-subdir -@kindex i @r{(Dired)} -@item i -@cindex inserted subdirectory (Dired) -@cindex in-situ subdirectory (Dired) -Insert the contents of a subdirectory later in the buffer. -@end table - -Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line -that describes a file which is a directory. It inserts the contents of -that directory into the same Dired buffer, and moves there. Inserted -subdirectory contents follow the top-level directory of the Dired -buffer, just as they do in @samp{ls -lR} output. - -If the subdirectory's contents are already present in the buffer, the -@kbd{i} command just moves to it. - -In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u -C-@key{SPC}} takes you back to the old position in the buffer (the line -describing that subdirectory). You can also use @samp{^} to return -to the parent directory in the same Dired buffer. - -Use the @kbd{l} command (@code{dired-do-redisplay}) to update the -subdirectory's contents. Use @kbd{C-u k} on the subdirectory header -line to delete the subdirectory (@pxref{Dired Updating}). You can also -hide and show inserted subdirectories (@pxref{Hiding Subdirectories}). - -@ifnottex -@include dired-xtra.texi -@end ifnottex - -@node Subdirectory Motion -@section Moving Over Subdirectories - - When a Dired buffer lists subdirectories, you can use the page motion -commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories -(@pxref{Pages}). - -@cindex header line (Dired) -@cindex directory header lines - The following commands move across, up and down in the tree of -directories within one Dired buffer. They move to @dfn{directory header -lines}, which are the lines that give a directory's name, at the -beginning of the directory's contents. - -@table @kbd -@findex dired-next-subdir -@kindex C-M-n @r{(Dired)} -@item C-M-n -Go to next subdirectory header line, regardless of level -(@code{dired-next-subdir}). - -@findex dired-prev-subdir -@kindex C-M-p @r{(Dired)} -@item C-M-p -Go to previous subdirectory header line, regardless of level -(@code{dired-prev-subdir}). - -@findex dired-tree-up -@kindex C-M-u @r{(Dired)} -@item C-M-u -Go up to the parent directory's header line (@code{dired-tree-up}). - -@findex dired-tree-down -@kindex C-M-d @r{(Dired)} -@item C-M-d -Go down in the directory tree, to the first subdirectory's header line -(@code{dired-tree-down}). - -@findex dired-prev-dirline -@kindex < @r{(Dired)} -@item < -Move up to the previous directory-file line (@code{dired-prev-dirline}). -These lines are the ones that describe a directory as a file in its -parent directory. - -@findex dired-next-dirline -@kindex > @r{(Dired)} -@item > -Move down to the next directory-file line (@code{dired-prev-dirline}). -@end table - -@node Hiding Subdirectories -@section Hiding Subdirectories -@cindex hiding subdirectories (Dired) -@cindex showing hidden subdirectories (Dired) - - @dfn{Hiding} a subdirectory means to make it invisible, except for its -header line. - -@table @kbd -@item $ -@findex dired-hide-subdir -@kindex $ @r{(Dired)} -Hide or show the subdirectory that point is in, and move point to the -next subdirectory (@code{dired-hide-subdir}). This is a toggle. A -numeric argument serves as a repeat count. - -@item M-$ -@findex dired-hide-all -@kindex M-$ @r{(Dired)} -Hide all subdirectories in this Dired buffer, leaving only their header -lines (@code{dired-hide-all}). Or, if any subdirectory is currently -hidden, make all subdirectories visible again. You can use this command -to get an overview in very deep directory trees or to move quickly to -subdirectories far away. -@end table - - Ordinary Dired commands never consider files inside a hidden -subdirectory. For example, the commands to operate on marked files -ignore files in hidden directories even if they are marked. Thus you -can use hiding to temporarily exclude subdirectories from operations -without having to remove the Dired marks on files in those -subdirectories. - -@xref{Dired Updating}, for how to insert or delete a subdirectory listing. - -@node Dired Updating -@section Updating the Dired Buffer -@cindex updating Dired buffer -@cindex refreshing displayed files - - This section describes commands to update the Dired buffer to reflect -outside (non-Dired) changes in the directories and files, and to delete -part of the Dired buffer. - -@table @kbd -@item g -Update the entire contents of the Dired buffer (@code{revert-buffer}). - -@item l -Update the specified files (@code{dired-do-redisplay}). You specify the -files for @kbd{l} in the same way as for file operations. - -@item k -Delete the specified @emph{file lines}---not the files, just the lines -(@code{dired-do-kill-lines}). - -@item s -Toggle between alphabetical order and date/time order -(@code{dired-sort-toggle-or-edit}). - -@item C-u s @var{switches} @key{RET} -Refresh the Dired buffer using @var{switches} as -@code{dired-listing-switches}. -@end table - -@kindex g @r{(Dired)} -@findex revert-buffer @r{(Dired)} - Type @kbd{g} (@code{revert-buffer}) to update the contents of the -Dired buffer, based on changes in the files and directories listed. -This preserves all marks except for those on files that have vanished. -Hidden subdirectories are updated but remain hidden. - -@kindex l @r{(Dired)} -@findex dired-do-redisplay - To update only some of the files, type @kbd{l} -(@code{dired-do-redisplay}). Like the Dired file-operating commands, -this command operates on the next @var{n} files (or previous -@minus{}@var{n} files), or on the marked files if any, or on the -current file. Updating the files means reading their current status, -then updating their lines in the buffer to indicate that status. - - If you use @kbd{l} on a subdirectory header line, it updates the -contents of the corresponding subdirectory. - -@kindex k @r{(Dired)} -@findex dired-do-kill-lines - To delete the specified @emph{file lines} from the buffer---not -delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like -the file-operating commands, this command operates on the next @var{n} -files, or on the marked files if any; but it does not operate on the -current file as a last resort. - - If you use @kbd{k} with a numeric prefix argument to kill the line -for a file that is a directory, which you have inserted in the Dired -buffer as a subdirectory, it deletes that subdirectory from the buffer -as well. Typing @kbd{C-u k} on the header line for a subdirectory -also deletes the subdirectory from the Dired buffer. - - The @kbd{g} command brings back any individual lines that you have -killed in this way, but not subdirectories---you must use @kbd{i} to -reinsert a subdirectory. - -@cindex Dired sorting -@cindex sorting Dired buffer -@kindex s @r{(Dired)} -@findex dired-sort-toggle-or-edit - The files in a Dired buffers are normally listed in alphabetical order -by file names. Alternatively Dired can sort them by date/time. The -Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches -between these two sorting modes. The mode line in a Dired buffer -indicates which way it is currently sorted---by name, or by date. - - @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for -@code{dired-listing-switches}. - -@node Dired and Find -@section Dired and @code{find} -@cindex @code{find} and Dired - - You can select a set of files for display in a Dired buffer more -flexibly by using the @command{find} utility to choose the files. - -@findex find-name-dired - To search for files with names matching a wildcard pattern use -@kbd{M-x find-name-dired}. It reads arguments @var{directory} and -@var{pattern}, and chooses all the files in @var{directory} or its -subdirectories whose individual names match @var{pattern}. - - The files thus chosen are displayed in a Dired buffer, in which the -ordinary Dired commands are available. - -@findex find-grep-dired - If you want to test the contents of files, rather than their names, -use @kbd{M-x find-grep-dired}. This command reads two minibuffer -arguments, @var{directory} and @var{regexp}; it chooses all the files -in @var{directory} or its subdirectories that contain a match for -@var{regexp}. It works by running the programs @command{find} and -@command{grep}. See also @kbd{M-x grep-find}, in @ref{Grep -Searching}. Remember to write the regular expression for -@command{grep}, not for Emacs. (An alternative method of showing -files whose contents match a given regexp is the @kbd{% g -@var{regexp}} command, see @ref{Marks vs Flags}.) - -@findex find-dired - The most general command in this series is @kbd{M-x find-dired}, -which lets you specify any condition that @command{find} can test. It -takes two minibuffer arguments, @var{directory} and @var{find-args}; -it runs @command{find} in @var{directory}, passing @var{find-args} to -tell @command{find} what condition to test. To use this command, you -need to know how to use @command{find}. - -@vindex find-ls-option - The format of listing produced by these commands is controlled by the -variable @code{find-ls-option}, whose default value specifies using -options @samp{-ld} for @code{ls}. If your listings are corrupted, you -may need to change the value of this variable. - -@findex locate -@findex locate-with-filter -@cindex file database (locate) -@vindex locate-command - The command @kbd{M-x locate} provides a similar interface to the -@command{locate} program. @kbd{M-x locate-with-filter} is similar, but -keeps only files whose names match a given regular expression. - - These buffers don't work entirely like ordinary Dired buffers: file -operations work, but do not always automatically update the buffer. -Reverting the buffer with @kbd{g} deletes all inserted subdirectories, -and erases all flags and marks. - -@node Wdired -@section Editing the Dired Buffer - -@cindex wdired mode -@findex wdired-change-to-wdired-mode - Wdired is a special mode that allows you to perform file operations -by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands -for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} -(@code{dired-toggle-read-only}) while in a Dired buffer. -Alternatively, use the @samp{Immediate / Edit File Names} menu item. - -@findex wdired-finish-edit - While in Wdired mode, you can rename files by editing the file names -displayed in the Dired buffer. All the ordinary Emacs editing -commands, including rectangle operations and @code{query-replace}, are -available for this. Once you are done editing, type @kbd{C-c C-c} -(@code{wdired-finish-edit}). This applies your changes and switches -back to ordinary Dired mode. - - Apart from simply renaming files, you can move a file to another -directory by typing in the new file name (either absolute or -relative). To mark a file for deletion, delete the entire file name. -To change the target of a symbolic link, edit the link target name -which appears next to the link name. - - The rest of the text in the buffer, such as the file sizes and -modification dates, is marked read-only, so you can't edit it. -However, if you set @code{wdired-allow-to-change-permissions} to -@code{t}, you can edit the file permissions. For example, you can -change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file -world-writable. These changes also take effect when you type @kbd{C-c -C-c}. - -@node Image-Dired -@section Viewing Image Thumbnails in Dired -@cindex image-dired mode -@cindex image-dired - - Image-Dired is a facility for browsing image files. It provides viewing -the images either as thumbnails or in full size, either inside Emacs -or through an external viewer. - -@kindex C-t d @r{(Image-Dired)} -@findex image-dired-display-thumbs - To enter Image-Dired, mark the image files you want to look at in -the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} -(@code{image-dired-display-thumbs}). This creates and switches to a -buffer containing image-dired, corresponding to the marked files. - - You can also enter Image-Dired directly by typing @kbd{M-x -image-dired}. This prompts for a directory; specify one that has -image files. This creates thumbnails for all the images in that -directory, and displays them all in the ``thumbnail buffer.'' This -takes a long time if the directory contains many image files, and it -asks for confirmation if the number of image files exceeds -@code{image-dired-show-all-from-dir-max-files}. - - With point in the thumbnail buffer, you can type @kbd{RET} -(@code{image-dired-display-thumbnail-original-image}) to display a -sized version of it in another window. This sizes the image to fit -the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @kbd{SPC} -(@code{image-dired-display-next-thumbnail-original}) to advance and -display the next image. Typing @kbd{DEL} -(@code{image-dired-display-previous-thumbnail-original}) backs up to -the previous thumbnail and displays that instead. - -@vindex image-dired-external-viewer - To view and the image in its original size, either provide a prefix -argument (@kbd{C-u}) before pressing @kbd{RET}, or type -@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to -display the image in an external viewer. You must first configure -@code{image-dired-external-viewer}. - - You can delete images through Image-Dired also. Type @kbd{d} -(@code{image-dired-flag-thumb-original-file}) to flag the image file -for deletion in the Dired buffer. You can also delete the thumbnail -image from the thumbnail buffer with @kbd{C-d} -(@code{image-dired-delete-char}). - - More advanced features include @dfn{image tags}, which are metadata -used to categorize image files. The tags are stored in a plain text -file configured by @code{image-dired-db-file}. - - To tag image files, mark them in the dired buffer (you can also mark -files in Dired from the thumbnail buffer by typing @kbd{m}) and type -@kbd{C-t t} (@code{image-dired-tag-files}). This reads the tag name -in the minibuffer. To mark files having a certain tag, type @kbd{C-t f} -(@code{image-dired-mark-tagged-files}). After marking image files -with a certain tag, you can use @kbd{C-t d} to view them. - - You can also tag a file directly from the thumbnail buffer by typing -@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also -a special ``tag'' called ``comment'' for each file (it is not a tag in -the exact same sense as the other tags, it is handled slightly -different). That is used to enter a comment or description about the -image. You comment a file from the thumbnail buffer by typing -@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add -a comment from Dired (@code{image-dired-dired-comment-files}). - - Image-Dired also provides simple image manipulation. In the -thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees -anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This -rotation is lossless, and uses an external utility called JpegTRAN. - -@node Misc Dired Features -@section Other Dired Features - -@kindex + @r{(Dired)} -@findex dired-create-directory - The command @kbd{+} (@code{dired-create-directory}) reads a -directory name, and creates the directory if it does not already -exist. - -@cindex searching multiple files via Dired - The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a -``multi-file'' incremental search on the marked files. If a search -fails at the end of a file, typing @kbd{C-s} advances to the next -marked file and repeats the search; at the end of the last marked -file, the search wraps around to the first marked file. The command -@kbd{M-s a M-C-s} (@code{dired-do-isearch-regexp}) does the same with -a regular expression search. @xref{Repeat Isearch}, for information -about search repetition. - -@cindex Adding to the kill ring in Dired. -@kindex w @r{(Dired)} -@findex dired-copy-filename-as-kill - The command @kbd{w} (@code{dired-copy-filename-as-kill}) puts the -names of the marked (or next @var{n}) files into the kill ring, as if -you had killed them with @kbd{C-w}. The names are separated by a -space. - - With a zero prefix argument, this uses the absolute file name of -each marked file. With just @kbd{C-u} as the prefix argument, it uses -file names relative to the Dired buffer's default directory. (This -can still contain slashes if in a subdirectory.) As a special case, -if point is on a directory headerline, @kbd{w} gives you the absolute -name of that directory. Any prefix argument or marked files are -ignored in this case. - - The main purpose of this command is so that you can yank the file -names into arguments for other Emacs commands. It also displays what -it added to the kill ring, so you can use it to display the list of -currently marked files in the echo area. - -@findex dired-compare-directories - The command @kbd{M-x dired-compare-directories} is used to compare -the current Dired buffer with another directory. It marks all the files -that are ``different'' between the two directories. It puts these marks -in all Dired buffers where these files are listed, which of course includes -the current buffer. - - The default comparison method (used if you type @key{RET} at the -prompt) is to compare just the file names---each file name that does -not appear in the other directory is ``different.'' You can specify -more stringent comparisons by entering a Lisp expression, which can -refer to the variables @code{size1} and @code{size2}, the respective -file sizes; @code{mtime1} and @code{mtime2}, the last modification -times in seconds, as floating point numbers; and @code{fa1} and -@code{fa2}, the respective file attribute lists (as returned by the -function @code{file-attributes}). This expression is evaluated for -each pair of like-named files, and if the expression's value is -non-@code{nil}, those files are considered ``different.'' - - For instance, the sequence @code{M-x dired-compare-directories -@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this -directory than in the other, and marks files older in the other -directory than in this one. It also marks files with no counterpart, -in both directories, as always. - -@cindex drag and drop, Dired - On the X window system, Emacs supports the ``drag and drop'' -protocol. You can drag a file object from another program, and drop -it onto a Dired buffer; this either moves, copies, or creates a link -to the file in that directory. Precisely which action is taken is -determined by the originating program. Dragging files out of a Dired -buffer is currently not supported. - -@ignore - arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1 -@end ignore diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi deleted file mode 100644 index 56a50bc168d..00000000000 --- a/doc/emacs/display.texi +++ /dev/null @@ -1,1317 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Display, Search, Registers, Top -@chapter Controlling the Display - - Since only part of a large buffer fits in the window, Emacs tries to -show a part that is likely to be interesting. Display-control -commands and variables allow you to specify which part of the text you -want to see, and how to display it. - -@menu -* Scrolling:: Commands to move text up and down in a window. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Standard Faces:: Emacs' predefined faces. -* Temporary Face Changes:: Commands to temporarily modify the default text face -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly-spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. -@end menu - -@node Scrolling -@section Scrolling - - If a buffer contains text that is too large to fit entirely within a -window that is displaying the buffer, Emacs shows a contiguous portion of -the text. The portion shown always contains point. - -@cindex scrolling - @dfn{Scrolling} means moving text up or down in the window so that -different parts of the text are visible. Scrolling ``forward'' or -``up'' means that text moves up, and new text appears at the bottom. -Scrolling ``backward'' or ``down'' moves text down, and new text -appears at the top. - - Scrolling happens automatically if you move point past the bottom or -top of the window. You can also scroll explicitly with these -commands: - -@table @kbd -@item C-l -Scroll the selected window to center point vertically within it and -redisplay the screen (@code{recenter-top-bottom}). -@item C-v -@itemx @key{next} -@itemx @key{PageDown} -Scroll forward by nearly a full window (@code{scroll-up}). -@item M-v -@itemx @key{prior} -@itemx @key{PageUp} -Scroll backward (@code{scroll-down}). -@item C-M-l -Scroll heuristically to bring useful information onto the screen -(@code{reposition-window}). -@end table - -@kindex C-l -@findex recenter-top-bottom - The most basic scrolling command is @kbd{C-l} -(@code{recenter-top-bottom}). This @dfn{recenters} the selected -window, scrolling it so that the current screen line is exactly in the -center of the window, or as close to the center as possible. It also -clears the screen and redisplays all windows; this is useful in case -the screen becomes garbled for any reason (@pxref{Screen Garbled}). - - Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window -so that point is on the topmost screen line. Typing a third @kbd{C-l} -scrolls the window so that point is on the bottom-most screen line. -Each successive @kbd{C-l} cycles through these three screen positions. -(If you change the variable @code{scroll-margin} to a non-zero value -@var{n}, Emacs leaves @var{n} screen lines between point and the top -or bottom of the window. @xref{Auto Scrolling}.) - - You can also supply @kbd{C-l} with a prefix argument. With a plain -prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a -positive argument @var{n}, it scrolls to place point @var{n} lines -down from the top of the window. An argument of zero puts point on -the topmost line. A negative argument @var{-n} puts point @var{n} -lines from the bottom of the window. For example, @kbd{C-u - 1 C-l} -puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five -lines from the bottom. When given an argument, @kbd{C-l} does not -clear the screen or cycle through different screen positions. - -@kindex C-v -@kindex M-v -@kindex next -@kindex prior -@kindex PageDown -@kindex PageUp -@findex scroll-up -@findex scroll-down - To read the buffer a windowful at a time, use @kbd{C-v} -(@code{scroll-up}). This scrolls forward by nearly the whole window -height. The effect is to take the two lines at the bottom of the -window and put them at the top, followed by lines that were not -previously visible. If point was in the text that scrolled off the -top, it ends up at the new top of the window. - - @kbd{M-v} (@code{scroll-down}) scrolls backward in a similar way. - -@vindex next-screen-context-lines - The variable @code{next-screen-context-lines} controls the number of -lines of overlap left by @kbd{C-v} or @kbd{M-v}; by default, it is 2. -The function keys @key{next} and @key{prior}, or @key{PageDown} and -@key{PageUp}, are equivalent to @kbd{C-v} and @kbd{M-v} respectively. - - You can supply @kbd{C-v} or @kbd{M-v} with a numeric prefix argument -@var{n}. This scrolls the window by @var{n} lines, while attempting -to leave point unchanged (so that the text and point move up or down -together). @kbd{C-v} with a negative argument is like @kbd{M-v} and -vice versa. - - The names of scroll commands are based on the direction that the -text moves in the window. Thus, the command to scroll forward is -called @code{scroll-up} because it moves the text upward on the -screen. The keys @key{PageUp} and @key{PageDown} derive their names -and customary meanings from a different convention that developed -elsewhere; hence the strange result that @key{PageDown} runs -@code{scroll-up}. - -@vindex scroll-preserve-screen-position - Some users like the full-screen scroll commands to keep point at the -same screen position. To enable this behavior, set the variable -@code{scroll-preserve-screen-position} to a non-@code{nil} value. -Then, whenever a command scrolls the text around point offscreen (or -within @code{scroll-margin} lines of the edge), Emacs moves point to -keep it at the same vertical and horizontal position within the -window. This mode is convenient for browsing through a file by -scrolling by screenfuls; if you come back to the screen where you -started, point goes back to the line where it started. - -@kindex C-M-l -@findex reposition-window - The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current -window heuristically in a way designed to get useful information onto -the screen. For example, in a Lisp file, this command tries to get the -entire current defun onto the screen if possible. - -@node Auto Scrolling -@section Automatic Scrolling - - Emacs performs @dfn{automatic scrolling} when point moves out of the -visible portion of the text. - -@vindex scroll-conservatively - Normally, this centers point vertically within the window. However, -if you set @code{scroll-conservatively} to a small number @var{n}, -then if you move point just a little off the screen (less than @var{n} -lines), Emacs scrolls the text just far enough to bring point back on -screen. By default, @code{scroll-conservatively} is@tie{}0. - -@cindex aggressive scrolling -@vindex scroll-up-aggressively -@vindex scroll-down-aggressively - When the window does scroll by a longer distance, you can control -how aggressively it scrolls by setting the variables -@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. -The value of @code{scroll-up-aggressively} should be either -@code{nil}, or a fraction @var{f} between 0 and 1. A fraction -specifies where on the screen to put point when scrolling upward: when -a window scrolls up because point is above the window start, the new -start position is chosen to put point @var{f} parts of the window -height from the top. Thus, larger @var{f} means more aggressive -scrolling. The default value, @code{nil}, is equivalent to 0.5. - - Likewise, @code{scroll-down-aggressively} is used for scrolling -down. The value specifies how far point should be placed from the -bottom of the window; thus, as with @code{scroll-up-aggressively}, a -larger value is more aggressive. - -@vindex scroll-margin - The variable @code{scroll-margin} restricts how close point can come -to the top or bottom of a window. Its value is a number of screen -lines; if point comes within that many lines of the top or bottom of -the window, Emacs performs automatic scrolling. By default, -@code{scroll-margin} is 0. - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - -@vindex auto-hscroll-mode - @dfn{Horizontal scrolling} means shifting all the lines sideways -within a window, so that some of the text near the left margin is not -displayed. When the text in a window is scrolled horizontally, text -lines are truncated rather than continued (@pxref{Line Truncation}). -If a window shows truncated lines, Emacs performs automatic horizontal -scrolling whenever point moves off the left or right edge of the -screen. To disable automatic horizontal scrolling, set the variable -@code{auto-hscroll-mode} to @code{nil}. - -@vindex hscroll-margin - The variable @code{hscroll-margin} controls how close point can get -to the window's edges before automatic scrolling occurs. It -is measured in columns. If the value is 5, then moving point within 5 -columns of an edge causes horizontal scrolling away from that edge. - -@vindex hscroll-step - The variable @code{hscroll-step} determines how many columns to -scroll the window when point gets too close to the edge. Zero, the -default value, means to center point horizontally within the window. -A positive integer value specifies the number of columns to scroll by. -A floating-point number specifies the fraction of the window's width -to scroll by. - - You can also perform explicit horizontal scrolling with the -following commands: - -@table @kbd -@item C-x < -Scroll text in current window to the left (@code{scroll-left}). -@item C-x > -Scroll to the right (@code{scroll-right}). -@end table - -@kindex C-x < -@kindex C-x > -@findex scroll-left -@findex scroll-right - @kbd{C-x <} (@code{scroll-left}) scrolls the selected window to the -left by the full width of the window, less two columns. (In other -words, the text in the window moves left relative to the window.) -With a numeric argument @var{n}, it scrolls by @var{n} columns. - - @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. -The window cannot be scrolled any farther to the right once it is -displayed normally, with each line starting at the window's left -margin; attempting to do so has no effect. This means that you don't -have to calculate the argument precisely for @w{@kbd{C-x >}}; any -sufficiently large argument will restore the normal display. - - If you use those commands to scroll a window horizontally, that sets -a lower bound for automatic horizontal scrolling. Automatic scrolling -will continue to scroll the window, but never farther to the right -than the amount you previously set by @code{scroll-left}. - -@node Follow Mode -@section Follow Mode -@cindex Follow mode -@cindex mode, Follow -@findex follow-mode -@cindex windows, synchronizing -@cindex synchronizing windows - - @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window.'' -To use Follow mode, go to a frame with just one window, split it into -two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x -follow-mode}. From then on, you can edit the buffer in either of the -two windows, or scroll either one; the other window follows it. - - In Follow mode, if you move point outside the portion visible in one -window and into the portion visible in the other window, that selects -the other window---again, treating the two as if they were parts of -one large window. - - To turn off Follow mode, type @kbd{M-x follow-mode} a second time. - -@node Faces -@section Faces: Controlling Text Display Style -@cindex faces - - Emacs can display text in several different styles, which are called -@dfn{faces}. Each face can specify various @dfn{face attributes}, -such as the font, height, weight and slant, the foreground and -background color, and underlining or overlining. A face does not have -to specify all of these attributes; often it inherits most of them -from another face. - - On a text-only terminal, not all face attributes are meaningful. -Some text-only terminals support inverse video, bold, and underline -attributes; some support colors. Text-only terminals generally do not -support changing the height, width or font. - - Most major modes assign faces to the text automatically through the -work of Font Lock mode. @xref{Font Lock}, for more information about -Font Lock mode and syntactic highlighting. You can print the current -buffer with the highlighting that appears on your screen using the -command @code{ps-print-buffer-with-faces}. @xref{PostScript}. - - Enriched mode, the mode for editing formatted text, provides -commands and menus for specifying faces for text in the buffer. -@xref{Format Faces}. - -@cindex face colors, setting - To alter the appearance of a face, use the customization buffer. -@xref{Face Customization}. You can also use X resources to specify -attributes of any particular face (@pxref{Resources}). When -displaying a character, any attribute that isn't specified by its face -is taken from the @code{default} face, whose attributes reflect the -default settings of the frame itself. - -@findex set-face-foreground -@findex set-face-background - You can also change the foreground and background colors of a -specific face with @kbd{M-x set-face-foreground} and @kbd{M-x -set-face-background}. These commands prompt in the minibuffer for a -face name and a color name, with completion, and then set that face to -use the specified color. @xref{Face Customization}, for information -about color names. These commands affect the face colors on all -frames, both existing and those to be created in the future. These -changes do not, however, persist for future Emacs sessions; to make -lasting changes, use the customization buffer (@pxref{Face -Customization}). - - You can also set foreground and background colors for the current -frame only; see @ref{Frame Parameters}. - - Emacs can display variable-width fonts, but some of the Emacs -commands that calculate width and indentation do not know how to -calculate variable widths. This can sometimes lead to incorrect -results when you use variable-width fonts. In particular, indentation -commands can give inconsistent results, so we recommend you avoid -variable-width fonts, especially for editing program source code. - -@node Standard Faces -@section Standard Faces - -@findex list-faces-display - To see what faces are currently defined, and what they look like, -type @kbd{M-x list-faces-display}. It's possible for a given face to -look different in different frames; this command shows the appearance -in the frame in which you type it. With a prefix argument, this -prompts for a regular expression, and displays only faces with names -matching that regular expression. - - Here are the standard faces for specifying text appearance. You can -apply them to specific text when you want the effects they produce. - -@table @code -@item default -This face is used for ordinary text that doesn't specify any face. -@item bold -This face uses a bold variant of the default font. -@item italic -This face uses an italic variant of the default font. -@item bold-italic -This face uses a bold italic variant of the default font. -@item underline -This face underlines text. -@item fixed-pitch -This face forces use of a fixed-width font. It's reasonable to -customize this face to use a different fixed-width font, if you like, -but you should not make it a variable-width font. -@item variable-pitch -This face forces use of a variable-width font. -@item shadow -This face is used for making the text less noticeable than the surrounding -ordinary text. Usually this can be achieved by using shades of gray in -contrast with either black or white default foreground color. -@end table - - Here's an incomplete list of faces used to highlight parts of the -text temporarily for specific purposes. (Many other modes define -their own faces for this purpose.) - -@table @code -@item highlight -This face is used for highlighting portions of text, in various modes. -For example, mouse-sensitive text is highlighted using this face. -@item isearch -This face is used for highlighting the current Isearch match -(@pxref{Incremental Search}). -@item query-replace -This face is used for highlighting the current Query Replace match -(@pxref{Replace}). -@item lazy-highlight -This face is used for lazy highlighting of Isearch and Query Replace -matches other than the current one. -@item region -This face is used for displaying a selected region (@pxref{Mark}). -@item secondary-selection -This face is used for displaying a secondary X selection (@pxref{Secondary -Selection}). -@item trailing-whitespace -The face for highlighting excess spaces and tabs at the end of a line -when @code{show-trailing-whitespace} is non-@code{nil}; see -@ref{Useless Whitespace}. -@item nobreak-space -The face for displaying the character ``nobreak space.'' -@item escape-glyph -The face for highlighting the @samp{\} or @samp{^} that indicates -a control character. It's also used when @samp{\} indicates a -nobreak space or nobreak (soft) hyphen. -@end table - - These faces control the appearance of parts of the Emacs frame. -They exist as faces to provide a consistent way to customize the -appearance of these parts of the frame. - -@table @code -@item mode-line -This face is used for the mode line of the currently selected window, -and for menu bars when toolkit menus are not used. By default, it's -drawn with shadows for a ``raised'' effect on graphical displays, and -drawn as the inverse of the default face on non-windowed terminals. -@item mode-line-inactive -Like @code{mode-line}, but used for mode lines of the windows other -than the selected one (if @code{mode-line-in-non-selected-windows} is -non-@code{nil}). This face inherits from @code{mode-line}, so changes -in that face affect mode lines in all windows. -@item mode-line-highlight -Like @code{highlight}, but used for portions of text on mode lines. -@item mode-line-buffer-id -This face is used for buffer identification parts in the mode line. -@item header-line -Similar to @code{mode-line} for a window's header line, which appears -at the top of a window just as the mode line appears at the bottom. -Most windows do not have a header line---only some special modes, such -Info mode, create one. -@item vertical-border -This face is used for the vertical divider between windows. -By default this face inherits from the @code{mode-line-inactive} face -on character terminals. On graphical displays the foreground color of -this face is used for the vertical line between windows without -scrollbars. -@item minibuffer-prompt -@cindex @code{minibuffer-prompt} face -@vindex minibuffer-prompt-properties -This face is used for the prompt strings displayed in the minibuffer. -By default, Emacs automatically adds this face to the value of -@code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. (This variable takes -effect when you enter the minibuffer.) -@item fringe -@cindex @code{fringe} face -The face for the fringes to the left and right of windows on graphic -displays. (The fringes are the narrow portions of the Emacs frame -between the text area and the window's right and left borders.) -@xref{Fringes}. -@item scroll-bar -This face determines the visual appearance of the scroll bar. -@xref{Scroll Bars}. -@item border -This face determines the color of the frame border. -@item cursor -This face determines the color of the cursor. -@item mouse -This face determines the color of the mouse pointer. -@item tool-bar -This face determines the color of tool bar icons. @xref{Tool Bars}. -@item tooltip -This face is used for tooltips. @xref{Tooltips}. -@item menu -@cindex menu bar appearance -@cindex @code{menu} face, no effect if customized -@cindex customization of @code{menu} face -This face determines the colors and font of Emacs's menus. @xref{Menu -Bars}. This has no effect in Emacs built with GTK and in the -MS-Windows/Mac ports; you need to use system-wide styles and options -to change the appearance of GTK, Windows, or Mac menus. Setting the -font of LessTif/Motif menus is currently not supported; attempts to -set the font are ignored in this case. -@end table - -@node Temporary Face Changes -@section Temporary Face Changes - -The following commands change the default face within a buffer. - -@cindex adjust buffer face height -@findex text-scale-adjust -@kindex C-x C-+ -@kindex C-x C-- -@kindex C-x C-= -@kindex C-x C-0 - To increase the height of the default face in the current buffer, -type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x -C--}. To restore the default (global) face height, type @kbd{C-x -C-0}. These keys are all bound to the same command, -@code{text-scale-adjust}, which looks at the last key typed to -determine which action to take. - - The final key of these commands may be repeated without the leading -@kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face -height by three steps. Each step scales the height of the default -face by the value of the variable @code{text-scale-mode-step}. As a -special case, an argument of 0 removes any scaling currently active. - -@cindex increase buffer face height -@findex text-scale-increase -@cindex decrease buffer face height -@findex text-scale-decrease - The commands @code{text-scale-increase} and -@code{text-scale-decrease} increase or decrease the height of the -default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. -You may find it convenient to bind to these commands, rather than -@code{text-scale-adjust}. - -@findex text-scale-mode - The above commands automatically enable or disable the minor mode -@code{text-scale-mode}, depending on whether the current font scaling -is other than 1 or not. - -@cindex variable pitch mode -@findex variable-pitch-mode - To temporarily change the face in the current buffer to a -variable-pitch (``proportional'') font, use the command @kbd{M-x -variable-pitch-mode} to enable or disable the Variable Pitch minor -mode. - -@node Font Lock -@section Font Lock mode -@cindex Font Lock mode -@cindex mode, Font Lock -@cindex syntax highlighting and coloring - - Font Lock mode is a minor mode, always local to a particular buffer, -which highlights (or ``fontifies'') the buffer contents according to -the syntax of the text you are editing. It can recognize comments and -strings in most programming languages; in several languages, it can -also recognize and properly highlight various other important -constructs, such as names of functions being defined or reserved -keywords. Some special modes, such as Occur mode and Info mode, have -completely specialized ways of assigning fonts for Font Lock mode. - -@findex font-lock-mode - Font Lock mode is turned on by default in all modes which support it. -You can toggle font-lock for each buffer with the command @kbd{M-x -font-lock-mode}. Using a positive argument unconditionally turns Font -Lock mode on, and a negative or zero argument turns it off. - -@findex global-font-lock-mode -@vindex global-font-lock-mode - If you do not wish Font Lock mode to be turned on by default, -customize the variable @code{global-font-lock-mode} using the Customize -interface (@pxref{Easy Customization}), or use the function -@code{global-font-lock-mode} in your @file{.emacs} file, like this: - -@example -(global-font-lock-mode 0) -@end example - -@noindent -This variable, like all the variables that control Font Lock mode, -take effect whenever fontification is done; that is, potentially at -any time. - -@findex turn-on-font-lock - If you have disabled Global Font Lock mode, you can still enable Font -Lock for specific major modes by adding the function -@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For -example, to enable Font Lock mode for editing C files, you can do this: - -@example -(add-hook 'c-mode-hook 'turn-on-font-lock) -@end example - - Font Lock mode uses several specifically named faces to do its job, -including @code{font-lock-string-face}, @code{font-lock-comment-face}, -and others. The easiest way to find them all is to use @kbd{M-x -customize-group @key{RET} font-lock-faces @key{RET}}. You can then -use that customization buffer to customize the appearance of these -faces. @xref{Face Customization}. - -@vindex font-lock-maximum-decoration - The variable @code{font-lock-maximum-decoration} specifies the -preferred level of fontification, for modes that provide multiple -levels. Level 1 is the least amount of fontification; some modes -support levels as high as 3. The normal default is ``as high as -possible.'' You can specify an integer, which applies to all modes, or -you can specify different numbers for particular major modes; for -example, to use level 1 for C/C++ modes, and the default level -otherwise, use this: - -@example -(setq font-lock-maximum-decoration - '((c-mode . 1) (c++-mode . 1))) -@end example - -@vindex font-lock-maximum-size - Fontification can be too slow for large buffers, so you can suppress -it for buffers above a certain size. The variable -@code{font-lock-maximum-size} specifies a buffer size, beyond which -buffer fontification is suppressed. - -@c @w is used below to prevent a bad page-break. -@vindex font-lock-beginning-of-syntax-function -@cindex incorrect fontification -@cindex parenthesis in column zero and fontification -@cindex brace in column zero and fontification - Comment and string fontification (or ``syntactic'' fontification) -relies on analysis of the syntactic structure of the buffer text. For -the sake of speed, some modes, including Lisp mode, rely on a special -convention: an open-parenthesis or open-brace in the leftmost column -always defines the @w{beginning} of a defun, and is thus always -outside any string or comment. (@xref{Left Margin Paren}.) If you -don't follow this convention, Font Lock mode can misfontify the text -that follows an open-parenthesis or open-brace in the leftmost column -that is inside a string or comment. - -@cindex slow display during scrolling - The variable @code{font-lock-beginning-of-syntax-function} (always -buffer-local) specifies how Font Lock mode can find a position -guaranteed to be outside any comment or string. In modes which use the -leftmost column parenthesis convention, the default value of the variable -is @code{beginning-of-defun}---that tells Font Lock mode to use the -convention. If you set this variable to @code{nil}, Font Lock no longer -relies on the convention. This avoids incorrect results, but the price -is that, in some cases, fontification for a changed text must rescan -buffer text from the beginning of the buffer. This can considerably -slow down redisplay while scrolling, particularly if you are close to -the end of a large buffer. - -@findex font-lock-add-keywords - Font Lock highlighting patterns already exist for many modes, but you -may want to fontify additional patterns. You can use the function -@code{font-lock-add-keywords}, to add your own highlighting patterns for -a particular mode. For example, to highlight @samp{FIXME:} words in C -comments, use this: - -@example -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))))) -@end example - -@findex font-lock-remove-keywords - To remove keywords from the font-lock highlighting patterns, use the -function @code{font-lock-remove-keywords}. @xref{Search-based -Fontification,,, elisp, The Emacs Lisp Reference Manual}. - -@cindex just-in-time (JIT) font-lock -@cindex background syntax highlighting - Fontifying large buffers can take a long time. To avoid large -delays when a file is visited, Emacs fontifies only the visible -portion of a buffer. As you scroll through the buffer, each portion -that becomes visible is fontified as soon as it is displayed; this -type of Font Lock is called @dfn{Just-In-Time} (or @dfn{JIT}) Lock. -You can control how JIT Lock behaves, including telling it to perform -fontification while idle, by customizing variables in the -customization group @samp{jit-lock}. @xref{Specific Customization}. - -@node Highlight Interactively -@section Interactive Highlighting -@cindex highlighting by matching -@cindex interactive highlighting -@cindex Highlight Changes mode - -@findex highlight-changes-mode -Highlight Changes mode is a minor mode that @dfn{highlights} the parts -of the buffer were changed most recently, by giving that text a -different face. To enable or disable Highlight Changes mode, use -@kbd{M-x highlight-changes-mode}. - -@cindex Hi Lock mode -@findex hi-lock-mode - Hi Lock mode is a minor mode that highlights text that matches -regular expressions you specify. For example, you can use it to -highlight all the references to a certain variable in a program source -file, highlight certain parts in a voluminous output of some program, -or highlight certain names in an article. To enable or disable Hi -Lock mode, use the command @kbd{M-x hi-lock-mode}. To enable Hi Lock -mode for all buffers, use @kbd{M-x global-hi-lock-mode} or place -@code{(global-hi-lock-mode 1)} in your @file{.emacs} file. - - Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except -that you specify explicitly the regular expressions to highlight. You -control them with these commands: - -@table @kbd -@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w h -@findex highlight-regexp -Highlight text that matches @var{regexp} using face @var{face} -(@code{highlight-regexp}). The highlighting will remain as long as -the buffer is loaded. For example, to highlight all occurrences of -the word ``whim'' using the default face (a yellow background) -@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for -highlighting, Hi Lock provides several of its own and these are -pre-loaded into a history list. While being prompted for a face use -@kbd{M-p} and @kbd{M-n} to cycle through them. - -You can use this command multiple times, specifying various regular -expressions to highlight in different ways. - -@item C-x w r @var{regexp} @key{RET} -@kindex C-x w r -@findex unhighlight-regexp -Unhighlight @var{regexp} (@code{unhighlight-regexp}). - -If you invoke this from the menu, you select the expression to -unhighlight from a list. If you invoke this from the keyboard, you -use the minibuffer. It will show the most recently added regular -expression; use @kbd{M-p} to show the next older expression and -@kbd{M-n} to select the next newer expression. (You can also type the -expression by hand, with completion.) When the expression you want to -unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit -the minibuffer and unhighlight it. - -@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} -@kindex C-x w l -@findex highlight-lines-matching-regexp -@cindex lines, highlighting -@cindex highlighting lines of text -Highlight entire lines containing a match for @var{regexp}, using face -@var{face} (@code{highlight-lines-matching-regexp}). - -@item C-x w b -@kindex C-x w b -@findex hi-lock-write-interactive-patterns -Insert all the current highlighting regexp/face pairs into the buffer -at point, with comment delimiters to prevent them from changing your -program. (This key binding runs the -@code{hi-lock-write-interactive-patterns} command.) - -These patterns are extracted from the comments, if appropriate, if you -invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while -Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). - -@item C-x w i -@kindex C-x w i -@findex hi-lock-find-patterns -Extract regexp/face pairs from comments in the current buffer -(@code{hi-lock-find-patterns}). Thus, you can enter patterns -interactively with @code{highlight-regexp}, store them into the file -with @code{hi-lock-write-interactive-patterns}, edit them (perhaps -including different faces for different parenthesized parts of the -match), and finally use this command (@code{hi-lock-find-patterns}) to -have Hi Lock highlight the edited patterns. - -@vindex hi-lock-file-patterns-policy -The variable @code{hi-lock-file-patterns-policy} controls whether Hi -Lock mode should automatically extract and highlight patterns found in -a file when it is visited. Its value can be @code{nil} (never -highlight), @code{t} (highlight the patterns), @code{ask} (query the -user), or a function. If it is a function, -@code{hi-lock-find-patterns} calls it with the patterns as argument; -if the function returns non-@code{nil}, the patterns are used. The -default is @code{nil}. Note that patterns are always highlighted if -you call @code{hi-lock-find-patterns} directly, regardless of the -value of this variable. - -@vindex hi-lock-exclude-modes -Also, @code{hi-lock-find-patterns} does nothing if the current major -mode's symbol is a member of the list @code{hi-lock-exclude-modes}. -@end table - -@node Fringes -@section Window Fringes -@cindex fringes - - On a graphical display, each Emacs window normally has narrow -@dfn{fringes} on the left and right edges. The fringes are used to -display symbols that provide information about the text in the window. - - The most common use of the fringes is to indicate a continuation -line, when one line of text is split into multiple lines on the -screen. The left fringe shows a curving arrow for each screen line -except the first, indicating that ``this is not the real beginning.'' -The right fringe shows a curving arrow for each screen line except the -last, indicating that ``this is not the real end.'' - - The fringes indicate line truncation with short horizontal arrows -meaning ``there's more text on this line which is scrolled -horizontally out of view;'' clicking the mouse on one of the arrows -scrolls the display horizontally in the direction of the arrow. The -fringes can also indicate other things, such as empty lines, or where a -program you are debugging is executing (@pxref{Debuggers}). - -@findex set-fringe-style -@findex fringe-mode - You can enable and disable the fringes for all frames using -@kbd{M-x fringe-mode}. To enable and disable the fringes -for the selected frame, use @kbd{M-x set-fringe-style}. - -@node Displaying Boundaries -@section Displaying Boundaries - -@vindex indicate-buffer-boundaries - On a graphical display, Emacs can indicate the buffer boundaries in -the fringes. It indicates the first line and the last line with -angle images in the fringes. This can be combined with up and down -arrow images which say whether it is possible to scroll the window up -and down. - - The buffer-local variable @code{indicate-buffer-boundaries} controls -how the buffer boundaries and window scrolling is indicated in the -fringes. If the value is @code{left} or @code{right}, both angle and -arrow bitmaps are displayed in the left or right fringe, respectively. - - If value is an alist, each element @code{(@var{indicator} . -@var{position})} specifies the position of one of the indicators. -The @var{indicator} must be one of @code{top}, @code{bottom}, -@code{up}, @code{down}, or @code{t} which specifies the default -position for the indicators not present in the alist. -The @var{position} is one of @code{left}, @code{right}, or @code{nil} -which specifies not to show this indicator. - - For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, the bottom angle bitmap in right fringe, and -both arrow bitmaps in right fringe. To show just the angle bitmaps in -the left fringe, but no arrow bitmaps, use @code{((top . left) -(bottom . left))}. - -@vindex default-indicate-buffer-boundaries - The value of the variable @code{default-indicate-buffer-boundaries} -is the default value for @code{indicate-buffer-boundaries} in buffers -that do not override it. - -@node Useless Whitespace -@section Useless Whitespace - -@cindex trailing whitespace -@cindex whitespace, trailing -@vindex show-trailing-whitespace - It is easy to leave unnecessary spaces at the end of a line, or -empty lines at the end of a file, without realizing it. In most -cases, this @dfn{trailing whitespace} has no effect, but there are -special circumstances where it matters, and it can be a nuisance. - - You can make trailing whitespace at the end of a line visible by -setting the buffer-local variable @code{show-trailing-whitespace} to -@code{t}. Then Emacs displays trailing whitespace, using the face -@code{trailing-whitespace}. - - This feature does not apply when point is at the end of the line -containing the whitespace. Strictly speaking, that is ``trailing -whitespace'' nonetheless, but displaying it specially in that case -looks ugly while you are typing in new text. In this special case, -the location of point is enough to show you that the spaces are -present. - -@findex delete-trailing-whitespace - To delete all trailing whitespace within the buffer's accessible -portion (@pxref{Narrowing}), type @kbd{M-x delete-trailing-whitespace -@key{RET}}. This command does not remove newline characters. - -@vindex indicate-empty-lines -@vindex default-indicate-empty-lines -@cindex unused lines -@cindex fringes, and unused line indication - Emacs can indicate unused lines at the end of the window with a -small image in the left fringe (@pxref{Fringes}). The image appears -for window lines that do not correspond to any buffer text. Blank -lines at the end of the buffer then stand out because they do not have -this image in the fringe. - - To enable this feature, set the buffer-local variable -@code{indicate-empty-lines} to a non-@code{nil} value. The default -value of this variable is controlled by the variable -@code{default-indicate-empty-lines}; by setting that variable, you -can enable or disable this feature for all new buffers. (This feature -currently doesn't work on text-only terminals.) - -@node Selective Display -@section Selective Display -@cindex selective display -@findex set-selective-display -@kindex C-x $ - - Emacs has the ability to hide lines indented more than a given -number of columns. You can use this to get an overview of a part of a -program. - - To hide lines in the current buffer, type @kbd{C-x $} -(@code{set-selective-display}) with a numeric argument @var{n}. Then -lines with at least @var{n} columns of indentation disappear from the -screen. The only indication of their presence is that three dots -(@samp{@dots{}}) appear at the end of each visible line that is -followed by one or more hidden ones. - - The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as -if they were not there. - - The hidden lines are still present in the buffer, and most editing -commands see them as usual, so you may find point in the middle of the -hidden text. When this happens, the cursor appears at the end of the -previous line, after the three dots. If point is at the end of the -visible line, before the newline that ends it, the cursor appears before -the three dots. - - To make all lines visible again, type @kbd{C-x $} with no argument. - -@vindex selective-display-ellipses - If you set the variable @code{selective-display-ellipses} to -@code{nil}, the three dots do not appear at the end of a line that -precedes hidden lines. Then there is no visible indication of the -hidden lines. This variable becomes local automatically when set. - - See also @ref{Outline Mode} for another way to hide part of -the text in a buffer. - -@node Optional Mode Line -@section Optional Mode Line Features - -@cindex buffer size display -@cindex display of buffer size -@findex size-indication-mode - The buffer percentage @var{pos} indicates the percentage of the -buffer above the top of the window. You can additionally display the -size of the buffer by typing @kbd{M-x size-indication-mode} to turn on -Size Indication mode. The size will be displayed immediately -following the buffer percentage like this: - -@example -@var{POS} of @var{SIZE} -@end example - -@noindent -Here @var{SIZE} is the human readable representation of the number of -characters in the buffer, which means that @samp{k} for 10^3, @samp{M} -for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. - -@cindex line number display -@cindex display of line number -@findex line-number-mode - The current line number of point appears in the mode line when Line -Number mode is enabled. Use the command @kbd{M-x line-number-mode} to -turn this mode on and off; normally it is on. The line number appears -after the buffer percentage @var{pos}, with the letter @samp{L} to -indicate what it is. - -@cindex Column Number mode -@cindex mode, Column Number -@findex column-number-mode - Similarly, you can display the current column number by turning on -Column number mode with @kbd{M-x column-number-mode}. The column -number is indicated by the letter @samp{C}. However, when both of -these modes are enabled, the line and column numbers are displayed in -parentheses, the line number first, rather than with @samp{L} and -@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more -information about minor modes and about how to use these commands. - -@cindex narrowing, and line number display - If you have narrowed the buffer (@pxref{Narrowing}), the displayed -line number is relative to the accessible portion of the buffer. -Thus, it isn't suitable as an argument to @code{goto-line}. (Use -@code{what-line} command to see the line number relative to the whole -file.) - -@vindex line-number-display-limit - If the buffer is very large (larger than the value of -@code{line-number-display-limit}), Emacs won't compute the line -number, because that would be too slow; therefore, the line number -won't appear on the mode-line. To remove this limit, set -@code{line-number-display-limit} to @code{nil}. - -@vindex line-number-display-limit-width - Line-number computation can also be slow if the lines in the buffer -are too long. For this reason, Emacs doesn't display line numbers if -the average width, in characters, of lines near point is larger than -the value of @code{line-number-display-limit-width}. The default -value is 200 characters. - -@findex display-time -@cindex time (on mode line) - Emacs can optionally display the time and system load in all mode -lines. To enable this feature, type @kbd{M-x display-time} or customize -the option @code{display-time-mode}. The information added to the mode -line usually appears after the buffer name, before the mode names and -their parentheses. It looks like this: - -@example -@var{hh}:@var{mm}pm @var{l.ll} -@end example - -@noindent -@vindex display-time-24hr-format -Here @var{hh} and @var{mm} are the hour and minute, followed always by -@samp{am} or @samp{pm}. @var{l.ll} is the average number of running -processes in the whole system recently. (Some fields may be missing if -your operating system cannot support them.) If you prefer time display -in 24-hour format, set the variable @code{display-time-24hr-format} -to @code{t}. - -@cindex mail (on mode line) -@vindex display-time-use-mail-icon -@vindex display-time-mail-face -@vindex display-time-mail-file -@vindex display-time-mail-directory - The word @samp{Mail} appears after the load level if there is mail -for you that you have not read yet. On a graphical display you can use -an icon instead of @samp{Mail} by customizing -@code{display-time-use-mail-icon}; this may save some space on the mode -line. You can customize @code{display-time-mail-face} to make the mail -indicator prominent. Use @code{display-time-mail-file} to specify -the mail file to check, or set @code{display-time-mail-directory} -to specify the directory to check for incoming mail (any nonempty regular -file in the directory is considered as ``newly arrived mail''). - -@cindex mail (on mode line) -@findex display-battery-mode -@vindex display-battery-mode -@vindex battery-mode-line-format - When running Emacs on a laptop computer, you can display the battery -charge on the mode-line, by using the command -@code{display-battery-mode} or customizing the variable -@code{display-battery-mode}. The variable -@code{battery-mode-line-format} determines the way the battery charge -is displayed; the exact mode-line message depends on the operating -system, and it usually shows the current battery charge as a -percentage of the total charge. - -@cindex mode line, 3D appearance -@cindex attributes of mode line, changing -@cindex non-integral number of lines in a window - By default, the mode line is drawn on graphics displays with -3D-style highlighting, like that of a button when it is not being -pressed. If you don't like this effect, you can disable the 3D -highlighting of the mode line, by customizing the attributes of the -@code{mode-line} face. @xref{Face Customization}. - -@cindex non-selected windows, mode line appearance - By default, the mode line of nonselected windows is displayed in a -different face, called @code{mode-line-inactive}. Only the selected -window is displayed in the @code{mode-line} face. This helps show -which window is selected. When the minibuffer is selected, since -it has no mode line, the window from which you activated the minibuffer -has its mode line displayed using @code{mode-line}; as a result, -ordinary entry to the minibuffer does not change any mode lines. - -@vindex mode-line-in-non-selected-windows - You can disable use of @code{mode-line-inactive} by setting variable -@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode -lines are displayed in the @code{mode-line} face. - -@vindex eol-mnemonic-unix -@vindex eol-mnemonic-dos -@vindex eol-mnemonic-mac -@vindex eol-mnemonic-undecided - You can customize the mode line display for each of the end-of-line -formats by setting each of the variables @code{eol-mnemonic-unix}, -@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and -@code{eol-mnemonic-undecided} to the strings you prefer. - -@node Text Display -@section How Text Is Displayed -@cindex characters (in text) - - @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs -buffers are displayed with their graphics, as are non-@acronym{ASCII} multibyte -printing characters (octal codes above 0400). - -@vindex tab-width -@vindex default-tab-width - Some @acronym{ASCII} control characters are displayed in special -ways. The newline character (octal code 012) is displayed by starting -a new line. The tab character (octal code 011) is displayed by moving -to the next tab stop column (normally every 8 columns). The number of -spaces per tab is controlled by the variable @code{tab-width}, which -must have an integer value between 1 and 1000, inclusive, and is made -local by changing it. Note that how the tab character in the buffer -is displayed has nothing to do with the definition of @key{TAB} as a -command. The variable @code{default-tab-width} controls the default -value of this variable for buffers where you have not set it locally. - - Other @acronym{ASCII} control characters are normally displayed as a caret -(@samp{^}) followed by the non-control version of the character; thus, -control-A is displayed as @samp{^A}. The caret appears in face -@code{escape-glyph}. - - Non-@acronym{ASCII} characters 0200 through 0237 (octal) are -displayed with octal escape sequences; thus, character code 0230 -(octal) is displayed as @samp{\230}. The backslash appears in face -@code{escape-glyph}. - -@vindex ctl-arrow - If the variable @code{ctl-arrow} is @code{nil}, control characters in -the buffer are displayed with octal escape sequences, except for newline -and tab. Altering the value of @code{ctl-arrow} makes it local to the -current buffer; until that time, the default value is in effect. The -default is initially @code{t}. - - The display of character codes 0240 through 0377 (octal) may be -either as escape sequences or as graphics. They do not normally occur -in multibyte buffers, but if they do, they are displayed as Latin-1 -graphics. In unibyte mode, if you enable European display they are -displayed using their graphics (assuming your terminal supports them), -otherwise as escape sequences. @xref{Unibyte Mode}. - -@vindex nobreak-char-display -@cindex no-break space, display -@cindex no-break hyphen, display -@cindex soft hyphen, display - Some character sets define ``no-break'' versions of the space and -hyphen characters, which are used where a line should not be broken. -Emacs normally displays these characters with special faces -(respectively, @code{nobreak-space} and @code{escape-glyph}) to -distinguish them from ordinary spaces and hyphens. You can turn off -this feature by setting the variable @code{nobreak-char-display} to -@code{nil}. If you set the variable to any other value, that means to -prefix these characters with an escape character. - - You can customize the way any particular character code is displayed -by means of a display table. @xref{Display Tables,, Display Tables, -elisp, The Emacs Lisp Reference Manual}. - -@node Cursor Display -@section Displaying the Cursor - -@findex blink-cursor-mode -@vindex blink-cursor-alist -@cindex cursor, locating visually -@cindex cursor, blinking - You can customize the cursor's color, and whether it blinks, using -the @code{cursor} Custom group (@pxref{Easy Customization}). On -a graphical display, the command @kbd{M-x blink-cursor-mode} enables -or disables the blinking of the cursor. (On text terminals, the -terminal itself blinks the cursor, and Emacs has no control over it.) -You can control how the cursor appears when it blinks off by setting -the variable @code{blink-cursor-alist}. - -@vindex visible-cursor - Some text terminals offer two different cursors: the normal cursor -and the very visible cursor, where the latter may be e.g. bigger or -blinking. By default Emacs uses the very visible cursor, and switches -to it when you start or resume Emacs. If the variable -@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it -doesn't switch, so it uses the normal cursor. - -@cindex cursor in non-selected windows -@vindex cursor-in-non-selected-windows - Normally, the cursor appears in non-selected windows without -blinking, with the same appearance as when the blinking cursor blinks -``off.'' For a box cursor, this is a hollow box; for a bar cursor, -this is a thinner bar. To turn off cursors in non-selected windows, -customize the variable @code{cursor-in-non-selected-windows} and -assign it a @code{nil} value. - -@vindex x-stretch-cursor -@cindex wide block cursor - On graphical displays, Emacs can optionally draw the block cursor -as wide as the character under the cursor---for example, if the cursor -is on a tab character, it would cover the full width occupied by that -tab character. To enable this feature, set the variable -@code{x-stretch-cursor} to a non-@code{nil} value. - -@findex hl-line-mode -@findex global-hl-line-mode -@cindex highlight current line - To make the cursor even more visible, you can use HL Line mode, a -minor mode that highlights the line containing point. Use @kbd{M-x -hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x -global-hl-line-mode} enables or disables the same mode globally. - -@node Line Truncation -@section Truncation of Lines - -@cindex truncation -@cindex line truncation, and fringes - As an alternative to continuation (@pxref{Continuation Lines}), Emacs -can display long lines by @dfn{truncation}. This means that all the -characters that do not fit in the width of the screen or window do not -appear at all. On graphical displays, a small straight arrow in the -fringe indicates truncation at either end of the line. On text-only -terminals, @samp{$} appears in the first column when there is text -truncated to the left, and in the last column when there is text -truncated to the right. - -@vindex truncate-lines -@findex toggle-truncate-lines - Horizontal scrolling automatically causes line truncation -(@pxref{Horizontal Scrolling}). You can explicitly enable line -truncation for a particular buffer with the command @kbd{M-x -toggle-truncate-lines}. This works by locally changing the variable -@code{truncate-lines}. If that variable is non-@code{nil}, long lines -are truncated; if it is @code{nil}, they are continued onto multiple -screen lines. Setting the variable @code{truncate-lines} in any way -makes it local to the current buffer; until that time, the default -value is in effect. The default value is normally @code{nil}. - -@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows. - If the variable @code{truncate-partial-width-windows} is -non-@code{nil}, it forces truncation rather than continuation in any -window less than the full width of the screen or frame, regardless of -the value of @code{truncate-lines}. See also @ref{Display,, Display, -elisp, The Emacs Lisp Reference Manual}. - -@vindex overflow-newline-into-fringe - If the variable @code{overflow-newline-into-fringe} is -non-@code{nil} on a graphical display, then Emacs does not continue or -truncate a line which is exactly as wide as the window. Instead, the -newline overflows into the right fringe, and the cursor appears in the -fringe when positioned on that newline. - -@node Visual Line Mode -@section Visual Line Mode - -@cindex word wrap - Another alternative to ordinary line continuation is to use -@dfn{word wrap}. Here, each long logical line is divided into two or -more screen lines, like in ordinary line continuation. However, Emacs -attempts to wrap the line at word boundaries near the right window -edge. This makes the text easier to read, as wrapping does not occur -in the middle of words. - -@cindex Visual Line mode -@findex visual-line-mode -@findex global-visual-line-mode - Word wrap is enabled by Visual Line mode, an optional minor mode. -To turn on Visual Line mode in the current buffer, type @kbd{M-x -visual-line-mode}; repeating this command turns it off. You can also -turn on Visual Line mode using the menu bar: in the Options menu, -select the @samp{Line Wrapping in this Buffer} submenu, followed by -the @samp{Word Wrap (Visual Line Mode)} menu item. While Visual Line -mode is enabled, the mode-line shows the string @samp{wrap} in the -mode display. The command @kbd{M-x global-visual-line-mode} toggles -Visual Line mode in all buffers. - -@findex beginning-of-visual-line -@findex end-of-visual-line -@findex next-logical-line -@findex previous-logical-line - In Visual Line mode, some editing commands work on screen lines -instead of logical lines: @kbd{C-a} (@code{beginning-of-visual-line}) -moves to the beginning of the screen line, @kbd{C-e} -(@code{end-of-visual-line}) moves to the end of the screen line, and -@kbd{C-k} (@code{kill-visual-line}) kills text to the end of the -screen line. - - To move by logical lines, use the commands @kbd{M-x -next-logical-line} and @kbd{M-x previous-logical-line}. These move -point to the next logical line and the previous logical line -respectively, regardless of whether Visual Line mode is enabled. If -you use these commands frequently, it may be convenient to assign key -bindings to them. @xref{Init Rebinding}. - - By default, word-wrapped lines do not display fringe indicators. -Visual Line mode is often used to edit files that contain many long -logical lines, so having a fringe indicator for each wrapped line -would be visually distracting. You can change this by customizing the -variable @code{visual-line-fringe-indicators}. - -@node Display Custom -@section Customization of Display - - This section describes variables (@pxref{Variables}) that you can -change to customize how Emacs displays. Beginning users can skip -it. -@c the reason for that pxref is because an xref early in the -@c ``echo area'' section leads here. - -@vindex inverse-video - If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts -to invert all the lines of the display from what they normally are. - -@vindex visible-bell - If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts -to make the whole screen blink when it would normally make an audible bell -sound. This variable has no effect if your terminal does not have a way -to make the screen blink. - -@vindex echo-keystrokes - The variable @code{echo-keystrokes} controls the echoing of multi-character -keys; its value is the number of seconds of pause required to cause echoing -to start, or zero, meaning don't echo at all. The value takes effect when -there is someting to echo. @xref{Echo Area}. - -@vindex baud-rate - The variable @anchor{baud-rate}@code{baud-rate} holds the output -speed of the terminal, as far as Emacs knows. Setting this variable -does not change the speed of actual data transmission, but the value -is used for calculations. On text-only terminals, it affects padding, -and decisions about whether to scroll part of the screen or redraw it -instead. It also affects the behavior of incremental search. - - On graphical displays, @code{baud-rate} is only used to determine -how frequently to look for pending input during display updating. A -higher value of @code{baud-rate} means that check for pending input -will be done less frequently. - -@cindex hourglass pointer display -@vindex hourglass-delay - On graphical displays, Emacs can optionally display the mouse pointer -in a special shape to say that Emacs is busy. To turn this feature on -or off, customize the group @code{cursor}. You can also control the -amount of time Emacs must remain busy before the busy indicator is -displayed, by setting the variable @code{hourglass-delay}. - -@vindex overline-margin - On graphical displays, the variable @code{overline-margin} specifies -the vertical position of an overline above the text, including the -height of the overline itself, in pixels. The default value is 2. - -@vindex x-underline-at-descent-line - On graphical displays, Emacs normally draws an underline at the -baseline level of the font. If @code{x-underline-at-descent-line} is -non-@code{nil}, Emacs draws the underline at the same height as the -font's descent line. - -@findex tty-suppress-bold-inverse-default-colors - On some text-only terminals, bold face and inverse video together -result in text that is hard to read. Call the function -@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} -argument to suppress the effect of bold-face in this case. - -@vindex no-redraw-on-reenter - On a text-only terminal, when you reenter Emacs after suspending, Emacs -normally clears the screen and redraws the entire display. On some -terminals with more than one page of memory, it is possible to arrange -the termcap entry so that the @samp{ti} and @samp{te} strings (output -to the terminal when Emacs is entered and exited, respectively) switch -between pages of memory so as to use one page for Emacs and another -page for other output. On such terminals, you might want to set the variable -@code{no-redraw-on-reenter} non-@code{nil}; this tells Emacs to -assume, when resumed, that the screen page it is using still contains -what Emacs last wrote there. - -@ignore - arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4 -@end ignore diff --git a/doc/emacs/doclicense.texi b/doc/emacs/doclicense.texi deleted file mode 100644 index 6e9f5a144b9..00000000000 --- a/doc/emacs/doclicense.texi +++ /dev/null @@ -1,512 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - -@ignore - arch-tag: d68e7b7a-0c7c-4c15-905b-a9482214e25a -@end ignore - diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi deleted file mode 100644 index 0450450fbcd..00000000000 --- a/doc/emacs/emacs-xtra.texi +++ /dev/null @@ -1,142 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/emacs-xtra -@settitle Specialized Emacs Features -@c Merge all functions, variables, and keys into the concept index. -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This manual describes specialized features of Emacs. - -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. -@end direntry - -@titlepage -@title Specialized Emacs Features -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Specialized Emacs Features - -@insertcopying - -@end ifnottex - -@menu -* Introduction:: What documentation belongs here? -@iftex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. - -* Autorevert:: Auto Reverting non-file buffers. -* Subdir Switches:: Subdirectory switches in Dired. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. -* Emerge:: A convenient way of merging two versions of a program. -* Advanced VC Usage:: Advanced VC (version control) features. -* Fortran:: Fortran mode and its special features. -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). -@end iftex -* Index:: -@end menu - -@node Introduction -@unnumbered Introduction - -This manual contains detailed information about various features that -are too specialized to be included in the printed Emacs manual. It is -intended to be readable by anyone having a basic knowledge of Emacs. -However, certain sections may be intended for a more specialized -audience, such as Elisp authors. This should be clearly pointed out -at the beginning of these sections. - -@c Note to authors - you need to be careful about cross-references to -@c topics in the Emacs manual. As a printed document, the xtra files -@c are separate from the Emacs manual; but as an info document, they -@c are part of the Emacs manual. Hence you need to use something like: -@c @iftex -@c @ref{Comparing Files,,, emacs, the Emacs Manual}, -@c @end iftex -@c @ifnottex -@c @ref{Comparing Files}, -@c @end ifnottex - -Certain packages (or collections of related features) have their own -manuals, separate from the main Emacs manual. This manual is -intended as a complement, rather than an alternative, to reading those -additional manuals. In a nutshell, it is a collection of smaller -specialized features (or extra detail about standard features), too -small or too obscure to justify their own manual, or inclusion in the -printed Emacs manual. The chapters in this manual are, however, -included (at the relevant places) in the main Emacs manual when it is -formatted as an Info document. - -Sections intended specifically for Elisp programmers can follow the -style of the Elisp manual. Other sections should follow the style of -the Emacs manual. - -@iftex -@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections. -@include picture-xtra.texi - -@raisesections -@include arevert-xtra.texi - -@include dired-xtra.texi - -@include cal-xtra.texi - -@include emerge-xtra.texi - -@include vc-xtra.texi - -@include fortran-xtra.texi - -@include msdog-xtra.texi - -@lowersections -@end iftex - -@node Index -@unnumbered Index - -@printindex cp - -@bye - -@ignore - arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 -@end ignore diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi deleted file mode 100644 index 2ba12b195d1..00000000000 --- a/doc/emacs/emacs.texi +++ /dev/null @@ -1,1570 +0,0 @@ -\input texinfo - -@setfilename ../../info/emacs -@settitle GNU Emacs Manual - -@c The edition number appears in several places in this file -@set EDITION Sixteenth -@set EMACSVER 23.1 - -@copying -This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* -updated for Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and -``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Emacs: (emacs). The extensible self-documenting text editor. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -@set EMACSVER 22 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@defcodeindex op -@synindex pg cp - -@iftex -@kbdinputstyle code - -@shorttitlepage GNU Emacs Manual -@end iftex - -@titlepage -@sp 6 -@center @titlefont{GNU Emacs Manual} -@sp 4 -@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. -@sp 5 -@center Richard Stallman -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin Street, Fifth Floor @* -Boston, MA 02110-1301 USA @* -ISBN 1-882114-86-8 - -@sp 2 -Cover art by Etienne Suvasa. - -@end titlepage - - -@summarycontents -@contents - - -@ifnottex -@node Top, Distrib, (dir), (dir) -@top The Emacs Editor - -Emacs is the extensible, customizable, self-documenting real-time -display editor. This Info file describes how to edit with Emacs and -some of how to customize it; it corresponds to GNU Emacs version -@value{EMACSVER}. - -@ifinfo -To learn more about the Info documentation system, type @kbd{h}, -to visit a programmed instruction sequence for the Info commands. -@end ifinfo - -For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The -Emacs Lisp Reference Manual}. - -@insertcopying -@end ifnottex - -@ignore -These subcategories have been deleted for simplicity -and to avoid conflicts. -Completion -Backup Files -Auto-Saving: Protection Against Disasters -Tags -Text Mode -Outline Mode -@TeX{} Mode -Formatted Text -Shell Command History - -The ones for Dired and Rmail have had the items turned into :: items -to avoid conflicts. -Also Running Shell Commands from Emacs -and Sending Mail and Registers and Minibuffer. -@end ignore - -@menu -* Distrib:: How to get the latest Emacs distribution. -* Intro:: An introduction to Emacs concepts. -@c Note that in the printed manual, the glossary and indices come last. -* Glossary:: Terms used in this manual. - -Indexes (each index contains a large menu) -* Key Index:: An item for each standard Emacs key sequence. -* Option Index:: An item for every command-line option. -* Command Index:: An item for each command name. -* Variable Index:: An item for each documented variable. -* Concept Index:: An item for each concept. - -* Acknowledgments:: Major contributors to GNU Emacs. - -Important General Concepts -* Screen:: How to interpret what you see on the screen. -* User Input:: Kinds of input events (characters, buttons, - function keys). -* Keys:: Key sequences: what you type to request one - editing action. -* Commands:: Named functions run by key sequences to do editing. -* Entering Emacs:: Starting Emacs from the shell. -* Exiting:: Stopping or killing Emacs. - -Fundamental Editing Commands -* Basic:: The most basic editing commands. -* Minibuffer:: Entering arguments that are prompted for. -* M-x:: Invoking commands by their names. -* Help:: Commands for asking Emacs about its commands. - -Important Text-Changing Commands -* Mark:: The mark: how to delimit a ``region'' of text. -* Killing:: Killing (cutting) text. -* Yanking:: Recovering killed text. Moving text. (Pasting.) -* Accumulating Text:: Other ways of copying text. -* Rectangles:: Operating on the text inside a rectangle on the screen. -* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} for copy - and paste, with enhanced rectangle support. -* Registers:: Saving a text string or a location in the buffer. -* Display:: Controlling what text is displayed. -* Search:: Finding or replacing occurrences of a string. -* Fixit:: Commands especially useful for fixing typos. -* Keyboard Macros:: A keyboard macro records a sequence of - keystrokes to be replayed with a single command. - -Major Structures of Emacs -* Files:: All about handling files. -* Buffers:: Multiple buffers; editing several files at once. -* Windows:: Viewing two pieces of text at once. -* Frames:: Running the same Emacs session in multiple X windows. -* International:: Using non-@acronym{ASCII} character sets. - -Advanced Features -* Major Modes:: Text mode vs. Lisp mode vs. C mode... -* Indentation:: Editing the white space at the beginnings of lines. -* Text:: Commands and modes for editing English. -* Programs:: Commands and modes for editing programs. -* Building:: Compiling, running and debugging programs. -* Maintaining:: Features for maintaining large programs. -* Abbrevs:: How to define text abbreviations to reduce - the number of characters you must type. -@c AFAICS, the tex stuff generates its own index and does not use this one. -@ifnottex -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. -@end ifnottex -* Sending Mail:: Sending mail in Emacs. -* Rmail:: Reading mail in Emacs. -* Dired:: You can ``edit'' a directory to manage files in it. -* Calendar/Diary:: The calendar and diary facilities. -* Document View:: Viewing PDF, PS and DVI files. -* Gnus:: How to read netnews with Emacs. -* Shell:: Executing shell commands from Emacs. -* Emacs Server:: Using Emacs as an editing server for @code{mail}, etc. -* Printing:: Printing hardcopies of buffers or regions. -* Sorting:: Sorting lines, paragraphs or pages within Emacs. -* Narrowing:: Restricting display and editing to a portion - of the buffer. -* Two-Column:: Splitting apart columns to edit them - in side-by-side windows. -* Editing Binary Files::Using Hexl mode to edit binary files. -* Saving Emacs Sessions:: Saving Emacs state from one session to the next. -* Recursive Edit:: A command can allow you to do editing - "within the command". This is called a - "recursive editing level". -* Emulation:: Emulating some other editors with Emacs. -* Hyperlinking:: Following links in buffers. -* Dissociated Press:: Dissociating text for fun. -* Amusements:: Various games and hacks. -* Customization:: Modifying the behavior of Emacs. - -Recovery from Problems -* Quitting:: Quitting and aborting. -* Lossage:: What to do if Emacs is hung or malfunctioning. -* Bugs:: How and when to report a bug. -* Contributing:: How to contribute improvements to Emacs. -* Service:: How to get help for your own Emacs needs. - -Appendices -* Copying:: The GNU General Public License gives you permission - to redistribute GNU Emacs on certain terms; - it also explains that there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Emacs Invocation:: Hairy startup options. -* X Resources:: X resources for customizing Emacs. -* Antinews:: Information about Emacs version 22. -* Mac OS / GNUstep:: Using Emacs under Mac OS and GNUstep. -* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. -* Manifesto:: What's GNU? Gnu's Not Unix! - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are some other nodes which are really inferiors of the ones -already listed, mentioned here so you can get to them in one step: - -The Organization of the Screen - -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. - -Basic Editing Commands - -* Inserting Text:: Inserting text by simply typing it. -* Moving Point:: Moving the cursor to the place where you want to - change something. -* Erasing:: Deleting and killing text. -* Basic Undo:: Undoing recent changes in the text. -* Basic Files:: Visiting, creating, and saving files. -* Basic Help:: Asking what a character does. -* Blank Lines:: Making and deleting blank lines. -* Continuation Lines:: How Emacs displays lines too wide for the screen. -* Position Info:: What page, line, row, or column is point on? -* Arguments:: Numeric arguments for repeating a command N times. -* Repeating:: Repeating the previous command quickly. - -The Minibuffer - -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. - -Completion - -* Completion Example:: Examples of using completion. -* Completion Commands:: A list of completion commands. -* Strict Completion:: Different types of completion. -* Completion Options:: Options for completion. - -Help - -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Library Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display pre-written help files. -* Help Echo:: Help on active text and tooltips (`balloon help'). - -The Mark and the Region - -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Persistent Mark:: Keeping the mark active all the time. - -Killing and Moving Text - -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. - -Yanking - -* Kill Ring:: Where killed text is stored. Basic yanking. -* Appending Kills:: Several kills in a row all yank together. -* Earlier Kills:: Yanking something killed some time ago. - -Registers - -* RegPos:: Saving positions in registers. -* RegText:: Saving text in registers. -* RegRect:: Saving rectangles in registers. -* RegConfig:: Saving window configurations in registers. -* RegNumbers:: Numbers in registers. -* RegFiles:: File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. - -Controlling the Display - -* Scrolling:: Commands to move text up and down in a window. -* Auto Scrolling:: Redisplay scrolls text automatically when needed. -* Horizontal Scrolling:: Moving text left and right in a window. -* Follow Mode:: Follow mode lets two windows scroll as one. -* Faces:: How to change the display style using faces. -* Standard Faces:: Emacs' predefined faces. -* Temporary Face Changes:: Commands to temporarily modify the default text face -* Font Lock:: Minor mode for syntactic highlighting using faces. -* Highlight Interactively:: Tell Emacs what text to highlight. -* Fringes:: Enabling or disabling window fringes. -* Displaying Boundaries:: Displaying top and bottom of the buffer. -* Useless Whitespace:: Showing possibly-spurious trailing whitespace. -* Selective Display:: Hiding lines with lots of indentation. -* Optional Mode Line:: Optional mode line display features. -* Text Display:: How text characters are normally displayed. -* Cursor Display:: Features for displaying the cursor. -* Line Truncation:: Truncating lines to fit the screen width instead - of continuing them to multiple screen lines. -* Visual Line Mode:: Word wrap and screen line-based editing. -* Display Custom:: Information on variables for customizing display. - -Searching and Replacement - -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. - -Incremental Search - -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Isearch Scroll:: Scrolling during an incremental search. -* Isearch Minibuffer:: Incremental search of the minibuffer history. -* Slow Isearch:: Incremental search features for slow terminals. - -Replacement Commands - -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. - -Commands for Fixing Typos - -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. - -Keyboard Macros - -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. - -File Handling - -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -* Autorevert:: Auto Reverting non-file buffers. -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other sites. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. - -Saving Files - -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* File Shadowing:: Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. - -Backup Files - -* Backup Names:: How backup files are named. -* Backup Deletion:: Emacs deletes excess numbered backups. -* Backup Copying:: Backups can be made by copying or renaming. - -Auto Reverting Non-File Buffers - -* Auto Reverting the Buffer Menu:: Auto Revert of the Buffer Menu. -* Auto Reverting Dired:: Auto Revert of Dired buffers. -* Supporting additional buffers:: How to add more Auto Revert support. - -Auto-Saving: Protection Against Disasters - -* Auto Save Files:: The file where auto-saved changes are - actually made until you save the file. -* Auto Save Control:: Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. - -Using Multiple Buffers - -* Select Buffer:: Creating a new buffer or reselecting an old one. -* List Buffers:: Getting a list of buffers that exist. -* Misc Buffer:: Renaming; changing read-onlyness; copying text. -* Kill Buffer:: Killing buffers you no longer need. -* Several Buffers:: How to go through the list of all buffers - and operate variously on several of them. -* Indirect Buffers:: An indirect buffer shares the text of another buffer. -* Buffer Convenience:: Convenience and customization features for - buffer handling. - -Convenience Features and Customization of Buffer Handling - -* Uniquify:: Making buffer names unique with directory parts. -* Iswitchb:: Switching between buffers with substrings. -* Buffer Menus:: Configurable buffer menu. - -Multiple Windows - -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Force Same Window:: Forcing certain buffers to appear in the selected - window rather than in another window. -* Change Window:: Deleting windows and changing their sizes. -* Window Convenience:: Convenience functions for window handling. - -Frames and Graphical Displays - -* Cut and Paste:: Mouse commands for cut and paste. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Moving the mouse pointer out of the way. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text-only terminals. - -Killing and Yanking on Graphical Displays - -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Cut/Paste Other App:: Transfering text between Emacs and other apps. -* Secondary Selection:: Cutting without altering point and mark. -* Clipboard:: Using the clipboard for selections. - -International Character Set Support - -* International Chars:: Basic concepts of multibyte characters. -* Enabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters::When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. - -Major Modes - -* Choosing Modes:: How major modes are specified or chosen. - -Indentation - -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. - -Commands for Human Languages - -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* TeX Mode:: Editing input to the formatter TeX. -* HTML Mode:: Editing HTML, SGML, and XML files. -* Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. - -Filling Text - -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -* Refill:: Keeping paragraphs filled. -* Longlines:: Editing text with very long lines. - -Outline Mode - -* Outline Format:: What the text of an outline looks like. -* Outline Motion:: Special commands for moving through - outlines. -* Outline Visibility:: Commands to control what is visible. -* Outline Views:: Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. - -@TeX{} Mode - -* TeX Editing:: Special commands for editing in TeX mode. -* LaTeX Editing:: Additional commands for LaTeX input files. -* TeX Print:: Commands for printing part of a file with TeX. -* TeX Misc:: Customization of TeX mode, and related features. - -Editing Formatted Text - -* Requesting Formatted Text:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Format Faces:: Bold, italic, underline, etc. -* Format Colors:: Changing the color of text. -* Format Indentation:: Changing the left and right margins. -* Format Justification:: Centering, setting text flush with the - left or right margin, etc. -* Format Properties:: The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. - -@c The automatic texinfo menu update inserts some duplicate items here -@c (faces, colors, indentation, justification, properties), because -@c they are listed in two menus. But we already have them above, no -@c need to list them twice. - -Editing Text-based Tables - -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. -* Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. -* Table Misc:: Table miscellany. - -Editing Programs - -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike modes. -* Asm Mode:: Asm mode and its special features. -* Fortran:: Fortran mode and its special features. - -Top-Level Definitions, or Defuns - -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. - -Indentation for Programs - -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. - -Commands for Editing with Parentheses - -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. - -Manipulating Comments - -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. - -Documentation Lookup - -* Info Lookup:: Looking up library functions and commands - in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. - -C and Related Modes - -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. - -Fortran Mode - -* Fortran Motion:: Moving point by statements or subprograms. -* Fortran Indent:: Indentation commands for Fortran. -* Fortran Comments:: Inserting and aligning comments. -* Fortran Autofill:: Auto fill support for Fortran. -* Fortran Columns:: Measuring columns for valid Fortran. -* Fortran Abbrev:: Built-in abbrevs for Fortran keywords. - -Fortran Indentation - -* ForIndent Commands:: Commands for indenting and filling Fortran. -* ForIndent Cont:: How continuation lines indent. -* ForIndent Num:: How line numbers auto-indent. -* ForIndent Conv:: Conventions you must obey to avoid trouble. -* ForIndent Vars:: Variables controlling Fortran indent style. - -Compiling and Testing Programs - -* Compilation:: Compiling programs in languages other - than Lisp (C, Pascal, etc.). -* Compilation Mode:: The mode for visiting compiler errors. -* Compilation Shell:: Customizing your shell properly - for use in the compilation buffer. -* Grep Searching:: Searching with grep. -* Flymake:: Finding syntax errors on the fly. -* Debuggers:: Running symbolic debuggers for non-Lisp programs. -* Executing Lisp:: Various modes for editing Lisp programs, - with different facilities for running - the Lisp programs. -* Lisp Libraries:: Creating Lisp programs to run in Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. -* External Lisp:: Communicating through Emacs with a separate Lisp. - -Running Debuggers Under Emacs - -* Starting GUD:: How to start a debugger subprocess. -* Debugger Operation:: Connection between the debugger and source buffers. -* Commands of GUD:: Key bindings for common commands. -* GUD Customization:: Defining your own commands for GUD. -* GDB Graphical Interface:: An enhanced mode that uses GDB features to - implement a graphical debugging environment through - Emacs. - -GDB Graphical Interface - -* GDB-UI Layout:: Control the number of displayed buffers. -* Source Buffers:: Use the mouse in the fringe/margin to - control your program. -* Breakpoints Buffer:: A breakpoint control panel. -* Stack Buffer:: Select a frame from the call stack. -* Other GDB-UI Buffers::Input/output, locals, registers, - assembler, threads and memory buffers. -* Watch Expressions:: Monitor variable values in the speedbar. - -Maintaining Large Programs - -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -* Emerge:: A convenient way of merging two versions of a program. - -Version Control - -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Old Revisions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -* Remote Repositories:: Efficient access to remote CVS servers. -* Revision Tags:: Symbolic names for revisions. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. - -Introduction to Version Control - -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* Types of Log File:: The VCS log in contrast to the ChangeLog. - -Basic Editing under Version Control - -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -* Log Buffer:: Features available in log entry buffers. - -The Secondary Commands of VC - -* Registering:: Putting a file under version control. -* VC Status:: Viewing the VC status of files. -* VC Undo:: Canceling changes before or after check-in. - -VC Directory Mode - -* VC Directory Buffer:: What the buffer looks like and means. -* VC Directory Commands:: Commands to use in a VC directory buffer. - -Multiple Branches of a File - -* Switching Branches:: How to get to another existing branch. -* Creating Branches:: How to start a new branch. -* Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. - -Remote Repositories - -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. - -Revision Tags - -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. - -Miscellaneous Commands and Features of VC - -* Change Logs and VC:: Generating a change log file from log entries. -* Renaming and VC:: A command to rename both the source and master - file correctly. -* Version Headers:: Inserting version control headers into working files. - -Customizing VC - -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. - -Change Logs - -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. - -Tags Tables - -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. - -Merging Files with Emerge - -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. - -Abbrevs - -* Abbrev Concepts:: Fundamentals of defined abbrevs. -* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. -* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. -* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. -* Saving Abbrevs:: Saving the entire list of abbrevs for another session. -* Dynamic Abbrevs:: Abbreviations for words already in the buffer. -* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. - -@ifnottex -Editing Pictures - -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end ifnottex - -Sending Mail - -* Mail Format:: Format of the mail being composed. -* Mail Headers:: Details of some standard mail header fields. -* Mail Aliases:: Abbreviating and grouping mail addresses. -* Mail Mode:: Special commands for editing mail being composed. -* Mail Amusements:: Distracting the NSA; adding fortune messages. -* Mail Methods:: Using alternative mail-composition methods. - -Mail Mode - -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Copying all or part of a message you are replying to. -* Mail Mode Misc:: Spell checking, signatures, etc. - -Reading Mail with Rmail - -* Rmail Basics:: Basic concepts of Rmail, and simple use. -* Rmail Scrolling:: Scrolling through a message. -* Rmail Motion:: Moving to another message. -* Rmail Deletion:: Deleting and expunging messages. -* Rmail Inbox:: How mail gets into the Rmail file. -* Rmail Files:: Using multiple Rmail files. -* Rmail Output:: Copying message out to files. -* Rmail Labels:: Classifying messages by labeling them. -* Rmail Attributes:: Certain standard labels, called attributes. -* Rmail Reply:: Sending replies to messages you are viewing. -* Rmail Summary:: Summaries show brief info on many messages. -* Rmail Sorting:: Sorting messages in Rmail. -* Rmail Display:: How Rmail displays a message; customization. -* Rmail Coding:: How Rmail handles decoding character sets. -* Rmail Editing:: Editing message text and headers in Rmail. -* Rmail Digest:: Extracting the messages from a digest message. -* Rmail Rot13:: Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. - -Summaries - -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. - -Dired, the Directory Editor - -* Dired Enter:: How to invoke Dired. -* Dired Navigation:: Special motion commands in the Dired buffer. -* Dired Deletion:: Deleting files with Dired. -* Flagging Many Files:: Flagging files based on their names. -* Dired Visiting:: Other file operations through Dired. -* Marks vs Flags:: Flagging for deletion vs marking. -* Operating on Files:: How to copy, rename, print, compress, etc. - either one file or several files. -* Shell Commands in Dired:: Running a shell command on the marked files. -* Transforming File Names:: Using patterns to rename multiple files. -* Comparison in Dired:: Running `diff' by way of Dired. -* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. -* Subdir Switches:: Subdirectory switches in Dired. -* Subdirectory Motion:: Moving across subdirectories, and up and down. -* Hiding Subdirectories:: Making subdirectories visible or invisible. -* Dired Updating:: Discarding lines for files of no interest. -* Dired and Find:: Using `find' to choose the files for Dired. -* Wdired:: Operating on files by editing the Dired buffer. -* Image-Dired:: Viewing image thumbnails in Dired. -* Misc Dired Features:: Various other features. - -The Calendar and the Diary - -* Calendar Motion:: Moving through the calendar; selecting a date. -* Scroll Calendar:: Bringing earlier or later months onto the screen. -* Counting Days:: How many days are there between two dates? -* General Calendar:: Exiting or recomputing the calendar. -* Writing Calendar Files:: Writing calendars to files of various formats. -* Holidays:: Displaying dates of holidays. -* Sunrise/Sunset:: Displaying local times of sunrise and sunset. -* Lunar Phases:: Displaying phases of the moon. -* Other Calendars:: Converting dates to other calendar systems. -* Diary:: Displaying events from your diary. -* Appointments:: Reminders when it's time to do something. -* Importing Diary:: Converting diary events to/from other formats. -* Daylight Saving:: How to specify when daylight saving time is active. -* Time Intervals:: Keeping track of time intervals. -* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. - -Movement in the Calendar - -* Calendar Unit Motion:: Moving by days, weeks, months, and years. -* Move to Beginning or End:: Moving to start/end of weeks, months, and years. -* Specified Dates:: Moving to the current date or another - specific date. - -Conversion To and From Other Calendars - -* Calendar Systems:: The calendars Emacs understands - (aside from Gregorian). -* To Other Calendar:: Converting the selected date to various calendars. -* From Other Calendar:: Moving to a date specified in another calendar. -* Mayan Calendar:: Moving to a date specified in a Mayan calendar. - -The Diary - -* Displaying the Diary:: Viewing diary entries and associated calendar dates. -* Format of Diary File:: Entering events in your diary. -* Date Formats:: Various ways you can specify dates. -* Adding to Diary:: Commands to create diary entries. -* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. - -Customizing the Calendar and Diary - -* Calendar Customizing:: Calendar layout and hooks. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Diary Customizing:: Defaults you can set. -* Non-Gregorian Diary:: Diary entries based on other calendars. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. - -Document Viewing - -* Navigation:: Navigation inside DocView buffers. -* Searching:: Searching inside documents. -* Slicing:: Specifying which part of pages should be displayed. -* Conversion:: Influencing and triggering conversion. - -Gnus - -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Summary of Gnus:: A short description of the basic Gnus commands. - -Running Shell Commands from Emacs - -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* Shell History:: Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Shell Options:: Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Paging in Term:: Paging in the terminal emulator. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. - -Shell Command History - -* Shell Ring:: Fetching commands from the history list. -* Shell History Copying::Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. - -Using Emacs as a Server - -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. - -Printing Hard Copies - -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. - -Hyperlinking and Navigation Features - -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. - -Customization - -* Minor Modes:: Each minor mode is a feature you can turn on - independently of any others. -* Easy Customization:: Convenient way to browse and change settings. -* Variables:: Many Emacs commands examine Emacs variables - to decide what to do; by setting variables, - you can control their functioning. -* Key Bindings:: The keymaps say what command each key runs. - By changing them, you can "redefine keys". -* Syntax:: The syntax table controls how words and - expressions are parsed. -* Init File:: How to write common customizations in the - @file{.emacs} file. - -Easy Customization Interface - -* Customization Groups:: How settings are classified in a structure. -* Browsing Custom:: Browsing and searching for settings. -* Changing a Variable:: How to edit an option's value and set the option. -* Saving Customizations:: Specifying the file for saving customizations. -* Face Customization:: How to edit the attributes of a face. -* Specific Customization:: Making a customization buffer for specific - variables, faces, or groups. -* Custom Themes:: How to define collections of customized options - that can be loaded and unloaded together. - -Variables - -* Examining:: Examining or setting one variable's value. -* Hooks:: Hook variables let you specify programs for parts - of Emacs to run on particular occasions. -* Locals:: Per-buffer values of variables. -* File Variables:: How files can specify variable values. -* Directory Variables:: How variable values can be specified by directory. - -Local Variables in Files - -* Specifying File Variables:: Specifying file local variables. -* Safe File Variables:: Making sure file local variables are safe. - -Customizing Key Bindings - -* Keymaps:: Generalities. The global keymap. -* Prefix Keymaps:: Keymaps for prefix keys. -* Local Keymaps:: Major and minor modes have their own keymaps. -* Minibuffer Maps:: The minibuffer uses its own local keymaps. -* Rebinding:: How to redefine one key's meaning conveniently. -* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. -* Modifier Keys:: Using modifier keys in key bindings. -* Function Keys:: Rebinding terminal function keys. -* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. -* Mouse Buttons:: Rebinding mouse buttons in Emacs. -* Disabling:: Disabling a command means confirmation is required - before it can be executed. This is done to protect - beginners from surprises. - -The Init File, @file{~/.emacs} - -* Init Syntax:: Syntax of constants in Emacs Lisp. -* Init Examples:: How to do some things with an init file. -* Terminal Init:: Each terminal type can have an init file. -* Find Init:: How Emacs finds the init file. -* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. - -Dealing with Emacs Trouble - -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. - -Reporting Bugs - -* Bug Criteria:: Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. - -Command Line Arguments for Emacs Invocation - -* Action Arguments:: Arguments to visit files, load libraries, - and call functions. -* Initial Options:: Arguments that take effect while starting Emacs. -* Command Example:: Examples of using command line arguments. -* Resume Arguments:: Specifying arguments when you resume a running Emacs. -* Environment:: Environment variables that Emacs uses. -* Display X:: Changing the default display and using remote login. -* Font X:: Choosing a font for text, under X. -* Colors:: Choosing display colors. -* Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. -* Title X:: Specifying the initial frame's title. -* Icons X:: Choosing what sort of icon to use, under X. -* Misc X:: Other display options. - -Environment Variables - -* General Variables:: Environment variables that all versions of Emacs use. -* Misc Variables:: Certain system-specific variables. -* MS-Windows Registry:: An alternative to the environment on MS-Windows. - -X Options and Resources - -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Face Resources:: X resources for customizing faces. -* Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. -* GTK resources:: Resources for GTK widgets. - -GTK resources - -* GTK widget names:: How widgets in GTK are named in general. -* GTK Names in Emacs:: GTK widget names in Emacs. -* GTK styles:: What can be customized in a GTK widget. - -Emacs and Mac OS / GNUstep - -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. - -Emacs and Microsoft Windows/MS-DOS - -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs}. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). - -Emacs and MS-DOS - -* MS-DOS Keyboard:: Keyboard conventions on MS-DOS. -* MS-DOS Mouse:: Mouse conventions on MS-DOS. -* MS-DOS Display:: Fonts, frames and display size on MS-DOS. -* MS-DOS File Names:: File name conventions on MS-DOS. -* MS-DOS Printing:: Printing specifics on MS-DOS. -* MS-DOS and MULE:: Support for internationalization on MS-DOS. -* MS-DOS Processes:: Running subprocesses on MS-DOS. - -@end detailmenu -@end menu - -@iftex -@unnumbered Preface - - This manual documents the use and simple customization of the Emacs -editor. Simple Emacs customizations do not require you to be a -programmer, but if you are not interested in customizing, you can -ignore the customization hints. - - This is primarily a reference manual, but can also be used as a -primer. If you are new to Emacs, we recommend you start with -the integrated, learn-by-doing tutorial, before reading the manual. To -run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial -describes commands, tells you when to try them, and explains the -results. - - On first reading, just skim chapters 1 and 2, which describe the -notational conventions of the manual and the general appearance of the -Emacs display screen. Note which questions are answered in these -chapters, so you can refer back later. After reading chapter 4, you -should practice the commands shown there. The next few chapters -describe fundamental techniques and concepts that are used constantly. -You need to understand them thoroughly, so experiment with them -until you are fluent. - - Chapters 14 through 19 describe intermediate-level features that are -useful for many kinds of editing. Chapter 20 and following chapters -describe optional but useful features; read those chapters when you -need them. - - Read the Common Problems chapter if Emacs does not seem to be -working properly. It explains how to cope with several common -problems (@pxref{Lossage}), as well as when and how to report Emacs -bugs (@pxref{Bugs}). - - To find the documentation of a particular command, look in the index. -Keys (character commands) and command names have separate indexes. -There is also a glossary, with a cross reference for each term. - - This manual is available as a printed book and also as an Info file. -The Info file is for use with the Info program, which is the principal -means of accessing on-line documentation in the GNU system. Both the -Emacs Info file and an Info reader are included with GNU Emacs. The -Info file and the printed book contain substantially the same text and -are generated from the same source files, which are also distributed -with GNU Emacs. - - GNU Emacs is a member of the Emacs editor family. There are many -Emacs editors, all sharing common principles of organization. For -information on the underlying philosophy of Emacs and the lessons -learned from its development, see @cite{Emacs, the Extensible, -Customizable Self-Documenting Display Editor}, available from -@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. - -This edition of the manual is intended for use with GNU Emacs -installed on GNU and Unix systems. GNU Emacs can also be used on -MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems. -Those systems use different file name syntax; in addition -MS-DOS does not support all GNU Emacs features. @xref{Microsoft -Windows}, for information about using Emacs on Windows. -@xref{Mac OS / GNUstep}, for information about using Emacs on -Macintosh (and GNUstep). -@end iftex - -@node Distrib, Intro, Top, Top -@unnumbered Distribution - -GNU Emacs is @dfn{free software}; this means that everyone is free to -use it and free to redistribute it on certain conditions. GNU Emacs -is not in the public domain; it is copyrighted and there are -restrictions on its distribution, but these restrictions are designed -to permit everything that a good cooperating citizen would want to do. -What is not allowed is to try to prevent others from further sharing -any version of GNU Emacs that they might get from you. The precise -conditions are found in the GNU General Public License that comes with -Emacs and also appears in this manual@footnote{This manual is itself -covered by the GNU Free Documentation License (see the reverse title -page in the printed manual or view the full source for online formats -to see the precise conditions). This license is similar in spirit to -the General Public License, but is more suitable for documentation. -@xref{GNU Free Documentation License}.}. @xref{Copying}. - -One way to get a copy of GNU Emacs is from someone else who has it. -You need not ask for our permission to do so, or tell any one else; -just copy it. If you have access to the Internet, you can get the -latest distribution version of GNU Emacs by anonymous FTP; see -@url{http://www.gnu.org/software/emacs} on our website for more -information. - -You may also receive GNU Emacs when you buy a computer. Computer -manufacturers are free to distribute copies on the same terms that apply to -everyone else. These terms require them to give you the full sources, -including whatever changes they may have made, and to permit you to -redistribute the GNU Emacs received from them under the usual terms of the -General Public License. In other words, the program must be free for you -when you get it, not just free for the manufacturer. - -@c FIXME no longer true? -You can also order copies of GNU Emacs from the Free Software -Foundation. This is a convenient and reliable way to get a copy; it is -also a good way to help fund our work. We also sell hardcopy versions -of this manual and @cite{An Introduction to Programming in Emacs Lisp}, -by Robert J. Chassell. You can visit our online store at -@url{http://shop.fsf.org/}. For further information, -write to - -@display -Free Software Foundation -51 Franklin Street, Fifth Floor -Boston, MA 02110-1301 -USA -@end display - -The income from sales goes to support the foundation's purpose: the -development of new free software, and improvements to our existing -programs including GNU Emacs. - -@c FIXME you can't order a CD any more. -If you find GNU Emacs useful, please @strong{send a donation} to the -Free Software Foundation to support our work. Donations to the Free -Software Foundation are tax deductible in the US. If you use GNU Emacs -at your workplace, please suggest that the company make a donation. If -company policy is unsympathetic to the idea of donating to charity, you -might instead suggest ordering a CD-ROM from the Foundation -occasionally, or subscribing to periodic updates. - -@iftex -@node Acknowledgments, Intro, Distrib, Top -@unnumberedsec Acknowledgments - -Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas -Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf -Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero, -Eli Barzilay, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff, -Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti, Ray Blaak, Jim Blandy, -Johan Bockg@aa{}rd, Per Bothner, Terrence Brannon, Frank Bresz, Peter -Breton, Emmanuel Briot, Kevin Broadey, Vincent Broman, David M.@: -Brown, Georges Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill -Carpenter, Per Cederqvist, Hans Chalupsky, Chong Yidong, Chris Chase, -Bob Chassell, Andrew Choi, Sacha Chua, James Clark, Mike Clarkson, -Glynn Clements, Andrew Csillag, Doug Cutting, Mathias Dahl, Satyaki -Das, Michael DeCorte, Gary Delp, Matthieu Devin, Eri Ding, Jan -Dj@"{a}rv, Carsten Dominik, Scott Draves, Benjamin Drieu, Viktor -Dukhovni, John Eaton, Rolf Ebert, Paul Eggert, Stephen Eglen, -Torbj@"orn Einarsson, Tsugutomo Enami, Hans Henrik Eriksen, Michael -Ernst, Ata Etemadi, Frederick Farnbach, Oscar Figueiredo, Fred Fish, -Karl Fogel, Gary Foster, Romain Francoise, Noah Friedman, Andreas -Fuchs, Hallvard Furuseth, Keith Gabryelski, Peter S.@: Galbraith, -Kevin Gallagher, Kevin Gallo, Juan Le@'{o}n Lahoz -Garc@'{@dotless{i}}a, Howard Gayle, Stephen Gildea, Julien Gilles, -David Gillespie, Bob Glickstein, Deepak Goel, Boris Goldowsky, -Michelangelo Grigni, Odd Gripenstam, Kai Gro@ss{}johann, Michael -Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Lars Hansen, -Chris Hanson, K. Shane Hartman, John Heidemann, Jon K.@: Hellan, -Jesper Harder, Magnus Henoch, Markus Heritsch, Karl Heuer, Manabu -Higashida, Anders Holst, Jeffrey C.@: Honig, Tassilo Horn, Kurt -Hornik, Tom Houlder, Joakim Hove, Denis Howe, Lars Ingebrigtsen, -Andrew Innes, Seiichiro Inoue, Pavel Janik, Paul Jarc, Ulf Jasper, -Michael K. Johnson, Kyle Jones, Terry Jones, Simon Josefsson, Arne -J@o{}rgensen, Tomoji Kagatani, Brewster Kahle, Lute Kamstra, David -Kastrup, David Kaufman, Henry Kautz, Taichi Kawabata, Howard Kaye, -Michael Kifer, Richard King, Peter Kleiweg, Shuhei Kobayashi, Pavel -Kobiakov, Larry K.@: Kolodney, David M.@: Koppelman, Koseki Yoshinori, -Robert Krawitz, Sebastian Kremer, Ryszard Kubiak, Geoff Kuenning, -David K@aa{}gedal, Daniel LaLiberte, Mario Lang, Aaron Larson, James -R.@: Larus, Vinicius Jose Latorre, Werner Lemberg, Frederic Lepied, -Peter Liljenberg, Lars Lindberg, Chris Lindblad, Anders Lindgren, -Thomas Link, Juri Linkov, Francis Litterio, Emilio C. Lopes, Károly -Lőrentey, Dave Love, Sascha L@"{u}decke, Eric Ludlam, Alan Mackenzie, -Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, Bill Mann, -Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin, Thomas -May, Roland McGrath, Will Mengarini, David Megginson, Ben A. Mesander, -Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard Mlynarik, Gerd -Moellmann, Stefan Monnier, Morioka Tomohiko, Keith Moore, Glenn -Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas Neumann, -Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan Nicolaescu, -Hrvoje Niksic, Jeff Norden, Andrew Norman, Alexandre Oliva, Bob Olson, -Michael Olson, Takaaki Ota, Pieter E.@: J.@: Pareit, David Pearson, -Jeff Peck, Damon Anton Permezel, Tom Perrine, William M.@: Perry, Per -Persson, Jens Petersen, Daniel Pfeiffer, Richard L.@: Pieri, Fred -Pierresteguy, Christian Plaunt, David Ponce, Francesco A.@: Potorti, -Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko Rahamaa, Ashwin -Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, Alex Rezinsky, -Rob Riepel, David Reitter, Adrian Robert, Nick Roberts, Roland B.@: -Roberts, John Robinson, Danny Roozendaal, William Rosenblatt, -Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, -Wolfgang Rupprecht, Kevin Ryde, James B. Salem, Masahiko Sato, Jorgen -Schaefer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor -Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan -Schormann, Alex Schroeder, Stephen Schoef, Raymond Scholz, Andreas -Schwab, Randal Schwartz, Oliver Seidel, Manuel Serrano, Hovav Shacham, -Stanislav Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen -Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul -D.@: Smith, Andre Spiegel, Michael Staats, William Sommerfeld, Michael -Staats, Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, -Ken Stevens, Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, -Steve Strassman, Olaf Sylvester, Naoto Takahashi, Steven Tamm, -Jean-Philippe Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, -Jim Thompson, Luc Teirlinck, Tom Tromey, Enami Tsugutomo, Eli -Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil -W.@: Van Dyke, Didier Verna, Ulrik Vieth, Geoffrey Voelker, Johan -Vromans, Inge Wallin, John Paul Wallington, Colin Walters, Barry -Warsaw, Morten Welinder, Joseph Brian Wells, Rodney Whitby, John -Wiegley, Ed Wilkinson, Mike Williams, Bill Wohler, Steven A. Wood, -Dale R.@: Worley, Francis J.@: Wright, Felix S. T. Wu, Tom Wurgler, -Katsumi Yamaoka, Yamamoto Mitsuharu, Masatake Yamato, Jonathan Yavner, -Ryan Yeske, Ilya Zakharevich, Milan Zamazal, Victor Zandy, Eli -Zaretskii, Jamie Zawinski, Shenghuo Zhu, Ian T.@: Zimmermann, Reto -Zimmermann, Neal Ziring, Teodor Zlatanov, and Detlev Zundel. -@end iftex - -@node Intro, Glossary, Distrib, Top -@unnumbered Introduction - - You are reading about GNU Emacs, the GNU incarnation of the -advanced, self-documenting, customizable, extensible editor Emacs. -(The `G' in `GNU' is not silent.) - - We call Emacs @dfn{advanced} because it can do much more than simple -insertion and deletion of text. It can control subprocesses, indent -programs automatically, show multiple files at once, and more. -Emacs editing commands operate in terms of characters, words, lines, -sentences, paragraphs, and pages, as well as expressions and comments -in various programming languages. - - @dfn{Self-documenting} means that at any time you can use special -commands, known as @dfn{help commands}, to find out what your options -are, or to find out what any command does, or to find all the -commands that pertain to a given topic. @xref{Help}. - - @dfn{Customizable} means that you can easily alter the behavior of -Emacs commands in simple ways. For instance, if you use a programming -language in which comments start with @samp{<**} and end with -@samp{**>}, you can tell the Emacs comment manipulation commands to -use those strings (@pxref{Comments}). To take another example, you -can rebind the basic cursor motion commands (up, down, left and right) -to any keys on the keyboard that you find comfortable. -@xref{Customization}. - - @dfn{Extensible} means that you can go beyond simple customization -and create entirely new commands. New commands are simply programs -written in the Lisp language, which are run by Emacs's own Lisp -interpreter. Existing commands can even be redefined in the middle of -an editing session, without having to restart Emacs. Most of the -editing commands in Emacs are written in Lisp; the few exceptions -could have been written in Lisp but use C instead for efficiency. -Writing an extension is programming, but non-programmers can use it -afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An -Introduction to Programming in Emacs Lisp}, if you want to learn Emacs -Lisp programming. - -@include screen.texi -@include commands.texi -@include entering.texi -@include basic.texi -@include mini.texi -@include m-x.texi -@include help.texi -@include mark.texi -@include killing.texi -@include regs.texi -@include display.texi -@include search.texi -@include fixit.texi -@include kmacro.texi -@c Includes arevert-xtra. -@include files.texi -@include buffers.texi -@include windows.texi -@include frames.texi -@include mule.texi -@include major.texi -@include indent.texi -@include text.texi -@c Includes fortran-xtra. -@include programs.texi -@include building.texi -@c Includes vc1-xtra, emerge-xtra. -@include maintaining.texi -@include abbrevs.texi -@ifnottex -@include picture-xtra.texi -@end ifnottex -@include sending.texi -@include rmail.texi -@c Includes dired-xtra. -@include dired.texi -@c Includes cal-xtra. -@include calendar.texi -@include misc.texi -@include custom.texi -@include trouble.texi - -@node Copying, GNU Free Documentation License, Service, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Emacs Invocation, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@include cmdargs.texi -@include xresources.texi - -@include anti.texi -@include macos.texi -@c Includes msdog-xtra. -@include msdog.texi -@include gnu.texi -@include glossary.texi -@ifnottex -@include ack.texi -@end ifnottex - -@c The Option Index is produced only in the on-line version, -@c because the index entries related to command-line options -@c tend to point to the same pages and all begin with a dash. -@c This, and the need to keep the node links consistent, are -@c the reasons for the funky @iftex/@ifnottex dance below. -@c The Option Index is _not_ before Key Index, because that -@c would require changes in the glossary.texi's @node line. -@c It is not after Concept Index for similar reasons. - -@iftex -@node Key Index, Command Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky -@end iftex - -@ifnottex -@node Key Index, Option Index, Glossary, Top -@unnumbered Key (Character) Index -@printindex ky - -@node Option Index, Command Index, Key Index, Top -@unnumbered Command-Line Options Index -@printindex op - -@node Command Index, Variable Index, Option Index, Top -@unnumbered Command and Function Index -@printindex fn -@end ifnottex - -@iftex -@node Command Index, Variable Index, Key Index, Top -@unnumbered Command and Function Index -@printindex fn -@end iftex - -@node Variable Index, Concept Index, Command Index, Top -@unnumbered Variable Index -@printindex vr - -@node Concept Index, Acknowledgments, Variable Index, Top -@unnumbered Concept Index -@printindex cp - -@bye - -@ignore - arch-tag: ed48740a-410b-46ea-9387-c9a9252a3392 -@end ignore diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi deleted file mode 100644 index c3b412f70c6..00000000000 --- a/doc/emacs/emerge-xtra.texi +++ /dev/null @@ -1,417 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Emerge -@section Merging Files with Emerge -@cindex Emerge -@cindex merging files - - It's not unusual for programmers to get their signals crossed and -modify the same program in two different directions. To recover from -this confusion, you need to merge the two versions. Emerge makes this -easier. For other ways to compare files, see -@iftex -@ref{Comparing Files,,, emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Comparing Files}, -@end ifnottex -and @ref{Top, Ediff,, ediff, The Ediff Manual}. - -@menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Miscellaneous issues. -@end menu - -@node Overview of Emerge -@subsection Overview of Emerge - - To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only -the accessible portions of those buffers, if they are narrowed. -@iftex -@xref{Narrowing,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Narrowing}. -@end ifnottex - - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). -For each run of differences between the input texts, you can choose -which one of them to keep, or edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@subsection Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states ``prefer-A'' and ``prefer-B'' -(@pxref{State of Difference}). Thus you see only differences for -which neither version is presumed ``correct.'' The mode line -indicates Skip Prefers mode with @samp{S}. This mode is only relevant -when there is an ancestor. - -@findex emerge-auto-advance-mode -@findex emerge-skip-prefers-mode - Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or -clear Auto Advance mode. Use @kbd{s s} -(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. -These commands turn on the mode with a positive argument, turn it off -with a negative or zero argument, and toggle the mode with no argument. - -@node State of Difference -@subsection State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B. This chosen default applies to all differences -that you have never selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@subsection Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. - -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. -@c [Does not work in the A or B buffer?] -@c You can use this command in the merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. With an argument, -reestablish the default three-window display. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. - -@item c b -Copy the B version of this difference into the kill ring. - -@item i a -Insert the A version of this difference at point. - -@item i b -Insert the B version of this difference at point. - -@item m -Put point and mark around the difference. - -@item ^ -Scroll all three windows down (like @kbd{M-v}). - -@item v -Scroll all three windows up (like @kbd{C-v}). - -@item < -Scroll all three windows left (like @kbd{C-x <}). - -@item > -Scroll all three windows right (like @kbd{C-x >}). - -@item | -Reset horizontal scroll on all three windows. - -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) - -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). - -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) - -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) - -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. - -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. -@end table - -@node Exiting Emerge -@subsection Exiting Emerge - - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. - - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. - - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. - -@node Combining in Emerge -@subsection Combining the Two Versions - - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: - -@example -@group -#ifdef NEW -@var{version from A buffer} -#else /* not NEW */ -@var{version from B buffer} -#endif /* not NEW */ -@end group -@end example - -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B. The default setting, which -produces the results shown above, looks like this: - -@example -@group -"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" -@end group -@end example - -@node Fine Points of Emerge -@subsection Fine Points of Emerge - - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. - - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. - - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. - -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@ignore - arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e -@end ignore diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi deleted file mode 100644 index d7ebb39339b..00000000000 --- a/doc/emacs/entering.texi +++ /dev/null @@ -1,190 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Entering and Exiting Emacs - - This chapter explains how to enter Emacs, and how to exit it. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Entering Emacs, Exiting, Commands, Top -@section Entering Emacs -@cindex entering Emacs -@cindex starting Emacs - - The usual way to invoke Emacs is with the shell command -@command{emacs}. From a terminal window running in the X Window -System, you can also run Emacs in the background with -@command{emacs&}; this way, Emacs won't tie up the terminal window, so -you can use it to run other shell commands. - -@cindex startup screen - When Emacs starts up, the initial frame displays a special buffer -named @samp{*GNU Emacs*}. This buffer contains some information about -Emacs, and includes @dfn{links} to common tasks that might be useful -to beginning users. For instance, activating the @samp{Emacs -Tutorial} link opens the Emacs tutorial; this does the same thing as -the command @kbd{C-h t} (@code{help-with-tutorial}). To activate a -link, either move point onto it and type @kbd{@key{RET}}, or click on -it with @kbd{mouse-1} (the left mouse button). - - Using a command line argument, you can tell Emacs to visit one or -more specific files as soon as it starts up. For example, -@command{emacs foo.txt} starts Emacs with a buffer displaying the -contents of the file @samp{foo.txt}. This feature exists mainly for -compatibility with other editors, which are designed to edit one file -at a time: once you are done with that file, you exit the editor, and -start it again the next time you need it. - - Using Emacs in this way---starting it afresh each time you want to -edit a file---is unnecessary and wasteful. Emacs can visit more than -one file in a single editing session, and exiting the Emacs session -loses valuable accumulated context, such as the kill ring, registers, -undo history, and mark ring. These features, described later in the -manual, are useful for performing edits across multiple files, or -continuing edits to a single file. - - The recommended way to use Emacs is to start it only once, just -after you log in, and do all your editing in the same Emacs session. -Each time you edit a file, visit it with the existing Emacs, which -eventually has many files in it ready for editing. @xref{Files}, for -more information on visiting more than one file. - - To edit a file from another program while Emacs is running, you can -use the @command{emacsclient} helper program to open a file in the -already running Emacs. @xref{Emacs Server}. - - Emacs accepts other command line arguments that tell it to load -certain Lisp files, call certain functions, and so forth. These -features exist mainly for advanced users. @xref{Emacs Invocation}. - -@vindex inhibit-startup-screen - If the variable @code{inhibit-startup-screen} is non-@code{nil}, -Emacs does not display the startup screen. In that case, if one or -more files were specified on the command line, Emacs simply displays -those files; otherwise, it displays a buffer named @samp{*scratch*}, -which can be used to evaluate Emacs Lisp expressions interactively. -@xref{Lisp Interaction}. You can set the variable -@code{inhibit-startup-screen} using the Customize facility -(@pxref{Easy Customization}), or by editing your initialization file -(@pxref{Init File}).@footnote{Note that setting -@code{inhibit-startup-screen} in @file{site-start.el} doesn't work, -because the startup screen is set up before reading -@file{site-start.el}. @xref{Init File}, for information about -@file{site-start.el}.} - - You can also force Emacs to display a file or directory at startup -by setting the variable @code{initial-buffer-choice} to a -non-@code{nil} value. (In that case, even if you specify one or more -files on the command line, Emacs opens but does not display them.) -The value of @code{initial-buffer-choice} can be either the name of -the desired file or directory, or @code{t}, which means to display the -@samp{*scratch*} buffer. - -@node Exiting, Basic, Entering Emacs, Top -@section Exiting Emacs -@cindex exiting -@cindex killing Emacs -@cindex leaving Emacs -@cindex quitting Emacs - -@table @kbd -@item C-x C-c -Kill Emacs (@code{save-buffers-kill-terminal}). -@item C-z -On a text terminal, suspend Emacs (@code{suspend-emacs}); on a -graphical display, iconify (or ``minimize'') the selected frame -(@code{iconify-or-deiconify-frame}). -@end table - -@kindex C-x C-c -@findex save-buffers-kill-terminal - @dfn{Killing} Emacs means terminating the Emacs program. To do -this, type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}). A -two-character key is used to make it harder to type by accident. If -there are any modified file-visiting buffers when you type @kbd{C-x -C-c}, Emacs first offers to save these buffers. If you do not save -them all, it asks for confirmation again, since the unsaved changes -will be lost. Emacs also asks for confirmation if any subprocesses -are still running, since killing Emacs will also kill the subprocesses -(@pxref{Shell}). - - @kbd{C-x C-c} behaves specially if you are using Emacs as a server. -If you type it from a ``client frame'', it closes the client -connection. @xref{Emacs Server}. - - Emacs can, optionally, record certain session information when you -kill it, such as the files you were visiting at the time. This -information is then available the next time you start Emacs. -@xref{Saving Emacs Sessions}. - -@vindex confirm-kill-emacs - If the value of the variable @code{confirm-kill-emacs} is -non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate -function, and calls that function. If the result of the function call -is non-@code{nil}, the session is killed, otherwise Emacs continues to -run. One convenient function to use as the value of -@code{confirm-kill-emacs} is the function @code{yes-or-no-p}. The -default value of @code{confirm-kill-emacs} is @code{nil}. - -@findex kill-emacs - To kill Emacs without being prompted about saving, type @kbd{M-x -kill-emacs}. - -@cindex minimizing a frame -@cindex iconifying -@cindex suspending - You can ``exit'' Emacs in two other ways. On a graphical display, -you can @dfn{iconify} (or @dfn{minimize}) an Emacs frame; depending on -the window system, this either replaces the Emacs frame with a tiny -``icon'' or conceals the frame entirely (@pxref{Frames}). On a -text-only terminal, you can @dfn{suspend} Emacs; this means stopping -the Emacs program temporarily, returning control to its parent process -(usually a shell). - -@kindex C-z -@findex iconify-or-deiconify-frame -@findex suspend-emacs - On a graphical display, @kbd{C-z} runs the command -@code{iconify-or-deiconify-frame}, which iconifies the selected Emacs -frame. On a text terminal, @kbd{C-z} runs the command -@code{suspend-emacs}, which suspends Emacs. - - After iconifying or suspending Emacs, you can return to it and -continue editing wherever you left off. The way to do this depends on -the window system or shell. In most common shells, you can resume -Emacs after suspending it with the shell command @command{%emacs}. - -@vindex cannot-suspend - On very old systems that don't support suspending programs, -@kbd{C-z} starts an inferior shell that communicates directly with the -terminal, and Emacs waits until you exit the subshell. (The way to -exit the subshell is usually @kbd{C-d} or @command{exit}.) On these -systems, you can only get back to the shell from which Emacs was run -(to log out, for example) when you kill Emacs. Suspending can also -fail if you run Emacs under a shell that doesn't support suspending -jobs, even if the system itself does support it. In this case, you -can set the variable @code{cannot-suspend} to a non-@code{nil} value -to force @kbd{C-z} to start an inferior shell. - - Text-only terminals usually listen for certain special characters -whose meaning is to kill or suspend the program you are running. -@b{This terminal feature is turned off while you are in Emacs.} The -meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were inspired -by the use of @kbd{C-z} and @kbd{C-c} on several operating systems as -the characters for stopping or killing a program, but that is their -only relationship with the operating system. You can customize these -keys to run any commands of your choice (@pxref{Keymaps}). - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: df798d8b-f253-4113-b585-f528f078a944 -@end ignore diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi deleted file mode 100644 index 54060b4f9f3..00000000000 --- a/doc/emacs/files.texi +++ /dev/null @@ -1,1973 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Files, Buffers, Keyboard Macros, Top -@chapter File Handling -@cindex files - - The operating system stores data permanently in named @dfn{files}, so -most of the text you edit with Emacs comes from a file and is ultimately -stored in a file. - - To edit a file, you must tell Emacs to read the file and prepare a -buffer containing a copy of the file's text. This is called -@dfn{visiting} the file. Editing commands apply directly to text in the -buffer; that is, to the copy inside Emacs. Your changes appear in the -file itself only when you @dfn{save} the buffer back into the file. - - In addition to visiting and saving files, Emacs can delete, copy, -rename, and append to files, keep multiple versions of them, and operate -on file directories. - -@menu -* File Names:: How to type and edit file-name arguments. -* Visiting:: Visiting a file prepares Emacs to edit the file. -* Saving:: Saving makes your changes permanent. -* Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex -* Auto Save:: Auto Save periodically protects against loss of data. -* File Aliases:: Handling multiple names for one file. -* Directories:: Creating, deleting, and listing file directories. -* Comparing Files:: Finding where two files differ. -* Diff Mode:: Mode for editing file differences. -* Misc File Ops:: Other things you can do on files. -* Compressed Files:: Accessing compressed files. -* File Archives:: Operating on tar, zip, jar etc. archive files. -* Remote Files:: Accessing files on other sites. -* Quoted File Names:: Quoting special characters in file names. -* File Name Cache:: Completion against a list of files you often use. -* File Conveniences:: Convenience Features for Finding Files. -* Filesets:: Handling sets of files. -@end menu - -@node File Names -@section File Names -@cindex file names - - Many Emacs commands that operate on a file require you to specify -the file name, using the minibuffer (@pxref{Minibuffer}). You can use -@dfn{completion} to specify long file names (@pxref{Completion}). -Note that file name completion ignores file names whose extensions -appear in the variable @code{completion-ignored-extensions} -(@pxref{Completion Options}). - - For most operations, there is a @dfn{default file name} which is -used if you type just @key{RET} to enter an empty argument. Normally, -the default file name is the name of the file visited in the current -buffer. - -@vindex default-directory -@vindex insert-default-directory - Each buffer has a @dfn{default directory} which is normally the same -as the directory of the file visited in that buffer. For example, if -the default file name is @file{/u/rms/gnu/gnu.tasks}, the default -directory is normally @file{/u/rms/gnu/}. The default directory is -kept in the variable @code{default-directory}, which has a separate -value in every buffer. When a command reads a file name using the -minibuffer, the default directory usually serves as the initial -contents of the minibuffer. To inhibit the insertion of the default -directory, set the variable @code{insert-default-directory} to -@code{nil}. - - If you enter a file name without a directory, that specifies a file -in the default directory. If you specify a directory in a relative -fashion, with a name that does not start with a slash, it is -interpreted with respect to the default directory. For example, -suppose the default directory is @file{/u/rms/gnu/}. Entering just -@samp{foo} in the minibuffer, with a directory omitted, specifies the -file @file{/u/rms/gnu/foo}; entering @samp{../.login} specifies -@file{/u/rms/.login}; and entering @samp{new/foo} specifies -@file{/u/rms/gnu/new/foo}. - - When typing a file name into the minibuffer, you can make use of a -couple of shortcuts: a double slash is interpreted as ``ignore -everything before the second slash in the pair,'' and @samp{~/} is -interpreted as your home directory. @xref{Minibuffer File}, for more -information about these shortcuts. - -@findex cd -@findex pwd - The command @kbd{M-x pwd} displays the default directory, and the -command @kbd{M-x cd} sets it to a value read using the minibuffer. A -buffer's default directory changes only when the @code{cd} command is -used. A file-visiting buffer's default directory is initialized to -the directory of the file it visits. If you create a buffer with -@kbd{C-x b}, its default directory is copied from that of the buffer -that was current at the time (@pxref{Select Buffer}). - -@cindex environment variables in file names -@cindex expansion of environment variables -@cindex @code{$} in file names - @anchor{File Names with $}The character @samp{$} is used to -substitute an environment variable into a file name. The name of the -environment variable consists of all the alphanumeric characters after -the @samp{$}; alternatively, it can be enclosed in braces after the -@samp{$}. For example, if you have used the shell command -@command{export FOO=rms/hacks} to set up an environment variable named -@env{FOO}, then both @file{/u/$FOO/test.c} and -@file{/u/$@{FOO@}/test.c} are abbreviations for -@file{/u/rms/hacks/test.c}. If the environment variable is not -defined, no substitution occurs, so that the character @samp{$} stands -for itself. - - Note that environment variables affect Emacs only if they are -applied before Emacs is started. - - To access a file with @samp{$} in its name, if the @samp{$} causes -expansion, type @samp{$$}. This pair is converted to a single -@samp{$} at the same time that variable substitution is performed for -a single @samp{$}. Alternatively, quote the whole file name with -@samp{/:} (@pxref{Quoted File Names}). File names which begin with a -literal @samp{~} should also be quoted with @samp{/:}. - - You can include non-@acronym{ASCII} characters in file names if you set the -variable @code{file-name-coding-system} to a non-@code{nil} value. -@xref{File Name Coding}. - -@node Visiting -@section Visiting Files -@cindex visiting files -@cindex open file - -@table @kbd -@item C-x C-f -Visit a file (@code{find-file}). -@item C-x C-r -Visit a file for viewing, without allowing changes to it -(@code{find-file-read-only}). -@item C-x C-v -Visit a different file instead of the one visited last -(@code{find-alternate-file}). -@item C-x 4 f -Visit a file, in another window (@code{find-file-other-window}). Don't -alter what is displayed in the selected window. -@item C-x 5 f -Visit a file, in a new frame (@code{find-file-other-frame}). Don't -alter what is displayed in the selected frame. -@item M-x find-file-literally -Visit a file with no conversion of the contents. -@end table - -@cindex files, visiting and saving -@cindex saving files - @dfn{Visiting} a file means reading its contents into an Emacs -buffer so you can edit them. Emacs makes a new buffer for each file -that you visit. - - Emacs normally constructs the buffer name from the file name, -omitting the directory name. For example, a file named -@file{/usr/rms/emacs.tex} is visited in a buffer named -@samp{emacs.tex}. If there is already a buffer with that name, Emacs -constructs a unique name; the normal method is to append @samp{<2>}, -@samp{<3>}, and so on, but you can select other methods. -@xref{Uniquify}. - - Each window's mode line shows the name of the buffer that is being -displayed in that window, so you can always tell what buffer you are -editing. @pxref{Mode Line}. - - The changes you make with editing commands are made in the Emacs -buffer. They do not take effect in the file that you visited, or any -permanent place, until you @dfn{save} the buffer (@pxref{Saving}). - -@cindex modified (buffer) - If a buffer contains changes that have not been saved, we say the -buffer is @dfn{modified}. This implies that some changes will be lost -if the buffer is not saved. The mode line displays two stars near the -left margin to indicate that the buffer is modified. - -@kindex C-x C-f -@findex find-file - To visit a file, type @kbd{C-x C-f} (@code{find-file}) and use the -minibuffer to enter the name of the desired file. The usual -defaulting and completion behavior is available in this minibuffer -(@pxref{Minibuffer File}). Note, also, that completion ignores -certain file names (@pxref{Completion Options}). While in the -minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. - - Your can tell that @kbd{C-x C-f} has completed successfully by the -appearance of new text on the screen and a new buffer name in the mode -line. If the specified file does not exist and you could not create -it, or exists but you can't read it, an error message is displayed in -the echo area. - - If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make -another copy. It selects the existing buffer containing that file. -However, before doing so, it checks whether the file itself has changed -since you visited or saved it last. If the file has changed, Emacs offers -to reread it. - -@vindex large-file-warning-threshold -@cindex maximum buffer size exceeded, error message - If you try to visit a file larger than -@code{large-file-warning-threshold} (the default is 10000000, which is -about 10 megabytes), Emacs asks you for confirmation first. You can -answer @kbd{y} to proceed with visiting the file. Note, however, that -Emacs cannot visit files that are larger than the maximum Emacs buffer -size, which is around 256 megabytes on 32-bit machines -(@pxref{Buffers}). If you try, Emacs will display an error message -saying that the maximum buffer size has been exceeded. - -@cindex wildcard characters in file names -@vindex find-file-wildcards - If the file name you specify contains shell-style wildcard -characters, Emacs visits all the files that match it. (On -case-insensitive filesystems, Emacs matches the wildcards disregarding -the letter case.) Wildcards include @samp{?}, @samp{*}, and -@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file -name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted -File Names}, for information on how to visit a file whose name -actually contains wildcard characters. You can disable the wildcard -feature by customizing @code{find-file-wildcards}. - -@cindex file selection dialog - On graphical displays, there are two additional methods for visiting -files. Firstly, when Emacs is built with a suitable GUI toolkit, -commands invoked with the mouse (by clicking on the menu bar or tool -bar) use the toolkit's standard ``File Selection'' dialog instead of -prompting for the file name in the minibuffer. On GNU/Linux and Unix -platforms, Emacs does this when built with GTK, LessTif, and Motif -toolkits; on MS-Windows and Mac, the GUI version does that by default. -For information on how to customize this, see @ref{Dialog Boxes}. - - Secondly, Emacs supports ``drag and drop'': dropping a file into an -ordinary Emacs window visits the file using that window. As an -exception, dropping a file into a window displaying a Dired buffer -moves or copies the file into the displayed directory. For details, -see @ref{Drag and Drop}, and @ref{Misc Dired Features}. - -@cindex creating files - What if you want to create a new file? Just visit it. Emacs -displays @samp{(New file)} in the echo area, but in other respects -behaves as if you had visited an existing empty file. If you make -changes and save them, the file is created. - -@cindex minibuffer confirmation -@cindex confirming in the minibuffer -@vindex confirm-nonexistent-file-or-buffer - When @key{TAB} completion results in a nonexistent file name and you -type @key{RET} immediately to visit it, Emacs asks for confirmation; -this is because it's possible that you expected completion to go -further and give you an existing file's name. The string -@samp{[Confirm]} appears for a short time after the file name to -indicate the need to confirm in this way. Type @key{RET} to confirm -and visit the nonexistent file. The variable -@code{confirm-nonexistent-file-or-buffer} controls whether Emacs asks -for confirmation before visiting a new file. The default value, -@code{after-completion}, gives the behavior we have just described. -If the value is @code{nil}, Emacs never asks for confirmation; for any -other non-@code{nil} value, Emacs always asks for confirmation. This -variable also affects the @code{switch-to-buffer} command -(@pxref{Select Buffer}). @xref{Completion}, for more information -about completion. - -@kindex C-x C-v -@findex find-alternate-file - If you visit a nonexistent file unintentionally (because you typed -the wrong file name), type @kbd{C-x C-v} (@code{find-alternate-file}) -to visit the file you really wanted. @kbd{C-x C-v} is similar to -@kbd{C-x C-f}, but it kills the current buffer (after first offering -to save it if it is modified). When @kbd{C-x C-v} reads the file name -to visit, it inserts the entire default file name in the buffer, with -point just after the directory part; this is convenient if you made a -slight error in typing the name. - -@vindex find-file-run-dired - If you ``visit'' a file that is actually a directory, Emacs invokes -Dired, the Emacs directory browser; this lets you ``edit'' the -contents of the directory. @xref{Dired}. You can disable this -behavior by setting the variable @code{find-file-run-dired} to -@code{nil}; in that case, it is an error to try to visit a directory. - - Files which are actually collections of other files, or @dfn{file -archives}, are visited in special modes which invoke a Dired-like -environment to allow operations on archive members. @xref{File -Archives}, for more about these features. - - If you visit a file that the operating system won't let you modify, -or that is marked read-only, Emacs makes the buffer read-only too, so -that you won't go ahead and make changes that you'll have trouble -saving afterward. You can make the buffer writable with @kbd{C-x C-q} -(@code{toggle-read-only}). @xref{Misc Buffer}. - -@kindex C-x C-r -@findex find-file-read-only - If you want to visit a file as read-only in order to protect -yourself from entering changes accidentally, visit it with the command -@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. - -@kindex C-x 4 f -@findex find-file-other-window - @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} -except that the buffer containing the specified file is selected in another -window. The window that was selected before @kbd{C-x 4 f} continues to -show the same buffer it was already showing. If this command is used when -only one window is being displayed, that window is split in two, with one -window showing the same buffer as before, and the other one showing the -newly requested file. @xref{Windows}. - -@kindex C-x 5 f -@findex find-file-other-frame - @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a -new frame, or makes visible any existing frame showing the file you -seek. This feature is available only when you are using a window -system. @xref{Frames}. - - Emacs recognizes from the contents of a file which end-of-line -convention it uses to separate lines---newline (used on GNU/Linux and -on Unix), carriage-return linefeed (used on Microsoft systems), or -just carriage-return (used on the Macintosh)---and automatically -converts the contents to the normal Emacs convention, which is that -the newline character separates lines. This is a part of the general -feature of coding system conversion (@pxref{Coding Systems}), and -makes it possible to edit files imported from different operating -systems with equal convenience. If you change the text and save the -file, Emacs performs the inverse conversion, changing newlines back -into carriage-return linefeed or just carriage-return if appropriate. - -@findex find-file-literally - If you wish to edit a file as a sequence of @acronym{ASCII} -characters with no special encoding or conversion, use the @kbd{M-x -find-file-literally} command. This visits a file, like @kbd{C-x C-f}, -but does not do format conversion (@pxref{Formatted Text}), character -code conversion (@pxref{Coding Systems}), or automatic uncompression -(@pxref{Compressed Files}), and does not add a final newline because -of @code{require-final-newline} (@pxref{Customize Save}). If you have -already visited the same file in the usual (non-literal) manner, this -command asks you whether to visit it literally instead. - -@vindex find-file-hook -@vindex find-file-not-found-functions - Two special hook variables allow extensions to modify the operation of -visiting files. Visiting a file that does not exist runs the functions -in the list @code{find-file-not-found-functions}; this variable holds a list -of functions, and the functions are called one by one (with no -arguments) until one of them returns non-@code{nil}. This is not a -normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} -to indicate that fact. - - Successful visiting of any file, whether existing or not, calls the -functions in the list @code{find-file-hook}, with no arguments. -This variable is a normal hook. In the case of a nonexistent file, the -@code{find-file-not-found-functions} are run first. @xref{Hooks}. - - There are several ways to specify automatically the major mode for -editing the file (@pxref{Choosing Modes}), and to specify local -variables defined for that file (@pxref{File Variables}). - -@node Saving -@section Saving Files - - @dfn{Saving} a buffer in Emacs means writing its contents back into the file -that was visited in the buffer. - -@menu -* Save Commands:: Commands for saving files. -* Backup:: How Emacs saves the old version of your file. -* Customize Save:: Customizing the saving of files. -* Interlocking:: How Emacs protects against simultaneous editing - of one file by two users. -* Shadowing: File Shadowing. Copying files to "shadows" automatically. -* Time Stamps:: Emacs can update time stamps on saved files. -@end menu - -@node Save Commands -@subsection Commands for Saving Files - - These are the commands that relate to saving and writing files. - -@table @kbd -@item C-x C-s -Save the current buffer in its visited file on disk (@code{save-buffer}). -@item C-x s -Save any or all buffers in their visited files (@code{save-some-buffers}). -@item M-~ -Forget that the current buffer has been changed (@code{not-modified}). -With prefix argument (@kbd{C-u}), mark the current buffer as changed. -@item C-x C-w -Save the current buffer with a specified file name (@code{write-file}). -@item M-x set-visited-file-name -Change the file name under which the current buffer will be saved. -@end table - -@kindex C-x C-s -@findex save-buffer - When you wish to save the file and make your changes permanent, type -@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} -displays a message like this: - -@example -Wrote /u/rms/gnu/gnu.tasks -@end example - -@noindent -If the selected buffer is not modified (no changes have been made in it -since the buffer was created or last saved), saving is not really done, -because it would have no effect. Instead, @kbd{C-x C-s} displays a message -like this in the echo area: - -@example -(No changes need to be saved) -@end example - -With a prefix argument, @kbd{C-u C-x C-s}, Emacs also marks the buffer -to be backed up when the next save is done. @xref{Backup}. - -@kindex C-x s -@findex save-some-buffers - The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any -or all modified buffers. It asks you what to do with each buffer. The -possible responses are analogous to those of @code{query-replace}: - -@table @kbd -@item y -Save this buffer and ask about the rest of the buffers. -@item n -Don't save this buffer, but ask about the rest of the buffers. -@item ! -Save this buffer and all the rest with no more questions. -@c following generates acceptable underfull hbox -@item @key{RET} -Terminate @code{save-some-buffers} without any more saving. -@item . -Save this buffer, then exit @code{save-some-buffers} without even asking -about other buffers. -@item C-r -View the buffer that you are currently being asked about. When you exit -View mode, you get back to @code{save-some-buffers}, which asks the -question again. -@item d -Diff the buffer against its corresponding file, so you can see what -changes you would be saving. This calls the command -@code{diff-buffer-with-file} (@pxref{Comparing Files}). -@item C-h -Display a help message about these options. -@end table - - @kbd{C-x C-c}, the key sequence to exit Emacs, invokes -@code{save-some-buffers} and therefore asks the same questions. - -@kindex M-~ -@findex not-modified - If you have changed a buffer but do not wish to save the changes, -you should take some action to prevent it. Otherwise, each time you -use @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer -by mistake. One thing you can do is type @kbd{M-~} -(@code{not-modified}), which clears out the indication that the buffer -is modified. If you do this, none of the save commands will believe -that the buffer needs to be saved. (@samp{~} is often used as a -mathematical symbol for `not'; thus @kbd{M-~} is `not', metafied.) -Alternatively, you can cancel all the changes made since the file was -visited or saved, by reading the text from the file again. This is -called @dfn{reverting}. @xref{Reverting}. (You could also undo all -the changes by repeating the undo command @kbd{C-x u} until you have -undone all the changes; but reverting is easier.) - -@findex set-visited-file-name - @kbd{M-x set-visited-file-name} alters the name of the file that the -current buffer is visiting. It reads the new file name using the -minibuffer. Then it marks the buffer as visiting that file name, and -changes the buffer name correspondingly. @code{set-visited-file-name} -does not save the buffer in the newly visited file; it just alters the -records inside Emacs in case you do save later. It also marks the -buffer as ``modified'' so that @kbd{C-x C-s} in that buffer -@emph{will} save. - -@kindex C-x C-w -@findex write-file - If you wish to mark the buffer as visiting a different file and save -it right away, use @kbd{C-x C-w} (@code{write-file}). This is -equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}, -except that @kbd{C-x C-w} asks for confirmation if the file exists. -@kbd{C-x C-s} used on a buffer that is not visiting a file has the -same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the -buffer as visiting that file, and saves it there. The default file -name in a buffer that is not visiting a file is made by combining the -buffer name with the buffer's default directory (@pxref{File Names}). - - If the new file name implies a major mode, then @kbd{C-x C-w} switches -to that major mode, in most cases. The command -@code{set-visited-file-name} also does this. @xref{Choosing Modes}. - - If Emacs is about to save a file and sees that the date of the latest -version on disk does not match what Emacs last read or wrote, Emacs -notifies you of this fact, because it probably indicates a problem caused -by simultaneous editing and requires your immediate attention. -@xref{Interlocking,, Simultaneous Editing}. - -@node Backup -@subsection Backup Files -@cindex backup file -@vindex make-backup-files -@vindex vc-make-backup-files - - On most operating systems, rewriting a file automatically destroys all -record of what the file used to contain. Thus, saving a file from Emacs -throws away the old contents of the file---or it would, except that -Emacs carefully copies the old contents to another file, called the -@dfn{backup} file, before actually saving. - - Emacs makes a backup for a file only the first time the file is -saved from a buffer. No matter how many times you subsequently save -the file, its backup remains unchanged. However, if you kill the -buffer and then visit the file again, a new backup file will be made. - - For most files, the variable @code{make-backup-files} determines -whether to make backup files. On most operating systems, its default -value is @code{t}, so that Emacs does write backup files. - - For files managed by a version control system (@pxref{Version -Control}), the variable @code{vc-make-backup-files} determines whether -to make backup files. By default it is @code{nil}, since backup files -are redundant when you store all the previous versions in a version -control system. -@iftex -@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{General VC Options}. -@end ifnottex - - At your option, Emacs can keep either a single backup for each file, -or make a series of numbered backup files for each file that you edit. -@xref{Backup Names}. - -@vindex backup-enable-predicate -@vindex temporary-file-directory -@vindex small-temporary-file-directory - The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories used -for temporary files, specified by @code{temporary-file-directory} or -@code{small-temporary-file-directory}. - - You can explicitly tell Emacs to make another backup file from a -buffer, even though that buffer has been saved before. If you save -the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made -into a backup file if you save the buffer again. @kbd{C-u C-u C-x -C-s} saves the buffer, but first makes the previous file contents into -a new backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it -makes a backup from the previous contents, and arranges to make -another from the newly saved contents if you save again. - -@menu -* Names: Backup Names. How backup files are named. -* Deletion: Backup Deletion. Emacs deletes excess numbered backups. -* Copying: Backup Copying. Backups can be made by copying or renaming. -@end menu - -@node Backup Names -@subsubsection Single or Numbered Backups - - When Emacs makes a backup file, its name is normally constructed by -appending @samp{~} to the file name being edited; thus, the backup -file for @file{eval.c} would be @file{eval.c~}. - - If access control stops Emacs from writing backup files under the usual -names, it writes the backup file as @file{%backup%~} in your home -directory. Only one such file can exist, so only the most recently -made such backup is available. - - Emacs can also make @dfn{numbered backup files}. Numbered backup -file names contain @samp{.~}, the number, and another @samp{~} after -the original file name. Thus, the backup files of @file{eval.c} would -be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way -through names like @file{eval.c.~259~} and beyond. - -@vindex version-control - The variable @code{version-control} determines whether to make -single backup files or multiple numbered backup files. Its possible -values are: - -@table @code -@item nil -Make numbered backups for files that have numbered backups already. -Otherwise, make single backups. This is the default. -@item t -Make numbered backups. -@item never -Never make numbered backups; always make single backups. -@end table - -@noindent -The usual way to set this variable is globally, through your -@file{.emacs} file or the customization buffer. However, you can set -@code{version-control} locally in an individual buffer to control the -making of backups for that buffer's file (@pxref{Locals}). You can -have Emacs set @code{version-control} locally whenever you visit a -given file (@pxref{File Variables}). Some modes, such as Rmail mode, -set this variable. - -@cindex @env{VERSION_CONTROL} environment variable - If you set the environment variable @env{VERSION_CONTROL}, to tell -various GNU utilities what to do with backup files, Emacs also obeys the -environment variable by setting the Lisp variable @code{version-control} -accordingly at startup. If the environment variable's value is @samp{t} -or @samp{numbered}, then @code{version-control} becomes @code{t}; if the -value is @samp{nil} or @samp{existing}, then @code{version-control} -becomes @code{nil}; if it is @samp{never} or @samp{simple}, then -@code{version-control} becomes @code{never}. - -@vindex backup-directory-alist - You can customize the variable @code{backup-directory-alist} to -specify that files matching certain patterns should be backed up in -specific directories. This variable applies to both single and -numbered backups. A typical use is to add an element @code{("." -. @var{dir})} to make all backups in the directory with absolute name -@var{dir}; Emacs modifies the backup file names to avoid clashes -between files with the same names originating in different -directories. Alternatively, adding, @code{("." . ".~")} would make -backups in the invisible subdirectory @file{.~} of the original file's -directory. Emacs creates the directory, if necessary, to make the -backup. - -@vindex make-backup-file-name-function - If you define the variable @code{make-backup-file-name-function} to -a suitable Lisp function, that overrides the usual way Emacs -constructs backup file names. - -@node Backup Deletion -@subsubsection Automatic Deletion of Backups - - To prevent excessive consumption of disk space, Emacs can delete numbered -backup versions automatically. Generally Emacs keeps the first few backups -and the latest few backups, deleting any in between. This happens every -time a new backup is made. - -@vindex kept-old-versions -@vindex kept-new-versions - The two variables @code{kept-old-versions} and -@code{kept-new-versions} control this deletion. Their values are, -respectively, the number of oldest (lowest-numbered) backups to keep -and the number of newest (highest-numbered) ones to keep, each time a -new backup is made. The backups in the middle (excluding those oldest -and newest) are the excess middle versions---those backups are -deleted. These variables' values are used when it is time to delete -excess versions, just after a new backup version is made; the newly -made backup is included in the count in @code{kept-new-versions}. By -default, both variables are 2. - -@vindex delete-old-versions - If @code{delete-old-versions} is @code{t}, Emacs deletes the excess -backup files silently. If it is @code{nil}, the default, Emacs asks -you whether it should delete the excess backup versions. If it has -any other value, then Emacs never automatically deletes backups. - - Dired's @kbd{.} (Period) command can also be used to delete old versions. -@xref{Dired Deletion}. - -@node Backup Copying -@subsubsection Copying vs.@: Renaming - - Backup files can be made by copying the old file or by renaming it. -This makes a difference when the old file has multiple names (hard -links). If the old file is renamed into the backup file, then the -alternate names become names for the backup file. If the old file is -copied instead, then the alternate names remain names for the file -that you are editing, and the contents accessed by those names will be -the new contents. - - The method of making a backup file may also affect the file's owner -and group. If copying is used, these do not change. If renaming is used, -you become the file's owner, and the file's group becomes the default -(different operating systems have different defaults for the group). - - Having the owner change is usually a good idea, because then the owner -always shows who last edited the file. Also, the owners of the backups -show who produced those versions. Occasionally there is a file whose -owner should not change; it is a good idea for such files to contain -local variable lists to set @code{backup-by-copying-when-mismatch} -locally (@pxref{File Variables}). - -@vindex backup-by-copying -@vindex backup-by-copying-when-linked -@vindex backup-by-copying-when-mismatch -@vindex backup-by-copying-when-privileged-mismatch -@cindex file ownership, and backup -@cindex backup, and user-id - The choice of renaming or copying is controlled by four variables. -Renaming is the default choice. If the variable -@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, -if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, -then copying is used for files that have multiple names, but renaming -may still be used when the file being edited has only one name. If the -variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then -copying is used if renaming would cause the file's owner or group to -change. @code{backup-by-copying-when-mismatch} is @code{t} by default -if you start Emacs as the superuser. The fourth variable, -@code{backup-by-copying-when-privileged-mismatch}, gives the highest -numeric user-id for which @code{backup-by-copying-when-mismatch} will be -forced on. This is useful when low-numbered user-ids are assigned to -special system users, such as @code{root}, @code{bin}, @code{daemon}, -etc., which must maintain ownership of files. - - When a file is managed with a version control system (@pxref{Version -Control}), Emacs does not normally make backups in the usual way for -that file. But check-in and check-out are similar in some ways to -making backups. One unfortunate similarity is that these operations -typically break hard links, disconnecting the file name you visited from -any alternate names for the same file. This has nothing to do with -Emacs---the version control system does it. - -@node Customize Save -@subsection Customizing Saving of Files - -@vindex require-final-newline - If the value of the variable @code{require-final-newline} is -@code{t}, saving or writing a file silently puts a newline at the end -if there isn't already one there. If the value is @code{visit}, Emacs -adds a newline at the end of any file that doesn't have one, just -after it visits the file. (This marks the buffer as modified, and you -can undo it.) If the value is @code{visit-save}, that means to add -newlines both on visiting and on saving. If the value is @code{nil}, -Emacs leaves the end of the file unchanged; if it's neither @code{nil} -nor @code{t}, Emacs asks you whether to add a newline. The default is -@code{nil}. - -@vindex mode-require-final-newline - Many major modes are designed for specific kinds of files that are -always supposed to end in newlines. These major modes set the -variable @code{require-final-newline} according to -@code{mode-require-final-newline}. By setting the latter variable, -you can control how these modes handle final newlines. - -@vindex write-region-inhibit-fsync - When Emacs saves a file, it invokes the @code{fsync} system call to -force the data immediately out to disk. This is important for safety -if the system crashes or in case of power outage. However, it can be -disruptive on laptops using power saving, because it requires the disk -to spin up each time you save a file. Setting -@code{write-region-inhibit-fsync} to a non-@code{nil} value disables -this synchronization. Be careful---this means increased risk of data -loss. - -@node Interlocking -@subsection Protection against Simultaneous Editing - -@cindex file dates -@cindex simultaneous editing - Simultaneous editing occurs when two users visit the same file, both -make changes, and then both save them. If nobody were informed that -this was happening, whichever user saved first would later find that his -changes were lost. - - On some systems, Emacs notices immediately when the second user starts -to change the file, and issues an immediate warning. On all systems, -Emacs checks when you save the file, and warns if you are about to -overwrite another user's changes. You can prevent loss of the other -user's work by taking the proper corrective action instead of saving the -file. - -@findex ask-user-about-lock -@cindex locking files - When you make the first modification in an Emacs buffer that is -visiting a file, Emacs records that the file is @dfn{locked} by you. -(It does this by creating a specially-named symbolic link in the same -directory.) Emacs removes the lock when you save the changes. The -idea is that the file is locked whenever an Emacs buffer visiting it -has unsaved changes. - -@cindex collision - If you begin to modify the buffer while the visited file is locked by -someone else, this constitutes a @dfn{collision}. When Emacs detects a -collision, it asks you what to do, by calling the Lisp function -@code{ask-user-about-lock}. You can redefine this function for the sake -of customization. The standard definition of this function asks you a -question and accepts three possible answers: - -@table @kbd -@item s -Steal the lock. Whoever was already changing the file loses the lock, -and you gain the lock. -@item p -Proceed. Go ahead and edit the file despite its being locked by someone else. -@item q -Quit. This causes an error (@code{file-locked}), and the buffer -contents remain unchanged---the modification you were trying to make -does not actually take place. -@end table - - Note that locking works on the basis of a file name; if a file has -multiple names, Emacs does not realize that the two names are the same file -and cannot prevent two users from editing it simultaneously under different -names. However, basing locking on names means that Emacs can interlock the -editing of new files that will not really exist until they are saved. - - Some systems are not configured to allow Emacs to make locks, and -there are cases where lock files cannot be written. In these cases, -Emacs cannot detect trouble in advance, but it still can detect the -collision when you try to save a file and overwrite someone else's -changes. Every time Emacs saves a buffer, it first checks the -last-modification date of the existing file on disk to verify that it -has not changed since the file was last visited or saved. If the date -does not match, it implies that changes were made in the file in some -other way, and these changes are about to be lost if Emacs actually -does save. To prevent this, Emacs displays a warning message and asks -for confirmation before saving. Occasionally you will know why the -file was changed and know that it does not matter; then you can answer -@kbd{yes} and proceed. Otherwise, you should cancel the save with -@kbd{C-g} and investigate the situation. - - If Emacs or the operating system crashes, this may leave behind lock -files which are stale, so you may occasionally get warnings about -spurious collisions. When you determine that the collision is spurious, -just use @kbd{p} to tell Emacs to go ahead anyway. - - The first thing you should do when notified that simultaneous editing -has already taken place is to list the directory with @kbd{C-u C-x C-d} -(@pxref{Directories}). This shows the file's current author. You -should attempt to contact him to warn him not to continue editing. -Often the next step is to save the contents of your Emacs buffer under a -different name, and use @code{diff} to compare the two files.@refill - -@node File Shadowing -@subsection Shadowing Files -@cindex shadow files -@cindex file shadows -@findex shadow-initialize - -@table @kbd -@item M-x shadow-initialize -Set up file shadowing. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. -@item M-x shadow-define-regexp-group -Make all files that match each of a group of files be shared between hosts. -@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} -Define a shadow file cluster @var{name}. -@item M-x shadow-copy-files -Copy all pending shadow files. -@item M-x shadow-cancel -Cancel the instruction to shadow some files. -@end table - -You can arrange to keep identical @dfn{shadow} copies of certain files -in more than one place---possibly on different machines. To do this, -first you must set up a @dfn{shadow file group}, which is a set of -identically-named files shared between a list of sites. The file -group is permanent and applies to further Emacs sessions as well as -the current one. Once the group is set up, every time you exit Emacs, -it will copy the file you edited to the other files in its group. You -can also do the copying without exiting Emacs, by typing @kbd{M-x -shadow-copy-files}. - -To set up a shadow file group, use @kbd{M-x -shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. -See their documentation strings for further information. - -Before copying a file to its shadows, Emacs asks for confirmation. -You can answer ``no'' to bypass copying of this file, this time. If -you want to cancel the shadowing permanently for a certain file, use -@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. - -A @dfn{shadow cluster} is a group of hosts that share directories, so -that copying to or from one of them is sufficient to update the file -on all of them. Each shadow cluster has a name, and specifies the -network address of a primary host (the one we copy files to), and a -regular expression that matches the host names of all the other hosts -in the cluster. You can define a shadow cluster with @kbd{M-x -shadow-define-cluster}. - -@node Time Stamps -@subsection Updating Time Stamps Automatically -@cindex time stamps -@cindex modification dates -@cindex locale, date format - -You can arrange to put a time stamp in a file, so that it will be updated -automatically each time you edit and save the file. The time stamp -has to be in the first eight lines of the file, and you should -insert it like this: - -@example -Time-stamp: <> -@end example - -@noindent -or like this: - -@example -Time-stamp: " " -@end example - -@findex time-stamp - Then add the hook function @code{time-stamp} to the hook -@code{before-save-hook}; that hook function will automatically update -the time stamp, inserting the current date and time when you save the -file. You can also use the command @kbd{M-x time-stamp} to update the -time stamp manually. For other customizations, see the Custom group -@code{time-stamp}. Note that non-numeric fields in the time stamp are -formatted according to your locale setting (@pxref{Environment}). - -@node Reverting -@section Reverting a Buffer -@findex revert-buffer -@cindex drastic changes -@cindex reread a file - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file. To do this, use @kbd{M-x revert-buffer}, which operates on -the current buffer. Since reverting a buffer unintentionally could lose -a lot of work, you must confirm this command with @kbd{yes}. - - @code{revert-buffer} tries to position point in such a way that, if -the file was edited only slightly, you will be at approximately the -same piece of text after reverting as before. However, if you have made -drastic changes, point may wind up in a totally different piece of text. - - Reverting marks the buffer as ``not modified''. - - Some kinds of buffers that are not associated with files, such as -Dired buffers, can also be reverted. For them, reverting means -recalculating their contents. Buffers created explicitly with -@kbd{C-x b} cannot be reverted; @code{revert-buffer} reports an error -if you try. - -@vindex revert-without-query - When you edit a file that changes automatically and frequently---for -example, a log of output from a process that continues to run---it may -be useful for Emacs to revert the file without querying you. To -request this behavior, set the variable @code{revert-without-query} to -a list of regular expressions. When a file name matches one of these -regular expressions, @code{find-file} and @code{revert-buffer} will -revert it automatically if it has changed---provided the buffer itself -is not modified. (If you have edited the text, it would be wrong to -discard your changes.) - -@cindex Global Auto-Revert mode -@cindex mode, Global Auto-Revert -@cindex Auto-Revert mode -@cindex mode, Auto-Revert -@findex global-auto-revert-mode -@findex auto-revert-mode -@findex auto-revert-tail-mode -@vindex auto-revert-interval - - In addition, you can tell Emacs to periodically revert a buffer by -typing @kbd{M-x auto-revert-mode}. This turns on Auto-Revert mode, a -minor mode that makes Emacs automatically revert the current buffer -every five seconds. You can change this interval through the variable -@code{auto-revert-interval}. Typing @kbd{M-x global-auto-revert-mode} -enables Global Auto-Revert mode, which does the same for all file -buffers. Auto-Revert mode and Global Auto-Revert modes do not check -or revert remote files, because that is usually too slow. - - One use of Auto-Revert mode is to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. - - @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that -visit files under version control. - -@ifnottex -@include arevert-xtra.texi -@end ifnottex - -@node Auto Save -@section Auto-Saving: Protection Against Disasters -@cindex Auto Save mode -@cindex mode, Auto Save -@cindex crashes - - From time to time, Emacs automatically saves each visited file in a -separate file, without altering the file you actually use. This is -called @dfn{auto-saving}. It prevents you from losing more than a -limited amount of work if the system crashes. - - When Emacs determines that it is time for auto-saving, it considers -each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. - -@menu -* Files: Auto Save Files. The file where auto-saved changes are - actually made until you save the file. -* Control: Auto Save Control. Controlling when and how often to auto-save. -* Recover:: Recovering text from auto-save files. -@end menu - -@node Auto Save Files -@subsection Auto-Save Files - - Auto-saving does not normally save in the files that you visited, -because it can be very undesirable to save a change that you did not -want to make permanent. Instead, auto-saving is done in a different -file called the @dfn{auto-save file}, and the visited file is changed -only when you request saving explicitly (such as with @kbd{C-x C-s}). - - Normally, the auto-save file name is made by appending @samp{#} to the -front and rear of the visited file name. Thus, a buffer visiting file -@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that -are not visiting files are auto-saved only if you request it explicitly; -when they are auto-saved, the auto-save file name is made by appending -@samp{#} to the front and rear of buffer name, then -adding digits and letters at the end for uniqueness. For -example, the @samp{*mail*} buffer in which you compose messages to be -sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file -names are made this way unless you reprogram parts of Emacs to do -something different (the functions @code{make-auto-save-file-name} and -@code{auto-save-file-name-p}). The file name to be used for auto-saving -in a buffer is calculated when auto-saving is turned on in that buffer. - -@cindex auto-save for remote files -@vindex auto-save-file-name-transforms - The variable @code{auto-save-file-name-transforms} allows a degree -of control over the auto-save file name. It lets you specify a series -of regular expressions and replacements to transform the auto save -file name. The default value puts the auto-save files for remote -files (@pxref{Remote Files}) into the temporary file directory on the -local machine. - - When you delete a substantial part of the text in a large buffer, auto -save turns off temporarily in that buffer. This is because if you -deleted the text unintentionally, you might find the auto-save file more -useful if it contains the deleted text. To reenable auto-saving after -this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x -auto-save-mode}. - -@vindex auto-save-visited-file-name - If you want auto-saving to be done in the visited file rather than -in a separate auto-save file, set the variable -@code{auto-save-visited-file-name} to a non-@code{nil} value. In this -mode, there is no real difference between auto-saving and explicit -saving. - -@vindex delete-auto-save-files - A buffer's auto-save file is deleted when you save the buffer in its -visited file. (You can inhibit this by setting the variable -@code{delete-auto-save-files} to @code{nil}.) Changing the visited -file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames -any auto-save file to go with the new visited name. - -@node Auto Save Control -@subsection Controlling Auto-Saving - -@vindex auto-save-default -@findex auto-save-mode - Each time you visit a file, auto-saving is turned on for that file's -buffer if the variable @code{auto-save-default} is non-@code{nil} (but not -in batch mode; @pxref{Entering Emacs}). The default for this variable is -@code{t}, so auto-saving is the usual practice for file-visiting buffers. -Auto-saving can be turned on or off for any existing buffer with the -command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x -auto-save-mode} turns auto-saving on with a positive argument, off with a -zero or negative argument; with no argument, it toggles. - -@vindex auto-save-interval - Emacs does auto-saving periodically based on counting how many characters -you have typed since the last time auto-saving was done. The variable -@code{auto-save-interval} specifies how many characters there are between -auto-saves. By default, it is 300. Emacs doesn't accept values that are -too small: if you customize @code{auto-save-interval} to a value less -than 20, Emacs will behave as if the value is 20. - -@vindex auto-save-timeout - Auto-saving also takes place when you stop typing for a while. The -variable @code{auto-save-timeout} says how many seconds Emacs should -wait before it does an auto save (and perhaps also a garbage -collection). (The actual time period is longer if the current buffer is -long; this is a heuristic which aims to keep out of your way when you -are editing long buffers, in which auto-save takes an appreciable amount -of time.) Auto-saving during idle periods accomplishes two things: -first, it makes sure all your work is saved if you go away from the -terminal for a while; second, it may avoid some auto-saving while you -are actually typing. - - Emacs also does auto-saving whenever it gets a fatal error. This -includes killing the Emacs job with a shell command such as @samp{kill -%emacs}, or disconnecting a phone line or network connection. - -@findex do-auto-save - You can request an auto-save explicitly with the command @kbd{M-x -do-auto-save}. - -@node Recover -@subsection Recovering Data from Auto-Saves - -@findex recover-file - You can use the contents of an auto-save file to recover from a loss -of data with the command @kbd{M-x recover-file @key{RET} @var{file} -@key{RET}}. This visits @var{file} and then (after your confirmation) -restores the contents from its auto-save file @file{#@var{file}#}. -You can then save with @kbd{C-x C-s} to put the recovered text into -@var{file} itself. For example, to recover file @file{foo.c} from its -auto-save file @file{#foo.c#}, do:@refill - -@example -M-x recover-file @key{RET} foo.c @key{RET} -yes @key{RET} -C-x C-s -@end example - - Before asking for confirmation, @kbd{M-x recover-file} displays a -directory listing describing the specified file and the auto-save file, -so you can compare their sizes and dates. If the auto-save file -is older, @kbd{M-x recover-file} does not offer to read it. - -@findex recover-session - If Emacs or the computer crashes, you can recover all the files you -were editing from their auto save files with the command @kbd{M-x -recover-session}. This first shows you a list of recorded interrupted -sessions. Move point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} asks about each of the files that were -being edited during that session, asking whether to recover that file. -If you answer @kbd{y}, it calls @code{recover-file}, which works in its -normal fashion. It shows the dates of the original file and its -auto-save file, and asks once again whether to recover that file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - -@vindex auto-save-list-file-prefix - Emacs records information about interrupted sessions for later -recovery in files named -@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The -directory used, @file{~/.emacs.d/auto-save-list/}, is determined by -the variable @code{auto-save-list-file-prefix}. You can record -sessions in a different place by customizing that variable. If you -set @code{auto-save-list-file-prefix} to @code{nil} in your -@file{.emacs} file, sessions are not recorded for recovery. - -@node File Aliases -@section File Name Aliases -@cindex symbolic links (visiting) -@cindex hard links (visiting) - - Symbolic links and hard links both make it possible for several file -names to refer to the same file. Hard links are alternate names that -refer directly to the file; all the names are equally valid, and no one -of them is preferred. By contrast, a symbolic link is a kind of defined -alias: when @file{foo} is a symbolic link to @file{bar}, you can use -either name to refer to the file, but @file{bar} is the real name, while -@file{foo} is just an alias. More complex cases occur when symbolic -links point to directories. - -@vindex find-file-existing-other-name -@vindex find-file-suppress-same-file-warnings - - Normally, if you visit a file which Emacs is already visiting under -a different name, Emacs displays a message in the echo area and uses -the existing buffer visiting that file. This can happen on systems -that support hard or symbolic links, or if you use a long file name on -a system that truncates long file names, or on a case-insensitive file -system. You can suppress the message by setting the variable -@code{find-file-suppress-same-file-warnings} to a non-@code{nil} -value. You can disable this feature entirely by setting the variable -@code{find-file-existing-other-name} to @code{nil}: then if you visit -the same file under two different names, you get a separate buffer for -each file name. - -@vindex find-file-visit-truename -@cindex truenames of files -@cindex file truenames - If the variable @code{find-file-visit-truename} is non-@code{nil}, -then the file name recorded for a buffer is the file's @dfn{truename} -(made by replacing all symbolic links with their target names), rather -than the name you specify. Setting @code{find-file-visit-truename} also -implies the effect of @code{find-file-existing-other-name}. - -@node Directories -@section File Directories - -@cindex file directory -@cindex directory listing - The file system groups files into @dfn{directories}. A @dfn{directory -listing} is a list of all the files in a directory. Emacs provides -commands to create and delete directories, and to make directory -listings in brief format (file names only) and verbose format (sizes, -dates, and authors included). Emacs also includes a directory browser -feature called Dired; see @ref{Dired}. - -@table @kbd -@item C-x C-d @var{dir-or-pattern} @key{RET} -Display a brief directory listing (@code{list-directory}). -@item C-u C-x C-d @var{dir-or-pattern} @key{RET} -Display a verbose directory listing. -@item M-x make-directory @key{RET} @var{dirname} @key{RET} -Create a new directory named @var{dirname}. -@item M-x delete-directory @key{RET} @var{dirname} @key{RET} -Delete the directory named @var{dirname}. It must be empty, -or you get an error. -@end table - -@findex list-directory -@kindex C-x C-d - The command to display a directory listing is @kbd{C-x C-d} -(@code{list-directory}). It reads using the minibuffer a file name -which is either a directory to be listed or a wildcard-containing -pattern for the files to be listed. For example, - -@example -C-x C-d /u2/emacs/etc @key{RET} -@end example - -@noindent -lists all the files in directory @file{/u2/emacs/etc}. Here is an -example of specifying a file name pattern: - -@example -C-x C-d /u2/emacs/src/*.c @key{RET} -@end example - - Normally, @kbd{C-x C-d} displays a brief directory listing containing -just file names. A numeric argument (regardless of value) tells it to -make a verbose listing including sizes, dates, and owners (like -@samp{ls -l}). - -@vindex list-directory-brief-switches -@vindex list-directory-verbose-switches - The text of a directory listing is mostly obtained by running -@code{ls} in an inferior process. Two Emacs variables control the -switches passed to @code{ls}: @code{list-directory-brief-switches} is -a string giving the switches to use in brief listings (@code{"-CF"} by -default), and @code{list-directory-verbose-switches} is a string -giving the switches to use in a verbose listing (@code{"-l"} by -default). - -@vindex directory-free-space-program -@vindex directory-free-space-args - In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. To do -this, it runs the program specified by -@code{directory-free-space-program} with arguments -@code{directory-free-space-args}. - - The command @kbd{M-x delete-directory} prompts for a directory name -using the minibuffer, and deletes the directory if it is empty. If -the directory is not empty, this signals an error. On systems that -have a ``Trash'' or ``Recycle Bin'' feature, you can make this command -move the specified directory to the Trash or Recycle Bin, instead of -deleting it outright, by changing the variable -@code{delete-by-moving-to-trash} to @code{t}. @xref{Misc File Ops}, -for more information about using the Trash. - -@node Comparing Files -@section Comparing Files -@cindex comparing files - -@findex diff -@vindex diff-switches - The command @kbd{M-x diff} prompts for two file names, using the -minibuffer, and displays the differences between the two files in a -buffer named @samp{*diff*}. This works by running the @command{diff} -program, using options taken from the variable @code{diff-switches}. -The value of @code{diff-switches} should be a string; the default is -@code{"-c"} to specify a context diff. @xref{Top,, Diff, diff, -Comparing and Merging Files}, for more information about -@command{diff} output formats. - - The output of the @code{diff} command is shown using a major mode -called Diff mode. @xref{Diff Mode}. - -@findex diff-backup - The command @kbd{M-x diff-backup} compares a specified file with its -most recent backup. If you specify the name of a backup file, -@code{diff-backup} compares it with the source file that it is a -backup of. In all other respects, this behaves like @kbd{M-x diff}. - -@findex diff-buffer-with-file - The command @kbd{M-x diff-buffer-with-file} compares a specified -buffer with its corresponding file. This shows you what changes you -would make to the file if you save the buffer. - -@findex compare-windows - The command @kbd{M-x compare-windows} compares the text in the -current window with that in the next window. (For more information -about windows in Emacs, @ref{Windows}.) Comparison starts at point in -each window, after pushing each initial point value on the mark ring -in its respective buffer. Then it moves point forward in each window, -one character at a time, until it reaches characters that don't match. -Then the command exits. - - If point in the two windows is followed by non-matching text when -the command starts, @kbd{M-x compare-windows} tries heuristically to -advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. - -@vindex compare-ignore-case -@vindex compare-ignore-whitespace - With a numeric argument, @code{compare-windows} ignores changes in -whitespace. If the variable @code{compare-ignore-case} is -non-@code{nil}, the comparison ignores differences in case as well. -If the variable @code{compare-ignore-whitespace} is non-@code{nil}, -@code{compare-windows} normally ignores changes in whitespace, and a -prefix argument turns that off. - -@cindex Smerge mode -@findex smerge-mode -@cindex failed merges -@cindex merges, failed -@cindex comparing 3 files (@code{diff3}) - You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor -mode for editing output from the @command{diff3} program. This is -typically the result of a failed merge from a version control system -``update'' outside VC, due to conflicting changes to a file. Smerge -mode provides commands to resolve conflicts by selecting specific -changes. - -@iftex -@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Emerge}, -@end ifnottex -for the Emerge facility, which provides a powerful interface for -merging files. - -@node Diff Mode -@section Diff Mode -@cindex Diff mode -@findex diff-mode -@cindex patches, editing - - Diff mode is a major mode used for the output of @kbd{M-x diff} and -other similar commands, as well as the output of the @command{diff} -program. This kind of output is called a @dfn{patch}, because it can -be passed to the @command{patch} command to automatically apply the -specified changes. To select Diff mode manually, type @kbd{M-x -diff-mode}. - -@cindex hunk, diff - The changes specified in a patch are grouped into @dfn{hunks}, which -are contiguous chunks of text that contain one or more changed lines. -Hunks can also include unchanged lines to provide context for the -changes. Each hunk is preceded by a @dfn{hunk header}, which -specifies the old and new line numbers at which the hunk occurs. Diff -mode highlights each hunk header, to distinguish it from the actual -contents of the hunk. - -@vindex diff-update-on-the-fly - You can edit a Diff mode buffer like any other buffer. (If it is -read-only, you need to make it writable first. @xref{Misc Buffer}.) -Whenever you change a hunk, Diff mode attempts to automatically -correct the line numbers in the hunk headers, to ensure that the diff -remains ``correct''. To disable automatic line number correction, -change the variable @code{diff-update-on-the-fly} to @code{nil}. - - Diff mode treats each hunk as an ``error message,'' similar to -Compilation mode. Thus, you can use commands such as @kbd{C-x '} to -visit the corresponding source locations. @xref{Compilation Mode}. - - In addition, Diff mode provides the following commands to navigate, -manipulate and apply parts of patches: - -@table @kbd -@item M-n -@findex diff-hunk-next -Move to the next hunk-start (@code{diff-hunk-next}). - -@item M-p -@findex diff-hunk-prev -Move to the previous hunk-start (@code{diff-hunk-prev}). - -@item M-@} -@findex diff-file-next -Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). - -@item M-@{ -@findex diff-file-prev -Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). - -@item M-k -@findex diff-hunk-kill -Kill the hunk at point (@code{diff-hunk-kill}). - -@item M-K -@findex diff-file-kill -In a multi-file patch, kill the current file part. -(@code{diff-file-kill}). - -@item C-c C-a -@findex diff-apply-hunk -Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. - -@item C-c C-b -@findex diff-refine-hunk -Highlight the changes of the hunk at point with a finer granularity -(@code{diff-refine-hunk}). This allows you to see exactly which parts -of each changed line were actually changed. - -@item C-c C-c -@findex diff-goto-source -Go to the source file and line corresponding to this hunk -(@code{diff-goto-source}). - -@item C-c C-e -@findex diff-ediff-patch -Start an Ediff session with the patch (@code{diff-ediff-patch}). -@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. - -@item C-c C-n -@findex diff-restrict-view -Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the -view to the current file of a multiple-file patch. To widen again, -use @kbd{C-x n w} (@code{widen}). - -@item C-c C-r -@findex diff-reverse-direction -Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). - -@item C-c C-s -@findex diff-split-hunk -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the @dfn{unified diff -format} produced by the @option{-u} or @option{--unified} options to -the @command{diff} program. If you need to split a hunk in the -@dfn{context diff format} produced by the @option{-c} or -@option{--context} options to @command{diff}, first convert the buffer -to the unified diff format with @kbd{C-c C-u}. - -@item C-c C-d -@findex diff-unified->context -Convert the entire buffer to the @dfn{context diff format} -(@code{diff-unified->context}). With a prefix argument, convert only -the text within the region. - -@item C-c C-u -@findex diff-context->unified -Convert the entire buffer to unified diff format -(@code{diff-context->unified}). With a prefix argument, convert -unified format to context format. When the mark is active, convert -only the text within the region. - -@item C-c C-w -@findex diff-refine-hunk -Refine the current hunk so that it disregards changes in whitespace -(@code{diff-refine-hunk}). - -@item C-x 4 A -@findex diff-add-change-log-entries-other-window -@findex add-change-log-entry-other-window@r{, in Diff mode} -Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change -Log}), for each one of the hunks -(@code{diff-add-change-log-entries-other-window}). This creates a -skeleton of the log of changes that you can later fill with the actual -descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode -operates on behalf of the current hunk's file, but gets the function -name from the patch itself. This is useful for making log entries for -functions that are deleted by the patch. - -@item M-x diff-show-trailing-whitespaces RET -@findex diff-show-trailing-whitespaces -Highlight trailing whitespace characters, except for those used by the -patch syntax (@pxref{Useless Whitespace}). -@end table - - -@node Misc File Ops -@section Miscellaneous File Operations - - Emacs has commands for performing many other operations on files. -All operate on one file; they do not accept wildcard file names. - -@findex view-file -@cindex viewing -@cindex View mode -@cindex mode, View - @kbd{M-x view-file} allows you to scan or read a file by sequential -screenfuls. It reads a file name argument using the minibuffer. After -reading the file into an Emacs buffer, @code{view-file} displays the -beginning. You can then type @key{SPC} to scroll forward one windowful, -or @key{DEL} to scroll backward. Various other commands are provided -for moving around in the file, but none for changing it; type @kbd{?} -while viewing for a list of them. They are mostly the same as normal -Emacs cursor motion commands. To exit from viewing, type @kbd{q}. -The commands for viewing are defined by a special minor mode called View -mode. - - A related command, @kbd{M-x view-buffer}, views a buffer already present -in Emacs. @xref{Misc Buffer}. - -@kindex C-x i -@findex insert-file - @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the -contents of the specified file into the current buffer at point, -leaving point unchanged before the contents. The position after the -inserted contents is added to the mark ring, without activating the -mark (@pxref{Mark Ring}). - -@findex insert-file-literally - @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, -except the file is inserted ``literally'': it is treated as a sequence -of @acronym{ASCII} characters with no special encoding or conversion, -similar to the @kbd{M-x find-file-literally} command -(@pxref{Visiting}). - -@findex write-region - @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it -copies the contents of the region into the specified file. @kbd{M-x -append-to-file} adds the text of the region to the end of the -specified file. @xref{Accumulating Text}. The variable -@code{write-region-inhibit-fsync} applies to these commands, as well -as saving files; see @ref{Customize Save}. - -@findex delete-file -@cindex deletion (of files) -@vindex delete-by-moving-to-trash - @kbd{M-x delete-file} deletes the specified file, like the @code{rm} -command in the shell. If you are deleting many files in one -directory, it may be more convenient to use Dired rather than -@code{delete-file}. @xref{Dired}. - -@cindex trash -@cindex recycle bin - On some systems, there is a facility called the ``Trash'' (or -``Recycle Bin''); ``deleting'' a file normally means moving it into -the Trash, and you can bring the file back from the Trash if you later -change your mind. By default, Emacs does @emph{not} use the Trash for -file deletion---when Emacs deletes a file, it is gone forever. You -can tell Emacs to use the Trash by changing the variable -@code{delete-by-moving-to-trash} to @code{t}. This applies to file -deletion via @kbd{M-x delete-file}, as well as @kbd{M-x -delete-directory} (@pxref{Directories}) and file deletion in Dired -(@pxref{Dired Deletion}). In addition, you can explicitly move a file -into the Trash with the command @kbd{M-x move-file-to-trash}. - -@findex rename-file - @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using -the minibuffer, then renames file @var{old} as @var{new}. If the file name -@var{new} already exists, you must confirm with @kbd{yes} or renaming is not -done; this is because renaming causes the old meaning of the name @var{new} -to be lost. If @var{old} and @var{new} are on different file systems, the -file @var{old} is copied and deleted. - - If the argument @var{new} is just a directory name, the real new -name is in that directory, with the same non-directory component as -@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} -renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all -the remaining commands in this section. All of them ask for -confirmation when the new file name already exists, too. - -@findex add-name-to-file -@cindex hard links (creation) - The similar command @kbd{M-x add-name-to-file} is used to add an -additional name to an existing file without removing its old name. -The new name is created as a ``hard link'' to the existing file. -The new name must belong on the same file system that the file is on. -On MS-Windows, this command works only if the file resides in an NTFS -file system. On MS-DOS, it works by copying the file. - -@findex copy-file -@cindex copying files - @kbd{M-x copy-file} reads the file @var{old} and writes a new file -named @var{new} with the same contents. - -@findex make-symbolic-link -@cindex symbolic links (creation) - @kbd{M-x make-symbolic-link} reads two file names @var{target} and -@var{linkname}, then creates a symbolic link named @var{linkname}, -which points at @var{target}. The effect is that future attempts to -open file @var{linkname} will refer to whatever file is named -@var{target} at the time the opening is done, or will get an error if -the name @var{target} is nonexistent at that time. This command does -not expand the argument @var{target}, so that it allows you to specify -a relative name as the target of the link. - - Not all systems support symbolic links; on systems that don't -support them, this command is not defined. - -@findex set-file-modes -@cindex file modes -@cindex file permissions - @kbd{M-x set-file-modes} reads a file name followed by a @dfn{file -mode}, and applies that file mode to the specified file. File modes, -also called @dfn{file permissions}, determine whether a file can be -read, written to, or executed, and by whom. This command reads file -modes using the same symbolic or octal format accepted by the -@command{chmod} command; for instance, @samp{u+x} means to add -execution permission for the user who owns the file. It has no effect -on operating systems that do not support file modes. @code{chmod} is a -convenience alias for this function. - -@node Compressed Files -@section Accessing Compressed Files -@cindex compression -@cindex uncompression -@cindex Auto Compression mode -@cindex mode, Auto Compression -@pindex gzip - - Emacs automatically uncompresses compressed files when you visit -them, and automatically recompresses them if you alter them and save -them. Emacs recognizes compressed files by their file names. File -names ending in @samp{.gz} indicate a file compressed with -@code{gzip}. Other endings indicate other compression programs. - - Automatic uncompression and compression apply to all the operations in -which Emacs uses the contents of a file. This includes visiting it, -saving it, inserting its contents into a buffer, loading it, and byte -compiling it. - -@findex auto-compression-mode -@vindex auto-compression-mode - To disable this feature, type the command @kbd{M-x -auto-compression-mode}. You can disable it permanently by -customizing the variable @code{auto-compression-mode}. - -@node File Archives -@section File Archives -@cindex mode, tar -@cindex Tar mode -@cindex file archives - - A file whose name ends in @samp{.tar} is normally an @dfn{archive} -made by the @code{tar} program. Emacs views these files in a special -mode called Tar mode which provides a Dired-like list of the contents -(@pxref{Dired}). You can move around through the list just as you -would in Dired, and visit the subfiles contained in the archive. -However, not all Dired commands are available in Tar mode. - - If Auto Compression mode is enabled (@pxref{Compressed Files}), then -Tar mode is used also for compressed archives---files with extensions -@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file -into its own buffer. You can edit it there, and if you save the -buffer, the edited version will replace the version in the Tar buffer. -@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts -the file and displays it in another window, so you could edit the file -and operate on the archive simultaneously. @kbd{d} marks a file for -deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in -Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} -renames a file within the archive. @kbd{g} reverts the buffer from -the archive on disk. - - The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission -bits, group, and owner, respectively. - - If your display supports colors and the mouse, moving the mouse -pointer across a file name highlights that file name, indicating that -you can click on it. Clicking @kbd{Mouse-2} on the highlighted file -name extracts the file into a buffer and displays that buffer. - - Saving the Tar buffer writes a new version of the archive to disk with -the changes you made to the components. - - You don't need the @code{tar} program to use Tar mode---Emacs reads -the archives directly. However, accessing compressed archives -requires the appropriate uncompression program. - -@cindex Archive mode -@cindex mode, archive -@cindex @code{arc} -@cindex @code{jar} -@cindex @code{rar} -@cindex @code{zip} -@cindex @code{lzh} -@cindex @code{zoo} -@pindex arc -@pindex jar -@pindex zip -@pindex rar -@pindex lzh -@pindex zoo -@cindex Java class archives -@cindex unzip archives - A separate but similar Archive mode is used for archives produced by -the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, -@code{rar}, and @code{zoo}, which have extensions corresponding to the -program names. Archive mode also works for those @code{exe} files -that are self-extracting executables. - - The key bindings of Archive mode are similar to those in Tar mode, -with the addition of the @kbd{m} key which marks a file for subsequent -operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of detailed file -information, for those archive types where it won't fit in a single -line. Operations such as renaming a subfile, or changing its mode or -owner, are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the archiving program to unpack -and repack archives. Details of the program names and their options -can be set in the @samp{Archive} Customize group. However, you don't -need these programs to look at the archive table of contents, only to -extract or manipulate the subfiles in the archive. - -@node Remote Files -@section Remote Files - -@cindex Tramp -@cindex FTP -@cindex remote file access - You can refer to files on other machines using a special file name -syntax: - -@example -@group -/@var{host}:@var{filename} -/@var{user}@@@var{host}:@var{filename} -/@var{user}@@@var{host}#@var{port}:@var{filename} -/@var{method}:@var{user}@@@var{host}:@var{filename} -/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} -@end group -@end example - -@noindent -To carry out this request, Emacs uses a remote-login program such as -@command{ftp}, @command{ssh}, @command{rlogin}, or @command{telnet}. -You can always specify in the file name which method to use---for -example, @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, -whereas @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses -@command{ssh}. When you don't specify a method in the file name, -Emacs chooses the method as follows: - -@enumerate -@item -If the host name starts with @samp{ftp.} (with dot), then Emacs uses -FTP. -@item -If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses -FTP. -@item -If the variable @code{tramp-default-method} is set to @samp{ftp}, -then Emacs uses FTP. -@item -If @command{ssh-agent} is running, then Emacs uses @command{scp}. -@item -Otherwise, Emacs uses @command{ssh}. -@end enumerate - -@cindex disabling remote files -@noindent -You can entirely turn off the remote file name feature by setting the -variable @code{tramp-mode} to @code{nil}. You can turn off the -feature in individual cases by quoting the file name with @samp{/:} -(@pxref{Quoted File Names}). - - Remote file access through FTP is handled by the Ange-FTP package, which -is documented in the following. Remote file access through the other -methods is handled by the Tramp package, which has its own manual. -@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. - -When the Ange-FTP package is used, Emacs logs in through FTP using -your user name or the name @var{user}. It may ask you for a password -from time to time (@pxref{Passwords}); this is used for logging in on -@var{host}. The form using @var{port} allows you to access servers -running on a non-default TCP port. - -@cindex backups for remote files -@vindex ange-ftp-make-backup-files - If you want to disable backups for remote files, set the variable -@code{ange-ftp-make-backup-files} to @code{nil}. - - By default, the auto-save files (@pxref{Auto Save Files}) for remote -files are made in the temporary file directory on the local machine. -This is achieved using the variable @code{auto-save-file-name-transforms}. - -@cindex ange-ftp -@vindex ange-ftp-default-user -@cindex user name for remote file access - Normally, if you do not specify a user name in a remote file name, -that means to use your own user name. But if you set the variable -@code{ange-ftp-default-user} to a string, that string is used instead. - -@cindex anonymous FTP -@vindex ange-ftp-generate-anonymous-password - To visit files accessible by anonymous FTP, you use special user -names @samp{anonymous} or @samp{ftp}. Passwords for these user names -are handled specially. The variable -@code{ange-ftp-generate-anonymous-password} controls what happens: if -the value of this variable is a string, then that string is used as -the password; if non-@code{nil} (the default), then the value of -@code{user-mail-address} is used; if @code{nil}, then Emacs prompts -you for a password as usual (@pxref{Passwords}). - -@cindex firewall, and accessing remote files -@cindex gateway, and remote file access with @code{ange-ftp} -@vindex ange-ftp-smart-gateway -@vindex ange-ftp-gateway-host - Sometimes you may be unable to access files on a remote machine -because a @dfn{firewall} in between blocks the connection for security -reasons. If you can log in on a @dfn{gateway} machine from which the -target files @emph{are} accessible, and whose FTP server supports -gatewaying features, you can still use remote file names; all you have -to do is specify the name of the gateway machine by setting the -variable @code{ange-ftp-gateway-host}, and set -@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able -to make remote file names work, but the procedure is complex. You can -read the instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. - -@node Quoted File Names -@section Quoted File Names - -@cindex quoting file names -@cindex file names, quote special characters - You can @dfn{quote} an absolute file name to prevent special -characters and syntax in it from having their special effects. -The way to do this is to add @samp{/:} at the beginning. - - For example, you can quote a local file name which appears remote, to -prevent it from being treated as a remote file name. Thus, if you have -a directory named @file{/foo:} and a file named @file{bar} in it, you -can refer to that file in Emacs as @samp{/:/foo:/bar}. - - @samp{/:} can also prevent @samp{~} from being treated as a special -character for a user's home directory. For example, @file{/:/tmp/~hack} -refers to a file whose name is @file{~hack} in directory @file{/tmp}. - - Quoting with @samp{/:} is also a way to enter in the minibuffer a -file name that contains @samp{$}. In order for this to work, the -@samp{/:} must be at the beginning of the minibuffer contents. (You -can also double each @samp{$}; see @ref{File Names with $}.) - - You can also quote wildcard characters with @samp{/:}, for visiting. -For example, @file{/:/tmp/foo*bar} visits the file -@file{/tmp/foo*bar}. - - Another method of getting the same result is to enter -@file{/tmp/foo[*]bar}, which is a wildcard specification that matches -only @file{/tmp/foo*bar}. However, in many cases there is no need to -quote the wildcard characters because even unquoted they give the -right result. For example, if the only file name in @file{/tmp} that -starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, -then specifying @file{/tmp/foo*bar} will visit only -@file{/tmp/foo*bar}. - -@node File Name Cache -@section File Name Cache - -@cindex file name caching -@cindex cache of file names -@pindex find -@kindex C-@key{TAB} -@findex file-cache-minibuffer-complete - You can use the @dfn{file name cache} to make it easy to locate a -file by name, without having to remember exactly where it is located. -When typing a file name in the minibuffer, @kbd{C-@key{tab}} -(@code{file-cache-minibuffer-complete}) completes it using the file -name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the -possible completions of what you had originally typed. (However, note -that the @kbd{C-@key{tab}} character cannot be typed on most text-only -terminals.) - - The file name cache does not fill up automatically. Instead, you -load file names into the cache using these commands: - -@findex file-cache-add-directory -@table @kbd -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} to the file name cache. -@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache. -@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} -Add each file name in @var{directory} and all of its nested -subdirectories to the file name cache, using @command{locate} to find -them all. -@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} -Add each file name in each directory listed in @var{variable} -to the file name cache. @var{variable} should be a Lisp variable -such as @code{load-path} or @code{exec-path}, whose value is a list -of directory names. -@item M-x file-cache-clear-cache @key{RET} -Clear the cache; that is, remove all file names from it. -@end table - - The file name cache is not persistent: it is kept and maintained -only for the duration of the Emacs session. You can view the contents -of the cache with the @code{file-cache-display} command. - -@node File Conveniences -@section Convenience Features for Finding Files - - In this section, we introduce some convenient facilities for finding -recently-opened files, reading file names from a buffer, and viewing -image files. - -@findex recentf-mode -@vindex recentf-mode -@findex recentf-save-list -@findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} -edits it. - - The @kbd{M-x ffap} command generalizes @code{find-file} with more -powerful heuristic defaults (@pxref{FFAP}), often based on the text at -point. Partial Completion mode offers other features extending -@code{find-file}, which can be used with @code{ffap}. -@xref{Completion Options}. - -@findex image-mode -@findex image-toggle-display -@cindex images, viewing - Visiting image files automatically selects Image mode. This major -mode allows you to toggle between displaying the file as an image in -the Emacs buffer, and displaying its underlying text representation, -using the command @kbd{C-c C-c} (@code{image-toggle-display}). This -works only when Emacs can display the specific image type. If the -displayed image is wider or taller than the frame, the usual point -motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts -of the image to be displayed. - -@findex thumbs-mode -@findex mode, thumbs - See also the Image-Dired package (@pxref{Image-Dired}) for viewing -images as thumbnails. - -@node Filesets -@section Filesets -@cindex filesets - -@findex filesets-init - If you regularly edit a certain group of files, you can define them -as a @dfn{fileset}. This lets you perform certain operations, such as -visiting, @code{query-replace}, and shell commands on all the files -at once. To make use of filesets, you must first add the expression -@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). -This adds a @samp{Filesets} menu to the menu bar. - -@findex filesets-add-buffer -@findex filesets-remove-buffer - The simplest way to define a fileset is by adding files to it one -at a time. To add a file to fileset @var{name}, visit the file and -type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If -there is no fileset @var{name}, this creates a new one, which -initially creates only the current file. The command @kbd{M-x -filesets-remove-buffer} removes the current file from a fileset. - - You can also edit the list of filesets directly, with @kbd{M-x -filesets-edit} (or by choosing @samp{Edit Filesets} from the -@samp{Filesets} menu). The editing is performed in a Customize buffer -(@pxref{Easy Customization}). Filesets need not be a simple list of -files---you can also define filesets using regular expression matching -file names. Some examples of these more complicated filesets are -shown in the Customize buffer. Remember to select @samp{Save for -future sessions} if you want to use the same filesets in future Emacs -sessions. - - You can use the command @kbd{M-x filesets-open} to visit all the -files in a fileset, and @kbd{M-x filesets-close} to close them. Use -@kbd{M-x filesets-run-cmd} to run a shell command on all the files in -a fileset. These commands are also available from the @samp{Filesets} -menu, where each existing fileset is represented by a submenu. - - Emacs uses the concept of a fileset elsewhere @pxref{Version -Control} to describe sets of files to be treated as a group for -purposes of version control operations. Those filesets are unnamed -and do not persist across Emacs sessions. - -@ignore - arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 -@end ignore diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi deleted file mode 100644 index 7acdc594dd3..00000000000 --- a/doc/emacs/fixit.texi +++ /dev/null @@ -1,429 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Fixit, Keyboard Macros, Search, Top -@chapter Commands for Fixing Typos -@cindex typos, fixing -@cindex mistakes, correcting - - In this chapter we describe the commands that are especially useful -when you catch a mistake in your text after you have made it, or -change your mind while composing text on the fly. - - The most fundamental command for correcting erroneous editing is the -undo command @kbd{C-/} (which is also bound to @kbd{C-x u} and -@kbd{C-_}). This undoes a single command, or a part of a command (as -in the case of @code{query-replace}), or several consecutive -self-inserting characters. Consecutive repetitions of @kbd{C-/} undo -earlier and earlier changes, back to the limit of the undo information -available. - - Aside from the commands described here, you can erase text using -deletion commands such as @key{DEL} (@code{delete-backward-char}). -These were described earlier in this manual. @xref{Erasing}. - -@menu -* Undo:: The Undo commands. -* Transpose:: Exchanging two characters, words, lines, lists... -* Fixing Case:: Correcting case of last word entered. -* Spelling:: Apply spelling checker to a word, or a whole file. -@end menu - -@node Undo -@section Undo -@cindex undo -@cindex changes, undoing - - The @dfn{undo} command reverses recent changes in the buffer's text. -Each buffer records changes individually, and the undo command always -applies to the current buffer. You can undo all the changes in a -buffer for as far as back its records go. Usually, each editing -command makes a separate entry in the undo records, but some commands -such as @code{query-replace} divide their changes into multiple -entries for flexibility in undoing. Consecutive character insertion -commands are usually grouped together into a single undo record, to -make undoing less tedious. - -@table @kbd -@item C-/ -@itemx C-x u -@itemx C-_ -Undo one entry in the current buffer's undo records (@code{undo}). -@end table - -@kindex C-x u -@kindex C-_ -@kindex C-/ -@findex undo - To begin to undo, type @kbd{C-/} (or its aliases, @kbd{C-_} or -@kbd{C-x u})@footnote{Aside from @kbd{C-/}, the @code{undo} command is -also bound to @kbd{C-x u} because that is more straightforward for -beginners to remember: @samp{u} stands for ``undo''. It is also bound -to @kbd{C-_} because typing @kbd{C-/} on some text-only terminals -actually enters @kbd{C-_}.}. This undoes the most recent change in -the buffer, and moves point back to where it was before that change. - - Consecutive repetitions of @kbd{C-/} (or its aliases) undo earlier -and earlier changes in the current buffer. If all the recorded -changes have already been undone, the undo command signals an error. - -@cindex redo -@findex undo-only - Any command other than an undo command breaks the sequence of undo -commands. Starting from that moment, the entire sequence of undo -commands that you have just performed are themselves placed into the -undo record, as a single set of changes. Therefore, to re-apply -changes you have undone, type @kbd{C-f} or any other command that -harmlessly breaks the sequence of undoing; then type @kbd{C-/} to undo -the undo command. - - On the other hand, if you want to resume undoing, without redoing -previous undo commands, use @kbd{M-x undo-only}. This is like -@code{undo}, but will not redo changes you have just undone. - - If you notice that a buffer has been modified accidentally, the -easiest way to recover is to type @kbd{C-/} repeatedly until the stars -disappear from the front of the mode line (@pxref{Mode Line}). -Whenever an undo command makes the stars disappear from the mode line, -it means that the buffer contents are the same as they were when the -file was last read in or saved. If you do not remember whether you -changed the buffer deliberately, type @kbd{C-/} once. When you see -the last change you made undone, you will see whether it was an -intentional change. If it was an accident, leave it undone. If it -was deliberate, redo the change as described above. - -@cindex selective undo -@kindex C-u C-/ - When there is an active region, any use of @code{undo} performs -@dfn{selective undo}: it undoes the most recent change within the -region, instead of the entire buffer. However, when Transient Mark -mode is off (@pxref{Persistent Mark}), @kbd{C-/} always operates on -the entire buffer, ignoring the region. In this case, you can perform -selective undo by supplying a prefix argument to the @code{undo} -command: @kbd{C-u C-/}. To undo further changes in the same region, -repeat the @code{undo} command (no prefix argument is needed). - - Some specialized buffers do not make undo records. Buffers whose -names start with spaces never do; these buffers are used internally by -Emacs to hold text that users don't normally look at or edit. - -@vindex undo-limit -@vindex undo-strong-limit -@vindex undo-outer-limit -@cindex undo limit - When the undo records for a buffer becomes too large, Emacs discards -the oldest undo records from time to time (during @dfn{garbage -collection}). You can specify how much undo records to keep by -setting the variables @code{undo-limit}, @code{undo-strong-limit}, and -@code{undo-outer-limit}. Their values are expressed in bytes. - - The variable @code{undo-limit} sets a soft limit: Emacs keeps undo -data for enough commands to reach this size, and perhaps exceed it, -but does not keep data for any earlier commands beyond that. Its -default value is 80000. The variable @code{undo-strong-limit} sets a -stricter limit: any previous command (though not the most recent one) -that pushes the size past this amount is forgotten. The default value -of @code{undo-strong-limit} is 120000. - - Regardless of the values of those variables, the most recent change -is never discarded unless it gets bigger than @code{undo-outer-limit} -(normally 12,000,000). At that point, Emacs discards the undo data and -warns you about it. This is the only situation in which you cannot -undo the last command. If this happens, you can increase the value of -@code{undo-outer-limit} to make it even less likely to happen in the -future. But if you didn't expect the command to create such large -undo data, then it is probably a bug and you should report it. -@xref{Bugs,, Reporting Bugs}. - -@node Transpose -@section Transposing Text - -@table @kbd -@item C-t -Transpose two characters (@code{transpose-chars}). -@item M-t -Transpose two words (@code{transpose-words}). -@item C-M-t -Transpose two balanced expressions (@code{transpose-sexps}). -@item C-x C-t -Transpose two lines (@code{transpose-lines}). -@end table - -@kindex C-t -@findex transpose-chars - The common error of transposing two characters can be fixed, when they -are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, -@kbd{C-t} transposes the two characters on either side of point. When -given at the end of a line, rather than transposing the last character of -the line with the newline, which would be useless, @kbd{C-t} transposes the -last two characters on the line. So, if you catch your transposition error -right away, you can fix it with just a @kbd{C-t}. If you don't catch it so -fast, you must move the cursor back between the two transposed -characters before you type @kbd{C-t}. If you transposed a space with -the last character of the word before it, the word motion commands are -a good way of getting there. Otherwise, a reverse search (@kbd{C-r}) -is often the best way. @xref{Search}. - -@kindex C-x C-t -@findex transpose-lines -@kindex M-t -@findex transpose-words -@c Don't index C-M-t and transpose-sexps here, they are indexed in -@c programs.texi, in the "List Commands" node. -@c @kindex C-M-t -@c @findex transpose-sexps - @kbd{M-t} transposes the word before point with the word after point -(@code{transpose-words}). It moves point forward over a word, -dragging the word preceding or containing point forward as well. The -punctuation characters between the words do not move. For example, -@w{@samp{FOO, BAR}} transposes into @w{@samp{BAR, FOO}} rather than -@samp{@w{BAR FOO,}}. - - @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for -transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards what units of text they transpose. - - A numeric argument to a transpose command serves as a repeat count: it -tells the transpose command to move the character (word, expression, line) -before or containing point across several other characters (words, -expressions, lines). For example, @kbd{C-u 3 C-t} moves the character before -point forward across three other characters. It would change -@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to -repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word -before point backward across four words. @kbd{C-u - C-M-t} would cancel -the effect of plain @kbd{C-M-t}.@refill - - A numeric argument of zero is assigned a special meaning (because -otherwise a command with a repeat count of zero would do nothing): to -transpose the character (word, expression, line) ending after point -with the one ending after the mark. - -@node Fixing Case -@section Case Conversion - -@table @kbd -@item M-- M-l -Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. -@item M-- M-u -Convert last word to all upper case. -@item M-- M-c -Convert last word to lower case with capital initial. -@end table - -@kindex M-@t{-} M-l -@kindex M-@t{-} M-u -@kindex M-@t{-} M-c - A very common error is to type words in the wrong case. Because of this, -the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a -special feature when used with a negative argument: they do not move the -cursor. As soon as you see you have mistyped the last word, you can simply -case-convert it and go on typing. @xref{Case}.@refill - -@node Spelling -@section Checking and Correcting Spelling -@cindex spelling, checking and correcting -@cindex checking spelling -@cindex correcting spelling - - This section describes the commands to check the spelling of a -single word or of a portion of a buffer. These commands only work if -the spelling checker program Aspell, Ispell or Hunspell is installed. -Aspell, Ispell or Hunspell are not part of Emacs, but one or the other -is usually installed in GNU/Linux and other free operating systems. -@ifnottex -@xref{Top, Aspell,, aspell, The Aspell Manual}. -@end ifnottex - -@table @kbd -@item M-$ -Check and correct spelling of the active region or the word at point -(@code{ispell-word}). -@item M-x ispell -Check and correct spelling in the active region or the entire buffer. -@item M-x ispell-buffer -Check and correct spelling in the buffer. -@item M-x ispell-region -Check and correct spelling in the region. -@item M-x ispell-message -Check and correct spelling in a draft mail message, excluding cited -material. -@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} -Restart the Aspell/Ispell/Hunspell process, using @var{dict} as the dictionary. -@item M-x ispell-kill-ispell -Kill the Aspell/Ispell/Hunspell subprocess. -@item M-@key{TAB} -@itemx @key{ESC} @key{TAB} -Complete the word before point based on the spelling dictionary -(@code{ispell-complete-word}). -@item M-x flyspell-mode -Enable Flyspell mode, which highlights all misspelled words. -@item M-x flyspell-prog-mode -Enable Flyspell mode for comments and strings only. -@end table - -@kindex M-$ -@findex ispell-word - To check the spelling of the word around or before point, and -optionally correct it as well, type @kbd{M-$} (@code{ispell-word}). -If a region is active, @kbd{M-$} checks the spelling of all words -within the region. @xref{Mark}. (When Transient Mark mode is off, -@kbd{M-$} always acts on the word around or before point, ignoring the -region. @xref{Persistent Mark}.) - -@findex ispell -@findex ispell-buffer -@findex ispell-region -@cindex spell-checking the active region - Similarly, the command @kbd{M-x ispell} performs spell-checking in -the region if one is active, or in the entire buffer otherwise. The -commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region} -explicitly perform spell-checking on the entire buffer or the region -respectively. To check spelling in an email message you are writing, -use @kbd{M-x ispell-message}; that command checks the whole buffer, -except for material that is indented or appears to be cited from other -messages. @xref{Sending Mail}. - - When one of these commands encounters what appears to be an -incorrect word, it asks you what to do. It usually displays a list of -numbered ``near-misses''---words that are close to the incorrect word. -Then you must type a single-character response. Here are the valid -responses: - -@table @kbd -@item @var{digit} -Replace the word, just this time, with one of the displayed -near-misses. Each near-miss is listed with a digit; type that digit -to select it. - -@item @key{SPC} -Skip this word---continue to consider it incorrect, but don't change it -here. - -@item r @var{new} @key{RET} -Replace the word, just this time, with @var{new}. (The replacement -string will be rescanned for more spelling errors.) - -@item R @var{new} @key{RET} -Replace the word with @var{new}, and do a @code{query-replace} so you -can replace it elsewhere in the buffer if you wish. (The replacements -will be rescanned for more spelling errors.) - -@item a -Accept the incorrect word---treat it as correct, but only in this -editing session. - -@item A -Accept the incorrect word---treat it as correct, but only in this -editing session and for this buffer. - -@item i -Insert this word in your private dictionary file so that Aspell or Ispell -or Hunspell will consider it correct from now on, even in future sessions. - -@item m -Like @kbd{i}, but you can also specify dictionary completion -information. - -@item u -Insert the lower-case version of this word in your private dic@-tion@-ary -file. - -@item l @var{word} @key{RET} -Look in the dictionary for words that match @var{word}. These words -become the new list of ``near-misses''; you can select one of them as -the replacement by typing a digit. You can use @samp{*} in @var{word} as a -wildcard. - -@item C-g -@itemx X -Quit interactive spell checking, leaving point at the word that was -being checked. You can restart checking again afterward with @kbd{C-u -M-$}. - -@item x -Quit interactive spell checking and move point back to where it was -when you started spell checking. - -@item q -Quit interactive spell checking and kill the Aspell/Ispell/Hunspell -subprocess. - -@item ? -Show the list of options. -@end table - -@findex ispell-complete-word - In Text mode and related modes, the command @kbd{M-@key{TAB}} -(@code{ispell-complete-word}) shows a list of completions based on -spelling correction. Insert the beginning of a word, and then type -@kbd{M-@key{TAB}}; the command displays a completion list window. (If -your window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC} -@key{TAB}} or @kbd{C-M-i}.) To choose one of the completions listed, -click @kbd{Mouse-2} or @kbd{Mouse-1} fast on it, or move the cursor -there in the completions window and type @key{RET}. @xref{Text Mode}. - -@cindex @code{ispell} program -@findex ispell-kill-ispell - Once started, the Aspell or Ispell or Hunspell subprocess continues -to run, waiting for something to do, so that subsequent spell checking -commands complete more quickly. If you want to get rid of the -process, use @kbd{M-x ispell-kill-ispell}. This is not usually -necessary, since the process uses no time except when you do spelling -correction. - -@vindex ispell-dictionary -@vindex ispell-local-dictionary -@vindex ispell-personal-dictionary -@vindex ispell-complete-word-dict - Ispell, Aspell and Hunspell use two dictionaries together for spell checking: -the standard dictionary and your private dictionary. The standard -dictionary is specified by @code{ispell-local-dictionary} or, -if @code{nil}, by @code{ispell-dictionary}. If both are @code{nil} -the default dictionary is selected. The command -@kbd{M-x ispell-change-dictionary} sets the standard dictionary for -the buffer and then restarts the subprocess, so that it will use a -different standard dictionary. Personal dictionary is specified by -@code{ispell-personal-dictionary}. If @code{nil}, default value is -used. - - Set variable @code{ispell-dictionary} to select a specific default -dictionary for all your documents. Set variable -@code{ispell-local-dictionary} in the local variables section to -select a specific dictionary for a given document. - - A separate dictionary is used for word completion. The variable -@code{ispell-complete-word-dict} specifies the file name of this -dictionary. The completion dictionary must be different because it -cannot use root and affix information. For some languages, there -is a spell checking dictionary but no word completion dictionary. - -@cindex Flyspell mode -@findex flyspell-mode - Flyspell mode is a fully-automatic way to check spelling as you edit -in Emacs. It operates by checking words as you change or insert them. -When it finds a word that it does not recognize, it highlights that -word. This does not interfere with your editing, but when you see the -highlighted word, you can move to it and fix it. Type @kbd{M-x -flyspell-mode} to enable or disable this mode in the current buffer. -@findex turn-on-flyspell -To enable @code{flyspell-mode} in all text mode buffers, add -@code{turn-on-flyspell} to @code{text-mode-hook}. - - - When Flyspell mode highlights a word as misspelled, you can click on -it with @kbd{Mouse-2} to display a menu of possible corrections and -actions. You can also correct the word by editing it manually in any -way you like. - -@findex flyspell-prog-mode - Flyspell Prog mode works just like ordinary Flyspell mode, except -that it only checks words in comments and string constants. This -feature is useful for editing programs. Type @kbd{M-x -flyspell-prog-mode} to enable or disable this mode in the current -buffer. - -@ignore - arch-tag: 3359a443-96ed-448f-9f05-c8111ba8eac0 -@end ignore diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi deleted file mode 100644 index e501fe0b16f..00000000000 --- a/doc/emacs/fortran-xtra.texi +++ /dev/null @@ -1,587 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Fortran -@section Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - -@cindex Fortran fixed form and free form -@cindex Fortran 77 and Fortran 90, 95, 2003 -@findex f90-mode -@findex fortran-mode - Fortran mode is meant for editing ``fixed form'' (and also ``tab -format'') source code (normally Fortran 77). For editing more modern -``free form'' source code (Fortran 90, 95, 2003), use F90 mode -(@code{f90-mode}). Emacs normally uses Fortran mode for files with -extension @samp{.f}, @samp{.F} or @samp{.for}, and F90 mode for the -extensions @samp{.f90} and @samp{.f95}. Customize -@code{auto-mode-alist} to add more extensions. GNU Fortran supports -both free and fixed form. This manual mainly documents Fortran mode, -but the corresponding F90 mode features are mentioned when revelant. - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers and continuation statements. -Fortran mode has support for Auto Fill mode that breaks long lines into -proper Fortran continuation lines. Fortran mode also supports Hideshow -minor mode -@iftex -(@pxref{Hideshow,,, emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Hideshow}), -@end ifnottex -and Imenu -@iftex -(@pxref{Imenu,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Imenu}). -@end ifnottex - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - - Use @kbd{M-x fortran-mode} to switch to this major mode. This -command runs the hook @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill support for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -@end menu - -@node Fortran Motion -@subsection Motion Commands - - In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, using the -commands @code{fortran-beginning-of-subprogram} and -@code{fortran-end-of-subprogram}; as well as modules for F90 mode), -Fortran mode provides special commands to move by statements and other -program units. - -@table @kbd -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-next-statement -@findex f90-next-statement -@item C-c C-n -Move to the beginning of the next statement -(@code{fortran-next-statement}/@code{f90-next-statement}). - -@kindex C-c C-p @r{(Fortran mode)} -@findex fortran-previous-statement -@findex f90-previous-statement -@item C-c C-p -Move to the beginning of the previous statement -(@code{fortran-previous-statement}/@code{f90-previous-statement}). -If there is no previous statement (i.e. if called from the first -statement in the buffer), move to the start of the buffer. - -@kindex C-c C-e @r{(F90 mode)} -@findex f90-next-block -@item C-c C-e -Move point forward to the start of the next code block, or the end of -the current block, whichever is encountered first. -(@code{f90-next-block}). A code block is a subroutine, -@code{if}--@code{endif} statement, and so forth. This command exists -for F90 mode only, not Fortran mode. With a numeric argument, this -moves forward that many blocks. - -@kindex C-c C-a @r{(F90 mode)} -@findex f90-previous-block -@item C-c C-a -Move point backward to the previous code block -(@code{f90-previous-block}). This is like @code{f90-next-block}, but -moves backwards. - -@kindex C-M-n @r{(Fortran mode)} -@findex fortran-end-of-block -@findex f90-end-of-block -@item C-M-n -Move to the end of the current code block -(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric -argument, move forward that number of blocks. The mark is set before -moving point. The F90 mode version of this command checks for -consistency of block types and labels (if present), but it does not -check the outermost block since that may be incomplete. - -@kindex C-M-p @r{(Fortran mode)} -@findex fortran-beginning-of-block -@findex f90-beginning-of-block -@item C-M-p -Move to the start of the current code block -(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This -is like @code{fortran-end-of-block}, but moves backwards. -@end table - -The commands @code{fortran-beginning-of-subprogram} and -@code{fortran-end-of-subprogram} move to the start or end of the -current subprogram, respectively. The commands @code{fortran-mark-do} -and @code{fortran-mark-if} mark the end of the current @code{do} or -@code{if} block, and move point to the start. - - -@node Fortran Indent -@subsection Fortran Indentation - - Special commands and features are needed for indenting fixed (or tab) -form Fortran code in order to make sure various syntactic entities (line -numbers, comment line indicators and continuation line flags) appear in -the required columns. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsubsection Fortran Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line at point and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement (using @code{fortran-fill-paragraph} -or @code{fortran-fill-statement}). -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -@kbd{M-q} in Fortran mode fills the comment block or statement that -point is in. This removes any excess statement continuations. - -@node ForIndent Cont -@subsubsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most Fortran 77 compilers allow two ways of writing continuation lines. -If the first non-space character on a line is in column 5, then that -line is a continuation of the previous line. We call this @dfn{fixed -form}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable -@code{fortran-continuation-string} specifies what character to put in -column 5. A line that starts with a tab character followed by any digit -except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran 90 introduced ``free form,'' -with another style of continuation lines). - -@vindex indent-tabs-mode @r{(Fortran mode)} -@vindex fortran-analyze-depth -@vindex fortran-tab-mode-default - Fortran mode can use either style of continuation line. When you -enter Fortran mode, it tries to deduce the proper continuation style -automatically from the buffer contents. It does this by scanning up to -@code{fortran-analyze-depth} (default 100) lines from the start of the -buffer. The first line that begins with either a tab character or six -spaces determines the choice. If the scan fails (for example, if the -buffer is new and therefore empty), the value of -@code{fortran-tab-mode-default} (@code{nil} for fixed form, and -non-@code{nil} for tab format) is used. @samp{/t} -(@code{fortran-tab-mode-string}) in the mode line indicates tab format -is selected. Fortran mode sets the value of @code{indent-tabs-mode} -accordingly. - - If the text on a line starts with the Fortran continuation marker -@samp{$}, or if it begins with any non-whitespace character in column -5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed form mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers always use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must always consist of one tab character. - -@node ForIndent Num -@subsubsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in GNU Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. The default -value of the variable is 1. Fortran mode tries to prevent line number -digits passing column 4, reducing the indentation below the specified -maximum if necessary. If @code{fortran-line-number-indent} has the -value 5, line numbers are right-justified to end in column 4. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. - - -@node ForIndent Conv -@subsubsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsubsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if}, @samp{select case}, or -@samp{where} statements (default 3). - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, -@samp{map}, or @samp{interface} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -In Fortran 77, a numbered @samp{do} statement is ended by any statement -with a matching line number. It is common (but not compulsory) to use a -@samp{continue} statement for this purpose. If this variable has a -non-@code{nil} value, indenting any numbered statement must check for a -@samp{do} that ends there. If you always end @samp{do} statements with -a @samp{continue} line (or if you use the more modern @samp{enddo}), -then you can speed up indentation by setting this variable to -@code{nil}. The default is @code{nil}. - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} -statement moves the cursor momentarily to the matching @samp{if} (or -@samp{do}) statement to show where it is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for Fortran statements when using fixed form -continuation line style. Statement bodies are never indented less than -this much. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for Fortran statements for tab format continuation line -style. Statement bodies are never indented less than this much. The -default is 8. -@end table - -The variables controlling the indentation of comments are described in -the following section. - -@node Fortran Comments -@subsection Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran 77, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. - -@vindex fortran-comment-line-start - Fortran mode can also handle the Fortran 90 comment syntax where -comments start with @samp{!} and can follow other text. Because only -some Fortran 77 compilers accept this syntax, Fortran mode will not -insert such comments unless you have said in advance to do so. To do -this, set the variable @code{fortran-comment-line-start} to @samp{"!"}. -If you use an unusual value, you may also need to adjust -@code{fortran-comment-line-start-skip}. - - -@table @kbd -@item M-; -Align comment or insert new comment (@code{comment-dwim}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only. - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - - @kbd{M-;} in Fortran mode runs the standard @code{comment-dwim}. -This recognizes any kind of existing comment and aligns its text -appropriately; if there is no existing comment, a comment is inserted -and aligned. Inserting and aligning comments are not the same in -Fortran mode as in other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum statement indentation is -@code{fortran-minimum-statement-indent-fixed} for fixed form -continuation line style and @code{fortran-minimum-statement-indent-tab} -for tab format style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex fortran-directive-re - Compiler directive lines, or preprocessor lines, have much the same -appearance as comment lines. It is important, though, that such lines -never be indented at all, no matter what the value of -@code{fortran-comment-indent-style}. The variable -@code{fortran-directive-re} is a regular expression that specifies which -lines are directives. Matching lines are never indented, and receive -distinctive font-locking. - - The normal Emacs comment command @kbd{C-x ;} has not been redefined. If -you use @samp{!} comments, this command can be used with them. Otherwise -it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{C$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{C$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@subsection Auto Fill in Fortran Mode - - Fortran mode has specialized support for Auto Fill mode, which is a -minor mode that automatically splits statements as you insert them -when they become too wide. Splitting a statement involves making -continuation lines using @code{fortran-continuation-string} -(@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. -@iftex -@xref{Auto Fill,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Auto Fill}. -@end ifnottex - -@vindex fortran-break-before-delimiters - Auto Fill breaks lines at spaces or delimiters when the lines get -longer than the desired width (the value of @code{fill-column}). The -delimiters (besides whitespace) that Auto Fill can break at are -@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, -and @samp{,}. The line break comes after the delimiter if the -variable @code{fortran-break-before-delimiters} is @code{nil}. -Otherwise (and by default), the break comes before the delimiter. - - To enable Auto Fill in all Fortran buffers, add -@code{turn-on-auto-fill} to @code{fortran-mode-hook}. -@iftex -@xref{Hooks,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Hooks}. -@end ifnottex - -@node Fortran Columns -@subsection Checking Columns in Fortran - -@vindex fortran-line-length -In standard Fortran 77, anything beyond column 72 is ignored. -Most compilers provide an option to change this (for example, -@samp{-ffixed-line-length-N} in gfortran). Customize the variable -@code{fortran-line-length} to change the line length in Fortran mode. -Anything beyond this point is font-locked as a comment. (Unless it is -inside a string: strings that extend beyond @code{fortran-line-length} -will confuse font-lock.) - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is -@code{fortran-line-length} columns wide -(@code{fortran-window-create-momentarily}). This may help you avoid -making lines longer than the character limit imposed by your Fortran -compiler. -@item C-u C-c C-w -Split the current window horizontally so that it is -@code{fortran-line-length} columns wide (@code{fortran-window-create}). -You can then continue editing. -@item M-x fortran-strip-sequence-nos -Delete all text in column @code{fortran-line-length} and beyond. -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - -@vindex fortran-column-ruler-fixed -@vindex fortran-column-ruler-tabs - The text used to display the column ruler depends on the value of the -variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the value of the variable @code{fortran-column-ruler-tab} is -displayed. By changing these variables, you can change the column ruler -display. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily - @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily -splits the current window horizontally, making a window -@code{fortran-line-length} columns wide, so you can see any lines that -are too long. Type a space to restore the normal width. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - You can also split the window horizontally and continue editing with -the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x -fortran-window-create}). By editing in this window you can -immediately see when you make a line too wide to be correct Fortran. - -@findex fortran-strip-sequence-nos - The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in -column @code{fortran-line-length} and beyond, on all lines in the -current buffer. This is the easiest way to get rid of old sequence -numbers. - -@node Fortran Abbrev -@subsection Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. -@iftex -@xref{Abbrevs,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Abbrevs}. -@end ifnottex - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. - -@ignore - arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6 -@end ignore diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi deleted file mode 100644 index a74345fb833..00000000000 --- a/doc/emacs/frames.texi +++ /dev/null @@ -1,1130 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Frames, International, Windows, Top -@chapter Frames and Graphical Displays -@cindex frames - - When using a graphical display, you can create multiple system-level -``windows'' in a single Emacs session. We refer to these system-level -windows as @dfn{frames}. A frame initially contains a single Emacs -window; however, you can subdivide this Emacs window into smaller -windows, all fitting into the same frame. Each frame normally -contains its own echo area and minibuffer. - - To avoid confusion, we reserve the word ``window'' for the -subdivisions that Emacs implements, and never use it to refer to a -frame. - - Any editing you do in one frame affects the other frames. For -instance, if you put text in the kill ring in one frame, you can yank -it in another frame. If you exit Emacs through @kbd{C-x C-c} in one -frame, it terminates all the frames. To delete just one frame, use -@kbd{C-x 5 0} (that is zero, not @kbd{o}). - - Emacs compiled for MS-DOS emulates some windowing functionality, -so that you can use many of the features described in this chapter. -@iftex -@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Mouse}. -@end ifnottex - -@menu -* Cut and Paste:: Mouse commands for cut and paste. -* Mouse References:: Using the mouse to select an item from a list. -* Menu Mouse Clicks:: Mouse clicks that bring up menus. -* Mode Line Mouse:: Mouse clicks on the mode line. -* Creating Frames:: Creating additional Emacs frames with various contents. -* Frame Commands:: Iconifying, deleting, and switching frames. -* Speedbar:: How to make and use a speedbar frame. -* Multiple Displays:: How one Emacs job can talk to several displays. -* Special Buffer Frames:: You can make certain buffers have their own frames. -* Frame Parameters:: Changing the colors and other modes of frames. -* Scroll Bars:: How to enable and disable scroll bars; how to use them. -* Wheeled Mice:: Using mouse wheels for scrolling. -* Drag and Drop:: Using drag and drop to open files and insert text. -* Menu Bars:: Enabling and disabling the menu bar. -* Tool Bars:: Enabling and disabling the tool bar. -* Dialog Boxes:: Controlling use of dialog boxes. -* Tooltips:: Displaying information at the current mouse position. -* Mouse Avoidance:: Moving the mouse pointer out of the way. -* Non-Window Terminals:: Multiple frames on terminals that show only one. -* Text-Only Mouse:: Using the mouse in text-only terminals. -@end menu - -@node Cut and Paste -@section Killing and Yanking on Graphical Displays - - This section describes commands for selecting a region, killing, and -yanking using the mouse. - -@menu -* Mouse Commands:: Moving, cutting, and pasting, with the mouse. -* Word and Line Mouse:: Mouse commands for selecting whole words or lines. -* Cut/Paste Other App:: Transfering text between Emacs and other apps. -* Secondary Selection:: Cutting without altering point and mark. -* Clipboard:: Using the clipboard for selections. -@end menu - -@node Mouse Commands -@subsection Mouse Commands for Editing -@cindex mouse buttons (what they do) - -@kindex Mouse-1 -@kindex Mouse-2 -@kindex Mouse-3 -@table @kbd -@item Mouse-1 -Move point to where you click (@code{mouse-set-point}). - -@item Drag-Mouse-1 -Activate the region around the text selected by dragging, and copy it -to the kill ring (@code{mouse-set-region}). - -@item Mouse-2 -Yank the last killed text at the click position -(@code{mouse-yank-at-click}). - -@item Mouse-3 -If the region is active, move the nearer end of the region to the -click position; otherwise, set mark at the current value of point and -point at the click position. Save the resulting region in the kill -ring; on a second click, kill it (@code{mouse-save-then-kill}). -@end table - -@findex mouse-set-point - The most basic mouse command is @code{mouse-set-point}, which is -called by clicking with the left mouse button, @kbd{Mouse-1}, in the -text area of a window. This moves point to the position where you -clicked. - -@vindex x-mouse-click-focus-ignore-position - Normally, Emacs does not distinguish between ordinary mouse clicks -and clicks that select a frame. When you click on a frame to select -it, that also changes the selected window and cursor position -according to the mouse click position. On the X window system, you -can change this behavior by setting the variable -@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the -first click selects the frame, but does not affect the selected window -or cursor position. If you click again in the same place, that click -will be in the selected frame, so it will change the window or cursor -position. - -@findex mouse-set-region -@vindex mouse-drag-copy-region - Holding down @kbd{Mouse-1} and ``dragging'' the mouse over a stretch -of text activates the region around that text -(@code{mouse-set-region}). @xref{Mark}. Emacs places the mark where -you started holding down the mouse button, and point where you release -it. In addition, the region is copied into the kill ring (@pxref{Kill -Ring}). If you don't want Emacs to copy the region, change the -variable @code{mouse-drag-copy-region} to @code{nil}. - -@vindex mouse-scroll-min-lines - If you move the mouse off the top or bottom of the window while -dragging, the window scrolls at a steady rate until you move the mouse -back into the window. This way, you can select regions that don't fit -entirely on the screen. The number of lines scrolled per step depends -on how far away from the window edge the mouse has gone; the variable -@code{mouse-scroll-min-lines} specifies a minimum step size. - -@findex mouse-yank-at-click -@vindex mouse-yank-at-point - Clicking with the middle mouse button, @kbd{Mouse-2}, moves point to -the position where you clicked and performs a yank -(@code{mouse-yank-at-click}). @xref{Yanking}. If you change the -variable @code{mouse-yank-at-point} to a non-@code{nil} value, -@kbd{Mouse-2} does not move point. Then it does not matter where you -click, or even which of the frame's windows you click on; the yank -occurs at the existing point. This variable also affects yanking the -primary and secondary selections (@pxref{Cut/Paste Other App}). - -@findex mouse-save-then-kill - Clicking with the right mouse button, @kbd{Mouse-3}, runs the -command @code{mouse-save-then-kill}. This performs several actions -depending on where you click and the status of the region: - -@itemize @bullet -@item -If no region is active, clicking @kbd{Mouse-3} activates the region, -placing the mark where point was and point at the clicked position. -In addition, the text in the region is copied to the kill ring. - -@item -If a region is active, clicking @kbd{Mouse-3} adjusts the nearer end -of the region by moving it to the clicked position. The adjusted -region's text is copied to the kill ring; if the text in the original -region was already on the kill ring, it replaces it there. - -@item -If you originally specified the region using a double or triple -@kbd{Mouse-1}, so that the region is defined to consist of entire -words or lines, then adjusting the region with @kbd{Mouse-3} also -proceeds by entire words or lines. - -@item -If you use @kbd{Mouse-3} a second time consecutively, at the same -place, that kills the region already selected. Thus, the simplest way -to kill text with the mouse is to click @kbd{Mouse-1} at one end, then -click @kbd{Mouse-3} twice at the other end. To copy the text into the -kill ring without deleting it from the buffer, press @kbd{Mouse-3} -just once---or just drag across the text with @kbd{Mouse-1}. Then you -can copy it elsewhere by yanking it. -@end itemize - - Whenever you set the region using any of the mouse commands -described above, the mark will be deactivated by any subsequent -unshifted cursor motion command, in addition to the usual ways of -deactivating the mark. @xref{Shift Selection}. While the region -remains active, typing @key{Backspace} or @key{Delete} deletes the -text in that region and deactivates the mark; this behavior follows a -convention established by other graphical programs, and it does -@emph{not} apply when you set the region any other way, including -shift-selection (@pxref{Shift Selection}). - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - Many graphical applications also follow the convention that -insertion while text is selected deletes the selected text. You can -make Emacs behave this way by enabling Delete Selection mode. -@xref{Using Region}. - -@node Word and Line Mouse -@subsection Mouse Commands for Words and Lines - - These variants of @kbd{Mouse-1} select entire words or lines at a -time. Emacs activates the region around the selected text, which is -also copied to the kill ring. - -@table @kbd -@item Double-Mouse-1 -Select the text around the word which you click on. - -Double-clicking on a character with ``symbol'' syntax (such as -underscore, in C mode) selects the symbol surrounding that character. -Double-clicking on a character with open- or close-parenthesis syntax -selects the parenthetical grouping which that character starts or -ends. Double-clicking on a character with string-delimiter syntax -(such as a singlequote or doublequote in C) selects the string -constant (Emacs uses heuristics to figure out whether that character -is the beginning or the end of it). - -@item Double-Drag-Mouse-1 -Select the text you drag across, in the form of whole words. - -@item Triple-Mouse-1 -Select the line you click on. - -@item Triple-Drag-Mouse-1 -Select the text you drag across, in the form of whole lines. -@end table - -@node Cut/Paste Other App -@subsection Cut and Paste with Other Window Applications - -@cindex X cutting and pasting -@cindex X selection -@cindex primary selection -@cindex selection, primary - When running Emacs under the X window system, you can easily -transfer text between Emacs and other X applications using the -@dfn{primary selection} (also called the @dfn{X selection}). This is -@emph{not} the same thing as the @dfn{clipboard}, which is a separate -facility used on desktop environments such as Gnome, and on operating -systems such as Microsoft Windows (@pxref{Clipboard}). - - Under X, whenever you select some text in Emacs by dragging or -clicking the mouse (@pxref{Mouse Commands}), it is also saved in the -primary selection. You can then @dfn{paste} that text into any other -X application, usually by clicking @kbd{Mouse-2} in that application. -Unlike the Emacs kill ring (@pxref{Kill Ring}), the primary selection -has no ``memory'': each time you save something in the primary -selection, either in Emacs or in another X application, the previous -contents of the primary selection are lost. - - Whenever you kill some text using a command such as @kbd{C-w} -(@code{kill-region}), or copy it into the kill ring using a command -such as @kbd{M-w} (@code{kill-ring-save}), that text is also saved in -the primary selection. @xref{Killing}. - -@cindex cut buffer -@vindex x-cut-buffer-max - Whenever Emacs saves some text to the primary selection, it may also -save it to the @dfn{cut buffer}. The cut buffer is an obsolete -predecessor to the primary selection; most modern applications do not -make use of it. Because saving text to the cut buffer is slow and -inefficient, Emacs only does it if the text is shorter than the value -of @code{x-cut-buffer-max} (the default is 20000 characters). - - You can yank the primary selection into Emacs using the usual yank -commands, such as @kbd{C-y} (@code{yank}) and @kbd{Mouse-2} -(@code{mouse-yank-at-click}). These commands actually check the -primary selection before referring to the kill ring; if no primary -selection is available, the kill ring contents are used. To prevent -yank commands from accessing the primary selection, set the variable -@code{x-select-enable-primary} to @code{nil}. - - The standard coding system for the primary selection is -@code{compound-text-with-extensions}. You may find that the pasted -text is not what you expected. In such a case, you can specify -another coding system for the selection by typing @kbd{C-x @key{RET} -x} or @kbd{C-x @key{RET} X}. Alternatively, you can request a -different data type by modifying the variable -@code{x-select-request-type}. @xref{Communication Coding}. - -@node Secondary Selection -@subsection Secondary Selection -@cindex secondary selection - - In addition to the primary selection, the X Window System provides a -second similar facility known as the @dfn{secondary selection}. -Nowadays, few X applications make use of the secondary selection, but -you can access it using the following Emacs commands: - -@table @kbd -@findex mouse-set-secondary -@kindex M-Drag-Mouse-1 -@item M-Drag-Mouse-1 -Set the secondary selection, with one end at the place where you press -down the button, and the other end at the place where you release it -(@code{mouse-set-secondary}). The selected text is highlighted, using -the @code{secondary-selection} face, as you drag. The window scrolls -automatically if you drag the mouse off the top or bottom of the -window, just like @code{mouse-set-region} (@pxref{Mouse Commands}). - -This command does not alter the kill ring. - -@findex mouse-start-secondary -@kindex M-Mouse-1 -@item M-Mouse-1 -Set one endpoint for the @dfn{secondary selection} -(@code{mouse-start-secondary}). - -@findex mouse-secondary-save-then-kill -@kindex M-Mouse-3 -@item M-Mouse-3 -Set the secondary selection, with one end at the position clicked and -the other at the position specified with @kbd{M-Mouse-1} -(@code{mouse-secondary-save-then-kill}). This also puts the selected -text in the kill ring. A second @kbd{M-Mouse-3} at the same place -kills the secondary selection just made. - -@findex mouse-yank-secondary -@kindex M-Mouse-2 -@item M-Mouse-2 -Insert the secondary selection where you click, placing point at the -end of the yanked text (@code{mouse-yank-secondary}). -@end table - -Double or triple clicking of @kbd{M-Mouse-1} operates on words and -lines, much like @kbd{Mouse-1}. - -If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} yanks -at point. Then it does not matter precisely where you click, or even -which of the frame's windows you click on. @xref{Mouse Commands}. - -@node Clipboard -@subsection Using the Clipboard -@cindex clipboard - - In desktop environments such as Gnome, and operating systems such as -Microsoft Windows and Mac OS X, you can transfer data (usually text) -between different applications using the @dfn{clipboard}. The -clipboard is distinct from the primary selection and secondary -selection discussed earlier. You can access the clipboard through the -@samp{Edit} menu of the menu bar (@pxref{Menu Bar}). - -@cindex cut -@findex clipboard-kill-region - The command @code{clipboard-kill-region}, which is bound to the -@code{Cut} menu item, kills the region and saves it in the clipboard. - -@cindex copy -@findex clipboard-kill-ring-save - The command @code{clipboard-kill-ring-save}, which is bound to the -@code{Copy} menu item, copies the region to the kill ring and saves it -in the clipboard. - -@findex clipboard-yank -@cindex paste - The @code{Paste} menu item in the Edit menu yanks the contents of -the clipboard at point (@code{clipboard-yank}). - -@vindex x-select-enable-clipboard - You can customize the variable @code{x-select-enable-clipboard} to -make the Emacs yank functions consult the clipboard before the primary -selection, and to make the kill functions to store in the clipboard as -well as the primary selection. Otherwise, these commands do not -access the clipboard at all. Using the clipboard is the default on -MS-Windows and Mac OS, but not on other systems. - -@node Mouse References -@section Following References with the Mouse -@kindex Mouse-1 @r{(selection)} -@kindex Mouse-2 @r{(selection)} - -@vindex mouse-highlight - Some Emacs buffers include @dfn{buttons}. A button is a piece of -text that performs some action when you activate it, such as following -a reference. Usually, a button's text is visually highlighted: it is -underlined, or a box is drawn around it. If you move the mouse over a -button, the shape of the mouse cursor changes and the button lights up -(if you change the variable @code{mouse-highlight} to @code{nil}, -Emacs disables this highlighting). - - You can activate a button by moving point to it and typing -@key{RET}, or by clicking either @kbd{Mouse-1} or @kbd{Mouse-2} on the -button. For example, typing @key{RET} or clicking on a file name in a -Dired buffer visits that file (@pxref{Dired}). Doing it on an error -message in the @samp{*Compilation*} buffer goes to the source code for -that error message (@pxref{Compilation}). Doing it on a completion in -the @samp{*Completions*} buffer chooses that completion -(@pxref{Completion}). - - Although clicking @kbd{Mouse-1} on a button usually activates that -button, if you hold the mouse button down for a short period of time -before releasing it (specifically, for more than 450 milliseconds), -then Emacs moves point where you clicked instead. This behavior -allows you to use the mouse to move point over a button without -following it. Dragging---moving the mouse while it is held down---has -its usual behavior of setting the region, even if you drag from or -onto a button. - -@vindex mouse-1-click-in-non-selected-windows - Normally, clicking @kbd{Mouse-1} on a button activates the button -even if it is in a nonselected window. If you change the variable -@code{mouse-1-click-in-non-selected-windows} to @code{nil}, clicking -@kbd{Mouse-1} on a button in an un-selected window moves point to the -clicked position and selects that window, without activating the -button. - -@vindex mouse-1-click-follows-link - In Emacs versions before 22, only @kbd{Mouse-2} activates buttons -and @kbd{Mouse-1} always sets point. If you prefer this older -behavior, set the variable @code{mouse-1-click-follows-link} to -@code{nil}. This variable also lets you choose various other -alternatives for following links with the mouse. Type @kbd{C-h v -mouse-1-click-follows-link @key{RET}} for more details. - -@node Menu Mouse Clicks -@section Mouse Clicks for Menus - - Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers -bring up menus. - -@table @kbd -@item C-Mouse-1 -@kindex C-Mouse-1 -This menu is for selecting a buffer. - -The MSB (``mouse select buffer'') global minor mode makes this -menu smarter and more customizable. @xref{Buffer Menus}. - -@item C-Mouse-2 -@kindex C-Mouse-2 -This menu is for specifying faces and other text properties -for editing formatted text. @xref{Formatted Text}. - -@item C-Mouse-3 -@kindex C-Mouse-3 -This menu is mode-specific. For most modes if Menu-bar mode is on, -this menu has the same items as all the mode-specific menu-bar menus -put together. Some modes may specify a different menu for this -button.@footnote{Some systems use @kbd{Mouse-3} for a mode-specific -menu. We took a survey of users, and found they preferred to keep -@kbd{Mouse-3} for selecting and killing regions. Hence the decision -to use @kbd{C-Mouse-3} for this menu. To use @kbd{Mouse-3} instead, -do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If -Menu-bar mode is off, this menu contains all the items which would be -present in the menu bar---not just the mode-specific ones---so that -you can access them without having to display the menu bar. - -@item S-Mouse-1 -This menu is for changing the default face within the window's buffer. -@xref{Temporary Face Changes}. -@end table - -@node Mode Line Mouse -@section Mode Line Mouse Commands -@cindex mode line, mouse -@cindex mouse on mode line - - You can use mouse clicks on window mode lines to select and manipulate -windows. - - Some areas of the mode line, such as the buffer name, and major and minor -mode names, have their own special mouse bindings. These areas are -highlighted when you hold the mouse over them, and information about -the special bindings will be displayed (@pxref{Tooltips}). This -section's commands do not apply in those areas. - -@table @kbd -@item Mouse-1 -@kindex Mouse-1 @r{(mode line)} -@kbd{Mouse-1} on a mode line selects the window it belongs to. By -dragging @kbd{Mouse-1} on the mode line, you can move it, thus -changing the height of the windows above and below. Changing heights -with the mouse in this way never deletes windows, it just refuses to -make any window smaller than the minimum height. - -@item Mouse-2 -@kindex Mouse-2 @r{(mode line)} -@kbd{Mouse-2} on a mode line expands that window to fill its frame. - -@item Mouse-3 -@kindex Mouse-3 @r{(mode line)} -@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the -frame has only one window, it buries the current buffer instead, and -switches to another buffer. - -@item C-Mouse-2 -@kindex C-mouse-2 @r{(mode line)} -@kbd{C-Mouse-2} on a mode line splits the window above -horizontally, above the place in the mode line where you click. -@end table - -@kindex C-Mouse-2 @r{(scroll bar)} -@kindex Mouse-1 @r{(scroll bar)} - Using @kbd{Mouse-1} on the divider between two side-by-side mode -lines, you can move the vertical boundary left or right. Using -@kbd{C-Mouse-2} on a scroll bar splits the corresponding window -vertically. @xref{Split Window}. - -@node Creating Frames -@section Creating Frames -@cindex creating frames - -@kindex C-x 5 - The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with -parallel subcommands. The difference is that @kbd{C-x 5} commands -create a new frame rather than just a new window in the selected frame -(@pxref{Pop Up Window}). If an existing visible or iconified -(``minimized'') frame already displays the requested material, these -commands use the existing frame, after raising or deiconifying -(``un-minimizing'') as necessary. - - The various @kbd{C-x 5} commands differ in how they find or create the -buffer to select: - -@table @kbd -@item C-x 5 2 -@kindex C-x 5 2 -@findex make-frame-command -Create a new frame (@code{make-frame-command}). -@item C-x 5 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another frame. This runs -@code{switch-to-buffer-other-frame}. -@item C-x 5 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another frame. This -runs @code{find-file-other-frame}. @xref{Visiting}. -@item C-x 5 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another frame. -This runs @code{dired-other-frame}. @xref{Dired}. -@item C-x 5 m -Start composing a mail message in another frame. This runs -@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. -@xref{Sending Mail}. -@item C-x 5 . -Find a tag in the current tag table in another frame. This runs -@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. -@xref{Tags}. -@item C-x 5 r @var{filename} @key{RET} -@kindex C-x 5 r -@findex find-file-read-only-other-frame -Visit file @var{filename} read-only, and select its buffer in another -frame. This runs @code{find-file-read-only-other-frame}. -@xref{Visiting}. -@end table - -@cindex default-frame-alist -@cindex initial-frame-alist -@cindex face customization, in init file -@cindex color customization, in init file - You can control the appearance of new frames you create by setting the -frame parameters in @code{default-frame-alist}. You can use the -variable @code{initial-frame-alist} to specify parameters that affect -only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs -Lisp Reference Manual}, for more information. - -@cindex font (default) - For instance, one way to specify the principal font for all your -Emacs frames is to modify @code{default-frame-alist} to specify the -@code{font} parameter (@pxref{Font X}): - -@example -(add-to-list 'default-frame-alist '(font . "10x20")) -@end example - -@noindent -Here's a similar example for specifying a foreground color: - -@example -(add-to-list 'default-frame-alist '(foreground-color . "blue")) -@end example - -@noindent -By putting such customizations in your init file, you can control the -appearance of all the frames Emacs creates, including the initial one. -@xref{Init File}. - -@node Frame Commands -@section Frame Commands - - The following commands let you create, delete and operate on frames: - -@table @kbd -@item C-z -@kindex C-z @r{(X windows)} -@findex iconify-or-deiconify-frame -Iconify (``minimize'') the selected Emacs frame -(@code{iconify-or-deiconify-frame}). @xref{Exiting}. - -@item C-x 5 0 -@kindex C-x 5 0 -@findex delete-frame -Delete the selected frame (@code{delete-frame}). This is not allowed -if there is only one frame. - -@item C-x 5 o -@kindex C-x 5 o -@findex other-frame -Select another frame, raise it, and warp the mouse to it. If you -repeat this command, it cycles through all the frames on your -terminal. - -@item C-x 5 1 -@kindex C-x 5 1 -@findex delete-other-frames -Delete all frames except the selected one. -@end table - -@vindex focus-follows-mouse - To make the command @kbd{C-x 5 o} work properly, you should tell -Emacs how the system (or the window manager) handles focus-switching -between windows. There are two possibilities: either simply moving -the mouse onto a window selects it (gives it focus), or you have to -click on it to do so. On X, this focus policy also affects whether -the focus is given to a frame that Emacs raises. Unfortunately there -is no way Emacs can find out automatically which way the system -handles this, so you have to explicitly say, by setting the variable -@code{focus-follows-mouse}. If just moving the mouse onto a window -selects it, that variable should be @code{t}; if a click is necessary, -the variable should be @code{nil}. The default is @code{t}. - - The window manager that is part of MS-Windows always gives focus to -a frame that raises, so this variable has no effect in the native -MS-Windows build of Emacs. - -@node Speedbar -@section Speedbar Frames -@cindex speedbar - -@cindex attached frame (of speedbar) - The @dfn{speedbar} is a special frame for conveniently navigating in -or operating on another frame. The speedbar, when it exists, is -always associated with a specific frame, called its @dfn{attached -frame}; all speedbar operations act on that frame. - - Type @kbd{M-x speedbar} to create the speedbar and associate it with -the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} -again, or select the speedbar and type @kbd{q}. (You can also delete -the speedbar frame like any other Emacs frame.) If you wish to -associate the speedbar with a different frame, dismiss it and call -@kbd{M-x speedbar} from that frame. - - The speedbar can operate in various modes. Its default mode is -@dfn{File Display} mode, which shows the files in the current -directory of the selected window of the attached frame, one file per -line. Clicking on a file name visits that file in the selected window -of the attached frame, and clicking on a directory name shows that -directory in the speedbar (@pxref{Mouse References}). Each line also -has a box, @samp{[+]} or @samp{<+>}, that you can click on to -@dfn{expand} the contents of that item. Expanding a directory adds -the contents of that directory to the speedbar display, underneath the -directory's own line. Expanding an ordinary file adds a list of the -tags in that file to the speedbar display; you can click on a tag name -to jump to that tag in the selected window of the attached frame. -When a file or directory is expanded, the @samp{[+]} changes to -@samp{[-]}; you can click on that box to @dfn{contract} the item, -hiding its contents. - - You navigate through the speedbar using the keyboard, too. Typing -@kbd{RET} while point is on a line in the speedbar is equivalent to -clicking the item on the current line, and @kbd{SPC} expands or -contracts the item. @kbd{U} displays the parent directory of the -current directory. To copy, delete, or rename the file on the current -line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a -new directory, type @kbd{M}. - - Another general-purpose speedbar mode is @dfn{Buffer Display} mode; -in this mode, the speedbar displays a list of Emacs buffers. To -switch to this mode, type @kbd{b} in the speedbar. To return to File -Display mode, type @kbd{f}. You can also change the display mode by -clicking @kbd{mouse-3} anywhere in the speedbar window (or -@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the -pop-up menu. - - Some major modes, including Rmail mode, Info, and GUD, have -specialized ways of putting useful items into the speedbar for you to -select. For example, in Rmail mode, the speedbar shows a list of Rmail -files, and lets you move the current message to another Rmail file by -clicking on its @samp{} box. - - For more details on using and programming the speedbar, @xref{Top, -Speedbar,,speedbar, Speedbar Manual}. - -@node Multiple Displays -@section Multiple Displays -@cindex multiple displays - - A single Emacs can talk to more than one X display. Initially, Emacs -uses just one display---the one specified with the @env{DISPLAY} -environment variable or with the @samp{--display} option (@pxref{Initial -Options}). To connect to another display, use the command -@code{make-frame-on-display}: - -@findex make-frame-on-display -@table @kbd -@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} -Create a new frame on display @var{display}. -@end table - - A single X server can handle more than one screen. When you open -frames on two screens belonging to one server, Emacs knows they share a -single keyboard, and it treats all the commands arriving from these -screens as a single stream of input. - - When you open frames on different X servers, Emacs makes a separate -input stream for each server. Each server also has its own selected -frame. The commands you enter with a particular X server apply to -that server's selected frame. - - It is even possible to use this feature to let two or more users -type simultaneously on the two displays, within the same Emacs job. -In practice, however, the different users can easily interfere with -each others' edits if they are not careful. - -@node Special Buffer Frames -@section Special Buffer Frames - -@vindex special-display-buffer-names - You can make certain chosen buffers, which Emacs normally displays -in ``another window,'' appear in special frames of their own. To do -this, set the variable @code{special-display-buffer-names} to a list -of buffer names; any buffer whose name is in that list automatically -gets a special frame, when an Emacs command wants to display it ``in -another window.'' - - For example, if you set the variable this way, - -@example -(setq special-display-buffer-names - '("*Completions*" "*grep*" "*tex-shell*")) -@end example - -@noindent -then completion lists, @code{grep} output and the @TeX{} mode shell -buffer get individual frames of their own. These frames, and the -windows in them, are never automatically split or reused for any other -buffers. They continue to show the buffers they were created for, -unless you alter them by hand. Killing the special buffer deletes its -frame automatically. - -@vindex special-display-regexps - More generally, you can set @code{special-display-regexps} to a list -of regular expressions; then a buffer gets its own frame if its name -matches any of those regular expressions. (Once again, this applies only -to buffers that normally get displayed for you in ``another window.'') - -@vindex special-display-frame-alist - The variable @code{special-display-frame-alist} specifies the frame -parameters for these frames. It has a default value, so you don't need -to set it. - - For those who know Lisp, an element of -@code{special-display-buffer-names} or @code{special-display-regexps} -can also be a list. Then the first element is the buffer name or -regular expression; the rest of the list specifies how to create the -frame. It can be an association list specifying frame parameter -values; these values take precedence over parameter values specified -in @code{special-display-frame-alist}. If you specify the symbol -@code{same-window} as a ``frame parameter'' in this list, with a -non-@code{nil} value, that means to use the selected window if -possible. If you use the symbol @code{same-frame} as a ``frame -parameter'' in this list, with a non-@code{nil} value, that means to -use the selected frame if possible. - - Alternatively, the value can have this form: - -@example -(@var{function} @var{args}...) -@end example - -@noindent -where @var{function} is a symbol. Then the frame is constructed by -calling @var{function}; its first argument is the buffer, and its -remaining arguments are @var{args}. - - An analogous feature lets you specify buffers which should be -displayed in the selected window. @xref{Force Same Window}. The -same-window feature takes precedence over the special-frame feature; -therefore, if you add a buffer name to -@code{special-display-buffer-names} and it has no effect, check to see -whether that feature is also in use for the same buffer name. - -@node Frame Parameters -@section Setting Frame Parameters -@cindex Auto-Raise mode -@cindex Auto-Lower mode - - These commands are available for controlling the window management -behavior of the selected frame: - -@table @kbd -@findex auto-raise-mode -@item M-x auto-raise-mode -Toggle whether or not the selected frame should auto-raise. Auto-raise -means that every time you move the mouse onto the frame, it raises the -frame. - -Some window managers also implement auto-raise. If you enable -auto-raise for Emacs frames in your window manager, it will work, but -it is beyond Emacs' control, so @code{auto-raise-mode} has no effect -on it. - -@findex auto-lower-mode -@item M-x auto-lower-mode -Toggle whether or not the selected frame should auto-lower. -Auto-lower means that every time you move the mouse off the frame, -the frame moves to the bottom of the stack on the screen. - -The command @code{auto-lower-mode} has no effect on auto-lower -implemented by the window manager. To control that, you must use the -appropriate window manager features. -@end table - - In Emacs versions that use an X toolkit, the color-setting and -font-setting functions don't affect menus and the menu bar, since they -are displayed by their own widget classes. To change the appearance of -the menus and menu bar, you must use X resources (@pxref{Resources}). -@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of -font. - - Colors, fonts, and other attributes of the frame's display can also -be customized by setting frame parameters in the variable -@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed -description of frame parameters and customization, see @ref{Frame -Parameters,,, elisp, The Emacs Lisp Reference Manual}. - -@node Scroll Bars -@section Scroll Bars -@cindex Scroll Bar mode -@cindex mode, Scroll Bar - - On graphical displays, Emacs normally makes a @dfn{scroll bar} at -the left of each Emacs window, running the height of the -window.@footnote{Placing it at the left is usually more useful with -overlapping frames with text starting at the left margin.} - - When Emacs is compiled with GTK+ support on the X window system, or -in operating systems such as Microsoft Windows or Mac OS, you can use -the scroll bar as you do in other graphical applications. If you -click @kbd{Mouse-1} on the scroll bar's up and down buttons, that -scrolls the window by one line at a time. Clicking @kbd{Mouse-1} -above or below the scroll bar's inner box scrolls the window by nearly -the entire height of the window, like @kbd{M-v} and @kbd{C-v} -respectively (@pxref{Moving Point}). Dragging the inner box with -@kbd{Mouse-1} scrolls the window continuously. - - If Emacs is compiled without GTK+ support on the X window system, -the scroll bar behaves differently. The scroll bar's inner box is -drawn to represent the portion of the buffer currently displayed, with -the entire height of the scroll bar representing the entire length of -the buffer. @kbd{Mouse-1} anywhere on the scroll bar scrolls forward -like @kbd{C-v}, and @kbd{Mouse-3} scrolls backward like @kbd{M-v}. -Clicking @kbd{Mouse-2} in the scroll bar lets you move or drag the -inner box up and down. - - You can also click @kbd{C-Mouse-2} in the scroll bar to split a -window vertically. The split occurs on the line where you click. - -@findex scroll-bar-mode -@vindex scroll-bar-mode - You can toggle the use of the scroll bar with the command @kbd{M-x -scroll-bar-mode}. With a prefix argument, this command turns use of -scroll bars on if and only if the argument is positive. This command -applies to all frames, including frames yet to be created. Customize -the variable @code{scroll-bar-mode} to control the use of scroll bars -at startup. You can use it to specify that they are placed at the -right of windows if you prefer that. You have to set this variable -through the @samp{Customize} interface (@pxref{Easy Customization}), -or it will not work properly. You can also use the X resource -@samp{verticalScrollBars} to control the initial setting of Scroll Bar -mode. @xref{Resources}. - -@findex toggle-scroll-bar - To enable or disable scroll bars for just the selected frame, use the -command @kbd{M-x toggle-scroll-bar}. - -@vindex scroll-bar-width -@cindex width of the scroll bar - You can control the scroll bar width by changing the value of the -@code{scroll-bar-width} frame parameter. - -@node Wheeled Mice -@section Scrolling With ``Wheeled'' Mice - -@cindex mouse wheel -@cindex wheel, mouse -@findex mouse-wheel-mode -@cindex Mouse Wheel minor mode -@cindex mode, Mouse Wheel - Some mice have a ``wheel'' instead of a third button. You can -usually click the wheel to act as either @kbd{Mouse-2} or -@kbd{Mouse-3}, depending on the setup. You can also use the wheel to -scroll windows instead of using the scroll bar or keyboard commands. -Mouse wheel support only works if the system generates appropriate -events; whenever possible, it is turned on by default. To toggle this -feature, use @kbd{M-x mouse-wheel-mode}. - -@vindex mouse-wheel-follow-mouse -@vindex mouse-wheel-scroll-amount -@vindex mouse-wheel-progressive-speed - The two variables @code{mouse-wheel-follow-mouse} and -@code{mouse-wheel-scroll-amount} determine where and by how much -buffers are scrolled. The variable -@code{mouse-wheel-progressive-speed} determines whether the scroll -speed is linked to how fast you move the wheel. - -@node Drag and Drop -@section Drag and Drop -@cindex drag and drop - - Emacs supports @dfn{drag and drop} using the mouse. For instance, -dropping text onto an Emacs frame inserts the text where it is dropped. -Dropping a file onto an Emacs frame visits that file. As a special -case, dropping the file on a Dired buffer moves or copies the file -(according to the conventions of the application it came from) into the -directory displayed in that buffer. - -@vindex dnd-open-file-other-window - Dropping a file normally visits it in the window you drop it on. If -you prefer to visit the file in a new window in such cases, customize -the variable @code{dnd-open-file-other-window}. - - The XDND and Motif drag and drop protocols, and the old KDE 1.x -protocol, are currently supported. - -@node Menu Bars -@section Menu Bars -@cindex Menu Bar mode -@cindex mode, Menu Bar -@findex menu-bar-mode -@vindex menu-bar-mode - - You can turn display of menu bars on or off with @kbd{M-x -menu-bar-mode} or by customizing the variable @code{menu-bar-mode}. -With no argument, this command toggles Menu Bar mode, a -minor mode. With an argument, the command turns Menu Bar mode on if the -argument is positive, off if the argument is not positive. You can use -the X resource @samp{menuBarLines} to control the initial setting of -Menu Bar mode. @xref{Resources}. - -@kindex C-Mouse-3 @r{(when menu bar is disabled)} - Expert users often turn off the menu bar, especially on text-only -terminals, where this makes one additional line available for text. -If the menu bar is off, you can still pop up a menu of its contents -with @kbd{C-Mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. - - @xref{Menu Bar}, for information on how to invoke commands with the -menu bar. @xref{X Resources}, for how to customize the menu bar -menus' visual appearance. - -@node Tool Bars -@section Tool Bars -@cindex Tool Bar mode -@cindex mode, Tool Bar -@cindex icons, toolbar - - The @dfn{tool bar} is a line (or lines) of icons at the top of the -Emacs window, just below the menu bar. You can click on these icons -with the mouse to do various jobs. - - The global tool bar contains general commands. Some major modes -define their own tool bars to replace it. A few ``special'' modes -that are not designed for ordinary editing remove some items from the -global tool bar. - - Tool bars work only on a graphical display. The tool bar uses colored -XPM icons if Emacs was built with XPM support. Otherwise, the tool -bar uses monochrome icons (PBM or XBM format). - -@findex tool-bar-mode -@vindex tool-bar-mode - You can turn display of tool bars on or off with @kbd{M-x -tool-bar-mode} or by customizing the option @code{tool-bar-mode}. - -@node Dialog Boxes -@section Using Dialog Boxes -@cindex dialog boxes - -@vindex use-dialog-box - A dialog box is a special kind of menu for asking you a yes-or-no -question or some other special question. Many Emacs commands use a -dialog box to ask a yes-or-no question, if you used the mouse to -invoke the command that led to the question. - - To disable the use of dialog boxes, change the variable -@code{use-dialog-box} to @code{nil}. In that case, Emacs always -performs yes-or-no prompts using the echo area and keyboard input. -This variable also controls whether to use file selection windows (but -those are not supported on all platforms). - -@vindex use-file-dialog -@cindex file selection dialog, how to disable - A file selection window is a special kind of dialog box for asking -for file names. You can customize the variable @code{use-file-dialog} -to suppress the use of file selection windows, even if you still want -other kinds of dialogs. This variable has no effect if you have -suppressed all dialog boxes with the variable @code{use-dialog-box}. - -@vindex x-gtk-show-hidden-files -@vindex x-gtk-file-dialog-help-text -@cindex hidden files, in GTK+ file chooser -@cindex help text, in GTK+ file chooser - When Emacs is compiled with GTK+ support, it uses the GTK+ ``file -chooser'' dialog. Emacs adds an additional toggle button to this -dialog, which you can use to enable or disable the display of hidden -files (files starting with a dot) in that dialog. If you want this -toggle to be activated by default, change the variable -@code{x-gtk-show-hidden-files} to @code{t}. In addition, Emacs adds -help text to the GTK+ file chooser dialog; to disable this help text, -change the variable @code{x-gtk-file-dialog-help-text} to @code{nil}. - -@vindex x-gtk-use-old-file-dialog - In GTK+ versions 2.4 through 2.10, you can choose to use an older -version of the GTK+ file dialog by setting the variable -@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If Emacs -is built with a GTK+ version that has only one file dialog, this -variable has no effect. - -@node Tooltips -@section Tooltips -@cindex tooltips - - @dfn{Tooltips} are small windows that display text information at the -current mouse position. They activate when there is a pause in mouse -movement. There are two types of tooltip: help tooltips and GUD -tooltips. - - @dfn{Help tooltips} typically display over text---including the mode -line---but are also available for other parts of the Emacs frame, such -as the tool bar and menu items. - -@findex tooltip-mode - You can toggle display of help tooltips (Tooltip mode) with the -command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the -help text is displayed in the echo area instead. - - @dfn{GUD tooltips} show values of variables. They are useful when -you are debugging a program. @xref{Debugger Operation}. - -@vindex tooltip-delay - The variables @code{tooltip-delay} specifies how long Emacs should -wait before displaying a tooltip. For additional customization -options for displaying tooltips, use @kbd{M-x customize-group -@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on -customizing the windows that display tooltips. - -@node Mouse Avoidance -@section Mouse Avoidance -@cindex avoiding mouse in the way of your typing -@cindex mouse avoidance - -@vindex mouse-avoidance-mode -Mouse Avoidance mode keeps the mouse pointer away from point, to avoid -obscuring text you want to edit. Whenever it moves the mouse, it also -raises the frame. To use Mouse Avoidance mode, customize the variable -@code{mouse-avoidance-mode}. You can set this to various values to -move the mouse in several ways: - -@table @code -@item banish -Move the mouse to the upper-right corner on any key-press; -@item exile -Move the mouse to the corner only if the cursor gets too close, -and allow it to return once the cursor is out of the way; -@item jump -If the cursor gets too close to the mouse, displace the mouse -a random distance & direction; -@item animate -As @code{jump}, but shows steps along the way for illusion of motion; -@item cat-and-mouse -The same as @code{animate}; -@item proteus -As @code{animate}, but changes the shape of the mouse pointer too. -@end table - -@findex mouse-avoidance-mode -You can also use the command @kbd{M-x mouse-avoidance-mode} to enable -the mode. - -@node Non-Window Terminals -@section Non-Window Terminals -@cindex non-window terminals -@cindex single-frame terminals - - On a text-only terminal, Emacs can display only one Emacs frame at a -time. However, you can still create multiple Emacs frames, and switch -between them. Switching frames on these terminals is much like -switching between different window configurations. - - Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x -5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete -the current frame. - - Each frame has a number to distinguish it. If your terminal can -display only one frame at a time, the selected frame's number @var{n} -appears near the beginning of the mode line, in the form -@samp{F@var{n}}. - -@findex set-frame-name -@findex select-frame-by-name - @samp{F@var{n}} is in fact the frame's initial name. You can give -frames more meaningful names if you wish, and you can select a frame -by its name. Use the command @kbd{M-x set-frame-name @key{RET} -@var{name} @key{RET}} to specify a new name for the selected frame, -and use @kbd{M-x select-frame-by-name @key{RET} @var{name} @key{RET}} -to select a frame according to its name. The name you specify appears -in the mode line when the frame is selected. - -@node Text-Only Mouse -@section Using a Mouse in Terminal Emulators -@cindex mouse support -@cindex terminal emulators, mouse support - -Some text-only terminals support mouse clicks in the terminal window. - -@cindex xterm -In a terminal emulator which is compatible with @code{xterm}, -you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over -simple use of the mouse---basically, only non-modified single clicks -are supported. The normal @code{xterm} mouse functionality for such -clicks is still available by holding down the @kbd{SHIFT} key when you -press the mouse button. Xterm Mouse mode is a global minor mode -(@pxref{Minor Modes}). Repeating the command turns the mode off -again. - -@findex gpm-mouse-mode -In the console on GNU/Linux, you can use @kbd{M-x gpm-mouse-mode} to -enable terminal mouse support. You must have the gpm package -installed and running on your system in order for this to work. - -@ignore - arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49 -@end ignore diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi deleted file mode 100644 index 397482e6f1e..00000000000 --- a/doc/emacs/glossary.texi +++ /dev/null @@ -1,1378 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Glossary, Key Index, Intro, Top -@unnumbered Glossary - -@table @asis -@item Abbrev -An abbrev is a text string which expands into a different text string -when present in the buffer. For example, you might define a few letters -as an abbrev for a long phrase that you want to insert frequently. -@xref{Abbrevs}. - -@item Aborting -Aborting means getting out of a recursive edit (q.v.@:). The -commands @kbd{C-]} and @kbd{M-x top-level} are used for this. -@xref{Quitting}. - -@item Alt -Alt is the name of a modifier bit that a keyboard input character may -have. To make a character Alt, type it while holding down the @key{ALT} -key. Such characters are given names that start with @kbd{Alt-} -(usually written @kbd{A-} for short). (Note that many terminals have a -key labeled @key{ALT} that is really a @key{META} key.) @xref{User -Input, Alt}. - -@item Argument -See `numeric argument.' - -@item @acronym{ASCII} character -An @acronym{ASCII} character is either an @acronym{ASCII} control -character or an @acronym{ASCII} printing character. @xref{User Input}. - -@item @acronym{ASCII} control character -An @acronym{ASCII} control character is the Control version of an upper-case -letter, or the Control version of one of the characters @samp{@@[\]^_?}. - -@item @acronym{ASCII} printing character -@acronym{ASCII} printing characters include letters, digits, space, and these -punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}. - -@item Auto Fill Mode -Auto Fill mode is a minor mode (q.v.@:) in which text that you insert is -automatically broken into lines of a given maximum width. -@xref{Filling}. - -@item Auto Saving -Auto saving is the practice of periodically saving the contents of an -Emacs buffer in a specially-named file, so that the information will -be preserved if the buffer is lost due to a system error or user error. -@xref{Auto Save}. - -@item Autoloading -Emacs can automatically load Lisp libraries when a Lisp program requests a -function from those libraries. This is called `autoloading.' -@xref{Lisp Libraries}. - -@item Backtrace -A backtrace is a trace of a series of function calls showing how a -program arrived at a certain point. It is used mainly for finding and -correcting bugs (q.v.@:). Emacs can display a backtrace when it signals -an error or when you type @kbd{C-g} (see `quitting'). @xref{Checklist}. - -@item Backup File -A backup file records the contents that a file had before the current -editing session. Emacs makes backup files automatically to help you -track down or cancel changes you later regret making. @xref{Backup}. - -@item Balancing Parentheses -Emacs can balance parentheses (or other matching delimiters) either -manually or automatically. You do manual balancing with the commands -to move over parenthetical groupings (@pxref{Moving by Parens}). -Automatic balancing works by blinking or highlighting the delimiter -that matches the one you just inserted (@pxref{Matching,,Matching -Parens}). - -@item Balanced Expressions -A balanced expression is a syntactically recognizable expression, such -as a symbol, number, string constant, block, or parenthesized expression -in C. @xref{Expressions,Balanced Expressions}. - -@item Balloon Help -See `tooltips.' - -@item Base Buffer -A base buffer is a buffer whose text is shared by an indirect buffer -(q.v.@:). - -@item Bind -To bind a key sequence means to give it a binding (q.v.@:). -@xref{Rebinding}. - -@item Binding -A key sequence gets its meaning in Emacs by having a binding, which is a -command (q.v.@:), a Lisp function that is run when you type that -sequence. @xref{Commands,Binding}. Customization often involves -rebinding a character to a different command function. The bindings of -all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}. - -@item Blank Lines -Blank lines are lines that contain only whitespace. Emacs has several -commands for operating on the blank lines in the buffer. - -@item Bookmark -Bookmarks are akin to registers (q.v.@:) in that they record positions -in buffers to which you can return later. Unlike registers, bookmarks -persist between Emacs sessions. - -@item Border -A border is a thin space along the edge of the frame, used just for -spacing, not for displaying anything. An Emacs frame has an ordinary -external border, outside of everything including the menu bar, plus an -internal border that surrounds the text windows, their scroll bars -and fringes, and separates them from the menu bar and tool bar. You -can customize both borders with options and resources (@pxref{Borders -X}). Borders are not the same as fringes (q.v.@:). - -@item Buffer -The buffer is the basic editing unit; one buffer corresponds to one text -being edited. You can have several buffers, but at any time you are -editing only one, the `current buffer,' though several can be visible -when you are using multiple windows or frames (q.v.@:). Most buffers -are visiting (q.v.@:) some file. @xref{Buffers}. - -@item Buffer Selection History -Emacs keeps a buffer selection history which records how recently each -Emacs buffer has been selected. This is used for choosing a buffer to -select. @xref{Buffers}. - -@item Bug -A bug is an incorrect or unreasonable behavior of a program, or -inaccurate or confusing documentation. Emacs developers treat bug -reports, both in Emacs code and its documentation, very seriously and -ask you to report any bugs you find. @xref{Bugs}. - -@item Button Down Event -A button down event is the kind of input event (q.v.@:) generated -right away when you press down on a mouse button. @xref{Mouse Buttons}. - -@item By Default -See `default.' - -@item Byte Compilation -See `compilation.' - -@item @kbd{C-} -@kbd{C-} in the name of a character is an abbreviation for Control. -@xref{User Input,C-}. - -@item @kbd{C-M-} -@kbd{C-M-} in the name of a character is an abbreviation for -Control-Meta. If your terminal lacks a real @key{META} key, you type -a Control-Meta character by typing @key{ESC} and then typing the -corresponding Control character. @xref{User Input,C-M-}. - -@item Case Conversion -Case conversion means changing text from upper case to lower case or -vice versa. @xref{Case}, for the commands for case conversion. - -@item Character -Characters form the contents of an Emacs buffer. Also, key sequences -(q.v.@:) are usually made up of characters (though they may include -other input events as well). @xref{User Input}. - -@item Character Set -Emacs supports a number of character sets, each of which represents a -particular alphabet or script. @xref{International}. - -@item Character Terminal -See `text-only terminal.' - -@item Click Event -A click event is the kind of input event (q.v.@:) generated when you -press a mouse button and release it without moving the mouse. -@xref{Mouse Buttons}. - -@item Clipboard -A clipboard is a buffer provided by the window system for transferring -text between applications. On the X Window system, the clipboard is -provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac, -the clipboard is used @emph{instead} of the primary selection. -@xref{Clipboard}. - -@item Coding System -A coding system is an encoding for representing text characters in a -file or in a stream of information. Emacs has the ability to convert -text to or from a variety of coding systems when reading or writing it. -@xref{Coding Systems}. - -@item Command -A command is a Lisp function specially defined to be able to serve as a -key binding in Emacs. When you type a key sequence (q.v.@:), its -binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find -the command to run. @xref{Commands}. - -@item Command History -See `minibuffer history.' - -@item Command Name -A command name is the name of a Lisp symbol which is a command -(@pxref{Commands}). You can invoke any command by its name using -@kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). - -@item Comment -A comment is text in a program which is intended only for humans reading -the program, and which is specially marked so that it will be ignored -when the program is loaded or compiled. Emacs offers special commands -for creating, aligning and killing comments. @xref{Comments}. - -@item Common Lisp -Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful -than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL -package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. - -@item Compilation -Compilation is the process of creating an executable program from source -code. Emacs has commands for compiling files of Emacs Lisp code -(@pxref{Byte Compilation,,, elisp, the Emacs Lisp -Reference Manual}) and programs in C and other languages -(@pxref{Compilation}). - -@item Complete Key -A complete key is a key sequence which fully specifies one action to be -performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} -are complete keys. Complete keys derive their meanings from being bound -(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to -a command to insert @samp{X} in the buffer; @kbd{C-x m} is -conventionally bound to a command to begin composing a mail message. -@xref{Keys}. - -@item Completion -Completion is what Emacs does when it automatically expands an -abbreviation for a name into the entire name. Completion is done for -minibuffer (q.v.@:) arguments when the set of possible valid inputs -is known; for example, on command names, buffer names, and -file names. Completion usually occurs when @key{TAB}, @key{SPC} or -@key{RET} is typed. @xref{Completion}.@refill - -@item Continuation Line -When a line of text is longer than the width of the window, it -normally (but see `Truncation') takes up more than one screen line -when displayed. We say that the text line is continued, and all -screen lines used for it after the first are called continuation -lines. @xref{Continuation Lines}. A related Emacs feature is -`filling' (q.v.@:). - -@item Control Character -A control character is a character that you type by holding down the -@key{CTRL} key. Some control characters also have their own keys, so -that you can type them without using @key{CTRL}. For example, -@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control -characters. @xref{User Input}. - -@item Copyleft -A copyleft is a notice giving the public legal permission to -redistribute and modify a program or other work of art, but requiring -modified versions to carry similar permission. Copyright is normally -used to keep users divided and helpless; with copyleft we turn that -around to empower users and encourage them to cooperate. - -The particular form of copyleft used by the GNU project is called the -GNU General Public License. @xref{Copying}. - -@item @key{CTRL} -The @key{CTRL} or ``control'' key is what you hold down -in order to enter a control character (q.v.). See also `@kbd{C-}.' - -@item Current Buffer -The current buffer in Emacs is the Emacs buffer on which most editing -commands operate. You can select any Emacs buffer as the current one. -@xref{Buffers}. - -@item Current Line -The current line is the line that point is on (@pxref{Point}). - -@item Current Paragraph -The current paragraph is the paragraph that point is in. If point is -between two paragraphs, the current paragraph is the one that follows -point. @xref{Paragraphs}. - -@item Current Defun -The current defun is the defun (q.v.@:) that point is in. If point is -between defuns, the current defun is the one that follows point. -@xref{Defuns}. - -@item Cursor -The cursor is the rectangle on the screen which indicates the position -(called point; q.v.@:) at which insertion and deletion takes place. -The cursor is on or under the character that follows point. Often -people speak of `the cursor' when, strictly speaking, they mean -`point.' @xref{Point,Cursor}. - -@item Customization -Customization is making minor changes in the way Emacs works, to -reflect your preferences or needs. It is often done by setting -variables (@pxref{Variables}) or faces (@pxref{Face Customization}), -or by rebinding key sequences (@pxref{Keymaps}). - -@cindex cut and paste -@item Cut and Paste -See `killing' and `yanking.' - -@item Daemon -A daemon is a standard term for a system-level process that runs in the -background. Daemons are often started when the system first starts up. -When Emacs runs in daemon-mode, it runs in the background and does not -open a display. You can then connect to it with the -@command{emacsclient} program. @xref{Emacs Server}. - -@item Default Argument -The default for an argument is the value that will be assumed if you -do not specify one. When the minibuffer is used to read an argument, -the default argument is used if you just type @key{RET}. -@xref{Minibuffer}. - -@item Default -A default is the value that is used for a certain purpose if and when -you do not specify a value to use. - -@item Default Directory -When you specify a file name that does not start with @samp{/} or @samp{~}, -it is interpreted relative to the current buffer's default directory. -(On MS-Windows and MS-DOS, file names which start with a drive letter -@samp{@var{x}:} are treated as absolute, not relative.) -@xref{Minibuffer File,Default Directory}. - -@item Defun -A defun is a major definition at the top level in a program. The name -`defun' comes from Lisp, where most such definitions use the construct -@code{defun}. @xref{Defuns}. - -@item @key{DEL} -@key{DEL} is a character that runs the command to delete one character -of text before the cursor. It is typically either the @key{DELETE} -key or the @key{BACKSPACE} key, whichever one is easy to type. -@xref{Erasing,DEL}. - -@item Deletion -Deletion means erasing text without copying it into the kill ring -(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}. - -@item Deletion of Files -Deleting a file means erasing it from the file system. -(Note that some systems use the concept of a ``trash can'', or ``recycle -bin'', to allow you to ``undelete'' files.) -@xref{Misc File Ops,Misc File Ops,Miscellaneous File Operations}. - -@item Deletion of Messages -Deleting a message (in Rmail, and other mail clients) means flagging -it to be eliminated from your mail file. Until you expunge (q.v.@:) -the Rmail file, you can still undelete the messages you have deleted. -@xref{Rmail Deletion}. - -@item Deletion of Windows -Deleting a window means eliminating it from the screen. Other windows -expand to use up the space. The text that was in the window is not -lost, and you can create a new window with the same dimensions as the -old if you wish. @xref{Windows}. - -@item Directory -File directories are named collections in the file system, within which -you can place individual files or subdirectories. They are sometimes -referred to as ``folders.'' @xref{Directories}. - -@item Dired -Dired is the Emacs facility that displays the contents of a file -directory and allows you to ``edit the directory,'' performing -operations on the files in the directory. @xref{Dired}. - -@item Disabled Command -A disabled command is one that you may not run without special -confirmation. The usual reason for disabling a command is that it is -confusing for beginning users. @xref{Disabling}. - -@item Down Event -Short for `button down event' (q.v.@:). - -@item Drag Event -A drag event is the kind of input event (q.v.@:) generated when you -press a mouse button, move the mouse, and then release the button. -@xref{Mouse Buttons}. - -@item Dribble File -A dribble file is a file into which Emacs writes all the characters that -you type on the keyboard. Dribble files can be used to make a record -for debugging Emacs bugs. Emacs does not make a dribble file unless you -tell it to. @xref{Bugs}. - -@item Echo Area -The echo area is the bottom line of the screen, used for echoing the -arguments to commands, for asking questions, and showing brief messages -(including error messages). The messages are stored in the buffer -@samp{*Messages*} so you can review them later. @xref{Echo Area}. - -@item Echoing -Echoing is acknowledging the receipt of input events by displaying -them (in the echo area). Emacs never echoes single-character key -sequences; longer key sequences echo only if you pause while typing -them. - -@item Electric -We say that a character is electric if it is normally self-inserting -(q.v.@:), but the current major mode (q.v.@:) redefines it to do something -else as well. For example, some programming language major modes define -particular delimiter characters to reindent the line, or insert one or -more newlines in addition to self-insertion. - -@item End Of Line -End of line is a character or a sequence of characters that indicate -the end of a text line. On GNU and Unix systems, this is a newline -(q.v.@:), but other systems have other conventions. @xref{Coding -Systems,end-of-line}. Emacs can recognize several end-of-line -conventions in files and convert between them. - -@item Environment Variable -An environment variable is one of a collection of variables stored by -the operating system, each one having a name and a value. Emacs can -access environment variables set by its parent shell, and it can set -variables in the environment it passes to programs it invokes. -@xref{Environment}. - -@item EOL -See `end of line.' - -@item Error -An error occurs when an Emacs command cannot execute in the current -circumstances. When an error occurs, execution of the command stops -(unless the command has been programmed to do otherwise) and Emacs -reports the error by displaying an error message (q.v.@:). -@c Not helpful? -@c Type-ahead is discarded. Then Emacs is ready to read another -@c editing command. - -@item Error Message -An error message is output displayed by Emacs when you ask it to do -something impossible (such as, killing text forward when point is at -the end of the buffer), or when a command malfunctions in some way. -Such messages appear in the echo area, accompanied by a beep. - -@item @key{ESC} -@key{ESC} is a character used as a prefix for typing Meta characters on -keyboards lacking a @key{META} key. Unlike the @key{META} key (which, -like the @key{SHIFT} key, is held down while another character is -typed), you press the @key{ESC} key as you would press a letter key, and -it applies to the next character you type. - -@item Expression -See `balanced expression.' - -@item Expunging -Expunging an Rmail, Gnus newsgroup, or Dired buffer is an operation -that truly discards the messages or files you have previously flagged -for deletion. - -@item Face -A face is a style of displaying characters. It specifies attributes -such as font family and size, foreground and background colors, -underline and strike-through, background stipple, etc. Emacs provides -features to associate specific faces with portions of buffer text, in -order to display that text as specified by the face attributes. -@xref{Faces}. - -@item File Locking -Emacs uses file locking to notice when two different users -start to edit one file at the same time. @xref{Interlocking}. - -@item File Name -A file name is a name that refers to a file. File names may be relative -or absolute; the meaning of a relative file name depends on the current -directory, but an absolute file name refers to the same file regardless -of which directory is current. On GNU and Unix systems, an absolute -file name starts with a slash (the root directory) or with @samp{~/} or -@samp{~@var{user}/} (a home directory). On MS-Windows/MS-DOS, an -absolute file name can also start with a drive letter and a colon, e.g. -@samp{@var{d}:}. - -Some people use the term ``pathname'' for file names, but we do not; -we use the word ``path'' only in the term ``search path'' (q.v.@:). - -@item File-Name Component -A file-name component names a file directly within a particular -directory. On GNU and Unix systems, a file name is a sequence of -file-name components, separated by slashes. For example, @file{foo/bar} -is a file name containing two components, @samp{foo} and @samp{bar}; it -refers to the file named @samp{bar} in the directory named @samp{foo} in -the current directory. MS-DOS/MS-Windows file names can also use -backslashes to separate components, as in @file{foo\bar}. - -@item Fill Prefix -The fill prefix is a string that should be expected at the beginning -of each line when filling is done. It is not regarded as part of the -text to be filled. @xref{Filling}. - -@item Filling -Filling text means adjusting the position of line-breaks to shift text -between consecutive lines, so that all the lines are approximately the -same length. @xref{Filling}. Some other editors call this feature -`line wrapping.' - -@item Font Lock -Font Lock is a mode that highlights parts of buffer text in different -faces, according to the syntax. For example, all comments (q.v.@:) -might be colored red. @xref{Font Lock}. - -@item Fontset -A fontset is a named collection of fonts. A fontset specification lists -character sets and which font to use to display each of them. Fontsets -make it easy to change several fonts at once by specifying the name of a -fontset, rather than changing each font separately. @xref{Fontsets}. - -@item Formatted Text -Formatted text is text that displays with formatting information while -you edit. Formatting information includes fonts, colors, and specified -margins. @xref{Formatted Text}. - -@item Formfeed Character -See `page.' - -@item Frame -A frame is a rectangular cluster of Emacs windows. Emacs starts out -with one frame, but you can create more. You can subdivide each frame -into Emacs windows (q.v.@:). When you are using a window system -(q.v.@:), more than one frame can be visible at the same time. -@xref{Frames}. Some other editors use the term ``window'' for this, -but in Emacs a window means something else. - -@item Free Software -Free software is software that gives you the freedom to share, study -and modify it. Emacs is free software, part of the GNU project -(q.v.@:), and distributed under a copyleft (q.v.@:) license called the -GNU General Public License. @xref{Copying}. - -@item Free Software Foundation -The Free Software Foundation (FSF) is a charitable foundation -dedicated to promoting the development of free software (q.v.@:). -For more information, see @uref{http://fsf.org/, the FSF website}. - -@item Fringe -On a graphical display (q.v.@:), there's a narrow portion of the frame -(q.v.@:) between the text area and the window's border. These -`fringes' are used to display symbols that provide information about -the buffer text (@pxref{Fringes}). Emacs displays the fringe using a -special face (q.v.@:) called @code{fringe}. @xref{Faces,fringe}. - -@item FSF -See `Free Software Foundation.' - -@item FTP -FTP is an acronym for File Transfer Protocol. This is one standard -method for retrieving remote files (q.v.@:). - -@item Function Key -A function key is a key on the keyboard that sends input but does not -correspond to any character. @xref{Function Keys}. - -@item Global -Global means ``independent of the current environment; in effect -throughout Emacs.'' It is the opposite of local (q.v.@:). Particular -examples of the use of `global' appear below. - -@item Global Abbrev -A global definition of an abbrev (q.v.@:) is effective in all major -modes that do not have local (q.v.@:) definitions for the same abbrev. -@xref{Abbrevs}. - -@item Global Keymap -The global keymap (q.v.@:) contains key bindings that are in effect -everywhere, except when overridden by local key bindings in a major -mode's local keymap (q.v.@:). @xref{Keymaps}. - -@item Global Mark Ring -The global mark ring records the series of buffers you have recently -set a mark (q.v.@:) in. In many cases you can use this to backtrack -through buffers you have been editing, or in which you have found -tags (see `tags table'). @xref{Global Mark Ring}. - -@item Global Substitution -Global substitution means replacing each occurrence of one string by -another string throughout a large amount of text. @xref{Replace}. - -@item Global Variable -The global value of a variable (q.v.@:) takes effect in all buffers -that do not have their own local (q.v.@:) values for the variable. -@xref{Variables}. - -@item GNU -GNU is a recursive acronym for GNU's Not Unix, and it refers to a -Unix-compatible operating system which is free software (q.v.@:). -@xref{Manifesto}. GNU is normally used with Linux as the kernel since -Linux works better than the GNU kernel. For more information, see -@uref{http://www.gnu.org/, the GNU website}. - -@item Graphic Character -Graphic characters are those assigned pictorial images rather than -just names. All the non-Meta (q.v.@:) characters except for the -Control (q.v.@:) characters are graphic characters. These include -letters, digits, punctuation, and spaces; they do not include -@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts -that character (in ordinary editing modes). @xref{Inserting Text}. - -@item Graphical Display -A graphical display is one that can display images and multiple fonts. -Usually it also has a window system (q.v.@:). - -@item Highlighting -Highlighting text means displaying it with a different foreground and/or -background color to make it stand out from the rest of the text in the -buffer. - -Emacs uses highlighting in several ways. It highlights the region -whenever it is active (@pxref{Mark}). Incremental search also -highlights matches (@pxref{Incremental Search}). See also `font lock.' - -@item Hardcopy -Hardcopy means printed output. Emacs has various commands for -printing the contents of Emacs buffers. @xref{Printing}. - -@item @key{HELP} -@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type -@key{HELP} at any time to ask what options you have, or to ask what any -command does. @xref{Help}. - -@item Help Echo -Help echo is a short message displayed in the echo area (q.v.@:) when -the mouse pointer is located on portions of display that require some -explanations. Emacs displays help echo for menu items, parts of the -mode line, tool-bar buttons, etc. On graphics displays, the messages -can be displayed as tooltips (q.v.@:). @xref{Tooltips}. - -@item Home Directory -Your home directory contains your personal files. On a multi-user GNU -or Unix system, each user has his or her own home directory. When you -start a new login session, your home directory is the default -directory in which to start. A standard shorthand for your home -directory is @samp{~}. Similarly, @samp{~@var{user}} represents the -home directory of some other user. - -@item Hook -A hook is a list of functions to be called on specific occasions, such -as saving a buffer in a file, major mode activation, etc. By -customizing the various hooks, you can modify Emacs's behavior without -changing any of its code. @xref{Hooks}. - -@item Hyper -Hyper is the name of a modifier bit that a keyboard input character may -have. To make a character Hyper, type it while holding down the -@key{HYPER} key. Such characters are given names that start with -@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input}. - -@item Iff -``Iff'' means ``if and only if.'' This terminology comes from -mathematics. Try to avoid using this term in documentation, since -many are unfamiliar with it and mistake it for a typo. - -@item Inbox -An inbox is a file in which mail is delivered by the operating system. -Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the -mail is then stored permanently or until explicitly deleted. -@xref{Rmail Inbox}. - -@item Incremental Search -Emacs provides an incremental search facility, whereby Emacs begins -searching for a string as soon as you type the first character. -As you type more characters, it refines the search. @xref{Incremental Search}. - -@item Indentation -Indentation means blank space at the beginning of a line. Most -programming languages have conventions for using indentation to -illuminate the structure of the program, and Emacs has special -commands to adjust indentation. -@xref{Indentation}. - -@item Indirect Buffer -An indirect buffer is a buffer that shares the text of another buffer, -called its base buffer (q.v.@:). @xref{Indirect Buffers}. - -@item Info -Info is the hypertext format used by the GNU project for writing -documentation. - -@item Input Event -An input event represents, within Emacs, one action taken by the user on -the terminal. Input events include typing characters, typing function -keys, pressing or releasing mouse buttons, and switching between Emacs -frames. @xref{User Input}. - -@item Input Method -An input method is a system for entering non-@acronym{ASCII} text characters by -typing sequences of @acronym{ASCII} characters (q.v.@:). @xref{Input Methods}. - -@item Insertion -Insertion means adding text into the buffer, either from the keyboard -or from some other place in Emacs. - -@item Interlocking -Interlocking is a feature for warning when you start to alter a file -that someone else is already editing. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item Isearch -See `incremental search.' - -@item Justification -Justification means adding extra spaces within lines of text -in order to adjust the position of the text edges. -@xref{Format Justification}. - -@item Key Binding -See `binding.' - -@item Keyboard Macro -Keyboard macros are a way of defining new Emacs commands from -sequences of existing ones, with no need to write a Lisp program. -You can use a macro to record a sequence of commands, then -play them back as many times as you like. -@xref{Keyboard Macros}. - -@cindex keyboard shortcuts -@item Keyboard Shortcut -A keyboard shortcut is a key sequence (q.v.@:) which invokes a -command. What some programs call ``assigning a keyboard shortcut,'' -Emacs calls ``binding a key sequence.'' See `binding.' - -@item Key Sequence -A key sequence (key, for short) is a sequence of input events (q.v.@:) -that are meaningful as a single unit. If the key sequence is enough to -specify one action, it is a complete key (q.v.@:); if it is not enough, -it is a prefix key (q.v.@:). @xref{Keys}. - -@item Keymap -The keymap is the data structure that records the bindings (q.v.@:) of -key sequences to the commands that they run. For example, the global -keymap binds the character @kbd{C-n} to the command function -@code{next-line}. @xref{Keymaps}. - -@item Keyboard Translation Table -The keyboard translation table is an array that translates the character -codes that come from the terminal into the character codes that make up -key sequences. - -@item Kill Ring -The kill ring is where all text you have killed recently is saved. -You can reinsert any of the killed text still in the ring; this is -called yanking (q.v.@:). @xref{Yanking}. - -@item Killing -Killing means erasing text and saving it on the kill ring so it can be -yanked (q.v.@:) later. Some other systems call this ``cutting.'' -Most Emacs commands that erase text perform killing, as opposed to -deletion (q.v.@:). @xref{Killing}. - -@item Killing a Job -Killing a job (such as, an invocation of Emacs) means making it cease -to exist. Any data within it, if not saved in a file, is lost. -@xref{Exiting}. - -@item Language Environment -Your choice of language environment specifies defaults for the input -method (q.v.@:) and coding system (q.v.@:). @xref{Language -Environments}. These defaults are relevant if you edit -non-@acronym{ASCII} text (@pxref{International}). - -@item Line Wrapping -See `filling.' - -@item Lisp -Lisp is a programming language. Most of Emacs is written in a dialect -of Lisp, called Emacs Lisp, which is extended with special features that -make it especially suitable for text editing tasks. - -@item List -A list is, approximately, a text string beginning with an open -parenthesis and ending with the matching close parenthesis. In C mode -and other non-Lisp modes, groupings surrounded by other kinds of matched -delimiters appropriate to the language, such as braces, are also -considered lists. Emacs has special commands for many operations on -lists. @xref{Moving by Parens}. - -@item Local -Local means ``in effect only in a particular context''; the relevant -kind of context is a particular function execution, a particular -buffer, or a particular major mode. It is the opposite of `global' -(q.v.@:). Specific uses of `local' in Emacs terminology appear below. - -@item Local Abbrev -A local abbrev definition is effective only if a particular major mode -is selected. In that major mode, it overrides any global definition -for the same abbrev. @xref{Abbrevs}. - -@item Local Keymap -A local keymap is used in a particular major mode; the key bindings -(q.v.@:) in the current local keymap override global bindings of the -same key sequences. @xref{Keymaps}. - -@item Local Variable -A local value of a variable (q.v.@:) applies to only one buffer. -@xref{Locals}. - -@item @kbd{M-} -@kbd{M-} in the name of a character is an abbreviation for @key{META}, -one of the modifier keys that can accompany any character. -@xref{User Input,M-}. - -@item @kbd{M-C-} -@kbd{M-C-} in the name of a character is an abbreviation for -Control-Meta; it means the same thing as `@kbd{C-M-}' (q.v.@:). - -@item @kbd{M-x} -@kbd{M-x} is the key sequence that is used to call an Emacs command by -name. This is how you run commands that are not bound to key sequences. -@xref{M-x,M-x,Running Commands by Name}. - -@item Mail -Mail means messages sent from one user to another through the computer -system, to be read at the recipient's convenience. Emacs has commands for -composing and sending mail, and for reading and editing the mail you have -received. @xref{Sending Mail}. @xref{Rmail}, for one way to read -mail with Emacs. - -@item Mail Composition Method -A mail composition method is a program runnable within Emacs for editing -and sending a mail message. Emacs lets you select from several -alternative mail composition methods. @xref{Mail Methods}. - -@item Major Mode -The Emacs major modes are a mutually exclusive set of options, each of -which configures Emacs for editing a certain sort of text. Ideally, -each programming language has its own major mode. @xref{Major Modes}. - -@item Margin -The space between the usable part of a window (including the -fringe) and the window edge. - -@item Mark -The mark points to a position in the text. It specifies one end of the -region (q.v.@:), point being the other end. Many commands operate on -all the text from point to the mark. Each buffer has its own mark. -@xref{Mark}. - -@item Mark Ring -The mark ring is used to hold several recent previous locations of the -mark, just in case you want to move back to them. Each buffer has its -own mark ring; in addition, there is a single global mark ring (q.v.@:). -@xref{Mark Ring}. - -@item Menu Bar -The menu bar is a line at the top of an Emacs frame. It contains -words you can click on with the mouse to bring up menus, or you can use -a keyboard interface to navigate it. @xref{Menu Bars}. - -@item Message -See `mail.' - -@item Meta -Meta is the name of a modifier bit which you can use in a command -character. To enter a meta character, you hold down the @key{META} -key while typing the character. We refer to such characters with -names that start with @kbd{Meta-} (usually written @kbd{M-} for -short). For example, @kbd{M-<} is typed by holding down @key{META} -and at the same time typing @kbd{<} (which itself is done, on most -terminals, by holding down @key{SHIFT} and typing @kbd{,}). -@xref{User Input,Meta}. - -On some terminals, the @key{META} key is actually labeled @key{ALT} -or @key{EDIT}. - -@item Meta Character -A Meta character is one whose character code includes the Meta bit. - -@item Minibuffer -The minibuffer is the window that appears when necessary inside the -echo area (q.v.@:), used for reading arguments to commands. -@xref{Minibuffer}. - -@item Minibuffer History -The minibuffer history records the text you have specified in the past -for minibuffer arguments, so you can conveniently use the same text -again. @xref{Minibuffer History}. - -@item Minor Mode -A minor mode is an optional feature of Emacs which can be switched on -or off independently of all other features. Each minor mode has a -command to turn it on or off. Some minor modes are global (q.v.@:), -and some are local (q.v.@:). @xref{Minor Modes}. - -@item Minor Mode Keymap -A minor mode keymap is a keymap that belongs to a minor mode and is -active when that mode is enabled. Minor mode keymaps take precedence -over the buffer's local keymap, just as the local keymap takes -precedence over the global keymap. @xref{Keymaps}. - -@item Mode Line -The mode line is the line at the bottom of each window (q.v.@:), giving -status information on the buffer displayed in that window. @xref{Mode -Line}. - -@item Modified Buffer -A buffer (q.v.@:) is modified if its text has been changed since the -last time the buffer was saved (or since it was created, if it -has never been saved). @xref{Saving}. - -@item Moving Text -Moving text means erasing it from one place and inserting it in -another. The usual way to move text is by killing (q.v.@:) it and then -yanking (q.v.@:) it. @xref{Killing}. - -@item MULE -MULE refers to the Emacs features for editing multilingual -non-@acronym{ASCII} text using multibyte characters (q.v.@:). -@xref{International}. - -@item Multibyte Character -A multibyte character is a character that takes up several bytes in a -buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, -since the number of non-@acronym{ASCII} characters is much more than 256. -@xref{International Chars, International Characters}. - -@item Named Mark -A named mark is a register (q.v.@:) in its role of recording a -location in text so that you can move point to that location. -@xref{Registers}. - -@item Narrowing -Narrowing means creating a restriction (q.v.@:) that limits editing in -the current buffer to only a part of the text. Text outside that part -is inaccessible for editing (or viewing) until the boundaries are -widened again, but it is still there, and saving the file saves it -all. @xref{Narrowing}. - -@item Newline -Control-J characters in the buffer terminate lines of text and are -therefore also called newlines. See `End of Line.' - -@cindex nil -@cindex t -@item @code{nil} -@code{nil} is a value usually interpreted as a logical ``false.'' Its -opposite is @code{t}, interpreted as ``true.'' - -@item Numeric Argument -A numeric argument is a number, specified before a command, to change -the effect of the command. Often the numeric argument serves as a -repeat count. @xref{Arguments}. - -@item Overwrite Mode -Overwrite mode is a minor mode. When it is enabled, ordinary text -characters replace the existing text after point rather than pushing -it to the right. @xref{Minor Modes}. - -@item Page -A page is a unit of text, delimited by formfeed characters (@acronym{ASCII} -control-L, code 014) coming at the beginning of a line. Some Emacs -commands are provided for moving over and operating on pages. -@xref{Pages}. - -@item Paragraph -Paragraphs are the medium-size unit of human-language text. There are -special Emacs commands for moving over and operating on paragraphs. -@xref{Paragraphs}. - -@item Parsing -We say that certain Emacs commands parse words or expressions in the -text being edited. Really, all they know how to do is find the other -end of a word or expression. @xref{Syntax}. - -@item Point -Point is the place in the buffer at which insertion and deletion -occur. Point is considered to be between two characters, not at one -character. The terminal's cursor (q.v.@:) indicates the location of -point. @xref{Point}. - -@item Prefix Argument -See `numeric argument.' - -@item Prefix Key -A prefix key is a key sequence (q.v.@:) whose sole function is to -introduce a set of longer key sequences. @kbd{C-x} is an example of -prefix key; any two-character sequence starting with @kbd{C-x} is -therefore a legitimate key sequence. @xref{Keys}. - -@item Primary Rmail File -Your primary Rmail file is the file named @samp{RMAIL} in your home -directory. That's where Rmail stores your incoming mail, unless you -specify a different file name. @xref{Rmail}. - -@item Primary Selection -The primary selection is one particular X selection (q.v.@:); it is the -selection that most X applications use for transferring text to and from -other applications. - -The Emacs kill commands set the primary selection and the yank command -uses the primary selection when appropriate. @xref{Killing}. - -@item Prompt -A prompt is text used to ask you for input. Displaying a prompt -is called prompting. Emacs prompts always appear in the echo area -(q.v.@:). One kind of prompting happens when the minibuffer is used to -read an argument (@pxref{Minibuffer}); the echoing that happens when -you pause in the middle of typing a multi-character key sequence is also -a kind of prompting (@pxref{Echo Area}). - -@item Query-Replace -Query-replace is an interactive string replacement feature provided by -Emacs. @xref{Query Replace}. - -@item Quitting -Quitting means canceling a partially typed command or a running -command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. - -@item Quoting -Quoting means depriving a character of its usual special significance. -The most common kind of quoting in Emacs is with @kbd{C-q}. What -constitutes special significance depends on the context and on -convention. For example, an ``ordinary'' character as an Emacs command -inserts itself; so in this context, a special character is any character -that does not normally insert itself (such as @key{DEL}, for example), -and quoting it makes it insert itself as if it were not special. Not -all contexts allow quoting. @xref{Inserting Text,Quoting}. - -@item Quoting File Names -Quoting a file name turns off the special significance of constructs -such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. - -@item Read-Only Buffer -A read-only buffer is one whose text you are not allowed to change. -Normally Emacs makes buffers read-only when they contain text which -has a special significance to Emacs; for example, Dired buffers. -Visiting a file that is write-protected also makes a read-only buffer. -@xref{Buffers}. - -@item Rectangle -A rectangle consists of the text in a given range of columns on a given -range of lines. Normally you specify a rectangle by putting point at -one corner and putting the mark at the diagonally opposite corner. -@xref{Rectangles}. - -@item Recursive Editing Level -A recursive editing level is a state in which part of the execution of -a command involves asking you to edit some text. This text may -or may not be the same as the text to which the command was applied. -The mode line indicates recursive editing levels with square brackets -(@samp{[} and @samp{]}). @xref{Recursive Edit}. - -@item Redisplay -Redisplay is the process of correcting the image on the screen to -correspond to changes that have been made in the text being edited. -@xref{Screen,Redisplay}. - -@item Regexp -See `regular expression.' - -@item Region -The region is the text between point (q.v.@:) and the mark (q.v.@:). -Many commands operate on the text of the region. @xref{Mark,Region}. - -@item Register -Registers are named slots in which text, buffer positions, or -rectangles can be saved for later use. @xref{Registers}. A related -Emacs feature is `bookmarks' (q.v.@:). - -@item Regular Expression -A regular expression is a pattern that can match various text strings; -for example, @samp{a[0-9]+} matches @samp{a} followed by one or more -digits. @xref{Regexps}. - -@item Remote File -A remote file is a file that is stored on a system other than your own. -Emacs can access files on other computers provided that they are -connected to the same network as your machine, and (obviously) that -you have a supported method to gain access to those files. -@xref{Remote Files}. - -@item Repeat Count -See `numeric argument.' - -@item Replacement -See `global substitution.' - -@item Restriction -A buffer's restriction is the amount of text, at the beginning or the -end of the buffer, that is temporarily inaccessible. Giving a buffer a -nonzero amount of restriction is called narrowing (q.v.@:); removing -a restriction is called widening (q.v.@:). @xref{Narrowing}. - -@item @key{RET} -@key{RET} is a character that in Emacs runs the command to insert a -newline into the text. It is also used to terminate most arguments -read in the minibuffer (q.v.@:). @xref{User Input,Return}. - -@item Reverting -Reverting means returning to the original state. Emacs lets you -revert a buffer by re-reading its file from disk. @xref{Reverting}. - -@item Rmail File -An Rmail file is a file containing text in the format used by -Rmail for storing mail. @xref{Rmail}. - -@item Saving -Saving a buffer means copying its text into the file that was visited -(q.v.@:) in that buffer. This is the way text in files actually gets -changed by your Emacs editing. @xref{Saving}. - -@item Scroll Bar -A scroll bar is a tall thin hollow box that appears at the side of a -window. You can use mouse commands in the scroll bar to scroll the -window. The scroll bar feature is supported only under windowing -systems. @xref{Scroll Bars}. - -@item Scrolling -Scrolling means shifting the text in the Emacs window so as to see a -different part of the buffer. @xref{Scrolling}. - -@item Searching -Searching means moving point to the next occurrence of a specified -string or the next match for a specified regular expression. -@xref{Search}. - -@item Search Path -A search path is a list of directory names, to be used for searching for -files for certain purposes. For example, the variable @code{load-path} -holds a search path for finding Lisp library files. @xref{Lisp Libraries}. - -@item Secondary Selection -The secondary selection is one particular X selection (q.v.@:); some X -applications can use it for transferring text to and from other -applications. Emacs has special mouse commands for transferring text -using the secondary selection. @xref{Secondary Selection}. - -@item Selected Frame -The selected frame is the one your input currently operates on. -@xref{Frames}. - -@item Selected Window -The selected window is the one your input currently operates on. -@xref{Basic Window}. - -@item Selecting a Buffer -Selecting a buffer means making it the current (q.v.@:) buffer. -@xref{Select Buffer}. - -@item Selection -Windowing systems allow an application program to specify -selections whose values are text. A program can also read the -selections that other programs have set up. This is the principal way -of transferring text between window applications. Emacs has commands to -work with the primary (q.v.@:) selection and the secondary (q.v.@:) -selection, and also with the clipboard (q.v.@:). - -@item Self-Documentation -Self-documentation is the feature of Emacs that can tell you what any -command does, or give you a list of all commands related to a topic -you specify. You ask for self-documentation with the help character, -@kbd{C-h}. @xref{Help}. - -@item Self-Inserting Character -A character is self-inserting if typing that character inserts that -character in the buffer. Ordinary printing and whitespace characters -are self-inserting in Emacs, except in certain special major modes. - -@item Sentences -Emacs has commands for moving by or killing by sentences. -@xref{Sentences}. - -@item Sexp -A sexp (short for ``s-expression'') is the basic syntactic unit of -Lisp in its textual form: either a list, or Lisp atom. Sexps are also -the balanced expressions (q.v.@:) of the Lisp language; this is why -the commands for editing balanced expressions have `sexp' in their -name. @xref{Expressions,Sexps}. - -@item Simultaneous Editing -Simultaneous editing means two users modifying the same file at once. -Simultaneous editing, if not detected, can cause one user to lose his -or her work. Emacs detects all cases of simultaneous editing, and -warns one of the users to investigate. -@xref{Interlocking,Interlocking,Simultaneous Editing}. - -@item @key{SPC} -@key{SPC} is the space character, which you enter by pressing the -space bar. - -@item Speedbar -The speedbar is a special tall frame that provides fast access to Emacs -buffers, functions within those buffers, Info nodes, and other -interesting parts of text within Emacs. @xref{Speedbar}. - -@item Spell Checking -Spell checking means checking correctness of the written form of each -one of the words in a text. Emacs can use various external -spelling-checker programs to check the spelling of parts of a buffer -via a convenient user interface. @xref{Spelling}. - -@item String -A string is a kind of Lisp data object which contains a sequence of -characters. Many Emacs variables are intended to have strings as -values. The Lisp syntax for a string consists of the characters in the -string with a @samp{"} before and another @samp{"} after. A @samp{"} -that is part of the string must be written as @samp{\"} and a @samp{\} -that is part of the string must be written as @samp{\\}. All other -characters, including newline, can be included just by writing them -inside the string; however, backslash sequences as in C, such as -@samp{\n} for newline or @samp{\241} using an octal character code, are -allowed as well. - -@item String Substitution -See `global substitution.' - -@item Syntax Highlighting -See `font lock.' - -@item Syntax Table -The syntax table tells Emacs which characters are part of a word, -which characters balance each other like parentheses, etc. -@xref{Syntax}. - -@item Super -Super is the name of a modifier bit that a keyboard input character may -have. To make a character Super, type it while holding down the -@key{SUPER} key. Such characters are given names that start with -@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input}. - -@item Suspending -Suspending Emacs means stopping it temporarily and returning control -to its parent process, which is usually a shell. Unlike killing a job -(q.v.@:), you can later resume the suspended Emacs job without losing -your buffers, unsaved edits, undo history, etc. @xref{Exiting}. - -@item @key{TAB} -@key{TAB} is the tab character. In Emacs it is typically used for -indentation or completion. - -@item Tags Table -A tags table is a file that serves as an index to the function -definitions in one or more other files. @xref{Tags}. - -@item Termscript File -A termscript file contains a record of all characters sent by Emacs to -the terminal. It is used for tracking down bugs in Emacs redisplay. -Emacs does not make a termscript file unless you tell it to. -@xref{Bugs}. - -@item Text -`Text' has two meanings (@pxref{Text}): - -@itemize @bullet -@item -Data consisting of a sequence of characters, as opposed to binary -numbers, executable programs, and the like. The basic contents of an -Emacs buffer (aside from the text properties, q.v.@:) are always text -in this sense. -@item -Data consisting of written human language (as opposed to programs), -or following the stylistic conventions of human language. -@end itemize - -@item Text-only Terminal -A text-only terminal is a display that is limited to displaying text in -character units. Such a terminal cannot control individual pixels it -displays. Emacs supports a subset of display features on text-only -terminals. - -@item Text Properties -Text properties are annotations recorded for particular characters in -the buffer. Images in the buffer are recorded as text properties; -they also specify formatting information. @xref{Editing Format Info}. - -@item Tool Bar -The tool bar is a line (sometimes multiple lines) of icons at the top -of an Emacs frame. Clicking on one of these icons executes a command. -You can think of this as a graphical relative of the menu bar (q.v.@:). -@xref{Tool Bars}. - -@item Tooltips -Tooltips are small windows displaying a help echo (q.v.@:) text, which -explains parts of the display, lists useful options available via mouse -clicks, etc. @xref{Tooltips}. - -@item Top Level -Top level is the normal state of Emacs, in which you are editing the -text of the file you have visited. You are at top level whenever you -are not in a recursive editing level (q.v.@:) or the minibuffer -(q.v.@:), and not in the middle of a command. You can get back to top -level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. - -@item Transposition -Transposing two units of text means putting each one into the place -formerly occupied by the other. There are Emacs commands to transpose -two adjacent characters, words, balanced expressions (q.v.@:) or lines -(@pxref{Transpose}). - -@item Truncation -Truncating text lines in the display means leaving out any text on a -line that does not fit within the right margin of the window -displaying it. See also `continuation line.' -@xref{Continuation Lines,Truncation}. - -@item TTY -See `text-only terminal.' - -@item Undoing -Undoing means making your previous editing go in reverse, bringing -back the text that existed earlier in the editing session. -@xref{Undo}. - -@item Unix -Unix is a class of multi-user computer operating systems with a long -history. There are several implementations today. The GNU project -(q.v.@:) aims to develop a complete Unix-like operating system that -is free software (q.v.@:). - -@item User Option -A user option is a face (q.v.@:) or a variable (q.v.@:) that exists so -that you can customize Emacs by setting it to a new value. -@xref{Easy Customization}. - -@item Variable -A variable is an object in Lisp that can store an arbitrary value. -Emacs uses some variables for internal purposes, and has others (known -as `user options'; q.v.@:) just so that you can set their values to -control the behavior of Emacs. The variables used in Emacs that you -are likely to be interested in are listed in the Variables Index in -this manual (@pxref{Variable Index}). @xref{Variables}, for -information on variables. - -@item Version Control -Version control systems keep track of multiple versions of a source file. -They provide a more powerful alternative to keeping backup files (q.v.@:). -@xref{Version Control}. - -@item Visiting -Visiting a file means loading its contents into a buffer (q.v.@:) -where they can be edited. @xref{Visiting}. - -@item Whitespace -Whitespace is any run of consecutive formatting characters (space, -tab, newline, and backspace). - -@item Widening -Widening is removing any restriction (q.v.@:) on the current buffer; -it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. - -@item Window -Emacs divides a frame (q.v.@:) into one or more windows, each of which -can display the contents of one buffer (q.v.@:) at any time. -@xref{Screen}, for basic information on how Emacs uses the screen. -@xref{Windows}, for commands to control the use of windows. Some -other editors use the term ``window'' for what we call a `frame' -(q.v.@:) in Emacs. - -@item Window System -A window system is software that operates on a graphical display -(q.v.@:), to subdivide the screen so that multiple applications can -have their] own windows at the same time. All modern operating systems -include a window system. - -@item Word Abbrev -See `abbrev.' - -@item Word Search -Word search is searching for a sequence of words, considering the -punctuation between them as insignificant. @xref{Word Search}. - -@item WYSIWYG -WYSIWYG stands for ``What you see is what you get.'' Emacs generally -provides WYSIWYG editing for files of characters; in Enriched mode -(@pxref{Formatted Text}), it provides WYSIWYG editing for files that -include text formatting information. - -@item Yanking -Yanking means reinserting text previously killed (q.v.@:). It can be -used to undo a mistaken kill, or for copying or moving text. Some -other systems call this ``pasting.'' @xref{Yanking}. -@end table - -@ignore - arch-tag: 0dd53ce1-5f09-4ac2-b13b-cf22b0f28d23 -@end ignore diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi deleted file mode 100644 index f8d23b20f8a..00000000000 --- a/doc/emacs/gnu.texi +++ /dev/null @@ -1,555 +0,0 @@ -@c Copyright (C) 1985, 1986, 1987, 1993, 1995, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document, in any medium, provided that the copyright notice and -@c permission notice are preserved, and that the distributor grants the -@c recipient permission for further redistribution as permitted by this -@c notice. -@c -@c Modified versions may not be made. - -@ifclear justgnu -@node Manifesto,, Microsoft Windows, Top -@unnumbered The GNU Manifesto -@end ifclear -@ifset justgnu -@node Top -@top The GNU Manifesto -@end ifset - -@quotation -The GNU Manifesto which appears below was written by Richard Stallman at -the beginning of the GNU project, to ask for participation and support. -For the first few years, it was updated in minor ways to account for -developments, but now it seems best to leave it unchanged as most people -have seen it. - -Since that time, we have learned about certain common misunderstandings -that different wording could help avoid. Footnotes added in 1993 help -clarify these points. - -For up-to-date information about available GNU software, please see -our web site, @uref{http://www.gnu.org}. For software tasks and other -ways to contribute, see @uref{http://www.gnu.org/help}. -@end quotation - -@unnumberedsec What's GNU? Gnu's Not Unix! - -GNU, which stands for Gnu's Not Unix, is the name for the complete -Unix-compatible software system which I am writing so that I can give it -away free to everyone who can use it.@footnote{The wording here was -careless. The intention was that nobody would have to pay for -@emph{permission} to use the GNU system. But the words don't make this -clear, and people often interpret them as saying that copies of GNU -should always be distributed at little or no charge. That was never the -intent; later on, the manifesto mentions the possibility of companies -providing the service of distribution for a profit. Subsequently I have -learned to distinguish carefully between ``free'' in the sense of -freedom and ``free'' in the sense of price. Free software is software -that users have the freedom to distribute and change. Some users may -obtain copies at no charge, while others pay to obtain copies---and if -the funds help support improving the software, so much the better. The -important thing is that everyone who has a copy has the freedom to -cooperate with others in using it.} Several other volunteers are helping -me. Contributions of time, money, programs and equipment are greatly -needed. - -So far we have an Emacs text editor with Lisp for writing editor commands, -a source level debugger, a yacc-compatible parser generator, a linker, and -around 35 utilities. A shell (command interpreter) is nearly completed. A -new portable optimizing C compiler has compiled itself and may be released -this year. An initial kernel exists but many more features are needed to -emulate Unix. When the kernel and compiler are finished, it will be -possible to distribute a GNU system suitable for program development. We -will use @TeX{} as our text formatter, but an nroff is being worked on. We -will use the free, portable X window system as well. After this we will -add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of -other things, plus on-line documentation. We hope to supply, eventually, -everything useful that normally comes with a Unix system, and more. - -GNU will be able to run Unix programs, but will not be identical to Unix. -We will make all improvements that are convenient, based on our experience -with other operating systems. In particular, we plan to have longer -file names, file version numbers, a crashproof file system, file name -completion perhaps, terminal-independent display support, and perhaps -eventually a Lisp-based window system through which several Lisp programs -and ordinary Unix programs can share a screen. Both C and Lisp will be -available as system programming languages. We will try to support UUCP, -MIT Chaosnet, and Internet protocols for communication. - -GNU is aimed initially at machines in the 68000/16000 class with virtual -memory, because they are the easiest machines to make it run on. The extra -effort to make it run on smaller machines will be left to someone who wants -to use it on them. - -To avoid horrible confusion, please pronounce the `G' in the word `GNU' -when it is the name of this project. - -@unnumberedsec Why I Must Write GNU - -I consider that the golden rule requires that if I like a program I must -share it with other people who like it. Software sellers want to divide -the users and conquer them, making each user agree not to share with -others. I refuse to break solidarity with other users in this way. I -cannot in good conscience sign a nondisclosure agreement or a software -license agreement. For years I worked within the Artificial Intelligence -Lab to resist such tendencies and other inhospitalities, but eventually -they had gone too far: I could not remain in an institution where such -things are done for me against my will. - -So that I can continue to use computers without dishonor, I have decided to -put together a sufficient body of free software so that I will be able to -get along without any software that is not free. I have resigned from the -AI lab to deny MIT any legal excuse to prevent me from giving GNU away. - -@unnumberedsec Why GNU Will Be Compatible with Unix - -Unix is not my ideal system, but it is not too bad. The essential features -of Unix seem to be good ones, and I think I can fill in what Unix lacks -without spoiling them. And a system compatible with Unix would be -convenient for many other people to adopt. - -@unnumberedsec How GNU Will Be Available - -GNU is not in the public domain. Everyone will be permitted to modify and -redistribute GNU, but no distributor will be allowed to restrict its -further redistribution. That is to say, proprietary modifications will not -be allowed. I want to make sure that all versions of GNU remain free. - -@unnumberedsec Why Many Other Programmers Want to Help - -I have found many other programmers who are excited about GNU and want to -help. - -Many programmers are unhappy about the commercialization of system -software. It may enable them to make more money, but it requires them to -feel in conflict with other programmers in general rather than feel as -comrades. The fundamental act of friendship among programmers is the -sharing of programs; marketing arrangements now typically used essentially -forbid programmers to treat others as friends. The purchaser of software -must choose between friendship and obeying the law. Naturally, many decide -that friendship is more important. But those who believe in law often do -not feel at ease with either choice. They become cynical and think that -programming is just a way of making money. - -By working on and using GNU rather than proprietary programs, we can be -hospitable to everyone and obey the law. In addition, GNU serves as an -example to inspire and a banner to rally others to join us in sharing. -This can give us a feeling of harmony which is impossible if we use -software that is not free. For about half the programmers I talk to, this -is an important happiness that money cannot replace. - -@unnumberedsec How You Can Contribute - -I am asking computer manufacturers for donations of machines and money. -I'm asking individuals for donations of programs and work. - -One consequence you can expect if you donate machines is that GNU will run -on them at an early date. The machines should be complete, ready to use -systems, approved for use in a residential area, and not in need of -sophisticated cooling or power. - -I have found very many programmers eager to contribute part-time work for -GNU. For most projects, such part-time distributed work would be very hard -to coordinate; the independently-written parts would not work together. -But for the particular task of replacing Unix, this problem is absent. A -complete Unix system contains hundreds of utility programs, each of which -is documented separately. Most interface specifications are fixed by Unix -compatibility. If each contributor can write a compatible replacement for -a single Unix utility, and make it work properly in place of the original -on a Unix system, then these utilities will work right when put together. -Even allowing for Murphy to create a few unexpected problems, assembling -these components will be a feasible task. (The kernel will require closer -communication and will be worked on by a small, tight group.) - -If I get donations of money, I may be able to hire a few people full or -part time. The salary won't be high by programmers' standards, but I'm -looking for people for whom building community spirit is as important as -making money. I view this as a way of enabling dedicated people to devote -their full energies to working on GNU by sparing them the need to make a -living in another way. - -@unnumberedsec Why All Computer Users Will Benefit - -Once GNU is written, everyone will be able to obtain good system -software free, just like air.@footnote{This is another place I failed to -distinguish carefully between the two different meanings of ``free.'' -The statement as it stands is not false---you can get copies of GNU -software at no charge, from your friends or over the net. But it does -suggest the wrong idea.} - -This means much more than just saving everyone the price of a Unix license. -It means that much wasteful duplication of system programming effort will -be avoided. This effort can go instead into advancing the state of the -art. - -Complete system sources will be available to everyone. As a result, a user -who needs changes in the system will always be free to make them himself, -or hire any available programmer or company to make them for him. Users -will no longer be at the mercy of one programmer or company which owns the -sources and is in sole position to make changes. - -Schools will be able to provide a much more educational environment by -encouraging all students to study and improve the system code. Harvard's -computer lab used to have the policy that no program could be installed on -the system if its sources were not on public display, and upheld it by -actually refusing to install certain programs. I was very much inspired by -this. - -Finally, the overhead of considering who owns the system software and what -one is or is not entitled to do with it will be lifted. - -Arrangements to make people pay for using a program, including licensing of -copies, always incur a tremendous cost to society through the cumbersome -mechanisms necessary to figure out how much (that is, which programs) a -person must pay for. And only a police state can force everyone to obey -them. Consider a space station where air must be manufactured at great -cost: charging each breather per liter of air may be fair, but wearing the -metered gas mask all day and all night is intolerable even if everyone can -afford to pay the air bill. And the TV cameras everywhere to see if you -ever take the mask off are outrageous. It's better to support the air -plant with a head tax and chuck the masks. - -Copying all or parts of a program is as natural to a programmer as -breathing, and as productive. It ought to be as free. - -@unnumberedsec Some Easily Rebutted Objections to GNU's Goals - -@quotation -``Nobody will use it if it is free, because that means they can't rely -on any support.'' - -``You have to charge for the program to pay for providing the -support.'' -@end quotation - -If people would rather pay for GNU plus service than get GNU free without -service, a company to provide just service to people who have obtained GNU -free ought to be profitable.@footnote{Several such companies now exist.} - -We must distinguish between support in the form of real programming work -and mere handholding. The former is something one cannot rely on from a -software vendor. If your problem is not shared by enough people, the -vendor will tell you to get lost. - -If your business needs to be able to rely on support, the only way is to -have all the necessary sources and tools. Then you can hire any available -person to fix your problem; you are not at the mercy of any individual. -With Unix, the price of sources puts this out of consideration for most -businesses. With GNU this will be easy. It is still possible for there to -be no available competent person, but this problem cannot be blamed on -distribution arrangements. GNU does not eliminate all the world's problems, -only some of them. - -Meanwhile, the users who know nothing about computers need handholding: -doing things for them which they could easily do themselves but don't know -how. - -Such services could be provided by companies that sell just hand-holding -and repair service. If it is true that users would rather spend money and -get a product with service, they will also be willing to buy the service -having got the product free. The service companies will compete in quality -and price; users will not be tied to any particular one. Meanwhile, those -of us who don't need the service should be able to use the program without -paying for the service. - -@quotation -``You cannot reach many people without advertising, -and you must charge for the program to support that.'' - -``It's no use advertising a program people can get free.'' -@end quotation - -There are various forms of free or very cheap publicity that can be used to -inform numbers of computer users about something like GNU. But it may be -true that one can reach more microcomputer users with advertising. If this -is really so, a business which advertises the service of copying and -mailing GNU for a fee ought to be successful enough to pay for its -advertising and more. This way, only the users who benefit from the -advertising pay for it. - -On the other hand, if many people get GNU from their friends, and such -companies don't succeed, this will show that advertising was not really -necessary to spread GNU. Why is it that free market advocates don't -want to let the free market decide this?@footnote{The Free Software -Foundation raises most of its funds from a distribution service, -although it is a charity rather than a company. If @emph{no one} -chooses to obtain copies by ordering from the FSF, it will be unable -to do its work. But this does not mean that proprietary restrictions -are justified to force every user to pay. If a small fraction of all -the users order copies from the FSF, that is sufficient to keep the FSF -afloat. So we ask users to choose to support us in this way. Have you -done your part?} - -@quotation -``My company needs a proprietary operating system -to get a competitive edge.'' -@end quotation - -GNU will remove operating system software from the realm of competition. -You will not be able to get an edge in this area, but neither will your -competitors be able to get an edge over you. You and they will compete in -other areas, while benefiting mutually in this one. If your business is -selling an operating system, you will not like GNU, but that's tough on -you. If your business is something else, GNU can save you from being -pushed into the expensive business of selling operating systems. - -I would like to see GNU development supported by gifts from many -manufacturers and users, reducing the cost to each.@footnote{A group of -computer companies recently pooled funds to support maintenance of the -GNU C Compiler.} - -@quotation -``Don't programmers deserve a reward for their creativity?'' -@end quotation - -If anything deserves a reward, it is social contribution. Creativity can -be a social contribution, but only in so far as society is free to use the -results. If programmers deserve to be rewarded for creating innovative -programs, by the same token they deserve to be punished if they restrict -the use of these programs. - -@quotation -``Shouldn't a programmer be able to ask for a reward for his creativity?'' -@end quotation - -There is nothing wrong with wanting pay for work, or seeking to maximize -one's income, as long as one does not use means that are destructive. But -the means customary in the field of software today are based on -destruction. - -Extracting money from users of a program by restricting their use of it is -destructive because the restrictions reduce the amount and the ways that -the program can be used. This reduces the amount of wealth that humanity -derives from the program. When there is a deliberate choice to restrict, -the harmful consequences are deliberate destruction. - -The reason a good citizen does not use such destructive means to become -wealthier is that, if everyone did so, we would all become poorer from the -mutual destructiveness. This is Kantian ethics; or, the Golden Rule. -Since I do not like the consequences that result if everyone hoards -information, I am required to consider it wrong for one to do so. -Specifically, the desire to be rewarded for one's creativity does not -justify depriving the world in general of all or part of that creativity. - -@quotation -``Won't programmers starve?'' -@end quotation - -I could answer that nobody is forced to be a programmer. Most of us cannot -manage to get any money for standing on the street and making faces. But -we are not, as a result, condemned to spend our lives standing on the -street making faces, and starving. We do something else. - -But that is the wrong answer because it accepts the questioner's implicit -assumption: that without ownership of software, programmers cannot possibly -be paid a cent. Supposedly it is all or nothing. - -The real reason programmers will not starve is that it will still be -possible for them to get paid for programming; just not paid as much as -now. - -Restricting copying is not the only basis for business in software. It is -the most common basis because it brings in the most money. If it were -prohibited, or rejected by the customer, software business would move to -other bases of organization which are now used less often. There are -always numerous ways to organize any kind of business. - -Probably programming will not be as lucrative on the new basis as it is -now. But that is not an argument against the change. It is not considered -an injustice that sales clerks make the salaries that they now do. If -programmers made the same, that would not be an injustice either. (In -practice they would still make considerably more than that.) - -@quotation -``Don't people have a right to control how their creativity is used?'' -@end quotation - -``Control over the use of one's ideas'' really constitutes control over -other people's lives; and it is usually used to make their lives more -difficult. - -People who have studied the issue of intellectual property -rights@footnote{In the 80s I had not yet realized how confusing it was -to speak of ``the issue'' of ``intellectual property.'' That term is -obviously biased; more subtle is the fact that it lumps together -various disparate laws which raise very different issues. Nowadays I -urge people to reject the term ``intellectual property'' entirely, -lest it lead others to suppose that those laws form one coherent -issue. The way to be clear is to discuss patents, copyrights, and -trademarks separately. See -@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more -explanation of how this term spreads confusion and bias.} carefully -(such as lawyers) say that there is no intrinsic right to intellectual -property. The kinds of supposed intellectual property rights that the -government recognizes were created by specific acts of legislation for -specific purposes. - -For example, the patent system was established to encourage inventors to -disclose the details of their inventions. Its purpose was to help society -rather than to help inventors. At the time, the life span of 17 years for -a patent was short compared with the rate of advance of the state of the -art. Since patents are an issue only among manufacturers, for whom the -cost and effort of a license agreement are small compared with setting up -production, the patents often do not do much harm. They do not obstruct -most individuals who use patented products. - -The idea of copyright did not exist in ancient times, when authors -frequently copied other authors at length in works of non-fiction. This -practice was useful, and is the only way many authors' works have survived -even in part. The copyright system was created expressly for the purpose -of encouraging authorship. In the domain for which it was -invented---books, which could be copied economically only on a printing -press---it did little harm, and did not obstruct most of the individuals -who read the books. - -All intellectual property rights are just licenses granted by society -because it was thought, rightly or wrongly, that society as a whole would -benefit by granting them. But in any particular situation, we have to ask: -are we really better off granting such license? What kind of act are we -licensing a person to do? - -The case of programs today is very different from that of books a hundred -years ago. The fact that the easiest way to copy a program is from one -neighbor to another, the fact that a program has both source code and -object code which are distinct, and the fact that a program is used rather -than read and enjoyed, combine to create a situation in which a person who -enforces a copyright is harming society as a whole both materially and -spiritually; in which a person should not do so regardless of whether the -law enables him to. - -@quotation -``Competition makes things get done better.'' -@end quotation - -The paradigm of competition is a race: by rewarding the winner, we -encourage everyone to run faster. When capitalism really works this way, -it does a good job; but its defenders are wrong in assuming it always works -this way. If the runners forget why the reward is offered and become -intent on winning, no matter how, they may find other strategies---such as, -attacking other runners. If the runners get into a fist fight, they will -all finish late. - -Proprietary and secret software is the moral equivalent of runners in a -fist fight. Sad to say, the only referee we've got does not seem to -object to fights; he just regulates them (``For every ten yards you run, -you can fire one shot''). He really ought to break them up, and penalize -runners for even trying to fight. - -@quotation -``Won't everyone stop programming without a monetary incentive?'' -@end quotation - -Actually, many people will program with absolutely no monetary incentive. -Programming has an irresistible fascination for some people, usually the -people who are best at it. There is no shortage of professional musicians -who keep at it even though they have no hope of making a living that way. - -But really this question, though commonly asked, is not appropriate to the -situation. Pay for programmers will not disappear, only become less. So -the right question is, will anyone program with a reduced monetary -incentive? My experience shows that they will. - -For more than ten years, many of the world's best programmers worked at the -Artificial Intelligence Lab for far less money than they could have had -anywhere else. They got many kinds of non-monetary rewards: fame and -appreciation, for example. And creativity is also fun, a reward in itself. - -Then most of them left when offered a chance to do the same interesting -work for a lot of money. - -What the facts show is that people will program for reasons other than -riches; but if given a chance to make a lot of money as well, they will -come to expect and demand it. Low-paying organizations do poorly in -competition with high-paying ones, but they do not have to do badly if the -high-paying ones are banned. - -@quotation -``We need the programmers desperately. If they demand that we -stop helping our neighbors, we have to obey.'' -@end quotation - -You're never so desperate that you have to obey this sort of demand. -Remember: millions for defense, but not a cent for tribute! - -@quotation -``Programmers need to make a living somehow.'' -@end quotation - -In the short run, this is true. However, there are plenty of ways that -programmers could make a living without selling the right to use a program. -This way is customary now because it brings programmers and businessmen the -most money, not because it is the only way to make a living. It is easy to -find other ways if you want to find them. Here are a number of examples. - -A manufacturer introducing a new computer will pay for the porting of -operating systems onto the new hardware. - -The sale of teaching, hand-holding and maintenance services could also -employ programmers. - -People with new ideas could distribute programs as -freeware@footnote{Subsequently we have discovered the need to -distinguish between ``free software'' and ``freeware''. The term -``freeware'' means software you are free to redistribute, but usually -you are not free to study and change the source code, so most of it is -not free software. See -@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more -explanation.}, asking for donations from satisfied users, or selling -hand-holding services. I have met people who are already working this -way successfully. - -Users with related needs can form users' groups, and pay dues. A group -would contract with programming companies to write programs that the -group's members would like to use. - -All sorts of development can be funded with a Software Tax: - -@quotation -Suppose everyone who buys a computer has to pay x percent of -the price as a software tax. The government gives this to -an agency like the NSF to spend on software development. - -But if the computer buyer makes a donation to software development -himself, he can take a credit against the tax. He can donate to -the project of his own choosing---often, chosen because he hopes to -use the results when it is done. He can take a credit for any amount -of donation up to the total tax he had to pay. - -The total tax rate could be decided by a vote of the payers of -the tax, weighted according to the amount they will be taxed on. - -The consequences: - -@itemize @bullet -@item -The computer-using community supports software development. -@item -This community decides what level of support is needed. -@item -Users who care which projects their share is spent on -can choose this for themselves. -@end itemize -@end quotation - -In the long run, making programs free is a step toward the post-scarcity -world, where nobody will have to work very hard just to make a living. -People will be free to devote themselves to activities that are fun, such -as programming, after spending the necessary ten hours a week on required -tasks such as legislation, family counseling, robot repair and asteroid -prospecting. There will be no need to be able to make a living from -programming. - -We have already greatly reduced the amount of work that the whole society -must do for its actual productivity, but only a little of this has -translated itself into leisure for workers because much nonproductive -activity is required to accompany productive activity. The main causes of -this are bureaucracy and isometric struggles against competition. Free -software will greatly reduce these drains in the area of software -production. We must do this, in order for technical gains in productivity -to translate into less work for us. - -@ignore - arch-tag: 21eb38f8-6fa0-480a-91cd-f3dab7148542 -@end ignore diff --git a/doc/emacs/gpl.texi b/doc/emacs/gpl.texi deleted file mode 100644 index 7fe5c3ebe40..00000000000 --- a/doc/emacs/gpl.texi +++ /dev/null @@ -1,721 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@ignore - arch-tag: 8b9947e1-c830-4d70-8907-a97e556731ba -@end ignore diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi deleted file mode 100644 index 061b4cddba9..00000000000 --- a/doc/emacs/help.texi +++ /dev/null @@ -1,680 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Help, Mark, M-x, Top -@chapter Help -@kindex Help -@cindex help -@cindex self-documentation -@findex help-command -@kindex C-h -@kindex F1 - - Emacs provides extensive help features, all accessible through the -@dfn{help character}, @kbd{C-h}. This is a prefix key that is used -for commands that display documentation; the next character you type -should be a @dfn{help option}, to ask for a particular kind of help. -You can cancel the @kbd{C-h} command with @kbd{C-g}. The function key -@key{F1} is equivalent to @kbd{C-h}. - -@kindex C-h C-h -@findex help-for-help - @kbd{C-h} itself is one of the help options; @kbd{C-h C-h} displays -a list of help options, with a brief description of each one -(@code{help-for-help}). You can scroll the list with @key{SPC} and -@key{DEL}, then type the help option you want. To cancel, type -@kbd{C-g}. - - @kbd{C-h} or @key{F1} means ``help'' in various other contexts as -well. For instance, you can type them after a prefix key to display -a list of the keys that can follow the prefix key. (A few prefix keys -don't support @kbd{C-h} in this way, because they define other -meanings for it, but they all support @key{F1} for help.) - - Most help buffers use a special major mode, Help mode, which lets -you scroll conveniently with @key{SPC} and @key{DEL}. You can also -follow hyperlinks to URLs, and to other facilities including Info -nodes and customization buffers. @xref{Help Mode}. - -@cindex searching documentation efficiently -@cindex looking for a subject in documentation - If you are looking for a certain feature, but don't know what it is -called or where to look, we recommend three methods. First, try an -apropos command, then try searching the manual index, then look in the -FAQ and the package keywords. - -@table @kbd -@item C-h a @var{topics} @key{RET} -This searches for commands whose names match the argument -@var{topics}. The argument can be a keyword, a list of keywords, or a -regular expression (@pxref{Regexps}). @xref{Apropos}. - -@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} -This searches for @var{topic} in the indices of the on-line Emacs -manual, and displays the first match found. Press @kbd{,} to see -subsequent matches. You can use a regular expression as @var{topic}. - -@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} -Similar, but searches the @emph{text} of the manual rather than the -indices. - -@item C-h C-f -This displays the Emacs FAQ. You can use the Info commands -to browse it. - -@item C-h p -This displays the available Emacs packages based on keywords. -@xref{Library Keywords}. -@end table - -@menu -* Help Summary:: Brief list of all Help commands. -* Key Help:: Asking what a key does in Emacs. -* Name Help:: Asking about a command, variable or function name. -* Apropos:: Asking what pertains to a given topic. -* Help Mode:: Special features of Help mode and Help buffers. -* Library Keywords:: Finding Lisp libraries by keywords (topics). -* Language Help:: Help relating to international language support. -* Misc Help:: Other help commands. -* Help Files:: Commands to display pre-written help files. -* Help Echo:: Help on active text and tooltips (`balloon help'). -@end menu - -@iftex -@node Help Summary -@end iftex -@ifnottex -@node Help Summary -@section Help Summary -@end ifnottex - - Here is a summary of the Emacs interactive help commands. (The -character that follows @kbd{C-h} is the ``help option.'') See -@ref{Help Files}, for other help commands that display fixed files -of information. - -@table @kbd -@item C-h a @var{topics} @key{RET} -Display a list of commands whose names match @var{topics} -(@code{apropos-command}; @pxref{Apropos}). -@item C-h b -Display all active key bindings; minor mode bindings first, then those -of the major mode, then global bindings (@code{describe-bindings}). -@item C-h c @var{key} -Given a key sequence @var{key}, show the name of the command that it -runs (@code{describe-key-briefly}). Here @kbd{c} stands for -``character.'' For more extensive information on @var{key}, use -@kbd{C-h k}. -@item C-h d @var{topics} @key{RET} -Display the commands and variables whose documentation matches -@var{topics} (@code{apropos-documentation}). -@item C-h e -Display the @code{*Messages*} buffer -(@code{view-echo-area-messages}). -@item C-h f @var{function} @key{RET} -Display documentation on the Lisp function named @var{function} -(@code{describe-function}). Since commands are Lisp functions, -this works for commands too. -@item C-h h -Display the @file{HELLO} file, which shows examples of various character -sets. -@item C-h i -Run Info, the GNU documentation browser (@code{info}). -The complete Emacs manual is available on-line in Info. -@item C-h k @var{key} -Display the name and documentation of the command that @var{key} runs -(@code{describe-key}). -@item C-h l -Display a description of your last 300 keystrokes -(@code{view-lossage}). -@item C-h m -Display documentation of the current major mode (@code{describe-mode}). -@item C-h n -Display news of recent Emacs changes (@code{view-emacs-news}). -@item C-h p -Find packages by topic keyword (@code{finder-by-keyword}). -@item C-h r -Display the Emacs manual in Info (@code{info-emacs-manual}). -@item C-h s -Display the current contents of the syntax table, with an explanation of -what they mean (@code{describe-syntax}). @xref{Syntax}. -@item C-h t -Enter the Emacs interactive tutorial (@code{help-with-tutorial}). -@item C-h v @var{var} @key{RET} -Display the documentation of the Lisp variable @var{var} -(@code{describe-variable}). -@item C-h w @var{command} @key{RET} -Show which keys run the command named @var{command} (@code{where-is}). -@item C-h C @var{coding} @key{RET} -Describe the coding system @var{coding} -(@code{describe-coding-system}). -@item C-h C @key{RET} -Describe the coding systems currently in use. -@item C-h F @var{command} @key{RET} -Enter Info and go to the node that documents the Emacs command -@var{command} (@code{Info-goto-emacs-command-node}). -@item C-h I @var{method} @key{RET} -Describe the input method @var{method} (@code{describe-input-method}). -@item C-h K @var{key} -Enter Info and go to the node that documents the key sequence -@var{key} (@code{Info-goto-emacs-key-command-node}). -@item C-h L @var{language-env} @key{RET} -Display information on the character sets, coding systems, and input -methods used in language environment @var{language-env} -(@code{describe-language-environment}). -@item C-h S @var{symbol} @key{RET} -Display the Info documentation on symbol @var{symbol} according to the -programming language you are editing (@code{info-lookup-symbol}). -@item C-h . -Display the help message for a special text area, if point is in one -(@code{display-local-help}). (These include, for example, links in -@samp{*Help*} buffers.) -@end table - -@node Key Help -@section Documentation for a Key - -@kindex C-h c -@findex describe-key-briefly - The help commands to get information about a key sequence are -@kbd{C-h c} and @w{@kbd{C-h k}}. @kbd{C-h c @var{key}} displays in -the echo area the name of the command that @var{key} is bound to. For -example, @kbd{C-h c C-f} displays @samp{forward-char}. Since command -names are chosen to describe what the commands do, this gives you a -very brief description of what @var{key} does. - -@kindex C-h k -@findex describe-key - @kbd{C-h k @var{key}} is similar but gives more information: it -displays the documentation string of the command as well as its name. -It displays this information in a window, since it may not fit in the -echo area. - -@kindex C-h K -@findex Info-goto-emacs-key-command-node - To find the documentation of a key sequence @var{key}, type @kbd{C-h -K @var{key}}. This displays the appropriate manual section which -contains the documentation of @var{key}. - - @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key -sequences, including function keys, menus, and mouse events. For -instance, after @kbd{C-h k} you can select a menu item from the menu -bar, to view the documentation string of the command it runs. - -@kindex C-h w -@findex where-is - @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to -@var{command}. It displays the list in the echo area. If it says the -command is not on any key, that means you must use @kbd{M-x} to run -it. @kbd{C-h w} runs the command @code{where-is}. - -@node Name Help -@section Help by Command or Variable Name - -@kindex C-h f -@findex describe-function - @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) -displays the documentation of Lisp function @var{function}, in a -window. Since commands are Lisp functions, you can use this method to -view the documentation of any command whose name you know. For -example, - -@example -C-h f auto-fill-mode @key{RET} -@end example - -@noindent -displays the documentation of @code{auto-fill-mode}. This is the only -way to get the documentation of a command that is not bound to any key -(one which you would normally run using @kbd{M-x}). - - @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp -program. For example, if you have just written the expression -@code{(make-vector len)} and want to check that you are using -@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. -Because @kbd{C-h f} allows all function names, not just command names, -you may find that some of your favorite completion abbreviations that -work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is -unique among command names may not be unique among all function names. - - If you type @kbd{C-h f @key{RET}}, it describes the function called -by the innermost Lisp expression in the buffer around point, -@emph{provided} that function name is a valid, defined Lisp function. -(That name appears as the default while you enter the argument.) For -example, if point is located following the text @samp{(make-vector -(car x)}, the innermost list containing point is the one that starts -with @samp{(make-vector}, so @kbd{C-h f @key{RET}} will describe the -function @code{make-vector}. - - @kbd{C-h f} is also useful just to verify that you spelled a -function name correctly. If the minibuffer prompt for @kbd{C-h f} -shows the function name from the buffer as the default, it means that -name is defined as a Lisp function. Type @kbd{C-g} to cancel the -@kbd{C-h f} command if you don't really want to view the -documentation. - -@kindex C-h v -@findex describe-variable - @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but -describes Lisp variables instead of Lisp functions. Its default is -the Lisp symbol around or before point, if that is the name of a -defined Lisp variable. @xref{Variables}. - - Help buffers that describe Emacs variables and functions normally -have hyperlinks to the corresponding source definition, if you have -the source files installed. (@xref{Hyperlinking}.) If you know Lisp -(or C), this provides the ultimate documentation. If you don't know -Lisp, you should learn it. (The Introduction to Emacs Lisp -Programming, available from the FSF through fsf.org, is a good way to -get started.) If Emacs feels you are just @emph{using} it, treating -it as an object program, its feelings may be hurt. For real intimacy, -read the Emacs source code. - -@kindex C-h F -@findex Info-goto-emacs-command-node - To find a command's documentation in a manual, use @kbd{C-h F} -(@code{Info-goto-emacs-command-node}). This knows about various -manuals, not just the Emacs manual, and finds the right one. - -@node Apropos -@section Apropos - - The @dfn{apropos} commands answer questions like, ``What are the -commands for working with files?'' More precisely, you specify an -@dfn{apropos pattern}, which means either a word, a list of words, or -a regular expression. Each apropos command displays a list of items -that match the pattern, in a separate buffer. - -@table @kbd -@item C-h a @var{pattern} @key{RET} -Search for commands whose names match @var{pattern}. - -@item M-x apropos @key{RET} @var{pattern} @key{RET} -Search for functions and variables whose names match @var{pattern}. -Both interactive functions (commands) and noninteractive functions can -be found by this command. - -@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} -Search for user-option variables whose names match @var{pattern}. - -@item M-x apropos-value @key{RET} @var{pattern} @key{RET} -Search for functions whose definitions match @var{pattern}, and -variables whose values match @var{pattern}. - -@item C-h d @var{pattern} @key{RET} -Search for functions and variables whose @strong{documentation -strings} match @var{pattern}. -@end table - -@kindex C-h a -@findex apropos-command -@cindex apropos - The simplest kind of apropos pattern is one word. Anything which -contains that word matches the pattern. Thus, to find the commands -that work on files, type @kbd{C-h a file @key{RET}}. This displays a -list of all command names that contain @samp{file}, including -@code{copy-file}, @code{find-file}, and so on. Each command name -comes with a brief description and a list of keys you can currently -invoke it with. In our example, it would say that you can invoke -@code{find-file} by typing @kbd{C-x C-f}. - - The @kbd{a} in @kbd{C-h a} stands for ``Apropos''; @kbd{C-h a} -runs the command @code{apropos-command}. This command normally checks -only commands (interactive functions); if you specify a prefix -argument, it checks noninteractive functions as well. - - For more information about a function definition, variable or symbol -property listed in the apropos buffer, you can click on it with -@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. - - When you specify more than one word in the apropos pattern, a name -must contain at least two of the words in order to match. Thus, if -you are looking for commands to kill a chunk of text before point, you -could try @kbd{C-h a kill back backward behind before @key{RET}}. The -real command name @code{kill-backward} will match that; if there were -a command @code{kill-text-before}, it would also match, since it -contains two of the specified words. - - For even greater flexibility, you can specify a regular expression -(@pxref{Regexps}). An apropos pattern is interpreted as a regular -expression if it contains any of the regular expression special -characters, @samp{^$*+?.\[}. - - Following the conventions for naming Emacs commands, here are some -words that you'll find useful in apropos patterns. By using them in -@kbd{C-h a}, you will also get a feel for the naming conventions. - -@quotation -char, line, word, sentence, paragraph, region, page, sexp, list, defun, -rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, -forward, backward, next, previous, up, down, search, goto, kill, delete, -mark, insert, yank, fill, indent, case, change, set, what, list, find, -view, describe, default. -@end quotation - -@findex apropos - Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp -symbols that match an apropos pattern, not just the symbols that are -commands. This command does not list key bindings by default; specify -a numeric argument if you want it to list them. - -@findex apropos-variable - Use @kbd{M-x apropos-variable} to list user-customizable variables -that match an apropos pattern. If you specify a prefix argument, it -lists all matching variables. - -@kindex C-h d -@findex apropos-documentation - The @code{apropos-documentation} command is like @code{apropos} -except that it searches documentation strings instead of symbol names -for matches. - -@findex apropos-value - The @code{apropos-value} command is like @code{apropos} except that -it searches variables' values for matches for the apropos pattern. -With a prefix argument, it also checks symbols' function definitions -and property lists. - -@vindex apropos-do-all - If the variable @code{apropos-do-all} is non-@code{nil}, the apropos -commands always behave as if they had been given a prefix argument. - -@vindex apropos-sort-by-scores -@cindex apropos search results, order by score - By default, apropos lists the search results in alphabetical order. -If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the -apropos commands try to guess the relevance of each result, and -display the most relevant ones first. - -@vindex apropos-documentation-sort-by-scores - By default, apropos lists the search results for -@code{apropos-documentation} in order of relevance of the match. If -the variable @code{apropos-documentation-sort-by-scores} is -@code{nil}, apropos lists the symbols found in alphabetical order. - -@node Help Mode -@section Help Mode Commands - - Help buffers provide the same commands as View mode (@pxref{Misc File -Ops}), plus a few special commands of their own. - -@table @kbd -@item @key{SPC} -Scroll forward. -@item @key{DEL} -Scroll backward. -@item @key{RET} -Follow a cross reference at point. -@item @key{TAB} -Move point forward to the next cross reference. -@item S-@key{TAB} -Move point back to the previous cross reference. -@item Mouse-1 -@itemx Mouse-2 -Follow a cross reference that you click on. -@item C-c C-c -Show all documentation about the symbol at point. -@end table - - When a function name (@pxref{M-x,, Running Commands by Name}), -variable name (@pxref{Variables}), or face name (@pxref{Faces}) -appears in the documentation, it normally appears inside paired -single-quotes. To view the documentation of that command, variable or -face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, -or move point there and type @key{RET}. Use @kbd{C-c C-b} to retrace -your steps. - -@cindex URL, viewing in help -@cindex help, viewing web pages -@cindex viewing web pages in help -@cindex web pages, viewing in help -@findex browse-url - You can follow cross references to URLs (web pages) also. This uses -the @code{browse-url} command to view the page in the browser you -choose. @xref{Browse-URL}. - -@kindex @key{TAB} @r{(Help mode)} -@findex help-next-ref -@kindex S-@key{TAB} @r{(Help mode)} -@findex help-previous-ref - There are convenient commands to move point to cross references in -the help text. @key{TAB} (@code{help-next-ref}) moves point down to -the next cross reference. @kbd{S-@key{TAB}} moves up to the previous -cross reference (@code{help-previous-ref}). - - To view all documentation about any symbol name that appears in the -text, move point to the symbol name and type @kbd{C-c C-c} -(@code{help-follow-symbol}). This shows all available documentation -about the symbol as a variable, function and/or face. As above, use -@kbd{C-c C-b} to retrace your steps. - -@node Library Keywords -@section Keyword Search for Lisp Libraries - -@kindex C-h p -@findex finder-by-keyword -The @kbd{C-h p} command lets you search the standard Emacs Lisp -libraries by topic keywords. Here is a partial list of keywords you can -use: - -@multitable {convenience} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} -@item abbrev@tab abbreviation handling, typing shortcuts, macros. -@item bib@tab code related to the @code{bib} bibliography processor. -@item c@tab support for the C language and related languages. -@item calendar@tab calendar and time management support. -@item comm@tab communications, networking, remote access to files. -@item convenience@tab convenience features for faster editing. -@item data@tab support for editing files of data. -@item docs@tab support for Emacs documentation. -@item emulations@tab emulations of other editors. -@item extensions@tab Emacs Lisp language extensions. -@item faces@tab support for multiple fonts. -@item files@tab support for editing and manipulating files. -@item frames@tab support for Emacs frames and window systems. -@item games@tab games, jokes and amusements. -@item hardware@tab support for interfacing with exotic hardware. -@item help@tab support for on-line help systems. -@item hypermedia@tab support for links between text or other media types. -@item i18n@tab internationalization and alternate character-set support. -@item internal@tab code for Emacs internals, build process, defaults. -@item languages@tab specialized modes for editing programming languages. -@item lisp@tab Lisp support, including Emacs Lisp. -@item local@tab code local to your site. -@item maint@tab maintenance aids for the Emacs development group. -@item mail@tab modes for electronic-mail handling. -@item matching@tab various sorts of searching and matching. -@item mouse@tab mouse support. -@item multimedia@tab images and sound support. -@item news@tab support for netnews reading and posting. -@item oop@tab support for object-oriented programming. -@item outlines@tab support for hierarchical outlining. -@item processes@tab process, subshell, compilation, and job control support. -@item terminals@tab support for terminal types. -@item tex@tab supporting code for the @TeX{} formatter. -@item tools@tab programming tools. -@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features. -@item wp@tab word processing. -@end multitable - -@node Language Help -@section Help for International Language Support - - You can use the command @kbd{C-h L} -(@code{describe-language-environment}) to get information about a -specific language environment. @xref{Language Environments}. This -tells you which languages this language environment supports. It also -lists the character sets, coding systems, and input methods that work -with this language environment, and finally shows some sample text to -illustrate scripts. - - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which shows how to say ``hello'' in many languages. - - The command @kbd{C-h I} (@code{describe-input-method}) describes an -input method---either a specified input method, or by default the -input method currently in use. @xref{Input Methods}. - - The command @kbd{C-h C} (@code{describe-coding-system}) describes -coding systems---either a specified coding system, or the ones -currently in use. @xref{Coding Systems}. - -@node Misc Help -@section Other Help Commands - -@kindex C-h i -@findex info -@cindex Info -@cindex manuals, on-line -@cindex on-line manuals - @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. - -@cindex find Info manual by its file name - With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer -@samp{*info*<@var{n}>}. This is useful if you want to browse multiple -Info manuals simultaneously. If you specify just @kbd{C-u} as the -prefix argument, @kbd{C-h i} prompts for the name of a documentation -file, so you can browse a file which doesn't have an entry in the -top-level Info menu. - - The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h -K @var{key}}, described above, enter Info and go straight to the -documentation of @var{function} or @var{key}. - -@kindex C-h S -@findex info-lookup-symbol - When editing a program, if you have an Info version of the manual -for the programming language, you can use @kbd{C-h S} -(@code{info-lookup-symbol}) to find an entry for a symbol (keyword, -function or variable) in the proper manual. The details of how this -command works depend on the major mode. - -@kindex C-h l -@findex view-lossage - If something surprising happens, and you are not sure what you typed, -use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays your last -300 input keystrokes. If you see commands that you don't know, you can -use @kbd{C-h c} to find out what they do. - -@kindex C-h e -@findex view-echo-area-messages - To review recent echo area messages, use @kbd{C-h e} -(@code{view-echo-area-messages}). This displays the buffer -@code{*Messages*}, where those messages are kept. - -@kindex C-h m -@findex describe-mode - Each Emacs major mode typically redefines a few keys and makes other -changes in how editing works. @kbd{C-h m} (@code{describe-mode}) -displays documentation on the current major mode, which normally -describes the commands and features that are changed in this mode. - -@kindex C-h b -@findex describe-bindings - @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} -(@code{describe-syntax}) show other information about the current -environment within Emacs. @kbd{C-h b} displays a list of all the key -bindings now in effect: first the local bindings of the current minor -modes, then the local bindings defined by the current major mode, and -finally the global bindings (@pxref{Key Bindings}). @kbd{C-h s} -displays the contents of the syntax table, with explanations of each -character's syntax (@pxref{Syntax}). - - You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h} after the prefix key. (There are a few prefix keys -for which this does not work---those that provide their own bindings -for @kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} -is actually @kbd{C-M-h}, which marks a defun.) - -@node Help Files -@section Help Files - - The Emacs help commands described above display dynamic help based -on the current state within Emacs, or refer to manuals. Other help -commands display pre-written, static help files. - - Except for @kbd{C-h g}, these commands all have the form @kbd{C-h -C-@var{char}}; that is, @kbd{C-h} followed by a control character. - -@kindex C-h C-c -@findex describe-copying -@kindex C-h C-d -@findex view-emacs-debugging -@kindex C-h C-e -@findex view-external-packages -@kindex C-h C-f -@findex view-emacs-FAQ -@kindex C-h g -@findex describe-gnu-project -@kindex C-h C-m -@findex view-order-manuals -@kindex C-h C-n -@findex view-emacs-news -@kindex C-h C-o -@findex describe-distribution -@kindex C-h C-p -@findex view-emacs-problems -@kindex C-h C-t -@findex view-emacs-todo -@kindex C-h C-w -@findex describe-no-warranty - -@table @kbd -@item C-h C-c -Display the Emacs copying conditions (@code{describe-copying}). -These are the rules under which you can copy and redistribute Emacs. -@item C-h C-d -Display how to debug Emacs problems (@code{view-emacs-debugging}). -@item C-h C-f -Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). -@item C-h g -Display general information about the GNU Project -(@code{describe-gnu-project}). -@item C-h C-m -Display how to order printed copies of Emacs manuals -(@code{view-order-manuals}). -@item C-h C-n -Display the Emacs ``news'' file, which lists new features in the most -recent version of Emacs (@code{view-emacs-news}). -@item C-h C-o -Display how to order or download the latest version of -Emacs and other GNU software (@code{describe-distribution}). -@item C-h C-p -Display the list of known Emacs problems, sometimes with suggested -workarounds (@code{view-emacs-problems}). -@item C-h C-t -Display the Emacs to-do list (@code{view-emacs-todo}). -@item C-h C-w -Display the full details on the complete absence of warranty for GNU -Emacs (@code{describe-no-warranty}). -@end table - -@node Help Echo -@section Help on Active Text and Tooltips - -@cindex tooltips -@cindex balloon help - When text on the screen is ``active'', so that it does something -special in response to mouse clicks or @kbd{RET}, it often has associated -help text. For instance, most parts of the mode line have help text. On -terminals that support mouse tracking, Emacs displays the help text as a -``tooltip'' (sometimes known as ``balloon help'') or in the echo area, -whenever you leave the mouse stationary over the active text. -@xref{Tooltips}. - -@kindex C-h . -@findex display-local-help -@vindex help-at-pt-display-when-idle - If your terminal doesn't support mouse-tracking, you can display the -help text for active buffer text using the keyboard. @kbd{C-h .} -(@code{display-local-help}) displays any help text associated with the -character after point, using the echo area. To display help text -automatically whenever it is available on the character after point, set -the variable @code{help-at-pt-display-when-idle} to @code{t}. - -@ignore - arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1 -@end ignore diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi deleted file mode 100644 index 9843bb33881..00000000000 --- a/doc/emacs/indent.texi +++ /dev/null @@ -1,251 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Indentation, Text, Major Modes, Top -@chapter Indentation -@cindex indentation -@cindex tabs -@cindex columns (indentation) - - This chapter describes the Emacs commands that add, remove, or -adjust indentation. - -@table @kbd -@item @key{TAB} -Indent the current line appropriately, in a mode-dependent fashion. -@item @kbd{C-j} -Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). -@item M-^ -Merge the previous and the current line (@code{delete-indentation}). -This would cancel the effect of a preceding @kbd{C-j}. -@item C-M-o -Split the current line at point; text on the line after point becomes a -new line indented to the same column where point is located -(@code{split-line}). -@item M-m -Move (forward or back) to the first nonblank character on the current -line (@code{back-to-indentation}). -@item C-M-\ -Indent lines in the region to the same column (@code{indent-region}). -@item C-x @key{TAB} -Shift lines in the region rigidly right or left (@code{indent-rigidly}). -@item M-i -Indent from point to the next prespecified tab stop column -(@code{tab-to-tab-stop}). -@item M-x indent-relative -Indent from point to under an indentation point in the previous line. -@end table - - In most major modes, the @key{TAB} key runs the command -@code{indent-for-tab-command}, which either performs indentation or -inserts whitespace at point, depending on the situation. - - In programming modes such as Lisp mode and C mode, @key{TAB} indents -the current line if the region is inactive. If the region is active, -it indents every line in the region (@pxref{Mark}). Indentation means -adding or removing some combination of space and tab characters -(@dfn{whitespace characters}) at the start of the line, in a way that -makes sense given the text in the preceding lines. Exactly how -indentation is performed depends on the major mode. @xref{Program -Indent}. - - In text modes, @key{TAB} inserts some whitespace characters to -advance point to the next tab stop (@pxref{Tab Stops}). For the -purposes of this command, the position of the first non-whitespace -character on the preceding line is treated as an additional tab stop. -You can therefore use @key{TAB} to ``align'' point with the preceding -line. If the region is active, @key{TAB} performs this action on -every line in the region. - -@vindex tab-width - Indentation is often performed with the help of @dfn{tab characters} -(@acronym{ASCII} code 9), which are displayed as a stretch of empty space -extending to the next @dfn{display tab stop}. By default, there is -one display tab stop every eight columns; the number of columns is -determined by the variable @code{tab-width}. You can insert a single -tab character by typing @kbd{C-q @key{TAB}}. @xref{Text Display}. - -@findex edit-tab-stops -@findex tab-to-tab-stop -@kindex M-i - The command @kbd{M-i} (@code{tab-to-tab-stop}) adjusts the -whitespace characters around point, inserting just enough whitespace -to advance point up to the next tab stop. By default, this involves -deleting the existing whitespace and inserting a single tab character. - - Normally, most of these indentation commands insert an optimal mix -of tabs and spaces to align to the desired column. @xref{Just -Spaces}, for how to disable use of tabs. However, @kbd{C-q @key{TAB}} -always inserts a tab, even when tabs are disabled for the indentation -commands. - -@menu -* Indentation Commands:: Various commands and techniques for indentation. -* Tab Stops:: You can set arbitrary "tab stops" and then - indent to the next tab stop when you want to. -* Just Spaces:: You can request indentation using just spaces. -@end menu - -@node Indentation Commands, Tab Stops, Indentation, Indentation -@section Indentation Commands and Techniques - -@kindex M-m -@findex back-to-indentation - To move over the indentation on a line, do @kbd{M-m} -(@code{back-to-indentation}). This command, given anywhere on a line, -positions point at the first nonblank character on the line, if any, -or else at the end of the line. - - To insert an indented line before the current line, do @kbd{C-a C-o -@key{TAB}}. To make an indented line after the current line, use -@kbd{C-e C-j}. - - If you just want to insert a tab character in the buffer, type -@kbd{C-q @key{TAB}}. - -@kindex C-M-o -@findex split-line - @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of -the line vertically down, so that the current line becomes two lines. -@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it -inserts after point a newline and enough indentation to reach the same -column point is on. Point remains before the inserted newline; in this -regard, @kbd{C-M-o} resembles @kbd{C-o}. - -@kindex M-^ -@findex delete-indentation - To join two lines cleanly, use the @kbd{M-^} -(@code{delete-indentation}) command. It deletes the indentation at -the front of the current line, and the line boundary as well, -replacing them with a single space. As a special case (useful for -Lisp code) the single space is omitted if the characters to be joined -are consecutive open parentheses or closing parentheses, or if the -junction follows another newline. To delete just the indentation of a -line, go to the beginning of the line and use @kbd{M-\} -(@code{delete-horizontal-space}), which deletes all spaces and tabs -around the cursor. - - If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it -appears after the newline that is deleted. @xref{Fill Prefix}. - -@kindex C-M-\ -@kindex C-x TAB -@findex indent-region -@findex indent-rigidly - There are also commands for changing the indentation of several lines -at once. They apply to all the lines that begin in the region. -@kbd{C-M-\} (@code{indent-region}) indents each line in the ``usual'' -way, as if you had typed @key{TAB} at the beginning of the line. A -numeric argument specifies the column to indent to, and each line is -shifted left or right so that its first nonblank character appears in -that column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of -the lines in the region right by its argument (left, for negative -arguments). The whole group of lines moves rigidly sideways, which is -how the command gets its name. - -@cindex remove indentation - To remove all indentation from all of the lines in the region, -invoke @kbd{C-x @key{TAB}} with a large negative argument, such as --1000. - -@findex indent-relative - @kbd{M-x indent-relative} indents at point based on the previous line -(actually, the last nonempty line). It inserts whitespace at point, moving -point, until it is underneath the next indentation point in the previous line. -An indentation point is the end of a sequence of whitespace or the end of -the line. If point is farther right than any indentation point in the -previous line, @code{indent-relative} runs @code{tab-to-tab-stop} -@ifnottex -(@pxref{Tab Stops}), -@end ifnottex -@iftex -(see next section), -@end iftex -unless it is called with a numeric argument, in which case it does -nothing. - - @xref{Format Indentation}, for another way of specifying the -indentation for part of your text. - -@node Tab Stops, Just Spaces, Indentation Commands, Indentation -@section Tab Stops - -@cindex tab stops -@cindex using tab stops in making tables -@cindex tables, indentation for -@kindex M-i -@findex tab-to-tab-stop - For typing in tables, you can use @kbd{M-i} (@code{tab-to-tab-stop}). -This command inserts indentation before point, enough to reach the -next tab stop column. - -@findex edit-tab-stops -@findex edit-tab-stops-note-changes -@kindex C-c C-c @r{(Edit Tab Stops)} -@vindex tab-stop-list - You can change the tab stops used by @kbd{M-i} and other indentation -commands, so that they need not be spaced every eight characters, or -even regularly spaced. The tab stops are stored in the variable -@code{tab-stop-list}, as a list of column numbers in increasing order. - - A convenient way to set the tab stops is with @kbd{M-x -edit-tab-stops}, which creates and selects a buffer containing a -description of the tab stop settings. You can edit this buffer to -specify different tab stops, and then type @kbd{C-c C-c} to make those -new tab stops take effect. The buffer uses Overwrite mode -(@pxref{Minor Modes}). @code{edit-tab-stops} records which buffer was -current when you invoked it, and stores the tab stops back in that -buffer; normally all buffers share the same tab stops and changing -them in one buffer affects all, but if you happen to make -@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in -that buffer will edit the local settings. - - Here is what the text representing the tab stops looks like for ordinary -tab stops every eight columns. - -@example - : : : : : : -0 1 2 3 4 -0123456789012345678901234567890123456789012345678 -To install changes, type C-c C-c -@end example - - The first line contains a colon at each tab stop. The remaining lines -are present just to help you see where the colons are and know what to do. - - Note that the tab stops that control @code{tab-to-tab-stop} have -nothing to do with how tab characters are displayed in the buffer. -Tab characters are always displayed as empty spaces extending to the -next display tab stop, which occurs every @code{tab-width} columns -regardless of the contents of @code{tab-stop-list}. @xref{Text -Display}. - -@node Just Spaces,, Tab Stops, Indentation -@section Tabs vs. Spaces - -@vindex indent-tabs-mode - Emacs normally uses both tabs and spaces to indent lines. If you -prefer, all indentation can be made from spaces only. To request -this, set @code{indent-tabs-mode} to @code{nil}. This is a per-buffer -variable, so altering the variable affects only the current buffer, -but there is a default value which you can change as well. -@xref{Locals}. - - A tab is not always displayed in the same way. By default, tabs are -eight columns wide, but some people like to customize their editors to -use a different tab width (e.g., by changing the variable -@code{tab-width} in Emacs). By using spaces only, you can make sure -that your file looks the same regardless of the tab width setting. - -@findex tabify -@findex untabify - There are also commands to convert tabs to spaces or vice versa, always -preserving the columns of all nonblank text. @kbd{M-x tabify} scans the -region for sequences of spaces, and converts sequences of at least two -spaces to tabs if that can be done without changing indentation. @kbd{M-x -untabify} changes all tabs in the region to appropriate numbers of spaces. - -@ignore - arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb -@end ignore diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi deleted file mode 100644 index 7626b2cfa06..00000000000 --- a/doc/emacs/killing.texi +++ /dev/null @@ -1,665 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. - -@node Killing, Yanking, Mark, Top -@chapter Killing and Moving Text - -@ifnottex -@raisesections -@end ifnottex - - @dfn{Killing} means erasing text and copying it into the @dfn{kill -ring}, from which you can bring it back into the buffer by -@dfn{yanking} it. (Some applications use the terms ``cutting'' and -``pasting'' for similar operations.) This is the most common way of -moving or copying text within Emacs. It is very versatile, because -there are commands for killing many different types of syntactic -units. - -@iftex -@section Deletion and Killing -@end iftex - -@cindex killing text -@cindex cutting text -@cindex deletion - Most commands which erase text from the buffer save it in the kill -ring. These are known as @dfn{kill} commands. The kill ring stores -several recent kills, not just the last one, so killing is a very safe -operation: when you make a new kill, you don't have to worry much -about losing text that you previously killed. - - You can yank text from the kill ring into any position in a buffer, -including a position in a different buffer; the kill ring is shared by -all buffers. The @kbd{C-/} (@code{undo}) command can undo both kill -and delete commands (@pxref{Undo}); the importance of the kill ring is -that you can yank the text in a different place. - - Commands that erase text but do not save it in the kill ring are -known as @dfn{delete} commands. These include @kbd{C-d} -(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}), -which delete only one character at a time, and those commands that -delete only spaces or newlines. Commands that can erase significant -amounts of nontrivial data generally do a kill operation instead. The -commands' names and individual descriptions use the words @samp{kill} -and @samp{delete} to say which kind of operation they perform. - -@vindex kill-read-only-ok -@cindex read-only text, killing - Some specialized buffers contain @dfn{read-only text}, which cannot -be modified and therefore cannot be killed. But some users like to -use the kill commands to copy read-only text into the kill ring, -without actually changing it. Therefore, the kill commands work -specially in a read-only buffer: they move over text, and copy it to -the kill ring, without actually deleting it from the buffer. -Normally, kill commands beep and display an error message when this -happens. But if you set the variable @code{kill-read-only-ok} to a -non-@code{nil} value, they just print a message in the echo area to -explain why the text has not been erased. - - You can also use the mouse to kill and yank. @xref{Cut and Paste}. - -@menu -* Deletion:: Commands for deleting small amounts of text and - blank areas. -* Killing by Lines:: How to kill entire lines of text at one time. -* Other Kill Commands:: Commands to kill large regions of text and - syntactic units such as words and sentences. -@end menu - -@need 1500 -@node Deletion -@subsection Deletion -@findex delete-backward-char -@findex delete-char - - Deletion means erasing text and not saving it in the kill ring. For -the most part, the Emacs commands that delete text are those that -erase just one character or only whitespace. - -@table @kbd -@item C-d -@itemx @key{Delete} -Delete next character (@code{delete-char}). -@item @key{DEL} -@itemx @key{Backspace} -Delete previous character (@code{delete-backward-char}). -@item M-\ -Delete spaces and tabs around point (@code{delete-horizontal-space}). -@item M-@key{SPC} -Delete spaces and tabs around point, leaving one space -(@code{just-one-space}). -@item C-x C-o -Delete blank lines around the current line (@code{delete-blank-lines}). -@item M-^ -Join two lines by deleting the intervening newline, along with any -indentation following it (@code{delete-indentation}). -@end table - - We have already described the basic deletion commands @kbd{C-d} -(@code{delete-char}) and @key{DEL} (@code{delete-backward-char}). -@xref{Erasing}. - -@kindex M-\ -@findex delete-horizontal-space -@kindex M-SPC -@findex just-one-space - The other delete commands are those that delete only whitespace -characters: spaces, tabs and newlines. @kbd{M-\} -(@code{delete-horizontal-space}) deletes all the spaces and tab -characters before and after point. With a prefix argument, this only -deletes spaces and tab characters before point. @kbd{M-@key{SPC}} -(@code{just-one-space}) does likewise but leaves a single space after -point, regardless of the number of spaces that existed previously -(even if there were none before). With a numeric argument @var{n}, it -leaves @var{n} spaces after point. - - @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines -after the current line. If the current line is blank, it deletes all -blank lines preceding the current line as well (leaving one blank line, -the current line). On a solitary blank line, it deletes that line. - - @kbd{M-^} (@code{delete-indentation}) joins the current line and the -previous line, by deleting a newline and all surrounding spaces, usually -leaving a single space. @xref{Indentation,M-^}. - -@node Killing by Lines -@subsection Killing by Lines - -@table @kbd -@item C-k -Kill rest of line or one or more lines (@code{kill-line}). -@item C-S-backspace -Kill an entire line at once (@code{kill-whole-line}) -@end table - -@kindex C-k -@findex kill-line - The simplest kill command is @kbd{C-k}. If given at the beginning -of a line, it kills all the text on the line@footnote{Here, ``line'' -means a logical text line, not a screen line. @xref{Continuation -Lines}.}, leaving it blank. When used on a blank line, it kills the -whole line including its newline. - - More precisely, @kbd{C-k} kills from point up to the end of the -line, unless it is at the end of a line. In that case it kills the -newline following point, thus merging the next line into the current -one. Spaces and tabs at the end of the line are ignored when deciding -which case applies, so as long as point is after the last visible -character in the line, you can be sure that @kbd{C-k} will kill the -newline. To kill an entire non-blank line, go to the beginning and -type @kbd{C-k} twice. - - When @kbd{C-k} is given a positive argument @var{n}, it kills -@var{n} lines and the newlines that follow them (text on the current -line before point is not killed). With a negative argument -@minus{}@var{n}, it kills @var{n} lines preceding the current line, -together with the text on the current line before point. @kbd{C-k} -with an argument of zero kills the text before point on the current -line. - -@vindex kill-whole-line - If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at -the very beginning of a line kills the entire line including the -following newline. This variable is normally @code{nil}. - -@kindex C-S-backspace -@findex kill-whole-line - @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line -including its newline regardless of the position of point within the -line. Note that many character terminals will prevent you from typing -the key sequence @kbd{C-S-backspace}. - -@node Other Kill Commands -@subsection Other Kill Commands -@findex kill-region -@kindex C-w - -@table @kbd -@item C-w -Kill region (@code{kill-region}). @xref{Mark}. -@item M-w -Save region as last killed text without actually killing it -(@code{kill-ring-save}). Some programs call this ``copying.'' -@item M-d -Kill word (@code{kill-word}). @xref{Words}. -@item M-@key{DEL} -Kill word backwards (@code{backward-kill-word}). -@item C-x @key{DEL} -Kill back to beginning of sentence (@code{backward-kill-sentence}). -@xref{Sentences}. -@item M-k -Kill to end of sentence (@code{kill-sentence}). -@item C-M-k -Kill the following balanced expression (@code{kill-sexp}). @xref{Expressions}. -@item M-z @var{char} -Kill through the next occurrence of @var{char} (@code{zap-to-char}). -@end table - - Apart from @kbd{C-k}, the most commonly-used kill command is -@kbd{C-w} (@code{kill-region}), which kills the text in the region -(i.e., between point and mark). @xref{Mark}. If the mark is inactive -when you type @kbd{C-w}, it first reactivates the mark where it was -last set. The mark is deactivated at the end of the command. - -@kindex M-w -@findex kill-ring-save - The command @kbd{M-w} (@code{kill-ring-save}) copies the region into -the kill ring without removing it from the buffer. This is -approximately equivalent to @kbd{C-w} followed by @kbd{C-/}, except -that @kbd{M-w} does not alter the undo history. - - Emacs also provides commands to kill specific syntactic units: -words, with @kbd{M-@key{DEL}} and @kbd{M-d} (@pxref{Words}); balanced -expressions, with @kbd{C-M-k} (@pxref{Expressions}); and sentences, -with @kbd{C-x @key{DEL}} and @kbd{M-k} (@pxref{Sentences}). - -@kindex M-z -@findex zap-to-char - The command @kbd{M-z} (@code{zap-to-char}) combines killing with -searching: it reads a character and kills from point up to (and -including) the next occurrence of that character in the buffer. A -numeric argument acts as a repeat count; a negative argument means to -search backward and kill text before point. - -@node Yanking, Accumulating Text, Killing, Top -@section Yanking -@cindex moving text -@cindex copying text -@cindex kill ring -@cindex yanking -@cindex pasting - - @dfn{Yanking} means reinserting text previously killed. The usual -way to move or copy text is to kill it and then yank it elsewhere one -or more times. - -@table @kbd -@item C-y -Yank last killed text (@code{yank}). -@item M-y -Replace text just yanked with an earlier batch of killed text -(@code{yank-pop}). -@item C-M-w -Append next kill to last batch of killed text (@code{append-next-kill}). -@end table - - On graphical displays with window systems, if there is a current -selection in some other application, and you selected it more recently -than you killed any text in Emacs, @kbd{C-y} copies the selection -instead of text killed within Emacs. - -@menu -* Kill Ring:: Where killed text is stored. Basic yanking. -* Appending Kills:: Several kills in a row all yank together. -* Earlier Kills:: Yanking something killed some time ago. -@end menu - -@node Kill Ring -@subsection The Kill Ring - - All killed text is recorded in the @dfn{kill ring}, a list of blocks -of text that have been killed. There is only one kill ring, shared by -all buffers, so you can kill text in one buffer and yank it in another -buffer. This is the usual way to move text from one file to another. -(There are several other methods: for instance, you could store the -text in a register. @xref{Registers}, for information about -registers. @xref{Accumulating Text}, for some other ways to move text -around.) - -@kindex C-y -@findex yank - The command @kbd{C-y} (@code{yank}) reinserts the text of the most -recent kill, leaving the cursor at the end of the text. It also adds -the position of the beginning of the text to the mark ring, without -activating the mark; this allows you to jump easily to that position -with @kbd{C-x C-x} (@pxref{Setting Mark}). With a plain prefix -argument (@kbd{C-u C-y}), it instead leaves the cursor in front of the -text, and adds the position of the end of the text to the mark ring. -Using other sort of prefix argument specifies an earlier kill; for -example, @kbd{C-u 4 C-y} reinserts the fourth most recent kill. -@xref{Earlier Kills}. - -@cindex yanking and text properties -@vindex yank-excluded-properties - The yank commands discard certain properties from the yanked text. -These are properties that might lead to annoying results, such as -causing the text to respond to the mouse or specifying key bindings. -The list of properties to discard is stored in the variable -@code{yank-excluded-properties}. Yanking of register contents and -rectangles also discard these properties. @xref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}, for more information about -text properties. - -@node Appending Kills -@subsection Appending Kills - -@cindex appending kills in the ring - Normally, each kill command pushes a new entry onto the kill ring. -However, two or more kill commands in a row combine their text into a -single entry, so that a single @kbd{C-y} yanks all the text as a unit, -just as it was before it was killed. - - Thus, if you want to yank text as a unit, you need not kill all of it -with one command; you can keep killing line after line, or word after -word, until you have killed it all, and you can still get it all back at -once. - - Commands that kill forward from point add onto the end of the previous -killed text. Commands that kill backward from point add text onto the -beginning. This way, any sequence of mixed forward and backward kill -commands puts all the killed text into one entry without rearrangement. -Numeric arguments do not break the sequence of appending kills. For -example, suppose the buffer contains this text: - -@example -This is a line @point{}of sample text. -@end example - -@noindent -with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d -M-@key{DEL}}, killing alternately forward and backward, you end up with -@samp{a line of sample} as one entry in the kill ring, and @samp{This -is@ @ text.} in the buffer. (Note the double space between @samp{is} -and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or -@kbd{M-q}.) - - Another way to kill the same text is to move back two words with -@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. -This produces exactly the same results in the buffer and in the kill -ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going -backward; once again, the result is the same. The text in the kill ring -entry always has the same order that it had in the buffer before you -killed it. - -@kindex C-M-w -@findex append-next-kill - If a kill command is separated from the last kill command by other -commands (not just numeric arguments), it starts a new entry on the kill -ring. But you can force it to append by first typing the command -@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} -tells the following command, if it is a kill command, to append the text -it kills to the last killed text, instead of starting a new entry. With -@kbd{C-M-w}, you can kill several separated pieces of text and -accumulate them to be yanked back in one place.@refill - - A kill command following @kbd{M-w} (@code{kill-ring-save}) does not -append to the text that @kbd{M-w} copied into the kill ring. - -@node Earlier Kills -@subsection Yanking Earlier Kills - -@cindex yanking previous kills -@kindex M-y -@findex yank-pop - To recover killed text that is no longer the most recent kill, use the -@kbd{M-y} command (@code{yank-pop}). It takes the text previously -yanked and replaces it with the text from an earlier kill. So, to -recover the text of the next-to-the-last kill, first use @kbd{C-y} to -yank the last kill, and then use @kbd{M-y} to replace it with the -previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another -@kbd{M-y}. - - You can understand @kbd{M-y} in terms of a ``last yank'' pointer which -points at an entry in the kill ring. Each time you kill, the ``last -yank'' pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. -@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the -text in the buffer changes to match. Enough @kbd{M-y} commands can move -the pointer to any entry in the ring, so you can get any entry into the -buffer. Eventually the pointer reaches the end of the ring; the next -@kbd{M-y} loops back around to the first entry again. - - @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does -not change the order of the entries in the ring, which always runs from -the most recent kill at the front to the oldest one still remembered. - - @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the ``last yank'' pointer by. A negative argument moves the -pointer toward the front of the ring; from the front of the ring, it -moves ``around'' to the last entry and continues forward from there. - - Once the text you are looking for is brought into the buffer, you can -stop doing @kbd{M-y} commands and it will stay there. It's just a copy -of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the ``last -yank'' pointer remains at the same place in the kill ring, so repeating -@kbd{C-y} will yank another copy of the same previous kill. - - If you know how many @kbd{M-y} commands it would take to find the -text you want, you can yank that text in one step using @kbd{C-y} with -a numeric argument. @kbd{C-y} with an argument restores the text from -the specified kill ring entry, counting back from the most recent as -1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killed -text---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numeric -argument starts counting from the ``last yank'' pointer, and sets the -``last yank'' pointer to the entry that it yanks. - -@vindex kill-ring-max - The length of the kill ring is controlled by the variable -@code{kill-ring-max}; no more than that many blocks of killed text are -saved. - -@vindex kill-ring - The actual contents of the kill ring are stored in a variable named -@code{kill-ring}; you can view the entire contents of the kill ring with -the command @kbd{C-h v kill-ring}. - -@node Accumulating Text, Rectangles, Yanking, Top -@section Accumulating Text -@findex append-to-buffer -@findex prepend-to-buffer -@findex copy-to-buffer -@findex append-to-file - -@cindex accumulating scattered text - Usually we copy or move text by killing it and yanking it, but there -are other convenient methods for copying one block of text in many -places, or for copying many scattered blocks of text into one place. -Here we describe the commands to accumulate scattered pieces of text -into a buffer or into a file. - -@table @kbd -@item M-x append-to-buffer -Append region to the contents of a specified buffer. -@item M-x prepend-to-buffer -Prepend region to the contents of a specified buffer. -@item M-x copy-to-buffer -Copy region into a specified buffer, deleting that buffer's old contents. -@item M-x insert-buffer -Insert the contents of a specified buffer into current buffer at point. -@item M-x append-to-file -Append region to the contents of a specified file, at the end. -@end table - - To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. -This reads a buffer name, then inserts a copy of the region into the -buffer specified. If you specify a nonexistent buffer, -@code{append-to-buffer} creates the buffer. The text is inserted -wherever point is in that buffer. If you have been using the buffer for -editing, the copied text goes into the middle of the text of the buffer, -starting from wherever point happens to be at that moment. - - Point in that buffer is left at the end of the copied text, so -successive uses of @code{append-to-buffer} accumulate the text in the -specified buffer in the same order as they were copied. Strictly -speaking, @code{append-to-buffer} does not always append to the text -already in the buffer---it appends only if point in that buffer is at the end. -However, if @code{append-to-buffer} is the only command you use to alter -a buffer, then point is always at the end. - - @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} -except that point in the other buffer is left before the copied text, so -successive prependings add text in reverse order. @kbd{M-x -copy-to-buffer} is similar, except that any existing text in the other -buffer is deleted, so the buffer is left containing just the text newly -copied into it. - - The command @kbd{M-x insert-buffer} can be used to retrieve the -accumulated text from another buffer. This prompts for the name of a -buffer, and inserts a copy of all the text in that buffer into the -current buffer at point, leaving point at the beginning of the -inserted text. It also adds the position of the end of the inserted -text to the mark ring, without activating the mark. @xref{Buffers}, -for background information on buffers. - - Instead of accumulating text in a buffer, you can append text -directly into a file with @kbd{M-x append-to-file}. This prompts for -a filename, and adds the text of the region to the end of the -specified file. The file is changed immediately on disk. - - You should use @code{append-to-file} only with files that are -@emph{not} being visited in Emacs. Using it on a file that you are -editing in Emacs would change the file behind Emacs's back, which -can lead to losing some of your editing. - - Another way to move text around is to store it in a register. -@xref{Registers}. - -@node Rectangles, CUA Bindings, Accumulating Text, Top -@section Rectangles -@cindex rectangle -@cindex columns (and rectangles) -@cindex killing rectangular areas of text - - @dfn{Rectangle} commands operate on rectangular areas of the text: -all the characters between a certain pair of columns, in a certain -range of lines. Emacs has commands to kill rectangles, yank killed -rectangles, clear them out, fill them with blanks or text, or delete -them. Rectangle commands are useful with text in multicolumn formats, -and for changing text into or out of such formats. - -@cindex mark rectangle - When you must specify a rectangle for a command to work on, you do it -by putting the mark at one corner and point at the opposite corner. The -rectangle thus specified is called the @dfn{region-rectangle} because -you control it in much the same way as the region is controlled. But -remember that a given combination of point and mark values can be -interpreted either as a region or as a rectangle, depending on the -command that uses them. - - If point and the mark are in the same column, the rectangle they -delimit is empty. If they are in the same line, the rectangle is one -line high. This asymmetry between lines and columns comes about -because point (and likewise the mark) is between two columns, but within -a line. - -@table @kbd -@item C-x r k -Kill the text of the region-rectangle, saving its contents as the -``last killed rectangle'' (@code{kill-rectangle}). -@item C-x r d -Delete the text of the region-rectangle (@code{delete-rectangle}). -@item C-x r y -Yank the last killed rectangle with its upper left corner at point -(@code{yank-rectangle}). -@item C-x r o -Insert blank space to fill the space of the region-rectangle -(@code{open-rectangle}). This pushes the previous contents of the -region-rectangle rightward. -@item C-x r c -Clear the region-rectangle by replacing all of its contents with spaces -(@code{clear-rectangle}). -@item M-x delete-whitespace-rectangle -Delete whitespace in each of the lines on the specified rectangle, -starting from the left edge column of the rectangle. -@item C-x r t @var{string} @key{RET} -Replace rectangle contents with @var{string} on each line -(@code{string-rectangle}). -@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} -Insert @var{string} on each line of the rectangle. -@end table - - The rectangle operations fall into two classes: commands for -deleting and inserting rectangles, and commands for blank rectangles. - -@kindex C-x r k -@kindex C-x r d -@findex kill-rectangle -@findex delete-rectangle - There are two ways to get rid of the text in a rectangle: you can -discard the text (delete it) or save it as the ``last killed'' -rectangle. The commands for these two ways are @kbd{C-x r d} -(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In -either case, the portion of each line that falls inside the rectangle's -boundaries is deleted, causing any following text on the line to -move left into the gap. - - Note that ``killing'' a rectangle is not killing in the usual sense; the -rectangle is not stored in the kill ring, but in a special place that -can only record the most recent rectangle killed. This is because yanking -a rectangle is so different from yanking linear text that different yank -commands have to be used. It is hard to define yank-popping for rectangles, -so we do not try. - -@kindex C-x r y -@findex yank-rectangle - To yank the last killed rectangle, type @kbd{C-x r y} -(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing -one. Point specifies where to put the rectangle's upper left corner. -The rectangle's first line is inserted there, the rectangle's second -line is inserted at the same horizontal position, but one line -vertically down, and so on. The number of lines affected is determined -by the height of the saved rectangle. - - You can convert single-column lists into double-column lists using -rectangle killing and yanking; kill the second half of the list as a -rectangle and then yank it beside the first line of the list. -@xref{Two-Column}, for another way to edit multi-column text. - - You can also copy rectangles into and out of registers with @kbd{C-x r -r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle -Registers}. - -@kindex C-x r o -@findex open-rectangle -@kindex C-x r c -@findex clear-rectangle - There are two commands you can use for making blank rectangles: -@kbd{C-x r c} (@code{clear-rectangle}) which blanks out existing text, -and @kbd{C-x r o} (@code{open-rectangle}) which inserts a blank -rectangle. Clearing a rectangle is equivalent to deleting it and then -inserting a blank rectangle of the same size. - -@findex delete-whitespace-rectangle - The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal -whitespace starting from a particular column. This applies to each of -the lines in the rectangle, and the column is specified by the left -edge of the rectangle. The right edge of the rectangle does not make -any difference to this command. - -@kindex C-x r t -@findex string-rectangle - The command @kbd{C-x r t} (@code{string-rectangle}) replaces the -contents of a region-rectangle with a string on each line. The -string's width need not be the same as the width of the rectangle. If -the string's width is less, the text after the rectangle shifts left; -if the string is wider than the rectangle, the text after the -rectangle shifts right. - -@findex string-insert-rectangle - The command @kbd{M-x string-insert-rectangle} is similar to -@code{string-rectangle}, but inserts the string on each line, -shifting the original text to the right. - -@node CUA Bindings, Registers, Rectangles, Top -@section CUA Bindings -@findex cua-mode -@vindex cua-mode -@cindex CUA key bindings -@vindex cua-enable-cua-keys - The command @kbd{M-x cua-mode} sets up key bindings that are -compatible with the Common User Access (CUA) system used in many other -applications. @kbd{C-x} means cut (kill), @kbd{C-c} copy, @kbd{C-v} -paste (yank), and @kbd{C-z} undo. Standard Emacs commands like -@kbd{C-x C-c} still work, because @kbd{C-x} and @kbd{C-c} only take -effect when the mark is active (and the region is highlighted). -However, if you don't want to override these bindings in Emacs at all, -set @code{cua-enable-cua-keys} to @code{nil}. - - To enter an Emacs command like @kbd{C-x C-f} while the mark is -active, use one of the following methods: either hold @kbd{Shift} -together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type -the prefix key twice, e.g. @kbd{C-x C-x C-f}. - - In CUA mode, typed text replaces the active region as in -Delete-Selection mode (@pxref{Mouse Commands}). - -@cindex rectangle highlighting - CUA mode provides enhanced rectangle support with visible -rectangle highlighting. Use @kbd{C-RET} to start a rectangle, -extend it using the movement commands, and cut or copy it using -@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next -(clockwise) corner of the rectangle, so you can easily expand it in -any direction. Normal text you type is inserted to the left or right -of each line in the rectangle (on the same side as the cursor). - - With CUA you can easily copy text and rectangles into and out of -registers by providing a one-digit numeric prefix to the kill, copy, -and yank commands, e.g. @kbd{C-1 C-c} copies the region into register -@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. - -@cindex global mark - CUA mode also has a global mark feature which allows easy moving and -copying of text between buffers. Use @kbd{C-S-SPC} to toggle the -global mark on and off. When the global mark is on, all text that you -kill or copy is automatically inserted at the global mark, and text -you type is inserted at the global mark rather than at the current -position. - - For example, to copy words from various buffers into a word list in -a given buffer, set the global mark in the target buffer, then -navigate to each of the words you want in the list, mark it (e.g. with -@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and -insert a newline after the word in the target list by pressing -@key{RET}. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c -@end ignore diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi deleted file mode 100644 index 07990959f4c..00000000000 --- a/doc/emacs/kmacro.texi +++ /dev/null @@ -1,575 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Keyboard Macros, Files, Fixit, Top -@chapter Keyboard Macros -@cindex defining keyboard macros -@cindex keyboard macro - - In this chapter we describe how to record a sequence of editing -commands so you can repeat it conveniently later. - - A @dfn{keyboard macro} is a command defined by an Emacs user to stand for -another sequence of keys. For example, if you discover that you are -about to type @kbd{C-n M-d C-d} forty times, you can speed your work by -defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing -it 39 more times. - - You define a keyboard macro by executing and recording the commands -which are its definition. Put differently, as you define a keyboard -macro, the definition is being executed for the first time. This way, -you can see the effects of your commands, so that you don't have to -figure them out in your head. When you close the definition, the -keyboard macro is defined and also has been, in effect, executed once. -You can then do the whole thing over again by invoking the macro. - - Keyboard macros differ from ordinary Emacs commands in that they are -written in the Emacs command language rather than in Lisp. This makes it -easier for the novice to write them, and makes them more convenient as -temporary hacks. However, the Emacs command language is not powerful -enough as a programming language to be useful for writing anything -intelligent or general. For such things, Lisp must be used. - -@menu -* Basic Keyboard Macro:: Defining and running keyboard macros. -* Keyboard Macro Ring:: Where previous keyboard macros are saved. -* Keyboard Macro Counter:: Inserting incrementing numbers in macros. -* Keyboard Macro Query:: Making keyboard macros do different things each time. -* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. -* Edit Keyboard Macro:: Editing keyboard macros. -* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard - macro. -@end menu - -@node Basic Keyboard Macro -@section Basic Use - -@table @kbd -@item @key{F3} -Start defining a keyboard macro -(@code{kmacro-start-macro-or-insert-counter}). -@item @key{F4} -If a keyboard macro is being defined, end the definition; otherwise, -execute the most recent keyboard macro -(@code{kmacro-end-or-call-macro}). -@item C-u @key{F3} -Re-execute last keyboard macro, then append keys to its definition. -@item C-u C-u @key{F3} -Append keys to the last keyboard macro without re-executing it. -@item C-x C-k r -Run the last keyboard macro on each line that begins in the region -(@code{apply-macro-to-region-lines}). -@end table - -@kindex F3 -@kindex F4 -@findex kmacro-start-macro-or-insert-counter -@findex kmacro-end-or-call-macro -@findex kmacro-end-and-call-macro - To start defining a keyboard macro, type @key{F3}. From then on, -your keys continue to be executed, but also become part of the -definition of the macro. @samp{Def} appears in the mode line to -remind you of what is going on. When you are finished, type @key{F4} -(@code{kmacro-end-or-call-macro}) to terminate the definition. For -example, - -@example -@key{F3} M-f foo @key{F4} -@end example - -@noindent -defines a macro to move forward a word and then insert @samp{foo}. -Note that @key{F3} and @key{F4} do not become part of the macro. - - After defining the macro, you can call it with @key{F4}. For the -above example, this has the same effect as typing @kbd{M-f foo} again. -(Note the two roles of the @key{F4} command: it ends the macro if you -are in the process of defining one, or calls the last macro -otherwise.) You can also supply @key{F4} with a numeric prefix -argument @samp{n}, which means to invoke the macro @samp{n} times. An -argument of zero repeats the macro indefinitely, until it gets an -error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}). - - The above example demonstrates a handy trick that you can employ -with keyboard macros: if you wish to repeat an operation at regularly -spaced places in the text, include a motion command as part of the -macro. In this case, repeating the macro inserts the string -@samp{foo} after each successive word. - - After terminating the definition of a keyboard macro, you can append -more keystrokes to its definition by typing @kbd{C-u @key{F3}}. This -is equivalent to plain @key{F3} followed by retyping the whole -definition so far. As a consequence, it re-executes the macro as -previously defined. If you change the variable -@code{kmacro-execute-before-append} to @code{nil}, the existing macro -will not be re-executed before appending to it (the default is -@code{t}). You can also add to the end of the definition of the last -keyboard macro without re-executing it by typing @kbd{C-u C-u -@key{F3}}. - - When a command reads an argument with the minibuffer, your -minibuffer input becomes part of the macro along with the command. So -when you replay the macro, the command gets the same argument as when -you entered the macro. For example, - -@example -@key{F3} C-a C-k C-x b foo @key{RET} C-y C-x b @key{RET} @key{F4} -@end example - -@noindent -defines a macro that kills the current line, yanks it into the buffer -@samp{foo}, then returns to the original buffer. - - Most keyboard commands work as usual in a keyboard macro definition, -with some exceptions. Typing @kbd{C-g} (@code{keyboard-quit}) quits -the keyboard macro definition. Typing @kbd{C-M-c} -(@code{exit-recursive-edit}) can be unreliable: it works as you'd -expect if exiting a recursive edit that started within the macro, but -if it exits a recursive edit that started before you invoked the -keyboard macro, it also necessarily exits the keyboard macro too. -Mouse events are also unreliable, even though you can use them in a -keyboard macro: when the macro replays the mouse event, it uses the -original mouse position of that event, the position that the mouse had -while you were defining the macro. The effect of this may be hard to -predict. - -@findex apply-macro-to-region-lines -@kindex C-x C-k r - The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) -repeats the last defined keyboard macro on each line that begins in -the region. It does this line by line, by moving point to the -beginning of the line and then executing the macro. - -@kindex C-x ( -@kindex C-x ) -@kindex C-x e -@findex kmacro-start-macro -@findex kmacro-end-macro - In addition to the @key{F3} and @key{F4} commands described above, -Emacs also supports an older set of keybindings for defining and -executing keyboard macros. To begin a macro definition, type @kbd{C-x -(} (@code{kmacro-start-macro}); as with @key{F3}, a prefix argument -appends this definition to the last keyboard macro. To end a macro -definition, type @kbd{C-x )} (@code{kmacro-end-macro}). To execute -the most recent macro, type @kbd{C-x e} -(@code{kmacro-end-and-call-macro}). If you enter @kbd{C-x e} while -defining a macro, the macro is terminated and executed immediately. -Immediately after typing @kbd{C-x e}, you can type @key{e} repeatedly -to immediately repeat the macro one or more times. You can also give -@kbd{C-x e} a repeat argument, just like @key{F4}. - - @kbd{C-x )} can be given a repeat count as an argument. This means -to repeat the macro right after defining it. The macro definition -itself counts as the first repetition, since it is executed as you -define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3 -additional times. - -@node Keyboard Macro Ring -@section The Keyboard Macro Ring - - All defined keyboard macros are recorded in the @dfn{keyboard macro -ring}. There is only one keyboard macro ring, shared by all buffers. - -@table @kbd -@item C-x C-k C-k -Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). -@item C-x C-k C-n -Rotate the keyboard macro ring to the next macro (defined earlier) -(@code{kmacro-cycle-ring-next}). -@item C-x C-k C-p -Rotate the keyboard macro ring to the previous macro (defined later) -(@code{kmacro-cycle-ring-previous}). -@end table - - All commands which operate on the keyboard macro ring use the -same @kbd{C-x C-k} prefix. Most of these commands can be executed and -repeated immediately after each other without repeating the @kbd{C-x -C-k} prefix. For example, - -@example -C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d -@end example - -@noindent -will rotate the keyboard macro ring to the ``second previous'' macro, -execute the resulting head macro three times, rotate back to the -original head macro, execute that once, rotate to the ``previous'' -macro, execute that, and finally delete it from the macro ring. - -@findex kmacro-end-or-call-macro-repeat -@kindex C-x C-k C-k - The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) -executes the keyboard macro at the head of the macro ring. You can -repeat the macro immediately by typing another @kbd{C-k}, or you can -rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. - - When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves -like @key{F4} except that, immediately afterward, you can use most key -bindings of this section without the @kbd{C-x C-k} prefix. For -instance, another @kbd{C-k} will re-execute the macro. - -@findex kmacro-cycle-ring-next -@kindex C-x C-k C-n -@findex kmacro-cycle-ring-previous -@kindex C-x C-k C-p - The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and -@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the -macro ring, bringing the next or previous keyboard macro to the head -of the macro ring. The definition of the new head macro is displayed -in the echo area. You can continue to rotate the macro ring -immediately by repeating just @kbd{C-n} and @kbd{C-p} until the -desired macro is at the head of the ring. To execute the new macro -ring head immediately, just type @kbd{C-k}. - - Note that Emacs treats the head of the macro ring as the ``last -defined keyboard macro.'' For instance, @key{F4} will execute that -macro, and @kbd{C-x C-k n} will give it a name. - -@vindex kmacro-ring-max - The maximum number of macros stored in the keyboard macro ring is -determined by the customizable variable @code{kmacro-ring-max}. - -@node Keyboard Macro Counter -@section The Keyboard Macro Counter - - Each keyboard macro has an associated counter, which is initialized -to 0 when you start defining the macro. This counter allows you to -insert a number into the buffer that depends on the number of times -the macro has been called. The counter is incremented each time its -value is inserted into the buffer. - -@table @kbd -@item @key{F3} -In a keyboard macro definition, insert the keyboard macro counter -value in the buffer (@code{kmacro-start-macro-or-insert-counter}). -@item C-x C-k C-i -Insert the keyboard macro counter value in the buffer -(@code{kmacro-insert-counter}). -@item C-x C-k C-c -Set the keyboard macro counter (@code{kmacro-set-counter}). -@item C-x C-k C-a -Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). -@item C-x C-k C-f -Specify the format for inserting the keyboard macro counter -(@code{kmacro-set-format}). -@end table - -@findex kmacro-insert-counter -@kindex C-x C-k C-i - When you are defining a keyboard macro, the command @key{F3} -(@code{kmacro-start-macro-or-insert-counter}) inserts the current -value of the keyboard macro's counter into the buffer, and increments -the counter by 1. (If you are not defining a macro, @key{F3} begins a -macro definition instead. @xref{Basic Keyboard Macro}.) You can use -a numeric prefix argument to specify a different increment. If you -just specify a @kbd{C-u} prefix, that is the same as an increment of -zero: it inserts the current counter value without changing it. - - As an example, let us show how the keyboard macro counter can be -used to build a numbered list. Consider the following key sequence: - -@example -@key{F3} C-a @key{F3} . @key{SPC} @key{F4} -@end example - -@noindent -As part of this keyboard macro definition, the string @samp{0. } was -inserted into the beginning of the current line. If you now move -somewhere else in the buffer and type @key{F4} to invoke the macro, -the string @samp{1. } is inserted at the beginning of that line. -Subsequent invocations insert @samp{2. }, @samp{3. }, and so forth. - - The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) does -the same thing as @key{F3}, but it can be used outside a keyboard -macro definition. When no keyboard macro is being defined or -executed, it inserts and increments the counter of the macro at the -head of the keyboard macro ring. - -@findex kmacro-set-counter -@kindex C-x C-k C-c - The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the -current macro counter to the value of the numeric argument. If you use -it inside the macro, it operates on each repetition of the macro. If -you specify just @kbd{C-u} as the prefix, while executing the macro, -that resets the counter to the value it had at the beginning of the -current repetition of the macro (undoing any increments so far in this -repetition). - -@findex kmacro-add-counter -@kindex C-x C-k C-a - The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the -prefix argument to the current macro counter. With just @kbd{C-u} as -argument, it resets the counter to the last value inserted by any -keyboard macro. (Normally, when you use this, the last insertion -will be in the same macro and it will be the same counter.) - -@findex kmacro-set-format -@kindex C-x C-k C-f - The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for -the format to use when inserting the macro counter. The default -format is @samp{%d}, which means to insert the number in decimal -without any padding. You can exit with empty minibuffer to reset the -format to this default. You can specify any format string that the -@code{format} function accepts and that makes sense with a single -integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). Do not put the format string inside double -quotes when you insert it in the minibuffer. - - If you use this command while no keyboard macro is being defined or -executed, the new format affects all subsequent macro definitions. -Existing macros continue to use the format in effect when they were -defined. If you set the format while defining a keyboard macro, this -affects the macro being defined from that point on, but it does not -affect subsequent macros. Execution of the macro will, at each step, -use the format in effect at that step during its definition. Changes -to the macro format during execution of a macro, like the -corresponding changes during its definition, have no effect on -subsequent macros. - - The format set by @kbd{C-x C-k C-f} does not affect insertion of -numbers stored in registers. - - If you use a register as a counter, incrementing it on each -repetition of the macro, that accomplishes the same thing as a -keyboard macro counter. @xref{RegNumbers}. For most purposes, it is -simpler to use a keyboard macro counter. - -@node Keyboard Macro Query -@section Executing Macros with Variations - - In a keyboard macro, you can create an effect similar to that of -@code{query-replace}, in that the macro asks you each time around -whether to make a change. - -@table @kbd -@item C-x q -When this point is reached during macro execution, ask for confirmation -(@code{kbd-macro-query}). -@end table - -@kindex C-x q -@findex kbd-macro-query - While defining the macro, type @kbd{C-x q} at the point where you -want the query to occur. During macro definition, the @kbd{C-x q} -does nothing, but when you run the macro later, @kbd{C-x q} asks you -interactively whether to continue. - - The valid responses when @kbd{C-x q} asks are: - -@table @asis -@item @key{SPC} (or @kbd{y}) -Continue executing the keyboard macro. - -@item @key{DEL} (or @kbd{n}) -Skip the remainder of this repetition of the macro, and start right -away with the next repetition. - -@item @key{RET} (or @kbd{q}) -Skip the remainder of this repetition and cancel further repetitions. - -@item @kbd{C-r} -Enter a recursive editing level, in which you can perform editing -which is not part of the macro. When you exit the recursive edit -using @kbd{C-M-c}, you are asked again how to continue with the -keyboard macro. If you type a @key{SPC} at this time, the rest of the -macro definition is executed. It is up to you to leave point and the -text in a state such that the rest of the macro will do what you want. -@end table - - @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, -performs a completely different function. It enters a recursive edit -reading input from the keyboard, both when you type it during the -definition of the macro, and when it is executed from the macro. During -definition, the editing you do inside the recursive edit does not become -part of the macro. During macro execution, the recursive edit gives you -a chance to do some particularized editing on each repetition. -@xref{Recursive Edit}. - -@node Save Keyboard Macro -@section Naming and Saving Keyboard Macros - -@table @kbd -@item C-x C-k n -Give a command name (for the duration of the Emacs session) to the most -recently defined keyboard macro (@code{kmacro-name-last-macro}). -@item C-x C-k b -Bind the most recently defined keyboard macro to a key sequence (for -the duration of the session) (@code{kmacro-bind-to-key}). -@item M-x insert-kbd-macro -Insert in the buffer a keyboard macro's definition, as Lisp code. -@end table - -@cindex saving keyboard macros -@findex kmacro-name-last-macro -@kindex C-x C-k n - If you wish to save a keyboard macro for later use, you can give it -a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). -This reads a name as an argument using the minibuffer and defines that -name to execute the last keyboard macro, in its current form. (If you -later add to the definition of this macro, that does not alter the -name's definition as a macro.) The macro name is a Lisp symbol, and -defining it in this way makes it a valid command name for calling with -@kbd{M-x} or for binding a key to with @code{global-set-key} -(@pxref{Keymaps}). If you specify a name that has a prior definition -other than a keyboard macro, an error message is shown and nothing is -changed. - -@cindex binding keyboard macros -@findex kmacro-bind-to-key -@kindex C-x C-k b - You can also bind the last keyboard macro (in its current form) to a -key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the -key sequence you want to bind. You can bind to any key sequence in -the global keymap, but since most key sequences already have other -bindings, you should select the key sequence carefully. If you try to -bind to a key sequence with an existing binding (in any keymap), this -command asks you for confirmation before replacing the existing binding. - - To avoid problems caused by overriding existing bindings, the key -sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} -through @kbd{C-x C-k Z} are reserved for your own keyboard macro -bindings. In fact, to bind to one of these key sequences, you only -need to type the digit or letter rather than the whole key sequences. -For example, - -@example -C-x C-k b 4 -@end example - -@noindent -will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. - -@findex insert-kbd-macro - Once a macro has a command name, you can save its definition in a file. -Then it can be used in another editing session. First, visit the file -you want to save the definition in. Then use this command: - -@example -M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} -@end example - -@noindent -This inserts some Lisp code that, when executed later, will define the -same macro with the same definition it has now. (You need not -understand Lisp code to do this, because @code{insert-kbd-macro} writes -the Lisp code for you.) Then save the file. You can load the file -later with @code{load-file} (@pxref{Lisp Libraries}). If the file you -save in is your init file @file{~/.emacs} (@pxref{Init File}) then the -macro will be defined each time you run Emacs. - - If you give @code{insert-kbd-macro} a numeric argument, it makes -additional Lisp code to record the keys (if any) that you have bound -to @var{macroname}, so that the macro will be reassigned the same keys -when you load the file. - -@node Edit Keyboard Macro -@section Editing a Keyboard Macro - -@table @kbd -@item C-x C-k C-e -Edit the last defined keyboard macro (@code{kmacro-edit-macro}). -@item C-x C-k e @var{name} @key{RET} -Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). -@item C-x C-k l -Edit the last 300 keystrokes as a keyboard macro -(@code{kmacro-edit-lossage}). -@end table - -@findex kmacro-edit-macro -@kindex C-x C-k C-e -@kindex C-x C-k RET - You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or -@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). This formats the macro -definition in a buffer and enters a specialized major mode for editing -it. Type @kbd{C-h m} once in that buffer to display details of how to -edit the macro. When you are finished editing, type @kbd{C-c C-c}. - -@findex edit-kbd-macro -@kindex C-x C-k e - You can edit a named keyboard macro or a macro bound to a key by typing -@kbd{C-x C-k e} (@code{edit-kbd-macro}). Follow that with the -keyboard input that you would use to invoke the macro---@kbd{C-x e} or -@kbd{M-x @var{name}} or some other key sequence. - -@findex kmacro-edit-lossage -@kindex C-x C-k l - You can edit the last 300 keystrokes as a macro by typing -@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). - -@node Keyboard Macro Step-Edit -@section Stepwise Editing a Keyboard Macro - -@findex kmacro-step-edit-macro -@kindex C-x C-k SPC - You can interactively replay and edit the last keyboard -macro, one command at a time, by typing @kbd{C-x C-k SPC} -(@code{kmacro-step-edit-macro}). Unless you quit the macro using -@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the -macro ring. - - This macro editing feature shows the last macro in the minibuffer -together with the first (or next) command to be executed, and prompts -you for an action. You can enter @kbd{?} to get a summary of your -options. These actions are available: - -@itemize @bullet{} -@item -@kbd{SPC} and @kbd{y} execute the current command, and advance to the -next command in the keyboard macro. -@item -@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. -@item -@kbd{f} skips the current command in this execution of the keyboard -macro, but doesn't delete it from the macro. -@item -@kbd{@key{TAB}} executes the current command, as well as all similar -commands immediately following the current command; for example, @key{TAB} -may be used to insert a sequence of characters (corresponding to a -sequence of @code{self-insert-command} commands). -@item -@kbd{c} continues execution (without further editing) until the end of -the keyboard macro. If execution terminates normally, the edited -macro replaces the original keyboard macro. -@item -@kbd{C-k} skips and deletes the rest of the keyboard macro, -terminates step-editing, and replaces the original keyboard macro -with the edited macro. -@item -@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; -discarding any changes made to the keyboard macro. -@item -@kbd{i KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and inserts them before the current -command in the keyboard macro, without advancing over the current -command. -@item -@kbd{I KEY...} reads one key sequence, executes it, and inserts it -before the current command in the keyboard macro, without advancing -over the current command. -@item -@kbd{r KEY... C-j} reads and executes a series of key sequences (not -including the final @kbd{C-j}), and replaces the current command in -the keyboard macro with them, advancing over the inserted key -sequences. -@item -@kbd{R KEY...} reads one key sequence, executes it, and replaces the -current command in the keyboard macro with that key sequence, -advancing over the inserted key sequence. -@item -@kbd{a KEY... C-j} executes the current command, then reads and -executes a series of key sequences (not including the final -@kbd{C-j}), and inserts them after the current command in the keyboard -macro; it then advances over the current command and the inserted key -sequences. -@item -@kbd{A KEY... C-j} executes the rest of the commands in the keyboard -macro, then reads and executes a series of key sequences (not -including the final @kbd{C-j}), and appends them at the end of the -keyboard macro; it then terminates the step-editing and replaces the -original keyboard macro with the edited macro. -@end itemize - -@ignore - arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c -@end ignore diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi deleted file mode 100644 index 1cd98a0282c..00000000000 --- a/doc/emacs/m-x.texi +++ /dev/null @@ -1,75 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node M-x, Help, Minibuffer, Top -@chapter Running Commands by Name - - Every Emacs command has a name that you can use to run it. For -convenience, many commands also have key bindings. You can run those -commands by typing the keys, or run them by name. Most Emacs commands -have no key bindings, so the only way to run them is by name. -(@xref{Key Bindings}, for how to set up key bindings.) - - By convention, a command name consists of one or more words, -separated by hyphens; for example, @code{auto-fill-mode} or -@code{manual-entry}. Command names mostly use complete English words -to make them easier to remember. - -@kindex M-x - To run a command by name, start with @kbd{M-x}, type the command -name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer -to read the command name. The string @samp{M-x} appears at the -beginning of the minibuffer as a @dfn{prompt} to remind you to enter a -command name to be run. @key{RET} exits the minibuffer and runs the -command. @xref{Minibuffer}, for more information on the minibuffer. - - You can use completion to enter the command name. For example, -to invoke the command @code{forward-char}, you can type - -@example -M-x forward-char @key{RET} -@end example - -@noindent -or - -@example -M-x forw @key{TAB} c @key{RET} -@end example - -@noindent -Note that @code{forward-char} is the same command that you invoke with -the key @kbd{C-f}. The existence of a key binding does not stop you -from running the command by name. - - To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead -of entering the command name. This takes you back to command level. - - To pass a numeric argument to the command you are invoking with -@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The -argument value appears in the prompt while the command name is being -read, and finally @kbd{M-x} passes the argument to that command. - -@vindex suggest-key-bindings - When the command you run with @kbd{M-x} has a key binding, Emacs -mentions this in the echo area after running the command. For -example, if you type @kbd{M-x forward-word}, the message says that you -can run the same command by typing @kbd{M-f}. You can turn off these -messages by setting the variable @code{suggest-key-bindings} to -@code{nil}. - - In this manual, when we speak of running a command by name, we often -omit the @key{RET} that terminates the name. Thus we might say -@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode -@key{RET}}. We mention the @key{RET} only for emphasis, such as when -the command is followed by arguments. - -@findex execute-extended-command - @kbd{M-x} works by running the command -@code{execute-extended-command}, which is responsible for reading the -name of another command and invoking it. - -@ignore - arch-tag: b67bff53-9628-4666-b94e-eda972a7ba56 -@end ignore diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi deleted file mode 100644 index 3fd070a12e7..00000000000 --- a/doc/emacs/macos.texi +++ /dev/null @@ -1,236 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -@c 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mac OS / GNUstep, Microsoft Windows, Antinews, Top -@appendix Emacs and Mac OS / GNUstep -@cindex Mac OS X -@cindex Macintosh -@cindex GNUstep - - This section briefly describes the peculiarities of using Emacs built with -the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X -with native window system support. For Mac OS X, Emacs can be built either -without window system support, with X11, or with the Cocoa interface. This -section only applies to the Cocoa build. Emacs 23 does not support Mac OS -Classic. - - Emacs, when built on Mac OS X, uses the Cocoa application interface. -For historical and technical reasons, Emacs uses the term -@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for -instance, most of the commands and variables described in the -following sections begin with @samp{ns-}, which is short for -@samp{Nextstep}. NeXTstep was an application interface released by -NeXT Inc during the 1980s, of which Cocoa is a direct descendant. -Apart from Cocoa, there is one other NeXTstep-style system: GNUstep, -which is free software. At the moment, Emacs has only incomplete -support for GNUstep (@pxref{GNUstep Support}). - - As of the 23.1 release, Emacs is not as stable on Cocoa as on other -platforms. We hope to improve this in future releases. - -@menu -* Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS. -* Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS. -* Mac / GNUstep Events:: How window system events are handled. -* GNUstep Support:: Details on status of GNUstep support. -@end menu - -@node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep -@section Basic Emacs usage under Mac OS and GNUstep - - By default, the @key{alt} and @key{option} keys are the same as -@key{Meta} when running under Mac OS. The Mac @key{Cmd} key is the -same as @key{Super}, and Emacs provides a set of keybindings using -this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac / -GNUstep Events}). You can change these bindings in the usual way (@pxref{Key -Bindings}). - - The standard Mac / GNUstep font and color panels are accessible via Lisp commands. - To use the color panel, drag from it to an Emacs frame to change the -foreground color of the face at that position (if the @key{shift} key -is held down, it changes the background color instead). To discard the -settings, create a new frame and close the altered one. -@c [unclear if the following holds.] -@c To finalize the settings for either color or font, choose @samp{Save Options} in the @samp{Options} menu. - - @key{S-Mouse-1} (i.e., clicking the left mouse button -while holding down the @key{Shift} key) adjusts the region to the -click position, just like @key{Mouse-3} (@code{mouse-save-then-kill}); -it does not pop up a menu for changing the default face, as -@key{S-Mouse-1} normally does (@pxref{Temporary Face Changes}). This -change makes Emacs behave more like other Mac / GNUstep applications. - - When you open or save files using the menus, or using the -@key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file -dialogs to read file names. However, if you use the regular Emacs key -sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read -file names. - - On GNUstep, in an X-windows environment you need to use @key{Cmd-c} -instead of one of the @key{C-w} or @key{M-w} commands to transfer text -to the X primary selection; otherwise, Emacs will use the -``clipboard'' selection. Likewise, @key{Cmd-y} (instead of @key{C-y}) -yanks from the X primary selection instead of the kill-ring or -clipboard. - - -@subsection Grabbing environment variables - -@c How is this any different to launching from a window manager menu -@c in GNU/Linux? These are sometimes not login shells either. -Many programs which may run under Emacs, like latex or man, depend on the -settings of environment variables. If Emacs is launched from the shell, it -will automatically inherit these environment variables and its subprocesses -will inherit them from it. But if Emacs is launched from the Finder it -is not a descendant of any shell, so its environment variables haven't been -set, which often causes the subprocesses it launches to behave differently than -they would when launched from the shell. - -For the PATH and MANPATH variables, a system-wide method -of setting PATH is recommended on Mac OS X 10.5 and later, using the -@file{/etc/paths} files and the @file{/etc/paths.d} directory. - -@node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep -@section Mac / GNUstep Customization - -Emacs can be customized in several ways in addition to the standard -customization buffers and the Options menu. - - -@subsection Font and Color Panels - -The Font Panel may be accessed with M-x ns-popup-font-panel. It -will set the default font in the frame most recently used or clicked -on. - -@c To make the setting permanent, use @samp{Save Options} in the -@c Options menu, or run @code{menu-bar-options-save}. - -You can bring up a color panel with M-x ns-popup-color-panel. and -drag the color you want over the emacs face you want to change. Normal -dragging will alter the foreground color. Shift dragging will alter the -background color. - -@c To make the changes permanent select the "Save Options" -@c item in the "Options" menu, or run @code{menu-bar-options-save}. - -Useful in this context is the listing of all faces obtained by @key{M-x} -@code{list-faces-display}. - -@subsection Open files by dragging to an Emacs window - -The default behaviour when a user drags files from another application -into an Emacs frame is to insert the contents of all the dragged files -into the current buffer. To remap the @code{ns-drag-file} event to -open the dragged files in the current frame use the following line: - -@lisp -(define-key global-map [ns-drag-file] 'ns-find-file) -@end lisp - - -@node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep -@section Windowing System Events under Mac OS / GNUstep - - Nextstep applications receive a number of special events which have -no X equivalent. These are sent as specially defined ``keys'', which -do not correspond to any sequence of keystrokes. Under Emacs, these -``key'' events can be bound to functions just like ordinary -keystrokes. Here is a list of these events. - -@table @key -@item ns-open-file -@vindex ns-pop-up-frames -This event occurs when another Nextstep application requests that -Emacs open a file. A typical reason for this would be a user -double-clicking a file in the Finder application. By default, Emacs -responds to this event by opening a new frame and visiting the file in -that frame (@code{ns-find-file}). As an exception, if the selected -buffer is the @samp{*scratch*} buffer, Emacs visits the file in the -selected frame. - -You can change how Emacs responds to @key{ns-open-file} by changing -the variable @code{ns-pop-up-frames}. Its default value, -@code{'fresh}, is what we have just described. A value of @code{t} -means to always visit the file in a new frame. A value of @code{nil} -means to always visit the file in an existing frame. - -@item ns-open-temp-file -This event occurs when another application requests that Emacs open a -temporary file. By default, this is handled by just generating a -@code{ns-open-file} event, the results of which are described above. - -You can bind @key{ns-pop-up-frames} and @key{ns-open-temp-file} to -other Lisp functions. When the event is registered, the name of the -file to open is stored in the variable @code{ns-input-file}. - -@item ns-open-file-line -Some applications, such as ProjectBuilder and gdb, request not only a -particular file, but also a particular line or sequence of lines in -the file. Emacs handles this by visiting that file and highlighting -the requested line (@code{ns-open-file-select-line}). - -@item ns-drag-file -This event occurs when a user drags files from another application -into an Emacs frame. The default behavior is to insert the contents -of all the dragged files into the current buffer -(@code{ns-insert-files}). The list of dragged files is stored in the -variable @code{ns-input-file}. - -@item ns-drag-color -This event occurs when a user drags a color from the color well (or -some other source) into an Emacs frame. The default behavior is to -alter the foreground color of the area the color was dragged onto -(@code{ns-set-foreground-at-mouse}). If this event is issued with a -@key{Shift} modifier, Emacs changes the background color instead -(@code{ns-set-background-at-mouse}). The name of the dragged color is -stored in the variable @code{ns-input-color}. - -@item ns-change-font -This event occurs when the user selects a font in a Nextstep font -panel (which can be opened with @kbd{Cmd-t}). The default behavior is -to adjust the font of the selected frame -(@code{ns-respond-to-changefont}). The name and size of the selected -font are stored in the variables @code{ns-input-font} and -@code{ns-input-fontsize}, respectively. - -@item ns-power-off -This event occurs when the user logs out and Emacs is still running, or when -`Quit Emacs' is chosen from the application menu. -The default behavior is to save all file-visiting buffers. -@end table - - Emacs also allows users to make use of Nextstep services, via a set -of commands whose names begin with @samp{ns-service-} and end with the -name of the service. Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} to -see a list of these commands. These functions either operate on -marked text (replacing it with the result) or take a string argument -and return the result as a string. You can also use the Lisp function -@code{ns-perform-service} to pass arbitrary strings to arbitrary -services and receive the results back. Note that you may need to -restart Emacs to access newly-available services. - - -@node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep -@section GNUstep Support - -Emacs can be built and run under GNUstep, however there are still some -issues to be addressed. Interested developers should contact -@email{emacs-devel@@gnu.org}. - -@c Presumably no longer relevant since CANNOT_DUMP removed 2009-05-06: -@ignore -In particular, it may be necessary to run @samp{make bootstrap} with a -plain X configuration, then @samp{make clean} and @samp{./configure ---with-ns} followed by @samp{make install}. - -Currently CANNOT_DUMP is automatically enabled in GNUstep configurations, -because the unex file(s) for GNUstep, mainly @samp{unexelf.c}, have not been -updated yet with the ``zone'' code in and related to @samp{unexmacosx.c}. -@end ignore - - -@ignore - arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 -@end ignore diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi deleted file mode 100644 index 114e2d0c655..00000000000 --- a/doc/emacs/maintaining.texi +++ /dev/null @@ -1,2226 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Maintaining, Abbrevs, Building, Top -@chapter Maintaining Large Programs - - This chapter describes Emacs features for maintaining large -programs. - -@menu -* Version Control:: Using version control systems. -* Change Log:: Maintaining a change history for your program. -* Tags:: Go directly to any function in your program in one - command. Tags remembers which file it is in. -@ifnottex -* Emerge:: A convenient way of merging two versions of a program. -@end ifnottex -@end menu - -@node Version Control -@section Version Control -@cindex version control - - A @dfn{version control system} is a package that can record multiple -versions of a source file, storing information such as the creation -time of each version, who created it, and a description of what was -changed in that version. - - The Emacs version control interface is called VC. Its commands work -with several different version control systems; currently, it supports -GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and -Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS, -and Bazaar. - - VC is enabled automatically whenever you visit a file that is -governed by a version control system. To disable VC entirely, set the -customizable variable @code{vc-handled-backends} to @code{nil} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex - -@menu -* Introduction to VC:: How version control works in general. -* VC Mode Line:: How the mode line shows version control status. -* Basic VC Editing:: How to edit a file under version control. -* Old Revisions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. -* VC Directory Mode:: Listing files managed by version control. -* Branches:: Multiple lines of development. -@ifnottex -* Remote Repositories:: Efficient access to remote CVS servers. -* Revision Tags:: Symbolic names for revisions. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end ifnottex -@end menu - -@node Introduction to VC -@subsection Introduction to Version Control - - VC allows you to use a version control system from within Emacs, -integrating the version control operations smoothly with editing. -Though VC cannot completely bridge the gaps between version control -systems with widely differing capabilities, it does provide a uniform -interface to many version control operations. Regardless of which -version control system is in use, you will be able to do basic -operations in much the same way. - - This section provides a general overview of version control, and -describes the version control systems that VC supports. You can skip -this section if you are already familiar with the version control system -you want to use. - -@menu -* Why Version Control?:: Understanding the problems it addresses. -* Version Control Systems:: Supported version control back-end systems. -* VCS Concepts:: Words and concepts related to version control. -* Types of Log File:: The VCS log in contrast to the ChangeLog. -@end menu - -@node Why Version Control? -@subsubsection Understanding the problems it addresses - - Version control systems provide you with three important -capabilities: - -@itemize @bullet -@item -@dfn{Reversibility}: the ability to back up to a previous state if you -discover that some modification you did was a mistake or a bad idea. - -@item -@dfn{Concurrency}: the ability to have many people modifying the same -collection of files knowing that conflicting modifications can be -detected and resolved. - -@item -@dfn{History}: the ability to attach historical data to your data, -such as explanatory comments about the intention behind each change to -it. Even for a programmer working solo, change histories are an -important aid to memory; for a multi-person project, they are a -vitally important form of communication among developers. -@end itemize - -@node Version Control Systems -@subsubsection Supported Version Control Systems - -@cindex back end (version control) - VC currently works with many different version control systems or -@dfn{back ends}: - -@itemize @bullet - -@cindex SCCS -@item -SCCS was the first version control system ever built, and was long ago -superseded by more advanced ones. VC compensates for certain features -missing in SCCS (e.g., tag names for releases) by implementing them -itself. Other VC features, such as multiple branches, are simply -unavailable. Since SCCS is non-free, we recommend avoiding it. - -@cindex CSSC -@item -CSSC is a free replacement for SCCS. You should use CSSC only if, for -some reason, you cannot use a more recent and better-designed version -control system. - -@cindex RCS -@item -RCS is the free version control system around which VC was initially -built. Almost everything you can do with RCS can be done through VC. -However, you cannot use RCS over the network, and it only works at the -level of individual files rather than projects. - -@cindex CVS -@item -CVS is the free version control system that was, until recently (circa -2008), used by the majority of free software projects. Nowadays, it -is slowly being superseded by newer systems. CVS allows concurrent -multi-user development either locally or over the network. It lacks -support for atomic commits or file moving/renaming. VC supports all -basic editing operations under CVS. For some less common tasks, you -still need to call CVS from the command line. Note also that before -using CVS you must set up a repository, which is a subject too complex -to treat here. - -@cindex SVN -@cindex Subversion -@item -Subversion (SVN) is a free version control system designed to be -similar to CVS but without its problems. It supports atomic commits -of filesets, and versioning of directories, symbolic links, meta-data, -renames, copies, and deletes. - -@cindex GNU Arch -@cindex Arch -@item -GNU Arch is a version control system designed for distributed work. -It differs in many ways from older systems like CVS and RCS. It -provides different methods for interoperating between users, support -for offline operations, and good branching and merging features. It -also supports atomic commits of filesets and file moving/renaming. VC -does not support all operations provided by GNU Arch, so you must -sometimes invoke it from the command line. - -@cindex git -@item -Git is a distributed version control system invented by Linus Torvalds to support -development of Linux (his kernel). It supports atomic commits of filesets and -file moving/renaming. One significant feature of git is that it -largely abolishes the notion of a single centralized repository; -instead, each working copy of a git project is its own repository and -coordination is done through repository-sync operations. VC supports -most git operations, with the exception of news merges and repository -syncing; these must be done from the command line. - -@cindex hg -@cindex Mercurial -@item -Mercurial (hg) is a distributed version control system broadly -resembling GNU Arch and git, with atomic fileset commits and file -moving/renaming. Like git, it is fully decentralized. VC supports -most Mercurial commands, with the exception of repository sync -operations; this needs to be done from the command line. - -@cindex bzr -@cindex Bazaar -@item -Bazaar (bzr) is a distributed version control system that supports both -repository-based and distributed versioning, with atomic fileset -commits and file moving/renaming. VC supports most basic editing -operations under Bazaar. -@end itemize - - Previous versions of VC supported a version control system known as -Meta-CVS. This support has been dropped because of limited interest -from users and developers. - -@node VCS Concepts -@subsubsection Concepts of Version Control - -@cindex repository -@cindex registered file - When a file is under version control, we say that it is -@dfn{registered} in the version control system. The system has a -@dfn{repository} which stores both the file's present state and its -change history---enough to reconstruct the current version or any -earlier version. The repository also contains other information, such -as @dfn{log entries} that describe the changes made to each file. - -@cindex work file -@cindex checking out files - A file @dfn{checked out} of a repository is called the @dfn{work -file}. You edit the work file and make changes in it, as you would -with an ordinary file. After you are done with a set of changes, you -@dfn{check in} or @dfn{commit} the file; this records the changes in -the repository, along with a log entry for those changes. - -@cindex revision -@cindex revision ID - A copy of a file stored in a repository is called a @dfn{revision}. -The history of a file is a sequence of revisions. Each revisions is -named by a @dfn{revision ID}. The format of the revision ID depends -on the version control system; in the simplest case, it is just an -integer. - - To go beyond these basic concepts, you will need to understand three -aspects in which version control systems differ. -They can be locking-based or merging-based; they can be file-based or -changeset-based; and they can be centralized or decentralized. VC -handles all these modes of operation, but it cannot hide the differences. - -@cindex locking versus merging - A version control system typically has some mechanism to coordinate -between users who want to change the same file. There are two ways to -do this: merging and locking. - - In a version control system that uses merging, each user may check -out and modify a work file at any time. The system lets you -@dfn{merge} your work file, which may contain changes that have not -been checked in, with the latest changes that others have checked into -the repository. - - Older version control systems use a @dfn{locking} scheme instead. -Here, work files are normally read-only. To edit a file, you ask the -version control system to make it writable for you by @dfn{locking} -it; only one user can lock a given file at any given time. This -procedure is analogous to, but different from, the locking that Emacs -uses to detect simultaneous editing of ordinary files -(@pxref{Interlocking}). When you check in your changes, that unlocks -the file, and the work file becomes read-only again. Other users may -then lock the file to make their own changes. - - Both locking and merging systems can have problems when multiple -users try to modify the same file at the same time. Locking systems -have @dfn{lock conflicts}; a user may try to check a file out and be -unable to because it is locked. In merging systems, @dfn{merge -conflicts} happen when you check in a change to a file that conflicts -with a change checked in by someone else after your checkout. Both -kinds of conflict have to be resolved by human judgment and -communication. Experience has shown that merging is superior to -locking, both in convenience to developers and in minimizing the -number and severity of conflicts that actually occur. - - SCCS always uses locking. RCS is lock-based by default but can be -told to operate in a merging style. CVS and Subversion are -merge-based by default but can be told to operate in a locking mode. -Distributed version control systems, such as GNU Arch, git, and -Mercurial, are exclusively merging-based. - - VC mode supports both locking and merging version control. The -terms ``checkin'' and ``checkout'' come from locking-based version -control systems; newer version control systems have slightly different -operations usually called ``commit'' and ``update'', but VC hides the -differences between them as much as possible. - -@cindex files versus changesets. - On SCCS, RCS, CVS, and other early version control systems, version -control operations are @dfn{file-based}: each file has its own comment -and revision history separate from that of all other files in the -system. Later systems, beginning with Subversion, are -@dfn{changeset-based}: a checkin may include changes to several files, -and the entire set of changes is treated as a unit by the system. Any -comment associated with the change does not belong to a single file, -but to the changeset itself. - - Changeset-based version control is more flexible and powerful than -file-based version control; usually, when a change to multiple files -has to be reversed, it's good to be able to easily identify and remove -all of it. - -@cindex centralized vs. decentralized version control - Early version control systems were designed around a -@dfn{centralized} model in which each project has only one repository -used by all developers. SCCS, RCS, CVS, and Subversion share this -kind of model. One of its drawbacks is that the repository is a choke -point for reliability and efficiency. - - GNU Arch pioneered the concept of @dfn{decentralized} version -control, later implemented in git, Mercurial, and Bazaar. A project -may have several different repositories, and these systems support a -sort of super-merge between repositories that tries to reconcile their -change histories. At the limit, each developer has his/her own -repository, and repository merges replace checkin/commit operations. - - VC's job is to help you manage the traffic between your personal -workfiles and a repository. Whether that repository is a single -master or one of a network of peer repositories is not something VC -has to care about. Thus, the difference between a centralized and a -decentralized version control system is invisible to VC mode. - -@node Types of Log File -@subsubsection Types of Log File -@cindex types of log file -@cindex log File, types of -@cindex version control log - - Projects that use a version control system can have two types of log -for changes. One is the log maintained by the version control system: -each time you check in a change, you fill out a @dfn{log entry} for -the change (@pxref{Log Buffer}). This is called the @dfn{version -control log}. - - The other kind of log is the file @file{ChangeLog} (@pxref{Change -Log}). It provides a chronological record of all changes to a large -portion of a program---typically one directory and its subdirectories. -A small program would use one @file{ChangeLog} file; a large program -may have a @file{ChangeLog} file in each major directory. -@xref{Change Log}. Programmers have used change logs since long -before version control systems. - - Changeset-based version systems typically maintain a changeset-based -modification log for the entire system, which makes change log files -somewhat redundant. One advantage that they retain is that it is -sometimes useful to be able to view the transaction history of a -single directory separately from those of other directories. - - A project maintained with version control can use just the version -control log, or it can use both kinds of logs. It can handle some -files one way and some files the other way. Each project has its -policy, which you should follow. - - When the policy is to use both, you typically want to write an entry -for each change just once, then put it into both logs. You can write -the entry in @file{ChangeLog}, then copy it to the log buffer with -@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or -you can write the entry in the log buffer while checking in the -change, and later use the @kbd{C-x v a} command to copy it to -@file{ChangeLog} -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - -@node VC Mode Line -@subsection Version Control and the Mode Line - - When you visit a file that is under version control, Emacs indicates -this on the mode line. For example, @samp{RCS-1.3} says that RCS is -used for that file, and the current version is 1.3. - - The character between the back-end name and the revision ID -indicates the version control status of the file. @samp{-} means that -the work file is not locked (if locking is in use), or not modified (if -locking is not in use). @samp{:} indicates that the file is locked, or -that it is modified. If the file is locked by some other user (for -instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. - - On a graphical display, you can move the mouse over this mode line -indicator to pop up a ``tool-tip'', which displays a more verbose -description of the version control status. Pressing @kbd{Mouse-1} -over the indicator pops up a menu of VC commands. This menu is -identical to the @samp{Tools / Version Control} menu item. - -@vindex auto-revert-check-vc-info - When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is -under version control, it updates the version control information in -the mode line. However, Auto Revert mode may not properly update this -information if the version control status changes without changes to -the work file, from outside the current Emacs session. If you set -@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates -the version control status information every -@code{auto-revert-interval} seconds, even if the work file itself is -unchanged. The resulting CPU usage depends on the version control -system, but is usually not excessive. - -@node Basic VC Editing -@subsection Basic Editing under Version Control - -@cindex filesets, VC - Most VC commands operate on @dfn{VC filesets}. A VC fileset is a -collection of one or more files that a VC operation acts on. When you -type VC commands in a buffer visiting a version-controlled file, the -VC fileset is simply that one file. When you type them in a VC -Directory buffer, and some files in it are marked, the VC fileset -consists of the marked files (@pxref{VC Directory Mode}). - - The principal VC command is an all-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), that performs either locking, merging or a -check-in (depending on the situation) on the current VC fileset. You -can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory -buffer. - -@table @kbd -@itemx C-x v v -Perform the appropriate next version control operation on the VC fileset. -@end table - -@findex vc-next-action -@kindex C-x v v - The precise action of @kbd{C-x v v} depends on the state of the VC -fileset, and whether the version control system uses locking or -merging. This is described in detail in the subsequent sections. - - VC filesets are the way that VC mode bridges the gap between -file-based and changeset-based version control systems. They are, -essentially, a way to pass multiple file arguments as a group to -version control commands. For example, on Subversion, a checkin with -a multi-file VC fileset becomes a joint commit, as though you had -typed @command{svn commit} with those file arguments at the shell -command line. All files in a VC fileset must be under the same -version control system; if they are not, Emacs signals an error when -you attempt to execute a command on the fileset. - - Support for VC filesets and changeset-based version control systems -is the main improvement to VC in Emacs 23. When you mark multi-file -VC in a VC Directory buffer, VC operations treat them as a VC fileset, -and operate on them all at once if the version control system is -changeset-based. @xref{VC Directory Mode}. - - VC filesets are distinct from the ``named filesets'' used for -viewing and visiting files in functional groups (@pxref{Filesets}). -Unlike named filesets, VC filesets are not named and don't persist -across sessions. - -@menu -* VC With A Merging VCS:: Without locking: default mode for CVS. -* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. -* Advanced C-x v v:: Advanced features available with a prefix argument. -* Log Buffer:: Features available in log entry buffers. -@end menu - -@node VC With A Merging VCS -@subsubsection Basic Version Control with Merging - - When your version control system is merging-based (the default for -CVS and all newer version control systems), work files are always -writable; you need not do anything special to begin editing a file. -The status indicator on the mode line is @samp{-} if the file is -unmodified; it flips to @samp{:} as soon as you save any changes -(@pxref{VC Mode Line}). - - Here is what @kbd{C-x v v} does when using a merging-based system: - -@itemize @bullet -@item -If the work file is the same as in the repository, it does nothing. - -@item -If you have not changed the work file, but some other user has checked -in changes to the repository, @kbd{C-x v v} merges those changes into -the work file. - -@item -If you have made modifications to the work file, @kbd{C-x v v} -attempts to check in your changes. To do this, Emacs first reads the -log entry for the new revision (@pxref{Log Buffer}). If some other -user has checked in changes to the repository since you last checked -it out, the checkin fails. In that case, type @kbd{C-x v v} again to -merge those changes into your own work file; this puts the work file -into a ``conflicted'' state. Type @kbd{C-x v v} to clear the -``conflicted'' state; VC then regards the file as up-to-date and -modified, and you can try to check it in again. - -To pick up any recent changes from the repository @emph{without} -trying to commit your own changes, type @kbd{C-x v m @key{RET}}. -@xref{Merging}. -@end itemize - - These rules also apply when you use RCS in its ``non-locking'' mode, -except that changes will not be automatically merged from the -repository. Nothing informs you if another user has checked in -changes in the same file since you began editing it; when you check in -your revision, his changes are removed (however, they remain in the -repository and are thus not irrevocably lost). Therefore, you must -verify that the current revision is unchanged before checking in your -changes. In addition, locking is possible with RCS even in this mode: -@kbd{C-x v v} with an unmodified file locks the file, just as it does -with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). - -@node VC With A Locking VCS -@subsubsection Basic Version Control with Locking - - Under a locking-based version control system (such as SCCS, and RCS -in its default mode), @kbd{C-x v v} does the following: - - @itemize @bullet -@item -If the file is not locked, @kbd{C-x v v} locks it, and makes it -writable so that you can change it. - -@item -If the file is locked by you, and contains changes, @kbd{C-x v v} -checks in the changes. In order to do this, it first reads the log -entry for the new revision. @xref{Log Buffer}. - -@item -If the file is locked by you, but you have not changed it since you -locked it, @kbd{C-x v v} releases the lock and makes the file -read-only again. - -@item -If the file is locked by some other user, @kbd{C-x v v} asks you whether -you want to ``steal the lock'' from that user. If you say yes, the file -becomes locked by you, but a message is sent to the person who had -formerly locked the file, to inform him of what has happened. -@end itemize - - These rules also apply when you use CVS in locking mode, except -that there is no such thing as stealing a lock. - -@node Advanced C-x v v -@subsubsection Advanced Control in @kbd{C-x v v} - -@cindex revision ID to check in/out - When you give a prefix argument to @code{vc-next-action} (@kbd{C-u -C-x v v}), it still performs the next logical version control -operation, but accepts additional arguments to specify precisely how -to do the operation. - -@itemize @bullet -@item -If the file is modified (or locked), you can specify the revision ID -to use for the new version that you check in. This is one way -to create a new branch (@pxref{Branches}). - -@item -If the file is not modified (and unlocked), you can specify the -revision to select; this lets you start working from an older -revision, or on another branch. If you do not enter any revision, -that takes you to the highest (``head'') revision on the current -branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to -get the latest version of a file from the repository. - -@item -@cindex specific version control system -Instead of the revision ID, you can also specify the name of a -version control system. This is useful when one file is being managed -with two version control systems at the same time -@iftex -(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs -Features}). -@end iftex -@ifnottex -(@pxref{Local Version Control}). -@end ifnottex - -@end itemize - -@node Log Buffer -@subsubsection Features of the Log Entry Buffer - - When you check in changes, Emacs pops up a buffer called -@samp{*VC-Log*} for you to enter a log entry. - - After you have finished editing the log message, type @kbd{C-c C-c} -to exit the buffer and commit the change. - -@findex log-edit-show-files -@findex log-edit-show-diff - In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f} -(@code{log-edit-show-files}) displays a list of files in the VC -fileset you are committing. If you called @kbd{C-x v v} directly from -a work file, the VC fileset consists of that single file, so this -command is not very useful. If you called @kbd{C-x v v} from a VC -directory buffer, the VC fileset may consist of multiple files -(@pxref{VC Directory Mode}). - -@findex log-edit-insert-changelog - Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of -the changes you have made (i.e., the differences between the work file -and the repository revision from which you started editing the file). -The diff is displayed in a special buffer in another window. -@xref{Comparing Files}. - - If you have written an entry in the @file{ChangeLog} (@pxref{Change -Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull -it into the @samp{*VC-Log*} buffer. If the topmost item in the -@file{ChangeLog} was made under your user name on the current date, -this command searches that item for entries that match the file(s) to -be committed; if found, these entries are inserted. -@iftex -@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, -@end iftex -@ifnottex -@xref{Change Logs and VC}, -@end ifnottex -for the opposite way of working---generating ChangeLog entries from -the revision control log. - - To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that -buffer. You can switch buffers and do other editing. As long as you -don't try to check in another file, the entry you were editing remains -in the @samp{*VC-Log*} buffer, and you can go back to that buffer at -any time to complete the check-in. - - If you change several source files for the same reason, it is often -convenient to specify the same log entry for many of the files. (This -is the normal way to do things on a changeset-oriented system, where -comments are attached to changesets rather than the history of -individual files.) The most convenient way to do this is to mark all -the files in VC Directory Mode and check in from there; the log buffer -will carry the fileset information with it and do a group commit when -you type @kbd{C-c C-c}. - - You can also browse the history of previous log entries to duplicate -a checkin comment. This can be useful when you want several files to -have checkin comments that vary only slightly from each other. The -commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this -work just like the minibuffer history commands (except that these -versions are used outside the minibuffer). - -@vindex vc-log-mode-hook - Each time you check in a change, the log entry buffer is put into VC -Log Edit mode, which involves running two hooks: @code{text-mode-hook} -and @code{vc-log-mode-hook}. @xref{Hooks}. - -@node Old Revisions -@subsection Examining And Comparing Old Revisions - - One of the convenient features of version control is the ability -to examine any revision of a file, or compare two revisions. - -@table @kbd -@item C-x v ~ @var{revision} @key{RET} -Examine revision @var{revision} of the visited file, in a buffer of its -own. - -@item C-x v = -Compare the buffer contents associated with the current -fileset with the working revision(s) from which you started editing. - -@item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} -Compare the specified two repository revisions of the current fileset. - -@item C-x v g -Display an annotated version of the file: for each line, show the -latest revision in which it was modified. -@end table - -@findex vc-revision-other-window -@kindex C-x v ~ - To examine an old revision, visit the work file and type @kbd{C-x v -~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, -@var{revision} is either the desired revision ID (@pxref{VCS -Concepts}), or the name of a tag or branch -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Tags}). -@end ifnottex -This command puts the text of the old revision in a file named -@file{@var{filename}.~@var{revision}~}, and visits it in its own -buffer in a separate window. - -@findex vc-diff -@kindex C-x v = - @kbd{C-x v =} (@code{vc-diff}) compares the current buffer contents -of each file in the current VC fileset (saving them if necessary) with -the repository revision from which you started editing. Note that the -latter may or may not be the latest revision of the file(s). The diff -is displayed in a special buffer in another window. @xref{Comparing -Files}. - -@findex vc-diff -@kindex C-u C-x v = - To compare two arbitrary revisions of the current VC fileset, call -@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This -prompts for two revision IDs, using the minibuffer, and displays the -diff in a special buffer in another window. Instead of providing a -revision ID, you can give an empty input, which specifies the current -contents of the work file; or a tag or branch name -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Tags}). -@end ifnottex -If your version control system is file-based (e.g. CVS) rather than -changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a -revision ID for a multi-file fileset (as opposed to a symbolic tag -name) is unlikely to return diffs that are connected in any meaningful -way. - - If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that -is neither visiting a version-controlled file nor a VC directory -buffer, these commands generate a diff of all registered files in the -current directory and its subdirectories. - -@vindex vc-diff-switches -@vindex vc-rcs-diff-switches - @kbd{C-x v =} works by running a variant of the @code{diff} utility -designed to work with the version control system in use. The options -to pass to the @code{diff} command are taken from the first non-@code{nil} -value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, -and @code{diff-switches} (@pxref{Comparing Files}), in that order. -Since @code{nil} means to check the next variable in the sequence, -either of the first two may use the value @code{t} to mean no switches at all. -Most of the @samp{vc@dots{}diff-switches} variables default to -@code{nil}, but some default to @code{t}. These are for those version -control systems (e.g. SVN) whose @code{diff} implementations do not -accept common options (e.g. @samp{-c}) likely to be in -@code{diff-switches}. - - The buffer produced by @kbd{C-x v =} supports the commands of -Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and -@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always -find the corresponding locations in the current work file. (Older -revisions are not, in general, present as files on your disk.) - -@findex vc-annotate -@kindex C-x v g - For some back ends, you can display the file @dfn{annotated} with -per-line revision information, by typing @kbd{C-x v g} -(@code{vc-annotate}). This creates a new buffer (the ``annotate -buffer'') displaying the file's text, with each part colored to show -how old it is. Text colored red is new, blue means old, and -intermediate colors indicate intermediate ages. By default, the color -is scaled over the full range of ages, such that the oldest changes -are blue, and the newest changes are red. - - When you give a prefix argument to this command, Emacs reads two -arguments using the minibuffer: the ID of which revision to display and -annotate (instead of the current file contents), and the time span in -days the color range should cover. - - From the annotate buffer, these and other color scaling options are -available from the @samp{VC-Annotate} menu. In this buffer, you can -also use the following keys to browse the annotations of past revisions, -view diffs, or view log entries: - -@table @kbd -@item p -Annotate the previous revision, that is to say, the revision before -the one currently annotated. A numeric prefix argument is a repeat -count, so @kbd{C-u 10 p} would take you back 10 revisions. - -@item n -Annotate the next revision---the one after the revision currently -annotated. A numeric prefix argument is a repeat count. - -@item j -Annotate the revision indicated by the current line. - -@item a -Annotate the revision before the one indicated by the current line. -This is useful to see the state the file was in before the change on -the current line was made. - -@item f -Show in a buffer the file revision indicated by the current line. - -@item d -Display the diff between the current line's revision and the previous -revision. This is useful to see what the current line's revision -actually changed in the file. - -@item D -Display the diff between the current line's revision and the previous -revision for all files in the changeset (for VC systems that support -changesets). This is useful to see what the current line's revision -actually changed in the tree. - -@item l -Show the log of the current line's revision. This is useful to see -the author's description of the changes in the revision on the current -line. - -@item w -Annotate the working revision--the one you are editing. If you used -@kbd{p} and @kbd{n} to browse to other revisions, use this key to -return to your working revision. - -@item v -Toggle the annotation visibility. This is useful for looking just at -the file contents without distraction from the annotations. -@end table - -@node Secondary VC Commands -@subsection The Secondary Commands of VC - - This section explains the secondary commands of VC. - -@menu -* Registering:: Putting a file under version control. -* VC Status:: Viewing the VC status of files. -* VC Undo:: Canceling changes before or after check-in. -@end menu - -@node Registering -@subsubsection Registering a File for Version Control - -@kindex C-x v i -@findex vc-register - You can put any file under version control by simply visiting it, and -then typing @w{@kbd{C-x v i}} (@code{vc-register}). - -@table @kbd -@item C-x v i -Register the visited file for version control. -@end table - - To register the file, Emacs must choose which version control system -to use for it. If the file's directory already contains files -registered in a version control system, Emacs uses that system. If -there is more than one system in use for a directory, Emacs uses the -one that appears first in @code{vc-handled-backends} -@iftex -(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Customizing VC}). -@end ifnottex -On the other hand, if there are no files already registered, Emacs uses -the first system from @code{vc-handled-backends} that could register -the file (for example, you cannot register a file under CVS if its -directory is not already part of a CVS tree); with the default value -of @code{vc-handled-backends}, this means that Emacs uses RCS in this -situation. - - If locking is in use, @kbd{C-x v i} leaves the file unlocked and -read-only. Type @kbd{C-x v v} if you wish to start editing it. After -registering a file with CVS, you must subsequently commit the initial -revision by typing @kbd{C-x v v}. Until you do that, the revision ID -appears as @samp{@@@@} in the mode line. - -@vindex vc-default-init-revision -@cindex initial revision ID to register - The default initial revision ID for a newly registered file -varies by what VCS you are using; normally it will be 1.1 on VCSes -that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. -You can specify a different default by setting the variable -@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a -numeric argument; then it reads the initial revision ID for this -particular file using the minibuffer. - -@vindex vc-initial-comment - If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an -initial comment to describe the purpose of this source file. Reading -the initial comment works like reading a log entry (@pxref{Log Buffer}). - -@node VC Status -@subsubsection VC Status Commands - -@table @kbd -@item C-x v l -Display revision control state and change history. -@end table - -@kindex C-x v l -@findex vc-print-log - To view the detailed revision control status and history of a file, -type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special -buffer named @samp{*vc-change-log*}, in a new window, that displays -the history of changes to the current file, including the text of the -log entries. The point is centered at the revision of the file that -is currently being visited. - - In the @samp{*vc-change-log*} buffer, you can use the following keys -to move between the logs of revisions and of files, to view past -revisions, to modify change comments, to view annotations and to view -diffs: - -@table @kbd -@item p -Move to the previous revision-item in the buffer. (Revision entries in the log -buffer are usually in reverse-chronological order, so the previous -revision-item usually corresponds to a newer revision.) A numeric -prefix argument is a repeat count. - -@item n -Move to the next revision-item (which most often corresponds to the -previous revision of the file). A numeric prefix argument is a repeat -count. - -@item P -Move to the log of the previous file, when the logs of multiple files -are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just -move to the beginning of the log. A numeric prefix argument is a -repeat count, so @kbd{C-u 10 P} would move backward 10 files. - -@item N -Move to the log of the next file, when the logs of multiple files are -in the log buffer (@pxref{VC Directory Mode}). It also takes a -numeric prefix argument as a repeat count. - -@item a -Annotate the revision indicated by the current line. - -@item e -Modify the change comment displayed at point. Note that not all VC -systems support modifying change comments. - -@item f -Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's ID (@pxref{Old Revisions}). - -@item d -Display the diff (@pxref{Comparing Files}) between the revision -indicated at the current line and the next earlier revision. This is -useful to see what actually changed in the file when the revision -indicated on the current line was committed. - -@item D -Display the changeset diff (@pxref{Comparing Files}) between the -revision indicated at the current line and the next earlier revision. -This is useful to see all the changes to all files that the revision -indicated on the current line did when it was committed. -@end table - -@node VC Undo -@subsubsection Undoing Version Control Actions - -@table @kbd -@item C-x v u -Revert the buffer and the file to the working revision from which you started -editing the file. - -@item C-x v c -Remove the last-entered change from the master for the visited file. -This undoes your last check-in. -@end table - -@kindex C-x v u -@findex vc-revert-buffer - If you want to discard your current set of changes and revert to the -working revision from which you started editing the file, use @kbd{C-x -v u} (@code{vc-revert-buffer}). If the version control system is -locking-based, this leaves the file unlocked, and you must lock it -again before making new changes. @kbd{C-x v u} requires confirmation, -unless it sees that you haven't made any changes with respect to the -master copy of the working revision. - - @kbd{C-x v u} is also the command to unlock a file if you lock it and -then decide not to change it. - -@kindex C-x v c -@findex vc-rollback - To cancel a change that you already checked in, use @kbd{C-x v c} -(@code{vc-rollback}). This command discards all record of the most -recent checked-in revision, but only if your work file corresponds to -that revision---you cannot use @kbd{C-x v c} to cancel a revision that -is not the latest on its branch. Note that many version control -systems do not support rollback at all; this command is something of a -historical relic. - -@node VC Directory Mode -@subsection VC Directory Mode - -@kindex C-x v d -@findex vc-dir - When you are working on a large program, it is often useful to find -out which files have changed within an entire directory tree, or to -view the status of all files under version control at once, and to -perform version control operations on collections of files. You can -use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory -listing that includes only files relevant for version control. This -creates a @dfn{VC Directory buffer} and displays it in a separate -window. - -@cindex PCL-CVS -@pindex cvs -@cindex CVS directory mode - The VC Directory buffer works with all the version control systems -that VC supports. For CVS, Emacs also offers a more powerful facility -called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The -Emacs Front-End to CVS}. - -@menu -* Buffer: VC Directory Buffer. What the buffer looks like and means. -* Commands: VC Directory Commands. Commands to use in a VC directory buffer. -@end menu - -@node VC Directory Buffer -@subsubsection The VC Directory Buffer - - The VC Directory buffer contains a list of version-controlled files -in the current directory and its subdirectories. Files which are -up-to-date (have no local differences from the repository copy) are -usually hidden; if all files in a subdirectory are up-to-date, the -subdirectory is hidden as well. There is an exception to this rule: -if VC mode detects that a file has changed to an up-to-date state -since you last looked at it, that file and its state are shown. - - If a directory uses more that one version control system, you can -select which system to use for the @code{vc-dir} command by invoking -@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. - - The line for an individual file shows the version control state of -the file. Under RCS and SCCS, the name of the user locking the file -is shown; under CVS, an abbreviated version of the @samp{cvs status} -output is used. Here is an example using CVS: - -@smallexample -@group - ./ - modified file1.c - needs-update file2.c - needs-merge file3.c -@end group -@end smallexample - -@noindent -In this example, @samp{file1.c} is modified with respect to the -repository, and @samp{file2.c} is not. @samp{file3.c} is modified, -but other changes have also been checked in to the repository---you -need to merge them with the work file before you can check it in. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local - In the above, if the repository were on a remote machine, VC only -contacts it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is @code{nil} -@iftex -(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{CVS Options}). -@end ifnottex -This is because access to the repository may be slow, or you may be -working offline and not have access to the repository at all. As a -consequence, VC would not be able to tell you that @samp{file3.c} is -in the ``merge'' state; you would learn that only when you try to -check-in your modified copy of the file, or use a command such as -@kbd{C-x v m}. - - In practice, this is not a problem because CVS handles this case -consistently whenever it arises. In VC, you'll simply get prompted to -merge the remote changes into your work file first. The benefits of -less network communication usually outweigh the disadvantage of not -seeing remote changes immediately. - -@vindex vc-directory-exclusion-list - When a VC directory displays subdirectories it omits some that -should never contain any files under version control. By default, -this includes Version Control subdirectories such as @samp{RCS} and -@samp{CVS}; you can customize this by setting the variable -@code{vc-directory-exclusion-list}. - -@node VC Directory Commands -@subsubsection VC Directory Commands - - VC Directory mode has a full set of navigation and marking commands -for picking out filesets. Some of these are also available in a -context menu invoked by the @kbd{mouse-2} button. - - Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also -move vertically as in other list-browsing modes. @key{SPC} and -@key{TAB} behave like down-arrow, and @key{BackTab} behaves like -up-arrow. - - Both @kbd{C-m} and @kbd{f} visit the file on the current -line. @kbd{o} visits that file in another window. @kbd{q} dismisses -the directory buffer. - - @kbd{x} hides up-to-date files. - - @kbd{m} marks the file or directory on the current line. If the -region is active, @kbd{m} marks all the files in the region. There -are some restrictions when marking: a file cannot be marked if any of -its parent directories are marked, and a directory cannot be marked if -any files in it or in its child directories are marked. - - @kbd{M} marks all the files with the same VC state as the current -file if the cursor is on a file. If the cursor is on a directory, it -marks all child files. With a prefix argument: marks all files and -directories. - - @kbd{u} unmarks the file or directory on the current line. If the -region is active, it unmarks all the files in the region. - - @kbd{U} marks all the files with the same VC state as the current file -if the cursor is on a file. If the cursor is on a directory, it -unmarks all child files. With a prefix argument: unmarks all marked -files and directories. - - It is possible to do search, search and replace, incremental search, -and incremental regexp search on multiple files. These commands will -work on all the marked files or the current file if nothing is marked. -If a directory is marked, the files in that directory shown in the VC -directory buffer will be used. - - @kbd{S} searches the marked files. - - @kbd{Q} does a query replace on the marked files. - - @kbd{M-s a C-s} does an incremental search on the marked files. - - @kbd{M-s a C-M-s} does an incremental search on the marked files. - - Commands are also accessible from the VC-dir menu. Note that some VC -backends use the VC-dir menu to make available extra backend specific -commands. - - Normal VC commands with the @kbd{C-x v} prefix work in VC directory -buffers. Some single-key shortcuts are available as well; @kbd{=}, -@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with -@kbd{C-x v}. - - The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the -marked files, so that you can check in several files at once. -If the underlying VC supports atomic commits of multiple-file -changesets, @kbd{C-x v v} with a selected set of modified but not -committed files will commit all of them at once as a single changeset. - - When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple -files, all of those files must be either in the same state or in -compatible states (added, modified and removed states are considered -compatible). Otherwise it signals an error. This differs from the -behavior of older versions of VC, which did not have fileset -operations and simply did @code{vc-next-action} on each file -individually. - - If any files are in a state that calls for commit, @kbd{C-x v v} reads a -single log entry and uses it for the changeset as a whole. If the -underling VCS is file- rather than changeset-oriented, the log entry -will be replicated into the history of each file. - -@node Branches -@subsection Multiple Branches of a File -@cindex branch (version control) -@cindex trunk (version control) - - One use of version control is to maintain multiple ``current'' -revisions of a file. For example, you might have different revisions of a -program in which you are gradually adding various unfinished new -features. Each such independent line of development is called a -@dfn{branch}. VC allows you to create branches, switch between -different branches, and merge changes from one branch to another. -Please note, however, that branches are not supported for SCCS. - - A file's main line of development is usually called the @dfn{trunk}. -You can create multiple branches from the trunk. How the difference -between trunk and branch is made visible is dependent on whether the -VCS uses dot-pair or monotonic version IDs. - - In VCSes with dot-pair revision IDs, the revisions on the trunk are -normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can -start an independent branch. A branch starting at revision 1.2 would -have revision ID 1.2.1.1, and consecutive revisions on this branch -would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is -a second branch also starting at revision 1.2, it would consist of -revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. - - In VCSes with monotonic revision IDs, trunk revisions are IDed as -1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and -continue through 2.2, 2.3, etc. But naming conventions for branches -and subbranches vary widely on these systems, and some (like -Mercurial) never depart from the monotonic integer sequence at all. -Consult the documentation of the VCS you are using. - -@cindex head revision - If you omit the final component of a dot-pair revision ID, that is called a -@dfn{branch ID}. It refers to the highest existing revision on that -branch---the @dfn{head revision} of that branch. The branches in the -dot-pair example above have branch IDs 1.2.1 and 1.2.2. - -@menu -* Switching Branches:: How to get to another existing branch. -* Creating Branches:: How to start a new branch. -* Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. -@end menu - -@node Switching Branches -@subsubsection Switching between Branches - - To switch between branches, type @kbd{C-u C-x v v} and specify the -revision ID you want to select. On a locking-based system, this -version is then visited @emph{unlocked} (write-protected), so you can -examine it before locking it. Switching branches in this way is allowed -only when the file is not locked. - - On a VCS with dot-pair IDs, you can omit the minor part, thus giving -only the branch ID; this takes you to the head version on the -chosen branch. If you only type @key{RET}, Emacs goes to the highest -version on the trunk. - - After you have switched to any branch (including the main branch), you -stay on it for subsequent VC commands, until you explicitly select some -other branch. - -@node Creating Branches -@subsubsection Creating New Branches - - To create a new branch from a head revision (one that is the latest in -the branch that contains it), first select that revision if necessary, -lock it with @kbd{C-x v v}, and make whatever changes you want. Then, -when you check in the changes, use @kbd{C-u C-x v v}. This lets you -specify the revision ID for the new revision. You should specify a -suitable branch ID for a branch starting at the current revision. -For example, if the current revision is 2.5, the branch ID should be -2.5.1, 2.5.2, and so on, depending on the number of existing branches at -that point. - - To create a new branch at an older revision (one that is no longer the -head of a branch), first select that revision (@pxref{Switching -Branches}). Your procedure will then differ depending on whether you -are using a locking or merging-based VCS. - - On a locking VCS, you will need to lock the old revision branch with -@kbd{C-x v v}. You'll be asked to confirm, when you lock the old -revision, that you really mean to create a new branch---if you say no, -you'll be offered a chance to lock the latest revision instead. On -a merging-based VCS you will skip this step. - - Then make your changes and type @kbd{C-x v v} again to check in a new -revision. This automatically creates a new branch starting from the -selected revision. You need not specially request a new branch, because -that's the only way to add a new revision at a point that is not the head -of a branch. - - After the branch is created, you ``stay'' on it. That means that -subsequent check-ins create new revisions on that branch. To leave the -branch, you must explicitly select a different revision with @kbd{C-u C-x -v v}. To transfer changes from one branch to another, use the merge -command, described in the next section. - -@node Merging -@subsubsection Merging Branches - -@cindex merging changes - When you have finished the changes on a certain branch, you will -often want to incorporate them into the file's main line of development -(the trunk). This is not a trivial operation, because development might -also have proceeded on the trunk, so that you must @dfn{merge} the -changes into a file that has already been changed otherwise. VC allows -you to do this (and other things) with the @code{vc-merge} command. - -@table @kbd -@item C-x v m (vc-merge) -Merge changes into the work file. -@end table - -@kindex C-x v m -@findex vc-merge - @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it -into the current version of the work file. It firsts asks you in the -minibuffer where the changes should come from. If you just type -@key{RET}, Emacs merges any changes that were made on the same branch -since you checked the file out (we call this @dfn{merging the news}). -This is the common way to pick up recent changes from the repository, -regardless of whether you have already changed the file yourself. - - You can also enter a branch ID or a pair of revision IDs in -the minibuffer. Then @kbd{C-x v m} finds the changes from that -branch, or the differences between the two revisions you specified, and -merges them into the current revision of the current file. - - As an example, suppose that you have finished a certain feature on -branch 1.3.1. In the meantime, development on the trunk has proceeded -to revision 1.5. To merge the changes from the branch to the trunk, -first go to the head revision of the trunk, by typing @kbd{C-u C-x v v -@key{RET}}. Revision 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, -type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on -branch 1.3.1 (relative to revision 1.3, where the branch started, up to -the last revision on the branch) and merges it into the current revision -of the work file. You can now check in the changed file, thus creating -revision 1.6 containing the changes from the branch. - - It is possible to do further editing after merging the branch, before -the next check-in. But it is usually wiser to check in the merged -revision, then lock it and make the further changes. This will keep -a better record of the history of changes. - -@cindex conflicts -@cindex resolving conflicts - When you merge changes into a file that has itself been modified, the -changes might overlap. We call this situation a @dfn{conflict}, and -reconciling the conflicting changes is called @dfn{resolving a -conflict}. - - Whenever conflicts occur during merging, VC detects them, tells you -about them in the echo area, and asks whether you want help in merging. -If you say yes, it starts an Ediff session (@pxref{Top, -Ediff, Ediff, ediff, The Ediff Manual}). - - If you say no, the conflicting changes are both inserted into the -file, surrounded by @dfn{conflict markers}. The example below shows how -a conflict region looks; the file is called @samp{name} and the current -master file revision with user B's changes in it is 1.11. - -@c @w here is so CVS won't think this is a conflict. -@smallexample -@group -@w{<}<<<<<< name - @var{User A's version} -======= - @var{User B's version} -@w{>}>>>>>> 1.11 -@end group -@end smallexample - -@cindex vc-resolve-conflicts - Then you can resolve the conflicts by editing the file manually. Or -you can type @code{M-x vc-resolve-conflicts} after visiting the file. -This starts an Ediff session, as described above. Don't forget to -check in the merged version afterwards. - -@node Multi-User Branching -@subsubsection Multi-User Branching - - It is often useful for multiple developers to work simultaneously on -different branches of a file. CVS and later systems allow this by -default; for RCS, it is possible if you create multiple source -directories. Each source directory should have a link named -@file{RCS} which points to a common directory of RCS master files. -Then each source directory can have its own choice of selected -revisions, but all share the same common RCS records. - - This technique works reliably and automatically, provided that the -source files contain RCS version headers -@iftex -(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Version Headers}). -@end ifnottex -The headers enable Emacs to be sure, at all times, which revision -ID is present in the work file. - - If the files do not have version headers, you must instead tell Emacs -explicitly in each session which branch you are working on. To do this, -first find the file, then type @kbd{C-u C-x v v} and specify the correct -branch ID. This ensures that Emacs knows which branch it is using -during this particular editing session. - -@ifnottex -@include vc1-xtra.texi -@end ifnottex - -@node Change Log -@section Change Logs - -@cindex change log - A change log file contains a chronological record of when and why you -have changed a program, consisting of a sequence of entries describing -individual changes. Normally it is kept in a file called -@file{ChangeLog} in the same directory as the file you are editing, or -one of its parent directories. A single @file{ChangeLog} file can -record changes for all the files in its directory and all its -subdirectories. - -@menu -* Change Log Commands:: Commands for editing change log files. -* Format of ChangeLog:: What the change log file looks like. -@end menu - -@node Change Log Commands -@subsection Change Log Commands - -@kindex C-x 4 a -@findex add-change-log-entry-other-window - The Emacs command @kbd{C-x 4 a} adds a new entry to the change log -file for the file you are editing -(@code{add-change-log-entry-other-window}). If that file is actually -a backup file, it makes an entry appropriate for the file's -parent---that is useful for making log entries for functions that -have been deleted in the current version. - - @kbd{C-x 4 a} visits the change log file and creates a new entry -unless the most recent entry is for today's date and your name. It -also creates a new item for the current file. For many languages, it -can even guess the name of the function or other object that was -changed. - -@vindex add-log-keep-changes-together - When the variable @code{add-log-keep-changes-together} is -non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file -rather than starting a new item. - -@vindex add-log-always-start-new-record - If @code{add-log-always-start-new-record} is non-@code{nil}, -@kbd{C-x 4 a} always makes a new entry, even if the last entry -was made by you and on the same date. - -@vindex change-log-version-info-enabled -@vindex change-log-version-number-regexp-list -@cindex file version in change log entries - If the value of the variable @code{change-log-version-info-enabled} -is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the -change log entry. It finds the version number by searching the first -ten percent of the file, using regular expressions from the variable -@code{change-log-version-number-regexp-list}. - -@cindex Change Log mode -@findex change-log-mode - The change log file is visited in Change Log mode. In this major -mode, each bunch of grouped items counts as one paragraph, and each -entry is considered a page. This facilitates editing the entries. -@kbd{C-j} and auto-fill indent each new line like the previous line; -this is convenient for entering the contents of an entry. - -You can use the @code{next-error} command (by default bound to -@kbd{C-x `}) to move between entries in the Change Log, when Change -Log mode is on. You will jump to the actual site in the file that was -changed, not just to the next Change Log entry. You can also use -@code{previous-error} to move back in the same list. - -@findex change-log-merge - You can use the command @kbd{M-x change-log-merge} to merge other -log files into a buffer in Change Log Mode, preserving the date -ordering of entries. - - Version control systems are another way to keep track of changes in -your program and keep a change log. In the VC log buffer, typing -@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists (@pxref{Log Buffer}). You can also -insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} -(@code{vc-update-change-log}) in the Change Log buffer -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex - -@node Format of ChangeLog -@subsection Format of ChangeLog - - A change log entry starts with a header line that contains the current -date, your name, and your email address (taken from the variable -@code{add-log-mailing-address}). Aside from these header lines, every -line in the change log starts with a space or a tab. The bulk of the -entry consists of @dfn{items}, each of which starts with a line starting -with whitespace and a star. Here are two entries, both dated in May -1993, with two items and one item respectively. - -@iftex -@medbreak -@end iftex -@smallexample -1993-05-25 Richard Stallman - - * man.el: Rename symbols `man-*' to `Man-*'. - (manual-entry): Make prompt string clearer. - - * simple.el (blink-matching-paren-distance): - Change default to 12,000. - -1993-05-24 Richard Stallman - - * vc.el (minor-mode-map-alist): Don't use it if it's void. - (vc-cancel-version): Doc fix. -@end smallexample - - One entry can describe several changes; each change should have its -own item, or its own line in an item. Normally there should be a -blank line between items. When items are related (parts of the same -change, in different places), group them by leaving no blank line -between them. - - You should put a copyright notice and permission notice at the -end of the change log file. Here is an example: - -@smallexample -Copyright 1997, 1998 Free Software Foundation, Inc. -Copying and distribution of this file, with or without modification, are -permitted provided the copyright notice and this notice are preserved. -@end smallexample - -@noindent -Of course, you should substitute the proper years and copyright holder. - -@node Tags -@section Tags Tables -@cindex tags and tag tables - - A @dfn{tag} is a reference to a subunit in a program or in a -document. In program source code, tags reference syntactic elements -of the program: functions, subroutines, data types, macros, etc. In a -document, tags reference chapters, sections, appendices, etc. Each -tag specifies the name of the file where the corresponding subunit is -defined, and the position of the subunit's definition in that file. - - A @dfn{tags table} records the tags extracted by scanning the source -code of a certain program or a certain document. Tags extracted from -generated files reference the original files, rather than the -generated files that were scanned during tag extraction. Examples of -generated files include C files generated from Cweb source files, from -a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed -C files; and Fortran files produced by preprocessing @file{.fpp} -source files. - - To produce a tags table, you use the @samp{etags} command, -submitting it a document or the source code of a program. -@samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags -file} in short. The conventional name for a tags file is @file{TAGS}. - - Emacs uses the information recorded in tags tables in commands that -search or replace through multiple source files: these commands use -the names of the source files recorded in the tags table to know which -files to search. Other commands, such as @kbd{M-.}, which finds the -definition of a function, use the recorded information about the -function names and positions to find the source file and the position -within that file where the function is defined. - -@cindex C++ class browser, tags -@cindex tags, C++ -@cindex class browser, C++ -@cindex Ebrowse - See also the Ebrowse facility, which is tailored for C++. -@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. - -@menu -* Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. -* Etags Regexps:: Create arbitrary tags using regular expressions. -* Select Tags Table:: How to visit a tags table. -* Find Tag:: Commands to find the definition of a specific tag. -* Tags Search:: Using a tags table for searching and replacing. -* List Tags:: Listing and finding tags defined in a file. -@end menu - -@node Tag Syntax -@subsection Source File Tag Syntax - - Here is how tag syntax is defined for the most popular languages: - -@itemize @bullet -@item -In C code, any C function or typedef is a tag, and so are definitions of -@code{struct}, @code{union} and @code{enum}. -@code{#define} macro definitions, @code{#undef} and @code{enum} -constants are also -tags, unless you specify @samp{--no-defines} when making the tags table. -Similarly, global variables are tags, unless you specify -@samp{--no-globals}, and so are struct members, unless you specify -@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} -and @samp{--no-members} can make the tags table file much smaller. - -You can tag function declarations and external variables in addition -to function definitions by giving the @samp{--declarations} option to -@code{etags}. - -@item -In C++ code, in addition to all the tag constructs of C code, member -functions are also recognized; member variables are also recognized, -unless you use the @samp{--no-members} option. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. @code{operator} definitions have -tag names like @samp{operator+}. - -@item -In Java code, tags include all the constructs recognized in C++, plus -the @code{interface}, @code{extends} and @code{implements} constructs. -Tags for variables and functions in classes are named -@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. - -@item -In La@TeX{} text, the argument of any of the commands @code{\chapter}, -@code{\section}, @code{\subsection}, @code{\subsubsection}, -@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, -@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, -@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, -@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill - -Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @code{etags}. The -value of this environment variable should be a colon-separated list of -command names. For example, - -@example -TEXTAGS="mycommand:myothercommand" -export TEXTAGS -@end example - -@noindent -specifies (using Bourne shell syntax) that the commands -@samp{\mycommand} and @samp{\myothercommand} also define tags. - -@item -In Lisp code, any function defined with @code{defun}, any variable -defined with @code{defvar} or @code{defconst}, and in general the first -argument of any expression that starts with @samp{(def} in column zero is -a tag. - -@item -In Scheme code, tags include anything defined with @code{def} or with a -construct whose name starts with @samp{def}. They also include variables -set with @code{set!} at top level in the file. -@end itemize - - Several other languages are also supported: - -@itemize @bullet - -@item -In Ada code, functions, procedures, packages, tasks and types are -tags. Use the @samp{--packages-only} option to create tags for -packages only. - -In Ada, the same name can be used for different kinds of entity -(e.g.@:, for a procedure and for a function). Also, for things like -packages, procedures and functions, there is the spec (i.e.@: the -interface) and the body (i.e.@: the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes -indicating the type of entity: - -@table @samp -@item /b -package body. -@item /f -function. -@item /k -task. -@item /p -procedure. -@item /s -package spec. -@item /t -type. -@end table - - Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go -directly to the body of the package @code{bidule}, while @kbd{M-x -find-tag @key{RET} bidule @key{RET}} will just search for any tag -@code{bidule}. - -@item -In assembler code, labels appearing at the beginning of a line, -followed by a colon, are tags. - -@item -In Bison or Yacc input files, each rule defines as a tag the nonterminal -it constructs. The portions of the file that contain C code are parsed -as C code. - -@item -In Cobol code, tags are paragraph names; that is, any word starting in -column 8 and followed by a period. - -@item -In Erlang code, the tags are the functions, records and macros defined -in the file. - -@item -In Fortran code, functions, subroutines and block data are tags. - -@item -In HTML input files, the tags are the @code{title} and the @code{h1}, -@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors -and all occurrences of @code{id=}. - -@item -In Lua input files, all functions are tags. - -@item -In makefiles, targets are tags; additionally, variables are tags -unless you specify @samp{--no-globals}. - -@item -In Objective C code, tags include Objective C definitions for classes, -class categories, methods and protocols. Tags for variables and -functions in classes are named @samp{@var{class}::@var{variable}} and -@samp{@var{class}::@var{function}}. - -@item -In Pascal code, the tags are the functions and procedures defined in -the file. - -@item -In Perl code, the tags are the packages, subroutines and variables -defined by the @code{package}, @code{sub}, @code{my} and @code{local} -keywords. Use @samp{--globals} if you want to tag global variables. -Tags for subroutines are named @samp{@var{package}::@var{sub}}. The -name for subroutines defined in the default package is -@samp{main::@var{sub}}. - -@item -In PHP code, tags are functions, classes and defines. Vars are tags -too, unless you use the @samp{--no-members} option. - -@item -In PostScript code, the tags are the functions. - -@item -In Prolog code, tags are predicates and rules at the beginning of -line. - -@item -In Python code, @code{def} or @code{class} at the beginning of a line -generate a tag. -@end itemize - - You can also generate tags based on regexp matching (@pxref{Etags -Regexps}) to handle other formats and languages. - -@node Create Tags Table -@subsection Creating Tags Tables -@cindex @code{etags} program - - The @code{etags} program is used to create a tags table file. It knows -the syntax of several languages, as described in -@iftex -the previous section. -@end iftex -@ifnottex -@ref{Tag Syntax}. -@end ifnottex -Here is how to run @code{etags}: - -@example -etags @var{inputfiles}@dots{} -@end example - -@noindent -The @code{etags} program reads the specified files, and writes a tags -table named @file{TAGS} in the current working directory. You can -optionally specify a different file name for the tags table by using the -@samp{--output=@var{file}} option; specifying @file{-} as a file name -prints the tags table to standard output. - - If the specified files don't exist, @code{etags} looks for -compressed versions of them and uncompresses them to read them. Under -MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} -if it is given @samp{mycode.c} on the command line and @file{mycode.c} -does not exist. - - @code{etags} recognizes the language used in an input file based on -its file name and contents. You can specify the language with the -@samp{--language=@var{name}} option, described below. - - If the tags table data become outdated due to changes in the files -described in the table, the way to update the tags table is the same -way it was made in the first place. If the tags table fails to record -a tag, or records it for the wrong file, then Emacs cannot possibly -find its definition until you update the tags table. However, if the -position recorded in the tags table becomes a little bit wrong (due to -other editing), the worst consequence is a slight delay in finding the -tag. Even if the stored position is very far wrong, Emacs will still -find the tag, after searching most of the file for it. That delay is -hardly noticeable with today's computers. - - Thus, there is no need to update the tags table after each edit. -You should update a tags table when you define new tags that you want -to have listed, or when you move tag definitions from one file to -another, or when changes become substantial. - - One tags table can virtually include another. Specify the included -tags file name with the @samp{--include=@var{file}} option when -creating the file that is to include it. The latter file then acts as -if it covered all the source files specified in the included file, as -well as the files it directly contains. - - If you specify the source files with relative file names when you run -@code{etags}, the tags file will contain file names relative to the -directory where the tags file was initially written. This way, you can -move an entire directory tree containing both the tags file and the -source files, and the tags file will still refer correctly to the source -files. If the tags file is @file{-} or is in the @file{/dev} directory, -however, the file names are -made relative to the current working directory. This is useful, for -example, when writing the tags to @file{/dev/stdout}. - - When using a relative file name, it should not be a symbolic link -pointing to a tags file in a different directory, because this would -generally render the file names invalid. - - If you specify absolute file names as arguments to @code{etags}, then -the tags file will contain absolute file names. This way, the tags file -will still refer to the same files even if you move it, as long as the -source files remain in the same place. Absolute file names start with -@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. - - When you want to make a tags table from a great number of files, you -may have problems listing them on the command line, because some systems -have a limit on its length. The simplest way to circumvent this limit -is to tell @code{etags} to read the file names from its standard input, -by typing a dash in place of the file names, like this: - -@smallexample -find . -name "*.[chCH]" -print | etags - -@end smallexample - - Use the option @samp{--language=@var{name}} to specify the language -explicitly. You can intermix these options with file names; each one -applies to the file names that follow it. Specify -@samp{--language=auto} to tell @code{etags} to resume guessing the -language from the file names and file contents. Specify -@samp{--language=none} to turn off language-specific processing -entirely; then @code{etags} recognizes tags by regexp matching alone -(@pxref{Etags Regexps}). - - The option @samp{--parse-stdin=@var{file}} is mostly useful when -calling @code{etags} from programs. It can be used (only once) in -place of a file name on the command line. @code{Etags} will read from -standard input and mark the produced tags as belonging to the file -@var{file}. - - @samp{etags --help} outputs the list of the languages @code{etags} -knows, and the file name rules for guessing the language. It also prints -a list of all the available @code{etags} options, together with a short -explanation. If followed by one or more @samp{--language=@var{lang}} -options, it outputs detailed information about how tags are generated for -@var{lang}. - -@node Etags Regexps -@subsection Etags Regexps - - The @samp{--regex} option provides a general way of recognizing tags -based on regexp matching. You can freely intermix this option with -file names, and each one applies to the source files that follow it. -If you specify multiple @samp{--regex} options, all of them are used -in parallel. The syntax is: - -@smallexample ---regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} -@end smallexample - - The essential part of the option value is @var{tagregexp}, the -regexp for matching tags. It is always used anchored, that is, it -only matches at the beginning of a line. If you want to allow -indented tags, use a regexp that matches initial whitespace; start it -with @samp{[ \t]*}. - - In these regular expressions, @samp{\} quotes the next character, and -all the GCC character escape sequences are supported (@samp{\a} for -bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for -escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for -carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). - - Ideally, @var{tagregexp} should not match more characters than are -needed to recognize what you want to tag. If the syntax requires you -to write @var{tagregexp} so it matches more characters beyond the tag -itself, you should add a @var{nameregexp}, to pick out just the tag. -This will enable Emacs to find tags more accurately and to do -completion on tag names more reliably. You can find some examples -below. - - The @var{modifiers} are a sequence of zero or more characters that -modify the way @code{etags} does the matching. A regexp with no -modifiers is applied sequentially to each line of the input file, in a -case-sensitive way. The modifiers and their meanings are: - -@table @samp -@item i -Ignore case when matching this regexp. -@item m -Match this regular expression against the whole file, so that -multi-line matches are possible. -@item s -Match this regular expression against the whole file, and allow -@samp{.} in @var{tagregexp} to match newlines. -@end table - - The @samp{-R} option cancels all the regexps defined by preceding -@samp{--regex} options. It too applies to the file names following -it. Here's an example: - -@smallexample -etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ - bar.ber -R --lang=lisp los.er -@end smallexample - -@noindent -Here @code{etags} chooses the parsing language for @file{voo.doo} and -@file{bar.ber} according to their contents. @code{etags} also uses -@var{reg1} to recognize additional tags in @file{voo.doo}, and both -@var{reg1} and @var{reg2} to recognize additional tags in -@file{bar.ber}. @var{reg1} is checked against each line of -@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while -@var{reg2} is checked against the whole @file{bar.ber} file, -permitting multi-line matches, in a case-sensitive way. @code{etags} -uses only the Lisp tags rules, with no user-specified regexp matching, -to recognize tags in @file{los.er}. - - You can restrict a @samp{--regex} option to match only files of a -given language by using the optional prefix @var{@{language@}}. -(@samp{etags --help} prints the list of languages recognized by -@code{etags}.) This is particularly useful when storing many -predefined regular expressions for @code{etags} in a file. The -following example tags the @code{DEFVAR} macros in the Emacs source -files, for the C language only: - -@smallexample ---regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' -@end smallexample - -@noindent -When you have complex regular expressions, you can store the list of -them in a file. The following option syntax instructs @code{etags} to -read two files of regular expressions. The regular expressions -contained in the second file are matched without regard to case. - -@smallexample ---regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} -@end smallexample - -@noindent -A regex file for @code{etags} contains one regular expression per -line. Empty lines, and lines beginning with space or tab are ignored. -When the first character in a line is @samp{@@}, @code{etags} assumes -that the rest of the line is the name of another file of regular -expressions; thus, one such file can include another file. All the -other lines are taken to be regular expressions. If the first -non-whitespace text on the line is @samp{--}, that line is a comment. - - For example, we can create a file called @samp{emacs.tags} with the -following contents: - -@smallexample - -- This is for GNU Emacs C source files -@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ -@end smallexample - -@noindent -and then use it like this: - -@smallexample -etags --regex=@@emacs.tags *.[ch] */*.[ch] -@end smallexample - - Here are some more examples. The regexps are quoted to protect them -from shell interpretation. - -@itemize @bullet - -@item -Tag Octave files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ - --regex='/###key \(.*\)/\1/' \ - --regex='/[ \t]*global[ \t].*/' \ - *.m -@end smallexample - -@noindent -Note that tags are not generated for scripts, so that you have to add -a line by yourself of the form @samp{###key @var{scriptname}} if you -want to jump to it. - -@item -Tag Tcl files: - -@smallexample -etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl -@end smallexample - -@item -Tag VHDL files: - -@smallexample -etags --language=none \ - --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ - --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ - \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' -@end smallexample -@end itemize - -@node Select Tags Table -@subsection Selecting a Tags Table - -@vindex tags-file-name -@findex visit-tags-table - Emacs has at any time one @dfn{selected} tags table, and all the -commands for working with tags tables use the selected one. To select -a tags table, type @kbd{M-x visit-tags-table}, which reads the tags -table file name as an argument, with @file{TAGS} in the default -directory as the default. - - Emacs does not actually read in the tags table contents until you -try to use them; all @code{visit-tags-table} does is store the file -name in the variable @code{tags-file-name}, and setting the variable -yourself is just as good. The variable's initial value is @code{nil}; -that value tells all the commands for working with tags tables that -they must ask for a tags table file name to use. - - Using @code{visit-tags-table} when a tags table is already loaded -gives you a choice: you can add the new tags table to the current list -of tags tables, or start a new list. The tags commands use all the tags -tables in the current list. If you start a new list, the new tags table -is used @emph{instead} of others. If you add the new table to the -current list, it is used @emph{as well as} the others. - -@vindex tags-table-list - You can specify a precise list of tags tables by setting the variable -@code{tags-table-list} to a list of strings, like this: - -@c keep this on two lines for formatting in smallbook -@example -@group -(setq tags-table-list - '("~/emacs" "/usr/local/lib/emacs/src")) -@end group -@end example - -@noindent -This tells the tags commands to look at the @file{TAGS} files in your -@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} -directory. The order depends on which file you are in and which tags -table mentions that file, as explained above. - - Do not set both @code{tags-file-name} and @code{tags-table-list}. - -@node Find Tag -@subsection Finding a Tag - - The most important thing that a tags table enables you to do is to find -the definition of a specific tag. - -@table @kbd -@item M-.@: @var{tag} @key{RET} -Find first definition of @var{tag} (@code{find-tag}). -@item C-u M-. -Find next alternate definition of last tag specified. -@item C-u - M-. -Go back to previous tag found. -@item C-M-. @var{pattern} @key{RET} -Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). -@item C-u C-M-. -Find the next tag whose name matches the last pattern used. -@item C-x 4 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, but display it in another window -(@code{find-tag-other-window}). -@item C-x 5 .@: @var{tag} @key{RET} -Find first definition of @var{tag}, and create a new frame to select the -buffer (@code{find-tag-other-frame}). -@item M-* -Pop back to where you previously invoked @kbd{M-.} and friends. -@end table - -@kindex M-. -@findex find-tag - @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of -a specified tag. It searches through the tags table for that tag, as a -string, and then uses the tags table info to determine the file that the -definition is in and the approximate character position in the file of -the definition. Then @code{find-tag} visits that file, moves point to -the approximate character position, and searches ever-increasing -distances away to find the tag definition. - - If an empty argument is given (just type @key{RET}), the balanced -expression in the buffer before or around point is used as the -@var{tag} argument. @xref{Expressions}. - - You don't need to give @kbd{M-.} the full name of the tag; a part -will do. This is because @kbd{M-.} finds tags in the table which -contain @var{tag} as a substring. However, it prefers an exact match -to a substring match. To find other tags that match the same -substring, give @code{find-tag} a numeric argument, as in @kbd{C-u -M-.}; this does not read a tag name, but continues searching the tags -table's text for another tag containing the same substring last used. -If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier -alternative to @kbd{C-u M-.}. - -@kindex C-x 4 . -@findex find-tag-other-window -@kindex C-x 5 . -@findex find-tag-other-frame - Like most commands that can switch buffers, @code{find-tag} has a -variant that displays the new buffer in another window, and one that -makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes -the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}}, -which invokes @code{find-tag-other-frame}. - - To move back to places you've found tags recently, use @kbd{C-u - -M-.}; more generally, @kbd{M-.} with a negative numeric argument. This -command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative -argument finds the previous tag location in another window. - -@kindex M-* -@findex pop-tag-mark -@vindex find-tag-marker-ring-length - As well as going back to places you've found tags recently, you can go -back to places @emph{from where} you found them. Use @kbd{M-*}, which -invokes the command @code{pop-tag-mark}, for this. Typically you would -find and study the definition of something with @kbd{M-.} and then -return to where you were with @kbd{M-*}. - - Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to -a depth determined by the variable @code{find-tag-marker-ring-length}. - -@findex find-tag-regexp -@kindex C-M-. - The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that -match a specified regular expression. It is just like @kbd{M-.} except -that it does regexp matching instead of substring matching. - -@node Tags Search -@subsection Searching and Replacing with Tags Tables -@cindex search and replace in multiple files -@cindex multiple-file search and replace - - The commands in this section visit and search all the files listed -in the selected tags table, one by one. For these commands, the tags -table serves only to specify a sequence of files to search. These -commands scan the list of tags tables starting with the first tags -table (if any) that describes the current file, proceed from there to -the end of the list, and then scan from the beginning of the list -until they have covered all the tables in the list. - -@table @kbd -@item M-x tags-search @key{RET} @var{regexp} @key{RET} -Search for @var{regexp} through the files in the selected tags -table. -@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} -Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-, -Restart one of the commands above, from the current location of point -(@code{tags-loop-continue}). -@end table - -@findex tags-search - @kbd{M-x tags-search} reads a regexp using the minibuffer, then -searches for matches in all the files in the selected tags table, one -file at a time. It displays the name of the file being searched so you -can follow its progress. As soon as it finds an occurrence, -@code{tags-search} returns. - -@kindex M-, -@findex tags-loop-continue - Having found one match, you probably want to find all the rest. To find -one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the -@code{tags-search}. This searches the rest of the current buffer, followed -by the remaining files of the tags table.@refill - -@findex tags-query-replace - @kbd{M-x tags-query-replace} performs a single -@code{query-replace-regexp} through all the files in the tags table. It -reads a regexp to search for and a string to replace with, just like -ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x -tags-search}, but repeatedly, processing matches according to your -input. @xref{Replace}, for more information on query replace. - -@vindex tags-case-fold-search -@cindex case-sensitivity and tags search - You can control the case-sensitivity of tags search commands by -customizing the value of the variable @code{tags-case-fold-search}. The -default is to use the same setting as the value of -@code{case-fold-search} (@pxref{Search Case}). - - It is possible to get through all the files in the tags table with a -single invocation of @kbd{M-x tags-query-replace}. But often it is -useful to exit temporarily, which you can do with any input event that -has no special query replace meaning. You can resume the query -replace subsequently by typing @kbd{M-,}; this command resumes the -last tags search or replace command that you did. For instance, to -skip the rest of the current file, you can type @kbd{M-> M-,}. - - The commands in this section carry out much broader searches than the -@code{find-tag} family. The @code{find-tag} commands search only for -definitions of tags that match your substring or regexp. The commands -@code{tags-search} and @code{tags-query-replace} find every occurrence -of the regexp, as ordinary search commands and replace commands do in -the current buffer. - - These commands create buffers only temporarily for the files that they -have to search (those which are not already visited in Emacs buffers). -Buffers in which no match is found are quickly killed; the others -continue to exist. - - It may have struck you that @code{tags-search} is a lot like -@code{grep}. You can also run @code{grep} itself as an inferior of -Emacs and have Emacs show you the matching lines one by one. -@xref{Grep Searching}. - -@node List Tags -@subsection Tags Table Inquiries - -@table @kbd -@item M-x list-tags @key{RET} @var{file} @key{RET} -Display a list of the tags defined in the program file @var{file}. -@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all tags matching @var{regexp}. -@end table - -@findex list-tags - @kbd{M-x list-tags} reads the name of one of the files described by -the selected tags table, and displays a list of all the tags defined in -that file. The ``file name'' argument is really just a string to -compare against the file names recorded in the tags table; it is read as -a string rather than as a file name. Therefore, completion and -defaulting are not available, and you must enter the file name the same -way it appears in the tags table. Do not include a directory as part of -the file name unless the file name recorded in the tags table includes a -directory. - -@findex tags-apropos -@vindex tags-apropos-verbose - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It finds all the tags in the selected tags table -whose entries match @var{regexp}, and displays them. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. - -@vindex tags-tag-face -@vindex tags-apropos-additional-actions - You can customize the appearance of the output by setting the -variable @code{tags-tag-face} to a face. You can display additional -output with @kbd{M-x tags-apropos} by customizing the variable -@code{tags-apropos-additional-actions}---see its documentation for -details. - - You can also use the collection of tag names to complete a symbol -name in the buffer. @xref{Symbol Completion}. - -@ifnottex -@include emerge-xtra.texi -@end ifnottex - -@ignore - arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb -@end ignore diff --git a/doc/emacs/major.texi b/doc/emacs/major.texi deleted file mode 100644 index 545b7080ee7..00000000000 --- a/doc/emacs/major.texi +++ /dev/null @@ -1,226 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Major Modes, Indentation, International, Top -@chapter Major Modes -@cindex major modes -@cindex mode, major -@kindex TAB @r{(and major modes)} -@kindex DEL @r{(and major modes)} -@kindex C-j @r{(and major modes)} - - Emacs provides many alternative @dfn{major modes}, each of which -customizes Emacs for editing text of a particular sort. The major modes -are mutually exclusive, and each buffer has one major mode at any time. -The mode line normally shows the name of the current major mode, in -parentheses (@pxref{Mode Line}). - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific redefinitions or variable settings, so -that each Emacs command behaves in its most general manner, and each -user option variable is in its default state. For editing text of a -specific type that Emacs knows about, such as Lisp code or English -text, you should switch to the appropriate major mode, such as Lisp -mode or Text mode. - - Selecting a major mode changes the meanings of a few keys to become -more specifically adapted to the language being edited. The ones that -are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The -prefix key @kbd{C-c} normally contains mode-specific commands. In -addition, the commands which handle comments use the mode to determine -how comments are to be delimited. Many major modes redefine the -syntactical properties of characters appearing in the buffer. -@xref{Syntax}. - - The major modes fall into three major groups. The first group -contains modes for normal text, either plain or with mark-up. It -includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline -mode. The second group contains modes for specific programming -languages. These include Lisp mode (which has several variants), C -mode, Fortran mode, and others. The remaining major modes are not -intended for use on users' files; they are used in buffers created for -specific purposes by Emacs, such as Dired mode for buffers made by -Dired (@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m} -(@pxref{Sending Mail}), and Shell mode for buffers used for -communicating with an inferior shell process (@pxref{Interactive -Shell}). - - Most programming-language major modes specify that only blank lines -separate paragraphs. This is to make the paragraph commands useful. -(@xref{Paragraphs}.) They also cause Auto Fill mode to use the -definition of @key{TAB} to indent the new lines it creates. This is -because most lines in a program are usually indented -(@pxref{Indentation}). - -@menu -* Choosing Modes:: How major modes are specified or chosen. -@end menu - -@node Choosing Modes,,Major Modes,Major Modes -@section How Major Modes are Chosen - -@cindex choosing a major mode - You can select a major mode explicitly for the current buffer, but -most of the time Emacs determines which mode to use based on the file -name or on special text in the file. - - To explicitly select a new major, you use an @kbd{M-x} command. -Take the name of a major mode and add @code{-mode} to get the name of -the command to select that mode. Thus, you can enter Lisp mode by -executing @kbd{M-x lisp-mode}. - -@vindex auto-mode-alist - When you visit a file, Emacs usually chooses the right major mode -automatically. Normally, it makes the choice based on the file -name---for example, files whose names end in @samp{.c} are normally -edited in C mode---but sometimes it chooses the major mode based on -the contents of the file. Here is the exact procedure: - - First, Emacs checks whether the file contains a file-local variable -that specifies the major mode. If so, it uses that major mode, -ignoring all other criteria. @xref{File Variables}. There are -several methods to specify a major mode using a file-local variable; -the simplest is to put the mode name in the first nonblank line, -preceded and followed by @samp{-*-}. Other text may appear on the -line as well. For example, - -@example -; -*-Lisp-*- -@end example - -@noindent -tells Emacs to use Lisp mode. Note how the semicolon is used to make -Lisp treat this line as a comment. Alternatively, you could write - -@example -; -*- mode: Lisp;-*- -@end example - -@noindent -The latter format allows you to specify local variables as well, like -this: - -@example -; -*- mode: Lisp; tab-width: 4; -*- -@end example - -@vindex interpreter-mode-alist - Second, Emacs checks whether the file's contents begin with -@samp{#!}. If so, that indicates that the file can serve as an -executable shell command, which works by running an interpreter named -on the file's first line (the rest of the file is used as input to the -interpreter). Therefore, Emacs tries to use the interpreter name to -choose a mode. For instance, a file that begins with -@samp{#!/usr/bin/perl} is opened in Perl mode. The variable -@code{interpreter-mode-alist} specifies the correspondence between -interpreter program names and major modes. - - When the first line starts with @samp{#!}, you usually cannot use -the @samp{-*-} feature on the first line, because the system would get -confused when running the interpreter. So Emacs looks for @samp{-*-} -on the second line in such files as well as on the first line. The -same is true for man pages which start with the magic string -@samp{'\"} to specify a list of troff preprocessors. - -@vindex magic-mode-alist - Third, Emacs tries to determine the major mode by looking at the -text at the start of the buffer, based on the variable -@code{magic-mode-alist}. By default, this variable is @code{nil} (an -empty list), so Emacs skips this step; however, you can customize it -in your init file (@pxref{Init File}). The value should be a list of -elements of the form - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -where @var{regexp} is a regular expression (@pxref{Regexps}), and -@var{mode-function} is a Lisp function that toggles a major mode. If -the text at the beginning of the file matches @var{regexp}, Emacs -chooses the major mode specified by @var{mode-function}. - -Alternatively, an element of @code{magic-mode-alist} may have the form - -@example -(@var{match-function} . @var{mode-function}) -@end example - -@noindent -where @var{match-function} is a Lisp function that is called at the -beginning of the buffer; if the function returns non-@code{nil}, Emacs -set the major mode wit @var{mode-function}. - - Fourth---if Emacs still hasn't found a suitable major mode---it -looks at the file's name. The correspondence between file names and -major modes is controlled by the variable @code{auto-mode-alist}. Its -value is a list in which each element has this form, - -@example -(@var{regexp} . @var{mode-function}) -@end example - -@noindent -or this form, - -@example -(@var{regexp} @var{mode-function} @var{flag}) -@end example - -@noindent -For example, one element normally found in the list has the form -@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C -mode for files whose names end in @file{.c}. (Note that @samp{\\} is -needed in Lisp syntax to include a @samp{\} in the string, which must -be used to suppress the special meaning of @samp{.} in regexps.) If -the element has the form @code{(@var{regexp} @var{mode-function} -@var{flag})} and @var{flag} is non-@code{nil}, then after calling -@var{mode-function}, Emacs discards the suffix that matched -@var{regexp} and searches the list again for another match. - -@vindex auto-mode-case-fold - On systems with case-insensitive file names, such as Microsoft -Windows, Emacs performs a single case-insensitive search through -@code{auto-mode-alist}. On other systems, Emacs normally performs a -single case-sensitive search through the alist. However, if you -change the variable @code{auto-mode-case-fold} to @code{t}, Emacs -performs a second case-insensitive search if the first search fails. - -@vindex magic-fallback-mode-alist - Finally, if Emacs @emph{still} hasn't found a major mode to use, it -compares the text at the start of the buffer to the variable -@code{magic-fallback-mode-alist}. This variable works like -@code{magic-mode-alist}, described above, except that is consulted -only after @code{auto-mode-alist}. By default, -@code{magic-fallback-mode-alist} contains forms that check for image -files, HTML/XML/SGML files, and Postscript files. - -@vindex default-major-mode - When you visit a file that does not specify a major mode to use, or -when you create a new buffer with @kbd{C-x b}, the variable -@code{default-major-mode} specifies which major mode to use. Normally -its value is the symbol @code{fundamental-mode}, which specifies -Fundamental mode. If @code{default-major-mode} is @code{nil}, the -major mode is taken from the previously current buffer. - -@findex normal-mode - If you change the major mode of a buffer, you can go back to the major -mode Emacs would choose automatically: use the command @kbd{M-x -normal-mode} to do this. This is the same function that -@code{find-file} calls to choose the major mode. It also processes -the file's @samp{-*-} line or local variables list (if any). -@xref{File Variables}. - -@vindex change-major-mode-with-file-name - The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to -a new major mode if the new file name implies a mode (@pxref{Saving}). -(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) -However, this does not happen if the buffer contents specify a major -mode, and certain ``special'' major modes do not allow the mode to -change. You can turn off this mode-changing feature by setting -@code{change-major-mode-with-file-name} to @code{nil}. - -@ignore - arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155 -@end ignore diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in deleted file mode 100644 index 9c1a8cd0037..00000000000 --- a/doc/emacs/makefile.w32-in +++ /dev/null @@ -1,144 +0,0 @@ -#### -*- Makefile -*- for the Emacs Manual - -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo --force -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_TARGETS = $(infodir)/emacs -DVI_TARGETS = emacs.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C - -EMACS_XTRA=\ - $(srcdir)/arevert-xtra.texi \ - $(srcdir)/cal-xtra.texi \ - $(srcdir)/dired-xtra.texi \ - $(srcdir)/picture-xtra.texi \ - $(srcdir)/emerge-xtra.texi \ - $(srcdir)/vc-xtra.texi \ - $(srcdir)/vc1-xtra.texi \ - $(srcdir)/fortran-xtra.texi \ - $(srcdir)/msdog-xtra.texi - -EMACSSOURCES= \ - $(srcdir)/emacs.texi \ - $(srcdir)/doclicense.texi \ - $(srcdir)/screen.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/entering.texi \ - $(srcdir)/basic.texi \ - $(srcdir)/mini.texi \ - $(srcdir)/m-x.texi \ - $(srcdir)/help.texi \ - $(srcdir)/mark.texi \ - $(srcdir)/killing.texi \ - $(srcdir)/regs.texi \ - $(srcdir)/display.texi \ - $(srcdir)/search.texi \ - $(srcdir)/fixit.texi \ - $(srcdir)/files.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/mule.texi \ - $(srcdir)/major.texi \ - $(srcdir)/indent.texi \ - $(srcdir)/text.texi \ - $(srcdir)/programs.texi \ - $(srcdir)/building.texi \ - $(srcdir)/maintaining.texi \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/sending.texi \ - $(srcdir)/rmail.texi \ - $(srcdir)/dired.texi \ - $(srcdir)/calendar.texi \ - $(srcdir)/misc.texi \ - $(srcdir)/custom.texi \ - $(srcdir)/trouble.texi \ - $(srcdir)/cmdargs.texi \ - $(srcdir)/xresources.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/macos.texi \ - $(srcdir)/msdog.texi \ - $(srcdir)/gnu.texi \ - $(srcdir)/glossary.texi \ - $(srcdir)/ack.texi \ - $(srcdir)/kmacro.texi \ - $(EMACS_XTRA) - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -$(infodir)/emacs: $(EMACSSOURCES) - $(MAKEINFO) emacs.texi - -emacs.dvi: $(EMACSSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi - -emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/emacs* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi deleted file mode 100644 index ca50643d596..00000000000 --- a/doc/emacs/mark.texi +++ /dev/null @@ -1,453 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Mark, Killing, Help, Top -@chapter The Mark and the Region -@cindex mark -@cindex setting a mark -@cindex region - - Many Emacs commands operate on an arbitrary contiguous part of the -current buffer. To specify the text for such a command to operate on, -you set @dfn{the mark} at one end of it, and move point to the other -end. The text between point and the mark is called @dfn{the region}. -The region always extends between point and the mark, no matter which -one comes earlier in the text; each time you move point, the region -changes. - - Setting the mark at a position in the text also @dfn{activates} it. -When the mark is active, Emacs indicates the extent of the region by -highlighting the text within it, using the @code{region} face -(@pxref{Face Customization}). After certain non-motion commands, -including any command that changes the text in the buffer, Emacs -automatically @dfn{deactivates} the mark; this turns off the -highlighting. You can also explicitly deactivate the mark at any -time, by typing @kbd{C-g} (@pxref{Quitting}). - - This default behavior of the mark is known as Transient Mark mode. -Disabling Transient Mark mode switches Emacs to an alternative -behavior, in which the mark is always active, which was the default -prior to Emacs 23. @xref{Persistent Mark}. - -@vindex highlight-nonselected-windows - Setting the mark in one buffer has no effect on the marks in other -buffers. When you return to a buffer with an active mark, the mark is -at the same place as before. When multiple windows show the same -buffer, they can have different values of point, and thus different -regions, but they all share one common mark position. @xref{Windows}. -Ordinarily, only the selected window highlights its region; however, -if the variable @code{highlight-nonselected-windows} is -non-@code{nil}, each window highlights its own region. - -@menu -* Setting Mark:: Commands to set the mark. -* Marking Objects:: Commands to put region around textual units. -* Using Region:: Summary of ways to operate on contents of the region. -* Mark Ring:: Previous mark positions saved so you can go back there. -* Global Mark Ring:: Previous mark positions in various buffers. -* Shift Selection:: Using shifted cursor motion keys. -* Persistent Mark:: Keeping the mark active all the time. -@end menu - -@node Setting Mark -@section Setting the Mark - - Here are some commands for setting the mark: - -@table @kbd -@item C-@key{SPC} -Set the mark at point, and activate it (@code{set-mark-command}). -@item C-@@ -The same. -@item C-x C-x -Set the mark at point, and move point where the mark was -(@code{exchange-point-and-mark}). -@item Drag-Mouse-1 -Set point and the mark around the text you drag across. -@item Mouse-3 -Set the mark at point, then move point to where you click -(@code{mouse-save-then-kill}). -@item @samp{Shifted motion keys} -Set the mark at point if the mark is inactive, then move point. -@end table - -@kindex C-SPC -@kindex C-@@ -@findex set-mark-command - The most common way to set the mark is with @kbd{C-@key{SPC}} -(@code{set-mark-command})@footnote{There is no @kbd{C-@key{SPC}} -character in @acronym{ASCII}; usually, typing @kbd{C-@key{SPC}} on a -text terminal gives the character @kbd{C-@@}. This key is also bound -to @code{set-mark-command}, so unless you are unlucky enough to have -an text terminal that behaves differently, you might as well think of -@kbd{C-@@} as @kbd{C-@key{SPC}}.}. This sets the mark where point is, -and activates it. You can then move point away, leaving the mark -behind. - - For example, suppose you wish to convert part of the buffer to upper -case. To accomplish this, go to the beginning of the desired text, -type @kbd{C-@key{SPC}}, and move point until the desired portion of -text is highlighted. Now type @kbd{C-x C-u} (@code{upcase-region}). -This converts the text in the region to upper case, and then -deactivates the mark. - -@kindex C-x C-x -@findex exchange-point-and-mark - The command @kbd{C-x C-x} (@code{exchange-point-and-mark}) exchanges -the positions of point and the mark, keeping the region unchanged. If -the mark is inactive, Emacs first reactivates the mark wherever it was -last set. @kbd{C-x C-x} is useful when you are satisfied with the -position of point but want to move the other end of the region (where -the mark is). Using @kbd{C-x C-x} a second time, if necessary, puts -the mark at the new position with point back at its original position. - - You can also set the mark with the mouse. If you press the left -mouse button (@kbd{down-mouse-1}) and drag the mouse across a range of -text while holding down this button, this sets the mark where you -first pressed the mouse button and puts point where you release it. -Alternatively, clicking the right mouse button (@kbd{mouse-3}) sets -the mark at point and then moves point to where you clicked. Using -the mouse to mark a region also copies the region into the kill ring -(@pxref{Kill Ring}). @xref{Mouse Commands}, for a more detailed -description of these mouse commands. - -@cindex shift-selection - Finally, you can set the mark by holding down the shift key while -typing certain cursor motion commands (such as @kbd{S-@key{right}}, -@kbd{S-C-f}, @kbd{S-C-n}, etc.) This is referred to as -@dfn{shift-selection}. This sets the mark at point before moving -point, but only if there is no active mark set via shift-selection. -The mark set by mouse commands and by shift-selection behaves slightly -differently from the usual mark: any subsequent unshifted cursor -motion command deactivates it automatically. For details, @xref{Shift -Selection}. - - Whenever the mark is active, you can deactivate it by typing -@kbd{C-g} (@pxref{Quitting}). The mark is also automatically -deactivated after certain non-motion commands. - -@node Marking Objects -@section Commands to Mark Textual Objects - -@cindex marking sections of text - Here are the commands for placing point and the mark around a textual -object such as a word, list, paragraph or page: - -@table @kbd -@item M-@@ -Set mark after end of next word (@code{mark-word}). This does not -move point. -@item C-M-@@ -Set mark after end of following balanced expression -(@code{mark-sexp}). This does not move point. -@item M-h -Move point to the beginning of the current paragraph, and set mark at -the end (@code{mark-paragraph}). -@item C-M-h -Move point to the beginning of the current defun, and set mark at the -end (@code{mark-defun}). -@item C-x C-p -Move point to the beginning of the current page, and set mark at the -end (@code{mark-page}). -@item C-x h -Move point to the beginning of the buffer, and set mark at the end -(@code{mark-whole-buffer}). -@end table - -@findex mark-word -@findex mark-sexp -@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next -word, while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the -next balanced expression (@pxref{Expressions}). These commands handle -arguments just like @kbd{M-f} and @kbd{C-M-f}. - -@kindex C-x h -@findex mark-whole-buffer - The other commands in the above list set both point and mark, so as -to delimit an object in the buffer. @kbd{M-h} (@code{mark-paragraph}) -moves point to the beginning of the paragraph that surrounds or -follows point, and sets the mark at the end of that paragraph -(@pxref{Paragraphs}). As a special exception, repeated invocations of -@kbd{M-h} extend the region to subsequent paragraphs. This is -convenient for indenting, case-converting, or killing entire -paragraphs. - - The @kbd{M-h} command accepts prefix arguments. If the argument's -value is positive, @kbd{M-h} marks that many paragraphs starting with -the one surrounding point; therefore, @kbd{C-u M-h} is equivalent to -@kbd{M-h M-h M-h M-h}. If the prefix argument is @minus{}@var{n}, -@kbd{M-h} marks @var{n} paragraphs running back from the one -surrounding point; in this case, point moves forward to the end of -that paragraph, and the mark goes at the start of the region. - - Similarly, @kbd{C-M-h} (@code{mark-defun}) sets mark and point -around major top-level definitions (@pxref{Moving by Defuns}), and -@kbd{C-x C-p} (@code{mark-page}) does the same for pages -(@pxref{Pages}). These treat repeated invocations and prefix -arguments similarly to @code{mark-paragraph}. - - Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire -buffer as the region, by putting point at the beginning and the mark -at the end. (In some programs this is called ``select all.'') - -@node Using Region -@section Operating on the Region - -@cindex operations on a marked region - Once you have a region, here are some of the ways you can operate on -it: - -@itemize @bullet -@item -Kill it with @kbd{C-w} (@pxref{Killing}). -@item -Copy it to the kill ring with @kbd{M-w} (@pxref{Yanking}). -@item -Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). -@item -Undo changes within it using @kbd{C-u C-/} (@pxref{Undo}). -@item -Replace text within it using @kbd{M-%} (@pxref{Query Replace}). -@item -Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). -@item -Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). -@item -Print hardcopy with @kbd{M-x print-region} (@pxref{Printing}). -@item -Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). -@item -Save it in a register with @kbd{C-x r s} (@pxref{Registers}). -@item -Save it in a buffer or a file (@pxref{Accumulating Text}). -@end itemize - - Most commands that operate on the text in the region have the word -@code{region} in their names. - - Some commands have a default behavior when the mark is inactive, but -operate on the text in the region if the mark is active. For example, -@kbd{M-$} (@code{ispell-word}) normally checks the spelling of the -word at point, but it checks the text in the region if the region is -active (@pxref{Spelling}). Normally, such commands use their default -behavior if the region is empty (i.e., if mark and point are at the -same position). If you want them to operate on the empty region, -change the variable @code{use-empty-active-region} to @code{t}. - -@cindex Delete Selection mode -@cindex mode, Delete Selection -@findex delete-selection-mode - If you enable Delete Selection mode, a minor mode, then inserting -text while the mark is active causes the selected text to be deleted -first. This also deactivates the mark. Many graphical applications -follow this convention, but Emacs does not. To toggle Delete -Selection mode on or off, type @kbd{M-x delete-selection-mode}. -Another effect of this mode is that some keys, such as @key{DEL} and -@kbd{C-d}, always kill the region if one exists. - -@node Mark Ring -@section The Mark Ring - -@cindex mark ring - Aside from delimiting the region, the mark is also useful for -remembering spots that you may want to go back to. Each buffer -remembers 16 previous locations of the mark, in the @dfn{mark ring}. -Commands that set the mark also push the old mark onto this ring. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -Set the mark, pushing it onto the mark ring, without activating it. -@item C-u C-@key{SPC} -Move point to where the mark was, and restore the mark from the ring -of former marks. -@end table - -@kindex C-SPC C-SPC - The command C-@key{SPC} C-@key{SPC} is handy when you want to use -the mark to remember a position to which you may wish to return. It -pushes the current point onto the mark ring, without activating the -mark (which would cause Emacs to highlight the region). This is -actually two consecutive invocations of @kbd{C-@key{SPC}} -(@code{set-mark-command}); the first @kbd{C-@key{SPC}} sets the mark, -and the second @kbd{C-@key{SPC}} deactivates it. (When Transient Mark -mode is off, C-@key{SPC} C-@key{SPC} instead activates Transient Mark -mode temporarily. @xref{Persistent Mark}.) - -@kindex C-u C-SPC - To return to a marked position, use @code{set-mark-command} with a -prefix argument: @kbd{C-u C-@key{SPC}}. This moves point to where the -mark was, and deactivates the mark if it was active. Each subsequent -@kbd{C-u C-@key{SPC}} jumps to a prior position stored in the mark -ring. The positions you move through in this way are not lost; they -go to the end of the ring. - -@vindex set-mark-command-repeat-pop - If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, -then immediately after you type @kbd{C-u C-@key{SPC}}, you can type -@kbd{C-@key{SPC}} instead of @kbd{C-u C-@key{SPC}} to cycle through -the mark ring. By default, @code{set-mark-command-repeat-pop} is -@code{nil}. - - Each buffer has its own mark ring. All editing commands use the -current buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} -always stays in the same buffer. - -@vindex mark-ring-max - The variable @code{mark-ring-max} specifies the maximum number of -entries to keep in the mark ring. If that many entries exist and -another one is pushed, the earliest one in the list is discarded. Repeating -@kbd{C-u C-@key{SPC}} cycles through the positions currently in the -ring. - -@vindex mark-even-if-inactive - If the variable @code{mark-even-if-inactive} is @code{nil}, commands -can only use the mark and the region when it is active. This variable -is non-@code{nil} by default. - - If you want to move back to the same place over and over, the mark -ring may not be convenient enough. If so, you can record the position -in a register for later retrieval (@pxref{RegPos,, Saving Positions in -Registers}). - -@node Global Mark Ring -@section The Global Mark Ring -@cindex global mark ring - - In addition to the ordinary mark ring that belongs to each buffer, -Emacs has a single @dfn{global mark ring}. Each time you set a mark, -in any buffer, this is recorded in the global mark ring in addition to -the current buffer's own mark ring. - -@kindex C-x C-@key{SPC} -@findex pop-global-mark - The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to -the buffer and position of the latest entry in the global ring. It also -rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take -you to earlier buffers and mark positions. - -@node Shift Selection -@section Shift Selection -@cindex shift-selection - - If you hold down the shift key while typing a cursor motion command, -this sets the mark before moving point, so that the region extends -from the original position of point to its new position. This -feature, newly introduced in Emacs 23, is referred to as -@dfn{shift-selection}. It is similar to the way text is selected in -other editors. - - The mark set via shift-selection behaves a little differently from -what we have described above. Firstly, in addition to the usual ways -of deactivating the mark (such as changing the buffer text or typing -@kbd{C-g}), the mark is deactivated by any @emph{unshifted} cursor -motion command. Secondly, any subsequent @emph{shifted} cursor motion -command avoids setting the mark anew. Therefore, a series of shifted -cursor motion commands will continuously extend the region. - - Shift-selection only works if the shifted cursor motion key is not -already bound to a separate command (@pxref{Customization}). For -example, if you bind @kbd{S-C-f} to another command, typing -@kbd{S-C-f} runs that command instead of performing a shift-selected -version of @kbd{C-f} (@code{forward-char}). - - A mark set via mouse commands behaves the same as a mark set via -shift-selection (@pxref{Setting Mark}). For example, if you specify a -region by dragging the mouse, you can continue to extend the region -using shifted cursor motion commands. In either case, any unshifted -cursor motion command deactivates the mark. - - To turn off shift-selection, set @code{shift-select-mode} to -@code{nil}. Doing this does not disable setting the mark via mouse -commands. - -@node Persistent Mark -@section Persistent Marks -@cindex mode, Transient Mark -@cindex Transient Mark mode -@cindex highlighting region -@cindex region highlighting -@cindex Zmacs mode - - By default, the mark is activated by setting it, and deactivated by -most non-motion commands (including all commands that change the text -in the buffer). This behavior is called Transient Mark -mode@footnote{It is also sometimes called @dfn{Zmacs mode}, because -the Zmacs editor on the MIT Lisp Machine handled the mark in a similar -way.}. - - Turning off Transient Mark mode switches Emacs to an alternative -mode of operation, which was the default prior to Emacs 23. When -Transient Mark mode is off, the mark is @emph{never} deactivated, but -it can be set to different locations using commands such as -@kbd{C-@key{SPC}}. Emacs does not highlight the region, because that -would be a nuisance. As a special exception, the region is -temporarily highlighted if you set it with the mouse (@pxref{Setting -Mark}), or with shift-selection (@pxref{Shift Selection}). - -@findex transient-mark-mode - To turn off Transient Mark mode, type @kbd{M-x transient-mark-mode}. -This command toggles the mode; you can use the same command to turn -Transient Mark mode on again. You can also turn off Transient Mark -mode using the menu bar: in the @samp{Options} menu, toggle the -@samp{Active Region Highlighting} menu item. - - Here are the details of how Emacs behaves when Transient Mark mode -is off: - -@itemize @bullet -@item -Emacs does not show where the mark is located---you have to remember. -The usual solution to this problem is to set the mark and then use it -soon, before you forget where it is. Alternatively, you can check the -location of the mark by using @kbd{C-x C-x}, which exchanges the -positions of the point and the mark (@pxref{Setting Mark}). - -@item -Many commands that insert text, such as @kbd{C-y} (@code{yank}), -position point and the mark at opposite ends of the inserted text, so -that the region consists of the text just inserted. You can tell when -a command sets the mark because it displays @samp{Mark set} in the -echo area. - -@item -Many commands that move point long distances, like @kbd{M-<} and -@kbd{C-s}, first set the mark where point was. - -@item -Some commands, which ordinarily operate on the region when the mark is -active, instead act on the entire buffer. For instance, @kbd{C-x u} -normally reverses changes within the region if the mark is active; -when Transient Mark mode is off, it acts on the entire buffer. -However, you can type @kbd{C-u C-x u} to make it operate on the -region. @xref{Undo}. Other commands that act this way are identified -in their own documentation. -@end itemize - - While Transient Mark mode is off, you can activate it temporarily -using @kbd{C-@key{SPC} C-@key{SPC}} or @kbd{C-u C-x C-x}. - -@table @kbd -@item C-@key{SPC} C-@key{SPC} -@kindex C-@key{SPC} C-@key{SPC} -Set the mark at point (like plain @kbd{C-@key{SPC}}) and enable -Transient Mark mode just once, until the mark is deactivated. (This -is not really a separate command; you are using the @kbd{C-@key{SPC}} -command twice.) - -@item C-u C-x C-x -@kindex C-u C-x C-x -Activate the mark without changing it; enable Transient Mark mode just -once, until the mark is deactivated. (This is the @kbd{C-x C-x} -command, @code{exchange-point-and-mark}, with a prefix argument.) -@end table - - These commands set or activate the mark, and enable Transient Mark -mode only until the mark is deactivated. One reason you may want to -use them is that some commands operate on the entire buffer instead of -the region when Transient Mark mode is off. Enabling Transient Mark -mode momentarily gives you a way to use these commands on the region. - -@ignore - arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 -@end ignore diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi deleted file mode 100644 index 37d483d3f9d..00000000000 --- a/doc/emacs/mini.texi +++ /dev/null @@ -1,658 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Minibuffer, M-x, Basic, Top -@chapter The Minibuffer -@cindex minibuffer - - The @dfn{minibuffer} is where Emacs commands read complicated -arguments, such as file names, buffer names, Emacs command names, or -Lisp expressions. We call it the ``minibuffer'' because it's a -special-purpose buffer with a small amount of screen space. You can -use the usual Emacs editing commands in the minibuffer to edit the -argument text. - -@cindex prompt - When the minibuffer is in use, it appears in the echo area, with a -cursor. The minibuffer display starts with a @dfn{prompt} in a -distinct color, usually ending with a colon. The prompt states what -kind of input is expected, and how it will be used. - - The simplest way to enter a minibuffer argument is to type the text, -then @key{RET} to submit the argument and exit the minibuffer. You -can cancel the minibuffer, and the command that wants the argument, by -typing @kbd{C-g}. - -@cindex default argument - Sometimes, a @dfn{default argument} appears in the prompt, inside -parentheses before the colon. The default will be used as the -argument value if you just type @key{RET}. For example, commands that -read buffer names usually show a buffer name as the default; you can -type @key{RET} to operate on that default buffer. - - Since the minibuffer appears in the echo area, it can conflict with -other uses of the echo area. If an error occurs while the minibuffer -is active, the error message hides the minibuffer for a few seconds, -or until you type something; then the minibuffer comes back. If a -command such as @kbd{C-x =} needs to display a message in the echo -area, the message hides the minibuffer for a few seconds, or until you -type something; then the minibuffer comes back. While the minibuffer -is in use, keystrokes do not echo. - -@menu -* Minibuffer File:: Entering file names with the minibuffer. -* Minibuffer Edit:: How to edit in the minibuffer. -* Completion:: An abbreviation facility for minibuffer input. -* Minibuffer History:: Reusing recent minibuffer arguments. -* Repetition:: Re-executing commands that used the minibuffer. -* Passwords:: Entering passwords in the echo area. -@end menu - -@node Minibuffer File -@section Minibuffers for File Names - - Commands such as @kbd{C-x C-f} (@code{find-file}) use the minibuffer -to read a file name argument (@pxref{Basic Files}). When the -minibuffer is used to read a file name, it typically starts out with -some initial text ending in a slash. This is the @dfn{default -directory}. For example, it may start out like this: - -@example -Find File: /u2/emacs/src/ -@end example - -@noindent -Here, @samp{Find File:@: } is the prompt and @samp{/u2/emacs/src/} is -the default directory. If you now type @kbd{buffer.c} as input, that -specifies the file @file{/u2/emacs/src/buffer.c}. @xref{File Names}, -for information about the default directory. - - You can specify the parent directory by adding @file{..}: for -example, @file{/u2/emacs/src/../lisp/simple.el} is equivalent to -@file{/u2/emacs/lisp/simple.el}. Alternatively, you can use -@kbd{M-@key{DEL}} to kill directory names backwards (@pxref{Words}). - - To specify a file in a completely different directory, you can kill -the entire default with @kbd{C-a C-k} (@pxref{Minibuffer Edit}). -Alternatively, you can ignore the default, and enter an absolute file -name starting with a slash or a tilde after the default directory. -For example, you can specify @file{/etc/termcap} as follows: - -@example -Find File: /u2/emacs/src//etc/termcap -@end example - -@noindent -@cindex // in file name -@cindex double slash in file name -@cindex slashes repeated in file name -@findex file-name-shadow-mode -Emacs interprets a double slash as ``ignore everything before the -second slash in the pair.'' In the example above, -@file{/u2/emacs/src/} is ignored, so the argument you supplied is -@file{/etc/termcap}. The ignored part of the file name is dimmed if -the terminal allows it (to disable this dimming, turn off File Name -Shadow mode with the command @kbd{M-x file-name-shadow-mode}.) - -@cindex home directory shorthand - Emacs interprets @file{~/} as your home directory. Thus, -@file{~/foo/bar.txt} specifies a file named @file{bar.txt}, inside a -directory named @file{foo}, which is in turn located in your home -directory. In addition, @file{~@var{user-id}/} means the home -directory of a user whose login name is @var{user-id}. Any leading -directory name in front of the @file{~} is ignored: thus, -@file{/u2/emacs/~/foo/bar.txt} is equivalent to @file{~/foo/bar.txt}. - - On MS-Windows and MS-DOS systems, where a user doesn't always have a -home directory, Emacs uses several alternatives. For MS-Windows, see -@ref{Windows HOME}; for MS-DOS, see -@ifnottex -@ref{MS-DOS File Names, HOME on MS-DOS}. -@end ifnottex -@iftex -@ref{MS-DOS File Names, HOME on MS-DOS,, emacs, the Emacs Manual}, in -the main Emacs manual. -@end iftex -On these systems, the @file{~@var{user-id}/} construct is supported -only for the current user, i.e., only if @var{user-id} is the current -user's login name. - -@vindex insert-default-directory - To prevent Emacs from inserting the default directory when reading -file names, change the variable @code{insert-default-directory} to -@code{nil}. In that case, the minibuffer starts out empty. -Nonetheless, relative file name arguments are still interpreted based -on the same default directory. - -@node Minibuffer Edit -@section Editing in the Minibuffer - - The minibuffer is an Emacs buffer, albeit a peculiar one, and the -usual Emacs commands are available for editing the argument text. -(The prompt, however, is @dfn{read-only}, and cannot be changed.) - - Since @key{RET} in the minibuffer is defined to exit the minibuffer, -you can't use it to insert a newline in the minibuffer. To do that, -type @kbd{C-o} or @kbd{C-q C-j}. (The newline character is really the -@acronym{ASCII} character control-J.) - - Inside a minibuffer, the keys @kbd{@key{TAB}}, @kbd{@key{SPC}}, and -@kbd{@key{?}} are often bound to commands that perform -@dfn{completion}. @xref{Completion}. You can use @kbd{C-q} -(@code{quoted-insert}) to insert a @key{TAB}, @key{SPC}, or @key{?} -character. For example, @kbd{C-q @key{TAB}} inserts a @key{TAB} -character. @xref{Inserting Text}. - - For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a -minibuffer moves point to the beginning of the argument text, not the -beginning of the prompt. For example, this allows you to erase the -entire argument with @kbd{C-a C-k}. - -@cindex height of minibuffer -@cindex size of minibuffer -@cindex growing minibuffer -@cindex resizing minibuffer - When the minibuffer is active, the echo area is treated much like an -ordinary Emacs window. For instance, you can switch to another window -(with @kbd{C-x o}), edit text there, then return to the minibuffer -window to finish the argument. You can even kill text in another -window, return to the minibuffer window, and yank the text into the -argument. There are some restrictions on the minibuffer window, -however: for instance, you cannot split it. @xref{Windows}. - -@vindex resize-mini-windows - Normally, the minibuffer window occupies a single screen line. -However, if you add two or more lines' worth of text into the -minibuffer, it expands automatically to accomodate the text. The -variable @code{resize-mini-windows} controls the resizing of the -minibuffer. The default value is @code{grow-only}, which means the -behavior we have just described. If the value is @code{t}, the -minibuffer window will also shrink automatically if you remove some -lines of text from the minibuffer, down to a minimum of one screen -line. If the value is @code{nil}, the minibuffer window never changes -size automatically, but you can use the usual window-resizing commands -on it (@pxref{Windows}). - -@vindex max-mini-window-height - The variable @code{max-mini-window-height} controls the maximum -height for resizing the minibuffer window. A floating-point number -specifies a fraction of the frame's height; an integer specifies the -maximum number of lines; @code{nil} means do not resize the minibuffer -window automatically. The default value is 0.25. - - The @kbd{C-M-v} command in the minibuffer scrolls the help text from -commands that display help text of any sort in another window. You -can also scroll the help text with @kbd{M-@key{prior}} and -@kbd{M-@key{next}} (or, equivalently, @kbd{M-@key{PageUp}} and -@kbd{M-@key{PageDown}}). This is especially useful with long lists of -possible completions. @xref{Other Window}. - -@vindex enable-recursive-minibuffers - Emacs normally disallows most commands that use the minibuffer while -the minibuffer is active. To allow such commands in the minibuffer, -set the variable @code{enable-recursive-minibuffers} to @code{t}. - -@node Completion -@section Completion -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. -@cindex completion - - Sometimes, you can use a feature called @dfn{completion} to help you -enter arguments. This means that after you type part of the argument, -Emacs can fill in the rest, or some of it, based on what you have -typed so far. - - When completion is available, certain keys (usually @key{TAB}, -@key{RET}, and @key{SPC}) are rebound to complete the text in the -minibuffer into a longer string chosen from a set of @dfn{completion -alternatives}. The set of completion alternatives depends on the -command that requested the argument, and on what you have typed so -far. In addition, you can usually type @kbd{?} to display a list of -possible completions. - - For example, @kbd{M-x} uses the minibuffer to read the name of a -command, so completion works by matching the minibuffer text against -the names of existing Emacs commands. So, to run the command -@code{insert-buffer}, you can type @kbd{M-x ins @key{SPC} b @key{RET}} -instead of the full @kbd{M-x insert-buffer @key{RET}}. - - Case is significant in completion when it is significant in the -argument you are entering, such as command names. Thus, -@samp{insert-buffer} is not a valid completion for @samp{IN}. -Completion ignores case distinctions for certain arguments in which -case does not matter. - -@menu -* Example: Completion Example. Examples of using completion. -* Commands: Completion Commands. A list of completion commands. -* Strict Completion:: Different types of completion. -* Options: Completion Options. Options for completion. -@end menu - -@node Completion Example -@subsection Completion Example - -@kindex TAB @r{(completion)} - A concrete example may help here. If you type @kbd{M-x a u -@key{TAB}}, the @key{TAB} looks for alternatives (in this case, -command names) that start with @samp{au}. There are several, -including @code{auto-fill-mode} and @code{autoconf-mode}, but they all -begin with @code{auto}, so the @samp{au} in the minibuffer completes -to @samp{auto}. - - If you type @key{TAB} again immediately, it cannot determine the -next character; it could be @samp{-}, @samp{a}, or @samp{c}. So it -does not add any characters; instead, @key{TAB} displays a list of all -possible completions in another window. - - Next, type @kbd{- f}. The minibuffer now contains @samp{auto-f}, -and the only command name that starts with this is -@code{auto-fill-mode}. If you now type @key{TAB}, completion fills in -the rest of the argument @samp{auto-fill-mode} into the minibuffer. -You have been able to enter @samp{auto-fill-mode} by typing just -@kbd{a u @key{TAB} - f @key{TAB}}. - -@node Completion Commands -@subsection Completion Commands - - Here is a list of the completion commands defined in the minibuffer -when completion is allowed. - -@table @kbd -@item @key{TAB} -@findex minibuffer-complete -Complete the text in the minibuffer as much as possible; if unable to -complete, display a list of possible completions -(@code{minibuffer-complete}). -@item @key{SPC} -Complete up to one word from the minibuffer text before point -(@code{minibuffer-complete-word}). @key{SPC} for completion is not -available when entering a file name, since file names often include -spaces. -@item @key{RET} -Submit the text in the minibuffer as the argument, possibly completing -first as described in the next -@iftex -subsection (@code{minibuffer-complete-and-exit}). -@end iftex -@ifnottex -node (@code{minibuffer-complete-and-exit}). @xref{Strict Completion}. -@end ifnottex -@item ? -Display a list of possible completions of the text before point -(@code{minibuffer-completion-help}). -@end table - -@kindex TAB -@findex minibuffer-complete - @key{TAB} (@code{minibuffer-complete}) is the most fundamental -completion command. It searches for all possible completion -alternatives that match the existing minibuffer text, and attempts to -complete as much as it can. The matching of completion alternatives -to the minibuffer text is performed according to somewhat intricate -rules, which are designed so that plausible completions are offered -under most circumstances. A valid completion alternative must satisfy -the following criteria: - -@itemize @bullet -@item -The minibuffer text before point must be the same as the beginning of -the completion alternative. If there is any minibuffer text after -point, it must be a substring of the remainder of the completion -alternative. - -@item -If no completion alternative satisfies the above rules, try using -@dfn{partial completion} rules: divide the minibuffer text into words -separated by hyphens or spaces, and complete each word separately. -Thus, when completing command names, @samp{em-l-m} completes to -@samp{emacs-lisp-mode}. - -@item -If there is still no completion alternative, try the first rule again, -but ignore the minibuffer text after point (i.e., don't try matching -it). -@end itemize - -@noindent -When performing these comparisons, a @samp{*} in the minibuffer text -acts as a @dfn{wildcard}---it matches any character at the -corresponding position in the completion alternative. - -@kindex SPC -@findex minibuffer-complete-word - @key{SPC} (@code{minibuffer-complete-word}) completes like -@key{TAB}, but only up to the next hyphen or space. If you have -@samp{auto-f} in the minibuffer and type @key{SPC}, it finds that the -completion is @samp{auto-fill-mode}, but it only inserts @samp{ill-}, -giving @samp{auto-fill-}. Another @key{SPC} at this point completes -all the way to @samp{auto-fill-mode}. - - If @key{TAB} or @key{SPC} is unable to complete, it displays a list -of possible completions (if there are any) in a separate window. You -can choose a completion from this list using the following commands: - -@table @kbd -@findex mouse-choose-completion -@item Mouse-1 -@itemx Mouse-2 -Clicking mouse button 1 or 2 on a completion possibility chooses that -completion (@code{mouse-choose-completion}). - -@findex switch-to-completions -@item M-v -@itemx @key{PageUp} -@itemx @key{prior} -Typing @kbd{M-v}, while in the minibuffer, selects the window showing -the completion list buffer (@code{switch-to-completions}). This paves -the way for using the commands below. Typing @key{PageUp} or -@key{prior} does the same, as does selecting that window in other -ways. - -@findex choose-completion -@item @key{RET} -Typing @key{RET}, while in the completion list buffer, chooses the -completion that point is in or next to (@code{choose-completion}). To -use this command, you must first switch to the completion list window. - -@findex next-completion -@item @key{Right} -Typing the right-arrow key @key{Right}, while in the completion list -buffer, moves point to the following completion possibility -(@code{next-completion}). - -@findex previous-completion -@item @key{Left} -Typing the left-arrow key @key{Left}, while in the completion list -buffer, moves point to the previous completion possibility -(@code{previous-completion}). -@end table - -@node Strict Completion -@subsection Strict Completion - - There are three different ways that @key{RET} can do completion, -depending on how the argument will be used. - -@itemize @bullet -@item -@dfn{Strict} completion accepts only known completion candidates. For -example, when @kbd{C-x k} reads the name of a buffer to kill, only the -name of an existing buffer makes sense. In strict completion, -@key{RET} refuses to exit if the text in the minibuffer does not -complete to an exact match. - -@item -@dfn{Cautious} completion is similar to strict completion, except that -@key{RET} exits only if the text is an already exact match. -Otherwise, @key{RET} does not exit, but it does complete the text. If -that completes to an exact match, a second @key{RET} will exit. - -Cautious completion is used for reading file names for files that must -already exist, for example. - -@item -@dfn{Permissive} completion allows any input; the completion -candidates are just suggestions. For example, when @kbd{C-x C-f} -reads the name of a file to visit, any file name is allowed, including -nonexistent file (in case you want to create a file). In permissive -completion, @key{RET} does not complete, it just submits the argument -as you have entered it. -@end itemize - - The completion commands display a list of all possible completions -whenever they can't determine even one more character by completion. -Also, typing @kbd{?} explicitly requests such a list. You can scroll -the list with @kbd{C-M-v} (@pxref{Other Window}). - -@node Completion Options -@subsection Completion Options - -@vindex completion-auto-help - If @code{completion-auto-help} is set to @code{nil}, the completion -commands never display the completion list buffer; you must type -@kbd{?} to display the list. If the value is @code{lazy}, Emacs only -shows the completion list buffer on the second attempt to complete. -In other words, if there is nothing to complete, the first @key{TAB} -echoes @samp{Next char not unique}; the second @key{TAB} does the -completion list buffer. - -@vindex completion-ignored-extensions -@cindex ignored file names, in completion - When completing file names, certain file names are usually ignored. -The variable @code{completion-ignored-extensions} contains a list of -strings; a file name ending in any of those strings is ignored as a -completion candidate. The standard value of this variable has several -elements including @code{".o"}, @code{".elc"}, and @code{"~"}. For -example, if a directory contains @samp{foo.c} and @samp{foo.elc}, -@samp{foo} completes to @samp{foo.c}. However, if @emph{all} possible -completions end in ``ignored'' strings, they are not ignored: in the -previous example, @samp{foo.e} completes to @samp{foo.elc}. -Displaying a list of possible completions disregards -@code{completion-ignored-extensions}; it shows them all. - - If an element of @code{completion-ignored-extensions} ends in a -slash (@file{/}), it's a subdirectory name; that directory and its -contents are ignored. Elements of -@code{completion-ignored-extensions} that do not end in a slash are -ordinary file names. - -@cindex case-sensitivity and completion -@vindex read-file-name-completion-ignore-case -@vindex read-buffer-completion-ignore-case - When completing file names, Emacs ignores case differences if the -variable @code{read-file-name-completion-ignore-case} is -non-@code{nil}. The default value is @code{nil} on systems that have -case-sensitive file-names, such as GNU/Linux; it is non-@code{nil} on -systems that have case-insensitive file-names, such as Microsoft -Windows. When completing buffer names, Emacs ignores case differences -if @code{read-buffer-completion-ignore-case} is non-@code{nil} (the -default value is @code{nil}). - -@vindex completion-styles - You can customize the matching rules for completion alternatives -using the variable @code{completion-styles}. Its value should be a -list of symbols, each representing a @dfn{completion style}; valid -style symbols are @code{basic}, @code{partial-completion}, -@code{emacs22}, and @code{emacs21}. When completing, Emacs attempts -to use the first completion style in the list; if this does not return -any completion alternatives, it tries the next completion style in the -list, and so on. The completion rules described in @ref{Completion -Commands} correspond to the default value of @code{completion-styles}, -which is @code{(basic partial-completion emacs22)}. - -@cindex Icomplete mode -@findex icomplete-mode - Icomplete mode presents a constantly-updated display that tells you -what completions are available for the text you've entered so far. The -command to enable or disable this minor mode is @kbd{M-x -icomplete-mode}. - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history of minibuffer input - - Every argument that you enter with the minibuffer is saved in a -@dfn{minibuffer history list} so you can easily use it again later. -You can use the following arguments to quickly fetch an earlier -argument into the minibuffer: - -@table @kbd -@item M-p -@itemx @key{Up} -Move to the previous item in the minibuffer history, an earlier -argument (@code{previous-history-element}). -@item M-n -@itemx @key{Down} -Move to the next item in the minibuffer history -(@code{next-history-element}). -@item M-r @var{regexp} @key{RET} -Move to an earlier item in the minibuffer history that -matches @var{regexp} (@code{previous-matching-history-element}). -@item M-s @var{regexp} @key{RET} -Move to a later item in the minibuffer history that matches -@var{regexp} (@code{next-matching-history-element}). -@end table - -@kindex M-p @r{(minibuffer history)} -@kindex M-n @r{(minibuffer history)} -@findex next-history-element -@findex previous-history-element - While in the minibuffer, typing @kbd{M-p} or @key{Up} -(@code{previous-history-element}) moves up through the minibuffer -history list, one item at a time. Each @kbd{M-p} fetches an earlier -item from the history list into the minibuffer, replacing its existing -contents. Similarly, typing @kbd{M-n} or @key{Down} -(@code{next-history-element}) moves back down the history list, -fetching later entries into the minibuffer. You can think of these -commands as ``backwards'' and ``forwards'' through the history list. - - If you type @kbd{M-n} in the minibuffer when there are no later -entries in the minibuffer history (e.g., if you haven't previously -typed @kbd{M-p}), Emacs tries fetching from a list of default -argument: values that you are likely to enter. You can think of this -as moving through the ``future list'' instead of the ``history list''. - - The input that @kbd{M-p} or @kbd{M-n} fetches into the minibuffer -entirely replaces the existing contents of the minibuffer, so you can -simply type @key{RET} to use it as an argument. You can also edit the -text before you reuse it; this does not change the history element -that you ``moved'' to, but your new argument does go at the end of the -history list in its own right. - -@findex previous-matching-history-element -@findex next-matching-history-element -@kindex M-r @r{(minibuffer history)} -@kindex M-s @r{(minibuffer history)} - There are also commands to search forward or backward through the -history; they search for history elements that match a regular -expression. @kbd{M-r} (@code{previous-matching-history-element}) -searches older elements in the history, while @kbd{M-s} -(@code{next-matching-history-element}) searches newer elements. These -commands are unusual: they use the minibuffer to read the regular -expression even though they are invoked from the minibuffer. As with -incremental searching, an upper-case letter in the regular expression -makes the search case-sensitive (@pxref{Search Case}). You can also -search through the history using an incremental search (@pxref{Isearch -Minibuffer}). - - All uses of the minibuffer record your input on a history list, but -there are separate history lists for different kinds of arguments. -For example, there is a list for file names, used by all the commands -that read file names. (As a special feature, this history list -records the absolute file name, even if the name you entered was not -absolute.) - - There are several other specific history lists, including one for -buffer names, one for arguments of commands like @code{query-replace}, -one used by @kbd{M-x} for command names, and one used by -@code{compile} for compilation commands. Finally, there is one -``miscellaneous'' history list that most minibuffer arguments use. - -@vindex history-length - The variable @code{history-length} specifies the maximum length of a -minibuffer history list; adding a new element deletes the oldest -element if the list gets too long. If the value of -@code{history-length} is @code{t}, there is no maximum length. - -@vindex history-delete-duplicates - The variable @code{history-delete-duplicates} specifies whether to -delete duplicates in history. If it is non-@code{nil}, adding a new -element deletes from the list all other elements that are equal to it. -The default is @code{nil}. - -@node Repetition -@section Repeating Minibuffer Commands -@cindex command history -@cindex history of commands - - Every command that uses the minibuffer once is recorded on a special -history list, the @dfn{command history}, together with the values of -its arguments, so that you can repeat the entire command. In -particular, every use of @kbd{M-x} is recorded there, since @kbd{M-x} -uses the minibuffer to read the command name. - -@findex list-command-history -@table @kbd -@item C-x @key{ESC} @key{ESC} -Re-execute a recent minibuffer command from the command history - (@code{repeat-complex-command}). -@item M-x list-command-history -Display the entire command history, showing all the commands -@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. -@end table - -@kindex C-x ESC ESC -@findex repeat-complex-command - @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent command -that used the minibuffer. With no argument, it repeats the last such -command. A numeric argument specifies which command to repeat; 1 -means the last one, 2 the previous, and so on. - - @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command -into a Lisp expression and then entering a minibuffer initialized with -the text for that expression. Even if you don't understand Lisp -syntax, it will probably be obvious which command is displayed for -repetition. If you type just @key{RET}, that repeats the command -unchanged. You can also change the command by editing the Lisp -expression before you execute it. The repeated command is added to -the front of the command history unless it is identical to the most -recently item. - - Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can -use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, -@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list -of saved entire commands. After finding the desired previous command, -you can edit its expression as usual and then repeat it by typing -@key{RET}. - -@vindex isearch-resume-in-command-history - Incremental search does not, strictly speaking, use the minibuffer. -Therefore, although it behaves like a complex command, it normally -does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. -You can make incremental search commands appear in the history by -setting @code{isearch-resume-in-command-history} to a non-@code{nil} -value. @xref{Incremental Search}. - -@vindex command-history - The list of previous minibuffer-using commands is stored as a Lisp -list in the variable @code{command-history}. Each element is a Lisp -expression which describes one command and its arguments. Lisp programs -can re-execute a command by calling @code{eval} with the -@code{command-history} element. - -@node Passwords -@section Entering passwords - -Sometimes, you may need to enter a password into Emacs. For instance, -when you tell Emacs to visit a file on another machine via a network -protocol such as FTP, you often need to supply a password to gain -access to the machine (@pxref{Remote Files}). - - Entering a password is, in a basic sense, similar to using a -minibuffer. Emacs displays a prompt in the echo area (such as -@samp{Password: }); after you type the required password, press -@key{RET} to submit it. To prevent others from seeing your password, -every character you type is displayed as a dot (@samp{.}) instead of -its usual form. - - Most of the features and commands associated with the minibuffer can -@emph{not} be used when entering a password. There is no history or -completion, and you cannot change windows or perform any other action -with Emacs until you have submitted the password. - - While you are typing the password, you may press @key{DEL} to delete -backwards, removing the last character entered. @key{C-u} deletes -everything you have typed so far. @kbd{C-g} quits the password prompt -(@pxref{Quitting}). @kbd{C-y} inserts the current kill into the -password (@pxref{Killing}). You may type either @key{RET} or -@key{ESC} to submit the password. Any other self-inserting character -key inserts the associated character into the password, and all other -input is ignored. - -@ignore - arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f -@end ignore diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi deleted file mode 100644 index 29f7f271350..00000000000 --- a/doc/emacs/misc.texi +++ /dev/null @@ -1,2852 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Miscellaneous Commands - - This chapter contains several brief topics that do not fit anywhere -else: viewing ``document files'', reading netnews, running shell -commands and shell subprocesses, using a single shared Emacs for -utilities that expect to run an editor as a subprocess, printing -hardcopy, sorting text, narrowing display to part of the buffer, -editing double-column files and binary files, saving an Emacs session -for later resumption, following hyperlinks, browsing images, emulating -other editors, and various diversions and amusements. - -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Document View, Gnus, Calendar/Diary, Top -@section Document Viewing -@cindex DVI file -@cindex PDF file -@cindex PS file -@cindex Postscript file -@cindex DocView mode -@cindex mode, DocView -@cindex document viewer (DocView) -@findex doc-view-mode - -DocView mode (@code{doc-view-mode}) is a viewer for DVI, Postscript -(PS), and PDF documents. It provides features such as slicing, -zooming, and searching inside documents. It works by converting the -document to a set of images using the @command{gs} (GhostScript) -command, and displaying those images. - -@findex doc-view-toggle-display -@findex doc-view-toggle-display -@cindex doc-view-minor-mode - When you visit a PDF or DVI file, Emacs automatically switches to -DocView mode. When you visit a Postscript file, Emacs switches to PS -mode, a major mode for editing Postscript files as text; however, it -also enables DocView minor mode, so you can type @kbd{C-c C-c} to view -the document with DocView. (PDF and DVI files, unlike Postscript -files, are not usually human-editable.) In either case, repeating -@kbd{C-c C-c} (@code{doc-view-toggle-display}) toggles between DocView -and the file text. - - You can explicitly toggle DocView mode with the command @code{M-x -doc-view-mode}, and DocView minor mode with the command @code{M-x -doc-view-minor-mode}. - - When DocView mode starts, it displays a welcome screen and begins -formatting the file, page by page. It displays the first page once -that has been formatted. - -@findex doc-view-enlarge -@findex doc-view-shrink -@vindex doc-view-resolution - When in DocView mode, you can enlarge or shrink the document with -@kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}). To specify the default size for DocView, -set or customize the variable @code{doc-view-resolution}. - - To kill the DocView buffer, type @kbd{k} -(@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} -(@code{quit-window}). - -@menu -* Navigation:: Navigation inside DocView buffers. -* Searching:: Searching inside documents. -* Slicing:: Specifying which part of pages should be displayed. -* Conversion:: Influencing and triggering conversion. -@end menu - -@node Navigation -@subsection Navigation - -When in DocView mode, you can scroll the current page using the usual -Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and -the arrow keys. - -@findex doc-view-next-page -@findex doc-view-previous-page - To display the next page, type @kbd{n}, @key{next} or @kbd{C-x ]} -(@code{doc-view-next-page}). To display the previous page, type -@kbd{p}, @key{prior} or @kbd{C-x [} (@code{doc-view-previous-page}). - -@findex doc-view-scroll-up-or-next-page -@findex doc-view-scroll-down-or-previous-page - The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a -convenient way to advance through the document. It scrolls within the -current page or advances to the next. @key{DEL} moves backwards in a -similar way (@code{doc-view-scroll-down-or-previous-page}). - -@findex doc-view-first-page -@findex doc-view-last-page -@findex doc-view-goto-page - To go to the first page, type @kbd{M-<} -(@code{doc-view-first-page}); to go to the last one, type @kbd{M->} -(@code{doc-view-last-page}). To jump to a page by its number, type -@kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). - -@node Searching -@subsection Searching - -While in DocView mode, you can search the file's text for a regular -expression (@pxref{Regexps}). The interface for searching is inspired -by @code{isearch} (@pxref{Incremental Search}). - -@findex doc-view-search -@findex doc-view-search-backward -@findex doc-view-show-tooltip - To begin a search, type @kbd{C-s} (@code{doc-view-search}) or -@kbd{C-r} (@code{doc-view-search-backward}). This reads a regular -expression using a minibuffer, then echoes the number of matches found -within the document. You can move forward and back among the matches -by typing @kbd{C-s} and @kbd{C-r}. DocView mode has no way to show -the match inside the page image; instead, it displays a tooltip (at -the mouse position) listing all matching lines in the current page. -To force display of this tooltip, type @kbd{C-t} -(@code{doc-view-show-tooltip}). - - To start a new search, use the search command with a prefix -argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} -for a backward search. - -@node Slicing -@subsection Slicing - -Documents often have wide margins for printing. They are annoying -when reading the document on the screen, because they use up screen -space and can cause inconvenient scrolling. - -@findex doc-view-set-slice -@findex doc-view-set-slice-using-mouse - With DocView you can hide these margins by selecting a @dfn{slice} -of pages to display. A slice is a rectangle within the page area; -once you specify a slice in DocView, it applies to whichever page you -look at. - - To specify the slice numerically, type @kbd{s s} -(@code{doc-view-set-slice}); then enter the top left pixel position -and the slice's width and height. -@c ??? how does this work? - - A more convenient graphical way to specify the slice is with @kbd{s -m} (@code{doc-view-set-slice-using-mouse}), where you use the mouse to -select the slice. -@c ??? How does this work? - -@findex doc-view-reset-slice - To cancel the selected slice, type @kbd{s r} -(@code{doc-view-reset-slice}). Then DocView shows the entire page -including its entire margins. - -@node Conversion -@subsection Conversion - -@vindex doc-view-cache-directory -@findex doc-view-clear-cache -For efficiency, DocView caches the images produced by @command{gs}. -The name of this directory is given by the variable -@code{doc-view-cache-directory}. You can clear the cache directory by -typing @code{M-x doc-view-clear-cache}. - -@findex doc-view-kill-proc -@findex doc-view-kill-proc-and-buffer - To force a reconversion of the currently viewed document, type -@kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter -process associated with the current buffer, type @kbd{K} -(@code{doc-view-kill-proc}). The command @kbd{k} -(@code{doc-view-kill-proc-and-buffer}) kills the converter process and -the DocView buffer. - - The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}) need to reconvert the document at the new -size. The current page is converted first. - -@node Gnus, Shell, Document View, Top -@section Gnus -@cindex Gnus -@cindex reading netnews - -Gnus is an Emacs package primarily designed for reading and posting -Usenet news. It can also be used to read and respond to messages from a -number of other sources---mail, remote directories, digests, and so on. -Here we introduce Gnus and describe several basic features. -@ifnottex -For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. -@end ifnottex -@iftex -For full details on Gnus, type @kbd{M-x info} and then select the Gnus -manual. -@end iftex - -@findex gnus -To start Gnus, type @kbd{M-x gnus @key{RET}}. - -@menu -* Buffers of Gnus:: The group, summary, and article buffers. -* Gnus Startup:: What you should know about starting Gnus. -* Summary of Gnus:: A short description of the basic Gnus commands. -@end menu - -@node Buffers of Gnus -@subsection Gnus Buffers - -Unlike most Emacs packages, Gnus uses several buffers to display -information and to receive commands. The three Gnus buffers users use -most are the @dfn{group buffer}, the @dfn{summary buffer} and the -@dfn{article buffer}. - -The @dfn{group buffer} contains a list of newsgroups. This is the -first buffer Gnus displays when it starts up. It normally displays -only the groups to which you subscribe and that contain unread -articles. Use this buffer to select a specific group. - -The @dfn{summary buffer} lists one line for each article in a single -group. By default, the author, the subject and the line number are -displayed for each article, but this is customizable, like most aspects -of Gnus display. The summary buffer is created when you select a group -in the group buffer, and is killed when you exit the group. Use this -buffer to select an article. - -The @dfn{article buffer} displays the article. In normal Gnus usage, -you see this buffer but you don't select it---all useful -article-oriented commands work in the summary buffer. But you can -select the article buffer, and execute all Gnus commands from that -buffer, if you want to. - -@node Gnus Startup -@subsection When Gnus Starts Up - -At startup, Gnus reads your @file{.newsrc} news initialization file -and attempts to communicate with the local news server, which is a -repository of news articles. The news server need not be the same -computer you are logged in on. - -If you start Gnus and connect to the server, but do not see any -newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get -a listing of all the groups. Then type @kbd{u} to toggle -subscription to groups. - -The first time you start Gnus, Gnus subscribes you to a few selected -groups. All other groups start out as @dfn{killed groups} for you; you -can list them with @kbd{A k}. All new groups that subsequently come to -exist at the news server become @dfn{zombie groups} for you; type @kbd{A -z} to list them. You can subscribe to a group shown in these lists -using the @kbd{u} command. - -When you quit Gnus with @kbd{q}, it automatically records in your -@file{.newsrc} and @file{.newsrc.eld} initialization files the -subscribed or unsubscribed status of all groups. You should normally -not edit these files manually, but you may if you know how. - -@node Summary of Gnus -@subsection Summary of Gnus Commands - -Reading news is a two-step process: - -@enumerate -@item -Choose a group in the group buffer. - -@item -Select articles from the summary buffer. Each article selected is -displayed in the article buffer in a large window, below the summary -buffer in its small window. -@end enumerate - - Each Gnus buffer has its own special commands; the meanings of any -given key in the various Gnus buffers are usually analogous, even if -not identical. Here are commands for the group and summary buffers: - -@table @kbd -@kindex q @r{(Gnus Group mode)} -@findex gnus-group-exit -@item q -In the group buffer, update your @file{.newsrc} initialization file -and quit Gnus. - -In the summary buffer, exit the current group and return to the -group buffer. Thus, typing @kbd{q} twice quits Gnus. - -@kindex L @r{(Gnus Group mode)} -@findex gnus-group-list-all-groups -@item L -In the group buffer, list all the groups available on your news -server (except those you have killed). This may be a long list! - -@kindex l @r{(Gnus Group mode)} -@findex gnus-group-list-groups -@item l -In the group buffer, list only the groups to which you subscribe and -which contain unread articles. - -@kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group -@cindex subscribe groups -@cindex unsubscribe groups -@item u -In the group buffer, unsubscribe from (or subscribe to) the group listed -in the line that point is on. When you quit Gnus by typing @kbd{q}, -Gnus lists in your @file{.newsrc} file which groups you have subscribed -to. The next time you start Gnus, you won't see this group, -because Gnus normally displays only subscribed-to groups. - -@kindex C-k @r{(Gnus)} -@findex gnus-group-kill-group -@item C-k -In the group buffer, ``kill'' the current line's group---don't -even list it in @file{.newsrc} from now on. This affects future -Gnus sessions as well as the present session. - -When you quit Gnus by typing @kbd{q}, Gnus writes information -in the file @file{.newsrc} describing all newsgroups except those you -have ``killed.'' - -@kindex SPC @r{(Gnus)} -@findex gnus-group-read-group -@item @key{SPC} -In the group buffer, select the group on the line under the cursor -and display the first unread article in that group. - -@need 1000 -In the summary buffer, - -@itemize @bullet -@item -Select the article on the line under the cursor if none is selected. - -@item -Scroll the text of the selected article (if there is one). - -@item -Select the next unread article if at the end of the current article. -@end itemize - -Thus, you can move through all the articles by repeatedly typing @key{SPC}. - -@kindex DEL @r{(Gnus)} -@item @key{DEL} -In the group buffer, move point to the previous group containing -unread articles. - -@findex gnus-summary-prev-page -In the summary buffer, scroll the text of the article backwards. - -@kindex n @r{(Gnus)} -@findex gnus-group-next-unread-group -@findex gnus-summary-next-unread-article -@item n -Move point to the next unread group, or select the next unread article. - -@kindex p @r{(Gnus)} -@findex gnus-group-prev-unread-group -@findex gnus-summary-prev-unread-article -@item p -Move point to the previous unread group, or select the previous -unread article. - -@kindex C-n @r{(Gnus Group mode)} -@findex gnus-group-next-group -@kindex C-p @r{(Gnus Group mode)} -@findex gnus-group-prev-group -@kindex C-n @r{(Gnus Summary mode)} -@findex gnus-summary-next-subject -@kindex C-p @r{(Gnus Summary mode)} -@findex gnus-summary-prev-subject -@item C-n -@itemx C-p -Move point to the next or previous item, even if it is marked as read. -This does not select the article or group on that line. - -@kindex s @r{(Gnus Summary mode)} -@findex gnus-summary-isearch-article -@item s -In the summary buffer, do an incremental search of the current text in -the article buffer, just as if you switched to the article buffer and -typed @kbd{C-s}. - -@kindex M-s @r{(Gnus Summary mode)} -@findex gnus-summary-search-article-forward -@item M-s @var{regexp} @key{RET} -In the summary buffer, search forward for articles containing a match -for @var{regexp}. - -@end table - -@ignore -@node Where to Look -@subsection Where to Look Further - -@c Too many references to the name of the manual if done with xref in TeX! -Gnus is powerful and customizable. Here are references to a few -@ifnottex -additional topics: - -@end ifnottex -@iftex -additional topics in @cite{The Gnus Manual}: - -@itemize @bullet -@item -Follow discussions on specific topics.@* -See section ``Threading.'' - -@item -Read digests. See section ``Document Groups.'' - -@item -Refer to and jump to the parent of the current article.@* -See section ``Finding the Parent.'' - -@item -Refer to articles by using Message-IDs included in the messages.@* -See section ``Article Keymap.'' - -@item -Save articles. See section ``Saving Articles.'' - -@item -Have Gnus score articles according to various criteria, like author -name, subject, or string in the body of the articles.@* -See section ``Scoring.'' - -@item -Send an article to a newsgroup.@* -See section ``Composing Messages.'' -@end itemize -@end iftex -@ifnottex -@itemize @bullet -@item -Follow discussions on specific topics.@* -@xref{Threading, , Reading Based on Conversation Threads, -gnus, The Gnus Manual}. - -@item -Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. - -@item -Refer to and jump to the parent of the current article.@* -@xref{Finding the Parent, , , gnus, The Gnus Manual}. - -@item -Refer to articles by using Message-IDs included in the messages.@* -@xref{Article Keymap, , , gnus, The Gnus Manual}. - -@item -Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. - -@item -Have Gnus score articles according to various criteria, like author -name, subject, or string in the body of the articles.@* -@xref{Scoring, , , gnus, The Gnus Manual}. - -@item -Send an article to a newsgroup.@* -@xref{Composing Messages, , , gnus, The Gnus Manual}. -@end itemize -@end ifnottex -@end ignore - -@node Shell, Emacs Server, Gnus, Top -@section Running Shell Commands from Emacs -@cindex subshell -@cindex shell commands - - Emacs has commands for passing single command lines to inferior shell -processes; it can also run a shell interactively with input and output -to an Emacs buffer named @samp{*shell*} or run a shell inside a terminal -emulator window. - -@table @kbd -@item M-! @var{cmd} @key{RET} -Run the shell command line @var{cmd} and display the output -(@code{shell-command}). -@item M-| @var{cmd} @key{RET} -Run the shell command line @var{cmd} with region contents as input; -optionally replace the region with the output -(@code{shell-command-on-region}). -@item M-x shell -Run a subshell with input and output through an Emacs buffer. -You can then give commands interactively. -@item M-x term -Run a subshell with input and output through an Emacs buffer. -You can then give commands interactively. -Full terminal emulation is available. -@end table - - @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It -is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, -Eshell: The Emacs Shell}. - -@menu -* Single Shell:: How to run one shell command and return. -* Interactive Shell:: Permanent shell taking input via Emacs. -* Shell Mode:: Special Emacs commands used with permanent shell. -* Shell Prompts:: Two ways to recognize shell prompts. -* History: Shell History. Repeating previous commands in a shell buffer. -* Directory Tracking:: Keeping track when the subshell changes directory. -* Options: Shell Options. Options for customizing Shell mode. -* Terminal emulator:: An Emacs window as a terminal emulator. -* Term Mode:: Special Emacs commands used in Term mode. -* Paging in Term:: Paging in the terminal emulator. -* Remote Host:: Connecting to another computer. -* Serial Terminal:: Connecting to a serial port. -@end menu - -@node Single Shell -@subsection Single Shell Commands - -@kindex M-! -@findex shell-command - @kbd{M-!} (@code{shell-command}) reads a line of text using the -minibuffer and executes it as a shell command in a subshell made just -for that command. Standard input for the command comes from the null -device. If the shell command produces any output, the output appears -either in the echo area (if it is short), or in an Emacs buffer named -@samp{*Shell Command Output*}, which is displayed in another window -but not selected (if the output is long). - - For instance, one way to decompress a file @file{foo.gz} from Emacs -is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command -normally creates the file @file{foo} and produces no terminal output. - - A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal -output into the current buffer instead of a separate buffer. It puts -point before the output, and sets the mark after the output. For -instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the -uncompressed equivalent of @file{foo.gz} into the current buffer. - - If the shell command line ends in @samp{&}, it runs asynchronously. -For a synchronous shell command, @code{shell-command} returns the -command's exit status (0 means success), when it is called from a Lisp -program. You do not get any status information for an asynchronous -command, since it hasn't finished yet when @code{shell-command} returns. - -@kindex M-| -@findex shell-command-on-region - @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but -passes the contents of the region as the standard input to the shell -command, instead of no input. With a numeric argument, meaning insert -the output in the current buffer, it deletes the old region and the -output replaces it as the contents of the region. It returns the -command's exit status, like @kbd{M-!}. - - One use for @kbd{M-|} is to run @code{gpg} to see what keys are in -the buffer. For instance, if the buffer contains a GPG key, type -@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to -the @code{gpg} program. That program will ignore everything except -the encoded keys, and will output a list of the keys the buffer -contains. - -@vindex shell-file-name - Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify -the shell to use. This variable is initialized based on your -@env{SHELL} environment variable when Emacs is started. If the file -name is relative, Emacs searches the directories in the list -@code{exec-path}; this list is initialized based on the environment -variable @env{PATH} when Emacs is started. Your init file can -override either or both of these default initializations (@pxref{Init -File}). - - Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete, -unless you end the command with @samp{&} to make it asynchronous. To -stop waiting, type @kbd{C-g} to quit; that terminates the shell -command with the signal @code{SIGINT}---the same signal that @kbd{C-c} -normally generates in the shell. Emacs then waits until the command -actually terminates. If the shell command doesn't stop (because it -ignores the @code{SIGINT} signal), type @kbd{C-g} again; this sends -the command a @code{SIGKILL} signal which is impossible to ignore. - - Asynchronous commands ending in @samp{&} feed their output into -the buffer @samp{*Async Shell Command*}. Output arrives in that -buffer regardless of whether it is visible in a window. - - To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command -@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. - -@vindex shell-command-default-error-buffer - Error output from these commands is normally intermixed with the -regular output. But if the variable -@code{shell-command-default-error-buffer} has a string as value, and -it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output -before point in that buffer. - -@node Interactive Shell -@subsection Interactive Inferior Shell - -@findex shell - To run a subshell interactively, use @kbd{M-x shell}. This creates -(or reuses) a buffer named @samp{*shell*} and runs a subshell with -input coming from and output going to that buffer. That is to say, -any ``terminal output'' from the subshell goes into the buffer, -advancing point, and any ``terminal input'' for the subshell comes -from text in the buffer. To give input to the subshell, go to the end -of the buffer and type the input, terminated by @key{RET}. - - Emacs does not wait for the subshell to do anything. You can switch -windows or buffers and edit them while the shell is waiting, or while it is -running a command. Output from the subshell waits until Emacs has time to -process it; this happens whenever Emacs is waiting for keyboard input or -for time to elapse. - -@cindex @code{comint-highlight-input} face -@cindex @code{comint-highlight-prompt} face - Input lines, once you submit them, are displayed using the face -@code{comint-highlight-input}, and prompts are displayed using the -face @code{comint-highlight-prompt}. This makes it easier to see -previous input lines in the buffer. @xref{Faces}. - - To make multiple subshells, you can invoke @kbd{M-x shell} with a -prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer -name and create (or reuse) a subshell in that buffer. You can also -rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then -create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. -Subshells in different buffers run independently and in parallel. - -@vindex explicit-shell-file-name -@cindex environment variables for subshells -@cindex @env{ESHELL} environment variable -@cindex @env{SHELL} environment variable - The file name used to load the subshell is the value of the variable -@code{explicit-shell-file-name}, if that is non-@code{nil}. -Otherwise, the environment variable @env{ESHELL} is used, or the -environment variable @env{SHELL} if there is no @env{ESHELL}. If the -file name specified is relative, the directories in the list -@code{exec-path} are searched; this list is initialized based on the -environment variable @env{PATH} when Emacs is started. Your init file -can override either or both of these default initializations. -(@pxref{Init File}). - - Emacs sends the new shell the contents of the file -@file{~/.emacs_@var{shellname}} as input, if it exists, where -@var{shellname} is the name of the file that the shell was loaded -from. For example, if you use bash, the file sent to it is -@file{~/.emacs_bash}. If this file is not found, Emacs tries to fallback -on @file{~/.emacs.d/init_@var{shellname}.sh}. - - To specify a coding system for the shell, you can use the command -@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can -also change the coding system for a running subshell by typing -@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication -Coding}. - -@cindex @env{INSIDE_EMACS} environment variable - Emacs sets the environment variable @env{INSIDE_EMACS} in the -subshell to a comma-separated list including the Emacs version. -Programs can check this variable to determine whether they are running -inside an Emacs subshell. - -@cindex @env{EMACS} environment variable - Emacs also sets the @env{EMACS} environment variable (to @code{t}) if -it is not already defined. @strong{Warning:} This environment -variable is deprecated. Programs that check this variable should be -changed to check @env{INSIDE_EMACS} instead. - -@node Shell Mode -@subsection Shell Mode -@cindex Shell mode -@cindex mode, Shell - - Shell buffers use Shell mode, which defines several special keys -attached to the @kbd{C-c} prefix. They are chosen to resemble the usual -editing and job control characters present in shells that are not under -Emacs, except that you must type @kbd{C-c} first. Here is a complete list -of the special key bindings of Shell mode: - -@table @kbd -@item @key{RET} -@kindex RET @r{(Shell mode)} -@findex comint-send-input -At end of buffer send line as input; otherwise, copy current line to -end of buffer and send it (@code{comint-send-input}). Copying a line -in this way omits any prompt at the beginning of the line (text output -by programs preceding your input). @xref{Shell Prompts}, for how -Shell mode recognizes prompts. - -@item @key{TAB} -@kindex TAB @r{(Shell mode)} -@findex comint-dynamic-complete -Complete the command name or file name before point in the shell buffer -(@code{comint-dynamic-complete}). @key{TAB} also completes history -references (@pxref{History References}) and environment variable names. - -@vindex shell-completion-fignore -@vindex comint-completion-fignore -The variable @code{shell-completion-fignore} specifies a list of file -name extensions to ignore in Shell mode completion. The default -setting is @code{nil}, but some users prefer @code{("~" "#" "%")} to -ignore file names ending in @samp{~}, @samp{#} or @samp{%}. Other -related Comint modes use the variable @code{comint-completion-fignore} -instead. - -@item M-? -@kindex M-? @r{(Shell mode)} -@findex comint-dynamic-list-filename@dots{} -Display temporarily a list of the possible completions of the file name -before point in the shell buffer -(@code{comint-dynamic-list-filename-completions}). - -@item C-d -@kindex C-d @r{(Shell mode)} -@findex comint-delchar-or-maybe-eof -Either delete a character or send @acronym{EOF} -(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell -buffer, @kbd{C-d} sends @acronym{EOF} to the subshell. Typed at any other -position in the buffer, @kbd{C-d} deletes a character as usual. - -@item C-c C-a -@kindex C-c C-a @r{(Shell mode)} -@findex comint-bol-or-process-mark -Move to the beginning of the line, but after the prompt if any -(@code{comint-bol-or-process-mark}). If you repeat this command twice -in a row, the second time it moves back to the process mark, which is -the beginning of the input that you have not yet sent to the subshell. -(Normally that is the same place---the end of the prompt on this -line---but after @kbd{C-c @key{SPC}} the process mark may be in a -previous line.) - -@item C-c @key{SPC} -Accumulate multiple lines of input, then send them together. This -command inserts a newline before point, but does not send the preceding -text as input to the subshell---at least, not yet. Both lines, the one -before this newline and the one after, will be sent together (along with -the newline that separates them), when you type @key{RET}. - -@item C-c C-u -@kindex C-c C-u @r{(Shell mode)} -@findex comint-kill-input -Kill all text pending at end of buffer to be sent as input -(@code{comint-kill-input}). If point is not at end of buffer, -this only kills the part of this text that precedes point. - -@item C-c C-w -@kindex C-c C-w @r{(Shell mode)} -Kill a word before point (@code{backward-kill-word}). - -@item C-c C-c -@kindex C-c C-c @r{(Shell mode)} -@findex comint-interrupt-subjob -Interrupt the shell or its current subjob if any -(@code{comint-interrupt-subjob}). This command also kills -any shell input pending in the shell buffer and not yet sent. - -@item C-c C-z -@kindex C-c C-z @r{(Shell mode)} -@findex comint-stop-subjob -Stop the shell or its current subjob if any (@code{comint-stop-subjob}). -This command also kills any shell input pending in the shell buffer and -not yet sent. - -@item C-c C-\ -@findex comint-quit-subjob -@kindex C-c C-\ @r{(Shell mode)} -Send quit signal to the shell or its current subjob if any -(@code{comint-quit-subjob}). This command also kills any shell input -pending in the shell buffer and not yet sent. - -@item C-c C-o -@kindex C-c C-o @r{(Shell mode)} -@findex comint-delete-output -Delete the last batch of output from a shell command -(@code{comint-delete-output}). This is useful if a shell command spews -out lots of output that just gets in the way. This command used to be -called @code{comint-kill-output}. - -@item C-c C-s -@kindex C-c C-s @r{(Shell mode)} -@findex comint-write-output -Write the last batch of output from a shell command to a file -(@code{comint-write-output}). With a prefix argument, the file is -appended to instead. Any prompt at the end of the output is not -written. - -@item C-c C-r -@itemx C-M-l -@kindex C-c C-r @r{(Shell mode)} -@kindex C-M-l @r{(Shell mode)} -@findex comint-show-output -Scroll to display the beginning of the last batch of output at the top -of the window; also move the cursor there (@code{comint-show-output}). - -@item C-c C-e -@kindex C-c C-e @r{(Shell mode)} -@findex comint-show-maximum-output -Scroll to put the end of the buffer at the bottom of the window -(@code{comint-show-maximum-output}). - -@item C-c C-f -@kindex C-c C-f @r{(Shell mode)} -@findex shell-forward-command -@vindex shell-command-regexp -Move forward across one shell command, but not beyond the current line -(@code{shell-forward-command}). The variable @code{shell-command-regexp} -specifies how to recognize the end of a command. - -@item C-c C-b -@kindex C-c C-b @r{(Shell mode)} -@findex shell-backward-command -Move backward across one shell command, but not beyond the current line -(@code{shell-backward-command}). - -@item M-x dirs -Ask the shell what its current directory is, so that Emacs can agree -with the shell. - -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible -Send @var{text} as input to the shell, after reading it without -echoing. This is useful when a shell command runs a program that asks -for a password. - -Please note that Emacs will not echo passwords by default. If you -really want them to be echoed, evaluate the following Lisp -expression: - -@example -(remove-hook 'comint-output-filter-functions - 'comint-watch-for-password-prompt) -@end example - -@item M-x comint-continue-subjob -@findex comint-continue-subjob -Continue the shell process. This is useful if you accidentally suspend -the shell process.@footnote{You should not suspend the shell process. -Suspending a subjob of the shell is a completely different matter---that -is normal practice, but you must use the shell to continue the subjob; -this command won't do it.} - -@item M-x comint-strip-ctrl-m -@findex comint-strip-ctrl-m -Discard all control-M characters from the current group of shell output. -The most convenient way to use this command is to make it run -automatically when you get output from the subshell. To do that, -evaluate this Lisp expression: - -@example -(add-hook 'comint-output-filter-functions - 'comint-strip-ctrl-m) -@end example - -@item M-x comint-truncate-buffer -@findex comint-truncate-buffer -This command truncates the shell buffer to a certain maximum number of -lines, specified by the variable @code{comint-buffer-maximum-size}. -Here's how to do this automatically each time you get output from the -subshell: - -@example -(add-hook 'comint-output-filter-functions - 'comint-truncate-buffer) -@end example -@end table - -@cindex Comint mode -@cindex mode, Comint - Shell mode is a derivative of Comint mode, a general-purpose mode for -communicating with interactive subprocesses. Most of the features of -Shell mode actually come from Comint mode, as you can see from the -command names listed above. The special features of Shell mode include -the directory tracking feature, and a few user commands. - - Other Emacs features that use variants of Comint mode include GUD -(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). - -@findex comint-run - You can use @kbd{M-x comint-run} to execute any program of your choice -in a subprocess using unmodified Comint mode---without the -specializations of Shell mode. - -@node Shell Prompts -@subsection Shell Prompts - -@vindex shell-prompt-pattern -@vindex comint-prompt-regexp -@vindex comint-use-prompt-regexp -@cindex prompt, shell - A prompt is text output by a program to show that it is ready to -accept new user input. Normally, Comint mode (and thus Shell mode) -considers the prompt to be any text output by a program at the -beginning of an input line. However, if the variable -@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode -uses a regular expression to recognize prompts. In Shell mode, -@code{shell-prompt-pattern} specifies the regular expression. - - The value of @code{comint-use-prompt-regexp} also affects many -motion and paragraph commands. If the value is non-@code{nil}, the -general Emacs motion commands behave as they normally do in buffers -without special text properties. However, if the value is @code{nil}, -the default, then Comint mode divides the buffer into two types of -``fields'' (ranges of consecutive characters having the same -@code{field} text property): input and output. Prompts are part of -the output. Most Emacs motion commands do not cross field boundaries, -unless they move over multiple lines. For instance, when point is in -input on the same line as a prompt, @kbd{C-a} puts point at the -beginning of the input if @code{comint-use-prompt-regexp} is -@code{nil} and at the beginning of the line otherwise. - - In Shell mode, only shell prompts start new paragraphs. Thus, a -paragraph consists of a prompt and the input and output that follow -it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the -default, most paragraph commands do not cross field boundaries. This -means that prompts, ranges of input, and ranges of non-prompt output -behave mostly like separate paragraphs; with this setting, numeric -arguments to most paragraph commands yield essentially undefined -behavior. For the purpose of finding paragraph boundaries, Shell mode -uses @code{shell-prompt-pattern}, regardless of -@code{comint-use-prompt-regexp}. - -@node Shell History -@subsection Shell Command History - - Shell buffers support three ways of repeating earlier commands. You -can use keys like those used for the minibuffer history; these work -much as they do in the minibuffer, inserting text from prior commands -while point remains always at the end of the buffer. You can move -through the buffer to previous inputs in their original place, then -resubmit them or copy them to the end. Or you can use a -@samp{!}-style history reference. - -@menu -* Ring: Shell Ring. Fetching commands from the history list. -* Copy: Shell History Copying. Moving to a command and then copying it. -* History References:: Expanding @samp{!}-style history references. -@end menu - -@node Shell Ring -@subsubsection Shell History Ring - -@table @kbd -@findex comint-previous-input -@kindex M-p @r{(Shell mode)} -@item M-p -@itemx C-@key{UP} -Fetch the next earlier old shell command. - -@kindex M-n @r{(Shell mode)} -@findex comint-next-input -@item M-n -@itemx C-@key{DOWN} -Fetch the next later old shell command. - -@kindex M-r @r{(Shell mode)} -@kindex M-s @r{(Shell mode)} -@findex comint-previous-matching-input -@findex comint-next-matching-input -@item M-r @var{regexp} @key{RET} -@itemx M-s @var{regexp} @key{RET} -Search backwards or forwards for old shell commands that match @var{regexp}. - -@item C-c C-x -@kindex C-c C-x @r{(Shell mode)} -@findex comint-get-next-from-history -Fetch the next subsequent command from the history. - -@item C-c . -@kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument -Fetch one argument from an old shell command. - -@item C-c C-l -@kindex C-c C-l @r{(Shell mode)} -@findex comint-dynamic-list-input-ring -Display the buffer's history of shell commands in another window -(@code{comint-dynamic-list-input-ring}). -@end table - - Shell buffers provide a history of previously entered shell commands. To -reuse shell commands from the history, use the editing commands @kbd{M-p}, -@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer -history commands except that they operate on the text at the end of the -shell buffer, where you would normally insert text to send to the shell. - - @kbd{M-p} fetches an earlier shell command to the end of the shell -buffer. Successive use of @kbd{M-p} fetches successively earlier -shell commands, each replacing any text that was already present as -potential shell input. @kbd{M-n} does likewise except that it finds -successively more recent shell commands from the buffer. -@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like -@kbd{M-n}. - - The history search commands @kbd{M-r} and @kbd{M-s} read a regular -expression and search through the history for a matching command. Aside -from the choice of which command to fetch, they work just like @kbd{M-p} -and @kbd{M-n}. If you enter an empty regexp, these commands reuse the -same regexp used last time. - - When you find the previous input you want, you can resubmit it by -typing @key{RET}, or you can edit it first and then resubmit it if you -wish. Any partial input you were composing before navigating the -history list is restored when you go to the beginning or end of the -history ring. - - Often it is useful to reexecute several successive shell commands that -were previously executed in sequence. To do this, first find and -reexecute the first command of the sequence. Then type @kbd{C-c C-x}; -that will fetch the following command---the one that follows the command -you just repeated. Then type @key{RET} to reexecute this command. You -can reexecute several successive commands by typing @kbd{C-c C-x -@key{RET}} over and over. - - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) -copies an individual argument from a previous command, like @kbd{ESC -.} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). - - These commands get the text of previous shell commands from a special -history list, not from the shell buffer itself. Thus, editing the shell -buffer, or even killing large parts of it, does not affect the history -that these commands access. - -@vindex shell-input-ring-file-name - Some shells store their command histories in files so that you can -refer to commands from previous shell sessions. Emacs reads -the command history file for your chosen shell, to initialize its own -command history. The file name is @file{~/.bash_history} for bash, -@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. - -@node Shell History Copying -@subsubsection Shell History Copying - -@table @kbd -@kindex C-c C-p @r{(Shell mode)} -@findex comint-previous-prompt -@item C-c C-p -Move point to the previous prompt (@code{comint-previous-prompt}). - -@kindex C-c C-n @r{(Shell mode)} -@findex comint-next-prompt -@item C-c C-n -Move point to the following prompt (@code{comint-next-prompt}). - -@kindex C-c RET @r{(Shell mode)} -@findex comint-copy-old-input -@item C-c @key{RET} -Copy the input command at point, inserting the copy at the end of the -buffer (@code{comint-copy-old-input}). This is useful if you move -point back to a previous command. After you copy the command, you can -submit the copy as input with @key{RET}. If you wish, you can edit -the copy before resubmitting it. If you use this command on an output -line, it copies that line to the end of the buffer. - -@item Mouse-2 -If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy -the old input command that you click on, inserting the copy at the end -of the buffer (@code{comint-insert-input}). If -@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is -not over old input, just yank as usual. -@end table - - Moving to a previous input and then copying it with @kbd{C-c -@key{RET}} or @kbd{Mouse-2} produces the same results---the same -buffer contents---that you would get by using @kbd{M-p} enough times -to fetch that previous input from the history list. However, @kbd{C-c -@key{RET}} copies the text from the buffer, which can be different -from what is in the history list if you edit the input text in the -buffer after it has been sent. - -@node History References -@subsubsection Shell History References -@cindex history reference - - Various shells including csh and bash support @dfn{history -references} that begin with @samp{!} and @samp{^}. Shell mode -recognizes these constructs, and can perform the history substitution -for you. - - If you insert a history reference and type @key{TAB}, this searches -the input history for a matching command, performs substitution if -necessary, and places the result in the buffer in place of the history -reference. For example, you can fetch the most recent command -beginning with @samp{mv} with @kbd{! m v @key{TAB}}. You can edit the -command if you wish, and then resubmit the command to the shell by -typing @key{RET}. - -@vindex comint-input-autoexpand -@findex comint-magic-space - Shell mode can optionally expand history references in the buffer -when you send them to the shell. To request this, set the variable -@code{comint-input-autoexpand} to @code{input}. You can make -@key{SPC} perform history expansion by binding @key{SPC} to the -command @code{comint-magic-space}. - - Shell mode recognizes history references when they follow a prompt. -@xref{Shell Prompts}, for how Shell mode recognizes prompts. - -@node Directory Tracking -@subsection Directory Tracking -@cindex directory tracking - -@vindex shell-pushd-regexp -@vindex shell-popd-regexp -@vindex shell-cd-regexp - Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} -commands given to the inferior shell, so it can keep the -@samp{*shell*} buffer's default directory the same as the shell's -working directory. It recognizes these commands syntactically, by -examining lines of input that are sent. - - If you use aliases for these commands, you can tell Emacs to -recognize them also. For example, if the value of the variable -@code{shell-pushd-regexp} matches the beginning of a shell command -line, that line is regarded as a @code{pushd} command. Change this -variable when you add aliases for @samp{pushd}. Likewise, -@code{shell-popd-regexp} and @code{shell-cd-regexp} are used to -recognize commands with the meaning of @samp{popd} and @samp{cd}. -These commands are recognized only at the beginning of a shell command -line. - -@ignore @c This seems to have been deleted long ago. -@vindex shell-set-directory-error-hook - If Emacs gets an error while trying to handle what it believes is a -@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook -@code{shell-set-directory-error-hook} (@pxref{Hooks}). -@end ignore - -@findex dirs - If Emacs gets confused about changes in the current directory of the -subshell, use the command @kbd{M-x dirs} to ask the shell what its -current directory is. This command works for shells that support the -most common command syntax; it may not work for unusual shells. - -@findex dirtrack-mode - You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an -alternative method of tracking changes in the current directory. This -method relies on your shell prompt containing the full current working -directory at all times. - -@node Shell Options -@subsection Shell Mode Options - -@vindex comint-scroll-to-bottom-on-input - If the variable @code{comint-scroll-to-bottom-on-input} is -non-@code{nil}, insertion and yank commands scroll the selected window -to the bottom before inserting. The default is @code{nil}. - -@vindex comint-scroll-show-maximum-output - If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then -arrival of output when point is at the end tries to scroll the last -line of text to the bottom line of the window, showing as much useful -text as possible. (This mimics the scrolling behavior of most -terminals.) The default is @code{t}. - -@vindex comint-move-point-for-output - By setting @code{comint-move-point-for-output}, you can opt for -having point jump to the end of the buffer whenever output arrives---no -matter where in the buffer point was before. If the value is -@code{this}, point jumps in the selected window. If the value is -@code{all}, point jumps in each window that shows the Comint buffer. If -the value is @code{other}, point jumps in all nonselected windows that -show the current buffer. The default value is @code{nil}, which means -point does not jump to the end. - -@vindex comint-prompt-read-only - If you set @code{comint-prompt-read-only}, the prompts in the Comint -buffer are read-only. - -@vindex comint-input-ignoredups - The variable @code{comint-input-ignoredups} controls whether successive -identical inputs are stored in the input history. A non-@code{nil} -value means to omit an input that is the same as the previous input. -The default is @code{nil}, which means to store each input even if it is -equal to the previous input. - -@vindex comint-completion-addsuffix -@vindex comint-completion-recexact -@vindex comint-completion-autolist - Three variables customize file name completion. The variable -@code{comint-completion-addsuffix} controls whether completion inserts a -space or a slash to indicate a fully completed file or directory name -(non-@code{nil} means do insert a space or slash). -@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} -to choose the shortest possible completion if the usual Emacs completion -algorithm cannot add even a single character. -@code{comint-completion-autolist}, if non-@code{nil}, says to list all -the possible completions whenever completion is not exact. - -@vindex shell-completion-execonly - Command completion normally considers only executable files. -If you set @code{shell-completion-execonly} to @code{nil}, -it considers nonexecutable files as well. - -@findex shell-pushd-tohome -@findex shell-pushd-dextract -@findex shell-pushd-dunique - You can configure the behavior of @samp{pushd}. Variables control -whether @samp{pushd} behaves like @samp{cd} if no argument is given -(@code{shell-pushd-tohome}), pop rather than rotate with a numeric -argument (@code{shell-pushd-dextract}), and only add directories to the -directory stack if they are not already on it -(@code{shell-pushd-dunique}). The values you choose should match the -underlying shell, of course. - - If you want Shell mode to handle color output from shell commands, -you can enable ANSI Color mode. Here is how to do this: - -@example -(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on) -@end example - -@node Terminal emulator -@subsection Emacs Terminal Emulator -@findex term - - To run a subshell in a terminal emulator, use @kbd{M-x term}. This -creates (or reuses) a buffer named @samp{*terminal*}, and runs a -subshell with input coming from your keyboard, and output going to -that buffer. - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. - - In char mode, each character is sent directly to the inferior -subshell, as ``terminal input.'' Any ``echoing'' of your input is the -responsibility of the subshell. The sole exception is the terminal -escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). -Any ``terminal output'' from the subshell goes into the buffer, -advancing point. - - Some programs (such as Emacs itself) need to control the appearance -on the terminal screen in detail. They do this by sending special -control codes. The exact control codes needed vary from terminal to -terminal, but nowadays most terminals and terminal emulators -(including @code{xterm}) understand the ANSI-standard (VT100-style) -escape sequences. Term mode recognizes these escape sequences, and -handles each one appropriately, changing the buffer so that the -appearance of the window matches what it would be on a real terminal. -You can actually run Emacs inside an Emacs Term window. - - You can use Term mode to communicate with a device connected to a -serial port of your computer. @xref{Serial Terminal}. - - The file name used to load the subshell is determined the same way -as for Shell mode. To make multiple terminal emulators, rename the -buffer @samp{*terminal*} to something different using @kbd{M-x -rename-uniquely}, just as with Shell mode. - - Unlike Shell mode, Term mode does not track the current directory by -examining your input. But some shells can tell Term what the current -directory is. This is done automatically by @code{bash} version 1.15 -and later. - -@node Term Mode -@subsection Term Mode -@cindex Term mode -@cindex mode, Term - - The terminal emulator uses Term mode, which has two input modes. In -line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. -In char mode, each character is sent directly to the inferior -subshell, except for the Term escape character, normally @kbd{C-c}. - - To switch between line and char mode, use these commands: - -@table @kbd -@kindex C-c C-j @r{(Term mode)} -@findex term-char-mode -@item C-c C-j -Switch to line mode. Do nothing if already in line mode. - -@kindex C-c C-k @r{(Term mode)} -@findex term-line-mode -@item C-c C-k -Switch to char mode. Do nothing if already in char mode. -@end table - - The following commands are only available in char mode: - -@table @kbd -@item C-c C-c -Send a literal @key{C-c} to the sub-shell. - -@item C-c @var{char} -This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For -example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which -is normally @samp{other-window}. -@end table - -@node Paging in Term -@subsection Page-At-A-Time Output -@cindex page-at-a-time - - Term mode has a page-at-a-time feature. When enabled it makes -output pause at the end of each screenful. - -@table @kbd -@kindex C-c C-q @r{(Term mode)} -@findex term-pager-toggle -@item C-c C-q -Toggle the page-at-a-time feature. This command works in both line -and char modes. When page-at-a-time is enabled, the mode-line -displays the word @samp{page}. -@end table - - With page-at-a-time enabled, whenever Term receives more than a -screenful of output since your last input, it pauses, displaying -@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next -screenful of output. Type @kbd{?} to see your other options. The -interface is similar to the @code{more} program. - -@node Remote Host -@subsection Remote Host Shell -@cindex remote host -@cindex connecting to remote host -@cindex Telnet -@cindex Rlogin - - You can login to a remote computer, using whatever commands you -would from a regular terminal (e.g.@: using the @code{telnet} or -@code{rlogin} commands), from a Term window. - - A program that asks you for a password will normally suppress -echoing of the password, so the password will not show up in the -buffer. This will happen just as if you were using a real terminal, -if the buffer is in char mode. If it is in line mode, the password is -temporarily visible, but will be erased when you hit return. (This -happens automatically; there is no special password processing.) - - When you log in to a different machine, you need to specify the type -of terminal you're using, by setting the @env{TERM} environment -variable in the environment for the remote login command. (If you use -bash, you do that by writing the variable assignment before the remote -login command, without separating comma.) Terminal types @samp{ansi} -or @samp{vt100} will work on most systems. - -@c If you are talking to a Bourne-compatible -@c shell, and your system understands the @env{TERMCAP} variable, -@c you can use the command @kbd{M-x shell-send-termcap}, which -@c sends a string specifying the terminal type and size. -@c (This command is also useful after the window has changed size.) - -@c You can of course run @samp{gdb} on that remote computer. One useful -@c trick: If you invoke gdb with the @code{--fullname} option, -@c it will send special commands to Emacs that will cause Emacs to -@c pop up the source files you're debugging. This will work -@c whether or not gdb is running on a different computer than Emacs, -@c as long as Emacs can access the source files specified by gdb. - -@ignore - You cannot log in to a remote computer using the Shell mode. -@c (This will change when Shell is re-written to use Term.) -Instead, Emacs provides two commands for logging in to another computer -and communicating with it through an Emacs buffer using Comint mode: - -@table @kbd -@item M-x telnet @key{RET} @var{hostname} @key{RET} -Set up a Telnet connection to the computer named @var{hostname}. -@item M-x rlogin @key{RET} @var{hostname} @key{RET} -Set up an Rlogin connection to the computer named @var{hostname}. -@end table - -@findex telnet - Use @kbd{M-x telnet} to set up a Telnet connection to another -computer. (Telnet is the standard Internet protocol for remote login.) -It reads the host name of the other computer as an argument with the -minibuffer. Once the connection is established, talking to the other -computer works like talking to a subshell: you can edit input with the -usual Emacs commands, and send it a line at a time by typing @key{RET}. -The output is inserted in the Telnet buffer interspersed with the input. - -@findex rlogin -@vindex rlogin-explicit-args - Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is -another remote login communication protocol, essentially much like the -Telnet protocol but incompatible with it, and supported only by certain -systems. Rlogin's advantages are that you can arrange not to have to -give your user name and password when communicating between two machines -you frequently use, and that you can make an 8-bit-clean connection. -(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} -before you run Rlogin.) - - @kbd{M-x rlogin} sets up the default file directory of the Emacs -buffer to access the remote host via FTP (@pxref{File Names}), and it -tracks the shell commands that change the current directory, just like -Shell mode. - -@findex rlogin-directory-tracking-mode - There are two ways of doing directory tracking in an Rlogin -buffer---either with remote directory names -@file{/@var{host}:@var{dir}/} or with local names (that works if the -``remote'' machine shares file systems with your machine of origin). -You can use the command @code{rlogin-directory-tracking-mode} to switch -modes. No argument means use remote directory names, a positive -argument means use local names, and a negative argument means turn -off directory tracking. - -@end ignore - -@node Serial Terminal -@subsection Serial Terminal -@cindex terminal, serial -@findex serial-term - - If you have a device connected to a serial port of your computer, -you can use Emacs to communicate with it. @kbd{M-x serial-term} will -ask you for a serial port name and speed and will then open a new -window in @ref{Term Mode}. - - The speed of the serial port is measured in bits per second. The -most common speed is 9600 bits per second. You can change the speed -interactively by clicking on the mode line. - - A serial port can be configured even more by clicking on ``8N1'' in -the mode line. By default, a serial port is configured as ``8N1'', -which means that each byte consists of 8 data bits, No parity check -bit, and 1 stopbit. - - When you have opened the serial port connection, you will see output -from the device in the window. Also, what you type in the window is -sent to the device. - - If the speed or the configuration is wrong, you cannot communicate -with your device and will probably only see garbage output in the -window. - -@node Emacs Server, Printing, Shell, Top -@section Using Emacs as a Server -@pindex emacsclient -@cindex Emacs as a server -@cindex server, using Emacs as -@cindex @env{EDITOR} environment variable - - Various programs such as @command{mail} can invoke your choice of -editor to edit a particular piece of text, such as a message that you -are sending. By convention, most of these programs use the -environment variable @env{EDITOR} to specify which editor to run. If -you set @env{EDITOR} to @samp{emacs}, they invoke Emacs---but in an -inconvenient way, by starting a new Emacs process. This is -inconvenient because the new Emacs process doesn't share buffers, a -command history, or other kinds of information with any existing Emacs -process. - - You can solve this problem by setting up Emacs as an @dfn{edit -server}, so that it ``listens'' for external edit requests and acts -accordingly. There are two ways to start an Emacs server: - -@findex server-start - The first is to run the command @code{server-start} in an existing -Emacs process: either type @kbd{M-x server-start}, or put the -expression @code{(server-start)} in your initialization file -(@pxref{Init File}). The existing Emacs process is the server; when -you exit Emacs, the server dies with the Emacs process. - -@cindex daemon, Emacs - The second way to start an Emacs server is to run Emacs as a -@dfn{daemon}, using the @samp{--daemon} command-line option. -@xref{Initial Options}. When Emacs is started this way, it calls -@code{server-start} after initialization, and returns control to the -calling terminal instead of opening an initial frame; it then waits in -the background, listening for edit requests. - -@cindex @env{TEXEDIT} environment variable - Once an Emacs server is set up, you can use a shell command called -@command{emacsclient} to connect to the existing Emacs process and -tell it to visit a file. If you set the @env{EDITOR} environment -variable to @samp{emacsclient}, programs such as @command{mail} will -use the existing Emacs process for editing.@footnote{Some programs use -a different environment variable; for example, to make @TeX{} use -@samp{emacsclient}, set the @env{TEXEDIT} environment variable to -@samp{emacsclient +%d %s}.} - -@vindex server-name - You can run multiple Emacs servers on the same machine by giving -each one a unique ``server name'', using the variable -@code{server-name}. For example, @kbd{M-x set-variable @key{RET} -server-name @key{RET} foo @key{RET}} sets the server name to -@samp{foo}. The @code{emacsclient} program can specify a server by -name, using the @samp{-s} option (@pxref{emacsclient Options}). - -@menu -* Invoking emacsclient:: Connecting to the Emacs server. -* emacsclient Options:: Emacs client startup options. -@end menu - -@node Invoking emacsclient -@subsection Invoking @code{emacsclient} -@cindex @code{emacsclient} invocation - - The simplest way to use the @command{emacsclient} program is to run -the shell command @samp{emacsclient @var{file}}, where @var{file} is a -file name. This connects to an Emacs server, and tells that Emacs -process to visit @var{file} in one of its existing frames---either a -graphical frame, or one in a text-only terminal (@pxref{Frames}). You -can then select that frame to begin editing. - - If there is no Emacs server, the @command{emacsclient} program halts -with an error message. If the Emacs process has no existing -frame---which can happen if it was started as a daemon (@pxref{Emacs -Server})---then Emacs opens a frame on the terminal in which you -called @command{emacsclient}, as though you had used the @samp{-t} -option (@pxref{emacsclient Options}). - - On a graphical display, switching to the Emacs server is -straightforward---just select its (system-level) window. If you are -using a text-only terminal, there are two ways to switch between -@command{emacsclient}'s shell and the Emacs server: (i) run the Emacs -server and @command{emacsclient} on different virtual terminals, and -switch to the Emacs server's virtual terminal after calling -@command{emacsclient}; or (ii) call @command{emacsclient} from within -the Emacs server itself, using Shell mode (@pxref{Interactive Shell}) -or Term mode (@pxref{Term Mode}); @code{emacsclient} blocks only the -subshell under Emacs, and you can still use Emacs to edit the file. - -@kindex C-x # -@findex server-edit - When you finish editing @var{file} in the Emacs server, type -@kbd{C-x #} (@code{server-edit}) in its buffer. This saves the file -and sends a message back to the @command{emacsclient} program, telling -it to exit. Programs that use @env{EDITOR} usually wait for the -``editor''---in the case @command{emacsclient}---to exit before doing -something else. - - You can also call @command{emacsclient} with multiple file name -arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the -Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs -selects the buffer visiting @var{file1}, and buries the other buffers -at the bottom of the buffer list (@pxref{Buffers}). The -@command{emacsclient} program exits once all the specified files are -finished (i.e., once you have typed @kbd{C-x #} in each server -buffer). - -@vindex server-kill-new-buffers -@vindex server-temp-file-regexp - Finishing with a server buffer also kills the buffer, unless it -already existed in the Emacs session before the server was asked to -create it. However, if you set @code{server-kill-new-buffers} to -@code{nil}, then a different criterion is used: finishing with a -server buffer kills it if the file name matches the regular expression -@code{server-temp-file-regexp}. This is set up to distinguish certain -``temporary'' files. - - Each @kbd{C-x #} checks for other pending external requests to edit -various files, and selects the next such file. You can switch to a -server buffer manually if you wish; you don't have to arrive at it -with @kbd{C-x #}. But @kbd{C-x #} is the way to tell -@command{emacsclient} that you are finished. - -@vindex server-window - If you set the variable @code{server-window} to a window or a frame, -@kbd{C-x #} always displays the next server buffer in that window or -in that frame. - -@node emacsclient Options -@subsection @code{emacsclient} Options -@cindex @code{emacsclient} options - - You can pass some optional arguments to the @command{emacsclient} -program, such as: - -@example -emacsclient -c +12 @var{file1} +4:3 @var{file2} -@end example - -@noindent -The @samp{+@var{line}} or @samp{+@var{line}:@var{column}} arguments -specify line numbers, or line and column numbers, for the next file -argument. These behave like the command line arguments for Emacs -itself. @xref{Action Arguments}. - - The other optional arguments recognized by @command{emacsclient} are -listed below: - -@table @samp -@item -a @var{command} -@itemx --alternate-editor=@var{command} -Specify a command to run if @code{emacsclient} fails to contact Emacs. -This is useful when running @code{emacsclient} in a script. For -example, the following setting for the @env{EDITOR} environment -variable will always give you an editor, even if no Emacs server is -running: - -@example -EDITOR="emacsclient --alternate-editor emacs +%d %s" -@end example - -@noindent -As a special exception, if @var{command} is the empty string, then -@code{emacsclient} starts Emacs in daemon mode and then tries -connecting again. - -@cindex @env{ALTERNATE_EDITOR} environment variable -The environment variable @env{ALTERNATE_EDITOR} has the same effect as -the @samp{-a} option. If both are present, the latter takes -precedence. - -@item -c -Create a new graphical frame, instead of using an existing Emacs -frame. Emacs 23 can create a graphical frame even if it was started -in a text-only terminal, provided it is able to connect to a graphical -display. If no graphical display is available, Emacs creates a new -text-only terminal frame (@pxref{Frames}). If you omit a filename -argument while supplying the @samp{-c} option, the new frame displays -the @samp{*scratch*} buffer (@pxref{Buffers}). - -@item -d @var{display} -@itemx --display=@var{display} -Tell Emacs to open the given files on the X display @var{display} -(assuming there is more than one X display available). - -@item -e -@itemx --eval -Tell Emacs to evaluate some Emacs Lisp code, instead of visiting some -files. When this option is given, the arguments to -@command{emacsclient} are interpreted as a list of expressions to -evaluate, @emph{not} as a list of files to visit. - -@item -f @var{server-file} -@itemx --server-file=@var{server-file} -@cindex @env{EMACS_SERVER_FILE} environment variable -@cindex server file -@vindex server-use-tcp -@vindex server-host -Specify a @dfn{server file} for connecting to an Emacs server via TCP. - -An Emacs server usually uses an operating system feature called a -``local socket'' to listen for connections. Some operating systems, -such as Microsoft Windows, do not support local sockets; in that case, -Emacs uses TCP instead. When you start the Emacs server, Emacs -creates a server file containing some TCP information that -@command{emacsclient} needs for making the connection. By default, -the server file is in @file{~/.emacs.d/server/}. On Microsoft -Windows, if @command{emacsclient} does not find the server file there, -it looks in the @file{.emacs.d/server/} subdirectory of the directory -pointed to by the @env{APPDATA} environment variable. You can tell -@command{emacsclient} to use a specific server file with the @samp{-f} -or @samp{--server-file} option, or by setting the -@env{EMACS_SERVER_FILE} environment variable. - -Even if local sockets are available, you can tell Emacs to use TCP by -setting the variable @code{server-use-tcp} to @code{t}. One advantage -of TCP is that the server can accept connections from remote machines. -For this to work, you must (i) set the variable @code{server-host} to -the hostname or IP address of the machine on which the Emacs server -runs, and (ii) provide @command{emacsclient} with the server file. -(One convenient way to do the latter is to put the server file on a -networked file system such as NFS.) - -@item -n -@itemx --no-wait -Let @command{emacsclient} exit immediately, instead of waiting until -all server buffers are finished. You can take as long as you like to -edit the server buffers within Emacs, and they are @emph{not} killed -when you type @kbd{C-x #} in them. - -@item -s @var{server-name} -@itemx --socket-name=@var{server-name} -Connect to the Emacs server named @var{server-name}. The server name -is given by the variable @code{server-name} on the Emacs server. If -this option is omitted, @command{emacsclient} connects to the first -server it finds. (This option is not supported on MS-Windows.) - -@item -t -@itemx --tty -@itemx -nw -Create a new Emacs frame on the current text-only terminal, instead of -using an existing Emacs frame. Emacs 23 can open a text-only terminal -even if it was started in another text-only terminal, or on a -graphical display. If you omit a filename argument while supplying -this option, the new frame displays the @samp{*scratch*} buffer. -@xref{Buffers}. -@end table - - If you type @kbd{C-x C-c} (@code{save-buffers-kill-terminal}) in an -Emacs frame created with @command{emacsclient}, via the @samp{-c} or -@samp{-t} options, Emacs deletes the frame instead of killing the -Emacs process itself. On a text-only terminal frame created with the -@samp{-t} option, this returns control to the terminal. Emacs also -marks all the server buffers for the client as finished, as though you -had typed @kbd{C-x #} in all of them. - - When Emacs is started as a daemon, all frames are considered client -frames, so @kbd{C-x C-c} will never kill Emacs. To kill the Emacs -process, type @kbd{M-x kill-emacs}. - -@node Printing, Sorting, Emacs Server, Top -@section Printing Hard Copies -@cindex hardcopy -@cindex printing - - Emacs provides commands for printing hard copies of either an entire -buffer or just part of one, with or without page headers. You can -invoke the printing commands directly, as detailed in the following -section, or using the @samp{File} menu on the menu bar. See also the -hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary -(@pxref{Displaying the Diary}). - -@table @kbd -@item M-x print-buffer -Print hardcopy of current buffer with page headings containing the file -name and page number. -@item M-x lpr-buffer -Print hardcopy of current buffer without page headings. -@item M-x print-region -Like @code{print-buffer} but print only the current region. -@item M-x lpr-region -Like @code{lpr-buffer} but print only the current region. -@end table - -@findex print-buffer -@findex print-region -@findex lpr-buffer -@findex lpr-region -@vindex lpr-switches - The hardcopy commands (aside from the PostScript commands) pass extra -switches to the @code{lpr} program based on the value of the variable -@code{lpr-switches}. Its value should be a list of strings, each string -an option starting with @samp{-}. For example, to specify a line width -of 80 columns for all the printing you do in Emacs, set -@code{lpr-switches} like this: - -@example -(setq lpr-switches '("-w80")) -@end example - -@vindex printer-name - You can specify the printer to use by setting the variable -@code{printer-name}. - -@vindex lpr-headers-switches -@vindex lpr-commands -@vindex lpr-add-switches - The variable @code{lpr-command} specifies the name of the printer -program to run; the default value depends on your operating system type. -On most systems, the default is @code{"lpr"}. The variable -@code{lpr-headers-switches} similarly specifies the extra switches to -use to make page headers. The variable @code{lpr-add-switches} controls -whether to supply @samp{-T} and @samp{-J} options (suitable for -@code{lpr}) to the printer program: @code{nil} means don't add them. -@code{lpr-add-switches} should be @code{nil} if your printer program is -not compatible with @code{lpr}. - -@menu -* PostScript:: Printing buffers or regions as PostScript. -* PostScript Variables:: Customizing the PostScript printing commands. -* Printing Package:: An optional advanced printing interface. -@end menu - -@node PostScript, PostScript Variables,, Printing -@section PostScript Hardcopy - - These commands convert buffer contents to PostScript, -either printing it or leaving it in another Emacs buffer. - -@table @kbd -@item M-x ps-print-buffer -Print hardcopy of the current buffer in PostScript form. -@item M-x ps-print-region -Print hardcopy of the current region in PostScript form. -@item M-x ps-print-buffer-with-faces -Print hardcopy of the current buffer in PostScript form, showing the -faces used in the text by means of PostScript features. -@item M-x ps-print-region-with-faces -Print hardcopy of the current region in PostScript form, showing the -faces used in the text. -@item M-x ps-spool-buffer -Generate and spool a PostScript image for the current buffer text. -@item M-x ps-spool-region -Generate and spool a PostScript image for the current region. -@item M-x ps-spool-buffer-with-faces -Generate and spool a PostScript image for the current buffer, showing the faces used. -@item M-x ps-spool-region-with-faces -Generate and spool a PostScript image for the current region, showing the faces used. -@item M-x ps-despool -Send the spooled PostScript to the printer. -@item M-x handwrite -Generate/print PostScript for the current buffer as if handwritten. -@end table - -@findex ps-print-region -@findex ps-print-buffer -@findex ps-print-region-with-faces -@findex ps-print-buffer-with-faces - The PostScript commands, @code{ps-print-buffer} and -@code{ps-print-region}, print buffer contents in PostScript form. One -command prints the entire buffer; the other, just the region. The -corresponding @samp{-with-faces} commands, -@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces}, -use PostScript features to show the faces (fonts and colors) in the text -properties of the text being printed. The @samp{-with-faces} commands only -work if they are used in a window system, so it has a way to determine color -values. - - Interactively, when you use a prefix argument (@kbd{C-u}), the command -prompts the user for a file name, and saves the PostScript image in that file -instead of sending it to the printer. - - Noninteractively, the argument @var{filename} is treated as follows: if it is -@code{nil}, send the image to the printer. If @var{filename} is a string, save -the PostScript image in a file with that name. - - If you are using a color display, you can print a buffer of program -code with color highlighting by turning on Font-Lock mode in that -buffer, and using @code{ps-print-buffer-with-faces}. - -@findex ps-spool-region -@findex ps-spool-buffer -@findex ps-spool-region-with-faces -@findex ps-spool-buffer-with-faces - The commands whose names have @samp{spool} instead of @samp{print}, -generate the PostScript output in an Emacs buffer instead of sending -it to the printer. - - Use the command @code{ps-despool} to send the spooled images to the printer. - -@findex ps-despool - This command sends the PostScript generated by @samp{-spool-} commands (see -commands above) to the printer. - - Interactively, when you use a prefix argument (@kbd{C-u}), the command -prompts the user for a file name, and saves the spooled PostScript image in -that file instead of sending it to the printer. - - Noninteractively, the argument @var{filename} is treated as follows: if it is -@code{nil}, send the image to the printer. If @var{filename} is a string, save -the PostScript image in a file with that name. - -@findex handwrite -@cindex handwriting -@kbd{M-x handwrite} is more frivolous. It generates a PostScript -rendition of the current buffer as a cursive handwritten document. It -can be customized in group @code{handwrite}. This function only -supports ISO 8859-1 characters. - -@ifnottex - The following section describes variables for customizing these commands. -@end ifnottex - -@node PostScript Variables, Printing Package, PostScript, Printing -@section Variables for PostScript Hardcopy - -@vindex ps-lpr-command -@vindex ps-lpr-switches -@vindex ps-printer-name - All the PostScript hardcopy commands use the variables -@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print -the output. @code{ps-lpr-command} specifies the command name to run, -@code{ps-lpr-switches} specifies command line options to use, and -@code{ps-printer-name} specifies the printer. If you don't set the -first two variables yourself, they take their initial values from -@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} -is @code{nil}, @code{printer-name} is used. - -@vindex ps-print-header - The variable @code{ps-print-header} controls whether these commands -add header lines to each page---set it to @code{nil} to turn headers -off. - -@cindex color emulation on black-and-white printers -@vindex ps-print-color-p - If your printer doesn't support colors, you should turn off color -processing by setting @code{ps-print-color-p} to @code{nil}. By -default, if the display supports colors, Emacs produces hardcopy output -with color information; on black-and-white printers, colors are emulated -with shades of gray. This might produce illegible output, even if your -screen colors only use shades of gray. - - Alternatively, you can set @code{ps-print-color-p} to @code{black-white} to -print colors on black/white printers. - -@vindex ps-use-face-background - By default, PostScript printing ignores the background colors of the -faces, unless the variable @code{ps-use-face-background} is -non-@code{nil}. This is to avoid unwanted interference with the zebra -stripes and background image/text. - -@vindex ps-paper-type -@vindex ps-page-dimensions-database - The variable @code{ps-paper-type} specifies which size of paper to -format for; legitimate values include @code{a4}, @code{a3}, -@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, -@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, -@code{tabloid}. The default is @code{letter}. You can define -additional paper sizes by changing the variable -@code{ps-page-dimensions-database}. - -@vindex ps-landscape-mode - The variable @code{ps-landscape-mode} specifies the orientation of -printing on the page. The default is @code{nil}, which stands for -``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' -mode. - -@vindex ps-number-of-columns - The variable @code{ps-number-of-columns} specifies the number of -columns; it takes effect in both landscape and portrait mode. The -default is 1. - -@vindex ps-font-family -@vindex ps-font-size -@vindex ps-font-info-database - The variable @code{ps-font-family} specifies which font family to use -for printing ordinary text. Legitimate values include @code{Courier}, -@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and -@code{Times}. The variable @code{ps-font-size} specifies the size of -the font for ordinary text. It defaults to 8.5 points. - -@vindex ps-multibyte-buffer -@cindex Intlfonts for PostScript printing -@cindex fonts for PostScript printing - Emacs supports more scripts and characters than a typical PostScript -printer. Thus, some of the characters in your buffer might not be -printable using the fonts built into your printer. You can augment -the fonts supplied with the printer with those from the GNU Intlfonts -package, or you can instruct Emacs to use Intlfonts exclusively. The -variable @code{ps-multibyte-buffer} controls this: the default value, -@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 -characters; a value of @code{non-latin-printer} is for printers which -have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean -characters built into them. A value of @code{bdf-font} arranges for -the BDF fonts from the Intlfonts package to be used for @emph{all} -characters. Finally, a value of @code{bdf-font-except-latin} -instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 -characters, and Intlfonts BDF fonts for the rest. - -@vindex bdf-directory-list - To be able to use the BDF fonts, Emacs needs to know where to find -them. The variable @code{bdf-directory-list} holds the list of -directories where Emacs should look for the fonts; the default value -includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. - - Many other customization variables for these commands are defined and -described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. - -@node Printing Package,, PostScript Variables, Printing -@section Printing Package -@cindex Printing package - - The basic Emacs facilities for printing hardcopy can be extended -using the Printing package. This provides an easy-to-use interface -for choosing what to print, previewing PostScript files before -printing, and setting various printing options such as print headers, -landscape or portrait modes, duplex modes, and so forth. On GNU/Linux -or Unix systems, the Printing package relies on the @file{gs} and -@file{gv} utilities, which are distributed as part of the GhostScript -program. On MS-Windows, the @file{gstools} port of Ghostscript can be -used. - -@findex pr-interface - To use the Printing package, add @code{(require 'printing)} to your -init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. -This function replaces the usual printing commands in the menu bar -with a @samp{Printing} submenu that contains various printing options. -You can also type @kbd{M-x pr-interface RET}; this creates a -@samp{*Printing Interface*} buffer, similar to a customization buffer, -where you can set the printing options. After selecting what and how -to print, you start the print job using the @samp{Print} button (click -@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For -further information on the various options, use the @samp{Interface -Help} button. - -@node Sorting, Narrowing, Printing, Top -@section Sorting Text -@cindex sorting - - Emacs provides several commands for sorting text in the buffer. All -operate on the contents of the region. -They divide the text of the region into many @dfn{sort records}, -identify a @dfn{sort key} for each record, and then reorder the records -into the order determined by the sort keys. The records are ordered so -that their keys are in alphabetical order, or, for numeric sorting, in -numeric order. In alphabetic sorting, all upper-case letters `A' through -`Z' come before lower-case `a', in accord with the @acronym{ASCII} character -sequence. - - The various sort commands differ in how they divide the text into sort -records and in which part of each record is used as the sort key. Most of -the commands make each line a separate sort record, but some commands use -paragraphs or pages as sort records. Most of the sort commands use each -entire sort record as its own sort key, but some use only a portion of the -record as the sort key. - -@findex sort-lines -@findex sort-paragraphs -@findex sort-pages -@findex sort-fields -@findex sort-numeric-fields -@vindex sort-numeric-base -@table @kbd -@item M-x sort-lines -Divide the region into lines, and sort by comparing the entire -text of a line. A numeric argument means sort into descending order. - -@item M-x sort-paragraphs -Divide the region into paragraphs, and sort by comparing the entire -text of a paragraph (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-pages -Divide the region into pages, and sort by comparing the entire -text of a page (except for leading blank lines). A numeric -argument means sort into descending order. - -@item M-x sort-fields -Divide the region into lines, and sort by comparing the contents of -one field in each line. Fields are defined as separated by -whitespace, so the first run of consecutive non-whitespace characters -in a line constitutes field 1, the second such run constitutes field -2, etc. - -Specify which field to sort by with a numeric argument: 1 to sort by -field 1, etc. A negative argument means count fields from the right -instead of from the left; thus, minus 1 means sort by the last field. -If several lines have identical contents in the field being sorted, they -keep the same relative order that they had in the original buffer. - -@item M-x sort-numeric-fields -Like @kbd{M-x sort-fields} except the specified field is converted -to an integer for each line, and the numbers are compared. @samp{10} -comes before @samp{2} when considered as text, but after it when -considered as a number. By default, numbers are interpreted according -to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or -@samp{0} are interpreted as hexadecimal and octal, respectively. - -@item M-x sort-columns -Like @kbd{M-x sort-fields} except that the text within each line -used for comparison comes from a fixed range of columns. See below -for an explanation. - -@item M-x reverse-region -Reverse the order of the lines in the region. This is useful for -sorting into descending order by fields or columns, since those sort -commands do not have a feature for doing that. -@end table - - For example, if the buffer contains this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -whether the file has changed on disk since it was last visited or -saved. If it has, you are asked to confirm that you want to change -the buffer. -@end smallexample - -@noindent -applying @kbd{M-x sort-lines} to the entire buffer produces this: - -@smallexample -On systems where clash detection (locking of files being edited) is -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the upper-case @samp{O} sorts before all lower-case letters. If -you use @kbd{C-u 2 M-x sort-fields} instead, you get this: - -@smallexample -implemented, Emacs also checks the first time you modify a buffer -saved. If it has, you are asked to confirm that you want to change -the buffer. -On systems where clash detection (locking of files being edited) is -whether the file has changed on disk since it was last visited or -@end smallexample - -@noindent -where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, -@samp{systems} and @samp{the}. - -@findex sort-columns - @kbd{M-x sort-columns} requires more explanation. You specify the -columns by putting point at one of the columns and the mark at the other -column. Because this means you cannot put point or the mark at the -beginning of the first line of the text you want to sort, this command -uses an unusual definition of ``region'': all of the line point is in is -considered part of the region, and so is all of the line the mark is in, -as well as all the lines in between. - - For example, to sort a table by information found in columns 10 to 15, -you could put the mark on column 10 in the first line of the table, and -point on column 15 in the last line of the table, and then run -@code{sort-columns}. Equivalently, you could run it with the mark on -column 15 in the first line and point on column 10 in the last line. - - This can be thought of as sorting the rectangle specified by point and -the mark, except that the text on each line to the left or right of the -rectangle moves along with the text inside the rectangle. -@xref{Rectangles}. - -@vindex sort-fold-case - Many of the sort commands ignore case differences when comparing, if -@code{sort-fold-case} is non-@code{nil}. - -@node Narrowing, Two-Column, Sorting, Top -@section Narrowing -@cindex widening -@cindex restriction -@cindex narrowing -@cindex accessible portion - - @dfn{Narrowing} means focusing in on some portion of the buffer, -making the rest temporarily inaccessible. The portion which you can -still get to is called the @dfn{accessible portion}. Canceling the -narrowing, which makes the entire buffer once again accessible, is -called @dfn{widening}. The bounds of narrowing in effect in a buffer -are called the buffer's @dfn{restriction}. - - Narrowing can make it easier to concentrate on a single subroutine or -paragraph by eliminating clutter. It can also be used to limit the -range of operation of a replace command or repeating keyboard macro. - -@table @kbd -@item C-x n n -Narrow down to between point and mark (@code{narrow-to-region}). -@item C-x n w -Widen to make the entire buffer accessible again (@code{widen}). -@item C-x n p -Narrow down to the current page (@code{narrow-to-page}). -@item C-x n d -Narrow down to the current defun (@code{narrow-to-defun}). -@end table - - When you have narrowed down to a part of the buffer, that part appears -to be all there is. You can't see the rest, you can't move into it -(motion commands won't go outside the accessible part), you can't change -it in any way. However, it is not gone, and if you save the file all -the inaccessible text will be saved. The word @samp{Narrow} appears in -the mode line whenever narrowing is in effect. - -@kindex C-x n n -@findex narrow-to-region - The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). -It sets the current buffer's restrictions so that the text in the current -region remains accessible, but all text before the region or after the -region is inaccessible. Point and mark do not change. - -@kindex C-x n p -@findex narrow-to-page -@kindex C-x n d -@findex narrow-to-defun - Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow -down to the current page. @xref{Pages}, for the definition of a page. -@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun -containing point (@pxref{Defuns}). - -@kindex C-x n w -@findex widen - The way to cancel narrowing is to widen with @kbd{C-x n w} -(@code{widen}). This makes all text in the buffer accessible again. - - You can get information on what part of the buffer you are narrowed down -to using the @kbd{C-x =} command. @xref{Position Info}. - - Because narrowing can easily confuse users who do not understand it, -@code{narrow-to-region} is normally a disabled command. Attempting to use -this command asks for confirmation and gives you the option of enabling it; -if you enable the command, confirmation will no longer be required for -it. @xref{Disabling}. - -@node Two-Column, Editing Binary Files, Narrowing, Top -@section Two-Column Editing -@cindex two-column editing -@cindex splitting columns -@cindex columns, splitting - - Two-column mode lets you conveniently edit two side-by-side columns of -text. It uses two side-by-side windows, each showing its own -buffer. - - There are three ways to enter two-column mode: - -@table @asis -@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} -@kindex F2 2 -@kindex C-x 6 2 -@findex 2C-two-columns -Enter two-column mode with the current buffer on the left, and on the -right, a buffer whose name is based on the current buffer's name -(@code{2C-two-columns}). If the right-hand buffer doesn't already -exist, it starts out empty; the current buffer's contents are not -changed. - -This command is appropriate when the current buffer is empty or contains -just one column and you want to add another column. - -@item @kbd{@key{F2} s} or @kbd{C-x 6 s} -@kindex F2 s -@kindex C-x 6 s -@findex 2C-split -Split the current buffer, which contains two-column text, into two -buffers, and display them side by side (@code{2C-split}). The current -buffer becomes the left-hand buffer, but the text in the right-hand -column is moved into the right-hand buffer. The current column -specifies the split point. Splitting starts with the current line and -continues to the end of the buffer. - -This command is appropriate when you have a buffer that already contains -two-column text, and you wish to separate the columns temporarily. - -@item @kbd{@key{F2} b @var{buffer} @key{RET}} -@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} -@kindex F2 b -@kindex C-x 6 b -@findex 2C-associate-buffer -Enter two-column mode using the current buffer as the left-hand buffer, -and using buffer @var{buffer} as the right-hand buffer -(@code{2C-associate-buffer}). -@end table - - @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which -is a string that appears on each line between the two columns. You can -specify the width of the separator with a numeric argument to -@kbd{@key{F2} s}; that many characters, before point, constitute the -separator string. By default, the width is 1, so the column separator -is the character before point. - - When a line has the separator at the proper place, @kbd{@key{F2} s} -puts the text after the separator into the right-hand buffer, and -deletes the separator. Lines that don't have the column separator at -the proper place remain unsplit; they stay in the left-hand buffer, and -the right-hand buffer gets an empty line to correspond. (This is the -way to write a line that ``spans both columns while in two-column -mode'': write it in the left-hand buffer, and put an empty line in the -right-hand buffer.) - -@kindex F2 RET -@kindex C-x 6 RET -@findex 2C-newline - The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} -(@code{2C-newline}) inserts a newline in each of the two buffers at -corresponding positions. This is the easiest way to add a new line to -the two-column text while editing it in split buffers. - -@kindex F2 1 -@kindex C-x 6 1 -@findex 2C-merge - When you have edited both buffers as you wish, merge them with -@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the -text from the right-hand buffer as a second column in the other buffer. -To go back to two-column editing, use @kbd{@key{F2} s}. - -@kindex F2 d -@kindex C-x 6 d -@findex 2C-dissociate - Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, -leaving each as it stands (@code{2C-dissociate}). If the other buffer, -the one not current when you type @kbd{@key{F2} d}, is empty, -@kbd{@key{F2} d} kills it. - -@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top -@section Editing Binary Files - -@cindex Hexl mode -@cindex mode, Hexl -@cindex editing binary files -@cindex hex editing - There is a special major mode for editing binary files: Hexl mode. To -use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit -the file. This command converts the file's contents to hexadecimal and -lets you edit the translation. When you save the file, it is converted -automatically back to binary. - - You can also use @kbd{M-x hexl-mode} to translate an existing buffer -into hex. This is useful if you visit a file normally and then discover -it is a binary file. - - Ordinary text characters overwrite in Hexl mode. This is to reduce -the risk of accidentally spoiling the alignment of data in the file. -There are special commands for insertion. Here is a list of the -commands of Hexl mode: - -@c I don't think individual index entries for these commands are useful--RMS. -@table @kbd -@item C-M-d -Insert a byte with a code typed in decimal. - -@item C-M-o -Insert a byte with a code typed in octal. - -@item C-M-x -Insert a byte with a code typed in hex. - -@item C-x [ -Move to the beginning of a 1k-byte ``page.'' - -@item C-x ] -Move to the end of a 1k-byte ``page.'' - -@item M-g -Move to an address specified in hex. - -@item M-j -Move to an address specified in decimal. - -@item C-c C-c -Leave Hexl mode, going back to the major mode this buffer had before you -invoked @code{hexl-mode}. -@end table - -@noindent -Other Hexl commands let you insert strings (sequences) of binary -bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a -hexl-@key{RET}} for details. - - -@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top -@section Saving Emacs Sessions -@cindex saving sessions -@cindex restore session -@cindex remember editing session -@cindex reload files -@cindex desktop - - Use the desktop library to save the state of Emacs from one session -to another. Once you save the Emacs @dfn{desktop}---the buffers, -their file names, major modes, buffer positions, and so on---then -subsequent Emacs sessions reload the saved desktop. - -@findex desktop-save -@vindex desktop-save-mode - You can save the desktop manually with the command @kbd{M-x -desktop-save}. You can also enable automatic saving of the desktop -when you exit Emacs, and automatic restoration of the last saved -desktop when Emacs starts: use the Customization buffer (@pxref{Easy -Customization}) to set @code{desktop-save-mode} to @code{t} for future -sessions, or add this line in your init file (@pxref{Init File}): - -@example -(desktop-save-mode 1) -@end example - -@findex desktop-change-dir -@findex desktop-revert - If you turn on @code{desktop-save-mode} in your init file, then when -Emacs starts, it looks for a saved desktop in the current directory. -Thus, you can have separate saved desktops in different directories, -and the starting directory determines which one Emacs reloads. You -can save the current desktop and reload one saved in another directory -by typing @kbd{M-x desktop-change-dir}. Typing @kbd{M-x -desktop-revert} reverts to the desktop previously reloaded. - - Specify the option @samp{--no-desktop} on the command line when you -don't want it to reload any saved desktop. This turns off -@code{desktop-save-mode} for the current session. Starting Emacs with -the @samp{--no-init-file} option also disables desktop reloading, -since it bypasses the init file, where @code{desktop-save-mode} is -usually turned on. - -@vindex desktop-restore-eager - By default, all the buffers in the desktop are restored at one go. -However, this may be slow if there are a lot of buffers in the -desktop. You can specify the maximum number of buffers to restore -immediately with the variable @code{desktop-restore-eager}; the -remaining buffers are restored ``lazily,'' when Emacs is idle. - -@findex desktop-clear -@vindex desktop-globals-to-clear -@vindex desktop-clear-preserve-buffers-regexp - Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills -all buffers except for internal ones, and clears the global variables -listed in @code{desktop-globals-to-clear}. If you want this to -preserve certain buffers, customize the variable -@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular -expression matching the names of buffers not to kill. - - If you want to save minibuffer history from one session to -another, use the @code{savehist} library. - -@node Recursive Edit, Emulation, Saving Emacs Sessions, Top -@section Recursive Editing Levels -@cindex recursive editing level -@cindex editing level, recursive - - A @dfn{recursive edit} is a situation in which you are using Emacs -commands to perform arbitrary editing while in the middle of another -Emacs command. For example, when you type @kbd{C-r} inside of a -@code{query-replace}, you enter a recursive edit in which you can change -the current buffer. On exiting from the recursive edit, you go back to -the @code{query-replace}. - -@kindex C-M-c -@findex exit-recursive-edit -@cindex exiting recursive edit - @dfn{Exiting} the recursive edit means returning to the unfinished -command, which continues execution. The command to exit is @kbd{C-M-c} -(@code{exit-recursive-edit}). - - You can also @dfn{abort} the recursive edit. This is like exiting, -but also quits the unfinished command immediately. Use the command -@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. - - The mode line shows you when you are in a recursive edit by displaying -square brackets around the parentheses that always surround the major and -minor mode names. Every window's mode line shows this in the same way, -since being in a recursive edit is true of Emacs as a whole rather than -any particular window or buffer. - - It is possible to be in recursive edits within recursive edits. For -example, after typing @kbd{C-r} in a @code{query-replace}, you may type a -command that enters the debugger. This begins a recursive editing level -for the debugger, within the recursive editing level for @kbd{C-r}. -Mode lines display a pair of square brackets for each recursive editing -level currently in progress. - - Exiting the inner recursive edit (such as with the debugger @kbd{c} -command) resumes the command running in the next level up. When that -command finishes, you can then use @kbd{C-M-c} to exit another recursive -editing level, and so on. Exiting applies to the innermost level only. -Aborting also gets out of only one level of recursive edit; it returns -immediately to the command level of the previous recursive edit. If you -wish, you can then abort the next recursive editing level. - - Alternatively, the command @kbd{M-x top-level} aborts all levels of -recursive edits, returning immediately to the top-level command -reader. It also exits the minibuffer, if it is active. - - The text being edited inside the recursive edit need not be the same text -that you were editing at top level. It depends on what the recursive edit -is for. If the command that invokes the recursive edit selects a different -buffer first, that is the buffer you will edit recursively. In any case, -you can switch buffers within the recursive edit in the normal manner (as -long as the buffer-switching keys have not been rebound). You could -probably do all the rest of your editing inside the recursive edit, -visiting files and all. But this could have surprising effects (such as -stack overflow) from time to time. So remember to exit or abort the -recursive edit when you no longer need it. - - In general, we try to minimize the use of recursive editing levels in -GNU Emacs. This is because they constrain you to ``go back'' in a -particular order---from the innermost level toward the top level. When -possible, we present different activities in separate buffers so that -you can switch between them as you please. Some commands switch to a -new major mode which provides a command to switch back. These -approaches give you more flexibility to go back to unfinished tasks in -the order you choose. - -@node Emulation, Hyperlinking, Recursive Edit, Top -@section Emulation -@cindex emulating other editors -@cindex other editors -@cindex EDT -@cindex vi -@cindex PC key bindings -@cindex scrolling all windows -@cindex PC selection -@cindex Motif key bindings -@cindex Macintosh key bindings -@cindex WordStar - - GNU Emacs can be programmed to emulate (more or less) most other -editors. Standard facilities can emulate these: - -@table @asis -@item CRiSP/Brief (PC editor) -@findex crisp-mode -@vindex crisp-override-meta-x -@findex scroll-all-mode -@cindex CRiSP mode -@cindex Brief emulation -@cindex emulation of Brief -@cindex mode, CRiSP -You can turn on key bindings to emulate the CRiSP/Brief editor with -@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs -unless you set the variable @code{crisp-override-meta-x}. You can -also use the command @kbd{M-x scroll-all-mode} or set the variable -@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature -(scrolling all windows together). - -@item EDT (DEC VMS editor) -@findex edt-emulation-on -@findex edt-emulation-off -Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, -while @kbd{M-x edt-emulation-off} restores normal Emacs command -bindings. - -Most of the EDT emulation commands are keypad keys, and most standard -Emacs key bindings are still available. The EDT emulation rebindings -are done in the global keymap, so there is no problem switching -buffers or major modes while in EDT emulation. - -@item TPU (DEC VMS editor) -@findex tpu-edt-on -@cindex TPU -@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. - -@item vi (Berkeley editor) -@findex viper-mode -Viper is the newest emulator for vi. It implements several levels of -emulation; level 1 is closest to vi itself, while level 5 departs -somewhat from strict emulation to take advantage of the capabilities of -Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you -the rest of the way and ask for the emulation level. @inforef{Top, -Viper, viper}. - -@item vi (another emulator) -@findex vi-mode -@kbd{M-x vi-mode} enters a major mode that replaces the previously -established major mode. All of the vi commands that, in real vi, enter -``input'' mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's ``input'' mode. - -Because vi emulation works through major modes, it does not work -to switch buffers during emulation. Return to normal Emacs first. - -If you plan to use vi emulation much, you probably want to bind a key -to the @code{vi-mode} command. - -@item vi (alternate emulator) -@findex vip-mode -@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator -is changed from ordinary Emacs so you can use @key{ESC} to go back to -emulated vi command mode. To get from emulated vi command mode back to -ordinary Emacs, type @kbd{C-z}. - -This emulation does not work through major modes, and it is possible -to switch buffers in various ways within the emulator. It is not -so necessary to assign a key to the command @code{vip-mode} as -it is with @code{vi-mode} because terminating insert mode does -not use it. - -@inforef{Top, VIP, vip}, for full information. - -@item WordStar (old wordprocessor) -@findex wordstar-mode -@kbd{M-x wordstar-mode} provides a major mode with WordStar-like -key bindings. -@end table - -@node Hyperlinking, Dissociated Press, Emulation, Top -@section Hyperlinking and Navigation Features - -@cindex hyperlinking -@cindex navigation - Various modes documented elsewhere have hypertext features so that -you can follow links, usually by clicking @kbd{Mouse-2} on the link or -typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1} -quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer -if you want to set point instead.) - - Info mode, Help mode and the Dired-like modes are examples of modes -that have links in the buffer. The Tags facility links between uses -and definitions in source files, see @ref{Tags}. Imenu provides -navigation amongst items indexed in the current buffer, see -@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions -in Info indexes, see @ref{Documentation}. Speedbar maintains a frame -in which links to files, and locations in files are displayed, see -@ref{Speedbar}. - - Other non-mode-specific facilities described in this section enable -following links from the current buffer in a context-sensitive -fashion. - -@menu -* Browse-URL:: Following URLs. -* Goto Address mode:: Activating URLs. -* FFAP:: Finding files etc. at point. -@end menu - -@node Browse-URL -@subsection Following URLs -@cindex World Wide Web -@cindex Web -@findex browse-url -@findex browse-url-at-point -@findex browse-url-at-mouse -@cindex Browse-URL -@cindex URLs - -@table @kbd -@item M-x browse-url @key{RET} @var{url} @key{RET} -Load a URL into a Web browser. -@end table - -The Browse-URL package provides facilities for following URLs specifying -links on the World Wide Web. Usually this works by invoking a web -browser, but you can, for instance, arrange to invoke @code{compose-mail} -from @samp{mailto:} URLs. - - The general way to use this feature is to type @kbd{M-x browse-url}, -which displays a specified URL. If point is located near a plausible -URL, that URL is used as the default. Other commands are available -which you might like to bind to keys, such as -@code{browse-url-at-point} and @code{browse-url-at-mouse}. - -@vindex browse-url-browser-function - You can customize Browse-URL's behavior via various options in the -@code{browse-url} Customize group, particularly -@code{browse-url-browser-function}. You can invoke actions dependent -on the type of URL by defining @code{browse-url-browser-function} as -an association list. The package's commentary available via @kbd{C-h -p} under the @samp{hypermedia} keyword provides more information. -Packages with facilities for following URLs should always go through -Browse-URL, so that the customization options for Browse-URL will -affect all browsing in Emacs. - -@node Goto Address mode -@subsection Activating URLs -@findex goto-address-mode -@cindex Goto Address mode -@cindex URLs, activating - -@table @kbd -@item M-x goto-address-mode -Activate URLs and e-mail addresses in the current buffer. -@end table - - You can make URLs in the current buffer active with @kbd{M-x -goto-address-mode}. This minor mode finds all the URLs in the buffer, -highlights them, and turns them into @dfn{buttons}: if you click on a -URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or -move to the URL and type @kbd{C-c @key{RET}}, that displays the web -page that the URL specifies. For a @samp{mailto} URL, it sends mail -instead, using your selected mail-composition method (@pxref{Mail -Methods}). - - It can be useful to add @code{goto-address-mode} to mode hooks and -the hooks used to display an incoming message (e.g., -@code{rmail-show-message-hook} for Rmail, and @code{mh-show-mode-hook} -for MH-E). This is not needed for Gnus, which has a similar feature -of its own. - -@node FFAP -@subsection Finding Files and URLs at Point -@findex find-file-at-point -@findex ffap -@findex dired-at-point -@findex ffap-next -@findex ffap-menu -@cindex finding file at point - - FFAP mode replaces certain key bindings for finding files, including -@kbd{C-x C-f}, with commands that provide more sensitive defaults. -These commands behave like the ordinary ones when given a prefix -argument. Otherwise, they get the default file name or URL from the -text around point. If what is found in the buffer has the form of a -URL rather than a file name, the commands use @code{browse-url} to -view it. - - This feature is useful for following references in mail or news -buffers, @file{README} files, @file{MANIFEST} files, and so on. The -@samp{ffap} package's commentary available via @kbd{C-h p} under the -@samp{files} keyword and the @code{ffap} Custom group provide details. - -@cindex FFAP minor mode -@findex ffap-mode - You can turn on FFAP minor mode by calling @code{ffap-bindings} to -make the following key bindings and to install hooks for using -@code{ffap} in Rmail, Gnus and VM article buffers. - -@table @kbd -@item C-x C-f @var{filename} @key{RET} -@kindex C-x C-f @r{(FFAP)} -Find @var{filename}, guessing a default from text around point -(@code{find-file-at-point}). -@item C-x C-r -@kindex C-x C-r @r{(FFAP)} -@code{ffap-read-only}, analogous to @code{find-file-read-only}. -@item C-x C-v -@kindex C-x C-v @r{(FFAP)} -@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. -@item C-x d @var{directory} @key{RET} -@kindex C-x d @r{(FFAP)} -Start Dired on @var{directory}, defaulting to the directory name at -point (@code{dired-at-point}). -@item C-x C-d -@code{ffap-list-directory}, analogous to @code{list-directory}. -@item C-x 4 f -@kindex C-x 4 f @r{(FFAP)} -@code{ffap-other-window}, analogous to @code{find-file-other-window}. -@item C-x 4 r -@code{ffap-read-only-other-window}, analogous to -@code{find-file-read-only-other-window}. -@item C-x 4 d -@code{ffap-dired-other-window}, analogous to @code{dired-other-window}. -@item C-x 5 f -@kindex C-x 5 f @r{(FFAP)} -@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. -@item C-x 5 r -@code{ffap-read-only-other-frame}, analogous to -@code{find-file-read-only-other-frame}. -@item C-x 5 d -@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. -@item M-x ffap-next -Search buffer for next file name or URL, then find that file or URL. -@item S-Mouse-3 -@kindex S-Mouse-3 @r{(FFAP)} -@code{ffap-at-mouse} finds the file guessed from text around the position -of a mouse click. -@item C-S-Mouse-3 -@kindex C-S-Mouse-3 @r{(FFAP)} -Display a menu of files and URLs mentioned in current buffer, then -find the one you select (@code{ffap-menu}). -@end table - -@node Dissociated Press, Amusements, Hyperlinking, Top -@section Dissociated Press - -@findex dissociated-press - @kbd{M-x dissociated-press} is a command for scrambling a file of text -either word by word or character by character. Starting from a buffer of -straight English, it produces extremely amusing output. The input comes -from the current Emacs buffer. Dissociated Press writes its output in a -buffer named @samp{*Dissociation*}, and redisplays that buffer after every -couple of lines (approximately) so you can read the output as it comes out. - - Dissociated Press asks every so often whether to continue generating -output. Answer @kbd{n} to stop it. You can also stop at any time by -typing @kbd{C-g}. The dissociation output remains in the -@samp{*Dissociation*} buffer for you to copy elsewhere if you wish. - -@cindex presidentagon - Dissociated Press operates by jumping at random from one point in -the buffer to another. In order to produce plausible output rather -than gibberish, it insists on a certain amount of overlap between the -end of one run of consecutive words or characters and the start of the -next. That is, if it has just output `president' and then decides to -jump to a different point in the buffer, it might spot the `ent' in -`pentagon' and continue from there, producing `presidentagon'. Long -sample texts produce the best results. - -@cindex againformation - A positive argument to @kbd{M-x dissociated-press} tells it to operate -character by character, and specifies the number of overlap characters. A -negative argument tells it to operate word by word, and specifies the number -of overlap words. In this mode, whole words are treated as the elements to -be permuted, rather than characters. No argument is equivalent to an -argument of two. For your againformation, the output goes only into the -buffer @samp{*Dissociation*}. The buffer you start with is not changed. - -@cindex Markov chain -@cindex ignoriginal -@cindex techniquitous - Dissociated Press produces results fairly like those of a Markov -chain based on a frequency table constructed from the sample text. It -is, however, an independent, ignoriginal invention. Dissociated Press -techniquitously copies several consecutive characters from the sample -text between random jumps, unlike a Markov chain which would jump -randomly after each word or character. This makes for more plausible -sounding results, and runs faster. - -@cindex outragedy -@cindex buggestion -@cindex properbose -@cindex mustatement -@cindex developediment -@cindex userenced - It is a mustatement that too much use of Dissociated Press can be a -developediment to your real work, sometimes to the point of outragedy. -And keep dissociwords out of your documentation, if you want it to be well -userenced and properbose. Have fun. Your buggestions are welcome. - -@node Amusements, Customization, Dissociated Press, Top -@section Other Amusements -@cindex boredom -@findex hanoi -@findex yow -@findex gomoku -@cindex tower of Hanoi - - If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are -considerably bored, give it a numeric argument. If you are very, very -bored, try an argument of 9. Sit back and watch. - -@cindex Go Moku - If you want a little more personal involvement, try @kbd{M-x gomoku}, -which plays the game Go Moku with you. - -@findex blackbox -@findex mpuz -@findex 5x5 -@cindex puzzles - @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are puzzles. -@code{blackbox} challenges you to determine the location of objects -inside a box by tomography. @code{mpuz} displays a multiplication -puzzle with letters standing for digits in a code that you must -guess---to guess a value, type a letter and then the digit you think it -stands for. The aim of @code{5x5} is to fill in all the squares. - -@findex decipher -@cindex ciphers -@cindex cryptanalysis -@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted -in a simple monoalphabetic substitution cipher. - -@findex dunnet - @kbd{M-x dunnet} runs an adventure-style exploration game, which is -a bigger sort of puzzle. - -@findex lm -@cindex landmark game -@kbd{M-x lm} runs a relatively non-participatory game in which a robot -attempts to maneuver towards a tree at the center of the window based on -unique olfactory cues from each of the four directions. - -@findex life -@cindex Life -@kbd{M-x life} runs Conway's ``Life'' cellular automaton. - -@findex morse-region -@findex unmorse-region -@cindex Morse code -@cindex --/---/.-./.../. -@kbd{M-x morse-region} converts text in a region to Morse code and -@kbd{M-x unmorse-region} converts it back. No cause for remorse. - -@findex pong -@cindex Pong game -@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing -bats. - -@findex solitaire -@cindex solitaire -@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs -across other pegs. - -@findex studlify-region -@cindex StudlyCaps -@kbd{M-x studlify-region} studlify-cases the region, producing -text like this: - -@example -M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region. -@end example - -@findex tetris -@cindex Tetris -@findex snake -@cindex Snake -@kbd{M-x tetris} runs an implementation of the well-known Tetris game. -Likewise, @kbd{M-x snake} provides an implementation of Snake. - - When you are frustrated, try the famous Eliza program. Just do -@kbd{M-x doctor}. End each input by typing @key{RET} twice. - -@cindex Zippy - When you are feeling strange, type @kbd{M-x yow}. - -@findex zone -The command @kbd{M-x zone} plays games with the display when Emacs is -idle. - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474 -@end ignore diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi deleted file mode 100644 index 78b70f7c1cf..00000000000 --- a/doc/emacs/msdog-xtra.texi +++ /dev/null @@ -1,619 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node MS-DOS -@section Emacs and MS-DOS -@cindex MS-DOG -@cindex MS-DOS peculiarities - - This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). -@iftex -Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows'') is in the main Emacs manual -(@pxref{Microsoft Windows,,, emacs, the Emacs Manual}). -@end iftex -@ifnottex -Information about peculiarities common to MS-DOS and Microsoft's -current operating systems Windows (also known as ``Losedows'') is in -@ref{Microsoft Windows}. -@end ifnottex - - If you build Emacs for MS-DOS, the binary will also run on Windows -3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS -application; all of this chapter applies for all of those systems, if -you use an Emacs that was built for MS-DOS. - -@iftex - @xref{Text and Binary,,,emacs, the Emacs Manual}, for information -@end iftex -@ifnottex - @xref{Text and Binary}, for information -@end ifnottex -about Emacs' special handling of text files under MS-DOS (and Windows). - -@menu -* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. -* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. -* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. -* Files: MS-DOS File Names. File name conventions on MS-DOS. -* Printing: MS-DOS Printing. Printing specifics on MS-DOS. -* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. -* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. -@end menu - -@node MS-DOS Keyboard -@subsection Keyboard Usage on MS-DOS - -@kindex DEL @r{(MS-DOS)} -@kindex BS @r{(MS-DOS)} - The key that is called @key{DEL} in Emacs (because that's how it is -designated on most workstations) is known as @key{BS} (backspace) on a -PC. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act -as @kbd{C-d} for the same reasons. - -@kindex C-g @r{(MS-DOS)} -@kindex C-BREAK @r{(MS-DOS)} -@cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit -character, just like @kbd{C-g}. This is because Emacs cannot detect -that you have typed @kbd{C-g} until it is ready for more input. As a -consequence, you cannot use @kbd{C-g} to stop a running command -@iftex -(@pxref{Quitting,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Quitting}). -@end ifnottex -By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you -type it (as @kbd{C-g} is on other systems), so it can be used to stop -a running command and for emergency escape -@iftex -(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Emergency Escape}). -@end ifnottex - -@cindex Meta (under MS-DOS) -@cindex Hyper (under MS-DOS) -@cindex Super (under MS-DOS) -@vindex dos-super-key -@vindex dos-hyper-key - The PC keyboard maps use the left @key{ALT} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{CTRL} key or the right @key{ALT} key by -setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 -or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is -also mapped to the @key{META} key. However, if the MS-DOS international -keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{ALT} to @key{META}, since it is used for -accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{ALT} as @key{META} -key. - -@kindex C-j @r{(MS-DOS)} -@vindex dos-keypad-mode - The variable @code{dos-keypad-mode} is a flag variable that controls -what key codes are returned by keys in the numeric keypad. You can also -define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the -following line into your @file{_emacs} file: - -@smallexample -;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) -@end smallexample - -@node MS-DOS Mouse -@subsection Mouse Usage on MS-DOS - -@cindex mouse support under MS-DOS - Emacs on MS-DOS supports a mouse (on the default terminal only). -The mouse commands work as documented, including those that use menus -and the menu bar -@iftex -(@pxref{Menu Bar,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Menu Bar}). -@end ifnottex - Scroll bars don't work in MS-DOS Emacs. PC mice usually have only -two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you -press both of them together, that has the effect of @kbd{Mouse-3}. If -the mouse does have 3 buttons, Emacs detects that at startup, and all -the 3 buttons function normally, as on X. - - Help strings for menu-bar and pop-up menus are displayed in the echo -area when the mouse pointer moves across the menu items. Highlighting -of mouse-sensitive text -@iftex -(@pxref{Mouse References,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Mouse References}) -@end ifnottex -is also supported. - -@cindex mouse, set number of buttons -@findex msdos-set-mouse-buttons - Some versions of mouse drivers don't report the number of mouse -buttons correctly. For example, mice with a wheel report that they -have 3 buttons, but only 2 of them are passed to Emacs; the clicks on -the wheel, which serves as the middle button, are not passed. In -these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command -to tell Emacs how many mouse buttons to expect. You could make such a -setting permanent by adding this fragment to your @file{_emacs} init -file: - -@example -;; @r{Treat the mouse like a 2-button mouse.} -(msdos-set-mouse-buttons 2) -@end example - -@cindex Windows clipboard support - Emacs built for MS-DOS supports clipboard operations when it runs on -Windows. Commands that put text on the kill ring, or yank text from -the ring, check the Windows clipboard first, just as Emacs does on the -X Window System -@iftex -(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Mouse Commands}). -@end ifnottex -Only the primary selection and the cut buffer are supported by MS-DOS -Emacs on Windows; the secondary selection always appears as empty. - - Due to the way clipboard access is implemented by Windows, the -length of text you can put into the clipboard is limited by the amount -of free DOS memory that is available to Emacs. Usually, up to 620KB of -text can be put into the clipboard, but this limit depends on the system -configuration and is lower if you run Emacs as a subprocess of -another program. If the killed text does not fit, Emacs outputs a -message saying so, and does not put the text into the clipboard. - - Null characters also cannot be put into the Windows clipboard. If the -killed text includes null characters, Emacs does not put such text into -the clipboard, and displays in the echo area a message to that effect. - -@vindex dos-display-scancodes - The variable @code{dos-display-scancodes}, when non-@code{nil}, -directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of -each keystroke; this feature serves as a complement to the -@code{view-lossage} command, for debugging. - -@node MS-DOS Display -@subsection Display on MS-DOS -@cindex faces under MS-DOS -@cindex fonts, emulating under MS-DOS - - Display on MS-DOS cannot use font variants, like bold or italic, but -it does support multiple faces, each of which can specify a foreground -and a background color. Therefore, you can get the full functionality -of Emacs packages that use fonts (such as @code{font-lock}, Enriched -Text mode, and others) by defining the relevant faces to use different -colors. Use the @code{list-colors-display} command -@iftex -(@pxref{Frame Parameters,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Frame Parameters}) -@end ifnottex -and the @code{list-faces-display} command -@iftex -(@pxref{Faces,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Faces}) -@end ifnottex -to see what colors and faces are available and what they look like. - - @xref{MS-DOS and MULE}, later in this chapter, for information on -how Emacs displays glyphs and characters that aren't supported by the -native font built into the DOS display. - -@cindex cursor shape on MS-DOS - When Emacs starts, it changes the cursor shape to a solid box. This -is for compatibility with other systems, where the box cursor is the -default in Emacs. This default shape can be changed to a bar by -specifying the @code{cursor-type} parameter in the variable -@code{default-frame-alist} -@iftex -(@pxref{Creating Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Creating Frames}). -@end ifnottex -The MS-DOS terminal doesn't support a vertical-bar cursor, -so the bar cursor is horizontal, and the @code{@var{width}} parameter, -if specified by the frame parameters, actually determines its height. -For this reason, the @code{bar} and @code{hbar} cursor types produce -the same effect on MS-DOS. As an extension, the bar cursor -specification can include the starting scan line of the cursor as well -as its width, like this: - -@example - '(cursor-type bar @var{width} . @var{start}) -@end example - -@noindent -In addition, if the @var{width} parameter is negative, the cursor bar -begins at the top of the character cell. - -@cindex frames on MS-DOS - The MS-DOS terminal can only display a single frame at a time. The -Emacs frame facilities work on MS-DOS much as they do on text-only -terminals -@iftex -(@pxref{Frames,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Frames}). -@end ifnottex -When you run Emacs from a DOS window on MS-Windows, you can make the -visible frame smaller than the full screen, but Emacs still cannot -display more than a single frame at a time. - -@cindex frame size under MS-DOS -@findex mode4350 -@findex mode25 - The @code{mode4350} command switches the display to 43 or 50 -lines, depending on your hardware; the @code{mode25} command switches -to the default 80x25 screen size. - - By default, Emacs only knows how to set screen sizes of 80 columns by -25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has -special video modes that will switch the display to other sizes, you can -have Emacs support those too. When you ask Emacs to switch the frame to -@var{n} rows by @var{m} columns dimensions, it checks if there is a -variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, -uses its value (which must be an integer) as the video mode to switch -to. (Emacs switches to that video mode by calling the BIOS @code{Set -Video Mode} function with the value of -@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) -For example, suppose your adapter will switch to 66x80 dimensions when -put into video mode 85. Then you can make Emacs support this screen -size by putting the following into your @file{_emacs} file: - -@example -(setq screen-dimensions-66x80 85) -@end example - - Since Emacs on MS-DOS can only set the frame size to specific -supported dimensions, it cannot honor every possible frame resizing -request. When an unsupported size is requested, Emacs chooses the next -larger supported size beyond the specified size. For example, if you -ask for 36x80 frame, you will get 40x80 instead. - - The variables @code{screen-dimensions-@var{n}x@var{m}} are used only -when they exactly match the specified size; the search for the next -larger supported size ignores them. In the above example, even if your -VGA supports 38x80 dimensions and you define a variable -@code{screen-dimensions-38x80} with a suitable value, you will still get -40x80 screen when you ask for a 36x80 frame. If you want to get the -38x80 size in this case, you can do it by setting the variable named -@code{screen-dimensions-36x80} with the same video mode value as -@code{screen-dimensions-38x80}. - - Changing frame dimensions on MS-DOS has the effect of changing all the -other frames to the new dimensions. - -@node MS-DOS File Names -@subsection File Names on MS-DOS -@cindex file names under MS-DOS -@cindex init file, default name under MS-DOS - - On MS-DOS, file names are case-insensitive and limited to eight -characters, plus optionally a period and three more characters. Emacs -knows enough about these limitations to handle file names that were -meant for other operating systems. For instance, leading dots -@samp{.} in file names are invalid in MS-DOS, so Emacs transparently -converts them to underscores @samp{_}; thus your default init file -@iftex -(@pxref{Init File,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Init File}) -@end ifnottex -is called @file{_emacs} on MS-DOS. Excess characters before or after -the period are generally ignored by MS-DOS itself; thus, if you visit -the file @file{LongFileName.EvenLongerExtension}, you will silently -get @file{longfile.eve}, but Emacs will still display the long file -name on the mode line. Other than that, it's up to you to specify -file names which are valid under MS-DOS; the transparent conversion as -described above only works on file names built into Emacs. - -@cindex backup file names on MS-DOS - The above restrictions on the file names on MS-DOS make it almost -impossible to construct the name of a backup file -@iftex -(@pxref{Backup Names,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Backup Names}) -@end ifnottex -without losing some of the original file name characters. For -example, the name of a backup file for @file{docs.txt} is -@file{docs.tx~} even if single backup is used. - -@cindex file names under Windows 95/NT -@cindex long file names in DOS box under Windows 95/NT - If you run Emacs as a DOS application under Windows 9X, Windows ME, or -Windows 2000/XP, you can turn on support for long file names. If you do -that, Emacs doesn't truncate file names or convert them to lower case; -instead, it uses the file names that you specify, verbatim. To enable -long file name support, set the environment variable @env{LFN} to -@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow -DOS programs to access long file names, so Emacs built for MS-DOS will -only see their short 8+3 aliases. - -@cindex @env{HOME} directory under MS-DOS - MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends -that the directory where it is installed is the value of the @env{HOME} -environment variable. That is, if your Emacs binary, -@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then -Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In -particular, that is where Emacs looks for the init file @file{_emacs}. -With this in mind, you can use @samp{~} in file names as an alias for -the home directory, as you would on GNU or Unix. You can also set -@env{HOME} variable in the environment before starting Emacs; its -value will then override the above default behavior. - - Emacs on MS-DOS handles the directory name @file{/dev} specially, -because of a feature in the emulator libraries of DJGPP that pretends -I/O devices have names in that directory. We recommend that you avoid -using an actual directory named @file{/dev} on any disk. - -@node MS-DOS Printing -@subsection Printing and MS-DOS - - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} -(@pxref{PostScript,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) -@end ifnottex -can work on MS-DOS by sending the output to one of the printer ports, -if a Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS. - -@iftex -@xref{Windows Printing,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@xref{Windows Printing}, -@end ifnottex -for details about setting up printing to a networked printer. - - Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even -though they are connected to a Windows machine which uses a different -encoding for the same locale. For example, in the Latin-1 locale, DOS -uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and -MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before -@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET -M-x lpr-region RET} will print the region while converting it to the -codepage 850 encoding. - -@vindex dos-printer -@vindex dos-ps-printer - For backwards compatibility, the value of @code{dos-printer} -(@code{dos-ps-printer}), if it has a value, overrides the value of -@code{printer-name} (@code{ps-printer-name}), on MS-DOS. - - -@node MS-DOS and MULE -@subsection International Support on MS-DOS -@cindex international support @r{(MS-DOS)} - - Emacs on MS-DOS supports the same international character sets as it -does on GNU, Unix and other platforms -@iftex -(@pxref{International,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{International}), -@end ifnottex -including coding systems for converting between the different -character sets. However, due to incompatibilities between -MS-DOS/MS-Windows and other systems, there are several DOS-specific -aspects of this support that you should be aware of. This section -describes these aspects. - - The description below is largely specific to the MS-DOS port of -Emacs, especially where it talks about practical implications for -Emacs users. - -@table @kbd -@item M-x dos-codepage-setup -Set up Emacs display and coding systems as appropriate for the current -DOS codepage. -@end table - -@cindex codepage, MS-DOS -@cindex DOS codepages - MS-DOS is designed to support one character set of 256 characters at -any given time, but gives you a variety of character sets to choose -from. The alternative character sets are known as @dfn{DOS codepages}. -Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 -characters (codes 128 through 255) vary from one codepage to another. -Each DOS codepage is identified by a 3-digit number, such as 850, 862, -etc. - - In contrast to X, which lets you use several fonts at the same time, -MS-DOS normally doesn't allow use of several codepages in a single -session. MS-DOS was designed to load a single codepage at system -startup, and require you to reboot in order to change -it@footnote{Normally, one particular codepage is burnt into the -display memory, while other codepages can be installed by modifying -system configuration files, such as @file{CONFIG.SYS}, and rebooting. -While there is third-party software that allows changing the codepage -without rebooting, we describe here how a stock MS-DOS system -behaves.}. Much the same limitation applies when you run DOS -executables on other systems such as MS-Windows. - -@vindex dos-codepage - For multibyte operation on MS-DOS, Emacs needs to know which -characters the chosen DOS codepage can display. So it queries the -system shortly after startup to get the chosen codepage number, and -stores the number in the variable @code{dos-codepage}. Some systems -return the default value 437 for the current codepage, even though the -actual codepage is different. (This typically happens when you use the -codepage built into the display hardware.) You can specify a different -codepage for Emacs to use by setting the variable @code{dos-codepage} in -your init file. - -@cindex language environment, automatic selection on @r{MS-DOS} - Multibyte Emacs supports only certain DOS codepages: those which can -display Far-Eastern scripts, like the Japanese codepage 932, and those -that encode a single ISO 8859 character set. - - The Far-Eastern codepages can directly display one of the MULE -character sets for these countries, so Emacs simply sets up to use the -appropriate terminal coding system that is supported by the codepage. -The special features described in the rest of this section mostly -pertain to codepages that encode ISO 8859 character sets. - - For the codepages which correspond to one of the ISO character sets, -Emacs knows the character set based on the codepage number. Emacs -automatically creates a coding system to support reading and writing -files that use the current codepage, and uses this coding system by -default. The name of this coding system is @code{cp@var{nnn}}, where -@var{nnn} is the codepage number.@footnote{The standard Emacs coding -systems for ISO 8859 are not quite right for the purpose, because -typically the DOS codepage does not match the standard ISO character -codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has -code 231 in the standard Latin-1 character set, but the corresponding -DOS codepage 850 uses code 135 for this glyph.} - -@cindex mode line @r{(MS-DOS)} - All the @code{cp@var{nnn}} coding systems use the letter @samp{D} -(for ``DOS'') as their mode-line mnemonic. Since both the terminal -coding system and the default coding system for file I/O are set to -the proper @code{cp@var{nnn}} coding system at startup, it is normal -for the mode line on MS-DOS to begin with @samp{-DD\-}. -@iftex -@xref{Mode Line,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Mode Line}. -@end ifnottex -Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding -systems, and thus their initial mode line looks like the Emacs -default. - - Since the codepage number also indicates which script you are using, -Emacs automatically runs @code{set-language-environment} to select the -language environment for that script -@iftex -(@pxref{Language Environments,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Language Environments}). -@end ifnottex - - If a buffer contains a character belonging to some other ISO 8859 -character set, not the one that the chosen DOS codepage supports, Emacs -displays it using a sequence of @acronym{ASCII} characters. For example, if the -current codepage doesn't have a glyph for the letter @samp{@`o} (small -@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where -the braces serve as a visual indication that this is a single character. -(This may look awkward for some non-Latin characters, such as those from -Greek or Hebrew alphabets, but it is still readable by a person who -knows the language.) Even though the character may occupy several -columns on the screen, it is really still just a single character, and -all Emacs commands treat it as one. - -@cindex MS-Windows codepages - MS-Windows provides its own codepages, which are different from the -DOS codepages for the same locale. For example, DOS codepage 850 -supports the same character set as Windows codepage 1252; DOS codepage -855 supports the same character set as Windows codepage 1251, etc. -The MS-Windows version of Emacs uses the current codepage for display -when invoked with the @samp{-nw} option. - -@node MS-DOS Processes -@subsection Subprocesses on MS-DOS - -@cindex compilation under MS-DOS -@cindex inferior processes under MS-DOS -@findex compile @r{(MS-DOS)} -@findex grep @r{(MS-DOS)} - Because MS-DOS is a single-process ``operating system,'' -asynchronous subprocesses are not available. In particular, Shell -mode and its variants do not work. Most Emacs features that use -asynchronous subprocesses also don't work on MS-DOS, including -Shell mode and GUD. When in doubt, try and see; commands that -don't work output an error message saying that asynchronous processes -aren't supported. - - Compilation under Emacs with @kbd{M-x compile}, searching files with -@kbd{M-x grep} and displaying differences between files with @kbd{M-x -diff} do work, by running the inferior processes synchronously. This -means you cannot do any more editing until the inferior process -finishes. - - Spell checking also works, by means of special support for synchronous -invocation of the @code{ispell} program. This is slower than the -asynchronous invocation on other platforms - - Instead of the Shell mode, which doesn't work on MS-DOS, you can use -the @kbd{M-x eshell} command. This invokes the Eshell package that -implements a Posix-like shell entirely in Emacs Lisp. - - By contrast, Emacs compiled as a native Windows application -@strong{does} support asynchronous subprocesses. -@iftex -@xref{Windows Processes,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Windows Processes}. -@end ifnottex - -@cindex printing under MS-DOS - Printing commands, such as @code{lpr-buffer} -@iftex -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. -@end iftex -@ifnottex -(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing}. -@end ifnottex - - When you run a subprocess synchronously on MS-DOS, make sure the -program terminates and does not try to read keyboard input. If the -program does not terminate on its own, you will be unable to terminate -it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these -cases. - - Accessing files on other machines is not supported on MS-DOS. Other -network-oriented commands such as sending mail, Web browsing, remote -login, etc., don't work either, unless network access is built into -MS-DOS with some network redirector. - -@cindex directory listing on MS-DOS -@vindex dired-listing-switches @r{(MS-DOS)} - Dired on MS-DOS uses the @code{ls-lisp} package where other -platforms use the system @code{ls} command. Therefore, Dired on -MS-DOS supports only some of the possible options you can mention in -the @code{dired-listing-switches} variable. The options that work are -@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, -@samp{-s}, @samp{-t}, and @samp{-u}. - -@ignore - arch-tag: 868d50ff-07f8-4a13-a807-dab6f1cdb431 -@end ignore diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi deleted file mode 100644 index 3634090c20e..00000000000 --- a/doc/emacs/msdog.texi +++ /dev/null @@ -1,921 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Microsoft Windows, Manifesto, Mac OS / GNUstep, Top -@appendix Emacs and Microsoft Windows/MS-DOS -@cindex Microsoft Windows -@cindex MS-Windows, Emacs peculiarities - - This section describes peculiarities of using Emacs on Microsoft -Windows. Some of these peculiarities are also relevant to Microsoft's -older MS-DOS ``operating system'' (also known as ``MS-DOG''). -However, Emacs features that are relevant @emph{only} to MS-DOS are -described in a separate -@iftex -manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -section (@pxref{MS-DOS}). -@end ifnottex - - - The behavior of Emacs on MS-Windows is reasonably similar to what is -documented in the rest of the manual, including support for long file -names, multiple frames, scroll bars, mouse menus, and subprocesses. -However, a few special considerations apply, and they are described -here. - -@menu -* Text and Binary:: Text files use CRLF to terminate lines. -* Windows Files:: File-name conventions on Windows. -* ls in Lisp:: Emulation of @code{ls} for Dired. -* Windows HOME:: Where Emacs looks for your @file{.emacs}. -* Windows Keyboard:: Windows-specific keyboard features. -* Windows Mouse:: Windows-specific mouse features. -* Windows Processes:: Running subprocesses on Windows. -* Windows Printing:: How to specify the printer on MS-Windows. -* Windows Fonts:: Specifying fonts on MS-Windows. -* Windows Misc:: Miscellaneous Windows features. -@ifnottex -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). -@end ifnottex -@end menu - -@node Text and Binary -@section Text Files and Binary Files -@cindex text and binary files on MS-DOS/MS-Windows - - GNU Emacs uses newline characters to separate text lines. This is the -convention used on GNU, Unix, and other Posix-compliant systems. - -@cindex end-of-line conversion on MS-DOS/MS-Windows - By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, -a two-character sequence, to separate text lines. (Linefeed is the same -character as newline.) Therefore, convenient editing of typical files -with Emacs requires conversion of these end-of-line (EOL) sequences. -And that is what Emacs normally does: it converts carriage-return -linefeed into newline when reading files, and converts newline into -carriage-return linefeed when writing files. The same mechanism that -handles conversion of international character codes does this conversion -also (@pxref{Coding Systems}). - -@cindex cursor location, on MS-DOS -@cindex point location, on MS-DOS - One consequence of this special format-conversion of most files is -that character positions as reported by Emacs (@pxref{Position Info}) do -not agree with the file size information known to the operating system. - - In addition, if Emacs recognizes from a file's contents that it uses -newline rather than carriage-return linefeed as its line separator, it -does not perform EOL conversion when reading or writing that file. -Thus, you can read and edit files from GNU and Unix systems on MS-DOS -with no special effort, and they will retain their Unix-style -end-of-line convention after you edit them. - - The mode line indicates whether end-of-line translation was used for -the current buffer. If MS-DOS end-of-line translation is in use for the -buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after -the coding system mnemonic near the beginning of the mode line -(@pxref{Mode Line}). If no EOL translation was performed, the string -@samp{(Unix)} is displayed instead of the backslash, to alert you that the -file's EOL format is not the usual carriage-return linefeed. - -@cindex DOS-to-Unix conversion of files - To visit a file and specify whether it uses DOS-style or Unix-style -end-of-line, specify a coding system (@pxref{Text Coding}). For -example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} -visits the file @file{foobar.txt} without converting the EOLs; if some -line ends with a carriage-return linefeed pair, Emacs will display -@samp{^M} at the end of that line. Similarly, you can direct Emacs to -save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} -command. For example, to save a buffer with Unix EOL format, type -@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file -with DOS EOL conversion, then save it with Unix EOL format, that -effectively converts the file to Unix EOL style, like @code{dos2unix}. - -@cindex untranslated file system -@findex add-untranslated-filesystem - When you use NFS, Samba, or some other similar method to access file -systems that reside on computers using GNU or Unix systems, Emacs -should not perform end-of-line translation on any files in these file -systems---not even when you create a new file. To request this, -designate these file systems as @dfn{untranslated} file systems by -calling the function @code{add-untranslated-filesystem}. It takes one -argument: the file system name, including a drive letter and -optionally a directory. For example, - -@example -(add-untranslated-filesystem "Z:") -@end example - -@noindent -designates drive Z as an untranslated file system, and - -@example -(add-untranslated-filesystem "Z:\\foo") -@end example - -@noindent -designates directory @file{\foo} on drive Z as an untranslated file -system. - - Most often you would use @code{add-untranslated-filesystem} in your -@file{.emacs} file, or in @file{site-start.el} so that all the users at -your site get the benefit of it. - -@findex remove-untranslated-filesystem - To countermand the effect of @code{add-untranslated-filesystem}, use -the function @code{remove-untranslated-filesystem}. This function takes -one argument, which should be a string just like the one that was used -previously with @code{add-untranslated-filesystem}. - - Designating a file system as untranslated does not affect character -set conversion, only end-of-line conversion. Essentially, it directs -Emacs to create new files with the Unix-style convention of using -newline at the end of a line. @xref{Coding Systems}. - -@vindex file-name-buffer-file-type-alist -@cindex binary files, on MS-DOS/MS-Windows - Some kinds of files should not be converted at all, because their -contents are not really text. Therefore, Emacs on MS-Windows distinguishes -certain files as @dfn{binary files}. (This distinction is not part of -MS-Windows; it is made by Emacs only.) Binary files include executable -programs, compressed archives, etc. Emacs uses the file name to decide -whether to treat a file as binary: the variable -@code{file-name-buffer-file-type-alist} defines the file-name patterns -that indicate binary files. If a file name matches one of the patterns -for binary files (those whose associations are of the type -@code{(@var{pattern} . t)}, Emacs reads and writes that file using the -@code{no-conversion} coding system (@pxref{Coding Systems}) which turns -off @emph{all} coding-system conversions, not only the EOL conversion. -@code{file-name-buffer-file-type-alist} also includes file-name patterns -for files which are known to be Windows-style text files with -carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs -always writes those files with Windows-style EOLs. - - If a file which belongs to an untranslated file system matches one of -the file-name patterns in @code{file-name-buffer-file-type-alist}, the -EOL conversion is determined by @code{file-name-buffer-file-type-alist}. - -@node Windows Files -@section File Names on MS-Windows -@cindex file names on MS-Windows - - MS-Windows and MS-DOS normally use a backslash, @samp{\}, to -separate name units within a file name, instead of the slash used on -other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or -backslash, and also knows about drive letters in file names. - -@cindex file-name completion, on MS-Windows - On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by -default ignores letter-case in file names during completion. - -@vindex w32-get-true-file-attributes - The variable @code{w32-get-true-file-attributes} controls whether -Emacs should issue additional system calls to determine more -accurately file attributes in primitives like @code{file-attributes} -and @code{directory-files-and-attributes}. These additional calls are -needed to report correct file ownership, link counts and file types -for special files such as pipes. Without these system calls, file -ownership will be attributed to the current user, link counts will be -always reported as 1, and special files will be reported as regular -files. - - If the value of this variable is @code{local} (the default), Emacs -will issue these additional system calls only for files on local fixed -drives. Any other non-@code{nil} value means do this even for -removable and remote volumes, where this could potentially slow down -Dired and other related features. The value of @code{nil} means never -issue those system calls. Non-@code{nil} values are more useful on -NTFS volumes, which support hard links and file security, than on FAT, -FAT32, and XFAT volumes. - -@node ls in Lisp -@section Emulation of @code{ls} on MS-Windows -@cindex Dired, and MS-Windows/MS-DOS -@cindex @code{ls} emulation - - Dired normally uses the external program @code{ls} (or its close -work-alike) to produce the directory listing displayed in Dired -buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't -come with such a program, although several ports of @sc{gnu} @code{ls} -are available. Therefore, Emacs on those systems @emph{emulates} -@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While -@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, -there are some options and features peculiar to that emulation; -@iftex -for more details, see the documentation of the variables whose names -begin with @code{ls-lisp}. -@end iftex -@ifnottex -they are described in this section. - - The @code{ls} emulation supports many of the @code{ls} switches, but -it doesn't support all of them. Here's the list of the switches it -does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, -@option{-c}, @option{-i}, @option{-G}, @option{-g}, @option{-R}, -@option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, -@option{-u}, and @option{-X}. The @option{-F} switch is partially -supported (it appends the character that classifies the file, but does -not prevent symlink following). - -@vindex ls-lisp-use-insert-directory-program - On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs -is built, so the Lisp emulation of @code{ls} is always used on those -platforms. If you have a ported @code{ls}, setting -@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value -will revert to using an external program named by the variable -@code{insert-directory-program}. - -@vindex ls-lisp-ignore-case - By default, @file{ls-lisp.el} uses a case-sensitive sort order for -the directory listing it produces; this is so the listing looks the -same as on other platforms. If you wish that the files be sorted in -case-insensitive order, set the variable @code{ls-lisp-ignore-case} to -a non-@code{nil} value. - -@vindex ls-lisp-dirs-first - By default, files and subdirectories are sorted together, to emulate -the behavior of @code{ls}. However, native MS-Windows/MS-DOS file -managers list the directories before the files; if you want that -behavior, customize the option @code{ls-lisp-dirs-first} to a -non-@code{nil} value. - -@vindex ls-lisp-verbosity - The variable @code{ls-lisp-verbosity} controls the file attributes -that @file{ls-lisp.el} displays. The value should be a list that -contains one or more of the symbols @code{links}, @code{uid}, and -@code{gid}. @code{links} means display the count of different file -names that are associated with (a.k.a.@: @dfn{links to}) the file's -data; this is only useful on NTFS volumes. @code{uid} means display -the numerical identifier of the user who owns the file. @code{gid} -means display the numerical identifier of the file owner's group. The -default value is @code{(links uid gid)} i.e.@: all the 3 optional -attributes are displayed. - -@vindex ls-lisp-emulation - The variable @code{ls-lisp-emulation} controls the flavour of the -@code{ls} emulation by setting the defaults for the 3 options -described above: @code{ls-lisp-ignore-case}, -@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of -this option can be one of the following symbols: - -@table @code -@item GNU -@itemx nil -Emulate @sc{gnu} systems; this is the default. This sets -@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to -@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. -@item UNIX -Emulate Unix systems. Like @code{GNU}, but sets -@code{ls-lisp-verbosity} to @code{(links uid)}. -@item MacOS -Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and -@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. -@item MS-Windows -Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and -@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to -@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X. -Note that the default emulation is @emph{not} @code{MS-Windows}, even -on Windows, since many users of Emacs on those platforms prefer the -@sc{gnu} defaults. -@end table - -@noindent -Any other value of @code{ls-lisp-emulation} means the same as -@code{GNU}. Note that this option needs to be set @emph{before} -@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS -you will have to set the value from your @file{.emacs} file and then -restart Emacs, since @file{ls-lisp.el} is preloaded. - -@vindex ls-lisp-support-shell-wildcards - The variable @code{ls-lisp-support-shell-wildcards} controls how -file-name patterns are supported: if it is non-@code{nil} (the -default), they are treated as shell-style wildcards; otherwise they -are treated as Emacs regular expressions. - -@vindex ls-lisp-format-time-list - The variable @code{ls-lisp-format-time-list} defines how to format -the date and time of files. @emph{The value of this variable is -ignored}, unless Emacs cannot determine the current locale. (However, -if the value of @code{ls-lisp-use-localized-time-format} is -non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if -the current locale is available; see below.) - -The value of @code{ls-lisp-format-time-list} is a list of 2 strings. -The first string is used if the file was modified within the current -year, while the second string is used for older files. In each of -these two strings you can use @samp{%}-sequences to substitute parts -of the time. For example: -@lisp -("%b %e %H:%M" "%b %e %Y") -@end lisp - -@noindent -Note that the strings substituted for these @samp{%}-sequences depend -on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp -Reference Manual}, for more about format time specs. - -@vindex ls-lisp-use-localized-time-format - Normally, Emacs formats the file time stamps in either traditional -or ISO-style time format. However, if the value of the variable -@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs -formats file time stamps according to what -@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in -@code{ls-lisp-format-time-list} produce locale-dependent month and day -names, which might cause misalignment of columns in Dired display. -@end ifnottex - -@node Windows HOME -@section HOME Directory on MS-Windows -@cindex @code{HOME} directory on MS-Windows - - The Windows equivalent of the @code{HOME} directory is the -@dfn{user-specific application data directory}. The actual location -depends on your Windows version and system configuration; typical values -are @file{C:\Documents and Settings\@var{username}\Application Data} on -Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data} -or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the -older Windows 9X/ME systems. - -@cindex init file @file{.emacs} on MS-Windows - The home directory is where your init file @file{.emacs} is stored. -When Emacs starts, it first checks whether the environment variable -@env{HOME} is set. If it is, it looks for the init file in the -directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs -checks for an existing @file{.emacs} file in @file{C:\}, the root -directory of drive @file{C:}@footnote{ -The check in @file{C:\} is for compatibility with older versions of Emacs, -which didn't check the application data directory. -}. If there's no such file in @file{C:\}, Emacs next uses the Windows -system calls to find out the exact location of your application data -directory. If that system call fails, Emacs falls back to @file{C:\}. - - Whatever the final place is, Emacs sets the value of the @env{HOME} -environment variable to point to it, and it will use that location for -other files and directories it normally creates in the user's home -directory. - - You can always find out where Emacs thinks is your home directory's -location by typing @kbd{C-x d ~/ @key{RET}}. This should present the -list of files in the home directory, and show its full name on the -first line. Likewise, to visit your init file, type @kbd{C-x C-f -~/.emacs @key{RET}}. - -@cindex @file{_emacs} init file, MS-Windows - Because MS-DOS does not allow file names with leading dots, and -because older Windows systems made it hard to create files with such -names, the Windows port of Emacs supports an alternative name -@file{_emacs} as a fallback, if such a file exists in the home -directory, whereas @file{.emacs} does not. - -@node Windows Keyboard -@section Keyboard Usage on MS-Windows -@cindex keyboard, MS-Windows - - This section describes the Windows-specific features related to -keyboard input in Emacs. - -@cindex MS-Windows keyboard shortcuts - Many key combinations (known as ``keyboard shortcuts'') that have -conventional uses in MS-Windows programs conflict with traditional -Emacs key bindings. (These Emacs key bindings were established years -before Microsoft was founded.) Examples of conflicts include -@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. -You can redefine some of them with meanings more like the MS-Windows -meanings by enabling CUA Mode (@pxref{CUA Bindings}). - -@kindex F10 @r{(MS-Windows)} -@cindex menu bar access using keyboard @r{(MS-Windows)} - The @key{F10} key on Windows activates the menu bar in a way that -makes it possible to use the menus without a mouse. In this mode, the -arrow keys traverse the menus, @key{RET} selects a highlighted menu -item, and @key{ESC} closes the menu. - -@iftex -@inforef{Windows Keyboard, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex -@ifnottex -@vindex w32-alt-is-meta -@cindex @code{Alt} key (MS-Windows) - By default, the key labeled @key{Alt} is mapped as the @key{META} -key. If you wish it to produce the @code{Alt} modifier instead, set -the variable @code{w32-alt-is-meta} to a @code{nil} value. - -@findex w32-register-hot-key -@findex w32-unregister-hot-key - MS-Windows reserves certain key combinations, such as -@kbd{Alt-@key{TAB}}, for its own use. These key combinations are -intercepted by the system before Emacs can see them. You can use the -@code{w32-register-hot-key} function to allow a key sequence to be -seen by Emacs instead of being grabbed by Windows. This functions -registers a key sequence as a @dfn{hot key}, overriding the special -meaning of that key sequence for Windows. (MS-Windows is told that -the key sequence is a hot key only when one of the Emacs windows has -focus, so that the special keys still have their usual meaning for -other Windows applications.) - - The argument to @code{w32-register-hot-key} must be a single key, -with or without modifiers, in vector form that would be acceptable to -@code{define-key}. The meta modifier is interpreted as the @key{ALT} -key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper -modifier is always interpreted as the Windows key (usually labeled -with @key{start} and the Windows logo). If the function succeeds in -registering the key sequence, it returns the hotkey ID, a number; -otherwise it returns @code{nil}. - -@kindex M-TAB@r{, (MS-Windows)} -@cindex @kbd{M-@key{TAB}} vs @kbd{Alt-@key{TAB}} (MS-Windows) -@cindex @kbd{Alt-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) - For example, @code{(w32-register-hot-key [M-tab])} lets you use -@kbd{M-TAB} normally in Emacs, for instance, to complete the word or -symbol at point at top level, or to complete the current search string -against previously sought strings during incremental search. - - The function @code{w32-unregister-hot-key} reverses the effect of -@code{w32-register-hot-key} for its argument key sequence. - -@vindex w32-capslock-is-shiftlock - By default, the @key{CapsLock} key only affects normal character -keys (it converts lower-case characters to their upper-case -variants). However, if you set the variable -@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the -@key{CapsLock} key will affect non-character keys as well, as if you -pressed the @key{Shift} key while typing the non-character key. - -@vindex w32-enable-caps-lock - If the variable @code{w32-enable-caps-lock} is set to a @code{nil} -value, the @key{CapsLock} key produces the symbol @code{capslock} -instead of the shifted version of they keys. The default value is -@code{t}. - -@vindex w32-enable-num-lock -@cindex keypad keys (MS-Windows) - Similarly, if @code{w32-enable-num-lock} is @code{nil}, the -@key{NumLock} key will produce the symbol @code{kp-numlock}. The -default is @code{t}, which causes @key{NumLock} to work as expected: -toggle the meaning of the keys on the numeric keypad. -@end ifnottex - -@vindex w32-apps-modifier - The variable @code{w32-apps-modifier} controls the effect of the -@key{Apps} key (usually located between the right @key{Alt} and the -right @key{Ctrl} keys). Its value can be one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} for the respective modifier, or @code{nil} to appear -as the key @code{apps}. The default is @code{nil}. - -@vindex w32-lwindow-modifier -@vindex w32-rwindow-modifier -@vindex w32-scroll-lock-modifier - The variable @code{w32-lwindow-modifier} determines the effect of -the left Windows key (usually labeled with @key{start} and the Windows -logo). If its value is @code{nil} (the default), the key will produce -the symbol @code{lwindow}. Setting it to one of the symbols -@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, -or @code{shift} will produce the respective modifier. A similar -variable @code{w32-rwindow-modifier} controls the effect of the right -Windows key, and @code{w32-scroll-lock-modifier} does the same for the -@key{ScrLock} key. If these variables are set to @code{nil}, the -right Windows key produces the symbol @code{rwindow} and @key{ScrLock} -produces the symbol @code{scroll}. - -@vindex w32-pass-alt-to-system -@cindex Windows system menu -@cindex @code{Alt} key invokes menu (Windows) - Emacs compiled as a native Windows application normally turns off -the Windows feature that tapping the @key{ALT} key invokes the Windows -menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. -When using Emacs, users often press the @key{META} key temporarily and -then change their minds; if this has the effect of bringing up the -Windows menu, it alters the meaning of subsequent commands. Many -users find this frustrating. - - You can re-enable Windows' default handling of tapping the @key{ALT} -key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} -value. - -@ifnottex -@vindex w32-pass-lwindow-to-system -@vindex w32-pass-rwindow-to-system - The variables @code{w32-pass-lwindow-to-system} and -@code{w32-pass-rwindow-to-system} determine whether the respective -keys are passed to Windows or swallowed by Emacs. If the value is -@code{nil}, the respective key is silently swallowed by Emacs, -otherwise it is passed to Windows. The default is @code{t} for both -of these variables. Passing each of these keys to Windows produces -its normal effect: for example, @kbd{@key{Lwindow}} opens the -@code{Start} menu, etc.@footnote{ -Some combinations of the ``Windows'' keys with other keys are caught -by Windows at low level in a way that Emacs currently cannot prevent. -For example, @kbd{@key{Lwindow} r} always pops up the Windows -@samp{Run} dialog. Customizing the value of -@code{w32-phantom-key-code} might help in some cases, though.} - -@vindex w32-recognize-altgr -@kindex AltGr @r{(MS-Windows)} -@cindex AltGr key (MS-Windows) - The variable @code{w32-recognize-altgr} controls whether the -@key{AltGr} key (if it exists on your keyboard), or its equivalent, -the combination of the right @key{Alt} and left @key{Ctrl} keys -pressed together, is recognized as the @key{AltGr} key. The default -is @code{t}, which means these keys produce @code{AltGr}; setting it -to @code{nil} causes @key{AltGr} or the equivalent key combination to -be interpreted as the combination of @key{CTRL} and @key{META} -modifiers. -@end ifnottex - -@node Windows Mouse -@section Mouse Usage on MS-Windows -@cindex mouse, and MS-Windows - - This section describes the Windows-specific variables related to -mouse. - -@vindex w32-mouse-button-tolerance -@cindex simulation of middle mouse button - The variable @code{w32-mouse-button-tolerance} specifies the -time interval, in milliseconds, for faking middle mouse button press -on 2-button mice. If both mouse buttons are depressed within this -time interval, Emacs generates a middle mouse button click event -instead of a double click on one of the buttons. - -@vindex w32-pass-extra-mouse-buttons-to-system - If the variable @code{w32-pass-extra-mouse-buttons-to-system} is -non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to -Windows. - -@vindex w32-swap-mouse-buttons - The variable @code{w32-swap-mouse-buttons} controls which of the 3 -mouse buttons generates the @kbd{mouse-2} events. When it is -@code{nil} (the default), the middle button generates @kbd{mouse-2} -and the right button generates @kbd{mouse-3} events. If this variable -is non-@code{nil}, the roles of these two buttons are reversed. - -@node Windows Processes -@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP -@cindex subprocesses on MS-Windows - -@cindex DOS applications, running from Emacs - Emacs compiled as a native Windows application (as opposed to the DOS -version) includes full support for asynchronous subprocesses. -In the Windows version, synchronous and asynchronous subprocesses work -fine on both -Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows -applications. However, when you run a DOS application in a subprocess, -you may encounter problems or be unable to run the application at all; -and if you run two DOS applications at the same time in two -subprocesses, you may have to reboot your system. - -Since the standard command interpreter (and most command line utilities) -on Windows 9X are DOS applications, these problems are significant when -using that system. But there's nothing we can do about them; only -Microsoft can fix them. - -If you run just one DOS application subprocess, the subprocess should -work as expected as long as it is ``well-behaved'' and does not perform -direct screen access or other unusual actions. If you have a CPU -monitor application, your machine will appear to be 100% busy even when -the DOS application is idle, but this is only an artifact of the way CPU -monitors measure processor load. - -You must terminate the DOS application before you start any other DOS -application in a different subprocess. Emacs is unable to interrupt or -terminate a DOS subprocess. The only way you can terminate such a -subprocess is by giving it a command that tells its program to exit. - -If you attempt to run two DOS applications at the same time in separate -subprocesses, the second one that is started will be suspended until the -first one finishes, even if either or both of them are asynchronous. - -@cindex kill DOS application -If you can go to the first subprocess, and tell it to exit, the second -subprocess should continue normally. However, if the second subprocess -is synchronous, Emacs itself will be hung until the first subprocess -finishes. If it will not finish without user input, then you have no -choice but to reboot if you are running on Windows 9X. If you are -running on Windows NT/2K/XP, you can use a process viewer application to kill -the appropriate instance of NTVDM instead (this will terminate both DOS -subprocesses). - -If you have to reboot Windows 9X in this situation, do not use the -@code{Shutdown} command on the @code{Start} menu; that usually hangs the -system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose -@code{Shutdown}. That usually works, although it may take a few minutes -to do its job. - -@vindex w32-quote-process-args - The variable @code{w32-quote-process-args} controls how Emacs quotes -the process arguments. Non-@code{nil} means quote with the @code{"} -character. If the value is a character, use that character to escape -any quote characters that appear; otherwise chose a suitable escape -character based on the type of the program. - -@ifnottex -@findex w32-shell-execute - The function @code{w32-shell-execute} can be useful for writing -customized commands that run MS-Windows applications registered to -handle a certain standard Windows operation for a specific type of -document or file. This function is a wrapper around the Windows -@code{ShellExecute} API. See the MS-Windows API documentation for -more details. -@end ifnottex - -@node Windows Printing -@section Printing and MS-Windows - - Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and -@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and -MS-Windows by sending the output to one of the printer ports, if a -Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS and MS-Windows. - - Emacs on Windows automatically determines your default printer and -sets the variable @code{printer-name} to that printer's name. But in -some rare cases this can fail, or you may wish to use a different -printer from within Emacs. The rest of this section explains how to -tell Emacs which printer to use. - -@vindex printer-name@r{, (MS-DOS/MS-Windows)} - If you want to use your local printer, then set the Lisp variable -@code{lpr-command} to @code{""} (its default value on Windows) and -@code{printer-name} to the name of the printer port---for example, -@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or -@code{"COM1"} for a serial printer. You can also set -@code{printer-name} to a file name, in which case ``printed'' output -is actually appended to that file. If you set @code{printer-name} to -@code{"NUL"}, printed output is silently discarded (sent to the system -null device). - - You can also use a printer shared by another machine by setting -@code{printer-name} to the UNC share name for that printer---for -example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use -forward slashes or backslashes here.) To find out the names of shared -printers, run the command @samp{net view} from the command prompt to -obtain a list of servers, and @samp{net view @var{server-name}} to see -the names of printers (and directories) shared by that server. -Alternatively, click the @samp{Network Neighborhood} icon on your -desktop, and look for machines which share their printers via the -network. - -@cindex @samp{net use}, and printing on MS-Windows -@cindex networked printers (MS-Windows) - If the printer doesn't appear in the output of @samp{net view}, or -if setting @code{printer-name} to the UNC share name doesn't produce a -hardcopy on that printer, you can use the @samp{net use} command to -connect a local print port such as @code{"LPT2"} to the networked -printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ -Note that the @samp{net use} command requires the UNC share name to be -typed with the Windows-style backslashes, while the value of -@code{printer-name} can be set with either forward- or backslashes.} -causes Windows to @dfn{capture} the @code{LPT2} port and redirect the -printed material to the printer connected to the machine @code{joes_pc}. -After this command, setting @code{printer-name} to @code{"LPT2"} -should produce the hardcopy on the networked printer. - - With some varieties of Windows network software, you can instruct -Windows to capture a specific printer port such as @code{"LPT2"}, and -redirect it to a networked printer via the @w{@code{Control -Panel->Printers}} applet instead of @samp{net use}. - - If you set @code{printer-name} to a file name, it's best to use an -absolute file name. Emacs changes the working directory according to -the default directory of the current buffer, so if the file name in -@code{printer-name} is relative, you will end up with several such -files, each one in the directory of the buffer from which the printing -was done. - - If the value of @code{printer-name} is correct, but printing does -not produce the hardcopy on your printer, it is possible that your -printer does not support printing plain text (some cheap printers omit -this functionality). In that case, try the PostScript print commands, -described below. - -@findex print-buffer @r{(MS-DOS)} -@findex print-region @r{(MS-DOS)} -@vindex lpr-headers-switches @r{(MS-DOS)} - The commands @code{print-buffer} and @code{print-region} call the -@code{pr} program, or use special switches to the @code{lpr} program, to -produce headers on each printed page. MS-DOS and MS-Windows don't -normally have these programs, so by default, the variable -@code{lpr-headers-switches} is set so that the requests to print page -headers are silently ignored. Thus, @code{print-buffer} and -@code{print-region} produce the same output as @code{lpr-buffer} and -@code{lpr-region}, respectively. If you do have a suitable @code{pr} -program (for example, from GNU Coreutils), set -@code{lpr-headers-switches} to @code{nil}; Emacs will then call -@code{pr} to produce the page headers, and print the resulting output as -specified by @code{printer-name}. - -@vindex print-region-function @r{(MS-DOS)} -@cindex lpr usage under MS-DOS -@vindex lpr-command @r{(MS-DOS)} -@vindex lpr-switches @r{(MS-DOS)} - Finally, if you do have an @code{lpr} work-alike, you can set the -variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use -@code{lpr} for printing, as on other systems. (If the name of the -program isn't @code{lpr}, set @code{lpr-command} to specify where to -find it.) The variable @code{lpr-switches} has its standard meaning -when @code{lpr-command} is not @code{""}. If the variable -@code{printer-name} has a string value, it is used as the value for the -@code{-P} option to @code{lpr}, as on Unix. - -@findex ps-print-buffer @r{(MS-DOS)} -@findex ps-spool-buffer @r{(MS-DOS)} -@vindex ps-printer-name @r{(MS-DOS)} -@vindex ps-lpr-command @r{(MS-DOS)} -@vindex ps-lpr-switches @r{(MS-DOS)} - A parallel set of variables, @code{ps-lpr-command}, -@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript -Variables}), defines how PostScript files should be printed. These -variables are used in the same way as the corresponding variables -described above for non-PostScript printing. Thus, the value of -@code{ps-printer-name} is used as the name of the device (or file) to -which PostScript output is sent, just as @code{printer-name} is used -for non-PostScript printing. (There are two distinct sets of -variables in case you have two printers attached to two different -ports, and only one of them is a PostScript printer.) - -@cindex Ghostscript, use for PostScript printing - The default value of the variable @code{ps-lpr-command} is @code{""}, -which causes PostScript output to be sent to the printer port specified -by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to -the name of a program which will accept PostScript files. Thus, if you -have a non-PostScript printer, you can set this variable to the name of -a PostScript interpreter program (such as Ghostscript). Any switches -that need to be passed to the interpreter program are specified using -@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a -string, it will be added to the list of switches as the value for the -@code{-P} option. This is probably only useful if you are using -@code{lpr}, so when using an interpreter typically you would set -@code{ps-printer-name} to something other than a string so it is -ignored.) - - For example, to use Ghostscript for printing on the system's default -printer, put this in your @file{.emacs} file: - -@example -(setq ps-printer-name t) -(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") -(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" - "-sDEVICE=mswinpr2" - "-sPAPERSIZE=a4")) -@end example - -@noindent -(This assumes that Ghostscript is installed in the -@file{D:/gs6.01} directory.) - -@node Windows Fonts -@section Specifying Fonts on MS-Windows -@cindex font specification (MS Windows) - - Starting with Emacs 23, fonts are specified by their name, size -and optional properties. The format for specifying fonts comes from the -fontconfig library used in modern Free desktops: - -@example - [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]] -@end example - - The old XLFD based format is also supported for backwards compatibility. - - Emacs 23 supports a number of backends. Currently, the @code{gdi} -and @code{uniscribe} font backends are supported on Windows. The -@code{gdi} font backend is available on all versions of Windows, and -supports all fonts that are natively supported by Windows. The -@code{uniscribe} font backend is available on Windows 2000 and later, -and supports Truetype and Opentype fonts. Some languages requiring -complex layout can only be properly supported by the uniscribe -backend. By default, both backends are enabled if supported, with -@code{uniscribe} taking priority over @code{gdi}. - -@cindex font properties (MS Windows) -@noindent -Optional properties common to all font backends on MS-Windows are: - -@table @code - -@vindex font-weight-table @r{(MS-Windows)} -@item weight -Specifies the weight of the font. Special values @code{light}, -@code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified -without @code{weight=} (e.g., @kbd{Courier New-12:bold}). Otherwise, -the weight should be a numeric value between 100 and 900, or one of the -named weights in @code{font-weight-table}. If unspecified, a regular font -is assumed. - -@vindex font-slant-table @r{(MS-Windows)} -@item slant -Specifies whether the font is italic. Special values -@code{roman}, @code{italic} and @code{oblique} can be specified -without @code{slant=} (e.g., @kbd{Courier New-12:italic}). -Otherwise, the slant should be a numeric value, or one of the named -slants in @code{font-slant-table}. On Windows, any slant above 150 is -treated as italics, and anything below as roman. - -@item family -Specifies the font family, but normally this will be specified -at the start of the font name. - -@item pixelsize -Specifies the font size in pixels. This can be used instead -of the point size specified after the family name. - -@item adstyle -Specifies additional style information for the font. -On MS-Windows, the values @code{mono}, @code{sans}, @code{serif}, -@code{script} and @code{decorative} are recognized. These are most useful -as a fallback with the font family left unspecified. - -@vindex w32-charset-info-alist -@item registry -Specifies the character set registry that the font is -expected to cover. Most Truetype and Opentype fonts will be unicode fonts -that cover several national character sets, but you can narrow down the -selection of fonts to those that support a particular character set by -using a specific registry from @code{w32-charset-info-alist} here. - -@item spacing -Specifies how the font is spaced. The @code{p} spacing specifies -a proportional font, and @code{m} or @code{c} specify a monospaced font. - -@item foundry -Not used on Windows, but for informational purposes and to -prevent problems with code that expects it to be set, is set internally to -@code{raster} for bitmapped fonts, @code{outline} for scalable fonts, -or @code{unknown} if the type cannot be determined as one of those. -@end table - -@cindex font properties (MS Windows gdi backend) -Options specific to @code{GDI} fonts: - -@table @code - -@cindex font scripts (MS Windows) -@cindex font unicode subranges (MS Windows) -@item script -Specifies a unicode subrange the font should support. - -The following scripts are recognized on Windows: @code{latin}, @code{greek}, -@code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic}, -@code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali}, -@code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu}, -@code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao}, -@code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul}, -@code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham}, -@code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille}, -@code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana}, -@code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol}, -@code{musical-symbol}, and @code{mathematical}. - -@cindex font antialiasing (MS Windows) -@item antialias -Specifies the antialiasing to use for the font. The value @code{none} -means no antialiasing, @code{standard} means use standard antialiasing, -@code{subpixel} means use subpixel antialiasing (known as Cleartype on Windows), -and @code{natural} means use subpixel antialiasing with adjusted spacing between -letters. If unspecified, the font will use the system default antialiasing. -@end table - -@node Windows Misc -@section Miscellaneous Windows-specific features - - This section describes miscellaneous Windows-specific features. - -@vindex w32-use-visible-system-caret -@cindex screen reader software, MS-Windows - The variable @code{w32-use-visible-system-caret} is a flag that -determines whether to make the system caret visible. The default when -no screen reader software is in use is @code{nil}, which means Emacs -draws its own cursor to indicate the position of point. A -non-@code{nil} value means Emacs will indicate point location by the -system caret; this facilitates use of screen reader software, and is -the default when such software is detected when running Emacs. -When this variable is non-@code{nil}, other variables affecting the -cursor display have no effect. - -@iftex -@inforef{Windows Misc, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex - -@ifnottex -@vindex w32-grab-focus-on-raise -@cindex frame focus policy, MS-Windows - The variable @code{w32-grab-focus-on-raise}, if set to a -non-@code{nil} value causes a frame to grab focus when it is raised. -The default is @code{t}, which fits well with the Windows default -click-to-focus policy. -@end ifnottex - -@ifnottex -@include msdog-xtra.texi -@end ifnottex - -@ignore - arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2 -@end ignore diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi deleted file mode 100644 index 98713c79227..00000000000 --- a/doc/emacs/mule.texi +++ /dev/null @@ -1,1672 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node International, Major Modes, Frames, Top -@chapter International Character Set Support -@c This node is referenced in the tutorial. When renaming or deleting -@c it, the tutorial needs to be adjusted. (TUTORIAL.de) -@cindex MULE -@cindex international scripts -@cindex multibyte characters -@cindex encoding of characters - -@cindex Celtic -@cindex Chinese -@cindex Cyrillic -@cindex Czech -@cindex Devanagari -@cindex Hindi -@cindex Marathi -@cindex Ethiopic -@cindex German -@cindex Greek -@cindex Hebrew -@cindex IPA -@cindex Japanese -@cindex Korean -@cindex Lao -@cindex Latin -@cindex Polish -@cindex Romanian -@cindex Slovak -@cindex Slovenian -@cindex Thai -@cindex Tibetan -@cindex Turkish -@cindex Vietnamese -@cindex Dutch -@cindex Spanish - Emacs supports a wide variety of international character sets, -including European and Vietnamese variants of the Latin alphabet, as -well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, -Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, -Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. -Emacs also supports various encodings of these characters used by -other internationalized software, such as word processors and mailers. - - Emacs allows editing text with international characters by supporting -all the related activities: - -@itemize @bullet -@item -You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and -pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as -compilers, spell-checkers, and mailers). Setting your language -environment (@pxref{Language Environments}) takes care of setting up the -coding systems and other options for a specific language or culture. -Alternatively, you can specify how Emacs should encode or decode text -for each command; see @ref{Text Coding}. - -@item -You can display non-@acronym{ASCII} characters encoded by the various -scripts. This works by using appropriate fonts on graphics displays -(@pxref{Defining Fontsets}), and by sending special codes to text-only -displays (@pxref{Terminal Coding}). If some characters are displayed -incorrectly, refer to @ref{Undisplayable Characters}, which describes -possible problems and explains how to solve them. - -@item -You can insert non-@acronym{ASCII} characters or search for them. To do that, -you can specify an input method (@pxref{Select Input Method}) suitable -for your language, or use the default input method set up when you set -your language environment. If -your keyboard can produce non-@acronym{ASCII} characters, you can select an -appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs -will accept those characters. Latin-1 characters can also be input by -using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. - -On X Window systems, your locale should be set to an appropriate value -to make sure Emacs interprets keyboard input correctly; see -@ref{Language Environments, locales}. -@end itemize - - The rest of this chapter describes these issues in detail. - -@menu -* International Chars:: Basic concepts of multibyte characters. -* Enabling Multibyte:: Controlling whether to use multibyte characters. -* Language Environments:: Setting things up for the language you use. -* Input Methods:: Entering text characters not on your keyboard. -* Select Input Method:: Specifying your choice of input methods. -* Coding Systems:: Character set conversion when you read and - write files, and so on. -* Recognize Coding:: How Emacs figures out which conversion to use. -* Specify Coding:: Specifying a file's coding system explicitly. -* Output Coding:: Choosing coding systems for output. -* Text Coding:: Choosing conversion to use for file text. -* Communication Coding:: Coding systems for interprocess communication. -* File Name Coding:: Coding systems for file @emph{names}. -* Terminal Coding:: Specifying coding systems for converting - terminal input and output. -* Fontsets:: Fontsets are collections of fonts - that cover the whole spectrum of characters. -* Defining Fontsets:: Defining a new fontset. -* Modifying Fontsets:: Modifying an existing fontset. -* Undisplayable Characters:: When characters don't display. -* Unibyte Mode:: You can pick one European character set - to use without multibyte characters. -* Charsets:: How Emacs groups its internal character codes. -@end menu - -@node International Chars -@section Introduction to International Character Sets - - The users of international character sets and scripts have -established many more-or-less standard coding systems for storing -files. These coding systems are typically @dfn{multibyte}, meaning -that sequences of two or more bytes are used to represent individual -non-@acronym{ASCII} characters. - -@cindex Unicode - Internally, Emacs uses its own multibyte character encoding, which -is a superset of the @dfn{Unicode} standard. This internal encoding -allows characters from almost every known script to be intermixed in a -single buffer or string. Emacs translates between the multibyte -character encoding and various other coding systems when reading and -writing files, and when exchanging data with subprocesses. - -@kindex C-h h -@findex view-hello-file -@cindex undisplayable characters -@cindex @samp{?} in display - The command @kbd{C-h h} (@code{view-hello-file}) displays the file -@file{etc/HELLO}, which shows how to say ``hello'' in many languages. -This illustrates various scripts. If some characters can't be -displayed on your terminal, they appear as @samp{?} or as hollow boxes -(@pxref{Undisplayable Characters}). - - Keyboards, even in the countries where these character sets are -used, generally don't have keys for all the characters in them. You -can insert characters that your keyboard does not support, using -@kbd{C-q} (@code{quoted-insert}) or @kbd{C-x 8 @key{RET}} -(@code{ucs-insert}). @xref{Inserting Text}. Emacs also supports -various @dfn{input methods}, typically one for each script or -language, which make it easier to type characters in the script. -@xref{Input Methods}. - -@kindex C-x RET - The prefix key @kbd{C-x @key{RET}} is used for commands that pertain -to multibyte characters, coding systems, and input methods. - -@kindex C-x = -@findex what-cursor-position - The command @kbd{C-x =} (@code{what-cursor-position}) shows -information about the character at point. In addition to the -character position, which was described in @ref{Position Info}, this -command displays how the character is encoded. For instance, it -displays the following line in the echo area for the character -@samp{c}: - -@smallexample -Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 -@end smallexample - - The four values after @samp{Char:} describe the character that -follows point, first by showing it and then by giving its character -code in decimal, octal and hex. For a non-@acronym{ASCII} multibyte -character, these are followed by @samp{file} and the character's -representation, in hex, in the buffer's coding system, if that coding -system encodes the character safely and with a single byte -(@pxref{Coding Systems}). If the character's encoding is longer than -one byte, Emacs shows @samp{file ...}. - - As a special case, if the character lies in the range 128 (0200 -octal) through 159 (0237 octal), it stands for a ``raw'' byte that -does not correspond to any specific displayable character. Such a -``character'' lies within the @code{eight-bit-control} character set, -and is displayed as an escaped octal character code. In this case, -@kbd{C-x =} shows @samp{part of display ...} instead of @samp{file}. - -@cindex character set of character at point -@cindex font of character at point -@cindex text properties at point -@cindex face at point - With a prefix argument (@kbd{C-u C-x =}), this command displays a -detailed description of the character in a window: - -@itemize @bullet -@item -The character set name, and the codes that identify the character -within that character set; @acronym{ASCII} characters are identified -as belonging to the @code{ascii} character set. - -@item -The character's syntax and categories. - -@item -The character's encodings, both internally in the buffer, and externally -if you were to save the file. - -@item -What keys to type to input the character in the current input method -(if it supports the character). - -@item -If you are running Emacs on a graphical display, the font name and -glyph code for the character. If you are running Emacs on a text-only -terminal, the code(s) sent to the terminal. - -@item -The character's text properties (@pxref{Text Properties,,, -elisp, the Emacs Lisp Reference Manual}), including any non-default -faces used to display the character, and any overlays containing it -(@pxref{Overlays,,, elisp, the same manual}). -@end itemize - - Here's an example showing the Latin-1 character A with grave accent, -in a buffer whose coding system is @code{utf-8-unix}: - -@smallexample - character: @`A (192, #o300, #xc0) -preferred charset: unicode (Unicode (ISO10646)) - code point: 0xC0 - syntax: w which means: word - category: j:Japanese l:Latin v:Vietnamese - buffer code: #xC3 #x80 - file code: not encodable by coding system undecided-unix - display: by this font (glyph code) - xft:-unknown-DejaVu Sans Mono-normal-normal-normal-*-13-*-*-*-m-0-iso10646-1 (#x82) - -Character code properties: customize what to show - name: LATIN CAPITAL LETTER A WITH GRAVE - general-category: Lu (Letter, Uppercase) - decomposition: (65 768) ('A' '̀') - old-name: LATIN CAPITAL LETTER A GRAVE - -There are text properties here: - auto-composed t -@end smallexample - -@node Enabling Multibyte -@section Enabling Multibyte Characters - - By default, Emacs starts in multibyte mode: it stores the contents -of buffers and strings using an internal encoding that represents -non-@acronym{ASCII} characters using multi-byte sequences. Multibyte -mode allows you to use all the supported languages and scripts without -limitations. - -@cindex turn multibyte support on or off - Under very special circumstances, you may want to disable multibyte -character support, either for Emacs as a whole, or for a single -buffer. When multibyte characters are disabled in a buffer, we call -that @dfn{unibyte mode}. In unibyte mode, each character in the -buffer has a character code ranging from 0 through 255 (0377 octal); 0 -through 127 (0177 octal) represent @acronym{ASCII} characters, and 128 -(0200 octal) through 255 (0377 octal) represent non-@acronym{ASCII} -characters. - - To edit a particular file in unibyte representation, visit it using -@code{find-file-literally}. @xref{Visiting}. You can convert a -multibyte buffer to unibyte by saving it to a file, killing the -buffer, and visiting the file again with @code{find-file-literally}. -Alternatively, you can use @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}) and specify @samp{raw-text} -as the coding system with which to visit or save a file. @xref{Text -Coding}. Unlike @code{find-file-literally}, finding a file as -@samp{raw-text} doesn't disable format conversion, uncompression, or -auto mode selection. - -@vindex enable-multibyte-characters -@vindex default-enable-multibyte-characters -@cindex environment variables, and non-@acronym{ASCII} characters - To turn off multibyte character support by default, start Emacs with -the @samp{--unibyte} option (@pxref{Initial Options}), or set the -environment variable @env{EMACS_UNIBYTE}. You can also customize -@code{enable-multibyte-characters} or, equivalently, directly set the -variable @code{default-enable-multibyte-characters} to @code{nil} in -your init file to have basically the same effect as @samp{--unibyte}. -With @samp{--unibyte}, multibyte strings are not created during -initialization from the values of environment variables, -@file{/etc/passwd} entries etc., even if those contain -non-@acronym{ASCII} characters. - -@cindex Lisp files, and multibyte operation -@cindex multibyte operation, and Lisp files -@cindex unibyte operation, and Lisp files -@cindex init file, and non-@acronym{ASCII} characters - Emacs normally loads Lisp files as multibyte, regardless of whether -you used @samp{--unibyte}. This includes the Emacs initialization -file, @file{.emacs}, and the initialization files of Emacs packages -such as Gnus. However, you can specify unibyte loading for a -particular Lisp file, by putting @w{@samp{-*-unibyte: t;-*-}} in a -comment on the first line (@pxref{File Variables}). Then that file is -always loaded as unibyte text. The motivation for these conventions -is that it is more reliable to always load any particular Lisp file in -the same way. However, you can load a Lisp file as unibyte, on any -one occasion, by typing @kbd{C-x @key{RET} c raw-text @key{RET}} -immediately before loading it. - - The mode line indicates whether multibyte character support is -enabled in the current buffer. If it is, there are two or more -characters (most often two dashes) near the beginning of the mode -line, before the indication of the visited file's end-of-line -convention (colon, backslash, etc.). When multibyte characters -are not enabled, nothing precedes the colon except a single dash. -@xref{Mode Line}, for more details about this. - -@findex toggle-enable-multibyte-characters - To convert a unibyte session to a multibyte session, set -@code{default-enable-multibyte-characters} to @code{t}. Buffers which -were created in the unibyte session before you turn on multibyte -support will stay unibyte. You can turn on multibyte support in a -specific buffer by invoking the command -@code{toggle-enable-multibyte-characters} in that buffer. - -@node Language Environments -@section Language Environments -@cindex language environments - - All supported character sets are supported in Emacs buffers whenever -multibyte characters are enabled; there is no need to select a -particular language in order to display its characters in an Emacs -buffer. However, it is important to select a @dfn{language -environment} in order to set various defaults. Roughly speaking, the -language environment represents a choice of preferred script rather -than a choice of language. - - The language environment controls which coding systems to recognize -when reading text (@pxref{Recognize Coding}). This applies to files, -incoming mail, and any other text you read into Emacs. It may also -specify the default coding system to use when you create a file. Each -language environment also specifies a default input method. - -@findex set-language-environment -@vindex current-language-environment - To select a language environment, customize the variable -@code{current-language-environment} or use the command @kbd{M-x -set-language-environment}. It makes no difference which buffer is -current when you use this command, because the effects apply globally -to the Emacs session. The supported language environments include: - -@cindex Euro sign -@cindex UTF-8 -@quotation -ASCII, Belarusian, Bengali, Brazilian Portuguese, Bulgarian, -Chinese-BIG5, Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Chinese-GBK, -Chinese-GB18030, Croatian, Cyrillic-ALT, Cyrillic-ISO, Cyrillic-KOI8, -Czech, Devanagari, Dutch, English, Esperanto, Ethiopic, French, -Georgian, German, Greek, Gujarati, Hebrew, IPA, Italian, Japanese, -Kannada, Khmer, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, -Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated Latin-1 -with the Euro sign), Latvian, Lithuanian, Malayalam, Oriya, Polish, -Punjabi, Romanian, Russian, Sinhala, Slovak, Slovenian, Spanish, -Swedish, TaiViet, Tajik, Tamil, Telugu, Thai, Tibetan, Turkish, UTF-8 -(for a setup which prefers Unicode characters and files encoded in -UTF-8), Ukrainian, Vietnamese, Welsh, and Windows-1255 (for a setup -which prefers Cyrillic characters and files encoded in Windows-1255). -@end quotation - -@cindex fonts for various scripts -@cindex Intlfonts package, installation - To display the script(s) used by your language environment on a -graphical display, you need to have a suitable font. If some of the -characters appear as empty boxes, you should install the GNU Intlfonts -package, which includes fonts for most supported scripts.@footnote{If -you run Emacs on X, you need to inform the X server about the location -of the newly installed fonts with the following commands: - -@example - xset fp+ /usr/local/share/emacs/fonts - xset fp rehash -@end example -} -@xref{Fontsets}, for more details about setting up your fonts. - -@findex set-locale-environment -@vindex locale-language-names -@vindex locale-charset-language-names -@cindex locales - Some operating systems let you specify the character-set locale you -are using by setting the locale environment variables @env{LC_ALL}, -@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is -set, the first one that is nonempty specifies your locale for this -purpose.} During startup, Emacs looks up your character-set locale's -name in the system locale alias table, matches its canonical name -against entries in the value of the variables -@code{locale-charset-language-names} and @code{locale-language-names}, -and selects the corresponding language environment if a match is found. -(The former variable overrides the latter.) It also adjusts the display -table and terminal coding system, the locale coding system, the -preferred coding system as needed for the locale, and---last but not -least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. - - If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} -environment variables while running Emacs, you may want to invoke the -@code{set-locale-environment} function afterwards to readjust the -language environment from the new locale. - -@vindex locale-preferred-coding-systems - The @code{set-locale-environment} function normally uses the preferred -coding system established by the language environment to decode system -messages. But if your locale matches an entry in the variable -@code{locale-preferred-coding-systems}, Emacs uses the corresponding -coding system instead. For example, if the locale @samp{ja_JP.PCK} -matches @code{japanese-shift-jis} in -@code{locale-preferred-coding-systems}, Emacs uses that encoding even -though it might normally use @code{japanese-iso-8bit}. - - You can override the language environment chosen at startup with -explicit use of the command @code{set-language-environment}, or with -customization of @code{current-language-environment} in your init -file. - -@kindex C-h L -@findex describe-language-environment - To display information about the effects of a certain language -environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} -@key{RET}} (@code{describe-language-environment}). This tells you -which languages this language environment is useful for, and lists the -character sets, coding systems, and input methods that go with it. It -also shows some sample text to illustrate scripts used in this -language environment. If you give an empty input for @var{lang-env}, -this command describes the chosen language environment. -@anchor{Describe Language Environment} - -@vindex set-language-environment-hook - You can customize any language environment with the normal hook -@code{set-language-environment-hook}. The command -@code{set-language-environment} runs that hook after setting up the new -language environment. The hook functions can test for a specific -language environment by checking the variable -@code{current-language-environment}. This hook is where you should -put non-default settings for specific language environment, such as -coding systems for keyboard input and terminal output, the default -input method, etc. - -@vindex exit-language-environment-hook - Before it starts to set up the new language environment, -@code{set-language-environment} first runs the hook -@code{exit-language-environment-hook}. This hook is useful for undoing -customizations that were made with @code{set-language-environment-hook}. -For instance, if you set up a special key binding in a specific language -environment using @code{set-language-environment-hook}, you should set -up @code{exit-language-environment-hook} to restore the normal binding -for that key. - -@node Input Methods -@section Input Methods - -@cindex input methods - An @dfn{input method} is a kind of character conversion designed -specifically for interactive input. In Emacs, typically each language -has its own input method; sometimes several languages which use the same -characters can share one input method. A few languages support several -input methods. - - The simplest kind of input method works by mapping @acronym{ASCII} letters -into another alphabet; this allows you to use one other alphabet -instead of @acronym{ASCII}. The Greek and Russian input methods -work this way. - - A more powerful technique is composition: converting sequences of -characters into one letter. Many European input methods use composition -to produce a single non-@acronym{ASCII} letter from a sequence that consists of a -letter followed by accent characters (or vice versa). For example, some -methods convert the sequence @kbd{a'} into a single accented letter. -These input methods have no special commands of their own; all they do -is compose sequences of printing characters. - - The input methods for syllabic scripts typically use mapping followed -by composition. The input methods for Thai and Korean work this way. -First, letters are mapped into symbols for particular sounds or tone -marks; then, sequences of these which make up a whole syllable are -mapped into one syllable sign. - - Chinese and Japanese require more complex methods. In Chinese input -methods, first you enter the phonetic spelling of a Chinese word (in -input method @code{chinese-py}, among others), or a sequence of -portions of the character (input methods @code{chinese-4corner} and -@code{chinese-sw}, and others). One input sequence typically -corresponds to many possible Chinese characters. You select the one -you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, -@kbd{C-p}, and digits, which have special meanings in this situation. - - The possible characters are conceptually arranged in several rows, -with each row holding up to 10 alternatives. Normally, Emacs displays -just one row at a time, in the echo area; @code{(@var{i}/@var{j})} -appears at the beginning, to indicate that this is the @var{i}th row -out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to -display the next row or the previous row. - - Type @kbd{C-f} and @kbd{C-b} to move forward and backward among -the alternatives in the current row. As you do this, Emacs highlights -the current alternative with a special color; type @code{C-@key{SPC}} -to select the current alternative and use it as input. The -alternatives in the row are also numbered; the number appears before -the alternative. Typing a digit @var{n} selects the @var{n}th -alternative of the current row and uses it as input. - - @key{TAB} in these Chinese input methods displays a buffer showing -all the possible characters at once; then clicking @kbd{Mouse-2} on -one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they -do the highlighting in the buffer showing the possible characters, -rather than in the echo area. - - In Japanese input methods, first you input a whole word using -phonetic spelling; then, after the word is in the buffer, Emacs -converts it into one or more characters using a large dictionary. One -phonetic spelling corresponds to a number of different Japanese words; -to select one of them, use @kbd{C-n} and @kbd{C-p} to cycle through -the alternatives. - - Sometimes it is useful to cut off input method processing so that the -characters you have just entered will not combine with subsequent -characters. For example, in input method @code{latin-1-postfix}, the -sequence @kbd{e '} combines to form an @samp{e} with an accent. What if -you want to enter them as separate characters? - - One way is to type the accent twice; this is a special feature for -entering the separate letter and accent. For example, @kbd{e ' '} gives -you the two characters @samp{e'}. Another way is to type another letter -after the @kbd{e}---something that won't combine with that---and -immediately delete it. For example, you could type @kbd{e e @key{DEL} -'} to get separate @samp{e} and @samp{'}. - - Another method, more general but not quite as easy to type, is to use -@kbd{C-\ C-\} between two characters to stop them from combining. This -is the command @kbd{C-\} (@code{toggle-input-method}) used twice. -@ifnottex -@xref{Select Input Method}. -@end ifnottex - -@cindex incremental search, input method interference - @kbd{C-\ C-\} is especially useful inside an incremental search, -because it stops waiting for more characters to combine, and starts -searching for what you have already entered. - - To find out how to input the character after point using the current -input method, type @kbd{C-u C-x =}. @xref{Position Info}. - -@vindex input-method-verbose-flag -@vindex input-method-highlight-flag - The variables @code{input-method-highlight-flag} and -@code{input-method-verbose-flag} control how input methods explain -what is happening. If @code{input-method-highlight-flag} is -non-@code{nil}, the partial sequence is highlighted in the buffer (for -most input methods---some disable this feature). If -@code{input-method-verbose-flag} is non-@code{nil}, the list of -possible characters to type next is displayed in the echo area (but -not when you are in the minibuffer). - -@node Select Input Method -@section Selecting an Input Method - -@table @kbd -@item C-\ -Enable or disable use of the selected input method. - -@item C-x @key{RET} C-\ @var{method} @key{RET} -Select a new input method for the current buffer. - -@item C-h I @var{method} @key{RET} -@itemx C-h C-\ @var{method} @key{RET} -@findex describe-input-method -@kindex C-h I -@kindex C-h C-\ -Describe the input method @var{method} (@code{describe-input-method}). -By default, it describes the current input method (if any). This -description should give you the full details of how to use any -particular input method. - -@item M-x list-input-methods -Display a list of all the supported input methods. -@end table - -@findex set-input-method -@vindex current-input-method -@kindex C-x RET C-\ - To choose an input method for the current buffer, use @kbd{C-x -@key{RET} C-\} (@code{set-input-method}). This command reads the -input method name from the minibuffer; the name normally starts with the -language environment that it is meant to be used with. The variable -@code{current-input-method} records which input method is selected. - -@findex toggle-input-method -@kindex C-\ - Input methods use various sequences of @acronym{ASCII} characters to -stand for non-@acronym{ASCII} characters. Sometimes it is useful to -turn off the input method temporarily. To do this, type @kbd{C-\} -(@code{toggle-input-method}). To reenable the input method, type -@kbd{C-\} again. - - If you type @kbd{C-\} and you have not yet selected an input method, -it prompts for you to specify one. This has the same effect as using -@kbd{C-x @key{RET} C-\} to specify an input method. - - When invoked with a numeric argument, as in @kbd{C-u C-\}, -@code{toggle-input-method} always prompts you for an input method, -suggesting the most recently selected one as the default. - -@vindex default-input-method - Selecting a language environment specifies a default input method for -use in various buffers. When you have a default input method, you can -select it in the current buffer by typing @kbd{C-\}. The variable -@code{default-input-method} specifies the default input method -(@code{nil} means there is none). - - In some language environments, which support several different input -methods, you might want to use an input method different from the -default chosen by @code{set-language-environment}. You can instruct -Emacs to select a different default input method for a certain -language environment, if you wish, by using -@code{set-language-environment-hook} (@pxref{Language Environments, -set-language-environment-hook}). For example: - -@lisp -(defun my-chinese-setup () - "Set up my private Chinese environment." - (if (equal current-language-environment "Chinese-GB") - (setq default-input-method "chinese-tonepy"))) -(add-hook 'set-language-environment-hook 'my-chinese-setup) -@end lisp - -@noindent -This sets the default input method to be @code{chinese-tonepy} -whenever you choose a Chinese-GB language environment. - -You can instruct Emacs to activate a certain input method -automatically. For example: - -@lisp -(add-hook 'text-mode-hook - (lambda () (set-input-method "german-prefix"))) -@end lisp - -@noindent -This activates the input method ``german-prefix'' automatically in the -Text mode. - -@findex quail-set-keyboard-layout - Some input methods for alphabetic scripts work by (in effect) -remapping the keyboard to emulate various keyboard layouts commonly used -for those scripts. How to do this remapping properly depends on your -actual keyboard layout. To specify which layout your keyboard has, use -the command @kbd{M-x quail-set-keyboard-layout}. - -@findex quail-show-key - You can use the command @kbd{M-x quail-show-key} to show what key (or -key sequence) to type in order to input the character following point, -using the selected keyboard layout. The command @kbd{C-u C-x =} also -shows that information in addition to the other information about the -character. - -@findex list-input-methods - To see a list of all the supported input methods, type @kbd{M-x -list-input-methods}. The list gives information about each input -method, including the string that stands for it in the mode line. - -@node Coding Systems -@section Coding Systems -@cindex coding systems - - Users of various languages have established many more-or-less standard -coding systems for representing them. Emacs does not use these coding -systems internally; instead, it converts from various coding systems to -its own system when reading data, and converts the internal coding -system to other coding systems when writing data. Conversion is -possible in reading or writing files, in sending or receiving from the -terminal, and in exchanging data with subprocesses. - - Emacs assigns a name to each coding system. Most coding systems are -used for one language, and the name of the coding system starts with -the language name. Some coding systems are used for several -languages; their names usually start with @samp{iso}. There are also -special coding systems, such as @code{no-conversion}, @code{raw-text}, -and @code{emacs-internal}. - -@cindex international files from DOS/Windows systems - A special class of coding systems, collectively known as -@dfn{codepages}, is designed to support text encoded by MS-Windows and -MS-DOS software. The names of these coding systems are -@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the -codepage. You can use these encodings just like any other coding -system; for example, to visit a file encoded in codepage 850, type -@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} -@key{RET}}. - - In addition to converting various representations of non-@acronym{ASCII} -characters, a coding system can perform end-of-line conversion. Emacs -handles three different conventions for how to separate lines in a file: -newline, carriage-return linefeed, and just carriage-return. - -@table @kbd -@item C-h C @var{coding} @key{RET} -Describe coding system @var{coding}. - -@item C-h C @key{RET} -Describe the coding systems currently in use. - -@item M-x list-coding-systems -Display a list of all the supported coding systems. -@end table - -@kindex C-h C -@findex describe-coding-system - The command @kbd{C-h C} (@code{describe-coding-system}) displays -information about particular coding systems, including the end-of-line -conversion specified by those coding systems. You can specify a coding -system name as the argument; alternatively, with an empty argument, it -describes the coding systems currently selected for various purposes, -both in the current buffer and as the defaults, and the priority list -for recognizing coding systems (@pxref{Recognize Coding}). - -@findex list-coding-systems - To display a list of all the supported coding systems, type @kbd{M-x -list-coding-systems}. The list gives information about each coding -system, including the letter that stands for it in the mode line -(@pxref{Mode Line}). - -@cindex end-of-line conversion -@cindex line endings -@cindex MS-DOS end-of-line conversion -@cindex Macintosh end-of-line conversion - Each of the coding systems that appear in this list---except for -@code{no-conversion}, which means no conversion of any kind---specifies -how and whether to convert printing characters, but leaves the choice of -end-of-line conversion to be decided based on the contents of each file. -For example, if the file appears to use the sequence carriage-return -linefeed to separate lines, DOS end-of-line conversion will be used. - - Each of the listed coding systems has three variants which specify -exactly what to do for end-of-line conversion: - -@table @code -@item @dots{}-unix -Don't do any end-of-line conversion; assume the file uses -newline to separate lines. (This is the convention normally used -on Unix and GNU systems.) - -@item @dots{}-dos -Assume the file uses carriage-return linefeed to separate lines, and do -the appropriate conversion. (This is the convention normally used on -Microsoft systems.@footnote{It is also specified for MIME @samp{text/*} -bodies and in other network transport contexts. It is different -from the SGML reference syntax record-start/record-end format which -Emacs doesn't support directly.}) - -@item @dots{}-mac -Assume the file uses carriage-return to separate lines, and do the -appropriate conversion. (This is the convention normally used on the -Macintosh system.) -@end table - - These variant coding systems are omitted from the -@code{list-coding-systems} display for brevity, since they are entirely -predictable. For example, the coding system @code{iso-latin-1} has -variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and -@code{iso-latin-1-mac}. - -@cindex @code{undecided}, coding system - The coding systems @code{unix}, @code{dos}, and @code{mac} are -aliases for @code{undecided-unix}, @code{undecided-dos}, and -@code{undecided-mac}, respectively. These coding systems specify only -the end-of-line conversion, and leave the character code conversion to -be deduced from the text itself. - - The coding system @code{raw-text} is good for a file which is mainly -@acronym{ASCII} text, but may contain byte values above 127 which are -not meant to encode non-@acronym{ASCII} characters. With -@code{raw-text}, Emacs copies those byte values unchanged, and sets -@code{enable-multibyte-characters} to @code{nil} in the current buffer -so that they will be interpreted properly. @code{raw-text} handles -end-of-line conversion in the usual way, based on the data -encountered, and has the usual three variants to specify the kind of -end-of-line conversion to use. - - In contrast, the coding system @code{no-conversion} specifies no -character code conversion at all---none for non-@acronym{ASCII} byte values and -none for end of line. This is useful for reading or writing binary -files, tar files, and other files that must be examined verbatim. It, -too, sets @code{enable-multibyte-characters} to @code{nil}. - - The easiest way to edit a file with no conversion of any kind is with -the @kbd{M-x find-file-literally} command. This uses -@code{no-conversion}, and also suppresses other Emacs features that -might convert the file contents before you see them. @xref{Visiting}. - - The coding system @code{emacs-internal} (or @code{utf-8-emacs}, -which is equivalent) means that the file contains non-@acronym{ASCII} -characters stored with the internal Emacs encoding. This coding -system handles end-of-line conversion based on the data encountered, -and has the usual three variants to specify the kind of end-of-line -conversion. - -@node Recognize Coding -@section Recognizing Coding Systems - - Whenever Emacs reads a given piece of text, it tries to recognize -which coding system to use. This applies to files being read, output -from subprocesses, text from X selections, etc. Emacs can select the -right coding system automatically most of the time---once you have -specified your preferences. - - Some coding systems can be recognized or distinguished by which byte -sequences appear in the data. However, there are coding systems that -cannot be distinguished, not even potentially. For example, there is no -way to distinguish between Latin-1 and Latin-2; they use the same byte -values with different meanings. - - Emacs handles this situation by means of a priority list of coding -systems. Whenever Emacs reads a file, if you do not specify the coding -system to use, Emacs checks the data against each coding system, -starting with the first in priority and working down the list, until it -finds a coding system that fits the data. Then it converts the file -contents assuming that they are represented in this coding system. - - The priority list of coding systems depends on the selected language -environment (@pxref{Language Environments}). For example, if you use -French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use -Czech, you probably want Latin-2 to be preferred. This is one of the -reasons to specify a language environment. - -@findex prefer-coding-system - However, you can alter the coding system priority list in detail -with the command @kbd{M-x prefer-coding-system}. This command reads -the name of a coding system from the minibuffer, and adds it to the -front of the priority list, so that it is preferred to all others. If -you use this command several times, each use adds one element to the -front of the priority list. - - If you use a coding system that specifies the end-of-line conversion -type, such as @code{iso-8859-1-dos}, what this means is that Emacs -should attempt to recognize @code{iso-8859-1} with priority, and should -use DOS end-of-line conversion when it does recognize @code{iso-8859-1}. - -@vindex file-coding-system-alist - Sometimes a file name indicates which coding system to use for the -file. The variable @code{file-coding-system-alist} specifies this -correspondence. There is a special function -@code{modify-coding-system-alist} for adding elements to this list. For -example, to read and write all @samp{.txt} files using the coding system -@code{chinese-iso-8bit}, you can execute this Lisp expression: - -@smallexample -(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-iso-8bit) -@end smallexample - -@noindent -The first argument should be @code{file}, the second argument should be -a regular expression that determines which files this applies to, and -the third argument says which coding system to use for these files. - -@vindex inhibit-eol-conversion -@cindex DOS-style end-of-line display - Emacs recognizes which kind of end-of-line conversion to use based on -the contents of the file: if it sees only carriage-returns, or only -carriage-return linefeed sequences, then it chooses the end-of-line -conversion accordingly. You can inhibit the automatic use of -end-of-line conversion by setting the variable @code{inhibit-eol-conversion} -to non-@code{nil}. If you do that, DOS-style files will be displayed -with the @samp{^M} characters visible in the buffer; some people -prefer this to the more subtle @samp{(DOS)} end-of-line type -indication near the left edge of the mode line (@pxref{Mode Line, -eol-mnemonic}). - -@vindex inhibit-iso-escape-detection -@cindex escape sequences in files - By default, the automatic detection of coding system is sensitive to -escape sequences. If Emacs sees a sequence of characters that begin -with an escape character, and the sequence is valid as an ISO-2022 -code, that tells Emacs to use one of the ISO-2022 encodings to decode -the file. - - However, there may be cases that you want to read escape sequences -in a file as is. In such a case, you can set the variable -@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code -detection ignores any escape sequences, and never uses an ISO-2022 -encoding. The result is that all escape sequences become visible in -the buffer. - - The default value of @code{inhibit-iso-escape-detection} is -@code{nil}. We recommend that you not change it permanently, only for -one specific operation. That's because many Emacs Lisp source files -in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the -coding system @code{iso-2022-7bit}, and they won't be -decoded correctly when you visit those files if you suppress the -escape sequence detection. - -@vindex auto-coding-alist -@vindex auto-coding-regexp-alist -@vindex auto-coding-functions - The variables @code{auto-coding-alist}, -@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are -the strongest way to specify the coding system for certain patterns of -file names, or for files containing certain patterns; these variables -even override @samp{-*-coding:-*-} tags in the file itself. Emacs -uses @code{auto-coding-alist} for tar and archive files, to prevent it -from being confused by a @samp{-*-coding:-*-} tag in a member of the -archive and thinking it applies to the archive file as a whole. -Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that -RMAIL files, whose names in general don't match any particular -pattern, are decoded correctly. One of the builtin -@code{auto-coding-functions} detects the encoding for XML files. - -@vindex rmail-decode-mime-charset -@vindex rmail-file-coding-system - When you get new mail in Rmail, each message is translated -automatically from the coding system it is written in, as if it were a -separate file. This uses the priority list of coding systems that you -have specified. If a MIME message specifies a character set, Rmail -obeys that specification, unless @code{rmail-decode-mime-charset} is -@code{nil}. For reading and saving Rmail files themselves, Emacs uses -the coding system specified by the variable -@code{rmail-file-coding-system}. The default value is @code{nil}, -which means that Rmail files are not translated (they are read and -written in the Emacs internal character code). - -@node Specify Coding -@section Specifying a File's Coding System - - If Emacs recognizes the encoding of a file incorrectly, you can -reread the file using the correct coding system by typing @kbd{C-x -@key{RET} r @var{coding-system} @key{RET}}. To see what coding system -Emacs actually used to decode the file, look at the coding system -mnemonic letter near the left edge of the mode line (@pxref{Mode -Line}), or type @kbd{C-h C @key{RET}}. - -@vindex coding - You can specify the coding system for a particular file in the file -itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, -or a local variables list at the end (@pxref{File Variables}). You do -this by defining a value for the ``variable'' named @code{coding}. -Emacs does not really have a variable @code{coding}; instead of -setting a variable, this uses the specified coding system for the -file. For example, @samp{-*-mode: C; coding: latin-1;-*-} specifies -use of the Latin-1 coding system, as well as C mode. When you specify -the coding explicitly in the file, that overrides -@code{file-coding-system-alist}. - -@node Output Coding -@section Choosing Coding Systems for Output - -@vindex buffer-file-coding-system - Once Emacs has chosen a coding system for a buffer, it stores that -coding system in @code{buffer-file-coding-system}. That makes it the -default for operations that write from this buffer into a file, such -as @code{save-buffer} and @code{write-region}. You can specify a -different coding system for further file output from the buffer using -@code{set-buffer-file-coding-system} (@pxref{Text Coding}). - - You can insert any character Emacs supports into any Emacs buffer, -but most coding systems can only handle a subset of these characters. -Therefore, it's possible that the characters you insert cannot be -encoded with the coding system that will be used to save the buffer. -For example, you could visit a text file in Polish, encoded in -@code{iso-8859-2}, and add some Russian words to it. When you save -that buffer, Emacs cannot use the current value of -@code{buffer-file-coding-system}, because the characters you added -cannot be encoded by that coding system. - - When that happens, Emacs tries the most-preferred coding system (set -by @kbd{M-x prefer-coding-system} or @kbd{M-x -set-language-environment}). If that coding system can safely encode -all of the characters in the buffer, Emacs uses it, and stores its -value in @code{buffer-file-coding-system}. Otherwise, Emacs displays -a list of coding systems suitable for encoding the buffer's contents, -and asks you to choose one of those coding systems. - - If you insert the unsuitable characters in a mail message, Emacs -behaves a bit differently. It additionally checks whether the -most-preferred coding system is recommended for use in MIME messages; -if not, Emacs tells you that the most-preferred coding system is not -recommended and prompts you for another coding system. This is so you -won't inadvertently send a message encoded in a way that your -recipient's mail software will have difficulty decoding. (You can -still use an unsuitable coding system if you type its name in response -to the question.) - -@vindex sendmail-coding-system - When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has -four different ways to determine the coding system to use for encoding -the message text. It tries the buffer's own value of -@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise, -it uses the value of @code{sendmail-coding-system}, if that is -non-@code{nil}. The third way is to use the default coding system for -new files, which is controlled by your choice of language environment, -if that is non-@code{nil}. If all of these three values are @code{nil}, -Emacs encodes outgoing mail using the Latin-1 coding system. - -@node Text Coding -@section Specifying a Coding System for File Text - - In cases where Emacs does not automatically choose the right coding -system for a file's contents, you can use these commands to specify -one: - -@table @kbd -@item C-x @key{RET} f @var{coding} @key{RET} -Use coding system @var{coding} for saving or revisiting the visited -file in the current buffer. - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command. - -@item C-x @key{RET} r @var{coding} @key{RET} -Revisit the current file using the coding system @var{coding}. - -@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} -Convert a region that was decoded using coding system @var{wrong}, -decoding it using coding system @var{right} instead. -@end table - -@kindex C-x RET f -@findex set-buffer-file-coding-system - The command @kbd{C-x @key{RET} f} -(@code{set-buffer-file-coding-system}) sets the file coding system for -the current buffer---in other words, it says which coding system to -use when saving or reverting the visited file. You specify which -coding system using the minibuffer. If you specify a coding system -that cannot handle all of the characters in the buffer, Emacs warns -you about the troublesome characters when you actually save the -buffer. - -@cindex specify end-of-line conversion - You can also use this command to specify the end-of-line conversion -(@pxref{Coding Systems, end-of-line conversion}) for encoding the -current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will -cause Emacs to save the current buffer's text with DOS-style CRLF line -endings. - -@kindex C-x RET c -@findex universal-coding-system-argument - Another way to specify the coding system for a file is when you visit -the file. First use the command @kbd{C-x @key{RET} c} -(@code{universal-coding-system-argument}); this command uses the -minibuffer to read a coding system name. After you exit the minibuffer, -the specified coding system is used for @emph{the immediately following -command}. - - So if the immediately following command is @kbd{C-x C-f}, for example, -it reads the file using that coding system (and records the coding -system for when you later save the file). Or if the immediately following -command is @kbd{C-x C-w}, it writes the file using that coding system. -When you specify the coding system for saving in this way, instead -of with @kbd{C-x @key{RET} f}, there is no warning if the buffer -contains characters that the coding system cannot handle. - - Other file commands affected by a specified coding system include -@kbd{C-x i} and @kbd{C-x C-v}, as well as the other-window variants -of @kbd{C-x C-f}. @kbd{C-x @key{RET} c} also affects commands that -start subprocesses, including @kbd{M-x shell} (@pxref{Shell}). If the -immediately following command does not use the coding system, then -@kbd{C-x @key{RET} c} ultimately has no effect. - - An easy way to visit a file with no conversion is with the @kbd{M-x -find-file-literally} command. @xref{Visiting}. - -@vindex default-buffer-file-coding-system - The variable @code{default-buffer-file-coding-system} specifies the -choice of coding system to use when you create a new file. It applies -when you find a new file, and when you create a buffer and then save it -in a file. Selecting a language environment typically sets this -variable to a good choice of default coding system for that language -environment. - -@kindex C-x RET r -@findex revert-buffer-with-coding-system - If you visit a file with a wrong coding system, you can correct this -with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). -This visits the current file again, using a coding system you specify. - -@findex recode-region - If a piece of text has already been inserted into a buffer using the -wrong coding system, you can redo the decoding of it using @kbd{M-x -recode-region}. This prompts you for the proper coding system, then -for the wrong coding system that was actually used, and does the -conversion. It first encodes the region using the wrong coding system, -then decodes it again using the proper coding system. - -@node Communication Coding -@section Coding Systems for Interprocess Communication - - This section explains how to specify coding systems for use -in communication with other processes. - -@table @kbd -@item C-x @key{RET} x @var{coding} @key{RET} -Use coding system @var{coding} for transferring selections to and from -other window-based applications. - -@item C-x @key{RET} X @var{coding} @key{RET} -Use coding system @var{coding} for transferring @emph{one} -selection---the next one---to or from another window-based application. - -@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} -Use coding systems @var{input-coding} and @var{output-coding} for -subprocess input and output in the current buffer. - -@item C-x @key{RET} c @var{coding} @key{RET} -Specify coding system @var{coding} for the immediately following -command. -@end table - -@kindex C-x RET x -@kindex C-x RET X -@findex set-selection-coding-system -@findex set-next-selection-coding-system - The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) -specifies the coding system for sending selected text to other windowing -applications, and for receiving the text of selections made in other -applications. This command applies to all subsequent selections, until -you override it by using the command again. The command @kbd{C-x -@key{RET} X} (@code{set-next-selection-coding-system}) specifies the -coding system for the next selection made in Emacs or read by Emacs. - -@vindex x-select-request-type - The variable @code{x-select-request-type} specifies the data type to -request from the X Window System for receiving text selections from -other applications. If the value is @code{nil} (the default), Emacs -tries @code{COMPOUND_TEXT} and @code{UTF8_STRING}, in this order, and -uses various heuristics to choose the more appropriate of the two -results; if none of these succeed, Emacs falls back on @code{STRING}. -If the value of @code{x-select-request-type} is one of the symbols -@code{COMPOUND_TEXT}, @code{UTF8_STRING}, @code{STRING}, or -@code{TEXT}, Emacs uses only that request type. If the value is a -list of some of these symbols, Emacs tries only the request types in -the list, in order, until one of them succeeds, or until the list is -exhausted. - -@kindex C-x RET p -@findex set-buffer-process-coding-system - The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) -specifies the coding system for input and output to a subprocess. This -command applies to the current buffer; normally, each subprocess has its -own buffer, and thus you can use this command to specify translation to -and from a particular subprocess by giving the command in the -corresponding buffer. - - You can also use @kbd{C-x @key{RET} c} just before the command that -runs or starts a subprocess, to specify the coding system to use for -communication with that subprocess. - - The default for translation of process input and output depends on the -current language environment. - -@vindex locale-coding-system -@cindex decoding non-@acronym{ASCII} keyboard input on X - The variable @code{locale-coding-system} specifies a coding system -to use when encoding and decoding system strings such as system error -messages and @code{format-time-string} formats and time stamps. That -coding system is also used for decoding non-@acronym{ASCII} keyboard input on X -Window systems. You should choose a coding system that is compatible -with the underlying system's text representation, which is normally -specified by one of the environment variables @env{LC_ALL}, -@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order -specified above, whose value is nonempty is the one that determines -the text representation.) - -@vindex x-select-request-type - The variable @code{x-select-request-type} specifies a selection data -type of selection to request from the X server. The default value is -@code{nil}, which means Emacs tries @code{COMPOUND_TEXT} and -@code{UTF8_STRING}, and uses whichever result seems more appropriate. -You can explicitly specify the data type by setting the variable to -one of the symbols @code{COMPOUND_TEXT}, @code{UTF8_STRING}, -@code{STRING} and @code{TEXT}. - -@node File Name Coding -@section Coding Systems for File Names - -@table @kbd -@item C-x @key{RET} F @var{coding} @key{RET} -Use coding system @var{coding} for encoding and decoding file -@emph{names}. -@end table - -@vindex file-name-coding-system -@cindex file names with non-@acronym{ASCII} characters - The variable @code{file-name-coding-system} specifies a coding -system to use for encoding file names. It has no effect on reading -and writing the @emph{contents} of files. - -@findex set-file-name-coding-system -@kindex C-x @key{RET} F - If you set the variable to a coding system name (as a Lisp symbol or -a string), Emacs encodes file names using that coding system for all -file operations. This makes it possible to use non-@acronym{ASCII} -characters in file names---or, at least, those non-@acronym{ASCII} -characters which the specified coding system can encode. Use @kbd{C-x -@key{RET} F} (@code{set-file-name-coding-system}) to specify this -interactively. - - If @code{file-name-coding-system} is @code{nil}, Emacs uses a -default coding system determined by the selected language environment. -In the default language environment, non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. - - @strong{Warning:} if you change @code{file-name-coding-system} (or the -language environment) in the middle of an Emacs session, problems can -result if you have already visited files whose names were encoded using -the earlier coding system and cannot be encoded (or are encoded -differently) under the new coding system. If you try to save one of -these buffers under the visited file name, saving may use the wrong file -name, or it may get an error. If such a problem happens, use @kbd{C-x -C-w} to specify a new file name for that buffer. - -@findex recode-file-name - If a mistake occurs when encoding a file name, use the command -@kbd{M-x recode-file-name} to change the file name's coding -system. This prompts for an existing file name, its old coding -system, and the coding system to which you wish to convert. - -@node Terminal Coding -@section Coding Systems for Terminal I/O - -@table @kbd -@item C-x @key{RET} k @var{coding} @key{RET} -Use coding system @var{coding} for keyboard input. - -@item C-x @key{RET} t @var{coding} @key{RET} -Use coding system @var{coding} for terminal output. -@end table - -@kindex C-x RET t -@findex set-terminal-coding-system - The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) -specifies the coding system for terminal output. If you specify a -character code for terminal output, all characters output to the -terminal are translated into that coding system. - - This feature is useful for certain character-only terminals built to -support specific languages or character sets---for example, European -terminals that support one of the ISO Latin character sets. You need to -specify the terminal coding system when using multibyte text, so that -Emacs knows which characters the terminal can actually handle. - - By default, output to the terminal is not translated at all, unless -Emacs can deduce the proper coding system from your terminal type or -your locale specification (@pxref{Language Environments}). - -@kindex C-x RET k -@findex set-keyboard-coding-system -@vindex keyboard-coding-system - The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}) -or the variable @code{keyboard-coding-system} specifies the coding -system for keyboard input. Character-code translation of keyboard -input is useful for terminals with keys that send non-@acronym{ASCII} -graphic characters---for example, some terminals designed for ISO -Latin-1 or subsets of it. - - By default, keyboard input is translated based on your system locale -setting. If your terminal does not really support the encoding -implied by your locale (for example, if you find it inserts a -non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set -@code{keyboard-coding-system} to @code{nil} to turn off encoding. -You can do this by putting - -@lisp -(set-keyboard-coding-system nil) -@end lisp - -@noindent -in your init file. - - There is a similarity between using a coding system translation for -keyboard input, and using an input method: both define sequences of -keyboard input that translate into single characters. However, input -methods are designed to be convenient for interactive use by humans, and -the sequences that are translated are typically sequences of @acronym{ASCII} -printing characters. Coding systems typically translate sequences of -non-graphic characters. - -@node Fontsets -@section Fontsets -@cindex fontsets - - A font typically defines shapes for a single alphabet or script. -Therefore, displaying the entire range of scripts that Emacs supports -requires a collection of many fonts. In Emacs, such a collection is -called a @dfn{fontset}. A fontset is defined by a list of font specs, -each assigned to handle a range of character codes, and may fall back -on another fontset for characters which are not covered by the fonts -it specifies. - - Each fontset has a name, like a font. However, while fonts are -stored in the system and the available font names are defined by the -system, fontsets are defined within Emacs itself. Once you have -defined a fontset, you can use it within Emacs by specifying its name, -anywhere that you could use a single font. Of course, Emacs fontsets -can use only the fonts that the system supports; if certain characters -appear on the screen as hollow boxes, this means that the fontset in -use for them has no font for those characters.@footnote{The Emacs -installation instructions have information on additional font -support.} - - Emacs creates three fontsets automatically: the @dfn{standard -fontset}, the @dfn{startup fontset} and the @dfn{default fontset}. -The default fontset is most likely to have fonts for a wide variety of -non-@acronym{ASCII} characters and is the default fallback for the -other two fontsets, and if you set a default font rather than fontset. -However it does not specify font family names, so results can be -somewhat random if you use it directly. You can specify use of a -specific fontset with the @samp{-fn} option. For example, - -@example -emacs -fn fontset-standard -@end example - -@noindent -You can also specify a fontset with the @samp{Font} resource (@pxref{X -Resources}). - - If no fontset is specified for use, then Emacs uses an -@acronym{ASCII} font, with @samp{fontset-default} as a fallback for -characters the font does not cover. The standard fontset is only used if -explicitly requested, despite its name. - - A fontset does not necessarily specify a font for every character -code. If a fontset specifies no font for a certain character, or if it -specifies a font that does not exist on your system, then it cannot -display that character properly. It will display that character as an -empty box instead. - -@node Defining Fontsets -@section Defining fontsets - -@vindex standard-fontset-spec -@vindex w32-standard-fontset-spec -@vindex ns-standard-fontset-spec -@cindex standard fontset - When running on X, Emacs creates a standard fontset automatically according to the value -of @code{standard-fontset-spec}. This fontset's name is - -@example --*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard -@end example - -@noindent -or just @samp{fontset-standard} for short. - - On GNUstep and Mac, fontset-standard is created using the value of -@code{ns-standard-fontset-spec}, and on Windows it is -created using the value of @code{w32-standard-fontset-spec}. - - Bold, italic, and bold-italic variants of the standard fontset are -created automatically. Their names have @samp{bold} instead of -@samp{medium}, or @samp{i} instead of @samp{r}, or both. - -@cindex startup fontset - Emacs generates a fontset automatically, based on any default -@acronym{ASCII} font that you specify with the @samp{Font} resource or -the @samp{-fn} argument, or the default font that Emacs found when it -started. This is the @dfn{startup fontset} and its name is -@code{fontset-startup}. It does this by replacing the -@var{charset_registry} field with @samp{fontset}, and replacing -@var{charset_encoding} field with @samp{startup}, then using the -resulting string to specify a fontset. - - For instance, if you start Emacs this way, - -@example -emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" -@end example - -@noindent -Emacs generates the following fontset and uses it for the initial X -window frame: - -@example --*-courier-medium-r-normal-*-14-140-*-*-*-*-fontset-startup -@end example - - The startup fontset will use the font that you specify or a variant -with a different registry and encoding for all the characters which -are supported by that font, and fallback on @samp{fontset-default} for -other characters. - - With the X resource @samp{Emacs.Font}, you can specify a fontset name -just like an actual font name. But be careful not to specify a fontset -name in a wildcard resource like @samp{Emacs*Font}---that wildcard -specification matches various other resources, such as for menus, and -menus cannot handle fontsets. - - You can specify additional fontsets using X resources named -@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. -The resource value should have this form: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -@var{fontpattern} should have the form of a standard X font name, except -for the last two fields. They should have the form -@samp{fontset-@var{alias}}. - - The fontset has two names, one long and one short. The long name is -@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You -can refer to the fontset by either name. - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the -font to use for that character set. You can use this construct any -number of times in defining one fontset. - - For the other character sets, Emacs chooses a font based on -@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values -that describe the character set. For the @acronym{ASCII} character font, -@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which is what Emacs -does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@findex create-fontset-from-fontset-spec - The function that processes the fontset resource value to create the -fontset is called @code{create-fontset-from-fontset-spec}. You can also -call this function explicitly to create a fontset. - - @xref{Font X}, for more information about font naming in X. - -@node Modifying Fontsets -@section Modifying Fontsets -@cindex fontsets, modifying -@findex set-fontset-font - - Fontsets do not always have to be created from scratch. If only -minor changes are required it may be easier to modify an existing -fontset. Modifying @samp{fontset-default} will also affect other -fontsets that use it as a fallback, so can be an effective way of -fixing problems with the fonts that Emacs chooses for a particular -script. - -Fontsets can be modified using the function @code{set-fontset-font}, -specifying a character, a charset, a script, or a range of characters -to modify the font for, and a font-spec for the font to be used. Some -examples are: - -@example -;; Use Liberation Mono for latin-3 charset. -(set-fontset-font "fontset-default" 'iso-8859-3 "Liberation Mono") - -;; Prefer a big5 font for han characters -(set-fontset-font "fontset-default" 'han (font-spec :registry "big5") - nil 'prepend) - -;; Use DejaVu Sans Mono as a fallback in fontset-startup before -;; resorting to fontset-default. -(set-fontset-font "fontset-startup" nil "DejaVu Sans Mono" nil 'append) - -;; Use MyPrivateFont for the Unicode private use area. -(set-fontset-font "fontset-default" '(#xe000 . #xf8ff) "MyPrivateFont") - -@end example - - -@node Undisplayable Characters -@section Undisplayable Characters - - There may be a some non-@acronym{ASCII} characters that your terminal cannot -display. Most text-only terminals support just a single character -set (use the variable @code{default-terminal-coding-system} -(@pxref{Terminal Coding}) to tell Emacs which one); characters which -can't be encoded in that coding system are displayed as @samp{?} by -default. - - Graphical displays can display a broader range of characters, but -you may not have fonts installed for all of them; characters that have -no font appear as a hollow box. - - If you use Latin-1 characters but your terminal can't display -Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences -instead, e.g.@: @samp{"o} for o-umlaut. Load the library -@file{iso-ascii} to do this. - -@vindex latin1-display - If your terminal can display Latin-1, you can display characters -from other European character sets using a mixture of equivalent -Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable -@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} -sequences mostly correspond to those of the prefix input methods. - -@node Unibyte Mode -@section Unibyte Editing Mode - -@cindex European character sets -@cindex accented characters -@cindex ISO Latin character sets -@cindex Unibyte operation - The ISO 8859 Latin-@var{n} character sets define character codes in -the range 0240 to 0377 octal (160 to 255 decimal) to handle the -accented letters and punctuation needed by various European languages -(and some non-European ones). If you disable multibyte characters, -Emacs can still handle @emph{one} of these character codes at a time. -To specify @emph{which} of these codes to use, invoke @kbd{M-x -set-language-environment} and specify a suitable language environment -such as @samp{Latin-@var{n}}. - - For more information about unibyte operation, see @ref{Enabling -Multibyte}. Note particularly that you probably want to ensure that -your initialization files are read as unibyte if they contain -non-@acronym{ASCII} characters. - -@vindex unibyte-display-via-language-environment - Emacs can also display those characters, provided the terminal or font -in use supports them. This works automatically. Alternatively, on a -graphical display, Emacs can also display single-byte characters -through fontsets, in effect by displaying the equivalent multibyte -characters according to the current language environment. To request -this, set the variable @code{unibyte-display-via-language-environment} -to a non-@code{nil} value. - -@cindex @code{iso-ascii} library - If your terminal does not support display of the Latin-1 character -set, Emacs can display these characters as @acronym{ASCII} sequences which at -least give you a clear idea of what the characters are. To do this, -load the library @code{iso-ascii}. Similar libraries for other -Latin-@var{n} character sets could be implemented, but we don't have -them yet. - -@findex standard-display-8bit -@cindex 8-bit display - Normally non-ISO-8859 characters (decimal codes between 128 and 159 -inclusive) are displayed as octal escapes. You can change this for -non-standard ``extended'' versions of ISO-8859 character sets by using the -function @code{standard-display-8bit} in the @code{disp-table} library. - - There are two ways to input single-byte non-@acronym{ASCII} -characters: - -@itemize @bullet -@cindex 8-bit input -@item -You can use an input method for the selected language environment. -@xref{Input Methods}. When you use an input method in a unibyte buffer, -the non-@acronym{ASCII} character you specify with it is converted to unibyte. - -@item -If your keyboard can generate character codes 128 (decimal) and up, -representing non-@acronym{ASCII} characters, you can type those character codes -directly. - -On a graphical display, you should not need to do anything special to use -these keys; they should simply work. On a text-only terminal, you -should use the command @code{M-x set-keyboard-coding-system} or the -variable @code{keyboard-coding-system} to specify which coding system -your keyboard uses (@pxref{Terminal Coding}). Enabling this feature -will probably require you to use @kbd{ESC} to type Meta characters; -however, on a console terminal or in @code{xterm}, you can arrange for -Meta to be converted to @kbd{ESC} and still be able type 8-bit -characters present directly on the keyboard or using @kbd{Compose} or -@kbd{AltGr} keys. @xref{User Input}. - -@kindex C-x 8 -@cindex @code{iso-transl} library -@cindex compose character -@cindex dead character -@item -For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose -character'' prefix for entry of non-@acronym{ASCII} Latin-1 printing -characters. @kbd{C-x 8} is good for insertion (in the minibuffer as -well as other buffers), for searching, and in any other context where -a key sequence is allowed. - -@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that -library is loaded, the @key{ALT} modifier key, if the keyboard has -one, serves the same purpose as @kbd{C-x 8}: use @key{ALT} together -with an accent character to modify the following letter. In addition, -if the keyboard has keys for the Latin-1 ``dead accent characters,'' -they too are defined to compose with the following character, once -@code{iso-transl} is loaded. - -Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. -@end itemize - -@node Charsets -@section Charsets -@cindex charsets - - Emacs defines most of popular character sets (e.g. ascii, -iso-8859-1, cp1250, big5, unicode) as @dfn{charsets} and a few of its -own charsets (e.g. emacs, unicode-bmp, eight-bit). All supported -characters belong to one or more charsets. Usually you don't have to -take care of ``charset'', but knowing about it may help understanding -the behavior of Emacs in some cases. - - One example is a font selection. In each language environment, -charsets have different priorities. Emacs, at first, tries to use a -font that matches with charsets of higher priority. For instance, in -Japanese language environment, the charset @code{japanese-jisx0208} -has the highest priority (@pxref{Describe Language Environment}). So, -Emacs tries to use a font whose @code{registry} property is -``JISX0208.1983-0'' for characters belonging to that charset. - - Another example is a use of @code{charset} text property. When -Emacs reads a file encoded in a coding systems that uses escape -sequences to switch charsets (e.g. iso-2022-int-1), the buffer text -keep the information of the original charset by @code{charset} text -property. By using this information, Emacs can write the file with -the same byte sequence as the original. - -@findex list-charset-chars -@cindex characters in a certain charset -@findex describe-character-set - There are two commands for obtaining information about Emacs -charsets. The command @kbd{M-x list-charset-chars} prompts for a -charset name, and displays all the characters in that character set. -The command @kbd{M-x describe-character-set} prompts for a charset -name and displays information about that charset, including its -internal representation within Emacs. - -@findex list-character-sets - To display a list of all the supported charsets, type @kbd{M-x -list-character-sets}. The list gives the names of charsets and -additional information to identity each charset (see ISO/IEC's this -page for the detail). In the -list, charsets are categorized into two; the normal charsets are -listed first, and the supplementary charsets are listed last. A -charset in the latter category is used for defining another charset -(as a parent or a subset), or was used only in Emacs of the older -versions. - - To find out which charset a character in the buffer belongs to, -put point before it and type @kbd{C-u C-x =}. - -@ignore - arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3 -@end ignore diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi deleted file mode 100644 index 64476b62d70..00000000000 --- a/doc/emacs/picture-xtra.texi +++ /dev/null @@ -1,291 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in emacs-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). -@node Picture Mode -@chapter Editing Pictures -@cindex pictures -@cindex making pictures out of text characters -@findex picture-mode - - To edit a picture made out of text characters (for example, a picture -of the division of a register into fields, as a comment in a program), -use the command @kbd{M-x picture-mode} to enter Picture mode. - - In Picture mode, editing is based on the @dfn{quarter-plane} model of -text, according to which the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the end -of a line does not exist in this model; the most you can say is where the -last nonblank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But Picture mode replaces -the most frequently-used commands with variants that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture mode -to do essentially the same thing but in a quarter-plane way. In addition, -Picture mode defines various keys starting with the @kbd{C-c} prefix to -run special picture editing commands. - - One of these keys, @kbd{C-c C-c}, is particularly important. Often -a picture is part of a larger file that is usually edited in some -other major mode. Picture mode records the name of the previous major -mode so you can use the @kbd{C-c C-c} command -(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c -C-c} also deletes spaces from the ends of lines, unless given a -numeric argument. - - The special commands of Picture mode all work in other modes (provided -the @file{picture} library is loaded), but are not bound to keys except -in Picture mode. The descriptions below talk of moving ``one column'' -and so on, but all the picture mode commands handle numeric arguments as -their normal equivalents do. - -@vindex picture-mode-hook - Turning on Picture mode runs the hook @code{picture-mode-hook}. -Additional extensions to Picture mode can be found in -@file{artist.el}. - -@menu -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end menu - -@node Basic Picture -@section Basic Editing in Picture Mode - -@findex picture-forward-column -@findex picture-backward-column -@findex picture-move-down -@findex picture-move-up -@cindex editing in Picture mode - - Most keys do the same thing in Picture mode that they usually do, but -do it in a quarter-plane style. For example, @kbd{C-f} is rebound to -run @code{picture-forward-column}, a command which moves point one -column to the right, inserting a space if necessary so that the actual -end of the line makes no difference. @kbd{C-b} is rebound to run -@code{picture-backward-column}, which always moves point left one -column, converting a tab to multiple spaces if necessary. @kbd{C-n} and -@kbd{C-p} are rebound to run @code{picture-move-down} and -@code{picture-move-up}, which can either insert spaces or convert tabs -as necessary to make sure that point stays in exactly the same column. -@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last -nonblank character on the line. There is no need to change @kbd{C-a}, -as the choice of screen model does not affect beginnings of -lines. - -@findex picture-newline - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode -@iftex -(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) -@end iftex -@ifnottex -(@pxref{Minor Modes}.) -@end ifnottex -Self-inserting characters replace existing text, column by column, -rather than pushing existing text to the right. @key{RET} runs -@code{picture-newline}, which just moves to the beginning of the -following line so that new text will replace that line. - -@findex picture-backward-clear-column -@findex picture-clear-column -@findex picture-clear-line - In Picture mode, the commands that normally delete or kill text, -instead erase text (replacing it with spaces). @key{DEL} -(@code{picture-backward-clear-column}) replaces the preceding -character with a space rather than removing it; this moves point -backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next -character or characters with spaces, but does not move point. (If you -want to clear characters to spaces and move forward over them, use -@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the -contents of lines, but does not delete the newlines from the buffer. - -@findex picture-open-line - To do actual insertion, you must use special commands. @kbd{C-o} -(@code{picture-open-line}) creates a blank line after the current -line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes -sense in Picture mode, so it is not changed. @kbd{C-j} -(@code{picture-duplicate-line}) inserts another line with the same -contents below the current line. - -@kindex C-c C-d @r{(Picture mode)} - To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} -(which is defined as @code{delete-char}, as @kbd{C-d} is in other -modes), or one of the picture rectangle commands (@pxref{Rectangles in -Picture}). - -@node Insert in Picture -@section Controlling Motion after Insert - -@findex picture-movement-up -@findex picture-movement-down -@findex picture-movement-left -@findex picture-movement-right -@findex picture-movement-nw -@findex picture-movement-ne -@findex picture-movement-sw -@findex picture-movement-se -@kindex C-c < @r{(Picture mode)} -@kindex C-c > @r{(Picture mode)} -@kindex C-c ^ @r{(Picture mode)} -@kindex C-c . @r{(Picture mode)} -@kindex C-c ` @r{(Picture mode)} -@kindex C-c ' @r{(Picture mode)} -@kindex C-c / @r{(Picture mode)} -@kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move -point, there is no essential restriction on how point should be moved. -Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' -character. This is useful for drawing lines in the buffer. - -@table @kbd -@item C-c < -@itemx C-c @key{LEFT} -Move left after insertion (@code{picture-movement-left}). -@item C-c > -@itemx C-c @key{RIGHT} -Move right after insertion (@code{picture-movement-right}). -@item C-c ^ -@itemx C-c @key{UP} -Move up after insertion (@code{picture-movement-up}). -@item C-c . -@itemx C-c @key{DOWN} -Move down after insertion (@code{picture-movement-down}). -@item C-c ` -@itemx C-c @key{HOME} -Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). -@item C-c ' -@itemx C-c @key{prior} -Move up and right (``northeast'') after insertion -(@code{picture-movement-ne}). -@item C-c / -@itemx C-c @key{END} -Move down and left (``southwest'') after insertion -@*(@code{picture-movement-sw}). -@item C-c \ -@itemx C-c @key{next} -Move down and right (``southeast'') after insertion -@*(@code{picture-movement-se}). -@end table - -@kindex C-c C-f @r{(Picture mode)} -@kindex C-c C-b @r{(Picture mode)} -@findex picture-motion -@findex picture-motion-reverse - Two motion commands move based on the current Picture insertion -direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c -C-b} (@code{picture-motion-reverse}) moves in the opposite direction. - -@node Tabs in Picture -@section Picture Mode Tabs - -@kindex M-TAB @r{(Picture mode)} -@findex picture-tab-search -@vindex picture-tab-chars - Two kinds of tab-like action are provided in Picture mode. Use -@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. -With no argument, it moves to a point underneath the next -``interesting'' character that follows whitespace in the previous -nonblank line. ``Next'' here means ``appearing at a horizontal position -greater than the one point starts out at.'' With an argument, as in -@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting -character in the current line. @kbd{M-@key{TAB}} does not change the -text; it only moves point. ``Interesting'' characters are defined by -the variable @code{picture-tab-chars}, which should define a set of -characters. The syntax for this variable is like the syntax used inside -of @samp{[@dots{}]} in a regular expression---but without the @samp{[} -and the @samp{]}. Its default value is @code{"!-~"}. - -@findex picture-tab - @key{TAB} itself runs @code{picture-tab}, which operates based on the -current tab stop settings; it is the Picture mode equivalent of -@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric -argument it clears the text that it moves over. - -@kindex C-c TAB @r{(Picture mode)} -@findex picture-set-tab-stops - The context-based and tab-stop-based forms of tabbing are brought -together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). -This command sets the tab stops to the positions which @kbd{M-@key{TAB}} -would consider significant in the current line. The use of this command, -together with @key{TAB}, can get the effect of context-based tabbing. But -@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. - - It may be convenient to prevent use of actual tab characters in -pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing -up the picture. You can do this by setting the variable -@code{indent-tabs-mode} to @code{nil}. - -@node Rectangles in Picture -@section Picture Mode Rectangle Commands -@cindex rectangles and Picture mode -@cindex Picture mode and rectangles - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful. -@iftex -@xref{Rectangles,,, emacs, the Emacs Manual}. -@end iftex -@ifnottex -@xref{Rectangles}. -@end ifnottex - -@table @kbd -@item C-c C-k -Clear out the region-rectangle with spaces -(@code{picture-clear-rectangle}). With argument, delete the text. -@item C-c C-w @var{r} -Similar, but save rectangle contents in register @var{r} first -(@code{picture-clear-rectangle-to-register}). -@item C-c C-y -Copy last killed rectangle into the buffer by overwriting, with upper -left corner at point (@code{picture-yank-rectangle}). With argument, -insert instead. -@item C-c C-x @var{r} -Similar, but use the rectangle in register @var{r} -(@code{picture-yank-rectangle-from-register}). -@end table - -@kindex C-c C-k @r{(Picture mode)} -@kindex C-c C-w @r{(Picture mode)} -@findex picture-clear-rectangle -@findex picture-clear-rectangle-to-register - The picture rectangle commands @kbd{C-c C-k} -(@code{picture-clear-rectangle}) and @kbd{C-c C-w} -(@code{picture-clear-rectangle-to-register}) differ from the standard -rectangle commands in that they normally clear the rectangle instead of -deleting it; this is analogous with the way @kbd{C-d} is changed in Picture -mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. -@kbd{C-c C-k} either with or without a numeric argument saves the -rectangle for @kbd{C-c C-y}. - -@kindex C-c C-y @r{(Picture mode)} -@kindex C-c C-x @r{(Picture mode)} -@findex picture-yank-rectangle -@findex picture-yank-rectangle-from-register - The Picture mode commands for yanking rectangles differ from the -standard ones in that they overwrite instead of inserting. This is -the same way that Picture mode insertion of other text differs from -other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts -(by overwriting) the rectangle that was most recently killed, while -@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does -likewise for the rectangle found in a specified register. - -@ignore - arch-tag: 10e423ad-d896-42f2-a7e8-7018adeaf8c2 -@end ignore diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi deleted file mode 100644 index 14db8276784..00000000000 --- a/doc/emacs/programs.texi +++ /dev/null @@ -1,1775 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Programs, Building, Text, Top -@chapter Editing Programs -@cindex Lisp editing -@cindex C editing -@cindex program editing - - Emacs provides many features to facilitate editing programs. Some -of these features can - -@itemize @bullet -@item -Find or move over top-level definitions (@pxref{Defuns}). -@item -Apply the usual indentation conventions of the language -(@pxref{Program Indent}). -@item -Balance parentheses (@pxref{Parentheses}). -@item -Insert, kill or align comments (@pxref{Comments}). -@item -Highlight program syntax (@pxref{Font Lock}). -@end itemize - - This chapter describes these features and many more. - -@menu -* Program Modes:: Major modes for editing programs. -* Defuns:: Commands to operate on major top-level parts - of a program. -* Program Indent:: Adjusting indentation to show the nesting. -* Parentheses:: Commands that operate on parentheses. -* Comments:: Inserting, killing, and aligning comments. -* Documentation:: Getting documentation of functions you plan to call. -* Hideshow:: Displaying blocks selectively. -* Symbol Completion:: Completion on symbol names of your program or language. -* Glasses:: Making identifiersLikeThis more readable. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike modes. -* Asm Mode:: Asm mode and its special features. -@ifnottex -* Fortran:: Fortran mode and its special features. -@end ifnottex -@end menu - -@node Program Modes -@section Major Modes for Programming Languages -@cindex modes for programming languages - - Emacs has specialized major modes for various programming languages. -@xref{Major Modes}. A programming language major mode typically -specifies the syntax of expressions, the customary rules for -indentation, how to do syntax highlighting for the language, and how -to find the beginning or end of a function definition. It often -customizes or provides facilities for compiling and debugging programs -as well. - - Ideally, Emacs should provide a major mode for each programming -language that you might want to edit; if it doesn't have a mode for -your favorite language, you can contribute one. But often the mode -for one language can serve for other syntactically similar languages. -The major mode for language @var{l} is called @code{@var{l}-mode}, -and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. -@xref{Choosing Modes}. - -@cindex Perl mode -@cindex Icon mode -@cindex Makefile mode -@cindex Tcl mode -@cindex CPerl mode -@cindex DSSSL mode -@cindex Octave mode -@cindex Metafont mode -@cindex Modula2 mode -@cindex Prolog mode -@cindex Python mode -@cindex Ruby mode -@cindex Simula mode -@cindex VHDL mode -@cindex M4 mode -@cindex Shell-script mode -@cindex Delphi mode -@cindex PostScript mode -@cindex Conf mode -@cindex DNS mode - The existing programming language major modes include Lisp, Scheme -(a variant of Lisp) and the Scheme-based DSSSL expression language, -Ada, ASM, AWK, C, C++, Delphi (Object Pascal), Fortran, Icon, IDL -(CORBA), IDLWAVE, Java, Metafont (@TeX{}'s companion for font -creation), Modula2, Objective-C, Octave, Pascal, Perl, Pike, -PostScript, Prolog, Python, Ruby, Simula, Tcl, and VHDL. An -alternative mode for Perl is called CPerl mode. Modes are available -for the scripting languages of the common GNU and Unix shells, VMS -DCL, and MS-DOS/MS-Windows @samp{BAT} files. There are also major -modes for editing makefiles, DNS master files, and various sorts of -configuration files. - -@kindex DEL @r{(programming modes)} -@findex c-electric-backspace - In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. So the major modes -for programming languages arrange for @key{TAB} to update the -indentation of the current line (@pxref{Program Indent}). They also -rebind @key{DEL} to treat a tab as if it were the equivalent number of -spaces; this lets you delete one column of indentation without -worrying whether the whitespace consists of spaces or tabs. Use -@kbd{C-b C-d} to delete a tab character before point, in these modes. - - Separate manuals are available for the modes for Ada (@pxref{Top, , Ada -Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK -(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes -(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran -mode, see -@iftex -@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@ref{Fortran}. -@end ifnottex - -@cindex mode hook -@vindex c-mode-hook -@vindex lisp-mode-hook -@vindex emacs-lisp-mode-hook -@vindex lisp-interaction-mode-hook -@vindex scheme-mode-hook - Turning on a major mode runs a normal hook called the @dfn{mode -hook}, which is the value of a Lisp variable. Each major mode has a -mode hook, and the hook's name is always made from the mode command's -name by adding @samp{-hook}. For example, turning on C mode runs the -hook @code{c-mode-hook}, while turning on Lisp mode runs the hook -@code{lisp-mode-hook}. The purpose of the mode hook is to give you a -place to set up customizations for that major mode. @xref{Hooks}. - -@node Defuns -@section Top-Level Definitions, or Defuns - - In Emacs, a major definition at the top level in the buffer, such as -a function, is called a @dfn{defun}. The name comes from Lisp, but in -Emacs we use it for all languages. - -@menu -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. -@end menu - -@node Left Margin Paren -@subsection Left Margin Convention - -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Many programming-language modes assume by default that any opening -delimiter found at the left margin is the start of a top-level -definition, or defun. Therefore, @strong{don't put an opening -delimiter at the left margin unless it should have that significance}. -For instance, never put an open-parenthesis at the left margin in a -Lisp file unless it is the start of a top-level list. - - The convention speeds up many Emacs operations, which would -otherwise have to scan back to the beginning of the buffer to analyze -the syntax of the code. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes the -indentation commands (@pxref{Program Indent}) and Font Lock mode -(@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. - - If you need to override this convention, you can do so by setting -this user option: - -@defvar open-paren-in-column-0-is-defun-start -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it's -@code{nil}, defuns are found by searching for parens or braces at the -outermost level. -@end defvar - - Usually, you should leave this option at its default value of -@code{t}. If your buffer contains parentheses or braces in column -zero which don't start defuns, and it is somehow impractical to remove -these parentheses or braces, it might be helpful to set the option to -@code{nil}. Be aware that this might make scrolling and display in -large buffers quite sluggish. Furthermore, the parentheses and braces -must be correctly matched throughout the buffer for it to work -properly. - -@node Moving by Defuns -@subsection Moving by Defuns -@cindex defuns - - These commands move point or set up the region based on top-level -major definitions, also called @dfn{defuns}. - -@table @kbd -@item C-M-a -Move to beginning of current or preceding defun -(@code{beginning-of-defun}). -@item C-M-e -Move to end of current or following defun (@code{end-of-defun}). -@item C-M-h -Put region around whole current or following defun (@code{mark-defun}). -@end table - -@cindex move to beginning or end of function -@cindex function, move to beginning or end -@kindex C-M-a -@kindex C-M-e -@kindex C-M-h -@findex beginning-of-defun -@findex end-of-defun -@findex mark-defun - The commands to move to the beginning and end of the current defun -are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} -(@code{end-of-defun}). If you repeat one of these commands, or use a -positive numeric argument, each repetition moves to the next defun in -the direction of motion. - - @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward -@var{n} times to the next beginning of a defun. This is not exactly -the same place that @kbd{C-M-e} with argument @var{n} would move to; -the end of this defun is not usually exactly the same place as the -beginning of the following defun. (Whitespace, comments, and perhaps -declarations can separate them.) Likewise, @kbd{C-M-e} with a -negative argument moves back to an end of a defun, which is not quite -the same as @kbd{C-M-a} with a positive argument. - -@kindex C-M-h @r{(C mode)} -@findex c-mark-function - To operate on the current defun, use @kbd{C-M-h} -(@code{mark-defun}), which sets the mark at the end of the current -defun and puts point at its beginning. @xref{Marking Objects}. This -is the easiest way to get ready to kill the defun in order to move it -to a different place in the file. If you use the command while point -is between defuns, it uses the following defun. If you use the -command while the mark is already active, it sets the mark but does -not move point; furthermore, each successive use of @kbd{C-M-h} -extends the end of the region to include one more defun. - - In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, -which is almost the same as @code{mark-defun}; the difference is that -it backs up over the argument declarations, function name and returned -data type so that the entire C function is inside the region. This is -an example of how major modes adjust the standard key bindings so that -they do their standard jobs in a way better fitting a particular -language. Other major modes may replace any or all of these key -bindings for that purpose. - -@node Imenu -@subsection Imenu -@cindex index of buffer definitions -@cindex buffer definitions index - - The Imenu facility offers a way to find the major definitions in -a file by name. It is also useful in text formatter major modes, -where it treats each chapter, section, etc., as a definition. -(@xref{Tags}, for a more powerful feature that handles multiple files -together.) - -@findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. - -@findex imenu-add-menubar-index - Alternatively, you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select a definition -name. You can also add the buffer's index to the menu bar by calling -@code{imenu-add-menubar-index}. If you want to have this menu bar -item available for all buffers in a certain major mode, you can do -this by adding @code{imenu-add-menubar-index} to its mode hook. But -if you have done that, you will have to wait a little while each time -you visit a file in that mode, while Emacs finds all the definitions -in that buffer. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions, you can update the buffer's index based on the -new contents by invoking the @samp{*Rescan*} item in the menu. -Rescanning happens automatically if you set @code{imenu-auto-rescan} to -a non-@code{nil} value. There is no need to rescan because of small -changes in the text. - -@vindex imenu-sort-function - You can customize the way the menus are sorted by setting the -variable @code{imenu-sort-function}. By default, names are ordered as -they occur in the buffer; if you want alphabetic sorting, use the -symbol @code{imenu--sort-by-name} as the value. You can also -define your own comparison function by writing Lisp code. - - Imenu provides the information to guide Which Function mode -@ifnottex -(@pxref{Which Function}). -@end ifnottex -@iftex -(see below). -@end iftex -The Speedbar can also use it (@pxref{Speedbar}). - -@node Which Function -@subsection Which Function Mode -@cindex current function name in mode line - - Which Function mode is a minor mode that displays the current -function name in the mode line, updating it as you move around in a -buffer. - -@findex which-function-mode -@vindex which-func-modes - To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. This command applies to all buffers, -both existing ones and those yet to be created. However, it takes -effect only in certain major modes, those listed in the value of -@code{which-func-modes}. If the value of @code{which-func-modes} is -@code{t} rather than a list of modes, then Which Function mode applies -to all major modes that know how to support it---in other words, all -the major modes that support Imenu. - -@node Program Indent -@section Indentation for Programs -@cindex indentation for programs - - The best way to keep a program properly indented is to use Emacs to -reindent it as you change it. Emacs has commands to indent either a -single line, a specified number of lines, or all of the lines inside a -single parenthetical grouping. - -@menu -* Basic Indent:: Indenting a single line. -* Multi-line Indent:: Commands to reindent many lines at once. -* Lisp Indent:: Specifying how each Lisp function should be indented. -* C Indent:: Extra features for indenting C and related modes. -* Custom C Indent:: Controlling indentation style for C and related modes. -@end menu - -@cindex pretty-printer - Emacs also provides a Lisp pretty-printer in the library @code{pp}. -This program reformats a Lisp object with indentation chosen to look nice. - -@node Basic Indent -@subsection Basic Program Indentation Commands - - The basic indentation commands indent a single line according to the -usual conventions of the language you are editing. - -@table @kbd -@item @key{TAB} -Adjust indentation of current line. -@item C-j -Insert a newline, then adjust indentation of following line -(@code{newline-and-indent}). -@end table - -@kindex TAB @r{(programming modes)} -@findex c-indent-command -@findex indent-line-function -@findex indent-for-tab-command - The basic indentation command is @key{TAB}. In any -programming-language major mode, @key{TAB} gives the current line the -correct indentation as determined from the previous lines. It does -this by inserting or deleting whitespace at the beginning of the -current line. If point was inside the whitespace at the beginning of -the line, @key{TAB} puts it at the end of that whitespace; otherwise, -@key{TAB} keeps point fixed with respect to the characters around it. -If the region is active (@pxref{Mark}), @key{TAB} indents every line -within the region instead of just the current line. The function that -@key{TAB} runs depends on the major mode; for instance, it is -@code{c-indent-line-or-region} in C mode. Each function is aware of -the syntax and conventions for its particular language. - - Use @kbd{C-q @key{TAB}} to insert a tab character at point. - -@kindex C-j -@findex newline-and-indent - When entering lines of new code, use @kbd{C-j} -(@code{newline-and-indent}), which inserts a newline and then adjusts -indentation after it. (It also deletes any trailing whitespace which -remains before the new newline.) For instance, @kbd{C-j} at the end -of a line creates a blank line with appropriate indentation. In -programming language modes, it is equivalent to @key{RET} @key{TAB}. - - When Emacs indents a line that starts within a parenthetical -grouping, it usually places the start of the line under the preceding -line within the group, or under the text after the parenthesis. If -you manually give one of these lines a nonstandard indentation, the -lines below will tend to follow it. This behavior is convenient in -cases where you have overridden the standard result of @key{TAB} -indentation (e.g., for aesthetic purposes). - - Many programming-language modes assume that an open-parenthesis, -open-brace or other opening delimiter at the left margin is the start -of a function. This assumption speeds up indentation commands. If -the text you are editing contains opening delimiters in column zero -that aren't the beginning of a functions---even if these delimiters -occur inside strings or comments---then you must set -@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin -Paren}. - - Normally, Emacs indents lines using an ``optimal'' mix of tab and -space characters. If you want Emacs to use spaces only, set -@code{indent-tabs-mode} (@pxref{Just Spaces}). - -@node Multi-line Indent -@subsection Indenting Several Lines - - Sometimes, you may want to reindent several lines of code at a time. -One way to do this is to use the mark; when the mark is active and the -region is non-empty, @key{TAB} indents every line within the region. -In addition, Emacs provides several other commands for indenting large -chunks of code: - -@table @kbd -@item C-M-q -Reindent all the lines within one parenthetical grouping. -@item C-M-\ -Reindent all lines in the region (@code{indent-region}). -@item C-u @key{TAB} -Shift an entire parenthetical grouping rigidly sideways so that its -first line is properly indented. -@item M-x indent-code-rigidly -Shift all the lines in the region rigidly sideways, but do not alter -lines that start inside comments and strings. -@end table - -@kindex C-M-q -@findex indent-pp-sexp - To reindent the contents of a single parenthetical grouping, -position point before the beginning of the grouping and type -@kbd{C-M-q}. This changes the relative indentation within the -grouping, without affecting its overall indentation (i.e., the -indentation of the line where the grouping starts). The function that -@kbd{C-M-q} runs depends on the major mode; it is -@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, -etc. To correct the overall indentation as well, type @key{TAB} -first. - - @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to the region. -This is useful when Transient Mark mode is disabled (@pxref{Persistent -Mark}), because in that case @key{TAB} does not act on the region. - -@kindex C-u TAB - If you like the relative indentation within a grouping but not the -indentation of its first line, move point to that first line and type -@kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, -@key{TAB} with a numeric argument reindents the current line as usual, -then reindents by the same amount all the lines in the parenthetical -grouping starting on the current line. It is clever, though, and does -not alter lines that start inside strings. Neither does it alter C -preprocessor lines when in C mode, but it does reindent any -continuation lines that may be attached to them. - -@findex indent-code-rigidly - The command @kbd{M-x indent-code-rigidly} rigidly shifts all the -lines in the region sideways, like @code{indent-rigidly} does -(@pxref{Indentation Commands}). It doesn't alter the indentation of -lines that start inside a string, unless the region also starts inside -that string. The prefix arg specifies the number of columns to -indent. - -@node Lisp Indent -@subsection Customizing Lisp Indentation -@cindex customizing Lisp indentation - - The indentation pattern for a Lisp expression can depend on the function -called by the expression. For each Lisp function, you can choose among -several predefined patterns of indentation, or define an arbitrary one with -a Lisp program. - - The standard pattern of indentation is as follows: the second line of the -expression is indented under the first argument, if that is on the same -line as the beginning of the expression; otherwise, the second line is -indented underneath the function name. Each following line is indented -under the previous line whose nesting depth is the same. - -@vindex lisp-indent-offset - If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides -the usual indentation pattern for the second line of an expression, so that -such lines are always indented @code{lisp-indent-offset} more columns than -the containing list. - -@vindex lisp-body-indent - Certain functions override the standard pattern. Functions whose -names start with @code{def} treat the second lines as the start of -a @dfn{body}, by indenting the second line @code{lisp-body-indent} -additional columns beyond the open-parenthesis that starts the -expression. - -@cindex @code{lisp-indent-function} property - You can override the standard pattern in various ways for individual -functions, according to the @code{lisp-indent-function} property of -the function name. Normally you would use this for macro definitions -and specify it using the @code{declare} construct (@pxref{Defining -Macros,,, elisp, the Emacs Lisp Reference Manual}). - -@node C Indent -@subsection Commands for C Indentation - - Here are special features for indentation in C mode and related modes: - -@table @code -@item C-c C-q -@kindex C-c C-q @r{(C mode)} -@findex c-indent-defun -Reindent the current top-level function definition or aggregate type -declaration (@code{c-indent-defun}). - -@item C-M-q -@kindex C-M-q @r{(C mode)} -@findex c-indent-exp -Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits warning messages -about invalid syntax. - -@item @key{TAB} -@findex c-indent-command -Reindent the current line, and/or in some cases insert a tab character -(@code{c-indent-command}). - -@vindex c-tab-always-indent -If @code{c-tab-always-indent} is @code{t}, this command always reindents -the current line and does nothing else. This is the default. - -If that variable is @code{nil}, this command reindents the current line -only if point is at the left margin or in the line's indentation; -otherwise, it inserts a tab (or the equivalent number of spaces, -if @code{indent-tabs-mode} is @code{nil}). - -Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment or a string. -@end table - - To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This -first selects the whole buffer as the region, then reindents that -region. - - To reindent the current block, use @kbd{C-M-u C-M-q}. This moves -to the front of the block and then reindents it all. - -@node Custom C Indent -@subsection Customizing C Indentation -@cindex style (for indentation) - - C mode and related modes use a flexible mechanism for customizing -indentation. C mode indents a source line in two steps: first it -classifies the line syntactically according to its contents and -context; second, it determines the indentation offset associated by -your selected @dfn{style} with the syntactic construct and adds this -onto the indentation of the @dfn{anchor statement}. - -@table @kbd -@item C-c . @key{RET} @var{style} @key{RET} -Select a predefined style @var{style} (@code{c-set-style}). -@end table - - A @dfn{style} is a named collection of customizations that can be -used in C mode and the related modes. @ref{Styles,,, ccmode, The CC -Mode Manual}, for a complete description. Emacs comes with several -predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, -@code{stroustrup}, @code{linux}, @code{python}, @code{java}, -@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these -styles are primarily intended for one language, but any of them can be -used with any of the languages supported by these modes. To find out -what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. - -@kindex C-c . @r{(C mode)} -@findex c-set-style - To choose a style for the current buffer, use the command @w{@kbd{C-c -.}}. Specify a style name as an argument (case is not significant). -This command affects the current buffer only, and it affects only -future invocations of the indentation commands; it does not reindent -the code already in the buffer. To reindent the whole buffer in the -new style, you can type @kbd{C-x h C-M-\}. - -@vindex c-default-style - You can also set the variable @code{c-default-style} to specify the -default style for various major modes. Its value should be either the -style's name (a string) or an alist, in which each element specifies -one major mode and which indentation style to use for it. For -example, - -@example -(setq c-default-style - '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) -@end example - -@noindent -specifies explicit choices for Java and AWK modes, and the default -@samp{gnu} style for the other C-like modes. (These settings are -actually the defaults.) This variable takes effect when you select -one of the C-like major modes; thus, if you specify a new default -style for Java mode, you can make it take effect in an existing Java -mode buffer by typing @kbd{M-x java-mode} there. - - The @code{gnu} style specifies the formatting recommended by the GNU -Project for C; it is the default, so as to encourage use of our -recommended style. - - @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and -@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more -information on customizing indentation for C and related modes, -including how to override parts of an existing style and how to define -your own styles. - -@node Parentheses -@section Commands for Editing with Parentheses - -@findex check-parens -@cindex unbalanced parentheses and quotes - This section describes the commands and features that take advantage -of the parenthesis structure in a program, or help you keep it -balanced. - - When talking about these facilities, the term ``parenthesis'' also -includes braces, brackets, or whatever delimiters are defined to match -in pairs. The major mode controls which delimiters are significant, -through the syntax table (@pxref{Syntax}). In Lisp, only parentheses -count; in C, these commands apply to braces and brackets too. - - You can use @kbd{M-x check-parens} to find any unbalanced -parentheses and unbalanced string quotes in the buffer. - -@menu -* Expressions:: Expressions with balanced parentheses. -* Moving by Parens:: Commands for moving up, down and across - in the structure of parentheses. -* Matching:: Insertion of a close-delimiter flashes matching open. -@end menu - -@node Expressions -@subsection Expressions with Balanced Parentheses - -@cindex sexp -@cindex expression -@cindex balanced expression - These commands deal with balanced expressions, also called -@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an -expression in Lisp.}. - -@table @kbd -@item C-M-f -Move forward over a balanced expression (@code{forward-sexp}). -@item C-M-b -Move backward over a balanced expression (@code{backward-sexp}). -@item C-M-k -Kill balanced expression forward (@code{kill-sexp}). -@item C-M-t -Transpose expressions (@code{transpose-sexps}). -@item C-M-@@ -@itemx C-M-@key{SPC} -Put mark after following expression (@code{mark-sexp}). -@end table - - Each programming language major mode customizes the definition of -balanced expressions to suit that language. Balanced expressions -typically include symbols, numbers, and string constants, as well as -any pair of matching delimiters and their contents. Some languages -have obscure forms of expression syntax that nobody has bothered to -implement in Emacs. - -@cindex Control-Meta - By convention, the keys for these commands are all Control-Meta -characters. They usually act on expressions just as the corresponding -Meta characters act on words. For instance, the command @kbd{C-M-b} -moves backward over a balanced expression, just as @kbd{M-b} moves -back over a word. - -@kindex C-M-f -@kindex C-M-b -@findex forward-sexp -@findex backward-sexp - To move forward over a balanced expression, use @kbd{C-M-f} -(@code{forward-sexp}). If the first significant character after point -is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or -@samp{@{} in C), @kbd{C-M-f} moves past the matching closing -delimiter. If the character begins a symbol, string, or number, -@kbd{C-M-f} moves over that. - - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression. The detailed rules are like those above for -@kbd{C-M-f}, but with directions reversed. If there are prefix -characters (single-quote, backquote and comma, in Lisp) preceding the -expression, @kbd{C-M-b} moves back over them as well. The balanced -expression commands move across comments as if they were whitespace, -in most modes. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. - -@cindex killing expressions -@kindex C-M-k -@findex kill-sexp - Killing a whole balanced expression can be done with @kbd{C-M-k} -(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} -would move over. - -@cindex transposition of expressions -@kindex C-M-t -@findex transpose-sexps - A somewhat random-sounding command which is nevertheless handy is -@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous -balanced expression across the next one. An argument serves as a -repeat count, moving the previous expression over that many following -ones. A negative argument drags the previous balanced expression -backwards across those before it (thus canceling out the effect of -@kbd{C-M-t} with a positive argument). An argument of zero, rather -than doing nothing, transposes the balanced expressions ending at or -after point and the mark. - -@kindex C-M-@@ -@kindex C-M-@key{SPC} -@findex mark-sexp - To set the region around the next balanced expression in the buffer, -use @kbd{C-M-@key{SPC}} (@code{mark-sexp}), which sets mark at the -same place that @kbd{C-M-f} would move to. @kbd{C-M-@key{SPC}} treats -numeric arguments in the same way as @kbd{C-M-f}; in particular, a -negative argument puts the mark at the beginning of the previous -balanced expression. The alias @kbd{C-M-@@} is equivalent to -@kbd{C-M-@key{SPC}}. While the mark is active, each successive use of -@kbd{C-M-@key{SPC}} extends the region by shifting the mark by one -sexp. - - In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions as such because there can be -multiple possibilities at a given position. For example, C mode does -not treat @samp{foo + bar} as a single expression, even though it -@emph{is} one C expression; instead, it recognizes @samp{foo} as one -expression and @samp{bar} as another, with the @samp{+} as punctuation -between them. Both @samp{foo + bar} and @samp{foo} are legitimate -choices for ``the expression following point'' when point is at the -@samp{f}, so the expression commands must perforce choose one or the -other to operate on. Note that @samp{(foo + bar)} is recognized as a -single expression in C mode, because of the parentheses. - -@node Moving by Parens -@subsection Moving in the Parenthesis Structure - -@cindex parenthetical groupings -@cindex parentheses, moving across -@cindex matching parenthesis and braces, moving to -@cindex braces, moving across -@cindex list commands - - The Emacs commands for handling parenthetical groupings see nothing -except parentheses (or whatever characters must balance in the -language you are working with). They ignore strings and comments -(including any parentheses within them) and ignore parentheses quoted -by an escape character. They are mainly intended for editing -programs, but can be useful for editing any text that has parentheses. -They are sometimes called ``list'' commands because in Lisp these -groupings are lists. - -These commands assume that the starting point is not inside a string -or a comment. Sometimes you can invoke them usefully from one of -these places (for example, when you have a parenthesised clause in a -comment) but this is unreliable. - -@table @kbd -@item C-M-n -Move forward over a parenthetical group (@code{forward-list}). -@item C-M-p -Move backward over a parenthetical group (@code{backward-list}). -@item C-M-u -Move up in parenthesis structure (@code{backward-up-list}). -@item C-M-d -Move down in parenthesis structure (@code{down-list}). -@end table - -@kindex C-M-n -@kindex C-M-p -@findex forward-list -@findex backward-list - The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and -@kbd{C-M-p} (@code{backward-list}) move forward or backward over one -(or @var{n}) parenthetical groupings. - -@kindex C-M-u -@findex backward-up-list - @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the -parenthesis structure. To move @emph{up} one (or @var{n}) levels, use -@kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up -past one unmatched opening delimiter. A positive argument serves as a -repeat count; a negative argument reverses the direction of motion, so -that the command moves forward and up one or more levels. - -@kindex C-M-d -@findex down-list - To move @emph{down} in the parenthesis structure, use @kbd{C-M-d} -(@code{down-list}). In Lisp mode, where @samp{(} is the only opening -delimiter, this is nearly the same as searching for a @samp{(}. An -argument specifies the number of levels to go down. - -@node Matching -@subsection Automatic Display Of Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - The Emacs parenthesis-matching feature is designed to show -automatically how parentheses (and other matching delimiters) match in -the text. Whenever you type a self-inserting character that is a -closing delimiter, the cursor moves momentarily to the location of the -matching opening delimiter, provided that is on the screen. If it is -not on the screen, Emacs displays some of the text near it in the echo -area. Either way, you can tell which grouping you are closing off. - - If the opening delimiter and closing delimiter are mismatched---such -as in @samp{[x)}---a warning message is displayed in the echo area. - -@vindex blink-matching-paren -@vindex blink-matching-paren-distance -@vindex blink-matching-delay - Three variables control parenthesis match display: - - @code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable match display. - - @code{blink-matching-delay} says how many seconds to leave the -cursor on the matching opening delimiter, before bringing it back to -the real location of point; the default is 1, but on some systems it -is useful to specify a fraction of a second. - - @code{blink-matching-paren-distance} specifies how many characters -back to search to find the matching opening delimiter. If the match -is not found in that distance, scanning stops, and nothing is displayed. -This is to prevent the scan for the matching delimiter from wasting -lots of time when there is no match. The default is 25600. - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode provides a more powerful kind of automatic matching. -Whenever point is before an opening delimiter or after a closing -delimiter, both that delimiter and its opposite delimiter are -highlighted. Use the command @kbd{M-x show-paren-mode} to enable or -disable this mode. - - Show Paren mode uses the faces @code{show-paren-match} and -@code{show-paren-mismatch} to highlight parentheses; you can customize -them to control how highlighting looks. @xref{Face Customization}. - -@node Comments -@section Manipulating Comments -@cindex comments - - Because comments are such an important part of programming, Emacs -provides special commands for editing and inserting comments. It can -also do spell checking on comments with Flyspell Prog mode -(@pxref{Spelling}). - -@menu -* Comment Commands:: Inserting, killing, and aligning comments. -* Multi-Line Comments:: Commands for adding and editing multi-line comments. -* Options for Comments::Customizing the comment features. -@end menu - -@node Comment Commands -@subsection Comment Commands -@cindex indentation for comments -@cindex alignment for comments - - The commands in this table insert, kill and align comments: - -@table @asis -@item @kbd{M-;} -Insert or realign comment on current line; alternatively, comment or -uncomment the region (@code{comment-dwim}). -@item @kbd{C-u M-;} -Kill comment on current line (@code{comment-kill}). -@item @kbd{C-x ;} -Set comment column (@code{comment-set-column}). -@item @kbd{C-M-j} -@itemx @kbd{M-j} -Like @key{RET} followed by inserting and aligning a comment -(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. -@item @kbd{M-x comment-region} -@itemx @kbd{C-c C-c} (in C-like modes) -Add or remove comment delimiters on all the lines in the region. -@end table - -@kindex M-; -@findex comment-dwim - The command to create or align a comment is @kbd{M-;} -(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What -I Mean''; it indicates that this command can be used for many -different jobs relating to comments, depending on the situation where -you use it. - - When a region is active, @kbd{M-;} either adds or removes comment -delimiters on each line of the region. @xref{Mark}. If every line in -the region is a comment, it removes comment delimiters from each; -otherwise, it adds comment delimiters to each. You can also use the -commands @code{comment-region} and @code{uncomment-region} to -explicitly comment or uncomment the text in the region -(@pxref{Multi-Line Comments}). If you supply a prefix argument to -@kbd{M-;} when a region is active, that specifies how many comment -delimiters to add or how many to delete. - - If the region is not active, @kbd{M-;} inserts a new comment if -there is no comment already on the line. The new comment is normally -aligned at a specific column called the @dfn{comment column}; if the -text of the line extends past the comment column, @kbd{M-;} aligns the -comment start string to a suitable boundary (usually, at least one -space is inserted). The comment begins with the string Emacs thinks -comments should start with (the value of @code{comment-start}; see -below). Emacs places point after that string, so you can insert the -text of the comment right away. If the major mode has specified a -string to terminate comments, @kbd{M-;} inserts that string after -point, to keep the syntax valid. - - You can also use @kbd{M-;} to align an existing comment. If a line -already contains the comment-start string, @kbd{M-;} realigns it to -the conventional alignment and moves point after it. (Exception: -comments starting in column 0 are not moved.) Even when an existing -comment is properly aligned, @kbd{M-;} is still useful for moving -directly to the start of the text inside the comment. - -@findex comment-kill -@kindex C-u M-; - @kbd{C-u M-;} kills any comment on the current line, along with the -whitespace before it. To reinsert the comment on another line, move -to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to -realign it. - - Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} -(@code{comment-dwim}) with a prefix argument. That command is -programmed so that when it receives a prefix argument it calls -@code{comment-kill}. However, @code{comment-kill} is a valid command -in its own right, and you can bind it directly to a key if you wish. - - Some major modes have special rules for aligning certain kinds of -comments in certain contexts. For example, in Lisp code, comments which -start with two semicolons are indented as if they were lines of code, -instead of at the comment column. Comments which start with three -semicolons are supposed to start at the left margin and are often used -for sectioning purposes. Emacs understands -these conventions by indenting a double-semicolon comment using @key{TAB}, -and by not changing the indentation of a triple-semicolon comment at all. - -@example -;; This function is just an example. -;;; Here either two or three semicolons are appropriate. -(defun foo (x) -;;; And now, the first part of the function: - ;; The following line adds one. - (1+ x)) ; This line adds one. -@end example - - For C-like modes, you can configure the exact effect of @kbd{M-;} by -setting the variables @code{c-indent-comment-alist} and -@code{c-indent-comments-syntactically-p}. For example, on a line -ending in a closing brace, @kbd{M-;} puts the comment one space after -the brace rather than at @code{comment-column}. For full details see -@ref{Comment Commands,,, ccmode, The CC Mode Manual}. - -@node Multi-Line Comments -@subsection Multiple Lines of Comments - -@kindex C-M-j -@kindex M-j -@cindex blank lines in programs -@findex comment-indent-new-line - - If you are typing a comment and wish to continue it on another line, -you can use the command @kbd{C-M-j} or @kbd{M-j} -(@code{comment-indent-new-line}). If @code{comment-multi-line} -(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new -line within the comment. Otherwise it closes the comment and starts a -new comment on a new line. When Auto Fill mode is on, going past the -fill column while typing a comment causes the comment to be continued -in just this fashion. - -@kindex C-c C-c (C mode) -@findex comment-region - To turn existing lines into comment lines, use the @kbd{M-x -comment-region} command (or type @kbd{C-c C-c} in C-like modes). It -adds comment delimiters to the lines that start in the region, thus -commenting them out. With a negative argument, it does the -opposite---it deletes comment delimiters from the lines in the region. - - With a positive argument, @code{comment-region} duplicates the last -character of the comment start sequence it adds; the argument -specifies how many copies of the character to insert. Thus, in Lisp -mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. -Duplicating the comment delimiter is a way of calling attention to the -comment. It can also affect how the comment is aligned or indented. -In Lisp, for proper indentation, you should use an argument of two or -three, if between defuns; if within a defun, it must be three. - - You can configure C Mode such that when you type a @samp{/} at the -start of a line in a multi-line block comment, this closes the -comment. Enable the @code{comment-close-slash} clean-up for this. -@xref{Clean-ups,,, ccmode, The CC Mode Manual}. - -@node Options for Comments -@subsection Options Controlling Comments - -@vindex comment-column -@kindex C-x ; -@findex comment-set-column - The @dfn{comment column}, the column at which Emacs tries to place -comments, is stored in the variable @code{comment-column}. You can -set it to a number explicitly. Alternatively, the command @kbd{C-x ;} -(@code{comment-set-column}) sets the comment column to the column -point is at. @kbd{C-u C-x ;} sets the comment column to match the -last comment before point in the buffer, and then does a @kbd{M-;} to -align the current line's comment under the previous one. - - The variable @code{comment-column} is per-buffer: setting the variable -in the normal fashion affects only the current buffer, but there is a -default value which you can change with @code{setq-default}. -@xref{Locals}. Many major modes initialize this variable for the -current buffer. - -@vindex comment-start-skip - The comment commands recognize comments based on the regular -expression that is the value of the variable @code{comment-start-skip}. -Make sure this regexp does not match the null string. It may match more -than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is -@c This stops M-q from breaking the line inside that @code. -@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces -after the @samp{/*} itself, and accepts C++ style comments also. -(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in -the string, which is needed to deny the first star its special meaning -in regexp syntax. @xref{Regexp Backslash}.) - -@vindex comment-start -@vindex comment-end - When a comment command makes a new comment, it inserts the value of -@code{comment-start} to begin it. The value of @code{comment-end} is -inserted after point, so that it will follow the text that you will -insert into the comment. When @code{comment-end} is non-empty, it -should start with a space. For example, in C mode, -@code{comment-start} has the value @w{@code{"/* "}} and -@code{comment-end} has the value @w{@code{" */"}}. - -@vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} should insert on each line between the comment -delimiter and the line's original text. The default is 1, to insert -one space. @code{nil} means 0. Alternatively, @code{comment-padding} -can hold the actual string to insert. - -@vindex comment-multi-line - The variable @code{comment-multi-line} controls how @kbd{C-M-j} -(@code{indent-new-comment-line}) behaves when used inside a comment. -Specifically, when @code{comment-multi-line} is @code{nil}, the -command inserts a comment terminator, begins a new line, and finally -inserts a comment starter. Otherwise it does not insert the -terminator and starter, so it effectively continues the current -comment across multiple lines. In languages that allow multi-line -comments, the choice of value for this variable is a matter of taste. -The default for this variable depends on the major mode. - -@vindex comment-indent-function - The variable @code{comment-indent-function} should contain a function -that will be called to compute the alignment for a newly inserted -comment or for aligning an existing comment. It is set differently by -various major modes. The function is called with no arguments, but with -point at the beginning of the comment, or at the end of a line if a new -comment is to be inserted. It should return the column in which the -comment ought to start. For example, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@node Documentation -@section Documentation Lookup - - Emacs provides several features you can use to look up the -documentation of functions, variables and commands that you plan to -use in your program. - -@menu -* Info Lookup:: Looking up library functions and commands - in Info files. -* Man Page:: Looking up man pages of library functions and commands. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. -@end menu - -@node Info Lookup -@subsection Info Documentation Lookup - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h S - For major modes that apply to languages which have documentation in -Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the -Info documentation for a symbol used in the program. You specify the -symbol with the minibuffer; the default is the symbol appearing in the -buffer at point. For example, in C mode this looks for the symbol in -the C Library Manual. The command only works if the appropriate -manual's Info files are installed. - - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -You can also use @kbd{M-x info-lookup-file} to look for documentation -for a file name. - - If you use @kbd{C-h S} in a major mode that does not support it, -it asks you to specify the ``symbol help mode.'' You should enter -a command such as @code{c-mode} that would select a major -mode which @kbd{C-h S} does support. - -@node Man Page -@subsection Man Page Lookup - -@cindex manual page - On Unix, the main form of on-line documentation was the @dfn{manual -page} or @dfn{man page}. In the GNU operating system, we aim to -replace man pages with better-organized manuals that you can browse -with Info (@pxref{Misc Help}). This process is not finished, so it is -still useful to read manual pages. - -@findex manual-entry - You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. It -runs the @code{man} program to format the man page; if the system -permits, it runs @code{man} asynchronously, so that you can keep on -editing while the page is being formatted. (On MS-DOS and MS-Windows -3, you cannot edit while Emacs waits for @code{man} to finish.) The -result goes in a buffer named @samp{*Man @var{topic}*}. These buffers -use a special major mode, Man mode, that facilitates scrolling and -jumping to other manual pages. For details, type @kbd{C-h m} while in -a man page buffer. - -@cindex sections of manual pages - Each man page belongs to one of ten or more @dfn{sections}, each -named by a digit or by a digit and a letter. Sometimes there are -multiple man pages with the same name in different sections. To read -a man page from a specific section, type -@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} -when @kbd{M-x manual-entry} prompts for the topic. For example, to -read the man page for the C library function @code{chmod} (as opposed -to a command of the same name), type @kbd{M-x manual-entry @key{RET} -chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in -section @samp{2}.) - -@vindex Man-switches - If you do not specify a section, the results depend on how the -@code{man} program works on your system. Some of them display only -the first man page they find. Others display all man pages that have -the specified name, so you can move between them with the @kbd{M-n} -and @kbd{M-p} keys@footnote{On some systems, the @code{man} program -accepts a @samp{-a} command-line option which tells it to display all -the man pages for the specified topic. If you want this behavior, you -can add this option to the value of the variable @code{Man-switches}.}. -The mode line shows how many manual pages are present in the Man buffer. - -@vindex Man-fontify-manpage-flag - By default, Emacs highlights the text in man pages. For a long man -page, highlighting can take substantial time. You can turn off -highlighting of man pages by setting the variable -@code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man,'' since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external -programs to format and display the man pages; instead it does the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program (and other programs it uses) are not generally -available. - - @kbd{M-x woman} prompts for a name of a manual page, and provides -completion based on the list of manual pages that are installed on -your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at -point in the current buffer is used to suggest the default for the -name the manual page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. This is useful if you add or delete -manual pages. - - If you type a name of a manual page and @kbd{M-x woman} finds that -several manual pages by the same name exist in different sections, it -pops up a window with possible candidates asking you to choose one of -them. - - For more information about setting up and using @kbd{M-x woman}, see -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan -Manual}. - -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup - - As you edit Lisp code to be run in Emacs, you can use the commands -@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} -(@code{describe-variable}) to view documentation of functions and -variables that you want to use. These commands use the minibuffer to -read the name of a function or variable to document, and display the -documentation in a window. Their default arguments are based on the -code in the neighborhood of point. For @kbd{C-h f}, the default is -the function called in the innermost list containing point. @kbd{C-h -v} uses the symbol name around or adjacent to point as its default. - -@cindex Eldoc mode -@findex eldoc-mode - A more automatic but less powerful method is Eldoc mode. This minor -mode constantly displays in the echo area the argument list for the -function being called at point. (In other words, it finds the -function call that point is contained in, and displays the argument -list of that function.) If point is over a documented variable, it -shows the first line of the variable's docstring. Eldoc mode applies -in Emacs Lisp and Lisp Interaction modes, and perhaps a few others -that provide special support for looking up doc strings. Use the -command @kbd{M-x eldoc-mode} to enable or disable this feature. - -@node Hideshow -@section Hideshow minor mode - -@findex hs-minor-mode - Hideshow minor mode provides selective display of portions of a -program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} -to enable or disable this mode, or add @code{hs-minor-mode} to the -mode hook for certain major modes in order to enable it automatically -for those modes. - - Just what constitutes a block depends on the major mode. In C mode -or C++ mode, they are delimited by braces, while in Lisp mode and -similar modes they are delimited by parentheses. Multi-line comments -also count as blocks. - -@findex hs-hide-all -@findex hs-hide-block -@findex hs-show-all -@findex hs-show-block -@findex hs-show-region -@findex hs-hide-level -@findex hs-minor-mode -@kindex C-c @@ C-h -@kindex C-c @@ C-s -@kindex C-c @@ C-M-h -@kindex C-c @@ C-M-s -@kindex C-c @@ C-r -@kindex C-c @@ C-l -@kindex S-Mouse-2 -@table @kbd -@item C-c @@ C-h -Hide the current block (@code{hs-hide-block}). -@item C-c @@ C-s -Show the current block (@code{hs-show-block}). -@item C-c @@ C-c -Either hide or show the current block (@code{hs-toggle-hiding}). -@item S-Mouse-2 -Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). -@item C-c @@ C-M-h -Hide all top-level blocks (@code{hs-hide-all}). -@item C-c @@ C-M-s -Show everything in the buffer (@code{hs-show-all}). -@item C-c @@ C-l -Hide all blocks @var{n} levels below this block -(@code{hs-hide-level}). -@end table - -@vindex hs-hide-comments-when-hiding-all -@vindex hs-isearch-open -@vindex hs-special-modes-alist - These variables exist for customizing Hideshow mode. - -@table @code -@item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. - -@item hs-isearch-open -Specifies what kind of hidden blocks incremental search should make -visible. The value should be one of these four symbols: - -@table @code -@item code -Open only code blocks. -@item comment -Open only comments. -@item t -Open both code blocks and comments. -@item nil -Open neither code blocks nor comments. -@end table - -@item hs-special-modes-alist -A list of elements, each specifying how to initialize Hideshow -variables for one major mode. See the variable's documentation string -for more information. -@end table - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - In Emacs, completion is something you normally do in the minibuffer -(@pxref{Completion}). But one kind of completion is available in all -buffers: completion for symbol names. - -@kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the -partial symbol before point against the set of meaningful symbol -names. This command inserts at point any additional characters that -it can determine from the partial name. - - If your window manager defines @kbd{M-@key{TAB}} to switch windows, -you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. -However, most window managers let you customize these shortcuts, so -you can change any that interfere with the way you use Emacs. - - If the partial name in the buffer has multiple possible completions -that differ in the very next character, so that it is impossible to -complete even one more character, @kbd{M-@key{TAB}} displays a list of -all possible completions in another window. - -@cindex tags-based completion -@cindex Info index completion -@findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. - -@cindex Lisp symbol completion -@cindex completion (Lisp symbols) -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the way they display. It knows two different -ways to do this: by displaying underscores between a lower-case letter -and the following capital letter, and by emboldening the capital -letters. It does not alter the buffer text, only the way they -display, so you can use it even on read-only buffers. You can use the -command @kbd{M-x glasses-mode} to enable or disable the mode in the -current buffer; you can also add @code{glasses-mode} to the mode hook -of the programming language major modes in which you normally want -to use Glasses mode. - -@node Misc for Programs -@section Other Features Useful for Editing Programs - - A number of Emacs commands that aren't designed specifically for -editing programs are useful for that nonetheless. - - The Emacs commands that operate on words, sentences and paragraphs -are useful for editing code. Most symbols names contain words -(@pxref{Words}); sentences can be found in strings and comments -(@pxref{Sentences}). Paragraphs in the strict sense can be found in -program code (in long comments), but the paragraph commands are useful -in other places too, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -Judicious use of blank lines to make the program clearer will also -provide useful chunks of text for the paragraph commands to work on. -Auto Fill mode, if enabled in a programming language major mode, -indents the new lines which it creates. - - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -hides the lines that are indented more than a specified amount. -Programming modes often support Outline minor mode (@pxref{Outline -Mode}). The Foldout package provides folding-editor features -(@pxref{Foldout}). - - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. - -@node C Modes -@section C and Related Modes -@cindex C mode -@cindex Java mode -@cindex Pike mode -@cindex IDL mode -@cindex CORBA IDL mode -@cindex Objective C mode -@cindex C++ mode -@cindex AWK mode -@cindex mode, Java -@cindex mode, C -@cindex mode, C++ -@cindex mode, Objective C -@cindex mode, CORBA IDL -@cindex mode, Pike -@cindex mode, AWK - - This section gives a brief description of the special features -available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. -(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, -ccmode, CC Mode}, for a more extensive description of these modes -and their special features. - -@menu -* Motion in C:: Commands to move by C statements, etc. -* Electric C:: Colon and other chars can automatically reindent. -* Hungry Delete:: A more powerful DEL command. -* Other C Commands:: Filling comments, viewing expansion of macros, - and other neat features. -@end menu - -@node Motion in C -@subsection C Mode Motion Commands - - This section describes commands for moving point, in C mode and -related modes. - -@table @code -@item M-x c-beginning-of-defun -@itemx M-x c-end-of-defun -@findex c-beginning-of-defun -@findex c-end-of-defun -Move point to the beginning or end of the current function or -top-level definition. These are found by searching for the least -enclosing braces. (By contrast, @code{beginning-of-defun} and -@code{end-of-defun} search for braces in column zero.) If you are -editing code where the opening brace of a function isn't placed in -column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to -these commands. @xref{Moving by Defuns}. - -@item C-c C-u -@kindex C-c C-u @r{(C mode)} -@findex c-up-conditional -Move point back to the containing preprocessor conditional, leaving the -mark behind. A prefix argument acts as a repeat count. With a negative -argument, move point forward to the end of the containing -preprocessor conditional. - -@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so -the function will stop at a @samp{#elif} when going backward, but not -when going forward. - -@item C-c C-p -@kindex C-c C-p @r{(C mode)} -@findex c-backward-conditional -Move point back over a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward. - -@item C-c C-n -@kindex C-c C-n @r{(C mode)} -@findex c-forward-conditional -Move point forward across a preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move backward. - -@item M-a -@kindex M-a (C mode) -@findex c-beginning-of-statement -Move point to the beginning of the innermost C statement -(@code{c-beginning-of-statement}). If point is already at the beginning -of a statement, move to the beginning of the preceding statement. With -prefix argument @var{n}, move back @var{n} @minus{} 1 statements. - -In comments or in strings which span more than one line, this command -moves by sentences instead of statements. - -@item M-e -@kindex M-e (C mode) -@findex c-end-of-statement -Move point to the end of the innermost C statement or sentence; like -@kbd{M-a} except that it moves in the other direction -(@code{c-end-of-statement}). -@end table - -@node Electric C -@subsection Electric C Characters - - In C mode and related modes, certain printing characters are -@dfn{electric}---in addition to inserting themselves, they also -reindent the current line, and optionally also insert newlines. The -``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, -@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and -@kbd{)}. - - You might find electric indentation inconvenient if you are editing -chaotically indented code. If you are new to CC Mode, you might find -it disconcerting. You can toggle electric action with the command -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: - -@table @kbd -@item C-c C-l -@kindex C-c C-l @r{(C mode)} -@findex c-toggle-electric-state -Toggle electric action (@code{c-toggle-electric-state}). With a -prefix argument, this command enables electric action if the argument -is positive, disables it if it is negative. -@end table - - Electric characters insert newlines only when, in addition to the -electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/la} in the mode line after the mode name). You can turn -this feature on or off with the command @kbd{C-c C-a}: - -@table @kbd -@item C-c C-a -@kindex C-c C-a @r{(C mode)} -@findex c-toggle-auto-newline -Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a -prefix argument, this command turns the auto-newline feature on if the -argument is positive, and off if it is negative. -@end table - - Usually the CC Mode style configures the exact circumstances in -which Emacs inserts auto-newlines. You can also configure this -directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. - -@node Hungry Delete -@subsection Hungry Delete Feature in C -@cindex hungry deletion (C Mode) - - If you want to delete an entire block of whitespace at point, you -can use @dfn{hungry deletion}. This deletes all the contiguous -whitespace either before point or after point in a single operation. -@dfn{Whitespace} here includes tabs and newlines, but not comments or -preprocessor commands. - -@table @kbd -@item C-c C-@key{DEL} -@itemx C-c @key{DEL} -@findex c-hungry-delete-backwards -@kindex C-c C-@key{DEL} (C Mode) -@kindex C-c @key{DEL} (C Mode) -@code{c-hungry-delete-backwards}---Delete the entire block of whitespace -preceding point. - -@item C-c C-d -@itemx C-c C-@key{DELETE} -@itemx C-c @key{DELETE} -@findex c-hungry-delete-forward -@kindex C-c C-d (C Mode) -@kindex C-c C-@key{DELETE} (C Mode) -@kindex C-c @key{DELETE} (C Mode) -@code{c-hungry-delete-forward}---Delete the entire block of whitespace -following point. -@end table - - As an alternative to the above commands, you can enable @dfn{hungry -delete mode}. When this feature is enabled (indicated by @samp{/h} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @key{DELETE}) deletes all following whitespace. - -@table @kbd -@item M-x c-toggle-hungry-state -@findex c-toggle-hungry-state -Toggle the hungry-delete feature -(@code{c-toggle-hungry-state})@footnote{This command had the binding -@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now -bound to @code{c-hungry-delete-forward}.}. With a prefix argument, -this command turns the hungry-delete feature on if the argument is -positive, and off if it is negative. -@end table - -@vindex c-hungry-delete-key - The variable @code{c-hungry-delete-key} controls whether the -hungry-delete feature is enabled. - -@node Other C Commands -@subsection Other Commands for C Mode - -@table @kbd -@item C-c C-w -@itemx M-x c-subword-mode -@findex c-subword-mode -Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word -commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by -the flag @samp{/w} on the mode line after the mode name -(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in -non-CC Mode buffers. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - -@item M-x c-context-line-break -@findex c-context-line-break -This command inserts a line break and indents the new line in a manner -appropriate to the context. In normal code, it does the work of -@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it -additionally inserts a @samp{\} at the line break, and within comments -it's like @kbd{M-j} (@code{c-indent-new-comment-line}). - -@code{c-context-line-break} isn't bound to a key by default, but it -needs a binding to be useful. The following code will bind it to -@kbd{C-j}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. - -@smallexample -(defun my-bind-clb () - (define-key c-mode-base-map "\C-j" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-bind-clb) -@end smallexample - -@item C-M-h -Put mark at the end of a function definition, and put point at the -beginning (@code{c-mark-function}). - -@item M-q -@kindex M-q @r{(C mode)} -@findex c-fill-paragraph -Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). -If any part of the current line is a comment or within a comment, this -command fills the comment or the paragraph of it that point is in, -preserving the comment indentation and comment delimiters. - -@item C-c C-e -@cindex macro expansion in C -@cindex expansion of C macros -@findex c-macro-expand -@kindex C-c C-e @r{(C mode)} -Run the C preprocessor on the text in the region, and show the result, -which includes the expansion of all the macro calls -(@code{c-macro-expand}). The buffer text before the region is also -included in preprocessing, for the sake of macros defined there, but the -output from this part isn't shown. - -When you are debugging C code that uses macros, sometimes it is hard to -figure out precisely how the macros expand. With this command, you -don't have to figure it out; you can see the expansions. - -@item C-c C-\ -@findex c-backslash-region -@kindex C-c C-\ @r{(C mode)} -Insert or align @samp{\} characters at the ends of the lines of the -region (@code{c-backslash-region}). This is useful after writing or -editing a C macro definition. - -If a line already ends in @samp{\}, this command adjusts the amount of -whitespace before it. Otherwise, it inserts a new @samp{\}. However, -the last line in the region is treated specially; no @samp{\} is -inserted on that line, and any @samp{\} there is deleted. - -@item M-x cpp-highlight-buffer -@cindex preprocessor highlighting -@findex cpp-highlight-buffer -Highlight parts of the text according to its preprocessor conditionals. -This command displays another buffer named @samp{*CPP Edit*}, which -serves as a graphic menu for selecting how to display particular kinds -of conditionals and their contents. After changing various settings, -click on @samp{[A]pply these settings} (or go to that buffer and type -@kbd{a}) to rehighlight the C mode buffer accordingly. - -@item C-c C-s -@findex c-show-syntactic-information -@kindex C-c C-s @r{(C mode)} -Display the syntactic information about the current source line -(@code{c-show-syntactic-information}). This information directs how -the line is indented. - -@item M-x cwarn-mode -@itemx M-x global-cwarn-mode -@findex cwarn-mode -@findex global-cwarn-mode -@vindex global-cwarn-mode -@cindex CWarn mode -@cindex suspicious constructions in C, C++ -CWarn minor mode highlights certain suspicious C and C++ constructions: - -@itemize @bullet{} -@item -Assignments inside expressions. -@item -Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} -(except after a @samp{do @dots{} while} statement); -@item -C++ functions with reference parameters. -@end itemize - -@noindent -You can enable the mode for one buffer with the command @kbd{M-x -cwarn-mode}, or for all suitable buffers with the command @kbd{M-x -global-cwarn-mode} or by customizing the variable -@code{global-cwarn-mode}. You must also enable Font Lock mode to make -it work. - -@item M-x hide-ifdef-mode -@findex hide-ifdef-mode -@cindex Hide-ifdef mode -@vindex hide-ifdef-shadow -Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. If you change the variable -@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode -``shadows'' preprocessor blocks by displaying them with a less -prominent face, instead of hiding them entirely. See the -documentation string of @code{hide-ifdef-mode} for more information. - -@item M-x ff-find-related-file -@cindex related files -@findex ff-find-related-file -@vindex ff-related-file-alist -Find a file ``related'' in a special way to the file visited by the -current buffer. Typically this will be the header file corresponding -to a C/C++ source file, or vice versa. The variable -@code{ff-related-file-alist} specifies how to compute related file -names. -@end table - -@node Asm Mode -@section Asm Mode - -@cindex Asm mode -@cindex assembler mode -Asm mode is a major mode for editing files of assembler code. It -defines these commands: - -@table @kbd -@item @key{TAB} -@code{tab-to-tab-stop}. -@item C-j -Insert a newline and then indent using @code{tab-to-tab-stop}. -@item : -Insert a colon and then remove the indentation from before the label -preceding colon. Then do @code{tab-to-tab-stop}. -@item ; -Insert or align a comment. -@end table - - The variable @code{asm-comment-char} specifies which character -starts comments in assembler syntax. - -@ifnottex -@include fortran-xtra.texi -@end ifnottex - -@ignore - arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 -@end ignore diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi deleted file mode 100644 index aeb3f6b447a..00000000000 --- a/doc/emacs/regs.texi +++ /dev/null @@ -1,336 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Registers, Display, CUA Bindings, Top -@chapter Registers -@cindex registers - - Emacs @dfn{registers} are compartments where you can save text, -rectangles, positions, and other things for later use. Once you save -text or a rectangle in a register, you can copy it into the buffer -once, or many times; once you save a position in a register, you can -jump back to that position once, or many times. - - Each register has a name that consists of a single character, which -we will denote by @var{r}; @var{r} can be a letter (such as @samp{a}) -or a number (such as @samp{1}); case matters, so register @samp{a} is -not the same as register @samp{A}. - -@findex view-register - A register can store a position, a piece of text, a rectangle, a -number, a window configuration, or a file name, but only one thing at -any given time. Whatever you store in a register remains there until -you store something else in that register. To see what register -@var{r} contains, use @kbd{M-x view-register}: - -@table @kbd -@item M-x view-register @key{RET} @var{r} -Display a description of what register @var{r} contains. -@end table - - @dfn{Bookmarks} record files and positions in them, so you can -return to those positions when you look at the file again. -Bookmarks are similar enough in spirit to registers that they -seem to belong in this chapter. - -@menu -* Position: RegPos. Saving positions in registers. -* Text: RegText. Saving text in registers. -* Rectangle: RegRect. Saving rectangles in registers. -* Configurations: RegConfig. Saving window configurations in registers. -* Numbers: RegNumbers. Numbers in registers. -* Files: RegFiles. File names in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. -@end menu - -@node RegPos -@section Saving Positions in Registers -@cindex saving position in a register - -@table @kbd -@item C-x r @key{SPC} @var{r} -Record the position of point and the current buffer in register -@var{r} (@code{point-to-register}). -@item C-x r j @var{r} -Jump to the position and buffer saved in register @var{r} -(@code{jump-to-register}). -@end table - -@kindex C-x r SPC -@findex point-to-register - Typing @kbd{C-x r @key{SPC}} (@code{point-to-register}), followed by -a character @kbd{@var{r}}, saves both the position of point and the -current buffer in register @var{r}. The register retains this -information until you store something else in it. - -@kindex C-x r j -@findex jump-to-register - The command @kbd{C-x r j @var{r}} switches to the buffer recorded in -register @var{r}, and moves point to the recorded position. The -contents of the register are not changed, so you can jump to the saved -position any number of times. - - If you use @kbd{C-x r j} to go to a saved position, but the buffer it -was saved from has been killed, @kbd{C-x r j} tries to create the buffer -again by visiting the same file. Of course, this works only for buffers -that were visiting files. - -@node RegText -@section Saving Text in Registers -@cindex saving text in a register - - When you want to insert a copy of the same piece of text several -times, it may be inconvenient to yank it from the kill ring, since each -subsequent kill moves that entry further down the ring. An alternative -is to store the text in a register and later retrieve it. - -@table @kbd -@item C-x r s @var{r} -Copy region into register @var{r} (@code{copy-to-register}). -@item C-x r i @var{r} -Insert text from register @var{r} (@code{insert-register}). -@item M-x append-to-register @key{RET} @var{r} -Append region to text in register @var{r}. -@item M-x prepend-to-register @key{RET} @var{r} -Prepend region to text in register @var{r}. -@end table - -@kindex C-x r s -@findex copy-to-register - @kbd{C-x r s @var{r}} stores a copy of the text of the region into -the register named @var{r}. If the mark is inactive, Emacs first -reactivates the mark where it was last set. The mark is deactivated -at the end of this command. @xref{Mark}. @kbd{C-u C-x r s @var{r}}, -the same command with a prefix argument, copies the text into register -@var{r} and deletes the text from the buffer as well; you can think of -this as ``moving'' the region text into the register. - -@findex append-to-register -@findex prepend-to-register - @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of -the text in the region to the text already stored in the register -named @var{r}. If invoked with a prefix argument, it deletes the -region after appending it to the register. The command -@code{prepend-to-register} is similar, except that it @emph{prepends} -the region text to the text in the register instead of -@emph{appending} it. - -@kindex C-x r i -@findex insert-register - @kbd{C-x r i @var{r}} inserts in the buffer the text from register -@var{r}. Normally it leaves point before the text and places the mark -after, but with a numeric argument (@kbd{C-u}) it puts point after the -text and the mark before. - -@node RegRect -@section Saving Rectangles in Registers -@cindex saving rectangle in a register - - A register can contain a rectangle instead of linear text. -@xref{Rectangles}, for basic information on how to specify a rectangle -in the buffer. - -@table @kbd -@findex copy-rectangle-to-register -@kindex C-x r r -@item C-x r r @var{r} -Copy the region-rectangle into register @var{r} -(@code{copy-rectangle-to-register}). With numeric argument, delete it as -well. -@item C-x r i @var{r} -Insert the rectangle stored in register @var{r} (if it contains a -rectangle) (@code{insert-register}). -@end table - - The @kbd{C-x r i @var{r}} command inserts a text string if the -register contains one, and inserts a rectangle if the register contains -one. - - See also the command @code{sort-columns}, which you can think of -as sorting a rectangle. @xref{Sorting}. - -@node RegConfig -@section Saving Window Configurations in Registers -@cindex saving window configuration in a register - -@findex window-configuration-to-register -@findex frame-configuration-to-register -@kindex C-x r w -@kindex C-x r f - You can save the window configuration of the selected frame in a -register, or even the configuration of all windows in all frames, and -restore the configuration later. @xref{Windows}, for information -about window configurations. - -@table @kbd -@item C-x r w @var{r} -Save the state of the selected frame's windows in register @var{r} -(@code{window-configuration-to-register}). -@item C-x r f @var{r} -Save the state of all frames, including all their windows, in register -@var{r} (@code{frame-configuration-to-register}). -@end table - - Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. -This is the same command used to restore a cursor position. When you -restore a frame configuration, any existing frames not included in the -configuration become invisible. If you wish to delete these frames -instead, use @kbd{C-u C-x r j @var{r}}. - -@node RegNumbers -@section Keeping Numbers in Registers -@cindex saving number in a register - - There are commands to store a number in a register, to insert -the number in the buffer in decimal, and to increment it. These commands -can be useful in keyboard macros (@pxref{Keyboard Macros}). - -@table @kbd -@item C-u @var{number} C-x r n @var{r} -@kindex C-x r n -@findex number-to-register -Store @var{number} into register @var{r} (@code{number-to-register}). -@item C-u @var{number} C-x r + @var{r} -@kindex C-x r + -@findex increment-register -Increment the number in register @var{r} by @var{number} -(@code{increment-register}). -@item C-x r i @var{r} -Insert the number from register @var{r} into the buffer. -@end table - - @kbd{C-x r i} is the same command used to insert any other sort of -register contents into the buffer. @kbd{C-x r +} with no numeric -argument increments the register value by 1; @kbd{C-x r n} with no -numeric argument stores zero in the register. - -@node RegFiles -@section Keeping File Names in Registers -@cindex saving file name in a register - - If you visit certain file names frequently, you can visit them more -conveniently if you put their names in registers. Here's the Lisp code -used to put a file name in a register: - -@smallexample -(set-register ?@var{r} '(file . @var{name})) -@end smallexample - -@need 3000 -@noindent -For example, - -@smallexample -(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) -@end smallexample - -@noindent -puts the file name shown in register @samp{z}. - - To visit the file whose name is in register @var{r}, type @kbd{C-x r j -@var{r}}. (This is the same command used to jump to a position or -restore a frame configuration.) - -@node Bookmarks -@section Bookmarks -@cindex bookmarks - - @dfn{Bookmarks} are somewhat like registers in that they record -positions you can jump to. Unlike registers, they have long names, and -they persist automatically from one Emacs session to the next. The -prototypical use of bookmarks is to record ``where you were reading'' in -various files. - -@table @kbd -@item C-x r m @key{RET} -Set the bookmark for the visited file, at point. - -@item C-x r m @var{bookmark} @key{RET} -@findex bookmark-set -Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). - -@item C-x r b @var{bookmark} @key{RET} -@findex bookmark-jump -Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). - -@item C-x r l -@findex list-bookmarks -List all bookmarks (@code{list-bookmarks}). - -@item M-x bookmark-save -@findex bookmark-save -Save all the current bookmark values in the default bookmark file. -@end table - -@kindex C-x r m -@findex bookmark-set -@kindex C-x r b -@findex bookmark-jump - The prototypical use for bookmarks is to record one current position -in each of several files. So the command @kbd{C-x r m}, which sets a -bookmark, uses the visited file name as the default for the bookmark -name. If you name each bookmark after the file it points to, then you -can conveniently revisit any of those files with @kbd{C-x r b}, and move -to the position of the bookmark at the same time. - -@kindex C-x r l - To display a list of all your bookmarks in a separate buffer, type -@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, -you can use it to edit your bookmark definitions or annotate the -bookmarks. Type @kbd{C-h m} in the bookmark buffer for more -information about its special editing commands. - - When you kill Emacs, Emacs offers to save your bookmark values in your -default bookmark file, @file{~/.emacs.bmk}, if you have changed any -bookmark values. You can also save the bookmarks at any time with the -@kbd{M-x bookmark-save} command. The bookmark commands load your -default bookmark file automatically. This saving and loading is how -bookmarks persist from one Emacs session to the next. - -@vindex bookmark-save-flag - If you set the variable @code{bookmark-save-flag} to 1, each command -that sets a bookmark will also save your bookmarks; this way, you -don't lose any bookmark values even if Emacs crashes. (The value, if -a number, says how many bookmark modifications should go by between -saving.) - -@vindex bookmark-search-size - Bookmark position values are saved with surrounding context, so that -@code{bookmark-jump} can find the proper position even if the file is -modified slightly. The variable @code{bookmark-search-size} says how -many characters of context to record on each side of the bookmark's -position. - - Here are some additional commands for working with bookmarks: - -@table @kbd -@item M-x bookmark-load @key{RET} @var{filename} @key{RET} -@findex bookmark-load -Load a file named @var{filename} that contains a list of bookmark -values. You can use this command, as well as @code{bookmark-write}, to -work with other files of bookmark values in addition to your default -bookmark file. - -@item M-x bookmark-write @key{RET} @var{filename} @key{RET} -@findex bookmark-write -Save all the current bookmark values in the file @var{filename}. - -@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} -@findex bookmark-delete -Delete the bookmark named @var{bookmark}. - -@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert-location -Insert in the buffer the name of the file that bookmark @var{bookmark} -points to. - -@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} -@findex bookmark-insert -Insert in the buffer the @emph{contents} of the file that bookmark -@var{bookmark} points to. -@end table - -@ignore - arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64 -@end ignore diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi deleted file mode 100644 index 0b5dd77b607..00000000000 --- a/doc/emacs/rmail.texi +++ /dev/null @@ -1,1484 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Rmail, Dired, Sending Mail, Top -@chapter Reading Mail with Rmail -@cindex Rmail -@cindex reading mail -@findex rmail -@findex rmail-mode -@vindex rmail-mode-hook - - Rmail is an Emacs subsystem for reading and disposing of mail that -you receive. Rmail stores mail messages in files called Rmail files. -Reading the messages in an Rmail file is done in a special major mode, -Rmail mode, which redefines most letters to run commands for managing mail. -@menu -* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. -* Scroll: Rmail Scrolling. Scrolling through a message. -* Motion: Rmail Motion. Moving to another message. -* Deletion: Rmail Deletion. Deleting and expunging messages. -* Inbox: Rmail Inbox. How mail gets into the Rmail file. -* Files: Rmail Files. Using multiple Rmail files. -* Output: Rmail Output. Copying messages out to files. -* Labels: Rmail Labels. Classifying messages by labeling them. -* Attrs: Rmail Attributes. Certain standard labels, called attributes. -* Reply: Rmail Reply. Sending replies to messages you are viewing. -* Summary: Rmail Summary. Summaries show brief info on many messages. -* Sort: Rmail Sorting. Sorting messages in Rmail. -* Display: Rmail Display. How Rmail displays a message; customization. -* Coding: Rmail Coding. How Rmail handles decoding character sets. -* Editing: Rmail Editing. Editing message text and headers in Rmail. -* Digest: Rmail Digest. Extracting the messages from a digest message. -* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. -* Movemail:: More details of fetching new mail. -* Remote Mailboxes:: Retrieving mail from remote mailboxes. -* Other Mailbox Formats:: Retrieving mail from local mailboxes in - various formats. -@end menu - -@node Rmail Basics -@section Basic Concepts of Rmail - -@cindex primary Rmail file -@vindex rmail-file-name - Using Rmail in the simplest fashion, you have one Rmail file -@file{~/RMAIL} in which all of your mail is saved. It is called your -@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary -Rmail file, merges new mail in from your inboxes, displays the first -message you haven't read yet, and lets you begin reading. The variable -@code{rmail-file-name} specifies the name of the primary Rmail file. - - Rmail displays only one message in the Rmail file at a time. -The message that is shown is called the @dfn{current message}. Rmail -mode's special commands can do such things as delete the current -message, copy it into another file, send a reply, or move to another -message. You can also create multiple Rmail files and use Rmail to move -messages between them. - -@cindex message number - Within the Rmail file, messages are normally arranged sequentially in -order of receipt; you can specify other ways to sort them (@pxref{Rmail -Sorting}). Messages are identified by consecutive integers which are -their @dfn{message numbers}. The number of the current message is -displayed in Rmail's mode line, followed by the total number of messages -in the file. You can move to a message by specifying its message number -with the @kbd{j} key (@pxref{Rmail Motion}). - -@kindex s @r{(Rmail)} -@findex rmail-expunge-and-save - Following the usual conventions of Emacs, changes in an Rmail file -become permanent only when you save the file. You can save it with -@kbd{s} (@code{rmail-expunge-and-save}), which also expunges deleted -messages from the file first (@pxref{Rmail Deletion}). To save the -file without expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail -file after merging new mail from an inbox file (@pxref{Rmail Inbox}). - -@kindex q @r{(Rmail)} -@findex rmail-quit -@kindex b @r{(Rmail)} -@findex rmail-bury - You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges -and saves the Rmail file, then buries the Rmail buffer as well as its -summary buffer, if present (@pxref{Rmail Summary}). But there is no -need to ``exit'' formally. If you switch from Rmail to editing in -other buffers, and never switch back, you have exited. Just make sure -to save the Rmail file eventually (like any other file you have -changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save -Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the -Rmail buffer and its summary buffer without expunging and saving the -Rmail file. - -@node Rmail Scrolling -@section Scrolling Within a Message - - When Rmail displays a message that does not fit on the screen, you -must scroll through it to read the rest. You could do this with -@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so -frequent that it deserves to be easier. - -@table @kbd -@item @key{SPC} -Scroll forward (@code{scroll-up}). -@item @key{DEL} -Scroll backward (@code{scroll-down}). -@item . -Scroll to start of message (@code{rmail-beginning-of-message}). -@item / -Scroll to end of message (@code{rmail-end-of-message}). -@end table - -@kindex SPC @r{(Rmail)} -@kindex DEL @r{(Rmail)} - Since the most common thing to do while reading a message is to scroll -through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of -@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}) - -@kindex . @r{(Rmail)} -@kindex / @r{(Rmail)} -@findex rmail-beginning-of-message -@findex rmail-end-of-message - The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the -beginning of the selected message. This is not quite the same as @kbd{M-<}: -for one thing, it does not set the mark; for another, it resets the buffer -boundaries of the current message if you have changed them. Similarly, -the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end -of the selected message. -@c The comment about buffer boundaries is still true in mbox Rmail, if -@c less likely to be relevant. - -@node Rmail Motion -@section Moving Among Messages - - The most basic thing to do with a message is to read it. The way to -do this in Rmail is to make the message current. The usual practice is -to move sequentially through the file, since this is the order of -receipt of messages. When you enter Rmail, you are positioned at the -first message that you have not yet made current (that is, the first one -that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move -forward to see the other new messages; move backward to re-examine old -messages. - -@table @kbd -@item n -Move to the next nondeleted message, skipping any intervening deleted -messages (@code{rmail-next-undeleted-message}). -@item p -Move to the previous nondeleted message -(@code{rmail-previous-undeleted-message}). -@item M-n -Move to the next message, including deleted messages -(@code{rmail-next-message}). -@item M-p -Move to the previous message, including deleted messages -(@code{rmail-previous-message}). -@item C-c C-n -Move to the next message with the same subject as the current one -(@code{rmail-next-same-subject}). -@item C-c C-p -Move to the previous message with the same subject as the current one -(@code{rmail-previous-same-subject}). -@item j -Move to the first message. With argument @var{n}, move to -message number @var{n} (@code{rmail-show-message}). -@item > -Move to the last message (@code{rmail-last-message}). -@item < -Move to the first message (@code{rmail-first-message}). - -@item M-s @var{regexp} @key{RET} -Move to the next message containing a match for @var{regexp} -(@code{rmail-search}). - -@item - M-s @var{regexp} @key{RET} -Move to the previous message containing a match for @var{regexp}. -@end table - -@kindex n @r{(Rmail)} -@kindex p @r{(Rmail)} -@kindex M-n @r{(Rmail)} -@kindex M-p @r{(Rmail)} -@findex rmail-next-undeleted-message -@findex rmail-previous-undeleted-message -@findex rmail-next-message -@findex rmail-previous-message - @kbd{n} and @kbd{p} are the usual way of moving among messages in -Rmail. They move through the messages sequentially, but skip over -deleted messages, which is usually what you want to do. Their command -definitions are named @code{rmail-next-undeleted-message} and -@code{rmail-previous-undeleted-message}. If you do not want to skip -deleted messages---for example, if you want to move to a message to -undelete it---use the variants @kbd{M-n} and @kbd{M-p} -(@code{rmail-next-message} and @code{rmail-previous-message}). A -numeric argument to any of these commands serves as a repeat -count. - - In Rmail, you can specify a numeric argument by typing just the -digits. You don't need to type @kbd{C-u} first. - -@kindex M-s @r{(Rmail)} -@findex rmail-search -@cindex searching in Rmail - The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of -search. The usual incremental search command @kbd{C-s} works in Rmail, -but it searches only within the current message. The purpose of -@kbd{M-s} is to search for another message. It reads a regular -expression (@pxref{Regexps}) nonincrementally, then searches starting at -the beginning of the following message for a match. It then selects -that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp -used the previous time. - - To search backward in the file for another message, give @kbd{M-s} a -negative argument. In Rmail you can do this with @kbd{- M-s}. This -begins searching from the end of the previous message. - - It is also possible to search for a message based on labels. -@xref{Rmail Labels}. - -@kindex C-c C-n @r{(Rmail)} -@kindex C-c C-p @r{(Rmail)} -@findex rmail-next-same-subject -@findex rmail-previous-same-subject - The @kbd{C-c C-n} (@code{rmail-next-same-subject}) command moves to -the next message with the same subject as the current one. A prefix -argument serves as a repeat count. With a negative argument, this -command moves backward, acting like @kbd{C-c C-p} -(@code{rmail-previous-same-subject}). When comparing subjects, these -commands ignore the prefixes typically added to the subjects of replies. - -@kindex j @r{(Rmail)} -@kindex > @r{(Rmail)} -@kindex < @r{(Rmail)} -@findex rmail-show-message -@findex rmail-last-message -@findex rmail-first-message - To move to a message specified by absolute message number, use @kbd{j} -(@code{rmail-show-message}) with the message number as argument. With -no argument, @kbd{j} selects the first message. @kbd{<} -(@code{rmail-first-message}) also selects the first message. @kbd{>} -(@code{rmail-last-message}) selects the last message. - -@node Rmail Deletion -@section Deleting Messages - -@cindex deletion (Rmail) - When you no longer need to keep a message, you can @dfn{delete} it. This -flags it as ignorable, and some Rmail commands pretend it is no longer -present; but it still has its place in the Rmail file, and still has its -message number. - -@cindex expunging (Rmail) - @dfn{Expunging} the Rmail file actually removes the deleted messages. -The remaining messages are renumbered consecutively. -@c The following is neither true (there is also unforward, sorting, -@c etc), nor especially interesting. -@c Expunging is the only action that changes the message number of any -@c message, except for undigestifying (@pxref{Rmail Digest}). - -@table @kbd -@item d -Delete the current message, and move to the next nondeleted message -(@code{rmail-delete-forward}). -@item C-d -Delete the current message, and move to the previous nondeleted -message (@code{rmail-delete-backward}). -@item u -Undelete the current message, or move back to the previous deleted -message and undelete it (@code{rmail-undelete-previous-message}). -@item x -Expunge the Rmail file (@code{rmail-expunge}). -@end table - -@kindex d @r{(Rmail)} -@kindex C-d @r{(Rmail)} -@findex rmail-delete-forward -@findex rmail-delete-backward - There are two Rmail commands for deleting messages. Both delete the -current message and select another message. @kbd{d} -(@code{rmail-delete-forward}) moves to the following message, skipping -messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) -moves to the previous nondeleted message. If there is no nondeleted -message to move to in the specified direction, the message that was just -deleted remains current. @kbd{d} with a prefix argument is equivalent -to @kbd{C-d}. Note that the Rmail summary versions of these commands -behave slightly differently (@pxref{Rmail Summary Edit}). - -@c mention other hooks, eg show message hook? -@vindex rmail-delete-message-hook - Whenever Rmail deletes a message, it runs the hook -@code{rmail-delete-message-hook}. When the hook functions are invoked, -the message has been marked deleted, but it is still the current message -in the Rmail buffer. - -@cindex undeletion (Rmail) -@kindex x @r{(Rmail)} -@findex rmail-expunge -@kindex u @r{(Rmail)} -@findex rmail-undelete-previous-message - To make all the deleted messages finally vanish from the Rmail file, -type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still -@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} -(@code{rmail-undelete-previous-message}), is designed to cancel the -effect of a @kbd{d} command in most cases. It undeletes the current -message if the current message is deleted. Otherwise it moves backward -to previous messages until a deleted message is found, and undeletes -that message. - - You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} -moves back to and undeletes the message that the @kbd{d} deleted. But -this does not work when the @kbd{d} skips a few already-deleted messages -that follow the message being deleted; then the @kbd{u} command -undeletes the last of the messages that were skipped. There is no clean -way to avoid this problem. However, by repeating the @kbd{u} command, -you can eventually get back to the message that you intend to -undelete. You can also select a particular deleted message with -the @kbd{M-p} command, then type @kbd{u} to undelete it. - - A deleted message has the @samp{deleted} attribute, and as a result -@samp{deleted} appears in the mode line when the current message is -deleted. In fact, deleting or undeleting a message is nothing more than -adding or removing this attribute. @xref{Rmail Attributes}. - -@node Rmail Inbox -@section Rmail Files and Inboxes -@cindex inbox file - - When you receive mail locally, the operating system places incoming -mail for you in a file that we call your @dfn{inbox}. When you start -up Rmail, it runs a C program called @code{movemail} to copy the new -messages from your local inbox into your primary Rmail file, which -also contains other messages saved from previous Rmail sessions. It -is in this file that you actually read the mail with Rmail. This -operation is called @dfn{getting new mail}. You can get new mail at -any time in Rmail by typing @kbd{g}. - -@vindex rmail-primary-inbox-list -@cindex @env{MAIL} environment variable - The variable @code{rmail-primary-inbox-list} contains a list of the -files which are inboxes for your primary Rmail file. If you don't set -this variable explicitly, Rmail uses the @env{MAIL} environment -variable, or, as a last resort, a default inbox based on -@code{rmail-spool-directory}. The default inbox file depends on your -operating system; often it is @file{/var/mail/@var{username}}, -@file{/var/spool/mail/@var{username}}, or -@file{/usr/spool/mail/@var{username}}. - - You can specify the inbox file(s) for any Rmail file for the current -session with the command @code{set-rmail-inbox-list}; see @ref{Rmail -Files}. - - There are two reasons for having separate Rmail files and inboxes. - -@enumerate -@item -The inbox file format varies between operating systems and according to -the other mail software in use. Only one part of Rmail needs to know -about the alternatives, and it need only understand how to convert all -of them to Rmail's own format. - -@item -It is very cumbersome to access an inbox file without danger of losing -mail, because it is necessary to interlock with mail delivery. -Moreover, different operating systems use different interlocking -techniques. The strategy of moving mail out of the inbox once and for -all into a separate Rmail file avoids the need for interlocking in all -the rest of Rmail, since only Rmail operates on the Rmail file. -@end enumerate - - Rmail was originally written to use the Babyl format as its internal -format. Since then, we have recognized that the usual inbox format -(@samp{mbox}) on Unix and GNU systems is adequate for the job, and so -since Emacs 23 Rmail uses that as its internal format. The Rmail file -is still separate from the inbox file, even though their format is the -same. - -@vindex rmail-preserve-inbox - When getting new mail, Rmail first copies the new mail from the -inbox file to the Rmail file; then it saves the Rmail file; then it -clears out the inbox file. This way, a system crash may cause -duplication of mail between the inbox and the Rmail file, but cannot -lose mail. If @code{rmail-preserve-inbox} is non-@code{nil}, then -Rmail does not clear out the inbox file when it gets new mail. You -may wish to set this, for example, on a portable computer you use to -check your mail via POP while traveling, so that your mail will remain -on the server and you can save it later on your workstation. - - In some cases, Rmail copies the new mail from the inbox file -indirectly. First it runs the @code{movemail} program to move the mail -from the inbox to an intermediate file called -@file{.newmail-@var{inboxname}}, in the same directory as the Rmail -file. Then Rmail merges the new mail from that file, saves the Rmail -file, and only then deletes the intermediate file. If there is a crash -at the wrong time, this file continues to exist, and Rmail will use it -again the next time it gets new mail from that inbox. - - If Rmail is unable to convert the data in -@file{.newmail-@var{inboxname}} into mbox format, it renames the file to -@file{RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the name -unique) so that Rmail will not have trouble with the data again. You -should look at the file, find whatever message confuses Rmail (probably -one that includes the control-underscore character, octal code 037), and -delete it. Then you can use @kbd{1 g} to get new mail from the -corrected file. - -@node Rmail Files -@section Multiple Rmail Files - - Rmail operates by default on your @dfn{primary Rmail file}, which is named -@file{~/RMAIL} and receives your incoming mail from your system inbox file. -But you can also have other Rmail files and edit them with Rmail. These -files can receive mail through their own inboxes, or you can move messages -into them with explicit Rmail commands (@pxref{Rmail Output}). - -@table @kbd -@item i @var{file} @key{RET} -Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). - -@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} -Specify inbox file names for current Rmail file to get mail from. - -@item g -Merge new mail from current Rmail file's inboxes -(@code{rmail-get-new-mail}). - -@item C-u g @var{file} @key{RET} -Merge new mail from inbox file @var{file}. -@end table - -@kindex i @r{(Rmail)} -@findex rmail-input - To run Rmail on a file other than your primary Rmail file, you can use -the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file -in Rmail mode. You can use @kbd{M-x rmail-input} even when not in -Rmail, but it is easier to type @kbd{C-u M-x rmail}, which does the -same thing. - - The file you read with @kbd{i} should normally be a valid mbox file. -If it is not, Rmail tries to convert its text to mbox format, and -visits the converted text in the buffer. If you save the buffer, that -converts the file. - - If you specify a file name that doesn't exist, @kbd{i} initializes a -new buffer for creating a new Rmail file. - -@vindex rmail-secondary-file-directory -@vindex rmail-secondary-file-regexp - You can also select an Rmail file from a menu. In the Classify menu, -choose the Input Rmail File item; then choose the Rmail file you want. -The variables @code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that match -the regular expression). If no files match, you cannot select this menu -item. These variables also apply to choosing a file for output -(@pxref{Rmail Output}). - -@ignore -@findex set-rmail-inbox-list - Each Rmail file can contain a list of inbox file names; you can specify -this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} -@key{RET}}. The argument can contain any number of file names, separated -by commas. It can also be empty, which specifies that this file should -have no inboxes. Once you specify a list of inboxes in an Rmail file, -the Rmail file remembers it permanently until you specify a different list. -@end ignore - -@vindex rmail-inbox-list - The inbox files to use are specified by the variable -@code{rmail-inbox-list}, which is buffer-local in Rmail mode. As a -special exception, if you have specified no inbox files for your primary -Rmail file, it uses the @env{MAIL} environment variable, or your -standard system inbox. - -@kindex g @r{(Rmail)} -@findex rmail-get-new-mail - The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the -current Rmail file from its inboxes. If the Rmail file has no -inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} also -merges new mail into your primary Rmail file. - - To merge mail from a file that is not the usual inbox, give the -@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file -name and merges mail from that file. The inbox file is not deleted or -changed in any way when @kbd{g} with an argument is used. This is, -therefore, a general way of merging one file of messages into another. - -@node Rmail Output -@section Copying Messages Out to Files - - These commands copy messages from an Rmail file into another file. - -@table @kbd -@item o @var{file} @key{RET} -Append a full copy of the current message to the file @var{file} -(@code{rmail-output}). - -@item C-o @var{file} @key{RET} -Append a copy of the current message, as displayed, to the file -@var{file} (@code{rmail-output-as-seen}). - -@item w @var{file} @key{RET} -Output just the message body to the file @var{file}, taking the default -file name from the message @samp{Subject} header. -@end table - -@kindex o @r{(Rmail)} -@findex rmail-output-as-seen -@kindex C-o @r{(Rmail)} -@findex rmail-output - The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file, adding it at the end. The two commands differ mainly -in how much to copy: @kbd{o} copies the full message headers, even if -they are not all visible, while @kbd{C-o} copies exactly the headers -currently displayed and no more. @xref{Rmail Display}. In addition, -@kbd{o} converts the message to Babyl format (used by Rmail in Emacs -version 22 and before) if the file is in Babyl format; @kbd{C-o} -cannot output to Babyl files at all. - - If the output file is currently visited in an Emacs buffer, the -output commands append the message to that buffer. It is up to you to -save the buffer eventually in its file. - -@kindex w @r{(Rmail)} -@findex rmail-output-body-to-file - Sometimes you may receive a message whose body holds the contents of a -file. You can save the body to a file (excluding the message header) -with the @kbd{w} command (@code{rmail-output-body-to-file}). Often -these messages contain the intended file name in the @samp{Subject} -field, so the @kbd{w} command uses the @samp{Subject} field as the -default for the output file name. However, the file name is read using -the minibuffer, so you can specify a different name if you wish. - - You can also output a message to an Rmail file chosen with a menu. -In the Classify menu, choose the Output Rmail File menu item; then -choose the Rmail file you want. This outputs the current message to -that file, like the @kbd{o} command. The variables -@code{rmail-secondary-file-directory} and -@code{rmail-secondary-file-regexp} specify which files to offer in the -menu: the first variable says which directory to find them in; the -second says which files in that directory to offer (all those that -match the regular expression). If no files match, you cannot select -this menu item. - -@vindex rmail-delete-after-output - Copying a message with @kbd{o} or @kbd{C-o} gives the original copy -of the message the @samp{filed} attribute, so that @samp{filed} -appears in the mode line when such a message is current. - - If you like to keep just a single copy of every mail message, set -the variable @code{rmail-delete-after-output} to @code{t}; then the -@kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message -after copying it. (You can undelete it afterward if you wish.) - -@vindex rmail-output-file-alist - The variable @code{rmail-output-file-alist} lets you specify -intelligent defaults for the output file, based on the contents of the -current message. The value should be a list whose elements have this -form: - -@example -(@var{regexp} . @var{name-exp}) -@end example - -@noindent -If there's a match for @var{regexp} in the current message, then the -default file name for output is @var{name-exp}. If multiple elements -match the message, the first matching element decides the default file -name. The subexpression @var{name-exp} may be a string constant giving -the file name to use, or more generally it may be any Lisp expression -that returns a file name as a string. @code{rmail-output-file-alist} -applies to both @kbd{o} and @kbd{C-o}. - -@node Rmail Labels -@section Labels -@cindex label (Rmail) -@cindex attribute (Rmail) - - Each message can have various @dfn{labels} assigned to it as a means -of classification. Each label has a name; different names are different -labels. Any given label is either present or absent on a particular -message. A few label names have standard meanings and are given to -messages automatically by Rmail when appropriate; these special labels -are called @dfn{attributes}. -@ifnottex -(@xref{Rmail Attributes}.) -@end ifnottex -All other labels are assigned only by users. - -@table @kbd -@item a @var{label} @key{RET} -Assign the label @var{label} to the current message (@code{rmail-add-label}). -@item k @var{label} @key{RET} -Remove the label @var{label} from the current message (@code{rmail-kill-label}). -@item C-M-n @var{labels} @key{RET} -Move to the next message that has one of the labels @var{labels} -(@code{rmail-next-labeled-message}). -@item C-M-p @var{labels} @key{RET} -Move to the previous message that has one of the labels @var{labels} -(@code{rmail-previous-labeled-message}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Make a summary of all messages containing any of the labels @var{labels} -(@code{rmail-summary-by-labels}). -@end table - -@kindex a @r{(Rmail)} -@kindex k @r{(Rmail)} -@findex rmail-add-label -@findex rmail-kill-label - The @kbd{a} (@code{rmail-add-label}) and @kbd{k} -(@code{rmail-kill-label}) commands allow you to assign or remove any -label on the current message. If the @var{label} argument is empty, it -means to assign or remove the same label most recently assigned or -removed. - - Once you have given messages labels to classify them as you wish, there -are three ways to use the labels: in moving, in summaries, and in sorting. - -@kindex C-M-n @r{(Rmail)} -@kindex C-M-p @r{(Rmail)} -@findex rmail-next-labeled-message -@findex rmail-previous-labeled-message - The command @kbd{C-M-n @var{labels} @key{RET}} -(@code{rmail-next-labeled-message}) moves to the next message that has -one of the labels @var{labels}. The argument @var{labels} specifies one -or more label names, separated by commas. @kbd{C-M-p} -(@code{rmail-previous-labeled-message}) is similar, but moves backwards -to previous messages. A numeric argument to either command serves as a -repeat count. - - The command @kbd{C-M-l @var{labels} @key{RET}} -(@code{rmail-summary-by-labels}) displays a summary containing only the -messages that have at least one of a specified set of labels. The -argument @var{labels} is one or more label names, separated by commas. -@xref{Rmail Summary}, for information on summaries. - - If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or -@kbd{C-M-l} is empty, it means to use the last set of labels specified -for any of these commands. - - @xref{Rmail Sorting}, for information on sorting messages with labels. - -@node Rmail Attributes -@section Rmail Attributes - - Some labels such as @samp{deleted} and @samp{filed} have built-in -meanings, and Rmail assigns them to messages automatically at -appropriate times; these labels are called @dfn{attributes}. Here is -a list of Rmail attributes: - -@table @samp -@item unseen -Means the message has never been current. Assigned to messages when -they come from an inbox file, and removed when a message is made -current. When you start Rmail, it initially shows the first message -that has this attribute. -@item deleted -Means the message is deleted. Assigned by deletion commands and -removed by undeletion commands (@pxref{Rmail Deletion}). -@item filed -Means the message has been copied to some other file. Assigned by the -@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). -@item answered -Means you have mailed an answer to the message. Assigned by the @kbd{r} -command (@code{rmail-reply}). @xref{Rmail Reply}. -@item forwarded -Means you have forwarded the message. Assigned by the @kbd{f} command -(@code{rmail-forward}). @xref{Rmail Reply}. -@item edited -Means you have edited the text of the message within Rmail. -@xref{Rmail Editing}. -@item resent -Means you have resent the message. Assigned by the command @kbd{M-x -rmail-resend}. @xref{Rmail Reply}. -@item retried -Means you have retried a failed outgoing message. Assigned by the -command @kbd{M-x rmail-retry-failure}. @xref{Rmail Reply}. -@end table - - All other labels are assigned or removed only by users, and have no -standard meaning. - -@node Rmail Reply -@section Sending Replies - - Rmail has several commands that use Mail mode to send outgoing mail. -@xref{Sending Mail}, for information on using Mail mode, including -certain features meant to work with Rmail. What this section documents -are the special commands of Rmail for entering Mail mode. Note that the -usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 -m}---also work normally in Rmail mode. - -@table @kbd -@item m -Send a message (@code{rmail-mail}). -@item c -Continue editing the already started outgoing message (@code{rmail-continue}). -@item r -Send a reply to the current Rmail message (@code{rmail-reply}). -@item f -Forward the current message to other users (@code{rmail-forward}). -@item C-u f -Resend the current message to other users (@code{rmail-resend}). -@item M-m -Try sending a bounced message a second time (@code{rmail-retry-failure}). -@end table - -@kindex r @r{(Rmail)} -@findex rmail-reply -@cindex reply to a message - The most common reason to send a message while in Rmail is to reply -to the message you are reading. To do this, type @kbd{r} -(@code{rmail-reply}). This displays the @samp{*mail*} buffer in -another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and -@samp{References} header fields based on the message you are replying -to. The @samp{To} field starts out as the address of the person who -sent the message you received, and the @samp{CC} field starts out with -all the other recipients of that message. - -@vindex rmail-dont-reply-to-names - You can exclude certain recipients from being included automatically -in replies, using the variable @code{rmail-dont-reply-to-names}. Its -value should be a regular expression; any recipients that match are -excluded from the @samp{CC} field. They are also excluded from the -@samp{To} field, unless this would leave the field empty. If this -variable is nil, then the first time you compose a reply it is -initialized to a default value that matches your own address, and any -name starting with @samp{info-}. (Those names are excluded because -there is a convention of using them for large mailing lists to broadcast -announcements.) - - To omit the @samp{CC} field completely for a particular reply, enter -the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. -This means to reply only to the sender of the original message. - - Once the @samp{*mail*} buffer has been initialized, editing and -sending the mail goes as usual (@pxref{Sending Mail}). You can edit the -presupplied header fields if they are not what you want. You can also -use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c -C-y} which yanks in the message that you are replying to. You can -also switch to the Rmail buffer, select a different message there, switch -back, and yank the new current message. - -@kindex M-m @r{(Rmail)} -@findex rmail-retry-failure -@cindex retrying a failed message -@vindex rmail-retry-ignored-headers - Sometimes a message does not reach its destination. Mailers usually -send the failed message back to you, enclosed in a @dfn{failure -message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) -prepares to send the same message a second time: it sets up a -@samp{*mail*} buffer with the same text and header fields as before. If -you type @kbd{C-c C-c} right away, you send the message again exactly -the same as the first time. Alternatively, you can edit the text or -headers and then send it. The variable -@code{rmail-retry-ignored-headers}, in the same format as -@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which -headers are stripped from the failed message when retrying it. - -@kindex f @r{(Rmail)} -@findex rmail-forward -@cindex forwarding a message - Another frequent reason to send mail in Rmail is to @dfn{forward} the -current message to other users. @kbd{f} (@code{rmail-forward}) makes -this easy by preinitializing the @samp{*mail*} buffer with the current -message as the text, and a subject designating a forwarded message. All -you have to do is fill in the recipients and send. When you forward a -message, recipients get a message which is ``from'' you, and which has -the original message in its contents. - -@findex unforward-rmail-message - Forwarding a message encloses it between two delimiter lines. It also -modifies every line that starts with a dash, by inserting @w{@samp{- }} -at the start of the line. When you receive a forwarded message, if it -contains something besides ordinary text---for example, program source -code---you might find it useful to undo that transformation. You can do -this by selecting the forwarded message and typing @kbd{M-x -unforward-rmail-message}. This command extracts the original forwarded -message, deleting the inserted @w{@samp{- }} strings, and inserts it -into the Rmail file as a separate message immediately following the -current one. - -@findex rmail-resend - @dfn{Resending} is an alternative similar to forwarding; the -difference is that resending sends a message that is ``from'' the -original sender, just as it reached you---with a few added header fields -(@samp{Resent-From} and @samp{Resent-To}) to indicate that it came via -you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs -@code{rmail-forward}, which invokes @code{rmail-resend} if you provide a -numeric argument.) - -@kindex m @r{(Rmail)} -@findex rmail-mail - Use the @kbd{m} (@code{rmail-mail}) command to start editing an -outgoing message that is not a reply. It leaves the header fields empty. -Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer -accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be -used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f} -can do. - -@kindex c @r{(Rmail)} -@findex rmail-continue - The @kbd{c} (@code{rmail-continue}) command resumes editing the -@samp{*mail*} buffer, to finish editing an outgoing message you were -already composing, or to alter a message you have sent. - -@vindex rmail-mail-new-frame - If you set the variable @code{rmail-mail-new-frame} to a -non-@code{nil} value, then all the Rmail commands to start sending a -message create a new frame to edit it in. This frame is deleted when -you send the message, or when you use the @samp{Cancel} item in the -@samp{Mail} menu. - - All the Rmail commands to send a message use the mail-composition -method that you have chosen (@pxref{Mail Methods}). - -@node Rmail Summary -@section Summaries -@cindex summary (Rmail) - - A @dfn{summary} is a buffer containing one line per message to give -you an overview of the mail in an Rmail file. Each line shows the -message number and date, the sender, the line count, the labels, and -the subject. Moving point in the summary buffer selects messages as -you move to their summary lines. Almost all Rmail commands are valid -in the summary buffer also; when used there, they apply to the message -described by the current line of the summary. - - A summary buffer applies to a single Rmail file only; if you are -editing multiple Rmail files, each one can have its own summary buffer. -The summary buffer name is made by appending @samp{-summary} to the -Rmail buffer's name. Normally only one summary buffer is displayed at a -time. - -@menu -* Rmail Make Summary:: Making various sorts of summaries. -* Rmail Summary Edit:: Manipulating messages from the summary. -@end menu - -@node Rmail Make Summary -@subsection Making Summaries - - Here are the commands to create a summary for the current Rmail -buffer. Once the Rmail buffer has a summary, changes in the Rmail -buffer (such as deleting or expunging messages, and getting new mail) -automatically update the summary. - -@table @kbd -@item h -@itemx C-M-h -Summarize all messages (@code{rmail-summary}). -@item l @var{labels} @key{RET} -@itemx C-M-l @var{labels} @key{RET} -Summarize messages that have one or more of the specified labels -(@code{rmail-summary-by-labels}). -@item C-M-r @var{rcpts} @key{RET} -Summarize messages that match the specified recipients -(@code{rmail-summary-by-recipients}). -@item C-M-t @var{topic} @key{RET} -Summarize messages that have a match for the specified regexp -@var{topic} in their subjects (@code{rmail-summary-by-topic}). -@item C-M-s @var{regexp} @key{RET} -Summarize messages whose headers match the specified regular expression -@var{regexp} (@code{rmail-summary-by-regexp}). -@item C-M-f @var{senders} @key{RET} -Summarize messages that match the specified senders. -(@code{rmail-summary-by-senders}). -@end table - -@kindex h @r{(Rmail)} -@findex rmail-summary - The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer -for the current Rmail buffer with a summary of all the messages in the buffer. -It then displays and selects the summary buffer in another window. - -@kindex l @r{(Rmail)} -@kindex C-M-l @r{(Rmail)} -@findex rmail-summary-by-labels - @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes -a partial summary mentioning only the messages that have one or more of the -labels @var{labels}. @var{labels} should contain label names separated by -commas. - -@kindex C-M-r @r{(Rmail)} -@findex rmail-summary-by-recipients - @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) -makes a partial summary mentioning only the messages that have one or -more recipients matching the regular expression @var{rcpts}. You can -use commas to separate multiple regular expressions. These are matched -against the @samp{To}, @samp{From}, and @samp{CC} headers (with a prefix -argument, this header is not included). - -@kindex C-M-t @r{(Rmail)} -@findex rmail-summary-by-topic - @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) -makes a partial summary mentioning only the messages whose subjects have -a match for the regular expression @var{topic}. You can use commas to -separate multiple regular expressions. With a prefix argument, the -match is against the whole message, not just the subject. - -@kindex C-M-s @r{(Rmail)} -@findex rmail-summary-by-regexp - @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) -makes a partial summary that mentions only the messages whose headers -(including the date and the subject lines) match the regular -expression @var{regexp}. - -@kindex C-M-f @r{(Rmail)} -@findex rmail-summary-by-senders - @kbd{C-M-f @var{senders} @key{RET}} (@code{rmail-summary-by-senders}) -makes a partial summary that mentions only the messages whose @samp{From} -fields match the regular expression @var{senders}. You can use commas to -separate multiple regular expressions. - - Note that there is only one summary buffer for any Rmail buffer; -making any kind of summary discards any previous summary. - -@vindex rmail-summary-window-size -@vindex rmail-summary-line-count-flag - The variable @code{rmail-summary-window-size} says how many lines to -use for the summary window. The variable -@code{rmail-summary-line-count-flag} controls whether the summary line -for a message should include the line count of the message. Setting -this option to nil might speed up the generation of summaries. - -@node Rmail Summary Edit -@subsection Editing in Summaries - - You can use the Rmail summary buffer to do almost anything you can do -in the Rmail buffer itself. In fact, once you have a summary buffer, -there's no need to switch back to the Rmail buffer. - - You can select and display various messages in the Rmail buffer, from -the summary buffer, just by moving point in the summary buffer to -different lines. It doesn't matter what Emacs command you use to move -point; whichever line point is on at the end of the command, that -message is selected in the Rmail buffer. - - Almost all Rmail commands work in the summary buffer as well as in the -Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current -message, @kbd{u} undeletes, and @kbd{x} expunges. (However, in the -summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} -serves as a repeat count. A negative argument reverses the meaning of -@kbd{d} and @kbd{C-d}. Also, if there are no more undeleted messages in -the relevant direction, the delete commands go to the first or last -message, rather than staying on the current message.) @kbd{o} and -@kbd{C-o} output the current message to a FILE; @kbd{r} starts a reply -to it; etc. You can scroll the current message while remaining in the -summary buffer using @key{SPC} and @key{DEL}. -@c rmail-summary-scroll-between-messages not mentioned. - -@findex rmail-summary-undelete-many -@kbd{M-u} (@code{rmail-summary-undelete-many}) undeletes all deleted -messages in the summary. A prefix argument means to undelete that many -of the previous deleted messages. - - The Rmail commands to move between messages also work in the summary -buffer, but with a twist: they move through the set of messages included -in the summary. They also ensure the Rmail buffer appears on the screen -(unlike cursor motion commands, which update the contents of the Rmail -buffer but don't display it in a window unless it already appears). -Here is a list of these commands: - -@table @kbd -@item n -Move to next line, skipping lines saying `deleted', and select its -message (@code{rmail-summary-next-msg}). -@item p -Move to previous line, skipping lines saying `deleted', and select -its message (@code{rmail-summary-previous-msg}). -@item M-n -Move to next line and select its message (@code{rmail-summary-next-all}). -@item M-p -Move to previous line and select its message -(@code{rmail-summary-previous-all}). -@item > -Move to the last line, and select its message -(@code{rmail-summary-last-message}). -@item < -Move to the first line, and select its message -(@code{rmail-summary-first-message}). -@item j -@itemx @key{RET} -Select the message on the current line (ensuring that the Rmail buffer -appears on the screen; @code{rmail-summary-goto-msg}). With argument -@var{n}, select message number @var{n} and move to its line in the -summary buffer; this signals an error if the message is not listed in -the summary buffer. -@item M-s @var{pattern} @key{RET} -Search through messages for @var{pattern} starting with the current -message; select the message found, and move point in the summary buffer -to that message's line (@code{rmail-summary-search}). A prefix argument -acts as a repeat count; a negative argument means search backward -(equivalent to @code{rmail-summary-search-backward}.) -@item C-M-n @var{labels} @key{RET} -Move to the next message with at least one of the specified labels -(@code{rmail-summary-next-labeled-message}). @var{labels} is a -comma-separated list of labels. A prefix argument acts as a repeat -count. -@item C-M-p @var{labels} @key{RET} -Move to the previous message with at least one of the specified labels -(@code{rmail-summary-previous-labeled-message}). -@item C-c C-n @key{RET} -Move to the next message with the same subject as the current message -(@code{rmail-summary-next-same-subject}). A prefix argument acts as a -repeat count. -@item C-c C-p @key{RET} -Move to the previous message with the same subject as the current message -(@code{rmail-summary-previous-same-subject}). -@end table - -@vindex rmail-redisplay-summary - Deletion, undeletion, and getting new mail, and even selection of a -different message all update the summary buffer when you do them in the -Rmail buffer. If the variable @code{rmail-redisplay-summary} is -non-@code{nil}, these actions also bring the summary buffer back onto -the screen. - -@kindex Q @r{(Rmail summary)} -@findex rmail-summary-wipe -@kindex q @r{(Rmail summary)} -@findex rmail-summary-quit -@kindex b @r{(Rmail summary)} -@findex rmail-summary-bury - When you are finished using the summary, type @kbd{Q} -(@code{rmail-summary-wipe}) to delete the summary buffer's window. You -can also exit Rmail while in the summary: @kbd{q} -(@code{rmail-summary-quit}) deletes the summary window, then exits from -Rmail by saving the Rmail file and switching to another buffer. -Alternatively, @kbd{b} (@code{rmail-summary-bury}) simply buries the -Rmail summary and buffer. - -@node Rmail Sorting -@section Sorting the Rmail File -@cindex sorting Rmail file -@cindex Rmail file sorting - -@table @kbd -@findex rmail-sort-by-date -@item C-c C-s C-d -@itemx M-x rmail-sort-by-date -Sort messages of current Rmail buffer by date. - -@findex rmail-sort-by-subject -@item C-c C-s C-s -@itemx M-x rmail-sort-by-subject -Sort messages of current Rmail buffer by subject. - -@findex rmail-sort-by-author -@item C-c C-s C-a -@itemx M-x rmail-sort-by-author -Sort messages of current Rmail buffer by author's name. - -@findex rmail-sort-by-recipient -@item C-c C-s C-r -@itemx M-x rmail-sort-by-recipient -Sort messages of current Rmail buffer by recipient's names. - -@findex rmail-sort-by-correspondent -@item C-c C-s C-c -@itemx M-x rmail-sort-by-correspondent -Sort messages of current Rmail buffer by the name of the other -correspondent. - -@findex rmail-sort-by-lines -@item C-c C-s C-l -@itemx M-x rmail-sort-by-lines -Sort messages of current Rmail buffer by number of lines. - -@findex rmail-sort-by-labels -@item C-c C-s C-k @key{RET} @var{labels} @key{RET} -@itemx M-x rmail-sort-by-labels @key{RET} @var{labels} @key{RET} -Sort messages of current Rmail buffer by labels. The argument -@var{labels} should be a comma-separated list of labels. The order of -these labels specifies the order of messages; messages with the first -label come first, messages with the second label come second, and so on. -Messages that have none of these labels come last. -@end table - - The Rmail sort commands perform a @emph{stable sort}: if there is no -reason to prefer either one of two messages, their order remains -unchanged. You can use this to sort by more than one criterion. For -example, if you use @code{rmail-sort-by-date} and then -@code{rmail-sort-by-author}, messages from the same author appear in -order by date. - - With a prefix argument, all these commands reverse the order of -comparison. This means they sort messages from newest to oldest, from -biggest to smallest, or in reverse alphabetical order. - - The same keys in the summary buffer run similar functions; for -example, @kbd{C-c C-s C-l} runs @code{rmail-summary-sort-by-lines}. -Note that these commands always sort the whole Rmail buffer, even if the -summary is only showing a subset of messages. - - Note that you cannot undo a sort, so you may wish to save the Rmail -buffer before sorting it. - -@node Rmail Display -@section Display of Messages - - Rmail reformats the header of each message before displaying it for -the first time. Reformatting hides uninteresting header fields to -reduce clutter. You can use the @kbd{t} command to show the entire -header or to repeat the header reformatting operation. - -@table @kbd -@item t -Toggle display of complete header (@code{rmail-toggle-header}). -@end table - -@vindex rmail-ignored-headers -@vindex rmail-nonignored-headers - Reformatting the header involves deleting most header fields, on the -grounds that they are not interesting. The variable -@code{rmail-ignored-headers} holds a regular expression that specifies -which header fields to hide in this way---if it matches the beginning -of a header field, that whole field is hidden. However, the variable -@code{rmail-nonignored-headers} provides a further override: a header -matching that regular expression is shown even if it matches -@code{rmail-ignored-headers} too. - -@vindex rmail-displayed-headers - As an alternative to the previous two variables, you can set -@code{rmail-displayed-headers} instead. If non-@code{nil}, this should -be a regular expression specifying which headers to display. - -@kindex t @r{(Rmail)} -@findex rmail-toggle-header - To see the complete, original header, use the @kbd{t} command -(@code{rmail-toggle-header}). This discards the reformatted headers of -the current message and displays it with the original header. Repeating -@kbd{t} reformats the message again, which shows only the interesting -headers according to the current values of the above variables. -Selecting the message again also reformats it if necessary. - - When the @kbd{t} command has a prefix argument, a positive argument -means to show the reformatted header, and a zero or negative argument -means to show the full header. - -@vindex rmail-highlighted-headers - Rmail highlights certain header fields that are especially -interesting---by default, the @samp{From} and @samp{Subject} fields. -The variable @code{rmail-highlighted-headers} holds a regular expression -that specifies the header fields to highlight; if it matches the -beginning of a header field, that whole field is highlighted. To turn -off this feature, set @code{rmail-highlighted-headers} to @code{nil}. -Customize the face @code{rmail-highlight} to adjust the style of the -highlighting. - - You can highlight and activate URLs in incoming messages using -Goto Address mode: - -@c FIXME goto-addr.el commentary says to use goto-address instead. -@smallexample -(add-hook 'rmail-show-message-hook (lambda () (goto-address-mode 1))) -@end smallexample - -@noindent -Then you can browse these URLs by clicking on them with @kbd{Mouse-2} -(or @kbd{Mouse-1} quickly) or by moving to one and typing @kbd{C-c -@key{RET}}. @xref{Goto Address mode, Activating URLs, Activating URLs}. - -@cindex MIME messages (Rmail) -@findex rmail-mime -@kindex v @r{(Rmail)} - The @kbd{v} (@code{rmail-mime}) command creates a temporary buffer -displaying the current MIME message. By default, it displays plain text -and multipart messages, and offers buttons to save attachments. - -@node Rmail Coding -@section Rmail and Coding Systems - -@cindex decoding mail messages (Rmail) - Rmail automatically decodes messages which contain non-@acronym{ASCII} -characters, just as Emacs does with files you visit and with subprocess -output. Rmail uses the standard @samp{charset=@var{charset}} header in -the message, if any, to determine how the message was encoded by the -sender. It maps @var{charset} into the corresponding Emacs coding -system (@pxref{Coding Systems}), and uses that coding system to decode -message text. If the message header doesn't have the @samp{charset} -specification, or if @var{charset} is not recognized, -Rmail chooses the coding system with the usual Emacs heuristics and -defaults (@pxref{Recognize Coding}). - -@cindex fixing incorrectly decoded mail messages - Occasionally, a message is decoded incorrectly, either because Emacs -guessed the wrong coding system in the absence of the @samp{charset} -specification, or because the specification was inaccurate. For -example, a misconfigured mailer could send a message with a -@samp{charset=iso-8859-1} header when the message is actually encoded -in @code{koi8-r}. When you see the message text garbled, or some of -its characters displayed as empty boxes, this may have happened. - -@findex rmail-redecode-body - You can correct the problem by decoding the message again using the -right coding system, if you can figure out or guess which one is -right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. -It reads the name of a coding system, and then redecodes the message -using the coding system you specified. If you specified the right -coding system, the result should be readable. - -@node Rmail Editing -@section Editing Within a Message - - Most of the usual Emacs keybindings are available in Rmail mode, though a -few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for -other purposes. However, the Rmail buffer is normally read only, and -most of the letters are redefined as Rmail commands. If you want to -edit the text of a message, you must use the Rmail command @kbd{e}. - -@table @kbd -@item e -Edit the current message as ordinary text. -@end table - -@kindex e @r{(Rmail)} -@findex rmail-edit-current-message - The @kbd{e} command (@code{rmail-edit-current-message}) switches from -Rmail mode into Rmail Edit mode, another major mode which is nearly the -same as Text mode. The mode line indicates this change. - - In Rmail Edit mode, letters insert themselves as usual and the Rmail -commands are not available. You can edit the message body and header -fields. When you are finished editing the message, type @kbd{C-c C-c} -to switch back to Rmail mode. Alternatively, you can return to Rmail -mode but cancel any editing that you have done, by typing @kbd{C-c C-]}. - -@vindex rmail-edit-mode-hook - Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then -it runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). -Returning to ordinary Rmail mode adds the attribute @samp{edited} to -the message, if you have made any changes in it. - -@node Rmail Digest -@section Digest Messages -@cindex digest message -@cindex undigestify - - A @dfn{digest message} is a message which exists to contain and carry -several other messages. Digests are used on some moderated mailing -lists; all the messages that arrive for the list during a period of time -such as one day are put inside a single digest which is then sent to the -subscribers. Transmitting the single digest uses much less computer -time than transmitting the individual messages even though the total -size is the same, because the per-message overhead in network mail -transmission is considerable. - -@findex undigestify-rmail-message - When you receive a digest message, the most convenient way to read it is -to @dfn{undigestify} it: to turn it back into many individual messages. -Then you can read and delete the individual messages as it suits you. -To do this, select the digest message and type the command @kbd{M-x -undigestify-rmail-message}. This extracts the submessages as separate -Rmail messages, and inserts them following the digest. The digest -message itself is flagged as deleted. - -@node Rmail Rot13 -@section Reading Rot13 Messages -@cindex rot13 code - - Mailing list messages that might offend some readers are sometimes -encoded in a simple code called @dfn{rot13}---so named because it -rotates the alphabet by 13 letters. This code is not for secrecy, as it -provides none; rather, it enables those who might be offended to avoid -seeing the real text of the message. - -@findex rot13-other-window - To view a buffer which uses the rot13 code, use the command @kbd{M-x -rot13-other-window}. This displays the current buffer in another window -which applies the code when displaying the text. - -@node Movemail -@section @code{movemail} program -@cindex @code{movemail} program - - Rmail uses the @code{movemail} program to move mail from your inbox to -your Rmail file (@pxref{Rmail Inbox}). When loaded for the first time, -Rmail attempts to locate the @code{movemail} program and determine its -version. There are two versions of the @code{movemail} program: the -native one, shipped with GNU Emacs (the ``emacs version'') and the one -included in GNU mailutils (the ``mailutils version,'' -@pxref{movemail,,,mailutils,GNU mailutils}). They support the same -command line syntax and the same basic subset of options. However, the -Mailutils version offers additional features. - - The Emacs version of @code{movemail} is able to retrieve mail from the -usual UNIX mailbox formats and from remote mailboxes using the POP3 -protocol. - - The Mailutils version is able to handle a wide set of mailbox -formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH} -mailboxes, etc. It is able to access remote mailboxes using the POP3 or -IMAP4 protocol, and can retrieve mail from them using a TLS encrypted -channel. It also accepts mailbox arguments in @acronym{URL} form. -The detailed description of mailbox @acronym{URL}s can be found in -@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} is: - -@smallexample -@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} -@end smallexample - -@noindent -where square brackets denote optional elements. - -@table @var -@item proto -Specifies the @dfn{mailbox protocol}, or @dfn{format} to -use. The exact semantics of the rest of @acronym{URL} elements depends -on the actual value of @var{proto} (see below). - -@item user -User name to access the remote mailbox. - -@item password -User password to access the remote mailbox. - -@item host-or-file-name -Hostname of the remote server for remote mailboxes or file name of a -local mailbox. -@end table - -@noindent -@var{Proto} can be one of: - -@table @code -@item mbox -Usual UNIX mailbox format. In this case, neither @var{user} nor -@var{pass} are used, and @var{host-or-file-name} denotes the file name of -the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. - -@item mh -A local mailbox in the @acronym{MH} format. @var{User} and -@var{pass} are not used. @var{Host-or-file-name} denotes the name of -@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. - -@item maildir -A local mailbox in the @acronym{maildir} format. @var{User} and -@var{pass} are not used, and @var{host-or-file-name} denotes the name of -@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. - -@item file -Any local mailbox format. Its actual format is detected automatically -by @code{movemail}. - -@item pop -A remote mailbox to be accessed via POP3 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; e.g., -@code{pop://smith:guessme@@remote.server.net}. - -@item imap -A remote mailbox to be accessed via IMAP4 protocol. @var{User} -specifies the remote user name to use, @var{pass} may be used to -specify the user password, @var{host-or-file-name} is the name or IP -address of the remote mail server to connect to; -e.g., @code{imap://smith:guessme@@remote.server.net}. -@end table - - Alternatively, you can specify the file name of the mailbox to use. -This is equivalent to specifying the @samp{file} protocol: - -@smallexample -/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} -@end smallexample - -@vindex rmail-movemail-program -@vindex rmail-movemail-search-path - The variable @code{rmail-movemail-program} controls which version of -@code{movemail} to use. If that is a string, it specifies the -absolute file name of the @code{movemail} executable. If it is -@code{nil}, Rmail searches for @code{movemail} in the directories -listed in @code{rmail-movemail-search-path} and @code{exec-path}, then -in @code{exec-directory}. - -@node Remote Mailboxes -@section Retrieving Mail from Remote Mailboxes -@pindex movemail - - Some sites use a method called POP for accessing users' inbox data -instead of storing the data in inbox files. By default, the @code{Emacs -movemail} can work with POP (unless the Emacs @code{configure} script -was run with the option @samp{--without-pop}). - -Similarly, the Mailutils @code{movemail} by default supports POP, unless -it was configured with the @samp{--disable-pop} option. - -Both versions of @code{movemail} only work with POP3, not with older -versions of POP. - -@cindex @env{MAILHOST} environment variable -@cindex POP mailboxes - No matter which flavor of @code{movemail} you use, you can specify -a POP inbox by using a POP @dfn{URL} (@pxref{Movemail}). A POP -@acronym{URL} is a ``file name'' of the form -@samp{pop://@var{username}@@@var{hostname}}, where -@var{hostname} is the host name or IP address of the remote mail -server and @var{username} is the user name on that server. -Additionally, you may specify the password in the mailbox @acronym{URL}: -@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this -case, @var{password} takes preference over the one set by -@code{rmail-remote-password} (see below). This is especially useful -if you have several remote mailboxes with different passwords. - - For backward compatibility, Rmail also supports an alternative way of -specifying remote POP mailboxes. Specifying an inbox name in the form -@samp{po:@var{username}:@var{hostname}} is equivalent to -@samp{pop://@var{username}@@@var{hostname}}. If you omit the -@var{:hostname} part, the @env{MAILHOST} environment variable specifies -the machine on which to look for the POP server. - -@c FIXME mention --with-hesiod "support Hesiod to get the POP server host"? - -@cindex IMAP mailboxes - Another method for accessing remote mailboxes is IMAP. This method is -supported only by the Mailutils @code{movemail}. To specify an IMAP -mailbox in the inbox list, use the following mailbox @acronym{URL}: -@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The -@var{password} part is optional, as described above. - -@vindex rmail-remote-password -@vindex rmail-remote-password-required - Accessing a remote mailbox may require a password. Rmail uses the -following algorithm to retrieve it: - -@enumerate -@item -If a @var{password} is present in the mailbox URL (see above), it is -used. -@item -If the variable @code{rmail-remote-password-required} is @code{nil}, -Rmail assumes no password is required. -@item -If the variable @code{rmail-remote-password} is non-@code{nil}, its -value is used. -@item -Otherwise, Rmail will ask you for the password to use. -@end enumerate - -@vindex rmail-movemail-flags - If you need to pass additional command-line flags to @code{movemail}, -set the variable @code{rmail-movemail-flags} a list of the flags you -wish to use. Do not use this variable to pass the @samp{-p} flag to -preserve your inbox contents; use @code{rmail-preserve-inbox} instead. - -@cindex Kerberos POP authentication - The @code{movemail} program installed at your site may support -Kerberos authentication (the Emacs @code{movemail} does so if Emacs was -configured with the option @code{--with-kerberos} or -@code{--with-kerberos5}). If it is supported, it is used by default -whenever you attempt to retrieve POP mail when -@code{rmail-remote-password} and @code{rmail-remote-password-required} -are unset. - -@cindex reverse order in POP inboxes - Some POP servers store messages in reverse order. If your server does -this, and you would rather read your mail in the order in which it was -received, you can tell @code{movemail} to reverse the order of -downloaded messages by adding the @samp{-r} flag to -@code{rmail-movemail-flags}. - -@cindex TLS encryption (Rmail) - Mailutils @code{movemail} supports TLS encryption. If you wish to -use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. - -@node Other Mailbox Formats -@section Retrieving Mail from Local Mailboxes in Various Formats - - If your incoming mail is stored on a local machine in a format other -than UNIX mailbox, you will need the Mailutils @code{movemail} to -retrieve it. @xref{Movemail}, for the detailed description of -@code{movemail} versions. For example, to access mail from a inbox in -@code{maildir} format located in @file{/var/spool/mail/in}, you would -include the following in the Rmail inbox list: - -@smallexample -maildir://var/spool/mail/in -@end smallexample - -@ignore - arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23 -@end ignore diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi deleted file mode 100644 index 234bcea5dbb..00000000000 --- a/doc/emacs/screen.texi +++ /dev/null @@ -1,325 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Screen, User Input, Acknowledgments, Top -@chapter The Organization of the Screen -@cindex screen -@cindex parts of the screen - - On a text-only terminal, the Emacs display occupies the entire -terminal screen. On a graphical display, such as on GNU/Linux using -the X Window System, Emacs creates its own windows to use. We use the -term @dfn{frame} to mean the entire terminal screen or graphical -window used by Emacs. Emacs uses both kinds of frames, in the same -way, to display your editing. Emacs normally starts out with just one -frame, but you can create additional frames if you wish -(@pxref{Frames}). - - The frame consists of several distinct regions. At the top of the -frame is a @dfn{menu bar}, which allows you to access commands via a -series of menus. On a graphical display, directly below the menu bar -is a @dfn{tool bar}, a row of icons that perform editing commands if -you click on them. At the very bottom of the frame is a special -@dfn{echo area}, where short informative messages are displayed and -where you enter information when Emacs asks for it. - - The main area of the frame, below the tool bar (if one exists) and -above the echo area, is called @dfn{the window}. This is where Emacs -displays the @dfn{buffer}: the text that you are editing. On a -graphical display, the window possesses a @dfn{scroll bar} on one -side, which you can use to display different parts of the buffer in -the window. The last line of the window is a @dfn{mode line}. This -displays various information about what is going on in the buffer, -such as whether there are unsaved changes, the editing modes that are -in use, the current line number, and so forth. - - When you start Emacs, there is normally only one window in the -frame. However, you can subdivide this window horizontally or -vertically to create multiple windows, each of which can independently -display a buffer (@pxref{Windows}). In this manual, the word -``window'' refers to the initial large window if not subdivided, or -any one of the multiple windows you have subdivided it into. - - At any time, one window is the @dfn{selected window}. On graphical -displays, the selected window normally shows a more prominent cursor -(usually solid and blinking) while other windows show a weaker cursor -(such as a hollow box). Text terminals have just one cursor, so it -always appears in the selected window. The buffer displayed in the -selected window is called the @dfn{current buffer}, and it is where -editing happens. Most Emacs commands implicitly apply to the current -buffer; the text displayed in unselected windows is mostly visible for -reference. If you use multiple frames on a graphical display, -selecting a particular frame selects a window in that frame. - -@menu -* Point:: The place in the text where editing commands operate. -* Echo Area:: Short messages appear at the bottom of the screen. -* Mode Line:: Interpreting the mode line. -* Menu Bar:: How to use the menu bar. -@end menu - -@node Point -@section Point -@cindex point -@cindex cursor - - The active cursor shows the location at which editing commands will -take effect, which is called @dfn{point}@footnote{The term ``point'' -comes from the character @samp{.}, which was the command in TECO (the -language in which the original Emacs was written) for accessing the -value now called ``point.''}. Many Emacs commands move point to -different places in the buffer; for example, you can place point by -clicking mouse button 1 (normally the left button) at the desired -location. - - While the cursor appears to be @emph{on} a character, you should -think of point as @emph{between} two characters; it points @emph{before} -the character that appears under the cursor. For example, if your text -looks like @samp{frob} with the cursor over the @samp{b}, then point is -between the @samp{o} and the @samp{b}. If you insert the character -@samp{!} at that position, the result is @samp{fro!b}, with point -between the @samp{!} and the @samp{b}. Thus, the cursor remains over -the @samp{b}, as before. - - Sometimes people speak of ``the cursor'' when they mean ``point,'' or -speak of commands that move point as ``cursor motion'' commands. - - If you are editing several files in Emacs, each in its own buffer, -each buffer has its own point location. A buffer that is not -currently displayed remembers its point location in case you display -it again later. When Emacs displays multiple windows, each window has -its own point location. If the same buffer appears in more than one -window, each window has its own point position in that buffer. - - On a graphical display, Emacs shows a cursor in each window; the -selected window's cursor is solid and blinking, and the other cursors -are hollow. On a text-only terminal, there is just one cursor, in the -selected window; even though the unselected windows have their own -point positions, they do not display a cursor. @xref{Cursor Display}, -for customizable variables that control cursor display. - -@node Echo Area -@section The Echo Area -@cindex echo area - - The line at the very bottom of the frame is the @dfn{echo area}. It -is used to display small amounts of text for various purposes. - - @dfn{Echoing} means displaying the characters that you type. -Single-character commands, including most simple editing operations, -are not echoed. Multi-character commands are echoed if you pause -while typing them: if you pause for more than a second in the middle -of a command, Emacs echoes all the characters of the command so far, -to prompt you for the rest of the command. The echoed characters are -displayed in the echo area. Once echoing has started, the rest of the -command echoes immediately as you type it. This behavior is designed -to give confident users fast response, while giving hesitant users -maximum feedback. @xref{Display Custom}. - -@cindex error message in the echo area - If a command cannot do its job, it may display an @dfn{error -message}. Error messages are also displayed in the echo area. They -may be accompanied by beeping or by flashing the screen. - - Some commands display informative messages in the echo area. Unlike -error messages, these messages are not announced with a beep or flash. -Sometimes the message tells you what the command has done, when this -is not obvious from looking at the text being edited. Other times, -the sole purpose of a command is to show you a message giving you -specific information. For example, @kbd{C-x =} (hold down @key{CTRL} -and type @kbd{x}, then let go of @key{CTRL} and type @kbd{=}) displays -a message describing the character position of point in the text and -its current column in the window. Commands that take a long time -often display messages ending in @samp{...} while they are working, -and add @samp{done} at the end when they are finished. They may also -indicate progress with percentages. - -@cindex @samp{*Messages*} buffer -@cindex saved echo area messages -@cindex messages saved from echo area -@vindex message-log-max - Informative echo-area messages are saved in a special buffer named -@samp{*Messages*}. (We have not explained buffers yet; see -@ref{Buffers}, for more information about them.) If you miss a -message that appeared briefly on the screen, you can switch to the -@samp{*Messages*} buffer to see it again. The @samp{*Messages*} -buffer is limited to a certain number of lines, specified by the -variable @code{message-log-max}. (We have not explained variables -either; see @ref{Variables}, for more information about them.) Beyond -this limit, one line is deleted from the beginning whenever a new -message line is added at the end. - -@cindex minibuffer - The echo area is also used to display the @dfn{minibuffer}, a -special window where you can input arguments to commands, such as the -name of a file to be edited. When the minibuffer is in use, the text -displayed in the echo area begins with a @dfn{prompt string} (usually -ending with a colon); also, the active cursor appears within the -minibuffer, which is temporarily considered the selected window. You -can always get out of the minibuffer by typing @kbd{C-g}. -@xref{Minibuffer}. - -@node Mode Line -@section The Mode Line -@cindex mode line -@cindex top level - - At the bottom of each window is a @dfn{mode line}, which describes -what is going on in the current buffer. When there is only one -window, the mode line appears right above the echo area; it is the -next-to-last line in the frame. On a graphical display, the mode line -is drawn with a 3D box appearance, and the mode line of the selected -window has a brighter color than that of unselected windows to make it -stand out. On a text-only terminal, the mode line is usually drawn in -inverse video. - - The text displayed in the mode line has the following format: - -@example --@var{cs}:@var{ch}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor})------ -@end example - -@noindent -The @var{cs} string and the colon character after it describe the -character set and newline convention used for the current buffer. -Normally, Emacs handles these settings intelligently, but it is -sometimes useful to have this information. - - @var{cs} describes the character set of the buffer (@pxref{Coding -Systems}). If it is a dash (@samp{-}), that indicates the default -state of affairs: no special character set handling, except for the -end-of-line translations described in the next paragraph. @samp{=} -means no conversion whatsoever. Letters represent various nontrivial -@dfn{coding systems}---for example, @samp{1} represents ISO Latin-1. -On a text-only terminal, @var{cs} is preceded by two additional -characters that describe the coding system for keyboard input and the -coding system for terminal output. Furthermore, if you are using an -input method, @var{cs} is preceded by a string that identifies the -input method, which takes the form @samp{@var{i}>}, @samp{@var{i}+}, -or @samp{@var{i}@@} (@pxref{Input Methods}). - -@cindex end-of-line conversion, mode-line indication - The character after @var{cs} is usually a colon. However, under -some circumstances a different string is displayed, which indicates a -nontrivial end-of-line convention. Usually, lines of text are -separated by @dfn{newline characters}, but two other conventions are -sometimes used. The MS-DOS convention is to use a ``carriage-return'' -character followed by a ``linefeed'' character; when editing such -files, the colon changes to either a backslash (@samp{\}) or -@samp{(DOS)}, depending on the operating system. The Macintosh -end-of-line convention is to use a ``carriage-return'' character -instead of a newline; when editing such files, the colon indicator -changes to either a forward slash (@samp{/}) or @samp{(Mac)}. On some -systems, Emacs displays @samp{(Unix)} instead of the colon for files -that use newline as the line separator. - - The next element on the mode line is the string indicated by -@var{ch}. This shows two dashes (@samp{--}) if the buffer displayed -in the window has the same contents as the corresponding file on the -disk; i.e., if the buffer is ``unmodified''. If the buffer is -modified, it shows two stars (@samp{**}). For a read-only buffer, it -shows @samp{%*} if the buffer is modified, and @samp{%%} otherwise. - - The character after @var{ch} is normally a dash (@samp{-}). -However, if the default-directory for the current buffer is on a -remote machine, @samp{@@} is displayed instead (@pxref{File Names}). - - @var{fr} gives the selected frame name (@pxref{Frames}). It appears -only on text-only terminals. The initial frame's name is @samp{F1}. - - @var{buf} is the name of the buffer displayed in the window. -Usually, this is the same as the name of a file you are editing. -@xref{Buffers}. - - @var{pos} tells you whether there is additional text above the top of -the window, or below the bottom. If your buffer is small and it is all -visible in the window, @var{pos} is @samp{All}. Otherwise, it is -@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot} -if you are looking at the end of the buffer, or @samp{@var{nn}%}, where -@var{nn} is the percentage of the buffer above the top of the window. -With Size Indication mode, you can display the size of the buffer as -well. @xref{Optional Mode Line}. - - @var{line} is the character @samp{L} followed by the line number at -point. (You can display the current column number too, by turning on -Column Number mode. @xref{Optional Mode Line}.) - - @var{major} is the name of the @dfn{major mode} used in the buffer. -A major mode is a principal editing mode for the buffer, such as Text -mode, Lisp mode, C mode, and so forth. @xref{Major Modes}. - - Some major modes display additional information after the major mode -name. For example, Rmail buffers display the current message number and -the total number of messages. Compilation buffers and Shell buffers -display the status of the subprocess. - - @var{minor} is a list of some of the @dfn{minor modes} turned on in -the buffer. Minor modes are optional editing modes that provide -additional features on top of the major mode. @xref{Minor Modes}. - - Some features are listed together with the minor modes whenever they -are turned on, even through they are not really minor modes. -@samp{Narrow} means that the buffer being displayed has editing -restricted to only a portion of its text (@pxref{Narrowing}). -@samp{Def} means that a keyboard macro is currently being defined -(@pxref{Keyboard Macros}). - - In addition, if Emacs is inside a recursive editing level, square -brackets (@samp{[@dots{}]}) appear around the parentheses that -surround the modes. If Emacs is in one recursive editing level within -another, double square brackets appear, and so on. Since recursive -editing levels affect Emacs globally, not just one buffer, the square -brackets appear in every window's mode line or not in any of them. -@xref{Recursive Edit}.@refill - - You can change the appearance of the mode line as well as the format -of its contents. @xref{Optional Mode Line}. In addition, the mode -line is mouse-sensitive; clicking on different parts of the mode line -performs various commands. @xref{Mode Line Mouse}. - -@node Menu Bar -@section The Menu Bar -@cindex menu bar - - Each Emacs frame normally has a @dfn{menu bar} at the top which you -can use to perform common operations. There's no need to list them -here, as you can more easily see them yourself. - -@kindex M-` -@kindex F10 -@findex tmm-menubar -@findex menu-bar-open - On a graphical display, you can use the mouse to choose a command -from the menu bar. A right-arrow at the end of a menu item means it -leads to a subsidiary menu, or @dfn{submenu}. A @samp{...} at the end -of a menu item means that the command invoked will prompt you for -further input before it actually does anything. - - Some of the commands in the menu bar have ordinary key bindings as -well; if so, a key binding is shown in parentheses after the item -itself. To view the full command name and documentation for a menu -item, type @kbd{C-h k}, and then select the menu bar with the mouse in -the usual way (@pxref{Key Help}). - - Instead of using the mouse, you can also invoke the first menu bar -item by pressing @key{F10} (to run the command @code{menu-bar-open}). -You can then navigate the menus with the arrow keys. To activate a -selected menu item, press @key{RET}; to cancel menu navigation, press -@key{ESC}. - - On text-only terminals with no mouse, you can use the menu bar by -typing @kbd{M-`} or @key{F10} (these run the command -@code{tmm-menubar}). This lets you select a menu item with the -keyboard. A provisional choice appears in the echo area. You can use -the up and down arrow keys to move through the menu to different -items, and then you can type @key{RET} to select the item. - - Each menu item also has an assigned letter or digit which designates -that item; it is usually the initial of some word in the item's name. -This letter or digit is separated from the item name by @samp{=>}. You -can type the item's letter or digit to select the item. - -@ignore - arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f -@end ignore diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi deleted file mode 100644 index 304ca1c6e97..00000000000 --- a/doc/emacs/search.texi +++ /dev/null @@ -1,1371 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Search, Fixit, Display, Top -@chapter Searching and Replacement -@cindex searching -@cindex finding strings within text - - Like other editors, Emacs has commands to search for occurrences of -a string. Emacs also has commands to replace occurrences of a string -with a different string. There are also commands that do the same -thing, but search for patterns instead of fixed strings. - - You can also search multiple files under the control of a tags table -(@pxref{Tags Search}) or through the Dired @kbd{A} command -(@pxref{Operating on Files}), or ask the @code{grep} program to do it -(@pxref{Grep Searching}). - - -@menu -* Incremental Search:: Search happens as you type the string. -* Nonincremental Search:: Specify entire string and then search. -* Word Search:: Search for sequence of words. -* Regexp Search:: Search for match for a regexp. -* Regexps:: Syntax of regular expressions. -* Regexp Backslash:: Regular expression constructs starting with `\'. -* Regexp Example:: A complex regular expression explained. -* Search Case:: To ignore case while searching, or not. -* Replace:: Search, and replace some or all matches. -* Other Repeating Search:: Operating on all matches for some regexp. -@end menu - -@node Incremental Search -@section Incremental Search -@cindex incremental search -@cindex isearch - - The principal search command in Emacs is @dfn{incremental}: it -begins searching as soon as you type the first character of the search -string. As you type in the search string, Emacs shows you where the -string (as you have typed it so far) would be found. When you have -typed enough characters to identify the place you want, you can stop. -Depending on what you plan to do next, you may or may not need to -terminate the search explicitly with @key{RET}. - -@table @kbd -@item C-s -Incremental search forward (@code{isearch-forward}). -@item C-r -Incremental search backward (@code{isearch-backward}). -@end table - -@menu -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Isearch Scroll:: Scrolling during an incremental search. -* Isearch Minibuffer:: Incremental search of the minibuffer history. -* Slow Isearch:: Incremental search features for slow terminals. -@end menu - -@node Basic Isearch -@subsection Basics of Incremental Search - -@table @kbd -@item C-s -Begin incremental search (@code{isearch-forward}). -@item C-r -Begin reverse incremental search (@code{isearch-backward}). -@end table - -@kindex C-s -@findex isearch-forward - @kbd{C-s} (@code{isearch-forward}) starts a forward incremental -search. It reads characters from the keyboard, and moves point just -past the end of the next occurrence of those characters in the buffer. - - For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the -cursor after the first @samp{F} that occurs in the buffer after the -starting point. Then if you then type @kbd{O}, the cursor moves to -just after the first @samp{FO}; the @samp{F} in that @samp{FO} might -not be the first @samp{F} previously found. After another @kbd{O}, -the cursor moves to just after the first @samp{FOO}. - -@cindex faces for highlighting search matches - At each step, Emacs highlights the @dfn{current match}---the buffer -text that matches the search string---using the @code{isearch} face -(@pxref{Faces}). The current search string is also displayed in the -echo area. - - If you make a mistake typing the search string, type @key{DEL}. -Each @key{DEL} cancels the last character of the search string. - - When you are satisfied with the place you have reached, type -@key{RET}. This stops searching, leaving the cursor where the search -brought it. Also, any command not specially meaningful in searches -stops the searching and is then executed. Thus, typing @kbd{C-a} -exits the search and then moves to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others -described below). - - As a special exception, entering @key{RET} when the search string is -empty launches nonincremental search (@pxref{Nonincremental Search}). - - When you exit the incremental search, it adds the original value of -point to the mark ring, without activating the mark; you can thus use -@kbd{C-u C-@key{SPC}} to return to where you were before beginning the -search. @xref{Mark Ring}. It only does this if the mark was not -already active. - -@kindex C-r -@findex isearch-backward - To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead -of @kbd{C-s} to start the search. A backward search finds matches -that end before the starting point, just as a forward search finds -matches that begin after it. - -@node Repeat Isearch -@subsection Repeating Incremental Search - - Suppose you search forward for @samp{FOO} and find a match, but not -the one you expected to find: the @samp{FOO} you were aiming for -occurs later in the buffer. In this event, type another @kbd{C-s} to -move to the next occurrence of the search string. You can repeat this -any number of times. If you overshoot, you can cancel some @kbd{C-s} -characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward -incremental search repeats the backward search. - -@cindex lazy search highlighting -@vindex isearch-lazy-highlight - If you pause for a little while during incremental search, Emacs -highlights all the other possible matches for the search string that -are present on the screen. This helps you anticipate where you can -get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The -other matches are highlighted differently from the current match, -using the customizable face @code{lazy-highlight} (@pxref{Faces}). If -you don't like this feature, you can disable it by setting -@code{isearch-lazy-highlight} to @code{nil}. - - After exiting a search, you can search for the same string again by -typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that -invokes incremental search, and the second @kbd{C-s} means ``search -again.'' Similarly, @kbd{C-r C-r} searches backward for the last -search string. In determining the last search string, it doesn't -matter whether the string was searched for with @kbd{C-s} or -@kbd{C-r}. - - If you are searching forward but you realize you were looking for -something before the starting point, type @kbd{C-r} to switch to a -backward search, leaving the search string unchanged. Similarly, -@kbd{C-s} in a backward search switches to a forward search. - - If a search is failing and you ask to repeat it by typing another -@kbd{C-s}, it starts again from the beginning of the buffer. -Repeating a failing reverse search with @kbd{C-r} starts again from -the end. This is called @dfn{wrapping around}, and @samp{Wrapped} -appears in the search prompt once this has happened. If you keep on -going past the original starting point of the search, it changes to -@samp{Overwrapped}, which means that you are revisiting matches that -you have already seen. - -@cindex search ring - To reuse earlier search strings, use the @dfn{search ring}. The -commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a -search string to reuse. These commands leave the selected search ring -element in the minibuffer, where you can edit it. To edit the current -search string in the minibuffer without replacing it with items from -the search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} to -terminate editing the string and search for it. - -@node Error in Isearch -@subsection Errors in Incremental Search - - If your string is not found at all, the echo area says @samp{Failing -I-Search}. The cursor is after the place where Emacs found as much of -your string as it could. Thus, if you search for @samp{FOOT}, and -there is no @samp{FOOT}, you might see the cursor after the @samp{FOO} -in @samp{FOOL}. In the echo area, the part of the search string that -failed to match is highlighted using the customizable face -@code{isearch-fail}. - - At this point, there are several things you can do. If your string -was mistyped, you can use @key{DEL} to erase some of it and correct -it. If you like the place you have found, you can type @key{RET} to -remain there. Or you can type @kbd{C-g}, which removes from the -search string the characters that could not be found (the @samp{T} in -@samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. - -@cindex quitting (in search) - The quit command, @kbd{C-g}, does special things during searches; -just what it does depends on the status of the search. If the search -has found what you specified and is waiting for input, @kbd{C-g} -cancels the entire search, moving the cursor back to where you started -the search. If @kbd{C-g} is typed when there are characters in the -search string that have not been found---because Emacs is still -searching for them, or because it has failed to find them---then the -search string characters which have not been found are discarded from -the search string. With them gone, the search is now successful and -waiting for more input, so a second @kbd{C-g} will cancel the entire -search. - -@node Special Isearch -@subsection Special Input for Incremental Search - - Some of the characters you type during incremental search have -special effects. - - If the search string you entered contains only lower-case letters, -the search is case-insensitive; as long as an upper-case letter exists -in the search string, the search becomes case-sensitive. If you -delete the upper-case character from the search string, it ceases to -have this effect. @xref{Search Case}. - - To search for a newline character, type @kbd{C-j}. - - To search for other control characters, such as @key{control-S}, -quote it by typing @kbd{C-q} first (@pxref{Inserting Text}). To -search for non-@acronym{ASCII} characters, you can either use -@kbd{C-q} and enter its octal code, or use an input method -(@pxref{Input Methods}). If an input method is enabled in the current -buffer when you start the search, you can use it in the search string -also. While typing the search string, you can toggle the input method -with the command @kbd{C-\} (@code{isearch-toggle-input-method}). You -can also turn on a non-default input method with @kbd{C-^} -(@code{isearch-toggle-specified-input-method}), which prompts for the -name of the input method. When an input method is active during -incremental search, the search prompt includes the input method -mnemonic, like this: - -@example -I-search [@var{im}]: -@end example - -@noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method -where @var{im} is the mnemonic of the active input method. Any input -method you enable during incremental search remains enabled in the -current buffer afterwards. - -@kindex M-% @r{(Incremental search)} - Typing @kbd{M-%} in incremental search invokes @code{query-replace} -or @code{query-replace-regexp} (depending on search mode) with the -current search string used as the string to replace. @xref{Query -Replace}. - -@kindex M-TAB @r{(Incremental search)} - Typing @kbd{M-@key{TAB}} in incremental search invokes -@code{isearch-complete}, which attempts to complete the search string -using the search ring as a list of completion alternatives. -@xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} -key sequence is captured by the window manager; you then need to -rebind @code{isearch-complete} to another key sequence if you want to -use it (@pxref{Rebinding}). - -@vindex isearch-mode-map - When incremental search is active, you can type @kbd{C-h C-h} to -access interactive help options, including a list of special -keybindings. These keybindings are part of the keymap -@code{isearch-mode-map} (@pxref{Keymaps}). - -@node Isearch Yank -@subsection Isearch Yanking - - Within incremental search, you can use @kbd{C-w} and @kbd{C-y} to grab -text from the buffer into the search string. This makes it convenient -to search for another occurrence of text at point. - - @kbd{C-w} copies the character or word after point and adds it to -the search string, advancing point over it. (The decision, whether to -copy a character or a word, is heuristic.) - - @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the -current line into the search string. If point is already at the end -of a line, it grabs the entire next line. If the search is currently -case-insensitive, both @kbd{C-y} and @kbd{C-w} convert the text they -copy to lower case, so that the search remains case-insensitive. - - @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one -character at a time: @kbd{C-M-w} deletes the last character from the -search string and @kbd{C-M-y} copies the character after point to the -end of the search string. An alternative method to add the character -after point into the search string is to enter the minibuffer by -@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the -minibuffer. - - The character @kbd{M-y} copies text from the kill ring into the -search string. It uses the same text that @kbd{C-y} would yank. -@kbd{Mouse-2} in the echo area does the same. @xref{Yanking}. - -@node Isearch Scroll -@subsection Scrolling During Incremental Search - -@vindex isearch-allow-scroll - You can enable the use of vertical scrolling during incremental -search (without exiting the search) by setting the customizable -variable @code{isearch-allow-scroll} to a non-@code{nil} value. This -applies to using the vertical scroll-bar and to certain keyboard -commands such as @key{prior} (@code{scroll-down}), @key{next} -(@code{scroll-up}) and @kbd{C-l} (@code{recenter}). You must run -these commands via their key sequences to stay in the search---typing -@kbd{M-x} will terminate the search. You can give prefix arguments to -these commands in the usual way. - - This feature won't let you scroll the current match out of visibility, -however. - - The feature also affects some other commands, such as @kbd{C-x 2} -(@code{split-window-vertically}) and @kbd{C-x ^} -(@code{enlarge-window}) which don't exactly scroll but do affect where -the text appears on the screen. In general, it applies to any command -whose name has a non-@code{nil} @code{isearch-scroll} property. So you -can control which commands are affected by changing these properties. - - For example, to make @kbd{C-h l} usable within an incremental search -in all future Emacs sessions, use @kbd{C-h c} to find what command it -runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) -Then you can put the following line in your @file{.emacs} file -(@pxref{Init File}): - -@example -(put 'view-lossage 'isearch-scroll t) -@end example - -@noindent -This feature can be applied to any command that doesn't permanently -change point, the buffer contents, the match data, the current buffer, -or the selected window and frame. The command must not itself attempt -an incremental search. - -@node Isearch Minibuffer -@subsection Searching the Minibuffer -@cindex minibuffer history, searching - -If you start an incremental search while the minibuffer is active, -Emacs searches the contents of the minibuffer. Unlike searching an -ordinary buffer, the search string is not shown in the echo area, -because that is used to display the minibuffer. - -If an incremental search fails in the minibuffer, it tries searching -the minibuffer history. @xref{Minibuffer History}. You can visualize -the minibuffer and its history as a series of ``pages'', with the -earliest history element on the first page and the current minibuffer -on the last page. A forward search, @kbd{C-s}, searches forward to -later pages; a reverse search, @kbd{C-r}, searches backwards to -earlier pages. Like in ordinary buffer search, a failing search can -wrap around, going from the last page to the first page or vice versa. - -When the current match is on a history element, that history element -is pulled into the minibuffer. If you exit the incremental search -normally (e.g. by typing @key{RET}), it remains in the minibuffer -afterwards. Cancelling the search, with @kbd{C-g}, restores the -contents of the minibuffer when you began the search. - -@node Slow Isearch -@subsection Slow Terminal Incremental Search - - Incremental search on a slow terminal uses a modified style of display -that is designed to take less time. Instead of redisplaying the buffer at -each place the search gets to, it creates a new single-line window and uses -that to display the line that the search has found. The single-line window -comes into play as soon as point moves outside of the text that is already -on the screen. - - When you terminate the search, the single-line window is removed. -Emacs then redisplays the window in which the search was done, to show -its new position of point. - -@vindex search-slow-speed - The slow terminal style of display is used when the terminal baud rate is -less than or equal to the value of the variable @code{search-slow-speed}, -initially 1200. See also the discussion of the variable @code{baud-rate} -(@pxref{baud-rate,, Customization of Display}). - -@vindex search-slow-window-lines - The number of lines to use in slow terminal search display is controlled -by the variable @code{search-slow-window-lines}. Its normal value is 1. - -@node Nonincremental Search -@section Nonincremental Search -@cindex nonincremental search - - Emacs also has conventional nonincremental search commands, which require -you to type the entire search string before searching begins. - -@table @kbd -@item C-s @key{RET} @var{string} @key{RET} -Search for @var{string}. -@item C-r @key{RET} @var{string} @key{RET} -Search backward for @var{string}. -@end table - - To start a nonincremental search, first type @kbd{C-s @key{RET}}. -This enters the minibuffer to read the search string; terminate the -string with @key{RET}, and then the search takes place. If the string -is not found, the search command signals an error. - - When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental -search as usual. That command is specially programmed to invoke -nonincremental search, @code{search-forward}, if the string you -specify is empty. (Such an empty argument would otherwise be -useless.) @kbd{C-r @key{RET}} does likewise, for a reverse -incremental search. - -@findex search-forward -@findex search-backward - Forward and backward nonincremental searches are implemented by the -commands @code{search-forward} and @code{search-backward}. These -commands may be bound to other keys in the usual manner. - -@node Word Search -@section Word Search -@cindex word search - - A @dfn{word search} finds a sequence of words without regard to the -type of punctuation between them. For instance, if you enter a search -string that consists of two words separated by a single space, the -search matches any sequence of those two words separated by one or -more spaces, newlines, or other punctuation characters. This is -particularly useful for searching text documents, because you don't -have to worry whether the words you are looking for are separated by -newlines or spaces. - -@table @kbd -@item M-s w -If incremental search is active, toggle word search mode -(@code{isearch-toggle-word}); otherwise, begin an incremental forward -word search (@code{isearch-forward-word}). -@item M-s w @key{RET} @var{words} @key{RET} -Search for @var{words}, using a forward nonincremental word search. -@item M-s w C-r @key{RET} @var{words} @key{RET} -Search backward for @var{words}, using a nonincremental word search. -@end table - -@kindex M-s w -@findex isearch-forward-word - To begin a forward incremental word search, type @kbd{M-s w}. If -incremental search is not already active, this runs the command -@code{isearch-forward-word}. If incremental search is already active -(whether a forward or backward search), @kbd{M-s w} switches to a word -search while keeping the direction of the search and the current -search string unchanged. You can toggle word search back off by -typing @kbd{M-s w} again. - -@findex word-search-forward -@findex word-search-backward - To begin a nonincremental word search, type @kbd{M-s w @key{RET}} -for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search. -These run the commands @code{word-search-forward} and -@code{word-search-backward} respectively. - - A nonincremental word search differs slightly from the incremental -version in the way it finds a match: the last word in the search -string must be an exact match for a whole word. In an incremental -word search, the last word in the search string can match part of a -word; this allows the matching to proceed incrementally as you type. - -@node Regexp Search -@section Regular Expression Search -@cindex regular expression -@cindex regexp - - A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern -that denotes a class of alternative strings to match. GNU Emacs -provides both incremental and nonincremental ways to search for a -match for a regexp. The syntax of regular expressions is explained in -the following section. - -@table @kbd -@item C-M-s -Begin incremental regexp search (@code{isearch-forward-regexp}). -@item C-M-r -Begin reverse incremental regexp search (@code{isearch-backward-regexp}). -@end table - -@kindex C-M-s -@findex isearch-forward-regexp -@kindex C-M-r -@findex isearch-backward-regexp - Incremental search for a regexp is done by typing @kbd{C-M-s} -(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a -prefix argument (whose value does not matter), or by typing @kbd{M-r} -within a forward incremental search. This command reads a -search string incrementally just like @kbd{C-s}, but it treats the -search string as a regexp rather than looking for an exact match -against the text in the buffer. Each time you add text to the search -string, you make the regexp longer, and the new regexp is searched -for. To search backward for a regexp, use @kbd{C-M-r} -(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, -or @kbd{M-r} within a backward incremental search. - - All of the special key sequences in an ordinary incremental search -do similar things in an incremental regexp search. For instance, -typing @kbd{C-s} immediately after starting the search retrieves the -last incremental search regexp used and searches forward for it. -Incremental regexp and non-regexp searches have independent defaults. -They also have separate search rings, which you can access with -@kbd{M-p} and @kbd{M-n}. - -@vindex search-whitespace-regexp - If you type @key{SPC} in incremental regexp search, it matches any -sequence of whitespace characters, including newlines. If you want to -match just a space, type @kbd{C-q @key{SPC}}. You can control what a -bare space matches by setting the variable -@code{search-whitespace-regexp} to the desired regexp. - - In some cases, adding characters to the regexp in an incremental -regexp search can make the cursor move back and start again. For -example, if you have searched for @samp{foo} and you add @samp{\|bar}, -the cursor backs up in case the first @samp{bar} precedes the first -@samp{foo}. @xref{Regexps}. - - Forward and backward regexp search are not symmetrical, because -regexp matching in Emacs always operates forward, starting with the -beginning of the regexp. Thus, forward regexp search scans forward, -trying a forward match at each possible starting position. Backward -regexp search scans backward, trying a forward match at each possible -starting position. These search methods are not mirror images. - -@findex re-search-forward -@findex re-search-backward - Nonincremental search for a regexp is done by the functions -@code{re-search-forward} and @code{re-search-backward}. You can -invoke these with @kbd{M-x}, or by way of incremental regexp search -with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. - - If you use the incremental regexp search commands with a prefix -argument, they perform ordinary string search, like -@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental -Search}. - -@node Regexps -@section Syntax of Regular Expressions -@cindex syntax of regexps - - This manual describes regular expression features that users -typically want to use. There are additional features that are -mainly used in Lisp programs; see @ref{Regular Expressions,,, -elisp, The Emacs Lisp Reference Manual}. - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression which matches that same -character and nothing else. The special characters are @samp{$}, -@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, and -@samp{\}. The character @samp{]} is special if it ends a character -alternative (see later). The character @samp{-} is special inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. (When you use -regular expressions in a Lisp program, each @samp{\} must be doubled, -see the example near the end of this section.) - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}. (When case distinctions are being ignored, these regexps -also match @samp{F} and @samp{O}, but we consider this a generalization -of ``the same string,'' rather than an exception.) - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression which matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something nontrivial, you -need to use one of the special characters. Here is a list of them. - -@table @asis -@item @kbd{.}@: @r{(Period)} -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item @kbd{*} -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill - -@item @kbd{+} -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @kbd{?} -is a postfix operator, similar to @samp{*} except that it can match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @kbd{*?}, @kbd{+?}, @kbd{??} -@cindex non-greedy regexp matching -are non-greedy variants of the operators above. The normal operators -@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as -much as they can, as long as the overall regexp can still match. With -a following @samp{?}, they are non-greedy: they will match as little -as possible. - -Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} -and the string @samp{abbbb}; but if you try to match them both against -the text @samp{abbb}, @samp{ab*} will match it all (the longest valid -match), while @samp{ab*?} will match just @samp{a} (the shortest -valid match). - -Non-greedy operators match the shortest possible string starting at a -given starting point; in a forward search, though, the earliest -possible starting point for match is always the one chosen. Thus, if -you search for @samp{a.*?$} against the text @samp{abbab} followed by -a newline, it matches the whole string. Since it @emph{can} match -starting at the first @samp{a}, it does. - -@item @kbd{\@{@var{n}\@}} -is a postfix operator that specifies repetition @var{n} times---that -is, the preceding regular expression must match exactly @var{n} times -in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} -and nothing else. - -@item @kbd{\@{@var{n},@var{m}\@}} -is a postfix operator that specifies repetition between @var{n} and -@var{m} times---that is, the preceding regular expression must match -at least @var{n} times, but no more than @var{m} times. If @var{m} is -omitted, then there is no upper limit, but the preceding regular -expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is -equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to -@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. - -@item @kbd{[ @dots{} ]} -is a @dfn{character set}, which begins with @samp{[} and is terminated -by @samp{]}. In the simplest case, the characters between the two -brackets are what this set can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string), from which it follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character set, by writing the -starting and ending characters with a @samp{-} between them. Thus, -@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be -intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or -period. - -Note that the usual regexp special characters are not special inside a -character set. A completely different set of special characters exists -inside character sets: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character set, you must make it the first -character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. (At the beginning, it complements the set---see below.) - -When you use a range in case-insensitive search, you should write both -ends of the range in upper case, or both in lower case, or both should -be non-letters. The behavior of a mixed-case range such as @samp{A-z} -is somewhat ill-defined, and it may change in future Emacs versions. - -@item @kbd{[^ @dots{} ]} -@samp{[^} begins a @dfn{complemented character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches -all characters @emph{except} @acronym{ASCII} letters and digits. - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character set can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @kbd{^} -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -For historical compatibility reasons, @samp{^} can be used with this -meaning only at the beginning of the regular expression, or after -@samp{\(} or @samp{\|}. - -@item @kbd{$} -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -For historical compatibility reasons, @samp{$} can be used with this -meaning only at the end of the regular expression, or before @samp{\)} -or @samp{\|}. - -@item @kbd{\} -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -See the following section for the special constructs that begin -with @samp{\}. -@end table - - Note: for historical compatibility, special characters are treated as -ordinary ones if they are in contexts where their special meanings make no -sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is -no preceding expression on which the @samp{*} can act. It is poor practice -to depend on this behavior; it is better to quote the special character anyway, -regardless of where it appears. - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -@node Regexp Backslash -@section Backslash in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: two-character -sequences starting with @samp{\} that have special meanings. The -second character in the sequence is always an ordinary character when -used on its own. Here is a table of @samp{\} constructs. - -@table @kbd -@item \| -specifies an alternative. Two regular expressions @var{a} and @var{b} -with @samp{\|} in between form an expression that matches some text if -either @var{a} matches it or @var{b} matches it. It works by trying to -match @var{a}, and if that fails, by trying to match @var{b}. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. -Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings.@refill - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that is assigned as a -second meaning to the same @samp{\( @dots{} \)} construct. In practice -there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. - -@item \(?: @dots{} \) -@cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -you can't refer back to it with @samp{\@var{d}}. This is useful -in mechanically combining regular expressions, so that you -can add groups for syntactic purposes without interfering with -the numbering of the groups that are meant to be referred to. - -@item \@var{d} -@cindex back reference, in regexp -matches the same text that matched the @var{d}th occurrence of a -@samp{\( @dots{} \)} construct. This is called a @dfn{back -reference}. - -After the end of a @samp{\( @dots{} \)} construct, the matcher remembers -the beginning and end of the text matched by that construct. Then, -later on in the regular expression, you can use @samp{\} followed by the -digit @var{d} to mean ``match the same text matched the @var{d}th time -by the @samp{\( @dots{} \)} construct.'' - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open-parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a particular @samp{\( @dots{} \)} construct matches more than once -(which can easily happen if it is followed by @samp{*}), only the last -match is recorded. - -@item \` -matches the empty string, but only at the beginning of the string or -buffer (or its accessible portion) being matched against. - -@item \' -matches the empty string, but only at the end of the string or buffer -(or its accessible portion) being matched against. - -@item \= -matches the empty string, but only at point. - -@item \b -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer -regardless of what text appears next to it. - -@item \B -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer only if a -word-constituent character follows. - -@item \> -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer only if the contents end with a -word-constituent character. - -@item \w -matches any word-constituent character. The syntax table -determines which characters these are. @xref{Syntax}. - -@item \W -matches any character that is not a word-constituent. - -@item \_< -matches the empty string, but only at the beginning of a symbol. -A symbol is a sequence of one or more symbol-constituent characters. -A symbol-constituent character is a character whose syntax is either -@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the -buffer only if a symbol-constituent character follows. - -@item \_> -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer only if the contents end with a -symbol-constituent character. - -@item \s@var{c} -matches any character whose syntax is @var{c}. Here @var{c} is a -character that designates a particular syntax class: thus, @samp{w} -for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} -for ordinary punctuation, etc. @xref{Syntax}. - -@item \S@var{c} -matches any character whose syntax is not @var{c}. - -@cindex categories of characters -@cindex characters which belong to a specific language -@findex describe-categories -@item \c@var{c} -matches any character that belongs to the category @var{c}. For -example, @samp{\cc} matches Chinese characters, @samp{\cg} matches -Greek characters, etc. For the description of the known categories, -type @kbd{M-x describe-categories @key{RET}}. - -@item \C@var{c} -matches any character that does @emph{not} belong to category -@var{c}. -@end table - - The constructs that pertain to words and syntax are controlled by the -setting of the syntax table (@pxref{Syntax}). - -@node Regexp Example -@section Regular Expression Example - - Here is an example of a regexp---the regexp that Emacs uses, by -default, to recognize the end of a sentence, not including the -following space (i.e., the variable @code{sentence-end-base}): - -@example -@verbatim -[.?!][]\"'””)}]* -@end verbatim -@end example - -@noindent -This contains two parts in succession: a character set matching -period, @samp{?}, or @samp{!}, and a character set matching -close-brackets, quotes, or parentheses, repeated zero or more times. - -@node Search Case -@section Searching and Case - - Searches in Emacs normally ignore the case of the text they are -searching through, if you specify the text in lower case. Thus, if -you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} -are also considered a match. Regexps, and in particular character -sets, are included: @samp{[ab]} would match @samp{a} or @samp{A} or -@samp{b} or @samp{B}.@refill - - An upper-case letter anywhere in the incremental search string makes -the search case-sensitive. Thus, searching for @samp{Foo} does not find -@samp{foo} or @samp{FOO}. This applies to regular expression search as -well as to string search. The effect ceases if you delete the -upper-case letter from the search string. - - Typing @kbd{M-c} within an incremental search toggles the case -sensitivity of that search. The effect does not extend beyond the -current incremental search to the next one, but it does override the -effect of adding or removing an upper-case letter in the current -search. - -@vindex case-fold-search -@vindex default-case-fold-search - If you set the variable @code{case-fold-search} to @code{nil}, then -all letters must match exactly, including case. This is a per-buffer -variable; altering the variable affects only the current buffer, but -there is a default value in @code{default-case-fold-search} that you -can also set. @xref{Locals}. This variable applies to nonincremental -searches also, including those performed by the replace commands -(@pxref{Replace}) and the minibuffer history matching commands -(@pxref{Minibuffer History}). - - Several related variables control case-sensitivity of searching and -matching for specific commands or activities. For instance, -@code{tags-case-fold-search} controls case sensitivity for -@code{find-tag}. To find these variables, do @kbd{M-x -apropos-variable @key{RET} case-fold-search @key{RET}}. - -@node Replace -@section Replacement Commands -@cindex replacement -@cindex search-and-replace commands -@cindex string substitution -@cindex global substitution - - Emacs provides several commands for performing search-and-replace -operations. In addition to the simple @kbd{M-x replace-string} -command, there is @kbd{M-%} (@code{query-replace}), which presents -each occurrence of the pattern and asks you whether to replace it. - - The replace commands normally operate on the text from point to the -end of the buffer. When the mark is active, they operate on the -region instead (@pxref{Mark}). The basic replace commands replace one -@dfn{search string} (or regexp) with one @dfn{replacement string}. It -is possible to perform several replacements in parallel, using the -command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). - -@menu -* Unconditional Replace:: Replacing all matches for a string. -* Regexp Replace:: Replacing all matches for a regexp. -* Replacement and Case:: How replacements preserve case of letters. -* Query Replace:: How to use querying. -@end menu - -@node Unconditional Replace, Regexp Replace, Replace, Replace -@subsection Unconditional Replacement -@findex replace-string - -@table @kbd -@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace every occurrence of @var{string} with @var{newstring}. -@end table - - To replace every instance of @samp{foo} after point with @samp{bar}, -use the command @kbd{M-x replace-string} with the two arguments -@samp{foo} and @samp{bar}. Replacement happens only in the text after -point, so if you want to cover the whole buffer you must go to the -beginning first. All occurrences up to the end of the buffer are -replaced; to limit replacement to part of the buffer, activate the -region around that part. When the region is active, replacement is -limited to the region (@pxref{Mark}). - - When @code{replace-string} exits, it leaves point at the last -occurrence replaced. It adds the prior position of point (where the -@code{replace-string} command was issued) to the mark ring, without -activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. -@xref{Mark Ring}. - - A prefix argument restricts replacement to matches that are -surrounded by word boundaries. The argument's value doesn't matter. - - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. - -@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace -@subsection Regexp Replacement -@findex replace-regexp - - The @kbd{M-x replace-string} command replaces exact matches for a -single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. - -@table @kbd -@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace every match for @var{regexp} with @var{newstring}. -@end table - -@cindex back reference, in regexp replacement - In @code{replace-regexp}, the @var{newstring} need not be constant: -it can refer to all or part of what is matched by the @var{regexp}. -@samp{\&} in @var{newstring} stands for the entire match being -replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a -digit, stands for whatever matched the @var{d}th parenthesized -grouping in @var{regexp}. (This is called a ``back reference.'') -@samp{\#} refers to the count of replacements already made in this -command, as a decimal number. In the first replacement, @samp{\#} -stands for @samp{0}; in the second, for @samp{1}; and so on. For -example, - -@example -M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} -@end example - -@noindent -replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} -with @samp{cddr-safe}. - -@example -M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} -@end example - -@noindent -performs the inverse transformation. To include a @samp{\} in the -text to replace with, you must enter @samp{\\}. - - If you want to enter part of the replacement string by hand each -time, use @samp{\?} in the replacement string. Each replacement will -ask you to edit the replacement string in the minibuffer, putting -point where the @samp{\?} was. - - The remainder of this subsection is intended for specialized tasks -and requires knowledge of Lisp. Most readers can skip it. - - You can use Lisp expressions to calculate parts of the -replacement string. To do this, write @samp{\,} followed by the -expression in the replacement string. Each replacement calculates the -value of the expression and converts it to text without quoting (if -it's a string, this means using the string's contents), and uses it in -the replacement string in place of the expression itself. If the -expression is a symbol, one space in the replacement string after the -symbol name goes with the symbol name, so the value replaces them -both. - - Inside such an expression, you can use some special sequences. -@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire -match as a string, and to a submatch as a string. @var{n} may be -multiple digits, and the value of @samp{\@var{n}} is @code{nil} if -subexpression @var{n} did not match. You can also use @samp{\#&} and -@samp{\#@var{n}} to refer to those matches as numbers (this is valid -when the match or submatch has the form of a numeral). @samp{\#} here -too stands for the number of already-completed replacements. - - Repeating our example to exchange @samp{x} and @samp{y}, we can thus -do it also this way: - -@example -M-x replace-regexp @key{RET} \(x\)\|y @key{RET} -\,(if \1 "y" "x") @key{RET} -@end example - - For computing replacement strings for @samp{\,}, the @code{format} -function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs -Lisp Reference Manual}). For example, to add consecutively numbered -strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are -already occupied), you can use - -@example -M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} -\,(format "%-72sABC%05d" \& \#) @key{RET} -@end example - -@node Replacement and Case, Query Replace, Regexp Replace, Replace -@subsection Replace Commands and Case - - If the first argument of a replace command is all lower case, the -command ignores case while searching for occurrences to -replace---provided @code{case-fold-search} is non-@code{nil}. If -@code{case-fold-search} is set to @code{nil}, case is always significant -in all searches. - -@vindex case-replace - In addition, when the @var{newstring} argument is all or partly lower -case, replacement commands try to preserve the case pattern of each -occurrence. Thus, the command - -@example -M-x replace-string @key{RET} foo @key{RET} bar @key{RET} -@end example - -@noindent -replaces a lower case @samp{foo} with a lower case @samp{bar}, an -all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with -@samp{Bar}. (These three alternatives---lower case, all caps, and -capitalized, are the only ones that @code{replace-string} can -distinguish.) - - If upper-case letters are used in the replacement string, they remain -upper case every time that text is inserted. If upper-case letters are -used in the first argument, the second argument is always substituted -exactly as given, with no case conversion. Likewise, if either -@code{case-replace} or @code{case-fold-search} is set to @code{nil}, -replacement is done without case conversion. - -@node Query Replace,, Replacement and Case, Replace -@subsection Query Replace -@cindex query replace - -@table @kbd -@item M-% @var{string} @key{RET} @var{newstring} @key{RET} -@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace some occurrences of @var{string} with @var{newstring}. -@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} -@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -Replace some matches for @var{regexp} with @var{newstring}. -@end table - -@kindex M-% -@findex query-replace - If you want to change only some of the occurrences of @samp{foo} to -@samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}). -This command finds occurrences of @samp{foo} one by one, displays each -occurrence and asks you whether to replace it. Aside from querying, -@code{query-replace} works just like @code{replace-string} -(@pxref{Unconditional Replace}). In particular, it preserves case -provided @code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means consider -only occurrences that are bounded by word-delimiter characters. - -@kindex C-M-% -@findex query-replace-regexp - @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). -It works like @code{replace-regexp} except that it queries -like @code{query-replace}. - -@cindex faces for highlighting query replace - These commands highlight the current match using the face -@code{query-replace}. They highlight other matches using -@code{lazy-highlight} just like incremental search (@pxref{Incremental -Search}). By default, @code{query-replace-regexp} will show -substituted replacement string for the current match in the -minibuffer. If you want to keep special sequences @samp{\&} and -@samp{\@var{n}} unexpanded, customize -@code{query-replace-show-replacement} variable. - - The characters you can type when you are shown a match for the string -or regexp are: - -@ignore @c Not worth it. -@kindex SPC @r{(query-replace)} -@kindex DEL @r{(query-replace)} -@kindex , @r{(query-replace)} -@kindex RET @r{(query-replace)} -@kindex . @r{(query-replace)} -@kindex ! @r{(query-replace)} -@kindex ^ @r{(query-replace)} -@kindex C-r @r{(query-replace)} -@kindex C-w @r{(query-replace)} -@kindex C-l @r{(query-replace)} -@end ignore - -@c WideCommands -@table @kbd -@item @key{SPC} -to replace the occurrence with @var{newstring}. - -@item @key{DEL} -to skip to the next occurrence without replacing this one. - -@item , @r{(Comma)} -to replace this occurrence and display the result. You are then asked -for another input character to say what to do next. Since the -replacement has already been made, @key{DEL} and @key{SPC} are -equivalent in this situation; both move to the next occurrence. - -You can type @kbd{C-r} at this point (see below) to alter the replaced -text. You can also type @kbd{C-x u} to undo the replacement; this exits -the @code{query-replace}, so if you want to do further replacement you -must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart -(@pxref{Repetition}). - -@item @key{RET} -to exit without doing any more replacements. - -@item .@: @r{(Period)} -to replace this occurrence and then exit without searching for more -occurrences. - -@item ! -to replace all remaining occurrences without asking again. - -@item ^ -to go back to the position of the previous occurrence (or what used to -be an occurrence), in case you changed it by mistake or want to -reexamine it. - -@item C-r -to enter a recursive editing level, in case the occurrence needs to be -edited rather than just replaced with @var{newstring}. When you are -done, exit the recursive editing level with @kbd{C-M-c} to proceed to -the next occurrence. @xref{Recursive Edit}. - -@item C-w -to delete the occurrence, and then enter a recursive editing level as in -@kbd{C-r}. Use the recursive edit to insert text to replace the deleted -occurrence of @var{string}. When done, exit the recursive editing level -with @kbd{C-M-c} to proceed to the next occurrence. - -@item e -to edit the replacement string in the minibuffer. When you exit the -minibuffer by typing @key{RET}, the minibuffer contents replace the -current occurrence of the pattern. They also become the new -replacement string for any further occurrences. - -@item C-l -to redisplay the screen. Then you must type another character to -specify what to do with this occurrence. - -@item C-h -to display a message summarizing these options. Then you must type -another character to specify what to do with this occurrence. -@end table - - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - - Aside from this, any other character exits the @code{query-replace}, -and is then reread as part of a key sequence. Thus, if you type -@kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. - - To restart a @code{query-replace} once it is exited, use @kbd{C-x -@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it -used the minibuffer to read its arguments. @xref{Repetition, C-x ESC -ESC}. - - @xref{Operating on Files}, for the Dired @kbd{Q} command which -performs query replace on selected files. See also @ref{Transforming -File Names}, for Dired commands to rename, copy, or link files by -replacing regexp matches in file names. - -@node Other Repeating Search -@section Other Search-and-Loop Commands - - Here are some other commands that find matches for a regular -expression. They all ignore case in matching, if the pattern contains -no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur} and its variants, all operate on the text from -point to the end of the buffer, or on the region if it is active. - -@findex list-matching-lines -@findex occur -@findex multi-occur -@findex multi-occur-in-matching-buffers -@findex how-many -@findex flush-lines -@findex keep-lines - -@table @kbd -@item M-x occur @key{RET} @var{regexp} @key{RET} -Display a list showing each line in the buffer that contains a match -for @var{regexp}. To limit the search to part of the buffer, narrow -to that part (@pxref{Narrowing}). A numeric argument @var{n} -specifies that @var{n} lines of context are to be displayed before and -after each matching line. Currently, @code{occur} can not correctly -handle multiline matches. - -@kindex RET @r{(Occur mode)} -@kindex o @r{(Occur mode)} -@kindex C-o @r{(Occur mode)} -The buffer @samp{*Occur*} containing the output serves as a menu for -finding the occurrences in their original context. Click -@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position -point there and type @key{RET}; this switches to the buffer that was -searched and moves point to the original of the chosen occurrence. -@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} -does not select it. - -After using @kbd{M-x occur}, you can use @code{next-error} to visit -the occurrences found, one by one. @ref{Compilation Mode}. - -@kindex M-s o -@item M-s o -Run @code{occur} using the search string of the last incremental -string search. You can also run @kbd{M-s o} when an incremental -search is active; this uses the current search string. - -@item M-x list-matching-lines -Synonym for @kbd{M-x occur}. - -@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} -This function is just like @code{occur}, except it is able to search -through multiple buffers. It asks you to specify the buffer names one by one. - -@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET} -This function is similar to @code{multi-occur}, except the buffers to -search are specified by a regular expression that matches visited -file names. With a prefix argument, it uses the regular expression to match -buffer names instead. - -@item M-x how-many @key{RET} @var{regexp} @key{RET} -Print the number of matches for @var{regexp} that exist in the buffer -after point. If the region is active, this operates on the region -instead. - -@item M-x flush-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that contains a match for @var{regexp}, -operating on the text after point; it deletes the current line if it -contains a match starting after point. If the region is active, it -operates on the region instead; if a line partially contained in the -region contains a match entirely contained in the region, it is -deleted. - -If a match is split across lines, @code{flush-lines} deletes all those -lines. It deletes the lines before starting to look for the next -match; hence, it ignores a match starting on the same line at which -another match ended. - -@item M-x keep-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that @emph{does not} contain a match -for @var{regexp}, operating on the text after point; if point is not -at the beginning of a line, it always keeps the current line. If the -region is active, the command operates on the region instead; it never -deletes lines that are only partially contained in the region (a -newline that ends a line counts as part of that line). - -If a match is split across lines, this command keeps all those lines. -@end table - -@ignore - arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e -@end ignore diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi deleted file mode 100644 index ff8fe8dde6d..00000000000 --- a/doc/emacs/sending.texi +++ /dev/null @@ -1,812 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Sending Mail -@chapter Sending Mail -@cindex sending mail -@cindex mail -@cindex message - - To send a message in Emacs, you start by typing a command (@kbd{C-x m}) -to select and initialize the @samp{*mail*} buffer. Then you edit the text -and headers of the message in this buffer, and type another command -(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message. - -@table @kbd -@item C-x m -Begin composing a message to send (@code{compose-mail}). -@item C-x 4 m -Likewise, but display the message in another window -(@code{compose-mail-other-window}). -@item C-x 5 m -Likewise, but make a new frame (@code{compose-mail-other-frame}). -@item C-c C-s -In Mail mode, send the message (@code{mail-send}). -@item C-c C-c -Send the message and bury the mail buffer (@code{mail-send-and-exit}). -@end table - -@kindex C-x m -@findex compose-mail -@kindex C-x 4 m -@findex compose-mail-other-window -@kindex C-x 5 m -@findex compose-mail-other-frame - The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named -@samp{*mail*} and initializes it with the skeleton of an outgoing -message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the -@samp{*mail*} buffer in a different window, leaving the previous current -buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates -a new frame to select the @samp{*mail*} buffer. - - Because the mail-composition buffer is an ordinary Emacs buffer, you can -switch to other buffers while in the middle of composing mail, and switch -back later (or never). If you use the @kbd{C-x m} command again when you -have been composing another message but have not sent it, you are asked to -confirm before the old message is erased. If you answer @kbd{n}, the -@samp{*mail*} buffer remains selected with its old contents, so you can -finish the old message and send it. @kbd{C-u C-x m} is another way to do -this. Sending the message marks the @samp{*mail*} buffer ``unmodified,'' -which avoids the need for confirmation when @kbd{C-x m} is next used. - - If you are composing a message in the @samp{*mail*} buffer and want to -send another message before finishing the first, rename the -@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc -Buffer}). Then you can use @kbd{C-x m} or its variants described above -to make a new @samp{*mail*} buffer. Once you've done that, you can work -with each mail buffer independently. - -@vindex mail-default-directory - The variable @code{mail-default-directory} controls the default -directory for mail buffers, and also says where to put their auto-save -files. - -@c Not mentioned: mail-bury-selects-summary. Really an Rmail feature. - -@ignore -@c Commented out because it is not user-oriented; -@c it doesn't say how to do some job. -- rms. -@cindex directory servers -@cindex LDAP -@cindex PH/QI -@cindex names and addresses -There is an interface to directory servers using various protocols such -as LDAP or the CCSO white pages directory system (PH/QI), described in a -separate manual. It may be useful for looking up names and addresses. -@xref{Top,,EUDC, eudc, EUDC Manual}. -@end ignore - -@menu -* Format: Mail Format. Format of the mail being composed. -* Headers: Mail Headers. Details of some standard mail header fields. -* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. -* Mode: Mail Mode. Special commands for editing mail being composed. -* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. -* Methods: Mail Methods. Using alternative mail-composition methods. -@end menu - -@node Mail Format -@section The Format of the Mail Buffer - - In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header -fields} which say who sent it, when, to whom, why, and so on. Some -header fields, such as @samp{Date} and @samp{Message-Id}, are created -automatically when you send the message. Others, such as the recipient -names, must be specified by you in order to send the message properly. - - In the mail buffer, you can insert and edit header fields using -ordinary editing commands. Mail mode provides commands to help you -edit some header fields, and some are automatically preinitialized in -the buffer, when appropriate. - -@vindex mail-header-separator - The line in the buffer that says - -@example ---text follows this line-- -@end example - -@noindent -is a special delimiter that separates the headers you have specified from -the text. Whatever follows this line is the text of the message; the -headers precede it. The delimiter line itself does not appear in the -message actually sent. The text used for the delimiter line is controlled -by the variable @code{mail-header-separator}. - - Here is an example of what the headers and text in the mail buffer -might look like. - -@example -To: gnu@@gnu.org -CC: lungfish@@spam.org, byob@@spam.org -Subject: The Emacs Manual ---text follows this line-- -Please ignore this message. -@end example - -@node Mail Headers -@section Mail Header Fields -@cindex headers (of mail message) - - A header field in the mail buffer starts with a field name at the -beginning of a line, terminated by a colon. Upper and lower case are -equivalent in field names (and in mailing addresses also). After the -colon and optional whitespace comes the contents of the field. - - You can use any name you like for a header field, but normally people -use only standard field names with accepted meanings. Here is a table -of fields commonly used in outgoing messages. Emacs preinitializes some -of these when you start to compose a mail, depending on various options -you can set. You can delete or alter any header field before you send -the message, if you wish. - -@table @samp -@item To -This field contains the mailing addresses to which the message is -addressed. If you list more than one address, use commas, not spaces, -to separate them. - -@item Subject -The contents of the @samp{Subject} field should be a piece of text -that says what the message is about. The reason @samp{Subject} fields -are useful is that most mail-reading programs can provide a summary of -messages, listing the subject of each message but not its text. - -@item CC -This field contains additional mailing addresses to send the message to, -like @samp{To} except that these readers should not regard the message -as directed at them. - -@item BCC -This field contains additional mailing addresses to send the message to, -which should not appear in the header of the message actually sent. -Copies sent this way are called @dfn{blind carbon copies}. - -@vindex mail-self-blind -@cindex copy of every outgoing message -To send a blind carbon copy of every outgoing message to yourself, set -the variable @code{mail-self-blind} to @code{t}. To send a blind carbon -copy of every message to some other @var{address}, set the variable -@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}. - -@item FCC -This field contains the name of one file and directs Emacs to append a -copy of the message to that file when you send the message. Emacs -writes the message in mbox format, unless the file is in Babyl format -(used by Rmail before Emacs 23), in which case Emacs writes Babyl. If -an Rmail buffer is visiting the file, Emacs updates it accordingly. -To specify more than one file, use several @samp{FCC} fields, with one -file name in each field. - -@vindex mail-archive-file-name -To put a fixed file name in the @samp{FCC} field each time you start -editing an outgoing message, set the variable -@code{mail-archive-file-name} to that file name. Unless you remove the -@samp{FCC} field before sending, the message will be written into that -file when it is sent. - -@item From -Use the @samp{From} field to say who you are. You might need to change -this if the account you are using to send the mail is not your own. The -contents of the @samp{From} field should be a valid mailing address, -since replies will normally go there. - -@vindex mail-setup-with-from -Emacs initializes this field (unless the variable -@code{mail-setup-with-from} is @code{nil}) using -@code{user-mail-address} as the default. If there is no @samp{From} -field when you send a mail, Emacs adds one. - -@item Reply-to -Use this field to direct replies to a different address. Most -mail-reading programs (including Rmail) automatically send replies to -the @samp{Reply-to} address in preference to the @samp{From} address. -By adding a @samp{Reply-to} field to your header, you can work around -any problems your @samp{From} address may cause for replies. - -@cindex @env{REPLYTO} environment variable -@vindex mail-default-reply-to -To put a fixed @samp{Reply-to} address into every outgoing message, set -the variable @code{mail-default-reply-to} to that address (as a string). -Then Emacs initializes the message with a @samp{Reply-to} field as -specified. When you first compose a mail, if -@code{mail-default-reply-to} is @code{nil}, Emacs initializes it from the -environment variable @env{REPLYTO}. - -@item Mail-reply-to - This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own purposes -(a somewhat controversial practice). - -@item Mail-followup-to - This field contains one or more addresses. It is typically used when -you reply to a message from a mailing list that you are subscribed to. -It usually indicates that you want replies to go to the list, and that -you do not need an extra copy sent directly to you. - -@vindex mail-mailing-lists - The variable @code{mail-mailing-lists} holds a list of mailing list -addresses that you are subscribed to. If it is non-@code{nil}, Emacs -inserts an appropriate @samp{Mail-followup-to} header when sending mail -to a mailing list. - -@c There is also "Sent-via", added by C-c C-v, but it does not seem -@c particularly useful (?). - -@item In-reply-to -This field contains a piece of text describing the message you are -replying to. Some mail systems can use this information to correlate -related pieces of mail. Normally this field is filled in by Rmail -when you reply to a message in Rmail, and you never need to -think about it (@pxref{Rmail}). - -@item References -This field lists the Message-Ids of related previous messages (a -Message-Id is a unique identifier generated when a message is sent). -Rmail sets up this field automatically when you reply to a message. -@end table - - The @samp{To}, @samp{CC}, and @samp{BCC} header fields can appear -any number of times, and each such header field can contain multiple -addresses, separated by commas. This way, you can specify any number -of places to send the message. These fields can also have -continuation lines: one or more lines starting with whitespace, -following the starting line of the field, are considered part of the -field. Here's an example of a @samp{To} field with a continuation -line: - -@example -@group -To: foo@@here.net, this@@there.net, - me@@gnu.cambridge.mass.usa.earth.spiral3281 -@end group -@end example - -@vindex mail-from-style - When you send the message, if you didn't write a @samp{From} field -yourself, Emacs puts in one for you, using @code{user-mail-address}. -The variable @code{mail-from-style} controls the format: - -@table @code -@item nil -Use just the email address, as in @samp{king@@grassland.com}. -@item parens -Use both email address and full name, as in:@* -@samp{king@@grassland.com (Elvis Parsley)}. -@item angles -Use both email address and full name, as in:@* -@samp{Elvis Parsley }. -@item system-default -Allow the system to insert the @samp{From} field. -@end table - -@c There is also mail-specify-envelope-from and mail-envelope-from, but -@c these are probably not topics for the Emacs manual. - -@vindex mail-default-headers - You can direct Emacs to insert certain default headers into the -outgoing message by setting the variable @code{mail-default-headers} -to a string. Then @code{C-x m} inserts this string into the message -headers. If the default header fields are not appropriate for a -particular message, edit them as necessary before sending the message. - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex @file{.mailrc} file -@cindex mailrc file - - You can define @dfn{mail aliases} in a file named @file{~/.mailrc}. -These are short mnemonic names which stand for mail addresses or groups of -mail addresses. Like many other mail programs, Emacs expands aliases -when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and -@samp{Reply-to} fields, plus their @samp{Resent-} variants. -@c The list is defined by mail-address-field-regexp. - - To define an alias in @file{~/.mailrc}, write a line in the following -format: - -@example -alias @var{shortaddress} @var{fulladdresses} -@end example - -@noindent -Here @var{fulladdresses} stands for one or more mail addresses for -@var{shortaddress} to expand into. Separate multiple addresses with -spaces; if an address contains a space, quote the whole address with a -pair of double quotes. - -For instance, to make @code{maingnu} stand for -@code{gnu@@gnu.org} plus a local address of your own, put in -this line:@refill - -@example -alias maingnu gnu@@gnu.org local-gnu -@end example - -@noindent -Addresses specified in this way should use double quotes around an -entire address when the address contains spaces. But you need not -include double quotes around parts of the address, such as the person's -full name. Emacs puts them in if they are needed. For example, - -@example -alias jsmith "John Q. Smith " -@end example - -@noindent -is correct in @samp{.mailrc}. Emacs will insert the address as -@samp{"John Q. Smith" }. - - Emacs also recognizes ``include'' commands in @samp{.mailrc} files. -They look like this: - -@example -source @var{filename} -@end example - -@noindent -The file @file{~/.mailrc} is used primarily by other mail-reading -programs; it can contain various other commands. Emacs ignores -everything in it except for alias definitions and include commands. - -@findex define-mail-alias - Another way to define a mail alias, within Emacs alone, is with the -@code{define-mail-alias} command. It prompts for the alias and then the -full address. You can use it to define aliases in your @file{.emacs} -file, like this: - -@example -(define-mail-alias "maingnu" "gnu@@gnu.org") -@end example - -@vindex mail-aliases - @code{define-mail-alias} records aliases by adding them to a -variable named @code{mail-aliases}. If you are comfortable with -manipulating Lisp lists, you can set @code{mail-aliases} directly. The -initial value of @code{mail-aliases} is @code{t}, which means that -Emacs should read @file{.mailrc} to get the proper value. - -@vindex mail-personal-alias-file - You can specify a different file name to use instead of -@file{~/.mailrc} by setting the variable -@code{mail-personal-alias-file}. - -@c There is also mail-alias-file for the system aliases. - -@findex expand-mail-aliases - Normally, Emacs expands aliases when you send the message. You do not -need to expand mail aliases before sending the message, but you can -expand them if you want to see where the mail will actually go. To do -this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail -aliases currently present in the mail headers that hold addresses. - - If you like, you can have mail aliases expand as abbrevs, as soon as -you type them in (@pxref{Abbrevs}). To enable this feature, execute the -following: - -@example -(add-hook 'mail-mode-hook 'mail-abbrevs-setup) -@end example - -@noindent -@findex define-mail-abbrev -@vindex mail-abbrevs -This can go in your @file{.emacs} file. @xref{Hooks}. If you use this -feature, you must use @code{define-mail-abbrev} instead of -@code{define-mail-alias}; the latter does not work with this package. -Note that the mail abbreviation package uses the variable -@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias -names are converted to lower case. - -@kindex C-c C-a @r{(Mail mode)} -@findex mail-abbrev-insert-alias - The mail abbreviation package also provides the @kbd{C-c C-a} -(@code{mail-abbrev-insert-alias}) command, which reads an alias -name (with completion) and inserts its definition at point. This is -useful when editing the message text itself or a header field such as -@samp{Subject} in which Emacs does not normally expand aliases. - - Note that abbrevs expand only if you insert a word-separator character -afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause -expansion as well. Here's how to do that: - -@smallexample -(add-hook 'mail-mode-hook - (lambda () - (define-key - mail-mode-map [remap next-line] 'mail-abbrev-next-line) - (define-key - mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer))) -@end smallexample - -@node Mail Mode -@section Mail Mode -@cindex Mail mode -@cindex mode, Mail - - The major mode used in the mail buffer is Mail mode, which is much -like Text mode except that various special commands are provided on the -@kbd{C-c} prefix. These commands all have to do specifically with -editing or sending the message. - - Mail mode is normally used in buffers set up automatically by the -@code{mail} command and related commands. However, you can also switch -to Mail mode in a file-visiting buffer. This is a useful thing to do if -you have saved the text of a draft message in a file. - -@menu -* Mail Sending:: Commands to send the message. -* Header Editing:: Commands to move to header fields and edit them. -* Citing Mail:: Copying all or part of a message you are replying to. -* Mail Mode Misc:: Spell checking, signatures, etc. -@end menu - -@node Mail Sending -@subsection Mail Sending - - Mail mode has two commands for sending the message you have been -editing: - -@table @kbd -@item C-c C-s -Send the message, and leave the mail buffer selected (@code{mail-send}). -@item C-c C-c -Send the message, and select some other buffer (@code{mail-send-and-exit}). -@end table - -@kindex C-c C-s @r{(Mail mode)} -@kindex C-c C-c @r{(Mail mode)} -@findex mail-send -@findex mail-send-and-exit -@vindex mail-send-hook - @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail -buffer unmodified, but leaves that buffer selected so that you can -modify the message (perhaps with new recipients) and send it again. -@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the -window or switches to another buffer. It puts the mail buffer at the -lowest priority for reselection by default, since you are finished with -using it. This is the usual way to send the message. Sending a message -runs the hook @code{mail-send-hook}. - -@c Options not mentioned: mail-interactive, mail-use-dsn. - - In a file-visiting buffer, sending the message does not clear the -modified flag, because only saving the file should do that. Also, you -don't get a warning if you try to send the same message twice. - -@c This is indexed in mule.texi, node "Recognize Coding". -@c @vindex sendmail-coding-system - When you send a message that contains non-@acronym{ASCII} characters, they need -to be encoded with a coding system (@pxref{Coding Systems}). Usually -the coding system is specified automatically by your chosen language -environment (@pxref{Language Environments}). You can explicitly specify -the coding system for outgoing mail by setting the variable -@code{sendmail-coding-system} (@pxref{Recognize Coding}). - - If the coding system thus determined does not handle the characters in -a particular message, Emacs asks you to select the coding system to use, -showing a list of possible coding systems. - -@c Not mentioned: mail-send-nonascii. - -@cindex SMTP -@cindex Feedmail -@cindex Sendmail -@cindex Mailclient -@vindex send-mail-function - The variable @code{send-mail-function} controls how the default mail -user agent sends mail. It should be set to a function. In most cases, -the default is @code{sendmail-send-it}, which delivers mail using the -Sendmail installation on the local host. On Mac OS X and MS-Windows, -however, the default is normally @code{mailclient-send-it}, which -passes the mail buffer on to the system's designated mail client (see -@file{mailclient.el}). To send mail through an SMTP server, set -@code{send-mail-function} to @code{smtpmail-send-it} and set up the -Emacs SMTP library (@pxref{Top,,Emacs SMTP Library, smtpmail, Sending -mail via SMTP}). Another option is @code{feedmail-send-it} (see the -commentary section of the @file{feedmail.el} package). - -@node Header Editing -@subsection Mail Header Editing - - Mail mode provides special commands to move to particular header -fields and to complete addresses in headers. - -@table @kbd -@item C-c C-f C-t -Move to the @samp{To} header field, creating one if there is none -(@code{mail-to}). -@item C-c C-f C-s -Move to the @samp{Subject} header field, creating one if there is -none (@code{mail-subject}). -@item C-c C-f C-c -Move to the @samp{CC} header field, creating one if there is none -(@code{mail-cc}). -@item C-c C-f C-b -Move to the @samp{BCC} header field, creating one if there is none -(@code{mail-bcc}). -@item C-c C-f C-r -Move to the @samp{Reply-To} header field, creating one if there is none -(@code{mail-reply-to}). -@item C-c C-f C-a -Move to the @samp{Mail-Reply-To} header field, creating one if there is none -(@code{mail-mail-reply-to}). -@item C-c C-f C-l -Move to the @samp{Mail-Followup-To} header field, creating one if there is none -(@code{mail-mail-followup-to}). -@item C-c C-f C-f -Add a new @samp{FCC} header field, with file-name completion -(@code{mail-fcc}). -@c There is also C-c C-v, mail-sent-via, which adds one or more -@c "Sent-via" headers, but I don't know what the point of that header is. -@item M-@key{TAB} -Complete a mailing address (@code{mail-complete}). -@end table - -@kindex C-c C-f C-t @r{(Mail mode)} -@findex mail-to -@kindex C-c C-f C-s @r{(Mail mode)} -@findex mail-subject -@kindex C-c C-f C-c @r{(Mail mode)} -@findex mail-cc -@kindex C-c C-f C-b @r{(Mail mode)} -@findex mail-bcc -@kindex C-c C-f C-r @r{(Mail mode)} -@findex mail-reply-to -@kindex C-c C-f C-a @r{(Mail mode)} -@findex mail-mail-reply-to -@kindex C-c C-f C-l @r{(Mail mode)} -@findex mail-mail-followup-to -@kindex C-c C-f C-f @r{(Mail mode)} -@findex mail-fcc - There are several commands to move point to particular header fields, -all based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). -They are listed in the table above. If the field in question does not -exist, these commands create one (the exception is @code{mail-fcc}, -which creates a new field each time). We provide special motion -commands for these particular fields because they are the fields users -most often want to edit. - -@findex mail-complete -@kindex M-TAB @r{(Mail mode)} -@c `mail-complete-alist' specifies the headers. - While editing a header field that contains mailing addresses, such -as @samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing -address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It -inserts the full name corresponding to the address, if it can -determine the full name. The variable @code{mail-complete-style} -controls whether to insert the full name, and what style to use, as in -@code{mail-from-style} (@pxref{Mail Headers}). (If your window -manager defines @kbd{M-@key{TAB}} to switch windows, you can type -@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) - - For completion purposes, the valid mailing addresses are taken to be -the local users' names plus your personal mail aliases (@pxref{Mail -Aliases}). You can specify additional sources of valid addresses; -browse the customization group @samp{mailalias} to see the variables for -customizing this feature (@pxref{Customization Groups}). - - If you type @kbd{M-@key{TAB}} in the body of the message, or on a -unrecognized header, @code{mail-complete} invokes the function specified -by @code{mail-complete-function}. By default, this is -@code{ispell-complete-word}, as in Text mode. - -@node Citing Mail -@subsection Citing Mail -@cindex citing mail - - Mail mode also has commands for yanking or @dfn{citing} all or part of -a message that you are replying to. These commands are active only when -you started sending a message using an Rmail command. - -@table @kbd -@item C-c C-y -Yank the selected message from Rmail (@code{mail-yank-original}). -@item C-c C-r -Yank the region from the Rmail buffer (@code{mail-yank-region}). -@item C-c C-q -Fill each paragraph cited from another message -(@code{mail-fill-yanked-message}). -@c There is also mail-split-line, but it does not seem very useful. -@end table - -@kindex C-c C-y @r{(Mail mode)} -@findex mail-yank-original - When mail sending is invoked from the Rmail mail reader using an Rmail -command, @kbd{C-c C-y} can be used inside the mail buffer to insert the -text of the message you are replying to. Normally it indents each line -of that message three spaces and eliminates most header fields (as -specified by the variable @code{mail-yank-ignored-headers}). A numeric -argument specifies the number of spaces to indent (the variable -@code{mail-indentation-spaces} specifies the default number). An -argument of just @kbd{C-u} says not to indent at all and not to -eliminate anything. @kbd{C-c C-y} always uses the current message from -the Rmail buffer, so you can insert several old messages by selecting -one in Rmail, switching to @samp{*mail*} and yanking it, then switching -back to Rmail to select another. - -@vindex mail-yank-prefix - You can specify the text for @kbd{C-c C-y} to insert at the beginning -of each line: set @code{mail-yank-prefix} to the desired string. (A -value of @code{nil} means to use indentation; this is the default.) -However, @kbd{C-u C-c C-y} never adds anything at the beginning of the -inserted lines, regardless of the value of @code{mail-yank-prefix}. - -@kindex C-c C-r @r{(Mail mode)} -@findex mail-yank-region - To yank just a part of an incoming message, set the region in Rmail to -the part you want; then go to the @samp{*Mail*} message and type -@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is -indented or prefixed according to @code{mail-yank-prefix}. - -@kindex C-c C-q @r{(Mail mode)} -@findex mail-fill-yanked-message - After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q} -(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked -old message or messages. One use of @kbd{C-c C-q} fills all such -paragraphs, each one individually. To fill a single paragraph of the -quoted message, use @kbd{M-q}. If filling does not automatically -handle the type of citation prefix you use, try setting the fill prefix -explicitly. @xref{Filling}. - -@vindex mail-citation-hook - You can customize mail citation through the hook -@code{mail-citation-hook}. For example, you can use the Supercite -package, which provides more flexible citation -(@pxref{Introduction,,,sc, Supercite}). - -@c No need to mention: mail-citation-prefix-regexp. - -@node Mail Mode Misc -@subsection Mail Mode Miscellany - -@table @kbd -@item C-c C-t -Move to the beginning of the message body text (@code{mail-text}). -@item C-c C-w -Insert a signature at the end of the message text (@code{mail-signature}). -@item C-c C-i @var{file} @key{RET} -Insert the contents of @var{file} at the end of the message text -(@code{mail-attach-file}). -@item M-x ispell-message -Perform spelling correction on the message text, but not on citations from -other messages, or the message headers. -@end table - -@kindex C-c C-t @r{(Mail mode)} -@findex mail-text - @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header -separator line---that is, to the beginning of the message body text. - -@kindex C-c C-w @r{(Mail mode)} -@findex mail-signature -@vindex mail-signature - @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text -(your @dfn{mail signature}) at the end of the message to say more about who -you are. For example, it may contain telephone numbers, or your -physical location. The text comes from the variable -@code{mail-signature}. It can be a fixed string, or a Lisp expression -that returns a string. If it is @code{t} or @code{nil}, the function -inserts the contents of the file @code{mail-signature-file}. By -default, this is the file @file{~/.signature} in your home directory. - - If the variable @code{mail-signature} has a non-@code{nil} value, -starting a mail automatically inserts your signature. Otherwise, you -must explicitly use the command @code{mail-signature}. If you want to -omit your signature from a particular message, just delete it from the -buffer before you send the message. - - Convention says that the start of your signature should be marked by a -line whose contents are @samp{-- }. If your signature comes from a -file, this prefix is added for you, but in all other cases you must add -it yourself. The remainder of your signature should be no more than -four lines. - -@findex ispell-message - You can do spelling correction on the message text you have written -with the command @kbd{M-x ispell-message}. If you have yanked an -incoming message into the outgoing draft, this command skips what was -yanked, but it checks the text that you yourself inserted. (It looks -for indentation or @code{mail-yank-prefix} to distinguish the cited -lines from your input.) @xref{Spelling}. - -@kindex C-c C-i @r{(Mail mode)} -@findex mail-attach-file - To include a file in the outgoing message, you can use @kbd{C-x i}, -the usual command to insert a file in the current buffer. But it is -often more convenient to use a special command, @kbd{C-c C-i} -(@code{mail-attach-file}). This command inserts the file contents at -the end of the buffer, after your signature (if any), with a delimiter -line that includes the file name. Note that this is not a MIME -attachment. - -@vindex mail-mode-hook -@vindex mail-setup-hook - Turning on Mail mode (which @kbd{C-x m} does automatically) runs the -normal hooks @code{text-mode-hook} and @code{mail-mode-hook}. -Initializing a new outgoing message runs the normal hook -@code{mail-setup-hook}; if you want to add special fields to your mail -header or make other changes to the appearance of the mail buffer, use -that hook. @xref{Hooks}. - - The main difference between these hooks is just when they are -invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs -as soon as the @samp{*mail*} buffer is created. Then the -@code{mail-setup} function inserts the default contents of the buffer. -After these default contents are inserted, @code{mail-setup-hook} runs. - - If you use @kbd{M-x mail} to continue an existing composition, -@code{mail-mode-hook} runs immediately after switching to the -@samp{*mail*} buffer. If the buffer is unmodified, or if you decide to -erase it and start again, @code{mail-setup-hook} runs after the default -contents are inserted. - -@node Mail Amusements -@section Mail Amusements - -@findex spook -@cindex NSA - @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing -mail message. The keywords are chosen from a list of words that suggest -you are discussing something subversive. - - The idea behind this feature is the suspicion that the -NSA@footnote{The US National Security Agency.} and other intelligence -agencies snoop on all electronic mail messages that contain keywords -suggesting they might find them interesting. (The agencies say that -they don't, but that's what they @emph{would} say.) The idea is that if -lots of people add suspicious words to their messages, the agencies will -get so busy with spurious input that they will have to give up reading -it all. Whether or not this is true, it at least amuses some people. - -@findex fortune-to-signature -@cindex fortune cookies - You can use the @code{fortune} program to put a ``fortune cookie'' -message into outgoing mail. To do this, add -@code{fortune-to-signature} to @code{mail-setup-hook}: - -@example -(add-hook 'mail-setup-hook 'fortune-to-signature) -@end example - -@noindent -You will probably need to set the variable @code{fortune-file} before -using this. - -@node Mail Methods -@section Mail-Composition Methods -@cindex mail-composition methods - -@cindex MH mail interface -@cindex Message mode for sending mail - In this chapter we have described the usual Emacs mode for editing -and sending mail---Mail mode. Emacs has alternative facilities for -editing and sending mail, including -MH-E and Message mode, not documented in this manual. -@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @xref{Top,,Message,message, -Message Manual}. You can choose any of them as your preferred method. -The commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use -whichever agent you have specified, as do various other Emacs commands -and facilities that send mail. - -@vindex mail-user-agent - To specify your mail-composition method, customize the variable -@code{mail-user-agent}. Currently legitimate values include -@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent}, -@code{message-user-agent} and @code{gnus-user-agent}. - - If you select a different mail-composition method, the information -in this chapter about the @samp{*mail*} buffer and Mail mode does not -apply; the other methods use a different format of text in a different -buffer, and their commands are different as well. - -@vindex read-mail-command - Similarly, to specify your preferred method for reading mail, -customize the variable @code{read-mail-command}. The default is -@code{rmail} (@pxref{Rmail}). - -@ignore - arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6 -@end ignore diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi deleted file mode 100644 index 3202d28769f..00000000000 --- a/doc/emacs/text.texi +++ /dev/null @@ -1,2929 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Text, Programs, Indentation, Top -@chapter Commands for Human Languages -@cindex text -@cindex manipulating text - - This chapter describes Emacs commands that act on @dfn{text}, by -which we mean sequences of characters in a human language (as opposed -to, say, a computer programming language). These commands act in ways -that take into account the syntactic and stylistic conventions of -human languages: conventions involving words, sentences, paragraphs, -and capital letters. There are also commands for @dfn{filling}, which -means rearranging the lines of a paragraph to be approximately equal -in length. These commands, while intended primarily for editing text, -are also often useful for editing programs. - - Emacs has several major modes for editing human-language text. If -the file contains ordinary text, use Text mode, which customizes Emacs -in small ways for the syntactic conventions of text. Outline mode -provides special commands for operating on text with an outline -structure. -@iftex -@xref{Outline Mode}. -@end iftex - - Emacs has other major modes for text which contains ``embedded'' -commands, such as @TeX{} and La@TeX{} (@pxref{TeX Mode}); HTML, SGML, -and XML (@pxref{HTML Mode}); and Groff and Nroff (@pxref{Nroff Mode}). -In addition, you can edit formatted text in WYSIWYG style (``what you -see is what you get''), using Enriched mode (@pxref{Formatted Text}). - -@cindex ASCII art - If you need to edit pictures made out of text characters (commonly -referred to as ``ASCII art''), use Picture mode, a special major mode -for editing such pictures. -@iftex -@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{Picture Mode}. -@end ifnottex - - -@cindex skeletons -@cindex templates -@cindex autotyping -@cindex automatic typing - The ``automatic typing'' features may be useful when writing text. -@inforef{Top,, autotype}. - -@menu -* Words:: Moving over and killing words. -* Sentences:: Moving over and killing sentences. -* Paragraphs:: Moving over paragraphs. -* Pages:: Moving over pages. -* Filling:: Filling or justifying text. -* Case:: Changing the case of text. -* Text Mode:: The major modes for editing text files. -* Outline Mode:: Editing outlines. -* TeX Mode:: Editing input to the formatter TeX. -* HTML Mode:: Editing HTML, SGML, and XML files. -* Nroff Mode:: Editing input to the formatter nroff. -* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. -* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. -@end menu - -@node Words -@section Words -@cindex words -@cindex Meta commands and words - - Emacs has commands for moving over or operating on words. By convention, -the keys for them are all Meta characters. - -@table @kbd -@item M-f -Move forward over a word (@code{forward-word}). -@item M-b -Move backward over a word (@code{backward-word}). -@item M-d -Kill up to the end of a word (@code{kill-word}). -@item M-@key{DEL} -Kill back to the beginning of a word (@code{backward-kill-word}). -@item M-@@ -Mark the end of the next word (@code{mark-word}). -@item M-t -Transpose two words or drag a word across others -(@code{transpose-words}). -@end table - - Notice how these keys form a series that parallels the character-based -@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is -cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. - -@kindex M-f -@kindex M-b -@findex forward-word -@findex backward-word - The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} -(@code{backward-word}) move forward and backward over words. These -@key{Meta}-based key sequences are analogous to the key sequences -@kbd{C-f} and @kbd{C-b}, which move over single characters. The -analogy extends to numeric arguments, which serve as repeat counts. -@kbd{M-f} with a negative argument moves backward, and @kbd{M-b} with -a negative argument moves forward. Forward motion stops right after -the last letter of the word, while backward motion stops right before -the first letter. - -@kindex M-d -@findex kill-word - @kbd{M-d} (@code{kill-word}) kills the word after point. To be -precise, it kills everything from point to the place @kbd{M-f} would -move to. Thus, if point is in the middle of a word, @kbd{M-d} kills -just the part after point. If some punctuation comes between point -and the next word, it is killed along with the word. (If you wish to -kill only the next word but not the punctuation before it, simply do -@kbd{M-f} to get the end, and kill the word backwards with -@kbd{M-@key{DEL}}.) @kbd{M-d} takes arguments just like @kbd{M-f}. - -@findex backward-kill-word -@kindex M-DEL - @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before -point. It kills everything from point back to where @kbd{M-b} would -move to. For instance, if point is after the space in @w{@samp{FOO, -BAR}}, it kills @w{@samp{FOO, }}. If you wish to kill just -@samp{FOO}, and not the comma and the space, use @kbd{M-b M-d} instead -of @kbd{M-@key{DEL}}. - -@c Don't index M-t and transpose-words here, they are indexed in -@c fixit.texi, in the node "Transpose". -@c @kindex M-t -@c @findex transpose-words - @kbd{M-t} (@code{transpose-words}) exchanges the word before or -containing point with the following word. The delimiter characters between -the words do not move. For example, @w{@samp{FOO, BAR}} transposes into -@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for -more on transposition. - -@kindex M-@@ -@findex mark-word - To operate on the next @var{n} words with an operation which acts on -the region, use the command @kbd{M-@@} (@code{mark-word}). This -command does not move point, but sets the mark where @kbd{M-f} would -move to. Once the mark is active, each additional @kbd{M-@@} advances -the mark by one additional word. @kbd{M-@@} also accepts a numeric -argument that says how many words to scan for the place to put the -mark. - - The word commands' understanding of word boundaries is controlled -by the syntax table. Any character can, for example, be declared to -be a word delimiter. @xref{Syntax}. - -@node Sentences -@section Sentences -@cindex sentences -@cindex manipulating sentences - - The Emacs commands for manipulating sentences and paragraphs are mostly -on Meta keys, so as to be like the word-handling commands. - -@table @kbd -@item M-a -Move back to the beginning of the sentence (@code{backward-sentence}). -@item M-e -Move forward to the end of the sentence (@code{forward-sentence}). -@item M-k -Kill forward to the end of the sentence (@code{kill-sentence}). -@item C-x @key{DEL} -Kill back to the beginning of the sentence (@code{backward-kill-sentence}). -@end table - -@kindex M-a -@kindex M-e -@findex backward-sentence -@findex forward-sentence - The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and -@code{forward-sentence}) move to the beginning and end of the current -sentence, respectively. They were chosen to resemble @kbd{C-a} and -@kbd{C-e}, which move to the beginning and end of a line. Unlike -them, @kbd{M-a} and @kbd{M-e} move over successive sentences if -repeated. - - Moving backward over a sentence places point just before the first -character of the sentence; moving forward places point right after the -punctuation that ends the sentence. Neither one moves over the -whitespace at the sentence boundary. - -@kindex M-k -@findex kill-sentence - Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to -go with them, @kbd{M-a} and @kbd{M-e} have a corresponding kill -command: @kbd{M-k} (@code{kill-sentence}) kills from point to the end -of the sentence. With a positive numeric argument @var{n}, it kills -the next @var{n} sentences; with a negative argument @minus{}@var{n}, -it kills back to the beginning of the @var{n}th preceding sentence. - -@kindex C-x DEL -@findex backward-kill-sentence - The @kbd{C-x @key{DEL}} (@code{backward-kill-sentence}) kills back -to the beginning of a sentence. - - The sentence commands assume that you follow the American typist's -convention of putting two spaces at the end of a sentence; they consider -a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!} -followed by the end of a line or two spaces, with any number of -@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between. -A sentence also begins or ends wherever a paragraph begins or ends. -It is useful to follow this convention, because it makes a distinction -between periods that end a sentence and periods that indicate -abbreviations; that enables the Emacs sentence commands to distinguish, -too. These commands do not stop for periods that indicate abbreviations. - -@vindex sentence-end-double-space - If you want to use just one space between sentences, you can set the -variable @code{sentence-end-double-space} to @code{nil} to make the -sentence commands stop for single spaces. However, this has a -drawback: there is no way to distinguish between periods that end -sentences and those that indicate abbreviations. For convenient and -reliable editing, we therefore recommend you follow the two-space -convention. The variable @code{sentence-end-double-space} also -affects filling (@pxref{Fill Commands}) in related ways. - -@vindex sentence-end - The variable @code{sentence-end} controls how to recognize the end -of a sentence. If non-@code{nil}, its value should be a regular -expression, which is used to match the last few characters of a -sentence, together with the whitespace following the sentence -(@pxref{Regexps}). If the value is @code{nil}, the default, then -Emacs computes sentence ends according to various criteria such as the -value of @code{sentence-end-double-space}. - -@vindex sentence-end-without-period - Some languages do not use periods to indicate the end of a sentence. -For example, sentences in Thai end with a double space but without a -period. Set the variable @code{sentence-end-without-period} to -@code{t} in such cases. - -@node Paragraphs -@section Paragraphs -@cindex paragraphs -@cindex manipulating paragraphs -@kindex M-@{ -@kindex M-@} -@findex backward-paragraph -@findex forward-paragraph - - The Emacs commands for manipulating paragraphs are also on Meta keys. - -@table @kbd -@item M-@{ -Move back to previous paragraph beginning (@code{backward-paragraph}). -@item M-@} -Move forward to next paragraph end (@code{forward-paragraph}). -@item M-h -Put point and mark around this or next paragraph (@code{mark-paragraph}). -@end table - - @kbd{M-@{} moves to the beginning of the current or previous -paragraph, while @kbd{M-@}} moves to the end of the current or next -paragraph. Blank lines and text-formatter command lines separate -paragraphs and are not considered part of any paragraph. If there is -a blank line before the paragraph, @kbd{M-@{} moves to the blank line, -because that is convenient in practice. - - In Text mode, an indented line is not a paragraph break. If you -want indented lines to have this effect, use Paragraph-Indent Text -mode instead. @xref{Text Mode}. - - In major modes for programs, paragraphs begin and end only at blank -lines. This makes the paragraph commands useful, even though there -are no paragraphs as such in a program. - - When you have set a fill prefix, then paragraphs are delimited by -all lines which don't start with the fill prefix. @xref{Filling}. - -@kindex M-h -@findex mark-paragraph - When you wish to operate on a paragraph, type @kbd{M-h} -(@code{mark-paragraph}) to set the region around it. For example, -@kbd{M-h C-w} kills the paragraph around or after point. @kbd{M-h} -puts point at the beginning and mark at the end of the paragraph point -was in. If point is between paragraphs (in a run of blank lines, or -at a boundary), the paragraph following point is surrounded by point -and mark. If there are blank lines preceding the first line of the -paragraph, one of these blank lines is included in the region. If the -region is already active, the command sets the mark without changing -point; furthermore, each subsequent @kbd{M-h} further advances the -mark by one paragraph. - -@vindex paragraph-start -@vindex paragraph-separate - The precise definition of a paragraph boundary is controlled by the -variables @code{paragraph-separate} and @code{paragraph-start}. The -value of @code{paragraph-start} is a regexp that should match any line -that either starts or separates paragraphs. The value of -@code{paragraph-separate} is another regexp that should match only lines -that separate paragraphs without being part of any paragraph (for -example, blank lines). Lines that start a new paragraph and are -contained in it must match only @code{paragraph-start}, not -@code{paragraph-separate}. Each regular expression must match at the -left margin. For example, in Fundamental mode, @code{paragraph-start} -is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is -@w{@code{"[ \t\f]*$"}}. - - Normally it is desirable for page boundaries to separate paragraphs. -The default values of these variables recognize the usual separator for -pages. - -@node Pages -@section Pages - -@cindex pages -@cindex formfeed character - Within some text files, text is divided into @dfn{pages}, which are -delimited by the @dfn{formfeed character} (@acronym{ASCII} code 12, -sometimes denoted as @key{control-L}). When you print hardcopy for a -file, the formfeed character forces a page break: each page of the -file goes on a separate page on paper. Most Emacs commands treat the -formfeed character just like any other character: you can insert it -with @kbd{C-q C-l}, and delete it with @key{DEL}. However, since -pages are often meaningful divisions of the file, Emacs provides -commands to move over them and operate on them. - -@table @kbd -@item C-x [ -Move point to previous page boundary (@code{backward-page}). -@item C-x ] -Move point to next page boundary (@code{forward-page}). -@item C-x C-p -Put point and mark around this page (or another page) (@code{mark-page}). -@item C-x l -Count the lines in this page (@code{count-lines-page}). -@end table - -@kindex C-x [ -@kindex C-x ] -@findex forward-page -@findex backward-page - The @kbd{C-x [} (@code{backward-page}) command moves point to immediately -after the previous page delimiter. If point is already right after a page -delimiter, it skips that one and stops at the previous one. A numeric -argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) -command moves forward past the next page delimiter. - -@kindex C-x C-p -@findex mark-page - The @kbd{C-x C-p} command (@code{mark-page}) puts point at the -beginning of the current page and the mark at the end. The page -delimiter at the end is included (the mark follows it). The page -delimiter at the front is excluded (point follows it). - - @kbd{C-x C-p C-w} is a handy way to kill a page to move it -elsewhere. If you move to another page delimiter with @kbd{C-x [} and -@kbd{C-x ]}, then yank the killed page, all the pages will be properly -delimited once again. The reason @kbd{C-x C-p} includes only the -following page delimiter in the region is to ensure that. - - A numeric argument to @kbd{C-x C-p} specifies which page to go to, -relative to the current one. Zero means the current page. One means -the next page, and @minus{}1 means the previous one. - -@kindex C-x l -@findex count-lines-page - The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding -where to break a page in two. It displays in the echo area the total number -of lines in the current page, and then divides it up into those preceding -the current line and those following, as in - -@example -Page has 96 (72+25) lines -@end example - -@noindent - Notice that the sum is off by one; this is correct if point is not at the -beginning of a line. - -@vindex page-delimiter - The variable @code{page-delimiter} controls where pages begin. Its -value is a regular expression that matches the beginning of a line -that separates pages (@pxref{Regexps}). The normal value of this -variable is @code{"^\f"}, which matches a formfeed character at the -beginning of a line. - -@node Filling -@section Filling Text -@cindex filling text - - @dfn{Filling} text means breaking it up into lines that fit a -specified width. Emacs does filling in two ways. In Auto Fill mode, -inserting text with self-inserting characters also automatically fills -it. There are also explicit fill commands that you can use when editing -text leaves it unfilled. When you edit formatted text, you can specify -a style of filling for each portion of the text (@pxref{Formatted -Text}). - -@menu -* Auto Fill:: Auto Fill mode breaks long lines automatically. -* Fill Commands:: Commands to refill paragraphs and center lines. -* Fill Prefix:: Filling paragraphs that are indented - or in a comment, etc. -* Adaptive Fill:: How Emacs can determine the fill prefix automatically. -* Refill:: Keeping paragraphs filled. -* Longlines:: Editing text with very long lines. -@end menu - -@node Auto Fill -@subsection Auto Fill Mode -@cindex Auto Fill mode -@cindex mode, Auto Fill - - @dfn{Auto Fill} mode is a minor mode in which lines are broken -automatically when they become too wide. Breaking happens only when -you type a @key{SPC} or @key{RET}. - -@table @kbd -@item M-x auto-fill-mode -Enable or disable Auto Fill mode. -@item @key{SPC} -@itemx @key{RET} -In Auto Fill mode, break lines when appropriate. -@end table - -@findex auto-fill-mode - @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off -if it was on. With a positive numeric argument it always turns Auto -Fill mode on, and with a negative argument always turns it off. You can -see when Auto Fill mode is in effect by the presence of the word -@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is -a minor mode which is enabled or disabled for each buffer individually. -@xref{Minor Modes}. - - In Auto Fill mode, lines are broken automatically at spaces when they -get longer than the desired width. Line breaking and rearrangement -takes place only when you type @key{SPC} or @key{RET}. If you wish to -insert a space or newline without permitting line-breaking, type -@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a -control-J). Also, @kbd{C-o} inserts a newline without line breaking. - - Auto Fill mode works well with programming-language modes, because it -indents new lines with @key{TAB}. If a line ending in a comment gets -too long, the text of the comment is split into two comment lines. -Optionally, new comment delimiters are inserted at the end of the first -line and the beginning of the second so that each line is a separate -comment; the variable @code{comment-multi-line} controls the choice -(@pxref{Comments}). - - Adaptive filling (@pxref{Adaptive Fill}) works for Auto Filling as -well as for explicit fill commands. It takes a fill prefix -automatically from the second or first line of a paragraph. - - Auto Fill mode does not refill entire paragraphs; it can break lines but -cannot merge lines. So editing in the middle of a paragraph can result in -a paragraph that is not correctly filled. The easiest way to make the -paragraph properly filled again is usually with the explicit fill commands. -@ifnottex -@xref{Fill Commands}. -@end ifnottex - - Many users like Auto Fill mode and want to use it in all text files. -The section on init files says how to arrange this permanently for yourself. -@xref{Init File}. - -@node Fill Commands -@subsection Explicit Fill Commands - -@table @kbd -@item M-q -Fill current paragraph (@code{fill-paragraph}). -@item C-x f -Set the fill column (@code{set-fill-column}). -@item M-x fill-region -Fill each paragraph in the region (@code{fill-region}). -@item M-x fill-region-as-paragraph -Fill the region, considering it as one paragraph. -@item M-o M-s -Center a line. -@end table - -@kindex M-q -@findex fill-paragraph - To refill a paragraph, use the command @kbd{M-q} -(@code{fill-paragraph}). This operates on the paragraph that point is -inside, or the one after point if point is between paragraphs. -Refilling works by removing all the line-breaks, then inserting new -ones where necessary. When there is an active region, this command -operates on the text within the region like @code{fill-region}. - -@findex fill-region - To refill many paragraphs, use @kbd{M-x fill-region}, which -finds the paragraphs in the region and fills each of them. - -@findex fill-region-as-paragraph - @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h} -for finding paragraph boundaries (@pxref{Paragraphs}). For more -control, you can use @kbd{M-x fill-region-as-paragraph}, which refills -everything between point and mark as a single paragraph. This command -deletes any blank lines within the region, so separate blocks of text -end up combined into one block. - -@cindex justification - A numeric argument to @kbd{M-q} tells it to @dfn{justify} the text -as well as filling it. This means that extra spaces are inserted to -make the right margin line up exactly at the fill column. To remove -the extra spaces, use @kbd{M-q} with no argument. (Likewise for -@code{fill-region}.) Another way to control justification, and choose -other styles of filling, is with the @code{justification} text -property; see @ref{Format Justification}. - -@kindex M-o M-s @r{(Text mode)} -@cindex centering -@findex center-line - The command @kbd{M-o M-s} (@code{center-line}) centers the current line -within the current fill column. With an argument @var{n}, it centers -@var{n} lines individually and moves past them. This binding is -made by Text mode and is available only in that and related modes -(@pxref{Text Mode}). - -@vindex fill-column -@kindex C-x f -@findex set-fill-column - The maximum line width for filling is in the variable -@code{fill-column}. Altering the value of @code{fill-column} makes it -local to the current buffer; until that time, the default value is in -effect. The default is initially 70. @xref{Locals}. The easiest way -to set @code{fill-column} is to use the command @kbd{C-x f} -(@code{set-fill-column}). With a numeric argument, it uses that as the -new fill column. With just @kbd{C-u} as argument, it sets -@code{fill-column} to the current horizontal position of point. - - Emacs commands normally consider a period followed by two spaces or by -a newline as the end of a sentence; a period followed by just one space -indicates an abbreviation and not the end of a sentence. To preserve -the distinction between these two ways of using a period, the fill -commands do not break a line after a period followed by just one space. - - If the variable @code{sentence-end-double-space} is @code{nil}, the -fill commands expect and leave just one space at the end of a sentence. -Ordinarily this variable is @code{t}, so the fill commands insist on -two spaces for the end of a sentence, as explained above. @xref{Sentences}. - -@vindex colon-double-space - If the variable @code{colon-double-space} is non-@code{nil}, the -fill commands put two spaces after a colon. - -@vindex fill-nobreak-predicate - The variable @code{fill-nobreak-predicate} is a hook (an abnormal -hook, @pxref{Hooks}) specifying additional conditions where -line-breaking is not allowed. Each function is called with no -arguments, with point at a place where Emacs is considering breaking -the line. If a function returns a non-@code{nil} value, then that's -a bad place to break the line. Two standard functions you can use are -@code{fill-single-word-nobreak-p} (don't break after the first word of -a sentence or before the last) and @code{fill-french-nobreak-p} (don't -break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). - -@node Fill Prefix -@subsection The Fill Prefix - -@cindex fill prefix - To fill a paragraph in which each line starts with a special marker -(which might be a few spaces, giving an indented paragraph), you can use -the @dfn{fill prefix} feature. The fill prefix is a string that Emacs -expects every line to start with, and which is not included in filling. -You can specify a fill prefix explicitly; Emacs can also deduce the -fill prefix automatically (@pxref{Adaptive Fill}). - -@table @kbd -@item C-x . -Set the fill prefix (@code{set-fill-prefix}). -@item M-q -Fill a paragraph using current fill prefix (@code{fill-paragraph}). -@item M-x fill-individual-paragraphs -Fill the region, considering each change of indentation as starting a -new paragraph. -@item M-x fill-nonuniform-paragraphs -Fill the region, considering only paragraph-separator lines as starting -a new paragraph. -@end table - -@kindex C-x . -@findex set-fill-prefix - To specify a fill prefix for the current buffer, move to a line that -starts with the desired prefix, put point at the end of the prefix, -and type @w{@kbd{C-x .}}@: (@code{set-fill-prefix}). (That's a period -after the @kbd{C-x}.) To turn off the fill prefix, specify an empty -prefix: type @w{@kbd{C-x .}}@: with point at the beginning of a line. - - When a fill prefix is in effect, the fill commands remove the fill -prefix from each line of the paragraph before filling and insert it on -each line after filling. (The beginning of the first line of the -paragraph is left unchanged, since often that is intentionally -different.) Auto Fill mode also inserts the fill prefix automatically -when it makes a new line. The @kbd{C-o} command inserts the fill -prefix on new lines it creates, when you use it at the beginning of a -line (@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes -the prefix (if it occurs) after the newline that it deletes -(@pxref{Indentation}). - - For example, if @code{fill-column} is 40 and you set the fill prefix -to @samp{;; }, then @kbd{M-q} in the following text - -@example -;; This is an -;; example of a paragraph -;; inside a Lisp-style comment. -@end example - -@noindent -produces this: - -@example -;; This is an example of a paragraph -;; inside a Lisp-style comment. -@end example - - Lines that do not start with the fill prefix are considered to start -paragraphs, both in @kbd{M-q} and the paragraph commands; this gives -good results for paragraphs with hanging indentation (every line -indented except the first one). Lines which are blank or indented once -the prefix is removed also separate or start paragraphs; this is what -you want if you are writing multi-paragraph comments with a comment -delimiter on each line. - -@findex fill-individual-paragraphs - You can use @kbd{M-x fill-individual-paragraphs} to set the fill -prefix for each paragraph automatically. This command divides the -region into paragraphs, treating every change in the amount of -indentation as the start of a new paragraph, and fills each of these -paragraphs. Thus, all the lines in one ``paragraph'' have the same -amount of indentation. That indentation serves as the fill prefix for -that paragraph. - -@findex fill-nonuniform-paragraphs - @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides -the region into paragraphs in a different way. It considers only -paragraph-separating lines (as defined by @code{paragraph-separate}) as -starting a new paragraph. Since this means that the lines of one -paragraph may have different amounts of indentation, the fill prefix -used is the smallest amount of indentation of any of the lines of the -paragraph. This gives good results with styles that indent a paragraph's -first line more or less that the rest of the paragraph. - -@vindex fill-prefix - The fill prefix is stored in the variable @code{fill-prefix}. Its value -is a string, or @code{nil} when there is no fill prefix. This is a -per-buffer variable; altering the variable affects only the current buffer, -but there is a default value which you can change as well. @xref{Locals}. - - The @code{indentation} text property provides another way to control -the amount of indentation paragraphs receive. @xref{Format Indentation}. - -@node Adaptive Fill -@subsection Adaptive Filling - -@cindex adaptive filling - The fill commands can deduce the proper fill prefix for a paragraph -automatically in certain cases: either whitespace or certain punctuation -characters at the beginning of a line are propagated to all lines of the -paragraph. - - If the paragraph has two or more lines, the fill prefix is taken from -the paragraph's second line, but only if it appears on the first line as -well. - - If a paragraph has just one line, fill commands @emph{may} take a -prefix from that line. The decision is complicated because there are -three reasonable things to do in such a case: - -@itemize @bullet -@item -Use the first line's prefix on all the lines of the paragraph. - -@item -Indent subsequent lines with whitespace, so that they line up under the -text that follows the prefix on the first line, but don't actually copy -the prefix from the first line. - -@item -Don't do anything special with the second and following lines. -@end itemize - - All three of these styles of formatting are commonly used. So the -fill commands try to determine what you would like, based on the prefix -that appears and on the major mode. Here is how. - -@vindex adaptive-fill-first-line-regexp - If the prefix found on the first line matches -@code{adaptive-fill-first-line-regexp}, or if it appears to be a -comment-starting sequence (this depends on the major mode), then the -prefix found is used for filling the paragraph, provided it would not -act as a paragraph starter on subsequent lines. - - Otherwise, the prefix found is converted to an equivalent number of -spaces, and those spaces are used as the fill prefix for the rest of the -lines, provided they would not act as a paragraph starter on subsequent -lines. - - In Text mode, and other modes where only blank lines and page -delimiters separate paragraphs, the prefix chosen by adaptive filling -never acts as a paragraph starter, so it can always be used for filling. - -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp - The variable @code{adaptive-fill-regexp} determines what kinds of line -beginnings can serve as a fill prefix: any characters at the start of -the line that match this regular expression are used. If you set the -variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is -never chosen automatically. - -@vindex adaptive-fill-function - You can specify more complex ways of choosing a fill prefix -automatically by setting the variable @code{adaptive-fill-function} to a -function. This function is called with point after the left margin of a -line, and it should return the appropriate fill prefix based on that -line. If it returns @code{nil}, @code{adaptive-fill-regexp} gets -a chance to find a prefix. - -@node Refill -@subsection Refill Mode -@cindex refilling text, word processor style -@cindex modes, Refill -@cindex Refill minor mode - - Refill minor mode provides support for keeping paragraphs filled as -you type or modify them in other ways. It provides an effect similar -to typical word processor behavior. This works by running a -paragraph-filling command at suitable times. - - To toggle the use of Refill mode in the current buffer, type -@kbd{M-x refill-mode}. When you are typing text, only characters -which normally trigger auto filling, like the space character, will -trigger refilling. This is to avoid making it too slow. Apart from -self-inserting characters, other commands which modify the text cause -refilling. - - The current implementation is preliminary and not robust. You can -get better ``line wrapping'' behavior using Longlines mode. -@xref{Longlines}. However, Longlines mode has an important -side-effect: the newlines that it inserts for you are not saved to -disk, so the files that you make with Longlines mode will appear to be -completely unfilled if you edit them without Longlines mode. - -@node Longlines -@subsection Long Lines Mode -@cindex refilling text, word processor style -@cindex modes, Long Lines -@cindex word wrap -@cindex Long Lines minor mode - - Sometimes, you may come across ``unfilled'' text files, which Emacs -normally displays as a bunch of extremely long lines. Comfortably -reading and editing such files normally requires ``word wrap'', a -feature that breaks up each long text line into multiple screen lines -in a readable manner---by putting the breaks at word boundaries. Many -text editors, such as those built into many web browsers, perform word -wrapping by default. - - There are two different minor modes in Emacs that perform word -wrapping. The first is Visual Line mode, which does it by altering -the behavior of screen line continuation. @xref{Visual Line Mode}, -for information about Visual Line mode. - -@findex longlines-mode - Instead of using Visual Line mode, you can use a minor mode called -Long Lines mode. Long Lines mode wraps lines by inserting or deleting -@dfn{soft newlines} as you type (@pxref{Hard and Soft Newlines}). -These soft newlines won't show up when you save the buffer into a -file, or when you copy the text into the kill ring, clipboard, or a -register. Unlike Visual Line mode, Lone Lines mode breaks long lines -at the fill column (@pxref{Fill Commands}), rather than the right -window edge. To enable Long Lines mode, type @kbd{M-x -longlines-mode}. If the text is full of long lines, this also -immediately ``wraps'' them all. - -@findex longlines-auto-wrap - The word wrap performed by Long Lines mode is @emph{not} the same as -ordinary filling (@pxref{Fill Commands}). It does not contract -multiple spaces into a single space, recognize fill prefixes -(@pxref{Fill Prefix}), or perform adaptive filling (@pxref{Adaptive -Fill}). The reason for this is that a wrapped line is still, -conceptually, a single line. Each soft newline is equivalent to -exactly one space in that long line, and vice versa. However, you can -still call filling functions such as @kbd{M-q}, and these will work as -expected, inserting soft newlines that won't show up on disk or when -the text is copied. You can even rely entirely on the normal fill -commands by turning off automatic line wrapping, with @kbd{C-u M-x -longlines-auto-wrap}. To turn automatic line wrapping back on, type -@kbd{M-x longlines-auto-wrap}. - -@findex longlines-show-hard-newlines - Type @kbd{RET} to insert a hard newline, one which automatic -refilling will not remove. If you want to see where all the hard -newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will -mark each hard newline with a special symbol. The same command with a -prefix argument turns this display off. - - Long Lines mode does not change normal text files that are already -filled, since the existing newlines are considered hard newlines. -Before Long Lines can do anything, you need to transform each -paragraph into a long line. One way is to set @code{fill-column} to a -large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs, -and then set @code{fill-column} back to its original value. - -@node Case -@section Case Conversion Commands -@cindex case conversion - - Emacs has commands for converting either a single word or any arbitrary -range of text to upper case or to lower case. - -@table @kbd -@item M-l -Convert following word to lower case (@code{downcase-word}). -@item M-u -Convert following word to upper case (@code{upcase-word}). -@item M-c -Capitalize the following word (@code{capitalize-word}). -@item C-x C-l -Convert region to lower case (@code{downcase-region}). -@item C-x C-u -Convert region to upper case (@code{upcase-region}). -@end table - -@kindex M-l -@kindex M-u -@kindex M-c -@cindex words, case conversion -@cindex converting text to upper or lower case -@cindex capitalizing words -@findex downcase-word -@findex upcase-word -@findex capitalize-word - The word conversion commands are the most useful. @kbd{M-l} -(@code{downcase-word}) converts the word after point to lower case, moving -past it. Thus, repeating @kbd{M-l} converts successive words. -@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while -@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word -into upper case and the rest into lower case. All these commands convert -several words at once if given an argument. They are especially convenient -for converting a large amount of text from all upper case to mixed case, -because you can move through the text using @kbd{M-l}, @kbd{M-u} or -@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead -to skip a word. - - When given a negative argument, the word case conversion commands apply -to the appropriate number of words before point, but do not move point. -This is convenient when you have just typed a word in the wrong case: you -can give the case conversion command and continue typing. - - If a word case conversion command is given in the middle of a word, -it applies only to the part of the word which follows point. (This is -comparable to what @kbd{M-d} (@code{kill-word}) does.) With a -negative argument, case conversion applies only to the part of the -word before point. - -@kindex C-x C-l -@kindex C-x C-u -@findex downcase-region -@findex upcase-region - The other case conversion commands are @kbd{C-x C-u} -(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which -convert everything between point and mark to the specified case. Point and -mark do not move. - - The region case conversion commands @code{upcase-region} and -@code{downcase-region} are normally disabled. This means that they ask -for confirmation if you try to use them. When you confirm, you may -enable the command, which means it will not ask for confirmation again. -@xref{Disabling}. - -@node Text Mode -@section Text Mode -@cindex Text mode -@cindex mode, Text -@findex text-mode - - When you edit files of text in a human language, it's more convenient -to use Text mode rather than Fundamental mode. To enter Text mode, type -@kbd{M-x text-mode}. - - In Text mode, only blank lines and page delimiters separate -paragraphs. As a result, paragraphs can be indented, and adaptive -filling determines what indentation to use when filling a paragraph. -@xref{Adaptive Fill}. - -@kindex TAB @r{(Text mode)} - Text mode defines @key{TAB} to run @code{indent-relative} -(@pxref{Indentation}), so that you can conveniently indent a line like -the previous line. - - Text mode turns off the features concerned with comments except when -you explicitly invoke them. It changes the syntax table so that -single-quotes are considered part of words. However, if a word starts -with single-quotes, these are treated as a prefix for purposes such as -capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into -@samp{'Hello'}, as expected. - -@cindex Paragraph-Indent Text mode -@cindex mode, Paragraph-Indent Text -@findex paragraph-indent-text-mode -@findex paragraph-indent-minor-mode - If you indent the first lines of paragraphs, then you should use -Paragraph-Indent Text mode rather than Text mode. In this mode, you -do not need to have blank lines between paragraphs, because the -first-line indentation is sufficient to start a paragraph; however -paragraphs in which every line is indented are not supported. Use -@kbd{M-x paragraph-indent-text-mode} to enter this mode. Use @kbd{M-x -paragraph-indent-minor-mode} to enable an equivalent minor mode in -situations where you can't change the major mode---in mail -composition, for instance. - -@kindex M-TAB @r{(Text mode)} - Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} -as the command @code{ispell-complete-word}, which performs completion -of the partial word in the buffer before point, using the spelling -dictionary as the space of possible words. @xref{Spelling}. If your -window manager defines @kbd{M-@key{TAB}} to switch windows, you can -type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}. - -@vindex text-mode-hook - Entering Text mode runs the hook @code{text-mode-hook}. Other major -modes related to Text mode also run this hook, followed by hooks of -their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{} -mode, Outline mode, and Mail mode. Hook functions on -@code{text-mode-hook} can look at the value of @code{major-mode} to see -which of these modes is actually being entered. @xref{Hooks}. - -@node Outline Mode -@section Outline Mode -@cindex Outline mode -@cindex mode, Outline -@cindex invisible lines - -@findex outline-mode -@findex outline-minor-mode -@vindex outline-minor-mode-prefix - Outline mode is a major mode much like Text mode but intended for -editing outlines. It allows you to make parts of the text temporarily -invisible so that you can see the outline structure. Type @kbd{M-x -outline-mode} to switch to Outline mode as the major mode of the current -buffer. - - When Outline mode makes a line invisible, the line does not appear -on the screen. The screen appears exactly as if the invisible line -were deleted, except that an ellipsis (three periods in a row) appears -at the end of the previous visible line. (Multiple consecutive -invisible lines produce just one ellipsis.) - - Editing commands that operate on lines, such as @kbd{C-n} and -@kbd{C-p}, treat the text of the invisible line as part of the previous -visible line. Killing the ellipsis at the end of a visible line -really kills all the following invisible lines. - - Outline minor mode provides the same commands as the major mode, -Outline mode, but you can use it in conjunction with other major modes. -Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in -the current buffer. You can also specify this in the text of a file, -with a file local variable of the form @samp{mode: outline-minor} -(@pxref{File Variables}). - -@kindex C-c @@ @r{(Outline minor mode)} - The major mode, Outline mode, provides special key bindings on the -@kbd{C-c} prefix. Outline minor mode provides similar bindings with -@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the -major mode's special commands. (The variable -@code{outline-minor-mode-prefix} controls the prefix used.) - -@vindex outline-mode-hook - Entering Outline mode runs the hook @code{text-mode-hook} followed by -the hook @code{outline-mode-hook} (@pxref{Hooks}). - -@menu -* Format: Outline Format. What the text of an outline looks like. -* Motion: Outline Motion. Special commands for moving through - outlines. -* Visibility: Outline Visibility. Commands to control what is visible. -* Views: Outline Views. Outlines and multiple views. -* Foldout:: Folding means zooming in on outlines. -@end menu - -@node Outline Format -@subsection Format of Outlines - -@cindex heading lines (Outline mode) -@cindex body lines (Outline mode) - Outline mode assumes that the lines in the buffer are of two types: -@dfn{heading lines} and @dfn{body lines}. A heading line represents a -topic in the outline. Heading lines start with one or more stars; the -number of stars determines the depth of the heading in the outline -structure. Thus, a heading line with one star is a major topic; all the -heading lines with two stars between it and the next one-star heading -are its subtopics; and so on. Any line that is not a heading line is a -body line. Body lines belong with the preceding heading line. Here is -an example: - -@example -* Food -This is the body, -which says something about the topic of food. - -** Delicious Food -This is the body of the second-level header. - -** Distasteful Food -This could have -a body too, with -several lines. - -*** Dormitory Food - -* Shelter -Another first-level topic with its header line. -@end example - - A heading line together with all following body lines is called -collectively an @dfn{entry}. A heading line together with all following -deeper heading lines and their body lines is called a @dfn{subtree}. - -@vindex outline-regexp - You can customize the criterion for distinguishing heading lines by -setting the variable @code{outline-regexp}. (The recommended ways to -do this are in a major mode function or with a file local variable.) -Any line whose beginning has a match for this regexp is considered a -heading line. Matches that start within a line (not at the left -margin) do not count. - - The length of the matching text determines the level of the heading; -longer matches make a more deeply nested level. Thus, for example, if -a text formatter has commands @samp{@@chapter}, @samp{@@section} and -@samp{@@subsection} to divide the document into chapters and sections, -you could make those lines count as heading lines by setting -@code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. Note -the trick: the two words @samp{chapter} and @samp{section} are equally -long, but by defining the regexp to match only @samp{chap} we ensure -that the length of the text matched on a chapter heading is shorter, -so that Outline mode will know that sections are contained in -chapters. This works as long as no other command starts with -@samp{@@chap}. - -@vindex outline-level - You can explicitly specify a rule for calculating the level of a -heading line by setting the variable @code{outline-level}. The value -of @code{outline-level} should be a function that takes no arguments -and returns the level of the current heading. The recommended ways to -set this variable are in a major mode command or with a file local -variable. - -@node Outline Motion -@subsection Outline Motion Commands - - Outline mode provides special motion commands that move backward and -forward to heading lines. - -@table @kbd -@item C-c C-n -Move point to the next visible heading line -(@code{outline-next-visible-heading}). -@item C-c C-p -Move point to the previous visible heading line -(@code{outline-previous-visible-heading}). -@item C-c C-f -Move point to the next visible heading line at the same level -as the one point is on (@code{outline-forward-same-level}). -@item C-c C-b -Move point to the previous visible heading line at the same level -(@code{outline-backward-same-level}). -@item C-c C-u -Move point up to a lower-level (more inclusive) visible heading line -(@code{outline-up-heading}). -@end table - -@findex outline-next-visible-heading -@findex outline-previous-visible-heading -@kindex C-c C-n @r{(Outline mode)} -@kindex C-c C-p @r{(Outline mode)} - @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next -heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves -similarly backward. Both accept numeric arguments as repeat counts. The -names emphasize that invisible headings are skipped, but this is not really -a special feature. All editing commands that look for lines ignore the -invisible lines automatically. - -@findex outline-up-heading -@findex outline-forward-same-level -@findex outline-backward-same-level -@kindex C-c C-f @r{(Outline mode)} -@kindex C-c C-b @r{(Outline mode)} -@kindex C-c C-u @r{(Outline mode)} - More powerful motion commands understand the level structure of headings. -@kbd{C-c C-f} (@code{outline-forward-same-level}) and -@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one -heading line to another visible heading at the same depth in -the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves -backward to another heading that is less deeply nested. - -@node Outline Visibility -@subsection Outline Visibility Commands - - The other special commands of outline mode are used to make lines visible -or invisible. Their names all start with @code{hide} or @code{show}. -Most of them fall into pairs of opposites. They are not undoable; instead, -you can undo right past them. Making lines visible or invisible is simply -not recorded by the undo mechanism. - - Many of these commands act on the ``current'' heading line. If -point is on a heading line, that is the current heading line; if point -is on a body line, the current heading line is the nearest preceding -header line. - -@table @kbd -@item C-c C-c -Make the current heading line's body invisible (@code{hide-entry}). -@item C-c C-e -Make the current heading line's body visible (@code{show-entry}). -@item C-c C-d -Make everything under the current heading invisible, not including the -heading itself (@code{hide-subtree}). -@item C-c C-s -Make everything under the current heading visible, including body, -subheadings, and their bodies (@code{show-subtree}). -@item C-c C-l -Make the body of the current heading line, and of all its subheadings, -invisible (@code{hide-leaves}). -@item C-c C-k -Make all subheadings of the current heading line, at all levels, -visible (@code{show-branches}). -@item C-c C-i -Make immediate subheadings (one level down) of the current heading -line visible (@code{show-children}). -@item C-c C-t -Make all body lines in the buffer invisible (@code{hide-body}). -@item C-c C-a -Make all lines in the buffer visible (@code{show-all}). -@item C-c C-q -Hide everything except the top @var{n} levels of heading lines -(@code{hide-sublevels}). -@item C-c C-o -Hide everything except for the heading or body that point is in, plus -the headings leading up from there to the top level of the outline -(@code{hide-other}). -@end table - -@findex hide-entry -@findex show-entry -@kindex C-c C-c @r{(Outline mode)} -@kindex C-c C-e @r{(Outline mode)} - Two commands that are exact opposites are @kbd{C-c C-c} -(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They apply -to the body lines directly following the current heading line. -Subheadings and their bodies are not affected. - -@findex hide-subtree -@findex show-subtree -@kindex C-c C-s @r{(Outline mode)} -@kindex C-c C-d @r{(Outline mode)} -@cindex subtree (Outline mode) - Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) -and @kbd{C-c C-s} (@code{show-subtree}). Both apply to the current -heading line's @dfn{subtree}: its body, all its subheadings, both -direct and indirect, and all of their bodies. In other words, the -subtree contains everything following the current heading line, up to -and not including the next heading of the same or higher rank. - -@findex hide-leaves -@findex show-branches -@kindex C-c C-l @r{(Outline mode)} -@kindex C-c C-k @r{(Outline mode)} - Intermediate between a visible subtree and an invisible one is having -all the subheadings visible but none of the body. There are two -commands for doing this, depending on whether you want to hide the -bodies or make the subheadings visible. They are @kbd{C-c C-l} -(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}). - -@kindex C-c C-i @r{(Outline mode)} -@findex show-children - A little weaker than @code{show-branches} is @kbd{C-c C-i} -(@code{show-children}). It makes just the direct subheadings -visible---those one level down. Deeper subheadings remain invisible, if -they were invisible. - -@findex hide-body -@findex show-all -@kindex C-c C-t @r{(Outline mode)} -@kindex C-c C-a @r{(Outline mode)} - Two commands have a blanket effect on the whole file. @kbd{C-c C-t} -(@code{hide-body}) makes all body lines invisible, so that you see just -the outline structure (as a special exception, it will not hide lines -at the top of the file, preceding the first header line, even though -these are technically body lines). @kbd{C-c C-a} (@code{show-all}) -makes all lines visible. These commands can be thought of as a pair -of opposites even though @kbd{C-c C-a} applies to more than just body -lines. - -@findex hide-sublevels -@kindex C-c C-q @r{(Outline mode)} - The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the -top level headings. With a numeric argument @var{n}, it hides everything -except the top @var{n} levels of heading lines. - -@findex hide-other -@kindex C-c C-o @r{(Outline mode)} - The command @kbd{C-c C-o} (@code{hide-other}) hides everything except -the heading and body text that point is in, plus its parents (the headers -leading up from there to top level in the outline) and the top level -headings. - -@findex reveal-mode - When incremental search finds text that is hidden by Outline mode, -it makes that part of the buffer visible. If you exit the search -at that position, the text remains visible. You can also -automatically make text visible as you navigate in it by using -@kbd{M-x reveal-mode}. - -@node Outline Views -@subsection Viewing One Outline in Multiple Views - -@cindex multiple views of outline -@cindex views of an outline -@cindex outline with multiple views -@cindex indirect buffers and outlines - You can display two views of a single outline at the same time, in -different windows. To do this, you must create an indirect buffer using -@kbd{M-x make-indirect-buffer}. The first argument of this command is -the existing outline buffer name, and its second argument is the name to -use for the new indirect buffer. @xref{Indirect Buffers}. - - Once the indirect buffer exists, you can display it in a window in the -normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline -mode commands to show and hide parts of the text operate on each buffer -independently; as a result, each buffer can have its own view. If you -want more than two views on the same outline, create additional indirect -buffers. - -@node Foldout -@subsection Folding Editing - -@cindex folding editing - The Foldout package extends Outline mode and Outline minor mode with -``folding'' commands. The idea of folding is that you zoom in on a -nested portion of the outline, while hiding its relatives at higher -levels. - - Consider an Outline mode buffer with all the text and subheadings under -level-1 headings hidden. To look at what is hidden under one of these -headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose -the body, or @kbd{C-c C-i} to expose the child (level-2) headings. - -@kindex C-c C-z -@findex foldout-zoom-subtree - With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). -This exposes the body and child subheadings, and narrows the buffer so -that only the @w{level-1} heading, the body and the level-2 headings are -visible. Now to look under one of the level-2 headings, position the -cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body -and its level-3 child subheadings and narrows the buffer again. Zooming -in on successive subheadings can be done as much as you like. A string -in the mode line shows how deep you've gone. - - When zooming in on a heading, to see only the child subheadings specify -a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children -can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2 -C-c C-z} exposes two levels of child subheadings. Alternatively, the -body can be specified with a negative argument: @kbd{M-- C-c C-z}. The -whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x -show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. - - While you're zoomed in, you can still use Outline mode's exposure and -hiding functions without disturbing Foldout. Also, since the buffer is -narrowed, ``global'' editing actions will only affect text under the -zoomed-in heading. This is useful for restricting changes to a -particular chapter or section of your document. - -@kindex C-c C-x -@findex foldout-exit-fold - To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). -This hides all the text and subheadings under the top-level heading and -returns you to the previous view of the buffer. Specifying a numeric -argument exits that many levels of folds. Specifying a zero argument -exits all folds. - - To cancel the narrowing of a fold without hiding the text and -subheadings, specify a negative argument. For example, @kbd{M--2 C-c -C-x} exits two folds and leaves the text and subheadings exposed. - - Foldout mode also provides mouse commands for entering and exiting -folds, and for showing and hiding text: - -@table @asis -@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on -@itemize @w{} -@item -single click: expose body. -@item -double click: expose subheadings. -@item -triple click: expose body and subheadings. -@item -quad click: expose entire subtree. -@end itemize -@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold -@itemize @w{} -@item -single click: hide subtree. -@item -double click: exit fold and hide text. -@item -triple click: exit fold without hiding text. -@item -quad click: exit all folds and hide text. -@end itemize -@end table - -@vindex foldout-mouse-modifiers - You can specify different modifier keys (instead of -@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if -you have already loaded the @file{foldout.el} library, you must reload -it in order for this to take effect. - - To use the Foldout package, you can type @kbd{M-x load-library -@key{RET} foldout @key{RET}}; or you can arrange for to do that -automatically by putting this in your @file{.emacs} file: - -@example -(eval-after-load "outline" '(require 'foldout)) -@end example - -@node TeX Mode -@section @TeX{} Mode -@cindex @TeX{} mode -@cindex La@TeX{} mode -@cindex Sli@TeX{} mode -@cindex Doc@TeX{} mode -@cindex mode, @TeX{} -@cindex mode, La@TeX{} -@cindex mode, Sli@TeX{} -@cindex mode, Doc@TeX{} -@findex tex-mode -@findex plain-tex-mode -@findex latex-mode -@findex slitex-mode -@findex doctex-mode -@findex bibtex-mode - - Emacs provides special major modes for editing files written in -@TeX{} and its related formats. @TeX{} is a powerful text formatter -written by Donald Knuth; like GNU Emacs, it is free software. -La@TeX{} is a simplified input format for @TeX{}, implemented using -@TeX{} macros. Doc@TeX{} is a special file format in which the -La@TeX{} sources are written, combining sources with documentation. -Sli@TeX{} is an obsolete special form of La@TeX{}.@footnote{It has -been replaced by the @samp{slides} document class, which comes with -La@TeX{}.} - -@vindex tex-default-mode - @TeX{} mode has four variants: Plain @TeX{} mode, La@TeX{} mode, -Doc@TeX{} mode, and Sli@TeX{} mode. These distinct major modes differ -only slightly, and are designed for editing the four different -formats. Emacs selects the appropriate mode by looking at the -contents of the buffer. (This is done by the @code{tex-mode} command, -which is normally called automatically when you visit a @TeX{}-like -file. @xref{Choosing Modes}.) If the contents are insufficient to -determine this, Emacs chooses the mode specified by the variable -@code{tex-default-mode}; its default value is @code{latex-mode}. If -Emacs does not guess right, you can select the correct variant of -@TeX{} mode using the command @kbd{M-x plain-tex-mode}, @kbd{M-x -latex-mode}, @kbd{M-x slitex-mode}, or @kbd{doctex-mode}. - - Emacs also provides Bib@TeX{} mode, a major mode for editing -Bib@TeX{} files. Bib@TeX{} is a tool for storing and formatting -bibliographic references, which is commonly used together with -La@TeX{}. In addition, the Ref@TeX{} package provides a minor mode -which can be used in conjunction with La@TeX{} mode to manage -bibliographic references. @inforef{Top,, reftex}. - -@menu -* Editing: TeX Editing. Special commands for editing in TeX mode. -* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. -* Printing: TeX Print. Commands for printing part of a file with TeX. -* Misc: TeX Misc. Customization of TeX mode, and related features. -@end menu - -@node TeX Editing -@subsection @TeX{} Editing Commands - -@table @kbd -@item " -Insert, according to context, either @samp{``} or @samp{"} or -@samp{''} (@code{tex-insert-quote}). -@item C-j -Insert a paragraph break (two newlines) and check the previous -paragraph for unbalanced braces or dollar signs -(@code{tex-terminate-paragraph}). -@item M-x tex-validate-region -Check each paragraph in the region for unbalanced braces or dollar signs. -@item C-c @{ -Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). -@item C-c @} -Move forward past the next unmatched close brace (@code{up-list}). -@end table - -@findex tex-insert-quote -@kindex " @r{(@TeX{} mode)} - In @TeX{}, the character @samp{"} is not normally used; instead, -quotations begin with @samp{``} and end with @samp{''}. For -convenience, @TeX{} mode overrides the normal meaning of the key -@kbd{"} with a command that inserts a pair of single-quotes or -backquotes (@code{tex-insert-quote}). To be precise, it inserts -@samp{``} after whitespace or an open brace, @samp{"} after a -backslash, and @samp{''} after any other character. - - As a special exception, if you type @kbd{"} when the text before -point is either @samp{``} or @samp{''}, Emacs replaces that preceding -text with a single @samp{"} character. You can therefore type -@kbd{""} to insert @samp{"}, should you ever need to do so. (You can -also use @kbd{C-q "} to insert this character.) - - To disable the @kbd{"} expansion feature, eliminate that binding in -the local map (@pxref{Key Bindings}). - - In @TeX{} mode, @samp{$} has a special syntax code which attempts to -understand the way @TeX{} math mode delimiters match. When you insert a -@samp{$} that is meant to exit math mode, the position of the matching -@samp{$} that entered math mode is displayed for a second. This is the -same feature that displays the open brace that matches a close brace that -is inserted. However, there is no way to tell whether a @samp{$} enters -math mode or leaves it; so when you insert a @samp{$} that enters math -mode, the previous @samp{$} position is shown as if it were a match, even -though they are actually unrelated. - -@findex tex-insert-braces -@kindex C-c @{ @r{(@TeX{} mode)} -@findex up-list -@kindex C-c @} @r{(@TeX{} mode)} - @TeX{} uses braces as delimiters that must match. Some users prefer -to keep braces balanced at all times, rather than inserting them -singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of -braces. It leaves point between the two braces so you can insert the -text that belongs inside. Afterward, use the command @kbd{C-c @}} -(@code{up-list}) to move forward past the close brace. - -@findex tex-validate-region -@findex tex-terminate-paragraph -@kindex C-j @r{(@TeX{} mode)} - There are two commands for checking the matching of braces. @kbd{C-j} -(@code{tex-terminate-paragraph}) checks the paragraph before point, and -inserts two newlines to start a new paragraph. It outputs a message in -the echo area if any mismatch is found. @kbd{M-x tex-validate-region} -checks a region, paragraph by paragraph. The errors are listed in the -@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in -that buffer to go to a particular mismatch. - - Note that Emacs commands count square brackets and parentheses in -@TeX{} mode, not just braces. This is not strictly correct for the -purpose of checking @TeX{} syntax. However, parentheses and square -brackets are likely to be used in text as matching delimiters, and it -is useful for the various motion commands and automatic match display -to work with them. - -@node LaTeX Editing -@subsection La@TeX{} Editing Commands - - La@TeX{} mode (and its obsolete variant, Sli@TeX{} mode) provide a -few extra features not applicable to plain @TeX{}: - -@table @kbd -@item C-c C-o -Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position -point on a line between them (@code{tex-latex-block}). -@item C-c C-e -Close the innermost La@TeX{} block not yet closed -(@code{tex-close-latex-block}). -@end table - -@findex tex-latex-block -@kindex C-c C-o @r{(La@TeX{} mode)} -@vindex latex-block-names - In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to -group blocks of text. To insert a @samp{\begin} and a matching -@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c -C-o} (@code{tex-latex-block}). A blank line is inserted between the -two, and point is left there. You can use completion when you enter the -block type; to specify additional block type names beyond the standard -list, set the variable @code{latex-block-names}. For example, here's -how to add @samp{theorem}, @samp{corollary}, and @samp{proof}: - -@example -(setq latex-block-names '("theorem" "corollary" "proof")) -@end example - -@findex tex-close-latex-block -@kindex C-c C-e @r{(La@TeX{} mode)} - In La@TeX{} input, @samp{\begin} and @samp{\end} commands must -balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to -insert automatically a matching @samp{\end} to match the last unmatched -@samp{\begin}. It indents the @samp{\end} to match the corresponding -@samp{\begin}. It inserts a newline after @samp{\end} if point is at -the beginning of a line. - -@node TeX Print -@subsection @TeX{} Printing Commands - - You can invoke @TeX{} as an inferior of Emacs on either the entire -contents of the buffer or just a region at a time. Running @TeX{} in -this way on just one chapter is a good way to see what your changes -look like without taking the time to format the entire file. - -@table @kbd -@item C-c C-r -Invoke @TeX{} on the current region, together with the buffer's header -(@code{tex-region}). -@item C-c C-b -Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). -@item C-c @key{TAB} -Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). -@item C-c C-f -Invoke @TeX{} on the current file (@code{tex-file}). -@item C-c C-l -Recenter the window showing output from the inferior @TeX{} so that -the last line can be seen (@code{tex-recenter-output-buffer}). -@item C-c C-k -Kill the @TeX{} subprocess (@code{tex-kill-job}). -@item C-c C-p -Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-print}). -@item C-c C-v -Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c -C-f} command (@code{tex-view}). -@item C-c C-q -Show the printer queue (@code{tex-show-print-queue}). -@item C-c C-c -Invoke some other compilation command on the entire current buffer -(@code{tex-compile}). -@end table - -@findex tex-buffer -@kindex C-c C-b @r{(@TeX{} mode)} -@findex tex-print -@kindex C-c C-p @r{(@TeX{} mode)} -@findex tex-view -@kindex C-c C-v @r{(@TeX{} mode)} -@findex tex-show-print-queue -@kindex C-c C-q @r{(@TeX{} mode)} - You can pass the current buffer through an inferior @TeX{} by means of -@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a -temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}). -Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to -view the progress of your output towards being printed. If your terminal -has the ability to display @TeX{} output files, you can preview the -output on the terminal with @kbd{C-c C-v} (@code{tex-view}). - -@cindex @env{TEXINPUTS} environment variable -@vindex tex-directory - You can specify the directory to use for running @TeX{} by setting the -variable @code{tex-directory}. @code{"."} is the default value. If -your environment variable @env{TEXINPUTS} contains relative directory -names, or if your files contains @samp{\input} commands with relative -file names, then @code{tex-directory} @emph{must} be @code{"."} or you -will get the wrong results. Otherwise, it is safe to specify some other -directory, such as @code{"/tmp"}. - -@vindex tex-run-command -@vindex latex-run-command -@vindex slitex-run-command -@vindex tex-dvi-print-command -@vindex tex-dvi-view-command -@vindex tex-show-queue-command - If you want to specify which shell commands are used in the inferior @TeX{}, -you can do so by setting the values of the variables @code{tex-run-command}, -@code{latex-run-command}, @code{slitex-run-command}, -@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and -@code{tex-show-queue-command}. The default values may -(or may not) be appropriate for your system. - - Normally, the file name given to these commands comes at the end of -the command string; for example, @samp{latex @var{filename}}. In some -cases, however, the file name needs to be embedded in the command; an -example is when you need to provide the file name as an argument to one -command whose output is piped to another. You can specify where to put -the file name with @samp{*} in the command string. For example, - -@example -(setq tex-dvi-print-command "dvips -f * | lpr") -@end example - -@findex tex-kill-job -@kindex C-c C-k @r{(@TeX{} mode)} -@findex tex-recenter-output-buffer -@kindex C-c C-l @r{(@TeX{} mode)} - The terminal output from @TeX{}, including any error messages, appears -in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can -switch to this buffer and feed it input (this works as in Shell mode; -@pxref{Interactive Shell}). Without switching to this buffer you can -scroll it so that its last line is visible by typing @kbd{C-c -C-l}. - - Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if -you see that its output is no longer useful. Using @kbd{C-c C-b} or -@kbd{C-c C-r} also kills any @TeX{} process still running. - -@findex tex-region -@kindex C-c C-r @r{(@TeX{} mode)} - You can also pass an arbitrary region through an inferior @TeX{} by typing -@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files -of @TeX{} input contain commands at the beginning to set parameters and -define macros, without which no later part of the file will format -correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a -part of the file as containing essential commands; it is included before -the specified region as part of the input to @TeX{}. The designated part -of the file is called the @dfn{header}. - -@cindex header (@TeX{} mode) - To indicate the bounds of the header in Plain @TeX{} mode, you insert two -special strings in the file. Insert @samp{%**start of header} before the -header, and @samp{%**end of header} after it. Each string must appear -entirely on one line, but there may be other text on the line before or -after. The lines containing the two strings are included in the header. -If @samp{%**start of header} does not appear within the first 100 lines of -the buffer, @kbd{C-c C-r} assumes that there is no header. - - In La@TeX{} mode, the header begins with @samp{\documentclass} or -@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These -are commands that La@TeX{} requires you to use in any case, so nothing -special needs to be done to identify the header. - -@findex tex-file -@kindex C-c C-f @r{(@TeX{} mode)} - The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their -work in a temporary directory, and do not have available any of the auxiliary -files needed by @TeX{} for cross-references; these commands are generally -not suitable for running the final copy in which all of the cross-references -need to be correct. - - When you want the auxiliary files for cross references, use @kbd{C-c -C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, -in that file's directory. Before running @TeX{}, it offers to save any -modified buffers. Generally, you need to use (@code{tex-file}) twice to -get the cross-references right. - -@vindex tex-start-options - The value of the variable @code{tex-start-options} specifies -options for the @TeX{} run. - -@vindex tex-start-commands - The value of the variable @code{tex-start-commands} specifies @TeX{} -commands for starting @TeX{}. The default value causes @TeX{} to run -in nonstop mode. To run @TeX{} interactively, set the variable to -@code{""}. - -@vindex tex-main-file - Large @TeX{} documents are often split into several files---one main -file, plus subfiles. Running @TeX{} on a subfile typically does not -work; you have to run it on the main file. In order to make -@code{tex-file} useful when you are editing a subfile, you can set the -variable @code{tex-main-file} to the name of the main file. Then -@code{tex-file} runs @TeX{} on that file. - - The most convenient way to use @code{tex-main-file} is to specify it -in a local variable list in each of the subfiles. @xref{File -Variables}. - -@findex tex-bibtex-file -@kindex C-c TAB @r{(@TeX{} mode)} -@vindex tex-bibtex-command - For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary -file for the current buffer's file. Bib@TeX{} looks up bibliographic -citations in a data base and prepares the cited references for the -bibliography section. The command @kbd{C-c @key{TAB}} -(@code{tex-bibtex-file}) runs the shell command -(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the -current buffer's file. Generally, you need to do @kbd{C-c C-f} -(@code{tex-file}) once to generate the @samp{.aux} file, then do -@kbd{C-c @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} -(@code{tex-file}) twice more to get the cross-references correct. - -@findex tex-compile -@kindex C-c C-c @r{(@TeX{} mode)} - To invoke some other compilation program on the current @TeX{} -buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows -how to pass arguments to many common programs, including -@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can -select your desired compilation program using the standard completion -keys (@pxref{Completion}). - -@node TeX Misc -@subsection @TeX{} Mode Miscellany - -@vindex tex-shell-hook -@vindex tex-mode-hook -@vindex latex-mode-hook -@vindex slitex-mode-hook -@vindex plain-tex-mode-hook - Entering any variant of @TeX{} mode runs the hooks -@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either -@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or -@code{slitex-mode-hook}, whichever is appropriate. Starting the -@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. - -@findex iso-iso2tex -@findex iso-tex2iso -@findex iso-iso2gtex -@findex iso-gtex2iso -@cindex Latin-1 @TeX{} encoding -@cindex @TeX{} encoding - The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x -iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert -between Latin-1 encoded files and @TeX{}-encoded equivalents. -@ignore -@c Too cryptic to be useful, too cryptic for me to make it better -- rms. - They -are included by default in the @code{format-alist} variable, so they -can be used with @kbd{M-x format-find-file}, for instance. -@end ignore - -@ignore @c Not worth documenting if it is only for Czech -- rms. -@findex tildify-buffer -@findex tildify-region -@cindex ties, @TeX{}, inserting -@cindex hard spaces, @TeX{}, inserting - The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} -insert @samp{~} (@dfn{tie}) characters where they are conventionally -required. This is set up for Czech---customize the group -@samp{tildify} for other languages or for other sorts of markup. -@end ignore - -@cindex Ref@TeX{} package -@cindex references, La@TeX{} -@cindex La@TeX{} references - For managing all kinds of references for La@TeX{}, you can use -Ref@TeX{}. @inforef{Top,, reftex}. - -@node HTML Mode -@section SGML, XML, and HTML Modes -@cindex SGML mode -@cindex HTML mode -@cindex XML mode -@cindex mode, SGML -@cindex mode, HTML -@cindex mode, XML -@findex sgml-mode -@findex html-mode -@findex xml-mode - - The major modes for SGML, XML, and HTML provide indentation support -and commands for operating on tags. XML mode is actually identical to -SGML mode (to be precise, @code{xml-mode} is an alias for -@code{sgml-mode}), because XML is a strict subset of SGML. HTML mode -is a slightly customized variant of SGML mode. - -@vindex sgml-xml-mode - In XML, every opening tag must have an explicit closing tag. When -the variable @code{sgml-xml-mode} is non-@code{nil}, the tag insertion -commands described below always insert explicit closing tags as well. -When you visit a file, Emacs determines whether it is XML by examining -the file contents, and sets @code{sgml-xml-mode} accordingly. - -@table @kbd -@item C-c C-n -@kindex C-c C-n @r{(SGML mode)} -@findex sgml-name-char -Interactively specify a special character and insert the SGML -@samp{&}-command for that character. - -@item C-c C-t -@kindex C-c C-t @r{(SGML mode)} -@findex sgml-tag -Interactively specify a tag and its attributes (@code{sgml-tag}). -This command asks you for a tag name and for the attribute values, -then inserts both the opening tag and the closing tag, leaving point -between them. - -With a prefix argument @var{n}, the command puts the tag around the -@var{n} words already present in the buffer after point. Whenever a -region is active, it puts the tag around the region (when Transient -Mark mode is off, it does this when a numeric argument of @minus{}1 is -supplied.) - -@item C-c C-a -@kindex C-c C-a @r{(SGML mode)} -@findex sgml-attributes -Interactively insert attribute values for the current tag -(@code{sgml-attributes}). - -@item C-c C-f -@kindex C-c C-f @r{(SGML mode)} -@findex sgml-skip-tag-forward -Skip across a balanced tag group (which extends from an opening tag -through its corresponding closing tag) (@code{sgml-skip-tag-forward}). -A numeric argument acts as a repeat count. - -@item C-c C-b -@kindex C-c C-b @r{(SGML mode)} -@findex sgml-skip-tag-backward -Skip backward across a balanced tag group (which extends from an -opening tag through its corresponding closing tag) -(@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat -count. - -@item C-c C-d -@kindex C-c C-d @r{(SGML mode)} -@findex sgml-delete-tag -Delete the tag at or after point, and delete the matching tag too -(@code{sgml-delete-tag}). If the tag at or after point is an opening -tag, delete the closing tag too; if it is a closing tag, delete the -opening tag too. - -@item C-c ? @var{tag} @key{RET} -@kindex C-c ? @r{(SGML mode)} -@findex sgml-tag-help -Display a description of the meaning of tag @var{tag} -(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe -the tag at point. - -@item C-c / -@kindex C-c / @r{(SGML mode)} -@findex sgml-close-tag -Insert a close tag for the innermost unterminated tag -(@code{sgml-close-tag}). If called from within a tag or a comment, -close this element instead of inserting a close tag. - -@item C-c 8 -@kindex C-c 8 @r{(SGML mode)} -@findex sgml-name-8bit-mode -Toggle a minor mode in which Latin-1 characters insert the -corresponding SGML commands that stand for them, instead of the -characters themselves (@code{sgml-name-8bit-mode}). - -@item C-c C-v -@kindex C-c C-v @r{(SGML mode)} -@findex sgml-validate -Run a shell command (which you must specify) to validate the current -buffer as SGML (@code{sgml-validate}). - -@item C-c TAB -@kindex C-c TAB @r{(SGML mode)} -@findex sgml-tags-invisible -Toggle the visibility of existing tags in the buffer. This can be -used as a cheap preview. -@end table - -@cindex nXML mode -@cindex mode, nXML -@findex nxml-mode -@cindex XML schema - Emacs also provides a more advanced mode for editing XML -documents, called nXML mode (@code{nxml-mode}). nXML mode is aware of -many existing XML schema, and uses them to provide completion of XML -elements via @kbd{C-@key{RET}} or @kbd{M-@key{TAB}}, as well as -``on-the-fly'' validation of XML, with errors highlighted via Font -Lock (@pxref{Font Lock}). It is described in its own manual. -@xref{Top, nXML Mode,,nxml-mode, nXML Mode}. - -@node Nroff Mode -@section Nroff Mode - -@cindex nroff -@findex nroff-mode - Nroff mode is a mode like Text mode but modified to handle nroff commands -present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It -differs from Text mode in only a few ways. All nroff command lines are -considered paragraph separators, so that filling will never garble the -nroff commands. Pages are separated by @samp{.bp} commands. Comments -start with backslash-doublequote. Also, three special commands are -provided that are not in Text mode: - -@findex forward-text-line -@findex backward-text-line -@findex count-text-lines -@kindex M-n @r{(Nroff mode)} -@kindex M-p @r{(Nroff mode)} -@kindex M-? @r{(Nroff mode)} -@table @kbd -@item M-n -Move to the beginning of the next line that isn't an nroff command -(@code{forward-text-line}). An argument is a repeat count. -@item M-p -Like @kbd{M-n} but move up (@code{backward-text-line}). -@item M-? -Displays in the echo area the number of text lines (lines that are not -nroff commands) in the region (@code{count-text-lines}). -@end table - -@findex electric-nroff-mode - The other feature of Nroff mode is that you can turn on Electric Nroff -mode. This is a minor mode that you can turn on or off with @kbd{M-x -electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each -time you use @key{RET} to end a line that contains an nroff command that -opens a kind of grouping, the matching nroff command to close that -grouping is automatically inserted on the following line. For example, -if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}}, -this inserts the matching command @samp{.)b} on a new line following -point. - - If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}), -heading lines are lines of the form @samp{.H} followed by a number (the -header level). - -@vindex nroff-mode-hook - Entering Nroff mode runs the hook @code{text-mode-hook}, followed by -the hook @code{nroff-mode-hook} (@pxref{Hooks}). - -@node Formatted Text -@section Editing Formatted Text - -@cindex Enriched mode -@cindex mode, Enriched -@cindex formatted text -@cindex WYSIWYG -@cindex word processing - @dfn{Enriched mode} is a minor mode for editing files that contain -formatted text in WYSIWYG fashion, as in a word processor. Currently, -formatted text in Enriched mode can specify fonts, colors, underlining, -margins, and types of filling and justification. In the future, we plan -to implement other formatting features as well. - - Enriched mode is a minor mode (@pxref{Minor Modes}). It is -typically used in conjunction with Text mode (@pxref{Text Mode}), but -you can also use it with other major modes such as Outline mode and -Paragraph-Indent Text mode. - -@cindex text/enriched MIME format - Potentially, Emacs can store formatted text files in various file -formats. Currently, only one format is implemented: @dfn{text/enriched} -format, which is defined by the MIME protocol. @xref{Format -Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual}, -for details of how Emacs recognizes and converts file formats. - - The Emacs distribution contains a formatted text file that can serve as -an example. Its name is @file{etc/enriched.doc}. It contains samples -illustrating all the features described in this section. It also -contains a list of ideas for future enhancements. - -@menu -* Requesting Formatted Text:: Entering and exiting Enriched mode. -* Hard and Soft Newlines:: There are two different kinds of newlines. -* Editing Format Info:: How to edit text properties. -* Faces: Format Faces. Bold, italic, underline, etc. -* Color: Format Colors. Changing the color of text. -* Indent: Format Indentation. Changing the left and right margins. -* Justification: Format Justification. - Centering, setting text flush with the - left or right margin, etc. -* Special: Format Properties. The "special" text properties submenu. -* Forcing Enriched Mode:: How to force use of Enriched mode. -@end menu - -@node Requesting Formatted Text -@subsection Requesting to Edit Formatted Text - - Whenever you visit a file that Emacs saved in the text/enriched -format, Emacs automatically converts the formatting information in the -file into Emacs's own internal format (known as @dfn{text -properties}), and turns on Enriched mode. - -@findex enriched-mode - To create a new file of formatted text, first visit the nonexistent -file, then type @kbd{M-x enriched-mode} before you start inserting text. -This command turns on Enriched mode. Do this before you begin inserting -text, to ensure that the text you insert is handled properly. - - More generally, the command @code{enriched-mode} turns Enriched mode -on if it was off, and off if it was on. With a prefix argument, this -command turns Enriched mode on if the argument is positive, and turns -the mode off otherwise. - - When you save a buffer while Enriched mode is enabled in it, Emacs -automatically converts the text to text/enriched format while writing it -into the file. When you visit the file again, Emacs will automatically -recognize the format, reconvert the text, and turn on Enriched mode -again. - -@vindex enriched-translations - You can add annotations for saving additional text properties, which -Emacs normally does not save, by adding to @code{enriched-translations}. -Note that the text/enriched standard requires any non-standard -annotations to have names starting with @samp{x-}, as in -@samp{x-read-only}. This ensures that they will not conflict with -standard annotations that may be added later. - - @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}, -for more information about text properties. - -@node Hard and Soft Newlines -@subsection Hard and Soft Newlines -@cindex hard newline -@cindex soft newline -@cindex newlines, hard and soft - -@cindex use-hard-newlines - In formatted text, Emacs distinguishes between two different kinds of -newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable -or disable this feature separately in any buffer with the command -@code{use-hard-newlines}.) - - Hard newlines are used to separate paragraphs, or items in a list, or -anywhere that there should always be a line break regardless of the -margins. The @key{RET} command (@code{newline}) and @kbd{C-o} -(@code{open-line}) insert hard newlines. - - Soft newlines are used to make text fit between the margins. All the -fill commands, including Auto Fill, insert soft newlines---and they -delete only soft newlines. - - Although hard and soft newlines look the same, it is important to bear -the difference in mind. Do not use @key{RET} to break lines in the -middle of filled paragraphs, or else you will get hard newlines that are -barriers to further filling. Instead, let Auto Fill mode break lines, -so that if the text or the margins change, Emacs can refill the lines -properly. @xref{Auto Fill}. - - On the other hand, in tables and lists, where the lines should always -remain as you type them, you can use @key{RET} to end lines. For these -lines, you may also want to set the justification style to -@code{unfilled}. @xref{Format Justification}. - -@node Editing Format Info -@subsection Editing Format Information - - There are two ways to alter the formatting information for a formatted -text file: with keyboard commands, and with the mouse. - - The easiest way to add properties to your document is with the Text -Properties menu. You can get to this menu in two ways: from the Edit -menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse), -or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle -mouse button). There are also keyboard commands described in the -following section. - - These items in the Text Properties menu run commands directly: - -@table @code -@findex facemenu-remove-face-props -@item Remove Face Properties -Delete from the region all face and color text properties -(@code{facemenu-remove-face-props}). - -@findex facemenu-remove-all -@item Remove Text Properties -Delete @emph{all} text properties from the region -(@code{facemenu-remove-all}). - -@findex describe-text-properties -@cindex text properties of characters -@cindex overlays at character position -@cindex widgets at buffer position -@cindex buttons at buffer position -@item Describe Properties -List all the text properties, widgets, buttons, and overlays of the -character following point (@code{describe-text-properties}). - -@item Display Faces -Display a list of all the defined faces (@code{list-faces-display}). - -@item Display Colors -Display a list of all the defined colors (@code{list-colors-display}). -@end table - -@ifinfo - Other items in the Text Properties menu lead to submenus: - -@menu -* Faces: Format Faces. Bold, italic, underline, etc. -* Color: Format Colors. Changing the color of text. -* Indent: Format Indentation. Changing the left and right margins. -* Justification: Format Justification. - Centering, setting text flush with the - left or right margin, etc. -* Special: Format Properties. The "special" text properties submenu. -@end menu -@end ifinfo -@ifnotinfo - The rest lead to submenus which are described in the following sections. -@end ifnotinfo - -@node Format Faces -@subsection Faces in Formatted Text - - The Faces submenu under Text Properties lists various Emacs faces -including @code{bold}, @code{italic}, and @code{underline} -(@pxref{Faces}). These menu items operate on the region if it is -active and nonempty. Otherwise, they specify to use that face for an -immediately following self-inserting character. There is also an item -@samp{Other} with which you can enter a face name through the -minibuffer (@pxref{Standard Faces}). - - Instead of the Faces submenu, you can use these keyboard commands: - -@table @kbd -@kindex M-o d @r{(Enriched mode)} -@findex facemenu-set-default -@item M-o d -Remove all @code{face} properties from the region (which includes -specified colors), or force the following inserted character to have no -@code{face} property (@code{facemenu-set-default}). -@kindex M-o b @r{(Enriched mode)} -@findex facemenu-set-bold -@item M-o b -Add the face @code{bold} to the region or to the following inserted -character (@code{facemenu-set-bold}). -@kindex M-o i @r{(Enriched mode)} -@findex facemenu-set-italic -@item M-o i -Add the face @code{italic} to the region or to the following inserted -character (@code{facemenu-set-italic}). -@kindex M-o l @r{(Enriched mode)} -@findex facemenu-set-bold-italic -@item M-o l -Add the face @code{bold-italic} to the region or to the following -inserted character (@code{facemenu-set-bold-italic}). -@kindex M-o u @r{(Enriched mode)} -@findex facemenu-set-underline -@item M-o u -Add the face @code{underline} to the region or to the following inserted -character (@code{facemenu-set-underline}). -@kindex M-o o @r{(Enriched mode)} -@findex facemenu-set-face -@item M-o o @var{face} @key{RET} -Add the face @var{face} to the region or to the following inserted -character (@code{facemenu-set-face}). -@end table - - With a prefix argument, all these commands apply to an immediately -following self-inserting character, disregarding the region. - - A self-inserting character normally inherits the @code{face} -property (and most other text properties) from the preceding character -in the buffer. If you use the above commands to specify face for the -next self-inserting character, or the next section's commands to -specify a foreground or background color for it, then it does not -inherit the @code{face} property from the preceding character; instead -it uses whatever you specified. It will still inherit other text -properties, though. - - Strictly speaking, these commands apply only to the first following -self-inserting character that you type. But if you insert additional -characters after it, they will inherit from the first one. So it -appears that these commands apply to all of them. - - Enriched mode defines two additional faces: @code{excerpt} and -@code{fixed}. These correspond to codes used in the text/enriched file -format. - - The @code{excerpt} face is intended for quotations. This face is the -same as @code{italic} unless you customize it (@pxref{Face Customization}). - - The @code{fixed} face means, ``Use a fixed-width font for this part -of the text.'' Applying the @code{fixed} face to a part of the text -will cause that part of the text to appear in a fixed-width font, even -if the default font is variable-width. This applies to Emacs and to -other systems that display text/enriched format. So if you -specifically want a certain part of the text to use a fixed-width -font, you should specify the @code{fixed} face for that part. - - By default, the @code{fixed} face looks the same as @code{bold}. -This is an attempt to distinguish it from @code{default}. You may -wish to customize @code{fixed} to some other fixed-width medium font. -@xref{Face Customization}. - - If your terminal cannot display different faces, you will not be -able to see them, but you can still edit documents containing faces, -and even add faces and colors to documents. The faces you specify -will be visible when the file is viewed on a terminal that can display -them. - -@node Format Colors -@subsection Colors in Formatted Text - - You can specify foreground and background colors for portions of the -text. Under Text Properties, there is a submenu for specifying the -foreground color, and a submenu for specifying the background color. -Each one lists all the colors that you have used in Enriched mode in -the current Emacs session. - - If the region is active, the command applies to the text in the -region; otherwise, it applies to any immediately following -self-inserting input. When Transient Mark mode is off -(@pxref{Persistent Mark}), it always applies to the region unless a -prefix argument is given, in which case it applies to the following -input. - - Each of the two color submenus contains one additional item: -@samp{Other}. You can use this item to specify a color that is not -listed in the menu; it reads the color name with the minibuffer. To -display a list of available colors and their names, use the -@samp{Display Colors} menu item in the Text Properties menu -(@pxref{Editing Format Info}). - - Any color that you specify in this way, or that is mentioned in a -formatted text file that you read in, is added to the corresponding -color menu for the duration of the Emacs session. - -@findex facemenu-set-foreground -@findex facemenu-set-background - There are no predefined key bindings for specifying colors, but you can do so -with the extended commands @kbd{M-x facemenu-set-foreground} and -@kbd{M-x facemenu-set-background}. Both of these commands read the name -of the color with the minibuffer. - -@node Format Indentation -@subsection Indentation in Formatted Text - - When editing formatted text, you can specify different amounts of -indentation for the right or left margin of an entire paragraph or a -part of a paragraph. The margins you specify automatically affect the -Emacs fill commands (@pxref{Filling}) and line-breaking commands. - - The Indentation submenu of Text Properties provides a convenient -interface for specifying these properties. The submenu contains four -items: - -@table @code -@kindex C-x TAB @r{(Enriched mode)} -@findex increase-left-margin -@item Indent More -Indent the region by 4 columns (@code{increase-left-margin}). In -Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if -you supply a numeric argument, that says how many columns to add to the -margin (a negative argument reduces the number of columns). - -@item Indent Less -Remove 4 columns of indentation from the region. - -@item Indent Right More -Make the text narrower by indenting 4 columns at the right margin. - -@item Indent Right Less -Remove 4 columns of indentation from the right margin. -@end table - - You can use these commands repeatedly to increase or decrease the -indentation. - - The most common way to use them is to change the indentation of an -entire paragraph. For other uses, the effects of refilling can be -hard to predict, except in some special cases like the one described -next. - - The most common other use is to format paragraphs with @dfn{hanging -indents}, which means that the first line is indented less than -subsequent lines. To set up a hanging indent, increase the -indentation of the region starting after the first word of the -paragraph and running until the end of the paragraph. - - Indenting the first line of a paragraph is easier. Set the margin for -the whole paragraph where you want it to be for the body of the -paragraph, then indent the first line by inserting extra spaces or tabs. - -@vindex standard-indent - The variable @code{standard-indent} specifies how many columns these -commands should add to or subtract from the indentation. The default -value is 4. The overall default right margin for Enriched mode is -controlled by the variable @code{fill-column}, as usual. - -@kindex C-c [ @r{(Enriched mode)} -@kindex C-c ] @r{(Enriched mode)} -@findex set-left-margin -@findex set-right-margin - There are also two commands for setting the left or right margin of -the region absolutely: @code{set-left-margin} and -@code{set-right-margin}. Enriched mode binds these commands to -@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the -margin width either with a numeric argument or in the minibuffer. - - Sometimes, as a result of editing, the filling of a paragraph becomes -messed up---parts of the paragraph may extend past the left or right -margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to -refill the paragraph. - - The fill prefix, if any, works in addition to the specified paragraph -indentation: @kbd{C-x .} does not include the specified indentation's -whitespace in the new value for the fill prefix, and the fill commands -look for the fill prefix after the indentation on each line. @xref{Fill -Prefix}. - -@node Format Justification -@subsection Justification in Formatted Text - - When editing formatted text, you can specify various styles of -justification for a paragraph. The style you specify automatically -affects the Emacs fill commands. - - The Justification submenu of Text Properties provides a convenient -interface for specifying the style. The submenu contains five items: - -@table @code -@item Left -This is the most common style of justification (at least for English). -Lines are aligned at the left margin but left uneven at the right. - -@item Right -This aligns each line with the right margin. Spaces and tabs are added -on the left, if necessary, to make lines line up on the right. - -@item Full -This justifies the text, aligning both edges of each line. Justified -text looks very nice in a printed book, where the spaces can all be -adjusted equally, but it does not look as nice with a fixed-width font -on the screen. Perhaps a future version of Emacs will be able to adjust -the width of spaces in a line to achieve elegant justification. - -@item Center -This centers every line between the current margins. - -@item Unfilled -This turns off filling entirely. Each line will remain as you wrote it; -the fill and auto-fill functions will have no effect on text which has -this setting. You can, however, still indent the left margin. In -unfilled regions, all newlines are treated as hard newlines (@pxref{Hard -and Soft Newlines}) . -@end table - - In Enriched mode, you can also specify justification from the keyboard -using the @kbd{M-j} prefix character: - -@table @kbd -@kindex M-j l @r{(Enriched mode)} -@findex set-justification-left -@item M-j l -Make the region left-filled (@code{set-justification-left}). -@kindex M-j r @r{(Enriched mode)} -@findex set-justification-right -@item M-j r -Make the region right-filled (@code{set-justification-right}). -@kindex M-j b @r{(Enriched mode)} -@findex set-justification-full -@item M-j b -Make the region fully justified (@code{set-justification-full}). -@kindex M-j c @r{(Enriched mode)} -@kindex M-S @r{(Enriched mode)} -@findex set-justification-center -@item M-j c -@itemx M-S -Make the region centered (@code{set-justification-center}). -@kindex M-j u @r{(Enriched mode)} -@findex set-justification-none -@item M-j u -Make the region unfilled (@code{set-justification-none}). -@end table - - Justification styles apply to entire paragraphs. All the -justification-changing commands operate on the paragraph containing -point, or, if the region is active, on all paragraphs which overlap the -region. - -@vindex default-justification - The default justification style is specified by the variable -@code{default-justification}. Its value should be one of the symbols -@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}. -This is a per-buffer variable. Setting the variable directly affects -only the current buffer. However, customizing it in a Custom buffer -sets (as always) the default value for buffers that do not override it. -@xref{Locals}, and @ref{Easy Customization}. - -@node Format Properties -@subsection Setting Other Text Properties - - The Special Properties submenu of Text Properties can add or remove -three other useful text properties: @code{read-only}, @code{invisible} -and @code{intangible}. The @code{intangible} property disallows -moving point within the text, the @code{invisible} text property hides -text from display, and the @code{read-only} property disallows -alteration of the text. - - Each of these special properties has a menu item to add it to the -region. The last menu item, @samp{Remove Special}, removes all of these -special properties from the text in the region. - - Currently, the @code{invisible} and @code{intangible} properties are -@emph{not} saved in the text/enriched format. The @code{read-only} -property is saved, but it is not a standard part of the text/enriched -format, so other editors may not respect it. - -@node Forcing Enriched Mode -@subsection Forcing Enriched Mode - - Normally, Emacs knows when you are editing formatted text because it -recognizes the special annotations used in the file that you visited. -However, sometimes you must take special actions to convert file -contents or turn on Enriched mode: - -@itemize @bullet -@item -When you visit a file that was created with some other editor, Emacs may -not recognize the file as being in the text/enriched format. In this -case, when you visit the file you will see the formatting commands -rather than the formatted text. Type @kbd{M-x format-decode-buffer} to -translate it. This also automatically turns on Enriched mode. - -@item -When you @emph{insert} a file into a buffer, rather than visiting it, -Emacs does the necessary conversions on the text which you insert, but -it does not enable Enriched mode. If you wish to do that, type @kbd{M-x -enriched-mode}. -@end itemize - - The command @code{format-decode-buffer} translates text in various -formats into Emacs's internal format. It asks you to specify the format -to translate from; however, normally you can type just @key{RET}, which -tells Emacs to guess the format. - -@findex format-find-file - If you wish to look at a text/enriched file in its raw form, as a -sequence of characters rather than as formatted text, use the @kbd{M-x -find-file-literally} command. This visits a file, like -@code{find-file}, but does not do format conversion. It also inhibits -character code conversion (@pxref{Coding Systems}) and automatic -uncompression (@pxref{Compressed Files}). To disable format conversion -but allow character code conversion and/or automatic uncompression if -appropriate, use @code{format-find-file} with suitable arguments. - -@node Text Based Tables -@section Editing Text-based Tables -@cindex table mode -@cindex text-based tables - - Table mode provides an easy and intuitive way to create and edit WYSIWYG -text-based tables. Here is an example of such a table: - -@smallexample -@group -+-----------------+--------------------------------+-----------------+ -| Command | Description | Key Binding | -+-----------------+--------------------------------+-----------------+ -| forward-char |Move point right N characters | C-f | -| |(left if N is negative). | | -| | | | -| |On reaching end of buffer, stop | | -| |and signal error. | | -+-----------------+--------------------------------+-----------------+ -| backward-char |Move point left N characters | C-b | -| |(right if N is negative). | | -| | | | -| |On attempt to pass beginning or | | -| |end of buffer, stop and signal | | -| |error. | | -+-----------------+--------------------------------+-----------------+ -@end group -@end smallexample - - Table mode allows the contents of the table such as this one to be -easily manipulated by inserting or deleting characters inside a cell. -A cell is effectively a localized rectangular edit region and edits to -a cell do not affect the contents of the surrounding cells. If the -contents do not fit into a cell, then the cell is automatically -expanded in the vertical and/or horizontal directions and the rest of -the table is restructured and reformatted in accordance with the -growth of the cell. - -@menu -* Table Definition:: What is a text based table. -* Table Creation:: How to create a table. -* Table Recognition:: How to activate and deactivate tables. -* Cell Commands:: Cell-oriented commands in a table. -* Cell Justification:: Justifying cell contents. -* Row Commands:: Manipulating rows of table cell. -* Column Commands:: Manipulating columns of table cell. -* Fixed Width Mode:: Fixing cell width. -* Table Conversion:: Converting between plain text and tables. -* Measuring Tables:: Analyzing table dimension. -* Table Misc:: Table miscellany. -@end menu - -@node Table Definition -@subsection What is a Text-based Table? - - Keep the following examples of valid tables in mind as a reference -while you read this section: - -@example - +--+----+---+ +-+ +--+-----+ - | | | | | | | | | - +--+----+---+ +-+ | +--+--+ - | | | | | | | | - +--+----+---+ +--+--+ | - | | | - +-----+--+ -@end example - - A table consists of a rectangular frame whose inside is divided into -cells. Each cell must be at least one character wide and one -character high, not counting its border lines. A cell can be -subdivided into multiple rectangular cells, but cells cannot overlap. - - The table frame and cell border lines are made of three special -characters. These variables specify those characters: - -@table @code -@vindex table-cell-vertical-char -@item table-cell-vertical-char -Holds the character used for vertical lines. The default value is -@samp{|}. - -@vindex table-cell-horizontal-chars -@item table-cell-horizontal-chars -Holds the characters used for horizontal lines. The default value is -@samp{"-="}. - -@vindex table-cell-intersection-char -@item table-cell-intersection-char -Holds the character used at where horizontal line and vertical line -meet. The default value is @samp{+}. -@end table - -@noindent -Based on this definition, the following five tables are examples of invalid -tables: - -@example - +-----+ +-----+ +--+ +-++--+ ++ - | | | | | | | || | ++ - | +-+ | | | | | | || | - | | | | +--+ | +--+--+ +-++--+ - | +-+ | | | | | | | +-++--+ - | | | | | | | | | || | - +-----+ +--+--+ +--+--+ +-++--+ - a b c d e -@end example - -From left to right: - -@enumerate a -@item -Overlapped cells or non-rectangular cells are not allowed. -@item -Same as a. -@item -The border must be rectangular. -@item -Cells must have a minimum width/height of one character. -@item -Same as d. -@end enumerate - -@node Table Creation -@subsection How to Create a Table? -@cindex create a text-based table -@cindex table creation - -@findex table-insert - The command to create a table is @code{table-insert}. When called -interactively, it asks for the number of columns, number of rows, cell -width and cell height. The number of columns is the number of cells -horizontally side by side. The number of rows is the number of cells -vertically within the table's height. The cell width is a number of -characters that each cell holds, left to right. The cell height is a -number of lines each cell holds. The cell width and the cell height -can be either an integer (when the value is constant across the table) -or a series of integer, separated by spaces or commas, where each -number corresponds to the next cell within a row from left to right, -or the next cell within a column from top to bottom. - -@node Table Recognition -@subsection Table Recognition -@cindex table recognition - -@findex table-recognize -@findex table-unrecognize - Table mode maintains special text properties in the buffer to allow -editing in a convenient fashion. When a buffer with tables is saved -to its file, these text properties are lost, so when you visit this -file again later, Emacs does not see a table, but just formatted text. -To resurrect the table text properties, issue the @kbd{M-x -table-recognize} command. It scans the current buffer, recognizes -valid table cells, and attaches appropriate text properties to allow -for table editing. The converse command, @code{table-unrecognize}, is -used to remove the special text properties and convert the buffer back -to plain text. - - Special commands exist to enable or disable tables within a region, -enable or disable individual tables, and enable/disable individual -cells. These commands are: - -@table @kbd -@findex table-recognize-region -@item M-x table-recognize-region -Recognize tables within the current region and activate them. -@findex table-unrecognize-region -@item M-x table-unrecognize-region -Deactivate tables within the current region. -@findex table-recognize-table -@item M-x table-recognize-table -Recognize the table under point and activate it. -@findex table-unrecognize-table -@item M-x table-unrecognize-table -Deactivate the table under point. -@findex table-recognize-cell -@item M-x table-recognize-cell -Recognize the cell under point and activate it. -@findex table-unrecognize-cell -@item M-x table-unrecognize-cell -Deactivate the cell under point. -@end table - - For another way of converting text into tables, see @ref{Table -Conversion}. - -@node Cell Commands -@subsection Commands for Table Cells - -@findex table-forward-cell -@findex table-backward-cell - The commands @code{table-forward-cell} and -@code{table-backward-cell} move point from the current cell to an -adjacent cell forward and backward respectively. The order of the -cells is cyclic: when point is in the last cell of a table, typing -@kbd{M-x table-forward-cell} moves to the first cell in the table. -Likewise @kbd{M-x table-backward-cell} from the first cell in a table -moves to the last cell. - -@findex table-span-cell - The command @code{table-span-cell} merges the current cell with the -adjacent cell in a specified direction---right, left, above or below. -You specify the direction with the minibuffer. It does not allow -merges which don't result in a legitimate cell layout. - -@findex table-split-cell -@cindex text-based tables, split a cell -@cindex split table cell - The command @code{table-split-cell} splits the current cell -vertically or horizontally. This command is a wrapper to the -direction specific commands @code{table-split-cell-vertically} and -@code{table-split-cell-horizontally}. You specify the direction with -a minibuffer argument. - -@findex table-split-cell-vertically - The command @code{table-split-cell-vertically} splits the current -cell vertically and creates a pair of cells above and below where -point is located. The content in the original cell is split as well. - -@findex table-split-cell-horizontally - The command @code{table-split-cell-horizontally} splits the current -cell horizontally and creates a pair of cells right and left of where -point is located. If the cell being split is not empty, this asks you -how to handle the cell contents. The three options are: @code{split}, -@code{left}, or @code{right}. @code{split} splits the contents at -point literally, while the @code{left} and @code{right} options move -the entire contents into the left or right cell respectively. - -@cindex enlarge a table cell -@cindex shrink a table cell - The next four commands enlarge or shrink a cell. They use numeric -arguments (@pxref{Arguments}) to specify how many columns or rows to -enlarge or shrink a particular table. - -@table @kbd -@findex table-heighten-cell -@item M-x table-heighten-cell -Enlarge the current cell vertically. -@findex table-shorten-cell -@item M-x table-shorten-cell -Shrink the current cell vertically. -@findex table-widen-cell -@item M-x table-widen-cell -Enlarge the current cell horizontally. -@findex table-narrow-cell -@item M-x table-narrow-cell -Shrink the current cell horizontally. -@end table - -@node Cell Justification -@subsection Cell Justification -@cindex cell text justification - - You can specify text justification for each cell. The justification -is remembered independently for each cell and the subsequent editing -of cell contents is subject to the specified justification. - -@findex table-justify - The command @code{table-justify} ask you to specify what to justify: -a cell, a column, or a row. If you select cell justification, this -command sets the justification only for the current cell. Selecting -column or row justification sets the justification for all the cells -within a column or row respectively. The command then ask you which -kind of justification to apply: @code{left}, @code{center}, -@code{right}, @code{top}, @code{middle}, @code{bottom}, or -@code{none}. Horizontal justification and vertical justification are -specified independently. The options @code{left}, @code{center}, and -@code{right} specify horizontal justification while the options -@code{top}, @code{middle}, @code{bottom}, and @code{none} specify -vertical justification. The vertical justification @code{none} -effectively removes vertical justification. Horizontal justification -must be one of @code{left}, @code{center}, or @code{right}. - -@vindex table-detect-cell-alignment - Justification information is stored in the buffer as a part of text -property. Therefore, this information is ephemeral and does not -survive through the loss of the buffer (closing the buffer and -revisiting the buffer erase any previous text properties). To -countermand for this, the command @code{table-recognize} and other -recognition commands (@pxref{Table Recognition}) are equipped with a -convenience feature (turned on by default). During table recognition, -the contents of a cell are examined to determine which justification -was originally applied to the cell and then applies this justification -to the cell. This is a speculative algorithm and is therefore not -perfect, however, the justification is deduced correctly most of the -time. To disable this feature, customize the variable -@code{table-detect-cell-alignment} and set it to @code{nil}. - -@node Row Commands -@subsection Commands for Table Rows -@cindex table row commands - -@cindex insert row in table -@findex table-insert-row - The command @code{table-insert-row} inserts a row of cells before -the current row in a table. The current row where point is located is -pushed down after the newly inserted row. A numeric prefix argument -specifies the number of rows to insert. Note that in order to insert -rows @emph{after} the last row at the bottom of a table, you must -place point below the table---that is, outside the table---prior to -invoking this command. - -@cindex delete row in table -@findex table-delete-row - The command @code{table-delete-row} deletes a row of cells at point. -A numeric prefix argument specifies the number of rows to delete. - -@node Column Commands -@subsection Commands for Table Columns -@cindex table column commands - -@cindex insert column in table -@findex table-insert-column - The command @code{table-insert-column} inserts a column of cells to -the left of the current row in a table. This pushes the current -column to the right. To insert a column to the right side of the -rightmost column, place point to the right of the rightmost column, -which is outside of the table, prior to invoking this command. A -numeric prefix argument specifies the number of columns to insert. - -@cindex delete column in table - A command @code{table-delete-column} deletes a column of cells at -point. A numeric prefix argument specifies the number of columns to -delete. - -@node Fixed Width Mode -@subsection Fix Width of Cells -@cindex fix width of table cells - -@findex table-fixed-width-mode - The command @code{table-fixed-width-mode} toggles fixed width mode -on and off. When fixed width mode is turned on, editing inside a -cell never changes the cell width; when it is off, the cell width -expands automatically in order to prevent a word from being folded -into multiple lines. By default, fixed width mode is disabled. - -@node Table Conversion -@subsection Conversion Between Plain Text and Tables -@cindex text to table -@cindex table to text - -@findex table-capture - The command @code{table-capture} captures plain text in a region and -turns it into a table. Unlike @code{table-recognize} (@pxref{Table -Recognition}), the original text does not have a table appearance but -may hold a logical table structure. For example, some elements -separated by known patterns form a two dimensional structure which can -be turned into a table. - - Here's an example of data that @code{table-capture} can operate on. -The numbers are horizontally separated by a comma and vertically -separated by a newline character. - -@example -1, 2, 3, 4 -5, 6, 7, 8 -, 9, 10 -@end example - -@noindent -Invoking @kbd{M-x table-capture} on that text produces this table: - -@example -+-----+-----+-----+-----+ -|1 |2 |3 |4 | -+-----+-----+-----+-----+ -|5 |6 |7 |8 | -+-----+-----+-----+-----+ -| |9 |10 | | -+-----+-----+-----+-----+ -@end example - -@noindent -The conversion uses @samp{,} for the column delimiter and newline for -a row delimiter, cells are left justified, and minimum cell width is -5. - -@findex table-release - The command @code{table-release} does the opposite of -@code{table-capture}. It releases a table by removing the table frame -and cell borders. This leaves the table contents as plain text. One -of the useful applications of @code{table-capture} and -@code{table-release} is to edit a text in layout. Look at the -following three paragraphs (the latter two are indented with header -lines): - -@example -@samp{table-capture} is a powerful command, but mastering its -power requires some practice. Here are some things it can do: - -Parse Cell Items By using column delimiter regular - expression and raw delimiter regular - expression, it parses the specified text - area and extracts cell items from - non-table text and then forms a table out - of them. - -Capture Text Area When no delimiters are specified it - creates a single cell table. The text in - the specified region is placed in that - cell. -@end example - -@noindent -Applying @code{table-capture} to a region containing the above three -paragraphs, with empty strings for column delimiter regexp and row -delimiter regexp, creates a table with a single cell like the -following one. - -@c The first line's right-hand frame in the following two examples -@c sticks out to accommodate for the removal of @samp in the -@c produced output!! -@smallexample -@group -+-----------------------------------------------------------------+ -|@samp{table-capture} is a powerful command, but mastering its | -|power requires some practice. Here are some things it can do: | -| | -|Parse Cell Items By using column delimiter regular | -| expression and raw delimiter regular | -| expression, it parses the specified text | -| area and extracts cell items from | -| non-table text and then forms a table out | -| of them. | -| | -|Capture Text Area When no delimiters are specified it | -| creates a single cell table. The text in | -| the specified region is placed in that | -| cell. | -+-----------------------------------------------------------------+ -@end group -@end smallexample - -@noindent -By splitting the cell appropriately we now have a table consisting of -paragraphs occupying its own cell. Each cell can now be edited -independently without affecting the layout of other cells. - -@smallexample -+-----------------------------------------------------------------+ -|@samp{table-capture} is a powerful command, but mastering its | -|power requires some practice. Here are some things it can do: | -+---------------------+-------------------------------------------+ -|Parse Cell Items |By using column delimiter regular | -| |expression and raw delimiter regular | -| |expression, it parses the specified text | -| |area and extracts cell items from | -| |non-table text and then forms a table out | -| |of them. | -+---------------------+-------------------------------------------+ -|Capture Text Area |When no delimiters are specified it | -| |creates a single cell table. The text in | -| |the specified region is placed in that | -| |cell. | -+---------------------+-------------------------------------------+ -@end smallexample - -@noindent -By applying @code{table-release}, which does the opposite process, the -contents become once again plain text. @code{table-release} works as -a companion command to @code{table-capture}. - -@node Measuring Tables -@subsection Analyzing Table Dimensions -@cindex table dimensions - -@findex table-query-dimension - The command @code{table-query-dimension} analyzes a table structure -and reports information regarding its dimensions. In case of the -above example table, the @code{table-query-dimension} command displays -in echo area: - -@smallexample -Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 -@end smallexample - -@noindent -This indicates that the current cell is 21 character wide and 6 lines -high, the entire table is 67 characters wide and 16 lines high. The -table has 2 columns and 3 rows. It has a total of 5 cells, since the -first row has a spanned cell. - -@node Table Misc -@subsection Table Miscellany - -@cindex insert string into table cells -@findex table-insert-sequence - The command @code{table-insert-sequence} inserts a string into each -cell. Each string is a part of a sequence i.e.@: a series of -increasing integer numbers. - -@cindex table in language format -@cindex table for HTML and LaTeX -@findex table-generate-source - The command @code{table-generate-source} generates a table formatted -for a specific markup language. It asks for a language (which must be -one of @code{html}, @code{latex}, or @code{cals}), a destination -buffer where to put the result, and the table caption (a string), and -then inserts the generated table in the proper syntax into the -destination buffer. The default destination buffer is -@code{table.@var{lang}}, where @var{lang} is the language you -specified. - -@ignore - arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70 -@end ignore diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi deleted file mode 100644 index 68c5fe97134..00000000000 --- a/doc/emacs/trouble.texi +++ /dev/null @@ -1,1055 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@iftex -@chapter Dealing with Common Problems - - If you type an Emacs command you did not intend, the results are often -mysterious. This chapter tells what you can do to cancel your mistake or -recover from a mysterious situation. Emacs bugs and system crashes are -also considered. -@end iftex - -@ifnottex -@raisesections -@end ifnottex - -@node Quitting, Lossage, Customization, Top -@section Quitting and Aborting -@cindex quitting - -@table @kbd -@item C-g -@itemx C-@key{BREAK} @r{(MS-DOS only)} -Quit: cancel running or partially typed command. -@item C-] -Abort innermost recursive editing level and cancel the command which -invoked it (@code{abort-recursive-edit}). -@item @key{ESC} @key{ESC} @key{ESC} -Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). -@item M-x top-level -Abort all recursive editing levels that are currently executing. -@item C-/ -@itemx C-x u -@itemx C-_ -Cancel a previously made change in the buffer contents (@code{undo}). -@end table - - There are two ways of canceling a command before it has finished: -@dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with @kbd{C-]} or -@kbd{M-x top-level}. Quitting cancels a partially typed command, or -one which is still running. Aborting exits a recursive editing level -and cancels the command that invoked the recursive edit. -(@xref{Recursive Edit}.) - -@cindex quitting -@kindex C-g - Quitting with @kbd{C-g} is the way to get rid of a partially typed -command, or a numeric argument that you don't want. Furthermore, if -you are in the middle of a command that is running, @kbd{C-g} stops -the command in a relatively safe way. For example, if you quit out of -a kill command that is taking a long time, either your text will -@emph{all} still be in the buffer, or it will @emph{all} be in the -kill ring, or maybe both. If the region is active, @kbd{C-g} -deactivates the mark, unless Transient Mark mode is off -(@pxref{Persistent Mark}). If you are in the middle of an incremental -search, @kbd{C-g} does special things; it may take two successive -@kbd{C-g} characters to get out of a search. @xref{Incremental -Search}, for details. - - On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character -like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to -recognize @kbd{C-g} while a command is running, between interactions -with the user. By contrast, it @emph{is} feasible to recognize -@kbd{C-@key{BREAK}} at all times. -@iftex -@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@xref{MS-DOS Keyboard}. -@end ifnottex - -@findex keyboard-quit - @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} -the instant @kbd{C-g} is typed; Emacs Lisp checks this variable -frequently, and quits if it is non-@code{nil}. @kbd{C-g} is only -actually executed as a command if you type it while Emacs is waiting for -input. In that case, the command it runs is @code{keyboard-quit}. - - On a text terminal, if you quit with @kbd{C-g} a second time before -the first @kbd{C-g} is recognized, you activate the ``emergency -escape'' feature and return to the shell. @xref{Emergency Escape}. - -@cindex NFS and quitting - There are some situations where you cannot quit. When Emacs is -waiting for the operating system to do something, quitting is -impossible unless special pains are taken for the particular system -call within Emacs where the waiting occurs. We have done this for the -system calls that users are likely to want to quit from, but it's -possible you will encounter a case not handled. In one very common -case---waiting for file input or output using NFS---Emacs itself knows -how to quit, but many NFS implementations simply do not allow user -programs to stop waiting for NFS when the NFS server is hung. - -@cindex aborting recursive edit -@findex abort-recursive-edit -@kindex C-] - Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get -out of a recursive editing level and cancel the command which invoked -it. Quitting with @kbd{C-g} does not do this, and could not do this, -because it is used to cancel a partially typed command @emph{within} the -recursive editing level. Both operations are useful. For example, if -you are in a recursive edit and type @kbd{C-u 8} to enter a numeric -argument, you can cancel that argument with @kbd{C-g} and remain in the -recursive edit. - -@findex keyboard-escape-quit -@kindex ESC ESC ESC - The sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} -(@code{keyboard-escape-quit}) can either quit or abort. (We defined -it this way because @key{ESC} means ``get out'' in many PC programs.) -It can cancel a prefix argument, clear a selected region, or get out -of a Query Replace, like @kbd{C-g}. It can get out of the minibuffer -or a recursive edit, like @kbd{C-]}. It can also get out of splitting -the frame into multiple windows, as with @kbd{C-x 1}. One thing it -cannot do, however, is stop a command that is running. That's because -it executes as an ordinary command, and Emacs doesn't notice it until -it is ready for the next command. - -@findex top-level - The command @kbd{M-x top-level} is equivalent to ``enough'' -@kbd{C-]} commands to get you out of all the levels of recursive edits -that you are in; it also exits the minibuffer if it is active. -@kbd{C-]} gets you out one level at a time, but @kbd{M-x top-level} -goes out all levels at once. Both @kbd{C-]} and @kbd{M-x top-level} -are like all other commands, and unlike @kbd{C-g}, in that they take -effect only when Emacs is ready for a command. @kbd{C-]} is an -ordinary key and has its meaning only because of its binding in the -keymap. @xref{Recursive Edit}. - - @kbd{C-/} (@code{undo}) is not strictly speaking a way of canceling -a command, but you can think of it as canceling a command that already -finished executing. @xref{Undo}, for more information about the undo -facility. - -@node Lossage, Bugs, Quitting, Top -@section Dealing with Emacs Trouble - - This section describes various conditions in which Emacs fails to work -normally, and how to recognize them and correct them. For a list of -additional problems you might encounter, see @ref{Bugs and problems, , -Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} -in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type -@kbd{C-h C-p} to read the @file{PROBLEMS} file. - -@menu -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. -* Stuck Recursive:: `[...]' in mode line around the parentheses. -* Screen Garbled:: Garbage on the screen. -* Text Garbled:: Garbage in the text. -* Memory Full:: How to cope when you run out of memory. -* After a Crash:: Recovering editing in an Emacs session that crashed. -* Emergency Escape:: Emergency escape--- - What to do if Emacs stops responding. -* Total Frustration:: When you are at your wits' end. -@end menu - -@node DEL Does Not Delete -@subsection If @key{DEL} Fails to Delete -@cindex @key{DEL} vs @key{BACKSPACE} -@cindex @key{BACKSPACE} vs @key{DEL} -@cindex usual erasure key - - Every keyboard has a large key, usually labelled @key{Backspace}, -which is ordinarily used to erase the last character that you typed. -We call this key @dfn{the usual erasure key}. In Emacs, it is -supposed to be equivalent to @key{DEL}. - - When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system. If the usual -erasure key deletes forwards instead of backwards, that is probably -what happened---Emacs ought to be treating the @key{Backspace} key as -@key{DEL}, but it isn't. - - Some keyboards also have a @key{Delete} key, which is ordinarily -used to forwards. If this key deletes backward in Emacs, that too -suggests Emacs got the wrong information---but in the opposite sense. - - On a text-only terminal, if you find the usual erasure key prompts -for a Help command, like @kbd{Control-h}, instead of deleting a -character, it means that key is actually sending the @key{BS} -character. Emacs ought to be treating @key{BS} as @key{DEL}, but it -isn't. - - In all of those cases, the immediate remedy is the same: use the -command @kbd{M-x normal-erase-is-backspace-mode}. This toggles -between the two modes that Emacs supports for handling @key{DEL}, so -if Emacs starts in the wrong mode, this should switch to the right -mode. On a text-only terminal, if you want to ask for help when -@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also -work, if it sends character code 127. - -@findex normal-erase-is-backspace-mode - To fix the problem automatically for every Emacs session, you can -put one of the following lines into your @file{.emacs} file -(@pxref{Init File}). For the first case above, where @key{Backspace} -deletes forwards instead of backwards, use this line to make -@key{Backspace} act as @key{DEL} (resulting in behavior compatible -with Emacs 20 and previous versions): - -@lisp -(normal-erase-is-backspace-mode 0) -@end lisp - -@noindent -For the other two cases, use this line: - -@lisp -(normal-erase-is-backspace-mode 1) -@end lisp - -@vindex normal-erase-is-backspace - Another way to fix the problem for every Emacs session is to -customize the variable @code{normal-erase-is-backspace}: the value -@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is -@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy -Customization}. - -@node Stuck Recursive -@subsection Recursive Editing Levels - - Recursive editing levels are important and useful features of Emacs, but -they can seem like malfunctions if you do not understand them. - - If the mode line has square brackets @samp{[@dots{}]} around the parentheses -that contain the names of the major and minor modes, you have entered a -recursive editing level. If you did not do this on purpose, or if you -don't understand what that means, you should just get out of the recursive -editing level. To do so, type @kbd{M-x top-level}. This is called getting -back to top level. @xref{Recursive Edit}. - -@node Screen Garbled -@subsection Garbage on the Screen - - If the text on a text terminal looks wrong, the first thing to do is -see whether it is wrong in the buffer. Type @kbd{C-l} to redisplay -the entire screen. If the screen appears correct after this, the -problem was entirely in the previous screen update. (Otherwise, see -the following section.) - - Display updating problems often result from an incorrect terminfo -entry for the terminal you are using. The file @file{etc/TERMS} in -the Emacs distribution gives the fixes for known problems of this -sort. @file{INSTALL} contains general advice for these problems in -one of its sections. To investigate the possibility that you have -this sort of problem, try Emacs on another terminal made by a -different manufacturer. If problems happen frequently on one kind of -terminal but not another kind, it is likely to be a bad terminfo entry, -though it could also be due to a bug in Emacs that appears for -terminals that have or that lack specific features. - -@node Text Garbled -@subsection Garbage in the Text - - If @kbd{C-l} shows that the text is wrong, first type @kbd{C-h l} to -see what commands you typed to produce the observed results. Then try -undoing the changes step by step using @kbd{C-x u}, until it gets back -to a state you consider correct. - - If a large portion of text appears to be missing at the beginning or -end of the buffer, check for the word @samp{Narrow} in the mode line. -If it appears, the text you don't see is probably still present, but -temporarily off-limits. To make it accessible again, type @kbd{C-x n -w}. @xref{Narrowing}. - -@node Memory Full -@subsection Running out of Memory -@cindex memory full -@cindex out of memory - - If you get the error message @samp{Virtual memory exceeded}, save -your modified buffers with @kbd{C-x s}. This method of saving them -has the smallest need for additional memory. Emacs keeps a reserve of -memory which it makes available when this error happens; that should -be enough to enable @kbd{C-x s} to complete its work. When the -reserve has been used, @samp{!MEM FULL!} appears at the beginning of -the mode line, indicating there is no more reserve. - - Once you have saved your modified buffers, you can exit this Emacs -session and start another, or you can use @kbd{M-x kill-some-buffers} -to free space in the current Emacs job. If this frees up sufficient -space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} -will disappear from the mode line. That means you can safely go on -editing in the same Emacs session. - - Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run -out of memory, because the buffer menu needs a fair amount of memory -itself, and the reserve supply may not be enough. - -@node After a Crash -@subsection Recovery After a Crash - - If Emacs or the computer crashes, you can recover the files you were -editing at the time of the crash from their auto-save files. To do -this, start Emacs again and type the command @kbd{M-x recover-session}. - - This command initially displays a buffer which lists interrupted -session files, each with its date. You must choose which session to -recover from. Typically the one you want is the most recent one. Move -point to the one you choose, and type @kbd{C-c C-c}. - - Then @code{recover-session} considers each of the files that you -were editing during that session; for each such file, it asks whether -to recover that file. If you answer @kbd{y} for a file, it shows the -dates of that file and its auto-save file, then asks once again -whether to recover that file. For the second question, you must -confirm with @kbd{yes}. If you do, Emacs visits the file but gets the -text from the auto-save file. - - When @code{recover-session} is done, the files you've chosen to -recover are present in Emacs buffers. You should then save them. Only -this---saving them---updates the files themselves. - - As a last resort, if you had buffers with content which were not -associated with any files, or if the autosave was not recent enough to -have recorded important changes, you can use the -@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to -retrieve them from a core dump--provided that a core dump was saved, -and that the Emacs executable was not stripped of its debugging -symbols. - - As soon as you get the core dump, rename it to another name such as -@file{core.emacs}, so that another crash won't overwrite it. - - To use this script, run @code{gdb} with the file name of your Emacs -executable and the file name of the core dump, e.g. @samp{gdb -/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the -recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. -Then type the command @code{ybuffer-list} to see which buffers are -available. For each buffer, it lists a buffer number. To save a -buffer, use @code{ysave-buffer}; you specify the buffer number, and -the file name to write that buffer into. You should use a file name -which does not already exist; if the file does exist, the script does -not make a backup of its old contents. - -@node Emergency Escape -@subsection Emergency Escape - - On text-only terminals, the @dfn{emergency escape} feature suspends -Emacs immediately if you type @kbd{C-g} a second time before Emacs can -actually respond to the first one by quitting. This is so you can -always get out of GNU Emacs no matter how badly it might be hung. -When things are working properly, Emacs recognizes and handles the -first @kbd{C-g} so fast that the second one won't trigger emergency -escape. However, if some problem prevents Emacs from handling the -first @kbd{C-g} properly, then the second one will get you back to the -shell. - - When you resume Emacs after a suspension caused by emergency escape, -it asks two questions before going back to what it had been doing: - -@example -Auto-save? (y or n) -Abort (and dump core)? (y or n) -@end example - -@noindent -Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. - - Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of -all modified buffers in which auto-saving is enabled. Saying @kbd{n} -skips this. - - Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to -crash, dumping core. This is to enable a wizard to figure out why -Emacs was failing to quit in the first place. Execution does not -continue after a core dump. - - If you answer this question @kbd{n}, Emacs execution resumes. With -luck, Emacs will ultimately do the requested quit. If not, each -subsequent @kbd{C-g} invokes emergency escape again. - - If Emacs is not really hung, just slow, you may invoke the double -@kbd{C-g} feature without really meaning to. Then just resume and -answer @kbd{n} to both questions, and you will get back to the former -state. The quit you requested will happen by and by. - - Emergency escape is active only for text terminals. On graphical -displays, you can use the mouse to kill Emacs or switch to another -program. - - On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause -emergency escape---but there are cases where it won't work, when -system call hangs or when Emacs is stuck in a tight loop in C code. - -@node Total Frustration -@subsection Help for Total Frustration -@cindex Eliza -@cindex doctor - - If using Emacs (or something else) becomes terribly frustrating and none -of the techniques described above solve the problem, Emacs can still help -you. - - First, if the Emacs you are using is not responding to commands, type -@kbd{C-g C-g} to get out of it and then start a new one. - -@findex doctor - Second, type @kbd{M-x doctor @key{RET}}. - - The Emacs psychotherapist will help you feel better. Each time you -say something to the psychotherapist, you must end it by typing -@key{RET} @key{RET}. This indicates you are finished typing. - -@node Bugs, Contributing, Lossage, Top -@section Reporting Bugs - -@cindex bugs - Sometimes you will encounter a bug in Emacs. Although we cannot -promise we can or will fix the bug, and we might not even agree that it -is a bug, we want to hear about problems you encounter. Often we agree -they are bugs and want to fix them. - - To make it possible for us to fix a bug, you must report it. In order -to do so effectively, you must know when and how to do it. - - Before reporting a bug, it is a good idea to see if it is already -known. You can find the list of known problems in the file -@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read -it. Some additional user-level problems can be found in @ref{Bugs and -problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your -problem in these two documents might provide you with a solution or a -work-around, or give you additional information about related issues. - -@menu -* Criteria: Bug Criteria. Have you really found a bug? -* Understanding Bug Reporting:: How to report a bug effectively. -* Checklist:: Steps to follow for a good bug report. -* Sending Patches:: How to send a patch for GNU Emacs. -@end menu - -@node Bug Criteria -@subsection When Is There a Bug - - If Emacs accesses an invalid memory location (``segmentation -fault''), or exits with an operating system error message that -indicates a problem in the program (as opposed to something like -``disk full''), then it is certainly a bug. - - If Emacs updates the display in a way that does not correspond to what is -in the buffer, then it is certainly a bug. If a command seems to do the -wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a -case of incorrect display updating. - - Taking forever to complete a command can be a bug, but you must make -certain that it was really Emacs's fault. Some commands simply take a -long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} -to see whether the input Emacs received was what you intended to type; -if the input was such that you @emph{know} it should have been processed -quickly, report a bug. If you don't know whether the command should -take a long time, find out by looking in the manual or by asking for -assistance. - - If a command you are familiar with causes an Emacs error message in a -case where its usual definition ought to be reasonable, it is probably a -bug. - - If a command does the wrong thing, that is a bug. But be sure you know -for certain what it ought to have done. If you aren't familiar with the -command, or don't know for certain how the command is supposed to work, -then it might actually be working right. Rather than jumping to -conclusions, show the problem to someone who knows for certain. - - Finally, a command's intended definition may not be the best -possible definition for editing with. This is a very important sort -of problem, but it is also a matter of judgment. Also, it is easy to -come to such a conclusion out of ignorance of some of the existing -features. It is probably best not to complain about such a problem -until you have checked the documentation in the usual ways, feel -confident that you understand it, and know for certain that what you -want is not available. Ask other Emacs users, too. If you are not -sure what the command is supposed to do after a careful reading of the -manual, check the index and glossary for any terms that may be -unclear. - - If after careful rereading of the manual you still do not understand -what the command should do, that indicates a bug in the manual, which -you should report. The manual's job is to make everything clear to -people who are not Emacs experts---including you. It is just as -important to report documentation bugs as program bugs. - - If the on-line documentation string of a function or variable disagrees -with the manual, one of them must be wrong; that is a bug. - -@node Understanding Bug Reporting -@subsection Understanding Bug Reporting - -@findex emacs-version - When you decide that there is a bug, it is important to report it and to -report it in a way which is useful. What is most useful is an exact -description of what commands you type, starting with the shell command to -run Emacs, until the problem happens. - - The most important principle in reporting a bug is to report -@emph{facts}. Hypotheses and verbal descriptions are no substitute for -the detailed raw data. Reporting the facts is straightforward, but many -people strain to posit explanations and report them instead of the -facts. If the explanations are based on guesses about how Emacs is -implemented, they will be useless; meanwhile, lacking the facts, we will -have no real information about the bug. - - For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh -@key{RET}}, visiting a file which (you know) happens to be rather -large, and Emacs displays @samp{I feel pretty today}. The best way to -report the bug is with a sentence like the preceding one, because it -gives all the facts. - - A bad way would be to assume that the problem is due to the size of -the file and say, ``I visited a large file, and Emacs displayed @samp{I -feel pretty today}.'' This is what we mean by ``guessing -explanations.'' The problem is just as likely to be due to the fact -that there is a @samp{z} in the file name. If this is so, then when we -got your report, we would try out the problem with some ``large file,'' -probably with no @samp{z} in its name, and not see any problem. There -is no way in the world that we could guess that we should try visiting a -file with a @samp{z} in its name. - - Alternatively, the problem might be due to the fact that the file starts -with exactly 25 spaces. For this reason, you should make sure that you -inform us of the exact contents of any file that is needed to reproduce the -bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} -command previously? This is why we ask you to give the exact sequence of -characters you typed since starting the Emacs session. - - You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless -you @emph{know} that it makes no difference which visiting command is used. -Similarly, rather than saying ``if I have three characters on the line,'' -say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is -the way you entered the text. - - So please don't guess any explanations when you report a bug. If you -want to actually @emph{debug} the problem, and report explanations that -are more than guesses, that is useful---but please include the facts as -well. - -@node Checklist -@subsection Checklist for Bug Reports - -@cindex reporting bugs - The best way to send a bug report is to mail it electronically to the -Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}, or to -@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta -release. (If you want to suggest a change as an improvement, use the -same address.) - - If you'd like to read the bug reports, you can find them on the -newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a -spectator you should not criticize anything about what you see there. -The purpose of bug reports is to give information to the Emacs -maintainers. Spectators are welcome only as long as they do not -interfere with this. In particular, some bug reports contain fairly -large amounts of data; spectators should not complain about this. - - Please do not post bug reports using netnews; mail is more reliable -than netnews about reporting your correct address, which we may need -in order to ask you for more information. If your data is more than -500,000 bytes, please don't include it directly in the bug report; -instead, offer to send it on request, or make it available by ftp and -say where. - -@findex report-emacs-bug - A convenient way to send a bug report for Emacs is to use the command -@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending -Mail}) and automatically inserts @emph{some} of the essential -information. However, it cannot supply all the necessary information; -you should still read and follow the guidelines below, so you can enter -the other crucial information by hand before you send the message. - - To enable maintainers to investigate a bug, your report -should include all these things: - -@itemize @bullet -@item -The version number of Emacs. Without this, we won't know whether there -is any point in looking for the bug in the current version of GNU -Emacs. - -You can get the version number by typing @kbd{M-x emacs-version -@key{RET}}. If that command does not work, you probably have something -other than GNU Emacs, so you will have to report the bug somewhere -else. - -@item -The type of machine you are using, and the operating system name and -version number. @kbd{M-x emacs-version @key{RET}} provides this -information too. Copy its output from the @samp{*Messages*} buffer, so -that you get it all and get it accurately. - -@item -The operands given to the @code{configure} command when Emacs was -installed. - -@item -A complete list of any modifications you have made to the Emacs source. -(We may not have time to investigate the bug unless it happens in an -unmodified Emacs. But if you've made modifications and you don't tell -us, you are sending us on a wild goose chase.) - -Be precise about these changes. A description in English is not -enough---send a context diff for them. - -Adding files of your own, or porting to another machine, is a -modification of the source. - -@item -Details of any other deviations from the standard procedure for installing -GNU Emacs. - -@item -The complete text of any files needed to reproduce the bug. - - If you can tell us a way to cause the problem without visiting any files, -please do so. This makes it much easier to debug. If you do need files, -make sure you arrange for us to see their exact contents. For example, it -can matter whether there are spaces at the ends of lines, or a -newline after the last line in the buffer (nothing ought to care whether -the last line is terminated, but try telling the bugs that). - -@item -The precise commands we need to type to reproduce the bug. - -@findex open-dribble-file -@cindex dribble file -@cindex logging keystrokes -The easy way to record the input to Emacs precisely is to write a -dribble file. To start the file, execute the Lisp expression - -@example -(open-dribble-file "~/dribble") -@end example - -@noindent -using @kbd{M-:} or from the @samp{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all your input to the -specified dribble file until the Emacs process is killed. - -@item -@findex open-termscript -@cindex termscript file -@cindex @env{TERM} environment variable -For possible display bugs, the terminal type (the value of environment -variable @env{TERM}), the complete termcap entry for the terminal from -@file{/etc/termcap} (since that file is not identical on all machines), -and the output that Emacs actually sent to the terminal. - -The way to collect the terminal output is to execute the Lisp expression - -@example -(open-termscript "~/termscript") -@end example - -@noindent -using @kbd{M-:} or from the @samp{*scratch*} buffer just after -starting Emacs. From then on, Emacs copies all terminal output to the -specified termscript file as well, until the Emacs process is killed. -If the problem happens when Emacs starts up, put this expression into -your @file{.emacs} file so that the termscript file will be open when -Emacs displays the screen for the first time. - -Be warned: it is often difficult, and sometimes impossible, to fix a -terminal-dependent bug without access to a terminal of the type that -stimulates the bug. - -@item -If non-@acronym{ASCII} text or internationalization is relevant, the locale that -was current when you started Emacs. On GNU/Linux and Unix systems, or -if you use a Posix-style shell such as Bash, you can use this shell -command to view the relevant values: - -@smallexample -echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ - LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG -@end smallexample - -Alternatively, use the @command{locale} command, if your system has it, -to display your locale settings. - -You can use the @kbd{M-!} command to execute these commands from -Emacs, and then copy the output from the @samp{*Messages*} buffer into -the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL -@key{RET}} will display the value of @code{LC_ALL} in the echo area, and -you can copy its output from the @samp{*Messages*} buffer. - -@item -A description of what behavior you observe that you believe is -incorrect. For example, ``The Emacs process gets a fatal signal,'' or, -``The resulting text is as follows, which I think is wrong.'' - -Of course, if the bug is that Emacs gets a fatal signal, then one can't -miss it. But if the bug is incorrect text, the maintainer might fail to -notice what is wrong. Why leave it to chance? - -Even if the problem you experience is a fatal signal, you should still -say so explicitly. Suppose something strange is going on, such as, your -copy of the source is out of sync, or you have encountered a bug in the -C library on your system. (This has happened!) Your copy might crash -and the copy here might not. If you @emph{said} to expect a crash, then -when Emacs here fails to crash, we would know that the bug was not -happening. If you don't say to expect a crash, then we would not know -whether the bug was happening---we would not be able to draw any -conclusion from our observations. - -@item -If the bug is that the Emacs Manual or the Emacs Lisp Reference Manual -fails to describe the actual behavior of Emacs, or that the text is -confusing, copy in the text from the online manual which you think is -at fault. If the section is small, just the section name is enough. - -@item -If the manifestation of the bug is an Emacs error message, it is -important to report the precise text of the error message, and a -backtrace showing how the Lisp program in Emacs arrived at the error. - -To get the error message text accurately, copy it from the -@samp{*Messages*} buffer into the bug report. Copy all of it, not just -part. - -@findex toggle-debug-on-error -@pindex Edebug -To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} -before the error happens (that is to say, you must give that command -and then make the bug happen). This causes the error to start the Lisp -debugger, which shows you a backtrace. Copy the text of the -debugger's backtrace into the bug report. @xref{Debugger,, The Lisp -Debugger, elisp, the Emacs Lisp Reference Manual}, for information on -debugging Emacs Lisp programs with the Edebug package. - -This use of the debugger is possible only if you know how to make the -bug happen again. If you can't make it happen again, at least copy -the whole error message. - -@item -Check whether any programs you have loaded into the Lisp world, -including your @file{.emacs} file, set any variables that may affect the -functioning of Emacs. Also, see whether the problem happens in a -freshly started Emacs without loading your @file{.emacs} file (start -Emacs with the @code{-q} switch to prevent loading the init file). If -the problem does @emph{not} occur then, you must report the precise -contents of any programs that you must load into the Lisp world in order -to cause the problem to occur. - -@item -If the problem does depend on an init file or other Lisp programs that -are not part of the standard Emacs system, then you should make sure it -is not a bug in those programs by complaining to their maintainers -first. After they verify that they are using Emacs in a way that is -supposed to work, they should report the bug. - -@item -If you wish to mention something in the GNU Emacs source, show the line -of code with a few lines of context. Don't just give a line number. - -The line numbers in the development sources don't match those in your -sources. It would take extra work for the maintainers to determine what -code is in your version at a given line number, and we could not be -certain. - -@item -Additional information from a C debugger such as GDB might enable -someone to find a problem on a machine which he does not have available. -If you don't know how to use GDB, please read the GDB manual---it is not -very long, and using GDB is easy. You can find the GDB distribution, -including the GDB manual in online form, in most of the same places you -can find the Emacs distribution. To run Emacs under GDB, you should -switch to the @file{src} subdirectory in which Emacs was compiled, then -do @samp{gdb emacs}. It is important for the directory @file{src} to be -current so that GDB will read the @file{.gdbinit} file in this -directory. - -However, you need to think when you collect the additional information -if you want it to show what causes the bug. - -@cindex backtrace for bug reports -For example, many people send just a backtrace, but that is not very -useful by itself. A simple backtrace with arguments often conveys -little about what is happening inside GNU Emacs, because most of the -arguments listed in the backtrace are pointers to Lisp objects. The -numeric values of these pointers have no significance whatever; all that -matters is the contents of the objects they point to (and most of the -contents are themselves pointers). - -@findex debug_print -To provide useful information, you need to show the values of Lisp -objects in Lisp notation. Do this for each variable which is a Lisp -object, in several stack frames near the bottom of the stack. Look at -the source to see which variables are Lisp objects, because the debugger -thinks of them as integers. - -To show a variable's value in Lisp syntax, first print its value, then -use the user-defined GDB command @code{pr} to print the Lisp object in -Lisp syntax. (If you must use another debugger, call the function -@code{debug_print} with the object as an argument.) The @code{pr} -command is defined by the file @file{.gdbinit}, and it works only if you -are debugging a running process (not with a core dump). - -To make Lisp errors stop Emacs and return to GDB, put a breakpoint at -@code{Fsignal}. - -For a short listing of Lisp functions running, type the GDB -command @code{xbacktrace}. - -The file @file{.gdbinit} defines several other commands that are useful -for examining the data types and contents of Lisp objects. Their names -begin with @samp{x}. These commands work at a lower level than -@code{pr}, and are less convenient, but they may work even when -@code{pr} does not, such as when debugging a core dump or when Emacs has -had a fatal signal. - -@cindex debugging Emacs, tricks and techniques -More detailed advice and other useful techniques for debugging Emacs -are available in the file @file{etc/DEBUG} in the Emacs distribution. -That file also includes instructions for investigating problems -whereby Emacs stops responding (many people assume that Emacs is -``hung,'' whereas in fact it might be in an infinite loop). - -To find the file @file{etc/DEBUG} in your Emacs installation, use the -directory name stored in the variable @code{data-directory}. -@end itemize - -Here are some things that are not necessary in a bug report: - -@itemize @bullet -@item -A description of the envelope of the bug---this is not necessary for a -reproducible bug. - -Often people who encounter a bug spend a lot of time investigating -which changes to the input file will make the bug go away and which -changes will not affect it. - -This is often time-consuming and not very useful, because the way we -will find the bug is by running a single example under the debugger -with breakpoints, not by pure deduction from a series of examples. -You might as well save time by not searching for additional examples. -It is better to send the bug report right away, go back to editing, -and find another bug to report. - -Of course, if you can find a simpler example to report @emph{instead} of -the original one, that is a convenience. Errors in the output will be -easier to spot, running under the debugger will take less time, etc. - -However, simplification is not vital; if you can't do this or don't have -time to try, please report the bug with your original test case. - -@item -A core dump file. - -Debugging the core dump might be useful, but it can only be done on -your machine, with your Emacs executable. Therefore, sending the core -dump file to the Emacs maintainers won't be useful. Above all, don't -include the core file in an email bug report! Such a large message -can be extremely inconvenient. - -@item -A system-call trace of Emacs execution. - -System-call traces are very useful for certain special kinds of -debugging, but in most cases they give little useful information. It is -therefore strange that many people seem to think that @emph{the} way to -report information about a crash is to send a system-call trace. Perhaps -this is a habit formed from experience debugging programs that don't -have source code or debugging symbols. - -In most programs, a backtrace is normally far, far more informative than -a system-call trace. Even in Emacs, a simple backtrace is generally -more informative, though to give full information you should supplement -the backtrace by displaying variable values and printing them as Lisp -objects with @code{pr} (see above). - -@item -A patch for the bug. - -A patch for the bug is useful if it is a good one. But don't omit the -other information that a bug report needs, such as the test case, on the -assumption that a patch is sufficient. We might see problems with your -patch and decide to fix the problem another way, or we might not -understand it at all. And if we can't understand what bug you are -trying to fix, or why your patch should be an improvement, we mustn't -install it. - -@ifnottex -@xref{Sending Patches}, for guidelines on how to make it easy for us to -understand and install your patches. -@end ifnottex - -@item -A guess about what the bug is or what it depends on. - -Such guesses are usually wrong. Even experts can't guess right about -such things without first using the debugger to find the facts. -@end itemize - -@node Sending Patches -@subsection Sending Patches for GNU Emacs - -@cindex sending patches for GNU Emacs -@cindex patches, sending - If you would like to write bug fixes or improvements for GNU Emacs, -that is very helpful. When you send your changes, please follow these -guidelines to make it easy for the maintainers to use them. If you -don't follow these guidelines, your information might still be useful, -but using it will take extra work. Maintaining GNU Emacs is a lot of -work in the best of circumstances, and we can't keep up unless you do -your best to help. - -@itemize @bullet -@item -Send an explanation with your changes of what problem they fix or what -improvement they bring about. For a bug fix, just include a copy of the -bug report, and explain why the change fixes the bug. - -(Referring to a bug report is not as good as including it, because then -we will have to look it up, and we have probably already deleted it if -we've already fixed the bug.) - -@item -Always include a proper bug report for the problem you think you have -fixed. We need to convince ourselves that the change is right before -installing it. Even if it is correct, we might have trouble -understanding it if we don't have a way to reproduce the problem. - -@item -Include all the comments that are appropriate to help people reading the -source in the future understand why this change was needed. - -@item -Don't mix together changes made for different reasons. -Send them @emph{individually}. - -If you make two changes for separate reasons, then we might not want to -install them both. We might want to install just one. If you send them -all jumbled together in a single set of diffs, we have to do extra work -to disentangle them---to figure out which parts of the change serve -which purpose. If we don't have time for this, we might have to ignore -your changes entirely. - -If you send each change as soon as you have written it, with its own -explanation, then two changes never get tangled up, and we can consider -each one properly without any extra work to disentangle them. - -@item -Send each change as soon as that change is finished. Sometimes people -think they are helping us by accumulating many changes to send them all -together. As explained above, this is absolutely the worst thing you -could do. - -Since you should send each change separately, you might as well send it -right away. That gives us the option of installing it immediately if it -is important. - -@item -Use @samp{diff -c} to make your diffs. Diffs without context are hard -to install reliably. More than that, they are hard to study; we must -always study a patch to decide whether we want to install it. Unidiff -format is better than contextless diffs, but not as easy to read as -@samp{-c} format. - -If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when -making diffs of C code. This shows the name of the function that each -change occurs in. - -@item -Avoid any ambiguity as to which is the old version and which is the new. -Please make the old version the first argument to diff, and the new -version the second argument. And please give one version or the other a -name that indicates whether it is the old version or your new changed -one. - -@item -Write the change log entries for your changes. This is both to save us -the extra work of writing them, and to help explain your changes so we -can understand them. - -The purpose of the change log is to show people where to find what was -changed. So you need to be specific about what functions you changed; -in large functions, it's often helpful to indicate where within the -function the change was. - -On the other hand, once you have shown people where to find the change, -you need not explain its purpose in the change log. Thus, if you add a -new function, all you need to say about it is that it is new. If you -feel that the purpose needs explaining, it probably does---but put the -explanation in comments in the code. It will be more useful there. - -Please read the @file{ChangeLog} files in the @file{src} and -@file{lisp} directories to see what sorts of information to put in, -and to learn the style that we use. @xref{Change Log}. - -@item -When you write the fix, keep in mind that we can't install a change that -would break other systems. Please think about what effect your change -will have if compiled on another type of system. - -Sometimes people send fixes that @emph{might} be an improvement in -general---but it is hard to be sure of this. It's hard to install -such changes because we have to study them very carefully. Of course, -a good explanation of the reasoning by which you concluded the change -was correct can help convince us. - -The safest changes are changes to the configuration files for a -particular machine. These are safe because they can't create new bugs -on other machines. - -Please help us keep up with the workload by designing the patch in a -form that is clearly safe to install. -@end itemize - -@node Contributing, Service, Bugs, Top -@section Contributing to Emacs Development - -If you would like to help pretest Emacs releases to assure they work -well, or if you would like to work on improving Emacs, please contact -the maintainers at @email{emacs-devel@@gnu.org}. A pretester -should be prepared to investigate bugs as well as report them. If you'd -like to work on improving Emacs, please ask for suggested projects or -suggest your own ideas. - -If you have already written an improvement, please tell us about it. If -you have not yet started work, it is useful to contact -@email{emacs-devel@@gnu.org} before you start; it might be -possible to suggest ways to make your extension fit in better with the -rest of Emacs. - -The development version of Emacs can be downloaded from the CVS -repository where it is actively maintained by a group of developers. -See the Emacs project page -@url{http://savannah.gnu.org/projects/emacs/} for details. - -@node Service, Copying, Contributing, Top -@section How To Get Help with GNU Emacs - -If you need help installing, using or changing GNU Emacs, there are two -ways to find it: - -@itemize @bullet -@item -Send a message to the mailing list -@email{help-gnu-emacs@@gnu.org}, or post your request on -newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup -interconnect, so it does not matter which one you use.) - -@item -Look in the service directory for someone who might help you for a fee. -The service directory is found in the file named @file{etc/SERVICE} in the -Emacs distribution. -@end itemize - -@ifnottex -@lowersections -@end ifnottex - -@ignore - arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c -@end ignore diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi deleted file mode 100644 index fe6ab3bf539..00000000000 --- a/doc/emacs/vc-xtra.texi +++ /dev/null @@ -1,30 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included in emacs-xtra.texi when producing the printed -@c version. -@iftex -@node Advanced VC Usage -@section Advanced VC Usage - - Commonly used features of Emacs' version control (VC) support are -described in the main Emacs manual (@pxref{Version Control,,,emacs, -the Emacs Manual}). This chapter describes more advanced VC usage. - -@menu -* Remote Repositories:: Efficient access to remote VCS servers. -* Revision Tags:: Symbolic names for revisions. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end menu -@end iftex - -@iftex -@include vc1-xtra.texi -@end iftex - -@ignore - arch-tag: 11a18d0e-1baf-49da-8e38-f61195ae4dc3 -@end ignore diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi deleted file mode 100644 index 0e9cf152a4d..00000000000 --- a/doc/emacs/vc1-xtra.texi +++ /dev/null @@ -1,793 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@c -@c This file is included either in vc-xtra.texi (when producing the -@c printed version) or in the main Emacs manual (for the on-line version). - -@node Remote Repositories -@subsection Remote Repositories -@cindex remote repositories - - A common way of using CVS and other more advanced VCSes is to set up -a central repository on some Internet host, then have each -developer check out a personal working copy of the files on his local -machine. Committing changes to the repository, and picking up changes -from other users into one's own working area, then works by direct -interactions with the repository server. - - One difficulty is that access to a repository server is often slow, -and that developers might need to work off-line as well. While only -third-generation decentralized VCses such as GNU Arch or Mercurial -really solve this problem, VC is designed to reduce the amount of -network interaction necessary. - - If you are using a truly decentralized VCS you can skip the rest of -this section. It describes backup and local-repository techniques -that are only useful for Subversion and earlier VCSes. - -@menu -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. -@end menu - -@node Version Backups -@subsubsection Version Backups -@cindex version backups - -@cindex automatic version backups - When VC sees that the repository for a file is on a remote -machine, it automatically makes local backups of unmodified versions -of the file---@dfn{automatic version backups}. This means that you -can compare the file to the repository version (@kbd{C-x v =}), or -revert to that version (@kbd{C-x v u}), without any network -interactions. - - The local copy of the unmodified file is called a @dfn{version -backup} to indicate that it corresponds exactly to a version that is -stored in the repository. Note that version backups are not the same -as ordinary Emacs backup files -@iftex -(@pxref{Backup,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Backup}). -@end ifnottex -But they follow a similar naming convention. - - For a file that comes from a remote repository, VC makes a -version backup whenever you save the first changes to the file, and -removes it after you have committed your modified version to the -repository. You can disable the making of automatic version backups by -setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). - -@cindex manual version backups - The name of the automatic version backup for version @var{version} -of file @var{file} is @code{@var{file}.~@var{version}.~}. This is -almost the same as the name used by @kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Revisions}), -@end ifnottex -the only difference being the additional dot (@samp{.}) after the -version number. This similarity is intentional, because both kinds of -files store the same kind of information. The file made by @kbd{C-x v -~} acts as a @dfn{manual version backup}. - - All the VC commands that operate on old versions of a file can use -both kinds of version backups. For instance, @kbd{C-x v ~} uses -either an automatic or a manual version backup, if possible, to get -the contents of the version you request. Likewise, @kbd{C-x v =} and -@kbd{C-x v u} use either an automatic or a manual version backup, if -one of them exists, to get the contents of a version to compare or -revert to. If you changed a file outside of Emacs, so that no -automatic version backup was created for the previous text, you can -create a manual backup of that version using @kbd{C-x v ~}, and thus -obtain the benefit of the local copy for Emacs commands. - - The only difference in Emacs's handling of manual and automatic -version backups, once they exist, is that Emacs deletes automatic -version backups when you commit to the repository. By contrast, -manual version backups remain until you delete them. - -@node Local Version Control -@subsubsection Local Version Control -@cindex local version control -@cindex local back end (version control) - -When you make many changes to a file that comes from a remote -repository, it can be convenient to have version control on your local -machine as well. You can then record intermediate versions, revert to -a previous state, etc., before you actually commit your changes to the -remote server. - -VC lets you do this by putting a file under a second, local version -control system, so that the file is effectively registered in two -systems at the same time. For the description here, we will assume -that the remote system is CVS, and you use RCS locally, although the -mechanism works with any combination of version control systems -(@dfn{back ends}). - -To make it work with other back ends, you must make sure that the -``more local'' back end comes before the ``more remote'' back end in -the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By -default, this variable is set up so that you can use remote CVS and -local RCS as described here. - -To start using local RCS for a file that comes from a remote CVS -server, you must @emph{register the file in RCS}, by typing @kbd{C-u -C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a -prefix argument, and specify RCS as the back end.) - -You can do this at any time; it does not matter whether you have -already modified the file with respect to the version in the CVS -repository. If possible, VC tries to make the RCS master start with -the unmodified repository version, then checks in any local changes -as a new version. This works if you have not made any changes yet, or -if the unmodified repository version exists locally as a version -backup (@pxref{Version Backups}). If the unmodified version is not -available locally, the RCS master starts with the modified version; -the only drawback to this is that you cannot compare your changes -locally to what is stored in the repository. - -The version number of the RCS master is derived from the current CVS -version, starting a branch from it. For example, if the current CVS -version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in -the RCS master will be identical to version 1.23 under CVS; your first -changes are checked in as 1.23.1.1. (If the unmodified file is not -available locally, VC will check in the modified file twice, both as -1.23 and 1.23.1.1, to make the revision numbers consistent.) - -If you do not use locking under CVS (the default), locking is also -disabled for RCS, so that editing under RCS works exactly as under -CVS. - -When you are done with local editing, you can commit the final version -back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. -This initializes the log entry buffer -@iftex -(@pxref{Log Buffer,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Log Buffer}) -@end ifnottex -to contain all the log entries you have recorded in the RCS master; -you can edit them as you wish, and then commit in CVS by typing -@kbd{C-c C-c}. If the commit is successful, VC removes the RCS -master, so that the file is once again registered under CVS only. -(The RCS master is not actually deleted, just renamed by appending -@samp{~} to the name, so that you can refer to it later if you wish.) - -While using local RCS, you can pick up recent changes from the CVS -repository into your local file, or commit some of your changes back -to CVS, without terminating local RCS version control. To do this, -switch to the CVS back end temporarily, with the @kbd{C-x v b} command: - -@table @kbd -@item C-x v b -Switch to another back end that the current file is registered -under (@code{vc-switch-backend}). - -@item C-u C-x v b @var{backend} @key{RET} -Switch to @var{backend} for the current file. -@end table - -@kindex C-x v b -@findex vc-switch-backend -@kbd{C-x v b} does not change the buffer contents, or any files; it -only changes VC's perspective on how to handle the file. Any -subsequent VC commands for that file will operate on the back end that -is currently selected. - -If the current file is registered in more than one back end, typing -@kbd{C-x v b} ``cycles'' through all of these back ends. With a -prefix argument, it asks for the back end to use in the minibuffer. - -Thus, if you are using local RCS, and you want to pick up some recent -changes in the file from remote CVS, first visit the file, then type -@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m -@key{RET}} to merge the news -@iftex -(@pxref{Merging,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Merging}). -@end ifnottex -You can then switch back to RCS by typing @kbd{C-x v b} again, and -continue to edit locally. - -But if you do this, the revision numbers in the RCS master no longer -correspond to those of CVS. Technically, this is not a problem, but -it can become difficult to keep track of what is in the CVS repository -and what is not. So we suggest that you return from time to time to -CVS-only operation, by committing your local changes back to the -repository using @kbd{C-u C-x v v cvs @key{RET}}. - -@node Revision Tags -@subsection Revision Tags -@cindex tags and version control - - In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS) -@dfn{tag} is a named set of file versions (one for each registered -file) that you can treat as a unit. In a VCS with per-repository -version numbers (Subversion and most later ones) a tag is simply -a symbolic name for a revision. - - One important kind of tag is a @dfn{release}, a (theoretically) -stable version of the system that is ready for distribution to users. - -@menu -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. -@end menu - -@node Making Revision Tags -@subsubsection Making and Using Revision Tags - - There are two basic commands for tags; one makes a -tag with a given name, the other retrieves a named tag. - -@table @code -@kindex C-x v s -@findex vc-create-tag -@item C-x v s @var{name} @key{RET} -Define the working revision of every registered file in or under the -current directory as a tag named @var{name} -(@code{vc-create-tag}). - -@kindex C-x v r -@findex vc-retrieve-tag -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, -retrieve the tagged revision @var{name}. This command will -switch to a branch if @var{name} is a branch name and your VCS -distinguishes branches from tags. -(@code{vc-retrieve-tag}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - -Tags are inexpensive, so you need not hesitate to create them whenever -they are useful. Branches vary in cost depending on your VCS; in -older ones they may be expensive. - - You can give a tag or branch name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Revisions}). -@end ifnottex -Thus, you can use it to compare a tagged version against the current files, -or two tagged versions against each other. - -@node Revision Tag Caveats -@subsubsection Revision Tag Caveats - - For SCCS, VC implements tags itself; these tags are visible only -through VC. Most later systems (including CVS, Subversion, bzr, git, -and hg) have a native tag facility, and VC uses it where -available; those tags will be visible even when you bypass VC. - - There is no support for VC tags using GNU Arch yet. - - Under older VCSes (SCCS, RCS, CVS, early versions of Subversion), -renaming and deletion could create some difficulties with tags. This is -not a VC-specific problem, but a general design issue in version -control systems that was not solved effectively until the earliest -third-generation systems. - - In a file-oriented VCS, when you rename a registered file you need -to rename its master along with it; the command @code{vc-rename-file} -will do this automatically. If you are using SCCS, you must also -update the records of the tag, to mention the file by its new name -(@code{vc-rename-file} does this, too). An old tag that refers to a -master file that no longer exists under the recorded name is invalid; -VC can no longer retrieve it. It would be beyond the scope of this -manual to explain enough about RCS and SCCS to explain how to update -the tags by hand. - - Using @code{vc-rename-file} makes the tag remain valid for -retrieval, but it does not solve all problems. For example, some of the -files in your program probably refer to others by name. At the very -least, the makefile probably mentions the file that you renamed. If you -retrieve an old tag, the renamed file is retrieved under its new -name, which is not the name that the makefile expects. So the program -won't really work as retrieved. - -@node Miscellaneous VC -@subsection Miscellaneous Commands and Features of VC - - This section explains the less-frequently-used features of VC. - -@menu -* Change Logs and VC:: Generating a change log file from log entries. -* Renaming and VC:: A command to rename both the source and master - file correctly. -* Version Headers:: Inserting version control headers into working files. -@end menu - -@node Change Logs and VC -@subsubsection Change Logs and VC - - If you use RCS or CVS for a program and also maintain a change log -file for it -@iftex -(@pxref{Change Log,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Change Log}), -@end ifnottex -you can generate change log entries automatically from the version -control log entries: - -@table @kbd -@item C-x v a -@kindex C-x v a -@findex vc-update-change-log -Visit the current directory's change log file and, for registered files -in that directory, create new entries for versions checked in since the -most recent entry in the change log file. -(@code{vc-update-change-log}). - -This command works with RCS or CVS only, not with any of the other -back ends. - -@item C-u C-x v a -As above, but only find entries for the current buffer's file. - -@item M-1 C-x v a -As above, but find entries for all the currently visited files that are -maintained with version control. This works only with RCS, and it puts -all entries in the log for the default directory, which may not be -appropriate. -@end table - - For example, suppose the first line of @file{ChangeLog} is dated -1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log -messages that start with `#'.}. Then @kbd{C-x v a} visits -@file{ChangeLog} and inserts text like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-22 Nathaniel Bowditch - - * rcs2log: Ignore log messages that start with `#'. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - -@noindent -You can then edit the new change log entry further as you wish. - - Some of the new change log entries may duplicate what's already in -ChangeLog. You will have to remove these duplicates by hand. - - Normally, the log entry for file @file{foo} is displayed as @samp{* -foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted -if the text of the log entry starts with @w{@samp{(@var{functionname}): -}}. For example, if the log entry for @file{vc.el} is -@samp{(vc-do-command): Check call-process status.}, then the text in -@file{ChangeLog} looks like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-06 Nathaniel Bowditch - - * vc.el (vc-do-command): Check call-process status. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - When @kbd{C-x v a} adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent check-ins have the following log -entries: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} -@end flushleft - -@noindent -They appear like this in @file{ChangeLog}: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch - - * vc.texinfo: Fix expansion typos. - - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - Normally, @kbd{C-x v a} separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label -itself is not copied to @file{ChangeLog}. For example, suppose the log -entries are: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} -@end flushleft - -@noindent -Then the text in @file{ChangeLog} looks like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch - - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - A log entry whose text begins with @samp{#} is not copied to -@file{ChangeLog}. For example, if you merely fix some misspellings in -comments, you can log the change with an entry beginning with @samp{#} -to avoid putting such trivia into @file{ChangeLog}. - -@node Renaming and VC -@subsubsection Renaming VC Work Files and Master Files - -@findex vc-rename-file - When you rename a registered file, you must also rename its master -file correspondingly to get proper results. Use @code{vc-rename-file} -to rename the source file as you specify, and rename its master file -accordingly. It also updates any tags (@pxref{Revision Tags}) that -mention the file, so that they use the new name; despite this, the -tag thus modified may not completely work (@pxref{Revision Tag Caveats}). - - Some back ends do not provide an explicit rename operation to their -repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} -on the original and renamed buffers and provide the necessary edit -log. - - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. - -@node Version Headers -@subsubsection Inserting Version Control Headers - - Sometimes it is convenient to put version identification strings -directly into working files. Certain special strings called -@dfn{version headers} are replaced in each successive version by the -number of that version, the name of the user who created it, and other -relevant information. All of the back ends that VC supports have such -a mechanism, except GNU Arch. - - VC does not normally use the information contained in these headers. -The exception is RCS---with RCS, version headers are sometimes more -reliable than the master file to determine which version of the file -you are editing. Note that in a multi-branch environment, version -headers are necessary to make VC behave correctly -@iftex -(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Multi-User Branching}). -@end ifnottex - - Searching for RCS version headers is controlled by the variable -@code{vc-consult-headers}. If it is non-@code{nil} (the default), -Emacs searches for headers to determine the version number you are -editing. Setting it to @code{nil} disables this feature. - - Note that although CVS uses the same kind of version headers as RCS -does, VC never searches for these headers if you are using CVS, -regardless of the above setting. - -@kindex C-x v h -@findex vc-insert-headers - You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to -insert a suitable header string. - -@table @kbd -@item C-x v h -Insert headers in a file for use with your version-control system. -@end table - -@vindex vc-@var{backend}-header - The default header string is @samp{@w{$}Id$} for RCS and -@samp{@w{%}W%} for SCCS. You can specify other headers to insert by -setting the variables @code{vc-@var{backend}-header} where -@var{backend} is @code{rcs} or @code{sccs}. - - Instead of a single string, you can specify a list of strings; then -each string in the list is inserted as a separate header on a line of -its own. - - It may be necessary to use apparently-superfluous backslashes when -writing the strings that you put in this variable. For instance, you -might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra -backslash prevents the string constant from being interpreted as a -header, if the Emacs Lisp file containing it is maintained with -version control. - -@vindex vc-comment-alist - Each header is inserted surrounded by tabs, inside comment delimiters, -on a new line at point. Normally the ordinary comment -start and comment end strings of the current mode are used, but for -certain modes, there are special comment delimiters for this purpose; -the variable @code{vc-comment-alist} specifies them. Each element of -this list has the form @code{(@var{mode} @var{starter} @var{ender})}. - -@vindex vc-static-header-alist - The variable @code{vc-static-header-alist} specifies further strings -to add based on the name of the buffer. Its value should be a list of -elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is inserted as part -of the header. A header line is inserted for each element that matches -the buffer name, and for each string specified by -@code{vc-@var{backend}-header}. The header line is made by processing the -string from @code{vc-@var{backend}-header} with the format taken from the -element. The default value for @code{vc-static-header-alist} is as follows: - -@example -@group -(("\\.c$" . - "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ -#endif /* lint */\n")) -@end group -@end example - -@noindent -It specifies insertion of text of this form: - -@example -@group - -#ifndef lint -static char vcid[] = "@var{string}"; -#endif /* lint */ -@end group -@end example - -@noindent -Note that the text above starts with a blank line. - - If you use more than one version header in a file, put them close -together in the file. The mechanism in @code{revert-buffer} that -preserves markers may not handle markers positioned between two version -headers. - -@node Customizing VC -@subsection Customizing VC - -@vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version -control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS BZR GIT HG Arch)}, so it contains all the version systems -that are currently supported. If you want VC to ignore one or more of -these systems, exclude its name from the list. To disable VC entirely, -set this variable to @code{nil}. - -The order of systems in the list is significant: when you visit a file -registered in more than one system (@pxref{Local Version Control}), VC -uses the system that comes first in @code{vc-handled-backends} by -default. The order is also significant when you register a file for -the first time, see -@iftex -@ref{Registering,,,emacs, the Emacs Manual}, -@end iftex -@ifnottex -@ref{Registering}, -@end ifnottex -for details. - -@menu -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end menu - -@node General VC Options -@subsubsection General Options - -@vindex vc-make-backup-files - Emacs normally does not save backup files for source files that are -maintained with version control. If you want to make backup files even -for files that use version control, set the variable -@code{vc-make-backup-files} to a non-@code{nil} value. - -@vindex vc-keep-workfiles - Normally the work file exists all the time, whether it is locked or -not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking -in a new version with @kbd{C-x v v} deletes the work file; but any -attempt to visit the file with Emacs creates it again. (With CVS, work -files are always kept.) - -@vindex vc-follow-symlinks - Editing a version-controlled file through a symbolic link can be -dangerous. It bypasses the version control system---you can edit the -file without locking it, and fail to check your changes in. Also, -your changes might overwrite those of another user. To protect against -this, VC checks each symbolic link that you visit, to see if it points -to a file under version control. - - The variable @code{vc-follow-symlinks} controls what to do when a -symbolic link points to a version-controlled file. If it is @code{nil}, -VC only displays a warning message. If it is @code{t}, VC automatically -follows the link, and visits the real file instead, telling you about -this in the echo area. If the value is @code{ask} (the default), VC -asks you each time whether to follow the link. - -@vindex vc-suppress-confirm - If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} -and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. (This -variable does not affect @kbd{C-x v c}; that operation is so drastic -that it should always ask for confirmation.) - -@vindex vc-command-messages - VC mode does much of its work by running the shell commands for RCS, -CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC -displays messages to indicate which shell commands it runs, and -additional messages when the commands finish. - -@vindex vc-path - You can specify additional directories to search for version control -programs by setting the variable @code{vc-path}. These directories -are searched before the usual search path. It is rarely necessary to -set this variable, because VC normally finds the proper files -automatically. - -@node RCS and SCCS -@subsubsection Options for RCS and SCCS - -@cindex non-strict locking (RCS) -@cindex locking, non-strict (RCS) - By default, RCS uses locking to coordinate the activities of several -users, but there is a mode called @dfn{non-strict locking} in which -you can check-in changes without locking the file first. Use -@samp{rcs -U} to switch to non-strict locking for a particular file, -see the @code{rcs} manual page for details. - - When deducing the version control state of an RCS file, VC first -looks for an RCS version header string in the file (@pxref{Version -Headers}). If there is no header string, VC normally looks at the -file permissions of the work file; this is fast. But there might be -situations when the file permissions cannot be trusted. In this case -the master file has to be consulted, which is rather expensive. Also -the master file can only tell you @emph{if} there's any lock on the -file, but not whether your work file really contains that locked -version. - -@vindex vc-consult-headers - You can tell VC not to use version headers to determine the file -status by setting @code{vc-consult-headers} to @code{nil}. VC then -always uses the file permissions (if it is supposed to trust them), or -else checks the master file. - -@vindex vc-mistrust-permissions - You can specify the criterion for whether to trust the file -permissions by setting the variable @code{vc-mistrust-permissions}. -Its value can be @code{t} (always mistrust the file permissions and -check the master file), @code{nil} (always trust the file -permissions), or a function of one argument which makes the decision. -The argument is the directory name of the @file{RCS} subdirectory. A -non-@code{nil} value from the function says to mistrust the file -permissions. If you find that the file permissions of work files are -changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. -Then VC always checks the master file to determine the file's status. - - VC determines the version control state of files under SCCS much as -with RCS. It does not consider SCCS version headers, though. Thus, -the variable @code{vc-mistrust-permissions} affects SCCS use, but -@code{vc-consult-headers} does not. - -@node CVS Options -@subsubsection Options specific for CVS - -@cindex locking (CVS) - By default, CVS does not use locking to coordinate the activities of -several users; anyone can change a work file at any time. However, -there are ways to restrict this, resulting in behavior that resembles -locking. - -@cindex CVSREAD environment variable (CVS) - For one thing, you can set the @env{CVSREAD} environment variable -(the value you use makes no difference). If this variable is defined, -CVS makes your work files read-only by default. In Emacs, you must -type @kbd{C-x v v} to make the file writable, so that editing works -in fact similar as if locking was used. Note however, that no actual -locking is performed, so several users can make their files writable -at the same time. When setting @env{CVSREAD} for the first time, make -sure to check out all your modules anew, so that the file protections -are set correctly. - -@cindex cvs watch feature -@cindex watching files (CVS) - Another way to achieve something similar to locking is to use the -@dfn{watch} feature of CVS. If a file is being watched, CVS makes it -read-only by default, and you must also use @kbd{C-x v v} in Emacs to -make it writable. VC calls @code{cvs edit} to make the file writable, -and CVS takes care to notify other developers of the fact that you -intend to change the file. See the CVS documentation for details on -using the watch feature. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local -@cindex remote repositories (CVS) - When a file's repository is on a remote machine, VC tries to keep -network interactions to a minimum. This is controlled by the variable -@code{vc-cvs-stay-local}. There is another variable, -@code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS. In the following, we will talk -only about @code{vc-cvs-stay-local}, but everything applies to -@code{vc-stay-local} as well. - -If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses -only the entry in the local CVS subdirectory to determine the file's -state (and possibly information returned by previous CVS commands). -One consequence of this is that when you have modified a file, and -somebody else has already checked in other changes to the file, you -are not notified of it until you actually try to commit. (But you can -try to pick up any recent changes from the repository first, using -@kbd{C-x v m @key{RET}}, -@iftex -@pxref{Merging,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -@pxref{Merging}). -@end ifnottex - - When @code{vc-cvs-stay-local} is @code{t}, VC also makes local -version backups, so that simple diff and revert operations are -completely local (@pxref{Version Backups}). - - On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, -then VC queries the remote repository @emph{before} it decides what to -do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. It also does not make any version backups. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. - -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. - -@ignore - arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 -@end ignore diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi deleted file mode 100644 index cda043c1b9d..00000000000 --- a/doc/emacs/windows.texi +++ /dev/null @@ -1,403 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Windows, Frames, Buffers, Top -@chapter Multiple Windows -@cindex windows in Emacs -@cindex multiple windows in Emacs - - Emacs can split a frame into two or many windows. Multiple windows -can display parts of different buffers, or different parts of one -buffer. Multiple frames always imply multiple windows, because each -frame has its own set of windows. Each window belongs to one and only -one frame. - -@menu -* Basic Window:: Introduction to Emacs windows. -* Split Window:: New windows are made by splitting existing windows. -* Other Window:: Moving to another window or doing something to it. -* Pop Up Window:: Finding a file or buffer in another window. -* Force Same Window:: Forcing certain buffers to appear in the selected - window rather than in another window. -* Change Window:: Deleting windows and changing their sizes. -* Window Convenience:: Convenience functions for window handling. -@end menu - -@node Basic Window -@section Concepts of Emacs Windows - - Each Emacs window displays one Emacs buffer at any time. A single -buffer may appear in more than one window; if it does, any changes in -its text are displayed in all the windows where it appears. But these -windows can show different parts of the buffer, because each window -has its own value of point. - -@cindex selected window - At any time, one Emacs window is the @dfn{selected window}; the -buffer this window is displaying is the current buffer. The terminal's -cursor shows the location of point in this window. Each other window -has a location of point as well. On text-only terminals, there is no -way to show where those locations are, since the terminal has only one -cursor. On a graphical display, the location of point in a -non-selected window is indicated by a hollow box; the cursor in the -selected window is blinking or solid. - - Commands to move point affect the value of point for the selected Emacs -window only. They do not change the value of point in other Emacs -windows, even those showing the same buffer. The same is true for commands -such as @kbd{C-x b} to switch buffers in the selected window; -they do not affect other windows at all. However, there are other commands -such as @kbd{C-x 4 b} that select a different window and switch buffers in -it. Also, all commands that display information in a window, including -(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} -(@code{list-buffers}), work by switching buffers in a nonselected window -without affecting the selected window. - - When multiple windows show the same buffer, they can have different -regions, because they can have different values of point. However, -they all have the same value for the mark, because each buffer has -only one mark position. - - Each window has its own mode line, which displays the buffer name, -modification status and major and minor modes of the buffer that is -displayed in the window. The selected window's mode line appears in a -different color. @xref{Mode Line}, for full details on the mode line. - -@node Split Window -@section Splitting Windows - -@table @kbd -@item C-x 2 -Split the selected window into two windows, one above the other -(@code{split-window-vertically}). -@item C-x 3 -Split the selected window into two windows positioned side by side -(@code{split-window-horizontally}). -@item C-Mouse-2 -In the mode line or scroll bar of a window, split that window. -@end table - -@kindex C-x 2 -@findex split-window-vertically - The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the -selected window into two windows, one above the other. Both windows start -out displaying the same buffer, with the same value of point. By default -the two windows each get half the height of the window that was split; a -numeric argument specifies how many lines to give to the top window. - -@kindex C-x 3 -@findex split-window-horizontally - @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected -window into two side-by-side windows. A numeric argument specifies how -many columns to give the one on the left. If you are not using -scrollbars, a vertical line separates the two windows. -You can customize its color with the face @code{vertical-border}. -Windows that are not the full width of the screen have mode lines, but -they are truncated. On terminals where Emacs does not support -highlighting, truncated mode lines sometimes do not appear in inverse -video. - -@kindex C-Mouse-2 @r{(scroll bar)} - You can split a window horizontally or vertically by clicking -@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of -splitting goes through the place where you click: if you click on the -mode line, the new scroll bar goes above the spot; if you click in the -scroll bar, the mode line of the split window is side by side with -your click. - -@vindex truncate-partial-width-windows - When a window occupies less than the full width of the frame, it may -become too narrow for most of the text lines in its buffer. If most of -its lines are continued (@pxref{Continuation Lines}), the buffer may -become difficult to read. Therefore, Emacs automatically truncates -lines if the window width becomes narrower than 50 columns. This -truncation occurs regardless of the value of the variable -@code{truncate-lines} (@pxref{Line Truncation}); it is instead -controlled by the variable @code{truncate-partial-width-windows}. If -the value of @code{truncate-partial-width-windows} is a positive integer -(the default is 50), that specifies the minimum width for a -partial-width window before automatic line truncation occurs; if the -value is @code{nil}, automatic line truncation is disabled; and for any -other non-@code{nil} value, Emacs truncates lines in every partial-width -window regardless of its width. - - Horizontal scrolling is often used in side-by-side windows. -@xref{Horizontal Scrolling}. - -@vindex split-window-keep-point - If @code{split-window-keep-point} is non-@code{nil}, the default, -both of the windows resulting from @kbd{C-x 2} inherit the value of -point from the window that was split. This means that scrolling is -inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to -avoid scrolling the text currently visible on the screen, by putting -point in each window at a position already visible in the window. It -also selects whichever window contains the screen line that the cursor -was previously on. Some users prefer that mode on slow terminals. - -@node Other Window -@section Using Other Windows - -@table @kbd -@item C-x o -Select another window (@code{other-window}). That is @kbd{o}, not zero. -@item C-M-v -Scroll the next window (@code{scroll-other-window}). -@item M-x compare-windows -Find next place where the text in the selected window does not match -the text in the next window. -@item Mouse-1 -@kbd{Mouse-1}, in a window's mode line, selects that window -but does not move point in it (@code{mouse-select-window}). -@end table - -@kindex C-x o -@findex other-window - To select a different window, click with @kbd{Mouse-1} on its mode -line. With the keyboard, you can switch windows by typing @kbd{C-x o} -(@code{other-window}). That is an @kbd{o}, for ``other,'' not a zero. -When there are more than two windows, this command moves through all the -windows in a cyclic order, generally top to bottom and left to right. -After the rightmost and bottommost window, it goes back to the one at -the upper left corner. A numeric argument means to move several steps -in the cyclic order of windows. A negative argument moves around the -cycle in the opposite order. When the minibuffer is active, the -minibuffer is the last window in the cycle; you can switch from the -minibuffer window to one of the other windows, and later switch back and -finish supplying the minibuffer argument that is requested. -@xref{Minibuffer Edit}. - -@kindex C-M-v -@findex scroll-other-window - The usual scrolling commands (@pxref{Display}) apply to the selected -window only, but there is one command to scroll the next window. -@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that -@kbd{C-x o} would select. It takes arguments, positive and negative, -like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window -that contains the minibuffer help display, if any, rather than the -next window in the standard cyclic order.) - - The command @kbd{M-x compare-windows} lets you compare two files or -buffers visible in two windows, by moving through them to the next -mismatch. @xref{Comparing Files}, for details. - -@vindex mouse-autoselect-window - If you set @code{mouse-autoselect-window} to a non-@code{nil} value, -moving the mouse into a different window selects that window. This -feature is off by default. - -@node Pop Up Window -@section Displaying in Another Window - -@cindex selecting buffers in other windows -@kindex C-x 4 - @kbd{C-x 4} is a prefix key for commands that select another window -(splitting the window if there is only one) and select a buffer in that -window. Different @kbd{C-x 4} commands have different ways of finding the -buffer to select. - -@table @kbd -@item C-x 4 b @var{bufname} @key{RET} -Select buffer @var{bufname} in another window. This runs -@code{switch-to-buffer-other-window}. -@item C-x 4 C-o @var{bufname} @key{RET} -Display buffer @var{bufname} in another window, but -don't select that buffer or that window. This runs -@code{display-buffer}. -@item C-x 4 f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another window. This -runs @code{find-file-other-window}. @xref{Visiting}. -@item C-x 4 d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another window. -This runs @code{dired-other-window}. @xref{Dired}. -@item C-x 4 m -Start composing a mail message in another window. This runs -@code{mail-other-window}; its same-window analogue is @kbd{C-x m} -(@pxref{Sending Mail}). -@item C-x 4 . -Find a tag in the current tags table, in another window. This runs -@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.} -(@pxref{Tags}). -@item C-x 4 r @var{filename} @key{RET} -Visit file @var{filename} read-only, and select its buffer in another -window. This runs @code{find-file-read-only-other-window}. -@xref{Visiting}. -@end table - -@vindex split-height-threshold -@vindex split-width-threshold - By default, these commands split the window vertically when there is -only one. You can customize the variables @code{split-height-threshold} -and @code{split-width-threshold} to split the window horizontally -instead. - - -@node Force Same Window -@section Forcing Display in the Same Window - - Certain Emacs commands switch to a specific buffer with special -contents. For example, @kbd{M-x shell} switches to a buffer named -@samp{*shell*}. By convention, all these commands are written to pop up -the buffer in a separate window. But you can specify that certain of -these buffers should appear in the selected window. - -@vindex same-window-buffer-names - If you add a buffer name to the list @code{same-window-buffer-names}, -the effect is that such commands display that particular buffer by -switching to it in the selected window. For example, if you add the -element @code{"*grep*"} to the list, the @code{grep} command will -display its output buffer in the selected window. - - The default value of @code{same-window-buffer-names} is not -@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and -@samp{*shell*} (as well as others used by more obscure Emacs packages). -This is why @kbd{M-x shell} normally switches to the @samp{*shell*} -buffer in the selected window. If you delete this element from the -value of @code{same-window-buffer-names}, the behavior of @kbd{M-x -shell} will change---it will pop up the buffer in another window -instead. - -@vindex same-window-regexps - You can specify these buffers more generally with the variable -@code{same-window-regexps}. Set it to a list of regular expressions; -then any buffer whose name matches one of those regular expressions is -displayed by switching to it in the selected window. (Once again, this -applies only to buffers that normally get displayed for you in a -separate window.) The default value of this variable specifies Telnet -and rlogin buffers. - - An analogous feature lets you specify buffers which should be -displayed in their own individual frames. @xref{Special Buffer Frames}. - -@node Change Window -@section Deleting and Rearranging Windows - -@table @kbd -@item C-x 0 -Delete the selected window (@code{delete-window}). The last character -in this key sequence is a zero. -@item C-x 1 -Delete all windows in the selected frame except the selected window -(@code{delete-other-windows}). -@item C-x 4 0 -Delete the selected window and kill the buffer that was showing in it -(@code{kill-buffer-and-window}). The last character in this key -sequence is a zero. -@item C-x ^ -Make selected window taller (@code{enlarge-window}). -@item C-x @} -Make selected window wider (@code{enlarge-window-horizontally}). -@item C-x @{ -Make selected window narrower (@code{shrink-window-horizontally}). -@item C-x - -Shrink this window if its buffer doesn't need so many lines -(@code{shrink-window-if-larger-than-buffer}). -@item C-x + -Make all windows the same height (@code{balance-windows}). -@end table - -@kindex C-x 0 -@findex delete-window - To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is -a zero.) The space occupied by the deleted window is given to an -adjacent window (but not the minibuffer window, even if that is active -at the time). Once a window is deleted, its attributes are forgotten; -only restoring a window configuration can bring it back. Deleting the -window has no effect on the buffer it used to display; the buffer -continues to exist, and you can select it in any window with @kbd{C-x -b}. - -@findex kill-buffer-and-window -@kindex C-x 4 0 - @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command -than @kbd{C-x 0}; it kills the current buffer and then deletes the -selected window. - -@kindex C-x 1 -@findex delete-other-windows - @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a -different way; it deletes all the windows except the selected one (and -the minibuffer); the selected window expands to use the whole frame -except for the echo area. - -@kindex C-x ^ -@findex enlarge-window -@kindex C-x @} -@findex enlarge-window-horizontally -@vindex window-min-height -@vindex window-min-width - To readjust the division of space among vertically adjacent windows, -use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently -selected window one line bigger, or as many lines as is specified -with a numeric argument. With a negative argument, it makes the -selected window smaller. @kbd{C-x @}} -(@code{enlarge-window-horizontally}) makes the selected window wider by -the specified number of columns. @kbd{C-x @{} -(@code{shrink-window-horizontally}) makes the selected window narrower -by the specified number of columns. - - When you make a window bigger, the space comes from its peers. If -this makes any window too small, it is deleted and its space is given -to an adjacent window. The minimum size is specified by the variables -@code{window-min-height} and @code{window-min-width}. - -@kindex C-x - -@findex shrink-window-if-larger-than-buffer - The command @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) -reduces the height of the selected window, if it is taller than -necessary to show the whole text of the buffer it is displaying. It -gives the extra lines to other windows in the frame. - -@kindex C-x + -@findex balance-windows - You can also use @kbd{C-x +} (@code{balance-windows}) to even out the -heights of all the windows in the selected frame. - - Mouse clicks on the mode line provide another way to change window -heights and to delete windows. @xref{Mode Line Mouse}. - -@node Window Convenience -@section Window Handling Convenience Features and Customization - -@findex winner-mode -@cindex Winner mode -@cindex mode, Winner -@cindex undoing window configuration changes -@cindex window configuration changes, undoing - @kbd{M-x winner-mode} is a global minor mode that records the -changes in the window configuration (i.e. how the frames are -partitioned into windows), so that you can ``undo'' them. To undo, -use @kbd{C-c left} (@code{winner-undo}). If you change your mind -while undoing, you can redo the changes you had undone using @kbd{C-c -right} (@code{M-x winner-redo}). Another way to enable Winner mode is -by customizing the variable @code{winner-mode}. - -@cindex Windmove package -@cindex directional window selection -@findex windmove-right -@findex windmove-default-keybindings - The Windmove commands move directionally between neighboring windows in -a frame. @kbd{M-x windmove-right} selects the window immediately to the -right of the currently selected one, and similarly for the ``left,'' ``up,'' -and ``down'' counterparts. @kbd{M-x windmove-default-keybindings} binds -these commands to @kbd{S-right} etc. (Not all terminals support shifted -arrow keys, however.) - - Follow minor mode (@kbd{M-x follow-mode}) synchronizes several -windows on the same buffer so that they always display adjacent -sections of that buffer. @xref{Follow Mode}. - -@vindex scroll-all-mode -@cindex scrolling windows together -@cindex Scroll-all mode -@cindex mode, Scroll-all - @kbd{M-x scroll-all-mode} provides commands to scroll all visible -windows together. You can also turn it on by customizing the variable -@code{scroll-all-mode}. The commands provided are @kbd{M-x -scroll-all-scroll-down-all}, @kbd{M-x scroll-all-page-down-all} and -their corresponding ``up'' equivalents. To make this mode useful, -you should bind these commands to appropriate keys. - -@ignore - arch-tag: 8bea7453-d4b1-49b1-9bf4-cfe4383e1113 -@end ignore diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi deleted file mode 100644 index a2deb1530ae..00000000000 --- a/doc/emacs/xresources.texi +++ /dev/null @@ -1,1195 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node X Resources, Antinews, Emacs Invocation, Top -@appendix X Options and Resources - - You can customize some X-related aspects of Emacs behavior using X -resources, as is usual for programs that use X. On MS-Windows, you -can customize some of the same aspects using the system registry. -@xref{MS-Windows Registry}. - - When Emacs is built using an ``X toolkit'', such as Lucid or -LessTif, you need to use X resources to customize the appearance of -the widgets, including the menu-bar, scroll-bar, and dialog boxes. -This is because the libraries that implement these don't provide for -customization through Emacs. GTK+ widgets use a separate system of -@ifnottex -``GTK resources'', which we will also describe. -@end ifnottex -@iftex -``GTK resources.'' In this chapter we describe the most commonly used -resource specifications. For full documentation, see the online -manual. - -@c Add xref for LessTif/Motif menu resources. -@end iftex - - -@menu -* Resources:: Using X resources with Emacs (in general). -* Table of Resources:: Table of specific X resources that affect Emacs. -* Face Resources:: X resources for customizing faces. -* Lucid Resources:: X resources for Lucid menus. -* LessTif Resources:: X resources for LessTif and Motif menus. -* GTK resources:: Resources for GTK widgets. -@end menu - -@node Resources -@appendixsec X Resources -@cindex resources -@cindex X resources -@cindex @file{~/.Xdefaults} file -@cindex @file{~/.Xresources} file - - Programs running under the X Window System organize their user -options under a hierarchy of classes and resources. You can specify -default values for these options in your @dfn{X resource file}, -usually named @file{~/.Xdefaults} or @file{~/.Xresources}. Changes in -this file do not take effect immediately, because the X server stores -its own list of resources; to update it, use the command -@command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. - -@cindex Registry (MS-Windows) - (MS-Windows systems do not support X resource files; on Windows, -Emacs looks for X resources in the Windows Registry, first under the -key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key -@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. The menu and scroll -bars are native widgets on MS-Windows, so they are only customizable -via the system-wide settings in the Display Control Panel. You can -also set resources using the @samp{-xrm} command line option, as -explained below.) - - Each line in the X resource file specifies a value for one option or -for a collection of related options. Each resource specification -consists of a @dfn{program name} and a @dfn{resource name}. Case -distinctions are significant in each of these names. Here is an -example: - -@example -emacs.borderWidth: 2 -@end example - -@ifnottex - The program name is the name of the executable file to which the -resource applies. For Emacs, this is normally @samp{emacs}. To -specify a definition that applies to all instances of Emacs, -regardless of the name of the Emacs executable, use @samp{Emacs}. - - The resource name is the name of a program setting. For instance, -Emacs recognizes a @samp{borderWidth} resource that controls the width -of the external border for graphical frames. - - Resources are grouped into named classes. For instance, the -@samp{BorderWidth} class contains both the @samp{borderWidth} resource -(which we just described), as well as the @samp{internalBorder} -resource, which controls the width of the internal border for -graphical frames. Instead of using a resource name, you can use a -class name to specify the same value for all resources in that class. -Here's an example: - -@example -emacs.BorderWidth: 2 -@end example - - If you specify a value for a class, it becomes the default for all -resources in that class. You can specify values for individual -resources as well; these override the class value, for those -particular resources. The following example specifies 2 as the -default width for all borders, but overrides this value with 4 for the -external border: - -@example -emacs.BorderWidth: 2 -emacs.borderWidth: 4 -@end example -@end ifnottex - - The order in which the lines appear in the file does not matter. -Also, command-line options always override the X resources file. - -@ifnottex - The following X command-line options affect how X resources are -processed: - -@table @samp -@item -name @var{name} -@opindex --name -@itemx --name=@var{name} -@cindex resource name, command-line argument -This option sets the program name of the initial Emacs frame to -@var{name}. It also sets the title of the initial frame to -@var{name}. This option does not affect subsequent frames. - -If you don't specify this option, the default is to use the Emacs -executable's name as the program name. - -For consistency, @samp{-name} also specifies the name to use for other -resource values that do not belong to any particular frame. - -The resources that name Emacs invocations also belong to a class, -named @samp{Emacs}. If you write @samp{Emacs} instead of -@samp{emacs}, the resource applies to all frames in all Emacs jobs, -regardless of frame titles and regardless of the name of the -executable file. - -@item -xrm @var{resource-values} -@opindex --xrm -@itemx --xrm=@var{resource-values} -@cindex resource values, command-line argument -This option specifies X resource values for the present Emacs job. - -@var{resource-values} should have the same format that you would use -inside a file of X resources. To include multiple resource -specifications in @var{resource-values}, put a newline between them, -just as you would in a file. You can also use @samp{#include -"@var{filename}"} to include a file full of resource specifications. -Resource values specified with @samp{-xrm} take precedence over all -other resource specifications. -@end table -@end ifnottex - - One way to experiment with the effect of different resource settings -is to use the @code{editres} program. See the @code{editres} man page -for more details. - -@node Table of Resources -@appendixsec Table of X Resources for Emacs - - This table lists the resource names that designate options for -Emacs, not counting those for the appearance of the menu bar, each -with the class that it belongs to: - -@table @asis -@item @code{background} (class @code{Background}) -Background color name. - -@ifnottex -@item @code{bitmapIcon} (class @code{BitmapIcon}) -Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window -manager choose an icon if @samp{off}. -@end ifnottex - -@item @code{borderColor} (class @code{BorderColor}) -Color name for the external border. - -@ifnottex -@item @code{borderWidth} (class @code{BorderWidth}) -Width in pixels of the external border. -@end ifnottex - -@item @code{cursorColor} (class @code{Foreground}) -Color name for text cursor (point). - -@ifnottex -@item @code{cursorBlink} (class @code{CursorBlink}) -Specifies whether to make the cursor blink. The default is @samp{on}. Use -@samp{off} or @samp{false} to turn cursor blinking off. -@end ifnottex - -@item @code{font} (class @code{Font}) -Font name for the @code{default} font. @xref{Font X}. You can also -specify a fontset name (@pxref{Fontsets}). - -@item @code{fontBackend} (class @code{FontBackend}) -The backend(s) to use for drawing fonts; if multiple backends are -specified, they must be comma-delimited and given in order of -precedence. On X, for instance, the value @samp{x,xft} tells Emacs to -draw fonts using the X core font driver, falling back on the Xft font -driver if that fails. Normally, you can leave this resource unset, in -which case Emacs tries using all font backends available on your -graphical device. - -@item @code{foreground} (class @code{Foreground}) -Color name for text. - -@item @code{geometry} (class @code{Geometry}) -Window size and position. Be careful not to specify this resource as -@samp{emacs*geometry}, because that may affect individual menus as well -as the Emacs frame itself. - -If this resource specifies a position, that position applies only to the -initial Emacs frame (or, in the case of a resource for a specific frame -name, only that frame). However, the size, if specified here, applies to -all frames. - -@ifnottex -@item @code{fullscreen} (class @code{Fullscreen}) -The desired fullscreen size. The value can be one of @code{fullboth}, -@code{fullwidth} or @code{fullheight}, which correspond to -the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh} -(@pxref{Window Size X}). - -Note that this applies to the initial frame only. -@end ifnottex - -@item @code{iconName} (class @code{Title}) -Name to display in the icon. - -@item @code{internalBorder} (class @code{BorderWidth}) -Width in pixels of the internal border. - -@item @code{lineSpacing} (class @code{LineSpacing}) -@cindex line spacing -@cindex leading -Additional space (@dfn{leading}) between lines, in pixels. - -@item @code{menuBar} (class @code{MenuBar}) -@cindex menu bar -Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. -@ifnottex -@xref{Lucid Resources}, and @ref{LessTif Resources}, -@end ifnottex -@iftex -@xref{Lucid Resources}, -@end iftex -for how to control the appearance of the menu bar if you have one. - -@ifnottex -@item @code{minibuffer} (class @code{Minibuffer}) -If @samp{none}, don't make a minibuffer in this frame. -It will use a separate minibuffer frame instead. - -@item @code{paneFont} (class @code{Font}) -@cindex font for menus -Font name for menu pane titles, in non-toolkit versions of Emacs. -@end ifnottex - -@item @code{pointerColor} (class @code{Foreground}) -Color of the mouse cursor. - -@ifnottex -@item @code{privateColormap} (class @code{PrivateColormap}) -If @samp{on}, use a private color map, in the case where the ``default -visual'' of class PseudoColor and Emacs is using it. - -@item @code{reverseVideo} (class @code{ReverseVideo}) -Switch foreground and background default colors if @samp{on}, use colors as -specified if @samp{off}. -@end ifnottex - -@item @code{screenGamma} (class @code{ScreenGamma}) -@cindex gamma correction -Gamma correction for colors, equivalent to the frame parameter -@code{screen-gamma}. - -@item @code{scrollBarWidth} (class @code{ScrollBarWidth}) -@cindex scrollbar width -The scroll bar width in pixels, equivalent to the frame parameter -@code{scroll-bar-width}. - -@ifnottex -@item @code{selectionFont} (class @code{SelectionFont}) -Font name for pop-up menu items, in non-toolkit versions of Emacs. (For -toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif -Resources}.) - -@item @code{selectionTimeout} (class @code{SelectionTimeout}) -Number of milliseconds to wait for a selection reply. -If the selection owner doesn't reply in this time, we give up. -A value of 0 means wait as long as necessary. - -@item @code{synchronous} (class @code{Synchronous}) -@cindex debugging X problems -@cindex synchronous X mode -Run Emacs in synchronous mode if @samp{on}. Synchronous mode is -useful for debugging X problems. -@end ifnottex - -@item @code{title} (class @code{Title}) -Name to display in the title bar of the initial Emacs frame. - -@item @code{toolBar} (class @code{ToolBar}) -@cindex tool bar -Number of lines to reserve for the tool bar. A zero value suppresses -the tool bar. If the value is non-zero and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size -will be changed automatically so that all tool bar items are visible. - If the value of @code{auto-resize-tool-bars} is @code{grow-only}, -the tool bar expands automatically, but does not contract automatically. -To contract the tool bar, you must redraw the frame by entering @kbd{C-l}. - -@item @code{useXIM} (class @code{UseXIM}) -@cindex XIM -@cindex X input methods -@cindex input methods, X -Turn off use of X input methods (XIM) if @samp{false} or @samp{off}. -This is only relevant if your Emacs is actually built with XIM -support. It is potentially useful to turn off XIM for efficiency, -especially slow X client/server links. - -@item @code{verticalScrollBars} (class @code{ScrollBars}) -Give frames scroll bars if @samp{on}; don't have scroll bars if -@samp{off}. - -@ifnottex -@item @code{visualClass} (class @code{VisualClass}) -Specify the ``visual'' that X should use. This tells X how to handle -colors. - -The value should start with one of @samp{TrueColor}, -@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor}, -@samp{GrayScale}, and @samp{StaticGray}, followed by -@samp{-@var{depth}}, where @var{depth} is the number of color planes. -Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo} -program outputs information saying which ones. -@end ifnottex -@end table - -@node Face Resources -@appendixsec X Resources for Faces - - You can use resources to customize the appearance of particular -faces (@pxref{Faces}): - -@table @code -@item @var{face}.attributeForeground -Foreground color for face @var{face}. -@item @var{face}.attributeBackground -Background color for face @var{face}. -@item @var{face}.attributeUnderline -Underline flag for face @var{face}. Use @samp{on} or @samp{true} for -yes. -@item @var{face}.attributeStrikeThrough -@itemx @var{face}.attributeOverline -@itemx @var{face}.attributeBox -@itemx @var{face}.attributeInverse -Likewise, for other boolean font attributes. -@item @var{face}.attributeStipple -The name of a pixmap data file to use for the stipple pattern, or -@code{false} to not use stipple for the face @var{face}. -@item @var{face}.attributeBackgroundPixmap -The background pixmap for the face @var{face}. Should be a name of a -pixmap file or @code{false}. -@item @var{face}.attributeFont -Font name (full XFD name or valid X abbreviation) for face @var{face}. -Instead of this, you can specify the font through separate attributes. -@end table - - Instead of using @code{attributeFont} to specify a font name, you can -select a font through these separate attributes: - -@table @code -@item @var{face}.attributeFamily -Font family for face @var{face}. -@item @var{face}.attributeHeight -Height of the font to use for face @var{face}: either an integer -specifying the height in units of 1/10@dmn{pt}, or a floating point -number that specifies a scale factor to scale the underlying face's -default font, or a function to be called with the default height which -will return a new height. -@item @var{face}.attributeWidth -@itemx @var{face}.attributeWeight -@itemx @var{face}.attributeSlant -Each of these resources corresponds to a like-named font attribute, -and you write the resource value the same as the symbol you would use -for the font attribute value. -@item @var{face}.attributeBold -Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for -yes. -@item @var{face}.attributeItalic -Italic flag for face @var{face}---instead of @code{attributeSlant}. -@end table - -@node Lucid Resources -@appendixsec Lucid Menu X Resources -@cindex Menu X Resources (Lucid widgets) -@cindex Lucid Widget X Resources - -@ifnottex - If the Emacs installed at your site was built to use the X toolkit -with the Lucid menu widgets, then the menu bar is a separate widget and -has its own resources. The resource names contain @samp{pane.menubar} -(following, as always, the name of the Emacs invocation, or @samp{Emacs}, -which stands for all Emacs invocations). Specify them like this: - -@example -Emacs.pane.menubar.@var{resource}: @var{value} -@end example - -@noindent -For example, to specify the font @samp{8x16} for the menu-bar items, -write this: -@end ifnottex -@iftex - If the Emacs installed at your site was built to use the X toolkit -with the Lucid menu widgets, then the menu bar is a separate widget -and has its own resources. The resource specifications start with -@samp{Emacs.pane.menubar}---for instance, to specify the font -@samp{8x16} for the menu-bar items, write this: -@end iftex - -@example -Emacs.pane.menubar.font: 8x16 -@end example - -@noindent -Resources for @emph{non-menubar} toolkit pop-up menus have -@samp{menu*} instead of @samp{pane.menubar}. For example, to specify -the font @samp{8x16} for the pop-up menu items, write this: - -@example -Emacs.menu*.font: 8x16 -@end example - -@noindent -For dialog boxes, use @samp{dialog*}: - -@example -Emacs.dialog*.font: 8x16 -@end example - -@noindent -The Lucid menus can display multilingual text in your locale. For -more information about fontsets see the man page for -@code{XCreateFontSet}. To enable multilingual menu text you specify a -@code{fontSet} resource instead of the font resource. If both -@code{font} and @code{fontSet} resources are specified, the -@code{fontSet} resource is used. - - Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*} -for both the popup and menu bar menus, write this: - -@example -Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* -@end example - -@noindent -The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and -@samp{menu@dots{}}. - -Experience shows that on some systems you may need to add -@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On -some other systems, you must not add @samp{shell.}. The generic wildcard -approach should work on both kinds of systems. - - Here is a list of the specific resources for menu bars and pop-up menus: - -@table @code -@item font -Font for menu item text. -@item fontSet -Fontset for menu item text. -@item foreground -Color of the foreground. -@item background -Color of the background. -@item buttonForeground -In the menu bar, the color of the foreground for a selected item. -@ifnottex -@item horizontalSpacing -Horizontal spacing in pixels between items. Default is 3. -@item verticalSpacing -Vertical spacing in pixels between items. Default is 2. -@item arrowSpacing -Horizontal spacing between the arrow (which indicates a submenu) and -the associated text. Default is 10. -@item shadowThickness -Thickness of shadow line around the widget. Default is 1. - -Also determines the thickness of shadow lines around other objects, -for instance 3D buttons and arrows. If you have the impression that -the arrows in the menus do not stand out clearly enough or that the -difference between ``in'' and ``out'' buttons is difficult to see, set -this to 2. If you have no problems with visibility, the default -probably looks better. The background color may also have some effect -on the contrast. -@end ifnottex -@item margin -The margin of the menu bar, in characters. Default is 1. -@end table - -@ifnottex -@node LessTif Resources -@appendixsec LessTif Menu X Resources -@cindex Menu X Resources (LessTif widgets) -@cindex LessTif Widget X Resources - - If the Emacs installed at your site was built to use the X toolkit -with the LessTif or Motif widgets, then the menu bar, the dialog -boxes, the pop-up menus, and the file-selection box are separate -widgets and have their own resources. - - The resource names for the menu bar contain @samp{pane.menubar} -(following, as always, the name of the Emacs invocation, or -@samp{Emacs}, which stands for all Emacs invocations). Specify them -like this: - -@smallexample -Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} -@end smallexample - - Each individual string in the menu bar is a subwidget; the subwidget's -name is the same as the menu item string. For example, the word -@samp{File} in the menu bar is part of a subwidget named -@samp{emacs.pane.menubar.File}. Most likely, you want to specify the -same resources for the whole menu bar. To do this, use @samp{*} instead -of a specific subwidget name. For example, to specify the font -@samp{8x16} for the menu-bar items, write this: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -@end smallexample - -@noindent -This also specifies the resource value for submenus. - - Each item in a submenu in the menu bar also has its own name for X -resources; for example, the @samp{File} submenu has an item named -@samp{Save (current buffer)}. A resource specification for a submenu -item looks like this: - -@smallexample -Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, here's how to specify the font for the @samp{Save (current -buffer)} item: - -@smallexample -Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 -@end smallexample - -@noindent -For an item in a second-level submenu, such as @samp{Complete Word} -under @samp{Spell Checking} under @samp{Tools}, the resource fits this -template: - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} -@end smallexample - -@noindent -For example, - -@smallexample -Emacs.pane.menubar.popup_*.popup_*.Spell Checking.Complete Word: @var{value} -@end smallexample - -@noindent -(This should be one long line.) - - It's impossible to specify a resource for all the menu-bar items -without also specifying it for the submenus as well. So if you want the -submenu items to look different from the menu bar itself, you must ask -for that in two steps. First, specify the resource for all of them; -then, override the value for submenus alone. Here is an example: - -@smallexample -Emacs.pane.menubar.*.fontList: 8x16 -Emacs.pane.menubar.popup_*.fontList: 8x16 -@end smallexample - -@noindent -For LessTif pop-up menus, use @samp{menu*} instead of -@samp{pane.menubar}. For example, to specify the font @samp{8x16} for -the pop-up menu items, write this: - -@smallexample -Emacs.menu*.fontList: 8x16 -@end smallexample - -@noindent -For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}: - -@example -Emacs.dialog*.fontList: 8x16 -Emacs.dialog*.foreground: hotpink -@end example - -To specify resources for the LessTif file-selection box, use -@samp{fsb*}, like this: - -@example -Emacs.fsb*.fontList: 8x16 -@end example - -@iftex -@medbreak -@end iftex - Here is a list of the specific resources for LessTif menu bars and -pop-up menus: - -@table @code -@item armColor -The color to show in an armed button. -@item fontList -The font to use. -@item marginBottom -@itemx marginHeight -@itemx marginLeft -@itemx marginRight -@itemx marginTop -@itemx marginWidth -Amount of space to leave around the item, within the border. -@item borderWidth -The width of the border around the menu item, on all sides. -@item shadowThickness -The width of the border shadow. -@item bottomShadowColor -The color for the border shadow, on the bottom and the right. -@item topShadowColor -The color for the border shadow, on the top and the left. -@end table -@end ifnottex - - -@node GTK resources -@appendixsec GTK resources -@iftex - The most common way to customize the GTK widgets Emacs uses (menus, dialogs -tool bars and scroll bars) is by choosing an appropriate theme, for example -with the GNOME theme selector. You can also do Emacs specific customization -by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}. Some GTK -themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything -works with all themes. To customize Emacs font, background, faces, etc., use -the normal X resources (@pxref{Resources}). We will present some examples of -customizations here, but for a more detailed description, see the online manual - - The first example is just one line. It changes the font on all GTK widgets -to courier with size 12: - -@smallexample -gtk-font-name = "courier 12" -@end smallexample - - The thing to note is that the font name is not an X font name, like --*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name. A Pango -font name is basically of the format "family style size", where the style -is optional as in the case above. A name with a style could be for example: - -@smallexample -gtk-font-name = "helvetica bold 10" -@end smallexample - - To customize widgets you first define a style and then apply the style to -the widgets. Here is an example that sets the font for menus, but not -for other widgets: - -@smallexample -# @r{Define the style @samp{menufont}.} -style "menufont" -@{ - font_name = "helvetica bold 14" # This is a Pango font name -@} - -# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} -widget "*emacs-menuitem*" style "menufont" -@end smallexample - -The widget name in this example contains wildcards, so the style will be -applied to all widgets that match "*emacs-menuitem*". The widgets are -named by the way they are contained, from the outer widget to the inner widget. -So to apply the style "my_style" (not shown) with the full, absolute name, for -the menubar and the scroll bar in Emacs we use: - -@smallexample -widget "Emacs.pane.menubar" style "my_style" -widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" -@end smallexample - -But to avoid having to type it all, wildcards are often used. @samp{*} -matches zero or more characters and @samp{?} matches one character. So "*" -matches all widgets. - - Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem). -You can assign styles by name or by class. In this example we have used the -class: - -@smallexample -style "menufont" -@{ - font_name = "helvetica bold 14" -@} - -widget_class "*GtkMenuBar" style "menufont" -@end smallexample - -@noindent -The names and classes for the GTK widgets Emacs uses are: - -@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} -@item @code{emacs-filedialog} -@tab @code{GtkFileSelection} -@item @code{emacs-dialog} -@tab @code{GtkDialog} -@item @code{Emacs} -@tab @code{GtkWindow} -@item @code{pane} -@tab @code{GtkVHbox} -@item @code{emacs} -@tab @code{GtkFixed} -@item @code{verticalScrollBar} -@tab @code{GtkVScrollbar} -@item @code{emacs-toolbar} -@tab @code{GtkToolbar} -@item @code{menubar} -@tab @code{GtkMenuBar} -@item @code{emacs-menuitem} -@tab anything in menus -@end multitable - - GTK absolute names are quite strange when it comes to menus -and dialogs. The names do not start with @samp{Emacs}, as they are -free-standing windows and not contained (in the GTK sense) by the -Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: - -@smallexample -widget "*emacs-dialog*" style "my_dialog_style" -widget "*emacs-filedialog* style "my_file_style" -widget "*emacs-menuitem* style "my_menu_style" -@end smallexample - - If you specify a customization in @file{~/.emacs.d/gtkrc}, then it -automatically applies only to Emacs, since other programs don't read -that file. For example, the drop down menu in the file dialog can not -be customized by any absolute widget name, only by an absolute class -name. This is because the widgets in the drop down menu do not -have names and the menu is not contained in the Emacs GtkWindow. To -have all menus in Emacs look the same, use this in -@file{~/.emacs.d/gtkrc}: - -@smallexample -widget_class "*Menu*" style "my_menu_style" -@end smallexample - - Here is a more elaborate example, showing how to change the parts of -the scroll bar: - -@smallexample -style "scroll" -@{ - fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} - bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} - bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} - bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} -@} - -widget "*verticalScrollBar*" style "scroll" -@end smallexample -@end iftex - -@ifnottex -@cindex GTK resources and customization -@cindex resource files for GTK -@cindex @file{~/.gtkrc-2.0} file -@cindex @file{~/.emacs.d/gtkrc} file - - If Emacs was built to use the GTK widget set, then the menu bar, tool bar, -scroll bar and the dialogs are customized with the standard GTK -customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific -file @file{~/.emacs.d/gtkrc}. We recommend that you use -@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0} -seems to be ignored when running GConf with GNOME. These files apply -only to GTK widget features. To customize Emacs font, background, -faces, etc., use the normal X resources (@pxref{Resources}). - - Some GTK themes override these mechanisms, which means that using -these mechanisms will not work to customize them. - - In these files you first define a style and say what it means; then -you specify to apply the style to various widget types (@pxref{GTK -widget names}). Here is an example of how to change the font for -Emacs menus: - -@smallexample -# @r{Define the style @samp{menufont}.} -style "menufont" -@{ - font_name = "helvetica bold 14" # This is a Pango font name -@} - -# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} -widget "*emacs-menuitem*" style "menufont" -@end smallexample - - Here is a more elaborate example, showing how to change the parts of -the scroll bar: - -@smallexample -style "scroll" -@{ - fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} - bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} - bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} - bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} -@} - -widget "*verticalScrollBar*" style "scroll" -@end smallexample - - There are also parameters that affect GTK as a whole. For example, -the property @code{gtk-font-name} sets the default font for GTK. You -must use Pango font names (@pxref{GTK styles}). A GTK resources file -that just sets a default font looks like this: - -@smallexample -gtk-font-name = "courier 12" -@end smallexample - - The GTK resources file is fully described in the GTK API document. -This can be found in -@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}, -where @file{prefix} is the directory in which the GTK libraries were -installed (usually @file{/usr} or @file{/usr/local}). You can also -find the document online, at -@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}. - -@menu -* GTK widget names:: How widgets in GTK are named in general. -* GTK Names in Emacs:: GTK widget names in Emacs. -* GTK styles:: What can be customized in a GTK widget. -@end menu - -@node GTK widget names -@appendixsubsec GTK widget names -@cindex GTK widget names - - A GTK widget is specified by its @dfn{widget class} and -@dfn{widget name}. The widget class is the type of the widget: for -example, @code{GtkMenuBar}. The widget name is the name given to a -specific widget. A widget always has a class, but need not have a -name. - - @dfn{Absolute names} are sequences of widget names or widget -classes, corresponding to hierarchies of widgets embedded within -other widgets. For example, if a @code{GtkWindow} named @code{top} -contains a @code{GtkVBox} named @code{box}, which in turn contains -a @code{GtkMenuBar} called @code{menubar}, the absolute class name -of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and -its absolute widget name is @code{top.box.menubar}. - - When assigning a style to a widget, you can use the absolute class -name or the absolute widget name. - - There are two commands to specify changes for widgets: - -@table @asis -@item @code{widget_class} -specifies a style for widgets based on the absolute class name. - -@item @code{widget} -specifies a style for widgets based on the absolute class name, -or just the class. -@end table - -@noindent -You must specify the class and the style in double-quotes, and put -these commands at the top level in the GTK customization file, like -this: - -@smallexample -style "menufont" -@{ - font_name = "helvetica bold 14" -@} - -widget "top.box.menubar" style "menufont" -widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont" -@end smallexample - - Matching of absolute names uses shell wildcard syntax: @samp{*} -matches zero or more characters and @samp{?} matches one character. -This example assigns @code{base_style} to all widgets: - -@smallexample -widget "*" style "base_style" -@end smallexample - - Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar} -and the corresponding absolute widget name @code{top.box.menubar}, all -these examples specify @code{my_style} for the menu bar: - -@smallexample -widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" -widget_class "GtkWindow.*.GtkMenuBar" style "my_style" -widget_class "*GtkMenuBar" style "my_style" -widget "top.box.menubar" style "my_style" -widget "*box*menubar" style "my_style" -widget "*menubar" style "my_style" -widget "*menu*" style "my_style" -@end smallexample - -@node GTK Names in Emacs -@appendixsubsec GTK Widget Names in Emacs -@cindex GTK widget names -@cindex GTK widget classes - - In Emacs, the top level widget for a frame is a @code{GtkWindow} -that contains a @code{GtkVBox}. The @code{GtkVBox} contains the -@code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll -bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed} -widget. The text you write in Emacs is drawn in the @code{GtkFixed} -widget. - - Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a -@code{GtkFileSelection} widget. - -@noindent -To set a style for the menu bar using the absolute class name, use: - -@smallexample -widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" -@end smallexample - -@noindent -For the scroll bar, the absolute class name is: - -@smallexample -widget_class - "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" - style "my_style" -@end smallexample - -@noindent -The names for the emacs widgets, and their classes, are: - -@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} -@item @code{emacs-filedialog} -@tab @code{GtkFileSelection} -@item @code{emacs-dialog} -@tab @code{GtkDialog} -@item @code{Emacs} -@tab @code{GtkWindow} -@item @code{pane} -@tab @code{GtkVHbox} -@item @code{emacs} -@tab @code{GtkFixed} -@item @code{verticalScrollBar} -@tab @code{GtkVScrollbar} -@item @code{emacs-toolbar} -@tab @code{GtkToolbar} -@item @code{menubar} -@tab @code{GtkMenuBar} -@item @code{emacs-menuitem} -@tab anything in menus -@end multitable - -@noindent -Thus, for Emacs you can write the two examples above as: - -@smallexample -widget "Emacs.pane.menubar" style "my_style" -widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" -@end smallexample - - GTK absolute names are quite strange when it comes to menus -and dialogs. The names do not start with @samp{Emacs}, as they are -free-standing windows and not contained (in the GTK sense) by the -Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: - -@smallexample -widget "*emacs-dialog*" style "my_dialog_style" -widget "*emacs-filedialog* style "my_file_style" -widget "*emacs-menuitem* style "my_menu_style" -@end smallexample - - If you specify a customization in @file{~/.emacs.d/gtkrc}, then it -automatically applies only to Emacs, since other programs don't read -that file. For example, the drop down menu in the file dialog can not -be customized by any absolute widget name, only by an absolute class -name. This is because the widgets in the drop down menu do not -have names and the menu is not contained in the Emacs GtkWindow. To -have all menus in Emacs look the same, use this in -@file{~/.emacs.d/gtkrc}: - -@smallexample -widget_class "*Menu*" style "my_menu_style" -@end smallexample - -@node GTK styles -@appendixsubsec GTK styles -@cindex GTK styles - - In a GTK style you specify the appearance widgets shall have. You -can specify foreground and background color, background pixmap and -font. The edit widget (where you edit the text) in Emacs is a GTK -widget, but trying to specify a style for the edit widget will have no -effect. This is so that Emacs compiled for GTK is compatible with -Emacs compiled for other X toolkits. The settings for foreground, -background and font for the edit widget is taken from the X resources; -@pxref{Resources}. Here is an example of two style declarations, -@samp{default} and @samp{ruler}: - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" - -style "default" -@{ - font_name = "helvetica 12" - - bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} - bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} - bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} - bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} - bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} - - fg[NORMAL] = "black" - fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} - fg[ACTIVE] = "black" - fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} - - base[INSENSITIVE] = "#777766" - text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} - - bg_pixmap[NORMAL] = "background.xpm" - bg_pixmap[INSENSITIVE] = "background.xpm" - bg_pixmap[ACTIVE] = "background.xpm" - bg_pixmap[PRELIGHT] = "" - -@} - -style "ruler" = "default" -@{ - font_name = "helvetica 8" -@} - -@end smallexample - - The style @samp{ruler} inherits from @samp{default}. This way you can build -on existing styles. The syntax for fonts and colors is described below. - - As this example shows, it is possible to specify several values for -foreground and background depending on the widget's @dfn{state}. The -possible states are: - -@table @code -@item NORMAL -This is the default state for widgets. -@item ACTIVE -This is the state for a widget that is ready to do something. It is -also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"} -sets the scroll bar trough to red. Buttons that have been pressed but -not released yet (``armed'') are in this state. -@item PRELIGHT -This is the state for a widget that can be manipulated, when the mouse -pointer is over it---for example when the mouse is over the thumb in -the scroll bar or over a menu item. When the mouse is over a button -that is not pressed, the button is in this state. -@item SELECTED -This is the state for data that has been selected by the user. It can -be selected text or items selected in a list. This state is not used -in Emacs. -@item INSENSITIVE -This is the state for widgets that are visible, but they can not be -manipulated in the usual way---for example, buttons that can't be -pressed, and disabled menu items. To display disabled menu items in -yellow, use @code{fg[INSENSITIVE] = "yellow"}. -@end table - - Here are the things that can go in a style declaration: - -@table @code -@item bg[@var{state}] = @var{color} -This specifies the background color for the widget. Note that -editable text doesn't use @code{bg}; it uses @code{base} instead. - -@item base[@var{state}] = @var{color} -This specifies the background color for editable text. In Emacs, this -color is used for the background of the text fields in the file -dialog. - -@item bg_pixmap[@var{state}] = "@var{pixmap}" -This specifies an image background (instead of a background color). -@var{pixmap} should be the image file name. GTK can use a number of -image file formats, including XPM, XBM, GIF, JPEG and PNG. If you -want a widget to use the same image as its parent, use -@samp{}. If you don't want any image, use @samp{}. -@samp{} is the way to cancel a background image inherited from a -parent style. - -You can't specify the file by its absolute file name. GTK looks for -the pixmap file in directories specified in @code{pixmap_path}. -@code{pixmap_path} is a colon-separated list of directories within -double quotes, specified at the top level in a @file{gtkrc} file -(i.e. not inside a style definition; see example above): - -@smallexample -pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" -@end smallexample - -@item fg[@var{state}] = @var{color} -This specifies the foreground color for widgets to use. It is the -color of text in menus and buttons, and the color for the arrows in -the scroll bar. For editable text, use @code{text}. - -@item text[@var{state}] = @var{color} -This is the color for editable text. In Emacs, this color is used for the -text fields in the file dialog. - -@item font_name = "@var{font}" -This specifies the font for text in the widget. @var{font} is a -Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica -Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact -syntax. The names are case insensitive. -@end table - - There are three ways to specify a color: by name, in hexadecimal -form, and with an RGB triplet. - -@noindent -A color name is written within double quotes, for example @code{"red"}. - -@noindent -Hexadecimal form is the same as in X: -@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs -must have the same number of hex digits (1, 2, 3 or 4). - -@noindent -An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}}, -where @var{r}, @var{g} and @var{b} are either integers in the range -0-65535 or floats in the range 0.0-1.0. - - Pango font names have the form ``@var{family-list} @var{style-options} -@var{size}.'' -@cindex Pango font name -@noindent -@var{family-list} is a comma separated list of font families optionally -terminated by a comma. This way you can specify several families and the -first one found will be used. @var{family} corresponds to the second part in -an X font name, for example in - -@smallexample --adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1 -@end smallexample - -@noindent -the family name is @samp{times}. - -@noindent -@var{style-options} is a whitespace separated list of words where each word -is a style, variant, weight, or stretch. The default value for all of -these is @code{normal}. - -@noindent -A `style' corresponds to the fourth part of an X font name. In X font -names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango -font names the corresponding values are @code{normal}, @code{italic}, -or @code{oblique}. - -@noindent -A `variant' is either @code{normal} or @code{small-caps}. -Small caps is a font with the lower case characters replaced by -smaller variants of the capital characters. - -@noindent -Weight describes the ``boldness'' of a font. It corresponds to the third -part of an X font name. It is one of @code{ultra-light}, @code{light}, -@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}. - -@noindent -Stretch gives the width of the font relative to other designs within a -family. It corresponds to the fifth part of an X font name. It is one of -@code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, -@code{semi-condensed}, @code{normal}, @code{semi-expanded}, -@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. - -@noindent -@var{size} is a decimal number that describes the font size in points. -@end ifnottex - -@ignore - arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f -@end ignore diff --git a/doc/lispintro/.cvsignore b/doc/lispintro/.cvsignore deleted file mode 100644 index e1af5a918b0..00000000000 --- a/doc/lispintro/.cvsignore +++ /dev/null @@ -1,21 +0,0 @@ -*.aux -*.fn -*.fns -*.cps -*.cp -*.kys -*.ky -*.toc -*.pgs -*.pg -*.log -*.vrs -*.vr -*.dvi -*.ps -*.tp -*.tps -*.tmp -*.txt -Makefile -makefile diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog deleted file mode 100644 index 83d9f4bcb0a..00000000000 --- a/doc/lispintro/ChangeLog +++ /dev/null @@ -1,356 +0,0 @@ -2009-07-29 Chong Yidong - - * Version 23.1 released. - -2009-07-28 Chong Yidong - - * emacs-lisp-intro.texi (Simple Extension): Bump emacs versions in - examples. - -2009-07-10 Glenn Morris - - * emacs-lisp-intro.texi (Top): Add missing @detailmenu entry. - -2009-07-09 Glenn Morris - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - -2009-07-06 Glenn Morris - - * emacs-lisp-intro.texi (defvar and asterisk): Minor rephrasing. - -2009-06-14 Chong Yidong - - * emacs-lisp-intro.texi (edebug): Fix typo. - -2009-02-22 Karl Berry - - * emacs-lisp-intro.texi (Default Configuration): fix dup word "by by". - -2009-02-20 Juanma Barranquero - - * emacs-lisp-intro.texi (current-kill, Code for current-kill) - (Body of current-kill): Remove duplicate words. - -2008-11-19 Glenn Morris - - * doclicense.texi: New file. - * emacs-lisp-intro.texi: Relicense under FDL 1.3 or later. - Include doclicense.texi rather than having license in the file itself. - -2008-10-16 Sean Sieger (tiny change) - - * emacs-lisp-intro.texi (Recursion with list): Fix typo. - -2008-10-04 Karl Berry - - * emacs-lisp-intro.texi: Apply similar formatting changes as for - the emacs and lispref manuals, to save pages. A couple minor - rewordings and reformatting of code to avoid overfull and - underfull lines. - (edition-number): Bump to 3.08. - (update-date): Bump to 4 October 2008. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-16 Glenn Morris - - * Makefile.am, Makefile.old, aclocal.m4, configure, configure.in: - * install-sh, missing, mkinstalldirs: Remove obsolete files. - -2008-05-13 Chong Yidong - - * emacs-lisp-intro.texi (Lisp Atoms): Rephrase "in addition" to - avoid confusion with addition operation discussed in previous - paragraph. - -2008-01-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Update back cover text. - -2007-09-12 Robert J. Chassell - - * emacs-lisp-intro.texi: Add email address to Thank You correctly. - -2007-09-06 Romain Francoise - - * Makefile.in (maintainer-clean): Delete info files. - -2007-09-06 Glenn Morris - - Move from lispintro/ to doc/lispintro/. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - * makefile.w32-in (infodir, ENVADD): Go up one more level. - * emacs-lisp-intro.texi (setfilename): Go up one more level. - -2007-07-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Fix typo on line 5173, change `thee' to - `these'. - -2007-07-25 Glenn Morris - - * Relicense all FSF files to GPLv3 or later. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-01-30 Robert J. Chassell - - * emacs-lisp-intro.texi (else): Rephrase message of first - if-then-else example so it is right both in itself and in the - "true" case of the expression, which asks whether 4 is greater - than 5. - -2006-11-27 Andreas Schwab - - * Makefile.in (usermanualdir): Define. - (emacs-lisp-intro.dvi): Pass -I options to texi2dvi instead of - using TEXINPUTS. - - * emacs-lisp-intro.texi: Input texinfo instead of ../man/texinfo - to fix building outside source directory. - -2006-11-09 Robert J. Chassell - - * emacs-lisp-intro.texi: Copy descriptions from detailed master - menu to menus within body. - - * emacs-lisp-intro.texi (at the beginning): Add `other shell - commands' to produce additional output formats; total is now ten. - (A Loop with an Incrementing Counter, and others): Ensure Info - menus will appear in short windows. - (Disentangle beginning-of-buffer): Replace `version 21' with `more - recent versions'. - (Simple Extension): Show how to handle multiple versions by adding - an alternative with a test of `>= 21'. - -2006-11-06 Robert J. Chassell - - * emacs-lisp-intro.texi: Finish minor changes seen from DVI output. - Replace 22.1.100 with 22.1.1. - (current-kill): Mention functions that directly or indirectly call - `kill-new', which sets `kill-ring-yank-pointer'. - (Understanding current-kill): Change `lasted' to `last'. Remove - extraneous parenthesis. Reword item about returning `car' of list. - (yank): Remove mention of `rotate-yank-pointer'. - (Y Axis Element): Add comment regarding replacement of blank space. - (print-Y-axis Penultimate): Explain that `print-graph' will pass - `height-of-top-line' so `print-Y-axis' does not have a bug. - -2006-11-05 Robert J. Chassell - - * emacs-lisp-intro.texi: Yet more minor changes: - (defcustom): Said that `:options' is usually for a hook. Remove - extraneous space in parenthetical remark concerning - `text-mode-hook-identify'. At end, mention other defines, too. - (Beginning a .emacs File): Reverse words about comments so they - parallel numbers of listed semi-colons. - (Text and Auto-fill): Remove extraneous blank line in example. - (Mail Aliases): Remove extraneous blank line in example. - (Keybindings): Reformat as needed with `key' rather than `kbd'. - (Keybindings, Miscellaneous, Mode Line): For small book format, start - section name on top of new page. - (Simple Extension): Replace longer expression with - `emacs-major-version'. Remove comment about `number-to-string' - function. - (Miscellaneous): Add filename option, `-H', to `grep' example - (debug, debug-on-entry): Replace `GNU Emacs 22' with `a recent - GNU Emacs'. - (edebug): More properly state where to place point for 'M-x - edebug-defun'. - - * emacs-lisp-intro.texi: More minor changes. - Center images for TeX output. - (kill-new function): Remove indentation for sentence talking about - momentarily skipping code. - (cons & search-fwd Review): Document @code{funcall}. Document - @code{re-search-forward} with existing @code{search-forward}. - Reference chapter on regular expression searches. - (Recursion with list): Specify a more recent version as being Emacs. - (Recursion with list, Every, recursive-graph-body-print): Change - `if ... progn' expression to `when'. - (Recursive triangle function): For printing in small book, ensure - section name is not last on bottom of preceding page. - (Keep): Remove extraneous space in function definition example. - (sentence-end): Specify `in English' for glyphs that end a sentence. - Note that in GNU Emacs 22, the name refers to both a variable and a - function. - (fwd-sentence while loops): Write a function as one, not as a form - (fwd-para let): Add `which' to sentence with `parstart' and `parsep'. - (etags): Move sentences involving `find-tag' and sources. State - location of Emacs `src' directory. - (Design count-words-region): Better explain two backslashes in a row. - (Find a File): Fix grammar; add a `to' and write `to visit'. Change - `named' to `selected'. - (lengths-list-file): Remove extraneous parenthesis from reference. - (lengths-list-many-files): Explain `expand-file-name' better. - (Files List): Rephrase sentence regarding Lisp sources directory - -2006-11-04 Robert J. Chassell - - * emacs-lisp-intro.texi: Replace 22.0.100 with 22.1.100. - (defcustom): Note that the value set by defconst is a variable. - (Buffer Size & Locations): Parenthetical remark about evaluation. - (Finding More): Change text to include C sources by inference. - - * emacs-lisp-intro.texi: Minor fixes. - Replace all tabs with eight spaces each so printed text looks correct. - Remove extraneous comma in a printed node name produced by `ref'. - (insert-buffer): Add a missing beginning parenthesis. - (beginning-of-buffer): Add `beginning of' to note about accessible - portion. - (narrow Exercise): Write closing parenthesis at end of correct - paragraph. - (zap-to-char): Remove extraneous `a' from first sentence. - (Complete zap-to-char): Remove two extraneous sentences. - (zap-to-char body): Move sentences on documentation two nodes earlier. - (Lisp macro): Add definition of `unless' macro. - (last-command & this-command): Remove comment that `we have not yet - seen' the @code{eq} function. - (kill-append function): Reformat `kill-append' function definition so - it prints well. - (kill-new function): Indent the sentence beginning `notice'. Replace - `the same as' with `similar to'. Repair typo. Remove obsolete - references to `yank' and `yank-pop. End section with a note that `we - will digress into C.' - -2006-11-02 Robert J. Chassell - - * emacs-lisp-intro.texi (kill-ring-yank-pointer): Revert addition - of extraneous quotation mark to rotate-yank-pointer. - -2006-11-01 Juri Linkov - - * emacs-lisp-intro.texi: Fix unbalanced quotes. - -2006-10-31 Robert J. Chassell - - * emacs-lisp-intro.texi: Revised text for kill-region, - copy-region-as-kill, kill-append, kill-new, forward-sentence, - forward-paragraph, find-file, current-kill, yank, and yank-pop. - Removed INSTALL MANIFEST from the directory since those files are - now irrelevant. Updated Info file in ../info. Changed numbering - so is now Revised Third Edition and this instance's edition-number - is 3.00. Did not update ISBN number. - - * emacs-lisp-intro.texi: Remove version reference for X colors. - Document `='. Remove mention that :eval was new in 21. Updated - instance's edition-number to 3.01. - -2006-10-30 Robert J. Chassell - - * emacs-lisp-intro.texi: Many changes since it turned out that - many `simple' functions were rewritten. Changes to the text - regarding zap-to-char, mark-whole-buffer, append-to-buffer, - copy-to-buffer, beginning-of-buffer, what-line, and possibly - others. (I have not reviewed all yet.) This instance does build - for Info and TeX. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-08-21 Robert J. Chassell - - * emacs-lisp-intro.texi: Deleted in directory copy of texinfo.tex - and pointed towards ../man/texinfo.tex so only one file - needs updating. Added comment of what to do when building on own. - - * texinfo.tex: Changed to version 2006-02-13.16 - to enable a DVI build using the more recent versions of TeX. - -2006-05-25 David Kastrup - - * emacs-lisp-intro.texi (setcar): Replace an antelope rather than - a giraffe with a hippopotamus. - -2006-05-19 Thien-Thi Nguyen - - * emacs-lisp-intro.texi (Digression concerning error): Fix typo. - -2005-09-16 Romain Francoise - - * emacs-lisp-intro.texi (GNU Free Documentation License): - Specify GFDL version 1.2. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-04 Lute Kamstra - - Update FSF's address in GPL notices. - - * emacs-lisp-intro.texi: Update FSF's address. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (mostlyclean, clean, maintainer-clean): - Use $(DEL) instead of rm, and ignore exit code. - -2003-11-16 Kevin Ryde - - * emacs-lisp-intro.texi: [CVS commitment by ] - Corrections to cross references, - (Interactive Options): elisp "interactive" -> "Using Interactive". - (defvar and asterisk): Remove emacs "Edit Options" reference, - edit-options is no longer described in the emacs manual. - (Lists diagrammed): elisp "List Type" -> "Cons Cell Type". - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2001-11-29 Eli Zaretskii - - * emacs-lisp-intro.texi (Index): @ignore extraneous text. - Use @dircategory and @direntry to define the DIR entry. - -2001-11-25 Robert J. Chassell - - * emacs-lisp-intro.texi: Move @contents to the beginning of the - file. Set the size to @smallbook. - -2001-11-24 Eli Zaretskii - - * Makefile.in: New file. - - * README: Update. - - * *.eps: Rename to avoid clashes in DOS 8+3 namespace. - -;; Local Variables: -;; coding: utf-8 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, - 2008, 2009 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . - -;;; arch-tag: ee4f8e1f-e14c-4d2e-86de-4dd697e6f1c3 diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in deleted file mode 100644 index 151cf2f4714..00000000000 --- a/doc/lispintro/Makefile.in +++ /dev/null @@ -1,73 +0,0 @@ -#### Makefile for the Emacs Lisp Introduction manual - -# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, -# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -SHELL = @SHELL@ - -srcdir = @srcdir@ -VPATH = @srcdir@ - -infodir = ../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -INFO_SOURCES = ${srcdir}/emacs-lisp-intro.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = ${infodir}/eintr -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -TEXI2DVI = texi2dvi -DVIPS = dvips - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -${infodir}/eintr: ${INFO_SOURCES} - cd $(srcdir); $(MAKEINFO) emacs-lisp-intro.texi -o $(infodir)/eintr - -emacs-lisp-intro.dvi: ${INFO_SOURCES} - $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - rm -f *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - rm -f *.dvi - -distclean: clean - -maintainer-clean: distclean - rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - cd $(infodir); rm -f eintr eintr-[1-9] - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/doc/lispintro/README b/doc/lispintro/README deleted file mode 100644 index 40187ca44e7..00000000000 --- a/doc/lispintro/README +++ /dev/null @@ -1,73 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - -This directory contains the source of the "Introduction to Programming -in Emacs Lisp" written by Robert J. Chassell, bob@gnu.org. This -manual is an elementary introduction to programming in Emacs Lisp for -people who are not programmers, and who are not necessarily interested -in programming, but who do want to customize or extend their computing -environment. - -This third edition of 2006 Oct 31 updates the previous editions to GNU -Emacs 22. - -The Texinfo source file `emacs-lisp-intro.texi', formats without -reported error using `pdfeTeXk', Version 3.141592-1.21a-2.2 (Web2C -7.5.4) and texinfo.tex version 2006-08-26.17 started by `texi2dvi' -version 4.8, and with `makeinfo' version 4.8. - -This directory contains the following Encapsulated PostScript figures: - - cons-1.eps, cons-2.eps, cons-2a.eps, cons-3.eps, cons-4.eps, cons-5.eps - drawers.eps, lambda-1.eps, lambda-2.eps, lambda-3.eps - -See the beginning of the `emacs-lisp-intro.texi' file for appropriate -settings. These figures are not necessary; they are merely nice to -look at --- without them you get the same figures printed with ASCII -characters. - -Whether and how you print PostScript depends on your site. You not -only need to set 'print-postscript-figures' before creating the .dvi -file, but then must convert the .dvi file to .ps with a 'dvips' or -equivalent command. - -On some systems you will see an error message when `psfig.tex' is -loaded for the last two .eps files: - - ! No room for a new \write . - -If this happens, try `epsf.tex' instead of `psfig.tex', or try typing -RET at the error; the formatting may continue successfully. - -Or else find the section that says: - - @c !!! Clear print-postscript-figures if the computer formatting this - @c document is too small and cannot handle all the diagrams and figures. - @c clear print-postscript-figures - -and change the file so it reads: @clear print-postscript-figures -This will prevent TeX from attempting to load the last few .eps files. - -You will find additional instructions on formatting in the beginning -of the Texinfo file 'emacs-lisp-intro.texi'. Best Wishes! - -2006 Oct 31 -Robert J. Chassell, bob@gnu.org - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps deleted file mode 100644 index 76e00dbacf5..00000000000 --- a/doc/lispintro/cons-1.eps +++ /dev/null @@ -1,582 +0,0 @@ -%! -%%BoundingBox: 35 711 289 757 -%%Title: cons-cell-diagram1 -%%CreationDate: Wed Mar 8 14:26:58 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 35 711 289 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 66 66 moveto 130 66 lineto 130 98 lineto 66 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 98 66 moveto - 98 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 114 82 moveto - 0 80 atan dup cos 8 mul 194 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 194 82 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 146 136 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 82 82 moveto - 82 131 lineto - 0 48 atan dup cos 8 mul 130 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 130 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 199 66 moveto 263 66 lineto 263 98 lineto 199 98 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 231 66 moveto - 231 98 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 247 82 moveto - 0 93 atan dup cos 8 mul 340 exch sub - exch sin 8 mul 82 exch sub lineto - stroke -grestore -gsave - newpath - 340 82 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 279 136 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 215 82 moveto - 215 131 lineto - 0 48 atan dup cos 8 mul 263 exch sub - exch sin 8 mul 131 exch sub lineto - stroke -grestore -gsave - newpath - 263 131 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 342 64 moveto 406 64 lineto 406 96 lineto 342 96 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 373 64 moveto - 373 96 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 389 81 moveto - 0 48 atan dup cos 8 mul 437 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 437 81 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 421 135 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 81 moveto - 357 130 lineto - 0 48 atan dup cos 8 mul 405 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 405 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 449 87 moveto (nil) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:58 1995 diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps deleted file mode 100644 index 9083ef0ca36..00000000000 --- a/doc/lispintro/cons-2.eps +++ /dev/null @@ -1,604 +0,0 @@ -%! -%%BoundingBox: 15 712 321 775 -%%Title: cons-cell-diagram2 -%%CreationDate: Wed Mar 8 14:26:39 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 712 321 775 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 47 moveto (bouquet) show - grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 122 65 moveto 186 65 lineto 186 97 lineto 122 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 154 65 moveto - 154 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 170 81 moveto - 0 80 atan dup cos 8 mul 250 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 250 81 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 202 135 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 138 81 moveto - 138 130 lineto - 0 48 atan dup cos 8 mul 186 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 186 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 255 65 moveto 319 65 lineto 319 97 lineto 255 97 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 287 65 moveto - 287 97 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 303 81 moveto - 0 93 atan dup cos 8 mul 396 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 396 81 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 335 135 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 271 81 moveto - 271 130 lineto - 0 48 atan dup cos 8 mul 319 exch sub - exch sin 8 mul 130 exch sub lineto - stroke -grestore -gsave - newpath - 319 130 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 398 63 moveto 462 63 lineto 462 95 lineto 398 95 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 429 63 moveto - 429 95 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 445 80 moveto - 0 48 atan dup cos 8 mul 493 exch sub - exch sin 8 mul 80 exch sub lineto - stroke -grestore -gsave - newpath - 493 80 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 477 134 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 413 80 moveto - 413 129 lineto - 0 48 atan dup cos 8 mul 461 exch sub - exch sin 8 mul 129 exch sub lineto - stroke -grestore -gsave - newpath - 461 129 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 505 86 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 66 53 moveto - 66 81 lineto - 0 46 atan dup cos 8 mul 112 exch sub - exch sin 8 mul 81 exch sub lineto - stroke -grestore -gsave - newpath - 112 81 8 3 46 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:26:39 1995 diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps deleted file mode 100644 index e492b15d77d..00000000000 --- a/doc/lispintro/cons-2a.eps +++ /dev/null @@ -1,598 +0,0 @@ -%! -%%BoundingBox: 15 702 300 767 -%%Title: cons-cell-diagram2a -%%CreationDate: Tue Mar 14 15:09:30 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 702 300 767 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 62 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 64 80 moveto - 64 120 lineto - 0 49 atan dup cos 8 mul 113 exch sub - exch sin 8 mul 120 exch sub lineto - stroke -grestore -gsave - newpath - 113 120 8 3 49 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 110 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 128 142 moveto (rose) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 192 110 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 207 124 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 217 123 moveto - 0 38 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 123 exch sub lineto - stroke -grestore -gsave - newpath - 255 123 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 268 111 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 264 143 moveto (violet) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 332 111 moveto (cdr) show - grestore - -% OVAL -gsave - newpath 347 125 4 4 tgifellipse stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 357 124 moveto - 0 38 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 395 124 8 3 38 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 112 moveto (car) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 408 136 moveto (butter-) show - 408 153 moveto (cup) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 496 113 moveto (cdr) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 495 137 moveto (nil) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 178 86 moveto - 178 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 485 84 moveto - 485 157 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 327 85 moveto - 327 157 lineto - stroke -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 120 86 moveto 234 86 lineto 234 157 lineto 120 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 257 85 moveto 371 85 lineto 371 157 lineto 257 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 397 84 moveto 531 84 lineto 531 157 lineto 397 157 lineto - closepath stroke - 1 setmiterlimit -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Tue Mar 14 15:09:30 1995 diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps deleted file mode 100644 index bb08120f4b8..00000000000 --- a/doc/lispintro/cons-3.eps +++ /dev/null @@ -1,628 +0,0 @@ -%! -%%BoundingBox: -1 691 324 757 -%%Title: cons-cell-diagram3 -%%CreationDate: Wed Mar 8 14:25:41 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: -1 691 324 757 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% BOX -gsave - 1.415 setmiterlimit - newpath - 128 102 moveto 192 102 lineto 192 134 lineto 128 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 102 moveto - 160 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 176 124 moveto - 0 80 atan dup cos 8 mul 256 exch sub - exch sin 8 mul 124 exch sub lineto - stroke -grestore -gsave - newpath - 256 124 8 3 80 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 208 172 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 144 118 moveto - 144 167 lineto - 0 48 atan dup cos 8 mul 192 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 192 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 261 102 moveto 325 102 lineto 325 134 lineto 261 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 293 102 moveto - 293 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 309 118 moveto - 0 93 atan dup cos 8 mul 402 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 402 118 8 3 93 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 341 172 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 277 118 moveto - 277 167 lineto - 0 48 atan dup cos 8 mul 325 exch sub - exch sin 8 mul 167 exch sub lineto - stroke -grestore -gsave - newpath - 325 167 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 404 100 moveto 468 100 lineto 468 132 lineto 404 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 435 100 moveto - 435 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 451 117 moveto - 0 48 atan dup cos 8 mul 499 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 499 117 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 483 171 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 419 117 moveto - 419 166 lineto - 0 48 atan dup cos 8 mul 467 exch sub - exch sin 8 mul 166 exch sub lineto - stroke -grestore -gsave - newpath - 467 166 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 511 123 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 131 80 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 210 75 moveto - 237 75 lineto - 237 113 lineto - 0 18 atan dup cos 8 mul 255 exch sub - exch sin 8 mul 113 exch sub lineto - stroke -grestore -gsave - newpath - 255 113 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 2 80 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 81 77 moveto - 108 77 lineto - 108 115 lineto - 0 18 atan dup cos 8 mul 126 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 126 115 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:41 1995 diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps deleted file mode 100644 index a19a96ded2a..00000000000 --- a/doc/lispintro/cons-4.eps +++ /dev/null @@ -1,681 +0,0 @@ -%! -%%BoundingBox: 6 681 355 758 -%%Title: cons-cell-diagram4 -%%CreationDate: Wed Mar 8 14:25:06 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 6 681 355 758 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 274 102 moveto - 274 134 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 289 122 moveto - 0 56 atan dup cos 8 mul 345 exch sub - exch sin 8 mul 122 exch sub lineto - stroke -grestore -gsave - newpath - 345 122 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 350 100 moveto 414 100 lineto 414 132 lineto 350 132 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 382 100 moveto - 382 132 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 397 114 moveto - 0 59 atan dup cos 8 mul 456 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 456 114 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 430 170 moveto (violet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 366 116 moveto - 366 165 lineto - 0 48 atan dup cos 8 mul 414 exch sub - exch sin 8 mul 165 exch sub lineto - stroke -grestore -gsave - newpath - 414 165 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 219 78 moveto (flowers) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 298 73 moveto - 325 73 lineto - 325 111 lineto - 0 18 atan dup cos 8 mul 343 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 343 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 459 95 moveto 523 95 lineto 523 127 lineto 459 127 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 490 95 moveto - 490 127 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 506 112 moveto - 0 48 atan dup cos 8 mul 554 exch sub - exch sin 8 mul 112 exch sub lineto - stroke -grestore -gsave - newpath - 554 112 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 566 118 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 538 151 moveto (buttercup) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 474 109 moveto - 474 146 lineto - 0 48 atan dup cos 8 mul 522 exch sub - exch sin 8 mul 146 exch sub lineto - stroke -grestore -gsave - newpath - 522 146 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 244 102 moveto 308 102 lineto 308 134 lineto 244 134 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 324 189 moveto (rose) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 260 117 moveto - 260 184 lineto - 0 48 atan dup cos 8 mul 308 exch sub - exch sin 8 mul 184 exch sub lineto - stroke -grestore -gsave - newpath - 308 184 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 146 101 moveto 210 101 lineto 210 133 lineto 146 133 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 177 101 moveto - 177 133 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 193 118 moveto - 0 48 atan dup cos 8 mul 241 exch sub - exch sin 8 mul 118 exch sub lineto - stroke -grestore -gsave - newpath - 241 118 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 187 178 moveto (lily) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 163 118 moveto - 163 171 lineto - 0 18 atan dup cos 8 mul 181 exch sub - exch sin 8 mul 171 exch sub lineto - stroke -grestore -gsave - newpath - 181 171 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 16 78 moveto (bouquet) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 95 73 moveto - 122 73 lineto - 122 111 lineto - 0 18 atan dup cos 8 mul 140 exch sub - exch sin 8 mul 111 exch sub lineto - stroke -grestore -gsave - newpath - 140 111 8 3 18 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:25:06 1995 diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps deleted file mode 100644 index 2102dce21c0..00000000000 --- a/doc/lispintro/cons-5.eps +++ /dev/null @@ -1,626 +0,0 @@ -%! -%%BoundingBox: 15 680 305 764 -%%Title: cons-cell-diagram5 -%%CreationDate: Wed Mar 8 14:27:28 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 15 680 305 764 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% POLY/OPEN-SPLINE -gsave - newpath - 156 105 moveto - 156 137 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 171 125 moveto - 0 56 atan dup cos 8 mul 227 exch sub - exch sin 8 mul 125 exch sub lineto - stroke -grestore -gsave - newpath - 227 125 8 3 56 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 232 103 moveto 296 103 lineto 296 135 lineto 232 135 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 103 moveto - 264 135 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 279 117 moveto - 0 59 atan dup cos 8 mul 338 exch sub - exch sin 8 mul 117 exch sub lineto - stroke -grestore -gsave - newpath - 338 117 8 3 59 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 289 172 moveto (a different piece of text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 248 119 moveto - 248 168 lineto - 0 29 atan dup cos 8 mul 277 exch sub - exch sin 8 mul 168 exch sub lineto - stroke -grestore -gsave - newpath - 277 168 8 3 29 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 147 66 moveto (kill-ring-yank-pointer) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 207 76 moveto - 207 114 lineto - 0 18 atan dup cos 8 mul 225 exch sub - exch sin 8 mul 114 exch sub lineto - stroke -grestore -gsave - newpath - 225 114 8 3 18 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 341 98 moveto 405 98 lineto 405 130 lineto 341 130 lineto - closepath stroke - 1 setmiterlimit -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 372 98 moveto - 372 130 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 388 115 moveto - 0 48 atan dup cos 8 mul 436 exch sub - exch sin 8 mul 115 exch sub lineto - stroke -grestore -gsave - newpath - 436 115 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 448 121 moveto (nil) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 397 154 moveto (yet more text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 356 112 moveto - 356 149 lineto - 0 35 atan dup cos 8 mul 391 exch sub - exch sin 8 mul 149 exch sub lineto - stroke -grestore -gsave - newpath - 391 149 8 3 35 0 tgifarrowtip - closepath fill -grestore - -% BOX -gsave - 1.415 setmiterlimit - newpath - 126 105 moveto 190 105 lineto 190 137 lineto 126 137 lineto - closepath stroke - 1 setmiterlimit -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 206 192 moveto (some text) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 142 120 moveto - 142 187 lineto - 0 48 atan dup cos 8 mul 190 exch sub - exch sin 8 mul 187 exch sub lineto - stroke -grestore -gsave - newpath - 190 187 8 3 48 0 tgifarrowtip - closepath fill -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 32 66 moveto (kill-ring) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 65 81 moveto - 65 121 lineto - 0 51 atan dup cos 8 mul 116 exch sub - exch sin 8 mul 121 exch sub lineto - stroke -grestore -gsave - newpath - 116 121 8 3 51 0 tgifarrowtip - closepath fill -grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:27:28 1995 diff --git a/doc/lispintro/doclicense.texi b/doc/lispintro/doclicense.texi deleted file mode 100644 index 1aa76136110..00000000000 --- a/doc/lispintro/doclicense.texi +++ /dev/null @@ -1,512 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - -@ignore - arch-tag: 839f250e-4800-4bc9-bd28-49ec7968331f -@end ignore - diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps deleted file mode 100644 index 01813d1dd62..00000000000 --- a/doc/lispintro/drawers.eps +++ /dev/null @@ -1,511 +0,0 @@ -%!PS-Adobe-3.0 EPSF-3.0 -%%BoundingBox: 34 577 324 778 -%%Title: chest-of-drawers-diagram-new -%%CreationDate: Fri Sep 14 17:40:57 2001 -%%Creator: Tgif-4.1.35 by William Chia-Wei Cheng (william@cs.UCLA.edu) -%%ProducedBy: (unknown) -%%Pages: 1 -%%DocumentFonts: (atend) -%%EndComments -%%BeginProlog - -% Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 53 dict def -tgifdict begin - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/TGEL % tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/TGMAX - { exch dup 3 1 roll exch dup 3 1 roll gt { pop } { exch pop } ifelse - } def -/TGMIN - { exch dup 3 1 roll exch dup 3 1 roll lt { pop } { exch pop } ifelse - } def -/TGSW { stringwidth pop } def - -/bd { bind def } bind def - -/GS { gsave } bd -/GR { grestore } bd -/NP { newpath } bd -/CP { closepath } bd -/CHP { charpath } bd -/CT { curveto } bd -/L { lineto } bd -/RL { rlineto } bd -/M { moveto } bd -/RM { rmoveto } bd -/S { stroke } bd -/F { fill } bd -/TR { translate } bd -/RO { rotate } bd -/SC { scale } bd -/MU { mul } bd -/DI { div } bd -/DU { dup } bd -/NE { neg } bd -/AD { add } bd -/SU { sub } bd -/PO { pop } bd -/EX { exch } bd -/CO { concat } bd -/CL { clip } bd -/EC { eoclip } bd -/EF { eofill } bd -/IM { image } bd -/IMM { imagemask } bd -/ARY { array } bd -/SG { setgray } bd -/RG { setrgbcolor } bd -/SD { setdash } bd -/W { setlinewidth } bd -/SM { setmiterlimit } bd -/SLC { setlinecap } bd -/SLJ { setlinejoin } bd -/SH { show } bd -/FF { findfont } bd -/MS { makefont setfont } bd -/AR { arcto 4 {pop} repeat } bd -/CURP { currentpoint } bd -/FLAT { flattenpath strokepath clip newpath } bd -/TGSM { tgiforigctm setmatrix } def -/TGRM { savematrix setmatrix } def - -end - -%%EndProlog -%%Page: 1 1 - -%%PageBoundingBox: 34 577 324 778 -tgifdict begin -/tgifsavedpage save def - -1 SM -1 W - -0 SG - -72 0 MU 72 11 MU TR -72 128 DI 100.000 MU 100 DI DU NE SC - -GS - -/tgiforigctm matrix currentmatrix def - -% BOX -0 SG -GS - 10 SM - GS - NP 64 104 M 255 104 L 255 360 L 64 360 L CP - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 65 296 M - 254 296 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 233 M - 255 233 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 169 M - 255 169 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 251 362 M - 251 361 L - 251 379 L - 244 379 L - 229 361 L - TGSM - 1 W - S -GR - -% OVAL -0 SG -GS - GS - NP 160 72 10 6 TGEL - S - GR -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 63 104 M - 128 64 L - 138 69 L - TGSM - 1 W - S -GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 255 103 M - 190 63 L - 180 68 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 160 152 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 41 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Chest of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 41 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (Contents of Drawers) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 160 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (bouquet) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 220 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([none]) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 279 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (\(rose violet buttercup\)) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 344 337 M - GS - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - ([not described here]) SH - GR - GR - -% POLY/OPEN-SPLINE -0 SG -GS - NP - 68 362 M - 68 361 L - 68 379 L - 75 379 L - 90 361 L - TGSM - 1 W - S -GR - -% TEXT -NP -0 SG - GS - 1 W - 158 132 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 345 139 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 350 259 M - GS - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (map to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 213 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (symbol definition) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 159 195 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 276 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (variable name) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (variable name) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 260 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 160 339 M - GS - GS - 0 - /Courier FF [17 0 0 -17 0 0] MS - (property list) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /Courier FF [17 0 0 -17 0 0] MS - (property list) SH - GR - GR - -% TEXT -NP -0 SG - GS - 1 W - 158 323 M - GS - GS - 0 - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) TGSW - AD - GR - 2 DI NE 0 RM - 0 SG - /NewCenturySchlbk-Roman FF [17 0 0 -17 0 0] MS - (directions to) SH - GR - GR - -GR -tgifsavedpage restore -end -showpage - -%%Trailer -%MatchingCreationDate: Fri Sep 14 17:40:57 2001 -%%DocumentFonts: NewCenturySchlbk-Roman -%%+ Courier -%%EOF diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi deleted file mode 100644 index 3f2d5f01ffa..00000000000 --- a/doc/lispintro/emacs-lisp-intro.texi +++ /dev/null @@ -1,22281 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/eintr -@c setfilename emacs-lisp-intro.info -@c sethtmlfilename emacs-lisp-intro.html -@settitle Programming in Emacs Lisp -@syncodeindex vr cp -@syncodeindex fn cp -@finalout - -@c --------- -@c <<<< For hard copy printing, this file is now -@c set for smallbook, which works for all sizes -@c of paper, and with Postscript figures >>>> -@set smallbook -@ifset smallbook -@smallbook -@clear largebook -@end ifset -@set print-postscript-figures -@c set largebook -@c clear print-postscript-figures -@c --------- - -@comment %**end of header - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@set edition-number 3.08 -@set update-date 4 October 2008 -@ignore - ## Summary of shell commands to create various output formats: - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## Info output - makeinfo --paragraph-indent=0 --verbose emacs-lisp-intro.texi - - ## ;; (progn (when (bufferp (get-buffer "*info*")) (kill-buffer "*info*")) (info "/usr/local/src/emacs/info/eintr")) - - ## DVI output - texi2dvi emacs-lisp-intro.texi - - ## xdvi -margins 24pt -topmargin 4pt -offsets 24pt -geometry 760x1140 -s 5 -useTeXpages -mousemode 1 emacs-lisp-intro.dvi & - - ## HTML output - makeinfo --html --no-split --verbose emacs-lisp-intro.texi - - ## galeon emacs-lisp-intro.html - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --verbose --no-headers --output=emacs-lisp-intro.txt emacs-lisp-intro.texi - - popd - -# as user `root' -# insert thumbdrive - mtusb # mount -v -t ext3 /dev/sda /mnt - cp -v /u/intro/emacs-lisp-intro.texi /mnt/backup/intro/emacs-lisp-intro.texi - umtusb # umount -v /mnt -# remove thumbdrive - - ## Other shell commands - - pushd /usr/local/src/emacs/lispintro/ - ## pushd /u/intro/ - - ## PDF - texi2dvi --pdf emacs-lisp-intro.texi - # xpdf emacs-lisp-intro.pdf & - - ## DocBook -- note file extension - makeinfo --docbook --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.docbook emacs-lisp-intro.texi - - ## XML with a Texinfo DTD -- note file extension - makeinfo --xml --no-split --paragraph-indent=0 \ - --verbose --output=emacs-lisp-intro.texinfoxml emacs-lisp-intro.texi - - ## PostScript (needs DVI) - # gv emacs-lisp-intro.ps & - # Create DVI if we lack it - # texi2dvi emacs-lisp-intro.texi - dvips emacs-lisp-intro.dvi -o emacs-lisp-intro.ps - - ## RTF (needs HTML) - # Use OpenOffice to view RTF - # Create HTML if we lack it - # makeinfo --no-split --html emacs-lisp-intro.texi - /usr/local/src/html2rtf.pl emacs-lisp-intro.html - - ## LaTeX (needs RTF) - /usr/bin/rtf2latex emacs-lisp-intro.rtf - - popd - -@end ignore - -@c ================ Included Figures ================ - -@c Set print-postscript-figures if you print PostScript figures. -@c If you clear this, the ten figures will be printed as ASCII diagrams. -@c (This is not relevant to Info, since Info only handles ASCII.) -@c Your site may require editing changes to print PostScript; in this -@c case, search for `print-postscript-figures' and make appropriate changes. - -@c ================ How to Create an Info file ================ - -@c If you have `makeinfo' installed, run the following command - -@c makeinfo emacs-lisp-intro.texi - -@c or, if you want a single, large Info file, and no paragraph indents: -@c makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi - -@c After creating the Info file, edit your Info `dir' file, if the -@c `dircategory' section below does not enable your system to -@c install the manual automatically. -@c (The `dir' file is often in the `/usr/local/share/info/' directory.) - -@c ================ How to Create an HTML file ================ - -@c To convert to HTML format -@c makeinfo --html --no-split --verbose emacs-lisp-intro.texi - -@c ================ How to Print a Book in Various Sizes ================ - -@c This book can be printed in any of three different sizes. -@c In the above header, set @-commands appropriately. - -@c 7 by 9.25 inches: -@c @smallbook -@c @clear largebook - -@c 8.5 by 11 inches: -@c @c smallbook -@c @set largebook - -@c European A4 size paper: -@c @c smallbook -@c @afourpaper -@c @set largebook - -@c ================ How to Typeset and Print ================ - -@c If you do not include PostScript figures, run either of the -@c following command sequences, or similar commands suited to your -@c system: - -@c texi2dvi emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c or else: - -@c tex emacs-lisp-intro.texi -@c texindex emacs-lisp-intro.?? -@c tex emacs-lisp-intro.texi -@c lpr -d emacs-lisp-intro.dvi - -@c If you include the PostScript figures, and you have old software, -@c you may need to convert the .dvi file to a .ps file before -@c printing. Run either of the following command sequences, or one -@c similar: -@c -@c dvips -f < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c -@c or else: -@c -@c postscript -p < emacs-lisp-intro.dvi > emacs-lisp-intro.ps -@c - -@c (Note: if you edit the book so as to change the length of the -@c table of contents, you may have to change the value of `pageno' below.) - -@c ================ End of Formatting Sections ================ - -@c For next or subsequent edition: -@c create function using with-output-to-temp-buffer -@c create a major mode, with keymaps -@c run an asynchronous process, like grep or diff - -@c For 8.5 by 11 inch format: do not use such a small amount of -@c whitespace between paragraphs as smallbook format -@ifset largebook -@tex -\global\parskip 6pt plus 1pt -@end tex -@end ifset - -@c For all sized formats: print within-book cross -@c reference with ``...'' rather than [...] - -@c This works with the texinfo.tex file, version 2003-05-04.08, -@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. - -@tex -\if \xrefprintnodename - \global\def\xrefprintnodename#1{\unskip, ``#1''} - \else - \global\def\xrefprintnodename#1{ ``#1''} -\fi -% \global\def\xrefprintnodename#1{, ``#1''} -@end tex - -@c ---------------------------------------------------- - -@dircategory Emacs -@direntry -* Emacs Lisp Intro: (eintr). - A simple introduction to Emacs Lisp programming. -@end direntry - -@copying -This is an @cite{Introduction to Programming in Emacs Lisp}, for -people who are not programmers. -@sp 1 -Edition @value{edition-number}, @value{update-date} -@sp 1 -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, - 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@sp 1 - -@iftex -Published by the:@* - -GNU Press, @hfill @uref{http://www.gnupress.org}@* -a division of the @hfill General: @email{press@@gnu.org}@* -Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* -51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@* -Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@* -@end iftex - -@ifnottex -Published by the: - -@example -GNU Press, Website: http://www.gnupress.org -a division of the General: press@@gnu.org -Free Software Foundation, Inc. Orders: sales@@gnu.org -51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942 -Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652 -@end example -@end ifnottex - -@sp 1 -@c Printed copies are available for $30 each.@* -ISBN 1-882114-43-4 - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; there -being no Invariant Section, with the Front-Cover Texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of -the license is included in the section entitled ``GNU Free -Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end copying - -@c half title; two lines here, so do not use `shorttitlepage' -@tex -{\begingroup% - \hbox{}\vskip 1.5in \chaprm \centerline{An Introduction to}% - \endgroup}% -{\begingroup\hbox{}\vskip 0.25in \chaprm% - \centerline{Programming in Emacs Lisp}% - \endgroup\page\hbox{}\page} -@end tex - -@titlepage -@sp 6 -@center @titlefont{An Introduction to} -@sp 2 -@center @titlefont{Programming in Emacs Lisp} -@sp 2 -@center Revised Third Edition -@sp 4 -@center by Robert J. Chassell - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@end iftex - -@ifnothtml -@c Keep T.O.C. short by tightening up for largebook -@ifset largebook -@tex -\global\parskip 2pt plus 1pt -\global\advance\baselineskip by -1pt -@end tex -@end ifset -@end ifnothtml - -@shortcontents -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@top An Introduction to Programming in Emacs Lisp - -@insertcopying - -This master menu first lists each chapter and index; then it lists -every node in every chapter. -@end ifnottex - -@c >>>> Set pageno appropriately <<<< - -@c The first page of the Preface is a roman numeral; it is the first -@c right handed page after the Table of Contents; hence the following -@c setting must be for an odd negative number. - -@c iftex -@c global@pageno = -11 -@c end iftex - -@menu -* Preface:: What to look for. -* List Processing:: What is Lisp? -* Practicing Evaluation:: Running several programs. -* Writing Defuns:: How to write function definitions. -* Buffer Walk Through:: Exploring a few buffer-related functions. -* More Complex:: A few, even more complex functions. -* Narrowing & Widening:: Restricting your and Emacs attention to - a region. -* car cdr & cons:: Fundamental functions in Lisp. -* Cutting & Storing Text:: Removing text and saving it. -* List Implementation:: How lists are implemented in the computer. -* Yanking:: Pasting stored text. -* Loops & Recursion:: How to repeat a process. -* Regexp Search:: Regular expression searches. -* Counting Words:: A review of repetition and regexps. -* Words in a defun:: Counting words in a @code{defun}. -* Readying a Graph:: A prototype graph printing function. -* Emacs Initialization:: How to write a @file{.emacs} file. -* Debugging:: How to run the Emacs Lisp debuggers. -* Conclusion:: Now you have the basics. -* the-the:: An appendix: how to find reduplicated words. -* Kill Ring:: An appendix: how the kill ring works. -* Full Graph:: How to create a graph with labelled axes. -* Free Software and Free Manuals:: -* GNU Free Documentation License:: -* Index:: -* About the Author:: - -@detailmenu - --- The Detailed Node Listing --- - -Preface - -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: - -List Processing - -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: - -Lisp Lists - -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. - -The Lisp Interpreter - -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. - -Evaluation - -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... - -Variables - -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. - -Arguments - -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. - -Setting the Value of a Variable - -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. - -Practicing Evaluation - -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: - -How To Write Function Definitions - -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: - -Install a Function Definition - -* Effect of installation:: -* Change a defun:: How to change a function definition. - -Make a Function Interactive - -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. - -@code{let} - -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: - -The @code{if} Special Form - -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. - -Truth and Falsehood in Emacs Lisp - -* nil explained:: @code{nil} has two meanings. - -@code{save-excursion} - -* Point and mark:: A review of various locations. -* Template for save-excursion:: - -A Few Buffer--Related Functions - -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: - -The Definition of @code{mark-whole-buffer} - -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. - -The Definition of @code{append-to-buffer} - -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. - -A Few More Complex Functions - -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: - -The Definition of @code{insert-buffer} - -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: - -The Interactive Expression in @code{insert-buffer} - -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. - -Complete Definition of @code{beginning-of-buffer} - -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: - -@code{beginning-of-buffer} with an Argument - -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: - -Narrowing and Widening - -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: - -@code{car}, @code{cdr}, @code{cons}: Fundamental Functions - -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: - -@code{cons} - -* Build a list:: -* length:: How to find the length of a list. - -Cutting and Storing Text - -* Storing Text:: Text is stored in a list. -* zap-to-char:: Cutting out text up to a character. -* kill-region:: Cutting text out of a region. -* copy-region-as-kill:: A definition for copying text. -* Digression into C:: Minor note on C programming language macros. -* defvar:: How to give a variable an initial value. -* cons & search-fwd Review:: -* search Exercises:: - -@code{zap-to-char} - -* Complete zap-to-char:: The complete implementation. -* zap-to-char interactive:: A three part interactive expression. -* zap-to-char body:: A short overview. -* search-forward:: How to search for a string. -* progn:: The @code{progn} special form. -* Summing up zap-to-char:: Using @code{point} and @code{search-forward}. - -@code{kill-region} - -* Complete kill-region:: The function definition. -* condition-case:: Dealing with a problem. -* Lisp macro:: - -@code{copy-region-as-kill} - -* Complete copy-region-as-kill:: The complete function definition. -* copy-region-as-kill body:: The body of @code{copy-region-as-kill}. - -The Body of @code{copy-region-as-kill} - -* last-command & this-command:: -* kill-append function:: -* kill-new function:: - -Initializing a Variable with @code{defvar} - -* See variable current value:: -* defvar and asterisk:: - -How Lists are Implemented - -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: - -Yanking Text Back - -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. - -Loops and Recursion - -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: - -@code{while} - -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. - -Details of an Incrementing Loop - -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. - -Loop with a Decrementing Counter - -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. - -Save your time: @code{dolist} and @code{dotimes} - -* dolist:: -* dotimes:: - -Recursion - -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: - -Recursion in Place of a Counter - -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: - -Recursive Patterns - -* Every:: -* Accumulate:: -* Keep:: - -Regular Expression Searches - -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: - -@code{forward-sentence} - -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. - -@code{forward-paragraph}: a Goldmine of Functions - -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. - -Counting: Repetition and Regexps - -* Why Count Words:: -* count-words-region:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: - -The @code{count-words-region} Function - -* Design count-words-region:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. - -Counting Words in a @code{defun} - -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{count-words}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. - -Count Words in @code{defuns} in Different Files - -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. - -Prepare the Data for Display in a Graph - -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: - -Readying a Graph - -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: - -Your @file{.emacs} File - -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. - -Debugging - -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: - -Handling the Kill Ring - -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: - -The @code{current-kill} Function - -* Code for current-kill:: -* Understanding current-kill:: - -@code{current-kill} in Outline - -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: - -A Graph with Labelled Axes - -* Labelled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. - -The @code{print-Y-axis} Function - -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. - -The @code{print-X-axis} Function - -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. - -Printing the Whole Graph - -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! - -@end detailmenu -@end menu - -@node Preface, List Processing, Top, Top -@comment node-name, next, previous, up -@unnumbered Preface - -Most of the GNU Emacs integrated environment is written in the programming -language called Emacs Lisp. The code written in this programming -language is the software---the sets of instructions---that tell the -computer what to do when you give it commands. Emacs is designed so -that you can write new code in Emacs Lisp and easily install it as an -extension to the editor. - -(GNU Emacs is sometimes called an ``extensible editor'', but it does -much more than provide editing capabilities. It is better to refer to -Emacs as an ``extensible computing environment''. However, that -phrase is quite a mouthful. It is easier to refer to Emacs simply as -an editor. Moreover, everything you do in Emacs---find the Mayan date -and phases of the moon, simplify polynomials, debug code, manage -files, read letters, write books---all these activities are kinds of -editing in the most general sense of the word.) - -@menu -* Why:: Why learn Emacs Lisp? -* On Reading this Text:: Read, gain familiarity, pick up habits.... -* Who You Are:: For whom this is written. -* Lisp History:: -* Note for Novices:: You can read this as a novice. -* Thank You:: -@end menu - -@node Why, On Reading this Text, Preface, Preface -@ifnottex -@unnumberedsec Why Study Emacs Lisp? -@end ifnottex - -Although Emacs Lisp is usually thought of in association only with Emacs, -it is a full computer programming language. You can use Emacs Lisp as -you would any other programming language. - -Perhaps you want to understand programming; perhaps you want to extend -Emacs; or perhaps you want to become a programmer. This introduction to -Emacs Lisp is designed to get you started: to guide you in learning the -fundamentals of programming, and more importantly, to show you how you -can teach yourself to go further. - -@node On Reading this Text, Who You Are, Why, Preface -@comment node-name, next, previous, up -@unnumberedsec On Reading this Text - -All through this document, you will see little sample programs you can -run inside of Emacs. If you read this document in Info inside of GNU -Emacs, you can run the programs as they appear. (This is easy to do and -is explained when the examples are presented.) Alternatively, you can -read this introduction as a printed book while sitting beside a computer -running Emacs. (This is what I like to do; I like printed books.) If -you don't have a running Emacs beside you, you can still read this book, -but in this case, it is best to treat it as a novel or as a travel guide -to a country not yet visited: interesting, but not the same as being -there. - -Much of this introduction is dedicated to walk-throughs or guided tours -of code used in GNU Emacs. These tours are designed for two purposes: -first, to give you familiarity with real, working code (code you use -every day); and, second, to give you familiarity with the way Emacs -works. It is interesting to see how a working environment is -implemented. -Also, I -hope that you will pick up the habit of browsing through source code. -You can learn from it and mine it for ideas. Having GNU Emacs is like -having a dragon's cave of treasures. - -In addition to learning about Emacs as an editor and Emacs Lisp as a -programming language, the examples and guided tours will give you an -opportunity to get acquainted with Emacs as a Lisp programming -environment. GNU Emacs supports programming and provides tools that -you will want to become comfortable using, such as @kbd{M-.} (the key -which invokes the @code{find-tag} command). You will also learn about -buffers and other objects that are part of the environment. -Learning about these features of Emacs is like learning new routes -around your home town. - -@ignore -In addition, I have written several programs as extended examples. -Although these are examples, the programs are real. I use them. -Other people use them. You may use them. Beyond the fragments of -programs used for illustrations, there is very little in here that is -`just for teaching purposes'; what you see is used. This is a great -advantage of Emacs Lisp: it is easy to learn to use it for work. -@end ignore - -Finally, I hope to convey some of the skills for using Emacs to -learn aspects of programming that you don't know. You can often use -Emacs to help you understand what puzzles you or to find out how to do -something new. This self-reliance is not only a pleasure, but an -advantage. - -@node Who You Are, Lisp History, On Reading this Text, Preface -@comment node-name, next, previous, up -@unnumberedsec For Whom This is Written - -This text is written as an elementary introduction for people who are -not programmers. If you are a programmer, you may not be satisfied with -this primer. The reason is that you may have become expert at reading -reference manuals and be put off by the way this text is organized. - -An expert programmer who reviewed this text said to me: - -@quotation -@i{I prefer to learn from reference manuals. I ``dive into'' each -paragraph, and ``come up for air'' between paragraphs.} - -@i{When I get to the end of a paragraph, I assume that that subject is -done, finished, that I know everything I need (with the -possible exception of the case when the next paragraph starts talking -about it in more detail). I expect that a well written reference manual -will not have a lot of redundancy, and that it will have excellent -pointers to the (one) place where the information I want is.} -@end quotation - -This introduction is not written for this person! - -Firstly, I try to say everything at least three times: first, to -introduce it; second, to show it in context; and third, to show it in a -different context, or to review it. - -Secondly, I hardly ever put all the information about a subject in one -place, much less in one paragraph. To my way of thinking, that imposes -too heavy a burden on the reader. Instead I try to explain only what -you need to know at the time. (Sometimes I include a little extra -information so you won't be surprised later when the additional -information is formally introduced.) - -When you read this text, you are not expected to learn everything the -first time. Frequently, you need only make, as it were, a `nodding -acquaintance' with some of the items mentioned. My hope is that I have -structured the text and given you enough hints that you will be alert to -what is important, and concentrate on it. - -You will need to ``dive into'' some paragraphs; there is no other way -to read them. But I have tried to keep down the number of such -paragraphs. This book is intended as an approachable hill, rather than -as a daunting mountain. - -This introduction to @cite{Programming in Emacs Lisp} has a companion -document, -@iftex -@cite{The GNU Emacs Lisp Reference Manual}. -@end iftex -@ifnottex -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifnottex -The reference manual has more detail than this introduction. In the -reference manual, all the information about one topic is concentrated -in one place. You should turn to it if you are like the programmer -quoted above. And, of course, after you have read this -@cite{Introduction}, you will find the @cite{Reference Manual} useful -when you are writing your own programs. - -@node Lisp History, Note for Novices, Who You Are, Preface -@unnumberedsec Lisp History -@cindex Lisp history - -Lisp was first developed in the late 1950s at the Massachusetts -Institute of Technology for research in artificial intelligence. The -great power of the Lisp language makes it superior for other purposes as -well, such as writing editor commands and integrated environments. - -@cindex Maclisp -@cindex Common Lisp -GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT -in the 1960s. It is somewhat inspired by Common Lisp, which became a -standard in the 1980s. However, Emacs Lisp is much simpler than Common -Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) - -@node Note for Novices, Thank You, Lisp History, Preface -@comment node-name, next, previous, up -@unnumberedsec A Note for Novices - -If you don't know GNU Emacs, you can still read this document -profitably. However, I recommend you learn Emacs, if only to learn to -move around your computer screen. You can teach yourself how to use -Emacs with the on-line tutorial. To use it, type @kbd{C-h t}. (This -means you press and release the @key{CTRL} key and the @kbd{h} at the -same time, and then press and release @kbd{t}.) - -Also, I often refer to one of Emacs' standard commands by listing the -keys which you press to invoke the command and then giving the name of -the command in parentheses, like this: @kbd{M-C-\} -(@code{indent-region}). What this means is that the -@code{indent-region} command is customarily invoked by typing -@kbd{M-C-\}. (You can, if you wish, change the keys that are typed to -invoke the command; this is called @dfn{rebinding}. @xref{Keymaps, , -Keymaps}.) The abbreviation @kbd{M-C-\} means that you type your -@key{META} key, @key{CTRL} key and @key{\} key all at the same time. -(On many modern keyboards the @key{META} key is labelled -@key{ALT}.) -Sometimes a combination like this is called a keychord, since it is -similar to the way you play a chord on a piano. If your keyboard does -not have a @key{META} key, the @key{ESC} key prefix is used in place -of it. In this case, @kbd{M-C-\} means that you press and release your -@key{ESC} key and then type the @key{CTRL} key and the @key{\} key at -the same time. But usually @kbd{M-C-\} means press the @key{CTRL} key -along with the key that is labelled @key{ALT} and, at the same time, -press the @key{\} key. - -In addition to typing a lone keychord, you can prefix what you type -with @kbd{C-u}, which is called the `universal argument'. The -@kbd{C-u} keychord passes an argument to the subsequent command. -Thus, to indent a region of plain text by 6 spaces, mark the region, -and then type @w{@kbd{C-u 6 M-C-\}}. (If you do not specify a number, -Emacs either passes the number 4 to the command or otherwise runs the -command differently than it would otherwise.) @xref{Arguments, , -Numeric Arguments, emacs, The GNU Emacs Manual}. - -If you are reading this in Info using GNU Emacs, you can read through -this whole document just by pressing the space bar, @key{SPC}. -(To learn about Info, type @kbd{C-h i} and then select Info.) - -A note on terminology: when I use the word Lisp alone, I often am -referring to the various dialects of Lisp in general, but when I speak -of Emacs Lisp, I am referring to GNU Emacs Lisp in particular. - -@node Thank You, , Note for Novices, Preface -@comment node-name, next, previous, up -@unnumberedsec Thank You - -My thanks to all who helped me with this book. My especial thanks to -@r{Jim Blandy}, @r{Noah Friedman}, @w{Jim Kingdon}, @r{Roland -McGrath}, @w{Frank Ritter}, @w{Randy Smith}, @w{Richard M.@: -Stallman}, and @w{Melissa Weisshaus}. My thanks also go to both -@w{Philip Johnson} and @w{David Stampe} for their patient -encouragement. My mistakes are my own. - -@flushright -Robert J. Chassell -@email{bob@@gnu.org} -@end flushright - -@c ================ Beginning of main text ================ - -@c Start main text on right-hand (verso) page - -@tex -\par\vfill\supereject -\headings off -\ifodd\pageno - \par\vfill\supereject -\else - \par\vfill\supereject - \page\hbox{}\page - \par\vfill\supereject -\fi -@end tex - -@iftex -@headings off -@evenheading @thispage @| @| @thischapter -@oddheading @thissection @| @| @thispage -@global@pageno = 1 -@end iftex - -@node List Processing, Practicing Evaluation, Preface, Top -@comment node-name, next, previous, up -@chapter List Processing - -To the untutored eye, Lisp is a strange programming language. In Lisp -code there are parentheses everywhere. Some people even claim that -the name stands for `Lots of Isolated Silly Parentheses'. But the -claim is unwarranted. Lisp stands for LISt Processing, and the -programming language handles @emph{lists} (and lists of lists) by -putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. - -@menu -* Lisp Lists:: What are lists? -* Run a Program:: Any list in Lisp is a program ready to run. -* Making Errors:: Generating an error message. -* Names & Definitions:: Names of symbols and function definitions. -* Lisp Interpreter:: What the Lisp interpreter does. -* Evaluation:: Running a program. -* Variables:: Returning a value from a variable. -* Arguments:: Passing information to a function. -* set & setq:: Setting the value of a variable. -* Summary:: The major points. -* Error Message Exercises:: -@end menu - -@node Lisp Lists, Run a Program, List Processing, List Processing -@comment node-name, next, previous, up -@section Lisp Lists -@cindex Lisp Lists - -In Lisp, a list looks like this: @code{'(rose violet daisy buttercup)}. -This list is preceded by a single apostrophe. It could just as well be -written as follows, which looks more like the kind of list you are likely -to be familiar with: - -@smallexample -@group -'(rose - violet - daisy - buttercup) -@end group -@end smallexample - -@noindent -The elements of this list are the names of the four different flowers, -separated from each other by whitespace and surrounded by parentheses, -like flowers in a field with a stone wall around them. -@cindex Flowers in a field - -@menu -* Numbers Lists:: List have numbers, other lists, in them. -* Lisp Atoms:: Elemental entities. -* Whitespace in Lists:: Formatting lists to be readable. -* Typing Lists:: How GNU Emacs helps you type lists. -@end menu - -@node Numbers Lists, Lisp Atoms, Lisp Lists, Lisp Lists -@ifnottex -@unnumberedsubsec Numbers, Lists inside of Lists -@end ifnottex - -Lists can also have numbers in them, as in this list: @code{(+ 2 2)}. -This list has a plus-sign, @samp{+}, followed by two @samp{2}s, each -separated by whitespace. - -In Lisp, both data and programs are represented the same way; that is, -they are both lists of words, numbers, or other lists, separated by -whitespace and surrounded by parentheses. (Since a program looks like -data, one program may easily serve as data for another; this is a very -powerful feature of Lisp.) (Incidentally, these two parenthetical -remarks are @emph{not} Lisp lists, because they contain @samp{;} and -@samp{.} as punctuation marks.) - -@need 1200 -Here is another list, this time with a list inside of it: - -@smallexample -'(this list has (a list inside of it)) -@end smallexample - -The components of this list are the words @samp{this}, @samp{list}, -@samp{has}, and the list @samp{(a list inside of it)}. The interior -list is made up of the words @samp{a}, @samp{list}, @samp{inside}, -@samp{of}, @samp{it}. - -@node Lisp Atoms, Whitespace in Lists, Numbers Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection Lisp Atoms -@cindex Lisp Atoms - -In Lisp, what we have been calling words are called @dfn{atoms}. This -term comes from the historical meaning of the word atom, which means -`indivisible'. As far as Lisp is concerned, the words we have been -using in the lists cannot be divided into any smaller parts and still -mean the same thing as part of a program; likewise with numbers and -single character symbols like @samp{+}. On the other hand, unlike an -ancient atom, a list can be split into parts. (@xref{car cdr & cons, -, @code{car} @code{cdr} & @code{cons} Fundamental Functions}.) - -In a list, atoms are separated from each other by whitespace. They can be -right next to a parenthesis. - -@cindex @samp{empty list} defined -Technically speaking, a list in Lisp consists of parentheses surrounding -atoms separated by whitespace or surrounding other lists or surrounding -both atoms and other lists. A list can have just one atom in it or -have nothing in it at all. A list with nothing in it looks like this: -@code{()}, and is called the @dfn{empty list}. Unlike anything else, an -empty list is considered both an atom and a list at the same time. - -@cindex Symbolic expressions, introduced -@cindex @samp{expression} defined -@cindex @samp{form} defined -The printed representation of both atoms and lists are called -@dfn{symbolic expressions} or, more concisely, @dfn{s-expressions}. -The word @dfn{expression} by itself can refer to either the printed -representation, or to the atom or list as it is held internally in the -computer. Often, people use the term @dfn{expression} -indiscriminately. (Also, in many texts, the word @dfn{form} is used -as a synonym for expression.) - -Incidentally, the atoms that make up our universe were named such when -they were thought to be indivisible; but it has been found that physical -atoms are not indivisible. Parts can split off an atom or it can -fission into two parts of roughly equal size. Physical atoms were named -prematurely, before their truer nature was found. In Lisp, certain -kinds of atom, such as an array, can be separated into parts; but the -mechanism for doing this is different from the mechanism for splitting a -list. As far as list operations are concerned, the atoms of a list are -unsplittable. - -As in English, the meanings of the component letters of a Lisp atom -are different from the meaning the letters make as a word. For -example, the word for the South American sloth, the @samp{ai}, is -completely different from the two words, @samp{a}, and @samp{i}. - -There are many kinds of atom in nature but only a few in Lisp: for -example, @dfn{numbers}, such as 37, 511, or 1729, and @dfn{symbols}, such -as @samp{+}, @samp{foo}, or @samp{forward-line}. The words we have -listed in the examples above are all symbols. In everyday Lisp -conversation, the word ``atom'' is not often used, because programmers -usually try to be more specific about what kind of atom they are dealing -with. Lisp programming is mostly about symbols (and sometimes numbers) -within lists. (Incidentally, the preceding three word parenthetical -remark is a proper list in Lisp, since it consists of atoms, which in -this case are symbols, separated by whitespace and enclosed by -parentheses, without any non-Lisp punctuation.) - -@need 1250 -Text between double quotation marks---even sentences or -paragraphs---is also an atom. Here is an example: -@cindex Text between double quotation marks - -@smallexample -'(this list includes "text between quotation marks.") -@end smallexample - -@cindex @samp{string} defined -@noindent -In Lisp, all of the quoted text including the punctuation mark and the -blank spaces is a single atom. This kind of atom is called a -@dfn{string} (for `string of characters') and is the sort of thing that -is used for messages that a computer can print for a human to read. -Strings are a different kind of atom than numbers or symbols and are -used differently. - -@node Whitespace in Lists, Typing Lists, Lisp Atoms, Lisp Lists -@comment node-name, next, previous, up -@subsection Whitespace in Lists -@cindex Whitespace in lists - -@need 1200 -The amount of whitespace in a list does not matter. From the point of view -of the Lisp language, - -@smallexample -@group -'(this list - looks like this) -@end group -@end smallexample - -@need 800 -@noindent -is exactly the same as this: - -@smallexample -'(this list looks like this) -@end smallexample - -Both examples show what to Lisp is the same list, the list made up of -the symbols @samp{this}, @samp{list}, @samp{looks}, @samp{like}, and -@samp{this} in that order. - -Extra whitespace and newlines are designed to make a list more readable -by humans. When Lisp reads the expression, it gets rid of all the extra -whitespace (but it needs to have at least one space between atoms in -order to tell them apart.) - -Odd as it seems, the examples we have seen cover almost all of what Lisp -lists look like! Every other list in Lisp looks more or less like one -of these examples, except that the list may be longer and more complex. -In brief, a list is between parentheses, a string is between quotation -marks, a symbol looks like a word, and a number looks like a number. -(For certain situations, square brackets, dots and a few other special -characters may be used; however, we will go quite far without them.) - -@node Typing Lists, , Whitespace in Lists, Lisp Lists -@comment node-name, next, previous, up -@subsection GNU Emacs Helps You Type Lists -@cindex Help typing lists -@cindex Formatting help - -When you type a Lisp expression in GNU Emacs using either Lisp -Interaction mode or Emacs Lisp mode, you have available to you several -commands to format the Lisp expression so it is easy to read. For -example, pressing the @key{TAB} key automatically indents the line the -cursor is on by the right amount. A command to properly indent the -code in a region is customarily bound to @kbd{M-C-\}. Indentation is -designed so that you can see which elements of a list belong to which -list---elements of a sub-list are indented more than the elements of -the enclosing list. - -In addition, when you type a closing parenthesis, Emacs momentarily -jumps the cursor back to the matching opening parenthesis, so you can -see which one it is. This is very useful, since every list you type -in Lisp must have its closing parenthesis match its opening -parenthesis. (@xref{Major Modes, , Major Modes, emacs, The GNU Emacs -Manual}, for more information about Emacs' modes.) - -@node Run a Program, Making Errors, Lisp Lists, List Processing -@comment node-name, next, previous, up -@section Run a Program -@cindex Run a program -@cindex Program, running one - -@cindex @samp{evaluate} defined -A list in Lisp---any list---is a program ready to run. If you run it -(for which the Lisp jargon is @dfn{evaluate}), the computer will do one -of three things: do nothing except return to you the list itself; send -you an error message; or, treat the first symbol in the list as a -command to do something. (Usually, of course, it is the last of these -three things that you really want!) - -@c use code for the single apostrophe, not samp. -The single apostrophe, @code{'}, that I put in front of some of the -example lists in preceding sections is called a @dfn{quote}; when it -precedes a list, it tells Lisp to do nothing with the list, other than -take it as it is written. But if there is no quote preceding a list, -the first item of the list is special: it is a command for the computer -to obey. (In Lisp, these commands are called @emph{functions}.) The list -@code{(+ 2 2)} shown above did not have a quote in front of it, so Lisp -understands that the @code{+} is an instruction to do something with the -rest of the list: add the numbers that follow. - -@need 1250 -If you are reading this inside of GNU Emacs in Info, here is how you can -evaluate such a list: place your cursor immediately after the right -hand parenthesis of the following list and then type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@c use code for the number four, not samp. -@noindent -You will see the number @code{4} appear in the echo area. (In the -jargon, what you have just done is ``evaluate the list.'' The echo area -is the line at the bottom of the screen that displays or ``echoes'' -text.) Now try the same thing with a quoted list: place the cursor -right after the following list and type @kbd{C-x C-e}: - -@smallexample -'(this is a quoted list) -@end smallexample - -@noindent -You will see @code{(this is a quoted list)} appear in the echo area. - -@cindex Lisp interpreter, explained -@cindex Interpreter, Lisp, explained -In both cases, what you are doing is giving a command to the program -inside of GNU Emacs called the @dfn{Lisp interpreter}---giving the -interpreter a command to evaluate the expression. The name of the Lisp -interpreter comes from the word for the task done by a human who comes -up with the meaning of an expression---who ``interprets'' it. - -You can also evaluate an atom that is not part of a list---one that is -not surrounded by parentheses; again, the Lisp interpreter translates -from the humanly readable expression to the language of the computer. -But before discussing this (@pxref{Variables}), we will discuss what the -Lisp interpreter does when you make an error. - -@node Making Errors, Names & Definitions, Run a Program, List Processing -@comment node-name, next, previous, up -@section Generate an Error Message -@cindex Generate an error message -@cindex Error message generation - -Partly so you won't worry if you do it accidentally, we will now give -a command to the Lisp interpreter that generates an error message. -This is a harmless activity; and indeed, we will often try to generate -error messages intentionally. Once you understand the jargon, error -messages can be informative. Instead of being called ``error'' -messages, they should be called ``help'' messages. They are like -signposts to a traveller in a strange country; deciphering them can be -hard, but once understood, they can point the way. - -The error message is generated by a built-in GNU Emacs debugger. We -will `enter the debugger'. You get out of the debugger by typing @code{q}. - -What we will do is evaluate a list that is not quoted and does not -have a meaningful command as its first element. Here is a list almost -exactly the same as the one we just used, but without the single-quote -in front of it. Position the cursor right after it and type @kbd{C-x -C-e}: - -@smallexample -(this is an unquoted list) -@end smallexample - -@noindent -What you see depends on which version of Emacs you are running. GNU -Emacs version 22 provides more information than version 20 and before. -First, the more recent result of generating an error; then the -earlier, version 20 result. - -@need 1250 -@noindent -In GNU Emacs version 22, a @file{*Backtrace*} window will open up and -you will see the following in it: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function this) - (this is an unquoted list) - eval((this is an unquoted list)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1200 -@noindent -Your cursor will be in this window (you may have to wait a few seconds -before it becomes visible). To quit the debugger and make the -debugger window go away, type: - -@smallexample -q -@end smallexample - -@noindent -Please type @kbd{q} right now, so you become confident that you can -get out of the debugger. Then, type @kbd{C-x C-e} again to re-enter -it. - -@cindex @samp{function} defined -Based on what we already know, we can almost read this error message. - -You read the @file{*Backtrace*} buffer from the bottom up; it tells -you what Emacs did. When you typed @kbd{C-x C-e}, you made an -interactive call to the command @code{eval-last-sexp}. @code{eval} is -an abbreviation for `evaluate' and @code{sexp} is an abbreviation for -`symbolic expression'. The command means `evaluate last symbolic -expression', which is the expression just before your cursor. - -Each line above tells you what the Lisp interpreter evaluated next. -The most recent action is at the top. The buffer is called the -@file{*Backtrace*} buffer because it enables you to track Emacs -backwards. - -@need 800 -At the top of the @file{*Backtrace*} buffer, you see the line: - -@smallexample -Debugger entered--Lisp error: (void-function this) -@end smallexample - -@noindent -The Lisp interpreter tried to evaluate the first atom of the list, the -word @samp{this}. It is this action that generated the error message -@samp{void-function this}. - -The message contains the words @samp{void-function} and @samp{this}. - -@cindex @samp{function} defined -The word @samp{function} was mentioned once before. It is a very -important word. For our purposes, we can define it by saying that a -@dfn{function} is a set of instructions to the computer that tell the -computer to do something. - -Now we can begin to understand the error message: @samp{void-function -this}. The function (that is, the word @samp{this}) does not have a -definition of any set of instructions for the computer to carry out. - -The slightly odd word, @samp{void-function}, is designed to cover the -way Emacs Lisp is implemented, which is that when a symbol does not -have a function definition attached to it, the place that should -contain the instructions is `void'. - -On the other hand, since we were able to add 2 plus 2 successfully, by -evaluating @code{(+ 2 2)}, we can infer that the symbol @code{+} must -have a set of instructions for the computer to obey and those -instructions must be to add the numbers that follow the @code{+}. - -@need 1250 -In GNU Emacs version 20, and in earlier versions, you will see only -one line of error message; it will appear in the echo area and look -like this: - -@smallexample -Symbol's function definition is void:@: this -@end smallexample - -@noindent -(Also, your terminal may beep at you---some do, some don't; and others -blink. This is just a device to get your attention.) The message goes -away as soon as you type another key, even just to move the cursor. - -We know the meaning of the word @samp{Symbol}. It refers to the first -atom of the list, the word @samp{this}. The word @samp{function} -refers to the instructions that tell the computer what to do. -(Technically, the symbol tells the computer where to find the -instructions, but this is a complication we can ignore for the -moment.) - -The error message can be understood: @samp{Symbol's function -definition is void:@: this}. The symbol (that is, the word -@samp{this}) lacks instructions for the computer to carry out. - -@node Names & Definitions, Lisp Interpreter, Making Errors, List Processing -@comment node-name, next, previous, up -@section Symbol Names and Function Definitions -@cindex Symbol names - -We can articulate another characteristic of Lisp based on what we have -discussed so far---an important characteristic: a symbol, like -@code{+}, is not itself the set of instructions for the computer to -carry out. Instead, the symbol is used, perhaps temporarily, as a way -of locating the definition or set of instructions. What we see is the -name through which the instructions can be found. Names of people -work the same way. I can be referred to as @samp{Bob}; however, I am -not the letters @samp{B}, @samp{o}, @samp{b} but am, or was, the -consciousness consistently associated with a particular life-form. -The name is not me, but it can be used to refer to me. - -In Lisp, one set of instructions can be attached to several names. -For example, the computer instructions for adding numbers can be -linked to the symbol @code{plus} as well as to the symbol @code{+} -(and are in some dialects of Lisp). Among humans, I can be referred -to as @samp{Robert} as well as @samp{Bob} and by other words as well. - -On the other hand, a symbol can have only one function definition -attached to it at a time. Otherwise, the computer would be confused as -to which definition to use. If this were the case among people, only -one person in the world could be named @samp{Bob}. However, the function -definition to which the name refers can be changed readily. -(@xref{Install, , Install a Function Definition}.) - -Since Emacs Lisp is large, it is customary to name symbols in a way -that identifies the part of Emacs to which the function belongs. -Thus, all the names for functions that deal with Texinfo start with -@samp{texinfo-} and those for functions that deal with reading mail -start with @samp{rmail-}. - -@node Lisp Interpreter, Evaluation, Names & Definitions, List Processing -@comment node-name, next, previous, up -@section The Lisp Interpreter -@cindex Lisp interpreter, what it does -@cindex Interpreter, what it does - -Based on what we have seen, we can now start to figure out what the -Lisp interpreter does when we command it to evaluate a list. -First, it looks to see whether there is a quote before the list; if -there is, the interpreter just gives us the list. On the other -hand, if there is no quote, the interpreter looks at the first element -in the list and sees whether it has a function definition. If it does, -the interpreter carries out the instructions in the function definition. -Otherwise, the interpreter prints an error message. - -This is how Lisp works. Simple. There are added complications which we -will get to in a minute, but these are the fundamentals. Of course, to -write Lisp programs, you need to know how to write function definitions -and attach them to names, and how to do this without confusing either -yourself or the computer. - -@menu -* Complications:: Variables, Special forms, Lists within. -* Byte Compiling:: Specially processing code for speed. -@end menu - -@node Complications, Byte Compiling, Lisp Interpreter, Lisp Interpreter -@ifnottex -@unnumberedsubsec Complications -@end ifnottex - -Now, for the first complication. In addition to lists, the Lisp -interpreter can evaluate a symbol that is not quoted and does not have -parentheses around it. The Lisp interpreter will attempt to determine -the symbol's value as a @dfn{variable}. This situation is described -in the section on variables. (@xref{Variables}.) - -@cindex Special form -The second complication occurs because some functions are unusual and do -not work in the usual manner. Those that don't are called @dfn{special -forms}. They are used for special jobs, like defining a function, and -there are not many of them. In the next few chapters, you will be -introduced to several of the more important special forms. - -The third and final complication is this: if the function that the -Lisp interpreter is looking at is not a special form, and if it is part -of a list, the Lisp interpreter looks to see whether the list has a list -inside of it. If there is an inner list, the Lisp interpreter first -figures out what it should do with the inside list, and then it works on -the outside list. If there is yet another list embedded inside the -inner list, it works on that one first, and so on. It always works on -the innermost list first. The interpreter works on the innermost list -first, to evaluate the result of that list. The result may be -used by the enclosing expression. - -Otherwise, the interpreter works left to right, from one expression to -the next. - -@node Byte Compiling, , Complications, Lisp Interpreter -@subsection Byte Compiling -@cindex Byte compiling - -One other aspect of interpreting: the Lisp interpreter is able to -interpret two kinds of entity: humanly readable code, on which we will -focus exclusively, and specially processed code, called @dfn{byte -compiled} code, which is not humanly readable. Byte compiled code -runs faster than humanly readable code. - -You can transform humanly readable code into byte compiled code by -running one of the compile commands such as @code{byte-compile-file}. -Byte compiled code is usually stored in a file that ends with a -@file{.elc} extension rather than a @file{.el} extension. You will -see both kinds of file in the @file{emacs/lisp} directory; the files -to read are those with @file{.el} extensions. - -As a practical matter, for most things you might do to customize or -extend Emacs, you do not need to byte compile; and I will not discuss -the topic here. @xref{Byte Compilation, , Byte Compilation, elisp, -The GNU Emacs Lisp Reference Manual}, for a full description of byte -compilation. - -@node Evaluation, Variables, Lisp Interpreter, List Processing -@comment node-name, next, previous, up -@section Evaluation -@cindex Evaluation - -When the Lisp interpreter works on an expression, the term for the -activity is called @dfn{evaluation}. We say that the interpreter -`evaluates the expression'. I've used this term several times before. -The word comes from its use in everyday language, `to ascertain the -value or amount of; to appraise', according to @cite{Webster's New -Collegiate Dictionary}. - -@menu -* How the Interpreter Acts:: Returns and Side Effects... -* Evaluating Inner Lists:: Lists within lists... -@end menu - -@node How the Interpreter Acts, Evaluating Inner Lists, Evaluation, Evaluation -@ifnottex -@unnumberedsubsec How the Lisp Interpreter Acts -@end ifnottex - -@cindex @samp{returned value} explained -After evaluating an expression, the Lisp interpreter will most likely -@dfn{return} the value that the computer produces by carrying out the -instructions it found in the function definition, or perhaps it will -give up on that function and produce an error message. (The interpreter -may also find itself tossed, so to speak, to a different function or it -may attempt to repeat continually what it is doing for ever and ever in -what is called an `infinite loop'. These actions are less common; and -we can ignore them.) Most frequently, the interpreter returns a value. - -@cindex @samp{side effect} defined -At the same time the interpreter returns a value, it may do something -else as well, such as move a cursor or copy a file; this other kind of -action is called a @dfn{side effect}. Actions that we humans think are -important, such as printing results, are often ``side effects'' to the -Lisp interpreter. The jargon can sound peculiar, but it turns out that -it is fairly easy to learn to use side effects. - -In summary, evaluating a symbolic expression most commonly causes the -Lisp interpreter to return a value and perhaps carry out a side effect; -or else produce an error. - -@node Evaluating Inner Lists, , How the Interpreter Acts, Evaluation -@comment node-name, next, previous, up -@subsection Evaluating Inner Lists -@cindex Inner list evaluation -@cindex Evaluating inner lists - -If evaluation applies to a list that is inside another list, the outer -list may use the value returned by the first evaluation as information -when the outer list is evaluated. This explains why inner expressions -are evaluated first: the values they return are used by the outer -expressions. - -@need 1250 -We can investigate this process by evaluating another addition example. -Place your cursor after the following expression and type @kbd{C-x C-e}: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -The number 8 will appear in the echo area. - -What happens is that the Lisp interpreter first evaluates the inner -expression, @code{(+ 3 3)}, for which the value 6 is returned; then it -evaluates the outer expression as if it were written @code{(+ 2 6)}, which -returns the value 8. Since there are no more enclosing expressions to -evaluate, the interpreter prints that value in the echo area. - -Now it is easy to understand the name of the command invoked by the -keystrokes @kbd{C-x C-e}: the name is @code{eval-last-sexp}. The -letters @code{sexp} are an abbreviation for `symbolic expression', and -@code{eval} is an abbreviation for `evaluate'. The command means -`evaluate last symbolic expression'. - -As an experiment, you can try evaluating the expression by putting the -cursor at the beginning of the next line immediately following the -expression, or inside the expression. - -@need 800 -Here is another copy of the expression: - -@smallexample -(+ 2 (+ 3 3)) -@end smallexample - -@noindent -If you place the cursor at the beginning of the blank line that -immediately follows the expression and type @kbd{C-x C-e}, you will -still get the value 8 printed in the echo area. Now try putting the -cursor inside the expression. If you put it right after the next to -last parenthesis (so it appears to sit on top of the last parenthesis), -you will get a 6 printed in the echo area! This is because the command -evaluates the expression @code{(+ 3 3)}. - -Now put the cursor immediately after a number. Type @kbd{C-x C-e} and -you will get the number itself. In Lisp, if you evaluate a number, you -get the number itself---this is how numbers differ from symbols. If you -evaluate a list starting with a symbol like @code{+}, you will get a -value returned that is the result of the computer carrying out the -instructions in the function definition attached to that name. If a -symbol by itself is evaluated, something different happens, as we will -see in the next section. - -@node Variables, Arguments, Evaluation, List Processing -@comment node-name, next, previous, up -@section Variables -@cindex Variables - -In Emacs Lisp, a symbol can have a value attached to it just as it can -have a function definition attached to it. The two are different. -The function definition is a set of instructions that a computer will -obey. A value, on the other hand, is something, such as number or a -name, that can vary (which is why such a symbol is called a variable). -The value of a symbol can be any expression in Lisp, such as a symbol, -number, list, or string. A symbol that has a value is often called a -@dfn{variable}. - -A symbol can have both a function definition and a value attached to -it at the same time. Or it can have just one or the other. -The two are separate. This is somewhat similar -to the way the name Cambridge can refer to the city in Massachusetts -and have some information attached to the name as well, such as -``great programming center''. - -@ignore -(Incidentally, in Emacs Lisp, a symbol can have two -other things attached to it, too: a property list and a documentation -string; these are discussed later.) -@end ignore - -Another way to think about this is to imagine a symbol as being a chest -of drawers. The function definition is put in one drawer, the value in -another, and so on. What is put in the drawer holding the value can be -changed without affecting the contents of the drawer holding the -function definition, and vice-verse. - -@menu -* fill-column Example:: -* Void Function:: The error message for a symbol - without a function. -* Void Variable:: The error message for a symbol without a value. -@end menu - -@node fill-column Example, Void Function, Variables, Variables -@ifnottex -@unnumberedsubsec @code{fill-column}, an Example Variable -@end ifnottex - -@findex fill-column, @r{an example variable} -@cindex Example variable, @code{fill-column} -@cindex Variable, example of, @code{fill-column} -The variable @code{fill-column} illustrates a symbol with a value -attached to it: in every GNU Emacs buffer, this symbol is set to some -value, usually 72 or 70, but sometimes to some other value. To find the -value of this symbol, evaluate it by itself. If you are reading this in -Info inside of GNU Emacs, you can do this by putting the cursor after -the symbol and typing @kbd{C-x C-e}: - -@smallexample -fill-column -@end smallexample - -@noindent -After I typed @kbd{C-x C-e}, Emacs printed the number 72 in my echo -area. This is the value for which @code{fill-column} is set for me as I -write this. It may be different for you in your Info buffer. Notice -that the value returned as a variable is printed in exactly the same way -as the value returned by a function carrying out its instructions. From -the point of view of the Lisp interpreter, a value returned is a value -returned. What kind of expression it came from ceases to matter once -the value is known. - -A symbol can have any value attached to it or, to use the jargon, we can -@dfn{bind} the variable to a value: to a number, such as 72; to a -string, @code{"such as this"}; to a list, such as @code{(spruce pine -oak)}; we can even bind a variable to a function definition. - -A symbol can be bound to a value in several ways. @xref{set & setq, , -Setting the Value of a Variable}, for information about one way to do -this. - -@node Void Function, Void Variable, fill-column Example, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Function -@cindex Symbol without function error -@cindex Error for symbol without function - -When we evaluated @code{fill-column} to find its value as a variable, -we did not place parentheses around the word. This is because we did -not intend to use it as a function name. - -If @code{fill-column} were the first or only element of a list, the -Lisp interpreter would attempt to find the function definition -attached to it. But @code{fill-column} has no function definition. -Try evaluating this: - -@smallexample -(fill-column) -@end smallexample - -@need 1250 -@noindent -In GNU Emacs version 22, you will create a @file{*Backtrace*} buffer -that says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function fill-column) - (fill-column) - eval((fill-column)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(Remember, to quit the debugger and make the debugger window go away, -type @kbd{q} in the @file{*Backtrace*} buffer.) - -@ignore -@need 800 -In GNU Emacs 20 and before, you will produce an error message that says: - -@smallexample -Symbol's function definition is void:@: fill-column -@end smallexample - -@noindent -(The message will go away as soon as you move the cursor or type -another key.) -@end ignore - -@node Void Variable, , Void Function, Variables -@comment node-name, next, previous, up -@subsection Error Message for a Symbol Without a Value -@cindex Symbol without value error -@cindex Error for symbol without value - -If you attempt to evaluate a symbol that does not have a value bound to -it, you will receive an error message. You can see this by -experimenting with our 2 plus 2 addition. In the following expression, -put your cursor right after the @code{+}, before the first number 2, -type @kbd{C-x C-e}: - -@smallexample -(+ 2 2) -@end smallexample - -@need 1500 -@noindent -In GNU Emacs 22, you will create a @file{*Backtrace*} buffer that -says: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-variable +) - eval(+) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(As with the other times we entered the debugger, you can quit by -typing @kbd{q} in the @file{*Backtrace*} buffer.) - -This backtrace is different from the very first error message we saw, -which said, @samp{Debugger entered--Lisp error: (void-function this)}. -In this case, the function does not have a value as a variable; while -in the other error message, the function (the word `this') did not -have a definition. - -In this experiment with the @code{+}, what we did was cause the Lisp -interpreter to evaluate the @code{+} and look for the value of the -variable instead of the function definition. We did this by placing the -cursor right after the symbol rather than after the parenthesis of the -enclosing list as we did before. As a consequence, the Lisp interpreter -evaluated the preceding s-expression, which in this case was the -@code{+} by itself. - -Since @code{+} does not have a value bound to it, just the function -definition, the error message reported that the symbol's value as a -variable was void. - -@ignore -@need 800 -In GNU Emacs version 20 and before, your error message will say: - -@example -Symbol's value as variable is void:@: + -@end example - -@noindent -The meaning is the same as in GNU Emacs 22. -@end ignore - -@node Arguments, set & setq, Variables, List Processing -@comment node-name, next, previous, up -@section Arguments -@cindex Arguments -@cindex Passing information to functions - -To see how information is passed to functions, let's look again at -our old standby, the addition of two plus two. In Lisp, this is written -as follows: - -@smallexample -(+ 2 2) -@end smallexample - -If you evaluate this expression, the number 4 will appear in your echo -area. What the Lisp interpreter does is add the numbers that follow -the @code{+}. - -@cindex @samp{argument} defined -The numbers added by @code{+} are called the @dfn{arguments} of the -function @code{+}. These numbers are the information that is given to -or @dfn{passed} to the function. - -The word `argument' comes from the way it is used in mathematics and -does not refer to a disputation between two people; instead it refers to -the information presented to the function, in this case, to the -@code{+}. In Lisp, the arguments to a function are the atoms or lists -that follow the function. The values returned by the evaluation of -these atoms or lists are passed to the function. Different functions -require different numbers of arguments; some functions require none at -all.@footnote{It is curious to track the path by which the word `argument' -came to have two different meanings, one in mathematics and the other in -everyday English. According to the @cite{Oxford English Dictionary}, -the word derives from the Latin for @samp{to make clear, prove}; thus it -came to mean, by one thread of derivation, `the evidence offered as -proof', which is to say, `the information offered', which led to its -meaning in Lisp. But in the other thread of derivation, it came to mean -`to assert in a manner against which others may make counter -assertions', which led to the meaning of the word as a disputation. -(Note here that the English word has two different definitions attached -to it at the same time. By contrast, in Emacs Lisp, a symbol cannot -have two different function definitions at the same time.)} - -@menu -* Data types:: Types of data passed to a function. -* Args as Variable or List:: An argument can be the value - of a variable or list. -* Variable Number of Arguments:: Some functions may take a - variable number of arguments. -* Wrong Type of Argument:: Passing an argument of the wrong type - to a function. -* message:: A useful function for sending messages. -@end menu - -@node Data types, Args as Variable or List, Arguments, Arguments -@comment node-name, next, previous, up -@subsection Arguments' Data Types -@cindex Data types -@cindex Types of data -@cindex Arguments' data types - -The type of data that should be passed to a function depends on what -kind of information it uses. The arguments to a function such as -@code{+} must have values that are numbers, since @code{+} adds numbers. -Other functions use different kinds of data for their arguments. - -@need 1250 -@findex concat -For example, the @code{concat} function links together or unites two or -more strings of text to produce a string. The arguments are strings. -Concatenating the two character strings @code{abc}, @code{def} produces -the single string @code{abcdef}. This can be seen by evaluating the -following: - -@smallexample -(concat "abc" "def") -@end smallexample - -@noindent -The value produced by evaluating this expression is @code{"abcdef"}. - -A function such as @code{substring} uses both a string and numbers as -arguments. The function returns a part of the string, a substring of -the first argument. This function takes three arguments. Its first -argument is the string of characters, the second and third arguments are -numbers that indicate the beginning and end of the substring. The -numbers are a count of the number of characters (including spaces and -punctuations) from the beginning of the string. - -@need 800 -For example, if you evaluate the following: - -@smallexample -(substring "The quick brown fox jumped." 16 19) -@end smallexample - -@noindent -you will see @code{"fox"} appear in the echo area. The arguments are the -string and the two numbers. - -Note that the string passed to @code{substring} is a single atom even -though it is made up of several words separated by spaces. Lisp counts -everything between the two quotation marks as part of the string, -including the spaces. You can think of the @code{substring} function as -a kind of `atom smasher' since it takes an otherwise indivisible atom -and extracts a part. However, @code{substring} is only able to extract -a substring from an argument that is a string, not from another type of -atom such as a number or symbol. - -@node Args as Variable or List, Variable Number of Arguments, Data types, Arguments -@comment node-name, next, previous, up -@subsection An Argument as the Value of a Variable or List - -An argument can be a symbol that returns a value when it is evaluated. -For example, when the symbol @code{fill-column} by itself is evaluated, -it returns a number. This number can be used in an addition. - -@need 1250 -Position the cursor after the following expression and type @kbd{C-x -C-e}: - -@smallexample -(+ 2 fill-column) -@end smallexample - -@noindent -The value will be a number two more than what you get by evaluating -@code{fill-column} alone. For me, this is 74, because my value of -@code{fill-column} is 72. - -As we have just seen, an argument can be a symbol that returns a value -when evaluated. In addition, an argument can be a list that returns a -value when it is evaluated. For example, in the following expression, -the arguments to the function @code{concat} are the strings -@w{@code{"The "}} and @w{@code{" red foxes."}} and the list -@code{(number-to-string (+ 2 fill-column))}. - -@c For GNU Emacs 22, need number-to-string -@smallexample -(concat "The " (number-to-string (+ 2 fill-column)) " red foxes.") -@end smallexample - -@noindent -If you evaluate this expression---and if, as with my Emacs, -@code{fill-column} evaluates to 72---@code{"The 74 red foxes."} will -appear in the echo area. (Note that you must put spaces after the -word @samp{The} and before the word @samp{red} so they will appear in -the final string. The function @code{number-to-string} converts the -integer that the addition function returns to a string. -@code{number-to-string} is also known as @code{int-to-string}.) - -@node Variable Number of Arguments, Wrong Type of Argument, Args as Variable or List, Arguments -@comment node-name, next, previous, up -@subsection Variable Number of Arguments -@cindex Variable number of arguments -@cindex Arguments, variable number of - -Some functions, such as @code{concat}, @code{+} or @code{*}, take any -number of arguments. (The @code{*} is the symbol for multiplication.) -This can be seen by evaluating each of the following expressions in -the usual way. What you will see in the echo area is printed in this -text after @samp{@result{}}, which you may read as `evaluates to'. - -@need 1250 -In the first set, the functions have no arguments: - -@smallexample -@group -(+) @result{} 0 - -(*) @result{} 1 -@end group -@end smallexample - -@need 1250 -In this set, the functions have one argument each: - -@smallexample -@group -(+ 3) @result{} 3 - -(* 3) @result{} 3 -@end group -@end smallexample - -@need 1250 -In this set, the functions have three arguments each: - -@smallexample -@group -(+ 3 4 5) @result{} 12 - -(* 3 4 5) @result{} 60 -@end group -@end smallexample - -@node Wrong Type of Argument, message, Variable Number of Arguments, Arguments -@comment node-name, next, previous, up -@subsection Using the Wrong Type Object as an Argument -@cindex Wrong type of argument -@cindex Argument, wrong type of - -When a function is passed an argument of the wrong type, the Lisp -interpreter produces an error message. For example, the @code{+} -function expects the values of its arguments to be numbers. As an -experiment we can pass it the quoted symbol @code{hello} instead of a -number. Position the cursor after the following expression and type -@kbd{C-x C-e}: - -@smallexample -(+ 2 'hello) -@end smallexample - -@noindent -When you do this you will generate an error message. What has happened -is that @code{+} has tried to add the 2 to the value returned by -@code{'hello}, but the value returned by @code{'hello} is the symbol -@code{hello}, not a number. Only numbers can be added. So @code{+} -could not carry out its addition. - -@need 1250 -In GNU Emacs version 22, you will create and enter a -@file{*Backtrace*} buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: - (wrong-type-argument number-or-marker-p hello) - +(2 hello) - eval((+ 2 (quote hello))) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1250 -As usual, the error message tries to be helpful and makes sense after you -learn how to read it.@footnote{@code{(quote hello)} is an expansion of -the abbreviation @code{'hello}.} - -The first part of the error message is straightforward; it says -@samp{wrong type argument}. Next comes the mysterious jargon word -@w{@samp{number-or-marker-p}}. This word is trying to tell you what -kind of argument the @code{+} expected. - -The symbol @code{number-or-marker-p} says that the Lisp interpreter is -trying to determine whether the information presented it (the value of -the argument) is a number or a marker (a special object representing a -buffer position). What it does is test to see whether the @code{+} is -being given numbers to add. It also tests to see whether the -argument is something called a marker, which is a specific feature of -Emacs Lisp. (In Emacs, locations in a buffer are recorded as markers. -When the mark is set with the @kbd{C-@@} or @kbd{C-@key{SPC}} command, -its position is kept as a marker. The mark can be considered a -number---the number of characters the location is from the beginning -of the buffer.) In Emacs Lisp, @code{+} can be used to add the -numeric value of marker positions as numbers. - -The @samp{p} of @code{number-or-marker-p} is the embodiment of a -practice started in the early days of Lisp programming. The @samp{p} -stands for `predicate'. In the jargon used by the early Lisp -researchers, a predicate refers to a function to determine whether some -property is true or false. So the @samp{p} tells us that -@code{number-or-marker-p} is the name of a function that determines -whether it is true or false that the argument supplied is a number or -a marker. Other Lisp symbols that end in @samp{p} include @code{zerop}, -a function that tests whether its argument has the value of zero, and -@code{listp}, a function that tests whether its argument is a list. - -Finally, the last part of the error message is the symbol @code{hello}. -This is the value of the argument that was passed to @code{+}. If the -addition had been passed the correct type of object, the value passed -would have been a number, such as 37, rather than a symbol like -@code{hello}. But then you would not have got the error message. - -@ignore -@need 1250 -In GNU Emacs version 20 and before, the echo area displays an error -message that says: - -@smallexample -Wrong type argument:@: number-or-marker-p, hello -@end smallexample - -This says, in different words, the same as the top line of the -@file{*Backtrace*} buffer. -@end ignore - -@node message, , Wrong Type of Argument, Arguments -@comment node-name, next, previous, up -@subsection The @code{message} Function -@findex message - -Like @code{+}, the @code{message} function takes a variable number of -arguments. It is used to send messages to the user and is so useful -that we will describe it here. - -@need 1250 -A message is printed in the echo area. For example, you can print a -message in your echo area by evaluating the following list: - -@smallexample -(message "This message appears in the echo area!") -@end smallexample - -The whole string between double quotation marks is a single argument -and is printed @i{in toto}. (Note that in this example, the message -itself will appear in the echo area within double quotes; that is -because you see the value returned by the @code{message} function. In -most uses of @code{message} in programs that you write, the text will -be printed in the echo area as a side-effect, without the quotes. -@xref{multiply-by-seven in detail, , @code{multiply-by-seven} in -detail}, for an example of this.) - -However, if there is a @samp{%s} in the quoted string of characters, the -@code{message} function does not print the @samp{%s} as such, but looks -to the argument that follows the string. It evaluates the second -argument and prints the value at the location in the string where the -@samp{%s} is. - -@need 1250 -You can see this by positioning the cursor after the following -expression and typing @kbd{C-x C-e}: - -@smallexample -(message "The name of this buffer is: %s." (buffer-name)) -@end smallexample - -@noindent -In Info, @code{"The name of this buffer is: *info*."} will appear in the -echo area. The function @code{buffer-name} returns the name of the -buffer as a string, which the @code{message} function inserts in place -of @code{%s}. - -To print a value as an integer, use @samp{%d} in the same way as -@samp{%s}. For example, to print a message in the echo area that -states the value of the @code{fill-column}, evaluate the following: - -@smallexample -(message "The value of fill-column is %d." fill-column) -@end smallexample - -@noindent -On my system, when I evaluate this list, @code{"The value of -fill-column is 72."} appears in my echo area@footnote{Actually, you -can use @code{%s} to print a number. It is non-specific. @code{%d} -prints only the part of a number left of a decimal point, and not -anything that is not a number.}. - -If there is more than one @samp{%s} in the quoted string, the value of -the first argument following the quoted string is printed at the -location of the first @samp{%s} and the value of the second argument is -printed at the location of the second @samp{%s}, and so on. - -@need 1250 -For example, if you evaluate the following, - -@smallexample -@group -(message "There are %d %s in the office!" - (- fill-column 14) "pink elephants") -@end group -@end smallexample - -@noindent -a rather whimsical message will appear in your echo area. On my system -it says, @code{"There are 58 pink elephants in the office!"}. - -The expression @code{(- fill-column 14)} is evaluated and the resulting -number is inserted in place of the @samp{%d}; and the string in double -quotes, @code{"pink elephants"}, is treated as a single argument and -inserted in place of the @samp{%s}. (That is to say, a string between -double quotes evaluates to itself, like a number.) - -Finally, here is a somewhat complex example that not only illustrates -the computation of a number, but also shows how you can use an -expression within an expression to generate the text that is substituted -for @samp{%s}: - -@smallexample -@group -(message "He saw %d %s" - (- fill-column 32) - (concat "red " - (substring - "The quick brown foxes jumped." 16 21) - " leaping.")) -@end group -@end smallexample - -In this example, @code{message} has three arguments: the string, -@code{"He saw %d %s"}, the expression, @code{(- fill-column 32)}, and -the expression beginning with the function @code{concat}. The value -resulting from the evaluation of @code{(- fill-column 32)} is inserted -in place of the @samp{%d}; and the value returned by the expression -beginning with @code{concat} is inserted in place of the @samp{%s}. - -When your fill column is 70 and you evaluate the expression, the -message @code{"He saw 38 red foxes leaping."} appears in your echo -area. - -@node set & setq, Summary, Arguments, List Processing -@comment node-name, next, previous, up -@section Setting the Value of a Variable -@cindex Variable, setting value -@cindex Setting value of variable - -@cindex @samp{bind} defined -There are several ways by which a variable can be given a value. One of -the ways is to use either the function @code{set} or the function -@code{setq}. Another way is to use @code{let} (@pxref{let}). (The -jargon for this process is to @dfn{bind} a variable to a value.) - -The following sections not only describe how @code{set} and @code{setq} -work but also illustrate how arguments are passed. - -@menu -* Using set:: Setting values. -* Using setq:: Setting a quoted value. -* Counting:: Using @code{setq} to count. -@end menu - -@node Using set, Using setq, set & setq, set & setq -@comment node-name, next, previous, up -@subsection Using @code{set} -@findex set - -To set the value of the symbol @code{flowers} to the list @code{'(rose -violet daisy buttercup)}, evaluate the following expression by -positioning the cursor after the expression and typing @kbd{C-x C-e}. - -@smallexample -(set 'flowers '(rose violet daisy buttercup)) -@end smallexample - -@noindent -The list @code{(rose violet daisy buttercup)} will appear in the echo -area. This is what is @emph{returned} by the @code{set} function. As a -side effect, the symbol @code{flowers} is bound to the list; that is, -the symbol @code{flowers}, which can be viewed as a variable, is given -the list as its value. (This process, by the way, illustrates how a -side effect to the Lisp interpreter, setting the value, can be the -primary effect that we humans are interested in. This is because every -Lisp function must return a value if it does not get an error, but it -will only have a side effect if it is designed to have one.) - -After evaluating the @code{set} expression, you can evaluate the symbol -@code{flowers} and it will return the value you just set. Here is the -symbol. Place your cursor after it and type @kbd{C-x C-e}. - -@smallexample -flowers -@end smallexample - -@noindent -When you evaluate @code{flowers}, the list -@code{(rose violet daisy buttercup)} appears in the echo area. - -Incidentally, if you evaluate @code{'flowers}, the variable with a quote -in front of it, what you will see in the echo area is the symbol itself, -@code{flowers}. Here is the quoted symbol, so you can try this: - -@smallexample -'flowers -@end smallexample - -Note also, that when you use @code{set}, you need to quote both -arguments to @code{set}, unless you want them evaluated. Since we do -not want either argument evaluated, neither the variable -@code{flowers} nor the list @code{(rose violet daisy buttercup)}, both -are quoted. (When you use @code{set} without quoting its first -argument, the first argument is evaluated before anything else is -done. If you did this and @code{flowers} did not have a value -already, you would get an error message that the @samp{Symbol's value -as variable is void}; on the other hand, if @code{flowers} did return -a value after it was evaluated, the @code{set} would attempt to set -the value that was returned. There are situations where this is the -right thing for the function to do; but such situations are rare.) - -@node Using setq, Counting, Using set, set & setq -@comment node-name, next, previous, up -@subsection Using @code{setq} -@findex setq - -As a practical matter, you almost always quote the first argument to -@code{set}. The combination of @code{set} and a quoted first argument -is so common that it has its own name: the special form @code{setq}. -This special form is just like @code{set} except that the first argument -is quoted automatically, so you don't need to type the quote mark -yourself. Also, as an added convenience, @code{setq} permits you to set -several different variables to different values, all in one expression. - -To set the value of the variable @code{carnivores} to the list -@code{'(lion tiger leopard)} using @code{setq}, the following expression -is used: - -@smallexample -(setq carnivores '(lion tiger leopard)) -@end smallexample - -@noindent -This is exactly the same as using @code{set} except the first argument -is automatically quoted by @code{setq}. (The @samp{q} in @code{setq} -means @code{quote}.) - -@need 1250 -With @code{set}, the expression would look like this: - -@smallexample -(set 'carnivores '(lion tiger leopard)) -@end smallexample - -Also, @code{setq} can be used to assign different values to -different variables. The first argument is bound to the value -of the second argument, the third argument is bound to the value of the -fourth argument, and so on. For example, you could use the following to -assign a list of trees to the symbol @code{trees} and a list of herbivores -to the symbol @code{herbivores}: - -@smallexample -@group -(setq trees '(pine fir oak maple) - herbivores '(gazelle antelope zebra)) -@end group -@end smallexample - -@noindent -(The expression could just as well have been on one line, but it might -not have fit on a page; and humans find it easier to read nicely -formatted lists.) - -Although I have been using the term `assign', there is another way of -thinking about the workings of @code{set} and @code{setq}; and that is to -say that @code{set} and @code{setq} make the symbol @emph{point} to the -list. This latter way of thinking is very common and in forthcoming -chapters we shall come upon at least one symbol that has `pointer' as -part of its name. The name is chosen because the symbol has a value, -specifically a list, attached to it; or, expressed another way, -the symbol is set to ``point'' to the list. - -@node Counting, , Using setq, set & setq -@comment node-name, next, previous, up -@subsection Counting -@cindex Counting - -Here is an example that shows how to use @code{setq} in a counter. You -might use this to count how many times a part of your program repeats -itself. First set a variable to zero; then add one to the number each -time the program repeats itself. To do this, you need a variable that -serves as a counter, and two expressions: an initial @code{setq} -expression that sets the counter variable to zero; and a second -@code{setq} expression that increments the counter each time it is -evaluated. - -@smallexample -@group -(setq counter 0) ; @r{Let's call this the initializer.} - -(setq counter (+ counter 1)) ; @r{This is the incrementer.} - -counter ; @r{This is the counter.} -@end group -@end smallexample - -@noindent -(The text following the @samp{;} are comments. @xref{Change a -defun, , Change a Function Definition}.) - -If you evaluate the first of these expressions, the initializer, -@code{(setq counter 0)}, and then evaluate the third expression, -@code{counter}, the number @code{0} will appear in the echo area. If -you then evaluate the second expression, the incrementer, @code{(setq -counter (+ counter 1))}, the counter will get the value 1. So if you -again evaluate @code{counter}, the number @code{1} will appear in the -echo area. Each time you evaluate the second expression, the value of -the counter will be incremented. - -When you evaluate the incrementer, @code{(setq counter (+ counter 1))}, -the Lisp interpreter first evaluates the innermost list; this is the -addition. In order to evaluate this list, it must evaluate the variable -@code{counter} and the number @code{1}. When it evaluates the variable -@code{counter}, it receives its current value. It passes this value and -the number @code{1} to the @code{+} which adds them together. The sum -is then returned as the value of the inner list and passed to the -@code{setq} which sets the variable @code{counter} to this new value. -Thus, the value of the variable, @code{counter}, is changed. - -@node Summary, Error Message Exercises, set & setq, List Processing -@comment node-name, next, previous, up -@section Summary - -Learning Lisp is like climbing a hill in which the first part is the -steepest. You have now climbed the most difficult part; what remains -becomes easier as you progress onwards. - -@need 1000 -In summary, - -@itemize @bullet - -@item -Lisp programs are made up of expressions, which are lists or single atoms. - -@item -Lists are made up of zero or more atoms or inner lists, separated by whitespace and -surrounded by parentheses. A list can be empty. - -@item -Atoms are multi-character symbols, like @code{forward-paragraph}, single -character symbols like @code{+}, strings of characters between double -quotation marks, or numbers. - -@item -A number evaluates to itself. - -@item -A string between double quotes also evaluates to itself. - -@item -When you evaluate a symbol by itself, its value is returned. - -@item -When you evaluate a list, the Lisp interpreter looks at the first symbol -in the list and then at the function definition bound to that symbol. -Then the instructions in the function definition are carried out. - -@item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should -return the following expression as written, and not evaluate it as it -would if the quote were not there. - -@item -Arguments are the information passed to a function. The arguments to a -function are computed by evaluating the rest of the elements of the list -of which the function is the first element. - -@item -A function always returns a value when it is evaluated (unless it gets -an error); in addition, it may also carry out some action called a -``side effect''. In many cases, a function's primary purpose is to -create a side effect. -@end itemize - -@node Error Message Exercises, , Summary, List Processing -@comment node-name, next, previous, up -@section Exercises - -A few simple exercises: - -@itemize @bullet -@item -Generate an error message by evaluating an appropriate symbol that is -not within parentheses. - -@item -Generate an error message by evaluating an appropriate symbol that is -between parentheses. - -@item -Create a counter that increments by two rather than one. - -@item -Write an expression that prints a message in the echo area when -evaluated. -@end itemize - -@node Practicing Evaluation, Writing Defuns, List Processing, Top -@comment node-name, next, previous, up -@chapter Practicing Evaluation -@cindex Practicing evaluation -@cindex Evaluation practice - -Before learning how to write a function definition in Emacs Lisp, it is -useful to spend a little time evaluating various expressions that have -already been written. These expressions will be lists with the -functions as their first (and often only) element. Since some of the -functions associated with buffers are both simple and interesting, we -will start with those. In this section, we will evaluate a few of -these. In another section, we will study the code of several other -buffer-related functions, to see how they were written. - -@menu -* How to Evaluate:: Typing editing commands or @kbd{C-x C-e} - causes evaluation. -* Buffer Names:: Buffers and files are different. -* Getting Buffers:: Getting a buffer itself, not merely its name. -* Switching Buffers:: How to change to another buffer. -* Buffer Size & Locations:: Where point is located and the size of - the buffer. -* Evaluation Exercise:: -@end menu - -@node How to Evaluate, Buffer Names, Practicing Evaluation, Practicing Evaluation -@ifnottex -@unnumberedsec How to Evaluate -@end ifnottex - -@i{Whenever you give an editing command} to Emacs Lisp, such as the -command to move the cursor or to scroll the screen, @i{you are evaluating -an expression,} the first element of which is a function. @i{This is -how Emacs works.} - -@cindex @samp{interactive function} defined -@cindex @samp{command} defined -When you type keys, you cause the Lisp interpreter to evaluate an -expression and that is how you get your results. Even typing plain text -involves evaluating an Emacs Lisp function, in this case, one that uses -@code{self-insert-command}, which simply inserts the character you -typed. The functions you evaluate by typing keystrokes are called -@dfn{interactive} functions, or @dfn{commands}; how you make a function -interactive will be illustrated in the chapter on how to write function -definitions. @xref{Interactive, , Making a Function Interactive}. - -In addition to typing keyboard commands, we have seen a second way to -evaluate an expression: by positioning the cursor after a list and -typing @kbd{C-x C-e}. This is what we will do in the rest of this -section. There are other ways to evaluate an expression as well; these -will be described as we come to them. - -Besides being used for practicing evaluation, the functions shown in the -next few sections are important in their own right. A study of these -functions makes clear the distinction between buffers and files, how to -switch to a buffer, and how to determine a location within it. - -@node Buffer Names, Getting Buffers, How to Evaluate, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Names -@findex buffer-name -@findex buffer-file-name - -The two functions, @code{buffer-name} and @code{buffer-file-name}, show -the difference between a file and a buffer. When you evaluate the -following expression, @code{(buffer-name)}, the name of the buffer -appears in the echo area. When you evaluate @code{(buffer-file-name)}, -the name of the file to which the buffer refers appears in the echo -area. Usually, the name returned by @code{(buffer-name)} is the same as -the name of the file to which it refers, and the name returned by -@code{(buffer-file-name)} is the full path-name of the file. - -A file and a buffer are two different entities. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; we say -the buffer is @dfn{visiting} that file. This copy is what you work on -and modify. Changes to the buffer do not change the file, until you -save the buffer. When you save the buffer, the buffer is copied to the file -and is thus saved permanently. - -@need 1250 -If you are reading this in Info inside of GNU Emacs, you can evaluate -each of the following expressions by positioning the cursor after it and -typing @kbd{C-x C-e}. - -@example -@group -(buffer-name) - -(buffer-file-name) -@end group -@end example - -@noindent -When I do this in Info, the value returned by evaluating -@code{(buffer-name)} is @file{"*info*"}, and the value returned by -evaluating @code{(buffer-file-name)} is @file{nil}. - -On the other hand, while I am writing this document, the value -returned by evaluating @code{(buffer-name)} is -@file{"introduction.texinfo"}, and the value returned by evaluating -@code{(buffer-file-name)} is -@file{"/gnu/work/intro/introduction.texinfo"}. - -@cindex @code{nil}, history of word -The former is the name of the buffer and the latter is the name of the -file. In Info, the buffer name is @file{"*info*"}. Info does not -point to any file, so the result of evaluating -@code{(buffer-file-name)} is @file{nil}. The symbol @code{nil} is -from the Latin word for `nothing'; in this case, it means that the -buffer is not associated with any file. (In Lisp, @code{nil} is also -used to mean `false' and is a synonym for the empty list, @code{()}.) - -When I am writing, the name of my buffer is -@file{"introduction.texinfo"}. The name of the file to which it -points is @file{"/gnu/work/intro/introduction.texinfo"}. - -(In the expressions, the parentheses tell the Lisp interpreter to -treat @w{@code{buffer-name}} and @w{@code{buffer-file-name}} as -functions; without the parentheses, the interpreter would attempt to -evaluate the symbols as variables. @xref{Variables}.) - -In spite of the distinction between files and buffers, you will often -find that people refer to a file when they mean a buffer and vice-verse. -Indeed, most people say, ``I am editing a file,'' rather than saying, -``I am editing a buffer which I will soon save to a file.'' It is -almost always clear from context what people mean. When dealing with -computer programs, however, it is important to keep the distinction in mind, -since the computer is not as smart as a person. - -@cindex Buffer, history of word -The word `buffer', by the way, comes from the meaning of the word as a -cushion that deadens the force of a collision. In early computers, a -buffer cushioned the interaction between files and the computer's -central processing unit. The drums or tapes that held a file and the -central processing unit were pieces of equipment that were very -different from each other, working at their own speeds, in spurts. The -buffer made it possible for them to work together effectively. -Eventually, the buffer grew from being an intermediary, a temporary -holding place, to being the place where work is done. This -transformation is rather like that of a small seaport that grew into a -great city: once it was merely the place where cargo was warehoused -temporarily before being loaded onto ships; then it became a business -and cultural center in its own right. - -Not all buffers are associated with files. For example, a -@file{*scratch*} buffer does not visit any file. Similarly, a -@file{*Help*} buffer is not associated with any file. - -In the old days, when you lacked a @file{~/.emacs} file and started an -Emacs session by typing the command @code{emacs} alone, without naming -any files, Emacs started with the @file{*scratch*} buffer visible. -Nowadays, you will see a splash screen. You can follow one of the -commands suggested on the splash screen, visit a file, or press the -spacebar to reach the @file{*scratch*} buffer. - -If you switch to the @file{*scratch*} buffer, type -@code{(buffer-name)}, position the cursor after it, and then type -@kbd{C-x C-e} to evaluate the expression. The name @code{"*scratch*"} -will be returned and will appear in the echo area. @code{"*scratch*"} -is the name of the buffer. When you type @code{(buffer-file-name)} in -the @file{*scratch*} buffer and evaluate that, @code{nil} will appear -in the echo area, just as it does when you evaluate -@code{(buffer-file-name)} in Info. - -Incidentally, if you are in the @file{*scratch*} buffer and want the -value returned by an expression to appear in the @file{*scratch*} -buffer itself rather than in the echo area, type @kbd{C-u C-x C-e} -instead of @kbd{C-x C-e}. This causes the value returned to appear -after the expression. The buffer will look like this: - -@smallexample -(buffer-name)"*scratch*" -@end smallexample - -@noindent -You cannot do this in Info since Info is read-only and it will not allow -you to change the contents of the buffer. But you can do this in any -buffer you can edit; and when you write code or documentation (such as -this book), this feature is very useful. - -@node Getting Buffers, Switching Buffers, Buffer Names, Practicing Evaluation -@comment node-name, next, previous, up -@section Getting Buffers -@findex current-buffer -@findex other-buffer -@cindex Getting a buffer - -The @code{buffer-name} function returns the @emph{name} of the buffer; -to get the buffer @emph{itself}, a different function is needed: the -@code{current-buffer} function. If you use this function in code, what -you get is the buffer itself. - -A name and the object or entity to which the name refers are different -from each other. You are not your name. You are a person to whom -others refer by name. If you ask to speak to George and someone hands you -a card with the letters @samp{G}, @samp{e}, @samp{o}, @samp{r}, -@samp{g}, and @samp{e} written on it, you might be amused, but you would -not be satisfied. You do not want to speak to the name, but to the -person to whom the name refers. A buffer is similar: the name of the -scratch buffer is @file{*scratch*}, but the name is not the buffer. To -get a buffer itself, you need to use a function such as -@code{current-buffer}. - -However, there is a slight complication: if you evaluate -@code{current-buffer} in an expression on its own, as we will do here, -what you see is a printed representation of the name of the buffer -without the contents of the buffer. Emacs works this way for two -reasons: the buffer may be thousands of lines long---too long to be -conveniently displayed; and, another buffer may have the same contents -but a different name, and it is important to distinguish between them. - -@need 800 -Here is an expression containing the function: - -@smallexample -(current-buffer) -@end smallexample - -@noindent -If you evaluate this expression in Info in Emacs in the usual way, -@file{#} will appear in the echo area. The special -format indicates that the buffer itself is being returned, rather than -just its name. - -Incidentally, while you can type a number or symbol into a program, you -cannot do that with the printed representation of a buffer: the only way -to get a buffer itself is with a function such as @code{current-buffer}. - -A related function is @code{other-buffer}. This returns the most -recently selected buffer other than the one you are in currently, not -a printed representation of its name. If you have recently switched -back and forth from the @file{*scratch*} buffer, @code{other-buffer} -will return that buffer. - -@need 800 -You can see this by evaluating the expression: - -@smallexample -(other-buffer) -@end smallexample - -@noindent -You should see @file{#} appear in the echo area, or -the name of whatever other buffer you switched back from most -recently@footnote{Actually, by default, if the buffer from which you -just switched is visible to you in another window, @code{other-buffer} -will choose the most recent buffer that you cannot see; this is a -subtlety that I often forget.}. - -@node Switching Buffers, Buffer Size & Locations, Getting Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Switching Buffers -@findex switch-to-buffer -@findex set-buffer -@cindex Switching to a buffer - -The @code{other-buffer} function actually provides a buffer when it is -used as an argument to a function that requires one. We can see this -by using @code{other-buffer} and @code{switch-to-buffer} to switch to a -different buffer. - -But first, a brief introduction to the @code{switch-to-buffer} -function. When you switched back and forth from Info to the -@file{*scratch*} buffer to evaluate @code{(buffer-name)}, you most -likely typed @kbd{C-x b} and then typed @file{*scratch*}@footnote{Or -rather, to save typing, you probably only typed @kbd{RET} if the -default buffer was @file{*scratch*}, or if it was different, then you -typed just part of the name, such as @code{*sc}, pressed your -@kbd{TAB} key to cause it to expand to the full name, and then typed -your @kbd{RET} key.} when prompted in the minibuffer for the name of -the buffer to which you wanted to switch. The keystrokes, @kbd{C-x -b}, cause the Lisp interpreter to evaluate the interactive function -@code{switch-to-buffer}. As we said before, this is how Emacs works: -different keystrokes call or run different functions. For example, -@kbd{C-f} calls @code{forward-char}, @kbd{M-e} calls -@code{forward-sentence}, and so on. - -By writing @code{switch-to-buffer} in an expression, and giving it a -buffer to switch to, we can switch buffers just the way @kbd{C-x b} -does. - -@need 1000 -Here is the Lisp expression: - -@smallexample -(switch-to-buffer (other-buffer)) -@end smallexample - -@noindent -The symbol @code{switch-to-buffer} is the first element of the list, -so the Lisp interpreter will treat it as a function and carry out the -instructions that are attached to it. But before doing that, the -interpreter will note that @code{other-buffer} is inside parentheses -and work on that symbol first. @code{other-buffer} is the first (and -in this case, the only) element of this list, so the Lisp interpreter -calls or runs the function. It returns another buffer. Next, the -interpreter runs @code{switch-to-buffer}, passing to it, as an -argument, the other buffer, which is what Emacs will switch to. If -you are reading this in Info, try this now. Evaluate the expression. -(To get back, type @kbd{C-x b @key{RET}}.)@footnote{Remember, this -expression will move you to your most recent other buffer that you -cannot see. If you really want to go to your most recently selected -buffer, even if you can still see it, you need to evaluate the -following more complex expression: - -@smallexample -(switch-to-buffer (other-buffer (current-buffer) t)) -@end smallexample - -@c noindent -In this case, the first argument to @code{other-buffer} tells it which -buffer to skip---the current one---and the second argument tells -@code{other-buffer} it is OK to switch to a visible buffer. -In regular use, @code{switch-to-buffer} takes you to an invisible -window since you would most likely use @kbd{C-x o} (@code{other-window}) -to go to another visible buffer.} - -In the programming examples in later sections of this document, you will -see the function @code{set-buffer} more often than -@code{switch-to-buffer}. This is because of a difference between -computer programs and humans: humans have eyes and expect to see the -buffer on which they are working on their computer terminals. This is -so obvious, it almost goes without saying. However, programs do not -have eyes. When a computer program works on a buffer, that buffer does -not need to be visible on the screen. - -@code{switch-to-buffer} is designed for humans and does two different -things: it switches the buffer to which Emacs' attention is directed; and -it switches the buffer displayed in the window to the new buffer. -@code{set-buffer}, on the other hand, does only one thing: it switches -the attention of the computer program to a different buffer. The buffer -on the screen remains unchanged (of course, normally nothing happens -there until the command finishes running). - -@cindex @samp{call} defined -Also, we have just introduced another jargon term, the word @dfn{call}. -When you evaluate a list in which the first symbol is a function, you -are calling that function. The use of the term comes from the notion of -the function as an entity that can do something for you if you `call' -it---just as a plumber is an entity who can fix a leak if you call him -or her. - -@node Buffer Size & Locations, Evaluation Exercise, Switching Buffers, Practicing Evaluation -@comment node-name, next, previous, up -@section Buffer Size and the Location of Point -@cindex Size of buffer -@cindex Buffer size -@cindex Point location -@cindex Location of point - -Finally, let's look at several rather simple functions, -@code{buffer-size}, @code{point}, @code{point-min}, and -@code{point-max}. These give information about the size of a buffer and -the location of point within it. - -The function @code{buffer-size} tells you the size of the current -buffer; that is, the function returns a count of the number of -characters in the buffer. - -@smallexample -(buffer-size) -@end smallexample - -@noindent -You can evaluate this in the usual way, by positioning the -cursor after the expression and typing @kbd{C-x C-e}. - -@cindex @samp{point} defined -In Emacs, the current position of the cursor is called @dfn{point}. -The expression @code{(point)} returns a number that tells you where the -cursor is located as a count of the number of characters from the -beginning of the buffer up to point. - -@need 1250 -You can see the character count for point in this buffer by evaluating -the following expression in the usual way: - -@smallexample -(point) -@end smallexample - -@noindent -As I write this, the value of @code{point} is 65724. The @code{point} -function is frequently used in some of the examples later in this -book. - -@need 1250 -The value of point depends, of course, on its location within the -buffer. If you evaluate point in this spot, the number will be larger: - -@smallexample -(point) -@end smallexample - -@noindent -For me, the value of point in this location is 66043, which means that -there are 319 characters (including spaces) between the two -expressions. (Doubtless, you will see different numbers, since I will -have edited this since I first evaluated point.) - -@cindex @samp{narrowing} defined -The function @code{point-min} is somewhat similar to @code{point}, but -it returns the value of the minimum permissible value of point in the -current buffer. This is the number 1 unless @dfn{narrowing} is in -effect. (Narrowing is a mechanism whereby you can restrict yourself, -or a program, to operations on just a part of a buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}.) Likewise, the -function @code{point-max} returns the value of the maximum permissible -value of point in the current buffer. - -@node Evaluation Exercise, , Buffer Size & Locations, Practicing Evaluation -@section Exercise - -Find a file with which you are working and move towards its middle. -Find its buffer name, file name, length, and your position in the file. - -@node Writing Defuns, Buffer Walk Through, Practicing Evaluation, Top -@comment node-name, next, previous, up -@chapter How To Write Function Definitions -@cindex Definition writing -@cindex Function definition writing -@cindex Writing a function definition - -When the Lisp interpreter evaluates a list, it looks to see whether the -first symbol on the list has a function definition attached to it; or, -put another way, whether the symbol points to a function definition. If -it does, the computer carries out the instructions in the definition. A -symbol that has a function definition is called, simply, a function -(although, properly speaking, the definition is the function and the -symbol refers to it.) - -@menu -* Primitive Functions:: -* defun:: The @code{defun} special form. -* Install:: Install a function definition. -* Interactive:: Making a function interactive. -* Interactive Options:: Different options for @code{interactive}. -* Permanent Installation:: Installing code permanently. -* let:: Creating and initializing local variables. -* if:: What if? -* else:: If--then--else expressions. -* Truth & Falsehood:: What Lisp considers false and true. -* save-excursion:: Keeping track of point, mark, and buffer. -* Review:: -* defun Exercises:: -@end menu - -@node Primitive Functions, defun, Writing Defuns, Writing Defuns -@ifnottex -@unnumberedsec An Aside about Primitive Functions -@end ifnottex -@cindex Primitive functions -@cindex Functions, primitive - -@cindex C language primitives -@cindex Primitives written in C -All functions are defined in terms of other functions, except for a few -@dfn{primitive} functions that are written in the C programming -language. When you write functions' definitions, you will write them in -Emacs Lisp and use other functions as your building blocks. Some of the -functions you will use will themselves be written in Emacs Lisp (perhaps -by you) and some will be primitives written in C. The primitive -functions are used exactly like those written in Emacs Lisp and behave -like them. They are written in C so we can easily run GNU Emacs on any -computer that has sufficient power and can run C. - -Let me re-emphasize this: when you write code in Emacs Lisp, you do not -distinguish between the use of functions written in C and the use of -functions written in Emacs Lisp. The difference is irrelevant. I -mention the distinction only because it is interesting to know. Indeed, -unless you investigate, you won't know whether an already-written -function is written in Emacs Lisp or C. - -@node defun, Install, Primitive Functions, Writing Defuns -@comment node-name, next, previous, up -@section The @code{defun} Special Form -@findex defun -@cindex Special form of @code{defun} - -@cindex @samp{function definition} defined -In Lisp, a symbol such as @code{mark-whole-buffer} has code attached to -it that tells the computer what to do when the function is called. -This code is called the @dfn{function definition} and is created by -evaluating a Lisp expression that starts with the symbol @code{defun} -(which is an abbreviation for @emph{define function}). Because -@code{defun} does not evaluate its arguments in the usual way, it is -called a @dfn{special form}. - -In subsequent sections, we will look at function definitions from the -Emacs source code, such as @code{mark-whole-buffer}. In this section, -we will describe a simple function definition so you can see how it -looks. This function definition uses arithmetic because it makes for a -simple example. Some people dislike examples using arithmetic; however, -if you are such a person, do not despair. Hardly any of the code we -will study in the remainder of this introduction involves arithmetic or -mathematics. The examples mostly involve text in one way or another. - -A function definition has up to five parts following the word -@code{defun}: - -@enumerate -@item -The name of the symbol to which the function definition should be -attached. - -@item -A list of the arguments that will be passed to the function. If no -arguments will be passed to the function, this is an empty list, -@code{()}. - -@item -Documentation describing the function. (Technically optional, but -strongly recommended.) - -@item -Optionally, an expression to make the function interactive so you can -use it by typing @kbd{M-x} and then the name of the function; or by -typing an appropriate key or keychord. - -@cindex @samp{body} defined -@item -The code that instructs the computer what to do: the @dfn{body} of the -function definition. -@end enumerate - -It is helpful to think of the five parts of a function definition as -being organized in a template, with slots for each part: - -@smallexample -@group -(defun @var{function-name} (@var{arguments}@dots{}) - "@var{optional-documentation}@dots{}" - (interactive @var{argument-passing-info}) ; @r{optional} - @var{body}@dots{}) -@end group -@end smallexample - -As an example, here is the code for a function that multiplies its -argument by 7. (This example is not interactive. @xref{Interactive, -, Making a Function Interactive}, for that information.) - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -This definition begins with a parenthesis and the symbol @code{defun}, -followed by the name of the function. - -@cindex @samp{argument list} defined -The name of the function is followed by a list that contains the -arguments that will be passed to the function. This list is called -the @dfn{argument list}. In this example, the list has only one -element, the symbol, @code{number}. When the function is used, the -symbol will be bound to the value that is used as the argument to the -function. - -Instead of choosing the word @code{number} for the name of the argument, -I could have picked any other name. For example, I could have chosen -the word @code{multiplicand}. I picked the word `number' because it -tells what kind of value is intended for this slot; but I could just as -well have chosen the word `multiplicand' to indicate the role that the -value placed in this slot will play in the workings of the function. I -could have called it @code{foogle}, but that would have been a bad -choice because it would not tell humans what it means. The choice of -name is up to the programmer and should be chosen to make the meaning of -the function clear. - -Indeed, you can choose any name you wish for a symbol in an argument -list, even the name of a symbol used in some other function: the name -you use in an argument list is private to that particular definition. -In that definition, the name refers to a different entity than any use -of the same name outside the function definition. Suppose you have a -nick-name `Shorty' in your family; when your family members refer to -`Shorty', they mean you. But outside your family, in a movie, for -example, the name `Shorty' refers to someone else. Because a name in an -argument list is private to the function definition, you can change the -value of such a symbol inside the body of a function without changing -its value outside the function. The effect is similar to that produced -by a @code{let} expression. (@xref{let, , @code{let}}.) - -@ignore -Note also that we discuss the word `number' in two different ways: as a -symbol that appears in the code, and as the name of something that will -be replaced by a something else during the evaluation of the function. -In the first case, @code{number} is a symbol, not a number; it happens -that within the function, it is a variable who value is the number in -question, but our primary interest in it is as a symbol. On the other -hand, when we are talking about the function, our interest is that we -will substitute a number for the word @var{number}. To keep this -distinction clear, we use different typography for the two -circumstances. When we talk about this function, or about how it works, -we refer to this number by writing @var{number}. In the function -itself, we refer to it by writing @code{number}. -@end ignore - -The argument list is followed by the documentation string that -describes the function. This is what you see when you type -@w{@kbd{C-h f}} and the name of a function. Incidentally, when you -write a documentation string like this, you should make the first line -a complete sentence since some commands, such as @code{apropos}, print -only the first line of a multi-line documentation string. Also, you -should not indent the second line of a documentation string, if you -have one, because that looks odd when you use @kbd{C-h f} -(@code{describe-function}). The documentation string is optional, but -it is so useful, it should be included in almost every function you -write. - -@findex * @r{(multiplication)} -The third line of the example consists of the body of the function -definition. (Most functions' definitions, of course, are longer than -this.) In this function, the body is the list, @code{(* 7 number)}, which -says to multiply the value of @var{number} by 7. (In Emacs Lisp, -@code{*} is the function for multiplication, just as @code{+} is the -function for addition.) - -When you use the @code{multiply-by-seven} function, the argument -@code{number} evaluates to the actual number you want used. Here is an -example that shows how @code{multiply-by-seven} is used; but don't try -to evaluate this yet! - -@smallexample -(multiply-by-seven 3) -@end smallexample - -@noindent -The symbol @code{number}, specified in the function definition in the -next section, is given or ``bound to'' the value 3 in the actual use of -the function. Note that although @code{number} was inside parentheses -in the function definition, the argument passed to the -@code{multiply-by-seven} function is not in parentheses. The -parentheses are written in the function definition so the computer can -figure out where the argument list ends and the rest of the function -definition begins. - -If you evaluate this example, you are likely to get an error message. -(Go ahead, try it!) This is because we have written the function -definition, but not yet told the computer about the definition---we have -not yet installed (or `loaded') the function definition in Emacs. -Installing a function is the process that tells the Lisp interpreter the -definition of the function. Installation is described in the next -section. - -@node Install, Interactive, defun, Writing Defuns -@comment node-name, next, previous, up -@section Install a Function Definition -@cindex Install a Function Definition -@cindex Definition installation -@cindex Function definition installation - -If you are reading this inside of Info in Emacs, you can try out the -@code{multiply-by-seven} function by first evaluating the function -definition and then evaluating @code{(multiply-by-seven 3)}. A copy of -the function definition follows. Place the cursor after the last -parenthesis of the function definition and type @kbd{C-x C-e}. When you -do this, @code{multiply-by-seven} will appear in the echo area. (What -this means is that when a function definition is evaluated, the value it -returns is the name of the defined function.) At the same time, this -action installs the function definition. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -By evaluating this @code{defun}, you have just installed -@code{multiply-by-seven} in Emacs. The function is now just as much a -part of Emacs as @code{forward-word} or any other editing function you -use. (@code{multiply-by-seven} will stay installed until you quit -Emacs. To reload code automatically whenever you start Emacs, see -@ref{Permanent Installation, , Installing Code Permanently}.) - -@menu -* Effect of installation:: -* Change a defun:: How to change a function definition. -@end menu - -@node Effect of installation, Change a defun, Install, Install -@ifnottex -@unnumberedsubsec The effect of installation -@end ifnottex - -You can see the effect of installing @code{multiply-by-seven} by -evaluating the following sample. Place the cursor after the following -expression and type @kbd{C-x C-e}. The number 21 will appear in the -echo area. - -@smallexample -(multiply-by-seven 3) -@end smallexample - -If you wish, you can read the documentation for the function by typing -@kbd{C-h f} (@code{describe-function}) and then the name of the -function, @code{multiply-by-seven}. When you do this, a -@file{*Help*} window will appear on your screen that says: - -@smallexample -@group -multiply-by-seven is a Lisp function. -(multiply-by-seven NUMBER) - -Multiply NUMBER by seven. -@end group -@end smallexample - -@noindent -(To return to a single window on your screen, type @kbd{C-x 1}.) - -@node Change a defun, , Effect of installation, Install -@comment node-name, next, previous, up -@subsection Change a Function Definition -@cindex Changing a function definition -@cindex Function definition, how to change -@cindex Definition, how to change - -If you want to change the code in @code{multiply-by-seven}, just rewrite -it. To install the new version in place of the old one, evaluate the -function definition again. This is how you modify code in Emacs. It is -very simple. - -As an example, you can change the @code{multiply-by-seven} function to -add the number to itself seven times instead of multiplying the number -by seven. It produces the same answer, but by a different path. At -the same time, we will add a comment to the code; a comment is text -that the Lisp interpreter ignores, but that a human reader may find -useful or enlightening. The comment is that this is the ``second -version''. - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Second version.} - "Multiply NUMBER by seven." - (+ number number number number number number number)) -@end group -@end smallexample - -@cindex Comments in Lisp code -The comment follows a semicolon, @samp{;}. In Lisp, everything on a -line that follows a semicolon is a comment. The end of the line is the -end of the comment. To stretch a comment over two or more lines, begin -each line with a semicolon. - -@xref{Beginning a .emacs File, , Beginning a @file{.emacs} -File}, and @ref{Comments, , Comments, elisp, The GNU Emacs Lisp -Reference Manual}, for more about comments. - -You can install this version of the @code{multiply-by-seven} function by -evaluating it in the same way you evaluated the first function: place -the cursor after the last parenthesis and type @kbd{C-x C-e}. - -In summary, this is how you write code in Emacs Lisp: you write a -function; install it; test it; and then make fixes or enhancements and -install it again. - -@node Interactive, Interactive Options, Install, Writing Defuns -@comment node-name, next, previous, up -@section Make a Function Interactive -@cindex Interactive functions -@findex interactive - -You make a function interactive by placing a list that begins with -the special form @code{interactive} immediately after the -documentation. A user can invoke an interactive function by typing -@kbd{M-x} and then the name of the function; or by typing the keys to -which it is bound, for example, by typing @kbd{C-n} for -@code{next-line} or @kbd{C-x h} for @code{mark-whole-buffer}. - -Interestingly, when you call an interactive function interactively, -the value returned is not automatically displayed in the echo area. -This is because you often call an interactive function for its side -effects, such as moving forward by a word or line, and not for the -value returned. If the returned value were displayed in the echo area -each time you typed a key, it would be very distracting. - -@menu -* Interactive multiply-by-seven:: An overview. -* multiply-by-seven in detail:: The interactive version. -@end menu - -@node Interactive multiply-by-seven, multiply-by-seven in detail, Interactive, Interactive -@ifnottex -@unnumberedsubsec An Interactive @code{multiply-by-seven}, An Overview -@end ifnottex - -Both the use of the special form @code{interactive} and one way to -display a value in the echo area can be illustrated by creating an -interactive version of @code{multiply-by-seven}. - -@need 1250 -Here is the code: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -@noindent -You can install this code by placing your cursor after it and typing -@kbd{C-x C-e}. The name of the function will appear in your echo area. -Then, you can use this code by typing @kbd{C-u} and a number and then -typing @kbd{M-x multiply-by-seven} and pressing @key{RET}. The phrase -@samp{The result is @dots{}} followed by the product will appear in the -echo area. - -Speaking more generally, you invoke a function like this in either of two -ways: - -@enumerate -@item -By typing a prefix argument that contains the number to be passed, and -then typing @kbd{M-x} and the name of the function, as with -@kbd{C-u 3 M-x forward-sentence}; or, - -@item -By typing whatever key or keychord the function is bound to, as with -@kbd{C-u 3 M-e}. -@end enumerate - -@noindent -Both the examples just mentioned work identically to move point forward -three sentences. (Since @code{multiply-by-seven} is not bound to a key, -it could not be used as an example of key binding.) - -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command -to a key.) - -A prefix argument is passed to an interactive function by typing the -@key{META} key followed by a number, for example, @kbd{M-3 M-e}, or by -typing @kbd{C-u} and then a number, for example, @kbd{C-u 3 M-e} (if you -type @kbd{C-u} without a number, it defaults to 4). - -@node multiply-by-seven in detail, , Interactive multiply-by-seven, Interactive -@comment node-name, next, previous, up -@subsection An Interactive @code{multiply-by-seven} - -Let's look at the use of the special form @code{interactive} and then at -the function @code{message} in the interactive version of -@code{multiply-by-seven}. You will recall that the function definition -looks like this: - -@smallexample -@group -(defun multiply-by-seven (number) ; @r{Interactive version.} - "Multiply NUMBER by seven." - (interactive "p") - (message "The result is %d" (* 7 number))) -@end group -@end smallexample - -In this function, the expression, @code{(interactive "p")}, is a list of -two elements. The @code{"p"} tells Emacs to pass the prefix argument to -the function and use its value for the argument of the function. - -@need 1000 -The argument will be a number. This means that the symbol -@code{number} will be bound to a number in the line: - -@smallexample -(message "The result is %d" (* 7 number)) -@end smallexample - -@need 1250 -@noindent -For example, if your prefix argument is 5, the Lisp interpreter will -evaluate the line as if it were: - -@smallexample -(message "The result is %d" (* 7 5)) -@end smallexample - -@noindent -(If you are reading this in GNU Emacs, you can evaluate this expression -yourself.) First, the interpreter will evaluate the inner list, which -is @code{(* 7 5)}. This returns a value of 35. Next, it -will evaluate the outer list, passing the values of the second and -subsequent elements of the list to the function @code{message}. - -As we have seen, @code{message} is an Emacs Lisp function especially -designed for sending a one line message to a user. (@xref{message, , -The @code{message} function}.) In summary, the @code{message} -function prints its first argument in the echo area as is, except for -occurrences of @samp{%d} or @samp{%s} (and various other %-sequences -which we have not mentioned). When it sees a control sequence, the -function looks to the second or subsequent arguments and prints the -value of the argument in the location in the string where the control -sequence is located. - -In the interactive @code{multiply-by-seven} function, the control string -is @samp{%d}, which requires a number, and the value returned by -evaluating @code{(* 7 5)} is the number 35. Consequently, the number 35 -is printed in place of the @samp{%d} and the message is @samp{The result -is 35}. - -(Note that when you call the function @code{multiply-by-seven}, the -message is printed without quotes, but when you call @code{message}, the -text is printed in double quotes. This is because the value returned by -@code{message} is what appears in the echo area when you evaluate an -expression whose first element is @code{message}; but when embedded in a -function, @code{message} prints the text as a side effect without -quotes.) - -@node Interactive Options, Permanent Installation, Interactive, Writing Defuns -@comment node-name, next, previous, up -@section Different Options for @code{interactive} -@cindex Options for @code{interactive} -@cindex Interactive options - -In the example, @code{multiply-by-seven} used @code{"p"} as the -argument to @code{interactive}. This argument told Emacs to interpret -your typing either @kbd{C-u} followed by a number or @key{META} -followed by a number as a command to pass that number to the function -as its argument. Emacs has more than twenty characters predefined for -use with @code{interactive}. In almost every case, one of these -options will enable you to pass the right information interactively to -a function. (@xref{Interactive Codes, , Code Characters for -@code{interactive}, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 1250 -Consider the function @code{zap-to-char}. Its interactive expression -is - -@smallexample -(interactive "p\ncZap to char: ") -@end smallexample - -The first part of the argument to @code{interactive} is @samp{p}, with -which you are already familiar. This argument tells Emacs to -interpret a `prefix', as a number to be passed to the function. You -can specify a prefix either by typing @kbd{C-u} followed by a number -or by typing @key{META} followed by a number. The prefix is the -number of specified characters. Thus, if your prefix is three and the -specified character is @samp{x}, then you will delete all the text up -to and including the third next @samp{x}. If you do not set a prefix, -then you delete all the text up to and including the specified -character, but no more. - -The @samp{c} tells the function the name of the character to which to delete. - -More formally, a function with two or more arguments can have -information passed to each argument by adding parts to the string that -follows @code{interactive}. When you do this, the information is -passed to each argument in the same order it is specified in the -@code{interactive} list. In the string, each part is separated from -the next part by a @samp{\n}, which is a newline. For example, you -can follow @samp{p} with a @samp{\n} and an @samp{cZap to char:@: }. -This causes Emacs to pass the value of the prefix argument (if there -is one) and the character. - -In this case, the function definition looks like the following, where -@code{arg} and @code{char} are the symbols to which @code{interactive} -binds the prefix argument and the specified character: - -@smallexample -@group -(defun @var{name-of-function} (arg char) - "@var{documentation}@dots{}" - (interactive "p\ncZap to char: ") - @var{body-of-function}@dots{}) -@end group -@end smallexample - -@noindent -(The space after the colon in the prompt makes it look better when you -are prompted. @xref{copy-to-buffer, , The Definition of -@code{copy-to-buffer}}, for an example.) - -When a function does not take arguments, @code{interactive} does not -require any. Such a function contains the simple expression -@code{(interactive)}. The @code{mark-whole-buffer} function is like -this. - -Alternatively, if the special letter-codes are not right for your -application, you can pass your own arguments to @code{interactive} as -a list. - -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}, -for an example. @xref{Using Interactive, , Using @code{Interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a more complete -explanation about this technique. - -@node Permanent Installation, let, Interactive Options, Writing Defuns -@comment node-name, next, previous, up -@section Install Code Permanently -@cindex Install code permanently -@cindex Permanent code installation -@cindex Code installation - -When you install a function definition by evaluating it, it will stay -installed until you quit Emacs. The next time you start a new session -of Emacs, the function will not be installed unless you evaluate the -function definition again. - -At some point, you may want to have code installed automatically -whenever you start a new session of Emacs. There are several ways of -doing this: - -@itemize @bullet -@item -If you have code that is just for yourself, you can put the code for the -function definition in your @file{.emacs} initialization file. When you -start Emacs, your @file{.emacs} file is automatically evaluated and all -the function definitions within it are installed. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -@item -Alternatively, you can put the function definitions that you want -installed in one or more files of their own and use the @code{load} -function to cause Emacs to evaluate and thereby install each of the -functions in the files. -@xref{Loading Files, , Loading Files}. - -@item -Thirdly, if you have code that your whole site will use, it is usual -to put it in a file called @file{site-init.el} that is loaded when -Emacs is built. This makes the code available to everyone who uses -your machine. (See the @file{INSTALL} file that is part of the Emacs -distribution.) -@end itemize - -Finally, if you have code that everyone who uses Emacs may want, you -can post it on a computer network or send a copy to the Free Software -Foundation. (When you do this, please license the code and its -documentation under a license that permits other people to run, copy, -study, modify, and redistribute the code and which protects you from -having your work taken from you.) If you send a copy of your code to -the Free Software Foundation, and properly protect yourself and -others, it may be included in the next release of Emacs. In large -part, this is how Emacs has grown over the past years, by donations. - -@node let, if, Permanent Installation, Writing Defuns -@comment node-name, next, previous, up -@section @code{let} -@findex let - -The @code{let} expression is a special form in Lisp that you will need -to use in most function definitions. - -@code{let} is used to attach or bind a symbol to a value in such a way -that the Lisp interpreter will not confuse the variable with a -variable of the same name that is not part of the function. - -To understand why the @code{let} special form is necessary, consider -the situation in which you own a home that you generally refer to as -`the house', as in the sentence, ``The house needs painting.'' If you -are visiting a friend and your host refers to `the house', he is -likely to be referring to @emph{his} house, not yours, that is, to a -different house. - -If your friend is referring to his house and you think he is referring -to your house, you may be in for some confusion. The same thing could -happen in Lisp if a variable that is used inside of one function has -the same name as a variable that is used inside of another function, -and the two are not intended to refer to the same value. The -@code{let} special form prevents this kind of confusion. - -@menu -* Prevent confusion:: -* Parts of let Expression:: -* Sample let Expression:: -* Uninitialized let Variables:: -@end menu - -@node Prevent confusion, Parts of let Expression, let, let -@ifnottex -@unnumberedsubsec @code{let} Prevents Confusion -@end ifnottex - -@cindex @samp{local variable} defined -@cindex @samp{variable, local}, defined -The @code{let} special form prevents confusion. @code{let} creates a -name for a @dfn{local variable} that overshadows any use of the same -name outside the @code{let} expression. This is like understanding -that whenever your host refers to `the house', he means his house, not -yours. (Symbols used in argument lists work the same way. -@xref{defun, , The @code{defun} Special Form}.) - -Local variables created by a @code{let} expression retain their value -@emph{only} within the @code{let} expression itself (and within -expressions called within the @code{let} expression); the local -variables have no effect outside the @code{let} expression. - -Another way to think about @code{let} is that it is like a @code{setq} -that is temporary and local. The values set by @code{let} are -automatically undone when the @code{let} is finished. The setting -only affects expressions that are inside the bounds of the @code{let} -expression. In computer science jargon, we would say ``the binding of -a symbol is visible only in functions called in the @code{let} form; -in Emacs Lisp, scoping is dynamic, not lexical.'' - -@code{let} can create more than one variable at once. Also, -@code{let} gives each variable it creates an initial value, either a -value specified by you, or @code{nil}. (In the jargon, this is called -`binding the variable to the value'.) After @code{let} has created -and bound the variables, it executes the code in the body of the -@code{let}, and returns the value of the last expression in the body, -as the value of the whole @code{let} expression. (`Execute' is a jargon -term that means to evaluate a list; it comes from the use of the word -meaning `to give practical effect to' (@cite{Oxford English -Dictionary}). Since you evaluate an expression to perform an action, -`execute' has evolved as a synonym to `evaluate'.) - -@node Parts of let Expression, Sample let Expression, Prevent confusion, let -@comment node-name, next, previous, up -@subsection The Parts of a @code{let} Expression -@cindex @code{let} expression, parts of -@cindex Parts of @code{let} expression - -@cindex @samp{varlist} defined -A @code{let} expression is a list of three parts. The first part is -the symbol @code{let}. The second part is a list, called a -@dfn{varlist}, each element of which is either a symbol by itself or a -two-element list, the first element of which is a symbol. The third -part of the @code{let} expression is the body of the @code{let}. The -body usually consists of one or more lists. - -@need 800 -A template for a @code{let} expression looks like this: - -@smallexample -(let @var{varlist} @var{body}@dots{}) -@end smallexample - -@noindent -The symbols in the varlist are the variables that are given initial -values by the @code{let} special form. Symbols by themselves are given -the initial value of @code{nil}; and each symbol that is the first -element of a two-element list is bound to the value that is returned -when the Lisp interpreter evaluates the second element. - -Thus, a varlist might look like this: @code{(thread (needles 3))}. In -this case, in a @code{let} expression, Emacs binds the symbol -@code{thread} to an initial value of @code{nil}, and binds the symbol -@code{needles} to an initial value of 3. - -When you write a @code{let} expression, what you do is put the -appropriate expressions in the slots of the @code{let} expression -template. - -If the varlist is composed of two-element lists, as is often the case, -the template for the @code{let} expression looks like this: - -@smallexample -@group -(let ((@var{variable} @var{value}) - (@var{variable} @var{value}) - @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -@node Sample let Expression, Uninitialized let Variables, Parts of let Expression, let -@comment node-name, next, previous, up -@subsection Sample @code{let} Expression -@cindex Sample @code{let} expression -@cindex @code{let} expression sample - -The following expression creates and gives initial values -to the two variables @code{zebra} and @code{tiger}. The body of the -@code{let} expression is a list which calls the @code{message} function. - -@smallexample -@group -(let ((zebra 'stripes) - (tiger 'fierce)) - (message "One kind of animal has %s and another is %s." - zebra tiger)) -@end group -@end smallexample - -Here, the varlist is @code{((zebra 'stripes) (tiger 'fierce))}. - -The two variables are @code{zebra} and @code{tiger}. Each variable is -the first element of a two-element list and each value is the second -element of its two-element list. In the varlist, Emacs binds the -variable @code{zebra} to the value @code{stripes}@footnote{According -to Jared Diamond in @cite{Guns, Germs, and Steel}, ``@dots{} zebras -become impossibly dangerous as they grow older'' but the claim here is -that they do not become fierce like a tiger. (1997, W. W. Norton and -Co., ISBN 0-393-03894-2, page 171)}, and binds the -variable @code{tiger} to the value @code{fierce}. In this example, -both values are symbols preceded by a quote. The values could just as -well have been another list or a string. The body of the @code{let} -follows after the list holding the variables. In this example, the -body is a list that uses the @code{message} function to print a string -in the echo area. - -@need 1500 -You may evaluate the example in the usual fashion, by placing the -cursor after the last parenthesis and typing @kbd{C-x C-e}. When you do -this, the following will appear in the echo area: - -@smallexample -"One kind of animal has stripes and another is fierce." -@end smallexample - -As we have seen before, the @code{message} function prints its first -argument, except for @samp{%s}. In this example, the value of the variable -@code{zebra} is printed at the location of the first @samp{%s} and the -value of the variable @code{tiger} is printed at the location of the -second @samp{%s}. - -@node Uninitialized let Variables, , Sample let Expression, let -@comment node-name, next, previous, up -@subsection Uninitialized Variables in a @code{let} Statement -@cindex Uninitialized @code{let} variables -@cindex @code{let} variables uninitialized - -If you do not bind the variables in a @code{let} statement to specific -initial values, they will automatically be bound to an initial value of -@code{nil}, as in the following expression: - -@smallexample -@group -(let ((birch 3) - pine - fir - (oak 'some)) - (message - "Here are %d variables with %s, %s, and %s value." - birch pine fir oak)) -@end group -@end smallexample - -@noindent -Here, the varlist is @code{((birch 3) pine fir (oak 'some))}. - -@need 1250 -If you evaluate this expression in the usual way, the following will -appear in your echo area: - -@smallexample -"Here are 3 variables with nil, nil, and some value." -@end smallexample - -@noindent -In this example, Emacs binds the symbol @code{birch} to the number 3, -binds the symbols @code{pine} and @code{fir} to @code{nil}, and binds -the symbol @code{oak} to the value @code{some}. - -Note that in the first part of the @code{let}, the variables @code{pine} -and @code{fir} stand alone as atoms that are not surrounded by -parentheses; this is because they are being bound to @code{nil}, the -empty list. But @code{oak} is bound to @code{some} and so is a part of -the list @code{(oak 'some)}. Similarly, @code{birch} is bound to the -number 3 and so is in a list with that number. (Since a number -evaluates to itself, the number does not need to be quoted. Also, the -number is printed in the message using a @samp{%d} rather than a -@samp{%s}.) The four variables as a group are put into a list to -delimit them from the body of the @code{let}. - -@node if, else, let, Writing Defuns -@comment node-name, next, previous, up -@section The @code{if} Special Form -@findex if -@cindex Conditional with @code{if} - -A third special form, in addition to @code{defun} and @code{let}, is the -conditional @code{if}. This form is used to instruct the computer to -make decisions. You can write function definitions without using -@code{if}, but it is used often enough, and is important enough, to be -included here. It is used, for example, in the code for the -function @code{beginning-of-buffer}. - -The basic idea behind an @code{if}, is that ``@emph{if} a test is true, -@emph{then} an expression is evaluated.'' If the test is not true, the -expression is not evaluated. For example, you might make a decision -such as, ``if it is warm and sunny, then go to the beach!'' - -@menu -* if in more detail:: -* type-of-animal in detail:: An example of an @code{if} expression. -@end menu - -@node if in more detail, type-of-animal in detail, if, if -@ifnottex -@unnumberedsubsec @code{if} in more detail -@end ifnottex - -@cindex @samp{if-part} defined -@cindex @samp{then-part} defined -An @code{if} expression written in Lisp does not use the word `then'; -the test and the action are the second and third elements of the list -whose first element is @code{if}. Nonetheless, the test part of an -@code{if} expression is often called the @dfn{if-part} and the second -argument is often called the @dfn{then-part}. - -Also, when an @code{if} expression is written, the true-or-false-test -is usually written on the same line as the symbol @code{if}, but the -action to carry out if the test is true, the ``then-part'', is written -on the second and subsequent lines. This makes the @code{if} -expression easier to read. - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-test-is-true}) -@end group -@end smallexample - -@noindent -The true-or-false-test will be an expression that -is evaluated by the Lisp interpreter. - -Here is an example that you can evaluate in the usual manner. The test -is whether the number 5 is greater than the number 4. Since it is, the -message @samp{5 is greater than 4!} will be printed. - -@smallexample -@group -(if (> 5 4) ; @r{if-part} - (message "5 is greater than 4!")) ; @r{then-part} -@end group -@end smallexample - -@noindent -(The function @code{>} tests whether its first argument is greater than -its second argument and returns true if it is.) -@findex > (greater than) - -Of course, in actual use, the test in an @code{if} expression will not -be fixed for all time as it is by the expression @code{(> 5 4)}. -Instead, at least one of the variables used in the test will be bound to -a value that is not known ahead of time. (If the value were known ahead -of time, we would not need to run the test!) - -For example, the value may be bound to an argument of a function -definition. In the following function definition, the character of the -animal is a value that is passed to the function. If the value bound to -@code{characteristic} is @code{fierce}, then the message, @samp{It's a -tiger!} will be printed; otherwise, @code{nil} will be returned. - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - (if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 1500 -@noindent -If you are reading this inside of GNU Emacs, you can evaluate the -function definition in the usual way to install it in Emacs, and then you -can evaluate the following two expressions to see the results: - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentences rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; and -when you evaluate @code{(type-of-animal 'zebra)} you will see @code{nil} -printed in the echo area. - -@node type-of-animal in detail, , if in more detail, if -@comment node-name, next, previous, up -@subsection The @code{type-of-animal} Function in Detail - -Let's look at the @code{type-of-animal} function in detail. - -The function definition for @code{type-of-animal} was written by filling -the slots of two templates, one for a function definition as a whole, and -a second for an @code{if} expression. - -@need 1250 -The template for every function that is not interactive is: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - @var{body}@dots{}) -@end group -@end smallexample - -@need 800 -The parts of the function that match this template look like this: - -@smallexample -@group -(defun type-of-animal (characteristic) - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger." - @var{body: the} @code{if} @var{expression}) -@end group -@end smallexample - -The name of function is @code{type-of-animal}; it is passed the value -of one argument. The argument list is followed by a multi-line -documentation string. The documentation string is included in the -example because it is a good habit to write documentation string for -every function definition. The body of the function definition -consists of the @code{if} expression. - -@need 800 -The template for an @code{if} expression looks like this: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true}) -@end group -@end smallexample - -@need 1250 -In the @code{type-of-animal} function, the code for the @code{if} -looks like this: - -@smallexample -@group -(if (equal characteristic 'fierce) - (message "It's a tiger!"))) -@end group -@end smallexample - -@need 800 -Here, the true-or-false-test is the expression: - -@smallexample -(equal characteristic 'fierce) -@end smallexample - -@noindent -In Lisp, @code{equal} is a function that determines whether its first -argument is equal to its second argument. The second argument is the -quoted symbol @code{'fierce} and the first argument is the value of the -symbol @code{characteristic}---in other words, the argument passed to -this function. - -In the first exercise of @code{type-of-animal}, the argument -@code{fierce} is passed to @code{type-of-animal}. Since @code{fierce} -is equal to @code{fierce}, the expression, @code{(equal characteristic -'fierce)}, returns a value of true. When this happens, the @code{if} -evaluates the second argument or then-part of the @code{if}: -@code{(message "It's tiger!")}. - -On the other hand, in the second exercise of @code{type-of-animal}, the -argument @code{zebra} is passed to @code{type-of-animal}. @code{zebra} -is not equal to @code{fierce}, so the then-part is not evaluated and -@code{nil} is returned by the @code{if} expression. - -@node else, Truth & Falsehood, if, Writing Defuns -@comment node-name, next, previous, up -@section If--then--else Expressions -@cindex Else - -An @code{if} expression may have an optional third argument, called -the @dfn{else-part}, for the case when the true-or-false-test returns -false. When this happens, the second argument or then-part of the -overall @code{if} expression is @emph{not} evaluated, but the third or -else-part @emph{is} evaluated. You might think of this as the cloudy -day alternative for the decision ``if it is warm and sunny, then go to -the beach, else read a book!''. - -The word ``else'' is not written in the Lisp code; the else-part of an -@code{if} expression comes after the then-part. In the written Lisp, the -else-part is usually written to start on a line of its own and is -indented less than the then-part: - -@smallexample -@group -(if @var{true-or-false-test} - @var{action-to-carry-out-if-the-test-returns-true} - @var{action-to-carry-out-if-the-test-returns-false}) -@end group -@end smallexample - -For example, the following @code{if} expression prints the message @samp{4 -is not greater than 5!} when you evaluate it in the usual way: - -@smallexample -@group -(if (> 4 5) ; @r{if-part} - (message "4 falsely greater than 5!") ; @r{then-part} - (message "4 is not greater than 5!")) ; @r{else-part} -@end group -@end smallexample - -@noindent -Note that the different levels of indentation make it easy to -distinguish the then-part from the else-part. (GNU Emacs has several -commands that automatically indent @code{if} expressions correctly. -@xref{Typing Lists, , GNU Emacs Helps You Type Lists}.) - -We can extend the @code{type-of-animal} function to include an -else-part by simply incorporating an additional part to the @code{if} -expression. - -@need 1500 -You can see the consequences of doing this if you evaluate the following -version of the @code{type-of-animal} function definition to install it -and then evaluate the two subsequent expressions to pass different -arguments to the function. - -@smallexample -@group -(defun type-of-animal (characteristic) ; @r{Second version.} - "Print message in echo area depending on CHARACTERISTIC. -If the CHARACTERISTIC is the symbol `fierce', -then warn of a tiger; -else say it's not fierce." - (if (equal characteristic 'fierce) - (message "It's a tiger!") - (message "It's not fierce!"))) -@end group -@end smallexample -@sp 1 - -@smallexample -@group -(type-of-animal 'fierce) - -(type-of-animal 'zebra) - -@end group -@end smallexample - -@c Following sentence rewritten to prevent overfull hbox. -@noindent -When you evaluate @code{(type-of-animal 'fierce)}, you will see the -following message printed in the echo area: @code{"It's a tiger!"}; but -when you evaluate @code{(type-of-animal 'zebra)}, you will see -@code{"It's not fierce!"}. - -(Of course, if the @var{characteristic} were @code{ferocious}, the -message @code{"It's not fierce!"} would be printed; and it would be -misleading! When you write code, you need to take into account the -possibility that some such argument will be tested by the @code{if} -and write your program accordingly.) - -@node Truth & Falsehood, save-excursion, else, Writing Defuns -@comment node-name, next, previous, up -@section Truth and Falsehood in Emacs Lisp -@cindex Truth and falsehood in Emacs Lisp -@cindex Falsehood and truth in Emacs Lisp -@findex nil - -There is an important aspect to the truth test in an @code{if} -expression. So far, we have spoken of `true' and `false' as values of -predicates as if they were new kinds of Emacs Lisp objects. In fact, -`false' is just our old friend @code{nil}. Anything else---anything -at all---is `true'. - -The expression that tests for truth is interpreted as @dfn{true} -if the result of evaluating it is a value that is not @code{nil}. In -other words, the result of the test is considered true if the value -returned is a number such as 47, a string such as @code{"hello"}, or a -symbol (other than @code{nil}) such as @code{flowers}, or a list (so -long as it is not empty), or even a buffer! - -@menu -* nil explained:: @code{nil} has two meanings. -@end menu - -@node nil explained, , Truth & Falsehood, Truth & Falsehood -@ifnottex -@unnumberedsubsec An explanation of @code{nil} -@end ifnottex - -Before illustrating a test for truth, we need an explanation of @code{nil}. - -In Emacs Lisp, the symbol @code{nil} has two meanings. First, it means the -empty list. Second, it means false and is the value returned when a -true-or-false-test tests false. @code{nil} can be written as an empty -list, @code{()}, or as @code{nil}. As far as the Lisp interpreter is -concerned, @code{()} and @code{nil} are the same. Humans, however, tend -to use @code{nil} for false and @code{()} for the empty list. - -In Emacs Lisp, any value that is not @code{nil}---is not the empty -list---is considered true. This means that if an evaluation returns -something that is not an empty list, an @code{if} expression will test -true. For example, if a number is put in the slot for the test, it -will be evaluated and will return itself, since that is what numbers -do when evaluated. In this conditional, the @code{if} expression will -test true. The expression tests false only when @code{nil}, an empty -list, is returned by evaluating the expression. - -You can see this by evaluating the two expressions in the following examples. - -In the first example, the number 4 is evaluated as the test in the -@code{if} expression and returns itself; consequently, the then-part -of the expression is evaluated and returned: @samp{true} appears in -the echo area. In the second example, the @code{nil} indicates false; -consequently, the else-part of the expression is evaluated and -returned: @samp{false} appears in the echo area. - -@smallexample -@group -(if 4 - 'true - 'false) -@end group - -@group -(if nil - 'true - 'false) -@end group -@end smallexample - -@need 1250 -Incidentally, if some other useful value is not available for a test that -returns true, then the Lisp interpreter will return the symbol @code{t} -for true. For example, the expression @code{(> 5 4)} returns @code{t} -when evaluated, as you can see by evaluating it in the usual way: - -@smallexample -(> 5 4) -@end smallexample - -@need 1250 -@noindent -On the other hand, this function returns @code{nil} if the test is false. - -@smallexample -(> 4 5) -@end smallexample - -@node save-excursion, Review, Truth & Falsehood, Writing Defuns -@comment node-name, next, previous, up -@section @code{save-excursion} -@findex save-excursion -@cindex Region, what it is -@cindex Preserving point, mark, and buffer -@cindex Point, mark, buffer preservation -@findex point -@findex mark - -The @code{save-excursion} function is the fourth and final special form -that we will discuss in this chapter. - -In Emacs Lisp programs used for editing, the @code{save-excursion} -function is very common. It saves the location of point and mark, -executes the body of the function, and then restores point and mark to -their previous positions if their locations were changed. Its primary -purpose is to keep the user from being surprised and disturbed by -unexpected movement of point or mark. - -@menu -* Point and mark:: A review of various locations. -* Template for save-excursion:: -@end menu - -@node Point and mark, Template for save-excursion, save-excursion, save-excursion -@ifnottex -@unnumberedsubsec Point and Mark -@end ifnottex - -Before discussing @code{save-excursion}, however, it may be useful -first to review what point and mark are in GNU Emacs. @dfn{Point} is -the current location of the cursor. Wherever the cursor -is, that is point. More precisely, on terminals where the cursor -appears to be on top of a character, point is immediately before the -character. In Emacs Lisp, point is an integer. The first character in -a buffer is number one, the second is number two, and so on. The -function @code{point} returns the current position of the cursor as a -number. Each buffer has its own value for point. - -The @dfn{mark} is another position in the buffer; its value can be set -with a command such as @kbd{C-@key{SPC}} (@code{set-mark-command}). If -a mark has been set, you can use the command @kbd{C-x C-x} -(@code{exchange-point-and-mark}) to cause the cursor to jump to the mark -and set the mark to be the previous position of point. In addition, if -you set another mark, the position of the previous mark is saved in the -mark ring. Many mark positions can be saved this way. You can jump the -cursor to a saved mark by typing @kbd{C-u C-@key{SPC}} one or more -times. - -The part of the buffer between point and mark is called @dfn{the -region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and -@code{print-region}. - -The @code{save-excursion} special form saves the locations of point and -mark and restores those positions after the code within the body of the -special form is evaluated by the Lisp interpreter. Thus, if point were -in the beginning of a piece of text and some code moved point to the end -of the buffer, the @code{save-excursion} would put point back to where -it was before, after the expressions in the body of the function were -evaluated. - -In Emacs, a function frequently moves point as part of its internal -workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being -bothered by jumps that are both unexpected and (from the user's point of -view) unnecessary, @code{save-excursion} is often used to keep point and -mark in the location expected by the user. The use of -@code{save-excursion} is good housekeeping. - -To make sure the house stays clean, @code{save-excursion} restores the -values of point and mark even if something goes wrong in the code inside -of it (or, to be more precise and to use the proper jargon, ``in case of -abnormal exit''). This feature is very helpful. - -In addition to recording the values of point and mark, -@code{save-excursion} keeps track of the current buffer, and restores -it, too. This means you can write code that will change the buffer and -have @code{save-excursion} switch you back to the original buffer. -This is how @code{save-excursion} is used in @code{append-to-buffer}. -(@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) - -@node Template for save-excursion, , Point and mark, save-excursion -@comment node-name, next, previous, up -@subsection Template for a @code{save-excursion} Expression - -@need 800 -The template for code using @code{save-excursion} is simple: - -@smallexample -@group -(save-excursion - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -The body of the function is one or more expressions that will be -evaluated in sequence by the Lisp interpreter. If there is more than -one expression in the body, the value of the last one will be returned -as the value of the @code{save-excursion} function. The other -expressions in the body are evaluated only for their side effects; and -@code{save-excursion} itself is used only for its side effect (which -is restoring the positions of point and mark). - -@need 1250 -In more detail, the template for a @code{save-excursion} expression -looks like this: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @var{third-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@noindent -An expression, of course, may be a symbol on its own or a list. - -In Emacs Lisp code, a @code{save-excursion} expression often occurs -within the body of a @code{let} expression. It looks like this: - -@smallexample -@group -(let @var{varlist} - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@node Review, defun Exercises, save-excursion, Writing Defuns -@comment node-name, next, previous, up -@section Review - -In the last few chapters we have introduced a fair number of functions -and special forms. Here they are described in brief, along with a few -similar functions that have not been mentioned yet. - -@table @code -@item eval-last-sexp -Evaluate the last symbolic expression before the current location of -point. The value is printed in the echo area unless the function is -invoked with an argument; in that case, the output is printed in the -current buffer. This command is normally bound to @kbd{C-x C-e}. - -@item defun -Define function. This special form has up to five parts: the name, -a template for the arguments that will be passed to the function, -documentation, an optional interactive declaration, and the body of the -definition. - -@need 1250 -For example, in an early version of Emacs, the function definition was -as follows. (It is slightly more complex now that it seeks the first -non-whitespace character rather than the first visible character.) - -@smallexample -@group -(defun back-to-indentation () - "Move point to first visible character on line." - (interactive) - (beginning-of-line 1) - (skip-chars-forward " \t")) -@end group -@end smallexample - -@ignore -In GNU Emacs 22, - -(defun backward-to-indentation (&optional arg) - "Move backward ARG lines and position at first nonblank character." - (interactive "p") - (forward-line (- (or arg 1))) - (skip-chars-forward " \t")) - -(defun back-to-indentation () - "Move point to the first non-whitespace character on this line." - (interactive) - (beginning-of-line 1) - (skip-syntax-forward " " (line-end-position)) - ;; Move back over chars that have whitespace syntax but have the p flag. - (backward-prefix-chars)) -@end ignore - -@item interactive -Declare to the interpreter that the function can be used -interactively. This special form may be followed by a string with one -or more parts that pass the information to the arguments of the -function, in sequence. These parts may also tell the interpreter to -prompt for information. Parts of the string are separated by -newlines, @samp{\n}. - -@need 1000 -Common code characters are: - -@table @code -@item b -The name of an existing buffer. - -@item f -The name of an existing file. - -@item p -The numeric prefix argument. (Note that this `p' is lower case.) - -@item r -Point and the mark, as two numeric arguments, smallest first. This -is the only code letter that specifies two successive arguments -rather than one. -@end table - -@xref{Interactive Codes, , Code Characters for @samp{interactive}, -elisp, The GNU Emacs Lisp Reference Manual}, for a complete list of -code characters. - -@item let -Declare that a list of variables is for use within the body of the -@code{let} and give them an initial value, either @code{nil} or a -specified value; then evaluate the rest of the expressions in the body -of the @code{let} and return the value of the last one. Inside the -body of the @code{let}, the Lisp interpreter does not see the values of -the variables of the same names that are bound outside of the -@code{let}. - -@need 1250 -For example, - -@smallexample -@group -(let ((foo (buffer-name)) - (bar (buffer-size))) - (message - "This buffer is %s and has %d characters." - foo bar)) -@end group -@end smallexample - -@item save-excursion -Record the values of point and mark and the current buffer before -evaluating the body of this special form. Restore the values of point -and mark and buffer afterward. - -@need 1250 -For example, - -@smallexample -@group -(message "We are %d characters into this buffer." - (- (point) - (save-excursion - (goto-char (point-min)) (point)))) -@end group -@end smallexample - -@item if -Evaluate the first argument to the function; if it is true, evaluate -the second argument; else evaluate the third argument, if there is one. - -The @code{if} special form is called a @dfn{conditional}. There are -other conditionals in Emacs Lisp, but @code{if} is perhaps the most -commonly used. - -@need 1250 -For example, - -@smallexample -@group -(if (= 22 emacs-major-version) - (message "This is version 22 Emacs") - (message "This is not version 22 Emacs")) -@end group -@end smallexample - -@need 1250 -@item < -@itemx > -@itemx <= -@itemx >= -The @code{<} function tests whether its first argument is smaller than -its second argument. A corresponding function, @code{>}, tests whether -the first argument is greater than the second. Likewise, @code{<=} -tests whether the first argument is less than or equal to the second and -@code{>=} tests whether the first argument is greater than or equal to -the second. In all cases, both arguments must be numbers or markers -(markers indicate positions in buffers). - -@need 800 -@item = -The @code{=} function tests whether two arguments, both numbers or -markers, are equal. - -@need 1250 -@item equal -@itemx eq -Test whether two objects are the same. @code{equal} uses one meaning -of the word `same' and @code{eq} uses another: @code{equal} returns -true if the two objects have a similar structure and contents, such as -two copies of the same book. On the other hand, @code{eq}, returns -true if both arguments are actually the same object. -@findex equal -@findex eq - -@need 1250 -@item string< -@itemx string-lessp -@itemx string= -@itemx string-equal -The @code{string-lessp} function tests whether its first argument is -smaller than the second argument. A shorter, alternative name for the -same function (a @code{defalias}) is @code{string<}. - -The arguments to @code{string-lessp} must be strings or symbols; the -ordering is lexicographic, so case is significant. The print names of -symbols are used instead of the symbols themselves. - -@cindex @samp{empty string} defined -An empty string, @samp{""}, a string with no characters in it, is -smaller than any string of characters. - -@code{string-equal} provides the corresponding test for equality. Its -shorter, alternative name is @code{string=}. There are no string test -functions that correspond to @var{>}, @code{>=}, or @code{<=}. - -@item message -Print a message in the echo area. The first argument is a string that -can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of -arguments that follow the string. The argument used by @samp{%s} must -be a string or a symbol; the argument used by @samp{%d} must be a -number. The argument used by @samp{%c} must be an @sc{ascii} code -number; it will be printed as the character with that @sc{ascii} code. -(Various other %-sequences have not been mentioned.) - -@item setq -@itemx set -The @code{setq} function sets the value of its first argument to the -value of the second argument. The first argument is automatically -quoted by @code{setq}. It does the same for succeeding pairs of -arguments. Another function, @code{set}, takes only two arguments and -evaluates both of them before setting the value returned by its first -argument to the value returned by its second argument. - -@item buffer-name -Without an argument, return the name of the buffer, as a string. - -@itemx buffer-file-name -Without an argument, return the name of the file the buffer is -visiting. - -@item current-buffer -Return the buffer in which Emacs is active; it may not be -the buffer that is visible on the screen. - -@item other-buffer -Return the most recently selected buffer (other than the buffer passed -to @code{other-buffer} as an argument and other than the current -buffer). - -@item switch-to-buffer -Select a buffer for Emacs to be active in and display it in the current -window so users can look at it. Usually bound to @kbd{C-x b}. - -@item set-buffer -Switch Emacs' attention to a buffer on which programs will run. Don't -alter what the window is showing. - -@item buffer-size -Return the number of characters in the current buffer. - -@item point -Return the value of the current position of the cursor, as an -integer counting the number of characters from the beginning of the -buffer. - -@item point-min -Return the minimum permissible value of point in -the current buffer. This is 1, unless narrowing is in effect. - -@item point-max -Return the value of the maximum permissible value of point in the -current buffer. This is the end of the buffer, unless narrowing is in -effect. -@end table - -@need 1500 -@node defun Exercises, , Review, Writing Defuns -@section Exercises - -@itemize @bullet -@item -Write a non-interactive function that doubles the value of its -argument, a number. Make that function interactive. - -@item -Write a function that tests whether the current value of -@code{fill-column} is greater than the argument passed to the function, -and if so, prints an appropriate message. -@end itemize - -@node Buffer Walk Through, More Complex, Writing Defuns, Top -@comment node-name, next, previous, up -@chapter A Few Buffer--Related Functions - -In this chapter we study in detail several of the functions used in GNU -Emacs. This is called a ``walk-through''. These functions are used as -examples of Lisp code, but are not imaginary examples; with the -exception of the first, simplified function definition, these functions -show the actual code used in GNU Emacs. You can learn a great deal from -these definitions. The functions described here are all related to -buffers. Later, we will study other functions. - -@menu -* Finding More:: How to find more information. -* simplified-beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* mark-whole-buffer:: Almost the same as @code{beginning-of-buffer}. -* append-to-buffer:: Uses @code{save-excursion} and - @code{insert-buffer-substring}. -* Buffer Related Review:: Review. -* Buffer Exercises:: -@end menu - -@node Finding More, simplified-beginning-of-buffer, Buffer Walk Through, Buffer Walk Through -@section Finding More Information - -@findex describe-function, @r{introduced} -@cindex Find function documentation -In this walk-through, I will describe each new function as we come to -it, sometimes in detail and sometimes briefly. If you are interested, -you can get the full documentation of any Emacs Lisp function at any -time by typing @kbd{C-h f} and then the name of the function (and then -@key{RET}). Similarly, you can get the full documentation for a -variable by typing @kbd{C-h v} and then the name of the variable (and -then @key{RET}). - -@cindex Find source of function -@c In version 22, tells location both of C and of Emacs Lisp -Also, @code{describe-function} will tell you the location of the -function definition. - -Put point into the name of the file that contains the function and -press the @key{RET} key. In this case, @key{RET} means -@code{push-button} rather than `return' or `enter'. Emacs will take -you directly to the function definition. - -@ignore -Not In version 22 - -If you move point over the file name and press -the @key{RET} key, which in this case means @code{help-follow} rather -than `return' or `enter', Emacs will take you directly to the function -definition. -@end ignore - -More generally, if you want to see a function in its original source -file, you can use the @code{find-tags} function to jump to it. -@code{find-tags} works with a wide variety of languages, not just -Lisp, and C, and it works with non-programming text as well. For -example, @code{find-tags} will jump to the various nodes in the -Texinfo source file of this document. -The @code{find-tags} function depends on `tags tables' that record -the locations of the functions, variables, and other items to which -@code{find-tags} jumps. - -To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the -period key while holding down the @key{META} key, or else type the -@key{ESC} key and then type the period key), and then, at the prompt, -type in the name of the function whose source code you want to see, -such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will -switch buffers and display the source code for the function on your -screen. To switch back to your current buffer, type @kbd{C-x b -@key{RET}}. (On some keyboards, the @key{META} key is labelled -@key{ALT}.) - -@c !!! 22.1.1 tags table location in this paragraph -@cindex TAGS table, specifying -@findex find-tags -Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your `tags table', -which is a file called @file{TAGS}. For example, if you are -interested in Emacs sources, the tags table you will most likely want, -if it has already been created for you, will be in a subdirectory of -the @file{/usr/local/share/emacs/} directory; thus you would use the -@code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table -has not already been created, you will have to create it yourself. It -will in a file such as @file{/usr/local/src/emacs/src/TAGS}. - -@need 1250 -To create a @file{TAGS} file in a specific directory, switch to that -directory in Emacs using @kbd{M-x cd} command, or list the directory -with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute: - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. - -After you become more familiar with Emacs Lisp, you will find that you will -frequently use @code{find-tags} to navigate your way around source code; -and you will create your own @file{TAGS} tables. - -@cindex Library, as term for `file' -Incidentally, the files that contain Lisp code are conventionally -called @dfn{libraries}. The metaphor is derived from that of a -specialized library, such as a law library or an engineering library, -rather than a general library. Each library, or file, contains -functions that relate to a particular topic or activity, such as -@file{abbrev.el} for handling abbreviations and other typing -shortcuts, and @file{help.el} for on-line help. (Sometimes several -libraries provide code for a single activity, as the various -@file{rmail@dots{}} files provide code for reading electronic mail.) -In @cite{The GNU Emacs Manual}, you will see sentences such as ``The -@kbd{C-h p} command lets you search the standard Emacs Lisp libraries -by topic keywords.'' - -@node simplified-beginning-of-buffer, mark-whole-buffer, Finding More, Buffer Walk Through -@comment node-name, next, previous, up -@section A Simplified @code{beginning-of-buffer} Definition -@findex simplified-beginning-of-buffer - -The @code{beginning-of-buffer} command is a good function to start with -since you are likely to be familiar with it and it is easy to -understand. Used as an interactive command, @code{beginning-of-buffer} -moves the cursor to the beginning of the buffer, leaving the mark at the -previous position. It is generally bound to @kbd{M-<}. - -In this section, we will discuss a shortened version of the function -that shows how it is most frequently used. This shortened function -works as written, but it does not contain the code for a complex option. -In another section, we will describe the entire function. -(@xref{beginning-of-buffer, , Complete Definition of -@code{beginning-of-buffer}}.) - -Before looking at the code, let's consider what the function -definition has to contain: it must include an expression that makes -the function interactive so it can be called by typing @kbd{M-x -beginning-of-buffer} or by typing a keychord such as @kbd{M-<}; it -must include code to leave a mark at the original position in the -buffer; and it must include code to move the cursor to the beginning -of the buffer. - -@need 1250 -Here is the complete text of the shortened version of the function: - -@smallexample -@group -(defun simplified-beginning-of-buffer () - "Move point to the beginning of the buffer; -leave mark at previous position." - (interactive) - (push-mark) - (goto-char (point-min))) -@end group -@end smallexample - -Like all function definitions, this definition has five parts following -the special form @code{defun}: - -@enumerate -@item -The name: in this example, @code{simplified-beginning-of-buffer}. - -@item -A list of the arguments: in this example, an empty list, @code{()}, - -@item -The documentation string. - -@item -The interactive expression. - -@item -The body. -@end enumerate - -@noindent -In this function definition, the argument list is empty; this means that -this function does not require any arguments. (When we look at the -definition for the complete function, we will see that it may be passed -an optional argument.) - -The interactive expression tells Emacs that the function is intended to -be used interactively. In this example, @code{interactive} does not have -an argument because @code{simplified-beginning-of-buffer} does not -require one. - -@need 800 -The body of the function consists of the two lines: - -@smallexample -@group -(push-mark) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark)}. When -this expression is evaluated by the Lisp interpreter, it sets a mark at -the current position of the cursor, wherever that may be. The position -of this mark is saved in the mark ring. - -The next line is @code{(goto-char (point-min))}. This expression -jumps the cursor to the minimum point in the buffer, that is, to the -beginning of the buffer (or to the beginning of the accessible portion -of the buffer if it is narrowed. @xref{Narrowing & Widening, , -Narrowing and Widening}.) - -The @code{push-mark} command sets a mark at the place where the cursor -was located before it was moved to the beginning of the buffer by the -@code{(goto-char (point-min))} expression. Consequently, you can, if -you wish, go back to where you were originally by typing @kbd{C-x C-x}. - -That is all there is to the function definition! - -@findex describe-function -When you are reading code such as this and come upon an unfamiliar -function, such as @code{goto-char}, you can find out what it does by -using the @code{describe-function} command. To use this command, type -@kbd{C-h f} and then type in the name of the function and press -@key{RET}. The @code{describe-function} command will print the -function's documentation string in a @file{*Help*} window. For -example, the documentation for @code{goto-char} is: - -@smallexample -@group -Set point to POSITION, a number or marker. -Beginning of buffer is position (point-min), end is (point-max). -@end group -@end smallexample - -@noindent -The function's one argument is the desired position. - -@noindent -(The prompt for @code{describe-function} will offer you the symbol -under or preceding the cursor, so you can save typing by positioning -the cursor right over or after the function and then typing @kbd{C-h f -@key{RET}}.) - -The @code{end-of-buffer} function definition is written in the same way as -the @code{beginning-of-buffer} definition except that the body of the -function contains the expression @code{(goto-char (point-max))} in place -of @code{(goto-char (point-min))}. - -@node mark-whole-buffer, append-to-buffer, simplified-beginning-of-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{mark-whole-buffer} -@findex mark-whole-buffer - -The @code{mark-whole-buffer} function is no harder to understand than the -@code{simplified-beginning-of-buffer} function. In this case, however, -we will look at the complete function, not a shortened version. - -The @code{mark-whole-buffer} function is not as commonly used as the -@code{beginning-of-buffer} function, but is useful nonetheless: it -marks a whole buffer as a region by putting point at the beginning and -a mark at the end of the buffer. It is generally bound to @kbd{C-x -h}. - -@menu -* mark-whole-buffer overview:: -* Body of mark-whole-buffer:: Only three lines of code. -@end menu - -@node mark-whole-buffer overview, Body of mark-whole-buffer, mark-whole-buffer, mark-whole-buffer -@ifnottex -@unnumberedsubsec An overview of @code{mark-whole-buffer} -@end ifnottex - -@need 1250 -In GNU Emacs 22, the code for the complete function looks like this: - -@smallexample -@group -(defun mark-whole-buffer () - "Put point at beginning and mark at end of buffer. -You probably should not use this function in Lisp programs; -it is usually a mistake for a Lisp function to use any subroutine -that uses or sets the mark." - (interactive) - (push-mark (point)) - (push-mark (point-max) nil t) - (goto-char (point-min))) -@end group -@end smallexample - -@need 1250 -Like all other functions, the @code{mark-whole-buffer} function fits -into the template for a function definition. The template looks like -this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -Here is how the function works: the name of the function is -@code{mark-whole-buffer}; it is followed by an empty argument list, -@samp{()}, which means that the function does not require arguments. -The documentation comes next. - -The next line is an @code{(interactive)} expression that tells Emacs -that the function will be used interactively. These details are similar -to the @code{simplified-beginning-of-buffer} function described in the -previous section. - -@need 1250 -@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer -@comment node-name, next, previous, up -@subsection Body of @code{mark-whole-buffer} - -The body of the @code{mark-whole-buffer} function consists of three -lines of code: - -@c GNU Emacs 22 -@smallexample -@group -(push-mark (point)) -(push-mark (point-max) nil t) -(goto-char (point-min)) -@end group -@end smallexample - -The first of these lines is the expression, @code{(push-mark (point))}. - -This line does exactly the same job as the first line of the body of -the @code{simplified-beginning-of-buffer} function, which is written -@code{(push-mark)}. In both cases, the Lisp interpreter sets a mark -at the current position of the cursor. - -I don't know why the expression in @code{mark-whole-buffer} is written -@code{(push-mark (point))} and the expression in -@code{beginning-of-buffer} is written @code{(push-mark)}. Perhaps -whoever wrote the code did not know that the arguments for -@code{push-mark} are optional and that if @code{push-mark} is not -passed an argument, the function automatically sets mark at the -location of point by default. Or perhaps the expression was written -so as to parallel the structure of the next line. In any case, the -line causes Emacs to determine the position of point and set a mark -there. - -In earlier versions of GNU Emacs, the next line of -@code{mark-whole-buffer} was @code{(push-mark (point-max))}. This -expression sets a mark at the point in the buffer that has the highest -number. This will be the end of the buffer (or, if the buffer is -narrowed, the end of the accessible portion of the buffer. -@xref{Narrowing & Widening, , Narrowing and Widening}, for more about -narrowing.) After this mark has been set, the previous mark, the one -set at point, is no longer set, but Emacs remembers its position, just -as all other recent marks are always remembered. This means that you -can, if you wish, go back to that position by typing @kbd{C-u -C-@key{SPC}} twice. - -@need 1250 -In GNU Emacs 22, the @code{(point-max)} is slightly more complicated. -The line reads - -@smallexample -(push-mark (point-max) nil t) -@end smallexample - -@noindent -The expression works nearly the same as before. It sets a mark at the -highest numbered place in the buffer that it can. However, in this -version, @code{push-mark} has two additional arguments. The second -argument to @code{push-mark} is @code{nil}. This tells the function -it @emph{should} display a message that says `Mark set' when it pushes -the mark. The third argument is @code{t}. This tells -@code{push-mark} to activate the mark when Transient Mark mode is -turned on. Transient Mark mode highlights the currently active -region. It is often turned off. - -Finally, the last line of the function is @code{(goto-char -(point-min)))}. This is written exactly the same way as it is written -in @code{beginning-of-buffer}. The expression moves the cursor to -the minimum point in the buffer, that is, to the beginning of the buffer -(or to the beginning of the accessible portion of the buffer). As a -result of this, point is placed at the beginning of the buffer and mark -is set at the end of the buffer. The whole buffer is, therefore, the -region. - -@node append-to-buffer, Buffer Related Review, mark-whole-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section The Definition of @code{append-to-buffer} -@findex append-to-buffer - -The @code{append-to-buffer} command is more complex than the -@code{mark-whole-buffer} command. What it does is copy the region -(that is, the part of the buffer between point and mark) from the -current buffer to a specified buffer. - -@menu -* append-to-buffer overview:: -* append interactive:: A two part interactive expression. -* append-to-buffer body:: Incorporates a @code{let} expression. -* append save-excursion:: How the @code{save-excursion} works. -@end menu - -@node append-to-buffer overview, append interactive, append-to-buffer, append-to-buffer -@ifnottex -@unnumberedsubsec An Overview of @code{append-to-buffer} -@end ifnottex - -@findex insert-buffer-substring -The @code{append-to-buffer} command uses the -@code{insert-buffer-substring} function to copy the region. -@code{insert-buffer-substring} is described by its name: it takes a -string of characters from part of a buffer, a ``substring'', and -inserts them into another buffer. - -Most of @code{append-to-buffer} is -concerned with setting up the conditions for -@code{insert-buffer-substring} to work: the code must specify both the -buffer to which the text will go, the window it comes from and goes -to, and the region that will be copied. - -@need 1250 -Here is the complete text of the function: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. -@end group - -@group -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer - (current-buffer) t)) - (region-beginning) (region-end))) -@end group -@group - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end group -@end smallexample - -The function can be understood by looking at it as a series of -filled-in templates. - -The outermost template is for the function definition. In this -function, it looks like this (with several slots filled in): - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -The first line of the function includes its name and three arguments. -The arguments are the @code{buffer} to which the text will be copied, and -the @code{start} and @code{end} of the region in the current buffer that -will be copied. - -The next part of the function is the documentation, which is clear and -complete. As is conventional, the three arguments are written in -upper case so you will notice them easily. Even better, they are -described in the same order as in the argument list. - -Note that the documentation distinguishes between a buffer and its -name. (The function can handle either.) - -@node append interactive, append-to-buffer body, append-to-buffer overview, append-to-buffer -@comment node-name, next, previous, up -@subsection The @code{append-to-buffer} Interactive Expression - -Since the @code{append-to-buffer} function will be used interactively, -the function must have an @code{interactive} expression. (For a -review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: - -@smallexample -@group -(interactive - (list (read-buffer - "Append to buffer: " - (other-buffer (current-buffer) t)) - (region-beginning) - (region-end))) -@end group -@end smallexample - -@noindent -This expression is not one with letters standing for parts, as -described earlier. Instead, it starts a list with these parts: - -The first part of the list is an expression to read the name of a -buffer and return it as a string. That is @code{read-buffer}. The -function requires a prompt as its first argument, @samp{"Append to -buffer: "}. Its second argument tells the command what value to -provide if you don't specify anything. - -In this case that second argument is an expression containing the -function @code{other-buffer}, an exception, and a @samp{t}, standing -for true. - -The first argument to @code{other-buffer}, the exception, is yet -another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that -tells @code{other-buffer} that it may show visible buffers (except in -this case, it will not show the current buffer, which makes sense). - -@need 1250 -The expression looks like this: - -@smallexample -(other-buffer (current-buffer) t) -@end smallexample - -The second and third arguments to the @code{list} expression are -@code{(region-beginning)} and @code{(region-end)}. These two -functions specify the beginning and end of the text to be appended. - -@need 1250 -Originally, the command used the letters @samp{B} and @samp{r}. -The whole @code{interactive} expression looked like this: - -@smallexample -(interactive "BAppend to buffer:@: \nr") -@end smallexample - -@noindent -But when that was done, the default value of the buffer switched to -was invisible. That was not wanted. - -(The prompt was separated from the second argument with a newline, -@samp{\n}. It was followed by an @samp{r} that told Emacs to bind the -two arguments that follow the symbol @code{buffer} in the function's -argument list (that is, @code{start} and @code{end}) to the values of -point and mark. That argument worked fine.) - -@node append-to-buffer body, append save-excursion, append interactive, append-to-buffer -@comment node-name, next, previous, up -@subsection The Body of @code{append-to-buffer} - -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The body of the @code{append-to-buffer} function begins with @code{let}. - -As we have seen before (@pxref{let, , @code{let}}), the purpose of a -@code{let} expression is to create and give initial values to one or -more variables that will only be used within the body of the -@code{let}. This means that such a variable will not be confused with -any variable of the same name outside the @code{let} expression. - -We can see how the @code{let} expression fits into the function as a -whole by showing a template for @code{append-to-buffer} with the -@code{let} expression in outline: - -@smallexample -@group -(defun append-to-buffer (buffer start end) - "@var{documentation}@dots{}" - (interactive @dots{}) - (let ((@var{variable} @var{value})) - @var{body}@dots{}) -@end group -@end smallexample - -The @code{let} expression has three elements: - -@enumerate -@item -The symbol @code{let}; - -@item -A varlist containing, in this case, a single two-element list, -@code{(@var{variable} @var{value})}; - -@item -The body of the @code{let} expression. -@end enumerate - -@need 800 -In the @code{append-to-buffer} function, the varlist looks like this: - -@smallexample -(oldbuf (current-buffer)) -@end smallexample - -@noindent -In this part of the @code{let} expression, the one variable, -@code{oldbuf}, is bound to the value returned by the -@code{(current-buffer)} expression. The variable, @code{oldbuf}, is -used to keep track of the buffer in which you are working and from -which you will copy. - -The element or elements of a varlist are surrounded by a set of -parentheses so the Lisp interpreter can distinguish the varlist from -the body of the @code{let}. As a consequence, the two-element list -within the varlist is surrounded by a circumscribing set of parentheses. -The line looks like this: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - @dots{} ) -@end group -@end smallexample - -@noindent -The two parentheses before @code{oldbuf} might surprise you if you did -not realize that the first parenthesis before @code{oldbuf} marks the -boundary of the varlist and the second parenthesis marks the beginning -of the two-element list, @code{(oldbuf (current-buffer))}. - -@node append save-excursion, , append-to-buffer body, append-to-buffer -@comment node-name, next, previous, up -@subsection @code{save-excursion} in @code{append-to-buffer} - -The body of the @code{let} expression in @code{append-to-buffer} -consists of a @code{save-excursion} expression. - -The @code{save-excursion} function saves the locations of point and -mark, and restores them to those positions after the expressions in the -body of the @code{save-excursion} complete execution. In addition, -@code{save-excursion} keeps track of the original buffer, and -restores it. This is how @code{save-excursion} is used in -@code{append-to-buffer}. - -@need 1500 -@cindex Indentation for formatting -@cindex Formatting convention -Incidentally, it is worth noting here that a Lisp function is normally -formatted so that everything that is enclosed in a multi-line spread is -indented more to the right than the first symbol. In this function -definition, the @code{let} is indented more than the @code{defun}, and -the @code{save-excursion} is indented more than the @code{let}, like -this: - -@smallexample -@group -(defun @dots{} - @dots{} - @dots{} - (let@dots{} - (save-excursion - @dots{} -@end group -@end smallexample - -@need 1500 -@noindent -This formatting convention makes it easy to see that the lines in -the body of the @code{save-excursion} are enclosed by the parentheses -associated with @code{save-excursion}, just as the -@code{save-excursion} itself is enclosed by the parentheses associated -with the @code{let}: - -@smallexample -@group -(let ((oldbuf (current-buffer))) - (save-excursion - @dots{} - (set-buffer @dots{}) - (insert-buffer-substring oldbuf start end) - @dots{})) -@end group -@end smallexample - -@need 1200 -The use of the @code{save-excursion} function can be viewed as a process -of filling in the slots of a template: - -@smallexample -@group -(save-excursion - @var{first-expression-in-body} - @var{second-expression-in-body} - @dots{} - @var{last-expression-in-body}) -@end group -@end smallexample - -@need 1200 -@noindent -In this function, the body of the @code{save-excursion} contains only -one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. - -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. - -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. - -@need 1250 -In the old days, the @code{set-buffer} expression was simply - -@smallexample -(set-buffer (get-buffer-create buffer)) -@end smallexample - -@need 1250 -@noindent -but now it is - -@smallexample -(set-buffer append-to) -@end smallexample - -@noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - -The @code{append-to-buffer} function definition inserts text from the -buffer in which you are currently to a named buffer. It happens that -@code{insert-buffer-substring} copies text from another buffer to the -current buffer, just the reverse---that is why the -@code{append-to-buffer} definition starts out with a @code{let} that -binds the local symbol @code{oldbuf} to the value returned by -@code{current-buffer}. - -@need 1250 -The @code{insert-buffer-substring} expression looks like this: - -@smallexample -(insert-buffer-substring oldbuf start end) -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies a string -@emph{from} the buffer specified as its first argument and inserts the -string into the present buffer. In this case, the argument to -@code{insert-buffer-substring} is the value of the variable created -and bound by the @code{let}, namely the value of @code{oldbuf}, which -was the current buffer when you gave the @code{append-to-buffer} -command. - -After @code{insert-buffer-substring} has done its work, -@code{save-excursion} will restore the action to the original buffer -and @code{append-to-buffer} will have done its job. - -@need 800 -Written in skeletal form, the workings of the body look like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (save-excursion ; @r{Keep track of buffer.} - @var{change-buffer} - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}) - - @var{change-back-to-original-buffer-when-finished} -@var{let-the-local-meaning-of-}@code{oldbuf}@var{-disappear-when-finished} -@end group -@end smallexample - -In summary, @code{append-to-buffer} works as follows: it saves the -value of the current buffer in the variable called @code{oldbuf}. It -gets the new buffer (creating one if need be) and switches Emacs' -attention to it. Using the value of @code{oldbuf}, it inserts the -region of text from the old buffer into the new buffer; and then using -@code{save-excursion}, it brings you back to your original buffer. - -In looking at @code{append-to-buffer}, you have explored a fairly -complex function. It shows how to use @code{let} and -@code{save-excursion}, and how to change to and come back from another -buffer. Many function definitions use @code{let}, -@code{save-excursion}, and @code{set-buffer} this way. - -@node Buffer Related Review, Buffer Exercises, append-to-buffer, Buffer Walk Through -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of the various functions discussed in this chapter. - -@table @code -@item describe-function -@itemx describe-variable -Print the documentation for a function or variable. -Conventionally bound to @kbd{C-h f} and @kbd{C-h v}. - -@item find-tag -Find the file containing the source for a function or variable and -switch buffers to it, positioning point at the beginning of the item. -Conventionally bound to @kbd{M-.} (that's a period following the -@key{META} key). - -@item save-excursion -Save the location of point and mark and restore their values after the -arguments to @code{save-excursion} have been evaluated. Also, remember -the current buffer and return to it. - -@item push-mark -Set mark at a location and record the value of the previous mark on the -mark ring. The mark is a location in the buffer that will keep its -relative position even if text is added to or removed from the buffer. - -@item goto-char -Set point to the location specified by the value of the argument, which -can be a number, a marker, or an expression that returns the number of -a position, such as @code{(point-min)}. - -@item insert-buffer-substring -Copy a region of text from a buffer that is passed to the function as -an argument and insert the region into the current buffer. - -@item mark-whole-buffer -Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. - -@item set-buffer -Switch the attention of Emacs to another buffer, but do not change the -window being displayed. Used when the program rather than a human is -to work on a different buffer. - -@item get-buffer-create -@itemx get-buffer -Find a named buffer or create one if a buffer of that name does not -exist. The @code{get-buffer} function returns @code{nil} if the named -buffer does not exist. -@end table - -@need 1500 -@node Buffer Exercises, , Buffer Related Review, Buffer Walk Through -@section Exercises - -@itemize @bullet -@item -Write your own @code{simplified-end-of-buffer} function definition; -then test it to see whether it works. - -@item -Use @code{if} and @code{get-buffer} to write a function that prints a -message telling you whether a buffer exists. - -@item -Using @code{find-tag}, find the source for the @code{copy-to-buffer} -function. -@end itemize - -@node More Complex, Narrowing & Widening, Buffer Walk Through, Top -@comment node-name, next, previous, up -@chapter A Few More Complex Functions - -In this chapter, we build on what we have learned in previous chapters -by looking at more complex functions. The @code{copy-to-buffer} -function illustrates use of two @code{save-excursion} expressions in -one definition, while the @code{insert-buffer} function illustrates -use of an asterisk in an @code{interactive} expression, use of -@code{or}, and the important distinction between a name and the object -to which the name refers. - -@menu -* copy-to-buffer:: With @code{set-buffer}, @code{get-buffer-create}. -* insert-buffer:: Read-only, and with @code{or}. -* beginning-of-buffer:: Shows @code{goto-char}, - @code{point-min}, and @code{push-mark}. -* Second Buffer Related Review:: -* optional Exercise:: -@end menu - -@node copy-to-buffer, insert-buffer, More Complex, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{copy-to-buffer} -@findex copy-to-buffer - -After understanding how @code{append-to-buffer} works, it is easy to -understand @code{copy-to-buffer}. This function copies text into a -buffer, but instead of adding to the second buffer, it replaces all the -previous text in the second buffer. - -@need 800 -The body of @code{copy-to-buffer} looks like this, - -@smallexample -@group -@dots{} -(interactive "BCopy to buffer: \nr") -(let ((oldbuf (current-buffer))) - (with-current-buffer (get-buffer-create buffer) - (barf-if-buffer-read-only) - (erase-buffer) - (save-excursion - (insert-buffer-substring oldbuf start end))))) -@end group -@end smallexample - -The @code{copy-to-buffer} function has a simpler @code{interactive} -expression than @code{append-to-buffer}. - -@need 800 -The definition then says - -@smallexample -(with-current-buffer (get-buffer-create buffer) @dots{} -@end smallexample - -First, look at the earliest inner expression; that is evaluated first. -That expression starts with @code{get-buffer-create buffer}. The -function tells the computer to use the buffer with the name specified -as the one to which you are copying, or if such a buffer does not -exist, to create it. Then, the @code{with-current-buffer} function -evaluates its body with that buffer temporarily current. - -(This demonstrates another way to shift the computer's attention but -not the user's. The @code{append-to-buffer} function showed how to do -the same with @code{save-excursion} and @code{set-buffer}. -@code{with-current-buffer} is a newer, and arguably easier, -mechanism.) - -The @code{barf-if-buffer-read-only} function sends you an error -message saying the buffer is read-only if you cannot modify it. - -The next line has the @code{erase-buffer} function as its sole -contents. That function erases the buffer. - -Finally, the last two lines contain the @code{save-excursion} -expression with @code{insert-buffer-substring} as its body. -The @code{insert-buffer-substring} expression copies the text from -the buffer you are in (and you have not seen the computer shift its -attention, so you don't know that that buffer is now called -@code{oldbuf}). - -Incidentally, this is what is meant by `replacement'. To replace text, -Emacs erases the previous text and then inserts new text. - -@need 1250 -In outline, the body of @code{copy-to-buffer} looks like this: - -@smallexample -@group -(let (@var{bind-}@code{oldbuf}@var{-to-value-of-}@code{current-buffer}) - (@var{with-the-buffer-you-are-copying-to} - (@var{but-do-not-erase-or-copy-to-a-read-only-buffer}) - (erase-buffer) - (save-excursion - @var{insert-substring-from-}@code{oldbuf}@var{-into-buffer}))) -@end group -@end smallexample - -@node insert-buffer, beginning-of-buffer, copy-to-buffer, More Complex -@comment node-name, next, previous, up -@section The Definition of @code{insert-buffer} -@findex insert-buffer - -@code{insert-buffer} is yet another buffer-related function. This -command copies another buffer @emph{into} the current buffer. It is the -reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they -copy a region of text @emph{from} the current buffer to another buffer. - -Here is a discussion based on the original code. The code was -simplified in 2003 and is harder to understand. - -(@xref{New insert-buffer, , New Body for @code{insert-buffer}}, to see -a discussion of the new body.) - -In addition, this code illustrates the use of @code{interactive} with a -buffer that might be @dfn{read-only} and the important distinction -between the name of an object and the object actually referred to. - -@menu -* insert-buffer code:: -* insert-buffer interactive:: When you can read, but not write. -* insert-buffer body:: The body has an @code{or} and a @code{let}. -* if & or:: Using an @code{if} instead of an @code{or}. -* Insert or:: How the @code{or} expression works. -* Insert let:: Two @code{save-excursion} expressions. -* New insert-buffer:: -@end menu - -@node insert-buffer code, insert-buffer interactive, insert-buffer, insert-buffer -@ifnottex -@unnumberedsubsec The Code for @code{insert-buffer} -@end ifnottex - -@need 800 -Here is the earlier code: - -@smallexample -@group -(defun insert-buffer (buffer) - "Insert after point the contents of BUFFER. -Puts mark after the inserted text. -BUFFER may be a buffer or a buffer name." - (interactive "*bInsert buffer:@: ") -@end group -@group - (or (bufferp buffer) - (setq buffer (get-buffer buffer))) - (let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@group - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark))) -@end group -@end smallexample - -@need 1200 -As with other function definitions, you can use a template to see an -outline of the function: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - @var{body}@dots{}) -@end group -@end smallexample - -@node insert-buffer interactive, insert-buffer body, insert-buffer code, insert-buffer -@comment node-name, next, previous, up -@subsection The Interactive Expression in @code{insert-buffer} -@findex interactive, @r{example use of} - -In @code{insert-buffer}, the argument to the @code{interactive} -declaration has two parts, an asterisk, @samp{*}, and @samp{bInsert -buffer:@: }. - -@menu -* Read-only buffer:: When a buffer cannot be modified. -* b for interactive:: An existing buffer or else its name. -@end menu - -@node Read-only buffer, b for interactive, insert-buffer interactive, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec A Read-only Buffer -@cindex Read-only buffer -@cindex Asterisk for read-only buffer -@findex * @r{for read-only buffer} - -The asterisk is for the situation when the current buffer is a -read-only buffer---a buffer that cannot be modified. If -@code{insert-buffer} is called when the current buffer is read-only, a -message to this effect is printed in the echo area and the terminal -may beep or blink at you; you will not be permitted to insert anything -into current buffer. The asterisk does not need to be followed by a -newline to separate it from the next argument. - -@node b for interactive, , Read-only buffer, insert-buffer interactive -@comment node-name, next, previous, up -@unnumberedsubsubsec @samp{b} in an Interactive Expression - -The next argument in the interactive expression starts with a lower -case @samp{b}. (This is different from the code for -@code{append-to-buffer}, which uses an upper-case @samp{B}. -@xref{append-to-buffer, , The Definition of @code{append-to-buffer}}.) -The lower-case @samp{b} tells the Lisp interpreter that the argument -for @code{insert-buffer} should be an existing buffer or else its -name. (The upper-case @samp{B} option provides for the possibility -that the buffer does not exist.) Emacs will prompt you for the name -of the buffer, offering you a default buffer, with name completion -enabled. If the buffer does not exist, you receive a message that -says ``No match''; your terminal may beep at you as well. - -The new and simplified code generates a list for @code{interactive}. -It uses the @code{barf-if-buffer-read-only} and @code{read-buffer} -functions with which we are already familiar and the @code{progn} -special form with which we are not. (It will be described later.) - -@node insert-buffer body, if & or, insert-buffer interactive, insert-buffer -@comment node-name, next, previous, up -@subsection The Body of the @code{insert-buffer} Function - -The body of the @code{insert-buffer} function has two major parts: an -@code{or} expression and a @code{let} expression. The purpose of the -@code{or} expression is to ensure that the argument @code{buffer} is -bound to a buffer and not just the name of a buffer. The body of the -@code{let} expression contains the code which copies the other buffer -into the current buffer. - -@need 1250 -In outline, the two expressions fit into the @code{insert-buffer} -function like this: - -@smallexample -@group -(defun insert-buffer (buffer) - "@var{documentation}@dots{}" - (interactive "*bInsert buffer:@: ") - (or @dots{} - @dots{} -@end group -@group - (let (@var{varlist}) - @var{body-of-}@code{let}@dots{} ) -@end group -@end smallexample - -To understand how the @code{or} expression ensures that the argument -@code{buffer} is bound to a buffer and not to the name of a buffer, it -is first necessary to understand the @code{or} function. - -Before doing this, let me rewrite this part of the function using -@code{if} so that you can see what is done in a manner that will be familiar. - -@node if & or, Insert or, insert-buffer body, insert-buffer -@comment node-name, next, previous, up -@subsection @code{insert-buffer} With an @code{if} Instead of an @code{or} - -The job to be done is to make sure the value of @code{buffer} is a -buffer itself and not the name of a buffer. If the value is the name, -then the buffer itself must be got. - -You can imagine yourself at a conference where an usher is wandering -around holding a list with your name on it and looking for you: the -usher is ``bound'' to your name, not to you; but when the usher finds -you and takes your arm, the usher becomes ``bound'' to you. - -@need 800 -In Lisp, you might describe this situation like this: - -@smallexample -@group -(if (not (holding-on-to-guest)) - (find-and-take-arm-of-guest)) -@end group -@end smallexample - -We want to do the same thing with a buffer---if we do not have the -buffer itself, we want to get it. - -@need 1200 -Using a predicate called @code{bufferp} that tells us whether we have a -buffer (rather than its name), we can write the code like this: - -@smallexample -@group -(if (not (bufferp buffer)) ; @r{if-part} - (setq buffer (get-buffer buffer))) ; @r{then-part} -@end group -@end smallexample - -@noindent -Here, the true-or-false-test of the @code{if} expression is -@w{@code{(not (bufferp buffer))}}; and the then-part is the expression -@w{@code{(setq buffer (get-buffer buffer))}}. - -In the test, the function @code{bufferp} returns true if its argument is -a buffer---but false if its argument is the name of the buffer. (The -last character of the function name @code{bufferp} is the character -@samp{p}; as we saw earlier, such use of @samp{p} is a convention that -indicates that the function is a predicate, which is a term that means -that the function will determine whether some property is true or false. -@xref{Wrong Type of Argument, , Using the Wrong Type Object as an -Argument}.) - -@need 1200 -The function @code{not} precedes the expression @code{(bufferp buffer)}, -so the true-or-false-test looks like this: - -@smallexample -(not (bufferp buffer)) -@end smallexample - -@noindent -@code{not} is a function that returns true if its argument is false -and false if its argument is true. So if @code{(bufferp buffer)} -returns true, the @code{not} expression returns false and vice-verse: -what is ``not true'' is false and what is ``not false'' is true. - -Using this test, the @code{if} expression works as follows: when the -value of the variable @code{buffer} is actually a buffer rather than -its name, the true-or-false-test returns false and the @code{if} -expression does not evaluate the then-part. This is fine, since we do -not need to do anything to the variable @code{buffer} if it really is -a buffer. - -On the other hand, when the value of @code{buffer} is not a buffer -itself, but the name of a buffer, the true-or-false-test returns true -and the then-part of the expression is evaluated. In this case, the -then-part is @code{(setq buffer (get-buffer buffer))}. This -expression uses the @code{get-buffer} function to return an actual -buffer itself, given its name. The @code{setq} then sets the variable -@code{buffer} to the value of the buffer itself, replacing its previous -value (which was the name of the buffer). - -@node Insert or, Insert let, if & or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{or} in the Body - -The purpose of the @code{or} expression in the @code{insert-buffer} -function is to ensure that the argument @code{buffer} is bound to a -buffer and not just to the name of a buffer. The previous section shows -how the job could have been done using an @code{if} expression. -However, the @code{insert-buffer} function actually uses @code{or}. -To understand this, it is necessary to understand how @code{or} works. - -@findex or -An @code{or} function can have any number of arguments. It evaluates -each argument in turn and returns the value of the first of its -arguments that is not @code{nil}. Also, and this is a crucial feature -of @code{or}, it does not evaluate any subsequent arguments after -returning the first non-@code{nil} value. - -@need 800 -The @code{or} expression looks like this: - -@smallexample -@group -(or (bufferp buffer) - (setq buffer (get-buffer buffer))) -@end group -@end smallexample - -@noindent -The first argument to @code{or} is the expression @code{(bufferp buffer)}. -This expression returns true (a non-@code{nil} value) if the buffer is -actually a buffer, and not just the name of a buffer. In the @code{or} -expression, if this is the case, the @code{or} expression returns this -true value and does not evaluate the next expression---and this is fine -with us, since we do not want to do anything to the value of -@code{buffer} if it really is a buffer. - -On the other hand, if the value of @code{(bufferp buffer)} is @code{nil}, -which it will be if the value of @code{buffer} is the name of a buffer, -the Lisp interpreter evaluates the next element of the @code{or} -expression. This is the expression @code{(setq buffer (get-buffer -buffer))}. This expression returns a non-@code{nil} value, which -is the value to which it sets the variable @code{buffer}---and this -value is a buffer itself, not the name of a buffer. - -The result of all this is that the symbol @code{buffer} is always -bound to a buffer itself rather than to the name of a buffer. All -this is necessary because the @code{set-buffer} function in a -following line only works with a buffer itself, not with the name to a -buffer. - -@need 1250 -Incidentally, using @code{or}, the situation with the usher would be -written like this: - -@smallexample -(or (holding-on-to-guest) (find-and-take-arm-of-guest)) -@end smallexample - -@node Insert let, New insert-buffer, Insert or, insert-buffer -@comment node-name, next, previous, up -@subsection The @code{let} Expression in @code{insert-buffer} - -After ensuring that the variable @code{buffer} refers to a buffer itself -and not just to the name of a buffer, the @code{insert-buffer function} -continues with a @code{let} expression. This specifies three local -variables, @code{start}, @code{end}, and @code{newmark} and binds them -to the initial value @code{nil}. These variables are used inside the -remainder of the @code{let} and temporarily hide any other occurrence of -variables of the same name in Emacs until the end of the @code{let}. - -@need 1200 -The body of the @code{let} contains two @code{save-excursion} -expressions. First, we will look at the inner @code{save-excursion} -expression in detail. The expression looks like this: - -@smallexample -@group -(save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) -@end group -@end smallexample - -@noindent -The expression @code{(set-buffer buffer)} changes Emacs' attention -from the current buffer to the one from which the text will copied. -In that buffer, the variables @code{start} and @code{end} are set to -the beginning and end of the buffer, using the commands -@code{point-min} and @code{point-max}. Note that we have here an -illustration of how @code{setq} is able to set two variables in the -same expression. The first argument of @code{setq} is set to the -value of its second, and its third argument is set to the value of its -fourth. - -After the body of the inner @code{save-excursion} is evaluated, the -@code{save-excursion} restores the original buffer, but @code{start} and -@code{end} remain set to the values of the beginning and end of the -buffer from which the text will be copied. - -@need 1250 -The outer @code{save-excursion} expression looks like this: - -@smallexample -@group -(save-excursion - (@var{inner-}@code{save-excursion}@var{-expression} - (@var{go-to-new-buffer-and-set-}@code{start}@var{-and-}@code{end}) - (insert-buffer-substring buffer start end) - (setq newmark (point))) -@end group -@end smallexample - -@noindent -The @code{insert-buffer-substring} function copies the text -@emph{into} the current buffer @emph{from} the region indicated by -@code{start} and @code{end} in @code{buffer}. Since the whole of the -second buffer lies between @code{start} and @code{end}, the whole of -the second buffer is copied into the buffer you are editing. Next, -the value of point, which will be at the end of the inserted text, is -recorded in the variable @code{newmark}. - -After the body of the outer @code{save-excursion} is evaluated, point -and mark are relocated to their original places. - -However, it is convenient to locate a mark at the end of the newly -inserted text and locate point at its beginning. The @code{newmark} -variable records the end of the inserted text. In the last line of -the @code{let} expression, the @code{(push-mark newmark)} expression -function sets a mark to this location. (The previous location of the -mark is still accessible; it is recorded on the mark ring and you can -go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is -located at the beginning of the inserted text, which is where it was -before you called the insert function, the position of which was saved -by the first @code{save-excursion}. - -@need 1250 -The whole @code{let} expression looks like this: - -@smallexample -@group -(let (start end newmark) - (save-excursion - (save-excursion - (set-buffer buffer) - (setq start (point-min) end (point-max))) - (insert-buffer-substring buffer start end) - (setq newmark (point))) - (push-mark newmark)) -@end group -@end smallexample - -Like the @code{append-to-buffer} function, the @code{insert-buffer} -function uses @code{let}, @code{save-excursion}, and -@code{set-buffer}. In addition, the function illustrates one way to -use @code{or}. All these functions are building blocks that we will -find and use again and again. - -@node New insert-buffer, , Insert let, insert-buffer -@comment node-name, next, previous, up -@subsection New Body for @code{insert-buffer} -@findex insert-buffer, new version body -@findex new version body for insert-buffer - -The body in the GNU Emacs 22 version is more confusing than the original. - -@need 1250 -It consists of two expressions, - -@smallexample -@group - (push-mark - (save-excursion - (insert-buffer-substring (get-buffer buffer)) - (point))) - - nil -@end group -@end smallexample - -@noindent -except, and this is what confuses novices, very important work is done -inside the @code{push-mark} expression. - -The @code{get-buffer} function returns a buffer with the name -provided. You will note that the function is @emph{not} called -@code{get-buffer-create}; it does not create a buffer if one does not -already exist. The buffer returned by @code{get-buffer}, an existing -buffer, is passed to @code{insert-buffer-substring}, which inserts the -whole of the buffer (since you did not specify anything else). - -The location into which the buffer is inserted is recorded by -@code{push-mark}. Then the function returns @code{nil}, the value of -its last command. Put another way, the @code{insert-buffer} function -exists only to produce a side effect, inserting another buffer, not to -return any value. - -@node beginning-of-buffer, Second Buffer Related Review, insert-buffer, More Complex -@comment node-name, next, previous, up -@section Complete Definition of @code{beginning-of-buffer} -@findex beginning-of-buffer - -The basic structure of the @code{beginning-of-buffer} function has -already been discussed. (@xref{simplified-beginning-of-buffer, , A -Simplified @code{beginning-of-buffer} Definition}.) -This section describes the complex part of the definition. - -As previously described, when invoked without an argument, -@code{beginning-of-buffer} moves the cursor to the beginning of the -buffer (in truth, the beginning of the accessible portion of the -buffer), leaving the mark at the previous position. However, when the -command is invoked with a number between one and ten, the function -considers that number to be a fraction of the length of the buffer, -measured in tenths, and Emacs moves the cursor that fraction of the -way from the beginning of the buffer. Thus, you can either call this -function with the key command @kbd{M-<}, which will move the cursor to -the beginning of the buffer, or with a key command such as @kbd{C-u 7 -M-<} which will move the cursor to a point 70% of the way through the -buffer. If a number bigger than ten is used for the argument, it -moves to the end of the buffer. - -The @code{beginning-of-buffer} function can be called with or without an -argument. The use of the argument is optional. - -@menu -* Optional Arguments:: -* beginning-of-buffer opt arg:: Example with optional argument. -* beginning-of-buffer complete:: -@end menu - -@node Optional Arguments, beginning-of-buffer opt arg, beginning-of-buffer, beginning-of-buffer -@subsection Optional Arguments - -Unless told otherwise, Lisp expects that a function with an argument in -its function definition will be called with a value for that argument. -If that does not happen, you get an error and a message that says -@samp{Wrong number of arguments}. - -@cindex Optional arguments -@cindex Keyword -@findex optional -However, optional arguments are a feature of Lisp: a particular -@dfn{keyword} is used to tell the Lisp interpreter that an argument is -optional. The keyword is @code{&optional}. (The @samp{&} in front of -@samp{optional} is part of the keyword.) In a function definition, if -an argument follows the keyword @code{&optional}, no value need be -passed to that argument when the function is called. - -@need 1200 -The first line of the function definition of @code{beginning-of-buffer} -therefore looks like this: - -@smallexample -(defun beginning-of-buffer (&optional arg) -@end smallexample - -@need 1250 -In outline, the whole function looks like this: - -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "@var{documentation}@dots{}" - (interactive "P") - (or (@var{is-the-argument-a-cons-cell} arg) - (and @var{are-both-transient-mark-mode-and-mark-active-true}) - (push-mark)) - (let (@var{determine-size-and-set-it}) - (goto-char - (@var{if-there-is-an-argument} - @var{figure-out-where-to-go} - @var{else-go-to} - (point-min)))) - @var{do-nicety} -@end group -@end smallexample - -The function is similar to the @code{simplified-beginning-of-buffer} -function except that the @code{interactive} expression has @code{"P"} -as an argument and the @code{goto-char} function is followed by an -if-then-else expression that figures out where to put the cursor if -there is an argument that is not a cons cell. - -(Since I do not explain a cons cell for many more chapters, please -consider ignoring the function @code{consp}. @xref{List -Implementation, , How Lists are Implemented}, and @ref{Cons Cell Type, -, Cons Cell and List Types, elisp, The GNU Emacs Lisp Reference -Manual}.) - -The @code{"P"} in the @code{interactive} expression tells Emacs to -pass a prefix argument, if there is one, to the function in raw form. -A prefix argument is made by typing the @key{META} key followed by a -number, or by typing @kbd{C-u} and then a number. (If you don't type -a number, @kbd{C-u} defaults to a cons cell with a 4. A lowercase -@code{"p"} in the @code{interactive} expression causes the function to -convert a prefix arg to a number.) - -The true-or-false-test of the @code{if} expression looks complex, but -it is not: it checks whether @code{arg} has a value that is not -@code{nil} and whether it is a cons cell. (That is what @code{consp} -does; it checks whether its argument is a cons cell.) If @code{arg} -has a value that is not @code{nil} (and is not a cons cell), which -will be the case if @code{beginning-of-buffer} is called with a -numeric argument, then this true-or-false-test will return true and -the then-part of the @code{if} expression will be evaluated. On the -other hand, if @code{beginning-of-buffer} is not called with an -argument, the value of @code{arg} will be @code{nil} and the else-part -of the @code{if} expression will be evaluated. The else-part is -simply @code{point-min}, and when this is the outcome, the whole -@code{goto-char} expression is @code{(goto-char (point-min))}, which -is how we saw the @code{beginning-of-buffer} function in its -simplified form. - -@node beginning-of-buffer opt arg, beginning-of-buffer complete, Optional Arguments, beginning-of-buffer -@subsection @code{beginning-of-buffer} with an Argument - -When @code{beginning-of-buffer} is called with an argument, an -expression is evaluated which calculates what value to pass to -@code{goto-char}. This expression is rather complicated at first sight. -It includes an inner @code{if} expression and much arithmetic. It looks -like this: - -@smallexample -@group -(if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ size 10)) - (/ - (+ 10 - (* - size (prefix-numeric-value arg))) 10))) -@end group -@end smallexample - -@menu -* Disentangle beginning-of-buffer:: -* Large buffer case:: -* Small buffer case:: -@end menu - -@node Disentangle beginning-of-buffer, Large buffer case, beginning-of-buffer opt arg, beginning-of-buffer opt arg -@ifnottex -@unnumberedsubsubsec Disentangle @code{beginning-of-buffer} -@end ifnottex - -Like other complex-looking expressions, the conditional expression -within @code{beginning-of-buffer} can be disentangled by looking at it -as parts of a template, in this case, the template for an if-then-else -expression. In skeletal form, the expression looks like this: - -@smallexample -@group -(if (@var{buffer-is-large} - @var{divide-buffer-size-by-10-and-multiply-by-arg} - @var{else-use-alternate-calculation} -@end group -@end smallexample - -The true-or-false-test of this inner @code{if} expression checks the -size of the buffer. The reason for this is that the old version 18 -Emacs used numbers that are no bigger than eight million or so and in -the computation that followed, the programmer feared that Emacs might -try to use over-large numbers if the buffer were large. The term -`overflow', mentioned in the comment, means numbers that are over -large. More recent versions of Emacs use larger numbers, but this -code has not been touched, if only because people now look at buffers -that are far, far larger than ever before. - -There are two cases: if the buffer is large and if it is not. - -@node Large buffer case, Small buffer case, Disentangle beginning-of-buffer, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a large buffer - -In @code{beginning-of-buffer}, the inner @code{if} expression tests -whether the size of the buffer is greater than 10,000 characters. To do -this, it uses the @code{>} function and the computation of @code{size} -that comes from the let expression. - -In the old days, the function @code{buffer-size} was used. Not only -was that function called several times, it gave the size of the whole -buffer, not the accessible part. The computation makes much more -sense when it handles just the accessible part. (@xref{Narrowing & -Widening, , Narrowing and Widening}, for more information on focusing -attention to an `accessible' part.) - -@need 800 -The line looks like this: - -@smallexample -(if (> size 10000) -@end smallexample - -@need 1200 -@noindent -When the buffer is large, the then-part of the @code{if} expression is -evaluated. It reads like this (after formatting for easy reading): - -@smallexample -@group -(* - (prefix-numeric-value arg) - (/ size 10)) -@end group -@end smallexample - -@noindent -This expression is a multiplication, with two arguments to the function -@code{*}. - -The first argument is @code{(prefix-numeric-value arg)}. When -@code{"P"} is used as the argument for @code{interactive}, the value -passed to the function as its argument is passed a ``raw prefix -argument'', and not a number. (It is a number in a list.) To perform -the arithmetic, a conversion is necessary, and -@code{prefix-numeric-value} does the job. - -@findex / @r{(division)} -@cindex Division -The second argument is @code{(/ size 10)}. This expression divides -the numeric value by ten --- the numeric value of the size of the -accessible portion of the buffer. This produces a number that tells -how many characters make up one tenth of the buffer size. (In Lisp, -@code{/} is used for division, just as @code{*} is used for -multiplication.) - -@need 1200 -In the multiplication expression as a whole, this amount is multiplied -by the value of the prefix argument---the multiplication looks like this: - -@smallexample -@group -(* @var{numeric-value-of-prefix-arg} - @var{number-of-characters-in-one-tenth-of-the-accessible-buffer}) -@end group -@end smallexample - -@noindent -If, for example, the prefix argument is @samp{7}, the one-tenth value -will be multiplied by 7 to give a position 70% of the way through. - -@need 1200 -The result of all this is that if the accessible portion of the buffer -is large, the @code{goto-char} expression reads like this: - -@smallexample -@group -(goto-char (* (prefix-numeric-value arg) - (/ size 10))) -@end group -@end smallexample - -This puts the cursor where we want it. - -@node Small buffer case, , Large buffer case, beginning-of-buffer opt arg -@comment node-name, next, previous, up -@unnumberedsubsubsec What happens in a small buffer - -If the buffer contains fewer than 10,000 characters, a slightly -different computation is performed. You might think this is not -necessary, since the first computation could do the job. However, in -a small buffer, the first method may not put the cursor on exactly the -desired line; the second method does a better job. - -@need 800 -The code looks like this: - -@c Keep this on one line. -@smallexample -(/ (+ 10 (* size (prefix-numeric-value arg))) 10)) -@end smallexample - -@need 1200 -@noindent -This is code in which you figure out what happens by discovering how the -functions are embedded in parentheses. It is easier to read if you -reformat it with each expression indented more deeply than its -enclosing expression: - -@smallexample -@group - (/ - (+ 10 - (* - size - (prefix-numeric-value arg))) - 10)) -@end group -@end smallexample - -@need 1200 -@noindent -Looking at parentheses, we see that the innermost operation is -@code{(prefix-numeric-value arg)}, which converts the raw argument to -a number. In the following expression, this number is multiplied by -the size of the accessible portion of the buffer: - -@smallexample -(* size (prefix-numeric-value arg)) -@end smallexample - -@noindent -This multiplication creates a number that may be larger than the size of -the buffer---seven times larger if the argument is 7, for example. Ten -is then added to this number and finally the large number is divided by -ten to provide a value that is one character larger than the percentage -position in the buffer. - -The number that results from all this is passed to @code{goto-char} and -the cursor is moved to that point. - -@need 1500 -@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer -@comment node-name, next, previous, up -@subsection The Complete @code{beginning-of-buffer} - -@need 1000 -Here is the complete text of the @code{beginning-of-buffer} function: -@sp 1 - -@c In GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With \\[universal-argument] prefix, -do not set mark at previous position. -With numeric arg N, -put point N/10 of the way from the beginning. - -If the buffer is narrowed, -this command uses the beginning and size -of the accessible part of the buffer. -@end group - -@group -Don't use this command in Lisp programs! -\(goto-char (point-min)) is faster -and avoids clobbering the mark." - (interactive "P") - (or (consp arg) - (and transient-mark-mode mark-active) - (push-mark)) -@end group -@group - (let ((size (- (point-max) (point-min)))) - (goto-char (if (and arg (not (consp arg))) - (+ (point-min) - (if (> size 10000) - ;; Avoid overflow for large buffer sizes! - (* (prefix-numeric-value arg) - (/ size 10)) - (/ (+ 10 (* size (prefix-numeric-value arg))) - 10))) - (point-min)))) - (if arg (forward-line 1))) -@end group -@end smallexample - -@ignore -From before GNU Emacs 22 -@smallexample -@group -(defun beginning-of-buffer (&optional arg) - "Move point to the beginning of the buffer; -leave mark at previous position. -With arg N, put point N/10 of the way -from the true beginning. -@end group -@group -Don't use this in Lisp programs! -\(goto-char (point-min)) is faster -and does not set the mark." - (interactive "P") - (push-mark) -@end group -@group - (goto-char - (if arg - (if (> (buffer-size) 10000) - ;; @r{Avoid overflow for large buffer sizes!} - (* (prefix-numeric-value arg) - (/ (buffer-size) 10)) -@end group -@group - (/ (+ 10 (* (buffer-size) - (prefix-numeric-value arg))) - 10)) - (point-min))) - (if arg (forward-line 1))) -@end group -@end smallexample -@end ignore - -@noindent -Except for two small points, the previous discussion shows how this -function works. The first point deals with a detail in the -documentation string, and the second point concerns the last line of -the function. - -@need 800 -In the documentation string, there is reference to an expression: - -@smallexample -\\[universal-argument] -@end smallexample - -@noindent -A @samp{\\} is used before the first square bracket of this -expression. This @samp{\\} tells the Lisp interpreter to substitute -whatever key is currently bound to the @samp{[@dots{}]}. In the case -of @code{universal-argument}, that is usually @kbd{C-u}, but it might -be different. (@xref{Documentation Tips, , Tips for Documentation -Strings, elisp, The GNU Emacs Lisp Reference Manual}, for more -information.) - -@need 1200 -Finally, the last line of the @code{beginning-of-buffer} command says -to move point to the beginning of the next line if the command is -invoked with an argument: - -@smallexample -(if arg (forward-line 1))) -@end smallexample - -@noindent -This puts the cursor at the beginning of the first line after the -appropriate tenths position in the buffer. This is a flourish that -means that the cursor is always located @emph{at least} the requested -tenths of the way through the buffer, which is a nicety that is, -perhaps, not necessary, but which, if it did not occur, would be sure -to draw complaints. - -On the other hand, it also means that if you specify the command with -a @kbd{C-u}, but without a number, that is to say, if the `raw prefix -argument' is simply a cons cell, then the command puts you at the -beginning of the second line @dots{} I don't know whether this is -intended or whether no one has dealt with the code to avoid this -happening. - -@node Second Buffer Related Review, optional Exercise, beginning-of-buffer, More Complex -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some of the topics covered in this chapter. - -@table @code -@item or -Evaluate each argument in sequence, and return the value of the first -argument that is not @code{nil}; if none return a value that is not -@code{nil}, return @code{nil}. In brief, return the first true value -of the arguments; return a true value if one @emph{or} any of the -others are true. - -@item and -Evaluate each argument in sequence, and if any are @code{nil}, return -@code{nil}; if none are @code{nil}, return the value of the last -argument. In brief, return a true value only if all the arguments are -true; return a true value if one @emph{and} each of the others is -true. - -@item &optional -A keyword used to indicate that an argument to a function definition -is optional; this means that the function can be evaluated without the -argument, if desired. - -@item prefix-numeric-value -Convert the `raw prefix argument' produced by @code{(interactive -"P")} to a numeric value. - -@item forward-line -Move point forward to the beginning of the next line, or if the argument -is greater than one, forward that many lines. If it can't move as far -forward as it is supposed to, @code{forward-line} goes forward as far as -it can and then returns a count of the number of additional lines it was -supposed to move but couldn't. - -@item erase-buffer -Delete the entire contents of the current buffer. - -@item bufferp -Return @code{t} if its argument is a buffer; otherwise return @code{nil}. -@end table - -@node optional Exercise, , Second Buffer Related Review, More Complex -@section @code{optional} Argument Exercise - -Write an interactive function with an optional argument that tests -whether its argument, a number, is greater than or equal to, or else, -less than the value of @code{fill-column}, and tells you which, in a -message. However, if you do not pass an argument to the function, use -56 as a default value. - -@node Narrowing & Widening, car cdr & cons, More Complex, Top -@comment node-name, next, previous, up -@chapter Narrowing and Widening -@cindex Focusing attention (narrowing) -@cindex Narrowing -@cindex Widening - -Narrowing is a feature of Emacs that makes it possible for you to focus -on a specific part of a buffer, and work without accidentally changing -other parts. Narrowing is normally disabled since it can confuse -novices. - -@menu -* Narrowing advantages:: The advantages of narrowing -* save-restriction:: The @code{save-restriction} special form. -* what-line:: The number of the line that point is on. -* narrow Exercise:: -@end menu - -@node Narrowing advantages, save-restriction, Narrowing & Widening, Narrowing & Widening -@ifnottex -@unnumberedsec The Advantages of Narrowing -@end ifnottex - -With narrowing, the rest of a buffer is made invisible, as if it weren't -there. This is an advantage if, for example, you want to replace a word -in one part of a buffer but not in another: you narrow to the part you want -and the replacement is carried out only in that section, not in the rest -of the buffer. Searches will only work within a narrowed region, not -outside of one, so if you are fixing a part of a document, you can keep -yourself from accidentally finding parts you do not need to fix by -narrowing just to the region you want. -(The key binding for @code{narrow-to-region} is @kbd{C-x n n}.) - -However, narrowing does make the rest of the buffer invisible, which -can scare people who inadvertently invoke narrowing and think they -have deleted a part of their file. Moreover, the @code{undo} command -(which is usually bound to @kbd{C-x u}) does not turn off narrowing -(nor should it), so people can become quite desperate if they do not -know that they can return the rest of a buffer to visibility with the -@code{widen} command. -(The key binding for @code{widen} is @kbd{C-x n w}.) - -Narrowing is just as useful to the Lisp interpreter as to a human. -Often, an Emacs Lisp function is designed to work on just part of a -buffer; or conversely, an Emacs Lisp function needs to work on all of a -buffer that has been narrowed. The @code{what-line} function, for -example, removes the narrowing from a buffer, if it has any narrowing -and when it has finished its job, restores the narrowing to what it was. -On the other hand, the @code{count-lines} function, which is called by -@code{what-line}, uses narrowing to restrict itself to just that portion -of the buffer in which it is interested and then restores the previous -situation. - -@node save-restriction, what-line, Narrowing advantages, Narrowing & Widening -@comment node-name, next, previous, up -@section The @code{save-restriction} Special Form -@findex save-restriction - -In Emacs Lisp, you can use the @code{save-restriction} special form to -keep track of whatever narrowing is in effect, if any. When the Lisp -interpreter meets with @code{save-restriction}, it executes the code -in the body of the @code{save-restriction} expression, and then undoes -any changes to narrowing that the code caused. If, for example, the -buffer is narrowed and the code that follows @code{save-restriction} -gets rid of the narrowing, @code{save-restriction} returns the buffer -to its narrowed region afterwards. In the @code{what-line} command, -any narrowing the buffer may have is undone by the @code{widen} -command that immediately follows the @code{save-restriction} command. -Any original narrowing is restored just before the completion of the -function. - -@need 1250 -The template for a @code{save-restriction} expression is simple: - -@smallexample -@group -(save-restriction - @var{body}@dots{} ) -@end group -@end smallexample - -@noindent -The body of the @code{save-restriction} is one or more expressions that -will be evaluated in sequence by the Lisp interpreter. - -Finally, a point to note: when you use both @code{save-excursion} and -@code{save-restriction}, one right after the other, you should use -@code{save-excursion} outermost. If you write them in reverse order, -you may fail to record narrowing in the buffer to which Emacs switches -after calling @code{save-excursion}. Thus, when written together, -@code{save-excursion} and @code{save-restriction} should be written -like this: - -@smallexample -@group -(save-excursion - (save-restriction - @var{body}@dots{})) -@end group -@end smallexample - -In other circumstances, when not written together, the -@code{save-excursion} and @code{save-restriction} special forms must -be written in the order appropriate to the function. - -@need 1250 -For example, - -@smallexample -@group - (save-restriction - (widen) - (save-excursion - @var{body}@dots{})) -@end group -@end smallexample - -@ignore -Emacs 22 -/usr/local/src/emacs/lisp/simple.el - -(defun what-line () - "Print the current buffer line number and narrowed line number of point." - (interactive) - (let ((start (point-min)) - (n (line-number-at-pos))) - (if (= start 1) - (message "Line %d" n) - (save-excursion - (save-restriction - (widen) - (message "line %d (narrowed line %d)" - (+ n (line-number-at-pos start) -1) n)))))) - -(defun line-number-at-pos (&optional pos) - "Return (narrowed) buffer line number at position POS. -If POS is nil, use current buffer location. -Counting starts at (point-min), so the value refers -to the contents of the accessible portion of the buffer." - (let ((opoint (or pos (point))) start) - (save-excursion - (goto-char (point-min)) - (setq start (point)) - (goto-char opoint) - (forward-line 0) - (1+ (count-lines start (point)))))) - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@node what-line, narrow Exercise, save-restriction, Narrowing & Widening -@comment node-name, next, previous, up -@section @code{what-line} -@findex what-line -@cindex Widening, example of - -The @code{what-line} command tells you the number of the line in which -the cursor is located. The function illustrates the use of the -@code{save-restriction} and @code{save-excursion} commands. Here is the -original text of the function: - -@smallexample -@group -(defun what-line () - "Print the current line number (in the buffer) of point." - (interactive) - (save-restriction - (widen) - (save-excursion - (beginning-of-line) - (message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -(In recent versions of GNU Emacs, the @code{what-line} function has -been expanded to tell you your line number in a narrowed buffer as -well as your line number in a widened buffer. The recent version is -more complex than the version shown here. If you feel adventurous, -you might want to look at it after figuring out how this version -works. You will probably need to use @kbd{C-h f} -(@code{describe-function}). The newer version uses a conditional to -determine whether the buffer has been narrowed. - -(Also, it uses @code{line-number-at-pos}, which among other simple -expressions, such as @code{(goto-char (point-min))}, moves point to -the beginning of the current line with @code{(forward-line 0)} rather -than @code{beginning-of-line}.) - -The @code{what-line} function as shown here has a documentation line -and is interactive, as you would expect. The next two lines use the -functions @code{save-restriction} and @code{widen}. - -The @code{save-restriction} special form notes whatever narrowing is in -effect, if any, in the current buffer and restores that narrowing after -the code in the body of the @code{save-restriction} has been evaluated. - -The @code{save-restriction} special form is followed by @code{widen}. -This function undoes any narrowing the current buffer may have had -when @code{what-line} was called. (The narrowing that was there is -the narrowing that @code{save-restriction} remembers.) This widening -makes it possible for the line counting commands to count from the -beginning of the buffer. Otherwise, they would have been limited to -counting within the accessible region. Any original narrowing is -restored just before the completion of the function by the -@code{save-restriction} special form. - -The call to @code{widen} is followed by @code{save-excursion}, which -saves the location of the cursor (i.e., of point) and of the mark, and -restores them after the code in the body of the @code{save-excursion} -uses the @code{beginning-of-line} function to move point. - -(Note that the @code{(widen)} expression comes between the -@code{save-restriction} and @code{save-excursion} special forms. When -you write the two @code{save- @dots{}} expressions in sequence, write -@code{save-excursion} outermost.) - -@need 1200 -The last two lines of the @code{what-line} function are functions to -count the number of lines in the buffer and then print the number in the -echo area. - -@smallexample -@group -(message "Line %d" - (1+ (count-lines 1 (point))))))) -@end group -@end smallexample - -The @code{message} function prints a one-line message at the bottom of -the Emacs screen. The first argument is inside of quotation marks and -is printed as a string of characters. However, it may contain a -@samp{%d} expression to print a following argument. @samp{%d} prints -the argument as a decimal, so the message will say something such as -@samp{Line 243}. - -@need 1200 -The number that is printed in place of the @samp{%d} is computed by the -last line of the function: - -@smallexample -(1+ (count-lines 1 (point))) -@end smallexample - -@ignore -GNU Emacs 22 - -(defun count-lines (start end) - "Return number of lines between START and END. -This is usually the number of newlines between them, -but can be one more if START is not equal to END -and the greater of them is not at the start of a line." - (save-excursion - (save-restriction - (narrow-to-region start end) - (goto-char (point-min)) - (if (eq selective-display t) - (save-match-data - (let ((done 0)) - (while (re-search-forward "[\n\C-m]" nil t 40) - (setq done (+ 40 done))) - (while (re-search-forward "[\n\C-m]" nil t 1) - (setq done (+ 1 done))) - (goto-char (point-max)) - (if (and (/= start end) - (not (bolp))) - (1+ done) - done))) - (- (buffer-size) (forward-line (buffer-size))))))) -@end ignore - -@noindent -What this does is count the lines from the first position of the -buffer, indicated by the @code{1}, up to @code{(point)}, and then add -one to that number. (The @code{1+} function adds one to its -argument.) We add one to it because line 2 has only one line before -it, and @code{count-lines} counts only the lines @emph{before} the -current line. - -After @code{count-lines} has done its job, and the message has been -printed in the echo area, the @code{save-excursion} restores point and -mark to their original positions; and @code{save-restriction} restores -the original narrowing, if any. - -@node narrow Exercise, , what-line, Narrowing & Widening -@section Exercise with Narrowing - -Write a function that will display the first 60 characters of the -current buffer, even if you have narrowed the buffer to its latter -half so that the first line is inaccessible. Restore point, mark, and -narrowing. For this exercise, you need to use a whole potpourri of -functions, including @code{save-restriction}, @code{widen}, -@code{goto-char}, @code{point-min}, @code{message}, and -@code{buffer-substring}. - -@cindex Properties, mention of @code{buffer-substring-no-properties} -(@code{buffer-substring} is a previously unmentioned function you will -have to investigate yourself; or perhaps you will have to use -@code{buffer-substring-no-properties} or -@code{filter-buffer-substring} @dots{}, yet other functions. Text -properties are a feature otherwise not discussed here. @xref{Text -Properties, , Text Properties, elisp, The GNU Emacs Lisp Reference -Manual}.) - -Additionally, do you really need @code{goto-char} or @code{point-min}? -Or can you write the function without them? - -@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top -@comment node-name, next, previous, up -@chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions -@findex car, @r{introduced} -@findex cdr, @r{introduced} - -In Lisp, @code{car}, @code{cdr}, and @code{cons} are fundamental -functions. The @code{cons} function is used to construct lists, and -the @code{car} and @code{cdr} functions are used to take them apart. - -In the walk through of the @code{copy-region-as-kill} function, we -will see @code{cons} as well as two variants on @code{cdr}, -namely, @code{setcdr} and @code{nthcdr}. (@xref{copy-region-as-kill}.) - -@menu -* Strange Names:: An historical aside: why the strange names? -* car & cdr:: Functions for extracting part of a list. -* cons:: Constructing a list. -* nthcdr:: Calling @code{cdr} repeatedly. -* nth:: -* setcar:: Changing the first element of a list. -* setcdr:: Changing the rest of a list. -* cons Exercise:: -@end menu - -@node Strange Names, car & cdr, car cdr & cons, car cdr & cons -@ifnottex -@unnumberedsec Strange Names -@end ifnottex - -The name of the @code{cons} function is not unreasonable: it is an -abbreviation of the word `construct'. The origins of the names for -@code{car} and @code{cdr}, on the other hand, are esoteric: @code{car} -is an acronym from the phrase `Contents of the Address part of the -Register'; and @code{cdr} (pronounced `could-er') is an acronym from -the phrase `Contents of the Decrement part of the Register'. These -phrases refer to specific pieces of hardware on the very early -computer on which the original Lisp was developed. Besides being -obsolete, the phrases have been completely irrelevant for more than 25 -years to anyone thinking about Lisp. Nonetheless, although a few -brave scholars have begun to use more reasonable names for these -functions, the old terms are still in use. In particular, since the -terms are used in the Emacs Lisp source code, we will use them in this -introduction. - -@node car & cdr, cons, Strange Names, car cdr & cons -@comment node-name, next, previous, up -@section @code{car} and @code{cdr} - -The @sc{car} of a list is, quite simply, the first item in the list. -Thus the @sc{car} of the list @code{(rose violet daisy buttercup)} is -@code{rose}. - -@need 1200 -If you are reading this in Info in GNU Emacs, you can see this by -evaluating the following: - -@smallexample -(car '(rose violet daisy buttercup)) -@end smallexample - -@noindent -After evaluating the expression, @code{rose} will appear in the echo -area. - -Clearly, a more reasonable name for the @code{car} function would be -@code{first} and this is often suggested. - -@code{car} does not remove the first item from the list; it only reports -what it is. After @code{car} has been applied to a list, the list is -still the same as it was. In the jargon, @code{car} is -`non-destructive'. This feature turns out to be important. - -The @sc{cdr} of a list is the rest of the list, that is, the -@code{cdr} function returns the part of the list that follows the -first item. Thus, while the @sc{car} of the list @code{'(rose violet -daisy buttercup)} is @code{rose}, the rest of the list, the value -returned by the @code{cdr} function, is @code{(violet daisy -buttercup)}. - -@need 800 -You can see this by evaluating the following in the usual way: - -@smallexample -(cdr '(rose violet daisy buttercup)) -@end smallexample - -@noindent -When you evaluate this, @code{(violet daisy buttercup)} will appear in -the echo area. - -Like @code{car}, @code{cdr} does not remove any elements from the -list---it just returns a report of what the second and subsequent -elements are. - -Incidentally, in the example, the list of flowers is quoted. If it were -not, the Lisp interpreter would try to evaluate the list by calling -@code{rose} as a function. In this example, we do not want to do that. - -Clearly, a more reasonable name for @code{cdr} would be @code{rest}. - -(There is a lesson here: when you name new functions, consider very -carefully what you are doing, since you may be stuck with the names -for far longer than you expect. The reason this document perpetuates -these names is that the Emacs Lisp source code uses them, and if I did -not use them, you would have a hard time reading the code; but do, -please, try to avoid using these terms yourself. The people who come -after you will be grateful to you.) - -When @code{car} and @code{cdr} are applied to a list made up of symbols, -such as the list @code{(pine fir oak maple)}, the element of the list -returned by the function @code{car} is the symbol @code{pine} without -any parentheses around it. @code{pine} is the first element in the -list. However, the @sc{cdr} of the list is a list itself, @code{(fir -oak maple)}, as you can see by evaluating the following expressions in -the usual way: - -@smallexample -@group -(car '(pine fir oak maple)) - -(cdr '(pine fir oak maple)) -@end group -@end smallexample - -On the other hand, in a list of lists, the first element is itself a -list. @code{car} returns this first element as a list. For example, -the following list contains three sub-lists, a list of carnivores, a -list of herbivores and a list of sea mammals: - -@smallexample -@group -(car '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -@noindent -In this example, the first element or @sc{car} of the list is the list of -carnivores, @code{(lion tiger cheetah)}, and the rest of the list is -@code{((gazelle antelope zebra) (whale dolphin seal))}. - -@smallexample -@group -(cdr '((lion tiger cheetah) - (gazelle antelope zebra) - (whale dolphin seal))) -@end group -@end smallexample - -It is worth saying again that @code{car} and @code{cdr} are -non-destructive---that is, they do not modify or change lists to which -they are applied. This is very important for how they are used. - -Also, in the first chapter, in the discussion about atoms, I said that -in Lisp, ``certain kinds of atom, such as an array, can be separated -into parts; but the mechanism for doing this is different from the -mechanism for splitting a list. As far as Lisp is concerned, the -atoms of a list are unsplittable.'' (@xref{Lisp Atoms}.) The -@code{car} and @code{cdr} functions are used for splitting lists and -are considered fundamental to Lisp. Since they cannot split or gain -access to the parts of an array, an array is considered an atom. -Conversely, the other fundamental function, @code{cons}, can put -together or construct a list, but not an array. (Arrays are handled -by array-specific functions. @xref{Arrays, , Arrays, elisp, The GNU -Emacs Lisp Reference Manual}.) - -@node cons, nthcdr, car & cdr, car cdr & cons -@comment node-name, next, previous, up -@section @code{cons} -@findex cons, @r{introduced} - -The @code{cons} function constructs lists; it is the inverse of -@code{car} and @code{cdr}. For example, @code{cons} can be used to make -a four element list from the three element list, @code{(fir oak maple)}: - -@smallexample -(cons 'pine '(fir oak maple)) -@end smallexample - -@need 800 -@noindent -After evaluating this list, you will see - -@smallexample -(pine fir oak maple) -@end smallexample - -@noindent -appear in the echo area. @code{cons} causes the creation of a new -list in which the element is followed by the elements of the original -list. - -We often say that `@code{cons} puts a new element at the beginning of -a list; it attaches or pushes elements onto the list', but this -phrasing can be misleading, since @code{cons} does not change an -existing list, but creates a new one. - -Like @code{car} and @code{cdr}, @code{cons} is non-destructive. - -@menu -* Build a list:: -* length:: How to find the length of a list. -@end menu - -@node Build a list, length, cons, cons -@ifnottex -@unnumberedsubsec Build a list -@end ifnottex - -@code{cons} must have a list to attach to.@footnote{Actually, you can -@code{cons} an element to an atom to produce a dotted pair. Dotted -pairs are not discussed here; see @ref{Dotted Pair Notation, , Dotted -Pair Notation, elisp, The GNU Emacs Lisp Reference Manual}.} You -cannot start from absolutely nothing. If you are building a list, you -need to provide at least an empty list at the beginning. Here is a -series of @code{cons} expressions that build up a list of flowers. If -you are reading this in Info in GNU Emacs, you can evaluate each of -the expressions in the usual way; the value is printed in this text -after @samp{@result{}}, which you may read as `evaluates to'. - -@smallexample -@group -(cons 'buttercup ()) - @result{} (buttercup) -@end group - -@group -(cons 'daisy '(buttercup)) - @result{} (daisy buttercup) -@end group - -@group -(cons 'violet '(daisy buttercup)) - @result{} (violet daisy buttercup) -@end group - -@group -(cons 'rose '(violet daisy buttercup)) - @result{} (rose violet daisy buttercup) -@end group -@end smallexample - -@noindent -In the first example, the empty list is shown as @code{()} and a list -made up of @code{buttercup} followed by the empty list is constructed. -As you can see, the empty list is not shown in the list that was -constructed. All that you see is @code{(buttercup)}. The empty list is -not counted as an element of a list because there is nothing in an empty -list. Generally speaking, an empty list is invisible. - -The second example, @code{(cons 'daisy '(buttercup))} constructs a new, -two element list by putting @code{daisy} in front of @code{buttercup}; -and the third example constructs a three element list by putting -@code{violet} in front of @code{daisy} and @code{buttercup}. - -@node length, , Build a list, cons -@comment node-name, next, previous, up -@subsection Find the Length of a List: @code{length} -@findex length - -You can find out how many elements there are in a list by using the Lisp -function @code{length}, as in the following examples: - -@smallexample -@group -(length '(buttercup)) - @result{} 1 -@end group - -@group -(length '(daisy buttercup)) - @result{} 2 -@end group - -@group -(length (cons 'violet '(daisy buttercup))) - @result{} 3 -@end group -@end smallexample - -@noindent -In the third example, the @code{cons} function is used to construct a -three element list which is then passed to the @code{length} function as -its argument. - -@need 1200 -We can also use @code{length} to count the number of elements in an -empty list: - -@smallexample -@group -(length ()) - @result{} 0 -@end group -@end smallexample - -@noindent -As you would expect, the number of elements in an empty list is zero. - -An interesting experiment is to find out what happens if you try to find -the length of no list at all; that is, if you try to call @code{length} -without giving it an argument, not even an empty list: - -@smallexample -(length ) -@end smallexample - -@need 800 -@noindent -What you see, if you evaluate this, is the error message - -@smallexample -Lisp error: (wrong-number-of-arguments length 0) -@end smallexample - -@noindent -This means that the function receives the wrong number of -arguments, zero, when it expects some other number of arguments. In -this case, one argument is expected, the argument being a list whose -length the function is measuring. (Note that @emph{one} list is -@emph{one} argument, even if the list has many elements inside it.) - -The part of the error message that says @samp{length} is the name of -the function. - -@ignore -@code{length} is still a subroutine, but you need C-h f to discover that. - -In an earlier version: - This is written with a special notation, @samp{# (length string) 0) - (if yank-handler - (put-text-property 0 (length string) - 'yank-handler yank-handler string)) - (if yank-handler - (signal 'args-out-of-range - (list string "yank-handler specified for empty string")))) -@end group -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@group - (if (and replace kill-ring) - (setcar kill-ring string) - (push string kill-ring) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample -@ignore -was: -(defun kill-new (string &optional replace) - "Make STRING the latest kill in the kill ring. -Set the kill-ring-yank pointer to point to it. -If `interprogram-cut-function' is non-nil, apply it to STRING. -Optional second argument REPLACE non-nil means that STRING will replace -the front of the kill ring, rather than being added to the list." - (and (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) - (if (and replace kill-ring) - (setcar kill-ring string) - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end ignore - -(Notice that the function is not interactive.) - -As usual, we can look at this function in parts. - -The function definition has an optional @code{yank-handler} argument, -which when invoked tells the function how to deal with properties -added to the text, such as `bold' or `italics'. We will skip that. - -@need 1200 -The first line of the documentation makes sense: - -@smallexample -Make STRING the latest kill in the kill ring. -@end smallexample - -@noindent -Let's skip over the rest of the documentation for the moment. - -@noindent -Also, let's skip over the initial @code{if} expression and those lines -of code involving @code{menu-bar-update-yank-menu}. We will explain -them below. - -@need 1200 -The critical lines are these: - -@smallexample -@group - (if (and replace kill-ring) - ;; @r{then} - (setcar kill-ring string) -@end group -@group - ;; @r{else} - (push string kill-ring) -@end group -@group - (setq kill-ring (cons string kill-ring)) - (if (> (length kill-ring) kill-ring-max) - ;; @r{avoid overly long kill ring} - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) -@end group -@group - (setq kill-ring-yank-pointer kill-ring) - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -The conditional test is @w{@code{(and replace kill-ring)}}. -This will be true when two conditions are met: the kill ring has -something in it, and the @code{replace} variable is true. - -@need 1250 -When the @code{kill-append} function sets @code{replace} to be true -and when the kill ring has at least one item in it, the @code{setcar} -expression is executed: - -@smallexample -(setcar kill-ring string) -@end smallexample - -The @code{setcar} function actually changes the first element of the -@code{kill-ring} list to the value of @code{string}. It replaces the -first element. - -@need 1250 -On the other hand, if the kill ring is empty, or replace is false, the -else-part of the condition is executed: - -@smallexample -(push string kill-ring) -@end smallexample - -@noindent -@need 1250 -@code{push} puts its first argument onto the second. It is similar to -the older - -@smallexample -(setq kill-ring (cons string kill-ring)) -@end smallexample - -@noindent -@need 1250 -or the newer - -@smallexample -(add-to-list kill-ring string) -@end smallexample - -@noindent -When it is false, the expression first constructs a new version of the -kill ring by prepending @code{string} to the existing kill ring as a -new element (that is what the @code{push} does). Then it executes a -second @code{if} clause. This second @code{if} clause keeps the kill -ring from growing too long. - -Let's look at these two expressions in order. - -The @code{push} line of the else-part sets the new value of the kill -ring to what results from adding the string being killed to the old -kill ring. - -We can see how this works with an example. - -@need 800 -First, - -@smallexample -(setq example-list '("here is a clause" "another clause")) -@end smallexample - -@need 1200 -@noindent -After evaluating this expression with @kbd{C-x C-e}, you can evaluate -@code{example-list} and see what it returns: - -@smallexample -@group -example-list - @result{} ("here is a clause" "another clause") -@end group -@end smallexample - -@need 1200 -@noindent -Now, we can add a new element on to this list by evaluating the -following expression: -@findex push, @r{example} - -@smallexample -(push "a third clause" example-list) -@end smallexample - -@need 800 -@noindent -When we evaluate @code{example-list}, we find its value is: - -@smallexample -@group -example-list - @result{} ("a third clause" "here is a clause" "another clause") -@end group -@end smallexample - -@noindent -Thus, the third clause is added to the list by @code{push}. - -@need 1200 -Now for the second part of the @code{if} clause. This expression -keeps the kill ring from growing too long. It looks like this: - -@smallexample -@group -(if (> (length kill-ring) kill-ring-max) - (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)) -@end group -@end smallexample - -The code checks whether the length of the kill ring is greater than -the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the -kill ring is too long, then this code sets the last element of the -kill ring to @code{nil}. It does this by using two functions, -@code{nthcdr} and @code{setcdr}. - -We looked at @code{setcdr} earlier (@pxref{setcdr, , @code{setcdr}}). -It sets the @sc{cdr} of a list, just as @code{setcar} sets the -@sc{car} of a list. In this case, however, @code{setcdr} will not be -setting the @sc{cdr} of the whole kill ring; the @code{nthcdr} -function is used to cause it to set the @sc{cdr} of the next to last -element of the kill ring---this means that since the @sc{cdr} of the -next to last element is the last element of the kill ring, it will set -the last element of the kill ring. - -@findex nthcdr, @r{example} -The @code{nthcdr} function works by repeatedly taking the @sc{cdr} of a -list---it takes the @sc{cdr} of the @sc{cdr} of the @sc{cdr} -@dots{} It does this @var{N} times and returns the results. -(@xref{nthcdr, , @code{nthcdr}}.) - -@findex setcdr, @r{example} -Thus, if we had a four element list that was supposed to be three -elements long, we could set the @sc{cdr} of the next to last element -to @code{nil}, and thereby shorten the list. (If you set the last -element to some other value than @code{nil}, which you could do, then -you would not have shortened the list. @xref{setcdr, , -@code{setcdr}}.) - -You can see shortening by evaluating the following three expressions -in turn. First set the value of @code{trees} to @code{(maple oak pine -birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} -and then find the value of @code{trees}: - -@smallexample -@group -(setq trees '(maple oak pine birch)) - @result{} (maple oak pine birch) -@end group - -@group -(setcdr (nthcdr 2 trees) nil) - @result{} nil - -trees - @result{} (maple oak pine) -@end group -@end smallexample - -@noindent -(The value returned by the @code{setcdr} expression is @code{nil} since -that is what the @sc{cdr} is set to.) - -To repeat, in @code{kill-new}, the @code{nthcdr} function takes the -@sc{cdr} a number of times that is one less than the maximum permitted -size of the kill ring and @code{setcdr} sets the @sc{cdr} of that -element (which will be the rest of the elements in the kill ring) to -@code{nil}. This prevents the kill ring from growing too long. - -@need 800 -The next to last expression in the @code{kill-new} function is - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -The @code{kill-ring-yank-pointer} is a global variable that is set to be -the @code{kill-ring}. - -Even though the @code{kill-ring-yank-pointer} is called a -@samp{pointer}, it is a variable just like the kill ring. However, the -name has been chosen to help humans understand how the variable is used. - -@need 1200 -Now, to return to an early expression in the body of the function: - -@smallexample -@group - (if (fboundp 'menu-bar-update-yank-menu) - (menu-bar-update-yank-menu string (and replace (car kill-ring)))) -@end group -@end smallexample - -@noindent -It starts with an @code{if} expression - -In this case, the expression tests first to see whether -@code{menu-bar-update-yank-menu} exists as a function, and if so, -calls it. The @code{fboundp} function returns true if the symbol it -is testing has a function definition that `is not void'. If the -symbol's function definition were void, we would receive an error -message, as we did when we created errors intentionally (@pxref{Making -Errors, , Generate an Error Message}). - -@noindent -The then-part contains an expression whose first element is the -function @code{and}. - -@findex and -The @code{and} special form evaluates each of its arguments until one -of the arguments returns a value of @code{nil}, in which case the -@code{and} expression returns @code{nil}; however, if none of the -arguments returns a value of @code{nil}, the value resulting from -evaluating the last argument is returned. (Since such a value is not -@code{nil}, it is considered true in Emacs Lisp.) In other words, an -@code{and} expression returns a true value only if all its arguments -are true. (@xref{Second Buffer Related Review}.) - -The expression determines whether the second argument to -@code{menu-bar-update-yank-menu} is true or not. -@ignore - ;; If we're supposed to be extending an existing string, and that - ;; string really is at the front of the menu, then update it in place. -@end ignore - -@code{menu-bar-update-yank-menu} is one of the functions that make it -possible to use the `Select and Paste' menu in the Edit item of a menu -bar; using a mouse, you can look at the various pieces of text you -have saved and select one piece to paste. - -The last expression in the @code{kill-new} function adds the newly -copied string to whatever facility exists for copying and pasting -among different programs running in a windowing system. In the X -Windowing system, for example, the @code{x-select-text} function takes -the string and stores it in memory operated by X. You can paste the -string in another program, such as an Xterm. - -@need 1200 -The expression looks like this: - -@smallexample -@group - (if interprogram-cut-function - (funcall interprogram-cut-function string (not replace)))) -@end group -@end smallexample - -If an @code{interprogram-cut-function} exists, then Emacs executes -@code{funcall}, which in turn calls its first argument as a function -and passes the remaining arguments to it. (Incidentally, as far as I -can see, this @code{if} expression could be replaced by an @code{and} -expression similar to the one in the first part of the function.) - -We are not going to discuss windowing systems and other programs -further, but merely note that this is a mechanism that enables GNU -Emacs to work easily and well with other programs. - -This code for placing text in the kill ring, either concatenated with -an existing element or as a new element, leads us to the code for -bringing back text that has been cut out of the buffer---the yank -commands. However, before discussing the yank commands, it is better -to learn how lists are implemented in a computer. This will make -clear such mysteries as the use of the term `pointer'. But before -that, we will digress into C. - -@ignore -@c is this true in Emacs 22? Does not seems to be - - (If the @w{@code{(< end beg))}} -expression is true, @code{kill-append} prepends the string to the just -previously clipped text. For a detailed discussion, see -@ref{kill-append function, , The @code{kill-append} function}.) - -If you then yank back the text, i.e., `paste' it, you get both -pieces of text at once. That way, if you delete two words in a row, -and then yank them back, you get both words, in their proper order, -with one yank. (The @w{@code{(< end beg))}} expression makes sure the -order is correct.) - -On the other hand, if the previous command is not @code{kill-region}, -then the @code{kill-new} function is called, which adds the text to -the kill ring as the latest item, and sets the -@code{kill-ring-yank-pointer} variable to point to it. -@end ignore -@ignore - -@c Evidently, changed for Emacs 22. The zap-to-char command does not -@c use the delete-and-extract-region function - -2006 Oct 26, the Digression into C is now OK but should come after -copy-region-as-kill and filter-buffer-substring - -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} -@end ignore - -@node Digression into C, defvar, copy-region-as-kill, Cutting & Storing Text -@comment node-name, next, previous, up -@section Digression into C -@findex delete-and-extract-region -@cindex C, a digression into -@cindex Digression into C - -The @code{copy-region-as-kill} function (@pxref{copy-region-as-kill, , -@code{copy-region-as-kill}}) uses the @code{filter-buffer-substring} -function, which in turn uses the @code{delete-and-extract-region} -function. It removes the contents of a region and you cannot get them -back. - -Unlike the other code discussed here, the -@code{delete-and-extract-region} function is not written in Emacs -Lisp; it is written in C and is one of the primitives of the GNU Emacs -system. Since it is very simple, I will digress briefly from Lisp and -describe it here. - -@c GNU Emacs 22 in /usr/local/src/emacs/src/editfns.c -@c the DEFUN for buffer-substring-no-properties - -@need 1500 -Like many of the other Emacs primitives, -@code{delete-and-extract-region} is written as an instance of a C -macro, a macro being a template for code. The complete macro looks -like this: - -@smallexample -@group -DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties, - Sbuffer_substring_no_properties, 2, 2, 0, - doc: /* Return the characters of part of the buffer, -without the text properties. -The two arguments START and END are character positions; -they can be in either order. */) - (start, end) - Lisp_Object start, end; -@{ - register int b, e; - - validate_region (&start, &end); - b = XINT (start); - e = XINT (end); - - return make_buffer_string (b, e, 0); -@} -@end group -@end smallexample - -Without going into the details of the macro writing process, let me -point out that this macro starts with the word @code{DEFUN}. The word -@code{DEFUN} was chosen since the code serves the same purpose as -@code{defun} does in Lisp. (The @code{DEFUN} C macro is defined in -@file{emacs/src/lisp.h}.) - -The word @code{DEFUN} is followed by seven parts inside of -parentheses: - -@itemize @bullet -@item -The first part is the name given to the function in Lisp, -@code{delete-and-extract-region}. - -@item -The second part is the name of the function in C, -@code{Fdelete_and_extract_region}. By convention, it starts with -@samp{F}. Since C does not use hyphens in names, underscores are used -instead. - -@item -The third part is the name for the C constant structure that records -information on this function for internal use. It is the name of the -function in C but begins with an @samp{S} instead of an @samp{F}. - -@item -The fourth and fifth parts specify the minimum and maximum number of -arguments the function can have. This function demands exactly 2 -arguments. - -@item -The sixth part is nearly like the argument that follows the -@code{interactive} declaration in a function written in Lisp: a letter -followed, perhaps, by a prompt. The only difference from the Lisp is -when the macro is called with no arguments. Then you write a @code{0} -(which is a `null string'), as in this macro. - -If you were to specify arguments, you would place them between -quotation marks. The C macro for @code{goto-char} includes -@code{"NGoto char: "} in this position to indicate that the function -expects a raw prefix, in this case, a numerical location in a buffer, -and provides a prompt. - -@item -The seventh part is a documentation string, just like the one for a -function written in Emacs Lisp, except that every newline must be -written explicitly as @samp{\n} followed by a backslash and carriage -return. - -@need 1000 -Thus, the first two lines of documentation for @code{goto-char} are -written like this: - -@smallexample -@group - "Set point to POSITION, a number or marker.\n\ -Beginning of buffer is position (point-min), end is (point-max)." -@end group -@end smallexample -@end itemize - -@need 1200 -In a C macro, the formal parameters come next, with a statement of -what kind of object they are, followed by what might be called the `body' -of the macro. For @code{delete-and-extract-region} the `body' -consists of the following four lines: - -@smallexample -@group -validate_region (&start, &end); -if (XINT (start) == XINT (end)) - return build_string (""); -return del_range_1 (XINT (start), XINT (end), 1, 1); -@end group -@end smallexample - -The @code{validate_region} function checks whether the values -passed as the beginning and end of the region are the proper type and -are within range. If the beginning and end positions are the same, -then return and empty string. - -The @code{del_range_1} function actually deletes the text. It is a -complex function we will not look into. It updates the buffer and -does other things. However, it is worth looking at the two arguments -passed to @code{del_range}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. - -As far as the C language is concerned, @code{start} and @code{end} are -two integers that mark the beginning and end of the region to be -deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type `Lisp_Object', which can -also be a C union instead of an integer type.}. - -In early versions of Emacs, these two numbers were thirty-two bits -long, but the code is slowly being generalized to handle other -lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as `content'. - -@samp{XINT} is a C macro that extracts the relevant number from the -longer collection of bits; the three other bits are discarded. - -@need 800 -The command in @code{delete-and-extract-region} looks like this: - -@smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); -@end smallexample - -@noindent -It deletes the region between the beginning position, @code{start}, -and the ending position, @code{end}. - -From the point of view of the person writing Lisp, Emacs is all very -simple; but hidden underneath is a great deal of complexity to make it -all work. - -@node defvar, cons & search-fwd Review, Digression into C, Cutting & Storing Text -@comment node-name, next, previous, up -@section Initializing a Variable with @code{defvar} -@findex defvar -@cindex Initializing a variable -@cindex Variable initialization - -@ignore -2006 Oct 24 -In Emacs 22, -copy-region-as-kill is short, 12 lines, and uses -filter-buffer-substring, which is longer, 39 lines -and has delete-and-extract-region in it. -delete-and-extract-region is written in C. - -see Initializing a Variable with @code{defvar} - -@end ignore - -The @code{copy-region-as-kill} function is written in Emacs Lisp. Two -functions within it, @code{kill-append} and @code{kill-new}, copy a -region in a buffer and save it in a variable called the -@code{kill-ring}. This section describes how the @code{kill-ring} -variable is created and initialized using the @code{defvar} special -form. - -(Again we note that the term @code{kill-ring} is a misnomer. The text -that is clipped out of the buffer can be brought back; it is not a ring -of corpses, but a ring of resurrectable text.) - -In Emacs Lisp, a variable such as the @code{kill-ring} is created and -given an initial value by using the @code{defvar} special form. The -name comes from ``define variable''. - -The @code{defvar} special form is similar to @code{setq} in that it sets -the value of a variable. It is unlike @code{setq} in two ways: first, -it only sets the value of the variable if the variable does not already -have a value. If the variable already has a value, @code{defvar} does -not override the existing value. Second, @code{defvar} has a -documentation string. - -(Another special form, @code{defcustom}, is designed for variables -that people customize. It has more features than @code{defvar}. -(@xref{defcustom, , Setting Variables with @code{defcustom}}.) - -@menu -* See variable current value:: -* defvar and asterisk:: -@end menu - -@node See variable current value, defvar and asterisk, defvar, defvar -@ifnottex -@unnumberedsubsec Seeing the Current Value of a Variable -@end ifnottex - -You can see the current value of a variable, any variable, by using -the @code{describe-variable} function, which is usually invoked by -typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring} -(followed by @key{RET}) when prompted, you will see what is in your -current kill ring---this may be quite a lot! Conversely, if you have -been doing nothing this Emacs session except read this document, you -may have nothing in it. Also, you will see the documentation for -@code{kill-ring}: - -@smallexample -@group -Documentation: -List of killed text sequences. -Since the kill ring is supposed to interact nicely with cut-and-paste -facilities offered by window systems, use of this variable should -@end group -@group -interact nicely with `interprogram-cut-function' and -`interprogram-paste-function'. The functions `kill-new', -`kill-append', and `current-kill' are supposed to implement this -interaction; you may want to use them instead of manipulating the kill -ring directly. -@end group -@end smallexample - -@need 800 -The kill ring is defined by a @code{defvar} in the following way: - -@smallexample -@group -(defvar kill-ring nil - "List of killed text sequences. -@dots{}") -@end group -@end smallexample - -@noindent -In this variable definition, the variable is given an initial value of -@code{nil}, which makes sense, since if you have saved nothing, you want -nothing back if you give a @code{yank} command. The documentation -string is written just like the documentation string of a @code{defun}. -As with the documentation string of the @code{defun}, the first line of -the documentation should be a complete sentence, since some commands, -like @code{apropos}, print only the first line of documentation. -Succeeding lines should not be indented; otherwise they look odd when -you use @kbd{C-h v} (@code{describe-variable}). - -@node defvar and asterisk, , See variable current value, defvar -@subsection @code{defvar} and an asterisk -@findex defvar @r{for a user customizable variable} -@findex defvar @r{with an asterisk} - -In the past, Emacs used the @code{defvar} special form both for -internal variables that you would not expect a user to change and for -variables that you do expect a user to change. Although you can still -use @code{defvar} for user customizable variables, please use -@code{defcustom} instead, since that special form provides a path into -the Customization commands. (@xref{defcustom, , Specifying Variables -using @code{defcustom}}.) - -When you specified a variable using the @code{defvar} special form, -you could distinguish a variable that a user might want to change from -others by typing an asterisk, @samp{*}, in the first column of its -documentation string. For example: - -@smallexample -@group -(defvar shell-command-default-error-buffer nil - "*Buffer name for `shell-command' @dots{} error output. -@dots{} ") -@end group -@end smallexample - -@findex set-variable -@noindent -You could (and still can) use the @code{set-variable} command to -change the value of @code{shell-command-default-error-buffer} -temporarily. However, options set using @code{set-variable} are set -only for the duration of your editing session. The new values are not -saved between sessions. Each time Emacs starts, it reads the original -value, unless you change the value within your @file{.emacs} file, -either by setting it manually or by using @code{customize}. -@xref{Emacs Initialization, , Your @file{.emacs} File}. - -For me, the major use of the @code{set-variable} command is to suggest -variables that I might want to set in my @file{.emacs} file. There -are now more than 700 such variables --- far too many to remember -readily. Fortunately, you can press @key{TAB} after calling the -@code{M-x set-variable} command to see the list of variables. -(@xref{Examining, , Examining and Setting Variables, emacs, -The GNU Emacs Manual}.) - -@need 1250 -@node cons & search-fwd Review, search Exercises, defvar, Cutting & Storing Text -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item car -@itemx cdr -@code{car} returns the first element of a list; @code{cdr} returns the -second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(car '(1 2 3 4 5 6 7)) - @result{} 1 -(cdr '(1 2 3 4 5 6 7)) - @result{} (2 3 4 5 6 7) -@end group -@end smallexample - -@item cons -@code{cons} constructs a list by prepending its first argument to its -second argument. - -@need 1250 -For example: - -@smallexample -@group -(cons 1 '(2 3 4)) - @result{} (1 2 3 4) -@end group -@end smallexample - -@item funcall -@code{funcall} evaluates its first argument as a function. It passes -its remaining arguments to its first argument. - -@item nthcdr -Return the result of taking @sc{cdr} `n' times on a list. -@iftex -The -@tex -$n^{th}$ -@end tex -@code{cdr}. -@end iftex -The `rest of the rest', as it were. - -@need 1250 -For example: - -@smallexample -@group -(nthcdr 3 '(1 2 3 4 5 6 7)) - @result{} (4 5 6 7) -@end group -@end smallexample - -@item setcar -@itemx setcdr -@code{setcar} changes the first element of a list; @code{setcdr} -changes the second and subsequent elements of a list. - -@need 1250 -For example: - -@smallexample -@group -(setq triple '(1 2 3)) - -(setcar triple '37) - -triple - @result{} (37 2 3) - -(setcdr triple '("foo" "bar")) - -triple - @result{} (37 "foo" "bar") -@end group -@end smallexample - -@item progn -Evaluate each argument in sequence and then return the value of the -last. - -@need 1250 -For example: - -@smallexample -@group -(progn 1 2 3 4) - @result{} 4 -@end group -@end smallexample - -@item save-restriction -Record whatever narrowing is in effect in the current buffer, if any, -and restore that narrowing after evaluating the arguments. - -@item search-forward -Search for a string, and if the string is found, move point. With a -regular expression, use the similar @code{re-search-forward}. -(@xref{Regexp Search, , Regular Expression Searches}, for an -explanation of regular expression patterns and searches.) - -@need 1250 -@noindent -@code{search-forward} and @code{re-search-forward} take four -arguments: - -@enumerate -@item -The string or regular expression to search for. - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item kill-region -@itemx delete-and-extract-region -@itemx copy-region-as-kill - -@code{kill-region} cuts the text between point and mark from the -buffer and stores that text in the kill ring, so you can get it back -by yanking. - -@code{copy-region-as-kill} copies the text between point and mark into -the kill ring, from which you can get it by yanking. The function -does not cut or remove the text from the buffer. -@end table - -@code{delete-and-extract-region} removes the text between point and -mark from the buffer and throws it away. You cannot get it back. -(This is not an interactive command.) - -@need 1500 -@node search Exercises, , cons & search-fwd Review, Cutting & Storing Text -@section Searching Exercises - -@itemize @bullet -@item -Write an interactive function that searches for a string. If the -search finds the string, leave point after it and display a message -that says ``Found!''. (Do not use @code{search-forward} for the name -of this function; if you do, you will overwrite the existing version of -@code{search-forward} that comes with Emacs. Use a name such as -@code{test-search} instead.) - -@item -Write a function that prints the third element of the kill ring in the -echo area, if any; if the kill ring does not contain a third element, -print an appropriate message. -@end itemize - -@node List Implementation, Yanking, Cutting & Storing Text, Top -@comment node-name, next, previous, up -@chapter How Lists are Implemented -@cindex Lists in a computer - -In Lisp, atoms are recorded in a straightforward fashion; if the -implementation is not straightforward in practice, it is, nonetheless, -straightforward in theory. The atom @samp{rose}, for example, is -recorded as the four contiguous letters @samp{r}, @samp{o}, @samp{s}, -@samp{e}. A list, on the other hand, is kept differently. The mechanism -is equally simple, but it takes a moment to get used to the idea. A -list is kept using a series of pairs of pointers. In the series, the -first pointer in each pair points to an atom or to another list, and the -second pointer in each pair points to the next pair, or to the symbol -@code{nil}, which marks the end of the list. - -A pointer itself is quite simply the electronic address of what is -pointed to. Hence, a list is kept as a series of electronic addresses. - -@menu -* Lists diagrammed:: -* Symbols as Chest:: Exploring a powerful metaphor. -* List Exercise:: -@end menu - -@node Lists diagrammed, Symbols as Chest, List Implementation, List Implementation -@ifnottex -@unnumberedsec Lists diagrammed -@end ifnottex - -For example, the list @code{(rose violet buttercup)} has three elements, -@samp{rose}, @samp{violet}, and @samp{buttercup}. In the computer, the -electronic address of @samp{rose} is recorded in a segment of computer -memory along with the address that gives the electronic address of where -the atom @samp{violet} is located; and that address (the one that tells -where @samp{violet} is located) is kept along with an address that tells -where the address for the atom @samp{buttercup} is located. - -@need 1200 -This sounds more complicated than it is and is easier seen in a diagram: - -@c clear print-postscript-figures -@c !!! cons-cell-diagram #1 -@ifnottex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In the diagram, each box represents a word of computer memory that -holds a Lisp object, usually in the form of a memory address. The boxes, -i.e.@: the addresses, are in pairs. Each arrow points to what the address -is the address of, either an atom or another pair of addresses. The -first box is the electronic address of @samp{rose} and the arrow points -to @samp{rose}; the second box is the address of the next pair of boxes, -the first part of which is the address of @samp{violet} and the second -part of which is the address of the next pair. The very last box -points to the symbol @code{nil}, which marks the end of the list. - -@need 1200 -When a variable is set to a list with a function such as @code{setq}, -it stores the address of the first box in the variable. Thus, -evaluation of the expression - -@smallexample -(setq bouquet '(rose violet buttercup)) -@end smallexample - -@need 1250 -@noindent -creates a situation like this: - -@c cons-cell-diagram #2 -@ifnottex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | ___ ___ ___ ___ ___ ___ - --> |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -In this example, the symbol @code{bouquet} holds the address of the first -pair of boxes. - -@need 1200 -This same list can be illustrated in a different sort of box notation -like this: - -@c cons-cell-diagram #2a -@ifnottex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-2a} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-2a.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -bouquet - | - | -------------- --------------- ---------------- - | | car | cdr | | car | cdr | | car | cdr | - -->| rose | o------->| violet | o------->| butter- | nil | - | | | | | | | cup | | - -------------- --------------- ---------------- -@end group -@end smallexample -@end iftex -@end ifclear - -(Symbols consist of more than pairs of addresses, but the structure of -a symbol is made up of addresses. Indeed, the symbol @code{bouquet} -consists of a group of address-boxes, one of which is the address of -the printed word @samp{bouquet}, a second of which is the address of a -function definition attached to the symbol, if any, a third of which -is the address of the first pair of address-boxes for the list -@code{(rose violet buttercup)}, and so on. Here we are showing that -the symbol's third address-box points to the first pair of -address-boxes for the list.) - -If a symbol is set to the @sc{cdr} of a list, the list itself is not -changed; the symbol simply has an address further down the list. (In -the jargon, @sc{car} and @sc{cdr} are `non-destructive'.) Thus, -evaluation of the following expression - -@smallexample -(setq flowers (cdr bouquet)) -@end smallexample - -@need 800 -@noindent -produces this: - -@c cons-cell-diagram #3 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ | ___ ___ ___ ___ - --> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@noindent -The value of @code{flowers} is @code{(violet buttercup)}, which is -to say, the symbol @code{flowers} holds the address of the pair of -address-boxes, the first of which holds the address of @code{violet}, -and the second of which holds the address of @code{buttercup}. - -A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted -pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp -Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair -Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more -information about cons cells and dotted pairs. - -@need 1200 -The function @code{cons} adds a new pair of addresses to the front of -a series of addresses like that shown above. For example, evaluating -the expression - -@smallexample -(setq bouquet (cons 'lily bouquet)) -@end smallexample - -@need 1500 -@noindent -produces: - -@c cons-cell-diagram #4 -@ifnottex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-4} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-4.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group -bouquet flowers - | | - | ___ ___ ___ ___ | ___ ___ ___ ___ - --> | | | | | | --> | | | | | | - |___|___|----> |___|___|----> |___|___|---->|___|___|--> nil - | | | | - | | | | - --> lily --> rose --> violet --> buttercup -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@need 1200 -@noindent -However, this does not change the value of the symbol -@code{flowers}, as you can see by evaluating the following, - -@smallexample -(eq (cdr (cdr bouquet)) flowers) -@end smallexample - -@noindent -which returns @code{t} for true. - -Until it is reset, @code{flowers} still has the value -@code{(violet buttercup)}; that is, it has the address of the cons -cell whose first address is of @code{violet}. Also, this does not -alter any of the pre-existing cons cells; they are all still there. - -Thus, in Lisp, to get the @sc{cdr} of a list, you just get the address -of the next cons cell in the series; to get the @sc{car} of a list, -you get the address of the first element of the list; to @code{cons} a -new element on a list, you add a new cons cell to the front of the list. -That is all there is to it! The underlying structure of Lisp is -brilliantly simple! - -And what does the last address in a series of cons cells refer to? It -is the address of the empty list, of @code{nil}. - -In summary, when a Lisp variable is set to a value, it is provided with -the address of the list to which the variable refers. - -@node Symbols as Chest, List Exercise, Lists diagrammed, List Implementation -@section Symbols as a Chest of Drawers -@cindex Symbols as a Chest of Drawers -@cindex Chest of Drawers, metaphor for a symbol -@cindex Drawers, Chest of, metaphor for a symbol - -In an earlier section, I suggested that you might imagine a symbol as -being a chest of drawers. The function definition is put in one -drawer, the value in another, and so on. What is put in the drawer -holding the value can be changed without affecting the contents of the -drawer holding the function definition, and vice-verse. - -Actually, what is put in each drawer is the address of the value or -function definition. It is as if you found an old chest in the attic, -and in one of its drawers you found a map giving you directions to -where the buried treasure lies. - -(In addition to its name, symbol definition, and variable value, a -symbol has a `drawer' for a @dfn{property list} which can be used to -record other information. Property lists are not discussed here; see -@ref{Property Lists, , Property Lists, elisp, The GNU Emacs Lisp -Reference Manual}.) - -@need 1500 -Here is a fanciful representation: - -@c chest-of-drawers diagram -@ifnottex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{drawers} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/drawers.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@sp 1 -@smallexample -@group - Chest of Drawers Contents of Drawers - - __ o0O0o __ - / \ - --------------------- - | directions to | [map to] - | symbol name | bouquet - | | - +---------------------+ - | directions to | - | symbol definition | [none] - | | - +---------------------+ - | directions to | [map to] - | variable value | (rose violet buttercup) - | | - +---------------------+ - | directions to | - | property list | [not described here] - | | - +---------------------+ - |/ \| -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -@node List Exercise, , Symbols as Chest, List Implementation -@section Exercise - -Set @code{flowers} to @code{violet} and @code{buttercup}. Cons two -more flowers on to this list and set this new list to -@code{more-flowers}. Set the @sc{car} of @code{flowers} to a fish. -What does the @code{more-flowers} list now contain? - -@node Yanking, Loops & Recursion, List Implementation, Top -@comment node-name, next, previous, up -@chapter Yanking Text Back -@findex yank -@cindex Text retrieval -@cindex Retrieving text -@cindex Pasting text - -Whenever you cut text out of a buffer with a `kill' command in GNU Emacs, -you can bring it back with a `yank' command. The text that is cut out of -the buffer is put in the kill ring and the yank commands insert the -appropriate contents of the kill ring back into a buffer (not necessarily -the original buffer). - -A simple @kbd{C-y} (@code{yank}) command inserts the first item from -the kill ring into the current buffer. If the @kbd{C-y} command is -followed immediately by @kbd{M-y}, the first element is replaced by -the second element. Successive @kbd{M-y} commands replace the second -element with the third, fourth, or fifth element, and so on. When the -last element in the kill ring is reached, it is replaced by the first -element and the cycle is repeated. (Thus the kill ring is called a -`ring' rather than just a `list'. However, the actual data structure -that holds the text is a list. -@xref{Kill Ring, , Handling the Kill Ring}, for the details of how the -list is handled as a ring.) - -@menu -* Kill Ring Overview:: -* kill-ring-yank-pointer:: The kill ring is a list. -* yank nthcdr Exercises:: The @code{kill-ring-yank-pointer} variable. -@end menu - -@node Kill Ring Overview, kill-ring-yank-pointer, Yanking, Yanking -@comment node-name, next, previous, up -@section Kill Ring Overview -@cindex Kill ring overview - -The kill ring is a list of textual strings. This is what it looks like: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -If this were the contents of my kill ring and I pressed @kbd{C-y}, the -string of characters saying @samp{some text} would be inserted in this -buffer where my cursor is located. - -The @code{yank} command is also used for duplicating text by copying it. -The copied text is not cut from the buffer, but a copy of it is put on the -kill ring and is inserted by yanking it back. - -Three functions are used for bringing text back from the kill ring: -@code{yank}, which is usually bound to @kbd{C-y}; @code{yank-pop}, -which is usually bound to @kbd{M-y}; and @code{rotate-yank-pointer}, -which is used by the two other functions. - -These functions refer to the kill ring through a variable called the -@code{kill-ring-yank-pointer}. Indeed, the insertion code for both the -@code{yank} and @code{yank-pop} functions is: - -@smallexample -(insert (car kill-ring-yank-pointer)) -@end smallexample - -@noindent -(Well, no more. In GNU Emacs 22, the function has been replaced by -@code{insert-for-yank} which calls @code{insert-for-yank-1} -repetitively for each @code{yank-handler} segment. In turn, -@code{insert-for-yank-1} strips text properties from the inserted text -according to @code{yank-excluded-properties}. Otherwise, it is just -like @code{insert}. We will stick with plain @code{insert} since it -is easier to understand.) - -To begin to understand how @code{yank} and @code{yank-pop} work, it is -first necessary to look at the @code{kill-ring-yank-pointer} variable. - -@node kill-ring-yank-pointer, yank nthcdr Exercises, Kill Ring Overview, Yanking -@comment node-name, next, previous, up -@section The @code{kill-ring-yank-pointer} Variable - -@code{kill-ring-yank-pointer} is a variable, just as @code{kill-ring} is -a variable. It points to something by being bound to the value of what -it points to, like any other Lisp variable. - -@need 1000 -Thus, if the value of the kill ring is: - -@smallexample -("some text" "a different piece of text" "yet more text") -@end smallexample - -@need 1250 -@noindent -and the @code{kill-ring-yank-pointer} points to the second clause, the -value of @code{kill-ring-yank-pointer} is: - -@smallexample -("a different piece of text" "yet more text") -@end smallexample - -As explained in the previous chapter (@pxref{List Implementation}), the -computer does not keep two different copies of the text being pointed to -by both the @code{kill-ring} and the @code{kill-ring-yank-pointer}. The -words ``a different piece of text'' and ``yet more text'' are not -duplicated. Instead, the two Lisp variables point to the same pieces of -text. Here is a diagram: - -@c cons-cell-diagram #5 -@ifnottex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{cons-5} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/cons-5.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -kill-ring kill-ring-yank-pointer - | | - | ___ ___ | ___ ___ ___ ___ - ---> | | | --> | | | | | | - |___|___|----> |___|___|--> |___|___|--> nil - | | | - | | | - | | --> "yet more text" - | | - | --> "a different piece of text - | - --> "some text" -@end group -@end smallexample -@sp 1 -@end iftex -@end ifclear - -Both the variable @code{kill-ring} and the variable -@code{kill-ring-yank-pointer} are pointers. But the kill ring itself is -usually described as if it were actually what it is composed of. The -@code{kill-ring} is spoken of as if it were the list rather than that it -points to the list. Conversely, the @code{kill-ring-yank-pointer} is -spoken of as pointing to a list. - -These two ways of talking about the same thing sound confusing at first but -make sense on reflection. The kill ring is generally thought of as the -complete structure of data that holds the information of what has recently -been cut out of the Emacs buffers. The @code{kill-ring-yank-pointer} -on the other hand, serves to indicate---that is, to `point to'---that part -of the kill ring of which the first element (the @sc{car}) will be -inserted. - -@ignore -In GNU Emacs 22, the @code{kill-new} function calls - -@code{(setq kill-ring-yank-pointer kill-ring)} - -(defun rotate-yank-pointer (arg) - "Rotate the yanking point in the kill ring. -With argument, rotate that many kills forward (or backward, if negative)." - (interactive "p") - (current-kill arg)) - -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) - -@end ignore - -@need 1500 -@node yank nthcdr Exercises, , kill-ring-yank-pointer, Yanking -@section Exercises with @code{yank} and @code{nthcdr} - -@itemize @bullet -@item -Using @kbd{C-h v} (@code{describe-variable}), look at the value of -your kill ring. Add several items to your kill ring; look at its -value again. Using @kbd{M-y} (@code{yank-pop)}, move all the way -around the kill ring. How many items were in your kill ring? Find -the value of @code{kill-ring-max}. Was your kill ring full, or could -you have kept more blocks of text within it? - -@item -Using @code{nthcdr} and @code{car}, construct a series of expressions -to return the first, second, third, and fourth elements of a list. -@end itemize - -@node Loops & Recursion, Regexp Search, Yanking, Top -@comment node-name, next, previous, up -@chapter Loops and Recursion -@cindex Loops and recursion -@cindex Recursion and loops -@cindex Repetition (loops) - -Emacs Lisp has two primary ways to cause an expression, or a series of -expressions, to be evaluated repeatedly: one uses a @code{while} -loop, and the other uses @dfn{recursion}. - -Repetition can be very valuable. For example, to move forward four -sentences, you need only write a program that will move forward one -sentence and then repeat the process four times. Since a computer does -not get bored or tired, such repetitive action does not have the -deleterious effects that excessive or the wrong kinds of repetition can -have on humans. - -People mostly write Emacs Lisp functions using @code{while} loops and -their kin; but you can use recursion, which provides a very powerful -way to think about and then to solve problems@footnote{You can write -recursive functions to be frugal or wasteful of mental or computer -resources; as it happens, methods that people find easy---that are -frugal of `mental resources'---sometimes use considerable computer -resources. Emacs was designed to run on machines that we now consider -limited and its default settings are conservative. You may want to -increase the values of @code{max-specpdl-size} and -@code{max-lisp-eval-depth}. In my @file{.emacs} file, I set them to -15 and 30 times their default value.}. - -@menu -* while:: Causing a stretch of code to repeat. -* dolist dotimes:: -* Recursion:: Causing a function to call itself. -* Looping exercise:: -@end menu - -@node while, dolist dotimes, Loops & Recursion, Loops & Recursion -@comment node-name, next, previous, up -@section @code{while} -@cindex Loops -@findex while - -The @code{while} special form tests whether the value returned by -evaluating its first argument is true or false. This is similar to what -the Lisp interpreter does with an @code{if}; what the interpreter does -next, however, is different. - -In a @code{while} expression, if the value returned by evaluating the -first argument is false, the Lisp interpreter skips the rest of the -expression (the @dfn{body} of the expression) and does not evaluate it. -However, if the value is true, the Lisp interpreter evaluates the body -of the expression and then again tests whether the first argument to -@code{while} is true or false. If the value returned by evaluating the -first argument is again true, the Lisp interpreter again evaluates the -body of the expression. - -@need 1200 -The template for a @code{while} expression looks like this: - -@smallexample -@group -(while @var{true-or-false-test} - @var{body}@dots{}) -@end group -@end smallexample - -@menu -* Looping with while:: Repeat so long as test returns true. -* Loop Example:: A @code{while} loop that uses a list. -* print-elements-of-list:: Uses @code{while}, @code{car}, @code{cdr}. -* Incrementing Loop:: A loop with an incrementing counter. -* Incrementing Loop Details:: -* Decrementing Loop:: A loop with a decrementing counter. -@end menu - -@node Looping with while, Loop Example, while, while -@ifnottex -@unnumberedsubsec Looping with @code{while} -@end ifnottex - -So long as the true-or-false-test of the @code{while} expression -returns a true value when it is evaluated, the body is repeatedly -evaluated. This process is called a loop since the Lisp interpreter -repeats the same thing again and again, like an airplane doing a loop. -When the result of evaluating the true-or-false-test is false, the -Lisp interpreter does not evaluate the rest of the @code{while} -expression and `exits the loop'. - -Clearly, if the value returned by evaluating the first argument to -@code{while} is always true, the body following will be evaluated -again and again @dots{} and again @dots{} forever. Conversely, if the -value returned is never true, the expressions in the body will never -be evaluated. The craft of writing a @code{while} loop consists of -choosing a mechanism such that the true-or-false-test returns true -just the number of times that you want the subsequent expressions to -be evaluated, and then have the test return false. - -The value returned by evaluating a @code{while} is the value of the -true-or-false-test. An interesting consequence of this is that a -@code{while} loop that evaluates without error will return @code{nil} -or false regardless of whether it has looped 1 or 100 times or none at -all. A @code{while} expression that evaluates successfully never -returns a true value! What this means is that @code{while} is always -evaluated for its side effects, which is to say, the consequences of -evaluating the expressions within the body of the @code{while} loop. -This makes sense. It is not the mere act of looping that is desired, -but the consequences of what happens when the expressions in the loop -are repeatedly evaluated. - -@node Loop Example, print-elements-of-list, Looping with while, while -@comment node-name, next, previous, up -@subsection A @code{while} Loop and a List - -A common way to control a @code{while} loop is to test whether a list -has any elements. If it does, the loop is repeated; but if it does not, -the repetition is ended. Since this is an important technique, we will -create a short example to illustrate it. - -A simple way to test whether a list has elements is to evaluate the -list: if it has no elements, it is an empty list and will return the -empty list, @code{()}, which is a synonym for @code{nil} or false. On -the other hand, a list with elements will return those elements when it -is evaluated. Since Emacs Lisp considers as true any value that is not -@code{nil}, a list that returns elements will test true in a -@code{while} loop. - -@need 1200 -For example, you can set the variable @code{empty-list} to @code{nil} by -evaluating the following @code{setq} expression: - -@smallexample -(setq empty-list ()) -@end smallexample - -@noindent -After evaluating the @code{setq} expression, you can evaluate the -variable @code{empty-list} in the usual way, by placing the cursor after -the symbol and typing @kbd{C-x C-e}; @code{nil} will appear in your -echo area: - -@smallexample -empty-list -@end smallexample - -On the other hand, if you set a variable to be a list with elements, the -list will appear when you evaluate the variable, as you can see by -evaluating the following two expressions: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -animals -@end group -@end smallexample - -Thus, to create a @code{while} loop that tests whether there are any -items in the list @code{animals}, the first part of the loop will be -written like this: - -@smallexample -@group -(while animals - @dots{} -@end group -@end smallexample - -@noindent -When the @code{while} tests its first argument, the variable -@code{animals} is evaluated. It returns a list. So long as the list -has elements, the @code{while} considers the results of the test to be -true; but when the list is empty, it considers the results of the test -to be false. - -To prevent the @code{while} loop from running forever, some mechanism -needs to be provided to empty the list eventually. An oft-used -technique is to have one of the subsequent forms in the @code{while} -expression set the value of the list to be the @sc{cdr} of the list. -Each time the @code{cdr} function is evaluated, the list will be made -shorter, until eventually only the empty list will be left. At this -point, the test of the @code{while} loop will return false, and the -arguments to the @code{while} will no longer be evaluated. - -For example, the list of animals bound to the variable @code{animals} -can be set to be the @sc{cdr} of the original list with the -following expression: - -@smallexample -(setq animals (cdr animals)) -@end smallexample - -@noindent -If you have evaluated the previous expressions and then evaluate this -expression, you will see @code{(giraffe lion tiger)} appear in the echo -area. If you evaluate the expression again, @code{(lion tiger)} will -appear in the echo area. If you evaluate it again and yet again, -@code{(tiger)} appears and then the empty list, shown by @code{nil}. - -A template for a @code{while} loop that uses the @code{cdr} function -repeatedly to cause the true-or-false-test eventually to test false -looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -This test and use of @code{cdr} can be put together in a function that -goes through a list and prints each element of the list on a line of its -own. - -@node print-elements-of-list, Incrementing Loop, Loop Example, while -@subsection An Example: @code{print-elements-of-list} -@findex print-elements-of-list - -The @code{print-elements-of-list} function illustrates a @code{while} -loop with a list. - -@cindex @file{*scratch*} buffer -The function requires several lines for its output. If you are -reading this in a recent instance of GNU Emacs, -@c GNU Emacs 21, GNU Emacs 22, or a later version, -you can evaluate the following expression inside of Info, as usual. - -If you are using an earlier version of Emacs, you need to copy the -necessary expressions to your @file{*scratch*} buffer and evaluate -them there. This is because the echo area had only one line in the -earlier versions. - -You can copy the expressions by marking the beginning of the region -with @kbd{C-@key{SPC}} (@code{set-mark-command}), moving the cursor to -the end of the region and then copying the region using @kbd{M-w} -(@code{kill-ring-save}, which calls @code{copy-region-as-kill} and -then provides visual feedback). In the @file{*scratch*} -buffer, you can yank the expressions back by typing @kbd{C-y} -(@code{yank}). - -After you have copied the expressions to the @file{*scratch*} buffer, -evaluate each expression in turn. Be sure to evaluate the last -expression, @code{(print-elements-of-list animals)}, by typing -@kbd{C-u C-x C-e}, that is, by giving an argument to -@code{eval-last-sexp}. This will cause the result of the evaluation -to be printed in the @file{*scratch*} buffer instead of being printed -in the echo area. (Otherwise you will see something like this in your -echo area: @code{^Jgazelle^J^Jgiraffe^J^Jlion^J^Jtiger^Jnil}, in which -each @samp{^J} stands for a `newline'.) - -@need 1500 -In a recent instance of GNU Emacs, you can evaluate these expressions -directly in the Info buffer, and the echo area will grow to show the -results. - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-of-list (list) - "Print each element of LIST on a line of its own." - (while list - (print (car list)) - (setq list (cdr list)))) - -(print-elements-of-list animals) -@end group -@end smallexample - -@need 1200 -@noindent -When you evaluate the three expressions in sequence, you will see -this: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -Each element of the list is printed on a line of its own (that is what -the function @code{print} does) and then the value returned by the -function is printed. Since the last expression in the function is the -@code{while} loop, and since @code{while} loops always return -@code{nil}, a @code{nil} is printed after the last element of the list. - -@node Incrementing Loop, Incrementing Loop Details, print-elements-of-list, while -@comment node-name, next, previous, up -@subsection A Loop with an Incrementing Counter - -A loop is not useful unless it stops when it ought. Besides -controlling a loop with a list, a common way of stopping a loop is to -write the first argument as a test that returns false when the correct -number of repetitions are complete. This means that the loop must -have a counter---an expression that counts how many times the loop -repeats itself. - -@node Incrementing Loop Details, Decrementing Loop, Incrementing Loop, while -@ifnottex -@unnumberedsubsec Details of an Incrementing Loop -@end ifnottex - -The test for a loop with an incrementing counter can be an expression -such as @code{(< count desired-number)} which returns @code{t} for -true if the value of @code{count} is less than the -@code{desired-number} of repetitions and @code{nil} for false if the -value of @code{count} is equal to or is greater than the -@code{desired-number}. The expression that increments the count can -be a simple @code{setq} such as @code{(setq count (1+ count))}, where -@code{1+} is a built-in function in Emacs Lisp that adds 1 to its -argument. (The expression @w{@code{(1+ count)}} has the same result -as @w{@code{(+ count 1)}}, but is easier for a human to read.) - -@need 1250 -The template for a @code{while} loop controlled by an incrementing -counter looks like this: - -@smallexample -@group -@var{set-count-to-initial-value} -(while (< count desired-number) ; @r{true-or-false-test} - @var{body}@dots{} - (setq count (1+ count))) ; @r{incrementer} -@end group -@end smallexample - -@noindent -Note that you need to set the initial value of @code{count}; usually it -is set to 1. - -@menu -* Incrementing Example:: Counting pebbles in a triangle. -* Inc Example parts:: The parts of the function definition. -* Inc Example altogether:: Putting the function definition together. -@end menu - -@node Incrementing Example, Inc Example parts, Incrementing Loop Details, Incrementing Loop Details -@unnumberedsubsubsec Example with incrementing counter - -Suppose you are playing on the beach and decide to make a triangle of -pebbles, putting one pebble in the first row, two in the second row, -three in the third row and so on, like this: - -@sp 1 -@c pebble diagram -@ifnottex -@smallexample -@group - * - * * - * * * - * * * * -@end group -@end smallexample -@end ifnottex -@iftex -@smallexample -@group - @bullet{} - @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} - @bullet{} @bullet{} @bullet{} @bullet{} -@end group -@end smallexample -@end iftex -@sp 1 - -@noindent -(About 2500 years ago, Pythagoras and others developed the beginnings of -number theory by considering questions such as this.) - -Suppose you want to know how many pebbles you will need to make a -triangle with 7 rows? - -Clearly, what you need to do is add up the numbers from 1 to 7. There -are two ways to do this; start with the smallest number, one, and add up -the list in sequence, 1, 2, 3, 4 and so on; or start with the largest -number and add the list going down: 7, 6, 5, 4 and so on. Because both -mechanisms illustrate common ways of writing @code{while} loops, we will -create two examples, one counting up and the other counting down. In -this first example, we will start with 1 and add 2, 3, 4 and so on. - -If you are just adding up a short list of numbers, the easiest way to do -it is to add up all the numbers at once. However, if you do not know -ahead of time how many numbers your list will have, or if you want to be -prepared for a very long list, then you need to design your addition so -that what you do is repeat a simple process many times instead of doing -a more complex process once. - -For example, instead of adding up all the pebbles all at once, what you -can do is add the number of pebbles in the first row, 1, to the number -in the second row, 2, and then add the total of those two rows to the -third row, 3. Then you can add the number in the fourth row, 4, to the -total of the first three rows; and so on. - -The critical characteristic of the process is that each repetitive -action is simple. In this case, at each step we add only two numbers, -the number of pebbles in the row and the total already found. This -process of adding two numbers is repeated again and again until the last -row has been added to the total of all the preceding rows. In a more -complex loop the repetitive action might not be so simple, but it will -be simpler than doing everything all at once. - -@node Inc Example parts, Inc Example altogether, Incrementing Example, Incrementing Loop Details -@unnumberedsubsubsec The parts of the function definition - -The preceding analysis gives us the bones of our function definition: -first, we will need a variable that we can call @code{total} that will -be the total number of pebbles. This will be the value returned by -the function. - -Second, we know that the function will require an argument: this -argument will be the total number of rows in the triangle. It can be -called @code{number-of-rows}. - -Finally, we need a variable to use as a counter. We could call this -variable @code{counter}, but a better name is @code{row-number}. That -is because what the counter does in this function is count rows, and a -program should be written to be as understandable as possible. - -When the Lisp interpreter first starts evaluating the expressions in the -function, the value of @code{total} should be set to zero, since we have -not added anything to it. Then the function should add the number of -pebbles in the first row to the total, and then add the number of -pebbles in the second to the total, and then add the number of -pebbles in the third row to the total, and so on, until there are no -more rows left to add. - -Both @code{total} and @code{row-number} are used only inside the -function, so they can be declared as local variables with @code{let} -and given initial values. Clearly, the initial value for @code{total} -should be 0. The initial value of @code{row-number} should be 1, -since we start with the first row. This means that the @code{let} -statement will look like this: - -@smallexample -@group - (let ((total 0) - (row-number 1)) - @var{body}@dots{}) -@end group -@end smallexample - -After the internal variables are declared and bound to their initial -values, we can begin the @code{while} loop. The expression that serves -as the test should return a value of @code{t} for true so long as the -@code{row-number} is less than or equal to the @code{number-of-rows}. -(If the expression tests true only so long as the row number is less -than the number of rows in the triangle, the last row will never be -added to the total; hence the row number has to be either less than or -equal to the number of rows.) - -@need 1500 -@findex <= @r{(less than or equal)} -Lisp provides the @code{<=} function that returns true if the value of -its first argument is less than or equal to the value of its second -argument and false otherwise. So the expression that the @code{while} -will evaluate as its test should look like this: - -@smallexample -(<= row-number number-of-rows) -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found. Since the number of -pebbles in the row is equal to the row number, the total can be found by -adding the row number to the total. (Clearly, in a more complex -situation, the number of pebbles in the row might be related to the row -number in a more complicated way; if this were the case, the row number -would be replaced by the appropriate expression.) - -@smallexample -(setq total (+ total row-number)) -@end smallexample - -@noindent -What this does is set the new value of @code{total} to be equal to the -sum of adding the number of pebbles in the row to the previous total. - -After setting the value of @code{total}, the conditions need to be -established for the next repetition of the loop, if there is one. This -is done by incrementing the value of the @code{row-number} variable, -which serves as a counter. After the @code{row-number} variable has -been incremented, the true-or-false-test at the beginning of the -@code{while} loop tests whether its value is still less than or equal to -the value of the @code{number-of-rows} and if it is, adds the new value -of the @code{row-number} variable to the @code{total} of the previous -repetition of the loop. - -@need 1200 -The built-in Emacs Lisp function @code{1+} adds 1 to a number, so the -@code{row-number} variable can be incremented with this expression: - -@smallexample -(setq row-number (1+ row-number)) -@end smallexample - -@node Inc Example altogether, , Inc Example parts, Incrementing Loop Details -@unnumberedsubsubsec Putting the function definition together - -We have created the parts for the function definition; now we need to -put them together. - -@need 800 -First, the contents of the @code{while} expression: - -@smallexample -@group -(while (<= row-number number-of-rows) ; @r{true-or-false-test} - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) ; @r{incrementer} -@end group -@end smallexample - -Along with the @code{let} expression varlist, this very nearly -completes the body of the function definition. However, it requires -one final element, the need for which is somewhat subtle. - -The final touch is to place the variable @code{total} on a line by -itself after the @code{while} expression. Otherwise, the value returned -by the whole function is the value of the last expression that is -evaluated in the body of the @code{let}, and this is the value -returned by the @code{while}, which is always @code{nil}. - -This may not be evident at first sight. It almost looks as if the -incrementing expression is the last expression of the whole function. -But that expression is part of the body of the @code{while}; it is the -last element of the list that starts with the symbol @code{while}. -Moreover, the whole of the @code{while} loop is a list within the body -of the @code{let}. - -@need 1250 -In outline, the function will look like this: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (let (@var{varlist}) - (while (@var{true-or-false-test}) - @var{body-of-while}@dots{} ) - @dots{} )) ; @r{Need final expression here.} -@end group -@end smallexample - -The result of evaluating the @code{let} is what is going to be returned -by the @code{defun} since the @code{let} is not embedded within any -containing list, except for the @code{defun} as a whole. However, if -the @code{while} is the last element of the @code{let} expression, the -function will always return @code{nil}. This is not what we want! -Instead, what we want is the value of the variable @code{total}. This -is returned by simply placing the symbol as the last element of the list -starting with @code{let}. It gets evaluated after the preceding -elements of the list are evaluated, which means it gets evaluated after -it has been assigned the correct value for the total. - -It may be easier to see this by printing the list starting with -@code{let} all on one line. This format makes it evident that the -@var{varlist} and @code{while} expressions are the second and third -elements of the list starting with @code{let}, and the @code{total} is -the last element: - -@smallexample -@group -(let (@var{varlist}) (while (@var{true-or-false-test}) @var{body-of-while}@dots{} ) total) -@end group -@end smallexample - -@need 1200 -Putting everything together, the @code{triangle} function definition -looks like this: - -@smallexample -@group -(defun triangle (number-of-rows) ; @r{Version with} - ; @r{ incrementing counter.} - "Add up the number of pebbles in a triangle. -The first row has one pebble, the second row two pebbles, -the third row three pebbles, and so on. -The argument is NUMBER-OF-ROWS." -@end group -@group - (let ((total 0) - (row-number 1)) - (while (<= row-number number-of-rows) - (setq total (+ total row-number)) - (setq row-number (1+ row-number))) - total)) -@end group -@end smallexample - -@need 1200 -After you have installed @code{triangle} by evaluating the function, you -can try it out. Here are two examples: - -@smallexample -@group -(triangle 4) - -(triangle 7) -@end group -@end smallexample - -@noindent -The sum of the first four numbers is 10 and the sum of the first seven -numbers is 28. - -@node Decrementing Loop, , Incrementing Loop Details, while -@comment node-name, next, previous, up -@subsection Loop with a Decrementing Counter - -Another common way to write a @code{while} loop is to write the test -so that it determines whether a counter is greater than zero. So long -as the counter is greater than zero, the loop is repeated. But when -the counter is equal to or less than zero, the loop is stopped. For -this to work, the counter has to start out greater than zero and then -be made smaller and smaller by a form that is evaluated -repeatedly. - -The test will be an expression such as @code{(> counter 0)} which -returns @code{t} for true if the value of @code{counter} is greater -than zero, and @code{nil} for false if the value of @code{counter} is -equal to or less than zero. The expression that makes the number -smaller and smaller can be a simple @code{setq} such as @code{(setq -counter (1- counter))}, where @code{1-} is a built-in function in -Emacs Lisp that subtracts 1 from its argument. - -@need 1250 -The template for a decrementing @code{while} loop looks like this: - -@smallexample -@group -(while (> counter 0) ; @r{true-or-false-test} - @var{body}@dots{} - (setq counter (1- counter))) ; @r{decrementer} -@end group -@end smallexample - -@menu -* Decrementing Example:: More pebbles on the beach. -* Dec Example parts:: The parts of the function definition. -* Dec Example altogether:: Putting the function definition together. -@end menu - -@node Decrementing Example, Dec Example parts, Decrementing Loop, Decrementing Loop -@unnumberedsubsubsec Example with decrementing counter - -To illustrate a loop with a decrementing counter, we will rewrite the -@code{triangle} function so the counter decreases to zero. - -This is the reverse of the earlier version of the function. In this -case, to find out how many pebbles are needed to make a triangle with -3 rows, add the number of pebbles in the third row, 3, to the number -in the preceding row, 2, and then add the total of those two rows to -the row that precedes them, which is 1. - -Likewise, to find the number of pebbles in a triangle with 7 rows, add -the number of pebbles in the seventh row, 7, to the number in the -preceding row, which is 6, and then add the total of those two rows to -the row that precedes them, which is 5, and so on. As in the previous -example, each addition only involves adding two numbers, the total of -the rows already added up and the number of pebbles in the row that is -being added to the total. This process of adding two numbers is -repeated again and again until there are no more pebbles to add. - -We know how many pebbles to start with: the number of pebbles in the -last row is equal to the number of rows. If the triangle has seven -rows, the number of pebbles in the last row is 7. Likewise, we know how -many pebbles are in the preceding row: it is one less than the number in -the row. - -@node Dec Example parts, Dec Example altogether, Decrementing Example, Decrementing Loop -@unnumberedsubsubsec The parts of the function definition - -We start with three variables: the total number of rows in the -triangle; the number of pebbles in a row; and the total number of -pebbles, which is what we want to calculate. These variables can be -named @code{number-of-rows}, @code{number-of-pebbles-in-row}, and -@code{total}, respectively. - -Both @code{total} and @code{number-of-pebbles-in-row} are used only -inside the function and are declared with @code{let}. The initial -value of @code{total} should, of course, be zero. However, the -initial value of @code{number-of-pebbles-in-row} should be equal to -the number of rows in the triangle, since the addition will start with -the longest row. - -@need 1250 -This means that the beginning of the @code{let} expression will look -like this: - -@smallexample -@group -(let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - @var{body}@dots{}) -@end group -@end smallexample - -The total number of pebbles can be found by repeatedly adding the number -of pebbles in a row to the total already found, that is, by repeatedly -evaluating the following expression: - -@smallexample -(setq total (+ total number-of-pebbles-in-row)) -@end smallexample - -@noindent -After the @code{number-of-pebbles-in-row} is added to the @code{total}, -the @code{number-of-pebbles-in-row} should be decremented by one, since -the next time the loop repeats, the preceding row will be -added to the total. - -The number of pebbles in a preceding row is one less than the number of -pebbles in a row, so the built-in Emacs Lisp function @code{1-} can be -used to compute the number of pebbles in the preceding row. This can be -done with the following expression: - -@smallexample -@group -(setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row)) -@end group -@end smallexample - -Finally, we know that the @code{while} loop should stop making repeated -additions when there are no pebbles in a row. So the test for -the @code{while} loop is simply: - -@smallexample -(while (> number-of-pebbles-in-row 0) -@end smallexample - -@node Dec Example altogether, , Dec Example parts, Decrementing Loop -@unnumberedsubsubsec Putting the function definition together - -We can put these expressions together to create a function definition -that works. However, on examination, we find that one of the local -variables is unneeded! - -@need 1250 -The function definition looks like this: - -@smallexample -@group -;;; @r{First subtractive version.} -(defun triangle (number-of-rows) - "Add up the number of pebbles in a triangle." - (let ((total 0) - (number-of-pebbles-in-row number-of-rows)) - (while (> number-of-pebbles-in-row 0) - (setq total (+ total number-of-pebbles-in-row)) - (setq number-of-pebbles-in-row - (1- number-of-pebbles-in-row))) - total)) -@end group -@end smallexample - -As written, this function works. - -However, we do not need @code{number-of-pebbles-in-row}. - -@cindex Argument as local variable -When the @code{triangle} function is evaluated, the symbol -@code{number-of-rows} will be bound to a number, giving it an initial -value. That number can be changed in the body of the function as if -it were a local variable, without any fear that such a change will -effect the value of the variable outside of the function. This is a -very useful characteristic of Lisp; it means that the variable -@code{number-of-rows} can be used anywhere in the function where -@code{number-of-pebbles-in-row} is used. - -@need 800 -Here is a second version of the function written a bit more cleanly: - -@smallexample -@group -(defun triangle (number) ; @r{Second version.} - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1- number))) - total)) -@end group -@end smallexample - -In brief, a properly written @code{while} loop will consist of three parts: - -@enumerate -@item -A test that will return false after the loop has repeated itself the -correct number of times. - -@item -An expression the evaluation of which will return the value desired -after being repeatedly evaluated. - -@item -An expression to change the value passed to the true-or-false-test so -that the test returns false after the loop has repeated itself the right -number of times. -@end enumerate - -@node dolist dotimes, Recursion, while, Loops & Recursion -@comment node-name, next, previous, up -@section Save your time: @code{dolist} and @code{dotimes} - -In addition to @code{while}, both @code{dolist} and @code{dotimes} -provide for looping. Sometimes these are quicker to write than the -equivalent @code{while} loop. Both are Lisp macros. (@xref{Macros, , -Macros, elisp, The GNU Emacs Lisp Reference Manual}. ) - -@code{dolist} works like a @code{while} loop that `@sc{cdr}s down a -list': @code{dolist} automatically shortens the list each time it -loops---takes the @sc{cdr} of the list---and binds the @sc{car} of -each shorter version of the list to the first of its arguments. - -@code{dotimes} loops a specific number of times: you specify the number. - -@menu -* dolist:: -* dotimes:: -@end menu - -@node dolist, dotimes, dolist dotimes, dolist dotimes -@unnumberedsubsubsec The @code{dolist} Macro -@findex dolist - -Suppose, for example, you want to reverse a list, so that -``first'' ``second'' ``third'' becomes ``third'' ``second'' ``first''. - -@need 1250 -In practice, you would use the @code{reverse} function, like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(reverse animals) -@end group -@end smallexample - -@need 800 -@noindent -Here is how you could reverse the list using a @code{while} loop: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-while (list) - "Using while, reverse the order of LIST." - (let (value) ; make sure list starts empty - (while list - (setq value (cons (car list) value)) - (setq list (cdr list))) - value)) - -(reverse-list-with-while animals) -@end group -@end smallexample - -@need 800 -@noindent -And here is how you could use the @code{dolist} macro: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun reverse-list-with-dolist (list) - "Using dolist, reverse the order of LIST." - (let (value) ; make sure list starts empty - (dolist (element list value) - (setq value (cons element value))))) - -(reverse-list-with-dolist animals) -@end group -@end smallexample - -@need 1250 -@noindent -In Info, you can place your cursor after the closing parenthesis of -each expression and type @kbd{C-x C-e}; in each case, you should see - -@smallexample -(tiger lion giraffe gazelle) -@end smallexample - -@noindent -in the echo area. - -For this example, the existing @code{reverse} function is obviously best. -The @code{while} loop is just like our first example (@pxref{Loop -Example, , A @code{while} Loop and a List}). The @code{while} first -checks whether the list has elements; if so, it constructs a new list -by adding the first element of the list to the existing list (which in -the first iteration of the loop is @code{nil}). Since the second -element is prepended in front of the first element, and the third -element is prepended in front of the second element, the list is reversed. - -In the expression using a @code{while} loop, -the @w{@code{(setq list (cdr list))}} -expression shortens the list, so the @code{while} loop eventually -stops. In addition, it provides the @code{cons} expression with a new -first element by creating a new and shorter list at each repetition of -the loop. - -The @code{dolist} expression does very much the same as the -@code{while} expression, except that the @code{dolist} macro does some -of the work you have to do when writing a @code{while} expression. - -Like a @code{while} loop, a @code{dolist} loops. What is different is -that it automatically shortens the list each time it loops --- it -`@sc{cdr}s down the list' on its own --- and it automatically binds -the @sc{car} of each shorter version of the list to the first of its -arguments. - -In the example, the @sc{car} of each shorter version of the list is -referred to using the symbol @samp{element}, the list itself is called -@samp{list}, and the value returned is called @samp{value}. The -remainder of the @code{dolist} expression is the body. - -The @code{dolist} expression binds the @sc{car} of each shorter -version of the list to @code{element} and then evaluates the body of -the expression; and repeats the loop. The result is returned in -@code{value}. - -@node dotimes, , dolist, dolist dotimes -@unnumberedsubsubsec The @code{dotimes} Macro -@findex dotimes - -The @code{dotimes} macro is similar to @code{dolist}, except that it -loops a specific number of times. - -The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. - -@need 1250 -For example, the following binds the numbers from 0 up to, but not -including, the number 3 to the first argument, @var{number}, and then -constructs a list of the three numbers. (The first number is 0, the -second number is 1, and the third number is 2; this makes a total of -three numbers in all, starting with zero as the first number.) - -@smallexample -@group -(let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) - -@result{} (2 1 0) -@end group -@end smallexample - -@noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. - -@need 1250 -Here is an example of a @code{defun} that uses @code{dotimes} to add -up the number of pebbles in a triangle. - -@smallexample -@group -(defun triangle-using-dotimes (number-of-rows) - "Using dotimes, add up the number of pebbles in a triangle." -(let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) - -(triangle-using-dotimes 4) -@end group -@end smallexample - -@node Recursion, Looping exercise, dolist dotimes, Loops & Recursion -@comment node-name, next, previous, up -@section Recursion -@cindex Recursion - -A recursive function contains code that tells the Lisp interpreter to -call a program that runs exactly like itself, but with slightly -different arguments. The code runs exactly the same because it has -the same name. However, even though the program has the same name, it -is not the same entity. It is different. In the jargon, it is a -different `instance'. - -Eventually, if the program is written correctly, the `slightly -different arguments' will become sufficiently different from the first -arguments that the final instance will stop. - -@menu -* Building Robots:: Same model, different serial number ... -* Recursive Definition Parts:: Walk until you stop ... -* Recursion with list:: Using a list as the test whether to recurse. -* Recursive triangle function:: -* Recursion with cond:: -* Recursive Patterns:: Often used templates. -* No Deferment:: Don't store up work ... -* No deferment solution:: -@end menu - -@node Building Robots, Recursive Definition Parts, Recursion, Recursion -@comment node-name, next, previous, up -@subsection Building Robots: Extending the Metaphor -@cindex Building robots -@cindex Robots, building - -It is sometimes helpful to think of a running program as a robot that -does a job. In doing its job, a recursive function calls on a second -robot to help it. The second robot is identical to the first in every -way, except that the second robot helps the first and has been -passed different arguments than the first. - -In a recursive function, the second robot may call a third; and the -third may call a fourth, and so on. Each of these is a different -entity; but all are clones. - -Since each robot has slightly different instructions---the arguments -will differ from one robot to the next---the last robot should know -when to stop. - -Let's expand on the metaphor in which a computer program is a robot. - -A function definition provides the blueprints for a robot. When you -install a function definition, that is, when you evaluate a -@code{defun} special form, you install the necessary equipment to -build robots. It is as if you were in a factory, setting up an -assembly line. Robots with the same name are built according to the -same blueprints. So they have, as it were, the same `model number', -but a different `serial number'. - -We often say that a recursive function `calls itself'. What we mean -is that the instructions in a recursive function cause the Lisp -interpreter to run a different function that has the same name and -does the same job as the first, but with different arguments. - -It is important that the arguments differ from one instance to the -next; otherwise, the process will never stop. - -@node Recursive Definition Parts, Recursion with list, Building Robots, Recursion -@comment node-name, next, previous, up -@subsection The Parts of a Recursive Definition -@cindex Parts of a Recursive Definition -@cindex Recursive Definition Parts - -A recursive function typically contains a conditional expression which -has three parts: - -@enumerate -@item -A true-or-false-test that determines whether the function is called -again, here called the @dfn{do-again-test}. - -@item -The name of the function. When this name is called, a new instance of -the function---a new robot, as it were---is created and told what to do. - -@item -An expression that returns a different value each time the function is -called, here called the @dfn{next-step-expression}. Consequently, the -argument (or arguments) passed to the new instance of the function -will be different from that passed to the previous instance. This -causes the conditional expression, the @dfn{do-again-test}, to test -false after the correct number of repetitions. -@end enumerate - -Recursive functions can be much simpler than any other kind of -function. Indeed, when people first start to use them, they often look -so mysteriously simple as to be incomprehensible. Like riding a -bicycle, reading a recursive function definition takes a certain knack -which is hard at first but then seems simple. - -@need 1200 -There are several different common recursive patterns. A very simple -pattern looks like this: - -@smallexample -@group -(defun @var{name-of-recursive-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (if @var{do-again-test} - @var{body}@dots{} - (@var{name-of-recursive-function} - @var{next-step-expression}))) -@end group -@end smallexample - -Each time a recursive function is evaluated, a new instance of it is -created and told what to do. The arguments tell the instance what to do. - -An argument is bound to the value of the next-step-expression. Each -instance runs with a different value of the next-step-expression. - -The value in the next-step-expression is used in the do-again-test. - -The value returned by the next-step-expression is passed to the new -instance of the function, which evaluates it (or some -transmogrification of it) to determine whether to continue or stop. -The next-step-expression is designed so that the do-again-test returns -false when the function should no longer be repeated. - -The do-again-test is sometimes called the @dfn{stop condition}, -since it stops the repetitions when it tests false. - -@node Recursion with list, Recursive triangle function, Recursive Definition Parts, Recursion -@comment node-name, next, previous, up -@subsection Recursion with a List - -The example of a @code{while} loop that printed the elements of a list -of numbers can be written recursively. Here is the code, including -an expression to set the value of the variable @code{animals} to a list. - -If you are using GNU Emacs 20 or before, this example must be copied -to the @file{*scratch*} buffer and each expression must be evaluated -there. Use @kbd{C-u C-x C-e} to evaluate the -@code{(print-elements-recursively animals)} expression so that the -results are printed in the buffer; otherwise the Lisp interpreter will -try to squeeze the results into the one line of the echo area. - -Also, place your cursor immediately after the last closing parenthesis -of the @code{print-elements-recursively} function, before the comment. -Otherwise, the Lisp interpreter will try to evaluate the comment. - -If you are using a more recent version of Emacs, you can evaluate this -expression directly in Info. - -@findex print-elements-recursively -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) - -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -The @code{print-elements-recursively} function first tests whether -there is any content in the list; if there is, the function prints the -first element of the list, the @sc{car} of the list. Then the -function `invokes itself', but gives itself as its argument, not the -whole list, but the second and subsequent elements of the list, the -@sc{cdr} of the list. - -Put another way, if the list is not empty, the function invokes -another instance of code that is similar to the initial code, but is a -different thread of execution, with different arguments than the first -instance. - -Put in yet another way, if the list is not empty, the first robot -assembles a second robot and tells it what to do; the second robot is -a different individual from the first, but is the same model. - -When the second evaluation occurs, the @code{when} expression is -evaluated and if true, prints the first element of the list it -receives as its argument (which is the second element of the original -list). Then the function `calls itself' with the @sc{cdr} of the list -it is invoked with, which (the second time around) is the @sc{cdr} of -the @sc{cdr} of the original list. - -Note that although we say that the function `calls itself', what we -mean is that the Lisp interpreter assembles and instructs a new -instance of the program. The new instance is a clone of the first, -but is a separate individual. - -Each time the function `invokes itself', it invokes itself on a -shorter version of the original list. It creates a new instance that -works on a shorter list. - -Eventually, the function invokes itself on an empty list. It creates -a new instance whose argument is @code{nil}. The conditional expression -tests the value of @code{list}. Since the value of @code{list} is -@code{nil}, the @code{when} expression tests false so the then-part is -not evaluated. The function as a whole then returns @code{nil}. - -@need 1200 -When you evaluate the expression @code{(print-elements-recursively -animals)} in the @file{*scratch*} buffer, you see this result: - -@smallexample -@group -gazelle - -giraffe - -lion - -tiger -nil -@end group -@end smallexample - -@need 2000 -@node Recursive triangle function, Recursion with cond, Recursion with list, Recursion -@comment node-name, next, previous, up -@subsection Recursion in Place of a Counter -@findex triangle-recursively - -@need 1200 -The @code{triangle} function described in a previous section can also -be written recursively. It looks like this: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} - -(triangle-recursively 7) -@end group -@end smallexample - -@noindent -You can install this function by evaluating it and then try it by -evaluating @code{(triangle-recursively 7)}. (Remember to put your -cursor immediately after the last parenthesis of the function -definition, before the comment.) The function evaluates to 28. - -To understand how this function works, let's consider what happens in the -various cases when the function is passed 1, 2, 3, or 4 as the value of -its argument. - -@menu -* Recursive Example arg of 1 or 2:: -* Recursive Example arg of 3 or 4:: -@end menu - -@node Recursive Example arg of 1 or 2, Recursive Example arg of 3 or 4, Recursive triangle function, Recursive triangle function -@ifnottex -@unnumberedsubsubsec An argument of 1 or 2 -@end ifnottex - -First, what happens if the value of the argument is 1? - -The function has an @code{if} expression after the documentation -string. It tests whether the value of @code{number} is equal to 1; if -so, Emacs evaluates the then-part of the @code{if} expression, which -returns the number 1 as the value of the function. (A triangle with -one row has one pebble in it.) - -Suppose, however, that the value of the argument is 2. In this case, -Emacs evaluates the else-part of the @code{if} expression. - -@need 1200 -The else-part consists of an addition, the recursive call to -@code{triangle-recursively} and a decrementing action; and it looks like -this: - -@smallexample -(+ number (triangle-recursively (1- number))) -@end smallexample - -When Emacs evaluates this expression, the innermost expression is -evaluated first; then the other parts in sequence. Here are the steps -in detail: - -@table @i -@item Step 1 @w{ } Evaluate the innermost expression. - -The innermost expression is @code{(1- number)} so Emacs decrements the -value of @code{number} from 2 to 1. - -@item Step 2 @w{ } Evaluate the @code{triangle-recursively} function. - -The Lisp interpreter creates an individual instance of -@code{triangle-recursively}. It does not matter that this function is -contained within itself. Emacs passes the result Step 1 as the -argument used by this instance of the @code{triangle-recursively} -function - -In this case, Emacs evaluates @code{triangle-recursively} with an -argument of 1. This means that this evaluation of -@code{triangle-recursively} returns 1. - -@item Step 3 @w{ } Evaluate the value of @code{number}. - -The variable @code{number} is the second element of the list that -starts with @code{+}; its value is 2. - -@item Step 4 @w{ } Evaluate the @code{+} expression. - -The @code{+} expression receives two arguments, the first -from the evaluation of @code{number} (Step 3) and the second from the -evaluation of @code{triangle-recursively} (Step 2). - -The result of the addition is the sum of 2 plus 1, and the number 3 is -returned, which is correct. A triangle with two rows has three -pebbles in it. -@end table - -@node Recursive Example arg of 3 or 4, , Recursive Example arg of 1 or 2, Recursive triangle function -@unnumberedsubsubsec An argument of 3 or 4 - -Suppose that @code{triangle-recursively} is called with an argument of -3. - -@table @i -@item Step 1 @w{ } Evaluate the do-again-test. - -The @code{if} expression is evaluated first. This is the do-again -test and returns false, so the else-part of the @code{if} expression -is evaluated. (Note that in this example, the do-again-test causes -the function to call itself when it tests false, not when it tests -true.) - -@item Step 2 @w{ } Evaluate the innermost expression of the else-part. - -The innermost expression of the else-part is evaluated, which decrements -3 to 2. This is the next-step-expression. - -@item Step 3 @w{ } Evaluate the @code{triangle-recursively} function. - -The number 2 is passed to the @code{triangle-recursively} function. - -We already know what happens when Emacs evaluates @code{triangle-recursively} with -an argument of 2. After going through the sequence of actions described -earlier, it returns a value of 3. So that is what will happen here. - -@item Step 4 @w{ } Evaluate the addition. - -3 will be passed as an argument to the addition and will be added to the -number with which the function was called, which is 3. -@end table - -@noindent -The value returned by the function as a whole will be 6. - -Now that we know what will happen when @code{triangle-recursively} is -called with an argument of 3, it is evident what will happen if it is -called with an argument of 4: - -@quotation -@need 800 -In the recursive call, the evaluation of - -@smallexample -(triangle-recursively (1- 4)) -@end smallexample - -@need 800 -@noindent -will return the value of evaluating - -@smallexample -(triangle-recursively 3) -@end smallexample - -@noindent -which is 6 and this value will be added to 4 by the addition in the -third line. -@end quotation - -@noindent -The value returned by the function as a whole will be 10. - -Each time @code{triangle-recursively} is evaluated, it evaluates a -version of itself---a different instance of itself---with a smaller -argument, until the argument is small enough so that it does not -evaluate itself. - -Note that this particular design for a recursive function -requires that operations be deferred. - -Before @code{(triangle-recursively 7)} can calculate its answer, it -must call @code{(triangle-recursively 6)}; and before -@code{(triangle-recursively 6)} can calculate its answer, it must call -@code{(triangle-recursively 5)}; and so on. That is to say, the -calculation that @code{(triangle-recursively 7)} makes must be -deferred until @code{(triangle-recursively 6)} makes its calculation; -and @code{(triangle-recursively 6)} must defer until -@code{(triangle-recursively 5)} completes; and so on. - -If each of these instances of @code{triangle-recursively} are thought -of as different robots, the first robot must wait for the second to -complete its job, which must wait until the third completes, and so -on. - -There is a way around this kind of waiting, which we will discuss in -@ref{No Deferment, , Recursion without Deferments}. - -@node Recursion with cond, Recursive Patterns, Recursive triangle function, Recursion -@comment node-name, next, previous, up -@subsection Recursion Example Using @code{cond} -@findex cond - -The version of @code{triangle-recursively} described earlier is written -with the @code{if} special form. It can also be written using another -special form called @code{cond}. The name of the special form -@code{cond} is an abbreviation of the word @samp{conditional}. - -Although the @code{cond} special form is not used as often in the -Emacs Lisp sources as @code{if}, it is used often enough to justify -explaining it. - -@need 800 -The template for a @code{cond} expression looks like this: - -@smallexample -@group -(cond - @var{body}@dots{}) -@end group -@end smallexample - -@noindent -where the @var{body} is a series of lists. - -@need 800 -Written out more fully, the template looks like this: - -@smallexample -@group -(cond - (@var{first-true-or-false-test} @var{first-consequent}) - (@var{second-true-or-false-test} @var{second-consequent}) - (@var{third-true-or-false-test} @var{third-consequent}) - @dots{}) -@end group -@end smallexample - -When the Lisp interpreter evaluates the @code{cond} expression, it -evaluates the first element (the @sc{car} or true-or-false-test) of -the first expression in a series of expressions within the body of the -@code{cond}. - -If the true-or-false-test returns @code{nil} the rest of that -expression, the consequent, is skipped and the true-or-false-test of the -next expression is evaluated. When an expression is found whose -true-or-false-test returns a value that is not @code{nil}, the -consequent of that expression is evaluated. The consequent can be one -or more expressions. If the consequent consists of more than one -expression, the expressions are evaluated in sequence and the value of -the last one is returned. If the expression does not have a consequent, -the value of the true-or-false-test is returned. - -If none of the true-or-false-tests test true, the @code{cond} expression -returns @code{nil}. - -@need 1250 -Written using @code{cond}, the @code{triangle} function looks like this: - -@smallexample -@group -(defun triangle-using-cond (number) - (cond ((<= number 0) 0) - ((= number 1) 1) - ((> number 1) - (+ number (triangle-using-cond (1- number)))))) -@end group -@end smallexample - -@noindent -In this example, the @code{cond} returns 0 if the number is less than or -equal to 0, it returns 1 if the number is 1 and it evaluates @code{(+ -number (triangle-using-cond (1- number)))} if the number is greater than -1. - -@node Recursive Patterns, No Deferment, Recursion with cond, Recursion -@comment node-name, next, previous, up -@subsection Recursive Patterns -@cindex Recursive Patterns - -Here are three common recursive patterns. Each involves a list. -Recursion does not need to involve lists, but Lisp is designed for lists -and this provides a sense of its primal capabilities. - -@menu -* Every:: -* Accumulate:: -* Keep:: -@end menu - -@node Every, Accumulate, Recursive Patterns, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{every} -@cindex Every, type of recursive pattern -@cindex Recursive pattern: every - -In the @code{every} recursive pattern, an action is performed on every -element of a list. - -@need 1500 -The basic pattern is: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, act on the beginning of the list (the @sc{car} of the list) - @itemize @minus - @item - through a recursive call by the function on the rest (the - @sc{cdr}) of the list, - @item - and, optionally, combine the acted-on element, using @code{cons}, - with the results of acting on the rest. - @end itemize -@end itemize - -@need 1500 -Here is example: - -@smallexample -@group -(defun square-each (numbers-list) - "Square each of a NUMBERS LIST, recursively." - (if (not numbers-list) ; do-again-test - nil - (cons - (* (car numbers-list) (car numbers-list)) - (square-each (cdr numbers-list))))) ; next-step-expression -@end group - -@group -(square-each '(1 2 3)) - @result{} (1 4 9) -@end group -@end smallexample - -@need 1200 -@noindent -If @code{numbers-list} is empty, do nothing. But if it has content, -construct a list combining the square of the first number in the list -with the result of the recursive call. - -(The example follows the pattern exactly: @code{nil} is returned if -the numbers' list is empty. In practice, you would write the -conditional so it carries out the action when the numbers' list is not -empty.) - -The @code{print-elements-recursively} function (@pxref{Recursion with -list, , Recursion with a List}) is another example of an @code{every} -pattern, except in this case, rather than bring the results together -using @code{cons}, we print each element of output. - -@need 1250 -The @code{print-elements-recursively} function looks like this: - -@smallexample -@group -(setq animals '(gazelle giraffe lion tiger)) -@end group - -@group -(defun print-elements-recursively (list) - "Print each element of LIST on a line of its own. -Uses recursion." - (when list ; @r{do-again-test} - (print (car list)) ; @r{body} - (print-elements-recursively ; @r{recursive call} - (cdr list)))) ; @r{next-step-expression} - -(print-elements-recursively animals) -@end group -@end smallexample - -@need 1500 -The pattern for @code{print-elements-recursively} is: - -@itemize @bullet -@item -When the list is empty, do nothing. -@item -But when the list has at least one element, - @itemize @minus - @item - act on the beginning of the list (the @sc{car} of the list), - @item - and make a recursive call on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@node Accumulate, Keep, Every, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{accumulate} -@cindex Accumulate, type of recursive pattern -@cindex Recursive pattern: accumulate - -Another recursive pattern is called the @code{accumulate} pattern. In -the @code{accumulate} recursive pattern, an action is performed on -every element of a list and the result of that action is accumulated -with the results of performing the action on the other elements. - -This is very like the `every' pattern using @code{cons}, except that -@code{cons} is not used, but some other combiner. - -@need 1500 -The pattern is: - -@itemize @bullet -@item -If a list be empty, return zero or some other constant. -@item -Else, act on the beginning of the list (the @sc{car} of the list), - @itemize @minus - @item - and combine that acted-on element, using @code{+} or - some other combining function, with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example: - -@smallexample -@group -(defun add-elements (numbers-list) - "Add the elements of NUMBERS-LIST together." - (if (not numbers-list) - 0 - (+ (car numbers-list) (add-elements (cdr numbers-list))))) -@end group - -@group -(add-elements '(1 2 3 4)) - @result{} 10 -@end group -@end smallexample - -@xref{Files List, , Making a List of Files}, for an example of the -accumulate pattern. - -@node Keep, , Accumulate, Recursive Patterns -@comment node-name, next, previous, up -@unnumberedsubsubsec Recursive Pattern: @emph{keep} -@cindex Keep, type of recursive pattern -@cindex Recursive pattern: keep - -A third recursive pattern is called the @code{keep} pattern. -In the @code{keep} recursive pattern, each element of a list is tested; -the element is acted on and the results are kept only if the element -meets a criterion. - -Again, this is very like the `every' pattern, except the element is -skipped unless it meets a criterion. - -@need 1500 -The pattern has three parts: - -@itemize @bullet -@item -If a list be empty, return @code{nil}. -@item -Else, if the beginning of the list (the @sc{car} of the list) passes - a test - @itemize @minus - @item - act on that element and combine it, using @code{cons} with - @item - a recursive call by the function on the rest (the @sc{cdr}) of the list. - @end itemize -@item -Otherwise, if the beginning of the list (the @sc{car} of the list) fails -the test - @itemize @minus - @item - skip on that element, - @item - and, recursively call the function on the rest (the @sc{cdr}) of the list. - @end itemize -@end itemize - -@need 1500 -Here is an example that uses @code{cond}: - -@smallexample -@group -(defun keep-three-letter-words (word-list) - "Keep three letter words in WORD-LIST." - (cond - ;; First do-again-test: stop-condition - ((not word-list) nil) - - ;; Second do-again-test: when to act - ((eq 3 (length (symbol-name (car word-list)))) - ;; combine acted-on element with recursive call on shorter list - (cons (car word-list) (keep-three-letter-words (cdr word-list)))) - - ;; Third do-again-test: when to skip element; - ;; recursively call shorter list with next-step expression - (t (keep-three-letter-words (cdr word-list))))) -@end group - -@group -(keep-three-letter-words '(one two three four five six)) - @result{} (one two six) -@end group -@end smallexample - -It goes without saying that you need not use @code{nil} as the test for -when to stop; and you can, of course, combine these patterns. - -@node No Deferment, No deferment solution, Recursive Patterns, Recursion -@subsection Recursion without Deferments -@cindex Deferment in recursion -@cindex Recursion without Deferments - -Let's consider again what happens with the @code{triangle-recursively} -function. We will find that the intermediate calculations are -deferred until all can be done. - -@need 800 -Here is the function definition: - -@smallexample -@group -(defun triangle-recursively (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) ; @r{do-again-test} - 1 ; @r{then-part} - (+ number ; @r{else-part} - (triangle-recursively ; @r{recursive call} - (1- number))))) ; @r{next-step-expression} -@end group -@end smallexample - -What happens when we call this function with a argument of 7? - -The first instance of the @code{triangle-recursively} function adds -the number 7 to the value returned by a second instance of -@code{triangle-recursively}, an instance that has been passed an -argument of 6. That is to say, the first calculation is: - -@smallexample -(+ 7 (triangle-recursively 6)) -@end smallexample - -@noindent -The first instance of @code{triangle-recursively}---you may want to -think of it as a little robot---cannot complete its job. It must hand -off the calculation for @code{(triangle-recursively 6)} to a second -instance of the program, to a second robot. This second individual is -completely different from the first one; it is, in the jargon, a -`different instantiation'. Or, put another way, it is a different -robot. It is the same model as the first; it calculates triangle -numbers recursively; but it has a different serial number. - -And what does @code{(triangle-recursively 6)} return? It returns the -number 6 added to the value returned by evaluating -@code{triangle-recursively} with an argument of 5. Using the robot -metaphor, it asks yet another robot to help it. - -@need 800 -Now the total is: - -@smallexample -(+ 7 6 (triangle-recursively 5)) -@end smallexample - -@need 800 -And what happens next? - -@smallexample -(+ 7 6 5 (triangle-recursively 4)) -@end smallexample - -Each time @code{triangle-recursively} is called, except for the last -time, it creates another instance of the program---another robot---and -asks it to make a calculation. - -@need 800 -Eventually, the full addition is set up and performed: - -@smallexample -(+ 7 6 5 4 3 2 1) -@end smallexample - -This design for the function defers the calculation of the first step -until the second can be done, and defers that until the third can be -done, and so on. Each deferment means the computer must remember what -is being waited on. This is not a problem when there are only a few -steps, as in this example. But it can be a problem when there are -more steps. - -@node No deferment solution, , No Deferment, Recursion -@subsection No Deferment Solution -@cindex No deferment solution -@cindex Defermentless solution -@cindex Solution without deferment - -The solution to the problem of deferred operations is to write in a -manner that does not defer operations@footnote{The phrase @dfn{tail -recursive} is used to describe such a process, one that uses -`constant space'.}. This requires -writing to a different pattern, often one that involves writing two -function definitions, an `initialization' function and a `helper' -function. - -The `initialization' function sets up the job; the `helper' function -does the work. - -@need 1200 -Here are the two function definitions for adding up numbers. They are -so simple, I find them hard to understand. - -@smallexample -@group -(defun triangle-initialization (number) - "Return the sum of the numbers 1 through NUMBER inclusive. -This is the `initialization' component of a two function -duo that uses recursion." - (triangle-recursive-helper 0 0 number)) -@end group -@end smallexample - -@smallexample -@group -(defun triangle-recursive-helper (sum counter number) - "Return SUM, using COUNTER, through NUMBER inclusive. -This is the `helper' component of a two function duo -that uses recursion." - (if (> counter number) - sum - (triangle-recursive-helper (+ sum counter) ; @r{sum} - (1+ counter) ; @r{counter} - number))) ; @r{number} -@end group -@end smallexample - -@need 1250 -Install both function definitions by evaluating them, then call -@code{triangle-initialization} with 2 rows: - -@smallexample -@group -(triangle-initialization 2) - @result{} 3 -@end group -@end smallexample - -The `initialization' function calls the first instance of the `helper' -function with three arguments: zero, zero, and a number which is the -number of rows in the triangle. - -The first two arguments passed to the `helper' function are -initialization values. These values are changed when -@code{triangle-recursive-helper} invokes new instances.@footnote{The -jargon is mildly confusing: @code{triangle-recursive-helper} uses a -process that is iterative in a procedure that is recursive. The -process is called iterative because the computer need only record the -three values, @code{sum}, @code{counter}, and @code{number}; the -procedure is recursive because the function `calls itself'. On the -other hand, both the process and the procedure used by -@code{triangle-recursively} are called recursive. The word -`recursive' has different meanings in the two contexts.} - -Let's see what happens when we have a triangle that has one row. (This -triangle will have one pebble in it!) - -@need 1200 -@code{triangle-initialization} will call its helper with -the arguments @w{@code{0 0 1}}. That function will run the conditional -test whether @code{(> counter number)}: - -@smallexample -(> 0 1) -@end smallexample - -@need 1200 -@noindent -and find that the result is false, so it will invoke -the else-part of the @code{if} clause: - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} -@end group -@end smallexample - -@need 800 -@noindent -which will first compute: - -@smallexample -@group -(triangle-recursive-helper (+ 0 0) ; @r{sum} - (1+ 0) ; @r{counter} - 1) ; @r{number} -@exdent which is: - -(triangle-recursive-helper 0 1 1) -@end group -@end smallexample - -Again, @code{(> counter number)} will be false, so again, the Lisp -interpreter will evaluate @code{triangle-recursive-helper}, creating a -new instance with new arguments. - -@need 800 -This new instance will be; - -@smallexample -@group - (triangle-recursive-helper - (+ sum counter) ; @r{sum plus counter} @result{} @r{sum} - (1+ counter) ; @r{increment counter} @result{} @r{counter} - number) ; @r{number stays the same} - -@exdent which is: - -(triangle-recursive-helper 1 2 1) -@end group -@end smallexample - -In this case, the @code{(> counter number)} test will be true! So the -instance will return the value of the sum, which will be 1, as -expected. - -Now, let's pass @code{triangle-initialization} an argument -of 2, to find out how many pebbles there are in a triangle with two rows. - -That function calls @code{(triangle-recursive-helper 0 0 2)}. - -@need 800 -In stages, the instances called will be: - -@smallexample -@group - @r{sum counter number} -(triangle-recursive-helper 0 1 2) - -(triangle-recursive-helper 1 2 2) - -(triangle-recursive-helper 3 3 2) -@end group -@end smallexample - -When the last instance is called, the @code{(> counter number)} test -will be true, so the instance will return the value of @code{sum}, -which will be 3. - -This kind of pattern helps when you are writing functions that can use -many resources in a computer. - -@need 1500 -@node Looping exercise, , Recursion, Loops & Recursion -@section Looping Exercise - -@itemize @bullet -@item -Write a function similar to @code{triangle} in which each row has a -value which is the square of the row number. Use a @code{while} loop. - -@item -Write a function similar to @code{triangle} that multiplies instead of -adds the values. - -@item -Rewrite these two functions recursively. Rewrite these functions -using @code{cond}. - -@c comma in printed title causes problem in Info cross reference -@item -Write a function for Texinfo mode that creates an index entry at the -beginning of a paragraph for every @samp{@@dfn} within the paragraph. -(In a Texinfo file, @samp{@@dfn} marks a definition. This book is -written in Texinfo.) - -Many of the functions you will need are described in two of the -previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing -Text}, and @ref{Yanking, , Yanking Text Back}. If you use -@code{forward-paragraph} to put the index entry at the beginning of -the paragraph, you will have to use @w{@kbd{C-h f}} -(@code{describe-function}) to find out how to make the command go -backwards. - -For more information, see -@ifinfo -@ref{Indicating, , Indicating Definitions, texinfo}. -@end ifinfo -@ifhtml -@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to -a Texinfo manual in the current directory. Or, if you are on the -Internet, see -@uref{http://www.gnu.org/software/texinfo/manual/texinfo/} -@end ifhtml -@iftex -``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU -Documentation Format}. -@end iftex -@end itemize - -@node Regexp Search, Counting Words, Loops & Recursion, Top -@comment node-name, next, previous, up -@chapter Regular Expression Searches -@cindex Searches, illustrating -@cindex Regular expression searches -@cindex Patterns, searching for -@cindex Motion by sentence and paragraph -@cindex Sentences, movement by -@cindex Paragraphs, movement by - -Regular expression searches are used extensively in GNU Emacs. The -two functions, @code{forward-sentence} and @code{forward-paragraph}, -illustrate these searches well. They use regular expressions to find -where to move point. The phrase `regular expression' is often written -as `regexp'. - -Regular expression searches are described in @ref{Regexp Search, , -Regular Expression Search, emacs, The GNU Emacs Manual}, as well as in -@ref{Regular Expressions, , , elisp, The GNU Emacs Lisp Reference -Manual}. In writing this chapter, I am presuming that you have at -least a mild acquaintance with them. The major point to remember is -that regular expressions permit you to search for patterns as well as -for literal strings of characters. For example, the code in -@code{forward-sentence} searches for the pattern of possible -characters that could mark the end of a sentence, and moves point to -that spot. - -Before looking at the code for the @code{forward-sentence} function, it -is worth considering what the pattern that marks the end of a sentence -must be. The pattern is discussed in the next section; following that -is a description of the regular expression search function, -@code{re-search-forward}. The @code{forward-sentence} function -is described in the section following. Finally, the -@code{forward-paragraph} function is described in the last section of -this chapter. @code{forward-paragraph} is a complex function that -introduces several new features. - -@menu -* sentence-end:: The regular expression for @code{sentence-end}. -* re-search-forward:: Very similar to @code{search-forward}. -* forward-sentence:: A straightforward example of regexp search. -* forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. -* Regexp Review:: -* re-search Exercises:: -@end menu - -@node sentence-end, re-search-forward, Regexp Search, Regexp Search -@comment node-name, next, previous, up -@section The Regular Expression for @code{sentence-end} -@findex sentence-end - -The symbol @code{sentence-end} is bound to the pattern that marks the -end of a sentence. What should this regular expression be? - -Clearly, a sentence may be ended by a period, a question mark, or an -exclamation mark. Indeed, in English, only clauses that end with one -of those three characters should be considered the end of a sentence. -This means that the pattern should include the character set: - -@smallexample -[.?!] -@end smallexample - -However, we do not want @code{forward-sentence} merely to jump to a -period, a question mark, or an exclamation mark, because such a character -might be used in the middle of a sentence. A period, for example, is -used after abbreviations. So other information is needed. - -According to convention, you type two spaces after every sentence, but -only one space after a period, a question mark, or an exclamation mark in -the body of a sentence. So a period, a question mark, or an exclamation -mark followed by two spaces is a good indicator of an end of sentence. -However, in a file, the two spaces may instead be a tab or the end of a -line. This means that the regular expression should include these three -items as alternatives. - -@need 800 -This group of alternatives will look like this: - -@smallexample -@group -\\($\\| \\| \\) - ^ ^^ - TAB SPC -@end group -@end smallexample - -@noindent -Here, @samp{$} indicates the end of the line, and I have pointed out -where the tab and two spaces are inserted in the expression. Both are -inserted by putting the actual characters into the expression. - -Two backslashes, @samp{\\}, are required before the parentheses and -vertical bars: the first backslash quotes the following backslash in -Emacs; and the second indicates that the following character, the -parenthesis or the vertical bar, is special. - -@need 1000 -Also, a sentence may be followed by one or more carriage returns, like -this: - -@smallexample -@group -[ -]* -@end group -@end smallexample - -@noindent -Like tabs and spaces, a carriage return is inserted into a regular -expression by inserting it literally. The asterisk indicates that the -@key{RET} is repeated zero or more times. - -But a sentence end does not consist only of a period, a question mark or -an exclamation mark followed by appropriate space: a closing quotation -mark or a closing brace of some kind may precede the space. Indeed more -than one such mark or brace may precede the space. These require a -expression that looks like this: - -@smallexample -[]\"')@}]* -@end smallexample - -In this expression, the first @samp{]} is the first character in the -expression; the second character is @samp{"}, which is preceded by a -@samp{\} to tell Emacs the @samp{"} is @emph{not} special. The last -three characters are @samp{'}, @samp{)}, and @samp{@}}. - -All this suggests what the regular expression pattern for matching the -end of a sentence should be; and, indeed, if we evaluate -@code{sentence-end} we find that it returns the following value: - -@smallexample -@group -sentence-end - @result{} "[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -(Well, not in GNU Emacs 22; that is because of an effort to make the -process simpler and to handle more glyphs and languages. When the -value of @code{sentence-end} is @code{nil}, then use the value defined -by the function @code{sentence-end}. (Here is a use of the difference -between a value and a function in Emacs Lisp.) The function returns a -value constructed from the variables @code{sentence-end-base}, -@code{sentence-end-double-space}, @code{sentence-end-without-period}, -and @code{sentence-end-without-space}. The critical variable is -@code{sentence-end-base}; its global value is similar to the one -described above but it also contains two additional quotation marks. -These have differing degrees of curliness. The -@code{sentence-end-without-period} variable, when true, tells Emacs -that a sentence may end without a period, such as text in Thai.) - -@ignore -@noindent -(Note that here the @key{TAB}, two spaces, and @key{RET} are shown -literally in the pattern.) - -This regular expression can be deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is the three characters, a period, a question -mark and an exclamation mark, within square brackets. The pattern must -begin with one or other of these characters. - -@item []\"')@}]* -The second part of the pattern is the group of closing braces and -quotation marks, which can appear zero or more times. These may follow -the period, question mark or exclamation mark. In a regular expression, -the backslash, @samp{\}, followed by the double quotation mark, -@samp{"}, indicates the class of string-quote characters. Usually, the -double quotation mark is the only character in this class. The -asterisk, @samp{*}, indicates that the items in the previous group (the -group surrounded by square brackets, @samp{[]}) may be repeated zero or -more times. - -@item \\($\\| \\| \\) -The third part of the pattern is one or other of: either the end of a -line, or two blank spaces, or a tab. The double back-slashes are used -to prevent Emacs from reading the parentheses and vertical bars as part -of the search pattern; the parentheses are used to mark the group and -the vertical bars are used to indicated that the patterns to either side -of them are alternatives. The dollar sign is used to indicate the end -of a line and both the two spaces and the tab are each inserted as is to -indicate what they are. - -@item [@key{RET}]* -Finally, the last part of the pattern indicates that the end of the line -or the whitespace following the period, question mark or exclamation -mark may, but need not, be followed by one or more carriage returns. In -the pattern, the carriage return is inserted as an actual carriage -return between square brackets but here it is shown as @key{RET}. -@end table -@end ignore - -@node re-search-forward, forward-sentence, sentence-end, Regexp Search -@comment node-name, next, previous, up -@section The @code{re-search-forward} Function -@findex re-search-forward - -The @code{re-search-forward} function is very like the -@code{search-forward} function. (@xref{search-forward, , The -@code{search-forward} Function}.) - -@code{re-search-forward} searches for a regular expression. If the -search is successful, it leaves point immediately after the last -character in the target. If the search is backwards, it leaves point -just before the first character in the target. You may tell -@code{re-search-forward} to return @code{t} for true. (Moving point -is therefore a `side effect'.) - -Like @code{search-forward}, the @code{re-search-forward} function takes -four arguments: - -@enumerate -@item -The first argument is the regular expression that the function searches -for. The regular expression will be a string between quotations marks. - -@item -The optional second argument limits how far the function will search; it is a -bound, which is specified as a position in the buffer. - -@item -The optional third argument specifies how the function responds to -failure: @code{nil} as the third argument causes the function to -signal an error (and print a message) when the search fails; any other -value causes it to return @code{nil} if the search fails and @code{t} -if the search succeeds. - -@item -The optional fourth argument is the repeat count. A negative repeat -count causes @code{re-search-forward} to search backwards. -@end enumerate - -@need 800 -The template for @code{re-search-forward} looks like this: - -@smallexample -@group -(re-search-forward "@var{regular-expression}" - @var{limit-of-search} - @var{what-to-do-if-search-fails} - @var{repeat-count}) -@end group -@end smallexample - -The second, third, and fourth arguments are optional. However, if you -want to pass a value to either or both of the last two arguments, you -must also pass a value to all the preceding arguments. Otherwise, the -Lisp interpreter will mistake which argument you are passing the value -to. - -@need 1200 -In the @code{forward-sentence} function, the regular expression will be -the value of the variable @code{sentence-end}. In simple form, that is: - -@smallexample -@group -"[.?!][]\"')@}]*\\($\\| \\| \\)[ -]*" -@end group -@end smallexample - -@noindent -The limit of the search will be the end of the paragraph (since a -sentence cannot go beyond a paragraph). If the search fails, the -function will return @code{nil}; and the repeat count will be provided -by the argument to the @code{forward-sentence} function. - -@node forward-sentence, forward-paragraph, re-search-forward, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-sentence} -@findex forward-sentence - -The command to move the cursor forward a sentence is a straightforward -illustration of how to use regular expression searches in Emacs Lisp. -Indeed, the function looks longer and more complicated than it is; this -is because the function is designed to go backwards as well as forwards; -and, optionally, over more than one sentence. The function is usually -bound to the key command @kbd{M-e}. - -@menu -* Complete forward-sentence:: -* fwd-sentence while loops:: Two @code{while} loops. -* fwd-sentence re-search:: A regular expression search. -@end menu - -@node Complete forward-sentence, fwd-sentence while loops, forward-sentence, forward-sentence -@ifnottex -@unnumberedsubsec Complete @code{forward-sentence} function definition -@end ifnottex - -@need 1250 -Here is the code for @code{forward-sentence}: - -@c in GNU Emacs 22 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next `sentence-end'. With argument, repeat. -With negative argument, move backward repeatedly to `sentence-beginning'. - -The variable `sentence-end' is a regular expression that matches ends of -sentences. Also, every paragraph boundary terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) - (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - (if (and (re-search-backward sentence-end par-beg t) - (or (< (match-end 0) pos) - (re-search-backward sentence-end par-beg t))) - (goto-char (match-end 0)) - (goto-char par-beg))) - (setq arg (1+ arg))) -@end group -@group - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg))) - (constrain-to-field nil opoint t))) -@end group -@end smallexample - -@ignore -GNU Emacs 21 -@smallexample -@group -(defun forward-sentence (&optional arg) - "Move forward to next sentence-end. With argument, repeat. -With negative argument, move backward repeatedly to sentence-beginning. -Sentence ends are identified by the value of sentence-end -treated as a regular expression. Also, every paragraph boundary -terminates sentences as well." -@end group -@group - (interactive "p") - (or arg (setq arg 1)) - (while (< arg 0) - (let ((par-beg - (save-excursion (start-of-paragraph-text) (point)))) - (if (re-search-backward - (concat sentence-end "[^ \t\n]") par-beg t) - (goto-char (1- (match-end 0))) - (goto-char par-beg))) - (setq arg (1+ arg))) - (while (> arg 0) - (let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) - (setq arg (1- arg)))) -@end group -@end smallexample -@end ignore - -The function looks long at first sight and it is best to look at its -skeleton first, and then its muscle. The way to see the skeleton is to -look at the expressions that start in the left-most columns: - -@smallexample -@group -(defun forward-sentence (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let ((opoint (point)) (sentence-end (sentence-end))) - (while (< arg 0) - (let ((pos (point)) - (par-beg (save-excursion (start-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-backwards} - (while (> arg 0) - (let ((par-end (save-excursion (end-of-paragraph-text) (point)))) - @var{rest-of-body-of-while-loop-when-going-forwards} - @var{handle-forms-and-equivalent} -@end group -@end smallexample - -This looks much simpler! The function definition consists of -documentation, an @code{interactive} expression, an @code{or} -expression, a @code{let} expression, and @code{while} loops. - -Let's look at each of these parts in turn. - -We note that the documentation is thorough and understandable. - -The function has an @code{interactive "p"} declaration. This means -that the processed prefix argument, if any, is passed to the -function as its argument. (This will be a number.) If the function -is not passed an argument (it is optional) then the argument -@code{arg} will be bound to 1. - -When @code{forward-sentence} is called non-interactively without an -argument, @code{arg} is bound to @code{nil}. The @code{or} expression -handles this. What it does is either leave the value of @code{arg} as -it is, but only if @code{arg} is bound to a value; or it sets the -value of @code{arg} to 1, in the case when @code{arg} is bound to -@code{nil}. - -Next is a @code{let}. That specifies the values of two local -variables, @code{point} and @code{sentence-end}. The local value of -point, from before the search, is used in the -@code{constrain-to-field} function which handles forms and -equivalents. The @code{sentence-end} variable is set by the -@code{sentence-end} function. - -@node fwd-sentence while loops, fwd-sentence re-search, Complete forward-sentence, forward-sentence -@unnumberedsubsec The @code{while} loops - -Two @code{while} loops follow. The first @code{while} has a -true-or-false-test that tests true if the prefix argument for -@code{forward-sentence} is a negative number. This is for going -backwards. The body of this loop is similar to the body of the second -@code{while} clause, but it is not exactly the same. We will skip -this @code{while} loop and concentrate on the second @code{while} -loop. - -@need 1500 -The second @code{while} loop is for moving point forward. Its skeleton -looks like this: - -@smallexample -@group -(while (> arg 0) ; @r{true-or-false-test} - (let @var{varlist} - (if (@var{true-or-false-test}) - @var{then-part} - @var{else-part} - (setq arg (1- arg)))) ; @code{while} @r{loop decrementer} -@end group -@end smallexample - -The @code{while} loop is of the decrementing kind. -(@xref{Decrementing Loop, , A Loop with a Decrementing Counter}.) It -has a true-or-false-test that tests true so long as the counter (in -this case, the variable @code{arg}) is greater than zero; and it has a -decrementer that subtracts 1 from the value of the counter every time -the loop repeats. - -If no prefix argument is given to @code{forward-sentence}, which is -the most common way the command is used, this @code{while} loop will -run once, since the value of @code{arg} will be 1. - -The body of the @code{while} loop consists of a @code{let} expression, -which creates and binds a local variable, and has, as its body, an -@code{if} expression. - -@need 1250 -The body of the @code{while} loop looks like this: - -@smallexample -@group -(let ((par-end - (save-excursion (end-of-paragraph-text) (point)))) - (if (re-search-forward sentence-end par-end t) - (skip-chars-backward " \t\n") - (goto-char par-end))) -@end group -@end smallexample - -The @code{let} expression creates and binds the local variable -@code{par-end}. As we shall see, this local variable is designed to -provide a bound or limit to the regular expression search. If the -search fails to find a proper sentence ending in the paragraph, it will -stop on reaching the end of the paragraph. - -But first, let us examine how @code{par-end} is bound to the value of -the end of the paragraph. What happens is that the @code{let} sets the -value of @code{par-end} to the value returned when the Lisp interpreter -evaluates the expression - -@smallexample -@group -(save-excursion (end-of-paragraph-text) (point)) -@end group -@end smallexample - -@noindent -In this expression, @code{(end-of-paragraph-text)} moves point to the -end of the paragraph, @code{(point)} returns the value of point, and then -@code{save-excursion} restores point to its original position. Thus, -the @code{let} binds @code{par-end} to the value returned by the -@code{save-excursion} expression, which is the position of the end of -the paragraph. (The @code{end-of-paragraph-text} function uses -@code{forward-paragraph}, which we will discuss shortly.) - -@need 1200 -Emacs next evaluates the body of the @code{let}, which is an @code{if} -expression that looks like this: - -@smallexample -@group -(if (re-search-forward sentence-end par-end t) ; @r{if-part} - (skip-chars-backward " \t\n") ; @r{then-part} - (goto-char par-end))) ; @r{else-part} -@end group -@end smallexample - -The @code{if} tests whether its first argument is true and if so, -evaluates its then-part; otherwise, the Emacs Lisp interpreter -evaluates the else-part. The true-or-false-test of the @code{if} -expression is the regular expression search. - -It may seem odd to have what looks like the `real work' of -the @code{forward-sentence} function buried here, but this is a common -way this kind of operation is carried out in Lisp. - -@node fwd-sentence re-search, , fwd-sentence while loops, forward-sentence -@unnumberedsubsec The regular expression search - -The @code{re-search-forward} function searches for the end of the -sentence, that is, for the pattern defined by the @code{sentence-end} -regular expression. If the pattern is found---if the end of the sentence is -found---then the @code{re-search-forward} function does two things: - -@enumerate -@item -The @code{re-search-forward} function carries out a side effect, which -is to move point to the end of the occurrence found. - -@item -The @code{re-search-forward} function returns a value of true. This is -the value received by the @code{if}, and means that the search was -successful. -@end enumerate - -@noindent -The side effect, the movement of point, is completed before the -@code{if} function is handed the value returned by the successful -conclusion of the search. - -When the @code{if} function receives the value of true from a successful -call to @code{re-search-forward}, the @code{if} evaluates the then-part, -which is the expression @code{(skip-chars-backward " \t\n")}. This -expression moves backwards over any blank spaces, tabs or carriage -returns until a printed character is found and then leaves point after -the character. Since point has already been moved to the end of the -pattern that marks the end of the sentence, this action leaves point -right after the closing printed character of the sentence, which is -usually a period. - -On the other hand, if the @code{re-search-forward} function fails to -find a pattern marking the end of the sentence, the function returns -false. The false then causes the @code{if} to evaluate its third -argument, which is @code{(goto-char par-end)}: it moves point to the -end of the paragraph. - -(And if the text is in a form or equivalent, and point may not move -fully, then the @code{constrain-to-field} function comes into play.) - -Regular expression searches are exceptionally useful and the pattern -illustrated by @code{re-search-forward}, in which the search is the -test of an @code{if} expression, is handy. You will see or write code -incorporating this pattern often. - -@node forward-paragraph, etags, forward-sentence, Regexp Search -@comment node-name, next, previous, up -@section @code{forward-paragraph}: a Goldmine of Functions -@findex forward-paragraph - -@ignore -@c in GNU Emacs 22 -(defun forward-paragraph (&optional arg) - "Move forward to end of paragraph. -With argument ARG, do it ARG times; -a negative argument ARG = -N means move backward N paragraphs. - -A line which `paragraph-start' matches either separates paragraphs -\(if `paragraph-separate' matches it also) or is the first line of a paragraph. -A paragraph end is the beginning of a line which is not part of the paragraph -to which the end of the previous line belongs, or the end of the buffer. -Returns the count of paragraphs left to move." - (interactive "p") - (or arg (setq arg 1)) - (let* ((opoint (point)) - (fill-prefix-regexp - (and fill-prefix (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix))) - ;; Remove ^ from paragraph-start and paragraph-sep if they are there. - ;; These regexps shouldn't be anchored, because we look for them - ;; starting at the left-margin. This allows paragraph commands to - ;; work normally with indented text. - ;; This hack will not find problem cases like "whatever\\|^something". - (parstart (if (and (not (equal "" paragraph-start)) - (equal ?^ (aref paragraph-start 0))) - (substring paragraph-start 1) - paragraph-start)) - (parsep (if (and (not (equal "" paragraph-separate)) - (equal ?^ (aref paragraph-separate 0))) - (substring paragraph-separate 1) - paragraph-separate)) - (parsep - (if fill-prefix-regexp - (concat parsep "\\|" - fill-prefix-regexp "[ \t]*$") - parsep)) - ;; This is used for searching. - (sp-parstart (concat "^[ \t]*\\(?:" parstart "\\|" parsep "\\)")) - start found-start) - (while (and (< arg 0) (not (bobp))) - (if (and (not (looking-at parsep)) - (re-search-backward "^\n" (max (1- (point)) (point-min)) t) - (looking-at parsep)) - (setq arg (1+ arg)) - (setq start (point)) - ;; Move back over paragraph-separating lines. - (forward-char -1) (beginning-of-line) - (while (and (not (bobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line -1)) - (if (bobp) - nil - (setq arg (1+ arg)) - ;; Go to end of the previous (non-separating) line. - (end-of-line) - ;; Search back for line that starts or separates paragraphs. - (if (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (let (multiple-lines) - (while (and (progn (beginning-of-line) (not (bobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (looking-at fill-prefix-regexp)) - (unless (= (point) start) - (setq multiple-lines t)) - (forward-line -1)) - (move-to-left-margin) - ;; This deleted code caused a long hanging-indent line - ;; not to be filled together with the following lines. - ;; ;; Don't move back over a line before the paragraph - ;; ;; which doesn't start with fill-prefix - ;; ;; unless that is the only line we've moved over. - ;; (and (not (looking-at fill-prefix-regexp)) - ;; multiple-lines - ;; (forward-line 1)) - (not (bobp))) - (while (and (re-search-backward sp-parstart nil 1) - (setq found-start t) - ;; Found a candidate, but need to check if it is a - ;; REAL parstart. - (progn (setq start (point)) - (move-to-left-margin) - (not (looking-at parsep))) - (not (and (looking-at parstart) - (or (not use-hard-newlines) - (bobp) - (get-text-property - (1- start) 'hard))))) - (setq found-start nil) - (goto-char start)) - found-start) - ;; Found one. - (progn - ;; Move forward over paragraph separators. - ;; We know this cannot reach the place we started - ;; because we know we moved back over a non-separator. - (while (and (not (eobp)) - (progn (move-to-left-margin) - (looking-at parsep))) - (forward-line 1)) - ;; If line before paragraph is just margin, back up to there. - (end-of-line 0) - (if (> (current-column) (current-left-margin)) - (forward-char 1) - (skip-chars-backward " \t") - (if (not (bolp)) - (forward-line 1)))) - ;; No starter or separator line => use buffer beg. - (goto-char (point-min)))))) - - (while (and (> arg 0) (not (eobp))) - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - (if (< (point) (point-max)) - (goto-char start)))) - (constrain-to-field nil opoint t) - ;; Return the number of steps that could not be done. - arg)) -@end ignore - -The @code{forward-paragraph} function moves point forward to the end -of the paragraph. It is usually bound to @kbd{M-@}} and makes use of a -number of functions that are important in themselves, including -@code{let*}, @code{match-beginning}, and @code{looking-at}. - -The function definition for @code{forward-paragraph} is considerably -longer than the function definition for @code{forward-sentence} -because it works with a paragraph, each line of which may begin with a -fill prefix. - -A fill prefix consists of a string of characters that are repeated at -the beginning of each line. For example, in Lisp code, it is a -convention to start each line of a paragraph-long comment with -@samp{;;; }. In Text mode, four blank spaces make up another common -fill prefix, creating an indented paragraph. (@xref{Fill Prefix, , , -emacs, The GNU Emacs Manual}, for more information about fill -prefixes.) - -The existence of a fill prefix means that in addition to being able to -find the end of a paragraph whose lines begin on the left-most -column, the @code{forward-paragraph} function must be able to find the -end of a paragraph when all or many of the lines in the buffer begin -with the fill prefix. - -Moreover, it is sometimes practical to ignore a fill prefix that -exists, especially when blank lines separate paragraphs. -This is an added complication. - -@menu -* forward-paragraph in brief:: Key parts of the function definition. -* fwd-para let:: The @code{let*} expression. -* fwd-para while:: The forward motion @code{while} loop. -@end menu - -@node forward-paragraph in brief, fwd-para let, forward-paragraph, forward-paragraph -@ifnottex -@unnumberedsubsec Shortened @code{forward-paragraph} function definition -@end ifnottex - -Rather than print all of the @code{forward-paragraph} function, we -will only print parts of it. Read without preparation, the function -can be daunting! - -@need 800 -In outline, the function looks like this: - -@smallexample -@group -(defun forward-paragraph (&optional arg) - "@var{documentation}@dots{}" - (interactive "p") - (or arg (setq arg 1)) - (let* - @var{varlist} - (while (and (< arg 0) (not (bobp))) ; @r{backward-moving-code} - @dots{} - (while (and (> arg 0) (not (eobp))) ; @r{forward-moving-code} - @dots{} -@end group -@end smallexample - -The first parts of the function are routine: the function's argument -list consists of one optional argument. Documentation follows. - -The lower case @samp{p} in the @code{interactive} declaration means -that the processed prefix argument, if any, is passed to the function. -This will be a number, and is the repeat count of how many paragraphs -point will move. The @code{or} expression in the next line handles -the common case when no argument is passed to the function, which occurs -if the function is called from other code rather than interactively. -This case was described earlier. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Now we reach the end of the -familiar part of this function. - -@node fwd-para let, fwd-para while, forward-paragraph in brief, forward-paragraph -@unnumberedsubsec The @code{let*} expression - -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is a different than @code{let}. The -symbol is @code{let*} not @code{let}. - -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and -@code{found-start}. - -The variable @code{parsep} appears twice, first, to remove instances -of @samp{^}, and second, to handle fill prefixes. - -The variable @code{opoint} is just the value of @code{point}. As you -can guess, it is used in a @code{constrain-to-field} expression, just -as in @code{forward-sentence}. - -The variable @code{fill-prefix-regexp} is set to the value returned by -evaluating the following list: - -@smallexample -@group -(and fill-prefix - (not (equal fill-prefix "")) - (not paragraph-ignore-fill-prefix) - (regexp-quote fill-prefix)) -@end group -@end smallexample - -@noindent -This is an expression whose first element is the @code{and} special form. - -As we learned earlier (@pxref{kill-new function, , The @code{kill-new} -function}), the @code{and} special form evaluates each of its -arguments until one of the arguments returns a value of @code{nil}, in -which case the @code{and} expression returns @code{nil}; however, if -none of the arguments returns a value of @code{nil}, the value -resulting from evaluating the last argument is returned. (Since such -a value is not @code{nil}, it is considered true in Lisp.) In other -words, an @code{and} expression returns a true value only if all its -arguments are true. -@findex and - -In this case, the variable @code{fill-prefix-regexp} is bound to a -non-@code{nil} value only if the following four expressions produce a -true (i.e., a non-@code{nil}) value when they are evaluated; otherwise, -@code{fill-prefix-regexp} is bound to @code{nil}. - -@table @code -@item fill-prefix -When this variable is evaluated, the value of the fill prefix, if any, -is returned. If there is no fill prefix, this variable returns -@code{nil}. - -@item (not (equal fill-prefix "") -This expression checks whether an existing fill prefix is an empty -string, that is, a string with no characters in it. An empty string is -not a useful fill prefix. - -@item (not paragraph-ignore-fill-prefix) -This expression returns @code{nil} if the variable -@code{paragraph-ignore-fill-prefix} has been turned on by being set to a -true value such as @code{t}. - -@item (regexp-quote fill-prefix) -This is the last argument to the @code{and} special form. If all the -arguments to the @code{and} are true, the value resulting from -evaluating this expression will be returned by the @code{and} expression -and bound to the variable @code{fill-prefix-regexp}, -@end table - -@findex regexp-quote -@noindent -The result of evaluating this @code{and} expression successfully is that -@code{fill-prefix-regexp} will be bound to the value of -@code{fill-prefix} as modified by the @code{regexp-quote} function. -What @code{regexp-quote} does is read a string and return a regular -expression that will exactly match the string and match nothing else. -This means that @code{fill-prefix-regexp} will be set to a value that -will exactly match the fill prefix if the fill prefix exists. -Otherwise, the variable will be set to @code{nil}. - -The next two local variables in the @code{let*} expression are -designed to remove instances of @samp{^} from @code{parstart} and -@code{parsep}, the local variables which indicate the paragraph start -and the paragraph separator. The next expression sets @code{parsep} -again. That is to handle fill prefixes. - -This is the setting that requires the definition call @code{let*} -rather than @code{let}. The true-or-false-test for the @code{if} -depends on whether the variable @code{fill-prefix-regexp} evaluates to -@code{nil} or some other value. - -If @code{fill-prefix-regexp} does not have a value, Emacs evaluates -the else-part of the @code{if} expression and binds @code{parsep} to -its local value. (@code{parsep} is a regular expression that matches -what separates paragraphs.) - -But if @code{fill-prefix-regexp} does have a value, Emacs evaluates -the then-part of the @code{if} expression and binds @code{parsep} to a -regular expression that includes the @code{fill-prefix-regexp} as part -of the pattern. - -Specifically, @code{parsep} is set to the original value of the -paragraph separate regular expression concatenated with an alternative -expression that consists of the @code{fill-prefix-regexp} followed by -optional whitespace to the end of the line. The whitespace is defined -by @w{@code{"[ \t]*$"}}.) The @samp{\\|} defines this portion of the -regexp as an alternative to @code{parsep}. - -According to a comment in the code, the next local variable, -@code{sp-parstart}, is used for searching, and then the final two, -@code{start} and @code{found-start}, are set to @code{nil}. - -Now we get into the body of the @code{let*}. The first part of the body -of the @code{let*} deals with the case when the function is given a -negative argument and is therefore moving backwards. We will skip this -section. - -@node fwd-para while, , fwd-para let, forward-paragraph -@unnumberedsubsec The forward motion @code{while} loop - -The second part of the body of the @code{let*} deals with forward -motion. It is a @code{while} loop that repeats itself so long as the -value of @code{arg} is greater than zero. In the most common use of -the function, the value of the argument is 1, so the body of the -@code{while} loop is evaluated exactly once, and the cursor moves -forward one paragraph. - -@ignore -(while (and (> arg 0) (not (eobp))) - - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) - - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart. - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) - - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) - - (if (< (point) (point-max)) - (goto-char start)))) -@end ignore - -This part handles three situations: when point is between paragraphs, -when there is a fill prefix and when there is no fill prefix. - -@need 800 -The @code{while} loop looks like this: - -@smallexample -@group -;; @r{going forwards and not at the end of the buffer} -(while (and (> arg 0) (not (eobp))) - - ;; @r{between paragraphs} - ;; Move forward over separator lines... - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (looking-at parsep)) - (forward-line 1)) - ;; @r{This decrements the loop} - (unless (eobp) (setq arg (1- arg))) - ;; ... and one more line. - (forward-line 1) -@end group - -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group - -@group - ;; There is no fill prefix; - ;; we go forward character by character - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group - -@group - ;; and if there is no fill prefix and if we are not at the end, - ;; go to whatever was found in the regular expression search - ;; for sp-parstart - (if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@findex eobp -We can see that this is a decrementing counter @code{while} loop, -using the expression @code{(setq arg (1- arg))} as the decrementer. -That expression is not far from the @code{while}, but is hidden in -another Lisp macro, an @code{unless} macro. Unless we are at the end -of the buffer --- that is what the @code{eobp} function determines; it -is an abbreviation of @samp{End Of Buffer P} --- we decrease the value -of @code{arg} by one. - -(If we are at the end of the buffer, we cannot go forward any more and -the next loop of the @code{while} expression will test false since the -test is an @code{and} with @code{(not (eobp))}. The @code{not} -function means exactly as you expect; it is another name for -@code{null}, a function that returns true when its argument is false.) - -Interestingly, the loop count is not decremented until we leave the -space between paragraphs, unless we come to the end of buffer or stop -seeing the local value of the paragraph separator. - -That second @code{while} also has a @code{(move-to-left-margin)} -expression. The function is self-explanatory. It is inside a -@code{progn} expression and not the last element of its body, so it is -only invoked for its side effect, which is to move point to the left -margin of the current line. - -@findex looking-at -The @code{looking-at} function is also self-explanatory; it returns -true if the text after point matches the regular expression given as -its argument. - -The rest of the body of the loop looks difficult at first, but makes -sense as you come to understand it. - -@need 800 -First consider what happens if there is a fill prefix: - -@smallexample -@group - (if fill-prefix-regexp - ;; There is a fill prefix; it overrides parstart; - ;; we go forward line by line - (while (and (not (eobp)) - (progn (move-to-left-margin) (not (eobp))) - (not (looking-at parsep)) - (looking-at fill-prefix-regexp)) - (forward-line 1)) -@end group -@end smallexample - -@noindent -This expression moves point forward line by line so long -as four conditions are true: - -@enumerate -@item -Point is not at the end of the buffer. - -@item -We can move to the left margin of the text and are -not at the end of the buffer. - -@item -The text following point does not separate paragraphs. - -@item -The pattern following point is the fill prefix regular expression. -@end enumerate - -The last condition may be puzzling, until you remember that point was -moved to the beginning of the line early in the @code{forward-paragraph} -function. This means that if the text has a fill prefix, the -@code{looking-at} function will see it. - -@need 1250 -Consider what happens when there is no fill prefix. - -@smallexample -@group - (while (and (re-search-forward sp-parstart nil 1) - (progn (setq start (match-beginning 0)) - (goto-char start) - (not (eobp))) - (progn (move-to-left-margin) - (not (looking-at parsep))) - (or (not (looking-at parstart)) - (and use-hard-newlines - (not (get-text-property (1- start) 'hard))))) - (forward-char 1)) -@end group -@end smallexample - -@noindent -This @code{while} loop has us searching forward for -@code{sp-parstart}, which is the combination of possible whitespace -with a the local value of the start of a paragraph or of a paragraph -separator. (The latter two are within an expression starting -@code{\(?:} so that they are not referenced by the -@code{match-beginning} function.) - -@need 800 -The two expressions, - -@smallexample -@group -(setq start (match-beginning 0)) -(goto-char start) -@end group -@end smallexample - -@noindent -mean go to the start of the text matched by the regular expression -search. - -The @code{(match-beginning 0)} expression is new. It returns a number -specifying the location of the start of the text that was matched by -the last search. - -The @code{match-beginning} function is used here because of a -characteristic of a forward search: a successful forward search, -regardless of whether it is a plain search or a regular expression -search, moves point to the end of the text that is found. In this -case, a successful search moves point to the end of the pattern for -@code{sp-parstart}. - -However, we want to put point at the end of the current paragraph, not -somewhere else. Indeed, since the search possibly includes the -paragraph separator, point may end up at the beginning of the next one -unless we use an expression that includes @code{match-beginning}. - -@findex match-beginning -When given an argument of 0, @code{match-beginning} returns the -position that is the start of the text matched by the most recent -search. In this case, the most recent search looks for -@code{sp-parstart}. The @code{(match-beginning 0)} expression returns -the beginning position of that pattern, rather than the end position -of that pattern. - -(Incidentally, when passed a positive number as an argument, the -@code{match-beginning} function returns the location of point at that -parenthesized expression in the last search unless that parenthesized -expression begins with @code{\(?:}. I don't know why @code{\(?:} -appears here since the argument is 0.) - -@need 1250 -The last expression when there is no fill prefix is - -@smallexample -@group -(if (< (point) (point-max)) - (goto-char start)))) -@end group -@end smallexample - -@noindent -This says that if there is no fill prefix and if we are not at the -end, point should move to the beginning of whatever was found by the -regular expression search for @code{sp-parstart}. - -The full definition for the @code{forward-paragraph} function not only -includes code for going forwards, but also code for going backwards. - -If you are reading this inside of GNU Emacs and you want to see the -whole function, you can type @kbd{C-h f} (@code{describe-function}) -and the name of the function. This gives you the function -documentation and the name of the library containing the function's -source. Place point over the name of the library and press the RET -key; you will be taken directly to the source. (Be sure to install -your sources! Without them, you are like a person who tries to drive -a car with his eyes shut!) - -@node etags, Regexp Review, forward-paragraph, Regexp Search -@section Create Your Own @file{TAGS} File -@findex etags -@cindex @file{TAGS} file, create own - -Besides @kbd{C-h f} (@code{describe-function}), another way to see the -source of a function is to type @kbd{M-.} (@code{find-tag}) and the -name of the function when prompted for it. This is a good habit to -get into. The @kbd{M-.} (@code{find-tag}) command takes you directly -to the source for a function, variable, or node. The function depends -on tags tables to tell it where to go. - -If the @code{find-tag} function first asks you for the name of a -@file{TAGS} table, give it the name of a @file{TAGS} file such as -@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your -@file{TAGS} file depends on how your copy of Emacs was installed. I -just told you the location that provides both my C and my Emacs Lisp -sources.) - -You can also create your own @file{TAGS} file for directories that -lack one. - -You often need to build and install tags tables yourself. They are -not built automatically. A tags table is called a @file{TAGS} file; -the name is in upper case letters. - -You can create a @file{TAGS} file by calling the @code{etags} program -that comes as a part of the Emacs distribution. Usually, @code{etags} -is compiled and installed when Emacs is built. (@code{etags} is not -an Emacs Lisp function or a part of Emacs; it is a C program.) - -@need 1250 -To create a @file{TAGS} file, first switch to the directory in which -you want to create the file. In Emacs you can do this with the -@kbd{M-x cd} command, or by visiting a file in the directory, or by -listing the directory with @kbd{C-x d} (@code{dired}). Then run the -compile command, with @w{@code{etags *.el}} as the command to execute - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -@noindent -to create a @file{TAGS} file for Emacs Lisp. - -For example, if you have a large number of files in your -@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, -of which I load 12---you can create a @file{TAGS} file for the Emacs -Lisp files in that directory. - -@need 1250 -The @code{etags} program takes all the usual shell `wildcards'. For -example, if you have two directories for which you want a single -@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where -@file{../elisp/} is the second directory: - -@smallexample -M-x compile RET etags *.el ../elisp/*.el RET -@end smallexample - -@need 1250 -Type - -@smallexample -M-x compile RET etags --help RET -@end smallexample - -@noindent -to see a list of the options accepted by @code{etags} as well as a -list of supported languages. - -The @code{etags} program handles more than 20 languages, including -Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, -LaTeX, Pascal, Perl, Postscript, Python, TeX, Texinfo, makefiles, and -most assemblers. The program has no switches for specifying the -language; it recognizes the language in an input file according to its -file name and contents. - -@file{etags} is very helpful when you are writing code yourself and -want to refer back to functions you have already written. Just run -@code{etags} again at intervals as you write new functions, so they -become part of the @file{TAGS} file. - -If you think an appropriate @file{TAGS} file already exists for what -you want, but do not know where it is, you can use the @code{locate} -program to attempt to find it. - -Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list -for you the full path names of all your @file{TAGS} files. On my -system, this command lists 34 @file{TAGS} files. On the other hand, a -`plain vanilla' system I recently installed did not contain any -@file{TAGS} files. - -If the tags table you want has been created, you can use the @code{M-x -visit-tags-table} command to specify it. Otherwise, you will need to -create the tag table yourself and then use @code{M-x -visit-tags-table}. - -@subsubheading Building Tags in the Emacs sources -@cindex Building Tags in the Emacs sources -@cindex Tags in the Emacs sources -@findex make tags - -The GNU Emacs sources come with a @file{Makefile} that contains a -sophisticated @code{etags} command that creates, collects, and merges -tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The -@file{src/} directory is below the top level of your Emacs directory.) - -@need 1250 -To build this @file{TAGS} file, go to the top level of your Emacs -source directory and run the compile command @code{make tags}: - -@smallexample -M-x compile RET make tags RET -@end smallexample - -@noindent -(The @code{make tags} command works well with the GNU Emacs sources, -as well as with some other source packages.) - -For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs -Manual}. - -@node Regexp Review, re-search Exercises, etags, Regexp Search -@comment node-name, next, previous, up -@section Review - -Here is a brief summary of some recently introduced functions. - -@table @code -@item while -Repeatedly evaluate the body of the expression so long as the first -element of the body tests true. Then return @code{nil}. (The -expression is evaluated only for its side effects.) - -@need 1250 -For example: - -@smallexample -@group -(let ((foo 2)) - (while (> foo 0) - (insert (format "foo is %d.\n" foo)) - (setq foo (1- foo)))) - - @result{} foo is 2. - foo is 1. - nil -@end group -@end smallexample - -@noindent -(The @code{insert} function inserts its arguments at point; the -@code{format} function returns a string formatted from its arguments -the way @code{message} formats its arguments; @code{\n} produces a new -line.) - -@item re-search-forward -Search for a pattern, and if the pattern is found, move point to rest -just after it. - -@noindent -Takes four arguments, like @code{search-forward}: - -@enumerate -@item -A regular expression that specifies the pattern to search for. -(Remember to put quotation marks around this argument!) - -@item -Optionally, the limit of the search. - -@item -Optionally, what to do if the search fails, return @code{nil} or an -error message. - -@item -Optionally, how many times to repeat the search; if negative, the -search goes backwards. -@end enumerate - -@item let* -Bind some variables locally to particular values, -and then evaluate the remaining arguments, returning the value of the -last one. While binding the local variables, use the local values of -variables bound earlier, if any. - -@need 1250 -For example: - -@smallexample -@group -(let* ((foo 7) - (bar (* 3 foo))) - (message "`bar' is %d." bar)) - @result{} `bar' is 21. -@end group -@end smallexample - -@item match-beginning -Return the position of the start of the text found by the last regular -expression search. - -@item looking-at -Return @code{t} for true if the text after point matches the argument, -which should be a regular expression. - -@item eobp -Return @code{t} for true if point is at the end of the accessible part -of a buffer. The end of the accessible part is the end of the buffer -if the buffer is not narrowed; it is the end of the narrowed part if -the buffer is narrowed. -@end table - -@need 1500 -@node re-search Exercises, , Regexp Review, Regexp Search -@section Exercises with @code{re-search-forward} - -@itemize @bullet -@item -Write a function to search for a regular expression that matches two -or more blank lines in sequence. - -@item -Write a function to search for duplicated words, such as `the the'. -@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, for information on how to write a regexp (a regular -expression) to match a string that is composed of two identical -halves. You can devise several regexps; some are better than others. -The function I use is described in an appendix, along with several -regexps. @xref{the-the, , @code{the-the} Duplicated Words Function}. -@end itemize - -@node Counting Words, Words in a defun, Regexp Search, Top -@chapter Counting: Repetition and Regexps -@cindex Repetition for word counting -@cindex Regular expressions for word counting - -Repetition and regular expression searches are powerful tools that you -often use when you write code in Emacs Lisp. This chapter illustrates -the use of regular expression searches through the construction of -word count commands using @code{while} loops and recursion. - -@menu -* Why Count Words:: -* count-words-region:: Use a regexp, but find a problem. -* recursive-count-words:: Start with case of no words in region. -* Counting Exercise:: -@end menu - -@node Why Count Words, count-words-region, Counting Words, Counting Words -@ifnottex -@unnumberedsec Counting words -@end ifnottex - -The standard Emacs distribution contains a function for counting the -number of lines within a region. However, there is no corresponding -function for counting words. - -Certain types of writing ask you to count words. Thus, if you write -an essay, you may be limited to 800 words; if you write a novel, you -may discipline yourself to write 1000 words a day. It seems odd to me -that Emacs lacks a word count command. Perhaps people use Emacs -mostly for code or types of documentation that do not require word -counts; or perhaps they restrict themselves to the operating system -word count command, @code{wc}. Alternatively, people may follow -the publishers' convention and compute a word count by dividing the -number of characters in a document by five. In any event, here are -commands to count words. - -@node count-words-region, recursive-count-words, Why Count Words, Counting Words -@comment node-name, next, previous, up -@section The @code{count-words-region} Function -@findex count-words-region - -A word count command could count words in a line, paragraph, region, -or buffer. What should the command cover? You could design the -command to count the number of words in a complete buffer. However, -the Emacs tradition encourages flexibility---you may want to count -words in just a section, rather than all of a buffer. So it makes -more sense to design the command to count the number of words in a -region. Once you have a @code{count-words-region} command, you can, -if you wish, count words in a whole buffer by marking it with -@w{@kbd{C-x h}} (@code{mark-whole-buffer}). - -Clearly, counting words is a repetitive act: starting from the -beginning of the region, you count the first word, then the second -word, then the third word, and so on, until you reach the end of the -region. This means that word counting is ideally suited to recursion -or to a @code{while} loop. - -@menu -* Design count-words-region:: The definition using a @code{while} loop. -* Whitespace Bug:: The Whitespace Bug in @code{count-words-region}. -@end menu - -@node Design count-words-region, Whitespace Bug, count-words-region, count-words-region -@ifnottex -@unnumberedsubsec Designing @code{count-words-region} -@end ifnottex - -First, we will implement the word count command with a @code{while} -loop, then with recursion. The command will, of course, be -interactive. - -@need 800 -The template for an interactive function definition is, as always: - -@smallexample -@group -(defun @var{name-of-function} (@var{argument-list}) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) - @var{body}@dots{}) -@end group -@end smallexample - -What we need to do is fill in the slots. - -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier -to remember. @code{count-words-region} is a good choice. - -The function counts words within a region. This means that the -argument list must contain symbols that are bound to the two -positions, the beginning and end of the region. These two positions -can be called @samp{beginning} and @samp{end} respectively. The first -line of the documentation should be a single sentence, since that is -all that is printed as documentation by a command such as -@code{apropos}. The interactive expression will be of the form -@samp{(interactive "r")}, since that will cause Emacs to pass the -beginning and end of the region to the function's argument list. All -this is routine. - -The body of the function needs to be written to do three tasks: -first, to set up conditions under which the @code{while} loop can -count words, second, to run the @code{while} loop, and third, to send -a message to the user. - -When a user calls @code{count-words-region}, point may be at the -beginning or the end of the region. However, the counting process -must start at the beginning of the region. This means we will want -to put point there if it is not already there. Executing -@code{(goto-char beginning)} ensures this. Of course, we will want to -return point to its expected position when the function finishes its -work. For this reason, the body must be enclosed in a -@code{save-excursion} expression. - -The central part of the body of the function consists of a -@code{while} loop in which one expression jumps point forward word by -word, and another expression counts those jumps. The true-or-false-test -of the @code{while} loop should test true so long as point should jump -forward, and false when point is at the end of the region. - -We could use @code{(forward-word 1)} as the expression for moving point -forward word by word, but it is easier to see what Emacs identifies as a -`word' if we use a regular expression search. - -A regular expression search that finds the pattern for which it is -searching leaves point after the last character matched. This means -that a succession of successful word searches will move point forward -word by word. - -As a practical matter, we want the regular expression search to jump -over whitespace and punctuation between words as well as over the -words themselves. A regexp that refuses to jump over interword -whitespace would never jump more than one word! This means that -the regexp should include the whitespace and punctuation that follows -a word, if any, as well as the word itself. (A word may end a buffer -and not have any following whitespace or punctuation, so that part of -the regexp must be optional.) - -Thus, what we want for the regexp is a pattern defining one or more -word constituent characters followed, optionally, by one or more -characters that are not word constituents. The regular expression for -this is: - -@smallexample -\w+\W* -@end smallexample - -@noindent -The buffer's syntax table determines which characters are and are not -word constituents. (@xref{Syntax, , What Constitutes a Word or -Symbol?}, for more about syntax. Also, see @ref{Syntax, Syntax, The -Syntax Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , -Syntax Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -@need 800 -The search expression looks like this: - -@smallexample -(re-search-forward "\\w+\\W*") -@end smallexample - -@noindent -(Note that paired backslashes precede the @samp{w} and @samp{W}. A -single backslash has special meaning to the Emacs Lisp interpreter. -It indicates that the following character is interpreted differently -than usual. For example, the two characters, @samp{\n}, stand for -@samp{newline}, rather than for a backslash followed by @samp{n}. Two -backslashes in a row stand for an ordinary, `unspecial' backslash, so -Emacs Lisp interpreter ends of seeing a single backslash followed by a -letter. So it discovers the letter is special.) - -We need a counter to count how many words there are; this variable -must first be set to 0 and then incremented each time Emacs goes -around the @code{while} loop. The incrementing expression is simply: - -@smallexample -(setq count (1+ count)) -@end smallexample - -Finally, we want to tell the user how many words there are in the -region. The @code{message} function is intended for presenting this -kind of information to the user. The message has to be phrased so -that it reads properly regardless of how many words there are in the -region: we don't want to say that ``there are 1 words in the region''. -The conflict between singular and plural is ungrammatical. We can -solve this problem by using a conditional expression that evaluates -different messages depending on the number of words in the region. -There are three possibilities: no words in the region, one word in the -region, and more than one word. This means that the @code{cond} -special form is appropriate. - -@need 1500 -All this leads to the following function definition: - -@smallexample -@group -;;; @r{First version; has bugs!} -(defun count-words-region (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent -character followed by at least one character that -is not a word-constituent. The buffer's syntax -table determines which characters these are." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@noindent -As written, the function works, but not in all circumstances. - -@node Whitespace Bug, , Design count-words-region, count-words-region -@comment node-name, next, previous, up -@subsection The Whitespace Bug in @code{count-words-region} - -The @code{count-words-region} command described in the preceding -section has two bugs, or rather, one bug with two manifestations. -First, if you mark a region containing only whitespace in the middle -of some text, the @code{count-words-region} command tells you that the -region contains one word! Second, if you mark a region containing -only whitespace at the end of the buffer or the accessible portion of -a narrowed buffer, the command displays an error message that looks -like this: - -@smallexample -Search failed: "\\w+\\W*" -@end smallexample - -If you are reading this in Info in GNU Emacs, you can test for these -bugs yourself. - -First, evaluate the function in the usual manner to install it. -@ifinfo -Here is a copy of the definition. Place your cursor after the closing -parenthesis and type @kbd{C-x C-e} to install it. - -@smallexample -@group -;; @r{First version; has bugs!} -(defun count-words-region (beginning end) - "Print number of words in the region. -Words are defined as at least one word-constituent character followed -by at least one character that is not a word-constituent. The buffer's -syntax table determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (goto-char beginning) - (let ((count 0)) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (< (point) end) - (re-search-forward "\\w+\\W*") - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message "The region does NOT have any words.")) - ((= 1 count) (message "The region has 1 word.")) - (t (message "The region has %d words." count)))))) -@end group -@end smallexample -@end ifinfo - -@need 1000 -If you wish, you can also install this keybinding by evaluating it: - -@smallexample -(global-set-key "\C-c=" 'count-words-region) -@end smallexample - -To conduct the first test, set mark and point to the beginning and end -of the following line and then type @kbd{C-c =} (or @kbd{M-x -count-words-region} if you have not bound @kbd{C-c =}): - -@smallexample - one two three -@end smallexample - -@noindent -Emacs will tell you, correctly, that the region has three words. - -Repeat the test, but place mark at the beginning of the line and place -point just @emph{before} the word @samp{one}. Again type the command -@kbd{C-c =} (or @kbd{M-x count-words-region}). Emacs should tell you -that the region has no words, since it is composed only of the -whitespace at the beginning of the line. But instead Emacs tells you -that the region has one word! - -For the third test, copy the sample line to the end of the -@file{*scratch*} buffer and then type several spaces at the end of the -line. Place mark right after the word @samp{three} and point at the -end of line. (The end of the line will be the end of the buffer.) -Type @kbd{C-c =} (or @kbd{M-x count-words-region}) as you did before. -Again, Emacs should tell you that the region has no words, since it is -composed only of the whitespace at the end of the line. Instead, -Emacs displays an error message saying @samp{Search failed}. - -The two bugs stem from the same problem. - -Consider the first manifestation of the bug, in which the command -tells you that the whitespace at the beginning of the line contains -one word. What happens is this: The @code{M-x count-words-region} -command moves point to the beginning of the region. The @code{while} -tests whether the value of point is smaller than the value of -@code{end}, which it is. Consequently, the regular expression search -looks for and finds the first word. It leaves point after the word. -@code{count} is set to one. The @code{while} loop repeats; but this -time the value of point is larger than the value of @code{end}, the -loop is exited; and the function displays a message saying the number -of words in the region is one. In brief, the regular expression -search looks for and finds the word even though it is outside -the marked region. - -In the second manifestation of the bug, the region is whitespace at -the end of the buffer. Emacs says @samp{Search failed}. What happens -is that the true-or-false-test in the @code{while} loop tests true, so -the search expression is executed. But since there are no more words -in the buffer, the search fails. - -In both manifestations of the bug, the search extends or attempts to -extend outside of the region. - -The solution is to limit the search to the region---this is a fairly -simple action, but as you may have come to expect, it is not quite as -simple as you might think. - -As we have seen, the @code{re-search-forward} function takes a search -pattern as its first argument. But in addition to this first, -mandatory argument, it accepts three optional arguments. The optional -second argument bounds the search. The optional third argument, if -@code{t}, causes the function to return @code{nil} rather than signal -an error if the search fails. The optional fourth argument is a -repeat count. (In Emacs, you can see a function's documentation by -typing @kbd{C-h f}, the name of the function, and then @key{RET}.) - -In the @code{count-words-region} definition, the value of the end of -the region is held by the variable @code{end} which is passed as an -argument to the function. Thus, we can add @code{end} as an argument -to the regular expression search expression: - -@smallexample -(re-search-forward "\\w+\\W*" end) -@end smallexample - -However, if you make only this change to the @code{count-words-region} -definition and then test the new version of the definition on a -stretch of whitespace, you will receive an error message saying -@samp{Search failed}. - -What happens is this: the search is limited to the region, and fails -as you expect because there are no word-constituent characters in the -region. Since it fails, we receive an error message. But we do not -want to receive an error message in this case; we want to receive the -message that "The region does NOT have any words." - -The solution to this problem is to provide @code{re-search-forward} -with a third argument of @code{t}, which causes the function to return -@code{nil} rather than signal an error if the search fails. - -However, if you make this change and try it, you will see the message -``Counting words in region ... '' and @dots{} you will keep on seeing -that message @dots{}, until you type @kbd{C-g} (@code{keyboard-quit}). - -Here is what happens: the search is limited to the region, as before, -and it fails because there are no word-constituent characters in the -region, as expected. Consequently, the @code{re-search-forward} -expression returns @code{nil}. It does nothing else. In particular, -it does not move point, which it does as a side effect if it finds the -search target. After the @code{re-search-forward} expression returns -@code{nil}, the next expression in the @code{while} loop is evaluated. -This expression increments the count. Then the loop repeats. The -true-or-false-test tests true because the value of point is still less -than the value of end, since the @code{re-search-forward} expression -did not move point. @dots{} and the cycle repeats @dots{} - -The @code{count-words-region} definition requires yet another -modification, to cause the true-or-false-test of the @code{while} loop -to test false if the search fails. Put another way, there are two -conditions that must be satisfied in the true-or-false-test before the -word count variable is incremented: point must still be within the -region and the search expression must have found a word to count. - -Since both the first condition and the second condition must be true -together, the two expressions, the region test and the search -expression, can be joined with an @code{and} special form and embedded in -the @code{while} loop as the true-or-false-test, like this: - -@smallexample -(and (< (point) end) (re-search-forward "\\w+\\W*" end t)) -@end smallexample - -@c colon in printed section title causes problem in Info cross reference -@c also trouble with an overfull hbox -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -The @code{re-search-forward} expression returns @code{t} if the search -succeeds and as a side effect moves point. Consequently, as words are -found, point is moved through the region. When the search expression -fails to find another word, or when point reaches the end of the -region, the true-or-false-test tests false, the @code{while} loop -exits, and the @code{count-words-region} function displays one or -other of its messages. - -After incorporating these final changes, the @code{count-words-region} -works without bugs (or at least, without bugs that I have found!). -Here is what it looks like: - -@smallexample -@group -;;; @r{Final version:} @code{while} -(defun count-words-region (beginning end) - "Print number of words in the region." - (interactive "r") - (message "Counting words in region ... ") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (save-excursion - (let ((count 0)) - (goto-char beginning) -@end group - -@group -;;; @r{2. Run the} while @r{loop.} - (while (and (< (point) end) - (re-search-forward "\\w+\\W*" end t)) - (setq count (1+ count))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node recursive-count-words, Counting Exercise, count-words-region, Counting Words -@comment node-name, next, previous, up -@section Count Words Recursively -@cindex Count words recursively -@cindex Recursively counting words -@cindex Words, counted recursively - -You can write the function for counting words recursively as well as -with a @code{while} loop. Let's see how this is done. - -First, we need to recognize that the @code{count-words-region} -function has three jobs: it sets up the appropriate conditions for -counting to occur; it counts the words in the region; and it sends a -message to the user telling how many words there are. - -If we write a single recursive function to do everything, we will -receive a message for every recursive call. If the region contains 13 -words, we will receive thirteen messages, one right after the other. -We don't want this! Instead, we must write two functions to do the -job, one of which (the recursive function) will be used inside of the -other. One function will set up the conditions and display the -message; the other will return the word count. - -Let us start with the function that causes the message to be displayed. -We can continue to call this @code{count-words-region}. - -This is the function that the user will call. It will be interactive. -Indeed, it will be similar to our previous versions of this -function, except that it will call @code{recursive-count-words} to -determine how many words are in the region. - -@need 1250 -We can readily construct a template for this function, based on our -previous versions: - -@smallexample -@group -;; @r{Recursive version; uses regular expression search} -(defun count-words-region (beginning end) - "@var{documentation}@dots{}" - (@var{interactive-expression}@dots{}) -@end group -@group - -;;; @r{1. Set up appropriate conditions.} - (@var{explanatory message}) - (@var{set-up functions}@dots{} -@end group -@group - -;;; @r{2. Count the words.} - @var{recursive call} -@end group -@group - -;;; @r{3. Send a message to the user.} - @var{message providing word count})) -@end group -@end smallexample - -The definition looks straightforward, except that somehow the count -returned by the recursive call must be passed to the message -displaying the word count. A little thought suggests that this can be -done by making use of a @code{let} expression: we can bind a variable -in the varlist of a @code{let} expression to the number of words in -the region, as returned by the recursive call; and then the -@code{cond} expression, using binding, can display the value to the -user. - -Often, one thinks of the binding within a @code{let} expression as -somehow secondary to the `primary' work of a function. But in this -case, what you might consider the `primary' job of the function, -counting words, is done within the @code{let} expression. - -@need 1250 -Using @code{let}, the function definition looks like this: - -@smallexample -@group -(defun count-words-region (beginning end) - "Print number of words in the region." - (interactive "r") -@end group - -@group -;;; @r{1. Set up appropriate conditions.} - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) -@end group - -@group -;;; @r{2. Count the words.} - (let ((count (recursive-count-words end))) -@end group - -@group -;;; @r{3. Send a message to the user.} - (cond ((zerop count) - (message - "The region does NOT have any words.")) - ((= 1 count) - (message - "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -Next, we need to write the recursive counting function. - -A recursive function has at least three parts: the `do-again-test', the -`next-step-expression', and the recursive call. - -The do-again-test determines whether the function will or will not be -called again. Since we are counting words in a region and can use a -function that moves point forward for every word, the do-again-test -can check whether point is still within the region. The do-again-test -should find the value of point and determine whether point is before, -at, or after the value of the end of the region. We can use the -@code{point} function to locate point. Clearly, we must pass the -value of the end of the region to the recursive counting function as an -argument. - -In addition, the do-again-test should also test whether the search finds a -word. If it does not, the function should not call itself again. - -The next-step-expression changes a value so that when the recursive -function is supposed to stop calling itself, it stops. More -precisely, the next-step-expression changes a value so that at the -right time, the do-again-test stops the recursive function from -calling itself again. In this case, the next-step-expression can be -the expression that moves point forward, word by word. - -The third part of a recursive function is the recursive call. - -Somewhere, also, we also need a part that does the `work' of the -function, a part that does the counting. A vital part! - -@need 1250 -But already, we have an outline of the recursive counting function: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - @var{do-again-test} - @var{next-step-expression} - @var{recursive call}) -@end group -@end smallexample - -Now we need to fill in the slots. Let's start with the simplest cases -first: if point is at or beyond the end of the region, there cannot -be any words in the region, so the function should return zero. -Likewise, if the search fails, there are no words to count, so the -function should return zero. - -On the other hand, if point is within the region and the search -succeeds, the function should call itself again. - -@need 800 -Thus, the do-again-test should look like this: - -@smallexample -@group -(and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group -@end smallexample - -Note that the search expression is part of the do-again-test---the -function returns @code{t} if its search succeeds and @code{nil} if it -fails. (@xref{Whitespace Bug, , The Whitespace Bug in -@code{count-words-region}}, for an explanation of how -@code{re-search-forward} works.) - -The do-again-test is the true-or-false test of an @code{if} clause. -Clearly, if the do-again-test succeeds, the then-part of the @code{if} -clause should call the function again; but if it fails, the else-part -should return zero since either point is outside the region or the -search failed because there were no words to find. - -But before considering the recursive call, we need to consider the -next-step-expression. What is it? Interestingly, it is the search -part of the do-again-test. - -In addition to returning @code{t} or @code{nil} for the -do-again-test, @code{re-search-forward} moves point forward as a side -effect of a successful search. This is the action that changes the -value of point so that the recursive function stops calling itself -when point completes its movement through the region. Consequently, -the @code{re-search-forward} expression is the next-step-expression. - -@need 1200 -In outline, then, the body of the @code{recursive-count-words} -function looks like this: - -@smallexample -@group -(if @var{do-again-test-and-next-step-combined} - ;; @r{then} - @var{recursive-call-returning-count} - ;; @r{else} - @var{return-zero}) -@end group -@end smallexample - -How to incorporate the mechanism that counts? - -If you are not used to writing recursive functions, a question like -this can be troublesome. But it can and should be approached -systematically. - -We know that the counting mechanism should be associated in some way -with the recursive call. Indeed, since the next-step-expression moves -point forward by one word, and since a recursive call is made for -each word, the counting mechanism must be an expression that adds one -to the value returned by a call to @code{recursive-count-words}. - -@need 800 -Consider several cases: - -@itemize @bullet -@item -If there are two words in the region, the function should return -a value resulting from adding one to the value returned when it counts -the first word, plus the number returned when it counts the remaining -words in the region, which in this case is one. - -@item -If there is one word in the region, the function should return -a value resulting from adding one to the value returned when it counts -that word, plus the number returned when it counts the remaining -words in the region, which in this case is zero. - -@item -If there are no words in the region, the function should return zero. -@end itemize - -From the sketch we can see that the else-part of the @code{if} returns -zero for the case of no words. This means that the then-part of the -@code{if} must return a value resulting from adding one to the value -returned from a count of the remaining words. - -@need 1200 -The expression will look like this, where @code{1+} is a function that -adds one to its argument. - -@smallexample -(1+ (recursive-count-words region-end)) -@end smallexample - -@need 1200 -The whole @code{recursive-count-words} function will then look like -this: - -@smallexample -@group -(defun recursive-count-words (region-end) - "@var{documentation}@dots{}" - -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 1250 -Let's examine how this works: - -If there are no words in the region, the else part of the @code{if} -expression is evaluated and consequently the function returns zero. - -If there is one word in the region, the value of point is less than -the value of @code{region-end} and the search succeeds. In this case, -the true-or-false-test of the @code{if} expression tests true, and the -then-part of the @code{if} expression is evaluated. The counting -expression is evaluated. This expression returns a value (which will -be the value returned by the whole function) that is the sum of one -added to the value returned by a recursive call. - -Meanwhile, the next-step-expression has caused point to jump over the -first (and in this case only) word in the region. This means that -when @code{(recursive-count-words region-end)} is evaluated a second -time, as a result of the recursive call, the value of point will be -equal to or greater than the value of region end. So this time, -@code{recursive-count-words} will return zero. The zero will be added -to one, and the original evaluation of @code{recursive-count-words} -will return one plus zero, which is one, which is the correct amount. - -Clearly, if there are two words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining word---that is, it adds one to one, producing two, which is -the correct amount. - -Similarly, if there are three words in the region, the first call to -@code{recursive-count-words} returns one added to the value returned -by calling @code{recursive-count-words} on a region containing the -remaining two words---and so on and so on. - -@need 1250 -@noindent -With full documentation the two functions look like this: - -@need 1250 -@noindent -The recursive function: - -@findex recursive-count-words -@smallexample -@group -(defun recursive-count-words (region-end) - "Number of words between point and REGION-END." -@end group - -@group -;;; @r{1. do-again-test} - (if (and (< (point) region-end) - (re-search-forward "\\w+\\W*" region-end t)) -@end group - -@group -;;; @r{2. then-part: the recursive call} - (1+ (recursive-count-words region-end)) - -;;; @r{3. else-part} - 0)) -@end group -@end smallexample - -@need 800 -@noindent -The wrapper: - -@smallexample -@group -;;; @r{Recursive version} -(defun count-words-region (beginning end) - "Print number of words in the region. -@end group - -@group -Words are defined as at least one word-constituent -character followed by at least one character that is -not a word-constituent. The buffer's syntax table -determines which characters these are." -@end group -@group - (interactive "r") - (message "Counting words in region ... ") - (save-excursion - (goto-char beginning) - (let ((count (recursive-count-words end))) -@end group -@group - (cond ((zerop count) - (message - "The region does NOT have any words.")) -@end group -@group - ((= 1 count) - (message "The region has 1 word.")) - (t - (message - "The region has %d words." count)))))) -@end group -@end smallexample - -@node Counting Exercise, , recursive-count-words, Counting Words -@section Exercise: Counting Punctuation - -Using a @code{while} loop, write a function to count the number of -punctuation marks in a region---period, comma, semicolon, colon, -exclamation mark, and question mark. Do the same using recursion. - -@node Words in a defun, Readying a Graph, Counting Words, Top -@chapter Counting Words in a @code{defun} -@cindex Counting words in a @code{defun} -@cindex Word counting in a @code{defun} - -Our next project is to count the number of words in a function -definition. Clearly, this can be done using some variant of -@code{count-word-region}. @xref{Counting Words, , Counting Words: -Repetition and Regexps}. If we are just going to count the words in -one definition, it is easy enough to mark the definition with the -@kbd{C-M-h} (@code{mark-defun}) command, and then call -@code{count-word-region}. - -However, I am more ambitious: I want to count the words and symbols in -every definition in the Emacs sources and then print a graph that -shows how many functions there are of each length: how many contain 40 -to 49 words or symbols, how many contain 50 to 59 words or symbols, -and so on. I have often been curious how long a typical function is, -and this will tell. - -@menu -* Divide and Conquer:: -* Words and Symbols:: What to count? -* Syntax:: What constitutes a word or symbol? -* count-words-in-defun:: Very like @code{count-words}. -* Several defuns:: Counting several defuns in a file. -* Find a File:: Do you want to look at a file? -* lengths-list-file:: A list of the lengths of many definitions. -* Several files:: Counting in definitions in different files. -* Several files recursively:: Recursively counting in different files. -* Prepare the data:: Prepare the data for display in a graph. -@end menu - -@node Divide and Conquer, Words and Symbols, Words in a defun, Words in a defun -@ifnottex -@unnumberedsec Divide and Conquer -@end ifnottex - -Described in one phrase, the histogram project is daunting; but -divided into numerous small steps, each of which we can take one at a -time, the project becomes less fearsome. Let us consider what the -steps must be: - -@itemize @bullet -@item -First, write a function to count the words in one definition. This -includes the problem of handling symbols as well as words. - -@item -Second, write a function to list the numbers of words in each function -in a file. This function can use the @code{count-words-in-defun} -function. - -@item -Third, write a function to list the numbers of words in each function -in each of several files. This entails automatically finding the -various files, switching to them, and counting the words in the -definitions within them. - -@item -Fourth, write a function to convert the list of numbers that we -created in step three to a form that will be suitable for printing as -a graph. - -@item -Fifth, write a function to print the results as a graph. -@end itemize - -This is quite a project! But if we take each step slowly, it will not -be difficult. - -@node Words and Symbols, Syntax, Divide and Conquer, Words in a defun -@section What to Count? -@cindex Words and symbols in defun - -When we first start thinking about how to count the words in a -function definition, the first question is (or ought to be) what are -we going to count? When we speak of `words' with respect to a Lisp -function definition, we are actually speaking, in large part, of -`symbols'. For example, the following @code{multiply-by-seven} -function contains the five symbols @code{defun}, -@code{multiply-by-seven}, @code{number}, @code{*}, and @code{7}. In -addition, in the documentation string, it contains the four words -@samp{Multiply}, @samp{NUMBER}, @samp{by}, and @samp{seven}. The -symbol @samp{number} is repeated, so the definition contains a total -of ten words and symbols. - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) -@end group -@end smallexample - -@noindent -However, if we mark the @code{multiply-by-seven} definition with -@kbd{C-M-h} (@code{mark-defun}), and then call -@code{count-words-region} on it, we will find that -@code{count-words-region} claims the definition has eleven words, not -ten! Something is wrong! - -The problem is twofold: @code{count-words-region} does not count the -@samp{*} as a word, and it counts the single symbol, -@code{multiply-by-seven}, as containing three words. The hyphens are -treated as if they were interword spaces rather than intraword -connectors: @samp{multiply-by-seven} is counted as if it were written -@samp{multiply by seven}. - -The cause of this confusion is the regular expression search within -the @code{count-words-region} definition that moves point forward word -by word. In the canonical version of @code{count-words-region}, the -regexp is: - -@smallexample -"\\w+\\W*" -@end smallexample - -@noindent -This regular expression is a pattern defining one or more word -constituent characters possibly followed by one or more characters -that are not word constituents. What is meant by `word constituent -characters' brings us to the issue of syntax, which is worth a section -of its own. - -@node Syntax, count-words-in-defun, Words and Symbols, Words in a defun -@section What Constitutes a Word or Symbol? -@cindex Syntax categories and tables - -Emacs treats different characters as belonging to different -@dfn{syntax categories}. For example, the regular expression, -@samp{\\w+}, is a pattern specifying one or more @emph{word -constituent} characters. Word constituent characters are members of -one syntax category. Other syntax categories include the class of -punctuation characters, such as the period and the comma, and the -class of whitespace characters, such as the blank space and the tab -character. (For more information, see @ref{Syntax, Syntax, The Syntax -Table, emacs, The GNU Emacs Manual}, and @ref{Syntax Tables, , Syntax -Tables, elisp, The GNU Emacs Lisp Reference Manual}.) - -Syntax tables specify which characters belong to which categories. -Usually, a hyphen is not specified as a `word constituent character'. -Instead, it is specified as being in the `class of characters that are -part of symbol names but not words.' This means that the -@code{count-words-region} function treats it in the same way it treats -an interword white space, which is why @code{count-words-region} -counts @samp{multiply-by-seven} as three words. - -There are two ways to cause Emacs to count @samp{multiply-by-seven} as -one symbol: modify the syntax table or modify the regular expression. - -We could redefine a hyphen as a word constituent character by -modifying the syntax table that Emacs keeps for each mode. This -action would serve our purpose, except that a hyphen is merely the -most common character within symbols that is not typically a word -constituent character; there are others, too. - -Alternatively, we can redefine the regular expression used in the -@code{count-words} definition so as to include symbols. This -procedure has the merit of clarity, but the task is a little tricky. - -@need 1200 -The first part is simple enough: the pattern must match ``at least one -character that is a word or symbol constituent''. Thus: - -@smallexample -"\\(\\w\\|\\s_\\)+" -@end smallexample - -@noindent -The @samp{\\(} is the first part of the grouping construct that -includes the @samp{\\w} and the @samp{\\s_} as alternatives, separated -by the @samp{\\|}. The @samp{\\w} matches any word-constituent -character and the @samp{\\s_} matches any character that is part of a -symbol name but not a word-constituent character. The @samp{+} -following the group indicates that the word or symbol constituent -characters must be matched at least once. - -However, the second part of the regexp is more difficult to design. -What we want is to follow the first part with ``optionally one or more -characters that are not constituents of a word or symbol''. At first, -I thought I could define this with the following: - -@smallexample -"\\(\\W\\|\\S_\\)*" -@end smallexample - -@noindent -The upper case @samp{W} and @samp{S} match characters that are -@emph{not} word or symbol constituents. Unfortunately, this -expression matches any character that is either not a word constituent -or not a symbol constituent. This matches any character! - -I then noticed that every word or symbol in my test region was -followed by white space (blank space, tab, or newline). So I tried -placing a pattern to match one or more blank spaces after the pattern -for one or more word or symbol constituents. This failed, too. Words -and symbols are often separated by whitespace, but in actual code -parentheses may follow symbols and punctuation may follow words. So -finally, I designed a pattern in which the word or symbol constituents -are followed optionally by characters that are not white space and -then followed optionally by white space. - -@need 800 -Here is the full regular expression: - -@smallexample -"\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" -@end smallexample - -@node count-words-in-defun, Several defuns, Syntax, Words in a defun -@section The @code{count-words-in-defun} Function -@cindex Counting words in a @code{defun} - -We have seen that there are several ways to write a -@code{count-word-region} function. To write a -@code{count-words-in-defun}, we need merely adapt one of these -versions. - -The version that uses a @code{while} loop is easy to understand, so I -am going to adapt that. Because @code{count-words-in-defun} will be -part of a more complex program, it need not be interactive and it need -not display a message but just return the count. These considerations -simplify the definition a little. - -On the other hand, @code{count-words-in-defun} will be used within a -buffer that contains function definitions. Consequently, it is -reasonable to ask that the function determine whether it is called -when point is within a function definition, and if it is, to return -the count for that definition. This adds complexity to the -definition, but saves us from needing to pass arguments to the -function. - -@need 1250 -These considerations lead us to prepare the following template: - -@smallexample -@group -(defun count-words-in-defun () - "@var{documentation}@dots{}" - (@var{set up}@dots{} - (@var{while loop}@dots{}) - @var{return count}) -@end group -@end smallexample - -@noindent -As usual, our job is to fill in the slots. - -First, the set up. - -We are presuming that this function will be called within a buffer -containing function definitions. Point will either be within a -function definition or not. For @code{count-words-in-defun} to work, -point must move to the beginning of the definition, a counter must -start at zero, and the counting loop must stop when point reaches the -end of the definition. - -The @code{beginning-of-defun} function searches backwards for an -opening delimiter such as a @samp{(} at the beginning of a line, and -moves point to that position, or else to the limit of the search. In -practice, this means that @code{beginning-of-defun} moves point to the -beginning of an enclosing or preceding function definition, or else to -the beginning of the buffer. We can use @code{beginning-of-defun} to -place point where we wish to start. - -The @code{while} loop requires a counter to keep track of the words or -symbols being counted. A @code{let} expression can be used to create -a local variable for this purpose, and bind it to an initial value of zero. - -The @code{end-of-defun} function works like @code{beginning-of-defun} -except that it moves point to the end of the definition. -@code{end-of-defun} can be used as part of an expression that -determines the position of the end of the definition. - -The set up for @code{count-words-in-defun} takes shape rapidly: first -we move point to the beginning of the definition, then we create a -local variable to hold the count, and finally, we record the position -of the end of the definition so the @code{while} loop will know when to stop -looping. - -@need 1250 -The code looks like this: - -@smallexample -@group -(beginning-of-defun) -(let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@end smallexample - -@noindent -The code is simple. The only slight complication is likely to concern -@code{end}: it is bound to the position of the end of the definition -by a @code{save-excursion} expression that returns the value of point -after @code{end-of-defun} temporarily moves it to the end of the -definition. - -The second part of the @code{count-words-in-defun}, after the set up, -is the @code{while} loop. - -The loop must contain an expression that jumps point forward word by -word and symbol by symbol, and another expression that counts the -jumps. The true-or-false-test for the @code{while} loop should test -true so long as point should jump forward, and false when point is at -the end of the definition. We have already redefined the regular -expression for this (@pxref{Syntax}), so the loop is straightforward: - -@smallexample -@group -(while (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" end t) - (setq count (1+ count))) -@end group -@end smallexample - -The third part of the function definition returns the count of words -and symbols. This part is the last expression within the body of the -@code{let} expression, and can be, very simply, the local variable -@code{count}, which when evaluated returns the count. - -@need 1250 -Put together, the @code{count-words-in-defun} definition looks like this: - -@findex count-words-in-defun -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -How to test this? The function is not interactive, but it is easy to -put a wrapper around the function to make it interactive; we can use -almost the same code as for the recursive version of -@code{count-words-region}: - -@smallexample -@group -;;; @r{Interactive version.} -(defun count-words-defun () - "Number of words and symbols in a function definition." - (interactive) - (message - "Counting words and symbols in function definition ... ") -@end group -@group - (let ((count (count-words-in-defun))) - (cond - ((zerop count) - (message - "The definition does NOT have any words or symbols.")) -@end group -@group - ((= 1 count) - (message - "The definition has 1 word or symbol.")) - (t - (message - "The definition has %d words or symbols." count))))) -@end group -@end smallexample - -@need 800 -@noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: - -@smallexample -(global-set-key "\C-c=" 'count-words-defun) -@end smallexample - -Now we can try out @code{count-words-defun}: install both -@code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: - -@smallexample -@group -(defun multiply-by-seven (number) - "Multiply NUMBER by seven." - (* 7 number)) - @result{} 10 -@end group -@end smallexample - -@noindent -Success! The definition has 10 words and symbols. - -The next problem is to count the numbers of words and symbols in -several definitions within a single file. - -@node Several defuns, Find a File, count-words-in-defun, Words in a defun -@section Count Several @code{defuns} Within a File - -A file such as @file{simple.el} may have a hundred or more function -definitions within it. Our long term goal is to collect statistics on -many files, but as a first step, our immediate goal is to collect -statistics on one file. - -The information will be a series of numbers, each number being the -length of a function definition. We can store the numbers in a list. - -We know that we will want to incorporate the information regarding one -file with information about many other files; this means that the -function for counting definition lengths within one file need only -return the list of lengths. It need not and should not display any -messages. - -The word count commands contain one expression to jump point forward -word by word and another expression to count the jumps. The function -to return the lengths of definitions can be designed to work the same -way, with one expression to jump point forward definition by -definition and another expression to construct the lengths' list. - -This statement of the problem makes it elementary to write the -function definition. Clearly, we will start the count at the -beginning of the file, so the first command will be @code{(goto-char -(point-min))}. Next, we start the @code{while} loop; and the -true-or-false test of the loop can be a regular expression search for -the next function definition---so long as the search succeeds, point -is moved forward and then the body of the loop is evaluated. The body -needs an expression that constructs the lengths' list. @code{cons}, -the list construction command, can be used to create the list. That -is almost all there is to it. - -@need 800 -Here is what this fragment of code looks like: - -@smallexample -@group -(goto-char (point-min)) -(while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) -@end group -@end smallexample - -What we have left out is the mechanism for finding the file that -contains the function definitions. - -In previous examples, we either used this, the Info file, or we -switched back and forth to some other buffer, such as the -@file{*scratch*} buffer. - -Finding a file is a new process that we have not yet discussed. - -@node Find a File, lengths-list-file, Several defuns, Words in a defun -@comment node-name, next, previous, up -@section Find a File -@cindex Find a File - -To find a file in Emacs, you use the @kbd{C-x C-f} (@code{find-file}) -command. This command is almost, but not quite right for the lengths -problem. - -@need 1200 -Let's look at the source for @code{find-file}: - -@smallexample -@group -(defun find-file (filename) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists." - (interactive "FFind file: ") - (switch-to-buffer (find-file-noselect filename))) -@end group -@end smallexample - -@noindent -(The most recent version of the @code{find-file} function definition -permits you to specify optional wildcards to visit multiple files; that -makes the definition more complex and we will not discuss it here, -since it is not relevant. You can see its source using either -@kbd{M-.} (@code{find-tag}) or @kbd{C-h f} (@code{describe-function}).) - -@ignore -In Emacs 22 -(defun find-file (filename &optional wildcards) - "Edit file FILENAME. -Switch to a buffer visiting file FILENAME, -creating one if none already exists. -Interactively, the default if you just type RET is the current directory, -but the visited file name is available through the minibuffer history: -type M-n to pull it into the minibuffer. - -Interactively, or if WILDCARDS is non-nil in a call from Lisp, -expand wildcards (if any) and visit multiple files. You can -suppress wildcard expansion by setting `find-file-wildcards' to nil. - -To visit a file without any kind of conversion and without -automatically choosing a major mode, use \\[find-file-literally]." - (interactive (find-file-read-args "Find file: " nil)) - (let ((value (find-file-noselect filename nil nil wildcards))) - (if (listp value) - (mapcar 'switch-to-buffer (nreverse value)) - (switch-to-buffer value)))) -@end ignore - -The definition I am showing possesses short but complete documentation -and an interactive specification that prompts you for a file name when -you use the command interactively. The body of the definition -contains two functions, @code{find-file-noselect} and -@code{switch-to-buffer}. - -According to its documentation as shown by @kbd{C-h f} (the -@code{describe-function} command), the @code{find-file-noselect} -function reads the named file into a buffer and returns the buffer. -(Its most recent version includes an optional wildcards argument, -too, as well as another to read a file literally and an other you -suppress warning messages. These optional arguments are irrelevant.) - -However, the @code{find-file-noselect} function does not select the -buffer in which it puts the file. Emacs does not switch its attention -(or yours if you are using @code{find-file-noselect}) to the selected -buffer. That is what @code{switch-to-buffer} does: it switches the -buffer to which Emacs attention is directed; and it switches the -buffer displayed in the window to the new buffer. We have discussed -buffer switching elsewhere. (@xref{Switching Buffers}.) - -In this histogram project, we do not need to display each file on the -screen as the program determines the length of each definition within -it. Instead of employing @code{switch-to-buffer}, we can work with -@code{set-buffer}, which redirects the attention of the computer -program to a different buffer but does not redisplay it on the screen. -So instead of calling on @code{find-file} to do the job, we must write -our own expression. - -The task is easy: use @code{find-file-noselect} and @code{set-buffer}. - -@node lengths-list-file, Several files, Find a File, Words in a defun -@section @code{lengths-list-file} in Detail - -The core of the @code{lengths-list-file} function is a @code{while} -loop containing a function to move point forward `defun by defun' and -a function to count the number of words and symbols in each defun. -This core must be surrounded by functions that do various other tasks, -including finding the file, and ensuring that point starts out at the -beginning of the file. The function definition looks like this: -@findex lengths-list-file - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@noindent -The function is passed one argument, the name of the file on which it -will work. It has four lines of documentation, but no interactive -specification. Since people worry that a computer is broken if they -don't see anything going on, the first line of the body is a -message. - -The next line contains a @code{save-excursion} that returns Emacs' -attention to the current buffer when the function completes. This is -useful in case you embed this function in another function that -presumes point is restored to the original buffer. - -In the varlist of the @code{let} expression, Emacs finds the file and -binds the local variable @code{buffer} to the buffer containing the -file. At the same time, Emacs creates @code{lengths-list} as a local -variable. - -Next, Emacs switches its attention to the buffer. - -In the following line, Emacs makes the buffer read-only. Ideally, -this line is not necessary. None of the functions for counting words -and symbols in a function definition should change the buffer. -Besides, the buffer is not going to be saved, even if it were changed. -This line is entirely the consequence of great, perhaps excessive, -caution. The reason for the caution is that this function and those -it calls work on the sources for Emacs and it is inconvenient if they -are inadvertently modified. It goes without saying that I did not -realize a need for this line until an experiment went awry and started -to modify my Emacs source files @dots{} - -Next comes a call to widen the buffer if it is narrowed. This -function is usually not needed---Emacs creates a fresh buffer if none -already exists; but if a buffer visiting the file already exists Emacs -returns that one. In this case, the buffer may be narrowed and must -be widened. If we wanted to be fully `user-friendly', we would -arrange to save the restriction and the location of point, but we -won't. - -The @code{(goto-char (point-min))} expression moves point to the -beginning of the buffer. - -Then comes a @code{while} loop in which the `work' of the function is -carried out. In the loop, Emacs determines the length of each -definition and constructs a lengths' list containing the information. - -Emacs kills the buffer after working through it. This is to save -space inside of Emacs. My version of GNU Emacs 19 contained over 300 -source files of interest; GNU Emacs 22 contains over a thousand source -files. Another function will apply @code{lengths-list-file} to each -of the files. - -Finally, the last expression within the @code{let} expression is the -@code{lengths-list} variable; its value is returned as the value of -the whole function. - -You can try this function by installing it in the usual fashion. Then -place your cursor after the following expression and type @kbd{C-x -C-e} (@code{eval-last-sexp}). - -@c !!! 22.1.1 lisp sources location here -@smallexample -(lengths-list-file - "/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el") -@end smallexample - -@noindent -(You may need to change the pathname of the file; the one here is for -GNU Emacs version 22.1.1. To change the expression, copy it to -the @file{*scratch*} buffer and edit it. - -@need 1200 -@noindent -(Also, to see the full length of the list, rather than a truncated -version, you may have to evaluate the following: - -@smallexample -(custom-set-variables '(eval-expression-print-length nil)) -@end smallexample - -@noindent -(@xref{defcustom, , Specifying Variables using @code{defcustom}}. -Then evaluate the @code{lengths-list-file} expression.) - -@need 1200 -The lengths' list for @file{debug.el} takes less than a second to -produce and looks like this in GNU Emacs 22: - -@smallexample -(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587) -@end smallexample - -@need 1500 -(Using my old machine, the version 19 lengths' list for @file{debug.el} -took seven seconds to produce and looked like this: - -@smallexample -(75 41 80 62 20 45 44 68 45 12 34 235) -@end smallexample - -(The newer version of @file{debug.el} contains more defuns than the -earlier one; and my new machine is much faster than the old one.) - -Note that the length of the last definition in the file is first in -the list. - -@node Several files, Several files recursively, lengths-list-file, Words in a defun -@section Count Words in @code{defuns} in Different Files - -In the previous section, we created a function that returns a list of -the lengths of each definition in a file. Now, we want to define a -function to return a master list of the lengths of the definitions in -a list of files. - -Working on each of a list of files is a repetitious act, so we can use -either a @code{while} loop or recursion. - -@menu -* lengths-list-many-files:: Return a list of the lengths of defuns. -* append:: Attach one list to another. -@end menu - -@node lengths-list-many-files, append, Several files, Several files -@ifnottex -@unnumberedsubsec Determine the lengths of @code{defuns} -@end ifnottex - -The design using a @code{while} loop is routine. The argument passed -the function is a list of files. As we saw earlier (@pxref{Loop -Example}), you can write a @code{while} loop so that the body of the -loop is evaluated if such a list contains elements, but to exit the -loop if the list is empty. For this design to work, the body of the -loop must contain an expression that shortens the list each time the -body is evaluated, so that eventually the list is empty. The usual -technique is to set the value of the list to the value of the @sc{cdr} -of the list each time the body is evaluated. - -@need 800 -The template looks like this: - -@smallexample -@group -(while @var{test-whether-list-is-empty} - @var{body}@dots{} - @var{set-list-to-cdr-of-list}) -@end group -@end smallexample - -Also, we remember that a @code{while} loop returns @code{nil} (the -result of evaluating the true-or-false-test), not the result of any -evaluation within its body. (The evaluations within the body of the -loop are done for their side effects.) However, the expression that -sets the lengths' list is part of the body---and that is the value -that we want returned by the function as a whole. To do this, we -enclose the @code{while} loop within a @code{let} expression, and -arrange that the last element of the @code{let} expression contains -the value of the lengths' list. (@xref{Incrementing Example, , Loop -Example with an Incrementing Counter}.) - -@findex lengths-list-many-files -@need 1250 -These considerations lead us directly to the function itself: - -@smallexample -@group -;;; @r{Use @code{while} loop.} -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." -@end group -@group - (let (lengths-list) - -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list - -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -@end group - -@group -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) - -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@code{expand-file-name} is a built-in function that converts a file -name to the absolute, long, path name form. The function employs the -name of the directory in which the function is called. - -@c !!! 22.1.1 lisp sources location here -@need 1500 -Thus, if @code{expand-file-name} is called on @code{debug.el} when -Emacs is visiting the -@file{/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/} directory, - -@smallexample -debug.el -@end smallexample - -@need 800 -@noindent -becomes - -@c !!! 22.1.1 lisp sources location here -@smallexample -/usr/local/share/emacs/22.1.1/lisp/emacs-lisp/debug.el -@end smallexample - -The only other new element of this function definition is the as yet -unstudied function @code{append}, which merits a short section for -itself. - -@node append, , lengths-list-many-files, Several files -@subsection The @code{append} Function - -@need 800 -The @code{append} function attaches one list to another. Thus, - -@smallexample -(append '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 800 -@noindent -produces the list - -@smallexample -(1 2 3 4 5 6 7 8) -@end smallexample - -This is exactly how we want to attach two lengths' lists produced by -@code{lengths-list-file} to each other. The results contrast with -@code{cons}, - -@smallexample -(cons '(1 2 3 4) '(5 6 7 8)) -@end smallexample - -@need 1250 -@noindent -which constructs a new list in which the first argument to @code{cons} -becomes the first element of the new list: - -@smallexample -((1 2 3 4) 5 6 7 8) -@end smallexample - -@node Several files recursively, Prepare the data, Several files, Words in a defun -@section Recursively Count Words in Different Files - -Besides a @code{while} loop, you can work on each of a list of files -with recursion. A recursive version of @code{lengths-list-many-files} -is short and simple. - -The recursive function has the usual parts: the `do-again-test', the -`next-step-expression', and the recursive call. The `do-again-test' -determines whether the function should call itself again, which it -will do if the @code{list-of-files} contains any remaining elements; -the `next-step-expression' resets the @code{list-of-files} to the -@sc{cdr} of itself, so eventually the list will be empty; and the -recursive call calls itself on the shorter list. The complete -function is shorter than this description! -@findex recursive-lengths-list-many-files - -@smallexample -@group -(defun recursive-lengths-list-many-files (list-of-files) - "Return list of lengths of each defun in LIST-OF-FILES." - (if list-of-files ; @r{do-again-test} - (append - (lengths-list-file - (expand-file-name (car list-of-files))) - (recursive-lengths-list-many-files - (cdr list-of-files))))) -@end group -@end smallexample - -@noindent -In a sentence, the function returns the lengths' list for the first of -the @code{list-of-files} appended to the result of calling itself on -the rest of the @code{list-of-files}. - -Here is a test of @code{recursive-lengths-list-many-files}, along with -the results of running @code{lengths-list-file} on each of the files -individually. - -Install @code{recursive-lengths-list-many-files} and -@code{lengths-list-file}, if necessary, and then evaluate the -following expressions. You may need to change the files' pathnames; -those here work when this Info file and the Emacs sources are located -in their customary places. To change the expressions, copy them to -the @file{*scratch*} buffer, edit them, and then evaluate them. - -The results are shown after the @samp{@result{}}. (These results are -for files from Emacs version 22.1.1; files from other versions of -Emacs may produce different results.) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(cd "/usr/local/share/emacs/22.1.1/") - -(lengths-list-file "./lisp/macros.el") - @result{} (283 263 480 90) -@end group - -@group -(lengths-list-file "./lisp/mail/mailalias.el") - @result{} (38 32 29 95 178 180 321 218 324) -@end group - -@group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) -@end group - -@group - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) -@end group -@end smallexample - -The @code{recursive-lengths-list-many-files} function produces the -output we want. - -The next step is to prepare the data in the list for display in a graph. - -@node Prepare the data, , Several files recursively, Words in a defun -@section Prepare the Data for Display in a Graph - -The @code{recursive-lengths-list-many-files} function returns a list -of numbers. Each number records the length of a function definition. -What we need to do now is transform this data into a list of numbers -suitable for generating a graph. The new list will tell how many -functions definitions contain less than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -In brief, we need to go through the lengths' list produced by the -@code{recursive-lengths-list-many-files} function and count the number -of defuns within each range of lengths, and produce a list of those -numbers. - -@menu -* Data for Display in Detail:: -* Sorting:: Sorting lists. -* Files List:: Making a list of files. -* Counting function definitions:: -@end menu - -@node Data for Display in Detail, Sorting, Prepare the data, Prepare the data -@ifnottex -@unnumberedsubsec The Data for Display in Detail -@end ifnottex - -Based on what we have done before, we can readily foresee that it -should not be too hard to write a function that `@sc{cdr}s' down the -lengths' list, looks at each element, determines which length range it -is in, and increments a counter for that range. - -However, before beginning to write such a function, we should consider -the advantages of sorting the lengths' list first, so the numbers are -ordered from smallest to largest. First, sorting will make it easier -to count the numbers in each range, since two adjacent numbers will -either be in the same length range or in adjacent ranges. Second, by -inspecting a sorted list, we can discover the highest and lowest -number, and thereby determine the largest and smallest length range -that we will need. - -@node Sorting, Files List, Data for Display in Detail, Prepare the data -@subsection Sorting Lists -@findex sort - -Emacs contains a function to sort lists, called (as you might guess) -@code{sort}. The @code{sort} function takes two arguments, the list -to be sorted, and a predicate that determines whether the first of -two list elements is ``less'' than the second. - -As we saw earlier (@pxref{Wrong Type of Argument, , Using the Wrong -Type Object as an Argument}), a predicate is a function that -determines whether some property is true or false. The @code{sort} -function will reorder a list according to whatever property the -predicate uses; this means that @code{sort} can be used to sort -non-numeric lists by non-numeric criteria---it can, for example, -alphabetize a list. - -@need 1250 -The @code{<} function is used when sorting a numeric list. For example, - -@smallexample -(sort '(4 8 21 17 33 7 21 7) '<) -@end smallexample - -@need 800 -@noindent -produces this: - -@smallexample -(4 7 7 8 17 21 21 33) -@end smallexample - -@noindent -(Note that in this example, both the arguments are quoted so that the -symbols are not evaluated before being passed to @code{sort} as -arguments.) - -Sorting the list returned by the -@code{recursive-lengths-list-many-files} function is straightforward; -it uses the @code{<} function: - -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - -@smallexample -@group -(sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mailalias.el" - "./lisp/makesum.el")) - '<) -@end group -@end smallexample - -@need 800 -@noindent -which produces: - -@smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) -@end smallexample - -@noindent -(Note that in this example, the first argument to @code{sort} is not -quoted, since the expression must be evaluated so as to produce the -list that is passed to @code{sort}.) - -@node Files List, Counting function definitions, Sorting, Prepare the data -@subsection Making a List of Files - -The @code{recursive-lengths-list-many-files} function requires a list -of files as its argument. For our test examples, we constructed such -a list by hand; but the Emacs Lisp source directory is too large for -us to do for that. Instead, we will write a function to do the job -for us. In this function, we will use both a @code{while} loop and a -recursive call. - -@findex directory-files -We did not have to write a function like this for older versions of -GNU Emacs, since they placed all the @samp{.el} files in one -directory. Instead, we were able to use the @code{directory-files} -function, which lists the names of files that match a specified -pattern within a single directory. - -However, recent versions of Emacs place Emacs Lisp files in -sub-directories of the top level @file{lisp} directory. This -re-arrangement eases navigation. For example, all the mail related -files are in a @file{lisp} sub-directory called @file{mail}. But at -the same time, this arrangement forces us to create a file listing -function that descends into the sub-directories. - -@findex files-in-below-directory -We can create this function, called @code{files-in-below-directory}, -using familiar functions such as @code{car}, @code{nthcdr}, and -@code{substring} in conjunction with an existing function called -@code{directory-files-and-attributes}. This latter function not only -lists all the filenames in a directory, including the names -of sub-directories, but also their attributes. - -To restate our goal: to create a function that will enable us -to feed filenames to @code{recursive-lengths-list-many-files} -as a list that looks like this (but with more elements): - -@smallexample -@group -("./lisp/macros.el" - "./lisp/mail/rmail.el" - "./lisp/makesum.el") -@end group -@end smallexample - -The @code{directory-files-and-attributes} function returns a list of -lists. Each of the lists within the main list consists of 13 -elements. The first element is a string that contains the name of the -file -- which, in GNU/Linux, may be a `directory file', that is to -say, a file with the special attributes of a directory. The second -element of the list is @code{t} for a directory, a string -for symbolic link (the string is the name linked to), or @code{nil}. - -For example, the first @samp{.el} file in the @file{lisp/} directory -is @file{abbrev.el}. Its name is -@file{/usr/local/share/emacs/22.1.1/lisp/abbrev.el} and it is not a -directory or a symbolic link. - -@need 1000 -This is how @code{directory-files-and-attributes} lists that file and -its attributes: - -@smallexample -@group -("abbrev.el" -nil -1 -1000 -100 -@end group -@group -(17733 259) -(17491 28834) -(17596 62124) -13157 -"-rw-rw-r--" -@end group -@group -nil -2971624 -773) -@end group -@end smallexample - -@need 1200 -On the other hand, @file{mail/} is a directory within the @file{lisp/} -directory. The beginning of its listing looks like this: - -@smallexample -@group -("mail" -t -@dots{} -) -@end group -@end smallexample - -(To learn about the different attributes, look at the documentation of -@code{file-attributes}. Bear in mind that the @code{file-attributes} -function does not list the filename, so its first element is -@code{directory-files-and-attributes}'s second element.) - -We will want our new function, @code{files-in-below-directory}, to -list the @samp{.el} files in the directory it is told to check, and in -any directories below that directory. - -This gives us a hint on how to construct -@code{files-in-below-directory}: within a directory, the function -should add @samp{.el} filenames to a list; and if, within a directory, -the function comes upon a sub-directory, it should go into that -sub-directory and repeat its actions. - -However, we should note that every directory contains a name that -refers to itself, called @file{.}, (``dot'') and a name that refers to -its parent directory, called @file{..} (``double dot''). (In -@file{/}, the root directory, @file{..} refers to itself, since -@file{/} has no parent.) Clearly, we do not want our -@code{files-in-below-directory} function to enter those directories, -since they always lead us, directly or indirectly, to the current -directory. - -Consequently, our @code{files-in-below-directory} function must do -several tasks: - -@itemize @bullet -@item -Check to see whether it is looking at a filename that ends in -@samp{.el}; and if so, add its name to a list. - -@item -Check to see whether it is looking at a filename that is the name of a -directory; and if so, - -@itemize @minus -@item -Check to see whether it is looking at @file{.} or @file{..}; and if -so skip it. - -@item -Or else, go into that directory and repeat the process. -@end itemize -@end itemize - -Let's write a function definition to do these tasks. We will use a -@code{while} loop to move from one filename to another within a -directory, checking what needs to be done; and we will use a recursive -call to repeat the actions on each sub-directory. The recursive -pattern is `accumulate' -(@pxref{Accumulate, , Recursive Pattern: @emph{accumulate}}), -using @code{append} as the combiner. - -@ignore -(directory-files "/usr/local/src/emacs/lisp/" t "\\.el$") -(shell-command "find /usr/local/src/emacs/lisp/ -name '*.el'") - -(directory-files "/usr/local/share/emacs/22.1.1/lisp/" t "\\.el$") -(shell-command "find /usr/local/share/emacs/22.1.1/lisp/ -name '*.el'") -@end ignore - -@c /usr/local/share/emacs/22.1.1/lisp/ - -@need 800 -Here is the function: - -@smallexample -@group -(defun files-in-below-directory (directory) - "List the .el files in DIRECTORY and in its sub-directories." - ;; Although the function will be used non-interactively, - ;; it will be easier to test if we make it interactive. - ;; The directory will have a name such as - ;; "/usr/local/share/emacs/22.1.1/lisp/" - (interactive "DDirectory name: ") -@end group -@group - (let (el-files-list - (current-directory-list - (directory-files-and-attributes directory t))) - ;; while we are in the current directory - (while current-directory-list -@end group -@group - (cond - ;; check to see whether filename ends in `.el' - ;; and if so, append its name to a list. - ((equal ".el" (substring (car (car current-directory-list)) -3)) - (setq el-files-list - (cons (car (car current-directory-list)) el-files-list))) -@end group -@group - ;; check whether filename is that of a directory - ((eq t (car (cdr (car current-directory-list)))) - ;; decide whether to skip or recurse - (if - (equal "." - (substring (car (car current-directory-list)) -1)) - ;; then do nothing since filename is that of - ;; current directory or parent, "." or ".." - () -@end group -@group - ;; else descend into the directory and repeat the process - (setq el-files-list - (append - (files-in-below-directory - (car (car current-directory-list))) - el-files-list))))) - ;; move to the next filename in the list; this also - ;; shortens the list so the while loop eventually comes to an end - (setq current-directory-list (cdr current-directory-list))) - ;; return the filenames - el-files-list)) -@end group -@end smallexample - -@c (files-in-below-directory "/usr/local/src/emacs/lisp/") -@c (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - -The @code{files-in-below-directory} @code{directory-files} function -takes one argument, the name of a directory. - -@need 1250 -Thus, on my system, - -@c (length (files-in-below-directory "/usr/local/src/emacs/lisp/")) - -@c !!! 22.1.1 lisp sources location here -@smallexample -@group -(length - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/")) -@end group -@end smallexample - -@noindent -tells me that in and below my Lisp sources directory are 1031 -@samp{.el} files. - -@code{files-in-below-directory} returns a list in reverse alphabetical -order. An expression to sort the list in alphabetical order looks -like this: - -@smallexample -@group -(sort - (files-in-below-directory "/usr/local/share/emacs/22.1.1/lisp/") - 'string-lessp) -@end group -@end smallexample - -@ignore -(defun test () - "Test how long it takes to find lengths of all sorted elisp defuns." - (insert "\n" (current-time-string) "\n") - (sit-for 0) - (sort - (recursive-lengths-list-many-files - (files-in-below-directory "/usr/local/src/emacs/lisp/")) - '<) - (insert (format "%s" (current-time-string)))) -@end ignore - -@node Counting function definitions, , Files List, Prepare the data -@subsection Counting function definitions - -Our immediate goal is to generate a list that tells us how many -function definitions contain fewer than 10 words and symbols, how many -contain between 10 and 19 words and symbols, how many contain between -20 and 29 words and symbols, and so on. - -With a sorted list of numbers, this is easy: count how many elements -of the list are smaller than 10, then, after moving past the numbers -just counted, count how many are smaller than 20, then, after moving -past the numbers just counted, count how many are smaller than 30, and -so on. Each of the numbers, 10, 20, 30, 40, and the like, is one -larger than the top of that range. We can call the list of such -numbers the @code{top-of-ranges} list. - -@need 1200 -If we wished, we could generate this list automatically, but it is -simpler to write a list manually. Here it is: -@vindex top-of-ranges - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) - "List specifying ranges for `defuns-per-range'.") -@end group -@end smallexample - -To change the ranges, we edit this list. - -Next, we need to write the function that creates the list of the -number of definitions within each range. Clearly, this function must -take the @code{sorted-lengths} and the @code{top-of-ranges} lists -as arguments. - -The @code{defuns-per-range} function must do two things again and -again: it must count the number of definitions within a range -specified by the current top-of-range value; and it must shift to the -next higher value in the @code{top-of-ranges} list after counting the -number of definitions in the current range. Since each of these -actions is repetitive, we can use @code{while} loops for the job. -One loop counts the number of definitions in the range defined by the -current top-of-range value, and the other loop selects each of the -top-of-range values in turn. - -Several entries of the @code{sorted-lengths} list are counted for each -range; this means that the loop for the @code{sorted-lengths} list -will be inside the loop for the @code{top-of-ranges} list, like a -small gear inside a big gear. - -The inner loop counts the number of definitions within the range. It -is a simple counting loop of the type we have seen before. -(@xref{Incrementing Loop, , A loop with an incrementing counter}.) -The true-or-false test of the loop tests whether the value from the -@code{sorted-lengths} list is smaller than the current value of the -top of the range. If it is, the function increments the counter and -tests the next value from the @code{sorted-lengths} list. - -@need 1250 -The inner loop looks like this: - -@smallexample -@group -(while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group -@end smallexample - -The outer loop must start with the lowest value of the -@code{top-of-ranges} list, and then be set to each of the succeeding -higher values in turn. This can be done with a loop like this: - -@smallexample -@group -(while top-of-ranges - @var{body-of-loop}@dots{} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -@need 1200 -Put together, the two loops look like this: - -@smallexample -@group -(while top-of-ranges - - ;; @r{Count the number of elements within the current range.} - (while @var{length-element-smaller-than-top-of-range} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges))) -@end group -@end smallexample - -In addition, in each circuit of the outer loop, Emacs should record -the number of definitions within that range (the value of -@code{number-within-range}) in a list. We can use @code{cons} for -this purpose. (@xref{cons, , @code{cons}}.) - -The @code{cons} function works fine, except that the list it -constructs will contain the number of definitions for the highest -range at its beginning and the number of definitions for the lowest -range at its end. This is because @code{cons} attaches new elements -of the list to the beginning of the list, and since the two loops are -working their way through the lengths' list from the lower end first, -the @code{defuns-per-range-list} will end up largest number first. -But we will want to print our graph with smallest values first and the -larger later. The solution is to reverse the order of the -@code{defuns-per-range-list}. We can do this using the -@code{nreverse} function, which reverses the order of a list. -@findex nreverse - -@need 800 -For example, - -@smallexample -(nreverse '(1 2 3 4)) -@end smallexample - -@need 800 -@noindent -produces: - -@smallexample -(4 3 2 1) -@end smallexample - -Note that the @code{nreverse} function is ``destructive''---that is, -it changes the list to which it is applied; this contrasts with the -@code{car} and @code{cdr} functions, which are non-destructive. In -this case, we do not want the original @code{defuns-per-range-list}, -so it does not matter that it is destroyed. (The @code{reverse} -function provides a reversed copy of a list, leaving the original list -as is.) -@findex reverse - -@need 1250 -Put all together, the @code{defuns-per-range} looks like this: - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges -@end group - -@group - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group - -@group - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) - - ;; @r{Exit inner loop but remain within outer loop.} -@end group - -@group - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} -@end group - -@group - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) -@end group - -@group - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@need 1200 -@noindent -The function is straightforward except for one subtle feature. The -true-or-false test of the inner loop looks like this: - -@smallexample -@group -(and (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) -@end group -@end smallexample - -@need 800 -@noindent -instead of like this: - -@smallexample -(< (car sorted-lengths) top-of-range) -@end smallexample - -The purpose of the test is to determine whether the first item in the -@code{sorted-lengths} list is less than the value of the top of the -range. - -The simple version of the test works fine unless the -@code{sorted-lengths} list has a @code{nil} value. In that case, the -@code{(car sorted-lengths)} expression function returns -@code{nil}. The @code{<} function cannot compare a number to -@code{nil}, which is an empty list, so Emacs signals an error and -stops the function from attempting to continue to execute. - -The @code{sorted-lengths} list always becomes @code{nil} when the -counter reaches the end of the list. This means that any attempt to -use the @code{defuns-per-range} function with the simple version of -the test will fail. - -We solve the problem by using the @code{(car sorted-lengths)} -expression in conjunction with the @code{and} expression. The -@code{(car sorted-lengths)} expression returns a non-@code{nil} -value so long as the list has at least one number within it, but -returns @code{nil} if the list is empty. The @code{and} expression -first evaluates the @code{(car sorted-lengths)} expression, and -if it is @code{nil}, returns false @emph{without} evaluating the -@code{<} expression. But if the @code{(car sorted-lengths)} -expression returns a non-@code{nil} value, the @code{and} expression -evaluates the @code{<} expression, and returns that value as the value -of the @code{and} expression. - -@c colon in printed section title causes problem in Info cross reference -This way, we avoid an error. -@iftex -@noindent -(For information about @code{and}, see -@ref{kill-new function, , The @code{kill-new} function}.) -@end iftex -@ifinfo -@noindent -(@xref{kill-new function, , The @code{kill-new} function}, for -information about @code{and}.) -@end ifinfo - -Here is a short test of the @code{defuns-per-range} function. First, -evaluate the expression that binds (a shortened) -@code{top-of-ranges} list to the list of values, then evaluate the -expression for binding the @code{sorted-lengths} list, and then -evaluate the @code{defuns-per-range} function. - -@smallexample -@group -;; @r{(Shorter list than we will use later.)} -(setq top-of-ranges - '(110 120 130 140 150 - 160 170 180 190 200)) - -(setq sorted-lengths - '(85 86 110 116 122 129 154 176 179 200 265 300 300)) - -(defuns-per-range sorted-lengths top-of-ranges) -@end group -@end smallexample - -@need 800 -@noindent -The list returned looks like this: - -@smallexample -(2 2 2 0 0 1 0 2 0 0 4) -@end smallexample - -@noindent -Indeed, there are two elements of the @code{sorted-lengths} list -smaller than 110, two elements between 110 and 119, two elements -between 120 and 129, and so on. There are four elements with a value -of 200 or larger. - -@c The next step is to turn this numbers' list into a graph. -@node Readying a Graph, Emacs Initialization, Words in a defun, Top -@chapter Readying a Graph -@cindex Readying a graph -@cindex Graph prototype -@cindex Prototype graph -@cindex Body of graph - -Our goal is to construct a graph showing the numbers of function -definitions of various lengths in the Emacs lisp sources. - -As a practical matter, if you were creating a graph, you would -probably use a program such as @code{gnuplot} to do the job. -(@code{gnuplot} is nicely integrated into GNU Emacs.) In this case, -however, we create one from scratch, and in the process we will -re-acquaint ourselves with some of what we learned before and learn -more. - -In this chapter, we will first write a simple graph printing function. -This first definition will be a @dfn{prototype}, a rapidly written -function that enables us to reconnoiter this unknown graph-making -territory. We will discover dragons, or find that they are myth. -After scouting the terrain, we will feel more confident and enhance -the function to label the axes automatically. - -@menu -* Columns of a graph:: -* graph-body-print:: How to print the body of a graph. -* recursive-graph-body-print:: -* Printed Axes:: -* Line Graph Exercise:: -@end menu - -@node Columns of a graph, graph-body-print, Readying a Graph, Readying a Graph -@ifnottex -@unnumberedsec Printing the Columns of a Graph -@end ifnottex - -Since Emacs is designed to be flexible and work with all kinds of -terminals, including character-only terminals, the graph will need to -be made from one of the `typewriter' symbols. An asterisk will do; as -we enhance the graph-printing function, we can make the choice of -symbol a user option. - -We can call this function @code{graph-body-print}; it will take a -@code{numbers-list} as its only argument. At this stage, we will not -label the graph, but only print its body. - -The @code{graph-body-print} function inserts a vertical column of -asterisks for each element in the @code{numbers-list}. The height of -each line is determined by the value of that element of the -@code{numbers-list}. - -Inserting columns is a repetitive act; that means that this function can -be written either with a @code{while} loop or recursively. - -Our first challenge is to discover how to print a column of asterisks. -Usually, in Emacs, we print characters onto a screen horizontally, -line by line, by typing. We have two routes we can follow: write our -own column-insertion function or discover whether one exists in Emacs. - -To see whether there is one in Emacs, we can use the @kbd{M-x apropos} -command. This command is like the @kbd{C-h a} (@code{command-apropos}) -command, except that the latter finds only those functions that are -commands. The @kbd{M-x apropos} command lists all symbols that match -a regular expression, including functions that are not interactive. -@findex apropos - -What we want to look for is some command that prints or inserts -columns. Very likely, the name of the function will contain either -the word `print' or the word `insert' or the word `column'. -Therefore, we can simply type @kbd{M-x apropos RET -print\|insert\|column RET} and look at the result. On my system, this -command once too takes quite some time, and then produced a list of 79 -functions and variables. Now it does not take much time at all and -produces a list of 211 functions and variables. Scanning down the -list, the only function that looks as if it might do the job is -@code{insert-rectangle}. - -@need 1200 -Indeed, this is the function we want; its documentation says: - -@smallexample -@group -insert-rectangle: -Insert text of RECTANGLE with upper left corner at point. -RECTANGLE's first line is inserted at point, -its second line is inserted at a point vertically under point, etc. -RECTANGLE should be a list of strings. -After this command, the mark is at the upper left corner -and point is at the lower right corner. -@end group -@end smallexample - -We can run a quick test, to make sure it does what we expect of it. - -Here is the result of placing the cursor after the -@code{insert-rectangle} expression and typing @kbd{C-u C-x C-e} -(@code{eval-last-sexp}). The function inserts the strings -@samp{"first"}, @samp{"second"}, and @samp{"third"} at and below -point. Also the function returns @code{nil}. - -@smallexample -@group -(insert-rectangle '("first" "second" "third"))first - second - thirdnil -@end group -@end smallexample - -@noindent -Of course, we won't be inserting the text of the -@code{insert-rectangle} expression itself into the buffer in which we -are making the graph, but will call the function from our program. We -shall, however, have to make sure that point is in the buffer at the -place where the @code{insert-rectangle} function will insert its -column of strings. - -If you are reading this in Info, you can see how this works by -switching to another buffer, such as the @file{*scratch*} buffer, -placing point somewhere in the buffer, typing @kbd{M-:}, typing the -@code{insert-rectangle} expression into the minibuffer at the prompt, -and then typing @key{RET}. This causes Emacs to evaluate the -expression in the minibuffer, but to use as the value of point the -position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not -appear in the @file{*scratch*} buffer since the expression is -evaluated in the minibuffer.) - -We find when we do this that point ends up at the end of the last -inserted line---that is to say, this function moves point as a -side-effect. If we were to repeat the command, with point at this -position, the next insertion would be below and to the right of the -previous insertion. We don't want this! If we are going to make a -bar graph, the columns need to be beside each other. - -So we discover that each cycle of the column-inserting @code{while} -loop must reposition point to the place we want it, and that place -will be at the top, not the bottom, of the column. Moreover, we -remember that when we print a graph, we do not expect all the columns -to be the same height. This means that the top of each column may be -at a different height from the previous one. We cannot simply -reposition point to the same line each time, but moved over to the -right---or perhaps we can@dots{} - -We are planning to make the columns of the bar graph out of asterisks. -The number of asterisks in the column is the number specified by the -current element of the @code{numbers-list}. We need to construct a -list of asterisks of the right length for each call to -@code{insert-rectangle}. If this list consists solely of the requisite -number of asterisks, then we will have position point the right number -of lines above the base for the graph to print correctly. This could -be difficult. - -Alternatively, if we can figure out some way to pass -@code{insert-rectangle} a list of the same length each time, then we -can place point on the same line each time, but move it over one -column to the right for each new column. If we do this, however, some -of the entries in the list passed to @code{insert-rectangle} must be -blanks rather than asterisks. For example, if the maximum height of -the graph is 5, but the height of the column is 3, then -@code{insert-rectangle} requires an argument that looks like this: - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -This last proposal is not so difficult, so long as we can determine -the column height. There are two ways for us to specify the column -height: we can arbitrarily state what it will be, which would work -fine for graphs of that height; or we can search through the list of -numbers and use the maximum height of the list as the maximum height -of the graph. If the latter operation were difficult, then the former -procedure would be easiest, but there is a function built into Emacs -that determines the maximum of its arguments. We can use that -function. The function is called @code{max} and it returns the -largest of all its arguments, which must be numbers. Thus, for -example, - -@smallexample -(max 3 4 6 5 7 3) -@end smallexample - -@noindent -returns 7. (A corresponding function called @code{min} returns the -smallest of all its arguments.) -@findex max -@findex min - -However, we cannot simply call @code{max} on the @code{numbers-list}; -the @code{max} function expects numbers as its argument, not a list of -numbers. Thus, the following expression, - -@smallexample -(max '(3 4 6 5 7 3)) -@end smallexample - -@need 800 -@noindent -produces the following error message; - -@smallexample -Wrong type of argument: number-or-marker-p, (3 4 6 5 7 3) -@end smallexample - -@findex apply -We need a function that passes a list of arguments to a function. -This function is @code{apply}. This function `applies' its first -argument (a function) to its remaining arguments, the last of which -may be a list. - -@need 1250 -For example, - -@smallexample -(apply 'max 3 4 7 3 '(4 8 5)) -@end smallexample - -@noindent -returns 8. - -(Incidentally, I don't know how you would learn of this function -without a book such as this. It is possible to discover other -functions, like @code{search-forward} or @code{insert-rectangle}, by -guessing at a part of their names and then using @code{apropos}. Even -though its base in metaphor is clear---`apply' its first argument to -the rest---I doubt a novice would come up with that particular word -when using @code{apropos} or other aid. Of course, I could be wrong; -after all, the function was first named by someone who had to invent -it.) - -The second and subsequent arguments to @code{apply} are optional, so -we can use @code{apply} to call a function and pass the elements of a -list to it, like this, which also returns 8: - -@smallexample -(apply 'max '(4 8 5)) -@end smallexample - -This latter way is how we will use @code{apply}. The -@code{recursive-lengths-list-many-files} function returns a numbers' -list to which we can apply @code{max} (we could also apply @code{max} to -the sorted numbers' list; it does not matter whether the list is -sorted or not.) - -@need 800 -Hence, the operation for finding the maximum height of the graph is this: - -@smallexample -(setq max-graph-height (apply 'max numbers-list)) -@end smallexample - -Now we can return to the question of how to create a list of strings -for a column of the graph. Told the maximum height of the graph -and the number of asterisks that should appear in the column, the -function should return a list of strings for the -@code{insert-rectangle} command to insert. - -Each column is made up of asterisks or blanks. Since the function is -passed the value of the height of the column and the number of -asterisks in the column, the number of blanks can be found by -subtracting the number of asterisks from the height of the column. -Given the number of blanks and the number of asterisks, two -@code{while} loops can be used to construct the list: - -@smallexample -@group -;;; @r{First version.} -(defun column-of-graph (max-graph-height actual-height) - "Return list of strings that is one column of a graph." - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in asterisks.} - (while (> actual-height 0) - (setq insert-list (cons "*" insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in blanks.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons " " insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) -@end group - -@group - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If you install this function and then evaluate the following -expression you will see that it returns the list as desired: - -@smallexample -(column-of-graph 5 3) -@end smallexample - -@need 800 -@noindent -returns - -@smallexample -(" " " " "*" "*" "*") -@end smallexample - -As written, @code{column-of-graph} contains a major flaw: the symbols -used for the blank and for the marked entries in the column are -`hard-coded' as a space and asterisk. This is fine for a prototype, -but you, or another user, may wish to use other symbols. For example, -in testing the graph function, you many want to use a period in place -of the space, to make sure the point is being repositioned properly -each time the @code{insert-rectangle} function is called; or you might -want to substitute a @samp{+} sign or other symbol for the asterisk. -You might even want to make a graph-column that is more than one -display column wide. The program should be more flexible. The way to -do that is to replace the blank and the asterisk with two variables -that we can call @code{graph-blank} and @code{graph-symbol} and define -those variables separately. - -Also, the documentation is not well written. These considerations -lead us to the second version of the function: - -@smallexample -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group -@end smallexample - -@noindent -(For an explanation of @code{defvar}, see -@ref{defvar, , Initializing a Variable with @code{defvar}}.) - -@smallexample -@group -;;; @r{Second version.} -(defun column-of-graph (max-graph-height actual-height) - "Return MAX-GRAPH-HEIGHT strings; ACTUAL-HEIGHT are graph-symbols. - -@end group -@group -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -If we wished, we could rewrite @code{column-of-graph} a third time to -provide optionally for a line graph as well as for a bar graph. This -would not be hard to do. One way to think of a line graph is that it -is no more than a bar graph in which the part of each bar that is -below the top is blank. To construct a column for a line graph, the -function first constructs a list of blanks that is one shorter than -the value, then it uses @code{cons} to attach a graph symbol to the -list; then it uses @code{cons} again to attach the `top blanks' to -the list. - -It is easy to see how to write such a function, but since we don't -need it, we will not do it. But the job could be done, and if it were -done, it would be done with @code{column-of-graph}. Even more -important, it is worth noting that few changes would have to be made -anywhere else. The enhancement, if we ever wish to make it, is -simple. - -Now, finally, we come to our first actual graph printing function. -This prints the body of a graph, not the labels for the vertical and -horizontal axes, so we can call this @code{graph-body-print}. - -@node graph-body-print, recursive-graph-body-print, Columns of a graph, Readying a Graph -@section The @code{graph-body-print} Function -@findex graph-body-print - -After our preparation in the preceding section, the -@code{graph-body-print} function is straightforward. The function -will print column after column of asterisks and blanks, using the -elements of a numbers' list to specify the number of asterisks in each -column. This is a repetitive act, which means we can use a -decrementing @code{while} loop or recursive function for the job. In -this section, we will write the definition using a @code{while} loop. - -The @code{column-of-graph} function requires the height of the graph -as an argument, so we should determine and record that as a local variable. - -This leads us to the following template for the @code{while} loop -version of this function: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group - -@group - (while numbers-list - @var{insert-columns-and-reposition-point} - (setq numbers-list (cdr numbers-list))))) -@end group -@end smallexample - -@noindent -We need to fill in the slots of the template. - -Clearly, we can use the @code{(apply 'max numbers-list)} expression to -determine the height of the graph. - -The @code{while} loop will cycle through the @code{numbers-list} one -element at a time. As it is shortened by the @code{(setq numbers-list -(cdr numbers-list))} expression, the @sc{car} of each instance of the -list is the value of the argument for @code{column-of-graph}. - -At each cycle of the @code{while} loop, the @code{insert-rectangle} -function inserts the list returned by @code{column-of-graph}. Since -the @code{insert-rectangle} function moves point to the lower right of -the inserted rectangle, we need to save the location of point at the -time the rectangle is inserted, move back to that position after the -rectangle is inserted, and then move horizontally to the next place -from which @code{insert-rectangle} is called. - -If the inserted columns are one character wide, as they will be if -single blanks and asterisks are used, the repositioning command is -simply @code{(forward-char 1)}; however, the width of a column may be -greater than one. This means that the repositioning command should be -written @code{(forward-char symbol-width)}. The @code{symbol-width} -itself is the length of a @code{graph-blank} and can be found using -the expression @code{(length graph-blank)}. The best place to bind -the @code{symbol-width} variable to the value of the width of graph -column is in the varlist of the @code{let} expression. - -@need 1250 -These considerations lead to the following function definition: - -@smallexample -@group -(defun graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) -@end group - -@group - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) -@end group -@group - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n") -)) -@end group -@end smallexample - -@noindent -The one unexpected expression in this function is the -@w{@code{(sit-for 0)}} expression in the @code{while} loop. This -expression makes the graph printing operation more interesting to -watch than it would be otherwise. The expression causes Emacs to -`sit' or do nothing for a zero length of time and then redraw the -screen. Placed here, it causes Emacs to redraw the screen column by -column. Without it, Emacs would not redraw the screen until the -function exits. - -We can test @code{graph-body-print} with a short list of numbers. - -@enumerate -@item -Install @code{graph-symbol}, @code{graph-blank}, -@code{column-of-graph}, which are in -@iftex -@ref{Readying a Graph, , Readying a Graph}, -@end iftex -@ifinfo -@ref{Columns of a graph}, -@end ifinfo -and @code{graph-body-print}. - -@need 800 -@item -Copy the following expression: - -@smallexample -(graph-body-print '(1 2 3 4 6 4 3 5 7 6 5 2 3)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the graph to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the @code{graph-body-print} expression. -@end enumerate - -@need 800 -Emacs will print a graph like this: - -@smallexample -@group - * - * ** - * **** - *** **** - ********* * - ************ - ************* -@end group -@end smallexample - -@node recursive-graph-body-print, Printed Axes, graph-body-print, Readying a Graph -@section The @code{recursive-graph-body-print} Function -@findex recursive-graph-body-print - -The @code{graph-body-print} function may also be written recursively. -The recursive solution is divided into two parts: an outside `wrapper' -that uses a @code{let} expression to determine the values of several -variables that need only be found once, such as the maximum height of -the graph, and an inside function that is called recursively to print -the graph. - -@need 1250 -The `wrapper' is uncomplicated: - -@smallexample -@group -(defun recursive-graph-body-print (numbers-list) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values." - (let ((height (apply 'max numbers-list)) - (symbol-width (length graph-blank)) - from-position) - (recursive-graph-body-print-internal - numbers-list - height - symbol-width))) -@end group -@end smallexample - -The recursive function is a little more difficult. It has four parts: -the `do-again-test', the printing code, the recursive call, and the -`next-step-expression'. The `do-again-test' is a @code{when} -expression that determines whether the @code{numbers-list} contains -any remaining elements; if it does, the function prints one column of -the graph using the printing code and calls itself again. The -function calls itself again according to the value produced by the -`next-step-expression' which causes the call to act on a shorter -version of the @code{numbers-list}. - -@smallexample -@group -(defun recursive-graph-body-print-internal - (numbers-list height symbol-width) - "Print a bar graph. -Used within recursive-graph-body-print function." -@end group - -@group - (when numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) -@end group -@group - (goto-char from-position) - (forward-char symbol-width) - (sit-for 0) ; @r{Draw graph column by column.} - (recursive-graph-body-print-internal - (cdr numbers-list) height symbol-width))) -@end group -@end smallexample - -@need 1250 -After installation, this expression can be tested; here is a sample: - -@smallexample -(recursive-graph-body-print '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@need 800 -Here is what @code{recursive-graph-body-print} produces: - -@smallexample -@group - * - ** * - **** * - **** *** - * ********* - ************ - ************* -@end group -@end smallexample - -Either of these two functions, @code{graph-body-print} or -@code{recursive-graph-body-print}, create the body of a graph. - -@node Printed Axes, Line Graph Exercise, recursive-graph-body-print, Readying a Graph -@section Need for Printed Axes - -A graph needs printed axes, so you can orient yourself. For a do-once -project, it may be reasonable to draw the axes by hand using Emacs' -Picture mode; but a graph drawing function may be used more than once. - -For this reason, I have written enhancements to the basic -@code{print-graph-body} function that automatically print labels for -the horizontal and vertical axes. Since the label printing functions -do not contain much new material, I have placed their description in -an appendix. @xref{Full Graph, , A Graph with Labelled Axes}. - -@node Line Graph Exercise, , Printed Axes, Readying a Graph -@section Exercise - -Write a line graph version of the graph printing functions. - -@node Emacs Initialization, Debugging, Readying a Graph, Top -@chapter Your @file{.emacs} File -@cindex @file{.emacs} file -@cindex Customizing your @file{.emacs} file -@cindex Initialization file - -``You don't have to like Emacs to like it'' -- this seemingly -paradoxical statement is the secret of GNU Emacs. The plain, `out of -the box' Emacs is a generic tool. Most people who use it, customize -it to suit themselves. - -GNU Emacs is mostly written in Emacs Lisp; this means that by writing -expressions in Emacs Lisp you can change or extend Emacs. - -@menu -* Default Configuration:: -* Site-wide Init:: You can write site-wide init files. -* defcustom:: Emacs will write code for you. -* Beginning a .emacs File:: How to write a @code{.emacs file}. -* Text and Auto-fill:: Automatically wrap lines. -* Mail Aliases:: Use abbreviations for email addresses. -* Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. -* Keymaps:: More about key binding. -* Loading Files:: Load (i.e., evaluate) files automatically. -* Autoload:: Make functions available. -* Simple Extension:: Define a function; bind it to a key. -* X11 Colors:: Colors in X. -* Miscellaneous:: -* Mode Line:: How to customize your mode line. -@end menu - -@node Default Configuration, Site-wide Init, Emacs Initialization, Emacs Initialization -@ifnottex -@unnumberedsec Emacs' Default Configuration -@end ifnottex - -There are those who appreciate Emacs' default configuration. After -all, Emacs starts you in C mode when you edit a C file, starts you in -Fortran mode when you edit a Fortran file, and starts you in -Fundamental mode when you edit an unadorned file. This all makes -sense, if you do not know who is going to use Emacs. Who knows what a -person hopes to do with an unadorned file? Fundamental mode is the -right default for such a file, just as C mode is the right default for -editing C code. (Enough programming languages have syntaxes -that enable them to share or nearly share features, so C mode is -now provided by CC mode, the `C Collection'.) - -But when you do know who is going to use Emacs---you, -yourself---then it makes sense to customize Emacs. - -For example, I seldom want Fundamental mode when I edit an -otherwise undistinguished file; I want Text mode. This is why I -customize Emacs: so it suits me. - -You can customize and extend Emacs by writing or adapting a -@file{~/.emacs} file. This is your personal initialization file; its -contents, written in Emacs Lisp, tell Emacs what to do.@footnote{You -may also add @file{.el} to @file{~/.emacs} and call it a -@file{~/.emacs.el} file. In the past, you were forbidden to type the -extra keystrokes that the name @file{~/.emacs.el} requires, but now -you may. The new format is consistent with the Emacs Lisp file -naming conventions; the old format saves typing.} - -A @file{~/.emacs} file contains Emacs Lisp code. You can write this -code yourself; or you can use Emacs' @code{customize} feature to write -the code for you. You can combine your own expressions and -auto-written Customize expressions in your @file{.emacs} file. - -(I myself prefer to write my own expressions, except for those, -particularly fonts, that I find easier to manipulate using the -@code{customize} command. I combine the two methods.) - -Most of this chapter is about writing expressions yourself. It -describes a simple @file{.emacs} file; for more information, see -@ref{Init File, , The Init File, emacs, The GNU Emacs Manual}, and -@ref{Init File, , The Init File, elisp, The GNU Emacs Lisp Reference -Manual}. - -@node Site-wide Init, defcustom, Default Configuration, Emacs Initialization -@section Site-wide Initialization Files - -@cindex @file{default.el} init file -@cindex @file{site-init.el} init file -@cindex @file{site-load.el} init file -In addition to your personal initialization file, Emacs automatically -loads various site-wide initialization files, if they exist. These -have the same form as your @file{.emacs} file, but are loaded by -everyone. - -Two site-wide initialization files, @file{site-load.el} and -@file{site-init.el}, are loaded into Emacs and then `dumped' if a -`dumped' version of Emacs is created, as is most common. (Dumped -copies of Emacs load more quickly. However, once a file is loaded and -dumped, a change to it does not lead to a change in Emacs unless you -load it yourself or re-dump Emacs. @xref{Building Emacs, , Building -Emacs, elisp, The GNU Emacs Lisp Reference Manual}, and the -@file{INSTALL} file.) - -Three other site-wide initialization files are loaded automatically -each time you start Emacs, if they exist. These are -@file{site-start.el}, which is loaded @emph{before} your @file{.emacs} -file, and @file{default.el}, and the terminal type file, which are both -loaded @emph{after} your @file{.emacs} file. - -Settings and definitions in your @file{.emacs} file will overwrite -conflicting settings and definitions in a @file{site-start.el} file, -if it exists; but the settings and definitions in a @file{default.el} -or terminal type file will overwrite those in your @file{.emacs} file. -(You can prevent interference from a terminal type file by setting -@code{term-file-prefix} to @code{nil}. @xref{Simple Extension, , A -Simple Extension}.) - -@c Rewritten to avoid overfull hbox. -The @file{INSTALL} file that comes in the distribution contains -descriptions of the @file{site-init.el} and @file{site-load.el} files. - -The @file{loadup.el}, @file{startup.el}, and @file{loaddefs.el} files -control loading. These files are in the @file{lisp} directory of the -Emacs distribution and are worth perusing. - -The @file{loaddefs.el} file contains a good many suggestions as to -what to put into your own @file{.emacs} file, or into a site-wide -initialization file. - -@node defcustom, Beginning a .emacs File, Site-wide Init, Emacs Initialization -@section Specifying Variables using @code{defcustom} -@findex defcustom - -You can specify variables using @code{defcustom} so that you and -others can then use Emacs' @code{customize} feature to set their -values. (You cannot use @code{customize} to write function -definitions; but you can write @code{defuns} in your @file{.emacs} -file. Indeed, you can write any Lisp expression in your @file{.emacs} -file.) - -The @code{customize} feature depends on the @code{defcustom} special -form. Although you can use @code{defvar} or @code{setq} for variables -that users set, the @code{defcustom} special form is designed for the -job. - -You can use your knowledge of @code{defvar} for writing the -first three arguments for @code{defcustom}. The first argument to -@code{defcustom} is the name of the variable. The second argument is -the variable's initial value, if any; and this value is set only if -the value has not already been set. The third argument is the -documentation. - -The fourth and subsequent arguments to @code{defcustom} specify types -and options; these are not featured in @code{defvar}. (These -arguments are optional.) - -Each of these arguments consists of a keyword followed by a value. -Each keyword starts with the colon character @samp{:}. - -@need 1250 -For example, the customizable user option variable -@code{text-mode-hook} looks like this: - -@smallexample -@group -(defcustom text-mode-hook nil - "Normal hook run when entering Text mode and many related modes." - :type 'hook - :options '(turn-on-auto-fill flyspell-mode) - :group 'data) -@end group -@end smallexample - -@noindent -The name of the variable is @code{text-mode-hook}; it has no default -value; and its documentation string tells you what it does. - -The @code{:type} keyword tells Emacs the kind of data to which -@code{text-mode-hook} should be set and how to display the value in a -Customization buffer. - -The @code{:options} keyword specifies a suggested list of values for -the variable. Usually, @code{:options} applies to a hook. -The list is only a suggestion; it is not exclusive; a person who sets -the variable may set it to other values; the list shown following the -@code{:options} keyword is intended to offer convenient choices to a -user. - -Finally, the @code{:group} keyword tells the Emacs Customization -command in which group the variable is located. This tells where to -find it. - -The @code{defcustom} function recognizes more than a dozen keywords. -For more information, see @ref{Customization, , Writing Customization -Definitions, elisp, The GNU Emacs Lisp Reference Manual}. - -Consider @code{text-mode-hook} as an example. - -There are two ways to customize this variable. You can use the -customization command or write the appropriate expressions yourself. - -@need 800 -Using the customization command, you can type: - -@smallexample -M-x customize -@end smallexample - -@noindent -and find that the group for editing files of data is called `data'. -Enter that group. Text Mode Hook is the first member. You can click -on its various options, such as @code{turn-on-auto-fill}, to set the -values. After you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write an expression into your @file{.emacs} file. -It will look like this: - -@smallexample -@group -(custom-set-variables - ;; custom-set-variables was added by Custom. - ;; If you edit it by hand, you could mess it up, so be careful. - ;; Your init file should contain only one such instance. - ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) -@end group -@end smallexample - -@noindent -(The @code{text-mode-hook-identify} function tells -@code{toggle-text-mode-auto-fill} which buffers are in Text mode. -It comes on automatically.) - -The @code{custom-set-variables} function works somewhat differently -than a @code{setq}. While I have never learned the differences, I -modify the @code{custom-set-variables} expressions in my @file{.emacs} -file by hand: I make the changes in what appears to me to be a -reasonable manner and have not had any problems. Others prefer to use -the Customization command and let Emacs do the work for them. - -Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. -This function sets the various font faces. Over time, I have set a -considerable number of faces. Some of the time, I re-set them using -@code{customize}; other times, I simply edit the -@code{custom-set-faces} expression in my @file{.emacs} file itself. - -The second way to customize your @code{text-mode-hook} is to set it -yourself in your @file{.emacs} file using code that has nothing to do -with the @code{custom-set-@dots{}} functions. - -@need 800 -When you do this, and later use @code{customize}, you will see a -message that says - -@smallexample -CHANGED outside Customize; operating on it here may be unreliable. -@end smallexample - -@need 800 -This message is only a warning. If you click on the button to - -@smallexample -Save for Future Sessions -@end smallexample - -@noindent -Emacs will write a @code{custom-set-@dots{}} expression near the end -of your @file{.emacs} file that will be evaluated after your -hand-written expression. It will, therefore, overrule your -hand-written expression. No harm will be done. When you do this, -however, be careful to remember which expression is active; if you -forget, you may confuse yourself. - -So long as you remember where the values are set, you will have no -trouble. In any event, the values are always set in your -initialization file, which is usually called @file{.emacs}. - -I myself use @code{customize} for hardly anything. Mostly, I write -expressions myself. - -@findex defsubst -@findex defconst -Incidentally, to be more complete concerning defines: @code{defsubst} -defines an inline function. The syntax is just like that of -@code{defun}. @code{defconst} defines a symbol as a constant. The -intent is that neither programs nor users should ever change a value -set by @code{defconst}. (You can change it; the value set is a -variable; but please do not.) - -@node Beginning a .emacs File, Text and Auto-fill, defcustom, Emacs Initialization -@section Beginning a @file{.emacs} File -@cindex @file{.emacs} file, beginning of - -When you start Emacs, it loads your @file{.emacs} file unless you tell -it not to by specifying @samp{-q} on the command line. (The -@code{emacs -q} command gives you a plain, out-of-the-box Emacs.) - -A @file{.emacs} file contains Lisp expressions. Often, these are no -more than expressions to set values; sometimes they are function -definitions. - -@xref{Init File, , The Init File @file{~/.emacs}, emacs, The GNU Emacs -Manual}, for a short description of initialization files. - -This chapter goes over some of the same ground, but is a walk among -extracts from a complete, long-used @file{.emacs} file---my own. - -The first part of the file consists of comments: reminders to myself. -By now, of course, I remember these things, but when I started, I did -not. - -@need 1200 -@smallexample -@group -;;;; Bob's .emacs file -; Robert J. Chassell -; 26 September 1985 -@end group -@end smallexample - -@noindent -Look at that date! I started this file a long time ago. I have been -adding to it ever since. - -@smallexample -@group -; Each section in this file is introduced by a -; line beginning with four semicolons; and each -; entry is introduced by a line beginning with -; three semicolons. -@end group -@end smallexample - -@noindent -This describes the usual conventions for comments in Emacs Lisp. -Everything on a line that follows a semicolon is a comment. Two, -three, and four semicolons are used as subsection and section markers. -(@xref{Comments, ,, elisp, The GNU Emacs Lisp Reference Manual}, for -more about comments.) - -@smallexample -@group -;;;; The Help Key -; Control-h is the help key; -; after typing control-h, type a letter to -; indicate the subject about which you want help. -; For an explanation of the help facility, -; type control-h two times in a row. -@end group -@end smallexample - -@noindent -Just remember: type @kbd{C-h} two times for help. - -@smallexample -@group -; To find out about any mode, type control-h m -; while in that mode. For example, to find out -; about mail mode, enter mail mode and then type -; control-h m. -@end group -@end smallexample - -@noindent -`Mode help', as I call this, is very helpful. Usually, it tells you -all you need to know. - -Of course, you don't need to include comments like these in your -@file{.emacs} file. I included them in mine because I kept forgetting -about Mode help or the conventions for comments---but I was able to -remember to look here to remind myself. - -@node Text and Auto-fill, Mail Aliases, Beginning a .emacs File, Emacs Initialization -@section Text and Auto Fill Mode - -Now we come to the part that `turns on' Text mode and -Auto Fill mode. - -@smallexample -@group -;;; Text mode and Auto Fill mode -; The next two lines put Emacs into Text mode -; and Auto Fill mode, and are for writers who -; want to start writing prose rather than code. -(setq default-major-mode 'text-mode) -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end group -@end smallexample - -Here is the first part of this @file{.emacs} file that does something -besides remind a forgetful human! - -The first of the two lines in parentheses tells Emacs to turn on Text -mode when you find a file, @emph{unless} that file should go into some -other mode, such as C mode. - -@cindex Per-buffer, local variables list -@cindex Local variables list, per-buffer, -@cindex Automatic mode selection -@cindex Mode selection, automatic -When Emacs reads a file, it looks at the extension to the file name, -if any. (The extension is the part that comes after a @samp{.}.) If -the file ends with a @samp{.c} or @samp{.h} extension then Emacs turns -on C mode. Also, Emacs looks at first nonblank line of the file; if -the line says @w{@samp{-*- C -*-}}, Emacs turns on C mode. Emacs -possesses a list of extensions and specifications that it uses -automatically. In addition, Emacs looks near the last page for a -per-buffer, ``local variables list'', if any. - -@ifinfo -@xref{Choosing Modes, , How Major Modes are Chosen, emacs, The GNU -Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``How Major Modes are Chosen'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -Now, back to the @file{.emacs} file. - -@need 800 -Here is the line again; how does it work? - -@cindex Text Mode turned on -@smallexample -(setq default-major-mode 'text-mode) -@end smallexample - -@noindent -This line is a short, but complete Emacs Lisp expression. - -We are already familiar with @code{setq}. It sets the following variable, -@code{default-major-mode}, to the subsequent value, which is -@code{text-mode}. The single quote mark before @code{text-mode} tells -Emacs to deal directly with the @code{text-mode} variable, not with -whatever it might stand for. @xref{set & setq, , Setting the Value of -a Variable}, for a reminder of how @code{setq} works. The main point -is that there is no difference between the procedure you use to set -a value in your @file{.emacs} file and the procedure you use anywhere -else in Emacs. - -@need 800 -Here is the next line: - -@cindex Auto Fill mode turned on -@findex add-hook -@smallexample -(add-hook 'text-mode-hook 'turn-on-auto-fill) -@end smallexample - -@noindent -In this line, the @code{add-hook} command adds -@code{turn-on-auto-fill} to the variable. - -@code{turn-on-auto-fill} is the name of a program, that, you guessed -it!, turns on Auto Fill mode. - -Every time Emacs turns on Text mode, Emacs runs the commands `hooked' -onto Text mode. So every time Emacs turns on Text mode, Emacs also -turns on Auto Fill mode. - -In brief, the first line causes Emacs to enter Text mode when you edit a -file, unless the file name extension, a first non-blank line, or local -variables to tell Emacs otherwise. - -Text mode among other actions, sets the syntax table to work -conveniently for writers. In Text mode, Emacs considers an apostrophe -as part of a word like a letter; but Emacs does not consider a period -or a space as part of a word. Thus, @kbd{M-f} moves you over -@samp{it's}. On the other hand, in C mode, @kbd{M-f} stops just after -the @samp{t} of @samp{it's}. - -The second line causes Emacs to turn on Auto Fill mode when it turns -on Text mode. In Auto Fill mode, Emacs automatically breaks a line -that is too wide and brings the excessively wide part of the line down -to the next line. Emacs breaks lines between words, not within them. - -When Auto Fill mode is turned off, lines continue to the right as you -type them. Depending on how you set the value of -@code{truncate-lines}, the words you type either disappear off the -right side of the screen, or else are shown, in a rather ugly and -unreadable manner, as a continuation line on the screen. - -@need 1250 -In addition, in this part of my @file{.emacs} file, I tell the Emacs -fill commands to insert two spaces after a colon: - -@smallexample -(setq colon-double-space t) -@end smallexample - -@node Mail Aliases, Indent Tabs Mode, Text and Auto-fill, Emacs Initialization -@section Mail Aliases - -Here is a @code{setq} that `turns on' mail aliases, along with more -reminders. - -@smallexample -@group -;;; Mail mode -; To enter mail mode, type `C-x m' -; To enter RMAIL (for reading mail), -; type `M-x rmail' -(setq mail-aliases t) -@end group -@end smallexample - -@cindex Mail aliases -@noindent -This @code{setq} command sets the value of the variable -@code{mail-aliases} to @code{t}. Since @code{t} means true, the line -says, in effect, ``Yes, use mail aliases.'' - -Mail aliases are convenient short names for long email addresses or -for lists of email addresses. The file where you keep your `aliases' -is @file{~/.mailrc}. You write an alias like this: - -@smallexample -alias geo george@@foobar.wiz.edu -@end smallexample - -@noindent -When you write a message to George, address it to @samp{geo}; the -mailer will automatically expand @samp{geo} to the full address. - -@node Indent Tabs Mode, Keybindings, Mail Aliases, Emacs Initialization -@section Indent Tabs Mode -@cindex Tabs, preventing -@findex indent-tabs-mode - -By default, Emacs inserts tabs in place of multiple spaces when it -formats a region. (For example, you might indent many lines of text -all at once with the @code{indent-region} command.) Tabs look fine on -a terminal or with ordinary printing, but they produce badly indented -output when you use @TeX{} or Texinfo since @TeX{} ignores tabs. - -@need 1250 -The following turns off Indent Tabs mode: - -@smallexample -@group -;;; Prevent Extraneous Tabs -(setq-default indent-tabs-mode nil) -@end group -@end smallexample - -Note that this line uses @code{setq-default} rather than the -@code{setq} command that we have seen before. The @code{setq-default} -command sets values only in buffers that do not have their own local -values for the variable. - -@ifinfo -@xref{Just Spaces, , Tabs vs. Spaces, emacs, The GNU Emacs Manual}. - -@xref{File Variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}. -@end ifinfo -@iftex -See sections ``Tabs vs.@: Spaces'' and ``Local Variables in -Files'' in @cite{The GNU Emacs Manual}. -@end iftex - -@need 1700 -@node Keybindings, Keymaps, Indent Tabs Mode, Emacs Initialization -@section Some Keybindings - -Now for some personal keybindings: - -@smallexample -@group -;;; Compare windows -(global-set-key "\C-cw" 'compare-windows) -@end group -@end smallexample - -@findex compare-windows -@code{compare-windows} is a nifty command that compares the text in -your current window with text in the next window. It makes the -comparison by starting at point in each window, moving over text in -each window as far as they match. I use this command all the time. - -This also shows how to set a key globally, for all modes. - -@cindex Setting a key globally -@cindex Global set key -@cindex Key setting globally -@findex global-set-key -The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as -shown: @code{\C-c} stands for `control-c', which means `press the -control key and the @key{c} key at the same time'. The @code{w} means -`press the @key{w} key'. The keybinding is surrounded by double -quotation marks. In documentation, you would write this as -@w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as -@kbd{M-c}, rather than a @key{CTRL} key, you would write -@w{@code{\M-c}} in your @file{.emacs} file. @xref{Init Rebinding, , -Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for -details.) - -The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs -would first try to evaluate the symbol to determine its value. - -These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to -remember that I should look at my existing @file{.emacs} file, and -adapt what is there. - -As for the keybinding itself: @kbd{C-c w}. This combines the prefix -key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This -set of keys, @kbd{C-c} followed by a single character, is strictly -reserved for individuals' own use. (I call these `own' keys, since -these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid -taking any of these keys for public use. Create a key like @kbd{C-c -C-w} instead. Otherwise, we will run out of `own' keys. - -@need 1250 -Here is another keybinding, with a comment: - -@smallexample -@group -;;; Keybinding for `occur' -; I use occur a lot, so let's bind it to a key: -(global-set-key "\C-co" 'occur) -@end group -@end smallexample - -@findex occur -The @code{occur} command shows all the lines in the current buffer -that contain a match for a regular expression. Matching lines are -shown in a buffer called @file{*Occur*}. That buffer serves as a menu -to jump to occurrences. - -@findex global-unset-key -@cindex Unbinding key -@cindex Key unbinding -@need 1250 -Here is how to unbind a key, so it does not -work: - -@smallexample -@group -;;; Unbind `C-x f' -(global-unset-key "\C-xf") -@end group -@end smallexample - -There is a reason for this unbinding: I found I inadvertently typed -@w{@kbd{C-x f}} when I meant to type @kbd{C-x C-f}. Rather than find a -file, as I intended, I accidentally set the width for filled text, -almost always to a width I did not want. Since I hardly ever reset my -default width, I simply unbound the key. - -@findex list-buffers, @r{rebound} -@findex buffer-menu, @r{bound to key} -@need 1250 -The following rebinds an existing key: - -@smallexample -@group -;;; Rebind `C-x C-b' for `buffer-menu' -(global-set-key "\C-x\C-b" 'buffer-menu) -@end group -@end smallexample - -By default, @kbd{C-x C-b} runs the -@code{list-buffers} command. This command lists -your buffers in @emph{another} window. Since I -almost always want to do something in that -window, I prefer the @code{buffer-menu} -command, which not only lists the buffers, -but moves point into that window. - -@node Keymaps, Loading Files, Keybindings, Emacs Initialization -@section Keymaps -@cindex Keymaps -@cindex Rebinding keys - -Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in -@code{current-global-map}. - -Specific modes, such as C mode or Text mode, have their own keymaps; -the mode-specific keymaps override the global map that is shared by -all buffers. - -The @code{global-set-key} function binds, or rebinds, the global -keymap. For example, the following binds the key @kbd{C-x C-b} to the -function @code{buffer-menu}: - -@smallexample -(global-set-key "\C-x\C-b" 'buffer-menu) -@end smallexample - -Mode-specific keymaps are bound using the @code{define-key} function, -which takes a specific keymap as an argument, as well as the key and -the command. For example, my @file{.emacs} file contains the -following expression to bind the @code{texinfo-insert-@@group} command -to @kbd{C-c C-c g}: - -@smallexample -@group -(define-key texinfo-mode-map "\C-c\C-cg" 'texinfo-insert-@@group) -@end group -@end smallexample - -@noindent -The @code{texinfo-insert-@@group} function itself is a little extension -to Texinfo mode that inserts @samp{@@group} into a Texinfo file. I -use this command all the time and prefer to type the three strokes -@kbd{C-c C-c g} rather than the six strokes @kbd{@@ g r o u p}. -(@samp{@@group} and its matching @samp{@@end group} are commands that -keep all enclosed text together on one page; many multi-line examples -in this book are surrounded by @samp{@@group @dots{} @@end group}.) - -@need 1250 -Here is the @code{texinfo-insert-@@group} function definition: - -@smallexample -@group -(defun texinfo-insert-@@group () - "Insert the string @@group in a Texinfo buffer." - (interactive) - (beginning-of-line) - (insert "@@group\n")) -@end group -@end smallexample - -(Of course, I could have used Abbrev mode to save typing, rather than -write a function to insert a word; but I prefer key strokes consistent -with other Texinfo mode key bindings.) - -You will see numerous @code{define-key} expressions in -@file{loaddefs.el} as well as in the various mode libraries, such as -@file{cc-mode.el} and @file{lisp-mode.el}. - -@xref{Key Bindings, , Customizing Key Bindings, emacs, The GNU Emacs -Manual}, and @ref{Keymaps, , Keymaps, elisp, The GNU Emacs Lisp -Reference Manual}, for more information about keymaps. - -@node Loading Files, Autoload, Keymaps, Emacs Initialization -@section Loading Files -@cindex Loading files -@c findex load - -Many people in the GNU Emacs community have written extensions to -Emacs. As time goes by, these extensions are often included in new -releases. For example, the Calendar and Diary packages are now part -of the standard GNU Emacs, as is Calc. - -You can use a @code{load} command to evaluate a complete file and -thereby install all the functions and variables in the file into Emacs. -For example: - -@c (auto-compression-mode t) - -@smallexample -(load "~/emacs/slowsplit") -@end smallexample - -This evaluates, i.e.@: loads, the @file{slowsplit.el} file or if it -exists, the faster, byte compiled @file{slowsplit.elc} file from the -@file{emacs} sub-directory of your home directory. The file contains -the function @code{split-window-quietly}, which John Robinson wrote in -1989. - -The @code{split-window-quietly} function splits a window with the -minimum of redisplay. I installed it in 1989 because it worked well -with the slow 1200 baud terminals I was then using. Nowadays, I only -occasionally come across such a slow connection, but I continue to use -the function because I like the way it leaves the bottom half of a -buffer in the lower of the new windows and the top half in the upper -window. - -@need 1250 -To replace the key binding for the default -@code{split-window-vertically}, you must also unset that key and bind -the keys to @code{split-window-quietly}, like this: - -@smallexample -@group -(global-unset-key "\C-x2") -(global-set-key "\C-x2" 'split-window-quietly) -@end group -@end smallexample - -@vindex load-path -If you load many extensions, as I do, then instead of specifying the -exact location of the extension file, as shown above, you can specify -that directory as part of Emacs' @code{load-path}. Then, when Emacs -loads a file, it will search that directory as well as its default -list of directories. (The default list is specified in @file{paths.h} -when Emacs is built.) - -@need 1250 -The following command adds your @file{~/emacs} directory to the -existing load path: - -@smallexample -@group -;;; Emacs Load Path -(setq load-path (cons "~/emacs" load-path)) -@end group -@end smallexample - -Incidentally, @code{load-library} is an interactive interface to the -@code{load} function. The complete function looks like this: - -@findex load-library -@smallexample -@group -(defun load-library (library) - "Load the library named LIBRARY. -This is an interface to the function `load'." - (interactive - (list (completing-read "Load library: " - (apply-partially 'locate-file-completion-table - load-path - (get-load-suffixes))))) - (load library)) -@end group -@end smallexample - -The name of the function, @code{load-library}, comes from the use of -`library' as a conventional synonym for `file'. The source for the -@code{load-library} command is in the @file{files.el} library. - -Another interactive command that does a slightly different job is -@code{load-file}. @xref{Lisp Libraries, , Libraries of Lisp Code for -Emacs, emacs, The GNU Emacs Manual}, for information on the -distinction between @code{load-library} and this command. - -@node Autoload, Simple Extension, Loading Files, Emacs Initialization -@section Autoloading -@findex autoload - -Instead of installing a function by loading the file that contains it, -or by evaluating the function definition, you can make the function -available but not actually install it until it is first called. This -is called @dfn{autoloading}. - -When you execute an autoloaded function, Emacs automatically evaluates -the file that contains the definition, and then calls the function. - -Emacs starts quicker with autoloaded functions, since their libraries -are not loaded right away; but you need to wait a moment when you -first use such a function, while its containing file is evaluated. - -Rarely used functions are frequently autoloaded. The -@file{loaddefs.el} library contains hundreds of autoloaded functions, -from @code{bookmark-set} to @code{wordstar-mode}. Of course, you may -come to use a `rare' function frequently. When you do, you should -load that function's file with a @code{load} expression in your -@file{.emacs} file. - -In my @file{.emacs} file, I load 14 libraries that contain functions -that would otherwise be autoloaded. (Actually, it would have been -better to include these files in my `dumped' Emacs, but I forgot. -@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, and the @file{INSTALL} file for more about -dumping.) - -You may also want to include autoloaded expressions in your @file{.emacs} -file. @code{autoload} is a built-in function that takes up to five -arguments, the final three of which are optional. The first argument -is the name of the function to be autoloaded; the second is the name -of the file to be loaded. The third argument is documentation for the -function, and the fourth tells whether the function can be called -interactively. The fifth argument tells what type of -object---@code{autoload} can handle a keymap or macro as well as a -function (the default is a function). - -@need 800 -Here is a typical example: - -@smallexample -@group -(autoload 'html-helper-mode - "html-helper-mode" "Edit HTML documents" t) -@end group -@end smallexample - -@noindent -(@code{html-helper-mode} is an older alternative to @code{html-mode}, -which is a standard part of the distribution.) - -@noindent -This expression autoloads the @code{html-helper-mode} function. It -takes it from the @file{html-helper-mode.el} file (or from the byte -compiled version @file{html-helper-mode.elc}, if that exists.) The -file must be located in a directory specified by @code{load-path}. -The documentation says that this is a mode to help you edit documents -written in the HyperText Markup Language. You can call this mode -interactively by typing @kbd{M-x html-helper-mode}. (You need to -duplicate the function's regular documentation in the autoload -expression because the regular function is not yet loaded, so its -documentation is not available.) - -@xref{Autoload, , Autoload, elisp, The GNU Emacs Lisp Reference -Manual}, for more information. - -@node Simple Extension, X11 Colors, Autoload, Emacs Initialization -@section A Simple Extension: @code{line-to-top-of-window} -@findex line-to-top-of-window -@cindex Simple extension in @file{.emacs} file - -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. - -You can put the following code into a separate file and then load it -from your @file{.emacs} file, or you can include it within your -@file{.emacs} file. - -@need 1250 -Here is the definition: - -@smallexample -@group -;;; Line to top of window; -;;; replace three keystroke sequence C-u 0 C-l -(defun line-to-top-of-window () - "Move the line point is on to top of window." - (interactive) - (recenter 0)) -@end group -@end smallexample - -@need 1250 -Now for the keybinding. - -Nowadays, function keys as well as mouse button events and -non-@sc{ascii} characters are written within square brackets, without -quotation marks. (In Emacs version 18 and before, you had to write -different function key bindings for each different make of terminal.) - -I bind @code{line-to-top-of-window} to my @key{F6} function key like -this: - -@smallexample -(global-set-key [f6] 'line-to-top-of-window) -@end smallexample - -For more information, see @ref{Init Rebinding, , Rebinding Keys in -Your Init File, emacs, The GNU Emacs Manual}. - -@cindex Conditional 'twixt two versions of Emacs -@cindex Version of Emacs, choosing -@cindex Emacs version, choosing -If you run two versions of GNU Emacs, such as versions 22 and 23, and -use one @file{.emacs} file, you can select which code to evaluate with -the following conditional: - -@smallexample -@group -(cond - ((= 22 emacs-major-version) - ;; evaluate version 21 code - ( @dots{} )) - ((= 23 emacs-major-version) - ;; evaluate version 22 code - ( @dots{} ))) -@end group -@end smallexample - -For example, in contrast to version 20, more recent versions blink -their cursors by default. I hate such blinking, as well as other -features, so I placed the following in my @file{.emacs} -file@footnote{When I start instances of Emacs that do not load my -@file{.emacs} file or any site file, I also turn off blinking: - -@smallexample -emacs -q --no-site-file -eval '(blink-cursor-mode nil)' - -@exdent Or nowadays, using an even more sophisticated set of options, - -emacs -Q - D -@end smallexample -}: - -@smallexample -@group -(when (>= emacs-major-version 21) - (blink-cursor-mode 0) - ;; Insert newline when you press `C-n' (next-line) - ;; at the end of the buffer - (setq next-line-add-newlines t) -@end group -@group - ;; Turn on image viewing - (auto-image-file-mode t) -@end group -@group - ;; Turn on menu bar (this bar has text) - ;; (Use numeric argument to turn on) - (menu-bar-mode 1) -@end group -@group - ;; Turn off tool bar (this bar has icons) - ;; (Use numeric argument to turn on) - (tool-bar-mode nil) -@end group -@group - ;; Turn off tooltip mode for tool bar - ;; (This mode causes icon explanations to pop up) - ;; (Use numeric argument to turn on) - (tooltip-mode nil) - ;; If tooltips turned on, make tips appear promptly - (setq tooltip-delay 0.1) ; default is 0.7 second - ) -@end group -@end smallexample - -@node X11 Colors, Miscellaneous, Simple Extension, Emacs Initialization -@section X11 Colors - -You can specify colors when you use Emacs with the MIT X Windowing -system. - -I dislike the default colors and specify my own. - -@need 1250 -Here are the expressions in my @file{.emacs} -file that set values: - -@smallexample -@group -;; Set cursor color -(set-cursor-color "white") - -;; Set mouse color -(set-mouse-color "white") - -;; Set foreground and background -(set-foreground-color "white") -(set-background-color "darkblue") -@end group - -@group -;;; Set highlighting colors for isearch and drag -(set-face-foreground 'highlight "white") -(set-face-background 'highlight "blue") -@end group - -@group -(set-face-foreground 'region "cyan") -(set-face-background 'region "blue") -@end group - -@group -(set-face-foreground 'secondary-selection "skyblue") -(set-face-background 'secondary-selection "darkblue") -@end group - -@group -;; Set calendar highlighting colors -(setq calendar-load-hook - '(lambda () - (set-face-foreground 'diary-face "skyblue") - (set-face-background 'holiday-face "slate blue") - (set-face-foreground 'holiday-face "white"))) -@end group -@end smallexample - -The various shades of blue soothe my eye and prevent me from seeing -the screen flicker. - -Alternatively, I could have set my specifications in various X -initialization files. For example, I could set the foreground, -background, cursor, and pointer (i.e., mouse) colors in my -@file{~/.Xresources} file like this: - -@smallexample -@group -Emacs*foreground: white -Emacs*background: darkblue -Emacs*cursorColor: white -Emacs*pointerColor: white -@end group -@end smallexample - -In any event, since it is not part of Emacs, I set the root color of -my X window in my @file{~/.xinitrc} file, like this@footnote{I also -run more modern window managers, such as Enlightenment, Gnome, or KDE; -in those cases, I often specify an image rather than a plain color.}: - -@smallexample -xsetroot -solid Navy -fg white & -@end smallexample - -@need 1700 -@node Miscellaneous, Mode Line, X11 Colors, Emacs Initialization -@section Miscellaneous Settings for a @file{.emacs} File - -@need 1250 -Here are a few miscellaneous settings: -@sp 1 - -@itemize @minus -@item -Set the shape and color of the mouse cursor: - -@smallexample -@group -; Cursor shapes are defined in -; `/usr/include/X11/cursorfont.h'; -; for example, the `target' cursor is number 128; -; the `top_left_arrow' cursor is number 132. -@end group - -@group -(let ((mpointer (x-get-resource "*mpointer" - "*emacs*mpointer"))) - ;; If you have not set your mouse pointer - ;; then set it, otherwise leave as is: - (if (eq mpointer nil) - (setq mpointer "132")) ; top_left_arrow -@end group -@group - (setq x-pointer-shape (string-to-int mpointer)) - (set-mouse-color "white")) -@end group -@end smallexample - -@item -Or you can set the values of a variety of features in an alist, like -this: - -@smallexample -@group -(setq-default - default-frame-alist - '((cursor-color . "white") - (mouse-color . "white") - (foreground-color . "white") - (background-color . "DodgerBlue4") - ;; (cursor-type . bar) - (cursor-type . box) -@end group -@group - (tool-bar-lines . 0) - (menu-bar-lines . 1) - (width . 80) - (height . 58) - (font . - "-Misc-Fixed-Medium-R-Normal--20-200-75-75-C-100-ISO8859-1") - )) -@end group -@end smallexample - -@item -Convert @kbd{@key{CTRL}-h} into @key{DEL} and @key{DEL} -into @kbd{@key{CTRL}-h}.@* -(Some older keyboards needed this, although I have not seen the -problem recently.) - -@smallexample -@group -;; Translate `C-h' to . -; (keyboard-translate ?\C-h ?\C-?) - -;; Translate to `C-h'. -(keyboard-translate ?\C-? ?\C-h) -@end group -@end smallexample - -@item Turn off a blinking cursor! - -@smallexample -@group -(if (fboundp 'blink-cursor-mode) - (blink-cursor-mode -1)) -@end group -@end smallexample - -@noindent -or start GNU Emacs with the command @code{emacs -nbc}. - -@need 1250 -@item When using `grep'@* -@samp{-i}@w{ } Ignore case distinctions@* -@samp{-n}@w{ } Prefix each line of output with line number@* -@samp{-H}@w{ } Print the filename for each match.@* -@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} - -@smallexample -(setq grep-command "grep -i -nH -e ") -@end smallexample - -@ignore -@c Evidently, no longer needed in GNU Emacs 22 - -item Automatically uncompress compressed files when visiting them - -smallexample -(load "uncompress") -end smallexample - -@end ignore - -@item Find an existing buffer, even if it has a different name@* -This avoids problems with symbolic links. - -@smallexample -(setq find-file-existing-other-name t) -@end smallexample - -@item Set your language environment and default input method - -@smallexample -@group -(set-language-environment "latin-1") -;; Remember you can enable or disable multilingual text input -;; with the @code{toggle-input-method'} (@kbd{C-\}) command -(setq default-input-method "latin-1-prefix") -@end group -@end smallexample - -If you want to write with Chinese `GB' characters, set this instead: - -@smallexample -@group -(set-language-environment "Chinese-GB") -(setq default-input-method "chinese-tonepy") -@end group -@end smallexample -@end itemize - -@subsubheading Fixing Unpleasant Key Bindings -@cindex Key bindings, fixing -@cindex Bindings, key, fixing unpleasant - -Some systems bind keys unpleasantly. Sometimes, for example, the -@key{CTRL} key appears in an awkward spot rather than at the far left -of the home row. - -Usually, when people fix these sorts of keybindings, they do not -change their @file{~/.emacs} file. Instead, they bind the proper keys -on their consoles with the @code{loadkeys} or @code{install-keymap} -commands in their boot script and then include @code{xmodmap} commands -in their @file{.xinitrc} or @file{.Xsession} file for X Windows. - -@need 1250 -@noindent -For a boot script: - -@smallexample -@group -loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz -@exdent or -install-keymap emacs2 -@end group -@end smallexample - -@need 1250 -@noindent -For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps -Lock} key is at the far left of the home row: - -@smallexample -@group -# Bind the key labeled `Caps Lock' to `Control' -# (Such a broken user interface suggests that keyboard manufacturers -# think that computers are typewriters from 1885.) - -xmodmap -e "clear Lock" -xmodmap -e "add Control = Caps_Lock" -@end group -@end smallexample - -@need 1250 -@noindent -In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} -key to a @key{META} key: - -@smallexample -@group -# Some ill designed keyboards have a key labeled ALT and no Meta -xmodmap -e "keysym Alt_L = Meta_L Alt_L" -@end group -@end smallexample - -@need 1700 -@node Mode Line, , Miscellaneous, Emacs Initialization -@section A Modified Mode Line -@vindex default-mode-line-format -@cindex Mode line format - -Finally, a feature I really like: a modified mode line. - -When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. - -So I reset my mode line to look like this: - -@smallexample --:-- foo.texi rattlesnake:/home/bob/ Line 1 (Texinfo Fill) Top -@end smallexample - -I am visiting a file called @file{foo.texi}, on my machine -@file{rattlesnake} in my @file{/home/bob} buffer. I am on line 1, in -Texinfo mode, and am at the top of the buffer. - -@need 1200 -My @file{.emacs} file has a section that looks like this: - -@smallexample -@group -;; Set a Mode Line that tells me which machine, which directory, -;; and which line I am on, plus the other customary information. -(setq default-mode-line-format - (quote - (#("-" 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - " " -@end group -@group - mode-line-buffer-identification - " " - (:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) - ":" - default-directory - #(" " 0 1 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (line-number-mode " Line %l ") - global-mode-string -@end group -@group - #(" %[(" 0 6 - (help-echo - "mouse-1: select window, mouse-2: delete others ...")) - (:eval (mode-line-mode-name)) - mode-line-process - minor-mode-alist - #("%n" 0 2 (help-echo "mouse-2: widen" local-map (keymap ...))) - ")%] " - (-3 . "%P") - ;; "-%-" - ))) -@end group -@end smallexample - -@noindent -Here, I redefine the default mode line. Most of the parts are from -the original; but I make a few changes. I set the @emph{default} mode -line format so as to permit various modes, such as Info, to override -it. - -Many elements in the list are self-explanatory: -@code{mode-line-modified} is a variable that tells whether the buffer -has been modified, @code{mode-name} tells the name of the mode, and so -on. However, the format looks complicated because of two features we -have not discussed. - -@cindex Properties, in mode line example -The first string in the mode line is a dash or hyphen, @samp{-}. In -the old days, it would have been specified simply as @code{"-"}. But -nowadays, Emacs can add properties to a string, such as highlighting -or, as in this case, a help feature. If you place your mouse cursor -over the hyphen, some help information appears (By default, you must -wait seven-tenths of a second before the information appears. You can -change that timing by changing the value of @code{tooltip-delay}.) - -@need 1000 -The new string format has a special syntax: - -@smallexample -#("-" 0 1 (help-echo "mouse-1: select window, ...")) -@end smallexample - -@noindent -The @code{#(} begins a list. The first element of the list is the -string itself, just one @samp{-}. The second and third -elements specify the range over which the fourth element applies. A -range starts @emph{after} a character, so a zero means the range -starts just before the first character; a 1 means that the range ends -just after the first character. The third element is the property for -the range. It consists of a property list, a -property name, in this case, @samp{help-echo}, followed by a value, in this -case, a string. The second, third, and fourth elements of this new -string format can be repeated. - -@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp -Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, -elisp, The GNU Emacs Lisp Reference Manual}, for more information. - -@code{mode-line-buffer-identification} -displays the current buffer name. It is a list -beginning @code{(#("%12b" 0 4 @dots{}}. -The @code{#(} begins the list. - -The @samp{"%12b"} displays the current buffer name, using the -@code{buffer-name} function with which we are familiar; the `12' -specifies the maximum number of characters that will be displayed. -When a name has fewer characters, whitespace is added to fill out to -this number. (Buffer names can and often should be longer than 12 -characters; this length works well in a typical 80 column wide -window.) - -@code{:eval} says to evaluate the following form and use the result as -a string to display. In this case, the expression displays the first -component of the full system name. The end of the first component is -a @samp{.} (`period'), so I use the @code{string-match} function to -tell me the length of the first component. The substring from the -zeroth character to that length is the name of the machine. - -@need 1250 -This is the expression: - -@smallexample -@group -(:eval (substring - (system-name) 0 (string-match "\\..+" (system-name)))) -@end group -@end smallexample - -@samp{%[} and @samp{%]} cause a pair of square brackets -to appear for each recursive editing level. @samp{%n} says `Narrow' -when narrowing is in effect. @samp{%P} tells you the percentage of -the buffer that is above the bottom of the window, or `Top', `Bottom', -or `All'. (A lower case @samp{p} tell you the percentage above the -@emph{top} of the window.) @samp{%-} inserts enough dashes to fill -out the line. - -Remember, ``You don't have to like Emacs to like it'' --- your own -Emacs can have different colors, different commands, and different -keys than a default Emacs. - -On the other hand, if you want to bring up a plain `out of the box' -Emacs, with no customization, type: - -@smallexample -emacs -q -@end smallexample - -@noindent -This will start an Emacs that does @emph{not} load your -@file{~/.emacs} initialization file. A plain, default Emacs. Nothing -more. - -@node Debugging, Conclusion, Emacs Initialization, Top -@chapter Debugging -@cindex debugging - -GNU Emacs has two debuggers, @code{debug} and @code{edebug}. The -first is built into the internals of Emacs and is always with you; -the second requires that you instrument a function before you can use it. - -Both debuggers are described extensively in @ref{Debugging, , -Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}. -In this chapter, I will walk through a short example of each. - -@menu -* debug:: How to use the built-in debugger. -* debug-on-entry:: Start debugging when you call a function. -* debug-on-quit:: Start debugging when you quit with @kbd{C-g}. -* edebug:: How to use Edebug, a source level debugger. -* Debugging Exercises:: -@end menu - -@node debug, debug-on-entry, Debugging, Debugging -@section @code{debug} -@findex debug - -Suppose you have written a function definition that is intended to -return the sum of the numbers 1 through a given number. (This is the -@code{triangle} function discussed earlier. @xref{Decrementing -Example, , Example with Decrementing Counter}, for a discussion.) -@c xref{Decrementing Loop,, Loop with a Decrementing Counter}, for a discussion.) - -However, your function definition has a bug. You have mistyped -@samp{1=} for @samp{1-}. Here is the broken definition: - -@findex triangle-bugged -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -If you are reading this in Info, you can evaluate this definition in -the normal fashion. You will see @code{triangle-bugged} appear in the -echo area. - -@need 1250 -Now evaluate the @code{triangle-bugged} function with an -argument of 4: - -@smallexample -(triangle-bugged 4) -@end smallexample - -@noindent -In a recent GNU Emacs, you will create and enter a @file{*Backtrace*} -buffer that says: - -@noindent -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) - (1= number) - (setq number (1= number)) - (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) - (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) - triangle-bugged(4) -@end group -@group - eval((triangle-bugged 4)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -(I have reformatted this example slightly; the debugger does not fold -long lines. As usual, you can quit the debugger by typing @kbd{q} in -the @file{*Backtrace*} buffer.) - -In practice, for a bug as simple as this, the `Lisp error' line will -tell you what you need to know to correct the definition. The -function @code{1=} is `void'. - -@ignore -@need 800 -In GNU Emacs 20 and before, you will see: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -which has the same meaning as the @file{*Backtrace*} buffer line in -version 21. -@end ignore - -However, suppose you are not quite certain what is going on? -You can read the complete backtrace. - -In this case, you need to run a recent GNU Emacs, which automatically -starts the debugger that puts you in the @file{*Backtrace*} buffer; or -else, you need to start the debugger manually as described below. - -Read the @file{*Backtrace*} buffer from the bottom up; it tells you -what Emacs did that led to the error. Emacs made an interactive call -to @kbd{C-x C-e} (@code{eval-last-sexp}), which led to the evaluation -of the @code{triangle-bugged} expression. Each line above tells you -what the Lisp interpreter evaluated next. - -@need 1250 -The third line from the top of the buffer is - -@smallexample -(setq number (1= number)) -@end smallexample - -@noindent -Emacs tried to evaluate this expression; in order to do so, it tried -to evaluate the inner expression shown on the second line from the -top: - -@smallexample -(1= number) -@end smallexample - -@need 1250 -@noindent -This is where the error occurred; as the top line says: - -@smallexample -Debugger entered--Lisp error: (void-function 1=) -@end smallexample - -@noindent -You can correct the mistake, re-evaluate the function definition, and -then run your test again. - -@node debug-on-entry, debug-on-quit, debug, Debugging -@section @code{debug-on-entry} -@findex debug-on-entry - -A recent GNU Emacs starts the debugger automatically when your -function has an error. - -@ignore -GNU Emacs version 20 and before did not; it simply -presented you with an error message. You had to start the debugger -manually. -@end ignore - -Incidentally, you can start the debugger manually for all versions of -Emacs; the advantage is that the debugger runs even if you do not have -a bug in your code. Sometimes your code will be free of bugs! - -You can enter the debugger when you call the function by calling -@code{debug-on-entry}. - -@need 1250 -@noindent -Type: - -@smallexample -M-x debug-on-entry RET triangle-bugged RET -@end smallexample - -@need 1250 -@noindent -Now, evaluate the following: - -@smallexample -(triangle-bugged 5) -@end smallexample - -@noindent -All versions of Emacs will create a @file{*Backtrace*} buffer and tell -you that it is beginning to evaluate the @code{triangle-bugged} -function: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--entering a function: -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -In the @file{*Backtrace*} buffer, type @kbd{d}. Emacs will evaluate -the first expression in @code{triangle-bugged}; the buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@end group -@group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@noindent -Now, type @kbd{d} again, eight times, slowly. Each time you type -@kbd{d}, Emacs will evaluate another expression in the function -definition. - -@need 1750 -Eventually, the buffer will look like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--beginning evaluation of function call form: -* (setq number (1= number)) -* (while (> number 0) (setq total (+ total number)) - (setq number (1= number))) -@group -@end group -* (let ((total 0)) (while (> number 0) (setq total ...) - (setq number ...)) total) -* triangle-bugged(5) - eval((triangle-bugged 5)) -@group -@end group - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -@need 1500 -@noindent -Finally, after you type @kbd{d} two more times, Emacs will reach the -error, and the top two lines of the @file{*Backtrace*} buffer will look -like this: - -@smallexample -@group ----------- Buffer: *Backtrace* ---------- -Debugger entered--Lisp error: (void-function 1=) -* (1= number) -@dots{} ----------- Buffer: *Backtrace* ---------- -@end group -@end smallexample - -By typing @kbd{d}, you were able to step through the function. - -You can quit a @file{*Backtrace*} buffer by typing @kbd{q} in it; this -quits the trace, but does not cancel @code{debug-on-entry}. - -@findex cancel-debug-on-entry -To cancel the effect of @code{debug-on-entry}, call -@code{cancel-debug-on-entry} and the name of the function, like this: - -@smallexample -M-x cancel-debug-on-entry RET triangle-bugged RET -@end smallexample - -@noindent -(If you are reading this in Info, cancel @code{debug-on-entry} now.) - -@node debug-on-quit, edebug, debug-on-entry, Debugging -@section @code{debug-on-quit} and @code{(debug)} - -In addition to setting @code{debug-on-error} or calling @code{debug-on-entry}, -there are two other ways to start @code{debug}. - -@findex debug-on-quit -You can start @code{debug} whenever you type @kbd{C-g} -(@code{keyboard-quit}) by setting the variable @code{debug-on-quit} to -@code{t}. This is useful for debugging infinite loops. - -@need 1500 -@cindex @code{(debug)} in code -Or, you can insert a line that says @code{(debug)} into your code -where you want the debugger to start, like this: - -@smallexample -@group -(defun triangle-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive." - (let ((total 0)) - (while (> number 0) - (setq total (+ total number)) - (debug) ; @r{Start debugger.} - (setq number (1= number))) ; @r{Error here.} - total)) -@end group -@end smallexample - -The @code{debug} function is described in detail in @ref{Debugger, , -The Lisp Debugger, elisp, The GNU Emacs Lisp Reference Manual}. - -@node edebug, Debugging Exercises, debug-on-quit, Debugging -@section The @code{edebug} Source Level Debugger -@cindex Source level debugger -@findex edebug - -Edebug is a source level debugger. Edebug normally displays the -source of the code you are debugging, with an arrow at the left that -shows which line you are currently executing. - -You can walk through the execution of a function, line by line, or run -quickly until reaching a @dfn{breakpoint} where execution stops. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1250 -Here is a bugged function definition for @code{triangle-recursively}. -@xref{Recursive triangle function, , Recursion in place of a counter}, -for a review of it. - -@smallexample -@group -(defun triangle-recursively-bugged (number) - "Return sum of numbers 1 through NUMBER inclusive. -Uses recursion." - (if (= number 1) - 1 - (+ number - (triangle-recursively-bugged - (1= number))))) ; @r{Error here.} -@end group -@end smallexample - -@noindent -Normally, you would install this definition by positioning your cursor -after the function's closing parenthesis and typing @kbd{C-x C-e} -(@code{eval-last-sexp}) or else by positioning your cursor within the -definition and typing @kbd{C-M-x} (@code{eval-defun}). (By default, -the @code{eval-defun} command works only in Emacs Lisp mode or in Lisp -Interaction mode.) - -@need 1500 -However, to prepare this function definition for Edebug, you must -first @dfn{instrument} the code using a different command. You can do -this by positioning your cursor within or just after the definition -and typing - -@smallexample -M-x edebug-defun RET -@end smallexample - -@noindent -This will cause Emacs to load Edebug automatically if it is not -already loaded, and properly instrument the function. - -After instrumenting the function, place your cursor after the -following expression and type @kbd{C-x C-e} (@code{eval-last-sexp}): - -@smallexample -(triangle-recursively-bugged 3) -@end smallexample - -@noindent -You will be jumped back to the source for -@code{triangle-recursively-bugged} and the cursor positioned at the -beginning of the @code{if} line of the function. Also, you will see -an arrowhead at the left hand side of that line. The arrowhead marks -the line where the function is executing. (In the following examples, -we show the arrowhead with @samp{=>}; in a windowing system, you may -see the arrowhead as a solid triangle in the window `fringe'.) - -@smallexample -=>@point{}(if (= number 1) -@end smallexample - -@noindent -@iftex -In the example, the location of point is displayed with a star, -@samp{@point{}} (in Info, it is displayed as @samp{-!-}). -@end iftex -@ifnottex -In the example, the location of point is displayed as @samp{@point{}} -(in a printed book, it is displayed with a five pointed star). -@end ifnottex - -If you now press @key{SPC}, point will move to the next expression to -be executed; the line will look like this: - -@smallexample -=>(if @point{}(= number 1) -@end smallexample - -@noindent -As you continue to press @key{SPC}, point will move from expression to -expression. At the same time, whenever an expression returns a value, -that value will be displayed in the echo area. For example, after you -move point past @code{number}, you will see the following: - -@smallexample -Result: 3 (#o3, #x3, ?\C-c) -@end smallexample - -@noindent -This means the value of @code{number} is 3, which is octal three, -hexadecimal three, and @sc{ascii} `control-c' (the third letter of the -alphabet, in case you need to know this information). - -You can continue moving through the code until you reach the line with -the error. Before evaluation, that line looks like this: - -@smallexample -=> @point{}(1= number))))) ; @r{Error here.} -@end smallexample - -@need 1250 -@noindent -When you press @key{SPC} once again, you will produce an error message -that says: - -@smallexample -Symbol's function definition is void:@: 1= -@end smallexample - -@noindent -This is the bug. - -Press @kbd{q} to quit Edebug. - -To remove instrumentation from a function definition, simply -re-evaluate it with a command that does not instrument it. -For example, you could place your cursor after the definition's -closing parenthesis and type @kbd{C-x C-e}. - -Edebug does a great deal more than walk with you through a function. -You can set it so it races through on its own, stopping only at an -error or at specified stopping points; you can cause it to display the -changing values of various expressions; you can find out how many -times a function is called, and more. - -Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs -Lisp Reference Manual}. - -@need 1500 -@node Debugging Exercises, , edebug, Debugging -@section Debugging Exercises - -@itemize @bullet -@item -Install the @code{count-words-region} function and then cause it to -enter the built-in debugger when you call it. Run the command on a -region containing two words. You will need to press @kbd{d} a -remarkable number of times. On your system, is a `hook' called after -the command finishes? (For information on hooks, see @ref{Command -Overview, , Command Loop Overview, elisp, The GNU Emacs Lisp Reference -Manual}.) - -@item -Copy @code{count-words-region} into the @file{*scratch*} buffer, -instrument the function for Edebug, and walk through its execution. -The function does not need to have a bug, although you can introduce -one if you wish. If the function lacks a bug, the walk-through -completes without problems. - -@item -While running Edebug, type @kbd{?} to see a list of all the Edebug commands. -(The @code{global-edebug-prefix} is usually @kbd{C-x X}, i.e.@: -@kbd{@key{CTRL}-x} followed by an upper case @kbd{X}; use this prefix -for commands made outside of the Edebug debugging buffer.) - -@item -In the Edebug debugging buffer, use the @kbd{p} -(@code{edebug-bounce-point}) command to see where in the region the -@code{count-words-region} is working. - -@item -Move point to some spot further down the function and then type the -@kbd{h} (@code{edebug-goto-here}) command to jump to that location. - -@item -Use the @kbd{t} (@code{edebug-trace-mode}) command to cause Edebug to -walk through the function on its own; use an upper case @kbd{T} for -@code{edebug-Trace-fast-mode}. - -@item -Set a breakpoint, then run Edebug in Trace mode until it reaches the -stopping point. -@end itemize - -@node Conclusion, the-the, Debugging, Top -@chapter Conclusion - -We have now reached the end of this Introduction. You have now -learned enough about programming in Emacs Lisp to set values, to write -simple @file{.emacs} files for yourself and your friends, and write -simple customizations and extensions to Emacs. - -This is a place to stop. Or, if you wish, you can now go onward, and -teach yourself. - -You have learned some of the basic nuts and bolts of programming. But -only some. There are a great many more brackets and hinges that are -easy to use that we have not touched. - -A path you can follow right now lies among the sources to GNU Emacs -and in -@ifnotinfo -@cite{The GNU Emacs Lisp Reference Manual}. -@end ifnotinfo -@ifinfo -@ref{Top, , The GNU Emacs Lisp Reference Manual, elisp, The GNU -Emacs Lisp Reference Manual}. -@end ifinfo - -The Emacs Lisp sources are an adventure. When you read the sources and -come across a function or expression that is unfamiliar, you need to -figure out or find out what it does. - -Go to the Reference Manual. It is a thorough, complete, and fairly -easy-to-read description of Emacs Lisp. It is written not only for -experts, but for people who know what you know. (The @cite{Reference -Manual} comes with the standard GNU Emacs distribution. Like this -introduction, it comes as a Texinfo source file, so you can read it -on-line and as a typeset, printed book.) - -Go to the other on-line help that is part of GNU Emacs: the on-line -documentation for all functions and variables, and @code{find-tags}, -the program that takes you to sources. - -Here is an example of how I explore the sources. Because of its name, -@file{simple.el} is the file I looked at first, a long time ago. As -it happens some of the functions in @file{simple.el} are complicated, -or at least look complicated at first sight. The @code{open-line} -function, for example, looks complicated. - -You may want to walk through this function slowly, as we did with the -@code{forward-sentence} function. (@xref{forward-sentence, The -@code{forward-sentence} function}.) Or you may want to skip that -function and look at another, such as @code{split-line}. You don't -need to read all the functions. According to -@code{count-words-in-defun}, the @code{split-line} function contains -102 words and symbols. - -Even though it is short, @code{split-line} contains expressions -we have not studied: @code{skip-chars-forward}, @code{indent-to}, -@code{current-column} and @code{insert-and-inherit}. - -Consider the @code{skip-chars-forward} function. (It is part of the -function definition for @code{back-to-indentation}, which is shown in -@ref{Review, , Review}.) - -In GNU Emacs, you can find out more about @code{skip-chars-forward} by -typing @kbd{C-h f} (@code{describe-function}) and the name of the -function. This gives you the function documentation. - -You may be able to guess what is done by a well named function such as -@code{indent-to}; or you can look it up, too. Incidentally, the -@code{describe-function} function itself is in @file{help.el}; it is -one of those long, but decipherable functions. You can look up -@code{describe-function} using the @kbd{C-h f} command! - -In this instance, since the code is Lisp, the @file{*Help*} buffer -contains the name of the library containing the function's source. -You can put point over the name of the library and press the RET key, -which in this situation is bound to @code{help-follow}, and be taken -directly to the source, in the same way as @kbd{M-.} -(@code{find-tag}). - -The definition for @code{describe-function} illustrates how to -customize the @code{interactive} expression without using the standard -character codes; and it shows how to create a temporary buffer. - -(The @code{indent-to} function is written in C rather than Emacs Lisp; -it is a `built-in' function. @code{help-follow} takes you to its -source as does @code{find-tag}, when properly set up.) - -You can look at a function's source using @code{find-tag}, which is -bound to @kbd{M-.} Finally, you can find out what the Reference -Manual has to say by visiting the manual in Info, and typing @kbd{i} -(@code{Info-index}) and the name of the function, or by looking up the -function in the index to a printed copy of the manual. - -Similarly, you can find out what is meant by -@code{insert-and-inherit}. - -Other interesting source files include @file{paragraphs.el}, -@file{loaddefs.el}, and @file{loadup.el}. The @file{paragraphs.el} -file includes short, easily understood functions as well as longer -ones. The @file{loaddefs.el} file contains the many standard -autoloads and many keymaps. I have never looked at it all; only at -parts. @file{loadup.el} is the file that loads the standard parts of -Emacs; it tells you a great deal about how Emacs is built. -(@xref{Building Emacs, , Building Emacs, elisp, The GNU Emacs Lisp -Reference Manual}, for more about building.) - -As I said, you have learned some nuts and bolts; however, and very -importantly, we have hardly touched major aspects of programming; I -have said nothing about how to sort information, except to use the -predefined @code{sort} function; I have said nothing about how to store -information, except to use variables and lists; I have said nothing -about how to write programs that write programs. These are topics for -another, and different kind of book, a different kind of learning. - -What you have done is learn enough for much practical work with GNU -Emacs. What you have done is get started. This is the end of a -beginning. - -@c ================ Appendix ================ - -@node the-the, Kill Ring, Conclusion, Top -@appendix The @code{the-the} Function -@findex the-the -@cindex Duplicated words function -@cindex Words, duplicated - -Sometimes when you you write text, you duplicate words---as with ``you -you'' near the beginning of this sentence. I find that most -frequently, I duplicate ``the''; hence, I call the function for -detecting duplicated words, @code{the-the}. - -@need 1250 -As a first step, you could use the following regular expression to -search for duplicates: - -@smallexample -\\(\\w+[ \t\n]+\\)\\1 -@end smallexample - -@noindent -This regexp matches one or more word-constituent characters followed -by one or more spaces, tabs, or newlines. However, it does not detect -duplicated words on different lines, since the ending of the first -word, the end of the line, is different from the ending of the second -word, a space. (For more information about regular expressions, see -@ref{Regexp Search, , Regular Expression Searches}, as well as -@ref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs -Manual}, and @ref{Regular Expressions, , Regular Expressions, elisp, -The GNU Emacs Lisp Reference Manual}.) - -You might try searching just for duplicated word-constituent -characters but that does not work since the pattern detects doubles -such as the two occurrences of `th' in `with the'. - -Another possible regexp searches for word-constituent characters -followed by non-word-constituent characters, reduplicated. Here, -@w{@samp{\\w+}} matches one or more word-constituent characters and -@w{@samp{\\W*}} matches zero or more non-word-constituent characters. - -@smallexample -\\(\\(\\w+\\)\\W*\\)\\1 -@end smallexample - -@noindent -Again, not useful. - -Here is the pattern that I use. It is not perfect, but good enough. -@w{@samp{\\b}} matches the empty string, provided it is at the beginning -or end of a word; @w{@samp{[^@@ \n\t]+}} matches one or more occurrences of -any characters that are @emph{not} an @@-sign, space, newline, or tab. - -@smallexample -\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b -@end smallexample - -One can write more complicated expressions, but I found that this -expression is good enough, so I use it. - -Here is the @code{the-the} function, as I include it in my -@file{.emacs} file, along with a handy global key binding: - -@smallexample -@group -(defun the-the () - "Search forward for for a duplicated word." - (interactive) - (message "Searching for for duplicated words ...") - (push-mark) -@end group -@group - ;; This regexp is not perfect - ;; but is fairly good over all: - (if (re-search-forward - "\\b\\([^@@ \n\t]+\\)[ \n\t]+\\1\\b" nil 'move) - (message "Found duplicated word.") - (message "End of buffer"))) -@end group - -@group -;; Bind `the-the' to C-c \ -(global-set-key "\C-c\\" 'the-the) -@end group -@end smallexample - -@sp 1 -Here is test text: - -@smallexample -@group -one two two three four five -five six seven -@end group -@end smallexample - -You can substitute the other regular expressions shown above in the -function definition and try each of them on this list. - -@node Kill Ring, Full Graph, the-the, Top -@appendix Handling the Kill Ring -@cindex Kill ring handling -@cindex Handling the kill ring -@cindex Ring, making a list like a - -The kill ring is a list that is transformed into a ring by the -workings of the @code{current-kill} function. The @code{yank} and -@code{yank-pop} commands use the @code{current-kill} function. - -This appendix describes the @code{current-kill} function as well as -both the @code{yank} and the @code{yank-pop} commands, but first, -consider the workings of the kill ring. - -@menu -* What the Kill Ring Does:: -* current-kill:: -* yank:: Paste a copy of a clipped element. -* yank-pop:: Insert element pointed to. -* ring file:: -@end menu - -@node What the Kill Ring Does, current-kill, Kill Ring, Kill Ring -@ifnottex -@unnumberedsec What the Kill Ring Does -@end ifnottex - -@need 1250 -The kill ring has a default maximum length of sixty items; this number -is too large for an explanation. Instead, set it to four. Please -evaluate the following: - -@smallexample -@group -(setq old-kill-ring-max kill-ring-max) -(setq kill-ring-max 4) -@end group -@end smallexample - -@noindent -Then, please copy each line of the following indented example into the -kill ring. You may kill each line with @kbd{C-k} or mark it and copy -it with @kbd{M-w}. - -@noindent -(In a read-only buffer, such as the @file{*info*} buffer, the kill -command, @kbd{C-k} (@code{kill-line}), will not remove the text, -merely copy it to the kill ring. However, your machine may beep at -you. Alternatively, for silence, you may copy the region of each line -with the @kbd{M-w} (@code{kill-ring-save}) command. You must mark -each line for this command to succeed, but it does not matter at which -end you put point or mark.) - -@need 1250 -@noindent -Please invoke the calls in order, so that five elements attempt to -fill the kill ring: - -@smallexample -@group -first some text -second piece of text -third line -fourth line of text -fifth bit of text -@end group -@end smallexample - -@need 1250 -@noindent -Then find the value of @code{kill-ring} by evaluating - -@smallexample -kill-ring -@end smallexample - -@need 800 -@noindent -It is: - -@smallexample -@group -("fifth bit of text" "fourth line of text" -"third line" "second piece of text") -@end group -@end smallexample - -@noindent -The first element, @samp{first some text}, was dropped. - -@need 1250 -To return to the old value for the length of the kill ring, evaluate: - -@smallexample -(setq kill-ring-max old-kill-ring-max) -@end smallexample - -@node current-kill, yank, What the Kill Ring Does, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @code{current-kill} Function -@findex current-kill - -The @code{current-kill} function changes the element in the kill ring -to which @code{kill-ring-yank-pointer} points. (Also, the -@code{kill-new} function sets @code{kill-ring-yank-pointer} to point -to the latest element of the kill ring. The @code{kill-new} -function is used directly or indirectly by @code{kill-append}, -@code{copy-region-as-kill}, @code{kill-ring-save}, @code{kill-line}, -and @code{kill-region}.) - -@menu -* Code for current-kill:: -* Understanding current-kill:: -@end menu - -@node Code for current-kill, Understanding current-kill, current-kill, current-kill -@ifnottex -@unnumberedsubsec The code for @code{current-kill} -@end ifnottex - - -@need 1500 -The @code{current-kill} function is used by @code{yank} and by -@code{yank-pop}. Here is the code for @code{current-kill}: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill. -If N is zero, `interprogram-paste-function' is set, and calling it -returns a string, then that string is added to the front of the -kill ring and returned as the latest kill. -@end group -@group -If optional arg DO-NOT-MOVE is non-nil, then don't actually move the -yanking point; just return the Nth kill forward." - (let ((interprogram-paste (and (= n 0) - interprogram-paste-function - (funcall interprogram-paste-function)))) -@end group -@group - (if interprogram-paste - (progn - ;; Disable the interprogram cut function when we add the new - ;; text to the kill ring, so Emacs doesn't try to own the - ;; selection, with identical text. - (let ((interprogram-cut-function nil)) - (kill-new interprogram-paste)) - interprogram-paste) -@end group -@group - (or kill-ring (error "Kill ring is empty")) - (let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element))))) -@end group -@end smallexample - -Remember also that the @code{kill-new} function sets -@code{kill-ring-yank-pointer} to the latest element of the kill -ring, which means that all the functions that call it set the value -indirectly: @code{kill-append}, @code{copy-region-as-kill}, -@code{kill-ring-save}, @code{kill-line}, and @code{kill-region}. - -@need 1500 -Here is the line in @code{kill-new}, which is explained in -@ref{kill-new function, , The @code{kill-new} function}. - -@smallexample -(setq kill-ring-yank-pointer kill-ring) -@end smallexample - -@node Understanding current-kill, , Code for current-kill, current-kill -@ifnottex -@unnumberedsubsec @code{current-kill} in Outline -@end ifnottex - -The @code{current-kill} function looks complex, but as usual, it can -be understood by taking it apart piece by piece. First look at it in -skeletal form: - -@smallexample -@group -(defun current-kill (n &optional do-not-move) - "Rotate the yanking point by N places, and then return that kill." - (let @var{varlist} - @var{body}@dots{}) -@end group -@end smallexample - -This function takes two arguments, one of which is optional. It has a -documentation string. It is @emph{not} interactive. - -@menu -* Body of current-kill:: -* Digression concerning error:: How to mislead humans, but not computers. -* Determining the Element:: -@end menu - -@node Body of current-kill, Digression concerning error, Understanding current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec The Body of @code{current-kill} -@end ifnottex - -The body of the function definition is a @code{let} expression, which -itself has a body as well as a @var{varlist}. - -The @code{let} expression declares a variable that will be only usable -within the bounds of this function. This variable is called -@code{interprogram-paste} and is for copying to another program. It -is not for copying within this instance of GNU Emacs. Most window -systems provide a facility for interprogram pasting. Sadly, that -facility usually provides only for the last element. Most windowing -systems have not adopted a ring of many possibilities, even though -Emacs has provided it for decades. - -The @code{if} expression has two parts, one if there exists -@code{interprogram-paste} and one if not. - -@need 2000 -Let us consider the `if not' or else-part of the @code{current-kill} -function. (The then-part uses the @code{kill-new} function, which -we have already described. @xref{kill-new function, , The -@code{kill-new} function}.) - -@smallexample -@group -(or kill-ring (error "Kill ring is empty")) -(let ((ARGth-kill-element - (nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) - (or do-not-move - (setq kill-ring-yank-pointer ARGth-kill-element)) - (car ARGth-kill-element)) -@end group -@end smallexample - -@noindent -The code first checks whether the kill ring has content; otherwise it -signals an error. - -@need 1000 -Note that the @code{or} expression is very similar to testing length -with an @code{if}: - -@findex zerop -@findex error -@smallexample -@group -(if (zerop (length kill-ring)) ; @r{if-part} - (error "Kill ring is empty")) ; @r{then-part} - ;; No else-part -@end group -@end smallexample - -@noindent -If there is not anything in the kill ring, its length must be zero and -an error message sent to the user: @samp{Kill ring is empty}. The -@code{current-kill} function uses an @code{or} expression which is -simpler. But an @code{if} expression reminds us what goes on. - -This @code{if} expression uses the function @code{zerop} which returns -true if the value it is testing is zero. When @code{zerop} tests -true, the then-part of the @code{if} is evaluated. The then-part is a -list starting with the function @code{error}, which is a function that -is similar to the @code{message} function -(@pxref{message, , The @code{message} Function}) in that -it prints a one-line message in the echo area. However, in addition -to printing a message, @code{error} also stops evaluation of the -function within which it is embedded. This means that the rest of the -function will not be evaluated if the length of the kill ring is zero. - -Then the @code{current-kill} function selects the element to return. -The selection depends on the number of places that @code{current-kill} -rotates and on where @code{kill-ring-yank-pointer} points. - -Next, either the optional @code{do-not-move} argument is true or the -current value of @code{kill-ring-yank-pointer} is set to point to the -list. Finally, another expression returns the first element of the -list even if the @code{do-not-move} argument is true. - -@node Digression concerning error, Determining the Element, Body of current-kill, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Digression about the word `error' -@end ifnottex - -In my opinion, it is slightly misleading, at least to humans, to use -the term `error' as the name of the @code{error} function. A better -term would be `cancel'. Strictly speaking, of course, you cannot -point to, much less rotate a pointer to a list that has no length, so -from the point of view of the computer, the word `error' is correct. -But a human expects to attempt this sort of thing, if only to find out -whether the kill ring is full or empty. This is an act of -exploration. - -From the human point of view, the act of exploration and discovery is -not necessarily an error, and therefore should not be labelled as one, -even in the bowels of a computer. As it is, the code in Emacs implies -that a human who is acting virtuously, by exploring his or her -environment, is making an error. This is bad. Even though the computer -takes the same steps as it does when there is an `error', a term such as -`cancel' would have a clearer connotation. - -@node Determining the Element, , Digression concerning error, Understanding current-kill -@ifnottex -@unnumberedsubsubsec Determining the Element -@end ifnottex - -Among other actions, the else-part of the @code{if} expression sets -the value of @code{kill-ring-yank-pointer} to -@code{ARGth-kill-element} when the kill ring has something in it and -the value of @code{do-not-move} is @code{nil}. - -@need 800 -The code looks like this: - -@smallexample -@group -(nthcdr (mod (- n (length kill-ring-yank-pointer)) - (length kill-ring)) - kill-ring))) -@end group -@end smallexample - -This needs some examination. Unless it is not supposed to move the -pointer, the @code{current-kill} function changes where -@code{kill-ring-yank-pointer} points. -That is what the -@w{@code{(setq kill-ring-yank-pointer ARGth-kill-element))}} -expression does. Also, clearly, @code{ARGth-kill-element} is being -set to be equal to some @sc{cdr} of the kill ring, using the -@code{nthcdr} function that is described in an earlier section. -(@xref{copy-region-as-kill}.) How does it do this? - -As we have seen before (@pxref{nthcdr}), the @code{nthcdr} function -works by repeatedly taking the @sc{cdr} of a list---it takes the -@sc{cdr} of the @sc{cdr} of the @sc{cdr} @dots{} - -@need 800 -The two following expressions produce the same result: - -@smallexample -@group -(setq kill-ring-yank-pointer (cdr kill-ring)) - -(setq kill-ring-yank-pointer (nthcdr 1 kill-ring)) -@end group -@end smallexample - -However, the @code{nthcdr} expression is more complicated. It uses -the @code{mod} function to determine which @sc{cdr} to select. - -(You will remember to look at inner functions first; indeed, we will -have to go inside the @code{mod}.) - -The @code{mod} function returns the value of its first argument modulo -the second; that is to say, it returns the remainder after dividing -the first argument by the second. The value returned has the same -sign as the second argument. - -@need 800 -Thus, - -@smallexample -@group -(mod 12 4) - @result{} 0 ;; @r{because there is no remainder} -(mod 13 4) - @result{} 1 -@end group -@end smallexample - -@need 1250 -In this case, the first argument is often smaller than the second. -That is fine. - -@smallexample -@group -(mod 0 4) - @result{} 0 -(mod 1 4) - @result{} 1 -@end group -@end smallexample - -We can guess what the @code{-} function does. It is like @code{+} but -subtracts instead of adds; the @code{-} function subtracts its second -argument from its first. Also, we already know what the @code{length} -function does (@pxref{length}). It returns the length of a list. - -And @code{n} is the name of the required argument to the -@code{current-kill} function. - -@need 1250 -So when the first argument to @code{nthcdr} is zero, the @code{nthcdr} -expression returns the whole list, as you can see by evaluating the -following: - -@smallexample -@group -;; kill-ring-yank-pointer @r{and} kill-ring @r{have a length of four} -;; @r{and} (mod (- 0 4) 4) @result{} 0 -(nthcdr (mod (- 0 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@need 1250 -When the first argument to the @code{current-kill} function is one, -the @code{nthcdr} expression returns the list without its first -element. - -@smallexample -@group -(nthcdr (mod (- 1 4) 4) - '("fourth line of text" - "third line" - "second piece of text" - "first some text")) -@end group -@end smallexample - -@cindex @samp{global variable} defined -@cindex @samp{variable, global}, defined -Incidentally, both @code{kill-ring} and @code{kill-ring-yank-pointer} -are @dfn{global variables}. That means that any expression in Emacs -Lisp can access them. They are not like the local variables set by -@code{let} or like the symbols in an argument list. -Local variables can only be accessed -within the @code{let} that defines them or the function that specifies -them in an argument list (and within expressions called by them). - -@ignore -@c texi2dvi fails when the name of the section is within ifnottex ... -(@xref{Prevent confusion, , @code{let} Prevents Confusion}, and -@ref{defun, , The @code{defun} Special Form}.) -@end ignore - -@node yank, yank-pop, current-kill, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank} -@findex yank - -After learning about @code{current-kill}, the code for the -@code{yank} function is almost easy. - -The @code{yank} function does not use the -@code{kill-ring-yank-pointer} variable directly. It calls -@code{insert-for-yank} which calls @code{current-kill} which sets the -@code{kill-ring-yank-pointer} variable. - -@need 1250 -The code looks like this: - -@c in GNU Emacs 22 -@smallexample -@group -(defun yank (&optional arg) - "Reinsert (\"paste\") the last stretch of killed text. -More precisely, reinsert the stretch of killed text most recently -killed OR yanked. Put point at end, and set mark at beginning. -With just \\[universal-argument] as argument, same but put point at -beginning (and mark at end). With argument N, reinsert the Nth most -recently killed stretch of killed text. - -When this command inserts killed text into the buffer, it honors -`yank-excluded-properties' and `yank-handler' as described in the -doc string for `insert-for-yank-1', which see. - -See also the command \\[yank-pop]." -@end group -@group - (interactive "*P") - (setq yank-window-start (window-start)) - ;; If we don't get all the way thru, make last-command indicate that - ;; for the following command. - (setq this-command t) - (push-mark (point)) -@end group -@group - (insert-for-yank (current-kill (cond - ((listp arg) 0) - ((eq arg '-) -2) - (t (1- arg))))) - (if (consp arg) - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) (point) (current-buffer))))) -@end group -@group - ;; If we do get all the way thru, make this-command indicate that. - (if (eq this-command t) - (setq this-command 'yank)) - nil) -@end group -@end smallexample - -The key expression is @code{insert-for-yank}, which inserts the string -returned by @code{current-kill}, but removes some text properties from -it. - -However, before getting to that expression, the function sets the value -of @code{yank-window-start} to the position returned by the -@code{(window-start)} expression, the position at which the display -currently starts. The @code{yank} function also sets -@code{this-command} and pushes the mark. - -After it yanks the appropriate element, if the optional argument is a -@sc{cons} rather than a number or nothing, it puts point at beginning -of the yanked text and mark at its end. - -(The @code{prog1} function is like @code{progn} but returns the value -of its first argument rather than the value of its last argument. Its -first argument is forced to return the buffer's mark as an integer. -You can see the documentation for these functions by placing point -over them in this buffer and then typing @kbd{C-h f} -(@code{describe-function}) followed by a @kbd{RET}; the default is the -function.) - -The last part of the function tells what to do when it succeeds. - -@node yank-pop, ring file, yank, Kill Ring -@comment node-name, next, previous, up -@appendixsec @code{yank-pop} -@findex yank-pop - -After understanding @code{yank} and @code{current-kill}, you know how -to approach the @code{yank-pop} function. Leaving out the -documentation to save space, it looks like this: - -@c GNU Emacs 22 -@smallexample -@group -(defun yank-pop (&optional arg) - "@dots{}" - (interactive "*p") - (if (not (eq last-command 'yank)) - (error "Previous command was not a yank")) -@end group -@group - (setq this-command 'yank) - (unless arg (setq arg 1)) - (let ((inhibit-read-only t) - (before (< (point) (mark t)))) -@end group -@group - (if before - (funcall (or yank-undo-function 'delete-region) (point) (mark t)) - (funcall (or yank-undo-function 'delete-region) (mark t) (point))) - (setq yank-undo-function nil) -@end group -@group - (set-marker (mark-marker) (point) (current-buffer)) - (insert-for-yank (current-kill arg)) - ;; Set the window start back where it was in the yank command, - ;; if possible. - (set-window-start (selected-window) yank-window-start t) -@end group -@group - (if before - ;; This is like exchange-point-and-mark, - ;; but doesn't activate the mark. - ;; It is cleaner to avoid activation, even though the command - ;; loop would deactivate the mark because we inserted text. - (goto-char (prog1 (mark t) - (set-marker (mark-marker) - (point) - (current-buffer)))))) - nil) -@end group -@end smallexample - -The function is interactive with a small @samp{p} so the prefix -argument is processed and passed to the function. The command can -only be used after a previous yank; otherwise an error message is -sent. This check uses the variable @code{last-command} which is set -by @code{yank} and is discussed elsewhere. -(@xref{copy-region-as-kill}.) - -The @code{let} clause sets the variable @code{before} to true or false -depending whether point is before or after mark and then the region -between point and mark is deleted. This is the region that was just -inserted by the previous yank and it is this text that will be -replaced. - -@code{funcall} calls its first argument as a function, passing -remaining arguments to it. The first argument is whatever the -@code{or} expression returns. The two remaining arguments are the -positions of point and mark set by the preceding @code{yank} command. - -There is more, but that is the hardest part. - -@node ring file, , yank-pop, Kill Ring -@comment node-name, next, previous, up -@appendixsec The @file{ring.el} File -@cindex @file{ring.el} file - -Interestingly, GNU Emacs posses a file called @file{ring.el} that -provides many of the features we just discussed. But functions such -as @code{kill-ring-yank-pointer} do not use this library, possibly -because they were written earlier. - -@node Full Graph, Free Software and Free Manuals, Kill Ring, Top -@appendix A Graph with Labelled Axes - -Printed axes help you understand a graph. They convey scale. In an -earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we -wrote the code to print the body of a graph. Here we write the code -for printing and labelling vertical and horizontal axes, along with the -body itself. - -@menu -* Labelled Example:: -* print-graph Varlist:: @code{let} expression in @code{print-graph}. -* print-Y-axis:: Print a label for the vertical axis. -* print-X-axis:: Print a horizontal label. -* Print Whole Graph:: The function to print a complete graph. -@end menu - -@node Labelled Example, print-graph Varlist, Full Graph, Full Graph -@ifnottex -@unnumberedsec Labelled Example Graph -@end ifnottex - -Since insertions fill a buffer to the right and below point, the new -graph printing function should first print the Y or vertical axis, -then the body of the graph, and finally the X or horizontal axis. -This sequence lays out for us the contents of the function: - -@enumerate -@item -Set up code. - -@item -Print Y axis. - -@item -Print body of graph. - -@item -Print X axis. -@end enumerate - -@need 800 -Here is an example of how a finished graph should look: - -@smallexample -@group - 10 - - * - * * - * ** - * *** - 5 - * ******* - * *** ******* - ************* - *************** - 1 - **************** - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -In this graph, both the vertical and the horizontal axes are labelled -with numbers. However, in some graphs, the horizontal axis is time -and would be better labelled with months, like this: - -@smallexample -@group - 5 - * - * ** * - ******* - ********** ** - 1 - ************** - | ^ | - Jan June Jan -@end group -@end smallexample - -Indeed, with a little thought, we can easily come up with a variety of -vertical and horizontal labelling schemes. Our task could become -complicated. But complications breed confusion. Rather than permit -this, it is better choose a simple labelling scheme for our first -effort, and to modify or replace it later. - -@need 1200 -These considerations suggest the following outline for the -@code{print-graph} function: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -We can work on each part of the @code{print-graph} function definition -in turn. - -@node print-graph Varlist, print-Y-axis, Labelled Example, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-graph} Varlist -@cindex @code{print-graph} varlist - -In writing the @code{print-graph} function, the first task is to write -the varlist in the @code{let} expression. (We will leave aside for the -moment any thoughts about making the function interactive or about the -contents of its documentation string.) - -The varlist should set several values. Clearly, the top of the label -for the vertical axis must be at least the height of the graph, which -means that we must obtain this information here. Note that the -@code{print-graph-body} function also requires this information. There -is no reason to calculate the height of the graph in two different -places, so we should change @code{print-graph-body} from the way we -defined it earlier to take advantage of the calculation. - -Similarly, both the function for printing the X axis labels and the -@code{print-graph-body} function need to learn the value of the width of -each symbol. We can perform the calculation here and change the -definition for @code{print-graph-body} from the way we defined it in the -previous chapter. - -The length of the label for the horizontal axis must be at least as long -as the graph. However, this information is used only in the function -that prints the horizontal axis, so it does not need to be calculated here. - -These thoughts lead us directly to the following form for the varlist -in the @code{let} for @code{print-graph}: - -@smallexample -@group -(let ((height (apply 'max numbers-list)) ; @r{First version.} - (symbol-width (length graph-blank))) -@end group -@end smallexample - -@noindent -As we shall see, this expression is not quite right. - -@need 2000 -@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph -@comment node-name, next, previous, up -@appendixsec The @code{print-Y-axis} Function -@cindex Axis, print vertical -@cindex Y axis printing -@cindex Vertical axis printing -@cindex Print vertical axis - -The job of the @code{print-Y-axis} function is to print a label for -the vertical axis that looks like this: - -@smallexample -@group - 10 - - - - - - 5 - - - - - 1 - -@end group -@end smallexample - -@noindent -The function should be passed the height of the graph, and then should -construct and insert the appropriate numbers and marks. - -@menu -* print-Y-axis in Detail:: -* Height of label:: What height for the Y axis? -* Compute a Remainder:: How to compute the remainder of a division. -* Y Axis Element:: Construct a line for the Y axis. -* Y-axis-column:: Generate a list of Y axis labels. -* print-Y-axis Penultimate:: A not quite final version. -@end menu - -@node print-Y-axis in Detail, Height of label, print-Y-axis, print-Y-axis -@ifnottex -@unnumberedsubsec The @code{print-Y-axis} Function in Detail -@end ifnottex - -It is easy enough to see in the figure what the Y axis label should -look like; but to say in words, and then to write a function -definition to do the job is another matter. It is not quite true to -say that we want a number and a tic every five lines: there are only -three lines between the @samp{1} and the @samp{5} (lines 2, 3, and 4), -but four lines between the @samp{5} and the @samp{10} (lines 6, 7, 8, -and 9). It is better to say that we want a number and a tic mark on -the base line (number 1) and then that we want a number and a tic on -the fifth line from the bottom and on every line that is a multiple of -five. - -@node Height of label, Compute a Remainder, print-Y-axis in Detail, print-Y-axis -@ifnottex -@unnumberedsubsec What height should the label be? -@end ifnottex - -The next issue is what height the label should be? Suppose the maximum -height of tallest column of the graph is seven. Should the highest -label on the Y axis be @samp{5 -}, and should the graph stick up above -the label? Or should the highest label be @samp{7 -}, and mark the peak -of the graph? Or should the highest label be @code{10 -}, which is a -multiple of five, and be higher than the topmost value of the graph? - -The latter form is preferred. Most graphs are drawn within rectangles -whose sides are an integral number of steps long---5, 10, 15, and so -on for a step distance of five. But as soon as we decide to use a -step height for the vertical axis, we discover that the simple -expression in the varlist for computing the height is wrong. The -expression is @code{(apply 'max numbers-list)}. This returns the -precise height, not the maximum height plus whatever is necessary to -round up to the nearest multiple of five. A more complex expression -is required. - -As usual in cases like this, a complex problem becomes simpler if it is -divided into several smaller problems. - -First, consider the case when the highest value of the graph is an -integral multiple of five---when it is 5, 10, 15, or some higher -multiple of five. We can use this value as the Y axis height. - -A fairly simply way to determine whether a number is a multiple of -five is to divide it by five and see if the division results in a -remainder. If there is no remainder, the number is a multiple of -five. Thus, seven divided by five has a remainder of two, and seven -is not an integral multiple of five. Put in slightly different -language, more reminiscent of the classroom, five goes into seven -once, with a remainder of two. However, five goes into ten twice, -with no remainder: ten is an integral multiple of five. - -@node Compute a Remainder, Y Axis Element, Height of label, print-Y-axis -@appendixsubsec Side Trip: Compute a Remainder - -@findex % @r{(remainder function)} -@cindex Remainder function, @code{%} -In Lisp, the function for computing a remainder is @code{%}. The -function returns the remainder of its first argument divided by its -second argument. As it happens, @code{%} is a function in Emacs Lisp -that you cannot discover using @code{apropos}: you find nothing if you -type @kbd{M-x apropos @key{RET} remainder @key{RET}}. The only way to -learn of the existence of @code{%} is to read about it in a book such -as this or in the Emacs Lisp sources. - -You can try the @code{%} function by evaluating the following two -expressions: - -@smallexample -@group -(% 7 5) - -(% 10 5) -@end group -@end smallexample - -@noindent -The first expression returns 2 and the second expression returns 0. - -To test whether the returned value is zero or some other number, we -can use the @code{zerop} function. This function returns @code{t} if -its argument, which must be a number, is zero. - -@smallexample -@group -(zerop (% 7 5)) - @result{} nil - -(zerop (% 10 5)) - @result{} t -@end group -@end smallexample - -Thus, the following expression will return @code{t} if the height -of the graph is evenly divisible by five: - -@smallexample -(zerop (% height 5)) -@end smallexample - -@noindent -(The value of @code{height}, of course, can be found from @code{(apply -'max numbers-list)}.) - -On the other hand, if the value of @code{height} is not a multiple of -five, we want to reset the value to the next higher multiple of five. -This is straightforward arithmetic using functions with which we are -already familiar. First, we divide the value of @code{height} by five -to determine how many times five goes into the number. Thus, five -goes into twelve twice. If we add one to this quotient and multiply by -five, we will obtain the value of the next multiple of five that is -larger than the height. Five goes into twelve twice. Add one to two, -and multiply by five; the result is fifteen, which is the next multiple -of five that is higher than twelve. The Lisp expression for this is: - -@smallexample -(* (1+ (/ height 5)) 5) -@end smallexample - -@noindent -For example, if you evaluate the following, the result is 15: - -@smallexample -(* (1+ (/ 12 5)) 5) -@end smallexample - -All through this discussion, we have been using `five' as the value -for spacing labels on the Y axis; but we may want to use some other -value. For generality, we should replace `five' with a variable to -which we can assign a value. The best name I can think of for this -variable is @code{Y-axis-label-spacing}. - -@need 1250 -Using this term, and an @code{if} expression, we produce the -following: - -@smallexample -@group -(if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing)) -@end group -@end smallexample - -@noindent -This expression returns the value of @code{height} itself if the height -is an even multiple of the value of the @code{Y-axis-label-spacing} or -else it computes and returns a value of @code{height} that is equal to -the next higher multiple of the value of the @code{Y-axis-label-spacing}. - -We can now include this expression in the @code{let} expression of the -@code{print-graph} function (after first setting the value of -@code{Y-axis-label-spacing}): -@vindex Y-axis-label-spacing - -@smallexample -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -@dots{} -(let* ((height (apply 'max numbers-list)) - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height -@end group -@group - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) - (symbol-width (length graph-blank)))) -@dots{} -@end group -@end smallexample - -@noindent -(Note use of the @code{let*} function: the initial value of height is -computed once by the @code{(apply 'max numbers-list)} expression and -then the resulting value of @code{height} is used to compute its -final value. @xref{fwd-para let, , The @code{let*} expression}, for -more about @code{let*}.) - -@node Y Axis Element, Y-axis-column, Compute a Remainder, print-Y-axis -@appendixsubsec Construct a Y Axis Element - -When we print the vertical axis, we want to insert strings such as -@w{@samp{5 -}} and @w{@samp{10 - }} every five lines. -Moreover, we want the numbers and dashes to line up, so shorter -numbers must be padded with leading spaces. If some of the strings -use two digit numbers, the strings with single digit numbers must -include a leading blank space before the number. - -@findex number-to-string -To figure out the length of the number, the @code{length} function is -used. But the @code{length} function works only with a string, not with -a number. So the number has to be converted from being a number to -being a string. This is done with the @code{number-to-string} function. -For example, - -@smallexample -@group -(length (number-to-string 35)) - @result{} 2 - -(length (number-to-string 100)) - @result{} 3 -@end group -@end smallexample - -@noindent -(@code{number-to-string} is also called @code{int-to-string}; you will -see this alternative name in various sources.) - -In addition, in each label, each number is followed by a string such -as @w{@samp{ - }}, which we will call the @code{Y-axis-tic} marker. -This variable is defined with @code{defvar}: - -@vindex Y-axis-tic -@smallexample -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group -@end smallexample - -The length of the Y label is the sum of the length of the Y axis tic -mark and the length of the number of the top of the graph. - -@smallexample -(length (concat (number-to-string height) Y-axis-tic))) -@end smallexample - -This value will be calculated by the @code{print-graph} function in -its varlist as @code{full-Y-label-width} and passed on. (Note that we -did not think to include this in the varlist when we first proposed it.) - -To make a complete vertical axis label, a tic mark is concatenated -with a number; and the two together may be preceded by one or more -spaces depending on how long the number is. The label consists of -three parts: the (optional) leading spaces, the number, and the tic -mark. The function is passed the value of the number for the specific -row, and the value of the width of the top line, which is calculated -(just once) by @code{print-graph}. - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -The @code{Y-axis-element} function concatenates together the leading -spaces, if any; the number, as a string; and the tic mark. - -To figure out how many leading spaces the label will need, the -function subtracts the actual length of the label---the length of the -number plus the length of the tic mark---from the desired label width. - -@findex make-string -Blank spaces are inserted using the @code{make-string} function. This -function takes two arguments: the first tells it how long the string -will be and the second is a symbol for the character to insert, in a -special format. The format is a question mark followed by a blank -space, like this, @samp{? }. @xref{Character Type, , Character Type, -elisp, The GNU Emacs Lisp Reference Manual}, for a description of the -syntax for characters. (Of course, you might want to replace the -blank space by some other character @dots{} You know what to do.) - -The @code{number-to-string} function is used in the concatenation -expression, to convert the number to a string that is concatenated -with the leading spaces and the tic mark. - -@node Y-axis-column, print-Y-axis Penultimate, Y Axis Element, print-Y-axis -@appendixsubsec Create a Y Axis Column - -The preceding functions provide all the tools needed to construct a -function that generates a list of numbered and blank strings to insert -as the label for the vertical axis: - -@findex Y-axis-column -@smallexample -@group -(defun Y-axis-column (height width-of-label) - "Construct list of Y axis labels and blank strings. -For HEIGHT of line above base and WIDTH-OF-LABEL." - (let (Y-axis) -@group -@end group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element height width-of-label) - Y-axis)) -@group -@end group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) - ;; @r{Insert base line.} - (setq Y-axis - (cons (Y-axis-element 1 width-of-label) Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -In this function, we start with the value of @code{height} and -repetitively subtract one from its value. After each subtraction, we -test to see whether the value is an integral multiple of the -@code{Y-axis-label-spacing}. If it is, we construct a numbered label -using the @code{Y-axis-element} function; if not, we construct a -blank label using the @code{make-string} function. The base line -consists of the number one followed by a tic mark. - -@need 2000 -@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis -@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} - -The list constructed by the @code{Y-axis-column} function is passed to -the @code{print-Y-axis} function, which inserts the list as a column. - -@findex print-Y-axis -@smallexample -@group -(defun print-Y-axis (height full-Y-label-width) - "Insert Y axis using HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element." -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. -@end group -@group - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width)) - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -The @code{print-Y-axis} uses the @code{insert-rectangle} function to -insert the Y axis labels created by the @code{Y-axis-column} function. -In addition, it places point at the correct position for printing the body of -the graph. - -You can test @code{print-Y-axis}: - -@enumerate -@item -Install - -@smallexample -@group -Y-axis-label-spacing -Y-axis-tic -Y-axis-element -Y-axis-column -print-Y-axis -@end group -@end smallexample - -@item -Copy the following expression: - -@smallexample -(print-Y-axis 12 5) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the @code{graph-body-print} expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -Emacs will print labels vertically, the top one being @w{@samp{10 -@w{ -}}}. (The @code{print-graph} function will pass the value of -@code{height-of-top-line}, which in this case will end up as 15, -thereby getting rid of what might appear as a bug.) - -@need 2000 -@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph -@appendixsec The @code{print-X-axis} Function -@cindex Axis, print horizontal -@cindex X axis printing -@cindex Print horizontal axis -@cindex Horizontal axis printing - -X axis labels are much like Y axis labels, except that the ticks are on a -line above the numbers. Labels should look like this: - -@smallexample -@group - | | | | - 1 5 10 15 -@end group -@end smallexample - -The first tic is under the first column of the graph and is preceded by -several blank spaces. These spaces provide room in rows above for the Y -axis labels. The second, third, fourth, and subsequent ticks are all -spaced equally, according to the value of @code{X-axis-label-spacing}. - -The second row of the X axis consists of numbers, preceded by several -blank spaces and also separated according to the value of the variable -@code{X-axis-label-spacing}. - -The value of the variable @code{X-axis-label-spacing} should itself be -measured in units of @code{symbol-width}, since you may want to change -the width of the symbols that you are using to print the body of the -graph without changing the ways the graph is labelled. - -@menu -* Similarities differences:: Much like @code{print-Y-axis}, but not exactly. -* X Axis Tic Marks:: Create tic marks for the horizontal axis. -@end menu - -@node Similarities differences, X Axis Tic Marks, print-X-axis, print-X-axis -@ifnottex -@unnumberedsubsec Similarities and differences -@end ifnottex - -The @code{print-X-axis} function is constructed in more or less the -same fashion as the @code{print-Y-axis} function except that it has -two lines: the line of tic marks and the numbers. We will write a -separate function to print each line and then combine them within the -@code{print-X-axis} function. - -This is a three step process: - -@enumerate -@item -Write a function to print the X axis tic marks, @code{print-X-axis-tic-line}. - -@item -Write a function to print the X numbers, @code{print-X-axis-numbered-line}. - -@item -Write a function to print both lines, the @code{print-X-axis} function, -using @code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. -@end enumerate - -@node X Axis Tic Marks, , Similarities differences, print-X-axis -@appendixsubsec X Axis Tic Marks - -The first function should print the X axis tic marks. We must specify -the tic marks themselves and their spacing: - -@smallexample -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@noindent -(Note that the value of @code{graph-blank} is set by another -@code{defvar}. The @code{boundp} predicate checks whether it has -already been set; @code{boundp} returns @code{nil} if it has not. If -@code{graph-blank} were unbound and we did not use this conditional -construction, in a recent GNU Emacs, we would enter the debugger and -see an error message saying @samp{@w{Debugger entered--Lisp error:} -@w{(void-variable graph-blank)}}.) - -@need 1200 -Here is the @code{defvar} for @code{X-axis-tic-symbol}: - -@smallexample -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group -@end smallexample - -@need 1250 -The goal is to make a line that looks like this: - -@smallexample - | | | | -@end smallexample - -The first tic is indented so that it is under the first column, which is -indented to provide space for the Y axis labels. - -A tic element consists of the blank spaces that stretch from one tic to -the next plus a tic symbol. The number of blanks is determined by the -width of the tic symbol and the @code{X-axis-label-spacing}. - -@need 1250 -The code looks like this: - -@smallexample -@group -;;; X-axis-tic-element -@dots{} -(concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol) -@dots{} -@end group -@end smallexample - -Next, we determine how many blanks are needed to indent the first tic -mark to the first column of the graph. This uses the value of -@code{full-Y-label-width} passed it by the @code{print-graph} function. - -@need 1250 -The code to make @code{X-axis-leading-spaces} -looks like this: - -@smallexample -@group -;; X-axis-leading-spaces -@dots{} -(make-string full-Y-label-width ? ) -@dots{} -@end group -@end smallexample - -We also need to determine the length of the horizontal axis, which is -the length of the numbers list, and the number of ticks in the horizontal -axis: - -@smallexample -@group -;; X-length -@dots{} -(length numbers-list) -@end group - -@group -;; tic-width -@dots{} -(* symbol-width X-axis-label-spacing) -@end group - -@group -;; number-of-X-ticks -(if (zerop (% (X-length tic-width))) - (/ (X-length tic-width)) - (1+ (/ (X-length tic-width)))) -@end group -@end smallexample - -@need 1250 -All this leads us directly to the function for printing the X axis tic line: - -@findex print-X-axis-tic-line -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -The line of numbers is equally straightforward: - -@need 1250 -First, we create a numbered element with blank spaces before each number: - -@findex X-axis-element -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -Next, we create the function to print the numbered line, starting with -the number ``1'' under the first column: - -@findex print-X-axis-numbered-line -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing)) - (insert X-axis-leading-spaces) - (insert "1") -@end group -@group - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) 2) - ? ) - (number-to-string number))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element number)) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -Finally, we need to write the @code{print-X-axis} that uses -@code{print-X-axis-tic-line} and -@code{print-X-axis-numbered-line}. - -The function must determine the local values of the variables used by both -@code{print-X-axis-tic-line} and @code{print-X-axis-numbered-line}, and -then it must call them. Also, it must print the carriage return that -separates the two lines. - -The function consists of a varlist that specifies five local variables, -and calls to each of the two line printing functions: - -@findex print-X-axis -@smallexample -@group -(defun print-X-axis (numbers-list) - "Print X axis labels to length of NUMBERS-LIST." - (let* ((leading-spaces - (make-string full-Y-label-width ? )) -@end group -@group - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string -@end group -@group - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) -@end group -@group - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group -@group - (print-X-axis-tic-line tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line tic-number leading-spaces))) -@end group -@end smallexample - -@need 1250 -You can test @code{print-X-axis}: - -@enumerate -@item -Install @code{X-axis-tic-symbol}, @code{X-axis-label-spacing}, -@code{print-X-axis-tic-line}, as well as @code{X-axis-element}, -@code{print-X-axis-numbered-line}, and @code{print-X-axis}. - -@item -Copy the following expression: - -@smallexample -@group -(progn - (let ((full-Y-label-width 5) - (symbol-width 1)) - (print-X-axis - '(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16)))) -@end group -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print the horizontal axis like this: -@sp 1 - -@smallexample -@group - | | | | | - 1 5 10 15 20 -@end group -@end smallexample - -@node Print Whole Graph, , print-X-axis, Full Graph -@appendixsec Printing the Whole Graph -@cindex Printing the whole graph -@cindex Whole graph printing -@cindex Graph, printing all - -Now we are nearly ready to print the whole graph. - -The function to print the graph with the proper labels follows the -outline we created earlier (@pxref{Full Graph, , A Graph with Labelled -Axes}), but with additions. - -@need 1250 -Here is the outline: - -@smallexample -@group -(defun print-graph (numbers-list) - "@var{documentation}@dots{}" - (let ((height @dots{} - @dots{})) -@end group -@group - (print-Y-axis height @dots{} ) - (graph-body-print numbers-list) - (print-X-axis @dots{} ))) -@end group -@end smallexample - -@menu -* The final version:: A few changes. -* Test print-graph:: Run a short test. -* Graphing words in defuns:: Executing the final code. -* lambda:: How to write an anonymous function. -* mapcar:: Apply a function to elements of a list. -* Another Bug:: Yet another bug @dots{} most insidious. -* Final printed graph:: The graph itself! -@end menu - -@node The final version, Test print-graph, Print Whole Graph, Print Whole Graph -@ifnottex -@unnumberedsubsec Changes for the Final Version -@end ifnottex - -The final version is different from what we planned in two ways: -first, it contains additional values calculated once in the varlist; -second, it carries an option to specify the labels' increment per row. -This latter feature turns out to be essential; otherwise, a graph may -have more rows than fit on a display or on a sheet of paper. - -@need 1500 -This new feature requires a change to the @code{Y-axis-column} -function, to add @code{vertical-step} to it. The function looks like -this: - -@findex Y-axis-column @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." -@end group -@group - (let (Y-axis - (number-per-line (or vertical-step 1))) - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) -@end group -@group - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -The values for the maximum height of graph and the width of a symbol -are computed by @code{print-graph} in its @code{let} expression; so -@code{graph-body-print} must be changed to accept them. - -@findex graph-body-print @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@need 1250 -Finally, the code for the @code{print-graph} function: - -@findex print-graph @r{Final version.} -@smallexample -@group -;;; @r{Final version.} -(defun print-graph - (numbers-list &optional vertical-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units." -@end group -@group - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length -@end group -@group - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group - -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) -@end group -@group - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list))) -@end group -@end smallexample - -@node Test print-graph, Graphing words in defuns, The final version, Print Whole Graph -@appendixsubsec Testing @code{print-graph} - -@need 1250 -We can test the @code{print-graph} function with a short list of numbers: - -@enumerate -@item -Install the final versions of @code{Y-axis-column}, -@code{graph-body-print}, and @code{print-graph} (in addition to the -rest of the code.) - -@item -Copy the following expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1)) -@end smallexample - -@item -Switch to the @file{*scratch*} buffer and place the cursor where you -want the axis labels to start. - -@item -Type @kbd{M-:} (@code{eval-expression}). - -@item -Yank the test expression into the minibuffer -with @kbd{C-y} (@code{yank)}. - -@item -Press @key{RET} to evaluate the expression. -@end enumerate - -@need 1250 -Emacs will print a graph that looks like this: - -@smallexample -@group -10 - - - - * - ** * - 5 - **** * - **** *** - * ********* - ************ - 1 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@need 1200 -On the other hand, if you pass @code{print-graph} a -@code{vertical-step} value of 2, by evaluating this expression: - -@smallexample -(print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) -@end smallexample - -@need 1250 -@noindent -The graph looks like this: - -@smallexample -@group -20 - - - - * - ** * -10 - **** * - **** *** - * ********* - ************ - 2 - ************* - - | | | | - 1 5 10 15 -@end group -@end smallexample - -@noindent -(A question: is the `2' on the bottom of the vertical axis a bug or a -feature? If you think it is a bug, and should be a `1' instead, (or -even a `0'), you can modify the sources.) - -@node Graphing words in defuns, lambda, Test print-graph, Print Whole Graph -@appendixsubsec Graphing Numbers of Words and Symbols - -Now for the graph for which all this code was written: a graph that -shows how many function definitions contain fewer than 10 words and -symbols, how many contain between 10 and 19 words and symbols, how -many contain between 20 and 29 words and symbols, and so on. - -This is a multi-step process. First make sure you have loaded all the -requisite code. - -@need 1500 -It is a good idea to reset the value of @code{top-of-ranges} in case -you have set it to some different value. You can evaluate the -following: - -@smallexample -@group -(setq top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250 - 260 270 280 290 300) -@end group -@end smallexample - -@noindent -Next create a list of the number of words and symbols in each range. - -@need 1500 -@noindent -Evaluate the following: - -@smallexample -@group -(setq list-for-graph - (defuns-per-range - (sort - (recursive-lengths-list-many-files - (directory-files "/usr/local/emacs/lisp" - t ".+el$")) - '<) - top-of-ranges)) -@end group -@end smallexample - -@noindent -On my old machine, this took about an hour. It looked though 303 Lisp -files in my copy of Emacs version 19.23. After all that computing, -the @code{list-for-graph} had this value: - -@smallexample -@group -(537 1027 955 785 594 483 349 292 224 199 166 120 116 99 -90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) -@end group -@end smallexample - -@noindent -This means that my copy of Emacs had 537 function definitions with -fewer than 10 words or symbols in them, 1,027 function definitions -with 10 to 19 words or symbols in them, 955 function definitions with -20 to 29 words or symbols in them, and so on. - -Clearly, just by looking at this list we can see that most function -definitions contain ten to thirty words and symbols. - -Now for printing. We do @emph{not} want to print a graph that is -1,030 lines high @dots{} Instead, we should print a graph that is -fewer than twenty-five lines high. A graph that height can be -displayed on almost any monitor, and easily printed on a sheet of paper. - -This means that each value in @code{list-for-graph} must be reduced to -one-fiftieth its present value. - -Here is a short function to do just that, using two functions we have -not yet seen, @code{mapcar} and @code{lambda}. - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number one-fiftieth of previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@node lambda, mapcar, Graphing words in defuns, Print Whole Graph -@appendixsubsec A @code{lambda} Expression: Useful Anonymity -@cindex Anonymous function -@findex lambda - -@code{lambda} is the symbol for an anonymous function, a function -without a name. Every time you use an anonymous function, you need to -include its whole body. - -@need 1250 -@noindent -Thus, - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -is a function definition that says `return the value resulting from -dividing whatever is passed to me as @code{arg} by 50'. - -@need 1200 -Earlier, for example, we had a function @code{multiply-by-seven}; it -multiplied its argument by 7. This function is similar, except it -divides its argument by 50; and, it has no name. The anonymous -equivalent of @code{multiply-by-seven} is: - -@smallexample -(lambda (number) (* 7 number)) -@end smallexample - -@noindent -(@xref{defun, , The @code{defun} Special Form}.) - -@need 1250 -@noindent -If we want to multiply 3 by 7, we can write: - -@c !!! Clear print-postscript-figures if the computer formatting this -@c document is too small and cannot handle all the diagrams and figures. -@c clear print-postscript-figures -@c set print-postscript-figures -@c lambda example diagram #1 -@ifnottex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-1} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-1.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -(multiply-by-seven 3) - \_______________/ ^ - | | - function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 21. - -@need 1250 -@noindent -Similarly, we can write: - -@c lambda example diagram #2 -@ifnottex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-2} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-2.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (number) (* 7 number)) 3) - \____________________________/ ^ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@need 1250 -@noindent -If we want to divide 100 by 50, we can write: - -@c lambda example diagram #3 -@ifnottex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end ifnottex -@ifset print-postscript-figures -@sp 1 -@tex -@center @image{lambda-3} -%%%% old method of including an image -% \input /usr/local/lib/tex/inputs/psfig.tex -% \centerline{\psfig{figure=/usr/local/lib/emacs/man/lambda-3.eps}} -% \catcode`\@=0 % -@end tex -@sp 1 -@end ifset -@ifclear print-postscript-figures -@iftex -@smallexample -@group -((lambda (arg) (/ arg 50)) 100) - \______________________/ \_/ - | | - anonymous function argument -@end group -@end smallexample -@end iftex -@end ifclear - -@noindent -This expression returns 2. The 100 is passed to the function, which -divides that number by 50. - -@xref{Lambda Expressions, , Lambda Expressions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{lambda}. Lisp and lambda -expressions derive from the Lambda Calculus. - -@node mapcar, Another Bug, lambda, Print Whole Graph -@appendixsubsec The @code{mapcar} Function -@findex mapcar - -@code{mapcar} is a function that calls its first argument with each -element of its second argument, in turn. The second argument must be -a sequence. - -The @samp{map} part of the name comes from the mathematical phrase, -`mapping over a domain', meaning to apply a function to each of the -elements in a domain. The mathematical phrase is based on the -metaphor of a surveyor walking, one step at a time, over an area he is -mapping. And @samp{car}, of course, comes from the Lisp notion of the -first of a list. - -@need 1250 -@noindent -For example, - -@smallexample -@group -(mapcar '1+ '(2 4 6)) - @result{} (3 5 7) -@end group -@end smallexample - -@noindent -The function @code{1+} which adds one to its argument, is executed on -@emph{each} element of the list, and a new list is returned. - -Contrast this with @code{apply}, which applies its first argument to -all the remaining. -(@xref{Readying a Graph, , Readying a Graph}, for a explanation of -@code{apply}.) - -@need 1250 -In the definition of @code{one-fiftieth}, the first argument is the -anonymous function: - -@smallexample -(lambda (arg) (/ arg 50)) -@end smallexample - -@noindent -and the second argument is @code{full-range}, which will be bound to -@code{list-for-graph}. - -@need 1250 -The whole expression looks like this: - -@smallexample -(mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end smallexample - -@xref{Mapping Functions, , Mapping Functions, elisp, The GNU Emacs -Lisp Reference Manual}, for more about @code{mapcar}. - -Using the @code{one-fiftieth} function, we can generate a list in -which each element is one-fiftieth the size of the corresponding -element in @code{list-for-graph}. - -@smallexample -@group -(setq fiftieth-list-for-graph - (one-fiftieth list-for-graph)) -@end group -@end smallexample - -@need 1250 -The resulting list looks like this: - -@smallexample -@group -(10 20 19 15 11 9 6 5 4 3 3 2 2 -1 1 1 1 0 1 0 0 0 0 0 0 0 0 0 0 0 4) -@end group -@end smallexample - -@noindent -This, we are almost ready to print! (We also notice the loss of -information: many of the higher ranges are 0, meaning that fewer than -50 defuns had that many words or symbols---but not necessarily meaning -that none had that many words or symbols.) - -@node Another Bug, Final printed graph, mapcar, Print Whole Graph -@appendixsubsec Another Bug @dots{} Most Insidious -@cindex Bug, most insidious type -@cindex Insidious type of bug - -I said `almost ready to print'! Of course, there is a bug in the -@code{print-graph} function @dots{} It has a @code{vertical-step} -option, but not a @code{horizontal-step} option. The -@code{top-of-range} scale goes from 10 to 300 by tens. But the -@code{print-graph} function will print only by ones. - -This is a classic example of what some consider the most insidious -type of bug, the bug of omission. This is not the kind of bug you can -find by studying the code, for it is not in the code; it is an omitted -feature. Your best actions are to try your program early and often; -and try to arrange, as much as you can, to write code that is easy to -understand and easy to change. Try to be aware, whenever you can, -that whatever you have written, @emph{will} be rewritten, if not soon, -eventually. A hard maxim to follow. - -It is the @code{print-X-axis-numbered-line} function that needs the -work; and then the @code{print-X-axis} and the @code{print-graph} -functions need to be adapted. Not much needs to be done; there is one -nicety: the numbers ought to line up under the tic marks. This takes -a little thought. - -@need 1250 -Here is the corrected @code{print-X-axis-numbered-line}: - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; @r{Delete extra leading spaces.} - (delete-char - (- (1- - (length (number-to-string horizontal-step))))) - (insert (concat - (make-string -@end group -@group - ;; @r{Insert white space.} - (- (* symbol-width - X-axis-label-spacing) - (1- - (length - (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string - (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element - (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@need 1500 -If you are reading this in Info, you can see the new versions of -@code{print-X-axis} @code{print-graph} and evaluate them. If you are -reading this in a printed book, you can see the changed lines here -(the full text is too much to print). - -@iftex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - @dots{} - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list - &optional vertical-step horizontal-step) - @dots{} - (print-X-axis numbers-list horizontal-step)) -@end group -@end smallexample -@end iftex - -@ifnottex -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@end ifnottex - -@c qqq -@ignore -Graphing Definitions Re-listed - -@need 1250 -Here are all the graphing definitions in their final form: - -@smallexample -@group -(defvar top-of-ranges - '(10 20 30 40 50 - 60 70 80 90 100 - 110 120 130 140 150 - 160 170 180 190 200 - 210 220 230 240 250) - "List specifying ranges for `defuns-per-range'.") -@end group - -@group -(defvar graph-symbol "*" - "String used as symbol in graph, usually an asterisk.") -@end group - -@group -(defvar graph-blank " " - "String used as blank in graph, usually a blank space. -graph-blank must be the same number of columns wide -as graph-symbol.") -@end group - -@group -(defvar Y-axis-tic " - " - "String that follows number in a Y axis label.") -@end group - -@group -(defvar Y-axis-label-spacing 5 - "Number of lines from one Y axis label to next.") -@end group - -@group -(defvar X-axis-tic-symbol "|" - "String to insert to point to a column in X axis.") -@end group - -@group -(defvar X-axis-label-spacing - (if (boundp 'graph-blank) - (* 5 (length graph-blank)) 5) - "Number of units from one X axis label to next.") -@end group -@end smallexample - -@smallexample -@group -(defun count-words-in-defun () - "Return the number of words and symbols in a defun." - (beginning-of-defun) - (let ((count 0) - (end (save-excursion (end-of-defun) (point)))) -@end group - -@group - (while - (and (< (point) end) - (re-search-forward - "\\(\\w\\|\\s_\\)+[^ \t\n]*[ \t\n]*" - end t)) - (setq count (1+ count))) - count)) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-file (filename) - "Return list of definitions' lengths within FILE. -The returned list is a list of numbers. -Each number is the number of words or -symbols in one function definition." -@end group - -@group - (message "Working on `%s' ... " filename) - (save-excursion - (let ((buffer (find-file-noselect filename)) - (lengths-list)) - (set-buffer buffer) - (setq buffer-read-only t) - (widen) - (goto-char (point-min)) -@end group - -@group - (while (re-search-forward "^(defun" nil t) - (setq lengths-list - (cons (count-words-in-defun) lengths-list))) - (kill-buffer buffer) - lengths-list))) -@end group -@end smallexample - -@smallexample -@group -(defun lengths-list-many-files (list-of-files) - "Return list of lengths of defuns in LIST-OF-FILES." - (let (lengths-list) -;;; @r{true-or-false-test} - (while list-of-files - (setq lengths-list - (append - lengths-list -@end group -@group -;;; @r{Generate a lengths' list.} - (lengths-list-file - (expand-file-name (car list-of-files))))) -;;; @r{Make files' list shorter.} - (setq list-of-files (cdr list-of-files))) -;;; @r{Return final value of lengths' list.} - lengths-list)) -@end group -@end smallexample - -@smallexample -@group -(defun defuns-per-range (sorted-lengths top-of-ranges) - "SORTED-LENGTHS defuns in each TOP-OF-RANGES range." - (let ((top-of-range (car top-of-ranges)) - (number-within-range 0) - defuns-per-range-list) -@end group - -@group - ;; @r{Outer loop.} - (while top-of-ranges - - ;; @r{Inner loop.} - (while (and - ;; @r{Need number for numeric test.} - (car sorted-lengths) - (< (car sorted-lengths) top-of-range)) - - ;; @r{Count number of definitions within current range.} - (setq number-within-range (1+ number-within-range)) - (setq sorted-lengths (cdr sorted-lengths))) -@end group - -@group - ;; @r{Exit inner loop but remain within outer loop.} - - (setq defuns-per-range-list - (cons number-within-range defuns-per-range-list)) - (setq number-within-range 0) ; @r{Reset count to zero.} - - ;; @r{Move to next range.} - (setq top-of-ranges (cdr top-of-ranges)) - ;; @r{Specify next top of range value.} - (setq top-of-range (car top-of-ranges))) -@end group - -@group - ;; @r{Exit outer loop and count the number of defuns larger than} - ;; @r{ the largest top-of-range value.} - (setq defuns-per-range-list - (cons - (length sorted-lengths) - defuns-per-range-list)) - - ;; @r{Return a list of the number of definitions within each range,} - ;; @r{ smallest to largest.} - (nreverse defuns-per-range-list))) -@end group -@end smallexample - -@smallexample -@group -(defun column-of-graph (max-graph-height actual-height) - "Return list of MAX-GRAPH-HEIGHT strings; -ACTUAL-HEIGHT are graph-symbols. -The graph-symbols are contiguous entries at the end -of the list. -The list will be inserted as one column of a graph. -The strings are either graph-blank or graph-symbol." -@end group - -@group - (let ((insert-list nil) - (number-of-top-blanks - (- max-graph-height actual-height))) - - ;; @r{Fill in @code{graph-symbols}.} - (while (> actual-height 0) - (setq insert-list (cons graph-symbol insert-list)) - (setq actual-height (1- actual-height))) -@end group - -@group - ;; @r{Fill in @code{graph-blanks}.} - (while (> number-of-top-blanks 0) - (setq insert-list (cons graph-blank insert-list)) - (setq number-of-top-blanks - (1- number-of-top-blanks))) - - ;; @r{Return whole list.} - insert-list)) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-element (number full-Y-label-width) - "Construct a NUMBERed label element. -A numbered element looks like this ` 5 - ', -and is padded as needed so all line up with -the element for the largest number." -@end group -@group - (let* ((leading-spaces - (- full-Y-label-width - (length - (concat (number-to-string number) - Y-axis-tic))))) -@end group -@group - (concat - (make-string leading-spaces ? ) - (number-to-string number) - Y-axis-tic))) -@end group -@end smallexample - -@smallexample -@group -(defun print-Y-axis - (height full-Y-label-width &optional vertical-step) - "Insert Y axis by HEIGHT and FULL-Y-LABEL-WIDTH. -Height must be the maximum height of the graph. -Full width is the width of the highest label element. -Optionally, print according to VERTICAL-STEP." -@end group -@group -;; Value of height and full-Y-label-width -;; are passed by `print-graph'. - (let ((start (point))) - (insert-rectangle - (Y-axis-column height full-Y-label-width vertical-step)) -@end group -@group - ;; @r{Place point ready for inserting graph.} - (goto-char start) - ;; @r{Move point forward by value of} full-Y-label-width - (forward-char full-Y-label-width))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-tic-line - (number-of-X-tics X-axis-leading-spaces X-axis-tic-element) - "Print ticks for X axis." - (insert X-axis-leading-spaces) - (insert X-axis-tic-symbol) ; @r{Under first column.} -@end group -@group - ;; @r{Insert second tic in the right spot.} - (insert (concat - (make-string - (- (* symbol-width X-axis-label-spacing) - ;; @r{Insert white space up to second tic symbol.} - (* 2 (length X-axis-tic-symbol))) - ? ) - X-axis-tic-symbol)) -@end group -@group - ;; @r{Insert remaining ticks.} - (while (> number-of-X-tics 1) - (insert X-axis-tic-element) - (setq number-of-X-tics (1- number-of-X-tics)))) -@end group -@end smallexample - -@smallexample -@group -(defun X-axis-element (number) - "Construct a numbered X axis element." - (let ((leading-spaces - (- (* symbol-width X-axis-label-spacing) - (length (number-to-string number))))) - (concat (make-string leading-spaces ? ) - (number-to-string number)))) -@end group -@end smallexample - -@smallexample -@group -(defun graph-body-print (numbers-list height symbol-width) - "Print a bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -HEIGHT is maximum height of graph. -SYMBOL-WIDTH is number of each column." -@end group -@group - (let (from-position) - (while numbers-list - (setq from-position (point)) - (insert-rectangle - (column-of-graph height (car numbers-list))) - (goto-char from-position) - (forward-char symbol-width) -@end group -@group - ;; @r{Draw graph column by column.} - (sit-for 0) - (setq numbers-list (cdr numbers-list))) - ;; @r{Place point for X axis labels.} - (forward-line height) - (insert "\n"))) -@end group -@end smallexample - -@smallexample -@group -(defun Y-axis-column - (height width-of-label &optional vertical-step) - "Construct list of labels for Y axis. -HEIGHT is maximum height of graph. -WIDTH-OF-LABEL is maximum width of label. -@end group -@group -VERTICAL-STEP, an option, is a positive integer -that specifies how much a Y axis label increments -for each line. For example, a step of 5 means -that each line is five units of the graph." - (let (Y-axis - (number-per-line (or vertical-step 1))) -@end group -@group - (while (> height 1) - (if (zerop (% height Y-axis-label-spacing)) - ;; @r{Insert label.} - (setq Y-axis - (cons - (Y-axis-element - (* height number-per-line) - width-of-label) - Y-axis)) -@end group -@group - ;; @r{Else, insert blanks.} - (setq Y-axis - (cons - (make-string width-of-label ? ) - Y-axis))) - (setq height (1- height))) -@end group -@group - ;; @r{Insert base line.} - (setq Y-axis (cons (Y-axis-element - (or vertical-step 1) - width-of-label) - Y-axis)) - (nreverse Y-axis))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis-numbered-line - (number-of-X-tics X-axis-leading-spaces - &optional horizontal-step) - "Print line of X-axis numbers" - (let ((number X-axis-label-spacing) - (horizontal-step (or horizontal-step 1))) -@end group -@group - (insert X-axis-leading-spaces) - ;; line up number - (delete-char (- (1- (length (number-to-string horizontal-step))))) - (insert (concat - (make-string - ;; @r{Insert white space up to next number.} - (- (* symbol-width X-axis-label-spacing) - (1- (length (number-to-string horizontal-step))) - 2) - ? ) - (number-to-string (* number horizontal-step)))) -@end group -@group - ;; @r{Insert remaining numbers.} - (setq number (+ number X-axis-label-spacing)) - (while (> number-of-X-tics 1) - (insert (X-axis-element (* number horizontal-step))) - (setq number (+ number X-axis-label-spacing)) - (setq number-of-X-tics (1- number-of-X-tics))))) -@end group -@end smallexample - -@smallexample -@group -(defun print-X-axis (numbers-list horizontal-step) - "Print X axis labels to length of NUMBERS-LIST. -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." -@end group -@group -;; Value of symbol-width and full-Y-label-width -;; are passed by `print-graph'. - (let* ((leading-spaces - (make-string full-Y-label-width ? )) - ;; symbol-width @r{is provided by} graph-body-print - (tic-width (* symbol-width X-axis-label-spacing)) - (X-length (length numbers-list)) -@end group -@group - (X-tic - (concat - (make-string - ;; @r{Make a string of blanks.} - (- (* symbol-width X-axis-label-spacing) - (length X-axis-tic-symbol)) - ? ) -@end group -@group - ;; @r{Concatenate blanks with tic symbol.} - X-axis-tic-symbol)) - (tic-number - (if (zerop (% X-length tic-width)) - (/ X-length tic-width) - (1+ (/ X-length tic-width))))) -@end group - -@group - (print-X-axis-tic-line - tic-number leading-spaces X-tic) - (insert "\n") - (print-X-axis-numbered-line - tic-number leading-spaces horizontal-step))) -@end group -@end smallexample - -@smallexample -@group -(defun one-fiftieth (full-range) - "Return list, each number of which is 1/50th previous." - (mapcar '(lambda (arg) (/ arg 50)) full-range)) -@end group -@end smallexample - -@smallexample -@group -(defun print-graph - (numbers-list &optional vertical-step horizontal-step) - "Print labelled bar graph of the NUMBERS-LIST. -The numbers-list consists of the Y-axis values. -@end group - -@group -Optionally, VERTICAL-STEP, a positive integer, -specifies how much a Y axis label increments for -each line. For example, a step of 5 means that -each row is five units. -@end group - -@group -Optionally, HORIZONTAL-STEP, a positive integer, -specifies how much an X axis label increments for -each column." - (let* ((symbol-width (length graph-blank)) - ;; @code{height} @r{is both the largest number} - ;; @r{and the number with the most digits.} - (height (apply 'max numbers-list)) -@end group -@group - (height-of-top-line - (if (zerop (% height Y-axis-label-spacing)) - height - ;; @r{else} - (* (1+ (/ height Y-axis-label-spacing)) - Y-axis-label-spacing))) -@end group -@group - (vertical-step (or vertical-step 1)) - (full-Y-label-width - (length - (concat - (number-to-string - (* height-of-top-line vertical-step)) - Y-axis-tic)))) -@end group -@group - - (print-Y-axis - height-of-top-line full-Y-label-width vertical-step) - (graph-body-print - numbers-list height-of-top-line symbol-width) - (print-X-axis numbers-list horizontal-step))) -@end group -@end smallexample -@c qqq -@end ignore - -@page -@node Final printed graph, , Another Bug, Print Whole Graph -@appendixsubsec The Printed Graph - -When made and installed, you can call the @code{print-graph} command -like this: -@sp 1 - -@smallexample -@group -(print-graph fiftieth-list-for-graph 50 10) -@end group -@end smallexample -@sp 1 - -@noindent -Here is the graph: -@sp 2 - -@smallexample -@group -1000 - * - ** - ** - ** - ** - 750 - *** - *** - *** - *** - **** - 500 - ***** - ****** - ****** - ****** - ******* - 250 - ******** - ********* * - *********** * - ************* * - 50 - ***************** * * - | | | | | | | | - 10 50 100 150 200 250 300 350 -@end group -@end smallexample - -@sp 2 - -@noindent -The largest group of functions contain 10 -- 19 words and symbols each. - -@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top -@appendix Free Software and Free Manuals - -@strong{by Richard M. Stallman} -@sp 1 - -The biggest deficiency in free operating systems is not in the -software---it is the lack of good free manuals that we can include in -these systems. Many of our most important programs do not come with -full manuals. Documentation is an essential part of any software -package; when an important free software package does not come with a -free manual, that is a major gap. We have many such gaps today. - -Once upon a time, many years ago, I thought I would learn Perl. I got -a copy of a free manual, but I found it hard to read. When I asked -Perl users about alternatives, they told me that there were better -introductory manuals---but those were not free. - -Why was this? The authors of the good manuals had written them for -O'Reilly Associates, which published them with restrictive terms---no -copying, no modification, source files not available---which exclude -them from the free software community. - -That wasn't the first time this sort of thing has happened, and (to -our community's great loss) it was far from the last. Proprietary -manual publishers have enticed a great many authors to restrict their -manuals since then. Many times I have heard a GNU user eagerly tell me -about a manual that he is writing, with which he expects to help the -GNU project---and then had my hopes dashed, as he proceeded to explain -that he had signed a contract with a publisher that would restrict it -so that we cannot use it. - -Given that writing good English is a rare skill among programmers, we -can ill afford to lose manuals this way. - -@c (texinfo)uref -(The Free Software Foundation -@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , -sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, -GNU manuals}, too.) - -Free documentation, like free software, is a matter of freedom, not -price. The problem with these manuals was not that O'Reilly Associates -charged a price for printed copies---that in itself is fine. (The Free -Software Foundation sells printed copies of free GNU manuals, too.) -But GNU manuals are available in source code form, while these manuals -are available only on paper. GNU manuals come with permission to copy -and modify; the Perl manuals do not. These restrictions are the -problems. - -The criterion for a free manual is pretty much the same as for free -software: it is a matter of giving all users certain -freedoms. Redistribution (including commercial redistribution) must be -permitted, so that the manual can accompany every copy of the program, -on-line or on paper. Permission for modification is crucial too. - -As a general rule, I don't believe that it is essential for people to -have permission to modify all sorts of articles and books. The issues -for writings are not necessarily the same as those for software. For -example, I don't think you or I are obliged to give permission to -modify articles like this one, which describe our actions and our -views. - -But there is a particular reason why the freedom to modify is crucial -for documentation for free software. When people exercise their right -to modify the software, and add or change its features, if they are -conscientious they will change the manual too---so they can provide -accurate and usable documentation with the modified program. A manual -which forbids programmers to be conscientious and finish the job, or -more precisely requires them to write a new manual from scratch if -they change the program, does not fill our community's needs. - -While a blanket prohibition on modification is unacceptable, some -kinds of limits on the method of modification pose no problem. For -example, requirements to preserve the original author's copyright -notice, the distribution terms, or the list of authors, are ok. It is -also no problem to require modified versions to include notice that -they were modified, even to have entire sections that may not be -deleted or changed, as long as these sections deal with nontechnical -topics. (Some GNU manuals have them.) - -These kinds of restrictions are not a problem because, as a practical -matter, they don't stop the conscientious programmer from adapting the -manual to fit the modified program. In other words, they don't block -the free software community from making full use of the manual. - -However, it must be possible to modify all the technical content of -the manual, and then distribute the result in all the usual media, -through all the usual channels; otherwise, the restrictions do block -the community, the manual is not free, and so we need another manual. - -Unfortunately, it is often hard to find someone to write another -manual when a proprietary manual exists. The obstacle is that many -users think that a proprietary manual is good enough---so they don't -see the need to write a free manual. They do not see that the free -operating system has a gap that needs filling. - -Why do users think that proprietary manuals are good enough? Some have -not considered the issue. I hope this article will do something to -change that. - -Other users consider proprietary manuals acceptable for the same -reason so many people consider proprietary software acceptable: they -judge in purely practical terms, not using freedom as a -criterion. These people are entitled to their opinions, but since -those opinions spring from values which do not include freedom, they -are no guide for those of us who do value freedom. - -Please spread the word about this issue. We continue to lose manuals -to proprietary publishing. If we spread the word that proprietary -manuals are not sufficient, perhaps the next person who wants to help -GNU by writing documentation will realize, before it is too late, that -he must above all make it free. - -We can also encourage commercial publishers to sell free, copylefted -manuals instead of proprietary ones. One way you can help this is to -check the distribution terms of a manual before you buy it, and prefer -copylefted manuals to non-copylefted ones. - -@sp 2 -@noindent -Note: The Free Software Foundation maintains a page on its Web site -that lists free books available from other publishers:@* -@uref{http://www.gnu.org/doc/other-free-books.html} - -@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top -@appendix GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License -@include doclicense.texi - -@node Index, About the Author, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@ignore -MENU ENTRY: NODE NAME. -@end ignore - -@printindex cp - -@iftex -@c Place biographical information on right-hand (verso) page - -@tex -\par\vfill\supereject -\ifodd\pageno - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}\page -\else -% \par\vfill\supereject - \global\evenheadline={\hfil} \global\evenfootline={\hfil} - \global\oddheadline={\hfil} \global\oddfootline={\hfil} - %\page\hbox{}%\page - %\page\hbox{}%\page -\fi -@end tex - -@c page -@w{ } - -@c ================ Biographical information ================ - -@w{ } -@sp 8 -@center About the Author -@sp 1 -@end iftex - -@ifnottex -@node About the Author, , Index, Top -@unnumbered About the Author -@end ifnottex - -@quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the -world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own -airplane. -@end quotation - -@c @page -@c @w{ } -@c -@c @c Prevent page number on blank verso, so eject it first. -@c @tex -@c \par\vfill\supereject -@c @end tex - -@c @iftex -@c @headings off -@c @evenheading @thispage @| @| @thistitle -@c @oddheading @| @| @thispage -@c @end iftex - -@bye - -@ignore - arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf -@end ignore diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps deleted file mode 100644 index 9b928e23893..00000000000 --- a/doc/lispintro/lambda-1.eps +++ /dev/null @@ -1,469 +0,0 @@ -%! -%%BoundingBox: 33 710 173 759 -%%Title: lambda-diagram1 -%%CreationDate: Wed Mar 8 14:31:53 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 710 173 759 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 75 moveto (\(multiply-by-seven 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 80 moveto - 96 96 lineto - 224 96 lineto - 240 80 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 264 119 moveto - -22 0 atan dup cos 8 mul 264 exch sub - exch sin 8 mul 97 exch sub lineto - stroke -grestore -gsave - newpath - 264 97 8 3 0 -22 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 160 103 moveto - 160 119 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 139 moveto (function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 224 139 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:31:53 1995 diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps deleted file mode 100644 index 1b948211d54..00000000000 --- a/doc/lispintro/lambda-2.eps +++ /dev/null @@ -1,469 +0,0 @@ -%! -%%BoundingBox: 33 730 240 777 -%%Title: lambda-diagram2 -%%CreationDate: Wed Mar 8 14:33:09 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 730 240 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(number\) \(* 7 number\)\) 3\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 336 64 lineto - 353 49 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 395 85 moveto - -21 0 atan dup cos 8 mul 395 exch sub - exch sin 8 mul 64 exch sub lineto - stroke -grestore -gsave - newpath - 395 64 8 3 0 -21 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 208 69 moveto - 208 85 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 112 102 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 344 102 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:09 1995 diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps deleted file mode 100644 index f930b0e38c8..00000000000 --- a/doc/lispintro/lambda-3.eps +++ /dev/null @@ -1,469 +0,0 @@ -%! -%%BoundingBox: 33 728 211 777 -%%Title: lambda-diagram3 -%%CreationDate: Wed Mar 8 14:33:49 1995 -%%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% -% Due to bugs in Transcript, the 'PS-Adobe-' stuff is omitted from line 1 -% - -% Copyright (C) 1995, 1997, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -% Free Software Foundation, Inc. -% -% This file is part of GNU Emacs. -% -% GNU Emacs is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% GNU Emacs is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with GNU Emacs. If not, see . - -/tgifdict 132 dict def -tgifdict begin - -% -% Using a zero value radius for an ellipse or an arc would result -% in a non-invertible CTM matrix which causes problem when this -% when this PostScript is wrapped inside other routines, such as -% the multi.ps package from -% ftp.ucc.su.oz.au:/pub/ps_printing/multi. You can overcome such -% error by uncommenting the sole line of the procedure below: -% -/tgif_min_radius - { -% dup 0.01 lt { pop 0.01 } if - } bind def - -/tgifellipsedict 6 dict def -tgifellipsedict /mtrx matrix put - -/tgifellipse - { tgifellipsedict begin - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 0 360 arc - savematrix setmatrix - end - } def - -/tgifarrowtipdict 8 dict def -tgifarrowtipdict /mtrx matrix put - -/tgifarrowtip - { tgifarrowtipdict begin - /dy exch def - /dx exch def - /h exch def - /w exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - dy dx atan rotate - 0 0 moveto - w neg h lineto - w neg h neg lineto - savematrix setmatrix - end - } def - -/tgifarcdict 8 dict def -tgifarcdict /mtrx matrix put - -/tgifarcn - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arc - savematrix setmatrix - end - } def - -/tgifarc - { tgifarcdict begin - /endangle exch def - /startangle exch def - /yrad exch def - /xrad exch def - /y exch def - /x exch def - /savematrix mtrx currentmatrix def - x y translate - xrad yrad scale - 0 0 1 startangle endangle arcn - savematrix setmatrix - end - } def - -/tgifsetuserscreendict 22 dict def -tgifsetuserscreendict begin - /tempctm matrix def - /temprot matrix def - /tempscale matrix def - - /concatprocs - { /proc2 exch cvlit def - /proc1 exch cvlit def - /newproc proc1 length proc2 length add array def - newproc 0 proc1 putinterval - newproc proc1 length proc2 putinterval - newproc cvx - } def - /resmatrix matrix def - /findresolution - { 72 0 resmatrix defaultmatrix dtransform - /yres exch def /xres exch def - xres dup mul yres dup mul add sqrt - } def -end - -/tgifsetuserscreen - { tgifsetuserscreendict begin - /spotfunction exch def - /screenangle exch def - /cellsize exch def - - /m tempctm currentmatrix def - /rm screenangle temprot rotate def - /sm cellsize dup tempscale scale def - - sm rm m m concatmatrix m concatmatrix pop - - 1 0 m dtransform /y1 exch def /x1 exch def - - /veclength x1 dup mul y1 dup mul add sqrt def - /frequency findresolution veclength div def - - /newscreenangle y1 x1 atan def - - m 2 get m 1 get mul m 0 get m 3 get mul sub 0 gt - - {{neg} /spotfunction load concatprocs - /spotfunction exch def - } if - - frequency newscreenangle /spotfunction load setscreen - end - } def - -/tgifsetpatterndict 18 dict def -tgifsetpatterndict begin - /bitison - { /ybit exch def /xbit exch def - /bytevalue bstring ybit bwidth mul xbit 8 idiv add get def - - /mask 1 7 xbit 8 mod sub bitshift def - bytevalue mask and 0 ne - } def -end - -/tgifbitpatternspotfunction - { tgifsetpatterndict begin - /y exch def /x exch def - - /xindex x 1 add 2 div bpside mul cvi def - /yindex y 1 add 2 div bpside mul cvi def - - xindex yindex bitison - { /onbits onbits 1 add def 1 } - { /offbits offbits 1 add def 0 } - ifelse - end - } def - -/tgifsetpattern - { tgifsetpatterndict begin - /cellsz exch def - /angle exch def - /bwidth exch def - /bpside exch def - /bstring exch def - - /onbits 0 def /offbits 0 def - cellsz angle /tgifbitpatternspotfunction load tgifsetuserscreen - {} settransfer - offbits offbits onbits add div setgray - end - } def - -/tgifxpmdict 4 dict def -/tgifbwpicstr 1 string def -/tgifcolorpicstr 3 string def - -/tgifsetpixels { tgifxpmdict begin /pixels exch def end } def - -/tgifsetpix { tgifxpmdict begin pixels 3 1 roll putinterval end } def - -/tgifbwspot - { tgifxpmdict begin - /index exch def - tgifbwpicstr 0 - pixels index 3 mul 3 getinterval aload pop - 255 mul .114 mul exch 255 mul .587 mul add exch 255 mul .299 mul add - cvi put - tgifbwpicstr - end - } def - -/tgifcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop - 255 mul cvi tgifcolorpicstr 2 3 -1 roll put - 255 mul cvi tgifcolorpicstr 1 3 -1 roll put - 255 mul cvi tgifcolorpicstr 0 3 -1 roll put - tgifcolorpicstr - end - } def - -/tgifnewcolorspot - { tgifxpmdict begin - /index exch def - pixels index 3 mul 3 getinterval aload pop setrgbcolor - end - } def - -/tgifcolordict 4 dict def - -/colorimage where - { pop } - { /colorimage - { tgifcolordict begin - pop pop pop pop pop - /ih exch def - /iw exch def - /x 0 def - /y 0 def - 1 1 ih - { pop 1 1 iw - { pop currentfile - tgifbwpicstr readhexstring pop 0 get tgifnewcolorspot - x y moveto 1 0 rlineto 0 1 rlineto -1 0 rlineto - closepath fill - /x x 1 add def - } for - /y y 1 add def - /x 0 def - } for - end - } def - } ifelse - -/tgifpatdict 10 dict def - -/tgifpatbyte - { currentdict /retstr get exch - pat i cellsz mod get put - } def - -/tgifpatproc - { 0 1 widthlim {tgifpatbyte} for retstr - /i i 1 add def - } def - -/tgifpatfill - { tgifpatdict begin - /h exch def - /w exch def - /lty exch def - /ltx exch def - /cellsz exch def - /pat exch def - - /widthlim w cellsz div cvi 1 sub def - /retstr widthlim 1 add string def - /i 0 def - - ltx lty translate - w h true [1 0 0 1 0 0] {tgifpatproc} imagemask - ltx neg lty neg translate - end - } def - -/pat1 def -/pat2 <0000000000000000> def -/pat3 <8000000008000000> def -/pat4 <8800000022000000> def -/pat5 <8800220088002200> def -/pat6 <8822882288228822> def -/pat7 def -/pat8 <77dd77dd77dd77dd> def -/pat9 <77ffddff77ffddff> def -/pat10 <77ffffff77ffffff> def -/pat11 <7fffffff7fffffff> def -/pat12 <8040200002040800> def -/pat13 <40a00000040a0000> def -/pat14 def -/pat15 def -/pat16 def -/pat17 <038448300c020101> def -/pat18 <081c22c180010204> def -/pat19 <8080413e080814e3> def -/pat20 <8040201008040201> def -/pat21 <8844221188442211> def -/pat22 <77bbddee77bbddee> def -/pat23 def -/pat24 <7fbfdfeff7fbfdfe> def -/pat25 <3e1f8fc7e3f1f87c> def -/pat26 <0102040810204080> def -/pat27 <1122448811224488> def -/pat28 def -/pat29 <83070e1c3870e0c1> def -/pat30 def -/pat31 <7cf8f1e3c78f1f3e> def - -/tgifcentertext { dup stringwidth pop 2 div neg 0 rmoveto } def - -/tgifrighttext { dup stringwidth pop neg 0 rmoveto } def - -/tgifreencsmalldict 12 dict def -/tgifReEncodeSmall - { tgifreencsmalldict begin - /newcodesandnames exch def - /newfontname exch def - /basefontname exch def - - /basefontdict basefontname findfont def - /newfont basefontdict maxlength dict def - - basefontdict - { exch dup /FID ne - { dup /Encoding eq - { exch dup length array copy newfont 3 1 roll put } - { exch newfont 3 1 roll put } - ifelse - } - { pop pop } - ifelse - } - forall - - newfont /FontName newfontname put - newcodesandnames aload pop - - newcodesandnames length 2 idiv - { newfont /Encoding get 3 1 roll put} - repeat - - newfontname newfont definefont pop - end - } def - -/tgifgray { 8 1 0 72 300 32 div div tgifsetpattern } bind def - -/tgifboxdict 6 dict def -/tgifboxstroke - { tgifboxdict begin - /pat def /w def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - 1.415 setmiterlimit - w 1 eq { w setlinewidth } if - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray stroke 0 setgray } { stroke } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - w 1 eq { 1 setlinewidth } if - 1 setmiterlimit - end - } def -/tgifboxfill - { tgifboxdict begin - /pat def /y2 exch def /x2 exch def /y1 exch def /x1 exch def - pat pat1 ne pat pat2 ne and { gsave pat tgifgray } if - newpath x1 y1 moveto x2 y1 lineto x2 y2 lineto x1 y2 lineto closepath - pat pat2 eq { 1 setgray fill 0 setgray } { fill } ifelse - pat pat1 ne pat pat2 ne and { grestore } if - end - } def - -end - -%%PageBoundingBox: 33 728 211 777 -tgifdict begin -/tgifsavedpage save def - -1 setmiterlimit -1 setlinewidth - -0 setgray - -72 0 mul 72 11.00 mul translate -72 128 div 100 mul 100 div dup neg scale - -gsave - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 63 43 moveto (\(\(lambda \(arg\) \(/ arg 50\)\) 100\)) show - grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 80 48 moveto - 96 64 lineto - 284 64 lineto - 299 48 lineto - stroke -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 354 86 moveto - -25 0 atan dup cos 8 mul 354 exch sub - exch sin 8 mul 61 exch sub lineto - stroke -grestore -gsave - newpath - 354 61 8 3 0 -25 tgifarrowtip - closepath fill -grestore - -% POLY/OPEN-SPLINE -gsave - newpath - 199 70 moveto - 199 86 lineto - stroke -grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 101 106 moveto (anonymous function) show - grestore - -% TEXT -0 setgray -/Courier findfont [17 0 0 -17 0 0] makefont setfont - gsave - 293 106 moveto (argument) show - grestore - -grestore -tgifsavedpage restore -end -%MatchingCreationDate: Wed Mar 8 14:33:49 1995 diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in deleted file mode 100644 index 951f133501d..00000000000 --- a/doc/lispintro/makefile.w32-in +++ /dev/null @@ -1,74 +0,0 @@ -#### -*- Makefile -*- for the Emacs Lisp Introduction manual. - -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -srcdir = . - -infodir = $(srcdir)/../../info - -INFO_SOURCES = $(srcdir)/emacs-lisp-intro.texi -# The file name eintr must fit within 5 characters, to allow for -# -NN extensions to fit into DOS 8+3 limits without clashing -INFO_TARGETS = $(infodir)/eintr -DVI_TARGETS = emacs-lisp-intro.dvi - -MAKEINFO = makeinfo -INSTALL_INFO = install-info -TEXI2DVI = texi2dvi -DVIPS = dvips -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C - -.SUFFIXES: .dvi .ps .texi - -info: $(INFO_TARGETS) - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -$(infodir)/eintr: $(INFO_SOURCES) - $(MAKEINFO) -o $@ $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.dvi: $(INFO_SOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-lisp-intro.texi - -emacs-lisp-intro.html: $(INFO_SOURCES) - $(MAKEINFO) --html -o $@ $(srcdir)/emacs-lisp-intro.texi - -.dvi.ps: - $(DVIPS) $< -o $@ - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr *.tp - -clean: mostlyclean - - $(DEL) *.dvi $(infodir)/eintr* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc - -# Tell versions [3.59,3.63) of GNU make to not export all variables. -# Otherwise a system limit (for SysV at least) may be exceeded. -.NOEXPORT: diff --git a/doc/lispref/.arch-inventory b/doc/lispref/.arch-inventory deleted file mode 100644 index 2f5e6b9eea0..00000000000 --- a/doc/lispref/.arch-inventory +++ /dev/null @@ -1,4 +0,0 @@ -# Generated files -precious ^(config\.status|config\.cache)$ - -# arch-tag: dde817a2-94ff-4c6e-838c-bb5b33e7f0df diff --git a/doc/lispref/.cvsignore b/doc/lispref/.cvsignore deleted file mode 100644 index ba74d365995..00000000000 --- a/doc/lispref/.cvsignore +++ /dev/null @@ -1,13 +0,0 @@ -texput.log -elisp.?? -elisp.??? -config.log -config.cache -config.status -Makefile -makefile -elisp -elisp-? -elisp-?? -elisp1* -elisp2* diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog deleted file mode 100644 index cee45971a1d..00000000000 --- a/doc/lispref/ChangeLog +++ /dev/null @@ -1,8156 +0,0 @@ -2009-07-29 Chong Yidong - - * Version 23.1 released. - -2009-07-18 Chong Yidong - - * processes.texi (Shell Arguments): Copyedits. - -2009-07-18 Glenn Morris - - * loading.texi (Repeated Loading): Fix typo. - -2009-07-15 Glenn Morris - - * edebug.texi: Minor re-phrasings throughout. - (Edebug Execution Modes): Sit-for affects continue mode too. - (Jumping): Use `forward-sexp' rather than its keybinding. - (Edebug Misc): Fix Q binding. - (Edebug Eval): Remove cl version. - (Printing in Edebug): Clarify print-length etc. - (Instrumenting Macro Calls): Defopt edebug-eval-macro-args. - (Specification List): Remove edebug-unwrap findex entry. - (Specification Examples): defmacro is actually not the same as defun. - Escape "`" in example. - -2009-07-11 Kevin Ryde - - * hooks.texi (Standard Hooks): Fix cross-references. - - * loading.texi (Named Features): Refer to eval-after-load. - -2009-07-11 Glenn Morris - - * searching.texi (Regexp Backslash): Fix typo. - - * elisp.texi (Top): Display copyright notice at start of non-TeX. - -2009-07-10 Glenn Morris - - * elisp.texi, vol1.texi, vol2.texi: Update @detailmenu. - - * customize.texi (Customization Types): - * display.texi (Abstract Display): - * objects.texi (Character Type, String Type): - Merge in some menu descriptions from elisp.texi. - - * files.texi (Format Conversion): - * hash.texi (Hash Tables): - * minibuf.texi (Completion): - * modes.texi (Multiline Font Lock): - * os.texi (System Interface): - End menu description with period. - -2009-07-09 Glenn Morris - - * back.texi: Don't hard-code texinfo location. - - * two-volume.make (texinfodir): New, with location of texinfo.tex. - (tex): Add texinfodir to TEXINPUTS. - (elisp1med-init, elisp2med-init): Use texinfodir. - - * Makefile.in (texinfodir): Rename from usermanualdir, and update. - (clean): Add two-volume.make intermediate files. - - * elisp.texi, vol1.texi, vol2.texi: - Use a DATE variable with the publication date, and update it. - Fix antinews menu description. - - * vol1.texi, vol2.texi: Update VERSION to match elisp.texi. - Update the detailed node listing to match elisp.texi. - - * README: Update edition to match elisp.texi. - - * objects.texi (General Escape Syntax): - * nonascii.texi (Character Sets): - Use consistent case for "Unicode Standard". - - * anti.texi (Antinews): - * customize.texi (Variable Definitions): - * functions.texi (Declaring Functions): - * nonascii.texi (Character Properties): - * processes.texi (Serial Ports): - * text.texi (Special Properties): - * tips.texi (Coding Conventions): - Minor rearrangements to improve TeX line-filling. - - * commands.texi (Using Interactive): Fix cross-reference. - -2009-07-01 Andreas Schwab - - * help.texi (Help Functions): Fix description of help-buffer and - help-setup-xref to use @defun instead of @deffn. - -2009-06-24 Chong Yidong - - * display.texi (Window Systems): Add ns to the list. - -2009-06-17 Martin Rudalics - - * windows.texi (Dedicated Windows): Fix typo. - (Resizing Windows): Replace @defun by @deffn. - -2009-06-17 Glenn Morris - - * variables.texi (Directory Local Variables): - Update for 2009-04-11 name-change of dir-locals-directory-alist. - -2009-06-09 Kenichi Handa - - * nonascii.texi (Character Sets): State clearly that FROM and TO - are codepoints of CHARSET. - -2009-06-07 Chong Yidong - - * minibuf.texi (Reading File Names): Fix introductory text. - Suggested by stan@derbycityprints.com. - (High-Level Completion): Fix typo. - -2009-05-28 Chong Yidong - - * frames.texi (Text Terminal Colors): Multi-tty is already - implemented, but tty-local colors are not. - -2009-05-27 Chong Yidong - - * hooks.texi (Standard Hooks): Remove mention of obsolete - redisplay-end-trigger-functions. - - * internals.texi (Window Internals): Remove mention of obsolete - redisplay-end-trigger-functions. - -2009-05-21 Martin Rudalics - - * abbrevs.texi (Abbrev Mode): abbrev-mode is an option. - - * backups.texi (Making Backups): backup-directory-alist and - make-backup-file-name-function are options. - (Auto-Saving): auto-save-list-file-prefix is an option. - - * buffers.texi (Killing Buffers): buffer-offer-save is an - option. - - * display.texi (Refresh Screen): no-redraw-on-reenter is an - option. - (Echo Area Customization): echo-keystrokes is an option. - (Selective Display): selective-display-ellipses is an option. - (Temporary Displays): temp-buffer-show-function is an option. - (Face Attributes): underline-minimum-offset and x-bitmap-file-path - are options. - (Font Selection): face-font-family-alternatives, - face-font-selection-order, face-font-registry-alternatives, and - scalable-fonts-allowed are options. - (Fringe Indicators): indicate-buffer-boundaries is an option. - (Fringe Cursors): overflow-newline-into-fringe is an option. - (Scroll Bars): scroll-bar-mode is an option. - - * eval.texi (Eval): max-lisp-eval-depth is an option. - - * files.texi (Visiting Functions): find-file-hook is an option. - (Directory Names): directory-abbrev-alist is an option. - (Unique File Names): temporary-file-directory and - small-temporary-file-directory are options. - - * frames.texi (Initial Parameters): initial-frame-alist, - minibuffer-frame-alist and default-frame-alist are options. - (Cursor Parameters): blink-cursor-alist and - cursor-in-non-selected-windows ar options. - (Window System Selections): selection-coding-system is an - option. - (Display Feature Testing): display-mm-dimensions-alist is an - option. - - * help.texi (Help Functions): help-char and help-event-list are - options. - - * keymaps.texi (Functions for Key Lookup): meta-prefix-char is - an option. - - * minibuf.texi (Minibuffer History): history-length and - history-delete-duplicates are options. - (High-Level Completion): read-buffer-function and - read-buffer-completion-ignore-case are options. - (Reading File Names): read-file-name-completion-ignore-case is - an option. - - * modes.texi (Mode Line Top): mode-line-format is an option. - (Mode Line Variables): mode-line-position and mode-line-modes - are options. - - * nonascii.texi (Text Representations): - enable-multibyte-characters is an option. - (Default Coding Systems): auto-coding-regexp-alist, - file-coding-system-alist, auto-coding-alist and - auto-coding-functions are options. - (Specifying Coding Systems): inhibit-eol-conversion is an - option. - - * os.texi (Init File): site-run-file is an option. - (System Environment): mail-host-address is an option. - (User Identification): user-mail-address is an option. - (Terminal Output): baud-rate is an option. - - * positions.texi (Word Motion): words-include-escapes is an - option. - - * searching.texi (Standard Regexps): page-delimiter, - paragraph-separate, paragraph-separate and sentence-end are - options. - - * text.texi (Margins): left-margin and fill-nobreak-predicate - are options. - - * variables.texi (Local Variables): max-specpdl-size is an - option. - - * windows.texi (Choosing Window): - split-window-preferred-function, special-display-function and - display-buffer-function are options. - -2009-05-20 Chong Yidong - - Fix errors spotted by Martin Rudalics. - - * syntax.texi (Position Parse): Document rationale for ignored - arguments to syntax-ppss-flush-cache. - - * processes.texi (Input to Processes): Mark PROCESS arg to - process-running-child-p as optional. - (Network Options): Document NO-ERROR arg to - set-network-process-option. - - * buffers.texi (Indirect Buffers): Mark clone-indirect-buffer as a - command. - - * searching.texi (POSIX Regexps): Mark posix-search-forward and - posix-search-backward as commands. - - * os.texi (Killing Emacs): Mark kill-emacs as a command. - (Suspending Emacs): Mark suspend-emacs as a command. - (Processor Run Time): Mark emacs-uptime and emacs-init-time as - commands. - (Terminal Output): Remove obsolete function baud-rate. Document - TERMINAL arg for send-string-to-terminal. - - * nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for - terminal-coding-system and set-terminal-coding-system. - (Explicit Encoding): Mark DESTINATION arg of decode-coding-region - as optional. - (Character Sets): Document RESTRICTION arg of char-charset. - (Character Codes): Mark POS argument to get-byte as optional. - - * minibuf.texi (Minibuffer Misc): Document ARGS arg for - minibuffer-message. - - * files.texi (Create/Delete Dirs): Mark make-directory and - delete-directory as commands. - - * abbrevs.texi (Abbrev Tables): Fix arglist for make-abbrev-table. - - * text.texi (Base 64): Mark base64-decode-string and - base64-encode-string as commands. - (Columns): Mark move-to-column as a command. - (Mode-Specific Indent): Document RIGID arg to - indent-for-tab-command. - (Region Indent): Mark TO-COLUMN arg to indent-region as optional. - Mark indent-code-rigidly as a command. - (Substitution): Mark translate-region as a command. - - * frames.texi (Size and Position): Remove obsolete functions - screen-height and screen-width. - -2009-05-19 Chong Yidong - - * windows.texi (Cyclic Window Ordering, Cyclic Window Ordering) - (Displaying Buffers, Resizing Windows): Correct mistakes; - next-window, previous-window, and pop-to-buffer are not commands, - and fit-window-to-buffer" is a command. (Pointed out by Martin - Rudalics.) - -2009-05-17 Richard M Stallman - - * modes.texi (Precalculated Fontification): Clarify text. - -2009-05-17 Martin Rudalics - - * windows.texi (Selecting Windows): Clarify descriptions of - with-selected-window and get-lru-window. - (Cyclic Window Ordering): Refer to particular frame when talking - about how splitting affects the ordering. - (Displaying Buffers): Fix descriptions of switch-to-buffer and - switch-to-buffer-other-window. Explain how setting of - display-buffer-reuse-frames affects pop-to-buffer. - (Choosing Window): Clarify some details in descriptions of - display-buffer-reuse-frames, pop-up-frames, and - pop-up-frame-function. - (Dedicated Windows): Clarify some details. - (Textual Scrolling): Replace term vscroll by term vertical - scroll position. - (Vertical Scrolling): Fix typo. - (Window Hooks): Relate text on jit-lock-register to window - scrolling and size changes. - -2009-05-14 Chong Yidong - - * frames.texi (Initial Parameters): Clarify what the initial - minibuffer frame is. - (Buffer Parameters): Note that the minibuffer parameter can not be - altered. - - * anti.texi (Antinews): Copyedits. Rearrange some entries. - Document display-buffer changes. - -2009-05-13 Chong Yidong - - * anti.texi (Antinews): Rewrite for Emacs 22. - - * abbrevs.texi (Abbrevs): Add xref to Creating Symbols when - obarrays are first mentioned. Define "system abbrev" more - prominently, and add it to the index. - (Abbrev Mode, Abbrev Tables, Defining Abbrevs, Abbrev Properties): - Copyedits. - (Abbrev Expansion): Document abbrev-insert. - -2009-05-12 Chong Yidong - - * frames.texi (Font and Color Parameters): Rename from Color - Parameters. Document font-backend parameter. - - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - * elisp.texi (Top): Update node listing. - -2009-05-11 Martin Rudalics - - * windows.texi (Choosing Window): Don't explicitly refer to - split-window-sensibly's window argument in descriptions of - split-height-threshold and split-width-threshold. - -2009-05-10 Martin Rudalics - - * windows.texi (Choosing Window): Fix rewrite of window - splitting section. - -2009-05-09 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Document - find-auto-coding, set-auto-coding, and auto-coding-alist. Add - indexing. - (Lisp and Coding Systems): Add index entries. - -2009-05-09 Martin Rudalics - - * windows.texi (Choosing Window): Describe split-window-sensibly - and rewrite section on window splitting accordingly. - (Textual Scrolling): Replace `...' by @code{...}. - -2009-05-04 Chong Yidong - - * hooks.texi (Standard Hooks): Add abbrev-expand-functions. - Remove obsoleted pre-abbrev-expand-hook. - - * locals.texi (Standard Buffer-Local Variables): Consolidate table - entries. - - * internals.texi (Object Internals): Don't assume 32-bit machines - are the norm. - (Buffer Internals): Consolidate table entries for readability. - (Window Internals): Synch field names to window.h. - (Process Internals): Synch field names to process.h. - -2009-04-29 Chong Yidong - - * variables.texi (File Local Variables): Note that read-circle is - bound to nil when reading file-local variables. - - * streams.texi (Input Functions): Document read-circle. - (Output Variables): Add xref to Circular Objects. - -2009-04-25 Chong Yidong - - * tips.texi (Coding Conventions): Copyedits. Add xref to Named - Features and Coding System Basics. Node that "p" stands for - "predicate". Recommend utf-8-emacs instead of emacs-mule. - (Key Binding Conventions): Emacs does use S-down-mouse-1, for - mouse-appearance-menu. - (Programming Tips): Add xref to Progress. - -2009-04-22 Chong Yidong - - * os.texi (Command-Line Arguments): Document - command-line-args-left. - (Suspending Emacs): Adapt text to multi-tty case. Document use of - terminal objects for tty arguments. - (Startup Summary): Add xref to Session Management. - (Session Management): Mention emacs-session-restore. Copyedits. - -2009-04-20 Chong Yidong - - * os.texi (Startup Summary): Copyedits. The init file is not - necessarily named .emacs now. Document initial-buffer-choice and - initial-scratch-message. Note where Emacs exits in batch mode. - Document inhibit-splash-screen as an alias. - (Init File): Be neutral about which init file name to use. - -2009-04-16 Chong Yidong - - * os.texi (System Interface): Fix Texinfo usage. - -2009-04-15 Chong Yidong - - * searching.texi (Regexp Backslash): Also refer to shy groups as - non-capturing or unnumbered groups. - (Regexp Functions): Add cross-reference to Regexp Backslash. - - * display.texi (Truncation): Overlays can use line-prefix and - wrap-prefix too. - (Overlay Properties): Document wrap-prefix and line-prefix. - (Face Attributes): Document underline-minimum-offset. - (Face Remapping): Copyedits. - (Low-Level Font): Copyedits. - (Image Cache): Note that the image cache is shared between frames. - (Line Height): Emphasize that line-spacing only takes effect on - graphical terminals. - -2009-04-13 Chong Yidong - - * display.texi (Refresh Screen): Note that a passage about screen - refreshing is text terminal only. - (Forcing Redisplay): Delete misleading comment---sit-for calls - redisplay, not the other way around. - (Truncation): Note new values of truncate-partial-width-windows. - Copyedits. - (Invisible Text): Document invisible-p. - -2009-04-11 Eli Zaretskii - - * display.texi (Overlays): Overlays don't scale well. See - http://lists.gnu.org/archive/html/emacs-devel/2009-04/msg00243.html. - -2009-04-10 Chong Yidong - - * syntax.texi (Syntax Table Functions): Document cons cell - argument for modify-syntax-entry. - (Categories): Document cons cell argument for - modify-category-entry. - - * searching.texi (String Search): Document word-search-forward-lax - and word-search-backward-lax. - (Searching and Case): Describe isearch behavior more precisely. - - * keymaps.texi (Tool Bar): Mention that some platforms do not - support multi-line toolbars. Suggested by Stephen Eglen. - - * frames.texi (Layout Parameters): Mention that Nextstep also - allows only one tool-bar line. Suggested by Stephen Eglen. - - * nonascii.texi (Text Representations): Copyedits. - (Coding System Basics): Also mention utf-8-emacs. - (Converting Representations, Selecting a Representation) - (Scanning Charsets, Translation of Characters, Encoding and I/O): - Copyedits. - (Character Codes): Mention role of codepoints 1114112 to 4194175. - -2009-04-09 Chong Yidong - - * text.texi (Yank Commands): Note that yank uses push-mark. - (Filling): Clarify REGION argument of fill-paragraph. Document - fill-forward-paragraph-function. - (Special Properties): Remove "new in Emacs 22" declaration. - (Clickable Text): Merge with Links and Mouse-1 node. - - * display.texi (Button Properties, Button Buffer Commands): Change - xref to Clickable Text. - - * tips.texi (Key Binding Conventions): Change xref to Clickable - Text. - - * elisp.texi (Top): Update node listing. - -2009-04-05 Chong Yidong - - * markers.texi (The Mark): Copyedits. Improve description of - handle-shift-selection. - (The Region): Move use-region-p here from The Mark. - - * positions.texi (Screen Lines): Document (cols . lines) argument - for vertical-motion. - -2009-04-04 Chong Yidong - - * frames.texi (Frames): Clean up introduction. Document `ns' - return value for framep. - (Creating Frames): Note how the terminal is chosen. - (Multiple Terminals, Multiple Displays): Merge into a single node. - (Color Parameters): Fix typo. - - * variables.texi (Local Variables, Buffer-Local Variables) - (Creating Buffer-Local): Change link to Multiple Terminals. - - * os.texi (X11 Keysyms): Change link to Multiple Terminals. - - * keymaps.texi (Controlling Active Maps): Change link to Multiple - Terminals. - - * commands.texi (Command Loop Info, Keyboard Macros): Change link - to Multiple Terminals. - - * elisp.texi (Top): Update node listing. - * vol2.texi (Top): Update node listing. - * vol1.texi (Top): Update node listing. - - * buffers.texi (Current Buffer): Note that the append-to-buffer - example is no longer in synch with the latest code. Tie the two - examples together. - - * files.texi (File Attributes): Move note about MS-DOS from - Changing Files to File Attributes. - (Create/Delete Dirs): Note that mkdir is an alias for this. - -2009-04-01 Markus Triska - - * processes.texi (Filter Functions): Suggest how to handle output - batches. - -2009-03-30 Chong Yidong - - * help.texi (Accessing Documentation): Update example to use - help-setup-xref and with-help-window. - (Help Functions): Remove print-help-return-message, which is - semi-obsolete due to with-help-window. Document help-buffer and - help-setup-xref. - -2009-03-29 Chong Yidong - - * help.texi (Accessing Documentation, Help Functions): Remove - information about long-obsolete Emacs versions. - - * modes.texi (Mode Line Variables): The default values of the mode - line variables are now more complicated. - -2009-03-28 Chong Yidong - - * modes.texi (Major Mode Conventions): Note that specialness is - inherited. - (Derived Modes): Note that define-derive-mode sets the mode-class - property. - - * keymaps.texi (Prefix Keys): The M-g prefix key is now named - goto-map. Add search-map to the list. - -2009-03-27 Eli Zaretskii - - * os.texi (System Environment): Update the list of system-type - values. - - * markers.texi (The Mark) : Update for - removal of the optional argument DEACTIVATE. - -2009-03-25 Chong Yidong - - * commands.texi (Focus Events): Most X window managers don't use - focus-follows-mouse nowadays. - -2009-03-24 Chong Yidong - - * commands.texi (Defining Commands): Clarify introduction. - (Using Interactive): Not that interactive can be put in a symbol - property. - (Interactive Call): Note that a symbol with a non-nil - interactive-form property satisfies commandp. - -2009-03-23 Juanma Barranquero - - * minibuf.texi (Intro to Minibuffers): Fix typos. - -2009-03-23 Chong Yidong - - * minibuf.texi (Intro to Minibuffers): Remove long-obsolete info - about minibuffers in old Emacs versions. Copyedits. Emphasize - that enable-recursive-minibuffers defaults to nil. - (Text from Minibuffer): Simplify introduction. - -2009-03-22 Alan Mackenzie - - * commands.texi (Using Interactive): Clarify string argument to - `interactive' - even promptless elements need \n separators. - -2009-03-18 Chong Yidong - - * minibuf.texi (Completion Styles): New node. - - * elisp.texi (Top): Update node listing. - -2009-03-17 Chong Yidong - - * minibuf.texi (Basic Completion): Note that - read-file-name-completion-ignore-case and - read-buffer-completion-ignore-case can override - completion-ignore-case. - (Minibuffer Completion): Document completing-read changes. - (Completion Commands): Avoid mentioning partial completion mode. - Document minibuffer-completion-confirm changes, and - minibuffer-confirm-exit-commands. - (High-Level Completion): Document new require-match behavior for - read-buffer. Document read-buffer-completion-ignore-case. - (Reading File Names): Document new require-match behavior for - read-file-name. - -2009-03-14 Chong Yidong - - * debugging.texi (Error Debugging): Don't mislead the reader into - thinking that debug-on-error enters debugger for C-f at EOB. - (Error Debugging): Setting debug-on-init within the init file - works, and has for some time. - -2009-03-13 Kenichi Handa - - * display.texi (Fontsets): Update the description. - -2009-03-13 Chong Yidong - - * advice.texi (Advising Primitives): Link to What Is a Function. - -2009-03-12 Chong Yidong - - * compile.texi (Speed of Byte-Code): Update example. - (Disassembly): Update examples. - - * loading.texi (Repeated Loading): Simplify examples. - - * customize.texi (Common Keywords): It's not necessary to use :tag - to remove hyphens, as custom-unlispify-tag-name does it - automatically. - (Variable Definitions): Link to File Local Variables. Document - customized-value symbol property. - (Customization Types): Move menu to end of node. - -2009-03-10 Chong Yidong - - * macros.texi (Compiling Macros): Omit misleading sentence, which - implied that macros can only be used in the same file they are - defined. - (Backquote): Remove obsolete information about Emacs 19. - -2009-03-05 John Foerch (tiny change) - - * display.texi (Display Margins): Fix paren typo. - -2009-02-27 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * variables.texi (Variables): Clarify introduction. - (Global Variables): Mention that setq is a special form. - (Local Variables): Use active voice. - (Tips for Defining): Mention marking variables as safe. - (Buffer-Local Variables): Mention terminal-local and frame-local - variables together. - (File Local Variables): Copyedits. - (Frame-Local Variables): Note that they are not really useful. - (Future Local Variables): Node deleted. - - * objects.texi (General Escape Syntax): Update explanation of - unicode escape syntax. - -2009-02-23 Chong Yidong - - * control.texi (Control Structures): Add cindex entry for "textual - order". - - * eval.texi (Intro Eval): Copyedits. Standardize on "form" - instead of "expression" throughout. - (Function Indirection): Copyedits. Use active voice. - (Eval): The default value of max-lisp-eval-depth is now 400. - -2009-02-23 Miles Bader - - * processes.texi (System Processes): Rename `system-process-attributes' - to `process-attributes'. - -2009-02-22 Chong Yidong - - * symbols.texi (Property Lists): Emphasize that property lists are - not restricted to symbol cells. - (Other Plists): Copyedit. - - * sequences.texi (Sequences Arrays Vectors): Make introduction - more concise. - (Arrays): Mention char-tables and bool-vectors too. - (Vectors): Don't repeat information given in Arrays node. Link to - nodes that explain the vector usage examples. - (Char-Tables): Note that char-table elements can have arbitrary - type. Explain effect of omitted char-table-extra-slots property. - Link to Property Lists node. - -2009-02-22 Chong Yidong - - * lists.texi (Building Lists): Remove obsolete Emacs 20 usage of - `append'. - (List Elements): Copyedits. - - * sequences.texi (Vector Functions): Remove obsolete Emacs 20 use - of `vconcat'. - - * strings.texi (Creating Strings): Copyedits. Remove obsolete - Emacs 20 usage of `concat'. - (Case Conversion): Copyedits. - -2009-02-21 Chong Yidong - - * objects.texi (Lisp Data Types, Syntax for Strings, Buffer Type): - Minor edits. - (Frame Configuration Type): Emphasize that it is not primitive. - (Font Type): New node. - (Type Predicates): Add fontp; type-of now recognizes font object - types. - - * intro.texi (Version Info): Update version numbers in examples. - (Acknowledgements): List more contributors. - - * elisp.texi: Bump version number to 3.0. - (Top): Link to Font Type node. - -2009-02-20 Juanma Barranquero - - * modes.texi (Major Mode Conventions): Remove duplicate words. - (Customizing Keywords): Fix typo. - -2009-02-14 Eli Zaretskii - - * nonascii.texi (User-Chosen Coding Systems): Document that - select-safe-coding-system suggests raw-text if there are raw bytes - in the region. - (Explicit Encoding): Warn not to use `undecided' when encoding. - -2009-02-11 Glenn Morris - - * frames.texi (Visibility of Frames): Mention the effect multiple - workspaces/desktops can have on visibility. - -2009-02-07 Eli Zaretskii - - * text.texi (Commands for Insertion): - * commands.texi (Event Mod): - * keymaps.texi (Searching Keymaps): - * nonascii.texi (Translation of Characters): Reinstate - documentation of translation-table-for-input. - (Explicit Encoding): Document the `charset' text property produced - by decode-coding-region and decode-coding-string. - -2009-01-27 Alan Mackenzie - - * modes.texi (Search-based Fontification): Correct a typo. - -2009-01-25 Juanma Barranquero - - * abbrevs.texi (Abbrev Table Properties): Fix typo. - Reported by Seweryn Kokot . (Bug#2039) - -2009-01-24 Eli Zaretskii - - * display.texi (Window Systems): Document the value of - `initial-window-system' under --daemon. - - * os.texi (System Environment): Remove description of the - `environment' function which has been deleted. - -2009-01-22 Dan Nicolaescu - - * frames.texi (Multiple Displays): Remove documentation for - removed function make-frame-on-tty. - -2009-01-22 Chong Yidong - - * files.texi (Format Conversion Piecemeal): Clarify behavior of - write-region-annotate-functions. Document - write-region-post-annotation-function. - -2009-01-19 Chong Yidong - - * display.texi (Font Lookup): Document WIDTH argument of - x-list-fonts. - -2009-01-17 Eli Zaretskii - - * maps.texi (Standard Keymaps): Rename function-key-map to - local-function-key-map. - - * keymaps.texi (Translation Keymaps): Rename function-key-map to - local-function-key-map. - - * nonascii.texi (Terminal I/O Encoding): `keyboard-coding-system' - and `set-keyboard-coding-system' now accept an optional terminal - argument. - - * commands.texi (Event Mod): `keyboard-translate-table' is now - terminal-local. - (Function Keys): Rename function-key-map to - local-function-key-map. - - * elisp.texi (Top): Make @detailmenu be consistent with changes in - frames.texi. - - * hooks.texi (Standard Hooks): Document `delete-frame-functions' - `delete-terminal-functions', `suspend-tty-functions' and - `resume-tty-functions'. - - * frames.texi (Frames): Document `frame-terminal' and - `terminal-live-p'. - (Multiple Displays): Document `make-frame-on-tty'. - (Multiple Terminals): Document `terminal-list', `delete-terminal', - `terminal-name', and `get-device-terminal'. - (Terminal Parameters): Document `terminal-parameters', - `terminal-parameter', and `set-terminal-parameter'. - - * os.texi (System Environment): Document `environment' and - `initial-environment'. - (Suspending Emacs): Update for multi-tty; document - `suspend-tty', `resume-tty', and `controlling-tty-p'. - - * nonascii.texi (Coding System Basics): More accurate description - of `raw-text'. - -2009-01-12 Juanma Barranquero - - * display.texi (Low-Level Font): Fix typo. - -2009-01-10 Chong Yidong - - * elisp.texi (Top): Update node listing. - - * display.texi (PostScript Images): Node deleted. - -2009-01-10 Eli Zaretskii - - * processes.texi (Decoding Output): Document that null bytes force - no-conversion for reading process output. - - * files.texi (Reading from Files): Document that null bytes force - no-conversion when visiting files. - - * processes.texi (Serial Ports): Improve wording, suggested by RMS. - - * nonascii.texi (Lisp and Coding Systems): Document - inhibit-null-byte-detection and inhibit-iso-escape-detection. - (Character Properties): Improve wording. - -2009-01-09 Chong Yidong - - * display.texi (Font Lookup): Remove obsolete function - x-font-family-list. x-list-fonts accepts Fontconfig/GTK syntax. - (Low-Level Font): Rename from Fonts, move to end of Faces section. - (Font Selection): Reorder order of variable descriptions. Minor - clarifications. - - * elisp.texi (Top): Update node listing. - -2009-01-09 Glenn Morris - - * commands.texi (Command Loop Info): Say that last-command-char and - last-input-char are obsolete aliases. - - * edebug.texi (Edebug Recursive Edit): Remove separate references to - last-input-char and last-command-char, since they are just aliases for - last-input-event and last-command-event. - - * minibuf.texi (Minibuffer Commands): Use last-command-event rather than - last-command-char. - -2009-01-08 Chong Yidong - - * elisp.texi: Update node listing. - - * display.texi (Faces): Put Font Selection node after Auto Faces. - (Face Attributes): Don't link to Font Lookup. Document - font-family-list. - (Fonts): New node. - -2009-01-08 Jason Rumney - - * frames.texi (Pointer Shape): Clarify that only X supports - changing the standard pointer shapes. (Bug#1485) - -2009-01-08 Chong Yidong - - * display.texi (Attribute Functions): Note that a function value - :height is relative, and that compatibility functions work by - calling set-face-attribute. - (Displaying Faces): Reorder list in order of increasing priority. - (Face Remapping): New node. Content moved here from Displaying - Faces. - (Glyphs): Link to Face Functions. - -2009-01-08 Chong Yidong - - * display.texi (Faces): Don't discuss face id here. facep does - not return t. - (Defining Faces): Minor clarification. - (Face Attributes): Rearrange items to match docstring of - set-face-attribute. Add :foundry attribute. Document new role of - :font attribute. Texinfo usage fix. - (Attribute Functions): Copyedits. - (Face Functions): Note that face number is seldom used. - -2009-01-05 Richard M Stallman - - * strings.texi (Predicates for Strings): Minor clarification. - - * functions.texi (Function Safety): Texinfo usage fix. - -2009-01-04 Eduard Wiebe (tiny patch) - - * objects.texi (General Escape Syntax): Fix typo. - -2009-01-03 Martin Rudalics - - * windows.texi (Choosing Window): Say that pop-up-frame-alist - works via the default value of pop-up-frame-function. - -2009-01-02 Eli Zaretskii - - * processes.texi (System Processes): Document the `time' and - `ctime' attributes of `system-process-attributes'. - -2009-01-01 Chong Yidong - - * display.texi (Face Attributes): Clarify :height attribute. - -2008-12-31 Martin Rudalics - - * buffers.texi (The Buffer List): Clarify what moves a buffer to - the front of the buffer list. Add entries for `last-buffer' and - `unbury-buffer'. - -2008-12-27 Eli Zaretskii - - * elisp.texi (Top): Add @detailmenu items for "Multiple Terminals" - and its subsections. - - * frames.texi (Multiple Terminals, Low-level Terminal) - (Terminal Parameters, Frames on Other TTY devices): New sections. - (Frames): Add an xref to "Multiple Terminals". - - * elisp.texi (Top): Add @detailmenu item for "Terminal Type". - - * objects.texi (Terminal Type): New node. - (Editing Types): Add it to the menu. - - * elisp.texi (Top): Add a @detailmenu item for "Directory Local - Variables". - - * variables.texi (Directory Local Variables): New node. - (Variables): Add a menu item for it. - - * loading.texi (Autoload): Document `generate-autoload-cookie' and - `generated-autoload-file'. - -2008-12-20 Eli Zaretskii - - * os.texi (Startup Summary): Add xref to documentation of - `initial-window-system'. - - * display.texi (Window Systems): Document `window-system' the - function. The variable `window-system' is now frame-local. - Document `initial-window-system'. - -2008-12-19 Martin Rudalics - - * windows.texi (Windows): Rewrite description of - fit-window-to-buffer. - -2008-12-13 Glenn Morris - - * modes.texi (Font Lock Basics): Fix level description. (Bug#1534) - (Levels of Font Lock): Refer to font-lock-maximum-decoration. - -2008-12-12 Glenn Morris - - * debugging.texi (Error Debugging): Refer forwards to - eval-expression-debug-on-error. - -2008-12-05 Eli Zaretskii - - * strings.texi (String Basics): Only unibyte strings that - represent key sequences hold 8-bit raw bytes. - - * nonascii.texi (Coding System Basics): Rewrite @ignore'd - paragraph to speak about `undecided'. - (Character Properties): Don't explain the meaning of each - property; instead, identify their Unicode Standard names. - (Character Sets): Document `map-charset-chars'. - -2008-12-02 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Rewrite format-write-file - section yet again. - -2008-11-29 Eli Zaretskii - - * nonascii.texi (Character Properties): New Section. - (Specifying Coding Systems): Document - `coding-system-priority-list', `set-coding-system-priority', and - `with-coding-priority'. - (Lisp and Coding Systems): Document `check-coding-systems-region' - and `coding-system-charset-list'. - (Coding System Basics): Document `coding-system-aliases'. - - * elisp.texi (Top): Add a @detailmenu entry for "Character - Properties". - - * objects.texi (Character Type): Correct the range of Emacs - characters. Add an @xref to "Character Codes". - - * strings.texi (String Basics): Add an @xref to "Character Codes". - - * numbers.texi (Integer Basics): Add an @xref to `max-char'. - - * nonascii.texi (Explicit Encoding): Update for Emacs 23. - (Character Codes): Document `max-char'. - -2008-11-28 Eli Zaretskii - - * nonascii.texi (Text Representations, Converting Representations) - (Character Sets, Scanning Charsets, Translation of Characters): - Make text more accurate. - -2008-11-28 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Improve previous change. - -2008-11-26 Chong Yidong - - * modes.texi (Auto Major Mode): Fix example. - -2008-11-25 Glenn Morris - - * control.texi (Signaling Errors): Fix `wrong-type-argument' name. - - * files.texi (Format Conversion Round-Trip): - Use active voice for previous change. - -2008-11-25 Chong Yidong - - * os.texi (Processor Run Time): - * processes.texi (Transaction Queues): - * markers.texi (The Mark): - * windows.texi (Choosing Window, Selecting Windows): - * files.texi (Changing Files, Magic File Names): - * commands.texi (Key Sequence Input): - * functions.texi (Declaring Functions): - * strings.texi (Predicates for Strings): - * intro.texi (nil and t): Fix typos (pointed out by Drew Adams). - -2008-11-24 Chong Yidong - - * help.texi (Accessing Documentation): Update example. - - * variables.texi (Defining Variables): Note that `*' is not - necessary if defcustom is used. - -2008-11-22 Eli Zaretskii - - * elisp.texi (Top): Remove "Chars and Bytes" and "Splitting - Characters" from @detailmenu. - - * nonascii.texi (Character Codes, Character Sets) - (Scanning Charsets, Translation of Characters): Update for Emacs 23. - (Chars and Bytes, Splitting Characters): Sections removed. - -2008-11-22 Lute Kamstra - - * positions.texi (Text Lines): Update goto-line documentation. - -2008-11-21 Martin Rudalics - - * frames.texi (Frames): Fix typo, add cross references, reword. - (Initial Parameters): Reword special-display-frame-alist text. - (Frames and Windows): Reword. Describe argument norecord for - set-frame-selected-window. - (Input Focus): Describe argument norecord for select-frame. - Remove comment on MS-Windows behavior for focus-follows-mouse. - (Raising and Lowering): Mention windows-frames dichotomy in - metaphor. - - * windows.texi (Displaying Buffers, Vertical Scrolling) - (Horizontal Scrolling): Fix indenting and rewording issues - introduced with 2008-11-07 change. - -2008-11-20 Glenn Morris - - * files.texi (Format Conversion Round-Trip): Mention `preserve' - element of `format-alist'. - -2008-11-19 Glenn Morris - - * doclicense.texi: Update to FDL 1.3. - * elisp.texi, vol1.texi, vol2.texi: Relicense under FDL 1.3 or later. - -2008-11-18 Chong Yidong - - * windows.texi (Window Hooks): Remove *-end-trigger-functions - vars, which are obsolete. Mention jit-lock-register. - - * modes.texi (Other Font Lock Variables): Document - jit-lock-register and jit-lock-unregister. - - * frames.texi (Color Parameters): Document alpha parameter. - -2008-11-16 Martin Rudalics - - * windows.texi (Splitting Windows, Deleting Windows) - (Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Choosing Window) - (Dedicated Windows, Window Point, Window Start and End) - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling) - (Size of Window, Resizing Windows, Window Configurations) - (Window Parameters): Avoid @var at beginning of sentences and - reword accordingly. - -2008-11-11 Lute Kamstra - - * files.texi (File Name Components): Fix file-name-extension - documentation. - -2008-11-11 Juanma Barranquero - - * frames.texi (Basic Parameters): Remove display-environment-variable - and term-environment-variable. - -2008-11-08 Eli Zaretskii - - * windows.texi (Basic Windows, Splitting Windows) - (Deleting Windows, Selecting Windows, Cyclic Window Ordering) - (Buffers and Windows, Displaying Buffers, Dedicated Windows) - (Resizing Windows, Window Configurations, Window Parameters): - Fix wording and markup. - -2008-11-07 Martin Rudalics - - * windows.texi (Windows): Update entries. - (Basic Windows): Remove listing of attributes. Reword. - (Splitting Windows, Deleting Windows): Reword. - (Selecting Windows, Cyclic Window Ordering): Reword with special - emphasis on order of recently selected windows and buffer list. - (Buffers and Windows, Choosing Window): Reword with special - emphasis on dedicated windows. - (Displaying Buffers): Reword. For switch-to-buffer mention that - it may fall back on pop-to-buffer. For other-window try to - explain how it treats the cyclic ordering of windows. - (Dedicated Windows): New node and section discussing dedicated - windows and associated functions. - (Window Point): Add entry for window-point-insertion-type. Reword. - (Window Start and End): Rename node and section title. Reword. - (Textual Scrolling, Vertical Scrolling, Horizontal Scrolling): - Minor rewording. - (Size of Window): Reword, in particular text on window-width. - (Resizing Windows): Reword. Add text on balancing windows. - (Window Configurations): Reword. Mention window parameters. - (Window Parameters): New node and section on window parameters. - (Window Hooks): Reword. Mention that - window-configuration-change-hook is run "buffer-locally". - * elisp.texi (Top): Update Windows entries in @detailmenu - section. - -2008-11-04 Juanma Barranquero - - * searching.texi (Regexp Search): Fix typo. - -2008-11-03 Seweryn Kokot (tiny change) - - * searching.texi (Regexp Search): Document GREEDY arg. - (Simple Match Data): Fix return value. - -2008-11-01 Eli Zaretskii - - * nonascii.texi (Text Representations): Rewrite to make consistent - with Emacs 23 internal representation of characters. Document - `unibyte-string'. - -2008-10-28 Chong Yidong - - * processes.texi (Process Information): Note that process-status - does not accept buffer names. - -2008-10-27 Seweryn Kokot (tiny change) - - * positions.texi (Skipping Characters): Correct return value of - skip-chars-forward. - -2008-10-25 Martin Rudalics - - * windows.texi (Deleting Windows): Update documentation of - delete-windows-on. - (Buffers and Windows): Update documentations of - get-buffer-window and get-buffer-window-list. - (Displaying Buffers): Update documentation of - replace-buffer-in-windows. - - * buffers.texi (Current Buffer): Reword set-buffer and - with-current-buffer documentations. - (Creating Buffers): Reword documentation of get-buffer-create. - -2008-10-23 Martin Rudalics - - * buffers.texi (Current Buffer): Reword documentation of - set-buffer. - (Buffer Names): Reword documentation of buffer-name. - (The Buffer List): For bury-buffer explain what happens with the - buffer's window. - (Creating Buffers): Say that get-buffer-create's arg is called - buffer-or-name. - -2008-10-22 Chong Yidong - - * advice.texi (Computed Advice): Explain what DEFINITION is. - - * nonascii.texi (Character Codes): Remove obsolete function - char-valid-p, and document characterp instead. - -2008-10-22 Martin Rudalics - - * windows.texi (Displaying Buffers): Reword documentation of - pop-to-buffer. - (Choosing Window): Rewrite documentation of display-buffer and - its options. - - * buffers.texi (Killing Buffers): Update documentation of - kill-buffer. - -2008-10-21 Eli Zaretskii - - * processes.texi (Serial Ports): Fix wording and improve markup. - - * searching.texi (Regexp Search): Document `string-match-p' and - `looking-at-p'. - (POSIX Regexps): Add an xref for "non-greedy". - (Regexp Special): Add @cindex entry for "non-greedy". - - * display.texi (Attribute Functions): Document `face-all-attributes'. - (Image Cache) : Minor wording fixes. - - * frames.texi (Color Names): Add an xref to `read-color'. - - * minibuf.texi (High-Level Completion): Document `read-color'. - - * elisp.texi (Top): Add "Swapping Text" to @detailmenu. - - * positions.texi (Narrowing): Add an xref to "Swapping Text". - - * buffers.texi (Swapping Text): New section, documents - `buffer-swap-text'. - -2008-10-21 Martin Rudalics - - * windows.texi (Resizing Windows): Minor wording fix. - -2008-10-20 Eli Zaretskii - - * processes.texi (Shell Arguments): Document `split-string-and-unquote' - and `combine-and-quote-strings'. - - * strings.texi (Creating Strings): Add xrefs for them. - -2008-10-19 Eli Zaretskii - - * elisp.texi (Top): Make descriptive text for "Reading File Names" - match the corresponding menu in minibuf.texi. - - * minibuf.texi (Reading File Names): Document `read-shell-command' - and `minibuffer-local-shell-command-map'. - -2008-10-19 Martin Rudalics - - * windows.texi (Resizing Windows): Remove var{} around "window" in - documentation of enlarge-window. - Rewrite documentation of window-min-height and window-min-width. - -2008-10-19 Eli Zaretskii - - * functions.texi (Calling Functions): Document `apply-partially'. - - * hooks.texi (Standard Hooks): Mention - `before-hack-local-variables-hook' and `hack-local-variables-hook'. - - * variables.texi (File Local Variables): Document - `file-local-variables-alist', `before-hack-local-variables-hook' - and `hack-local-variables-hook'. - - * processes.texi (Synchronous Processes): Document `process-lines'. - - * customize.texi (Variable Definitions): Document - `custom-reevaluate-setting'. - -2008-10-18 Martin Rudalics - - * windows.texi (Choosing Window, Deleting Windows) - (Displaying Buffers): Expand documentation of dedicated windows. - -2008-10-18 Eli Zaretskii - - * files.texi (Changing Files): Document symbolic input of file - modes to `set-file-modes'. Document `read-file-modes' and - `file-modes-symbolic-to-number'. - - * maps.texi (Standard Keymaps): Document `multi-query-replace-map' - and `search-map'. - - * searching.texi (Search and Replace): Document - `replace-search-function' and `replace-re-search-function'. - Document `multi-query-replace-map'. - - * minibuf.texi (Text from Minibuffer): Document `read-regexp'. - (Completion Commands, Reading File Names): Rename - `minibuffer-local-must-match-filename-map' to - `minibuffer-local-filename-must-match-map'. - (Minibuffer Completion): The `require-match' argument to - `completing-read' can now have the value `confirm-only'. - - * windows.texi (Displaying Buffers): Minor wording fix. - (Choosing Window): `split-height-threshold' can now be nil. - Document `split-width-threshold'. `pop-up-frames' can have the - value `graphic-only'. - -2008-10-17 Eli Zaretskii - - * os.texi (Startup Summary): Document `before-init-time' and - `after-init-time'. Document `initial-window-system' and - `window-system-initialization-alist'. Document reading the - abbrevs file. Document the call to `server-start' under --daemon. - Rearrange a bit to be consistent with the code flow. - (Processor Run Time): Document `emacs-uptime' and `emacs-init-time'. - (Time Parsing): Document `format-seconds'. - -2008-10-17 Martin Rudalics - - * windows.texi (Basic Windows, Splitting Windows): Fix whitespace - and reword. - -2008-10-16 Eli Zaretskii - - * markers.texi (The Mark): Document use-region-p. - -2008-10-15 Eli Zaretskii - - * internals.texi (Writing Emacs Primitives): The interactive spec - of a primitive can be a Lisp form. - - * markers.texi (The Mark): Document the `lambda' and `(only . OLD)' - values of transient-mark-mode. Document handle-shift-selection. - - * commands.texi (Using Interactive, Interactive Codes): Document `^'. - (Interactive Examples): Show an example of `^'. - (Key Sequence Input): Document this-command-keys-shift-translated. - (Defining Commands, Using Interactive): The interactive-form of a - function can be added via its symbol's property. - - * positions.texi (List Motion): beginning-of-defun-function can - now accept an argument. - - * text.texi (Low-Level Kill Ring): interprogram-paste-function can - now return a list of strings. - - * control.texi (Handling Errors): Document ignore-errors. - - * frames.texi (Creating Frames): Document frame-inherited-parameters. - (Parameter Access): Document set-frame-parameter. - - * variables.texi (Creating Buffer-Local): Add an xref to "Setting - Hooks" for the effect of kill-all-local-variables on local hook - functions. - - * modes.texi (Major Mode Conventions, Mode Line Variables): - `mode-name' need not be a string. xref to "Mode Line Data" for - details, and to "Emulating Mode Line" for computing a string - value. - -2008-10-14 Eli Zaretskii - - * processes.texi (System Processes): New section. - (Processes, Signals to Processes): Add xrefs to it. - - * objects.texi (Editing Types): A `process' is a subprocess of - Emacs, not just any process running on the OS. - - * elisp.texi (Top): Adjust the @detailmenu for the above two - changes. - - * sequences.texi (Char-Tables): Remove documentation of - set-char-table-default, which has no effect since Emacs 23. - : Don't mention generic - characters and charsets. Add a cons cell as a possible argument. - - * nonascii.texi (Splitting Characters) - (Translation of Characters): Don't mention generic characters. - - * display.texi (Fontsets): Don't mention generic characters. - - * sequences.texi (Char-Tables): `map-char-table' can now call its - argument FUNCTION with a cons cell as KEY. - -2008-10-13 Eli Zaretskii - - * objects.texi (Primitive Function Type): Move "@cindex special - forms" from here... - - * eval.texi (Special Forms): ...to here. - - * functions.texi (What Is a Function): `functionp' returns nil for - special forms. Add an xref. - - * elisp.texi (Top): Add a @detailmenu entry for "Frame-Local - Variables". - - * variables.texi (Frame-Local Variables): New section. - (Buffer-Local Variables): Add an xref to it. - (Intro to Buffer-Local, Creating Buffer-Local): A variable cannot - have both frame-local and buffer-local binding. - - * frames.texi (Frames): Mention multiple tty frames. - (Frame Parameters, Parameter Access): Mention frame-local variable - bindings. - -2008-09-20 Glenn Morris - - * display.texi (Defining Faces): Recommend against face variables. - -2008-09-16 Juanma Barranquero - - * display.texi (Echo Area Customization): Fix typo. - -2008-09-09 Juanma Barranquero - - * loading.texi (Where Defined): Add `defface' item. - -2008-09-06 Martin Rudalics - - * loading.texi (Where Defined): Fix description of symbol-file. - -2008-08-26 Jason Rumney - - * display.texi (TIFF Images): New section describing :index property. - -2008-08-23 Chong Yidong - - * display.texi (Temporary Displays): Remove unnecessary comment - about usage of temp-buffer-show-hook. - -2008-08-05 Chong Yidong - - * symbols.texi (Other Plists): Fix incorrect example. - Suggested by Florian Beck. - -2008-07-31 Juanma Barranquero - - * os.texi: Fix previous change. - -2008-07-31 Dan Nicolaescu - - * os.texi: - * intro.texi: - * files.texi: Remove VMS support. - -2008-07-27 Dan Nicolaescu - - * os.texi: - * frames.texi: - * display.texi: Remove mentions of Mac Carbon. - -2008-07-01 Miles Bader - - * text.texi (Special Properties): - * display.texi (Truncation): Add wrap-prefix and line-prefix. - -2008-06-28 Johan Bockgård - - * display.texi (Other Image Types): Fix copy/paste error; say - "PBM", not "XBM". - -2008-06-26 Dan Nicolaescu - - * os.texi: Remove references to obsolete systems. - -2008-06-20 Eli Zaretskii - - * makefile.w32-in (distclean): Remove makefile. - -2008-06-17 Glenn Morris - - * Makefile.in (emacsver, miscmanualdir, VERSION, manual, install) - (elisp, dist): Remove rules and variables that are obsolete now - the lisp manual is no longer distributed separately. - -2008-06-16 Glenn Morris - - * configure, configure.in, mkinstalldirs: Remove unused files. - - * book-spine.texinfo: Set version to 23.0.60. - * vol1.texi (EMACSVER): - * vol2.texi (EMACSVER): Set to 23.0.60. - - * elisp.texi, vol1.texi, vol2.texi: Update Back-Cover Text - as per maintain.info. - -2008-06-15 Glenn Morris - - * makefile.w32-in (manual): Use "23" rather than "21". - - * Makefile.in (emacsver): New, set by configure. - (manual): Use emacsver. - - * intro.texi: Report bugs using M-x report-emacs-bug. - - * elisp.texi (EMACSVER): Remove duplicate, outdated setting. - -2008-06-13 Daniel Engeler - - * elisp.texi, internals.texi, processes.texi: Add documentation - about serial port access. - -2008-06-05 Miles Bader - - * display.texi (Displaying Faces): Update to reflect function - renamings in face-remap.el. - -2008-06-05 Juanma Barranquero - - * display.texi (Fontsets): Fix typos. - -2008-06-03 Miles Bader - - * display.texi (Displaying Faces): Add add-relative-face-remapping, - remove-relative-face-remapping, set-base-face-remapping, - and set-default-base-face-remapping. - -2008-06-01 Miles Bader - - * display.texi (Displaying Faces): Add face-remapping-alist. - -2008-05-30 Stefan Monnier - - * tips.texi (Coding Conventions): Do not encourage the use of "-flag" - variable names. - -2008-05-03 Eric S. Raymond - - * keymaps.texi: Clarify that (current-local-map) and - (current-global-map) return references, not copies. - -2008-05-02 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Document a list of - default values for `read-from-minibuffer'. - -2008-04-24 Juanma Barranquero - - * nonascii.texi (Translation of Characters): Fix previous change. - -2008-04-20 Chong Yidong - - * display.texi (Overlay Properties): Clarify role of underlying - textprop and overlay keymaps for display strings. - - * keymaps.texi (Active Keymaps): Ditto. - -2008-04-19 Stefan Monnier - - * minibuf.texi (Programmed Completion): - Replace dynamic-completion-table with the new completion-table-dynamic. - -2008-04-07 Chong Yidong - - * intro.texi (Some Terms): Change "fonts in this manual" index - entry to "typographic conventions". - -2008-04-05 Eli Zaretskii - - * objects.texi (Text Props and Strings): Add indexing for read - syntax of text properties. - -2008-03-25 Stefan Monnier - - * processes.texi (Decoding Output): Remove process-filter-multibyte - functions. - -2008-03-15 Martin Rudalics - - * display.texi (Finding Overlays): Say that empty overlays at - the end of the buffer are reported too. - -2008-03-13 Glenn Morris - - * elisp.texi (EMACSVER): Set to 23.0.60. - -2008-02-26 Chong Yidong - - * strings.texi (Formatting Strings): Treat - and 0 as flag characters. - -2008-02-22 Glenn Morris - - * frames.texi (Position Parameters): Clarify the description of - `left' and `top', using information from "Geometry". - (Geometry): Give a pointer to "Position Parameters", rather than - repeating information. - -2008-02-11 Glenn Morris - - * objects.texi (Equality Predicates): No longer talk about "two" - functions. - -2008-02-11 Lawrence Mitchell (tiny change) - - * objects.texi (Equality Predicates): Add defun for - equal-including-properties. - -2008-02-10 Glenn Morris - - * objects.texi (Equality Predicates): - Mention equal-including-properties. - -2008-02-07 Richard Stallman - - * windows.texi (Window Start): Mention the feature of moving - window-start to start of line. - -2008-02-07 Jan Djärv - - * keymaps.texi (Tool Bar): Document rtl property. - -2008-01-27 Thien-Thi Nguyen - - * display.texi (Button Types): - For define-button-type, clarify type of NAME. - -2008-01-19 Martin Rudalics - - * buffers.texi (Buffer Modification): Fix typo. - -2008-01-06 Dan Nicolaescu - - * os.texi (System Environment): Remove references to OSes that are - not supported anymore. - -2008-01-05 Dan Nicolaescu - - * os.texi (System Environment): Remove mention for Masscomp. - -2008-01-04 Richard Stallman - - * display.texi (Faces): Don't talk about internal face vector as arg - to facep. - - * customize.texi (Type Keywords): Fix previous change. - - * text.texi (Links and Mouse-1): Fix xref for commands.texi change. - * elisp.texi (Top): Fix menu for commands.texi change. - -2007-12-30 Richard Stallman - - * commands.texi (Accessing Mouse): Renamed from Accessing Events. - (Accessing Scroll): New node broken out of Accessing Mouse. - -2007-12-28 Richard Stallman - - * frames.texi (Size Parameters): Fix typo. - (Basic Parameters): For `title', refer to title bar. - (Size and Position): Explain meaning of frame pixel width and height. - -2007-12-23 Richard Stallman - - * customize.texi (Type Keywords): Uncomment :validate and clarify it. - Improve some of the commented-out keywords' text too. - -2007-12-14 Martin Rudalics - - * nonascii.texi (Encoding and I/O): Reword to avoid saying - "visit the current buffer". - - * os.texi (System Interface): Fix typo. - -2007-12-04 Richard Stallman - - * objects.texi (Symbol Type): Fix typo. - -2007-12-03 Richard Stallman - - * hooks.texi (Standard Hooks): Add link to Hooks for Loading. - -2007-12-01 Glenn Morris - - * functions.texi (Declaring Functions): Improve previous change. - -2007-11-30 Glenn Morris - - * functions.texi (Declaring Functions): Add optional fourth - argument of declare-function, and setting third argument to `t'. - -2007-11-29 Richard Stallman - - * customize.texi (Composite Types): Document `group' type. - -2007-11-29 Glenn Morris - - * functions.texi (Declaring Functions): Add findex. Mention - `external' files. - -2007-11-26 Juanma Barranquero - - * functions.texi (Declaring Functions): Fix directive. - -2007-11-25 Richard Stallman - - * help.texi (Help Functions): Clean up last change. - - * advice.texi (Preactivation, Activation of Advice): Minor cleanup. - - * loading.texi (Named Features): Minor cleanup. - - * macros.texi (Eval During Expansion): Minor cleanup. - - * variables.texi (Variable Aliases): Minor cleanup. - -2007-11-24 Richard Stallman - - * functions.texi (Declaring Functions): Clarify previous change. - - * compile.texi (Compiler Errors): Clarify previous change. - -2007-11-24 Richard Stallman - - * display.texi (Refresh Screen, Forcing Redisplay): - Clarify the text and move items around. - -2007-11-24 Glenn Morris - - * functions.texi (Declaring Functions): New section. - * compile.texi (Compiler Errors): Mention declaring functions, - defvar with no initvalue, and byte-compile-warnings. - -2007-11-15 Martin Rudalics - - * vol1.texi (Top): Remove Frame-Local Variables from Node Listing. - * vol2.texi (Top): Remove Frame-Local Variables from Node Listing. - -2007-11-13 Martin Rudalics - - * help.texi (Help Functions): Document new macro `with-help-window'. - -2007-11-10 Paul Pogonyshev - - * searching.texi (Replacing Match): Describe new - `match-substitute-replacement'. - -2007-10-31 Richard Stallman - - * strings.texi (Creating Strings): Null strings from concat not unique. - -2007-10-26 Richard Stallman - - * objects.texi (Equality Predicates): Null strings are uniquified. - - * minibuf.texi: Minor clarifications in previous change. - -2007-10-25 Glenn Morris - - * customize.texi (Variable Definitions): Add :risky and :safe keywords. - -2007-10-24 Richard Stallman - - * elisp.texi (Top): Delete Frame-Local Variables from subnode menu. - - * variables.texi (Frame-Local Variables): Node deleted. - (Variables): Delete Frame-Local Variables from menu. - (Local Variables, Buffer-Local Variables, Intro to Buffer-Local) - (Default Value): Don't mention frame-local vars. - - * os.texi (Idle Timers): current-idle-time returns nil if not idle. - - * loading.texi (Unloading): Document FEATURE-unload-function - instead of FEATURE-unload-hook. - - * frames.texi (Multiple Displays): Don't mention frame-local vars. - -2007-10-22 Juri Linkov - - * minibuf.texi (Text from Minibuffer, Minibuffer Completion) - (High-Level Completion): Document a list of default value strings - in the DEFAULT argument, for which minibuffer functions return the - first element. - -2007-10-17 Juri Linkov - - * text.texi (Filling): Update arguments of fill-paragraph. - fill-paragraph operates on the active region in Transient Mark mode. - Remove fill-paragraph-or-region. - -2007-10-13 Karl Berry - - * elisp.texi (@dircategory): Move to after @copying, - since we want @copying as close as possible to the beginning of - the output. - -2007-10-12 Richard Stallman - - * elisp.texi (Top): Add Distinguish Interactive to subnode menu. - - * commands.texi (Distinguish Interactive): New node, - broken out from Interactive Call and rewritten. - (Command Loop): Put Distinguish Interactive in menu. - -2007-10-09 Richard Stallman - - * text.texi (Examining Properties): Mention overlay priority. - - * display.texi (Display Margins): Correct the description - of margin display specifications. - (Replacing Specs): New subnode broken out of Display Property. - -2007-10-06 Juri Linkov - - * text.texi (Filling): Document fill-paragraph-or-region. - -2007-10-05 Juanma Barranquero - - * display.texi (Auto Faces): Fix typo. - -2007-10-02 Richard Stallman - - * display.texi (Display Property): Explain some display specs - don't let you move point in. - - * frames.texi (Cursor Parameters): Describe - cursor-in-non-selected-windows here. Explain more values. - - * windows.texi (Basic Windows): Don't describe - cursor-in-non-selected-windows here. - -2007-10-01 Eli Zaretskii - - * processes.texi (Misc Network): Note that these functions are - supported only on some systems. - -2007-10-01 Richard Stallman - - * display.texi (Overlay Properties): Explain nil as priority. - Explain that conflicts are unpredictable if not resolved by - priorities. - -2007-09-23 Richard Stallman - - * macros.texi (Backquote): Minor clarification. - -2007-09-19 Richard Stallman - - * display.texi (Display Property): Explain multiple display specs. - Clarify when they work in parallel and when one overrides. - Fix error in example. - -2007-09-06 Glenn Morris - - Move from lispref/ to doc/lispref/. Change all setfilename - commands to use ../../info. - * Makefile.in (infodir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - (miscmanualdir): New. - (dist): Use new variable miscmanualdir. - * makefile.w32-in (infodir, texinputdir): Go up one more level. - (usermanualdir): Change from ../man to ../emacs. - -2007-08-30 Martin Rudalics - - * commands.texi (Command Loop Info): Advise against changing - most variables described here. Explain new variable - last-repeatable-command. - -2007-08-29 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 23.0.50. - -2007-08-29 Dan Nicolaescu - - * frames.texi (Basic Parameters): Add display-environment-variable - and term-environment-variable. - -2007-08-28 Juri Linkov - - * display.texi (Image Formats, Other Image Types): Add SVG. - -2007-08-28 Juri Linkov - - * display.texi (Images): Move formats-related text to new node - "Image Formats". - (Image Formats): New node. - -2007-08-27 Richard Stallman - - * windows.texi (Window Configurations): Clarify what - a window configuration saves. - -2007-08-25 Richard Stallman - - * display.texi (Images): Delete redundant @findex. - -2007-08-16 Richard Stallman - - * processes.texi (Asynchronous Processes): Clarify - doc of start-file-process. - -2007-08-08 Martin Rudalics - - * modes.texi (Example Major Modes): Fix typo. - -2007-08-08 Glenn Morris - - * intro.texi (nil and t): Do not use `iff' in documentation. - - * tips.texi (Documentation Tips): Recommend against `iff'. - -2007-08-07 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-08-06 Martin Rudalics - - * windows.texi (Size of Window): Document window-full-width-p. - -2007-07-25 Glenn Morris - - * gpl.texi (GPL): Replace license with GPLv3. - - * Relicense all FSF files to GPLv3 or later. - -2007-07-24 Michael Albinus - - * processes.texi (Synchronous Processes): - Add `process-file-shell-command'. - (Asynchronous Processes): Mention restricted use of - `process-filter' and `process-sentinel' in - `start-file-process'. Add `start-file-process-shell-command'. - -2007-07-17 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - IDENTIFICATION for `file-remote-p'. - -2007-07-16 Richard Stallman - - * display.texi (Defining Faces): Fix previous change. - -2007-07-14 Richard Stallman - - * control.texi (Handling Errors): Document `debug' in handler list. - -2007-07-10 Richard Stallman - - * display.texi (Defining Faces): Explain C-M-x feature for defface. - -2007-07-09 Richard Stallman - - * files.texi (Magic File Names): Rewrite previous change. - -2007-07-08 Michael Albinus - - * files.texi (Magic File Names): Introduce optional parameter - CONNECTED for `file-remote-p'. - -2007-07-07 Michael Albinus - - * processes.texi (Asynchronous Processes): - * files.texi (Magic File Names): Add `start-file-process'. - -2007-06-27 Richard Stallman - - * files.texi (Format Conversion Piecemeal): Clarify - `after-insert-file-functions' calling convention. - -2007-06-27 Michael Albinus - - * files.texi (Magic File Names): Remove `dired-call-process'. - Add `process-file'. - -2007-06-27 Kenichi Handa - - * text.texi (Special Properties): Fix description about - `composition' property. - -2007-06-26 Kenichi Handa - - * nonascii.texi (Default Coding Systems): Document about the - return value `undecided'. - -2007-06-25 David Kastrup - - * keymaps.texi (Active Keymaps): Document new POSITION argument of - `current-active-maps'. - -2007-06-24 Karl Berry - - * elisp.texi, vol1.texi, vol2.texi: New Back-Cover Text. - -2007-06-15 Juanma Barranquero - - * display.texi (Overlay Arrow): Doc fix. - -2007-06-14 Karl Berry - - * anti.texi (Antinews): Typo. - -2007-06-14 Chong Yidong - - * display.texi (Image Cache): Document image-refresh. - -2007-06-12 Karl Berry - - * vol1.texi, vol2.texi, two-volume-cross-refs.txt: Update. - * two-volume.make: New file. - * .cvsignore: Ignore two-volume files. - -2007-06-12 Tom Tromey - - * os.texi (Init File): Document user-emacs-directory. - -2007-06-03 Nick Roberts - - * commands.texi (Click Events): Describe width and height when - object is nil. - -2007-05-30 Nick Roberts - - * commands.texi (Click Events): Layout more logically. Describe - width and height. - (Drag Events, Motion Events): Update to new format for position. - -2007-06-02 Richard Stallman - - * frames.texi (Color Parameters): Add xref to (emacs)Standard Faces. - -2007-06-02 Chong Yidong - - * Version 22.1 released. - -2007-06-01 Stefan Monnier - - * text.texi (Special Properties): Correct meaning of fontified face. - -2007-05-30 Richard Stallman - - * text.texi (Special Properties): Add link to Adjusting Point. - -2007-05-12 Richard Stallman - - * text.texi (Margins): indent-to-left-margin is not the default. - (Mode-Specific Indent): For indent-line-function, the default - is indent-relative. - - * modes.texi (Example Major Modes): Explain last line of text-mode - is redundant. - -2007-05-10 Richard Stallman - - * keymaps.texi (Scanning Keymaps): Update where-is-internal example. - - * help.texi (Keys in Documentation): Add reference to - Documentation Tips. - - * files.texi (Format Conversion): TO-FN gets three arguments. - - * modes.texi (Auto Major Mode): Document file-start-mode-alist. - -2007-05-10 Thien-Thi Nguyen - - * elisp.texi (Top): Remove "Saving Properties" from detailed menu. - * files.texi (Format Conversion): Expand intro; add menu. - (Format Conversion Overview, Format Conversion Round-Trip) - (Format Conversion Piecemeal): New nodes/subsections. - * hooks.texi: Xref "Format Conversion" , not "Saving Properties". - * text.texi (Text Properties): Remove "Saving Properties" from menu. - (Saving Properties): Delete node/subsection. - -2007-05-07 Karl Berry - - * elisp.texi (EMACSVER): Back to 22. - -2007-05-06 Richard Stallman - - * processes.texi (Accepting Output): Revert most of previous change. - -2007-05-05 Richard Stallman - - * processes.texi (Accepting Output): accept-process-output - uses microseconds, not milliseconds. But that arg is obsolete. - -2007-05-04 Karl Berry - - * elisp.texi (EMACSVER) [smallbook]: 22.1, not 22. - -2007-05-04 Eli Zaretskii - - * tips.texi (Documentation Tips): Rearrange items to place the - more important ones first. Add an index entry for hyperlinks. - -2007-05-03 Karl Berry - - * elisp.texi (\urlcolor, \linkcolor) [smallbook]: \Black for printing. - (EMACSVER) [smallbook]: 22 for printed version. - - * control.texi (Signaling Errors) : texinfo.tex is fixed, - so restore anchor to normal position after defun. Found by Kevin Ryde. - -2007-04-26 Glenn Morris - - * elisp.texi (EMACSVER): Increase to 22.1.50. - -2007-04-28 Karl Berry - - * elisp.texi: Improve line breaks on copyright page, - similar layout to emacs manual, 8.5x11 by default. - -2007-04-24 Richard Stallman - - * text.texi (Special Properties): Add xref to Overlay Properties. - - * display.texi (Overlay Properties): Add xref to Special Properties. - -2007-04-22 Richard Stallman - - * keymaps.texi (Extended Menu Items): Move the info about - format with cached keyboard binding. - -2007-04-21 Richard Stallman - - * text.texi (Special Properties): Clarify previous change. - - * files.texi (File Name Expansion): Clarify previous change. - - * display.texi (Attribute Functions): Fix example for - face-attribute-relative-p. - -2007-04-19 Kenichi Handa - - * text.texi (Special Properties): Document composition property. - -2007-04-19 Glenn Morris - - * files.texi (File Name Expansion): Mention "superroot". - -2007-04-15 Chong Yidong - - * frames.texi (Multiple Displays): Add note about "multi-monitor" - setups. - (Display Feature Testing): Note that display refers to all - physical monitors for multi-monitor setups. - -2007-04-14 Richard Stallman - - * lists.texi (Sets And Lists): Clarify `delete' examples. - Remove spurious xref to same node. - Clarify xref for add-to-list. - -2007-04-12 Nick Roberts - - * keymaps.texi (Format of Keymaps): Remove spurious ")" from - value of lisp-mode-map. - -2007-04-11 Karl Berry - - * anti.texi (Antinews): - * display.texi (Overlay Properties, Defining Images): - * processes.texi (Synchronous Processes, Sentinels): - * syntax.texi (Syntax Table Internals): - * searching.texi (Regexp Special): - * nonascii.texi (Default Coding Systems): - * text.texi (Special Properties): - * minibuf.texi (Basic Completion): Wording to improve breaks in - 8.5x11 format. - * elisp.texi (smallbook): New @set to more easily switch between - smallbook and 8.5x11. - -2007-04-11 Richard Stallman - - * text.texi (Lazy Properties): Minor fix. - -2007-04-08 Karl Berry - - * symbols.texi (Plists and Alists): Period after "vs" in index entries. - * macros.texi (Backquote): Downcase Backquote in index entries for - consistency. - -2007-04-08 Richard Stallman - - * text.texi (Adaptive Fill): Just describe default, - don't show it (since it contains non-ASCII chars). - -2007-04-07 Karl Berry - - * text.texi (Adaptive Fill) [@iftex]: Omit binary characters in - adaptive-fill-regexp's value, since they are not in the standard - TeX fonts. - -2007-04-07 Guanpeng Xu - - * display.texi (Defining Faces): Fix example. - -2007-04-07 Karl Berry - - * display.texi (Button Buffer Commands): Improve page break. - -2007-04-07 Richard Stallman - - * advice.texi (Activation of Advice): Remove redundant index entry. - - * backups.texi: Improve index entries. Remove redundant ones. - - * compile.texi (Byte Compilation): Improve index entry. - - * hash.texi (Creating Hash): Improve index entry. - - * symbols.texi (Definitions): Improve index entry. - - * edebug.texi: Improve index entries. Remove redundant/useless ones. - - * maps.texi (Standard Keymaps): Remove useless index entry. - - * help.texi (Documentation Basics): Remove redundant index entries. - - * customize.texi: Improve index entries. - Remove redundant/useless ones. - - * locals.texi (Standard Buffer-Local Variables): Clarify intro text. - - * streams.texi (Output Variables): Improve index entry. - - * abbrevs.texi (Abbrevs): Remove useless index entry. - - * macros.texi (Expansion): Remove useless index entry. - - * text.texi: Improve index entries. Remove redundant/useless ones. - (Text Properties, Examining Properties) - (Special Properties): Use "property category" instead of "category" - to refer to the `category' property. - - * positions.texi: Improve index entries. Remove useless one. - - * lists.texi: Improve index entries. Remove redundant/useless ones. - - * os.texi: Improve index entries. - (Timers): Fix previous change. - - * buffers.texi: Improve index entries. - (Modification Time): Get rid of term "obsolete buffer". - - * debugging.texi: Improve index entries. - (Test Coverage): Add xref to other test coverage ftr. - - * eval.texi: Improve index entry. Remove redundant ones. - - * numbers.texi: Improve index entries. Remove redundant/useless ones. - - * files.texi: Improve index entries. Remove redundant/useless ones. - - * objects.texi: Improve index entries. - - * processes.texi: Improve index entries. - - * modes.texi: Improve index entry. Remove redundant one. - - * nonascii.texi: Improve index entries. - - * internals.texi: Improve index entries. - - * syntax.texi: Improve index entries. - - * keymaps.texi (Active Keymaps): Improve index entries. - - * commands.texi: Improve index entries. Remove redundant/useless ones. - - * frames.texi: Improve index entries. Remove redundant/useless ones. - - * markers.texi: Improve index entries. Remove redundant ones. - - * tips.texi: Improve index entries. - - * loading.texi (Unloading): Improve index entry. - - * variables.texi: Improve index entries. Remove redundant one. - - * sequences.texi: Improve index entry. - - * display.texi: Improve index entries. Remove redundant ones. - - * windows.texi: Improve index entries. - - * searching.texi: Improve index entries. Remove redundant one. - - * strings.texi (Case Tables): Improve last change. - -2007-04-04 Chong Yidong - - * strings.texi (Case Tables): Document with-case-table and - ascii-case-table. - -2007-04-03 Karl Berry - - * processes.texi (Network): Reword to improve page break. - -2007-04-03 Eli Zaretskii - - * functions.texi (Inline Functions): Describe more disadvantages - of defsubst, and make advice against it stronger. - -2007-04-02 Karl Berry - - * backups.texi (Backup Names): Avoid widow words. - * modes.texi (Example Major Modes): Align last comment. - -2007-04-01 Chong Yidong - - * keymaps.texi (Remapping Commands): Document new arg to - command-remapping. - -2007-04-01 Karl Berry - - * processes.texi (Low-Level Network): Typo. - * loading.texi (Hooks for Loading): Avoid double "the". - * keymaps.texi (Key Sequences): No double "and". - (Changing Key Bindings): Shorten to improve line break. - -2007-03-31 Glenn Morris - - * os.texi (Timers): Fix description of run-at-time TIME formats. - -2007-03-31 Richard Stallman - - * display.texi (Invisible Text): Correct buffer-invisibility-spec - regarding ellipsis. - -2007-03-31 Eli Zaretskii - - * intro.texi (nil and t): - * symbols.texi (Plists and Alists): - * variables.texi (Variable Aliases, Constant Variables): - * functions.texi (Defining Functions): - * advice.texi (Advising Primitives): - * debugging.texi (Syntax Errors, Compilation Errors): - * minibuf.texi (Minibuffer Windows): - * commands.texi (Adjusting Point): - * modes.texi (Syntactic Font Lock, Faces for Font Lock) - (Auto Major Mode, Major Mode Conventions): - * help.texi (Describing Characters): - * files.texi (Create/Delete Dirs, Information about Files) - (File Locks, Writing to Files, Reading from Files) - (Saving Buffers): - * windows.texi (Resizing Windows, Cyclic Window Ordering): - * frames.texi (Finding All Frames): - * positions.texi (Buffer End, Motion): - * markers.texi (The Region): - * text.texi (Deletion, Near Point): - * display.texi (Displaying Messages, Truncation): - * os.texi (Processor Run Time): - * tips.texi (Key Binding Conventions, Programming Tips) - (Warning Tips, Documentation Tips, Comment Tips): - * internals.texi (Memory Usage): Improve indexing. - - * variables.texi (Frame-Local Variables): - * functions.texi (Argument List): - * loading.texi (Library Search): - * streams.texi (Output Variables): - * keymaps.texi (Translation Keymaps, Searching Keymaps): - * searching.texi (Replacing Match, Search and Replace): - * processes.texi (Byte Packing, Decoding Output) - (Accepting Output, Network Servers, Shell Arguments): - * display.texi (Abstract Display, Image Cache, Scroll Bars): - * windows.texi (Window Point, Window Start): - * frames.texi (Management Parameters, Frame Parameters, Frame Titles): - * commands.texi (Reading Input, Keyboard Events): - * minibuf.texi (Reading File Names, Minibuffer Completion) - (Recursive Mini): - * positions.texi (List Motion): - * hash.texi (Hash Tables, Creating Hash, Defining Hash): - * numbers.texi (Arithmetic Operations, Math Functions) - (Predicates on Numbers, Comparison of Numbers): - (Numeric Conversions): - * locals.texi (Standard Buffer-Local Variables): - * maps.texi (Standard Keymaps): - * os.texi (User Identification, System Environment, Recording Input) - (X11 Keysyms): - * nonascii.texi (Non-ASCII Characters, Splitting Characters): - * backups.texi (Backups and Auto-Saving): - * customize.texi (Customization, Group Definitions) - (Variable Definitions): - * compile.texi (Byte Compilation): Improve index entries. - -2007-03-31 Karl Berry - - * macros.texi (Defining Macros): Avoid widow syllable. - -2007-03-31 Eli Zaretskii - - * elisp.texi (Top): Postscript -> PostScript. - - * display.texi (Images, Postscript Images): Postscript -> PostScript. - -2007-03-31 Markus Triska - - * internals.texi (Writing Emacs Primitives): Untabify `For'. - -2007-03-30 Karl Berry - - * lists.texi (List-related Predicates): Remove spurious @need. - (Setcdr): Use @smallexample to improve page break. - (Association Lists) : Reword to improve page break. - - * strings.texi (String Conversion): Insert blank line to improve - page break. - - * numbers.texi (Random Numbers): Use @minus{}. - (Math Functions): Use @minus{}. - - * intro.texi (Acknowledgements): Avoid line breaks before middle - initials. - -2007-03-24 Eli Zaretskii - - * errors.texi (Standard Errors): Add an index entry. - -2007-03-19 Richard Stallman - - * os.texi (Recording Input): recent-keys now gives 300 keys. - -2007-03-12 Glenn Morris - - * os.texi: Replace "daylight savings" with "daylight saving" - throughout. - -2007-03-05 Richard Stallman - - * variables.texi (File Local Variables): Update - enable-local-variables values. - -2007-03-04 Richard Stallman - - * syntax.texi (Control Parsing): Minor clarification. - - * strings.texi (Formatting Strings): Clarify width, precision, flags. - - * sequences.texi (Sequence Functions): Move string-bytes away, - add xref. - - * nonascii.texi (Text Representations): Move string-bytes here. - - * modes.texi (Major Mode Conventions): Fundamental mode is exception. - - * minibuf.texi (Basic Completion): Minor clarification. - - * markers.texi (The Mark): Clarify existence vs activation of mark. - Other cleanup. - - * display.texi (Finding Overlays): Write better example. - - * compile.texi (Eval During Compile): Clarify putting macros - in eval-when-compile. - -2007-02-25 Vinicius Jose Latorre (tiny change) - - * loading.texi (How Programs Do Loading): Fix anchor position at - load-read-function definition doc. - -2007-02-21 Kim F. Storm - - * strings.texi (Text Comparison): Mention that assoc-string - converts symbols to strings before testing. - -2007-02-17 Kim F. Storm - - * processes.texi (Bindat Spec): Vector types can have optional - element type. - (Bindat Examples): Fix example. Add vector with element type. - -2007-02-16 Andreas Schwab - - * strings.texi (Formatting Strings): Document '+' flag. - -2007-02-15 Juanma Barranquero - - * strings.texi (Modifying Strings): Clarify that `clear-string' - always converts the string to unibyte. - -2007-02-14 Kim F. Storm - - * display.texi (Glyphs): Add make-glyph-code, glyph-char, glyph-face. - Rewrite glyph code description to refer to these functions. - Remove details of encoding face number and char into integer code. - -2007-02-03 Alan Mackenzie - - * loading.texi (Hooks for Loading): Make the description of - `eval-after-load' more detailed, and amend the description of - after-load-alist, in accordance with changes from 2006-05. - -2007-02-03 Chong Yidong - - * modes.texi (Defining Minor Modes): Document that a :require - keyword or similar may be required to make saved customization - variables work. - -2007-02-03 Eli Zaretskii - - * elisp.texi (Top): Make the detailed menu headers compliant with - Texinfo guidelines and with what texnfo-upd.el expects. Add - comments to prevent people from inadvertently modifying the key - parts needed by `texinfo-multiple-files-update'. - -2007-02-02 Eli Zaretskii - - * elisp.texi (Top): Update the top-level menus. - - * syntax.texi (Categories): Add index entries. - -2007-02-01 Juanma Barranquero - - * display.texi (Attribute Functions): Fix name and description of - the UNDERLINE arg of `set-face-underline-p'. - -2007-01-29 Eli Zaretskii - - * elisp.texi (Top): Add "Standard Errors", "Standard Buffer-Local - Variables", and "Standard Keymaps" to the detailed menu. - - * variables.texi (Future Local Variables): Add index entry. - -2007-01-28 Richard Stallman - - * tips.texi (Coding Conventions): Clarify the tip about macros - that define a function or a variable. - - * files.texi (File Attributes): UID and GID can be floats. - (Magic File Names): Explain why deferring all operations to - the standard handler does not work. - -2007-01-23 Martin Rudalics - - * backups.texi (Reverting): Use "buffer" instead of "file" - when talking about major and minor modes. - -2007-01-21 Richard Stallman - - * help.texi (Documentation): Add xref to Documentation Tips. - -2007-01-14 Juanma Barranquero - - * tips.texi (Coding Conventions): Fix typos. - -2007-01-05 Richard Stallman - - * modes.texi (Defining Minor Modes): Fix previous change. - -2007-01-03 Richard Stallman - - * customize.texi (Variable Definitions, Customization Types): - Don't use * in doc string for defcustom. - -2007-01-02 Richard Stallman - - * variables.texi (Variable Aliases): Clarify that aliases vars - always have the same value. - - * processes.texi (Bindat Spec): Fix Texinfo usage. - - * modes.texi (Defining Minor Modes): Explain effect of command - defined with define-global-minor-mode on new buffers. - -2006-12-30 Kim F. Storm - - * keymaps.texi (Tool Bar): Describe `grow-only' value of - `auto-resize-tool-bars'. - -2006-12-30 Richard Stallman - - * keymaps.texi (Active Keymaps): Fix previous change. - -2006-12-30 Nick Roberts - - * keymaps.texi (Active Keymaps): Make xref to lookup-key. - -2006-12-30 Kim F. Storm - - * processes.texi (Bindat Spec): Clarify using field names in - length specifications. - -2006-12-29 Kim F. Storm - - * processes.texi (Bindat Spec): Explain eval forms and lengths better. - Add count and index variables for eval forms in repeat blocks. - -2006-12-24 Richard Stallman - - * customize.texi (Variable Definitions): Document - new name custom-add-frequent-value. - -2006-12-19 Kim F. Storm - - * commands.texi (Misc Events): User signals now result in sigusr1 - and sigusr2 events which are handled through special-event-map. - (Special Events): User signals and drag-n-drop are special. - -2006-12-17 Richard Stallman - - * loading.texi (Named Features): Explain subfeatures better. - - * customize.texi: Use "option" only for user options. - For the keyword values inside defcustom etc, say "keywords". - For :options value's elements, say "elements". - :group should not be omitted. - - * syntax.texi (Parsing Expressions): Split up node. - (Motion via Parsing, Position Parse, Parser State) - (Low-Level Parsing, Control Parsing): New subnodes. - (Parser State): Document syntax-ppss-toplevel-pos. - - * positions.texi (List Motion): Punctuation fix. - - * files.texi (File Name Completion): Document PREDICATE arg - to file-name-completion. - -2006-12-16 Eli Zaretskii - - * internals.texi (Building Emacs, Writing Emacs Primitives): - Add index entries. - -2006-12-11 Richard Stallman - - * modes.texi (Font Lock Basics): Explain how nil for font-lock-defaults - affects face menu. Explain how to make it non-nil without enabling - any fontification. - -2006-12-10 Chong Yidong - - * modes.texi (Font Lock Basics): Document nil value of - font-lock-defaults. - -2006-12-10 Glenn Morris - - * abbrevs.texi (Defining Abbrevs): Mention `define-abbrev' 'force - value for system-flag argument. Abbrev tables may not be empty - when major modes are loaded. - -2006-12-08 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Partially revert last - change; delete "elisp-?" and "elisp-??" instead of "elisp-*" - to protect elisp-covers.texi. - -2006-12-07 Juanma Barranquero - - * makefile.w32-in (maintainer-clean): Depend on `distclean'. - Don't remove elisp* info files; they are already deleted by the - `clean' and `distclean' targets, and they are in the $(infodir) - directory, not the current one. - -2006-12-04 Kim F. Storm - - * commands.texi (Misc Events): Update signal events. - (Event Examples): Add signal example. - -2006-11-29 Richard Stallman - - * frames.texi (Visibility of Frames): Explain visible windows - can be covered by others. Add xref for raise-frame. - -2006-11-28 Richard Stallman - - * searching.texi (Regexp Special): Update when ^ is special. - -2006-11-27 Eli Zaretskii - - * customize.texi (Customization, Common Keywords) - (Group Definitions, Variable Definitions, Composite Types) - (Type Keywords, Customization Types): Add index entries for - various customization keywords. - -2006-11-23 Stefan Monnier - - * modes.texi (Multiline Font Lock): Rephrase some parts for clarity. - -2006-11-10 Jan Djärv - - * frames.texi (Window System Selections): Remove clipboard from - description of selection-coding-system. - -2006-11-06 Richard Stallman - - * lists.texi (List Variables): Document COMPARE-FN. - - * keymaps.texi: Avoid use of "binding" to mean a relation; - use it only to refer to the meaning associated with a key. - (Keymaps): Change menu node description. - - * elisp.texi (Top): Change menu node description. - - * display.texi (Managing Overlays): Document overlay-recenter. - -2006-10-29 Chong Yidong - - * Makefile.in: Use relative paths to avoid advertising filesystem - contents during compilation. - -2006-10-23 Kim F. Storm - - * commands.texi (Event Input Misc): Update unread-command-events. - -2006-10-23 Nick Roberts - - * lists.texi (Sets And Lists): Fix typos. - -2006-10-18 Juanma Barranquero - - * control.texi (Processing of Errors): Use @var for an argument, - not @code. - -2006-10-16 Richard Stallman - - * edebug.texi (Edebug Recursive Edit): Minor cleanup. - - * keymaps.texi (Format of Keymaps): Show all the keymap element - patterns that result from menu items. - (Key Lookup): Minor cleanups. - - * modes.texi (Precalculated Fontification): Don't say that - not setting font-lock-defaults avoids loading font-lock. - - * help.texi (Documentation): Move xref to Emacs Manual here. - (Documentation Basics): From here. - Also doc emacs-lisp-docstring-fill-column. - - * elisp.texi: Update version and ISBN. - - * commands.texi (Interactive Call): Clarify KEYS arg to - call-interactively is a vector. - (Command Loop Info): Delete anchor in this-command-keys. - Add anchor in this-command-keys-vector. - (Recursive Editing): Document how recursive-edit - handles the current buffer. - -2006-10-13 Chong Yidong - - * frames.texi (Frame Titles): %c and %l are ignored in - frame-title-format. - -2006-10-11 Richard Stallman - - * keymaps.texi (Key Sequences): Clarify use of kbd. - -2006-10-10 Kim F. Storm - - * lists.texi (Sets And Lists): Add memql. - -2006-10-03 Richard Stallman - - * searching.texi (Char Classes): Document :multibyte: and :unibyte:. - Clarify :ascii: and :nonascii:. - -2006-09-29 Juri Linkov - - * modes.texi (%-Constructs): Reorder coding systems in the - documentation of %z to the real order displayed in the modeline. - -2006-09-25 Richard Stallman - - * os.texi (Timers): Describe timer-max-repeats. - -2006-09-25 Chong Yidong - - * os.texi (Timers): Mention with-local-quit. - -2006-09-24 Richard Stallman - - * searching.texi (Searching and Matching): Mention property search. - - * commands.texi (Command Loop Info): Explain how read-event affects - this-command-keys. - -2006-09-20 Richard Stallman - - * os.texi (Timers): Clarify about REPEAT when timer is delayed. - - * windows.texi (Window Start): Minor cleanups. - -2006-09-20 Kim F. Storm - - * windows.texi (Window Start): pos-visible-in-window-p allows - specifying t for position to mean "end of window". - Add window-line-height. - - * anti.texi (Antinews): Mention window-line-height. - -2006-09-19 David Kastrup - - * keymaps.texi (Searching Keymaps): Small clarification. - -2006-09-18 Richard Stallman - - * keymaps.texi (Creating Keymaps): Explain that keymap prompt strings - cause keyboard menus. - (Menu Keymaps): Likewise. - (Defining Menus, Keyboard Menus): Clarify. - - * text.texi (Fields): Clarify explanation of constrain-to-field. - -2006-09-16 Eli Zaretskii - - * variables.texi (Tips for Defining): Fix a typo. - -2006-09-15 Richard Stallman - - * keymaps.texi (Remapping Commands, Searching Keymaps) - (Active Keymaps): Clean up previous change. - -2006-09-15 Jay Belanger - - * gpl.texi: Replace "Library Public License" by "Lesser Public - License" throughout. - -2006-09-15 David Kastrup - - * keymaps.texi (Active Keymaps): Adapt description to use - `get-char-property' instead `get-text-property'. Explain how - mouse events change this. Explain the new optional argument of - `key-binding' and its mouse-dependent lookup. - (Searching Keymaps): Adapt description similarly. - (Remapping Commands): Explain the new optional argument of - `command-remapping'. - -2006-09-14 Richard Stallman - - * keymaps.texi (Searching Keymaps): Clarification. - (Active Keymaps): Refer to Searching Keymaps instead of duplication. - -2006-09-13 Richard Stallman - - * objects.texi (Character Type): Node split. - Add xref to Describing Characters. - (Basic Char Syntax, General Escape Syntax) - (Ctl-Char Syntax, Meta-Char Syntax): New subnodes. - -2006-09-11 Richard Stallman - - * display.texi (Display Table Format): Wording clarification. - (Glyphs): Clarifications. - -2006-09-10 Chong Yidong - - * keymaps.texi (Active Keymaps): Mention that key-binding checks - local maps. - -2006-09-10 Kim F. Storm - - * display.texi (Forcing Redisplay): Document return value of - function redisplay. - -2006-09-09 Richard Stallman - - * windows.texi (Window Hooks): Explain limits of - window-scroll-functions. - - * display.texi (Fringe Indicators): Update for last change in - indicate-buffer-boundaries. - -2006-09-08 Richard Stallman - - * processes.texi (Bindat Spec): Suggest names ending in -bindat-spec. - -2006-09-06 Kim F. Storm - - * frames.texi (Display Feature Testing): display-mm-dimensions-alist. - - * windows.texi (Window Start): Update pos-visible-in-window-p. - -2006-09-04 Richard Stallman - - * processes.texi (Accepting Output): Explain SECONDS=0 for - accept-process-output. - - * os.texi (Idle Timers): Explain why timer functions should not - loop until (input-pending-p). - -2006-09-02 Eli Zaretskii - - * makefile.w32-in (usermanualdir): New variable. - (elisp.dvi): Use it. - -2006-09-01 Eli Zaretskii - - * buffers.texi (Buffer Modification): Fix last change. - -2006-09-01 Chong Yidong - - * buffers.texi (Buffer Modification): Document - buffer-chars-modified-tick. - -2006-08-31 Richard Stallman - - * modes.texi (Syntactic Font Lock): Mention specific faces once again. - -2006-08-31 Richard Bielawski (tiny change) - - * modes.texi (Syntactic Font Lock): - Mention font-lock-syntactic-face-function - instead of specific faces. - -2006-08-29 Chong Yidong - - * display.texi (Images): Add xrref to display-images-p. - -2006-08-28 Kenichi Handa - - * nonascii.texi (Lisp and Coding Systems): Fix description of - detect-coding-region. - -2006-08-27 Michael Olson - - * processes.texi (Transaction Queues): Remove stray quote - character. - -2006-08-25 Richard Stallman - - * os.texi (Idle Timers): run-with-idle-timer allows Lisp time value. - Add xref. - -2006-08-24 Chong Yidong - - * os.texi (Timers): Avoid waiting inside timers. - -2006-08-21 Lute Kamstra - - * Makefile.in: Use ../man/texinfo.tex to build elisp.dvi. - -2006-08-20 Richard Stallman - - * os.texi (Idle Timers): New node, split out from Timers. - Document current-idle-time. - * commands.texi (Reading One Event): Update xref. - * elisp.texi (Top): Update subnode menu. - -2006-08-16 Richard Stallman - - * keymaps.texi (Extended Menu Items): Show format of cached - bindings in extended menu items. - - * customize.texi (Variable Definitions): Explain when the - standard value expression is evaluated. - -2006-08-15 Chong Yidong - - * commands.texi (Reading One Event): Explain idleness in - `read-event'. - -2006-08-12 Chong Yidong - - * text.texi (Near Point): Say "cursor" not "terminal cursor". - (Commands for Insertion): Removed split-line since it's not - relevant for Lisp programming. - (Yank Commands): Rewrite introduction. - (Undo): Clarify. - (Maintaining Undo): Clarify. Document undo-ask-before-discard. - (Filling): Remove redundant comment. Clarify return value of - current-justification. - (Margins): Minor clarifications. - (Adaptive Fill): Update default value of adaptive-fill-regexp. - (Sorting): Update definition of sort-lines. - (Columns): Clarify behavior of sort-columns. - (Indent Tabs): Link to Tab Stops in Emacs manual. - (Special Properties): Clarify. - (Clickable Text): Mention Buttons package. - -2006-08-12 Kevin Ryde - - * os.texi (Time Parsing): Add %z to description of - format-time-string, as per docstring. Add cross reference to - glibc manual for strftime. - -2006-08-08 Richard Stallman - - * modes.texi: Clean up wording in previous change. - -2006-08-07 Chong Yidong - - * modes.texi (Hooks): Clarify. - (Major Mode Basics): Mention define-derived-mode explicitly. - (Major Mode Conventions): Rebinding RET is OK for some modes. - Mention change-major-mode-hook and after-change-major-mode-hook. - (Example Major Modes): Moved to end of Modes section. - (Mode Line Basics): Clarify. - (Mode Line Data): Mention help-echo and local-map in strings. - Explain reason for treatment of non-risky variables. - (Properties in Mode): Clarify. - (Faces for Font Lock): Add font-lock-negation-char-face. - -2006-08-04 Eli Zaretskii - - * strings.texi (Formatting Strings): Warn against arbitrary - strings as first arg to `format'. - -2006-07-31 Thien-Thi Nguyen - - * text.texi (Clickable Text): Mention `help-echo' text property. - Update intro, examples and associated explanations. - -2006-07-31 Richard Stallman - - * commands.texi: Update xrefs. - (Event Mod): New node, cut out from old Translating Input. - - * maps.texi: Update xrefs. - - * keymaps.texi (Translation Keymaps): New node. - Update xrefs from Translating Input to Translation Keymaps. - - * elisp.texi (Top): Update subnode menu. - - * display.texi (Face Functions): Fix explanations of FRAME=t or nil. - - * os.texi (System Interface): Fix menu descriptions of some nodes. - (Translating Input): Node deleted. - -2006-07-31 Nick Roberts - - * modes.texi (Minor Mode Conventions): Update xref for add-to-list. - - * lists.texi (Sets And Lists): Likewise. - -2006-07-30 Thien-Thi Nguyen - - * text.texi (Fields): Mention POS - requirement when narrowing is in effect. - -2006-07-28 Richard Stallman - - * display.texi (Face Attributes): Simplify wording. - (Attribute Functions): Clarify meaning of new-frame default - attribute settings. - - * customize.texi (Common Keywords): Document how to use - :package-version in a package not in Emacs. - -2006-07-28 Kim F. Storm - - * commands.texi (Reading One Event): Fix last change. - -2006-07-26 Chong Yidong - - * commands.texi (Reading One Event): Document SECONDS argument for - read-event, read-char, and read-char-exclusive. - -2006-07-25 Stefan Monnier - - * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline - to ensure correct identification. - -2006-07-24 Richard Stallman - - * text.texi (Clickable Text): Clarify. - - * sequences.texi (Vector Functions): Delete duplicate xref. - - * objects.texi (Function Type): Clarify. - - * modes.texi (Keymaps and Minor Modes): List punct chars for minor - modes. - - * lists.texi (List Variables): New node. - Material moved from other nodes. - - * variables.texi (Setting Variables): add-to-list and - add-to-ordered-list moved to List Variables node. - -2006-07-23 Thien-Thi Nguyen - - * text.texi (Links and Mouse-1): - For mouse-on-link-p, expand on arg POS. - -2006-07-21 Kim F. Storm - - * display.texi (Forcing Redisplay): Don't mention systems which - don't support sub-second timers for redisplay-preemption-period. - - * os.texi (Terminal Output): Clarify text vs graphical terminal. - -2006-07-21 Eli Zaretskii - - * frames.texi (Input Focus): Document that focus-follows-mouse has - no effect on MS-Windows. - -2006-07-18 Richard Stallman - - * display.texi (Forcing Redisplay): Cleanups in previous change. - - * processes.texi (Low-Level Network): Make menu more convenient. - -2006-07-18 Kim F. Storm - - * display.texi (Forcing Redisplay): redisplay-preemption-period - only used on window systems. Add xref to Terminal Output. - - * os.texi (Terminal Output): baud-rate only controls preemption on - non-window systems. Add xref to Forcing Redisplay. - - * processes.texi (Low-Level Network): Rename node "Make Network" - to "Network Processes". - -2006-07-18 Karl Berry - - * variables.texi, functions.texi, customize.texi, loading.texi: - * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. - -2006-07-17 Chong Yidong - - * commands.texi (Waiting): Document batch-mode sit-for behavior. - -2006-07-17 Richard Stallman - - * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. - Put period and comma inside quotes. - - * loading.texi, markers.texi: Use real doublequote inside menus. - - * windows.texi: Put point and comma inside quotes. - (Textual Scrolling): Use @samp for error message. - - * variables.texi, tips.texi, syntax.texi, symbols.texi: - * strings.texi, streams.texi, processes.texi, os.texi: - * objects.texi, numbers.texi, modes.texi, minibuf.texi: - * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: - * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: - * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: - Put point and comma inside quotes. - - * control.texi (Processing of Errors): Add command-error-function. - - * variables.texi (File Local Variables): Clarify that - file local variables make buffer-local bindings. - - * modes.texi (Syntactic Font Lock): Give default for - font-lock-syntax-table. - -2006-07-17 Nick Roberts - - * text.texi (Special Properties): Clean up previous change. - -2006-07-16 Karl Berry - - * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: - * control.texi: Fix bad page breaks through chapter 10 (control). - - * anti.texi (Antinews): Reorder face-attribute fns to avoid - underfull hbox. - -2006-07-15 Nick Roberts - - * text.texi (Special Properties): Describe fontified text property - in relation to a character (not text). - -2006-07-15 Kim F. Storm - - * maps.texi (Standard Keymaps): Add xref for minibuffer maps. - Add apropos-mode-map, custom-mode-map, esc-map, global-map, - grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. - - * anti.texi (Antinews): Mention redisplay function. - The kbd macro existed, but was not documented, before 22.x. - Function pos-visible-in-window-p is not new in 22.x, just enhanced. - -2006-07-14 Nick Roberts - - * display.texi (Displaying Messages): Add anchor. - - * frames.texi (Dialog Boxes): Use it. - -2006-07-12 Richard Stallman - - * objects.texi (Frame Type): Explain nature of frames better. - - * frames.texi (Frames): Explain nature of frames better. - -2006-07-12 Ken Manheimer - - * tips.texi (Coding Conventions): Explain why use cl at compile time. - -2006-07-12 YAMAMOTO Mitsuharu - - * frames.texi (Window System Selections): Mention scrap support for Mac. - Default value of x-select-enable-clipboard is t on Mac. - - * os.texi (Getting Out): Suspending is not allowed on Mac, either. - -2006-07-11 Kim F. Storm - - * display.texi (Forcing Redisplay): Add `redisplay' function. - Don't mention (sit-for -1) -- use (redisplay t) instead. - - * commands.texi (Waiting): (sit-for -1) is no longer special. - (sit-for 0) is equivalent to (redisplay). - Iconifying/deiconifying no longer makes sit-for return. - -2006-07-10 Nick Roberts - - * display.texi (Buttons): Fix typo. - - * index.texi, elisp.texi (New Symbols): Comment node out. - -2006-07-09 Richard Stallman - - * display.texi (Truncation): Clean up previous change. - -2006-07-08 Richard Stallman - - * commands.texi (Interactive Call): Use 3 as prefix in example - for execute-extended-command. - - * display.texi (Attribute Functions): Move paragraph about - compatibility with Emacs < 21. - -2006-07-09 Kim F. Storm - - * display.texi (Refresh Screen): Clarify force-window-update. - (Truncation): "Normally" indicated by fringe arrows. - -2006-07-08 Eli Zaretskii - - * windows.texi (Textual Scrolling, Resizing Windows): - * variables.texi (Constant Variables): - * text.texi (Buffer Contents, Deletion, Changing Properties) - (Property Search, Special Properties, Sticky Properties) - (Links and Mouse-1, Fields, Change Hooks): - * syntax.texi (Syntax Table Functions, Parsing Expressions) - (Categories): - * symbols.texi (Other Plists): - * streams.texi (Output Variables): - * processes.texi (Input to Processes, Query Before Exit): - * positions.texi (Word Motion, Text Lines, List Motion): - * os.texi (Init File, System Environment, Sound Output) - (Session Management): - * nonascii.texi (Text Representations, Character Sets) - (Chars and Bytes, Locales): - * modes.texi (Defining Minor Modes, Header Lines): - * minibuf.texi (Minibuffer Contents): - * markers.texi (Information from Markers): - * lists.texi (List Elements, Building Lists, Association Lists): - * keymaps.texi (Tool Bar): - * hash.texi (Creating Hash, Hash Access, Defining Hash, Other Hash): - * functions.texi (What Is a Function, Mapping Functions): - * frames.texi (Creating Frames, Parameter Access, Pointer Shape) - (Color Names, Text Terminal Colors, Display Feature Testing): - * files.texi (Visiting Functions, File Name Components) - (Unique File Names, Contents of Directories): - * display.texi (Forcing Redisplay, Displaying Messages) - (Temporary Displays, Font Selection, Auto Faces) - (Font Lookup, Fringe Indicators, Display Margins) - (Image Descriptors, Showing Images, Image Cache, Button Types) - (Making Buttons, Manipulating Buttons, Button Buffer Commands) - (Display Table Format, Glyphs): - * control.texi (Iteration): - * commands.texi (Command Loop Info, Adjusting Point): - * backups.texi (Making Backups, Auto-Saving): - Remove @tindex entries. - -2006-07-07 Kim F. Storm - - * display.texi (Fringe Cursors): Fix typo. - (Customizing Bitmaps): Fix define-fringe-bitmap entry. - (Overlay Arrow): Default is overlay-arrow fringe indicator. - -2006-07-05 Richard Stallman - - * text.texi (Buffer Contents): Add example of text props - in result of buffer-substring. - (Text Properties): Explain better about use of specific property names. - (Property Search): Some cleanups; reorder some functions. - - * keymaps.texi (Changing Key Bindings): Cleanup. - Add xref to Key Binding Conventions. - - * display.texi (Attribute Functions): Add examples for - face-attribute-relative-p. - - * tips.texi (Coding Conventions): Cleanup last change. - -2006-07-05 Karl Berry - - * elisp.texi: Use @fonttextsize 10pt, a la emacs.texi. - Remove @setchapternewpage odd. - Result is 1013 pages, down from 1100. - - * anti.texi, customize.texi, display.texi, internals.texi: - * minibuf.texi, modes.texi, tips.texi: - Fix overfull/underfull boxes. - -2006-07-05 Thien-Thi Nguyen - - * edebug.texi (Instrumenting): - Add Edebug-specific findex for eval-buffer. - * loading.texi (Loading): - Replace eval-current-buffer with eval-buffer. - -2006-06-30 Nick Roberts - - * locals.texi (Standard Buffer-Local Variables): Update the list - of variables. - -2006-06-26 Nick Roberts - - * files.texi (File Name Completion): Point user to the node - "Reading File Names". - -2006-06-24 Eli Zaretskii - - * files.texi (Contents of Directories): Document case-insensitive - behavior on respective filesystems. - - * objects.texi (Character Type): Document that Emacs signals an - error for unsupported Unicode characters specified as \uNNNN. - -2006-06-19 Richard Stallman - - * processes.texi (Bindat Spec): Clarify previous change. - -2006-06-16 Richard Stallman - - * tips.texi (Coding Conventions): Better explain conventions - for definition constructs. - - * text.texi (Special Properties): String value of `read-only' - serves as the error message. - - * objects.texi (Character Type): Clarify prev. change. - (Non-ASCII in Strings): Mention \u and \U. - - * commands.texi (Using Interactive): Explain problem of - markers, etc., in command-history. - -2006-06-14 Kim F. Storm - - * commands.texi (Waiting): Negative arg to sit-for forces - redisplay even if input is pending. - - * display.texi (Forcing Redisplay): Use (sit-for -1) to force a - redisplay. Remove incorrect example of binding redisplay-dont-pause - around (sit-for 0). - -2006-06-13 Richard Stallman - - * display.texi (Forcing Redisplay): Clarify previous change. - -2006-06-13 Romain Francoise - - * display.texi (Forcing Redisplay): Fix typo. - -2006-06-13 Kim F. Storm - - * display.texi (Forcing Redisplay): Add redisplay-preemption-period. - -2006-06-10 Luc Teirlinck - - * tips.texi (Coding Conventions): Add `@end itemize'. - -2006-06-10 Richard Stallman - - * tips.texi (Coding Conventions): Explain use of coding systems - to ensure one decoding for strings. - -2006-06-09 Aidan Kehoe - - * objects.texi (Character Type): Describe the \uABCD and \U00ABCDEF - syntax. - -2006-06-07 Eli Zaretskii - - * display.texi (Font Selection): Remove description of - clear-face-cache. - - * compile.texi (Eval During Compile): Fix a typo. Add index - entries for possible uses of eval-when-compile. - -2006-06-04 Thien-Thi Nguyen - - * display.texi (Abstract Display): Fix typo. - -2006-06-03 Eli Zaretskii - - * minibuf.texi (Minibuffer History) : - Reword variable's description. - -2006-06-01 Richard Stallman - - * windows.texi (Splitting Windows): Clarify splitting nonselected - window. - -2006-05-31 Juri Linkov - - * minibuf.texi (Minibuffer History): Add history-add-new-input. - -2006-05-30 Richard Stallman - - * display.texi (Line Height): Fix errors in description of - default line height and line-height property. - - * nonascii.texi (Default Coding Systems): Further clarification. - -2006-05-29 Luc Teirlinck - - * internals.texi (Pure Storage): Mention that an overflow in pure - space causes a memory leak. - (Garbage Collection): If there was an overflow in pure space, - `garbage-collect' returns nil. - -2006-05-30 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix it some more. - -2006-05-29 Eli Zaretskii - - * nonascii.texi (Default Coding Systems): Fix last change. - -2006-05-29 Kenichi Handa - - * nonascii.texi (find-operation-coding-system): Describe the new - argument format (FILENAME . BUFFER). - -2006-05-28 Richard Stallman - - * tips.texi (Coding Conventions): Better explain reasons not to - advise other packages or use `eval-after-load'. - -2006-05-29 Kim F. Storm - - * processes.texi (Bindat Functions): Rename `pos' and `raw-data' to - `bindat-idx' and `bindat-raw' for clarity. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Spec): Expand on `repeat' handler. - - * display.texi (Display): Add "Abstract Display" to menu. - (Abstract Display, Abstract Display Functions) - (Abstract Display Example): New nodes. - * elisp.texi (Top): Add "Abstract Display" to menu. - -2006-05-27 Chong Yidong - - * keymaps.texi (Key Sequences): Link to input events definition. - (Format of Keymaps): Delete material duplicated in Keymap Basics. - - * files.texi (Changing Files): Document updated argument list for - copy-file. - -2006-05-27 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Explain term "total length". - Use it in bindat-length and bindat-pack descriptions. - -2006-05-26 Eli Zaretskii - - * tips.texi (Coding Conventions): Advise against using - eval-after-load in packages. Add an index entry. - -2006-05-25 Juri Linkov - - * minibuf.texi (Text from Minibuffer): Undocument keep-all. - - * modes.texi (%-Constructs): Add %e, %z, %Z. - -2006-05-25 Richard Stallman - - * elisp.texi (Top): Update subnode menu. - - * keymaps.texi (Keymap Basics): New node, split out of Key Sequences. - (Keymaps): Update menu. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Some clarifications. - -2006-05-25 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): Say "unibyte string" - explicitly for bindat-unpack and bindat-pack descriptions. - (Bindat Examples): Don't call `string-make-unibyte' in example. - -2006-05-25 Chong Yidong - - * keymaps.texi (Key Sequences): Renamed from Keymap Terminology. - Explain string and vector representations of key sequences. - - * keymaps.texi (Changing Key Bindings): - * commands.texi (Interactive Codes): - * help.texi (Describing Characters): Refer to it. - -2006-05-23 Luc Teirlinck - - * frames.texi (Pointer Shape): @end table -> @end defvar. - -2006-05-22 Richard Stallman - - * elisp.texi (Top): Update subnode menus. - - * frames.texi (Pointer Shape): Node renamed from Pointer Shapes. - Contents rewritten; material from old Pointer Shape node moved here. - - * display.texi (Pointer Shape): Node deleted. - (Image Descriptors): Minor cleanup. - -2006-05-21 Richard Stallman - - * syntax.texi (Parsing Expressions): Update info on which STATE - elements are ignored. - -2006-05-19 Luc Teirlinck - - * hooks.texi (Standard Hooks): Correct typo. - - * gpl.texi (GPL): ifinfo -> ifnottex. - -2006-05-19 Michael Ernst (tiny change) - - * searching.texi (Simple Match Data): Warn about match data being - set anew by every search. - -2006-05-17 Richard Stallman - - * minibuf.texi (Minibuffer History): Clarify. - - * searching.texi (Regexp Special): Clarify nested regexp warning. - -2006-05-16 Kim F. Storm - - * minibuf.texi (Minibuffer History): Update add-to-history. - -2006-05-15 Oliver Scholz (tiny change) - - * nonascii.texi (Explicit Encoding): Fix - typo (encoding<->decoding). - -2006-05-14 Richard Stallman - - * buffers.texi (Creating Buffers): Cleanup. - - * files.texi (Visiting Functions): Rewrite in find-file-noselect. - -2006-05-13 Eli Zaretskii - - * buffers.texi (Current Buffer): Document that with-temp-buffer - disables undo. - - * os.texi (Terminal-Specific): More accurate description of how - Emacs searches for the terminal-specific libraries. - -2006-05-12 Eli Zaretskii - - * hooks.texi (Standard Hooks) [iftex]: Convert @xref's to - emacs-xtra to @inforef's. - - * text.texi (Undo): Document that undo is turned off in buffers - whose names begin with a space. - - * buffers.texi (Buffer Names): Add index entries for buffers whose - names begin with a space. - (Creating Buffers): Document that undo is turned off in buffers - whose names begin with a space. - - * files.texi (Visiting Functions, Reading from Files) - (Saving Buffers): Mention code and EOL conversions by file I/O - primitives and subroutines. - - * nonascii.texi (Lisp and Coding Systems): Document - coding-system-eol-type. Add index entries for eol conversion. - - * display.texi (Defining Faces): Mention `mac', and add an xref to - where window-system is described. - -2006-05-10 Richard Stallman - - * internals.texi (Writing Emacs Primitives): Clarify GCPRO rules. - -2006-05-10 Reiner Steib - - * variables.texi (File Local Variables): Recommend to quote lambda - expressions in safe-local-variable property. - -2006-05-09 Richard Stallman - - * variables.texi (File Local Variables): Document - safe-local-eval-forms and safe-local-eval-function. - -2006-05-07 Kim F. Storm - - * minibuf.texi (Minibuffer History): Remove keep-dups arg - from add-to-history. - -2006-05-07 Romain Francoise - - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile): - * internals.texi (Buffer Internals): - * minibuf.texi (Initial Input): - * nonascii.texi (Scanning Charsets): - * numbers.texi (Comparison of Numbers): - * windows.texi (Textual Scrolling, Vertical Scrolling): - Fix various typos. - -2006-05-06 Eli Zaretskii - - * hooks.texi (Standard Hooks): Replace inforef to emacs-xtra by - conditional xref's to either emacs or emacs-xtra, depending on - @iftex/@ifnottex. - - * minibuf.texi (Minibuffer History): Document add-to-history. - -2006-05-05 Eli Zaretskii - - * internals.texi (Pure Storage): Mention the pure overflow message - at startup. - -2006-05-05 Johan Bockgård - - * keymaps.texi (Active Keymaps): Fix pseudo-Lisp syntax. - (Searching Keymaps): Fix pseudo-Lisp description of keymap - search. - -2006-05-01 Richard Stallman - - * intro.texi (nil and t): Clarify. - - * variables.texi (File Local Variables): Suggest using booleanp. - -2006-05-01 Juanma Barranquero - - * objects.texi (Type Predicates): Fix typos. - -2006-05-01 Stefan Monnier - - * intro.texi (nil and t): Add booleanp. - - * objects.texi (Type Predicates): Add links for booleanp and - string-or-null-p. - -2006-04-29 Richard Stallman - - * modes.texi (Multiline Font Lock): Rename from - Multi line Font Lock Elements. Much clarification. - (Font Lock Multiline, Region to Fontify): Much clarification. - -2006-04-29 Stefan Monnier - - * variables.texi (File Local Variables): Remove the special case t for - safe-local-variable. - -2006-04-26 Richard Stallman - - * syntax.texi (Parsing Expressions): Minor cleanup. - -2006-04-18 Richard Stallman - - * tips.texi (Coding Conventions): Explain when the package's - prefix should appear later on (not at the start of the name). - - * searching.texi (String Search): Clarify effect of NOERROR. - - * modes.texi (Imenu): Clarify what special items do. - - * hooks.texi (Standard Hooks): Delete text about old hook names. - -2006-04-17 Romain Francoise - - * variables.texi (Local Variables): Update the default value of - `max-specpdl-size'. - -2006-04-15 Michael Olson - - * processes.texi (Transaction Queues): Mention the new optional - `delay-question' argument for `tq-enqueue'. - -2006-04-13 Bill Wohler - - * customize.texi (Common Keywords): Use dotted notation for - :package-version value. Specify its values. Improve documentation - for customize-package-emacs-version-alist. - -2006-04-12 Bill Wohler - - * customize.texi (Common Keywords): Move description of - customize-package-emacs-version-alist to @defvar. - -2006-04-10 Bill Wohler - - * customize.texi (Common Keywords): Add :package-version. - -2006-04-10 Kim F. Storm - - * text.texi (Buffer Contents): Add NOPROPS arg to - filter-buffer-substring. - -2006-04-08 Kevin Ryde - - * os.texi (Command-Line Arguments): Update xref to emacs manual - "Command Arguments" -> "Emacs Invocation", per change there. - -2006-04-08 Thien-Thi Nguyen - - * display.texi (Other Display Specs): Arrange a @code{DOTTED-LIST} to - be on one line to help makeinfo not render two spaces after the dot. - -2006-04-07 Reiner Steib - - * strings.texi (Predicates for Strings): Add string-or-null-p. - -2006-03-28 Kim F. Storm - - * processes.texi (Accepting Output): Remove obsolete (and incorrect) - remarks about systems that don't support fractional seconds. - -2006-03-25 Karl Berry - - * elisp.texi: Use @copyright{} instead of (C), and do not indent - the year list. - -2006-03-21 Nick Roberts - - * display.texi (Fringe Indicators): Fix typos. - -2006-03-19 Luc Teirlinck - - * tips.texi (Documentation Tips): One can now also write `program' - in front of a quoted symbol in a docstring to prevent making a - hyperlink. - -2006-03-19 Alan Mackenzie - - * text.texi (Special Properties): Clarify `fontified' property. - -2006-03-16 Richard Stallman - - * display.texi (Defining Images): Minor cleanup. - -2006-03-16 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - prefer user's images. - -2006-03-15 Stefan Monnier - - * modes.texi (Region to Fontify): Remove font-lock-lines-before. - -2006-03-15 Bill Wohler - - * display.texi (Defining Images): Fix example in - image-load-path-for-library by not recommending that one binds - image-load-path. Just defvar it to placate compiler and only use - it if previously defined. - -2006-03-14 Bill Wohler - - * display.texi (Defining Images): In image-load-path-for-library, - always return list of directories. Update example. - -2006-03-14 Alan Mackenzie - - * modes.texi: New node, "Region to Fontify" (for Font Lock). - This describes font-lock-extend-region-function. - ("Other Font Lock Variables"): Move "font-lock-lines-before" to - the new node "Region to Fontify". - -2006-03-13 Richard Stallman - - * display.texi (Invisible Text): The impossible position is - now before the invisible text, not after. - (Defining Images): Clean up last change. - -2006-03-11 Bill Wohler - - * display.texi (Defining Images): Add image-load-path-for-library. - -2006-03-11 Luc Teirlinck - - * text.texi (Adaptive Fill): Fix Texinfo usage. - - * strings.texi (Creating Strings): Fix Texinfo usage. - - * searching.texi (Regexp Special): Use @samp for regular - expressions that are not in Lisp syntax. - -2006-03-08 Luc Teirlinck - - * searching.texi (Regexp Special): Put remark between parentheses - to avoid misreading. - -2006-03-07 Luc Teirlinck - - * searching.texi (Syntax of Regexps): More accurately describe - which characters are special in which situations. - (Regexp Special): Recommend _not_ to quote `]' or `-' when they - are not special. Describe in detail when `[' and `]' are special. - (Regexp Backslash): Plenty of regexps with unbalanced square - brackets are valid, so reword that statement. - -2006-03-02 Kim F. Storm - - * keymaps.texi (Tool Bar): Add tool-bar-border. - -2006-02-28 Luc Teirlinck - - * loading.texi (Load Suffixes): Rephrase last paragraph. Fix typos. - -2006-02-27 Luc Teirlinck - - * elisp.texi (Top): Include "Load Suffixes" in the detailed menu. - - * files.texi (Locating Files): Suggest additional values for the - SUFFIXES arg of `locate-file'. Update pxref. - - * loading.texi (Loading): Include new node "Load Suffixes" in menu. - (How Programs Do Loading): Discuss the effects of Auto Compression - mode on `load'. - (Load Suffixes): New node. - (Library Search): Delete description of `load-suffixes'; it was - moved to "Load Suffixes". - (Autoload, Named Features): Mention `load-suffixes'. - -2006-02-21 Giorgos Keramidas (tiny change) - - * display.texi (Fringe Indicators, Fringe Cursors): Fix typos. - - * windows.texi (Window Tree): Fix typo. - -2006-02-20 Kim F. Storm - - * display.texi (Fringe Indicators): New section. - Move indicate-empty-lines, indicate-buffer-boundaries, and - default-indicate-buffer-boundaries here. - Add fringe-indicator-alist and default-fringes-indicator-alist. - Add list of logical fringe indicator symbols. - Update list of standard bitmap names. - (Fringe Cursors): New section. - Move overflow-newline-into-fringe here. - Add fringe-cursor-alist and default-fringes-cursor-alist. - Add list of fringe cursor symbols. - -2006-02-20 Juanma Barranquero - - * commands.texi (Using Interactive): Fix reference to node - "Minibuffers". - -2006-02-19 Richard M. Stallman - - * minibuf.texi (High-Level Completion): - Add xref to read-input-method-name. - - * files.texi (Relative File Names): Move file-relative-name here. - (File Name Expansion): From here. Minor clarifications. - - * commands.texi (Using Interactive): Add xrefs about reading input. - Clarify remarks about that moving point and mark. - Put string case before list case. - -2006-02-16 Johan Bockgård - - * display.texi (Other Display Specs, Image Descriptors): - Revert erroneous changes. The previous description of - image-descriptors as `(image . PROPS)' was correct. - -2006-02-14 Richard M. Stallman - - * variables.texi (File Local Variables): Clarifications. - -2006-02-14 Juanma Barranquero - - * variables.texi (File Local Variables): Use @code for a cons - cell, not @var. - -2006-02-13 Chong Yidong - - * variables.texi (File Local Variables): Document new file local - variable behavior. - -2006-02-10 Kim F. Storm - - * eval.texi (Function Indirection): Add NOERROR to indirect-function. - -2006-02-08 Juanma Barranquero - - * modes.texi (%-Constructs): Remove obsolete info about - `global-mode-string'. - -2006-02-07 Richard M. Stallman - - * commands.texi (Prefix Command Arguments): Minor cleanup. - - * display.texi: "Graphical display", not window system. - - * functions.texi (What Is a Function): Fix xref. - - * keymaps.texi (Key Lookup): Clarify wrt commands vs other functions. - (Changing Key Bindings): Clarify when remapping is better than - substitute-key-definition. - -2006-02-02 Richard M. Stallman - - * minibuf.texi (Basic Completion): Completion alists are risky. - - * keymaps.texi (Active Keymaps): Clarifications. - (Searching Keymaps): New node. - (Keymaps): Update menu. - - * frames.texi (Layout Parameters): Minor clarification. - (Drag and Drop): New node. - (Frames): Update menu. - -2006-01-29 Chong Yidong - - * display.texi (Other Display Specs, Image Descriptors): - Image description is a list, not a cons cell. - -2006-01-28 Luc Teirlinck - - * lists.texi (Cons Cells): Minor correction (the cdr of a dotted - list is not necessarily a list). - -2006-01-27 Eli Zaretskii - - * frames.texi (Layout Parameters): border-width and - internal-border-width belong to the frame, not the window. - -2006-01-19 Richard M. Stallman - - * nonascii.texi (Translation of Characters): Search cmds use - translation-table-for-input. Automatically made local. - - * markers.texi (Overview of Markers): Count insertion type - as one of a marker's attributes. - - * keymaps.texi (Controlling Active Maps): New node, split out of - Active Keymaps. - (Keymaps): Menu updated. - (Active Keymaps): Give pseudocode to explain how the active - maps are searched. current-active-maps and key-binding moved here. - (Functions for Key Lookup): current-active-maps and key-binding moved. - Clarifications. - (Searching the Keymaps): New subnode. - - * elisp.texi (Top): Menu clarification. - - * display.texi (Other Display Specs): Delete duplicate entry for - just a string as display spec. Move text about recursive display - specs on such a string. - - * commands.texi (Key Sequence Input): Clarify. - Move num-nonmacro-input-events out. - (Reading One Event): num-nonmacro-input-events moved here. - -2006-01-14 Nick Roberts - - * advice.texi (Simple Advice): Update example to fit argument - change in previous-line. - -2006-01-05 Richard M. Stallman - - * markers.texi (The Mark): Fix in `mark'. - -2006-01-04 Richard M. Stallman - - * processes.texi (Misc Network, Make Network): Minor cleanups. - -2006-01-04 Kim F. Storm - - * processes.texi (Make Network): Add IPv6 addresses and handling. - (Network Feature Testing): Mention (:family ipv6). - (Misc Network): Add IPv6 formats to format-network-address. - -2005-12-30 Richard M. Stallman - - * text.texi (Changing Properties): - Don't use return value of set-text-properties. - -2005-12-29 Luc Teirlinck - - * modes.texi (Mode Line Format): Correct typo in menu. - -2005-12-29 Richard M. Stallman - - * modes.texi (Mode Line Top): New node. - (Mode Line Data): Some text moved to new node. - Explain the data structure more concretely. - (Mode Line Basics): Clarifications. - (Mode Line Variables): Clarify intro paragraph. - (%-Constructs): Clarify intro paragraph. - (Mode Line Format): Update menu. - -2005-12-28 Luc Teirlinck - - * minibuf.texi (Basic Completion): Update lazy-completion-table - examples for removal of ARGS argument. - -2005-12-23 Richard M. Stallman - - * text.texi (Undo): Restore some explanation from the version - that was deleted. - -2005-12-23 Eli Zaretskii - - * text.texi (Undo): Remove duplicate descriptions of `apply - funname' and `apply delta' elements of the undo list. - -2005-12-20 Richard M. Stallman - - * help.texi (Help Functions): Update documentation of `apropos'. - -2005-12-20 Luc Teirlinck - - * customize.texi (Type Keywords): Delete xref to "Text help-echo", - because it is confusing. If the :help-echo keyword is a function, - it is not directly used as the :help-echo overlay property, as the - xref seems to suggest (it does not take the appropriate args). - -2005-12-19 Luc Teirlinck - - * customize.texi (Common Keywords): Fix Texinfo usage. - (Group Definitions, Variable Definitions): Update for new - conventions for using `*' in docstrings. - - * tips.texi (Documentation Tips): Update for new conventions for - using `*' in docstrings. - -2005-12-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Contents): Minor cleanup. - -2005-12-16 Juri Linkov - - * minibuf.texi (Minibuffer Contents): Add minibuffer-completion-contents. - -2005-12-14 Romain Francoise - - * modes.texi (Customizing Keywords): Rename `append' to `how'. - Fix typo. - -2005-12-11 Juri Linkov - - * minibuf.texi (Completion Commands): Add mention of read-file-name - for filename completion keymaps. - (Reading File Names): Add mention of filename completion keymaps - for read-file-name and xref to `Completion Commands'. - -2005-12-10 Richard M. Stallman - - * customize.texi (Common Keywords): State caveats for use of :tag. - -2005-12-08 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Replace list of local maps - with xrefs and better explanation. - (Completion Commands): Add the filename completion maps. - - * objects.texi (Character Type): Clarify that \s is not space - if a dash follows. - -2005-12-05 Richard M. Stallman - - * windows.texi (Resizing Windows): Delete preserve-before args. - -2005-12-05 Stefan Monnier - - * keymaps.texi (Format of Keymaps): Remove mention of a quirk - in full keymaps, since the quirk has been fixed. - -2005-12-03 Eli Zaretskii - - * hooks.texi (Standard Hooks): Add index entries. Mention - `compilation-finish-functions'. - -2005-11-27 Richard M. Stallman - - * windows.texi (Resizing Windows): Add adjust-window-trailing-edge. - -2005-11-21 Juri Linkov - - * customize.texi (Common Keywords): Update links types - custom-manual and url-link. Add link types emacs-library-link, - file-link, function-link, variable-link, custom-group-link. - -2005-11-20 Chong Yidong - - * display.texi: Revert 2005-11-20 change. - -2005-11-20 Thien-Thi Nguyen - - * processes.texi (Bindat Functions): - Say "third" to refer to zero-based index "2". - -2005-11-18 Luc Teirlinck - - * loading.texi (Library Search): Update the default value of - `load-suffixes'. - -2005-11-17 Chong Yidong - - * display.texi (Attribute Functions): Mention :ignore-defface. - -2005-11-16 Stefan Monnier - - * modes.texi (Minor Mode Conventions): Use custom-set-minor-mode. - (Minor Mode Conventions): Mention the use of a hook. - -2005-11-06 Richard M. Stallman - - * files.texi (Magic File Names): find-file-name-handler checks the - `operations' property of the handler. - -2005-11-03 Richard M. Stallman - - * variables.texi (Frame-Local Variables): Small clarification. - -2005-10-29 Chong Yidong - - * os.texi (Init File): Document ~/.emacs.d/init.el. - -2005-10-29 Richard M. Stallman - - * internals.texi (Garbage Collection): Document memory-full. - -2005-10-28 Bill Wohler - - * tips.texi (Documentation Tips): Help mode now creates hyperlinks - for URLs. - -2005-10-28 Richard M. Stallman - - * minibuf.texi (Completion Commands): Clean up prev change. - -2005-10-26 Kevin Ryde - - * compile.texi (Eval During Compile): Explain recommended uses - of eval-when-compile and eval-and-compile. - -2005-10-27 Masatake YAMATO - - * minibuf.texi (Completion Commands): - Write about new optional argument for `display-completion-list'. - -2005-10-23 Richard M. Stallman - - * display.texi (Overlay Arrow): Clarify about local bindings of - overlay-arrow-position. - -2005-10-22 Eli Zaretskii - - * internals.texi (Building Emacs): Fix last change. - -2005-10-22 Richard M. Stallman - - * internals.texi (Building Emacs): Document eval-at-startup. - -2005-10-21 Richard M. Stallman - - * loading.texi (Where Defined): load-history contains abs file names. - symbol-file returns abs file names. - -2005-10-19 Kim F. Storm - - * display.texi (Showing Images): Add max-image-size integer value. - -2005-10-18 Chong Yidong - - * display.texi (Showing Images): Document max-image-size. - -2005-10-17 Richard M. Stallman - - * commands.texi (Quitting): Minor clarification. - - * processes.texi (Sentinels): Clarify about output and quitting. - (Filter Functions): Mention with-local-quit. - -2005-10-17 Juri Linkov - - * buffers.texi (Current Buffer): - * commands.texi (Event Input Misc): - * compile.texi (Eval During Compile, Compiler Errors): - * customize.texi (Group Definitions): - * display.texi (Progress, Defining Faces): - * files.texi (Writing to Files): - * modes.texi (Mode Hooks, Defining Minor Modes): - * streams.texi (Output Functions): - * syntax.texi (Syntax Table Functions): - * text.texi (Change Hooks): - Replace `...' with `@dots{}' in `@defmac' and `@defspec'. - - * commands.texi (Quitting): Replace arg `forms' with `body' in - `with-local-quit'. - - * positions.texi (Excursions): Replace arg `forms' with `body' in - `save-excursion'. - -2005-10-08 Kim F. Storm - - * windows.texi (Window Tree): Rename window-split-tree to window-tree. - Rename manual section accordingly. - -2005-10-04 Kim F. Storm - - * windows.texi (Window Split Tree): New section describing - new function window-split-tree function. - -2005-10-03 Nick Roberts - - * display.texi (Fringe Size/Pos): Simplify and add detail. - -2005-09-30 Romain Francoise - - * minibuf.texi (High-Level Completion): Explain that the prompt - given to `read-buffer' should end with a colon and a space. - Update usage examples. - -2005-09-29 Juri Linkov - - * display.texi (Displaying Messages): Rename argument name - `string' to `format-string' in functions `message', `message-box', - `message-or-box'. - -2005-09-26 Chong Yidong - - * errors.texi (Standard Errors): Correct xrefs. - -2005-09-18 Chong Yidong - - * display.texi (Defining Images): Update documentation for - `image-load-path'. - -2005-09-17 Richard M. Stallman - - * display.texi (Defining Images): Clean up previous change. - -2005-09-16 Romain Francoise - - * elisp.texi: Specify GFDL version 1.2. - - * doclicense.texi (GNU Free Documentation License): Update to - version 1.2. - -2005-09-15 Chong Yidong - - * display.texi (Defining Images): Document `image-load-path'. - -2005-09-15 Richard M. Stallman - - * objects.texi (Printed Representation): Minor cleanup. - (Box Diagrams): Minor fix. - (Cons Cell Type): Move (...) index item here. - (Box Diagrams): From here. - (Array Type): Minor fix. - (Type Predicates): Delete index "predicates". - (Hash Table Type): Clarify xref. - (Dotted Pair Notation): Minor fix. - -2005-09-10 Chong Yidong - - * files.texi (Saving Buffers): Fix typo. - -2005-09-08 Richard M. Stallman - - * tips.texi (Programming Tips): Correct the "default" prompt spec. - -2005-09-08 Chong Yidong - - * locals.texi (Standard Buffer-Local Variables): Don't include - mode variables for minor modes. - Fix xrefs for buffer-display-count, buffer-display-table, - buffer-offer-save, buffer-saved-size, cache-long-line-scans, - enable-multibyte-characters, fill-column, header-line-format, - left-fringe-width, left-margin, and right-fringe-width. - - * hooks.texi (Standard Hooks): All hooks should conform to the - standard naming convention now. - Fix xref for `echo-area-clear-hook'. - - * display.texi (Usual Display): Note that indicate-empty-lines and - tab-width are buffer-local. - - * files.texi (Saving Buffers): Add xref to `Killing Buffers'. - - * modes.texi (Mode Help): Note that major-mode is buffer-local. - - * nonascii.texi (Encoding and I/O): Note that - buffer-file-coding-system is buffer-local. - - * positions.texi (List Motion): Note that defun-prompt-regexp is - buffer-local. - - * text.texi (Auto Filling): Note that auto-fill-function is - buffer-local. - (Undo): Note that buffer-undo-list is buffer-local. - - * windows.texi (Buffers and Windows): Document - buffer-display-count. - -2005-09-06 Richard M. Stallman - - * tips.texi (Coding Conventions): Sometimes it is ok to put the - package prefix elsewhere than at the start of the name. - -2005-09-03 Richard M. Stallman - - * tips.texi (Programming Tips): Add conventions for minibuffer - questions and prompts. - -2005-09-03 Joshua Varner (tiny change) - - * intro.texi (nil and t): Minor cleanup. - Delete spurious mention of keyword symbols. - (Evaluation Notation): Add index entry. - (A Sample Function Description): Minor cleanup. - (A Sample Variable Description): Not all vars can be set. - -2005-09-03 Thien-Thi Nguyen - - * text.texi (Buffer Contents): Use "\n" in examples' result strings. - - (Insertion): Document precise type of `insert-char' arg COUNT. - -2005-09-02 Stefan Monnier - - * modes.texi (Other Font Lock Variables): Sync the default of - font-lock-lines-before. - -2005-08-31 Michael Albinus - - * files.texi (Magic File Names): Add `make-auto-save-file-name'. - -2005-08-29 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu. - - * searching.texi (Searching and Matching): Move node. - Rearrange contents and add overall explanation. - (Searching and Case): Move node. - (Searching and Matching): Update menu. - -2005-08-27 Eli Zaretskii - - * os.texi (Startup Summary): Fix the description of the initial - startup message display. - -2005-08-25 Richard M. Stallman - - * searching.texi (Search and Replace): Add replace-regexp-in-string. - -2005-08-25 Emilio C. Lopes - - * display.texi (Finding Overlays): Fix `find-overlay-prop' in - `next-overlay-change' example. - -2005-08-22 Juri Linkov - - * display.texi (Attribute Functions): Add set-face-inverse-video-p. - Fix invert-face. Fix args of face-background. - - * display.texi (Standard Faces): Delete node. - (Faces): Add xref to `(emacs)Standard Faces'. - (Displaying Faces): Fix xref to `Standard Faces'. - - * modes.texi (Mode Line Data): Fix xref to Standard Faces. - -2005-08-20 Alan Mackenzie - - * buffers.texi (The Buffer List): Clarify the manipulation of the - buffer list. - -2005-08-14 Richard M. Stallman - - * modes.texi (Auto Major Mode): interpreter-mode-alist key is not - a regexp. - -2005-08-11 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists. - - * display.texi (Inverse Video): Node deleted. - - * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): - New nodes split out of Coding Conventions. - - * searching.texi (Regular Expressions): Document re-builder. - - * os.texi (Time Parsing): New node split out of Time Conversion. - - * processes.texi (Misc Network, Network Feature Testing) - (Network Options, Make Network): New nodes split out of - Low-Level Network. - -2005-08-09 Richard M. Stallman - - * frames.texi (Geometry): New node, split from Size and Position. - (Frame Parameters): Refer to Geometry. - - * buffers.texi (The Buffer List): Fix xrefs. - - * windows.texi (Splitting Windows): Fix xref. - - * frames.texi (Layout Parameters): Add xref. - - * display.texi (Line Height, Scroll Bars): Fix xrefs. - - * keymaps.texi (Menu Bar): Fix xref. - - * locals.texi (Standard Buffer-Local Variables): Fix xref. - - * modes.texi (%-Constructs): Fix xref. - - * frames.texi (Window Frame Parameters): Node split up. - (Basic Parameters, Position Parameters, Size Parameters) - (Layout Parameters, Buffer Parameters, Management Parameters) - (Cursor Parameters, Color Parameters): New subnodes. - -2005-08-09 Luc Teirlinck - - * positions.texi (Screen Lines): Update xref for previous change - in minibuf.texi. - - * minibuf.texi (Intro to Minibuffers): Update pxref for previous - change in minibuf.texi. - -2005-08-09 Richard M. Stallman - - * tips.texi (Coding Conventions): Minor cleanup. - - * modes.texi (Defining Minor Modes): Explain when init-value - can be non-nil. - - * elisp.texi (Top): Update submenu for Minibuffer. - - * minibuf.texi (Minibuffer Misc): Node split up. - (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) - (Recursive Mini): New nodes split out from Minibuffer Misc. - (Minibuffer Misc): Document max-mini-window-height. - - * hash.texi (Defining Hash): Delete stray paren in example. - - * display.texi (Echo Area Customization): Don't define - max-mini-window-height here; xref instead. - - * commands.texi (Event Input Misc): Update while-no-input. - - * advice.texi (Advising Functions): Explain when to use advice - and when to use a hook. - -2005-07-30 Eli Zaretskii - - * makefile.w32-in (info): Don't run install-info. - ($(infodir)/dir): New target, produced by running install-info. - -2005-07-27 Luc Teirlinck - - * modes.texi (Defining Minor Modes): The keyword for the initial - value is :init-value, not :initial-value. - -2005-07-23 Eli Zaretskii - - * loading.texi (Autoload): Make the `doctor' example be consistent - with what's in current loaddefs.el. Describe the "fn" magic in - the usage portion of the doc string. - -2005-07-22 Richard M. Stallman - - * internals.texi (Garbage Collection): Clarify previous change. - -2005-07-21 Stefan Monnier - - * internals.texi (Garbage Collection): Add gc-cons-percentage. - -2005-07-18 Juri Linkov - - * commands.texi (Accessing Events): - * frames.texi (Text Terminal Colors, Resources): - * markers.texi (The Mark): - * modes.texi (Defining Minor Modes): - Delete duplicate duplicate words. - -2005-07-16 Richard M. Stallman - - * display.texi (Managing Overlays): Clarify make-overlay - args for insertion types. - -2005-07-13 Luc Teirlinck - - * customize.texi (Variable Definitions): - Add `custom-initialize-safe-set' and `custom-initialize-safe-default'. - `standard-value' is a list too. - (Defining New Types): Use @key{RET} instead of @key{ret}. - -2005-07-13 Francis Litterio (tiny change) - - * os.texi (Translating Input): Fix typo. - -2005-07-08 Richard M. Stallman - - * README: Update edition number and size estimate. - - * elisp.texi (VERSION): Set to 2.9. - -2005-07-07 Richard M. Stallman - - * book-spine.texinfo: Update Emacs version. - - * display.texi (Inverse Video): Delete mode-line-inverse-video. - -2005-07-06 Richard M. Stallman - - * searching.texi (Regexp Search): Clarify what re-search-forward - does when the search fails. - -2005-07-05 Lute Kamstra - - * Update FSF's address in GPL notices. - - * doclicense.texi (GNU Free Documentation License): - * gpl.texi (GPL): - * tips.texi (Coding Conventions, Library Headers): - * vol1.texi: - * vol2.texi: Update FSF's address. - -2005-07-04 Richard M. Stallman - - * hooks.texi (Standard Hooks): Add occur-hook. - -2005-07-03 Luc Teirlinck - - * display.texi (The Echo Area): Correct menu. - -2005-07-03 Richard M. Stallman - - * elisp.texi (Top): Update subnode menu for Display. - - * display.texi (Displaying Messages): New node, with most - of what was in The Echo Area. - (Progress): Moved under The Echo Area. - (Logging Messages): New node with new text. - (Echo Area Customization): New node, the rest of what was - in The Echo Area. Document message-truncate-lines with @defvar. - (Display): Update menu. - - * windows.texi (Textual Scrolling): Doc 3 values for - scroll-preserve-screen-position. - - * text.texi (Special Properties): Change hook functions - should bind inhibit-modification-hooks around altering buffer text. - - * keymaps.texi (Key Binding Commands): Call binding BINDING - rather than DEFINITION. - -2005-06-29 Juanma Barranquero - - * variables.texi (Defining Variables): `user-variable-p' returns t - for aliases of user options, nil for alias loops. - -2005-06-28 Richard M. Stallman - - * keymaps.texi (Creating Keymaps): Put make-sparse-keymap before - make-keymap. - -2005-06-27 Luc Teirlinck - - * variables.texi (Setting Variables): Correct and clarify - description of `add-to-ordered-list'. - -2005-06-26 Richard M. Stallman - - * display.texi (Faces): Minor cleanup. - -2005-06-25 Luc Teirlinck - - * display.texi (Faces): `facep' returns t for strings that are - face names. - -2005-06-25 Richard M. Stallman - - * objects.texi (Equality Predicates): Clarify meaning of equal. - - * windows.texi (Selecting Windows): save-selected-window - and with-selected-window save and restore the current buffer. - -2005-06-24 Richard M. Stallman - - * numbers.texi (Float Basics): Explain how to test for NaN, - and printing the sign of NaNs. - -2005-06-24 Eli Zaretskii - - * makefile.w32-in (MAKEINFO): Use --force. - -2005-06-23 Richard M. Stallman - - * display.texi (Face Functions): Correct Texinfo usage. - -2005-06-23 Luc Teirlinck - - * lists.texi (Rings): `ring-elements' now returns the elements of - RING in order. - -2005-06-23 Juanma Barranquero - - * markers.texi (The Mark): Texinfo usage fix. - -2005-06-23 Kim F. Storm - - * searching.texi (Entire Match Data): Remove evaporate option for - match-data. Do not mention evaporate option for set-match-data. - -2005-06-22 Glenn Morris - - * display.texi (Face Functions): Mention face aliases. - -2005-06-21 Richard M. Stallman - - * anti.texi (Antinews): Texinfo usage fix. - -2005-06-21 Karl Berry - - * elisp.texi: Use @copying. - - * elisp.texi: Put @summarycontents and @contents before the Top - node, instead of the end of the file, so that the contents appear - in the right place in the dvi/pdf output. - -2005-06-21 Juri Linkov - - * display.texi (Defining Faces): Add `customized-face'. - -2005-06-20 Kim F. Storm - - * variables.texi (Setting Variables): Any type of element can be - given order in add-to-ordered-list. Compare elements with eq. - - * lists.texi (Rearrangement): Sort predicate may just return non-nil. - -2005-06-20 Karl Berry - - * syntax.texi (Syntax Flags): Make last column very slightly wider - to avoid "generic comment" breaking on two lines and causing an - underfull box. - -2005-06-19 Luc Teirlinck - - * lists.texi (Rings): Various minor clarifications and corrections. - -2005-06-18 Richard M. Stallman - - * functions.texi (Obsolete Functions): Simplify. - - * variables.texi (Variable Aliases): Simplify. - - * anti.texi, backups.texi, compile.texi, customization.texi: - * debugging.texi, display.texi, edebug.texi, errors.texi, frames.texi: - * functions.texi, help.texi, keymaps.texi, modes.texi, nonascii.texi: - * os.texi, processes.texi, searching.texi, strings.texi, text.texi: - * variables.texi: Fix formatting ugliness. - - * elisp.texi: Add links to Rings and Byte Packing. - Update version and copyright years. - - * minibuf.texi: Fix formatting ugliness. - (Completion Commands): Move keymap vars to the end - and vars completing-read binds to the top. - -2005-06-17 Luc Teirlinck - - * processes.texi: Fix typos. - (Bindat Spec): Correct Texinfo error. - (Byte Packing): Fix ungrammatical sentence. - -2005-06-17 Thien-Thi Nguyen - - * lists.texi (Rings): New node. - (Lists): Add it to menu. - - * processes.texi (Byte Packing): New node. - (Processes): Add it to menu. - -2005-06-17 Richard M. Stallman - - * syntax.texi (Parsing Expressions): Fix texinfo usage. - - * help.texi (Documentation Basics): Explain the xref to - Documentation Tips. - - * debugging.texi (Debugger Commands): Minor fix. - -2005-06-16 Luc Teirlinck - - * edebug.texi (Instrumenting): Eliminate duplicate link. - (Specification List): Replace references to "below", referring to - a later node, with one @ref to that node. - - * os.texi (Timers): Timers should save and restore the match data - if they change it. - - * debugging.texi (Debugger Commands): Mention that the Lisp - debugger can not step through primitive functions. - -2005-06-16 Juanma Barranquero - - * functions.texi (Obsolete Functions): Update argument names of - `make-obsolete' and `define-obsolete-function-alias'. - - * variables.texi (Variable Aliases): Update argument names of - `defvaralias', `make-obsolete-variable' and - `define-obsolete-variable-alias'. - -2005-06-15 Kim F. Storm - - * searching.texi (Entire Match Data): Rephrase warnings about - evaporate arg to match-data and set-match-data. - -2005-06-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * edebug.texi (Edebug): Update menu. - (Instrumenting): Update xrefs. - (Edebug Execution Modes): Correct xref. - (Jumping): Clarify description of `h' command. - Eliminate redundant @ref. - (Breaks): New node. - (Breakpoints): Is now a subsubsection. - (Global Break Condition): Mention `C-x X X'. - (Edebug Views): Clarify `v' and `p'. Mention `C-x X w'. - (Trace Buffer): Clarify STRING arg of `edebug-tracing'. - (Edebug Display Update): Correct pxref. - (Edebug and Macros): New node. - (Instrumenting Macro Calls): Is now a subsubsection. - Neither arg of `def-edebug-spec' is evaluated. - (Instrumenting Macro Calls): Mention `edebug-eval-macro-args'. - (Specification Examples): Fix typo. - -2005-06-14 Lute Kamstra - - * debugging.texi (Function Debugging): Primitives can break on - entry too. - -2005-06-14 Kim F. Storm - - * variables.texi (Setting Variables): Add add-to-ordered-list. - -2005-06-13 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document aux functions and vars of - syntax-ppss: syntax-ppss-flush-cache and syntax-begin-function. - -2005-06-13 Lute Kamstra - - * text.texi (Special Properties): Fix cross reference. - -2005-06-11 Luc Teirlinck - - * debugging.texi (Function Debugging): Delete mention of empty - string argument to `cancel-debug-on-entry'. Delete inaccurate - description of the return value of that command. - -2005-06-11 Alan Mackenzie - - * text.texi (Adaptive Fill): Amplify the description of - fill-context-prefix. - -2005-06-10 Luc Teirlinck - - * syntax.texi (Parsing Expressions): Fix Texinfo error. - -2005-06-10 Stefan Monnier - - * syntax.texi (Parsing Expressions): Document syntax-ppss. - -2005-06-10 Luc Teirlinck - - * debugging.texi (Error Debugging): Minor rewording. - (Function Debugging): FUNCTION-NAME arg to `cancel-debug-on-entry' - is optional. - -2005-06-10 Lute Kamstra - - * elisp.texi: Use EMACSVER to refer to the current version of Emacs. - (Top): Give it a title. Correct version number. Give the - detailed node listing a more prominent header. - * intro.texi: Don't set VERSION here a second time. - Mention Emacs's version too. - * anti.texi (Antinews): Use EMACSVER to refer to the current - version of Emacs. - -2005-06-09 Kim F. Storm - - * searching.texi (Entire Match Data): Explain new `reseat' argument to - match-data and set-match-data. - -2005-06-08 Richard M. Stallman - - * searching.texi (Entire Match Data): Clarify when match-data - returns markers and when integers. - - * display.texi (Defining Faces): Explain that face name should not - end in `-face'. - - * modes.texi (Mode Line Data): Minor cleanup. - (Customizing Keywords): Node split out of Search-based Fontification. - Add example of using font-lock-add-keywords from a hook. - Clarify when MODE should be non-nil, and when nil. - -2005-06-06 Richard M. Stallman - - * modes.texi (Mode Line Data): Explain what happens when the car - of a list is a void symbol. - (Search-based Fontification): Explain MODE arg to - font-lock-add-keywords and warn about calls from major modes. - -2005-06-08 Juri Linkov - - * display.texi (Standard Faces): Add `shadow' face. - -2005-05-29 Luc Teirlinck - - * modes.texi (Major Mode Conventions): A derived mode only needs - to put the call to the parent mode inside `delay-mode-hooks'. - -2005-05-29 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook is - new, and what that implies. Clarify. - - * files.texi (Locating Files): Clean up the text. - - * frames.texi (Window Frame Parameters): Document user-size. - Shorten entry for top by referring to left. - -2005-05-26 Richard M. Stallman - - * modes.texi (Mode Hooks): Explain that after-change-major-mode-hook - is new, and what the implications are. Other clarifications. - -2005-05-24 Richard M. Stallman - - * frames.texi (Dialog Boxes): Minor fixes. - -2005-05-25 Masatake YAMATO - - * display.texi (Standard Faces): Write about `mode-line-highlight'. - -2005-05-24 Luc Teirlinck - - * frames.texi (Dialog Boxes): HEADER argument to `x-popup-dialog' - is optional. - -2005-05-24 Nick Roberts - - * frames.texi (Dialog Boxes): Describe new optional argument. - -2005-05-23 Lute Kamstra - - * modes.texi (Font Lock Basics, Syntactic Font Lock): Recommend - syntax-begin-function over font-lock-beginning-of-syntax-function. - -2005-05-21 Luc Teirlinck - - * minibuf.texi (Reading File Names): Update description of - `read-directory-name'. - - * modes.texi (Derived Modes): Clarify :group keyword. - -2005-05-21 Eli Zaretskii - - * files.texi (Locating Files): New subsection. - Describe locate-file and executable-find. - -2005-05-21 Kevin Ryde - - * frames.texi (Initial Parameters): Update cross reference to - "Emacs Invocation". - -2005-05-19 Luc Teirlinck - - * keymaps.texi (Active Keymaps): Add anchor. - - * modes.texi (Hooks): Delete confusing and unnecessary sentence. - (Major Mode Conventions): Refer to `Auto Major Mode' in more - appropriate place. - (Derived Modes): Small clarifications. - (Minor Mode Conventions, Keymaps and Minor Modes): - Replace references to nodes with references to anchors. - (Mode Line Data): Warn that `(:eval FORM)' should not load any files. - Clarify description of lists whose first element is an integer. - (Mode Line Variables): Add anchor. - (%-Constructs): Clarify description of integer after %. - (Emulating Mode Line): Describe nil value for FACE. - -2005-05-18 Luc Teirlinck - - * modes.texi (Derived Modes): Correct references to non-existing - variable standard-syntax-table. - -2005-05-17 Lute Kamstra - - * modes.texi (Defining Minor Modes): Mention the mode hook. - -2005-05-15 Kim F. Storm - - * processes.texi (Network): Remove open-network-stream-nowait. - (Network Servers): Remove open-network-stream-server. - -2005-05-15 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu. - - * variables.texi: Reorder nodes. - (Variables): Update menu. - (File Local Variables): Do not refer to the `-*-' line as - a "local variables list". Add pxref. - -2005-05-14 Luc Teirlinck - - * elisp.texi (Top): Update detailed menu for node changes. - - * modes.texi (Modes): Update Menu. - (Hooks): Move to beginning of chapter. - Most minor modes run mode hooks too. - `add-hook' can handle void hooks or hooks whose value is a single - function. - (Major Modes): Update Menu. - (Major Mode Basics): New node, split off from `Major Modes'. - (Major Mode Conventions): Correct xref. Explain how to handle - auto-mode-alist if the major mode command has an autoload cookie. - (Auto Major Mode): Major update. Add magic-mode-alist. - (Derived Modes): Major update. - (Mode Line Format): Update Menu. - (Mode Line Basics): New node, split off from `Mode Line Format'. - - * loading.texi (Autoload): Mention `autoload cookie' as synonym - for `magic autoload comment'. Add index entries and anchor. - -2005-05-14 Richard M. Stallman - - * tips.texi (Coding Conventions): Explain how important it is - that just loading certain files not change Emacs behavior. - - * modes.texi (Defining Minor Modes): Define define-global-minor-mode. - -2005-05-12 Lute Kamstra - - * modes.texi (Generic Modes): Update. - (Major Modes): Refer to node "Generic Modes". - - * elisp.texi (Top): Update to the current structure of the manual. - * processes.texi (Processes): Add menu description. - * customize.texi (Customization): Add menu descriptions. - -2005-05-11 Thien-Thi Nguyen - - * processes.texi (Signals to Processes) - (Low-Level Network): Fix typos. - -2005-05-11 Lute Kamstra - - * elisp.texi (Top): Add some nodes from the chapter "Major and - Minor Modes" to the detailed node listing. - -2005-05-10 Richard M. Stallman - - * keymaps.texi (Extended Menu Items): Menu item filter functions - can be called at any time. - -2005-05-08 Luc Teirlinck - - * variables.texi (File Local Variables): `(hack-local-variables t)' - now also checks whether a mode is specified in the local variables - list. - -2005-05-05 Kevin Ryde - - * display.texi (The Echo Area): Correct format function cross - reference. - -2005-05-05 Luc Teirlinck - - * variables.texi (Variable Aliases): Change description of - `define-obsolete-variable-alias'. - - * functions.texi (Functions): Add "Obsolete Functions" to menu. - (Defining Functions): Add xref. - (Obsolete Functions): New node. - (Function Safety): Standardize capitalization of section title. - - * frames.texi (Pop-Up Menus): Complete description of `x-popup-menu'. - (Dialog Boxes): Complete description of `x-popup-dialog'. - -2005-05-04 Richard M. Stallman - - * commands.texi (Interactive Codes): Fix Texinfo usage. - Document U more clearly. - -2005-05-01 Luc Teirlinck - - * variables.texi (Variable Aliases): `make-obsolete-variable' is a - function and not a macro. - - * frames.texi (Pop-Up Menus): Correct and clarify description of - `x-popup-menu'. - (Dialog Boxes): Clarify description of `x-popup-dialog'. - -2005-05-01 Richard M. Stallman - - * edebug.texi (Checking Whether to Stop): Fix previous change. - -2005-05-01 Luc Teirlinck - - * display.texi: Fix typos and Texinfo usage. - - * edebug.texi (Checking Whether to Stop): executing-macro -> - executing-kbd-macro. - -2005-05-01 Richard M. Stallman - - * display.texi (Invisible Text): Correct add-to-invisibility-spec. - -2005-04-30 Richard M. Stallman - - * files.texi (Magic File Names): Document `operations' property. - -2005-04-29 Lute Kamstra - - * modes.texi (Generic Modes): New node. - (Major Modes): Add it to the menu. - (Derived Modes): Add "derived mode" to concept index. - -2005-04-28 Lute Kamstra - - * modes.texi (Defining Minor Modes): Fix previous change. - (Font Lock Mode): Simplify. - (Font Lock Basics): Say that font-lock-defaults is buffer-local - when set and that some parts are optional. Add cross references. - (Search-based Fontification): Say how to specify font-lock-keywords. - Add cross references. Add font-lock-multiline to index. - Move font-lock-keywords-case-fold-search here from node "Other Font - Lock Variables". Document font-lock-add-keywords and - font-lock-remove-keywords. - (Other Font Lock Variables): Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function to node "Syntactic Font - Lock". Move font-lock-keywords-case-fold-search to node - "Search-based Fontification". Document font-lock-inhibit-thing-lock - and font-lock-{,un}fontify-{buffer,region}-function. - (Precalculated Fontification): Remove reference to deleted variable - font-lock-core-only. - (Faces for Font Lock): Add font-lock-comment-delimiter-face. - (Syntactic Font Lock): Add intro. Move font-lock-keywords-only, - font-lock-syntax-table, font-lock-beginning-of-syntax-function, - and font-lock-syntactic-face-function here from node "Other Font - Lock Variables". Move font-lock-syntactic-keywords to "Setting - Syntax Properties". Add cross references. - (Setting Syntax Properties): New node. - Move font-lock-syntactic-keywords here from "Syntactic Font Lock". - * syntax.texi (Syntax Properties): Add cross reference. - * hooks.texi (Standard Hooks): Add Font-Lock hooks. - -2005-04-26 Richard M. Stallman - - * display.texi (Defining Faces): - Document `default' elements of defface spec. - - * modes.texi (Major Mode Conventions): Explain customizing ElDoc mode. - - * variables.texi (Variable Aliases): Clarify text. - -2005-04-25 Chong Yidong - - * windows.texi (Window Hooks): Remove reference to obsolete Lazy Lock. - -2005-04-25 Luc Teirlinck - - * hooks.texi (Standard Hooks): Most minor modes have mode hooks too. - -2005-04-24 Eli Zaretskii - - * syntax.texi (Syntax Table Internals): Elaborate documentation of - syntax-after and syntax-class. - - * files.texi (Changing Files): Fix last change's cross-reference. - (Unique File Names): Don't mention "numbers" in the documentation - of make-temp-file and make-temp-name. - -2005-04-23 Richard M. Stallman - - * files.texi (Changing Files): Document MUSTBENEW arg in copy-file. - -2005-04-22 Nick Roberts - - * windows.texi (Cyclic Window Ordering): Clarify window-list. - -2005-04-22 Nick Roberts - - * variables.texi (Variable Aliases): Describe make-obsolete-variable - and define-obsolete-variable-alias. - -2005-04-22 Kim F. Storm - - * symbols.texi (Symbol Plists): Remove safe-get, as get is now safe. - (Other Plists): Remove safe-plist-get, as plist-get is now safe. - -2005-04-21 Lute Kamstra - - * lists.texi (Association Lists): Document rassq-delete-all. - -2005-04-19 Richard M. Stallman - - * modes.texi (Search-based Fontification): Explain that - facespec is an expression to be evaluated. - -2005-04-19 Kevin Ryde - - * streams.texi (Output Functions): Fix xref. - * strings.texi (String Conversion): Fix xref. - -2005-04-19 Kim F. Storm - - * symbols.texi (Symbol Plists): Add safe-get. - Mention that `get' may signal an error. - -2005-04-18 Nick Roberts - - * customize.texi (Variable Definitions): Replace tooltip-mode - example with save-place. - -2005-04-17 Richard M. Stallman - - * buffers.texi (Indirect Buffers): Clarify. - - * positions.texi (Positions): Clarify converting marker to integer. - - * strings.texi (String Basics): Mention string-match; clarify. - -2005-04-08 Lute Kamstra - - * modes.texi (Search-based Fontification): Fix cross references. - Use consistent terminology. Document anchored highlighting. - -2005-04-05 Lute Kamstra - - * modes.texi (Defining Minor Modes): Document :group keyword - argument and its default value. - -2005-04-03 Lute Kamstra - - * hooks.texi (Standard Hooks): Add some hooks. Add cross - references and/or descriptions. Delete major mode hooks; mention - them as a category instead. Rename or delete obsolete hooks. - -2005-04-02 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Another wording cleanup. - -2005-04-01 Richard M. Stallman - - * nonascii.texi (Coding System Basics): Clarify previous change. - -2005-04-01 Kenichi Handa - - * nonascii.texi (Coding System Basics): Describe about roundtrip - identity of coding systems. - -2005-03-29 Chong Yidong - - * text.texi (Buffer Contents): Add filter-buffer-substring and - buffer-substring-filters. - -2005-03-26 Chong Yidong - - * anti.texi (Antinews): Mention `G' interactive code. - - * tips.texi (Compilation Tips): Mention benchmark.el. - -2005-03-27 Luc Teirlinck - - * modes.texi (Other Font Lock Variables): `font-lock-fontify-block' - is now bound to M-o M-o. - - * keymaps.texi (Prefix Keys): `facemenu-keymap' is now on M-o. - -2005-03-26 Glenn Morris - - * calendar.texi: Delete file (and move contents to emacs-xtra.texi - in the Emacs Manual). - * Makefile.in (srcs): Remove calendar.texi. - * makefile.w32-in (srcs): Remove calendar.texi. - * display.texi (Display): Change name of next node. - * os.texi (System In): Change name of previous node. - * elisp.texi (Top): Remove Calendar references. - * vol1.texi (Top): Remove Calendar references. - * vol2.texi (Top): Remove Calendar references. - -2005-03-25 Richard M. Stallman - - * display.texi (Standard Faces, Fringe Bitmaps, Customizing Bitmaps): - Cleanup previous change. - -2005-03-25 Chong Yidong - - * display.texi (Face Attributes): Faces earlier in an :inherit - list take precedence. - (Scroll Bars): Fix description of vertical-scroll-bars. - Document frame-current-scroll-bars and window-current-scroll-bars. - - * markers.texi (The Mark): Document temporary Transient Mark mode. - - * minibuf.texi (Reading File Names): - Document read-file-name-completion-ignore-case. - - * positions.texi (Screen Lines): Document nil for width argument - to compute-motion. - -2005-03-23 Kim F. Storm - - * display.texi (Standard Faces): Other faces used in the fringe - implicitly inherits from the fringe face. - (Fringe Bitmaps): FACE in right-fringe and left-fringe display - properties implicitly inherits from fringe face. - (Customizing Bitmaps): Likewise for set-fringe-bitmap-face. - -2005-03-20 Chong Yidong - - * display.texi (Invisible Text): State default value of - line-move-ignore-invisible. - (Managing Overlays): Document remove-overlays. - (Standard Faces): Document escape-glyph face. - - * minibuf.texi (Reading File Names): Document read-file-name-function. - - * modes.texi (Other Font Lock Variables): - Document font-lock-lines-before. - - * positions.texi (Skipping Characters): skip-chars-forward allows - character classes. - -2005-03-18 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix another typo. - -2005-03-17 Richard M. Stallman - - * text.texi (Undo): Document extensible undo entries. - - * searching.texi (String Search, Regexp Search): Cleanups. - - * nonascii.texi (Character Codes): Minor fix. - - * display.texi (Display Property): Explain the significance - of having text properties that are eq. - (Other Display Specs): Explain string as display spec. - - * commands.texi (Interactive Codes): Document G option. - -2005-03-17 Chong Yidong - - * text.texi (Filling): Add sentence-end-without-period and - sentence-end-without-space. - (Changing Properties): Minor fix. - - * anti.texi: Total rewrite. - -2005-03-15 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typos. - -2005-03-08 Kim F. Storm - - * display.texi (Specified Space): Property :width is support on - non-graphic terminals, :height is not. - -2005-03-07 Richard M. Stallman - - * display.texi (Overlay Arrow, Fringe Bitmaps, Customizing Bitmaps): - Now subnodes of Fringes. - (Overlay Arrow): Document overlay-arrow-variable-list. - (Fringe Size/Pos): New node, broken out of Fringes. - (Display): Explain clearing vs redisplay better. - (Truncation): Clarify use of bitmaps. - (The Echo Area): Clarify the uses of the echo area. - Add max-mini-window-height. - (Progress): Clarify. - (Invisible Text): Explain that main loop moves point out. - (Selective Display): Say "hidden", not "invisible". - (Managing Overlays): Move up. Describe relation to Undo here. - (Overlay Properties): Clarify intro. - (Finding Overlays): Explain return values when nothing found. - (Width): truncate-string-to-width has added arg. - (Displaying Faces): Clarify and update mode line face handling. - (Face Functions): Minor cleanup. - (Conditional Display): Merge into Other Display Specs. - (Pixel Specification, Other Display Specs): Minor cleanups. - (Images, Image Descriptors): Minor cleanups. - (GIF Images): Patents have expired. - (Showing Images): Explain default text for insert-image. - (Manipulating Button Types): Merge into Manipulating Buttons. - (Making Buttons): Explain return values. - (Button Buffer Commands): Add xref. - (Inverse Video): Update mode-line-inverse-video. - (Display Table Format): Clarify. - (Active Display Table): Give defaults for window-display-table. - - * calendar.texi (Calendar Customizing): calendar-holiday-marker - and calendar-today-marker are strings, not chars. - (Holiday Customizing): Minor fix. - - * internals.texi (Writing Emacs Primitives): Update `or' example. - Update limit on # args of subr. - - * edebug.texi (Using Edebug): Arrow is in fringe. - (Instrumenting): Arg to eval-defun works without loading edebug. - (Edebug Execution Modes): Add xref. - - * customize.texi (Common Keywords): Clarify :require. - Mention :version here. - (Variable Definitions, Group Definitions): Not here. - (Variable Definitions): Clarify symbol arg to :initialize and :set fns. - -2005-03-07 Chong Yidong - * nonascii.texi (Text Representations): Clarify position-bytes. - (Character Sets): Add list-charset-chars. - (Scanning Charsets): Add charset-after. - (Encoding and I/O): Minor fix. - -2005-03-06 Richard M. Stallman - - * windows.texi (Vertical Scrolling): Get rid of "Emacs 21". - (Resizing Windows): Likewise. - - * text.texi (Change Hooks): Get rid of "Emacs 21". - - * strings.texi (Formatting Strings): Get rid of "Emacs 21". - - * streams.texi (Output Variables): Get rid of "Emacs 21". - - * searching.texi (Regexp Special, Char Classes): Get rid of "Emacs 21". - - * os.texi (Translating Input): Replace flow-control example - with a less obsolete example that uses `keyboard-translate'. - - * objects.texi (Hash Table Type, Circular Objects): - Get rid of "Emacs 21". - - * modes.texi (Mode Line Format): Get rid of "Emacs 21". - (Mode Line Data, Properties in Mode, Header Lines): Likewise. - - * minibuf.texi (Minibuffer Misc): Get rid of "Emacs 21". - - * lists.texi (List Elements, Building Lists): Get rid of "Emacs 21". - - * keymaps.texi (Menu Separators, Tool Bar): Get rid of "Emacs 21". - (Menu Bar): Fix when menu-bar-update-hook is called. - - * hash.texi (Hash Tables): Get rid of "Emacs 21". - - * frames.texi (Text Terminal Colors): Get rid of "Emacs 21", - and make it read better. - - * files.texi (Writing to Files): Get rid of "Emacs 21". - (Unique File Names): Likewise. - - * elisp.texi: Update Emacs version to 22. - - * display.texi (Forcing Redisplay): Get rid of "Emacs 21". - (Overlay Properties, Face Attributes): Likewise. - (Managing Overlays): Fix punctuation. - (Attribute Functions): Clarify set-face-font; get rid of - info about old Emacs versions. - (Auto Faces, Font Lookup, Display Property, Images): - Get rid of "Emacs 21". - - * calendar.texi (Calendar Customizing): Get rid of "Emacs 21". - -2005-03-05 Richard M. Stallman - - * debugging.texi (Error Debugging): Remove stack-trace-on-error. - -2005-03-04 Lute Kamstra - - * debugging.texi (Error Debugging): Document stack-trace-on-error. - -2005-03-03 Lute Kamstra - - * edebug.texi (Instrumenting Macro Calls): Fix typo. - -2005-03-01 Lute Kamstra - - * debugging.texi (Debugger Commands): Update `j'. - -2005-02-28 Lute Kamstra - - * debugging.texi (Debugging): Fix typo. - (Error Debugging): Document eval-expression-debug-on-error. - (Function Debugging): Update example. - (Using Debugger): Mention starred stack frames. - (Debugger Commands): Document `j' and `l'. - (Invoking the Debugger): `d' and `j' exit recursive edit too. - Update the messages that the debugger displays. - (Internals of Debugger): Add cross reference. Update example. - (Excess Open): Minor improvement. - (Excess Close): Minor improvement. - -2005-02-26 Richard M. Stallman - - * tips.texi (Coding Conventions): Clarify. - Put all the major mode key reservations together. - Mention the Mouse-1 => Mouse-2 conventions. - - * syntax.texi (Syntax Class Table): Clarify. - (Syntax Table Functions): syntax-after moved from here. - (Syntax Table Internals): syntax-after moved to here. - (Parsing Expressions): Update info on number of values - and what's meaningful in the STATE argument. - (Categories): Fix typo. - - * sequences.texi (Arrays): Cleanup. - (Char-Tables): Clarify. - - * processes.texi (Deleting Processes): Cleanups, add xref. - (Subprocess Creation): Explain nil in exec-path. Cleanup. - (Process Information): set-process-coding-system, some args optional. - (Input to Processes): Explain various types for PROCESS args. - Rename them from PROCESS-NAME to PROCESS. - (Signals to Processes): Likewise. - (Decoding Output): Cleanup. - (Query Before Exit): Clarify. - - * os.texi (Startup Summary): Correct the options; add missing ones. - (Terminal Output, Batch Mode): Clarify. - (Flow Control): Node deleted. - - * markers.texi (The Mark): Clarify. - - * macros.texi (Expansion): Cleanup. - (Indenting Macros): indent-spec allows ints, not floats. - - * keymaps.texi (Keymaps): Clarify. - (Format of Keymaps): Update lisp-mode-map example. - (Active Keymaps, Key Lookup): Clarify. - (Changing Key Bindings): Add xref to `kbd'. - (Key Binding Commands, Simple Menu Items): Clarify. - (Mouse Menus, Menu Bar): Clarify. - (Menu Example): Replace print example with menu-bar-replace-menu. - - * help.texi (Documentation Basics): Add function-documentation prop. - - * elisp.texi (Top): Don't refer to Flow Control node. - - * commands.texi (Command Overview): Improve xrefs. - (Adjusting Point): Adjusting point applies to intangible and invis. - (Key Sequence Input): Doc extra read-key-sequence args. - Likewise for read-key-sequence-vector. - - * backups.texi (Rename or Copy): Minor fix. - (Numbered Backups): For version-control, say the default. - (Auto-Saving): make-auto-save-file-name example is simplified. - - * advice.texi (Advising Functions): Don't imply one part of Emacs - should advise another part. Markup changes. - (Defining Advice): Move transitional para. - (Activation of Advice): Cleanup. - Explain if COMPILE is nil or negative. - - * abbrevs.texi (Abbrev Expansion): Clarify, fix typo. - -2005-02-24 Lute Kamstra - - * modes.texi (Defining Minor Modes): Explain that INIT-VALUE, - LIGHTER, and KEYMAP can be omitted when KEYWORD-ARGS are used. - -2005-02-23 Lute Kamstra - - * modes.texi (Defining Minor Modes): define-minor-mode can be used - to define global minor modes as well. - - * display.texi (Managing Overlays): overlay-buffer returns nil for - deleted overlays. - -2005-02-22 Kim F. Storm - - * minibuf.texi (Basic Completion): Allow symbols in addition to - strings in try-completion and all-completions. - -2005-02-14 Lute Kamstra - - * elisp.texi (Top): Remove reference to deleted node. - - * lists.texi (Lists): Remove reference to deleted node. - (Cons Cells): Fix typo. - - * loading.texi (Where Defined): Fix typo. - -2005-02-14 Richard M. Stallman - - * variables.texi (Creating Buffer-Local): change-major-mode-hook - is useful for discarding some minor modes. - - * symbols.texi (Symbol Components): Reorder examples. - - * streams.texi (Input Functions): State standard-input default. - (Output Variables): State standard-output default. - - * objects.texi (Printed Representation): Clarify read syntax vs print. - (Floating Point Type): Explain meaning better. - (Symbol Type): Explain uniqueness better. - (Cons Cell Type): Explain empty list sooner. CAR and CDR later. - List examples sooner. - (Box Diagrams): New subnode broken out. - Some examples moved from old Lists as Boxes node. - (Dotted Pair Notation): Clarify intro. - (Array Type): Clarify. - (Type Predicates): Add hash-table-p. - - * numbers.texi (Integer Basics): Clarify radix explanation. - (Predicates on Numbers): Minor clarification. - (Comparison of Numbers): Minor clarification. Clarify eql. - Typos in min, max. - (Math Functions): Clarify overflow in expt. - - * minibuf.texi (Text from Minibuffer): Minor clarification. - Mention arrow keys. - - * loading.texi (Autoload): defun's doc string overrides autoload's - doc string. - (Repeated Loading): Modernize "add to list" examples. - (Where Defined): Finish updating table of load-history elts. - - * lists.texi (List-related Predicates): Minor wording improvement. - (Lists as Boxes): Node deleted. - (Building Lists): Explain trivial cases of number-sequence. - - * hash.texi (Hash Tables): Add desc to menu items. - (Creating Hash): Explain "full" means "make larger". - (Hash Access): Any object can be a key. - State value of maphash. - - * functions.texi (What Is a Function): Wording cleanup. - (Function Documentation): Minor cleanup. - Explain purpose of calling convention at end of doc string. - (Function Names): Wording cleanup. - (Calling Functions): Wording cleanup. - Explain better how funcall calls the function. - (Function Cells): Delete example of saving and redefining function. - - * control.texi (Combining Conditions): Wording cleanup. - (Iteration): dolist and dotimes bind VAR locally. - (Cleanups): Xref to Atomic Changes. - - * compile.texi (Byte Compilation): Delete 19.29 info. - (Compilation Functions): Macros' difficulties don't affect defsubst. - (Docs and Compilation): Delete 19.29 info. - -2005-02-10 Richard M. Stallman - - * objects.texi (Symbol Type): Minor correction. - -2005-02-06 Lute Kamstra - - * modes.texi (Example Major Modes): Fix typos. - -2005-02-06 Richard M. Stallman - - * text.texi (Margins): fill-nobreak-predicate can be one function. - - * strings.texi (Modifying Strings): clear-string can make unibyte. - (Formatting Strings): format gives error if values missing. - - * positions.texi (Character Motion): Mention default arg - for forward-char. backward-char refers to forward-char. - (Word Motion): Mention default arg for forward-word. - (Buffer End Motion): Mention default arg for beginning-of-buffer. - Simplify end-of-buffer. - (Text Lines): Mention default arg for forward-line. - (List Motion): Mention default arg for beginning/end-of-defun. - (Skipping Characters): Minor fixes in explaining character-set. - - * modes.texi (Major Mode Conventions): Mention "system abbrevs". - Mode inheritance applies only when default-major-mode is nil. - Clarifications. - (Example Major Modes): Update Text mode and Lisp mode examples. - (Minor Mode Conventions): Mention define-minor-mode at top. - (Defining Minor Modes): In Hungry example, don't define C-M-DEL. - (Mode Line Format): Update mode line face display info. - (Properties in Mode): Mention effect of risky vars. - (Imenu): Define imenu-add-to-menubar. - (Font Lock Mode): Add descriptions to menu lines. - (Faces for Font Lock): Add font-lock-doc-face. - -2005-02-05 Lute Kamstra - - * text.texi (Maintaining Undo): Remove obsolete function. - -2005-02-05 Eli Zaretskii - - * frames.texi (Color Names): Add pointer to the X docs about RGB - color specifications. Improve indexing - (Text Terminal Colors): Replace the description of RGB values by - an xref to "Color Names". - -2005-02-03 Richard M. Stallman - - * windows.texi (Basic Windows): Add cursor-in-non-selected-windows. - Clarify. - (Selecting Windows): Clarify save-selected-window. - (Cyclic Window Ordering): Clarify walk-windows. - (Window Point): Clarify. - (Window Start): Add comment to example. - (Resizing Windows): Add `interactive' specs in examples. - Document fit-window-to-buffer. - - * text.texi (User-Level Deletion): just-one-space takes numeric arg. - (Undo, Maintaining Undo): Clarify last change. - (Sorting): In sort-numeric-fields, explain about octal and hex. - Mention sort-numeric-base. - (Format Properties): Add xref for hard newlines. - - * frames.texi (Window Frame Parameters): Explain pixel=char on tty. - (Pop-Up Menus): Fix typo. - (Color Names): Explain all types of color names. - Explain color-values on B&W terminal. - (Text Terminal Colors): Explain "rgb values" are lists. Fix arg names. - - * files.texi (File Locks): Not supported on MS systems. - (Testing Accessibility): Clarify. - - * edebug.texi (Printing in Edebug): Fix edebug-print-circle. - (Coverage Testing): Fix typo. - - * commands.texi (Misc Events): Remove stray space. - - * buffers.texi (Buffer Names): Clarify generate-new-buffer-name. - (Modification Time): Clarify when visited-file-modtime returns 0. - (The Buffer List): Clarify bury-buffer. - (Killing Buffers): Clarify. - (Indirect Buffers): Add clone-indirect-buffer. - -2005-02-02 Matt Hodges - - * edebug.texi (Printing in Edebug): Fix default value of - edebug-print-circle. - (Coverage Testing): Fix displayed frequency count data. - -2005-02-02 Luc Teirlinck - - * text.texi (Maintaining Undo): Add `undo-outer-limit'. - -2005-02-02 Kim F. Storm - - * text.texi (Undo) : Describe `apply' elements. - -2005-01-29 Eli Zaretskii - - * commands.texi (Misc Events): Describe the help-echo event. - - * text.texi (Special Properties) : Use `pos' - consistently in description of the help-echo property. - Use @code{nil} instead of @var{nil}. - - * display.texi (Overlay Properties): Fix the index entry for - help-echo overlay property. - - * customize.texi (Type Keywords): Uncomment the xref to the - help-echo property documentation. - -2005-01-23 Kim F. Storm - - * windows.texi (Window Start): Fix `pos-visible-in-window-p' - return value. Third element FULLY replaced by PARTIAL which - specifies number of invisible pixels if row is only partially visible. - (Textual Scrolling): Mention auto-window-vscroll. - (Vertical Scrolling): New defvar auto-window-vscroll. - -2005-01-16 Luc Teirlinck - - * keymaps.texi (Changing Key Bindings): `suppress-keymap' now uses - command remapping. - -2005-01-15 Richard M. Stallman - - * display.texi (Defining Images): Mention DATA-P arg of create-image. - -2005-01-14 Kim F. Storm - - * commands.texi (Accessing Events): Add WHOLE arg to posn-at-x-y. - - * text.texi (Links and Mouse-1): Fix string and vector item. - -2005-01-13 Richard M. Stallman - - * keymaps.texi (Active Keymaps): Rewrite the text, and update the - descriptions of overriding-local-map and overriding-terminal-local-map. - - * text.texi (Links and Mouse-1): Clarify text. - -2005-01-13 Kim F. Storm - - * modes.texi (Emulating Mode Line): Update format-mode-line entry. - -2005-01-13 Francis Litterio (tiny change) - - * keymaps.texi (Active Keymaps): Fix overriding-local-map description. - -2005-01-12 Kim F. Storm - - * text.texi (Links and Mouse-1): Rename section from Enabling - Mouse-1 to Following Links. Change xrefs. - Add examples for define-button-type and define-widget. - - * display.texi (Button Properties, Button Buffer Commands): - Clarify mouse-1 and follow-link functionality. - -2005-01-12 Richard M. Stallman - - * text.texi (Enabling Mouse-1 to Follow Links): Redo prev. change. - - * display.texi (Beeping): Fix Texinfo usage. - - * modes.texi (Emulating Mode Line): Doc FACE arg in format-header-line. - -2005-01-11 Kim F. Storm - - * display.texi (Button Properties, Button Buffer Commands): - Mention mouse-1 binding. Add follow-link keyword. - - * text.texi (Text Properties): Add "Enable Mouse-1" to submenu. - (Enabling Mouse-1 to Follow Links): New subsection. - -2005-01-06 Richard M. Stallman - - * text.texi (Special Properties): Minor change. - - * os.texi (Timers): Clarify previous change. - - * modes.texi (Emulating Mode Line): format-mode-line requires 1 arg. - -2005-01-01 Luc Teirlinck - - * display.texi (Face Attributes): Correct xref to renamed node. - -2005-01-01 Richard M. Stallman - - * display.texi (Face Attributes): Describe hex color specs. - -2004-12-31 Richard M. Stallman - - * os.texi (Timers): Update previous change. - -2004-12-30 Kim F. Storm - - * display.texi (Line Height): Total line-height is now specified - in line-height property of form (HEIGHT TOTAL). Swap (FACE . RATIO) - in cons cells. (nil . RATIO) is relative to actual line height. - Use line-height `t' instead of `0' to get minimum height. - -2004-12-29 Richard M. Stallman - - * os.texi (Timers): Discuss timers vs editing the buffer and undo. - -2004-12-28 Richard M. Stallman - - * commands.texi (Quitting): Clarify value of with-local-quit. - - * elisp.texi (Top): Fix previous change. - - * loading.texi (Loading): Fix previous change. - -2004-12-27 Richard M. Stallman - - * Makefile.in (MAKEINFO): Specify --force. - - * buffers.texi (Killing Buffers): Add buffer-save-without-query. - - * modes.texi (Emulating Mode Line): Document format's BUFFER arg. - - * display.texi (Line Height): Further clarify. - - * elisp.texi (Top): Update Loading submenu. - - * loading.texi (Where Defined): New node. - (Unloading): load-history moved to Where Defined. - -2004-12-21 Richard M. Stallman - - * commands.texi (Event Input Misc): Add while-no-input. - -2004-12-11 Richard M. Stallman - - * display.texi (Line Height): Rewrite text for clarity. - -2004-12-11 Kim F. Storm - - * display.texi (Display): Add node "Line Height" to menu. - (Line Height): New node. Move full description of line-spacing - and line-height text properties here from text.texi. - (Scroll Bars): Add vertical-scroll-bar variable. - - * frames.texi (Window Frame Parameters): Remove line-height defvar. - - * locals.texi (Standard Buffer-Local Variables): Fix xref for - line-spacing and vertical-scroll-bar. - - * text.texi (Special Properties): Just mention line-spacing and - line-height here, add xref to new "Line Height" node. - -2004-12-09 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): New @defvar for `line-spacing'. - - * locals.texi (Standard Buffer-Local Variables): - Add @xref for `line-spacing'. - -2004-12-05 Richard M. Stallman - - * Makefile.in (maintainer-clean): Remove the info files - in $(infodir) where they are created. - -2004-12-03 Richard M. Stallman - - * windows.texi (Selecting Windows): get-lru-window and - get-largest-window don't consider dedicated windows. - - * text.texi (Undo): Document undo-in-progress. - -2004-11-26 Richard M. Stallman - - * locals.texi (Standard Buffer-Local Variables): Undo prev change. - Remove a few vars that are not always buffer-local. - -2004-11-24 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): Comment out - xref's to non-existent node `Yet to be written'. - -2004-11-24 Richard M. Stallman - - * processes.texi (Synchronous Processes): Grammar fix. - - * numbers.texi (Comparison of Numbers): Add eql. - - * locals.texi (Standard Buffer-Local Variables): Add many vars. - - * intro.texi (Printing Notation): Fix previous change. - - * display.texi (Customizing Bitmaps): Move indicate-buffer-boundaries - and default-indicate-buffer-boundaries from here. - (Usual Display): To here. - (Scroll Bars): Add scroll-bar-mode and scroll-bar-width. - (Usual Display): Move tab-width up. - - * customize.texi (Variable Definitions): Replace - show-paren-mode example with tooltip-mode. - (Simple Types, Composite Types, Defining New Types): - Minor cleanups. - -2004-11-21 Jesper Harder - - * processes.texi (Synchronous Processes, Output from Processes): - Markup fix. - -2004-11-20 Richard M. Stallman - - * positions.texi (Skipping Characters): skip-chars-forward - now handles char classes. - - * intro.texi (Printing Notation): Avoid confusion of `print' - when explaining @print. - - * macros.texi (Argument Evaluation): Fix 1st `for' expansion example. - - * display.texi (Display Table Format): Minor fix. - - * streams.texi (Output Functions): Fix print example. - - * Makefile.in (elisp): New target. - (dist): Depend on $(infodir)/elisp, not elisp. - Copy the info files from $(infodir). - - * minibuf.texi (Text from Minibuffer): Document KEEP-ALL arg in - read-from-minibuffer. - - * searching.texi (Regexp Search): Rename that to search-spaces-regexp. - -2004-11-19 Richard M. Stallman - - * searching.texi (Regexp Search): Add search-whitespace-regexp. - -2004-11-19 CHENG Gao (tiny change) - - * tips.texi (Coding Conventions): Fix typo. - -2004-11-16 Richard M. Stallman - - * tips.texi (Coding Conventions): Separate defvar and require - methods to avoid warnings. Use require only when there are many - functions and variables from that package. - - * minibuf.texi (Minibuffer Completion): When ignoring case, - predicate must not be case-sensitive. - - * debugging.texi (Function Debugging, Explicit Debug): Clarified. - (Test Coverage): Don't talk about "splotches". Clarified. - -2004-11-16 Thien-Thi Nguyen - - * frames.texi (Window Frame Parameters): Fix typo. - -2004-11-15 Kim F. Storm - - * symbols.texi (Other Plists): Note that plist-get may signal error. - Add safe-plist-get. - -2004-11-15 Thien-Thi Nguyen - - * modes.texi (Font Lock Basics): Fix typo. - -2004-11-08 Richard M. Stallman - - * syntax.texi (Syntax Table Functions): Add syntax-after. - -2004-11-06 Lars Brinkhoff - - * os.texi (Processor Run Time): New section documenting - get-internal-run-time. - -2004-11-06 Eli Zaretskii - - * Makefile.in (install, maintainer-clean): Don't use "elisp-*" as - it nukes elisp-cover.texi. - (dist): Change elisp-[0-9] to elisp-[1-9], as there could be no - elisp-0 etc. - -2004-11-05 Luc Teirlinck - - * commands.texi (Keyboard Macros): Document `append' return value - of `defining-kbd-macro'. - -2004-11-01 Richard M. Stallman - - * commands.texi (Interactive Call): Add called-interactively-p. - -2004-10-29 Simon Josefsson - - * minibuf.texi (Reading a Password): Revert. - -2004-10-28 Richard M. Stallman - - * frames.texi (Display Feature Testing): Explain about "vendor". - -2004-10-27 Richard M. Stallman - - * commands.texi (Interactive Codes): `N' uses numeric prefix, - not raw. Clarify `n'. - (Interactive Call): Rewrite interactive-p, focusing on when - and how to use it. - (Misc Events): Clarify previous change. - - * advice.texi (Simple Advice): Clarify what job the example does. - (Around-Advice): Clarify ad-do-it. - (Activation of Advice): An option of ad-default-compilation-action - is `never', not `nil'. - -2004-10-26 Kim F. Storm - - * commands.texi (Interactive Codes): Add U code letter. - -2004-10-25 Simon Josefsson - - * minibuf.texi (Reading a Password): Add. - -2004-10-24 Jason Rumney - - * commands.texi (Misc Events): Remove mouse-wheel. Add wheel-up - and wheel-down. - -2004-10-24 Kai Grossjohann - - * processes.texi (Synchronous Processes): Document process-file. - -2004-10-22 Kenichi Handa - - * text.texi (translate-region): Document that it accepts also a - char-table. - -2004-10-22 David Ponce - - * windows.texi (Resizing Windows): Document the `preserve-before' - argument of the functions `enlarge-window' and `shrink-window'. - -2004-10-19 Jason Rumney - - * makefile.w32-in (elisp): Change order of arguments to makeinfo. - -2004-10-09 Luc Teirlinck - - * text.texi (Filling): Add anchor for definition of - `sentence-end-double-space'. - - * searching.texi (Regexp Example): Update description of how - Emacs currently recognizes the end of a sentence. - (Standard Regexps): Update definition of the variable - `sentence-end'. Add definition of the function `sentence-end'. - -2004-10-08 Paul Pogonyshev - - * display.texi (Progress): New node. - -2004-10-05 Kim F. Storm - - * display.texi (Fringe Bitmaps): Update fringe-bitmaps-at-pos. - -2004-09-29 Kim F. Storm - - * display.texi (Fringe Bitmaps): Use symbols rather than numbers - to identify bitmaps. Remove -fringe-bitmap suffix for standard - fringe bitmap symbols, as they now have their own namespace. - (Customizing Bitmaps) : Clarify bit ordering - vs. pixels. Signal error if no free bitmap slots. - (Pixel Specification): Change IMAGE to @var{image}. - -2004-09-28 Richard M. Stallman - - * text.texi (Special Properties): Clarify line-spacing and line-height. - - * searching.texi (Regexp Search): Add looking-back. - -2004-09-25 Luc Teirlinck - - * display.texi: Correct typos. - (Image Descriptors): Correct xref's. - -2004-09-25 Richard M. Stallman - - * text.texi (Special Properties): Cleanups in `cursor'. - Rewrites in `line-height' and `line-spacing'; exchange them. - - * display.texi (Fringes): Rewrite previous change. - (Fringe Bitmaps): Merge text from Display Fringe Bitmaps. Rewrite. - (Display Fringe Bitmaps): Node deleted, text moved. - (Customizing Bitmaps): Split off from Fringe Bitmaps. Rewrite. - (Scroll Bars): Clarify set-window-scroll-bars. - (Pointer Shape): Rewrite. - (Specified Space): Clarify :align-to, etc. - (Pixel Specification): Use @var. Clarify new text. - (Other Display Specs): Clarify `slice'. - (Image Descriptors): Cleanups. - (Showing Images): Cleanups. - -2004-09-24 Luc Teirlinck - - * hooks.texi (Standard Hooks): Add `after-change-major-mode-hook'. - - * modes.texi: Various minor changes in addition to: - (Major Mode Conventions): Final call to `run-mode-hooks' should - not be inside the `delay-mode-hooks' form. - (Mode Hooks): New node. - (Hooks): Delete obsolete example. - Move definitions of `run-mode-hooks' and `delay-mode-hooks' to new - node "Mode Hooks". - -2004-09-22 Luc Teirlinck - - * display.texi: Correct various typos. - (Display): Rename node "Pointer Shapes" to "Pointer - Shape". (There is already a node called "Pointer Shapes" in - frames.texi.) - (Images): Remove non-existent node "Image Slices" from menu. - -2004-09-23 Kim F. Storm - - * text.texi (Special Properties): Add `cursor', `pointer', - `line-height', and `line-spacing' properties. - - * display.texi (Display): Add 'Fringe Bitmaps' and 'Pointer - Shapes' to menu. - (Standard Faces): Doc fix for fringe face. - (Fringes): Add `overflow-newline-into-fringe' and - 'indicate-buffer-boundaries'. - (Fringe Bitmaps, Pointer Shapes): New nodes. - (Display Property): Add 'Pixel Specification' and 'Display Fringe - Bitmaps' to menu. - (Specified Space): Describe pixel width and height. - (Pixel Specification): New node. - (Other Display Specs): Add `slice' property. - (Display Fringe Bitmaps): New node. - (Images): Add 'Image Slices' to menu. - (Image Descriptors): Add `:pointer' and `:map' properties. - (Showing Images): Add slice arg to `insert-image'. Add - 'insert-sliced-image'. - -2004-09-20 Richard M. Stallman - - * commands.texi (Key Sequence Input): - Clarify downcasing in read-key-sequence. - -2004-09-08 Juri Linkov - - * minibuf.texi (Minibuffer History): Add `history-delete-duplicates'. - -2004-09-07 Luc Teirlinck - - * locals.texi (Standard Buffer-Local Variables): Add - `buffer-auto-save-file-format'. - * internals.texi (Buffer Internals): Describe new - auto_save_file_format field of the buffer structure. - * files.texi (Format Conversion): `auto-save-file-format' has been - renamed `buffer-auto-save-file-format'. - -2004-08-27 Luc Teirlinck - - * abbrevs.texi (Abbrev Expansion): `abbrev-start-location' can be - an integer or a marker. - (Abbrev Expansion): Replace example for `pre-abbrev-expand-hook'. - -2004-08-22 Richard M. Stallman - - * modes.texi (Major Mode Conventions): Discuss rebinding of - standard key bindings. - -2004-08-18 Kim F. Storm - - * processes.texi (Accepting Output): Add `just-this-one' arg to - `accept-process-output'. - (Output from Processes): New var `process-adaptive-read-buffering'. - -2004-08-10 Luc Teirlinck - - * keymaps.texi: Various changes in addition to: - (Keymap Terminology): `kbd' uses same syntax as Edit Macro mode. - Give more varied examples for `kbd'. - (Creating Keymaps): Char tables have slots for all characters - without modifiers. - (Active Keymaps): `overriding-local-map' and - `overriding-terminal-local-map' also override text property and - overlay keymaps. - (Functions for Key Lookup): Mention OLP arg to `current-active-maps'. - (Scanning Keymaps): `accessible-keymaps' uses `[]' instead of `""' - to denote a prefix of no events. - `map-keymap' includes parent's bindings _recursively_. - Clarify and correct description of `where-is-internal'. - Mention BUFFER-OR-NAME arg to `describe-bindings'. - (Menu Example): For menus intended for use with the keyboard, the - menu items should be bound to characters or real function keys. - -2004-08-08 Luc Teirlinck - - * objects.texi (Character Type): Reposition `@anchor' to prevent - double space inside sentence in Info. - - * hooks.texi (Standard Hooks): `disabled-command-hook' has been - renamed to `disabled-command-function'. - * commands.texi (Key Sequence Input): Remove unnecessary anchor. - (Command Loop Info): Replace reference to it. - (Disabling Commands): `disabled-command-hook' has been renamed to - `disabled-command-function'. - -2004-08-07 Luc Teirlinck - - * os.texi (Translating Input): Only non-prefix bindings in - `key-translation-map' override actual key bindings. Warn about - possible indirect effect of actual key bindings on non-prefix - bindings in `key-translation-map'. - -2004-08-06 Luc Teirlinck - - * minibuf.texi (High-Level Completion): Add anchor for definition - of `read-variable'. - - * commands.texi: Various changes in addition to: - (Using Interactive): Clarify description of `interactive-form'. - (Interactive Call): Mention default for KEYS argument to - `call-interactively'. - (Command Loop Info): Clarify description of `this-command-keys'. - Mention KEEP-RECORD argument to `clear-this-command-keys'. - Value of `last-event-frame' can be `macro'. - (Repeat Events): `double-click-fuzz' is also used to distinguish - clicks and drags. - (Classifying Events): Clarify descriptions of `event-modifiers' - `event-basic-type' and `event-convert-list'. - (Accessing Events): `posn-timestamp' takes POSITION argument. - (Quoted Character Input): Clarify description of - `read-quoted-char' and fix example. - (Quitting): Add `with-local-quit'. - (Disabling Commands): Correct and clarify descriptions of - `enable-command' and `disable-command'. - Mention what happens if `disabled-command-hook' is nil. - (Keyboard Macros): Mention LOOPFUNC arg to `execute-kbd-macro'. - Describe `executing-kbd-macro' instead of obsolete `executing-macro'. - -2004-07-24 Luc Teirlinck - - * frames.texi: Various changes in addition to: - (Creating Frames): Expand and clarify description of `make-frame'. - (Window Frame Parameters): Either none or both of the `icon-left' - and `icon-top' parameters must be specified. Put descriptions of - `menu-bar-lines' and `toolbar-lines' closer together and change - them accordingly. - (Frame Titles): `multiple-frames' is not guaranteed to be accurate - except while processing `frame-title-format' or `icon-title-format'. - (Deleting Frames): Correct description of `delete-frame'. - Non-nil return values of `frame-live-p' are like those of `framep'. - (Frames and Windows): Mention return value of - `set-frame-selected-window'. - (Visibility of Frames): Mention `force' argument to - `make-frame-invisible'. `frame-visible-p' returns t for all - frames on text-only terminals. - (Frame Configurations): Restoring a frame configuration does not - restore deleted frames. - (Window System Selections): `x-set-selection' returns DATA. - (Resources): Add example. - (Display Feature Testing): Clarify descriptions of - `display-pixel-height', `display-pixel-width', `x-server-version' - and `x-server-vendor'. - - * windows.texi (Choosing Window): Add anchor. - * minibuf.texi (Minibuffer Misc): Add anchor. - -2004-07-23 John Paul Wallington - - * macros.texi (Defining Macros): Declaration keyword for setting - Edebug spec is `debug' not `edebug'. - -2004-07-19 Luc Teirlinck - - * windows.texi: Various small changes in addition to: - (Window Point): Mention return value of `set-window-point'. - (Window Start): `pos-visible-in-window-p' disregards horizontal - scrolling. Explain return value if PARTIALLY is non-nil. - (Vertical Scrolling): Mention PIXELS-P argument to `window-vscroll' - and `set-window-vscroll'. - (Size of Window): The argument WINDOW to `window-inside-edges', - `window-pixel-edges' and `window-inside-pixel-edges' is optional. - (Resizing Windows): Explain return value of - `shrink-window-if-larger-than-buffer'. - `window-size-fixed' automatically becomes buffer local when set. - (Window Configurations): Explain return value of - `set-window-configuration'. - - * minibuf.texi (Minibuffer Misc): Add anchor for - `minibuffer-scroll-window'. - - * positions.texi (Text Lines): Add anchor for `count-lines'. - -2004-07-17 Richard M. Stallman - - * display.texi (Overlay Properties): Adding `evaporate' prop - deletes empty overlay immediately. - - * abbrevs.texi (Abbrev Expansion): Clarify pre-abbrev-expand-hook, - fix example. - -2004-07-16 Jim Blandy - - * searching.texi (Regexp Backslash): Document new \_< and \_> - operators. - -2004-07-16 Juanma Barranquero - - * display.texi (Images): Fix Texinfo usage. - -2004-07-14 Luc Teirlinck - - * buffers.texi (Modification Time): `visited-file-modtime' now - returns a list of two integers, instead of a cons. - -2004-07-13 Luc Teirlinck - - * windows.texi: Various changes in addition to: - (Splitting Windows): Add `split-window-keep-point'. - -2004-07-09 Richard M. Stallman - - * frames.texi (Input Focus): Minor fix. - -2004-07-07 Luc Teirlinck - - * frames.texi (Input Focus): Clarify descriptions of - `select-frame-set-input-focus' and `select-frame'. - -2004-07-06 Luc Teirlinck - - * os.texi: Various small changes in addition to: - (Killing Emacs): Expand and clarify description of - `kill-emacs-query-functions' and `kill-emacs-hook'. - (System Environment): Expand and clarify description of `getenv' - and `setenv'. - (Timers): Clarify description of `run-at-time'. - (Translating Input): Correct description of - `extra-keyboard-modifiers'. - (Flow Control): Correct description of `enable-flow-control'. - -2004-07-06 Thien-Thi Nguyen - - * os.texi: Update copyright. - (Session Management): Grammar fix. - Clarify which Emacs does the restarting. - Use @samp for *scratch* buffer. - -2004-07-04 Alan Mackenzie - - * frames.texi (Input Focus): Add documentation for - `select-frame-set-input-focus'. Replace refs to non-existent - `switch-frame' with `select-frame'. Minor corrections and tidying - up of text-only terminal stuff. - -2004-07-02 Richard M. Stallman - - * files.texi (Saving Buffers): Cleanup write-contents-function. - (Magic File Names): Cleanup file-remote-p. - -2004-07-02 Kai Großjohann - - * files.texi (Magic File Names): `file-remote-p' returns an - identifier of the remote system, not just t. - -2004-07-02 David Kastrup - - * searching.texi (Entire Match Data): Add explanation about new - match-data behavior when @var{integers} is non-nil. - -2004-06-24 Richard M. Stallman - - * commands.texi (Misc Events): Describe usr1-signal, usr2-signal event. - - * customize.texi (Variable Definitions): Note about doc strings - and :set. - - * keymaps.texi (Keymap Terminology): Document `kbd'. - (Changing Key Bindings, Key Binding Commands): Use kbd in examples. - - * display.texi (Invisible Text): Setting buffer-invisibility-spec - makes it buffer-local. - - * files.texi (Saving Buffers): Correct previous change. - - * commands.texi (Accessing Events): - Clarify posn-col-row and posn-actual-col-row. - -2004-06-24 David Ponce - - * commands.texi (Accessing Events): New functions - posn-at-point and posn-at-x-y. Add example to posn-x-y. - -2004-06-23 Luc Teirlinck - - * lists.texi, files.texi, processes.texi, macros.texi, hash.texi: - * frames.texi, buffers.texi, backups.texi, variables.texi: - * loading.texi, eval.texi, functions.texi, control.texi: - * symbols.texi, minibuf.texi: Reposition @anchor's. - - * help.texi: Various small changes in addition to the following. - (Describing Characters): Describe PREFIX argument to - `key-description'. Correct and clarify definition of - `text-char-description'. Describe NEED-VECTOR argument to - `read-kbd-macro'. - (Help Functions): Clarify definition of `apropos'. - -2004-06-23 Lars Hansen - - * files.texi (Saving Buffers): Correct description of - `write-contents-functions'. - -2004-06-21 Juanma Barranquero - - * display.texi (Images): Remove redundant @vindex directives. - Rewrite `image-library-alist' doc in active voice. - -2004-06-14 Juanma Barranquero - - * display.texi (Images): Document new delayed library loading, - variable `image-library-alist' and (existing but undocumented) - function `image-type-available-p'. - -2004-06-05 Richard M. Stallman - - * minibuf.texi (Minibuffer Completion): For INITIAL arg, - refer the user to the Initial Input node. - (Text from Minibuffer): Likewise. - (Initial Input): New node. Document this feature - and say it is mostly deprecated. - -2004-05-30 Richard M. Stallman - - * loading.texi (Named Features): Clarify return value - and meaning of NOERROR. - - * variables.texi (File Local Variables): Minor cleanup. - -2004-05-30 Michael Albinus - - * files.texi (Magic File Names): Add `file-remote-p' as operation - of file name handlers. - -2004-05-29 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): (-) has no special meaning - as arg to a minor mode command. - -2004-05-22 Richard M. Stallman - - * syntax.texi (Syntax Class Table): Word syntax not just for English. - - * streams.texi (Output Variables): Doc float-output-format. - - * searching.texi (Regexp Special): Nested repetition can be infloop. - - * eval.texi (Eval): Increasing max-lisp-eval-depth can cause - real stack overflow. - - * compile.texi: Minor cleanups. - -2004-05-22 Luc Teirlinck - - * lists.texi (Cons Cells): Explain dotted lists, true lists, - circular lists. - (List Elements): Explain handling of circular and dotted lists. - -2004-05-19 Thien-Thi Nguyen - - * modes.texi (Search-based Fontification): Fix typo. - -2004-05-10 Juanma Barranquero - - * modes.texi (Mode Line Variables): Fix description of - global-mode-string, which is now after which-func-mode, not the - buffer name. - -2004-05-07 Lars Hansen - - * modes.texi (Desktop Save Mode): Add. - (Modes): Add menu entry Desktop Save Mode. - - * hooks.texi: Add desktop-after-read-hook, - desktop-no-desktop-file-hook and desktop-save-hook. - - * locals.texi: Add desktop-save-buffer. - -2004-04-30 Jesper Harder - - * display.texi: emacs -> Emacs. - -2004-04-27 Matthew Mundell - - * files.texi (Changing Files): Document set-file-times. - -2004-04-23 Juanma Barranquero - - * makefile.w32-in: Add "-*- makefile -*-" mode tag. - -2004-04-18 Jesper Harder - - * tips.texi (Coding Conventions): defopt -> defcustom. - -2004-04-16 Luc Teirlinck - - * sequences.texi: Various clarifications. - -2004-04-14 Luc Teirlinck - - * buffers.texi (Read Only Buffers): Mention optional ARG to - `toggle-read-only'. - -2004-04-14 Nick Roberts - - * windows.texi (Selecting Windows): Note that get-lru-window - returns a full-width window if possible. - -2004-04-13 Luc Teirlinck - - * buffers.texi: Various changes in addition to: - (Buffer File Name): Add `find-buffer-visiting'. - (Buffer Modification): Mention optional ARG to `not-modified'. - (Indirect Buffers): Mention optional CLONE argument to - `make-indirect-buffer'. - - * files.texi: Various changes in addition to: - (Visiting Functions): `find-file-hook' is now a normal hook. - (File Name Expansion): Explain difference between the way that - `expand-file-name' and `file-truename' treat `..'. - (Contents of Directories): Mention optional ID-FORMAT argument to - `directory-files-and-attributes'. - (Format Conversion): Mention new optional CONFIRM argument to - `format-write-file'. - -2004-04-12 Miles Bader - - * macros.texi (Expansion): Add description of `macroexpand-all'. - -2004-04-05 Jesper Harder - - * variables.texi (Variable Aliases): Mention - cyclic-variable-indirection. - - * errors.texi (Standard Errors): Ditto. - -2004-04-04 Luc Teirlinck - - * backups.texi: Various small changes in addition to: - (Making Backups): Mention return value of `backup-buffer'. - (Auto-Saving): Mention optional FORCE argument to - `delete-auto-save-file-if-necessary'. - (Reverting): Mention optional PRESERVE-MODES argument to - `revert-buffer'. Correct description of `revert-buffer-function'. - -2004-03-22 Juri Linkov - - * sequences.texi (Sequence Functions): Replace xref to `Vectors' - with `Vector Functions'. - - * text.texi (Sorting): Add missing quote. - -2004-03-14 Luc Teirlinck - - * intro.texi (Lisp History): Replace xref to `cl' manual with - inforef. - -2004-03-12 Richard M. Stallman - - * intro.texi (Version Info): Add arg to emacs-version. - (Lisp History): Change xref to CL manual. - -2004-03-09 Luc Teirlinck - - * minibuf.texi (Completion Commands): Add xref to Emacs manual - for Partial Completion mode. - -2004-03-07 Thien-Thi Nguyen - - * customize.texi: Fix typo. Remove eol whitespace. - -2004-03-04 Richard M. Stallman - - * processes.texi: Fix typos. - - * lists.texi (Building Lists): Minor clarification. - - * hash.texi (Creating Hash): Correct the meaning of t for WEAK - in make-hash-table. - -2004-02-29 Juanma Barranquero - - * makefile.w32-in (clean, maintainer-clean): Use $(DEL) instead of - rm, and ignore exit code. - -2004-02-27 Dan Nicolaescu - - * display.texi (Defining Faces): Add description for min-colors. - Update example. - -2004-02-23 Luc Teirlinck - - * abbrevs.texi: Various corrections and clarifications in addition - to the following: - (Abbrev Tables): Delete add-abbrev (as suggested by RMS). - -2004-02-22 Matthew Mundell (tiny change) - - * calendar.texi (Holiday Customizing): Quote arg of holiday-sexp. - -2004-02-21 Luc Teirlinck - - * text.texi: Various small changes in addition to the following: - (User-Level Deletion): Mention optional BACKWARD-ONLY argument - to delete-horizontal-space. - (Kill Functions, Yanking, Low-Level Kill Ring): Clarify and correct - description of yank-handler text property at various places. - - * frames.texi (Window System Selections): Add anchor. - - * syntax.texi (Syntax Table Functions): Clarify and correct - descriptions of make-syntax-table and copy-syntax-table. - (Motion and Syntax): Clarify SYNTAXES argument to - skip-syntax-forward. - (Parsing Expressions): Mention that the return value of - parse-partial-sexp is currently a list of ten rather than nine - elements. - (Categories): Various corrections and clarifications. - -2004-02-17 Luc Teirlinck - - * markers.texi (Marker Insertion Types): Minor change. - - * locals.texi (Standard Buffer-Local Variables): - * commands.texi (Interactive Codes, Using Interactive): - * functions.texi (Related Topics): Fix xrefs. - -2004-02-16 Luc Teirlinck - - * lists.texi (Sets And Lists): Update description of delete-dups. - -2004-02-16 Jesper Harder (tiny change) - - * keymaps.texi (Tool Bar): tool-bar-item => tool-bar-button. - -2004-02-16 Jan Djärv - - * frames.texi (Parameter Access): frame-parameters arg is optional. - modify-frame-parameters handles nil for FRAME. - (Window Frame Parameters): menu-bar-lines and tool-bar-lines - are all-or-nothing for certain toolkits. - Mention parameter wait-for-wm. - (Frames and Windows): In frame-first-window and frame-selected-window - the arg is optional. - (Input Focus): In redirect-frame-focus the second arg is optional. - (Window System Selections): Mention selection type CLIPBOARD. - Mention data-type UTF8_STRING. - Mention numbering of cut buffers. - (Resources): Describe x-resource-name. - -2004-02-16 Richard M. Stallman - - * windows.texi (Buffers and Windows): Delete false table - about all-frames. - - * syntax.texi (Parsing Expressions): Delete old caveat - about parse-sexp-ignore-comments. - - * streams.texi (Output Variables): Add print-quoted. - - * lists.texi (Building Lists): Minor cleanup. - - * hash.texi (Creating Hash): Correct and clarify doc of WEAK values. - - * display.texi (Overlays): Explain overlays use markers. - (Managing Overlays): Explain front-advance and rear-advance - in more detail. - - * loading.texi (Unloading): Document unload-feature-special-hooks. - Get rid of fns-NNN.el file. - -2004-02-16 Matthew Mundell (tiny change) - - * help.texi (Describing Characters): Fix text-char-description - example output. - - * edebug.texi (Using Edebug): Fix example. - - * debugging.texi (Internals of Debugger): Fix return value. - - * files.texi (Changing Files): Fix argname. - - * calendar.texi: Fix parens, and default values. - - * display.texi, frames.texi, internals.texi, modes.texi: Minor fixes. - * nonascii.texi, objects.texi, os.texi: Minor fixes. - * searching.texi, text.texi, tips.texi, windows.texi: Minor fixes. - - * positions.texi (Text Lines): Don't add -1 in current-line. - -2004-02-16 Richard M. Stallman - - * compile.texi (Compiler Errors): if-boundp feature applies to cond. - -2004-02-16 Jesper Harder (tiny change) - - * processes.texi (Low-Level Network): Fix a typo. - -2004-02-12 Kim F. Storm - - * display.texi (Fringes): Use consistent wording. - Note that window-fringe's window arg is optional. - (Scroll Bars): Use consistent wording. - -2004-02-11 Luc Teirlinck - - * tips.texi (Comment Tips): Document the new conventions for - commenting out code. - -2004-02-07 Jan Djärv - - * positions.texi (Text Lines): Added missing end defun. - -2004-02-07 Kim F. Storm - - * positions.texi (Text Lines): Add line-number-at-pos. - -2004-02-06 John Paul Wallington - - * display.texi (Button Properties, Button Buffer Commands): - mouse-2 invokes button, not down-mouse-1. - -2004-02-04 Jason Rumney - - * makefile.w32-in: Sync with Makefile.in changes. - -2004-02-03 Luc Teirlinck - - * minibuf.texi (Text from Minibuffer): Various corrections and - clarifications. - (Object from Minibuffer): Correct Lisp description of - read-minibuffer. - (Minibuffer History): Clarify description of cons values for - HISTORY arguments. - (Basic Completion): Various corrections and clarifications. Add - completion-regexp-list. - (Minibuffer Completion): Correct and clarify description of - completing-read. - (Completion Commands): Mention Partial Completion mode. Various - other minor changes. - (High-Level Completion): Various corrections and clarifications. - (Reading File Names): Ditto. - (Minibuffer Misc): Ditto. - -2004-01-26 Luc Teirlinck - - * strings.texi (Text Comparison): assoc-string also matches - elements of alists that are strings instead of conses. - (Formatting Strings): Standardize Texinfo usage. Update index - entries. - -2004-01-20 Luc Teirlinck - - * lists.texi (Sets And Lists): Add delete-dups. - -2004-01-15 Luc Teirlinck - - * edebug.texi (Instrumenting Macro Calls): `declare' is not a - special form. - * macros.texi (Defining Macros): Update description of `declare', - which now is a macro. - (Wrong Time): Fix typos. - -2004-01-14 Luc Teirlinck - - * compile.texi (Compilation Functions): Expand descriptions of - `compile-defun', `byte-compile-file', `byte-recompile-directory' - and `batch-byte-compile'. In particular, mention and describe - all optional arguments. - (Disassembly): Correct and clarify the description of `disassemble'. - -2004-01-11 Luc Teirlinck - - * searching.texi: Various small changes in addition to the - following. - (Regexp Example): Adapt to new value of `sentence-end'. - (Regexp Functions): The PAREN argument to `regexp-opt' can be - `words'. - (Search and Replace): Add usage note for `perform-replace'. - (Entire Match Data): Mention INTEGERS and REUSE arguments to - `match-data'. - (Standard Regexps): Update for new values of `paragraph-start' - and `sentence-end'. - -2004-01-07 Luc Teirlinck - - * files.texi (Saving Buffers): Clarify descriptions of - `write-contents-functions' and `before-save-hook'. - Make the defvar's for `before-save-hook' and `after-save-hook' - into defopt's. - -2004-01-07 Kim F. Storm - - * commands.texi (Click Events): Describe new image and - width/height elements of click events. - (Accessing Events): Add posn-string, posn-image, and - posn-object-width-height. Change posn-object to return either - image or string object. - -2004-01-01 Simon Josefsson - - * hooks.texi (Standard Hooks): Add before-save-hook. - * files.texi (Saving Buffers): Likewise. - -2004-01-03 Richard M. Stallman - - * frames.texi (Frames and Windows): Delete frame-root-window. - -2004-01-03 Luc Teirlinck - - * eval.texi, hash.texi, help.texi, symbols.texi: Add anchors. - - * functions.texi: Various small changes in addition to the - following. - (What Is a Function): `functionp' returns nil for macros. Clarify - behavior of this and following functions for symbol arguments. - (Function Documentation): Add `\' in front of (fn @var{arglist}) - and explain why. - (Defining Functions): Mention DOCSTRING argument to `defalias'. - Add anchor. - (Mapping Functions): Add anchor. Unquote nil in mapcar* example. - -2004-01-01 Miles Bader - - * display.texi (Buttons): New section. - -2003-12-31 Andreas Schwab - - * numbers.texi (Math Functions): sqrt reports a domain-error - error. - (Float Basics): Use `(/ 0.0 0.0)' instead of `(sqrt -1.0)'. - -2003-12-30 Luc Teirlinck - - * tips.texi (Documentation Tips): Update item on hyperlinks in - documentation strings. - - * errors.texi (Standard Errors): Various small corrections and - additions. - - * control.texi: Various small changes in addition to the - following. - (Signaling Errors): Provide some more details on how `signal' - constructs the error message. Add anchor to the definition of - `signal'. - (Error Symbols): Describe special treatment of `quit'. - (Cleanups): Rename BODY argument of `unwind-protect' to BODY-FORM - to emphasize that it has to be a single form. - - * buffers.texi: Add anchor. - -2003-12-29 Richard M. Stallman - - * windows.texi (Choosing Window): Add same-window-p, special-display-p. - (Window Configurations): Add window-configuration-frame. - - * variables.texi (Creating Buffer-Local): Add local-variable-if-set-p. - - * text.texi (Examining Properties): Add get-char-property-and-overlay. - Change arg name in get-char-property. - (Special Properties): Update handling of keymap property. - - * strings.texi (Modifying Strings): Add clear-string. - (Text Comparison): Add assoc-string and remove - assoc-ignore-case, assoc-ignore-representation. - - * os.texi (Time of Day): Add set-time-zone-rule. - - * numbers.texi (Math Functions): asin, acos, log, log10 - report domain-error errors. - - * nonascii.texi (Converting Representations): - Add multibyte-char-to-unibyte and unibyte-char-to-multibyte. - (Encoding and I/O): Add file-name-coding-system. - - * modes.texi (Search-based Fontification): Explain that - face specs are symbols with face names as values. - - * minibuf.texi (Minibuffer Misc): Add set-minibuffer-window. - - * lists.texi (Building Lists): remq moved elsewhere. - (Sets And Lists): remq moved here. - (Association Lists): Refer to assoc-string. - - * internals.texi (Garbage Collection): Add memory-use-counts. - - * frames.texi (Frames and Windows): Add set-frame-selected-window - and frame-root-window. - - * files.texi (Contents of Directories): - Add directory-files-and-attributes. - - * display.texi (Refresh Screen): Add force-window-update. - (Invisible Text): Explain about moving point out of invis text. - (Overlay Properties): Add overlay-properties. - (Managing Overlays): Add overlayp. - (GIF Images): Invalid image number displays a hollow box. - - * buffers.texi (Buffer Modification): Add restore-buffer-modified-p. - (Killing Buffers): Add buffer-live-p. - -2003-12-25 Markus Rost - - * display.texi (Fringes): Fix typo "set-buffer-window". - -2003-12-24 Luc Teirlinck - - * display.texi, eval.texi, help.texi, internals.texi, loading.texi: - * nonascii.texi, processes.texi, tips.texi, variables.texi: - Add or change various xrefs and anchors. - - * commands.texi: Replace all occurrences of @acronym{CAR} with - @sc{car}, for consistency with the rest of the Elisp manual. - `car' and `cdr' are historically acronyms, but are no longer - widely thought of as such. - - * internals.texi (Pure Storage): Mention that `purecopy' does not - copy text properties. - (Object Internals): Now 29 bits are used (in most implementations) - to address Lisp objects. - - * variables.texi (Variables with Restricted Values): New node. - - * objects.texi (Lisp Data Types): Mention that certain variables - can only take on a restricted set of values and add an xref to - the new node "Variables with Restricted Values". - - * eval.texi (Function Indirection): Describe the errors that - `indirect-function' can signal. - (Eval): Clarify the descriptions of `eval-region' and `values'. - Describe `eval-buffer' instead of `eval-current-buffer' and - mention `eval-current-buffer' as an alias for `current-buffer'. - Correct the description and mention all optional arguments. - - * nonascii.texi: Various small changes in addition to the - following. - (Converting Representations): Clarify behavior of - `string-make-multibyte' and `string-to-multibyte' for unibyte all - ASCII arguments. - (Character Sets): Document the variable `charset-list' and adapt - the definition of the function `charset-list' accordingly. - (Translation of Characters): Clarify use of generic characters in - `make-translation-table'. Clarify and correct the description of - the use of translation tables in encoding and decoding. - (User-Chosen Coding Systems): Correct and clarify the description - of `select-safe-coding-system'. - (Default Coding Systems): Clarify description of - `file-coding-system-alist'. - -2003-11-30 Luc Teirlinck - - * strings.texi (Text Comparison): Correctly describe when two - strings are `equal'. Combine and clarify descriptions of - `assoc-ignore-case' and `assoc-ignore-representation'. - - * objects.texi (Non-ASCII in Strings): Clarify description of - when a string is unibyte or multibyte. - (Bool-Vector Type): Update examples. - (Equality Predicates): Correctly describe when two strings are - `equal'. - -2003-11-29 Luc Teirlinck - - * lists.texi (Building Lists): `append' no longer accepts integer - arguments. Update the description of `number-sequence' to reflect - recent changes. - (Sets And Lists): Describe `member-ignore-case' after `member'. - -2003-11-27 Kim F. Storm - - * commands.texi (Click Events): Click object may be an images. - Describe (dx . dy) element of click positions. - (Accessing Events): Remove duplicate posn-timestamp. - New functions posn-object and posn-object-x-y. - -2003-11-23 Kim F. Storm - - * commands.texi (Click Events): Describe enhancements to event - position lists, including new text-pos and (col . row) items. - Mention left-fringe and right-fringe area events. - (Accessing Events): New functions posn-area and - posn-actual-col-row. Mention posn-timestamp. Mention that - posn-point in non-text area still returns buffer position. - Clarify posn-col-row. - -2003-11-21 Lars Hansen - - * files.texi (File Attributes): Describe new parameter ID-FORMAT. - * anti.texi (File Attributes): Describe removed parameter - ID-FORMAT. - -2003-11-20 Luc Teirlinck - - * positions.texi (Positions): Mention that, if a marker is used as - a position, its buffer is ignored. - - * markers.texi (Overview of Markers): Mention it here too. - -2003-11-12 Luc Teirlinck - - * numbers.texi (Numeric Conversions): Not just `floor', but also - `truncate', `ceiling' and `round' accept optional argument DIVISOR. - -2003-11-10 Luc Teirlinck - - * markers.texi (Creating Markers): Specify insertion type of - created markers. Add xref to `Marker Insertion Types'. - Second argument to `copy-marker' is optional. - (Marker Insertion Types): Mention that most markers are created - with insertion type nil. - (The Mark): Correctly describe when `mark' signals an error. - (The Region): Correctly describe when `region-beginning' and - `region-end' signal an error. - -2003-11-08 Luc Teirlinck - - * hash.texi (Creating Hash): Clarify description of `eql'. - `makehash' is obsolete. - (Hash Access): Add Common Lisp notes for `remhash' and `clrhash'. - - * positions.texi (Point): Change description of `buffer-end', so - that it is also correct for floating point arguments. - (List Motion): Correct argument lists of `beginning-of-defun' and - `end-of-defun'. - (Excursions): Add xref to `Marker Insertion Types'. - (Narrowing): Argument to `narrow-to-page' is optional. - -2003-11-06 Luc Teirlinck - - * streams.texi (Output Streams): Clarify behavior of point for - marker output streams. - -2003-11-04 Luc Teirlinck - - * variables.texi (Defining Variables): Second argument to - `defconst' is not optional. - (Setting Variables): Mention optional argument APPEND to - `add-to-list'. - (Creating Buffer-Local): Expand description of - `make-variable-buffer-local'. - (Frame-Local Variables): Expand description of - `make-variable-frame-local'. - (Variable Aliases): Correct description of optional argument - DOCSTRING to `defvaralias'. Mention return value of - `defvaralias'. - (File Local Variables): Add xref to `File variables' in Emacs - Manual. Correct description of `hack-local-variables'. Mention - `safe-local-variable' property. Mention optional second argument - to `risky-local-variable-p'. - -2003-11-03 Luc Teirlinck - - * symbols.texi (Symbol Plists): Mention return value of `setplist'. - -2003-11-02 Jesper Harder (tiny change) - - * lispref/anti.texi, lispref/backups.texi, lispref/commands.texi - lispref/customize.texi, lispref/display.texi, lispref/files.texi, - lispref/internals.texi, lispref/keymaps.texi, lispref/loading.texi, - lispref/modes.texi, lispref/nonascii.texi, lispref/numbers.texi, - lispref/objects.texi, lispref/os.texi, lispref/positions.texi, - lispref/processes.texi, lispref/searching.texi, - lispref/sequences.texi, lispref/streams.texi, lispref/strings.texi, - lispref/syntax.texi, lispref/text.texi: Replace @sc{foo} with - @acronym{FOO}. - -2003-10-27 Luc Teirlinck - - * strings.texi (Creating Strings): Argument START to `substring' - can not be `nil'. Expand description of - `substring-no-properties'. Correct description of `split-string', - especially with respect to empty matches. Prevent very bad line - break in definition of `split-string-default-separators'. - (Text Comparison): `string=' and `string<' also accept symbols as - arguments. - (String Conversion): More completely describe argument BASE in - `string-to-number'. - (Formatting Strings): `%s' and `%S' in `format' do require - corresponding object. Clarify behavior of numeric prefix after - `%' in `format'. - (Case Conversion): The argument to `upcase-initials' can be a - character. - -2003-10-27 Kenichi Handa - - * display.texi (Fontsets): Fix texinfo usage. - -2003-10-25 Kenichi Handa - - * display.texi (Fontsets): Add description of the function - set-fontset-font. - -2003-10-23 Luc Teirlinck - - * display.texi (Temporary Displays): Add xref to `Documentation - Tips'. - - * functions.texi (Function Safety): Use inforef instead of pxref - for SES. - -2003-10-23 Andreas Schwab - - * Makefile.in (TEX, texinputdir): Don't define. - (TEXI2DVI): Define. - (srcs): Remove $(srcdir)/index.perm and $(srcdir)/index.unperm, - add $(srcdir)/index.texi. - ($(infodir)/elisp): Remove index.texi dependency. - (elisp.dvi): Likewise. Use $(TEXI2DVI). - (index.texi): Remove target. - (dist): Don't link $(srcdir)/permute-index. - (clean): Don't remove index.texi. - - * permute-index, index.perm: Remove. - * index.texi: Rename from index.unperm. - -2003-10-22 Luc Teirlinck - - * tips.texi (Documentation Tips): Document new behavior for face - and variable hyperlinks in Help mode. - -2003-10-21 Luc Teirlinck - - * objects.texi (Integer Type): Update for extra bit of integer range. - (Character Type): Ditto. - -2003-10-16 Eli Zaretskii - - * numbers.texi (Integer Basics): Add index entries for reading - numbers in hex, octal, and binary. - -2003-10-16 Lute Kamstra - - * modes.texi (Mode Line Format): Mention force-mode-line-update's - argument. - -2003-10-13 Luc Teirlinck - - * windows.texi (Choosing Window): Fix typo. - * edebug.texi (Edebug Execution Modes): Fix typo. - -2003-10-13 Richard M. Stallman - - * windows.texi (Basic Windows): A window has fringe settings, - display margins and scroll-bar settings. - (Splitting Windows): Doc split-window return value. - Clean up one-window-p. - (Selecting Windows): Fix typo. - (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. - (Buffers and Windows): In set-window-buffer, explain effect - on fringe settings and scroll bar settings. - (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. - (Choosing Window): Use defopt for pop-up-frame-function. - For special-display-buffer-names, explain same-window and same-frame. - Clarify window-dedicated-p return value. - (Textual Scrolling): scroll-up and scroll-down can get an error. - (Horizontal Scrolling): Clarify auto-hscroll-mode. - Clarify set-window-hscroll. - (Size of Window): Don't mention tool bar in window-height. - (Coordinates and Windows): Explain what coordinates-in-window-p - returns for fringes and display margins. - (Window Configurations): Explain saving fringes, etc. - - * tips.texi (Library Headers): Clean up Documentation. - - * syntax.texi (Parsing Expressions): Clean up forward-comment - and parse-sexp-lookup-properties. - - * sequences.texi (Sequence Functions): sequencep accepts bool-vectors. - - * os.texi (System Environment): Clean up text for load-average errors. - - * modes.texi (Hooks): Don't explain local hook details at front. - Clarify run-hooks and run-hook-with-args a little. - Clean up add-hook and remove-hook. - - * edebug.texi (Edebug Execution Modes): Clarify t. - Document edebug-sit-for-seconds. - (Coverage Testing): Document C-x X = and =. - (Instrumenting Macro Calls): Fix typo. - (Specification List): Don't index the specification keywords. - -2003-10-10 Kim F. Storm - - * processes.texi (Network): Introduce make-network-process. - -2003-10-09 Luc Teirlinck - - * tips.texi (Library Headers): Fix typo. - -2003-10-07 Juri Linkov - - * modes.texi (Imenu): Mention imenu-create-index-function's - default value. Explain submenus better. - -2003-10-07 Lute Kamstra - - * modes.texi (Faces for Font Lock): Fix typo. - (Hooks): Explain how buffer-local hook variables can refer to - global hook variables. - Various minor clarifications. - -2003-10-06 Lute Kamstra - - * tips.texi (Coding Conventions): Mention naming conventions for - hooks. - -2003-10-05 Luc Teirlinck - - * loading.texi (Library Search): Correct default value of - load-suffixes. - (Named Features): Fix typo. - -2003-10-05 Richard M. Stallman - - * loading.texi (Named Features): In `provide', - say how to test for subfeatures. - (Unloading): In unload-feature, use new var name - unload-feature-special-hooks. - -2003-10-03 Lute Kamstra - - * modes.texi (Major Mode Conventions): Mention third way to set up - Imenu. - (Imenu): A number of small fixes. - Delete documentation of internal variable imenu--index-alist. - Document the return value format of imenu-create-index-function - functions. - -2003-09-30 Richard M. Stallman - - * processes.texi (Network): Say what stopped datagram connections do. - - * lists.texi (Association Lists): Clarify `assq-delete-all'. - - * display.texi (Overlay Properties): Clarify `evaporate' property. - -2003-09-29 Lute Kamstra - - * modes.texi (Mode Line Data): Explain when symbols in mode-line - constructs should be marked as risky. - Change cons cell into proper list. - (Mode Line Variables): Change cons cell into proper list. - -2003-09-26 Lute Kamstra - - * modes.texi (Mode Line Data): Document the :propertize construct. - (Mode Line Variables): Reorder the descriptions of the variables - to match their order in the default mode-line-format. - Describe the new variables mode-line-position and mode-line-modes. - Update the default values of mode-line-frame-identification, - minor-mode-alist, and default-mode-line-format. - (Properties in Mode): Mention the :propertize construct. - -2003-09-26 Richard M. Stallman - - * buffers.texi, commands.texi, debugging.texi, eval.texi: - * loading.texi, minibuf.texi, text.texi, variables.texi: - Avoid @strong{Note:}. - -2003-09-26 Richard M. Stallman - - * keymaps.texi (Remapping Commands): Fix typo. - -2003-09-23 Luc Teirlinck - - * processes.texi (Low-Level Network): Fix typo. - -2003-09-23 Kim F. Storm - - * processes.texi (Network, Network Servers): Fix typos. - (Low-Level Network): Add timeout value for :server keyword. - Add new option keywords to make-network-process. - Add set-network-process-options. - Explain how to test availability of network options. - -2003-09-19 Richard M. Stallman - - * text.texi (Motion by Indent): Arg to - backward-to-indentation and forward-to-indentation is optional. - - * strings.texi (Creating Strings): Add substring-no-properties. - - * processes.texi - (Process Information): Add list-processes arg QUERY-ONLY. - Delete process-contact from here. - Add new status values for process-status. - Add process-get, process-put, process-plist, set-process-plist. - (Synchronous Processes): Add call-process-shell-command. - (Signals to Processes): signal-process allows process objects. - (Network): Complete rewrite. - (Network Servers, Datagrams, Low-Level Network): New nodes. - - * positions.texi (Word Motion): forward-word, backward-word - arg is optional. Reword. - - * abbrevs.texi (Defining Abbrevs): Index no-self-insert. - - * variables.texi (Creating Buffer-Local): - Delete duplicate definition of buffer-local-value. - (File Local Variables): Explain about discarding text props. - -2003-09-11 Richard M. Stallman - - * minibuf.texi (Intro to Minibuffers): Explain that the minibuffer - changes variables that record input events. - (Minibuffer Misc): Add minibuffer-selected-window. - - * lists.texi (Building Lists): Add copy-tree. - - * display.texi (Fontsets): Add char-displayable-p. - (Scroll Bars): New node. - -2003-09-08 Lute Kamstra - - * modes.texi (%-Constructs): Document new `%i' and `%I' - constructs. - -2003-09-03 Peter Runestig - - * makefile.w32-in: New file. - -2003-08-29 Richard M. Stallman - - * display.texi (Overlay Properties): Clarify how priorities - affect use of the properties. - -2003-08-19 Luc Teirlinck - - * customize.texi (Type Keywords): Correct the description of - `:help-echo' in the case where `motion-doc' is a function. - -2003-08-14 John Paul Wallington - - * modes.texi (Emulating Mode Line): Subsection, not section. - -2003-08-13 Richard M. Stallman - - * elisp.texi (Top): Update subnode lists in menu. - - * text.texi (Insertion): Add insert-buffer-substring-no-properties. - (Kill Functions): kill-region has new arg yank-handler. - (Yanking): New node. - (Yank Commands): Add yank-undo-function. - (Low-Level Kill Ring): - kill-new and kill-append have new arg yank-handler. - (Changing Properties): Add remove-list-of-text-properties. - (Atomic Changes): New node. - - * symbols.texi (Other Plists): Add lax-plist-get, lax-plist-put. - - * streams.texi (Output Variables): Add eval-expression-print-length - and eval-expression-print-level. - - * os.texi (Time Conversion): For encode-time, explain limits on year. - - * objects.texi (Character Type): Define anchor "modifier bits". - - * modes.texi (Emulating Mode Line): New node. - (Search-based Fontification): Font Lock uses font-lock-face property. - (Other Font Lock Variables): Likewise. - - * keymaps.texi (Format of Keymaps): Keymaps contain char tables, - not vectors. - (Active Keymaps): Add emulation-mode-map-alists. - (Functions for Key Lookup): key-binding has new arg no-remap. - (Remapping Commands): New node. - (Scanning Keymaps): where-is-internal has new arg no-remap. - (Tool Bar): Add tool-bar-local-item-from-menu. - Clarify when to use tool-bar-add-item-from-menu. - - * commands.texi (Interactive Call): commandp has new arg. - (Command Loop Info): Add this-original-command. - -2003-08-06 John Paul Wallington - - * compile.texi (Compiler Errors): Say `@end defmac' after `@defmac'. - - * display.texi (Warning Basics): Fix typo. - (Fringes): Add closing curly bracket and fix typo. - - * elisp.texi (Top): Fix typo. - -2003-08-05 Richard M. Stallman - - * elisp.texi: Update lists of subnodes. - - * windows.texi (Buffers and Windows): set-window-buffer has new arg. - - * variables.texi (Local Variables): Use lc for example variable names. - - * tips.texi (Library Headers): Explain where to put -*-. - - * strings.texi (Creating Strings): Fix xref for vconcat. - - * sequences.texi (Vector Functions): - vconcat no longer allows integer args. - - * minibuf.texi (Reading File Names): read-file-name has new - arg PREDICATE. New function read-directory-name. - - * macros.texi (Defining Macros): Give definition of `declare' - (Indenting Macros): New node. - - * frames.texi (Parameter Access): Add modify-all-frames-parameters. - (Window Frame Parameters): Make separate table of parameters - that are coupled with specific face attributes. - (Deleting Frames): delete-frame-hooks renamed to - delete-frame-functions. - - * files.texi (Magic File Names): Add file-remote-p. - Clarify file-local-copy. - - * edebug.texi (Instrumenting Macro Calls): Don't define `declare' - here; instead xref Defining Macros. - - * display.texi (Warnings): New node, and subnodes. - (Fringes): New node. - - * debugging.texi (Test Coverage): New node. - - * compile.texi (Compiler Errors): Explain with-no-warnings - and other ways to suppress warnings. - - * commands.texi (Interactive Call): Minor clarification. - - * buffers.texi (Buffer File Name): set-visited-file-name - renames the buffer too. - - * abbrevs.texi (Abbrev Tables): Add copy-abbrev-table. - -2003-07-24 Markus Rost - - * abbrevs.texi (Abbrev Expansion): Use \s syntax in example. - -2003-07-22 Markus Rost - - * internals.texi (Garbage Collection): Fix previous change. - -2003-07-22 Richard M. Stallman - - * files.texi (Truenames): Add LIMIT arg to file-chase-links. - - * display.texi (Width): Use \s syntax in example. - (Font Selection): Add face-font-rescale-alist. - - * modes.texi (Imenu): Add xref to Emacs Manual node on Imenu. - Remove spurious indent in example. - - * lists.texi (Building Lists): Add number-sequence. - - * internals.texi (Garbage Collection): Add gcs-done, gc-elapsed. - - * functions.texi (Function Documentation): Explain how to - show calling convention explicitly in the doc string. - - * windows.texi (Selecting Windows): save-selected-window saves - selected window of each frame. - (Window Configurations): Minor change. - - * syntax.texi (Syntax Table Functions): Use \s syntax in examples. - - * streams.texi (Output Variables): Add print-continuous-numbering - and print-number-table. - - * processes.texi (Decoding Output): New node. - - * os.texi (Time Conversion): decode-time arg is optional. - - * objects.texi (Character Type): Don't use space as example for \. - Make list of char names and \-sequences correspond. - Explain that \s is not used in strings. `\ ' needs space after. - - * nonascii.texi (Converting Representations): Add string-to-multibyte. - (Translation of Characters): Add translation-table-for-input. - (Default Coding Systems): Add auto-coding-functions. - (Explicit Encoding): Add decode-coding-inserted-region. - (Locales): Add locale-info. - - * minibuf.texi (Basic Completion): Describe test-completion. - Collections can be lists of strings. - Clean up lazy-completion-table. - (Programmed Completion): Mention test-completion. - Clarify why lambda expressions are not accepted. - (Minibuffer Misc): Describe minibufferp. - -2003-07-14 Richard M. Stallman - - * buffers.texi (Killing Buffers): kill-buffer-hook is perm local. - - * windows.texi (Selecting Windows): New arg to select-window. - (Selecting Windows): Add with-selected-window. - (Size of Window): Add window-inside-edges, etc. - - * internals.texi (Garbage Collection): Add post-gc-hook. - - * processes.texi (Subprocess Creation): Add exec-suffixes. - - * keymaps.texi (Functions for Key Lookup): Add current-active-maps. - (Scanning Keymaps): Add map-keymaps. - (Defining Menus): Add keymap-prompt. - - * numbers.texi (Integer Basics): Add most-positive-fixnum, - most-negative-fixnum. - - * compile.texi (Byte Compilation): Explain no-byte-compile - (Compiler Errors): New node. - - * os.texi (User Identification): user-uid, user-real-uid - can return float. - - * modes.texi (Major Mode Conventions): Explain about run-mode-hooks - and about derived modes. - (Minor Modes): Add minor-mode-list. - (Defining Minor Modes): Keyword args for define-minor-mode. - (Search-based Fontification): Explain managing other properties. - (Other Font Lock Variables): Add font-lock-extra-managed-props. - (Faces for Font Lock): Add font-lock-preprocessor-face. - (Hooks): Add run-mode-hooks and delay-mode-hooks. - - * variables.texi (Creating Buffer-Local): Add buffer-local-value. - (Variable Aliases): Clarify defvaralias. - - * loading.texi (Library Search): Add load-suffixes. - - * minibuf.texi (Basic Completion): Add lazy-completion-table. - (Programmed Completion): Add dynamic-completion-table. - - * files.texi (Changing Files): copy-file allows dir as NEWNAME. - (Magic File Names): Specify precedence order of handlers. - - * commands.texi (Command Overview): Emacs server runs pre-command-hook - and post-command-hook. - (Waiting): New calling convention for sit-for. - - * text.texi (Special Properties): local-map and keymap properties - apply based on their stickiness. - -2003-07-07 Richard M. Stallman - - * modes.texi (Minor Mode Conventions): Specify only some kinds - of list values as args to minor modes. - - * files.texi (File Name Expansion): Warn about iterative use - of substitute-in-file-name. - - * advice.texi (Activation of Advice): Clean up previous change. - -2003-07-06 Markus Rost - - * advice.texi (Activation of Advice): Note that ad-start-advice is - turned on by default. - -2003-06-30 Richard M. Stallman - - * text.texi (Buffer Contents): Document current-word. - (Change Hooks): Not called for *Messages*. - - * functions.texi (Defining Functions): Explain about redefining - primitives. - (Function Safety): Renamed. Minor changes. - Comment out the detailed criteria for what is safe. - -2003-06-22 Andreas Schwab - - * objects.texi (Symbol Type): Fix description of examples. - -2003-06-16 Andreas Schwab - - * hash.texi (Creating Hash): Fix description of :weakness. - -2003-06-13 Kai Großjohann - - * files.texi (Changing Files): copy-file copies file modes, too. - -2003-05-28 Richard M. Stallman - - * strings.texi (Creating Strings): Clarify split-string. - -2003-05-22 Stephen J. Turnbull - - * strings.texi (Creating Strings): Update split-string specification - and examples. - -2003-05-19 Richard M. Stallman - - * elisp.texi: Correct invariant section names. - -2003-04-20 Richard M. Stallman - - * os.texi (Timers): Explain about timers and quitting. - -2003-04-19 Richard M. Stallman - - * internals.texi (Writing Emacs Primitives): Strings are - no longer special for GCPROs. Mention GCPRO5, GCPRO6. - Explain GCPRO convention for varargs function args. - -2003-04-16 Richard M. Stallman - - * minibuf.texi (Minibuffer Misc): Document fn minibuffer-message. - -2003-04-08 Richard M. Stallman - - * files.texi (Kinds of Files): Correct return value of file-symlink-p. - -2003-02-13 Kim F. Storm - - * objects.texi (Character Type): New \s escape for space. - -2003-01-31 Joe Buehler - - * os.texi (System Environment): Added cygwin system-type. - -2003-01-25 Richard M. Stallman - - * keymaps.texi: Document that a symbol can act as a keymap. - -2003-01-13 Richard M. Stallman - - * text.texi (Changing Properties): Say string indices are origin-0. - - * positions.texi (Screen Lines) : - Correct order of elts in return value. - - * keymaps.texi (Changing Key Bindings) : Mention - how to define a default binding. - -2002-12-07 Markus Rost - - * loading.texi (Unloading): Fix recent change for load-history. - - * customize.texi (Simple Types): Clarify description of custom - type 'number. Describe new custom type 'float. - -2002-12-04 Markus Rost - - * variables.texi (File Local Variables): Fix typo. - -2002-10-23 Kai Großjohann - - From Michael Albinus . - - * README: Target for Info file is `make info'. - - * files.texi (File Name Components): Fixed typos in - `file-name-sans-extension'. - (Magic File Names): Complete list of operations for magic file - name handlers. - -2002-09-16 Jonathan Yavner - - * variables.texi (File Local Variables): New function - risky-local-variable-p. - -2002-09-15 Jonathan Yavner - - * functions.texi (Function safety): New node about unsafep. - -2002-08-05 Per Abrahamsen - - * customize.texi (Splicing into Lists): Fixed example. - Reported by Fabrice Bauzac - -2002-06-17 Juanma Barranquero - - * frames.texi (Display Feature Testing): Fix typo. - -2002-06-12 Andreas Schwab - - * frames.texi (Initial Parameters, Resources): Fix references to - the Emacs manual. - -2002-05-13 Kim F. Storm - - * variables.texi (Intro to Buffer-Local): Updated warning and - example relating to changing buffer inside let. - -2002-03-10 Jan Djärv - - * os.texi (Session Management): New node about X Session management. - -2002-01-18 Eli Zaretskii - - * elisp.texi (VERSION): Set to 2.9. Update the version of Emacs - to which the manual corresponds, and the copyright years. - - * Makefile.in (VERSION): Set to 2.9. - -2001-11-29 Eli Zaretskii - - * elisp.texi: Change the category in @dircategory to "Emacs", to - make it consistent with info/dir. - -2001-11-25 Miles Bader - - * text.texi (Fields): Describe new `limit' arg in - field-beginning/field-end. - -2001-11-17 Eli Zaretskii - - * permute-index: Don't depend on csh-specific features. Replace - the interpreter name with /bin/sh. - - * two-volume-cross-refs.txt: New file. - * two.el: New file. - * spellfile: New file. - -2001-11-16 Eli Zaretskii - - * permute-index: New file. - - * vol1.texi, vol2.texi: Renamed from elisp-vol1.texi and - elisp-vol2.texi, respectively, to avoid file-name clashes in DOS - 8+3 restricted namespace. - - * Makefile.in (infodir): Define relative to $(srcdir). - ($(infodir)/elisp): Don't chdir into $(srcdir), but add it to the - include directories list via -I switch to makeinfo. - (index.texi): Use cp if both hard and symbolic links fail. - -2001-11-10 Eli Zaretskii - - * Makefile.in (distclean): Add. - - The following changes make ELisp manual part of the Emacs - distribution: - - * Makefile.in: Add Copyright notice. - (prefix): Remove. - (infodir): Change value to "../info". - (VPATH): New variable. - (MAKE): Don't define. - (texmacrodir): Don't define. - (texinputdir): Append the existing value of TEXINPUTS. - ($(infodir)/elisp): Instead of just "elisp". Reformat the - command to be compatible with man/Makefile.in, and to put the - output into ../info. - (info): Add target. - (installall): Target removed. - -2001-10-31 Pavel Janík - - * tips.texi (Coding Conventions): Fix typo. - -2001-10-23 Gerd Moellmann - - * Makefile.in (srcs): Add gpl.texi and doclicense.texi. - -2001-10-22 Eli Zaretskii - - * files.texi (File Name Components): Update the description of - file-name-sans-extension and file-name-extension, as they now - ignore leading dots. - -2001-10-20 Gerd Moellmann - - * (Version 21.1 released.) - -2001-10-19 Miles Bader - - * positions.texi (Text Lines): Describe behavior of - `beginning-of-line'/`end-of-line' in the presence of field properties. - -2001-10-17 Gerd Moellmann - - * Makefile.in (VERSION): Set to 2.8. - (manual): Use `manual-21'. - - * elisp.texi (VERSION): Add and use it where the version - number was used. Set it to 2.8. - - * intro.texi: Likewise. - -2001-10-13 Eli Zaretskii - - * files.texi (File Name Completion): Document the significance of - a trailing slash in elements of completion-ignored-extensions. - -2001-10-06 Miles Bader - - * variables.texi (Variable Aliases): It's `@defmac', not `@defmacro'. - -2001-10-04 Gerd Moellmann - - * variables.texi (Variable Aliases): New node. - -2001-10-04 Gerd Moellmann - - * Branch for 21.1. - -2001-10-02 Miles Bader - - * minibuf.texi (Minibuffer Misc): Add entries for - `minibuffer-contents', `minibuffer-contents-no-properties', and - `delete-minibuffer-contents'. - Correct description for `minibuffer-prompt-end'. - - * text.texi (Property Search): Correct descriptions of - `next-char-property-change' and `previous-char-property-change'. - Add entries for `next-single-char-property-change' and - `previous-single-char-property-change'. - Make operand names a bit more consistent. - -2001-09-30 Eli Zaretskii - - * frames.texi (Finding All Frames): Document that next-frame and - previous-frame are local to current terminal. - -2001-09-26 Eli Zaretskii - - * keymaps.texi (Creating Keymaps): Fix the description of the - result of make-keymap. - -2001-09-23 Eli Zaretskii - - * display.texi (Font Lookup, Attribute Functions) - (Image Descriptors): Add cross-references to the definition of - selected frame. - - * buffers.texi (The Buffer List): Add cross-references to the - definition of selected frame. - - * frames.texi (Input Focus): Clarify which frame is _the_ selected - frame at any given time. - (Multiple Displays, Size and Position): Add a cross-reference to - the definition of the selected frame. - -2001-09-08 Eli Zaretskii - - * strings.texi (String Conversion) : Document - that a float is returned for integers that are too large. - - * frames.texi (Mouse Position): Document mouse-position-function. - (Display Feature Testing): Document display-images-p. - (Window Frame Parameters): Document the cursor-type variable. - - * numbers.texi (Integer Basics): Document CL style read syntax for - integers in bases other than 10. - - * positions.texi (List Motion): Document - open-paren-in-column-0-is-defun-start. - - * lists.texi (Sets And Lists): Document member-ignore-case. - - * internals.texi (Garbage Collection): Document the used and free - strings report. - (Memory Usage): Document strings-consed. - - * os.texi (Time of Day): Document float-time. - (Recording Input): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - - * keymaps.texi (Scanning Keymaps) : The - argument keymap can be a list. - - * nonascii.texi (User-Chosen Coding Systems) - : Document the new argument - accept-default-p and the variable - select-safe-coding-system-accept-default-p. Tell what happens if - buffer-file-coding-system is undecided. - (Default Coding Systems): Document auto-coding-regexp-alist. - - * display.texi (The Echo Area) : Document - message-truncate-lines. - (Glyphs): Document that the glyph table is unused on windowed - displays. - - * help.texi (Describing Characters) : - Document the new argument no-angles. - (Accessing Documentation) : Document that - a non-string property is evaluated. - : Document that the function-documentation property - is looked for. - - * windows.texi (Selecting Windows): Document some-window. - - * text.texi (MD5 Checksum): New node, documents the md5 primitive. - - * hooks.texi (Standard Hooks): Add kbd-macro-termination-hook and - apropos-mode-hook. - - * commands.texi (Using Interactive): Document interactive-form. - (Keyboard Macros): Document kbd-macro-termination-hook. - (Command Loop Info): Document that clear-this-command-keys clears - the vector to be returned by recent-keys. - -2001-09-04 Werner LEMBERG - - * Makefile.in (srcdir, texinputdir): New variables. - (srcs, index.texi, install): Use $(srcdir). - (.PHONY): Remove elisp.dvi. - (elisp): Use -I switch for makeinfo. - (elisp.dvi): Use $(srcdir) and $(texinputdir). - (installall, dist): Use $(srcdir). - Fix path to texinfo.tex. - (maintainer-clean): Add elisp.dvi and elisp.oaux. - -2001-08-30 Gerd Moellmann - - * display.texi (Conditional Display): Adjust to API change. - - * configure: New file. - -2001-07-30 Gerd Moellmann - - * commands.texi (Repeat Events): Add description of - double-click-fuzz. - -2001-05-08 Stefan Monnier - - * syntax.texi (Syntax Class Table): Add the missing designator for - comment and string fences. - (Syntax Properties): Add a xref to syntax table internals. - (Syntax Table Internals): Document string-to-syntax. - -2001-05-07 Gerd Moellmann - - * Makefile.in (install): Use install-info command line options - like in Emacs' Makefile.in. - -2000-12-09 Miles Bader - - * windows.texi (Window Start): Update documentation for - `pos-visible-in-window-p'. - -2000-11-12 Stefan Monnier - - * lists.texi (Building Lists): Add footnote to explain how to add - to the end of a list. - -2000-10-25 Gerd Moellmann - - * files.texi (Visiting Functions): Typos. - -2000-10-25 Kenichi Handa - - * files.texi (Visiting Functions): Return value of - find-file-noselect may be a list of buffers if wildcards are used. - -2000-10-24 Miles Bader - - * display.texi (Defining Faces): Document `graphic' display type - in face specs. - -2000-10-18 Kai Großjohann - - * hooks.texi (Standard Hooks): Replace obsolete - `after-make-frame-hook' with `after-make-frame-functions'. - - * frames.texi (Creating Frames): Ditto. - - * variables.texi (Future Local Variables): Ditto. - -2000-10-16 Gerd Moellmann - - * display.texi (Other Image Types): Add description of :foreground - and :background properties of mono PBM images. - -2000-08-17 Werner LEMBERG - - * .cvsignore: New file. - -2000-01-05 Gerd Moellmann - - * tindex.pl: New script. - -1999-12-03 Dave Love - - * Makefile.in (MAKEINFO): New parameter. - -1999-09-17 Richard Stallman - - * Makefile.in (srcs): Add hash.texi. - (VERSION): Update to 20.6. - -1999-09-13 Richard Stallman - - * Makefile.in (index.texi): If cannot make a symlink, make a hard link. - -1998-08-29 Karl Heuer - - * configure.in: New file. - * Makefile.in: Renamed from Makefile. - (prefix, infodir): Use value obtained from configure. - (emacslibdir): Obsolete variable deleted. - (dist): Distribute configure.in, configure, Makefile.in. - -1998-06-12 Richard Stallman - - * Makefile (INSTALL_INFO): New variable. - (install): Run install-info. - -1998-05-09 Richard Stallman - - * Makefile (elisp.dvi): Add missing backslash. - -1998-05-02 Richard Stallman - - * Makefile (elisp.dvi): Don't depend on texindex or on elisp.tps. - Run texindex without `./'. Always run texindex on elisp.tp. - (elisp.tps): Target deleted. - -1998-04-05 Richard Stallman - - * Makefile (srcs): Add nonascii.texi and customize.texi. - (dist): Start by deleting `temp'. - -1998-02-17 Richard Stallman - - * Makefile (makeinfo, texindex): Targets deleted. - (makeinfo.o, texindex.o): Targets deleted. - (clean, dist): Don't do anything with them or with getopt*. - -1998-01-30 Richard Stallman - - * Makefile (SHELL): Defined. - -1998-01-27 Richard Stallman - - * Makefile (elisp.tps): New target. - (elisp.dvi): Depend on elisp.tps. - -1996-04-03 Karl Heuer - - * README: Update phone number. - - * Makefile (elisp): Make this be the default target. - Depend on makeinfo.c instead of makeinfo. - (install): Don't depend on elisp.dvi, since we don't install that. - Use mkinstalldirs. - (dist): Add mkinstalldirs. - -1995-06-19 Richard Stallman - - * Makefile (VERSION): Update version number. - (maintainer-clean): Renamed from realclean. - -1995-06-07 Karl Heuer - - * Makefile (realclean): New target. - (elisp): Remove any old elisp-* files first. - -1993-11-23 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) - - * Makefile (VERSION): New variable. - (dist): Make packaged directory name `elisp-manual-19-$(VERSION)'. - Compressed file suffix should be `.gz', not `.z'. - -1993-11-22 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (elisp): Depend on makeinfo. - -1993-11-19 Noah Friedman (friedman@gnu.ai.mit.edu) - - * Makefile (srcs): Add anti.texi. - -1993-05-28 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (infodir, prefix): New vars. - (install): Use infodir. - (emacsinfodir): Deleted. - -1993-05-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Add calendar.texi. - - * Makefile (dist): Copy texindex.c and makeinfo.c. - Limit elisp-* files to those with one or two digits. - -1993-05-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Changed to use Gzip instead of compress. - -1993-04-23 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * loading.texi (Unloading): define-function changed back to - defalias. It may not stay this way, but at least it's - consistent with the known-good version of the code patch. - -1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) - - * modes.texi (Hooks): Document new optional arg of add-hook. - -1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) - - * variables.texi: Document nil initial value of buffer-local variables. - - * tips.texi: Add new section on standard library headers. - -1993-02-27 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (srcs): Add frame.texi to the list of sources. - -1993-02-23 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't bother excluding autosave files; they'll - never make it into the temp directory anyway, and the hash marks - in the name are problematic for make and the Bourne shell. - (srcs): - -1993-02-12 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) - - * Makefile (dist): Don't include backup files or autosave files in - the distribution tar file. - -1991-11-26 Richard Stallman (rms@mole.gnu.ai.mit.edu) - - * Makefile (srcs): Added index.perm. - (elisp.dvi): Remove erroneous shell comment. - Expect output of permute-index in permuted.fns. - Save old elisp.aux in elisp.oaux. - (clean): Added index.texi to be deleted. - -1990-08-11 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * Makefile (elisp.dvi, index.texi): Use shell if instead of ifdef. - -1990-06-26 David Lawrence (tale@geech) - - * files.texi: Noted that completion-ignored-extensions is ignored - when making *Completions*. - -1990-06-08 Jay Fenlason (hack@ai.mit.edu) - - * Makefile make dist now depends on elisp.dvi, since it tries - to include it in the dist file. - -1990-03-28 Jim Kingdon (kingdon@mole.ai.mit.edu) - - * functions.texinfo (Mapping Functions): Add missing quote. - -1989-06-19 Richard Stallman (rms@sugar-bombs.ai.mit.edu) - - * texinfo.tex (frenchspacing): Use decimal codes for char to be set. - (defunargs): Turn off \hyphenchar of \sl font temporarily. - -1989-05-10 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expansion{}, @print{}, @quiv{}, @point{}, - and @error{} are the terms now being used. The files in the - directory have been changed to reflect this. - - * All instances of @indentedresultt{} have been changed to - ` @result{}', using 5 spaces at the begining of the line. - -1989-04-24 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * @result{}, @expandsto{}, @prints{}, @quiv{}, @error{}, and the - experimental @indentedresult{}, @indentedexpandsto{} are part of - the texinfo.tex in this directory. These TeX macros are not - stable yet. - -1989-04-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * texinfo.tex: Temporarily added - \let\result=\dblarrow - \def\error{{\it ERROR} \longdblarrow} - We need to do this better soon. - -1989-04-11 Robert J. Chassell (bob@rice-chex.ai.mit.edu) - - * Applied Karl Berry's patches to *.texinfo files, but not to - texinfo.tex; those diffs are in `berry-texinfo-tex-diffs'. (Karl's - new title page format is also not applied, since it requires - texinfo.tex changes.) - - * Cleaned up `Makefile' and defined the `emacslibdir' directory - for the Project GNU development environment. - -;; Local Variables: -;; coding: utf-8 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, - 2007, 2008, 2009 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . - -;;; arch-tag: 985ae0ce-df29-475b-b3f8-4bbcbf6f7fda diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in deleted file mode 100644 index 7c8f1af79c1..00000000000 --- a/doc/lispref/Makefile.in +++ /dev/null @@ -1,115 +0,0 @@ -# Makefile for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, -# 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Standard configure variables. -srcdir = @srcdir@ - -# Tell make where to find source files; this is needed for the makefiles. -VPATH=@srcdir@ - -infodir = ../../info -# Directory with the (customized) texinfo.tex file. -texinfodir = $(srcdir)/../misc - -TEXI2DVI = texi2dvi -SHELL = /bin/sh -INSTALL_INFO = install-info -MAKEINFO = makeinfo --force - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/locals.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. -info: $(infodir)/elisp - -$(infodir)/elisp: $(srcs) - cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp - -elisp.dvi: $(srcs) - $(TEXI2DVI) -I $(srcdir) -I $(texinfodir) $(srcdir)/elisp.texi - -clean: - rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys elisp[12]* - rm -f make.out core - -distclean: clean - -maintainer-clean: clean - rm -f elisp.dvi elisp.oaux - cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9] diff --git a/doc/lispref/README b/doc/lispref/README deleted file mode 100644 index 88957131a4e..00000000000 --- a/doc/lispref/README +++ /dev/null @@ -1,50 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. -See the end of the file for license conditions. - - -README for Edition 3.0 of the Emacs Lisp Reference Manual. - -* This directory contains the texinfo source files for the Emacs Lisp -Reference Manual. - -* Report bugs in the Lisp Manual or in Emacs using M-x report-emacs-bug. -To ask questions, use the newsgroup gnu.emacs.help. - -* The Emacs Lisp Reference Manual is quite large. It totals around -1100 pages in smallbook format; the info files total around 3.0 megabytes. - -* You can format this manual either for Info or for printing hardcopy -using TeX. - -* You can buy nicely printed copies from the Free Software Foundation. -Buying a manual from the Free Software Foundation helps support our GNU -development work. See . - -* The master file for formatting this manual for Tex is called -`elisp.texi'. It contains @include commands to include all the -chapters that make up the manual. In addition, `elisp.texi' has -the title page in a new format designed by Karl Berry, using the -@titlespec command. - -* This distribution contains a Makefile that you can use with GNU Make. - -** To create a DVI file with a sorted index, run `make elisp.dvi'. - -** To make an Info file, you need to install Texinfo, then run `make info'. - - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi deleted file mode 100644 index 9e14c3d4e9b..00000000000 --- a/doc/lispref/abbrevs.texi +++ /dev/null @@ -1,523 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/abbrevs -@node Abbrevs, Processes, Syntax Tables, Top -@chapter Abbrevs and Abbrev Expansion -@cindex abbrev -@c @cindex abbrev table Redundant with "abbrev". - - An abbreviation or @dfn{abbrev} is a string of characters that may be -expanded to a longer string. The user can insert the abbrev string and -find it replaced automatically with the expansion of the abbrev. This -saves typing. - - The set of abbrevs currently in effect is recorded in an @dfn{abbrev -table}. Each buffer has a local abbrev table, but normally all buffers -in the same major mode share one abbrev table. There is also a global -abbrev table. Normally both are used. - - An abbrev table is represented as an obarray. @xref{Creating -Symbols}, for information about obarrays. Each abbreviation is -represented by a symbol in the obarray. The symbol's name is the -abbreviation; its value is the expansion; its function definition is -the hook function for performing the expansion (@pxref{Defining -Abbrevs}); and its property list cell contains various additional -properties, including the use count and the number of times the -abbreviation has been expanded (@pxref{Abbrev Properties}). - -@cindex system abbrev - Certain abbrevs, called @dfn{system abbrevs}, are defined by a major -mode instead of the user. A system abbrev is identified by its -non-@code{nil} @code{:system} property (@pxref{Abbrev Properties}). -When abbrevs are saved to an abbrev file, system abbrevs are omitted. -@xref{Abbrev Files}. - - Because the symbols used for abbrevs are not interned in the usual -obarray, they will never appear as the result of reading a Lisp -expression; in fact, normally they are never used except by the code -that handles abbrevs. Therefore, it is safe to use them in an -extremely nonstandard way. - - For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev -Mode, emacs, The GNU Emacs Manual}. - -@menu -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. -@end menu - -@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs -@comment node-name, next, previous, up -@section Setting Up Abbrev Mode - - Abbrev mode is a minor mode controlled by the variable -@code{abbrev-mode}. - -@defopt abbrev-mode -If this variable is non-@code{nil}, abbrevs are automatically expanded -in the buffer. If the value is @code{nil}, abbrevs may be defined, -but they are not expanded automatically. - -This variable automatically becomes buffer-local when set in any fashion. -@end defopt - -@defvar default-abbrev-mode -This is the value of @code{abbrev-mode} for buffers that do not -override it. It is the same as @code{(default-value 'abbrev-mode)}. -@end defvar - -@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs -@section Abbrev Tables - - This section describes how to create and manipulate abbrev tables. - -@defun make-abbrev-table &optional props -This function creates and returns a new, empty abbrev table---an -obarray containing no symbols. It is a vector filled with zeros. -@var{props} is a property list that is applied to the new table -(@pxref{Abbrev Table Properties}). -@end defun - -@defun abbrev-table-p object -This function returns a non-@code{nil} value if @var{object} is an -abbrev table. -@end defun - -@defun clear-abbrev-table abbrev-table -This function undefines all the abbrevs in @var{abbrev-table}, leaving -it empty. It always returns @code{nil}. -@end defun - -@defun copy-abbrev-table abbrev-table -This function returns a copy of @var{abbrev-table}---a new abbrev -table containing the same abbrev definitions. There is one difference -between the contents of @var{abbrev-table} and the returned copy: all -abbrevs in the latter have their property lists set to @code{nil}. -@end defun - -@defun define-abbrev-table tabname definitions &optional docstring &rest props -This function defines @var{tabname} (a symbol) as an abbrev table -name, i.e., as a variable whose value is an abbrev table. It defines -abbrevs in the table according to @var{definitions}, a list of -elements of the form @code{(@var{abbrevname} @var{expansion} -[@var{hook}] [@var{props}...])}. These elements are passed as -arguments to @code{define-abbrev}. The return value is always -@code{nil}. - -The optional string @var{docstring} is the documentation string of the -variable @var{tabname}. The property list @var{props} is applied to -the abbrev table (@pxref{Abbrev Table Properties}). - -If this function is called more than once for the same @var{tabname}, -subsequent calls add the definitions in @var{definitions} to -@var{tabname}, rather than overriding the entire original contents. -(A subsequent call only overrides abbrevs explicitly redefined or -undefined in @var{definitions}.) -@end defun - -@defvar abbrev-table-name-list -This is a list of symbols whose values are abbrev tables. -@code{define-abbrev-table} adds the new abbrev table name to this list. -@end defvar - -@defun insert-abbrev-table-description name &optional human -This function inserts before point a description of the abbrev table -named @var{name}. The argument @var{name} is a symbol whose value is an -abbrev table. The return value is always @code{nil}. - -If @var{human} is non-@code{nil}, the description is human-oriented. -System abbrevs are listed and identified as such. Otherwise the -description is a Lisp expression---a call to @code{define-abbrev-table} -that would define @var{name} as it is currently defined, but without -the system abbrevs. (The mode or package using @var{name} is supposed -to add these to @var{name} separately.) -@end defun - -@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs -@comment node-name, next, previous, up -@section Defining Abbrevs - - @code{define-abbrev} is the low-level basic function for defining an -abbrev in an abbrev table. - - When a major mode defines a system abbrev, it should call -@code{define-abbrev} and specify a @code{t} for the @code{:system} -property. Be aware that any saved non-``system'' abbrevs are restored -at startup, i.e. before some major modes are loaded. Therefore, major -modes should not assume that their abbrev tables are empty when they -are first loaded. - -@defun define-abbrev abbrev-table name expansion &optional hook &rest props -This function defines an abbrev named @var{name}, in -@var{abbrev-table}, to expand to @var{expansion} and call @var{hook}, -with properties @var{props} (@pxref{Abbrev Properties}). The return -value is @var{name}. The @code{:system} property in @var{props} is -treated specially here: if it has the value @code{force}, then it will -overwrite an existing definition even for a non-``system'' abbrev of -the same name. - -@var{name} should be a string. The argument @var{expansion} is -normally the desired expansion (a string), or @code{nil} to undefine -the abbrev. If it is anything but a string or @code{nil}, then the -abbreviation ``expands'' solely by running @var{hook}. - -The argument @var{hook} is a function or @code{nil}. If @var{hook} is -non-@code{nil}, then it is called with no arguments after the abbrev is -replaced with @var{expansion}; point is located at the end of -@var{expansion} when @var{hook} is called. - -@cindex @code{no-self-insert} property -If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert} -property is non-@code{nil}, @var{hook} can explicitly control whether -to insert the self-inserting input character that triggered the -expansion. If @var{hook} returns non-@code{nil} in this case, that -inhibits insertion of the character. By contrast, if @var{hook} -returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as -if expansion had not really occurred. - -Normally, @code{define-abbrev} sets the variable -@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev. -(This is so that some commands will offer to save the abbrevs.) It -does not do this for a system abbrev, since those aren't saved anyway. -@end defun - -@defopt only-global-abbrevs -If this variable is non-@code{nil}, it means that the user plans to use -global abbrevs only. This tells the commands that define mode-specific -abbrevs to define global ones instead. This variable does not alter the -behavior of the functions in this section; it is examined by their -callers. -@end defopt - -@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs -@section Saving Abbrevs in Files - - A file of saved abbrev definitions is actually a file of Lisp code. -The abbrevs are saved in the form of a Lisp program to define the same -abbrev tables with the same contents. Therefore, you can load the file -with @code{load} (@pxref{How Programs Do Loading}). However, the -function @code{quietly-read-abbrev-file} is provided as a more -convenient interface. - - User-level facilities such as @code{save-some-buffers} can save -abbrevs in a file automatically, under the control of variables -described here. - -@defopt abbrev-file-name -This is the default file name for reading and saving abbrevs. -@end defopt - -@defun quietly-read-abbrev-file &optional filename -This function reads abbrev definitions from a file named @var{filename}, -previously written with @code{write-abbrev-file}. If @var{filename} is -omitted or @code{nil}, the file specified in @code{abbrev-file-name} is -used. @code{save-abbrevs} is set to @code{t} so that changes will be -saved. - -This function does not display any messages. It returns @code{nil}. -@end defun - -@defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrevs} means that Emacs should -offer the user to save abbrevs when files are saved. If the value is -@code{silently}, Emacs saves the abbrevs without asking the user. -@code{abbrev-file-name} specifies the file to save the abbrevs in. -@end defopt - -@defvar abbrevs-changed -This variable is set non-@code{nil} by defining or altering any -abbrevs (except system abbrevs). This serves as a flag for various -Emacs commands to offer to save your abbrevs. -@end defvar - -@deffn Command write-abbrev-file &optional filename -Save all abbrev definitions (except system abbrevs), for all abbrev -tables listed in @code{abbrev-table-name-list}, in the file -@var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, -@code{abbrev-file-name} is used. This function returns @code{nil}. -@end deffn - -@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs -@comment node-name, next, previous, up -@section Looking Up and Expanding Abbreviations - - Abbrevs are usually expanded by certain interactive commands, -including @code{self-insert-command}. This section describes the -subroutines used in writing such commands, as well as the variables they -use for communication. - -@defun abbrev-symbol abbrev &optional table -This function returns the symbol representing the abbrev named -@var{abbrev}. The value returned is @code{nil} if that abbrev is not -defined. The optional second argument @var{table} is the abbrev table -in which to look it up. If @var{table} is @code{nil}, this function -tries first the current buffer's local abbrev table, and second the -global abbrev table. -@end defun - -@defun abbrev-expansion abbrev &optional table -This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). If -@var{abbrev} is not a valid abbrev, the function returns @code{nil}. -The optional argument @var{table} specifies the abbrev table to use, -as in @code{abbrev-symbol}. -@end defun - -@deffn Command expand-abbrev -This command expands the abbrev before point, if any. If point does not -follow an abbrev, this command does nothing. The command returns the -abbrev symbol if it did expansion, @code{nil} otherwise. - -If the abbrev symbol has a hook function which is a symbol whose -@code{no-self-insert} property is non-@code{nil}, and if the hook -function returns @code{nil} as its value, then @code{expand-abbrev} -returns @code{nil} even though expansion did occur. -@end deffn - -@deffn abbrev-insert abbrev &optional name start end -This function inserts the abbrev expansion of @code{abbrev}, replacing -the text between @code{start} and @code{end}. If @code{start} is -omitted, it defaults to point. @code{name}, if non-@code{nil}, should -be the name by which this abbrev was found (a string); it is used to -figure out whether to adjust the capitalization of the expansion. The -function returns @code{abbrev} if the abbrev was successfully -inserted. -@end deffn - -@deffn Command abbrev-prefix-mark &optional arg -This command marks the current location of point as the beginning of -an abbrev. The next call to @code{expand-abbrev} will use the text -from here to point (where it is then) as the abbrev to expand, rather -than using the previous word as usual. - -First, this command expands any abbrev before point, unless @var{arg} -is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.) -Then it inserts a hyphen before point, to indicate the start of the -next abbrev to be expanded. The actual expansion removes the hyphen. -@end deffn - -@defopt abbrev-all-caps -When this is set non-@code{nil}, an abbrev entered entirely in upper -case is expanded using all upper case. Otherwise, an abbrev entered -entirely in upper case is expanded by capitalizing each word of the -expansion. -@end defopt - -@defvar abbrev-start-location -The value of this variable is a buffer position (an integer or a marker) -for @code{expand-abbrev} to use as the start of the next abbrev to be -expanded. The value can also be @code{nil}, which means to use the -word before point instead. @code{abbrev-start-location} is set to -@code{nil} each time @code{expand-abbrev} is called. This variable is -also set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar abbrev-start-location-buffer -The value of this variable is the buffer for which -@code{abbrev-start-location} has been set. Trying to expand an abbrev -in any other buffer clears @code{abbrev-start-location}. This variable -is set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar last-abbrev -This is the @code{abbrev-symbol} of the most recent abbrev expanded. This -information is left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding -Abbrevs, emacs, The GNU Emacs Manual}). -@end defvar - -@defvar last-abbrev-location -This is the location of the most recent abbrev expanded. This contains -information left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-text -This is the exact expansion text of the most recent abbrev expanded, -after case conversion (if any). Its value is @code{nil} if the abbrev -has already been unexpanded. This contains information left by -@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command. -@end defvar - -@defvar abbrev-expand-functions -This is a special hook run @emph{around} the @code{expand-abbrev} -function. Each function on this hook is called with a single -argument: a function that performs the normal abbrev expansion. The -hook function can hence do anything it wants before and after -performing the expansion. It can also choose not to call its -argument, thus overriding the default behavior; or it may even call it -several times. The function should return the abbrev symbol if -expansion took place. -@end defvar - - The following sample code shows a simple use of -@code{abbrev-expand-functions}. It assumes that @code{foo-mode} is a -mode for editing certain files in which lines that start with @samp{#} -are comments. You want to use Text mode abbrevs for those lines. The -regular local abbrev table, @code{foo-mode-abbrev-table} is -appropriate for all other lines. Then you can put the following code -in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the -definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}. - -@smallexample -(defun foo-mode-abbrev-expand-function (expand) - (if (not (save-excursion (forward-line 0) (eq (char-after) ?#))) - ;; Performs normal expansion. - (funcall expand) - ;; We're inside a comment: use the text-mode abbrevs. - (let ((local-abbrev-table text-mode-abbrev-table)) - (funcall expand)))) - -(add-hook 'foo-mode-hook - #'(lambda () - (add-hook 'abbrev-expand-functions - 'foo-mode-abbrev-expand-function - nil t))) -@end smallexample - -@node Standard Abbrev Tables, Abbrev Properties, Abbrev Expansion, Abbrevs -@comment node-name, next, previous, up -@section Standard Abbrev Tables - - Here we list the variables that hold the abbrev tables for the -preloaded major modes of Emacs. - -@defvar global-abbrev-table -This is the abbrev table for mode-independent abbrevs. The abbrevs -defined in it apply to all buffers. Each buffer may also have a local -abbrev table, whose abbrev definitions take precedence over those in the -global table. -@end defvar - -@defvar local-abbrev-table -The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. It can also be a list of -such tables. -@end defvar - -@defvar abbrev-minor-mode-table-alist -The value of this variable is a list of elements of the form -@code{(@var{mode} . @var{abbrev-table})} where @var{mode} is the name -of a variable: if the variable is bound to a non-@code{nil} value, -then the @var{abbrev-table} is active, otherwise it is ignored. -@var{abbrev-table} can also be a list of abbrev tables. -@end defvar - -@defvar fundamental-mode-abbrev-table -This is the local abbrev table used in Fundamental mode; in other words, -it is the local abbrev table in all buffers in Fundamental mode. -@end defvar - -@defvar text-mode-abbrev-table -This is the local abbrev table used in Text mode. -@end defvar - -@defvar lisp-mode-abbrev-table -This is the local abbrev table used in Lisp mode and Emacs Lisp mode. -@end defvar - -@node Abbrev Properties, Abbrev Table Properties, Standard Abbrev Tables, Abbrevs -@section Abbrev Properties - -Abbrevs have properties, some of which influence the way they work. -You can provide them as arguments to @code{define-abbrev} and you can -manipulate them with the following functions: - -@defun abbrev-put abbrev prop val -Set the property @var{prop} of @var{abbrev} to value @var{val}. -@end defun - -@defun abbrev-get abbrev prop -Return the property @var{prop} of @var{abbrev}, or @code{nil} if the -abbrev has no such property. -@end defun - -The following properties have special meanings: - -@table @code -@item :count -This property counts the number of times the abbrev has -been expanded. If not explicitly set, it is initialized to 0 by -@code{define-abbrev}. - -@item :system -If non-@code{nil}, this property marks the abbrev as a system abbrev. -Such abbrevs are not saved (@pxref{Abbrev Files}). - -@item :enable-function -If non-@code{nil}, this property should be a function of no -arguments which returns @code{nil} if the abbrev should not be used -and @code{t} otherwise. - -@item :case-fixed -If non-@code{nil}, this property indicates that the case of the -abbrev's name is significant and should only match a text with the -same pattern of capitalization. It also disables the code that -modifies the capitalization of the expansion. -@end table - -@node Abbrev Table Properties, , Abbrev Properties, Abbrevs -@section Abbrev Table Properties - -Like abbrevs, abbrev tables have properties, some of which influence -the way they work. You can provide them as arguments to -@code{define-abbrev-table} and you can manipulate them with the -functions: - -@defun abbrev-table-put table prop val -Set the property @var{prop} of abbrev table @var{table} to value @var{val}. -@end defun - -@defun abbrev-table-get table prop -Return the property @var{prop} of abbrev table @var{table}, or @code{nil} -if the abbrev has no such property. -@end defun - -The following properties have special meaning: - -@table @code -@item :enable-function -This is like the @code{:enable-function} abbrev property except that -it applies to all abbrevs in the table and is used even before trying -to find the abbrev before point so it can dynamically modify the -abbrev table. - -@item :case-fixed -This is like the @code{:case-fixed} abbrev property except that it -applies to all abbrevs in the table. - -@item :regexp -If non-@code{nil}, this property is a regular expression that -indicates how to extract the name of the abbrev before point before -looking it up in the table. When the regular expression matches -before point, the abbrev name is expected to be in submatch 1. -If this property is @code{nil}, @code{expand-function} defaults to -@code{"\\<\\(\\w+\\)\\W"}. This property allows the use of abbrevs -whose name contains characters of non-word syntax. - -@item :parents -This property holds the list of tables from which to inherit -other abbrevs. - -@item :abbrev-table-modiff -This property holds a counter incremented each time a new abbrev is -added to the table. - -@end table - - -@ignore - arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec -@end ignore diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi deleted file mode 100644 index 57cfc616f23..00000000000 --- a/doc/lispref/advice.texi +++ /dev/null @@ -1,783 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/advising -@node Advising Functions, Debugging, Byte Compilation, Top -@chapter Advising Emacs Lisp Functions -@cindex advising functions - - The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a cleaner method -for a library to customize functions defined within Emacs---cleaner -than redefining the whole function. - -@cindex piece of advice - Each function can have multiple @dfn{pieces of advice}, separately -defined. Each defined piece of advice can be @dfn{enabled} or -@dfn{disabled} explicitly. All the enabled pieces of advice for any given -function actually take effect when you @dfn{activate} advice for that -function, or when you define or redefine the function. Note that -enabling a piece of advice and activating advice for a function -are not the same thing. - - @strong{Usage Note:} Advice is useful for altering the behavior of -existing calls to an existing function. If you want the new behavior -for new calls, or for key bindings, you should define a new function -(or a new command) which uses the existing function. - - @strong{Usage note:} Advising a function can cause confusion in -debugging, since people who debug calls to the original function may -not notice that it has been modified with advice. Therefore, if you -have the possibility to change the code of that function (or ask -someone to do so) to run a hook, please solve the problem that way. -Advice should be reserved for the cases where you cannot get the -function changed. - - In particular, this means that a file in Emacs should not put advice -on a function in Emacs. There are currently a few exceptions to this -convention, but we aim to correct them. - -@menu -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. -* Combined Definition:: How advice is implemented. -@end menu - -@node Simple Advice -@section A Simple Advice Example - - The command @code{next-line} moves point down vertically one or more -lines; it is the standard binding of @kbd{C-n}. When used on the last -line of the buffer, this command inserts a newline to create a line to -move to if @code{next-line-add-newlines} is non-@code{nil} (its default -is @code{nil}.) - - Suppose you wanted to add a similar feature to @code{previous-line}, -which would insert a new line at the beginning of the buffer for the -command to move to (when @code{next-line-add-newlines} is -non-@code{nil}). How could you do this? - - You could do it by redefining the whole function, but that is not -modular. The advice feature provides a cleaner alternative: you can -effectively add your code to the existing function definition, without -actually changing or even seeing that definition. Here is how to do -this: - -@example -(defadvice previous-line (before next-line-at-end - (&optional arg try-vscroll)) - "Insert an empty line when moving up from the top line." - (if (and next-line-add-newlines (= arg 1) - (save-excursion (beginning-of-line) (bobp))) - (progn - (beginning-of-line) - (newline)))) -@end example - - This expression defines a @dfn{piece of advice} for the function -@code{previous-line}. This piece of advice is named -@code{next-line-at-end}, and the symbol @code{before} says that it is -@dfn{before-advice} which should run before the regular definition of -@code{previous-line}. @code{(&optional arg try-vscroll)} specifies -how the advice code can refer to the function's arguments. - - When this piece of advice runs, it creates an additional line, in the -situation where that is appropriate, but does not move point to that -line. This is the correct way to write the advice, because the normal -definition will run afterward and will move back to the newly inserted -line. - - Defining the advice doesn't immediately change the function -@code{previous-line}. That happens when you @dfn{activate} the advice, -like this: - -@example -(ad-activate 'previous-line) -@end example - -@noindent -This is what actually begins to use the advice that has been defined so -far for the function @code{previous-line}. Henceforth, whenever that -function is run, whether invoked by the user with @kbd{C-p} or -@kbd{M-x}, or called from Lisp, it runs the advice first, and its -regular definition second. - - This example illustrates before-advice, which is one @dfn{class} of -advice: it runs before the function's base definition. There are two -other advice classes: @dfn{after-advice}, which runs after the base -definition, and @dfn{around-advice}, which lets you specify an -expression to wrap around the invocation of the base definition. - -@node Defining Advice -@section Defining Advice -@cindex defining advice -@cindex advice, defining - - To define a piece of advice, use the macro @code{defadvice}. A call -to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun} and @code{defmacro}, but adds more: - -@findex defadvice -@example -(defadvice @var{function} (@var{class} @var{name} - @r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]} - @var{flags}...) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-form}@r{]} - @var{body-forms}...) -@end example - -@noindent -Here, @var{function} is the name of the function (or macro or special -form) to be advised. From now on, we will write just ``function'' when -describing the entity being advised, but this always includes macros and -special forms. - - In place of the argument list in an ordinary definition, an advice -definition calls for several different pieces of information. - -@cindex class of advice -@cindex before-advice -@cindex after-advice -@cindex around-advice -@var{class} specifies the @dfn{class} of the advice---one of @code{before}, -@code{after}, or @code{around}. Before-advice runs before the function -itself; after-advice runs after the function itself; around-advice is -wrapped around the execution of the function itself. After-advice and -around-advice can override the return value by setting -@code{ad-return-value}. - -@defvar ad-return-value -While advice is executing, after the function's original definition has -been executed, this variable holds its return value, which will -ultimately be returned to the caller after finishing all the advice. -After-advice and around-advice can arrange to return some other value -by storing it in this variable. -@end defvar - -The argument @var{name} is the name of the advice, a non-@code{nil} -symbol. The advice name uniquely identifies one piece of advice, within all -the pieces of advice in a particular class for a particular -@var{function}. The name allows you to refer to the piece of -advice---to redefine it, or to enable or disable it. - -The optional @var{position} specifies where, in the current list of -advice of the specified @var{class}, this new advice should be placed. -It should be either @code{first}, @code{last} or a number that specifies -a zero-based position (@code{first} is equivalent to 0). If no position -is specified, the default is @code{first}. Position values outside the -range of existing positions in this class are mapped to the beginning or -the end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -The optional @var{arglist} can be used to define the argument list for -the sake of advice. This becomes the argument list of the combined -definition that is generated in order to run the advice (@pxref{Combined -Definition}). Therefore, the advice expressions can use the argument -variables in this list to access argument values. - -The argument list used in advice need not be the same as the argument -list used in the original function, but must be compatible with it, so -that it can handle the ways the function is actually called. If two -pieces of advice for a function both specify an argument list, they must -specify the same argument list. - -@xref{Argument Access in Advice}, for more information about argument -lists and advice, and a more flexible way for advice to access the -arguments. - -The remaining elements, @var{flags}, are symbols that specify further -information about how to use this piece of advice. Here are the valid -symbols and their meanings: - -@table @code -@item activate -Activate the advice for @var{function} now. Changes in a function's -advice always take effect the next time you activate advice for the -function; this flag says to do so, for @var{function}, immediately after -defining this piece of advice. - -@cindex forward advice -This flag has no immediate effect if @var{function} itself is not defined yet (a -situation known as @dfn{forward advice}), because it is impossible to -activate an undefined function's advice. However, defining -@var{function} will automatically activate its advice. - -@item protect -Protect this piece of advice against non-local exits and errors in -preceding code and advice. Protecting advice places it as a cleanup in -an @code{unwind-protect} form, so that it will execute even if the -previous code gets an error or uses @code{throw}. @xref{Cleanups}. - -@item compile -Compile the combined definition that is used to run the advice. This -flag is ignored unless @code{activate} is also specified. -@xref{Combined Definition}. - -@item disable -Initially disable this piece of advice, so that it will not be used -unless subsequently explicitly enabled. @xref{Enabling Advice}. - -@item preactivate -Activate advice for @var{function} when this @code{defadvice} is -compiled or macroexpanded. This generates a compiled advised definition -according to the current advice state, which will be used during -activation if appropriate. @xref{Preactivation}. - -This is useful only if this @code{defadvice} is byte-compiled. -@end table - -The optional @var{documentation-string} serves to document this piece of -advice. When advice is active for @var{function}, the documentation for -@var{function} (as returned by @code{documentation}) combines the -documentation strings of all the advice for @var{function} with the -documentation string of its original function definition. - -The optional @var{interactive-form} form can be supplied to change the -interactive behavior of the original function. If more than one piece -of advice has an @var{interactive-form}, then the first one (the one -with the smallest position) found among all the advice takes precedence. - -The possibly empty list of @var{body-forms} specifies the body of the -advice. The body of an advice can access or change the arguments, the -return value, the binding environment, and perform any other kind of -side effect. - -@strong{Warning:} When you advise a macro, keep in mind that macros are -expanded when a program is compiled, not when a compiled program is run. -All subroutines used by the advice need to be available when the byte -compiler expands the macro. - -@deffn Command ad-unadvise function -This command deletes the advice from @var{function}. -@end deffn - -@deffn Command ad-unadvise-all -This command deletes all pieces of advice from all functions. -@end deffn - -@node Around-Advice -@section Around-Advice - - Around-advice lets you ``wrap'' a Lisp expression ``around'' the -original function definition. You specify where the original function -definition should go by means of the special symbol @code{ad-do-it}. -Where this symbol occurs inside the around-advice body, it is replaced -with a @code{progn} containing the forms of the surrounded code. Here -is an example: - -@example -(defadvice foo (around foo-around) - "Ignore case in `foo'." - (let ((case-fold-search t)) - ad-do-it)) -@end example - -@noindent -Its effect is to make sure that case is ignored in -searches when the original definition of @code{foo} is run. - -@defvar ad-do-it -This is not really a variable, rather a place-holder that looks like a -variable. You use it in around-advice to specify the place to run the -function's original definition and other ``earlier'' around-advice. -@end defvar - -If the around-advice does not use @code{ad-do-it}, then it does not run -the original function definition. This provides a way to override the -original definition completely. (It also overrides lower-positioned -pieces of around-advice). - -If the around-advice uses @code{ad-do-it} more than once, the original -definition is run at each place. In this way, around-advice can execute -the original definition (and lower-positioned pieces of around-advice) -several times. Another way to do that is by using @code{ad-do-it} -inside of a loop. - -@node Computed Advice -@section Computed Advice - -The macro @code{defadvice} resembles @code{defun} in that the code for -the advice, and all other information about it, are explicitly stated in -the source code. You can also create advice whose details are computed, -using the function @code{ad-add-advice}. - -@defun ad-add-advice function advice class position -Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to -@var{function} in class @var{class}. The argument @var{advice} has -this form: - -@example -(@var{name} @var{protected} @var{enabled} @var{definition}) -@end example - -@noindent -Here, @var{protected} and @var{enabled} are flags; if @var{protected} -is non-@code{nil}, the advice is protected against non-local exits -(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the -advice is initially disabled (@pxref{Enabling Advice}). -@var{definition} should have the form - -@example -(advice . @var{lambda}) -@end example - -@noindent -where @var{lambda} is a lambda expression; this lambda expression is -called in order to perform the advice. @xref{Lambda Expressions}. - -If the @var{function} argument to @code{ad-add-advice} already has one -or more pieces of advice in the specified @var{class}, then -@var{position} specifies where in the list to put the new piece of -advice. The value of @var{position} can either be @code{first}, -@code{last}, or a number (counting from 0 at the beginning of the -list). Numbers outside the range are mapped to the beginning or the -end of the range, whichever is closer. The @var{position} value is -ignored when redefining an existing piece of advice. - -If @var{function} already has a piece of @var{advice} with the same -name, then the position argument is ignored and the old advice is -replaced with the new one. -@end defun - -@node Activation of Advice -@section Activation of Advice -@cindex activating advice -@cindex advice, activating - -By default, advice does not take effect when you define it---only when -you @dfn{activate} advice for the function that was advised. However, -the advice will be activated automatically if you define or redefine -the function later. You can request the activation of advice for a -function when you define the advice, by specifying the @code{activate} -flag in the @code{defadvice}. But normally you activate the advice -for a function by calling the function @code{ad-activate} or one of -the other activation commands listed below. - -Separating the activation of advice from the act of defining it permits -you to add several pieces of advice to one function efficiently, without -redefining the function over and over as each advice is added. More -importantly, it permits defining advice for a function before that -function is actually defined. - -When a function's advice is first activated, the function's original -definition is saved, and all enabled pieces of advice for that function -are combined with the original definition to make a new definition. -(Pieces of advice that are currently disabled are not used; see -@ref{Enabling Advice}.) This definition is installed, and optionally -byte-compiled as well, depending on conditions described below. - -In all of the commands to activate advice, if @var{compile} is -@code{t} (or anything but @code{nil} or a negative number), the -command also compiles the combined definition which implements the -advice. If it is @code{nil} or a negative number, what happens -depends on @code{ad-default-compilation-action} as described below. - -@deffn Command ad-activate function &optional compile -This command activates all the advice defined for @var{function}. -@end deffn - - Activating advice does nothing if @var{function}'s advice is already -active. But if there is new advice, added since the previous time you -activated advice for @var{function}, it activates the new advice. - -@deffn Command ad-deactivate function -This command deactivates the advice for @var{function}. -@cindex deactivating advice -@c @cindex advice, deactivating "advice, activating" is just above -@end deffn - -@deffn Command ad-update function &optional compile -This command activates the advice for @var{function} -if its advice is already activated. This is useful -if you change the advice. -@end deffn - -@deffn Command ad-activate-all &optional compile -This command activates the advice for all functions. -@end deffn - -@deffn Command ad-deactivate-all -This command deactivates the advice for all functions. -@end deffn - -@deffn Command ad-update-all &optional compile -This command activates the advice for all functions -whose advice is already activated. This is useful -if you change the advice of some functions. -@end deffn - -@deffn Command ad-activate-regexp regexp &optional compile -This command activates all pieces of advice whose names match -@var{regexp}. More precisely, it activates all advice for any function -which has at least one piece of advice that matches @var{regexp}. -@end deffn - -@deffn Command ad-deactivate-regexp regexp -This command deactivates all pieces of advice whose names match -@var{regexp}. More precisely, it deactivates all advice for any -function which has at least one piece of advice that matches -@var{regexp}. -@end deffn - -@deffn Command ad-update-regexp regexp &optional compile -This command activates pieces of advice whose names match @var{regexp}, -but only those for functions whose advice is already activated. -@cindex reactivating advice - -Reactivating a function's advice is useful for putting into effect all -the changes that have been made in its advice (including enabling and -disabling specific pieces of advice; @pxref{Enabling Advice}) since the -last time it was activated. -@end deffn - -@deffn Command ad-start-advice -Turn on automatic advice activation when a function is defined or -redefined. This is the default mode. -@end deffn - -@deffn Command ad-stop-advice -Turn off automatic advice activation when a function is defined or -redefined. -@end deffn - -@defopt ad-default-compilation-action -This variable controls whether to compile the combined definition -that results from activating advice for a function. - -A value of @code{always} specifies to compile unconditionally. -A value of @code{never} specifies never compile the advice. - -A value of @code{maybe} specifies to compile if the byte compiler is -already loaded. A value of @code{like-original} specifies to compile -the advice if the original definition of the advised function is -compiled or a built-in function. - -This variable takes effect only if the @var{compile} argument of -@code{ad-activate} (or any of the above functions) did not force -compilation. -@end defopt - - If the advised definition was constructed during ``preactivation'' -(@pxref{Preactivation}), then that definition must already be compiled, -because it was constructed during byte-compilation of the file that -contained the @code{defadvice} with the @code{preactivate} flag. - -@node Enabling Advice -@section Enabling and Disabling Advice -@cindex enabling advice -@cindex advice, enabling and disabling -@cindex disabling advice - - Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it on -and off without having to undefine and redefine it. For example, here is -how to disable a particular piece of advice named @code{my-advice} for -the function @code{foo}: - -@example -(ad-disable-advice 'foo 'before 'my-advice) -@end example - - This function by itself only changes the enable flag for a piece of -advice. To make the change take effect in the advised definition, you -must activate the advice for @code{foo} again: - -@example -(ad-activate 'foo) -@end example - -@deffn Command ad-disable-advice function class name -This command disables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - -@deffn Command ad-enable-advice function class name -This command enables the piece of advice named @var{name} in class -@var{class} on @var{function}. -@end deffn - - You can also disable many pieces of advice at once, for various -functions, using a regular expression. As always, the changes take real -effect only when you next reactivate advice for the functions in -question. - -@deffn Command ad-disable-regexp regexp -This command disables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@deffn Command ad-enable-regexp regexp -This command enables all pieces of advice whose names match -@var{regexp}, in all classes, on all functions. -@end deffn - -@node Preactivation -@section Preactivation -@cindex preactivating advice -@cindex advice, preactivating - - Constructing a combined definition to execute advice is moderately -expensive. When a library advises many functions, this can make loading -the library slow. In that case, you can use @dfn{preactivation} to -construct suitable combined definitions in advance. - - To use preactivation, specify the @code{preactivate} flag when you -define the advice with @code{defadvice}. This @code{defadvice} call -creates a combined definition which embodies this piece of advice -(whether enabled or not) plus any other currently enabled advice for the -same function, and the function's own definition. If the -@code{defadvice} is compiled, that compiles the combined definition -also. - - When the function's advice is subsequently activated, if the enabled -advice for the function matches what was used to make this combined -definition, then the existing combined definition is used, thus avoiding -the need to construct one. Thus, preactivation never causes wrong -results---but it may fail to do any good, if the enabled advice at the -time of activation doesn't match what was used for preactivation. - - Here are some symptoms that can indicate that a preactivation did not -work properly, because of a mismatch. - -@itemize @bullet -@item -Activation of the advised -function takes longer than usual. -@item -The byte compiler gets -loaded while an advised function gets activated. -@item -@code{byte-compile} is included in the value of @code{features} even -though you did not ever explicitly use the byte compiler. -@end itemize - -Compiled preactivated advice works properly even if the function itself -is not defined until later; however, the function needs to be defined -when you @emph{compile} the preactivated advice. - -There is no elegant way to find out why preactivated advice is not being -used. What you can do is to trace the function -@code{ad-cache-id-verification-code} (with the function -@code{trace-function-background}) before the advised function's advice -is activated. After activation, check the value returned by -@code{ad-cache-id-verification-code} for that function: @code{verified} -means that the preactivated advice was used, while other values give -some information about why they were considered inappropriate. - - @strong{Warning:} There is one known case that can make preactivation -fail, in that a preconstructed combined definition is used even though -it fails to match the current state of advice. This can happen when two -packages define different pieces of advice with the same name, in the -same class, for the same function. But you should avoid that anyway. - -@node Argument Access in Advice -@section Argument Access in Advice - - The simplest way to access the arguments of an advised function in the -body of a piece of advice is to use the same names that the function -definition uses. To do this, you need to know the names of the argument -variables of the original function. - - While this simple method is sufficient in many cases, it has a -disadvantage: it is not robust, because it hard-codes the argument names -into the advice. If the definition of the original function changes, -the advice might break. - - Another method is to specify an argument list in the advice itself. -This avoids the need to know the original function definition's argument -names, but it has a limitation: all the advice on any particular -function must use the same argument list, because the argument list -actually used for all the advice comes from the first piece of advice -for that function. - - A more robust method is to use macros that are translated into the -proper access forms at activation time, i.e., when constructing the -advised definition. Access macros access actual arguments by position -regardless of how these actual arguments get distributed onto the -argument variables of a function. This is robust because in Emacs Lisp -the meaning of an argument is strictly determined by its position in the -argument list. - -@defmac ad-get-arg position -This returns the actual argument that was supplied at @var{position}. -@end defmac - -@defmac ad-get-args position -This returns the list of actual arguments supplied starting at -@var{position}. -@end defmac - -@defmac ad-set-arg position value -This sets the value of the actual argument at @var{position} to -@var{value} -@end defmac - -@defmac ad-set-args position value-list -This sets the list of actual arguments starting at @var{position} to -@var{value-list}. -@end defmac - - Now an example. Suppose the function @code{foo} is defined as - -@example -(defun foo (x y &optional z &rest r) ...) -@end example - -@noindent -and is then called with - -@example -(foo 0 1 2 3 4 5 6) -@end example - -@noindent -which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is -@code{(3 4 5 6)} within the body of @code{foo}. Here is what -@code{ad-get-arg} and @code{ad-get-args} return in this case: - -@example -(ad-get-arg 0) @result{} 0 -(ad-get-arg 1) @result{} 1 -(ad-get-arg 2) @result{} 2 -(ad-get-arg 3) @result{} 3 -(ad-get-args 2) @result{} (2 3 4 5 6) -(ad-get-args 4) @result{} (4 5 6) -@end example - - Setting arguments also makes sense in this example: - -@example -(ad-set-arg 5 "five") -@end example - -@noindent -has the effect of changing the sixth argument to @code{"five"}. If this -happens in advice executed before the body of @code{foo} is run, then -@var{r} will be @code{(3 4 "five" 6)} within that body. - - Here is an example of setting a tail of the argument list: - -@example -(ad-set-args 0 '(5 4 3 2 1 0)) -@end example - -@noindent -If this happens in advice executed before the body of @code{foo} is run, -then within that body, @var{x} will be 5, @var{y} will be 4, @var{z} -will be 3, and @var{r} will be @code{(2 1 0)} inside the body of -@code{foo}. - - These argument constructs are not really implemented as Lisp macros. -Instead they are implemented specially by the advice mechanism. - -@node Advising Primitives -@section Advising Primitives -@cindex advising primitives - - Advising a primitive function (@pxref{What Is a Function}) is risky. -Some primitive functions are used by the advice mechanism; advising -them could cause an infinite recursion. Also, many primitive -functions are called directly from C code. Calls to the primitive -from Lisp code will take note of the advice, but calls from C code -will ignore the advice. - -When the advice facility constructs the combined definition, it needs -to know the argument list of the original function. This is not -always possible for primitive functions. When advice cannot determine -the argument list, it uses @code{(&rest ad-subr-args)}, which always -works but is inefficient because it constructs a list of the argument -values. You can use @code{ad-define-subr-args} to declare the proper -argument names for a primitive function: - -@defun ad-define-subr-args function arglist -This function specifies that @var{arglist} should be used as the -argument list for function @var{function}. -@end defun - -For example, - -@example -(ad-define-subr-args 'fset '(sym newdef)) -@end example - -@noindent -specifies the argument list for the function @code{fset}. - -@node Combined Definition -@section The Combined Definition - - Suppose that a function has @var{n} pieces of before-advice -(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of -around-advice and @var{k} pieces of after-advice. Assuming no piece -of advice is protected, the combined definition produced to implement -the advice for a function looks like this: - -@example -(lambda @var{arglist} - @r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]} - (let (ad-return-value) - @r{before-0-body-form}... - .... - @r{before-@var{n}@minus{}1-body-form}... - @r{around-0-body-form}... - @r{around-1-body-form}... - .... - @r{around-@var{m}@minus{}1-body-form}... - (setq ad-return-value - @r{apply original definition to @var{arglist}}) - @r{end-of-around-@var{m}@minus{}1-body-form}... - .... - @r{end-of-around-1-body-form}... - @r{end-of-around-0-body-form}... - @r{after-0-body-form}... - .... - @r{after-@var{k}@minus{}1-body-form}... - ad-return-value)) -@end example - -Macros are redefined as macros, which means adding @code{macro} to -the beginning of the combined definition. - -The interactive form is present if the original function or some piece -of advice specifies one. When an interactive primitive function is -advised, advice uses a special method: it calls the primitive with -@code{call-interactively} so that it will read its own arguments. -In this case, the advice cannot access the arguments. - -The body forms of the various advice in each class are assembled -according to their specified order. The forms of around-advice @var{l} -are included in one of the forms of around-advice @var{l} @minus{} 1. - -The innermost part of the around advice onion is - -@display -apply original definition to @var{arglist} -@end display - -@noindent -whose form depends on the type of the original function. The variable -@code{ad-return-value} is set to whatever this returns. The variable is -visible to all pieces of advice, which can access and modify it before -it is actually returned from the advised function. - -The semantic structure of advised functions that contain protected -pieces of advice is the same. The only difference is that -@code{unwind-protect} forms ensure that the protected advice gets -executed even if some previous piece of advice had an error or a -non-local exit. If any around-advice is protected, then the whole -around-advice onion is protected as a result. - -@ignore - arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f -@end ignore diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi deleted file mode 100644 index df4efdf030c..00000000000 --- a/doc/lispref/anti.texi +++ /dev/null @@ -1,160 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -@c 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This node must have no pointers. - -@node Antinews, GNU Free Documentation License, System Interface, Top -@appendix Emacs 22 Antinews -@c Update the elisp.texi, vol1.texi, vol2.texi Antinews menu entries -@c with the above version number. - -For those users who live backwards in time, here is information about -downgrading to Emacs version 22.3. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs @value{EMACSVER} -features. - -@section Old Lisp Features in Emacs 22 - -@itemize @bullet -@item -The internal character representation used by Emacs is not longer -based on Unicode. In this representation, called @code{emacs-mule}, -each character belongs to one and only one script. Emacs makes no -attempt to distinguish between ``similar'' characters occurring in -different scripts. - -@item -The @code{^} interactive spec code, the function -@code{handle-shift-selection}, and the variable -@code{this-command-keys-shift-translated} have all been removed. -Shift-translated keys are no longer treated specially, making Emacs' -handling of keybindings much more consistent. - -@item -Temporarily-active regions are not created by giving the variable -@code{transient-mark-mode} values of the form @code{(only -. @var{oldvar})}. We instead use a more more complicated scheme: -setting @code{transient-mark-mode} to @code{only} enables Transient -Mark mode for the following command only, during which the value of -@code{transient-mark-mode} is set to @code{identity}; if it is still -@code{identity} at the end of the command, Transient Mark mode is -disabled. - -@item -Many minibuffer functions, such as @code{read-file-name} and -@code{minibuffer-complete}, have been rewritten in C for greater -speed. The completion code has been considerably simplified; the -completion style can no longer be changed via -@code{completion-styles-alist}, and @code{completing-read} no longer -recognizes the special values @code{confirm-only} and -@code{confirm-after-completion} for its @var{require-match} argument. - -@item -Emacs no longer supports explicitly-numbered groups in regular -expressions. - -@item -The @code{permanent-local-hook} function property has no special -meaning. - -@item -The @code{functionp} function now returns @code{t} for special forms. - -@item -The @code{interactive-form} symbol property has no special meaning. -Once you supply a function with an interactive form, the only way to -change it is to redefine the function. - -@item -The @code{ignore-errors} macro has been moved into the @code{cl} -package. - -@item -Variables can now be both buffer-local and frame-local; buffer-local -bindings take precedence over frame-local bindings. - -@item -Faces can no longer be remapped. - -@item -Lisp programs now specify fonts by their names, which are strings -following the XLFD (X logical font descriptor) format. Fonts are no -longer represented using a special set of ``font'' data types. The -various functions that act on these data types, such as @code{fontp}, -@code{font-spec}, and @code{list-fonts}, have all been deleted. - -@item -Emacs does not recognize the @code{FontBackend} X resource and the -@code{font-backend} frame parameter. On the X Window System, fonts -are always drawn using the X core font driver. - -@item -Display terminals are no longer represented using a ``terminal'' data -type; this is not necessary, because we have removed the ability to -display on graphical and text-only terminals simultaneously. For the -same reason, the @code{window-system} variable is no longer -frame-local, and the @code{window-system} function has been removed. - -@item -The functions @code{list-system-processes} and -@code{process-attributes} have been removed. To get information about -system processes, call an external program, such as @command{ps}. - -@item -The function @code{locate-user-emacs-file} and the variable -@code{user-emacs-directory} have been removed. Instead, use -hard-coded values pointing to @file{~/.emacs.d}. - -@item -@code{vertical-motion} can no longer be told to move to a specific -column; it always puts point on the first column of a line. - -@item -Windows no longer have parameters. - -@item -The @code{display-buffer} function has been rewritten in C. Its -window-splitting heuristics are a little less sophisticated, and a -little less documented. Window-splitting is handled internally, -instead of using @code{split-window-preferred-function} (which has -been removed). Windows are never split horizontally; the variable -@code{split-width-threshold} has been removed. - -@item -The @code{mode-name} variable now accepts only string values, and -cannot take the form of a mode-line construct. - -@item -The behavior of @code{map-char-table} has changed. It calls the -mapping function for every single character in the table, instead of -using cons cells to represent contiguous character code ranges. - -@item -Several keymaps have been eliminated: @code{input-decode-map}, -@code{local-function-key-map}, @code{search-map}, -@code{multi-query-replace-map}, and -@code{minibuffer-local-shell-command-map}. - -@item -Many functions have been removed, including: @code{buffer-swap-text}, -@code{emacs-init-time}, @code{emacs-uptime}, @code{use-region-p}, -@code{region-active-p}, @code{start-file-process}, -@code{process-lines}, @code{image-refresh}, -@code{match-substitute-replacement}, @code{word-search-forward-lax}, -and @code{word-search-backward-lax}. - -@item -Many variables have been removed, including @code{read-circle}, -@code{after-init-time} and @code{before-init-time}, -@code{generate-autoload-cookie}, @code{file-local-variables-alist}, -@code{replace-search-function} and @code{replace-re-search-function}, -@code{inhibit-changing-match-data}, @code{wrap-prefix}, and -@code{line-prefix}, -@end itemize - -@ignore - arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6 -@end ignore diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi deleted file mode 100644 index c423b5668c2..00000000000 --- a/doc/lispref/back.texi +++ /dev/null @@ -1,42 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@c %**start of header -@setfilename back-cover -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header -. -@sp 7 -@center @titlefont {GNU Emacs Lisp} -@sp 1 - -@quotation - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual describes Emacs Lisp. Generally speaking, the earlier -chapters describe features of Emacs Lisp that have counterparts in -many programming languages, and later chapters describe features that -are peculiar to Emacs Lisp or relate specifically to editing. -@end quotation - -@hfil -@bye - -@ignore - arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1 -@end ignore diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi deleted file mode 100644 index 6de8594607f..00000000000 --- a/doc/lispref/backups.texi +++ /dev/null @@ -1,756 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/backups -@node Backups and Auto-Saving, Buffers, Files, Top -@chapter Backups and Auto-Saving -@cindex backups and auto-saving - - Backup files and auto-save files are two methods by which Emacs tries -to protect the user from the consequences of crashes or of the user's -own errors. Auto-saving preserves the text from earlier in the current -editing session; backup files preserve file contents prior to the -current session. - -@menu -* Backup Files:: How backup files are made; how their names are chosen. -* Auto-Saving:: How auto-save files are made; how their names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize what it does. -@end menu - -@node Backup Files -@section Backup Files -@cindex backup file - - A @dfn{backup file} is a copy of the old contents of a file you are -editing. Emacs makes a backup file the first time you save a buffer -into its visited file. Thus, normally, the backup file contains the -contents of the file as it was before the current editing session. -The contents of the backup file normally remain unchanged once it -exists. - - Backups are usually made by renaming the visited file to a new name. -Optionally, you can specify that backup files should be made by copying -the visited file. This choice makes a difference for files with -multiple names; it also can affect whether the edited file remains owned -by the original owner or becomes owned by the user editing it. - - By default, Emacs makes a single backup file for each file edited. -You can alternatively request numbered backups; then each new backup -file gets a new name. You can delete old numbered backups when you -don't want them any more, or Emacs can delete them automatically. - -@menu -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. -@end menu - -@node Making Backups -@subsection Making Backup Files - -@defun backup-buffer - This function makes a backup of the file visited by the current -buffer, if appropriate. It is called by @code{save-buffer} before -saving the buffer the first time. - -If a backup was made by renaming, the return value is a cons cell of -the form (@var{modes} . @var{backupname}), where @var{modes} are the -mode bits of the original file, as returned by @code{file-modes} -(@pxref{File Attributes,, Other Information about Files}), and -@var{backupname} is the name of the backup. In all other cases, that -is, if a backup was made by copying or if no backup was made, this -function returns @code{nil}. -@end defun - -@defvar buffer-backed-up - This buffer-local variable says whether this buffer's file has -been backed up on account of this buffer. If it is non-@code{nil}, -the backup file has been written. Otherwise, the file should be backed -up when it is next saved (if backups are enabled). This is a -permanent local; @code{kill-all-local-variables} does not alter@tie{}it. -@end defvar - -@defopt make-backup-files -This variable determines whether or not to make backup files. If it -is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time---provided that @code{backup-inhibited} -is @code{nil} (see below). - -The following example shows how to change the @code{make-backup-files} -variable only in the Rmail buffers and not elsewhere. Setting it -@code{nil} stops Emacs from making backups of these files, which may -save disk space. (You would put this code in your init file.) - -@smallexample -@group -(add-hook 'rmail-mode-hook - (function (lambda () - (make-local-variable - 'make-backup-files) - (setq make-backup-files nil)))) -@end group -@end smallexample -@end defopt - -@defvar backup-enable-predicate -This variable's value is a function to be called on certain occasions to -decide whether a file should have backup files. The function receives -one argument, an absolute file name to consider. If the function returns -@code{nil}, backups are disabled for that file. Otherwise, the other -variables in this section say whether and how to make backups. - -@findex normal-backup-enable-predicate -The default value is @code{normal-backup-enable-predicate}, which checks -for files in @code{temporary-file-directory} and -@code{small-temporary-file-directory}. -@end defvar - -@defvar backup-inhibited -If this variable is non-@code{nil}, backups are inhibited. It records -the result of testing @code{backup-enable-predicate} on the visited file -name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. For example, VC sets this -variable non-@code{nil} to prevent making backups for files managed -with a version control system. - -This is a permanent local, so that changing the major mode does not lose -its value. Major modes should not set this variable---they should set -@code{make-backup-files} instead. -@end defvar - -@defopt backup-directory-alist -This variable's value is an alist of filename patterns and backup -directory names. Each element looks like -@smallexample -(@var{regexp} . @var{directory}) -@end smallexample - -@noindent -Backups of files with names matching @var{regexp} will be made in -@var{directory}. @var{directory} may be relative or absolute. If it is -absolute, so that all matching files are backed up into the same -directory, the file names in this directory will be the full name of the -file backed up with all directory separators changed to @samp{!} to -prevent clashes. This will not work correctly if your filesystem -truncates the resulting name. - -For the common case of all backups going into one directory, the alist -should contain a single element pairing @samp{"."} with the appropriate -directory name. - -If this variable is @code{nil}, or it fails to match a filename, the -backup is made in the original file's directory. - -On MS-DOS filesystems without long names this variable is always -ignored. -@end defopt - -@defopt make-backup-file-name-function -This variable's value is a function to use for making backups instead -of the default @code{make-backup-file-name}. A value of @code{nil} -gives the default @code{make-backup-file-name} behavior. -@xref{Backup Names,, Naming Backup Files}. - -This could be buffer-local to do something special for specific -files. If you define it, you may need to change -@code{backup-file-name-p} and @code{file-name-sans-versions} too. -@end defopt - - -@node Rename or Copy -@subsection Backup by Renaming or by Copying? -@cindex backup files, rename or copy - - There are two ways that Emacs can make a backup file: - -@itemize @bullet -@item -Emacs can rename the original file so that it becomes a backup file, and -then write the buffer being saved into a new file. After this -procedure, any other names (i.e., hard links) of the original file now -refer to the backup file. The new file is owned by the user doing the -editing, and its group is the default for new files written by the user -in that directory. - -@item -Emacs can copy the original file into a backup file, and then overwrite -the original file with new contents. After this procedure, any other -names (i.e., hard links) of the original file continue to refer to the -current (updated) version of the file. The file's owner and group will -be unchanged. -@end itemize - - The first method, renaming, is the default. - - The variable @code{backup-by-copying}, if non-@code{nil}, says to use -the second method, which is to copy the original file and overwrite it -with the new buffer contents. The variable @code{file-precious-flag}, -if non-@code{nil}, also has this effect (as a sideline of its main -significance). @xref{Saving Buffers}. - -@defopt backup-by-copying -If this variable is non-@code{nil}, Emacs always makes backup files by -copying. -@end defopt - - The following three variables, when non-@code{nil}, cause the second -method to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - -@defopt backup-by-copying-when-linked -If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-mismatch -If this variable is non-@code{nil}, Emacs makes backups by copying in cases -where renaming would change either the owner or the group of the file. - -The value has no effect when renaming would not alter the owner or -group of the file; that is, for files which are owned by the user and -whose group matches the default for a new file created there by the -user. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defopt - -@defopt backup-by-copying-when-privileged-mismatch -This variable, if non-@code{nil}, specifies the same behavior as -@code{backup-by-copying-when-mismatch}, but only for certain user-id -values: namely, those less than or equal to a certain number. You set -this variable to that number. - -Thus, if you set @code{backup-by-copying-when-privileged-mismatch} -to 0, backup by copying is done for the superuser only, -when necessary to prevent a change in the owner of the file. - -The default is 200. -@end defopt - -@node Numbered Backups -@subsection Making and Deleting Numbered Backup Files - - If a file's name is @file{foo}, the names of its numbered backup -versions are @file{foo.~@var{v}~}, for various integers @var{v}, like -this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, -@file{foo.~259~}, and so on. - -@defopt version-control -This variable controls whether to make a single non-numbered backup -file or multiple numbered backups. - -@table @asis -@item @code{nil} -Make numbered backups if the visited file already has numbered backups; -otherwise, do not. This is the default. - -@item @code{never} -Do not make numbered backups. - -@item @var{anything else} -Make numbered backups. -@end table -@end defopt - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. Emacs can do this -automatically or it can ask the user whether to delete them. - -@defopt kept-new-versions -The value of this variable is the number of newest versions to keep -when a new numbered backup is made. The newly made backup is included -in the count. The default value is@tie{}2. -@end defopt - -@defopt kept-old-versions -The value of this variable is the number of oldest versions to keep -when a new numbered backup is made. The default value is@tie{}2. -@end defopt - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function @code{find-backup-file-name} -(@pxref{Backup Names}) is responsible for determining which backup -versions to delete, but does not delete them itself. - -@defopt delete-old-versions -If this variable is @code{t}, then saving a file deletes excess -backup versions silently. If it is @code{nil}, that means -to ask for confirmation before deleting excess backups. -Otherwise, they are not deleted at all. -@end defopt - -@defopt dired-kept-versions -This variable specifies how many of the newest backup versions to keep -in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the -same thing @code{kept-new-versions} specifies when you make a new backup -file. The default is@tie{}2. -@end defopt - -@node Backup Names -@subsection Naming Backup Files - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - -@defun backup-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -possible name for a backup file. It just checks the name, not whether -a file with the name @var{filename} exists. - -@smallexample -@group -(backup-file-name-p "foo") - @result{} nil -@end group -@group -(backup-file-name-p "foo~") - @result{} 3 -@end group -@end smallexample - -The standard definition of this function is as follows: - -@smallexample -@group -(defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ -name (numeric or not)..." - (string-match "~\\'" file)) -@end group -@end smallexample - -@noindent -Thus, the function returns a non-@code{nil} value if the file name ends -with a @samp{~}. (We use a backslash to split the documentation -string's first line into two lines in the text, but produce just one -line in the string itself.) - -This simple expression is placed in a separate function to make it easy -to redefine for customization. -@end defun - -@defun make-backup-file-name filename -This function returns a string that is the name to use for a -non-numbered backup file for file @var{filename}. On Unix, this is just -@var{filename} with a tilde appended. - -The standard definition of this function, on most operating systems, is -as follows: - -@smallexample -@group -(defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE..." - (concat file "~")) -@end group -@end smallexample - -You can change the backup-file naming convention by redefining this -function. The following example redefines @code{make-backup-file-name} -to prepend a @samp{.} in addition to appending a tilde: - -@smallexample -@group -(defun make-backup-file-name (filename) - (expand-file-name - (concat "." (file-name-nondirectory filename) "~") - (file-name-directory filename))) -@end group - -@group -(make-backup-file-name "backups.texi") - @result{} ".backups.texi~" -@end group -@end smallexample - -Some parts of Emacs, including some Dired commands, assume that backup -file names end with @samp{~}. If you do not follow that convention, it -will not cause serious problems, but these commands may give -less-than-desirable results. -@end defun - -@defun find-backup-file-name filename -This function computes the file name for a new backup file for -@var{filename}. It may also propose certain existing backup files for -deletion. @code{find-backup-file-name} returns a list whose @sc{car} is -the name for the new backup file and whose @sc{cdr} is a list of backup -files whose deletion is proposed. The value can also be @code{nil}, -which means not to make a backup. - -Two variables, @code{kept-old-versions} and @code{kept-new-versions}, -determine which backup versions should be kept. This function keeps -those versions by excluding them from the @sc{cdr} of the value. -@xref{Numbered Backups}. - -In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' -version that the caller should consider deleting now. - -@smallexample -@group -(find-backup-file-name "~rms/foo") - @result{} ("~rms/foo.~5~" "~rms/foo.~3~") -@end group -@end smallexample -@end defun - -@c Emacs 19 feature -@defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. - -Some file comparison commands use this function so that they can -automatically compare a file with its most recent backup. -@end defun - -@node Auto-Saving -@section Auto-Saving -@c @cindex auto-saving Lots of symbols starting with auto-save here. - - Emacs periodically saves all files that you are visiting; this is -called @dfn{auto-saving}. Auto-saving prevents you from losing more -than a limited amount of work if the system crashes. By default, -auto-saves happen every 300 keystrokes, or after around 30 seconds of -idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against -Disasters, emacs, The GNU Emacs Manual}, for information on auto-save -for users. Here we describe the functions used to implement auto-saving -and the variables that control them. - -@defvar buffer-auto-save-file-name -This buffer-local variable is the name of the file used for -auto-saving the current buffer. It is @code{nil} if the buffer -should not be auto-saved. - -@example -@group -buffer-auto-save-file-name - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example -@end defvar - -@deffn Command auto-save-mode arg -When used interactively without an argument, this command is a toggle -switch: it turns on auto-saving of the current buffer if it is off, and -vice versa. With an argument @var{arg}, the command turns auto-saving -on if the value of @var{arg} is @code{t}, a nonempty list, or a positive -integer. Otherwise, it turns auto-saving off. -@end deffn - -@defun auto-save-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It assumes -the usual naming convention for auto-save files: a name that -begins and ends with hash marks (@samp{#}) is a possible auto-save file -name. The argument @var{filename} should not contain a directory part. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@group -(auto-save-file-name-p "#backups.texi#") - @result{} 0 -@end group -@group -(auto-save-file-name-p "backups.texi") - @result{} nil -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. -@end defun - -@defun make-auto-save-file-name -This function returns the file name to use for auto-saving the current -buffer. This is just the file name with hash marks (@samp{#}) prepended -and appended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); callers of this -function should check that variable first. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backups.texi#" -@end group -@end example - -Here is a simplified version of the standard definition of this -function: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer.." - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. -@end defun - -@defopt auto-save-visited-file-name -If this variable is non-@code{nil}, Emacs auto-saves buffers in -the files they are visiting. That is, the auto-save is done in the same -file that you are editing. Normally, this variable is @code{nil}, so -auto-save files have distinct names that are created by -@code{make-auto-save-file-name}. - -When you change the value of this variable, the new value does not take -effect in an existing buffer until the next time auto-save mode is -reenabled in it. If auto-save mode is already enabled, auto-saves -continue to go in the same file name until @code{auto-save-mode} is -called again. -@end defopt - -@defun recent-auto-save-p -This function returns @code{t} if the current buffer has been -auto-saved since the last time it was read in or saved. -@end defun - -@defun set-buffer-auto-saved -This function marks the current buffer as auto-saved. The buffer will -not be auto-saved again until the buffer text is changed again. The -function returns @code{nil}. -@end defun - -@defopt auto-save-interval -The value of this variable specifies how often to do auto-saving, in -terms of number of input events. Each time this many additional input -events are read, Emacs does auto-saving for all buffers in which that is -enabled. Setting this to zero disables autosaving based on the -number of characters typed. -@end defopt - -@defopt auto-save-timeout -The value of this variable is the number of seconds of idle time that -should cause auto-saving. Each time the user pauses for this long, -Emacs does auto-saving for all buffers in which that is enabled. (If -the current buffer is large, the specified timeout is multiplied by a -factor that increases as the size increases; for a million-byte -buffer, the factor is almost 4.) - -If the value is zero or @code{nil}, then auto-saving is not done as a -result of idleness, only after a certain number of input events as -specified by @code{auto-save-interval}. -@end defopt - -@defvar auto-save-hook -This normal hook is run whenever an auto-save is about to happen. -@end defvar - -@defopt auto-save-default -If this variable is non-@code{nil}, buffers that are visiting files -have auto-saving enabled by default. Otherwise, they do not. -@end defopt - -@deffn Command do-auto-save &optional no-message current-only -This function auto-saves all buffers that need to be auto-saved. It -saves all buffers for which auto-saving is enabled and that have been -changed since the previous auto-save. - -If any buffers are auto-saved, @code{do-auto-save} normally displays a -message saying @samp{Auto-saving...} in the echo area while -auto-saving is going on. However, if @var{no-message} is -non-@code{nil}, the message is inhibited. - -If @var{current-only} is non-@code{nil}, only the current buffer -is auto-saved. -@end deffn - -@defun delete-auto-save-file-if-necessary &optional force -This function deletes the current buffer's auto-save file if -@code{delete-auto-save-files} is non-@code{nil}. It is called every -time a buffer is saved. - -Unless @var{force} is non-@code{nil}, this function only deletes the -file if it was written by the current Emacs session since the last -true save. -@end defun - -@defopt delete-auto-save-files -This variable is used by the function -@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, -Emacs deletes auto-save files when a true save is done (in the visited -file). This saves disk space and unclutters your directory. -@end defopt - -@defun rename-auto-save-file -This function adjusts the current buffer's auto-save file name if the -visited file name has changed. It also renames an existing auto-save -file, if it was made in the current Emacs session. If the visited -file name has not changed, this function does nothing. -@end defun - -@defvar buffer-saved-size -The value of this buffer-local variable is the length of the current -buffer, when it was last read in, saved, or auto-saved. This is -used to detect a substantial decrease in size, and turn off auto-saving -in response. - -If it is @minus{}1, that means auto-saving is temporarily shut off in -this buffer due to a substantial decrease in size. Explicitly saving -the buffer stores a positive value in this variable, thus reenabling -auto-saving. Turning auto-save mode off or on also updates this -variable, so that the substantial decrease in size is forgotten. -@end defvar - -@defvar auto-save-list-file-name -This variable (if non-@code{nil}) specifies a file for recording the -names of all the auto-save files. Each time Emacs does auto-saving, it -writes two lines into this file for each buffer that has auto-saving -enabled. The first line gives the name of the visited file (it's empty -if the buffer has none), and the second gives the name of the auto-save -file. - -When Emacs exits normally, it deletes this file; if Emacs crashes, you -can look in the file to find all the auto-save files that might contain -work that was otherwise lost. The @code{recover-session} command uses -this file to find them. - -The default name for this file specifies your home directory and starts -with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the -host name. -@end defvar - -@defopt auto-save-list-file-prefix -After Emacs reads your init file, it initializes -@code{auto-save-list-file-name} (if you have not already set it -non-@code{nil}) based on this prefix, adding the host name and process -ID. If you set this to @code{nil} in your init file, then Emacs does -not initialize @code{auto-save-list-file-name}. -@end defopt - -@node Reverting -@section Reverting - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file with the @code{revert-buffer} command. @xref{Reverting, , -Reverting a Buffer, emacs, The GNU Emacs Manual}. - -@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes -This command replaces the buffer text with the text of the visited -file on disk. This action undoes all changes since the file was visited -or saved. - -By default, if the latest auto-save file is more recent than the visited -file, and the argument @var{ignore-auto} is @code{nil}, -@code{revert-buffer} asks the user whether to use that auto-save -instead. When you invoke this command interactively, @var{ignore-auto} -is @code{t} if there is no numeric prefix argument; thus, the -interactive default is not to check the auto-save file. - -Normally, @code{revert-buffer} asks for confirmation before it changes -the buffer; but if the argument @var{noconfirm} is non-@code{nil}, -@code{revert-buffer} does not ask for confirmation. - -Normally, this command reinitializes the buffer's major and minor modes -using @code{normal-mode}. But if @var{preserve-modes} is -non-@code{nil}, the modes remain unchanged. - -Reverting tries to preserve marker positions in the buffer by using the -replacement feature of @code{insert-file-contents}. If the buffer -contents and the file contents are identical before the revert -operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; in that case, it preserves -the markers in the unchanged text (if any) at the beginning and end of -the buffer. Preserving any additional markers would be problematical. -@end deffn - -You can customize how @code{revert-buffer} does its work by setting -the variables described in the rest of this section. - -@defopt revert-without-query -This variable holds a list of files that should be reverted without -query. The value is a list of regular expressions. If the visited file -name matches one of these regular expressions, and the file has changed -on disk but the buffer is not modified, then @code{revert-buffer} -reverts the file without asking the user for confirmation. -@end defopt - - Some major modes customize @code{revert-buffer} by making -buffer-local bindings for these variables: - -@defvar revert-buffer-function -@anchor{Definition of revert-buffer-function} -The value of this variable is the function to use to revert this -buffer. If non-@code{nil}, it should be a function with two optional -arguments to do the work of reverting. The two optional arguments, -@var{ignore-auto} and @var{noconfirm}, are the arguments that -@code{revert-buffer} received. If the value is @code{nil}, reverting -works the usual way. - -Modes such as Dired mode, in which the text being edited does not -consist of a file's contents but can be regenerated in some other -fashion, can give this variable a buffer-local value that is a function to -regenerate the contents. -@end defvar - -@defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, specifies the function to use to -insert the updated contents when reverting this buffer. The function -receives two arguments: first the file name to use; second, @code{t} if -the user has asked to read the auto-save file. - -The reason for a mode to set this variable instead of -@code{revert-buffer-function} is to avoid duplicating or replacing the -rest of what @code{revert-buffer} does: asking for confirmation, -clearing the undo list, deciding the proper major mode, and running the -hooks listed below. -@end defvar - -@defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. -@end defvar - -@defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. -@end defvar - -@ignore - arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f -@end ignore diff --git a/doc/lispref/book-spine.texinfo b/doc/lispref/book-spine.texinfo deleted file mode 100644 index 4f4c91a4404..00000000000 --- a/doc/lispref/book-spine.texinfo +++ /dev/null @@ -1,29 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename book-spine -@settitle book-spine -@c %**end of header - -@c need dot in text so first space command works! -. -@sp 7 - -@center @titlefont{GNU Emacs Lisp Reference Manual} -@sp 5 -@center GNU -@center Emacs Version 23.1 -@center for Unix Users -@sp 5 - -@center by -@center Bil Lewis, -@center Dan LaLiberte, -@center and the -@center GNU Manual Group -@sp 5 -@center Free Software Foundation -@bye - -@ignore - arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87 -@end ignore diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi deleted file mode 100644 index 5d03865e8e2..00000000000 --- a/doc/lispref/buffers.texi +++ /dev/null @@ -1,1221 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/buffers -@node Buffers, Windows, Backups and Auto-Saving, Top -@chapter Buffers -@cindex buffer - - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -@menu -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. -@end menu - -@node Buffer Basics -@comment node-name, next, previous, up -@section Buffer Basics - -@ifnottex - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. Although several buffers -normally exist, only one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. -@end ifnottex - - Buffers in Emacs editing are objects that have distinct names and hold -text that can be edited. Buffers appear to Lisp programs as a special -data type. You can think of the contents of a buffer as a string that -you can extend; insertions and deletions may occur in any part of the -buffer. @xref{Text}. - - A Lisp buffer object contains numerous pieces of information. Some of -this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -@dfn{buffer-local} variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as @code{fill-column} or @code{comment-column} in this -way. For more information about buffer-local variables and functions -related to them, see @ref{Buffer-Local Variables}. - - For functions and variables related to visiting files in buffers, see -@ref{Visiting Files} and @ref{Saving Buffers}. For functions and -variables related to the display of buffers in windows, see -@ref{Buffers and Windows}. - -@defun bufferp object -This function returns @code{t} if @var{object} is a buffer, -@code{nil} otherwise. -@end defun - -@node Current Buffer -@section The Current Buffer -@cindex selecting a buffer -@cindex changing to another buffer -@cindex current buffer - - There are, in general, many buffers in an Emacs session. At any time, -one of them is designated as the @dfn{current buffer}. This is the -buffer in which most editing takes place, because most of the primitives -for examining or changing text in a buffer operate implicitly on the -current buffer (@pxref{Text}). Normally the buffer that is displayed on -the screen in the selected window is the current buffer, but this is not -always so: a Lisp program can temporarily designate any buffer as -current in order to operate on its contents, without changing what is -displayed on the screen. - - The way to designate a current buffer in a Lisp program is by calling -@code{set-buffer}. The specified buffer remains current until a new one -is designated. - - When an editing command returns to the editor command loop, the -command loop designates the buffer displayed in the selected window as -current, to prevent confusion: the buffer that the cursor is in when -Emacs reads a command is the buffer that the command will apply to. -(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to -switch visibly to a different buffer so that the user can edit it. For -that, you must use the functions described in @ref{Displaying Buffers}. - - @strong{Warning:} Lisp functions that change to a different current buffer -should not depend on the command loop to set it back afterwards. -Editing commands written in Emacs Lisp can be called from other programs -as well as from the command loop; it is convenient for the caller if -the subroutine does not change which buffer is current (unless, of -course, that is the subroutine's purpose). Therefore, you should -normally use @code{set-buffer} within a @code{save-current-buffer} or -@code{save-excursion} (@pxref{Excursions}) form that will restore the -current buffer when your function is done. Here, as an example, is a -simplified version of the command @code{append-to-buffer}: - -@example -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region." - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (save-current-buffer - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - -@noindent -This function binds a local variable to record the current buffer, and -then @code{save-current-buffer} arranges to make it current again. -Next, @code{set-buffer} makes the specified buffer current. Finally, -@code{insert-buffer-substring} copies the string from the original -current buffer to the specified (and now current) buffer. - - If the buffer appended to happens to be displayed in some window, -the next redisplay will show how its text has changed. Otherwise, you -will not see the change immediately on the screen. The buffer becomes -current temporarily during the execution of the command, but this does -not cause it to be displayed. - - If you make local bindings (with @code{let} or function arguments) for -a variable that may also have buffer-local bindings, make sure that the -same buffer is current at the beginning and at the end of the local -binding's scope. Otherwise you might bind it in one buffer and unbind -it in another! There are two ways to do this. In simple cases, you may -see that nothing ever changes the current buffer within the scope of the -binding. Otherwise, use @code{save-current-buffer} or -@code{save-excursion} to make sure that the buffer current at the -beginning is current again whenever the variable is unbound. - - Do not rely on using @code{set-buffer} to change the current buffer -back, because that won't do the job if a quit happens while the wrong -buffer is current. For instance, in the previous example, it would -have been wrong to do this: - -@example -@group - (let ((oldbuf (current-buffer))) - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end) - (set-buffer oldbuf)) -@end group -@end example - -@noindent -Using @code{save-current-buffer}, as we did, handles quitting, errors, -and @code{throw}, as well as ordinary evaluation. - -@defun current-buffer -This function returns the current buffer. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example -@end defun - -@defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. -@var{buffer-or-name} must be an existing buffer or the name of an -existing buffer. The return value is the buffer made current. - -This function does not display the buffer in any window, so the user -cannot necessarily see the buffer. But Lisp programs will now operate -on it. -@end defun - -@defspec save-current-buffer body@dots{} -The @code{save-current-buffer} special form saves the identity of the -current buffer, evaluates the @var{body} forms, and finally restores -that buffer as current. The return value is the value of the last -form in @var{body}. The current buffer is restored even in case of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -If the buffer that used to be current has been killed by the time of -exit from @code{save-current-buffer}, then it is not made current again, -of course. Instead, whichever buffer was current just before exit -remains current. -@end defspec - -@defmac with-current-buffer buffer-or-name body@dots{} -The @code{with-current-buffer} macro saves the identity of the current -buffer, makes @var{buffer-or-name} current, evaluates the @var{body} -forms, and finally restores the current buffer. @var{buffer-or-name} -must specify an existing buffer or the name of an existing buffer. - -The return value is the value of the last form in @var{body}. The -current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). -@end defmac - -@defmac with-temp-buffer body@dots{} -@anchor{Definition of with-temp-buffer} -The @code{with-temp-buffer} macro evaluates the @var{body} forms -with a temporary buffer as the current buffer. It saves the identity of -the current buffer, creates a temporary buffer and makes it current, -evaluates the @var{body} forms, and finally restores the previous -current buffer while killing the temporary buffer. By default, undo -information (@pxref{Undo}) is not recorded in the buffer created by -this macro (but @var{body} can enable that, if needed). - -The return value is the value of the last form in @var{body}. You can -return the contents of the temporary buffer by using -@code{(buffer-string)} as the last form. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-file} in @ref{Definition of with-temp-file,, -Writing to Files}. -@end defmac - -@node Buffer Names -@section Buffer Names -@cindex buffer names - - Each buffer has a unique name, which is a string. Many of the -functions that work on buffers accept either a buffer or a buffer name -as an argument. Any argument called @var{buffer-or-name} is of this -sort, and an error is signaled if it is neither a string nor a buffer. -Any argument called @var{buffer} must be an actual buffer -object, not a name. - -@cindex hidden buffers -@cindex buffers without undo information - Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} and -@code{buffer-menu} commands don't mention them (but if such a buffer -visits a file, it @strong{is} mentioned). A name starting with -space also initially disables recording undo information; see -@ref{Undo}. - -@defun buffer-name &optional buffer -This function returns the name of @var{buffer} as a string. -@var{buffer} defaults to the current buffer. - -If @code{buffer-name} returns @code{nil}, it means that @var{buffer} -has been killed. @xref{Killing Buffers}. - -@example -@group -(buffer-name) - @result{} "buffers.texi" -@end group - -@group -(setq foo (get-buffer "temp")) - @result{} # -@end group -@group -(kill-buffer foo) - @result{} nil -@end group -@group -(buffer-name foo) - @result{} nil -@end group -@group -foo - @result{} # -@end group -@end example -@end defun - -@deffn Command rename-buffer newname &optional unique -This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string. - -@c Emacs 19 feature -Ordinarily, @code{rename-buffer} signals an error if @var{newname} is -already in use. However, if @var{unique} is non-@code{nil}, it modifies -@var{newname} to make a name that is not in use. Interactively, you can -make @var{unique} non-@code{nil} with a numeric prefix argument. -(This is how the command @code{rename-uniquely} is implemented.) - -This function returns the name actually given to the buffer. -@end deffn - -@defun get-buffer buffer-or-name -This function returns the buffer specified by @var{buffer-or-name}. -If @var{buffer-or-name} is a string and there is no buffer with that -name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given; that is not very useful, so the argument is usually -a name. For example: - -@example -@group -(setq b (get-buffer "lewis")) - @result{} # -@end group -@group -(get-buffer b) - @result{} # -@end group -@group -(get-buffer "Frazzle-nots") - @result{} nil -@end group -@end example - -See also the function @code{get-buffer-create} in @ref{Creating Buffers}. -@end defun - -@c Emacs 19 feature -@defun generate-new-buffer-name starting-name &optional ignore -This function returns a name that would be unique for a new buffer---but -does not create the buffer. It starts with @var{starting-name}, and -produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. It starts at 2 and keeps -incrementing the number until it is not the name of an existing buffer. - -If the optional second argument @var{ignore} is non-@code{nil}, it -should be a string, a potential buffer name. It means to consider -that potential buffer acceptable, if it is tried, even it is the name -of an existing buffer (which would normally be rejected). Thus, if -buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and -@samp{foo<4>} exist, - -@example -(generate-new-buffer-name "foo") - @result{} "foo<5>" -(generate-new-buffer-name "foo" "foo<3>") - @result{} "foo<3>" -(generate-new-buffer-name "foo" "foo<6>") - @result{} "foo<5>" -@end example - -See the related function @code{generate-new-buffer} in @ref{Creating -Buffers}. -@end defun - -@node Buffer File Name -@section Buffer File Name -@cindex visited file -@cindex buffer file name -@cindex file name of buffer - - The @dfn{buffer file name} is the name of the file that is visited in -that buffer. When a buffer is not visiting a file, its buffer file name -is @code{nil}. Most of the time, the buffer name is the same as the -nondirectory part of the buffer file name, but the buffer file name and -the buffer name are distinct and can be set independently. -@xref{Visiting Files}. - -@defun buffer-file-name &optional buffer -This function returns the absolute file name of the file that -@var{buffer} is visiting. If @var{buffer} is not visiting any file, -@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not -supplied, it defaults to the current buffer. - -@example -@group -(buffer-file-name (other-buffer)) - @result{} "/usr/user/lewis/manual/files.texi" -@end group -@end example -@end defun - -@defvar buffer-file-name -This buffer-local variable contains the name of the file being visited -in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local variable, unaffected by -@code{kill-all-local-variables}. - -@example -@group -buffer-file-name - @result{} "/usr/user/lewis/manual/buffers.texi" -@end group -@end example - -It is risky to change this variable's value without doing various other -things. Normally it is better to use @code{set-visited-file-name} (see -below); some of the things done there, such as changing the buffer name, -are not strictly necessary, but others are essential to avoid confusing -Emacs. -@end defvar - -@defvar buffer-file-truename -This buffer-local variable holds the abbreviated truename of the file -visited in the current buffer, or @code{nil} if no file is visited. -It is a permanent local, unaffected by -@code{kill-all-local-variables}. @xref{Truenames}, and -@ref{Definition of abbreviate-file-name}. -@end defvar - -@defvar buffer-file-number -This buffer-local variable holds the file number and directory device -number of the file visited in the current buffer, or @code{nil} if no -file or a nonexistent file is visited. It is a permanent local, -unaffected by @code{kill-all-local-variables}. - -The value is normally a list of the form @code{(@var{filenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among -all files accessible on the system. See the function -@code{file-attributes}, in @ref{File Attributes}, for more information -about them. - -If @code{buffer-file-name} is the name of a symbolic link, then both -numbers refer to the recursive target. -@end defvar - -@defun get-file-buffer filename -This function returns the buffer visiting file @var{filename}. If -there is no such buffer, it returns @code{nil}. The argument -@var{filename}, which must be a string, is expanded (@pxref{File Name -Expansion}), then compared against the visited file names of all live -buffers. Note that the buffer's @code{buffer-file-name} must match -the expansion of @var{filename} exactly. This function will not -recognize other names for the same file. - -@example -@group -(get-file-buffer "buffers.texi") - @result{} # -@end group -@end example - -In unusual circumstances, there can be more than one buffer visiting -the same file name. In such cases, this function returns the first -such buffer in the buffer list. -@end defun - -@defun find-buffer-visiting filename &optional predicate -This is like @code{get-file-buffer}, except that it can return any -buffer visiting the file @emph{possibly under a different name}. That -is, the buffer's @code{buffer-file-name} does not need to match the -expansion of @var{filename} exactly, it only needs to refer to the -same file. If @var{predicate} is non-@code{nil}, it should be a -function of one argument, a buffer visiting @var{filename}. The -buffer is only considered a suitable return value if @var{predicate} -returns non-@code{nil}. If it can not find a suitable buffer to -return, @code{find-buffer-visiting} returns @code{nil}. -@end defun - -@deffn Command set-visited-file-name filename &optional no-query along-with-file -If @var{filename} is a non-empty string, this function changes the -name of the file visited in the current buffer to @var{filename}. (If the -buffer had no visited file, this gives it one.) The @emph{next time} -the buffer is saved it will go in the newly-specified file. - -This command marks the buffer as modified, since it does not (as far -as Emacs knows) match the contents of @var{filename}, even if it -matched the former visited file. It also renames the buffer to -correspond to the new file name, unless the new name is already in -use. - -If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file.'' In this case, @code{set-visited-file-name} marks -the buffer as having no visited file, without changing the buffer's -modified flag. - -Normally, this function asks the user for confirmation if there -already is a buffer visiting @var{filename}. If @var{no-query} is -non-@code{nil}, that prevents asking this question. If there already -is a buffer visiting @var{filename}, and the user confirms or -@var{query} is non-@code{nil}, this function makes the new buffer name -unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. - -If @var{along-with-file} is non-@code{nil}, that means to assume that -the former visited file has been renamed to @var{filename}. In this -case, the command does not change the buffer's modified flag, nor the -buffer's recorded last file modification time as reported by -@code{visited-file-modtime} (@pxref{Modification Time}). If -@var{along-with-file} is @code{nil}, this function clears the recorded -last file modification time, after which @code{visited-file-modtime} -returns zero. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -When the function @code{set-visited-file-name} is called interactively, it -prompts for @var{filename} in the minibuffer. -@end deffn - -@defvar list-buffers-directory -This buffer-local variable specifies a string to display in a buffer -listing where the visited file name would go, for buffers that don't -have a visited file name. Dired buffers use this variable. -@end defvar - -@node Buffer Modification -@section Buffer Modification -@cindex buffer modification -@cindex modification flag (of buffer) - - Emacs keeps a flag called the @dfn{modified flag} for each buffer, to -record whether you have changed the text of the buffer. This flag is -set to @code{t} whenever you alter the contents of the buffer, and -cleared to @code{nil} when you save it. Thus, the flag shows whether -there are unsaved changes. The flag value is normally shown in the mode -line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving -Buffers}) and auto-saving (@pxref{Auto-Saving}). - - Some Lisp programs set the flag explicitly. For example, the function -@code{set-visited-file-name} sets the flag to @code{t}, because the text -does not match the newly-visited file, even if it is unchanged from the -file formerly visited. - - The functions that modify the contents of buffers are described in -@ref{Text}. - -@defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. -@end defun - -@defun set-buffer-modified-p flag -This function marks the current buffer as modified if @var{flag} is -non-@code{nil}, or as unmodified if the flag is @code{nil}. - -Another effect of calling this function is to cause unconditional -redisplay of the mode line for the current buffer. In fact, the -function @code{force-mode-line-update} works by doing this: - -@example -@group -(set-buffer-modified-p (buffer-modified-p)) -@end group -@end example -@end defun - -@defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. -@end defun - -@deffn Command not-modified &optional arg -This command marks the current buffer as unmodified, and not needing -to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as -modified, so that it will be saved at the next suitable occasion. -Interactively, @var{arg} is the prefix argument. - -Don't use this function in programs, since it prints a message in the -echo area; use @code{set-buffer-modified-p} (above) instead. -@end deffn - -@defun buffer-modified-tick &optional buffer -This function returns @var{buffer}'s modification-count. This is a -counter that increments every time the buffer is modified. If -@var{buffer} is @code{nil} (or omitted), the current buffer is used. -The counter can wrap around occasionally. -@end defun - -@defun buffer-chars-modified-tick &optional buffer -This function returns @var{buffer}'s character-change modification-count. -Changes to text properties leave this counter unchanged; however, each -time text is inserted or removed from the buffer, the counter is reset -to the value that would be returned by @code{buffer-modified-tick}. -By comparing the values returned by two @code{buffer-chars-modified-tick} -calls, you can tell whether a character change occurred in that buffer -in between the calls. If @var{buffer} is @code{nil} (or omitted), the -current buffer is used. -@end defun - -@node Modification Time -@comment node-name, next, previous, up -@section Buffer Modification Time -@cindex comparing file modification time -@cindex modification time of buffer - - Suppose that you visit a file and make changes in its buffer, and -meanwhile the file itself is changed on disk. At this point, saving the -buffer would overwrite the changes in the file. Occasionally this may -be what you want, but usually it would lose valuable information. Emacs -therefore checks the file's modification time using the functions -described below before saving the file. (@xref{File Attributes}, -for how to examine a file's modification time.) - -@defun verify-visited-file-modtime buffer -This function compares what @var{buffer} has recorded for the -modification time of its visited file against the actual modification -time of the file as recorded by the operating system. The two should be -the same unless some other process has written the file since Emacs -visited or saved it. - -The function returns @code{t} if the last actual modification time and -Emacs's recorded modification time are the same, @code{nil} otherwise. -It also returns @code{t} if the buffer has no recorded last -modification time, that is if @code{visited-file-modtime} would return -zero. - -It always returns @code{t} for buffers that are not visiting a file, -even if @code{visited-file-modtime} returns a non-zero value. For -instance, it always returns @code{t} for dired buffers. It returns -@code{t} for buffers that are visiting a file that does not exist and -never existed, but @code{nil} for file-visiting buffers whose file has -been deleted. -@end defun - -@defun clear-visited-file-modtime -This function clears out the record of the last modification time of -the file being visited by the current buffer. As a result, the next -attempt to save this buffer will not complain of a discrepancy in -file modification times. - -This function is called in @code{set-visited-file-name} and other -exceptional places where the usual test to avoid overwriting a changed -file should not be done. -@end defun - -@c Emacs 19 feature -@defun visited-file-modtime -This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low})}. -(This is the same format that @code{file-attributes} uses to return -time values; see @ref{File Attributes}.) - -If the buffer has no recorded last modification time, this function -returns zero. This case occurs, for instance, if the buffer is not -visiting a file or if the time has been explicitly cleared by -@code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers -too. For instance, in a Dired buffer listing a directory, it returns -the last modification time of that directory, as recorded by Dired. - -For a new buffer visiting a not yet existing file, @var{high} is -@minus{}1 and @var{low} is 65535, that is, -@ifnottex -@w{2**16 - 1.} -@end ifnottex -@tex -@math{2^{16}-1}. -@end tex -@end defun - -@c Emacs 19 feature -@defun set-visited-file-modtime &optional time -This function updates the buffer's record of the last modification time -of the visited file, to the value specified by @var{time} if @var{time} -is not @code{nil}, and otherwise to the last modification time of the -visited file. - -If @var{time} is neither @code{nil} nor zero, it should have the form -@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in -either case containing two integers, each of which holds 16 bits of the -time. - -This function is useful if the buffer was not read from the file -normally, or if the file itself has been changed for some known benign -reason. -@end defun - -@defun ask-user-about-supersession-threat filename -This function is used to ask a user how to proceed after an attempt to -modify an buffer visiting file @var{filename} when the file is newer -than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. - -@kindex file-supersession -Depending on the user's answer, the function may return normally, in -which case the modification of the buffer proceeds, or it may signal a -@code{file-supersession} error with data @code{(@var{filename})}, in which -case the proposed buffer modification is not allowed. - -This function is called automatically by Emacs on the proper -occasions. It exists so you can customize Emacs by redefining it. -See the file @file{userlock.el} for the standard definition. - -See also the file locking mechanism in @ref{File Locks}. -@end defun - -@node Read Only Buffers -@section Read-Only Buffers -@cindex read-only buffer -@cindex buffer, read-only - - If a buffer is @dfn{read-only}, then you cannot change its contents, -although you may change your view of the contents by scrolling and -narrowing. - - Read-only buffers are used in two kinds of situations: - -@itemize @bullet -@item -A buffer visiting a write-protected file is normally read-only. - -Here, the purpose is to inform the user that editing the buffer with the -aim of saving it in the file may be futile or undesirable. The user who -wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-x C-q}. - -@item -Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands would probably be a mistake. - -The special commands of these modes bind @code{buffer-read-only} to -@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to -@code{t} around the places where they themselves change the text. -@end itemize - -@defvar buffer-read-only -This buffer-local variable specifies whether the buffer is read-only. -The buffer is read-only if this variable is non-@code{nil}. -@end defvar - -@defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and, -depending on the actual value, some or all read-only characters may be -modified. Read-only characters in a buffer are those that have -non-@code{nil} @code{read-only} properties (either text properties or -overlay properties). @xref{Special Properties}, for more information -about text properties. @xref{Overlays}, for more information about -overlays and their properties. - -If @code{inhibit-read-only} is @code{t}, all @code{read-only} character -properties have no effect. If @code{inhibit-read-only} is a list, then -@code{read-only} character properties have no effect if they are members -of the list (comparison is done with @code{eq}). -@end defvar - -@deffn Command toggle-read-only &optional arg -This command toggles whether the current buffer is read-only. It is -intended for interactive use; do not use it in programs. At any given -point in a program, you should know whether you want the read-only flag -on or off; so you can set @code{buffer-read-only} explicitly to the -proper value, @code{t} or @code{nil}. - -If @var{arg} is non-@code{nil}, it should be a raw prefix argument. -@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if -the numeric value of that prefix argument is positive and to -@code{nil} otherwise. @xref{Prefix Command Arguments}. -@end deffn - -@defun barf-if-buffer-read-only -This function signals a @code{buffer-read-only} error if the current -buffer is read-only. @xref{Using Interactive}, for another way to -signal an error if the current buffer is read-only. -@end defun - -@node The Buffer List -@section The Buffer List -@cindex buffer list - - The @dfn{buffer list} is a list of all live buffers. The order of the -buffers in this list is based primarily on how recently each buffer has -been displayed in a window. Several functions, notably -@code{other-buffer}, use this ordering. A buffer list displayed for the -user also follows this order. - - Creating a buffer adds it to the end of the buffer list, and killing a -buffer removes it from that list. A buffer moves to the front of this -list whenever it is chosen for display in a window (@pxref{Displaying -Buffers}) or a window displaying it is selected (@pxref{Selecting -Windows}). A buffer moves to the end of the list when it is buried (see -@code{bury-buffer}, below). There are no functions available to the -Lisp programmer which directly manipulate the buffer list. - - In addition to the fundamental buffer list just described, Emacs -maintains a local buffer list for each frame, in which the buffers that -have been displayed (or had their windows selected) in that frame come -first. (This order is recorded in the frame's @code{buffer-list} frame -parameter; see @ref{Buffer Parameters}.) Buffers never displayed in -that frame come afterward, ordered according to the fundamental buffer -list. - -@defun buffer-list &optional frame -This function returns the buffer list, including all buffers, even those -whose names begin with a space. The elements are actual buffers, not -their names. - -If @var{frame} is a frame, this returns @var{frame}'s local buffer list. -If @var{frame} is @code{nil} or omitted, the fundamental buffer list is -used: the buffers appear in order of most recent display or selection, -regardless of which frames they were displayed on. - -@example -@group -(buffer-list) - @result{} (# - # # - # #) -@end group - -@group -;; @r{Note that the name of the minibuffer} -;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) - @result{} ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") -@end group -@end example -@end defun - - The list returned by @code{buffer-list} is constructed specifically; -it is not an internal Emacs data structure, and modifying it has no -effect on the order of buffers. If you want to change the order of -buffers in the fundamental buffer list, here is an easy way: - -@example -(defun reorder-buffer-list (new-list) - (while new-list - (bury-buffer (car new-list)) - (setq new-list (cdr new-list)))) -@end example - - With this method, you can specify any order for the list, but there is -no danger of losing a buffer or adding something that is not a valid -live buffer. - - To change the order or value of a specific frame's buffer list, set -that frame's @code{buffer-list} parameter with -@code{modify-frame-parameters} (@pxref{Parameter Access}). - -@defun other-buffer &optional buffer visible-ok frame -This function returns the first buffer in the buffer list other than -@var{buffer}. Usually, this is the buffer appearing in the most -recently selected window (in frame @var{frame} or else the selected -frame, @pxref{Input Focus}), aside from @var{buffer}. Buffers whose -names start with a space are not considered at all. - -If @var{buffer} is not supplied (or if it is not a live buffer), then -@code{other-buffer} returns the first buffer in the selected frame's -local buffer list. (If @var{frame} is non-@code{nil}, it returns the -first buffer in @var{frame}'s local buffer list instead.) - -If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, -then @code{other-buffer} uses that predicate to decide which buffers to -consider. It calls the predicate once for each buffer, and if the value -is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. - -@c Emacs 19 feature -If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning -a buffer visible in any window on any visible frame, except as a last -resort. If @var{visible-ok} is non-@code{nil}, then it does not matter -whether a buffer is displayed somewhere or not. - -If no suitable buffer exists, the buffer @samp{*scratch*} is returned -(and created, if necessary). -@end defun - -@defun last-buffer &optional buffer visible-ok frame -This function returns the last buffer in @var{frame}'s buffer list other -than @var{BUFFER}. If @var{frame} is omitted or @code{nil}, it uses the -selected frame's buffer list. - -The argument @var{visible-ok} is handled as with @code{other-buffer}, -see above. If no suitable buffer can be found, the buffer -@samp{*scratch*} is returned. -@end defun - -@deffn Command bury-buffer &optional buffer-or-name -This command puts @var{buffer-or-name} at the end of the buffer list, -without changing the order of any of the other buffers on the list. -This buffer therefore becomes the least desirable candidate for -@code{other-buffer} to return. The argument can be either a buffer -itself or the name of one. - -@code{bury-buffer} operates on each frame's @code{buffer-list} parameter -as well as the fundamental buffer list; therefore, the buffer that you -bury will come last in the value of @code{(buffer-list @var{frame})} and -in the value of @code{(buffer-list)}. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the -current buffer. In addition, if the buffer is displayed in the selected -window, this switches to some other buffer (obtained using -@code{other-buffer}) in the selected window. @xref{Displaying Buffers}. -But if the selected window is dedicated to its buffer, it deletes that -window if there are other windows left on its frame. Otherwise, if the -selected window is the only window on its frame, it iconifies that -frame. If @var{buffer-or-name} is displayed in some other window, it -remains displayed there. - -To replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. -@end deffn - -@deffn Command unbury-buffer -This command switches to the last buffer in the local buffer list of the -selected frame. More precisely, it calls the function -@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the -buffer returned by @code{last-buffer}, see above, in the selected -window. -@end deffn - - -@node Creating Buffers -@section Creating Buffers -@cindex creating buffers -@cindex buffers, creating - - This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and -@code{create-file-buffer} (@pxref{Visiting Files}). Starting a -subprocess can also create a buffer (@pxref{Processes}). - -@defun get-buffer-create buffer-or-name -This function returns a buffer named @var{buffer-or-name}. The buffer -returned does not become the current buffer---this function does not -change which buffer is current. - -@var{buffer-or-name} must be either a string or an existing buffer. If -it is a string and a live buffer with that name already exists, -@code{get-buffer-create} returns that buffer. If no such buffer exists, -it creates a new buffer. If @var{buffer-or-name} is a buffer instead of -a string, it is returned as given, even if it is dead. - -@example -@group -(get-buffer-create "foo") - @result{} # -@end group -@end example - -The major mode for a newly created buffer is set to Fundamental mode. -(The variable @code{default-major-mode} is handled at a higher level; -see @ref{Auto Major Mode}.) If the name begins with a space, the -buffer initially disables undo information recording (@pxref{Undo}). -@end defun - -@defun generate-new-buffer name -This function returns a newly created, empty buffer, but does not make -it current. If there is no buffer named @var{name}, then that is the -name of the new buffer. If that name is in use, this function adds -suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an -integer. It tries successive integers starting with 2 until it finds an -available name. - -An error is signaled if @var{name} is not a string. - -@example -@group -(generate-new-buffer "bar") - @result{} # -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@group -(generate-new-buffer "bar") - @result{} #> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The -variable @code{default-major-mode} is handled at a higher level. -@xref{Auto Major Mode}. - -See the related function @code{generate-new-buffer-name} in @ref{Buffer -Names}. -@end defun - -@node Killing Buffers -@section Killing Buffers -@cindex killing buffers -@cindex buffers, killing - - @dfn{Killing a buffer} makes its name unknown to Emacs and makes the -memory space it occupied available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; if you kill two distinct buffers, they remain -distinct according to @code{eq} although both are dead. - - If you kill a buffer that is current or displayed in a window, Emacs -automatically selects or displays some other buffer instead. This means -that killing a buffer can in general change the current buffer. -Therefore, when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). @xref{Current Buffer}. - - If you kill a buffer that is the base buffer of one or more indirect -buffers, the indirect buffers are automatically killed as well. - - The @code{buffer-name} of a killed buffer is @code{nil}. You can use -this feature to test whether a buffer has been killed: - -@example -@group -(defun buffer-killed-p (buffer) - "Return t if BUFFER is killed." - (not (buffer-name buffer))) -@end group -@end example - -@deffn Command kill-buffer &optional buffer-or-name -This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. If -@var{buffer-or-name} is @code{nil} or omitted, it kills the current -buffer. - -Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} signal, which normally causes them to terminate. -(The basic meaning of @code{SIGHUP} is that a dialup line has been -disconnected.) @xref{Signals to Processes}. - -If the buffer is visiting a file and contains unsaved changes, -@code{kill-buffer} asks the user to confirm before the buffer is killed. -It does this even if not called interactively. To prevent the request -for confirmation, clear the modified flag before calling -@code{kill-buffer}. @xref{Buffer Modification}. - -This function calls @code{replace-buffer-in-windows} for cleaning up -all windows currently displaying the buffer to be killed. - -Killing a buffer that is already dead has no effect. - -This function returns @code{t} if it actually killed the buffer. It -returns @code{nil} if the user refuses to confirm or if -@var{buffer-or-name} was already dead. - -@smallexample -(kill-buffer "foo.unchanged") - @result{} t -(kill-buffer "foo.changed") - ----------- Buffer: Minibuffer ---------- -Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ----------- Buffer: Minibuffer ---------- - - @result{} t -@end smallexample -@end deffn - -@defvar kill-buffer-query-functions -After confirming unsaved changes, @code{kill-buffer} calls the functions -in the list @code{kill-buffer-query-functions}, in order of appearance, -with no arguments. The buffer being killed is the current buffer when -they are called. The idea of this feature is that these functions will -ask for confirmation from the user. If any of them returns @code{nil}, -@code{kill-buffer} spares the buffer's life. -@end defvar - -@defvar kill-buffer-hook -This is a normal hook run by @code{kill-buffer} after asking all the -questions it is going to ask, just before actually killing the buffer. -The buffer to be killed is current when the hook functions run. -@xref{Hooks}. This variable is a permanent local, so its local binding -is not cleared by changing major modes. -@end defvar - -@defopt buffer-offer-save -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the -second optional argument to that function is @code{t}) to offer to -save that buffer, just as they offer to save file-visiting buffers. -@xref{Definition of save-some-buffers}. The variable -@code{buffer-offer-save} automatically becomes buffer-local when set -for any reason. @xref{Buffer-Local Variables}. -@end defopt - -@defvar buffer-save-without-query -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to save -this buffer (if it's modified) without asking the user. The variable -automatically becomes buffer-local when set for any reason. -@end defvar - -@defun buffer-live-p object -This function returns @code{t} if @var{object} is a buffer which has -not been killed, @code{nil} otherwise. -@end defun - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffers -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. This includes the text properties as well as the characters -themselves. - - In all other respects, the indirect buffer and its base buffer are -completely separate. They have different names, independent values of -point, independent narrowing, independent markers and overlays (though -inserting or deleting text in either buffer relocates the markers and -overlays for both), independent major modes, and independent -buffer-local variable bindings. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually saves the base -buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer effectively kills the indirect buffer in that it cannot -ever again be the current buffer. - -@deffn Command make-indirect-buffer base-buffer name &optional clone -This creates and returns an indirect buffer named @var{name} whose -base buffer is @var{base-buffer}. The argument @var{base-buffer} may -be a live buffer or the name (a string) of an existing buffer. If -@var{name} is the name of an existing buffer, an error is signaled. - -If @var{clone} is non-@code{nil}, then the indirect buffer originally -shares the ``state'' of @var{base-buffer} such as major mode, minor -modes, buffer local variables and so on. If @var{clone} is omitted -or @code{nil} the indirect buffer's state is set to the default state -for new buffers. - -If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. If, in addition, @var{clone} is -non-@code{nil}, the initial state is copied from the actual base -buffer, not from @var{base-buffer}. -@end deffn - -@deffn clone-indirect-buffer newname display-flag &optional norecord -This function creates and returns a new indirect buffer that shares -the current buffer's base buffer and copies the rest of the current -buffer's attributes. (If the current buffer is not indirect, it is -used as the base buffer.) - -If @var{display-flag} is non-@code{nil}, that means to display the new -buffer by calling @code{pop-to-buffer}. If @var{norecord} is -non-@code{nil}, that means not to put the new buffer to the front of -the buffer list. -@end deffn - -@defun buffer-base-buffer &optional buffer -This function returns the base buffer of @var{buffer}, which defaults -to the current buffer. If @var{buffer} is not indirect, the value is -@code{nil}. Otherwise, the value is another buffer, which is never an -indirect buffer. -@end defun - -@node Swapping Text -@section Swapping Text Between Two Buffers -@cindex swap text between buffers -@cindex virtual buffers - - Specialized modes sometimes need to let the user access from the -same buffer several vastly different types of text. For example, you -may need to display a summary of the buffer text, in addition to -letting the user access the text itself. - - This could be implemented with multiple buffers (kept in sync when -the user edits the text), or with narrowing (@pxref{Narrowing}). But -these alternatives might sometimes become tedious or prohibitively -expensive, especially if each type of text requires expensive -buffer-global operations in order to provide correct display and -editing commands. - - Emacs provides another facility for such modes: you can quickly swap -buffer text between two buffers with @code{buffer-swap-text}. This -function is very fast because it doesn't move any text, it only -changes the internal data structures of the buffer object to point to -a different chunk of text. Using it, you can pretend that a group of -two or more buffers are actually a single virtual buffer that holds -the contents of all the individual buffers together. - -@defun buffer-swap-text buffer -This function swaps text between the current buffer and its argument -@var{buffer}. It signals an error if one of the two buffers is an -indirect buffer (@pxref{Indirect Buffers}) or is a base buffer of an -indirect buffer. - -All the buffer properties that are related to the buffer text are -swapped as well: the positions of point and mark, all the markers, the -overlays, the text properties, the undo list, the value of the -@code{enable-multibyte-characters} flag (@pxref{Text Representations, -enable-multibyte-characters}), etc. -@end defun - -@node Buffer Gap -@section The Buffer Gap - - Emacs buffers are implemented using an invisible @dfn{gap} to make -insertion and deletion faster. Insertion works by filling in part of -the gap, and deletion adds to the gap. Of course, this means that the -gap must first be moved to the locus of the insertion or deletion. -Emacs moves the gap only when you try to insert or delete. This is why -your first editing command in one part of a large buffer, after -previously editing in another far-away part, sometimes involves a -noticeable delay. - - This mechanism works invisibly, and Lisp code should never be affected -by the gap's current location, but these functions are available for -getting information about the gap status. - -@defun gap-position -This function returns the current gap position in the current buffer. -@end defun - -@defun gap-size -This function returns the current gap size of the current buffer. -@end defun - -@ignore - arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c -@end ignore diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi deleted file mode 100644 index 147fdf274a8..00000000000 --- a/doc/lispref/commands.texi +++ /dev/null @@ -1,3362 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/commands -@node Command Loop, Keymaps, Minibuffers, Top -@chapter Command Loop -@cindex editor command loop -@cindex command loop - - When you run Emacs, it enters the @dfn{editor command loop} almost -immediately. This loop reads key sequences, executes their definitions, -and displays the results. In this chapter, we describe how these things -are done, and the subroutines that allow Lisp programs to do them. - -@menu -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. -@end menu - -@node Command Overview -@section Command Loop Overview - - The first thing the command loop must do is read a key sequence, which -is a sequence of events that translates into a command. It does this by -calling the function @code{read-key-sequence}. Your Lisp code can also -call this function (@pxref{Key Sequence Input}). Lisp programs can also -do input at a lower level with @code{read-event} (@pxref{Reading One -Event}) or discard pending input with @code{discard-input} -(@pxref{Event Input Misc}). - - The key sequence is translated into a command through the currently -active keymaps. @xref{Key Lookup}, for information on how this is done. -The result should be a keyboard macro or an interactively callable -function. If the key is @kbd{M-x}, then it reads the name of another -command, which it then calls. This is done by the command -@code{execute-extended-command} (@pxref{Interactive Call}). - - To execute a command requires first reading the arguments for it. -This is done by calling @code{command-execute} (@pxref{Interactive -Call}). For commands written in Lisp, the @code{interactive} -specification says how to read the arguments. This may use the prefix -argument (@pxref{Prefix Command Arguments}) or may read with prompting -in the minibuffer (@pxref{Minibuffers}). For example, the command -@code{find-file} has an @code{interactive} specification which says to -read a file name using the minibuffer. The command's function body does -not use the minibuffer; if you call this command from Lisp code as a -function, you must supply the file name string as an ordinary Lisp -function argument. - - If the command is a string or vector (i.e., a keyboard macro) then -@code{execute-kbd-macro} is used to execute it. You can call this -function yourself (@pxref{Keyboard Macros}). - - To terminate the execution of a running command, type @kbd{C-g}. This -character causes @dfn{quitting} (@pxref{Quitting}). - -@defvar pre-command-hook -The editor command loop runs this normal hook before each command. At -that time, @code{this-command} contains the command that is about to -run, and @code{last-command} describes the previous command. -@xref{Command Loop Info}. -@end defvar - -@defvar post-command-hook -The editor command loop runs this normal hook after each command -(including commands terminated prematurely by quitting or by errors), -and also when the command loop is first entered. At that time, -@code{this-command} refers to the command that just ran, and -@code{last-command} refers to the command before that. -@end defvar - - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}. If an error happens while executing one of -these hooks, it terminates execution of the hook, and clears the hook -variable to @code{nil} so as to prevent an infinite loop of errors. - - A request coming into the Emacs server (@pxref{Emacs Server,,, -emacs, The GNU Emacs Manual}) runs these two hooks just as a keyboard -command does. - -@node Defining Commands -@section Defining Commands -@cindex defining commands -@cindex commands, defining -@cindex functions, making them interactive -@cindex interactive function - - The special form @code{interactive} turns a Lisp function into a -command. The @code{interactive} form must be located at top-level in -the function body (usually as the first form in the body), or in the -@code{interactive-form} property of the function symbol. When the -@code{interactive} form is located in the function body, it does -nothing when actually executed. Its presence serves as a flag, which -tells the Emacs command loop that the function can be called -interactively. The argument of the @code{interactive} form controls -the reading of arguments for an interactive call. - -@menu -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. -@end menu - -@node Using Interactive -@subsection Using @code{interactive} -@cindex arguments, interactive entry - - This section describes how to write the @code{interactive} form that -makes a Lisp function an interactively-callable command, and how to -examine a command's @code{interactive} form. - -@defspec interactive arg-descriptor -This special form declares that a function is a command, and that it -may therefore be called interactively (via @kbd{M-x} or by entering a -key sequence bound to it). The argument @var{arg-descriptor} declares -how to compute the arguments to the command when the command is called -interactively. - -A command may be called from Lisp programs like any other function, but -then the caller supplies the arguments and @var{arg-descriptor} has no -effect. - -@cindex @code{interactive-form}, function property -The @code{interactive} form must be located at top-level in the -function body, or in the function symbol's @code{interactive-form} -property (@pxref{Symbol Plists}). It has its effect because the -command loop looks for it before calling the function -(@pxref{Interactive Call}). Once the function is called, all its body -forms are executed; at this time, if the @code{interactive} form -occurs within the body, the form simply returns @code{nil} without -even evaluating its argument. - -By convention, you should put the @code{interactive} form in the -function body, as the first top-level form. If there is an -@code{interactive} form in both the @code{interactive-form} symbol -property and the function body, the former takes precedence. The -@code{interactive-form} symbol property can be used to add an -interactive form to an existing function, or change how its arguments -are processed interactively, without redefining the function. -@end defspec - -There are three possibilities for the argument @var{arg-descriptor}: - -@itemize @bullet -@item -It may be omitted or @code{nil}; then the command is called with no -arguments. This leads quickly to an error if the command requires one -or more arguments. - -@item -It may be a string; its contents are a sequence of elements separated -by newlines, one for each parameter@footnote{Some elements actually -supply two parameters.}. Each element consists of a code character -(@pxref{Interactive Codes}) optionally followed by a prompt (which -some code characters use and some ignore). Here is an example: - -@smallexample -(interactive "P\nbFrobnicate buffer: ") -@end smallexample - -@noindent -The code letter @samp{P} sets the command's first argument to the raw -command prefix (@pxref{Prefix Command Arguments}). @samp{bFrobnicate -buffer: } prompts the user with @samp{Frobnicate buffer: } to enter -the name of an existing buffer, which becomes the second and final -argument. - -@c Emacs 19 feature -The prompt string can use @samp{%} to include previous argument values -(starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how -you could read the name of an existing buffer followed by a new name to -give to that buffer: - -@smallexample -@group -(interactive "bBuffer to rename: \nsRename buffer %s to: ") -@end group -@end smallexample - -@cindex @samp{*} in @code{interactive} -@cindex read-only buffers in interactive -If @samp{*} appears at the beginning of the string, then an error is -signaled if the buffer is read-only. - -@cindex @samp{@@} in @code{interactive} -@c Emacs 19 feature -If @samp{@@} appears at the beginning of the string, and if the key -sequence used to invoke the command includes any mouse events, then -the window associated with the first of those events is selected -before the command is run. - -@cindex @samp{^} in @code{interactive} -@cindex shift-selection, and @code{interactive} spec -If @samp{^} appears at the beginning of the string, and if the command -was invoked through @dfn{shift-translation}, set the mark and activate -the region temporarily, or extend an already active region, before the -command is run. If the command was invoked without shift-translation, -and the region is temporarily active, deactivate the region before the -command is run. Shift-translation is controlled on the user level by -@code{shift-select-mode}; see @ref{Shift Selection,,, emacs, The GNU -Emacs Manual}. - -You can use @samp{*}, @samp{@@}, and @code{^} together; the order does -not matter. Actual reading of arguments is controlled by the rest of -the prompt string (starting with the first character that is not -@samp{*}, @samp{@@}, or @samp{^}). - -@item -It may be a Lisp expression that is not a string; then it should be a -form that is evaluated to get a list of arguments to pass to the -command. Usually this form will call various functions to read input -from the user, most often through the minibuffer (@pxref{Minibuffers}) -or directly from the keyboard (@pxref{Reading Input}). - -Providing point or the mark as an argument value is also common, but -if you do this @emph{and} read input (whether using the minibuffer or -not), be sure to get the integer values of point or the mark after -reading. The current buffer may be receiving subprocess output; if -subprocess output arrives while the command is waiting for input, it -could relocate point and the mark. - -Here's an example of what @emph{not} to do: - -@smallexample -(interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) -@end smallexample - -@noindent -Here's how to avoid the problem, by examining point and the mark after -reading the keyboard input: - -@smallexample -(interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) -@end smallexample - -@strong{Warning:} the argument values should not include any data -types that can't be printed and then read. Some facilities save -@code{command-history} in a file to be read in the subsequent -sessions; if a command's arguments contain a data type that prints -using @samp{#<@dots{}>} syntax, those facilities won't work. - -There are, however, a few exceptions: it is ok to use a limited set of -expressions such as @code{(point)}, @code{(mark)}, -@code{(region-beginning)}, and @code{(region-end)}, because Emacs -recognizes them specially and puts the expression (rather than its -value) into the command history. To see whether the expression you -wrote is one of these exceptions, run the command, then examine -@code{(car command-history)}. -@end itemize - -@cindex examining the @code{interactive} form -@defun interactive-form function -This function returns the @code{interactive} form of @var{function}. -If @var{function} is an interactively callable function -(@pxref{Interactive Call}), the value is the command's -@code{interactive} form @code{(interactive @var{spec})}, which -specifies how to compute its arguments. Otherwise, the value is -@code{nil}. If @var{function} is a symbol, its function definition is -used. -@end defun - -@node Interactive Codes -@comment node-name, next, previous, up -@subsection Code Characters for @code{interactive} -@cindex interactive code description -@cindex description for interactive codes -@cindex codes, interactive, description of -@cindex characters for interactive codes - - The code character descriptions below contain a number of key words, -defined here as follows: - -@table @b -@item Completion -@cindex interactive completion -Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name -completion because the argument is read using @code{completing-read} -(@pxref{Completion}). @kbd{?} displays a list of possible completions. - -@item Existing -Require the name of an existing object. An invalid name is not -accepted; the commands to exit the minibuffer do not exit if the current -input is not valid. - -@item Default -@cindex default argument string -A default value of some sort is used if the user enters no text in the -minibuffer. The default depends on the code character. - -@item No I/O -This code letter computes an argument without reading any input. -Therefore, it does not use a prompt string, and any prompt string you -supply is ignored. - -Even though the code letter doesn't use a prompt string, you must follow -it with a newline if it is not the last code character in the string. - -@item Prompt -A prompt immediately follows the code character. The prompt ends either -with the end of the string or with a newline. - -@item Special -This code character is meaningful only at the beginning of the -interactive string, and it does not look for a prompt or a newline. -It is a single, isolated character. -@end table - -@cindex reading interactive arguments - Here are the code character descriptions for use with @code{interactive}: - -@table @samp -@item * -Signal an error if the current buffer is read-only. Special. - -@item @@ -Select the window mentioned in the first mouse event in the key -sequence that invoked this command. Special. - -@item ^ -If the command was invoked through shift-translation, set the mark and -activate the region temporarily, or extend an already active region, -before the command is run. If the command was invoked without -shift-translation, and the region is temporarily active, deactivate -the region before the command is run. Special. - -@item a -A function name (i.e., a symbol satisfying @code{fboundp}). Existing, -Completion, Prompt. - -@item b -The name of an existing buffer. By default, uses the name of the -current buffer (@pxref{Buffers}). Existing, Completion, Default, -Prompt. - -@item B -A buffer name. The buffer need not exist. By default, uses the name of -a recently used buffer other than the current buffer. Completion, -Default, Prompt. - -@item c -A character. The cursor does not move into the echo area. Prompt. - -@item C -A command name (i.e., a symbol satisfying @code{commandp}). Existing, -Completion, Prompt. - -@item d -@cindex position argument -The position of point, as an integer (@pxref{Point}). No I/O. - -@item D -A directory name. The default is the current default directory of the -current buffer, @code{default-directory} (@pxref{File Name Expansion}). -Existing, Completion, Default, Prompt. - -@item e -The first or next mouse event in the key sequence that invoked the command. -More precisely, @samp{e} gets events that are lists, so you can look at -the data in the lists. @xref{Input Events}. No I/O. - -You can use @samp{e} more than once in a single command's interactive -specification. If the key sequence that invoked the command has -@var{n} events that are lists, the @var{n}th @samp{e} provides the -@var{n}th such event. Events that are not lists, such as function keys -and @acronym{ASCII} characters, do not count where @samp{e} is concerned. - -@item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. - -@item F -A file name. The file need not exist. Completion, Default, Prompt. - -@item G -A file name. The file need not exist. If the user enters just a -directory name, then the value is just that directory name, with no -file name within the directory added. Completion, Default, Prompt. - -@item i -An irrelevant argument. This code always supplies @code{nil} as -the argument's value. No I/O. - -@item k -A key sequence (@pxref{Key Sequences}). This keeps reading events -until a command (or undefined command) is found in the current key -maps. The key sequence argument is represented as a string or vector. -The cursor does not move into the echo area. Prompt. - -If @samp{k} reads a key sequence that ends with a down-event, it also -reads and discards the following up-event. You can get access to that -up-event with the @samp{U} code character. - -This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. - -@item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. - -@item m -@cindex marker argument -The position of the mark, as an integer. No I/O. - -@item M -Arbitrary text, read in the minibuffer using the current buffer's input -method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU -Emacs Manual}). Prompt. - -@item n -A number, read with the minibuffer. If the input is not a number, the -user has to try again. @samp{n} never uses the prefix argument. -Prompt. - -@item N -The numeric prefix argument; but if there is no prefix argument, read -a number as with @kbd{n}. The value is always a number. @xref{Prefix -Command Arguments}. Prompt. - -@item p -@cindex numeric prefix argument usage -The numeric prefix argument. (Note that this @samp{p} is lower case.) -No I/O. - -@item P -@cindex raw prefix argument usage -The raw prefix argument. (Note that this @samp{P} is upper case.) No -I/O. - -@item r -@cindex region argument -Point and the mark, as two numeric arguments, smallest first. This is -the only code letter that specifies two successive arguments rather than -one. No I/O. - -@item s -Arbitrary text, read in the minibuffer and returned as a string -(@pxref{Text from Minibuffer}). Terminate the input with either -@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of -these characters in the input.) Prompt. - -@item S -An interned symbol whose name is read in the minibuffer. Any whitespace -character terminates the input. (Use @kbd{C-q} to include whitespace in -the string.) Other characters that normally terminate a symbol (e.g., -parentheses and brackets) do not do so here. Prompt. - -@item U -A key sequence or @code{nil}. Can be used after a @samp{k} or -@samp{K} argument to get the up-event that was discarded (if any) -after @samp{k} or @samp{K} read a down-event. If no up-event has been -discarded, @samp{U} provides @code{nil} as the argument. No I/O. - -@item v -A variable declared to be a user option (i.e., satisfying the -predicate @code{user-variable-p}). This reads the variable using -@code{read-variable}. @xref{Definition of read-variable}. Existing, -Completion, Prompt. - -@item x -A Lisp object, specified with its read syntax, terminated with a -@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from -Minibuffer}. Prompt. - -@item X -@cindex evaluated expression argument -A Lisp form's value. @samp{X} reads as @samp{x} does, then evaluates -the form so that its value becomes the argument for the command. -Prompt. - -@item z -A coding system name (a symbol). If the user enters null input, the -argument value is @code{nil}. @xref{Coding Systems}. Completion, -Existing, Prompt. - -@item Z -A coding system name (a symbol)---but only if this command has a prefix -argument. With no prefix argument, @samp{Z} provides @code{nil} as the -argument value. Completion, Existing, Prompt. -@end table - -@node Interactive Examples -@comment node-name, next, previous, up -@subsection Examples of Using @code{interactive} -@cindex examples of using @code{interactive} -@cindex @code{interactive}, examples of using - - Here are some examples of @code{interactive}: - -@example -@group -(defun foo1 () ; @r{@code{foo1} takes no arguments,} - (interactive) ; @r{just moves forward two words.} - (forward-word 2)) - @result{} foo1 -@end group - -@group -(defun foo2 (n) ; @r{@code{foo2} takes one argument,} - (interactive "^p") ; @r{which is the numeric prefix.} - ; @r{under @code{shift-select-mode},} - ; @r{will activate or extend region.} - (forward-word (* 2 n))) - @result{} foo2 -@end group - -@group -(defun foo3 (n) ; @r{@code{foo3} takes one argument,} - (interactive "nCount:") ; @r{which is read with the Minibuffer.} - (forward-word (* 2 n))) - @result{} foo3 -@end group - -@group -(defun three-b (b1 b2 b3) - "Select three existing buffers. -Put them into three windows, selecting the last one." -@end group - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - @result{} three-b -@group -(three-b "*scratch*" "declarations.texi" "*mail*") - @result{} nil -@end group -@end example - -@node Interactive Call -@section Interactive Call -@cindex interactive call - - After the command loop has translated a key sequence into a command, -it invokes that command using the function @code{command-execute}. If -the command is a function, @code{command-execute} calls -@code{call-interactively}, which reads the arguments and calls the -command. You can also call these functions yourself. - -@defun commandp object &optional for-call-interactively -Returns @code{t} if @var{object} is suitable for calling interactively; -that is, if @var{object} is a command. Otherwise, returns @code{nil}. - -Interactively-callable objects include strings and vectors (which are -treated as keyboard macros), lambda expressions that contain a -top-level @code{interactive} form (@pxref{Using Interactive}), -byte-code function objects made from such lambda expressions, autoload -objects that are declared as interactive (non-@code{nil} fourth -argument to @code{autoload}), and some primitive functions. - -A symbol satisfies @code{commandp} if it has a non-@code{nil} -@code{interactive-form} property, or if its function definition -satisfies @code{commandp}. Keys and keymaps are not commands. -Rather, they are used to look up commands (@pxref{Keymaps}). - -If @var{for-call-interactively} is non-@code{nil}, then -@code{commandp} returns @code{t} only for objects that -@code{call-interactively} could call---thus, not for keyboard macros. - -See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example of using @code{commandp}. -@end defun - -@defun call-interactively command &optional record-flag keys -This function calls the interactively callable function @var{command}, -reading arguments according to its interactive calling specifications. -It returns whatever @var{command} returns. An error is signaled if -@var{command} is not a function or if it cannot be called -interactively (i.e., is not a command). Note that keyboard macros -(strings and vectors) are not accepted, even though they are -considered commands, because they are not functions. If @var{command} -is a symbol, then @code{call-interactively} uses its function definition. - -@cindex record command history -If @var{record-flag} is non-@code{nil}, then this command and its -arguments are unconditionally added to the list @code{command-history}. -Otherwise, the command is added only if it uses the minibuffer to read -an argument. @xref{Command History}. - -The argument @var{keys}, if given, should be a vector which specifies -the sequence of events to supply if the command inquires which events -were used to invoke it. If @var{keys} is omitted or @code{nil}, the -default is the return value of @code{this-command-keys-vector}. -@xref{Definition of this-command-keys-vector}. -@end defun - -@defun command-execute command &optional record-flag keys special -@cindex keyboard macro execution -This function executes @var{command}. The argument @var{command} must -satisfy the @code{commandp} predicate; i.e., it must be an interactively -callable function or a keyboard macro. - -A string or vector as @var{command} is executed with -@code{execute-kbd-macro}. A function is passed to -@code{call-interactively}, along with the optional @var{record-flag} -and @var{keys}. - -A symbol is handled by using its function definition in its place. A -symbol with an @code{autoload} definition counts as a command if it was -declared to stand for an interactively callable function. Such a -definition is handled by loading the specified library and then -rechecking the definition of the symbol. - -The argument @var{special}, if given, means to ignore the prefix -argument and not clear it. This is used for executing special events -(@pxref{Special Events}). -@end defun - -@deffn Command execute-extended-command prefix-argument -@cindex read command name -This function reads a command name from the minibuffer using -@code{completing-read} (@pxref{Completion}). Then it uses -@code{command-execute} to call the specified command. Whatever that -command returns becomes the value of @code{execute-extended-command}. - -@cindex execute with prefix argument -If the command asks for a prefix argument, it receives the value -@var{prefix-argument}. If @code{execute-extended-command} is called -interactively, the current raw prefix argument is used for -@var{prefix-argument}, and thus passed on to whatever command is run. - -@c !!! Should this be @kindex? -@cindex @kbd{M-x} -@code{execute-extended-command} is the normal definition of @kbd{M-x}, -so it uses the string @w{@samp{M-x }} as a prompt. (It would be better -to take the prompt from the events used to invoke -@code{execute-extended-command}, but that is painful to implement.) A -description of the value of the prefix argument, if any, also becomes -part of the prompt. - -@example -@group -(execute-extended-command 3) ----------- Buffer: Minibuffer ---------- -3 M-x forward-word RET ----------- Buffer: Minibuffer ---------- - @result{} t -@end group -@end example -@end deffn - -@node Distinguish Interactive -@section Distinguish Interactive Calls - - Sometimes a command should display additional visual feedback (such -as an informative message in the echo area) for interactive calls -only. There are three ways to do this. The recommended way to test -whether the function was called using @code{call-interactively} is to -give it an optional argument @code{print-message} and use the -@code{interactive} spec to make it non-@code{nil} in interactive -calls. Here's an example: - -@example -(defun foo (&optional print-message) - (interactive "p") - (when print-message - (message "foo"))) -@end example - -@noindent -We use @code{"p"} because the numeric prefix argument is never -@code{nil}. Defined in this way, the function does display the -message when called from a keyboard macro. - - The above method with the additional argument is usually best, -because it allows callers to say ``treat this call as interactive.'' -But you can also do the job in a simpler way by testing -@code{called-interactively-p}. - -@defun called-interactively-p -This function returns @code{t} when the calling function was called -using @code{call-interactively}. - -If the containing function was called by Lisp evaluation (or with -@code{apply} or @code{funcall}), then it was not called interactively. -@end defun - - Here's an example of using @code{called-interactively-p}: - -@example -@group -(defun foo () - (interactive) - (when (called-interactively-p) - (message "foo")) - 'haha) - @result{} foo -@end group - -@group -;; @r{Type @kbd{M-x foo}.} - @print{} foo -@end group - -@group -(foo) - @result{} haha -@end group -@end example - - Here is another example that contrasts direct and indirect -calls to @code{called-interactively-p}. - -@example -@group -(defun bar () - (interactive) - (setq foobar (list (foo) (called-interactively-p)))) - @result{} bar -@end group - -@group -;; @r{Type @kbd{M-x bar}.} -;; @r{This does not display a message.} -@end group - -@group -foobar - @result{} (nil t) -@end group -@end example - - If you want to treat commands run in keyboard macros just like calls -from Lisp programs, test @code{interactive-p} instead of -@code{called-interactively-p}. - -@defun interactive-p -This function returns @code{t} if the containing function (the one -whose code includes the call to @code{interactive-p}) was called in -direct response to user input. This means that it was called with the -function @code{call-interactively}, and that a keyboard macro is -not running, and that Emacs is not running in batch mode. -@end defun - -@node Command Loop Info -@comment node-name, next, previous, up -@section Information from the Command Loop - -The editor command loop sets several Lisp variables to keep status -records for itself and for commands that are run. With the exception of -@code{this-command} and @code{last-command} it's generally a bad idea to -change any of these variables in a Lisp program. - -@defvar last-command -This variable records the name of the previous command executed by the -command loop (the one before the current command). Normally the value -is a symbol with a function definition, but this is not guaranteed. - -The value is copied from @code{this-command} when a command returns to -the command loop, except when the command has specified a prefix -argument for the following command. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar real-last-command -This variable is set up by Emacs just like @code{last-command}, -but never altered by Lisp programs. -@end defvar - -@defvar last-repeatable-command -This variable stores the most recently executed command that was not -part of an input event. This is the command @code{repeat} will try to -repeat, @xref{Repeating,,, emacs, The GNU Emacs Manual}. -@end defvar - -@defvar this-command -@cindex current command -This variable records the name of the command now being executed by -the editor command loop. Like @code{last-command}, it is normally a symbol -with a function definition. - -The command loop sets this variable just before running a command, and -copies its value into @code{last-command} when the command finishes -(unless the command specified a prefix argument for the following -command). - -@cindex kill command repetition -Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions for killing text -set @code{this-command} to @code{kill-region} so that any kill commands -immediately following will know to append the killed text to the -previous kill. -@end defvar - -If you do not want a particular command to be recognized as the previous -command in the case where it got an error, you must code that command to -prevent this. One way is to set @code{this-command} to @code{t} at the -beginning of the command, and set @code{this-command} back to its proper -value at the end, like this: - -@example -(defun foo (args@dots{}) - (interactive @dots{}) - (let ((old-this-command this-command)) - (setq this-command t) - @r{@dots{}do the work@dots{}} - (setq this-command old-this-command))) -@end example - -@noindent -We do not bind @code{this-command} with @code{let} because that would -restore the old value in case of error---a feature of @code{let} which -in this case does precisely what we want to avoid. - -@defvar this-original-command -This has the same value as @code{this-command} except when command -remapping occurs (@pxref{Remapping Commands}). In that case, -@code{this-command} gives the command actually run (the result of -remapping), and @code{this-original-command} gives the command that -was specified to run but remapped into another command. -@end defvar - -@defun this-command-keys -This function returns a string or vector containing the key sequence -that invoked the present command, plus any previous commands that -generated the prefix argument for this command. Any events read by the -command using @code{read-event} without a timeout get tacked on to the end. - -However, if the command has called @code{read-key-sequence}, it -returns the last read key sequence. @xref{Key Sequence Input}. The -value is a string if all events in the sequence were characters that -fit in a string. @xref{Input Events}. - -@example -@group -(this-command-keys) -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} "^U^X^E" -@end group -@end example -@end defun - -@defun this-command-keys-vector -@anchor{Definition of this-command-keys-vector} -Like @code{this-command-keys}, except that it always returns the events -in a vector, so you don't need to deal with the complexities of storing -input events in a string (@pxref{Strings of Events}). -@end defun - -@defun clear-this-command-keys &optional keep-record -This function empties out the table of events for -@code{this-command-keys} to return. Unless @var{keep-record} is -non-@code{nil}, it also empties the records that the function -@code{recent-keys} (@pxref{Recording Input}) will subsequently return. -This is useful after reading a password, to prevent the password from -echoing inadvertently as part of the next command in certain cases. -@end defun - -@defvar last-nonmenu-event -This variable holds the last input event read as part of a key sequence, -not counting events resulting from mouse menus. - -One use of this variable is for telling @code{x-popup-menu} where to pop -up a menu. It is also used internally by @code{y-or-n-p} -(@pxref{Yes-or-No Queries}). -@end defvar - -@defvar last-command-event -@defvarx last-command-char -This variable is set to the last input event that was read by the -command loop as part of a command. The principal use of this variable -is in @code{self-insert-command}, which uses it to decide which -character to insert. - -@example -@group -last-command-event -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} 5 -@end group -@end example - -@noindent -The value is 5 because that is the @acronym{ASCII} code for @kbd{C-e}. - -The alias @code{last-command-char} is obsolete. -@end defvar - -@c Emacs 19 feature -@defvar last-event-frame -This variable records which frame the last input event was directed to. -Usually this is the frame that was selected when the event was -generated, but if that frame has redirected input focus to another -frame, the value is the frame to which the event was redirected. -@xref{Input Focus}. - -If the last event came from a keyboard macro, the value is @code{macro}. -@end defvar - -@node Adjusting Point -@section Adjusting Point After Commands -@cindex adjusting point -@cindex invisible/intangible text, and point -@cindex @code{display} property, and point display -@cindex @code{composition} property, and point display - - It is not easy to display a value of point in the middle of a -sequence of text that has the @code{display}, @code{composition} or -@code{intangible} property, or is invisible. Therefore, after a -command finishes and returns to the command loop, if point is within -such a sequence, the command loop normally moves point to the edge of -the sequence. - - A command can inhibit this feature by setting the variable -@code{disable-point-adjustment}: - -@defvar disable-point-adjustment -If this variable is non-@code{nil} when a command returns to the -command loop, then the command loop does not check for those text -properties, and does not move point out of sequences that have them. - -The command loop sets this variable to @code{nil} before each command, -so if a command sets it, the effect applies only to that command. -@end defvar - -@defvar global-disable-point-adjustment -If you set this variable to a non-@code{nil} value, the feature of -moving point out of these sequences is completely turned off. -@end defvar - -@node Input Events -@section Input Events -@cindex events -@cindex input events - -The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity. The events for keyboard activity -are characters or symbols; mouse events are always lists. This section -describes the representation and meaning of input events in detail. - -@defun eventp object -This function returns non-@code{nil} if @var{object} is an input event -or event type. - -Note that any symbol might be used as an event or an event type. -@code{eventp} cannot distinguish whether a symbol is intended by Lisp -code to be used as an event. Instead, it distinguishes whether the -symbol has actually been used in an event that has been read as input in -the current Emacs session. If a symbol has not yet been so used, -@code{eventp} returns @code{nil}. -@end defun - -@menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. -@end menu - -@node Keyboard Events -@subsection Keyboard Events -@cindex keyboard events - -There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. The event -type of a character event is the character itself (an integer); see -@ref{Classifying Events}. - -@cindex modifier bits (of input character) -@cindex basic code (of input character) -An input character event consists of a @dfn{basic code} between 0 and -524287, plus any or all of these @dfn{modifier bits}: - -@table @asis -@item meta -The -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit in the character code indicates a character -typed with the meta key held down. - -@item control -The -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit in the character code indicates a non-@acronym{ASCII} -control character. - -@sc{ascii} control characters such as @kbd{C-a} have special basic -codes of their own, so Emacs needs no special bit to indicate them. -Thus, the code for @kbd{C-a} is just 1. - -But if you type a control combination not in @acronym{ASCII}, such as -@kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -(assuming the terminal supports non-@acronym{ASCII} -control characters). - -@item shift -The -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in the character code indicates an @acronym{ASCII} control -character typed with the shift key held down. - -For letters, the basic code itself indicates upper versus lower case; -for digits and punctuation, the shift key selects an entirely different -character with a different basic code. In order to keep within the -@acronym{ASCII} character set whenever possible, Emacs avoids using the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit for those characters. - -However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit in @kbd{C-A} and not in -@kbd{C-a}. - -@item hyper -The -@tex -@math{2^{24}} -@end tex -@ifnottex -2**24 -@end ifnottex -bit in the character code indicates a character -typed with the hyper key held down. - -@item super -The -@tex -@math{2^{23}} -@end tex -@ifnottex -2**23 -@end ifnottex -bit in the character code indicates a character -typed with the super key held down. - -@item alt -The -@tex -@math{2^{22}} -@end tex -@ifnottex -2**22 -@end ifnottex -bit in the character code indicates a character typed with -the alt key held down. (On some terminals, the key labeled @key{ALT} -is actually the meta key.) -@end table - - It is best to avoid mentioning specific bit numbers in your program. -To test the modifier bits of a character, use the function -@code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). - -@node Function Keys -@subsection Function Keys - -@cindex function keys -Most keyboards also have @dfn{function keys}---keys that have names or -symbols that are not characters. Function keys are represented in Emacs -Lisp as symbols; the symbol's name is the function key's label, in lower -case. For example, pressing a key labeled @key{F1} places the symbol -@code{f1} in the input stream. - -The event type of a function key event is the event symbol itself. -@xref{Classifying Events}. - -Here are a few special cases in the symbol-naming convention for -function keys: - -@table @asis -@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @acronym{ASCII} control characters that have -special keys on most keyboards. - -In @acronym{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the -terminal can distinguish between them, Emacs conveys the distinction to -Lisp programs by representing the former as the integer 9, and the -latter as the symbol @code{tab}. - -Most of the time, it's not useful to distinguish the two. So normally -@code{local-function-key-map} (@pxref{Translation Keymaps}) is set up -to map @code{tab} into 9. Thus, a key binding for character code 9 -(the character @kbd{C-i}) also applies to @code{tab}. Likewise for -the other symbols in this group. The function @code{read-char} -likewise converts these events into characters. - -In @acronym{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} -converts into the character code 127 (@key{DEL}), not into code 8 -(@key{BS}). This is what most users prefer. - -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys -@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} -Keypad keys (to the right of the regular keyboard). -@item @code{kp-0}, @code{kp-1}, @dots{} -Keypad keys with digits. -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} -Keypad arrow keys. Emacs normally translates these into the -corresponding non-keypad keys @code{home}, @code{left}, @dots{} -@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} -Additional keypad duplicates of keys ordinarily found elsewhere. Emacs -normally translates these into the like-named non-keypad keys. -@end table - -You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, -@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to -represent them is with prefixes in the symbol name: - -@table @samp -@item A- -The alt modifier. -@item C- -The control modifier. -@item H- -The hyper modifier. -@item M- -The meta modifier. -@item S- -The shift modifier. -@item s- -The super modifier. -@end table - -Thus, the symbol for the key @key{F3} with @key{META} held down is -@code{M-f3}. When you use more than one prefix, we recommend you -write them in alphabetical order; but the order does not matter in -arguments to the key-binding lookup and modification functions. - -@node Mouse Events -@subsection Mouse Events - -Emacs supports four kinds of mouse events: click events, drag events, -button-down events, and motion events. All mouse events are represented -as lists. The @sc{car} of the list is the event type; this says which -mouse button was involved, and which modifier keys were used with it. -The event type can also distinguish double or triple button presses -(@pxref{Repeat Events}). The rest of the list elements give position -and time information. - -For key lookup, only the event type matters: two events of the same type -necessarily run the same command. The command can access the full -values of these events using the @samp{e} interactive code. -@xref{Interactive Codes}. - -A key sequence that starts with a mouse event is read using the keymaps -of the buffer in the window that the mouse was in, not the current -buffer. This does not imply that clicking in a window selects that -window or its buffer---that is entirely under the control of the command -binding of the key sequence. - -@node Click Events -@subsection Click Events -@cindex click event -@cindex mouse click event - -When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event -share the same format: - -@example -(@var{event-type} @var{position} @var{click-count}) -@end example - -@table @asis -@item @var{event-type} -This is a symbol that indicates which mouse button was used. It is -one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. - -You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, -@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift -and super, just as you would with function keys. - -This symbol also serves as the event type of the event. Key bindings -describe events by their types; thus, if there is a key binding for -@code{mouse-1}, that binding would apply to all events whose -@var{event-type} is @code{mouse-1}. - -@item @var{position} -This is the position where the mouse click occurred. The actual -format of @var{position} depends on what part of a window was clicked -on. - -For mouse click events in the text area, mode line, header line, or in -the marginal areas, @var{position} has this form: - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@table @asis -@item @var{window} -This is the window in which the click occurred. - -@item @var{pos-or-area} -This is the buffer position of the character clicked on in the text -area, or if clicked outside the text area, it is the window area in -which the click occurred. It is one of the symbols @code{mode-line}, -@code{header-line}, @code{vertical-line}, @code{left-margin}, -@code{right-margin}, @code{left-fringe}, or @code{right-fringe}. - -In one special case, @var{pos-or-area} is a list containing a symbol (one -of the symbols listed above) instead of just the symbol. This happens -after the imaginary prefix keys for the event are inserted into the -input stream. @xref{Key Sequence Input}. - - -@item @var{x}, @var{y} -These are the pixel coordinates of the click, relative to -the top left corner of @var{window}, which is @code{(0 . 0)}. -For the mode or header line, @var{y} does not have meaningful data. -For the vertical line, @var{x} does not have meaningful data. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{object} -This is the object on which the click occurred. It is either -@code{nil} if there is no string property, or it has the form -(@var{string} . @var{string-pos}) when there is a string-type text -property at the click position. - -@table @asis -@item @var{string} -This is the string on which the click occurred, including any -properties. - -@item @var{string-pos} -This is the position in the string on which the click occurred, -relevant if properties at the click need to be looked up. -@end table - -@item @var{text-pos} -For clicks on a marginal area or on a fringe, this is the buffer -position of the first visible character in the corresponding line in -the window. For other events, it is the current buffer position in -the window. - -@item @var{col}, @var{row} -These are the actual coordinates of the glyph under the @var{x}, -@var{y} position, possibly padded with default character width -glyphs if @var{x} is beyond the last glyph on the line. - -@item @var{image} -This is the image object on which the click occurred. It is either -@code{nil} if there is no image at the position clicked on, or it is -an image object as returned by @code{find-image} if click was in an image. - -@item @var{dx}, @var{dy} -These are the pixel coordinates of the click, relative to -the top left corner of @var{object}, which is @code{(0 . 0)}. If -@var{object} is @code{nil}, the coordinates are relative to the top -left corner of the character glyph clicked on. - -@item @var{width}, @var{height} -These are the pixel width and height of @var{object} or, if this is -@code{nil}, those of the character glyph clicked on. -@end table - -@sp 1 -For mouse clicks on a scroll-bar, @var{position} has this form: - -@example -(@var{window} @var{area} (@var{portion} . @var{whole}) @var{timestamp} @var{part}) -@end example - -@table @asis -@item @var{window} -This is the window whose scroll-bar was clicked on. - -@item @var{area} -This is the scroll bar where the click occurred. It is one of the -symbols @code{vertical-scroll-bar} or @code{horizontal-scroll-bar}. - -@item @var{portion} -This is the distance of the click from the top or left end of -the scroll bar. - -@item @var{whole} -This is the length of the entire scroll bar. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. - -@item @var{part} -This is the part of the scroll-bar which was clicked on. It is one -of the symbols @code{above-handle}, @code{handle}, @code{below-handle}, -@code{up}, @code{down}, @code{top}, @code{bottom}, and @code{end-scroll}. -@end table - -@item @var{click-count} -This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. -@end table - -@node Drag Events -@subsection Drag Events -@cindex drag event -@cindex mouse drag event - -With Emacs, you can have a drag event without even changing your -clothes. A @dfn{drag event} happens every time the user presses a mouse -button and then moves the mouse to a different character position before -releasing the button. Like all mouse events, drag events are -represented in Lisp as lists. The lists record both the starting mouse -position and the final position, like this: - -@example -(@var{event-type} - (@var{window1} START-POSITION) - (@var{window2} END-POSITION)) -@end example - -For a drag event, the name of the symbol @var{event-type} contains the -prefix @samp{drag-}. For example, dragging the mouse with button 2 -held down generates a @code{drag-mouse-2} event. The second and third -elements of the event give the starting and ending position of the -drag. They have the same form as @var{position} in a click event -(@pxref{Click Events}) that is not on the scroll bar part of the -window. You can access the second element of any mouse event in the -same way, with no need to distinguish drag events from others. - -The @samp{drag-} prefix follows the modifier key prefixes such as -@samp{C-} and @samp{M-}. - -If @code{read-key-sequence} receives a drag event that has no key -binding, and the corresponding click event does have a binding, it -changes the drag event into a click event at the drag's starting -position. This means that you don't have to distinguish between click -and drag events unless you want to. - -@node Button-Down Events -@subsection Button-Down Events -@cindex button-down event - -Click and drag events happen when the user releases a mouse button. -They cannot happen earlier, because there is no way to distinguish a -click from a drag until the button is released. - -If you want to take action as soon as a button is pressed, you need to -handle @dfn{button-down} events.@footnote{Button-down is the -conservative antithesis of drag.} These occur as soon as a button is -pressed. They are represented by lists that look exactly like click -events (@pxref{Click Events}), except that the @var{event-type} symbol -name contains the prefix @samp{down-}. The @samp{down-} prefix follows -modifier key prefixes such as @samp{C-} and @samp{M-}. - -The function @code{read-key-sequence} ignores any button-down events -that don't have command bindings; therefore, the Emacs command loop -ignores them too. This means that you need not worry about defining -button-down events unless you want them to do something. The usual -reason to define a button-down event is so that you can track mouse -motion (by reading motion events) until the button is released. -@xref{Motion Events}. - -@node Repeat Events -@subsection Repeat Events -@cindex repeat events -@cindex double-click events -@cindex triple-click events -@cindex mouse events, repeated - -If you press the same mouse button more than once in quick succession -without moving the mouse, Emacs generates special @dfn{repeat} mouse -events for the second and subsequent presses. - -The most common repeat events are @dfn{double-click} events. Emacs -generates a double-click event when you click a button twice; the event -happens when you release the button (as is normal for all click -events). - -The event type of a double-click event contains the prefix -@samp{double-}. Thus, a double click on the second mouse button with -@key{meta} held down comes to the Lisp program as -@code{M-double-mouse-2}. If a double-click event has no binding, the -binding of the corresponding ordinary click event is used to execute -it. Thus, you need not pay attention to the double click feature -unless you really want to. - -When the user performs a double click, Emacs generates first an ordinary -click event, and then a double-click event. Therefore, you must design -the command binding of the double click event to assume that the -single-click command has already run. It must produce the desired -results of a double click, starting from the results of a single click. - -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface -design practice for double clicks. - -If you click a button, then press it down again and start moving the -mouse with the button held down, then you get a @dfn{double-drag} event -when you ultimately release the button. Its event type contains -@samp{double-drag} instead of just @samp{drag}. If a double-drag event -has no binding, Emacs looks for an alternate binding as if the event -were an ordinary drag. - -Before the double-click or double-drag event, Emacs generates a -@dfn{double-down} event when the user presses the button down for the -second time. Its event type contains @samp{double-down} instead of just -@samp{down}. If a double-down event has no binding, Emacs looks for an -alternate binding as if the event were an ordinary button-down event. -If it finds no binding that way either, the double-down event is -ignored. - -To summarize, when you click a button and then press it again right -away, Emacs generates a down event and a click event for the first -click, a double-down event when you press the button again, and finally -either a double-click or a double-drag event. - -If you click a button twice and then press it again, all in quick -succession, Emacs generates a @dfn{triple-down} event, followed by -either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of -these events contain @samp{triple} instead of @samp{double}. If any -triple event has no binding, Emacs uses the binding that it would use -for the corresponding double event. - -If you click a button three or more times and then press it again, the -events for the presses beyond the third are all triple events. Emacs -does not have separate event types for quadruple, quintuple, etc.@: -events. However, you can look at the event list to find out precisely -how many times the button was pressed. - -@defun event-click-count event -This function returns the number of consecutive button presses that led -up to @var{event}. If @var{event} is a double-down, double-click or -double-drag event, the value is 2. If @var{event} is a triple event, -the value is 3 or greater. If @var{event} is an ordinary mouse event -(not a repeat event), the value is 1. -@end defun - -@defopt double-click-fuzz -To generate repeat events, successive mouse button presses must be at -approximately the same screen position. The value of -@code{double-click-fuzz} specifies the maximum number of pixels the -mouse may be moved (horizontally or vertically) between two successive -clicks to make a double-click. - -This variable is also the threshold for motion of the mouse to count -as a drag. -@end defopt - -@defopt double-click-time -To generate repeat events, the number of milliseconds between -successive button presses must be less than the value of -@code{double-click-time}. Setting @code{double-click-time} to -@code{nil} disables multi-click detection entirely. Setting it to -@code{t} removes the time limit; Emacs then detects multi-clicks by -position only. -@end defopt - -@node Motion Events -@subsection Motion Events -@cindex motion event -@cindex mouse motion events - -Emacs sometimes generates @dfn{mouse motion} events to describe motion -of the mouse without any button activity. Mouse motion events are -represented by lists that look like this: - -@example -(mouse-movement (POSITION)) -@end example - -The second element of the list describes the current position of the -mouse, just as in a click event (@pxref{Click Events}). - -The special form @code{track-mouse} enables generation of motion events -within its body. Outside of @code{track-mouse} forms, Emacs does not -generate events for mere motion of the mouse, and these events do not -appear. @xref{Mouse Tracking}. - -@node Focus Events -@subsection Focus Events -@cindex focus event - -Window systems provide general ways for the user to control which window -gets keyboard input. This choice of window is called the @dfn{focus}. -When the user does something to switch between Emacs frames, that -generates a @dfn{focus event}. The normal definition of a focus event, -in the global keymap, is to select a new frame within Emacs, as the user -would expect. @xref{Input Focus}. - -Focus events are represented in Lisp as lists that look like this: - -@example -(switch-frame @var{new-frame}) -@end example - -@noindent -where @var{new-frame} is the frame switched to. - -Some X window managers are set up so that just moving the mouse into a -window is enough to set the focus there. Usually, there is no need -for a Lisp program to know about the focus change until some other -kind of input arrives. Emacs generates a focus event only when the -user actually types a keyboard key or presses a mouse button in the -new frame; just moving the mouse between frames does not generate a -focus event. - -A focus event in the middle of a key sequence would garble the -sequence. So Emacs never generates a focus event in the middle of a key -sequence. If the user changes focus in the middle of a key -sequence---that is, after a prefix key---then Emacs reorders the events -so that the focus event comes either before or after the multi-event key -sequence, and not within it. - -@node Misc Events -@subsection Miscellaneous System Events - -A few other event types represent occurrences within the system. - -@table @code -@cindex @code{delete-frame} event -@item (delete-frame (@var{frame})) -This kind of event indicates that the user gave the window manager -a command to delete a particular window, which happens to be an Emacs frame. - -The standard definition of the @code{delete-frame} event is to delete @var{frame}. - -@cindex @code{iconify-frame} event -@item (iconify-frame (@var{frame})) -This kind of event indicates that the user iconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been iconified, Emacs has no work to do. The purpose -of this event type is so that you can keep track of such events if you -want to. - -@cindex @code{make-frame-visible} event -@item (make-frame-visible (@var{frame})) -This kind of event indicates that the user deiconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been made visible, Emacs has no work to do. - -@cindex @code{wheel-up} event -@cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@item (wheel-down @var{position}) -These kinds of event are generated by moving a mouse wheel. Their -usual meaning is a kind of scroll or zoom. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event. - -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. - -@cindex @code{drag-n-drop} event -@item (drag-n-drop @var{position} @var{files}) -This kind of event is generated when a group of files is -selected in an application outside of Emacs, and then dragged and -dropped onto an Emacs frame. - -The element @var{position} is a list describing the position of the -event, in the same format as used in a mouse-click event, and -@var{files} is the list of file names that were dragged and dropped. -The usual way to handle this event is by visiting these files. - -This kind of event is generated, at present, only on some kinds of -systems. - -@cindex @code{help-echo} event -@item help-echo -This kind of event is generated when a mouse pointer moves onto a -portion of buffer text which has a @code{help-echo} text property. -The generated event has this form: - -@example -(help-echo @var{frame} @var{help} @var{window} @var{object} @var{pos}) -@end example - -@noindent -The precise meaning of the event parameters and the way these -parameters are used to display the help-echo text are described in -@ref{Text help-echo}. - -@cindex @code{sigusr1} event -@cindex @code{sigusr2} event -@cindex user signals -@item sigusr1 -@itemx sigusr2 -These events are generated when the Emacs process receives -the signals @code{SIGUSR1} and @code{SIGUSR2}. They contain no -additional data because signals do not carry additional information. - -To catch a user signal, bind the corresponding event to an interactive -command in the @code{special-event-map} (@pxref{Active Keymaps}). -The command is called with no arguments, and the specific signal event is -available in @code{last-input-event}. For example: - -@smallexample -(defun sigusr-handler () - (interactive) - (message "Caught signal %S" last-input-event)) - -(define-key special-event-map [sigusr1] 'sigusr-handler) -@end smallexample - -To test the signal handler, you can make Emacs send a signal to itself: - -@smallexample -(signal-process (emacs-pid) 'sigusr1) -@end smallexample -@end table - - If one of these events arrives in the middle of a key sequence---that -is, after a prefix key---then Emacs reorders the events so that this -event comes either before or after the multi-event key sequence, not -within it. - -@node Event Examples -@subsection Event Examples - -If the user presses and releases the left mouse button over the same -location, that generates a sequence of events like this: - -@smallexample -(down-mouse-1 (# 2613 (0 . 38) -864320)) -(mouse-1 (# 2613 (0 . 38) -864180)) -@end smallexample - -While holding the control key down, the user might hold down the -second mouse button, and drag the mouse from one line to the next. -That produces two events, as shown here: - -@smallexample -(C-down-mouse-2 (# 3440 (0 . 27) -731219)) -(C-drag-mouse-2 (# 3440 (0 . 27) -731219) - (# 3510 (0 . 28) -729648)) -@end smallexample - -While holding down the meta and shift keys, the user might press the -second mouse button on the window's mode line, and then drag the mouse -into another window. That produces a pair of events like these: - -@smallexample -(M-S-down-mouse-2 (# mode-line (33 . 31) -457844)) -(M-S-drag-mouse-2 (# mode-line (33 . 31) -457844) - (# 161 (33 . 3) - -453816)) -@end smallexample - -To handle a SIGUSR1 signal, define an interactive function, and -bind it to the @code{signal usr1} event sequence: - -@smallexample -(defun usr1-handler () - (interactive) - (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) -@end smallexample - -@node Classifying Events -@subsection Classifying Events -@cindex event type - - Every event has an @dfn{event type}, which classifies the event for -key binding purposes. For a keyboard event, the event type equals the -event value; thus, the event type for a character is the character, and -the event type for a function key symbol is the symbol itself. For -events that are lists, the event type is the symbol in the @sc{car} of -the list. Thus, the event type is always a symbol or a character. - - Two events of the same type are equivalent where key bindings are -concerned; thus, they always run the same command. That does not -necessarily mean they do the same things, however, as some commands look -at the whole event to decide what to do. For example, some commands use -the location of a mouse event to decide where in the buffer to act. - - Sometimes broader classifications of events are useful. For example, -you might want to ask whether an event involved the @key{META} key, -regardless of which other key or mouse button was used. - - The functions @code{event-modifiers} and @code{event-basic-type} are -provided to get such information conveniently. - -@defun event-modifiers event -This function returns a list of the modifiers that @var{event} has. The -modifiers are symbols; they include @code{shift}, @code{control}, -@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, -the modifiers list of a mouse event symbol always contains one of -@code{click}, @code{drag}, and @code{down}. For double or triple -events, it also contains @code{double} or @code{triple}. - -The argument @var{event} may be an entire event object, or just an -event type. If @var{event} is a symbol that has never been used in an -event that has been read as input in the current Emacs session, then -@code{event-modifiers} can return @code{nil}, even when @var{event} -actually has modifiers. - -Here are some examples: - -@example -(event-modifiers ?a) - @result{} nil -(event-modifiers ?A) - @result{} (shift) -(event-modifiers ?\C-a) - @result{} (control) -(event-modifiers ?\C-%) - @result{} (control) -(event-modifiers ?\C-\S-a) - @result{} (control shift) -(event-modifiers 'f5) - @result{} nil -(event-modifiers 's-f5) - @result{} (super) -(event-modifiers 'M-S-f5) - @result{} (meta shift) -(event-modifiers 'mouse-1) - @result{} (click) -(event-modifiers 'down-mouse-1) - @result{} (down) -@end example - -The modifiers list for a click event explicitly contains @code{click}, -but the event symbol name itself does not contain @samp{click}. -@end defun - -@defun event-basic-type event -This function returns the key or mouse button that @var{event} -describes, with all modifiers removed. The @var{event} argument is as -in @code{event-modifiers}. For example: - -@example -(event-basic-type ?a) - @result{} 97 -(event-basic-type ?A) - @result{} 97 -(event-basic-type ?\C-a) - @result{} 97 -(event-basic-type ?\C-\S-a) - @result{} 97 -(event-basic-type 'f5) - @result{} f5 -(event-basic-type 's-f5) - @result{} f5 -(event-basic-type 'M-S-f5) - @result{} f5 -(event-basic-type 'down-mouse-1) - @result{} mouse-1 -@end example -@end defun - -@defun mouse-movement-p object -This function returns non-@code{nil} if @var{object} is a mouse movement -event. -@end defun - -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - -@node Accessing Mouse -@subsection Accessing Mouse Events -@cindex mouse events, data in - - This section describes convenient functions for accessing the data in -a mouse button or motion event. - - These two functions return the starting or ending position of a -mouse-button event, as a list of this form: - -@example -(@var{window} @var{pos-or-area} (@var{x} . @var{y}) @var{timestamp} - @var{object} @var{text-pos} (@var{col} . @var{row}) - @var{image} (@var{dx} . @var{dy}) (@var{width} . @var{height})) -@end example - -@defun event-start event -This returns the starting position of @var{event}. - -If @var{event} is a click or button-down event, this returns the -location of the event. If @var{event} is a drag event, this returns the -drag's starting position. -@end defun - -@defun event-end event -This returns the ending position of @var{event}. - -If @var{event} is a drag event, this returns the position where the user -released the mouse button. If @var{event} is a click or button-down -event, the value is actually the starting position, which is the only -position such events have. -@end defun - -@cindex mouse position list, accessing - These functions take a position list as described above, and -return various parts of it. - -@defun posn-window position -Return the window that @var{position} is in. -@end defun - -@defun posn-area position -Return the window area recorded in @var{position}. It returns @code{nil} -when the event occurred in the text area of the window; otherwise, it -is a symbol identifying the area in which the event occurred. -@end defun - -@defun posn-point position -Return the buffer position in @var{position}. When the event occurred -in the text area of the window, in a marginal area, or on a fringe, -this is an integer specifying a buffer position. Otherwise, the value -is undefined. -@end defun - -@defun posn-x-y position -Return the pixel-based x and y coordinates in @var{position}, as a -cons cell @code{(@var{x} . @var{y})}. These coordinates are relative -to the window given by @code{posn-window}. - -This example shows how to convert these window-relative coordinates -into frame-relative coordinates: - -@example -(defun frame-relative-coordinates (position) - "Return frame-relative coordinates from POSITION." - (let* ((x-y (posn-x-y position)) - (window (posn-window position)) - (edges (window-inside-pixel-edges window))) - (cons (+ (car x-y) (car edges)) - (+ (cdr x-y) (cadr edges))))) -@end example -@end defun - -@defun posn-col-row position -Return the row and column (in units of the frame's default character -height and width) of @var{position}, as a cons cell @code{(@var{col} . -@var{row})}. These are computed from the @var{x} and @var{y} values -actually found in @var{position}. -@end defun - -@defun posn-actual-col-row position -Return the actual row and column in @var{position}, as a cons cell -@code{(@var{col} . @var{row})}. The values are the actual row number -in the window, and the actual character number in that row. It returns -@code{nil} if @var{position} does not include actual positions values. -You can use @code{posn-col-row} to get approximate values. -@end defun - -@defun posn-string position -Return the string object in @var{position}, either @code{nil}, or a -cons cell @code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-image position -Return the image object in @var{position}, either @code{nil}, or an -image @code{(image ...)}. -@end defun - -@defun posn-object position -Return the image or string object in @var{position}, either -@code{nil}, an image @code{(image ...)}, or a cons cell -@code{(@var{string} . @var{string-pos})}. -@end defun - -@defun posn-object-x-y position -Return the pixel-based x and y coordinates relative to the upper left -corner of the object in @var{position} as a cons cell @code{(@var{dx} -. @var{dy})}. If the @var{position} is a buffer position, return the -relative position in the character at that position. -@end defun - -@defun posn-object-width-height position -Return the pixel width and height of the object in @var{position} as a -cons cell @code{(@var{width} . @var{height})}. If the @var{position} -is a buffer position, return the size of the character at that position. -@end defun - -@cindex timestamp of a mouse event -@defun posn-timestamp position -Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. -@end defun - - These functions compute a position list given particular buffer -position or screen position. You can access the data in this position -list with the functions described above. - -@defun posn-at-point &optional pos window -This function returns a position list for position @var{pos} in -@var{window}. @var{pos} defaults to point in @var{window}; -@var{window} defaults to the selected window. - -@code{posn-at-point} returns @code{nil} if @var{pos} is not visible in -@var{window}. -@end defun - -@defun posn-at-x-y x y &optional frame-or-window whole -This function returns position information corresponding to pixel -coordinates @var{x} and @var{y} in a specified frame or window, -@var{frame-or-window}, which defaults to the selected window. -The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. -@end defun - -@node Accessing Scroll -@subsection Accessing Scroll Bar Events -@cindex scroll bar events, data in - - These functions are useful for decoding scroll bar events. - -@defun scroll-bar-event-ratio event -This function returns the fractional vertical position of a scroll bar -event within the scroll bar. The value is a cons cell -@code{(@var{portion} . @var{whole})} containing two integers whose ratio -is the fractional position. -@end defun - -@defun scroll-bar-scale ratio total -This function multiplies (in effect) @var{ratio} by @var{total}, -rounding the result to an integer. The argument @var{ratio} is not a -number, but rather a pair @code{(@var{num} . @var{denom})}---typically a -value returned by @code{scroll-bar-event-ratio}. - -This function is handy for scaling a position on a scroll bar into a -buffer position. Here's how to do that: - -@example -(+ (point-min) - (scroll-bar-scale - (posn-x-y (event-start event)) - (- (point-max) (point-min)))) -@end example - -Recall that scroll bar events have two integers forming a ratio, in place -of a pair of x and y coordinates. -@end defun - -@node Strings of Events -@subsection Putting Keyboard Events in Strings -@cindex keyboard events in strings -@cindex strings with keyboard events - - In most of the places where strings are used, we conceptualize the -string as containing text characters---the same kind of characters found -in buffers or files. Occasionally Lisp programs use strings that -conceptually contain keyboard characters; for example, they may be key -sequences or keyboard macro definitions. However, storing keyboard -characters in a string is a complex matter, for reasons of historical -compatibility, and it is not always possible. - - We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. - -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize - - The complexities stem from the modifier bits that keyboard input -characters can include. Aside from the Meta modifier, none of these -modifier bits can be included in a string, and the Meta modifier is -allowed only in special cases. - - The earliest GNU Emacs versions represented meta characters as codes -in the range of 128 to 255. At that time, the basic character codes -ranged from 0 to 127, so all keyboard character codes did fit in a -string. Many Lisp programs used @samp{\M-} in string constants to stand -for meta characters, especially in arguments to @code{define-key} and -similar functions, and key sequences and sequences of events were always -represented as strings. - - When we added support for larger basic character codes beyond 127, and -additional modifier bits, we had to change the representation of meta -characters. Now the flag that represents the Meta modifier in a -character is -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -and such numbers cannot be included in a string. - - To support programs with @samp{\M-} in string constants, there are -special rules for including certain meta characters in a string. -Here are the rules for interpreting a string as a sequence of input -characters: - -@itemize @bullet -@item -If the keyboard character value is in the range of 0 to 127, it can go -in the string unchanged. - -@item -The meta variants of those characters, with codes in the range of -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -to -@tex -@math{2^{27} + 127}, -@end tex -@ifnottex -2**27+127, -@end ifnottex -can also go in the string, but you must change their -numeric values. You must set the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit instead of the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit, resulting in a value between 128 and 255. Only a unibyte string -can include these codes. - -@item -Non-@acronym{ASCII} characters above 256 can be included in a multibyte string. - -@item -Other keyboard character events cannot fit in a string. This includes -keyboard events in the range of 128 to 255. -@end itemize - - Functions such as @code{read-key-sequence} that construct strings of -keyboard input characters follow these rules: they construct vectors -instead of strings, when the events won't fit in a string. - - When you use the read syntax @samp{\M-} in a string, it produces a -code in the range of 128 to 255---the same code that you get if you -modify the corresponding keyboard event to put it in the string. Thus, -meta events in strings work consistently regardless of how they get into -the strings. - - However, most programs would do well to avoid these issues by -following the recommendations at the beginning of this section. - -@node Reading Input -@section Reading Input -@cindex read input -@cindex keyboard input - - The editor command loop reads key sequences using the function -@code{read-key-sequence}, which uses @code{read-event}. These and other -functions for event input are also available for use in Lisp programs. -See also @code{momentary-string-display} in @ref{Temporary Displays}, -and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for -functions and variables for controlling terminal input modes and -debugging terminal input. - - For higher-level input facilities, see @ref{Minibuffers}. - -@menu -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. -@end menu - -@node Key Sequence Input -@subsection Key Sequence Input -@cindex key sequence input - - The command loop reads input a key sequence at a time, by calling -@code{read-key-sequence}. Lisp programs can also call this function; -for example, @code{describe-key} uses it to read the key to describe. - -@defun read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This function reads a key sequence and returns it as a string or -vector. It keeps reading events until it has accumulated a complete key -sequence; that is, enough to specify a non-prefix command using the -currently active keymaps. (Remember that a key sequence that starts -with a mouse event is read using the keymaps of the buffer in the -window that the mouse was in, not the current buffer.) - -If the events are all characters and all can fit in a string, then -@code{read-key-sequence} returns a string (@pxref{Strings of Events}). -Otherwise, it returns a vector, since a vector can hold all kinds of -events---characters, symbols, and lists. The elements of the string or -vector are the events in the key sequence. - -Reading a key sequence includes translating the events in various -ways. @xref{Translation Keymaps}. - -The argument @var{prompt} is either a string to be displayed in the -echo area as a prompt, or @code{nil}, meaning not to display a prompt. -The argument @var{continue-echo}, if non-@code{nil}, means to echo -this key as a continuation of the previous key. - -Normally any upper case event is converted to lower case if the -original event is undefined and the lower case equivalent is defined. -The argument @var{dont-downcase-last}, if non-@code{nil}, means do not -convert the last event to lower case. This is appropriate for reading -a key sequence to be defined. - -The argument @var{switch-frame-ok}, if non-@code{nil}, means that this -function should process a @code{switch-frame} event if the user -switches frames before typing anything. If the user switches frames -in the middle of a key sequence, or at the start of the sequence but -@var{switch-frame-ok} is @code{nil}, then the event will be put off -until after the current key sequence. - -The argument @var{command-loop}, if non-@code{nil}, means that this -key sequence is being read by something that will read commands one -after another. It should be @code{nil} if the caller will read just -one key sequence. - -In the following example, Emacs displays the prompt @samp{?} in the -echo area, and then the user types @kbd{C-x C-f}. - -@example -(read-key-sequence "?") - -@group ----------- Echo Area ---------- -?@kbd{C-x C-f} ----------- Echo Area ---------- - - @result{} "^X^F" -@end group -@end example - -The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} -typed while reading with this function works like any other character, -and does not set @code{quit-flag}. @xref{Quitting}. -@end defun - -@defun read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop -This is like @code{read-key-sequence} except that it always -returns the key sequence as a vector, never as a string. -@xref{Strings of Events}. -@end defun - -@cindex upper case key sequence -@cindex downcasing in @code{lookup-key} -@cindex shift-translation -If an input character is upper-case (or has the shift modifier) and -has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. - -@vindex this-command-keys-shift-translated -When reading input results in such a @dfn{shift-translation}, Emacs -sets the variable @code{this-command-keys-shift-translated} to a -non-@code{nil} value. Lisp programs can examine this variable if they -need to modify their behavior when invoked by shift-translated keys. -For example, the function @code{handle-shift-selection} examines the -value of this variable to determine how to activate or deactivate the -region (@pxref{The Mark, handle-shift-selection}). - -The function @code{read-key-sequence} also transforms some mouse events. -It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events and -miscellaneous window events so that they never appear in a key sequence -with any other events. - -@cindex @code{header-line} prefix key -@cindex @code{mode-line} prefix key -@cindex @code{vertical-line} prefix key -@cindex @code{horizontal-scroll-bar} prefix key -@cindex @code{vertical-scroll-bar} prefix key -@cindex @code{menu-bar} prefix key -@cindex mouse events, in special parts of frame -When mouse events occur in special parts of a window, such as a mode -line or a scroll bar, the event type shows nothing special---it is the -same symbol that would normally represent that combination of mouse -button and modifier keys. The information about the window part is kept -elsewhere in the event---in the coordinates. But -@code{read-key-sequence} translates this information into imaginary -``prefix keys,'' all of which are symbols: @code{header-line}, -@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, -@code{vertical-line}, and @code{vertical-scroll-bar}. You can define -meanings for mouse clicks in special window parts by defining key -sequences using these imaginary prefix keys. - -For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get two events, like this: - -@example -(read-key-sequence "Click on the mode line: ") - @result{} [mode-line - (mouse-1 - (# mode-line - (40 . 63) 5959987))] -@end example - -@defvar num-input-keys -@c Emacs 19 feature -This variable's value is the number of key sequences processed so far in -this Emacs session. This includes key sequences read from the terminal -and key sequences read from keyboard macros being executed. -@end defvar - -@node Reading One Event -@subsection Reading One Event -@cindex reading a single event -@cindex event, reading only one - - The lowest level functions for command input are those that read a -single event. - -None of the three functions below suppresses quitting. - -@defun read-event &optional prompt inherit-input-method seconds -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. - -If the optional argument @var{prompt} is non-@code{nil}, it should be a -string to display in the echo area as a prompt. Otherwise, -@code{read-event} does not display any message to indicate it is waiting -for input; instead, it prompts by echoing: it displays descriptions of -the events that led to or were read by the current command. @xref{The -Echo Area}. - -If @var{inherit-input-method} is non-@code{nil}, then the current input -method (if any) is employed to make it possible to enter a -non-@acronym{ASCII} character. Otherwise, input method handling is disabled -for reading this event. - -If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} -moves the cursor temporarily to the echo area, to the end of any message -displayed there. Otherwise @code{read-event} does not move the cursor. - -If @var{seconds} is non-@code{nil}, it should be a number specifying -the maximum time to wait for input, in seconds. If no input arrives -within that time, @code{read-event} stops waiting and returns -@code{nil}. A floating-point value for @var{seconds} means to wait -for a fractional number of seconds. Some systems support only a whole -number of seconds; on these systems, @var{seconds} is rounded down. -If @var{seconds} is @code{nil}, @code{read-event} waits as long as -necessary for input to arrive. - -If @var{seconds} is @code{nil}, Emacs is considered idle while waiting -for user input to arrive. Idle timers---those created with -@code{run-with-idle-timer} (@pxref{Idle Timers})---can run during this -period. However, if @var{seconds} is non-@code{nil}, the state of -idleness remains unchanged. If Emacs is non-idle when -@code{read-event} is called, it remains non-idle throughout the -operation of @code{read-event}; if Emacs is idle (which can happen if -the call happens inside an idle timer), it remains idle. - -If @code{read-event} gets an event that is defined as a help character, -then in some cases @code{read-event} processes the event directly without -returning. @xref{Help Functions}. Certain other events, called -@dfn{special events}, are also processed directly within -@code{read-event} (@pxref{Special Events}). - -Here is what happens if you call @code{read-event} and then press the -right-arrow function key: - -@example -@group -(read-event) - @result{} right -@end group -@end example -@end defun - -@defun read-char &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character (i.e. a mouse click or -function key event), @code{read-char} signals an error. The arguments -work as in @code{read-event}. - -In the first example, the user types the character @kbd{1} (@acronym{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. - -@example -@group -(read-char) - @result{} 49 -@end group - -@group -;; @r{We assume here you use @kbd{M-:} to evaluate this.} -(symbol-function 'foo) - @result{} "^[:(read-char)^M1" -@end group -@group -(execute-kbd-macro 'foo) - @print{} 49 - @result{} nil -@end group -@end example -@end defun - -@defun read-char-exclusive &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character, -@code{read-char-exclusive} ignores it and reads another event, until it -gets a character. The arguments work as in @code{read-event}. -@end defun - -@defvar num-nonmacro-input-events -This variable holds the total number of input events received so far -from the terminal---not counting those generated by keyboard macros. -@end defvar - -@node Event Mod -@subsection Modifying and Translating Input Events - - Emacs modifies every event it reads according to -@code{extra-keyboard-modifiers}, then translates it through -@code{keyboard-translate-table} (if applicable), before returning it -from @code{read-event}. - -@c Emacs 19 feature -@defvar extra-keyboard-modifiers -This variable lets Lisp programs ``press'' the modifier keys on the -keyboard. The value is a character. Only the modifiers of the -character matter. Each time the user types a keyboard key, it is -altered as if those modifier keys were held down. For instance, if -you bind @code{extra-keyboard-modifiers} to @code{?\C-\M-a}, then all -keyboard input characters typed during the scope of the binding will -have the control and meta modifiers applied to them. The character -@code{?\C-@@}, equivalent to the integer 0, does not count as a control -character for this purpose, but as a character with no modifiers. -Thus, setting @code{extra-keyboard-modifiers} to zero cancels any -modification. - -When using a window system, the program can ``press'' any of the -modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} -keys can be virtually pressed. - -Note that this variable applies only to events that really come from -the keyboard, and has no effect on mouse events or any other events. -@end defvar - -@defvar keyboard-translate-table -This terminal-local variable is the translate table for keyboard -characters. It lets you reshuffle the keys on the keyboard without -changing any command bindings. Its value is normally a char-table, or -else @code{nil}. (It can also be a string or vector, but this is -considered obsolete.) - -If @code{keyboard-translate-table} is a char-table -(@pxref{Char-Tables}), then each character read from the keyboard is -looked up in this char-table. If the value found there is -non-@code{nil}, then it is used instead of the actual input character. - -Note that this translation is the first thing that happens to a -character after it is read from the terminal. Record-keeping features -such as @code{recent-keys} and dribble files record the characters after -translation. - -Note also that this translation is done before the characters are -supplied to input methods (@pxref{Input Methods}). Use -@code{translation-table-for-input} (@pxref{Translation of Characters}), -if you want to translate characters after input methods operate. -@end defvar - -@defun keyboard-translate from to -This function modifies @code{keyboard-translate-table} to translate -character code @var{from} into character code @var{to}. It creates -the keyboard translate table if necessary. -@end defun - - Here's an example of using the @code{keyboard-translate-table} to -make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste -operations: - -@example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) -@end example - -@noindent -On a graphical terminal that supports extended @acronym{ASCII} input, -you can still get the standard Emacs meanings of one of those -characters by typing it with the shift key. That makes it a different -character as far as keyboard translation is concerned, but it has the -same usual meaning. - - @xref{Translation Keymaps}, for mechanisms that translate event sequences -at the level of @code{read-key-sequence}. - -@node Invoking the Input Method -@subsection Invoking the Input Method - - The event-reading functions invoke the current input method, if any -(@pxref{Input Methods}). If the value of @code{input-method-function} -is non-@code{nil}, it should be a function; when @code{read-event} reads -a printing character (including @key{SPC}) with no modifier bits, it -calls that function, passing the character as an argument. - -@defvar input-method-function -If this is non-@code{nil}, its value specifies the current input method -function. - -@strong{Warning:} don't bind this variable with @code{let}. It is often -buffer-local, and if you bind it around reading input (which is exactly -when you @emph{would} bind it), switching buffers asynchronously while -Emacs is waiting will cause the value to be restored in the wrong -buffer. -@end defvar - - The input method function should return a list of events which should -be used as input. (If the list is @code{nil}, that means there is no -input, so @code{read-event} waits for another event.) These events are -processed before the events in @code{unread-command-events} -(@pxref{Event Input Misc}). Events -returned by the input method function are not passed to the input method -function again, even if they are printing characters with no modifier -bits. - - If the input method function calls @code{read-event} or -@code{read-key-sequence}, it should bind @code{input-method-function} to -@code{nil} first, to prevent recursion. - - The input method function is not called when reading the second and -subsequent events of a key sequence. Thus, these characters are not -subject to input method processing. The input method function should -test the values of @code{overriding-local-map} and -@code{overriding-terminal-local-map}; if either of these variables is -non-@code{nil}, the input method should put its argument into a list and -return that list with no further processing. - -@node Quoted Character Input -@subsection Quoted Character Input -@cindex quoted character input - - You can use the function @code{read-quoted-char} to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command @code{quoted-insert} uses this function. - -@defun read-quoted-char &optional prompt -@cindex octal character input -@cindex control characters, reading -@cindex nonprinting characters, reading -This function is like @code{read-char}, except that if the first -character read is an octal digit (0-7), it reads any number of octal -digits (but stopping if a non-octal digit is found), and returns the -character represented by that numeric character code. If the -character that terminates the sequence of octal digits is @key{RET}, -it is discarded. Any other terminating character is used as input -after this function returns. - -Quitting is suppressed when the first character is read, so that the -user can enter a @kbd{C-g}. @xref{Quitting}. - -If @var{prompt} is supplied, it specifies a string for prompting the -user. The prompt string is always displayed in the echo area, followed -by a single @samp{-}. - -In the following example, the user types in the octal number 177 (which -is 127 in decimal). - -@example -(read-quoted-char "What character") - -@group ----------- Echo Area ---------- -What character @kbd{1 7 7}- ----------- Echo Area ---------- - - @result{} 127 -@end group -@end example -@end defun - -@need 2000 -@node Event Input Misc -@subsection Miscellaneous Event Input Features - -This section describes how to ``peek ahead'' at events without using -them up, how to check for pending input, and how to discard pending -input. See also the function @code{read-passwd} (@pxref{Reading a -Password}). - -@defvar unread-command-events -@cindex next input -@cindex peeking at input -This variable holds a list of events waiting to be read as command -input. The events are used in the order they appear in the list, and -removed one by one as they are used. - -The variable is needed because in some cases a function reads an event -and then decides not to use it. Storing the event in this variable -causes it to be processed normally, by the command loop or by the -functions to read command input. - -@cindex prefix argument unreading -For example, the function that implements numeric prefix arguments reads -any number of digits. When it finds a non-digit event, it must unread -the event so that it can be read normally by the command loop. -Likewise, incremental search uses this feature to unread events with no -special meaning in a search, because these events should exit the search -and then execute normally. - -The reliable and easy way to extract events from a key sequence so as to -put them in @code{unread-command-events} is to use -@code{listify-key-sequence} (@pxref{Strings of Events}). - -Normally you add events to the front of this list, so that the events -most recently unread will be reread first. - -Events read from this list are not normally added to the current -command's key sequence (as returned by e.g. @code{this-command-keys}), -as the events will already have been added once as they were read for -the first time. An element of the form @code{(@code{t} . @var{event})} -forces @var{event} to be added to the current command's key sequence. -@end defvar - -@defun listify-key-sequence key -This function converts the string or vector @var{key} to a list of -individual events, which you can put in @code{unread-command-events}. -@end defun - -@defvar unread-command-char -This variable holds a character to be read as command input. -A value of -1 means ``empty.'' - -This variable is mostly obsolete now that you can use -@code{unread-command-events} instead; it exists only to support programs -written for Emacs versions 18 and earlier. -@end defvar - -@defun input-pending-p -@cindex waiting for command key input -This function determines whether any command input is currently -available to be read. It returns immediately, with value @code{t} if -there is available input, @code{nil} otherwise. On rare occasions it -may return @code{t} when no input is available. -@end defun - -@defvar last-input-event -@defvarx last-input-char -This variable records the last terminal input event read, whether -as part of a command or explicitly by a Lisp program. - -In the example below, the Lisp program reads the character @kbd{1}, -@acronym{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate -this expression) remains the value of @code{last-command-event}. - -@example -@group -(progn (print (read-char)) - (print last-command-event) - last-input-event) - @print{} 49 - @print{} 5 - @result{} 49 -@end group -@end example - -The alias @code{last-input-char} is obsolete. -@end defvar - -@defmac while-no-input body@dots{} -This construct runs the @var{body} forms and returns the value of the -last one---but only if no input arrives. If any input arrives during -the execution of the @var{body} forms, it aborts them (working much -like a quit). The @code{while-no-input} form returns @code{nil} if -aborted by a real quit, and returns @code{t} if aborted by arrival of -other input. - -If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, -arrival of input during those parts won't cause an abort until -the end of that part. - -If you want to be able to distinguish all possible values computed -by @var{body} from both kinds of abort conditions, write the code -like this: - -@example -(while-no-input - (list - (progn . @var{body}))) -@end example -@end defmac - -@defun discard-input -@cindex flushing input -@cindex discarding input -@cindex keyboard macro, terminating -This function discards the contents of the terminal input buffer and -cancels any keyboard macro that might be in the process of definition. -It returns @code{nil}. - -In the following example, the user may type a number of characters right -after starting the evaluation of the form. After the @code{sleep-for} -finishes sleeping, @code{discard-input} discards any characters typed -during the sleep. - -@example -(progn (sleep-for 2) - (discard-input)) - @result{} nil -@end example -@end defun - -@node Special Events -@section Special Events - -@cindex special events -Special events are handled at a very low level---as soon as they are -read. The @code{read-event} function processes these events itself, and -never returns them. Instead, it keeps waiting for the first event -that is not special and returns that one. - -Events that are handled in this way do not echo, they are never grouped -into key sequences, and they never appear in the value of -@code{last-command-event} or @code{(this-command-keys)}. They do not -discard a numeric argument, they cannot be unread with -@code{unread-command-events}, they may not appear in a keyboard macro, -and they are not recorded in a keyboard macro while you are defining -one. - -These events do, however, appear in @code{last-input-event} immediately -after they are read, and this is the way for the event's definition to -find the actual event. - -The events types @code{iconify-frame}, @code{make-frame-visible}, -@code{delete-frame}, @code{drag-n-drop}, and user signals like -@code{sigusr1} are normally handled in this way. The keymap which -defines how to handle special events---and which events are special---is -in the variable @code{special-event-map} (@pxref{Active Keymaps}). - -@node Waiting -@section Waiting for Elapsed Time or Input -@cindex waiting - - The wait functions are designed to wait for a certain amount of time -to pass or until there is input. For example, you may wish to pause in -the middle of a computation to allow the user time to view the display. -@code{sit-for} pauses and updates the screen, and returns immediately if -input comes in, while @code{sleep-for} pauses without updating the -screen. - -@defun sit-for seconds &optional nodisp -This function performs redisplay (provided there is no pending input -from the user), then waits @var{seconds} seconds, or until input is -available. The usual purpose of @code{sit-for} is to give the user -time to read text that you display. The value is @code{t} if -@code{sit-for} waited the full time with no input arriving -(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The expression @code{(sit-for 0)} is equivalent to @code{(redisplay)}, -i.e. it requests a redisplay, without any delay, if there is no pending input. -@xref{Forcing Redisplay}. - -If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not -redisplay, but it still returns as soon as input is available (or when -the timeout elapses). - -In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be -interrupted, even by input from the standard input descriptor. It is -thus equivalent to @code{sleep-for}, which is described below. - -It is also possible to call @code{sit-for} with three arguments, -as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, -but that is considered obsolete. -@end defun - -@defun sleep-for seconds &optional millisec -This function simply pauses for @var{seconds} seconds without updating -the display. It pays no attention to available input. It returns -@code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -Use @code{sleep-for} when you wish to guarantee a delay. -@end defun - - @xref{Time of Day}, for functions to get the current time. - -@node Quitting -@section Quitting -@cindex @kbd{C-g} -@cindex quitting -@cindex interrupt Lisp functions - - Typing @kbd{C-g} while a Lisp function is running causes Emacs to -@dfn{quit} whatever it is doing. This means that control returns to the -innermost active command loop. - - Typing @kbd{C-g} while the command loop is waiting for keyboard input -does not cause a quit; it acts as an ordinary input character. In the -simplest case, you cannot tell the difference, because @kbd{C-g} -normally runs the command @code{keyboard-quit}, whose effect is to quit. -However, when @kbd{C-g} follows a prefix key, they combine to form an -undefined key. The effect is to cancel the prefix key as well as any -prefix argument. - - In the minibuffer, @kbd{C-g} has a different definition: it aborts out -of the minibuffer. This means, in effect, that it exits the minibuffer -and then quits. (Simply quitting would return to the command loop -@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit -directly when the command reader is reading input is so that its meaning -can be redefined in the minibuffer in this way. @kbd{C-g} following a -prefix key is not redefined in the minibuffer, and it has its normal -effect of canceling the prefix key and prefix argument. This too -would not be possible if @kbd{C-g} always quit directly. - - When @kbd{C-g} does directly quit, it does so by setting the variable -@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate -times and quits if it is not @code{nil}. Setting @code{quit-flag} -non-@code{nil} in any way thus causes a quit. - - At the level of C code, quitting cannot happen just anywhere; only at the -special places that check @code{quit-flag}. The reason for this is -that quitting at other places might leave an inconsistency in Emacs's -internal state. Because quitting is delayed until a safe place, quitting -cannot make Emacs crash. - - Certain functions such as @code{read-key-sequence} or -@code{read-quoted-char} prevent quitting entirely even though they wait -for input. Instead of quitting, @kbd{C-g} serves as the requested -input. In the case of @code{read-key-sequence}, this serves to bring -about the special behavior of @kbd{C-g} in the command loop. In the -case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used -to quote a @kbd{C-g}. - -@cindex preventing quitting - You can prevent quitting for a portion of a Lisp function by binding -the variable @code{inhibit-quit} to a non-@code{nil} value. Then, -although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the -usual result of this---a quit---is prevented. Eventually, -@code{inhibit-quit} will become @code{nil} again, such as when its -binding is unwound at the end of a @code{let} form. At that time, if -@code{quit-flag} is still non-@code{nil}, the requested quit happens -immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. - -@cindex @code{read-quoted-char} quitting - In some functions (such as @code{read-quoted-char}), @kbd{C-g} is -handled in a special way that does not involve quitting. This is done -by reading the input with @code{inhibit-quit} bound to @code{t}, and -setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} -becomes @code{nil} again. This excerpt from the definition of -@code{read-quoted-char} shows how this is done; it also shows that -normal quitting is permitted after the first character of input. - -@example -(defun read-quoted-char (&optional prompt) - "@dots{}@var{documentation}@dots{}" - (let ((message-log-max nil) done (first t) (code 0) char) - (while (not done) - (let ((inhibit-quit first) - @dots{}) - (and prompt (message "%s-" prompt)) - (setq char (read-event)) - (if inhibit-quit (setq quit-flag nil))) - @r{@dots{}set the variable @code{code}@dots{}}) - code)) -@end example - -@defvar quit-flag -If this variable is non-@code{nil}, then Emacs quits immediately, unless -@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets -@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. -@end defvar - -@defvar inhibit-quit -This variable determines whether Emacs should quit when @code{quit-flag} -is set to a value other than @code{nil}. If @code{inhibit-quit} is -non-@code{nil}, then @code{quit-flag} has no special effect. -@end defvar - -@defmac with-local-quit body@dots{} -This macro executes @var{body} forms in sequence, but allows quitting, at -least locally, within @var{body} even if @code{inhibit-quit} was -non-@code{nil} outside this construct. It returns the value of the -last form in @var{body}, unless exited by quitting, in which case -it returns @code{nil}. - -If @code{inhibit-quit} is @code{nil} on entry to @code{with-local-quit}, -it only executes the @var{body}, and setting @code{quit-flag} causes -a normal quit. However, if @code{inhibit-quit} is non-@code{nil} so -that ordinary quitting is delayed, a non-@code{nil} @code{quit-flag} -triggers a special kind of local quit. This ends the execution of -@var{body} and exits the @code{with-local-quit} body with -@code{quit-flag} still non-@code{nil}, so that another (ordinary) quit -will happen as soon as that is allowed. If @code{quit-flag} is -already non-@code{nil} at the beginning of @var{body}, the local quit -happens immediately and the body doesn't execute at all. - -This macro is mainly useful in functions that can be called from -timers, process filters, process sentinels, @code{pre-command-hook}, -@code{post-command-hook}, and other places where @code{inhibit-quit} is -normally bound to @code{t}. -@end defmac - -@deffn Command keyboard-quit -This function signals the @code{quit} condition with @code{(signal 'quit -nil)}. This is the same thing that quitting does. (See @code{signal} -in @ref{Errors}.) -@end deffn - - You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. - -@node Prefix Command Arguments -@section Prefix Command Arguments -@cindex prefix argument -@cindex raw prefix argument -@cindex numeric prefix argument - - Most Emacs commands can use a @dfn{prefix argument}, a number -specified before the command itself. (Don't confuse prefix arguments -with prefix keys.) The prefix argument is at all times represented by a -value, which may be @code{nil}, meaning there is currently no prefix -argument. Each command may use the prefix argument or ignore it. - - There are two representations of the prefix argument: @dfn{raw} and -@dfn{numeric}. The editor command loop uses the raw representation -internally, and so do the Lisp variables that store the information, but -commands can request either representation. - - Here are the possible values of a raw prefix argument: - -@itemize @bullet -@item -@code{nil}, meaning there is no prefix argument. Its numeric value is -1, but numerous commands make a distinction between @code{nil} and the -integer 1. - -@item -An integer, which stands for itself. - -@item -A list of one element, which is an integer. This form of prefix -argument results from one or a succession of @kbd{C-u}'s with no -digits. The numeric value is the integer in the list, but some -commands make a distinction between such a list and an integer alone. - -@item -The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was -typed, without following digits. The equivalent numeric value is -@minus{}1, but some commands make a distinction between the integer -@minus{}1 and the symbol @code{-}. -@end itemize - -We illustrate these possibilities by calling the following function with -various prefixes: - -@example -@group -(defun display-prefix (arg) - "Display the value of the raw prefix arg." - (interactive "P") - (message "%s" arg)) -@end group -@end example - -@noindent -Here are the results of calling @code{display-prefix} with various -raw prefix arguments: - -@example - M-x display-prefix @print{} nil - -C-u M-x display-prefix @print{} (4) - -C-u C-u M-x display-prefix @print{} (16) - -C-u 3 M-x display-prefix @print{} 3 - -M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} - -C-u - M-x display-prefix @print{} - - -M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} - -C-u - 7 M-x display-prefix @print{} -7 - -M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} -@end example - - Emacs uses two variables to store the prefix argument: -@code{prefix-arg} and @code{current-prefix-arg}. Commands such as -@code{universal-argument} that set up prefix arguments for other -commands store them in @code{prefix-arg}. In contrast, -@code{current-prefix-arg} conveys the prefix argument to the current -command, so setting it has no effect on the prefix arguments for future -commands. - - Normally, commands specify which representation to use for the prefix -argument, either numeric or raw, in the @code{interactive} specification. -(@xref{Using Interactive}.) Alternatively, functions may look at the -value of the prefix argument directly in the variable -@code{current-prefix-arg}, but this is less clean. - -@defun prefix-numeric-value arg -This function returns the numeric meaning of a valid raw prefix argument -value, @var{arg}. The argument may be a symbol, a number, or a list. -If it is @code{nil}, the value 1 is returned; if it is @code{-}, the -value @minus{}1 is returned; if it is a number, that number is returned; -if it is a list, the @sc{car} of that list (which should be a number) is -returned. -@end defun - -@defvar current-prefix-arg -This variable holds the raw prefix argument for the @emph{current} -command. Commands may examine it directly, but the usual method for -accessing it is with @code{(interactive "P")}. -@end defvar - -@defvar prefix-arg -The value of this variable is the raw prefix argument for the -@emph{next} editing command. Commands such as @code{universal-argument} -that specify prefix arguments for the following command work by setting -this variable. -@end defvar - -@defvar last-prefix-arg -The raw prefix argument value used by the previous command. -@end defvar - - The following commands exist to set up prefix arguments for the -following command. Do not call them for any other reason. - -@deffn Command universal-argument -This command reads input and specifies a prefix argument for the -following command. Don't call this command yourself unless you know -what you are doing. -@end deffn - -@deffn Command digit-argument arg -This command adds to the prefix argument for the following command. The -argument @var{arg} is the raw prefix argument as it was before this -command; it is used to compute the updated prefix argument. Don't call -this command yourself unless you know what you are doing. -@end deffn - -@deffn Command negative-argument arg -This command adds to the numeric argument for the next command. The -argument @var{arg} is the raw prefix argument as it was before this -command; its value is negated to form the new prefix argument. Don't -call this command yourself unless you know what you are doing. -@end deffn - -@node Recursive Editing -@section Recursive Editing -@cindex recursive command loop -@cindex recursive editing level -@cindex command loop, recursive - - The Emacs command loop is entered automatically when Emacs starts up. -This top-level invocation of the command loop never exits; it keeps -running as long as Emacs does. Lisp programs can also invoke the -command loop. Since this makes more than one activation of the command -loop, we call it @dfn{recursive editing}. A recursive editing level has -the effect of suspending whatever command invoked it and permitting the -user to do arbitrary editing before resuming that command. - - The commands available during recursive editing are the same ones -available in the top-level editing loop and defined in the keymaps. -Only a few special commands exit the recursive editing level; the others -return to the recursive editing level when they finish. (The special -commands for exiting are always available, but they do nothing when -recursive editing is not in progress.) - - All command loops, including recursive ones, set up all-purpose error -handlers so that an error in a command run from the command loop will -not exit the loop. - -@cindex minibuffer input - Minibuffer input is a special kind of recursive editing. It has a few -special wrinkles, such as enabling display of the minibuffer and the -minibuffer window, but fewer than you might suppose. Certain keys -behave differently in the minibuffer, but that is only because of the -minibuffer's local map; if you switch windows, you get the usual Emacs -commands. - -@cindex @code{throw} example -@kindex exit -@cindex exit recursive editing -@cindex aborting - To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). - - Most applications should not use recursive editing, except as part of -using the minibuffer. Usually it is more convenient for the user if you -change the major mode of the current buffer temporarily to a special -major mode, which should have a command to go back to the previous mode. -(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively,'' create and select -a new buffer in a special mode. In this mode, define a command to -complete the processing and go back to the previous buffer. (The -@kbd{m} command in Rmail does this.) - - Recursive edits are useful in debugging. You can insert a call to -@code{debug} into a function definition as a sort of breakpoint, so that -you can look around when the function gets there. @code{debug} invokes -a recursive edit but also provides the other features of the debugger. - - Recursive editing levels are also used when you type @kbd{C-r} in -@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). - -@defun recursive-edit -@cindex suspend evaluation -This function invokes the editor command loop. It is called -automatically by the initialization of Emacs, to let the user begin -editing. When called from a Lisp program, it enters a recursive editing -level. - -If the current buffer is not the same as the selected window's buffer, -@code{recursive-edit} saves and restores the current buffer. Otherwise, -if you switch buffers, the buffer you switched to is current after -@code{recursive-edit} returns. - -In the following example, the function @code{simple-rec} first -advances point one word, then enters a recursive edit, printing out a -message in the echo area. The user can then do any editing desired, and -then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. - -@example -(defun simple-rec () - (forward-word 1) - (message "Recursive edit in progress") - (recursive-edit) - (forward-word 1)) - @result{} simple-rec -(simple-rec) - @result{} nil -@end example -@end defun - -@deffn Command exit-recursive-edit -This function exits from the innermost recursive edit (including -minibuffer input). Its definition is effectively @code{(throw 'exit -nil)}. -@end deffn - -@deffn Command abort-recursive-edit -This function aborts the command that requested the innermost recursive -edit (including minibuffer input), by signaling @code{quit} -after exiting the recursive edit. Its definition is effectively -@code{(throw 'exit t)}. @xref{Quitting}. -@end deffn - -@deffn Command top-level -This function exits all recursive editing levels; it does not return a -value, as it jumps completely out of any computation directly back to -the main command loop. -@end deffn - -@defun recursion-depth -This function returns the current depth of recursive edits. When no -recursive edit is active, it returns 0. -@end defun - -@node Disabling Commands -@section Disabling Commands -@cindex disabled command - - @dfn{Disabling a command} marks the command as requiring user -confirmation before it can be executed. Disabling is used for commands -which might be confusing to beginning users, to prevent them from using -the commands by accident. - -@kindex disabled - The low-level mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. These properties are normally set up by the user's -init file (@pxref{Init File}) with Lisp expressions such as this: - -@example -(put 'upcase-region 'disabled t) -@end example - -@noindent -For a few commands, these properties are present by default (you can -remove them in your init file if you wish). - - If the value of the @code{disabled} property is a string, the message -saying the command is disabled includes that string. For example: - -@example -(put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") -@end example - - @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on -what happens when a disabled command is invoked interactively. -Disabling a command has no effect on calling it as a function from Lisp -programs. - -@deffn Command enable-command command -Allow @var{command} (a symbol) to be executed without special -confirmation from now on, and alter the user's init file (@pxref{Init -File}) so that this will apply to future sessions. -@end deffn - -@deffn Command disable-command command -Require special confirmation to execute @var{command} from now on, and -alter the user's init file so that this will apply to future sessions. -@end deffn - -@defvar disabled-command-function -The value of this variable should be a function. When the user -invokes a disabled command interactively, this function is called -instead of the disabled command. It can use @code{this-command-keys} -to determine what the user typed to run the command, and thus find the -command itself. - -The value may also be @code{nil}. Then all commands work normally, -even disabled ones. - -By default, the value is a function that asks the user whether to -proceed. -@end defvar - -@node Command History -@section Command History -@cindex command history -@cindex complex command -@cindex history of commands - - The command loop keeps a history of the complex commands that have -been executed, to make it convenient to repeat these commands. A -@dfn{complex command} is one for which the interactive argument reading -uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-:} command, and any command whose @code{interactive} -specification reads an argument from the minibuffer. Explicit use of -the minibuffer during the execution of the command itself does not cause -the command to be considered complex. - -@defvar command-history -This variable's value is a list of recent complex commands, each -represented as a form to evaluate. It continues to accumulate all -complex commands for the duration of the editing session, but when it -reaches the maximum size (@pxref{Minibuffer History}), the oldest -elements are deleted as new ones are added. - -@example -@group -command-history -@result{} ((switch-to-buffer "chistory.texi") - (describe-key "^X^[") - (visit-tags-table "~/emacs/src/") - (find-tag "repeat-complex-command")) -@end group -@end example -@end defvar - - This history list is actually a special case of minibuffer history -(@pxref{Minibuffer History}), with one special twist: the elements are -expressions rather than strings. - - There are a number of commands devoted to the editing and recall of -previous commands. The commands @code{repeat-complex-command}, and -@code{list-command-history} are described in the user manual -(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the -minibuffer, the usual minibuffer history commands are available. - -@node Keyboard Macros -@section Keyboard Macros -@cindex keyboard macros - - A @dfn{keyboard macro} is a canned sequence of input events that can -be considered a command and made the definition of a key. The Lisp -representation of a keyboard macro is a string or vector containing the -events. Don't confuse keyboard macros with Lisp macros -(@pxref{Macros}). - -@defun execute-kbd-macro kbdmacro &optional count loopfunc -This function executes @var{kbdmacro} as a sequence of events. If -@var{kbdmacro} is a string or vector, then the events in it are executed -exactly as if they had been input by the user. The sequence is -@emph{not} expected to be a single key sequence; normally a keyboard -macro definition consists of several key sequences concatenated. - -If @var{kbdmacro} is a symbol, then its function definition is used in -place of @var{kbdmacro}. If that is another symbol, this process repeats. -Eventually the result should be a string or vector. If the result is -not a symbol, string, or vector, an error is signaled. - -The argument @var{count} is a repeat count; @var{kbdmacro} is executed that -many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is -executed once. If it is 0, @var{kbdmacro} is executed over and over until it -encounters an error or a failing search. - -If @var{loopfunc} is non-@code{nil}, it is a function that is called, -without arguments, prior to each iteration of the macro. If -@var{loopfunc} returns @code{nil}, then this stops execution of the macro. - -@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}. -@end defun - -@defvar executing-kbd-macro -This variable contains the string or vector that defines the keyboard -macro that is currently executing. It is @code{nil} if no macro is -currently executing. A command can test this variable so as to behave -differently when run from an executing macro. Do not set this variable -yourself. -@end defvar - -@defvar defining-kbd-macro -This variable is non-@code{nil} if and only if a keyboard macro is -being defined. A command can test this variable so as to behave -differently while a macro is being defined. The value is -@code{append} while appending to the definition of an existing macro. -The commands @code{start-kbd-macro}, @code{kmacro-start-macro} and -@code{end-kbd-macro} set this variable---do not set it yourself. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -@defvar kbd-macro-termination-hook -This normal hook (@pxref{Standard Hooks}) is run when a keyboard -macro terminates, regardless of what caused it to terminate (reaching -the macro end or an error which ended the macro prematurely). -@end defvar - -@ignore - arch-tag: e34944ad-7d5c-4980-be00-36a5fe54d4b1 -@end ignore diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi deleted file mode 100644 index 227f86f930c..00000000000 --- a/doc/lispref/compile.texi +++ /dev/null @@ -1,802 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/compile -@node Byte Compilation, Advising Functions, Loading, Top -@chapter Byte Compilation -@cindex byte compilation -@cindex byte-code -@cindex compilation (Emacs Lisp) - - Emacs Lisp has a @dfn{compiler} that translates functions written -in Lisp into a special representation called @dfn{byte-code} that can be -executed more efficiently. The compiler replaces Lisp function -definitions with byte-code. When a byte-code function is called, its -definition is evaluated by the @dfn{byte-code interpreter}. - - Because the byte-compiled code is evaluated by the byte-code -interpreter, instead of being executed directly by the machine's -hardware (as true compiled code is), byte-code is completely -transportable from machine to machine without recompilation. It is not, -however, as fast as true compiled code. - - Compiling a Lisp file with the Emacs byte compiler always reads the -file as multibyte text, even if Emacs was started with @samp{--unibyte}, -unless the file specifies otherwise. This is so that compilation gives -results compatible with running the same file without compilation. -@xref{Loading Non-ASCII}. - - In general, any version of Emacs can run byte-compiled code produced -by recent earlier versions of Emacs, but the reverse is not true. - -@vindex no-byte-compile - If you do not want a Lisp file to be compiled, ever, put a file-local -variable binding for @code{no-byte-compile} into it, like this: - -@example -;; -*-no-byte-compile: t; -*- -@end example - - @xref{Compilation Errors}, for how to investigate errors occurring in -byte compilation. - -@menu -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. -@end menu - -@node Speed of Byte-Code -@section Performance of Byte-Compiled Code - - A byte-compiled function is not as efficient as a primitive function -written in C, but runs much faster than the version written in Lisp. -Here is an example: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) -@result{} silly-loop -@end group - -@group -(silly-loop 50000000) -@result{} ("Wed Mar 11 21:10:19 2009" - "Wed Mar 11 21:10:41 2009") ; @r{22 seconds} -@end group - -@group -(byte-compile 'silly-loop) -@result{} @r{[Compiled code not shown]} -@end group - -@group -(silly-loop 50000000) -@result{} ("Wed Mar 11 21:12:26 2009" - "Wed Mar 11 21:12:32 2009") ; @r{6 seconds} -@end group -@end example - - In this example, the interpreted code required 22 seconds to run, -whereas the byte-compiled code required 6 seconds. These results are -representative, but actual results will vary greatly. - -@node Compilation Functions -@comment node-name, next, previous, up -@section The Compilation Functions -@cindex compilation functions - - You can byte-compile an individual function or macro definition with -the @code{byte-compile} function. You can compile a whole file with -@code{byte-compile-file}, or several files with -@code{byte-recompile-directory} or @code{batch-byte-compile}. - - The byte compiler produces error messages and warnings about each file -in a buffer called @samp{*Compile-Log*}. These report things in your -program that suggest a problem but are not necessarily erroneous. - -@cindex macro compilation - Be careful when writing macro calls in files that you may someday -byte-compile. Macro calls are expanded when they are compiled, so the -macros must already be defined for proper compilation. For more -details, see @ref{Compiling Macros}. If a program does not work the -same way when compiled as it does when interpreted, erroneous macro -definitions are one likely cause (@pxref{Problems with Macros}). -Inline (@code{defsubst}) functions are less troublesome; if you -compile a call to such a function before its definition is known, the -call will still work right, it will just run slower. - - Normally, compiling a file does not evaluate the file's contents or -load the file. But it does execute any @code{require} calls at top -level in the file. One way to ensure that necessary macro definitions -are available during compilation is to require the file that defines -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@defun byte-compile symbol -This function byte-compiles the function definition of @var{symbol}, -replacing the previous definition with the compiled one. The function -definition of @var{symbol} must be the actual code for the function; -i.e., the compiler does not follow indirection to another symbol. -@code{byte-compile} returns the new, compiled definition of -@var{symbol}. - - If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. Lisp records -only one function definition for any symbol, and if that is already -compiled, non-compiled code is not available anywhere. So there is no -way to ``compile the same definition again.'' - -@example -@group -(defun factorial (integer) - "Compute factorial of INTEGER." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) -@result{} factorial -@end group - -@group -(byte-compile 'factorial) -@result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] -@end group -@end example - -@noindent -The result is a byte-code function object. The string it contains is -the actual byte-code; each character in it is an instruction or an -operand of an instruction. The vector contains all the constants, -variable names and function names used by the function, except for -certain primitives that are coded as special instructions. - -If the argument to @code{byte-compile} is a @code{lambda} expression, -it returns the corresponding compiled code, but does not store -it anywhere. -@end defun - -@deffn Command compile-defun &optional arg -This command reads the defun containing point, compiles it, and -evaluates the result. If you use this on a defun that is actually a -function definition, the effect is to install a compiled version of that -function. - -@code{compile-defun} normally displays the result of evaluation in the -echo area, but if @var{arg} is non-@code{nil}, it inserts the result -in the current buffer after the form it compiled. -@end deffn - -@deffn Command byte-compile-file filename &optional load -This function compiles a file of Lisp code named @var{filename} into a -file of byte-code. The output file's name is made by changing the -@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in -@samp{.el}, it adds @samp{.elc} to the end of @var{filename}. - -Compilation works by reading the input file one form at a time. If it -is a definition of a function or macro, the compiled function or macro -definition is written out. Other forms are batched together, then each -batch is compiled, and written so that its compiled code will be -executed when the file is read. All comments are discarded when the -input file is read. - -This command returns @code{t} if there were no errors and @code{nil} -otherwise. When called interactively, it prompts for the file name. - -If @var{load} is non-@code{nil}, this command loads the compiled file -after compiling it. Interactively, @var{load} is the prefix argument. - -@example -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -@end group - -@group -(byte-compile-file "~/emacs/push.el") - @result{} t -@end group - -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el --rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc -@end group -@end example -@end deffn - -@deffn Command byte-recompile-directory directory &optional flag force -@cindex library compilation -This command recompiles every @samp{.el} file in @var{directory} (or -its subdirectories) that needs recompilation. A file needs -recompilation if a @samp{.elc} file exists but is older than the -@samp{.el} file. - -When a @samp{.el} file has no corresponding @samp{.elc} file, -@var{flag} says what to do. If it is @code{nil}, this command ignores -these files. If @var{flag} is 0, it compiles them. If it is neither -@code{nil} nor 0, it asks the user whether to compile each such file, -and asks about each subdirectory as well. - -Interactively, @code{byte-recompile-directory} prompts for -@var{directory} and @var{flag} is the prefix argument. - -If @var{force} is non-@code{nil}, this command recompiles every -@samp{.el} file that has a @samp{.elc} file. - -The returned value is unpredictable. -@end deffn - -@defun batch-byte-compile &optional noforce -This function runs @code{byte-compile-file} on files specified on the -command line. This function must be used only in a batch execution of -Emacs, as it kills Emacs on completion. An error in one file does not -prevent processing of subsequent files, but no output file will be -generated for it, and the Emacs process will terminate with a nonzero -status code. - -If @var{noforce} is non-@code{nil}, this function does not recompile -files that have an up-to-date @samp{.elc} file. - -@example -% emacs -batch -f batch-byte-compile *.el -@end example -@end defun - -@defun byte-code code-string data-vector max-stack -@cindex byte-code interpreter -This function actually interprets byte-code. A byte-compiled function -is actually defined with a body that calls @code{byte-code}. Don't call -this function yourself---only the byte compiler knows how to generate -valid calls to this function. - -In Emacs version 18, byte-code was always executed by way of a call to -the function @code{byte-code}. Nowadays, byte-code is usually executed -as part of a byte-code function object, and only rarely through an -explicit call to @code{byte-code}. -@end defun - -@node Docs and Compilation -@section Documentation Strings and Compilation -@cindex dynamic loading of documentation - - Functions and variables loaded from a byte-compiled file access their -documentation strings dynamically from the file whenever needed. This -saves space within Emacs, and makes loading faster because the -documentation strings themselves need not be processed while loading the -file. Actual access to the documentation strings becomes slower as a -result, but this normally is not enough to bother users. - - Dynamic access to documentation strings does have drawbacks: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer access the documentation strings for the functions and variables -in the file. - -@item -If you alter the compiled file (such as by compiling a new version), -then further access to documentation strings in this file will -probably give nonsense results. -@end itemize - - If your site installs Emacs following the usual procedures, these -problems will never normally occur. Installing a new version uses a new -directory with a different name; as long as the old version remains -installed, its files will remain unmodified in the places where they are -expected to be. - - However, if you have built Emacs yourself and use it from the -directory where you built it, you will experience this problem -occasionally if you edit and recompile Lisp files. When it happens, you -can cure the problem by reloading the file after recompiling it. - - You can turn off this feature at compile time by setting -@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful -mainly if you expect to change the file, and you want Emacs processes -that have already loaded it to keep working when the file changes. -You can do this globally, or for one source file by specifying a -file-local binding for the variable. One way to do that is by adding -this string to the file's first line: - -@example --*-byte-compile-dynamic-docstrings: nil;-*- -@end example - -@defvar byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. -@end defvar - -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} - The dynamic documentation string feature writes compiled files that -use a special Lisp reader construct, @samp{#@@@var{count}}. This -construct skips the next @var{count} characters. It also uses the -@samp{#$} construct, which stands for ``the name of this file, as a -string.'' It is usually best not to use these constructs in Lisp source -files, since they are not designed to be clear to humans reading the -file. - -@node Dynamic Loading -@section Dynamic Loading of Individual Functions - -@cindex dynamic loading of functions -@cindex lazy loading - When you compile a file, you can optionally enable the @dfn{dynamic -function loading} feature (also known as @dfn{lazy loading}). With -dynamic function loading, loading the file doesn't fully read the -function definitions in the file. Instead, each function definition -contains a place-holder which refers to the file. The first time each -function is called, it reads the full definition from the file, to -replace the place-holder. - - The advantage of dynamic function loading is that loading the file -becomes much faster. This is a good thing for a file which contains -many separate user-callable functions, if using one of them does not -imply you will probably also use the rest. A specialized mode which -provides many keyboard commands often has that usage pattern: a user may -invoke the mode, but use only a few of the commands it provides. - - The dynamic loading feature has certain disadvantages: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer load the remaining function definitions not already loaded. - -@item -If you alter the compiled file (such as by compiling a new version), -then trying to load any function not already loaded will usually yield -nonsense results. -@end itemize - - These problems will never happen in normal circumstances with -installed Emacs files. But they are quite likely to happen with Lisp -files that you are changing. The easiest way to prevent these problems -is to reload the new compiled file immediately after each recompilation. - - The byte compiler uses the dynamic function loading feature if the -variable @code{byte-compile-dynamic} is non-@code{nil} at compilation -time. Do not set this variable globally, since dynamic loading is -desirable only for certain files. Instead, enable the feature for -specific source files with file-local variable bindings. For example, -you could do it by writing this text in the source file's first line: - -@example --*-byte-compile-dynamic: t;-*- -@end example - -@defvar byte-compile-dynamic -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic function loading. -@end defvar - -@defun fetch-bytecode function -If @var{function} is a byte-code function object, this immediately -finishes loading the byte code of @var{function} from its -byte-compiled file, if it is not fully loaded already. Otherwise, -it does nothing. It always returns @var{function}. -@end defun - -@node Eval During Compile -@section Evaluation During Compilation - - These features permit you to write code to be evaluated during -compilation of a program. - -@defspec eval-and-compile body@dots{} -This form marks @var{body} to be evaluated both when you compile the -containing code and when you run it (whether compiled or not). - -You can get a similar result by putting @var{body} in a separate file -and referring to that file with @code{require}. That method is -preferable when @var{body} is large. Effectively @code{require} is -automatically @code{eval-and-compile}, the package is loaded both when -compiling and executing. - -@code{autoload} is also effectively @code{eval-and-compile} too. It's -recognized when compiling, so uses of such a function don't produce -``not known to be defined'' warnings. - -Most uses of @code{eval-and-compile} are fairly sophisticated. - -If a macro has a helper function to build its result, and that macro -is used both locally and outside the package, then -@code{eval-and-compile} should be used to get the helper both when -compiling and then later when running. - -If functions are defined programmatically (with @code{fset} say), then -@code{eval-and-compile} can be used to have that done at compile-time -as well as run-time, so calls to those functions are checked (and -warnings about ``not known to be defined'' suppressed). -@end defspec - -@defspec eval-when-compile body@dots{} -This form marks @var{body} to be evaluated at compile time but not when -the compiled program is loaded. The result of evaluation by the -compiler becomes a constant which appears in the compiled program. If -you load the source file, rather than compiling it, @var{body} is -evaluated normally. - -@cindex compile-time constant -If you have a constant that needs some calculation to produce, -@code{eval-when-compile} can do that at compile-time. For example, - -@lisp -(defvar my-regexp - (eval-when-compile (regexp-opt '("aaa" "aba" "abb")))) -@end lisp - -@cindex macros, at compile time -If you're using another package, but only need macros from it (the -byte compiler will expand those), then @code{eval-when-compile} can be -used to load it for compiling, but not executing. For example, - -@lisp -(eval-when-compile - (require 'my-macro-package)) ;; only macros needed from this -@end lisp - -The same sort of thing goes for macros and @code{defsubst} functions -defined locally and only for use within the file. They are needed for -compiling the file, but in most cases they are not needed for -execution of the compiled file. For example, - -@lisp -(eval-when-compile - (unless (fboundp 'some-new-thing) - (defmacro 'some-new-thing () - (compatibility code)))) -@end lisp - -@noindent -This is often good for code that's only a fallback for compatibility -with other versions of Emacs. - -@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common -Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the -Common Lisp @samp{#.} reader macro (but not when interpreting) is closer -to what @code{eval-when-compile} does. -@end defspec - -@node Compiler Errors -@section Compiler Errors -@cindex compiler errors - - Byte compilation outputs all errors and warnings into the buffer -@samp{*Compile-Log*}. The messages include file names and line -numbers that identify the location of the problem. The usual Emacs -commands for operating on compiler diagnostics work properly on -these messages. - - However, the warnings about functions that were used but not -defined are always ``located'' at the end of the file, so these -commands won't find the places they are really used. To do that, -you must search for the function names. - - You can suppress the compiler warning for calling an undefined -function @var{func} by conditionalizing the function call on an -@code{fboundp} test, like this: - -@example -(if (fboundp '@var{func}) ...(@var{func} ...)...) -@end example - -@noindent -The call to @var{func} must be in the @var{then-form} of the -@code{if}, and @var{func} must appear quoted in the call to -@code{fboundp}. (This feature operates for @code{cond} as well.) - - You can tell the compiler that a function is defined using -@code{declare-function} (@pxref{Declaring Functions}). Likewise, you -can tell the compiler that a variable is defined using @code{defvar} -with no initial value. - - You can suppress the compiler warning for a specific use of an -undefined variable @var{variable} by conditionalizing its use on a -@code{boundp} test, like this: - -@example -(if (boundp '@var{variable}) ...@var{variable}...) -@end example - -@noindent -The reference to @var{variable} must be in the @var{then-form} of the -@code{if}, and @var{variable} must appear quoted in the call to -@code{boundp}. - - You can suppress any and all compiler warnings within a certain -expression using the construct @code{with-no-warnings}: - -@c This is implemented with a defun, but conceptually it is -@c a special form. - -@defspec with-no-warnings body@dots{} -In execution, this is equivalent to @code{(progn @var{body}...)}, -but the compiler does not issue warnings for anything that occurs -inside @var{body}. - -We recommend that you use this construct around the smallest -possible piece of code, to avoid missing possible warnings other than one -one you intend to suppress. -@end defspec - - More precise control of warnings is possible by setting the variable -@code{byte-compile-warnings}. - -@node Byte-Code Objects -@section Byte-Code Function Objects -@cindex compiled function -@cindex byte-code function - - Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. - - Internally, a byte-code function object is much like a vector; -however, the evaluator handles this data type specially when it appears -as a function to be called. The printed representation for a byte-code -function object is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. - - A byte-code function object must have at least four elements; there is -no maximum number, but only the first six elements have any normal use. -They are: - -@table @var -@item arglist -The list of argument symbols. - -@item byte-code -The string containing the byte-code instructions. - -@item constants -The vector of Lisp objects referenced by the byte code. These include -symbols used as function names and variable names. - -@item stacksize -The maximum stack size this function needs. - -@item docstring -The documentation string (if any); otherwise, @code{nil}. The value may -be a number or a list, in case the documentation string is stored in a -file. Use the function @code{documentation} to get the real -documentation string (@pxref{Accessing Documentation}). - -@item interactive -The interactive spec (if any). This can be a string or a Lisp -expression. It is @code{nil} for a function that isn't interactive. -@end table - -Here's an example of a byte-code function object, in printed -representation. It is the definition of the command -@code{backward-sexp}. - -@example -#[(&optional arg) - "^H\204^F^@@\301^P\302^H[!\207" - [arg 1 forward-sexp] - 2 - 254435 - "p"] -@end example - - The primitive way to create a byte-code object is with -@code{make-byte-code}: - -@defun make-byte-code &rest elements -This function constructs and returns a byte-code function object -with @var{elements} as its elements. -@end defun - - You should not try to come up with the elements for a byte-code -function yourself, because if they are inconsistent, Emacs may crash -when you call the function. Always leave it to the byte compiler to -create these objects; it makes the elements consistent (we hope). - - You can access the elements of a byte-code object using @code{aref}; -you can also use @code{vconcat} to create a vector with the same -elements. - -@node Disassembly -@section Disassembled Byte-Code -@cindex disassembled byte-code - - People do not write byte-code; that job is left to the byte -compiler. But we provide a disassembler to satisfy a cat-like -curiosity. The disassembler converts the byte-compiled code into -human-readable form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - -@deffn Command disassemble object &optional buffer-or-name -This command displays the disassembled code for @var{object}. In -interactive use, or if @var{buffer-or-name} is @code{nil} or omitted, -the output goes in a buffer named @samp{*Disassemble*}. If -@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the -name of an existing buffer. Then the output goes there, at point, and -point is left before the output. - -The argument @var{object} can be a function name, a lambda expression -or a byte-code object. If it is a lambda expression, @code{disassemble} -compiles it and disassembles the resulting compiled code. -@end deffn - - Here are two examples of using the @code{disassemble} function. We -have added explanatory comments to help you relate the byte-code to the -Lisp source; these do not appear in the output of @code{disassemble}. - -@example -@group -(defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - @result{} factorial -@end group - -@group -(factorial 4) - @result{} 24 -@end group - -@group -(disassemble 'factorial) - @print{} byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) -@end group - -@group -0 varref integer ; @r{Get the value of @code{integer}} - ; @r{and push it onto the stack.} -1 constant 1 ; @r{Push 1 onto stack.} -@end group - -@group -2 eqlsign ; @r{Pop top two values off stack, compare} - ; @r{them, and push result onto stack.} -@end group - -@group -3 goto-if-nil 1 ; @r{Pop and test top of stack;} - ; @r{if @code{nil}, go to 1,} - ; @r{else continue.} -6 constant 1 ; @r{Push 1 onto top of stack.} -7 return ; @r{Return the top element} - ; @r{of the stack.} -@end group - -@group -8:1 varref integer ; @r{Push value of @code{integer} onto stack.} -9 constant factorial ; @r{Push @code{factorial} onto stack.} -10 varref integer ; @r{Push value of @code{integer} onto stack.} -11 sub1 ; @r{Pop @code{integer}, decrement value,} - ; @r{push new value onto stack.} -12 call 1 ; @r{Call function @code{factorial} using} - ; @r{the first (i.e., the top) element} - ; @r{of the stack as the argument;} - ; @r{push returned value onto stack.} -@end group - -@group -13 mult ; @r{Pop top two values off stack, multiply} - ; @r{them, and push result onto stack.} -14 return ; @r{Return the top element of stack.} -@end group -@end example - -The @code{silly-loop} function is somewhat more complex: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - @result{} silly-loop -@end group - -@group -(disassemble 'silly-loop) - @print{} byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) - -0 constant current-time-string ; @r{Push} - ; @r{@code{current-time-string}} - ; @r{onto top of stack.} -@end group - -@group -1 call 0 ; @r{Call @code{current-time-string}} - ; @r{with no argument,} - ; @r{pushing result onto stack.} -@end group - -@group -2 varbind t1 ; @r{Pop stack and bind @code{t1}} - ; @r{to popped value.} -@end group - -@group -3:1 varref n ; @r{Get value of @code{n} from} - ; @r{the environment and push} - ; @r{the value onto the stack.} -4 sub1 ; @r{Subtract 1 from top of stack.} -@end group - -@group -5 dup ; @r{Duplicate the top of the stack;} - ; @r{i.e., copy the top of} - ; @r{the stack and push the} - ; @r{copy onto the stack.} -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} - - ; @r{In effect, the sequence @code{dup varset}} - ; @r{copies the top of the stack} - ; @r{into the value of @code{n}} - ; @r{without popping it.} -@end group - -@group -7 constant 0 ; @r{Push 0 onto stack.} -8 gtr ; @r{Pop top two values off stack,} - ; @r{test if @var{n} is greater than 0} - ; @r{and push result onto stack.} -@end group - -@group -9 goto-if-not-nil 1 ; @r{Goto 1 if @code{n} > 0} - ; @r{(this continues the while loop)} - ; @r{else continue.} -@end group - -@group -12 varref t1 ; @r{Push value of @code{t1} onto stack.} -13 constant current-time-string ; @r{Push @code{current-time-string}} - ; @r{onto top of stack.} -14 call 0 ; @r{Call @code{current-time-string} again.} -@end group - -@group -15 unbind 1 ; @r{Unbind @code{t1} in local environment.} -16 list2 ; @r{Pop top two elements off stack,} - ; @r{create a list of them,} - ; @r{and push list onto stack.} -17 return ; @r{Return value of the top of stack.} -@end group -@end example - - -@ignore - arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289 -@end ignore diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi deleted file mode 100644 index 41f844b4e21..00000000000 --- a/doc/lispref/control.texi +++ /dev/null @@ -1,1311 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/control -@node Control Structures, Variables, Evaluation, Top -@chapter Control Structures -@cindex special forms for control structures -@cindex control structures - - A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). -We control the order of execution of these forms by enclosing them in -@dfn{control structures}. Control structures are special forms which -control when, whether, or how many times to execute the forms they -contain. - -@cindex textual order - The simplest order of execution is sequential execution: first form -@var{a}, then form @var{b}, and so on. This is what happens when you -write several forms in succession in the body of a function, or at top -level in a file of Lisp code---the forms are executed in the order -written. We call this @dfn{textual order}. For example, if a function -body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}. The result of -evaluating @var{b} becomes the value of the function. - - Explicit control structures make possible an order of execution other -than sequential. - - Emacs Lisp provides several kinds of control structure, including -other varieties of sequencing, conditionals, iteration, and (controlled) -jumps---all discussed below. The built-in control structures are -special forms since their subforms are not necessarily evaluated or not -evaluated sequentially. You can use macros to define your own control -structure constructs (@pxref{Macros}). - -@menu -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. -@end menu - -@node Sequencing -@section Sequencing - - Evaluating forms in the order they appear is the most common way -control passes from one form to another. In some contexts, such as in a -function body, this happens automatically. Elsewhere you must use a -control structure construct to do this: @code{progn}, the simplest -control construct of Lisp. - - A @code{progn} special form looks like this: - -@example -@group -(progn @var{a} @var{b} @var{c} @dots{}) -@end group -@end example - -@noindent -and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in -that order. These forms are called the @dfn{body} of the @code{progn} form. -The value of the last form in the body becomes the value of the entire -@code{progn}. @code{(progn)} returns @code{nil}. - -@cindex implicit @code{progn} - In the early days of Lisp, @code{progn} was the only way to execute -two or more forms in succession and use the value of the last of them. -But programmers found they often needed to use a @code{progn} in the -body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': -several forms are allowed just as in the body of an actual @code{progn}. -Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as much as it was many years ago. -It is needed now most often inside an @code{unwind-protect}, @code{and}, -@code{or}, or in the @var{then}-part of an @code{if}. - -@defspec progn forms@dots{} -This special form evaluates all of the @var{forms}, in textual -order, returning the result of the final form. - -@example -@group -(progn (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The third form" -@end group -@end example -@end defspec - - Two other control constructs likewise evaluate a series of forms but return -a different value: - -@defspec prog1 form1 forms@dots{} -This special form evaluates @var{form1} and all of the @var{forms}, in -textual order, returning the result of @var{form1}. - -@example -@group -(prog1 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The first form" -@end group -@end example - -Here is a way to remove the first element from a list in the variable -@code{x}, then return the value of that former element: - -@example -(prog1 (car x) (setq x (cdr x))) -@end example -@end defspec - -@defspec prog2 form1 form2 forms@dots{} -This special form evaluates @var{form1}, @var{form2}, and all of the -following @var{forms}, in textual order, returning the result of -@var{form2}. - -@example -@group -(prog2 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The second form" -@end group -@end example -@end defspec - -@node Conditionals -@section Conditionals -@cindex conditional evaluation - - Conditional control structures choose among alternatives. Emacs Lisp -has four conditional forms: @code{if}, which is much the same as in -other languages; @code{when} and @code{unless}, which are variants of -@code{if}; and @code{cond}, which is a generalized case statement. - -@defspec if condition then-form else-forms@dots{} -@code{if} chooses between the @var{then-form} and the @var{else-forms} -based on the value of @var{condition}. If the evaluated @var{condition} is -non-@code{nil}, @var{then-form} is evaluated and the result returned. -Otherwise, the @var{else-forms} are evaluated in textual order, and the -value of the last one is returned. (The @var{else} part of @code{if} is -an example of an implicit @code{progn}. @xref{Sequencing}.) - -If @var{condition} has the value @code{nil}, and no @var{else-forms} are -given, @code{if} returns @code{nil}. - -@code{if} is a special form because the branch that is not selected is -never evaluated---it is ignored. Thus, in the example below, -@code{true} is not printed because @code{print} is never called. - -@example -@group -(if nil - (print 'true) - 'very-false) -@result{} very-false -@end group -@end example -@end defspec - -@defmac when condition then-forms@dots{} -This is a variant of @code{if} where there are no @var{else-forms}, -and possibly several @var{then-forms}. In particular, - -@example -(when @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} (progn @var{a} @var{b} @var{c}) nil) -@end example -@end defmac - -@defmac unless condition forms@dots{} -This is a variant of @code{if} where there is no @var{then-form}: - -@example -(unless @var{condition} @var{a} @var{b} @var{c}) -@end example - -@noindent -is entirely equivalent to - -@example -(if @var{condition} nil - @var{a} @var{b} @var{c}) -@end example -@end defmac - -@defspec cond clause@dots{} -@code{cond} chooses among an arbitrary number of alternatives. Each -@var{clause} in the @code{cond} must be a list. The @sc{car} of this -list is the @var{condition}; the remaining elements, if any, the -@var{body-forms}. Thus, a clause looks like this: - -@example -(@var{condition} @var{body-forms}@dots{}) -@end example - -@code{cond} tries the clauses in textual order, by evaluating the -@var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and the value of the last of @var{body-forms} becomes -the value of the @code{cond}. The remaining clauses are ignored. - -If the value of @var{condition} is @code{nil}, the clause ``fails,'' so -the @code{cond} moves on to the following clause, trying its -@var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. - -A clause may also look like this: - -@example -(@var{condition}) -@end example - -@noindent -Then, if @var{condition} is non-@code{nil} when tested, the value of -@var{condition} becomes the value of the @code{cond} form. - -The following example has four clauses, which test for the cases where -the value of @code{x} is a number, string, buffer and symbol, -respectively: - -@example -@group -(cond ((numberp x) x) - ((stringp x) x) - ((bufferp x) - (setq temporary-hack x) ; @r{multiple body-forms} - (buffer-name x)) ; @r{in one clause} - ((symbolp x) (symbol-value x))) -@end group -@end example - -Often we want to execute the last clause whenever none of the previous -clauses was successful. To do this, we use @code{t} as the -@var{condition} of the last clause, like this: @code{(t -@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is -never @code{nil}, so this clause never fails, provided the @code{cond} -gets to it at all. - -For example, - -@example -@group -(setq a 5) -(cond ((eq a 'hack) 'foo) - (t "default")) -@result{} "default" -@end group -@end example - -@noindent -This @code{cond} expression returns @code{foo} if the value of @code{a} -is @code{hack}, and returns the string @code{"default"} otherwise. -@end defspec - -Any conditional construct can be expressed with @code{cond} or with -@code{if}. Therefore, the choice between them is a matter of style. -For example: - -@example -@group -(if @var{a} @var{b} @var{c}) -@equiv{} -(cond (@var{a} @var{b}) (t @var{c})) -@end group -@end example - -@node Combining Conditions -@section Constructs for Combining Conditions - - This section describes three constructs that are often used together -with @code{if} and @code{cond} to express complicated conditions. The -constructs @code{and} and @code{or} can also be used individually as -kinds of multiple conditional constructs. - -@defun not condition -This function tests for the falsehood of @var{condition}. It returns -@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. -The function @code{not} is identical to @code{null}, and we recommend -using the name @code{null} if you are testing for an empty list. -@end defun - -@defspec and conditions@dots{} -The @code{and} special form tests whether all the @var{conditions} are -true. It works by evaluating the @var{conditions} one by one in the -order written. - -If any of the @var{conditions} evaluates to @code{nil}, then the result -of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns @code{nil} right away, ignoring -the remaining @var{conditions}. - -If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. Just -@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate -because all the @var{conditions} turned out non-@code{nil}. (Think -about it; which one did not?) - -Here is an example. The first condition returns the integer 1, which is -not @code{nil}. Similarly, the second condition returns the integer 2, -which is not @code{nil}. The third condition is @code{nil}, so the -remaining condition is never evaluated. - -@example -@group -(and (print 1) (print 2) nil (print 3)) - @print{} 1 - @print{} 2 -@result{} nil -@end group -@end example - -Here is a more realistic example of using @code{and}: - -@example -@group -(if (and (consp foo) (eq (car foo) 'x)) - (message "foo is a list starting with x")) -@end group -@end example - -@noindent -Note that @code{(car foo)} is not executed if @code{(consp foo)} returns -@code{nil}, thus avoiding an error. - -@code{and} expressions can also be written using either @code{if} or -@code{cond}. Here's how: - -@example -@group -(and @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(if @var{arg1} (if @var{arg2} @var{arg3})) -@equiv{} -(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) -@end group -@end example -@end defspec - -@defspec or conditions@dots{} -The @code{or} special form tests whether at least one of the -@var{conditions} is true. It works by evaluating all the -@var{conditions} one by one in the order written. - -If any of the @var{conditions} evaluates to a non-@code{nil} value, then -the result of the @code{or} must be non-@code{nil}; so @code{or} returns -right away, ignoring the remaining @var{conditions}. The value it -returns is the non-@code{nil} value of the condition just evaluated. - -If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. Just @code{(or)}, with no -@var{conditions}, returns @code{nil}, appropriate because all the -@var{conditions} turned out @code{nil}. (Think about it; which one -did not?) - -For example, this expression tests whether @code{x} is either -@code{nil} or the integer zero: - -@example -(or (eq x nil) (eq x 0)) -@end example - -Like the @code{and} construct, @code{or} can be written in terms of -@code{cond}. For example: - -@example -@group -(or @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(cond (@var{arg1}) - (@var{arg2}) - (@var{arg3})) -@end group -@end example - -You could almost write @code{or} in terms of @code{if}, but not quite: - -@example -@group -(if @var{arg1} @var{arg1} - (if @var{arg2} @var{arg2} - @var{arg3})) -@end group -@end example - -@noindent -This is not completely equivalent because it can evaluate @var{arg1} or -@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} -@var{arg3})} never evaluates any argument more than once. -@end defspec - -@node Iteration -@section Iteration -@cindex iteration -@cindex recursion - - Iteration means executing part of a program repetitively. For -example, you might want to repeat some computation once for each element -of a list, or once for each integer from 0 to @var{n}. You can do this -in Emacs Lisp with the special form @code{while}: - -@defspec while condition forms@dots{} -@code{while} first evaluates @var{condition}. If the result is -non-@code{nil}, it evaluates @var{forms} in textual order. Then it -reevaluates @var{condition}, and if the result is non-@code{nil}, it -evaluates @var{forms} again. This process repeats until @var{condition} -evaluates to @code{nil}. - -There is no limit on the number of iterations that may occur. The loop -will continue until either @var{condition} evaluates to @code{nil} or -until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). - -The value of a @code{while} form is always @code{nil}. - -@example -@group -(setq num 0) - @result{} 0 -@end group -@group -(while (< num 4) - (princ (format "Iteration %d." num)) - (setq num (1+ num))) - @print{} Iteration 0. - @print{} Iteration 1. - @print{} Iteration 2. - @print{} Iteration 3. - @result{} nil -@end group -@end example - -To write a ``repeat...until'' loop, which will execute something on each -iteration and then do the end-test, put the body followed by the -end-test in a @code{progn} as the first argument of @code{while}, as -shown here: - -@example -@group -(while (progn - (forward-line 1) - (not (looking-at "^$")))) -@end group -@end example - -@noindent -This moves forward one line and continues moving by lines until it -reaches an empty line. It is peculiar in that the @code{while} has no -body, just the end test (which also does the real work of moving point). -@end defspec - - The @code{dolist} and @code{dotimes} macros provide convenient ways to -write two common kinds of loops. - -@defmac dolist (var list [result]) body@dots{} -This construct executes @var{body} once for each element of -@var{list}, binding the variable @var{var} locally to hold the current -element. Then it returns the value of evaluating @var{result}, or -@code{nil} if @var{result} is omitted. For example, here is how you -could use @code{dolist} to define the @code{reverse} function: - -@example -(defun reverse (list) - (let (value) - (dolist (elt list value) - (setq value (cons elt value))))) -@end example -@end defmac - -@defmac dotimes (var count [result]) body@dots{} -This construct executes @var{body} once for each integer from 0 -(inclusive) to @var{count} (exclusive), binding the variable @var{var} -to the integer for the current iteration. Then it returns the value -of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: - -@example -(dotimes (i 100) - (insert "I will not obey absurd orders\n")) -@end example -@end defmac - -@node Nonlocal Exits -@section Nonlocal Exits -@cindex nonlocal exits - - A @dfn{nonlocal exit} is a transfer of control from one point in a -program to another remote point. Nonlocal exits can occur in Emacs Lisp -as a result of errors; you can also use them under explicit control. -Nonlocal exits unbind all variable bindings made by the constructs being -exited. - -@menu -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an error happens. -@end menu - -@node Catch and Throw -@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} - - Most control constructs affect only the flow of control within the -construct itself. The function @code{throw} is the exception to this -rule of normal program execution: it performs a nonlocal exit on -request. (There are other exceptions, but they are for error handling -only.) @code{throw} is used inside a @code{catch}, and jumps back to -that @code{catch}. For example: - -@example -@group -(defun foo-outer () - (catch 'foo - (foo-inner))) - -(defun foo-inner () - @dots{} - (if x - (throw 'foo t)) - @dots{}) -@end group -@end example - -@noindent -The @code{throw} form, if executed, transfers control straight back to -the corresponding @code{catch}, which returns immediately. The code -following the @code{throw} is not executed. The second argument of -@code{throw} is used as the return value of the @code{catch}. - - The function @code{throw} finds the matching @code{catch} based on the -first argument: it searches for a @code{catch} whose first argument is -@code{eq} to the one specified in the @code{throw}. If there is more -than one applicable @code{catch}, the innermost one takes precedence. -Thus, in the above example, the @code{throw} specifies @code{foo}, and -the @code{catch} in @code{foo-outer} specifies the same symbol, so that -@code{catch} is the applicable one (assuming there is no other matching -@code{catch} in between). - - Executing @code{throw} exits all Lisp constructs up to the matching -@code{catch}, including function calls. When binding constructs such as -@code{let} or function calls are exited in this way, the bindings are -unbound, just as they are when these constructs exit normally -(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer -and position saved by @code{save-excursion} (@pxref{Excursions}), and -the narrowing status saved by @code{save-restriction} and the window -selection saved by @code{save-window-excursion} (@pxref{Window -Configurations}). It also runs any cleanups established with the -@code{unwind-protect} special form when it exits that form -(@pxref{Cleanups}). - - The @code{throw} need not appear lexically within the @code{catch} -that it jumps to. It can equally well be called from another function -called within the @code{catch}. As long as the @code{throw} takes place -chronologically after entry to the @code{catch}, and chronologically -before exit from it, it has access to that @code{catch}. This is why -@code{throw} can be used in commands such as @code{exit-recursive-edit} -that throw back to the editor command loop (@pxref{Recursive Editing}). - -@cindex CL note---only @code{throw} in Emacs -@quotation -@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: @code{return}, -@code{return-from}, and @code{go}, for example. Emacs Lisp has only -@code{throw}. -@end quotation - -@defspec catch tag body@dots{} -@cindex tag on run time stack -@code{catch} establishes a return point for the @code{throw} function. -The return point is distinguished from other such return points by -@var{tag}, which may be any Lisp object except @code{nil}. The argument -@var{tag} is evaluated normally before the return point is established. - -With the return point in effect, @code{catch} evaluates the forms of the -@var{body} in textual order. If the forms execute normally (without -error or nonlocal exit) the value of the last body form is returned from -the @code{catch}. - -If a @code{throw} is executed during the execution of @var{body}, -specifying the same value @var{tag}, the @code{catch} form exits -immediately; the value it returns is whatever was specified as the -second argument of @code{throw}. -@end defspec - -@defun throw tag value -The purpose of @code{throw} is to return from a return point previously -established with @code{catch}. The argument @var{tag} is used to choose -among the various existing return points; it must be @code{eq} to the value -specified in the @code{catch}. If multiple return points match @var{tag}, -the innermost one is used. - -The argument @var{value} is used as the value to return from that -@code{catch}. - -@kindex no-catch -If no return point is in effect with tag @var{tag}, then a @code{no-catch} -error is signaled with data @code{(@var{tag} @var{value})}. -@end defun - -@node Examples of Catch -@subsection Examples of @code{catch} and @code{throw} - - One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``go to.'') -Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} -varying from 0 to 9: - -@example -@group -(defun search-foo () - (catch 'loop - (let ((i 0)) - (while (< i 10) - (let ((j 0)) - (while (< j 10) - (if (foo i j) - (throw 'loop (list i j))) - (setq j (1+ j)))) - (setq i (1+ i)))))) -@end group -@end example - -@noindent -If @code{foo} ever returns non-@code{nil}, we stop immediately and return a -list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the -@code{catch} returns normally, and the value is @code{nil}, since that -is the result of the @code{while}. - - Here are two tricky examples, slightly different, showing two -return points at once. First, two return points with the same tag, -@code{hack}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'hack)) - 'no) -@print{} yes -@result{} no -@end group -@end example - -@noindent -Since both return points have tags that match the @code{throw}, it goes to -the inner one, the one established in @code{catch2}. Therefore, -@code{catch2} returns normally with value @code{yes}, and this value is -printed. Finally the second body form in the outer @code{catch}, which is -@code{'no}, is evaluated and returned from the outer @code{catch}. - - Now let's change the argument given to @code{catch2}: - -@example -@group -(catch 'hack - (print (catch2 'quux)) - 'no) -@result{} yes -@end group -@end example - -@noindent -We still have two return points, but this time only the outer one has -the tag @code{hack}; the inner one has the tag @code{quux} instead. -Therefore, @code{throw} makes the outer @code{catch} return the value -@code{yes}. The function @code{print} is never called, and the -body-form @code{'no} is never evaluated. - -@node Errors -@subsection Errors -@cindex errors - - When Emacs Lisp attempts to evaluate a form that, for some reason, -cannot be evaluated, it @dfn{signals} an @dfn{error}. - - When an error is signaled, Emacs's default reaction is to print an -error message and terminate execution of the current command. This is -the right thing to do in most cases, such as if you type @kbd{C-f} at -the end of the buffer. - - In complicated programs, simple termination may not be what you want. -For example, the program may have made temporary changes in data -structures, or created temporary buffers that should be deleted before -the program is finished. In such cases, you would use -@code{unwind-protect} to establish @dfn{cleanup expressions} to be -evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may -wish the program to continue execution despite an error in a subroutine. -In these cases, you would use @code{condition-case} to establish -@dfn{error handlers} to recover control in case of error. - - Resist the temptation to use error handling to transfer control from -one part of the program to another; use @code{catch} and @code{throw} -instead. @xref{Catch and Throw}. - -@menu -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. -@end menu - -@node Signaling Errors -@subsubsection How to Signal an Error -@cindex signaling errors - - @dfn{Signaling} an error means beginning error processing. Error -processing normally aborts all or part of the running program and -returns to a point that is set up to handle the error -(@pxref{Processing of Errors}). Here we describe how to signal an -error. - - Most errors are signaled ``automatically'' within Lisp primitives -which you call for other purposes, such as if you try to take the -@sc{car} of an integer or move forward a character at the end of the -buffer. You can also signal errors explicitly with the functions -@code{error} and @code{signal}. - - Quitting, which happens when the user types @kbd{C-g}, is not -considered an error, but it is handled almost like an error. -@xref{Quitting}. - - Every error specifies an error message, one way or another. The -message should state what is wrong (``File does not exist''), not how -things ought to be (``File must exist''). The convention in Emacs -Lisp is that error messages should start with a capital letter, but -should not end with any sort of punctuation. - -@defun error format-string &rest args -This function signals an error with an error message constructed by -applying @code{format} (@pxref{Formatting Strings}) to -@var{format-string} and @var{args}. - -These examples show typical uses of @code{error}: - -@example -@group -(error "That is an error -- try something else") - @error{} That is an error -- try something else -@end group - -@group -(error "You have committed %d errors" 10) - @error{} You have committed 10 errors -@end group -@end example - -@code{error} works by calling @code{signal} with two arguments: the -error symbol @code{error}, and a list containing the string returned by -@code{format}. - -@strong{Warning:} If you want to use your own string as an error message -verbatim, don't just write @code{(error @var{string})}. If @var{string} -contains @samp{%}, it will be interpreted as a format specifier, with -undesirable results. Instead, use @code{(error "%s" @var{string})}. -@end defun - -@defun signal error-symbol data -@anchor{Definition of signal} -This function signals an error named by @var{error-symbol}. The -argument @var{data} is a list of additional Lisp objects relevant to -the circumstances of the error. - -The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol -bearing a property @code{error-conditions} whose value is a list of -condition names. This is how Emacs Lisp classifies different sorts of -errors. @xref{Error Symbols}, for a description of error symbols, -error conditions and condition names. - -If the error is not handled, the two arguments are used in printing -the error message. Normally, this error message is provided by the -@code{error-message} property of @var{error-symbol}. If @var{data} is -non-@code{nil}, this is followed by a colon and a comma separated list -of the unevaluated elements of @var{data}. For @code{error}, the -error message is the @sc{car} of @var{data} (that must be a string). -Subcategories of @code{file-error} are handled specially. - -The number and significance of the objects in @var{data} depends on -@var{error-symbol}. For example, with a @code{wrong-type-argument} error, -there should be two objects in the list: a predicate that describes the type -that was expected, and the object that failed to fit that type. - -Both @var{error-symbol} and @var{data} are available to any error -handlers that handle the error: @code{condition-case} binds a local -variable to a list of the form @code{(@var{error-symbol} .@: -@var{data})} (@pxref{Handling Errors}). - -The function @code{signal} never returns (though in older Emacs versions -it could sometimes return). - -@smallexample -@group -(signal 'wrong-number-of-arguments '(x y)) - @error{} Wrong number of arguments: x, y -@end group - -@group -(signal 'no-such-error '("My unknown error condition")) - @error{} peculiar error: "My unknown error condition" -@end group -@end smallexample -@end defun - -@cindex CL note---no continuable errors -@quotation -@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp -concept of continuable errors. -@end quotation - -@node Processing of Errors -@subsubsection How Emacs Processes Errors - -When an error is signaled, @code{signal} searches for an active -@dfn{handler} for the error. A handler is a sequence of Lisp -expressions designated to be executed if an error happens in part of the -Lisp program. If the error has an applicable handler, the handler is -executed, and control resumes following the handler. The handler -executes in the environment of the @code{condition-case} that -established it; all functions called within that @code{condition-case} -have already been exited, and the handler cannot return to them. - -If there is no applicable handler for the error, it terminates the -current command and returns control to the editor command loop. (The -command loop has an implicit handler for all kinds of errors.) The -command loop's handler uses the error symbol and associated data to -print an error message. You can use the variable -@code{command-error-function} to control how this is done: - -@defvar command-error-function -This variable, if non-@code{nil}, specifies a function to use to -handle errors that return control to the Emacs command loop. The -function should take three arguments: @var{data}, a list of the same -form that @code{condition-case} would bind to its variable; -@var{context}, a string describing the situation in which the error -occurred, or (more often) @code{nil}; and @var{caller}, the Lisp -function which called the primitive that signaled the error. -@end defvar - -@cindex @code{debug-on-error} use -An error that has no explicit handler may call the Lisp debugger. The -debugger is enabled if the variable @code{debug-on-error} (@pxref{Error -Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs -in the environment of the error, so that you can examine values of -variables precisely as they were at the time of the error. - -@node Handling Errors -@subsubsection Writing Code to Handle Errors -@cindex error handler -@cindex handling errors - - The usual effect of signaling an error is to terminate the command -that is running and return immediately to the Emacs editor command loop. -You can arrange to trap errors occurring in a part of your program by -establishing an error handler, with the special form -@code{condition-case}. A simple example looks like this: - -@example -@group -(condition-case nil - (delete-file filename) - (error nil)) -@end group -@end example - -@noindent -This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs@footnote{ -Actually, you should use @code{ignore-errors} in such a simple case; -see below.}. - - The @code{condition-case} construct is often used to trap errors that -are predictable, such as failure to open a file in a call to -@code{insert-file-contents}. It is also used to trap errors that are -totally unpredictable, such as when the program evaluates an expression -read from the user. - - The second argument of @code{condition-case} is called the -@dfn{protected form}. (In the example above, the protected form is a -call to @code{delete-file}.) The error handlers go into effect when -this form begins execution and are deactivated when this form returns. -They remain in effect for all the intervening time. In particular, they -are in effect during the execution of functions called by this form, in -their subroutines, and so on. This is a good thing, since, strictly -speaking, errors can be signaled only by Lisp primitives (including -@code{signal} and @code{error}) called by the protected form, not by the -protected form itself. - - The arguments after the protected form are handlers. Each handler -lists one or more @dfn{condition names} (which are symbols) to specify -which errors it will handle. The error symbol specified when an error -is signaled also defines a list of condition names. A handler applies -to an error if they have any condition names in common. In the example -above, there is one handler, and it specifies one condition name, -@code{error}, which covers all errors. - - The search for an applicable handler checks all the established handlers -starting with the most recently established one. Thus, if two nested -@code{condition-case} forms offer to handle the same error, the inner of -the two gets to handle it. - - If an error is handled by some @code{condition-case} form, this -ordinarily prevents the debugger from being run, even if -@code{debug-on-error} says this error should invoke the debugger. - - If you want to be able to debug errors that are caught by a -@code{condition-case}, set the variable @code{debug-on-signal} to a -non-@code{nil} value. You can also specify that a particular handler -should let the debugger run first, by writing @code{debug} among the -conditions, like this: - -@example -@group -(condition-case nil - (delete-file filename) - ((debug error) nil)) -@end group -@end example - -@noindent -The effect of @code{debug} here is only to prevent -@code{condition-case} from suppressing the call to the debugger. Any -given error will invoke the debugger only if @code{debug-on-error} and -the other usual filtering mechanisms say it should. @xref{Error Debugging}. - - Once Emacs decides that a certain handler handles the error, it -returns control to that handler. To do so, Emacs unbinds all variable -bindings made by binding constructs that are being exited, and -executes the cleanups of all @code{unwind-protect} forms that are -being exited. Once control arrives at the handler, the body of the -handler executes normally. - - After execution of the handler body, execution returns from the -@code{condition-case} form. Because the protected form is exited -completely before execution of the handler, the handler cannot resume -execution at the point of the error, nor can it examine variable -bindings that were made within the protected form. All it can do is -clean up and proceed. - - Error signaling and handling have some resemblance to @code{throw} and -@code{catch} (@pxref{Catch and Throw}), but they are entirely separate -facilities. An error cannot be caught by a @code{catch}, and a -@code{throw} cannot be handled by an error handler (though using -@code{throw} when there is no suitable @code{catch} signals an error -that can be handled). - -@defspec condition-case var protected-form handlers@dots{} -This special form establishes the error handlers @var{handlers} around -the execution of @var{protected-form}. If @var{protected-form} executes -without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has -no effect. The @code{condition-case} form makes a difference when an -error occurs during @var{protected-form}. - -Each of the @var{handlers} is a list of the form @code{(@var{conditions} -@var{body}@dots{})}. Here @var{conditions} is an error condition name -to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: - -@smallexample -@group -(error nil) - -(arith-error (message "Division by zero")) - -((arith-error file-error) - (message - "Either division by zero or failure to open a file")) -@end group -@end smallexample - -Each error that occurs has an @dfn{error symbol} that describes what -kind of error it is. The @code{error-conditions} property of this -symbol is a list of condition names (@pxref{Error Symbols}). Emacs -searches all the active @code{condition-case} forms for a handler that -specifies one or more of these condition names; the innermost matching -@code{condition-case} handles the error. Within this -@code{condition-case}, the first applicable handler handles the error. - -After executing the body of the handler, the @code{condition-case} -returns normally, using the value of the last form in the handler body -as the overall value. - -@cindex error description -The argument @var{var} is a variable. @code{condition-case} does not -bind this variable when executing the @var{protected-form}, only when it -handles an error. At that time, it binds @var{var} locally to an -@dfn{error description}, which is a list giving the particulars of the -error. The error description has the form @code{(@var{error-symbol} -. @var{data})}. The handler can refer to this list to decide what to -do. For example, if the error is for failure opening a file, the file -name is the second element of @var{data}---the third element of the -error description. - -If @var{var} is @code{nil}, that means no variable is bound. Then the -error symbol and associated data are not available to the handler. -@end defspec - -@defun error-message-string error-description -This function returns the error message string for a given error -descriptor. It is useful if you want to handle an error by printing the -usual error message for that error. @xref{Definition of signal}. -@end defun - -@cindex @code{arith-error} example -Here is an example of using @code{condition-case} to handle the error -that results from dividing by zero. The handler displays the error -message (but without a beep), then returns a very large number. - -@smallexample -@group -(defun safe-divide (dividend divisor) - (condition-case err - ;; @r{Protected form.} - (/ dividend divisor) -@end group -@group - ;; @r{The handler.} - (arith-error ; @r{Condition.} - ;; @r{Display the usual message for this error.} - (message "%s" (error-message-string err)) - 1000000))) -@result{} safe-divide -@end group - -@group -(safe-divide 5 0) - @print{} Arithmetic error: (arith-error) -@result{} 1000000 -@end group -@end smallexample - -@noindent -The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, - -@smallexample -@group -(safe-divide nil 3) - @error{} Wrong type argument: number-or-marker-p, nil -@end group -@end smallexample - - Here is a @code{condition-case} that catches all kinds of errors, -including those signaled with @code{error}: - -@smallexample -@group -(setq baz 34) - @result{} 34 -@end group - -@group -(condition-case err - (if (eq baz 35) - t - ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35" 'baz baz)) - ;; @r{This is the handler; it is not a form.} - (error (princ (format "The error was: %s" err)) - 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35") -@result{} 2 -@end group -@end smallexample - -@defmac ignore-errors body@dots{} -This construct executes @var{body}, ignoring any errors that occur -during its execution. If the execution is without error, -@code{ignore-errors} returns the value of the last form in @var{body}; -otherwise, it returns @code{nil}. - -Here's the example at the beginning of this subsection rewritten using -@code{ignore-errors}: - -@smallexample -@group - (ignore-errors - (delete-file filename)) -@end group -@end smallexample -@end defmac - -@node Error Symbols -@subsubsection Error Symbols and Condition Names -@cindex error symbol -@cindex error name -@cindex condition name -@cindex user-defined error -@kindex error-conditions - - When you signal an error, you specify an @dfn{error symbol} to specify -the kind of error you have in mind. Each error has one and only one -error symbol to categorize it. This is the finest classification of -errors defined by the Emacs Lisp language. - - These narrow classifications are grouped into a hierarchy of wider -classes called @dfn{error conditions}, identified by @dfn{condition -names}. The narrowest such classes belong to the error symbols -themselves: each error symbol is also a condition name. There are also -condition names for more extensive classes, up to the condition name -@code{error} which takes in all kinds of errors (but not @code{quit}). -Thus, each error has one or more condition names: @code{error}, the -error symbol if that is distinct from @code{error}, and perhaps some -intermediate classifications. - - In order for a symbol to be an error symbol, it must have an -@code{error-conditions} property which gives a list of condition names. -This list defines the conditions that this kind of error belongs to. -(The error symbol itself, and the symbol @code{error}, should always be -members of this list.) Thus, the hierarchy of condition names is -defined by the @code{error-conditions} properties of the error symbols. -Because quitting is not considered an error, the value of the -@code{error-conditions} property of @code{quit} is just @code{(quit)}. - -@cindex peculiar error - In addition to the @code{error-conditions} list, the error symbol -should have an @code{error-message} property whose value is a string to -be printed when that error is signaled but not handled. If the -error symbol has no @code{error-message} property or if the -@code{error-message} property exists, but is not a string, the error -message @samp{peculiar error} is used. @xref{Definition of signal}. - - Here is how we define a new error symbol, @code{new-error}: - -@example -@group -(put 'new-error - 'error-conditions - '(error my-own-errors new-error)) -@result{} (error my-own-errors new-error) -@end group -@group -(put 'new-error 'error-message "A new error") -@result{} "A new error" -@end group -@end example - -@noindent -This error has three condition names: @code{new-error}, the narrowest -classification; @code{my-own-errors}, which we imagine is a wider -classification; and @code{error}, which is the widest of all. - - The error string should start with a capital letter but it should -not end with a period. This is for consistency with the rest of Emacs. - - Naturally, Emacs will never signal @code{new-error} on its own; only -an explicit call to @code{signal} (@pxref{Definition of signal}) in -your code can do this: - -@example -@group -(signal 'new-error '(x y)) - @error{} A new error: x, y -@end group -@end example - - This error can be handled through any of the three condition names. -This example handles @code{new-error} and any other errors in the class -@code{my-own-errors}: - -@example -@group -(condition-case foo - (bar nil t) - (my-own-errors nil)) -@end group -@end example - - The significant way that errors are classified is by their condition -names---the names used to match errors with handlers. An error symbol -serves only as a convenient way to specify the intended error message -and list of condition names. It would be cumbersome to give -@code{signal} a list of condition names rather than one error symbol. - - By contrast, using only error symbols without condition names would -seriously decrease the power of @code{condition-case}. Condition names -make it possible to categorize errors at various levels of generality -when you write an error handler. Using error symbols alone would -eliminate all but the narrowest level of classification. - - @xref{Standard Errors}, for a list of all the standard error symbols -and their conditions. - -@node Cleanups -@subsection Cleaning Up from Nonlocal Exits - - The @code{unwind-protect} construct is essential whenever you -temporarily put a data structure in an inconsistent state; it permits -you to make the data consistent again in the event of an error or -throw. (Another more specific cleanup construct that is used only for -changes in buffer contents is the atomic change group; @ref{Atomic -Changes}.) - -@defspec unwind-protect body-form cleanup-forms@dots{} -@cindex cleanup forms -@cindex protected forms -@cindex error cleanup -@cindex unwinding -@code{unwind-protect} executes @var{body-form} with a guarantee that -the @var{cleanup-forms} will be evaluated if control leaves -@var{body-form}, no matter how that happens. @var{body-form} may -complete normally, or execute a @code{throw} out of the -@code{unwind-protect}, or cause an error; in all cases, the -@var{cleanup-forms} will be evaluated. - -If @var{body-form} finishes normally, @code{unwind-protect} returns the -value of @var{body-form}, after it evaluates the @var{cleanup-forms}. -If @var{body-form} does not finish, @code{unwind-protect} does not -return any value in the normal sense. - -Only @var{body-form} is protected by the @code{unwind-protect}. If any -of the @var{cleanup-forms} themselves exits nonlocally (via a -@code{throw} or an error), @code{unwind-protect} is @emph{not} -guaranteed to evaluate the rest of them. If the failure of one of the -@var{cleanup-forms} has the potential to cause trouble, then protect -it with another @code{unwind-protect} around that form. - -The number of currently active @code{unwind-protect} forms counts, -together with the number of local variable bindings, against the limit -@code{max-specpdl-size} (@pxref{Definition of max-specpdl-size,, Local -Variables}). -@end defspec - - For example, here we make an invisible buffer for temporary use, and -make sure to kill it before finishing: - -@smallexample -@group -(save-excursion - (let ((buffer (get-buffer-create " *temp*"))) - (set-buffer buffer) - (unwind-protect - @var{body-form} - (kill-buffer buffer)))) -@end group -@end smallexample - -@noindent -You might think that we could just as well write @code{(kill-buffer -(current-buffer))} and dispense with the variable @code{buffer}. -However, the way shown above is safer, if @var{body-form} happens to -get an error after switching to a different buffer! (Alternatively, -you could write another @code{save-excursion} around @var{body-form}, -to ensure that the temporary buffer becomes current again in time to -kill it.) - - Emacs includes a standard macro called @code{with-temp-buffer} which -expands into more or less the code shown above (@pxref{Definition of -with-temp-buffer,, Current Buffer}). Several of the macros defined in -this manual use @code{unwind-protect} in this way. - -@findex ftp-login - Here is an actual example derived from an FTP package. It creates a -process (@pxref{Processes}) to try to establish a connection to a remote -machine. As the function @code{ftp-login} is highly susceptible to -numerous problems that the writer of the function cannot anticipate, it -is protected with a form that guarantees deletion of the process in the -event of failure. Otherwise, Emacs might fill up with useless -subprocesses. - -@smallexample -@group -(let ((win nil)) - (unwind-protect - (progn - (setq process (ftp-setup-buffer host file)) - (if (setq win (ftp-login process host user password)) - (message "Logged in") - (error "Ftp login failed"))) - (or win (and process (delete-process process))))) -@end group -@end smallexample - - This example has a small bug: if the user types @kbd{C-g} to -quit, and the quit happens immediately after the function -@code{ftp-setup-buffer} returns but before the variable @code{process} is -set, the process will not be killed. There is no easy way to fix this bug, -but at least it is very unlikely. - -@ignore - arch-tag: 8abc30d4-4d3a-47f9-b908-e9e971c18c6d -@end ignore diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi deleted file mode 100644 index 8db58eaae49..00000000000 --- a/doc/lispref/customize.texi +++ /dev/null @@ -1,1288 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/customize -@node Customization, Loading, Macros, Top -@chapter Writing Customization Definitions - -@cindex customization definitions - This chapter describes how to declare user options for customization, -and also customization groups for classifying them. We use the term -@dfn{customization item} to include both kinds of customization -definitions---as well as face definitions (@pxref{Defining Faces}). - -@menu -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. -@end menu - -@node Common Keywords -@section Common Item Keywords - -@cindex customization keywords - All kinds of customization declarations (for variables and groups, and -for faces) accept keyword arguments for specifying various information. -This section describes some keywords that apply to all kinds. - - All of these keywords, except @code{:tag}, can be used more than once -in a given item. Each use of the keyword has an independent effect. -The keyword @code{:tag} is an exception because any given item can only -display one name. - -@table @code -@item :tag @var{label} -@kindex tag@r{, customization keyword} -Use @var{label}, a string, instead of the item's name, to label the -item in customization menus and buffers. @strong{Don't use a tag -which is substantially different from the item's real name; that would -cause confusion.} - -@kindex group@r{, customization keyword} -@item :group @var{group} -Put this customization item in group @var{group}. When you use -@code{:group} in a @code{defgroup}, it makes the new group a subgroup of -@var{group}. - -If you use this keyword more than once, you can put a single item into -more than one group. Displaying any of those groups will show this -item. Please don't overdo this, since the result would be annoying. - -@item :link @var{link-data} -@kindex link@r{, customization keyword} -Include an external link after the documentation string for this item. -This is a sentence containing an active field which references some -other documentation. - -There are several alternatives you can use for @var{link-data}: - -@table @code -@item (custom-manual @var{info-node}) -Link to an Info node; @var{info-node} is a string which specifies the -node name, as in @code{"(emacs)Top"}. The link appears as -@samp{[Manual]} in the customization buffer and enters the built-in -Info reader on @var{info-node}. - -@item (info-link @var{info-node}) -Like @code{custom-manual} except that the link appears -in the customization buffer with the Info node name. - -@item (url-link @var{url}) -Link to a web page; @var{url} is a string which specifies the -@acronym{URL}. The link appears in the customization buffer as -@var{url} and invokes the WWW browser specified by -@code{browse-url-browser-function}. - -@item (emacs-commentary-link @var{library}) -Link to the commentary section of a library; @var{library} is a string -which specifies the library name. - -@item (emacs-library-link @var{library}) -Link to an Emacs Lisp library file; @var{library} is a string which -specifies the library name. - -@item (file-link @var{file}) -Link to a file; @var{file} is a string which specifies the name of the -file to visit with @code{find-file} when the user invokes this link. - -@item (function-link @var{function}) -Link to the documentation of a function; @var{function} is a string -which specifies the name of the function to describe with -@code{describe-function} when the user invokes this link. - -@item (variable-link @var{variable}) -Link to the documentation of a variable; @var{variable} is a string -which specifies the name of the variable to describe with -@code{describe-variable} when the user invokes this link. - -@item (custom-group-link @var{group}) -Link to another customization group. Invoking it creates a new -customization buffer for @var{group}. -@end table - -You can specify the text to use in the customization buffer by adding -@code{:tag @var{name}} after the first element of the @var{link-data}; -for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to -the Emacs manual which appears in the buffer as @samp{foo}. - -An item can have more than one external link; however, most items have -none at all. - -@item :load @var{file} -@kindex load@r{, customization keyword} -Load file @var{file} (a string) before displaying this customization -item. Loading is done with @code{load-library}, and only if the file is -not already loaded. - -@item :require @var{feature} -@kindex require@r{, customization keyword} -Execute @code{(require '@var{feature})} when your saved customizations -set the value of this item. @var{feature} should be a symbol. - -The most common reason to use @code{:require} is when a variable enables -a feature such as a minor mode, and just setting the variable won't have -any effect unless the code which implements the mode is loaded. - -@item :version @var{version} -@kindex version@r{, customization keyword} -This keyword specifies that the item was first introduced in Emacs -version @var{version}, or that its default value was changed in that -version. The value @var{version} must be a string. - -@item :package-version '(@var{package} . @var{version}) -@kindex package-version@r{, customization keyword} -This keyword specifies that the item was first introduced in -@var{package} version @var{version}, or that its meaning or default -value was changed in that version. The value of @var{package} is a -symbol and @var{version} is a string. - -This keyword takes priority over @code{:version}. - -@var{package} should be the official name of the package, such as MH-E -or Gnus. If the package @var{package} is released as part of Emacs, -@var{package} and @var{version} should appear in the value of -@code{customize-package-emacs-version-alist}. -@end table - -Packages distributed as part of Emacs that use the -@code{:package-version} keyword must also update the -@code{customize-package-emacs-version-alist} variable. - -@defvar customize-package-emacs-version-alist -This alist provides a mapping for the versions of Emacs that are -associated with versions of a package listed in the -@code{:package-version} keyword. Its elements look like this: - -@example -(@var{package} (@var{pversion} . @var{eversion})@dots{}) -@end example - -For each @var{package}, which is a symbol, there are one or more -elements that contain a package version @var{pversion} with an -associated Emacs version @var{eversion}. These versions are strings. -For example, the MH-E package updates this alist with the following: - -@smallexample -(add-to-list 'customize-package-emacs-version-alist - '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1") - ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1") - ("7.4" . "22.1") ("8.0" . "22.1"))) -@end smallexample - -The value of @var{package} needs to be unique and it needs to match -the @var{package} value appearing in the @code{:package-version} -keyword. Since the user might see the value in a error message, a good -choice is the official name of the package, such as MH-E or Gnus. -@end defvar - -@node Group Definitions -@section Defining Customization Groups -@cindex define customization group -@cindex customization groups, defining - - Each Emacs Lisp package should have one main customization group which -contains all the options, faces and other groups in the package. If the -package has a small number of options and faces, use just one group and -put everything in it. When there are more than twelve or so options and -faces, then you should structure them into subgroups, and put the -subgroups under the package's main customization group. It is OK to -put some of the options and faces in the package's main group alongside -the subgroups. - - The package's main or only group should be a member of one or more of -the standard customization groups. (To display the full list of them, -use @kbd{M-x customize}.) Choose one or more of them (but not too -many), and add your group to each of them using the @code{:group} -keyword. - - The way to declare new customization groups is with @code{defgroup}. - -@defmac defgroup group members doc [keyword value]@dots{} -Declare @var{group} as a customization group containing @var{members}. -Do not quote the symbol @var{group}. The argument @var{doc} specifies -the documentation string for the group. - -The argument @var{members} is a list specifying an initial set of -customization items to be members of the group. However, most often -@var{members} is @code{nil}, and you specify the group's members by -using the @code{:group} keyword when defining those members. - -If you want to specify group members through @var{members}, each element -should have the form @code{(@var{name} @var{widget})}. Here @var{name} -is a symbol, and @var{widget} is a widget type for editing that symbol. -Useful widgets are @code{custom-variable} for a variable, -@code{custom-face} for a face, and @code{custom-group} for a group. - -When you introduce a new group into Emacs, use the @code{:version} -keyword in the @code{defgroup}; then you need not use it for -the individual members of the group. - -In addition to the common keywords (@pxref{Common Keywords}), you can -also use this keyword in @code{defgroup}: - -@table @code -@item :prefix @var{prefix} -@kindex prefix@r{, @code{defgroup} keyword} -If the name of an item in the group starts with @var{prefix}, then the -tag for that item is constructed (by default) by omitting @var{prefix}. - -One group can have any number of prefixes. -@end table -@end defmac - - The prefix-discarding feature is currently turned off, which means -that @code{:prefix} currently has no effect. We did this because we -found that discarding the specified prefixes often led to confusing -names for options. This happened because the people who wrote the -@code{defgroup} definitions for various groups added @code{:prefix} -keywords whenever they make logical sense---that is, whenever the -variables in the library have a common prefix. - - In order to obtain good results with @code{:prefix}, it would be -necessary to check the specific effects of discarding a particular -prefix, given the specific items in a group and their names and -documentation. If the resulting text is not clear, then @code{:prefix} -should not be used in that case. - - It should be possible to recheck all the customization groups, delete -the @code{:prefix} specifications which give unclear results, and then -turn this feature back on, if someone would like to do the work. - -@node Variable Definitions -@section Defining Customization Variables -@cindex define customization options -@cindex customization variables, how to define - - Use @code{defcustom} to declare user-customizable variables. - -@defmac defcustom option standard doc [keyword value]@dots{} -This macro declares @var{option} as a customizable @dfn{user option}. -You should not quote @var{option}. - -This causes the function @code{user-variable-p} to return @code{t} -when given @var{option} as an argument. @xref{Defining Variables}. -The argument @var{doc} specifies the documentation string for the -variable. (Note that there is no need to start @var{doc} with a -@samp{*}.) - -The argument @var{standard} is an expression that specifies the -standard value for @var{option}. Evaluating the @code{defcustom} form -evaluates @var{standard}, but does not necessarily install the -standard value. If @var{option} already has a default value, -@code{defcustom} does not change it. If the user has saved a -customization for @var{option}, @code{defcustom} installs the user's -customized value as @var{option}'s default value. If neither of those -cases applies, @code{defcustom} installs the result of evaluating -@var{standard} as the default value. - -The expression @var{standard} can be evaluated at various other times, -too---whenever the customization facility needs to know @var{option}'s -standard value. So be sure to use an expression which is harmless to -evaluate at any time. We recommend avoiding backquotes in -@var{standard}, because they are not expanded when editing the value, -so list values will appear to have the wrong structure. - -Every @code{defcustom} should specify @code{:group} at least once. - -If you specify the @code{:set} keyword, to make the variable take other -special actions when set through the customization buffer, the -variable's documentation string should tell the user specifically how -to do the same job in hand-written Lisp code. - -When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp -mode (@code{eval-defun}), a special feature of @code{eval-defun} -arranges to set the variable unconditionally, without testing whether -its value is void. (The same feature applies to @code{defvar}.) -@xref{Defining Variables}. - -If you put a @code{defcustom} in a file that is preloaded at dump time -(@pxref{Building Emacs}), and the standard value installed for the -variable at that time might not be correct, use -@code{custom-reevaluate-setting}, described below, to re-evaluate the -standard value during or after Emacs startup. -@end defmac - - @code{defcustom} accepts the following additional keywords: - -@table @code -@item :type @var{type} -Use @var{type} as the data type for this option. It specifies which -values are legitimate, and how to display the value. -@xref{Customization Types}, for more information. - -@item :options @var{value-list} -@kindex options@r{, @code{defcustom} keyword} -Specify the list of reasonable values for use in this -option. The user is not restricted to using only these values, but they -are offered as convenient alternatives. - -This is meaningful only for certain types, currently including -@code{hook}, @code{plist} and @code{alist}. See the definition of the -individual types for a description of how to use @code{:options}. - -@item :set @var{setfunction} -@kindex set@r{, @code{defcustom} keyword} -Specify @var{setfunction} as the way to change the value of this -option. The function @var{setfunction} should take two arguments, a -symbol (the option name) and the new value, and should do whatever is -necessary to update the value properly for this option (which may not -mean simply setting the option as a Lisp variable). The default for -@var{setfunction} is @code{set-default}. - -@item :get @var{getfunction} -@kindex get@r{, @code{defcustom} keyword} -Specify @var{getfunction} as the way to extract the value of this -option. The function @var{getfunction} should take one argument, a -symbol, and should return whatever customize should use as the -``current value'' for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. - -You have to really understand the workings of Custom to use -@code{:get} correctly. It is meant for values that are treated in -Custom as variables but are not actually stored in Lisp variables. It -is almost surely a mistake to specify @code{getfunction} for a value -that really is stored in a Lisp variable. - -@item :initialize @var{function} -@kindex initialize@r{, @code{defcustom} keyword} -@var{function} should be a function used to initialize the variable -when the @code{defcustom} is evaluated. It should take two arguments, -the option name (a symbol) and the value. Here are some predefined -functions meant for use in this way: - -@table @code -@item custom-initialize-set -Use the variable's @code{:set} function to initialize the variable, but -do not reinitialize it if it is already non-void. - -@item custom-initialize-default -Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. - -@item custom-initialize-reset -Always use the @code{:set} function to initialize the variable. If -the variable is already non-void, reset it by calling the @code{:set} -function using the current value (returned by the @code{:get} method). -This is the default @code{:initialize} function. - -@item custom-initialize-changed -Use the @code{:set} function to initialize the variable, if it is -already set or has been customized; otherwise, just use -@code{set-default}. - -@item custom-initialize-safe-set -@itemx custom-initialize-safe-default -These functions behave like @code{custom-initialize-set} -(@code{custom-initialize-default}, respectively), but catch errors. -If an error occurs during initialization, they set the variable to -@code{nil} using @code{set-default}, and throw no error. - -These two functions are only meant for options defined in pre-loaded -files, where some variables or functions used to compute the option's -value may not yet be defined. The option normally gets updated in -@file{startup.el}, ignoring the previously computed value. Because of -this typical usage, the value which these two functions compute -normally only matters when, after startup, one unsets the option's -value and then reevaluates the defcustom. By that time, the necessary -variables and functions will be defined, so there will not be an error. -@end table - -@item :risky @var{value} -@kindex risky@r{, @code{defcustom} keyword} -Set the variable's @code{risky-local-variable} property to -@var{value} (@pxref{File Local Variables}). - -@item :safe @var{function} -@kindex safe@r{, @code{defcustom} keyword} -Set the variable's @code{safe-local-variable} property to -@var{function} (@pxref{File Local Variables}). - -@item :set-after @var{variables} -@kindex set-after@r{, @code{defcustom} keyword} -When setting variables according to saved customizations, make sure to -set the variables @var{variables} before this one; in other words, delay -setting this variable until after those others have been handled. Use -@code{:set-after} if setting this variable won't work properly unless -those other variables already have their intended values. -@end table - - It is useful to specify the @code{:require} keyword for an option -that ``turns on'' a certain feature. This causes Emacs to load the -feature, if it is not already loaded, whenever the option is set. -@xref{Common Keywords}. Here is an example, from the library -@file{saveplace.el}: - -@example -(defcustom save-place nil - "Non-nil means automatically save place in each file..." - :type 'boolean - :require 'saveplace - :group 'save-place) -@end example - -If a customization item has a type such as @code{hook} or -@code{alist}, which supports @code{:options}, you can add additional -values to the list from outside the @code{defcustom} declaration by -calling @code{custom-add-frequent-value}. For example, if you define a -function @code{my-lisp-mode-initialization} intended to be called from -@code{emacs-lisp-mode-hook}, you might want to add that to the list of -reasonable values for @code{emacs-lisp-mode-hook}, but not by editing -its definition. You can do it thus: - -@example -(custom-add-frequent-value 'emacs-lisp-mode-hook - 'my-lisp-mode-initialization) -@end example - -@defun custom-add-frequent-value symbol value -For the customization option @var{symbol}, add @var{value} to the -list of reasonable values. - -The precise effect of adding a value depends on the customization type -of @var{symbol}. -@end defun - -Internally, @code{defcustom} uses the symbol property -@code{standard-value} to record the expression for the standard value, -@code{saved-value} to record the value saved by the user with the -customization buffer, and @code{customized-value} to record the value -set by the user with the customization buffer, but not saved. -@xref{Property Lists}. These properties are lists, the car of which -is an expression that evaluates to the value. - -@defun custom-reevaluate-setting symbol -This function re-evaluates the standard value of @var{symbol}, which -should be a user option declared via @code{defcustom}. (If the -variable was customized, this function re-evaluates the saved value -instead.) This is useful for customizable options that are defined -before their value could be computed correctly, such as variables -defined in packages that are loaded at dump time, but depend on the -run-time information. For example, the value could be a file whose -precise name depends on the hierarchy of files when Emacs runs, or a -name of a program that needs to be searched at run time. - -A good place to put calls to this function is in the function -@code{command-line} that is run during startup (@pxref{Startup Summary}) -or in the various hooks it calls. -@end defun - -@node Customization Types -@section Customization Types - -@cindex customization types - When you define a user option with @code{defcustom}, you must specify -its @dfn{customization type}. That is a Lisp object which describes (1) -which values are legitimate and (2) how to display the value in the -customization buffer for editing. - -@kindex type@r{, @code{defcustom} keyword} - You specify the customization type in @code{defcustom} with the -@code{:type} keyword. The argument of @code{:type} is evaluated, but -only once when the @code{defcustom} is executed, so it isn't useful -for the value to vary. Normally we use a quoted constant. For -example: - -@example -(defcustom diff-command "diff" - "The command to use to run diff." - :type '(string) - :group 'diff) -@end example - - In general, a customization type is a list whose first element is a -symbol, one of the customization type names defined in the following -sections. After this symbol come a number of arguments, depending on -the symbol. Between the type symbol and its arguments, you can -optionally write keyword-value pairs (@pxref{Type Keywords}). - - Some type symbols do not use any arguments; those are called -@dfn{simple types}. For a simple type, if you do not use any -keyword-value pairs, you can omit the parentheses around the type -symbol. For example just @code{string} as a customization type is -equivalent to @code{(string)}. - - All customization types are implemented as widgets; see @ref{Top, , -Introduction, widget, The Emacs Widget Library}, for details. - -@menu -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. -@end menu - -@node Simple Types -@subsection Simple Types - - This section describes all the simple customization types. - -@table @code -@item sexp -The value may be any Lisp object that can be printed and read back. You -can use @code{sexp} as a fall-back for any option, if you don't want to -take the time to work out a more specific type to use. - -@item integer -The value must be an integer, and is represented textually -in the customization buffer. - -@item number -The value must be a number (floating point or integer), and is -represented textually in the customization buffer. - -@item float -The value must be a floating point number, and is represented -textually in the customization buffer. - -@item string -The value must be a string, and the customization buffer shows just the -contents, with no delimiting @samp{"} characters and no quoting with -@samp{\}. - -@item regexp -Like @code{string} except that the string must be a valid regular -expression. - -@item character -The value must be a character code. A character code is actually an -integer, but this type shows the value by inserting the character in the -buffer, rather than by showing the number. - -@item file -The value must be a file name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item (file :must-match t) -The value must be a file name for an existing file, and you can do -completion with @kbd{M-@key{TAB}}. - -@item directory -The value must be a directory name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item hook -The value must be a list of functions (or a single function, but that is -obsolete usage). This customization type is used for hook variables. -You can use the @code{:options} keyword in a hook variable's -@code{defcustom} to specify a list of functions recommended for use in -the hook; see @ref{Variable Definitions}. - -@item alist -The value must be a list of cons-cells, the @sc{car} of each cell -representing a key, and the @sc{cdr} of the same cell representing an -associated value. The user can add and delete key/value pairs, and -edit both the key and the value of each pair. - -You can specify the key and value types like this: - -@smallexample -(alist :key-type @var{key-type} :value-type @var{value-type}) -@end smallexample - -@noindent -where @var{key-type} and @var{value-type} are customization type -specifications. The default key type is @code{sexp}, and the default -value type is @code{sexp}. - -The user can add any key matching the specified key type, but you can -give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys -will always be shown in the customize buffer (together with a suitable -value), with a checkbox to include or exclude or disable the key/value -pair from the alist. The user will not be able to edit the keys -specified by the @code{:options} keyword argument. - -The argument to the @code{:options} keywords should be a list of -specifications for reasonable keys in the alist. Ordinarily, they are -simply atoms, which stand for themselves as. For example: - -@smallexample -:options '("foo" "bar" "baz") -@end smallexample - -@noindent -specifies that there are three ``known'' keys, namely @code{"foo"}, -@code{"bar"} and @code{"baz"}, which will always be shown first. - -You may want to restrict the value type for specific keys, for -example, the value associated with the @code{"bar"} key can only be an -integer. You can specify this by using a list instead of an atom in -the list. The first element will specify the key, like before, while -the second element will specify the value type. For example: - -@smallexample -:options '("foo" ("bar" integer) "baz") -@end smallexample - -Finally, you may want to change how the key is presented. By default, -the key is simply shown as a @code{const}, since the user cannot change -the special keys specified with the @code{:options} keyword. However, -you may want to use a more specialized type for presenting the key, like -@code{function-item} if you know it is a symbol with a function binding. -This is done by using a customization type specification instead of a -symbol for the key. - -@smallexample -:options '("foo" ((function-item some-function) integer) - "baz") -@end smallexample - -Many alists use lists with two elements, instead of cons cells. For -example, - -@smallexample -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE).") -@end smallexample - -@noindent -instead of - -@smallexample -(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) - "Each element is a cons-cell (KEY . VALUE).") -@end smallexample - -Because of the way lists are implemented on top of cons cells, you can -treat @code{list-alist} in the example above as a cons cell alist, where -the value type is a list with a single element containing the real -value. - -@smallexample -(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) - "Each element is a list of the form (KEY VALUE)." - :type '(alist :value-type (group integer))) -@end smallexample - -The @code{group} widget is used here instead of @code{list} only because -the formatting is better suited for the purpose. - -Similarly, you can have alists with more values associated with each -key, using variations of this trick: - -@smallexample -(defcustom person-data '(("brian" 50 t) - ("dorith" 55 nil) - ("ken" 52 t)) - "Alist of basic info about people. -Each element has the form (NAME AGE MALE-FLAG)." - :type '(alist :value-type (group integer boolean))) - -(defcustom pets '(("brian") - ("dorith" "dog" "guppy") - ("ken" "cat")) - "Alist of people's pets. -In an element (KEY . VALUE), KEY is the person's name, -and the VALUE is a list of that person's pets." - :type '(alist :value-type (repeat string))) -@end smallexample - -@item plist -The @code{plist} custom type is similar to the @code{alist} (see above), -except that the information is stored as a property list, i.e. a list of -this form: - -@smallexample -(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) -@end smallexample - -The default @code{:key-type} for @code{plist} is @code{symbol}, -rather than @code{sexp}. - -@item symbol -The value must be a symbol. It appears in the customization buffer as -the name of the symbol. - -@item function -The value must be either a lambda expression or a function name. When -it is a function name, you can do completion with @kbd{M-@key{TAB}}. - -@item variable -The value must be a variable name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item face -The value must be a symbol which is a face name, and you can do -completion with @kbd{M-@key{TAB}}. - -@item boolean -The value is boolean---either @code{nil} or @code{t}. Note that by -using @code{choice} and @code{const} together (see the next section), -you can specify that the value must be @code{nil} or @code{t}, but also -specify the text to describe each value in a way that fits the specific -meaning of the alternative. - -@item coding-system -The value must be a coding-system name, and you can do completion with -@kbd{M-@key{TAB}}. - -@item color -The value must be a valid color name, and you can do completion with -@kbd{M-@key{TAB}}. A sample is provided. -@end table - -@node Composite Types -@subsection Composite Types -@cindex Composite Types (customization) - - When none of the simple types is appropriate, you can use composite -types, which build new types from other types or from specified data. -The specified types or data are called the @dfn{arguments} of the -composite type. The composite type normally looks like this: - -@example -(@var{constructor} @var{arguments}@dots{}) -@end example - -@noindent -but you can also add keyword-value pairs before the arguments, like -this: - -@example -(@var{constructor} @r{@{}@var{keyword} @var{value}@r{@}}@dots{} @var{arguments}@dots{}) -@end example - - Here is a table of constructors and how to use them to write -composite types: - -@table @code -@item (cons @var{car-type} @var{cdr-type}) -The value must be a cons cell, its @sc{car} must fit @var{car-type}, and -its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string -symbol)} is a customization type which matches values such as -@code{("foo" . foo)}. - -In the customization buffer, the @sc{car} and the @sc{cdr} are -displayed and edited separately, each according to the type -that you specify for it. - -@item (list @var{element-types}@dots{}) -The value must be a list with exactly as many elements as the -@var{element-types} given; and each element must fit the -corresponding @var{element-type}. - -For example, @code{(list integer string function)} describes a list of -three elements; the first element must be an integer, the second a -string, and the third a function. - -In the customization buffer, each element is displayed and edited -separately, according to the type specified for it. - -@item (group @var{element-types}@dots{}) -This works like @code{list} except for the formatting -of text in the Custom buffer. @code{list} labels each -element value with its tag; @code{group} does not. - -@item (vector @var{element-types}@dots{}) -Like @code{list} except that the value must be a vector instead of a -list. The elements work the same as in @code{list}. - -@item (choice @var{alternative-types}@dots{}) -The value must fit at least one of @var{alternative-types}. -For example, @code{(choice integer string)} allows either an -integer or a string. - -In the customization buffer, the user selects an alternative -using a menu, and can then edit the value in the usual way for that -alternative. - -Normally the strings in this menu are determined automatically from the -choices; however, you can specify different strings for the menu by -including the @code{:tag} keyword in the alternatives. For example, if -an integer stands for a number of spaces, while a string is text to use -verbatim, you might write the customization type this way, - -@example -(choice (integer :tag "Number of spaces") - (string :tag "Literal text")) -@end example - -@noindent -so that the menu offers @samp{Number of spaces} and @samp{Literal text}. - -In any alternative for which @code{nil} is not a valid value, other than -a @code{const}, you should specify a valid default for that alternative -using the @code{:value} keyword. @xref{Type Keywords}. - -If some values are covered by more than one of the alternatives, -customize will choose the first alternative that the value fits. This -means you should always list the most specific types first, and the -most general last. Here's an example of proper usage: - -@example -(choice (const :tag "Off" nil) - symbol (sexp :tag "Other")) -@end example - -@noindent -This way, the special value @code{nil} is not treated like other -symbols, and symbols are not treated like other Lisp expressions. - -@item (radio @var{element-types}@dots{}) -This is similar to @code{choice}, except that the choices are displayed -using `radio buttons' rather than a menu. This has the advantage of -displaying documentation for the choices when applicable and so is often -a good choice for a choice between constant functions -(@code{function-item} customization types). - -@item (const @var{value}) -The value must be @var{value}---nothing else is allowed. - -The main use of @code{const} is inside of @code{choice}. For example, -@code{(choice integer (const nil))} allows either an integer or -@code{nil}. - -@code{:tag} is often used with @code{const}, inside of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (const :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and @code{foo} means ``ask.'' - -@item (other @var{value}) -This alternative can match any Lisp value, but if the user chooses this -alternative, that selects the value @var{value}. - -The main use of @code{other} is as the last element of @code{choice}. -For example, - -@example -(choice (const :tag "Yes" t) - (const :tag "No" nil) - (other :tag "Ask" foo)) -@end example - -@noindent -describes a variable for which @code{t} means yes, @code{nil} means no, -and anything else means ``ask.'' If the user chooses @samp{Ask} from -the menu of alternatives, that specifies the value @code{foo}; but any -other value (not @code{t}, @code{nil} or @code{foo}) displays as -@samp{Ask}, just like @code{foo}. - -@item (function-item @var{function}) -Like @code{const}, but used for values which are functions. This -displays the documentation string as well as the function name. -The documentation string is either the one you specify with -@code{:doc}, or @var{function}'s own documentation string. - -@item (variable-item @var{variable}) -Like @code{const}, but used for values which are variable names. This -displays the documentation string as well as the variable name. The -documentation string is either the one you specify with @code{:doc}, or -@var{variable}'s own documentation string. - -@item (set @var{types}@dots{}) -The value must be a list, and each element of the list must match one of -the @var{types} specified. - -This appears in the customization buffer as a checklist, so that each of -@var{types} may have either one corresponding element or none. It is -not possible to specify two different elements that match the same one -of @var{types}. For example, @code{(set integer symbol)} allows one -integer and/or one symbol in the list; it does not allow multiple -integers or multiple symbols. As a result, it is rare to use -nonspecific types such as @code{integer} in a @code{set}. - -Most often, the @var{types} in a @code{set} are @code{const} types, as -shown here: - -@example -(set (const :bold) (const :italic)) -@end example - -Sometimes they describe possible elements in an alist: - -@example -(set (cons :tag "Height" (const height) integer) - (cons :tag "Width" (const width) integer)) -@end example - -@noindent -That lets the user specify a height value optionally -and a width value optionally. - -@item (repeat @var{element-type}) -The value must be a list and each element of the list must fit the type -@var{element-type}. This appears in the customization buffer as a -list of elements, with @samp{[INS]} and @samp{[DEL]} buttons for adding -more elements or removing elements. - -@item (restricted-sexp :match-alternatives @var{criteria}) -This is the most general composite type construct. The value may be -any Lisp object that satisfies one of @var{criteria}. @var{criteria} -should be a list, and each element should be one of these -possibilities: - -@itemize @bullet -@item -A predicate---that is, a function of one argument that has no side -effects, and returns either @code{nil} or non-@code{nil} according to -the argument. Using a predicate in the list says that objects for which -the predicate returns non-@code{nil} are acceptable. - -@item -A quoted constant---that is, @code{'@var{object}}. This sort of element -in the list says that @var{object} itself is an acceptable value. -@end itemize - -For example, - -@example -(restricted-sexp :match-alternatives - (integerp 't 'nil)) -@end example - -@noindent -allows integers, @code{t} and @code{nil} as legitimate values. - -The customization buffer shows all legitimate values using their read -syntax, and the user edits them textually. -@end table - - Here is a table of the keywords you can use in keyword-value pairs -in a composite type: - -@table @code -@item :tag @var{tag} -Use @var{tag} as the name of this alternative, for user communication -purposes. This is useful for a type that appears inside of a -@code{choice}. - -@item :match-alternatives @var{criteria} -@kindex match-alternatives@r{, customization keyword} -Use @var{criteria} to match possible values. This is used only in -@code{restricted-sexp}. - -@item :args @var{argument-list} -@kindex args@r{, customization keyword} -Use the elements of @var{argument-list} as the arguments of the type -construct. For instance, @code{(const :args (foo))} is equivalent to -@code{(const foo)}. You rarely need to write @code{:args} explicitly, -because normally the arguments are recognized automatically as -whatever follows the last keyword-value pair. -@end table - -@node Splicing into Lists -@subsection Splicing into Lists - - The @code{:inline} feature lets you splice a variable number of -elements into the middle of a list or vector. You use it in a -@code{set}, @code{choice} or @code{repeat} type which appears among the -element-types of a @code{list} or @code{vector}. - - Normally, each of the element-types in a @code{list} or @code{vector} -describes one and only one element of the list or vector. Thus, if an -element-type is a @code{repeat}, that specifies a list of unspecified -length which appears as one element. - - But when the element-type uses @code{:inline}, the value it matches is -merged directly into the containing sequence. For example, if it -matches a list with three elements, those become three elements of the -overall sequence. This is analogous to using @samp{,@@} in the backquote -construct. - - For example, to specify a list whose first element must be @code{baz} -and whose remaining arguments should be zero or more of @code{foo} and -@code{bar}, use this customization type: - -@example -(list (const baz) (set :inline t (const foo) (const bar))) -@end example - -@noindent -This matches values such as @code{(baz)}, @code{(baz foo)}, @code{(baz bar)} -and @code{(baz foo bar)}. - - When the element-type is a @code{choice}, you use @code{:inline} not -in the @code{choice} itself, but in (some of) the alternatives of the -@code{choice}. For example, to match a list which must start with a -file name, followed either by the symbol @code{t} or two strings, use -this customization type: - -@example -(list file - (choice (const t) - (list :inline t string string))) -@end example - -@noindent -If the user chooses the first alternative in the choice, then the -overall list has two elements and the second element is @code{t}. If -the user chooses the second alternative, then the overall list has three -elements and the second and third must be strings. - -@node Type Keywords -@subsection Type Keywords - -You can specify keyword-argument pairs in a customization type after the -type name symbol. Here are the keywords you can use, and their -meanings: - -@table @code -@item :value @var{default} -This is used for a type that appears as an alternative inside of -@code{choice}; it specifies the default value to use, at first, if and -when the user selects this alternative with the menu in the -customization buffer. - -Of course, if the actual value of the option fits this alternative, it -will appear showing the actual value, not @var{default}. - -If @code{nil} is not a valid value for the alternative, then it is -essential to specify a valid default with @code{:value}. - -@item :format @var{format-string} -@kindex format@r{, customization keyword} -This string will be inserted in the buffer to represent the value -corresponding to the type. The following @samp{%} escapes are available -for use in @var{format-string}: - -@table @samp -@item %[@var{button}%] -Display the text @var{button} marked as a button. The @code{:action} -attribute specifies what the button will do if the user invokes it; -its value is a function which takes two arguments---the widget which -the button appears in, and the event. - -There is no way to specify two different buttons with different -actions. - -@item %@{@var{sample}%@} -Show @var{sample} in a special face specified by @code{:sample-face}. - -@item %v -Substitute the item's value. How the value is represented depends on -the kind of item, and (for variables) on the customization type. - -@item %d -Substitute the item's documentation string. - -@item %h -Like @samp{%d}, but if the documentation string is more than one line, -add an active field to control whether to show all of it or just the -first line. - -@item %t -Substitute the tag here. You specify the tag with the @code{:tag} -keyword. - -@item %% -Display a literal @samp{%}. -@end table - -@item :action @var{action} -@kindex action@r{, customization keyword} -Perform @var{action} if the user clicks on a button. - -@item :button-face @var{face} -@kindex button-face@r{, customization keyword} -Use the face @var{face} (a face name or a list of face names) for button -text displayed with @samp{%[@dots{}%]}. - -@item :button-prefix @var{prefix} -@itemx :button-suffix @var{suffix} -@kindex button-prefix@r{, customization keyword} -@kindex button-suffix@r{, customization keyword} -These specify the text to display before and after a button. -Each can be: - -@table @asis -@item @code{nil} -No text is inserted. - -@item a string -The string is inserted literally. - -@item a symbol -The symbol's value is used. -@end table - -@item :tag @var{tag} -Use @var{tag} (a string) as the tag for the value (or part of the value) -that corresponds to this type. - -@item :doc @var{doc} -@kindex doc@r{, customization keyword} -Use @var{doc} as the documentation string for this value (or part of the -value) that corresponds to this type. In order for this to work, you -must specify a value for @code{:format}, and use @samp{%d} or @samp{%h} -in that value. - -The usual reason to specify a documentation string for a type is to -provide more information about the meanings of alternatives inside a -@code{:choice} type or the parts of some other composite type. - -@item :help-echo @var{motion-doc} -@kindex help-echo@r{, customization keyword} -When you move to this item with @code{widget-forward} or -@code{widget-backward}, it will display the string @var{motion-doc} in -the echo area. In addition, @var{motion-doc} is used as the mouse -@code{help-echo} string and may actually be a function or form evaluated -to yield a help string. If it is a function, it is called with one -argument, the widget. - -@item :match @var{function} -@kindex match@r{, customization keyword} -Specify how to decide whether a value matches the type. The -corresponding value, @var{function}, should be a function that accepts -two arguments, a widget and a value; it should return non-@code{nil} if -the value is acceptable. - -@item :validate @var{function} -Specify a validation function for input. @var{function} takes a -widget as an argument, and should return @code{nil} if the widget's -current value is valid for the widget. Otherwise, it should return -the widget containing the invalid data, and set that widget's -@code{:error} property to a string explaining the error. - -@ignore -@item :indent @var{columns} -Indent this item by @var{columns} columns. The indentation is used for -@samp{%n}, and automatically for group names, for checklists and radio -buttons, and for editable lists. It affects the whole of the -item except for the first line. - -@item :offset @var{extra} -Indent the subitems of this item @var{extra} columns more than this -item itself. By default, subitems are indented the same as their -parent. - -@item :extra-offset @var{n} -Add @var{n} extra spaces to this item's indentation, compared to its -parent's indentation. - -@item :notify @var{function} -Call @var{function} each time the item or a subitem is changed. The -function gets two or three arguments. The first argument is the item -itself, the second argument is the item that was changed, and the -third argument is the event leading to the change, if any. - -@item :menu-tag @var{tag-string} -Use @var{tag-string} in the menu when the widget is used as an option -in a @code{menu-choice} widget. - -@item :menu-tag-get -A function used for finding the tag when the widget is used as an option -in a @code{menu-choice} widget. By default, the tag used will be either the -@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} -representation of the @code{:value} property if not. - -@item :tab-order -Specify the order in which widgets are traversed with -@code{widget-forward} or @code{widget-backward}. This is only partially -implemented. - -@enumerate a -@item -Widgets with tabbing order @code{-1} are ignored. - -@item -(Unimplemented) When on a widget with tabbing order @var{n}, go to the -next widget in the buffer with tabbing order @var{n+1} or @code{nil}, -whichever comes first. - -@item -When on a widget with no tabbing order specified, go to the next widget -in the buffer with a positive tabbing order, or @code{nil} -@end enumerate - -@item :parent -The parent of a nested widget (e.g., a @code{menu-choice} item or an -element of a @code{editable-list} widget). - -@item :sibling-args -This keyword is only used for members of a @code{radio-button-choice} or -@code{checklist}. The value should be a list of extra keyword -arguments, which will be used when creating the @code{radio-button} or -@code{checkbox} associated with this item. -@end ignore -@end table - -@node Defining New Types -@subsection Defining New Types - -In the previous sections we have described how to construct elaborate -type specifications for @code{defcustom}. In some cases you may want -to give such a type specification a name. The obvious case is when -you are using the same type for many user options: rather than repeat -the specification for each option, you can give the type specification -a name, and use that name each @code{defcustom}. The other case is -when a user option's value is a recursive data structure. To make it -possible for a datatype to refer to itself, it needs to have a name. - -Since custom types are implemented as widgets, the way to define a new -customize type is to define a new widget. We are not going to describe -the widget interface here in details, see @ref{Top, , Introduction, -widget, The Emacs Widget Library}, for that. Instead we are going to -demonstrate the minimal functionality needed for defining new customize -types by a simple example. - -@example -(define-widget 'binary-tree-of-string 'lazy - "A binary tree made of cons-cells and strings." - :offset 4 - :tag "Node" - :type '(choice (string :tag "Leaf" :value "") - (cons :tag "Interior" - :value ("" . "") - binary-tree-of-string - binary-tree-of-string))) - -(defcustom foo-bar "" - "Sample variable holding a binary tree of strings." - :type 'binary-tree-of-string) -@end example - -The function to define a new widget is called @code{define-widget}. The -first argument is the symbol we want to make a new widget type. The -second argument is a symbol representing an existing widget, the new -widget is going to be defined in terms of difference from the existing -widget. For the purpose of defining new customization types, the -@code{lazy} widget is perfect, because it accepts a @code{:type} keyword -argument with the same syntax as the keyword argument to -@code{defcustom} with the same name. The third argument is a -documentation string for the new widget. You will be able to see that -string with the @kbd{M-x widget-browse @key{RET} binary-tree-of-string -@key{RET}} command. - -After these mandatory arguments follow the keyword arguments. The most -important is @code{:type}, which describes the data type we want to match -with this widget. Here a @code{binary-tree-of-string} is described as -being either a string, or a cons-cell whose car and cdr are themselves -both @code{binary-tree-of-string}. Note the reference to the widget -type we are currently in the process of defining. The @code{:tag} -attribute is a string to name the widget in the user interface, and the -@code{:offset} argument is there to ensure that child nodes are -indented four spaces relative to the parent node, making the tree -structure apparent in the customization buffer. - -The @code{defcustom} shows how the new widget can be used as an ordinary -customization type. - -The reason for the name @code{lazy} is that the other composite -widgets convert their inferior widgets to internal form when the -widget is instantiated in a buffer. This conversion is recursive, so -the inferior widgets will convert @emph{their} inferior widgets. If -the data structure is itself recursive, this conversion is an infinite -recursion. The @code{lazy} widget prevents the recursion: it convert -its @code{:type} argument only when needed. - -@ignore - arch-tag: d1b8fad3-f48c-4ce4-a402-f73b5ef19bd2 -@end ignore diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi deleted file mode 100644 index c768bbd93cc..00000000000 --- a/doc/lispref/debugging.texi +++ /dev/null @@ -1,823 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/debugging -@node Debugging, Read and Print, Advising Functions, Top -@chapter Debugging Lisp Programs - - There are three ways to investigate a problem in an Emacs Lisp program, -depending on what you are doing with the program when the problem appears. - -@itemize @bullet -@item -If the problem occurs when you run the program, you can use a Lisp -debugger to investigate what is happening during execution. In addition -to the ordinary debugger, Emacs comes with a source-level debugger, -Edebug. This chapter describes both of them. - -@item -If the problem is syntactic, so that Lisp cannot even read the program, -you can use the Emacs facilities for editing Lisp to localize it. - -@item -If the problem occurs when trying to compile the program with the byte -compiler, you need to know how to examine the compiler's input buffer. -@end itemize - -@menu -* Debugger:: How the Emacs Lisp debugger is implemented. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Compilation Errors:: How to find errors that show up in byte compilation. -@end menu - - Another useful debugging tool is the dribble file. When a dribble -file is open, Emacs copies all keyboard input characters to that file. -Afterward, you can examine the file to find out what input was used. -@xref{Terminal Input}. - - For debugging problems in terminal descriptions, the -@code{open-termscript} function can be useful. @xref{Terminal Output}. - -@node Debugger -@section The Lisp Debugger -@cindex debugger for Emacs Lisp -@cindex Lisp debugger -@cindex break - - The ordinary @dfn{Lisp debugger} provides the ability to suspend -evaluation of a form. While evaluation is suspended (a state that is -commonly known as a @dfn{break}), you may examine the run time stack, -examine the values of local or global variables, or change those values. -Since a break is a recursive edit, all the usual editing facilities of -Emacs are available; you can even run programs that will enter the -debugger recursively. @xref{Recursive Editing}. - -@menu -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. -@end menu - -@node Error Debugging -@subsection Entering the Debugger on an Error -@cindex error debugging -@cindex debugging errors - - The most important time to enter the debugger is when a Lisp error -happens. This allows you to investigate the immediate causes of the -error. - - However, entry to the debugger is not a normal consequence of an -error. Many commands frequently cause Lisp errors when invoked -inappropriately, and during ordinary editing it would be very -inconvenient to enter the debugger each time this happens. So if you -want errors to enter the debugger, set the variable -@code{debug-on-error} to non-@code{nil}. (The command -@code{toggle-debug-on-error} provides an easy way to do this.) - -@defopt debug-on-error -This variable determines whether the debugger is called when an error -is signaled and not handled. If @code{debug-on-error} is @code{t}, -all kinds of errors call the debugger, except those listed in -@code{debug-ignored-errors} (see below). If it is @code{nil}, none -call the debugger. (Note that @code{eval-expression-debug-on-error} -affects the setting of this variable in some cases; see below.) - -The value can also be a list of error conditions that should call the -debugger. For example, if you set it to the list -@code{(void-variable)}, then only errors about a variable that has no -value invoke the debugger. - -When this variable is non-@code{nil}, Emacs does not create an error -handler around process filter functions and sentinels. Therefore, -errors in these functions also invoke the debugger. @xref{Processes}. -@end defopt - -@defopt debug-ignored-errors -This variable specifies certain kinds of errors that should not enter -the debugger. Its value is a list of error condition symbols and/or -regular expressions. If the error has any of those condition symbols, -or if the error message matches any of the regular expressions, then -that error does not enter the debugger, regardless of the value of -@code{debug-on-error}. - -The normal value of this variable lists several errors that happen often -during editing but rarely result from bugs in Lisp programs. However, -``rarely'' is not ``never''; if your program fails with an error that -matches this list, you will need to change this list in order to debug -the error. The easiest way is usually to set -@code{debug-ignored-errors} to @code{nil}. -@end defopt - -@defopt eval-expression-debug-on-error -If this variable has a non-@code{nil} value, then -@code{debug-on-error} is set to @code{t} when evaluating with the -command @code{eval-expression}. If -@code{eval-expression-debug-on-error} is @code{nil}, then the value of -@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}. -@end defopt - -@defopt debug-on-signal -Normally, errors that are caught by @code{condition-case} never run the -debugger, even if @code{debug-on-error} is non-@code{nil}. In other -words, @code{condition-case} gets a chance to handle the error before -the debugger gets a chance. - -If you set @code{debug-on-signal} to a non-@code{nil} value, then the -debugger gets the first chance at every error; an error will invoke the -debugger regardless of any @code{condition-case}, if it fits the -criteria specified by the values of @code{debug-on-error} and -@code{debug-ignored-errors}. - -@strong{Warning:} This variable is strong medicine! Various parts of -Emacs handle errors in the normal course of affairs, and you may not -even realize that errors happen there. If you set -@code{debug-on-signal} to a non-@code{nil} value, those errors will -enter the debugger. - -@strong{Warning:} @code{debug-on-signal} has no effect when -@code{debug-on-error} is @code{nil}. -@end defopt - - To debug an error that happens during loading of the init -file, use the option @samp{--debug-init}. This binds -@code{debug-on-error} to @code{t} while loading the init file, and -bypasses the @code{condition-case} which normally catches errors in the -init file. - -@node Infinite Loops -@subsection Debugging Infinite Loops -@cindex infinite loops -@cindex loops, infinite -@cindex quitting from infinite loop -@cindex stopping an infinite loop - - When a program loops infinitely and fails to return, your first -problem is to stop the loop. On most operating systems, you can do this -with @kbd{C-g}, which causes a @dfn{quit}. - - Ordinary quitting gives no information about why the program was -looping. To get more information, you can set the variable -@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not -considered an error, and @code{debug-on-error} has no effect on the -handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on -errors. - - Once you have the debugger running in the middle of the infinite loop, -you can proceed from the debugger using the stepping commands. If you -step through the entire loop, you will probably get enough information -to solve the problem. - -@defopt debug-on-quit -This variable determines whether the debugger is called when @code{quit} -is signaled and not handled. If @code{debug-on-quit} is non-@code{nil}, -then the debugger is called whenever you quit (that is, type @kbd{C-g}). -If @code{debug-on-quit} is @code{nil}, then the debugger is not called -when you quit. @xref{Quitting}. -@end defopt - -@node Function Debugging -@subsection Entering the Debugger on a Function Call -@cindex function call debugging -@cindex debugging specific functions - - To investigate a problem that happens in the middle of a program, one -useful technique is to enter the debugger whenever a certain function is -called. You can do this to the function in which the problem occurs, -and then step through the function, or you can do this to a function -called shortly before the problem, step quickly over the call to that -function, and then step through its caller. - -@deffn Command debug-on-entry function-name -This function requests @var{function-name} to invoke the debugger each -time it is called. It works by inserting the form -@code{(implement-debug-on-entry)} into the function definition as the -first form. - -Any function or macro defined as Lisp code may be set to break on -entry, regardless of whether it is interpreted code or compiled code. -If the function is a command, it will enter the debugger when called -from Lisp and when called interactively (after the reading of the -arguments). You can also set debug-on-entry for primitive functions -(i.e., those written in C) this way, but it only takes effect when the -primitive is called from Lisp code. Debug-on-entry is not allowed for -special forms. - -When @code{debug-on-entry} is called interactively, it prompts for -@var{function-name} in the minibuffer. If the function is already set -up to invoke the debugger on entry, @code{debug-on-entry} does nothing. -@code{debug-on-entry} always returns @var{function-name}. - -@strong{Warning:} if you redefine a function after using -@code{debug-on-entry} on it, the code to enter the debugger is -discarded by the redefinition. In effect, redefining the function -cancels the break-on-entry feature for that function. - -Here's an example to illustrate use of this function: - -@example -@group -(defun fact (n) - (if (zerop n) 1 - (* n (fact (1- n))))) - @result{} fact -@end group -@group -(debug-on-entry 'fact) - @result{} fact -@end group -@group -(fact 3) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--entering a function: -* fact(3) - eval((fact 3)) - eval-last-sexp-1(nil) - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------- Buffer: *Backtrace* ------ -@end group - -@group -(symbol-function 'fact) - @result{} (lambda (n) - (debug (quote debug)) - (if (zerop n) 1 (* n (fact (1- n))))) -@end group -@end example -@end deffn - -@deffn Command cancel-debug-on-entry &optional function-name -This function undoes the effect of @code{debug-on-entry} on -@var{function-name}. When called interactively, it prompts for -@var{function-name} in the minibuffer. If @var{function-name} is -omitted or @code{nil}, it cancels break-on-entry for all functions. -Calling @code{cancel-debug-on-entry} does nothing to a function which is -not currently set up to break on entry. -@end deffn - -@node Explicit Debug -@subsection Explicit Entry to the Debugger - - You can cause the debugger to be called at a certain point in your -program by writing the expression @code{(debug)} at that point. To do -this, visit the source file, insert the text @samp{(debug)} at the -proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key -binding). @strong{Warning:} if you do this for temporary debugging -purposes, be sure to undo this insertion before you save the file! - - The place where you insert @samp{(debug)} must be a place where an -additional form can be evaluated and its value ignored. (If the value -of @code{(debug)} isn't ignored, it will alter the execution of the -program!) The most common suitable places are inside a @code{progn} or -an implicit @code{progn} (@pxref{Sequencing}). - -@node Using Debugger -@subsection Using the Debugger - - When the debugger is entered, it displays the previously selected -buffer in one window and a buffer named @samp{*Backtrace*} in another -window. The backtrace buffer contains one line for each level of Lisp -function execution currently going on. At the beginning of this buffer -is a message describing the reason that the debugger was invoked (such -as the error message and associated data, if it was invoked due to an -error). - - The backtrace buffer is read-only and uses a special major mode, -Debugger mode, in which letters are defined as debugger commands. The -usual Emacs editing commands are available; thus, you can switch windows -to examine the buffer that was being edited at the time of the error, -switch buffers, visit files, or do any other sort of editing. However, -the debugger is a recursive editing level (@pxref{Recursive Editing}) -and it is wise to go back to the backtrace buffer and exit the debugger -(with the @kbd{q} command) when you are finished with it. Exiting -the debugger gets out of the recursive edit and kills the backtrace -buffer. - -@cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click @kbd{Mouse-2} on that -name, or move to it and type @key{RET}, to visit the source code. - - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. - -@node Debugger Commands -@subsection Debugger Commands -@cindex debugger command list - - The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of -debugger commands is for stepping through code, so that you can see -how control flows. The debugger can step through the control -structures of an interpreted function, but cannot do so in a -byte-compiled function. If you would like to step through a -byte-compiled function, replace it with an interpreted definition of -the same function. (To do this, visit the source for the function and -type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger -to step through a primitive function. - - Here is a list of Debugger mode commands: - -@table @kbd -@item c -Exit the debugger and continue execution. When continuing is possible, -it resumes execution of the program as if the debugger had never been -entered (aside from any side-effects that you caused by changing -variable values or data structures while inside the debugger). - -Continuing is possible after entry to the debugger due to function entry -or exit, explicit invocation, or quitting. You cannot continue if the -debugger was entered because of an error. - -@item d -Continue execution, but enter the debugger the next time any Lisp -function is called. This allows you to step through the -subexpressions of an expression, seeing what values the subexpressions -compute, and what else they do. - -The stack frame made for the function call which enters the debugger in -this way will be flagged automatically so that the debugger will be -called again when the frame is exited. You can use the @kbd{u} command -to cancel this flag. - -@item b -Flag the current frame so that the debugger will be entered when the -frame is exited. Frames flagged in this way are marked with stars -in the backtrace buffer. - -@item u -Don't enter the debugger when the current frame is exited. This -cancels a @kbd{b} command on that frame. The visible effect is to -remove the star from the line in the backtrace buffer. - -@item j -Flag the current frame like @kbd{b}. Then continue execution like -@kbd{c}, but temporarily disable break-on-entry for all functions that -are set up to do so by @code{debug-on-entry}. - -@item e -Read a Lisp expression in the minibuffer, evaluate it, and print the -value in the echo area. The debugger alters certain important -variables, and the current buffer, as part of its operation; @kbd{e} -temporarily restores their values from outside the debugger, so you can -examine and change them. This makes the debugger more transparent. By -contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. - -@item R -Like @kbd{e}, but also save the result of evaluation in the -buffer @samp{*Debugger-record*}. - -@item q -Terminate the program being debugged; return to top-level Emacs -command execution. - -If the debugger was entered due to a @kbd{C-g} but you really want -to quit, and not debug, use the @kbd{q} command. - -@item r -Return a value from the debugger. The value is computed by reading an -expression with the minibuffer and evaluating it. - -The @kbd{r} command is useful when the debugger was invoked due to exit -from a Lisp call frame (as requested with @kbd{b} or by entering the -frame with @kbd{d}); then the value specified in the @kbd{r} command is -used as the value of that frame. It is also useful if you call -@code{debug} and use its return value. Otherwise, @kbd{r} has the same -effect as @kbd{c}, and the specified return value does not matter. - -You can't use @kbd{r} when the debugger was entered due to an error. - -@item l -Display a list of functions that will invoke the debugger when called. -This is a list of functions that are set to break on entry by means of -@code{debug-on-entry}. @strong{Warning:} if you redefine such a -function and thus cancel the effect of @code{debug-on-entry}, it may -erroneously show up in this list. -@end table - -@node Invoking the Debugger -@subsection Invoking the Debugger - - Here we describe in full detail the function @code{debug} that is used -to invoke the debugger. - -@defun debug &rest debugger-args -This function enters the debugger. It switches buffers to a buffer -named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second -recursive entry to the debugger, etc.), and fills it with information -about the stack of Lisp function calls. It then enters a recursive -edit, showing the backtrace buffer in Debugger mode. - -The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit -the recursive edit; then @code{debug} switches back to the previous -buffer and returns to whatever called @code{debug}. This is the only -way the function @code{debug} can return to its caller. - -The use of the @var{debugger-args} is that @code{debug} displays the -rest of its arguments at the top of the @samp{*Backtrace*} buffer, so -that the user can see them. Except as described below, this is the -@emph{only} way these arguments are used. - -However, certain values for first argument to @code{debug} have a -special significance. (Normally, these values are used only by the -internals of Emacs, and not by programmers calling @code{debug}.) Here -is a table of these special values: - -@table @code -@item lambda -@cindex @code{lambda} in debug -A first argument of @code{lambda} means @code{debug} was called -because of entry to a function when @code{debug-on-next-call} was -non-@code{nil}. The debugger displays @samp{Debugger -entered--entering a function:} as a line of text at the top of the -buffer. - -@item debug -@code{debug} as first argument means @code{debug} was called because -of entry to a function that was set to debug on entry. The debugger -displays the string @samp{Debugger entered--entering a function:}, -just as in the @code{lambda} case. It also marks the stack frame for -that function so that it will invoke the debugger when exited. - -@item t -When the first argument is @code{t}, this indicates a call to -@code{debug} due to evaluation of a function call form when -@code{debug-on-next-call} is non-@code{nil}. The debugger displays -@samp{Debugger entered--beginning evaluation of function call form:} -as the top line in the buffer. - -@item exit -When the first argument is @code{exit}, it indicates the exit of a -stack frame previously marked to invoke the debugger on exit. The -second argument given to @code{debug} in this case is the value being -returned from the frame. The debugger displays @samp{Debugger -entered--returning value:} in the top line of the buffer, followed by -the value being returned. - -@item error -@cindex @code{error} in debug -When the first argument is @code{error}, the debugger indicates that -it is being entered because an error or @code{quit} was signaled and -not handled, by displaying @samp{Debugger entered--Lisp error:} -followed by the error signaled and any arguments to @code{signal}. -For example, - -@example -@group -(let ((debug-on-error t)) - (/ 1 0)) -@end group - -@group ------- Buffer: *Backtrace* ------ -Debugger entered--Lisp error: (arith-error) - /(1 0) -... ------- Buffer: *Backtrace* ------ -@end group -@end example - -If an error was signaled, presumably the variable -@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, -then presumably the variable @code{debug-on-quit} is non-@code{nil}. - -@item nil -Use @code{nil} as the first of the @var{debugger-args} when you want -to enter the debugger explicitly. The rest of the @var{debugger-args} -are printed on the top line of the buffer. You can use this feature to -display messages---for example, to remind yourself of the conditions -under which @code{debug} is called. -@end table -@end defun - -@node Internals of Debugger -@subsection Internals of the Debugger - - This section describes functions and variables used internally by the -debugger. - -@defvar debugger -The value of this variable is the function to call to invoke the -debugger. Its value must be a function of any number of arguments, or, -more typically, the name of a function. This function should invoke -some kind of debugger. The default value of the variable is -@code{debug}. - -The first argument that Lisp hands to the function indicates why it -was called. The convention for arguments is detailed in the description -of @code{debug} (@pxref{Invoking the Debugger}). -@end defvar - -@deffn Command backtrace -@cindex run time stack -@cindex call stack -This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@samp{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. - -In the following example, a Lisp expression calls @code{backtrace} -explicitly. This prints the backtrace to the stream -@code{standard-output}, which, in this case, is the buffer -@samp{backtrace-output}. - -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. - -@smallexample -@group -(with-output-to-temp-buffer "backtrace-output" - (let ((var 1)) - (save-excursion - (setq var (eval '(progn - (1+ var) - (list 'testing (backtrace)))))))) - - @result{} (testing nil) -@end group - -@group ------------ Buffer: backtrace-output ------------ - backtrace() - (list ...computing arguments...) -@end group - (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) - (setq ...) - (save-excursion ...) - (let ...) - (with-output-to-temp-buffer ...) - eval((with-output-to-temp-buffer ...)) - eval-last-sexp-1(nil) -@group - eval-last-sexp(nil) - call-interactively(eval-last-sexp) ------------ Buffer: backtrace-output ------------ -@end group -@end smallexample -@end deffn - -@ignore @c Not worth mentioning -@defopt stack-trace-on-error -@cindex stack trace -This variable controls whether Lisp automatically displays a -backtrace buffer after every error that is not handled. A quit signal -counts as an error for this variable. If it is non-@code{nil} then a -backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every -error. If it is @code{nil}, then a backtrace is not shown. - -When a backtrace is shown, that buffer is not selected. If either -@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then -a backtrace is shown in one buffer, and the debugger is popped up in -another buffer with its own backtrace. - -We consider this feature to be obsolete and superseded by the debugger -itself. -@end defopt -@end ignore - -@defvar debug-on-next-call -@cindex @code{eval}, and debugging -@cindex @code{apply}, and debugging -@cindex @code{funcall}, and debugging -If this variable is non-@code{nil}, it says to call the debugger before -the next @code{eval}, @code{apply} or @code{funcall}. Entering the -debugger sets @code{debug-on-next-call} to @code{nil}. - -The @kbd{d} command in the debugger works by setting this variable. -@end defvar - -@defun backtrace-debug level flag -This function sets the debug-on-exit flag of the stack frame @var{level} -levels down the stack, giving it the value @var{flag}. If @var{flag} is -non-@code{nil}, this will cause the debugger to be entered when that -frame later exits. Even a nonlocal exit through that frame will enter -the debugger. - -This function is used only by the debugger. -@end defun - -@defvar command-debug-status -This variable records the debugging status of the current interactive -command. Each time a command is called interactively, this variable is -bound to @code{nil}. The debugger can set this variable to leave -information for future debugger invocations during the same command -invocation. - -The advantage of using this variable rather than an ordinary global -variable is that the data will never carry over to a subsequent command -invocation. -@end defvar - -@defun backtrace-frame frame-number -The function @code{backtrace-frame} is intended for use in Lisp -debuggers. It returns information about what computation is happening -in the stack frame @var{frame-number} levels down. - -If that frame has not evaluated the arguments yet, or is a special -form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. - -If that frame has evaluated its arguments and called its function -already, the return value is @code{(t @var{function} -@var{arg-values}@dots{})}. - -In the return value, @var{function} is whatever was supplied as the -@sc{car} of the evaluated list, or a @code{lambda} expression in the -case of a macro call. If the function has a @code{&rest} argument, that -is represented as the tail of the list @var{arg-values}. - -If @var{frame-number} is out of range, @code{backtrace-frame} returns -@code{nil}. -@end defun - -@include edebug.texi - -@node Syntax Errors -@section Debugging Invalid Lisp Syntax -@cindex debugging invalid Lisp syntax - - The Lisp reader reports invalid syntax, but cannot say where the real -problem is. For example, the error ``End of file during parsing'' in -evaluating an expression indicates an excess of open parentheses (or -square brackets). The reader detects this imbalance at the end of the -file, but it cannot figure out where the close parenthesis should have -been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close -parenthesis or missing open parenthesis, but does not say where the -missing parenthesis belongs. How, then, to find what to change? - - If the problem is not simply an imbalance of parentheses, a useful -technique is to try @kbd{C-M-e} at the beginning of each defun, and see -if it goes to the place where that defun appears to end. If it does -not, there is a problem in that defun. - -@cindex unbalanced parentheses -@cindex parenthesis mismatch, debugging - However, unmatched parentheses are the most common syntax errors in -Lisp, and we can give further advice for those cases. (In addition, -just moving point through the code with Show Paren mode enabled might -find the mismatch.) - -@menu -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. -@end menu - -@node Excess Open -@subsection Excess Open Parentheses - - The first step is to find the defun that is unbalanced. If there is -an excess open parenthesis, the way to do this is to go to the end of -the file and type @kbd{C-u C-M-u}. This will move you to the -beginning of the first defun that is unbalanced. - - The next step is to determine precisely what is wrong. There is no -way to be sure of this except by studying the program, but often the -existing indentation is a clue to where the parentheses should have -been. The easiest way to use this clue is to reindent with @kbd{C-M-q} -and see what moves. @strong{But don't do this yet!} Keep reading, -first. - - Before you do this, make sure the defun has enough close parentheses. -Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest -of the file until the end. So move to the end of the defun and insert a -close parenthesis there. Don't use @kbd{C-M-e} to move there, since -that too will fail to work until the defun is balanced. - - Now you can go to the beginning of the defun and type @kbd{C-M-q}. -Usually all the lines from a certain point to the end of the function -will shift to the right. There is probably a missing close parenthesis, -or a superfluous open parenthesis, near that point. (However, don't -assume this is true; study the code to make sure.) Once you have found -the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old -indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fit the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Excess Close -@subsection Excess Close Parentheses - - To deal with an excess close parenthesis, first go to the beginning -of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first -unbalanced defun. - - Then find the actual matching close parenthesis by typing @kbd{C-M-f} -at the beginning of that defun. This will leave you somewhere short of -the place where the defun ought to end. It is possible that you will -find a spurious close parenthesis in that vicinity. - - If you don't see a problem at that point, the next thing to do is to -type @kbd{C-M-q} at the beginning of the defun. A range of lines will -probably shift left; if so, the missing open parenthesis or spurious -close parenthesis is probably near the first of those lines. (However, -don't assume this is true; study the code to make sure.) Once you have -found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the -old indentation is probably appropriate to the intended parentheses. - - After you think you have fixed the problem, use @kbd{C-M-q} again. If -the old indentation actually fits the intended nesting of parentheses, -and you have put back those parentheses, @kbd{C-M-q} should not change -anything. - -@node Test Coverage -@section Test Coverage -@cindex coverage testing - -@findex testcover-start -@findex testcover-mark-all -@findex testcover-next-mark - You can do coverage testing for a file of Lisp code by loading the -@code{testcover} library and using the command @kbd{M-x -testcover-start @key{RET} @var{file} @key{RET}} to instrument the -code. Then test your code by calling it one or more times. Then use -the command @kbd{M-x testcover-mark-all} to display colored highlights -on the code to show where coverage is insufficient. The command -@kbd{M-x testcover-next-mark} will move point forward to the next -highlighted spot. - - Normally, a red highlight indicates the form was never completely -evaluated; a brown highlight means it always evaluated to the same -value (meaning there has been little testing of what is done with the -result). However, the red highlight is skipped for forms that can't -possibly complete their evaluation, such as @code{error}. The brown -highlight is skipped for forms that are expected to always evaluate to -the same value, such as @code{(setq x 14)}. - - For difficult cases, you can add do-nothing macros to your code to -give advice to the test coverage tool. - -@defmac 1value form -Evaluate @var{form} and return its value, but inform coverage testing -that @var{form}'s value should always be the same. -@end defmac - -@defmac noreturn form -Evaluate @var{form}, informing coverage testing that @var{form} should -never return. If it ever does return, you get a run-time error. -@end defmac - - Edebug also has a coverage testing feature (@pxref{Coverage -Testing}). These features partly duplicate each other, and it would -be cleaner to combine them. - -@node Compilation Errors -@section Debugging Problems in Compilation -@cindex debugging byte compilation problems - - When an error happens during byte compilation, it is normally due to -invalid syntax in the program you are compiling. The compiler prints a -suitable error message in the @samp{*Compile-Log*} buffer, and then -stops. The message may state a function name in which the error was -found, or it may not. Either way, here is how to find out where in the -file the error occurred. - - What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}. -(Note that the buffer name starts with a space, so it does not show -up in @kbd{M-x list-buffers}.) This buffer contains the program being -compiled, and point shows how far the byte compiler was able to read. - - If the error was due to invalid Lisp syntax, point shows exactly where -the invalid syntax was @emph{detected}. The cause of the error is not -necessarily near by! Use the techniques in the previous section to find -the error. - - If the error was detected while compiling a form that had been read -successfully, then point is located at the end of the form. In this -case, this technique can't localize the error precisely, but can still -show you which function to check. - -@ignore - arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7 -@end ignore diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi deleted file mode 100644 index 14e6a79c5f0..00000000000 --- a/doc/lispref/display.texi +++ /dev/null @@ -1,5880 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/display -@node Display, System Interface, Processes, Top -@chapter Emacs Display - - This chapter describes a number of features related to the display -that Emacs presents to the user. - -@menu -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style for text characters: - font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs' Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: The usual conventions for displaying nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -@end menu - -@node Refresh Screen -@section Refreshing the Screen - - The function @code{redraw-frame} clears and redisplays the entire -contents of a given frame (@pxref{Frames}). This is useful if the -screen is corrupted. - -@c Emacs 19 feature -@defun redraw-frame frame -This function clears and redisplays frame @var{frame}. -@end defun - - Even more powerful is @code{redraw-display}: - -@deffn Command redraw-display -This function clears and redisplays all visible frames. -@end deffn - - In Emacs, processing user input takes priority over redisplay. If -you call these functions when input is available, they don't redisplay -immediately, but the requested redisplay does happen -eventually---after all the input has been processed. - - On text-only terminals, suspending and resuming Emacs normally also -refreshes the screen. Some terminal emulators record separate -contents for display-oriented programs such as Emacs and for ordinary -sequential display. If you are using such a terminal, you might want -to inhibit the redisplay on resumption. - -@defopt no-redraw-on-reenter -@cindex suspend (cf. @code{no-redraw-on-reenter}) -@cindex resume (cf. @code{no-redraw-on-reenter}) -This variable controls whether Emacs redraws the entire screen after it -has been suspended and resumed. Non-@code{nil} means there is no need -to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. -@end defopt - -@node Forcing Redisplay -@section Forcing Redisplay -@cindex forcing redisplay - - Emacs normally tries to redisplay the screen whenever it waits for -input. With the following function, you can request an immediate -attempt to redisplay, in the middle of Lisp code, without actually -waiting for input. - -@defun redisplay &optional force -This function tries immediately to redisplay, provided there are no -pending input events. - -If the optional argument @var{force} is non-@code{nil}, it does all -pending redisplay work even if input is available, with no -pre-emption. - -The function returns @code{t} if it actually tried to redisplay, and -@code{nil} otherwise. A value of @code{t} does not mean that -redisplay proceeded to completion; it could have been pre-empted by -newly arriving terminal input. -@end defun - - @code{redisplay} with no argument tries immediately to redisplay, -but has no effect on the usual rules for what parts of the screen to -redisplay. By contrast, the following function adds certain windows -to the pending redisplay work (as if their contents had completely -changed), but doesn't immediately try to do any redisplay work. - -@defun force-window-update &optional object -This function forces some or all windows to be updated on next -redisplay. If @var{object} is a window, it requires eventual -redisplay of that window. If @var{object} is a buffer or buffer name, -it requires eventual redisplay of all windows displaying that buffer. -If @var{object} is @code{nil} (or omitted), it requires eventual -redisplay of all windows. -@end defun - - @code{force-window-update} does not do a redisplay immediately. -(Emacs will do that when it waits for input.) Rather, its effect is -to put more work on the queue to be done by redisplay whenever there -is a chance. - - Emacs redisplay normally stops if input arrives, and does not happen -at all if input is available before it starts. Most of the time, this -is exactly what you want. However, you can prevent preemption by -binding @code{redisplay-dont-pause} to a non-@code{nil} value. - -@defvar redisplay-dont-pause -If this variable is non-@code{nil}, pending input does not -prevent or halt redisplay; redisplay occurs, and finishes, -regardless of whether input is available. -@end defvar - -@defvar redisplay-preemption-period -This variable specifies how many seconds Emacs waits between checks -for new input during redisplay. (The default is 0.1 seconds.) If -input has arrived when Emacs checks, it pre-empts redisplay and -processes the available input before trying again to redisplay. - -If this variable is @code{nil}, Emacs does not check for input during -redisplay, and redisplay cannot be preempted by input. - -This variable is only obeyed on graphical terminals. For -text terminals, see @ref{Terminal Output}. -@end defvar - -@node Truncation -@section Truncation -@cindex line wrapping -@cindex line truncation -@cindex continuation lines -@cindex @samp{$} in display -@cindex @samp{\} in display - - When a line of text extends beyond the right edge of a window, Emacs -can @dfn{continue} the line (make it ``wrap'' to the next screen -line), or @dfn{truncate} the line (limit it to one screen line). The -additional screen lines used to display a long text line are called -@dfn{continuation} lines. Continuation is not the same as filling; -continuation happens on the screen only, not in the buffer contents, -and it breaks a line precisely at the right margin, not at a word -boundary. @xref{Filling}. - - On a graphical display, tiny arrow images in the window fringes -indicate truncated and continued lines (@pxref{Fringes}). On a text -terminal, a @samp{$} in the rightmost column of the window indicates -truncation; a @samp{\} on the rightmost column indicates a line that -``wraps.'' (The display table can specify alternate characters to use -for this; @pxref{Display Tables}). - -@defopt truncate-lines -If this buffer-local variable is non-@code{nil}, lines that extend -beyond the right edge of the window are truncated; otherwise, they are -continued. As a special exception, the variable -@code{truncate-partial-width-windows} takes precedence in -@dfn{partial-width} windows (i.e., windows that do not occupy the -entire frame width). -@end defopt - -@defopt default-truncate-lines -This variable is the default value for @code{truncate-lines}, for -buffers that do not have buffer-local values for it. -@end defopt - -@defopt truncate-partial-width-windows -This variable controls line truncation in @dfn{partial-width} windows. -A partial-width window is one that does not occupy the entire frame -width (@pxref{Splitting Windows}). If the value is @code{nil}, line -truncation is determined by the variable @code{truncate-lines} (see -above). If the value is an integer @var{n}, lines are truncated if -the partial-width window has fewer than @var{n} columns, regardless of -the value of @code{truncate-lines}; if the partial-width window has -@var{n} or more columns, line truncation is determined by -@code{truncate-lines}. For any other non-@code{nil} value, lines are -truncated in every partial-width window, regardless of the value of -@code{truncate-lines}. -@end defopt - - When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in -a window, that forces truncation. - -@defvar wrap-prefix -If this buffer-local variable is non-@code{nil}, it defines a -``prefix'' that is prepended to every continuation line at -display-time. (If lines are truncated, the wrap-prefix is never -used.) It may be a string, an image, or a stretch-glyph; the value is -interpreted in the same way as a @code{display} text property. -@xref{Display Property}. - -A wrap-prefix may also be specified for regions of text, using the -@code{wrap-prefix} text or overlay property. This takes precedence -over the @code{wrap-prefix} variable. @xref{Special Properties}. -@end defvar - -@defvar line-prefix -If this buffer-local variable is non-@code{nil}, it defines a -``prefix'' that is prepended to every non-continuation line at -display-time. It may be a string, an image, or a stretch-glyph; the -value is interpreted in the same way as a @code{display} text -property. @xref{Display Property}. - -A line-prefix may also be specified for regions of text using the -@code{line-prefix} text or overlay property. This takes precedence -over the @code{line-prefix} variable. @xref{Special Properties}. -@end defvar - - If your buffer contains @emph{very} long lines, and you use -continuation to display them, computing the continuation lines can -make Emacs redisplay slow. The column computation and indentation -functions also become slow. Then you might find it advisable to set -@code{cache-long-line-scans} to @code{t}. - -@defvar cache-long-line-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. - -Turning on the cache slows down processing of short lines somewhat. - -This variable is automatically buffer-local in every buffer. -@end defvar - -@node The Echo Area -@section The Echo Area -@cindex error display -@cindex echo area - - The @dfn{echo area} is used for displaying error messages -(@pxref{Errors}), for messages made with the @code{message} primitive, -and for echoing keystrokes. It is not the same as the minibuffer, -despite the fact that the minibuffer appears (when active) in the same -place on the screen as the echo area. The @cite{GNU Emacs Manual} -specifies the rules for resolving conflicts between the echo area and -the minibuffer for use of that screen space (@pxref{Minibuffer,, The -Minibuffer, emacs, The GNU Emacs Manual}). - - You can write output in the echo area by using the Lisp printing -functions with @code{t} as the stream (@pxref{Output Functions}), or -explicitly. - -@menu -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. -@end menu - -@node Displaying Messages -@subsection Displaying Messages in the Echo Area -@cindex display message in echo area - - This section describes the functions for explicitly producing echo -area messages. Many other Emacs features display messages there, too. - -@defun message format-string &rest arguments -This function displays a message in the echo area. The argument -@var{format-string} is similar to a C language @code{printf} format -string. See @code{format} in @ref{Formatting Strings}, for the details -on the conversion specifications. @code{message} returns the -constructed string. - -In batch mode, @code{message} prints the message text on the standard -error stream, followed by a newline. - -If @var{format-string}, or strings among the @var{arguments}, have -@code{face} text properties, these affect the way the message is displayed. - -@c Emacs 19 feature -If @var{format-string} is @code{nil} or the empty string, -@code{message} clears the echo area; if the echo area has been -expanded automatically, this brings it back to its normal size. -If the minibuffer is active, this brings the minibuffer contents back -onto the screen immediately. - -@example -@group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." -@end group - -@group ----------- Echo Area ---------- -Minibuffer depth is 0. ----------- Echo Area ---------- -@end group -@end example - -To automatically display a message in the echo area or in a pop-buffer, -depending on its size, use @code{display-message-or-buffer} (see below). -@end defun - -@defmac with-temp-message message &rest body -This construct displays a message in the echo area temporarily, during -the execution of @var{body}. It displays @var{message}, executes -@var{body}, then returns the value of the last body form while restoring -the previous echo area contents. -@end defmac - -@defun message-or-box format-string &rest arguments -This function displays a message like @code{message}, but may display it -in a dialog box instead of the echo area. If this function is called in -a command that was invoked using the mouse---more precisely, if -@code{last-nonmenu-event} (@pxref{Command Loop Info}) is either -@code{nil} or a list---then it uses a dialog box or pop-up menu to -display the message. Otherwise, it uses the echo area. (This is the -same criterion that @code{y-or-n-p} uses to make a similar decision; see -@ref{Yes-or-No Queries}.) - -You can force use of the mouse or of the echo area by binding -@code{last-nonmenu-event} to a suitable value around the call. -@end defun - -@defun message-box format-string &rest arguments -@anchor{message-box} -This function displays a message like @code{message}, but uses a dialog -box (or a pop-up menu) whenever that is possible. If it is impossible -to use a dialog box or pop-up menu, because the terminal does not -support them, then @code{message-box} uses the echo area, like -@code{message}. -@end defun - -@defun display-message-or-buffer message &optional buffer-name not-this-window frame -This function displays the message @var{message}, which may be either a -string or a buffer. If it is shorter than the maximum height of the -echo area, as defined by @code{max-mini-window-height}, it is displayed -in the echo area, using @code{message}. Otherwise, -@code{display-buffer} is used to show it in a pop-up buffer. - -Returns either the string shown in the echo area, or when a pop-up -buffer is used, the window used to display it. - -If @var{message} is a string, then the optional argument -@var{buffer-name} is the name of the buffer used to display it when a -pop-up buffer is used, defaulting to @samp{*Message*}. In the case -where @var{message} is a string and displayed in the echo area, it is -not specified whether the contents are inserted into the buffer anyway. - -The optional arguments @var{not-this-window} and @var{frame} are as for -@code{display-buffer}, and only used if a buffer is displayed. -@end defun - -@defun current-message -This function returns the message currently being displayed in the -echo area, or @code{nil} if there is none. -@end defun - -@node Progress -@subsection Reporting Operation Progress -@cindex progress reporting - - When an operation can take a while to finish, you should inform the -user about the progress it makes. This way the user can estimate -remaining time and clearly see that Emacs is busy working, not hung. - - Functions listed in this section provide simple and efficient way of -reporting operation progress. Here is a working example that does -nothing useful: - -@smallexample -(let ((progress-reporter - (make-progress-reporter "Collecting mana for Emacs..." - 0 500))) - (dotimes (k 500) - (sit-for 0.01) - (progress-reporter-update progress-reporter k)) - (progress-reporter-done progress-reporter)) -@end smallexample - -@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time -This function creates and returns a @dfn{progress reporter}---an -object you will use as an argument for all other functions listed -here. The idea is to precompute as much data as possible to make -progress reporting very fast. - -When this progress reporter is subsequently used, it will display -@var{message} in the echo area, followed by progress percentage. -@var{message} is treated as a simple string. If you need it to depend -on a filename, for instance, use @code{format} before calling this -function. - -@var{min-value} and @var{max-value} arguments stand for starting and -final states of your operation. For instance, if you scan a buffer, -they should be the results of @code{point-min} and @code{point-max} -correspondingly. It is required that @var{max-value} is greater than -@var{min-value}. If you create progress reporter when some part of -the operation has already been completed, then specify -@var{current-value} argument. But normally you should omit it or set -it to @code{nil}---it will default to @var{min-value} then. - -Remaining arguments control the rate of echo area updates. Progress -reporter will wait for at least @var{min-change} more percents of the -operation to be completed before printing next message. -@var{min-time} specifies the minimum time in seconds to pass between -successive prints. It can be fractional. Depending on Emacs and -system capabilities, progress reporter may or may not respect this -last argument or do it with varying precision. Default value for -@var{min-change} is 1 (one percent), for @var{min-time}---0.2 -(seconds.) - -This function calls @code{progress-reporter-update}, so the first -message is printed immediately. -@end defun - -@defun progress-reporter-update reporter value -This function does the main work of reporting progress of your -operation. It displays the message of @var{reporter}, followed by -progress percentage determined by @var{value}. If percentage is zero, -or close enough according to the @var{min-change} and @var{min-time} -arguments, then it is omitted from the output. - -@var{reporter} must be the result of a call to -@code{make-progress-reporter}. @var{value} specifies the current -state of your operation and must be between @var{min-value} and -@var{max-value} (inclusive) as passed to -@code{make-progress-reporter}. For instance, if you scan a buffer, -then @var{value} should be the result of a call to @code{point}. - -This function respects @var{min-change} and @var{min-time} as passed -to @code{make-progress-reporter} and so does not output new messages -on every invocation. It is thus very fast and normally you should not -try to reduce the number of calls to it: resulting overhead will most -likely negate your effort. -@end defun - -@defun progress-reporter-force-update reporter value &optional new-message -This function is similar to @code{progress-reporter-update} except -that it prints a message in the echo area unconditionally. - -The first two arguments have the same meaning as for -@code{progress-reporter-update}. Optional @var{new-message} allows -you to change the message of the @var{reporter}. Since this functions -always updates the echo area, such a change will be immediately -presented to the user. -@end defun - -@defun progress-reporter-done reporter -This function should be called when the operation is finished. It -prints the message of @var{reporter} followed by word ``done'' in the -echo area. - -You should always call this function and not hope for -@code{progress-reporter-update} to print ``100%.'' Firstly, it may -never print it, there are many good reasons for this not to happen. -Secondly, ``done'' is more explicit. -@end defun - -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} -This is a convenience macro that works the same way as @code{dotimes} -does, but also reports loop progress using the functions described -above. It allows you to save some typing. - -You can rewrite the example in the beginning of this node using -this macro this way: - -@example -(dotimes-with-progress-reporter - (k 500) - "Collecting some mana for Emacs..." - (sit-for 0.01)) -@end example -@end defmac - -@node Logging Messages -@subsection Logging Messages in @samp{*Messages*} -@cindex logging echo-area messages - - Almost all the messages displayed in the echo area are also recorded -in the @samp{*Messages*} buffer so that the user can refer back to -them. This includes all the messages that are output with -@code{message}. - -@defopt message-log-max -This variable specifies how many lines to keep in the @samp{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - - To make @samp{*Messages*} more convenient for the user, the logging -facility combines successive identical messages. It also combines -successive related messages for the sake of two cases: question -followed by answer, and a series of progress messages. - - A ``question followed by an answer'' means two messages like the -ones produced by @code{y-or-n-p}: the first is @samp{@var{question}}, -and the second is @samp{@var{question}...@var{answer}}. The first -message conveys no additional information beyond what's in the second, -so logging the second message discards the first from the log. - - A ``series of progress messages'' means successive messages like -those produced by @code{make-progress-reporter}. They have the form -@samp{@var{base}...@var{how-far}}, where @var{base} is the same each -time, while @var{how-far} varies. Logging each message in the series -discards the previous one, provided they are consecutive. - - The functions @code{make-progress-reporter} and @code{y-or-n-p} -don't have to do anything special to activate the message log -combination feature. It operates whenever two consecutive messages -are logged that share a common prefix ending in @samp{...}. - -@node Echo Area Customization -@subsection Echo Area Customization - - These variables control details of how the echo area works. - -@defvar cursor-in-echo-area -This variable controls where the cursor appears when a message is -displayed in the echo area. If it is non-@code{nil}, then the cursor -appears at the end of the message. Otherwise, the cursor appears at -point---not in the echo area at all. - -The value is normally @code{nil}; Lisp programs bind it to @code{t} -for brief periods of time. -@end defvar - -@defvar echo-area-clear-hook -This normal hook is run whenever the echo area is cleared---either by -@code{(message nil)} or for any other reason. -@end defvar - -@defopt echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer or floating point number, -which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. (Once echoing -begins in a key sequence, all subsequent characters in the same key -sequence are echoed immediately.) - -If the value is zero, then command input is not echoed. -@end defopt - -@defvar message-truncate-lines -Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it, as in Emacs 20 and before. -@end defvar - - The variable @code{max-mini-window-height}, which specifies the -maximum height for resizing minibuffer windows, also applies to the -echo area (which is really a special use of the minibuffer window. -@xref{Minibuffer Misc}.). - -@node Warnings -@section Reporting Warnings -@cindex warnings - - @dfn{Warnings} are a facility for a program to inform the user of a -possible problem, but continue running. - -@menu -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize their warnings. -* Warning Options:: Variables users set to control display of warnings. -@end menu - -@node Warning Basics -@subsection Warning Basics -@cindex severity level - - Every warning has a textual message, which explains the problem for -the user, and a @dfn{severity level} which is a symbol. Here are the -possible severity levels, in order of decreasing severity, and their -meanings: - -@table @code -@item :emergency -A problem that will seriously impair Emacs operation soon -if you do not attend to it promptly. -@item :error -A report of data or circumstances that are inherently wrong. -@item :warning -A report of data or circumstances that are not inherently wrong, but -raise suspicion of a possible problem. -@item :debug -A report of information that may be useful if you are debugging. -@end table - - When your program encounters invalid input data, it can either -signal a Lisp error by calling @code{error} or @code{signal} or report -a warning with severity @code{:error}. Signaling a Lisp error is the -easiest thing to do, but it means the program cannot continue -processing. If you want to take the trouble to implement a way to -continue processing despite the bad data, then reporting a warning of -severity @code{:error} is the right way to inform the user of the -problem. For instance, the Emacs Lisp byte compiler can report an -error that way and continue compiling other functions. (If the -program signals a Lisp error and then handles it with -@code{condition-case}, the user won't see the error message; it could -show the message to the user by reporting it as a warning.) - -@cindex warning type - Each warning has a @dfn{warning type} to classify it. The type is a -list of symbols. The first symbol should be the custom group that you -use for the program's user options. For example, byte compiler -warnings use the warning type @code{(bytecomp)}. You can also -subcategorize the warnings, if you wish, by using more symbols in the -list. - -@defun display-warning type message &optional level buffer-name -This function reports a warning, using @var{message} as the message -and @var{type} as the warning type. @var{level} should be the -severity level, with @code{:warning} being the default. - -@var{buffer-name}, if non-@code{nil}, specifies the name of the buffer -for logging the warning. By default, it is @samp{*Warnings*}. -@end defun - -@defun lwarn type level message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message. In other respects it is -equivalent to @code{display-warning}. -@end defun - -@defun warn message &rest args -This function reports a warning using the value of @code{(format -@var{message} @var{args}...)} as the message, @code{(emacs)} as the -type, and @code{:warning} as the severity level. It exists for -compatibility only; we recommend not using it, because you should -specify a specific warning type. -@end defun - -@node Warning Variables -@subsection Warning Variables - - Programs can customize how their warnings appear by binding -the variables described in this section. - -@defvar warning-levels -This list defines the meaning and severity order of the warning -severity levels. Each element defines one severity level, -and they are arranged in order of decreasing severity. - -Each element has the form @code{(@var{level} @var{string} -@var{function})}, where @var{level} is the severity level it defines. -@var{string} specifies the textual description of this level. -@var{string} should use @samp{%s} to specify where to put the warning -type information, or it can omit the @samp{%s} so as not to include -that information. - -The optional @var{function}, if non-@code{nil}, is a function to call -with no arguments, to get the user's attention. - -Normally you should not change the value of this variable. -@end defvar - -@defvar warning-prefix-function -If non-@code{nil}, the value is a function to generate prefix text for -warnings. Programs can bind the variable to a suitable function. -@code{display-warning} calls this function with the warnings buffer -current, and the function can insert text in it. That text becomes -the beginning of the warning message. - -The function is called with two arguments, the severity level and its -entry in @code{warning-levels}. It should return a list to use as the -entry (this value need not be an actual member of -@code{warning-levels}). By constructing this value, the function can -change the severity of the warning, or specify different handling for -a given severity level. - -If the variable's value is @code{nil} then there is no function -to call. -@end defvar - -@defvar warning-series -Programs can bind this variable to @code{t} to say that the next -warning should begin a series. When several warnings form a series, -that means to leave point on the first warning of the series, rather -than keep moving it for each warning so that it appears on the last one. -The series ends when the local binding is unbound and -@code{warning-series} becomes @code{nil} again. - -The value can also be a symbol with a function definition. That is -equivalent to @code{t}, except that the next warning will also call -the function with no arguments with the warnings buffer current. The -function can insert text which will serve as a header for the series -of warnings. - -Once a series has begun, the value is a marker which points to the -buffer position in the warnings buffer of the start of the series. - -The variable's normal value is @code{nil}, which means to handle -each warning separately. -@end defvar - -@defvar warning-fill-prefix -When this variable is non-@code{nil}, it specifies a fill prefix to -use for filling each warning's text. -@end defvar - -@defvar warning-type-format -This variable specifies the format for displaying the warning type -in the warning message. The result of formatting the type this way -gets included in the message under the control of the string in the -entry in @code{warning-levels}. The default value is @code{" (%s)"}. -If you bind it to @code{""} then the warning type won't appear at -all. -@end defvar - -@node Warning Options -@subsection Warning Options - - These variables are used by users to control what happens -when a Lisp program reports a warning. - -@defopt warning-minimum-level -This user option specifies the minimum severity level that should be -shown immediately to the user. The default is @code{:warning}, which -means to immediately display all warnings except @code{:debug} -warnings. -@end defopt - -@defopt warning-minimum-log-level -This user option specifies the minimum severity level that should be -logged in the warnings buffer. The default is @code{:warning}, which -means to log all warnings except @code{:debug} warnings. -@end defopt - -@defopt warning-suppress-types -This list specifies which warning types should not be displayed -immediately for the user. Each element of the list should be a list -of symbols. If its elements match the first elements in a warning -type, then that warning is not displayed immediately. -@end defopt - -@defopt warning-suppress-log-types -This list specifies which warning types should not be logged in the -warnings buffer. Each element of the list should be a list of -symbols. If it matches the first few elements in a warning type, then -that warning is not logged. -@end defopt - -@node Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property (@pxref{Text Properties}) or a property of an overlay -(@pxref{Overlays}). Cursor motion also partly ignores these -characters; if the command loop finds point within them, it moves -point to the other side of them. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisible} property works. You should normally use @code{t} -as the value of the @code{invisible} property if you don't plan -to set @code{buffer-invisibility-spec} yourself. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a -database. It permits the implementation of convenient filtering -commands to view just a part of the entries in the database. Setting -this variable is very fast, much faster than scanning all the text in -the buffer looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. Setting this variable makes it -buffer-local. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list specifies a criterion for invisibility; if a -character's @code{invisible} property fits any one of these criteria, -the character is invisible. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} property value -is @var{atom} or if it is a list with @var{atom} as a member. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} property value is -@var{atom} or if it is a list with @var{atom} as a member. Moreover, -a sequence of such characters displays as an ellipsis. -@end table -@end table -@end defvar - - Two functions are specifically provided for adding elements to -@code{buffer-invisibility-spec} and removing elements from it. - -@defun add-to-invisibility-spec element -This function adds the element @var{element} to -@code{buffer-invisibility-spec}. If @code{buffer-invisibility-spec} -was @code{t}, it changes to a list, @code{(t)}, so that text whose -@code{invisible} property is @code{t} remains invisible. -@end defun - -@defun remove-from-invisibility-spec element -This removes the element @var{element} from -@code{buffer-invisibility-spec}. This does nothing if @var{element} -is not in the list. -@end defun - - A convention for use of @code{buffer-invisibility-spec} is that a -major mode should use the mode's own name as an element of -@code{buffer-invisibility-spec} and as the value of the -@code{invisible} property: - -@example -;; @r{If you want to display an ellipsis:} -(add-to-invisibility-spec '(my-symbol . t)) -;; @r{If you don't want ellipsis:} -(add-to-invisibility-spec 'my-symbol) - -(overlay-put (make-overlay beginning end) - 'invisible 'my-symbol) - -;; @r{When done with the overlays:} -(remove-from-invisibility-spec '(my-symbol . t)) -;; @r{Or respectively:} -(remove-from-invisibility-spec 'my-symbol) -@end example - - You can check for invisibility using the following function: - -@defun invisible-p pos-or-prop -If @var{pos-or-prop} is a marker or number, this function returns a -non-@code{nil} value if the text at that position is invisible. - -If @var{pos-or-prop} is any other kind of Lisp object, that is taken -to mean a possible value of the @code{invisible} text or overlay -property. In that case, this function returns a non-@code{nil} value -if that value would cause text to become invisible, based on the -current value of @code{buffer-invisibility-spec}. -@end defun - -@vindex line-move-ignore-invisible - Ordinarily, functions that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -ignore invisible newlines if @code{line-move-ignore-invisible} is -non-@code{nil} (the default), but only because they are explicitly -programmed to do so. - - However, if a command ends with point inside or immediately before -invisible text, the main editing loop moves point further forward or -further backward (in the same direction that the command already moved -it) until that condition is no longer true. Thus, if the command -moved point back into an invisible range, Emacs moves point back to -the beginning of that range, and then back one more character. If the -command moved point forward into an invisible range, Emacs moves point -forward up to the first visible character that follows the invisible -text. - - Incremental search can make invisible overlays visible temporarily -and/or permanently when a match includes invisible text. To enable -this, the overlay should have a non-@code{nil} -@code{isearch-open-invisible} property. The property value should be a -function to be called with the overlay as an argument. This function -should make the overlay visible permanently; it is used when the match -overlaps the overlay on exit from the search. - - During the search, such overlays are made temporarily visible by -temporarily modifying their invisible and intangible properties. If you -want this to be done differently for a certain overlay, give it an -@code{isearch-open-invisible-temporary} property which is a function. -The function is called with two arguments: the first is the overlay, and -the second is @code{nil} to make the overlay visible, or @code{t} to -make it invisible again. - -@node Selective Display -@section Selective Display -@c @cindex selective display Duplicates selective-display - - @dfn{Selective display} refers to a pair of related features for -hiding certain lines on the screen. - - The first variant, explicit selective display, is designed for use -in a Lisp program: it controls which lines are hidden by altering the -text. This kind of hiding in some ways resembles the effect of the -@code{invisible} property (@pxref{Invisible Text}), but the two -features are different and do not work the same way. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now hidden. Strictly -speaking, it is temporarily no longer a line at all, since only -newlines can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly -into hidden text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For -example, @code{next-line} skips hidden lines, since it searches only -for newlines. Modes that use selective display can also define -commands that take account of the newlines, or that control which -parts of the text are hidden. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing hidden. The selective display -effect is seen only within Emacs. - -@defvar selective-display -This buffer-local variable enables selective display. This means that -lines, or portions of lines, may be made hidden. - -@itemize @bullet -@item -If the value of @code{selective-display} is @code{t}, then the character -control-m marks the start of hidden text; the control-m, and the rest -of the line following it, are not displayed. This is explicit selective -display. - -@item -If the value of @code{selective-display} is a positive integer, then -lines that start with more than that many columns of indentation are not -displayed. -@end itemize - -When some portion of a buffer is hidden, the vertical movement -commands operate as if that portion did not exist, allowing a single -@code{next-line} command to skip any number of hidden lines. -However, character movement commands (such as @code{forward-char}) do -not skip the hidden portion, and it is possible (if tricky) to insert -or delete text in an hidden portion. - -In the examples below, we show the @emph{display appearance} of the -buffer @code{foo}, which changes with the value of -@code{selective-display}. The @emph{contents} of the buffer do not -change. - -@example -@group -(setq selective-display nil) - @result{} nil - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 3n this column - 3n this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group - -@group -(setq selective-display 2) - @result{} 2 - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example -@end defvar - -@defopt selective-display-ellipses -If this buffer-local variable is non-@code{nil}, then Emacs displays -@samp{@dots{}} at the end of a line that is followed by hidden text. -This example is a continuation of the previous one. - -@example -@group -(setq selective-display-ellipses t) - @result{} t - ----------- Buffer: foo ---------- -1 on this column - 2on this column ... - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example - -You can use a display table to substitute other text for the ellipsis -(@samp{@dots{}}). @xref{Display Tables}. -@end defopt - -@node Temporary Displays -@section Temporary Displays - - Temporary displays are used by Lisp programs to put output into a -buffer and then present it to the user for perusal rather than for -editing. Many help commands use this feature. - -@defspec with-output-to-temp-buffer buffer-name forms@dots{} -This function executes @var{forms} while arranging to insert any output -they print into the buffer named @var{buffer-name}, which is first -created if necessary, and put into Help mode. Finally, the buffer is -displayed in some window, but not selected. - -If the @var{forms} do not change the major mode in the output buffer, -so that it is still Help mode at the end of their execution, then -@code{with-output-to-temp-buffer} makes this buffer read-only at the -end, and also scans it for function and variable names to make them -into clickable cross-references. @xref{Docstring hyperlinks, , Tips -for Documentation Strings}, in particular the item on hyperlinks in -documentation strings, for more details. - -The string @var{buffer-name} specifies the temporary buffer, which -need not already exist. The argument must be a string, not a buffer. -The buffer is erased initially (with no questions asked), and it is -marked as unmodified after @code{with-output-to-temp-buffer} exits. - -@code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{forms}. Output -using the Lisp output functions within @var{forms} goes by default to -that buffer (but screen display and messages in the echo area, although -they are ``output'' in the general sense of the word, are not affected). -@xref{Output Functions}. - -Several hooks are available for customizing the behavior -of this construct; they are listed below. - -The value of the last form in @var{forms} is returned. - -@example -@group ----------- Buffer: foo ---------- - This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) -@result{} # - ----------- Buffer: foo ---------- -20 - -# - ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@defopt temp-buffer-show-function -If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} -calls it as a function to do the job of displaying a help buffer. The -function gets one argument, which is the buffer it should display. - -It is a good idea for this function to run @code{temp-buffer-show-hook} -just as @code{with-output-to-temp-buffer} normally would, inside of -@code{save-selected-window} and with the chosen window and buffer -selected. -@end defopt - -@defvar temp-buffer-setup-hook -This normal hook is run by @code{with-output-to-temp-buffer} before -evaluating @var{body}. When the hook runs, the temporary buffer is -current. This hook is normally set up with a function to put the -buffer in Help mode. -@end defvar - -@defvar temp-buffer-show-hook -This normal hook is run by @code{with-output-to-temp-buffer} after -displaying the temporary buffer. When the hook runs, the temporary buffer -is current, and the window it was displayed in is selected. -@end defvar - -@defun momentary-string-display string position &optional char message -This function momentarily displays @var{string} in the current buffer at -@var{position}. It has no effect on the undo list or on the buffer's -modification status. - -The momentary display remains until the next input event. If the next -input event is @var{char}, @code{momentary-string-display} ignores it -and returns. Otherwise, that event remains buffered for subsequent use -as input. Thus, typing @var{char} will simply remove the string from -the display, while typing (say) @kbd{C-f} will remove the string from -the display and later (presumably) move point forward. The argument -@var{char} is a space by default. - -The return value of @code{momentary-string-display} is not meaningful. - -If the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating (and then subsequently -deleting) an overlay with a @code{before-string} property. -@xref{Overlay Properties}. - -If @var{message} is non-@code{nil}, it is displayed in the echo area -while @var{string} is displayed in the buffer. If it is @code{nil}, a -default message says to type @var{char} to continue. - -In this example, point is initially located at the beginning of the -second line: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo. -@point{}Second line. ----------- Buffer: foo ---------- -@end group - -@group -(momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") -@result{} t -@end group - -@group ----------- Buffer: foo ---------- -This is the contents of foo. -**** Important Message! ****Second line. ----------- Buffer: foo ---------- - ----------- Echo Area ---------- -Type RET when done reading ----------- Echo Area ---------- -@end group -@end example -@end defun - -@node Overlays -@section Overlays -@cindex overlays - -You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen, for the sake of presentation features. An overlay is an -object that belongs to a particular buffer, and has a specified -beginning and end. It also has properties that you can examine and set; -these affect the display of the text within the overlay. - -@cindex scalability of overlays -The visual effect of an overlay is the same as of the corresponding -text property (@pxref{Text Properties}). However, due to a different -implementation, overlays generally don't scale well (many operations -take a time that is proportional to the number of overlays in the -buffer). If you need to affect the visual appearance of many portions -in the buffer, we recommend using text properties. - -An overlay uses markers to record its beginning and end; thus, -editing the text of the buffer adjusts the beginning and end of each -overlay so that it stays with the text. When you create the overlay, -you can specify whether text inserted at the beginning should be -inside the overlay or outside, and likewise for the end of the overlay. - -@menu -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. -@end menu - -@node Managing Overlays -@subsection Managing Overlays - - This section describes the functions to create, delete and move -overlays, and to examine their contents. Overlay changes are not -recorded in the buffer's undo list, since the overlays are not -part of the buffer's contents. - -@defun overlayp object -This function returns @code{t} if @var{object} is an overlay. -@end defun - -@defun make-overlay start end &optional buffer front-advance rear-advance -This function creates and returns an overlay that belongs to -@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} -and @var{end} must specify buffer positions; they may be integers or -markers. If @var{buffer} is omitted, the overlay is created in the -current buffer. - -The arguments @var{front-advance} and @var{rear-advance} specify the -marker insertion type for the start of the overlay and for the end of -the overlay, respectively. @xref{Marker Insertion Types}. If they -are both @code{nil}, the default, then the overlay extends to include -any text inserted at the beginning, but not text inserted at the end. -If @var{front-advance} is non-@code{nil}, text inserted at the -beginning of the overlay is excluded from the overlay. If -@var{rear-advance} is non-@code{nil}, text inserted at the end of the -overlay is included in the overlay. -@end defun - -@defun overlay-start overlay -This function returns the position at which @var{overlay} starts, -as an integer. -@end defun - -@defun overlay-end overlay -This function returns the position at which @var{overlay} ends, -as an integer. -@end defun - -@defun overlay-buffer overlay -This function returns the buffer that @var{overlay} belongs to. It -returns @code{nil} if @var{overlay} has been deleted. -@end defun - -@defun delete-overlay overlay -This function deletes @var{overlay}. The overlay continues to exist as -a Lisp object, and its property list is unchanged, but it ceases to be -attached to the buffer it belonged to, and ceases to have any effect on -display. - -A deleted overlay is not permanently disconnected. You can give it a -position in a buffer again by calling @code{move-overlay}. -@end defun - -@defun move-overlay overlay start end &optional buffer -This function moves @var{overlay} to @var{buffer}, and places its bounds -at @var{start} and @var{end}. Both arguments @var{start} and @var{end} -must specify buffer positions; they may be integers or markers. - -If @var{buffer} is omitted, @var{overlay} stays in the same buffer it -was already associated with; if @var{overlay} was deleted, it goes into -the current buffer. - -The return value is @var{overlay}. - -This is the only valid way to change the endpoints of an overlay. Do -not try modifying the markers in the overlay by hand, as that fails to -update other vital data structures and can cause some overlays to be -``lost.'' -@end defun - -@defun remove-overlays &optional start end name value -This function removes all the overlays between @var{start} and -@var{end} whose property @var{name} has the value @var{value}. It can -move the endpoints of the overlays in the region, or split them. - -If @var{name} is omitted or @code{nil}, it means to delete all overlays in -the specified region. If @var{start} and/or @var{end} are omitted or -@code{nil}, that means the beginning and end of the buffer respectively. -Therefore, @code{(remove-overlays)} removes all the overlays in the -current buffer. -@end defun - - Here are some examples: - -@example -;; @r{Create an overlay.} -(setq foo (make-overlay 1 10)) - @result{} # -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 10 -(overlay-buffer foo) - @result{} # -;; @r{Give it a property we can check later.} -(overlay-put foo 'happy t) - @result{} t -;; @r{Verify the property is present.} -(overlay-get foo 'happy) - @result{} t -;; @r{Move the overlay.} -(move-overlay foo 5 20) - @result{} # -(overlay-start foo) - @result{} 5 -(overlay-end foo) - @result{} 20 -;; @r{Delete the overlay.} -(delete-overlay foo) - @result{} nil -;; @r{Verify it is deleted.} -foo - @result{} # -;; @r{A deleted overlay has no position.} -(overlay-start foo) - @result{} nil -(overlay-end foo) - @result{} nil -(overlay-buffer foo) - @result{} nil -;; @r{Undelete the overlay.} -(move-overlay foo 1 20) - @result{} # -;; @r{Verify the results.} -(overlay-start foo) - @result{} 1 -(overlay-end foo) - @result{} 20 -(overlay-buffer foo) - @result{} # -;; @r{Moving and deleting the overlay does not change its properties.} -(overlay-get foo 'happy) - @result{} t -@end example - - Emacs stores the overlays of each buffer in two lists, divided -around an arbitrary ``center position.'' One list extends backwards -through the buffer from that center position, and the other extends -forwards from that center position. The center position can be anywhere -in the buffer. - -@defun overlay-recenter pos -This function recenters the overlays of the current buffer around -position @var{pos}. That makes overlay lookup faster for positions -near @var{pos}, but slower for positions far away from @var{pos}. -@end defun - - A loop that scans the buffer forwards, creating overlays, can run -faster if you do @code{(overlay-recenter (point-max))} first. - -@node Overlay Properties -@subsection Overlay Properties - - Overlay properties are like text properties in that the properties that -alter how a character is displayed can come from either source. But in -most respects they are different. @xref{Text Properties}, for comparison. - - Text properties are considered a part of the text; overlays and -their properties are specifically considered not to be part of the -text. Thus, copying text between various buffers and strings -preserves text properties, but does not try to preserve overlays. -Changing a buffer's text properties marks the buffer as modified, -while moving an overlay or changing its properties does not. Unlike -text property changes, overlay property changes are not recorded in -the buffer's undo list. - - Since more than one overlay can specify a property value for the -same character, Emacs lets you specify a priority value of each -overlay. You should not make assumptions about which overlay will -prevail when there is a conflict and they have the same priority. - - These functions read and set the properties of an overlay: - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - -@defun overlay-properties overlay -This returns a copy of the property list of @var{overlay}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - - Many overlay properties have special meanings; here is a table -of them: - -@table @code -@item priority -@kindex priority @r{(overlay property)} -This property's value (which should be a nonnegative integer number) -determines the priority of the overlay. No priority, or @code{nil}, -means zero. - -The priority matters when two or more overlays cover the same -character and both specify the same property; the one whose -@code{priority} value is larger overrides the other. For the -@code{face} property, the higher priority overlay's value does not -completely override the other value; instead, its face attributes -override the face attributes of the lower priority @code{face} -property. - -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. - -@item window -@kindex window @r{(overlay property)} -If the @code{window} property is non-@code{nil}, then the overlay -applies only on that window. - -@item category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the way text is displayed---for example, which -font and which colors. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities: - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the form (@var{keyword} -@var{value} @dots{}), where each @var{keyword} is a face attribute -name and @var{value} is a meaningful value for that attribute. With -this feature, you do not need to create a face each time you want to -specify a particular attribute for certain text. @xref{Face -Attributes}. - -@item -A cons cell, either of the form @code{(foreground-color . @var{color-name})} or -@code{(background-color . @var{color-name})}. These elements specify -just the foreground color or just the background color. - -@code{(foreground-color . @var{color-name})} has the same effect as -@code{(:foreground @var{color-name})}; likewise for the background. -@end itemize - -@item mouse-face -@kindex mouse-face @r{(overlay property)} -This property is used instead of @code{face} when the mouse is within -the range of the overlay. - -@item display -@kindex display @r{(overlay property)} -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrower, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(overlay property)} -If an overlay has a @code{help-echo} property, then when you move the -mouse onto the text in the overlay, Emacs displays a help string in the -echo area, or in the tooltip window. For details see @ref{Text -help-echo}. - -@item modification-hooks -@kindex modification-hooks @r{(overlay property)} -This property's value is a list of functions to be called if any -character within the overlay is changed or if text is inserted strictly -within the overlay. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Text properties also support the @code{modification-hooks} property, -but the details are somewhat different (@pxref{Special Properties}). - -@item insert-in-front-hooks -@kindex insert-in-front-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. - -@item isearch-open-invisible -This property tells incremental search how to make an invisible overlay -visible, permanently, if the final match overlaps it. @xref{Invisible -Text}. - -@item isearch-open-invisible-temporary -This property tells incremental search how to make an invisible overlay -visible, temporarily, during the search. @xref{Invisible Text}. - -@item before-string -@kindex before-string @r{(overlay property)} -This property's value is a string to add to the display at the beginning -of the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item after-string -@kindex after-string @r{(overlay property)} -This property's value is a string to add to the display at the end of -the overlay. The string does not appear in the buffer in any -sense---only on the screen. - -@item line-prefix -This property specifies a display spec to prepend to each -non-continuation line at display-time. @xref{Truncation}. - -@itemx wrap-prefix -This property specifies a display spec to prepend to each continuation -line at display-time. @xref{Truncation}. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. - -@item local-map -@cindex keymap of character (and overlays) -@kindex local-map @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. - -@item keymap -@kindex keymap @r{(overlay property)} -The @code{keymap} property is similar to @code{local-map} but overrides the -buffer's local map (and the map specified by the @code{local-map} -property) rather than replacing it. -@end table - -The @code{local-map} and @code{keymap} properties do not affect a -string displayed by the @code{before-string}, @code{after-string}, or -@code{display} properties. This is only relevant for mouse clicks and -other mouse events that fall on the string, since point is never on -the string. To bind special mouse events for the string, assign it a -@code{local-map} or @code{keymap} text property. @xref{Special -Properties}. - -@node Finding Overlays -@subsection Searching for Overlays - -@defun overlays-at pos -This function returns a list of all the overlays that cover the -character at position @var{pos} in the current buffer. The list is in -no particular order. An overlay contains position @var{pos} if it -begins at or before @var{pos}, and ends after @var{pos}. - -To illustrate usage, here is a Lisp function that returns a list of the -overlays that specify property @var{prop} for the character at point: - -@smallexample -(defun find-overlays-specifying (prop) - (let ((overlays (overlays-at (point))) - found) - (while overlays - (let ((overlay (car overlays))) - (if (overlay-get overlay prop) - (setq found (cons overlay found)))) - (setq overlays (cdr overlays))) - found)) -@end smallexample -@end defun - -@defun overlays-in beg end -This function returns a list of the overlays that overlap the region -@var{beg} through @var{end}. ``Overlap'' means that at least one -character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located at @var{beg}, strictly between @var{beg} and @var{end}, -or at @var{end} when @var{end} denotes the position at the end of the -buffer. -@end defun - -@defun next-overlay-change pos -This function returns the buffer position of the next beginning or end -of an overlay, after @var{pos}. If there is none, it returns -@code{(point-max)}. -@end defun - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @var{pos}. If there is none, it returns -@code{(point-min)}. -@end defun - - As an example, here's a simplified (and inefficient) version of the -primitive function @code{next-single-char-property-change} -(@pxref{Property Search}). It searches forward from position -@var{pos} for the next position where the value of a given property -@code{prop}, as obtained from either overlays or text properties, -changes. - -@smallexample -(defun next-single-char-property-change (position prop) - (save-excursion - (goto-char position) - (let ((propval (get-char-property (point) prop))) - (while (and (not (eobp)) - (eq (get-char-property (point) prop) propval)) - (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) prop))))) - (point))) -@end smallexample - -@node Width -@section Width - -Since not all characters have the same width, these functions let you -check the width of a character. @xref{Primitive Indent}, and -@ref{Screen Lines}, for related functions. - -@defun char-width char -This function returns the width in columns of the character @var{char}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun string-width string -This function returns the width in columns of the string @var{string}, -if it were displayed in the current buffer and the selected window. -@end defun - -@defun truncate-string-to-width string width &optional start-column padding ellipsis -This function returns the part of @var{string} that fits within -@var{width} columns, as a new string. - -If @var{string} does not reach @var{width}, then the result ends where -@var{string} ends. If one multi-column character in @var{string} -extends across the column @var{width}, that character is not included in -the result. Thus, the result can fall short of @var{width} but cannot -go beyond it. - -The optional argument @var{start-column} specifies the starting column. -If this is non-@code{nil}, then the first @var{start-column} columns of -the string are omitted from the value. If one multi-column character in -@var{string} extends across the column @var{start-column}, that -character is not included. - -The optional argument @var{padding}, if non-@code{nil}, is a padding -character added at the beginning and end of the result string, to extend -it to exactly @var{width} columns. The padding character is used at the -end of the result if it falls short of @var{width}. It is also used at -the beginning of the result if one multi-column character in -@var{string} extends across the column @var{start-column}. - -If @var{ellipsis} is non-@code{nil}, it should be a string which will -replace the end of @var{str} (including any padding) if it extends -beyond @var{end-column}, unless the display width of @var{str} is -equal to or less than the display width of @var{ellipsis}. If -@var{ellipsis} is non-@code{nil} and not a string, it stands for -@code{"..."}. - -@example -(truncate-string-to-width "\tab\t" 12 4) - @result{} "ab" -(truncate-string-to-width "\tab\t" 12 4 ?\s) - @result{} " ab " -@end example -@end defun - -@node Line Height -@section Line Height -@cindex line height - - The total height of each display line consists of the height of the -contents of the line, plus optional additional vertical line spacing -above or below the display line. - - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) - - There are several ways to explicitly specify a larger line height, -either by specifying an absolute height for the display line, or by -specifying vertical space. However, no matter what you specify, the -actual line height can never be less than the default. - -@kindex line-height @r{(text property)} - A newline can have a @code{line-height} text or overlay property -that controls the total height of the display line ending in that -newline. - - If the property value is @code{t}, the newline character has no -effect on the displayed height of the line---the visible contents -alone determine the height. This is useful for tiling small images -(or image slices) without adding blank areas between the images. - - If the property value is a list of the form @code{(@var{height} -@var{total})}, that adds extra space @emph{below} the display line. -First Emacs uses @var{height} as a height spec to control extra space -@emph{above} the line; then it adds enough space @emph{below} the line -to bring the total line height up to @var{total}. In this case, the -other ways to specify the line spacing are ignored. - - Any other kind of property value is a height spec, which translates -into a number---the specified line height. There are several ways to -write a height spec; here's how each of them translates into a number: - -@table @code -@item @var{integer} -If the height spec is a positive integer, the height value is that integer. -@item @var{float} -If the height spec is a float, @var{float}, the numeric height value -is @var{float} times the frame's default line height. -@item (@var{face} . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of face @var{face}. @var{ratio} can -be any type of number, or @code{nil} which means a ratio of 1. -If @var{face} is @code{t}, it refers to the current face. -@item (nil . @var{ratio}) -If the height spec is a cons of the format shown, the numeric height -is @var{ratio} times the height of the contents of the line. -@end table - - Thus, any valid height spec determines the height in pixels, one way -or another. If the line contents' height is less than that, Emacs -adds extra vertical space above the line to achieve the specified -total height. - - If you don't specify the @code{line-height} property, the line's -height consists of the contents' height plus the line spacing. -There are several ways to specify the line spacing for different -parts of Emacs text. - -@vindex default-line-spacing - On graphical terminals, you can specify the line spacing for all -lines in a frame, using the @code{line-spacing} frame parameter -(@pxref{Layout Parameters}). However, if the variable -@code{default-line-spacing} is non-@code{nil}, it overrides the -frame's @code{line-spacing} parameter. An integer value specifies the -number of pixels put below lines. A floating point number specifies -the spacing relative to the frame's default line height. - -@vindex line-spacing - You can specify the line spacing for all lines in a buffer via the -buffer-local @code{line-spacing} variable. An integer value specifies -the number of pixels put below lines. A floating point number -specifies the spacing relative to the default frame line height. This -overrides line spacings specified for the frame. - -@kindex line-spacing @r{(text property)} - Finally, a newline can have a @code{line-spacing} text or overlay -property that overrides the default frame line spacing and the buffer -local @code{line-spacing} variable, for the display line ending in -that newline. - - One way or another, these mechanisms specify a Lisp value for the -spacing of each line. The value is a height spec, and it translates -into a Lisp value as described above. However, in this case the -numeric height value specifies the line spacing, rather than the line -height. - - On text-only terminals, the line spacing cannot be altered. - -@node Faces -@section Faces -@cindex faces - - A @dfn{face} is a collection of graphical attributes for displaying -text: font family, foreground color, background color, optional -underlining, and so on. Faces control how buffer text is displayed, -and how some parts of the frame, such as the mode-line, are displayed. -@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of -faces Emacs normally comes with. - -@cindex face id - For most purposes, you refer to a face in Lisp programs using its -@dfn{face name}. This is either a string or (equivalently) a Lisp -symbol whose name is equal to that string. - -@defun facep object -This function returns a non-@code{nil} value if @var{object} is a Lisp -symbol or string that names a face. Otherwise, it returns @code{nil}. -@end defun - - Each face name is meaningful for all frames, and by default it has -the same meaning in all frames. But you can arrange to give a -particular face name a special meaning in one frame if you wish. - -@menu -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. -@end menu - -@node Defining Faces -@subsection Defining Faces - - The way to define a new face is with @code{defface}. This creates a -kind of customization item (@pxref{Customization}) which the user can -customize using the Customization buffer (@pxref{Easy Customization,,, -emacs, The GNU Emacs Manual}). - - People are sometimes tempted to create variables whose values specify -which faces to use (for example, Font-Lock does this). In the vast -majority of cases, this is not necessary, and simply using faces -directly is preferable. - -@defmac defface face spec doc [keyword value]@dots{} -This declares @var{face} as a customizable face whose default -attributes are given by @var{spec}. You should not quote the symbol -@var{face}, and it should not end in @samp{-face} (that would be -redundant). The argument @var{doc} specifies the face documentation. -The keywords you can use in @code{defface} are the same as in -@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}). - -When @code{defface} executes, it defines the face according to -@var{spec}, then uses any customizations that were read from the -init file (@pxref{Init File}) to override that specification. - -When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs -Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} -overrides any customizations of the face. This way, the face reflects -exactly what the @code{defface} says. - -The purpose of @var{spec} is to specify how the face should appear on -different kinds of terminals. It should be an alist whose elements -have the form @code{(@var{display} @var{atts})}. Each element's -@sc{car}, @var{display}, specifies a class of terminals. (The first -element, if its @sc{car} is @code{default}, is special---it specifies -defaults for the remaining elements). The element's @sc{cadr}, -@var{atts}, is a list of face attributes and their values; it -specifies what the face should look like on that kind of terminal. -The possible attributes are defined in the value of -@code{custom-face-attributes}. - -The @var{display} part of an element of @var{spec} determines which -frames the element matches. If more than one element of @var{spec} -matches a given frame, the first element that matches is the one used -for that frame. There are three possibilities for @var{display}: - -@table @asis -@item @code{default} -This element of @var{spec} doesn't match any frames; instead, it -specifies defaults that apply to all frames. This kind of element, if -used, must be the first element of @var{spec}. Each of the following -elements can override any or all of these defaults. - -@item @code{t} -This element of @var{spec} matches all frames. Therefore, any -subsequent elements of @var{spec} are never used. Normally -@code{t} is used in the last (or only) element of @var{spec}. - -@item a list -If @var{display} is a list, each element should have the form -@code{(@var{characteristic} @var{value}@dots{})}. Here -@var{characteristic} specifies a way of classifying frames, and the -@var{value}s are possible classifications which @var{display} should -apply to. Here are the possible values of @var{characteristic}: - -@table @code -@item type -The kind of window system the frame uses---either @code{graphic} (any -graphics-capable display), @code{x}, @code{pc} (for the MS-DOS console), -@code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} -(a non-graphics-capable display). -@xref{Window Systems, window-system}. - -@item class -What kinds of colors the frame supports---either @code{color}, -@code{grayscale}, or @code{mono}. - -@item background -The kind of background---either @code{light} or @code{dark}. - -@item min-colors -An integer that represents the minimum number of colors the frame -should support. This matches a frame if its -@code{display-color-cells} value is at least the specified integer. - -@item supports -Whether or not the frame can display the face attributes given in -@var{value}@dots{} (@pxref{Face Attributes}). @xref{Display Face -Attribute Testing}, for more information on exactly how this testing -is done. -@end table - -If an element of @var{display} specifies more than one @var{value} for a -given @var{characteristic}, any of those values is acceptable. If -@var{display} has more than one element, each element should specify a -different @var{characteristic}; then @emph{each} characteristic of the -frame must match one of the @var{value}s specified for it in -@var{display}. -@end table -@end defmac - - Here's how the standard face @code{region} is defined: - -@example -@group -(defface region - '((((class color) (min-colors 88) (background dark)) - :background "blue3") -@end group - (((class color) (min-colors 88) (background light)) - :background "lightgoldenrod2") - (((class color) (min-colors 16) (background dark)) - :background "blue3") - (((class color) (min-colors 16) (background light)) - :background "lightgoldenrod2") - (((class color) (min-colors 8)) - :background "blue" :foreground "white") - (((type tty) (class mono)) - :inverse-video t) - (t :background "gray")) -@group - "Basic face for highlighting the region." - :group 'basic-faces) -@end group -@end example - - Internally, @code{defface} uses the symbol property -@code{face-defface-spec} to record the specified face attributes. The -attributes saved by the user with the customization buffer are -recorded in the symbol property @code{saved-face}; the attributes -customized by the user for the current session, but not saved, are -recorded in the symbol property @code{customized-face}. The -documentation string is recorded in the symbol property -@code{face-documentation}. - -@defopt frame-background-mode -This option, if non-@code{nil}, specifies the background type to use for -interpreting face definitions. If it is @code{dark}, then Emacs treats -all frames as if they had a dark background, regardless of their actual -background colors. If it is @code{light}, then Emacs treats all frames -as if they had a light background. -@end defopt - -@node Face Attributes -@subsection Face Attributes -@cindex face attributes - - The effect of using a face is determined by a fixed set of @dfn{face -attributes}. This table lists all the face attributes, their possible -values, and their effects. You can specify more than one face for a -given piece of text; Emacs merges the attributes of all the faces to -determine how to display the text. @xref{Displaying Faces}. - - In addition to the values given below, each face attribute can also -have the value @code{unspecified}. This special value means the face -doesn't specify that attribute. In face merging, when the first face -fails to specify a particular attribute, the next face gets a chance. -However, the @code{default} face must specify all attributes. - - Some of these font attributes are meaningful only on certain kinds -of displays. If your display cannot handle a certain attribute, the -attribute is ignored. - -@table @code -@item :family -Font family name or fontset name (a string). If you specify a font -family name, the wild-card characters @samp{*} and @samp{?} are -allowed. The function @code{font-family-list}, described below, -returns a list of available family names. @xref{Fontsets}, for -information about fontsets. - -@item :foundry -The name of the @dfn{font foundry} in which the font family specified -by the @code{:family} attribute is located (a string). The wild-card -characters @samp{*} and @samp{?} are allowed. - -@item :width -Relative proportionate character width, also known as the character -set width. This should be one of the symbols @code{ultra-condensed}, -@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, -@code{normal}, @code{semi-expanded}, @code{expanded}, -@code{extra-expanded}, or @code{ultra-expanded}. - -@item :height -Font height---either an integer in units of 1/10 point, or a floating -point number specifying the amount by which to scale the height of any -underlying face, or a function that is called with one argument (the -height of the underlying face) and returns the height of the new face. -If the function is passed an integer argument, it must return an -integer. - -The height of the default face must be specified using an integer; -floating point and function values are not allowed. - -@item :weight -Font weight---one of the symbols (from densest to faintest) -@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, -@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, or -@code{ultra-light}. On text-only terminals that support -variable-brightness text, any weight greater than normal is displayed -as extra bright, and any weight less than normal is displayed as -half-bright. - -@item :slant -Font slant---one of the symbols @code{italic}, @code{oblique}, -@code{normal}, @code{reverse-italic}, or @code{reverse-oblique}. On -text-only terminals that support variable-brightness text, slanted -text is displayed as half-bright. - -@item :foreground -Foreground color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. On -black-and-white displays, certain shades of gray are implemented by -stipple patterns. - -@item :background -Background color, a string. The value can be a system-defined color -name, or a hexadecimal color specification. @xref{Color Names}. - -@item :underline -Whether or not characters should be underlined, and in what color. If -the value is @code{t}, underlining uses the foreground color of the -face. If the value is a string, underlining uses that color. The -value @code{nil} means do not underline. - -@item :overline -Whether or not characters should be overlined, and in what color. -The value is used like that of @code{:underline}. - -@item :strike-through -Whether or not characters should be strike-through, and in what -color. The value is used like that of @code{:underline}. - -@item :box -Whether or not a box should be drawn around characters, its color, the -width of the box lines, and 3D appearance. Here are the possible -values of the @code{:box} attribute, and what they mean: - -@table @asis -@item @code{nil} -Don't draw a box. - -@item @code{t} -Draw a box with lines of width 1, in the foreground color. - -@item @var{color} -Draw a box with lines of width 1, in color @var{color}. - -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to 1. - -The value @var{color} specifies the color to draw with. The default is -the foreground color of the face for simple boxes, and the background -color of the face for 3D boxes. - -The value @var{style} specifies whether to draw a 3D box. If it is -@code{released-button}, the box looks like a 3D button that is not being -pressed. If it is @code{pressed-button}, the box looks like a 3D button -that is being pressed. If it is @code{nil} or omitted, a plain 2D box -is used. -@end table - -@item :inverse-video -Whether or not characters should be displayed in inverse video. The -value should be @code{t} (yes) or @code{nil} (no). - -@item :stipple -The background stipple, a bitmap. - -The value can be a string; that should be the name of a file containing -external-format X bitmap data. The file is found in the directories -listed in the variable @code{x-bitmap-file-path}. - -Alternatively, the value can specify the bitmap directly, with a list -of the form @code{(@var{width} @var{height} @var{data})}. Here, -@var{width} and @var{height} specify the size in pixels, and -@var{data} is a string containing the raw bits of the bitmap, row by -row. Each row occupies @math{(@var{width} + 7) / 8} consecutive bytes -in the string (which should be a unibyte string for best results). -This means that each row always occupies at least one whole byte. - -If the value is @code{nil}, that means use no stipple pattern. - -Normally you do not need to set the stipple attribute, because it is -used automatically to handle certain shades of gray. - -@item :font -The font used to display the face. Its value should be a font object. -@xref{Font Selection}, for information about font objects. - -When specifying this attribute using @code{set-face-attribute} -(@pxref{Attribute Functions}), you may also supply a font spec, a font -entity, or a string. Emacs converts such values to an appropriate -font object, and stores that font object as the actual attribute -value. If you specify a string, the contents of the string should be -a font name (@pxref{Font X,, Font Specification Options, emacs, The -GNU Emacs Manual}); if the font name is an XLFD containing wildcards, -Emacs chooses the first font matching those wildcards. Specifying -this attribute also changes the values of the @code{:family}, -@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and -@code{:slant} attributes. - -@item :inherit -The name of a face from which to inherit attributes, or a list of face -names. Attributes from inherited faces are merged into the face like -an underlying face would be, with higher priority than underlying -faces. If a list of faces is used, attributes from faces earlier in -the list override those from later faces. -@end table - -For compatibility with Emacs 20, you can also specify values for two -``fake'' face attributes: @code{:bold} and @code{:italic}. Their -values must be either @code{t} or @code{nil}; a value of -@code{unspecified} is not allowed. Setting @code{:bold} to @code{t} -is equivalent to setting the @code{:weight} attribute to @code{bold}, -and setting it to @code{nil} is equivalent to setting @code{:weight} -to @code{normal}. Setting @code{:italic} to @code{t} is equivalent to -setting the @code{:slant} attribute to @code{italic}, and setting it -to @code{nil} is equivalent to setting @code{:slant} to @code{normal}. - -@defun font-family-list &optional frame -This function returns a list of available font family names. The -optional argument @var{frame} specifies the frame on which the text is -to be displayed; if it is @code{nil}, the selected frame is used. -@end defun - -@defopt underline-minimum-offset -This variable specifies the minimum distance between the baseline and -the underline, in pixels, when displaying underlined text. -@end defopt - -@defopt x-bitmap-file-path -This variable specifies a list of directories for searching -for bitmap files, for the @code{:stipple} attribute. -@end defopt - -@defun bitmap-spec-p object -This returns @code{t} if @var{object} is a valid bitmap specification, -suitable for use with @code{:stipple} (see above). It returns -@code{nil} otherwise. -@end defun - -@node Attribute Functions -@subsection Face Attribute Functions - - This section describes the functions for accessing and modifying the -attributes of an existing face. - -@defun set-face-attribute face frame &rest arguments -This function sets one or more attributes of @var{face} for -@var{frame}. The attributes you specify this way override whatever -the @code{defface} says. - -The extra arguments @var{arguments} specify the attributes to set, and -the values for them. They should consist of alternating attribute names -(such as @code{:family} or @code{:underline}) and corresponding values. -Thus, - -@example -(set-face-attribute 'foo nil - :width 'extended - :weight 'bold - :underline "red") -@end example - -@noindent -sets the attributes @code{:width}, @code{:weight} and @code{:underline} -to the corresponding values. - -If @var{frame} is @code{t}, this function sets the default attributes -for new frames. Default attribute values specified this way override -the @code{defface} for newly created frames. - -If @var{frame} is @code{nil}, this function sets the attributes for -all existing frames, and the default for new frames. -@end defun - -@defun face-attribute face attribute &optional frame inherit -This returns the value of the @var{attribute} attribute of @var{face} -on @var{frame}. If @var{frame} is @code{nil}, that means the selected -frame (@pxref{Input Focus}). - -If @var{frame} is @code{t}, this returns whatever new-frames default -value you previously specified with @code{set-face-attribute} for the -@var{attribute} attribute of @var{face}. If you have not specified -one, it returns @code{nil}. - -If @var{inherit} is @code{nil}, only attributes directly defined by -@var{face} are considered, so the return value may be -@code{unspecified}, or a relative value. If @var{inherit} is -non-@code{nil}, @var{face}'s definition of @var{attribute} is merged -with the faces specified by its @code{:inherit} attribute; however the -return value may still be @code{unspecified} or relative. If -@var{inherit} is a face or a list of faces, then the result is further -merged with that face (or faces), until it becomes specified and -absolute. - -To ensure that the return value is always specified and absolute, use -a value of @code{default} for @var{inherit}; this will resolve any -unspecified or relative values by merging with the @code{default} face -(which is always completely specified). - -For example, - -@example -(face-attribute 'bold :weight) - @result{} bold -@end example -@end defun - -@defun face-attribute-relative-p attribute value -This function returns non-@code{nil} if @var{value}, when used as the -value of the face attribute @var{attribute}, is relative. This means -it would modify, rather than completely override, any value that comes -from a subsequent face in the face list or that is inherited from -another face. - -@code{unspecified} is a relative value for all attributes. For -@code{:height}, floating point and function values are also relative. - -For example: - -@example -(face-attribute-relative-p :height 2.0) - @result{} t -@end example -@end defun - -@defun face-all-attributes face &optional frame -This function returns an alist of attributes of @var{face}. The -elements of the result are name-value pairs of the form -@w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument -@var{frame} specifies the frame whose definition of @var{face} to -return; if omitted or @code{nil}, the returned value describes the -default attributes of @var{face} for newly created frames. -@end defun - -@defun merge-face-attribute attribute value1 value2 -If @var{value1} is a relative value for the face attribute -@var{attribute}, returns it merged with the underlying value -@var{value2}; otherwise, if @var{value1} is an absolute value for the -face attribute @var{attribute}, returns @var{value1} unchanged. -@end defun - - The following functions provide compatibility with Emacs 20 and -below. They work by calling @code{set-face-attribute}. Values of -@code{t} and @code{nil} for their @var{frame} argument are handled -just like @code{set-face-attribute} and @code{face-attribute}. - -@defun set-face-foreground face color &optional frame -@defunx set-face-background face color &optional frame -These functions set the @code{:foreground} attribute (or -@code{:background} attribute, respectively) of @var{face} to -@var{color}. -@end defun - -@defun set-face-stipple face pattern &optional frame -This function sets the @code{:stipple} attribute of @var{face} to -@var{pattern}. -@end defun - -@defun set-face-font face font &optional frame -This function sets the @code{:font} attribute of @var{face} to -@var{font}. -@end defun - -@defun set-face-bold-p face bold-p &optional frame -This function sets the @code{:weight} attribute of @var{face} to -@var{normal} if @var{bold-p} is @code{nil}, and to @var{bold} -otherwise. -@end defun - -@defun set-face-italic-p face italic-p &optional frame -This function sets the @code{:slant} attribute of @var{face} to -@var{normal} if @var{italic-p} is @code{nil}, and to @var{italic} -otherwise. -@end defun - -@defun set-face-underline-p face underline &optional frame -This function sets the @code{:underline} attribute of @var{face} to -@var{underline}. -@end defun - -@defun set-face-inverse-video-p face inverse-video-p &optional frame -This function sets the @code{:inverse-video} attribute of @var{face} -to @var{inverse-video-p}. -@end defun - -@defun invert-face face &optional frame -This function swaps the foreground and background colors of face -@var{face}. -@end defun - - The following functions examine the attributes of a face. If you -don't specify @var{frame}, they refer to the selected frame; @code{t} -refers to the default data for new frames. They return the symbol -@code{unspecified} if the face doesn't define any value for that -attribute. - -@defun face-foreground face &optional frame inherit -@defunx face-background face &optional frame inherit -These functions return the foreground color (or background color, -respectively) of face @var{face}, as a string. - -If @var{inherit} is @code{nil}, only a color directly defined by the face is -returned. If @var{inherit} is non-@code{nil}, any faces specified by its -@code{:inherit} attribute are considered as well, and if @var{inherit} -is a face or a list of faces, then they are also considered, until a -specified color is found. To ensure that the return value is always -specified, use a value of @code{default} for @var{inherit}. -@end defun - -@defun face-stipple face &optional frame inherit -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. - -If @var{inherit} is @code{nil}, only a stipple directly defined by the -face is returned. If @var{inherit} is non-@code{nil}, any faces -specified by its @code{:inherit} attribute are considered as well, and -if @var{inherit} is a face or a list of faces, then they are also -considered, until a specified stipple is found. To ensure that the -return value is always specified, use a value of @code{default} for -@var{inherit}. -@end defun - -@defun face-font face &optional frame -This function returns the name of the font of face @var{face}. -@end defun - -@defun face-bold-p face &optional frame -This function returns a non-@code{nil} value if the @code{:weight} -attribute of @var{face} is bolder than normal (i.e., one of -@code{semi-bold}, @code{bold}, @code{extra-bold}, or -@code{ultra-bold}). Otherwise, it returns @code{nil}. -@end defun - -@defun face-italic-p face &optional frame -This function returns a non-@code{nil} value if the @code{:slant} -attribute of @var{face} is @code{italic} or @code{oblique}, and -@code{nil} otherwise. -@end defun - -@defun face-underline-p face &optional frame -This function returns the @code{:underline} attribute of face @var{face}. -@end defun - -@defun face-inverse-video-p face &optional frame -This function returns the @code{:inverse-video} attribute of face @var{face}. -@end defun - -@node Displaying Faces -@subsection Displaying Faces - - Here is how Emacs determines the face to use for displaying any -given piece of text: - -@itemize @bullet -@item -If the text consists of a special glyph, the glyph can specify a -particular face. @xref{Glyphs}. - -@item -If the text lies within an active region, Emacs highlights it using -the @code{region} face. @xref{Standard Faces,,, emacs, The GNU Emacs -Manual}. - -@item -If the text lies within an overlay with a non-@code{nil} @code{face} -property, Emacs applies the face or face attributes specified by that -property. If the overlay has a @code{mouse-face} property and the -mouse is ``near enough'' to the overlay, Emacs applies the face or -face attributes specified by the @code{mouse-face} property instead. -@xref{Overlay Properties}. - -When multiple overlays cover one character, an overlay with higher -priority overrides those with lower priority. @xref{Overlays}. - -@item -If the text contains a @code{face} or @code{mouse-face} property, -Emacs applies the specified faces and face attributes. @xref{Special -Properties}. (This is how Font Lock mode faces are applied. -@xref{Font Lock Mode}.) - -@item -If the text lies within the mode line of the selected window, Emacs -applies the @code{mode-line} face. For the mode line of a -non-selected window, Emacs applies the @code{mode-line-inactive} face. -For a header line, Emacs applies the @code{header-line} face. - -@item -If any given attribute has not been specified during the preceding -steps, Emacs applies the attribute of the @code{default} face. -@end itemize - - If these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various faces -specified. For each attribute, Emacs tries using the above order -(i.e., first the face of any special glyph; then the face for region -highlighting, if appropriate; then faces specified by overlays, then -faces specified by text properties, then the @code{mode-line} or -@code{mode-line-inactive} or @code{header-line} face, if appropriate, -and finally the @code{default} face). - -@node Face Remapping -@subsection Face Remapping - - The variable @code{face-remapping-alist} is used for buffer-local or -global changes in the appearance of a face. For instance, it can be -used to make the @code{default} face a variable-pitch face within a -particular buffer. - -@defvar face-remapping-alist -An alist whose elements have the form @code{(@var{face} -@var{remapping...})}. This causes Emacs to display text using the -face @var{face} using @var{remapping...} instead of @var{face}'s -ordinary definition. @var{remapping...} may be any face specification -suitable for a @code{face} text property: either a face name, or a -property list of attribute/value pairs. @xref{Special Properties}. - -If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. - -Two points bear emphasizing: - -@enumerate -@item -The new definition @var{remapping...} is the complete -specification of how to display @var{face}---it entirely replaces, -rather than augmenting or modifying, the normal definition of that -face. - -@item -If @var{remapping...} recursively references the same face name -@var{face}, either directly remapping entry, or via the -@code{:inherit} attribute of some other face in @var{remapping...}, -then that reference uses the normal definition of @var{face} in the -selected frame, instead of the ``remapped'' definition. - -For instance, if the @code{mode-line} face is remapped using this -entry in @code{face-remapping-alist}: -@example -(mode-line italic mode-line) -@end example -@noindent -then the new definition of the @code{mode-line} face inherits from the -@code{italic} face, and the @emph{normal} (non-remapped) definition of -@code{mode-line} face. -@end enumerate -@end defvar - - A typical use of the @code{face-remapping-alist} is to change a -buffer's @code{default} face; for example, the following changes a -buffer's @code{default} face to use the @code{variable-pitch} face, -with the height doubled: - -@example -(set (make-local-variable 'face-remapping-alist) - '((default variable-pitch :height 2.0))) -@end example - - The following functions implement a higher-level interface to -@code{face-remapping-alist}, making it easier to use -``cooperatively''. They are mainly intended for buffer-local use, and -so all make @code{face-remapping-alist} variable buffer-local as a -side-effect. They use entries in @code{face-remapping-alist} which -have the general form: - -@example - (@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs}) -@end example - -Everything except @var{face} is a ``face spec'': a list of face names -or face attribute-value pairs. All face specs are merged together, -with earlier values taking precedence. - -The @var{relative_specs_}n values are ``relative specs'', and are -added by @code{face-remap-add-relative} (and removed by -@code{face-remap-remove-relative}. These are intended for face -modifications (such as increasing the size). Typical users of these -relative specs would be minor modes. - -@var{base_specs} is the lowest-priority value, and by default is just the -face name, which causes the global definition of that face to be used. - -A non-default value of @var{base_specs} may also be set using -@code{face-remap-set-base}. Because this @emph{overwrites} the -default base-spec value (which inherits the global face definition), -it is up to the caller of @code{face-remap-set-base} to add such -inheritance if it is desired. A typical use of -@code{face-remap-set-base} would be a major mode adding a face -remappings, e.g., of the default face. - - -@defun face-remap-add-relative face &rest specs -This functions adds a face remapping entry of @var{face} to @var{specs} -in the current buffer. - -It returns a ``cookie'' which can be used to later delete the remapping with -@code{face-remap-remove-relative}. - -@var{specs} can be any value suitable for the @code{face} text -property, including a face name, a list of face names, or a -face-attribute property list. The attributes given by @var{specs} -will be merged with any other currently active face remappings of -@var{face}, and with the global definition of @var{face} (by default; -this may be changed using @code{face-remap-set-base}), with the most -recently added relative remapping taking precedence. -@end defun - -@defun face-remap-remove-relative cookie -This function removes a face remapping previously added by -@code{face-remap-add-relative}. @var{cookie} should be a return value -from that function. -@end defun - -@defun face-remap-set-base face &rest specs -This function sets the ``base remapping'' of @var{face} in the current -buffer to @var{specs}. If @var{specs} is empty, the default base -remapping is restored, which inherits from the global definition of -@var{face}; note that this is different from @var{specs} containing a -single value @code{nil}, which has the opposite result (the global -definition of @var{face} is ignored). -@end defun - -@defun face-remap-reset-base face -This function sets the ``base remapping'' of @var{face} to its default -value, which inherits from @var{face}'s global definition. -@end defun - -@node Face Functions -@subsection Functions for Working with Faces - - Here are additional functions for creating and working with faces. - -@defun make-face name -This function defines a new face named @var{name}, initially with all -attributes @code{nil}. It does nothing if there is already a face named -@var{name}. -@end defun - -@defun face-list -This function returns a list of all defined face names. -@end defun - -@defun copy-face old-face new-name &optional frame new-frame -This function defines a face named @var{new-name} as a copy of the existing -face named @var{old-face}. It creates the face @var{new-name} if that -doesn't already exist. - -If the optional argument @var{frame} is given, this function applies -only to that frame. Otherwise it applies to each frame individually, -copying attributes from @var{old-face} in each frame to @var{new-face} -in the same frame. - -If the optional argument @var{new-frame} is given, then @code{copy-face} -copies the attributes of @var{old-face} in @var{frame} to @var{new-name} -in @var{new-frame}. -@end defun - -@defun face-id face -This function returns the @dfn{face number} of face @var{face}. This -is a number that uniquely identifies a face at low levels within -Emacs. It is seldom necessary to refer to a face by its face number. -@end defun - -@defun face-documentation face -This function returns the documentation string of face @var{face}, or -@code{nil} if none was specified for it. -@end defun - -@defun face-equal face1 face2 &optional frame -This returns @code{t} if the faces @var{face1} and @var{face2} have the -same attributes for display. -@end defun - -@defun face-differs-from-default-p face &optional frame -This returns non-@code{nil} if the face @var{face} displays -differently from the default face. -@end defun - -@cindex face alias -A @dfn{face alias} provides an equivalent name for a face. You can -define a face alias by giving the alias symbol the @code{face-alias} -property, with a value of the target face name. The following example -makes @code{modeline} an alias for the @code{mode-line} face. - -@example -(put 'modeline 'face-alias 'mode-line) -@end example - -@node Auto Faces -@subsection Automatic Face Assignment -@cindex automatic face assignment -@cindex faces, automatic choice - - This hook is used for automatically assigning faces to text in the -buffer. It is part of the implementation of Jit-Lock mode, used by -Font-Lock. - -@defvar fontification-functions -This variable holds a list of functions that are called by Emacs -redisplay as needed to assign faces automatically to text in the buffer. - -The functions are called in the order listed, with one argument, a -buffer position @var{pos}. Each function should attempt to assign faces -to the text in the current buffer starting at @var{pos}. - -Each function should record the faces they assign by setting the -@code{face} property. It should also add a non-@code{nil} -@code{fontified} property for all the text it has assigned faces to. -That property tells redisplay that faces have been assigned to that text -already. - -It is probably a good idea for each function to do nothing if the -character after @var{pos} already has a non-@code{nil} @code{fontified} -property, but this is not required. If one function overrides the -assignments made by a previous one, the properties as they are -after the last function finishes are the ones that really matter. - -For efficiency, we recommend writing these functions so that they -usually assign faces to around 400 to 600 characters at each call. -@end defvar - -@node Font Selection -@subsection Font Selection - - Before Emacs can draw a character on a particular display, it must -select a @dfn{font} for that character@footnote{In this context, the -term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock -Mode}).}. Normally, Emacs automatically chooses a font based on the -faces assigned to that character---specifically, the face attributes -@code{:family}, @code{:weight}, @code{:slant}, and @code{:width} -(@pxref{Face Attributes}). The choice of font also depends on the -character to be displayed; some fonts can only display a limited set -of characters. If no available font exactly fits the requirements, -Emacs looks for the @dfn{closest matching font}. The variables in -this section control how Emacs makes this selection. - -@defopt face-font-family-alternatives -If a given family is specified but does not exist, this variable -specifies alternative font families to try. Each element should have -this form: - -@example -(@var{family} @var{alternate-families}@dots{}) -@end example - -If @var{family} is specified but not available, Emacs will try the other -families given in @var{alternate-families}, one by one, until it finds a -family that does exist. -@end defopt - -@defopt face-font-selection-order -If there is no font that exactly matches all desired face attributes -(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}), -this variable specifies the order in which these attributes should be -considered when selecting the closest matching font. The value should -be a list containing those four attribute symbols, in order of -decreasing importance. The default is @code{(:width :height :weight -:slant)}. - -Font selection first finds the best available matches for the first -attribute in the list; then, among the fonts which are best in that -way, it searches for the best matches in the second attribute, and so -on. - -The attributes @code{:weight} and @code{:width} have symbolic values in -a range centered around @code{normal}. Matches that are more extreme -(farther from @code{normal}) are somewhat preferred to matches that are -less extreme (closer to @code{normal}); this is designed to ensure that -non-normal faces contrast with normal ones, whenever possible. - -One example of a case where this variable makes a difference is when the -default font has no italic equivalent. With the default ordering, the -@code{italic} face will use a non-italic font that is similar to the -default one. But if you put @code{:slant} before @code{:height}, the -@code{italic} face will use an italic font, even if its height is not -quite right. -@end defopt - -@defopt face-font-registry-alternatives -This variable lets you specify alternative font registries to try, if a -given registry is specified and doesn't exist. Each element should have -this form: - -@example -(@var{registry} @var{alternate-registries}@dots{}) -@end example - -If @var{registry} is specified but not available, Emacs will try the -other registries given in @var{alternate-registries}, one by one, -until it finds a registry that does exist. -@end defopt - - Emacs can make use of scalable fonts, but by default it does not use -them. - -@defopt scalable-fonts-allowed -This variable controls which scalable fonts to use. A value of -@code{nil}, the default, means do not use scalable fonts. @code{t} -means to use any scalable font that seems appropriate for the text. - -Otherwise, the value must be a list of regular expressions. Then a -scalable font is enabled for use if its name matches any regular -expression in the list. For example, - -@example -(setq scalable-fonts-allowed '("muleindian-2$")) -@end example - -@noindent -allows the use of scalable fonts with registry @code{muleindian-2}. -@end defopt - -@defvar face-font-rescale-alist -This variable specifies scaling for certain faces. Its value should -be a list of elements of the form - -@example -(@var{fontname-regexp} . @var{scale-factor}) -@end example - -If @var{fontname-regexp} matches the font name that is about to be -used, this says to choose a larger similar font according to the -factor @var{scale-factor}. You would use this feature to normalize -the font size if certain fonts are bigger or smaller than their -nominal heights and widths would suggest. -@end defvar - -@node Font Lookup -@subsection Looking Up Fonts - -@defun x-list-fonts name &optional reference-face frame maximum width -This function returns a list of available font names that match -@var{name}. @var{name} should be a string containing a font name in -either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font -Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD -string, wildcard characters may be used: the @samp{*} character -matches any substring, and the @samp{?} character matches any single -character. Case is ignored when matching font names. - -If the optional arguments @var{reference-face} and @var{frame} are -specified, the returned list includes only fonts that are the same -size as @var{reference-face} (a face name) currently is on the frame -@var{frame}. - -The optional argument @var{maximum} sets a limit on how many fonts to -return. If it is non-@code{nil}, then the return value is truncated -after the first @var{maximum} matching fonts. Specifying a small -value for @var{maximum} can make this function much faster, in cases -where many fonts match the pattern. - -The optional argument @var{width} specifies a desired font width. If -it is non-@code{nil}, the function only returns those fonts whose -characters are (on average) @var{width} times as wide as -@var{reference-face}. -@end defun - -@defun x-family-fonts &optional family frame -This function returns a list describing the available fonts for family -@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, -this list applies to all families, and therefore, it contains all -available fonts. Otherwise, @var{family} must be a string; it may -contain the wildcards @samp{?} and @samp{*}. - -The list describes the display that @var{frame} is on; if @var{frame} is -omitted or @code{nil}, it applies to the selected frame's display -(@pxref{Input Focus}). - -Each element in the list is a vector of the following form: - -@example -[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} - @var{fixed-p} @var{full} @var{registry-and-encoding}] -@end example - -The first five elements correspond to face attributes; if you -specify these attributes for a face, it will use this font. - -The last three elements give additional information about the font. -@var{fixed-p} is non-@code{nil} if the font is fixed-pitch. -@var{full} is the full name of the font, and -@var{registry-and-encoding} is a string giving the registry and -encoding of the font. -@end defun - -@defvar font-list-limit -This variable specifies maximum number of fonts to consider in font -matching. The function @code{x-family-fonts} will not return more than -that many fonts, and font selection will consider only that many fonts -when searching a matching font for face attributes. The default is -currently 100. -@end defvar - -@node Fontsets -@subsection Fontsets - - A @dfn{fontset} is a list of fonts, each assigned to a range of -character codes. An individual font cannot display the whole range of -characters that Emacs supports, but a fontset can. Fontsets have names, -just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is -information about defining a fontset under Lisp program control. - -@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror -This function defines a new fontset according to the specification -string @var{fontset-spec}. The string should have this format: - -@smallexample -@var{fontpattern}, @r{[}@var{charset}:@var{font}@r{]@dots{}} -@end smallexample - -@noindent -Whitespace characters before and after the commas are ignored. - -The first part of the string, @var{fontpattern}, should have the form of -a standard X font name, except that the last two fields should be -@samp{fontset-@var{alias}}. - -The new fontset has two names, one long and one short. The long name is -@var{fontpattern} in its entirety. The short name is -@samp{fontset-@var{alias}}. You can refer to the fontset by either -name. If a fontset with the same name already exists, an error is -signaled, unless @var{noerror} is non-@code{nil}, in which case this -function does nothing. - -If optional argument @var{style-variant-p} is non-@code{nil}, that says -to create bold, italic and bold-italic variants of the fontset as well. -These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold or italic -status. - -The specification string also says which fonts to use in the fontset. -See below for the details. -@end defun - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the font -to use for that character set. You can use this construct any number of -times in the specification string. - - For the remaining character sets, those that you don't specify -explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces -@samp{fontset-@var{alias}} with a value that names one character set. -For the @acronym{ASCII} character set, @samp{fontset-@var{alias}} is replaced -with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which Emacs does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for @acronym{ASCII} characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. - -@defun set-fontset-font name character font-spec &optional frame add -This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. - -If @var{name} is @code{nil}, this function modifies the fontset of the -selected frame or that of @var{frame} if @var{frame} is not -@code{nil}. - -If @var{name} is @code{t}, this function modifies the default -fontset, whose short name is @samp{fontset-default}. - -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). - -@var{character} may be a charset. In that case, use -@var{font-spec} for all character in the charsets. - -@var{character} may be a script anme. In that case, use -@var{font-spec} for all character in the charsets. - -@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, -where @var{family} is a family name of a font (possibly including a -foundry name at the head), @var{registry} is a registry name of a font -(possibly including an encoding name at the tail). - -@var{font-spec} may be a font name string. - -The optional argument @var{add}, if non-@code{nil}, specifies how to -add @var{font-spec} to the font specifications previously set. If it -is @code{prepend}, @var{font-spec} is prepended. If it is -@code{append}, @var{font-spec} is appended. By default, -@var{font-spec} overrides the previous settings. - -For instance, this changes the default fontset to use a font of which -family name is @samp{Kochi Gothic} for all characters belonging to -the charset @code{japanese-jisx0208}. - -@smallexample -(set-fontset-font t 'japanese-jisx0208 - (font-spec :family "Kochi Gothic")) -@end smallexample -@end defun - -@defun char-displayable-p char -This function returns @code{t} if Emacs ought to be able to display -@var{char}. More precisely, if the selected frame's fontset has a -font to display the character set that @var{char} belongs to. - -Fontsets can specify a font on a per-character basis; when the fontset -does that, this function's value may not be accurate. -@end defun - -@node Low-Level Font -@subsection Low-Level Font Representation - - Normally, it is not necessary to manipulate fonts directly. In case -you need to do so, this section explains how. - - In Emacs Lisp, fonts are represented using three different Lisp -object types: @dfn{font objects}, @dfn{font specs}, and @dfn{font -entities}. - -@defun fontp object &optional type -Return @code{t} if @var{object} is a font object, font spec, or font -entity. Otherwise, return @code{nil}. - -The optional argument @var{type}, if non-@code{nil}, determines the -exact type of Lisp object to check for. In that case, @var{type} -should be one of @code{font-object}, @code{font-spec}, or -@code{font-entity}. -@end defun - - A font object is a Lisp object that represents a font that Emacs has -@dfn{opened}. Font objects cannot be modified in Lisp, but they can -be inspected. - -@defun font-at position &optional window string -Return the font object that is being used to display the character at -position @var{position} in the window @var{window}. If @var{window} -is @code{nil}, it defaults to the selected window. If @var{string} is -@code{nil}, @var{position} specifies a position in the current buffer; -otherwise, @var{string} should be a string, and @var{position} -specifies a position in that string. -@end defun - - A font spec is a Lisp object that contains a set of specifications -that can be used to find a font. More than one font may match the -specifications in a font spec. - -@defun font-spec &rest arguments -Return a new font spec using the specifications in @var{arguments}, -which should come in @code{property}-@code{value} pairs. The possible -specifications are as follows: - -@table @code -@item :name -The font name (a string), in either XLFD, Fontconfig, or GTK format. -@xref{Font X,, Font Specification Options, emacs, The GNU Emacs -Manual}. - -@item :family -@itemx :foundry -@itemx :weight -@itemx :slant -@itemx :width -These have the same meanings as the face attributes of the same name. -@xref{Face Attributes}. - -@item :size -The font size---either a non-negative integer that specifies the pixel -size, or a floating point number that specifies the point size. - -@item :adstyle -Additional typographic style information for the font, such as -@samp{sans}. The value should be a string or a symbol. - -@item :registry -The charset registry and encoding of the font, such as -@samp{iso8859-1}. The value should be a string or a symbol. - -@item :script -The script that the font must support (a symbol). -@end table -@end defun - -@defun font-put font-spec property value -Set the font property @var{property} in the font-spec @var{font-spec} -to @var{value}. -@end defun - - A font entity is a reference to a font that need not be open. Its -properties are intermediate between a font object and a font spec: -like a font object, and unlike a font spec, it refers to a single, -specific font. Unlike a font object, creating a font entity does not -load the contents of that font into computer memory. - -@defun find-font font-spec &optional frame -This function returns a font entity that best matches the font spec -@var{font-spec} on frame @var{frame}. If @var{frame} is @code{nil}, -it defaults to the selected frame. -@end defun - -@defun list-fonts font-spec &optional frame num prefer -This function returns a list of all font entities that match the font -spec @var{font-spec}. - -The optional argument @var{frame}, if non-@code{nil}, specifies the -frame on which the fonts are to be displayed. The optional argument -@var{num}, if non-@code{nil}, should be an integer that specifies the -maximum length of the returned list. The optional argument -@var{prefer}, if non-@code{nil}, should be another font spec, which is -used to control the order of the returned list; the returned font -entities are sorted in order of decreasing ``closeness'' to that font -spec. -@end defun - - If you call @code{set-face-attribute} and pass a font spec, font -entity, or font name string as the value of the @code{:font} -attribute, Emacs opens the best ``matching'' font that is available -for display. It then stores the corresponding font object as the -actual value of the @code{:font} attribute for that face. - - The following functions can be used to obtain information about a -font. For these functions, the @var{font} argument can be a font -object, a font entity, or a font spec. - -@defun font-get font property -This function returns the value of the font property @var{property} -for @var{font}. - -If @var{font} is a font spec and the font spec does not specify -@var{property}, the return value is @code{nil}. If @var{font} is a -font object or font entity, the value for the @var{:script} property -may be a list of scripts supported by the font. -@end defun - -@defun font-face-attributes font &optional frame -This function returns a list of face attributes corresponding to -@var{font}. The optional argument @var{frame} specifies the frame on -which the font is to be displayed. If it is @code{nil}, the selected -frame is used. The return value has the form - -@smallexample -(:family @var{family} :height @var{height} :weight @var{weight} - :slant @var{slant} :width @var{width}) -@end smallexample - -where the values of @var{family}, @var{height}, @var{weight}, -@var{slant}, and @var{width} are face attribute values. Some of these -key-attribute pairs may be omitted from the list if they are not -specified by @var{font}. -@end defun - -@defun font-xlfd-name font &optional fold-wildcards -This function returns the XLFD (X Logical Font Descriptor), a string, -matching @var{font}. @xref{Font X,, Font Specification Options, -emacs, The GNU Emacs Manual}, for information about XLFDs. If the -name is too long for an XLFD (which can contain at most 255 -characters), the function returns @code{nil}. - -If the optional argument @var{fold-wildcards} is non-@code{nil}, -consecutive wildcards in the XLFD are folded into one. -@end defun - -@node Fringes -@section Fringes -@cindex fringes - - The @dfn{fringes} of a window are thin vertical strips down the -sides that are used for displaying bitmaps that indicate truncation, -continuation, horizontal scrolling, and the overlay arrow. - -@menu -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. -@end menu - -@node Fringe Size/Pos -@subsection Fringe Size and Position - - The following buffer-local variables control the position and width -of the window fringes. - -@defvar fringes-outside-margins -The fringes normally appear between the display margins and the window -text. If the value is non-@code{nil}, they appear outside the display -margins. @xref{Display Margins}. -@end defvar - -@defvar left-fringe-width -This variable, if non-@code{nil}, specifies the width of the left -fringe in pixels. A value of @code{nil} means to use the left fringe -width from the window's frame. -@end defvar - -@defvar right-fringe-width -This variable, if non-@code{nil}, specifies the width of the right -fringe in pixels. A value of @code{nil} means to use the right fringe -width from the window's frame. -@end defvar - - The values of these variables take effect when you display the -buffer in a window. If you change them while the buffer is visible, -you can call @code{set-window-buffer} to display it once again in the -same window, to make the changes take effect. - -@defun set-window-fringes window left &optional right outside-margins -This function sets the fringe widths of window @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The argument @var{left} specifies the width in pixels of the left -fringe, and likewise @var{right} for the right fringe. A value of -@code{nil} for either one stands for the default width. If -@var{outside-margins} is non-@code{nil}, that specifies that fringes -should appear outside of the display margins. -@end defun - -@defun window-fringes &optional window -This function returns information about the fringes of a window -@var{window}. If @var{window} is omitted or @code{nil}, the selected -window is used. The value has the form @code{(@var{left-width} -@var{right-width} @var{outside-margins})}. -@end defun - - -@node Fringe Indicators -@subsection Fringe Indicators -@cindex fringe indicators -@cindex indicators, fringe - - The @dfn{fringe indicators} are tiny icons Emacs displays in the -window fringe (on a graphic display) to indicate truncated or -continued lines, buffer boundaries, overlay arrow, etc. - -@defopt indicate-empty-lines -@cindex fringes, and empty line indication -When this is non-@code{nil}, Emacs displays a special glyph in the -fringe of each empty line at the end of the buffer, on graphical -displays. @xref{Fringes}. This variable is automatically -buffer-local in every buffer. -@end defopt - -@defopt indicate-buffer-boundaries -This buffer-local variable controls how the buffer boundaries and -window scrolling are indicated in the window fringes. - -Emacs can indicate the buffer boundaries---that is, the first and last -line in the buffer---with angle icons when they appear on the screen. -In addition, Emacs can display an up-arrow in the fringe to show -that there is text above the screen, and a down-arrow to show -there is text below the screen. - -There are three kinds of basic values: - -@table @asis -@item @code{nil} -Don't display any of these fringe icons. -@item @code{left} -Display the angle icons and arrows in the left fringe. -@item @code{right} -Display the angle icons and arrows in the right fringe. -@item any non-alist -Display the angle icons in the left fringe -and don't display the arrows. -@end table - -Otherwise the value should be an alist that specifies which fringe -indicators to display and where. Each element of the alist should -have the form @code{(@var{indicator} . @var{position})}. Here, -@var{indicator} is one of @code{top}, @code{bottom}, @code{up}, -@code{down}, and @code{t} (which covers all the icons not yet -specified), while @var{position} is one of @code{left}, @code{right} -and @code{nil}. - -For example, @code{((top . left) (t . right))} places the top angle -bitmap in left fringe, and the bottom angle bitmap as well as both -arrow bitmaps in right fringe. To show the angle bitmaps in the left -fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}. -@end defopt - -@defvar default-indicate-buffer-boundaries -The value of this variable is the default value for -@code{indicate-buffer-boundaries} in buffers that do not override it. -@end defvar - -@defvar fringe-indicator-alist -This buffer-local variable specifies the mapping from logical fringe -indicators to the actual bitmaps displayed in the window fringes. - -These symbols identify the logical fringe indicators: - -@table @asis -@item Truncation and continuation line indicators: -@code{truncation}, @code{continuation}. - -@item Buffer position indicators: -@code{up}, @code{down}, -@code{top}, @code{bottom}, -@code{top-bottom}. - -@item Empty line indicator: -@code{empty-line}. - -@item Overlay arrow indicator: -@code{overlay-arrow}. - -@item Unknown bitmap indicator: -@code{unknown}. -@end table - - The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})} -specifies the fringe bitmaps used to display a specific logical -fringe indicator. - -Here, @var{indicator} specifies the logical indicator type, and -@var{bitmaps} is list of symbols @code{(@var{left} @var{right} -[@var{left1} @var{right1}])} which specifies the actual bitmap shown -in the left or right fringe for the logical indicator. - -The @var{left} and @var{right} symbols specify the bitmaps shown in -the left and/or right fringe for the specific indicator. The -@var{left1} or @var{right1} bitmaps are used only for the `bottom' and -`top-bottom indicators when the last (only) line in has no final -newline. Alternatively, @var{bitmaps} may be a single symbol which is -used in both left and right fringes. - -When @code{fringe-indicator-alist} has a buffer-local value, and there -is no bitmap defined for a logical indicator, or the bitmap is -@code{t}, the corresponding value from the (non-local) -@code{default-fringe-indicator-alist} is used. - -To completely hide a specific indicator, set the bitmap to @code{nil}. -@end defvar - -@defvar default-fringe-indicator-alist -The value of this variable is the default value for -@code{fringe-indicator-alist} in buffers that do not override it. -@end defvar - -Standard fringe bitmaps for indicators: -@example -left-arrow right-arrow up-arrow down-arrow -left-curly-arrow right-curly-arrow -left-triangle right-triangle -top-left-angle top-right-angle -bottom-left-angle bottom-right-angle -left-bracket right-bracket -filled-rectangle hollow-rectangle -filled-square hollow-square -vertical-bar horizontal-bar -empty-line question-mark -@end example - -@node Fringe Cursors -@subsection Fringe Cursors -@cindex fringe cursors -@cindex cursor, fringe - - When a line is exactly as wide as the window, Emacs displays the -cursor in the right fringe instead of using two lines. Different -bitmaps are used to represent the cursor in the fringe depending on -the current buffer's cursor type. - -@table @asis -@item Logical cursor types: -@code{box} , @code{hollow}, @code{bar}, -@code{hbar}, @code{hollow-small}. -@end table - -The @code{hollow-small} type is used instead of @code{hollow} when the -normal @code{hollow-rectangle} bitmap is too tall to fit on a specific -display line. - -@defopt overflow-newline-into-fringe -If this is non-@code{nil}, lines exactly as wide as the window (not -counting the final newline character) are not continued. Instead, -when point is at the end of the line, the cursor appears in the right -fringe. -@end defopt - -@defvar fringe-cursor-alist -This variable specifies the mapping from logical cursor type to the -actual fringe bitmaps displayed in the right fringe. The value is an -alist where each element @code{(@var{cursor} . @var{bitmap})} specifies -the fringe bitmaps used to display a specific logical cursor type in -the fringe. Here, @var{cursor} specifies the logical cursor type and -@var{bitmap} is a symbol specifying the fringe bitmap to be displayed -for that logical cursor type. - -When @code{fringe-cursor-alist} has a buffer-local value, and there is -no bitmap defined for a cursor type, the corresponding value from the -(non-local) @code{default-fringes-indicator-alist} is used. -@end defvar - -@defvar default-fringes-cursor-alist -The value of this variable is the default value for -@code{fringe-cursor-alist} in buffers that do not override it. -@end defvar - -Standard bitmaps for displaying the cursor in right fringe: -@example -filled-rectangle hollow-rectangle filled-square hollow-square -vertical-bar horizontal-bar -@end example - - -@node Fringe Bitmaps -@subsection Fringe Bitmaps -@cindex fringe bitmaps -@cindex bitmaps, fringe - - The @dfn{fringe bitmaps} are the actual bitmaps which represent the -logical fringe indicators for truncated or continued lines, buffer -boundaries, overlay arrow, etc. Fringe bitmap symbols have their own -name space. The fringe bitmaps are shared by all frames and windows. -You can redefine the built-in fringe bitmaps, and you can define new -fringe bitmaps. - - The way to display a bitmap in the left or right fringes for a given -line in a window is by specifying the @code{display} property for one -of the characters that appears in it. Use a display specification of -the form @code{(left-fringe @var{bitmap} [@var{face}])} or -@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display -Property}). Here, @var{bitmap} is a symbol identifying the bitmap you -want, and @var{face} (which is optional) is the name of the face whose -colors should be used for displaying the bitmap, instead of the -default @code{fringe} face. @var{face} is automatically merged with -the @code{fringe} face, so normally @var{face} need only specify the -foreground color for the bitmap. - -@defun fringe-bitmaps-at-pos &optional pos window -This function returns the fringe bitmaps of the display line -containing position @var{pos} in window @var{window}. The return -value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left} -is the symbol for the fringe bitmap in the left fringe (or @code{nil} -if no bitmap), @var{right} is similar for the right fringe, and @var{ov} -is non-@code{nil} if there is an overlay arrow in the left fringe. - -The value is @code{nil} if @var{pos} is not visible in @var{window}. -If @var{window} is @code{nil}, that stands for the selected window. -If @var{pos} is @code{nil}, that stands for the value of point in -@var{window}. -@end defun - -@node Customizing Bitmaps -@subsection Customizing Fringe Bitmaps - -@defun define-fringe-bitmap bitmap bits &optional height width align -This function defines the symbol @var{bitmap} as a new fringe bitmap, -or replaces an existing bitmap with that name. - -The argument @var{bits} specifies the image to use. It should be -either a string or a vector of integers, where each element (an -integer) corresponds to one row of the bitmap. Each bit of an integer -corresponds to one pixel of the bitmap, where the low bit corresponds -to the rightmost pixel of the bitmap. - -The height is normally the length of @var{bits}. However, you -can specify a different height with non-@code{nil} @var{height}. The width -is normally 8, but you can specify a different width with non-@code{nil} -@var{width}. The width must be an integer between 1 and 16. - -The argument @var{align} specifies the positioning of the bitmap -relative to the range of rows where it is used; the default is to -center the bitmap. The allowed values are @code{top}, @code{center}, -or @code{bottom}. - -The @var{align} argument may also be a list @code{(@var{align} -@var{periodic})} where @var{align} is interpreted as described above. -If @var{periodic} is non-@code{nil}, it specifies that the rows in -@code{bits} should be repeated enough times to reach the specified -height. -@end defun - -@defun destroy-fringe-bitmap bitmap -This function destroy the fringe bitmap identified by @var{bitmap}. -If @var{bitmap} identifies a standard fringe bitmap, it actually -restores the standard definition of that bitmap, instead of -eliminating it entirely. -@end defun - -@defun set-fringe-bitmap-face bitmap &optional face -This sets the face for the fringe bitmap @var{bitmap} to @var{face}. -If @var{face} is @code{nil}, it selects the @code{fringe} face. The -bitmap's face controls the color to draw it in. - -@var{face} is merged with the @code{fringe} face, so normally -@var{face} should specify only the foreground color. -@end defun - -@node Overlay Arrow -@subsection The Overlay Arrow -@c @cindex overlay arrow Duplicates variable names - - The @dfn{overlay arrow} is useful for directing the user's attention -to a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. This feature has nothing to do with -@dfn{overlays} (@pxref{Overlays}). - -@defvar overlay-arrow-string -This variable holds the string to display to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -On a graphical display the contents of the string are ignored; instead a -glyph is displayed in the fringe area to the left of the display area. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -arrow. It should point at the beginning of a line. On a non-graphical -display the arrow text -appears at the beginning of that line, overlaying any text that would -otherwise appear. Since the arrow is usually short, and the line -usually begins with indentation, normally nothing significant is -overwritten. - -The overlay-arrow string is displayed in any given buffer if the value -of @code{overlay-arrow-position} in that buffer points into that -buffer. Thus, it is possible to display multiple overlay arrow strings -by creating buffer-local bindings of @code{overlay-arrow-position}. -However, it is usually cleaner to use -@code{overlay-arrow-variable-list} to achieve this result. -@c !!! overlay-arrow-position: but the overlay string may remain in the display -@c of some other buffer until an update is required. This should be fixed -@c now. Is it? -@end defvar - - You can do a similar job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - - You can define multiple overlay arrows via the variable -@code{overlay-arrow-variable-list}. - -@defvar overlay-arrow-variable-list -This variable's value is a list of variables, each of which specifies -the position of an overlay arrow. The variable -@code{overlay-arrow-position} has its normal meaning because it is on -this list. -@end defvar - -Each variable on this list can have properties -@code{overlay-arrow-string} and @code{overlay-arrow-bitmap} that -specify an overlay arrow string (for text-only terminals) or fringe -bitmap (for graphical terminals) to display at the corresponding -overlay arrow position. If either property is not set, the default -@code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator -is used. - -@node Scroll Bars -@section Scroll Bars -@cindex scroll bars - -Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. - -@defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. - - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: - -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. - -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. - -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. -@end defun - -@defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. - -@var{horizontal-type} is not actually meaningful. -@end defun - -If you don't specify these values for a window with -@code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function -@code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} -specifying the same buffer that is already displayed. - -@defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defopt - -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun - -@defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. -@end defvar - -@node Display Property -@section The @code{display} Property -@cindex display specification -@kindex display @r{(text property)} - - The @code{display} text property (or overlay property) is used to -insert images into text, and also control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} -property value generally apply in parallel to the text they cover. - - If several sources (overlays and/or a text property) specify values -for the @code{display} property, only one of the values takes effect, -following the rules of @code{get-char-property}. @xref{Examining -Properties}. - - The rest of this section describes several kinds of -display specifications and what they mean. - -@menu -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of the main text. -@end menu - -@node Replacing Specs -@subsection Display Specs That Replace The Text - - Some kinds of @code{display} specifications specify something to -display instead of the text that has the property. These are called -@dfn{replacing} display specifications. Emacs does not allow the user -to interactively move point into the middle of buffer text that is -replaced in this way. - - If a list of display specifications includes more than one replacing -display specification, the first overrides the rest. Replacing -display specifications make most other display specifications -irrelevant, since those don't apply to the replacement. - - For replacing display specifications, ``the text that has the -property'' means all the consecutive characters that have the same -Lisp object as their @code{display} property; these characters are -replaced as a single unit. By contrast, characters that have similar -but distinct Lisp objects as their @code{display} properties are -handled separately. Here's a function that illustrates this point: - -@smallexample -(defun foo () - (goto-char (point-min)) - (dotimes (i 5) - (let ((string (concat "A"))) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 1) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 1)))) -@end smallexample - -@noindent -It gives each of the first ten characters in the buffer string -@code{"A"} as the @code{display} property, but they don't all get the -same string. The first two characters get the same string, so they -together are replaced with one @samp{A}. The next two characters get -a second string, so they together are replaced with one @samp{A}. -Likewise for each following pair of characters. Thus, the ten -characters appear as five A's. This function would have the same -results: - -@smallexample -(defun foo () - (goto-char (point-min)) - (dotimes (i 5) - (let ((string (concat "A"))) - (put-text-property (point) (+ 2 (point)) 'display string) - (put-text-property (point) (1+ (point)) 'display string) - (forward-char 2)))) -@end smallexample - -@noindent -This illustrates that what matters is the property value for -each character. If two consecutive characters have the same -object as the @code{display} property value, it's irrelevant -whether they got this property from a single call to -@code{put-text-property} or from two different calls. - -@node Specified Space -@subsection Specified Spaces -@cindex spaces, specified height or width -@cindex variable-width spaces - - To display a space of specified width and/or height, use a display -specification of the form @code{(space . @var{props})}, where -@var{props} is a property list (a list of alternating properties and -values). You can put this property on one or more consecutive -characters; a space of the specified height and width is displayed in -place of @emph{all} of those characters. These are the properties you -can use in @var{props} to specify the weight of the space: - -@table @code -@item :width @var{width} -If @var{width} is an integer or floating point number, it specifies -that the space width should be @var{width} times the normal character -width. @var{width} can also be a @dfn{pixel width} specification -(@pxref{Pixel Specification}). - -@item :relative-width @var{factor} -Specifies that the width of the stretch should be computed from the -first character in the group of consecutive characters that have the -same @code{display} property. The space width is the width of that -character, multiplied by @var{factor}. - -@item :align-to @var{hpos} -Specifies that the space should be wide enough to reach @var{hpos}. -If @var{hpos} is a number, it is measured in units of the normal -character width. @var{hpos} can also be a @dfn{pixel width} -specification (@pxref{Pixel Specification}). -@end table - - You should use one and only one of the above properties. You can -also specify the height of the space, with these properties: - -@table @code -@item :height @var{height} -Specifies the height of the space. -If @var{height} is an integer or floating point number, it specifies -that the space height should be @var{height} times the normal character -height. The @var{height} may also be a @dfn{pixel height} specification -(@pxref{Pixel Specification}). - -@item :relative-height @var{factor} -Specifies the height of the space, multiplying the ordinary height -of the text having this display specification by @var{factor}. - -@item :ascent @var{ascent} -If the value of @var{ascent} is a non-negative number no greater than -100, it specifies that @var{ascent} percent of the height of the space -should be considered as the ascent of the space---that is, the part -above the baseline. The ascent may also be specified in pixel units -with a @dfn{pixel ascent} specification (@pxref{Pixel Specification}). - -@end table - - Don't use both @code{:height} and @code{:relative-height} together. - - The @code{:width} and @code{:align-to} properties are supported on -non-graphic terminals, but the other space properties in this section -are not. - -@node Pixel Specification -@subsection Pixel Specification for Spaces -@cindex spaces, pixel specification - - The value of the @code{:width}, @code{:align-to}, @code{:height}, -and @code{:ascent} properties can be a special kind of expression that -is evaluated during redisplay. The result of the evaluation is used -as an absolute number of pixels. - - The following expressions are supported: - -@smallexample -@group - @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} - @var{num} ::= @var{integer} | @var{float} | @var{symbol} - @var{unit} ::= in | mm | cm | width | height -@end group -@group - @var{elem} ::= left-fringe | right-fringe | left-margin | right-margin - | scroll-bar | text - @var{pos} ::= left | center | right - @var{form} ::= (@var{num} . @var{expr}) | (@var{op} @var{expr} ...) - @var{op} ::= + | - -@end group -@end smallexample - - The form @var{num} specifies a fraction of the default frame font -height or width. The form @code{(@var{num})} specifies an absolute -number of pixels. If @var{num} is a symbol, @var{symbol}, its -buffer-local variable binding is used. - - The @code{in}, @code{mm}, and @code{cm} units specify the number of -pixels per inch, millimeter, and centimeter, respectively. The -@code{width} and @code{height} units correspond to the default width -and height of the current face. An image specification @code{image} -corresponds to the width or height of the image. - - The @code{left-fringe}, @code{right-fringe}, @code{left-margin}, -@code{right-margin}, @code{scroll-bar}, and @code{text} elements -specify to the width of the corresponding area of the window. - - The @code{left}, @code{center}, and @code{right} positions can be -used with @code{:align-to} to specify a position relative to the left -edge, center, or right edge of the text area. - - Any of the above window elements (except @code{text}) can also be -used with @code{:align-to} to specify that the position is relative to -the left edge of the given area. Once the base offset for a relative -position has been set (by the first occurrence of one of these -symbols), further occurrences of these symbols are interpreted as the -width of the specified area. For example, to align to the center of -the left-margin, use - -@example -:align-to (+ left-margin (0.5 . left-margin)) -@end example - - If no specific base offset is set for alignment, it is always relative -to the left edge of the text area. For example, @samp{:align-to 0} in a -header-line aligns with the first text column in the text area. - - A value of the form @code{(@var{num} . @var{expr})} stands for the -product of the values of @var{num} and @var{expr}. For example, -@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . -@var{image})} specifies half the width (or height) of the specified -image. - - The form @code{(+ @var{expr} ...)} adds up the value of the -expressions. The form @code{(- @var{expr} ...)} negates or subtracts -the value of the expressions. - -@node Other Display Specs -@subsection Other Display Specifications - - Here are the other sorts of display specifications that you can use -in the @code{display} text property. - -@table @code -@item @var{string} -Display @var{string} instead of the text that has this property. - -Recursive display specifications are not supported---@var{string}'s -@code{display} properties, if any, are not used. - -@item (image . @var{image-props}) -This kind of display specification is an image descriptor (@pxref{Images}). -When used as a display specification, it means to display the image -instead of the text that has the display specification. - -@item (slice @var{x} @var{y} @var{width} @var{height}) -This specification together with @code{image} specifies a @dfn{slice} -(a partial area) of the image to display. The elements @var{y} and -@var{x} specify the top left corner of the slice, within the image; -@var{width} and @var{height} specify the width and height of the -slice. Integer values are numbers of pixels. A floating point number -in the range 0.0--1.0 stands for that fraction of the width or height -of the entire image. - -@item ((margin nil) @var{string}) -A display specification of this form means to display @var{string} -instead of the text that has the display specification, at the same -position as that text. It is equivalent to using just @var{string}, -but it is done as a special case of marginal display (@pxref{Display -Margins}). - -@item (space-width @var{factor}) -This display specification affects all the space characters within the -text that has the specification. It displays all of these spaces -@var{factor} times as wide as normal. The element @var{factor} should -be an integer or float. Characters other than spaces are not affected -at all; in particular, this has no effect on tab characters. - -@item (height @var{height}) -This display specification makes the text taller or shorter. -Here are the possibilities for @var{height}: - -@table @asis -@item @code{(+ @var{n})} -This means to use a font that is @var{n} steps larger. A ``step'' is -defined by the set of available fonts---specifically, those that match -what was otherwise specified for this text, in all attributes except -height. Each size for which a suitable font is available counts as -another step. @var{n} should be an integer. - -@item @code{(- @var{n})} -This means to use a font that is @var{n} steps smaller. - -@item a number, @var{factor} -A number, @var{factor}, means to use a font that is @var{factor} times -as tall as the default font. - -@item a symbol, @var{function} -A symbol is a function to compute the height. It is called with the -current height as argument, and should return the new height to use. - -@item anything else, @var{form} -If the @var{height} value doesn't fit the previous possibilities, it is -a form. Emacs evaluates it to get the new height, with the symbol -@code{height} bound to the current specified font height. -@end table - -@item (raise @var{factor}) -This kind of display specification raises or lowers the text -it applies to, relative to the baseline of the line. - -@var{factor} must be a number, which is interpreted as a multiple of the -height of the affected text. If it is positive, that means to display -the characters raised. If it is negative, that means to display them -lower down. - -If the text also has a @code{height} display specification, that does -not affect the amount of raising or lowering, which is based on the -faces used for the text. -@end table - -@c We put all the `@code{(when ...)}' on one line to encourage -@c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot -@c was at eol; the info file ended up w/ two spaces rendered after it. - You can make any display specification conditional. To do that, -package it in another list of the form -@code{(when @var{condition} . @var{spec})}. -Then the specification @var{spec} applies only when -@var{condition} evaluates to a non-@code{nil} value. During the -evaluation, @code{object} is bound to the string or buffer having the -conditional @code{display} property. @code{position} and -@code{buffer-position} are bound to the position within @code{object} -and the buffer position where the @code{display} property was found, -respectively. Both positions can be different when @code{object} is a -string. - -@node Display Margins -@subsection Displaying in the Margins -@cindex display margins -@cindex margins, display - - A buffer can have blank areas called @dfn{display margins} on the -left and on the right. Ordinary text never appears in these areas, -but you can put things into the display margins using the -@code{display} property. There is currently no way to make text or -images in the margin mouse-sensitive. - - The way to display something in the margins is to specify it in a -margin display specification in the @code{display} property of some -text. This is a replacing display specification, meaning that the -text you put it on does not get displayed; the margin display appears, -but that text does not. - - A margin display specification looks like @code{((margin -right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}. -Here, @var{spec} is another display specification that says what to -display in the margin. Typically it is a string of text to display, -or an image descriptor. - - To display something in the margin @emph{in association with} -certain buffer text, without altering or preventing the display of -that text, put a @code{before-string} property on the text and put the -margin display specification on the contents of the before-string. - - Before the display margins can display anything, you must give -them a nonzero width. The usual way to do that is to set these -variables: - -@defvar left-margin-width -This variable specifies the width of the left margin. -It is buffer-local in all buffers. -@end defvar - -@defvar right-margin-width -This variable specifies the width of the right margin. -It is buffer-local in all buffers. -@end defvar - - Setting these variables does not immediately affect the window. These -variables are checked when a new buffer is displayed in the window. -Thus, you can make changes take effect by calling -@code{set-window-buffer}. - - You can also set the margin widths immediately. - -@defun set-window-margins window left &optional right -This function specifies the margin widths for window @var{window}. -The argument @var{left} controls the left margin and -@var{right} controls the right margin (default @code{0}). -@end defun - -@defun window-margins &optional window -This function returns the left and right margins of @var{window} -as a cons cell of the form @code{(@var{left} . @var{right})}. -If @var{window} is @code{nil}, the selected window is used. -@end defun - -@node Images -@section Images -@cindex images in buffers - - To display an image in an Emacs buffer, you must first create an image -descriptor, then use it as a display specifier in the @code{display} -property of text that is displayed (@pxref{Display Property}). - - Emacs is usually able to display images when it is run on a -graphical terminal. Images cannot be displayed in a text terminal, on -certain graphical terminals that lack the support for this, or if -Emacs is compiled without image support. You can use the function -@code{display-images-p} to determine if images can in principle be -displayed (@pxref{Display Feature Testing}). - -@menu -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once it is defined. -* Image Cache:: Internal mechanisms of image display. -@end menu - -@node Image Formats -@subsection Image Formats -@cindex image formats -@cindex image types - - Emacs can display a number of different image formats; some of them -are supported only if particular support libraries are installed on -your machine. In some environments, Emacs can load image -libraries on demand; if so, the variable @code{image-library-alist} -can be used to modify the set of known names for these dynamic -libraries (though it is not possible to add new image formats). - - The supported image formats include XBM, XPM (this requires the -libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring -@code{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the -@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff} -v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring -@code{librsvg} 2.0.0). - - You specify one of these formats with an image type symbol. The image -type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, -@code{pbm}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. - -@defvar image-types -This variable contains a list of those image type symbols that are -potentially supported in the current configuration. -@emph{Potentially} here means that Emacs knows about the image types, -not necessarily that they can be loaded (they could depend on -unavailable dynamic libraries, for example). - -To know which image types are really available, use -@code{image-type-available-p}. -@end defvar - -@defvar image-library-alist -This in an alist of image types vs external libraries needed to -display them. - -Each element is a list @code{(@var{image-type} @var{library}...)}, -where the car is a supported image format from @code{image-types}, and -the rest are strings giving alternate filenames for the corresponding -external libraries to load. - -Emacs tries to load the libraries in the order they appear on the -list; if none is loaded, the running session of Emacs won't support -the image type. @code{pbm} and @code{xbm} don't need to be listed; -they're always supported. - -This variable is ignored if the image libraries are statically linked -into Emacs. -@end defvar - -@defun image-type-available-p type -This function returns non-@code{nil} if image type @var{type} is -available, i.e., if images of this type can be loaded and displayed in -Emacs. @var{type} should be one of the types contained in -@code{image-types}. - -For image types whose support libraries are statically linked, this -function always returns @code{t}; for other image types, it returns -@code{t} if the dynamic library could be loaded, @code{nil} otherwise. -@end defun - -@node Image Descriptors -@subsection Image Descriptors -@cindex image descriptor - - An image description is a list of the form @code{(image . @var{props})}, -where @var{props} is a property list containing alternating keyword -symbols (symbols whose names start with a colon) and their values. -You can use any Lisp object as a property, but the only properties -that have any special meaning are certain symbols, all of them keywords. - - Every image descriptor must contain the property @code{:type -@var{type}} to specify the format of the image. The value of @var{type} -should be an image type symbol; for example, @code{xpm} for an image in -XPM format. - - Here is a list of other properties that are meaningful for all image -types: - -@table @code -@item :file @var{file} -The @code{:file} property says to load the image from file -@var{file}. If @var{file} is not an absolute file name, it is expanded -in @code{data-directory}. - -@item :data @var{data} -The @code{:data} property says the actual contents of the image. -Each image must use either @code{:data} or @code{:file}, but not both. -For most image types, the value of the @code{:data} property should be a -string containing the image data; we recommend using a unibyte string. - -Before using @code{:data}, look for further information in the section -below describing the specific image format. For some image types, -@code{:data} may not be supported; for some, it allows other data types; -for some, @code{:data} alone is not enough, so you need to use other -image properties along with @code{:data}. - -@item :margin @var{margin} -The @code{:margin} property specifies how many pixels to add as an -extra margin around the image. The value, @var{margin}, must be a -non-negative number, or a pair @code{(@var{x} . @var{y})} of such -numbers. If it is a pair, @var{x} specifies how many pixels to add -horizontally, and @var{y} specifies how many pixels to add vertically. -If @code{:margin} is not specified, the default is zero. - -@item :ascent @var{ascent} -The @code{:ascent} property specifies the amount of the image's -height to use for its ascent---that is, the part above the baseline. -The value, @var{ascent}, must be a number in the range 0 to 100, or -the symbol @code{center}. - -If @var{ascent} is a number, that percentage of the image's height is -used for its ascent. - -If @var{ascent} is @code{center}, the image is vertically centered -around a centerline which would be the vertical centerline of text drawn -at the position of the image, in the manner specified by the text -properties and overlays that apply to the image. - -If this property is omitted, it defaults to 50. - -@item :relief @var{relief} -The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle -around the image. The value, @var{relief}, specifies the width of the -shadow lines, in pixels. If @var{relief} is negative, shadows are drawn -so that the image appears as a pressed button; otherwise, it appears as -an unpressed button. - -@item :conversion @var{algorithm} -The @code{:conversion} property, if non-@code{nil}, specifies a -conversion algorithm that should be applied to the image before it is -displayed; the value, @var{algorithm}, specifies which algorithm. - -@table @code -@item laplace -@itemx emboss -Specifies the Laplace edge detection algorithm, which blurs out small -differences in color while highlighting larger differences. People -sometimes consider this useful for displaying the image for a -``disabled'' button. - -@item (edge-detection :matrix @var{matrix} :color-adjust @var{adjust}) -Specifies a general edge-detection algorithm. @var{matrix} must be -either a nine-element list or a nine-element vector of numbers. A pixel -at position @math{x/y} in the transformed image is computed from -original pixels around that position. @var{matrix} specifies, for each -pixel in the neighborhood of @math{x/y}, a factor with which that pixel -will influence the transformed pixel; element @math{0} specifies the -factor for the pixel at @math{x-1/y-1}, element @math{1} the factor for -the pixel at @math{x/y-1} etc., as shown below: -@iftex -@tex -$$\pmatrix{x-1/y-1 & x/y-1 & x+1/y-1 \cr - x-1/y & x/y & x+1/y \cr - x-1/y+1& x/y+1 & x+1/y+1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (x-1/y-1 x/y-1 x+1/y-1 - x-1/y x/y x+1/y - x-1/y+1 x/y+1 x+1/y+1) -@end display -@end ifnottex - -The resulting pixel is computed from the color intensity of the color -resulting from summing up the RGB values of surrounding pixels, -multiplied by the specified factors, and dividing that sum by the sum -of the factors' absolute values. - -Laplace edge-detection currently uses a matrix of -@iftex -@tex -$$\pmatrix{1 & 0 & 0 \cr - 0& 0 & 0 \cr - 9 & 9 & -1 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - (1 0 0 - 0 0 0 - 9 9 -1) -@end display -@end ifnottex - -Emboss edge-detection uses a matrix of -@iftex -@tex -$$\pmatrix{ 2 & -1 & 0 \cr - -1 & 0 & 1 \cr - 0 & 1 & -2 \cr}$$ -@end tex -@end iftex -@ifnottex -@display - ( 2 -1 0 - -1 0 1 - 0 1 -2) -@end display -@end ifnottex - -@item disabled -Specifies transforming the image so that it looks ``disabled.'' -@end table - -@item :mask @var{mask} -If @var{mask} is @code{heuristic} or @code{(heuristic @var{bg})}, build -a clipping mask for the image, so that the background of a frame is -visible behind the image. If @var{bg} is not specified, or if @var{bg} -is @code{t}, determine the background color of the image by looking at -the four corners of the image, assuming the most frequently occurring -color from the corners is the background color of the image. Otherwise, -@var{bg} must be a list @code{(@var{red} @var{green} @var{blue})} -specifying the color to assume for the background of the image. - -If @var{mask} is @code{nil}, remove a mask from the image, if it has -one. Images in some formats include a mask which can be removed by -specifying @code{:mask nil}. - -@item :pointer @var{shape} -This specifies the pointer shape when the mouse pointer is over this -image. @xref{Pointer Shape}, for available pointer shapes. - -@item :map @var{map} -This associates an image map of @dfn{hot spots} with this image. - -An image map is an alist where each element has the format -@code{(@var{area} @var{id} @var{plist})}. An @var{area} is specified -as either a rectangle, a circle, or a polygon. - -A rectangle is a cons -@code{(rect . ((@var{x0} . @var{y0}) . (@var{x1} . @var{y1})))} -which specifies the pixel coordinates of the upper left and bottom right -corners of the rectangle area. - -A circle is a cons -@code{(circle . ((@var{x0} . @var{y0}) . @var{r}))} -which specifies the center and the radius of the circle; @var{r} may -be a float or integer. - -A polygon is a cons -@code{(poly . [@var{x0} @var{y0} @var{x1} @var{y1} ...])} -where each pair in the vector describes one corner in the polygon. - -When the mouse pointer lies on a hot-spot area of an image, the -@var{plist} of that hot-spot is consulted; if it contains a @code{help-echo} -property, that defines a tool-tip for the hot-spot, and if it contains -a @code{pointer} property, that defines the shape of the mouse cursor when -it is on the hot-spot. -@xref{Pointer Shape}, for available pointer shapes. - -When you click the mouse when the mouse pointer is over a hot-spot, an -event is composed by combining the @var{id} of the hot-spot with the -mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's -@var{id} is @code{area4}. -@end table - -@defun image-mask-p spec &optional frame -This function returns @code{t} if image @var{spec} has a mask bitmap. -@var{frame} is the frame on which the image will be displayed. -@var{frame} @code{nil} or omitted means to use the selected frame -(@pxref{Input Focus}). -@end defun - -@node XBM Images -@subsection XBM Images -@cindex XBM - - To use XBM format, specify @code{xbm} as the image type. This image -format doesn't require an external library, so images of this type are -always supported. - - Additional image properties supported for the @code{xbm} image type are: - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the XBM that is 0. The default is the frame's -background color. -@end table - - If you specify an XBM image using data within Emacs instead of an -external file, use the following three properties: - -@table @code -@item :data @var{data} -The value, @var{data}, specifies the contents of the image. -There are three formats you can use for @var{data}: - -@itemize @bullet -@item -A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. - -@item -A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. - -@item -A string or a bool-vector containing the bits of the image (plus perhaps -some extra bits at the end that will not be used). It should contain at -least @var{width} * @code{height} bits. In this case, you must specify -@code{:height} and @code{:width}, both to indicate that the string -contains just the bits rather than a whole XBM file, and to specify the -size of the image. -@end itemize - -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. -@end table - -@node XPM Images -@subsection XPM Images -@cindex XPM - - To use XPM format, specify @code{xpm} as the image type. The -additional image property @code{:color-symbols} is also meaningful with -the @code{xpm} image type: - -@table @code -@item :color-symbols @var{symbols} -The value, @var{symbols}, should be an alist whose elements have the -form @code{(@var{name} . @var{color})}. In each element, @var{name} is -the name of a color as it appears in the image file, and @var{color} -specifies the actual color to use for displaying that name. -@end table - -@node GIF Images -@subsection GIF Images -@cindex GIF - - For GIF images, specify image type @code{gif}. - -@table @code -@item :index @var{index} -You can use @code{:index} to specify one image from a GIF file that -contains more than one image. This property specifies use of image -number @var{index} from the file. If the GIF file doesn't contain an -image with index @var{index}, the image displays as a hollow box. -@end table - -@ignore -This could be used to implement limited support for animated GIFs. -For example, the following function displays a multi-image GIF file -at point-min in the current buffer, switching between sub-images -every 0.1 seconds. - -(defun show-anim (file max) - "Display multi-image GIF file FILE which contains MAX subimages." - (display-anim (current-buffer) file 0 max t)) - -(defun display-anim (buffer file idx max first-time) - (when (= idx max) - (setq idx 0)) - (let ((img (create-image file nil :image idx))) - (save-excursion - (set-buffer buffer) - (goto-char (point-min)) - (unless first-time (delete-char 1)) - (insert-image img)) - (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) -@end ignore - -@node TIFF Images -@subsection TIFF Images -@cindex TIFF - - For TIFF images, specify image type @code{tiff}. - -@table @code -@item :index @var{index} -You can use @code{:index} to specify one image from a TIFF file that -contains more than one image. This property specifies use of image -number @var{index} from the file. If the TIFF file doesn't contain an -image with index @var{index}, the image displays as a hollow box. -@end table - -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - -@node Other Image Types -@subsection Other Image Types -@cindex PBM - - For PBM images, specify image type @code{pbm}. Color, gray-scale and -monochromatic images are supported. For mono PBM images, two additional -image properties are supported. - -@table @code -@item :foreground @var{foreground} -The value, @var{foreground}, should be a string specifying the image -foreground color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 1. The default is the frame's -foreground color. - -@item :background @var{background} -The value, @var{background}, should be a string specifying the image -background color, or @code{nil} for the default color. This color is -used for each pixel in the PBM that is 0. The default is the frame's -background color. -@end table - - For JPEG images, specify image type @code{jpeg}. - - For TIFF images, specify image type @code{tiff}. - - For PNG images, specify image type @code{png}. - - For SVG images, specify image type @code{svg}. - -@node Defining Images -@subsection Defining Images - - The functions @code{create-image}, @code{defimage} and -@code{find-image} provide convenient ways to create image descriptors. - -@defun create-image file-or-data &optional type data-p &rest props -This function creates and returns an image descriptor which uses the -data in @var{file-or-data}. @var{file-or-data} can be a file name or -a string containing the image data; @var{data-p} should be @code{nil} -for the former case, non-@code{nil} for the latter case. - -The optional argument @var{type} is a symbol specifying the image type. -If @var{type} is omitted or @code{nil}, @code{create-image} tries to -determine the image type from the file's first few bytes, or else -from the file's name. - -The remaining arguments, @var{props}, specify additional image -properties---for example, - -@example -(create-image "foo.xpm" 'xpm nil :heuristic-mask t) -@end example - -The function returns @code{nil} if images of this type are not -supported. Otherwise it returns an image descriptor. -@end defun - -@defmac defimage symbol specs &optional doc -This macro defines @var{symbol} as an image name. The arguments -@var{specs} is a list which specifies how to display the image. -The third argument, @var{doc}, is an optional documentation string. - -Each argument in @var{specs} has the form of a property list, and each -one should specify at least the @code{:type} property and either the -@code{:file} or the @code{:data} property. The value of @code{:type} -should be a symbol specifying the image type, the value of -@code{:file} is the file to load the image from, and the value of -@code{:data} is a string containing the actual image data. Here is an -example: - -@example -(defimage test-image - ((:type xpm :file "~/test1.xpm") - (:type xbm :file "~/test1.xbm"))) -@end example - -@code{defimage} tests each argument, one by one, to see if it is -usable---that is, if the type is supported and the file exists. The -first usable argument is used to make an image descriptor which is -stored in @var{symbol}. - -If none of the alternatives will work, then @var{symbol} is defined -as @code{nil}. -@end defmac - -@defun find-image specs -This function provides a convenient way to find an image satisfying one -of a list of image specifications @var{specs}. - -Each specification in @var{specs} is a property list with contents -depending on image type. All specifications must at least contain the -properties @code{:type @var{type}} and either @w{@code{:file @var{file}}} -or @w{@code{:data @var{DATA}}}, where @var{type} is a symbol specifying -the image type, e.g.@: @code{xbm}, @var{file} is the file to load the -image from, and @var{data} is a string containing the actual image data. -The first specification in the list whose @var{type} is supported, and -@var{file} exists, is used to construct the image specification to be -returned. If no specification is satisfied, @code{nil} is returned. - -The image is looked for in @code{image-load-path}. -@end defun - -@defvar image-load-path -This variable's value is a list of locations in which to search for -image files. If an element is a string or a variable symbol whose -value is a string, the string is taken to be the name of a directory -to search. If an element is a variable symbol whose value is a list, -that is taken to be a list of directory names to search. - -The default is to search in the @file{images} subdirectory of the -directory specified by @code{data-directory}, then the directory -specified by @code{data-directory}, and finally in the directories in -@code{load-path}. Subdirectories are not automatically included in -the search, so if you put an image file in a subdirectory, you have to -supply the subdirectory name explicitly. For example, to find the -image @file{images/foo/bar.xpm} within @code{data-directory}, you -should specify the image as follows: - -@example -(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) -@end example -@end defvar - -@defun image-load-path-for-library library image &optional path no-error -This function returns a suitable search path for images used by the -Lisp package @var{library}. - -The function searches for @var{image} first using @code{image-load-path}, -excluding @file{@code{data-directory}/images}, and then in -@code{load-path}, followed by a path suitable for @var{library}, which -includes @file{../../etc/images} and @file{../etc/images} relative to -the library file itself, and finally in -@file{@code{data-directory}/images}. - -Then this function returns a list of directories which contains first -the directory in which @var{image} was found, followed by the value of -@code{load-path}. If @var{path} is given, it is used instead of -@code{load-path}. - -If @var{no-error} is non-@code{nil} and a suitable path can't be -found, don't signal an error. Instead, return a list of directories as -before, except that @code{nil} appears in place of the image directory. - -Here is an example that uses a common idiom to provide compatibility -with versions of Emacs that lack the variable @code{image-load-path}: - -@example -(defvar image-load-path) ; shush compiler -(let* ((load-path (image-load-path-for-library - "mh-e" "mh-logo.xpm")) - (image-load-path (cons (car load-path) - (when (boundp 'image-load-path) - image-load-path)))) - (mh-tool-bar-folder-buttons-init)) -@end example -@end defun - -@node Showing Images -@subsection Showing Images - - You can use an image descriptor by setting up the @code{display} -property yourself, but it is easier to use the functions in this -section. - -@defun insert-image image &optional string area slice -This function inserts @var{image} in the current buffer at point. The -value @var{image} should be an image descriptor; it could be a value -returned by @code{create-image}, or the value of a symbol defined with -@code{defimage}. The argument @var{string} specifies the text to put -in the buffer to hold the image. If it is omitted or @code{nil}, -@code{insert-image} uses @code{" "} by default. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -The argument @var{slice} specifies a slice of the image to insert. If -@var{slice} is @code{nil} or omitted the whole image is inserted. -Otherwise, @var{slice} is a list @code{(@var{x} @var{y} @var{width} -@var{height})} which specifies the @var{x} and @var{y} positions and -@var{width} and @var{height} of the image area to insert. Integer -values are in units of pixels. A floating point number in the range -0.0--1.0 stands for that fraction of the width or height of the entire -image. - -Internally, this function inserts @var{string} in the buffer, and gives -it a @code{display} property which specifies @var{image}. @xref{Display -Property}. -@end defun - -@defun insert-sliced-image image &optional string area rows cols -This function inserts @var{image} in the current buffer at point, like -@code{insert-image}, but splits the image into @var{rows}x@var{cols} -equally sized slices. -@end defun - -@defun put-image image pos &optional string area -This function puts image @var{image} in front of @var{pos} in the -current buffer. The argument @var{pos} should be an integer or a -marker. It specifies the buffer position where the image should appear. -The argument @var{string} specifies the text that should hold the image -as an alternative to the default. - -The argument @var{image} must be an image descriptor, perhaps returned -by @code{create-image} or stored by @code{defimage}. - -The argument @var{area} specifies whether to put the image in a margin. -If it is @code{left-margin}, the image appears in the left margin; -@code{right-margin} specifies the right margin. If @var{area} is -@code{nil} or omitted, the image is displayed at point within the -buffer's text. - -Internally, this function creates an overlay, and gives it a -@code{before-string} property containing text that has a @code{display} -property whose value is the image. (Whew!) -@end defun - -@defun remove-images start end &optional buffer -This function removes images in @var{buffer} between positions -@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, -images are removed from the current buffer. - -This removes only images that were put into @var{buffer} the way -@code{put-image} does it, not images that were inserted with -@code{insert-image} or in other ways. -@end defun - -@defun image-size spec &optional pixels frame -This function returns the size of an image as a pair -@w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). -@end defun - -@defvar max-image-size -This variable is used to define the maximum size of image that Emacs -will load. Emacs will refuse to load (and display) any image that is -larger than this limit. - -If the value is an integer, it directly specifies the maximum -image height and width, measured in pixels. If it is a floating -point number, it specifies the maximum image height and width -as a ratio to the frame height and width. If the value is -non-numeric, there is no explicit limit on the size of images. - -The purpose of this variable is to prevent unreasonably large images -from accidentally being loaded into Emacs. It only takes effect the -first time an image is loaded. Once an image is placed in the image -cache, it can always be displayed, even if the value of -@var{max-image-size} is subsequently changed (@pxref{Image Cache}). -@end defvar - -@node Image Cache -@subsection Image Cache -@cindex image cache - - Emacs caches images so that it can display them again more -efficiently. When Emacs displays an image, it searches the image -cache for an existing image specification @code{equal} to the desired -specification. If a match is found, the image is displayed from the -cache; otherwise, Emacs loads the image normally. - - Occasionally, you may need to tell Emacs to refresh the images -associated with a given image specification. For example, suppose you -display an image using a specification that contains a @code{:file} -property. The image is automatically cached, and subsequent displays -of that image, with the same image specification, will use the image -cache. If the image file changes in the meantime, Emacs would be -displaying the old version of the image. In such a situation, you can -``refresh'' the image by calling @code{image-refresh}. - - In Emacs' current implementation, each graphical terminal possesses -an image cache, which is shared by all the frames on that terminal -(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame -also refreshes it in all other frames on the same terminal. - -@defun image-refresh spec &optional frame -This function refreshes any images with image specifications -@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is -@code{nil}, it defaults to the selected frame. If @var{frame} is -@code{t}, the refresh is applied to all existing frames. -@end defun - -@defun clear-image-cache &optional filter -This function clears an image cache, removing all the images stored in -it. If @var{filter} is omitted or @code{nil}, it clears the cache for -the selected frame. If @var{filter} is a frame, it clears the cache -for that frame. If @var{filter} is @code{t}, all image caches are -cleared. Otherwise, @var{filter} is taken to be a file name, and all -images associated with that file name are removed from all image -caches. -@end defun - -If an image in the image cache has not been displayed for a specified -period of time, Emacs removes it from the cache and frees the -associated memory. - -@defvar image-cache-eviction-delay -This variable specifies the number of seconds an image can remain in the -cache without being displayed. When an image is not displayed for this -length of time, Emacs removes it from the image cache. - -If the value is @code{nil}, Emacs does not remove images from the cache -except when you explicitly clear it. This mode can be useful for -debugging. -@end defvar - -@node Buttons -@section Buttons -@cindex buttons in buffers -@cindex clickable buttons in buffers - - The @emph{button} package defines functions for inserting and -manipulating clickable (with the mouse, or via keyboard commands) -buttons in Emacs buffers, such as might be used for help hyper-links, -etc. Emacs uses buttons for the hyper-links in help text and the like. - - A button is essentially a set of properties attached (via text -properties or overlays) to a region of text in an Emacs buffer. These -properties are called @dfn{button properties}. - - One of these properties (@code{action}) is a function, which will -be called when the user invokes it using the keyboard or the mouse. -The invoked function may then examine the button and use its other -properties as desired. - - In some ways the Emacs button package duplicates functionality offered -by the widget package (@pxref{Top, , Introduction, widget, The Emacs -Widget Library}), but the button package has the advantage that it is -much faster, much smaller, and much simpler to use (for elisp -programmers---for users, the result is about the same). The extra -speed and space savings are useful mainly if you need to create many -buttons in a buffer (for instance an @code{*Apropos*} buffer uses -buttons to make entries clickable, and may contain many thousands of -entries). - -@menu -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. -@end menu - -@node Button Properties -@subsection Button Properties -@cindex button properties - - Buttons have an associated list of properties defining their -appearance and behavior, and other arbitrary properties may be used -for application specific purposes. Some properties that have special -meaning to the button package include: - -@table @code -@item action -@kindex action @r{(button property)} -The function to call when the user invokes the button, which is passed -the single argument @var{button}. By default this is @code{ignore}, -which does nothing. - -@item mouse-action -@kindex mouse-action @r{(button property)} -This is similar to @code{action}, and when present, will be used -instead of @code{action} for button invocations resulting from -mouse-clicks (instead of the user hitting @key{RET}). If not -present, mouse-clicks use @code{action} instead. - -@item face -@kindex face @r{(button property)} -This is an Emacs face controlling how buttons of this type are -displayed; by default this is the @code{button} face. - -@item mouse-face -@kindex mouse-face @r{(button property)} -This is an additional face which controls appearance during -mouse-overs (merged with the usual button face); by default this is -the usual Emacs @code{highlight} face. - -@item keymap -@kindex keymap @r{(button property)} -The button's keymap, defining bindings active within the button -region. By default this is the usual button region keymap, stored -in the variable @code{button-map}, which defines @key{RET} and -@key{mouse-2} to invoke the button. - -@item type -@kindex type @r{(button property)} -The button-type of the button. When creating a button, this is -usually specified using the @code{:type} keyword argument. -@xref{Button Types}. - -@item help-echo -@kindex help-index @r{(button property)} -A string displayed by the Emacs tool-tip help system; by default, -@code{"mouse-2, RET: Push this button"}. - -@item follow-link -@kindex follow-link @r{(button property)} -The follow-link property, defining how a @key{Mouse-1} click behaves -on this button, @xref{Clickable Text}. - -@item button -@kindex button @r{(button property)} -All buttons have a non-@code{nil} @code{button} property, which may be useful -in finding regions of text that comprise buttons (which is what the -standard button functions do). -@end table - - There are other properties defined for the regions of text in a -button, but these are not generally interesting for typical uses. - -@node Button Types -@subsection Button Types -@cindex button types - - Every button has a button @emph{type}, which defines default values -for the button's properties. Button types are arranged in a -hierarchy, with specialized types inheriting from more general types, -so that it's easy to define special-purpose types of buttons for -specific tasks. - -@defun define-button-type name &rest properties -Define a `button type' called @var{name} (a symbol). -The remaining arguments -form a sequence of @var{property value} pairs, specifying default -property values for buttons with this type (a button's type may be set -by giving it a @code{type} property when creating the button, using -the @code{:type} keyword argument). - -In addition, the keyword argument @code{:supertype} may be used to -specify a button-type from which @var{name} inherits its default -property values. Note that this inheritance happens only when -@var{name} is defined; subsequent changes to a supertype are not -reflected in its subtypes. -@end defun - - Using @code{define-button-type} to define default properties for -buttons is not necessary---buttons without any specified type use the -built-in button-type @code{button}---but it is encouraged, since -doing so usually makes the resulting code clearer and more efficient. - -@node Making Buttons -@subsection Making Buttons -@cindex making buttons - - Buttons are associated with a region of text, using an overlay or -text properties to hold button-specific information, all of which are -initialized from the button's type (which defaults to the built-in -button type @code{button}). Like all Emacs text, the appearance of -the button is governed by the @code{face} property; by default (via -the @code{face} property inherited from the @code{button} button-type) -this is a simple underline, like a typical web-page link. - - For convenience, there are two sorts of button-creation functions, -those that add button properties to an existing region of a buffer, -called @code{make-...button}, and those that also insert the button -text, called @code{insert-...button}. - - The button-creation functions all take the @code{&rest} argument -@var{properties}, which should be a sequence of @var{property value} -pairs, specifying properties to add to the button; see @ref{Button -Properties}. In addition, the keyword argument @code{:type} may be -used to specify a button-type from which to inherit other properties; -see @ref{Button Types}. Any properties not explicitly specified -during creation will be inherited from the button's type (if the type -defines such a property). - - The following functions add a button using an overlay -(@pxref{Overlays}) to hold the button properties: - -@defun make-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the -current buffer, and returns it. -@end defun - -@defun insert-button label &rest properties -This insert a button with the label @var{label} at point, -and returns it. -@end defun - - The following functions are similar, but use Emacs text properties -(@pxref{Text Properties}) to hold the button properties, making the -button actually part of the text instead of being a property of the -buffer. Buttons using text properties do not create markers into the -buffer, which is important for speed when you use extremely large -numbers of buttons. Both functions return the position of the start -of the new button: - -@defun make-text-button beg end &rest properties -This makes a button from @var{beg} to @var{end} in the current buffer, using -text properties. -@end defun - -@defun insert-text-button label &rest properties -This inserts a button with the label @var{label} at point, using text -properties. -@end defun - -@node Manipulating Buttons -@subsection Manipulating Buttons -@cindex manipulating buttons - -These are functions for getting and setting properties of buttons. -Often these are used by a button's invocation function to determine -what to do. - -Where a @var{button} parameter is specified, it means an object -referring to a specific button, either an overlay (for overlay -buttons), or a buffer-position or marker (for text property buttons). -Such an object is passed as the first argument to a button's -invocation function when it is invoked. - -@defun button-start button -Return the position at which @var{button} starts. -@end defun - -@defun button-end button -Return the position at which @var{button} ends. -@end defun - -@defun button-get button prop -Get the property of button @var{button} named @var{prop}. -@end defun - -@defun button-put button prop val -Set @var{button}'s @var{prop} property to @var{val}. -@end defun - -@defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@end defun - -@defun button-label button -Return @var{button}'s text label. -@end defun - -@defun button-type button -Return @var{button}'s button-type. -@end defun - -@defun button-has-type-p button type -Return @code{t} if @var{button} has button-type @var{type}, or one of -@var{type}'s subtypes. -@end defun - -@defun button-at pos -Return the button at position @var{pos} in the current buffer, or @code{nil}. -@end defun - -@defun button-type-put type prop val -Set the button-type @var{type}'s @var{prop} property to @var{val}. -@end defun - -@defun button-type-get type prop -Get the property of button-type @var{type} named @var{prop}. -@end defun - -@defun button-type-subtype-p type supertype -Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. -@end defun - -@node Button Buffer Commands -@subsection Button Buffer Commands -@cindex button buffer commands - -These are commands and functions for locating and operating on -buttons in an Emacs buffer. - -@code{push-button} is the command that a user uses to actually `push' -a button, and is bound by default in the button itself to @key{RET} -and to @key{mouse-2} using a region-specific keymap. Commands -that are useful outside the buttons itself, such as -@code{forward-button} and @code{backward-button} are additionally -available in the keymap stored in @code{button-buffer-map}; a mode -which uses buttons may want to use @code{button-buffer-map} as a -parent keymap for its keymap. - -If the button has a non-@code{nil} @code{follow-link} property, and -@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click -will also activate the @code{push-button} command. -@xref{Clickable Text}. - -@deffn Command push-button &optional pos use-mouse-action -Perform the action specified by a button at location @var{pos}. -@var{pos} may be either a buffer position or a mouse-event. If -@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a -mouse-event (@pxref{Mouse Events}), try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. -@var{pos} defaults to point, except when @code{push-button} is invoked -interactively as the result of a mouse-event, in which case, the mouse -event's position is used. If there's no button at @var{pos}, do -nothing and return @code{nil}, otherwise return @code{t}. -@end deffn - -@deffn Command forward-button n &optional wrap display-message -Move to the @var{n}th next button, or @var{n}th previous button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@deffn Command backward-button n &optional wrap display-message -Move to the @var{n}th previous button, or @var{n}th next button if -@var{n} is negative. If @var{n} is zero, move to the start of any -button at point. If @var{wrap} is non-@code{nil}, moving past either -end of the buffer continues from the other end. If -@var{display-message} is non-@code{nil}, the button's help-echo string -is displayed. Any button with a non-@code{nil} @code{skip} property -is skipped over. Returns the button found. -@end deffn - -@defun next-button pos &optional count-current -@defunx previous-button pos &optional count-current -Return the next button after (for @code{next-button} or before (for -@code{previous-button}) position @var{pos} in the current buffer. If -@var{count-current} is non-@code{nil}, count any button at @var{pos} -in the search, instead of starting at the next button. -@end defun - -@node Abstract Display -@section Abstract Display -@cindex ewoc -@cindex display, abstract -@cindex display, arbitrary objects -@cindex model/view/controller -@cindex view part, model/view/controller - - The Ewoc package constructs buffer text that represents a structure -of Lisp objects, and updates the text to follow changes in that -structure. This is like the ``view'' component in the -``model/view/controller'' design paradigm. - - An @dfn{ewoc} is a structure that organizes information required to -construct buffer text that represents certain Lisp data. The buffer -text of the ewoc has three parts, in order: first, fixed @dfn{header} -text; next, textual descriptions of a series of data elements (Lisp -objects that you specify); and last, fixed @dfn{footer} text. -Specifically, an ewoc contains information on: - -@itemize @bullet -@item -The buffer which its text is generated in. - -@item -The text's start position in the buffer. - -@item -The header and footer strings. - -@item -A doubly-linked chain of @dfn{nodes}, each of which contains: - -@itemize -@item -A @dfn{data element}, a single Lisp object. - -@item -Links to the preceding and following nodes in the chain. -@end itemize - -@item -A @dfn{pretty-printer} function which is responsible for -inserting the textual representation of a data -element value into the current buffer. -@end itemize - - Typically, you define an ewoc with @code{ewoc-create}, and then pass -the resulting ewoc structure to other functions in the Ewoc package to -build nodes within it, and display it in the buffer. Once it is -displayed in the buffer, other functions determine the correspondance -between buffer positions and nodes, move point from one node's textual -representation to another, and so forth. @xref{Abstract Display -Functions}. - - A node @dfn{encapsulates} a data element much the way a variable -holds a value. Normally, encapsulation occurs as a part of adding a -node to the ewoc. You can retrieve the data element value and place a -new value in its place, like so: - -@lisp -(ewoc-data @var{node}) -@result{} value - -(ewoc-set-data @var{node} @var{new-value}) -@result{} @var{new-value} -@end lisp - -@noindent -You can also use, as the data element value, a Lisp object (list or -vector) that is a container for the ``real'' value, or an index into -some other structure. The example (@pxref{Abstract Display Example}) -uses the latter approach. - - When the data changes, you will want to update the text in the -buffer. You can update all nodes by calling @code{ewoc-refresh}, or -just specific nodes using @code{ewoc-invalidate}, or all nodes -satisfying a predicate using @code{ewoc-map}. Alternatively, you can -delete invalid nodes using @code{ewoc-delete} or @code{ewoc-filter}, -and add new nodes in their place. Deleting a node from an ewoc deletes -its associated textual description from buffer, as well. - -@menu -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. -@end menu - -@node Abstract Display Functions -@subsection Abstract Display Functions - - In this subsection, @var{ewoc} and @var{node} stand for the -structures described above (@pxref{Abstract Display}), while -@var{data} stands for an arbitrary Lisp object used as a data element. - -@defun ewoc-create pretty-printer &optional header footer nosep -This constructs and returns a new ewoc, with no nodes (and thus no data -elements). @var{pretty-printer} should be a function that takes one -argument, a data element of the sort you plan to use in this ewoc, and -inserts its textual description at point using @code{insert} (and never -@code{insert-before-markers}, because that would interfere with the -Ewoc package's internal mechanisms). - -Normally, a newline is automatically inserted after the header, -the footer and every node's textual description. If @var{nosep} -is non-@code{nil}, no newline is inserted. This may be useful for -displaying an entire ewoc on a single line, for example, or for -making nodes ``invisible'' by arranging for @var{pretty-printer} -to do nothing for those nodes. - -An ewoc maintains its text in the buffer that is current when -you create it, so switch to the intended buffer before calling -@code{ewoc-create}. -@end defun - -@defun ewoc-buffer ewoc -This returns the buffer where @var{ewoc} maintains its text. -@end defun - -@defun ewoc-get-hf ewoc -This returns a cons cell @code{(@var{header} . @var{footer})} -made from @var{ewoc}'s header and footer. -@end defun - -@defun ewoc-set-hf ewoc header footer -This sets the header and footer of @var{ewoc} to the strings -@var{header} and @var{footer}, respectively. -@end defun - -@defun ewoc-enter-first ewoc data -@defunx ewoc-enter-last ewoc data -These add a new node encapsulating @var{data}, putting it, respectively, -at the beginning or end of @var{ewoc}'s chain of nodes. -@end defun - -@defun ewoc-enter-before ewoc node data -@defunx ewoc-enter-after ewoc node data -These add a new node encapsulating @var{data}, adding it to -@var{ewoc} before or after @var{node}, respectively. -@end defun - -@defun ewoc-prev ewoc node -@defunx ewoc-next ewoc node -These return, respectively, the previous node and the next node of @var{node} -in @var{ewoc}. -@end defun - -@defun ewoc-nth ewoc n -This returns the node in @var{ewoc} found at zero-based index @var{n}. -A negative @var{n} means count from the end. @code{ewoc-nth} returns -@code{nil} if @var{n} is out of range. -@end defun - -@defun ewoc-data node -This extracts the data encapsulated by @var{node} and returns it. -@end defun - -@defun ewoc-set-data node data -This sets the data encapsulated by @var{node} to @var{data}. -@end defun - -@defun ewoc-locate ewoc &optional pos guess -This determines the node in @var{ewoc} which contains point (or -@var{pos} if specified), and returns that node. If @var{ewoc} has no -nodes, it returns @code{nil}. If @var{pos} is before the first node, -it returns the first node; if @var{pos} is after the last node, it returns -the last node. The optional third arg @var{guess} -should be a node that is likely to be near @var{pos}; this doesn't -alter the result, but makes the function run faster. -@end defun - -@defun ewoc-location node -This returns the start position of @var{node}. -@end defun - -@defun ewoc-goto-prev ewoc arg -@defunx ewoc-goto-next ewoc arg -These move point to the previous or next, respectively, @var{arg}th node -in @var{ewoc}. @code{ewoc-goto-prev} does not move if it is already at -the first node or if @var{ewoc} is empty, whereas @code{ewoc-goto-next} -moves past the last node, returning @code{nil}. Excepting this special -case, these functions return the node moved to. -@end defun - -@defun ewoc-goto-node ewoc node -This moves point to the start of @var{node} in @var{ewoc}. -@end defun - -@defun ewoc-refresh ewoc -This function regenerates the text of @var{ewoc}. It works by -deleting the text between the header and the footer, i.e., all the -data elements' representations, and then calling the pretty-printer -function for each node, one by one, in order. -@end defun - -@defun ewoc-invalidate ewoc &rest nodes -This is similar to @code{ewoc-refresh}, except that only @var{nodes} in -@var{ewoc} are updated instead of the entire set. -@end defun - -@defun ewoc-delete ewoc &rest nodes -This deletes each node in @var{nodes} from @var{ewoc}. -@end defun - -@defun ewoc-filter ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} and -deletes those nodes for which @var{predicate} returns @code{nil}. -Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-collect ewoc predicate &rest args -This calls @var{predicate} for each data element in @var{ewoc} -and returns a list of those elements for which @var{predicate} -returns non-@code{nil}. The elements in the list are ordered -as in the buffer. Any @var{args} are passed to @var{predicate}. -@end defun - -@defun ewoc-map map-function ewoc &rest args -This calls @var{map-function} for each data element in @var{ewoc} and -updates those nodes for which @var{map-function} returns non-@code{nil}. -Any @var{args} are passed to @var{map-function}. -@end defun - -@node Abstract Display Example -@subsection Abstract Display Example - - Here is a simple example using functions of the ewoc package to -implement a ``color components display,'' an area in a buffer that -represents a vector of three integers (itself representing a 24-bit RGB -value) in various ways. - -@example -(setq colorcomp-ewoc nil - colorcomp-data nil - colorcomp-mode-map nil - colorcomp-labels ["Red" "Green" "Blue"]) - -(defun colorcomp-pp (data) - (if data - (let ((comp (aref colorcomp-data data))) - (insert (aref colorcomp-labels data) "\t: #x" - (format "%02X" comp) " " - (make-string (ash comp -2) ?#) "\n")) - (let ((cstr (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (samp " (sample text) ")) - (insert "Color\t: " - (propertize samp 'face `(foreground-color . ,cstr)) - (propertize samp 'face `(background-color . ,cstr)) - "\n")))) - -(defun colorcomp (color) - "Allow fiddling with COLOR in a new buffer. -The buffer is in Color Components mode." - (interactive "sColor (name or #RGB or #RRGGBB): ") - (when (string= "" color) - (setq color "green")) - (unless (color-values color) - (error "No such color: %S" color)) - (switch-to-buffer - (generate-new-buffer (format "originally: %s" color))) - (kill-all-local-variables) - (setq major-mode 'colorcomp-mode - mode-name "Color Components") - (use-local-map colorcomp-mode-map) - (erase-buffer) - (buffer-disable-undo) - (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8)) - (color-values color)))) - (ewoc (ewoc-create 'colorcomp-pp - "\nColor Components\n\n" - (substitute-command-keys - "\n\\@{colorcomp-mode-map@}")))) - (set (make-local-variable 'colorcomp-data) data) - (set (make-local-variable 'colorcomp-ewoc) ewoc) - (ewoc-enter-last ewoc 0) - (ewoc-enter-last ewoc 1) - (ewoc-enter-last ewoc 2) - (ewoc-enter-last ewoc nil))) -@end example - -@cindex controller part, model/view/controller - This example can be extended to be a ``color selection widget'' (in -other words, the controller part of the ``model/view/controller'' -design paradigm) by defining commands to modify @code{colorcomp-data} -and to ``finish'' the selection process, and a keymap to tie it all -together conveniently. - -@smallexample -(defun colorcomp-mod (index limit delta) - (let ((cur (aref colorcomp-data index))) - (unless (= limit cur) - (aset colorcomp-data index (+ cur delta))) - (ewoc-invalidate - colorcomp-ewoc - (ewoc-nth colorcomp-ewoc index) - (ewoc-nth colorcomp-ewoc -1)))) - -(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1)) -(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1)) -(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1)) -(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1)) -(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1)) -(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1)) - -(defun colorcomp-copy-as-kill-and-exit () - "Copy the color components into the kill ring and kill the buffer. -The string is formatted #RRGGBB (hash followed by six hex digits)." - (interactive) - (kill-new (format "#%02X%02X%02X" - (aref colorcomp-data 0) - (aref colorcomp-data 1) - (aref colorcomp-data 2))) - (kill-buffer nil)) - -(setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) -@end smallexample - -Note that we never modify the data in each node, which is fixed when the -ewoc is created to be either @code{nil} or an index into the vector -@code{colorcomp-data}, the actual color components. - -@node Blinking -@section Blinking Parentheses -@cindex parenthesis matching -@cindex blinking parentheses -@cindex balancing parentheses - - This section describes the mechanism by which Emacs shows a matching -open parenthesis when the user inserts a close parenthesis. - -@defvar blink-paren-function -The value of this variable should be a function (of no arguments) to -be called whenever a character with close parenthesis syntax is inserted. -The value of @code{blink-paren-function} may be @code{nil}, in which -case nothing is done. -@end defvar - -@defopt blink-matching-paren -If this variable is @code{nil}, then @code{blink-matching-open} does -nothing. -@end defopt - -@defopt blink-matching-paren-distance -This variable specifies the maximum distance to scan for a matching -parenthesis before giving up. -@end defopt - -@defopt blink-matching-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. -@end defopt - -@deffn Command blink-matching-open -This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax and -moves the cursor momentarily to the matching opening character. If that -character is not already on the screen, it displays the character's -context in the echo area. To avoid long delays, this function does not -search farther than @code{blink-matching-paren-distance} characters. - -Here is an example of calling this function explicitly. - -@smallexample -@group -(defun interactive-blink-matching-open () -@c Do not break this line! -- rms. -@c The first line of a doc string -@c must stand alone. - "Indicate momentarily the start of sexp before point." - (interactive) -@end group -@group - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) -@end group -@end smallexample -@end deffn - -@node Usual Display -@section Usual Display Conventions - - The usual display conventions define how to display each character -code. You can override these conventions by setting up a display table -(@pxref{Display Tables}). Here are the usual display conventions: - -@itemize @bullet -@item -Character codes 32 through 126 map to glyph codes 32 through 126. -Normally this means they display as themselves. - -@item -Character code 9 is a horizontal tab. It displays as whitespace -up to a position determined by @code{tab-width}. - -@item -Character code 10 is a newline. - -@item -All other codes in the range 0 through 31, and code 127, display in one -of two ways according to the value of @code{ctl-arrow}. If it is -non-@code{nil}, these codes map to sequences of two glyphs, where the -first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can -specify a glyph to use instead of @samp{^}.) Otherwise, these codes map -just like the codes in the range 128 to 255. - -On MS-DOS terminals, Emacs arranges by default for the character code -127 to be mapped to the glyph code 127, which normally displays as an -empty polygon. This glyph is used to display non-@acronym{ASCII} characters -that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, -emacs, The GNU Emacs Manual}. - -@item -Character codes 128 through 255 map to sequences of four glyphs, where -the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are -digit characters representing the character code in octal. (A display -table can specify a glyph to use instead of @samp{\}.) - -@item -Multibyte character codes above 256 are displayed as themselves, or as a -question mark or empty box if the terminal cannot display that -character. -@end itemize - - The usual display conventions apply even when there is a display -table, for any character whose entry in the active display table is -@code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. - - These display rules apply to carriage return (character code 13), when -it appears in the buffer. But that character may not appear in the -buffer where you expect it, if it was eliminated as part of end-of-line -conversion (@pxref{Coding System Basics}). - - These variables affect the way certain characters are displayed on the -screen. Since they change the number of columns the characters occupy, -they also affect the indentation functions. These variables also affect -how the mode line is displayed; if you want to force redisplay of the -mode line using the new values, call the function -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@defopt ctl-arrow -@cindex control characters in display -This buffer-local variable controls how control characters are -displayed. If it is non-@code{nil}, they are displayed as a caret -followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as a backslash followed by three octal digits: @samp{\001}. -@end defopt - -@c Following may have overfull hbox. -@defvar default-ctl-arrow -The value of this variable is the default value for @code{ctl-arrow} in -buffers that do not override it. @xref{Default Value}. -@end defvar - -@defopt tab-width -The value of this buffer-local variable is the spacing between tab -stops used for displaying tab characters in Emacs buffers. The value -is in units of columns, and the default is 8. Note that this feature -is completely independent of the user-settable tab stops used by the -command @code{tab-to-tab-stop}. @xref{Indent Tabs}. -@end defopt - -@node Display Tables -@section Display Tables - -@cindex display table -You can use the @dfn{display table} feature to control how all possible -character codes display on the screen. This is useful for displaying -European languages that have letters not in the @acronym{ASCII} character -set. - -The display table maps each character code into a sequence of -@dfn{glyphs}, each glyph being a graphic that takes up one character -position on the screen. You can also define how to display each glyph -on your terminal, using the @dfn{glyph table}. - -Display tables affect how the mode line is displayed; if you want to -force redisplay of the mode line using a new display table, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -@menu -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -@end menu - -@node Display Table Format -@subsection Display Table Format - - A display table is actually a char-table (@pxref{Char-Tables}) with -@code{display-table} as its subtype. - -@defun make-display-table -This creates and returns a display table. The table initially has -@code{nil} in all elements. -@end defun - - The ordinary elements of the display table are indexed by character -codes; the element at index @var{c} says how to display the character -code @var{c}. The value should be @code{nil} or a vector of the -glyphs to be output (@pxref{Glyphs}). @code{nil} says to display the -character @var{c} according to the usual display conventions -(@pxref{Usual Display}). - - @strong{Warning:} if you use the display table to change the display -of newline characters, the whole buffer will be displayed as one long -``line.'' - - The display table also has six ``extra slots'' which serve special -purposes. Here is a table of their meanings; @code{nil} in any slot -means to use the default for that slot, as stated below. - -@table @asis -@item 0 -The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses -arrows in the fringes to indicate truncation, so the display table has -no effect. - -@item 1 -The glyph for the end of a continued line (the default is @samp{\}). -On graphical terminals, Emacs uses curved arrows in the fringes to -indicate continuation, so the display table has no effect. - -@item 2 -The glyph for indicating a character displayed as an octal character -code (the default is @samp{\}). - -@item 3 -The glyph for indicating a control character (the default is @samp{^}). - -@item 4 -A vector of glyphs for indicating the presence of invisible lines (the -default is @samp{...}). @xref{Selective Display}. - -@item 5 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. This takes effect only -when there are no scroll bars; if scroll bars are supported and in use, -a scroll bar separates the two windows. -@end table - - For example, here is how to construct a display table that mimics the -effect of setting @code{ctl-arrow} to a non-@code{nil} value: - -@example -(setq disptab (make-display-table)) -(let ((i 0)) - (while (< i 32) - (or (= i ?\t) (= i ?\n) - (aset disptab i (vector ?^ (+ i 64)))) - (setq i (1+ i))) - (aset disptab 127 (vector ?^ ??))) -@end example - -@defun display-table-slot display-table slot -This function returns the value of the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun set-display-table-slot display-table slot value -This function stores @var{value} in the extra slot @var{slot} of -@var{display-table}. The argument @var{slot} may be a number from 0 to -5 inclusive, or a slot name (symbol). Valid symbols are -@code{truncation}, @code{wrap}, @code{escape}, @code{control}, -@code{selective-display}, and @code{vertical-border}. -@end defun - -@defun describe-display-table display-table -This function displays a description of the display table -@var{display-table} in a help buffer. -@end defun - -@deffn Command describe-current-display-table -This command displays a description of the current display table in a -help buffer. -@end deffn - -@node Active Display Table -@subsection Active Display Table -@cindex active display table - - Each window can specify a display table, and so can each buffer. When -a buffer @var{b} is displayed in window @var{w}, display uses the -display table for window @var{w} if it has one; otherwise, the display -table for buffer @var{b} if it has one; otherwise, the standard display -table if any. The display table chosen is called the @dfn{active} -display table. - -@defun window-display-table &optional window -This function returns @var{window}'s display table, or @code{nil} -if @var{window} does not have an assigned display table. The default -for @var{window} is the selected window. -@end defun - -@defun set-window-display-table window table -This function sets the display table of @var{window} to @var{table}. -The argument @var{table} should be either a display table or -@code{nil}. -@end defun - -@defvar buffer-display-table -This variable is automatically buffer-local in all buffers; its value in -a particular buffer specifies the display table for that buffer. If it -is @code{nil}, that means the buffer does not have an assigned display -table. -@end defvar - -@defvar standard-display-table -This variable's value is the default display table, used whenever a -window has no display table and neither does the buffer displayed in -that window. This variable is @code{nil} by default. -@end defvar - - If there is no display table to use for a particular window---that is, -if the window specifies none, its buffer specifies none, and -@code{standard-display-table} is @code{nil}---then Emacs uses the usual -display conventions for all character codes in that window. @xref{Usual -Display}. - -A number of functions for changing the standard display table -are defined in the library @file{disp-table}. - -@node Glyphs -@subsection Glyphs - -@cindex glyph - A @dfn{glyph} is a generalization of a character; it stands for an -image that takes up a single character position on the screen. Normally -glyphs come from vectors in the display table (@pxref{Display Tables}). - - A glyph is represented in Lisp as a @dfn{glyph code}. A glyph code -can be @dfn{simple} or it can be defined by the @dfn{glyph table}. A -simple glyph code is just a way of specifying a character and a face -to output it in. @xref{Faces}. - - The following functions are used to manipulate simple glyph codes: - -@defun make-glyph-code char &optional face -This function returns a simple glyph code representing char @var{char} -with face @var{face}. -@end defun - -@defun glyph-char glyph -This function returns the character of simple glyph code @var{glyph}. -@end defun - -@defun glyph-face glyph -This function returns face of simple glyph code @var{glyph}, or -@code{nil} if @var{glyph} has the default face (face-id 0). -@xref{Face Functions}. -@end defun - - On character terminals, you can set up a @dfn{glyph table} to define -the meaning of glyph codes (represented as small integers). - -@defvar glyph-table -The value of this variable is the current glyph table. It should be -@code{nil} or a vector whose @var{g}th element defines glyph code -@var{g}. - -If a glyph code is greater than or equal to the length of the glyph -table, that code is automatically simple. If @code{glyph-table} is -@code{nil} then all glyph codes are simple. - -The glyph table is used only on character terminals. On graphical -displays, all glyph codes are simple. -@end defvar - - Here are the meaningful types of elements in the glyph table: - -@table @asis -@item @var{string} -Send the characters in @var{string} to the terminal to output -this glyph code. - -@item @var{code} -Define this glyph code as an alias for glyph code @var{code} created -by @code{make-glyph-code}. You can use such an alias to define a -small-numbered glyph code which specifies a character with a face. - -@item @code{nil} -This glyph code is simple. -@end table - -@defun create-glyph string -This function returns a newly-allocated glyph code which is set up to -display by sending @var{string} to the terminal. -@end defun - -@node Beeping -@section Beeping -@c @cindex beeping "beep" is adjacent -@cindex bell - - This section describes how to make Emacs ring the bell (or blink the -screen) to attract the user's attention. Be conservative about how -often you do this; frequent bells can become irritating. Also be -careful not to use just beeping when signaling an error is more -appropriate. (@xref{Errors}.) - -@defun ding &optional do-not-terminate -@cindex keyboard macro termination -This function beeps, or flashes the screen (see @code{visible-bell} below). -It also terminates any keyboard macro currently executing unless -@var{do-not-terminate} is non-@code{nil}. -@end defun - -@defun beep &optional do-not-terminate -This is a synonym for @code{ding}. -@end defun - -@defopt visible-bell -This variable determines whether Emacs should flash the screen to -represent a bell. Non-@code{nil} means yes, @code{nil} means no. This -is effective on graphical displays, and on text-only terminals -provided the terminal's Termcap entry defines the visible bell -capability (@samp{vb}). -@end defopt - -@defvar ring-bell-function -If this is non-@code{nil}, it specifies how Emacs should ``ring the -bell.'' Its value should be a function of no arguments. If this is -non-@code{nil}, it takes precedence over the @code{visible-bell} -variable. -@end defvar - -@node Window Systems -@section Window Systems - - Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window,'' but use it -differently. An Emacs frame is a single window as far as X is -concerned; the individual Emacs windows are not known to X at all. - -@defvar window-system -This frame-local variable tells Lisp programs what window system Emacs is using -for displaying the frame. The possible values are - -@table @code -@item x -@cindex X Window System -Emacs is displaying the frame using X. -@item w32 -Emacs is displaying the frame using native MS-Windows GUI. -@item ns -Emacs is displaying the frame using the Nextstep interface (used on -GNUstep and Mac OS X). -@item pc -Emacs is displaying the frame using MS-DOS direct screen writes. -@item nil -Emacs is displaying the frame on a character-based terminal. -@end table -@end defvar - -@defvar initial-window-system -This variable holds the value of @code{window-system} used for the -first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) -@end defvar - -@defun window-system &optional frame -This function returns a symbol whose name tells what window system is -used for displaying @var{frame} (which defaults to the currently -selected frame). The list of possible symbols it returns is the same -one documented for the variable @code{window-system} above. -@end defun - -@defvar window-setup-hook -This variable is a normal hook which Emacs runs after handling the -initialization files. Emacs runs this hook after it has completed -loading your init file, the default initialization file (if -any), and the terminal-specific Lisp code, and running the hook -@code{term-setup-hook}. - -This hook is used for internal purposes: setting up communication with -the window system, and creating the initial window. Users should not -interfere with it. -@end defvar - -@ignore - arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6 -@end ignore diff --git a/doc/lispref/doclicense.texi b/doc/lispref/doclicense.texi deleted file mode 100644 index 9adddffba98..00000000000 --- a/doc/lispref/doclicense.texi +++ /dev/null @@ -1,514 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@node GNU Free Documentation License, GPL, Antinews, Top - -@appendix GNU Free Documentation License -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - -@ignore - arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c -@end ignore diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi deleted file mode 100644 index 943bab416ef..00000000000 --- a/doc/lispref/edebug.texi +++ /dev/null @@ -1,1594 +0,0 @@ -@comment -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. - -@c This file can also be used by an independent Edebug User -@c Manual in which case the Edebug node below should be used -@c with the following links to the Bugs section and to the top level: - -@c , Bugs and Todo List, Top, Top - -@node Edebug, Syntax Errors, Debugger, Debugging -@section Edebug -@cindex Edebug debugging facility - - Edebug is a source-level debugger for Emacs Lisp programs, with which -you can: - -@itemize @bullet -@item -Step through evaluation, stopping before and after each expression. - -@item -Set conditional or unconditional breakpoints. - -@item -Stop when a specified condition is true (the global break event). - -@item -Trace slow or fast, stopping briefly at each stop point, or -at each breakpoint. - -@item -Display expression results and evaluate expressions as if outside of -Edebug. - -@item -Automatically re-evaluate a list of expressions and -display their results each time Edebug updates the display. - -@item -Output trace information on function calls and returns. - -@item -Stop when an error occurs. - -@item -Display a backtrace, omitting Edebug's own frames. - -@item -Specify argument evaluation for macros and defining forms. - -@item -Obtain rudimentary coverage testing and frequency counts. -@end itemize - -The first three sections below should tell you enough about Edebug to -start using it. - -@menu -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Misc: Edebug Misc. Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Views: Edebug Views. Views inside and outside of Edebug. -* Eval: Edebug Eval. Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Options: Edebug Options. Option variables for customizing Edebug. -@end menu - -@node Using Edebug -@subsection Using Edebug - - To debug a Lisp program with Edebug, you must first @dfn{instrument} -the Lisp code that you want to debug. A simple way to do this is to -first move point into the definition of a function or macro and then do -@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See -@ref{Instrumenting}, for alternative ways to instrument code. - - Once a function is instrumented, any call to the function activates -Edebug. Depending on which Edebug execution mode you have selected, -activating Edebug may stop execution and let you step through the -function, or it may update the display and continue execution while -checking for debugging commands. The default execution mode is step, -which stops execution. @xref{Edebug Execution Modes}. - - Within Edebug, you normally view an Emacs buffer showing the source of -the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}, and it is temporarily read-only. - - An arrow in the left fringe indicates the line where the function is -executing. Point initially shows where within the line the function is -executing, but this ceases to be true if you move point yourself. - - If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you would normally see. Point is -at the open-parenthesis before @code{if}. - -@example -(defun fac (n) -=>@point{}(if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -@cindex stop points -The places within a function where Edebug can stop execution are called -@dfn{stop points}. These occur both before and after each subexpression -that is a list, and also after each variable reference. -Here we use periods to show the stop points in the function -@code{fac}: - -@example -(defun fac (n) - .(if .(< 0 n.). - .(* n. .(fac .(1- n.).).). - 1).) -@end example - -The special commands of Edebug are available in the source code buffer -in addition to the commands of Emacs Lisp mode. For example, you can -type the Edebug command @key{SPC} to execute until the next stop point. -If you type @key{SPC} once after entry to @code{fac}, here is the -display you will see: - -@example -(defun fac (n) -=>(if @point{}(< 0 n) - (* n (fac (1- n))) - 1)) -@end example - -When Edebug stops execution after an expression, it displays the -expression's value in the echo area. - -Other frequently used commands are @kbd{b} to set a breakpoint at a stop -point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to -exit Edebug and return to the top-level command loop. Type @kbd{?} to -display a list of all Edebug commands. - -@node Instrumenting -@subsection Instrumenting for Edebug - - In order to use Edebug to debug Lisp code, you must first -@dfn{instrument} the code. Instrumenting code inserts additional code -into it, to invoke Edebug at the proper places. - -@kindex C-M-x -@findex eval-defun (Edebug) - When you invoke command @kbd{C-M-x} (@code{eval-defun}) with a -prefix argument on a function definition, it instruments the -definition before evaluating it. (This does not modify the source -code itself.) If the variable @code{edebug-all-defs} is -non-@code{nil}, that inverts the meaning of the prefix argument: in -this case, @kbd{C-M-x} instruments the definition @emph{unless} it has -a prefix argument. The default value of @code{edebug-all-defs} is -@code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value -of the variable @code{edebug-all-defs}. - -@findex eval-region @r{(Edebug)} -@findex eval-buffer @r{(Edebug)} -@findex eval-current-buffer @r{(Edebug)} - If @code{edebug-all-defs} is non-@code{nil}, then the commands -@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} -also instrument any definitions they evaluate. Similarly, -@code{edebug-all-forms} controls whether @code{eval-region} should -instrument @emph{any} form, even non-defining forms. This doesn't apply -to loading or evaluations in the minibuffer. The command @kbd{M-x -edebug-all-forms} toggles this option. - -@findex edebug-eval-top-level-form - Another command, @kbd{M-x edebug-eval-top-level-form}, is available to -instrument any top-level form regardless of the values of -@code{edebug-all-defs} and @code{edebug-all-forms}. - - While Edebug is active, the command @kbd{I} -(@code{edebug-instrument-callee}) instruments the definition of the -function or macro called by the list form after point, if is not already -instrumented. This is possible only if Edebug knows where to find the -source for that function; for this reason, after loading Edebug, -@code{eval-region} records the position of every definition it -evaluates, even if not instrumenting it. See also the @kbd{i} command -(@pxref{Jumping}), which steps into the call after instrumenting the -function. - - Edebug knows how to instrument all the standard special forms, -@code{interactive} forms with an expression argument, anonymous lambda -expressions, and other defining forms. However, Edebug cannot determine -on its own what a user-defined macro will do with the arguments of a -macro call, so you must provide that information using Edebug -specifications; for details, @pxref{Edebug and Macros}. - - When Edebug is about to instrument code for the first time in a -session, it runs the hook @code{edebug-setup-hook}, then sets it to -@code{nil}. You can use this to load Edebug specifications -associated with a package you are using, but only when you use Edebug. - -@findex eval-expression @r{(Edebug)} - To remove instrumentation from a definition, simply re-evaluate its -definition in a way that does not instrument. There are two ways of -evaluating forms that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - If Edebug detects a syntax error while instrumenting, it leaves point -at the erroneous code and signals an @code{invalid-read-syntax} error. - - @xref{Edebug Eval}, for other evaluation functions available -inside of Edebug. - -@node Edebug Execution Modes -@subsection Edebug Execution Modes - -@cindex Edebug execution modes -Edebug supports several execution modes for running the program you are -debugging. We call these alternatives @dfn{Edebug execution modes}; do -not confuse them with major or minor modes. The current Edebug execution mode -determines how far Edebug continues execution before stopping---whether -it stops at each stop point, or continues to the next breakpoint, for -example---and how much Edebug displays the progress of the evaluation -before it stops. - -Normally, you specify the Edebug execution mode by typing a command to -continue the program in a certain mode. Here is a table of these -commands; all except for @kbd{S} resume execution of the program, at -least for a certain distance. - -@table @kbd -@item S -Stop: don't execute any more of the program, but wait for more -Edebug commands (@code{edebug-stop}). - -@item @key{SPC} -Step: stop at the next stop point encountered (@code{edebug-step-mode}). - -@item n -Next: stop at the next stop point encountered after an expression -(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in -@ref{Jumping}. - -@item t -Trace: pause (normally one second) at each Edebug stop point -(@code{edebug-trace-mode}). - -@item T -Rapid trace: update the display at each stop point, but don't actually -pause (@code{edebug-Trace-fast-mode}). - -@item g -Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. - -@item c -Continue: pause one second at each breakpoint, and then continue -(@code{edebug-continue-mode}). - -@item C -Rapid continue: move point to each breakpoint, but don't pause -(@code{edebug-Continue-fast-mode}). - -@item G -Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You -can still stop the program by typing @kbd{S}, or any editing command. -@end table - -In general, the execution modes earlier in the above list run the -program more slowly or stop sooner than the modes later in the list. - -While executing or tracing, you can interrupt the execution by typing -any Edebug command. Edebug stops the program at the next stop point and -then executes the command you typed. For example, typing @kbd{t} during -execution switches to trace mode at the next stop point. You can use -@kbd{S} to stop execution without doing anything else. - -If your function happens to read input, a character you type intending -to interrupt execution may be read by the function instead. You can -avoid such unintended results by paying attention to when your program -wants input. - -@cindex keyboard macros (Edebug) -Keyboard macros containing the commands in this section do not -completely work: exiting from Edebug, to resume the program, loses track -of the keyboard macro. This is not easy to fix. Also, defining or -executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. See also the -@code{edebug-continue-kbd-macro} option in @ref{Edebug Options}. - -When you enter a new Edebug level, the initial execution mode comes -from the value of the variable @code{edebug-initial-mode} -(@pxref{Edebug Options}). By default, this specifies step mode. Note -that you may reenter the same Edebug level several times if, for -example, an instrumented function is called several times from one -command. - -@defopt edebug-sit-for-seconds -This option specifies how many seconds to wait between execution steps -in trace mode or continue mode. The default is 1 second. -@end defopt - -@node Jumping -@subsection Jumping - - The commands described in this section execute until they reach a -specified location. All except @kbd{i} make a temporary breakpoint to -establish the place to stop, then switch to go mode. Any other -breakpoint reached before the intended stop point will also stop -execution. @xref{Breakpoints}, for the details on breakpoints. - - These commands may fail to work as expected in case of nonlocal exit, -as that can bypass the temporary breakpoint where you expected the -program to stop. - -@table @kbd -@item h -Proceed to the stop point near where point is (@code{edebug-goto-here}). - -@item f -Run the program for one expression -(@code{edebug-forward-sexp}). - -@item o -Run the program until the end of the containing sexp (@code{edebug-step-out}). - -@item i -Step into the function or macro called by the form after point. -@end table - -The @kbd{h} command proceeds to the stop point at or after the current -location of point, using a temporary breakpoint. - -The @kbd{f} command runs the program forward over one expression. More -precisely, it sets a temporary breakpoint at the position that -@code{forward-sexp} would reach, then executes in go mode so that -the program will stop at breakpoints. - -With a prefix argument @var{n}, the temporary breakpoint is placed -@var{n} sexps beyond point. If the containing list ends before @var{n} -more elements, then the place to stop is after the containing -expression. - -You must check that the position @code{forward-sexp} finds is a place -that the program will really get to. In @code{cond}, for example, -this may not be true. - -For flexibility, the @kbd{f} command does @code{forward-sexp} starting -at point, rather than at the stop point. If you want to execute one -expression @emph{from the current stop point}, first type @kbd{w} -(@code{edebug-where}) to move point there, and then type @kbd{f}. - -The @kbd{o} command continues ``out of'' an expression. It places a -temporary breakpoint at the end of the sexp containing point. If the -containing sexp is a function definition itself, @kbd{o} continues until -just before the last sexp in the definition. If that is where you are -now, it returns from the function and then stops. In other words, this -command does not exit the currently executing function unless you are -positioned after the last sexp. - -The @kbd{i} command steps into the function or macro called by the list -form after point, and stops at its first stop point. Note that the form -need not be the one about to be evaluated. But if the form is a -function call about to be evaluated, remember to use this command before -any of the arguments are evaluated, since otherwise it will be too late. - -The @kbd{i} command instruments the function or macro it's supposed to -step into, if it isn't instrumented already. This is convenient, but keep -in mind that the function or macro remains instrumented unless you explicitly -arrange to deinstrument it. - -@node Edebug Misc -@subsection Miscellaneous Edebug Commands - - Some miscellaneous Edebug commands are described here. - -@table @kbd -@item ? -Display the help message for Edebug (@code{edebug-help}). - -@item C-] -Abort one level back to the previous command level -(@code{abort-recursive-edit}). - -@item q -Return to the top level editor command loop (@code{top-level}). This -exits all recursive editing levels, including all levels of Edebug -activity. However, instrumented code protected with -@code{unwind-protect} or @code{condition-case} forms may resume -debugging. - -@item Q -Like @kbd{q}, but don't stop even for protected code -(@code{edebug-top-level-nonstop}). - -@item r -Redisplay the most recently known expression result in the echo area -(@code{edebug-previous-result}). - -@item d -Display a backtrace, excluding Edebug's own functions for clarity -(@code{edebug-backtrace}). - -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. - -The backtrace buffer is killed automatically when you continue -execution. -@end table - -You can invoke commands from Edebug that activate Edebug again -recursively. Whenever Edebug is active, you can quit to the top level -with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can -display a backtrace of all the pending evaluations with @kbd{d}. - -@node Breaks -@subsection Breaks - -Edebug's step mode stops execution when the next stop point is reached. -There are three other ways to stop Edebug execution once it has started: -breakpoints, the global break condition, and source breakpoints. - -@menu -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. -@end menu - -@node Breakpoints -@subsubsection Edebug Breakpoints - -@cindex breakpoints (Edebug) -While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: these are places where execution should stop. You can set a -breakpoint at any stop point, as defined in @ref{Using Edebug}. For -setting and unsetting breakpoints, the stop point that is affected is -the first one at or after point in the source code buffer. Here are the -Edebug commands for breakpoints: - -@table @kbd -@item b -Set a breakpoint at the stop point at or after point -(@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary---it turns off the first time it stops the -program. - -@item u -Unset the breakpoint (if any) at the stop point at or after -point (@code{edebug-unset-breakpoint}). - -@item x @var{condition} @key{RET} -Set a conditional breakpoint which stops the program only if -evaluating @var{condition} produces a non-@code{nil} value -(@code{edebug-set-conditional-breakpoint}). With a prefix argument, -the breakpoint is temporary. - -@item B -Move point to the next breakpoint in the current definition -(@code{edebug-next-breakpoint}). -@end table - -While in Edebug, you can set a breakpoint with @kbd{b} and unset one -with @kbd{u}. First move point to the Edebug stop point of your choice, -then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. -Unsetting a breakpoint where none has been set has no effect. - -Re-evaluating or reinstrumenting a definition removes all of its -previous breakpoints. - -A @dfn{conditional breakpoint} tests a condition each time the program -gets there. Any errors that occur as a result of evaluating the -condition are ignored, as if the result were @code{nil}. To set a -conditional breakpoint, use @kbd{x}, and specify the condition -expression in the minibuffer. Setting a conditional breakpoint at a -stop point that has a previously established conditional breakpoint puts -the previous condition expression in the minibuffer so you can edit it. - -You can make a conditional or unconditional breakpoint -@dfn{temporary} by using a prefix argument with the command to set the -breakpoint. When a temporary breakpoint stops the program, it is -automatically unset. - -Edebug always stops or pauses at a breakpoint, except when the Edebug -mode is Go-nonstop. In that mode, it ignores breakpoints entirely. - -To find out where your breakpoints are, use the @kbd{B} command, which -moves point to the next breakpoint following point, within the same -function, or to the first breakpoint if there are no following -breakpoints. This command does not continue execution---it just moves -point in the buffer. - -@node Global Break Condition -@subsubsection Global Break Condition - -@cindex stopping on events -@cindex global break condition - A @dfn{global break condition} stops execution when a specified -condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point; if it -evaluates to a non-@code{nil} value, then execution stops or pauses -depending on the execution mode, as if a breakpoint had been hit. If -evaluating the condition gets an error, execution does not stop. - -@findex edebug-set-global-break-condition - The condition expression is stored in -@code{edebug-global-break-condition}. You can specify a new expression -using the @kbd{X} command from the source code buffer while Edebug is -active, or using @kbd{C-x X X} from any buffer at any time, as long as -Edebug is loaded (@code{edebug-set-global-break-condition}). - - The global break condition is the simplest way to find where in your -code some event occurs, but it makes code run much more slowly. So you -should reset the condition to @code{nil} when not using it. - -@node Source Breakpoints -@subsubsection Source Breakpoints - -@findex edebug -@cindex source breakpoints - All breakpoints in a definition are forgotten each time you -reinstrument it. If you wish to make a breakpoint that won't be -forgotten, you can write a @dfn{source breakpoint}, which is simply a -call to the function @code{edebug} in your source code. You can, of -course, make such a call conditional. For example, in the @code{fac} -function, you can insert the first line as shown below, to stop when the -argument reaches zero: - -@example -(defun fac (n) - (if (= n 0) (edebug)) - (if (< 0 n) - (* n (fac (1- n))) - 1)) -@end example - - When the @code{fac} definition is instrumented and the function is -called, the call to @code{edebug} acts as a breakpoint. Depending on -the execution mode, Edebug stops or pauses there. - - If no instrumented code is being executed when @code{edebug} is called, -that function calls @code{debug}. -@c This may not be a good idea anymore. - -@node Trapping Errors -@subsection Trapping Errors - - Emacs normally displays an error message when an error is signaled and -not handled with @code{condition-case}. While Edebug is active and -executing instrumented code, it normally responds to all unhandled -errors. You can customize this with the options @code{edebug-on-error} -and @code{edebug-on-quit}; see @ref{Edebug Options}. - - When Edebug responds to an error, it shows the last stop point -encountered before the error. This may be the location of a call to a -function which was not instrumented, and within which the error actually -occurred. For an unbound variable error, the last known stop point -might be quite distant from the offending variable reference. In that -case, you might want to display a full backtrace (@pxref{Edebug Misc}). - -@c Edebug should be changed for the following: -- dan - If you change @code{debug-on-error} or @code{debug-on-quit} while -Edebug is active, these changes will be forgotten when Edebug becomes -inactive. Furthermore, during Edebug's recursive edit, these variables -are bound to the values they had outside of Edebug. - -@node Edebug Views -@subsection Edebug Views - - These Edebug commands let you view aspects of the buffer and window -status as they were before entry to Edebug. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Switch to viewing the outside window configuration -(@code{edebug-view-outside}). Type @kbd{C-x X w} to return to Edebug. - -@item p -Temporarily display the outside current buffer with point at its -outside position (@code{edebug-bounce-point}), pausing for one second -before returning to Edebug. With a prefix argument @var{n}, pause for -@var{n} seconds instead. - -@item w -Move point back to the current stop point in the source code buffer -(@code{edebug-where}). - -If you use this command in a different window displaying the same -buffer, that window will be used instead to display the current -definition in the future. - -@item W -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -With a prefix argument, @code{W} only toggles saving and restoring of -the selected window. To specify a window that is not displaying the -source code buffer, you must use @kbd{C-x X W} from the global keymap. -@end table - - You can view the outside window configuration with @kbd{v} or just -bounce to the point in the current buffer with @kbd{p}, even if -it is not normally displayed. - - After moving point, you may wish to jump back to the stop point. -You can do that with @kbd{w} from a source code buffer. You can jump -back to the stop point in the source code buffer from any buffer using -@kbd{C-x X w}. - - Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the -saved outside window configuration---so that even if you turn saving -back @emph{on}, the current window configuration remains unchanged when -you next exit Edebug (by continuing the program). However, the -automatic redisplay of @samp{*edebug*} and @samp{*edebug-trace*} may -conflict with the buffers you wish to see unless you have enough windows -open. - -@node Edebug Eval -@subsection Evaluation - - While within Edebug, you can evaluate expressions ``as if'' Edebug -were not running. Edebug tries to be invisible to the expression's -evaluation and printing. Evaluation of expressions that cause side -effects will work as expected, except for changes to data that Edebug -explicitly saves and restores. @xref{The Outside Context}, for details -on this process. - -@table @kbd -@item e @var{exp} @key{RET} -Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. - -@item M-: @var{exp} @key{RET} -Evaluate expression @var{exp} in the context of Edebug itself -(@code{eval-expression}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). -@end table - -@cindex lexical binding (Edebug) - Edebug supports evaluation of expressions containing references to -lexically bound symbols created by the following constructs in -@file{cl.el}: @code{lexical-let}, @code{macrolet}, and -@code{symbol-macrolet}. - -@node Eval List -@subsection Evaluation List Buffer - - You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to -evaluate expressions interactively. You can also set up the -@dfn{evaluation list} of expressions to be evaluated automatically each -time Edebug updates the display. - -@table @kbd -@item E -Switch to the evaluation list buffer @samp{*edebug*} -(@code{edebug-visit-eval-list}). -@end table - - In the @samp{*edebug*} buffer you can use the commands of Lisp -Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs -Manual}) as well as these special commands: - -@table @kbd -@item C-j -Evaluate the expression before point, in the outside context, and insert -the value in the buffer (@code{edebug-eval-print-last-sexp}). - -@item C-x C-e -Evaluate the expression before point, in the context outside of Edebug -(@code{edebug-eval-last-sexp}). - -@item C-c C-u -Build a new evaluation list from the contents of the buffer -(@code{edebug-update-eval-list}). - -@item C-c C-d -Delete the evaluation list group that point is in -(@code{edebug-delete-eval-item}). - -@item C-c C-w -Switch back to the source code buffer at the current stop point -(@code{edebug-where}). -@end table - - You can evaluate expressions in the evaluation list window with -@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; -but they are evaluated in the context outside of Edebug. - - The expressions you enter interactively (and their results) are lost -when you continue execution; but you can set up an @dfn{evaluation list} -consisting of expressions to be evaluated each time execution stops. - -@cindex evaluation list group - To do this, write one or more @dfn{evaluation list groups} in the -evaluation list buffer. An evaluation list group consists of one or -more Lisp expressions. Groups are separated by comment lines. - - The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the -evaluation list, scanning the buffer and using the first expression of -each group. (The idea is that the second expression of the group is the -value previously computed and displayed.) - - Each entry to Edebug redisplays the evaluation list by inserting each -expression in the buffer, followed by its current value. It also -inserts comment lines so that each expression becomes its own group. -Thus, if you type @kbd{C-c C-u} again without changing the buffer text, -the evaluation list is effectively unchanged. - - If an error occurs during an evaluation from the evaluation list, -the error message is displayed in a string as if it were the result. -Therefore, expressions using variables that are not currently valid do -not interrupt your debugging. - - Here is an example of what the evaluation list window looks like after -several expressions have been added to it: - -@smallexample -(current-buffer) -# -;--------------------------------------------------------------- -(selected-window) -# -;--------------------------------------------------------------- -(point) -196 -;--------------------------------------------------------------- -bad-var -"Symbol's value as variable is void: bad-var" -;--------------------------------------------------------------- -(recursion-depth) -0 -;--------------------------------------------------------------- -this-command -eval-last-sexp -;--------------------------------------------------------------- -@end smallexample - -To delete a group, move point into it and type @kbd{C-c C-d}, or simply -delete the text for the group and update the evaluation list with -@kbd{C-c C-u}. To add a new expression to the evaluation list, insert -the expression at a suitable place, insert a new comment line, then type -@kbd{C-c C-u}. You need not insert dashes in the comment line---its -contents don't matter. - -After selecting @samp{*edebug*}, you can return to the source code -buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when -you continue execution, and recreated next time it is needed. - -@node Printing in Edebug -@subsection Printing in Edebug - -@cindex printing (Edebug) -@cindex printing circular structures -@pindex cust-print - If an expression in your program produces a value containing circular -list structure, you may get an error when Edebug attempts to print it. - - One way to cope with circular structure is to set @code{print-length} -or @code{print-level} to truncate the printing. Edebug does this for -you; it binds @code{print-length} and @code{print-level} to the values -of the variables @code{edebug-print-length} and -@code{edebug-print-level} (so long as they have non-@code{nil} -values). @xref{Output Variables}. - -@defopt edebug-print-length -If non-@code{nil}, Edebug binds @code{print-length} to this value while -printing results. The default value is @code{50}. -@end defopt - -@defopt edebug-print-level -If non-@code{nil}, Edebug binds @code{print-level} to this value while -printing results. The default value is @code{50}. -@end defopt - - You can also print circular structures and structures that share -elements more informatively by binding @code{print-circle} -to a non-@code{nil} value. - - Here is an example of code that creates a circular structure: - -@example -(setq a '(x y)) -(setcar a a) -@end example - -@noindent -Custom printing prints this as @samp{Result: #1=(#1# y)}. The -@samp{#1=} notation labels the structure that follows it with the label -@samp{1}, and the @samp{#1#} notation references the previously labeled -structure. This notation is used for any shared elements of lists or -vectors. - -@defopt edebug-print-circle -If non-@code{nil}, Edebug binds @code{print-circle} to this value while -printing results. The default value is @code{t}. -@end defopt - - Other programs can also use custom printing; see @file{cust-print.el} -for details. - -@node Trace Buffer -@subsection Trace Buffer -@cindex trace buffer - - Edebug can record an execution trace, storing it in a buffer named -@samp{*edebug-trace*}. This is a log of function calls and returns, -showing the function names and their arguments and values. To enable -trace recording, set @code{edebug-trace} to a non-@code{nil} value. - - Making a trace buffer is not the same thing as using trace execution -mode (@pxref{Edebug Execution Modes}). - - When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record consists of -@samp{::::@{}, followed by the function name and argument values. A -function exit record consists of @samp{::::@}}, followed by the function -name and result of the function. - - The number of @samp{:}s in an entry shows its recursion depth. You -can use the braces in the trace buffer to find the matching beginning or -end of function calls. - -@findex edebug-print-trace-before -@findex edebug-print-trace-after - You can customize trace recording for function entry and exit by -redefining the functions @code{edebug-print-trace-before} and -@code{edebug-print-trace-after}. - -@defmac edebug-tracing string body@dots{} -This macro requests additional trace information around the execution -of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer, after the @samp{@{} or @samp{@}}. All -the arguments are evaluated, and @code{edebug-tracing} returns the -value of the last form in @var{body}. -@end defmac - -@defun edebug-trace format-string &rest format-args -This function inserts text in the trace buffer. It computes the text -with @code{(apply 'format @var{format-string} @var{format-args})}. -It also appends a newline to separate entries. -@end defun - - @code{edebug-tracing} and @code{edebug-trace} insert lines in the -trace buffer whenever they are called, even if Edebug is not active. -Adding text to the trace buffer also scrolls its window to show the last -lines inserted. - -@node Coverage Testing -@subsection Coverage Testing - -@cindex coverage testing (Edebug) -@cindex frequency counts -@cindex performance analysis - Edebug provides rudimentary coverage testing and display of execution -frequency. - - Coverage testing works by comparing the result of each expression with -the previous result; each form in the program is considered ``covered'' -if it has returned two different values since you began testing coverage -in the current Emacs session. Thus, to do coverage testing on your -program, execute it under various conditions and note whether it behaves -correctly; Edebug will tell you when you have tried enough different -conditions that each form has returned two different values. - - Coverage testing makes execution slower, so it is only done if -@code{edebug-test-coverage} is non-@code{nil}. Frequency counting is -performed for all executions of an instrumented function, even if the -execution mode is Go-nonstop, and regardless of whether coverage testing -is enabled. - -@kindex C-x X = -@findex edebug-temp-display-freq-count - Use @kbd{C-x X =} (@code{edebug-display-freq-count}) to display both -the coverage information and the frequency counts for a definition. -Just @kbd{=} (@code{edebug-temp-display-freq-count}) displays the same -information temporarily, only until you type another key. - -@deffn Command edebug-display-freq-count -This command displays the frequency count data for each line of the -current definition. - -It inserts frequency counts as comment lines after each line of code. -You can undo all insertions with one @code{undo} command. The counts -appear under the @samp{(} before an expression or the @samp{)} after -an expression, or on the last character of a variable. To simplify -the display, a count is not shown if it is equal to the count of an -earlier expression on the same line. - -The character @samp{=} following the count for an expression says that -the expression has returned the same value each time it was evaluated. -In other words, it is not yet ``covered'' for coverage testing purposes. - -To clear the frequency count and coverage data for a definition, -simply reinstrument it with @code{eval-defun}. -@end deffn - -For example, after evaluating @code{(fac 5)} with a source -breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when -the breakpoint is reached, the frequency data looks like this: - -@example -(defun fac (n) - (if (= n 0) (edebug)) -;#6 1 = =5 - (if (< 0 n) -;#5 = - (* n (fac (1- n))) -;# 5 0 - 1)) -;# 0 -@end example - -The comment lines show that @code{fac} was called 6 times. The -first @code{if} statement returned 5 times with the same result each -time; the same is true of the condition on the second @code{if}. -The recursive call of @code{fac} did not return at all. - - -@node The Outside Context -@subsection The Outside Context - -Edebug tries to be transparent to the program you are debugging, but it -does not succeed completely. Edebug also tries to be transparent when -you evaluate expressions with @kbd{e} or with the evaluation list -buffer, by temporarily restoring the outside context. This section -explains precisely what context Edebug restores, and how Edebug fails to -be completely transparent. - -@menu -* Checking Whether to Stop:: When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. -@end menu - -@node Checking Whether to Stop -@subsubsection Checking Whether to Stop - -Whenever Edebug is entered, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@itemize @bullet -@item -@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both -increased to reduce Edebug's impact on the stack. You could, however, -still run out of stack space when using Edebug. - -@item -The state of keyboard macro execution is saved and restored. While -Edebug is active, @code{executing-kbd-macro} is bound to @code{nil} -unless @code{edebug-continue-kbd-macro} is non-@code{nil}. -@end itemize - - -@node Edebug Display Update -@subsubsection Edebug Display Update - -@c This paragraph is not filled, because LaLiberte's conversion script -@c needs an xref to be on just one line. -When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug -(@pxref{Window Configurations}). When you exit Edebug (by continuing -the program), it restores the previous window configuration. - -Emacs redisplays only when it pauses. Usually, when you continue -execution, the program re-enters Edebug at a breakpoint or after -stepping, without pausing or reading input in between. In such cases, -Emacs never gets a chance to redisplay the ``outside'' configuration. -Consequently, what you see is the same window configuration as the last -time Edebug was active, with no interruption. - -Entry to Edebug for displaying something also saves and restores the -following data (though some of them are deliberately not restored if an -error or quit signal occurs). - -@itemize @bullet -@item -@cindex current buffer point and mark (Edebug) -Which buffer is current, and the positions of point and the mark in the -current buffer, are saved and restored. - -@item -@cindex window configuration (Edebug) -The outside window configuration is saved and restored if -@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Options}). - -The window configuration is not restored on error or quit, but the -outside selected window @emph{is} reselected even on error or quit in -case a @code{save-excursion} is active. If the value of -@code{edebug-save-windows} is a list, only the listed windows are saved -and restored. - -The window start and horizontal scrolling of the source code buffer are -not restored, however, so that the display remains coherent within Edebug. - -@item -The value of point in each displayed buffer is saved and restored if -@code{edebug-save-displayed-buffer-points} is non-@code{nil}. - -@item -The variables @code{overlay-arrow-position} and -@code{overlay-arrow-string} are saved and restored, so you can safely -invoke Edebug from the recursive edit elsewhere in the same buffer. - -@item -@code{cursor-in-echo-area} is locally bound to @code{nil} so that -the cursor shows up in the window. -@end itemize - -@node Edebug Recursive Edit -@subsubsection Edebug Recursive Edit - -When Edebug is entered and actually reads commands from the user, it -saves (and later restores) these additional data: - -@itemize @bullet -@item -The current match data. @xref{Match Data}. - -@item -The variables @code{last-command}, @code{this-command}, -@code{last-input-event}, @code{last-command-event}, -@code{last-event-frame}, @code{last-nonmenu-event}, and -@code{track-mouse}. Commands used within Edebug do not affect these -variables outside of Edebug. - -Executing commands within Edebug can change the key sequence that -would be returned by @code{this-command-keys}, and there is no way to -reset the key sequence from Lisp. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value can interfere with execution of the program you are -debugging. - -@item -Complex commands executed while in Edebug are added to the variable -@code{command-history}. In rare cases this can alter execution. - -@item -Within Edebug, the recursion depth appears one deeper than the recursion -depth outside Edebug. This is not true of the automatically updated -evaluation list window. - -@item -@code{standard-output} and @code{standard-input} are bound to @code{nil} -by the @code{recursive-edit}, but Edebug temporarily restores them during -evaluations. - -@item -The state of keyboard macro definition is saved and restored. While -Edebug is active, @code{defining-kbd-macro} is bound to -@code{edebug-continue-kbd-macro}. -@end itemize - -@node Edebug and Macros -@subsection Edebug and Macros - -To make Edebug properly instrument expressions that call macros, some -extra care is needed. This subsection explains the details. - -@menu -* Instrumenting Macro Calls:: The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. -@end menu - -@node Instrumenting Macro Calls -@subsubsection Instrumenting Macro Calls - - When Edebug instruments an expression that calls a Lisp macro, it needs -additional information about the macro to do the job properly. This is -because there is no a-priori way to tell which subexpressions of the -macro call are forms to be evaluated. (Evaluation may occur explicitly -in the macro body, or when the resulting expansion is evaluated, or any -time later.) - - Therefore, you must define an Edebug specification for each macro -that Edebug will encounter, to explain the format of calls to that -macro. To do this, add a @code{debug} declaration to the macro -definition. Here is a simple example that shows the specification for -the @code{for} example macro (@pxref{Argument Evaluation}). - -@smallexample -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (declare (debug (symbolp "from" form "to" form "do" &rest form))) - ...) -@end smallexample - - The Edebug specification says which parts of a call to the macro are -forms to be evaluated. For simple macros, the specification -often looks very similar to the formal argument list of the macro -definition, but specifications are much more general than macro -arguments. @xref{Defining Macros}, for more explanation of -the @code{declare} form. - - You can also define an edebug specification for a macro separately -from the macro definition with @code{def-edebug-spec}. Adding -@code{debug} declarations is preferred, and more convenient, for macro -definitions in Lisp, but @code{def-edebug-spec} makes it possible to -define Edebug specifications for special forms implemented in C. - -@deffn Macro def-edebug-spec macro specification -Specify which expressions of a call to macro @var{macro} are forms to be -evaluated. @var{specification} should be the edebug specification. -Neither argument is evaluated. - -The @var{macro} argument can actually be any symbol, not just a macro -name. -@end deffn - -Here is a table of the possibilities for @var{specification} and how each -directs processing of arguments. - -@table @asis -@item @code{t} -All arguments are instrumented for evaluation. - -@item @code{0} -None of the arguments is instrumented. - -@item a symbol -The symbol must have an Edebug specification, which is used instead. -This indirection is repeated until another kind of specification is -found. This allows you to inherit the specification from another macro. - -@item a list -The elements of the list describe the types of the arguments of a -calling form. The possible elements of a specification list are -described in the following sections. -@end table - -If a macro has no Edebug specification, neither through a @code{debug} -declaration nor through a @code{def-edebug-spec} call, the variable -@code{edebug-eval-macro-args} comes into play. - -@defopt edebug-eval-macro-args -This controls the way Edebug treats macro arguments with no explicit -Edebug specification. If it is @code{nil} (the default), none of the -arguments is instrumented for evaluation. Otherwise, all arguments -are instrumented. -@end defopt - -@node Specification List -@subsubsection Specification List - -@cindex Edebug specification list -A @dfn{specification list} is required for an Edebug specification if -some arguments of a macro call are evaluated while others are not. Some -elements in a specification list match one or more arguments, but others -modify the processing of all following elements. The latter, called -@dfn{specification keywords}, are symbols beginning with @samp{&} (such -as @code{&optional}). - -A specification list may contain sublists which match arguments that are -themselves lists, or it may contain vectors used for grouping. Sublists -and groups thus subdivide the specification list into a hierarchy of -levels. Specification keywords apply only to the remainder of the -sublist or group they are contained in. - -When a specification list involves alternatives or repetition, matching -it against an actual macro call may require backtracking. For more -details, @pxref{Backtracking}. - -Edebug specifications provide the power of regular expression matching, -plus some context-free grammar constructs: the matching of sublists with -balanced parentheses, recursive processing of forms, and recursion via -indirect specifications. - -Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced -examples): - -@table @code -@item sexp -A single unevaluated Lisp object, which is not instrumented. -@c an "expression" is not necessarily intended for evaluation. - -@item form -A single evaluated expression, which is instrumented. - -@item place -@c I can't see that this index entry is useful without any explanation. -@c @findex edebug-unwrap -A place to store a value, as in the Common Lisp @code{setf} construct. - -@item body -Short for @code{&rest form}. See @code{&rest} below. - -@item function-form -A function form: either a quoted function symbol, a quoted lambda -expression, or a form (that should evaluate to a function symbol or -lambda expression). This is useful when an argument that's a lambda -expression might be quoted with @code{quote} rather than -@code{function}, since it instruments the body of the lambda expression -either way. - -@item lambda-expr -A lambda expression with no quoting. - -@item &optional -@c @kindex &optional @r{(Edebug)} -All following elements in the specification list are optional; as soon -as one does not match, Edebug stops matching at this level. - -To make just a few elements optional followed by non-optional elements, -use @code{[&optional @var{specs}@dots{}]}. To specify that several -elements must all match or none, use @code{&optional -[@var{specs}@dots{}]}. See the @code{defun} example. - -@item &rest -@c @kindex &rest @r{(Edebug)} -All following elements in the specification list are repeated zero or -more times. In the last repetition, however, it is not a problem if the -expression runs out before matching all of the elements of the -specification list. - -To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. -To specify several elements that must all match on every repetition, use -@code{&rest [@var{specs}@dots{}]}. - -@item &or -@c @kindex &or @r{(Edebug)} -Each of the following elements in the specification list is an -alternative. One of the alternatives must match, or the @code{&or} -specification fails. - -Each list element following @code{&or} is a single alternative. To -group two or more list elements as a single alternative, enclose them in -@code{[@dots{}]}. - -@item ¬ -@c @kindex ¬ @r{(Edebug)} -Each of the following elements is matched as alternatives as if by using -@code{&or}, but if any of them match, the specification fails. If none -of them match, nothing is matched, but the @code{¬} specification -succeeds. - -@item &define -@c @kindex &define @r{(Edebug)} -Indicates that the specification is for a defining form. The defining -form itself is not instrumented (that is, Edebug does not stop before and -after the defining form), but forms inside it typically will be -instrumented. The @code{&define} keyword should be the first element in -a list specification. - -@item nil -This is successful when there are no more arguments to match at the -current argument list level; otherwise it fails. See sublist -specifications and the backquote example. - -@item gate -@cindex preventing backtracking -No argument is matched but backtracking through the gate is disabled -while matching the remainder of the specifications at this level. This -is primarily used to generate more specific syntax error messages. See -@ref{Backtracking}, for more details. Also see the @code{let} example. - -@item @var{other-symbol} -@cindex indirect specifications -Any other symbol in a specification list may be a predicate or an -indirect specification. - -If the symbol has an Edebug specification, this @dfn{indirect -specification} should be either a list specification that is used in -place of the symbol, or a function that is called to process the -arguments. The specification may be defined with @code{def-edebug-spec} -just as for macros. See the @code{defun} example. - -Otherwise, the symbol should be a predicate. The predicate is called -with the argument and the specification fails if the predicate returns -@code{nil}, and the argument is not instrumented. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@item [@var{elements}@dots{}] -@cindex [@dots{}] (Edebug) -A vector of elements groups the elements into a single @dfn{group -specification}. Its meaning has nothing to do with vectors. - -@item "@var{string}" -The argument should be a symbol named @var{string}. This specification -is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name -of @var{symbol} is the @var{string}, but the string form is preferred. - -@item (vector @var{elements}@dots{}) -The argument should be a vector whose elements must match the -@var{elements} in the specification. See the backquote example. - -@item (@var{elements}@dots{}) -Any other list is a @dfn{sublist specification} and the argument must be -a list whose elements match the specification @var{elements}. - -@cindex dotted lists (Edebug) -A sublist specification may be a dotted list and the corresponding list -argument may then be a dotted list. Alternatively, the last @sc{cdr} of a -dotted list specification may be another sublist specification (via a -grouping or an indirect specification, e.g., @code{(spec . [(more -specs@dots{})])}) whose elements match the non-dotted list arguments. -This is useful in recursive specifications such as in the backquote -example. Also see the description of a @code{nil} specification -above for terminating such recursion. - -Note that a sublist specification written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @code{(specs -sublist-elements@dots{})}. -@end table - -@c Need to document extensions with &symbol and :symbol - -Here is a list of additional specifications that may appear only after -@code{&define}. See the @code{defun} example. - -@table @code -@item name -The argument, a symbol, is the name of the defining form. - -A defining form is not required to have a name field; and it may have -multiple name fields. - -@item :name -This construct does not actually match an argument. The element -following @code{:name} should be a symbol; it is used as an additional -name component for the definition. You can use this to add a unique, -static component to the name of the definition. It may be used more -than once. - -@item arg -The argument, a symbol, is the name of an argument of the defining form. -However, lambda-list keywords (symbols starting with @samp{&}) -are not allowed. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@item def-body -The argument is the body of code in a definition. This is like -@code{body}, described above, but a definition body must be instrumented -with a different Edebug call that looks up information associated with -the definition. Use @code{def-body} for the highest level list of forms -within the definition. - -@item def-form -The argument is a single, highest-level form in a definition. This is -like @code{def-body}, except it is used to match a single form rather than -a list of forms. As a special case, @code{def-form} also means that -tracing information is not output when the form is executed. See the -@code{interactive} example. -@end table - -@node Backtracking -@subsubsection Backtracking in Specifications - -@cindex backtracking -@cindex syntax error (Edebug) -If a specification fails to match at some point, this does not -necessarily mean a syntax error will be signaled; instead, -@dfn{backtracking} will take place until all alternatives have been -exhausted. Eventually every element of the argument list must be -matched by some element in the specification, and every required element -in the specification must match some argument. - -When a syntax error is detected, it might not be reported until much -later, after higher-level alternatives have been exhausted, and with the -point positioned further from the real error. But if backtracking is -disabled when an error occurs, it can be reported immediately. Note -that backtracking is also reenabled automatically in several situations; -when a new alternative is established by @code{&optional}, -@code{&rest}, or @code{&or}, or at the start of processing a sublist, -group, or indirect specification. The effect of enabling or disabling -backtracking is limited to the remainder of the level currently being -processed and lower levels. - -Backtracking is disabled while matching any of the -form specifications (that is, @code{form}, @code{body}, @code{def-form}, and -@code{def-body}). These specifications will match any form so any error -must be in the form itself rather than at a higher level. - -Backtracking is also disabled after successfully matching a quoted -symbol or string specification, since this usually indicates a -recognized construct. But if you have a set of alternative constructs that -all begin with the same symbol, you can usually work around this -constraint by factoring the symbol out of the alternatives, e.g., -@code{["foo" &or [first case] [second case] ...]}. - -Most needs are satisfied by these two ways that backtracking is -automatically disabled, but occasionally it is useful to explicitly -disable backtracking by using the @code{gate} specification. This is -useful when you know that no higher alternatives could apply. See the -example of the @code{let} specification. - -@node Specification Examples -@subsubsection Specification Examples - -It may be easier to understand Edebug specifications by studying -the examples provided here. - -A @code{let} special form has a sequence of bindings and a body. Each -of the bindings is either a symbol or a sublist with a symbol and -optional expression. In the specification below, notice the @code{gate} -inside of the sublist to prevent backtracking once a sublist is found. - -@c FIXME? The actual definition in edebug.el does not have a gate. -@example -(def-edebug-spec let - ((&rest - &or symbolp (gate symbolp &optional form)) - body)) -@end example - -Edebug uses the following specifications for @code{defun} and the -associated argument list and @code{interactive} specifications. It is -necessary to handle interactive forms specially since an expression -argument is actually evaluated outside of the function body. (The -specification for @code{defmacro} is very similar to that for -@code{defun}, but allows for the @code{declare} statement.) - -@smallexample -(def-edebug-spec defun - (&define name lambda-list - [&optional stringp] ; @r{Match the doc string, if present.} - [&optional ("interactive" interactive)] - def-body)) - -(def-edebug-spec lambda-list - (([&rest arg] - [&optional ["&optional" arg &rest arg]] - &optional ["&rest" arg] - ))) - -(def-edebug-spec interactive - (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} -@end smallexample - -The specification for backquote below illustrates how to match -dotted lists and use @code{nil} to terminate recursion. It also -illustrates how components of a vector may be matched. (The actual -specification defined by Edebug is a little different, and does not -support dotted lists because doing so causes very deep recursion that -could fail.) - -@smallexample -(def-edebug-spec \` (backquote-form)) ; @r{Alias just for clarity.} - -(def-edebug-spec backquote-form - (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) - (backquote-form . [&or nil backquote-form]) - (vector &rest backquote-form) - sexp)) -@end smallexample - - -@node Edebug Options -@subsection Edebug Options - - These options affect the behavior of Edebug: -@c Previously defopt'd: -@c edebug-sit-for-seconds, edebug-print-length, edebug-print-level -@c edebug-print-circle, edebug-eval-macro-args - -@defopt edebug-setup-hook -Functions to call before Edebug is used. Each time it is set to a new -value, Edebug will call those functions once and then -@code{edebug-setup-hook} is reset to @code{nil}. You could use this to -load up Edebug specifications associated with a package you are using -but only when you also use Edebug. -@xref{Instrumenting}. -@end defopt - -@defopt edebug-all-defs -If this is non-@code{nil}, normal evaluation of defining forms such as -@code{defun} and @code{defmacro} instruments them for Edebug. This -applies to @code{eval-defun}, @code{eval-region}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -Use the command @kbd{M-x edebug-all-forms} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-save-windows -If this is non-@code{nil}, Edebug saves and restores the window -configuration. That takes some time, so if your program does not care -what happens to the window configurations, it is better to set this -variable to @code{nil}. - -If the value is a list, only the listed windows are saved and -restored. - -You can use the @kbd{W} command in Edebug to change this variable -interactively. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-save-displayed-buffer-points -If this is non-@code{nil}, Edebug saves and restores point in all -displayed buffers. - -Saving and restoring point in other buffers is necessary if you are -debugging code that changes the point of a buffer that is displayed in -a non-selected window. If Edebug or the user then selects the window, -point in that buffer will move to the window's value of point. - -Saving and restoring point in all buffers is expensive, since it -requires selecting each window twice, so enable this only if you need -it. @xref{Edebug Display Update}. -@end defopt - -@defopt edebug-initial-mode -If this variable is non-@code{nil}, it specifies the initial execution -mode for Edebug when it is first activated. Possible values are -@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, -@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. - -The default value is @code{step}. -@xref{Edebug Execution Modes}. -@end defopt - -@defopt edebug-trace -If this is non-@code{nil}, trace each function entry and exit. -Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one -function entry or exit per line, indented by the recursion level. - -Also see @code{edebug-tracing}, in @ref{Trace Buffer}. -@end defopt - -@defopt edebug-test-coverage -If non-@code{nil}, Edebug tests coverage of all expressions debugged. -@xref{Coverage Testing}. -@end defopt - -@defopt edebug-continue-kbd-macro -If non-@code{nil}, continue defining or executing any keyboard macro -that is executing outside of Edebug. Use this with caution since it is not -debugged. -@xref{Edebug Execution Modes}. -@end defopt - -@c FIXME edebug-unwrap-results - -@defopt edebug-on-error -Edebug binds @code{debug-on-error} to this value, if -@code{debug-on-error} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - -@defopt edebug-on-quit -Edebug binds @code{debug-on-quit} to this value, if -@code{debug-on-quit} was previously @code{nil}. @xref{Trapping -Errors}. -@end defopt - - If you change the values of @code{edebug-on-error} or -@code{edebug-on-quit} while Edebug is active, their values won't be used -until the @emph{next} time Edebug is invoked via a new command. -@c Not necessarily a deeper command level. -@c A new command is not precisely true, but that is close enough -- dan - -@defopt edebug-global-break-condition -If non-@code{nil}, an expression to test for at every stop point. If -the result is non-@code{nil}, then break. Errors are ignored. -@xref{Global Break Condition}. -@end defopt - -@ignore - arch-tag: 74842db8-019f-4818-b5a4-b2de878e57fd -@end ignore diff --git a/doc/lispref/elisp-covers.texi b/doc/lispref/elisp-covers.texi deleted file mode 100644 index e7bfa856ec5..00000000000 --- a/doc/lispref/elisp-covers.texi +++ /dev/null @@ -1,257 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename covers.info -@settitle GNU Emacs Lisp Reference Manual -@comment %**end of header - -@titlepage -@c ================ Volume 1 ================ -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 ================ -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 16pt ================ - -@tex -\global\baselineskip = 16pt -@end tex - -16 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 18pt ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip, with 15pts between sections - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@tex -\global\baselineskip = 15pt -@end tex - -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 18 pts ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@page -@c ================ Spine 1 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 1 -@sp 3 -@author FSF - -@author - -@page -@c ================ Spine 2 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 2 -@sp 3 -@author FSF - -@end titlepage -@bye - -@ignore - arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98 -@end ignore diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi deleted file mode 100644 index 5eaa5ee23ed..00000000000 --- a/doc/lispref/elisp.texi +++ /dev/null @@ -1,1529 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header - -@c Version of the manual and of Emacs. -@c Please remember to update the edition number in README as well. -@c And also the copies in vol1.texi and vol2.texi. -@set VERSION 3.0 -@set EMACSVER 23.1 -@set DATE July 2009 - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. The manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@c set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. - -@insertcopying -@end ifnottex - -@c Copy any updates to vol1.texi and vol2.texi. -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Writing customization declarations. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 22. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. -@c Copy any updates to vol1.texi and vol2.texi. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will open code. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Writing Customization Definitions - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: How the Emacs Lisp debugger is implemented. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Compilation Errors:: How to find errors that show up in - byte compilation. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Styles:: Specifying rules for performing completion. -* Programmed Completion:: Writing your own completion-function. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: How a mode can provide a menu - of definitions in the buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Basics:: -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-level functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text-only terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for - network connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs' Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: The usual conventions for displaying - nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include hash.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include customize.texi -@include loading.texi -@include compile.texi -@include advice.texi - -@c This includes edebug.texi. -@include debugging.texi -@include streams.texi -@include minibuf.texi -@include commands.texi - -@include keymaps.texi -@include modes.texi -@include help.texi -@include files.texi - -@include backups.texi -@include buffers.texi -@include windows.texi -@include frames.texi - -@include positions.texi -@include markers.texi -@include text.texi -@include nonascii.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi -@include processes.texi - -@include display.texi -@include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include anti.texi -@include doclicense.texi -@include gpl.texi -@include tips.texi -@include internals.texi -@include errors.texi -@include locals.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. - -@ignore - arch-tag: f7e9a219-a0e1-4776-b631-08eaa1d49b34 -@end ignore diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi deleted file mode 100644 index a49525825ff..00000000000 --- a/doc/lispref/errors.texi +++ /dev/null @@ -1,209 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/errors -@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top -@appendix Standard Errors -@cindex standard errors - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -@code{error-message} property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an @code{error-conditions} property that is a -list of symbols. Normally this list includes the error symbol itself -and the symbol @code{error}. Occasionally it includes additional -symbols, which are intermediate classifications, narrower than -@code{error} but broader than a single error symbol. For example, all -the errors in accessing files have the condition @code{file-error}. If -we do not say here that a certain error symbol has additional error -conditions, that means it has none. - - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. - - @xref{Errors}, for an explanation of how errors are generated and -handled. - -@table @code -@item @var{symbol} -@var{string}; @var{reference}. - -@item error -@code{"error"}@* -@xref{Errors}. - -@item quit -@code{"Quit"}@* -@xref{Quitting}. - -@item args-out-of-range -@code{"Args out of range"}@* -This happens when trying to access an element beyond the range of a -sequence or buffer.@* -@xref{Sequences Arrays Vectors}, @xref{Text}. - -@item arith-error -@code{"Arithmetic error"}@* -@xref{Arithmetic Operations}. - -@item beginning-of-buffer -@code{"Beginning of buffer"}@* -@xref{Character Motion}. - -@item buffer-read-only -@code{"Buffer is read-only"}@* -@xref{Read Only Buffers}. - -@item coding-system-error -@code{"Invalid coding system"}@* -@xref{Lisp and Coding Systems}. - -@item cyclic-function-indirection -@code{"Symbol's chain of function indirections\@* contains a loop"}@* -@xref{Function Indirection}. - -@item cyclic-variable-indirection -@code{"Symbol's chain of variable indirections\@* contains a loop"}@* -@xref{Variable Aliases}. - -@item end-of-buffer -@code{"End of buffer"}@* -@xref{Character Motion}. - -@item end-of-file -@code{"End of file during parsing"}@* -Note that this is not a subcategory of @code{file-error}, -because it pertains to the Lisp reader, not to file I/O.@* -@xref{Input Functions}. - -@item file-already-exists -This is a subcategory of @code{file-error}.@* -@xref{Writing to Files}. - -@item file-date-error -This is a subcategory of @code{file-error}. It occurs when -@code{copy-file} tries and fails to set the last-modification time of -the output file.@* -@xref{Changing Files}. - -@item file-error -We do not list the error-strings of this error and its subcategories, -because the error message is normally constructed from the data items -alone when the error condition @code{file-error} is present. Thus, -the error-strings are not very relevant. However, these error symbols -do have @code{error-message} properties, and if no data is provided, -the @code{error-message} property @emph{is} used.@* -@xref{Files}. - -@item file-locked -This is a subcategory of @code{file-error}.@* -@xref{File Locks}. - -@item file-supersession -This is a subcategory of @code{file-error}.@* -@xref{Modification Time}. - -@item ftp-error -This is a subcategory of @code{file-error}, which results from problems -in accessing a remote file using ftp.@* -@xref{Remote Files,,, emacs, The GNU Emacs Manual}. - -@item invalid-function -@code{"Invalid function"}@* -@xref{Function Indirection}. - -@item invalid-read-syntax -@code{"Invalid read syntax"}@* -@xref{Printed Representation}. - -@item invalid-regexp -@code{"Invalid regexp"}@* -@xref{Regular Expressions}. - -@item mark-inactive -@code{"The mark is not active now"}@* -@xref{The Mark}. - -@item no-catch -@code{"No catch for tag"}@* -@xref{Catch and Throw}. - -@item scan-error -@code{"Scan error"}@* -This happens when certain syntax-parsing functions -find invalid syntax or mismatched parentheses.@* -@xref{List Motion}, and @ref{Parsing Expressions}. - -@item search-failed -@code{"Search failed"}@* -@xref{Searching and Matching}. - -@item setting-constant -@code{"Attempt to set a constant symbol"}@* -The values of the symbols @code{nil} and @code{t}, -and any symbols that start with @samp{:}, -may not be changed.@* -@xref{Constant Variables, , Variables that Never Change}. - -@item text-read-only -@code{"Text is read-only"}@* -This is a subcategory of @code{buffer-read-only}.@* -@xref{Special Properties}. - -@item undefined-color -@code{"Undefined color"}@* -@xref{Color Names}. - -@item void-function -@code{"Symbol's function definition is void"}@* -@xref{Function Cells}. - -@item void-variable -@code{"Symbol's value as variable is void"}@* -@xref{Accessing Variables}. - -@item wrong-number-of-arguments -@code{"Wrong number of arguments"}@* -@xref{Classifying Lists}. - -@item wrong-type-argument -@code{"Wrong type argument"}@* -@xref{Type Predicates}. -@end table - - These kinds of error, which are classified as special cases of -@code{arith-error}, can occur on certain systems for invalid use of -mathematical functions. - -@table @code -@item domain-error -@code{"Arithmetic domain error"}@* -@xref{Math Functions}. - -@item overflow-error -@code{"Arithmetic overflow error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. - -@item range-error -@code{"Arithmetic range error"}@* -@xref{Math Functions}. - -@item singularity-error -@code{"Arithmetic singularity error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. - -@item underflow-error -@code{"Arithmetic underflow error"}@* -This is a subcategory of @code{domain-error}.@* -@xref{Math Functions}. -@end table - -@ignore - arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19 -@end ignore diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi deleted file mode 100644 index 7e470055b77..00000000000 --- a/doc/lispref/eval.texi +++ /dev/null @@ -1,754 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/eval -@node Evaluation, Control Structures, Symbols, Top -@chapter Evaluation -@cindex evaluation -@cindex interpreter -@cindex interpreter -@cindex value of expression - - The @dfn{evaluation} of expressions in Emacs Lisp is performed by the -@dfn{Lisp interpreter}---a program that receives a Lisp object as input -and computes its @dfn{value as an expression}. How it does this depends -on the data type of the object, according to rules described in this -chapter. The interpreter runs automatically to evaluate portions of -your program, but can also be called explicitly via the Lisp primitive -function @code{eval}. - -@ifnottex -@menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Eval:: How to invoke the Lisp interpreter explicitly. -@end menu - -@node Intro Eval -@section Introduction to Evaluation - - The Lisp interpreter, or evaluator, is the part of Emacs that -computes the value of an expression that is given to it. When a -function written in Lisp is called, the evaluator computes the value -of the function by evaluating the expressions in the function body. -Thus, running any Lisp program really means running the Lisp -interpreter. -@end ifnottex - -@cindex form -@cindex expression - A Lisp object that is intended for evaluation is called an -@dfn{expression} or a @dfn{form}. The fact that forms are data -objects and not merely text is one of the fundamental differences -between Lisp-like languages and typical programming languages. Any -object can be evaluated, but in practice only numbers, symbols, lists -and strings are evaluated very often. - - In subsequent sections, we will describe the details of what -evaluation means for each kind of form. - - It is very common to read a Lisp form and then evaluate the form, -but reading and evaluation are separate activities, and either can be -performed alone. Reading per se does not evaluate anything; it -converts the printed representation of a Lisp object to the object -itself. It is up to the caller of @code{read} to specify whether this -object is a form to be evaluated, or serves some entirely different -purpose. @xref{Input Functions}. - -@cindex recursive evaluation - Evaluation is a recursive process, and evaluating a form often -involves evaluating parts within that form. For instance, when you -evaluate a @dfn{function call} form such as @code{(car x)}, Emacs -first evaluates the argument (the subform @code{x}). After evaluating -the argument, Emacs @dfn{executes} the function (@code{car}), and if -the function is written in Lisp, execution works by evaluating the -@dfn{body} of the function. (In this example, however, @code{car} is -not a Lisp function; it is a primitive function implemented in C.) -@xref{Functions}, for more information about functions and function -calls. - -@cindex environment - Evaluation takes place in a context called the @dfn{environment}, -which consists of the current values and bindings of all Lisp -variables (@pxref{Variables}).@footnote{This definition of -``environment'' is specifically not intended to include all the data -that can affect the result of a program.} Whenever a form refers to a -variable without creating a new binding for it, the variable evaluates -to the value given by the current environment. Evaluating a form may -create a new environment for recursive evaluation, by binding -variables (@pxref{Local Variables}). Such environments are temporary, -and vanish when the evaluation of the form is complete. - -@cindex side effect - Evaluating a form may also make changes that persist; these changes -are called @dfn{side effects}. An example of a form that produces a -side effect is @code{(setq foo 1)}. - - Do not confuse evaluation with command key interpretation. The -editor command loop translates keyboard input into a command (an -interactively callable function) using the active keymaps, and then -uses @code{call-interactively} to execute that command. Executing the -command usually involves evaluation, if the command is written in -Lisp; however, this step is not considered a part of command key -interpretation. @xref{Command Loop}. - -@node Forms -@section Kinds of Forms - - A Lisp object that is intended to be evaluated is called a @dfn{form}. -How Emacs evaluates a form depends on its data type. Emacs has three -different kinds of form that are evaluated differently: symbols, lists, -and ``all other types.'' This section describes all three kinds, one by -one, starting with the ``all other types'' which are self-evaluating -forms. - -@menu -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. -@end menu - -@node Self-Evaluating Forms -@subsection Self-Evaluating Forms -@cindex vector evaluation -@cindex literal evaluation -@cindex self-evaluating form - - A @dfn{self-evaluating form} is any form that is not a list or -symbol. Self-evaluating forms evaluate to themselves: the result of -evaluation is the same object that was evaluated. Thus, the number 25 -evaluates to 25, and the string @code{"foo"} evaluates to the string -@code{"foo"}. Likewise, evaluating a vector does not cause evaluation -of the elements of the vector---it returns the same vector with its -contents unchanged. - -@example -@group -'123 ; @r{A number, shown without evaluation.} - @result{} 123 -@end group -@group -123 ; @r{Evaluated as usual---result is the same.} - @result{} 123 -@end group -@group -(eval '123) ; @r{Evaluated ``by hand''---result is the same.} - @result{} 123 -@end group -@group -(eval (eval '123)) ; @r{Evaluating twice changes nothing.} - @result{} 123 -@end group -@end example - - It is common to write numbers, characters, strings, and even vectors -in Lisp code, taking advantage of the fact that they self-evaluate. -However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually. It is possible -to construct Lisp expressions containing these types by means of a Lisp -program. Here is an example: - -@example -@group -;; @r{Build an expression containing a buffer object.} -(setq print-exp (list 'print (current-buffer))) - @result{} (print #) -@end group -@group -;; @r{Evaluate it.} -(eval print-exp) - @print{} # - @result{} # -@end group -@end example - -@node Symbol Forms -@subsection Symbol Forms -@cindex symbol evaluation - - When a symbol is evaluated, it is treated as a variable. The result -is the variable's value, if it has one. If it has none (if its value -cell is void), an error is signaled. For more information on the use of -variables, see @ref{Variables}. - - In the following example, we set the value of a symbol with -@code{setq}. Then we evaluate the symbol, and get back the value that -@code{setq} stored. - -@example -@group -(setq a 123) - @result{} 123 -@end group -@group -(eval 'a) - @result{} 123 -@end group -@group -a - @result{} 123 -@end group -@end example - - The symbols @code{nil} and @code{t} are treated specially, so that the -value of @code{nil} is always @code{nil}, and the value of @code{t} is -always @code{t}; you cannot set or bind them to any other values. Thus, -these two symbols act like self-evaluating forms, even though -@code{eval} treats them like any other symbol. A symbol whose name -starts with @samp{:} also self-evaluates in the same way; likewise, -its value ordinarily cannot be changed. @xref{Constant Variables}. - -@node Classifying Lists -@subsection Classification of List Forms -@cindex list form evaluation - - A form that is a nonempty list is either a function call, a macro -call, or a special form, according to its first element. These three -kinds of forms are evaluated in different ways, described below. The -remaining list elements constitute the @dfn{arguments} for the function, -macro, or special form. - - The first step in evaluating a nonempty list is to examine its first -element. This element alone determines what kind of form the list is -and how the rest of the list is to be processed. The first element is -@emph{not} evaluated, as it would be in some Lisp dialects such as -Scheme. - -@node Function Indirection -@subsection Symbol Function Indirection -@cindex symbol function indirection -@cindex indirection for functions -@cindex void function - - If the first element of the list is a symbol then evaluation -examines the symbol's function cell, and uses its contents instead of -the original symbol. If the contents are another symbol, this -process, called @dfn{symbol function indirection}, is repeated until -it obtains a non-symbol. @xref{Function Names}, for more information -about symbol function indirection. - - One possible consequence of this process is an infinite loop, in the -event that a symbol's function cell refers to the same symbol. Or a -symbol may have a void function cell, in which case the subroutine -@code{symbol-function} signals a @code{void-function} error. But if -neither of these things happens, we eventually obtain a non-symbol, -which ought to be a function or other suitable object. - -@kindex invalid-function - More precisely, we should now have a Lisp function (a lambda -expression), a byte-code function, a primitive function, a Lisp macro, -a special form, or an autoload object. Each of these types is a case -described in one of the following sections. If the object is not one -of these types, Emacs signals an @code{invalid-function} error. - - The following example illustrates the symbol indirection process. We -use @code{fset} to set the function cell of a symbol and -@code{symbol-function} to get the function cell contents -(@pxref{Function Cells}). Specifically, we store the symbol @code{car} -into the function cell of @code{first}, and the symbol @code{first} into -the function cell of @code{erste}. - -@smallexample -@group -;; @r{Build this function cell linkage:} -;; ------------- ----- ------- ------- -;; | # | <-- | car | <-- | first | <-- | erste | -;; ------------- ----- ------- ------- -@end group -@end smallexample - -@smallexample -@group -(symbol-function 'car) - @result{} # -@end group -@group -(fset 'first 'car) - @result{} car -@end group -@group -(fset 'erste 'first) - @result{} first -@end group -@group -(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} - @result{} 1 -@end group -@end smallexample - - By contrast, the following example calls a function without any symbol -function indirection, because the first element is an anonymous Lisp -function, not a symbol. - -@smallexample -@group -((lambda (arg) (erste arg)) - '(1 2 3)) - @result{} 1 -@end group -@end smallexample - -@noindent -Executing the function itself evaluates its body; this does involve -symbol function indirection when calling @code{erste}. - - The built-in function @code{indirect-function} provides an easy way to -perform symbol function indirection explicitly. - -@c Emacs 19 feature -@defun indirect-function function &optional noerror -@anchor{Definition of indirect-function} -This function returns the meaning of @var{function} as a function. If -@var{function} is a symbol, then it finds @var{function}'s function -definition and starts over with that value. If @var{function} is not a -symbol, then it returns @var{function} itself. - -This function signals a @code{void-function} error if the final symbol -is unbound and optional argument @var{noerror} is @code{nil} or -omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns -@code{nil} if the final symbol is unbound. - -It signals a @code{cyclic-function-indirection} error if there is a -loop in the chain of symbols. - -Here is how you could define @code{indirect-function} in Lisp: - -@smallexample -(defun indirect-function (function) - (if (symbolp function) - (indirect-function (symbol-function function)) - function)) -@end smallexample -@end defun - -@node Function Forms -@subsection Evaluation of Function Forms -@cindex function form evaluation -@cindex function call - - If the first element of a list being evaluated is a Lisp function -object, byte-code object or primitive function object, then that list is -a @dfn{function call}. For example, here is a call to the function -@code{+}: - -@example -(+ 1 x) -@end example - - The first step in evaluating a function call is to evaluate the -remaining elements of the list from left to right. The results are the -actual argument values, one value for each list element. The next step -is to call the function with this list of arguments, effectively using -the function @code{apply} (@pxref{Calling Functions}). If the function -is written in Lisp, the arguments are used to bind the argument -variables of the function (@pxref{Lambda Expressions}); then the forms -in the function body are evaluated in order, and the value of the last -body form becomes the value of the function call. - -@node Macro Forms -@subsection Lisp Macro Evaluation -@cindex macro call evaluation - - If the first element of a list being evaluated is a macro object, then -the list is a @dfn{macro call}. When a macro call is evaluated, the -elements of the rest of the list are @emph{not} initially evaluated. -Instead, these elements themselves are used as the arguments of the -macro. The macro definition computes a replacement form, called the -@dfn{expansion} of the macro, to be evaluated in place of the original -form. The expansion may be any sort of form: a self-evaluating -constant, a symbol, or a list. If the expansion is itself a macro call, -this process of expansion repeats until some other sort of form results. - - Ordinary evaluation of a macro call finishes by evaluating the -expansion. However, the macro expansion is not necessarily evaluated -right away, or at all, because other programs also expand macro calls, -and they may or may not evaluate the expansions. - - Normally, the argument expressions are not evaluated as part of -computing the macro expansion, but instead appear as part of the -expansion, so they are computed when the expansion is evaluated. - - For example, given a macro defined as follows: - -@example -@group -(defmacro cadr (x) - (list 'car (list 'cdr x))) -@end group -@end example - -@noindent -an expression such as @code{(cadr (assq 'handler list))} is a macro -call, and its expansion is: - -@example -(car (cdr (assq 'handler list))) -@end example - -@noindent -Note that the argument @code{(assq 'handler list)} appears in the -expansion. - -@xref{Macros}, for a complete description of Emacs Lisp macros. - -@node Special Forms -@subsection Special Forms -@cindex special forms -@cindex evaluation of special forms - - A @dfn{special form} is a primitive function specially marked so that -its arguments are not all evaluated. Most special forms define control -structures or perform variable bindings---things which functions cannot -do. - - Each special form has its own rules for which arguments are evaluated -and which are used without evaluation. Whether a particular argument is -evaluated may depend on the results of evaluating other arguments. - - Here is a list, in alphabetical order, of all of the special forms in -Emacs Lisp with a reference to where each is described. - -@table @code -@item and -@pxref{Combining Conditions} - -@item catch -@pxref{Catch and Throw} - -@item cond -@pxref{Conditionals} - -@item condition-case -@pxref{Handling Errors} - -@item defconst -@pxref{Defining Variables} - -@item defmacro -@pxref{Defining Macros} - -@item defun -@pxref{Defining Functions} - -@item defvar -@pxref{Defining Variables} - -@item function -@pxref{Anonymous Functions} - -@item if -@pxref{Conditionals} - -@item interactive -@pxref{Interactive Call} - -@item let -@itemx let* -@pxref{Local Variables} - -@item or -@pxref{Combining Conditions} - -@item prog1 -@itemx prog2 -@itemx progn -@pxref{Sequencing} - -@item quote -@pxref{Quoting} - -@item save-current-buffer -@pxref{Current Buffer} - -@item save-excursion -@pxref{Excursions} - -@item save-restriction -@pxref{Narrowing} - -@item save-window-excursion -@pxref{Window Configurations} - -@item setq -@pxref{Setting Variables} - -@item setq-default -@pxref{Creating Buffer-Local} - -@item track-mouse -@pxref{Mouse Tracking} - -@item unwind-protect -@pxref{Nonlocal Exits} - -@item while -@pxref{Iteration} - -@item with-output-to-temp-buffer -@pxref{Temporary Displays} -@end table - -@cindex CL note---special forms compared -@quotation -@b{Common Lisp note:} Here are some comparisons of special forms in -GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and -@code{catch} are special forms in both Emacs Lisp and Common Lisp. -@code{defun} is a special form in Emacs Lisp, but a macro in Common -Lisp. @code{save-excursion} is a special form in Emacs Lisp, but -doesn't exist in Common Lisp. @code{throw} is a special form in -Common Lisp (because it must be able to throw multiple values), but it -is a function in Emacs Lisp (which doesn't have multiple -values).@refill -@end quotation - -@node Autoloading -@subsection Autoloading - - The @dfn{autoload} feature allows you to call a function or macro -whose function definition has not yet been loaded into Emacs. It -specifies which file contains the definition. When an autoload object -appears as a symbol's function definition, calling that symbol as a -function automatically loads the specified file; then it calls the real -definition loaded from that file. @xref{Autoload}. - -@node Quoting -@section Quoting - - The special form @code{quote} returns its single argument, as written, -without evaluating it. This provides a way to include constant symbols -and lists, which are not self-evaluating objects, in a program. (It is -not necessary to quote self-evaluating objects such as numbers, strings, -and vectors.) - -@defspec quote object -This special form returns @var{object}, without evaluating it. -@end defspec - -@cindex @samp{'} for quoting -@cindex quoting using apostrophe -@cindex apostrophe for quoting -Because @code{quote} is used so often in programs, Lisp provides a -convenient read syntax for it. An apostrophe character (@samp{'}) -followed by a Lisp object (in read syntax) expands to a list whose first -element is @code{quote}, and whose second element is the object. Thus, -the read syntax @code{'x} is an abbreviation for @code{(quote x)}. - -Here are some examples of expressions that use @code{quote}: - -@example -@group -(quote (+ 1 2)) - @result{} (+ 1 2) -@end group -@group -(quote foo) - @result{} foo -@end group -@group -'foo - @result{} foo -@end group -@group -''foo - @result{} (quote foo) -@end group -@group -'(quote foo) - @result{} (quote foo) -@end group -@group -['foo] - @result{} [(quote foo)] -@end group -@end example - - Other quoting constructs include @code{function} (@pxref{Anonymous -Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote -only part of a list, while computing and substituting other parts. - -@node Eval -@section Eval - - Most often, forms are evaluated automatically, by virtue of their -occurrence in a program being run. On rare occasions, you may need to -write code that evaluates a form that is computed at run time, such as -after reading a form from text being edited or getting one from a -property list. On these occasions, use the @code{eval} function. - - The functions and variables described in this section evaluate forms, -specify limits to the evaluation process, or record recently returned -values. Loading a file also does evaluation (@pxref{Loading}). - - It is generally cleaner and more flexible to store a function in a -data structure, and call it with @code{funcall} or @code{apply}, than -to store an expression in the data structure and evaluate it. Using -functions provides the ability to pass information to them as -arguments. - -@defun eval form -This is the basic function evaluating an expression. It evaluates -@var{form} in the current environment and returns the result. How the -evaluation proceeds depends on the type of the object (@pxref{Forms}). - -Since @code{eval} is a function, the argument expression that appears -in a call to @code{eval} is evaluated twice: once as preparation before -@code{eval} is called, and again by the @code{eval} function itself. -Here is an example: - -@example -@group -(setq foo 'bar) - @result{} bar -@end group -@group -(setq bar 'baz) - @result{} baz -;; @r{Here @code{eval} receives argument @code{foo}} -(eval 'foo) - @result{} bar -;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}} -(eval foo) - @result{} baz -@end group -@end example - -The number of currently active calls to @code{eval} is limited to -@code{max-lisp-eval-depth} (see below). -@end defun - -@deffn Command eval-region start end &optional stream read-function -@anchor{Definition of eval-region} -This function evaluates the forms in the current buffer in the region -defined by the positions @var{start} and @var{end}. It reads forms from -the region and calls @code{eval} on them until the end of the region is -reached, or until an error is signaled and not handled. - -By default, @code{eval-region} does not produce any output. However, -if @var{stream} is non-@code{nil}, any output produced by output -functions (@pxref{Output Functions}), as well as the values that -result from evaluating the expressions in the region are printed using -@var{stream}. @xref{Output Streams}. - -If @var{read-function} is non-@code{nil}, it should be a function, -which is used instead of @code{read} to read expressions one by one. -This function is called with one argument, the stream for reading -input. You can also use the variable @code{load-read-function} -(@pxref{Definition of load-read-function,, How Programs Do Loading}) -to specify this function, but it is more robust to use the -@var{read-function} argument. - -@code{eval-region} does not move point. It always returns @code{nil}. -@end deffn - -@cindex evaluation of buffer contents -@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print -This is similar to @code{eval-region}, but the arguments provide -different optional features. @code{eval-buffer} operates on the -entire accessible portion of buffer @var{buffer-or-name}. -@var{buffer-or-name} can be a buffer, a buffer name (a string), or -@code{nil} (or omitted), which means to use the current buffer. -@var{stream} is used as in @code{eval-region}, unless @var{stream} is -@code{nil} and @var{print} non-@code{nil}. In that case, values that -result from evaluating the expressions are still discarded, but the -output of the output functions is printed in the echo area. -@var{filename} is the file name to use for @code{load-history} -(@pxref{Unloading}), and defaults to @code{buffer-file-name} -(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil}, -@code{read} converts strings to unibyte whenever possible. - -@findex eval-current-buffer -@code{eval-current-buffer} is an alias for this command. -@end deffn - -@defopt max-lisp-eval-depth -@anchor{Definition of max-lisp-eval-depth} -This variable defines the maximum depth allowed in calls to @code{eval}, -@code{apply}, and @code{funcall} before an error is signaled (with error -message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). - -This limit, with the associated error when it is exceeded, is one way -Emacs Lisp avoids infinite recursion on an ill-defined function. If -you increase the value of @code{max-lisp-eval-depth} too much, such -code can cause stack overflow instead. -@cindex Lisp nesting error - -The depth limit counts internal uses of @code{eval}, @code{apply}, and -@code{funcall}, such as for calling the functions mentioned in Lisp -expressions, and recursive evaluation of function call arguments and -function body forms, as well as explicit calls in Lisp code. - -The default value of this variable is 400. If you set it to a value -less than 100, Lisp will reset it to 100 if the given value is -reached. Entry to the Lisp debugger increases the value, if there is -little room left, to make sure the debugger itself has room to -execute. - -@code{max-specpdl-size} provides another limit on nesting. -@xref{Definition of max-specpdl-size,, Local Variables}. -@end defopt - -@defvar values -The value of this variable is a list of the values returned by all the -expressions that were read, evaluated, and printed from buffers -(including the minibuffer) by the standard Emacs commands which do -this. (Note that this does @emph{not} include evaluation in -@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in -@code{lisp-interaction-mode}.) The elements are ordered most recent -first. - -@example -@group -(setq x 1) - @result{} 1 -@end group -@group -(list 'A (1+ 2) auto-save-default) - @result{} (A 3 t) -@end group -@group -values - @result{} ((A 3 t) 1 @dots{}) -@end group -@end example - -This variable is useful for referring back to values of forms recently -evaluated. It is generally a bad idea to print the value of -@code{values} itself, since this may be very long. Instead, examine -particular elements, like this: - -@example -@group -;; @r{Refer to the most recent evaluation result.} -(nth 0 values) - @result{} (A 3 t) -@end group -@group -;; @r{That put a new element on,} -;; @r{so all elements move back one.} -(nth 1 values) - @result{} (A 3 t) -@end group -@group -;; @r{This gets the element that was next-to-most-recent} -;; @r{before this example.} -(nth 3 values) - @result{} 1 -@end group -@end example -@end defvar - -@ignore - arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57 -@end ignore diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi deleted file mode 100644 index ff225e0230b..00000000000 --- a/doc/lispref/files.texi +++ /dev/null @@ -1,3142 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/files -@node Files, Backups and Auto-Saving, Documentation, Top -@comment node-name, next, previous, up -@chapter Files - - In Emacs, you can find, create, view, save, and otherwise work with -files and file directories. This chapter describes most of the -file-related functions of Emacs Lisp, but a few others are described in -@ref{Buffers}, and those related to backups and auto-saving are -described in @ref{Backups and Auto-Saving}. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments by calling @code{expand-file-name}, so that -@file{~} is handled correctly, as are relative file names (including -@samp{../}). These functions don't recognize environment variable -substitutions such as @samp{$HOME}. @xref{File Name Expansion}. - - When file I/O functions signal Lisp errors, they usually use the -condition @code{file-error} (@pxref{Handling Errors}). The error -message is in most cases obtained from the operating system, according -to locale @code{system-message-locale}, and decoded using coding system -@code{locale-coding-system} (@pxref{Locales}). - -@menu -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Format Conversion:: Conversion to and from various file formats. -@end menu - -@node Visiting Files -@section Visiting Files -@cindex finding files -@cindex visiting files - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -@dfn{save} the buffer, which means copying the altered buffer contents -back into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -``I am editing a file,'' rather than, ``I am editing a buffer that I -will soon save as a file of the same name.'' Humans do not usually need -to make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -@menu -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. -@end menu - -@node Visiting Functions -@subsection Functions for Visiting Files - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for -functions and variables that access the visited file name of a buffer or -that find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use @code{insert-file-contents} in a -temporary buffer. Visiting the file is not necessary and takes longer. -@xref{Reading from Files}. - -@deffn Command find-file filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, -using an existing buffer if there is one, and otherwise creating a -new buffer and reading the file into it. It also returns that buffer. - -Aside from some technical details, the body of the @code{find-file} -function is basically equivalent to: - -@smallexample -(switch-to-buffer (find-file-noselect filename nil nil wildcards)) -@end smallexample - -@noindent -(See @code{switch-to-buffer} in @ref{Displaying Buffers}.) - -If @var{wildcards} is non-@code{nil}, which is always true in an -interactive call, then @code{find-file} expands wildcard characters in -@var{filename} and visits all the matching files. - -When @code{find-file} is called interactively, it prompts for -@var{filename} in the minibuffer. -@end deffn - -@defun find-file-noselect filename &optional nowarn rawfile wildcards -This function is the guts of all the file-visiting functions. It -returns a buffer visiting the file @var{filename}. You may make the -buffer current or display it in a window if you wish, but this -function does not do so. - -The function returns an existing buffer if there is one; otherwise it -creates a new buffer and reads the file into it. When -@code{find-file-noselect} uses an existing buffer, it first verifies -that the file has not changed since it was last visited or saved in -that buffer. If the file has changed, this function asks the user -whether to reread the changed file. If the user says @samp{yes}, any -edits previously made in the buffer are lost. - -Reading the file involves decoding the file's contents (@pxref{Coding -Systems}), including end-of-line conversion, and format conversion -(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, -then @code{find-file-noselect} expands wildcard characters in -@var{filename} and visits all the matching files. - -This function displays warning or advisory messages in various peculiar -cases, unless the optional argument @var{nowarn} is non-@code{nil}. For -example, if it needs to create a buffer, and there is no file named -@var{filename}, it displays the message @samp{(New file)} in the echo -area, and leaves the buffer empty. - -The @code{find-file-noselect} function normally calls -@code{after-find-file} after reading the file (@pxref{Subroutines of -Visiting}). That function sets the buffer major mode, parses local -variables, warns the user if there exists an auto-save file more recent -than the file just visited, and finishes by running the functions in -@code{find-file-hook}. - -If the optional argument @var{rawfile} is non-@code{nil}, then -@code{after-find-file} is not called, and the -@code{find-file-not-found-functions} are not run in case of failure. -What's more, a non-@code{nil} @var{rawfile} value suppresses coding -system conversion and format conversion. - -The @code{find-file-noselect} function usually returns the buffer that -is visiting the file @var{filename}. But, if wildcards are actually -used and expanded, it returns a list of buffers that are visiting the -various files. - -@example -@group -(find-file-noselect "/etc/fstab") - @result{} # -@end group -@end example -@end defun - -@deffn Command find-file-other-window filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, but -does so in a window other than the selected window. It may use another -existing window or split a window; see @ref{Displaying Buffers}. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command find-file-read-only filename &optional wildcards -This command selects a buffer visiting the file @var{filename}, like -@code{find-file}, but it marks the buffer as read-only. @xref{Read Only -Buffers}, for related functions and variables. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command view-file filename -This command visits @var{filename} using View mode, returning to the -previous buffer when you exit View mode. View mode is a minor mode that -provides commands to skim rapidly through the file, but does not let you -modify the text. Entering View mode runs the normal hook -@code{view-mode-hook}. @xref{Hooks}. - -When @code{view-file} is called interactively, it prompts for -@var{filename}. -@end deffn - -@defopt find-file-wildcards -If this variable is non-@code{nil}, then the various @code{find-file} -commands check for wildcard characters and visit all the files that -match them (when invoked interactively or when their @var{wildcards} -argument is non-@code{nil}). If this option is @code{nil}, then -the @code{find-file} commands ignore their @var{wildcards} argument -and never treat wildcard characters specially. -@end defopt - -@defopt find-file-hook -The value of this variable is a list of functions to be called after a -file is visited. The file's local-variables specification (if any) will -have been processed before the hooks are run. The buffer visiting the -file is current when the hook functions are run. - -This variable is a normal hook. @xref{Hooks}. -@end defopt - -@defvar find-file-not-found-functions -The value of this variable is a list of functions to be called when -@code{find-file} or @code{find-file-noselect} is passed a nonexistent -file name. @code{find-file-noselect} calls these functions as soon as -it detects a nonexistent file. It calls them in the order of the list, -until one of them returns non-@code{nil}. @code{buffer-file-name} is -already set up. - -This is not a normal hook because the values of the functions are -used, and in many cases only some of the functions are called. -@end defvar - -@node Subroutines of Visiting -@comment node-name, next, previous, up -@subsection Subroutines of Visiting - - The @code{find-file-noselect} function uses two important subroutines -which are sometimes useful in user Lisp code: @code{create-file-buffer} -and @code{after-find-file}. This section explains how to use them. - -@defun create-file-buffer filename -This function creates a suitably named buffer for visiting -@var{filename}, and returns it. It uses @var{filename} (sans directory) -as the name if that name is free; otherwise, it appends a string such as -@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. - -@strong{Please note:} @code{create-file-buffer} does @emph{not} -associate the new buffer with a file and does not select the buffer. -It also does not use the default major mode. - -@example -@group -(create-file-buffer "foo") - @result{} # -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@group -(create-file-buffer "foo") - @result{} #> -@end group -@end example - -This function is used by @code{find-file-noselect}. -It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). -@end defun - -@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes -This function sets the buffer major mode, and parses local variables -(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} -and by the default revert function (@pxref{Reverting}). - -@cindex new file message -@cindex file open error -If reading the file got an error because the file does not exist, but -its directory does exist, the caller should pass a non-@code{nil} value -for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New file)}. For more serious errors, the caller should usually not -call @code{after-find-file}. - -If @var{warn} is non-@code{nil}, then this function issues a warning -if an auto-save file exists and is more recent than the visited file. - -If @var{noauto} is non-@code{nil}, that says not to enable or disable -Auto-Save mode. The mode remains enabled if it was enabled before. - -If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that -means this call was from @code{revert-buffer}. This has no direct -effect, but some mode functions and hook functions check the value -of this variable. - -If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's -major mode, don't process local variables specifications in the file, -and don't run @code{find-file-hook}. This feature is used by -@code{revert-buffer} in some cases. - -The last thing @code{after-find-file} does is call all the functions -in the list @code{find-file-hook}. -@end defun - -@node Saving Buffers -@section Saving Buffers -@cindex saving buffers - - When you edit a file in Emacs, you are actually working on a buffer -that is visiting that file---that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you @dfn{save} the buffer, which -means copying the contents of the buffer into the file. - -@deffn Command save-buffer &optional backup-option -This function saves the contents of the current buffer in its visited -file if the buffer has been modified since it was last visited or saved. -Otherwise it does nothing. - -@code{save-buffer} is responsible for making backup files. Normally, -@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup -file only if this is the first save since visiting the file. Other -values for @var{backup-option} request the making of backup files in -other circumstances: - -@itemize @bullet -@item -With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the -@code{save-buffer} function marks this version of the file to be -backed up when the buffer is next saved. - -@item -With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the -@code{save-buffer} function unconditionally backs up the previous -version of the file before saving it. - -@item -With an argument of 0, unconditionally do @emph{not} make any backup file. -@end itemize -@end deffn - -@deffn Command save-some-buffers &optional save-silently-p pred -@anchor{Definition of save-some-buffers} -This command saves some modified file-visiting buffers. Normally it -asks the user about each buffer. But if @var{save-silently-p} is -non-@code{nil}, it saves all the file-visiting buffers without querying -the user. - -The optional @var{pred} argument controls which buffers to ask about -(or to save silently if @var{save-silently-p} is non-@code{nil}). -If it is @code{nil}, that means to ask only about file-visiting buffers. -If it is @code{t}, that means also offer to save certain other non-file -buffers---those that have a non-@code{nil} buffer-local value of -@code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says -@samp{yes} to saving a non-file buffer is asked to specify the file -name to use. The @code{save-buffers-kill-emacs} function passes the -value @code{t} for @var{pred}. - -If @var{pred} is neither @code{t} nor @code{nil}, then it should be -a function of no arguments. It will be called in each buffer to decide -whether to offer to save that buffer. If it returns a non-@code{nil} -value in a certain buffer, that means do offer to save that buffer. -@end deffn - -@deffn Command write-file filename &optional confirm -@anchor{Definition of write-file} -This function writes the current buffer into file @var{filename}, makes -the buffer visit that file, and marks it not modified. Then it renames -the buffer based on @var{filename}, appending a string like @samp{<2>} -if necessary to make a unique buffer name. It does most of this work by -calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and -@code{save-buffer}. - -If @var{confirm} is non-@code{nil}, that means to ask for confirmation -before overwriting an existing file. Interactively, confirmation is -required, unless the user supplies a prefix argument. - -If @var{filename} is an existing directory, or a symbolic link to one, -@code{write-file} uses the name of the visited file, in directory -@var{filename}. If the buffer is not visiting a file, it uses the -buffer name instead. -@end deffn - - Saving a buffer runs several hooks. It also performs format -conversion (@pxref{Format Conversion}). - -@defvar write-file-functions -The value of this variable is a list of functions to be called before -writing out a buffer to its visited file. If one of them returns -non-@code{nil}, the file is considered already written and the rest of -the functions are not called, nor is the usual code for writing the file -executed. - -If a function in @code{write-file-functions} returns non-@code{nil}, it -is responsible for making a backup file (if that is appropriate). -To do so, execute the following code: - -@example -(or buffer-backed-up (backup-buffer)) -@end example - -You might wish to save the file modes value returned by -@code{backup-buffer} and use that (if non-@code{nil}) to set the mode -bits of the file that you write. This is what @code{save-buffer} -normally does. @xref{Making Backups,, Making Backup Files}. - -The hook functions in @code{write-file-functions} are also responsible -for encoding the data (if desired): they must choose a suitable coding -system and end-of-line conversion (@pxref{Lisp and Coding Systems}), -perform the encoding (@pxref{Explicit Encoding}), and set -@code{last-coding-system-used} to the coding system that was used -(@pxref{Encoding and I/O}). - -If you set this hook locally in a buffer, it is assumed to be -associated with the file or the way the contents of the buffer were -obtained. Thus the variable is marked as a permanent local, so that -changing the major mode does not alter a buffer-local value. On the -other hand, calling @code{set-visited-file-name} will reset it. -If this is not what you want, you might like to use -@code{write-contents-functions} instead. - -Even though this is not a normal hook, you can use @code{add-hook} and -@code{remove-hook} to manipulate the list. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@defvar write-contents-functions -This works just like @code{write-file-functions}, but it is intended -for hooks that pertain to the buffer's contents, not to the particular -visited file or its location. Such hooks are usually set up by major -modes, as buffer-local bindings for this variable. This variable -automatically becomes buffer-local whenever it is set; switching to a -new major mode always resets this variable, but calling -@code{set-visited-file-name} does not. - -If any of the functions in this hook returns non-@code{nil}, the file -is considered already written and the rest are not called and neither -are the functions in @code{write-file-functions}. -@end defvar - -@defopt before-save-hook -This normal hook runs before a buffer is saved in its visited file, -regardless of whether that is done normally or by one of the hooks -described above. For instance, the @file{copyright.el} program uses -this hook to make sure the file you are saving has the current year in -its copyright notice. -@end defopt - -@c Emacs 19 feature -@defopt after-save-hook -This normal hook runs after a buffer has been saved in its visited file. -One use of this hook is in Fast Lock mode; it uses this hook to save the -highlighting information in a cache file. -@end defopt - -@defopt file-precious-flag -If this variable is non-@code{nil}, then @code{save-buffer} protects -against I/O errors while saving by writing the new file to a temporary -name instead of the name it is supposed to have, and then renaming it to -the intended name after it is clear there are no errors. This procedure -prevents problems such as a lack of disk space from resulting in an -invalid file. - -As a side effect, backups are necessarily made by copying. @xref{Rename -or Copy}. Yet, at the same time, saving a precious file always breaks -all hard links between the file you save and other file names. - -Some modes give this variable a non-@code{nil} buffer-local value -in particular buffers. -@end defopt - -@defopt require-final-newline -This variable determines whether files may be written out that do -@emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end of -the file whenever the buffer being saved does not already end in one. -If the value of the variable is non-@code{nil}, but not @code{t}, then -@code{save-buffer} asks the user whether to add a newline each time the -case arises. - -If the value of the variable is @code{nil}, then @code{save-buffer} -doesn't add newlines at all. @code{nil} is the default value, but a few -major modes set it to @code{t} in particular buffers. -@end defopt - - See also the function @code{set-visited-file-name} (@pxref{Buffer File -Name}). - -@node Reading from Files -@comment node-name, next, previous, up -@section Reading from Files -@cindex reading from files - - You can copy a file from the disk and insert it into a buffer -using the @code{insert-file-contents} function. Don't use the user-level -command @code{insert-file} in a Lisp program, as that sets the mark. - -@defun insert-file-contents filename &optional visit beg end replace -This function inserts the contents of file @var{filename} into the -current buffer after point. It returns a list of the absolute file name -and the length of the data inserted. An error is signaled if -@var{filename} is not the name of a file that can be read. - -The function @code{insert-file-contents} checks the file contents -against the defined file formats, and converts the file contents if -appropriate and also calls the functions in -the list @code{after-insert-file-functions}. @xref{Format Conversion}. -Normally, one of the functions in the -@code{after-insert-file-functions} list determines the coding system -(@pxref{Coding Systems}) used for decoding the file's contents, -including end-of-line conversion. However, if the file contains null -bytes, it is by default visited without any code conversions; see -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to -control this behavior. - -If @var{visit} is non-@code{nil}, this function additionally marks the -buffer as unmodified and sets up various fields in the buffer so that it -is visiting the file @var{filename}: these include the buffer's visited -file name and its last save file modtime. This feature is used by -@code{find-file-noselect} and you probably should not use it yourself. - -If @var{beg} and @var{end} are non-@code{nil}, they should be integers -specifying the portion of the file to insert. In this case, @var{visit} -must be @code{nil}. For example, - -@example -(insert-file-contents filename nil 0 500) -@end example - -@noindent -inserts the first 500 characters of a file. - -If the argument @var{replace} is non-@code{nil}, it means to replace the -contents of the buffer (actually, just the accessible portion) with the -contents of the file. This is better than simply deleting the buffer -contents and inserting the whole file, because (1) it preserves some -marker positions and (2) it puts less data in the undo list. - -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. -@end defun - -@defun insert-file-contents-literally filename &optional visit beg end replace -This function works like @code{insert-file-contents} except that it does -not do format decoding (@pxref{Format Conversion}), does not do -character code conversion (@pxref{Coding Systems}), does not run -@code{find-file-hook}, does not perform automatic uncompression, and so -on. -@end defun - -If you want to pass a file name to another process so that another -program can read the file, use the function @code{file-local-copy}; see -@ref{Magic File Names}. - -@node Writing to Files -@comment node-name, next, previous, up -@section Writing to Files -@cindex writing to files - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the @code{append-to-file} and -@code{write-region} functions. Don't use these functions to write to -files that are being visited; that could cause confusion in the -mechanisms for visiting. - -@deffn Command append-to-file start end filename -This function appends the contents of the region delimited by -@var{start} and @var{end} in the current buffer to the end of file -@var{filename}. If that file does not exist, it is created. This -function returns @code{nil}. - -An error is signaled if @var{filename} specifies a nonwritable file, -or a nonexistent file in a directory where files cannot be created. - -When called from Lisp, this function is completely equivalent to: - -@example -(write-region start end filename t) -@end example -@end deffn - -@deffn Command write-region start end filename &optional append visit lockname mustbenew -This function writes the region delimited by @var{start} and @var{end} -in the current buffer into the file specified by @var{filename}. - -If @var{start} is @code{nil}, then the command writes the entire buffer -contents (@emph{not} just the accessible portion) to the file and -ignores @var{end}. - -@c Emacs 19 feature -If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. @var{end} is ignored in -this case. - -If @var{append} is non-@code{nil}, then the specified text is appended -to the existing file contents (if any). If @var{append} is an -integer, @code{write-region} seeks to that byte offset from the start -of the file and writes the data from there. - -If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks -for confirmation if @var{filename} names an existing file. If -@var{mustbenew} is the symbol @code{excl}, then @code{write-region} -does not ask for confirmation, but instead it signals an error -@code{file-already-exists} if the file already exists. - -The test for an existing file, when @var{mustbenew} is @code{excl}, uses -a special system feature. At least for files on a local disk, there is -no chance that some other program could create a file of the same name -before Emacs does, without Emacs's noticing. - -If @var{visit} is @code{t}, then Emacs establishes an association -between the buffer and the file: the buffer is then visiting that file. -It also sets the last file modification time for the current buffer to -@var{filename}'s modtime, and marks the buffer as not modified. This -feature is used by @code{save-buffer}, but you probably should not use -it yourself. - -@c Emacs 19 feature -If @var{visit} is a string, it specifies the file name to visit. This -way, you can write the data to one file (@var{filename}) while recording -the buffer as visiting another file (@var{visit}). The argument -@var{visit} is used in the echo area message and also for file locking; -@var{visit} is stored in @code{buffer-file-name}. This feature is used -to implement @code{file-precious-flag}; don't use it yourself unless you -really know what you're doing. - -The optional argument @var{lockname}, if non-@code{nil}, specifies the -file name to use for purposes of locking and unlocking, overriding -@var{filename} and @var{visit} for that purpose. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format} -and also calls the functions in the list -@code{write-region-annotate-functions}. -@xref{Format Conversion}. - -Normally, @code{write-region} displays the message @samp{Wrote -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This -feature is useful for programs that use files for internal purposes, -files that the user does not need to know about. -@end deffn - -@defmac with-temp-file file body@dots{} -@anchor{Definition of with-temp-file} -The @code{with-temp-file} macro evaluates the @var{body} forms with a -temporary buffer as the current buffer; then, at the end, it writes the -buffer contents into file @var{file}. It kills the temporary buffer -when finished, restoring the buffer that was current before the -@code{with-temp-file} form. Then it returns the value of the last form -in @var{body}. - -The current buffer is restored even in case of an abnormal exit via -@code{throw} or error (@pxref{Nonlocal Exits}). - -See also @code{with-temp-buffer} in @ref{Definition of -with-temp-buffer,, The Current Buffer}. -@end defmac - -@node File Locks -@section File Locks -@cindex file locks -@cindex lock file - - When two users edit the same file at the same time, they are likely -to interfere with each other. Emacs tries to prevent this situation -from arising by recording a @dfn{file lock} when a file is being -modified. (File locks are not implemented on Microsoft systems.) -Emacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another Emacs job, and ask the user what to do. -The file lock is really a file, a symbolic link with a special name, -stored in the same directory as the file you are editing. - - When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously.'' -If this happens, it is possible for the two users to make changes -simultaneously, but Emacs will still warn the user who saves second. -Also, the detection of modification of a buffer visiting a file changed -on disk catches some cases of simultaneous editing; see -@ref{Modification Time}. - -@defun file-locked-p filename -This function returns @code{nil} if the file @var{filename} is not -locked. It returns @code{t} if it is locked by this Emacs process, and -it returns the name of the user who has locked it if it is locked by -some other job. - -@example -@group -(file-locked-p "foo") - @result{} nil -@end group -@end example -@end defun - -@defun lock-buffer &optional filename -This function locks the file @var{filename}, if the current buffer is -modified. The argument @var{filename} defaults to the current buffer's -visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified, or if the system does not support locking. -@end defun - -@defun unlock-buffer -This function unlocks the file being visited in the current buffer, -if the buffer is modified. If the buffer is not modified, then -the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file, or if the -system does not support locking. -@end defun - - File locking is not supported on some systems. On systems that do not -support it, the functions @code{lock-buffer}, @code{unlock-buffer} and -@code{file-locked-p} do nothing and return @code{nil}. - -@defun ask-user-about-lock file other-user -This function is called when the user tries to modify @var{file}, but it -is locked by another user named @var{other-user}. The default -definition of this function asks the user to say what to do. The value -this function returns determines what Emacs does next: - -@itemize @bullet -@item -A value of @code{t} says to grab the lock on the file. Then -this user may edit the file and @var{other-user} loses the lock. - -@item -A value of @code{nil} says to ignore the lock and let this -user edit the file anyway. - -@item -@kindex file-locked -This function may instead signal a @code{file-locked} error, in which -case the change that the user was about to make does not take place. - -The error message for this error looks like this: - -@example -@error{} File is locked: @var{file} @var{other-user} -@end example - -@noindent -where @code{file} is the name of the file and @var{other-user} is the -name of the user who has locked the file. -@end itemize - -If you wish, you can replace the @code{ask-user-about-lock} function -with your own version that makes the decision in another way. The code -for its usual definition is in @file{userlock.el}. -@end defun - -@node Information about Files -@section Information about Files -@cindex file, information about - - The functions described in this section all operate on strings that -designate file names. With a few exceptions, all the functions have -names that begin with the word @samp{file}. These functions all -return information about actual files or directories, so their -arguments must all exist as actual files or directories unless -otherwise noted. - -@menu -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. -@end menu - -@node Testing Accessibility -@comment node-name, next, previous, up -@subsection Testing Accessibility -@cindex accessibility of a file -@cindex file accessibility - - These functions test for permission to access a file in specific -ways. Unless explicitly stated otherwise, they recursively follow -symbolic links for their file name arguments, at all levels (at the -level of the file itself and at all levels of parent directories). - -@defun file-exists-p filename -This function returns @code{t} if a file named @var{filename} appears -to exist. This does not mean you can necessarily read the file, only -that you can find out its attributes. (On Unix and GNU/Linux, this is -true if the file exists and you have execute permission on the -containing directories, regardless of the protection of the file -itself.) - -If the file does not exist, or if fascist access control policies -prevent you from finding the attributes of the file, this function -returns @code{nil}. - -Directories are files, so @code{file-exists-p} returns @code{t} when -given a directory name. However, symbolic links are treated -specially; @code{file-exists-p} returns @code{t} for a symbolic link -name only if the target file exists. -@end defun - -@defun file-readable-p filename -This function returns @code{t} if a file named @var{filename} exists -and you can read it. It returns @code{nil} otherwise. - -@example -@group -(file-readable-p "files.texi") - @result{} t -@end group -@group -(file-exists-p "/usr/spool/mqueue") - @result{} t -@end group -@group -(file-readable-p "/usr/spool/mqueue") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-executable-p filename -This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. On Unix and -GNU/Linux, if the file is a directory, execute permission means you can -check the existence and attributes of files inside the directory, and -open those files if their modes permit. -@end defun - -@defun file-writable-p filename -This function returns @code{t} if the file @var{filename} can be written -or created by you, and @code{nil} otherwise. A file is writable if the -file exists and you can write it. It is creatable if it does not exist, -but the specified directory does exist and you can write in that -directory. - -In the third example below, @file{foo} is not writable because the -parent directory does not exist, even though the user could create such -a directory. - -@example -@group -(file-writable-p "~/foo") - @result{} t -@end group -@group -(file-writable-p "/foo") - @result{} nil -@end group -@group -(file-writable-p "~/no-such-dir/foo") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-accessible-directory-p dirname -This function returns @code{t} if you have permission to open existing -files in the directory whose name as a file is @var{dirname}; -otherwise (or if there is no such directory), it returns @code{nil}. -The value of @var{dirname} may be either a directory name (such as -@file{/foo/}) or the file name of a file which is a directory -(such as @file{/foo}, without the final slash). - -Example: after the following, - -@example -(file-accessible-directory-p "/foo") - @result{} nil -@end example - -@noindent -we can deduce that any attempt to read a file in @file{/foo/} will -give an error. -@end defun - -@defun access-file filename string -This function opens file @var{filename} for reading, then closes it and -returns @code{nil}. However, if the open fails, it signals an error -using @var{string} as the error message text. -@end defun - -@defun file-ownership-preserved-p filename -This function returns @code{t} if deleting the file @var{filename} and -then creating it anew would keep the file's owner unchanged. It also -returns @code{t} for nonexistent files. - -If @var{filename} is a symbolic link, then, unlike the other functions -discussed here, @code{file-ownership-preserved-p} does @emph{not} -replace @var{filename} with its target. However, it does recursively -follow symbolic links at all levels of parent directories. -@end defun - -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename1} does exist, but -@var{filename2} does not, it returns @code{t}. - -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. - -@example -@group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil -@end group -@group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t -@end group -@group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t -@end group -@group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil -@end group -@end example - -You can use @code{file-attributes} to get a file's last modification -time as a list of two numbers. @xref{File Attributes}. -@end defun - -@node Kinds of Files -@comment node-name, next, previous, up -@subsection Distinguishing Kinds of Files - - This section describes how to distinguish various kinds of files, such -as directories, symbolic links, and ordinary files. - -@defun file-symlink-p filename -@cindex file symbolic links -If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns the (non-recursive) link target -as a string. (Determining the file name that the link points to from -the target is nontrivial.) First, this function recursively follows -symbolic links at all levels of parent directories. - -If the file @var{filename} is not a symbolic link (or there is no such file), -@code{file-symlink-p} returns @code{nil}. - -@example -@group -(file-symlink-p "foo") - @result{} nil -@end group -@group -(file-symlink-p "sym-link") - @result{} "foo" -@end group -@group -(file-symlink-p "sym-link2") - @result{} "sym-link" -@end group -@group -(file-symlink-p "/bin") - @result{} "/pub/bin" -@end group -@end example - -@c !!! file-symlink-p: should show output of ls -l for comparison -@end defun - -The next two functions recursively follow symbolic links at -all levels for @var{filename}. - -@defun file-directory-p filename -This function returns @code{t} if @var{filename} is the name of an -existing directory, @code{nil} otherwise. - -@example -@group -(file-directory-p "~rms") - @result{} t -@end group -@group -(file-directory-p "~rms/lewis/files.texi") - @result{} nil -@end group -@group -(file-directory-p "~rms/lewis/no-such-file") - @result{} nil -@end group -@group -(file-directory-p "$HOME") - @result{} nil -@end group -@group -(file-directory-p - (substitute-in-file-name "$HOME")) - @result{} t -@end group -@end example -@end defun - -@defun file-regular-p filename -This function returns @code{t} if the file @var{filename} exists and is -a regular file (not a directory, named pipe, terminal, or -other I/O device). -@end defun - -@node Truenames -@subsection Truenames -@cindex truename (of file) - -@c Emacs 19 features - The @dfn{truename} of a file is the name that you get by following -symbolic links at all levels until none remain, then simplifying away -@samp{.}@: and @samp{..}@: appearing as name components. This results -in a sort of canonical name for the file. A file does not always have a -unique truename; the number of distinct truenames a file has is equal to -the number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - -@defun file-truename filename -The function @code{file-truename} returns the truename of the file -@var{filename}. The argument must be an absolute file name. - -This function does not expand environment variables. Only -@code{substitute-in-file-name} does that. @xref{Definition of -substitute-in-file-name}. - -If you may need to follow symbolic links preceding @samp{..}@: -appearing as a name component, you should make sure to call -@code{file-truename} without prior direct or indirect calls to -@code{expand-file-name}, as otherwise the file name component -immediately preceding @samp{..} will be ``simplified away'' before -@code{file-truename} is called. To eliminate the need for a call to -@code{expand-file-name}, @code{file-truename} handles @samp{~} in the -same way that @code{expand-file-name} does. @xref{File Name -Expansion,, Functions that Expand Filenames}. -@end defun - -@defun file-chase-links filename &optional limit -This function follows symbolic links, starting with @var{filename}, -until it finds a file name which is not the name of a symbolic link. -Then it returns that file name. This function does @emph{not} follow -symbolic links at the level of parent directories. - -If you specify a number for @var{limit}, then after chasing through -that many links, the function just returns what it has even if that is -still a symbolic link. -@end defun - - To illustrate the difference between @code{file-chase-links} and -@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to -the directory @file{/home/foo}, and @file{/home/foo/hello} is an -ordinary file (or at least, not a symbolic link) or nonexistent. Then -we would have: - -@example -(file-chase-links "/usr/foo/hello") - ;; @r{This does not follow the links in the parent directories.} - @result{} "/usr/foo/hello" -(file-truename "/usr/foo/hello") - ;; @r{Assuming that @file{/home} is not a symbolic link.} - @result{} "/home/foo/hello" -@end example - - @xref{Buffer File Name}, for related information. - -@node File Attributes -@comment node-name, next, previous, up -@subsection Other Information about Files - - This section describes the functions for getting detailed information -about a file, other than its contents. This information includes the -mode bits that control access permission, the owner and group numbers, -the number of names, the inode number, the size, and the times of access -and modification. - -@defun file-modes filename -@cindex permission -@cindex file attributes -This function returns the mode bits of @var{filename}, as an integer. -The mode bits are also called the file permissions, and they specify -access control in the usual Unix fashion. If the low-order bit is 1, -then the file is executable by all users, if the second-lowest-order bit -is 1, then the file is writable by all users, etc. - -The highest value returnable is 4095 (7777 octal), meaning that -everyone has read, write, and execute permission, that the @acronym{SUID} bit -is set for both others and group, and that the sticky bit is set. - -If @var{filename} does not exist, @code{file-modes} returns @code{nil}. - -This function recursively follows symbolic links at all levels. - -@example -@group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} -@end group -@group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} -@end group - -@group -(set-file-modes "~/junk/diffs" 438) - @result{} nil -@end group - -@group -(format "%o" 438) - @result{} "666" ; @r{Convert to octal.} -@end group - -@group -% ls -l diffs - -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs -@end group -@end example -@end defun - -If the @var{filename} argument to the next two functions is a symbolic -link, then these function do @emph{not} replace it with its target. -However, they both recursively follow symbolic links at all levels of -parent directories. - -@defun file-nlinks filename -This functions returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, then this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files they -link to. - -@example -@group -% ls -l foo* --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - -@defun file-attributes filename &optional id-format -@anchor{Definition of file-attributes} -This function returns a list of attributes of file @var{filename}. If -the specified file cannot be opened, it returns @code{nil}. -The optional parameter @var{id-format} specifies the preferred format -of attributes @acronym{UID} and @acronym{GID} (see below)---the -valid values are @code{'string} and @code{'integer}. The latter is -the default, but we plan to change that, so you should specify a -non-@code{nil} value for @var{id-format} if you use the returned -@acronym{UID} or @acronym{GID}. - -The elements of the list, in order, are: - -@enumerate 0 -@item -@code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. - -@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 -@item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). - -@item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is an integer or a floating -point number. - -@item -The file's @acronym{GID}, likewise. - -@item -The time of last access, as a list of two integers. -The first integer has the high-order 16 bits of time, -the second has the low 16 bits. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) - -@item -The time of last modification as a list of two integers (as above). -@cindex modification time of file - -@item -The time of last status change as a list of two integers (as above). - -@item -The size of the file in bytes. If the size is too large to fit in a -Lisp integer, this is a floating point number. - -@item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. - -@item -@code{t} if the file's @acronym{GID} would change if file were -deleted and recreated; @code{nil} otherwise. - -@item -The file's inode number. If possible, this is an integer. If the inode -number is too large to be represented as an integer in Emacs Lisp, then -the value has the form @code{(@var{high} . @var{low})}, where @var{low} -holds the low 16 bits. - -@item -The file system number of the file system that the file is in. -Depending on the magnitude of the value, this can be either an integer -or a cons cell, in the same manner as the inode number. This element -and the file's inode number together give enough information to -distinguish any two files on the system---no two files can have the same -values for both of these numbers. -@end enumerate - -For example, here are the file attributes for @file{files.texi}: - -@example -@group -(file-attributes "files.texi" 'string) - @result{} (nil 1 "lh" "users" - (8489 20284) - (8489 20284) - (8489 20285) - 14906 "-rw-rw-rw-" - nil 129500 -32252) -@end group -@end example - -@noindent -and here is how the result is interpreted: - -@table @code -@item nil -is neither a directory nor a symbolic link. - -@item 1 -has only one name (the name @file{files.texi} in the current default -directory). - -@item "lh" -is owned by the user with name "lh". - -@item "users" -is in the group with name "users". - -@item (8489 20284) -was last accessed on Aug 19 00:09. - -@item (8489 20284) -was last modified on Aug 19 00:09. - -@item (8489 20285) -last had its inode changed on Aug 19 00:09. - -@item 14906 -is 14906 bytes long. (It may not contain 14906 characters, though, -if some of the bytes belong to multibyte sequences.) - -@item "-rw-rw-rw-" -has a mode of read and write access for the owner, group, and world. - -@item nil -would retain the same @acronym{GID} if it were recreated. - -@item 129500 -has an inode number of 129500. -@item -32252 -is on file system number -32252. -@end table -@end defun - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS - On MS-DOS, there is no such thing as an ``executable'' file mode bit. -So Emacs considers a file executable if its name ends in one of the -standard executable extensions, such as @file{.com}, @file{.bat}, -@file{.exe}, and some others. Files that begin with the Unix-standard -@samp{#!} signature, such as shell and Perl scripts, are also considered -as executable files. This is reflected in the values returned by -@code{file-modes} and @code{file-attributes}. Directories are also -reported with executable bit set, for compatibility with Unix. - -@node Locating Files -@subsection How to Locate Files in Standard Places -@cindex locate file in path -@cindex find file in path - - This section explains how to search for a file in a list of -directories (a @dfn{path}). One example is when you need to look for -a program's executable file, e.g., to find out whether a given program -is installed on the user's system. Another example is the search for -Lisp libraries (@pxref{Library Search}). Such searches generally need -to try various possible file name extensions, in addition to various -possible directories. Emacs provides a function for such a -generalized search for a file. - -@defun locate-file filename path &optional suffixes predicate -This function searches for a file whose name is @var{filename} in a -list of directories given by @var{path}, trying the suffixes in -@var{suffixes}. If it finds such a file, it returns the full -@dfn{absolute file name} of the file (@pxref{Relative File Names}); -otherwise it returns @code{nil}. - -The optional argument @var{suffixes} gives the list of file-name -suffixes to append to @var{filename} when searching. -@code{locate-file} tries each possible directory with each of these -suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there -are no suffixes, and @var{filename} is used only as-is. Typical -values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess -Creation, exec-suffixes}), @code{load-suffixes}, -@code{load-file-rep-suffixes} and the return value of the function -@code{get-load-suffixes} (@pxref{Load Suffixes}). - -Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess -Creation, exec-path}) when looking for executable programs or -@code{load-path} (@pxref{Library Search, load-path}) when looking for -Lisp files. If @var{filename} is absolute, @var{path} has no effect, -but the suffixes in @var{suffixes} are still tried. - -The optional argument @var{predicate}, if non-@code{nil}, specifies -the predicate function to use for testing whether a candidate file is -suitable. The predicate function is passed the candidate file name as -its single argument. If @var{predicate} is @code{nil} or unspecified, -@code{locate-file} uses @code{file-readable-p} as the default -predicate. Useful non-default predicates include -@code{file-executable-p}, @code{file-directory-p}, and other -predicates described in @ref{Kinds of Files}. - -For compatibility, @var{predicate} can also be one of the symbols -@code{executable}, @code{readable}, @code{writable}, @code{exists}, or -a list of one or more of these symbols. -@end defun - -@defun executable-find program -This function searches for the executable file of the named -@var{program} and returns the full absolute name of the executable, -including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories -in @code{exec-path} and tries all the file-name extensions in -@code{exec-suffixes}. -@end defun - -@node Changing Files -@section Changing File Names and Attributes -@c @cindex renaming files Duplicates rename-file -@cindex copying files -@cindex deleting files -@cindex linking files -@cindex setting modes of files - - The functions in this section rename, copy, delete, link, and set the -modes of files. - - In the functions that have an argument @var{newname}, if a file by the -name of @var{newname} already exists, the actions taken depend on the -value of the argument @var{ok-if-already-exists}: - -@itemize @bullet -@item -Signal a @code{file-already-exists} error if -@var{ok-if-already-exists} is @code{nil}. - -@item -Request confirmation if @var{ok-if-already-exists} is a number. - -@item -Replace the old file without confirmation if @var{ok-if-already-exists} -is any other value. -@end itemize - -The next four commands all recursively follow symbolic links at all -levels of parent directories for their first argument, but, if that -argument is itself a symbolic link, then only @code{copy-file} -replaces it with its (recursive) target. - -@deffn Command add-name-to-file oldname newname &optional ok-if-already-exists -@cindex file with multiple names -@cindex file hard link -This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. - -In the first part of the following example, we list two files, -@file{foo} and @file{foo3}. - -@example -@group -% ls -li fo* -81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Now we create a hard link, by calling @code{add-name-to-file}, then list -the files again. This shows two names for one file, @file{foo} and -@file{foo2}. - -@example -@group -(add-name-to-file "foo" "foo2") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 -84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Finally, we evaluate the following: - -@example -(add-name-to-file "foo" "foo3" t) -@end example - -@noindent -and list the files again. Now there are three names -for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old -contents of @file{foo3} are lost. - -@example -@group -(add-name-to-file "foo1" "foo3") - @result{} nil -@end group - -@group -% ls -li fo* -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 -81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 -@end group -@end example - -This function is meaningless on operating systems where multiple names -for one file are not allowed. Some systems implement multiple names -by copying the file instead. - -See also @code{file-nlinks} in @ref{File Attributes}. -@end deffn - -@deffn Command rename-file filename newname &optional ok-if-already-exists -This command renames the file @var{filename} as @var{newname}. - -If @var{filename} has additional names aside from @var{filename}, it -continues to have those names. In fact, adding the name @var{newname} -with @code{add-name-to-file} and then deleting @var{filename} has the -same effect as renaming, aside from momentary intermediate states. -@end deffn - -@deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid -This command copies the file @var{oldname} to @var{newname}. An -error is signaled if @var{oldname} does not exist. If @var{newname} -names a directory, it copies @var{oldname} into that directory, -preserving its final name component. - -If @var{time} is non-@code{nil}, then this function gives the new file -the same last-modified time that the old one has. (This works on only -some operating systems.) If setting the time gets an error, -@code{copy-file} signals a @code{file-date-error} error. In an -interactive call, a prefix argument specifies a non-@code{nil} value -for @var{time}. - -This function copies the file modes, too. - -If argument @var{preserve-uid-gid} is @code{nil}, we let the operating -system decide the user and group ownership of the new file (this is -usually set to the user running Emacs). If @var{preserve-uid-gid} is -non-@code{nil}, we attempt to copy the user and group ownership of the -file. This works only on some operating systems, and only if you have -the correct permissions to do so. -@end deffn - -@deffn Command make-symbolic-link filename newname &optional ok-if-exists -@pindex ln -@kindex file-already-exists -This command makes a symbolic link to @var{filename}, named -@var{newname}. This is like the shell command @samp{ln -s -@var{filename} @var{newname}}. - -This function is not available on systems that don't support symbolic -links. -@end deffn - -@deffn Command delete-file filename -@pindex rm -This command deletes the file @var{filename}, like the shell command -@samp{rm @var{filename}}. If the file has multiple names, it continues -to exist under the other names. - -A suitable kind of @code{file-error} error is signaled if the file does -not exist, or is not deletable. (On Unix and GNU/Linux, a file is -deletable if its directory is writable.) - -If @var{filename} is a symbolic link, @code{delete-file} does not -replace it with its target, but it does follow symbolic links at all -levels of parent directories. - -See also @code{delete-directory} in @ref{Create/Delete Dirs}. -@end deffn - -@deffn Command set-file-modes filename mode -This function sets mode bits of @var{filename} to @var{mode} (which -must be an integer when the function is called non-interactively). -Only the low 12 bits of @var{mode} are used. - -Interactively, @var{mode} is read from the minibuffer using -@code{read-file-modes}, which accepts mode bits either as a number or -as a character string representing the mode bits symbolically. See -the description of @code{read-file-modes} below for the supported -forms of symbolic notation for mode bits. - -This function recursively follows symbolic links at all levels for -@var{filename}. -@end deffn - -@c Emacs 19 feature -@defun set-default-file-modes mode -@cindex umask -This function sets the default file protection for new files created by -Emacs and its subprocesses. Every file created with Emacs initially has -this protection, or a subset of it (@code{write-region} will not give a -file execute permission even if the default file protection allows -execute permission). On Unix and GNU/Linux, the default protection is -the bitwise complement of the ``umask'' value. - -The argument @var{mode} must be an integer. On most systems, only the -low 9 bits of @var{mode} are meaningful. You can use the Lisp construct -for octal character codes to enter @var{mode}; for example, - -@example -(set-default-file-modes ?\644) -@end example - -Saving a modified version of an existing file does not count as creating -the file; it preserves the existing file's mode, whatever that is. So -the default file protection has no effect. -@end defun - -@defun default-file-modes -This function returns the current default protection value. -@end defun - -@defun read-file-modes &optional prompt base-file -This function reads file mode bits from the minibuffer. The optional -argument @var{prompt} specifies a non-default prompt. Second optional -argument @var{base-file} is the name of a file on whose permissions to -base the mode bits that this function returns, if what the user types -specifies mode bits relative to permissions of an existing file. - -If user input represents an octal number, this function returns that -number. If it is a complete symbolic specification of mode bits, as -in @code{"u=rwx"}, the function converts it to the equivalent numeric -value using @code{file-modes-symbolic-to-number} and returns the -result. If the specification is relative, as in @code{"o+g"}, then -the permissions on which the specification is based are taken from the -mode bits of @var{base-file}. If @var{base-file} is omitted or -@code{nil}, the function uses @code{0} as the base mode bits. The -complete and relative specifications can be combined, as in -@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The -@sc{gnu} @code{Coreutils} Manual}, for detailed description of -symbolic mode bits specifications. -@end defun - -@defun file-modes-symbolic-to-number modes &optional base-modes -This subroutine converts a symbolic specification of file mode bits in -@var{modes} into the equivalent numeric value. If the symbolic -specification is based on an existing file, that file's mode bits are -taken from the optional argument @var{base-modes}; if that argument is -omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at -all. -@end defun - -@defun set-file-times filename &optional time -This function sets the access and modification times of @var{filename} -to @var{time}. The return value is @code{t} if the times are successfully -set, otherwise it is @code{nil}. @var{time} defaults to the current -time and must be in the format returned by @code{current-time} -(@pxref{Time of Day}). -@end defun - -@node File Names -@section File Names -@cindex file names - - Files are generally referred to by their names, in Emacs as elsewhere. -File names in Emacs are represented as strings. The functions that -operate on a file all expect a file name argument. - - In addition to operating on files themselves, Emacs Lisp programs -often need to operate on file names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - - On MS-DOS and MS-Windows, these functions (like the function that -actually operate on files) accept MS-DOS or MS-Windows file-name syntax, -where backslashes separate the components, as well as Unix syntax; but -they always return Unix syntax. This enables Lisp programs to specify -file names in Unix syntax and work properly on all systems without -change. - -@menu -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. -@end menu - -@node File Name Components -@subsection File Name Components -@cindex directory part (of file name) -@cindex nondirectory part (of file name) -@cindex version number (in file name) - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, Emacs considers a file name as having two main -parts: the @dfn{directory name} part, and the @dfn{nondirectory} part -(or @dfn{file name within the directory}). Either part may be empty. -Concatenating these two parts reproduces the original file name. - - On most systems, the directory part is everything up to and including -the last slash (backslash is also allowed in input on MS-DOS or -MS-Windows); the nondirectory part is the rest. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On most systems, only -backup files have version numbers in their names. - -@defun file-name-directory filename -This function returns the directory part of @var{filename}, as a -directory name (@pxref{Directory Names}), or @code{nil} if -@var{filename} does not include a directory part. - -On GNU and Unix systems, a string returned by this function always -ends in a slash. On MS-DOS it can also end in a colon. - -@example -@group -(file-name-directory "lewis/foo") ; @r{Unix example} - @result{} "lewis/" -@end group -@group -(file-name-directory "foo") ; @r{Unix example} - @result{} nil -@end group -@end example -@end defun - -@defun file-name-nondirectory filename -This function returns the nondirectory part of @var{filename}. - -@example -@group -(file-name-nondirectory "lewis/foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "lewis/") - @result{} "" -@end group -@end example -@end defun - -@defun file-name-sans-versions filename &optional keep-backup-version -This function returns @var{filename} with any file version numbers, -backup version numbers, or trailing tildes discarded. - -If @var{keep-backup-version} is non-@code{nil}, then true file version -numbers understood as such by the file system are discarded from the -return value, but backup version numbers are kept. - -@example -@group -(file-name-sans-versions "~rms/foo.~1~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo") - @result{} "~rms/foo" -@end group -@end example -@end defun - -@defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension,'' if any, -after applying @code{file-name-sans-versions} to remove any -version/backup part. The extension, in a file name, is the part that -follows the last @samp{.} in the last name component (minus any -version/backup part). - -This function returns @code{nil} for extensionless file names such as -@file{foo}. It returns @code{""} for null extensions, as in -@file{foo.}. If the last component of a file name begins with a -@samp{.}, that @samp{.} doesn't count as the beginning of an -extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not -@samp{.emacs}. - -If @var{period} is non-@code{nil}, then the returned value includes -the period that delimits the extension, and if @var{filename} has no -extension, the value is @code{""}. -@end defun - -@defun file-name-sans-extension filename -This function returns @var{filename} minus its extension, if any. The -version/backup part, if present, is only removed if the file has an -extension. For example, - -@example -(file-name-sans-extension "foo.lose.c") - @result{} "foo.lose" -(file-name-sans-extension "big.hack/foo") - @result{} "big.hack/foo" -(file-name-sans-extension "/my/home/.emacs") - @result{} "/my/home/.emacs" -(file-name-sans-extension "/my/home/.emacs.el") - @result{} "/my/home/.emacs" -(file-name-sans-extension "~/foo.el.~3~") - @result{} "~/foo" -(file-name-sans-extension "~/foo.~3~") - @result{} "~/foo.~3~" -@end example - -Note that the @samp{.~3~} in the two last examples is the backup part, -not an extension. -@end defun - -@ignore -Andrew Innes says that this - -@c @defvar directory-sep-char -This variable holds the character that Emacs normally uses to separate -file name components. The default value is @code{?/}, but on MS-Windows -you can set it to @code{?\\}; then the functions that transform file names -use backslashes in their output. - -File names using backslashes work as input to Lisp primitives even on -MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default -value of @code{?/}. -@end defvar -@end ignore - -@node Relative File Names -@subsection Absolute and Relative File Names -@cindex absolute file name -@cindex relative file name - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an @dfn{absolute} -file name. Or it can specify the position of the file in the tree -relative to a default directory; then it is called a @dfn{relative} file -name. On Unix and GNU/Linux, an absolute file name starts with a slash -or a tilde (@samp{~}), and a relative one does not. On MS-DOS and -MS-Windows, an absolute file name starts with a slash or a backslash, or -with a drive specification @samp{@var{x}:/}, where @var{x} is the -@dfn{drive letter}. - -@defun file-name-absolute-p filename -This function returns @code{t} if file @var{filename} is an absolute -file name, @code{nil} otherwise. - -@example -@group -(file-name-absolute-p "~rms/foo") - @result{} t -@end group -@group -(file-name-absolute-p "rms/foo") - @result{} nil -@end group -@group -(file-name-absolute-p "/user/rms/foo") - @result{} t -@end group -@end example -@end defun - - Given a possibly relative file name, you can convert it to an -absolute name using @code{expand-file-name} (@pxref{File Name -Expansion}). This function converts absolute file names to relative -names: - -@defun file-relative-name filename &optional directory -This function tries to return a relative name that is equivalent to -@var{filename}, assuming the result will be interpreted relative to -@var{directory} (an absolute directory name or directory file name). -If @var{directory} is omitted or @code{nil}, it defaults to the -current buffer's default directory. - -On some operating systems, an absolute file name begins with a device -name. On such systems, @var{filename} has no relative equivalent based -on @var{directory} if they start with two different device names. In -this case, @code{file-relative-name} returns @var{filename} in absolute -form. - -@example -(file-relative-name "/foo/bar" "/foo/") - @result{} "bar" -(file-relative-name "/foo/bar" "/hack/") - @result{} "../foo/bar" -@end example -@end defun - -@node Directory Names -@comment node-name, next, previous, up -@subsection Directory Names -@cindex directory name -@cindex file name of directory - - A @dfn{directory name} is the name of a directory. A directory is -actually a kind of file, so it has a file name, which is related to -the directory name but not identical to it. (This is not quite the -same as the usual Unix terminology.) These two different names for -the same entity are related by a syntactic transformation. On GNU and -Unix systems, this is simple: a directory name ends in a slash, -whereas the directory's name as a file lacks that slash. On MS-DOS -the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. When @code{file-name-directory} returns a string, that is -always a directory name. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. - -@defun file-name-as-directory filename -This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. On -most systems, this means appending a slash to the string (if it does not -already end in one). - -@example -@group -(file-name-as-directory "~rms/lewis") - @result{} "~rms/lewis/" -@end group -@end example -@end defun - -@defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On most -systems, this means removing the final slash (or backslash) from the -string. - -@example -@group -(directory-file-name "~lewis/") - @result{} "~lewis" -@end group -@end example -@end defun - - Given a directory name, you can combine it with a relative file name -using @code{concat}: - -@example -(concat @var{dirname} @var{relfile}) -@end example - -@noindent -Be sure to verify that the file name is relative before doing that. -If you use an absolute file name, the results could be syntactically -invalid or refer to the wrong file. - - If you want to use a directory file name in making such a -combination, you must first convert it to a directory name using -@code{file-name-as-directory}: - -@example -(concat (file-name-as-directory @var{dirfile}) @var{relfile}) -@end example - -@noindent -Don't try concatenating a slash by hand, as in - -@example -;;; @r{Wrong!} -(concat @var{dirfile} "/" @var{relfile}) -@end example - -@noindent -because this is not portable. Always use -@code{file-name-as-directory}. - -@cindex directory name abbreviation - Directory name abbreviations are useful for directories that are -normally accessed through symbolic links. Sometimes the users recognize -primarily the link's name as ``the name'' of the directory, and find it -annoying to see the directory's ``real'' name. If you define the link -name as an abbreviation for the ``real'' name, Emacs shows users the -abbreviation instead. - -@defopt directory-abbrev-alist -The variable @code{directory-abbrev-alist} contains an alist of -abbreviations to use for file directories. Each element has the form -@code{(@var{from} . @var{to})}, and says to replace @var{from} with -@var{to} when it appears in a directory name. The @var{from} string is -actually a regular expression; it should always start with @samp{^}. -The @var{to} string should be an ordinary absolute directory name. Do -not use @samp{~} to stand for a home directory in that string. The -function @code{abbreviate-file-name} performs these substitutions. - -You can set this variable in @file{site-init.el} to describe the -abbreviations appropriate for your site. - -Here's an example, from a system on which file system @file{/home/fsf} -and so on are normally accessed through symbolic links named @file{/fsf} -and so on. - -@example -(("^/home/fsf" . "/fsf") - ("^/home/gp" . "/gp") - ("^/home/gd" . "/gd")) -@end example -@end defopt - - To convert a directory name to its abbreviation, use this -function: - -@defun abbreviate-file-name filename -@anchor{Definition of abbreviate-file-name} -This function applies abbreviations from @code{directory-abbrev-alist} -to its argument, and substitutes @samp{~} for the user's home -directory. You can use it for directory names and for file names, -because it recognizes abbreviations even as part of the name. -@end defun - -@node File Name Expansion -@subsection Functions that Expand Filenames -@cindex expansion of file names - - @dfn{Expansion} of a file name means converting a relative file name -to an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name to -be expanded. Expansion also simplifies file names by eliminating -redundancies such as @file{./} and @file{@var{name}/../}. - -@defun expand-file-name filename &optional directory -This function converts @var{filename} to an absolute file name. If -@var{directory} is supplied, it is the default directory to start with -if @var{filename} is relative. (The value of @var{directory} should -itself be an absolute directory name or directory file name; it may -start with @samp{~}.) Otherwise, the current buffer's value of -@code{default-directory} is used. For example: - -@example -@group -(expand-file-name "foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@group -(expand-file-name "../foo") - @result{} "/xcssun/users/rms/foo" -@end group -@group -(expand-file-name "foo" "/usr/spool/") - @result{} "/usr/spool/foo" -@end group -@group -(expand-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/lewis/$HOME/foo" -@end group -@end example - -If the part of the combined file name before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first -slash is @samp{~@var{user}} and if @var{user} is a valid login name, -it expands to @var{user}'s home directory. - -Filenames containing @samp{.} or @samp{..} are simplified to their -canonical form: - -@example -@group -(expand-file-name "bar/../foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@end example - -In some cases, a leading @samp{..} component can remain in the output: - -@example -@group -(expand-file-name "../home" "/") - @result{} "/../home" -@end group -@end example - -@noindent -This is for the sake of filesystems that have the concept of a -``superroot'' above the root directory @file{/}. On other filesystems, -@file{/../} is interpreted exactly the same as @file{/}. - -Note that @code{expand-file-name} does @emph{not} expand environment -variables; only @code{substitute-in-file-name} does that. - -Note also that @code{expand-file-name} does not follow symbolic links -at any level. This results in a difference between the way -@code{file-truename} and @code{expand-file-name} treat @samp{..}. -Assuming that @samp{/tmp/bar} is a symbolic link to the directory -@samp{/tmp/foo/bar} we get: - -@example -@group -(file-truename "/tmp/bar/../myfile") - @result{} "/tmp/foo/myfile" -@end group -@group -(expand-file-name "/tmp/bar/../myfile") - @result{} "/tmp/myfile" -@end group -@end example - -If you may need to follow symbolic links preceding @samp{..}, you -should make sure to call @code{file-truename} without prior direct or -indirect calls to @code{expand-file-name}. @xref{Truenames}. -@end defun - -@defvar default-directory -The value of this buffer-local variable is the default directory for the -current buffer. It should be an absolute directory name; it may start -with @samp{~}. This variable is buffer-local in every buffer. - -@code{expand-file-name} uses the default directory when its second -argument is @code{nil}. - -The value is always a string ending with a slash. - -@example -@group -default-directory - @result{} "/user/lewis/manual/" -@end group -@end example -@end defvar - -@defun substitute-in-file-name filename -@anchor{Definition of substitute-in-file-name} -This function replaces environment variable references in -@var{filename} with the environment variable values. Following -standard Unix shell syntax, @samp{$} is the prefix to substitute an -environment variable value. If the input contains @samp{$$}, that is -converted to @samp{$}; this gives the user a way to ``quote'' a -@samp{$}. - -The environment variable name is the series of alphanumeric characters -(including underscores) that follow the @samp{$}. If the character following -the @samp{$} is a @samp{@{}, then the variable name is everything up to the -matching @samp{@}}. - -Calling @code{substitute-in-file-name} on output produced by -@code{substitute-in-file-name} tends to give incorrect results. For -instance, use of @samp{$$} to quote a single @samp{$} won't work -properly, and @samp{$} in an environment variable's value could lead -to repeated substitution. Therefore, programs that call this function -and put the output where it will be passed to this function need to -double all @samp{$} characters to prevent subsequent incorrect -results. - -@c Wordy to avoid overfull hbox. --rjc 15mar92 -Here we assume that the environment variable @code{HOME}, which holds -the user's home directory name, has value @samp{/xcssun/users/rms}. - -@example -@group -(substitute-in-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -After substitution, if a @samp{~} or a @samp{/} appears immediately -after another @samp{/}, the function discards everything before it (up -through the immediately preceding @samp{/}). - -@example -@group -(substitute-in-file-name "bar/~/foo") - @result{} "~/foo" -@end group -@group -(substitute-in-file-name "/usr/local/$HOME/foo") - @result{} "/xcssun/users/rms/foo" - ;; @r{@file{/usr/local/} has been discarded.} -@end group -@end example - -@end defun - -@node Unique File Names -@subsection Generating Unique File Names - - Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: - -@example -(make-temp-file @var{name-of-application}) -@end example - -@noindent -The job of @code{make-temp-file} is to prevent two different users or -two different jobs from trying to use the exact same file name. - -@defun make-temp-file prefix &optional dir-flag suffix -This function creates a temporary file and returns its name. Emacs -creates the temporary file's name by adding to @var{prefix} some -random characters that are different in each Emacs job. The result is -guaranteed to be a newly created empty file. On MS-DOS, this function -can truncate the @var{string} prefix to fit into the 8+3 file-name -limits. If @var{prefix} is a relative file name, it is expanded -against @code{temporary-file-directory}. - -@example -@group -(make-temp-file "foo") - @result{} "/tmp/foo232J6v" -@end group -@end example - -When @code{make-temp-file} returns, the file has been created and is -empty. At that point, you should write the intended contents into the -file. - -If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an -empty directory instead of an empty file. It returns the file name, -not the directory name, of that directory. @xref{Directory Names}. - -If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at -the end of the file name. - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-file} should have its -own @var{prefix}. The number added to the end of @var{prefix} -distinguishes between the same application running in different Emacs -jobs. Additional added characters permit a large number of distinct -names even in one Emacs job. -@end defun - - The default directory for temporary files is controlled by the -variable @code{temporary-file-directory}. This variable gives the user -a uniform way to specify the directory for all temporary files. Some -programs use @code{small-temporary-file-directory} instead, if that is -non-@code{nil}. To use it, you should expand the prefix against -the proper directory before calling @code{make-temp-file}. - - In older Emacs versions where @code{make-temp-file} does not exist, -you should use @code{make-temp-name} instead: - -@example -(make-temp-name - (expand-file-name @var{name-of-application} - temporary-file-directory)) -@end example - -@defun make-temp-name string -This function generates a string that can be used as a unique file -name. The name starts with @var{string}, and has several random -characters appended to it, which are different in each Emacs job. It -is like @code{make-temp-file} except that it just constructs a name, -and does not create a file. Another difference is that @var{string} -should be an absolute file name. On MS-DOS, this function can -truncate the @var{string} prefix to fit into the 8+3 file-name limits. -@end defun - -@defopt temporary-file-directory -@cindex @code{TMPDIR} environment variable -@cindex @code{TMP} environment variable -@cindex @code{TEMP} environment variable -This variable specifies the directory name for creating temporary files. -Its value should be a directory name (@pxref{Directory Names}), but it -is good for Lisp programs to cope if the value is a directory's file -name instead. Using the value as the second argument to -@code{expand-file-name} is a good way to achieve that. - -The default value is determined in a reasonable way for your operating -system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} -environment variables, with a fall-back to a system-dependent name if -none of these variables is defined. - -Even if you do not use @code{make-temp-file} to create the temporary -file, you should still use this variable to decide which directory to -put the file in. However, if you expect the file to be small, you -should use @code{small-temporary-file-directory} first if that is -non-@code{nil}. -@end defopt - -@defopt small-temporary-file-directory -This variable specifies the directory name for -creating certain temporary files, which are likely to be small. - -If you want to write a temporary file which is likely to be small, you -should compute the directory like this: - -@example -(make-temp-file - (expand-file-name @var{prefix} - (or small-temporary-file-directory - temporary-file-directory))) -@end example -@end defopt - -@node File Name Completion -@subsection File Name Completion -@cindex file name completion subroutines -@cindex completion, file name - - This section describes low-level subroutines for completing a file -name. For higher level functions, see @ref{Reading File Names}. - -@defun file-name-all-completions partial-filename directory -This function returns a list of all possible completions for a file -whose name starts with @var{partial-filename} in directory -@var{directory}. The order of the completions is the order of the files -in the directory, which is unpredictable and conveys no useful -information. - -The argument @var{partial-filename} must be a file name containing no -directory part and no slash (or backslash on some systems). The current -buffer's default directory is prepended to @var{directory}, if -@var{directory} is not absolute. - -In the following example, suppose that @file{~rms/lewis} is the current -default directory, and has five files whose names begin with @samp{f}: -@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-all-completions "f" "") - @result{} ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") -@end group - -@group -(file-name-all-completions "fo" "") - @result{} ("foo") -@end group -@end example -@end defun - -@defun file-name-completion filename directory &optional predicate -This function completes the file name @var{filename} in directory -@var{directory}. It returns the longest prefix common to all file names -in directory @var{directory} that start with @var{filename}. If -@var{predicate} is non-@code{nil} then it ignores possible completions -that don't satisfy @var{predicate}, after calling that function -with one argument, the expanded absolute file name. - -If only one match exists and @var{filename} matches it exactly, the -function returns @code{t}. The function returns @code{nil} if directory -@var{directory} contains no name starting with @var{filename}. - -In the following example, suppose that the current default directory -has five files whose names begin with @samp{f}: @file{foo}, -@file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-completion "fi" "") - @result{} "file" -@end group - -@group -(file-name-completion "file.c.~1" "") - @result{} "file.c.~1~" -@end group - -@group -(file-name-completion "file.c.~1~" "") - @result{} t -@end group - -@group -(file-name-completion "file.c.~3" "") - @result{} nil -@end group -@end example -@end defun - -@defopt completion-ignored-extensions -@code{file-name-completion} usually ignores file names that end in any -string in this list. It does not ignore them when all the possible -completions end in one of these suffixes. This variable has no effect -on @code{file-name-all-completions}.@refill - -A typical value might look like this: - -@example -@group -completion-ignored-extensions - @result{} (".o" ".elc" "~" ".dvi") -@end group -@end example - -If an element of @code{completion-ignored-extensions} ends in a slash -@samp{/}, it signals a directory. The elements which do @emph{not} end -in a slash will never match a directory; thus, the above value will not -filter out a directory named @file{foo.elc}. -@end defopt - -@node Standard File Names -@subsection Standard File Names - - Most of the file names used in Lisp programs are entered by the user. -But occasionally a Lisp program needs to specify a standard file name -for a particular use---typically, to hold customization information -about each user. For example, abbrev definitions are stored (by -default) in the file @file{~/.abbrev_defs}; the @code{completion} -package stores completions in the file @file{~/.completions}. These are -two of the many standard file names used by parts of Emacs for certain -purposes. - - Various operating systems have their own conventions for valid file -names and for which file names to use for user profile data. A Lisp -program which reads a file using a standard file name ought to use, on -each type of system, a file name suitable for that system. The function -@code{convert-standard-filename} makes this easy to do. - -@defun convert-standard-filename filename -This function alters the file name @var{filename} to fit the conventions -of the operating system in use, and returns the result as a new string. -@end defun - - The recommended way to specify a standard file name in a Lisp program -is to choose a name which fits the conventions of GNU and Unix systems, -usually with a nondirectory part that starts with a period, and pass it -to @code{convert-standard-filename} instead of using it directly. Here -is an example from the @code{completion} package: - -@example -(defvar save-completions-file-name - (convert-standard-filename "~/.completions") - "*The file name to save completions to.") -@end example - - On GNU and Unix systems, and on some other systems as well, -@code{convert-standard-filename} returns its argument unchanged. On -some other systems, it alters the name to fit the system's conventions. - - For example, on MS-DOS the alterations made by this function include -converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the -middle of the name to @samp{.} if there is no other @samp{.}, inserting -a @samp{.} after eight characters if there is none, and truncating to -three characters after the @samp{.}. (It makes other changes as well.) -Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and -@file{.completions} becomes @file{_complet.ion}. - -@node Contents of Directories -@section Contents of Directories -@cindex directory-oriented functions -@cindex file names in directory - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - Emacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the @code{ls} shell command. In -the latter case, it can optionally display information about each file, -depending on the options passed to the @code{ls} command. - -@defun directory-files directory &optional full-name match-regexp nosort -This function returns a list of the names of the files in the directory -@var{directory}. By default, the list is in alphabetical order. - -If @var{full-name} is non-@code{nil}, the function returns the files' -absolute file names. Otherwise, it returns the names relative to -the specified directory. - -If @var{match-regexp} is non-@code{nil}, this function returns only -those file names that contain a match for that regular expression---the -other file names are excluded from the list. On case-insensitive -filesystems, the regular expression matching is case-insensitive. - -@c Emacs 19 feature -If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort -the list, so you get the file names in no particular order. Use this if -you want the utmost possible speed and don't care what order the files -are processed in. If the order of processing is visible to the user, -then the user will probably be happier if you do sort the names. - -@example -@group -(directory-files "~lewis") - @result{} ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") -@end group -@end example - -An error is signaled if @var{directory} is not the name of a directory -that can be read. -@end defun - -@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format -This is similar to @code{directory-files} in deciding which files -to report on and how to report their names. However, instead -of returning a list of file names, it returns for each file a -list @code{(@var{filename} . @var{attributes})}, where @var{attributes} -is what @code{file-attributes} would return for that file. -The optional argument @var{id-format} has the same meaning as the -corresponding argument to @code{file-attributes} (@pxref{Definition -of file-attributes}). -@end defun - -@defun file-expand-wildcards pattern &optional full -This function expands the wildcard pattern @var{pattern}, returning -a list of file names that match it. - -If @var{pattern} is written as an absolute file name, -the values are absolute also. - -If @var{pattern} is written as a relative file name, it is interpreted -relative to the current default directory. The file names returned are -normally also relative to the current default directory. However, if -@var{full} is non-@code{nil}, they are absolute. -@end defun - -@defun insert-directory file switches &optional wildcard full-directory-p -This function inserts (in the current buffer) a directory listing for -directory @var{file}, formatted with @code{ls} according to -@var{switches}. It leaves point after the inserted text. -@var{switches} may be a string of options, or a list of strings -representing individual options. - -The argument @var{file} may be either a directory name or a file -specification including wildcard characters. If @var{wildcard} is -non-@code{nil}, that means treat @var{file} as a file specification with -wildcards. - -If @var{full-directory-p} is non-@code{nil}, that means the directory -listing is expected to show the full contents of a directory. You -should specify @code{t} when @var{file} is a directory and switches do -not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to -describe a directory itself as a file, rather than showing its -contents.) - -On most systems, this function works by running a directory listing -program whose name is in the variable @code{insert-directory-program}. -If @var{wildcard} is non-@code{nil}, it also runs the shell specified by -@code{shell-file-name}, to expand the wildcards. - -MS-DOS and MS-Windows systems usually lack the standard Unix program -@code{ls}, so this function emulates the standard Unix program @code{ls} -with Lisp code. - -As a technical detail, when @var{switches} contains the long -@samp{--dired} option, @code{insert-directory} treats it specially, -for the sake of dired. However, the normally equivalent short -@samp{-D} option is just passed on to @code{insert-directory-program}, -as any other option. -@end defun - -@defvar insert-directory-program -This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. It is ignored on systems -which generate the listing with Lisp code. -@end defvar - -@node Create/Delete Dirs -@section Creating and Deleting Directories -@cindex creating and deleting directories -@c Emacs 19 features - - Most Emacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with @code{delete-file}. These special functions exist to create and -delete directories. - -@findex mkdir -@deffn Command make-directory dirname &optional parents -This command creates a directory named @var{dirname}. If -@var{parents} is non-@code{nil}, as is always the case in an -interactive call, that means to create the parent directories first, -if they don't already exist. - -@code{mkdir} is an alias for this. -@end deffn - -@deffn Command delete-directory dirname -This command deletes the directory named @var{dirname}. The function -@code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} for them. If the directory contains -any files, @code{delete-directory} signals an error. - -@code{delete-directory} only follows symbolic links at the level of -parent directories. -@end deffn - -@node Magic File Names -@section Making Certain File Names ``Magic'' -@cindex magic file names - -@c Emacs 19 feature - You can implement special handling for certain file names. This is -called making those names @dfn{magic}. The principal use for this -feature is in implementing remote file names (@pxref{Remote Files,, -Remote Files, emacs, The GNU Emacs Manual}). - - To define a kind of magic file name, you must supply a regular -expression to define the class of names (all those that match the -regular expression), plus a handler that implements all the primitive -Emacs file operations for file names that do match. - - The variable @code{file-name-handler-alist} holds a list of handlers, -together with regular expressions that determine when to apply each -handler. Each element has this form: - -@example -(@var{regexp} . @var{handler}) -@end example - -@noindent -All the Emacs primitives for file access and file name transformation -check the given file name against @code{file-name-handler-alist}. If -the file name matches @var{regexp}, the primitives handle that file by -calling @var{handler}. - - The first argument given to @var{handler} is the name of the -primitive, as a symbol; the remaining arguments are the arguments that -were passed to that primitive. (The first of these arguments is most -often the file name itself.) For example, if you do this: - -@example -(file-exists-p @var{filename}) -@end example - -@noindent -and @var{filename} has handler @var{handler}, then @var{handler} is -called like this: - -@example -(funcall @var{handler} 'file-exists-p @var{filename}) -@end example - - When a function takes two or more arguments that must be file names, -it checks each of those names for a handler. For example, if you do -this: - -@example -(expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -then it checks for a handler for @var{filename} and then for a handler -for @var{dirname}. In either case, the @var{handler} is called like -this: - -@example -(funcall @var{handler} 'expand-file-name @var{filename} @var{dirname}) -@end example - -@noindent -The @var{handler} then needs to figure out whether to handle -@var{filename} or @var{dirname}. - - If the specified file name matches more than one handler, the one -whose match starts last in the file name gets precedence. This rule -is chosen so that handlers for jobs such as uncompression are handled -first, before handlers for jobs such as remote file access. - - Here are the operations that a magic file name handler gets to handle: - -@ifnottex -@noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* -@code{copy-file}, @code{delete-directory}, -@code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, -@code{file-accessible-directory-p}, -@code{file-attributes}, -@code{file-directory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirectory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-preserved-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect},@* -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents},@* -@code{load}, -@code{make-auto-save-file-name}, -@code{make-directory}, -@code{make-directory-internal}, -@code{make-symbolic-link},@* -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, @code{set-file-times}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name},@* -@code{unhandled-file-name-directory}, -@code{vc-registered}, -@code{verify-visited-file-modtime},@* -@code{write-region}. -@end ifnottex -@iftex -@noindent -@flushleft -@code{access-file}, @code{add-name-to-file}, -@code{byte-com@discretionary{}{}{}piler-base-file-name}, -@code{copy-file}, @code{delete-directory}, -@code{delete-file}, -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files}, -@code{directory-files-and-at@discretionary{}{}{}tributes}, -@code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, -@code{file-accessible-direc@discretionary{}{}{}tory-p}, -@code{file-attributes}, -@code{file-direct@discretionary{}{}{}ory-p}, -@code{file-executable-p}, @code{file-exists-p}, -@code{file-local-copy}, @code{file-remote-p}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, -@code{file-name-completion}, -@code{file-name-directory}, -@code{file-name-nondirec@discretionary{}{}{}tory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-pre@discretionary{}{}{}served-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect}, -@code{get-file-buffer}, -@code{insert-directory}, -@code{insert-file-contents}, -@code{load}, @code{make-direc@discretionary{}{}{}tory}, -@code{make-direc@discretionary{}{}{}tory-internal}, -@code{make-symbolic-link}, -@code{process-file}, -@code{rename-file}, @code{set-file-modes}, -@code{set-visited-file-modtime}, @code{shell-command}, -@code{start-file-process}, -@code{substitute-in-file-name}, -@code{unhandled-file-name-directory}, -@code{vc-regis@discretionary{}{}{}tered}, -@code{verify-visited-file-modtime}, -@code{write-region}. -@end flushleft -@end iftex - - Handlers for @code{insert-file-contents} typically need to clear the -buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the -@var{visit} argument is non-@code{nil}. This also has the effect of -unlocking the buffer if it is locked. - - The handler function must handle all of the above operations, and -possibly others to be added in the future. It need not implement all -these operations itself---when it has nothing special to do for a -certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way.'' It should always reinvoke the primitive -for an operation it does not recognize. Here's one way to do this: - -@smallexample -(defun my-file-handler (operation &rest args) - ;; @r{First check for the specific operations} - ;; @r{that we have special handling for.} - (cond ((eq operation 'insert-file-contents) @dots{}) - ((eq operation 'write-region) @dots{}) - @dots{} - ;; @r{Handle any operation we don't know about.} - (t (let ((inhibit-file-name-handlers - (cons 'my-file-handler - (and (eq inhibit-file-name-operation operation) - inhibit-file-name-handlers))) - (inhibit-file-name-operation operation)) - (apply operation args))))) -@end smallexample - - When a handler function decides to call the ordinary Emacs primitive for -the operation at hand, it needs to prevent the primitive from calling -the same handler once again, thus leading to an infinite recursion. The -example above shows how to do this, with the variables -@code{inhibit-file-name-handlers} and -@code{inhibit-file-name-operation}. Be careful to use them exactly as -shown above; the details are crucial for proper behavior in the case of -multiple handlers, and for operations that have two file names that may -each have handlers. - -@kindex safe-magic (@r{property}) - Handlers that don't really do anything special for actual access to the -file---such as the ones that implement completion of host names for -remote file names---should have a non-@code{nil} @code{safe-magic} -property. For instance, Emacs normally ``protects'' directory names -it finds in @code{PATH} from becoming magic, if they look like magic -file names, by prefixing them with @samp{/:}. But if the handler that -would be used for them has a non-@code{nil} @code{safe-magic} -property, the @samp{/:} is not added. - -@kindex operations (@r{property}) - A file name handler can have an @code{operations} property to -declare which operations it handles in a nontrivial way. If this -property has a non-@code{nil} value, it should be a list of -operations; then only those operations will call the handler. This -avoids inefficiency, but its main purpose is for autoloaded handler -functions, so that they won't be loaded except when they have real -work to do. - - Simply deferring all operations to the usual primitives does not -work. For instance, if the file name handler applies to -@code{file-exists-p}, then it must handle @code{load} itself, because -the usual @code{load} code won't work properly in that case. However, -if the handler uses the @code{operations} property to say it doesn't -handle @code{file-exists-p}, then it need not handle @code{load} -nontrivially. - -@defvar inhibit-file-name-handlers -This variable holds a list of handlers whose use is presently inhibited -for a certain operation. -@end defvar - -@defvar inhibit-file-name-operation -The operation for which certain handlers are presently inhibited. -@end defvar - -@defun find-file-name-handler file operation -This function returns the handler function for file name @var{file}, -or @code{nil} if there is none. The argument @var{operation} should -be the operation to be performed on the file---the value you will pass -to the handler as its first argument when you call it. If -@var{operation} equals @code{inhibit-file-name-operation}, or if it is -not found in the @code{operations} property of the handler, this -function returns @code{nil}. -@end defun - -@defun file-local-copy filename -This function copies file @var{filename} to an ordinary non-magic file -on the local machine, if it isn't on the local machine already. Magic -file names should handle the @code{file-local-copy} operation if they -refer to files on other machines. A magic file name that is used for -other purposes than remote file access should not handle -@code{file-local-copy}; then this function will treat the file as -local. - -If @var{filename} is local, whether magic or not, this function does -nothing and returns @code{nil}. Otherwise it returns the file name -of the local copy file. -@end defun - -@defun file-remote-p filename &optional identification connected -This function tests whether @var{filename} is a remote file. If -@var{filename} is local (not remote), the return value is @code{nil}. -If @var{filename} is indeed remote, the return value is a string that -identifies the remote system. - -This identifier string can include a host name and a user name, as -well as characters designating the method used to access the remote -system. For example, the remote identifier string for the filename -@code{/sudo::/some/file} is @code{/sudo:root@@localhost:}. - -If @code{file-remote-p} returns the same identifier for two different -filenames, that means they are stored on the same file system and can -be accessed locally with respect to each other. This means, for -example, that it is possible to start a remote process accessing both -files at the same time. Implementors of file handlers need to ensure -this principle is valid. - -@var{identification} specifies which part of the identifier shall be -returned as string. @var{identification} can be the symbol -@code{method}, @code{user} or @code{host}; any other value is handled -like @code{nil} and means to return the complete identifier string. -In the example above, the remote @code{user} identifier string would -be @code{root}. - -If @var{connected} is non-@code{nil}, this function returns @code{nil} -even if @var{filename} is remote, if Emacs has no network connection -to its host. This is useful when you want to avoid the delay of -making connections when they don't exist. -@end defun - -@defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. It -uses the directory part of @var{filename} if that is not magic. For a -magic file name, it invokes the file name handler, which therefore -decides what value to return. If @var{filename} is not accessible -from a local process, then the file name handler should indicate it by -returning @code{nil}. - -This is useful for running a subprocess; every subprocess must have a -non-magic directory to serve as its current directory, and this function -is a good way to come up with one. -@end defun - -@node Format Conversion -@section File Format Conversion - -@cindex file format conversion -@cindex encoding file formats -@cindex decoding file formats -@cindex text properties in files -@cindex saving text properties - Emacs performs several steps to convert the data in a buffer (text, -text properties, and possibly other information) to and from a -representation suitable for storing into a file. This section describes -the fundamental functions that perform this @dfn{format conversion}, -namely @code{insert-file-contents} for reading a file into a buffer, -and @code{write-region} for writing a buffer into a file. - -@menu -* Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}. -* Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}. -* Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion. -@end menu - -@node Format Conversion Overview -@subsection Overview -@noindent -The function @code{insert-file-contents}: - -@itemize -@item initially, inserts bytes from the file into the buffer; -@item decodes bytes to characters as appropriate; -@item processes formats as defined by entries in @code{format-alist}; and -@item calls functions in @code{after-insert-file-functions}. -@end itemize - -@noindent -The function @code{write-region}: - -@itemize -@item initially, calls functions in @code{write-region-annotate-functions}; -@item processes formats as defined by entries in @code{format-alist}; -@item encodes characters to bytes as appropriate; and -@item modifies the file with the bytes. -@end itemize - - This shows the symmetry of the lowest-level operations; reading and -writing handle things in opposite order. The rest of this section -describes the two facilities surrounding the three variables named -above, as well as some related functions. @ref{Coding Systems}, for -details on character encoding and decoding. - -@node Format Conversion Round-Trip -@subsection Round-Trip Specification - - The most general of the two facilities is controlled by the variable -@code{format-alist}, a list of @dfn{file format} specifications, which -describe textual representations used in files for the data in an Emacs -buffer. The descriptions for reading and writing are paired, which is -why we call this ``round-trip'' specification -(@pxref{Format Conversion Piecemeal}, for non-paired specification). - -@defvar format-alist -This list contains one format definition for each defined file format. -Each format definition is a list of this form: - -@example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve}) -@end example -@end defvar - -@cindex format definition -@noindent -Here is what the elements in a format definition mean: - -@table @var -@item name -The name of this format. - -@item doc-string -A documentation string for the format. - -@item regexp -A regular expression which is used to recognize files represented in -this format. - -@item from-fn -A shell command or function to decode data in this format (to convert -file data into the usual Emacs data representation). - -A shell command is represented as a string; Emacs runs the command as a -filter to perform the conversion. - -If @var{from-fn} is a function, it is called with two arguments, @var{begin} -and @var{end}, which specify the part of the buffer it should convert. -It should convert the text by editing it in place. Since this can -change the length of the text, @var{from-fn} should return the modified -end position. - -One responsibility of @var{from-fn} is to make sure that the beginning -of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. - -@item to-fn -A shell command or function to encode data in this format---that is, to -convert the usual Emacs data representation into this format. - -If @var{to-fn} is a string, it is a shell command; Emacs runs the -command as a filter to perform the conversion. - -If @var{to-fn} is a function, it is called with three arguments: -@var{begin} and @var{end}, which specify the part of the buffer it -should convert, and @var{buffer}, which specifies which buffer. There -are two ways it can do the conversion: - -@itemize @bullet -@item -By editing the buffer in place. In this case, @var{to-fn} should -return the end-position of the range of text, as modified. - -@item -By returning a list of annotations. This is a list of elements of the -form @code{(@var{position} . @var{string})}, where @var{position} is an -integer specifying the relative position in the text to be written, and -@var{string} is the annotation to add there. The list must be sorted in -order of position when @var{to-fn} returns it. - -When @code{write-region} actually writes the text from the buffer to the -file, it intermixes the specified annotations at the corresponding -positions. All this takes place without modifying the buffer. -@end itemize - -@item modify -A flag, @code{t} if the encoding function modifies the buffer, and -@code{nil} if it works by returning a list of annotations. - -@item mode-fn -A minor-mode function to call after visiting a file converted from this -format. The function is called with one argument, the integer 1; -that tells a minor-mode function to enable the mode. - -@item preserve -A flag, @code{t} if @code{format-write-file} should not remove this format -from @code{buffer-file-format}. -@end table - -The function @code{insert-file-contents} automatically recognizes file -formats when it reads the specified file. It checks the text of the -beginning of the file against the regular expressions of the format -definitions, and if it finds a match, it calls the decoding function for -that format. Then it checks all the known formats over again. -It keeps checking them until none of them is applicable. - -Visiting a file, with @code{find-file-noselect} or the commands that use -it, performs conversion likewise (because it calls -@code{insert-file-contents}); it also calls the mode function for each -format that it decodes. It stores a list of the format names in the -buffer-local variable @code{buffer-file-format}. - -@defvar buffer-file-format -This variable states the format of the visited file. More precisely, -this is a list of the file format names that were decoded in the course -of visiting the current buffer's file. It is always buffer-local in all -buffers. -@end defvar - -When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}, -in the order of appearance in the list. - -@deffn Command format-write-file file format &optional confirm -This command writes the current buffer contents into the file @var{file} -in a format based on @var{format}, which is a list of format names. It -constructs the actual format starting from @var{format}, then appending -any elements from the value of @code{buffer-file-format} with a non-nil -@var{preserve} flag (see above), if they are not already present in -@var{format}. It then updates @code{buffer-file-format} with this -format, making it the default for future saves. Except for the -@var{format} argument, this command is similar to @code{write-file}. In -particular, @var{confirm} has the same meaning and interactive treatment -as the corresponding argument to @code{write-file}. @xref{Definition of -write-file}. -@end deffn - -@deffn Command format-find-file file format -This command finds the file @var{file}, converting it according to -format @var{format}. It also makes @var{format} the default if the -buffer is saved later. - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@deffn Command format-insert-file file format &optional beg end -This command inserts the contents of file @var{file}, converting it -according to format @var{format}. If @var{beg} and @var{end} are -non-@code{nil}, they specify which part of the file to read, as in -@code{insert-file-contents} (@pxref{Reading from Files}). - -The return value is like what @code{insert-file-contents} returns: a -list of the absolute file name and the length of the data inserted -(after conversion). - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end deffn - -@defvar buffer-auto-save-file-format -This variable specifies the format to use for auto-saving. Its value is -a list of format names, just like the value of -@code{buffer-file-format}; however, it is used instead of -@code{buffer-file-format} for writing auto-save files. If the value -is @code{t}, the default, auto-saving uses the same format as a -regular save in the same buffer. This variable is always buffer-local -in all buffers. -@end defvar - -@node Format Conversion Piecemeal -@subsection Piecemeal Specification - - In contrast to the round-trip specification described in the previous -subsection (@pxref{Format Conversion Round-Trip}), you can use the variables -@code{after-insert-file-functions} and @code{write-region-annotate-functions} -to separately control the respective reading and writing conversions. - - Conversion starts with one representation and produces another -representation. When there is only one conversion to do, there is no -conflict about what to start with. However, when there are multiple -conversions involved, conflict may arise when two conversions need to -start with the same data. - - This situation is best understood in the context of converting text -properties during @code{write-region}. For example, the character at -position 42 in a buffer is @samp{X} with a text property @code{foo}. If -the conversion for @code{foo} is done by inserting into the buffer, say, -@samp{FOO:}, then that changes the character at position 42 from -@samp{X} to @samp{F}. The next conversion will start with the wrong -data straight away. - - To avoid conflict, cooperative conversions do not modify the buffer, -but instead specify @dfn{annotations}, a list of elements of the form -@code{(@var{position} . @var{string})}, sorted in order of increasing -@var{position}. - - If there is more than one conversion, @code{write-region} merges their -annotations destructively into one sorted list. Later, when the text -from the buffer is actually written to the file, it intermixes the -specified annotations at the corresponding positions. All this takes -place without modifying the buffer. - -@c ??? What about ``overriding'' conversions like those allowed -@c ??? for `write-region-annotate-functions', below? --ttn - - In contrast, when reading, the annotations intermixed with the text -are handled immediately. @code{insert-file-contents} sets point to -the beginning of some text to be converted, then calls the conversion -functions with the length of that text. These functions should always -return with point at the beginning of the inserted text. This -approach makes sense for reading because annotations removed by the -first converter can't be mistakenly processed by a later converter. -Each conversion function should scan for the annotations it -recognizes, remove the annotation, modify the buffer text (to set a -text property, for example), and return the updated length of the -text, as it stands after those changes. The value returned by one -function becomes the argument to the next function. - -@defvar write-region-annotate-functions -A list of functions for @code{write-region} to call. Each function in -the list is called with two arguments: the start and end of the region -to be written. These functions should not alter the contents of the -buffer. Instead, they should return annotations. - -As a special case, a function may return with a different buffer -current. Emacs takes this to mean that the current buffer contains -altered text to be output. It therefore changes the @var{start} and -@var{end} arguments of the @code{write-region} call, giving them the -values of @code{point-min} and @code{point-max} in the new buffer, -respectively. It also discards all previous annotations, because they -should have been dealt with by this function. -@end defvar - -@defvar write-region-post-annotation-function -The value of this variable, if non-@code{nil}, should be a function. -This function is called, with no arguments, after @code{write-region} -has completed. - -If any function in @code{write-region-annotate-functions} returns with -a different buffer current, Emacs calls -@code{write-region-post-annotation-function} more than once. Emacs -calls it with the last buffer that was current, and again with the -buffer before that, and so on back to the original buffer. - -Thus, a function in @code{write-region-annotate-functions} can create -a buffer, give this variable the local value of @code{kill-buffer} in -that buffer, set up the buffer with altered text, and make the buffer -current. The buffer will be killed after @code{write-region} is done. -@end defvar - -@defvar after-insert-file-functions -Each function in this list is called by @code{insert-file-contents} -with one argument, the number of characters inserted, and with point -at the beginning of the inserted text. Each function should leave -point unchanged, and return the new character count describing the -inserted text as modified by the function. -@c ??? The docstring mentions a handler from `file-name-handler-alist' -@c "intercepting" `insert-file-contents'. Hmmm. --ttn -@end defvar - - We invite users to write Lisp programs to store and retrieve text -properties in files, using these hooks, and thus to experiment with -various data formats and find good ones. Eventually we hope users -will produce good, general extensions we can install in Emacs. - - We suggest not trying to handle arbitrary Lisp objects as text property -names or values---because a program that general is probably difficult -to write, and slow. Instead, choose a set of possible data types that -are reasonably flexible, and not too hard to encode. - -@ignore - arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c -@end ignore diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi deleted file mode 100644 index 87127c9cd66..00000000000 --- a/doc/lispref/frames.texi +++ /dev/null @@ -1,2406 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/frames -@node Frames, Positions, Windows, Top -@chapter Frames -@cindex frame - - A @dfn{frame} is a screen object that contains one or more Emacs -windows (@pxref{Windows}). It is the kind of object called a -``window'' in the terminology of graphical environments; but we can't -call it a ``window'' here, because Emacs uses that word in a different -way. In Emacs Lisp, a @dfn{frame object} is a Lisp object that -represents a frame on the screen. @xref{Frame Type}. - - A frame initially contains a single main window and/or a minibuffer -window; you can subdivide the main window vertically or horizontally -into smaller windows. @xref{Splitting Windows}. - -@cindex terminal - A @dfn{terminal} is a display device capable of displaying one or -more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp -object that represents a terminal. @xref{Terminal Type}. - -@cindex terminal frame -@cindex window frame - There are two classes of terminals: text-only terminals and -graphical terminals. Text-only terminals are non-graphics-capable -display devices, including ``terminal emulators'' such as xterm. On -text-only terminals, each frame occupies the entire terminal screen; -although you can create additional frames and switch between them, -only one frame can be shown at any given time. We refer to frames on -text-only terminals as @dfn{terminal frames}. Graphical terminals, on -the other hand, are graphics-capable windowing systems, such as the X -Window System. On a graphical terminal, Emacs can display multiple -frames simultaneously. We refer to such frames as @dfn{window -frames}. - - On GNU and Unix systems, you can create additional frames on any -available terminal, within a single Emacs session, regardless of -whether Emacs was started on a text-only or graphical terminal. Emacs -can display on both graphical and text-only terminals simultaneously. -This comes in handy, for instance, when you connect to the same -session from several remote locations. @xref{Multiple Terminals}. - -@defun framep object -This predicate returns a non-@code{nil} value if @var{object} is a -frame, and @code{nil} otherwise. For a frame, the value indicates which -kind of display the frame uses: - -@table @code -@item x -The frame is displayed in an X window. -@item t -A terminal frame on a character display. -@item w32 -The frame is displayed on MS-Windows 9X/NT. -@item ns -The frame is displayed on a GNUstep or Macintosh Cocoa display. -@item pc -The frame is displayed on an MS-DOS terminal. -@end table -@end defun - -@defun frame-terminal &optional frame -This function returns the terminal object that displays @var{frame}. -If @var{frame} is @code{nil} or unspecified, it defaults to the -selected frame. -@end defun - -@defun terminal-live-p object -This predicate returns a non-@code{nil} value if @var{object} is a -terminal that is alive (i.e.@: was not deleted), and @code{nil} -otherwise. For live terminals, the return value indicates what kind -of frames are displayed on that terminal; the list of possible values -is the same as for @code{framep} above. -@end defun - -@menu -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections:: Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text-only terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. -@end menu - -@node Creating Frames -@section Creating Frames - -To create a new frame, call the function @code{make-frame}. - -@defun make-frame &optional alist -This function creates and returns a new frame, displaying the current -buffer. - -The @var{alist} argument is an alist that specifies frame parameters -for the new frame. @xref{Frame Parameters}. If you specify the -@code{terminal} parameter in @var{alist}, the new frame is created on -that terminal. Otherwise, if you specify the @code{window-system} -frame parameter in @var{alist}, that determines whether the frame -should be displayed on a text-only or graphical terminal. -@xref{Window Systems}. If neither is specified, the new frame is -created in the same terminal as the selected frame. - -Any parameters not mentioned in @var{alist} default to the values in -the alist @code{default-frame-alist} (@pxref{Initial Parameters}); -parameters not specified there default from the X resources or its -equivalent on your operating system (@pxref{X Resources,, X Resources, -emacs, The GNU Emacs Manual}). After the frame is created, Emacs -applies any parameters listed in @code{frame-inherited-parameters} -(see below) and not present in the argument, taking the values from -the frame that was selected when @code{make-frame} was called. - -This function itself does not make the new frame the selected frame. -@xref{Input Focus}. The previously selected frame remains selected. -On graphical terminals, however, the windowing system may select the -new frame for its own reasons. -@end defun - -@defvar before-make-frame-hook -A normal hook run by @code{make-frame} before it creates the frame. -@end defvar - -@defvar after-make-frame-functions -An abnormal hook run by @code{make-frame} after it creates the frame. -Each function in @code{after-make-frame-functions} receives one argument, the -frame just created. -@end defvar - -@defvar frame-inherited-parameters -This variable specifies the list of frame parameters that a newly -created frame inherits from the currently selected frame. For each -parameter (a symbol) that is an element in the list and is not present -in the argument to @code{make-frame}, the function sets the value of -that parameter in the created frame to its value in the selected -frame. -@end defvar - -@node Multiple Terminals -@section Multiple Terminals -@cindex multiple terminals -@cindex multi-tty -@cindex multiple X displays -@cindex displays, multiple - - Emacs represents each terminal, whether graphical or text-only, as a -@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and -Unix systems, Emacs can use multiple terminals simultaneously in each -session. On other systems, it can only use a single terminal. Each -terminal object has the following attributes: - -@itemize @bullet -@item -The name of the device used by the terminal (e.g., @samp{:0.0} or -@file{/dev/tty}). - -@item -The terminal and keyboard coding systems used on the terminal. -@xref{Terminal I/O Encoding}. - -@item -The kind of display associated with the terminal. This is the symbol -returned by the function @code{terminal-live-p} (i.e., @code{x}, -@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. - -@item -A list of terminal parameters. @xref{Terminal Parameters}. -@end itemize - - There is no primitive for creating terminal objects. Emacs creates -them as needed, such as when you call @code{make-frame-on-display} -(which is described below). - -@defun terminal-name &optional terminal -This function returns the file name of the device used by -@var{terminal}. If @var{terminal} is omitted or @code{nil}, it -defaults to the selected frame's terminal. @var{terminal} can also be -a frame, meaning that frame's terminal. -@end defun - -@defun terminal-list -This function returns a list of all terminal objects currently in use. -@end defun - -@defun get-device-terminal device -This function returns a terminal whose device name is given by -@var{device}. If @var{device} is a string, it can be either the file -name of a terminal device, or the name of an X display of the form -@samp{@var{host}:@var{server}.@var{screen}}. If @var{device} is a -frame, this function returns that frame's terminal; @code{nil} means -the selected frame. Finally, if @var{device} is a terminal object -that represents a live terminal, that terminal is returned. The -function signals an error if its argument is none of the above. -@end defun - -@defun delete-terminal &optional terminal force -This function deletes all frames on @var{terminal} and frees the -resources used by it. It runs the abnormal hook -@code{delete-terminal-functions}, passing @var{terminal} as the -argument to each function. - -If @var{terminal} is omitted or @code{nil}, it defaults to the -selected frame's terminal. @var{terminal} can also be a frame, -meaning that frame's terminal. - -Normally, this function signals an error if you attempt to delete the -sole active terminal, but if @var{force} is non-@code{nil}, you are -allowed to do so. Emacs automatically calls this function when the -last frame on a terminal is deleted (@pxref{Deleting Frames}). -@end defun - -@defvar delete-terminal-functions -An abnormal hook run by @code{delete-terminal}. Each function -receives one argument, the @var{terminal} argument passed to -@code{delete-terminal}. Due to technical details, the functions may -be called either just before the terminal is deleted, or just -afterwards. -@end defvar - -@cindex terminal-local variables - A few Lisp variables are @dfn{terminal-local}; that is, they have a -separate binding for each terminal. The binding in effect at any time -is the one for the terminal that the currently selected frame belongs -to. These variables include @code{default-minibuffer-frame}, -@code{defining-kbd-macro}, @code{last-kbd-macro}, and -@code{system-key-alist}. They are always terminal-local, and can -never be buffer-local (@pxref{Buffer-Local Variables}). - - On GNU and Unix systems, each X display is a separate graphical -terminal. When Emacs is started from within the X window system, it -uses the X display chosen with the @code{DISPLAY} environment -variable, or with the @samp{--display} option. @xref{Initial -Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X -displays via the command @code{make-frame-on-display}. Each X display -has its own selected frame and its own minibuffer windows; however, -only one of those frames is ``@emph{the} selected frame'' at any given -moment (@pxref{Input Focus}). Emacs can even connect to other -text-only terminals, by interacting with the @command{emacsclient} -program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - - A single X server can handle more than one display. Each X display -has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}. -The first two parts, @var{host} and @var{server}, identify the X -server; the third part, @var{screen}, identifies a screen number on -that X server. When you use two or more screens belonging to one -server, Emacs knows by the similarity in their names that they share a -single keyboard. - - On some ``multi-monitor'' setups, a single X display outputs to more -than one monitor. Currently, there is no way for Emacs to distinguish -between the different physical monitors. - -@deffn Command make-frame-on-display display &optional parameters -This function creates and returns a new frame on @var{display}, taking -the other frame parameters from the alist @var{parameters}. -@var{display} should be the name of an X display (a string). - -Before creating the frame, this function ensures that Emacs is ``set -up'' to display graphics. For instance, if Emacs has not processed X -resources (e.g., if it was started on a text-only terminal), it does -so at this time. In all other respects, this function behaves like -@code{make-frame} (@pxref{Creating Frames}). -@end deffn - -@defun x-display-list -This function returns a list that indicates which X displays Emacs has -a connection to. The elements of the list are strings, and each one -is a display name. -@end defun - -@defun x-open-connection display &optional xrm-string must-succeed -This function opens a connection to the X display @var{display}, -without creating a frame on that display. Normally, Emacs Lisp -programs need not call this function, as @code{make-frame-on-display} -calls it automatically. The only reason for calling it is to check -whether communication can be established with a given X display. - -The optional argument @var{xrm-string}, if not @code{nil}, is a string -of resource names and values, in the same format used in the -@file{.Xresources} file. @xref{X Resources,, X Resources, emacs, The -GNU Emacs Manual}. These values apply to all Emacs frames created on -this display, overriding the resource values recorded in the X server. -Here's an example of what this string might look like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -If @var{must-succeed} is non-@code{nil}, failure to open the connection -terminates Emacs. Otherwise, it is an ordinary Lisp error. -@end defun - -@defun x-close-connection display -This function closes the connection to display @var{display}. Before -you can do this, you must first delete all the frames that were open -on that display (@pxref{Deleting Frames}). -@end defun - -@node Frame Parameters -@section Frame Parameters -@cindex frame parameters - - A frame has many parameters that control its appearance and behavior. -Just what parameters a frame has depends on what display mechanism it -uses. - - Frame parameters exist mostly for the sake of window systems. A -terminal frame has a few parameters, mostly for compatibility's sake; -only the @code{height}, @code{width}, @code{name}, @code{title}, -@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} -parameters do something special. If the terminal supports colors, the -parameters @code{foreground-color}, @code{background-color}, -@code{background-mode} and @code{display-type} are also meaningful. -If the terminal supports frame transparency, the parameter -@code{alpha} is also meaningful. - - You can use frame parameters to define frame-local bindings for -variables. @xref{Frame-Local Variables}. - -@menu -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. -@end menu - -@node Parameter Access -@subsection Access to Frame Parameters - -These functions let you read and change the parameter values of a -frame. - -@defun frame-parameter frame parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the -selected frame's parameter. If @var{frame} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun frame-parameters &optional frame -The function @code{frame-parameters} returns an alist listing all the -parameters of @var{frame} and their values. If @var{frame} is -@code{nil} or omitted, this returns the selected frame's parameters -@end defun - -@defun modify-frame-parameters frame alist -This function alters the parameters of frame @var{frame} based on the -elements of @var{alist}. Each element of @var{alist} has the form -@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a -parameter. If you don't mention a parameter in @var{alist}, its value -doesn't change. If @var{frame} is @code{nil}, it defaults to the selected -frame. - -You can use this function to define frame-local bindings for -variables, see @ref{Frame-Local Variables}. -@end defun - -@defun set-frame-parameter frame parm value -This function sets the frame parameter @var{parm} to the specified -@var{value}. If @var{frame} is @code{nil}, it defaults to the -selected frame. -@end defun - -@defun modify-all-frames-parameters alist -This function alters the frame parameters of all existing frames -according to @var{alist}, then modifies @code{default-frame-alist} -(and, if necessary, @code{initial-frame-alist}) to apply the same -parameter values to frames that will be created henceforth. -@end defun - -@node Initial Parameters -@subsection Initial Frame Parameters - -You can specify the parameters for the initial startup frame -by setting @code{initial-frame-alist} in your init file (@pxref{Init File}). - -@defopt initial-frame-alist -This variable's value is an alist of parameter values used when creating -the initial window frame. You can set this variable to specify the -appearance of the initial frame without altering subsequent frames. -Each element has the form: - -@example -(@var{parameter} . @var{value}) -@end example - -Emacs creates the initial frame before it reads your init -file. After reading that file, Emacs checks @code{initial-frame-alist}, -and applies the parameter settings in the altered value to the already -created initial frame. - -If these settings affect the frame geometry and appearance, you'll see -the frame appear with the wrong ones and then change to the specified -ones. If that bothers you, you can specify the same geometry and -appearance with X resources; those do take effect before the frame is -created. @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -X resource settings typically apply to all frames. If you want to -specify some X resources solely for the sake of the initial frame, and -you don't want them to apply to subsequent frames, here's how to achieve -this. Specify parameters in @code{default-frame-alist} to override the -X resources for subsequent frames; then, to prevent these from affecting -the initial frame, specify the same parameters in -@code{initial-frame-alist} with values that match the X resources. -@end defopt - -If these parameters specify a separate minibuffer-only frame with -@code{(minibuffer . nil)}, and you have not created one, Emacs creates -one for you. - -@defopt minibuffer-frame-alist -This variable's value is an alist of parameter values used when -creating an initial minibuffer-only frame. This is the -minibuffer-only frame that Emacs creates if @code{initial-frame-alist} -specifies a frame with no minibuffer. -@end defopt - -@defopt default-frame-alist -This is an alist specifying default values of frame parameters for all -Emacs frames---the first frame, and subsequent frames. When using the X -Window System, you can get the same results by means of X resources -in many cases. - -Setting this variable does not affect existing frames. -@end defopt - -Functions that display a buffer in a separate frame can override the -default parameters by supplying their own parameters. @xref{Definition -of special-display-frame-alist}. - -If you use options that specify window appearance when you invoke Emacs, -they take effect by adding elements to @code{default-frame-alist}. One -exception is @samp{-geometry}, which adds the specified position to -@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command -Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. - -@node Window Frame Parameters -@subsection Window Frame Parameters - - Just what parameters a frame has depends on what display mechanism -it uses. This section describes the parameters that have special -meanings on some or all kinds of terminals. Of these, @code{name}, -@code{title}, @code{height}, @code{width}, @code{buffer-list} and -@code{buffer-predicate} provide meaningful information in terminal -frames, and @code{tty-color-mode} is meaningful @emph{only} in -terminal frames. - -@menu -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. -@end menu - -@node Basic Parameters -@subsubsection Basic Parameters - - These frame parameters give the most basic information about the -frame. @code{title} and @code{name} are meaningful on all terminals. - -@table @code -@item display -The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@code{DISPLAY} environment variable. - -@item display-type -This parameter describes the range of possible colors that can be used -in this frame. Its value is @code{color}, @code{grayscale} or -@code{mono}. - -@item title -If a frame has a non-@code{nil} title, it appears in the window -system's title bar at the top of the frame, and also in the mode line -of windows in that frame if @code{mode-line-frame-identification} uses -@samp{%F} (@pxref{%-Constructs}). This is normally the case when -Emacs is not using a window system, and can only display one frame at -a time. @xref{Frame Titles}. - -@item name -The name of the frame. The frame name serves as a default for the frame -title, if the @code{title} parameter is unspecified or @code{nil}. If -you don't specify a name, Emacs sets the frame name automatically -(@pxref{Frame Titles}). - -If you specify the frame name explicitly when you create the frame, the -name is also used (instead of the name of the Emacs executable) when -looking up X resources for the frame. -@end table - -@node Position Parameters -@subsubsection Position Parameters - - Position parameters' values are normally measured in pixels, but on -text-only terminals they count characters or lines instead. - -@table @code -@item left -The position, in pixels, of the left (or right) edge of the frame with -respect to the left (or right) edge of the screen. The value may be: - -@table @asis -@item an integer -A positive integer relates the left edge of the frame to the left edge -of the screen. A negative integer relates the right frame edge to the -right screen edge. - -@item @code{(+ @var{pos})} -This specifies the position of the left frame edge relative to the left -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. - -@item @code{(- @var{pos})} -This specifies the position of the right frame edge relative to the right -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen. -@end table - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@item top -The screen position of the top (or bottom) edge, in pixels, with respect -to the top (or bottom) edge of the screen. It works just like -@code{left}, except vertically instead of horizontally. - -@item icon-left -The screen position of the left edge @emph{of the frame's icon}, in -pixels, counting from the left edge of the screen. This takes effect if -and when the frame is iconified. - -If you specify a value for this parameter, then you must also specify -a value for @code{icon-top} and vice versa. The window manager may -ignore these two parameters. - -@item icon-top -The screen position of the top edge @emph{of the frame's icon}, in -pixels, counting from the top edge of the screen. This takes effect if -and when the frame is iconified. - -@item user-position -When you create a frame and specify its screen position with the -@code{left} and @code{top} parameters, use this parameter to say whether -the specified position was user-specified (explicitly requested in some -way by a human user) or merely program-specified (chosen by a program). -A non-@code{nil} value says the position was user-specified. - -Window managers generally heed user-specified positions, and some heed -program-specified positions too. But many ignore program-specified -positions, placing the window in a default fashion or letting the user -place it with the mouse. Some window managers, including @code{twm}, -let the user specify whether to obey program-specified positions or -ignore them. - -When you call @code{make-frame}, you should specify a non-@code{nil} -value for this parameter if the values of the @code{left} and @code{top} -parameters represent the user's stated preference; otherwise, use -@code{nil}. -@end table - -@node Size Parameters -@subsubsection Size Parameters - - Size parameters' values are normally measured in pixels, but on -text-only terminals they count characters or lines instead. - -@table @code -@item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) - -@item width -The width of the frame contents, in characters. (To get the width in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) - -@item user-size -This does for the size parameters @code{height} and @code{width} what -the @code{user-position} parameter (see above) does for the position -parameters @code{top} and @code{left}. - -@item fullscreen -Specify that width, height or both shall be set to the size of the screen. -The value @code{fullwidth} specifies that width shall be the size of the -screen. The value @code{fullheight} specifies that height shall be the -size of the screen. The value @code{fullboth} specifies that both the -width and the height shall be set to the size of the screen. -@end table - -@node Layout Parameters -@subsubsection Layout Parameters - - These frame parameters enable or disable various parts of the -frame, or control their sizes. - -@table @code -@item border-width -The width in pixels of the frame's border. - -@item internal-border-width -The distance in pixels between text (or fringe) and the frame's border. - -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling, and which side -of the frame they should be on. The possible values are @code{left}, -@code{right}, and @code{nil} for no scroll bars. - -@ignore -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). Horizontal scroll bars are not currently -implemented. -@end ignore - -@item scroll-bar-width -The width of vertical scroll bars, in pixels, or @code{nil} meaning to -use the default width. - -@item left-fringe -@itemx right-fringe -The default width of the left and right fringes of windows in this -frame (@pxref{Fringes}). If either of these is zero, that effectively -removes the corresponding fringe. A value of @code{nil} stands for -the standard fringe width, which is the width needed to display the -fringe bitmaps. - -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame may be -larger than the specified values. The extra width needed to reach an -acceptable total is distributed evenly between the left and right -fringe. However, you can force one fringe or the other to a precise -width by specifying that width as a negative integer. If both widths are -negative, only the left fringe gets the specified width. - -@item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1. A value of @code{nil} means don't display a -menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one -menu bar line; they treat larger values as 1.) - -@item tool-bar-lines -The number of lines to use for the tool bar. A value of @code{nil} -means don't display a tool bar. (GTK and Nextstep allow at most one -tool bar line; they treat larger values as 1.) - -@item line-spacing -Additional space to leave below each text line, in pixels (a positive -integer). @xref{Line Height}, for more information. -@end table - -@node Buffer Parameters -@subsubsection Buffer Parameters - - These frame parameters, meaningful on all kinds of terminals, deal -with which buffers have been, or should, be displayed in the frame. - -@table @code -@item minibuffer -Whether this frame has its own minibuffer. The value @code{t} means -yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer. If the value is a minibuffer window (in some other -frame), the frame uses that minibuffer. - -This frame parameter takes effect when the frame is created, and can -not be changed afterwards. - -@item buffer-predicate -The buffer-predicate function for this frame. The function -@code{other-buffer} uses this predicate (from the selected frame) to -decide which buffers it should consider, if the predicate is not -@code{nil}. It calls the predicate with one argument, a buffer, once for -each buffer; if the predicate returns a non-@code{nil} value, it -considers that buffer. - -@item buffer-list -A list of buffers that have been selected in this frame, -ordered most-recently-selected first. - -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. -@end table - -@node Management Parameters -@subsubsection Window Management Parameters -@cindex window manager, and frame parameters - - These frame parameters, meaningful only on window system displays, -interact with the window manager. - -@table @code -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. - -@item auto-raise -Whether selecting the frame raises it (non-@code{nil} means yes). - -@item auto-lower -Whether deselecting the frame lowers it (non-@code{nil} means yes). - -@item icon-type -The type of icon to use for this frame when it is iconified. If the -value is a string, that specifies a file containing a bitmap to use. -Any other non-@code{nil} value specifies the default bitmap icon (a -picture of a gnu); @code{nil} specifies a text icon. - -@item icon-name -The name to use in the icon for this frame, when and if the icon -appears. If this is @code{nil}, the frame's title is used. - -@item window-id -The number of the window-system window used by the frame -to contain the actual Emacs windows. - -@item outer-window-id -The number of the outermost window-system window used for the whole frame. - -@item wait-for-wm -If non-@code{nil}, tell Xt to wait for the window manager to confirm -geometry changes. Some window managers, including versions of Fvwm2 -and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to -prevent hanging with those window managers. - -@ignore -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end ignore -@end table - -@node Cursor Parameters -@subsubsection Cursor Parameters - - This frame parameter controls the way the cursor looks. - -@table @code -@item cursor-type -How to display the cursor. Legitimate values are: - -@table @code -@item box -Display a filled box. (This is the default.) -@item hollow -Display a hollow box. -@item nil -Don't display a cursor. -@item bar -Display a vertical bar between characters. -@item (bar . @var{width}) -Display a vertical bar @var{width} pixels wide between characters. -@item hbar -Display a horizontal bar. -@item (hbar . @var{height}) -Display a horizontal bar @var{height} pixels high. -@end table -@end table - -@vindex cursor-type -The buffer-local variable @code{cursor-type} overrides the value of -the @code{cursor-type} frame parameter, but if it is @code{t}, that -means to use the cursor specified for the frame. - -@defopt blink-cursor-alist -This variable specifies how to blink the cursor. Each element has the -form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor -type equals @var{on-state} (comparing using @code{equal}), the -corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off.'' Both @var{on-state} and @var{off-state} -should be suitable values for the @code{cursor-type} frame parameter. - -There are various defaults for how to blink each type of cursor, if -the type is not mentioned as an @var{on-state} here. Changes in this -variable do not take effect immediately, only when you specify the -@code{cursor-type} frame parameter. -@end defopt - -@defopt cursor-in-non-selected-windows -This variable controls how the cursor looks in a window that is not -selected. It supports the same values as the @code{cursor-type} frame -parameter; also, @code{nil} means don't display a cursor in -nonselected windows, and @code{t} (the default) means use a standard -modificatoin of the usual cursor type (solid box becomes hollow box, -and bar becomes a narrower bar). -@end defopt - -@node Font and Color Parameters -@subsubsection Font and Color Parameters - - These frame parameters control the use of fonts and colors. - -@table @code -@item font-backend -A list of symbols, specifying the @dfn{font backends} to use for -drawing fonts in the frame, in order of priority. On X, there are -currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On other systems, there -is only one available font backend, so it does not make sense to -modify this frame parameter. - -@item background-mode -This parameter is either @code{dark} or @code{light}, according -to whether the background color is a light one or a dark one. - -@item tty-color-mode -@cindex standard colors for character terminals -This parameter overrides the terminal's color support as given by the -system's terminal capabilities database in that this parameter's value -specifies the color mode to use in terminal frames. The value can be -either a symbol or a number. A number specifies the number of colors -to use (and, indirectly, what commands to issue to produce each -color). For example, @code{(tty-color-mode . 8)} specifies use of the -ANSI escape sequences for 8 standard text colors. A value of -1 turns -off color support. - -If the parameter's value is a symbol, it specifies a number through -the value of @code{tty-color-mode-alist}, and the associated number is -used instead. - -@item screen-gamma -@cindex gamma correction -If this is a number, Emacs performs ``gamma correction'' which adjusts -the brightness of all colors. The value should be the screen gamma of -your display, a floating point number. - -Usual PC monitors have a screen gamma of 2.2, so color values in -Emacs, and in X windows generally, are calibrated to display properly -on a monitor with that gamma value. If you specify 2.2 for -@code{screen-gamma}, that means no correction is needed. Other values -request correction, designed to make the corrected colors appear on -your screen the way they would have appeared without correction on an -ordinary monitor with a gamma value of 2.2. - -If your monitor displays colors too light, you should specify a -@code{screen-gamma} value smaller than 2.2. This requests correction -that makes colors darker. A screen gamma value of 1.5 may give good -results for LCD color displays. - -@item alpha -@cindex opacity, frame -@cindex transparency, frame -@vindex frame-alpha-lower-limit -This parameter specifies the opacity of the frame, on graphical -displays that support variable opacity. It should be an integer -between 0 and 100, where 0 means completely transparent and 100 means -completely opaque. It can also have a @code{nil} value, which tells -Emacs not to set the frame opacity (leaving it to the window manager). - -To prevent the frame from disappearing completely from view, the -variable @code{frame-alpha-lower-limit} defines a lower opacity limit. -If the value of the frame parameter is less than the value of this -variable, Emacs uses the latter. By default, -@code{frame-alpha-lower-limit} is 20. - -The @code{alpha} frame parameter can also be a cons cell -@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the -opacity of the frame when it is selected, and @samp{inactive} is the -opactity when it is not selected. -@end table - -The following frame parameters are semi-obsolete in that they are -automatically equivalent to particular face attributes of particular -faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}): - -@table @code -@item font -The name of the font for displaying text in the frame. This is a -string, either a valid font name for your system or the name of an Emacs -fontset (@pxref{Fontsets}). It is equivalent to the @code{font} -attribute of the @code{default} face. - -@item foreground-color -The color to use for the image of a character. It is equivalent to -the @code{:foreground} attribute of the @code{default} face. - -@item background-color -The color to use for the background of characters. It is equivalent to -the @code{:background} attribute of the @code{default} face. - -@item mouse-color -The color for the mouse pointer. It is equivalent to the @code{:background} -attribute of the @code{mouse} face. - -@item cursor-color -The color for the cursor that shows point. It is equivalent to the -@code{:background} attribute of the @code{cursor} face. - -@item border-color -The color for the border of the frame. It is equivalent to the -@code{:background} attribute of the @code{border} face. - -@item scroll-bar-foreground -If non-@code{nil}, the color for the foreground of scroll bars. It is -equivalent to the @code{:foreground} attribute of the -@code{scroll-bar} face. - -@item scroll-bar-background -If non-@code{nil}, the color for the background of scroll bars. It is -equivalent to the @code{:background} attribute of the -@code{scroll-bar} face. -@end table - -@node Size and Position -@subsection Frame Size And Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions. -(For the precise meaning of ``selected frame'' used by these functions, -see @ref{Input Focus}.) - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen. - -Negative parameter values position the bottom edge of the window up from -the bottom edge of the screen, or the right window edge to the left of -the right edge of the screen. It would probably be better if the values -were always counted from the left and top, so that negative arguments -would position the frame partly off the top or left edge of the screen, -but it seems inadvisable to change that now. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -lines and columns. If you don't supply @var{frame}, they use the -selected frame. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of the main display area -of @var{frame}, measured in pixels. If you don't supply @var{frame}, -they use the selected frame. - -These values include the internal borders, and windows' scroll bars -and fringes (which belong to individual windows, not to the frame -itself), but do not include menu bars or tool bars (except when using -X without an X toolkit). -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defun set-frame-size frame cols rows -This function sets the size of @var{frame}, measured in characters; -@var{cols} and @var{rows} specify the new width and height. - -To set the size based on values measured in pixels, use -@code{frame-char-height} and @code{frame-char-width} to convert -them to units of characters. -@end defun - -@defun set-frame-height frame lines &optional pretend -This function resizes @var{frame} to a height of @var{lines} lines. The -sizes of existing windows in @var{frame} are altered proportionally to -fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful for a terminal frame. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on a -terminal frame. -@end defun - -@defun set-frame-width frame width &optional pretend -This function sets the width of @var{frame}, measured in characters. -The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. -@end defun - -@findex set-screen-height -@findex set-screen-width - The older functions @code{set-screen-height} and -@code{set-screen-width} were used to specify the height and width of the -screen, in Emacs versions that did not support multiple frames. They -are semi-obsolete, but still work; they apply to the selected frame. - -@node Geometry -@subsection Geometry - - Here's how to examine the data in an X-style window geometry -specification: - -@defun x-parse-geometry geom -@cindex geometry specification -The function @code{x-parse-geometry} converts a standard X window -geometry string to an alist that you can use as part of the argument to -@code{make-frame}. - -The alist describes which parameters were specified in @var{geom}, and -gives the values specified for them. Each element looks like -@code{(@var{parameter} . @var{value})}. The possible @var{parameter} -values are @code{left}, @code{top}, @code{width}, and @code{height}. - -For the size parameters, the value must be an integer. The position -parameter names @code{left} and @code{top} are not totally accurate, -because some values indicate the position of the right or bottom edges -instead. The @var{value} possibilities for the position parameters are: -an integer, a list @code{(+ @var{pos})}, or a list @code{(- @var{pos})}; -as previously described (@pxref{Position Parameters}). - -Here is an example: - -@example -(x-parse-geometry "35x70+0-0") - @result{} ((height . 70) (width . 35) - (top - 0) (left . 0)) -@end example -@end defun - -@node Terminal Parameters -@section Terminal Parameters -@cindex terminal parameters - - Each terminal has a list of associated parameters. These -@dfn{terminal parameters} are mostly a convenient way of storage for -terminal-local variables, but some terminal parameters have a special -meaning. - - This section describes functions to read and change the parameter values -of a terminal. They all accept as their argument either a terminal or -a frame; the latter means use that frame's terminal. An argument of -@code{nil} means the selected frame's terminal. - -@defun terminal-parameters &optional terminal -This function returns an alist listing all the parameters of -@var{terminal} and their values. -@end defun - -@defun terminal-parameter terminal parameter -This function returns the value of the parameter @var{parameter} (a -symbol) of @var{terminal}. If @var{terminal} has no setting for -@var{parameter}, this function returns @code{nil}. -@end defun - -@defun set-terminal-parameter terminal parameter value -This function sets the parameter @var{parm} of @var{terminal} to the -specified @var{value}, and returns the previous value of that -parameter. -@end defun - -Here's a list of a few terminal parameters that have a special -meaning: - -@table @code -@item background-mode -The classification of the terminal's background color, either -@code{light} or @code{dark}. -@item normal-erase-is-backspace -Value is either 1 or 0, depending on whether -@code{normal-erase-is-backspace-mode} is turned on or off on this -terminal. @xref{DEL Does Not Delete,,, emacs, The Emacs Manual}. -@item terminal-initted -After the terminal is initialized, this is set to the -terminal-specific initialization function. -@end table - -@node Frame Titles -@section Frame Titles -@cindex frame title - - Every frame has a @code{name} parameter; this serves as the default -for the frame title which window systems typically display at the top of -the frame. You can specify a name explicitly by setting the @code{name} -frame property. - - Normally you don't specify the name explicitly, and Emacs computes the -frame name automatically based on a template stored in the variable -@code{frame-title-format}. Emacs recomputes the name each time the -frame is redisplayed. - -@defvar frame-title-format -This variable specifies how to compute a name for a frame when you have -not explicitly specified one. The variable's value is actually a mode -line construct, just like @code{mode-line-format}, except that the -@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line -Data}. -@end defvar - -@defvar icon-title-format -This variable specifies how to compute the name for an iconified frame, -when you have not explicitly specified the frame title. This title -appears in the icon itself. -@end defvar - -@defvar multiple-frames -This variable is set automatically by Emacs. Its value is @code{t} when -there are two or more frames (not counting minibuffer-only frames or -invisible frames). The default value of @code{frame-title-format} uses -@code{multiple-frames} so as to put the buffer name in the frame title -only when there is more than one frame. - -The value of this variable is not guaranteed to be accurate except -while processing @code{frame-title-format} or -@code{icon-title-format}. -@end defvar - -@node Deleting Frames -@section Deleting Frames -@cindex deleting frames - -Frames remain potentially visible until you explicitly @dfn{delete} -them. A deleted frame cannot appear on the screen, but continues to -exist as a Lisp object until there are no references to it. - -@deffn Command delete-frame &optional frame force -@vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. - -A frame cannot be deleted if its minibuffer is used by other frames. -Normally, you cannot delete a frame if all other frames are invisible, -but if @var{force} is non-@code{nil}, then you are allowed to do so. -@end deffn - -@defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. -@end defun - - Some window managers provide a command to delete a window. These work -by sending a special message to the program that operates the window. -When Emacs gets one of these commands, it generates a -@code{delete-frame} event, whose normal definition is a command that -calls the function @code{delete-frame}. @xref{Misc Events}. - -@node Finding All Frames -@section Finding All Frames -@cindex frames, scanning all - -@defun frame-list -The function @code{frame-list} returns a list of all the live frames, -i.e.@: those that have not been deleted. It is analogous to -@code{buffer-list} for buffers, and includes frames on all terminals. -The list that you get is newly created, so modifying the list doesn't -have any effect on the internals of Emacs. -@end defun - -@defun visible-frame-list -This function returns a list of just the currently visible frames. -@xref{Visibility of Frames}. (Terminal frames always count as -``visible,'' even though only the selected one is actually displayed.) -@end defun - -@defun next-frame &optional frame minibuf -The function @code{next-frame} lets you cycle conveniently through all -the frames on the current display from an arbitrary starting point. It -returns the ``next'' frame after @var{frame} in the cycle. If -@var{frame} is omitted or @code{nil}, it defaults to the selected frame -(@pxref{Input Focus}). - -The second argument, @var{minibuf}, says which frames to consider: - -@table @asis -@item @code{nil} -Exclude minibuffer-only frames. -@item @code{visible} -Consider all visible frames. -@item 0 -Consider all visible or iconified frames. -@item a window -Consider only the frames using that particular window as their -minibuffer. -@item anything else -Consider all frames. -@end table -@end defun - -@defun previous-frame &optional frame minibuf -Like @code{next-frame}, but cycles through all frames in the opposite -direction. -@end defun - - See also @code{next-window} and @code{previous-window}, in @ref{Cyclic -Window Ordering}. - -@node Frames and Windows -@section Frames and Windows - - Each window is part of one and only one frame; you can get that frame -with @code{window-frame}. - -@defun window-frame window -This function returns the frame that @var{window} is on. -@end defun - - All the non-minibuffer windows in a frame are arranged in a cyclic -order. The order runs from the frame's top window, which is at the -upper left corner, down and to the right, until it reaches the window at -the lower right corner (always the minibuffer window, if the frame has -one), and then it moves back to the top. @xref{Cyclic Window Ordering}. - -@defun frame-first-window &optional frame -This returns the topmost, leftmost window of frame @var{frame}. -If omitted or @code{nil}, @var{frame} defaults to the selected frame. -@end defun - -At any time, exactly one window on any frame is @dfn{selected within the -frame}. The significance of this designation is that selecting the -frame also selects this window. Conversely, selecting a window for -Emacs with @code{select-window} also makes that window selected within -its frame. @xref{Selecting Windows}. - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to -the selected frame. -@end defun - -@defun set-frame-selected-window frame window &optional norecord -This sets the selected window of frame @var{frame} to @var{window}. -If @var{frame} is @code{nil}, it operates on the selected frame. If -@var{frame} is the selected frame, this makes @var{window} the -selected window. This function returns @var{window}. - -Optional argument @var{norecord} non-@code{nil} means to neither change -the order of recently selected windows nor the buffer list (@pxref{The -Buffer List}). -@end defun - - Another function that (usually) returns one of the windows in a given -frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. - -@node Minibuffers and Frames -@section Minibuffers and Frames - -Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Definition of -minibuffer-window}). - -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can specify explicitly the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. - -If you use a minibuffer-only frame, you might want that frame to raise -when you enter the minibuffer. If so, set the variable -@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. - -@defvar default-minibuffer-frame -This variable specifies the frame to use for the minibuffer window, by -default. It does not affect existing frames. It is always local to -the current terminal and cannot be buffer-local. @xref{Multiple -Terminals}. -@end defvar - -@node Input Focus -@section Input Focus -@cindex input focus -@c @cindex selected frame Duplicates selected-frame - -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. - -When Emacs displays its frames on several terminals (@pxref{Multiple -Terminals}), each terminal has its own selected frame. But only one -of these is ``@emph{the} selected frame'': it's the frame that belongs -to the terminal from which the most recent input came. That is, when -Emacs runs a command that came from a certain terminal, the selected -frame is the one of that terminal. Since Emacs runs only a single -command at any given time, it needs to consider only one selected -frame at a time; this frame is what we call @dfn{the selected frame} -in this manual. The display on which the selected frame is shown is -the @dfn{selected frame's display}. - -@defun selected-frame -This function returns the selected frame. -@end defun - -Some window systems and window managers direct keyboard input to the -window object that the mouse is in; others require explicit clicks or -commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To -explicitly switch to a different frame from a Lisp function, call -@code{select-frame-set-input-focus}. - -Lisp programs can also switch frames ``temporarily'' by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. - -When using a text-only terminal, only one frame can be displayed at a -time on the terminal, so after a call to @code{select-frame}, the next -redisplay actually displays the newly selected frame. This frame -remains selected until a subsequent call to @code{select-frame}. Each -terminal frame has a number which appears in the mode line before the -buffer name (@pxref{Mode Line Variables}). - -@defun select-frame-set-input-focus frame -This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. On -a text-only terminal, the next redisplay displays the new frame on the -entire terminal screen. The return value of this function is not -significant. -@end defun - -@c ??? This is not yet implemented properly. -@defun select-frame frame &optional norecord -This function selects frame @var{frame}, temporarily disregarding the -focus of the X server if any. The selection of @var{frame} lasts until -the next time the user does something to select a different frame, or -until the next time this function is called. (If you are using a -window system, the previously selected frame may be restored as the -selected frame after return to the command loop, because it still may -have the window system's input focus.) - -The specified @var{frame} becomes the selected frame, as explained -above, and the terminal that @var{frame} is on becomes the selected -terminal. The window selected within @var{frame} becomes the selected -window. This function returns @var{frame}, or @code{nil} if @var{frame} -has been deleted. - -Optional argument @var{norecord} non-@code{nil} means to neither change -the order of recently selected windows nor the buffer list. @xref{The -Buffer List}. - -In general, you should never use @code{select-frame} in a way that could -switch to a different terminal without switching back when you're done. -@end defun - -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. - -@deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. -@end deffn - -@defun redirect-frame-focus frame &optional focus-frame -This function redirects focus from @var{frame} to @var{focus-frame}. -This means that @var{focus-frame} will receive subsequent keystrokes and -events intended for @var{frame}. After such an event, the value of -@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame -events specifying @var{frame} will instead select @var{focus-frame}. - -If @var{focus-frame} is omitted or @code{nil}, that cancels any existing -redirection for @var{frame}, which therefore once again receives its own -events. - -One use of focus redirection is for frames that don't have minibuffers. -These frames use minibuffers on other frames. Activating a minibuffer -on another frame redirects focus to that frame. This puts the focus on -the minibuffer's frame, where it belongs, even though the mouse remains -in the frame that activated the minibuffer. - -Selecting a frame can also change focus redirections. Selecting frame -@code{bar}, when @code{foo} had been selected, changes any redirections -pointing to @code{foo} so that they point to @code{bar} instead. This -allows focus redirection to work properly when the user switches from -one frame to another using @code{select-window}. - -This means that a frame whose focus is redirected to itself is treated -differently from a frame whose focus is not redirected. -@code{select-frame} affects the former but not the latter. - -The redirection lasts until @code{redirect-frame-focus} is called to -change it. -@end defun - -@defopt focus-follows-mouse -This option is how you inform Emacs whether the window manager transfers -focus when the user moves the mouse. Non-@code{nil} says that it does. -When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. -@end defopt - -@node Visibility of Frames -@section Visibility of Frames -@cindex visible frame -@cindex invisible frame -@cindex iconified frame -@cindex frame visibility - -A window frame may be @dfn{visible}, @dfn{invisible}, or -@dfn{iconified}. If it is visible, you can see its contents, unless -other windows cover it. If it is iconified, the frame's contents do -not appear on the screen, but an icon does. (Note: because of the -way in which some window managers implement the concept of multiple -workspaces, or desktops, all frames on other workspaces may appear to -Emacs to be iconified.) If the frame is invisible, it doesn't show on -the screen, not even as an icon. - -Visibility is meaningless for terminal frames, since only the selected -one is actually displayed in any case. - -@deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit -@var{frame}, it makes the selected frame visible. This does not raise -the frame, but you can do that with @code{raise-frame} if you wish -(@pxref{Raising and Lowering}). -@end deffn - -@deffn Command make-frame-invisible &optional frame force -This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. - -Unless @var{force} is non-@code{nil}, this function refuses to make -@var{frame} invisible if all other frames are invisible.. -@end deffn - -@deffn Command iconify-frame &optional frame -This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. -@end deffn - -@defun frame-visible-p frame -This returns the visibility status of frame @var{frame}. The value is -@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and -@code{icon} if it is iconified. - -On a text-only terminal, all frames are considered visible, whether -they are currently being displayed or not, and this function returns -@code{t} for all frames. -@end defun - - The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{Management -Parameters}. - - The user can iconify and deiconify frames with the window manager. -This happens below the level at which Emacs can exert any control, but -Emacs does provide events that you can use to keep track of such -changes. @xref{Misc Events}. - -@node Raising and Lowering -@section Raising and Lowering Frames - - Most window systems use a desktop metaphor. Part of this metaphor is -the idea that windows are stacked in a notional third dimension -perpendicular to the screen surface, and thus ordered from ``highest'' -to ``lowest.'' Where two windows overlap, the one higher up covers -the one underneath. Even a window at the bottom of the stack can be -seen if no other window overlaps it. - -@c @cindex raising a frame redundant with raise-frame -@cindex lowering a frame - A window's place in this ordering is not fixed; in fact, users tend -to change the order frequently. @dfn{Raising} a window means moving -it ``up,'' to the top of the stack. @dfn{Lowering} a window means -moving it to the bottom of the stack. This motion is in the notional -third dimension only, and does not change the position of the window -on the screen. - - With Emacs, frames constitute the windows in the metaphor sketched -above. You can raise and lower frames using these functions: - -@deffn Command raise-frame &optional frame -This function raises frame @var{frame} (default, the selected frame). -If @var{frame} is invisible or iconified, this makes it visible. -@end deffn - -@deffn Command lower-frame &optional frame -This function lowers frame @var{frame} (default, the selected frame). -@end deffn - -@defopt minibuffer-auto-raise -If this is non-@code{nil}, activation of the minibuffer raises the frame -that the minibuffer window is in. -@end defopt - -You can also enable auto-raise (raising automatically when a frame is -selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{Management Parameters}. - -@node Frame Configurations -@section Frame Configurations -@cindex frame configuration - - A @dfn{frame configuration} records the current arrangement of frames, -all their properties, and the window configuration of each one. -(@xref{Window Configurations}.) - -@defun current-frame-configuration -This function returns a frame configuration list that describes -the current arrangement of frames and their contents. -@end defun - -@defun set-frame-configuration configuration &optional nodelete -This function restores the state of frames described in -@var{configuration}. However, this function does not restore deleted -frames. - -Ordinarily, this function deletes all existing frames not listed in -@var{configuration}. But if @var{nodelete} is non-@code{nil}, the -unwanted frames are iconified instead. -@end defun - -@node Mouse Tracking -@section Mouse Tracking -@cindex mouse tracking -@c @cindex tracking the mouse Duplicates track-mouse - - Sometimes it is useful to @dfn{track} the mouse, which means to display -something to indicate where the mouse is and move the indicator as the -mouse moves. For efficient mouse tracking, you need a way to wait until -the mouse actually moves. - - The convenient way to track the mouse is to ask for events to represent -mouse motion. Then you can wait for motion by waiting for an event. In -addition, you can easily handle any other sorts of events that may -occur. That is useful, because normally you don't want to track the -mouse forever---only until some other event, such as the release of a -button. - -@defspec track-mouse body@dots{} -This special form executes @var{body}, with generation of mouse motion -events enabled. Typically, @var{body} would use @code{read-event} to -read the motion events and modify the display accordingly. @xref{Motion -Events}, for the format of mouse motion events. - -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. -@end defspec - -The usual purpose of tracking mouse motion is to indicate on the screen -the consequences of pushing or releasing a button at the current -position. - -In many cases, you can avoid the need to track the mouse by using -the @code{mouse-face} text property (@pxref{Special Properties}). -That works at a much lower level and runs more smoothly than -Lisp-level mouse tracking. - -@ignore -@c These are not implemented yet. - -These functions change the screen appearance instantaneously. The -effect is transient, only until the next ordinary Emacs redisplay. That -is OK for mouse tracking, since it doesn't make sense for mouse tracking -to change the text, and the body of @code{track-mouse} normally reads -the events itself and does not do redisplay. - -@defun x-contour-region window beg end -This function draws lines to make a box around the text from @var{beg} -to @var{end}, in window @var{window}. -@end defun - -@defun x-uncontour-region window beg end -This function erases the lines that would make a box around the text -from @var{beg} to @var{end}, in window @var{window}. Use it to remove -a contour that you previously made by calling @code{x-contour-region}. -@end defun - -@defun x-draw-rectangle frame left top right bottom -This function draws a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. It uses the cursor color, the one used for indicating the -location of point. -@end defun - -@defun x-erase-rectangle frame left top right bottom -This function erases a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. Erasure means redrawing the text and background that -normally belong in the specified rectangle. -@end defun -@end ignore - -@node Mouse Position -@section Mouse Position -@cindex mouse position -@cindex position of mouse - - The functions @code{mouse-position} and @code{set-mouse-position} -give access to the current position of the mouse. - -@defun mouse-position -This function returns a description of the position of the mouse. The -value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. -@end defun - -@defvar mouse-position-function -If non-@code{nil}, the value of this variable is a function for -@code{mouse-position} to call. @code{mouse-position} calls this -function just before returning, with its normal return value as the -sole argument, and it returns whatever this function returns to it. - -This abnormal hook exists for the benefit of packages like -@file{xt-mouse.el} that need to do mouse handling at the Lisp level. -@end defvar - -@defun set-mouse-position frame x y -This function @dfn{warps the mouse} to position @var{x}, @var{y} in -frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. -@end defun - -@defun mouse-pixel-position -This function is like @code{mouse-position} except that it returns -coordinates in units of pixels rather than units of characters. -@end defun - -@defun set-mouse-pixel-position frame x y -This function warps the mouse like @code{set-mouse-position} except that -@var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. - -If @var{frame} is not visible, this function does nothing. The return -value is not significant. -@end defun - -@need 3000 - -@node Pop-Up Menus -@section Pop-Up Menus - - When using a window system, a Lisp program can pop up a menu so that -the user can choose an alternative with the mouse. - -@defun x-popup-menu position menu -This function displays a pop-up menu and returns an indication of -what selection the user makes. - -The argument @var{position} specifies where on the screen to put the -top left corner of the menu. It can be either a mouse button event -(which says to put the menu where the user actuated the button) or a -list of this form: - -@example -((@var{xoffset} @var{yoffset}) @var{window}) -@end example - -@noindent -where @var{xoffset} and @var{yoffset} are coordinates, measured in -pixels, counting from the top left corner of @var{window}. @var{window} -may be a window or a frame. - -If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. - -The argument @var{menu} says what to display in the menu. It can be a -keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the -return value is the list of events corresponding to the user's choice. -(This list has more than one element if the choice occurred in a -submenu.) Note that @code{x-popup-menu} does not actually execute the -command bound to that sequence of events. - -Alternatively, @var{menu} can have the following form: - -@example -(@var{title} @var{pane1} @var{pane2}...) -@end example - -@noindent -where each pane is a list of form - -@example -(@var{title} @var{item1} @var{item2}...) -@end example - -Each item should normally be a cons cell @code{(@var{line} . @var{value})}, -where @var{line} is a string, and @var{value} is the value to return if -that @var{line} is chosen. An item can also be a string; this makes a -non-selectable line in the menu. - -If the user gets rid of the menu without making a valid choice, for -instance by clicking the mouse away from a valid choice or by typing -keyboard input, then this normally results in a quit and -@code{x-popup-menu} does not return. But if @var{position} is a mouse -button event (indicating that the user invoked the menu with the -mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}. -@end defun - - @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu -if you could do the job with a prefix key defined with a menu keymap. -If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h -a} can see the individual items in that menu and provide help for them. -If instead you implement the menu by defining a command that calls -@code{x-popup-menu}, the help facilities cannot know what happens inside -that command, so they cannot give any help for the menu's items. - - The menu bar mechanism, which lets you switch between submenus by -moving the mouse, cannot look within the definition of a command to see -that it calls @code{x-popup-menu}. Therefore, if you try to implement a -submenu using @code{x-popup-menu}, it cannot work with the menu bar in -an integrated fashion. This is why all menu bar submenus are -implemented with menu keymaps within the parent menu, and never with -@code{x-popup-menu}. @xref{Menu Bar}. - - If you want a menu bar submenu to have contents that vary, you should -still use a menu keymap to implement it. To make the contents vary, add -a hook function to @code{menu-bar-update-hook} to update the contents of -the menu keymap as necessary. - -@node Dialog Boxes -@section Dialog Boxes -@cindex dialog boxes - - A dialog box is a variant of a pop-up menu---it looks a little -different, it always appears in the center of a frame, and it has just -one level and one or more buttons. The main use of dialog boxes is -for asking questions that the user can answer with ``yes,'' ``no,'' -and a few other alternatives. With a single button, they can also -force the user to acknowledge important information. The functions -@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the -keyboard, when called from commands invoked by mouse clicks. - -@defun x-popup-dialog position contents &optional header -This function displays a pop-up dialog box and returns an indication of -what selection the user makes. The argument @var{contents} specifies -the alternatives to offer; it has this format: - -@example -(@var{title} (@var{string} . @var{value})@dots{}) -@end example - -@noindent -which looks like the list that specifies a single pane for -@code{x-popup-menu}. - -The return value is @var{value} from the chosen alternative. - -As for @code{x-popup-menu}, an element of the list may be just a -string instead of a cons cell @code{(@var{string} . @var{value})}. -That makes a box that cannot be selected. - -If @code{nil} appears in the list, it separates the left-hand items from -the right-hand items; items that precede the @code{nil} appear on the -left, and items that follow the @code{nil} appear on the right. If you -don't include a @code{nil} in the list, then approximately half the -items appear on each side. - -Dialog boxes always appear in the center of a frame; the argument -@var{position} specifies which frame. The possible values are as in -@code{x-popup-menu}, but the precise coordinates or the individual -window don't matter; only the frame matters. - -If @var{header} is non-@code{nil}, the frame title for the box is -@samp{Information}, otherwise it is @samp{Question}. The former is used -for @code{message-box} (@pxref{message-box}). - -In some configurations, Emacs cannot display a real dialog box; so -instead it displays the same items in a pop-up menu in the center of the -frame. - -If the user gets rid of the dialog box without making a valid choice, -for instance using the window manager, then this produces a quit and -@code{x-popup-dialog} does not return. -@end defun - -@node Pointer Shape -@section Pointer Shape -@cindex pointer shape -@cindex mouse pointer shape - - You can specify the mouse pointer style for particular text or -images using the @code{pointer} text property, and for images with the -@code{:pointer} and @code{:map} image properties. The values you can -use in these properties are @code{text} (or @code{nil}), @code{arrow}, -@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and -@code{hourglass}. @code{text} stands for the usual mouse pointer -style used over text. - - Over void parts of the window (parts that do not correspond to any -of the buffer contents), the mouse pointer usually uses the -@code{arrow} style, but you can specify a different style (one of -those above) by setting @code{void-text-area-pointer}. - -@defvar void-text-area-pointer -This variable specifies the mouse pointer style for void text areas. -These include the areas after the end of a line or below the last line -in the buffer. The default is to use the @code{arrow} (non-text) -pointer style. -@end defvar - - When using X, you can specify what the @code{text} pointer style -really looks like by setting the variable @code{x-pointer-shape}. - -@defvar x-pointer-shape -This variable specifies the pointer shape to use ordinarily in the -Emacs frame, for the @code{text} pointer style. -@end defvar - -@defvar x-sensitive-text-pointer-shape -This variable specifies the pointer shape to use when the mouse -is over mouse-sensitive text. -@end defvar - - These variables affect newly created frames. They do not normally -affect existing frames; however, if you set the mouse color of a -frame, that also installs the current value of those two variables. -@xref{Font and Color Parameters}. - - The values you can use, to specify either of these pointer shapes, are -defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos -@key{RET} x-pointer @key{RET}} to see a list of them. - -@node Window System Selections -@section Window System Selections -@cindex selection (for window systems) - -The X server records a set of @dfn{selections} which permit transfer of -data between application programs. The various selections are -distinguished by @dfn{selection types}, represented in Emacs by -symbols. X clients including Emacs can read or set the selection for -any given type. - -@deffn Command x-set-selection type data -This function sets a ``selection'' in the X server. It takes two -arguments: a selection type @var{type}, and the value to assign to it, -@var{data}. If @var{data} is @code{nil}, it means to clear out the -selection. Otherwise, @var{data} may be a string, a symbol, an integer -(or a cons of two integers or list of two integers), an overlay, or a -cons of two markers pointing to the same buffer. An overlay or a pair -of markers stands for text in the overlay or between the markers. - -The argument @var{data} may also be a vector of valid non-vector -selection values. - -Each possible @var{type} has its own selection value, which changes -independently. The usual values of @var{type} are @code{PRIMARY}, -@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case -names, in accord with X Window System conventions. If @var{type} is -@code{nil}, that stands for @code{PRIMARY}. - -This function returns @var{data}. -@end deffn - -@defun x-get-selection &optional type data-type -This function accesses selections set up by Emacs or by other X -clients. It takes two optional arguments, @var{type} and -@var{data-type}. The default for @var{type}, the selection type, is -@code{PRIMARY}. - -The @var{data-type} argument specifies the form of data conversion to -use, to convert the raw data obtained from another X client into Lisp -data. Meaningful values include @code{TEXT}, @code{STRING}, -@code{UTF8_STRING}, @code{TARGETS}, @code{LENGTH}, @code{DELETE}, -@code{FILE_NAME}, @code{CHARACTER_POSITION}, @code{NAME}, -@code{LINE_NUMBER}, @code{COLUMN_NUMBER}, @code{OWNER_OS}, -@code{HOST_NAME}, @code{USER}, @code{CLASS}, @code{ATOM}, and -@code{INTEGER}. (These are symbols with upper-case names in accord -with X conventions.) The default for @var{data-type} is -@code{STRING}. -@end defun - -@cindex cut buffer -The X server also has a set of eight numbered @dfn{cut buffers} which can -store text or other data being moved between applications. Cut buffers -are considered obsolete, but Emacs supports them for the sake of X -clients that still use them. Cut buffers are numbered from 0 to 7. - -@defun x-get-cut-buffer &optional n -This function returns the contents of cut buffer number @var{n}. -If omitted @var{n} defaults to 0. -@end defun - -@defun x-set-cut-buffer string &optional push -@anchor{Definition of x-set-cut-buffer} -This function stores @var{string} into the first cut buffer (cut buffer -0). If @var{push} is @code{nil}, only the first cut buffer is changed. -If @var{push} is non-@code{nil}, that says to move the values down -through the series of cut buffers, much like the way successive kills in -Emacs move down the kill ring. In other words, the previous value of -the first cut buffer moves into the second cut buffer, and the second to -the third, and so on through all eight cut buffers. -@end defun - -@defopt selection-coding-system -This variable specifies the coding system to use when reading and -writing selections or the clipboard. @xref{Coding -Systems}. The default is @code{compound-text-with-extensions}, which -converts to the text representation that X11 normally uses. -@end defopt - -@cindex clipboard support (for MS-Windows) -When Emacs runs on MS-Windows, it does not implement X selections in -general, but it does support the clipboard. @code{x-get-selection} -and @code{x-set-selection} on MS-Windows support the text data type -only; if the clipboard holds other types of data, Emacs treats the -clipboard as empty. - -@defopt x-select-enable-clipboard -If this is non-@code{nil}, the Emacs yank functions consult the -clipboard before the primary selection, and the kill functions store in -the clipboard as well as the primary selection. Otherwise they do not -access the clipboard at all. The default is @code{nil} on most systems, -but @code{t} on MS-Windows. -@end defopt - -@node Drag and Drop -@section Drag and Drop - -@vindex x-dnd-test-function -@vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. - -@vindex x-dnd-types-alist - If you want to change the way Emacs handles drop of different types -or add a new type, customize @code{x-dnd-types-alist}. This requires -detailed knowledge of what types other applications use for drag and -drop. - -@vindex dnd-protocol-alist - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (ftp, http, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. - -@node Color Names -@section Color Names - -@cindex color names -@cindex specify color -@cindex numerical RGB color specification - A color name is text (usually in a string) that specifies a color. -Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc., -are allowed; use @kbd{M-x list-colors-display} to see a list of -defined names. You can also specify colors numerically in forms such -as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where -@var{r} specifies the red level, @var{g} specifies the green level, -and @var{b} specifies the blue level. You can use either one, two, -three, or four hex digits for @var{r}; then you must use the same -number of hex digits for all @var{g} and @var{b} as well, making -either 3, 6, 9 or 12 hex digits in all. (See the documentation of the -X Window System for more details about numerical RGB specification of -colors.) - - These functions provide a way to determine which color names are -valid, and what they look like. In some cases, the value depends on the -@dfn{selected frame}, as described below; see @ref{Input Focus}, for the -meaning of the term ``selected frame.'' - - To read user input of color names with completion, use -@code{read-color} (@pxref{High-Level Completion, read-color}). - -@defun color-defined-p color &optional frame -This function reports whether a color name is meaningful. It returns -@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says -which frame's display to ask about; if @var{frame} is omitted or -@code{nil}, the selected frame is used. - -Note that this does not tell you whether the display you are using -really supports that color. When using X, you can ask for any defined -color on any kind of display, and you will get some result---typically, -the closest it can do. To determine whether a frame can really display -a certain color, use @code{color-supported-p} (see below). - -@findex x-color-defined-p -This function used to be called @code{x-color-defined-p}, -and that name is still supported as an alias. -@end defun - -@defun defined-colors &optional frame -This function returns a list of the color names that are defined -and supported on frame @var{frame} (default, the selected frame). -If @var{frame} does not support colors, the value is @code{nil}. - -@findex x-defined-colors -This function used to be called @code{x-defined-colors}, -and that name is still supported as an alias. -@end defun - -@defun color-supported-p color &optional frame background-p -This returns @code{t} if @var{frame} can really display the color -@var{color} (or at least something close to it). If @var{frame} is -omitted or @code{nil}, the question applies to the selected frame. - -Some terminals support a different set of colors for foreground and -background. If @var{background-p} is non-@code{nil}, that means you are -asking whether @var{color} can be used as a background; otherwise you -are asking whether it can be used as a foreground. - -The argument @var{color} must be a valid color name. -@end defun - -@defun color-gray-p color &optional frame -This returns @code{t} if @var{color} is a shade of gray, as defined on -@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the -question applies to the selected frame. If @var{color} is not a valid -color name, this function returns @code{nil}. -@end defun - -@defun color-values color &optional frame -@cindex rgb value -This function returns a value that describes what @var{color} should -ideally look like on @var{frame}. If @var{color} is defined, the -value is a list of three integers, which give the amount of red, the -amount of green, and the amount of blue. Each integer ranges in -principle from 0 to 65535, but some displays may not use the full -range. This three-element list is called the @dfn{rgb values} of the -color. - -If @var{color} is not defined, the value is @code{nil}. - -@example -(color-values "black") - @result{} (0 0 0) -(color-values "white") - @result{} (65280 65280 65280) -(color-values "red") - @result{} (65280 0 0) -(color-values "pink") - @result{} (65280 49152 51968) -(color-values "hungry") - @result{} nil -@end example - -The color values are returned for @var{frame}'s display. If -@var{frame} is omitted or @code{nil}, the information is returned for -the selected frame's display. If the frame cannot display colors, the -value is @code{nil}. - -@findex x-color-values -This function used to be called @code{x-color-values}, -and that name is still supported as an alias. -@end defun - -@node Text Terminal Colors -@section Text Terminal Colors -@cindex colors on text-only terminals - - Text-only terminals usually support only a small number of colors, -and the computer uses small integers to select colors on the terminal. -This means that the computer cannot reliably tell what the selected -color looks like; instead, you have to inform your application which -small integers correspond to which colors. However, Emacs does know -the standard set of colors and will try to use them automatically. - - The functions described in this section control how terminal colors -are used by Emacs. - - Several of these functions use or return @dfn{rgb values}, described -in @ref{Color Names}. - - These functions accept a display (either a frame or the name of a -terminal) as an optional argument. We hope in the future to make -Emacs support different colors on different text-only terminals; then -this argument will specify which terminal to operate on (the default -being the selected frame's terminal; @pxref{Input Focus}). At -present, though, the @var{frame} argument has no effect. - -@defun tty-color-define name number &optional rgb frame -This function associates the color name @var{name} with -color number @var{number} on the terminal. - -The optional argument @var{rgb}, if specified, is an rgb value, a list -of three numbers that specify what the color actually looks like. -If you do not specify @var{rgb}, then this color cannot be used by -@code{tty-color-approximate} to approximate other colors, because -Emacs will not know what it looks like. -@end defun - -@defun tty-color-clear &optional frame -This function clears the table of defined colors for a text-only terminal. -@end defun - -@defun tty-color-alist &optional frame -This function returns an alist recording the known colors supported by a -text-only terminal. - -Each element has the form @code{(@var{name} @var{number} . @var{rgb})} -or @code{(@var{name} @var{number})}. Here, @var{name} is the color -name, @var{number} is the number used to specify it to the terminal. -If present, @var{rgb} is a list of three color values (for red, green, -and blue) that says what the color actually looks like. -@end defun - -@defun tty-color-approximate rgb &optional frame -This function finds the closest color, among the known colors -supported for @var{display}, to that described by the rgb value -@var{rgb} (a list of color values). The return value is an element of -@code{tty-color-alist}. -@end defun - -@defun tty-color-translate color &optional frame -This function finds the closest color to @var{color} among the known -colors supported for @var{display} and returns its index (an integer). -If the name @var{color} is not defined, the value is @code{nil}. -@end defun - -@node Resources -@section X Resources - -@defun x-get-resource attribute class &optional component subclass -The function @code{x-get-resource} retrieves a resource value from the X -Window defaults database. - -Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. -This function searches using a key of the form -@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs.@var{class}} as -the class. - -The optional arguments @var{component} and @var{subclass} add to the key -and the class, respectively. You must specify both of them or neither. -If you specify them, the key is -@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{class}.@var{subclass}}. -@end defun - -@defvar x-resource-class -This variable specifies the application name that @code{x-get-resource} -should look up. The default value is @code{"Emacs"}. You can examine X -resources for application names other than ``Emacs'' by binding this -variable to some other string, around a call to @code{x-get-resource}. -@end defvar - -@defvar x-resource-name -This variable specifies the instance name that @code{x-get-resource} -should look up. The default value is the name Emacs was invoked with, -or the value specified with the @samp{-name} or @samp{-rn} switches. -@end defvar - -To illustrate some of the above, suppose that you have the line: - -@example -xterm.vt100.background: yellow -@end example - -@noindent -in your X resources file (whose name is usually @file{~/.Xdefaults} -or @file{~/.Xresources}). Then: - -@example -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "vt100.background" "VT100.Background")) - @result{} "yellow" -@end group -@group -(let ((x-resource-class "XTerm") (x-resource-name "xterm")) - (x-get-resource "background" "VT100" "vt100" "Background")) - @result{} "yellow" -@end group -@end example - - @xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}. - -@node Display Feature Testing -@section Display Feature Testing -@cindex display feature testing - - The functions in this section describe the basic capabilities of a -particular display. Lisp programs can use them to adapt their behavior -to what the display can do. For example, a program that ordinarily uses -a popup menu could use the minibuffer if popup menus are not supported. - - The optional argument @var{display} in these functions specifies which -display to ask the question about. It can be a display name, a frame -(which designates the display that frame is on), or @code{nil} (which -refers to the selected frame's display, @pxref{Input Focus}). - - @xref{Color Names}, @ref{Text Terminal Colors}, for other functions to -obtain information about displays. - -@defun display-popup-menus-p &optional display -This function returns @code{t} if popup menus are supported on -@var{display}, @code{nil} if not. Support for popup menus requires that -the mouse be available, since the user cannot choose menu items without -a mouse. -@end defun - -@defun display-graphic-p &optional display -This function returns @code{t} if @var{display} is a graphic display -capable of displaying several frames and several different fonts at -once. This is true for displays that use a window system such as X, and -false for text-only terminals. -@end defun - -@defun display-mouse-p &optional display -@cindex mouse, availability -This function returns @code{t} if @var{display} has a mouse available, -@code{nil} if not. -@end defun - -@defun display-color-p &optional display -@findex x-display-color-p -This function returns @code{t} if the screen is a color screen. -It used to be called @code{x-display-color-p}, and that name -is still supported as an alias. -@end defun - -@defun display-grayscale-p &optional display -This function returns @code{t} if the screen can display shades of gray. -(All color displays can do this.) -@end defun - -@defun display-supports-face-attributes-p attributes &optional display -@anchor{Display Face Attribute Testing} -This function returns non-@code{nil} if all the face attributes in -@var{attributes} are supported (@pxref{Face Attributes}). - -The definition of `supported' is somewhat heuristic, but basically -means that a face containing all the attributes in @var{attributes}, -when merged with the default face for display, can be represented in a -way that's - -@enumerate -@item -different in appearance than the default face, and - -@item -`close in spirit' to what the attributes specify, if not exact. -@end enumerate - -Point (2) implies that a @code{:weight black} attribute will be -satisfied by any display that can display bold, as will -@code{:foreground "yellow"} as long as some yellowish color can be -displayed, but @code{:slant italic} will @emph{not} be satisfied by -the tty display code's automatic substitution of a `dim' face for -italic. -@end defun - -@defun display-selections-p &optional display -This function returns @code{t} if @var{display} supports selections. -Windowed displays normally support selections, but they may also be -supported in some other cases. -@end defun - -@defun display-images-p &optional display -This function returns @code{t} if @var{display} can display images. -Windowed displays ought in principle to handle images, but some -systems lack the support for that. On a display that does not support -images, Emacs cannot display a tool bar. -@end defun - -@defun display-screens &optional display -This function returns the number of screens associated with the display. -@end defun - -@defun display-pixel-height &optional display -This function returns the height of the screen in pixels. -On a character terminal, it gives the height in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-pixel-width &optional display -This function returns the width of the screen in pixels. -On a character terminal, it gives the width in characters. - -For graphical terminals, note that on ``multi-monitor'' setups this -refers to the pixel width for all physical monitors associated with -@var{display}. @xref{Multiple Terminals}. -@end defun - -@defun display-mm-height &optional display -This function returns the height of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defun display-mm-width &optional display -This function returns the width of the screen in millimeters, -or @code{nil} if Emacs cannot get that information. -@end defun - -@defopt display-mm-dimensions-alist -This variable allows the user to specify the dimensions of graphical -displays returned by @code{display-mm-height} and -@code{display-mm-width} in case the system provides incorrect values. -@end defopt - -@defun display-backing-store &optional display -This function returns the backing store capability of the display. -Backing store means recording the pixels of windows (and parts of -windows) that are not exposed, so that when exposed they can be -displayed very quickly. - -Values can be the symbols @code{always}, @code{when-mapped}, or -@code{not-useful}. The function can also return @code{nil} -when the question is inapplicable to a certain kind of display. -@end defun - -@defun display-save-under &optional display -This function returns non-@code{nil} if the display supports the -SaveUnder feature. That feature is used by pop-up windows -to save the pixels they obscure, so that they can pop down -quickly. -@end defun - -@defun display-planes &optional display -This function returns the number of planes the display supports. -This is typically the number of bits per pixel. -For a tty display, it is log to base two of the number of colors supported. -@end defun - -@defun display-visual-class &optional display -This function returns the visual class for the screen. The value is one -of the symbols @code{static-gray}, @code{gray-scale}, -@code{static-color}, @code{pseudo-color}, @code{true-color}, and -@code{direct-color}. -@end defun - -@defun display-color-cells &optional display -This function returns the number of color cells the screen supports. -@end defun - - These functions obtain additional information specifically -about X displays. - -@defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. The value is a list of three integers: the major -and minor version numbers of the X protocol, and the -distributor-specific release number of the X server software itself. -@end defun - -@defun x-server-vendor &optional display -This function returns the ``vendor'' that provided the X server -software (as a string). Really this means whoever distributes the X -server. - -When the developers of X labelled software distributors as -``vendors,'' they showed their false assumption that no system could -ever be developed and distributed noncommercially. -@end defun - -@ignore -@defvar x-no-window-manager -This variable's value is @code{t} if no X window manager is in use. -@end defvar -@end ignore - -@ignore -@item -The functions @code{x-pixel-width} and @code{x-pixel-height} return the -width and height of an X Window frame, measured in pixels. -@end ignore - - -@ignore - arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba -@end ignore diff --git a/doc/lispref/front-cover-1.texi b/doc/lispref/front-cover-1.texi deleted file mode 100644 index 5c9f4351f42..00000000000 --- a/doc/lispref/front-cover-1.texi +++ /dev/null @@ -1,56 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename front1.info -@settitle GNU Emacs Lisp Reference Manual -@smallbook -@comment %**end of header - -@titlepage -. -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -. -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@end titlepage -@bye - -@ignore - arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d -@end ignore diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi deleted file mode 100644 index 36a937c529a..00000000000 --- a/doc/lispref/functions.texi +++ /dev/null @@ -1,1501 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/functions -@node Functions, Macros, Variables, Top -@chapter Functions - - A Lisp program is composed mainly of Lisp functions. This chapter -explains what functions are, how they accept arguments, and how to -define them. - -@menu -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler will open code. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how functions work. -@end menu - -@node What Is a Function -@section What Is a Function? - - In a general sense, a function is a rule for carrying on a computation -given several values called @dfn{arguments}. The result of the -computation is called the value of the function. The computation can -also have side effects: lasting changes in the values of variables or -the contents of data structures. - - Here are important terms for functions in Emacs Lisp and for other -function-like objects. - -@table @dfn -@item function -@cindex function -In Emacs Lisp, a @dfn{function} is anything that can be applied to -arguments in a Lisp program. In some cases, we use it more -specifically to mean a function written in Lisp. Special forms and -macros are not functions. - -@item primitive -@cindex primitive -@cindex subr -@cindex built-in function -A @dfn{primitive} is a function callable from Lisp that is written in C, -such as @code{car} or @code{append}. These functions are also called -@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also -considered primitives.) - -Usually the reason we implement a function as a primitive is either -because it is fundamental, because it provides a low-level interface -to operating system services, or because it needs to run fast. -Primitives can be modified or added only by changing the C sources and -recompiling the editor. See @ref{Writing Emacs Primitives}. - -@item lambda expression -A @dfn{lambda expression} is a function written in Lisp. -These are described in the following section. -@ifnottex -@xref{Lambda Expressions}. -@end ifnottex - -@item special form -A @dfn{special form} is a primitive that is like a function but does not -evaluate all of its arguments in the usual way. It may evaluate only -some of the arguments, or may evaluate them in an unusual order, or -several times. Many special forms are described in @ref{Control -Structures}. - -@item macro -@cindex macro -A @dfn{macro} is a construct defined in Lisp by the programmer. It -differs from a function in that it translates a Lisp expression that you -write into an equivalent expression to be evaluated instead of the -original expression. Macros enable Lisp programmers to do the sorts of -things that special forms can do. @xref{Macros}, for how to define and -use macros. - -@item command -@cindex command -A @dfn{command} is an object that @code{command-execute} can invoke; it -is a possible definition for a key sequence. Some functions are -commands; a function written in Lisp is a command if it contains an -interactive declaration (@pxref{Defining Commands}). Such a function -can be called from Lisp expressions like other functions; in this case, -the fact that the function is a command makes no difference. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. A symbol is a command if its function -definition is a command; such symbols can be invoked with @kbd{M-x}. -The symbol is a function as well if the definition is a function. -@xref{Interactive Call}. - -@item keystroke command -@cindex keystroke command -A @dfn{keystroke command} is a command that is bound to a key sequence -(typically one to three keystrokes). The distinction is made here -merely to avoid confusion with the meaning of ``command'' in non-Emacs -editors; for Lisp programs, the distinction is normally unimportant. - -@item byte-code function -A @dfn{byte-code function} is a function that has been compiled by the -byte compiler. @xref{Byte-Code Type}. -@end table - -@defun functionp object -This function returns @code{t} if @var{object} is any kind of -function, i.e.@: can be passed to @code{funcall}. Note that -@code{functionp} returns @code{nil} for special forms (@pxref{Special -Forms}). -@end defun - -Unlike @code{functionp}, the next three functions do @emph{not} -treat a symbol as its function definition. - -@defun subrp object -This function returns @code{t} if @var{object} is a built-in function -(i.e., a Lisp primitive). - -@example -@group -(subrp 'message) ; @r{@code{message} is a symbol,} - @result{} nil ; @r{not a subr object.} -@end group -@group -(subrp (symbol-function 'message)) - @result{} t -@end group -@end example -@end defun - -@defun byte-code-function-p object -This function returns @code{t} if @var{object} is a byte-code -function. For example: - -@example -@group -(byte-code-function-p (symbol-function 'next-line)) - @result{} t -@end group -@end example -@end defun - -@defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. -@end defun - -@node Lambda Expressions -@section Lambda Expressions -@cindex lambda expression - - A function written in Lisp is a list that looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-declaration}@r{]} - @var{body-forms}@dots{}) -@end example - -@noindent -Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it -actually is valid as an expression---it evaluates to itself. In some -other Lisp dialects, a lambda expression is not a valid expression at -all. In either case, its main use is not to be evaluated as an -expression, but to be called as a function. - -@menu -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. -@end menu - -@node Lambda Components -@subsection Components of a Lambda Expression - -@ifnottex - - A function written in Lisp (a ``lambda expression'') is a list that -looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - [@var{documentation-string}] - [@var{interactive-declaration}] - @var{body-forms}@dots{}) -@end example -@end ifnottex - -@cindex lambda list - The first element of a lambda expression is always the symbol -@code{lambda}. This indicates that the list represents a function. The -reason functions are defined to start with @code{lambda} is so that -other lists, intended for other uses, will not accidentally be valid as -functions. - - The second element is a list of symbols---the argument variable names. -This is called the @dfn{lambda list}. When a Lisp function is called, -the argument values are matched up against the variables in the lambda -list, which are given local bindings with the values provided. -@xref{Local Variables}. - - The documentation string is a Lisp string object placed within the -function definition to describe the function for the Emacs help -facilities. @xref{Function Documentation}. - - The interactive declaration is a list of the form @code{(interactive -@var{code-string})}. This declares how to provide arguments if the -function is used interactively. Functions with this declaration are called -@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. -Functions not intended to be called in this way should not have interactive -declarations. @xref{Defining Commands}, for how to write an interactive -declaration. - -@cindex body of function - The rest of the elements are the @dfn{body} of the function: the Lisp -code to do the work of the function (or, as a Lisp programmer would say, -``a list of Lisp forms to evaluate''). The value returned by the -function is the value returned by the last element of the body. - -@node Simple Lambda -@subsection A Simple Lambda-Expression Example - - Consider for example the following function: - -@example -(lambda (a b c) (+ a b c)) -@end example - -@noindent -We can call this function by writing it as the @sc{car} of an -expression, like this: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 2 3) -@end group -@end example - -@noindent -This call evaluates the body of the lambda expression with the variable -@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. -Evaluation of the body adds these three numbers, producing the result 6; -therefore, this call to the function returns the value 6. - - Note that the arguments can be the results of other function calls, as in -this example: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 (* 2 3) (- 5 4)) -@end group -@end example - -@noindent -This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression to the -argument values 1, 6 and 1 to produce the value 8. - - It is not often useful to write a lambda expression as the @sc{car} of -a form in this way. You can get the same result, of making local -variables and giving them values, using the special form @code{let} -(@pxref{Local Variables}). And @code{let} is clearer and easier to use. -In practice, lambda expressions are either stored as the function -definitions of symbols, to produce named functions, or passed as -arguments to other functions (@pxref{Anonymous Functions}). - - However, calls to explicit lambda expressions were very useful in the -old days of Lisp, before the special form @code{let} was invented. At -that time, they were the only way to bind and initialize local -variables. - -@node Argument List -@subsection Other Features of Argument Lists -@kindex wrong-number-of-arguments -@cindex argument binding -@cindex binding arguments -@cindex argument lists, features - - Our simple sample function, @code{(lambda (a b c) (+ a b c))}, -specifies three argument variables, so it must be called with three -arguments: if you try to call it with only two arguments or four -arguments, you get a @code{wrong-number-of-arguments} error. - - It is often convenient to write a function that allows certain -arguments to be omitted. For example, the function @code{substring} -accepts three arguments---a string, the start index and the end -index---but the third argument defaults to the @var{length} of the -string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{list} -and @code{+} do. - -@cindex optional arguments -@cindex rest arguments -@kindex &optional -@kindex &rest - To specify optional arguments that may be omitted when a function -is called, simply include the keyword @code{&optional} before the optional -arguments. To specify a list of zero or more extra arguments, include the -keyword @code{&rest} before one final argument. - - Thus, the complete syntax for an argument list is as follows: - -@example -@group -(@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) -@end group -@end example - -@noindent -The square brackets indicate that the @code{&optional} and @code{&rest} -clauses, and the variables that follow them, are optional. - - A call to the function requires one actual argument for each of the -@var{required-vars}. There may be actual arguments for zero or more of -the @var{optional-vars}, and there cannot be any actual arguments beyond -that unless the lambda list uses @code{&rest}. In that case, there may -be any number of extra actual arguments. - - If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. There is no way for the -function to distinguish between an explicit argument of @code{nil} and -an omitted argument. However, the body of the function is free to -consider @code{nil} an abbreviation for some other meaningful value. -This is what @code{substring} does; @code{nil} as the third argument to -@code{substring} means to use the length of the string supplied. - -@cindex CL note---default optional arg -@quotation -@b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' -variables that tell you whether an argument was explicitly passed. -@end quotation - - For example, an argument list that looks like this: - -@example -(a b &optional c d &rest e) -@end example - -@noindent -binds @code{a} and @code{b} to the first two actual arguments, which are -required. If one or two more arguments are provided, @code{c} and -@code{d} are bound to them respectively; any arguments after the first -four are collected into a list and @code{e} is bound to that list. If -there are only two arguments, @code{c} is @code{nil}; if two or three -arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} -is @code{nil}. - - There is no way to have required arguments following optional -ones---it would not make sense. To see why this must be so, suppose -that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the -third argument be for? Would it be used for the @var{c}, or for -@var{d}? One can argue for both possibilities. Similarly, it makes -no sense to have any more arguments (either required or optional) -after a @code{&rest} argument. - - Here are some examples of argument lists and proper calls: - -@smallexample -((lambda (n) (1+ n)) ; @r{One required:} - 1) ; @r{requires exactly one argument.} - @result{} 2 -((lambda (n &optional n1) ; @r{One required and one optional:} - (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} - 1 2) - @result{} 3 -((lambda (n &rest ns) ; @r{One required and one rest:} - (+ n (apply '+ ns))) ; @r{1 or more arguments.} - 1 2 3 4 5) - @result{} 15 -@end smallexample - -@node Function Documentation -@subsection Documentation Strings of Functions -@cindex documentation of function - - A lambda expression may optionally have a @dfn{documentation string} just -after the lambda list. This string does not affect execution of the -function; it is a kind of comment, but a systematized comment which -actually appears inside the Lisp world and can be used by the Emacs help -facilities. @xref{Documentation}, for how the @var{documentation-string} is -accessed. - - It is a good idea to provide documentation strings for all the -functions in your program, even those that are called only from within -your program. Documentation strings are like comments, except that they -are easier to access. - - The first line of the documentation string should stand on its own, -because @code{apropos} displays just this first line. It should consist -of one or two complete sentences that summarize the function's purpose. - - The start of the documentation string is usually indented in the -source file, but since these spaces come before the starting -double-quote, they are not part of the string. Some people make a -practice of indenting any additional lines of the string so that the -text lines up in the program source. @emph{That is a mistake.} The -indentation of the following lines is inside the string; what looks -nice in the source code will look ugly when displayed by the help -commands. - - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. - - The last line of the documentation string can specify calling -conventions different from the actual function arguments. Write -text like this: - -@example -\(fn @var{arglist}) -@end example - -@noindent -following a blank line, at the beginning of the line, with no newline -following it inside the documentation string. (The @samp{\} is used -to avoid confusing the Emacs motion commands.) The calling convention -specified in this way appears in help messages in place of the one -derived from the actual arguments of the function. - - This feature is particularly useful for macro definitions, since the -arguments written in a macro definition often do not correspond to the -way users think of the parts of the macro call. - -@node Function Names -@section Naming a Function -@cindex function definition -@cindex named function -@cindex function name - - In most computer languages, every function has a name; the idea of a -function without a name is nonsensical. In Lisp, a function in the -strictest sense has no name. It is simply a list whose first element is -@code{lambda}, a byte-code function object, or a primitive subr-object. - - However, a symbol can serve as the name of a function. This happens -when you put the function in the symbol's @dfn{function cell} -(@pxref{Symbol Components}). Then the symbol itself becomes a valid, -callable function, equivalent to the list or subr-object that its -function cell refers to. The contents of the function cell are also -called the symbol's @dfn{function definition}. The procedure of using a -symbol's function definition in place of the symbol is called -@dfn{symbol function indirection}; see @ref{Function Indirection}. - - In practice, nearly all functions are given names in this way and -referred to through their names. For example, the symbol @code{car} works -as a function and does what it does because the primitive subr-object -@code{#} is stored in its function cell. - - We give functions names because it is convenient to refer to them by -their names in Lisp expressions. For primitive subr-objects such as -@code{#}, names are the only way you can refer to them: there -is no read syntax for such objects. For functions written in Lisp, the -name is more convenient to use in a call than an explicit lambda -expression. Also, a function with a name can refer to itself---it can -be recursive. Writing the function's name in its own definition is much -more convenient than making the function definition point to itself -(something that is not impossible but that has various disadvantages in -practice). - - We often identify functions with the symbols used to name them. For -example, we often speak of ``the function @code{car},'' not -distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, the -distinction is not important. - - Even so, keep in mind that a function need not have a unique name. While -a given function object @emph{usually} appears in the function cell of only -one symbol, this is just a matter of convenience. It is easy to store -it in several symbols using @code{fset}; then each of the symbols is -equally well a name for the same function. - - A symbol used as a function name may also be used as a variable; these -two uses of a symbol are independent and do not conflict. (Some Lisp -dialects, such as Scheme, do not distinguish between a symbol's value -and its function definition; a symbol's value as a variable is also its -function definition.) If you have not given a symbol a function -definition, you cannot use it as a function; whether the symbol has a -value as a variable makes no difference to this. - -@node Defining Functions -@section Defining Functions -@cindex defining a function - - We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} special form. - -@defspec defun name argument-list body-forms -@code{defun} is the usual way to define new Lisp functions. It -defines the symbol @var{name} as a function that looks like this: - -@example -(lambda @var{argument-list} . @var{body-forms}) -@end example - -@code{defun} stores this lambda expression in the function cell of -@var{name}. It returns the value @var{name}, but usually we ignore this -value. - -As described previously, @var{argument-list} is a list of argument -names and may include the keywords @code{&optional} and @code{&rest} -(@pxref{Lambda Expressions}). Also, the first two of the -@var{body-forms} may be a documentation string and an interactive -declaration. - -There is no conflict if the same symbol @var{name} is also used as a -variable, since the symbol's value cell is independent of the function -cell. @xref{Symbol Components}. - -Here are some examples: - -@example -@group -(defun foo () 5) - @result{} foo -@end group -@group -(foo) - @result{} 5 -@end group - -@group -(defun bar (a &optional b &rest c) - (list a b c)) - @result{} bar -@end group -@group -(bar 1 2 3 4 5) - @result{} (1 2 (3 4 5)) -@end group -@group -(bar 1) - @result{} (1 nil nil) -@end group -@group -(bar) -@error{} Wrong number of arguments. -@end group - -@group -(defun capitalize-backwards () - "Upcase the last letter of a word." - (interactive) - (backward-word 1) - (forward-word 1) - (backward-char 1) - (capitalize-word 1)) - @result{} capitalize-backwards -@end group -@end example - -Be careful not to redefine existing functions unintentionally. -@code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Redefining a function already -defined is often done deliberately, and there is no way to distinguish -deliberate redefinition from unintentional redefinition. -@end defspec - -@cindex function aliases -@defun defalias name definition &optional docstring -@anchor{Definition of defalias} -This special form defines the symbol @var{name} as a function, with -definition @var{definition} (which can be any valid Lisp function). -It returns @var{definition}. - -If @var{docstring} is non-@code{nil}, it becomes the function -documentation of @var{name}. Otherwise, any documentation provided by -@var{definition} is used. - -The proper place to use @code{defalias} is where a specific function -name is being defined---especially where that name appears explicitly in -the source file being loaded. This is because @code{defalias} records -which file defined the function, just like @code{defun} -(@pxref{Unloading}). - -By contrast, in programs that manipulate function definitions for other -purposes, it is better to use @code{fset}, which does not keep such -records. @xref{Function Cells}. -@end defun - - You cannot create a new primitive function with @code{defun} or -@code{defalias}, but you can use them to change the function definition of -any symbol, even one such as @code{car} or @code{x-popup-menu} whose -normal definition is a primitive. However, this is risky: for -instance, it is next to impossible to redefine @code{car} without -breaking Lisp completely. Redefining an obscure function such as -@code{x-popup-menu} is less dangerous, but it still may not work as -you expect. If there are calls to the primitive from C code, they -call the primitive's C definition directly, so changing the symbol's -definition will have no effect on them. - - See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to open-code it. @xref{Inline Functions}. - -@node Calling Functions -@section Calling Functions -@cindex function invocation -@cindex calling a function - - Defining functions is only half the battle. Functions don't do -anything until you @dfn{call} them, i.e., tell them to run. Calling a -function is also known as @dfn{invocation}. - - The most common way of invoking a function is by evaluating a list. -For example, evaluating the list @code{(concat "a" "b")} calls the -function @code{concat} with arguments @code{"a"} and @code{"b"}. -@xref{Evaluation}, for a description of evaluation. - - When you write a list as an expression in your program, you specify -which function to call, and how many arguments to give it, in the text -of the program. Usually that's just what you want. Occasionally you -need to compute at run time which function to call. To do that, use -the function @code{funcall}. When you also need to determine at run -time how many arguments to pass, use @code{apply}. - -@defun funcall function &rest arguments -@code{funcall} calls @var{function} with @var{arguments}, and returns -whatever @var{function} returns. - -Since @code{funcall} is a function, all of its arguments, including -@var{function}, are evaluated before @code{funcall} is called. This -means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the -expressions you write for the @var{arguments}, only their values. -These values are @emph{not} evaluated a second time in the act of -calling @var{function}; the operation of @code{funcall} is like the -normal procedure for calling a function, once its arguments have -already been evaluated. - -The argument @var{function} must be either a Lisp function or a -primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument -expressions. @code{funcall} cannot provide these because, as we saw -above, it never knows them in the first place. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(funcall f 'x 'y 'z) - @result{} (x y z) -@end group -@group -(funcall f 'x 'y '(z)) - @result{} (x y (z)) -@end group -@group -(funcall 'and t nil) -@error{} Invalid function: # -@end group -@end example - -Compare these examples with the examples of @code{apply}. -@end defun - -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just like -@code{funcall} but with one difference: the last of @var{arguments} is a -list of objects, which are passed to @var{function} as separate -arguments, rather than a single list. We say that @code{apply} -@dfn{spreads} this list so that each individual element becomes an -argument. - -@code{apply} returns the result of calling @var{function}. As with -@code{funcall}, @var{function} must either be a Lisp function or a -primitive function; special forms and macros do not make sense in -@code{apply}. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -@end group -@group -(apply '+ 1 2 '(3 4)) - @result{} 10 -@end group -@group -(apply '+ '(1 2 3 4)) - @result{} 10 -@end group - -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - -For an interesting example of using @code{apply}, see @ref{Definition -of mapcar}. -@end defun - -@cindex partial application of functions -@cindex currying - Sometimes it is useful to fix some of the function's arguments at -certain values, and leave the rest of arguments for when the function -is actually called. The act of fixing some of the function's -arguments is called @dfn{partial application} of the function@footnote{ -This is related to, but different from @dfn{currying}, which -transforms a function that takes multiple arguments in such a way that -it can be called as a chain of functions, each one with a single -argument.}. -The result is a new function that accepts the rest of -arguments and calls the original function with all the arguments -combined. - - Here's how to do partial application in Emacs Lisp: - -@defun apply-partially func &rest args -This function returns a new function which, when called, will call -@var{func} with the list of arguments composed from @var{args} and -additional arguments specified at the time of the call. If @var{func} -accepts @var{n} arguments, then a call to @code{apply-partially} with -@w{@code{@var{m} < @var{n}}} arguments will produce a new function of -@w{@code{@var{n} - @var{m}}} arguments. - -Here's how we could define the built-in function @code{1+}, if it -didn't exist, using @code{apply-partially} and @code{+}, another -built-in function: - -@example -@group -(defalias '1+ (apply-partially '+ 1) - "Increment argument by one.") -@end group -@group -(1+ 10) - @result{} 11 -@end group -@end example -@end defun - -@cindex functionals - It is common for Lisp functions to accept functions as arguments or -find them in data structures (especially in hook variables and property -lists) and call them using @code{funcall} or @code{apply}. Functions -that accept function arguments are often called @dfn{functionals}. - - Sometimes, when you call a functional, it is useful to supply a no-op -function as the argument. Here are two different kinds of no-op -function: - -@defun identity arg -This function returns @var{arg} and has no side effects. -@end defun - -@defun ignore &rest args -This function ignores any arguments and returns @code{nil}. -@end defun - -@node Mapping Functions -@section Mapping Functions -@cindex mapping functions - - A @dfn{mapping function} applies a given function (@emph{not} a -special form or macro) to each element of a list or other collection. -Emacs Lisp has several such functions; @code{mapcar} and -@code{mapconcat}, which scan a list, are described here. -@xref{Definition of mapatoms}, for the function @code{mapatoms} which -maps over the symbols in an obarray. @xref{Definition of maphash}, -for the function @code{maphash} which maps over key/value associations -in a hash table. - - These mapping functions do not allow char-tables because a char-table -is a sparse array whose nominal range of indices is very large. To map -over a char-table in a way that deals properly with its sparse nature, -use the function @code{map-char-table} (@pxref{Char-Tables}). - -@defun mapcar function sequence -@anchor{Definition of mapcar} -@code{mapcar} applies @var{function} to each element of @var{sequence} -in turn, and returns a list of the results. - -The argument @var{sequence} can be any kind of sequence except a -char-table; that is, a list, a vector, a bool-vector, or a string. The -result is always a list. The length of the result is the same as the -length of @var{sequence}. For example: - -@smallexample -@group -(mapcar 'car '((a b) (c d) (e f))) - @result{} (a c e) -(mapcar '1+ [1 2 3]) - @result{} (2 3 4) -(mapcar 'char-to-string "abc") - @result{} ("a" "b" "c") -@end group - -@group -;; @r{Call each function in @code{my-hooks}.} -(mapcar 'funcall my-hooks) -@end group - -@group -(defun mapcar* (function &rest args) - "Apply FUNCTION to successive cars of all ARGS. -Return the list of results." - ;; @r{If no list is exhausted,} - (if (not (memq nil args)) - ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function - ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) -@end group - -@group -(mapcar* 'cons '(a b c) '(1 2 3 4)) - @result{} ((a . 1) (b . 2) (c . 3)) -@end group -@end smallexample -@end defun - -@defun mapc function sequence -@code{mapc} is like @code{mapcar} except that @var{function} is used for -side-effects only---the values it returns are ignored, not collected -into a list. @code{mapc} always returns @var{sequence}. -@end defun - -@defun mapconcat function sequence separator -@code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string -@var{separator}. Usually @var{separator} contains a space or comma or -other suitable punctuation. - -The argument @var{function} must be a function that can take one -argument and return a string. The argument @var{sequence} can be any -kind of sequence except a char-table; that is, a list, a vector, a -bool-vector, or a string. - -@smallexample -@group -(mapconcat 'symbol-name - '(The cat in the hat) - " ") - @result{} "The cat in the hat" -@end group - -@group -(mapconcat (function (lambda (x) (format "%c" (1+ x)))) - "HAL-8000" - "") - @result{} "IBM.9111" -@end group -@end smallexample -@end defun - -@node Anonymous Functions -@section Anonymous Functions -@cindex anonymous function - - In Lisp, a function is a list that starts with @code{lambda}, a -byte-code function compiled from such a list, or alternatively a -primitive subr-object; names are ``extra.'' Although usually functions -are defined with @code{defun} and given names at the same time, it is -occasionally more concise to use an explicit lambda expression---an -anonymous function. Such a list is valid wherever a function name is. - - Any method of creating such a list makes a valid function. Even this: - -@smallexample -@group -(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) -@result{} (lambda (x) (+ 12 x)) -@end group -@end smallexample - -@noindent -This computes a list that looks like @code{(lambda (x) (+ 12 x))} and -makes it the value (@emph{not} the function definition!) of -@code{silly}. - - Here is how we might call this function: - -@example -@group -(funcall silly 1) -@result{} 13 -@end group -@end example - -@noindent -(It does @emph{not} work to write @code{(silly 1)}, because this function -is not the @emph{function definition} of @code{silly}. We have not given -@code{silly} any function definition, just a value as a variable.) - - Most of the time, anonymous functions are constants that appear in -your program. For example, you might want to pass one as an argument to -the function @code{mapcar}, which applies any given function to each -element of a list. - - Here we define a function @code{change-property} which -uses a function as its third argument: - -@example -@group -(defun change-property (symbol prop function) - (let ((value (get symbol prop))) - (put symbol prop (funcall function value)))) -@end group -@end example - -@noindent -Here we define a function that uses @code{change-property}, -passing it a function to double a number: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop '(lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -In such cases, we usually use the special form @code{function} instead -of simple quotation to quote the anonymous function, like this: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop - (function (lambda (x) (* 2 x))))) -@end group -@end example - -Using @code{function} instead of @code{quote} makes a difference if you -compile the function @code{double-property}. For example, if you -compile the second definition of @code{double-property}, the anonymous -function is compiled as well. By contrast, if you compile the first -definition which uses ordinary @code{quote}, the argument passed to -@code{change-property} is the precise list shown: - -@example -(lambda (x) (* x 2)) -@end example - -@noindent -The Lisp compiler cannot assume this list is a function, even though it -looks like one, since it does not know what @code{change-property} will -do with the list. Perhaps it will check whether the @sc{car} of the third -element is the symbol @code{*}! Using @code{function} tells the -compiler it is safe to go ahead and compile the constant function. - - Nowadays it is possible to omit @code{function} entirely, like this: - -@example -@group -(defun double-property (symbol prop) - (change-property symbol prop (lambda (x) (* 2 x)))) -@end group -@end example - -@noindent -This is because @code{lambda} itself implies @code{function}. - - We sometimes write @code{function} instead of @code{quote} when -quoting the name of a function, but this usage is just a sort of -comment: - -@example -(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} -@end example - -@cindex @samp{#'} syntax - The read syntax @code{#'} is a short-hand for using @code{function}. -For example, - -@example -#'(lambda (x) (* x x)) -@end example - -@noindent -is equivalent to - -@example -(function (lambda (x) (* x x))) -@end example - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is equivalent to @code{quote}. However, it serves as a -note to the Emacs Lisp compiler that @var{function-object} is intended -to be used only as a function, and therefore can safely be compiled. -Contrast this with @code{quote}, in @ref{Quoting}. -@end defspec - - @xref{describe-symbols example}, for a realistic example using -@code{function} and an anonymous function. - -@node Function Cells -@section Accessing Function Cell Contents - - The @dfn{function definition} of a symbol is the object stored in the -function cell of the symbol. The functions described here access, test, -and set the function cell of symbols. - - See also the function @code{indirect-function}. @xref{Definition of -indirect-function}. - -@defun symbol-function symbol -@kindex void-function -This returns the object in the function cell of @var{symbol}. If the -symbol's function cell is void, a @code{void-function} error is -signaled. - -This function does not check that the returned object is a legitimate -function. - -@example -@group -(defun bar (n) (+ n 2)) - @result{} bar -@end group -@group -(symbol-function 'bar) - @result{} (lambda (n) (+ n 2)) -@end group -@group -(fset 'baz 'bar) - @result{} bar -@end group -@group -(symbol-function 'baz) - @result{} bar -@end group -@end example -@end defun - -@cindex void function cell - If you have never given a symbol any function definition, we say that -that symbol's function cell is @dfn{void}. In other words, the function -cell does not have any Lisp object in it. If you try to call such a symbol -as a function, it signals a @code{void-function} error. - - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and they can be valid functions if you define them in turn with -@code{defun}). A void function cell contains no object whatsoever. - - You can test the voidness of a symbol's function definition with -@code{fboundp}. After you have given a symbol a function definition, you -can make it void once more using @code{fmakunbound}. - -@defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. -@end defun - -@defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a -@code{void-function} error. It returns @var{symbol}. (See also -@code{makunbound}, in @ref{Void Variables}.) - -@example -@group -(defun foo (x) x) - @result{} foo -@end group -@group -(foo 1) - @result{}1 -@end group -@group -(fmakunbound 'foo) - @result{} foo -@end group -@group -(foo 1) -@error{} Symbol's function definition is void: foo -@end group -@end example -@end defun - -@defun fset symbol definition -This function stores @var{definition} in the function cell of -@var{symbol}. The result is @var{definition}. Normally -@var{definition} should be a function or the name of a function, but -this is not checked. The argument @var{symbol} is an ordinary evaluated -argument. - -There are three normal uses of this function: - -@itemize @bullet -@item -Copying one symbol's function definition to another---in other words, -making an alternate name for a function. (If you think of this as the -definition of the new name, you should use @code{defalias} instead of -@code{fset}; see @ref{Definition of defalias}.) - -@item -Giving a symbol a function definition that is not a list and therefore -cannot be made with @code{defun}. For example, you can use @code{fset} -to give a symbol @code{s1} a function definition which is another symbol -@code{s2}; then @code{s1} serves as an alias for whatever definition -@code{s2} presently has. (Once again use @code{defalias} instead of -@code{fset} if you think of this as the definition of @code{s1}.) - -@item -In constructs for defining or altering functions. If @code{defun} -were not a primitive, it could be written in Lisp (as a macro) using -@code{fset}. -@end itemize - -Here are examples of these uses: - -@example -@group -;; @r{Save @code{foo}'s definition in @code{old-foo}.} -(fset 'old-foo (symbol-function 'foo)) -@end group - -@group -;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} -;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)} -(fset 'xfirst 'car) - @result{} car -@end group -@group -(xfirst '(1 2 3)) - @result{} 1 -@end group -@group -(symbol-function 'xfirst) - @result{} car -@end group -@group -(symbol-function (symbol-function 'xfirst)) - @result{} # -@end group - -@group -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end group - -@group -;; @r{Here is a function that alters other functions.} -(defun copy-function-definition (new old) - "Define NEW with the same function definition as OLD." - (fset new (symbol-function old))) -@end group -@end example -@end defun - - @code{fset} is sometimes used to save the old definition of a -function before redefining it. That permits the new definition to -invoke the old definition. But it is unmodular and unclean for a Lisp -file to redefine a function defined elsewhere. If you want to modify -a function defined by another package, it is cleaner to use -@code{defadvice} (@pxref{Advising Functions}). - -@node Obsolete Functions -@section Declaring Functions Obsolete - -You can use @code{make-obsolete} to declare a function obsolete. This -indicates that the function may be removed at some stage in the future. - -@defun make-obsolete obsolete-name current-name &optional when -This function makes the byte compiler warn that the function -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the -warning message says to use @var{current-name} instead of -@var{obsolete-name}. @var{current-name} does not need to be an alias for -@var{obsolete-name}; it can be a different function with similar -functionality. If @var{current-name} is a string, it is the warning -message. - -If provided, @var{when} should be a string indicating when the function -was first made obsolete---for example, a date or a release number. -@end defun - -You can define a function as an alias and declare it obsolete at the -same time using the macro @code{define-obsolete-function-alias}. - -@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring -This macro marks the function @var{obsolete-name} obsolete and also -defines it as an alias for the function @var{current-name}. It is -equivalent to the following: - -@example -(defalias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@node Inline Functions -@section Inline Functions -@cindex inline functions - -@findex defsubst -You can define an @dfn{inline function} by using @code{defsubst} instead -of @code{defun}. An inline function works just like an ordinary -function except for one thing: when you compile a call to the function, -the function's definition is open-coded into the caller. - -Making a function inline makes explicit calls run faster. But it also -has disadvantages. For one thing, it reduces flexibility; if you -change the definition of the function, calls already inlined still use -the old definition until you recompile them. - -Another disadvantage is that making a large function inline can increase -the size of compiled code both in files and in memory. Since the speed -advantage of inline functions is greatest for small functions, you -generally should not make large functions inline. - -Also, inline functions do not behave well with respect to debugging, -tracing, and advising (@pxref{Advising Functions}). Since ease of -debugging and the flexibility of redefining functions are important -features of Emacs, you should not make a function inline, even if it's -small, unless its speed is really crucial, and you've timed the code -to verify that using @code{defun} actually has performance problems. - -It's possible to define a macro to expand into the same code that an -inline function would execute. (@xref{Macros}.) But the macro would be -limited to direct use in expressions---a macro cannot be called with -@code{apply}, @code{mapcar} and so on. Also, it takes some work to -convert an ordinary function into a macro. To convert it into an inline -function is very easy; simply replace @code{defun} with @code{defsubst}. -Since each argument of an inline function is evaluated exactly once, you -needn't worry about how many times the body uses the arguments, as you -do for macros. (@xref{Argument Evaluation}.) - -Inline functions can be used and open-coded later on in the same file, -following the definition, just like macros. - -@node Declaring Functions -@section Telling the Compiler that a Function is Defined -@cindex function declaration -@cindex declaring functions -@findex declare-function - -Byte-compiling a file often produces warnings about functions that the -compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this -indicates a real problem, but usually the functions in question are -defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: - -@smallexample -In end of data: -fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known - to be defined. -@end smallexample - -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. - -All you need to do is add a @code{declare-function} statement before the -first use of the function in question: - -@smallexample -(declare-function gud-find-c-expr "gud.el" nil) -@end smallexample - -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the -@samp{.el} can be omitted). The compiler takes for granted that that file -really defines the function, and does not check. - - The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments -(@code{nil} is different from not specifying a value). In other -cases, this might be something like @code{(file &optional overwrite)}. -You don't have to specify the argument list, but if you do the -byte compiler can check that the calls match the declaration. - -@defmac declare-function function file &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that -@var{file} exists, not that it actually defines @var{function}. -@end defmac - - To verify that these functions really are declared where -@code{declare-function} says they are, use @code{check-declare-file} -to check all @code{declare-function} calls in one source file, or use -@code{check-declare-directory} check all the files in and under a -certain directory. - - These commands find the file that ought to contain a function's -definition using @code{locate-library}; if that finds no file, they -expand the definition file name relative to the directory of the file -that contains the @code{declare-function} call. - - You can also say that a function is defined by C code by specifying -a file name ending in @samp{.c}. @code{check-declare-file} looks for -these files in the C source code directory. This is useful only when -you call a function that is defined only on certain systems. Most -of the primitive functions of Emacs are always defined so they will -never give you a warning. - - Sometimes a file will optionally use functions from an external package. -If you prefix the filename in the @code{declare-function} statement with -@samp{ext:}, then it will be checked if it is found, otherwise skipped -without error. - - There are some function definitions that @samp{check-declare} does not -understand (e.g. @code{defstruct} and some other macros). In such cases, -you can pass a non-@code{nil} @var{fileonly} argument to -@code{declare-function}, meaning to only check that the file exists, not -that it actually defines the function. Note that to do this without -having to specify an argument list, you should set the @var{arglist} -argument to @code{t} (because @code{nil} means an empty argument list, as -opposed to an unspecified one). - -@node Function Safety -@section Determining whether a Function is Safe to Call -@cindex function safety -@cindex safety of functions - -Some major modes such as SES call functions that are stored in user -files. (@inforef{Top, ,ses}, for more information on SES.) User -files sometimes have poor pedigrees---you can get a spreadsheet from -someone you've just met, or you can get one through email from someone -you've never met. So it is risky to call a function whose source code -is stored in a user file until you have determined that it is safe. - -@defun unsafep form &optional unsafep-vars -Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or -returns a list that describes why it might be unsafe. The argument -@var{unsafep-vars} is a list of symbols known to have temporary -bindings at this point; it is mainly used for internal recursive -calls. The current buffer is an implicit argument, which provides a -list of buffer-local bindings. -@end defun - -Being quick and simple, @code{unsafep} does a very light analysis and -rejects many Lisp expressions that are actually safe. There are no -known cases where @code{unsafep} returns @code{nil} for an unsafe -expression. However, a ``safe'' Lisp expression can return a string -with a @code{display} property, containing an associated Lisp -expression to be executed after the string is inserted into a buffer. -This associated expression can be a virus. In order to be safe, you -must delete properties from all strings calculated by user code before -inserting them into buffers. - -@ignore -What is a safe Lisp expression? Basically, it's an expression that -calls only built-in functions with no side effects (or only innocuous -ones). Innocuous side effects include displaying messages and -altering non-risky buffer-local variables (but not global variables). - -@table @dfn -@item Safe expression -@itemize -@item -An atom or quoted thing. -@item -A call to a safe function (see below), if all its arguments are -safe expressions. -@item -One of the special forms @code{and}, @code{catch}, @code{cond}, -@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, -@code{while}, and @code{unwind-protect}], if all its arguments are -safe. -@item -A form that creates temporary bindings (@code{condition-case}, -@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or -@code{let*}), if all args are safe and the symbols to be bound are not -explicitly risky (see @pxref{File Local Variables}). -@item -An assignment using @code{add-to-list}, @code{setq}, @code{push}, or -@code{pop}, if all args are safe and the symbols to be assigned are -not explicitly risky and they already have temporary or buffer-local -bindings. -@item -One of [apply, mapc, mapcar, mapconcat] if the first argument is a -safe explicit lambda and the other args are safe expressions. -@end itemize - -@item Safe function -@itemize -@item -A lambda containing safe expressions. -@item -A symbol on the list @code{safe-functions}, so the user says it's safe. -@item -A symbol with a non-@code{nil} @code{side-effect-free} property. -@item -A symbol with a non-@code{nil} @code{safe-function} property. The -value @code{t} indicates a function that is safe but has innocuous -side effects. Other values will someday indicate functions with -classes of side effects that are not always safe. -@end itemize - -The @code{side-effect-free} and @code{safe-function} properties are -provided for built-in functions and for low-level functions and macros -defined in @file{subr.el}. You can assign these properties for the -functions you write. -@end table -@end ignore - -@node Related Topics -@section Other Topics Related to Functions - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -@table @code -@item apply -See @ref{Calling Functions}. - -@item autoload -See @ref{Autoload}. - -@item call-interactively -See @ref{Interactive Call}. - -@item called-interactively-p -See @ref{Distinguish Interactive}. - -@item commandp -See @ref{Interactive Call}. - -@item documentation -See @ref{Accessing Documentation}. - -@item eval -See @ref{Eval}. - -@item funcall -See @ref{Calling Functions}. - -@item function -See @ref{Anonymous Functions}. - -@item ignore -See @ref{Calling Functions}. - -@item indirect-function -See @ref{Function Indirection}. - -@item interactive -See @ref{Using Interactive}. - -@item interactive-p -See @ref{Distinguish Interactive}. - -@item mapatoms -See @ref{Creating Symbols}. - -@item mapcar -See @ref{Mapping Functions}. - -@item map-char-table -See @ref{Char-Tables}. - -@item mapconcat -See @ref{Mapping Functions}. - -@item undefined -See @ref{Functions for Key Lookup}. -@end table - -@ignore - arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2 -@end ignore diff --git a/doc/lispref/gpl.texi b/doc/lispref/gpl.texi deleted file mode 100644 index 163af4627bb..00000000000 --- a/doc/lispref/gpl.texi +++ /dev/null @@ -1,727 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../../info/gpl - -@node GPL, Tips, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@appendix GNU General Public License -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@ignore - arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f -@end ignore diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi deleted file mode 100644 index dd785f8fd7c..00000000000 --- a/doc/lispref/hash.texi +++ /dev/null @@ -1,337 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005, -@c 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/hash -@node Hash Tables, Symbols, Sequences Arrays Vectors, Top -@chapter Hash Tables -@cindex hash tables -@cindex lookup tables - - A hash table is a very fast kind of lookup table, somewhat like an -alist (@pxref{Association Lists}) in that it maps keys to -corresponding values. It differs from an alist in these ways: - -@itemize @bullet -@item -Lookup in a hash table is extremely fast for large tables---in fact, the -time required is essentially @emph{independent} of how many elements are -stored in the table. For smaller tables (a few tens of elements) -alists may still be faster because hash tables have a more-or-less -constant overhead. - -@item -The correspondences in a hash table are in no particular order. - -@item -There is no way to share structure between two hash tables, -the way two alists can share a common tail. -@end itemize - - Emacs Lisp provides a general-purpose hash table data type, along -with a series of functions for operating on them. Hash tables have no -read syntax, and print in hash notation, like this: - -@example -(make-hash-table) - @result{} # -@end example - -@noindent -(The term ``hash notation'' refers to the initial @samp{#} -character---@pxref{Printed Representation}---and has nothing to do with -the term ``hash table.'') - - Obarrays are also a kind of hash table, but they are a different type -of object and are used only for recording interned symbols -(@pxref{Creating Symbols}). - -@menu -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. -@end menu - -@node Creating Hash -@section Creating Hash Tables -@cindex creating hash tables - - The principal function for creating a hash table is -@code{make-hash-table}. - -@defun make-hash-table &rest keyword-args -This function creates a new hash table according to the specified -arguments. The arguments should consist of alternating keywords -(particular symbols recognized specially) and values corresponding to -them. - -Several keywords make sense in @code{make-hash-table}, but the only two -that you really need to know about are @code{:test} and @code{:weakness}. - -@table @code -@item :test @var{test} -This specifies the method of key lookup for this hash table. The -default is @code{eql}; @code{eq} and @code{equal} are other -alternatives: - -@table @code -@item eql -Keys which are numbers are ``the same'' if they are @code{equal}, that -is, if they are equal in value and either both are integers or both -are floating point numbers; otherwise, two distinct objects are never -``the same.'' - -@item eq -Any two distinct Lisp objects are ``different'' as keys. - -@item equal -Two Lisp objects are ``the same,'' as keys, if they are equal -according to @code{equal}. -@end table - -You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to -define additional possibilities for @var{test}. - -@item :weakness @var{weak} -The weakness of a hash table specifies whether the presence of a key or -value in the hash table preserves it from garbage collection. - -The value, @var{weak}, must be one of @code{nil}, @code{key}, -@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t} -which is an alias for @code{key-and-value}. If @var{weak} is @code{key} -then the hash table does not prevent its keys from being collected as -garbage (if they are not referenced anywhere else); if a particular key -does get collected, the corresponding association is removed from the -hash table. - -If @var{weak} is @code{value}, then the hash table does not prevent -values from being collected as garbage (if they are not referenced -anywhere else); if a particular value does get collected, the -corresponding association is removed from the hash table. - -If @var{weak} is @code{key-and-value} or @code{t}, both the key and -the value must be live in order to preserve the association. Thus, -the hash table does not protect either keys or values from garbage -collection; if either one is collected as garbage, that removes the -association. - -If @var{weak} is @code{key-or-value}, either the key or -the value can preserve the association. Thus, associations are -removed from the hash table when both their key and value would be -collected as garbage (if not for references from weak hash tables). - -The default for @var{weak} is @code{nil}, so that all keys and values -referenced in the hash table are preserved from garbage collection. - -@item :size @var{size} -This specifies a hint for how many associations you plan to store in the -hash table. If you know the approximate number, you can make things a -little more efficient by specifying it this way. If you specify too -small a size, the hash table will grow automatically when necessary, but -doing that takes some extra time. - -The default size is 65. - -@item :rehash-size @var{rehash-size} -When you add an association to a hash table and the table is ``full,'' -it grows automatically. This value specifies how to make the hash table -larger, at that time. - -If @var{rehash-size} is an integer, it should be positive, and the hash -table grows by adding that much to the nominal size. If -@var{rehash-size} is a floating point number, it had better be greater -than 1, and the hash table grows by multiplying the old size by that -number. - -The default value is 1.5. - -@item :rehash-threshold @var{threshold} -This specifies the criterion for when the hash table is ``full'' (so -it should be made larger). The value, @var{threshold}, should be a -positive floating point number, no greater than 1. The hash table is -``full'' whenever the actual number of entries exceeds this fraction -of the nominal size. The default for @var{threshold} is 0.8. -@end table -@end defun - -@defun makehash &optional test -This is equivalent to @code{make-hash-table}, but with a different style -argument list. The argument @var{test} specifies the method -of key lookup. - -This function is obsolete. Use @code{make-hash-table} instead. -@end defun - -@node Hash Access -@section Hash Table Access - - This section describes the functions for accessing and storing -associations in a hash table. In general, any Lisp object can be used -as a hash key, unless the comparison method imposes limits. Any Lisp -object can also be used as the value. - -@defun gethash key table &optional default -This function looks up @var{key} in @var{table}, and returns its -associated @var{value}---or @var{default}, if @var{key} has no -association in @var{table}. -@end defun - -@defun puthash key value table -This function enters an association for @var{key} in @var{table}, with -value @var{value}. If @var{key} already has an association in -@var{table}, @var{value} replaces the old associated value. -@end defun - -@defun remhash key table -This function removes the association for @var{key} from @var{table}, if -there is one. If @var{key} has no association, @code{remhash} does -nothing. - -@b{Common Lisp note:} In Common Lisp, @code{remhash} returns -non-@code{nil} if it actually removed an association and @code{nil} -otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. -@end defun - -@defun clrhash table -This function removes all the associations from hash table @var{table}, -so that it becomes empty. This is also called @dfn{clearing} the hash -table. - -@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty -@var{table}. In Emacs Lisp, it returns @code{nil}. -@end defun - -@defun maphash function table -@anchor{Definition of maphash} -This function calls @var{function} once for each of the associations in -@var{table}. The function @var{function} should accept two -arguments---a @var{key} listed in @var{table}, and its associated -@var{value}. @code{maphash} returns @code{nil}. -@end defun - -@node Defining Hash -@section Defining Hash Comparisons -@cindex hash code -@cindex define hash comparisons - - You can define new methods of key lookup by means of -@code{define-hash-table-test}. In order to use this feature, you need -to understand how hash tables work, and what a @dfn{hash code} means. - - You can think of a hash table conceptually as a large array of many -slots, each capable of holding one association. To look up a key, -@code{gethash} first computes an integer, the hash code, from the key. -It reduces this integer modulo the length of the array, to produce an -index in the array. Then it looks in that slot, and if necessary in -other nearby slots, to see if it has found the key being sought. - - Thus, to define a new method of key lookup, you need to specify both a -function to compute the hash code from a key, and a function to compare -two keys directly. - -@defun define-hash-table-test name test-fn hash-fn -This function defines a new hash table test, named @var{name}. - -After defining @var{name} in this way, you can use it as the @var{test} -argument in @code{make-hash-table}. When you do that, the hash table -will use @var{test-fn} to compare key values, and @var{hash-fn} to compute -a ``hash code'' from a key value. - -The function @var{test-fn} should accept two arguments, two keys, and -return non-@code{nil} if they are considered ``the same.'' - -The function @var{hash-fn} should accept one argument, a key, and return -an integer that is the ``hash code'' of that key. For good results, the -function should use the whole range of integer values for hash codes, -including negative integers. - -The specified functions are stored in the property list of @var{name} -under the property @code{hash-table-test}; the property value's form is -@code{(@var{test-fn} @var{hash-fn})}. -@end defun - -@defun sxhash obj -This function returns a hash code for Lisp object @var{obj}. -This is an integer which reflects the contents of @var{obj} -and the other Lisp objects it points to. - -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. - -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. -@end defun - - This example creates a hash table whose keys are strings that are -compared case-insensitively. - -@example -(defun case-fold-string= (a b) - (compare-strings a nil nil b nil nil t)) -(defun case-fold-string-hash (a) - (sxhash (upcase a))) - -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) - -(make-hash-table :test 'case-fold) -@end example - - Here is how you could define a hash table test equivalent to the -predefined test value @code{equal}. The keys can be any Lisp object, -and equal-looking objects are considered the same key. - -@example -(define-hash-table-test 'contents-hash 'equal 'sxhash) - -(make-hash-table :test 'contents-hash) -@end example - -@node Other Hash -@section Other Hash Table Functions - - Here are some other functions for working with hash tables. - -@defun hash-table-p table -This returns non-@code{nil} if @var{table} is a hash table object. -@end defun - -@defun copy-hash-table table -This function creates and returns a copy of @var{table}. Only the table -itself is copied---the keys and values are shared. -@end defun - -@defun hash-table-count table -This function returns the actual number of entries in @var{table}. -@end defun - -@defun hash-table-test table -This returns the @var{test} value that was given when @var{table} was -created, to specify how to hash and compare keys. See -@code{make-hash-table} (@pxref{Creating Hash}). -@end defun - -@defun hash-table-weakness table -This function returns the @var{weak} value that was specified for hash -table @var{table}. -@end defun - -@defun hash-table-rehash-size table -This returns the rehash size of @var{table}. -@end defun - -@defun hash-table-rehash-threshold table -This returns the rehash threshold of @var{table}. -@end defun - -@defun hash-table-size table -This returns the current nominal size of @var{table}. -@end defun - -@ignore - arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e -@end ignore diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi deleted file mode 100644 index bb38aabfa66..00000000000 --- a/doc/lispref/help.texi +++ /dev/null @@ -1,706 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/help -@node Documentation, Files, Modes, Top -@chapter Documentation -@cindex documentation strings - - GNU Emacs Lisp has convenient on-line help facilities, most of which -derive their information from the documentation strings associated with -functions and variables. This chapter describes how to write good -documentation strings for your Lisp programs, as well as how to write -programs to access documentation. - - Note that the documentation strings for Emacs are not the same thing -as the Emacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - - For commands to display documentation strings, see @ref{Help, , -Help, emacs, The GNU Emacs Manual}. For the conventions for writing -documentation strings, see @ref{Documentation Tips}. - -@menu -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. -@end menu - -@node Documentation Basics -@comment node-name, next, previous, up -@section Documentation Basics -@cindex documentation conventions -@cindex writing a documentation string -@cindex string, writing a doc string - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a -complete sentence (or two complete sentences) since some commands, -such as @code{apropos}, show only the first line of a multi-line -documentation string. Also, you should not indent the second line of -a documentation string, if it has one, because that looks odd when you -use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v} -(@code{describe-variable}) to view the documentation string. There -are many other conventions for doc strings; see @ref{Documentation -Tips}. - - Documentation strings can contain several special substrings, which -stand for key bindings to be looked up in the current keymaps when the -documentation is displayed. This allows documentation strings to refer -to the keys for related commands and be accurate even when a user -rearranges the key bindings. (@xref{Keys in Documentation}.) - -@vindex emacs-lisp-docstring-fill-column - Emacs Lisp mode fills documentation strings to the width -specified by @code{emacs-lisp-docstring-fill-column}. - - In Emacs Lisp, a documentation string is accessible through the -function or variable that it describes: - -@itemize @bullet -@item -@kindex function-documentation -The documentation for a function is usually stored in the function -definition itself (@pxref{Lambda Expressions}). The function -@code{documentation} knows how to extract it. You can also put -function documentation in the @code{function-documentation} property -of the function name. That is useful with definitions such as -keyboard macros that can't hold a documentation string. - -@item -@kindex variable-documentation -The documentation for a variable is stored in the variable's property -list under the property name @code{variable-documentation}. The -function @code{documentation-property} knows how to retrieve it. -@end itemize - -@cindex @file{DOC-@var{version}} (documentation) file -To save space, the documentation for preloaded functions and variables -(including primitive functions and autoloaded functions) is stored in -the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The -documentation strings for functions and variables loaded during the -Emacs session from byte-compiled files are stored in those files -(@pxref{Docs and Compilation}). - -The data structure inside Emacs has an integer offset into the file, or -a list containing a file name and an integer, in place of the -documentation string. The functions @code{documentation} and -@code{documentation-property} use that information to fetch the -documentation string from the appropriate file; this is transparent to -the user. - -@c Wordy to prevent overfull hbox. --rjc 15mar92 - The @file{emacs/lib-src} directory contains two utilities that you can -use to print nice-looking hardcopy for the file -@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and -@file{digest-doc}. - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string that is recorded in -@var{symbol}'s property list under property @var{property}. It -retrieves the text from a file if the value calls for that. If the -property value isn't @code{nil}, isn't a string, and doesn't refer to -text in a file, then it is evaluated to obtain a string. - -The last thing this function does is pass the string through -@code{substitute-command-keys} to substitute actual key bindings, -unless @var{verbatim} is non-@code{nil}. - -@smallexample -@group -(documentation-property 'command-line-processed - 'variable-documentation) - @result{} "Non-nil once command line has been processed" -@end group -@group -(symbol-plist 'command-line-processed) - @result{} (variable-documentation 188902) -@end group -@group -(documentation-property 'emacs 'group-documentation) - @result{} "Customization of the One True Editor." -@end group -@end smallexample -@end defun - -@defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. -@code{documentation} handles macros, named keyboard macros, and -special forms, as well as ordinary functions. - -If @var{function} is a symbol, this function first looks for the -@code{function-documentation} property of that symbol; if that has a -non-@code{nil} value, the documentation comes from that value (if the -value is not a string, it is evaluated). If @var{function} is not a -symbol, or if it has no @code{function-documentation} property, then -@code{documentation} extracts the documentation string from the actual -function definition, reading it from a file if called for. - -Finally, unless @var{verbatim} is non-@code{nil}, it calls -@code{substitute-command-keys} so as to return a value containing the -actual (current) key bindings. - -The function @code{documentation} signals a @code{void-function} error -if @var{function} has no function definition. However, it is OK if -the function definition has no documentation string. In that case, -@code{documentation} returns @code{nil}. -@end defun - -@defun face-documentation face -This function returns the documentation string of @var{face} as a -face. -@end defun - -@c Wordy to prevent overfull hboxes. --rjc 15mar92 -Here is an example of using the two functions, @code{documentation} and -@code{documentation-property}, to display the documentation strings for -several symbols in a @samp{*Help*} buffer. - -@anchor{describe-symbols example} -@smallexample -@group -(defun describe-symbols (pattern) - "Describe the Emacs Lisp symbols matching PATTERN. -All symbols that have PATTERN in their name are described -in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) -@end group -@group - ;; @r{Print description of symbol.} - (if (fboundp s) ; @r{It is a function.} - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") -@end group -@group - (or (documentation s) - "not documented")))) - - (if (boundp s) ; @r{It is a variable.} -@end group -@group - (princ - (format "%s\t%s\n%s\n\n" s - (if (user-variable-p s) - "Option " "Variable") -@end group -@group - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) -@end group - -@group - ;; @r{Build a list of symbols that match pattern.} - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) -@end group - -@group - ;; @r{Display the data.} - (help-setup-xref (list 'describe-symbols pattern) (interactive-p)) - (with-help-window (help-buffer) - (mapcar describe-func (sort sym-list 'string<))))) -@end group -@end smallexample - - The @code{describe-symbols} function works like @code{apropos}, -but provides more information. - -@smallexample -@group -(describe-symbols "goal") - ----------- Buffer: *Help* ---------- -goal-column Option -Semipermanent goal column for vertical motion, as set by @dots{} -@end group -@c Do not blithely break or fill these lines. -@c That makes them incorrect. - -@group -set-goal-column Keys: C-x C-n -Set the current horizontal position as a goal for C-n and C-p. -@end group -@c DO NOT put a blank line here! That is factually inaccurate! -@group -Those commands will move to this position in the line moved to -rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column -so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. -@end group - -@group -temporary-goal-column Variable -Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -@defun Snarf-documentation filename -@anchor{Definition of Snarf-documentation} -This function is used only during Emacs initialization, just before -the runnable Emacs is dumped. It finds the file offsets of the -documentation strings stored in the file @var{filename}, and records -them in the in-core function definitions and variable property lists in -place of the actual strings. @xref{Building Emacs}. - -Emacs reads the file @var{filename} from the @file{emacs/etc} directory. -When the dumped Emacs is later executed, the same file will be looked -for in the directory @code{doc-directory}. Usually @var{filename} is -@code{"DOC-@var{version}"}. -@end defun - -@defvar doc-directory -This variable holds the name of the directory which should contain the -file @code{"DOC-@var{version}"} that contains documentation strings for -built-in and preloaded functions and variables. - -In most cases, this is the same as @code{data-directory}. They may be -different when you run Emacs from the directory where you built it, -without actually installing it. @xref{Definition of data-directory}. -@end defvar - -@node Keys in Documentation -@section Substituting Key Bindings in Documentation -@cindex documentation, keys in -@cindex keys in documentation strings -@cindex substituting keys in documentation - - When documentation strings refer to key sequences, they should use the -current, actual key bindings. They can do so using certain special text -sequences described below. Accessing documentation strings in the usual -way substitutes current key binding information for these special -sequences. This works by calling @code{substitute-command-keys}. You -can also call that function yourself. - - Here is a list of the special sequences and what they mean: - -@table @code -@item \[@var{command}] -stands for a key sequence that will invoke @var{command}, or @samp{M-x -@var{command}} if @var{command} has no key bindings. - -@item \@{@var{mapvar}@} -stands for a summary of the keymap which is the value of the variable -@var{mapvar}. The summary is made using @code{describe-bindings}. - -@item \<@var{mapvar}> -stands for no text itself. It is used only for a side effect: it -specifies @var{mapvar}'s value as the keymap for any following -@samp{\[@var{command}]} sequences in this documentation string. - -@item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. -@end table - -@strong{Please note:} Each @samp{\} must be doubled when written in a -string in Emacs Lisp. - -@defun substitute-command-keys string -This function scans @var{string} for the above special sequences and -replaces them by what they stand for, returning the result as a string. -This permits display of documentation that refers accurately to the -user's own customized key bindings. -@end defun - - Here are examples of the special sequences: - -@smallexample -@group -(substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" -@end group - -@group -(substitute-command-keys - "The keys that are defined for the minibuffer here are: - \\@{minibuffer-local-must-match-map@}") -@result{} "The keys that are defined for the minibuffer here are: -@end group - -? minibuffer-completion-help -SPC minibuffer-complete-word -TAB minibuffer-complete -C-j minibuffer-complete-and-exit -RET minibuffer-complete-and-exit -C-g abort-recursive-edit -" - -@group -(substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." -@end group -@end smallexample - - There are other special conventions for the text in documentation -strings---for instance, you can refer to functions, variables, and -sections of this manual. @xref{Documentation Tips}, for details. - -@node Describing Characters -@section Describing Characters for Help Messages -@cindex describe characters and events - - These functions convert events, key sequences, or characters to -textual descriptions. These descriptions are useful for including -arbitrary text characters or key sequences in messages, because they -convert non-printing and whitespace characters to sequences of printing -characters. The description of a non-whitespace printing character is -the character itself. - -@defun key-description sequence &optional prefix -@cindex Emacs event standard notation -This function returns a string containing the Emacs standard notation -for the input events in @var{sequence}. If @var{prefix} is -non-@code{nil}, it is a sequence of input events leading up to -@var{sequence} and is included in the return value. Both arguments -may be strings, vectors or lists. @xref{Input Events}, for more -information about valid events. - -@smallexample -@group -(key-description [?\M-3 delete]) - @result{} "M-3 " -@end group -@group -(key-description [delete] "\M-3") - @result{} "M-3 " -@end group -@end smallexample - - See also the examples for @code{single-key-description}, below. -@end defun - -@defun single-key-description event &optional no-angles -@cindex event printing -@cindex character printing -@cindex control character printing -@cindex meta character printing -This function returns a string describing @var{event} in the standard -Emacs notation for keyboard input. A normal printing character -appears as itself, but a control character turns into a string -starting with @samp{C-}, a meta character turns into a string starting -with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC}, -@samp{TAB}, etc. A function key symbol appears inside angle brackets -@samp{<@dots{}>}. An event that is a list appears as the name of the -symbol in the @sc{car} of the list, inside angle brackets. - -If the optional argument @var{no-angles} is non-@code{nil}, the angle -brackets around function keys and event symbols are omitted; this is -for compatibility with old versions of Emacs which didn't use the -brackets. - -@smallexample -@group -(single-key-description ?\C-x) - @result{} "C-x" -@end group -@group -(key-description "\C-x \M-y \n \t \r \f123") - @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3" -@end group -@group -(single-key-description 'delete) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "" -@end group -@group -(single-key-description 'C-mouse-1 t) - @result{} "C-mouse-1" -@end group -@end smallexample -@end defun - -@defun text-char-description character -This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). Another difference is that -@code{text-char-description} recognizes the 2**7 bit as the Meta -character, whereas @code{single-key-description} uses the 2**27 bit -for Meta. - -@smallexample -@group -(text-char-description ?\C-c) - @result{} "^C" -@end group -@group -(text-char-description ?\M-m) - @result{} "\xed" -@end group -@group -(text-char-description ?\C-\M-m) - @result{} "\x8d" -@end group -@group -(text-char-description (+ 128 ?m)) - @result{} "M-m" -@end group -@group -(text-char-description (+ 128 ?\C-m)) - @result{} "M-^M" -@end group -@end smallexample -@end defun - -@defun read-kbd-macro string &optional need-vector -This function is used mainly for operating on keyboard macros, but it -can also be used as a rough inverse for @code{key-description}. You -call it with a string containing key descriptions, separated by spaces; -it returns a string or vector containing the corresponding events. -(This may or may not be a single valid key sequence, depending on what -events you use; @pxref{Key Sequences}.) If @var{need-vector} is -non-@code{nil}, the return value is always a vector. -@end defun - -@node Help Functions -@section Help Functions - - Emacs provides a variety of on-line help functions, all accessible to -the user as subcommands of the prefix @kbd{C-h}. For more information -about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here -we describe some program-level interfaces to the same information. - -@deffn Command apropos pattern &optional do-all -This function finds all ``meaningful'' symbols whose names contain a -match for the apropos pattern @var{pattern}. An apropos pattern is -either a word to match, a space-separated list of words of which at -least two must match, or a regular expression (if any special regular -expression characters occur). A symbol is ``meaningful'' if it has a -definition as a function, variable, or face, or has properties. - -The function returns a list of elements that look like this: - -@example -(@var{symbol} @var{score} @var{fn-doc} @var{var-doc} - @var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc}) -@end example - -Here, @var{score} is an integer measure of how important the symbol -seems to be as a match, and the remaining elements are documentation -strings for @var{symbol}'s various roles (or @code{nil}). - -It also displays the symbols in a buffer named @samp{*Apropos*}, each -with a one-line description taken from the beginning of its -documentation string. - -If @var{do-all} is non-@code{nil}, or if the user option -@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also -shows key bindings for the functions that are found; it also shows -@emph{all} interned symbols, not just meaningful ones (and it lists -them in the return value as well). -@end deffn - -@defvar help-map -The value of this variable is a local keymap for characters following the -Help key, @kbd{C-h}. -@end defvar - -@deffn {Prefix Command} help-command -This symbol is not a function; its function definition cell holds the -keymap known as @code{help-map}. It is defined in @file{help.el} as -follows: - -@smallexample -@group -(define-key global-map (char-to-string help-char) 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defopt help-char -The value of this variable is the help character---the character that -Emacs recognizes as meaning Help. By default, its value is 8, which -stands for @kbd{C-h}. When Emacs reads this character, if -@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that -expression, and displays the result in a window if it is a string. - -Usually the value of @code{help-form} is @code{nil}. Then the -help character has no special meaning at the level of command input, and -it becomes part of a key sequence in the normal way. The standard key -binding of @kbd{C-h} is a prefix key for several general-purpose help -features. - -The help character is special after prefix keys, too. If it has no -binding as a subcommand of the prefix key, it runs -@code{describe-prefix-bindings}, which displays a list of all the -subcommands of the prefix key. -@end defopt - -@defopt help-event-list -The value of this variable is a list of event types that serve as -alternative ``help characters.'' These events are handled just like the -event specified by @code{help-char}. -@end defopt - -@defvar help-form -If this variable is non-@code{nil}, its value is a form to evaluate -whenever the character @code{help-char} is read. If evaluating the form -produces a string, that string is displayed. - -A command that calls @code{read-event} or @code{read-char} probably -should bind @code{help-form} to a non-@code{nil} expression while it -does input. (The time when you should not do this is when @kbd{C-h} has -some other meaning.) Evaluating this expression should result in a -string that explains what the input is for and how to enter it properly. - -Entry to the minibuffer binds this variable to the value of -@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}). -@end defvar - -@defvar prefix-help-command -This variable holds a function to print help for a prefix key. The -function is called when the user types a prefix key followed by the help -character, and the help character has no binding after that prefix. The -variable's default value is @code{describe-prefix-bindings}. -@end defvar - -@defun describe-prefix-bindings -This function calls @code{describe-bindings} to display a list of all -the subcommands of the prefix key of the most recent key sequence. The -prefix described consists of all but the last event of that key -sequence. (The last event is, presumably, the help character.) -@end defun - - The following two functions are meant for modes that want to provide -help without relinquishing control, such as the ``electric'' modes. -Their names begin with @samp{Helper} to distinguish them from the -ordinary help functions. - -@deffn Command Helper-describe-bindings -This command pops up a window displaying a help buffer containing a -listing of all of the key bindings from both the local and global keymaps. -It works by calling @code{describe-bindings}. -@end deffn - -@deffn Command Helper-help -This command provides help for the current mode. It prompts the user -in the minibuffer with the message @samp{Help (Type ? for further -options)}, and then provides assistance in finding out what the key -bindings are, and what the mode is intended for. It returns @code{nil}. - -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@defvar data-directory -@anchor{Definition of data-directory} -This variable holds the name of the directory in which Emacs finds -certain documentation and text files that come with Emacs. -@end defvar - -@defun help-buffer -This function returns the name of the help buffer, which is normally -@samp{*Help*}; if such a buffer does not exist, it is first created. -@end defun - -@defmac with-help-window buffer-name body@dots{} -This macro evaluates the @var{body} forms, inserting any output they -produce into a buffer named @var{buffer-name} like -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}). -(Usually, @var{buffer-name} should be the value returned by the -function @code{help-buffer}.) It also puts the specified buffer into -Help mode and displays a message telling the user how to quit and -scroll the help window. -@end defmac - -@defun help-setup-xref item interactive-p -This function updates the cross reference data in the @samp{*Help*} -buffer, which is used to regenerate the help information when the user -clicks on the @samp{Back} or @samp{Forward} buttons. Most commands -that use the @samp{*Help*} buffer should invoke this function before -clearing the buffer. The @var{item} argument should have the form -@code{(@var{funtion} . @var{args})}, where @var{funtion} is a function -to call, with argument list @var{args}, to regenerate the help buffer. -The @var{interactive-p} argument is non-@code{nil} if the calling -command was invoked interactively; in that case, the stack of items -for the @samp{*Help*} buffer's @samp{Back} buttons is cleared. -@end defun - -@xref{describe-symbols example}, for an example of using -@code{help-buffer}, @code{with-help-window}, and -@code{help-setup-xref}. - -@defmac make-help-screen fname help-line help-text help-map -This macro defines a help command named @var{fname} that acts like a -prefix key that shows a list of the subcommands it offers. - -When invoked, @var{fname} displays @var{help-text} in a window, then -reads and executes a key sequence according to @var{help-map}. The -string @var{help-text} should describe the bindings available in -@var{help-map}. - -The command @var{fname} is defined to handle a few events itself, by -scrolling the display of @var{help-text}. When @var{fname} reads one of -those special events, it does the scrolling and then reads another -event. When it reads an event that is not one of those few, and which -has a binding in @var{help-map}, it executes that key's binding and -then returns. - -The argument @var{help-line} should be a single-line summary of the -alternatives in @var{help-map}. In the current version of Emacs, this -argument is used only if you set the option @code{three-step-help} to -@code{t}. - -This macro is used in the command @code{help-for-help} which is the -binding of @kbd{C-h C-h}. -@end defmac - -@defopt three-step-help -If this variable is non-@code{nil}, commands defined with -@code{make-help-screen} display their @var{help-line} strings in the -echo area at first, and display the longer @var{help-text} strings only -if the user types the help character again. -@end defopt - -@ignore - arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815 -@end ignore diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi deleted file mode 100644 index 8eb5bcb241c..00000000000 --- a/doc/lispref/hooks.texi +++ /dev/null @@ -1,358 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/hooks -@node Standard Hooks, Index, Standard Keymaps, Top -@appendix Standard Hooks -@cindex standard hooks -@cindex hook variables, list of - -The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - -Most of these variables have names ending with @samp{-hook}. They are -@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such -a hook is a list of functions; the functions are called with no -arguments and their values are completely ignored. The recommended way -to put a new function on such a hook is to call @code{add-hook}. -@xref{Hooks}, for more information about using hooks. - -Every major mode defines a mode hook named -@samp{@var{modename}-mode-hook}. The major mode command runs this -normal hook with @code{run-mode-hooks} as the very last thing it does. -@xref{Mode Hooks}. Most minor modes have mode hooks too. Mode hooks -are omitted in the list below. - -The variables whose names end in @samp{-hooks} or @samp{-functions} are -usually @dfn{abnormal hooks}; their values are lists of functions, but -these functions are called in a special way (they are passed arguments, -or their values are used). The variables whose names end in -@samp{-function} have single functions as their values. - -A special feature allows you to specify expressions to evaluate if and -when a file is loaded (@pxref{Hooks for Loading}). That feature is -not exactly a hook, but does a similar job. - -@c We need to xref to where each hook is documented or else document -@c it here. - -@table @code -@item abbrev-expand-functions -@xref{Abbrev Expansion}. - -@item activate-mark-hook -@xref{The Mark}. - -@item after-change-functions -@xref{Change Hooks}. - -@item after-change-major-mode-hook -@xref{Mode Hooks}. - -@item after-init-hook -@xref{Init File}. - -@item after-insert-file-functions -@xref{Format Conversion}. - -@item after-make-frame-functions -@xref{Creating Frames}. - -@item after-revert-hook -@xref{Reverting}. - -@item after-save-hook -@xref{Saving Buffers}. - -@item auto-fill-function -@xref{Auto Filling}. - -@item auto-save-hook -@xref{Auto-Saving}. - -@item before-change-functions -@xref{Change Hooks}. - -@item before-hack-local-variables-hook -@xref{File Local Variables}. - -@item before-init-hook -@xref{Init File}. - -@item before-make-frame-hook -@xref{Creating Frames}. - -@item before-revert-hook -@xref{Reverting}. - -@item before-save-hook -@xref{Saving Buffers}. - -@item blink-paren-function -@xref{Blinking}. - -@item buffer-access-fontify-functions -@xref{Lazy Properties}. - -@item calendar-load-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - - -@item change-major-mode-hook -@xref{Creating Buffer-Local}. - -@item command-line-functions -@xref{Command-Line Arguments}. - -@item comment-indent-function -@xref{Options for Comments,, Options Controlling Comments, emacs, the -GNU Emacs Manual}. - -@item compilation-finish-functions -Functions to call when a compilation process finishes. - -@item custom-define-hook -Hook called after defining each customize option. - -@item deactivate-mark-hook -@xref{The Mark}. - -@item delete-frame-functions -Functions to call when Emacs deletes a frame. @xref{Deleting Frames}. - -@item delete-terminal-functions -Functions to call when Emacs deletes a terminal. @xref{Multiple -Terminals}. - -@item desktop-after-read-hook -Normal hook run after a successful @code{desktop-read}. May be used -to show a buffer list. @xref{Saving Emacs Sessions,, Saving Emacs -Sessions, emacs, the GNU Emacs Manual}. - -@item desktop-no-desktop-file-hook -Normal hook run when @code{desktop-read} can't find a desktop file. -May be used to show a dired buffer. @xref{Saving Emacs Sessions,, -Saving Emacs Sessions, emacs, the GNU Emacs Manual}. - -@item desktop-save-hook -Normal hook run before the desktop is saved in a desktop file. This -is useful for truncating history lists, for example. @xref{Saving -Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}. - -@item diary-display-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item diary-hook -List of functions called after the display of the diary. Can be used -for appointment notification. - -@item disabled-command-function -@xref{Disabling Commands}. - -@item echo-area-clear-hook -@xref{Echo Area Customization}. - -@item emacs-startup-hook -@xref{Init File}. - -@item find-file-hook -@xref{Visiting Functions}. - -@item find-file-not-found-functions -@xref{Visiting Functions}. - -@item first-change-hook -@xref{Change Hooks}. - -@item font-lock-beginning-of-syntax-function -@xref{Syntactic Font Lock}. - -@item font-lock-fontify-buffer-function -@xref{Other Font Lock Variables}. - -@item font-lock-fontify-region-function -@xref{Other Font Lock Variables}. - -@item font-lock-mark-block-function -@xref{Other Font Lock Variables}. - -@item font-lock-syntactic-face-function -@xref{Syntactic Font Lock}. - -@item font-lock-unfontify-buffer-function -@xref{Other Font Lock Variables}. - -@item hack-local-variables-hook -@xref{File Local Variables}. - -@item font-lock-unfontify-region-function -@xref{Other Font Lock Variables}. - -@item initial-calendar-window-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item kbd-macro-termination-hook -@xref{Keyboard Macros}. - -@item kill-buffer-hook -@xref{Killing Buffers}. - -@item kill-buffer-query-functions -@xref{Killing Buffers}. - -@item kill-emacs-hook -@xref{Killing Emacs}. - -@item kill-emacs-query-functions -@xref{Killing Emacs}. - -@item lisp-indent-function - -@item list-diary-entries-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item mail-setup-hook -@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs -Manual}. - -@item mark-diary-entries-hook -@iftex -@inforef{Fancy Diary Display,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Fancy Diary Display,,, emacs}. -@end ifnottex - -@item menu-bar-update-hook -@xref{Menu Bar}. - -@item minibuffer-setup-hook -@xref{Minibuffer Misc}. - -@item minibuffer-exit-hook -@xref{Minibuffer Misc}. - -@item mouse-position-function -@xref{Mouse Position}. - -@item nongregorian-diary-listing-hook -@iftex -@inforef{Non-Gregorian Diary,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Non-Gregorian Diary,,, emacs}. -@end ifnottex - -@item nongregorian-diary-marking-hook -@iftex -@inforef{Non-Gregorian Diary,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Non-Gregorian Diary,,, emacs}. -@end ifnottex - -@item occur-hook - -@item post-command-hook -@xref{Command Overview}. - -@item pre-command-hook -@xref{Command Overview}. - -@item print-diary-entries-hook -@iftex -@inforef{Diary Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Diary Customizing,,, emacs}. -@end ifnottex - -@item resume-tty-functions -@xref{Suspending Emacs}. - -@item scheme-indent-function - -@item suspend-hook -@xref{Suspending Emacs}. - -@item suspend-resume-hook -@xref{Suspending Emacs}. - -@item suspend-tty-functions -@xref{Suspending Emacs}. - -@item temp-buffer-setup-hook -@xref{Temporary Displays}. - -@item temp-buffer-show-function -@xref{Temporary Displays}. - -@item temp-buffer-show-hook -@xref{Temporary Displays}. - -@item term-setup-hook -@xref{Terminal-Specific}. - -@item today-visible-calendar-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item today-invisible-calendar-hook -@iftex -@inforef{Calendar Customizing,, emacs-xtra}. -@end iftex -@ifnottex -@xref{Calendar Customizing,,, emacs}. -@end ifnottex - -@item window-configuration-change-hook -@xref{Window Hooks}. - -@item window-scroll-functions -@xref{Window Hooks}. - -@item window-setup-hook -@xref{Window Systems}. - -@item window-size-change-functions -@xref{Window Hooks}. - -@item write-contents-functions -@xref{Saving Buffers}. - -@item write-file-functions -@xref{Saving Buffers}. - -@item write-region-annotate-functions -@xref{Format Conversion}. -@end table - -@ignore - arch-tag: 55fd0296-d906-4551-b300-979d3846aa88 -@end ignore diff --git a/doc/lispref/index.texi b/doc/lispref/index.texi deleted file mode 100644 index 6cdadf94491..00000000000 --- a/doc/lispref/index.texi +++ /dev/null @@ -1,29 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../../info/index - -@c Indexing guidelines - -@c I assume that all indexes will be combined. -@c Therefore, if a generated findex and permutations -@c cover the ways an index user would look up the entry, -@c then no cindex is added. -@c Concept index (cindex) entries will also be permuted. Therefore, they -@c have no commas and few irrelevant connectives in them. - -@c I tried to include words in a cindex that give the context of the entry, -@c particularly if there is more than one entry for the same concept. -@c For example, "nil in keymap" -@c Similarly for explicit findex and vindex entries, e.g. "print example". - -@c Error codes are given cindex entries, e.g. "end-of-file error". - -@c pindex is used for .el files and Unix programs - -@node Index, , Standard Hooks, Top -@unnumbered Index - -@c Print the indices - -@printindex fn - - diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi deleted file mode 100644 index e2814983770..00000000000 --- a/doc/lispref/internals.texi +++ /dev/null @@ -1,1404 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2001, 2002, 2003, -@c 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/internals -@node GNU Emacs Internals, Standard Errors, Tips, Top -@comment node-name, next, previous, up -@appendix GNU Emacs Internals - -This chapter describes how the runnable Emacs executable is dumped with -the preloaded Lisp libraries in it, how storage is allocated, and some -internal aspects of GNU Emacs that may be of interest to C programmers. - -@menu -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. -@end menu - -@node Building Emacs -@appendixsec Building Emacs -@cindex building Emacs -@pindex temacs - - This section explains the steps involved in building the Emacs -executable. You don't have to know this material to build and install -Emacs, since the makefiles do all these things automatically. This -information is pertinent to Emacs maintenance. - - Compilation of the C source files in the @file{src} directory -produces an executable file called @file{temacs}, also called a -@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O -routines, but not the editing commands. - -@cindex @file{loadup.el} - The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create -the real runnable Emacs executable. These arguments direct -@file{temacs} to evaluate the Lisp files specified in the file -@file{loadup.el}. These files set up the normal Emacs editing -environment, resulting in an Emacs that is still impure but no longer -bare. - -@cindex dumping Emacs - It takes a substantial time to load the standard Lisp files. Luckily, -you don't have to do this each time you run Emacs; @file{temacs} can -dump out an executable program called @file{emacs} that has these files -preloaded. @file{emacs} starts more quickly because it does not need to -load the files. This is the Emacs executable that is normally -installed. - - To create @file{emacs}, use the command @samp{temacs -batch -l loadup -dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} -from trying to initialize any of its data on the terminal; this ensures -that the tables of terminal information are empty in the dumped Emacs. -The argument @samp{dump} tells @file{loadup.el} to dump a new executable -named @file{emacs}. - - Some operating systems don't support dumping. On those systems, you -must start Emacs with the @samp{temacs -l loadup} command each time you -use it. This takes a substantial time, but since you need to start -Emacs once a day at most---or once a week if you never log out---the -extra time is not too severe a problem. - -@cindex @file{site-load.el} - - You can specify additional files to preload by writing a library named -@file{site-load.el} that loads them. You may need to add a definition - -@example -#define SITELOAD_PURESIZE_EXTRA @var{n} -@end example - -@noindent -to make @var{n} added bytes of pure space to hold the additional files. -(Try adding increments of 20000 until it is big enough.) However, the -advantage of preloading additional files decreases as machines get -faster. On modern machines, it is usually not advisable. - - After @file{loadup.el} reads @file{site-load.el}, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file @file{etc/DOC} where they are stored, by -calling @code{Snarf-documentation} (@pxref{Definition of -Snarf-documentation,, Accessing Documentation}). - -@cindex @file{site-init.el} -@cindex preloading additional functions and variables - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named @file{site-init.el}. This file is -executed after the documentation strings are found. - - If you want to preload function or variable definitions, there are -three ways you can do this and make their documentation strings -accessible when you subsequently run Emacs: - -@itemize @bullet -@item -Arrange to scan these files when producing the @file{etc/DOC} file, -and load them with @file{site-load.el}. - -@item -Load the files with @file{site-init.el}, then copy the files into the -installation directory for Lisp files when you install Emacs. - -@item -Specify a non-@code{nil} value for -@code{byte-compile-dynamic-docstrings} as a local variable in each of these -files, and load them with either @file{site-load.el} or -@file{site-init.el}. (This method has the drawback that the -documentation strings take up space in Emacs all the time.) -@end itemize - - It is not advisable to put anything in @file{site-load.el} or -@file{site-init.el} that would alter any of the features that users -expect in an ordinary unmodified Emacs. If you feel you must override -normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Startup Summary}. - - In a package that can be preloaded, it is sometimes useful to -specify a computation to be done when Emacs subsequently starts up. -For this, use @code{eval-at-startup}: - -@defmac eval-at-startup body@dots{} -This evaluates the @var{body} forms, either immediately if running in -an Emacs that has already started up, or later when Emacs does start -up. Since the value of the @var{body} forms is not necessarily -available when the @code{eval-at-startup} form is run, that form -always returns @code{nil}. -@end defmac - -@defun dump-emacs to-file from-file -@cindex unexec -This function dumps the current state of Emacs into an executable file -@var{to-file}. It takes symbols from @var{from-file} (this is normally -the executable file @file{temacs}). - -If you want to use this function in an Emacs that was already dumped, -you must run Emacs with @samp{-batch}. -@end defun - -@node Pure Storage -@appendixsec Pure Storage -@cindex pure storage - - Emacs Lisp uses two kinds of storage for user-created Lisp objects: -@dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session are kept; see the -following section for information on normal storage. Pure storage is -used for certain data in the preloaded standard Lisp files---data that -should never change during actual use of Emacs. - - Pure storage is allocated only while @file{temacs} is loading the -standard preloaded Lisp libraries. In the file @file{emacs}, it is -marked as read-only (on operating systems that permit this), so that -the memory space can be shared by all the Emacs jobs running on the -machine at once. Pure storage is not expandable; a fixed amount is -allocated when Emacs is compiled, and if that is not sufficient for -the preloaded libraries, @file{temacs} allocates dynamic memory for -the part that didn't fit. If that happens, you should increase the -compilation parameter @code{PURESIZE} in the file -@file{src/puresize.h} and rebuild Emacs, even though the resulting -image will work: garbage collection is disabled in this situation, -causing a memory leak. Such an overflow normally won't happen unless you -try to preload additional libraries or add features to the standard -ones. Emacs will display a warning about the overflow when it -starts. - -@defun purecopy object -This function makes a copy in pure storage of @var{object}, and returns -it. It copies a string by simply making a new string with the same -characters, but without text properties, in pure storage. It -recursively copies the contents of vectors and cons cells. It does -not make copies of other objects such as symbols, but just returns -them unchanged. It signals an error if asked to copy markers. - -This function is a no-op except while Emacs is being built and dumped; -it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but -a few packages call it just in case you decide to preload them. -@end defun - -@defvar pure-bytes-used -The value of this variable is the number of bytes of pure storage -allocated so far. Typically, in a dumped Emacs, this number is very -close to the total amount of pure storage available---if it were not, -we would preallocate less. -@end defvar - -@defvar purify-flag -This variable determines whether @code{defun} should make a copy of the -function definition in pure storage. If it is non-@code{nil}, then the -function definition is copied into pure storage. - -This flag is @code{t} while loading all of the basic functions for -building Emacs initially (allowing those functions to be sharable and -non-collectible). Dumping Emacs as an executable always writes -@code{nil} in this variable, regardless of the value it actually has -before and after dumping. - -You should not change this flag in a running Emacs. -@end defvar - -@node Garbage Collection -@appendixsec Garbage Collection -@cindex garbage collection - -@cindex memory allocation - When a program creates a list or the user defines a new function (such -as by loading a library), that data is placed in normal storage. If -normal storage runs low, then Emacs asks the operating system to -allocate more memory in blocks of 1k bytes. Each block is used for one -type of Lisp object, so symbols, cons cells, markers, etc., are -segregated in distinct blocks in memory. (Vectors, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small strings are -packed into blocks of 8k bytes.) - - It is quite common to use some storage for a while, then release it by -(for example) killing a buffer or deleting the last pointer to an -object. Emacs provides a @dfn{garbage collector} to reclaim this -abandoned storage. (This name is traditional, but ``garbage recycler'' -might be a more intuitive metaphor for this facility.) - - The garbage collector operates by finding and marking all Lisp objects -that are still accessible to Lisp programs. To begin with, it assumes -all the symbols, their values and associated function definitions, and -any data presently on the stack, are accessible. Any objects that can -be reached indirectly through other accessible objects are also -accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. - -@c ??? Maybe add something describing weak hash tables here? - -@cindex free list - The sweep phase puts unused cons cells onto a @dfn{free list} -for future allocation; likewise for symbols and markers. It compacts -the accessible strings so they occupy fewer 8k blocks; then it frees the -other 8k blocks. Vectors, buffers, windows, and other large objects are -individually allocated and freed using @code{malloc} and @code{free}. - -@cindex CL note---allocate more storage -@quotation -@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not -call the garbage collector when the free list is empty. Instead, it -simply requests the operating system to allocate more storage, and -processing continues until @code{gc-cons-threshold} bytes have been -used. - -This means that you can make sure that the garbage collector will not -run during a certain portion of a Lisp program by calling the garbage -collector explicitly just before it (provided that portion of the -program does not use so much space as to force a second garbage -collection). -@end quotation - -@deffn Command garbage-collect -This command runs a garbage collection, and returns information on -the amount of space in use. (Garbage collection can also occur -spontaneously if you use more than @code{gc-cons-threshold} bytes of -Lisp data since the previous garbage collection.) - -@code{garbage-collect} returns a list containing the following -information: - -@example -@group -((@var{used-conses} . @var{free-conses}) - (@var{used-syms} . @var{free-syms}) -@end group - (@var{used-miscs} . @var{free-miscs}) - @var{used-string-chars} - @var{used-vector-slots} - (@var{used-floats} . @var{free-floats}) - (@var{used-intervals} . @var{free-intervals}) - (@var{used-strings} . @var{free-strings})) -@end example - -Here is an example: - -@example -@group -(garbage-collect) - @result{} ((106886 . 13184) (9769 . 0) - (7731 . 4651) 347543 121628 - (31 . 94) (1273 . 168) - (25474 . 3569)) -@end group -@end example - -Here is a table explaining each element: - -@table @var -@item used-conses -The number of cons cells in use. - -@item free-conses -The number of cons cells for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-syms -The number of symbols in use. - -@item free-syms -The number of symbols for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-miscs -The number of miscellaneous objects in use. These include markers and -overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - -@item used-string-chars -The total size of all strings, in characters. - -@item used-vector-slots -The total number of elements of existing vectors. - -@item used-floats -@c Emacs 19 feature -The number of floats in use. - -@item free-floats -@c Emacs 19 feature -The number of floats for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-intervals -The number of intervals in use. Intervals are an internal -data structure used for representing text properties. - -@item free-intervals -The number of intervals for which space has been obtained -from the operating system, but that are not currently being used. - -@item used-strings -The number of strings in use. - -@item free-strings -The number of string headers for which the space was obtained from the -operating system, but which are currently not in use. (A string -object consists of a header and the storage for the string text -itself; the latter is only allocated when the string is created.) -@end table - -If there was overflow in pure space (see the previous section), -@code{garbage-collect} returns @code{nil}, because a real garbage -collection can not be done in this situation. -@end deffn - -@defopt garbage-collection-messages -If this variable is non-@code{nil}, Emacs displays a message at the -beginning and end of garbage collection. The default value is -@code{nil}, meaning there are no such messages. -@end defopt - -@defvar post-gc-hook -This is a normal hook that is run at the end of garbage collection. -Garbage collection is inhibited while the hook functions run, so be -careful writing them. -@end defvar - -@defopt gc-cons-threshold -The value of this variable is the number of bytes of storage that must -be allocated for Lisp objects after one garbage collection in order to -trigger another garbage collection. A cons cell counts as eight bytes, -a string as one byte per character plus a few bytes of overhead, and so -on; space allocated to the contents of buffers does not count. Note -that the subsequent garbage collection does not happen immediately when -the threshold is exhausted, but only the next time the Lisp evaluator is -called. - -The initial threshold value is 400,000. If you specify a larger -value, garbage collection will happen less often. This reduces the -amount of time spent garbage collecting, but increases total memory use. -You may want to do this when running a program that creates lots of -Lisp data. - -You can make collections more frequent by specifying a smaller value, -down to 10,000. A value less than 10,000 will remain in effect only -until the subsequent garbage collection, at which time -@code{garbage-collect} will set the threshold back to 10,000. -@end defopt - -@defopt gc-cons-percentage -The value of this variable specifies the amount of consing before a -garbage collection occurs, as a fraction of the current heap size. -This criterion and @code{gc-cons-threshold} apply in parallel, and -garbage collection occurs only when both criteria are satisfied. - -As the heap size increases, the time to perform a garbage collection -increases. Thus, it can be desirable to do them less frequently in -proportion. -@end defopt - - The value returned by @code{garbage-collect} describes the amount of -memory used by Lisp data, broken down by data type. By contrast, the -function @code{memory-limit} provides information on the total amount of -memory Emacs is currently using. - -@c Emacs 19 feature -@defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - -You can use this to get a general idea of how your actions affect the -memory usage. -@end defun - -@defvar memory-full -This variable is @code{t} if Emacs is close to out of memory for Lisp -objects, and @code{nil} otherwise. -@end defvar - -@defun memory-use-counts -This returns a list of numbers that count the number of objects -created in this Emacs session. Each of these counters increments for -a certain kind of object. See the documentation string for details. -@end defun - -@defvar gcs-done -This variable contains the total number of garbage collections -done so far in this Emacs session. -@end defvar - -@defvar gc-elapsed -This variable contains the total number of seconds of elapsed time -during garbage collection so far in this Emacs session, as a floating -point number. -@end defvar - -@node Memory Usage -@section Memory Usage -@cindex memory usage - - These functions and variables give information about the total amount -of memory allocation that Emacs has done, broken down by data type. -Note the difference between these and the values returned by -@code{(garbage-collect)}; those count objects that currently exist, but -these count the number or size of all allocations, including those for -objects that have since been freed. - -@defvar cons-cells-consed -The total number of cons cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar floats-consed -The total number of floats that have been allocated so far -in this Emacs session. -@end defvar - -@defvar vector-cells-consed -The total number of vector cells that have been allocated so far -in this Emacs session. -@end defvar - -@defvar symbols-consed -The total number of symbols that have been allocated so far -in this Emacs session. -@end defvar - -@defvar string-chars-consed -The total number of string characters that have been allocated so far -in this Emacs session. -@end defvar - -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this Emacs session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - -@defvar intervals-consed -The total number of intervals that have been allocated so far -in this Emacs session. -@end defvar - -@defvar strings-consed -The total number of strings that have been allocated so far in this -Emacs session. -@end defvar - -@node Writing Emacs Primitives -@appendixsec Writing Emacs Primitives -@cindex primitive function internals -@cindex writing Emacs primitives - - Lisp primitives are Lisp functions implemented in C. The details of -interfacing the C function so that Lisp can call it are handled by a few -C macros. The only way to really understand how to write new C code is -to read the source, but we can explain some things here. - - An example of a special form is the definition of @code{or}, from -@file{eval.c}. (An ordinary function would have the same general -appearance.) - -@cindex garbage collection protection -@smallexample -@group -DEFUN ("or", For, Sor, 0, UNEVALLED, 0, - doc: /* Eval args until one of them yields non-nil, then return that -value. The remaining args are not evalled at all. -If all args return nil, return nil. -@end group -@group -usage: (or CONDITIONS ...) */) - (args) - Lisp_Object args; -@{ - register Lisp_Object val = Qnil; - struct gcpro gcpro1; -@end group - -@group - GCPRO1 (args); -@end group - -@group - while (CONSP (args)) - @{ - val = Feval (XCAR (args)); - if (!NILP (val)) - break; - args = XCDR (args); - @} -@end group - -@group - UNGCPRO; - return val; -@} -@end group -@end smallexample - -@cindex @code{DEFUN}, C macro to define Lisp primitives - Let's start with a precise explanation of the arguments to the -@code{DEFUN} macro. Here is a template for them: - -@example -DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) -@end example - -@table @var -@item lname -This is the name of the Lisp symbol to define as the function name; in -the example above, it is @code{or}. - -@item fname -This is the C function name for this function. This is -the name that is used in C code for calling the function. The name is, -by convention, @samp{F} prepended to the Lisp name, with all dashes -(@samp{-}) in the Lisp name changed to underscores. Thus, to call this -function from C code, call @code{For}. Remember that the arguments must -be of type @code{Lisp_Object}; various macros and functions for creating -values of type @code{Lisp_Object} are declared in the file -@file{lisp.h}. - -@item sname -This is a C variable name to use for a structure that holds the data for -the subr object that represents the function in Lisp. This structure -conveys the Lisp symbol name to the initialization routine that will -create the symbol and store the subr object as its definition. By -convention, this name is always @var{fname} with @samp{F} replaced with -@samp{S}. - -@item min -This is the minimum number of arguments that the function requires. The -function @code{or} allows a minimum of zero arguments. - -@item max -This is the maximum number of arguments that the function accepts, if -there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, -indicating a special form that receives unevaluated arguments, or -@code{MANY}, indicating an unlimited number of evaluated arguments (the -equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are -macros. If @var{max} is a number, it may not be less than @var{min} and -it may not be greater than eight. - -@item interactive -This is an interactive specification, a string such as might be used as -the argument of @code{interactive} in a Lisp function. In the case of -@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be -called interactively. A value of @code{""} indicates a function that -should receive no arguments when called interactively. If the value -begins with a @samp{(}, the string is evaluated as a Lisp form. - -@item doc -This is the documentation string. It uses C comment syntax rather -than C string syntax because comment syntax requires nothing special -to include multiple lines. The @samp{doc:} identifies the comment -that follows as the documentation string. The @samp{/*} and @samp{*/} -delimiters that begin and end the comment are not part of the -documentation string. - -If the last line of the documentation string begins with the keyword -@samp{usage:}, the rest of the line is treated as the argument list -for documentation purposes. This way, you can use different argument -names in the documentation string from the ones used in the C code. -@samp{usage:} is required if the function has an unlimited number of -arguments. - -All the usual rules for documentation strings in Lisp code -(@pxref{Documentation Tips}) apply to C code documentation strings -too. -@end table - - After the call to the @code{DEFUN} macro, you must write the argument -name list that every C function must have, followed by ordinary C -declarations for the arguments. For a function with a fixed maximum -number of arguments, declare a C argument for each Lisp argument, and -give them all type @code{Lisp_Object}. When a Lisp function has no -upper limit on the number of arguments, its implementation in C actually -receives exactly two arguments: the first is the number of Lisp -arguments, and the second is the address of a block containing their -values. They have types @code{int} and @w{@code{Lisp_Object *}}. - -@cindex @code{GCPRO} and @code{UNGCPRO} -@cindex protect C variables from garbage collection - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to -``protect'' a variable from garbage collection---to inform the garbage -collector that it must look in that variable and regard its contents -as an accessible object. GC protection is necessary whenever you call -@code{Feval} or anything that can directly or indirectly call -@code{Feval}. At such a time, any Lisp object that this function may -refer to again must be protected somehow. - - It suffices to ensure that at least one pointer to each object is -GC-protected; that way, the object cannot be recycled, so all pointers -to it remain valid. Thus, a particular local variable can do without -protection if it is certain that the object it points to will be -preserved by some other pointer (such as another local variable which -has a @code{GCPRO})@footnote{Formerly, strings were a special -exception; in older Emacs versions, every local variable that might -point to a string needed a @code{GCPRO}.}. Otherwise, the local -variable needs a @code{GCPRO}. - - The macro @code{GCPRO1} protects just one local variable. If you -want to protect two variables, use @code{GCPRO2} instead; repeating -@code{GCPRO1} will not work. Macros @code{GCPRO3}, @code{GCPRO4}, -@code{GCPRO5}, and @code{GCPRO6} also exist. All these macros -implicitly use local variables such as @code{gcpro1}; you must declare -these explicitly, with type @code{struct gcpro}. Thus, if you use -@code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. -Alas, we can't explain all the tricky details here. - - @code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this -explicitly. - - Built-in functions that take a variable number of arguments actually -accept two arguments at the C level: the number of Lisp arguments, and -a @code{Lisp_Object *} pointer to a C vector containing those Lisp -arguments. This C vector may be part of a Lisp vector, but it need -not be. The responsibility for using @code{GCPRO} to protect the Lisp -arguments from GC if necessary rests with the caller in this case, -since the caller allocated or found the storage for them. - - You must not use C initializers for static or global variables unless -the variables are never written once Emacs is dumped. These variables -with initializers are allocated in an area of memory that becomes -read-only (on certain operating systems) as a result of dumping Emacs. -@xref{Pure Storage}. - - Do not use static variables within functions---place all static -variables at top level in the file. This is necessary because Emacs on -some operating systems defines the keyword @code{static} as a null -macro. (This definition is used because those systems put all variables -declared static in a place that becomes read-only after dumping, whether -they have initializers or not.) - -@cindex @code{defsubr}, Lisp symbol for a primitive - Defining the C function is not enough to make a Lisp primitive -available; you must also create the Lisp symbol for the primitive and -store a suitable subr object in its function cell. The code looks like -this: - -@example -defsubr (&@var{subr-structure-name}); -@end example - -@noindent -Here @var{subr-structure-name} is the name you used as the third -argument to @code{DEFUN}. - - If you add a new primitive to a file that already has Lisp primitives -defined in it, find the function (near the end of the file) named -@code{syms_of_@var{something}}, and add the call to @code{defsubr} -there. If the file doesn't have this function, or if you create a new -file, add to it a @code{syms_of_@var{filename}} (e.g., -@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all -of these functions are called, and add a call to -@code{syms_of_@var{filename}} there. - -@anchor{Defining Lisp variables in C} -@vindex byte-boolean-vars -@cindex defining Lisp variables in C -@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL} - The function @code{syms_of_@var{filename}} is also the place to define -any C variables that are to be visible as Lisp variables. -@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible -in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} -visible in Lisp with a value that is always an integer. -@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. Note that variables -defined with @code{DEFVAR_BOOL} are automatically added to the list -@code{byte-boolean-vars} used by the byte compiler. - -@cindex @code{staticpro}, protection from GC - If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it from garbage-collection by calling @code{staticpro} -in @code{syms_of_@var{filename}}, like this: - -@example -staticpro (&@var{variable}); -@end example - - Here is another example function, with more complicated arguments. -This comes from the code in @file{window.c}, and it demonstrates the use -of macros and functions to manipulate Lisp objects. - -@smallexample -@group -DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, - Scoordinates_in_window_p, 2, 2, - "xSpecify coordinate pair: \nXExpression which evals to window: ", - "Return non-nil if COORDINATES is in WINDOW.\n\ -COORDINATES is a cons of the form (X . Y), X and Y being distances\n\ -... -@end group -@group -If they are on the border between WINDOW and its right sibling,\n\ - `vertical-line' is returned.") - (coordinates, window) - register Lisp_Object coordinates, window; -@{ - int x, y; -@end group - -@group - CHECK_LIVE_WINDOW (window, 0); - CHECK_CONS (coordinates, 1); - x = XINT (Fcar (coordinates)); - y = XINT (Fcdr (coordinates)); -@end group - -@group - switch (coordinates_in_window (XWINDOW (window), &x, &y)) - @{ - case 0: /* NOT in window at all. */ - return Qnil; -@end group - -@group - case 1: /* In text part of window. */ - return Fcons (make_number (x), make_number (y)); -@end group - -@group - case 2: /* In mode line of window. */ - return Qmode_line; -@end group - -@group - case 3: /* On right border of window. */ - return Qvertical_line; -@end group - -@group - default: - abort (); - @} -@} -@end group -@end smallexample - - Note that C code cannot call functions by name unless they are defined -in C. The way to call a function written in Lisp is to use -@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since -the Lisp function @code{funcall} accepts an unlimited number of -arguments, in C it takes two: the number of Lisp-level arguments, and a -one-dimensional array containing their values. The first Lisp-level -argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. - - The C functions @code{call0}, @code{call1}, @code{call2}, and so on, -provide handy ways to call a Lisp function conveniently with a fixed -number of arguments. They work by calling @code{Ffuncall}. - - @file{eval.c} is a very good file to look through for examples; -@file{lisp.h} contains the definitions for some important macros and -functions. - - If you define a function which is side-effect free, update the code -in @file{byte-opt.el} which binds @code{side-effect-free-fns} and -@code{side-effect-and-error-free-fns} so that the compiler optimizer -knows about it. - -@node Object Internals -@appendixsec Object Internals -@cindex object internals - - GNU Emacs Lisp manipulates many different types of data. The actual -data are stored in a heap and the only access that programs have to it -is through pointers. Each pointer is 32 bits wide on 32-bit machines, -and 64 bits wide on 64-bit machines; three of these bits are used for -the tag that identifies the object's type, and the remainder are used -to address the object. - - Because Lisp objects are represented as tagged pointers, it is always -possible to determine the Lisp data type of any object. The C data type -@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary -variables have type @code{Lisp_Object}, which means they can hold any -type of Lisp value; you can determine the actual data type only at run -time. The same is true for function arguments; if you want a function -to accept only a certain type of argument, you must check the type -explicitly using a suitable predicate (@pxref{Type Predicates}). -@cindex type checking internals - -@menu -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@node Buffer Internals -@appendixsubsec Buffer Internals -@cindex internals, of buffer -@cindex buffer internals - - Two structures are used to represent buffers in C. The -@code{buffer_text} structure contains fields describing the text of a -buffer; the @code{buffer} structure holds other fields. In the case -of indirect buffers, two or more @code{buffer} structures reference -the same @code{buffer_text} structure. - -Here are some of the fields in @code{struct buffer_text}: - -@table @code -@item beg -The address of the buffer contents. - -@item gpt -@itemx gpt_byte -The character and byte positions of the buffer gap. @xref{Buffer -Gap}. - -@item z -@itemx z_byte -The character and byte positions of the end of the buffer text. - -@item gap_size -The size of buffer's gap. @xref{Buffer Gap}. - -@item modiff -@itemx save_modiff -@itemx chars_modiff -@itemx overlay_modiff -These fields count the number of buffer-modification events performed -in this buffer. @code{modiff} is incremented after each -buffer-modification event, and is never otherwise changed; -@code{save_modiff} contains the value of @code{modiff} the last time -the buffer was visited or saved; @code{chars_modiff} counts only -modifications to the characters in the buffer, ignoring all other -kinds of changes; and @code{overlay_modiff} counts only modifications -to the overlays. - -@item beg_unchanged -@itemx end_unchanged -The number of characters at the start and end of the text that are -known to be unchanged since the last complete redisplay. - -@item unchanged_modified -@itemx overlay_unchanged_modified -The values of @code{modiff} and @code{overlay_modiff}, respectively, -after the last compelete redisplay. If their current values match -@code{modiff} or @code{overlay_modiff}, that means -@code{beg_unchanged} and @code{end_unchanged} contain no useful -information. - -@item markers -The markers that refer to this buffer. This is actually a single -marker, and successive elements in its marker @code{chain} are the other -markers referring to this buffer text. - -@item intervals -The interval tree which records the text properties of this buffer. -@end table - -Some of the fields of @code{struct buffer} are: - -@table @code -@item next -Points to the next buffer, in the chain of all buffers (including -killed buffers). This chain is used only for garbage collection, in -order to collect killed buffers properly. Note that vectors, and most -kinds of objects allocated as vectors, are all on one chain, but -buffers are on a separate chain of their own. - -@item own_text -A @code{struct buffer_text} structure that ordinarily holds the buffer -contents. In indirect buffers, this field is not used. - -@item text -A pointer to the @code{buffer_text} structure for this buffer. In an -ordinary buffer, this is the @code{own_text} field above. In an -indirect buffer, this is the @code{own_text} field of the base buffer. - -@item pt -@itemx pt_byte -The character and byte positions of point in a buffer. - -@item begv -@itemx begv_byte -The character and byte positions of the beginning of the accessible -range of text in the buffer. - -@item zv -@itemx zv_byte -The character and byte positions of the end of the accessible range of -text in the buffer. - -@item base_buffer -In an indirect buffer, this points to the base buffer. In an ordinary -buffer, it is null. - -@item local_flags -This field contains flags indicating that certain variables are local -in this buffer. Such variables are declared in the C code using -@code{DEFVAR_PER_BUFFER}, and their buffer-local bindings are stored -in fields in the buffer structure itself. (Some of these fields are -described in this table.) - -@item modtime -The modification time of the visited file. It is set when the file is -written or read. Before writing the buffer into a file, this field is -compared to the modification time of the file to see if the file has -changed on disk. @xref{Buffer Modification}. - -@item auto_save_modified -The time when the buffer was last auto-saved. - -@item last_window_start -The @code{window-start} position in the buffer as of the last time the -buffer was displayed in a window. - -@item clip_changed -This flag indicates that narrowing has changed in the buffer. -@xref{Narrowing}. - -@item prevent_redisplay_optimizations_p -This flag indicates that redisplay optimizations should not be used to -display this buffer. - -@item overlay_center -This field holds the current overlay center position. @xref{Managing -Overlays}. - -@item overlays_before -@itemx overlays_after -These fields hold, respectively, a list of overlays that end at or -before the current overlay center, and a list of overlays that end -after the current overlay center. @xref{Managing Overlays}. -@code{overlays_before} is sorted in order of decreasing end position, -and @code{overlays_after} is sorted in order of increasing beginning -position. - -@item name -A Lisp string that names the buffer. It is guaranteed to be unique. -@xref{Buffer Names}. - -@item save_length -The length of the file this buffer is visiting, when last read or -saved. This and other fields concerned with saving are not kept in -the @code{buffer_text} structure because indirect buffers are never -saved. - -@item directory -The directory for expanding relative file names. This is the value of -the buffer-local variable @code{default-directory} (@pxref{File Name Expansion}). - -@item filename -The name of the file visited in this buffer, or @code{nil}. This is -the value of the buffer-local variable @code{buffer-file-name} -(@pxref{Buffer File Name}). - -@item undo_list -@itemx backed_up -@itemx auto_save_file_name -@itemx read_only -@itemx file_format -@itemx file_truename -@itemx invisibility_spec -@itemx display_count -@itemx display_time -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have the additional prefix @code{buffer-} and have -underscores replaced with dashes. For instance, @code{undo_list} -stores the value of @code{buffer-undo-list}. @xref{Standard -Buffer-Local Variables}. - -@item mark -The mark for the buffer. The mark is a marker, hence it is also -included on the list @code{markers}. @xref{The Mark}. - -@item local_var_alist -The association list describing the buffer-local variable bindings of -this buffer, not including the built-in buffer-local bindings that -have special slots in the buffer object. (Those slots are omitted -from this table.) @xref{Buffer-Local Variables}. - -@item major_mode -Symbol naming the major mode of this buffer, e.g., @code{lisp-mode}. - -@item mode_name -Pretty name of the major mode, e.g., @code{"Lisp"}. - -@item keymap -@itemx abbrev_table -@itemx syntax_table -@itemx category_table -@itemx display_table -These fields store the buffer's local keymap (@pxref{Keymaps}), abbrev -table (@pxref{Abbrev Tables}), syntax table (@pxref{Syntax Tables}), -category table (@pxref{Categories}), and display table (@pxref{Display -Tables}). - -@item downcase_table -@itemx upcase_table -@itemx case_canon_table -These fields store the conversion tables for converting text to lower -case, upper case, and for canonicalizing text for case-fold search. -@xref{Case Tables}. - -@item minor_modes -An alist of the minor modes of this buffer. - -@item pt_marker -@itemx begv_marker -@itemx zv_marker -These fields are only used in an indirect buffer, or in a buffer that -is the base of an indirect buffer. Each holds a marker that records -@code{pt}, @code{begv}, and @code{zv} respectively, for this buffer -when the buffer is not current. - -@item mode_line_format -@itemx header_line_format -@itemx case_fold_search -@itemx tab_width -@itemx fill_column -@itemx left_margin -@itemx auto_fill_function -@itemx truncate_lines -@itemx word_wrap -@itemx ctl_arrow -@itemx selective_display -@itemx selective_display_ellipses -@itemx overwrite_mode -@itemx abbrev_mode -@itemx display_table -@itemx mark_active -@itemx enable_multibyte_characters -@itemx buffer_file_coding_system -@itemx auto_save_file_format -@itemx cache_long_line_scans -@itemx point_before_scroll -@itemx left_fringe_width -@itemx right_fringe_width -@itemx fringes_outside_margins -@itemx scroll_bar_width -@itemx indicate_empty_lines -@itemx indicate_buffer_boundaries -@itemx fringe_indicator_alist -@itemx fringe_cursor_alist -@itemx scroll_up_aggressively -@itemx scroll_down_aggressively -@itemx cursor_type -@itemx cursor_in_non_selected_windows -These fields store the values of Lisp variables that are automatically -buffer-local (@pxref{Buffer-Local Variables}), whose corresponding -variable names have underscores replaced with dashes. For instance, -@code{mode_line_format} stores the value of @code{mode-line-format}. -@xref{Standard Buffer-Local Variables}. - -@item last_selected_window -This is the last window that was selected with this buffer in it, or @code{nil} -if that window no longer displays this buffer. -@end table - -@node Window Internals -@appendixsubsec Window Internals -@cindex internals, of window -@cindex window internals - - Windows have the following accessible fields: - -@table @code -@item frame -The frame that this window is on. - -@item mini_p -Non-@code{nil} if this window is a minibuffer window. - -@item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. - -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. - -@item hchild -@itemx vchild -These fields contain the window's leftmost child and its topmost child -respectively. @code{hchild} is used if the window is subdivided -horizontally by child windows, and @code{vchild} if it is subdivided -vertically. - -@item next -@itemx prev -The next sibling and previous sibling of this window. @code{next} is -@code{nil} if the window is the rightmost or bottommost in its group; -@code{prev} is @code{nil} if it is the leftmost or topmost in its -group. - -@item left_col -The left-hand edge of the window, measured in columns, relative to the -leftmost column in the frame (column 0). - -@item top_line -The top edge of the window, measured in lines, relative to the topmost -line in the frame (line 0). - -@item total_cols -@itemx total_lines -The width and height of the window, measured in columns and lines -respectively. The width includes the scroll bar and fringes, and/or -the separator line on the right of the window (if any). - -@item buffer -The buffer that the window is displaying. - -@item start -A marker pointing to the position in the buffer that is the first -character displayed in the window. - -@item pointm -@cindex window point internals -This is the value of point in the current buffer when this window is -selected; when it is not selected, it retains its previous value. - -@item force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. - -@item frozen_window_start_p -This field is set temporarily to 1 to indicate to redisplay that -@code{start} of this window should not be changed, even if point -gets invisible. - -@item start_at_line_beg -Non-@code{nil} means current value of @code{start} was the beginning of a line -when it was chosen. - -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. - -@item sequence_number -A unique number assigned to this window when it was created. - -@item last_modified -The @code{modiff} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_overlay_modified -The @code{overlay_modiff} field of the window's buffer, as of the last -time a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time a redisplay completed -in this window. - -@item last_had_star -A non-@code{nil} value means the window's buffer was ``modified'' when the -window was last updated. - -@item vertical_scroll_bar -This window's vertical scroll bar. - -@item left_margin_width -@itemx right_margin_width -The widths of the left and right margins in this window. A value of -@code{nil} means to use the buffer's value of @code{left-margin-width} -or @code{right-margin-width}. - -@item window_end_pos -This is computed as @code{z} minus the buffer position of the last glyph -in the current matrix of the window. The value is only valid if -@code{window_end_valid} is not @code{nil}. - -@item window_end_bytepos -The byte position corresponding to @code{window_end_pos}. - -@item window_end_vpos -The window-relative vertical position of the line containing -@code{window_end_pos}. - -@item window_end_valid -This field is set to a non-@code{nil} value if @code{window_end_pos} is truly -valid. This is @code{nil} if nontrivial redisplay is preempted since in that -case the display that @code{window_end_pos} was computed for did not get -onto the screen. - -@item cursor -A structure describing where the cursor is in this window. - -@item last_cursor -The value of @code{cursor} as of the last redisplay that finished. - -@item phys_cursor -A structure describing where the cursor of this window physically is. - -@item phys_cursor_type -The type of cursor that was last displayed on this window. - -@item phys_cursor_on_p -This field is non-zero if the cursor is physically on. - -@item cursor_off_p -Non-zero means the cursor in this window is logically on. - -@item last_cursor_off_p -This field contains the value of @code{cursor_off_p} as of the time of -the last redisplay. - -@item must_be_updated_p -This is set to 1 during redisplay when this window must be updated. - -@item hscroll -This is the number of columns that the display in the window is scrolled -horizontally to the left. Normally, this is 0. - -@item vscroll -Vertical scroll amount, in pixels. Normally, this is 0. - -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. - -@item display_table -The window's display table, or @code{nil} if none is specified for it. - -@item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. - -@item base_line_number -The line number of a certain position in the buffer, or @code{nil}. -This is used for displaying the line number of point in the mode line. - -@item base_line_pos -The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. - -@item region_showing -If the region (or part of it) is highlighted in this window, this field -holds the mark position that made one end of that region. Otherwise, -this field is @code{nil}. - -@item column_number_displayed -The column number currently displayed in this window's mode line, or @code{nil} -if column numbers are not being displayed. - -@item current_matrix -A glyph matrix describing the current display of this window. - -@item desired_matrix -A glyph matrix describing the desired display of this window. -@end table - -@node Process Internals -@appendixsubsec Process Internals -@cindex internals, of process -@cindex process internals - - The fields of a process are: - -@table @code -@item name -A string, the name of the process. - -@item command -A list containing the command arguments that were used to start this -process. For a network or serial process, it is @code{nil} if the -process is running or @code{t} if the process is stopped. - -@item filter -A function used to accept output from the process instead of a buffer, -or @code{nil}. - -@item sentinel -A function called whenever the process receives a signal, or @code{nil}. - -@item buffer -The associated buffer of the process. - -@item pid -An integer, the operating system's process @acronym{ID}. - -@item childp -A flag, non-@code{nil} if this is really a child process. -It is @code{nil} for a network or serial connection. - -@item mark -A marker indicating the position of the end of the last output from this -process inserted into the buffer. This is often but not always the end -of the buffer. - -@item kill_without_query -If this is non-zero, killing Emacs while this process is still running -does not ask for confirmation about killing the process. - -@item raw_status_low -@itemx raw_status_high -These two fields record 16 bits each of the process status returned by -the @code{wait} system call. - -@item status -The process status, as @code{process-status} should return it. - -@item tick -@itemx update_tick -If these two fields are not equal, a change in the status of the process -needs to be reported, either by running the sentinel or by inserting a -message in the process buffer. - -@item pty_flag -Non-@code{nil} if communication with the subprocess uses a @acronym{PTY}; -@code{nil} if it uses a pipe. - -@item infd -The file descriptor for input from the process. - -@item outfd -The file descriptor for output to the process. - -@item subtty -The file descriptor for the terminal that the subprocess is using. (On -some systems, there is no need to record this, so the value is -@code{nil}.) - -@item tty_name -The name of the terminal that the subprocess is using, -or @code{nil} if it is using pipes. - -@item decode_coding_system -Coding-system for decoding the input from this process. - -@item decoding_buf -A working buffer for decoding. - -@item decoding_carryover -Size of carryover in decoding. - -@item encode_coding_system -Coding-system for encoding the output to this process. - -@item encoding_buf -A working buffer for encoding. - -@item encoding_carryover -Size of carryover in encoding. - -@item inherit_coding_system_flag -Flag to set @code{coding-system} of the process buffer from the -coding system used to decode process output. - -@item type -Symbol indicating the type of process: @code{real}, @code{network}, -@code{serial} - -@end table - -@ignore - arch-tag: 4b2c33bc-d7e4-43f5-bc20-27c0db52a53e -@end ignore diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi deleted file mode 100644 index 86ec6eb1661..00000000000 --- a/doc/lispref/intro.texi +++ /dev/null @@ -1,552 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/intro - -@node Introduction, Lisp Data Types, Top, Top -@comment node-name, next, previous, up -@chapter Introduction - - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual attempts to be a full description of Emacs Lisp. For a -beginner's introduction to Emacs Lisp, see @cite{An Introduction to -Emacs Lisp Programming}, by Bob Chassell, also published by the Free -Software Foundation. This manual presumes considerable familiarity with -the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this -basic information. - - Generally speaking, the earlier chapters describe features of Emacs -Lisp that have counterparts in many programming languages, and later -chapters describe features that are peculiar to Emacs Lisp or relate -specifically to editing. - - This is edition @value{VERSION} of the GNU Emacs Lisp Reference -Manual, corresponding to Emacs version @value{EMACSVER}. - -@menu -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. -@end menu - -@node Caveats -@section Caveats -@cindex bugs in this manual - - This manual has gone through numerous drafts. It is nearly complete -but not flawless. There are a few topics that are not covered, either -because we consider them secondary (such as most of the individual -modes) or because they are yet to be written. Because we are not able -to deal with them completely, we have left out several parts -intentionally. - - The manual should be fully correct in what it does cover, and it is -therefore open to criticism on anything it says---from specific examples -and descriptive text, to the ordering of chapters and sections. If -something is confusing, or you find that you have to look at the sources -or experiment to learn something not covered in the manual, then perhaps -the manual should be fixed. Please let us know. - -@iftex - As you use this manual, we ask that you mark pages with corrections so -you can later look them up and send them to us. If you think of a simple, -real-life example for a function or group of functions, please make an -effort to write it up and send it in. Please reference any comments to -the chapter name, section name, and function name, as appropriate, since -page numbers and chapter and section numbers will change and we may have -trouble finding the text you are talking about. Also state the number -of the edition you are criticizing. -@end iftex -@ifnottex - -As you use this manual, we ask that you send corrections as soon as you -find them. If you think of a simple, real life example for a function -or group of functions, please make an effort to write it up and send it -in. Please reference any comments to the node name and function or -variable name, as appropriate. Also state the number of the edition -you are criticizing. -@end ifnottex - -@cindex bugs -@cindex suggestions -Please send comments and corrections using @kbd{M-x report-emacs-bug}. - -@node Lisp History -@section Lisp History -@cindex Lisp history - - Lisp (LISt Processing language) was first developed in the late 1950s -at the Massachusetts Institute of Technology for research in artificial -intelligence. The great power of the Lisp language makes it ideal -for other purposes as well, such as writing editing commands. - -@cindex Maclisp -@cindex Common Lisp - Dozens of Lisp implementations have been built over the years, each -with its own idiosyncrasies. Many of them were inspired by Maclisp, -which was written in the 1960s at MIT's Project MAC. Eventually the -implementors of the descendants of Maclisp came together and developed a -standard for Lisp systems, called Common Lisp. In the meantime, Gerry -Sussman and Guy Steele at MIT developed a simplified but very powerful -dialect of Lisp, called Scheme. - - GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common -Lisp. If you know Common Lisp, you will notice many similarities. -However, many features of Common Lisp have been omitted or -simplified in order to reduce the memory requirements of GNU Emacs. -Sometimes the simplifications are so drastic that a Common Lisp user -might be very confused. We will occasionally point out how GNU Emacs -Lisp differs from Common Lisp. If you don't know Common Lisp, don't -worry about it; this manual is self-contained. - -@pindex cl - A certain amount of Common Lisp emulation is available via the -@file{cl} library. @inforef{Top, Overview, cl}. - - Emacs Lisp is not at all influenced by Scheme; but the GNU project has -an implementation of Scheme, called Guile. We use Guile in all new GNU -software that calls for extensibility. - -@node Conventions -@section Conventions - -This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. - -@menu -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. -@end menu - -@node Some Terms -@subsection Some Terms - - Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp -printer'' refer to those routines in Lisp that convert textual -representations of Lisp objects into actual Lisp objects, and vice -versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you.'' ``The user'' is the person who uses Lisp -programs, including those you write. - -@cindex typographic conventions - Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. -Names that represent metasyntactic variables, or arguments to a function -being described, are formatted like this: @var{first-number}. - -@node nil and t -@subsection @code{nil} and @code{t} -@cindex truth value -@cindex boolean - -@cindex @code{nil} -@cindex false - In Lisp, the symbol @code{nil} has three separate meanings: it -is a symbol with the name @samp{nil}; it is the logical truth value -@var{false}; and it is the empty list---the list of zero elements. -When used as a variable, @code{nil} always has the value @code{nil}. - - As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are -identical: they stand for the same object, the symbol @code{nil}. The -different ways of writing the symbol are intended entirely for human -readers. After the Lisp reader has read either @samp{()} or @samp{nil}, -there is no way to determine which representation was actually written -by the programmer. - - In this manual, we write @code{()} when we wish to emphasize that it -means the empty list, and we write @code{nil} when we wish to emphasize -that it means the truth value @var{false}. That is a good convention to use -in Lisp programs also. - -@example -(cons 'foo ()) ; @r{Emphasize the empty list} -(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} -@end example - -@cindex @code{t} -@cindex true - In contexts where a truth value is expected, any non-@code{nil} value -is considered to be @var{true}. However, @code{t} is the preferred way -to represent the truth value @var{true}. When you need to choose a -value which represents @var{true}, and there is no other basis for -choosing, use @code{t}. The symbol @code{t} always has the value -@code{t}. - - In Emacs Lisp, @code{nil} and @code{t} are special symbols that always -evaluate to themselves. This is so that you do not need to quote them -to use them as constants in a program. An attempt to change their -values results in a @code{setting-constant} error. @xref{Constant -Variables}. - -@defun booleanp object -Return non-@code{nil} if @var{object} is one of the two canonical -boolean values: @code{t} or @code{nil}. -@end defun - -@node Evaluation Notation -@subsection Evaluation Notation -@cindex evaluation notation -@cindex documentation notation -@cindex notation - - A Lisp expression that you can evaluate is called a @dfn{form}. -Evaluating a form always produces a result, which is a Lisp object. In -the examples in this manual, this is indicated with @samp{@result{}}: - -@example -(car '(1 2)) - @result{} 1 -@end example - -@noindent -You can read this as ``@code{(car '(1 2))} evaluates to 1.'' - - When a form is a macro call, it expands into a new form for Lisp to -evaluate. We show the result of the expansion with -@samp{@expansion{}}. We may or may not show the result of the -evaluation of the expanded form. - -@example -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end example - - Sometimes to help describe one form we show another form that -produces identical results. The exact equivalence of two forms is -indicated with @samp{@equiv{}}. - -@example -(make-sparse-keymap) @equiv{} (list 'keymap) -@end example - -@node Printing Notation -@subsection Printing Notation -@cindex printing notation - - Many of the examples in this manual print text when they are -evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @samp{*scratch*}), the printed text is inserted into -the buffer. If you execute the example by other means (such as by -evaluating the function @code{eval-region}), the printed text is -displayed in the echo area. - - Examples in this manual indicate printed text with @samp{@print{}}, -irrespective of where that text goes. The value returned by -evaluating the form (here @code{bar}) follows on a separate line with -@samp{@result{}}. - -@example -@group -(progn (prin1 'foo) (princ "\n") (prin1 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end example - -@node Error Messages -@subsection Error Messages -@cindex error message notation - - Some examples signal errors. This normally displays an error message -in the echo area. We show the error message on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear in -the echo area. - -@example -(+ 23 'x) -@error{} Wrong type argument: number-or-marker-p, x -@end example - -@node Buffer Text Notation -@subsection Buffer Text Notation -@cindex buffer text notation - - Some examples describe modifications to the contents of a buffer, by -showing the ``before'' and ``after'' versions of the text. These -examples show the contents of the buffer in question between two lines -of dashes containing the buffer name. In addition, @samp{@point{}} -indicates the location of point. (The symbol for point, of course, is -not part of the text in the buffer; it indicates the place -@emph{between} two characters where point is currently located.) - -@example ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- -@end example - -@node Format of Descriptions -@subsection Format of Descriptions -@cindex description format - - Functions, variables, macros, commands, user options, and special -forms are described in this manual in a uniform format. The first -line of a description contains the name of the item followed by its -arguments, if any. -@ifnottex -The category---function, variable, or whatever---appears at the -beginning of the line. -@end ifnottex -@iftex -The category---function, variable, or whatever---is printed next to the -right margin. -@end iftex -The description follows on succeeding lines, sometimes with examples. - -@menu -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, - @code{electric-future-map}. -@end menu - -@node A Sample Function Description -@subsubsection A Sample Function Description -@cindex function descriptions -@cindex command descriptions -@cindex macro descriptions -@cindex special form descriptions - - In a function description, the name of the function being described -appears first. It is followed on the same line by a list of argument -names. These names are also used in the body of the description, to -stand for the values of the arguments. - - The appearance of the keyword @code{&optional} in the argument list -indicates that the subsequent arguments may be omitted (omitted -arguments default to @code{nil}). Do not write @code{&optional} when -you call the function. - - The keyword @code{&rest} (which must be followed by a single -argument name) indicates that any number of arguments can follow. The -single argument name following @code{&rest} will receive, as its -value, a list of all the remaining arguments passed to the function. -Do not write @code{&rest} when you call the function. - - Here is a description of an imaginary function @code{foo}: - -@defun foo integer1 &optional integer2 &rest integers -The function @code{foo} subtracts @var{integer1} from @var{integer2}, -then adds all the rest of the arguments to the result. If @var{integer2} -is not supplied, then the number 19 is used by default. - -@example -(foo 1 5 3 9) - @result{} 16 -(foo 5) - @result{} 14 -@end example - -@need 1500 -More generally, - -@example -(foo @var{w} @var{x} @var{y}@dots{}) -@equiv{} -(+ (- @var{x} @var{w}) @var{y}@dots{}) -@end example -@end defun - - Any argument whose name contains the name of a type (e.g., -@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that -type. A plural of a type (such as @var{buffers}) often means a list of -objects of that type. Arguments named @var{object} may be of any type. -(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments -with other sorts of names (e.g., @var{new-file}) are discussed -specifically in the description of the function. In some sections, -features common to the arguments of several functions are described at -the beginning. - - @xref{Lambda Expressions}, for a more complete description of optional -and rest arguments. - - Command, macro, and special form descriptions have the same format, -but the word `Function' is replaced by `Command', `Macro', or `Special -Form', respectively. Commands are simply functions that may be called -interactively; macros process their arguments differently from functions -(the arguments are not evaluated), but are presented the same way. - - Special form descriptions use a more complex notation to specify -optional and repeated arguments because they can break the argument -list down into separate arguments in more complicated ways. -@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is -optional and @samp{@var{repeated-args}@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped into -additional levels of list structure. Here is an example: - -@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -This imaginary special form implements a loop that executes the -@var{body} forms and then increments the variable @var{var} on each -iteration. On the first iteration, the variable has the value -@var{from}; on subsequent iterations, it is incremented by one (or by -@var{inc} if that is given). The loop exits before executing @var{body} -if @var{var} equals @var{to}. Here is an example: - -@example -(count-loop (i 0 10) - (prin1 i) (princ " ") - (prin1 (aref vector i)) - (terpri)) -@end example - -If @var{from} and @var{to} are omitted, @var{var} is bound to -@code{nil} before the loop begins, and the loop exits if @var{var} is -non-@code{nil} at the beginning of an iteration. Here is an example: - -@example -(count-loop (done) - (if (pending) - (fixit) - (setq done t))) -@end example - -In this special form, the arguments @var{from} and @var{to} are -optional, but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the form. -@end defspec - -@node A Sample Variable Description -@subsubsection A Sample Variable Description -@cindex variable descriptions -@cindex option descriptions - - A @dfn{variable} is a name that can hold a value. Although nearly -all variables can be set by the user, certain variables exist -specifically so that users can change them; these are called @dfn{user -options}. Ordinary variables and user options are described using a -format like that for functions except that there are no arguments. - - Here is a description of the imaginary @code{electric-future-map} -variable.@refill - -@defvar electric-future-map -The value of this variable is a full keymap used by Electric Command -Future mode. The functions in this map allow you to edit commands you -have not yet thought about executing. -@end defvar - - User option descriptions have the same format, but `Variable' is -replaced by `User Option'. - -@node Version Info -@section Version Information - - These facilities provide information about which version of Emacs is -in use. - -@deffn Command emacs-version &optional here -This function returns a string describing the version of Emacs that is -running. It is useful to include this string in bug reports. - -@smallexample -@group -(emacs-version) - @result{} "GNU Emacs 23.1 (i686-pc-linux-gnu, GTK+ Version 2.14.4) - of 2009-06-01 on cyd.mit.edu" -@end group -@end smallexample - -If @var{here} is non-@code{nil}, it inserts the text in the buffer -before point, and returns @code{nil}. When this function is called -interactively, it prints the same information in the echo area, but -giving a prefix argument makes @var{here} non-@code{nil}. -@end deffn - -@defvar emacs-build-time -The value of this variable indicates the time at which Emacs was built -at the local site. It is a list of three integers, like the value -of @code{current-time} (@pxref{Time of Day}). - -@example -@group -emacs-build-time - @result{} (18846 52016 156039) -@end group -@end example -@end defvar - -@defvar emacs-version -The value of this variable is the version of Emacs being run. It is a -string such as @code{"23.1.1"}. The last number in this string is not -really part of the Emacs release version number; it is incremented -each time you build Emacs in any given directory. A value with four -numeric components, such as @code{"22.0.91.1"}, indicates an -unreleased test version. -@end defvar - - The following two variables have existed since Emacs version 19.23: - -@defvar emacs-major-version -The major version number of Emacs, as an integer. For Emacs version -23.1, the value is 23. -@end defvar - -@defvar emacs-minor-version -The minor version number of Emacs, as an integer. For Emacs version -23.1, the value is 1. -@end defvar - -@node Acknowledgements -@section Acknowledgements - - This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, -Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU -manual group, in an effort extending over several years. -Robert@tie{}J. Chassell helped to review and edit the manual, with the -support of the Defense Advanced Research Projects Agency, ARPA Order -6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, -Inc. Additional sections were written by Miles Bader, Lars Brinkhoff, -Chong Yidong, Kenichi Handa, Lute Kamstra, Juri Linkov, Glenn Morris, -Thien-Thi Nguyen, Dan Nicolaescu, Martin Rudalics, Kim F. Storm, Luc -Teirlinck, and Eli Zaretskii. - - Corrections were supplied by Drew Adams, Juanma Barranquero, Karl -Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David Boyes, Alan -Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch, David -A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf Fassel, -Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow, Jesper -Harder, George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak -Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, -K. Richard Magill, Brian Marick, Roland McGrath, Stefan Monnier, Skip -Montanaro, John Gardiner Myers, Thomas A. Peterson, Francesco Potorti, -Friedrich Pukelsheim, Arnold D. Robbins, Raul Rockwell, Jason Rumney, -Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, Bill -Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding, -Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn. - -@ignore - arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa -@end ignore diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi deleted file mode 100644 index 4afe5e55d82..00000000000 --- a/doc/lispref/keymaps.texi +++ /dev/null @@ -1,2810 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/keymaps -@node Keymaps, Modes, Command Loop, Top -@chapter Keymaps -@cindex keymap - - The command bindings of input events are recorded in data structures -called @dfn{keymaps}. Each entry in a keymap associates (or -@dfn{binds}) an individual event type, either to another keymap or to -a command. When an event type is bound to a keymap, that keymap is -used to look up the next input event; this continues until a command -is found. The whole process is called @dfn{key lookup}. - -@menu -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. -@end menu - -@node Key Sequences -@section Key Sequences -@cindex key -@cindex keystroke -@cindex key sequence - - A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one -or more input events that form a unit. Input events include -characters, function keys, and mouse actions (@pxref{Input Events}). -The Emacs Lisp representation for a key sequence is a string or -vector. Unless otherwise stated, any Emacs Lisp function that accepts -a key sequence as an argument can handle both representations. - - In the string representation, alphanumeric characters ordinarily -stand for themselves; for example, @code{"a"} represents @kbd{a} -and @code{"2"} represents @kbd{2}. Control character events are -prefixed by the substring @code{"\C-"}, and meta characters by -@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}. -In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events -are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and -@code{"\d"} respectively. The string representation of a complete key -sequence is the concatenation of the string representations of the -constituent events; thus, @code{"\C-xl"} represents the key sequence -@kbd{C-x l}. - - Key sequences containing function keys, mouse button events, or -non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be -represented as strings; they have to be represented as vectors. - - In the vector representation, each element of the vector represents -an input event, in its Lisp form. @xref{Input Events}. For example, -the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}. - - For examples of key sequences written in string and vector -representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}. - -@defmac kbd keyseq-text -This macro converts the text @var{keyseq-text} (a string constant) -into a key sequence (a string or vector constant). The contents of -@var{keyseq-text} should describe the key sequence using almost the same -syntax used in this manual. More precisely, it uses the same syntax -that Edit Macro mode uses for editing keyboard macros (@pxref{Edit -Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround -function key names with @samp{<@dots{}>}. - -@example -(kbd "C-x") @result{} "\C-x" -(kbd "C-x C-f") @result{} "\C-x\C-f" -(kbd "C-x 4 C-f") @result{} "\C-x4\C-f" -(kbd "X") @result{} "X" -(kbd "RET") @result{} "\^M" -(kbd "C-c SPC") @result{} "\C-c@ " -(kbd " SPC") @result{} [f1 32] -(kbd "C-M-") @result{} [C-M-down] -@end example - -This macro is not meant for use with arguments that vary---only -with string constants. -@end defmac - -@node Keymap Basics -@section Keymap Basics -@cindex key binding -@cindex binding of a key -@cindex complete key -@cindex undefined key - - A keymap is a Lisp data structure that specifies @dfn{key bindings} -for various key sequences. - - A single keymap directly specifies definitions for individual -events. When a key sequence consists of a single event, its binding -in a keymap is the keymap's definition for that event. The binding of -a longer key sequence is found by an iterative process: first find the -definition of the first event (which must itself be a keymap); then -find the second event's definition in that keymap, and so on until all -the events in the key sequence have been processed. - - If the binding of a key sequence is a keymap, we call the key sequence -a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because -no more events can be added to it). If the binding is @code{nil}, -we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, -@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are -@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete -keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more -details. - - The rule for finding the binding of a key sequence assumes that the -intermediate bindings (found for the events before the last) are all -keymaps; if this is not so, the sequence of events does not form a -unit---it is not really one key sequence. In other words, removing one -or more events from the end of any valid key sequence must always yield -a prefix key. For example, @kbd{C-f C-n} is not a key sequence; -@kbd{C-f} is not a prefix key, so a longer sequence starting with -@kbd{C-f} cannot be a key sequence. - - The set of possible multi-event key sequences depends on the bindings -for prefix keys; therefore, it can be different for different keymaps, -and can change when bindings are changed. However, a one-event sequence -is always a key sequence, because it does not depend on any prefix keys -for its well-formedness. - - At any time, several primary keymaps are @dfn{active}---that is, in -use for finding key bindings. These are the @dfn{global map}, which is -shared by all buffers; the @dfn{local keymap}, which is usually -associated with a specific major mode; and zero or more @dfn{minor mode -keymaps}, which belong to currently enabled minor modes. (Not all minor -modes have keymaps.) The local keymap bindings shadow (i.e., take -precedence over) the corresponding global bindings. The minor mode -keymaps shadow both local and global keymaps. @xref{Active Keymaps}, -for details. - -@node Format of Keymaps -@section Format of Keymaps -@cindex format of keymaps -@cindex keymap format -@cindex full keymap -@cindex sparse keymap - - Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The -remaining elements of the list define the key bindings of the keymap. -A symbol whose function definition is a keymap is also a keymap. Use -the function @code{keymapp} (see below) to test whether an object is a -keymap. - - Several kinds of elements may appear in a keymap, after the symbol -@code{keymap} that begins it: - -@table @code -@item (@var{type} .@: @var{binding}) -This specifies one binding, for events of type @var{type}. Each -ordinary binding applies to events of a particular @dfn{event type}, -which is always a character or a symbol. @xref{Classifying Events}. -In this kind of binding, @var{binding} is a command. - -@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding}) -This specifies a binding which is also a simple menu item that -displays as @var{item-name} in the menu. @var{cache}, if present, -caches certain information for display in the menu. @xref{Simple Menu -Items}. - -@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding}) -This is a simple menu item with help string @var{help-string}. - -@item (@var{type} menu-item .@: @var{details}) -This specifies a binding which is also an extended menu item. This -allows use of other features. @xref{Extended Menu Items}. - -@item (t .@: @var{binding}) -@cindex default key binding -This specifies a @dfn{default key binding}; any event not bound by other -elements of the keymap is given @var{binding} as its binding. Default -bindings allow a keymap to bind all possible event types without having -to enumerate all of them. A keymap that has a default binding -completely masks any lower-precedence keymap, except for events -explicitly bound to @code{nil} (see below). - -@item @var{char-table} -If an element of a keymap is a char-table, it counts as holding -bindings for all character events with no modifier bits -(@pxref{modifier bits}): element @var{n} is the binding for the -character with code @var{n}. This is a compact way to record lots of -bindings. A keymap with such a char-table is called a @dfn{full -keymap}. Other keymaps are called @dfn{sparse keymaps}. - -@item @var{string} -@cindex keymap prompt string -@cindex overall prompt string -@cindex prompt string of keymap -Aside from elements that specify bindings for keys, a keymap can also -have a string as an element. This is called the @dfn{overall prompt -string} and makes it possible to use the keymap as a menu. -@xref{Defining Menus}. -@end table - -When the binding is @code{nil}, it doesn't constitute a definition -but it does take precedence over a default binding or a binding in the -parent keymap. On the other hand, a binding of @code{nil} does -@emph{not} override lower-precedence keymaps; thus, if the local map -gives a binding of @code{nil}, Emacs uses the binding from the -global map. - -@cindex meta characters lookup - Keymaps do not directly record bindings for the meta characters. -Instead, meta characters are regarded for purposes of key lookup as -sequences of two characters, the first of which is @key{ESC} (or -whatever is currently the value of @code{meta-prefix-char}). Thus, the -key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its -global binding is found at the slot for @kbd{a} in @code{esc-map} -(@pxref{Prefix Keys}). - - This conversion applies only to characters, not to function keys or -other input events; thus, @kbd{M-@key{end}} has nothing to do with -@kbd{@key{ESC} @key{end}}. - - Here as an example is the local keymap for Lisp mode, a sparse -keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c -C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. - -@example -@group -lisp-mode-map -@result{} -@end group -@group -(keymap - (3 keymap - ;; @kbd{C-c C-z} - (26 . run-lisp)) -@end group -@group - (27 keymap - ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} - (24 . lisp-send-defun) - keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) -@end group -@group - ;; @r{This part is inherited from @code{lisp-mode-shared-map}.} - keymap - ;; @key{DEL} - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} - (17 . indent-sexp)) - (9 . lisp-indent-line)) -@end group -@end example - -@defun keymapp object -This function returns @code{t} if @var{object} is a keymap, @code{nil} -otherwise. More precisely, this function tests for a list whose -@sc{car} is @code{keymap}, or for a symbol whose function definition -satisfies @code{keymapp}. - -@example -@group -(keymapp '(keymap)) - @result{} t -@end group -@group -(fset 'foo '(keymap)) -(keymapp 'foo) - @result{} t -@end group -@group -(keymapp (current-global-map)) - @result{} t -@end group -@end example -@end defun - -@node Creating Keymaps -@section Creating Keymaps -@cindex creating keymaps - - Here we describe the functions for creating keymaps. - -@defun make-sparse-keymap &optional prompt -This function creates and returns a new sparse keymap with no entries. -(A sparse keymap is the kind of keymap you usually want.) The new -keymap does not contain a char-table, unlike @code{make-keymap}, and -does not bind any events. - -@example -@group -(make-sparse-keymap) - @result{} (keymap) -@end group -@end example - -If you specify @var{prompt}, that becomes the overall prompt string -for the keymap. You should specify this only for menu keymaps -(@pxref{Defining Menus}). A keymap with an overall prompt string will -always present a mouse menu or a keyboard menu if it is active for -looking up the next input event. Don't specify an overall prompt string -for the main map of a major or minor mode, because that would cause -the command loop to present a keyboard menu every time. -@end defun - -@defun make-keymap &optional prompt -This function creates and returns a new full keymap. That keymap -contains a char-table (@pxref{Char-Tables}) with slots for all -characters without modifiers. The new keymap initially binds all -these characters to @code{nil}, and does not bind any other kind of -event. The argument @var{prompt} specifies a -prompt string, as in @code{make-sparse-keymap}. - -@example -@group -(make-keymap) - @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap]) -@end group -@end example - -A full keymap is more efficient than a sparse keymap when it holds -lots of bindings; for just a few, the sparse keymap is better. -@end defun - -@defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that -appear directly as bindings in @var{keymap} are also copied recursively, -and so on to any number of levels. However, recursive copying does not -take place when the definition of a character is a symbol whose function -definition is a keymap; the same symbol appears in the new copy. -@c Emacs 19 feature - -@example -@group -(setq map (copy-keymap (current-local-map))) -@result{} (keymap -@end group -@group - ;; @r{(This implements meta characters.)} - (27 keymap - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group -(eq map (current-local-map)) - @result{} nil -@end group -@group -(equal map (current-local-map)) - @result{} t -@end group -@end example -@end defun - -@node Inheritance and Keymaps -@section Inheritance and Keymaps -@cindex keymap inheritance -@cindex inheriting a keymap's bindings - - A keymap can inherit the bindings of another keymap, which we call the -@dfn{parent keymap}. Such a keymap looks like this: - -@example -(keymap @var{elements}@dots{} . @var{parent-keymap}) -@end example - -@noindent -The effect is that this keymap inherits all the bindings of -@var{parent-keymap}, whatever they may be at the time a key is looked up, -but can add to them or override them with @var{elements}. - -If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed -bindings are visible in the inheriting keymap, unless shadowed by the -bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these -changes are recorded in @var{elements}, but have no effect on -@var{parent-keymap}. - -The proper way to construct a keymap with a parent is to use -@code{set-keymap-parent}; if you have code that directly constructs a -keymap with a parent, please convert the program to use -@code{set-keymap-parent} instead. - -@defun keymap-parent keymap -This returns the parent keymap of @var{keymap}. If @var{keymap} -has no parent, @code{keymap-parent} returns @code{nil}. -@end defun - -@defun set-keymap-parent keymap parent -This sets the parent keymap of @var{keymap} to @var{parent}, and returns -@var{parent}. If @var{parent} is @code{nil}, this function gives -@var{keymap} no parent at all. - -If @var{keymap} has submaps (bindings for prefix keys), they too receive -new parent keymaps that reflect what @var{parent} specifies for those -prefix keys. -@end defun - - Here is an example showing how to make a keymap that inherits -from @code{text-mode-map}: - -@example -(let ((map (make-sparse-keymap))) - (set-keymap-parent map text-mode-map) - map) -@end example - - A non-sparse keymap can have a parent too, but this is not very -useful. A non-sparse keymap always specifies something as the binding -for every numeric character code without modifier bits, even if it is -@code{nil}, so these character's bindings are never inherited from -the parent keymap. - -@node Prefix Keys -@section Prefix Keys -@cindex prefix key - - A @dfn{prefix key} is a key sequence whose binding is a keymap. The -keymap defines what to do with key sequences that extend the prefix key. -For example, @kbd{C-x} is a prefix key, and it uses a keymap that is -also stored in the variable @code{ctl-x-map}. This keymap defines -bindings for key sequences starting with @kbd{C-x}. - - Some of the standard Emacs prefix keys use keymaps that are -also found in Lisp variables: - -@itemize @bullet -@item -@vindex esc-map -@findex ESC-prefix -@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus, -the global definitions of all meta characters are actually found here. -This map is also the function definition of @code{ESC-prefix}. - -@item -@cindex @kbd{C-h} -@code{help-map} is the global keymap for the @kbd{C-h} prefix key. - -@item -@cindex @kbd{C-c} -@vindex mode-specific-map -@code{mode-specific-map} is the global keymap for the prefix key -@kbd{C-c}. This map is actually global, not mode-specific, but its name -provides useful information about @kbd{C-c} in the output of @kbd{C-h b} -(@code{display-bindings}), since the main use of this prefix key is for -mode-specific bindings. - -@item -@cindex @kbd{C-x} -@vindex ctl-x-map -@findex Control-X-prefix -@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key. -This map is found via the function cell of the symbol -@code{Control-X-prefix}. - -@item -@cindex @kbd{C-x @key{RET}} -@vindex mule-keymap -@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} -prefix key. - -@item -@cindex @kbd{C-x 4} -@vindex ctl-x-4-map -@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix -key. - -@item -@cindex @kbd{C-x 5} -@vindex ctl-x-5-map -@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix -key. - -@item -@cindex @kbd{C-x 6} -@vindex 2C-mode-map -@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix -key. - -@item -@cindex @kbd{C-x v} -@vindex vc-prefix-map -@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix -key. - -@item -@cindex @kbd{M-g} -@vindex goto-map -@code{goto-map} is the global keymap used for the @kbd{M-g} prefix -key. - -@item -@cindex @kbd{M-s} -@vindex search-map -@code{search-map} is the global keymap used for the @kbd{M-s} prefix -key. - -@item -@cindex @kbd{M-o} -@vindex facemenu-keymap -@code{facemenu-keymap} is the global keymap used for the @kbd{M-o} -prefix key. - -@item -The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x -@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have -no special names. -@end itemize - - The keymap binding of a prefix key is used for looking up the event -that follows the prefix key. (It may instead be a symbol whose function -definition is a keymap. The effect is the same, but the symbol serves -as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the -symbol @code{Control-X-prefix}, whose function cell holds the keymap -for @kbd{C-x} commands. (The same keymap is also the value of -@code{ctl-x-map}.) - - Prefix key definitions can appear in any active keymap. The -definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix -keys appear in the global map, so these prefix keys are always -available. Major and minor modes can redefine a key as a prefix by -putting a prefix key definition for it in the local map or the minor -mode's map. @xref{Active Keymaps}. - - If a key is defined as a prefix in more than one active map, then its -various definitions are in effect merged: the commands defined in the -minor mode keymaps come first, followed by those in the local map's -prefix definition, and then by those from the global map. - - In the following example, we make @kbd{C-p} a prefix key in the local -keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then -the binding for @kbd{C-p C-f} is the function @code{find-file}, just -like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any -active keymap. - -@example -@group -(use-local-map (make-sparse-keymap)) - @result{} nil -@end group -@group -(local-set-key "\C-p" ctl-x-map) - @result{} nil -@end group -@group -(key-binding "\C-p\C-f") - @result{} find-file -@end group - -@group -(key-binding "\C-p6") - @result{} nil -@end group -@end example - -@defun define-prefix-command symbol &optional mapvar prompt -@cindex prefix command -@anchor{Definition of define-prefix-command} -This function prepares @var{symbol} for use as a prefix key's binding: -it creates a sparse keymap and stores it as @var{symbol}'s function -definition. Subsequently binding a key sequence to @var{symbol} will -make that key sequence into a prefix key. The return value is @code{symbol}. - -This function also sets @var{symbol} as a variable, with the keymap as -its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar} -as a variable instead. - -If @var{prompt} is non-@code{nil}, that becomes the overall prompt -string for the keymap. The prompt string should be given for menu keymaps -(@pxref{Defining Menus}). -@end defun - -@node Active Keymaps -@section Active Keymaps -@cindex active keymap -@cindex global keymap -@cindex local keymap - - Emacs normally contains many keymaps; at any given time, just a few -of them are @dfn{active}, meaning that they participate in the -interpretation of user input. All the active keymaps are used -together to determine what command to execute when a key is entered. - - Normally the active keymaps are the @code{keymap} property keymap, -the keymaps of any enabled minor modes, the current buffer's local -keymap, and the global keymap, in that order. Emacs searches for each -input key sequence in all these keymaps. @xref{Searching Keymaps}, -for more details of this procedure. - - When the key sequence starts with a mouse event (optionally preceded -by a symbolic prefix), the active keymaps are determined based on the -position in that event. If the event happened on a string embedded -with a @code{display}, @code{before-string}, or @code{after-string} -property (@pxref{Special Properties}), the non-@code{nil} map -properties of the string override those of the buffer (if the -underlying buffer text contains map properties in its text properties -or overlays, they are ignored). - - The @dfn{global keymap} holds the bindings of keys that are defined -regardless of the current buffer, such as @kbd{C-f}. The variable -@code{global-map} holds this keymap, which is always active. - - Each buffer may have another keymap, its @dfn{local keymap}, which -may contain new or overriding definitions for keys. The current -buffer's local keymap is always active except when -@code{overriding-local-map} overrides it. The @code{local-map} text -or overlay property can specify an alternative local keymap for certain -parts of the buffer; see @ref{Special Properties}. - - Each minor mode can have a keymap; if it does, the keymap is active -when the minor mode is enabled. Modes for emulation can specify -additional active keymaps through the variable -@code{emulation-mode-map-alists}. - - The highest precedence normal keymap comes from the @code{keymap} -text or overlay property. If that is non-@code{nil}, it is the first -keymap to be processed, in normal circumstances. - - However, there are also special ways for programs to substitute -other keymaps for some of those. The variable -@code{overriding-local-map}, if non-@code{nil}, specifies a keymap -that replaces all the usual active keymaps except the global keymap. -Another way to do this is with @code{overriding-terminal-local-map}; -it operates on a per-terminal basis. These variables are documented -below. - -@cindex major mode keymap - Since every buffer that uses the same major mode normally uses the -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using @code{local-set-key}, for -example) is seen also in the other buffers that share that keymap. - - The local keymaps that are used for Lisp mode and some other major -modes exist even if they have not yet been used. These local keymaps are -the values of variables such as @code{lisp-mode-map}. For most major -modes, which are less frequently used, the local keymap is constructed -only when the mode is used for the first time in a session. - - The minibuffer has local keymaps, too; they contain various completion -and exit commands. @xref{Intro to Minibuffers}. - - Emacs has other keymaps that are used in a different way---translating -events within @code{read-key-sequence}. @xref{Translation Keymaps}. - - @xref{Standard Keymaps}, for a list of standard keymaps. - -@defun current-active-maps &optional olp position -This returns the list of active keymaps that would be used by the -command loop in the current circumstances to look up a key sequence. -Normally it ignores @code{overriding-local-map} and -@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil} -then it pays attention to them. @var{position} can optionally be either -an event position as returned by @code{event-start} or a buffer -position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -returns the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -An error is signaled if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example -@end defun - -@node Searching Keymaps -@section Searching the Active Keymaps -@cindex searching active keymaps for keys - - After translation of event subsequences (@pxref{Translation -Keymaps}) Emacs looks for them in the active keymaps. Here is a -pseudo-Lisp description of the order and conditions for searching -them: - -@lisp -(or (if overriding-terminal-local-map - (@var{find-in} overriding-terminal-local-map) - (if overriding-local-map - (@var{find-in} overriding-local-map) - (or (@var{find-in} (get-char-property (point) 'keymap)) - (@var{find-in-any} emulation-mode-map-alists) - (@var{find-in-any} minor-mode-overriding-map-alist) - (@var{find-in-any} minor-mode-map-alist) - (if (get-text-property (point) 'local-map) - (@var{find-in} (get-char-property (point) 'local-map)) - (@var{find-in} (current-local-map)))))) - (@var{find-in} (current-global-map))) -@end lisp - -@noindent -The @var{find-in} and @var{find-in-any} are pseudo functions that -search in one keymap and in an alist of keymaps, respectively. -(Searching a single keymap for a binding is called @dfn{key lookup}; -see @ref{Key Lookup}.) If the key sequence starts with a mouse event, -or a symbolic prefix event followed by a mouse event, that event's -position is used instead of point and the current buffer. Mouse -events on an embedded string use non-@code{nil} text properties from -that string instead of the buffer. - -@enumerate -@item -The function finally found may be remapped -(@pxref{Remapping Commands}). - -@item -Characters that are bound to @code{self-insert-command} are translated -according to @code{translation-table-for-input} before insertion. - -@item -@code{current-active-maps} returns a list of the -currently active keymaps at point. - -@item -When a match is found (@pxref{Key Lookup}), if the binding in the -keymap is a function, the search is over. However if the keymap entry -is a symbol with a value or a string, Emacs replaces the input key -sequences with the variable's value or the string, and restarts the -search of the active keymaps. -@end enumerate - -@node Controlling Active Maps -@section Controlling the Active Keymaps - -@defvar global-map -This variable contains the default global keymap that maps Emacs -keyboard input to commands. The global keymap is normally this -keymap. The default global keymap is a full keymap that binds -@code{self-insert-command} to all of the printing characters. - -It is normal practice to change the bindings in the global keymap, but you -should not assign this variable any value other than the keymap it starts -out with. -@end defvar - -@defun current-global-map -This function returns the current global keymap. This is the same as -the value of @code{global-map} unless you change one or the other. -The return value is a reference, not a copy; if you use -@code{define-key} or other functions on it you will alter global -bindings. - -@example -@group -(current-global-map) -@result{} (keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@end example -@end defun - -@defun current-local-map -This function returns the current buffer's local keymap, or @code{nil} -if it has none. In the following example, the keymap for the -@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap -in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse -keymap. - -@example -@group -(current-local-map) -@result{} (keymap - (10 . eval-print-last-sexp) - (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) -@end group -@group - (27 keymap - (24 . eval-defun) - (17 . indent-sexp))) -@end group -@end example -@end defun - -@code{current-local-map} returns a reference to the local keymap, not -a copy of it; if you use @code{define-key} or other functions on it -you will alter local bindings. - -@defun current-minor-mode-maps -This function returns a list of the keymaps of currently enabled minor modes. -@end defun - -@defun use-global-map keymap -This function makes @var{keymap} the new current global keymap. It -returns @code{nil}. - -It is very unusual to change the global keymap. -@end defun - -@defun use-local-map keymap -This function makes @var{keymap} the new local keymap of the current -buffer. If @var{keymap} is @code{nil}, then the buffer has no local -keymap. @code{use-local-map} returns @code{nil}. Most major mode -commands use this function. -@end defun - -@c Emacs 19 feature -@defvar minor-mode-map-alist -@anchor{Definition of minor-mode-map-alist} -This variable is an alist describing keymaps that may or may not be -active according to the values of certain variables. Its elements look -like this: - -@example -(@var{variable} . @var{keymap}) -@end example - -The keymap @var{keymap} is active whenever @var{variable} has a -non-@code{nil} value. Typically @var{variable} is the variable that -enables or disables a minor mode. @xref{Keymaps and Minor Modes}. - -Note that elements of @code{minor-mode-map-alist} do not have the same -structure as elements of @code{minor-mode-alist}. The map must be the -@sc{cdr} of the element; a list with the map as the second element will -not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose -function definition is a keymap. - -When more than one minor mode keymap is active, the earlier one in -@code{minor-mode-map-alist} takes priority. But you should design -minor modes so that they don't interfere with each other. If you do -this properly, the order will not matter. - -See @ref{Keymaps and Minor Modes}, for more information about minor -modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key -Lookup}). -@end defvar - -@defvar minor-mode-overriding-map-alist -This variable allows major modes to override the key bindings for -particular minor modes. The elements of this alist look like the -elements of @code{minor-mode-map-alist}: @code{(@var{variable} -. @var{keymap})}. - -If a variable appears as an element of -@code{minor-mode-overriding-map-alist}, the map specified by that -element totally replaces any map specified for the same variable in -@code{minor-mode-map-alist}. - -@code{minor-mode-overriding-map-alist} is automatically buffer-local in -all buffers. -@end defvar - -@defvar overriding-local-map -If non-@code{nil}, this variable holds a keymap to use instead of the -buffer's local keymap, any text property or overlay keymaps, and any -minor mode keymaps. This keymap, if specified, overrides all other -maps that would have been active, except for the current global map. -@end defvar - -@defvar overriding-terminal-local-map -If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap, text property -or overlay keymaps, and all the minor mode keymaps. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Terminals}. It is used to implement -incremental search mode. -@end defvar - -@defvar overriding-local-map-menu-flag -If this variable is non-@code{nil}, the value of -@code{overriding-local-map} or @code{overriding-terminal-local-map} can -affect the display of the menu bar. The default value is @code{nil}, so -those map variables have no effect on the menu bar. - -Note that these two map variables do affect the execution of key -sequences entered using the menu bar, even if they do not affect the -menu bar display. So if a menu bar key sequence comes in, you should -clear the variables before looking up and executing that key sequence. -Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and -exiting. -@end defvar - -@defvar special-event-map -This variable holds a keymap for special events. If an event type has a -binding in this keymap, then it is special, and the binding for the -event is run directly by @code{read-event}. @xref{Special Events}. -@end defvar - -@defvar emulation-mode-map-alists -This variable holds a list of keymap alists to use for emulations -modes. It is intended for modes or packages using multiple minor-mode -keymaps. Each element is a keymap alist which has the same format and -meaning as @code{minor-mode-map-alist}, or a symbol with a variable -binding which is such an alist. The ``active'' keymaps in each alist -are used before @code{minor-mode-map-alist} and -@code{minor-mode-overriding-map-alist}. -@end defvar - -@node Key Lookup -@section Key Lookup -@cindex key lookup -@cindex keymap entry - - @dfn{Key lookup} is the process of finding the binding of a key -sequence from a given keymap. The execution or use of the binding is -not part of key lookup. - - Key lookup uses just the event type of each event in the key sequence; -the rest of the event is ignored. In fact, a key sequence used for key -lookup may designate a mouse event with just its types (a symbol) -instead of the entire event (a list). @xref{Input Events}. Such -a ``key sequence'' is insufficient for @code{command-execute} to run, -but it is sufficient for looking up or rebinding a key. - - When the key sequence consists of multiple events, key lookup -processes the events sequentially: the binding of the first event is -found, and must be a keymap; then the second event's binding is found in -that keymap, and so on until all the events in the key sequence are used -up. (The binding thus found for the last event may or may not be a -keymap.) Thus, the process of key lookup is defined in terms of a -simpler process for looking up a single event in a keymap. How that is -done depends on the type of object associated with the event in that -keymap. - - Let's use the term @dfn{keymap entry} to describe the value found by -looking up an event type in a keymap. (This doesn't include the item -string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in -the returned value.) While any Lisp object may be stored in a keymap -as a keymap entry, not all make sense for key lookup. Here is a table -of the meaningful types of keymap entries: - -@table @asis -@item @code{nil} -@cindex @code{nil} in keymap -@code{nil} means that the events used so far in the lookup form an -undefined key. When a keymap fails to mention an event type at all, and -has no default binding, that is equivalent to a binding of @code{nil} -for that event type. - -@item @var{command} -@cindex command in keymap -The events used so far in the lookup form a complete key, -and @var{command} is its binding. @xref{What Is a Function}. - -@item @var{array} -@cindex string in keymap -The array (either a string or a vector) is a keyboard macro. The events -used so far in the lookup form a complete key, and the array is its -binding. See @ref{Keyboard Macros}, for more information. - -@item @var{keymap} -@cindex keymap in keymap -The events used so far in the lookup form a prefix key. The next -event of the key sequence is looked up in @var{keymap}. - -@item @var{list} -@cindex list in keymap -The meaning of a list depends on what it contains: - -@itemize @bullet -@item -If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list -is a keymap, and is treated as a keymap (see above). - -@item -@cindex @code{lambda} in keymap -If the @sc{car} of @var{list} is @code{lambda}, then the list is a -lambda expression. This is presumed to be a function, and is treated -as such (see above). In order to execute properly as a key binding, -this function must be a command---it must have an @code{interactive} -specification. @xref{Defining Commands}. - -@item -If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event -type, then this is an @dfn{indirect entry}: - -@example -(@var{othermap} . @var{othertype}) -@end example - -When key lookup encounters an indirect entry, it looks up instead the -binding of @var{othertype} in @var{othermap} and uses that. - -This feature permits you to define one key as an alias for another key. -For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global -binding of @kbd{Meta-@key{SPC}}, whatever that may be.'' -@end itemize - -@item @var{symbol} -@cindex symbol in keymap -The function definition of @var{symbol} is used in place of -@var{symbol}. If that too is a symbol, then this process is repeated, -any number of times. Ultimately this should lead to an object that is -a keymap, a command, or a keyboard macro. A list is allowed if it is a -keymap or a command, but indirect entries are not understood when found -via symbols. - -Note that keymaps and keyboard macros (strings and vectors) are not -valid functions, so a symbol with a keymap, string, or vector as its -function definition is invalid as a function. It is, however, valid as -a key binding. If the definition is a keyboard macro, then the symbol -is also valid as an argument to @code{command-execute} -(@pxref{Interactive Call}). - -@cindex @code{undefined} in keymap -The symbol @code{undefined} is worth special mention: it means to treat -the key as undefined. Strictly speaking, the key is defined, and its -binding is the command @code{undefined}; but that command does the same -thing that is done automatically for an undefined key: it rings the bell -(by calling @code{ding}) but does not signal an error. - -@cindex preventing prefix key -@code{undefined} is used in local keymaps to override a global key -binding and make the key ``undefined'' locally. A local binding of -@code{nil} would fail to do this because it would not override the -global binding. - -@item @var{anything else} -If any other type of object is found, the events used so far in the -lookup form a complete key, and the object is its binding, but the -binding is not executable as a command. -@end table - - In short, a keymap entry may be a keymap, a command, a keyboard macro, -a symbol that leads to one of them, or an indirection or @code{nil}. -Here is an example of a sparse keymap with two characters bound to -commands and one bound to another keymap. This map is the normal value -of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB}, -127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for -@kbd{C-x}. - -@example -@group -(keymap (9 . lisp-indent-line) - (127 . backward-delete-char-untabify) - (27 keymap (17 . indent-sexp) (24 . eval-defun))) -@end group -@end example - -@node Functions for Key Lookup -@section Functions for Key Lookup - - Here are the functions and variables pertaining to key lookup. - -@defun lookup-key keymap key &optional accept-defaults -This function returns the definition of @var{key} in @var{keymap}. All -the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: - -@example -@group -(lookup-key (current-global-map) "\C-x\C-f") - @result{} find-file -@end group -@group -(lookup-key (current-global-map) (kbd "C-x C-f")) - @result{} find-file -@end group -@group -(lookup-key (current-global-map) "\C-x\C-f12345") - @result{} 2 -@end group -@end example - -If the string or vector @var{key} is not a valid key sequence according -to the prefix keys specified in @var{keymap}, it must be ``too long'' -and have extra events at the end that do not fit into a single key -sequence. Then the value is a number, the number of events at the front -of @var{key} that compose a complete key. - -@c Emacs 19 feature -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} -considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for -the specific sequence @var{key}, ignoring default bindings except when -you explicitly ask about them. (To do this, supply @code{t} as an -element of @var{key}; see @ref{Format of Keymaps}.) - -If @var{key} contains a meta character (not a function key), that -character is implicitly replaced by a two-character sequence: the value -of @code{meta-prefix-char}, followed by the corresponding non-meta -character. Thus, the first example below is handled by conversion into -the second example. - -@example -@group -(lookup-key (current-global-map) "\M-f") - @result{} forward-word -@end group -@group -(lookup-key (current-global-map) "\ef") - @result{} forward-word -@end group -@end example - -Unlike @code{read-key-sequence}, this function does not modify the -specified events in ways that discard information (@pxref{Key Sequence -Input}). In particular, it does not convert letters to lower case and -it does not change drag events to clicks. -@end defun - -@deffn Command undefined -Used in keymaps to undefine keys. It calls @code{ding}, but does -not cause an error. -@end deffn - -@defun local-key-binding key &optional accept-defaults -This function returns the binding for @var{key} in the current -local keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@defun global-key-binding key &optional accept-defaults -This function returns the binding for command @var{key} in the -current global keymap, or @code{nil} if it is undefined there. - -@c Emacs 19 feature -The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). -@end defun - -@c Emacs 19 feature -@defun minor-mode-key-binding key &optional accept-defaults -This function returns a list of all the active minor mode bindings of -@var{key}. More precisely, it returns an alist of pairs -@code{(@var{modename} . @var{binding})}, where @var{modename} is the -variable that enables the minor mode, and @var{binding} is @var{key}'s -binding in that mode. If @var{key} has no minor-mode bindings, the -value is @code{nil}. - -If the first binding found is not a prefix definition (a keymap or a -symbol defined as a keymap), all subsequent bindings from other minor -modes are omitted, since they would be completely shadowed. Similarly, -the list omits non-prefix bindings that follow prefix bindings. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). -@end defun - -@defopt meta-prefix-char -@cindex @key{ESC} -This variable is the meta-prefix character code. It is used for -translating a meta character to a two-character sequence so it can be -looked up in a keymap. For useful results, the value should be a -prefix event (@pxref{Prefix Keys}). The default value is 27, which is -the @acronym{ASCII} code for @key{ESC}. - -As long as the value of @code{meta-prefix-char} remains 27, key lookup -translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined -as the @code{backward-word} command. However, if you were to set -@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will -translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the -@code{switch-to-buffer} command. (Don't actually do this!) Here is an -illustration of what would happen: - -@smallexample -@group -meta-prefix-char ; @r{The default value.} - @result{} 27 -@end group -@group -(key-binding "\M-b") - @result{} backward-word -@end group -@group -?\C-x ; @r{The print representation} - @result{} 24 ; @r{of a character.} -@end group -@group -(setq meta-prefix-char 24) - @result{} 24 -@end group -@group -(key-binding "\M-b") - @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} - ; @r{like typing @kbd{C-x b}.} - -(setq meta-prefix-char 27) ; @r{Avoid confusion!} - @result{} 27 ; @r{Restore the default value!} -@end group -@end smallexample - -This translation of one event into two happens only for characters, not -for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function -key, is not converted into @kbd{@key{ESC} @key{F1}}. -@end defopt - -@node Changing Key Bindings -@section Changing Key Bindings -@cindex changing key bindings -@cindex rebinding - - The way to rebind a key is to change its entry in a keymap. If you -change a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow the -global binding with a local one). If you change the current buffer's -local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are -convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general -function; then you must specify explicitly the map to change. - - When choosing the key sequences for Lisp programs to rebind, please -follow the Emacs conventions for use of various keys (@pxref{Key -Binding Conventions}). - -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient -way to specify the key sequence. - -@defun define-key keymap key binding -This function sets the binding for @var{key} in @var{keymap}. (If -@var{key} is more than one event long, the change is actually made -in another keymap reached from @var{keymap}.) The argument -@var{binding} can be any Lisp object, but only certain types are -meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. - -If @var{key} is @code{[t]}, this sets the default binding in -@var{keymap}. When an event has no binding of its own, the Emacs -command loop uses the keymap's default binding, if there is one. - -@cindex invalid prefix key error -@cindex key sequence error -Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) -or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix -key so that the rest of @var{key} can be defined as specified. - -If there was previously no binding for @var{key} in @var{keymap}, the -new binding is added at the beginning of @var{keymap}. The order of -bindings in a keymap makes no difference for keyboard input, but it -does matter for menu keymaps (@pxref{Menu Keymaps}). -@end defun - - This example creates a sparse keymap and makes a number of -bindings in it: - -@smallexample -@group -(setq map (make-sparse-keymap)) - @result{} (keymap) -@end group -@group -(define-key map "\C-f" 'forward-char) - @result{} forward-char -@end group -@group -map - @result{} (keymap (6 . forward-char)) -@end group - -@group -;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) - @result{} forward-word -@end group -@group -map -@result{} (keymap - (24 keymap ; @kbd{C-x} - (102 . forward-word)) ; @kbd{f} - (6 . forward-char)) ; @kbd{C-f} -@end group - -@group -;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) -;; @code{ctl-x-map} -@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] -@end group - -@group -;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) -@result{} 'foo -@end group -@group -map -@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} - (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) - (24 keymap - (102 . forward-word)) - (6 . forward-char)) -@end group -@end smallexample - -@noindent -Note that storing a new binding for @kbd{C-p C-f} actually works by -changing an entry in @code{ctl-x-map}, and this has the effect of -changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the -default global map. - - The function @code{substitute-key-definition} scans a keymap for -keys that have a certain binding and rebinds them with a different -binding. Another feature which is cleaner and can often produce the -same results to remap one command into another (@pxref{Remapping -Commands}). - -@defun substitute-key-definition olddef newdef keymap &optional oldmap -@cindex replace bindings -This function replaces @var{olddef} with @var{newdef} for any keys in -@var{keymap} that were bound to @var{olddef}. In other words, -@var{olddef} is replaced with @var{newdef} wherever it appears. The -function returns @code{nil}. - -For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with -standard bindings: - -@smallexample -@group -(substitute-key-definition - 'find-file 'find-file-read-only (current-global-map)) -@end group -@end smallexample - -@c Emacs 19 feature -If @var{oldmap} is non-@code{nil}, that changes the behavior of -@code{substitute-key-definition}: the bindings in @var{oldmap} determine -which keys to rebind. The rebindings still happen in @var{keymap}, not -in @var{oldmap}. Thus, you can change one map under the control of the -bindings in another. For example, - -@smallexample -(substitute-key-definition - 'delete-backward-char 'my-funny-delete - my-map global-map) -@end smallexample - -@noindent -puts the special deletion command in @code{my-map} for whichever keys -are globally bound to the standard deletion command. - -Here is an example showing a keymap before and after substitution: - -@smallexample -@group -(setq map '(keymap - (?1 . olddef-1) - (?2 . olddef-2) - (?3 . olddef-1))) -@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) -@end group - -@group -(substitute-key-definition 'olddef-1 'newdef map) -@result{} nil -@end group -@group -map -@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) -@end group -@end smallexample -@end defun - -@defun suppress-keymap keymap &optional nodigits -@cindex @code{self-insert-command} override -This function changes the contents of the full keymap @var{keymap} by -remapping @code{self-insert-command} to the command @code{undefined} -(@pxref{Remapping Commands}). This has the effect of undefining all -printing characters, thus making ordinary insertion of text impossible. -@code{suppress-keymap} returns @code{nil}. - -If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines -digits to run @code{digit-argument}, and @kbd{-} to run -@code{negative-argument}. Otherwise it makes them undefined like the -rest of the printing characters. - -@cindex yank suppression -@cindex @code{quoted-insert} suppression -The @code{suppress-keymap} function does not make it impossible to -modify a buffer, as it does not suppress commands such as @code{yank} -and @code{quoted-insert}. To prevent any modification of a buffer, make -it read-only (@pxref{Read Only Buffers}). - -Since this function modifies @var{keymap}, you would normally use it -on a newly created keymap. Operating on an existing keymap -that is used for some other purpose is likely to cause trouble; for -example, suppressing @code{global-map} would make it impossible to use -most of Emacs. - -Most often, @code{suppress-keymap} is used to initialize local -keymaps of modes such as Rmail and Dired where insertion of text is not -desirable and the buffer is read-only. Here is an example taken from -the file @file{emacs/lisp/dired.el}, showing how the local keymap for -Dired mode is set up: - -@smallexample -@group -(setq dired-mode-map (make-keymap)) -(suppress-keymap dired-mode-map) -(define-key dired-mode-map "r" 'dired-rename-file) -(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) -(define-key dired-mode-map "d" 'dired-flag-file-deleted) -(define-key dired-mode-map "v" 'dired-view-file) -(define-key dired-mode-map "e" 'dired-find-file) -(define-key dired-mode-map "f" 'dired-find-file) -@dots{} -@end group -@end smallexample -@end defun - -@node Remapping Commands -@section Remapping Commands -@cindex remapping commands - - A special kind of key binding, using a special ``key sequence'' -which includes a command name, has the effect of @dfn{remapping} that -command into another. Here's how it works. You make a key binding -for a key sequence that starts with the dummy event @code{remap}, -followed by the command name you want to remap. Specify the remapped -definition as the definition in this binding. The remapped definition -is usually a command name, but it can be any valid definition for -a key binding. - - Here's an example. Suppose that My mode uses special commands -@code{my-kill-line} and @code{my-kill-word}, which should be invoked -instead of @code{kill-line} and @code{kill-word}. It can establish -this by making these two command-remapping bindings in its keymap: - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap kill-word] 'my-kill-word) -@end smallexample - -Whenever @code{my-mode-map} is an active keymap, if the user types -@kbd{C-k}, Emacs will find the standard global binding of -@code{kill-line} (assuming nobody has changed it). But -@code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line}, -so instead of running @code{kill-line}, Emacs runs -@code{my-kill-line}. - -Remapping only works through a single level. In other words, - -@smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) -@end smallexample - -@noindent -does not have the effect of remapping @code{kill-line} into -@code{my-other-kill-line}. If an ordinary key binding specifies -@code{kill-line}, this keymap will remap it to @code{my-kill-line}; -if an ordinary binding specifies @code{my-kill-line}, this keymap will -remap it to @code{my-other-kill-line}. - -@defun command-remapping command &optional position keymaps -This function returns the remapping for @var{command} (a symbol), -given the current active keymaps. If @var{command} is not remapped -(which is the usual situation), or not a symbol, the function returns -@code{nil}. @code{position} can optionally specify a buffer position -or an event position to determine the keymaps to use, as in -@code{key-binding}. - -If the optional argument @code{keymaps} is non-@code{nil}, it -specifies a list of keymaps to search in. This argument is ignored if -@code{position} is non-@code{nil}. -@end defun - -@node Translation Keymaps -@section Keymaps for Translating Sequences of Events -@cindex keymaps for translating events - - This section describes keymaps that are used during reading a key -sequence, to translate certain event sequences into others. -@code{read-key-sequence} checks every subsequence of the key sequence -being read, as it is read, against @code{input-decode-map}, then -@code{local-function-key-map}, and then against @code{key-translation-map}. - -@defvar input-decode-map -This variable holds a keymap that describes the character sequences sent -by function keys on an ordinary character terminal. This keymap has the -same structure as other keymaps, but is used differently: it specifies -translations to make while reading key sequences, rather than bindings -for key sequences. - -If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector -@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a -key sequence, it is replaced with the events in @var{v}. - -For example, VT100 terminals send @kbd{@key{ESC} O P} when the -keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate -that sequence of events into the single event @code{pf1}. We accomplish -this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in -@code{input-decode-map}, when using a VT100. - -Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c -@key{ESC} O P}; later the function @code{read-key-sequence} translates -this back into @kbd{C-c @key{PF1}}, which it returns as the vector -@code{[?\C-c pf1]}. - -The value of @code{input-decode-map} is usually set up automatically -according to the terminal's Terminfo or Termcap entry, but sometimes -those need help from terminal-specific Lisp files. Emacs comes with -terminal-specific files for many common terminals; their main purpose is -to make entries in @code{input-decode-map} beyond those that can be -deduced from Termcap and Terminfo. @xref{Terminal-Specific}. -@end defvar - -@defvar local-function-key-map -This variable holds a keymap similar to @code{input-decode-map} except -that it describes key sequences which should be translated to -alternative interpretations that are usually preferred. It applies -after @code{input-decode-map} and before @code{key-translation-map}. - -Entries in @code{local-function-key-map} are ignored if they conflict -with bindings made in the minor mode, local, or global keymaps. I.e. -the remapping only applies if the original key sequence would -otherwise not have any binding. - -@code{local-function-key-map} inherits from @code{function-key-map}, -but the latter should not be used directly. -@end defvar - -@defvar key-translation-map -This variable is another keymap used just like @code{input-decode-map} -to translate input events into other events. It differs from -@code{input-decode-map} in that it goes to work after -@code{local-function-key-map} is finished rather than before; it -receives the results of translation by @code{local-function-key-map}. - -Just like @code{input-decode-map}, but unlike -@code{local-function-key-map}, this keymap is applied regardless of -whether the input key-sequence has a normal binding. Note however -that actual key bindings can have an effect on -@code{key-translation-map}, even though they are overridden by it. -Indeed, actual key bindings override @code{local-function-key-map} and -thus may alter the key sequence that @code{key-translation-map} -receives. Clearly, it is better to avoid this type of situation. - -The intent of @code{key-translation-map} is for users to map one -character set to another, including ordinary characters normally bound -to @code{self-insert-command}. -@end defvar - -@cindex key translation function -You can use @code{input-decode-map}, @code{local-function-key-map}, or -@code{key-translation-map} for more than simple aliases, by using a -function, instead of a key sequence, as the ``translation'' of a key. -Then this function is called to compute the translation of that key. - -The key translation function receives one argument, which is the prompt -that was specified in @code{read-key-sequence}---or @code{nil} if the -key sequence is being read by the editor command loop. In most cases -you can ignore the prompt value. - -If the function reads input itself, it can have the effect of altering -the event that follows. For example, here's how to define @kbd{C-c h} -to turn the character that follows into a Hyper character: - -@example -@group -(defun hyperify (prompt) - (let ((e (read-event))) - (vector (if (numberp e) - (logior (lsh 1 24) e) - (if (memq 'hyper (event-modifiers e)) - e - (add-event-modifier "H-" e)))))) - -(defun add-event-modifier (string e) - (let ((symbol (if (symbolp e) e (car e)))) - (setq symbol (intern (concat string - (symbol-name symbol)))) -@end group -@group - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - -(define-key local-function-key-map "\C-ch" 'hyperify) -@end group -@end example - - If you have enabled keyboard character set decoding using -@code{set-keyboard-coding-system}, decoding is done after the -translations listed above. @xref{Terminal I/O Encoding}. However, in -future Emacs versions, character set decoding may be done at an -earlier stage. - -@node Key Binding Commands -@section Commands for Binding Keys - - This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. - - People often use @code{global-set-key} in their init files -(@pxref{Init File}) for simple customization. For example, - -@smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) -@end smallexample - -@noindent -redefines @kbd{C-x C-\} to move down a line. - -@smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) -@end smallexample - -@noindent -redefines the first (leftmost) mouse button, entered with the Meta key, to -set point where you click. - -@cindex non-@acronym{ASCII} text in keybindings - Be careful when using non-@acronym{ASCII} text characters in Lisp -specifications of keys to bind. If these are read as multibyte text, as -they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you -must type the keys as multibyte too. For instance, if you use this: - -@smallexample -(global-set-key "@"o" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?@"o 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -and your language environment is multibyte Latin-1, these commands -actually bind the multibyte character with code 2294, not the unibyte -Latin-1 character with code 246 (@kbd{M-v}). In order to use this -binding, you need to enter the multibyte Latin-1 character as keyboard -input. One way to do this is by using an appropriate input method -(@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). - - If you want to use a unibyte character in the key binding, you can -construct the key sequence string using @code{multibyte-char-to-unibyte} -or @code{string-make-unibyte} (@pxref{Converting Representations}). - -@deffn Command global-set-key key binding -This function sets the binding of @var{key} in the current global map -to @var{binding}. - -@smallexample -@group -(global-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-global-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command global-unset-key key -@cindex unbinding keys -This function removes the binding of @var{key} from the current -global map. - -One use of this function is in preparation for defining a longer key -that uses @var{key} as a prefix---which would not be allowed if -@var{key} has a non-prefix binding. For example: - -@smallexample -@group -(global-unset-key "\C-l") - @result{} nil -@end group -@group -(global-set-key "\C-l\C-l" 'redraw-display) - @result{} nil -@end group -@end smallexample - -This function is implemented simply using @code{define-key}: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@deffn Command local-set-key key binding -This function sets the binding of @var{key} in the current local -keymap to @var{binding}. - -@smallexample -@group -(local-set-key @var{key} @var{binding}) -@equiv{} -(define-key (current-local-map) @var{key} @var{binding}) -@end group -@end smallexample -@end deffn - -@deffn Command local-unset-key key -This function removes the binding of @var{key} from the current -local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample -@end deffn - -@node Scanning Keymaps -@section Scanning Keymaps - - This section describes functions used to scan all the current keymaps -for the sake of printing help information. - -@defun accessible-keymaps keymap &optional prefix -This function returns a list of all the keymaps that can be reached (via -zero or more prefix keys) from @var{keymap}. The value is an -association list with elements of the form @code{(@var{key} .@: -@var{map})}, where @var{key} is a prefix key whose definition in -@var{keymap} is @var{map}. - -The elements of the alist are ordered so that the @var{key} increases -in length. The first element is always @code{([] .@: @var{keymap})}, -because the specified keymap is accessible from itself with a prefix of -no events. - -If @var{prefix} is given, it should be a prefix key sequence; then -@code{accessible-keymaps} includes only the submaps whose prefixes start -with @var{prefix}. These elements look just as they do in the value of -@code{(accessible-keymaps)}; the only difference is that some elements -are omitted. - -In the example below, the returned alist indicates that the key -@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose -definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) -(115 .@: foo))}. - -@smallexample -@group -(accessible-keymaps (current-local-map)) -@result{}(([] keymap - (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} - (83 . center-paragraph) - (115 . center-line)) - (9 . tab-to-tab-stop)) -@end group - -@group - ("^[" keymap - (83 . center-paragraph) - (115 . foo))) -@end group -@end smallexample - -In the following example, @kbd{C-h} is a prefix key that uses a sparse -keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. -Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of -the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of -several dummy events used as prefixes for mouse actions in special parts -of a window. - -@smallexample -@group -(accessible-keymaps (current-global-map)) -@result{} (([] keymap [set-mark-command beginning-of-line @dots{} - delete-backward-char]) -@end group -@group - ("^H" keymap (118 . describe-variable) @dots{} - (8 . help-for-help)) -@end group -@group - ("^X" keymap [x-flush-mouse-queue @dots{} - backward-kill-sentence]) -@end group -@group - ("^[" keymap [mark-sexp backward-sexp @dots{} - backward-kill-word]) -@end group - ("^X4" keymap (15 . display-buffer) @dots{}) -@group - ([mode-line] keymap - (S-mouse-2 . mouse-split-window-horizontally) @dots{})) -@end group -@end smallexample - -@noindent -These are not all the keymaps you would see in actuality. -@end defun - -@defun map-keymap function keymap -The function @code{map-keymap} calls @var{function} once -for each binding in @var{keymap}. It passes two arguments, -the event type and the value of the binding. If @var{keymap} -has a parent, the parent's bindings are included as well. -This works recursively: if the parent has itself a parent, then the -grandparent's bindings are also included and so on. - -This function is the cleanest way to examine all the bindings -in a keymap. -@end defun - -@defun where-is-internal command &optional keymap firstonly noindirect no-remap -This function is a subroutine used by the @code{where-is} command -(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list -of all key sequences (of any length) that are bound to @var{command} in a -set of keymaps. - -The argument @var{command} can be any object; it is compared with all -keymap entries using @code{eq}. - -If @var{keymap} is @code{nil}, then the maps used are the current active -keymaps, disregarding @code{overriding-local-map} (that is, pretending -its value is @code{nil}). If @var{keymap} is a keymap, then the -maps searched are @var{keymap} and the global keymap. If @var{keymap} -is a list of keymaps, only those keymaps are searched. - -Usually it's best to use @code{overriding-local-map} as the expression -for @var{keymap}. Then @code{where-is-internal} searches precisely the -keymaps that are active. To search only the global map, pass -@code{(keymap)} (an empty keymap) as @var{keymap}. - -If @var{firstonly} is @code{non-ascii}, then the value is a single -vector representing the first key sequence found, rather than a list of -all possible key sequences. If @var{firstonly} is @code{t}, then the -value is the first key sequence, except that key sequences consisting -entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII} -characters) are preferred to all other key sequences and that the -return value can never be a menu binding. - -If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't -follow indirect keymap bindings. This makes it possible to search for -an indirect definition itself. - -When command remapping is in effect (@pxref{Remapping Commands}), -@code{where-is-internal} figures out when a command will be run due to -remapping and reports keys accordingly. It also returns @code{nil} if -@var{command} won't really be run because it has been remapped to some -other command. However, if @var{no-remap} is non-@code{nil}. -@code{where-is-internal} ignores remappings. - -@smallexample -@group -(where-is-internal 'describe-function) - @result{} ([8 102] [f1 102] [help 102] - [menu-bar help-menu describe describe-function]) -@end group -@end smallexample -@end defun - -@deffn Command describe-bindings &optional prefix buffer-or-name -This function creates a listing of all current key bindings, and -displays it in a buffer named @samp{*Help*}. The text is grouped by -modes---minor modes first, then the major mode, then global bindings. - -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. - -The listing describes meta characters as @key{ESC} followed by the -corresponding non-meta character. - -When several characters with consecutive @acronym{ASCII} codes have the -same definition, they are shown together, as -@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @acronym{ASCII} codes to understand which characters this means. -For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32, -@kbd{~} is @acronym{ASCII} 126, and the characters between them include all -the normal printing characters, (e.g., letters, digits, punctuation, -etc.@:); all these characters are bound to @code{self-insert-command}. - -If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a -buffer name. Then @code{describe-bindings} lists that buffer's bindings, -instead of the current buffer's. -@end deffn - -@node Menu Keymaps -@section Menu Keymaps -@cindex menu keymaps - -A keymap can operate as a menu as well as defining bindings for -keyboard keys and mouse buttons. Menus are usually actuated with the -mouse, but they can function with the keyboard also. If a menu keymap -is active for the next input event, that activates the keyboard menu -feature. - -@menu -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. -@end menu - -@node Defining Menus -@subsection Defining Menus -@cindex defining menus -@cindex menu prompt string -@cindex prompt string (of menu) - -A keymap acts as a menu if it has an @dfn{overall prompt string}, -which is a string that appears as an element of the keymap. -(@xref{Format of Keymaps}.) The string should describe the purpose of -the menu's commands. Emacs displays the overall prompt string as the -menu title in some cases, depending on the toolkit (if any) used for -displaying menus.@footnote{It is required for menus which do not use a -toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the -overall prompt string. - -The easiest way to construct a keymap with a prompt string is to -specify the string as an argument when you call @code{make-keymap}, -@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or -@code{define-prefix-command} (@pxref{Definition of -define-prefix-command}). If you do not want the keymap to operate as -a menu, don't specify a prompt string for it. - -@defun keymap-prompt keymap -This function returns the overall prompt string of @var{keymap}, -or @code{nil} if it has none. -@end defun - -The menu's items are the bindings in the keymap. Each binding -associates an event type to a definition, but the event types have no -significance for the menu appearance. (Usually we use pseudo-events, -symbols that the keyboard cannot generate, as the event types for menu -item bindings.) The menu is generated entirely from the bindings that -correspond in the keymap to these events. - -The order of items in the menu is the same as the order of bindings in -the keymap. Since @code{define-key} puts new bindings at the front, you -should define the menu items starting at the bottom of the menu and -moving to the top, if you care about the order. When you add an item to -an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). - -@menu -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. -@end menu - -@node Simple Menu Items -@subsubsection Simple Menu Items - - The simpler (and original) way to define a menu item is to bind some -event type (it doesn't matter what event type) to a binding like this: - -@example -(@var{item-string} . @var{real-binding}) -@end example - -@noindent -The @sc{car}, @var{item-string}, is the string to be displayed in the -menu. It should be short---preferably one to three words. It should -describe the action of the command it corresponds to. Note that it is -not generally possible to display non-@acronym{ASCII} text in menus. It will -work for keyboard menus and will work to a large extent when Emacs is -built with the Gtk+ toolkit.@footnote{In this case, the text is first -encoded using the @code{utf-8} coding system and then rendered by the -toolkit as it sees fit.} - - You can also supply a second string, called the help string, as follows: - -@example -(@var{item-string} @var{help} . @var{real-binding}) -@end example - -@noindent -@var{help} specifies a ``help-echo'' string to display while the mouse -is on that item in the same way as @code{help-echo} text properties -(@pxref{Help display}). - - As far as @code{define-key} is concerned, @var{item-string} and -@var{help-string} are part of the event's binding. However, -@code{lookup-key} returns just @var{real-binding}, and only -@var{real-binding} is used for executing the key. - - If @var{real-binding} is @code{nil}, then @var{item-string} appears in -the menu but cannot be selected. - - If @var{real-binding} is a symbol and has a non-@code{nil} -@code{menu-enable} property, that property is an expression that -controls whether the menu item is enabled. Every time the keymap is -used to display a menu, Emacs evaluates the expression, and it enables -the menu item only if the expression's value is non-@code{nil}. When a -menu item is disabled, it is displayed in a ``fuzzy'' fashion, and -cannot be selected. - - The menu bar does not recalculate which items are enabled every time you -look at a menu. This is because the X toolkit requires the whole tree -of menus in advance. To force recalculation of the menu bar, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - - You've probably noticed that menu items show the equivalent keyboard key -sequence (if any) to invoke the same command. To save time on -recalculation, menu display caches this information in a sublist in the -binding, like this: - -@c This line is not too long--rms. -@example -(@var{item-string} @r{[}@var{help}@r{]} (@var{key-binding-data}) . @var{real-binding}) -@end example - -@noindent -Don't put these sublists in the menu item yourself; menu display -calculates them automatically. Don't mention keyboard equivalents in -the item strings themselves, since that is redundant. - -@node Extended Menu Items -@subsubsection Extended Menu Items -@kindex menu-item - - An extended-format menu item is a more flexible and also cleaner -alternative to the simple format. You define an event type with a -binding that's a list starting with the symbol @code{menu-item}. -For a non-selectable string, the binding looks like this: - -@example -(menu-item @var{item-name}) -@end example - -@noindent -A string starting with two or more dashes specifies a separator line; -see @ref{Menu Separators}. - - To define a real menu item which can be selected, the extended format -binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} - . @var{item-property-list}) -@end example - -@noindent -Here, @var{item-name} is an expression which evaluates to the menu item -string. Thus, the string need not be a constant. The third element, -@var{real-binding}, is the command to execute. The tail of the list, -@var{item-property-list}, has the form of a property list which contains -other information. - - When an equivalent keyboard key binding is cached, the extended menu -item binding looks like this: - -@example -(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data}) - . @var{item-property-list}) -@end example - - Here is a table of the properties that are supported: - -@table @code -@item :enable @var{form} -The result of evaluating @var{form} determines whether the item is -enabled (non-@code{nil} means yes). If the item is not enabled, -you can't really click on it. - -@item :visible @var{form} -The result of evaluating @var{form} determines whether the item should -actually appear in the menu (non-@code{nil} means yes). If the item -does not appear, then the menu is displayed as if this item were -not defined at all. - -@item :help @var{help} -The value of this property, @var{help}, specifies a ``help-echo'' string -to display while the mouse is on that item. This is displayed in the -same way as @code{help-echo} text properties (@pxref{Help display}). -Note that this must be a constant string, unlike the @code{help-echo} -property for text and overlays. - -@item :button (@var{type} . @var{selected}) -This property provides a way to define radio buttons and toggle buttons. -The @sc{car}, @var{type}, says which: it should be @code{:toggle} or -@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the -result of evaluating it says whether this button is currently selected. - -A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off'' -according to the value of @var{selected}. The command itself should -toggle @var{selected}, setting it to @code{t} if it is @code{nil}, -and to @code{nil} if it is @code{t}. Here is how the menu item -to toggle the @code{debug-on-error} flag is defined: - -@example -(menu-item "Debug on Error" toggle-debug-on-error - :button (:toggle - . (and (boundp 'debug-on-error) - debug-on-error))) -@end example - -@noindent -This works because @code{toggle-debug-on-error} is defined as a command -which toggles the variable @code{debug-on-error}. - -@dfn{Radio buttons} are a group of menu items, in which at any time one -and only one is ``selected.'' There should be a variable whose value -says which one is selected at any time. The @var{selected} form for -each radio button in the group should check whether the variable has the -right value for selecting that button. Clicking on the button should -set the variable so that the button you clicked on becomes selected. - -@item :key-sequence @var{key-sequence} -This property specifies which key sequence is likely to be bound to the -same command invoked by this menu item. If you specify the right key -sequence, that makes preparing the menu for display run much faster. - -If you specify the wrong key sequence, it has no effect; before Emacs -displays @var{key-sequence} in the menu, it verifies that -@var{key-sequence} is really equivalent to this menu item. - -@item :key-sequence nil -This property indicates that there is normally no key binding which is -equivalent to this menu item. Using this property saves time in -preparing the menu for display, because Emacs does not need to search -the keymaps for a keyboard equivalent for this menu item. - -However, if the user has rebound this item's definition to a key -sequence, Emacs ignores the @code{:keys} property and finds the keyboard -equivalent anyway. - -@item :keys @var{string} -This property specifies that @var{string} is the string to display -as the keyboard equivalent for this menu item. You can use -the @samp{\\[...]} documentation construct in @var{string}. - -@item :filter @var{filter-fn} -This property provides a way to compute the menu item dynamically. -The property value @var{filter-fn} should be a function of one argument; -when it is called, its argument will be @var{real-binding}. The -function should return the binding to use instead. - -Emacs can call this function at any time that it does redisplay or -operates on menu data structures, so you should write it so it can -safely be called at any time. -@end table - -@node Menu Separators -@subsubsection Menu Separators -@cindex menu separators - - A menu separator is a kind of menu item that doesn't display any -text---instead, it divides the menu into subparts with a horizontal line. -A separator looks like this in the menu keymap: - -@example -(menu-item @var{separator-type}) -@end example - -@noindent -where @var{separator-type} is a string starting with two or more dashes. - - In the simplest case, @var{separator-type} consists of only dashes. -That specifies the default kind of separator. (For compatibility, -@code{""} and @code{-} also count as separators.) - - Certain other values of @var{separator-type} specify a different -style of separator. Here is a table of them: - -@table @code -@item "--no-line" -@itemx "--space" -An extra vertical space, with no actual line. - -@item "--single-line" -A single line in the menu's foreground color. - -@item "--double-line" -A double line in the menu's foreground color. - -@item "--single-dashed-line" -A single dashed line in the menu's foreground color. - -@item "--double-dashed-line" -A double dashed line in the menu's foreground color. - -@item "--shadow-etched-in" -A single line with a 3D sunken appearance. This is the default, -used separators consisting of dashes only. - -@item "--shadow-etched-out" -A single line with a 3D raised appearance. - -@item "--shadow-etched-in-dash" -A single dashed line with a 3D sunken appearance. - -@item "--shadow-etched-out-dash" -A single dashed line with a 3D raised appearance. - -@item "--shadow-double-etched-in" -Two lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out" -Two lines with a 3D raised appearance. - -@item "--shadow-double-etched-in-dash" -Two dashed lines with a 3D sunken appearance. - -@item "--shadow-double-etched-out-dash" -Two dashed lines with a 3D raised appearance. -@end table - - You can also give these names in another style, adding a colon after -the double-dash and replacing each single dash with capitalization of -the following word. Thus, @code{"--:singleLine"}, is equivalent to -@code{"--single-line"}. - - Some systems and display toolkits don't really handle all of these -separator types. If you use a type that isn't supported, the menu -displays a similar kind of separator that is supported. - -@node Alias Menu Items -@subsubsection Alias Menu Items - - Sometimes it is useful to make menu items that use the ``same'' -command but with different enable conditions. The best way to do this -in Emacs now is with extended menu items; before that feature existed, -it could be done by defining alias commands and using them in menu -items. Here's an example that makes two aliases for -@code{toggle-read-only} and gives them different enable conditions: - -@example -(defalias 'make-read-only 'toggle-read-only) -(put 'make-read-only 'menu-enable '(not buffer-read-only)) -(defalias 'make-writable 'toggle-read-only) -(put 'make-writable 'menu-enable 'buffer-read-only) -@end example - -When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases -(which typically don't have any key bindings except for the menu -itself). To request this, give the alias symbol a non-@code{nil} -@code{menu-alias} property. Thus, - -@example -(put 'make-read-only 'menu-alias t) -(put 'make-writable 'menu-alias t) -@end example - -@noindent -causes menu items for @code{make-read-only} and @code{make-writable} to -show the keyboard bindings for @code{toggle-read-only}. - -@node Mouse Menus -@subsection Menus and the Mouse - - The usual way to make a menu keymap produce a menu is to make it the -definition of a prefix key. (A Lisp program can explicitly pop up a -menu and receive the user's choice---see @ref{Pop-Up Menus}.) - - If the prefix key ends with a mouse event, Emacs handles the menu keymap -by popping up a visible menu, so that the user can select a choice with -the mouse. When the user clicks on a menu item, the event generated is -whatever character or symbol has the binding that brought about that -menu item. (A menu item may generate a series of events if the menu has -multiple levels or comes from the menu bar.) - - It's often best to use a button-down event to trigger the menu. Then -the user can select a menu item by releasing the button. - - A single keymap can appear as multiple menu panes, if you explicitly -arrange for this. The way to do this is to make a keymap for each pane, -then create a binding for each of those maps in the main keymap of the -menu. Give each of these bindings an item string that starts with -@samp{@@}. The rest of the item string becomes the name of the pane. -See the file @file{lisp/mouse.el} for an example of this. Any ordinary -bindings with @samp{@@}-less item strings are grouped into one pane, -which appears along with the other panes explicitly created for the -submaps. - - X toolkit menus don't have panes; instead, they can have submenus. -Every nested keymap becomes a submenu, whether the item string starts -with @samp{@@} or not. In a toolkit version of Emacs, the only thing -special about @samp{@@} at the beginning of an item string is that the -@samp{@@} doesn't appear in the menu item. - - Multiple keymaps that define the same menu prefix key produce -separate panes or separate submenus. - -@node Keyboard Menus -@subsection Menus and the Keyboard - - When a prefix key ending with a keyboard event (a character or -function key) has a definition that is a menu keymap, the keymap -operates as a keyboard menu; the user specifies the next event by -choosing a menu item with the keyboard. - - Emacs displays the keyboard menu with the map's overall prompt -string, followed by the alternatives (the item strings of the map's -bindings), in the echo area. If the bindings don't all fit at once, -the user can type @key{SPC} to see the next line of alternatives. -Successive uses of @key{SPC} eventually get to the end of the menu and -then cycle around to the beginning. (The variable -@code{menu-prompt-more-char} specifies which character is used for -this; @key{SPC} is the default.) - - When the user has found the desired alternative from the menu, he or -she should type the corresponding character---the one whose binding is -that alternative. - -@ignore -In a menu intended for keyboard use, each menu item must clearly -indicate what character to type. The best convention to use is to make -the character the first letter of the item string---that is something -users will understand without being told. We plan to change this; by -the time you read this manual, keyboard menus may explicitly name the -key for each alternative. -@end ignore - - This way of using menus in an Emacs-like editor was inspired by the -Hierarkey system. - -@defvar menu-prompt-more-char -This variable specifies the character to use to ask to see -the next line of a menu. Its initial value is 32, the code -for @key{SPC}. -@end defvar - -@node Menu Example -@subsection Menu Example -@cindex menu definition example - - Here is a complete example of defining a menu keymap. It is the -definition of the @samp{Replace} submenu in the @samp{Edit} menu in -the menu bar, and it uses the extended menu item format -(@pxref{Extended Menu Items}). First we create the keymap, and give -it a name: - -@smallexample -(defvar menu-bar-replace-menu (make-sparse-keymap "Replace")) -@end smallexample - -@noindent -Next we define the menu items: - -@smallexample -(define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue - :help "Continue last tags replace operation")) -(define-key menu-bar-replace-menu [tags-repl] - '(menu-item "Replace in tagged files" tags-query-replace - :help "Interactively replace a regexp in all tagged files")) -(define-key menu-bar-replace-menu [separator-replace-tags] - '(menu-item "--")) -;; @r{@dots{}} -@end smallexample - -@noindent -Note the symbols which the bindings are ``made for''; these appear -inside square brackets, in the key sequence being defined. In some -cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys,'' but they are -not real function keys on the keyboard. They do not affect the -functioning of the menu itself, but they are ``echoed'' in the echo area -when the user selects from the menu, and they appear in the output of -@code{where-is} and @code{apropos}. - - The menu in this example is intended for use with the mouse. If a -menu is intended for use with the keyboard, that is, if it is bound to -a key sequence ending with a keyboard event, then the menu items -should be bound to characters or ``real'' function keys, that can be -typed with the keyboard. - - The binding whose definition is @code{("--")} is a separator line. -Like a real menu item, the separator has a key symbol, in this case -@code{separator-replace-tags}. If one menu has two separators, they -must have two different key symbols. - - Here is how we make this menu appear as an item in the parent menu: - -@example -(define-key menu-bar-edit-menu [replace] - (list 'menu-item "Replace" menu-bar-replace-menu)) -@end example - -@noindent -Note that this incorporates the submenu keymap, which is the value of -the variable @code{menu-bar-replace-menu}, rather than the symbol -@code{menu-bar-replace-menu} itself. Using that symbol in the parent -menu item would be meaningless because @code{menu-bar-replace-menu} is -not a command. - - If you wanted to attach the same replace menu to a mouse click, you -can do it this way: - -@example -(define-key global-map [C-S-down-mouse-1] - menu-bar-replace-menu) -@end example - -@node Menu Bar -@subsection The Menu Bar -@cindex menu bar - - Most window systems allow each frame to have a @dfn{menu bar}---a -permanently displayed menu stretching horizontally across the top of the -frame. The items of the menu bar are the subcommands of the fake -``function key'' @code{menu-bar}, as defined in the active keymaps. - - To add an item to the menu bar, invent a fake ``function key'' of your -own (let's call it @var{key}), and make a binding for the key sequence -@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, -so that pressing a button on the menu bar item leads to another menu. - - When more than one active keymap defines the same fake function key -for the menu bar, the item appears just once. If the user clicks on -that menu bar item, it brings up a single, combined menu containing -all the subcommands of that item---the global subcommands, the local -subcommands, and the minor mode subcommands. - - The variable @code{overriding-local-map} is normally ignored when -determining the menu bar contents. That is, the menu bar is computed -from the keymaps that would be active if @code{overriding-local-map} -were @code{nil}. @xref{Active Keymaps}. - - In order for a frame to display a menu bar, its @code{menu-bar-lines} -parameter must be greater than zero. Emacs uses just one line for the -menu bar itself; if you specify more than one line, the other lines -serve to separate the menu bar from the windows in the frame. We -recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout -Parameters}. - - Here's an example of setting up a menu bar item: - -@example -@group -(modify-frame-parameters (selected-frame) - '((menu-bar-lines . 2))) -@end group - -@group -;; @r{Make a menu keymap (with a prompt string)} -;; @r{and make it the menu bar item's definition.} -(define-key global-map [menu-bar words] - (cons "Words" (make-sparse-keymap "Words"))) -@end group - -@group -;; @r{Define specific subcommands in this menu.} -(define-key global-map - [menu-bar words forward] - '("Forward word" . forward-word)) -@end group -@group -(define-key global-map - [menu-bar words backward] - '("Backward word" . backward-word)) -@end group -@end example - - A local keymap can cancel a menu bar item made by the global keymap by -rebinding the same fake function key with @code{undefined} as the -binding. For example, this is how Dired suppresses the @samp{Edit} menu -bar item: - -@example -(define-key dired-mode-map [menu-bar edit] 'undefined) -@end example - -@noindent -@code{edit} is the fake function key used by the global map for the -@samp{Edit} menu bar item. The main reason to suppress a global -menu bar item is to regain space for mode-specific items. - -@defvar menu-bar-final-items -Normally the menu bar shows global items followed by items defined by the -local maps. - -This variable holds a list of fake function keys for items to display at -the end of the menu bar rather than in normal sequence. The default -value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears -at the end of the menu bar, following local menu items. -@end defvar - -@defvar menu-bar-update-hook -This normal hook is run by redisplay to update the menu bar contents, -before redisplaying the menu bar. You can use it to update submenus -whose contents should vary. Since this hook is run frequently, we -advise you to ensure that the functions it calls do not take much time -in the usual case. -@end defvar - -@node Tool Bar -@subsection Tool bars -@cindex tool bar - - A @dfn{tool bar} is a row of icons at the top of a frame, that execute -commands when you click on them---in effect, a kind of graphical menu -bar. - - The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar}) -controls how many lines' worth of height to reserve for the tool bar. A -zero value suppresses the tool bar. If the value is nonzero, and -@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and -contracts automatically as needed to hold the specified contents. - - If the value of @code{auto-resize-tool-bars} is @code{grow-only}, -the tool bar expands automatically, but does not contract automatically. -To contract the tool bar, the user has to redraw the frame by entering -@kbd{C-l}. - - The tool bar contents are controlled by a menu keymap attached to a -fake ``function key'' called @code{tool-bar} (much like the way the menu -bar is controlled). So you define a tool bar item using -@code{define-key}, like this: - -@example -(define-key global-map [tool-bar @var{key}] @var{item}) -@end example - -@noindent -where @var{key} is a fake ``function key'' to distinguish this item from -other items, and @var{item} is a menu item key binding (@pxref{Extended -Menu Items}), which says how to display this item and how it behaves. - - The usual menu keymap item properties, @code{:visible}, -@code{:enable}, @code{:button}, and @code{:filter}, are useful in -tool bar bindings and have their normal meanings. The @var{real-binding} -in the item must be a command, not a keymap; in other words, it does not -work to define a tool bar icon as a prefix key. - - The @code{:help} property specifies a ``help-echo'' string to display -while the mouse is on that item. This is displayed in the same way as -@code{help-echo} text properties (@pxref{Help display}). - - In addition, you should use the @code{:image} property; -this is how you specify the image to display in the tool bar: - -@table @code -@item :image @var{image} -@var{images} is either a single image specification or a vector of four -image specifications. If you use a vector of four, -one of them is used, depending on circumstances: - -@table @asis -@item item 0 -Used when the item is enabled and selected. -@item item 1 -Used when the item is enabled and deselected. -@item item 2 -Used when the item is disabled and selected. -@item item 3 -Used when the item is disabled and deselected. -@end table -@end table - -If @var{image} is a single image specification, Emacs draws the tool bar -button in disabled state by applying an edge-detection algorithm to the -image. - -The @code{:rtl} property specifies an alternative image to use for -right-to-left languages. Only the Gtk+ version of Emacs supports this -at present. - -The default tool bar is defined so that items specific to editing do not -appear for major modes whose command symbol has a @code{mode-class} -property of @code{special} (@pxref{Major Mode Conventions}). Major -modes may add items to the global bar by binding @code{[tool-bar -@var{foo}]} in their local map. It makes sense for some major modes to -replace the default tool bar items completely, since not many can be -accommodated conveniently, and the default bindings make this easy by -using an indirection through @code{tool-bar-map}. - -@defvar tool-bar-map -By default, the global map binds @code{[tool-bar]} as follows: -@example -(global-set-key [tool-bar] - '(menu-item "tool bar" ignore - :filter (lambda (ignore) tool-bar-map))) -@end example -@noindent -Thus the tool bar map is derived dynamically from the value of variable -@code{tool-bar-map} and you should normally adjust the default (global) -tool bar by changing that map. Major modes may replace the global bar -completely by making @code{tool-bar-map} buffer-local and set to a -keymap containing only the desired items. Info mode provides an -example. -@end defvar - -There are two convenience functions for defining tool bar items, as -follows. - -@defun tool-bar-add-item icon def key &rest props -This function adds an item to the tool bar by modifying -@code{tool-bar-map}. The image to use is defined by @var{icon}, which -is the base name of an XPM, XBM or PBM image file to be located by -@code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm}, -@file{exit.pbm} and @file{exit.xbm} would be searched for in that order -on a color display. On a monochrome display, the search order is -@samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the -command @var{def}, and @var{key} is the fake function key symbol in the -prefix keymap. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. - -To define items in some local map, bind @code{tool-bar-map} with -@code{let} around calls of this function: -@example -(defvar foo-tool-bar-map - (let ((tool-bar-map (make-sparse-keymap))) - (tool-bar-add-item @dots{}) - @dots{} - tool-bar-map)) -@end example -@end defun - -@defun tool-bar-add-item-from-menu command icon &optional map &rest props -This function is a convenience for defining tool bar items which are -consistent with existing menu bar bindings. The binding of -@var{command} is looked up in the menu bar in @var{map} (default -@code{global-map}) and modified to add an image specification for -@var{icon}, which is found in the same way as by -@code{tool-bar-add-item}. The resulting binding is then placed in -@code{tool-bar-map}, so use this function only for global tool bar -items. - -@var{map} must contain an appropriate keymap bound to -@code{[menu-bar]}. The remaining arguments @var{props} are additional -property list elements to add to the menu item specification. -@end defun - -@defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props -This function is used for making non-global tool bar items. Use it -like @code{tool-bar-add-item-from-menu} except that @var{in-map} -specifies the local map to make the definition in. The argument -@var{from-map} is like the @var{map} argument of -@code{tool-bar-add-item-from-menu}. -@end defun - -@defvar auto-resize-tool-bars -If this variable is non-@code{nil}, the tool bar automatically resizes to -show all defined tool bar items---but not larger than a quarter of the -frame's height. - -If the value is @code{grow-only}, the tool bar expands automatically, -but does not contract automatically. To contract the tool bar, the -user has to redraw the frame by entering @kbd{C-l}. - -If Emacs is built with GTK or Nextstep, the tool bar can only show one -line, so this variable has no effect. -@end defvar - -@defvar auto-raise-tool-bar-buttons -If this variable is non-@code{nil}, tool bar items display -in raised form when the mouse moves over them. -@end defvar - -@defvar tool-bar-button-margin -This variable specifies an extra margin to add around tool bar items. -The value is an integer, a number of pixels. The default is 4. -@end defvar - -@defvar tool-bar-button-relief -This variable specifies the shadow width for tool bar items. -The value is an integer, a number of pixels. The default is 1. -@end defvar - -@defvar tool-bar-border -This variable specifies the height of the border drawn below the tool -bar area. An integer value specifies height as a number of pixels. -If the value is one of @code{internal-border-width} (the default) or -@code{border-width}, the tool bar border height corresponds to the -corresponding frame parameter. -@end defvar - - You can define a special meaning for clicking on a tool bar item with -the shift, control, meta, etc., modifiers. You do this by setting up -additional items that relate to the original item through the fake -function keys. Specifically, the additional items should use the -modified versions of the same fake function key used to name the -original item. - - Thus, if the original item was defined this way, - -@example -(define-key global-map [tool-bar shell] - '(menu-item "Shell" shell - :image (image :type xpm :file "shell.xpm"))) -@end example - -@noindent -then here is how you can define clicking on the same tool bar image with -the shift modifier: - -@example -(define-key global-map [tool-bar S-shell] 'some-command) -@end example - -@xref{Function Keys}, for more information about how to add modifiers to -function keys. - -@node Modifying Menus -@subsection Modifying Menus - - When you insert a new item in an existing menu, you probably want to -put it in a particular place among the menu's existing items. If you -use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: - -@defun define-key-after map key binding &optional after -Define a binding in @var{map} for @var{key}, with value @var{binding}, -just like @code{define-key}, but position the binding in @var{map} after -the binding for the event @var{after}. The argument @var{key} should be -of length one---a vector or string with just one element. But -@var{after} should be a single event type---a symbol or a character, not -a sequence. The new binding goes after the binding for @var{after}. If -@var{after} is @code{t} or is omitted, then the new binding goes last, at -the end of the keymap. However, new bindings are added before any -inherited keymap. - -Here is an example: - -@example -(define-key-after my-menu [drink] - '("Drink" . drink-command) 'eat) -@end example - -@noindent -makes a binding for the fake function key @key{DRINK} and puts it -right after the binding for @key{EAT}. - -Here is how to insert an item called @samp{Work} in the @samp{Signals} -menu of Shell mode, after the item @code{break}: - -@example -(define-key-after - (lookup-key shell-mode-map [menu-bar signals]) - [work] '("Work" . work-command) 'break) -@end example -@end defun - -@ignore - arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794 -@end ignore diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi deleted file mode 100644 index 64854e9bdfe..00000000000 --- a/doc/lispref/lay-flat.texi +++ /dev/null @@ -1,48 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@c -@comment %**start of header -@setfilename inner-covers.info -@settitle Inner Covers -@smallbook -@comment %**end of header - -@headings off - -@w{ } -@sp 4 -@tex -\center {\secfonts \rm Lay-Flat Binding} -@end tex -@sp 2 - -We have bound this manual using a new @dfn{lay-flat} binding -technology. This type of binding allows you to open a soft cover book -so that it ``lays flat'' on a table without creasing the binding. - -In order to make the book lay flat properly, you need to ``crack'' the -binding. To do this, divide the book into two sections and bend it so -that the front and back covers meet. Do not worry; the pages are -sewn and glued to the binding, and will not fall out easily. -The outer cardboard binding itself is designed so that it will not -break or crease as an ordinary paperback binding will. Bend the book -several times in this manner, dividing it in a different place each -time and pressing the pages flat and open. With use, the binding will -become flexible and the pages will lay flat without needing to be -pushed or held down. - -@page - - -@tex -\center {\secfonts \rm Notes} -@end tex - -@bye - -@ignore - arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07 -@end ignore diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi deleted file mode 100644 index d38cdc14505..00000000000 --- a/doc/lispref/lists.texi +++ /dev/null @@ -1,1894 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/lists -@node Lists, Sequences Arrays Vectors, Strings and Characters, Top -@chapter Lists -@cindex lists -@cindex element (of list) - - A @dfn{list} represents a sequence of zero or more elements (which may -be any Lisp objects). The important difference between lists and -vectors is that two or more lists can share part of their structure; in -addition, you can insert or delete elements in a list without copying -the whole list. - -@menu -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. -@end menu - -@node Cons Cells -@section Lists and Cons Cells -@cindex lists and cons cells - - Lists in Lisp are not a primitive data type; they are built up from -@dfn{cons cells}. A cons cell is a data object that represents an -ordered pair. That is, it has two slots, and each slot @dfn{holds}, or -@dfn{refers to}, some Lisp object. One slot is known as the @sc{car}, -and the other is known as the @sc{cdr}. (These names are traditional; -see @ref{Cons Cell Type}.) @sc{cdr} is pronounced ``could-er.'' - - We say that ``the @sc{car} of this cons cell is'' whatever object -its @sc{car} slot currently holds, and likewise for the @sc{cdr}. - - A list is a series of cons cells ``chained together,'' so that each -cell refers to the next one. There is one cons cell for each element of -the list. By convention, the @sc{car}s of the cons cells hold the -elements of the list, and the @sc{cdr}s are used to chain the list: the -@sc{cdr} slot of each cons cell refers to the following cons cell. The -@sc{cdr} of the last cons cell is @code{nil}. This asymmetry between -the @sc{car} and the @sc{cdr} is entirely a matter of convention; at the -level of cons cells, the @sc{car} and @sc{cdr} slots have the same -characteristics. - -@cindex true list - Since @code{nil} is the conventional value to put in the @sc{cdr} of -the last cons cell in the list, we call that case a @dfn{true list}. - - In Lisp, we consider the symbol @code{nil} a list as well as a -symbol; it is the list with no elements. For convenience, the symbol -@code{nil} is considered to have @code{nil} as its @sc{cdr} (and also -as its @sc{car}). Therefore, the @sc{cdr} of a true list is always a -true list. - -@cindex dotted list -@cindex circular list - If the @sc{cdr} of a list's last cons cell is some other value, -neither @code{nil} nor another cons cell, we call the structure a -@dfn{dotted list}, since its printed representation would use -@samp{.}. There is one other possibility: some cons cell's @sc{cdr} -could point to one of the previous cons cells in the list. We call -that structure a @dfn{circular list}. - - For some purposes, it does not matter whether a list is true, -circular or dotted. If the program doesn't look far enough down the -list to see the @sc{cdr} of the final cons cell, it won't care. -However, some functions that operate on lists demand true lists and -signal errors if given a dotted list. Most functions that try to find -the end of a list enter infinite loops if given a circular list. - -@cindex list structure - Because most cons cells are used as part of lists, the phrase -@dfn{list structure} has come to mean any structure made out of cons -cells. - - The @sc{cdr} of any nonempty true list @var{l} is a list containing all the -elements of @var{l} except the first. - - @xref{Cons Cell Type}, for the read and print syntax of cons cells and -lists, and for ``box and arrow'' illustrations of lists. - -@node List-related Predicates -@section Predicates on Lists - - The following predicates test whether a Lisp object is an atom, -whether it is a cons cell or is a list, or whether it is the -distinguished object @code{nil}. (Many of these predicates can be -defined in terms of the others, but they are used so often that it is -worth having all of them.) - -@defun consp object -This function returns @code{t} if @var{object} is a cons cell, @code{nil} -otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. -@end defun - -@defun atom object -This function returns @code{t} if @var{object} is an atom, @code{nil} -otherwise. All objects except cons cells are atoms. The symbol -@code{nil} is an atom and is also a list; it is the only Lisp object -that is both. - -@example -(atom @var{object}) @equiv{} (not (consp @var{object})) -@end example -@end defun - -@defun listp object -This function returns @code{t} if @var{object} is a cons cell or -@code{nil}. Otherwise, it returns @code{nil}. - -@example -@group -(listp '(1)) - @result{} t -@end group -@group -(listp '()) - @result{} t -@end group -@end example -@end defun - -@defun nlistp object -This function is the opposite of @code{listp}: it returns @code{t} if -@var{object} is not a list. Otherwise, it returns @code{nil}. - -@example -(listp @var{object}) @equiv{} (not (nlistp @var{object})) -@end example -@end defun - -@defun null object -This function returns @code{t} if @var{object} is @code{nil}, and -returns @code{nil} otherwise. This function is identical to @code{not}, -but as a matter of clarity we use @code{null} when @var{object} is -considered a list and @code{not} when it is considered a truth value -(see @code{not} in @ref{Combining Conditions}). - -@example -@group -(null '(1)) - @result{} nil -@end group -@group -(null '()) - @result{} t -@end group -@end example -@end defun - - -@node List Elements -@section Accessing Elements of Lists -@cindex list elements - -@defun car cons-cell -This function returns the value referred to by the first slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{car} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}. Therefore, any list is a valid argument. An -error is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(car '(a b c)) - @result{} a -@end group -@group -(car '()) - @result{} nil -@end group -@end example -@end defun - -@defun cdr cons-cell -This function returns the value referred to by the second slot of the -cons cell @var{cons-cell}. In other words, it returns the @sc{cdr} of -@var{cons-cell}. - -As a special case, if @var{cons-cell} is @code{nil}, this function -returns @code{nil}; therefore, any list is a valid argument. An error -is signaled if the argument is not a cons cell or @code{nil}. - -@example -@group -(cdr '(a b c)) - @result{} (b c) -@end group -@group -(cdr '()) - @result{} nil -@end group -@end example -@end defun - -@defun car-safe object -This function lets you take the @sc{car} of a cons cell while avoiding -errors for other data types. It returns the @sc{car} of @var{object} if -@var{object} is a cons cell, @code{nil} otherwise. This is in contrast -to @code{car}, which signals an error if @var{object} is not a list. - -@example -@group -(car-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (car x) - nil)) -@end group -@end example -@end defun - -@defun cdr-safe object -This function lets you take the @sc{cdr} of a cons cell while -avoiding errors for other data types. It returns the @sc{cdr} of -@var{object} if @var{object} is a cons cell, @code{nil} otherwise. -This is in contrast to @code{cdr}, which signals an error if -@var{object} is not a list. - -@example -@group -(cdr-safe @var{object}) -@equiv{} -(let ((x @var{object})) - (if (consp x) - (cdr x) - nil)) -@end group -@end example -@end defun - -@defmac pop listname -This macro is a way of examining the @sc{car} of a list, -and taking it off the list, all at once. - -It operates on the list which is stored in the symbol @var{listname}. -It removes this element from the list by setting @var{listname} -to the @sc{cdr} of its old value---but it also returns the @sc{car} -of that list, which is the element being removed. - -@example -x - @result{} (a b c) -(pop x) - @result{} a -x - @result{} (b c) -@end example -@end defmac - -@defun nth n list -@anchor{Definition of nth} -This function returns the @var{n}th element of @var{list}. Elements -are numbered starting with zero, so the @sc{car} of @var{list} is -element number zero. If the length of @var{list} is @var{n} or less, -the value is @code{nil}. - -If @var{n} is negative, @code{nth} returns the first element of -@var{list}. - -@example -@group -(nth 2 '(1 2 3 4)) - @result{} 3 -@end group -@group -(nth 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nth -3 '(1 2 3 4)) - @result{} 1 - -(nth n x) @equiv{} (car (nthcdr n x)) -@end group -@end example - -The function @code{elt} is similar, but applies to any kind of sequence. -For historical reasons, it takes its arguments in the opposite order. -@xref{Sequence Functions}. -@end defun - -@defun nthcdr n list -This function returns the @var{n}th @sc{cdr} of @var{list}. In other -words, it skips past the first @var{n} links of @var{list} and returns -what follows. - -If @var{n} is zero or negative, @code{nthcdr} returns all of -@var{list}. If the length of @var{list} is @var{n} or less, -@code{nthcdr} returns @code{nil}. - -@example -@group -(nthcdr 1 '(1 2 3 4)) - @result{} (2 3 4) -@end group -@group -(nthcdr 10 '(1 2 3 4)) - @result{} nil -@end group -@group -(nthcdr -3 '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun last list &optional n -This function returns the last link of @var{list}. The @code{car} of -this link is the list's last element. If @var{list} is null, -@code{nil} is returned. If @var{n} is non-@code{nil}, the -@var{n}th-to-last link is returned instead, or the whole of @var{list} -if @var{n} is bigger than @var{list}'s length. -@end defun - -@defun safe-length list -@anchor{Definition of safe-length} -This function returns the length of @var{list}, with no risk of either -an error or an infinite loop. It generally returns the number of -distinct cons cells in the list. However, for circular lists, -the value is just an upper bound; it is often too large. - -If @var{list} is not @code{nil} or a cons cell, @code{safe-length} -returns 0. -@end defun - - The most common way to compute the length of a list, when you are not -worried that it may be circular, is with @code{length}. @xref{Sequence -Functions}. - -@defun caar cons-cell -This is the same as @code{(car (car @var{cons-cell}))}. -@end defun - -@defun cadr cons-cell -This is the same as @code{(car (cdr @var{cons-cell}))} -or @code{(nth 1 @var{cons-cell})}. -@end defun - -@defun cdar cons-cell -This is the same as @code{(cdr (car @var{cons-cell}))}. -@end defun - -@defun cddr cons-cell -This is the same as @code{(cdr (cdr @var{cons-cell}))} -or @code{(nthcdr 2 @var{cons-cell})}. -@end defun - -@defun butlast x &optional n -This function returns the list @var{x} with the last element, -or the last @var{n} elements, removed. If @var{n} is greater -than zero it makes a copy of the list so as not to damage the -original list. In general, @code{(append (butlast @var{x} @var{n}) -(last @var{x} @var{n}))} will return a list equal to @var{x}. -@end defun - -@defun nbutlast x &optional n -This is a version of @code{butlast} that works by destructively -modifying the @code{cdr} of the appropriate element, rather than -making a copy of the list. -@end defun - -@node Building Lists -@comment node-name, next, previous, up -@section Building Cons Cells and Lists -@cindex cons cells -@cindex building lists - - Many functions build lists, as lists reside at the very heart of Lisp. -@code{cons} is the fundamental list-building function; however, it is -interesting to note that @code{list} is used more times in the source -code for Emacs than @code{cons}. - -@defun cons object1 object2 -This function is the most basic function for building new list -structure. It creates a new cons cell, making @var{object1} the -@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new -cons cell. The arguments @var{object1} and @var{object2} may be any -Lisp objects, but most often @var{object2} is a list. - -@example -@group -(cons 1 '(2)) - @result{} (1 2) -@end group -@group -(cons 1 '()) - @result{} (1) -@end group -@group -(cons 1 2) - @result{} (1 . 2) -@end group -@end example - -@cindex consing -@code{cons} is often used to add a single element to the front of a -list. This is called @dfn{consing the element onto the list}. -@footnote{There is no strictly equivalent way to add an element to -the end of a list. You can use @code{(append @var{listname} (list -@var{newelt}))}, which creates a whole new list by copying @var{listname} -and adding @var{newelt} to its end. Or you can use @code{(nconc -@var{listname} (list @var{newelt}))}, which modifies @var{listname} -by following all the @sc{cdr}s and then replacing the terminating -@code{nil}. Compare this to adding an element to the beginning of a -list with @code{cons}, which neither copies nor modifies the list.} -For example: - -@example -(setq list (cons newelt list)) -@end example - -Note that there is no conflict between the variable named @code{list} -used in this example and the function named @code{list} described below; -any symbol can serve both purposes. -@end defun - -@defun list &rest objects -This function creates a list with @var{objects} as its elements. The -resulting list is always @code{nil}-terminated. If no @var{objects} -are given, the empty list is returned. - -@example -@group -(list 1 2 3 4 5) - @result{} (1 2 3 4 5) -@end group -@group -(list 1 2 '(3 4 5) 'foo) - @result{} (1 2 (3 4 5) foo) -@end group -@group -(list) - @result{} nil -@end group -@end example -@end defun - -@defun make-list length object -This function creates a list of @var{length} elements, in which each -element is @var{object}. Compare @code{make-list} with -@code{make-string} (@pxref{Creating Strings}). - -@example -@group -(make-list 3 'pigs) - @result{} (pigs pigs pigs) -@end group -@group -(make-list 0 'pigs) - @result{} nil -@end group -@group -(setq l (make-list 3 '(a b)) - @result{} ((a b) (a b) (a b)) -(eq (car l) (cadr l)) - @result{} t -@end group -@end example -@end defun - -@defun append &rest sequences -@cindex copying lists -This function returns a list containing all the elements of -@var{sequences}. The @var{sequences} may be lists, vectors, -bool-vectors, or strings, but the last one should usually be a list. -All arguments except the last one are copied, so none of the arguments -is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join -lists with no copying.) - -More generally, the final argument to @code{append} may be any Lisp -object. The final argument is not copied or converted; it becomes the -@sc{cdr} of the last cons cell in the new list. If the final argument -is itself a list, then its elements become in effect elements of the -result list. If the final element is not a list, the result is a -dotted list since its final @sc{cdr} is not @code{nil} as required -in a true list. -@end defun - - Here is an example of using @code{append}: - -@example -@group -(setq trees '(pine oak)) - @result{} (pine oak) -(setq more-trees (append '(maple birch) trees)) - @result{} (maple birch pine oak) -@end group - -@group -trees - @result{} (pine oak) -more-trees - @result{} (maple birch pine oak) -@end group -@group -(eq trees (cdr (cdr more-trees))) - @result{} t -@end group -@end example - - You can see how @code{append} works by looking at a box diagram. The -variable @code{trees} is set to the list @code{(pine oak)} and then the -variable @code{more-trees} is set to the list @code{(maple birch pine -oak)}. However, the variable @code{trees} continues to refer to the -original list: - -@smallexample -@group -more-trees trees -| | -| --- --- --- --- -> --- --- --- --- - --> | | |--> | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- --- --- - | | | | - | | | | - --> maple -->birch --> pine --> oak -@end group -@end smallexample - - An empty sequence contributes nothing to the value returned by -@code{append}. As a consequence of this, a final @code{nil} argument -forces a copy of the previous argument: - -@example -@group -trees - @result{} (pine oak) -@end group -@group -(setq wood (append trees nil)) - @result{} (pine oak) -@end group -@group -wood - @result{} (pine oak) -@end group -@group -(eq wood trees) - @result{} nil -@end group -@end example - -@noindent -This once was the usual way to copy a list, before the function -@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. - - Here we show the use of vectors and strings as arguments to @code{append}: - -@example -@group -(append [a b] "cd" nil) - @result{} (a b 99 100) -@end group -@end example - - With the help of @code{apply} (@pxref{Calling Functions}), we can append -all the lists in a list of lists: - -@example -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - - If no @var{sequences} are given, @code{nil} is returned: - -@example -@group -(append) - @result{} nil -@end group -@end example - - Here are some examples where the final argument is not a list: - -@example -(append '(x y) 'z) - @result{} (x y . z) -(append '(x y) [z]) - @result{} (x y . [z]) -@end example - -@noindent -The second example shows that when the final argument is a sequence but -not a list, the sequence's elements do not become elements of the -resulting list. Instead, the sequence becomes the final @sc{cdr}, like -any other non-list final argument. - -@defun reverse list -This function creates a new list whose elements are the elements of -@var{list}, but in reverse order. The original argument @var{list} is -@emph{not} altered. - -@example -@group -(setq x '(1 2 3 4)) - @result{} (1 2 3 4) -@end group -@group -(reverse x) - @result{} (4 3 2 1) -x - @result{} (1 2 3 4) -@end group -@end example -@end defun - -@defun copy-tree tree &optional vecp -This function returns a copy of the tree @code{tree}. If @var{tree} is a -cons cell, this makes a new cons cell with the same @sc{car} and -@sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the -same way. - -Normally, when @var{tree} is anything other than a cons cell, -@code{copy-tree} simply returns @var{tree}. However, if @var{vecp} is -non-@code{nil}, it copies vectors too (and operates recursively on -their elements). -@end defun - -@defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and -incrementing by @var{separation}, and ending at or just before -@var{to}. @var{separation} can be positive or negative and defaults -to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, -the value is the one-element list @code{(@var{from})}. If @var{to} is -less than @var{from} with a positive @var{separation}, or greater than -@var{from} with a negative @var{separation}, the value is @code{nil} -because those arguments specify an empty sequence. - -If @var{separation} is 0 and @var{to} is neither @code{nil} nor -numerically equal to @var{from}, @code{number-sequence} signals an -error, since those arguments specify an infinite sequence. - -All arguments can be integers or floating point numbers. However, -floating point arguments can be tricky, because floating point -arithmetic is inexact. For instance, depending on the machine, it may -quite well happen that @code{(number-sequence 0.4 0.6 0.2)} returns -the one element list @code{(0.4)}, whereas -@code{(number-sequence 0.4 0.8 0.2)} returns a list with three -elements. The @var{n}th element of the list is computed by the exact -formula @code{(+ @var{from} (* @var{n} @var{separation}))}. Thus, if -one wants to make sure that @var{to} is included in the list, one can -pass an expression of this exact type for @var{to}. Alternatively, -one can replace @var{to} with a slightly larger value (or a slightly -more negative value if @var{separation} is negative). - -Some examples: - -@example -(number-sequence 4 9) - @result{} (4 5 6 7 8 9) -(number-sequence 9 4 -1) - @result{} (9 8 7 6 5 4) -(number-sequence 9 4 -2) - @result{} (9 7 5) -(number-sequence 8) - @result{} (8) -(number-sequence 8 5) - @result{} nil -(number-sequence 5 8 -1) - @result{} nil -(number-sequence 1.5 6 2) - @result{} (1.5 3.5 5.5) -@end example -@end defun - -@node List Variables -@section Modifying List Variables - - These functions, and one macro, provide convenient ways -to modify a list which is stored in a variable. - -@defmac push newelt listname -This macro provides an alternative way to write -@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. - -@example -(setq l '(a b)) - @result{} (a b) -(push 'c l) - @result{} (c a b) -l - @result{} (c a b) -@end example -@end defmac - - Two functions modify lists that are the values of variables. - -@defun add-to-list symbol element &optional append compare-fn -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -@code{add-to-list} uses @var{compare-fn} to compare @var{element} -against existing list members; if @var{compare-fn} is @code{nil}, it -uses @code{equal}. - -Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is -non-@code{nil}, it is added at the end. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. -@end defun - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@defun add-to-ordered-list symbol element &optional order -This function sets the variable @var{symbol} by inserting -@var{element} into the old value, which must be a list, at the -position specified by @var{order}. If @var{element} is already a -member of the list, its position in the list is adjusted according -to @var{order}. Membership is tested using @code{eq}. -This function returns the resulting list, whether updated or not. - -The @var{order} is typically a number (integer or float), and the -elements of the list are sorted in non-decreasing numerical order. - -@var{order} may also be omitted or @code{nil}. Then the numeric order -of @var{element} stays unchanged if it already has one; otherwise, -@var{element} has no numeric order. Elements without a numeric list -order are placed at the end of the list, in no particular order. - -Any other value for @var{order} removes the numeric order of @var{element} -if it already has one; otherwise, it is equivalent to @code{nil}. - -The argument @var{symbol} is not implicitly quoted; -@code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if that is what -you want. - -The ordering information is stored in a hash table on @var{symbol}'s -@code{list-order} property. -@end defun - -Here's a scenario showing how to use @code{add-to-ordered-list}: - -@example -(setq foo '()) - @result{} nil - -(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} - @result{} (a) - -(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} - @result{} (a c) - -(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} - @result{} (a b c) - -(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} - @result{} (a c b) - -(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} - @result{} (a c b d) - -(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. - @result{} (a c b e d) - -foo ;; @r{@code{foo} was changed.} - @result{} (a c b e d) -@end example - -@node Modifying Lists -@section Modifying Existing List Structure -@cindex destructive list operations - - You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the -primitives @code{setcar} and @code{setcdr}. We call these ``destructive'' -operations because they change existing list structure. - -@cindex CL note---@code{rplaca} vs @code{setcar} -@quotation -@findex rplaca -@findex rplacd -@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and -@code{rplacd} to alter list structure; they change structure the same -way as @code{setcar} and @code{setcdr}, but the Common Lisp functions -return the cons cell while @code{setcar} and @code{setcdr} return the -new @sc{car} or @sc{cdr}. -@end quotation - -@menu -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. -@end menu - -@node Setcar -@subsection Altering List Elements with @code{setcar} - - Changing the @sc{car} of a cons cell is done with @code{setcar}. When -used on a list, @code{setcar} replaces one element of a list with a -different element. - -@defun setcar cons object -This function stores @var{object} as the new @sc{car} of @var{cons}, -replacing its previous @sc{car}. In other words, it changes the -@sc{car} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. For example: - -@example -@group -(setq x '(1 2)) - @result{} (1 2) -@end group -@group -(setcar x 4) - @result{} 4 -@end group -@group -x - @result{} (4 2) -@end group -@end example -@end defun - - When a cons cell is part of the shared structure of several lists, -storing a new @sc{car} into the cons changes one element of each of -these lists. Here is an example: - -@example -@group -;; @r{Create two lists that are partly shared.} -(setq x1 '(a b c)) - @result{} (a b c) -(setq x2 (cons 'z (cdr x1))) - @result{} (z b c) -@end group - -@group -;; @r{Replace the @sc{car} of a shared link.} -(setcar (cdr x1) 'foo) - @result{} foo -x1 ; @r{Both lists are changed.} - @result{} (a foo c) -x2 - @result{} (z foo c) -@end group - -@group -;; @r{Replace the @sc{car} of a link that is not shared.} -(setcar x1 'baz) - @result{} baz -x1 ; @r{Only one list is changed.} - @result{} (baz foo c) -x2 - @result{} (z foo c) -@end group -@end example - - Here is a graphical depiction of the shared structure of the two lists -in the variables @code{x1} and @code{x2}, showing why replacing @code{b} -changes them both: - -@example -@group - --- --- --- --- --- --- -x1---> | | |----> | | |--> | | |--> nil - --- --- --- --- --- --- - | --> | | - | | | | - --> a | --> b --> c - | - --- --- | -x2--> | | |-- - --- --- - | - | - --> z -@end group -@end example - - Here is an alternative form of box diagram, showing the same relationship: - -@example -@group -x1: - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o------->| b | o------->| c | nil | -| | | -->| | | | | | - -------------- | -------------- -------------- - | -x2: | - -------------- | -| car | cdr | | -| z | o---- -| | | - -------------- -@end group -@end example - -@node Setcdr -@subsection Altering the CDR of a List - - The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: - -@defun setcdr cons object -This function stores @var{object} as the new @sc{cdr} of @var{cons}, -replacing its previous @sc{cdr}. In other words, it changes the -@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the -value @var{object}. -@end defun - - Here is an example of replacing the @sc{cdr} of a list with a -different list. All but the first element of the list are removed in -favor of a different sequence of elements. The first element is -unchanged, because it resides in the @sc{car} of the list, and is not -reached via the @sc{cdr}. - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(setcdr x '(4)) - @result{} (4) -@end group -@group -x - @result{} (1 4) -@end group -@end example - - You can delete elements from the middle of a list by altering the -@sc{cdr}s of the cons cells in the list. For example, here we delete -the second element, @code{b}, from the list @code{(a b c)}, by changing -the @sc{cdr} of the first cons cell: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cdr (cdr x1))) - @result{} (c) -x1 - @result{} (a c) -@end group -@end example - - Here is the result in box notation: - -@smallexample -@group - -------------------- - | | - -------------- | -------------- | -------------- -| car | cdr | | | car | cdr | -->| car | cdr | -| a | o----- | b | o-------->| c | nil | -| | | | | | | | | - -------------- -------------- -------------- -@end group -@end smallexample - -@noindent -The second cons cell, which previously held the element @code{b}, still -exists and its @sc{car} is still @code{b}, but it no longer forms part -of this list. - - It is equally easy to insert a new element by changing @sc{cdr}s: - -@example -@group -(setq x1 '(a b c)) - @result{} (a b c) -(setcdr x1 (cons 'd (cdr x1))) - @result{} (d b c) -x1 - @result{} (a d b c) -@end group -@end example - - Here is this result in box notation: - -@smallexample -@group - -------------- ------------- ------------- -| car | cdr | | car | cdr | | car | cdr | -| a | o | -->| b | o------->| c | nil | -| | | | | | | | | | | - --------- | -- | ------------- ------------- - | | - ----- -------- - | | - | --------------- | - | | car | cdr | | - -->| d | o------ - | | | - --------------- -@end group -@end smallexample - -@node Rearrangement -@subsection Functions that Rearrange Lists -@cindex rearrangement of lists -@cindex modification of lists - - Here are some functions that rearrange lists ``destructively'' by -modifying the @sc{cdr}s of their component cons cells. We call these -functions ``destructive'' because they chew up the original lists passed -to them as arguments, relinking their cons cells to form a new list that -is the returned value. - -@ifnottex - See @code{delq}, in @ref{Sets And Lists}, for another function -that modifies cons cells. -@end ifnottex -@iftex - The function @code{delq} in the following section is another example -of destructive list manipulation. -@end iftex - -@defun nconc &rest lists -@cindex concatenating lists -@cindex joining lists -This function returns a list containing all the elements of @var{lists}. -Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are -@emph{not} copied. Instead, the last @sc{cdr} of each of the -@var{lists} is changed to refer to the following list. The last of the -@var{lists} is not altered. For example: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x '(4 5)) - @result{} (1 2 3 4 5) -@end group -@group -x - @result{} (1 2 3 4 5) -@end group -@end example - - Since the last argument of @code{nconc} is not itself modified, it is -reasonable to use a constant list, such as @code{'(4 5)}, as in the -above example. For the same reason, the last argument need not be a -list: - -@example -@group -(setq x '(1 2 3)) - @result{} (1 2 3) -@end group -@group -(nconc x 'z) - @result{} (1 2 3 . z) -@end group -@group -x - @result{} (1 2 3 . z) -@end group -@end example - -However, the other arguments (all but the last) must be lists. - -A common pitfall is to use a quoted constant list as a non-last -argument to @code{nconc}. If you do this, your program will change -each time you run it! Here is what happens: - -@smallexample -@group -(defun add-foo (x) ; @r{We want this function to add} - (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) -@end group - -@group -(setq xx (add-foo '(1 2))) ; @r{It seems to work.} - @result{} (foo 1 2) -@end group -@group -(setq xy (add-foo '(3 4))) ; @r{What happened?} - @result{} (foo 1 2 3 4) -@end group -@group -(eq xx xy) - @result{} t -@end group - -@group -(symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) -@end group -@end smallexample -@end defun - -@defun nreverse list -@cindex reversing a list - This function reverses the order of the elements of @var{list}. -Unlike @code{reverse}, @code{nreverse} alters its argument by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -used to be the last one in @var{list} becomes the first cons cell of the -value. - - For example: - -@example -@group -(setq x '(a b c)) - @result{} (a b c) -@end group -@group -x - @result{} (a b c) -(nreverse x) - @result{} (c b a) -@end group -@group -;; @r{The cons cell that was first is now last.} -x - @result{} (a) -@end group -@end example - - To avoid confusion, we usually store the result of @code{nreverse} -back in the same variable which held the original list: - -@example -(setq x (nreverse x)) -@end example - - Here is the @code{nreverse} of our favorite example, @code{(a b c)}, -presented graphically: - -@smallexample -@group -@r{Original list head:} @r{Reversed list:} - ------------- ------------- ------------ -| car | cdr | | car | cdr | | car | cdr | -| a | nil |<-- | b | o |<-- | c | o | -| | | | | | | | | | | | | - ------------- | --------- | - | -------- | - - | | | | - ------------- ------------ -@end group -@end smallexample -@end defun - -@defun sort list predicate -@cindex stable sort -@cindex sorting lists -This function sorts @var{list} stably, though destructively, and -returns the sorted list. It compares elements using @var{predicate}. A -stable sort is one in which elements with equal sort keys maintain their -relative order before and after the sort. Stability is important when -successive sorts are used to order elements according to different -criteria. - -The argument @var{predicate} must be a function that accepts two -arguments. It is called with two elements of @var{list}. To get an -increasing order sort, the @var{predicate} should return non-@code{nil} if the -first element is ``less than'' the second, or @code{nil} if not. - -The comparison function @var{predicate} must give reliable results for -any given pair of arguments, at least within a single call to -@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is -less than @var{b}, @var{b} must not be less than @var{a}. It must be -@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b} -is less than @var{c}, then @var{a} must be less than @var{c}. If you -use a comparison function which does not meet these requirements, the -result of @code{sort} is unpredictable. - -The destructive aspect of @code{sort} is that it rearranges the cons -cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort -function would create new cons cells to store the elements in their -sorted order. If you wish to make a sorted copy without destroying the -original, copy it first with @code{copy-sequence} and then sort. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; -the cons cell that originally contained the element @code{a} in -@var{list} still has @code{a} in its @sc{car} after sorting, but it now -appears in a different position in the list due to the change of -@sc{cdr}s. For example: - -@example -@group -(setq nums '(1 3 2 6 5 4 0)) - @result{} (1 3 2 6 5 4 0) -@end group -@group -(sort nums '<) - @result{} (0 1 2 3 4 5 6) -@end group -@group -nums - @result{} (1 2 3 4 5 6) -@end group -@end example - -@noindent -@strong{Warning}: Note that the list in @code{nums} no longer contains -0; this is the same cons cell that it was before, but it is no longer -the first one in the list. Don't assume a variable that formerly held -the argument now holds the entire sorted list! Instead, save the result -of @code{sort} and use that. Most often we store the result back into -the variable that held the original list: - -@example -(setq nums (sort nums '<)) -@end example - -@xref{Sorting}, for more functions that perform sorting. -See @code{documentation} in @ref{Accessing Documentation}, for a -useful example of @code{sort}. -@end defun - -@node Sets And Lists -@section Using Lists as Sets -@cindex lists as sets -@cindex sets - - A list can represent an unordered mathematical set---simply consider a -value an element of a set if it appears in the list, and ignore the -order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). You can remove -@code{equal} duplicates using @code{delete-dups}. Other useful -functions for sets include @code{memq} and @code{delq}, and their -@code{equal} versions, @code{member} and @code{delete}. - -@cindex CL note---lack @code{union}, @code{intersection} -@quotation -@b{Common Lisp note:} Common Lisp has functions @code{union} (which -avoids duplicate elements) and @code{intersection} for set operations, -but GNU Emacs Lisp does not have them. You can write them in Lisp if -you wish. -@end quotation - -@defun memq object list -@cindex membership in a list -This function tests to see whether @var{object} is a member of -@var{list}. If it is, @code{memq} returns a list starting with the -first occurrence of @var{object}. Otherwise, it returns @code{nil}. -The letter @samp{q} in @code{memq} says that it uses @code{eq} to -compare @var{object} against the elements of the list. For example: - -@example -@group -(memq 'b '(a b c b a)) - @result{} (b c b a) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -@defun delq object list -@cindex deleting list elements -This function destructively removes all elements @code{eq} to -@var{object} from @var{list}. The letter @samp{q} in @code{delq} says -that it uses @code{eq} to compare @var{object} against the elements of -the list, like @code{memq} and @code{remq}. -@end defun - -When @code{delq} deletes elements from the front of the list, it does so -simply by advancing down the list and returning a sublist that starts -after those elements: - -@example -@group -(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) -@end group -@end example - -When an element to be deleted appears in the middle of the list, -removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). - -@example -@group -(setq sample-list '(a b c (4))) - @result{} (a b c (4)) -@end group -@group -(delq 'a sample-list) - @result{} (b c (4)) -@end group -@group -sample-list - @result{} (a b c (4)) -@end group -@group -(delq 'c sample-list) - @result{} (a b (4)) -@end group -@group -sample-list - @result{} (a b (4)) -@end group -@end example - -Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to -splice out the third element, but @code{(delq 'a sample-list)} does not -splice anything---it just returns a shorter list. Don't assume that a -variable which formerly held the argument @var{list} now has fewer -elements, or that it still holds the original list! Instead, save the -result of @code{delq} and use that. Most often we store the result back -into the variable that held the original list: - -@example -(setq flowers (delq 'rose flowers)) -@end example - -In the following example, the @code{(4)} that @code{delq} attempts to match -and the @code{(4)} in the @code{sample-list} are not @code{eq}: - -@example -@group -(delq '(4) sample-list) - @result{} (a c (4)) -@end group - -If you want to delete elements that are @code{equal} to a given value, -use @code{delete} (see below). -@end example - -@defun remq object list -This function returns a copy of @var{list}, with all elements removed -which are @code{eq} to @var{object}. The letter @samp{q} in @code{remq} -says that it uses @code{eq} to compare @var{object} against the elements -of @code{list}. - -@example -@group -(setq sample-list '(a b c a b c)) - @result{} (a b c a b c) -@end group -@group -(remq 'a sample-list) - @result{} (b c b c) -@end group -@group -sample-list - @result{} (a b c a b c) -@end group -@end example -@end defun - -@defun memql object list -The function @code{memql} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{eql}, -so floating point elements are compared by value. -If @var{object} is a member, @code{memql} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(memql 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are @code{eql}.} - @result{} (1.2 1.3) -@end group -@group -(memq 1.2 '(1.1 1.2 1.3)) ; @r{@code{1.2} and @code{1.2} are not @code{eq}.} - @result{} nil -@end group -@end example -@end defun - -The following three functions are like @code{memq}, @code{delq} and -@code{remq}, but use @code{equal} rather than @code{eq} to compare -elements. @xref{Equality Predicates}. - -@defun member object list -The function @code{member} tests to see whether @var{object} is a member -of @var{list}, comparing members with @var{object} using @code{equal}. -If @var{object} is a member, @code{member} returns a list starting with -its first occurrence in @var{list}. Otherwise, it returns @code{nil}. - -Compare this with @code{memq}: - -@example -@group -(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} - @result{} ((2)) -@end group -@group -(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} - @result{} nil -@end group -@group -;; @r{Two strings with the same contents are @code{equal}.} -(member "foo" '("foo" "bar")) - @result{} ("foo" "bar") -@end group -@end example -@end defun - -@defun delete object sequence -If @code{sequence} is a list, this function destructively removes all -elements @code{equal} to @var{object} from @var{sequence}. For lists, -@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it -uses @code{equal} to compare elements with @var{object}, like -@code{member}; when it finds an element that matches, it cuts the -element out just as @code{delq} would. - -If @code{sequence} is a vector or string, @code{delete} returns a copy -of @code{sequence} with all elements @code{equal} to @code{object} -removed. - -For example: - -@example -@group -(setq l '((2) (1) (2))) -(delete '(2) l) - @result{} ((1)) -l - @result{} ((2) (1)) -;; @r{If you want to change @code{l} reliably,} -;; @r{write @code{(setq l (delete elt l))}.} -@end group -@group -(setq l '((2) (1) (2))) -(delete '(1) l) - @result{} ((2) (2)) -l - @result{} ((2) (2)) -;; @r{In this case, it makes no difference whether you set @code{l},} -;; @r{but you should do so for the sake of the other case.} -@end group -@group -(delete '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@defun remove object sequence -This function is the non-destructive counterpart of @code{delete}. It -returns a copy of @code{sequence}, a list, vector, or string, with -elements @code{equal} to @code{object} removed. For example: - -@example -@group -(remove '(2) '((2) (1) (2))) - @result{} ((1)) -@end group -@group -(remove '(2) [(2) (1) (2)]) - @result{} [(1)] -@end group -@end example -@end defun - -@quotation -@b{Common Lisp note:} The functions @code{member}, @code{delete} and -@code{remove} in GNU Emacs Lisp are derived from Maclisp, not Common -Lisp. The Common Lisp versions do not use @code{equal} to compare -elements. -@end quotation - -@defun member-ignore-case object list -This function is like @code{member}, except that @var{object} should -be a string and that it ignores differences in letter-case and text -representation: upper-case and lower-case letters are treated as -equal, and unibyte strings are converted to multibyte prior to -comparison. -@end defun - -@defun delete-dups list -This function destructively removes all @code{equal} duplicates from -@var{list}, stores the result in @var{list} and returns it. Of -several @code{equal} occurrences of an element in @var{list}, -@code{delete-dups} keeps the first one. -@end defun - - See also the function @code{add-to-list}, in @ref{List Variables}, -for a way to add an element to a list stored in a variable and used as a -set. - -@node Association Lists -@section Association Lists -@cindex association list -@cindex alist - - An @dfn{association list}, or @dfn{alist} for short, records a mapping -from keys to values. It is a list of cons cells called -@dfn{associations}: the @sc{car} of each cons cell is the @dfn{key}, and the -@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' -is not related to the term ``key sequence''; it means a value used to -look up an item in a table. In this case, the table is the alist, and -the alist associations are the items.} - - Here is an example of an alist. The key @code{pine} is associated with -the value @code{cones}; the key @code{oak} is associated with -@code{acorns}; and the key @code{maple} is associated with @code{seeds}. - -@example -@group -((pine . cones) - (oak . acorns) - (maple . seeds)) -@end group -@end example - - Both the values and the keys in an alist may be any Lisp objects. -For example, in the following alist, the symbol @code{a} is -associated with the number @code{1}, and the string @code{"b"} is -associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of -the alist element: - -@example -((a . 1) ("b" 2 3)) -@end example - - Sometimes it is better to design an alist to store the associated -value in the @sc{car} of the @sc{cdr} of the element. Here is an -example of such an alist: - -@example -((rose red) (lily white) (buttercup yellow)) -@end example - -@noindent -Here we regard @code{red} as the value associated with @code{rose}. One -advantage of this kind of alist is that you can store other related -information---even a list of other items---in the @sc{cdr} of the -@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see -below) to find the element containing a given value. When neither of -these considerations is important, the choice is a matter of taste, as -long as you are consistent about it for any given alist. - - The same alist shown above could be regarded as having the -associated value in the @sc{cdr} of the element; the value associated -with @code{rose} would be the list @code{(red)}. - - Association lists are often used to record information that you might -otherwise keep on a stack, since new associations may be added easily to -the front of the list. When searching an association list for an -association with a given key, the first one found is returned, if there -is more than one. - - In Emacs Lisp, it is @emph{not} an error if an element of an -association list is not a cons cell. The alist search functions simply -ignore such elements. Many other versions of Lisp signal errors in such -cases. - - Note that property lists are similar to association lists in several -respects. A property list behaves like an association list in which -each key can occur only once. @xref{Property Lists}, for a comparison -of property lists and association lists. - -@defun assoc key alist -This function returns the first association for @var{key} in -@var{alist}, comparing @var{key} against the alist elements using -@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} @code{equal} to @var{key}. -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assoc 'oak trees) - @result{} (oak . acorns) -(cdr (assoc 'oak trees)) - @result{} acorns -(assoc 'birch trees) - @result{} nil -@end smallexample - -Here is another example, in which the keys and values are not symbols: - -@smallexample -(setq needles-per-cluster - '((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine"))) - -(cdr (assoc 3 needles-per-cluster)) - @result{} ("Pitch Pine") -(cdr (assoc 2 needles-per-cluster)) - @result{} ("Austrian Pine" "Red Pine") -@end smallexample -@end defun - - The function @code{assoc-string} is much like @code{assoc} except -that it ignores certain differences between strings. @xref{Text -Comparison}. - -@defun rassoc value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{equal} to @var{value}. - -@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc},'' finding the key for a given value. -@end defun - -@defun assq key alist -This function is like @code{assoc} in that it returns the first -association for @var{key} in @var{alist}, but it makes the comparison -using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} -if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. -This function is used more often than @code{assoc}, since @code{eq} is -faster than @code{equal} and most alists use symbols as keys. -@xref{Equality Predicates}. - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - @result{} ((pine . cones) (oak . acorns) (maple . seeds)) -(assq 'pine trees) - @result{} (pine . cones) -@end smallexample - -On the other hand, @code{assq} is not usually useful in alists where the -keys may not be symbols: - -@smallexample -(setq leaves - '(("simple leaves" . oak) - ("compound leaves" . horsechestnut))) - -(assq "simple leaves" leaves) - @result{} nil -(assoc "simple leaves" leaves) - @result{} ("simple leaves" . oak) -@end smallexample -@end defun - -@defun rassq value alist -This function returns the first association with value @var{value} in -@var{alist}. It returns @code{nil} if no association in @var{alist} has -a @sc{cdr} @code{eq} to @var{value}. - -@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of -each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq},'' finding the key for a given value. - -For example: - -@smallexample -(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) - -(rassq 'acorns trees) - @result{} (oak . acorns) -(rassq 'spores trees) - @result{} nil -@end smallexample - -@code{rassq} cannot search for a value stored in the @sc{car} -of the @sc{cdr} of an element: - -@smallexample -(setq colors '((rose red) (lily white) (buttercup yellow))) - -(rassq 'white colors) - @result{} nil -@end smallexample - -In this case, the @sc{cdr} of the association @code{(lily white)} is not -the symbol @code{white}, but rather the list @code{(white)}. This -becomes clearer if the association is written in dotted pair notation: - -@smallexample -(lily white) @equiv{} (lily . (white)) -@end smallexample -@end defun - -@defun assoc-default key alist &optional test default -This function searches @var{alist} for a match for @var{key}. For each -element of @var{alist}, it compares the element (if it is an atom) or -the element's @sc{car} (if it is a cons) against @var{key}, by calling -@var{test} with two arguments: the element or its @sc{car}, and -@var{key}. The arguments are passed in that order so that you can get -useful results using @code{string-match} with an alist that contains -regular expressions (@pxref{Regexp Search}). If @var{test} is omitted -or @code{nil}, @code{equal} is used for comparison. - -If an alist element matches @var{key} by this criterion, -then @code{assoc-default} returns a value based on this element. -If the element is a cons, then the value is the element's @sc{cdr}. -Otherwise, the return value is @var{default}. - -If no alist element matches @var{key}, @code{assoc-default} returns -@code{nil}. -@end defun - -@defun copy-alist alist -@cindex copying alists -This function returns a two-level deep copy of @var{alist}: it creates a -new copy of each association, so that you can alter the associations of -the new alist without changing the old one. - -@smallexample -@group -(setq needles-per-cluster - '((2 . ("Austrian Pine" "Red Pine")) - (3 . ("Pitch Pine")) -@end group - (5 . ("White Pine")))) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(setq copy (copy-alist needles-per-cluster)) -@result{} -((2 "Austrian Pine" "Red Pine") - (3 "Pitch Pine") - (5 "White Pine")) - -(eq needles-per-cluster copy) - @result{} nil -(equal needles-per-cluster copy) - @result{} t -(eq (car needles-per-cluster) (car copy)) - @result{} nil -(cdr (car (cdr needles-per-cluster))) - @result{} ("Pitch Pine") -@group -(eq (cdr (car (cdr needles-per-cluster))) - (cdr (car (cdr copy)))) - @result{} t -@end group -@end smallexample - - This example shows how @code{copy-alist} makes it possible to change -the associations of one copy without affecting the other: - -@smallexample -@group -(setcdr (assq 3 copy) '("Martian Vacuum Pine")) -(cdr (assq 3 needles-per-cluster)) - @result{} ("Pitch Pine") -@end group -@end smallexample -@end defun - -@defun assq-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{eq} to @var{key}, much as if you used @code{delq} to delete -each such element one by one. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. For -correct results, use the return value of @code{assq-delete-all} rather -than looking at the saved value of @var{alist}. - -@example -(setq alist '((foo 1) (bar 2) (foo 3) (lose 4))) - @result{} ((foo 1) (bar 2) (foo 3) (lose 4)) -(assq-delete-all 'foo alist) - @result{} ((bar 2) (lose 4)) -alist - @result{} ((foo 1) (bar 2) (lose 4)) -@end example -@end defun - -@defun rassq-delete-all value alist -This function deletes from @var{alist} all the elements whose @sc{cdr} -is @code{eq} to @var{value}. It returns the shortened alist, and -often modifies the original list structure of @var{alist}. -@code{rassq-delete-all} is like @code{assq-delete-all} except that it -compares the @sc{cdr} of each @var{alist} association instead of the -@sc{car}. -@end defun - -@node Rings -@section Managing a Fixed-Size Ring of Objects - -@cindex ring data structure - This section describes functions for operating on rings. A -@dfn{ring} is a fixed-size data structure that supports insertion, -deletion, rotation, and modulo-indexed reference and traversal. - -@defun make-ring size -This returns a new ring capable of holding @var{size} objects. -@var{size} should be an integer. -@end defun - -@defun ring-p object -This returns @code{t} if @var{object} is a ring, @code{nil} otherwise. -@end defun - -@defun ring-size ring -This returns the maximum capacity of the @var{ring}. -@end defun - -@defun ring-length ring -This returns the number of objects that @var{ring} currently contains. -The value will never exceed that returned by @code{ring-size}. -@end defun - -@defun ring-elements ring -This returns a list of the objects in @var{ring}, in order, newest first. -@end defun - -@defun ring-copy ring -This returns a new ring which is a copy of @var{ring}. -The new ring contains the same (@code{eq}) objects as @var{ring}. -@end defun - -@defun ring-empty-p ring -This returns @code{t} if @var{ring} is empty, @code{nil} otherwise. -@end defun - - The newest element in the ring always has index 0. Higher indices -correspond to older elements. Indices are computed modulo the ring -length. Index @minus{}1 corresponds to the oldest element, @minus{}2 -to the next-oldest, and so forth. - -@defun ring-ref ring index -This returns the object in @var{ring} found at index @var{index}. -@var{index} may be negative or greater than the ring length. If -@var{ring} is empty, @code{ring-ref} signals an error. -@end defun - -@defun ring-insert ring object -This inserts @var{object} into @var{ring}, making it the newest -element, and returns @var{object}. - -If the ring is full, insertion removes the oldest element to -make room for the new element. -@end defun - -@defun ring-remove ring &optional index -Remove an object from @var{ring}, and return that object. The -argument @var{index} specifies which item to remove; if it is -@code{nil}, that means to remove the oldest item. If @var{ring} is -empty, @code{ring-remove} signals an error. -@end defun - -@defun ring-insert-at-beginning ring object -This inserts @var{object} into @var{ring}, treating it as the oldest -element. The return value is not significant. - -If the ring is full, this function removes the newest element to make -room for the inserted element. -@end defun - -@cindex fifo data structure - If you are careful not to exceed the ring size, you can -use the ring as a first-in-first-out queue. For example: - -@lisp -(let ((fifo (make-ring 5))) - (mapc (lambda (obj) (ring-insert fifo obj)) - '(0 one "two")) - (list (ring-remove fifo) t - (ring-remove fifo) t - (ring-remove fifo))) - @result{} (0 t one t "two") -@end lisp - -@ignore - arch-tag: 31fb8a4e-4aa8-4a74-a206-aa00451394d4 -@end ignore diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi deleted file mode 100644 index 403a7404edf..00000000000 --- a/doc/lispref/loading.texi +++ /dev/null @@ -1,988 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/loading -@node Loading, Byte Compilation, Customization, Top -@chapter Loading -@cindex loading -@cindex library -@cindex Lisp library - - Loading a file of Lisp code means bringing its contents into the Lisp -environment in the form of Lisp objects. Emacs finds and opens the -file, reads the text, evaluates each form, and then closes the file. - - The load functions evaluate all the expressions in a file just -as the @code{eval-buffer} function evaluates all the -expressions in a buffer. The difference is that the load functions -read and evaluate the text in the file as found on disk, not the text -in an Emacs buffer. - -@cindex top-level form - The loaded file must contain Lisp expressions, either as source code -or as byte-compiled code. Each form in the file is called a -@dfn{top-level form}. There is no special format for the forms in a -loadable file; any form in a file may equally well be typed directly -into a buffer and evaluated there. (Indeed, most code is tested this -way.) Most often, the forms are function definitions and variable -definitions. - - A file containing Lisp code is often called a @dfn{library}. Thus, -the ``Rmail library'' is a file containing code for Rmail mode. -Similarly, a ``Lisp library directory'' is a directory of files -containing Lisp code. - -@menu -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. -@end menu - -@node How Programs Do Loading -@section How Programs Do Loading - - Emacs Lisp has several interfaces for loading. For example, -@code{autoload} creates a placeholder object for a function defined in a -file; trying to call the autoloading function loads the file to get the -function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Named Features}). Ultimately, -all these facilities call the @code{load} function to do the work. - -@defun load filename &optional missing-ok nomessage nosuffix must-suffix -This function finds and opens a file of Lisp code, evaluates all the -forms in it, and closes the file. - -To find the file, @code{load} first looks for a file named -@file{@var{filename}.elc}, that is, for a file whose name is -@var{filename} with the extension @samp{.elc} appended. If such a -file exists, it is loaded. If there is no file by that name, then -@code{load} looks for a file named @file{@var{filename}.el}. If that -file exists, it is loaded. Finally, if neither of those names is -found, @code{load} looks for a file named @var{filename} with nothing -appended, and loads it if it exists. (The @code{load} function is not -clever about looking at @var{filename}. In the perverse case of a -file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will -indeed find it.) - -If Auto Compression mode is enabled, as it is by default, then if -@code{load} can not find a file, it searches for a compressed version -of the file before trying other file names. It decompresses and loads -it if it exists. It looks for compressed versions by appending each -of the suffixes in @code{jka-compr-load-suffixes} to the file name. -The value of this variable must be a list of strings. Its standard -value is @code{(".gz")}. - -If the optional argument @var{nosuffix} is non-@code{nil}, then -@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In -this case, you must specify the precise file name you want, except -that, if Auto Compression mode is enabled, @code{load} will still use -@code{jka-compr-load-suffixes} to find compressed versions. By -specifying the precise file name and using @code{t} for -@var{nosuffix}, you can prevent perverse file names such as -@file{foo.el.el} from being tried. - -If the optional argument @var{must-suffix} is non-@code{nil}, then -@code{load} insists that the file name used must end in either -@samp{.el} or @samp{.elc} (possibly extended with a compression -suffix), unless it contains an explicit directory name. - -If @var{filename} is a relative file name, such as @file{foo} or -@file{baz/foo.bar}, @code{load} searches for the file using the variable -@code{load-path}. It appends @var{filename} to each of the directories -listed in @code{load-path}, and loads the first file it finds whose name -matches. The current default directory is tried only if it is specified -in @code{load-path}, where @code{nil} stands for the default directory. -@code{load} tries all three possible suffixes in the first directory in -@code{load-path}, then all three suffixes in the second directory, and -so on. @xref{Library Search}. - -If you get a warning that @file{foo.elc} is older than @file{foo.el}, it -means you should consider recompiling @file{foo.el}. @xref{Byte -Compilation}. - -When loading a source file (not compiled), @code{load} performs -character set translation just as Emacs would do when visiting the file. -@xref{Coding Systems}. - -Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear -in the echo area during loading unless @var{nomessage} is -non-@code{nil}. - -@cindex load errors -Any unhandled errors while loading a file terminate loading. If the -load was done for the sake of @code{autoload}, any function definitions -made during the loading are undone. - -@kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file -@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then -@code{load} just returns @code{nil}. - -You can use the variable @code{load-read-function} to specify a function -for @code{load} to use instead of @code{read} for reading expressions. -See below. - -@code{load} returns @code{t} if the file loads successfully. -@end defun - -@deffn Command load-file filename -This command loads the file @var{filename}. If @var{filename} is a -relative file name, then the current default directory is assumed. -This command does not use @code{load-path}, and does not append -suffixes. However, it does look for compressed versions (if Auto -Compression Mode is enabled). Use this command if you wish to specify -precisely the file name to load. -@end deffn - -@deffn Command load-library library -This command loads the library named @var{library}. It is equivalent to -@code{load}, except in how it reads its argument interactively. -@end deffn - -@defvar load-in-progress -This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. -@end defvar - -@defvar load-read-function -@anchor{Definition of load-read-function} -@c do not allow page break at anchor; work around Texinfo deficiency. -This variable specifies an alternate expression-reading function for -@code{load} and @code{eval-region} to use instead of @code{read}. -The function should accept one argument, just as @code{read} does. - -Normally, the variable's value is @code{nil}, which means those -functions should use @code{read}. - -Instead of using this variable, it is cleaner to use another, newer -feature: to pass the function as the @var{read-function} argument to -@code{eval-region}. @xref{Definition of eval-region,, Eval}. -@end defvar - - For information about how @code{load} is used in building Emacs, see -@ref{Building Emacs}. - -@node Load Suffixes -@section Load Suffixes -We now describe some technical details about the exact suffixes that -@code{load} tries. - -@defvar load-suffixes -This is a list of suffixes indicating (compiled or source) Emacs Lisp -files. It should not include the empty string. @code{load} uses -these suffixes in order when it appends Lisp suffixes to the specified -file name. The standard value is @code{(".elc" ".el")} which produces -the behavior described in the previous section. -@end defvar - -@defvar load-file-rep-suffixes -This is a list of suffixes that indicate representations of the same -file. This list should normally start with the empty string. -When @code{load} searches for a file it appends the suffixes in this -list, in order, to the file name, before searching for another file. - -Enabling Auto Compression mode appends the suffixes in -@code{jka-compr-load-suffixes} to this list and disabling Auto -Compression mode removes them again. The standard value of -@code{load-file-rep-suffixes} if Auto Compression mode is disabled is -@code{("")}. Given that the standard value of -@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value -of @code{load-file-rep-suffixes} if Auto Compression mode is enabled -is @code{("" ".gz")}. -@end defvar - -@defun get-load-suffixes -This function returns the list of all suffixes that @code{load} should -try, in order, when its @var{must-suffix} argument is non-@code{nil}. -This takes both @code{load-suffixes} and @code{load-file-rep-suffixes} -into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes} -and @code{load-file-rep-suffixes} all have their standard values, this -function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto -Compression mode is enabled and @code{(".elc" ".el")} if Auto -Compression mode is disabled. -@end defun - -To summarize, @code{load} normally first tries the suffixes in the -value of @code{(get-load-suffixes)} and then those in -@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil}, -it skips the former group, and if @var{must-suffix} is non-@code{nil}, -it skips the latter group. - -@node Library Search -@section Library Search -@cindex library search -@cindex find library - - When Emacs loads a Lisp library, it searches for the library -in a list of directories specified by the variable @code{load-path}. - -@defopt load-path -@cindex @code{EMACSLOADPATH} environment variable -The value of this variable is a list of directories to search when -loading files with @code{load}. Each element is a string (which must be -a directory name) or @code{nil} (which stands for the current working -directory). -@end defopt - - The value of @code{load-path} is initialized from the environment -variable @code{EMACSLOADPATH}, if that exists; otherwise its default -value is specified in @file{emacs/src/epaths.h} when Emacs is built. -Then the list is expanded by adding subdirectories of the directories -in the list. - - The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; -@samp{:} (or @samp{;}, according to the operating system) separates -directory names, and @samp{.} is used for the current default directory. -Here is an example of how to set your @code{EMACSLOADPATH} variable from -a @code{csh} @file{.login} file: - -@smallexample -setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp -@end smallexample - - Here is how to set it using @code{sh}: - -@smallexample -export EMACSLOADPATH -EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp -@end smallexample - - Here is an example of code you can place in your init file (@pxref{Init -File}) to add several directories to the front of your default -@code{load-path}: - -@smallexample -@group -(setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) -@end group -@end smallexample - -@c Wordy to rid us of an overfull hbox. --rjc 15mar92 -@noindent -In this example, the path searches the current working directory first, -followed then by the @file{/user/bil/emacs} directory, the -@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory, -which are then followed by the standard directories for Lisp code. - - Dumping Emacs uses a special value of @code{load-path}. If the value of -@code{load-path} at the end of dumping is unchanged (that is, still the -same special value), the dumped Emacs switches to the ordinary -@code{load-path} value when it starts up, as described above. But if -@code{load-path} has any other value at the end of dumping, that value -is used for execution of the dumped Emacs also. - - Therefore, if you want to change @code{load-path} temporarily for -loading a few libraries in @file{site-init.el} or @file{site-load.el}, -you should bind @code{load-path} locally with @code{let} around the -calls to @code{load}. - - The default value of @code{load-path}, when running an Emacs which has -been installed on the system, includes two special directories (and -their subdirectories as well): - -@smallexample -"/usr/local/share/emacs/@var{version}/site-lisp" -@end smallexample - -@noindent -and - -@smallexample -"/usr/local/share/emacs/site-lisp" -@end smallexample - -@noindent -The first one is for locally installed packages for a particular Emacs -version; the second is for locally installed packages meant for use with -all installed Emacs versions. - - There are several reasons why a Lisp package that works well in one -Emacs version can cause trouble in another. Sometimes packages need -updating for incompatible changes in Emacs; sometimes they depend on -undocumented internal Emacs data that can change without notice; -sometimes a newer Emacs version incorporates a version of the package, -and should be used only with that version. - - Emacs finds these directories' subdirectories and adds them to -@code{load-path} when it starts up. Both immediate subdirectories and -subdirectories multiple levels down are added to @code{load-path}. - - Not all subdirectories are included, though. Subdirectories whose -names do not start with a letter or digit are excluded. Subdirectories -named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which -contains a file named @file{.nosearch} is excluded. You can use these -methods to prevent certain subdirectories of the @file{site-lisp} -directories from being searched. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---then @code{load-path} -normally contains two additional directories. These are the @code{lisp} -and @code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - -@deffn Command locate-library library &optional nosuffix path interactive-call -This command finds the precise file name for library @var{library}. It -searches for the library in the same way @code{load} does, and the -argument @var{nosuffix} has the same meaning as in @code{load}: don't -add suffixes @samp{.elc} or @samp{.el} to the specified name -@var{library}. - -If the @var{path} is non-@code{nil}, that list of directories is used -instead of @code{load-path}. - -When @code{locate-library} is called from a program, it returns the file -name as a string. When the user runs @code{locate-library} -interactively, the argument @var{interactive-call} is @code{t}, and this -tells @code{locate-library} to display the file name in the echo area. -@end deffn - -@node Loading Non-ASCII -@section Loading Non-@acronym{ASCII} Characters - - When Emacs Lisp programs contain string constants with non-@acronym{ASCII} -characters, these can be represented within Emacs either as unibyte -strings or as multibyte strings (@pxref{Text Representations}). Which -representation is used depends on how the file is read into Emacs. If -it is read with decoding into multibyte representation, the text of the -Lisp program will be multibyte text, and its string constants will be -multibyte strings. If a file containing Latin-1 characters (for -example) is read without decoding, the text of the program will be -unibyte text, and its string constants will be unibyte strings. -@xref{Coding Systems}. - - To make the results more predictable, Emacs always performs decoding -into the multibyte representation when loading Lisp files, even if it -was started with the @samp{--unibyte} option. This means that string -constants with non-@acronym{ASCII} characters translate into multibyte -strings. The only exception is when a particular file specifies no -decoding. - - The reason Emacs is designed this way is so that Lisp programs give -predictable results, regardless of how Emacs was started. In addition, -this enables programs that depend on using multibyte text to work even -in a unibyte Emacs. Of course, such programs should be designed to -notice whether the user prefers unibyte or multibyte text, by checking -@code{default-enable-multibyte-characters}, and convert representations -appropriately. - - In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are -multibyte strings should not be noticeable, since inserting them in -unibyte buffers converts them to unibyte automatically. However, if -this does make a difference, you can force a particular Lisp file to be -interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a -comment on the file's first line. With that designator, the file will -unconditionally be interpreted as unibyte, even in an ordinary -multibyte Emacs session. This can matter when making keybindings to -non-@acronym{ASCII} characters written as @code{?v@var{literal}}. - -@node Autoload -@section Autoload -@cindex autoload - - The @dfn{autoload} facility allows you to make a function or macro -known in Lisp, but put off loading the file that defines it. The first -call to the function automatically reads the proper file to install the -real definition and other associated code, then runs the real definition -as if it had been loaded all along. - - There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the -source before the real definition. @code{autoload} is the low-level -primitive for autoloading; any Lisp program can call @code{autoload} at -any time. Magic comments are the most convenient way to make a function -autoload, for packages installed along with Emacs. These comments do -nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} -and arranges to execute them when Emacs is built. - -@defun autoload function filename &optional docstring interactive type -This function defines the function (or macro) named @var{function} so as -to load automatically from @var{filename}. The string @var{filename} -specifies the file to load to get the real definition of @var{function}. - -If @var{filename} does not contain either a directory name, or the -suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding -one of these suffixes, and it will not load from a file whose name is -just @var{filename} with no added suffix. (The variable -@code{load-suffixes} specifies the exact required suffixes.) - -The argument @var{docstring} is the documentation string for the -function. Specifying the documentation string in the call to -@code{autoload} makes it possible to look at the documentation without -loading the function's real definition. Normally, this should be -identical to the documentation string in the function definition -itself. If it isn't, the function definition's documentation string -takes effect when it is loaded. - -If @var{interactive} is non-@code{nil}, that says @var{function} can be -called interactively. This lets completion in @kbd{M-x} work without -loading @var{function}'s real definition. The complete interactive -specification is not given here; it's not needed unless the user -actually calls @var{function}, and when that happens, it's time to load -the real definition. - -You can autoload macros and keymaps as well as ordinary functions. -Specify @var{type} as @code{macro} if @var{function} is really a macro. -Specify @var{type} as @code{keymap} if @var{function} is really a -keymap. Various parts of Emacs need to know this information without -loading the real definition. - -An autoloaded keymap loads automatically during key lookup when a prefix -key's binding is the symbol @var{function}. Autoloading does not occur -for other kinds of access to the keymap. In particular, it does not -happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same -symbol @var{function}. - -@cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, @code{autoload} does nothing and returns @code{nil}. -If the function cell of @var{function} is void, or is already an autoload -object, then it is defined as an autoload object like this: - -@example -(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) -@end example - -For example, - -@example -@group -(symbol-function 'run-prolog) - @result{} (autoload "prolog" 169681 t nil) -@end group -@end example - -@noindent -In this case, @code{"prolog"} is the name of the file to load, 169681 -refers to the documentation string in the -@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}), -@code{t} means the function is interactive, and @code{nil} that it is -not a macro or a keymap. -@end defun - -@cindex autoload errors - The autoloaded file usually contains other definitions and may require -or provide one or more features. If the file is not completely loaded -(due to an error in the evaluation of its contents), any function -definitions or @code{provide} calls that occurred during the load are -undone. This is to ensure that the next attempt to call any function -autoloading from this file will try again to load the file. If not for -this, then some of the functions in the file might be defined by the -aborted load, but fail to work properly for the lack of certain -subroutines not loaded successfully because they come later in the file. - - If the autoloaded file fails to define the desired Lisp function or -macro, then an error is signaled with data @code{"Autoloading failed to -define function @var{function-name}"}. - -@findex update-file-autoloads -@findex update-directory-autoloads -@cindex magic autoload comment -@cindex autoload cookie -@anchor{autoload cookie} - A magic autoload comment (often called an @dfn{autoload cookie}) -consists of @samp{;;;###autoload}, on a line by itself, -just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} -writes a corresponding @code{autoload} call into @file{loaddefs.el}. -(The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the -above defaults, see below.) -Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x update-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. - - The same magic comment can copy any kind of form into -@file{loaddefs.el}. If the form following the magic comment is not a -function-defining form or a @code{defcustom} form, it is copied -verbatim. ``Function-defining forms'' include @code{define-skeleton}, -@code{define-derived-mode}, @code{define-generic-mode} and -@code{define-minor-mode} as well as @code{defun} and -@code{defmacro}. To save space, a @code{defcustom} form is converted to -a @code{defvar} in @file{loaddefs.el}, with some additional information -if it uses @code{:require}. - - You can also use a magic comment to execute a form at build time -@emph{without} executing it when the file itself is loaded. To do this, -write the form @emph{on the same line} as the magic comment. Since it -is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where -it is executed while building Emacs. - - The following example shows how @code{doctor} is prepared for -autoloading with a magic comment: - -@smallexample -;;;###autoload -(defun doctor () - "Switch to *doctor* buffer and start giving psychotherapy." - (interactive) - (switch-to-buffer "*doctor*") - (doctor-mode)) -@end smallexample - -@noindent -Here's what that produces in @file{loaddefs.el}: - -@smallexample -(autoload (quote doctor) "doctor" "\ -Switch to *doctor* buffer and start giving psychotherapy. - -\(fn)" t nil) -@end smallexample - -@noindent -@cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. - - If you write a function definition with an unusual macro that is not -one of the known and recognized function definition methods, use of an -ordinary magic autoload comment would copy the whole definition into -@code{loaddefs.el}. That is not desirable. You can put the desired -@code{autoload} call into @code{loaddefs.el} instead by writing this: - -@smallexample -;;;###autoload (autoload 'foo "myfile") -(mydefunmacro foo - ...) -@end smallexample - - You can use a non-default string as the autoload cookie and have the -corresponding autoload calls written into a file whose name is -different from the default @file{loaddefs.el}. Emacs provides two -variables to control this: - -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. -@end defvar - -@defvar generated-autoload-file -The value of this variable names an Emacs Lisp file where the autoload -calls should go. The default value is @file{loaddefs.el}, but you can -override that, e.g., in the ``Local Variables'' section of a -@file{.el} file (@pxref{File Local Variables}). The autoload file is -assumed to contain a trailer starting with a formfeed character. -@end defvar - -@node Repeated Loading -@section Repeated Loading -@cindex repeated loading - - You can load a given file more than once in an Emacs session. For -example, after you have rewritten and reinstalled a function definition -by editing it in a buffer, you may wish to return to the original -version; you can do this by reloading the file it came from. - - When you load or reload files, bear in mind that the @code{load} and -@code{load-library} functions automatically load a byte-compiled file -rather than a non-compiled file of similar name. If you rewrite a file -that you intend to save and reinstall, you need to byte-compile the new -version; otherwise Emacs will load the older, byte-compiled file instead -of your newer, non-compiled file! If that happens, the message -displayed when loading the file includes, @samp{(compiled; note, source is -newer)}, to remind you to recompile it. - - When writing the forms in a Lisp library file, keep in mind that the -file might be loaded more than once. For example, think about whether -each variable should be reinitialized when you reload the library; -@code{defvar} does not change the value if the variable is already -initialized. (@xref{Defining Variables}.) - - The simplest way to add an element to an alist is like this: - -@example -(push '(leif-mode " Leif") minor-mode-alist) -@end example - -@noindent -But this would add multiple elements if the library is reloaded. To -avoid the problem, use @code{add-to-list} (@pxref{List Variables}): - -@example -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end example - - Occasionally you will want to test explicitly whether a library has -already been loaded. If the library uses @code{provide} to provide a -named feature, you can use @code{featurep} earlier in the file to test -whether the @code{provide} call has been executed before (@pxref{Named -Features}). Alternatively, you could use something like this: - -@example -(defvar foo-was-loaded nil) - -(unless foo-was-loaded - @var{execute-first-time-only} - (setq foo-was-loaded t)) -@end example - -@noindent - -@node Named Features -@section Features -@cindex features -@cindex requiring features -@cindex providing features - - @code{provide} and @code{require} are an alternative to -@code{autoload} for loading files automatically. They work in terms of -named @dfn{features}. Autoloading is triggered by calling a specific -function, but a feature is loaded the first time another program asks -for it by name. - - A feature name is a symbol that stands for a collection of functions, -variables, etc. The file that defines them should @dfn{provide} the -feature. Another program that uses them may ensure they are defined by -@dfn{requiring} the feature. This loads the file of definitions if it -hasn't been loaded already. - -@cindex load error with require - To require the presence of a feature, call @code{require} with the -feature name as argument. @code{require} looks in the global variable -@code{features} to see whether the desired feature has been provided -already. If not, it loads the feature from the appropriate file. This -file should call @code{provide} at the top level to add the feature to -@code{features}; if it fails to do so, @code{require} signals an error. - - For example, in @file{emacs/lisp/prolog.el}, -the definition for @code{run-prolog} includes the following code: - -@smallexample -(defun run-prolog () - "Run an inferior Prolog process, with I/O via buffer *prolog*." - (interactive) - (require 'comint) - (switch-to-buffer (make-comint "prolog" prolog-program-name)) - (inferior-prolog-mode)) -@end smallexample - -@noindent -The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded. This ensures that @code{make-comint} is -defined. Features are normally named after the files that provide them, -so that @code{require} need not be given the file name. - -The @file{comint.el} file contains the following top-level expression: - -@smallexample -(provide 'comint) -@end smallexample - -@noindent -This adds @code{comint} to the global @code{features} list, so that -@code{(require 'comint)} will henceforth know that nothing needs to be -done. - -@cindex byte-compiling @code{require} - When @code{require} is used at top level in a file, it takes effect -when you byte-compile that file (@pxref{Byte Compilation}) as well as -when you load it. This is in case the required package contains macros -that the byte compiler must know about. It also avoids byte compiler -warnings for functions and variables defined in the file loaded with -@code{require}. - - Although top-level calls to @code{require} are evaluated during -byte compilation, @code{provide} calls are not. Therefore, you can -ensure that a file of definitions is loaded before it is byte-compiled -by including a @code{provide} followed by a @code{require} for the same -feature, as in the following example. - -@smallexample -@group -(provide 'my-feature) ; @r{Ignored by byte compiler,} - ; @r{evaluated by @code{load}.} -(require 'my-feature) ; @r{Evaluated by byte compiler.} -@end group -@end smallexample - -@noindent -The compiler ignores the @code{provide}, then processes the -@code{require} by loading the file in question. Loading the file does -execute the @code{provide} call, so the subsequent @code{require} call -does nothing when the file is loaded. - -@defun provide feature &optional subfeatures -This function announces that @var{feature} is now loaded, or being -loaded, into the current Emacs session. This means that the facilities -associated with @var{feature} are or will be available for other Lisp -programs. - -The direct effect of calling @code{provide} is if not already in -@var{features} then to add @var{feature} to the front of that list and -call any @code{eval-after-load} code waiting for it (@pxref{Hooks for -Loading}). The argument @var{feature} must be a symbol. -@code{provide} returns @var{feature}. - -If provided, @var{subfeatures} should be a list of symbols indicating -a set of specific subfeatures provided by this version of -@var{feature}. You can test the presence of a subfeature using -@code{featurep}. The idea of subfeatures is that you use them when a -package (which is one @var{feature}) is complex enough to make it -useful to give names to various parts or functionalities of the -package, which might or might not be loaded, or might or might not be -present in a given version. @xref{Network Feature Testing}, for -an example. - -@smallexample -features - @result{} (bar bish) - -(provide 'foo) - @result{} foo -features - @result{} (foo bar bish) -@end smallexample - -When a file is loaded to satisfy an autoload, and it stops due to an -error in the evaluation of its contents, any function definitions or -@code{provide} calls that occurred during the load are undone. -@xref{Autoload}. -@end defun - -@defun require feature &optional filename noerror -This function checks whether @var{feature} is present in the current -Emacs session (using @code{(featurep @var{feature})}; see below). The -argument @var{feature} must be a symbol. - -If the feature is not present, then @code{require} loads @var{filename} -with @code{load}. If @var{filename} is not supplied, then the name of -the symbol @var{feature} is used as the base file name to load. -However, in this case, @code{require} insists on finding @var{feature} -with an added @samp{.el} or @samp{.elc} suffix (possibly extended with -a compression suffix); a file whose name is just @var{feature} won't -be used. (The variable @code{load-suffixes} specifies the exact -required Lisp suffixes.) - -If @var{noerror} is non-@code{nil}, that suppresses errors from actual -loading of the file. In that case, @code{require} returns @code{nil} -if loading the file fails. Normally, @code{require} returns -@var{feature}. - -If loading the file succeeds but does not provide @var{feature}, -@code{require} signals an error, @samp{Required feature @var{feature} -was not provided}. -@end defun - -@defun featurep feature &optional subfeature -This function returns @code{t} if @var{feature} has been provided in -the current Emacs session (i.e.@:, if @var{feature} is a member of -@code{features}.) If @var{subfeature} is non-@code{nil}, then the -function returns @code{t} only if that subfeature is provided as well -(i.e.@: if @var{subfeature} is a member of the @code{subfeature} -property of the @var{feature} symbol.) -@end defun - -@defvar features -The value of this variable is a list of symbols that are the features -loaded in the current Emacs session. Each symbol was put in this list -with a call to @code{provide}. The order of the elements in the -@code{features} list is not significant. -@end defvar - -@node Where Defined -@section Which File Defined a Certain Symbol - -@defun symbol-file symbol &optional type -This function returns the name of the file that defined @var{symbol}. -If @var{type} is @code{nil}, then any kind of definition is acceptable. -If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that -specifies function definition, variable definition, or face definition -only. - -The value is normally an absolute file name. It can also be @code{nil}, -if the definition is not associated with any file. If @var{symbol} -specifies an autoloaded function, the value can be a relative file name -without extension. -@end defun - - The basis for @code{symbol-file} is the data in the variable -@code{load-history}. - -@defvar load-history -This variable's value is an alist connecting library file names with the -names of functions and variables they define, the features they provide, -and the features they require. - -Each element is a list and describes one library. The @sc{car} of the -list is the absolute file name of the library, as a string. The rest -of the list elements have these forms: - -@table @code -@item @var{var} -The symbol @var{var} was defined as a variable. -@item (defun . @var{fun}) -The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always -@code{(defun . @var{fun})}, which represents defining @var{fun} as a -function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. -@item (defface . @var{face}) -The face @var{face} was defined. -@item (require . @var{feature}) -The feature @var{feature} was required. -@item (provide . @var{feature}) -The feature @var{feature} was provided. -@end table - -The value of @code{load-history} may have one element whose @sc{car} is -@code{nil}. This element describes definitions made with -@code{eval-buffer} on a buffer that is not visiting a file. -@end defvar - - The command @code{eval-region} updates @code{load-history}, but does so -by adding the symbols defined to the element for the file being visited, -rather than replacing that element. @xref{Eval}. - -@node Unloading -@section Unloading -@cindex unloading packages - -@c Emacs 19 feature - You can discard the functions and variables loaded by a library to -reclaim memory for other Lisp objects. To do this, use the function -@code{unload-feature}: - -@deffn Command unload-feature feature &optional force -This command unloads the library that provided feature @var{feature}. -It undefines all functions, macros, and variables defined in that -library with @code{defun}, @code{defalias}, @code{defsubst}, -@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. -It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) - -Before restoring the previous definitions, @code{unload-feature} runs -@code{remove-hook} to remove functions in the library from certain -hooks. These hooks include variables whose names end in @samp{hook} -or @samp{-hooks}, plus those listed in -@code{unload-feature-special-hooks}, as well as -@code{auto-mode-alist}. This is to prevent Emacs from ceasing to -function because important hooks refer to functions that are no longer -defined. - -Standard unloading activities also undoes ELP profiling of functions -in that library, unprovides any features provided by the library, and -cancels timers held in variables defined by the library. - -@vindex @var{feature}-unload-function -If these measures are not sufficient to prevent malfunction, a library -can define an explicit unloader named @code{@var{feature}-unload-function}. -If that symbol is defined as a function, @code{unload-feature} calls -it with no arguments before doing anything else. It can do whatever -is appropriate to unload the library. If it returns @code{nil}, -@code{unload-feature} proceeds to take the normal unload actions. -Otherwise it considers the job to be done. - -Ordinarily, @code{unload-feature} refuses to unload a library on which -other loaded libraries depend. (A library @var{a} depends on library -@var{b} if @var{a} contains a @code{require} for @var{b}.) If the -optional argument @var{force} is non-@code{nil}, dependencies are -ignored and you can unload any library. -@end deffn - - The @code{unload-feature} function is written in Lisp; its actions are -based on the variable @code{load-history}. - -@defvar unload-feature-special-hooks -This variable holds a list of hooks to be scanned before unloading a -library, to remove functions defined in the library. -@end defvar - -@node Hooks for Loading -@section Hooks for Loading -@cindex loading hooks -@cindex hooks for loading - -You can ask for code to be executed if and when a particular library is -loaded, by calling @code{eval-after-load}. - -@defun eval-after-load library form -This function arranges to evaluate @var{form} at the end of loading -the file @var{library}, each time @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{form} right away. -Don't forget to quote @var{form}! - -You don't need to give a directory or extension in the file name -@var{library}---normally you just give a bare file name, like this: - -@example -(eval-after-load "edebug" '(def-edebug-spec c-point t)) -@end example - -To restrict which files can trigger the evaluation, include a -directory or an extension or both in @var{library}. Only a file whose -absolute true name (i.e., the name with all symbolic links chased out) -matches all the given name components will match. In the following -example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory -@code{..../foo/bar} will trigger the evaluation, but not -@file{my_inst.el}: - -@example -(eval-after-load "foo/bar/my_inst.elc" @dots{}) -@end example - -@var{library} can also be a feature (i.e.@: a symbol), in which case -@var{form} is evaluated when @code{(provide @var{library})} is called. - -An error in @var{form} does not undo the load, but does prevent -execution of the rest of @var{form}. -@end defun - -In general, well-designed Lisp programs should not use this feature. -The clean and modular ways to interact with a Lisp library are (1) -examine and set the library's variables (those which are meant for -outside use), and (2) call the library's functions. If you wish to -do (1), you can do it immediately---there is no need to wait for when -the library is loaded. To do (2), you must load the library (preferably -with @code{require}). - -But it is OK to use @code{eval-after-load} in your personal -customizations if you don't feel they must meet the design standards for -programs meant for wider use. - -@defvar after-load-alist -This variable, an alist built by @code{eval-after-load}, holds the -expressions to evaluate when particular libraries are loaded. Each -element looks like this: - -@example -(@var{regexp-or-feature} @var{forms}@dots{}) -@end example - -The key @var{regexp-or-feature} is either a regular expression or a -symbol, and the value is a list of forms. The forms are evaluated when -the key matches the absolute true name of the file being -@code{load}ed or the symbol being @code{provide}d. -@end defvar - -@ignore - arch-tag: df731f89-0900-4389-a436-9105241b6f7a -@end ignore diff --git a/doc/lispref/locals.texi b/doc/lispref/locals.texi deleted file mode 100644 index fcd627713c1..00000000000 --- a/doc/lispref/locals.texi +++ /dev/null @@ -1,228 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/locals -@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top -@appendix Buffer-Local Variables -@c The title "Standard Buffer-Local Variables" is too long for -@c smallbook. --rjc 30mar92 -@cindex buffer-local variables, general-purpose -@cindex standard buffer-local variables - - The table below lists the general-purpose Emacs variables that -automatically become buffer-local in each buffer. Most become -buffer-local only when set; a few of them are always local in every -buffer. Many Lisp packages define such variables for their internal -use, but we don't try to list them all here. - - Every buffer-specific minor mode defines a buffer-local variable -named @samp{@var{modename}-mode}. @xref{Minor Mode Conventions}. -Minor mode variables will not be listed here. - -@table @code -@item auto-fill-function -@xref{Auto Filling}. - -@item buffer-auto-save-file-format -@xref{Format Conversion}. - -@item buffer-auto-save-file-name -@xref{Auto-Saving}. - -@item buffer-backed-up -@xref{Making Backups}. - -@item buffer-display-count -@xref{Buffers and Windows}. - -@item buffer-display-table -@xref{Active Display Table}. - -@item buffer-display-time -@xref{Buffers and Windows}. - -@item buffer-file-coding-system -@xref{Encoding and I/O}. - -@item buffer-file-format -@xref{Format Conversion}. - -@item buffer-file-name -@xref{Buffer File Name}. - -@item buffer-file-number -@xref{Buffer File Name}. - -@item buffer-file-truename -@xref{Buffer File Name}. - -@item buffer-file-type -@xref{MS-DOS File Types}. - -@item buffer-invisibility-spec -@xref{Invisible Text}. - -@item buffer-offer-save -@xref{Killing Buffers}. - -@item buffer-save-without-query -@xref{Killing Buffers}. - -@item buffer-read-only -@xref{Read Only Buffers}. - -@item buffer-saved-size -@xref{Auto-Saving}. - -@item buffer-undo-list -@xref{Undo}. - -@item cache-long-line-scans -@xref{Truncation}. - -@item case-fold-search -@xref{Searching and Case}. - -@item ctl-arrow -@xref{Usual Display}. - -@item cursor-in-non-selected-windows -@xref{Basic Windows}. - -@item cursor-type -@xref{Cursor Parameters}. - -@item comment-column -@xref{Comments,,, emacs, The GNU Emacs Manual}. - -@item default-directory -@xref{File Name Expansion}. - -@item defun-prompt-regexp -@xref{List Motion}. - -@item desktop-save-buffer -@xref{Desktop Save Mode}. - -@ignore -@item direction-reversed -Does not work yet. -@end ignore - -@item enable-multibyte-characters -@ref{Text Representations}. - -@item fill-column -@xref{Margins}. - -@item fill-prefix -@xref{Margins}. - -@item font-lock-defaults -@xref{Font Lock Basics}. - -@item fringe-cursor-alist -@xref{Fringe Cursors}. - -@item fringe-indicator-alist -@xref{Fringe Indicators}. - -@item fringes-outside-margins -@xref{Fringes}. - -@item goal-column -@xref{Moving Point,,, emacs, The GNU Emacs Manual}. - -@item header-line-format -@xref{Header Lines}. - -@item indicate-buffer-boundaries -@xref{Usual Display}. - -@item indicate-empty-lines -@xref{Usual Display}. - -@item left-fringe-width -@xref{Fringe Size/Pos}. - -@item left-margin -@xref{Margins}. - -@item left-margin-width -@xref{Display Margins}. - -@item line-spacing -@xref{Line Height}. - -@item local-abbrev-table -@xref{Standard Abbrev Tables}. - -@item major-mode -@xref{Mode Help}. - -@item mark-active -@xref{The Mark}. - -@item mark-ring -@xref{The Mark}. - -@item mode-line-buffer-identification -@xref{Mode Line Variables}. - -@item mode-line-format -@xref{Mode Line Data}. - -@item mode-line-modified -@xref{Mode Line Variables}. - -@item mode-line-process -@xref{Mode Line Variables}. - -@item mode-name -@xref{Mode Line Variables}. - -@item point-before-scroll -Used for communication between mouse commands and scroll-bar commands. - -@item right-fringe-width -@xref{Fringe Size/Pos}. - -@item right-margin-width -@xref{Display Margins}. - -@item save-buffer-coding-system -@xref{Encoding and I/O}. - -@item scroll-bar-width -@xref{Scroll Bars}. - -@item scroll-down-aggressively -@itemx scroll-up-aggressively -@xref{Textual Scrolling}. - -@item selective-display -@itemx selective-display-ellipses -@xref{Selective Display}. - -@item tab-width -@xref{Usual Display}. - -@item truncate-lines -@xref{Truncation}. - -@item vertical-scroll-bar -@xref{Scroll Bars}. - -@item window-size-fixed -@xref{Resizing Windows}. - -@item write-contents-functions -@xref{Saving Buffers}. -@end table - - -@ignore - arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543 -@end ignore diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi deleted file mode 100644 index 935dc6553dc..00000000000 --- a/doc/lispref/macros.texi +++ /dev/null @@ -1,738 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/macros -@node Macros, Customization, Functions, Top -@chapter Macros -@cindex macros - - @dfn{Macros} enable you to define new control constructs and other -language features. A macro is defined much like a function, but instead -of telling how to compute a value, it tells how to compute another Lisp -expression which will in turn compute the value. We call this -expression the @dfn{expansion} of the macro. - - Macros can do this because they operate on the unevaluated expressions -for the arguments, not on the argument values as functions do. They can -therefore construct an expansion containing these argument expressions -or parts of them. - - If you are using a macro to do something an ordinary function could -do, just for the sake of speed, consider using an inline function -instead. @xref{Inline Functions}. - -@menu -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. -@end menu - -@node Simple Macro -@section A Simple Example of a Macro - - Suppose we would like to define a Lisp construct to increment a -variable value, much like the @code{++} operator in C. We would like to -write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. -Here's a macro definition that does the job: - -@findex inc -@example -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) -@end group -@end example - - When this is called with @code{(inc x)}, the argument @var{var} is the -symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would -be in a function. The body of the macro uses this to construct the -expansion, which is @code{(setq x (1+ x))}. Once the macro definition -returns this expansion, Lisp proceeds to evaluate it, thus incrementing -@code{x}. - -@node Expansion -@section Expansion of a Macro Call -@cindex expansion of macros -@cindex macro call - - A macro call looks just like a function call in that it is a list which -starts with the name of the macro. The rest of the elements of the list -are the arguments of the macro. - - Evaluation of the macro call begins like evaluation of a function call -except for one crucial difference: the macro arguments are the actual -expressions appearing in the macro call. They are not evaluated before -they are given to the macro definition. By contrast, the arguments of a -function are results of evaluating the elements of the function call -list. - - Having obtained the arguments, Lisp invokes the macro definition just -as a function is invoked. The argument variables of the macro are bound -to the argument values from the macro call, or to a list of them in the -case of a @code{&rest} argument. And the macro body executes and -returns its value just as a function body does. - - The second crucial difference between macros and functions is that the -value returned by the macro body is not the value of the macro call. -Instead, it is an alternate expression for computing that value, also -known as the @dfn{expansion} of the macro. The Lisp interpreter -proceeds to evaluate the expansion as soon as it comes back from the -macro. - - Since the expansion is evaluated in the normal manner, it may contain -calls to other macros. It may even be a call to the same macro, though -this is unusual. - - You can see the expansion of a given macro call by calling -@code{macroexpand}. - -@defun macroexpand form &optional environment -@cindex macro expansion -This function expands @var{form}, if it is a macro call. If the result -is another macro call, it is expanded in turn, until something which is -not a macro call results. That is the value returned by -@code{macroexpand}. If @var{form} is not a macro call to begin with, it -is returned as given. - -Note that @code{macroexpand} does not look at the subexpressions of -@var{form} (although some macro definitions may do so). Even if they -are macro calls themselves, @code{macroexpand} does not expand them. - -The function @code{macroexpand} does not expand calls to inline functions. -Normally there is no need for that, since a call to an inline function is -no harder to understand than a call to an ordinary function. - -If @var{environment} is provided, it specifies an alist of macro -definitions that shadow the currently defined macros. Byte compilation -uses this feature. - -@smallexample -@group -(defmacro inc (var) - (list 'setq var (list '1+ var))) - @result{} inc -@end group - -@group -(macroexpand '(inc r)) - @result{} (setq r (1+ r)) -@end group - -@group -(defmacro inc2 (var1 var2) - (list 'progn (list 'inc var1) (list 'inc var2))) - @result{} inc2 -@end group - -@group -(macroexpand '(inc2 r s)) - @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} -@end group -@end smallexample -@end defun - - -@defun macroexpand-all form &optional environment -@code{macroexpand-all} expands macros like @code{macroexpand}, but -will look for and expand all macros in @var{form}, not just at the -top-level. If no macros are expanded, the return value is @code{eq} -to @var{form}. - -Repeating the example used for @code{macroexpand} above with -@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does} -expand the embedded calls to @code{inc}: - -@smallexample -(macroexpand-all '(inc2 r s)) - @result{} (progn (setq r (1+ r)) (setq s (1+ s))) -@end smallexample - -@end defun - -@node Compiling Macros -@section Macros and Byte Compilation -@cindex byte-compiling macros - - You might ask why we take the trouble to compute an expansion for a -macro and then evaluate the expansion. Why not have the macro body -produce the desired results directly? The reason has to do with -compilation. - - When a macro call appears in a Lisp program being compiled, the Lisp -compiler calls the macro definition just as the interpreter would, and -receives an expansion. But instead of evaluating this expansion, it -compiles the expansion as if it had appeared directly in the program. -As a result, the compiled code produces the value and side effects -intended for the macro, but executes at full compiled speed. This would -not work if the macro body computed the value and side effects -itself---they would be computed at compile time, which is not useful. - - In order for compilation of macro calls to work, the macros must -already be defined in Lisp when the calls to them are compiled. The -compiler has a special feature to help you do this: if a file being -compiled contains a @code{defmacro} form, the macro is defined -temporarily for the rest of the compilation of that file. - - Byte-compiling a file also executes any @code{require} calls at -top-level in the file, so you can ensure that necessary macro -definitions are available during compilation by requiring the files -that define them (@pxref{Named Features}). To avoid loading the macro -definition files when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@node Defining Macros -@section Defining Macros - - A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should -be a function; expansion of the macro works by applying the function -(with @code{apply}) to the list of unevaluated argument-expressions -from the macro call. - - It is possible to use an anonymous Lisp macro just like an anonymous -function, but this is never done, because it does not make sense to pass -an anonymous macro to functionals such as @code{mapcar}. In practice, -all Lisp macros have names, and they are usually defined with the -special form @code{defmacro}. - -@defspec defmacro name argument-list body-forms@dots{} -@code{defmacro} defines the symbol @var{name} as a macro that looks -like this: - -@example -(macro lambda @var{argument-list} . @var{body-forms}) -@end example - -(Note that the @sc{cdr} of this list is a function---a lambda expression.) -This macro object is stored in the function cell of @var{name}. The -value returned by evaluating the @code{defmacro} form is @var{name}, but -usually we ignore this value. - -The shape and meaning of @var{argument-list} is the same as in a -function, and the keywords @code{&rest} and @code{&optional} may be used -(@pxref{Argument List}). Macros may have a documentation string, but -any @code{interactive} declaration is ignored since macros cannot be -called interactively. -@end defspec - - The body of the macro definition can include a @code{declare} form, -which can specify how @key{TAB} should indent macro calls, and how to -step through them for Edebug. - -@defmac declare @var{specs}@dots{} -@anchor{Definition of declare} -A @code{declare} form is used in a macro definition to specify various -additional information about it. Two kinds of specification are -currently supported: - -@table @code -@item (debug @var{edebug-form-spec}) -Specify how to step through macro calls for Edebug. -@xref{Instrumenting Macro Calls}. - -@item (indent @var{indent-spec}) -Specify how to indent calls to this macro. @xref{Indenting Macros}, -for more details. -@end table - -A @code{declare} form only has its special effect in the body of a -@code{defmacro} form if it immediately follows the documentation -string, if present, or the argument list otherwise. (Strictly -speaking, @emph{several} @code{declare} forms can follow the -documentation string or argument list, but since a @code{declare} form -can have several @var{specs}, they can always be combined into a -single form.) When used at other places in a @code{defmacro} form, or -outside a @code{defmacro} form, @code{declare} just returns @code{nil} -without evaluating any @var{specs}. -@end defmac - - No macro absolutely needs a @code{declare} form, because that form -has no effect on how the macro expands, on what the macro means in the -program. It only affects secondary features: indentation and Edebug. - -@node Backquote -@section Backquote -@cindex backquote (list substitution) -@cindex ` (list substitution) -@findex ` - - Macros often need to construct large list structures from a mixture of -constants and nonconstant parts. To make this easier, use the @samp{`} -syntax (usually called @dfn{backquote}). - - Backquote allows you to quote a list, but selectively evaluate -elements of that list. In the simplest case, it is identical to the -special form @code{quote} (@pxref{Quoting}). For example, these -two forms yield identical results: - -@example -@group -`(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@group -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with backquote)} -The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. Backquote evaluates the -argument of @samp{,} and puts the value in the list structure: - -@example -@group -(list 'a 'list 'of (+ 2 3) 'elements) - @result{} (a list of 5 elements) -@end group -@group -`(a list of ,(+ 2 3) elements) - @result{} (a list of 5 elements) -@end group -@end example - - Substitution with @samp{,} is allowed at deeper levels of the list -structure also. For example: - -@example -@group -(defmacro t-becomes-nil (variable) - `(if (eq ,variable t) - (setq ,variable nil))) -@end group - -@group -(t-becomes-nil foo) - @equiv{} (if (eq foo t) (setq foo nil)) -@end group -@end example - -@findex ,@@ @r{(with backquote)} -@cindex splicing (with backquote) - You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. The elements of the spliced list -become elements at the same level as the other elements of the resulting -list. The equivalent code without using @samp{`} is often unreadable. -Here are some examples: - -@example -@group -(setq some-list '(2 3)) - @result{} (2 3) -@end group -@group -(cons 1 (append some-list '(4) some-list)) - @result{} (1 2 3 4 2 3) -@end group -@group -`(1 ,@@some-list 4 ,@@some-list) - @result{} (1 2 3 4 2 3) -@end group - -@group -(setq list '(hack foo bar)) - @result{} (hack foo bar) -@end group -@group -(cons 'use - (cons 'the - (cons 'words (append (cdr list) '(as elements))))) - @result{} (use the words foo bar as elements) -@end group -@group -`(use the words ,@@(cdr list) as elements) - @result{} (use the words foo bar as elements) -@end group -@end example - -@node Problems with Macros -@section Common Problems Using Macros - - The basic facts of macro expansion have counterintuitive consequences. -This section describes some important consequences that can lead to -trouble, and rules to follow to avoid trouble. - -@menu -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. -@end menu - -@node Wrong Time -@subsection Wrong Time - - The most common problem in writing macros is doing some of the -real work prematurely---while expanding the macro, rather than in the -expansion itself. For instance, one real package had this macro -definition: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - (set-buffer-multibyte arg))) -@end example - -With this erroneous macro definition, the program worked fine when -interpreted but failed when compiled. This macro definition called -@code{set-buffer-multibyte} during compilation, which was wrong, and -then did nothing when the compiled package was run. The definition -that the programmer really wanted was this: - -@example -(defmacro my-set-buffer-multibyte (arg) - (if (fboundp 'set-buffer-multibyte) - `(set-buffer-multibyte ,arg))) -@end example - -@noindent -This macro expands, if appropriate, into a call to -@code{set-buffer-multibyte} that will be executed when the compiled -program is actually run. - -@node Argument Evaluation -@subsection Evaluating Macro Arguments Repeatedly - - When defining a macro you must pay attention to the number of times -the arguments will be evaluated when the expansion is executed. The -following macro (used to facilitate iteration) illustrates the problem. -This macro allows us to write a simple ``for'' loop such as one might -find in Pascal. - -@findex for -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - (list 'let (list (list var init)) - (cons 'while (cons (list '<= var final) - (append body (list (list 'inc var))))))) -@end group -@result{} for - -@group -(for i from 1 to 3 do - (setq square (* i i)) - (princ (format "\n%d %d" i square))) -@expansion{} -@end group -@group -(let ((i 1)) - (while (<= i 3) - (setq square (* i i)) - (princ (format "\n%d %d" i square)) - (inc i))) -@end group -@group - - @print{}1 1 - @print{}2 4 - @print{}3 9 -@result{} nil -@end group -@end smallexample - -@noindent -The arguments @code{from}, @code{to}, and @code{do} in this macro are -``syntactic sugar''; they are entirely ignored. The idea is that you -will write noise words (such as @code{from}, @code{to}, and @code{do}) -in those positions in the macro call. - -Here's an equivalent definition simplified through use of backquote: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple \"for\" loop. -For example, (for i from 1 to 10 do (print i))." - `(let ((,var ,init)) - (while (<= ,var ,final) - ,@@body - (inc ,var)))) -@end group -@end smallexample - -Both forms of this definition (with backquote and without) suffer from -the defect that @var{final} is evaluated on every iteration. If -@var{final} is a constant, this is not a problem. If it is a more -complex form, say @code{(long-complex-calculation x)}, this can slow -down the execution significantly. If @var{final} has side effects, -executing it more than once is probably incorrect. - -@cindex macro argument evaluation -A well-designed macro definition takes steps to avoid this problem by -producing an expansion that evaluates the argument expressions exactly -once unless repeated evaluation is part of the intended purpose of the -macro. Here is a correct expansion for the @code{for} macro: - -@smallexample -@group -(let ((i 1) - (max 3)) - (while (<= i max) - (setq square (* i i)) - (princ (format "%d %d" i square)) - (inc i))) -@end group -@end smallexample - -Here is a macro definition that creates this expansion: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end smallexample - - Unfortunately, this fix introduces another problem, -described in the following section. - -@node Surprising Local Vars -@subsection Local Variables in Macro Expansions - -@ifnottex - In the previous section, the definition of @code{for} was fixed as -follows to make the expansion evaluate the macro arguments the proper -number of times: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." -@end group -@group - `(let ((,var ,init) - (max ,final)) - (while (<= ,var max) - ,@@body - (inc ,var)))) -@end group -@end smallexample -@end ifnottex - - The new definition of @code{for} has a new problem: it introduces a -local variable named @code{max} which the user does not expect. This -causes trouble in examples such as the following: - -@smallexample -@group -(let ((max 0)) - (for x from 0 to 10 do - (let ((this (frob x))) - (if (< max this) - (setq max this))))) -@end group -@end smallexample - -@noindent -The references to @code{max} inside the body of the @code{for}, which -are supposed to refer to the user's binding of @code{max}, really access -the binding made by @code{for}. - -The way to correct this is to use an uninterned symbol instead of -@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be -bound and referred to just like any other symbol, but since it is -created by @code{for}, we know that it cannot already appear in the -user's program. Since it is not interned, there is no way the user can -put it into the program later. It will never appear anywhere except -where put by @code{for}. Here is a definition of @code{for} that works -this way: - -@smallexample -@group -(defmacro for (var from init to final do &rest body) - "Execute a simple for loop: (for i from 1 to 10 do (print i))." - (let ((tempvar (make-symbol "max"))) - `(let ((,var ,init) - (,tempvar ,final)) - (while (<= ,var ,tempvar) - ,@@body - (inc ,var))))) -@end group -@end smallexample - -@noindent -This creates an uninterned symbol named @code{max} and puts it in the -expansion instead of the usual interned symbol @code{max} that appears -in expressions ordinarily. - -@node Eval During Expansion -@subsection Evaluating Macro Arguments in Expansion - - Another problem can happen if the macro definition itself -evaluates any of the macro argument expressions, such as by calling -@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the -user's variables, you may have trouble if the user happens to use a -variable with the same name as one of the macro arguments. Inside the -macro body, the macro argument binding is the most local binding of this -variable, so any references inside the form being evaluated do refer to -it. Here is an example: - -@example -@group -(defmacro foo (a) - (list 'setq (eval a) t)) - @result{} foo -@end group -@group -(setq x 'b) -(foo x) @expansion{} (setq b t) - @result{} t ; @r{and @code{b} has been set.} -;; @r{but} -(setq a 'c) -(foo a) @expansion{} (setq a t) - @result{} t ; @r{but this set @code{a}, not @code{c}.} - -@end group -@end example - - It makes a difference whether the user's variable is named @code{a} or -@code{x}, because @code{a} conflicts with the macro argument variable -@code{a}. - - Another problem with calling @code{eval} in a macro definition is that -it probably won't do what you intend in a compiled program. The -byte compiler runs macro definitions while compiling the program, when -the program's own computations (which you might have wished to access -with @code{eval}) don't occur and its local variable bindings don't -exist. - - To avoid these problems, @strong{don't evaluate an argument expression -while computing the macro expansion}. Instead, substitute the -expression into the macro expansion, so that its value will be computed -as part of executing the expansion. This is how the other examples in -this chapter work. - -@node Repeated Expansion -@subsection How Many Times is the Macro Expanded? - - Occasionally problems result from the fact that a macro call is -expanded each time it is evaluated in an interpreted function, but is -expanded only once (during compilation) for a compiled function. If the -macro definition has side effects, they will work differently depending -on how many times the macro is expanded. - - Therefore, you should avoid side effects in computation of the -macro expansion, unless you really know what you are doing. - - One special kind of side effect can't be avoided: constructing Lisp -objects. Almost all macro expansions include constructed lists; that is -the whole point of most macros. This is usually safe; there is just one -case where you must be careful: when the object you construct is part of a -quoted constant in the macro expansion. - - If the macro is expanded just once, in compilation, then the object is -constructed just once, during compilation. But in interpreted -execution, the macro is expanded each time the macro call runs, and this -means a new object is constructed each time. - - In most clean Lisp code, this difference won't matter. It can matter -only if you perform side-effects on the objects constructed by the macro -definition. Thus, to avoid trouble, @strong{avoid side effects on -objects constructed by macro definitions}. Here is an example of how -such side effects can get you into trouble: - -@lisp -@group -(defmacro empty-object () - (list 'quote (cons nil nil))) -@end group - -@group -(defun initialize (condition) - (let ((object (empty-object))) - (if condition - (setcar object condition)) - object)) -@end group -@end lisp - -@noindent -If @code{initialize} is interpreted, a new list @code{(nil)} is -constructed each time @code{initialize} is called. Thus, no side effect -survives between calls. If @code{initialize} is compiled, then the -macro @code{empty-object} is expanded during compilation, producing a -single ``constant'' @code{(nil)} that is reused and altered each time -@code{initialize} is called. - -One way to avoid pathological cases like this is to think of -@code{empty-object} as a funny kind of constant, not as a memory -allocation construct. You wouldn't use @code{setcar} on a constant such -as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} -either. - -@node Indenting Macros -@section Indenting Macros - - You can use the @code{declare} form in the macro definition to -specify how to @key{TAB} should indent indent calls to the macro. You -write it like this: - -@example -(declare (indent @var{indent-spec})) -@end example - -@noindent -Here are the possibilities for @var{indent-spec}: - -@table @asis -@item @code{nil} -This is the same as no property---use the standard indentation pattern. -@item @code{defun} -Handle this function like a @samp{def} construct: treat the second -line as the start of a @dfn{body}. -@item an integer, @var{number} -The first @var{number} arguments of the function are -@dfn{distinguished} arguments; the rest are considered the body -of the expression. A line in the expression is indented according to -whether the first argument on it is distinguished or not. If the -argument is part of the body, the line is indented @code{lisp-body-indent} -more columns than the open-parenthesis starting the containing -expression. If the argument is distinguished and is either the first -or second argument, it is indented @emph{twice} that many extra columns. -If the argument is distinguished and not the first or second argument, -the line uses the standard pattern. -@item a symbol, @var{symbol} -@var{symbol} should be a function name; that function is called to -calculate the indentation of a line within this expression. The -function receives two arguments: -@table @asis -@item @var{state} -The value returned by @code{parse-partial-sexp} (a Lisp primitive for -indentation and nesting computation) when it parses up to the -beginning of this line. -@item @var{pos} -The position at which the line being indented begins. -@end table -@noindent -It should return either a number, which is the number of columns of -indentation for that line, or a list whose car is such a number. The -difference between returning a number and returning a list is that a -number says that all following lines at the same nesting level should -be indented just like this one; a list says that following lines might -call for different indentations. This makes a difference when the -indentation is being computed by @kbd{C-M-q}; if the value is a -number, @kbd{C-M-q} need not recalculate indentation for the following -lines until the end of the list. -@end table - -@ignore - arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b -@end ignore diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in deleted file mode 100644 index 1ba8e1e0389..00000000000 --- a/doc/lispref/makefile.w32-in +++ /dev/null @@ -1,125 +0,0 @@ -# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. - -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Standard configure variables. -srcdir = . - -infodir = $(srcdir)/../../info -usermanualdir = $(srcdir)/../emacs - -# Redefine `TEX' if `tex' does not invoke plain TeX. For example: -# TEX=platex -TEX=tex -INSTALL_INFO = install-info -MAKEINFO = makeinfo --force - -# The environment variable and its value to add $(srcdir) to the path -# searched for TeX input files. -texinputdir = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C - -# The name of the manual: -VERSION=2.9 -## FIXME can this be set by configure, as per Makefile.in? -manual = elisp-manual-23-$(VERSION) - -# List of all the texinfo files in the manual: - -srcs = \ - $(srcdir)/abbrevs.texi \ - $(srcdir)/advice.texi \ - $(srcdir)/anti.texi \ - $(srcdir)/back.texi \ - $(srcdir)/backups.texi \ - $(srcdir)/buffers.texi \ - $(srcdir)/commands.texi \ - $(srcdir)/compile.texi \ - $(srcdir)/control.texi \ - $(srcdir)/customize.texi \ - $(srcdir)/debugging.texi \ - $(srcdir)/display.texi \ - $(srcdir)/edebug.texi \ - $(srcdir)/elisp.texi \ - $(srcdir)/errors.texi \ - $(srcdir)/eval.texi \ - $(srcdir)/files.texi \ - $(srcdir)/frames.texi \ - $(srcdir)/functions.texi \ - $(srcdir)/hash.texi \ - $(srcdir)/help.texi \ - $(srcdir)/hooks.texi \ - $(srcdir)/internals.texi \ - $(srcdir)/intro.texi \ - $(srcdir)/keymaps.texi \ - $(srcdir)/lists.texi \ - $(srcdir)/loading.texi \ - $(srcdir)/locals.texi \ - $(srcdir)/macros.texi \ - $(srcdir)/maps.texi \ - $(srcdir)/markers.texi \ - $(srcdir)/minibuf.texi \ - $(srcdir)/modes.texi \ - $(srcdir)/nonascii.texi \ - $(srcdir)/numbers.texi \ - $(srcdir)/objects.texi \ - $(srcdir)/os.texi \ - $(srcdir)/positions.texi \ - $(srcdir)/processes.texi \ - $(srcdir)/searching.texi \ - $(srcdir)/sequences.texi \ - $(srcdir)/streams.texi \ - $(srcdir)/strings.texi \ - $(srcdir)/symbols.texi \ - $(srcdir)/syntax.texi \ - $(srcdir)/text.texi \ - $(srcdir)/tips.texi \ - $(srcdir)/variables.texi \ - $(srcdir)/windows.texi \ - $(srcdir)/index.texi \ - $(srcdir)/gpl.texi \ - $(srcdir)/doclicense.texi - - -.PHONY: clean - -# The info file is named `elisp'. - -info: $(infodir)/elisp - -$(infodir)/dir: - $(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp - -$(infodir)/elisp: $(srcs) - $(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi - -elisp.dvi: $(srcs) - $(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi - -clean: - - $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ - *.vr *.vrs *.pg *.pgs *.ky *.kys - - $(DEL) make.out core - - $(DEL) $(infodir)/elisp* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi deleted file mode 100644 index 88ab85a2ac7..00000000000 --- a/doc/lispref/maps.texi +++ /dev/null @@ -1,244 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/maps -@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top -@appendix Standard Keymaps -@cindex standard keymaps - -The following symbols are used as the names for various keymaps. -Some of these exist when Emacs is first started, others are -loaded only when their respective mode is used. This is not -an exhaustive list. - -Several keymaps are used in the minibuffer. @xref{Completion Commands}. - -Almost all of these maps are used as local maps. Indeed, of the modes -that presently exist, only Vip mode and Terminal mode ever change the -global keymap. - -@table @code -@item apropos-mode-map -@vindex apropos-mode-map -A sparse keymap for @code{apropos} buffers. - -@item Buffer-menu-mode-map -@vindex Buffer-menu-mode-map -A full keymap used by Buffer Menu mode. - -@item c-mode-map -@vindex c-mode-map -A sparse keymap used by C mode. - -@item command-history-map -@vindex command-history-map -A full keymap used by Command History mode. - -@item ctl-x-4-map -A sparse keymap for subcommands of the prefix @kbd{C-x 4}. - -@item ctl-x-5-map -A sparse keymap for subcommands of the prefix @kbd{C-x 5}. - -@item ctl-x-map -A full keymap for @kbd{C-x} commands. - -@item custom-mode-map -A full keymap for Custom mode. - -@item debugger-mode-map -@vindex debugger-mode-map -A full keymap used by Debugger mode. - -@item dired-mode-map -@vindex dired-mode-map -A full keymap for @code{dired-mode} buffers. - -@item edit-abbrevs-map -@vindex edit-abbrevs-map -A sparse keymap used in @code{edit-abbrevs}. - -@item edit-tab-stops-map -@vindex edit-tab-stops-map -A sparse keymap used in @code{edit-tab-stops}. - -@item electric-buffer-menu-mode-map -@vindex electric-buffer-menu-mode-map -A full keymap used by Electric Buffer Menu mode. - -@item electric-history-map -@vindex electric-history-map -A full keymap used by Electric Command History mode. - -@item emacs-lisp-mode-map -@vindex emacs-lisp-mode-map -A sparse keymap used by Emacs Lisp mode. - -@item esc-map -A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. - -@item facemenu-menu -@vindex facemenu-menu -The sparse keymap that displays the Text Properties menu. - -@item facemenu-background-menu -@vindex facemenu-background-menu -The sparse keymap that displays the Background Color submenu of the Text -Properties menu. - -@item facemenu-face-menu -@vindex facemenu-face-menu -The sparse keymap that displays the Face submenu of the Text Properties menu. - -@item facemenu-foreground-menu -@vindex facemenu-foreground-menu -The sparse keymap that displays the Foreground Color submenu of the Text -Properties menu. - -@item facemenu-indentation-menu -@vindex facemenu-indentation-menu -The sparse keymap that displays the Indentation submenu of the Text -Properties menu. - -@item facemenu-justification-menu -@vindex facemenu-justification-menu -The sparse keymap that displays the Justification submenu of the Text -Properties menu. - -@item facemenu-special-menu -@vindex facemenu-special-menu -The sparse keymap that displays the Special Props submenu of the Text -Properties menu. - -@item local-function-key-map -The keymap for translating key sequences to preferred alternatives.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item fundamental-mode-map -@vindex fundamental-mode-map -The sparse keymap for Fundamental mode.@* -It is empty and should not be changed. - -@item global-map -The full keymap containing default global key bindings.@* -Modes should not modify the Global map. - -@item grep-mode-map -@vindex grep-mode-map -The keymap for @code{grep-mode} buffers. - -@item help-map -The sparse keymap for the keys that follow the help character @kbd{C-h}. - -@item help-mode-map -@vindex help-mode-map -The sparse keymap for Help mode. - -@item Helper-help-map -@vindex Helper-help-map -A full keymap used by the help utility package.@* -It has the same keymap in its value cell and in its function -cell. - -@item Info-edit-map -@vindex Info-edit-map -A sparse keymap used by the @kbd{e} command of Info. - -@item Info-mode-map -@vindex Info-mode-map -A sparse keymap containing Info commands. - -@item input-decode-map -The keymap for translating keypad and function keys.@* -If there are none, then it contains an empty sparse keymap. -@xref{Translation Keymaps}. - -@item isearch-mode-map -@vindex isearch-mode-map -A keymap that defines the characters you can type within incremental -search. - -@item key-translation-map -A keymap for translating keys. This one overrides ordinary key -bindings, unlike @code{local- function-key-map}. @xref{Translation -Keymaps}. - -@item kmacro-map -@vindex kmacro-map -A sparse keymap for keys that follows the @kbd{C-x C-k} prefix -search. - -@item lisp-interaction-mode-map -@vindex lisp-interaction-mode-map -A sparse keymap used by Lisp Interaction mode. - -@item lisp-mode-map -@vindex lisp-mode-map -A sparse keymap used by Lisp mode. - -@item menu-bar-edit-menu -@vindex menu-bar-edit-menu -The keymap which displays the Edit menu in the menu bar. - -@item menu-bar-files-menu -@vindex menu-bar-files-menu -The keymap which displays the Files menu in the menu bar. - -@item menu-bar-help-menu -@vindex menu-bar-help-menu -The keymap which displays the Help menu in the menu bar. - -@item menu-bar-mule-menu -@vindex menu-bar-mule-menu -The keymap which displays the Mule menu in the menu bar. - -@item menu-bar-search-menu -@vindex menu-bar-search-menu -The keymap which displays the Search menu in the menu bar. - -@item menu-bar-tools-menu -@vindex menu-bar-tools-menu -The keymap which displays the Tools menu in the menu bar. - -@item mode-specific-map -The keymap for characters following @kbd{C-c}. Note, this is in the -global map. This map is not actually mode specific: its name was chosen -to be informative for the user in @kbd{C-h b} (@code{display-bindings}), -where it describes the main use of the @kbd{C-c} prefix key. - -@item multi-query-replace-map -A sparse keymap that extends @code{query-replace-map} for multi-buffer -replacements. @xref{Search and Replace, query-replace-map}. - -@item occur-mode-map -@vindex occur-mode-map -A sparse keymap used by Occur mode. - -@item query-replace-map -A sparse keymap used for responses in @code{query-replace} and related -commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions -that use this map do not support prefix keys; they look up one event at a -time. - -@item search-map -A sparse keymap that provides global bindings for search-related -commands. - -@item text-mode-map -@vindex text-mode-map -A sparse keymap used by Text mode. - -@item tool-bar-map -The keymap defining the contents of the tool bar. - -@item view-mode-map -@vindex view-mode-map -A full keymap used by View mode. -@end table - -@ignore - arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9 -@end ignore diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi deleted file mode 100644 index 78dbbefd790..00000000000 --- a/doc/lispref/markers.texi +++ /dev/null @@ -1,679 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/markers -@node Markers, Text, Positions, Top -@chapter Markers -@cindex markers - - A @dfn{marker} is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -@menu -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". -@end menu - -@node Overview of Markers -@section Overview of Markers - - A marker specifies a buffer and a position in that buffer. The -marker can be used to represent a position in the functions that -require one, just as an integer could be used. In that case, the -marker's buffer is normally ignored. Of course, a marker used in this -way usually points to a position in the buffer that the function -operates on, but that is entirely the programmer's responsibility. -@xref{Positions}, for a complete description of positions. - - A marker has three attributes: the marker position, the marker -buffer, and the insertion type. The marker position is an integer -that is equivalent (at a given time) to the marker as a position in -that buffer. But the marker's position value can change often during -the life of the marker. Insertion and deletion of text in the buffer -relocate the marker. The idea is that a marker positioned between two -characters remains between those two characters despite insertion and -deletion elsewhere in the buffer. Relocation changes the integer -equivalent of the marker. - -@cindex marker relocation - Deleting text around a marker's position leaves the marker between the -characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker either in -front of or after the new text, depending on the marker's @dfn{insertion -type} (@pxref{Marker Insertion Types})---unless the insertion is done -with @code{insert-before-markers} (@pxref{Insertion}). - -@cindex marker garbage collection - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Unreferenced markers are garbage collected eventually, but until then -will continue to use time if they do point somewhere. - -@cindex markers as numbers - Because it is common to perform arithmetic operations on a marker -position, most of the arithmetic operations (including @code{+} and -@code{-}) accept markers as arguments. In such cases, the marker -stands for its current position. - -Here are examples of creating markers, setting markers, and moving point -to markers: - -@example -@group -;; @r{Make a new marker that initially does not point anywhere:} -(setq m1 (make-marker)) - @result{} # -@end group - -@group -;; @r{Set @code{m1} to point between the 99th and 100th characters} -;; @r{in the current buffer:} -(set-marker m1 100) - @result{} # -@end group - -@group -;; @r{Now insert one character at the beginning of the buffer:} -(goto-char (point-min)) - @result{} 1 -(insert "Q") - @result{} nil -@end group - -@group -;; @r{@code{m1} is updated appropriately.} -m1 - @result{} # -@end group - -@group -;; @r{Two markers that point to the same position} -;; @r{are not @code{eq}, but they are @code{equal}.} -(setq m2 (copy-marker m1)) - @result{} # -(eq m1 m2) - @result{} nil -(equal m1 m2) - @result{} t -@end group - -@group -;; @r{When you are finished using a marker, make it point nowhere.} -(set-marker m1 nil) - @result{} # -@end group -@end example - -@node Predicates on Markers -@section Predicates on Markers - - You can test an object to see whether it is a marker, or whether it is -either an integer or a marker. The latter test is useful in connection -with the arithmetic functions that work with both markers and integers. - -@defun markerp object -This function returns @code{t} if @var{object} is a marker, @code{nil} -otherwise. Note that integers are not markers, even though many -functions will accept either a marker or an integer. -@end defun - -@defun integer-or-marker-p object -This function returns @code{t} if @var{object} is an integer or a marker, -@code{nil} otherwise. -@end defun - -@defun number-or-marker-p object -This function returns @code{t} if @var{object} is a number (either -integer or floating point) or a marker, @code{nil} otherwise. -@end defun - -@node Creating Markers -@section Functions that Create Markers - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - -The next four functions all return markers with insertion type -@code{nil}. @xref{Marker Insertion Types}. - -@defun make-marker -This function returns a newly created marker that does not point -anywhere. - -@example -@group -(make-marker) - @result{} # -@end group -@end example -@end defun - -@defun point-marker -This function returns a new marker that points to the present position -of point in the current buffer. @xref{Point}. For an example, see -@code{copy-marker}, below. -@end defun - -@defun point-min-marker -This function returns a new marker that points to the beginning of the -accessible portion of the buffer. This will be the beginning of the -buffer unless narrowing is in effect. @xref{Narrowing}. -@end defun - -@defun point-max-marker -This function returns a new marker that points to the end of the -accessible portion of the buffer. This will be the end of the buffer -unless narrowing is in effect. @xref{Narrowing}. - -Here are examples of this function and @code{point-min-marker}, shown in -a buffer containing a version of the source file for the text of this -chapter. - -@example -@group -(point-min-marker) - @result{} # -(point-max-marker) - @result{} # -@end group - -@group -(narrow-to-region 100 200) - @result{} nil -@end group -@group -(point-min-marker) - @result{} # -@end group -@group -(point-max-marker) - @result{} # -@end group -@end example -@end defun - -@defun copy-marker marker-or-integer &optional insertion-type -If passed a marker as its argument, @code{copy-marker} returns a -new marker that points to the same place and the same buffer as does -@var{marker-or-integer}. If passed an integer as its argument, -@code{copy-marker} returns a new marker that points to position -@var{marker-or-integer} in the current buffer. - -The new marker's insertion type is specified by the argument -@var{insertion-type}. @xref{Marker Insertion Types}. - -If passed an integer argument less than 1, @code{copy-marker} returns a -new marker that points to the beginning of the current buffer. If -passed an integer argument greater than the length of the buffer, -@code{copy-marker} returns a new marker that points to the end of the -buffer. - -@example -@group -(copy-marker 0) - @result{} # -@end group - -@group -(copy-marker 20000) - @result{} # -@end group -@end example - -An error is signaled if @var{marker} is neither a marker nor an -integer. -@end defun - - Two distinct markers are considered @code{equal} (even though not -@code{eq}) to each other if they have the same position and buffer, or -if they both point nowhere. - -@example -@group -(setq p (point-marker)) - @result{} # -@end group - -@group -(setq q (copy-marker p)) - @result{} # -@end group - -@group -(eq p q) - @result{} nil -@end group - -@group -(equal p q) - @result{} t -@end group -@end example - -@node Information from Markers -@section Information from Markers - - This section describes the functions for accessing the components of a -marker object. - -@defun marker-position marker -This function returns the position that @var{marker} points to, or -@code{nil} if it points nowhere. -@end defun - -@defun marker-buffer marker -This function returns the buffer that @var{marker} points into, or -@code{nil} if it points nowhere. - -@example -@group -(setq m (make-marker)) - @result{} # -@end group -@group -(marker-position m) - @result{} nil -@end group -@group -(marker-buffer m) - @result{} nil -@end group - -@group -(set-marker m 3770 (current-buffer)) - @result{} # -@end group -@group -(marker-buffer m) - @result{} # -@end group -@group -(marker-position m) - @result{} 3770 -@end group -@end example -@end defun - -@defun buffer-has-markers-at position -This function returns @code{t} if one or more markers -point at position @var{position} in the current buffer. -@end defun - -@node Marker Insertion Types -@section Marker Insertion Types - -@cindex insertion type of a marker - When you insert text directly at the place where a marker points, -there are two possible ways to relocate that marker: it can point before -the inserted text, or point after it. You can specify which one a given -marker should do by setting its @dfn{insertion type}. Note that use of -@code{insert-before-markers} ignores markers' insertion types, always -relocating a marker to point after the inserted text. - -@defun set-marker-insertion-type marker type -This function sets the insertion type of marker @var{marker} to -@var{type}. If @var{type} is @code{t}, @var{marker} will advance when -text is inserted at its position. If @var{type} is @code{nil}, -@var{marker} does not advance when text is inserted there. -@end defun - -@defun marker-insertion-type marker -This function reports the current insertion type of @var{marker}. -@end defun - -Most functions that create markers, without an argument allowing to -specify the insertion type, create them with insertion type -@code{nil}. Also, the mark has, by default, insertion type -@code{nil}. - -@node Moving Markers -@section Moving Marker Positions - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. - -@defun set-marker marker position &optional buffer -This function moves @var{marker} to @var{position} -in @var{buffer}. If @var{buffer} is not provided, it defaults to -the current buffer. - -If @var{position} is less than 1, @code{set-marker} moves @var{marker} -to the beginning of the buffer. If @var{position} is greater than the -size of the buffer, @code{set-marker} moves marker to the end of the -buffer. If @var{position} is @code{nil} or a marker that points -nowhere, then @var{marker} is set to point nowhere. - -The value returned is @var{marker}. - -@example -@group -(setq m (point-marker)) - @result{} # -@end group -@group -(set-marker m 55) - @result{} # -@end group -@group -(setq b (get-buffer "foo")) - @result{} # -@end group -@group -(set-marker m 0 b) - @result{} # -@end group -@end example -@end defun - -@defun move-marker marker position &optional buffer -This is another name for @code{set-marker}. -@end defun - -@node The Mark -@section The Mark -@cindex mark, the -@cindex mark ring - - Each buffer has a special marker, which is designated @dfn{the -mark}. When a buffer is newly created, this marker exists but does -not point anywhere; this means that the mark ``doesn't exist'' in that -buffer yet. Subsequent commands can set the mark. - - The mark specifies a position to bound a range of text for many -commands, such as @code{kill-region} and @code{indent-rigidly}. These -commands typically act on the text between point and the mark, which -is called the @dfn{region}. If you are writing a command that -operates on the region, don't examine the mark directly; instead, use -@code{interactive} with the @samp{r} specification. This provides the -values of point and the mark as arguments to the command in an -interactive call, but permits other Lisp programs to specify arguments -explicitly. @xref{Interactive Codes}. - - Some commands set the mark as a side-effect. Commands should do -this only if it has a potential use to the user, and never for their -own internal purposes. For example, the @code{replace-regexp} command -sets the mark to the value of point before doing any replacements, -because this enables the user to move back there conveniently after -the replace is finished. - - Once the mark ``exists'' in a buffer, it normally never ceases to -exist. However, it may become @dfn{inactive}, if Transient Mark mode -is enabled. The buffer-local variable @code{mark-active}, if -non-@code{nil}, means that the mark is active. A command can call the -function @code{deactivate-mark} to deactivate the mark directly, or it -can request deactivation of the mark upon return to the editor command -loop by setting the variable @code{deactivate-mark} to a -non-@code{nil} value. - - If Transient Mode is enabled, certain editing commands that normally -apply to text near point, apply instead to the region when the mark is -active. This is the main motivation for using Transient Mark mode. -(Another is that this enables highlighting of the region when the mark -is active. @xref{Display}.) - - In addition to the mark, each buffer has a @dfn{mark ring} which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable @code{mark-ring-max} specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - - There is also a separate global mark ring, but that is used only in a -few particular user-level commands, and is not relevant to Lisp -programming. So we do not describe it here. - -@defun mark &optional force -@cindex current buffer mark -This function returns the current buffer's mark position as an integer, -or @code{nil} if no mark has ever been set in this buffer. - -If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is -@code{nil}, @code{mark} signals an error if the mark is inactive. -However, if @var{force} is non-@code{nil}, then @code{mark} disregards -inactivity of the mark, and returns the mark position (or @code{nil}) -anyway. -@end defun - -@defun mark-marker -This function returns the marker that represents the current buffer's -mark. It is not a copy, it is the marker used internally. Therefore, -changing this marker's position will directly affect the buffer's -mark. Don't do that unless that is the effect you want. - -@example -@group -(setq m (mark-marker)) - @result{} # -@end group -@group -(set-marker m 100) - @result{} # -@end group -@group -(mark-marker) - @result{} # -@end group -@end example - -Like any marker, this marker can be set to point at any buffer you -like. If you make it point at any buffer other than the one of which -it is the mark, it will yield perfectly consistent, but rather odd, -results. We recommend that you not do it! -@end defun - -@defun set-mark position -This function sets the mark to @var{position}, and activates the mark. -The old value of the mark is @emph{not} pushed onto the mark ring. - -@strong{Please note:} Use this function only if you want the user to -see that the mark has moved, and you want the previous mark position to -be lost. Normally, when a new mark is set, the old one should go on the -@code{mark-ring}. For this reason, most applications should use -@code{push-mark} and @code{pop-mark}, not @code{set-mark}. - -Novice Emacs Lisp programmers often try to use the mark for the wrong -purposes. The mark saves a location for the user's convenience. An -editing command should not alter the mark unless altering the mark is -part of the user-level functionality of the command. (And, in that -case, this effect should be documented.) To remember a location for -internal use in the Lisp program, store it in a Lisp variable. For -example: - -@example -@group -(let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). -@end group -@end example -@end defun - -@defun push-mark &optional position nomsg activate -This function sets the current buffer's mark to @var{position}, and -pushes a copy of the previous mark onto @code{mark-ring}. If -@var{position} is @code{nil}, then the value of point is used. -@code{push-mark} returns @code{nil}. - -The function @code{push-mark} normally @emph{does not} activate the -mark. To do that, specify @code{t} for the argument @var{activate}. - -A @samp{Mark set} message is displayed unless @var{nomsg} is -non-@code{nil}. -@end defun - -@defun pop-mark -This function pops off the top element of @code{mark-ring} and makes -that mark become the buffer's actual mark. This does not move point in -the buffer, and it does nothing if @code{mark-ring} is empty. It -deactivates the mark. - -The return value is not meaningful. -@end defun - -@defopt transient-mark-mode -This variable, if non-@code{nil}, enables Transient Mark mode. In -Transient Mark mode, every buffer-modifying primitive sets -@code{deactivate-mark}. As a consequence, most commands that modify -the buffer also deactivate the mark. - -When Transient Mark mode is enabled and the mark is active, many -commands that normally apply to the text near point instead apply to -the region. Such commands should use the function @code{use-region-p} -to test whether they should operate on the region. @xref{The Region}. - -Lisp programs can set @code{transient-mark-mode} to non-@code{nil}, -non-@code{t} values to enable Transient Mark mode temporarily. If the -value is @code{lambda}, Transient Mark mode is automatically turned -off after any action, such as buffer modification, that would normally -deactivate the mark. If the value is @w{@code{(only . @var{oldval})}}, -then @code{transient-mark-mode} is set to the value @var{oldval} after -any subsequent command that moves point and is not shift-translated -(@pxref{Key Sequence Input, shift-translation}), or after any other -action that would normally deactivate the mark. -@end defopt - -@defopt mark-even-if-inactive -If this is non-@code{nil}, Lisp programs and the Emacs user can use the -mark even when it is inactive. This option affects the behavior of -Transient Mark mode. When the option is non-@code{nil}, deactivation of -the mark turns off region highlighting, but commands that use the mark -behave as if the mark were still active. -@end defopt - -@defvar deactivate-mark -If an editor command sets this variable non-@code{nil}, then the editor -command loop deactivates the mark after the command returns (if -Transient Mark mode is enabled). All the primitives that change the -buffer set @code{deactivate-mark}, to deactivate the mark when the -command is finished. - -To write Lisp code that modifies the buffer without causing -deactivation of the mark at the end of the command, bind -@code{deactivate-mark} to @code{nil} around the code that does the -modification. For example: - -@example -(let (deactivate-mark) - (insert " ")) -@end example -@end defvar - -@defun deactivate-mark -This function deactivates the mark, if Transient Mark mode is enabled. -Otherwise it does nothing. -@end defun - -@defvar mark-active -The mark is active when this variable is non-@code{nil}. This -variable is always buffer-local in each buffer. Do @emph{not} use the -value of this variable to decide whether a command that normally -operates on text near point should operate on the region instead. Use -the function @code{use-region-p} for that (@pxref{The Region}). -@end defvar - -@defvar activate-mark-hook -@defvarx deactivate-mark-hook -These normal hooks are run, respectively, when the mark becomes active -and when it becomes inactive. The hook @code{activate-mark-hook} is -also run at the end of a command if the mark is active and it is -possible that the region may have changed. -@end defvar - -@defun handle-shift-selection -This function implements the ``shift-selection'' behavior of -point-motion commands. @xref{Shift Selection,,, emacs, The GNU Emacs -Manual}. It is called automatically by the Emacs command loop -whenever a command with a @samp{^} character in its @code{interactive} -spec is invoked, before the command itself is executed -(@pxref{Interactive Codes, ^}). - -If @code{shift-select-mode} is non-@code{nil} and the current command -was invoked via shift translation (@pxref{Key Sequence Input, -shift-translation}), this function sets the mark and temporarily -activates the region, unless the region was already temporarily -activated in this way. Otherwise, if the region has been activated -temporarily, it deactivates the mark and restores the variable -@code{transient-mark-mode} to its earlier value. -@end defun - -@defvar mark-ring -The value of this buffer-local variable is the list of saved former -marks of the current buffer, most recent first. - -@example -@group -mark-ring -@result{} (# - # - @dots{}) -@end group -@end example -@end defvar - -@defopt mark-ring-max -The value of this variable is the maximum size of @code{mark-ring}. If -more marks than this are pushed onto the @code{mark-ring}, -@code{push-mark} discards an old mark when it adds a new one. -@end defopt - -@node The Region -@section The Region -@cindex region (between point and mark) - - The text between point and the mark is known as @dfn{the region}. -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - -The next two functions signal an error if the mark does not point -anywhere. If Transient Mark mode is enabled and -@code{mark-even-if-inactive} is @code{nil}, they also signal an error -if the mark is inactive. - -@defun region-beginning -This function returns the position of the beginning of the region (as -an integer). This is the position of either point or the mark, -whichever is smaller. -@end defun - -@defun region-end -This function returns the position of the end of the region (as an -integer). This is the position of either point or the mark, whichever is -larger. -@end defun - - Few programs need to use the @code{region-beginning} and -@code{region-end} functions. A command designed to operate on a region -should normally use @code{interactive} with the @samp{r} specification -to find the beginning and end of the region. This lets other Lisp -programs specify the bounds explicitly as arguments. (@xref{Interactive -Codes}.) - -@defun use-region-p -This function returns @code{t} if Transient Mark mode is enabled, the -mark is active, and there's a valid region in the buffer. Commands -that operate on the region (instead of on text near point) when -there's an active mark should use this to test whether to do that. -@end defun - -@ignore - arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299 -@end ignore diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi deleted file mode 100644 index c28ab70e2d8..00000000000 --- a/doc/lispref/minibuf.texi +++ /dev/null @@ -1,2140 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/minibuf -@node Minibuffers, Command Loop, Read and Print, Top -@chapter Minibuffers -@cindex arguments, reading -@cindex complex arguments -@cindex minibuffer - - A @dfn{minibuffer} is a special buffer that Emacs commands use to -read arguments more complicated than the single numeric prefix -argument. These arguments include file names, buffer names, and -command names (as in @kbd{M-x}). The minibuffer is displayed on the -bottom line of the frame, in the same place as the echo area -(@pxref{The Echo Area}), but only while it is in use for reading an -argument. - -@menu -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. -@end menu - -@node Intro to Minibuffers -@section Introduction to Minibuffers - - In most ways, a minibuffer is a normal Emacs buffer. Most operations -@emph{within} a buffer, such as editing commands, work normally in a -minibuffer. However, many operations for managing buffers do not apply -to minibuffers. The name of a minibuffer always has the form @w{@samp{ -*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are -displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometimes frames have -no minibuffer window, and sometimes a special kind of frame contains -nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - - The text in the minibuffer always starts with the @dfn{prompt string}, -the text that was specified by the program that is using the minibuffer -to tell the user what sort of input to type. This text is marked -read-only so you won't accidentally delete or change it. It is also -marked as a field (@pxref{Fields}), so that certain motion functions, -including @code{beginning-of-line}, @code{forward-word}, -@code{forward-sentence}, and @code{forward-paragraph}, stop at the -boundary between the prompt and the actual text. - - The minibuffer's window is normally a single line; it grows -automatically if the contents require more space. You can explicitly -resize it temporarily with the window sizing commands; it reverts to -its normal size when the minibuffer is exited. You can resize it -permanently by using the window sizing commands in the frame's other -window, when the minibuffer is not active. If the frame contains just -a minibuffer, you can change the minibuffer's size by changing the -frame's size. - - Use of the minibuffer reads input events, and that alters the values -of variables such as @code{this-command} and @code{last-command} -(@pxref{Command Loop Info}). Your program should bind them around the -code that uses the minibuffer, if you do not want that to change them. - - Under some circumstances, a command can use a minibuffer even if -there is an active minibuffer; such minibuffers are called a -@dfn{recursive minibuffer}. The first minibuffer is named -@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with -a space so that they won't show up in normal buffer lists.) Of -several recursive minibuffers, the innermost (or most recently -entered) is the active minibuffer. We usually call this ``the'' -minibuffer. You can permit or forbid recursive minibuffers by setting -the variable @code{enable-recursive-minibuffers}, or by putting -properties of that name on command symbols (@xref{Recursive Mini}.) - - Like other buffers, a minibuffer uses a local keymap -(@pxref{Keymaps}) to specify special key bindings. The function that -invokes the minibuffer also sets up its local map according to the job -to be done. @xref{Text from Minibuffer}, for the non-completion -minibuffer local maps. @xref{Completion Commands}, for the minibuffer -local maps for completion. - - When Emacs is running in batch mode, any request to read from the -minibuffer actually reads a line from the standard input descriptor that -was supplied when Emacs was started. - -@node Text from Minibuffer -@section Reading Text Strings with the Minibuffer - - The most basic primitive for minibuffer input is -@code{read-from-minibuffer}, which can be used to read either a string -or a Lisp object in textual form. The function @code{read-regexp} is -used for reading regular expressions (@pxref{Regular Expressions}), -which are a special kind of string. There are also specialized -functions for reading commands, variables, file names, etc.@: -(@pxref{Completion}). - - In most cases, you should not call minibuffer input functions in the -middle of a Lisp function. Instead, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method -This function is the most general way to get input from the -minibuffer. By default, it accepts arbitrary text and returns it as a -string; however, if @var{read} is non-@code{nil}, then it uses -@code{read} to convert the text into a Lisp object (@pxref{Input -Functions}). - -The first thing this function does is to activate a minibuffer and -display it with @var{prompt-string} as the prompt. This value must be a -string. Then the user can edit text in the minibuffer. - -When the user types a command to exit the minibuffer, -@code{read-from-minibuffer} constructs the return value from the text in -the minibuffer. Normally it returns a string containing that text. -However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer} -reads the text and returns the resulting Lisp object, unevaluated. -(@xref{Input Functions}, for information about reading.) - -The argument @var{default} specifies default values to make available -through the history commands. It should be a string, a list of -strings, or @code{nil}. The string or strings become the minibuffer's -``future history,'' available to the user with @kbd{M-n}. - -If @var{read} is non-@code{nil}, then @var{default} is also used -as the input to @code{read}, if the user enters empty input. -If @var{default} is a list of strings, the first string is used as the input. -If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error. -However, in the usual case (where @var{read} is @code{nil}), -@code{read-from-minibuffer} ignores @var{default} when the user enters -empty input and returns an empty string, @code{""}. In this respect, -it differs from all the other minibuffer input functions in this chapter. - -If @var{keymap} is non-@code{nil}, that keymap is the local keymap to -use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the -value of @code{minibuffer-local-map} is used as the keymap. Specifying -a keymap is the most important way to customize the minibuffer for -various applications such as completion. - -The argument @var{hist} specifies which history list variable to use -for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. - -If the variable @code{minibuffer-allow-text-properties} is -non-@code{nil}, then the string which is returned includes whatever text -properties were present in the minibuffer. Otherwise all the text -properties are stripped when the value is returned. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input Methods}) and -the setting of @code{enable-multibyte-characters} (@pxref{Text -Representations}) from whichever buffer was current before entering the -minibuffer. - -Use of @var{initial-contents} is mostly deprecated; we recommend using -a non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. -@end defun - -@defun read-string prompt &optional initial history default inherit-input-method -This function reads a string from the minibuffer and returns it. The -arguments @var{prompt}, @var{initial}, @var{history} and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. -The keymap used is @code{minibuffer-local-map}. - -The optional argument @var{default} is used as in -@code{read-from-minibuffer}, except that, if non-@code{nil}, it also -specifies a default value to return if the user enters null input. As -in @code{read-from-minibuffer} it should be a string, a list of -strings, or @code{nil} which is equivalent to an empty string. When -@var{default} is a string, that string is the default value. When it -is a list of strings, the first string is the default value. (All -these strings are available to the user in the ``future minibuffer -history.'') - -This function works by calling the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit}) -@equiv{} -(let ((value - (read-from-minibuffer @var{prompt} @var{initial} nil nil - @var{history} @var{default} @var{inherit}))) - (if (and (equal value "") @var{default}) - (if (consp @var{default}) (car @var{default}) @var{default}) - value)) -@end group -@end smallexample -@end defun - -@defun read-regexp prompt &optional default-value -This function reads a regular expression as a string from the -minibuffer and returns it. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. The keymap used is -@code{minibuffer-local-map}, and @code{regexp-history} is used as the -history list (@pxref{Minibuffer History, regexp-history}). - -The optional argument @var{default-value} specifies a default value to -return if the user enters null input; it should be a string, or -@code{nil} which is equivalent to an empty string. - -In addition, @code{read-regexp} collects a few useful candidates for -input and passes them to @code{read-from-minibuffer}, to make them -available to the user as the ``future minibuffer history list'' -(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs -Manual}). These candidates are: - -@itemize @minus -@item -The word or symbol at point. -@item -The last regexp used in an incremental search. -@item -The last string used in an incremental search. -@item -The last string or pattern used in query-replace commands. -@end itemize - -This function works by calling the @code{read-from-minibuffer} -function, after computing the list of defaults as described above. -@end defun - -@defvar minibuffer-allow-text-properties -If this variable is @code{nil}, then @code{read-from-minibuffer} strips -all text properties from the minibuffer input before returning it. -This variable also affects @code{read-string}. However, -@code{read-no-blanks-input} (see below), as well as -@code{read-minibuffer} and related functions (@pxref{Object from -Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all -functions that do minibuffer input with completion, discard text -properties unconditionally, regardless of the value of this variable. -@end defvar - -@defvar minibuffer-local-map -This -@anchor{Definition of minibuffer-local-map} -@c avoid page break at anchor; work around Texinfo deficiency -is the default local keymap for reading from the minibuffer. By -default, it makes the following bindings: - -@table @asis -@item @kbd{C-j} -@code{exit-minibuffer} - -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - -@item @kbd{M-n} -@itemx @key{DOWN} -@code{next-history-element} - -@item @kbd{M-p} -@itemx @key{UP} -@code{previous-history-element} - -@item @kbd{M-s} -@code{next-matching-history-element} - -@item @kbd{M-r} -@code{previous-matching-history-element} -@end table -@end defvar - -@c In version 18, initial is required -@c Emacs 19 feature -@defun read-no-blanks-input prompt &optional initial inherit-input-method -This function reads a string from the minibuffer, but does not allow -whitespace characters as part of the input: instead, those characters -terminate the input. The arguments @var{prompt}, @var{initial}, and -@var{inherit-input-method} are used as in @code{read-from-minibuffer}. - -This is a simplified interface to the @code{read-from-minibuffer} -function, and passes the value of the @code{minibuffer-local-ns-map} -keymap as the @var{keymap} argument for that function. Since the keymap -@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} -possible to put a space into the string, by quoting it. - -This function discards text properties, regardless of the value of -@code{minibuffer-allow-text-properties}. - -@smallexample -@group -(read-no-blanks-input @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)) -@end group -@end smallexample -@end defun - -@defvar minibuffer-local-ns-map -This built-in variable is the keymap used as the minibuffer local keymap -in the function @code{read-no-blanks-input}. By default, it makes the -following bindings, in addition to those of @code{minibuffer-local-map}: - -@table @asis -@item @key{SPC} -@cindex @key{SPC} in minibuffer -@code{exit-minibuffer} - -@item @key{TAB} -@cindex @key{TAB} in minibuffer -@code{exit-minibuffer} - -@item @kbd{?} -@cindex @kbd{?} in minibuffer -@code{self-insert-and-exit} -@end table -@end defvar - -@node Object from Minibuffer -@section Reading Lisp Objects with the Minibuffer - - This section describes functions for reading Lisp objects with the -minibuffer. - -@defun read-minibuffer prompt &optional initial -This function reads a Lisp object using the minibuffer, and returns it -without evaluating it. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-minibuffer @var{prompt} @var{initial}) -@equiv{} -(let (minibuffer-allow-text-properties) - (read-from-minibuffer @var{prompt} @var{initial} nil t)) -@end group -@end smallexample - -Here is an example in which we supply the string @code{"(testing)"} as -initial input: - -@smallexample -@group -(read-minibuffer - "Enter an expression: " (format "%s" '(testing))) - -;; @r{Here is how the minibuffer is displayed:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Enter an expression: (testing)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -The user can type @key{RET} immediately to use the initial input as a -default, or can edit the input. -@end defun - -@defun eval-minibuffer prompt &optional initial -This function reads a Lisp expression using the minibuffer, evaluates -it, then returns the result. The arguments @var{prompt} and -@var{initial} are used as in @code{read-from-minibuffer}. - -This function simply evaluates the result of a call to -@code{read-minibuffer}: - -@smallexample -@group -(eval-minibuffer @var{prompt} @var{initial}) -@equiv{} -(eval (read-minibuffer @var{prompt} @var{initial})) -@end group -@end smallexample -@end defun - -@defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, and then -evaluates it. The difference between this command and -@code{eval-minibuffer} is that here the initial @var{form} is not -optional and it is treated as a Lisp object to be converted to printed -representation rather than as a string of text. It is printed with -@code{prin1}, so if it is a string, double-quote characters (@samp{"}) -appear in the initial text. @xref{Output Functions}. - -The first thing @code{edit-and-eval-command} does is to activate the -minibuffer with @var{prompt} as the prompt. Then it inserts the printed -representation of @var{form} in the minibuffer, and lets the user edit it. -When the user exits the minibuffer, the edited text is read with -@code{read} and then evaluated. The resulting value becomes the value -of @code{edit-and-eval-command}. - -In the following example, we offer the user an expression with initial -text which is a valid form already: - -@smallexample -@group -(edit-and-eval-command "Please edit: " '(forward-word 1)) - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Please edit: (forward-word 1)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -Typing @key{RET} right away would exit the minibuffer and evaluate the -expression, thus moving point forward one word. -@code{edit-and-eval-command} returns @code{nil} in this example. -@end defun - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history list - - A @dfn{minibuffer history list} records previous minibuffer inputs so -the user can reuse them conveniently. A history list is actually a -symbol, not a list; it is a variable whose value is a list of strings -(previous inputs), most recent first. - - There are many separate history lists, used for different kinds of -inputs. It's the Lisp programmer's job to specify the right history -list for each use of the minibuffer. - - You specify the history list with the optional @var{hist} argument -to either @code{read-from-minibuffer} or @code{completing-read}. Here -are the possible values for it: - -@table @asis -@item @var{variable} -Use @var{variable} (a symbol) as the history list. - -@item (@var{variable} . @var{startpos}) -Use @var{variable} (a symbol) as the history list, and assume that the -initial history position is @var{startpos} (a nonnegative integer). - -Specifying 0 for @var{startpos} is equivalent to just specifying the -symbol @var{variable}. @code{previous-history-element} will display -the most recent element of the history list in the minibuffer. If you -specify a positive @var{startpos}, the minibuffer history functions -behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the -history element currently shown in the minibuffer. - -For consistency, you should also specify that element of the history -as the initial minibuffer contents, using the @var{initial} argument -to the minibuffer input function (@pxref{Initial Input}). -@end table - - If you don't specify @var{hist}, then the default history list -@code{minibuffer-history} is used. For other standard history lists, -see below. You can also create your own history list variable; just -initialize it to @code{nil} before the first use. - - Both @code{read-from-minibuffer} and @code{completing-read} add new -elements to the history list automatically, and provide commands to -allow the user to reuse items on the list. The only thing your program -needs to do to use a history list is to initialize it and to pass its -name to the input functions when you wish. But it is safe to modify the -list by hand when the minibuffer input functions are not using it. - - Emacs functions that add a new element to a history list can also -delete old elements if the list gets too long. The variable -@code{history-length} specifies the maximum length for most history -lists. To specify a different maximum length for a particular history -list, put the length in the @code{history-length} property of the -history list symbol. The variable @code{history-delete-duplicates} -specifies whether to delete duplicates in history. - -@defun add-to-history history-var newelt &optional maxelt keep-all -This function adds a new element @var{newelt}, if it isn't the empty -string, to the history list stored in the variable @var{history-var}, -and returns the updated history list. It limits the list length to -the value of @var{maxelt} (if non-@code{nil}) or @code{history-length} -(described below). The possible values of @var{maxelt} have the same -meaning as the values of @code{history-length}. - -Normally, @code{add-to-history} removes duplicate members from the -history list if @code{history-delete-duplicates} is non-@code{nil}. -However, if @var{keep-all} is non-@code{nil}, that says not to remove -duplicates, and to add @var{newelt} to the list even if it is empty. -@end defun - -@defvar history-add-new-input -If the value of this variable is @code{nil}, standard functions that -read from the minibuffer don't add new elements to the history list. -This lets Lisp programs explicitly manage input history by using -@code{add-to-history}. By default, @code{history-add-new-input} is -set to a non-@code{nil} value. -@end defvar - -@defopt history-length -The value of this variable specifies the maximum length for all -history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there no maximum (don't delete old -elements). The value of @code{history-length} property of the history -list variable's symbol, if set, overrides this variable for that -particular history list. -@end defopt - -@defopt history-delete-duplicates -If the value of this variable is @code{t}, that means when adding a -new history element, all previous identical elements are deleted. -@end defopt - - Here are some of the standard minibuffer history list variables: - -@defvar minibuffer-history -The default history list for minibuffer history input. -@end defvar - -@defvar query-replace-history -A history list for arguments to @code{query-replace} (and similar -arguments to other commands). -@end defvar - -@defvar file-name-history -A history list for file-name arguments. -@end defvar - -@defvar buffer-name-history -A history list for buffer-name arguments. -@end defvar - -@defvar regexp-history -A history list for regular expression arguments. -@end defvar - -@defvar extended-command-history -A history list for arguments that are names of extended commands. -@end defvar - -@defvar shell-command-history -A history list for arguments that are shell commands. -@end defvar - -@defvar read-expression-history -A history list for arguments that are Lisp expressions to evaluate. -@end defvar - -@node Initial Input -@section Initial Input - -Several of the functions for minibuffer input have an argument called -@var{initial} or @var{initial-contents}. This is a mostly-deprecated -feature for specifying that the minibuffer should start out with -certain text, instead of empty as usual. - -If @var{initial} is a string, the minibuffer starts out containing the -text of the string, with point at the end, when the user starts to -edit the text. If the user simply types @key{RET} to exit the -minibuffer, it will use the initial input string to determine the -value to return. - -@strong{We discourage use of a non-@code{nil} value for -@var{initial}}, because initial input is an intrusive interface. -History lists and default values provide a much more convenient method -to offer useful default inputs to the user. - -There is just one situation where you should specify a string for an -@var{initial} argument. This is when you specify a cons cell for the -@var{hist} or @var{history} argument. @xref{Minibuffer History}. - -@var{initial} can also be a cons cell of the form @code{(@var{string} -. @var{position})}. This means to insert @var{string} in the -minibuffer but put point at @var{position} within the string's text. - -As a historical accident, @var{position} was implemented -inconsistently in different functions. In @code{completing-read}, -@var{position}'s value is interpreted as origin-zero; that is, a value -of 0 means the beginning of the string, 1 means after the first -character, etc. In @code{read-minibuffer}, and the other -non-completion minibuffer input functions that support this argument, -1 means the beginning of the string 2 means after the first character, -etc. - -Use of a cons cell as the value for @var{initial} arguments is -deprecated in user code. - -@node Completion -@section Completion -@cindex completion - - @dfn{Completion} is a feature that fills in the rest of a name -starting from an abbreviation for it. Completion works by comparing the -user's input against a list of valid names and determining how much of -the name is determined uniquely by what the user has typed. For -example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then -type the first few letters of the name of the buffer to which you wish -to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs -extends the name as far as it can. - - Standard Emacs commands offer completion for names of symbols, files, -buffers, and processes; with the functions in this section, you can -implement completion for other kinds of names. - - The @code{try-completion} function is the basic primitive for -completion: it returns the longest determined completion of a given -initial string, with a given set of strings to match against. - - The function @code{completing-read} provides a higher-level interface -for completion. A call to @code{completing-read} specifies how to -determine the list of valid names. The function then activates the -minibuffer with a local keymap that binds a few keys to commands useful -for completion. Other functions provide convenient simple interfaces -for reading certain kinds of names with completion. - -@menu -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Styles:: Specifying rules for performing completion. -* Programmed Completion:: Writing your own completion-function. -@end menu - -@node Basic Completion -@subsection Basic Completion Functions - - The completion functions @code{try-completion}, -@code{all-completions} and @code{test-completion} have nothing in -themselves to do with minibuffers. We describe them in this chapter -so as to keep them near the higher-level completion features that do -use the minibuffer. - - If you store a completion alist in a variable, you should mark the -variable as ``risky'' with a non-@code{nil} -@code{risky-local-variable} property. - -@defun try-completion string collection &optional predicate -This function returns the longest common substring of all possible -completions of @var{string} in @var{collection}. The value of -@var{collection} must be a list of strings or symbols, an alist, an -obarray, a hash table, or a function that implements a virtual set of -strings (see below). - -Completion compares @var{string} against each of the permissible -completions specified by @var{collection}; if the beginning of the -permissible completion equals @var{string}, it matches. If no permissible -completions match, @code{try-completion} returns @code{nil}. If only -one permissible completion matches, and the match is exact, then -@code{try-completion} returns @code{t}. Otherwise, the value is the -longest initial sequence common to all the permissible completions that -match. - -If @var{collection} is an alist (@pxref{Association Lists}), the -permissible completions are the elements of the alist that are either -strings, symbols, or conses whose @sc{car} is a string or symbol. -Symbols are converted to strings using @code{symbol-name}. Other -elements of the alist are ignored. (Remember that in Emacs Lisp, the -elements of alists do not @emph{have} to be conses.) In particular, a -list of strings or symbols is allowed, even though we usually do not -think of such lists as alists. - -@cindex obarray in completion -If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. The -global variable @code{obarray} holds an obarray containing the names of -all interned Lisp symbols. - -Note that the only valid way to make a new obarray is to create it -empty and then add symbols to it one by one using @code{intern}. -Also, you cannot intern a given symbol in more than one obarray. - -If @var{collection} is a hash table, then the keys that are strings -are the possible completions. Other keys are ignored. - -You can also use a symbol that is a function as @var{collection}. Then -the function is solely responsible for performing completion; -@code{try-completion} returns whatever this function returns. The -function is called with three arguments: @var{string}, @var{predicate} -and @code{nil}. (The reason for the third argument is so that the same -function can be used in @code{all-completions} and do the appropriate -thing in either case.) @xref{Programmed Completion}. - -If the argument @var{predicate} is non-@code{nil}, then it must be a -function of one argument, unless @var{collection} is a hash table, in -which case it should be a function of two arguments. It is used to -test each possible match, and the match is accepted only if -@var{predicate} returns non-@code{nil}. The argument given to -@var{predicate} is either a string or a cons cell (the @sc{car} of -which is a string) from the alist, or a symbol (@emph{not} a symbol -name) from the obarray. If @var{collection} is a hash table, -@var{predicate} is called with two arguments, the string key and the -associated value. - -In addition, to be acceptable, a completion must also match all the -regular expressions in @code{completion-regexp-list}. (Unless -@var{collection} is a function, in which case that function has to -handle @code{completion-regexp-list} itself.) - -In the first of the following examples, the string @samp{foo} is -matched by three of the alist @sc{car}s. All of the matches begin with -the characters @samp{fooba}, so that is the result. In the second -example, there is only one possible match, and it is exact, so the value -is @code{t}. - -@smallexample -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - @result{} "fooba" -@end group - -@group -(try-completion "foo" '(("barfoo" 2) ("foo" 3))) - @result{} t -@end group -@end smallexample - -In the following example, numerous symbols begin with the characters -@samp{forw}, and all of them begin with the word @samp{forward}. In -most of the symbols, this is followed with a @samp{-}, but not in all, -so no more than @samp{forward} can be completed. - -@smallexample -@group -(try-completion "forw" obarray) - @result{} "forward" -@end group -@end smallexample - -Finally, in the following example, only two of the three possible -matches pass the predicate @code{test} (the string @samp{foobaz} is -too short). Both of those begin with the string @samp{foobar}. - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} "foobar" -@end group -@end smallexample -@end defun - -@defun all-completions string collection &optional predicate nospace -This function returns a list of all possible completions of -@var{string}. The arguments to this function (aside from -@var{nospace}) are the same as those of @code{try-completion}. Also, -this function uses @code{completion-regexp-list} in the same way that -@code{try-completion} does. The optional argument @var{nospace} only -matters if @var{string} is the empty string. In that case, if -@var{nospace} is non-@code{nil}, completions that start with a space -are ignored. - -If @var{collection} is a function, it is called with three arguments: -@var{string}, @var{predicate} and @code{t}; then @code{all-completions} -returns whatever the function returns. @xref{Programmed Completion}. - -Here is an example, using the function @code{test} shown in the -example for @code{try-completion}: - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group - -@group -(all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} ("foobar1" "foobar2") -@end group -@end smallexample -@end defun - -@defun test-completion string collection &optional predicate -@anchor{Definition of test-completion} -This function returns non-@code{nil} if @var{string} is a valid -completion possibility specified by @var{collection} and -@var{predicate}. The arguments are the same as in -@code{try-completion}. For instance, if @var{collection} is a list of -strings, this is true if @var{string} appears in the list and -@var{predicate} is satisfied. - -This function uses @code{completion-regexp-list} in the same -way that @code{try-completion} does. - -If @var{predicate} is non-@code{nil} and if @var{collection} contains -several strings that are equal to each other, as determined by -@code{compare-strings} according to @code{completion-ignore-case}, -then @var{predicate} should accept either all or none of them. -Otherwise, the return value of @code{test-completion} is essentially -unpredictable. - -If @var{collection} is a function, it is called with three arguments, -the values @var{string}, @var{predicate} and @code{lambda}; whatever -it returns, @code{test-completion} returns in turn. -@end defun - -@defvar completion-ignore-case -If the value of this variable is non-@code{nil}, Emacs does not -consider case significant in completion. Note, however, that this -variable is overridden by @code{read-file-name-completion-ignore-case} -within @code{read-file-name} (@pxref{Reading File Names}), and by -@code{read-buffer-completion-ignore-case} within @code{read-buffer} -(@pxref{High-Level Completion}). -@end defvar - -@defvar completion-regexp-list -This is a list of regular expressions. The completion functions only -consider a completion acceptable if it matches all regular expressions -in this list, with @code{case-fold-search} (@pxref{Searching and Case}) -bound to the value of @code{completion-ignore-case}. -@end defvar - -@defmac lazy-completion-table var fun -This macro provides a way to initialize the variable @var{var} as a -collection for completion in a lazy way, not computing its actual -contents until they are first needed. You use this macro to produce a -value that you store in @var{var}. The actual computation of the -proper value is done the first time you do completion using @var{var}. -It is done by calling @var{fun} with no arguments. The -value @var{fun} returns becomes the permanent value of @var{var}. - -Here is an example of use: - -@smallexample -(defvar foo (lazy-completion-table foo make-my-alist)) -@end smallexample -@end defmac - -@node Minibuffer Completion -@subsection Completion and the Minibuffer -@cindex minibuffer completion -@cindex reading from minibuffer with completion - - This section describes the basic interface for reading from the -minibuffer with completion. - -@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method -This function reads a string in the minibuffer, assisting the user by -providing completion. It activates the minibuffer with prompt -@var{prompt}, which must be a string. - -The actual completion is done by passing @var{collection} and -@var{predicate} to the function @code{try-completion}. This happens -in certain commands bound in the local keymaps used for completion. -Some of these commands also call @code{test-completion}. Thus, if -@var{predicate} is non-@code{nil}, it should be compatible with -@var{collection} and @code{completion-ignore-case}. @xref{Definition -of test-completion}. - -The value of the optional argument @var{require-match} determines how -the user may exit the minibuffer: - -@itemize @bullet -@item -If @code{nil}, the usual minibuffer exit commands work regardless of -the input in the minibuffer. - -@item -If @code{t}, the usual minibuffer exit commands won't exit unless the -input completes to an element of @var{collection}. - -@item -If @code{confirm}, the user can exit with any input, but is asked for -confirmation if the input is not an element of @var{collection}. - -@item -If @code{confirm-after-completion}, the user can exit with any input, -but is asked for confirmation if the preceding command was a -completion command (i.e., one of the commands in -@code{minibuffer-confirm-exit-commands}) and the resulting input is -not an element of @var{collection}. @xref{Completion Commands}. - -@item -Any other value of @var{require-match} behaves like @code{t}, except -that the exit commands won't exit if it performs completion. -@end itemize - -However, empty input is always permitted, regardless of the value of -@var{require-match}; in that case, @code{completing-read} returns the -first element of @var{default}, if it is a list; @code{""}, if -@var{default} is @code{nil}; or @var{default}. The string or strings -in @var{default} are also available to the user through the history -commands. - -The function @code{completing-read} uses -@code{minibuffer-local-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-must-match-map} if @var{require-match} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{hist} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. - -The argument @var{initial} is mostly deprecated; we recommend using a -non-@code{nil} value only in conjunction with specifying a cons cell -for @var{hist}. @xref{Initial Input}. For default input, use -@var{default} instead. - -If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current input method (@pxref{Input -Methods}) and the setting of @code{enable-multibyte-characters} -(@pxref{Text Representations}) from whichever buffer was current before -entering the minibuffer. - -If the built-in variable @code{completion-ignore-case} is -non-@code{nil}, completion ignores case when comparing the input -against the possible matches. @xref{Basic Completion}. In this mode -of operation, @var{predicate} must also ignore case, or you will get -surprising results. - -Here's an example of using @code{completing-read}: - -@smallexample -@group -(completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") -@end group - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} - ----------- Buffer: Minibuffer ---------- -Complete a foo: fo@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, -@code{completing-read} returns @code{barfoo}. - -The @code{completing-read} function binds variables to pass -information to the commands that actually do completion. -They are described in the following section. -@end defun - -@node Completion Commands -@subsection Minibuffer Commands that Do Completion - - This section describes the keymaps, commands and user options used -in the minibuffer to do completion. - -@defvar minibuffer-completion-table -The value of this variable is the collection used for completion in -the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as @code{minibuffer-complete-word}. -@end defvar - -@defvar minibuffer-completion-predicate -This variable's value is the predicate that @code{completing-read} -passes to @code{try-completion}. The variable is also used by the other -minibuffer completion functions. -@end defvar - -@defvar minibuffer-completion-confirm -This variable determines whether Emacs asks for confirmation before -exiting the minibuffer; @code{completing-read} binds this variable, -and the function @code{minibuffer-complete-and-exit} checks the value -before exiting. If the value is @code{nil}, confirmation is not -required. If the value is @code{confirm}, the user may exit with an -input that is not a valid completion alternative, but Emacs asks for -confirmation. If the value is @code{confirm-after-completion}, the -user may exit with an input that is not a valid completion -alternative, but Emacs asks for confirmation if the user submitted the -input right after any of the completion commands in -@code{minibuffer-confirm-exit-commands}. -@end defvar - -@defvar minibuffer-confirm-exit-commands -This variable holds a list of commands that cause Emacs to ask for -confirmation before exiting the minibuffer, if the @var{require-match} -argument to @code{completing-read} is @code{confirm-after-completion}. -The confirmation is requested if the user attempts to exit the -minibuffer immediately after calling any command in this list. -@end defvar - -@deffn Command minibuffer-complete-word -This function completes the minibuffer contents by at most a single -word. Even if the minibuffer contents have only one completion, -@code{minibuffer-complete-word} does not add any characters beyond the -first character that is not a word constituent. @xref{Syntax Tables}. -@end deffn - -@deffn Command minibuffer-complete -This function completes the minibuffer contents as far as possible. -@end deffn - -@deffn Command minibuffer-complete-and-exit -This function completes the minibuffer contents, and exits if -confirmation is not required, i.e., if -@code{minibuffer-completion-confirm} is @code{nil}. If confirmation -@emph{is} required, it is given by repeating this command -immediately---the command is programmed to work without confirmation -when run twice in succession. -@end deffn - -@deffn Command minibuffer-completion-help -This function creates a list of the possible completions of the -current minibuffer contents. It works by calling @code{all-completions} -using the value of the variable @code{minibuffer-completion-table} as -the @var{collection} argument, and the value of -@code{minibuffer-completion-predicate} as the @var{predicate} argument. -The list of completions is displayed as text in a buffer named -@samp{*Completions*}. -@end deffn - -@defun display-completion-list completions &optional common-substring -This function displays @var{completions} to the stream in -@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more -information about streams.) The argument @var{completions} is normally -a list of completions just returned by @code{all-completions}, but it -does not have to be. Each element may be a symbol or a string, either -of which is simply printed. It can also be a list of two strings, -which is printed as if the strings were concatenated. The first of -the two strings is the actual completion, the second string serves as -annotation. - -The argument @var{common-substring} is the prefix that is common to -all the completions. With normal Emacs completion, it is usually the -same as the string that was completed. @code{display-completion-list} -uses this to highlight text in the completion list for better visual -feedback. This is not needed in the minibuffer; for minibuffer -completion, you can pass @code{nil}. - -This function is called by @code{minibuffer-completion-help}. The -most common way to use it is together with -@code{with-output-to-temp-buffer}, like this: - -@example -(with-output-to-temp-buffer "*Completions*" - (display-completion-list - (all-completions (buffer-string) my-alist) - (buffer-string))) -@end example -@end defun - -@defopt completion-auto-help -If this variable is non-@code{nil}, the completion commands -automatically display a list of possible completions whenever nothing -can be completed because the next character is not uniquely determined. -@end defopt - -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map} -(@pxref{Definition of minibuffer-local-map}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} - -@item @kbd{C-j} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map}. -@end defvar - -@defvar minibuffer-local-filename-completion-map -This is like @code{minibuffer-local-completion-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. -@end defvar - -@defvar minibuffer-local-filename-must-match-map -This is like @code{minibuffer-local-must-match-map} -except that it does not bind @key{SPC}. This keymap is used by the -function @code{read-file-name}. -@end defvar - -@node High-Level Completion -@subsection High-Level Completion Functions - - This section describes the higher-level convenient functions for -reading certain sorts of names with completion. - - In most cases, you should not call these functions in the middle of a -Lisp function. When possible, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} -specification. @xref{Defining Commands}. - -@defun read-buffer prompt &optional default require-match -This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string, a list of strings, or a buffer. If it is -a list, the default value is the first element of this list. It is -mentioned in the prompt, but is not inserted in the minibuffer as -initial input. - -The argument @var{prompt} should be a string ending with a colon and a -space. If @var{default} is non-@code{nil}, the function inserts it in -@var{prompt} before the colon to follow the convention for reading from -the minibuffer with a default value (@pxref{Programming Tips}). - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{require-match} is @code{t}, -and the only buffer name starting with the given input is -@samp{minibuffer.texi}, so that name is the value. - -@example -(read-buffer "Buffer name: " "foo" t) -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Buffer name (default foo): @point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{The user types @kbd{minibuffer.t @key{RET}}.} - @result{} "minibuffer.texi" -@end group -@end example -@end defun - -@defopt read-buffer-function -This variable specifies how to read buffer names. For example, if you -set this variable to @code{iswitchb-read-buffer}, all Emacs commands -that call @code{read-buffer} to read a buffer name will actually use the -@code{iswitchb} package to read it. -@end defopt - -@defopt read-buffer-completion-ignore-case -If this variable is non-@code{nil}, @code{read-buffer} ignores case -when performing completion. -@end defopt - -@defun read-command prompt &optional default -This function reads the name of a command and returns it as a Lisp -symbol. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. Recall that a command is anything for -which @code{commandp} returns @code{t}, and a command name is a symbol -for which @code{commandp} returns @code{t}. @xref{Interactive Call}. - -The argument @var{default} specifies what to return if the user enters -null input. It can be a symbol, a string or a list of strings. If it -is a string, @code{read-command} interns it before returning it. -If it is a list, @code{read-command} returns the first element of this list. -If @var{default} is @code{nil}, that means no default has been -specified; then if the user enters null input, the return value is -@code{(intern "")}, that is, a symbol whose name is an empty string. - -@example -(read-command "Command name? ") - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Command name? ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user types @kbd{forward-c @key{RET}}, then this function returns -@code{forward-char}. - -The @code{read-command} function is a simplified interface to -@code{completing-read}. It uses the variable @code{obarray} so as to -complete in the set of extant Lisp symbols, and it uses the -@code{commandp} predicate so as to accept only command names: - -@cindex @code{commandp} example -@example -@group -(read-command @var{prompt}) -@equiv{} -(intern (completing-read @var{prompt} obarray - 'commandp t nil)) -@end group -@end example -@end defun - -@defun read-variable prompt &optional default -@anchor{Definition of read-variable} -This function reads the name of a user variable and returns it as a -symbol. - -The argument @var{default} specifies the default value to return if -the user enters null input. It can be a symbol, a string, or a list -of strings. If it is a string, @code{read-variable} interns it to -make the default value. If it is a list, @code{read-variable} interns -the first element. If @var{default} is @code{nil}, that means no -default has been specified; then if the user enters null input, the -return value is @code{(intern "")}. - -@example -@group -(read-variable "Variable name? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Variable name? @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} -returns @code{fill-prefix}. - -In general, @code{read-variable} is similar to @code{read-command}, -but uses the predicate @code{user-variable-p} instead of -@code{commandp}: - -@cindex @code{user-variable-p} example -@example -@group -(read-variable @var{prompt}) -@equiv{} -(intern - (completing-read @var{prompt} obarray - 'user-variable-p t nil)) -@end group -@end example -@end defun - -@deffn Command read-color &optional prompt convert allow-empty display -This function reads a string that is a color specification, either the -color's name or an RGB hex value such as @code{#RRRGGGBBB}. It -prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"}) -and provides completion for color names, but not for hex RGB values. -In addition to names of standard colors, completion candidates include -the foreground and background colors at point. - -Valid RGB values are described in @ref{Color Names}. - -The function's return value is the color name typed by the user in the -minibuffer. However, when called interactively or if the optional -argument @var{convert} is non-@code{nil}, it converts the name into -the color's RGB value and returns that value as a string. If an -invalid color name was specified, this function signals an error, -except that empty color names are allowed when @code{allow-empty} is -non-@code{nil} and the user enters null input. - -Interactively, or when @var{display} is non-@code{nil}, the return -value is also displayed in the echo area. -@end deffn - - See also the functions @code{read-coding-system} and -@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}, -and @code{read-input-method-name}, in @ref{Input Methods}. - -@node Reading File Names -@subsection Reading File Names -@cindex read file names -@cindex prompt for file name - - The high-level completion functions @code{read-file-name}, -@code{read-directory-name}, and @code{read-shell-command} are designed -to read file names, directory names, and shell commands respectively. -They provide special features, including automatic insertion of the -default directory. - -@defun read-file-name prompt &optional directory default require-match initial predicate -This function reads a file name in the minibuffer, prompting with -@var{prompt} and providing completion. - -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. - -@code{read-file-name} uses -@code{minibuffer-local-filename-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-filename-must-match-map} if @var{require-match} -is non-@code{nil}. @xref{Completion Commands}. - -The argument @var{directory} specifies the directory to use for -completion of relative file names. It should be an absolute directory -name. If @code{insert-default-directory} is non-@code{nil}, -@var{directory} is also inserted in the minibuffer as initial input. -It defaults to the current buffer's value of @code{default-directory}. - -@c Emacs 19 feature -If you specify @var{initial}, that is an initial file name to insert -in the buffer (after @var{directory}, if that is inserted). In this -case, point goes at the beginning of @var{initial}. The default for -@var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please -note:} we recommend using @var{default} rather than @var{initial} in -most cases. - -If @var{default} is non-@code{nil}, then the function returns -@var{default} if the user exits the minibuffer with the same non-empty -contents that @code{read-file-name} inserted initially. The initial -minibuffer contents are always non-empty if -@code{insert-default-directory} is non-@code{nil}, as it is by -default. @var{default} is not checked for validity, regardless of the -value of @var{require-match}. However, if @var{require-match} is -non-@code{nil}, the initial minibuffer contents should be a valid file -(or directory) name. Otherwise @code{read-file-name} attempts -completion if the user exits without any editing, and does not return -@var{default}. @var{default} is also available through the history -commands. - -If @var{default} is @code{nil}, @code{read-file-name} tries to find a -substitute default to use in its place, which it treats in exactly the -same way as if it had been specified explicitly. If @var{default} is -@code{nil}, but @var{initial} is non-@code{nil}, then the default is -the absolute file name obtained from @var{directory} and -@var{initial}. If both @var{default} and @var{initial} are @code{nil} -and the buffer is visiting a file, @code{read-file-name} uses the -absolute file name of that file as default. If the buffer is not -visiting a file, then there is no default. In that case, if the user -types @key{RET} without any editing, @code{read-file-name} simply -returns the pre-inserted contents of the minibuffer. - -If the user types @key{RET} in an empty minibuffer, this function -returns an empty string, regardless of the value of -@var{require-match}. This is, for instance, how the user can make the -current buffer visit no file using @code{M-x set-visited-file-name}. - -If @var{predicate} is non-@code{nil}, it specifies a function of one -argument that decides which file names are acceptable completion -possibilities. A file name is an acceptable value if @var{predicate} -returns non-@code{nil} for it. - -@code{read-file-name} does not automatically expand file names. You -must call @code{expand-file-name} yourself if an absolute file name is -required. - -Here is an example: - -@example -@group -(read-file-name "The file is ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -Typing @kbd{manual @key{TAB}} results in the following: - -@example -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/manual.texi@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@c Wordy to avoid overfull hbox in smallbook mode. -@noindent -If the user types @key{RET}, @code{read-file-name} returns the file name -as the string @code{"/gp/gnu/elisp/manual.texi"}. -@end defun - -@defvar read-file-name-function -If non-@code{nil}, this should be a function that accepts the same -arguments as @code{read-file-name}. When @code{read-file-name} is -called, it calls this function with the supplied arguments instead of -doing its usual work. -@end defvar - -@defopt read-file-name-completion-ignore-case -If this variable is non-@code{nil}, @code{read-file-name} ignores case -when performing completion. -@end defopt - -@defun read-directory-name prompt &optional directory default require-match initial -This function is like @code{read-file-name} but allows only directory -names as completion possibilities. - -If @var{default} is @code{nil} and @var{initial} is non-@code{nil}, -@code{read-directory-name} constructs a substitute default by -combining @var{directory} (or the current buffer's default directory -if @var{directory} is @code{nil}) and @var{initial}. If both -@var{default} and @var{initial} are @code{nil}, this function uses -@var{directory} as substitute default, or the current buffer's default -directory if @var{directory} is @code{nil}. -@end defun - -@defopt insert-default-directory -This variable is used by @code{read-file-name}, and thus, indirectly, -by most commands reading file names. (This includes all commands that -use the code letters @samp{f} or @samp{F} in their interactive form. -@xref{Interactive Codes,, Code Characters for interactive}.) Its -value controls whether @code{read-file-name} starts by placing the -name of the default directory in the minibuffer, plus the initial file -name if any. If the value of this variable is @code{nil}, then -@code{read-file-name} does not place any initial input in the -minibuffer (unless you specify initial input with the @var{initial} -argument). In that case, the default directory is still used for -completion of relative file names, but is not displayed. - -If this variable is @code{nil} and the initial minibuffer contents are -empty, the user may have to explicitly fetch the next history element -to access a default value. If the variable is non-@code{nil}, the -initial minibuffer contents are always non-empty and the user can -always request a default value by immediately typing @key{RET} in an -unedited minibuffer. (See above.) - -For example: - -@example -@group -;; @r{Here the minibuffer starts out with the default directory.} -(let ((insert-default-directory t)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is ~lewis/manual/@point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{Here the minibuffer is empty and only the prompt} -;; @r{appears on its line.} -(let ((insert-default-directory nil)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example -@end defopt - -@defun read-shell-command prompt &optional initial-contents hist &rest args -This function reads a shell command from the minibuffer, prompting -with @var{prompt} and providing intelligent completion. It completes -the first word of the command using candidates that are appropriate -for command names, and the rest of the command words as file names. - -This function uses @code{minibuffer-local-shell-command-map} as the -keymap for minibuffer input. The @var{hist} argument specifies the -history list to use; if is omitted or @code{nil}, it defaults to -@code{shell-command-history} (@pxref{Minibuffer History, -shell-command-history}). The optional argument @var{initial-contents} -specifies the initial content of the minibuffer (@pxref{Initial -Input}). The rest of @var{args}, if present, are used as the -@var{default} and @var{inherit-input-method} arguments in -@code{read-from-minibuffer} (@pxref{Text from Minibuffer}). -@end defun - -@defvar minibuffer-local-shell-command-map -This keymap is used by @code{read-shell-command} for completing -command and file names that are part of a shell command. -@end defvar - -@node Completion Styles -@subsection Completion Styles -@cindex completion styles - - A @dfn{completion style} is a set of rules for generating -completions. The user option @code{completion-styles} stores a list -of completion styles, which are represented by symbols. - -@defopt completion-styles -This is a list of completion style symbols to use for performing -completion. Each completion style in this list must be defined in -@code{completion-styles-alist}. -@end defopt - -@defvar completion-styles-alist -This variable stores a list of available completion styles. Each -element in the list must have the form @samp{(@var{name} -@var{try-completion} @var{all-completions})}. Here, @var{name} is the -name of the completion style (a symbol), which may be used in -@code{completion-styles-alist} to refer to this style. - -@var{try-completion} is the function that does the completion, and -@var{all-completions} is the function that lists the completions. -These functions should accept four arguments: @var{string}, -@var{collection}, @var{predicate}, and @var{point}. The @var{string}, -@var{collection}, and @var{predicate} arguments have the same meanings -as in @code{try-completion} (@pxref{Basic Completion}), and the -@var{point} argument is the position of point within @var{string}. -Each function should return a non-@code{nil} value if it performed its -job, and @code{nil} if it did not (e.g., if there is no way to -complete @var{string} according to the completion style). - -When the user calls a completion command, such as -@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks -for the first style listed in @code{completion-styles} and calls its -@var{try-completion} function. If this function returns @code{nil}, -Emacs moves to the next completion style listed in -@code{completion-styles} and calls its @var{try-completion} function, -and so on until one of the @var{try-completion} functions successfully -performs completion and returns a non-@code{nil} value. A similar -procedure is used for listing completions, via the -@var{all-completions} functions. -@end defvar - - By default, @code{completion-styles-alist} contains four pre-defined -completion styles: @code{basic}, a basic completion style; -@code{partial-completion}, which does partial completion (completing -each word in the input separately); @code{emacs22}, which performs -completion according to the rules used in Emacs 22; and -@code{emacs21}, which performs completion according to the rules used -in Emacs 21. - -@node Programmed Completion -@subsection Programmed Completion -@cindex programmed completion - - Sometimes it is not possible to create an alist or an obarray -containing all the intended possible completions. In such a case, you -can supply your own function to compute the completion of a given string. -This is called @dfn{programmed completion}. - - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function -@code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. - - The completion function should accept three arguments: - -@itemize @bullet -@item -The string to be completed. - -@item -The predicate function to filter possible matches, or @code{nil} if -none. Your function should call the predicate for each possible match, -and ignore the possible match if the predicate returns @code{nil}. - -@item -A flag specifying the type of operation. -@end itemize - - There are three flag values for three operations: - -@itemize @bullet -@item -@code{nil} specifies @code{try-completion}. The completion function -should return the completion of the specified string, or @code{t} if the -string is a unique and exact match already, or @code{nil} if the string -matches no possibility. - -If the string is an exact match for one possibility, but also matches -other longer possibilities, the function should return the string, not -@code{t}. - -@item -@code{t} specifies @code{all-completions}. The completion function -should return a list of all possible completions of the specified -string. - -@item -@code{lambda} specifies @code{test-completion}. The completion -function should return @code{t} if the specified string is an exact -match for some possibility; @code{nil} otherwise. -@end itemize - - It would be consistent and clean for completion functions to allow -lambda expressions (lists that are functions) as well as function -symbols as @var{collection}, but this is impossible. Lists as -completion tables already have other meanings, and it would be -unreliable to treat one differently just because it is also a possible -function. So you must arrange for any function you wish to use for -completion to be encapsulated in a symbol. - - Emacs uses programmed completion when completing file names. -@xref{File Name Completion}. - -@defun completion-table-dynamic function -This function is a convenient way to write a function that can act as -programmed completion function. The argument @var{function} should be -a function that takes one argument, a string, and returns an alist of -possible completions of it. You can think of -@code{completion-table-dynamic} as a transducer between that interface -and the interface for programmed completion functions. -@end defun - -@node Yes-or-No Queries -@section Yes-or-No Queries -@cindex asking the user questions -@cindex querying the user -@cindex yes-or-no questions - - This section describes functions used to ask the user a yes-or-no -question. The function @code{y-or-n-p} can be answered with a single -character; it is useful for questions where an inadvertent wrong answer -will not have serious consequences. @code{yes-or-no-p} is suitable for -more momentous questions, since it requires three or four characters to -answer. - - If either of these functions is called in a command that was invoked -using the mouse---more precisely, if @code{last-nonmenu-event} -(@pxref{Command Loop Info}) is either @code{nil} or a list---then it -uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use of the mouse or use of keyboard -input by binding @code{last-nonmenu-event} to a suitable value around -the call. - - Strictly speaking, @code{yes-or-no-p} uses the minibuffer and -@code{y-or-n-p} does not; but it seems best to describe them together. - -@defun y-or-n-p prompt -This function asks the user a question, expecting input in the echo -area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the -user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like -@kbd{C-g}, because the question might look like a minibuffer and for -that reason the user might try to use @kbd{C-]} to get out. The answer -is a single character, with no @key{RET} needed to terminate it. Upper -and lower case are equivalent. - -``Asking the question'' means printing @var{prompt} in the echo area, -followed by the string @w{@samp{(y or n) }}. If the input is not one of -the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, -@kbd{@key{DEL}}, or something that quits), the function responds -@samp{Please answer y or n.}, and repeats the request. - -This function does not actually use the minibuffer, since it does not -allow editing of the answer. It actually uses the echo area (@pxref{The -Echo Area}), which uses the same screen space as the minibuffer. The -cursor moves to the echo area while the question is being asked. - -The answers and their meanings, even @samp{y} and @samp{n}, are not -hardwired. The keymap @code{query-replace-map} specifies them. -@xref{Search and Replace}. - -In the following example, the user first types @kbd{q}, which is -invalid. At the next prompt the user types @kbd{y}. - -@smallexample -@group -(y-or-n-p "Do you need a lift? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears in the echo area:} -@end group - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{If the user then types @kbd{q}, the following appears:} - -@group ----------- Echo area ---------- -Please answer y or n. Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{When the user types a valid answer,} -;; @r{it is displayed after the question:} - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) y ----------- Echo area ---------- -@end group -@end smallexample - -@noindent -We show successive lines of echo area messages, but only one actually -appears on the screen at a time. -@end defun - -@defun y-or-n-p-with-timeout prompt seconds default-value -Like @code{y-or-n-p}, except that if the user fails to answer within -@var{seconds} seconds, this function stops waiting and returns -@var{default-value}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. -@end defun - -@defun yes-or-no-p prompt -This function asks the user a question, expecting input in the -minibuffer. It returns @code{t} if the user enters @samp{yes}, -@code{nil} if the user types @samp{no}. The user must type @key{RET} to -finalize the response. Upper and lower case are equivalent. - -@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, -followed by @w{@samp{(yes or no) }}. The user must type one of the -expected responses; otherwise, the function responds @samp{Please answer -yes or no.}, waits about two seconds and repeats the request. - -@code{yes-or-no-p} requires more work from the user than -@code{y-or-n-p} and is appropriate for more crucial decisions. - -Here is an example: - -@smallexample -@group -(yes-or-no-p "Do you really want to remove everything? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: minibuffer ---------- -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user first types @kbd{y @key{RET}}, which is invalid because this -function demands the entire word @samp{yes}, it responds by displaying -these prompts, with a brief pause between them: - -@smallexample -@group ----------- Buffer: minibuffer ---------- -Please answer yes or no. -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample -@end defun - -@node Multiple Queries -@section Asking Multiple Y-or-N Questions - - When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use -@code{map-y-or-n-p} to ask the collection of questions, rather than -asking each question individually. This gives the user certain -convenient facilities such as the ability to answer the whole series at -once. - -@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area -This function asks the user a series of questions, reading a -single-character answer in the echo area for each one. - -The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil} meaning stop asking questions. - -The argument @var{prompter} specifies how to ask each question. If -@var{prompter} is a string, the question text is computed like this: - -@example -(format @var{prompter} @var{object}) -@end example - -@noindent -where @var{object} is the next object to ask about (as obtained from -@var{list}). - -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t} meaning do act on this object (and -don't ask the user), or @code{nil} meaning ignore this object (and don't -ask the user). - -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. - -If the argument @var{help} is given, it should be a list of this form: - -@example -(@var{singular} @var{plural} @var{action}) -@end example - -@noindent -where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the -corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. - -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. - -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. - -You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the -answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -``acted upon,'' and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. - -Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while -prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it -does not do that. - -If @code{map-y-or-n-p} is called in a command that was invoked using the -mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command -Loop Info}) is either @code{nil} or a list---then it uses a dialog box -or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use of the mouse or use -of keyboard input by binding @code{last-nonmenu-event} to a suitable -value around the call. - -The return value of @code{map-y-or-n-p} is the number of objects acted on. -@end defun - -@node Reading a Password -@section Reading a Password -@cindex passwords, reading - - To read a password to pass to another program, you can use the -function @code{read-passwd}. - -@defun read-passwd prompt &optional confirm default -This function reads a password, prompting with @var{prompt}. It does -not echo the password as the user types it; instead, it echoes @samp{.} -for each character in the password. - -The optional argument @var{confirm}, if non-@code{nil}, says to read the -password twice and insist it must be the same both times. If it isn't -the same, the user has to type it over and over until the last two -times match. - -The optional argument @var{default} specifies the default password to -return if the user enters empty input. If @var{default} is @code{nil}, -then @code{read-passwd} returns the null string in that case. -@end defun - -@node Minibuffer Commands -@section Minibuffer Commands - - This section describes some commands meant for use in the -minibuffer. - -@deffn Command exit-minibuffer -This command exits the active minibuffer. It is normally bound to -keys in minibuffer local keymaps. -@end deffn - -@deffn Command self-insert-and-exit -This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-event}; -@pxref{Command Loop Info}). -@end deffn - -@deffn Command previous-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element. -@end deffn - -@deffn Command next-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th more recent history element. -@end deffn - -@deffn Command previous-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@deffn Command next-matching-history-element pattern n -This command replaces the minibuffer contents with the value of the -@var{n}th next (newer) history element that matches @var{pattern} (a -regular expression). -@end deffn - -@node Minibuffer Windows -@section Minibuffer Windows -@cindex minibuffer windows - - These functions access and select minibuffer windows -and test whether they are active. - -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if none is currently active. -@end defun - -@defun minibuffer-window &optional frame -@anchor{Definition of minibuffer-window} -This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that -frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. -@end defun - -@defun set-minibuffer-window window -This function specifies @var{window} as the minibuffer window to use. -This affects where the minibuffer is displayed if you put text in it -without invoking the usual minibuffer commands. It has no effect on -the usual minibuffer input functions because they all start by -choosing the minibuffer window according to the current frame. -@end defun - -@c Emacs 19 feature -@defun window-minibuffer-p &optional window -This function returns non-@code{nil} if @var{window} is a minibuffer -window. -@var{window} defaults to the selected window. -@end defun - -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. - -@defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window}, assumed to be -a minibuffer window, is currently active. -@end defun - -@node Minibuffer Contents -@section Minibuffer Contents - - These functions access the minibuffer prompt and contents. - -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-end -This function returns the current -position of the end of the minibuffer prompt, if a minibuffer is -current. Otherwise, it returns the minimum valid buffer position. -@end defun - -@defun minibuffer-prompt-width -This function returns the current display-width of the minibuffer -prompt, if a minibuffer is current. Otherwise, it returns zero. -@end defun - -@defun minibuffer-contents -This function returns the editable -contents of the minibuffer (that is, everything except the prompt) as -a string, if a minibuffer is current. Otherwise, it returns the -entire contents of the current buffer. -@end defun - -@defun minibuffer-contents-no-properties -This is like @code{minibuffer-contents}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun minibuffer-completion-contents -This is like @code{minibuffer-contents}, except that it returns only -the contents before point. That is the part that completion commands -operate on. @xref{Minibuffer Completion}. -@end defun - -@defun delete-minibuffer-contents -This function erases the editable contents of the minibuffer (that is, -everything except the prompt), if a minibuffer is current. Otherwise, -it erases the entire current buffer. -@end defun - -@node Recursive Mini -@section Recursive Minibuffers -@cindex recursive minibuffers - - These functions and variables deal with recursive minibuffers -(@pxref{Recursive Editing}): - -@defun minibuffer-depth -This function returns the current depth of activations of the -minibuffer, a nonnegative integer. If no minibuffers are active, it -returns zero. -@end defun - -@defopt enable-recursive-minibuffers -If this variable is non-@code{nil}, you can invoke commands (such as -@code{find-file}) that use minibuffers even while the minibuffer window -is active. Such invocation produces a recursive editing level for a new -minibuffer. The outer-level minibuffer is invisible while you are -editing the inner one. - -If this variable is @code{nil}, you cannot invoke minibuffer -commands when the minibuffer window is active, not even if you switch to -another window to do it. -@end defopt - -@c Emacs 19 feature -If a command name has a property @code{enable-recursive-minibuffers} -that is non-@code{nil}, then the command can use the minibuffer to read -arguments even if it is invoked from the minibuffer. A command can -also achieve this by binding @code{enable-recursive-minibuffers} -to @code{t} in the interactive declaration (@pxref{Using Interactive}). -The minibuffer command @code{next-matching-history-element} (normally -@kbd{M-s} in the minibuffer) does the latter. - -@node Minibuffer Misc -@section Minibuffer Miscellany - -@defun minibufferp &optional buffer-or-name -This function returns non-@code{nil} if @var{buffer-or-name} is a -minibuffer. If @var{buffer-or-name} is omitted, it tests the current -buffer. -@end defun - -@defvar minibuffer-setup-hook -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -@anchor{Definition of minibuffer-help-form} -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar - -@defvar minibuffer-scroll-window -@anchor{Definition of minibuffer-scroll-window} -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar - -@defun minibuffer-selected-window -This function returns the window which was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. -@end defun - -@defopt max-mini-window-height -This variable specifies the maximum height for resizing minibuffer -windows. If a float, it specifies a fraction of the height of the -frame. If an integer, it specifies a number of lines. -@end defopt - -@defun minibuffer-message string &rest args -This function displays @var{string} temporarily at the end of the -minibuffer text, for two seconds, or until the next input event -arrives, whichever comes first. If @var{args} is non-@code{nil}, the -actual message is obtained by passing @var{string} and @var{args} -through @code{format}. @xref{Formatting Strings}. -@end defun - -@ignore - arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218 -@end ignore diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi deleted file mode 100644 index 8313ef7fd70..00000000000 --- a/doc/lispref/modes.texi +++ /dev/null @@ -1,3287 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/modes -@node Modes, Documentation, Keymaps, Top -@chapter Major and Minor Modes -@cindex mode - - A @dfn{mode} is a set of definitions that customize Emacs and can be -turned on and off while you edit. There are two varieties of modes: -@dfn{major modes}, which are mutually exclusive and used for editing -particular kinds of text, and @dfn{minor modes}, which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how to -indicate them in the mode line, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see -@ref{Keymaps}, and @ref{Syntax Tables}. - -@menu -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: How a mode can provide a menu - of definitions in the buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. -@end menu - -@node Hooks -@section Hooks -@cindex hooks - - A @dfn{hook} is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. Emacs -provides hooks for the sake of customization. Most often, hooks are set -up in the init file (@pxref{Init File}), but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of standard hook variables. - -@cindex normal hook - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. By -convention, whenever the hook name ends in @samp{-hook}, that tells -you it is normal. We try to make all hooks normal, as much as -possible, so that you can use them in a uniform way. - - Every major mode function is supposed to run a normal hook called -the @dfn{mode hook} as the one of the last steps of initialization. -This makes it easy for a user to customize the behavior of the mode, -by overriding the buffer-local variable assignments already made by -the mode. Most minor mode functions also run a mode hook at the end. -But hooks are used in other contexts too. For example, the hook -@code{suspend-hook} runs just before Emacs suspends itself -(@pxref{Suspending Emacs}). - - The recommended way to add a hook function to a normal hook is by -calling @code{add-hook} (see below). The hook functions may be any of -the valid kinds of functions that @code{funcall} accepts (@pxref{What -Is a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. You can add hooks either -globally or buffer-locally with @code{add-hook}. - -@cindex abnormal hook - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an @dfn{abnormal hook}. That means the hook -functions are called with arguments, or their return values are used -in some way. The hook's documentation says how the functions are -called. You can use @code{add-hook} to add a function to an abnormal -hook, but you must write the function to follow the hook's calling -convention. - - By convention, abnormal hook names end in @samp{-functions} or -@samp{-hooks}. If the variable's name ends in @samp{-function}, then -its value is just a single function, not a list of functions. - -@menu -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. -@end menu - -@node Running Hooks -@subsection Running Hooks - - At the appropriate times, Emacs uses the @code{run-hooks} function -and the other functions below to run particular hooks. - -@defun run-hooks &rest hookvars -This function takes one or more normal hook variable names as -arguments, and runs each hook in turn. Each argument should be a -symbol that is a normal hook variable. These arguments are processed -in the order specified. - -If a hook variable has a non-@code{nil} value, that value should be a -list of functions. @code{run-hooks} calls all the functions, one by -one, with no arguments. - -The hook variable's value can also be a single function---either a -lambda expression or a symbol with a function definition---which -@code{run-hooks} calls. But this usage is obsolete. -@end defun - -@defun run-hook-with-args hook &rest args -This function is the way to run an abnormal hook and always call all -of the hook functions. It calls each of the hook functions one by -one, passing each of them the arguments @var{args}. -@end defun - -@defun run-hook-with-args-until-failure hook &rest args -This function is the way to run an abnormal hook until one of the hook -functions fails. It calls each of the hook functions, passing each of -them the arguments @var{args}, until some hook function returns -@code{nil}. It then stops and returns @code{nil}. If none of the -hook functions return @code{nil}, it returns a non-@code{nil} value. -@end defun - -@defun run-hook-with-args-until-success hook &rest args -This function is the way to run an abnormal hook until a hook function -succeeds. It calls each of the hook functions, passing each of them -the arguments @var{args}, until some hook function returns -non-@code{nil}. Then it stops, and returns whatever was returned by -the last hook function that was called. If all hook functions return -@code{nil}, it returns @code{nil} as well. -@end defun - -@node Setting Hooks -@subsection Setting Hooks - - Here's an example that uses a mode hook to turn on Auto Fill mode when -in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) -@end example - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. You can use it for abnormal hooks as well as for -normal hooks. @var{function} can be any Lisp function that can accept -the proper number of arguments for @var{hook}. For example, - -@example -(add-hook 'text-mode-hook 'my-text-hook-function) -@end example - -@noindent -adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. - -If @var{function} is already present in @var{hook} (comparing using -@code{equal}), then @code{add-hook} does not add it a second time. - -If @var{function} has a non-@code{nil} property -@code{permanent-local-hook}, then @code{kill-all-local-variables} (or -changing major modes) won't delete it from the hook variable's local -value. - -It is best to design your hook functions so that the order in which -they are executed does not matter. Any dependence on the order is -asking for trouble. However, the order is predictable: normally, -@var{function} goes at the front of the hook list, so it will be -executed first (barring another @code{add-hook} call). If the -optional argument @var{append} is non-@code{nil}, the new hook -function goes at the end of the hook list and will be executed last. - -@code{add-hook} can handle the cases where @var{hook} is void or its -value is a single function; it sets or changes the value to a list of -functions. - -If @var{local} is non-@code{nil}, that says to add @var{function} to -the buffer-local hook list instead of to the global hook list. If -needed, this makes the hook buffer-local and adds @code{t} to the -buffer-local value. The latter acts as a flag to run the hook -functions in the default value as well as in the local value. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable -@var{hook}. It compares @var{function} with elements of @var{hook} -using @code{equal}, so it works for both symbols and lambda -expressions. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the buffer-local hook list instead of from the global hook list. -@end defun - -@node Major Modes -@section Major Modes -@cindex major mode - - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has only one major mode at a time. For each major mode -there is a function to switch to that mode in the current buffer; its -name should end in @samp{-mode}. These functions work by setting -buffer-local variable bindings and other data associated with the -buffer, such as a local keymap. The effect lasts until you switch -to another major mode in the same buffer. - -@menu -* Major Mode Basics:: -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Example Major Modes:: Text mode and Lisp modes. -@end menu - -@node Major Mode Basics -@subsection Major Mode Basics -@cindex Fundamental mode - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific definitions or variable settings, so each -Emacs command behaves in its default manner, and each option is in its -default state. All other major modes redefine various keys and options. -For example, Lisp Interaction mode provides special key bindings for -@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB} -(@code{lisp-indent-line}), and other keys. - - When you need to write several editing commands to help you perform a -specialized editing task, creating a new major mode is usually a good -idea. In practice, writing a major mode is easy (in contrast to -writing a minor mode, which is often difficult). - - If the new mode is similar to an old one, it is often unwise to -modify the old one to serve two purposes, since it may become harder -to use and maintain. Instead, copy and rename an existing major mode -definition and alter the copy---or use the @code{define-derived-mode} -macro to define a @dfn{derived mode} (@pxref{Derived Modes}). For -example, Rmail Edit mode is a major mode that is very similar to Text -mode except that it provides two additional commands. Its definition -is distinct from that of Text mode, but uses that of Text mode. - - Even if the new mode is not an obvious derivative of any other mode, -it is convenient to use @code{define-derived-mode} with a @code{nil} -parent argument, since it automatically enforces the most important -coding conventions for you. - - For a very simple programming language major mode that handles -comments and fontification, you can use @code{define-generic-mode}. -@xref{Generic Modes}. - - Rmail Edit mode offers an example of changing the major mode -temporarily for a buffer, so it can be edited in a different way (with -ordinary Emacs commands rather than Rmail commands). In such cases, the -temporary major mode usually provides a command to switch back to the -buffer's usual mode (Rmail mode, in this case). You might be tempted to -present the temporary redefinitions inside a recursive edit and restore -the usual ones when the user exits; but this is a bad idea because it -constrains the user's options when it is done in more than one buffer: -recursive edits must be exited most-recently-entered first. Using an -alternative major mode avoids this limitation. @xref{Recursive -Editing}. - - The standard GNU Emacs Lisp library directory tree contains the code -for several major modes, in files such as @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and -@file{rmail.el}. They are found in various subdirectories of the -@file{lisp} directory. You can study these libraries to see how modes -are written. Text mode is perhaps the simplest major mode aside from -Fundamental mode. Rmail mode is a complicated and specialized mode. - -@node Major Mode Conventions -@subsection Major Mode Conventions -@cindex major mode conventions -@cindex conventions for writing major modes - - The code for existing major modes follows various coding conventions, -including conventions for local keymap and syntax table initialization, -global names, and hooks. Please follow these conventions when you -define a new major mode. (Fundamental mode is an exception to many -of these conventions, because its definition is to present the global -state of Emacs.) - - This list of conventions is only partial, because each major mode -should aim for consistency in general with other Emacs major modes. -This makes Emacs as a whole more coherent. It is impossible to list -here all the possible points where this issue might come up; if the -Emacs developers point out an area where your major mode deviates from -the usual conventions, please make it compatible. - -@itemize @bullet -@item -Define a command whose name ends in @samp{-mode}, with no arguments, -that switches to the new mode in the current buffer. This command -should set up the keymap, syntax table, and buffer-local variables in an -existing buffer, without changing the buffer's contents. - -@item -Write a documentation string for this command that describes the -special commands available in this mode. @kbd{C-h m} -(@code{describe-mode}) in your mode will display this string. - -The documentation string may include the special documentation -substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and -@samp{\<@var{keymap}>}, which enable the documentation to adapt -automatically to the user's own key bindings. @xref{Keys in -Documentation}. - -@item -The major mode command should start by calling -@code{kill-all-local-variables}. This runs the normal hook -@code{change-major-mode-hook}, then gets rid of the buffer-local -variables of the major mode previously in effect. @xref{Creating -Buffer-Local}. - -@item -The major mode command should set the variable @code{major-mode} to the -major mode command symbol. This is how @code{describe-mode} discovers -which documentation to print. - -@item -The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, usually a string (but see @ref{Mode Line -Data}, for other possible forms). The name of the mode appears -in the mode line. - -@item -@cindex functions in modes -Since all global names are in the same name space, all the global -variables, constants, and functions that are part of the mode should -have names that start with the major mode name (or with an abbreviation -of it if the name is long). @xref{Coding Conventions}. - -@item -In a major mode for editing some kind of structured text, such as a -programming language, indentation of text according to structure is -probably useful. So the mode should set @code{indent-line-function} -to a suitable function, and probably customize other variables -for indentation. - -@item -@cindex keymaps in modes -The major mode should usually have its own keymap, which is used as the -local keymap in all buffers in that mode. The major mode command should -call @code{use-local-map} to install this local map. @xref{Active -Keymaps}, for more information. - -This keymap should be stored permanently in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -The key sequences bound in a major mode keymap should usually start with -@kbd{C-c}, followed by a control character, a digit, or @kbd{@{}, -@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation -characters are reserved for minor modes, and ordinary letters are -reserved for users. - -A major mode can also rebind the keys @kbd{M-n}, @kbd{M-p} and -@kbd{M-s}. The bindings for @kbd{M-n} and @kbd{M-p} should normally -be some kind of ``moving forward and backward,'' but this does not -necessarily mean cursor motion. - -It is legitimate for a major mode to rebind a standard key sequence if -it provides a command that does ``the same job'' in a way better -suited to the text this mode is used for. For example, a major mode -for editing a programming language might redefine @kbd{C-M-a} to -``move to the beginning of a function'' in a way that works better for -that language. - -It is also legitimate for a major mode to rebind a standard key -sequence whose standard meaning is rarely useful in that mode. For -instance, minibuffer modes rebind @kbd{M-r}, whose standard meaning is -rarely of any use in the minibuffer. Major modes such as Dired or -Rmail that do not allow self-insertion of text can reasonably redefine -letters and other printing characters as special commands. - -@item -Major modes for editing text should not define @key{RET} to do -anything other than insert a newline. However, it is ok for -specialized modes for text that users don't directly edit, such as -Dired and Info modes, to redefine @key{RET} to do something entirely -different. - -@item -Major modes should not alter options that are primarily a matter of user -preference, such as whether Auto-Fill mode is enabled. Leave this to -each user to decide. However, a major mode should customize other -variables so that Auto-Fill mode will work usefully @emph{if} the user -decides to use it. - -@item -@cindex syntax tables in modes -The mode may have its own syntax table or may share one with other -related modes. If it has its own syntax table, it should store this in -a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@item -@cindex abbrev tables in modes -The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this -in a variable named @code{@var{modename}-mode-abbrev-table}. If the -major mode command defines any abbrevs itself, it should pass @code{t} -for the @var{system-flag} argument to @code{define-abbrev}. -@xref{Defining Abbrevs}. - -@item -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults} (@pxref{Font Lock Mode}). - -@item -The mode should specify how Imenu should find the definitions or -sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression}, for the two variables -@code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}, or for the variable -@code{imenu-create-index-function} (@pxref{Imenu}). - -@item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. - -@item -Use @code{defvar} or @code{defcustom} to set mode-related variables, so -that they are not reinitialized if they already have a value. (Such -reinitialization could discard customizations made by the user.) - -@item -@cindex buffer-local variables in modes -To make a buffer-local binding for an Emacs customization variable, use -@code{make-local-variable} in the major mode command, not -@code{make-variable-buffer-local}. The latter function would make the -variable local to every buffer in which it is subsequently set, which -would affect buffers that do not use this mode. It is undesirable for a -mode to have such global effects. @xref{Buffer-Local Variables}. - -With rare exceptions, the only reasonable way to use -@code{make-variable-buffer-local} in a Lisp package is for a variable -which is used only within that package. Using it on a variable used by -other packages would interfere with them. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a normal @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The very last thing the major mode command -should do is to call @code{run-mode-hooks}. This runs the mode hook, -and then runs the normal hook @code{after-change-major-mode-hook}. -@xref{Mode Hooks}. - -@item -The major mode command may start by calling some other major mode -command (called the @dfn{parent mode}) and then alter some of its -settings. A mode that does this is called a @dfn{derived mode}. The -recommended way to define one is to use the @code{define-derived-mode} -macro, but this is not required. Such a mode should call the parent -mode command inside a @code{delay-mode-hooks} form. (Using -@code{define-derived-mode} does this automatically.) @xref{Derived -Modes}, and @ref{Mode Hooks}. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, this mode can set up a buffer-local -value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}). - -@item -If this mode is appropriate only for specially-prepared text, then the -major mode command symbol should have a property named @code{mode-class} -with value @code{special}, put on as follows: - -@kindex mode-class @r{(property)} -@cindex @code{special} -@example -(put 'funny-mode 'mode-class 'special) -@end example - -@noindent -This tells Emacs that new buffers created while the current buffer is -in Funny mode should not inherit Funny mode, in case -@code{default-major-mode} is @code{nil}. Modes such as Dired, Rmail, -and Buffer List use this feature. - -The @code{define-derived-mode} macro automatically marks the derived -mode as special if the parent mode is special. The special mode -@code{special-mode} provides a convenient parent for other special -modes to inherit from; it sets @code{buffer-read-only} to @code{t}, -and does nothing else. - -@item -If you want to make the new mode the default for files with certain -recognizable names, add an element to @code{auto-mode-alist} to select -the mode for those file names (@pxref{Auto Major Mode}). If you -define the mode command to autoload, you should add this element in -the same file that calls @code{autoload}. If you use an autoload -cookie for the mode command, you can also use an autoload cookie for -the form that adds the element (@pxref{autoload cookie}). If you do -not autoload the mode command, it is sufficient to add the element in -the file that contains the mode definition. - -@item -In the comments that document the file, you should provide a sample -@code{autoload} form and an example of how to add to -@code{auto-mode-alist}, that users can include in their init files -(@pxref{Init File}). - -@item -@cindex mode loading -The top-level forms in the file defining the mode should be written so -that they may be evaluated more than once without adverse consequences. -Even if you never load the file more than once, someone else will. -@end itemize - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode -@cindex major mode, automatic selection - - Based on information in the file name or in the file itself, Emacs -automatically selects a major mode for the new buffer when a file is -visited. It also processes local variables specified in the file text. - -@deffn Command fundamental-mode - Fundamental mode is a major mode that is not specialized for anything -in particular. Other major modes are defined in effect by comparison -with this one---their definitions say what to change, starting from -Fundamental mode. The @code{fundamental-mode} function does @emph{not} -run any mode hooks; you're not supposed to customize it. (If you want Emacs -to behave differently in Fundamental mode, change the @emph{global} -state of Emacs.) -@end deffn - -@deffn Command normal-mode &optional find-file -This function establishes the proper major mode and buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File Local Variables}). - -If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, -@code{normal-mode} assumes that the @code{find-file} function is calling -it. In this case, it may process local variables in the @samp{-*-} -line or at the end of the file. The variable -@code{enable-local-variables} controls whether to do so. @xref{File -Variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, -for the syntax of the local variables section of a file. - -If you run @code{normal-mode} interactively, the argument -@var{find-file} is normally @code{nil}. In this case, -@code{normal-mode} unconditionally processes any file local variables. - -If @code{normal-mode} processes the local variables list and this list -specifies a major mode, that mode overrides any mode chosen by -@code{set-auto-mode}. If neither @code{set-auto-mode} nor -@code{hack-local-variables} specify a major mode, the buffer stays in -the major mode determined by @code{default-major-mode} (see below). - -@cindex file mode specification error -@code{normal-mode} uses @code{condition-case} around the call to the -major mode function, so errors are caught and reported as a @samp{File -mode specification error}, followed by the original error message. -@end deffn - -@defun set-auto-mode &optional keep-mode-if-same -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on -the @w{@samp{-*-}} line, on the @w{@samp{#!}} line (using -@code{interpreter-mode-alist}), on the text at the beginning of the -buffer (using @code{magic-mode-alist}), and finally on the visited -file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How -Major Modes are Chosen, emacs, The GNU Emacs Manual}. However, this -function does not look for the @samp{mode:} local variable near the -end of a file; the @code{hack-local-variables} function does that. -If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode} -does not check the @w{@samp{-*-}} line for a mode tag either. - -If @var{keep-mode-if-same} is non-@code{nil}, this function does not -call the mode command if the buffer is already in the proper major -mode. For instance, @code{set-visited-file-name} sets this to -@code{t} to avoid killing buffer local variables that the user may -have set. -@end defun - -@defopt default-major-mode -This variable holds the default major mode for new buffers. The -standard value is @code{fundamental-mode}. - -If the value of @code{default-major-mode} is @code{nil}, Emacs uses -the (previously) current buffer's major mode as the default major mode -of a new buffer. However, if that major mode symbol has a @code{mode-class} -property with value @code{special}, then it is not used for new buffers; -Fundamental mode is used instead. The modes that have this property are -those such as Dired and Rmail that are useful only with text that has -been specially prepared. -@end defopt - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the value of -@code{default-major-mode}; if that variable is @code{nil}, it uses the -current buffer's major mode (if that is suitable). As an exception, -if @var{buffer}'s name is @samp{*scratch*}, it sets the mode to -@code{initial-major-mode}. - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defopt initial-major-mode -@cindex @samp{*scratch*} -The value of this variable determines the major mode of the initial -@samp{*scratch*} buffer. The value should be a symbol that is a major -mode command. The default value is @code{lisp-interaction-mode}. -@end defopt - -@defvar interpreter-mode-alist -This variable specifies major modes to use for scripts that specify a -command interpreter in a @samp{#!} line. Its value is an alist with -elements of the form @code{(@var{interpreter} . @var{mode})}; for -example, @code{("perl" . perl-mode)} is one element present by -default. The element says to use mode @var{mode} if the file -specifies an interpreter which matches @var{interpreter}. -@end defvar - -@defvar magic-mode-alist -This variable's value is an alist with elements of the form -@code{(@var{regexp} . @var{function})}, where @var{regexp} is a -regular expression and @var{function} is a function or @code{nil}. -After visiting a file, @code{set-auto-mode} calls @var{function} if -the text at the beginning of the buffer matches @var{regexp} and -@var{function} is non-@code{nil}; if @var{function} is @code{nil}, -@code{auto-mode-alist} gets to decide the mode. -@end defvar - -@defvar magic-fallback-mode-alist -This works like @code{magic-mode-alist}, except that it is handled -only if @code{auto-mode-alist} does not specify a mode for this file. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions) and corresponding major mode commands. Usually, -the file name patterns test for suffixes, such as @samp{.el} and -@samp{.c}, but this need not be the case. An ordinary element of the -alist looks like @code{(@var{regexp} . @var{mode-function})}. - -For example, - -@smallexample -@group -(("\\`/tmp/fol/" . text-mode) - ("\\.texinfo\\'" . texinfo-mode) - ("\\.texi\\'" . texinfo-mode) -@end group -@group - ("\\.el\\'" . emacs-lisp-mode) - ("\\.c\\'" . c-mode) - ("\\.h\\'" . c-mode) - @dots{}) -@end group -@end smallexample - -When you visit a file whose expanded file name (@pxref{File Name -Expansion}), with version numbers and backup suffixes removed using -@code{file-name-sans-versions} (@pxref{File Name Components}), matches -a @var{regexp}, @code{set-auto-mode} calls the corresponding -@var{mode-function}. This feature enables Emacs to select the proper -major mode for most files. - -If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} -@var{function} t)}, then after calling @var{function}, Emacs searches -@code{auto-mode-alist} again for a match against the portion of the file -name that did not match before. This feature is useful for -uncompression packages: an entry of the form @code{("\\.gz\\'" -@var{function} t)} can uncompress the file and then put the uncompressed -file in the proper mode according to the name sans @samp{.gz}. - -Here is an example of how to prepend several pattern pairs to -@code{auto-mode-alist}. (You might use this sort of expression in your -init file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name (within directory) starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("/[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@node Mode Help -@subsection Getting Help about a Major Mode -@cindex mode help -@cindex help for major mode -@cindex documentation for major mode - - The @code{describe-mode} function is used to provide information -about major modes. It is normally called with @kbd{C-h m}. The -@code{describe-mode} function uses the value of @code{major-mode}, -which is why every major mode function needs to set the -@code{major-mode} variable. - -@deffn Command describe-mode -This function displays the documentation of the current major mode. - -The @code{describe-mode} function calls the @code{documentation} -function using the value of @code{major-mode} as an argument. Thus, it -displays the documentation string of the major mode function. -(@xref{Accessing Documentation}.) -@end deffn - -@defvar major-mode -This buffer-local variable holds the symbol for the current buffer's -major mode. This symbol should have a function definition that is the -command to switch to that major mode. The @code{describe-mode} -function uses the documentation string of the function as the -documentation of the major mode. -@end defvar - -@node Derived Modes -@subsection Defining Derived Modes -@cindex derived mode - - It's often useful to define a new major mode in terms of an existing -one. An easy way to do this is to use @code{define-derived-mode}. - -@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{} -This macro defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. @var{variant} and -@var{parent} should be unquoted symbols. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own sparse keymap, named -@code{@var{variant}-map}. @code{define-derived-mode} -makes the parent mode's keymap the parent of the new map, unless -@code{@var{variant}-map} is already set and already has a parent. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}, unless you override this using the -@code{:syntax-table} keyword (see below). @code{define-derived-mode} -makes the parent mode's syntax-table the parent of -@code{@var{variant}-syntax-table}, unless the latter is already set -and already has a parent different from the standard syntax table. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}, unless you override this using the -@code{:abbrev-table} keyword (see below). - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}. It -runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running the mode hooks. - -If @var{parent} has a non-@code{nil} @code{mode-class} symbol -property, then @code{define-derived-mode} sets the @code{mode-class} -property of @var{variant} to the same value. This ensures, for -example, that if @var{parent} is a special mode, then @var{variant} is -also a special mode (@pxref{Major Mode Conventions}). - -You can also specify @code{nil} for @var{parent}. This gives the new -mode no parent. Then @code{define-derived-mode} behaves as described -above, but, of course, omits all actions connected with @var{parent}. - -The argument @var{docstring} specifies the documentation string for -the new mode. @code{define-derived-mode} adds some general -information about the mode's hook, followed by the mode's keymap, at -the end of this docstring. If you omit @var{docstring}, -@code{define-derived-mode} generates a documentation string. - -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: - -@table @code -@item :syntax-table -You can use this to explicitly specify a syntax table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -syntax table as @var{parent}, or the standard syntax table if -@var{parent} is @code{nil}. (Note that this does @emph{not} follow -the convention used for non-keyword arguments that a @code{nil} value -is equivalent with not specifying the argument.) - -@item :abbrev-table -You can use this to explicitly specify an abbrev table for the new -mode. If you specify a @code{nil} value, the new mode uses the same -abbrev table as @var{parent}, or @code{fundamental-mode-abbrev-table} -if @var{parent} is @code{nil}. (Again, a @code{nil} value is -@emph{not} equivalent to not specifying this keyword.) - -@item :group -If this is specified, the value should be the customization group for -this mode. (Not all major modes have one.) Only the (still -experimental and unadvertised) command @code{customize-mode} currently -uses this. @code{define-derived-mode} does @emph{not} automatically -define the specified customization group. -@end table - -Here is a hypothetical example: - -@example -(define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. -\\@{hypertext-mode-map@}" - (setq case-fold-search nil)) - -(define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) -@end example - -Do not write an @code{interactive} spec in the definition; -@code{define-derived-mode} does that automatically. -@end defmac - -@node Generic Modes -@subsection Generic Modes -@cindex generic mode - - @dfn{Generic modes} are simple major modes with basic support for -comment syntax and Font Lock mode. To define a generic mode, use the -macro @code{define-generic-mode}. See the file @file{generic-x.el} -for some examples of the use of @code{define-generic-mode}. - -@defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring -This macro defines a generic mode command named @var{mode} (a symbol, -not quoted). The optional argument @var{docstring} is the -documentation for the mode command. If you do not supply it, -@code{define-generic-mode} generates one by default. - -The argument @var{comment-list} is a list in which each element is -either a character, a string of one or two characters, or a cons cell. -A character or a string is set up in the mode's syntax table as a -``comment starter.'' If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' -(Use @code{nil} for the latter if you want comments to end at the end -of the line.) Note that the syntax table mechanism has limitations -about what comment starters and enders are actually possible. -@xref{Syntax Tables}. - -The argument @var{keyword-list} is a list of keywords to highlight -with @code{font-lock-keyword-face}. Each keyword should be a string. -Meanwhile, @var{font-lock-list} is a list of additional expressions to -highlight. Each element of this list should have the same form as an -element of @code{font-lock-keywords}. @xref{Search-based -Fontification}. - -The argument @var{auto-mode-list} is a list of regular expressions to -add to the variable @code{auto-mode-alist}. They are added by the execution -of the @code{define-generic-mode} form, not by expanding the macro call. - -Finally, @var{function-list} is a list of functions for the mode -command to call for additional setup. It calls these functions just -before it runs the mode hook variable @code{@var{mode}-hook}. -@end defmac - -@node Mode Hooks -@subsection Mode Hooks - - Every major mode function should finish by running its mode hook and -the mode-independent normal hook @code{after-change-major-mode-hook}. -It does this by calling @code{run-mode-hooks}. If the major mode is a -derived mode, that is if it calls another major mode (the parent mode) -in its body, it should do this inside @code{delay-mode-hooks} so that -the parent won't run these hooks itself. Instead, the derived mode's -call to @code{run-mode-hooks} runs the parent's mode hook too. -@xref{Major Mode Conventions}. - - Emacs versions before Emacs 22 did not have @code{delay-mode-hooks}. -When user-implemented major modes have not been updated to use it, -they won't entirely follow these conventions: they may run the -parent's mode hook too early, or fail to run -@code{after-change-major-mode-hook}. If you encounter such a major -mode, please correct it to follow these conventions. - - When you defined a major mode using @code{define-derived-mode}, it -automatically makes sure these conventions are followed. If you -define a major mode ``by hand,'' not using @code{define-derived-mode}, -use the following functions to handle these conventions automatically. - -@defun run-mode-hooks &rest hookvars -Major modes should run their mode hook using this function. It is -similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{after-change-major-mode-hook}. - -When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. -Instead, it arranges for the next call to @code{run-mode-hooks} to run -them. -@end defun - -@defmac delay-mode-hooks body@dots{} -When one major mode command calls another, it should do so inside of -@code{delay-mode-hooks}. - -This macro executes @var{body}, but tells all @code{run-mode-hooks} -calls during the execution of @var{body} to delay running their hooks. -The hooks will actually run during the next call to -@code{run-mode-hooks} after the end of the @code{delay-mode-hooks} -construct. -@end defmac - -@defvar after-change-major-mode-hook -This is a normal hook run by @code{run-mode-hooks}. It is run at the -very end of every properly-written major mode function. -@end defvar - -@node Example Major Modes -@subsection Major Mode Examples - - Text mode is perhaps the simplest mode besides Fundamental mode. -Here are excerpts from @file{text-mode.el} that illustrate many of -the conventions listed above: - -@smallexample -@group -;; @r{Create the syntax table for this mode.} -(defvar text-mode-syntax-table - (let ((st (make-syntax-table))) - (modify-syntax-entry ?\" ". " st) - (modify-syntax-entry ?\\ ". " st) - ;; Add `p' so M-c on `hello' leads to `Hello', not `hello'. - (modify-syntax-entry ?' "w p" st) - st) - "Syntax table used while in `text-mode'.") -@end group - -;; @r{Create the keymap for this mode.} -@group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - (define-key map "\es" 'center-line) - (define-key map "\eS" 'center-paragraph) - map) - "Keymap for `text-mode'. -Many other modes, such as Mail mode, Outline mode -and Indented Text mode, inherit all the commands -defined in this map.") -@end group -@end smallexample - - Here is how the actual mode command is defined now: - -@smallexample -@group -(define-derived-mode text-mode nil "Text" - "Major mode for editing text written for humans to read. -In this mode, paragraphs are delimited only by blank or white lines. -You can thus get the full benefit of adaptive filling - (see the variable `adaptive-fill-mode'). -\\@{text-mode-map@} -Turning on Text mode runs the normal hook `text-mode-hook'." -@end group -@group - (make-local-variable 'text-mode-variant) - (setq text-mode-variant t) - ;; @r{These two lines are a feature added recently.} - (set (make-local-variable 'require-final-newline) - mode-require-final-newline) - (set (make-local-variable 'indent-line-function) 'indent-relative)) -@end group -@end smallexample - -@noindent -(The last line is redundant nowadays, since @code{indent-relative} is -the default value, and we'll delete it in a future version.) - - Here is how it was defined formerly, before -@code{define-derived-mode} existed: - -@smallexample -@group -;; @r{This isn't needed nowadays, since @code{define-derived-mode} does it.} -(defvar text-mode-abbrev-table nil - "Abbrev table used while in text mode.") -(define-abbrev-table 'text-mode-abbrev-table ()) -@end group - -@group -(defun text-mode () - "Major mode for editing text intended for humans to read... - Special commands: \\@{text-mode-map@} -@end group -@group -Turning on text-mode runs the hook `text-mode-hook'." - (interactive) - (kill-all-local-variables) - (use-local-map text-mode-map) -@end group -@group - (setq local-abbrev-table text-mode-abbrev-table) - (set-syntax-table text-mode-syntax-table) -@end group -@group - ;; @r{These four lines are absent from the current version} - ;; @r{not because this is done some other way, but rather} - ;; @r{because nowadays Text mode uses the normal definition of paragraphs.} - (make-local-variable 'paragraph-start) - (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter)) - (make-local-variable 'paragraph-separate) - (setq paragraph-separate paragraph-start) - (make-local-variable 'indent-line-function) - (setq indent-line-function 'indent-relative-maybe) -@end group -@group - (setq mode-name "Text") - (setq major-mode 'text-mode) - (run-mode-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} - ; @r{customize the mode with a hook.} -@end group -@end smallexample - -@cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp -Interaction mode) have more features than Text mode and the code is -correspondingly more complicated. Here are excerpts from -@file{lisp-mode.el} that illustrate how these modes are written. - -@cindex syntax table example -@smallexample -@group -;; @r{Create mode-specific table variables.} -(defvar lisp-mode-syntax-table nil "") -(defvar lisp-mode-abbrev-table nil "") -@end group - -@group -(defvar emacs-lisp-mode-syntax-table - (let ((table (make-syntax-table))) - (let ((i 0)) -@end group - -@group - ;; @r{Set syntax of chars up to @samp{0} to say they are} - ;; @r{part of symbol names but not words.} - ;; @r{(The digit @samp{0} is @code{48} in the @acronym{ASCII} character set.)} - (while (< i ?0) - (modify-syntax-entry i "_ " table) - (setq i (1+ i))) - ;; @r{@dots{} similar code follows for other character ranges.} -@end group -@group - ;; @r{Then set the syntax codes for characters that are special in Lisp.} - (modify-syntax-entry ? " " table) - (modify-syntax-entry ?\t " " table) - (modify-syntax-entry ?\f " " table) - (modify-syntax-entry ?\n "> " table) -@end group -@group - ;; @r{Give CR the same syntax as newline, for selective-display.} - (modify-syntax-entry ?\^m "> " table) - (modify-syntax-entry ?\; "< " table) - (modify-syntax-entry ?` "' " table) - (modify-syntax-entry ?' "' " table) - (modify-syntax-entry ?, "' " table) -@end group -@group - ;; @r{@dots{}likewise for many other characters@dots{}} - (modify-syntax-entry ?\( "() " table) - (modify-syntax-entry ?\) ")( " table) - (modify-syntax-entry ?\[ "(] " table) - (modify-syntax-entry ?\] ")[ " table)) - table)) -@end group -@group -;; @r{Create an abbrev table for lisp-mode.} -(define-abbrev-table 'lisp-mode-abbrev-table ()) -@end group -@end smallexample - - The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (lisp-syntax) - (when lisp-syntax - (set-syntax-table lisp-mode-syntax-table)) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{} -@end group -@end smallexample - - In Lisp and most programming languages, we want the paragraph -commands to treat only blank lines as paragraph separators. And the -modes should understand the Lisp conventions for comments. The rest of -@code{lisp-mode-variables} sets this up: - -@smallexample -@group - (make-local-variable 'paragraph-start) - (setq paragraph-start (concat page-delimiter "\\|$" )) - (make-local-variable 'paragraph-separate) - (setq paragraph-separate paragraph-start) - @dots{} -@end group -@group - (make-local-variable 'comment-indent-function) - (setq comment-indent-function 'lisp-comment-indent)) - @dots{} -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following code sets up the common commands: - -@smallexample -@group -(defvar shared-lisp-mode-map () - "Keymap for commands shared by all sorts of Lisp modes.") - -;; @r{Putting this @code{if} after the @code{defvar} is an older style.} -(if shared-lisp-mode-map - () - (setq shared-lisp-mode-map (make-sparse-keymap)) - (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp) - (define-key shared-lisp-mode-map "\177" - 'backward-delete-char-untabify)) -@end group -@end smallexample - -@noindent -And here is the code to set up the keymap for Lisp mode: - -@smallexample -@group -(defvar lisp-mode-map () - "Keymap for ordinary Lisp mode...") - -(if lisp-mode-map - () - (setq lisp-mode-map (make-sparse-keymap)) - (set-keymap-parent lisp-mode-map shared-lisp-mode-map) - (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun) - (define-key lisp-mode-map "\C-c\C-z" 'run-lisp)) -@end group -@end smallexample - - Finally, here is the complete major mode function definition for -Lisp mode. - -@smallexample -@group -(defun lisp-mode () - "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. -\\@{lisp-mode-map@} -Note that `run-lisp' may be used either to start an inferior Lisp job -or to switch back to an existing one. -@end group - -@group -Entry to this mode calls the value of `lisp-mode-hook' -if that value is non-nil." - (interactive) - (kill-all-local-variables) -@end group -@group - (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.} - (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds out what to describe.} - (setq mode-name "Lisp") ; @r{This goes into the mode line.} - (lisp-mode-variables t) ; @r{This defines various variables.} - (make-local-variable 'comment-start-skip) - (setq comment-start-skip - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") - (make-local-variable 'font-lock-keywords-case-fold-search) - (setq font-lock-keywords-case-fold-search t) -@end group -@group - (setq imenu-case-fold-search t) - (set-syntax-table lisp-mode-syntax-table) - (run-mode-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a} - ; @r{hook to customize the mode.} -@end group -@end smallexample - -@node Minor Modes -@section Minor Modes -@cindex minor mode - - A @dfn{minor mode} provides features that users may enable or disable -independently of the choice of major mode. Minor modes can be enabled -individually or in combination. Minor modes would be better named -``generally available, optional feature modes,'' except that such a name -would be unwieldy. - - A minor mode is not usually meant as a variation of a single major mode. -Usually they are general and can apply to many major modes. For -example, Auto Fill mode works with any major mode that permits text -insertion. To be general, a minor mode must be effectively independent -of the things major modes do. - - A minor mode is often much more difficult to implement than a major -mode. One reason is that you should be able to activate and deactivate -minor modes in any order. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - Often the biggest problem in implementing a minor mode is finding a -way to insert the necessary hook into the rest of Emacs. Minor mode -keymaps make this easier than it used to be. - -@defvar minor-mode-list -The value of this variable is a list of all minor mode commands. -@end defvar - -@menu -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. -@end menu - -@node Minor Mode Conventions -@subsection Conventions for Writing Minor Modes -@cindex minor mode conventions -@cindex conventions for writing minor modes - - There are conventions for writing minor modes just as there are for -major modes. Several of the major mode conventions apply to minor -modes as well: those regarding the name of the mode initialization -function, the names of global symbols, the use of a hook at the end of -the initialization function, and the use of keymaps and other tables. - - In addition, there are several conventions that are specific to -minor modes. (The easiest way to follow all the conventions is to use -the macro @code{define-minor-mode}; @ref{Defining Minor Modes}.) - -@itemize @bullet -@item -@cindex mode variable -Make a variable whose name ends in @samp{-mode} to control the minor -mode. We call this the @dfn{mode variable}. The minor mode command -should set this variable (@code{nil} to disable; anything else to -enable). - -If possible, implement the mode so that setting the variable -automatically enables or disables the mode. Then the minor mode command -does not need to do anything except set the variable. - -This variable is used in conjunction with the @code{minor-mode-alist} to -display the minor mode name in the mode line. It can also enable -or disable a minor mode keymap. Individual commands or hooks can also -check the variable's value. - -If you want the minor mode to be enabled separately in each buffer, -make the variable buffer-local. - -@item -Define a command whose name is the same as the mode variable. -Its job is to enable and disable the mode by setting the variable. - -The command should accept one optional argument. If the argument is -@code{nil}, it should toggle the mode (turn it on if it is off, and -off if it is on). It should turn the mode on if the argument is a -positive integer, the symbol @code{t}, or a list whose @sc{car} is one -of those. It should turn the mode off if the argument is a negative -integer or zero, the symbol @code{-}, or a list whose @sc{car} is a -negative integer or zero. The meaning of other arguments is not -specified. - -Here is an example taken from the definition of @code{transient-mark-mode}. -It shows the use of @code{transient-mark-mode} as a variable that enables or -disables the mode's behavior, and also shows the proper way to toggle, -enable or disable the minor mode based on the raw prefix argument value. - -@smallexample -@group -(setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) -@end group -@end smallexample - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Definition of minor-mode-alist}), if you want to indicate the -minor mode in the mode line. This element should be a list of the -following form: - -@smallexample -(@var{mode-variable} @var{string}) -@end smallexample - -Here @var{mode-variable} is the variable that controls enabling of the -minor mode, and @var{string} is a short string, starting with a space, -to represent the mode in the mode line. These strings must be short so -that there is room for several of them at once. - -When you add an element to @code{minor-mode-alist}, use @code{assq} to -check for an existing element, to avoid duplication. For example: - -@smallexample -@group -(unless (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) -@end group -@end smallexample - -@noindent -or like this, using @code{add-to-list} (@pxref{List Variables}): - -@smallexample -@group -(add-to-list 'minor-mode-alist '(leif-mode " Leif")) -@end group -@end smallexample -@end itemize - - Global minor modes distributed with Emacs should if possible support -enabling and disabling via Custom (@pxref{Customization}). To do this, -the first step is to define the mode variable with @code{defcustom}, and -specify @code{:type boolean}. - - If just setting the variable is not sufficient to enable the mode, you -should also specify a @code{:set} method which enables the mode by -invoking the mode command. Note in the variable's documentation string that -setting the variable other than via Custom may not take effect. - - Also mark the definition with an autoload cookie (@pxref{autoload cookie}), -and specify a @code{:require} so that customizing the variable will load -the library that defines the mode. This will copy suitable definitions -into @file{loaddefs.el} so that users can use @code{customize-option} to -enable the mode. For example: - -@smallexample -@group - -;;;###autoload -(defcustom msb-mode nil - "Toggle msb-mode. -Setting this variable directly does not take effect; -use either \\[customize] or the function `msb-mode'." - :set 'custom-set-minor-mode - :initialize 'custom-initialize-default - :version "20.4" - :type 'boolean - :group 'msb - :require 'msb) -@end group -@end smallexample - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}. - -@cindex @code{self-insert-command}, minor modes - One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing @code{self-insert-command} are limited to -special cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of @code{self-insert-command} for the -standard one. The editor command loop handles this function specially.) - -The key sequences bound in a minor mode should consist of @kbd{C-c} -followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other -punctuation characters are reserved for major modes.) - -@node Defining Minor Modes -@subsection Defining Minor Modes - - The macro @code{define-minor-mode} offers a convenient way of -implementing a mode in one self-contained definition. - -@defmac define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args@dots{} body@dots{} -This macro defines a new minor mode whose name is @var{mode} (a -symbol). It defines a command named @var{mode} to toggle the minor -mode, with @var{doc} as its documentation string. It also defines a -variable named @var{mode}, which is set to @code{t} or @code{nil} by -enabling or disabling the mode. The variable is initialized to -@var{init-value}. Except in unusual circumstances (see below), this -value must be @code{nil}. - -The string @var{lighter} says what to display in the mode line -when the mode is enabled; if it is @code{nil}, the mode is not displayed -in the mode line. - -The optional argument @var{keymap} specifies the keymap for the minor mode. -It can be a variable name, whose value is the keymap, or it can be an alist -specifying bindings in this form: - -@example -(@var{key-sequence} . @var{definition}) -@end example - -The above three arguments @var{init-value}, @var{lighter}, and -@var{keymap} can be (partially) omitted when @var{keyword-args} are -used. The @var{keyword-args} consist of keywords followed by -corresponding values. A few keywords have special meanings: - -@table @code -@item :group @var{group} -Custom group name to use in all generated @code{defcustom} forms. -Defaults to @var{mode} without the possible trailing @samp{-mode}. -@strong{Warning:} don't use this default group name unless you have -written a @code{defgroup} to define that group properly. @xref{Group -Definitions}. - -@item :global @var{global} -If non-@code{nil}, this specifies that the minor mode should be global -rather than buffer-local. It defaults to @code{nil}. - -One of the effects of making a minor mode global is that the -@var{mode} variable becomes a customization variable. Toggling it -through the Custom interface turns the mode on and off, and its value -can be saved for future Emacs sessions (@pxref{Saving -Customizations,,, emacs, The GNU Emacs Manual}. For the saved -variable to work, you should ensure that the @code{define-minor-mode} -form is evaluated each time Emacs starts; for packages that are not -part of Emacs, the easiest way to do this is to specify a -@code{:require} keyword. - -@item :init-value @var{init-value} -This is equivalent to specifying @var{init-value} positionally. - -@item :lighter @var{lighter} -This is equivalent to specifying @var{lighter} positionally. - -@item :keymap @var{keymap} -This is equivalent to specifying @var{keymap} positionally. -@end table - -Any other keyword arguments are passed directly to the -@code{defcustom} generated for the variable @var{mode}. - -The command named @var{mode} first performs the standard actions such -as setting the variable named @var{mode} and then executes the -@var{body} forms, if any. It finishes by running the mode hook -variable @code{@var{mode}-hook}. -@end defmac - - The initial value must be @code{nil} except in cases where (1) the -mode is preloaded in Emacs, or (2) it is painless for loading to -enable the mode even though the user did not request it. For -instance, if the mode has no effect unless something else is enabled, -and will always be loaded by that time, enabling it by default is -harmless. But these are unusual circumstances. Normally, the -initial value must be @code{nil}. - -@findex easy-mmode-define-minor-mode - The name @code{easy-mmode-define-minor-mode} is an alias -for this macro. - - Here is an example of using @code{define-minor-mode}: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - nil - ;; The indicator for the mode line. - " Hungry" - ;; The minor mode bindings. - '(("\C-\^?" . hungry-electric-delete)) - :group 'hunger) -@end smallexample - -@noindent -This defines a minor mode named ``Hungry mode,'' a command named -@code{hungry-mode} to toggle it, a variable named @code{hungry-mode} -which indicates whether the mode is enabled, and a variable named -@code{hungry-mode-map} which holds the keymap that is active when the -mode is enabled. It initializes the keymap with a key binding for -@kbd{C-@key{DEL}}. It puts the variable @code{hungry-mode} into -custom group @code{hunger}. There are no @var{body} forms---many -minor modes don't need any. - - Here's an equivalent way to write it: - -@smallexample -(define-minor-mode hungry-mode - "Toggle Hungry mode. -With no argument, this command toggles the mode. -Non-null prefix argument turns on the mode. -Null prefix argument turns off the mode. - -When Hungry mode is enabled, the control delete key -gobbles all preceding whitespace except the last. -See the command \\[hungry-electric-delete]." - ;; The initial value. - :init-value nil - ;; The indicator for the mode line. - :lighter " Hungry" - ;; The minor mode bindings. - :keymap - '(("\C-\^?" . hungry-electric-delete) - ("\C-\M-\^?" - . (lambda () - (interactive) - (hungry-electric-delete t)))) - :group 'hunger) -@end smallexample - -@defmac define-globalized-minor-mode global-mode mode turn-on keyword-args@dots{} -This defines a global toggle named @var{global-mode} whose meaning is -to enable or disable the buffer-local minor mode @var{mode} in all -buffers. To turn on the minor mode in a buffer, it uses the function -@var{turn-on}; to turn off the minor mode, it calls @code{mode} with -@minus{}1 as argument. - -Globally enabling the mode also affects buffers subsequently created -by visiting files, and buffers that use a major mode other than -Fundamental mode; but it does not detect the creation of a new buffer -in Fundamental mode. - -This defines the customization option @var{global-mode} (@pxref{Customization}), -which can be toggled in the Custom interface to turn the minor mode on -and off. As with @code{define-minor-mode}, you should ensure that the -@code{define-globalized-minor-mode} form is evaluated each time Emacs -starts, for example by providing a @code{:require} keyword. - -Use @code{:group @var{group}} in @var{keyword-args} to specify the -custom group for the mode variable of the global minor mode. -@end defmac - -@node Mode Line Format -@section Mode-Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) typically has a mode -line at the bottom, which displays status information about the buffer -displayed in the window. The mode line contains information about the -buffer, such as its name, associated file, depth of recursive editing, -and major and minor modes. A window can also have a @dfn{header -line}, which is much like the mode line but appears at the top of the -window. - - This section describes how to control the contents of the mode line -and header line. We include it in this chapter because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - -@menu -* Base: Mode Line Basics. Basic ideas of mode line control. -* Data: Mode Line Data. The data structure that controls the mode line. -* Top: Mode Line Top. The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. -@end menu - -@node Mode Line Basics -@subsection Mode Line Basics - - @code{mode-line-format} is a buffer-local variable that holds a -@dfn{mode line construct}, a kind of template, which controls what is -displayed on the mode line of the current buffer. The value of -@code{header-line-format} specifies the buffer's header line in the -same way. All windows for the same buffer use the same -@code{mode-line-format} and @code{header-line-format}. - - For efficiency, Emacs does not continuously recompute the mode -line and header line of a window. It does so when circumstances -appear to call for it---for instance, if you change the window -configuration, switch buffers, narrow or widen the buffer, scroll, or -change the buffer's modification status. If you modify any of the -variables referenced by @code{mode-line-format} (@pxref{Mode Line -Variables}), or any other variables and data structures that affect -how text is displayed (@pxref{Display}), you may want to force an -update of the mode line so as to display the new information or -display it in the new way. - -@defun force-mode-line-update &optional all -Force redisplay of the current buffer's mode line and header line. -The next redisplay will update the mode line and header line based on -the latest values of all relevant variables. With optional -non-@code{nil} @var{all}, force redisplay of all mode lines and header -lines. - -This function also forces recomputation of the menu bar menus -and the frame title. -@end defun - - The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines -appear in the face @code{mode-line-inactive} instead. @xref{Faces}. - -@node Mode Line Data -@subsection The Data Structure of the Mode Line -@cindex mode-line construct - - The mode-line contents are controlled by a data structure called a -@dfn{mode-line construct}, made up of lists, strings, symbols, and -numbers kept in buffer-local variables. Each data type has a specific -meaning for the mode-line appearance, as described below. The same -data structure is used for constructing frame titles (@pxref{Frame -Titles}) and header lines (@pxref{Header Lines}). - - A mode-line construct may be as simple as a fixed string of text, -but it usually specifies how to combine fixed strings with variables' -values to construct the text. Many of these variables are themselves -defined to have mode-line constructs as their values. - - Here are the meanings of various data types as mode-line constructs: - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode-line construct appears verbatim except for -@dfn{@code{%}-constructs} in it. These stand for substitution of -other data; see @ref{%-Constructs}. - -If parts of the string have @code{face} properties, they control -display of the text just as they would text in the buffer. Any -characters which have no @code{face} properties are displayed, by -default, in the face @code{mode-line} or @code{mode-line-inactive} -(@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). The -@code{help-echo} and @code{local-map} properties in @var{string} have -special meanings. @xref{Properties in Mode}. - -@item @var{symbol} -A symbol as a mode-line construct stands for its value. The value of -@var{symbol} is used as a mode-line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored, as is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -Unless @var{symbol} is marked as ``risky'' (i.e., it has a -non-@code{nil} @code{risky-local-variable} property), all text -properties specified in @var{symbol}'s value are ignored. This -includes the text properties of strings in @var{symbol}'s value, as -well as all @code{:eval} and @code{:propertize} forms in it. (The -reason for this is security: non-risky variables could be set -automatically from file variables without prompting the user.) - -@item (@var{string} @var{rest}@dots{}) -@itemx (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode-line construct. - -@item (:eval @var{form}) -A list whose first element is the symbol @code{:eval} says to evaluate -@var{form}, and use the result as a string to display. Make sure this -evaluation cannot load any files, as doing so could cause infinite -recursion. - -@item (:propertize @var{elt} @var{props}@dots{}) -A list whose first element is the symbol @code{:propertize} says to -process the mode-line construct @var{elt} recursively, then add the text -properties specified by @var{props} to the result. The argument -@var{props} should consist of zero or more pairs @var{text-property} -@var{value}. (This feature is new as of Emacs 22.1.) - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol that is not a keyword specifies -a conditional. Its meaning depends on the value of @var{symbol}. If -@var{symbol} has a non-@code{nil} value, the second element, -@var{then}, is processed recursively as a mode-line element. -Otherwise, the third element, @var{else}, is processed recursively. -You may omit @var{else}; then the mode-line element displays nothing -if the value of @var{symbol} is @code{nil} or void. - -@item (@var{width} @var{rest}@dots{}) -A list whose first element is an integer specifies truncation or -padding of the results of @var{rest}. The remaining elements -@var{rest} are processed recursively as mode-line constructs and -concatenated together. When @var{width} is positive, the result is -space filled on the right if its width is less than @var{width}. When -@var{width} is negative, the result is truncated on the right to -@minus{}@var{width} columns if its width exceeds @minus{}@var{width}. - -For example, the usual way to show what percentage of a buffer is above -the top of the window is to use a list like this: @code{(-3 "%p")}. -@end table - -@node Mode Line Top -@subsection The Top Level of Mode Line Control - - The variable in overall control of the mode line is -@code{mode-line-format}. - -@defopt mode-line-format -The value of this variable is a mode-line construct that controls the -contents of the mode-line. It is always buffer-local in all buffers. - -If you set this variable to @code{nil} in a buffer, that buffer does -not have a mode line. (A window that is just one line tall never -displays a mode line.) -@end defopt - - The default value of @code{mode-line-format} is designed to use the -values of other variables such as @code{mode-line-position} and -@code{mode-line-modes} (which in turn incorporates the values of the -variables @code{mode-name} and @code{minor-mode-alist}). Very few -modes need to alter @code{mode-line-format} itself. For most -purposes, it is sufficient to alter some of the variables that -@code{mode-line-format} either directly or indirectly refers to. - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - - Here is an example of a @code{mode-line-format} that might be -useful for @code{shell-mode}, since it contains the host name and default -directory. - -@example -@group -(setq mode-line-format - (list "-" - 'mode-line-mule-info - 'mode-line-modified - 'mode-line-frame-identification - "%b--" -@end group -@group - ;; @r{Note that this is evaluated while making the list.} - ;; @r{It makes a mode-line construct which is just a string.} - (getenv "HOST") -@end group - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - '(:eval (mode-line-mode-name)) - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]--" -@group - '(which-func-mode ("" which-func-format "--")) - '(line-number-mode "L%l--") - '(column-number-mode "C%c--") - '(-3 "%p") - "-%-")) -@end group -@end example - -@noindent -(The variables @code{line-number-mode}, @code{column-number-mode} -and @code{which-func-mode} enable particular minor modes; as usual, -these variable names are also the minor mode command names.) - -@node Mode Line Variables -@subsection Variables Used in the Mode Line - - This section describes variables incorporated by the standard value -of @code{mode-line-format} into the text of the mode line. There is -nothing inherently special about these variables; any other variables -could have the same effects on the mode line if -@code{mode-line-format}'s value were changed to use them. However, -various parts of Emacs set these variables on the understanding that -they will control parts of the mode line; therefore, practically -speaking, it is essential for the mode line to use them. - -@defvar mode-line-mule-info -This variable holds the value of the mode-line construct that displays -information about the language environment, buffer coding system, and -current input method. @xref{Non-ASCII Characters}. -@end defvar - -@defvar mode-line-modified -This variable holds the value of the mode-line construct that displays -whether the current buffer is modified. Its default value displays -@samp{**} if the buffer is modified, @samp{--} if the buffer is not -modified, @samp{%%} if the buffer is read only, and @samp{%*} if the -buffer is read only and modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-frame-identification -This variable identifies the current frame. Its default value -displays @code{" "} if you are using a window system which can show -multiple frames, or @code{"-%F "} on an ordinary terminal which shows -only one frame at a time. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. -Its default value displays the buffer name, padded with spaces to at -least 12 columns. -@end defvar - -@defopt mode-line-position -This variable indicates the position in the buffer. Its default value -displays the buffer percentage and, optionally, the buffer size, the -line number and the column number. -@end defopt - -@defvar vc-mode -The variable @code{vc-mode}, buffer-local in each buffer, records -whether the buffer's visited file is maintained with version control, -and, if so, which kind. Its value is a string that appears in the mode -line, or @code{nil} for no version control. -@end defvar - -@defopt mode-line-modes -This variable displays the buffer's major and minor modes. Its -default value also displays the recursive editing level, information -on the process status, and whether narrowing is in effect. -@end defopt - - The following three variables are used in @code{mode-line-modes}: - -@defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that -the mode name will appear in the mode line. The value does not have -to be a string, but can use any of the data types valid in a mode-line -construct (@pxref{Mode Line Data}). To compute the string that will -identify the mode name in the mode line, use @code{format-mode-line} -(@pxref{Emulating Mode Line}). -@end defvar - -@defvar mode-line-process -This buffer-local variable contains the mode-line information on process -status in modes used for communicating with subprocesses. It is -displayed immediately following the major mode name, with no intervening -space. For example, its value in the @samp{*shell*} buffer is -@code{(":%s")}, which allows the shell to display its status along -with the major mode as: @samp{(Shell:run)}. Normally this variable -is @code{nil}. -@end defvar - -@defvar minor-mode-alist -@anchor{Definition of minor-mode-alist} -This variable holds an association list whose elements specify how the -mode line should indicate that a minor mode is active. Each element of -the @code{minor-mode-alist} should be a two-element list: - -@example -(@var{minor-mode-variable} @var{mode-line-string}) -@end example - -More generally, @var{mode-line-string} can be any mode-line spec. It -appears in the mode line when the value of @var{minor-mode-variable} -is non-@code{nil}, and not otherwise. These strings should begin with -spaces so that they don't run together. Conventionally, the -@var{minor-mode-variable} for a specific mode is set to a -non-@code{nil} value when that minor mode is activated. - -@code{minor-mode-alist} itself is not buffer-local. Each variable -mentioned in the alist should be buffer-local if its minor mode can be -enabled separately in each buffer. -@end defvar - -@defvar global-mode-string -This variable holds a mode-line spec that, by default, appears in the -mode line just after the @code{which-func-mode} minor mode if set, -else after @code{mode-line-modes}. The command @code{display-time} -sets @code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time -and load information. - -The @samp{%M} construct substitutes the value of -@code{global-mode-string}, but that is obsolete, since the variable is -included in the mode line from @code{mode-line-format}. -@end defvar - - The variable @code{default-mode-line-format} is where -@code{mode-line-format} usually gets its value: - -@defvar default-mode-line-format -This variable holds the default @code{mode-line-format} for buffers -that do not override it. This is the same as @code{(default-value -'mode-line-format)}. - -Here is a simplified version of the default value of -@code{default-mode-line-format}. The real default value also -specifies addition of text properties. - -@example -@group -("-" - mode-line-mule-info - mode-line-modified - mode-line-frame-identification - mode-line-buffer-identification -@end group - " " - mode-line-position - (vc-mode vc-mode) - " " -@group - mode-line-modes - (which-func-mode ("" which-func-format "--")) - (global-mode-string ("--" global-mode-string)) - "-%-") -@end group -@end example -@end defvar - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - Strings used as mode-line constructs can use certain -@code{%}-constructs to substitute various kinds of data. Here is a -list of the defined @code{%}-constructs, and what they mean. In any -construct except @samp{%%}, you can add a decimal integer after the -@samp{%} to specify a minimum field width. If the width is less, the -field is padded with spaces to the right. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %c -The current column number of point. - -@item %e -When Emacs is nearly out of memory for Lisp objects, a brief message -saying so. Otherwise, this is empty. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The title (only on a window system) or the name of the selected frame. -@xref{Basic Parameters}. - -@item %i -The size of the accessible part of the current buffer; basically -@code{(- (point-max) (point-min))}. - -@item %I -Like @samp{%i}, but the size is printed in a more readable way by using -@samp{k} for 10^3, @samp{M} for 10^6, @samp{G} for 10^9, etc., to -abbreviate. - -@item %l -The current line number of point, counting within the accessible portion -of the buffer. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default -mode-line specification truncates this to three characters. - -@item %P -The percentage of the buffer text that is above the @strong{bottom} of -the window (which includes the text visible in the window, as well as -the text above the top), plus @samp{Top} if the top of the buffer is -visible on screen; or @samp{Bottom} or @samp{All}. - -@item %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %t -Whether the visited file is a text file or a binary file. This is a -meaningful distinction only on certain operating systems (@pxref{MS-DOS -File Types}). - -@item %z -The mnemonics of keyboard, terminal, and buffer coding systems. - -@item %Z -Like @samp{%z}, but including the end-of-line format. - -@item %* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{-} otherwise. @xref{Buffer Modification}. - -@item %+ -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@item %[ -An indication of the depth of recursive editing levels (not counting -minibuffer levels): one @samp{[} for each editing level. -@xref{Recursive Editing}. - -@item %] -One @samp{]} for each recursive editing level (not counting minibuffer -levels). - -@item %- -Dashes sufficient to fill the remainder of the mode line. - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. -@end table - -The following two @code{%}-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -@code{mode-name} and @code{global-mode-string}. - -@table @code -@item %m -The value of @code{mode-name}. - -@item %M -The value of @code{global-mode-string}. -@end table - -@node Properties in Mode -@subsection Properties in the Mode Line -@cindex text properties in the mode line - - Certain text properties are meaningful in the -mode line. The @code{face} property affects the appearance of text; the -@code{help-echo} property associates help strings with the text, and -@code{local-map} can make the text mouse-sensitive. - - There are four ways to specify text properties for text in the mode -line: - -@enumerate -@item -Put a string with a text property directly into the mode-line data -structure. - -@item -Put a text property on a mode-line %-construct such as @samp{%12b}; then -the expansion of the %-construct will have that same text property. - -@item -Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to -give @var{elt} a text property specified by @var{props}. - -@item -Use a list containing @code{:eval @var{form}} in the mode-line data -structure, and make @var{form} evaluate to a string that has a text -property. -@end enumerate - - You can use the @code{local-map} property to specify a keymap. This -keymap only takes real effect for mouse clicks; binding character keys -and function keys to it has no effect, since it is impossible to move -point into the mode line. - - When the mode line refers to a variable which does not have a -non-@code{nil} @code{risky-local-variable} property, any text -properties given or specified within that variable's values are -ignored. This is because such properties could otherwise specify -functions to be called, and those functions could come from file -local variables. - -@node Header Lines -@subsection Window Header Lines -@cindex header line (of a window) -@cindex window header line - - A window can have a @dfn{header line} at the -top, just as it can have a mode line at the bottom. The header line -feature works just like the mode-line feature, except that it's -controlled by different variables. - -@defvar header-line-format -This variable, local in every buffer, specifies how to display the -header line, for windows displaying the buffer. The format of the value -is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -@end defvar - -@defvar default-header-line-format -This variable holds the default @code{header-line-format} for buffers -that do not override it. This is the same as @code{(default-value -'header-line-format)}. - -It is normally @code{nil}, so that ordinary buffers have no header line. -@end defvar - - A window that is just one line tall never displays a header line. A -window that is two lines tall cannot display both a mode line and a -header line at once; if it has a mode line, then it does not display a -header line. - -@node Emulating Mode Line -@subsection Emulating Mode-Line Formatting - - You can use the function @code{format-mode-line} to compute -the text that would appear in a mode line or header line -based on a certain mode-line specification. - -@defun format-mode-line format &optional face window buffer -This function formats a line of text according to @var{format} as if -it were generating the mode line for @var{window}, but instead of -displaying the text in the mode line or the header line, it returns -the text as a string. The argument @var{window} defaults to the -selected window. If @var{buffer} is non-@code{nil}, all the -information used is taken from @var{buffer}; by default, it comes from -@var{window}'s buffer. - -The value string normally has text properties that correspond to the -faces, keymaps, etc., that the mode line would have. And any character -for which no @code{face} property is specified gets a default -value which is usually @var{face}. (If @var{face} is @code{t}, -that stands for either @code{mode-line} if @var{window} is selected, -otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or -omitted, that stands for no face property.) - -However, if @var{face} is an integer, the value has no text properties. - -For example, @code{(format-mode-line header-line-format)} returns the -text that would appear in the selected window's header line (@code{""} -if it has no header line). @code{(format-mode-line header-line-format -'header-line)} returns the same text, with each character -carrying the face that it will have in the header line itself. -@end defun - -@node Imenu -@section Imenu - -@cindex Imenu - @dfn{Imenu} is a feature that lets users select a definition or -section in the buffer, from a menu which lists all of them, to go -directly to that location in the buffer. Imenu works by constructing -a buffer index which lists the names and buffer positions of the -definitions, or other named portions of the buffer; then the user can -choose one of them and move point to it. Major modes can add a menu -bar item to use Imenu using @code{imenu-add-to-menubar}. - -@defun imenu-add-to-menubar name -This function defines a local menu bar item named @var{name} -to run Imenu. -@end defun - - The user-level commands for using Imenu are described in the Emacs -Manual (@pxref{Imenu,, Imenu, emacs, the Emacs Manual}). This section -explains how to customize Imenu's method of finding definitions or -buffer portions for a particular major mode. - - The usual and simplest way is to set the variable -@code{imenu-generic-expression}: - -@defvar imenu-generic-expression -This variable, if non-@code{nil}, is a list that specifies regular -expressions for finding definitions for Imenu. Simple elements of -@code{imenu-generic-expression} look like this: - -@example -(@var{menu-title} @var{regexp} @var{index}) -@end example - -Here, if @var{menu-title} is non-@code{nil}, it says that the matches -for this element should go in a submenu of the buffer index; -@var{menu-title} itself specifies the name for the submenu. If -@var{menu-title} is @code{nil}, the matches for this element go directly -in the top level of the buffer index. - -The second item in the list, @var{regexp}, is a regular expression -(@pxref{Regular Expressions}); anything in the buffer that it matches -is considered a definition, something to mention in the buffer index. -The third item, @var{index}, is a non-negative integer that indicates -which subexpression in @var{regexp} matches the definition's name. - -An element can also look like this: - -@example -(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{}) -@end example - -Each match for this element creates an index item, and when the index -item is selected by the user, it calls @var{function} with arguments -consisting of the item name, the buffer position, and @var{arguments}. - -For Emacs Lisp mode, @code{imenu-generic-expression} could look like -this: - -@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+] -@example -@group -((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Vars*" "^\\s-*(def\\(var\\|const\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2) -@end group -@group - ("*Types*" - "^\\s-*\ -(def\\(type\\|struct\\|class\\|ine-condition\\)\ -\\s-+\\([-A-Za-z0-9+]+\\)" 2)) -@end group -@end example - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-case-fold-search -This variable controls whether matching against the regular -expressions in the value of @code{imenu-generic-expression} is -case-sensitive: @code{t}, the default, means matching should ignore -case. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-syntax-alist -This variable is an alist of syntax table modifiers to use while -processing @code{imenu-generic-expression}, to override the syntax table -of the current buffer. Each element should have this form: - -@example -(@var{characters} . @var{syntax-description}) -@end example - -The @sc{car}, @var{characters}, can be either a character or a string. -The element says to give that character or characters the syntax -specified by @var{syntax-description}, which is passed to -@code{modify-syntax-entry} (@pxref{Syntax Table Functions}). - -This feature is typically used to give word syntax to characters which -normally have symbol syntax, and thus to simplify -@code{imenu-generic-expression} and speed up matching. -For example, Fortran mode uses it this way: - -@example -(setq imenu-syntax-alist '(("_$" . "w"))) -@end example - -The @code{imenu-generic-expression} regular expressions can then use -@samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this -technique may be inconvenient when the mode needs to limit the initial -character of a name to a smaller set of characters than are allowed in -the rest of a name. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - Another way to customize Imenu for a major mode is to set the -variables @code{imenu-prev-index-position-function} and -@code{imenu-extract-index-name-function}: - -@defvar imenu-prev-index-position-function -If this variable is non-@code{nil}, its value should be a function that -finds the next ``definition'' to put in the buffer index, scanning -backward in the buffer from point. It should return @code{nil} if it -doesn't find another ``definition'' before point. Otherwise it should -leave point at the place it finds a ``definition'' and return any -non-@code{nil} value. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@defvar imenu-extract-index-name-function -If this variable is non-@code{nil}, its value should be a function to -return the name for a definition, assuming point is in that definition -as the @code{imenu-prev-index-position-function} function would leave -it. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - - The last way to customize Imenu for a major mode is to set the -variable @code{imenu-create-index-function}: - -@defvar imenu-create-index-function -This variable specifies the function to use for creating a buffer -index. The function should take no arguments, and return an index -alist for the current buffer. It is called within -@code{save-excursion}, so where it leaves point makes no difference. - -The index alist can have three types of elements. Simple elements -look like this: - -@example -(@var{index-name} . @var{index-position}) -@end example - -Selecting a simple element has the effect of moving to position -@var{index-position} in the buffer. Special elements look like this: - -@example -(@var{index-name} @var{index-position} @var{function} @var{arguments}@dots{}) -@end example - -Selecting a special element performs: - -@example -(funcall @var{function} - @var{index-name} @var{index-position} @var{arguments}@dots{}) -@end example - -A nested sub-alist element looks like this: - -@example -(@var{menu-title} @var{sub-alist}) -@end example - -It creates the submenu @var{menu-title} specified by @var{sub-alist}. - -The default value of @code{imenu-create-index-function} is -@code{imenu-default-create-index-function}. This function calls the -value of @code{imenu-prev-index-position-function} and the value of -@code{imenu-extract-index-name-function} to produce the index alist. -However, if either of these two variables is @code{nil}, the default -function uses @code{imenu-generic-expression} instead. - -Setting this variable makes it buffer-local in the current buffer. -@end defvar - -@node Font Lock Mode -@section Font Lock Mode -@cindex Font Lock mode - - @dfn{Font Lock mode} is a feature that automatically attaches -@code{face} properties to certain parts of the buffer based on their -syntactic role. How it parses the buffer depends on the major mode; -most major modes define syntactic criteria for which faces to use in -which contexts. This section explains how to customize Font Lock for a -particular major mode. - - Font Lock mode finds text to highlight in two ways: through -syntactic parsing based on the syntax table, and through searching -(usually for regular expressions). Syntactic fontification happens -first; it finds comments and string constants and highlights them. -Search-based fontification happens second. - -@menu -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. -@end menu - -@node Font Lock Basics -@subsection Font Lock Basics - - There are several variables that control how Font Lock mode highlights -text. But major modes should not set any of these variables directly. -Instead, they should set @code{font-lock-defaults} as a buffer-local -variable. The value assigned to this variable is used, if and when Font -Lock mode is enabled, to set all the other variables. - -@defvar font-lock-defaults -This variable is set by major modes, as a buffer-local variable, to -specify how to fontify text in that mode. It automatically becomes -buffer-local when you set it. If its value is @code{nil}, Font-Lock -mode does no highlighting, and you can use the @samp{Faces} menu -(under @samp{Edit} and then @samp{Text Properties} in the menu bar) to -assign faces explicitly to text in the buffer. - -If non-@code{nil}, the value should look like this: - -@example -(@var{keywords} [@var{keywords-only} [@var{case-fold} - [@var{syntax-alist} [@var{syntax-begin} @var{other-vars}@dots{}]]]]) -@end example - -The first element, @var{keywords}, indirectly specifies the value of -@code{font-lock-keywords} which directs search-based fontification. -It can be a symbol, a variable or a function whose value is the list -to use for @code{font-lock-keywords}. It can also be a list of -several such symbols, one for each possible level of fontification. -The first symbol specifies the @samp{mode default} level of -fontification, the next symbol level 1 fontification, the next level 2, -and so on. The @samp{mode default} level is normally the same as level -1. It is used when @code{font-lock-maximum-decoration} has a @code{nil} -value. @xref{Levels of Font Lock}. - -The second element, @var{keywords-only}, specifies the value of the -variable @code{font-lock-keywords-only}. If this is omitted or -@code{nil}, syntactic fontification (of strings and comments) is also -performed. If this is non-@code{nil}, such fontification is not -performed. @xref{Syntactic Font Lock}. - -The third element, @var{case-fold}, specifies the value of -@code{font-lock-keywords-case-fold-search}. If it is non-@code{nil}, -Font Lock mode ignores case when searching as directed by -@code{font-lock-keywords}. - -If the fourth element, @var{syntax-alist}, is non-@code{nil}, it -should be a list of cons cells of the form @code{(@var{char-or-string} -. @var{string})}. These are used to set up a syntax table for -syntactic fontification (@pxref{Syntax Table Functions}). The -resulting syntax table is stored in @code{font-lock-syntax-table}. - -The fifth element, @var{syntax-begin}, specifies the value of -@code{font-lock-beginning-of-syntax-function}. We recommend setting -this variable to @code{nil} and using @code{syntax-begin-function} -instead. - -All the remaining elements (if any) are collectively called -@var{other-vars}. Each of these elements should have the form -@code{(@var{variable} . @var{value})}---which means, make -@var{variable} buffer-local and then set it to @var{value}. You can -use these @var{other-vars} to set other variables that affect -fontification, aside from those you can control with the first five -elements. @xref{Other Font Lock Variables}. -@end defvar - - If your mode fontifies text explicitly by adding -@code{font-lock-face} properties, it can specify @code{(nil t)} for -@code{font-lock-defaults} to turn off all automatic fontification. -However, this is not required; it is possible to fontify some things -using @code{font-lock-face} properties and set up automatic -fontification for other parts of the text. - -@node Search-based Fontification -@subsection Search-based Fontification - - The most important variable for customizing Font Lock mode is -@code{font-lock-keywords}. It specifies the search criteria for -search-based fontification. You should specify the value of this -variable with @var{keywords} in @code{font-lock-defaults}. - -@defvar font-lock-keywords -This variable's value is a list of the keywords to highlight. Be -careful when composing regular expressions for this list; a poorly -written pattern can dramatically slow things down! -@end defvar - - Each element of @code{font-lock-keywords} specifies how to find -certain cases of text, and how to highlight those cases. Font Lock mode -processes the elements of @code{font-lock-keywords} one by one, and for -each element, it finds and handles all matches. Ordinarily, once -part of the text has been fontified already, this cannot be overridden -by a subsequent match in the same text; but you can specify different -behavior using the @var{override} element of a @var{subexp-highlighter}. - - Each element of @code{font-lock-keywords} should have one of these -forms: - -@table @code -@item @var{regexp} -Highlight all matches for @var{regexp} using -@code{font-lock-keyword-face}. For example, - -@example -;; @r{Highlight occurrences of the word @samp{foo}} -;; @r{using @code{font-lock-keyword-face}.} -"\\" -@end example - -The function @code{regexp-opt} (@pxref{Regexp Functions}) is useful -for calculating optimal regular expressions to match a number of -different keywords. - -@item @var{function} -Find text by calling @var{function}, and highlight the matches -it finds using @code{font-lock-keyword-face}. - -When @var{function} is called, it receives one argument, the limit of -the search; it should begin searching at point, and not search beyond the -limit. It should return non-@code{nil} if it succeeds, and set the -match data to describe the match that was found. Returning @code{nil} -indicates failure of the search. - -Fontification will call @var{function} repeatedly with the same limit, -and with point where the previous invocation left it, until -@var{function} fails. On failure, @var{function} need not reset point -in any particular way. - -@item (@var{matcher} . @var{subexp}) -In this kind of element, @var{matcher} is either a regular -expression or a function, as described above. The @sc{cdr}, -@var{subexp}, specifies which subexpression of @var{matcher} should be -highlighted (instead of the entire text that @var{matcher} matched). - -@example -;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} -;; @r{using @code{font-lock-keyword-face}.} -("fu\\(bar\\)" . 1) -@end example - -If you use @code{regexp-opt} to produce the regular expression -@var{matcher}, you can use @code{regexp-opt-depth} (@pxref{Regexp -Functions}) to calculate the value for @var{subexp}. - -@item (@var{matcher} . @var{facespec}) -In this kind of element, @var{facespec} is an expression whose value -specifies the face to use for highlighting. In the simplest case, -@var{facespec} is a Lisp variable (a symbol) whose value is a face -name. - -@example -;; @r{Highlight occurrences of @samp{fubar},} -;; @r{using the face which is the value of @code{fubar-face}.} -("fubar" . fubar-face) -@end example - -However, @var{facespec} can also evaluate to a list of this form: - -@example -(face @var{face} @var{prop1} @var{val1} @var{prop2} @var{val2}@dots{}) -@end example - -@noindent -to specify the face @var{face} and various additional text properties -to put on the text that matches. If you do this, be sure to add the -other text property names that you set in this way to the value of -@code{font-lock-extra-managed-props} so that the properties will also -be cleared out when they are no longer appropriate. Alternatively, -you can set the variable @code{font-lock-unfontify-region-function} to -a function that clears these properties. @xref{Other Font Lock -Variables}. - -@item (@var{matcher} . @var{subexp-highlighter}) -In this kind of element, @var{subexp-highlighter} is a list -which specifies how to highlight matches found by @var{matcher}. -It has the form: - -@example -(@var{subexp} @var{facespec} [@var{override} [@var{laxmatch}]]) -@end example - -The @sc{car}, @var{subexp}, is an integer specifying which subexpression -of the match to fontify (0 means the entire matching text). The second -subelement, @var{facespec}, is an expression whose value specifies the -face, as described above. - -The last two values in @var{subexp-highlighter}, @var{override} and -@var{laxmatch}, are optional flags. If @var{override} is @code{t}, -this element can override existing fontification made by previous -elements of @code{font-lock-keywords}. If it is @code{keep}, then -each character is fontified if it has not been fontified already by -some other element. If it is @code{prepend}, the face specified by -@var{facespec} is added to the beginning of the @code{font-lock-face} -property. If it is @code{append}, the face is added to the end of the -@code{font-lock-face} property. - -If @var{laxmatch} is non-@code{nil}, it means there should be no error -if there is no subexpression numbered @var{subexp} in @var{matcher}. -Obviously, fontification of the subexpression numbered @var{subexp} will -not occur. However, fontification of other subexpressions (and other -regexps) will continue. If @var{laxmatch} is @code{nil}, and the -specified subexpression is missing, then an error is signaled which -terminates search-based fontification. - -Here are some examples of elements of this kind, and what they do: - -@smallexample -;; @r{Highlight occurrences of either @samp{foo} or @samp{bar}, using} -;; @r{@code{foo-bar-face}, even if they have already been highlighted.} -;; @r{@code{foo-bar-face} should be a variable whose value is a face.} -("foo\\|bar" 0 foo-bar-face t) - -;; @r{Highlight the first subexpression within each occurrence} -;; @r{that the function @code{fubar-match} finds,} -;; @r{using the face which is the value of @code{fubar-face}.} -(fubar-match 1 fubar-face) -@end smallexample - -@item (@var{matcher} . @var{anchored-highlighter}) -In this kind of element, @var{anchored-highlighter} specifies how to -highlight text that follows a match found by @var{matcher}. So a -match found by @var{matcher} acts as the anchor for further searches -specified by @var{anchored-highlighter}. @var{anchored-highlighter} -is a list of the following form: - -@example -(@var{anchored-matcher} @var{pre-form} @var{post-form} - @var{subexp-highlighters}@dots{}) -@end example - -Here, @var{anchored-matcher}, like @var{matcher}, is either a regular -expression or a function. After a match of @var{matcher} is found, -point is at the end of the match. Now, Font Lock evaluates the form -@var{pre-form}. Then it searches for matches of -@var{anchored-matcher} and uses @var{subexp-highlighters} to highlight -these. A @var{subexp-highlighter} is as described above. Finally, -Font Lock evaluates @var{post-form}. - -The forms @var{pre-form} and @var{post-form} can be used to initialize -before, and cleanup after, @var{anchored-matcher} is used. Typically, -@var{pre-form} is used to move point to some position relative to the -match of @var{matcher}, before starting with @var{anchored-matcher}. -@var{post-form} might be used to move back, before resuming with -@var{matcher}. - -After Font Lock evaluates @var{pre-form}, it does not search for -@var{anchored-matcher} beyond the end of the line. However, if -@var{pre-form} returns a buffer position that is greater than the -position of point after @var{pre-form} is evaluated, then the position -returned by @var{pre-form} is used as the limit of the search instead. -It is generally a bad idea to return a position greater than the end -of the line; in other words, the @var{anchored-matcher} search should -not span lines. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{item} following} -;; @r{an occurrence of the word @samp{anchor} (on the same line)} -;; @r{in the value of @code{item-face}.} -("\\" "\\" nil nil (0 item-face)) -@end smallexample - -Here, @var{pre-form} and @var{post-form} are @code{nil}. Therefore -searching for @samp{item} starts at the end of the match of -@samp{anchor}, and searching for subsequent instances of @samp{anchor} -resumes from where searching for @samp{item} concluded. - -@item (@var{matcher} @var{highlighters}@dots{}) -This sort of element specifies several @var{highlighter} lists for a -single @var{matcher}. A @var{highlighter} list can be of the type -@var{subexp-highlighter} or @var{anchored-highlighter} as described -above. - -For example, - -@smallexample -;; @r{Highlight occurrences of the word @samp{anchor} in the value} -;; @r{of @code{anchor-face}, and subsequent occurrences of the word} -;; @r{@samp{item} (on the same line) in the value of @code{item-face}.} -("\\" (0 anchor-face) - ("\\" nil nil (0 item-face))) -@end smallexample - -@item (eval . @var{form}) -Here @var{form} is an expression to be evaluated the first time -this value of @code{font-lock-keywords} is used in a buffer. -Its value should have one of the forms described in this table. -@end table - -@strong{Warning:} Do not design an element of @code{font-lock-keywords} -to match text which spans lines; this does not work reliably. -For details, see @xref{Multiline Font Lock}. - -You can use @var{case-fold} in @code{font-lock-defaults} to specify -the value of @code{font-lock-keywords-case-fold-search} which says -whether search-based fontification should be case-insensitive. - -@defvar font-lock-keywords-case-fold-search -Non-@code{nil} means that regular expression matching for the sake of -@code{font-lock-keywords} should be case-insensitive. -@end defvar - -@node Customizing Keywords -@subsection Customizing Search-Based Fontification - - You can use @code{font-lock-add-keywords} to add additional -search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. - -@defun font-lock-add-keywords mode keywords &optional how -This function adds highlighting @var{keywords}, for the current buffer -or for major mode @var{mode}. The argument @var{keywords} should be a -list with the same format as the variable @code{font-lock-keywords}. - -If @var{mode} is a symbol which is a major mode command name, such as -@code{c-mode}, the effect is that enabling Font Lock mode in -@var{mode} will add @var{keywords} to @code{font-lock-keywords}. -Calling with a non-@code{nil} value of @var{mode} is correct only in -your @file{~/.emacs} file. - -If @var{mode} is @code{nil}, this function adds @var{keywords} to -@code{font-lock-keywords} in the current buffer. This way of calling -@code{font-lock-add-keywords} is usually used in mode hook functions. - -By default, @var{keywords} are added at the beginning of -@code{font-lock-keywords}. If the optional argument @var{how} is -@code{set}, they are used to replace the value of -@code{font-lock-keywords}. If @var{how} is any other non-@code{nil} -value, they are added at the end of @code{font-lock-keywords}. - -Some modes provide specialized support you can use in additional -highlighting patterns. See the variables -@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types}, -and @code{java-font-lock-extra-types}, for example. - -@strong{Warning:} major mode functions must not call -@code{font-lock-add-keywords} under any circumstances, either directly -or indirectly, except through their mode hooks. (Doing so would lead -to incorrect behavior for some minor modes.) They should set up their -rules for search-based fontification by setting -@code{font-lock-keywords}. -@end defun - -@defun font-lock-remove-keywords mode keywords -This function removes @var{keywords} from @code{font-lock-keywords} -for the current buffer or for major mode @var{mode}. As in -@code{font-lock-add-keywords}, @var{mode} should be a major mode -command name or @code{nil}. All the caveats and requirements for -@code{font-lock-add-keywords} apply here too. -@end defun - - For example, this code - -@smallexample -(font-lock-add-keywords 'c-mode - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face))) -@end smallexample - -@noindent -adds two fontification patterns for C mode: one to fontify the word -@samp{FIXME}, even in comments, and another to fontify the words -@samp{and}, @samp{or} and @samp{not} as keywords. - -@noindent -That example affects only C mode proper. To add the same patterns to -C mode @emph{and} all modes derived from it, do this instead: - -@smallexample -(add-hook 'c-mode-hook - (lambda () - (font-lock-add-keywords nil - '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend) - ("\\<\\(and\\|or\\|not\\)\\>" . - font-lock-keyword-face))))) -@end smallexample - -@node Other Font Lock Variables -@subsection Other Font Lock Variables - - This section describes additional variables that a major mode can -set by means of @var{other-vars} in @code{font-lock-defaults} -(@pxref{Font Lock Basics}). - -@defvar font-lock-mark-block-function -If this variable is non-@code{nil}, it should be a function that is -called with no arguments, to choose an enclosing range of text for -refontification for the command @kbd{M-o M-o} -(@code{font-lock-fontify-block}). - -The function should report its choice by placing the region around it. -A good choice is a range of text large enough to give proper results, -but not too large so that refontification becomes slow. Typical values -are @code{mark-defun} for programming modes or @code{mark-paragraph} for -textual modes. -@end defvar - -@defvar font-lock-extra-managed-props -This variable specifies additional properties (other than -@code{font-lock-face}) that are being managed by Font Lock mode. It -is used by @code{font-lock-default-unfontify-region}, which normally -only manages the @code{font-lock-face} property. If you want Font -Lock to manage other properties as well, you must specify them in a -@var{facespec} in @code{font-lock-keywords} as well as add them to -this list. @xref{Search-based Fontification}. -@end defvar - -@defvar font-lock-fontify-buffer-function -Function to use for fontifying the buffer. The default value is -@code{font-lock-default-fontify-buffer}. -@end defvar - -@defvar font-lock-unfontify-buffer-function -Function to use for unfontifying the buffer. This is used when -turning off Font Lock mode. The default value is -@code{font-lock-default-unfontify-buffer}. -@end defvar - -@defvar font-lock-fontify-region-function -Function to use for fontifying a region. It should take two -arguments, the beginning and end of the region, and an optional third -argument @var{verbose}. If @var{verbose} is non-@code{nil}, the -function should print status messages. The default value is -@code{font-lock-default-fontify-region}. -@end defvar - -@defvar font-lock-unfontify-region-function -Function to use for unfontifying a region. It should take two -arguments, the beginning and end of the region. The default value is -@code{font-lock-default-unfontify-region}. -@end defvar - -@defun jit-lock-register function &optional contextual -This function tells Font Lock mode to run the Lisp function -@var{function} any time it has to fontify or refontify part of the -current buffer. It calls @var{function} before calling the default -fontification functions, and gives it two arguments, @var{start} and -@var{end}, which specify the region to be fontified or refontified. - -The optional argument @var{contextual}, if non-@code{nil}, forces Font -Lock mode to always refontify a syntactically relevant part of the -buffer, and not just the modified lines. This argument can usually be -omitted. -@end defun - -@defun jit-lock-unregister function -If @var{function} was previously registered as a fontification -function using @code{jit-lock-register}, this function unregisters it. -@end defun - -@node Levels of Font Lock -@subsection Levels of Font Lock - - Many major modes offer three different levels of fontification. You -can define multiple levels by using a list of symbols for @var{keywords} -in @code{font-lock-defaults}. Each symbol specifies one level of -fontification; it is up to the user to choose one of these levels, -normally by setting @code{font-lock-maximum-decoration} (@pxref{Font -Lock,,, emacs, the GNU Emacs Manual}). The chosen level's symbol -value is used to initialize @code{font-lock-keywords}. - - Here are the conventions for how to define the levels of -fontification: - -@itemize @bullet -@item -Level 1: highlight function declarations, file directives (such as include or -import directives), strings and comments. The idea is speed, so only -the most important and top-level components are fontified. - -@item -Level 2: in addition to level 1, highlight all language keywords, -including type names that act like keywords, as well as named constant -values. The idea is that all keywords (either syntactic or semantic) -should be fontified appropriately. - -@item -Level 3: in addition to level 2, highlight the symbols being defined in -function and variable declarations, and all builtin function names, -wherever they appear. -@end itemize - -@node Precalculated Fontification -@subsection Precalculated Fontification - - Some major modes such as @code{list-buffers} and @code{occur} -construct the buffer text programmatically. The easiest way for them -to support Font Lock mode is to specify the faces of text when they -insert the text in the buffer. - - The way to do this is to specify the faces in the text with the -special text property @code{font-lock-face} (@pxref{Special -Properties}). When Font Lock mode is enabled, this property controls -the display, just like the @code{face} property. When Font Lock mode -is disabled, @code{font-lock-face} has no effect on the display. - - It is ok for a mode to use @code{font-lock-face} for some text and -also use the normal Font Lock machinery. But if the mode does not use -the normal Font Lock machinery, it should not set the variable -@code{font-lock-defaults}. - -@node Faces for Font Lock -@subsection Faces for Font Lock -@cindex faces for font lock -@cindex font lock faces - - You can make Font Lock mode use any face, but several faces are -defined specifically for Font Lock mode. Each of these symbols is both -a face name, and a variable whose default value is the symbol itself. -Thus, the default value of @code{font-lock-comment-face} is -@code{font-lock-comment-face}. This means you can write -@code{font-lock-comment-face} in a context such as -@code{font-lock-keywords} where a face-name-valued expression is used. - -@table @code -@item font-lock-comment-face -@vindex font-lock-comment-face -Used (typically) for comments. - -@item font-lock-comment-delimiter-face -@vindex font-lock-comment-delimiter-face -Used (typically) for comments delimiters. - -@item font-lock-doc-face -@vindex font-lock-doc-face -Used (typically) for documentation strings in the code. - -@item font-lock-string-face -@vindex font-lock-string-face -Used (typically) for string constants. - -@item font-lock-keyword-face -@vindex font-lock-keyword-face -Used (typically) for keywords---names that have special syntactic -significance, like @code{for} and @code{if} in C. - -@item font-lock-builtin-face -@vindex font-lock-builtin-face -Used (typically) for built-in function names. - -@item font-lock-function-name-face -@vindex font-lock-function-name-face -Used (typically) for the name of a function being defined or declared, -in a function definition or declaration. - -@item font-lock-variable-name-face -@vindex font-lock-variable-name-face -Used (typically) for the name of a variable being defined or declared, -in a variable definition or declaration. - -@item font-lock-type-face -@vindex font-lock-type-face -Used (typically) for names of user-defined data types, -where they are defined and where they are used. - -@item font-lock-constant-face -@vindex font-lock-constant-face -Used (typically) for constant names. - -@item font-lock-preprocessor-face -@vindex font-lock-preprocessor-face -Used (typically) for preprocessor commands. - -@item font-lock-negation-char-face -@vindex font-lock-negation-char-face -Used (typically) for easily-overlooked negation characters. - -@item font-lock-warning-face -@vindex font-lock-warning-face -Used (typically) for constructs that are peculiar, or that greatly -change the meaning of other text. For example, this is used for -@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error} -directives in C. -@end table - -@node Syntactic Font Lock -@subsection Syntactic Font Lock -@cindex syntactic font lock - -Syntactic fontification uses the syntax table to find comments and -string constants (@pxref{Syntax Tables}). It highlights them using -@code{font-lock-comment-face} and @code{font-lock-string-face} -(@pxref{Faces for Font Lock}), or whatever -@code{font-lock-syntactic-face-function} chooses. There are several -variables that affect syntactic fontification; you should set them by -means of @code{font-lock-defaults} (@pxref{Font Lock Basics}). - -@defvar font-lock-keywords-only -Non-@code{nil} means Font Lock should not do syntactic fontification; -it should only fontify based on @code{font-lock-keywords}. The normal -way for a mode to set this variable to @code{t} is with -@var{keywords-only} in @code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntax-table -This variable holds the syntax table to use for fontification of -comments and strings. Specify it using @var{syntax-alist} in -@code{font-lock-defaults}. If this is @code{nil}, fontification uses -the buffer's syntax table. -@end defvar - -@defvar font-lock-beginning-of-syntax-function -If this variable is non-@code{nil}, it should be a function to move -point back to a position that is syntactically at ``top level'' and -outside of strings or comments. Font Lock uses this when necessary -to get the right results for syntactic fontification. - -This function is called with no arguments. It should leave point at -the beginning of any enclosing syntactic block. Typical values are -@code{beginning-of-line} (used when the start of the line is known to -be outside a syntactic block), or @code{beginning-of-defun} for -programming modes, or @code{backward-paragraph} for textual modes. - -If the value is @code{nil}, Font Lock uses -@code{syntax-begin-function} to move back outside of any comment, -string, or sexp. This variable is semi-obsolete; we recommend setting -@code{syntax-begin-function} instead. - -Specify this variable using @var{syntax-begin} in -@code{font-lock-defaults}. -@end defvar - -@defvar font-lock-syntactic-face-function -A function to determine which face to use for a given syntactic -element (a string or a comment). The function is called with one -argument, the parse state at point returned by -@code{parse-partial-sexp}, and should return a face. The default -value returns @code{font-lock-comment-face} for comments and -@code{font-lock-string-face} for strings. - -This can be used to highlighting different kinds of strings or -comments differently. It is also sometimes abused together with -@code{font-lock-syntactic-keywords} to highlight constructs that span -multiple lines, but this is too esoteric to document here. - -Specify this variable using @var{other-vars} in -@code{font-lock-defaults}. -@end defvar - -@node Setting Syntax Properties -@subsection Setting Syntax Properties - - Font Lock mode can be used to update @code{syntax-table} properties -automatically (@pxref{Syntax Properties}). This is useful in -languages for which a single syntax table by itself is not sufficient. - -@defvar font-lock-syntactic-keywords -This variable enables and controls updating @code{syntax-table} -properties by Font Lock. Its value should be a list of elements of -this form: - -@example -(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch}) -@end example - -The parts of this element have the same meanings as in the corresponding -sort of element of @code{font-lock-keywords}, - -@example -(@var{matcher} @var{subexp} @var{facespec} @var{override} @var{laxmatch}) -@end example - -However, instead of specifying the value @var{facespec} to use for the -@code{face} property, it specifies the value @var{syntax} to use for -the @code{syntax-table} property. Here, @var{syntax} can be a string -(as taken by @code{modify-syntax-entry}), a syntax table, a cons cell -(as returned by @code{string-to-syntax}), or an expression whose value -is one of those two types. @var{override} cannot be @code{prepend} or -@code{append}. - -For example, an element of the form: - -@example -("\\$\\(#\\)" 1 ".") -@end example - -highlights syntactically a hash character when following a dollar -character, with a SYNTAX of @code{"."} (meaning punctuation syntax). -Assuming that the buffer syntax table specifies hash characters to -have comment start syntax, the element will only highlight hash -characters that do not follow dollar characters as comments -syntactically. - -An element of the form: - -@example - ("\\('\\).\\('\\)" - (1 "\"") - (2 "\"")) -@end example - -highlights syntactically both single quotes which surround a single -character, with a SYNTAX of @code{"\""} (meaning string quote syntax). -Assuming that the buffer syntax table does not specify single quotes -to have quote syntax, the element will only highlight single quotes of -the form @samp{'@var{c}'} as strings syntactically. Other forms, such -as @samp{foo'bar} or @samp{'fubar'}, will not be highlighted as -strings. - -Major modes normally set this variable with @var{other-vars} in -@code{font-lock-defaults}. -@end defvar - -@node Multiline Font Lock -@subsection Multiline Font Lock Constructs -@cindex multiline font lock - - Normally, elements of @code{font-lock-keywords} should not match -across multiple lines; that doesn't work reliably, because Font Lock -usually scans just part of the buffer, and it can miss a multi-line -construct that crosses the line boundary where the scan starts. (The -scan normally starts at the beginning of a line.) - - Making elements that match multiline constructs work properly has -two aspects: correct @emph{identification} and correct -@emph{rehighlighting}. The first means that Font Lock finds all -multiline constructs. The second means that Font Lock will correctly -rehighlight all the relevant text when a multiline construct is -changed---for example, if some of the text that was previously part of -a multiline construct ceases to be part of it. The two aspects are -closely related, and often getting one of them to work will appear to -make the other also work. However, for reliable results you must -attend explicitly to both aspects. - - There are three ways to ensure correct identification of multiline -constructs: - -@itemize -@item -Add a function to @code{font-lock-extend-region-functions} that does -the @emph{identification} and extends the scan so that the scanned -text never starts or ends in the middle of a multiline construct. -@item -Use the @code{font-lock-fontify-region-function} hook similarly to -extend the scan so that the scanned text never starts or ends in the -middle of a multiline construct. -@item -Somehow identify the multiline construct right when it gets inserted -into the buffer (or at any point after that but before font-lock -tries to highlight it), and mark it with a @code{font-lock-multiline} -which will instruct font-lock not to start or end the scan in the -middle of the construct. -@end itemize - - There are three ways to do rehighlighting of multiline constructs: - -@itemize -@item -Place a @code{font-lock-multiline} property on the construct. This -will rehighlight the whole construct if any part of it is changed. In -some cases you can do this automatically by setting the -@code{font-lock-multiline} variable, which see. -@item -Make sure @code{jit-lock-contextually} is set and rely on it doing its -job. This will only rehighlight the part of the construct that -follows the actual change, and will do it after a short delay. -This only works if the highlighting of the various parts of your -multiline construct never depends on text in subsequent lines. -Since @code{jit-lock-contextually} is activated by default, this can -be an attractive solution. -@item -Place a @code{jit-lock-defer-multiline} property on the construct. -This works only if @code{jit-lock-contextually} is used, and with the -same delay before rehighlighting, but like @code{font-lock-multiline}, -it also handles the case where highlighting depends on -subsequent lines. -@end itemize - -@menu -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. -@end menu - -@node Font Lock Multiline -@subsubsection Font Lock Multiline - - One way to ensure reliable rehighlighting of multiline Font Lock -constructs is to put on them the text property @code{font-lock-multiline}. -It should be present and non-@code{nil} for text that is part of a -multiline construct. - - When Font Lock is about to highlight a range of text, it first -extends the boundaries of the range as necessary so that they do not -fall within text marked with the @code{font-lock-multiline} property. -Then it removes any @code{font-lock-multiline} properties from the -range, and highlights it. The highlighting specification (mostly -@code{font-lock-keywords}) must reinstall this property each time, -whenever it is appropriate. - - @strong{Warning:} don't use the @code{font-lock-multiline} property -on large ranges of text, because that will make rehighlighting slow. - -@defvar font-lock-multiline -If the @code{font-lock-multiline} variable is set to @code{t}, Font -Lock will try to add the @code{font-lock-multiline} property -automatically on multiline constructs. This is not a universal -solution, however, since it slows down Font Lock somewhat. It can -miss some multiline constructs, or make the property larger or smaller -than necessary. - -For elements whose @var{matcher} is a function, the function should -ensure that submatch 0 covers the whole relevant multiline construct, -even if only a small subpart will be highlighted. It is often just as -easy to add the @code{font-lock-multiline} property by hand. -@end defvar - - The @code{font-lock-multiline} property is meant to ensure proper -refontification; it does not automatically identify new multiline -constructs. Identifying the requires that Font-Lock operate on large -enough chunks at a time. This will happen by accident on many cases, -which may give the impression that multiline constructs magically work. -If you set the @code{font-lock-multiline} variable non-@code{nil}, -this impression will be even stronger, since the highlighting of those -constructs which are found will be properly updated from then on. -But that does not work reliably. - - To find multiline constructs reliably, you must either manually -place the @code{font-lock-multiline} property on the text before -Font-Lock looks at it, or use -@code{font-lock-fontify-region-function}. - -@node Region to Fontify -@subsubsection Region to Fontify after a Buffer Change - - When a buffer is changed, the region that Font Lock refontifies is -by default the smallest sequence of whole lines that spans the change. -While this works well most of the time, sometimes it doesn't---for -example, when a change alters the syntactic meaning of text on an -earlier line. - - You can enlarge (or even reduce) the region to fontify by setting -one the following variables: - -@defvar font-lock-extend-after-change-region-function -This buffer-local variable is either @code{nil} or a function for -Font-Lock to call to determine the region to scan and fontify. - -The function is given three parameters, the standard @var{beg}, -@var{end}, and @var{old-len} from after-change-functions -(@pxref{Change Hooks}). It should return either a cons of the -beginning and end buffer positions (in that order) of the region to -fontify, or @code{nil} (which means choose the region in the standard -way). This function needs to preserve point, the match-data, and the -current restriction. The region it returns may start or end in the -middle of a line. - -Since this function is called after every buffer change, it should be -reasonably fast. -@end defvar - -@node Desktop Save Mode -@section Desktop Save Mode -@cindex desktop save mode - -@dfn{Desktop Save Mode} is a feature to save the state of Emacs from -one session to another. The user-level commands for using Desktop -Save Mode are described in the GNU Emacs Manual (@pxref{Saving Emacs -Sessions,,, emacs, the GNU Emacs Manual}). Modes whose buffers visit -a file, don't have to do anything to use this feature. - -For buffers not visiting a file to have their state saved, the major -mode must bind the buffer local variable @code{desktop-save-buffer} to -a non-@code{nil} value. - -@defvar desktop-save-buffer -If this buffer-local variable is non-@code{nil}, the buffer will have -its state saved in the desktop file at desktop save. If the value is -a function, it is called at desktop save with argument -@var{desktop-dirname}, and its value is saved in the desktop file along -with the state of the buffer for which it was called. When file names -are returned as part of the auxiliary information, they should be -formatted using the call - -@example -(desktop-file-name @var{file-name} @var{desktop-dirname}) -@end example - -@end defvar - -For buffers not visiting a file to be restored, the major mode must -define a function to do the job, and that function must be listed in -the alist @code{desktop-buffer-mode-handlers}. - -@defvar desktop-buffer-mode-handlers -Alist with elements - -@example -(@var{major-mode} . @var{restore-buffer-function}) -@end example - -The function @var{restore-buffer-function} will be called with -argument list - -@example -(@var{buffer-file-name} @var{buffer-name} @var{desktop-buffer-misc}) -@end example - -and it should return the restored buffer. -Here @var{desktop-buffer-misc} is the value returned by the function -optionally bound to @code{desktop-save-buffer}. -@end defvar - -@ignore - arch-tag: 4c7bff41-36e6-4da6-9e7f-9b9289e27c8e -@end ignore diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi deleted file mode 100644 index 870c028a311..00000000000 --- a/doc/lispref/nonascii.texi +++ /dev/null @@ -1,1924 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004, -@c 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/characters -@node Non-ASCII Characters, Searching and Matching, Text, Top -@chapter Non-@acronym{ASCII} Characters -@cindex multibyte characters -@cindex characters, multi-byte -@cindex non-@acronym{ASCII} characters - - This chapter covers the special issues relating to characters and -how they are stored in strings and buffers. - -@menu -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. -@end menu - -@node Text Representations -@section Text Representations -@cindex text representation - - Emacs buffers and strings support a large repertoire of characters -from many different scripts, allowing users to type and display text -in most any known written language. - -@cindex character codepoint -@cindex codespace -@cindex Unicode - To support this multitude of characters and scripts, Emacs closely -follows the @dfn{Unicode Standard}. The Unicode Standard assigns a -unique number, called a @dfn{codepoint}, to each and every character. -The range of codepoints defined by Unicode, or the Unicode -@dfn{codespace}, is @code{0..10FFFF} (in hex), inclusive. Emacs -extends this range with codepoints in the range @code{110000..3FFFFF}, -which it uses for representing characters that are not unified with -Unicode and raw 8-bit bytes that cannot be interpreted as characters -(the latter occupy the range @code{3FFF80..3FFFFF}). Thus, a -character codepoint in Emacs is a 22-bit integer number. - -@cindex internal representation of characters -@cindex characters, representation in buffers and strings -@cindex multibyte text - To conserve memory, Emacs does not hold fixed-length 22-bit numbers -that are codepoints of text characters within buffers and strings. -Rather, Emacs uses a variable-length internal representation of -characters, that stores each character as a sequence of 1 to 5 8-bit -bytes, depending on the magnitude of its codepoint@footnote{ -This internal representation is based on one of the encodings defined -by the Unicode Standard, called @dfn{UTF-8}, for representing any -Unicode codepoint, but Emacs extends UTF-8 to represent the additional -codepoints it uses for raw 8-bit bytes and characters not unified with -Unicode.}. For example, any @acronym{ASCII} character takes up only 1 -byte, a Latin-1 character takes up 2 bytes, etc. We call this -representation of text @dfn{multibyte}. - - Outside Emacs, characters can be represented in many different -encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts -between these external encodings and its internal representation, as -appropriate, when it reads text into a buffer or a string, or when it -writes text to a disk file or passes it to some other process. - - Occasionally, Emacs needs to hold and manipulate encoded text or -binary non-text data in its buffers or strings. For example, when -Emacs visits a file, it first reads the file's text verbatim into a -buffer, and only then converts it to the internal representation. -Before the conversion, the buffer holds encoded text. - -@cindex unibyte text - Encoded text is not really text, as far as Emacs is concerned, but -rather a sequence of raw 8-bit bytes. We call buffers and strings -that hold encoded text @dfn{unibyte} buffers and strings, because -Emacs treats them as a sequence of individual bytes. Usually, Emacs -displays unibyte buffers and strings as octal codes such as -@code{\237}. We recommend that you never use unibyte buffers and -strings except for manipulating encoded text or binary non-text data. - - In a buffer, the buffer-local value of the variable -@code{enable-multibyte-characters} specifies the representation used. -The representation for a string is determined and recorded in the string -when the string is constructed. - -@defopt enable-multibyte-characters -This variable specifies the current buffer's text representation. -If it is non-@code{nil}, the buffer contains multibyte text; otherwise, -it contains unibyte encoded text or binary non-text data. - -You cannot set this variable directly; instead, use the function -@code{set-buffer-multibyte} to change a buffer's representation. -@end defopt - -@defvar default-enable-multibyte-characters -This variable's value is entirely equivalent to @code{(default-value -'enable-multibyte-characters)}, and setting this variable changes that -default value. Setting the local binding of -@code{enable-multibyte-characters} in a specific buffer is not allowed, -but changing the default value is supported, and it is a reasonable -thing to do, because it has no effect on existing buffers. - -The @samp{--unibyte} command line option does its job by setting the -default value to @code{nil} early in startup. -@end defvar - -@defun position-bytes position -Buffer positions are measured in character units. This function -returns the byte-position corresponding to buffer position -@var{position} in the current buffer. This is 1 at the start of the -buffer, and counts upward in bytes. If @var{position} is out of -range, the value is @code{nil}. -@end defun - -@defun byte-to-position byte-position -Return the buffer position, in character units, corresponding to given -@var{byte-position} in the current buffer. If @var{byte-position} is -out of range, the value is @code{nil}. In a multibyte buffer, an -arbitrary value of @var{byte-position} can be not at character -boundary, but inside a multibyte sequence representing a single -character; in this case, this function returns the buffer position of -the character whose multibyte sequence includes @var{byte-position}. -In other words, the value does not change for all byte positions that -belong to the same character. -@end defun - -@defun multibyte-string-p string -Return @code{t} if @var{string} is a multibyte string, @code{nil} -otherwise. -@end defun - -@defun string-bytes string -@cindex string, number of bytes -This function returns the number of bytes in @var{string}. -If @var{string} is a multibyte string, this can be greater than -@code{(length @var{string})}. -@end defun - -@defun unibyte-string &rest bytes -This function concatenates all its argument @var{bytes} and makes the -result a unibyte string. -@end defun - -@node Converting Representations -@section Converting Text Representations - - Emacs can convert unibyte text to multibyte; it can also convert -multibyte text to unibyte, provided that the multibyte text contains -only @acronym{ASCII} and 8-bit raw bytes. In general, these -conversions happen when inserting text into a buffer, or when putting -text from several strings together in one string. You can also -explicitly convert a string's contents to either representation. - - Emacs chooses the representation for a string based on the text from -which it is constructed. The general rule is to convert unibyte text -to multibyte text when combining it with other multibyte text, because -the multibyte representation is more general and can hold whatever -characters the unibyte text has. - - When inserting text into a buffer, Emacs converts the text to the -buffer's representation, as specified by -@code{enable-multibyte-characters} in that buffer. In particular, when -you insert multibyte text into a unibyte buffer, Emacs converts the text -to unibyte, even though this conversion cannot in general preserve all -the characters that might be in the multibyte text. The other natural -alternative, to convert the buffer contents to multibyte, is not -acceptable because the buffer's representation is a choice made by the -user that cannot be overridden automatically. - - Converting unibyte text to multibyte text leaves @acronym{ASCII} -characters unchanged, and converts bytes with codes 128 through 159 to -the multibyte representation of raw eight-bit bytes. - - Converting multibyte text to unibyte converts all @acronym{ASCII} -and eight-bit characters to their single-byte form, but loses -information for non-@acronym{ASCII} characters by discarding all but -the low 8 bits of each character's codepoint. Converting unibyte text -to multibyte and back to unibyte reproduces the original unibyte text. - -The next two functions either return the argument @var{string}, or a -newly created string with no text properties. - -@defun string-to-multibyte string -This function returns a multibyte string containing the same sequence -of characters as @var{string}. If @var{string} is a multibyte string, -it is returned unchanged. The function assumes that @var{string} -includes only @acronym{ASCII} characters and raw 8-bit bytes; the -latter are converted to their multibyte representation corresponding -to the codepoints in the @code{3FFF80..3FFFFF} area (@pxref{Text -Representations, codepoints}). -@end defun - -@defun string-to-unibyte string -This function returns a unibyte string containing the same sequence of -characters as @var{string}. It signals an error if @var{string} -contains a non-@acronym{ASCII} character. If @var{string} is a -unibyte string, it is returned unchanged. Use this function for -@var{string} arguments that contain only @acronym{ASCII} and eight-bit -characters. -@end defun - -@defun multibyte-char-to-unibyte char -This converts the multibyte character @var{char} to a unibyte -character, and returns that character. If @var{char} is neither -@acronym{ASCII} nor eight-bit, the function returns -1. -@end defun - -@defun unibyte-char-to-multibyte char -This convert the unibyte character @var{char} to a multibyte -character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit -byte. -@end defun - -@node Selecting a Representation -@section Selecting a Representation - - Sometimes it is useful to examine an existing buffer or string as -multibyte when it was unibyte, or vice versa. - -@defun set-buffer-multibyte multibyte -Set the representation type of the current buffer. If @var{multibyte} -is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte} -is @code{nil}, the buffer becomes unibyte. - -This function leaves the buffer contents unchanged when viewed as a -sequence of bytes. As a consequence, it can change the contents -viewed as characters; for instance, a sequence of three bytes which is -treated as one character in multibyte representation will count as -three characters in unibyte representation. Eight-bit characters -representing raw bytes are an exception. They are represented by one -byte in a unibyte buffer, but when the buffer is set to multibyte, -they are converted to two-byte sequences, and vice versa. - -This function sets @code{enable-multibyte-characters} to record which -representation is in use. It also adjusts various data in the buffer -(including overlays, text properties and markers) so that they cover the -same text as they did before. - -You cannot use @code{set-buffer-multibyte} on an indirect buffer, -because indirect buffers always inherit the representation of the -base buffer. -@end defun - -@defun string-as-unibyte string -If @var{string} is already a unibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each byte as a separate character -(so that the value may have more characters than @var{string}); as an -exception, each eight-bit character representing a raw byte is -converted into a single byte. The newly-created string contains no -text properties. -@end defun - -@defun string-as-multibyte string -If @var{string} is a multibyte string, this function returns -@var{string} itself. Otherwise, it returns a new string with the same -bytes as @var{string}, but treating each multibyte sequence as one -character. This means that the value may have fewer characters than -@var{string} has. If a byte sequence in @var{string} is invalid as a -multibyte representation of a single character, each byte in the -sequence is treated as a raw 8-bit byte. The newly-created string -contains no text properties. -@end defun - -@node Character Codes -@section Character Codes -@cindex character codes - - The unibyte and multibyte text representations use different -character codes. The valid character codes for unibyte representation -range from 0 to 255---the values that can fit in one byte. The valid -character codes for multibyte representation range from 0 to 4194303 -(#x3FFFFF). In this code space, values 0 through 127 are for -@acronym{ASCII} charcters, and values 129 through 4194175 (#x3FFF7F) -are for non-@acronym{ASCII} characters. Values 0 through 1114111 -(#10FFFF) correspond to Unicode characters of the same codepoint; -values 1114112 (#110000) through 4194175 (#x3FFF7F) represent -characters that are not unified with Unicode; and values 4194176 -(#x3FFF80) through 4194303 (#x3FFFFF) represent eight-bit raw bytes. - -@defun characterp charcode -This returns @code{t} if @var{charcode} is a valid character, and -@code{nil} otherwise. - -@example -@group -(characterp 65) - @result{} t -@end group -@group -(characterp 4194303) - @result{} t -@end group -@group -(characterp 4194304) - @result{} nil -@end group -@end example -@end defun - -@cindex maximum value of character codepoint -@cindex codepoint, largest value -@defun max-char -This function returns the largest value that a valid character -codepoint can have. - -@example -@group -(characterp (max-char)) - @result{} t -@end group -@group -(characterp (1+ (max-char))) - @result{} nil -@end group -@end example -@end defun - -@defun get-byte &optional pos string -This function returns the byte at character position @var{pos} in the -current buffer. If the current buffer is unibyte, this is literally -the byte at that position. If the buffer is multibyte, byte values of -@acronym{ASCII} characters are the same as character codepoints, -whereas eight-bit raw bytes are converted to their 8-bit codes. The -function signals an error if the character at @var{pos} is -non-@acronym{ASCII}. - -The optional argument @var{string} means to get a byte value from that -string instead of the current buffer. -@end defun - -@node Character Properties -@section Character Properties -@cindex character properties -A @dfn{character property} is a named attribute of a character that -specifies how the character behaves and how it should be handled -during text processing and display. Thus, character properties are an -important part of specifying the character's semantics. - - On the whole, Emacs follows the Unicode Standard in its implementation -of character properties. In particular, Emacs supports the -@uref{http://www.unicode.org/reports/tr23/, Unicode Character Property -Model}, and the Emacs character property database is derived from the -Unicode Character Database (@acronym{UCD}). See the -@uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character -Properties chapter of the Unicode Standard}, for a detailed -description of Unicode character properties and their meaning. This -section assumes you are already familiar with that chapter of the -Unicode Standard, and want to apply that knowledge to Emacs Lisp -programs. - - In Emacs, each property has a name, which is a symbol, and a set of -possible values, whose types depend on the property; if a character -does not have a certain property, the value is @code{nil}. As a -general rule, the names of character properties in Emacs are produced -from the corresponding Unicode properties by downcasing them and -replacing each @samp{_} character with a dash @samp{-}. For example, -@code{Canonical_Combining_Class} becomes -@code{canonical-combining-class}. However, sometimes we shorten the -names to make their use easier. - - Here is the full list of value types for all the character -properties that Emacs knows about: - -@table @code -@item name -This property corresponds to the Unicode @code{Name} property. The -value is a string consisting of upper-case Latin letters A to Z, -digits, spaces, and hyphen @samp{-} characters. - -@item general-category -This property corresponds to the Unicode @code{General_Category} -property. The value is a symbol whose name is a 2-letter abbreviation -of the character's classification. - -@item canonical-combining-class -Corresponds to the Unicode @code{Canonical_Combining_Class} property. -The value is an integer number. - -@item bidi-class -Corresponds to the Unicode @code{Bidi_Class} property. The value is a -symbol whose name is the Unicode @dfn{directional type} of the -character. - -@item decomposition -Corresponds to the Unicode @code{Decomposition_Type} and -@code{Decomposition_Value} properties. The value is a list, whose -first element may be a symbol representing a compatibility formatting -tag, such as @code{small}@footnote{ -Note that the Unicode spec writes these tag names inside -@samp{<..>} brackets. The tag names in Emacs do not include the -brackets; e.g., Unicode specifies @samp{} where Emacs uses -@samp{small}. -}; the other elements are characters that give the compatibility -decomposition sequence of this character. - -@item decimal-digit-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Digit}. The value is an -integer number. - -@item digit -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Decimal}. The value is -an integer number. Examples of such characters include compatibility -subscript and superscript digits, for which the value is the -corresponding number. - -@item numeric-value -Corresponds to the Unicode @code{Numeric_Value} property for -characters whose @code{Numeric_Type} is @samp{Numeric}. The value of -this property is an integer or a floating-point number. Examples of -characters that have this property include fractions, subscripts, -superscripts, Roman numerals, currency numerators, and encircled -numbers. For example, the value of this property for the character -@code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. - -@item mirrored -Corresponds to the Unicode @code{Bidi_Mirrored} property. The value -of this property is a symbol, either @code{Y} or @code{N}. - -@item old-name -Corresponds to the Unicode @code{Unicode_1_Name} property. The value -is a string. - -@item iso-10646-comment -Corresponds to the Unicode @code{ISO_Comment} property. The value is -a string. - -@item uppercase -Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property. -The value of this property is a single character. - -@item lowercase -Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property. -The value of this property is a single character. - -@item titlecase -Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property. -@dfn{Title case} is a special form of a character used when the first -character of a word needs to be capitalized. The value of this -property is a single character. -@end table - -@defun get-char-code-property char propname -This function returns the value of @var{char}'s @var{propname} property. - -@example -@group -(get-char-code-property ? 'general-category) - @result{} Zs -@end group -@group -(get-char-code-property ?1 'general-category) - @result{} Nd -@end group -@group -(get-char-code-property ?\u2084 'digit-value) ; subscript 4 - @result{} 4 -@end group -@group -(get-char-code-property ?\u2155 'numeric-value) ; one fifth - @result{} 1/5 -@end group -@group -(get-char-code-property ?\u2163 'numeric-value) ; Roman IV - @result{} \4 -@end group -@end example -@end defun - -@defun char-code-property-description prop value -This function returns the description string of property @var{prop}'s -@var{value}, or @code{nil} if @var{value} has no description. - -@example -@group -(char-code-property-description 'general-category 'Zs) - @result{} "Separator, Space" -@end group -@group -(char-code-property-description 'general-category 'Nd) - @result{} "Number, Decimal Digit" -@end group -@group -(char-code-property-description 'numeric-value '1/5) - @result{} nil -@end group -@end example -@end defun - -@defun put-char-code-property char propname value -This function stores @var{value} as the value of the property -@var{propname} for the character @var{char}. -@end defun - -@defvar char-script-table -The value of this variable is a char-table (@pxref{Char-Tables}) that -specifies, for each character, a symbol whose name is the script to -which the character belongs, according to the Unicode Standard -classification of the Unicode code space into script-specific blocks. -This char-table has a single extra slot whose value is the list of all -script symbols. -@end defvar - -@defvar char-width-table -The value of this variable is a char-table that specifies the width of -each character in columns that it will occupy on the screen. -@end defvar - -@defvar printable-chars -The value of this variable is a char-table that specifies, for each -character, whether it is printable or not. That is, if evaluating -@code{(aref printable-chars char)} results in @code{t}, the character -is printable, and if it results in @code{nil}, it is not. -@end defvar - -@node Character Sets -@section Character Sets -@cindex character sets - -@cindex charset -@cindex coded character set -An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters -in which each character is assigned a numeric code point. (The -Unicode Standard calls this a @dfn{coded character set}.) Each Emacs -charset has a name which is a symbol. A single character can belong -to any number of different character sets, but it will generally have -a different code point in each charset. Examples of character sets -include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and -@code{windows-1255}. The code point assigned to a character in a -charset is usually different from its code point used in Emacs buffers -and strings. - -@cindex @code{emacs}, a charset -@cindex @code{unicode}, a charset -@cindex @code{eight-bit}, a charset - Emacs defines several special character sets. The character set -@code{unicode} includes all the characters whose Emacs code points are -in the range @code{0..10FFFF}. The character set @code{emacs} -includes all @acronym{ASCII} and non-@acronym{ASCII} characters. -Finally, the @code{eight-bit} charset includes the 8-bit raw bytes; -Emacs uses it to represent raw bytes encountered in text. - -@defun charsetp object -Returns @code{t} if @var{object} is a symbol that names a character set, -@code{nil} otherwise. -@end defun - -@defvar charset-list -The value is a list of all defined character set names. -@end defvar - -@defun charset-priority-list &optional highestp -This functions returns a list of all defined character sets ordered by -their priority. If @var{highestp} is non-@code{nil}, the function -returns a single character set of the highest priority. -@end defun - -@defun set-charset-priority &rest charsets -This function makes @var{charsets} the highest priority character sets. -@end defun - -@defun char-charset character &optional restriction -This function returns the name of the character set of highest -priority that @var{character} belongs to. @acronym{ASCII} characters -are an exception: for them, this function always returns @code{ascii}. - -If @var{restriction} is non-@code{nil}, it should be a list of -charsets to search. Alternatively, it can be a coding system, in -which case the returned charset must be supported by that coding -system (@pxref{Coding Systems}). -@end defun - -@defun charset-plist charset -This function returns the property list of the character set -@var{charset}. Although @var{charset} is a symbol, this is not the -same as the property list of that symbol. Charset properties include -important information about the charset, such as its documentation -string, short name, etc. -@end defun - -@defun put-charset-property charset propname value -This function sets the @var{propname} property of @var{charset} to the -given @var{value}. -@end defun - -@defun get-charset-property charset propname -This function returns the value of @var{charset}s property -@var{propname}. -@end defun - -@deffn Command list-charset-chars charset -This command displays a list of characters in the character set -@var{charset}. -@end deffn - - Emacs can convert between its internal representation of a character -and the character's codepoint in a specific charset. The following -two functions support these conversions. - -@c FIXME: decode-char and encode-char accept and ignore an additional -@c argument @var{restriction}. When that argument actually makes a -@c difference, it should be documented here. -@defun decode-char charset code-point -This function decodes a character that is assigned a @var{code-point} -in @var{charset}, to the corresponding Emacs character, and returns -it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be -specified as a cons cell @code{(@var{high} . @var{low})}, where -@var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. -@end defun - -@defun encode-char char charset -This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If -@var{charset} doesn't have a codepoint for @var{char}, the value is -@code{nil}. -@end defun - - The following function comes in handy for applying a certain -function to all or part of the characters in a charset: - -@defun map-charset-chars function charset &optional arg from to -Call @var{function} for characters in @var{charset}. @var{function} -is called with two arguments. The first one is a cons cell -@code{(@var{from} . @var{to})}, where @var{from} and @var{to} -indicate a range of characters contained in charset. The second -argument is the optional argument @var{arg}. - -By default, the range of codepoints passed to @var{function} includes -all the characters in @var{charset}, but optional arguments -@var{from-code} and @var{to-code} limit that to the range of -characters between these two codepoints of @var{charset}. If either -of them is @code{nil}, it defaults to the first or last codepoint of -@var{charset}, respectively. -@end defun - -@node Scanning Charsets -@section Scanning for Character Sets - - Sometimes it is useful to find out which character set a particular -character belongs to. One use for this is in determining which coding -systems (@pxref{Coding Systems}) are capable of representing all of -the text in question; another is to determine the font(s) for -displaying that text. - -@defun charset-after &optional pos -This function returns the charset of highest priority containing the -character at position @var{pos} in the current buffer. If @var{pos} -is omitted or @code{nil}, it defaults to the current value of point. -If @var{pos} is out of range, the value is @code{nil}. -@end defun - -@defun find-charset-region beg end &optional translation -This function returns a list of the character sets of highest priority -that contain characters in the current buffer between positions -@var{beg} and @var{end}. - -The optional argument @var{translation} specifies a translation table -to use for scanning the text (@pxref{Translation of Characters}). If -it is non-@code{nil}, then each character in the region is translated -through this table, and the value returned describes the translated -characters instead of the characters actually in the buffer. -@end defun - -@defun find-charset-string string &optional translation -This function returns a list of character sets of highest priority -that contain characters in @var{string}. It is just like -@code{find-charset-region}, except that it applies to the contents of -@var{string} instead of part of the current buffer. -@end defun - -@node Translation of Characters -@section Translation of Characters -@cindex character translation tables -@cindex translation tables - - A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that -specifies a mapping of characters into characters. These tables are -used in encoding and decoding, and for other purposes. Some coding -systems specify their own particular translation tables; there are -also default translation tables which apply to all other coding -systems. - - A translation table has two extra slots. The first is either -@code{nil} or a translation table that performs the reverse -translation; the second is the maximum number of characters to look up -for translating sequences of characters (see the description of -@code{make-translation-table-from-alist} below). - -@defun make-translation-table &rest translations -This function returns a translation table based on the argument -@var{translations}. Each element of @var{translations} should be a -list of elements of the form @code{(@var{from} . @var{to})}; this says -to translate the character @var{from} into @var{to}. - -The arguments and the forms in each argument are processed in order, -and if a previous form already translates @var{to} to some other -character, say @var{to-alt}, @var{from} is also translated to -@var{to-alt}. -@end defun - - During decoding, the translation table's translations are applied to -the characters that result from ordinary decoding. If a coding system -has the property @code{:decode-translation-table}, that specifies the -translation table to use, or a list of translation tables to apply in -sequence. (This is a property of the coding system, as returned by -@code{coding-system-get}, not a property of the symbol that is the -coding system's name. @xref{Coding System Basics,, Basic Concepts of -Coding Systems}.) Finally, if -@code{standard-translation-table-for-decode} is non-@code{nil}, the -resulting characters are translated by that table. - - During encoding, the translation table's translations are applied to -the characters in the buffer, and the result of translation is -actually encoded. If a coding system has property -@code{:encode-translation-table}, that specifies the translation table -to use, or a list of translation tables to apply in sequence. In -addition, if the variable @code{standard-translation-table-for-encode} -is non-@code{nil}, it specifies the translation table to use for -translating the result. - -@defvar standard-translation-table-for-decode -This is the default translation table for decoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@defvar standard-translation-table-for-encode -This is the default translation table for encoding. If a coding -systems specifies its own translation tables, the table that is the -value of this variable, if non-@code{nil}, is applied after them. -@end defvar - -@defvar translation-table-for-input -Self-inserting characters are translated through this translation -table before they are inserted. Search commands also translate their -input through this table, so they can compare more reliably with -what's in the buffer. - -This variable automatically becomes buffer-local when set. -@end defvar - -@defun make-translation-table-from-vector vec -This function returns a translation table made from @var{vec} that is -an array of 256 elements to map byte values 0 through 255 to -characters. Elements may be @code{nil} for untranslated bytes. The -returned table has a translation table for reverse mapping in the -first extra slot, and the value @code{1} in the second extra slot. - -This function provides an easy way to make a private coding system -that maps each byte to a specific character. You can specify the -returned table and the reverse translation table using the properties -@code{:decode-translation-table} and @code{:encode-translation-table} -respectively in the @var{props} argument to -@code{define-coding-system}. -@end defun - -@defun make-translation-table-from-alist alist -This function is similar to @code{make-translation-table} but returns -a complex translation table rather than a simple one-to-one mapping. -Each element of @var{alist} is of the form @code{(@var{from} -. @var{to})}, where @var{from} and @var{to} are either characters or -vectors specifying a sequence of characters. If @var{from} is a -character, that character is translated to @var{to} (i.e.@: to a -character or a character sequence). If @var{from} is a vector of -characters, that sequence is translated to @var{to}. The returned -table has a translation table for reverse mapping in the first extra -slot, and the maximum length of all the @var{from} character sequences -in the second extra slot. -@end defun - -@node Coding Systems -@section Coding Systems - -@cindex coding system - When Emacs reads or writes a file, and when Emacs sends text to a -subprocess or receives text from a subprocess, it normally performs -character code conversion and end-of-line conversion as specified -by a particular @dfn{coding system}. - - How to define a coding system is an arcane matter, and is not -documented here. - -@menu -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. -@end menu - -@node Coding System Basics -@subsection Basic Concepts of Coding Systems - -@cindex character code conversion - @dfn{Character code conversion} involves conversion between the -internal representation of characters used inside Emacs and some other -encoding. Emacs supports many different encodings, in that it can -convert to and from them. For example, it can convert text to or from -encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and -several variants of ISO 2022. In some cases, Emacs supports several -alternative encodings for the same characters; for example, there are -three coding systems for the Cyrillic (Russian) alphabet: ISO, -Alternativnyj, and KOI8. - - Every coding system specifies a particular set of character code -conversions, but the coding system @code{undecided} is special: it -leaves the choice unspecified, to be chosen heuristically for each -file, based on the file's data. - - In general, a coding system doesn't guarantee roundtrip identity: -decoding a byte sequence using coding system, then encoding the -resulting text in the same coding system, can produce a different byte -sequence. But some coding systems do guarantee that the byte sequence -will be the same as what you originally decoded. Here are a few -examples: - -@quotation -iso-8859-1, utf-8, big5, shift_jis, euc-jp -@end quotation - - Encoding buffer text and then decoding the result can also fail to -reproduce the original text. For instance, if you encode a character -with a coding system which does not support that character, the result -is unpredictable, and thus decoding it using the same coding system -may produce a different text. Currently, Emacs can't report errors -that result from encoding unsupported characters. - -@cindex EOL conversion -@cindex end-of-line conversion -@cindex line end conversion - @dfn{End of line conversion} handles three different conventions -used on various systems for representing end of line in files. The -Unix convention, used on GNU and Unix systems, is to use the linefeed -character (also called newline). The DOS convention, used on -MS-Windows and MS-DOS systems, is to use a carriage-return and a -linefeed at the end of a line. The Mac convention is to use just -carriage-return. - -@cindex base coding system -@cindex variant coding system - @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line -conversion unspecified, to be chosen based on the data. @dfn{Variant -coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and -@code{latin-1-mac} specify the end-of-line conversion explicitly as -well. Most base coding systems have three corresponding variants whose -names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}. - -@vindex raw-text@r{ coding system} - The coding system @code{raw-text} is special in that it prevents -character code conversion, and causes the buffer visited with this -coding system to be a unibyte buffer. For historical reasons, you can -save both unibyte and multibyte text with this coding system. When -you use @code{raw-text} to encode multibyte text, it does perform one -character code conversion: it converts eight-bit characters to their -single-byte external representation. @code{raw-text} does not specify -the end-of-line conversion, allowing that to be determined as usual by -the data, and has the usual three variants which specify the -end-of-line conversion. - -@vindex no-conversion@r{ coding system} -@vindex binary@r{ coding system} - @code{no-conversion} (and its alias @code{binary}) is equivalent to -@code{raw-text-unix}: it specifies no conversion of either character -codes or end-of-line. - -@vindex emacs-internal@r{ coding system} -@vindex utf-8-emacs@r{ coding system} - The coding system @code{utf-8-emacs} specifies that the data is -represented in the internal Emacs encoding (@pxref{Text -Representations}). This is like @code{raw-text} in that no code -conversion happens, but different in that the result is multibyte -data. The name @code{emacs-internal} is an alias for -@code{utf-8-emacs}. - -@defun coding-system-get coding-system property -This function returns the specified property of the coding system -@var{coding-system}. Most coding system properties exist for internal -purposes, but one that you might find useful is @code{:mime-charset}. -That property's value is the name used in MIME for the character coding -which this coding system can read and write. Examples: - -@example -(coding-system-get 'iso-latin-1 :mime-charset) - @result{} iso-8859-1 -(coding-system-get 'iso-2022-cn :mime-charset) - @result{} iso-2022-cn -(coding-system-get 'cyrillic-koi8 :mime-charset) - @result{} koi8-r -@end example - -The value of the @code{:mime-charset} property is also defined -as an alias for the coding system. -@end defun - -@defun coding-system-aliases coding-system -This function returns the list of aliases of @var{coding-system}. -@end defun - -@node Encoding and I/O -@subsection Encoding and I/O - - The principal purpose of coding systems is for use in reading and -writing files. The function @code{insert-file-contents} uses a coding -system to decode the file data, and @code{write-region} uses one to -encode the buffer contents. - - You can specify the coding system to use either explicitly -(@pxref{Specifying Coding Systems}), or implicitly using a default -mechanism (@pxref{Default Coding Systems}). But these methods may not -completely specify what to do. For example, they may choose a coding -system such as @code{undefined} which leaves the character code -conversion to be determined from the data. In these cases, the I/O -operation finishes the job of choosing a coding system. Very often -you will want to find out afterwards which coding system was chosen. - -@defvar buffer-file-coding-system -This buffer-local variable records the coding system used for saving the -buffer and for writing part of the buffer with @code{write-region}. If -the text to be written cannot be safely encoded using the coding system -specified by this variable, these operations select an alternative -encoding by calling the function @code{select-safe-coding-system} -(@pxref{User-Chosen Coding Systems}). If selecting a different encoding -requires to ask the user to specify a coding system, -@code{buffer-file-coding-system} is updated to the newly selected coding -system. - -@code{buffer-file-coding-system} does @emph{not} affect sending text -to a subprocess. -@end defvar - -@defvar save-buffer-coding-system -This variable specifies the coding system for saving the buffer (by -overriding @code{buffer-file-coding-system}). Note that it is not used -for @code{write-region}. - -When a command to save the buffer starts out to use -@code{buffer-file-coding-system} (or @code{save-buffer-coding-system}), -and that coding system cannot handle -the actual text in the buffer, the command asks the user to choose -another coding system (by calling @code{select-safe-coding-system}). -After that happens, the command also updates -@code{buffer-file-coding-system} to represent the coding system that -the user specified. -@end defvar - -@defvar last-coding-system-used -I/O operations for files and subprocesses set this variable to the -coding system name that was used. The explicit encoding and decoding -functions (@pxref{Explicit Encoding}) set it too. - -@strong{Warning:} Since receiving subprocess output sets this variable, -it can change whenever Emacs waits; therefore, you should copy the -value shortly after the function call that stores the value you are -interested in. -@end defvar - - The variable @code{selection-coding-system} specifies how to encode -selections for the window system. @xref{Window System Selections}. - -@defvar file-name-coding-system -The variable @code{file-name-coding-system} specifies the coding -system to use for encoding file names. Emacs encodes file names using -that coding system for all file operations. If -@code{file-name-coding-system} is @code{nil}, Emacs uses a default -coding system determined by the selected language environment. In the -default language environment, any non-@acronym{ASCII} characters in -file names are not encoded specially; they appear in the file system -using the internal Emacs representation. -@end defvar - - @strong{Warning:} if you change @code{file-name-coding-system} (or -the language environment) in the middle of an Emacs session, problems -can result if you have already visited files whose names were encoded -using the earlier coding system and are handled differently under the -new coding system. If you try to save one of these buffers under the -visited file name, saving may use the wrong file name, or it may get -an error. If such a problem happens, use @kbd{C-x C-w} to specify a -new file name for that buffer. - -@node Lisp and Coding Systems -@subsection Coding Systems in Lisp - - Here are the Lisp facilities for working with coding systems: - -@cindex list all coding systems -@defun coding-system-list &optional base-only -This function returns a list of all coding system names (symbols). If -@var{base-only} is non-@code{nil}, the value includes only the -base coding systems. Otherwise, it includes alias and variant coding -systems as well. -@end defun - -@defun coding-system-p object -This function returns @code{t} if @var{object} is a coding system -name or @code{nil}. -@end defun - -@cindex validity of coding system -@cindex coding system, validity check -@defun check-coding-system coding-system -This function checks the validity of @var{coding-system}. If that is -valid, it returns @var{coding-system}. If @var{coding-system} is -@code{nil}, the function return @code{nil}. For any other values, it -signals an error whose @code{error-symbol} is @code{coding-system-error} -(@pxref{Signaling Errors, signal}). -@end defun - -@cindex eol type of coding system -@defun coding-system-eol-type coding-system -This function returns the type of end-of-line (a.k.a.@: @dfn{eol}) -conversion used by @var{coding-system}. If @var{coding-system} -specifies a certain eol conversion, the return value is an integer 0, -1, or 2, standing for @code{unix}, @code{dos}, and @code{mac}, -respectively. If @var{coding-system} doesn't specify eol conversion -explicitly, the return value is a vector of coding systems, each one -with one of the possible eol conversion types, like this: - -@lisp -(coding-system-eol-type 'latin-1) - @result{} [latin-1-unix latin-1-dos latin-1-mac] -@end lisp - -@noindent -If this function returns a vector, Emacs will decide, as part of the -text encoding or decoding process, what eol conversion to use. For -decoding, the end-of-line format of the text is auto-detected, and the -eol conversion is set to match it (e.g., DOS-style CRLF format will -imply @code{dos} eol conversion). For encoding, the eol conversion is -taken from the appropriate default coding system (e.g., -@code{default-buffer-file-coding-system} for -@code{buffer-file-coding-system}), or from the default eol conversion -appropriate for the underlying platform. -@end defun - -@cindex eol conversion of coding system -@defun coding-system-change-eol-conversion coding-system eol-type -This function returns a coding system which is like @var{coding-system} -except for its eol conversion, which is specified by @code{eol-type}. -@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or -@code{nil}. If it is @code{nil}, the returned coding system determines -the end-of-line conversion from the data. - -@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, -@code{dos} and @code{mac}, respectively. -@end defun - -@cindex text conversion of coding system -@defun coding-system-change-text-conversion eol-coding text-coding -This function returns a coding system which uses the end-of-line -conversion of @var{eol-coding}, and the text conversion of -@var{text-coding}. If @var{text-coding} is @code{nil}, it returns -@code{undecided}, or one of its variants according to @var{eol-coding}. -@end defun - -@cindex safely encode region -@cindex coding systems for encoding region -@defun find-coding-systems-region from to -This function returns a list of coding systems that could be used to -encode a text between @var{from} and @var{to}. All coding systems in -the list can safely encode any multibyte characters in that portion of -the text. - -If the text contains no multibyte characters, the function returns the -list @code{(undecided)}. -@end defun - -@cindex safely encode a string -@cindex coding systems for encoding a string -@defun find-coding-systems-string string -This function returns a list of coding systems that could be used to -encode the text of @var{string}. All coding systems in the list can -safely encode any multibyte characters in @var{string}. If the text -contains no multibyte characters, this returns the list -@code{(undecided)}. -@end defun - -@cindex charset, coding systems to encode -@cindex safely encode characters in a charset -@defun find-coding-systems-for-charsets charsets -This function returns a list of coding systems that could be used to -encode all the character sets in the list @var{charsets}. -@end defun - -@defun check-coding-systems-region start end coding-system-list -This function checks whether coding systems in the list -@code{coding-system-list} can encode all the characters in the region -between @var{start} and @var{end}. If all of the coding systems in -the list can encode the specified text, the function returns -@code{nil}. If some coding systems cannot encode some of the -characters, the value is an alist, each element of which has the form -@code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning -that @var{coding-system1} cannot encode characters at buffer positions -@var{pos1}, @var{pos2}, @enddots{}. - -@var{start} may be a string, in which case @var{end} is ignored and -the returned value references string indices instead of buffer -positions. -@end defun - -@defun detect-coding-region start end &optional highest -This function chooses a plausible coding system for decoding the text -from @var{start} to @var{end}. This text should be a byte sequence, -i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and -eight-bit characters (@pxref{Explicit Encoding}). - -Normally this function returns a list of coding systems that could -handle decoding the text that was scanned. They are listed in order of -decreasing priority. But if @var{highest} is non-@code{nil}, then the -return value is just one coding system, the one that is highest in -priority. - -If the region contains only @acronym{ASCII} characters except for such -ISO-2022 control characters ISO-2022 as @code{ESC}, the value is -@code{undecided} or @code{(undecided)}, or a variant specifying -end-of-line conversion, if that can be deduced from the text. - -If the region contains null bytes, the value is @code{no-conversion}, -even if the region contains text encoded in some coding system. -@end defun - -@defun detect-coding-string string &optional highest -This function is like @code{detect-coding-region} except that it -operates on the contents of @var{string} instead of bytes in the buffer. -@end defun - -@cindex null bytes, and decoding text -@defvar inhibit-null-byte-detection -If this variable has a non-@code{nil} value, null bytes are ignored -when detecting the encoding of a region or a string. This allows to -correctly detect the encoding of text that contains null bytes, such -as Info files with Index nodes. -@end defvar - -@defvar inhibit-iso-escape-detection -If this variable has a non-@code{nil} value, ISO-2022 escape sequences -are ignored when detecting the encoding of a region or a string. The -result is that no text is ever detected as encoded in some ISO-2022 -encoding, and all escape sequences become visible in a buffer. -@strong{Warning:} @emph{Use this variable with extreme caution, -because many files in the Emacs distribution use ISO-2022 encoding.} -@end defvar - -@cindex charsets supported by a coding system -@defun coding-system-charset-list coding-system -This function returns the list of character sets (@pxref{Character -Sets}) supported by @var{coding-system}. Some coding systems that -support too many character sets to list them all yield special values: -@itemize @bullet -@item -If @var{coding-system} supports all the ISO-2022 charsets, the value -is @code{iso-2022}. -@item -If @var{coding-system} supports all Emacs characters, the value is -@code{(emacs)}. -@item -If @var{coding-system} supports all emacs-mule characters, the value -is @code{emacs-mule}. -@item -If @var{coding-system} supports all Unicode characters, the value is -@code{(unicode)}. -@end itemize -@end defun - - @xref{Coding systems for a subprocess,, Process Information}, in -particular the description of the functions -@code{process-coding-system} and @code{set-process-coding-system}, for -how to examine or set the coding systems used for I/O to a subprocess. - -@node User-Chosen Coding Systems -@subsection User-Chosen Coding Systems - -@cindex select safe coding system -@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file -This function selects a coding system for encoding specified text, -asking the user to choose if necessary. Normally the specified text -is the text in the current buffer between @var{from} and @var{to}. If -@var{from} is a string, the string specifies the text to encode, and -@var{to} is ignored. - -If the specified text includes raw bytes (@pxref{Text -Representations}), @code{select-safe-coding-system} suggests -@code{raw-text} for its encoding. - -If @var{default-coding-system} is non-@code{nil}, that is the first -coding system to try; if that can handle the text, -@code{select-safe-coding-system} returns that coding system. It can -also be a list of coding systems; then the function tries each of them -one by one. After trying all of them, it next tries the current -buffer's value of @code{buffer-file-coding-system} (if it is not -@code{undecided}), then the value of -@code{default-buffer-file-coding-system} and finally the user's most -preferred coding system, which the user can set using the command -@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing -Coding Systems, emacs, The GNU Emacs Manual}). - -If one of those coding systems can safely encode all the specified -text, @code{select-safe-coding-system} chooses it and returns it. -Otherwise, it asks the user to choose from a list of coding systems -which can encode all the text, and returns the user's choice. - -@var{default-coding-system} can also be a list whose first element is -t and whose other elements are coding systems. Then, if no coding -system in the list can handle the text, @code{select-safe-coding-system} -queries the user immediately, without trying any of the three -alternatives described above. - -The optional argument @var{accept-default-p}, if non-@code{nil}, -should be a function to determine whether a coding system selected -without user interaction is acceptable. @code{select-safe-coding-system} -calls this function with one argument, the base coding system of the -selected coding system. If @var{accept-default-p} returns @code{nil}, -@code{select-safe-coding-system} rejects the silently selected coding -system, and asks the user to select a coding system from a list of -possible candidates. - -@vindex select-safe-coding-system-accept-default-p -If the variable @code{select-safe-coding-system-accept-default-p} is -non-@code{nil}, its value overrides the value of -@var{accept-default-p}. - -As a final step, before returning the chosen coding system, -@code{select-safe-coding-system} checks whether that coding system is -consistent with what would be selected if the contents of the region -were read from a file. (If not, this could lead to data corruption in -a file subsequently re-visited and edited.) Normally, -@code{select-safe-coding-system} uses @code{buffer-file-name} as the -file for this purpose, but if @var{file} is non-@code{nil}, it uses -that file instead (this can be relevant for @code{write-region} and -similar functions). If it detects an apparent inconsistency, -@code{select-safe-coding-system} queries the user before selecting the -coding system. -@end defun - - Here are two functions you can use to let the user specify a coding -system, with completion. @xref{Completion}. - -@defun read-coding-system prompt &optional default -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user enters null input, @var{default} specifies which coding system -to return. It should be a symbol or a string. -@end defun - -@defun read-non-nil-coding-system prompt -This function reads a coding system using the minibuffer, prompting with -string @var{prompt}, and returns the coding system name as a symbol. If -the user tries to enter null input, it asks the user to try again. -@xref{Coding Systems}. -@end defun - -@node Default Coding Systems -@subsection Default Coding Systems -@cindex default coding system -@cindex coding system, automatically determined - - This section describes variables that specify the default coding -system for certain files or when running certain subprograms, and the -function that I/O operations use to access them. - - The idea of these variables is that you set them once and for all to the -defaults you want, and then do not change them again. To specify a -particular coding system for a particular operation in a Lisp program, -don't change these variables; instead, override them using -@code{coding-system-for-read} and @code{coding-system-for-write} -(@pxref{Specifying Coding Systems}). - -@cindex file contents, and default coding system -@defopt auto-coding-regexp-alist -This variable is an alist of text patterns and corresponding coding -systems. Each element has the form @code{(@var{regexp} -. @var{coding-system})}; a file whose first few kilobytes match -@var{regexp} is decoded with @var{coding-system} when its contents are -read into a buffer. The settings in this alist take priority over -@code{coding:} tags in the files and the contents of -@code{file-coding-system-alist} (see below). The default value is set -so that Emacs automatically recognizes mail files in Babyl format and -reads them with no code conversions. -@end defopt - -@cindex file name, and default coding system -@defopt file-coding-system-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Each element has the form -@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular -expression that matches certain file names. The element applies to file -names that match @var{pattern}. - -The @sc{cdr} of the element, @var{coding}, should be either a coding -system, a cons cell containing two coding systems, or a function name (a -symbol with a function definition). If @var{coding} is a coding system, -that coding system is used for both reading the file and writing it. If -@var{coding} is a cons cell containing two coding systems, its @sc{car} -specifies the coding system for decoding, and its @sc{cdr} specifies the -coding system for encoding. - -If @var{coding} is a function name, the function should take one -argument, a list of all arguments passed to -@code{find-operation-coding-system}. It must return a coding system -or a cons cell containing two coding systems. This value has the same -meaning as described above. - -If @var{coding} (or what returned by the above function) is -@code{undecided}, the normal code-detection is performed. -@end defopt - -@defopt auto-coding-alist -This variable is an alist that specifies the coding systems to use for -reading and writing particular files. Its form is like that of -@code{file-coding-system-alist}, but, unlike the latter, this variable -takes priority over any @code{coding:} tags in the file. -@end defopt - -@cindex program name, and default coding system -@defvar process-coding-system-alist -This variable is an alist specifying which coding systems to use for a -subprocess, depending on which program is running in the subprocess. It -works like @code{file-coding-system-alist}, except that @var{pattern} is -matched against the program name used to start the subprocess. The coding -system or systems specified in this alist are used to initialize the -coding systems used for I/O to the subprocess, but you can specify -other coding systems later using @code{set-process-coding-system}. -@end defvar - - @strong{Warning:} Coding systems such as @code{undecided}, which -determine the coding system from the data, do not work entirely reliably -with asynchronous subprocess output. This is because Emacs handles -asynchronous subprocess output in batches, as it arrives. If the coding -system leaves the character code conversion unspecified, or leaves the -end-of-line conversion unspecified, Emacs must try to detect the proper -conversion from one batch at a time, and this does not always work. - - Therefore, with an asynchronous subprocess, if at all possible, use a -coding system which determines both the character code conversion and -the end of line conversion---that is, one like @code{latin-1-unix}, -rather than @code{undecided} or @code{latin-1}. - -@cindex port number, and default coding system -@cindex network service name, and default coding system -@defvar network-coding-system-alist -This variable is an alist that specifies the coding system to use for -network streams. It works much like @code{file-coding-system-alist}, -with the difference that the @var{pattern} in an element may be either a -port number or a regular expression. If it is a regular expression, it -is matched against the network service name used to open the network -stream. -@end defvar - -@defvar default-process-coding-system -This variable specifies the coding systems to use for subprocess (and -network stream) input and output, when nothing else specifies what to -do. - -The value should be a cons cell of the form @code{(@var{input-coding} -. @var{output-coding})}. Here @var{input-coding} applies to input from -the subprocess, and @var{output-coding} applies to output to it. -@end defvar - -@cindex default coding system, functions to determine -@defopt auto-coding-functions -This variable holds a list of functions that try to determine a -coding system for a file based on its undecoded contents. - -Each function in this list should be written to look at text in the -current buffer, but should not modify it in any way. The buffer will -contain undecoded text of parts of the file. Each function should -take one argument, @var{size}, which tells it how many characters to -look at, starting from point. If the function succeeds in determining -a coding system for the file, it should return that coding system. -Otherwise, it should return @code{nil}. - -If a file has a @samp{coding:} tag, that takes precedence, so these -functions won't be called. -@end defopt - -@defun find-auto-coding filename size -This function tries to determine a suitable coding system for -@var{filename}. It examines the buffer visiting the named file, using -the variables documented above in sequence, until it finds a match for -one of the rules specified by these variables. It then returns a cons -cell of the form @code{(@var{coding} . @var{source})}, where -@var{coding} is the coding system to use and @var{source} is a symbol, -one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist}, -@code{:coding}, or @code{auto-coding-functions}, indicating which one -supplied the matching rule. The value @code{:coding} means the coding -system was specified by the @code{coding:} tag in the file -(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}). -The order of looking for a matching rule is @code{auto-coding-alist} -first, then @code{auto-coding-regexp-alist}, then the @code{coding:} -tag, and lastly @code{auto-coding-functions}. If no matching rule was -found, the function returns @code{nil}. - -The second argument @var{size} is the size of text, in characters, -following point. The function examines text only within @var{size} -characters after point. Normally, the buffer should be positioned at -the beginning when this function is called, because one of the places -for the @code{coding:} tag is the first one or two lines of the file; -in that case, @var{size} should be the size of the buffer. -@end defun - -@defun set-auto-coding filename size -This function returns a suitable coding system for file -@var{filename}. It uses @code{find-auto-coding} to find the coding -system. If no coding system could be determined, the function returns -@code{nil}. The meaning of the argument @var{size} is like in -@code{find-auto-coding}. -@end defun - -@defun find-operation-coding-system operation &rest arguments -This function returns the coding system to use (by default) for -performing @var{operation} with @var{arguments}. The value has this -form: - -@example -(@var{decoding-system} . @var{encoding-system}) -@end example - -The first element, @var{decoding-system}, is the coding system to use -for decoding (in case @var{operation} does decoding), and -@var{encoding-system} is the coding system for encoding (in case -@var{operation} does encoding). - -The argument @var{operation} is a symbol, one of @code{write-region}, -@code{start-process}, @code{call-process}, @code{call-process-region}, -@code{insert-file-contents}, or @code{open-network-stream}. These are -the names of the Emacs I/O primitives that can do character code and -eol conversion. - -The remaining arguments should be the same arguments that might be given -to the corresponding I/O primitive. Depending on the primitive, one -of those arguments is selected as the @dfn{target}. For example, if -@var{operation} does file I/O, whichever argument specifies the file -name is the target. For subprocess primitives, the process name is the -target. For @code{open-network-stream}, the target is the service name -or port number. - -Depending on @var{operation}, this function looks up the target in -@code{file-coding-system-alist}, @code{process-coding-system-alist}, -or @code{network-coding-system-alist}. If the target is found in the -alist, @code{find-operation-coding-system} returns its association in -the alist; otherwise it returns @code{nil}. - -If @var{operation} is @code{insert-file-contents}, the argument -corresponding to the target may be a cons cell of the form -@code{(@var{filename} . @var{buffer})}). In that case, @var{filename} -is a file name to look up in @code{file-coding-system-alist}, and -@var{buffer} is a buffer that contains the file's contents (not yet -decoded). If @code{file-coding-system-alist} specifies a function to -call for this file, and that function needs to examine the file's -contents (as it usually does), it should examine the contents of -@var{buffer} instead of reading the file. -@end defun - -@node Specifying Coding Systems -@subsection Specifying a Coding System for One Operation - - You can specify the coding system for a specific operation by binding -the variables @code{coding-system-for-read} and/or -@code{coding-system-for-write}. - -@defvar coding-system-for-read -If this variable is non-@code{nil}, it specifies the coding system to -use for reading a file, or for input from a synchronous subprocess. - -It also applies to any asynchronous subprocess or network stream, but in -a different way: the value of @code{coding-system-for-read} when you -start the subprocess or open the network stream specifies the input -decoding method for that subprocess or network stream. It remains in -use for that subprocess or network stream unless and until overridden. - -The right way to use this variable is to bind it with @code{let} for a -specific I/O operation. Its global value is normally @code{nil}, and -you should not globally set it to any other value. Here is an example -of the right way to use the variable: - -@example -;; @r{Read the file with no character code conversion.} -;; @r{Assume @acronym{crlf} represents end-of-line.} -(let ((coding-system-for-read 'emacs-mule-dos)) - (insert-file-contents filename)) -@end example - -When its value is non-@code{nil}, this variable takes precedence over -all other methods of specifying a coding system to use for input, -including @code{file-coding-system-alist}, -@code{process-coding-system-alist} and -@code{network-coding-system-alist}. -@end defvar - -@defvar coding-system-for-write -This works much like @code{coding-system-for-read}, except that it -applies to output rather than input. It affects writing to files, -as well as sending output to subprocesses and net connections. - -When a single operation does both input and output, as do -@code{call-process-region} and @code{start-process}, both -@code{coding-system-for-read} and @code{coding-system-for-write} -affect it. -@end defvar - -@defopt inhibit-eol-conversion -When this variable is non-@code{nil}, no end-of-line conversion is done, -no matter which coding system is specified. This applies to all the -Emacs I/O and subprocess primitives, and to the explicit encoding and -decoding functions (@pxref{Explicit Encoding}). -@end defopt - -@cindex priority order of coding systems -@cindex coding systems, priority - Sometimes, you need to prefer several coding systems for some -operation, rather than fix a single one. Emacs lets you specify a -priority order for using coding systems. This ordering affects the -sorting of lists of coding sysems returned by functions such as -@code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}). - -@defun coding-system-priority-list &optional highestp -This function returns the list of coding systems in the order of their -current priorities. Optional argument @var{highestp}, if -non-@code{nil}, means return only the highest priority coding system. -@end defun - -@defun set-coding-system-priority &rest coding-systems -This function puts @var{coding-systems} at the beginning of the -priority list for coding systems, thus making their priority higher -than all the rest. -@end defun - -@defmac with-coding-priority coding-systems &rest body@dots{} -This macro execute @var{body}, like @code{progn} does -(@pxref{Sequencing, progn}), with @var{coding-systems} at the front of -the priority list for coding systems. @var{coding-systems} should be -a list of coding systems to prefer during execution of @var{body}. -@end defmac - -@node Explicit Encoding -@subsection Explicit Encoding and Decoding -@cindex encoding in coding systems -@cindex decoding in coding systems - - All the operations that transfer text in and out of Emacs have the -ability to use a coding system to encode or decode the text. -You can also explicitly encode and decode text using the functions -in this section. - - The result of encoding, and the input to decoding, are not ordinary -text. They logically consist of a series of byte values; that is, a -series of @acronym{ASCII} and eight-bit characters. In unibyte -buffers and strings, these characters have codes in the range 0 -through 255. In a multibyte buffer or string, eight-bit characters -have character codes higher than 255 (@pxref{Text Representations}), -but Emacs transparently converts them to their single-byte values when -you encode or decode such text. - - The usual way to read a file into a buffer as a sequence of bytes, so -you can decode the contents explicitly, is with -@code{insert-file-contents-literally} (@pxref{Reading from Files}); -alternatively, specify a non-@code{nil} @var{rawfile} argument when -visiting a file with @code{find-file-noselect}. These methods result in -a unibyte buffer. - - The usual way to use the byte sequence that results from explicitly -encoding text is to copy it to a file or process---for example, to write -it with @code{write-region} (@pxref{Writing to Files}), and suppress -encoding by binding @code{coding-system-for-write} to -@code{no-conversion}. - - Here are the functions to perform explicit encoding or decoding. The -encoding functions produce sequences of bytes; the decoding functions -are meant to operate on sequences of bytes. All of these functions -discard text properties. They also set @code{last-coding-system-used} -to the precise coding system they used. - -@deffn Command encode-coding-region start end coding-system &optional destination -This command encodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. Normally, the encoded text -replaces the original text in the buffer, but the optional argument -@var{destination} can change that. If @var{destination} is a buffer, -the encoded text is inserted in that buffer after point (point does -not move); if it is @code{t}, the command returns the encoded text as -a unibyte string without inserting it. - -If encoded text is inserted in some buffer, this command returns the -length of the encoded text. - -The result of encoding is logically a sequence of bytes, but the -buffer remains multibyte if it was multibyte before, and any 8-bit -bytes are converted to their multibyte representation (@pxref{Text -Representations}). - -@cindex @code{undecided} coding-system, when encoding -Do @emph{not} use @code{undecided} for @var{coding-system} when -encoding text, since that may lead to unexpected results. Instead, -use @code{select-safe-coding-system} (@pxref{User-Chosen Coding -Systems, select-safe-coding-system}) to suggest a suitable encoding, -if there's no obvious pertinent value for @var{coding-system}. -@end deffn - -@defun encode-coding-string string coding-system &optional nocopy buffer -This function encodes the text in @var{string} according to coding -system @var{coding-system}. It returns a new string containing the -encoded text, except when @var{nocopy} is non-@code{nil}, in which -case the function may return @var{string} itself if the encoding -operation is trivial. The result of encoding is a unibyte string. -@end defun - -@deffn Command decode-coding-region start end coding-system &optional destination -This command decodes the text from @var{start} to @var{end} according -to coding system @var{coding-system}. To make explicit decoding -useful, the text before decoding ought to be a sequence of byte -values, but both multibyte and unibyte buffers are acceptable (in the -multibyte case, the raw byte values should be represented as eight-bit -characters). Normally, the decoded text replaces the original text in -the buffer, but the optional argument @var{destination} can change -that. If @var{destination} is a buffer, the decoded text is inserted -in that buffer after point (point does not move); if it is @code{t}, -the command returns the decoded text as a multibyte string without -inserting it. - -If decoded text is inserted in some buffer, this command returns the -length of the decoded text. - -This command puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text. -@end deffn - -@defun decode-coding-string string coding-system &optional nocopy buffer -This function decodes the text in @var{string} according to -@var{coding-system}. It returns a new string containing the decoded -text, except when @var{nocopy} is non-@code{nil}, in which case the -function may return @var{string} itself if the decoding operation is -trivial. To make explicit decoding useful, the contents of -@var{string} ought to be a unibyte string with a sequence of byte -values, but a multibyte string is also acceptable (assuming it -contains 8-bit bytes in their multibyte form). - -If optional argument @var{buffer} specifies a buffer, the decoded text -is inserted in that buffer after point (point does not move). In this -case, the return value is the length of the decoded text. - -@cindex @code{charset}, text property -This function puts a @code{charset} text property on the decoded text. -The value of the property states the character set used to decode the -original text: - -@example -@group -(decode-coding-string "Gr\374ss Gott" 'latin-1) - @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1)) -@end group -@end example -@end defun - -@defun decode-coding-inserted-region from to filename &optional visit beg end replace -This function decodes the text from @var{from} to @var{to} as if -it were being read from file @var{filename} using @code{insert-file-contents} -using the rest of the arguments provided. - -The normal way to use this function is after reading text from a file -without decoding, if you decide you would rather have decoded it. -Instead of deleting the text and reading it again, this time with -decoding, you can call this function. -@end defun - -@node Terminal I/O Encoding -@subsection Terminal I/O Encoding - - Emacs can decode keyboard input using a coding system, and encode -terminal output. This is useful for terminals that transmit or -display text using a particular encoding such as Latin-1. Emacs does -not set @code{last-coding-system-used} for encoding or decoding of -terminal I/O. - -@defun keyboard-coding-system &optional terminal -This function returns the coding system that is in use for decoding -keyboard input from @var{terminal}---or @code{nil} if no coding system -is to be used for that terminal. If @var{terminal} is omitted or -@code{nil}, it means the selected frame's terminal. @xref{Multiple -Terminals}. -@end defun - -@deffn Command set-keyboard-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for decoding keyboard input from @var{terminal}. If -@var{coding-system} is @code{nil}, that means do not decode keyboard -input. If @var{terminal} is a frame, it means that frame's terminal; -if it is @code{nil}, that means the currently selected frame's -terminal. @xref{Multiple Terminals}. -@end deffn - -@defun terminal-coding-system &optional terminal -This function returns the coding system that is in use for encoding -terminal output from @var{terminal}---or @code{nil} if the output is -not encoded. If @var{terminal} is a frame, it means that frame's -terminal; if it is @code{nil}, that means the currently selected -frame's terminal. -@end defun - -@deffn Command set-terminal-coding-system coding-system &optional terminal -This command specifies @var{coding-system} as the coding system to use -for encoding terminal output from @var{terminal}. If -@var{coding-system} is @code{nil}, terminal output is not encoded. If -@var{terminal} is a frame, it means that frame's terminal; if it is -@code{nil}, that means the currently selected frame's terminal. -@end deffn - -@node MS-DOS File Types -@subsection MS-DOS File Types -@cindex DOS file types -@cindex MS-DOS file types -@cindex Windows file types -@cindex file types on MS-DOS and Windows -@cindex text files and binary files -@cindex binary files and text files - - On MS-DOS and Microsoft Windows, Emacs guesses the appropriate -end-of-line conversion for a file by looking at the file's name. This -feature classifies files as @dfn{text files} and @dfn{binary files}. By -``binary file'' we mean a file of literal byte values that are not -necessarily meant to be characters; Emacs does no end-of-line conversion -and no character code conversion for them. On the other hand, the bytes -in a text file are intended to represent characters; when you create a -new file whose name implies that it is a text file, Emacs uses DOS -end-of-line conversion. - -@defvar buffer-file-type -This variable, automatically buffer-local in each buffer, records the -file type of the buffer's visited file. When a buffer does not specify -a coding system with @code{buffer-file-coding-system}, this variable is -used to determine which coding system to use when writing the contents -of the buffer. It should be @code{nil} for text, @code{t} for binary. -If it is @code{t}, the coding system is @code{no-conversion}. -Otherwise, @code{undecided-dos} is used. - -Normally this variable is set by visiting a file; it is set to -@code{nil} if the file was visited without any actual conversion. -@end defvar - -@defopt file-name-buffer-file-type-alist -This variable holds an alist for recognizing text and binary files. -Each element has the form (@var{regexp} . @var{type}), where -@var{regexp} is matched against the file name, and @var{type} may be -@code{nil} for text, @code{t} for binary, or a function to call to -compute which. If it is a function, then it is called with a single -argument (the file name) and should return @code{t} or @code{nil}. - -When running on MS-DOS or MS-Windows, Emacs checks this alist to decide -which coding system to use when reading a file. For a text file, -@code{undecided-dos} is used. For a binary file, @code{no-conversion} -is used. - -If no element in this alist matches a given file name, then -@code{default-buffer-file-type} says how to treat the file. -@end defopt - -@defopt default-buffer-file-type -This variable says how to handle files for which -@code{file-name-buffer-file-type-alist} says nothing about the type. - -If this variable is non-@code{nil}, then these files are treated as -binary: the coding system @code{no-conversion} is used. Otherwise, -nothing special is done for them---the coding system is deduced solely -from the file contents, in the usual Emacs fashion. -@end defopt - -@node Input Methods -@section Input Methods -@cindex input methods - - @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII} -characters from the keyboard. Unlike coding systems, which translate -non-@acronym{ASCII} characters to and from encodings meant to be read by -programs, input methods provide human-friendly commands. (@xref{Input -Methods,,, emacs, The GNU Emacs Manual}, for information on how users -use input methods to enter text.) How to define input methods is not -yet documented in this manual, but here we describe how to use them. - - Each input method has a name, which is currently a string; -in the future, symbols may also be usable as input method names. - -@defvar current-input-method -This variable holds the name of the input method now active in the -current buffer. (It automatically becomes local in each buffer when set -in any fashion.) It is @code{nil} if no input method is active in the -buffer now. -@end defvar - -@defopt default-input-method -This variable holds the default input method for commands that choose an -input method. Unlike @code{current-input-method}, this variable is -normally global. -@end defopt - -@deffn Command set-input-method input-method -This command activates input method @var{input-method} for the current -buffer. It also sets @code{default-input-method} to @var{input-method}. -If @var{input-method} is @code{nil}, this command deactivates any input -method for the current buffer. -@end deffn - -@defun read-input-method-name prompt &optional default inhibit-null -This function reads an input method name with the minibuffer, prompting -with @var{prompt}. If @var{default} is non-@code{nil}, that is returned -by default, if the user enters empty input. However, if -@var{inhibit-null} is non-@code{nil}, empty input signals an error. - -The returned value is a string. -@end defun - -@defvar input-method-alist -This variable defines all the supported input methods. -Each element defines one input method, and should have the form: - -@example -(@var{input-method} @var{language-env} @var{activate-func} - @var{title} @var{description} @var{args}...) -@end example - -Here @var{input-method} is the input method name, a string; -@var{language-env} is another string, the name of the language -environment this input method is recommended for. (That serves only for -documentation purposes.) - -@var{activate-func} is a function to call to activate this method. The -@var{args}, if any, are passed as arguments to @var{activate-func}. All -told, the arguments to @var{activate-func} are @var{input-method} and -the @var{args}. - -@var{title} is a string to display in the mode line while this method is -active. @var{description} is a string describing this method and what -it is good for. -@end defvar - - The fundamental interface to input methods is through the -variable @code{input-method-function}. @xref{Reading One Event}, -and @ref{Invoking the Input Method}. - -@node Locales -@section Locales -@cindex locale - - POSIX defines a concept of ``locales'' which control which language -to use in language-related features. These Emacs variables control -how Emacs interacts with these features. - -@defvar locale-coding-system -@cindex keyboard input decoding on X -This variable specifies the coding system to use for decoding system -error messages and---on X Window system only---keyboard input, for -encoding the format argument to @code{format-time-string}, and for -decoding the return value of @code{format-time-string}. -@end defvar - -@defvar system-messages-locale -This variable specifies the locale to use for generating system error -messages. Changing the locale can cause messages to come out in a -different language or in a different orthography. If the variable is -@code{nil}, the locale is specified by environment variables in the -usual POSIX fashion. -@end defvar - -@defvar system-time-locale -This variable specifies the locale to use for formatting time values. -Changing the locale can cause messages to appear according to the -conventions of a different language. If the variable is @code{nil}, the -locale is specified by environment variables in the usual POSIX fashion. -@end defvar - -@defun locale-info item -This function returns locale data @var{item} for the current POSIX -locale, if available. @var{item} should be one of these symbols: - -@table @code -@item codeset -Return the character set as a string (locale item @code{CODESET}). - -@item days -Return a 7-element vector of day names (locale items -@code{DAY_1} through @code{DAY_7}); - -@item months -Return a 12-element vector of month names (locale items @code{MON_1} -through @code{MON_12}). - -@item paper -Return a list @code{(@var{width} @var{height})} for the default paper -size measured in millimeters (locale items @code{PAPER_WIDTH} and -@code{PAPER_HEIGHT}). -@end table - -If the system can't provide the requested information, or if -@var{item} is not one of those symbols, the value is @code{nil}. All -strings in the return value are decoded using -@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, -for more information about locales and locale items. -@end defun - -@ignore - arch-tag: be705bf8-941b-4c35-84fc-ad7d20ddb7cb -@end ignore diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi deleted file mode 100644 index bb67f8a7e6a..00000000000 --- a/doc/lispref/numbers.texi +++ /dev/null @@ -1,1214 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/numbers -@node Numbers, Strings and Characters, Lisp Data Types, Top -@chapter Numbers -@cindex integers -@cindex numbers - - GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point -numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or -2.71828. They can also be expressed in exponential notation: 1.5e2 -equals 150; in this example, @samp{e2} stands for ten to the second -power, and that is multiplied by 1.5. Floating point values are not -exact; they have a fixed, limited amount of precision. - -@menu -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. -@end menu - -@node Integer Basics -@comment node-name, next, previous, up -@section Integer Basics - - The range of values for an integer depends on the machine. The -minimum range is @minus{}268435456 to 268435455 (29 bits; i.e., -@ifnottex --2**28 -@end ifnottex -@tex -@math{-2^{28}} -@end tex -to -@ifnottex -2**28 - 1), -@end ifnottex -@tex -@math{2^{28}-1}), -@end tex -but some machines may provide a wider range. Many examples in this -chapter assume an integer has 29 bits. -@cindex overflow - - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. - -@example - 1 ; @r{The integer 1.} - 1. ; @r{The integer 1.} -+1 ; @r{Also the integer 1.} --1 ; @r{The integer @minus{}1.} - 536870913 ; @r{Also the integer 1, due to overflow.} - 0 ; @r{The integer 0.} --0 ; @r{The integer 0.} -@end example - -@cindex integers in specific radix -@cindex radix for reading an integer -@cindex base for reading an integer -@cindex hex numbers -@cindex octal numbers -@cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads -@var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads -@var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: - -@example -#b101100 @result{} 44 -#o54 @result{} 44 -#x2c @result{} 44 -#24r1k @result{} 44 -@end example - - To understand how various functions work on integers, especially the -bitwise operators (@pxref{Bitwise Operations}), it is often helpful to -view the numbers in their binary form. - - In 29-bit binary, the decimal integer 5 looks like this: - -@example -0 0000 0000 0000 0000 0000 0000 0101 -@end example - -@noindent -(We have inserted spaces between groups of 4 bits, and two spaces -between groups of 8 bits, to make the binary integer easier to read.) - - The integer @minus{}1 looks like this: - -@example -1 1111 1111 1111 1111 1111 1111 1111 -@end example - -@noindent -@cindex two's complement -@minus{}1 is represented as 29 ones. (This is called @dfn{two's -complement} notation.) - - The negative integer, @minus{}5, is creating by subtracting 4 from -@minus{}1. In binary, the decimal integer 4 is 100. Consequently, -@minus{}5 looks like this: - -@example -1 1111 1111 1111 1111 1111 1111 1011 -@end example - - In this implementation, the largest 29-bit binary integer value is -268,435,455 in decimal. In binary, it looks like this: - -@example -0 1111 1111 1111 1111 1111 1111 1111 -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 268,435,455, the value is the -negative integer @minus{}268,435,456: - -@example -(+ 1 268435455) - @result{} -268435456 - @result{} 1 0000 0000 0000 0000 0000 0000 0000 -@end example - - Many of the functions described in this chapter accept markers for -arguments in place of numbers. (@xref{Markers}.) Since the actual -arguments to such functions may be either numbers or markers, we often -give these arguments the name @var{number-or-marker}. When the argument -value is a marker, its position value is used and its buffer is ignored. - -@defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp -can handle. -@end defvar - -@defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. -@end defvar - - @xref{Character Codes, max-char}, for the maximum value of a valid -character codepoint. - -@node Float Basics -@section Floating Point Basics - - Floating point numbers are useful for representing numbers that are -not integral. The precise range of floating point numbers is -machine-specific; it is the same as the range of the C data type -@code{double} on the machine you are using. - - The read-syntax for floating point numbers requires either a decimal -point (with at least one digit following), an exponent, or both. For -example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and -@samp{.15e4} are five ways of writing a floating point number whose -value is 1500. They are all equivalent. You can also use a minus sign -to write negative floating point numbers, as in @samp{-1.0}. - -@cindex @acronym{IEEE} floating point -@cindex positive infinity -@cindex negative infinity -@cindex infinity -@cindex NaN - Most modern computers support the @acronym{IEEE} floating point standard, -which provides for positive infinity and negative infinity as floating point -values. It also provides for a class of values called NaN or -``not-a-number''; numerical functions return such values in cases where -there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a -NaN. For practical purposes, there's no significant difference between -different NaN values in Emacs Lisp, and there's no rule for precisely -which NaN value should be used in a particular case, so Emacs Lisp -doesn't try to distinguish them (but it does report the sign, if you -print it). Here are the read syntaxes for these special floating -point values: - -@table @asis -@item positive infinity -@samp{1.0e+INF} -@item negative infinity -@samp{-1.0e+INF} -@item Not-a-number -@samp{0.0e+NaN} or @samp{-0.0e+NaN}. -@end table - - To test whether a floating point value is a NaN, compare it with -itself using @code{=}. That returns @code{nil} for a NaN, and -@code{t} for any other floating point value. - - The value @code{-0.0} is distinguishable from ordinary zero in -@acronym{IEEE} floating point, but Emacs Lisp @code{equal} and -@code{=} consider them equal values. - - You can use @code{logb} to extract the binary exponent of a floating -point number (or estimate the logarithm of an integer): - -@defun logb number -This function returns the binary exponent of @var{number}. More -precisely, the value is the logarithm of @var{number} base 2, rounded -down to an integer. - -@example -(logb 10) - @result{} 3 -(logb 10.0e20) - @result{} 69 -@end example -@end defun - -@node Predicates on Numbers -@section Type Predicates for Numbers -@cindex predicates for numbers - - The functions in this section test for numbers, or for a specific -type of number. The functions @code{integerp} and @code{floatp} can -take any type of Lisp object as argument (they would not be of much -use otherwise), but the @code{zerop} predicate requires a number as -its argument. See also @code{integer-or-marker-p} and -@code{number-or-marker-p}, in @ref{Predicates on Markers}. - -@defun floatp object -This predicate tests whether its argument is a floating point -number and returns @code{t} if so, @code{nil} otherwise. - -@code{floatp} does not exist in Emacs versions 18 and earlier. -@end defun - -@defun integerp object -This predicate tests whether its argument is an integer, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@defun numberp object -This predicate tests whether its argument is a number (either integer or -floating point), and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun wholenump object -@cindex natural numbers -The @code{wholenump} predicate (whose name comes from the phrase -``whole-number-p'') tests to see whether its argument is a nonnegative -integer, and returns @code{t} if so, @code{nil} otherwise. 0 is -considered non-negative. - -@findex natnump -@code{natnump} is an obsolete synonym for @code{wholenump}. -@end defun - -@defun zerop number -This predicate tests whether its argument is zero, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. - -@code{(zerop x)} is equivalent to @code{(= x 0)}. -@end defun - -@node Comparison of Numbers -@section Comparison of Numbers -@cindex number comparison -@cindex comparing numbers - - To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating point -number objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - At present, each integer value has a unique Lisp object in Emacs Lisp. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing an -unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of any -type. By contrast, @code{=} signals an error if the arguments are not -numbers or markers. However, it is a good idea to use @code{=} if you -can, even for comparing integers, just in case we change the -representation of integers in a future Emacs version. - - Sometimes it is useful to compare numbers with @code{equal}; it -treats two numbers as equal if they have the same data type (both -integers, or both floating point) and the same value. By contrast, -@code{=} can treat an integer and a floating point number as equal. -@xref{Equality Predicates}. - - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. -Here's a function to do this: - -@example -(defvar fuzz-factor 1.0e-6) -(defun approx-equal (x y) - (or (and (= x 0) (= y 0)) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) -@end example - -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integer values. -@end quotation - -@defun = number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun eql value1 value2 -This function acts like @code{eq} except when both arguments are -numbers. It compares numbers by type and numeric value, so that -@code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. -@end defun - -@defun /= number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if they are not, and @code{nil} if they are. -@end defun - -@defun < number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly less than -its second argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun <= number-or-marker1 number-or-marker2 -This function tests whether its first argument is less than or equal -to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun > number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly greater -than its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun >= number-or-marker1 number-or-marker2 -This function tests whether its first argument is greater than or -equal to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun max number-or-marker &rest numbers-or-markers -This function returns the largest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(max 20) - @result{} 20 -(max 1 2.5) - @result{} 2.5 -(max 1 3 2.5) - @result{} 3.0 -@end example -@end defun - -@defun min number-or-marker &rest numbers-or-markers -This function returns the smallest of its arguments. -If any of the arguments is floating-point, the value is returned -as floating point, even if it was given as an integer. - -@example -(min -4 1) - @result{} -4 -@end example -@end defun - -@defun abs number -This function returns the absolute value of @var{number}. -@end defun - -@node Numeric Conversions -@section Numeric Conversions -@cindex rounding in conversions -@cindex number conversions -@cindex converting numbers - -To convert an integer to floating point, use the function @code{float}. - -@defun float number -This returns @var{number} converted to floating point. -If @var{number} is already a floating point number, @code{float} returns -it unchanged. -@end defun - -There are four functions to convert floating point numbers to integers; -they differ in how they round. All accept an argument @var{number} -and an optional argument @var{divisor}. Both arguments may be -integers or floating point numbers. @var{divisor} may also be -@code{nil}. If @var{divisor} is @code{nil} or omitted, these -functions convert @var{number} to an integer, or return it unchanged -if it already is an integer. If @var{divisor} is non-@code{nil}, they -divide @var{number} by @var{divisor} and convert the result to an -integer. An @code{arith-error} results if @var{divisor} is 0. - -@defun truncate number &optional divisor -This returns @var{number}, converted to an integer by rounding towards -zero. - -@example -(truncate 1.2) - @result{} 1 -(truncate 1.7) - @result{} 1 -(truncate -1.2) - @result{} -1 -(truncate -1.7) - @result{} -1 -@end example -@end defun - -@defun floor number &optional divisor -This returns @var{number}, converted to an integer by rounding downward -(towards negative infinity). - -If @var{divisor} is specified, this uses the kind of division -operation that corresponds to @code{mod}, rounding downward. - -@example -(floor 1.2) - @result{} 1 -(floor 1.7) - @result{} 1 -(floor -1.2) - @result{} -2 -(floor -1.7) - @result{} -2 -(floor 5.99 3) - @result{} 1 -@end example -@end defun - -@defun ceiling number &optional divisor -This returns @var{number}, converted to an integer by rounding upward -(towards positive infinity). - -@example -(ceiling 1.2) - @result{} 2 -(ceiling 1.7) - @result{} 2 -(ceiling -1.2) - @result{} -1 -(ceiling -1.7) - @result{} -1 -@end example -@end defun - -@defun round number &optional divisor -This returns @var{number}, converted to an integer by rounding towards the -nearest integer. Rounding a value equidistant between two integers -may choose the integer closer to zero, or it may prefer an even integer, -depending on your machine. - -@example -(round 1.2) - @result{} 1 -(round 1.7) - @result{} 2 -(round -1.2) - @result{} -1 -(round -1.7) - @result{} -2 -@end example -@end defun - -@node Arithmetic Operations -@section Arithmetic Operations -@cindex arithmetic operations - - Emacs Lisp provides the traditional four arithmetic operations: -addition, subtraction, multiplication, and division. Remainder and modulus -functions supplement the division functions. The functions to -add or subtract 1 are provided because they are traditional in Lisp and -commonly used. - - All of these functions except @code{%} return a floating point value -if any argument is floating. - - It is important to note that in Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 268435455)} may evaluate to -@minus{}268435456, depending on your hardware. - -@defun 1+ number-or-marker -This function returns @var{number-or-marker} plus 1. -For example, - -@example -(setq foo 4) - @result{} 4 -(1+ foo) - @result{} 5 -@end example - -This function is not analogous to the C operator @code{++}---it does not -increment a variable. It just computes a sum. Thus, if we continue, - -@example -foo - @result{} 4 -@end example - -If you want to increment the variable, you must use @code{setq}, -like this: - -@example -(setq foo (1+ foo)) - @result{} 5 -@end example -@end defun - -@defun 1- number-or-marker -This function returns @var{number-or-marker} minus 1. -@end defun - -@defun + &rest numbers-or-markers -This function adds its arguments together. When given no arguments, -@code{+} returns 0. - -@example -(+) - @result{} 0 -(+ 1) - @result{} 1 -(+ 1 2 3 4) - @result{} 10 -@end example -@end defun - -@defun - &optional number-or-marker &rest more-numbers-or-markers -The @code{-} function serves two purposes: negation and subtraction. -When @code{-} has a single argument, the value is the negative of the -argument. When there are multiple arguments, @code{-} subtracts each of -the @var{more-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. - -@example -(- 10 1 2 3 4) - @result{} 0 -(- 10) - @result{} -10 -(-) - @result{} 0 -@end example -@end defun - -@defun * &rest numbers-or-markers -This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. - -@example -(*) - @result{} 1 -(* 1) - @result{} 1 -(* 1 2 3 4) - @result{} 24 -@end example -@end defun - -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a -number or a marker. - -If all the arguments are integers, then the result is an integer too. -This means the result has to be rounded. On most machines, the result -is rounded towards zero after each division, but some machines may round -differently with negative arguments. This is because the Lisp function -@code{/} is implemented using the C division operator, which also -permits machine-dependent rounding. As a practical matter, all known -machines round in the standard fashion. - -@cindex @code{arith-error} in division -If you divide an integer by 0, an @code{arith-error} error is signaled. -(@xref{Errors}.) Floating point division by zero returns either -infinity or a NaN if your machine supports @acronym{IEEE} floating point; -otherwise, it signals an @code{arith-error} error. - -@example -@group -(/ 6 2) - @result{} 3 -@end group -(/ 5 2) - @result{} 2 -(/ 5.0 2) - @result{} 2.5 -(/ 5 2.0) - @result{} 2.5 -(/ 5.0 2.0) - @result{} 2.5 -(/ 25 3 2) - @result{} 4 -@group -(/ -17 6) - @result{} -2 @r{(could in theory be @minus{}3 on some machines)} -@end group -@end example -@end defun - -@defun % dividend divisor -@cindex remainder -This function returns the integer remainder after division of @var{dividend} -by @var{divisor}. The arguments must be integers or markers. - -For negative arguments, the remainder is in principle machine-dependent -since the quotient is; but in practice, all known machines behave alike. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -(% 9 4) - @result{} 1 -(% -9 4) - @result{} -1 -(% 9 -4) - @result{} 1 -(% -9 -4) - @result{} -1 -@end example - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}. -@end defun - -@defun mod dividend divisor -@cindex modulus -This function returns the value of @var{dividend} modulo @var{divisor}; -in other words, the remainder after division of @var{dividend} -by @var{divisor}, but with the same sign as @var{divisor}. -The arguments must be numbers or markers. - -Unlike @code{%}, @code{mod} returns a well-defined result for negative -arguments. It also permits floating point arguments; it rounds the -quotient downward (towards minus infinity) to an integer, and uses that -quotient to compute the remainder. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -@group -(mod 9 4) - @result{} 1 -@end group -@group -(mod -9 4) - @result{} 3 -@end group -@group -(mod 9 -4) - @result{} -3 -@end group -@group -(mod -9 -4) - @result{} -1 -@end group -@group -(mod 5.5 2.5) - @result{} .5 -@end group -@end example - -For any two numbers @var{dividend} and @var{divisor}, - -@example -@group -(+ (mod @var{dividend} @var{divisor}) - (* (floor @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric -Conversions}. -@end defun - -@node Rounding Operations -@section Rounding Operations -@cindex rounding without conversion - -The functions @code{ffloor}, @code{fceiling}, @code{fround}, and -@code{ftruncate} take a floating point argument and return a floating -point result whose value is a nearby integer. @code{ffloor} returns the -nearest integer below; @code{fceiling}, the nearest integer above; -@code{ftruncate}, the nearest integer in the direction towards zero; -@code{fround}, the nearest integer. - -@defun ffloor float -This function rounds @var{float} to the next lower integral value, and -returns that value as a floating point number. -@end defun - -@defun fceiling float -This function rounds @var{float} to the next higher integral value, and -returns that value as a floating point number. -@end defun - -@defun ftruncate float -This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating point number. -@end defun - -@defun fround float -This function rounds @var{float} to the nearest integral value, -and returns that value as a floating point number. -@end defun - -@node Bitwise Operations -@section Bitwise Operations on Integers -@cindex bitwise arithmetic -@cindex logical arithmetic - - In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -@dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over.'' - - The bitwise operations in Emacs Lisp apply only to integers. - -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. - -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. - -@example -@group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 -;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 -@end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): - -@example -@group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 -@end group -@end example - -On the other hand, shifting one place to the right looks like this: - -@example -@group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 -@end group - -@group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 -@end group -@end example - -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. - -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -268,435,455 produces @minus{}2 on a 29-bit machine: - -@example -(lsh 268435455 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, in the 29-bit implementation, the argument looks like this: - -@example -@group -;; @r{Decimal 268,435,455} -0 1111 1111 1111 1111 1111 1111 1111 -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1 1111 1111 1111 1111 1111 1111 1110 -@end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example -@group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1 1111 1111 1111 1111 1111 1111 1010 - @result{} -1 1111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: - -@example -@group -(lsh -6 -1) @result{} 268435453 -;; @r{Decimal @minus{}6 becomes decimal 268,435,453.} -1 1111 1111 1111 1111 1111 1111 1010 - @result{} -0 1111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -Here are other examples: - -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 -@smallexample -@group - ; @r{ 29-bit binary values} - -(lsh 5 2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{0 0000 0000 0000 0000 0000 0001 0100} -@end group -@group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{1 1111 1111 1111 1111 1111 1110 1100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{0 0000 0000 0000 0000 0000 0000 0001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} 134217726 ; = @r{0 0111 1111 1111 1111 1111 1111 1110} -@end group -@group -(ash -5 -2) ; -5 = @r{1 1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{1 1111 1111 1111 1111 1111 1111 1110} -@end group -@end smallexample -@end defun - -@defun logand &rest ints-or-markers -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) - -For example, using 4-bit binary numbers, the ``logical and'' of 13 and -12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. - -@noindent -Therefore, - -@example -@group -(logand 13 12) - @result{} 12 -@end group -@end example - -If @code{logand} is not passed any argument, it returns a value of -@minus{}1. This number is an identity element for @code{logand} -because its binary representation consists entirely of ones. If -@code{logand} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logand 14 13) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} - @result{} 12 ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} -@end group - -@group -(logand 14 13 4) ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} - ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} - @result{} 4 ; 4 = @r{0 0000 0000 0000 0000 0000 0000 0100} -@end group - -@group -(logand) - @result{} -1 ; -1 = @r{1 1111 1111 1111 1111 1111 1111 1111} -@end group -@end smallexample -@end defun - -@defun logior &rest ints-or-markers -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, -which is an identity element for this operation. If @code{logior} is -passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logior 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 13 ; 13 = @r{0 0000 0000 0000 0000 0000 0000 1101} -@end group - -@group -(logior 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} - @result{} 15 ; 15 = @r{0 0000 0000 0000 0000 0000 0000 1111} -@end group -@end smallexample -@end defun - -@defun logxor &rest ints-or-markers -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the -result is 0, which is an identity element for this operation. If -@code{logxor} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 29-bit binary values} - -(logxor 12 5) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - @result{} 9 ; 9 = @r{0 0000 0000 0000 0000 0000 0000 1001} -@end group - -@group -(logxor 12 5 7) ; 12 = @r{0 0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0 0000 0000 0000 0000 0000 0000 0111} - @result{} 14 ; 14 = @r{0 0000 0000 0000 0000 0000 0000 1110} -@end group -@end smallexample -@end defun - -@defun lognot integer -This function returns the logical complement of its argument: the @var{n}th -bit is one in the result if, and only if, the @var{n}th bit is zero in -@var{integer}, and vice-versa. - -@example -(lognot 5) - @result{} -6 -;; 5 = @r{0 0000 0000 0000 0000 0000 0000 0101} -;; @r{becomes} -;; -6 = @r{1 1111 1111 1111 1111 1111 1111 1010} -@end example -@end defun - -@node Math Functions -@section Standard Mathematical Functions -@cindex transcendental functions -@cindex mathematical functions -@cindex floating-point functions - - These mathematical functions allow integers as well as floating point -numbers as arguments. - -@defun sin arg -@defunx cos arg -@defunx tan arg -These are the ordinary trigonometric functions, with argument measured -in radians. -@end defun - -@defun asin arg -The value of @code{(asin @var{arg})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of -range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun acos arg -The value of @code{(acos @var{arg})} is a number between 0 and -@ifnottex -pi -@end ifnottex -@tex -@math{\pi} -@end tex -(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out -of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error. -@end defun - -@defun atan y &optional x -The value of @code{(atan @var{y})} is a number between -@ifnottex -@minus{}pi/2 -@end ifnottex -@tex -@math{-\pi/2} -@end tex -and -@ifnottex -pi/2 -@end ifnottex -@tex -@math{\pi/2} -@end tex -(exclusive) whose tangent is @var{y}. If the optional second -argument @var{x} is given, the value of @code{(atan y x)} is the -angle in radians between the vector @code{[@var{x}, @var{y}]} and the -@code{X} axis. -@end defun - -@defun exp arg -This is the exponential function; it returns -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -to the power @var{arg}. -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is a fundamental mathematical constant also called the base of natural -logarithms. -@end defun - -@defun log arg &optional base -This function returns the logarithm of @var{arg}, with base @var{base}. -If you don't specify @var{base}, the base -@tex -@math{e} -@end tex -@ifnottex -@i{e} -@end ifnottex -is used. If @var{arg} is negative, it signals a @code{domain-error} -error. -@end defun - -@ignore -@defun expm1 arg -This function returns @code{(1- (exp @var{arg}))}, but it is more -accurate than that when @var{arg} is negative and @code{(exp @var{arg})} -is close to 1. -@end defun - -@defun log1p arg -This function returns @code{(log (1+ @var{arg}))}, but it is more -accurate than that when @var{arg} is so small that adding 1 to it would -lose accuracy. -@end defun -@end ignore - -@defun log10 arg -This function returns the logarithm of @var{arg}, with base 10. If -@var{arg} is negative, it signals a @code{domain-error} error. -@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least -approximately. -@end defun - -@defun expt x y -This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. -@end defun - -@defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -it signals a @code{domain-error} error. -@end defun - -@node Random Numbers -@section Random Numbers -@cindex random numbers - -A deterministic computer program cannot generate true random numbers. -For most purposes, @dfn{pseudo-random numbers} suffice. A series of -pseudo-random numbers is generated in a deterministic fashion. The -numbers are not truly random, but they have certain properties that -mimic a random series. For example, all possible values occur equally -often in a pseudo-random series. - -In Emacs, pseudo-random numbers are generated from a ``seed'' number. -Starting from any given seed, the @code{random} function always -generates the same sequence of numbers. Emacs always starts with the -same seed value, so the sequence of values of @code{random} is actually -the same in each Emacs run! For example, in one operating system, the -first call to @code{(random)} after you start Emacs always returns -@minus{}1457731, and the second one always returns @minus{}7692030. This -repeatability is helpful for debugging. - -If you want random numbers that don't always come out the same, execute -@code{(random t)}. This chooses a new seed based on the current time of -day and on Emacs's process @acronym{ID} number. - -@defun random &optional limit -This function returns a pseudo-random integer. Repeated calls return a -series of pseudo-random integers. - -If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit}. - -If @var{limit} is @code{t}, it means to choose a new seed based on the -current time of day and on Emacs's process @acronym{ID} number. -@c "Emacs'" is incorrect usage! - -On some machines, any integer representable in Lisp may be the result -of @code{random}. On other machines, the result can never be larger -than a certain maximum or less than a certain (negative) minimum. -@end defun - -@ignore - arch-tag: 574e8dd2-d513-4616-9844-c9a27869782e -@end ignore diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi deleted file mode 100644 index 2145b9bcb93..00000000000 --- a/doc/lispref/objects.texi +++ /dev/null @@ -1,2101 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/objects -@node Lisp Data Types, Numbers, Introduction, Top -@chapter Lisp Data Types -@cindex object -@cindex Lisp object -@cindex type -@cindex data type - - A Lisp @dfn{object} is a piece of data used and manipulated by Lisp -programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of -possible objects. - - Every object belongs to at least one type. Objects of the same type -have similar structures and may usually be used in the same contexts. -Types can overlap, and objects can belong to two or more types. -Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. - -@cindex primitive type - A few fundamental object types are built into Emacs. These, from -which all other types are constructed, are called @dfn{primitive types}. -Each object belongs to one and only one primitive type. These types -include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{hash-table}, @dfn{subr}, and -@dfn{byte-code function}, plus several special types, such as -@dfn{buffer}, that are related to editing. (@xref{Editing Types}.) - - Each primitive type has a corresponding Lisp function that checks -whether an object is a member of that type. - - Lisp is unlike many other languages in that its objects are -@dfn{self-typing}: the primitive type of each object is implicit in -the object itself. For example, if an object is a vector, nothing can -treat it as a number; Lisp knows it is a vector, not a number. - - In most languages, the programmer must declare the data type of each -variable, and the type is known by the compiler but not represented in -the data. Such type declarations do not exist in Emacs Lisp. A Lisp -variable can have any type of value, and it remembers whatever value -you store in it, type and all. (Actually, a small number of Emacs -Lisp variables can only take on values of a certain type. -@xref{Variables with Restricted Values}.) - - This chapter describes the purpose, printed representation, and read -syntax of each of the standard types in GNU Emacs Lisp. Details on how -to use these types can be found in later chapters. - -@menu -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. -@end menu - -@node Printed Representation -@comment node-name, next, previous, up -@section Printed Representation and Read Syntax -@cindex printed representation -@cindex read syntax - - The @dfn{printed representation} of an object is the format of the -output generated by the Lisp printer (the function @code{prin1}) for -that object. Every data type has a unique printed representation. -The @dfn{read syntax} of an object is the format of the input accepted -by the Lisp reader (the function @code{read}) for that object. This -is not necessarily unique; many kinds of object have more than one -syntax. @xref{Read and Print}. - -@cindex hash notation - In most cases, an object's printed representation is also a read -syntax for the object. However, some types have no read syntax, since -it does not make sense to enter objects of these types as constants in -a Lisp program. These objects are printed in @dfn{hash notation}, -which consists of the characters @samp{#<}, a descriptive string -(typically the type name followed by the name of the object), and a -closing @samp{>}. For example: - -@example -(current-buffer) - @result{} # -@end example - -@noindent -Hash notation cannot be read at all, so the Lisp reader signals the -error @code{invalid-read-syntax} whenever it encounters @samp{#<}. -@kindex invalid-read-syntax - - In other languages, an expression is text; it has no other form. In -Lisp, an expression is primarily a Lisp object and only secondarily the -text that is the object's read syntax. Often there is no need to -emphasize this distinction, but you must keep it in the back of your -mind, or you will occasionally be very confused. - - When you evaluate an expression interactively, the Lisp interpreter -first reads the textual representation of it, producing a Lisp object, -and then evaluates that object (@pxref{Evaluation}). However, -evaluation and reading are separate activities. Reading returns the -Lisp object represented by the text that is read; the object may or may -not be evaluated later. @xref{Input Functions}, for a description of -@code{read}, the basic function for reading objects. - -@node Comments -@comment node-name, next, previous, up -@section Comments -@cindex comments -@cindex @samp{;} in comment - - A @dfn{comment} is text that is written in a program only for the sake -of humans that read the program, and that has no effect on the meaning -of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it -is not within a string or character constant. The comment continues to -the end of line. The Lisp reader discards comments; they do not become -part of the Lisp objects which represent the program within the Lisp -system. - - The @samp{#@@@var{count}} construct, which skips the next @var{count} -characters, is useful for program-generated comments containing binary -data. The Emacs Lisp byte compiler uses this in its output files -(@pxref{Byte Compilation}). It isn't meant for source files, however. - - @xref{Comment Tips}, for conventions for formatting comments. - -@node Programming Types -@section Programming Types -@cindex programming types - - There are two general categories of types in Emacs Lisp: those having -to do with Lisp programming, and those having to do with editing. The -former exist in many Lisp implementations, in one form or another. The -latter are unique to Emacs Lisp. - -@menu -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. -@end menu - -@node Integer Type -@subsection Integer Type - - The range of values for integers in Emacs Lisp is @minus{}268435456 to -268435455 (29 bits; i.e., -@ifnottex --2**28 -@end ifnottex -@tex -@math{-2^{28}} -@end tex -to -@ifnottex -2**28 - 1) -@end ifnottex -@tex -@math{2^{28}-1}) -@end tex -on most machines. (Some machines may provide a wider range.) It is -important to note that the Emacs Lisp arithmetic functions do not check -for overflow. Thus @code{(1+ 268435455)} is @minus{}268435456 on most -machines. - - The read syntax for integers is a sequence of (base ten) digits with an -optional sign at the beginning and an optional period at the end. The -printed representation produced by the Lisp interpreter never has a -leading @samp{+} or a final @samp{.}. - -@example -@group --1 ; @r{The integer -1.} -1 ; @r{The integer 1.} -1. ; @r{Also the integer 1.} -+1 ; @r{Also the integer 1.} -536870913 ; @r{Also the integer 1 on a 29-bit implementation.} -@end group -@end example - - @xref{Numbers}, for more information. - -@node Floating Point Type -@subsection Floating Point Type - - Floating point numbers are the computer equivalent of scientific -notation; you can think of a floating point number as a fraction -together with a power of ten. The precise number of significant -figures and the range of possible exponents is machine-specific; Emacs -uses the C data type @code{double} to store the value, and internally -this records a power of 2 rather than a power of 10. - - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point -number whose value is 1500. They are all equivalent. - - @xref{Numbers}, for more information. - -@node Character Type -@subsection Character Type -@cindex @acronym{ASCII} character codes - - A @dfn{character} in Emacs Lisp is nothing more than an integer. In -other words, characters are represented by their character codes. For -example, the character @kbd{A} is represented as the @w{integer 65}. - - Individual characters are used occasionally in programs, but it is -more common to work with @emph{strings}, which are sequences composed -of characters. @xref{String Type}. - - Characters in strings and buffers are currently limited to the range -of 0 to 4194303---twenty two bits (@pxref{Character Codes}). Codes 0 -through 127 are @acronym{ASCII} codes; the rest are -non-@acronym{ASCII} (@pxref{Non-ASCII Characters}). Characters that -represent keyboard input have a much wider range, to encode modifier -keys such as Control, Meta and Shift. - - There are special functions for producing a human-readable textual -description of a character for the sake of messages. @xref{Describing -Characters}. - -@menu -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. -@end menu - -@node Basic Char Syntax -@subsubsection Basic Char Syntax -@cindex read syntax for characters -@cindex printed representation for characters -@cindex syntax for characters -@cindex @samp{?} in character constant -@cindex question mark in character constant - - Since characters are really integers, the printed representation of -a character is a decimal number. This is also a possible read syntax -for a character, but writing characters that way in Lisp programs is -not clear programming. You should @emph{always} use the special read -syntax formats that Emacs Lisp provides for characters. These syntax -formats start with a question mark. - - The usual read syntax for alphanumeric characters is a question mark -followed by the character; thus, @samp{?A} for the character -@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the -character @kbd{a}. - - For example: - -@example -?Q @result{} 81 ?q @result{} 113 -@end example - - You can use the same syntax for punctuation characters, but it is -often a good idea to add a @samp{\} so that the Emacs commands for -editing Lisp code don't get confused. For example, @samp{?\(} is the -way to write the open-paren character. If the character is @samp{\}, -you @emph{must} use a second @samp{\} to quote it: @samp{?\\}. - -@cindex whitespace -@cindex bell character -@cindex @samp{\a} -@cindex backspace -@cindex @samp{\b} -@cindex tab (ASCII character) -@cindex @samp{\t} -@cindex vertical tab -@cindex @samp{\v} -@cindex formfeed -@cindex @samp{\f} -@cindex newline -@cindex @samp{\n} -@cindex return (ASCII character) -@cindex @samp{\r} -@cindex escape (ASCII character) -@cindex @samp{\e} -@cindex space (ASCII character) -@cindex @samp{\s} - You can express the characters control-g, backspace, tab, newline, -vertical tab, formfeed, space, return, del, and escape as @samp{?\a}, -@samp{?\b}, @samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, -@samp{?\s}, @samp{?\r}, @samp{?\d}, and @samp{?\e}, respectively. -(@samp{?\s} followed by a dash has a different meaning---it applies -the ``super'' modifier to the following character.) Thus, - -@example -?\a @result{} 7 ; @r{control-g, @kbd{C-g}} -?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} -?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} -?\n @result{} 10 ; @r{newline, @kbd{C-j}} -?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} -?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} -?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} -?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} -?\s @result{} 32 ; @r{space character, @key{SPC}} -?\\ @result{} 92 ; @r{backslash character, @kbd{\}} -?\d @result{} 127 ; @r{delete character, @key{DEL}} -@end example - -@cindex escape sequence - These sequences which start with backslash are also known as -@dfn{escape sequences}, because backslash plays the role of an -``escape character''; this terminology has nothing to do with the -character @key{ESC}. @samp{\s} is meant for use in character -constants; in string constants, just write the space. - - A backslash is allowed, and harmless, preceding any character without -a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. -There is no reason to add a backslash before most characters. However, -you should add a backslash before any of the characters -@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing -Lisp code. You can also add a backslash before whitespace characters such as -space, tab, newline and formfeed. However, it is cleaner to use one of -the easily readable escape sequences, such as @samp{\t} or @samp{\s}, -instead of an actual whitespace character such as a tab or a space. -(If you do write backslash followed by a space, you should write -an extra space after the character constant to separate it from the -following text.) - -@node General Escape Syntax -@subsubsection General Escape Syntax - - In addition to the specific escape sequences for special important -control characters, Emacs provides several types of escape syntax that -you can use to specify non-ASCII text characters. - -@cindex unicode character escape - You can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character that maps to the Unicode -code point @samp{U+@var{nnnn}} (by convention, Unicode code points are -given in hexadecimal). There is a slightly different syntax for -specifying characters with code points higher than -@code{U+@var{ffff}}: @code{\U00@var{nnnnnn}} represents the character -whose code point is @samp{U+@var{nnnnnn}}. The Unicode Standard only -defines code points up to @samp{U+@var{10ffff}}, so if you specify a -code point higher than that, Emacs signals an error. - - This peculiar and inconvenient syntax was adopted for compatibility -with other programming languages. Unlike some other languages, Emacs -Lisp supports this syntax only in character literals and strings. - -@cindex @samp{\} in character constant -@cindex backslash in character constant -@cindex octal character code - The most general read syntax for a character represents the -character code in either octal or hex. To use octal, write a question -mark followed by a backslash and the octal character code (up to three -octal digits); thus, @samp{?\101} for the character @kbd{A}, -@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the -character @kbd{C-b}. Although this syntax can represent any -@acronym{ASCII} character, it is preferred only when the precise octal -value is more important than the @acronym{ASCII} representation. - -@example -@group -?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 -?\101 @result{} 65 ?A @result{} 65 -@end group -@end example - - To use hex, write a question mark followed by a backslash, @samp{x}, -and the hexadecimal character code. You can use any number of hex -digits, so you can represent any character code in this way. -Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the -character @kbd{C-a}, and @code{?\x8e0} for the Latin-1 character -@iftex -@samp{@`a}. -@end iftex -@ifnottex -@samp{a} with grave accent. -@end ifnottex - -@node Ctl-Char Syntax -@subsubsection Control-Character Syntax - -@cindex control characters - Control characters can be represented using yet another read syntax. -This consists of a question mark followed by a backslash, caret, and the -corresponding non-control character, in either upper or lower case. For -example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the -character @kbd{C-i}, the character whose value is 9. - - Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is -equivalent to @samp{?\^I} and to @samp{?\^i}: - -@example -?\^I @result{} 9 ?\C-I @result{} 9 -@end example - - In strings and buffers, the only control characters allowed are those -that exist in @acronym{ASCII}; but for keyboard input purposes, you can turn -any character into a control character with @samp{C-}. The character -codes for these non-@acronym{ASCII} control characters include the -@tex -@math{2^{26}} -@end tex -@ifnottex -2**26 -@end ifnottex -bit as well as the code for the corresponding non-control -character. Ordinary terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using X -and other window systems. - - For historical reasons, Emacs treats the @key{DEL} character as -the control equivalent of @kbd{?}: - -@example -?\^? @result{} 127 ?\C-? @result{} 127 -@end example - -@noindent -As a result, it is currently not possible to represent the character -@kbd{Control-?}, which is a meaningful input character under X, using -@samp{\C-}. It is not easy to change this, as various Lisp files refer -to @key{DEL} in this way. - - For representing control characters to be found in files or strings, -we recommend the @samp{^} syntax; for control characters in keyboard -input, we prefer the @samp{C-} syntax. Which one you use does not -affect the meaning of the program, but may guide the understanding of -people who read it. - -@node Meta-Char Syntax -@subsubsection Meta-Character Syntax - -@cindex meta characters - A @dfn{meta character} is a character typed with the @key{META} -modifier key. The integer that represents such a character has the -@tex -@math{2^{27}} -@end tex -@ifnottex -2**27 -@end ifnottex -bit set. We use high bits for this and other modifiers to make -possible a wide range of basic character codes. - - In a string, the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit attached to an @acronym{ASCII} character indicates a meta -character; thus, the meta characters that can fit in a string have -codes in the range from 128 to 255, and are the meta versions of the -ordinary @acronym{ASCII} characters. (In Emacs versions 18 and older, -this convention was used for characters outside of strings as well.) - - The read syntax for meta characters uses @samp{\M-}. For example, -@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with -octal character codes (see below), with @samp{\C-}, or with any other -syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, -or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as -@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. - -@node Other Char Bits -@subsubsection Other Character Modifier Bits - - The case of a graphic character is indicated by its character code; -for example, @acronym{ASCII} distinguishes between the characters @samp{a} -and @samp{A}. But @acronym{ASCII} has no way to represent whether a control -character is upper case or lower case. Emacs uses the -@tex -@math{2^{25}} -@end tex -@ifnottex -2**25 -@end ifnottex -bit to indicate that the shift key was used in typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary terminals do not report the -distinction to the computer in any way. The Lisp syntax for -the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} -represents the shifted-control-o character. - -@cindex hyper characters -@cindex super characters -@cindex alt characters - The X Window System defines three other -@anchor{modifier bits}modifier bits that can be set -in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes -for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is -significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents -@kbd{Alt-Hyper-Meta-x}. (Note that @samp{\s} with no following @samp{-} -represents the space character.) -@tex -Numerically, the bit values are @math{2^{22}} for alt, @math{2^{23}} -for super and @math{2^{24}} for hyper. -@end tex -@ifnottex -Numerically, the -bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. -@end ifnottex - -@node Symbol Type -@subsection Symbol Type - - A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The -symbol name serves as the printed representation of the symbol. In -ordinary Lisp use, with one single obarray (@pxref{Creating Symbols}), -a symbol's name is unique---no two symbols have the same name. - - A symbol can serve as a variable, as a function name, or to hold a -property list. Or it may serve only to be distinct from all other Lisp -objects, so that its presence in a data structure may be recognized -reliably. In a given context, usually only one of these uses is -intended. But you can use one symbol in all of these ways, -independently. - - A symbol whose name starts with a colon (@samp{:}) is called a -@dfn{keyword symbol}. These symbols automatically act as constants, and -are normally used only by comparing an unknown symbol with a few -specific alternatives. - -@cindex @samp{\} in symbols -@cindex backslash in symbols - A symbol name can contain any characters whatever. Most symbol names -are written with letters, digits, and the punctuation characters -@samp{-+=*/}. Such names require no special punctuation; the characters -of the name suffice as long as the name does not look like a number. -(If it does, write a @samp{\} at the beginning of the name to force -interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}?} are -less often used but also require no special punctuation. Any other -characters may be included in a symbol's name by escaping them with a -backslash. In contrast to its use in strings, however, a backslash in -the name of a symbol simply quotes the single character that follows the -backslash. For example, in a string, @samp{\t} represents a tab -character; in the name of a symbol, however, @samp{\t} merely quotes the -letter @samp{t}. To have a symbol with a tab character in its name, you -must actually use a tab (preceded with a backslash). But it's rare to -do such a thing. - -@cindex CL note---case of letters -@quotation -@b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs -Lisp, upper case and lower case letters are distinct. -@end quotation - - Here are several examples of symbol names. Note that the @samp{+} in -the fifth example is escaped to prevent it from being read as a number. -This is not necessary in the fourth example because the rest of the name -makes it invalid as a number. - -@example -@group -foo ; @r{A symbol named @samp{foo}.} -FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -char-to-string ; @r{A symbol named @samp{char-to-string}.} -@end group -@group -1+ ; @r{A symbol named @samp{1+}} - ; @r{(not @samp{+1}, which is an integer).} -@end group -@group -\+1 ; @r{A symbol named @samp{+1}} - ; @r{(not a very readable name).} -@end group -@group -\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} -@c the @'s in this next line use up three characters, hence the -@c apparent misalignment of the comment. -+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} - ; @r{These characters need not be escaped.} -@end group -@end example - -@ifinfo -@c This uses ``colon'' instead of a literal `:' because Info cannot -@c cope with a `:' in a menu -@cindex @samp{#@var{colon}} read syntax -@end ifinfo -@ifnotinfo -@cindex @samp{#:} read syntax -@end ifnotinfo - Normally the Lisp reader interns all symbols (@pxref{Creating -Symbols}). To prevent interning, you can write @samp{#:} before the -name of the symbol. - -@node Sequence Type -@subsection Sequence Types - - A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp, lists and -arrays. Thus, an object of type list or of type array is also -considered a sequence. - - Arrays are further subdivided into strings, vectors, char-tables and -bool-vectors. Vectors can hold elements of any type, but string -elements must be characters, and bool-vector elements must be @code{t} -or @code{nil}. Char-tables are like vectors except that they are -indexed by any valid character code. The characters in a string can -have text properties like characters in a buffer (@pxref{Text -Properties}), but vectors do not support text properties, even when -their elements happen to be characters. - - Lists, strings and the other array types are different, but they have -important similarities. For example, all have a length @var{l}, and all -have elements which can be indexed from zero to @var{l} minus one. -Several functions, called sequence functions, accept any kind of -sequence. For example, the function @code{elt} can be used to extract -an element of a sequence, given its index. @xref{Sequences Arrays -Vectors}. - - It is generally impossible to read the same sequence twice, since -sequences are always created anew upon reading. If you read the read -syntax for a sequence twice, you get two sequences with equal contents. -There is one exception: the empty list @code{()} always stands for the -same object, @code{nil}. - -@node Cons Cell Type -@subsection Cons Cell and List Types -@cindex address field of register -@cindex decrement field of register -@cindex pointers - - A @dfn{cons cell} is an object that consists of two slots, called the -@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or -@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of -this cons cell is'' whatever object its @sc{car} slot currently holds, -and likewise for the @sc{cdr}. - -@quotation -A note to C programmers: in Lisp, we do not distinguish between -``holding'' a value and ``pointing to'' the value, because pointers in -Lisp are implicit. -@end quotation - - A @dfn{list} is a series of cons cells, linked together so that the -@sc{cdr} slot of each cons cell holds either the next cons cell or the -empty list. The empty list is actually the symbol @code{nil}. -@xref{Lists}, for functions that work on lists. Because most cons -cells are used as part of lists, the phrase @dfn{list structure} has -come to refer to any structure made out of cons cells. - -@cindex atoms - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell.'' These objects are called -@dfn{atoms}. - -@cindex parenthesis -@cindex @samp{(@dots{})} in lists - The read syntax and printed representation for lists are identical, and -consist of a left parenthesis, an arbitrary number of elements, and a -right parenthesis. Here are examples of lists: - -@example -(A 2 "A") ; @r{A list of three elements.} -() ; @r{A list of no elements (the empty list).} -nil ; @r{A list of no elements (the empty list).} -("A ()") ; @r{A list of one element: the string @code{"A ()"}.} -(A ()) ; @r{A list of two elements: @code{A} and the empty list.} -(A nil) ; @r{Equivalent to the previous.} -((A B C)) ; @r{A list of one element} - ; @r{(which is a list of three elements).} -@end example - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} slot of the cons cell holds the element, and its @sc{cdr} -slot refers to the next cons cell of the list, which holds the next -element in the list. The @sc{cdr} slot of the last cons cell is set to -hold @code{nil}. - - The names @sc{car} and @sc{cdr} derive from the history of Lisp. The -original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of -the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named -for the function @code{cons} that creates them, which in turn was named -for its purpose, the construction of cells. - -@menu -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. -@end menu - -@node Box Diagrams -@subsubsection Drawing Lists as Box Diagrams -@cindex box diagrams, for lists -@cindex diagrams, boxed, for lists - - A list can be illustrated by a diagram in which the cons cells are -shown as pairs of boxes, like dominoes. (The Lisp reader cannot read -such an illustration; unlike the textual notation, which can be -understood by both humans and computers, the box illustrations can be -understood only by humans.) This picture represents the three-element -list @code{(rose violet buttercup)}: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example - - In this diagram, each box represents a slot that can hold or refer to -any Lisp object. Each pair of boxes represents a cons cell. Each arrow -represents a reference to a Lisp object, either an atom or another cons -cell. - - In this example, the first box, which holds the @sc{car} of the first -cons cell, refers to or ``holds'' @code{rose} (a symbol). The second -box, holding the @sc{cdr} of the first cons cell, refers to the next -pair of boxes, the second cons cell. The @sc{car} of the second cons -cell is @code{violet}, and its @sc{cdr} is the third cons cell. The -@sc{cdr} of the third (and last) cons cell is @code{nil}. - - Here is another diagram of the same list, @code{(rose violet -buttercup)}, sketched in a different manner: - -@smallexample -@group - --------------- ---------------- ------------------- -| car | cdr | | car | cdr | | car | cdr | -| rose | o-------->| violet | o-------->| buttercup | nil | -| | | | | | | | | - --------------- ---------------- ------------------- -@end group -@end smallexample - -@cindex @code{nil} as a list -@cindex empty list - A list with no elements in it is the @dfn{empty list}; it is identical -to the symbol @code{nil}. In other words, @code{nil} is both a symbol -and a list. - - Here is the list @code{(A ())}, or equivalently @code{(A nil)}, -depicted with boxes and arrows: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> A --> nil -@end group -@end example - - Here is a more complex illustration, showing the three-element list, -@code{((pine needles) oak maple)}, the first element of which is a -two-element list: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | --> oak --> maple - | - | --- --- --- --- - --> | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> pine --> needles -@end group -@end example - - The same list represented in the second box notation looks like this: - -@example -@group - -------------- -------------- -------------- -| car | cdr | | car | cdr | | car | cdr | -| o | o------->| oak | o------->| maple | nil | -| | | | | | | | | | - -- | --------- -------------- -------------- - | - | - | -------------- ---------------- - | | car | cdr | | car | cdr | - ------>| pine | o------->| needles | nil | - | | | | | | - -------------- ---------------- -@end group -@end example - -@node Dotted Pair Notation -@subsubsection Dotted Pair Notation -@cindex dotted pair notation -@cindex @samp{.} in lists - - @dfn{Dotted pair notation} is a general syntax for cons cells that -represents the @sc{car} and @sc{cdr} explicitly. In this syntax, -@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is -the object @var{a} and whose @sc{cdr} is the object @var{b}. Dotted -pair notation is more general than list syntax because the @sc{cdr} -does not have to be a list. However, it is more cumbersome in cases -where list syntax would work. In dotted pair notation, the list -@samp{(1 2 3)} is written as @samp{(1 . (2 . (3 . nil)))}. For -@code{nil}-terminated lists, you can use either notation, but list -notation is usually clearer and more convenient. When printing a -list, the dotted pair notation is only used if the @sc{cdr} of a cons -cell is not a list. - - Here's an example using boxes to illustrate dotted pair notation. -This example shows the pair @code{(rose . violet)}: - -@example -@group - --- --- - | | |--> violet - --- --- - | - | - --> rose -@end group -@end example - - You can combine dotted pair notation with list notation to represent -conveniently a chain of cons cells with a non-@code{nil} final @sc{cdr}. -You write a dot after the last element of the list, followed by the -@sc{cdr} of the final cons cell. For example, @code{(rose violet -. buttercup)} is equivalent to @code{(rose . (violet . buttercup))}. -The object looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> buttercup - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - The syntax @code{(rose .@: violet .@: buttercup)} is invalid because -there is nothing that it could mean. If anything, it would say to put -@code{buttercup} in the @sc{cdr} of a cons cell whose @sc{cdr} is already -used for @code{violet}. - - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))}, -and looks like this: - -@example -@group - --- --- --- --- - | | |--> | | |--> nil - --- --- --- --- - | | - | | - --> rose --> violet -@end group -@end example - - Similarly, the three-element list @code{(rose violet buttercup)} -is equivalent to @code{(rose . (violet . (buttercup)))}. -@ifnottex -It looks like this: - -@example -@group - --- --- --- --- --- --- - | | |--> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example -@end ifnottex - -@node Association List Type -@comment node-name, next, previous, up -@subsubsection Association List Type - - An @dfn{association list} or @dfn{alist} is a specially-constructed -list whose elements are cons cells. In each element, the @sc{car} is -considered a @dfn{key}, and the @sc{cdr} is considered an -@dfn{associated value}. (In some cases, the associated value is stored -in the @sc{car} of the @sc{cdr}.) Association lists are often used as -stacks, since it is easy to add or remove associations at the front of -the list. - - For example, - -@example -(setq alist-of-colors - '((rose . red) (lily . white) (buttercup . yellow))) -@end example - -@noindent -sets the variable @code{alist-of-colors} to an alist of three elements. In the -first element, @code{rose} is the key and @code{red} is the value. - - @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. @xref{Hash Tables}, for another kind of -lookup table, which is much faster for handling a large number of keys. - -@node Array Type -@subsection Array Type - - An @dfn{array} is composed of an arbitrary number of slots for -holding or referring to other Lisp objects, arranged in a contiguous block of -memory. Accessing any element of an array takes approximately the same -amount of time. In contrast, accessing an element of a list requires -time proportional to the position of the element in the list. (Elements -at the end of a list take longer to access than elements at the -beginning of a list.) - - Emacs defines four types of array: strings, vectors, bool-vectors, and -char-tables. - - A string is an array of characters and a vector is an array of -arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}. -These kinds of array may have any length up to the largest integer. -Char-tables are sparse arrays indexed by any valid character code; they -can hold arbitrary objects. - - The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. The -largest possible index value is one less than the length of the array. -Once an array is created, its length is fixed. - - All Emacs Lisp arrays are one-dimensional. (Most other programming -languages support multidimensional arrays, but they are not essential; -you can get the same effect with nested one-dimensional arrays.) Each -type of array has its own read syntax; see the following sections for -details. - - The array type is a subset of the sequence type, and contains the -string type, the vector type, the bool-vector type, and the char-table -type. - -@node String Type -@subsection String Type - - A @dfn{string} is an array of characters. Strings are used for many -purposes in Emacs, as can be expected in a text editor; for example, as -the names of Lisp symbols, as messages for the user, and to represent -text extracted from buffers. Strings in Lisp are constants: evaluation -of a string returns the same string. - - @xref{Strings and Characters}, for functions that operate on strings. - -@menu -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. -@end menu - -@node Syntax for Strings -@subsubsection Syntax for Strings - -@cindex @samp{"} in strings -@cindex double-quote in strings -@cindex @samp{\} in strings -@cindex backslash in strings - The read syntax for a string is a double-quote, an arbitrary number -of characters, and another double-quote, @code{"like this"}. To -include a double-quote in a string, precede it with a backslash; thus, -@code{"\""} is a string containing just a single double-quote -character. Likewise, you can include a backslash by preceding it with -another backslash, like this: @code{"this \\ is a single embedded -backslash"}. - -@cindex newline in strings - The newline character is not special in the read syntax for strings; -if you write a new line between the double-quotes, it becomes a -character in the string. But an escaped newline---one that is preceded -by @samp{\}---does not become part of the string; i.e., the Lisp reader -ignores an escaped newline while reading a string. An escaped space -@w{@samp{\ }} is likewise ignored. - -@example -"It is useful to include newlines -in documentation strings, -but the newline is \ -ignored if escaped." - @result{} "It is useful to include newlines -in documentation strings, -but the newline is ignored if escaped." -@end example - -@node Non-ASCII in Strings -@subsubsection Non-@acronym{ASCII} Characters in Strings - - You can include a non-@acronym{ASCII} international character in a string -constant by writing it literally. There are two text representations -for non-@acronym{ASCII} characters in Emacs strings (and in buffers): unibyte -and multibyte. If the string constant is read from a multibyte source, -such as a multibyte buffer or string, or a file that would be visited as -multibyte, then the character is read as a multibyte character, and that -makes the string multibyte. If the string constant is read from a -unibyte source, then the character is read as unibyte and that makes the -string unibyte. - - You can also represent a multibyte non-@acronym{ASCII} character with its -character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many -digits as necessary. (Multibyte non-@acronym{ASCII} character codes are all -greater than 256.) Any character which is not a valid hex digit -terminates this construct. If the next character in the string could be -interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to -terminate the hex escape---for example, @w{@samp{\x8e0\ }} represents -one character, @samp{a} with grave accent. @w{@samp{\ }} in a string -constant is just like backslash-newline; it does not contribute any -character to the string, but it does terminate the preceding hex escape. - - You can represent a unibyte non-@acronym{ASCII} character with its -character code, which must be in the range from 128 (0200 octal) to -255 (0377 octal). If you write all such character codes in octal and -the string contains no other characters forcing it to be multibyte, -this produces a unibyte string. However, using any hex escape in a -string (even for an @acronym{ASCII} character) forces the string to be -multibyte. - - You can also specify characters in a string by their numeric values -in Unicode, using @samp{\u} and @samp{\U} (@pxref{Character Type}). - - @xref{Text Representations}, for more information about the two -text representations. - -@node Nonprinting Characters -@subsubsection Nonprinting Characters in Strings - - You can use the same backslash escape-sequences in a string constant -as in character literals (but do not use the question mark that begins a -character constant). For example, you can write a string containing the -nonprinting characters tab and @kbd{C-a}, with commas and spaces between -them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a -description of the read syntax for characters. - - However, not all of the characters you can write with backslash -escape-sequences are valid in strings. The only control characters that -a string can hold are the @acronym{ASCII} control characters. Strings do not -distinguish case in @acronym{ASCII} control characters. - - Properly speaking, strings cannot hold meta characters; but when a -string is to be used as a key sequence, there is a special convention -that provides a way to represent meta versions of @acronym{ASCII} -characters in a string. If you use the @samp{\M-} syntax to indicate -a meta character in a string constant, this sets the -@tex -@math{2^{7}} -@end tex -@ifnottex -2**7 -@end ifnottex -bit of the character in the string. If the string is used in -@code{define-key} or @code{lookup-key}, this numeric code is translated -into the equivalent meta character. @xref{Character Type}. - - Strings cannot hold characters that have the hyper, super, or alt -modifiers. - -@node Text Props and Strings -@subsubsection Text Properties in Strings - -@cindex @samp{#(} read syntax -@cindex text properties, read syntax - A string can hold properties for the characters it contains, in -addition to the characters themselves. This enables programs that copy -text between strings and buffers to copy the text's properties with no -special effort. @xref{Text Properties}, for an explanation of what text -properties mean. Strings with text properties use a special read and -print syntax: - -@example -#("@var{characters}" @var{property-data}...) -@end example - -@noindent -where @var{property-data} consists of zero or more elements, in groups -of three as follows: - -@example -@var{beg} @var{end} @var{plist} -@end example - -@noindent -The elements @var{beg} and @var{end} are integers, and together specify -a range of indices in the string; @var{plist} is the property list for -that range. For example, - -@example -#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic)) -@end example - -@noindent -represents a string whose textual contents are @samp{foo bar}, in which -the first three characters have a @code{face} property with value -@code{bold}, and the last three have a @code{face} property with value -@code{italic}. (The fourth character has no text properties, so its -property list is @code{nil}. It is not actually necessary to mention -ranges with @code{nil} as the property list, since any characters not -mentioned in any range will default to having no properties.) - -@node Vector Type -@subsection Vector Type - - A @dfn{vector} is a one-dimensional array of elements of any type. It -takes a constant amount of time to access any element of a vector. (In -a list, the access time of an element is proportional to the distance of -the element from the beginning of the list.) - - The printed representation of a vector consists of a left square -bracket, the elements, and a right square bracket. This is also the -read syntax. Like numbers and strings, vectors are considered constants -for evaluation. - -@example -[1 "two" (three)] ; @r{A vector of three elements.} - @result{} [1 "two" (three)] -@end example - - @xref{Vectors}, for functions that work with vectors. - -@node Char-Table Type -@subsection Char-Table Type - - A @dfn{char-table} is a one-dimensional array of elements of any type, -indexed by character codes. Char-tables have certain extra features to -make them more useful for many jobs that involve assigning information -to character codes---for example, a char-table can have a parent to -inherit from, a default value, and a small number of extra slots to use for -special purposes. A char-table can also specify a single value for -a whole character set. - - The printed representation of a char-table is like a vector -except that there is an extra @samp{#^} at the beginning. - - @xref{Char-Tables}, for special functions to operate on char-tables. -Uses of char-tables include: - -@itemize @bullet -@item -Case tables (@pxref{Case Tables}). - -@item -Character category tables (@pxref{Categories}). - -@item -Display tables (@pxref{Display Tables}). - -@item -Syntax tables (@pxref{Syntax Tables}). -@end itemize - -@node Bool-Vector Type -@subsection Bool-Vector Type - - A @dfn{bool-vector} is a one-dimensional array of elements that -must be @code{t} or @code{nil}. - - The printed representation of a bool-vector is like a string, except -that it begins with @samp{#&} followed by the length. The string -constant that follows actually specifies the contents of the bool-vector -as a bitmap---each ``character'' in the string contains 8 bits, which -specify the next 8 elements of the bool-vector (1 stands for @code{t}, -and 0 for @code{nil}). The least significant bits of the character -correspond to the lowest indices in the bool-vector. - -@example -(make-bool-vector 3 t) - @result{} #&3"^G" -(make-bool-vector 3 nil) - @result{} #&3"^@@" -@end example - -@noindent -These results make sense, because the binary code for @samp{C-g} is -111 and @samp{C-@@} is the character with code 0. - - If the length is not a multiple of 8, the printed representation -shows extra elements, but these extras really make no difference. For -instance, in the next example, the two bool-vectors are equal, because -only the first 3 bits are used: - -@example -(equal #&3"\377" #&3"\007") - @result{} t -@end example - -@node Hash Table Type -@subsection Hash Table Type - - A hash table is a very fast kind of lookup table, somewhat like an -alist in that it maps keys to corresponding values, but much faster. -Hash tables have no read syntax, and print using hash notation. -@xref{Hash Tables}, for functions that operate on hash tables. - -@example -(make-hash-table) - @result{} # -@end example - -@node Function Type -@subsection Function Type - - Lisp functions are executable code, just like functions in other -programming languages. In Lisp, unlike most languages, functions are -also Lisp objects. A non-compiled function in Lisp is a lambda -expression: that is, a list whose first element is the symbol -@code{lambda} (@pxref{Lambda Expressions}). - - In most programming languages, it is impossible to have a function -without a name. In Lisp, a function has no intrinsic name. A lambda -expression can be called as a function even though it has no name; to -emphasize this, we also call it an @dfn{anonymous function} -(@pxref{Anonymous Functions}). A named function in Lisp is just a -symbol with a valid function in its function cell (@pxref{Defining -Functions}). - - Most of the time, functions are called when their names are written in -Lisp expressions in Lisp programs. However, you can construct or obtain -a function object at run time and then call it with the primitive -functions @code{funcall} and @code{apply}. @xref{Calling Functions}. - -@node Macro Type -@subsection Macro Type - - A @dfn{Lisp macro} is a user-defined construct that extends the Lisp -language. It is represented as an object much like a function, but with -different argument-passing semantics. A Lisp macro has the form of a -list whose first element is the symbol @code{macro} and whose @sc{cdr} -is a Lisp function object, including the @code{lambda} symbol. - - Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation -of how to write a macro. - - @strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard -Macros}) are entirely different things. When we use the word ``macro'' -without qualification, we mean a Lisp macro, not a keyboard macro. - -@node Primitive Function Type -@subsection Primitive Function Type -@cindex primitive function - - A @dfn{primitive function} is a function callable from Lisp but -written in the C programming language. Primitive functions are also -called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine.'') Most primitive functions evaluate all -their arguments when they are called. A primitive function that does -not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}).@refill - - It does not matter to the caller of a function whether the function is -primitive. However, this does matter if you try to redefine a primitive -with a function written in Lisp. The reason is that the primitive -function may be called directly from C code. Calls to the redefined -function from Lisp will use the new definition, but calls from C code -may still use the built-in definition. Therefore, @strong{we discourage -redefinition of primitive functions}. - - The term @dfn{function} refers to all Emacs functions, whether written -in Lisp or C. @xref{Function Type}, for information about the -functions written in Lisp. - - Primitive functions have no read syntax and print in hash notation -with the name of the subroutine. - -@example -@group -(symbol-function 'car) ; @r{Access the function cell} - ; @r{of the symbol.} - @result{} # -(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} - @result{} t ; @r{Yes.} -@end group -@end example - -@node Byte-Code Type -@subsection Byte-Code Function Type - -The byte compiler produces @dfn{byte-code function objects}. -Internally, a byte-code function object is much like a vector; however, -the evaluator handles this data type specially when it appears as a -function to be called. @xref{Byte Compilation}, for information about -the byte compiler. - -The printed representation and read syntax for a byte-code function -object is like that for a vector, with an additional @samp{#} before the -opening @samp{[}. - -@node Autoload Type -@subsection Autoload Type - - An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol, -where it serves as a placeholder for the real definition. The autoload -object says that the real definition is found in a file of Lisp code -that should be loaded when necessary. It contains the name of the file, -plus some other information about the real definition. - - After the file has been loaded, the symbol should have a new function -definition that is not an autoload object. The new definition is then -called as if it had been there to begin with. From the user's point of -view, the function call works as expected, using the function definition -in the loaded file. - - An autoload object is usually created with the function -@code{autoload}, which stores the object in the function cell of a -symbol. @xref{Autoload}, for more details. - -@node Editing Types -@section Editing Types -@cindex editing types - - The types in the previous section are used for general programming -purposes, and most of them are common to most Lisp dialects. Emacs Lisp -provides several additional data types for purposes connected with -editing. - -@menu -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. -@end menu - -@node Buffer Type -@subsection Buffer Type - - A @dfn{buffer} is an object that holds text that can be edited -(@pxref{Buffers}). Most buffers hold the contents of a disk file -(@pxref{Files}) so they can be edited, but some are used for other -purposes. Most buffers are also meant to be seen by the user, and -therefore displayed, at some time, in a window (@pxref{Windows}). But -a buffer need not be displayed in any window. Each buffer has a -designated position called @dfn{point} (@pxref{Positions}); most -editing commands act on the contents of the current buffer in the -neighborhood of point. At any time, one buffer is the @dfn{current -buffer}. - - The contents of a buffer are much like a string, but buffers are not -used like strings in Emacs Lisp, and the available operations are -different. For example, you can insert text efficiently into an -existing buffer, altering the buffer's contents, whereas ``inserting'' -text into a string requires concatenating substrings, and the result -is an entirely new string object. - - Many of the standard Emacs functions manipulate or test the -characters in the current buffer; a whole chapter in this manual is -devoted to describing these functions (@pxref{Text}). - - Several other data structures are associated with each buffer: - -@itemize @bullet -@item -a local syntax table (@pxref{Syntax Tables}); - -@item -a local keymap (@pxref{Keymaps}); and, - -@item -a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}). - -@item -overlays (@pxref{Overlays}). - -@item -text properties for the text in the buffer (@pxref{Text Properties}). -@end itemize - -@noindent -The local keymap and variable list contain entries that individually -override global bindings or values. These are used to customize the -behavior of programs in different buffers, without actually changing the -programs. - - A buffer may be @dfn{indirect}, which means it shares the text -of another buffer, but presents it differently. @xref{Indirect Buffers}. - - Buffers have no read syntax. They print in hash notation, showing the -buffer name. - -@example -@group -(current-buffer) - @result{} # -@end group -@end example - -@node Marker Type -@subsection Marker Type - - A @dfn{marker} denotes a position in a specific buffer. Markers -therefore have two components: one for the buffer, and one for the -position. Changes in the buffer's text automatically relocate the -position value as necessary to ensure that the marker always points -between the same two characters in the buffer. - - Markers have no read syntax. They print in hash notation, giving the -current character position and the name of the buffer. - -@example -@group -(point-marker) - @result{} # -@end group -@end example - -@xref{Markers}, for information on how to test, create, copy, and move -markers. - -@node Window Type -@subsection Window Type - - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. - - Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. - - Windows have no read syntax. They print in hash notation, giving the -window number and the name of the buffer being displayed. The window -numbers exist to identify windows uniquely, since the buffer displayed -in any given window can change frequently. - -@example -@group -(selected-window) - @result{} # -@end group -@end example - - @xref{Windows}, for a description of the functions that work on windows. - -@node Frame Type -@subsection Frame Type - - A @dfn{frame} is a screen area that contains one or more Emacs -windows; we also use the term ``frame'' to refer to the Lisp object -that Emacs uses to refer to the screen area. - - Frames have no read syntax. They print in hash notation, giving the -frame's title, plus its address in core (useful to identify the frame -uniquely). - -@example -@group -(selected-frame) - @result{} # -@end group -@end example - - @xref{Frames}, for a description of the functions that work on frames. - -@node Terminal Type -@subsection Terminal Type -@cindex terminal type - - A @dfn{terminal} is a device capable of displaying one or more -Emacs frames (@pxref{Frame Type}). - - Terminals have no read syntax. They print in hash notation giving -the terminal's ordinal number and its TTY device file name. - -@example -@group -(get-device-terminal nil) - @result{} # -@end group -@end example - -@c FIXME: add an xref to where terminal-related primitives are described. - -@node Window Configuration Type -@subsection Window Configuration Type -@cindex window layout in a frame - - A @dfn{window configuration} stores information about the positions, -sizes, and contents of the windows in a frame, so you can recreate the -same arrangement of windows later. - - Window configurations do not have a read syntax; their print syntax -looks like @samp{#}. @xref{Window -Configurations}, for a description of several functions related to -window configurations. - -@node Frame Configuration Type -@subsection Frame Configuration Type -@cindex screen layout -@cindex window layout, all frames - - A @dfn{frame configuration} stores information about the positions, -sizes, and contents of the windows in all frames. It is not a -primitive type---it is actually a list whose @sc{car} is -@code{frame-configuration} and whose @sc{cdr} is an alist. Each alist -element describes one frame, which appears as the @sc{car} of that -element. - - @xref{Frame Configurations}, for a description of several functions -related to frame configurations. - -@node Process Type -@subsection Process Type - - The word @dfn{process} usually means a running program. Emacs itself -runs in a process of this sort. However, in Emacs Lisp, a process is a -Lisp object that designates a subprocess created by the Emacs process. -Programs such as shells, GDB, ftp, and compilers, running in -subprocesses of Emacs, extend the capabilities of Emacs. - - An Emacs subprocess takes textual input from Emacs and returns textual -output to Emacs for further manipulation. Emacs can also send signals -to the subprocess. - - Process objects have no read syntax. They print in hash notation, -giving the name of the process: - -@example -@group -(process-list) - @result{} (#) -@end group -@end example - -@xref{Processes}, for information about functions that create, delete, -return information about, send input or signals to, and receive output -from processes. - -@node Stream Type -@subsection Stream Type - - A @dfn{stream} is an object that can be used as a source or sink for -characters---either to supply characters for input or to accept them as -output. Many different types can be used this way: markers, buffers, -strings, and functions. Most often, input streams (character sources) -obtain characters from the keyboard, a buffer, or a file, and output -streams (character sinks) send characters to a buffer, such as a -@file{*Help*} buffer, or to the echo area. - - The object @code{nil}, in addition to its other meanings, may be used -as a stream. It stands for the value of the variable -@code{standard-input} or @code{standard-output}. Also, the object -@code{t} as a stream specifies input using the minibuffer -(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo -Area}). - - Streams have no special printed representation or read syntax, and -print as whatever primitive type they are. - - @xref{Read and Print}, for a description of functions -related to streams, including parsing and printing functions. - -@node Keymap Type -@subsection Keymap Type - - A @dfn{keymap} maps keys typed by the user to commands. This mapping -controls how the user's command input is executed. A keymap is actually -a list whose @sc{car} is the symbol @code{keymap}. - - @xref{Keymaps}, for information about creating keymaps, handling prefix -keys, local as well as global keymaps, and changing key bindings. - -@node Overlay Type -@subsection Overlay Type - - An @dfn{overlay} specifies properties that apply to a part of a -buffer. Each overlay applies to a specified range of the buffer, and -contains a property list (a list whose elements are alternating property -names and values). Overlay properties are used to present parts of the -buffer temporarily in a different display style. Overlays have no read -syntax, and print in hash notation, giving the buffer name and range of -positions. - - @xref{Overlays}, for how to create and use overlays. - -@node Font Type -@subsection Font Type - - A @dfn{font} specifies how to display text on a graphical terminal. -There are actually three separate font types---@dfn{font objects}, -@dfn{font specs}, and @dfn{font entities}---each of which has slightly -different properties. None of them have a read syntax; their print -syntax looks like @samp{#}, @samp{#}, and -@samp{#} respectively. @xref{Low-Level Font}, for a -description of these Lisp objects. - -@node Circular Objects -@section Read Syntax for Circular Objects -@cindex circular structure, read syntax -@cindex shared structure, read syntax -@cindex @samp{#@var{n}=} read syntax -@cindex @samp{#@var{n}#} read syntax - - To represent shared or circular structures within a complex of Lisp -objects, you can use the reader constructs @samp{#@var{n}=} and -@samp{#@var{n}#}. - - Use @code{#@var{n}=} before an object to label it for later reference; -subsequently, you can use @code{#@var{n}#} to refer the same object in -another place. Here, @var{n} is some integer. For example, here is how -to make a list in which the first element recurs as the third element: - -@example -(#1=(a) b #1#) -@end example - -@noindent -This differs from ordinary syntax such as this - -@example -((a) b (a)) -@end example - -@noindent -which would result in a list whose first and third elements -look alike but are not the same Lisp object. This shows the difference: - -@example -(prog1 nil - (setq x '(#1=(a) b #1#))) -(eq (nth 0 x) (nth 2 x)) - @result{} t -(setq x '((a) b (a))) -(eq (nth 0 x) (nth 2 x)) - @result{} nil -@end example - - You can also use the same syntax to make a circular structure, which -appears as an ``element'' within itself. Here is an example: - -@example -#1=(a #1#) -@end example - -@noindent -This makes a list whose second element is the list itself. -Here's how you can see that it really works: - -@example -(prog1 nil - (setq x '#1=(a #1#))) -(eq x (cadr x)) - @result{} t -@end example - - The Lisp printer can produce this syntax to record circular and shared -structure in a Lisp object, if you bind the variable @code{print-circle} -to a non-@code{nil} value. @xref{Output Variables}. - -@node Type Predicates -@section Type Predicates -@cindex type checking -@kindex wrong-type-argument - - The Emacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. - - All built-in functions do check the types of their actual arguments -when appropriate, and signal a @code{wrong-type-argument} error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to @code{+} that it cannot handle: - -@example -@group -(+ 2 'a) - @error{} Wrong type argument: number-or-marker-p, a -@end group -@end example - -@cindex type predicates -@cindex testing types - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a @dfn{type predicate} function. Emacs has a -type predicate for each type, as well as some predicates for -combinations of types. - - A type predicate function takes one argument; it returns @code{t} if -the argument belongs to the appropriate type, and @code{nil} otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with @samp{p}. - - Here is an example which uses the predicates @code{listp} to check for -a list and @code{symbolp} to check for a symbol. - -@example -(defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) - (t - ;; We handle only symbols and lists. - (error "Invalid argument %s in add-on" x)))) -@end example - - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. - -@table @code -@item atom -@xref{List-related Predicates, atom}. - -@item arrayp -@xref{Array Functions, arrayp}. - -@item bool-vector-p -@xref{Bool-Vectors, bool-vector-p}. - -@item bufferp -@xref{Buffer Basics, bufferp}. - -@item byte-code-function-p -@xref{Byte-Code Type, byte-code-function-p}. - -@item case-table-p -@xref{Case Tables, case-table-p}. - -@item char-or-string-p -@xref{Predicates for Strings, char-or-string-p}. - -@item char-table-p -@xref{Char-Tables, char-table-p}. - -@item commandp -@xref{Interactive Call, commandp}. - -@item consp -@xref{List-related Predicates, consp}. - -@item display-table-p -@xref{Display Tables, display-table-p}. - -@item floatp -@xref{Predicates on Numbers, floatp}. - -@item fontp -@xref{Low-Level Font}. - -@item frame-configuration-p -@xref{Frame Configurations, frame-configuration-p}. - -@item frame-live-p -@xref{Deleting Frames, frame-live-p}. - -@item framep -@xref{Frames, framep}. - -@item functionp -@xref{Functions, functionp}. - -@item hash-table-p -@xref{Other Hash, hash-table-p}. - -@item integer-or-marker-p -@xref{Predicates on Markers, integer-or-marker-p}. - -@item integerp -@xref{Predicates on Numbers, integerp}. - -@item keymapp -@xref{Creating Keymaps, keymapp}. - -@item keywordp -@xref{Constant Variables}. - -@item listp -@xref{List-related Predicates, listp}. - -@item markerp -@xref{Predicates on Markers, markerp}. - -@item wholenump -@xref{Predicates on Numbers, wholenump}. - -@item nlistp -@xref{List-related Predicates, nlistp}. - -@item numberp -@xref{Predicates on Numbers, numberp}. - -@item number-or-marker-p -@xref{Predicates on Markers, number-or-marker-p}. - -@item overlayp -@xref{Overlays, overlayp}. - -@item processp -@xref{Processes, processp}. - -@item sequencep -@xref{Sequence Functions, sequencep}. - -@item stringp -@xref{Predicates for Strings, stringp}. - -@item subrp -@xref{Function Cells, subrp}. - -@item symbolp -@xref{Symbols, symbolp}. - -@item syntax-table-p -@xref{Syntax Tables, syntax-table-p}. - -@item user-variable-p -@xref{Defining Variables, user-variable-p}. - -@item vectorp -@xref{Vectors, vectorp}. - -@item window-configuration-p -@xref{Window Configurations, window-configuration-p}. - -@item window-live-p -@xref{Deleting Windows, window-live-p}. - -@item windowp -@xref{Basic Windows, windowp}. - -@item booleanp -@xref{nil and t, booleanp}. - -@item string-or-null-p -@xref{Predicates for Strings, string-or-null-p}. -@end table - - The most general way to check the type of an object is to call the -function @code{type-of}. Recall that each object belongs to one and -only one primitive type; @code{type-of} tells you which one (@pxref{Lisp -Data Types}). But @code{type-of} knows nothing about non-primitive -types. In most cases, it is more convenient to use type predicates than -@code{type-of}. - -@defun type-of object -This function returns a symbol naming the primitive type of -@var{object}. The value is one of the symbols @code{bool-vector}, -@code{buffer}, @code{char-table}, @code{compiled-function}, -@code{cons}, @code{float}, @code{font-entity}, @code{font-object}, -@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, -@code{marker}, @code{overlay}, @code{process}, @code{string}, -@code{subr}, @code{symbol}, @code{vector}, @code{window}, or -@code{window-configuration}. - -@example -(type-of 1) - @result{} integer -@group -(type-of 'nil) - @result{} symbol -(type-of '()) ; @r{@code{()} is @code{nil}.} - @result{} symbol -(type-of '(x)) - @result{} cons -@end group -@end example -@end defun - -@node Equality Predicates -@section Equality Predicates -@cindex equality - - Here we describe functions that test for equality between any two -objects. Other functions test equality of contents between objects of specific -types, e.g., strings. For these predicates, see the appropriate chapter -describing the data type. - -@defun eq object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} are -the same object, @code{nil} otherwise. - -@code{eq} returns @code{t} if @var{object1} and @var{object2} are -integers with the same value. Also, since symbol names are normally -unique, if the arguments are symbols with the same name, they are -@code{eq}. For other types (e.g., lists, vectors, strings), two -arguments with the same contents or elements are not necessarily -@code{eq} to each other: they are @code{eq} only if they are the same -object, meaning that a change in the contents of one will be reflected -by the same change in the contents of the other. - -@example -@group -(eq 'foo 'foo) - @result{} t -@end group - -@group -(eq 456 456) - @result{} t -@end group - -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(eq "" "") - @result{} t -;; @r{This exception occurs because Emacs Lisp} -;; @r{makes just one multibyte empty string, to save space.} -@end group - -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(setq foo '(1 (2 (3)))) - @result{} (1 (2 (3))) -(eq foo foo) - @result{} t -(eq foo '(1 (2 (3)))) - @result{} nil -@end group - -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -The @code{make-symbol} function returns an uninterned symbol, distinct -from the symbol that is used if you write the name in a Lisp expression. -Distinct symbols with the same name are not @code{eq}. @xref{Creating -Symbols}. - -@example -@group -(eq (make-symbol "foo") 'foo) - @result{} nil -@end group -@end example -@end defun - -@defun equal object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} have -equal components, @code{nil} otherwise. Whereas @code{eq} tests if its -arguments are the same object, @code{equal} looks inside nonidentical -arguments to see if their elements or contents are the same. So, if two -objects are @code{eq}, they are @code{equal}, but the converse is not -always true. - -@example -@group -(equal 'foo 'foo) - @result{} t -@end group - -@group -(equal 456 456) - @result{} t -@end group - -@group -(equal "asdf" "asdf") - @result{} t -@end group -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(equal '(1 (2 (3))) '(1 (2 (3)))) - @result{} t -@end group -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(equal [(1 2) 3] [(1 2) 3]) - @result{} t -@end group -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(equal (point-marker) (point-marker)) - @result{} t -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -Comparison of strings is case-sensitive, but does not take account of -text properties---it compares only the characters in the strings. Use -@code{equal-including-properties} to also compare text properties. For -technical reasons, a unibyte string and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -(@pxref{Text Representations}). - -@example -@group -(equal "asdf" "ASDF") - @result{} nil -@end group -@end example - -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. -@end defun - - The test for equality is implemented recursively; for example, given -two cons cells @var{x} and @var{y}, @code{(equal @var{x} @var{y})} -returns @code{t} if and only if both the expressions below return -@code{t}: - -@example -(equal (car @var{x}) (car @var{y})) -(equal (cdr @var{x}) (cdr @var{y})) -@end example - -Because of this recursive method, circular lists may therefore cause -infinite recursion (leading to an error). - -@defun equal-including-properties object1 object2 -This function behaves like @code{equal} in all cases but also requires -that for two strings to be equal, they have the same text properties. - -@example -@group -(equal "asdf" (propertize "asdf" '(asdf t))) - @result{} t -@end group -@group -(equal-including-properties "asdf" - (propertize "asdf" '(asdf t))) - @result{} nil -@end group -@end example -@end defun - -@ignore - arch-tag: 9711a66e-4749-4265-9e8c-972d55b67096 -@end ignore diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi deleted file mode 100644 index c535307b802..00000000000 --- a/doc/lispref/os.texi +++ /dev/null @@ -1,2190 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/os -@node System Interface, Antinews, Display, Top -@chapter Operating System Interface - - This chapter is about starting and getting out of Emacs, access to -values in the operating system environment, and terminal input, output, -and flow control. - - @xref{Building Emacs}, for related information. @xref{Display}, for -additional operating system status information pertaining to the -terminal and the screen. - -@menu -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with X Session Management. -@end menu - -@node Starting Up -@section Starting Up Emacs - - This section describes what Emacs does when it is started, and how you -can customize these actions. - -@menu -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. -@end menu - -@node Startup Summary -@subsection Summary: Sequence of Actions at Startup -@cindex initialization of Emacs -@cindex startup of Emacs -@cindex @file{startup.el} - - When Emacs is started up, it performs the following operations -(which are defined in @file{startup.el}): - -@enumerate -@item -It adds subdirectories to @code{load-path}, by running the file named -@file{subdirs.el} in each directory in the list. Normally, this file -adds the directory's subdirectories to the list, and those are scanned -in their turn. The files @file{subdirs.el} are normally generated -automatically when Emacs is installed. - -@vindex before-init-time -@item -It sets the variable @code{before-init-time} to the value of -@code{current-time} (@pxref{Time of Day}). It also sets -@code{after-init-time} to @code{nil}, which signals to Lisp programs -that Emacs is being initialized. - -@vindex initial-window-system@r{, and startup} -@vindex window-system-initialization-alist -@item -It loads the initialization library for the window system specified by -the variable @code{initial-window-system} (@pxref{Window Systems, -initial-window-system}). This library's name is -@file{term/@var{windowsystem}-win.el}, where @var{windowsystem} is the -value of @code{initial-window-system}. From that library, it calls -the appropriate initialization function. The initialization function -for each supported window system is specified by -@code{window-system-initialization-alist}. - -@item -It sets the language environment and the terminal coding system, -if requested by environment variables such as @code{LANG}. - -@item -It processes the initial options. (Some of them are handled -even earlier than this.) - -@item -It runs the normal hook @code{before-init-hook}. - -@item -It initializes the window frame and faces, if appropriate, and turns -on the menu bar and tool bar, if the initial frame needs them. - -@item -It loads the library @file{site-start}, if it exists. This is not -done if the options @samp{-Q} or @samp{--no-site-file} were specified. -@cindex @file{site-start.el} - -@item -It loads your init file (@pxref{Init File}). This is not done if the -options @samp{-q}, @samp{-Q}, or @samp{--batch} were specified. If -the @samp{-u} option was specified, Emacs looks for the init file in -that user's home directory instead. - -@item -It loads the library @file{default}, if it exists. This is not done -if @code{inhibit-default-init} is non-@code{nil}, nor if the options -@samp{-q}, @samp{-Q}, or @samp{--batch} were specified. -@cindex @file{default.el} - -@item -It loads your abbrevs from the file specified by -@code{abbrev-file-name}, if that file exists and can be read -(@pxref{Abbrev Files, abbrev-file-name}). This is not done if the -option @samp{--batch} was specified. - -@vindex after-init-time -@item -It sets the variable @code{after-init-time} to the value of -@code{current-time}. This variable was set to @code{nil} earlier; -setting it to the current time signals that the initialization phase -is over, and, together with @code{before-init-time}, provides the -measurement of how long it took. - -@item -It runs the normal hook @code{after-init-hook}. - -@item -If the buffer @samp{*scratch*} exists and is still in Fundamental mode -(as it should be by default), it sets its major mode according to -@code{initial-major-mode}. - -@item -If started on a text-only terminal, it loads the terminal-specific -Lisp library, which is specified by the variable -@code{term-file-prefix} (@pxref{Terminal-Specific}). This is not done -in @code{--batch} mode, nor if @code{term-file-prefix} is @code{nil}. - -@item -It displays the initial echo area message, unless you have suppressed -that with @code{inhibit-startup-echo-area-message}. - -@item -It processes the action arguments from the command line. - -@item -It now exits if the option @code{--batch} was specified. - -@item -If @code{initial-buffer-choice} is a string, it visits the file with -that name. Furthermore, if the @samp{*scratch*} buffer exists and is -empty, it inserts @code{initial-scratch-message} into that buffer. - -@item -It runs @code{emacs-startup-hook} and then @code{term-setup-hook}. - -@item -It calls @code{frame-notice-user-settings}, which modifies the -parameters of the selected frame according to whatever the init files -specify. - -@item -It runs @code{window-setup-hook}. @xref{Window Systems}. - -@item -If the option @code{--daemon} was specified, it calls -@code{server-start} and detaches from the controlling terminal. -@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. - -@item -It displays the @dfn{startup screen}, which is a special buffer that -contains information about copyleft and basic Emacs usage. This is -not done if @code{initial-buffer-choice} or -@code{inhibit-startup-screen} are @code{nil}, nor if the -@samp{--no-splash} or @samp{-Q} command-line options were specified. - -@item -If started by the X session manager, it calls -@code{emacs-session-restore} passing it as argument the ID of the -previous session. @xref{Session Management}. -@end enumerate - -@defopt inhibit-startup-screen -This variable, if non-@code{nil}, inhibits the startup screen. In -that case, Emacs typically displays the @samp{*scratch*} buffer; but -see @code{initial-buffer-choice}, below. - -Do not set this variable in the init file of a new user, or in a way -that affects more than one user, as that would prevent new users from -receiving information about copyleft and basic Emacs usage. - -@code{inhibit-startup-message} and @code{inhibit-splash-screen} are -aliases for this variable. -@end defopt - -@defopt initial-buffer-choice -This variable, if non-@code{nil}, determines a file or buffer for -Emacs to display after starting up, instead of the startup screen. If -its value is @code{t}, Emacs displays the @samp{*scratch*} buffer. If -its value is a string, that specifies the name of a file for Emacs to -visit. -@end defopt - -@defopt inhibit-startup-echo-area-message -This variable controls the display of the startup echo area message. -You can suppress the startup echo area message by adding text with this -form to your init file: - -@example -(setq inhibit-startup-echo-area-message - "@var{your-login-name}") -@end example - -Emacs explicitly checks for an expression as shown above in your init -file; your login name must appear in the expression as a Lisp string -constant. Other methods of setting -@code{inhibit-startup-echo-area-message} to the same value do not -inhibit the startup message. This way, you can easily inhibit the -message for yourself if you wish, but thoughtless copying of your init -file will not inhibit the message for someone else. -@end defopt - -@defopt initial-scratch-message -This variable, if non-@code{nil}, should be a string, which is -inserted into the @samp{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @samp{*scratch*} buffer is empty. -@end defopt - -@node Init File -@subsection The Init File, @file{.emacs} -@cindex init file -@cindex @file{.emacs} - - When you start Emacs, it normally attempts to load your @dfn{init -file}. This is either a file named @file{.emacs} or @file{.emacs.el} -in your home directory, or a file named @file{init.el} in a -subdirectory named @file{.emacs.d} in your home directory. Whichever -place you use, you can also compile the file (@pxref{Byte -Compilation}); then the actual file loaded will be @file{.emacs.elc} -or @file{init.elc}. - - The command-line switches @samp{-q}, @samp{-Q}, and @samp{-u} -control whether and where to find the init file; @samp{-q} (and the -stronger @samp{-Q}) says not to load an init file, while @samp{-u -@var{user}} says to load @var{user}'s init file instead of yours. -@xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If neither -option is specified, Emacs uses the @code{LOGNAME} environment -variable, or the @code{USER} (most systems) or @code{USERNAME} (MS -systems) variable, to find your home directory and thus your init -file; this way, even if you have su'd, Emacs still loads your own init -file. If those environment variables are absent, though, Emacs uses -your user-id to find your home directory. - -@cindex default init file - A site may have a @dfn{default init file}, which is the library -named @file{default.el}. Emacs finds the @file{default.el} file -through the standard search path for libraries (@pxref{How Programs Do -Loading}). The Emacs distribution does not come with this file; sites -may provide one for local customizations. If the default init file -exists, it is loaded whenever you start Emacs, except in batch mode or -if @samp{-q} (or @samp{-Q}) is specified. But your own personal init -file, if any, is loaded first; if it sets @code{inhibit-default-init} -to a non-@code{nil} value, then Emacs does not subsequently load the -@file{default.el} file. - - Another file for site-customization is @file{site-start.el}. Emacs -loads this @emph{before} the user's init file. You can inhibit the -loading of this file with the option @samp{--no-site-file}. - -@defopt site-run-file -This variable specifies the site-customization file to load before the -user's init file. Its normal value is @code{"site-start"}. The only -way you can change it with real effect is to do so before dumping -Emacs. -@end defopt - - @xref{Init Examples,, Init File Examples, emacs, The GNU Emacs Manual}, for -examples of how to make various commonly desired customizations in your -@file{.emacs} file. - -@defopt inhibit-default-init -This variable prevents Emacs from loading the default initialization -library file for your session of Emacs. If its value is non-@code{nil}, -then the default library is not loaded. The default value is -@code{nil}. -@end defopt - -@defvar before-init-hook -This normal hook is run, once, just before loading all the init files -(the user's init file, @file{default.el}, and/or @file{site-start.el}). -(The only way to change it with real effect is before dumping Emacs.) -@end defvar - -@defvar after-init-hook -This normal hook is run, once, just after loading all the init files -(the user's init file, @file{default.el}, and/or @file{site-start.el}), -before loading the terminal-specific library and processing the -command-line action arguments. -@end defvar - -@defvar emacs-startup-hook -This normal hook is run, once, just after handling the command line -arguments, just before @code{term-setup-hook}. -@end defvar - -@defvar user-init-file -This variable holds the absolute file name of the user's init file. If the -actual init file loaded is a compiled file, such as @file{.emacs.elc}, -the value refers to the corresponding source file. -@end defvar - -@defvar user-emacs-directory -This variable holds the name of the @file{.emacs.d} directory. It is -ordinarily @file{~/.emacs.d}, but differs on some platforms. -@end defvar - -@node Terminal-Specific -@subsection Terminal-Specific Initialization -@cindex terminal-specific initialization - - Each terminal type can have its own Lisp library that Emacs loads when -run on that type of terminal. The library's name is constructed by -concatenating the value of the variable @code{term-file-prefix} and the -terminal type (specified by the environment variable @code{TERM}). -Normally, @code{term-file-prefix} has the value -@code{"term/"}; changing this is not recommended. Emacs finds the file -in the normal manner, by searching the @code{load-path} directories, and -trying the @samp{.elc} and @samp{.el} suffixes. - -@cindex Termcap - The usual function of a terminal-specific library is to enable -special keys to send sequences that Emacs can recognize. It may also -need to set or add to @code{input-decode-map} if the Termcap or -Terminfo entry does not specify all the terminal's function keys. -@xref{Terminal Input}. - - When the name of the terminal type contains a hyphen, and no library -is found whose name is identical to the terminal's name, Emacs strips -from the terminal's name the last hyphen and everything that follows -it, and tries again. This process is repeated until Emacs finds a -matching library or until there are no more hyphens in the name (the -latter means the terminal doesn't have any library specific to it). -Thus, for example, if there are no @samp{aaa-48} and @samp{aaa-30} -libraries, Emacs will try the same library @file{term/aaa.el} for -terminal types @samp{aaa-48} and @samp{aaa-30-rv}. If necessary, the -library can evaluate @code{(getenv "TERM")} to find the full name of -the terminal type.@refill - - Your init file can prevent the loading of the -terminal-specific library by setting the variable -@code{term-file-prefix} to @code{nil}. This feature is useful when -experimenting with your own peculiar customizations. - - You can also arrange to override some of the actions of the -terminal-specific library by setting the variable -@code{term-setup-hook}. This is a normal hook which Emacs runs using -@code{run-hooks} at the end of Emacs initialization, after loading both -your init file and any terminal-specific libraries. You can -use this variable to define initializations for terminals that do not -have their own libraries. @xref{Hooks}. - -@defvar term-file-prefix -@cindex @code{TERM} environment variable -If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads -a terminal-specific initialization file as follows: - -@example -(load (concat term-file-prefix (getenv "TERM"))) -@end example - -@noindent -You may set the @code{term-file-prefix} variable to @code{nil} in your -init file if you do not wish to load the -terminal-initialization file. To do this, put the following in -your init file: @code{(setq term-file-prefix nil)}. - -On MS-DOS, if the environment variable @code{TERM} is not set, Emacs -uses @samp{internal} as the terminal type. -@end defvar - -@defvar term-setup-hook -This variable is a normal hook that Emacs runs after loading your -init file, the default initialization file (if any) and the -terminal-specific Lisp file. - -You can use @code{term-setup-hook} to override the definitions made by a -terminal-specific file. -@end defvar - - See @code{window-setup-hook} in @ref{Window Systems}, for a related -feature. - -@node Command-Line Arguments -@subsection Command-Line Arguments -@cindex command-line arguments - - You can use command-line arguments to request various actions when you -start Emacs. Since you do not need to start Emacs more than once per -day, and will often leave your Emacs session running longer than that, -command-line arguments are hardly ever used. As a practical matter, it -is best to avoid making the habit of using them, since this habit would -encourage you to kill and restart Emacs unnecessarily often. These -options exist for two reasons: to be compatible with other editors (for -invocation by other programs) and to enable shell scripts to run -specific Lisp programs. - - This section describes how Emacs processes command-line arguments, -and how you can customize them. - -@ignore - (Note that some other editors require you to start afresh each time -you want to edit a file. With this kind of editor, you will probably -specify the file as a command-line argument. The recommended way to -use GNU Emacs is to start it only once, just after you log in, and do -all your editing in the same Emacs process. Each time you want to edit -a different file, you visit it with the existing Emacs, which eventually -comes to have many files in it ready for editing. Usually you do not -kill the Emacs until you are about to log out.) -@end ignore - -@defun command-line -This function parses the command line that Emacs was called with, -processes it, loads the user's init file and displays the -startup messages. -@end defun - -@defvar command-line-processed -The value of this variable is @code{t} once the command line has been -processed. - -If you redump Emacs by calling @code{dump-emacs}, you may wish to set -this variable to @code{nil} first in order to cause the new dumped Emacs -to process its new command-line arguments. -@end defvar - -@defvar command-switch-alist -@cindex switches on command line -@cindex options on command line -@cindex command-line options -The value of this variable is an alist of user-defined command-line -options and associated handler functions. This variable exists so you -can add elements to it. - -A @dfn{command-line option} is an argument on the command line, which -has the form: - -@example --@var{option} -@end example - -The elements of the @code{command-switch-alist} look like this: - -@example -(@var{option} . @var{handler-function}) -@end example - -The @sc{car}, @var{option}, is a string, the name of a command-line -option (not including the initial hyphen). The @var{handler-function} -is called to handle @var{option}, and receives the option name as its -sole argument. - -In some cases, the option is followed in the command line by an -argument. In these cases, the @var{handler-function} can find all the -remaining command-line arguments in the variable -@code{command-line-args-left}. (The entire list of command-line -arguments is in @code{command-line-args}.) - -The command-line arguments are parsed by the @code{command-line-1} -function in the @file{startup.el} file. See also @ref{Emacs -Invocation, , Command Line Arguments for Emacs Invocation, emacs, The -GNU Emacs Manual}. -@end defvar - -@defvar command-line-args -The value of this variable is the list of command-line arguments passed -to Emacs. -@end defvar - -@defvar command-line-args-left -The value of this variable is the list of command-line arguments that -have not yet been processed. @code{argv} is an alias for this. -@end defvar - -@defvar command-line-functions -This variable's value is a list of functions for handling an -unrecognized command-line argument. Each time the next argument to be -processed has no special meaning, the functions in this list are called, -in order of appearance, until one of them returns a non-@code{nil} -value. - -These functions are called with no arguments. They can access the -command-line argument under consideration through the variable -@code{argi}, which is bound temporarily at this point. The remaining -arguments (not including the current one) are in the variable -@code{command-line-args-left}. - -When a function recognizes and processes the argument in @code{argi}, it -should return a non-@code{nil} value to say it has dealt with that -argument. If it has also dealt with some of the following arguments, it -can indicate that by deleting them from @code{command-line-args-left}. - -If all of these functions return @code{nil}, then the argument is used -as a file name to visit. -@end defvar - -@node Getting Out -@section Getting Out of Emacs -@cindex exiting Emacs - - There are two ways to get out of Emacs: you can kill the Emacs job, -which exits permanently, or you can suspend it, which permits you to -reenter the Emacs process later. As a practical matter, you seldom kill -Emacs---only when you are about to log out. Suspending is much more -common. - -@menu -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. -@end menu - -@node Killing Emacs -@comment node-name, next, previous, up -@subsection Killing Emacs -@cindex killing Emacs - - Killing Emacs means ending the execution of the Emacs process. The -parent process normally resumes control. The low-level primitive for -killing Emacs is @code{kill-emacs}. - -@deffn Command kill-emacs &optional exit-data -This command exits the Emacs process and kills it. - -If @var{exit-data} is an integer, then it is used as the exit status -of the Emacs process. (This is useful primarily in batch operation; see -@ref{Batch Mode}.) - -If @var{exit-data} is a string, its contents are stuffed into the -terminal input buffer so that the shell (or whatever program next reads -input) can read them. -@end deffn - - All the information in the Emacs process, aside from files that have -been saved, is lost when the Emacs process is killed. Because killing -Emacs inadvertently can lose a lot of work, Emacs queries for -confirmation before actually terminating if you have buffers that need -saving or subprocesses that are running. This is done in the function -@code{save-buffers-kill-emacs}, the higher level function from which -@code{kill-emacs} is usually called. - -@defvar kill-emacs-query-functions -After asking the standard questions, @code{save-buffers-kill-emacs} -calls the functions in the list @code{kill-emacs-query-functions}, in -order of appearance, with no arguments. These functions can ask for -additional confirmation from the user. If any of them returns -@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and -does not run the remaining functions in this hook. Calling -@code{kill-emacs} directly does not run this hook. -@end defvar - -@defvar kill-emacs-hook -This variable is a normal hook; once @code{save-buffers-kill-emacs} is -finished with all file saving and confirmation, it calls -@code{kill-emacs} which runs the functions in this hook. -@code{kill-emacs} does not run this hook in batch mode. - -@code{kill-emacs} may be invoked directly (that is not via -@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in -similar situations where interaction with the user is not possible. -Thus, if your hook needs to interact with the user, put it on -@code{kill-emacs-query-functions}; if it needs to run regardless of -how Emacs is killed, put it on @code{kill-emacs-hook}. -@end defvar - -@node Suspending Emacs -@subsection Suspending Emacs -@cindex suspending Emacs - - On text-only terminals, it is possible to @dfn{suspend Emacs}, which -means stopping Emacs temporarily and returning control to its superior -process, which is usually the shell. This allows you to resume -editing later in the same Emacs process, with the same buffers, the -same kill ring, the same undo history, and so on. To resume Emacs, -use the appropriate command in the parent shell---most likely -@code{fg}. - -@cindex controlling terminal - Suspending works only on a terminal device from which the Emacs -session was started. We call that device the @dfn{controlling -terminal} of the session. Suspending is not allowed if the -controlling terminal is a graphical terminal. - - Some operating systems do not support suspension of jobs; on these -systems, ``suspension'' actually creates a new shell temporarily as a -subprocess of Emacs. Then you would exit the shell to return to Emacs. - -@deffn Command suspend-emacs &optional string -This function stops Emacs and returns control to the superior process. -If and when the superior process resumes Emacs, @code{suspend-emacs} -returns @code{nil} to its caller in Lisp. - -This function works only on the controlling terminal of the Emacs -session; to relinquish control of other tty devices, use -@code{suspend-tty} (see below). If the Emacs session uses more than -one terminal, you must delete the frames on all the other terminals -before suspending Emacs, or this function signals an error. -@xref{Multiple Terminals}. - -If @var{string} is non-@code{nil}, its characters are sent to Emacs's -superior shell, to be read as terminal input. The characters in -@var{string} are not echoed by the superior shell; only the results -appear. - -Before suspending, @code{suspend-emacs} runs the normal hook -@code{suspend-hook}. After the user resumes Emacs, -@code{suspend-emacs} runs the normal hook @code{suspend-resume-hook}. -@xref{Hooks}. - -The next redisplay after resumption will redraw the entire screen, -unless the variable @code{no-redraw-on-reenter} is non-@code{nil}. -@xref{Refresh Screen}. - -In the following example, note that @samp{pwd} is not echoed after -Emacs is suspended. But it is read and executed by the shell. - -@smallexample -@group -(suspend-emacs) - @result{} nil -@end group - -@group -(add-hook 'suspend-hook - (function (lambda () - (or (y-or-n-p - "Really suspend? ") - (error "Suspend canceled"))))) - @result{} (lambda nil - (or (y-or-n-p "Really suspend? ") - (error "Suspend canceled"))) -@end group -@group -(add-hook 'suspend-resume-hook - (function (lambda () (message "Resumed!")))) - @result{} (lambda nil (message "Resumed!")) -@end group -@group -(suspend-emacs "pwd") - @result{} nil -@end group -@group ----------- Buffer: Minibuffer ---------- -Really suspend? @kbd{y} ----------- Buffer: Minibuffer ---------- -@end group - -@group ----------- Parent Shell ---------- -lewis@@slug[23] % /user/lewis/manual -lewis@@slug[24] % fg -@end group - -@group ----------- Echo Area ---------- -Resumed! -@end group -@end smallexample -@end deffn - -@defvar suspend-hook -This variable is a normal hook that Emacs runs before suspending. -@end defvar - -@defvar suspend-resume-hook -This variable is a normal hook that Emacs runs on resuming -after a suspension. -@end defvar - -@defun suspend-tty &optional tty -If @var{tty} specifies a terminal device used by Emacs, this function -relinquishes the device and restores it to its prior state. Frames -that used the device continue to exist, but are not updated and Emacs -doesn't read input from them. @var{tty} can be a terminal object, a -frame (meaning the terminal for that frame), or @code{nil} (meaning -the terminal for the selected frame). @xref{Multiple Terminals}. - -If @var{tty} is already suspended, this function does nothing. - -This function runs the hook @code{suspend-tty-functions}, passing the -terminal object as an argument to each function. -@end defun - -@defun resume-tty &optional tty -This function resumes the previously suspended terminal device -@var{tty}; @var{tty} can be a terminal object, a frame (meaning the -terminal for that frame), or @code{nil} (meaning the terminal for the -selected frame). - -This function reopens the terminal device, re-initializes it, and -redraws its with that terminal's selected frame. It then runs the -hook @code{resume-tty-functions}, passing the terminal object as an -argument to each function. - -If the same device is already used by another Emacs terminal, this -function signals an error. -@end defun - -@defun controlling-tty-p &optional terminal -This function returns non-@code{nil} if @var{terminal} is the -controlling terminal of the Emacs session; @code{terminal} can be a -terminal object, a frame (meaning the terminal for that frame), or -@code{nil} (meaning the terminal for the selected frame). -@end defun - -@deffn Command suspend-frame -This command @dfn{suspends} a frame. For GUI frames, it calls -@code{iconify-frame} (@pxref{Visibility of Frames}); for text-only -frames, it calls either @code{suspend-emacs} or @code{suspend-tty}, -depending on whether the frame is displayed on the controlling -terminal device or not. -@end deffn - -@node System Environment -@section Operating System Environment -@cindex operating system environment - - Emacs provides access to variables in the operating system environment -through various functions. These variables include the name of the -system, the user's @acronym{UID}, and so on. - -@defvar system-configuration -This variable holds the standard GNU configuration name for the -hardware/software configuration of your system, as a string. The -convenient way to test parts of this string is with -@code{string-match}. -@end defvar - -@cindex system type and name -@defvar system-type -The value of this variable is a symbol indicating the type of operating -system Emacs is operating on. Here is a table of the possible values: - -@table @code -@item aix -IBM's AIX. - -@item berkeley-unix -Berkeley BSD and its variants. - -@item cygwin -Cygwin, a Posix layer on top of MS-Windows. - -@item darwin -Darwin (Mac OS X). - -@item gnu -The GNU system (using the GNU kernel, which consists of the HURD and Mach). - -@item gnu/linux -A GNU/Linux system---that is, a variant GNU system, using the Linux -kernel. (These systems are the ones people often call ``Linux,'' but -actually Linux is just the kernel, not the whole system.) - -@item gnu/kfreebsd -A GNU (glibc-based) system with a FreeBSD kernel. - -@item hpux -Hewlett-Packard HPUX operating system. - -@item irix -Silicon Graphics Irix system. - -@item lynxos 3.0.1 -LynxOS-3.0.1. - -@item ms-dos -Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for -MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on -MS-Windows. - -@item usg-unix-v -AT&T Unix System V. - -@item windows-nt -Microsoft Windows NT and later. The same executable supports Windows -9X, but the value of @code{system-type} is @code{windows-nt} in either -case. - -@end table - -We do not wish to add new symbols to make finer distinctions unless it -is absolutely necessary! In fact, we hope to eliminate some of these -alternatives in the future. We recommend using -@code{system-configuration} to distinguish between different operating -systems. -@end defvar - -@defun system-name -This function returns the name of the machine you are running on. -@example -(system-name) - @result{} "www.gnu.org" -@end example -@end defun - - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - -@defopt mail-host-address -If this variable is non-@code{nil}, it is used instead of -@code{system-name} for purposes of generating email addresses. For -example, it is used when constructing the default value of -@code{user-mail-address}. @xref{User Identification}. (Since this is -done when Emacs starts up, the value actually used is the one saved when -Emacs was dumped. @xref{Building Emacs}.) -@end defopt - -@deffn Command getenv var &optional frame -@cindex environment variable access -This function returns the value of the environment variable @var{var}, -as a string. @var{var} should be a string. If @var{var} is undefined -in the environment, @code{getenv} returns @code{nil}. If returns -@samp{""} if @var{var} is set but null. Within Emacs, the environment -variable values are kept in the Lisp variable @code{process-environment}. - -@example -@group -(getenv "USER") - @result{} "lewis" -@end group - -@group -lewis@@slug[10] % printenv -PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin -USER=lewis -@end group -@group -TERM=ibmapa16 -SHELL=/bin/csh -HOME=/user/lewis -@end group -@end example -@end deffn - -@c Emacs 19 feature -@deffn Command setenv variable &optional value -This command sets the value of the environment variable named -@var{variable} to @var{value}. @var{variable} should be a string. -Internally, Emacs Lisp can handle any string. However, normally -@var{variable} should be a valid shell identifier, that is, a sequence -of letters, digits and underscores, starting with a letter or -underscore. Otherwise, errors may occur if subprocesses of Emacs try -to access the value of @var{variable}. If @var{value} is omitted or -@code{nil}, @code{setenv} removes @var{variable} from the environment. -Otherwise, @var{value} should be a string. - -@code{setenv} works by modifying @code{process-environment}; binding -that variable with @code{let} is also reasonable practice. - -@code{setenv} returns the new value of @var{variable}, or @code{nil} -if it removed @var{variable} from the environment. -@end deffn - -@defvar process-environment -This variable is a list of strings, each describing one environment -variable. The functions @code{getenv} and @code{setenv} work by means -of this variable. - -@smallexample -@group -process-environment -@result{} ("l=/usr/stanford/lib/gnuemacs/lisp" - "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" - "USER=lewis" -@end group -@group - "TERM=ibmapa16" - "SHELL=/bin/csh" - "HOME=/user/lewis") -@end group -@end smallexample - -If @code{process-environment} contains ``duplicate'' elements that -specify the same environment variable, the first of these elements -specifies the variable, and the other ``duplicates'' are ignored. -@end defvar - -@defvar initial-environment -This variable holds the list of environment variables Emacs inherited -from its parent process. It is computed during startup, see -@ref{Startup Summary}. -@end defvar - -@defvar path-separator -This variable holds a string which says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS -and MS-Windows. -@end defvar - -@defun parse-colon-path path -This function takes a search path string such as would be the value of -the @code{PATH} environment variable, and splits it at the separators, -returning a list of directory names. @code{nil} in this list stands for -``use the current directory.'' Although the function's name says -``colon,'' it actually uses the value of @code{path-separator}. - -@example -(parse-colon-path ":/foo:/bar") - @result{} (nil "/foo/" "/bar/") -@end example -@end defun - -@defvar invocation-name -This variable holds the program name under which Emacs was invoked. The -value is a string, and does not include a directory name. -@end defvar - -@defvar invocation-directory -This variable holds the directory from which the Emacs executable was -invoked, or perhaps @code{nil} if that directory cannot be determined. -@end defvar - -@defvar installation-directory -If non-@code{nil}, this is a directory within which to look for the -@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} -when Emacs can't find those directories in their standard installed -locations, but can find them in a directory related somehow to the one -containing the Emacs executable. -@end defvar - -@defun load-average &optional use-float -This function returns the current 1-minute, 5-minute, and 15-minute load -averages, in a list. - -By default, the values are integers that are 100 times the system load -averages, which indicate the average number of processes trying to run. -If @var{use-float} is non-@code{nil}, then they are returned -as floating point numbers and without multiplying by 100. - -If it is impossible to obtain the load average, this function signals -an error. On some platforms, access to load averages requires -installing Emacs as setuid or setgid so that it can read kernel -information, and that usually isn't advisable. - -If the 1-minute load average is available, but the 5- or 15-minute -averages are not, this function returns a shortened list containing -the available averages. - -@example -@group -(load-average) - @result{} (169 48 36) -@end group -@group -(load-average t) - @result{} (1.69 0.48 0.36) -@end group - -@group -lewis@@rocky[5] % uptime - 11:55am up 1 day, 19:37, 3 users, - load average: 1.69, 0.48, 0.36 -@end group -@end example -@end defun - -@defun emacs-pid -This function returns the process @acronym{ID} of the Emacs process, -as an integer. -@end defun - -@defvar tty-erase-char -This variable holds the erase character that was selected -in the system's terminal driver, before Emacs was started. -The value is @code{nil} if Emacs is running under a window system. -@end defvar - -@node User Identification -@section User Identification -@cindex user identification - -@defvar init-file-user -This variable says which user's init files should be used by -Emacs---or @code{nil} if none. @code{""} stands for the user who -originally logged in. The value reflects command-line options such as -@samp{-q} or @samp{-u @var{user}}. - -Lisp packages that load files of customizations, or any other sort of -user profile, should obey this variable in deciding where to find it. -They should load the profile of the user name found in this variable. -If @code{init-file-user} is @code{nil}, meaning that the @samp{-q} -option was used, then Lisp packages should not load any customization -files or user profile. -@end defvar - -@defopt user-mail-address -This holds the nominal email address of the user who is using Emacs. -Emacs normally sets this variable to a default value after reading your -init files, but not if you have already set it. So you can set the -variable to some other value in your init file if you do not -want to use the default value. -@end defopt - -@defun user-login-name &optional uid -If you don't specify @var{uid}, this function returns the name under -which the user is logged in. If the environment variable @code{LOGNAME} -is set, that value is used. Otherwise, if the environment variable -@code{USER} is set, that value is used. Otherwise, the value is based -on the effective @acronym{UID}, not the real @acronym{UID}. - -If you specify @var{uid}, the value is the user name that corresponds -to @var{uid} (which should be an integer), or @code{nil} if there is -no such user. - -@example -@group -(user-login-name) - @result{} "lewis" -@end group -@end example -@end defun - -@defun user-real-login-name -This function returns the user name corresponding to Emacs's real -@acronym{UID}. This ignores the effective @acronym{UID} and ignores the -environment variables @code{LOGNAME} and @code{USER}. -@end defun - -@defun user-full-name &optional uid -This function returns the full name of the logged-in user---or the value -of the environment variable @code{NAME}, if that is set. - -@c "Bil" is the correct spelling. -@example -@group -(user-full-name) - @result{} "Bil Lewis" -@end group -@end example - -If the Emacs job's user-id does not correspond to any known user (and -provided @code{NAME} is not set), the value is @code{"unknown"}. - -If @var{uid} is non-@code{nil}, then it should be a number (a user-id) -or a string (a login name). Then @code{user-full-name} returns the full -name corresponding to that user-id or login name. If you specify a -user-id or login name that isn't defined, it returns @code{nil}. -@end defun - -@vindex user-full-name -@vindex user-real-login-name -@vindex user-login-name - The symbols @code{user-login-name}, @code{user-real-login-name} and -@code{user-full-name} are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (@pxref{Frame -Titles}). - -@defun user-real-uid -This function returns the real @acronym{UID} of the user. -The value may be a floating point number. - -@example -@group -(user-real-uid) - @result{} 19 -@end group -@end example -@end defun - -@defun user-uid -This function returns the effective @acronym{UID} of the user. -The value may be a floating point number. -@end defun - -@node Time of Day -@section Time of Day - - This section explains how to determine the current time and the time -zone. - -@defun current-time-string &optional time-value -This function returns the current time and date as a human-readable -string. The format of the string is unvarying; the number of characters -used for each part is always the same, so you can reliably use -@code{substring} to extract pieces of it. It is wise to count the -characters from the beginning of the string rather than from the end, as -additional information may some day be added at the end. - -@c Emacs 19 feature -The argument @var{time-value}, if given, specifies a time to format -instead of the current time. The argument should be a list whose first -two elements are integers. Thus, you can use times obtained from -@code{current-time} (see below) and from @code{file-attributes} -(@pxref{Definition of file-attributes}). @var{time-value} can also be -a cons of two integers, but this is considered obsolete. - -@example -@group -(current-time-string) - @result{} "Wed Oct 14 22:21:05 1987" -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun current-time -This function returns the system's time value as a list of three -integers: @code{(@var{high} @var{low} @var{microsec})}. The integers -@var{high} and @var{low} combine to give the number of seconds since -0:00 January 1, 1970 UTC (Coordinated Universal Time), which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). - -The first two elements can be compared with file time values such as you -get with the function @code{file-attributes}. -@xref{Definition of file-attributes}. -@end defun - -@c Emacs 19 feature -@defun current-time-zone &optional time-value -This function returns a list describing the time zone that the user is -in. - -The value has the form @code{(@var{offset} @var{name})}. Here -@var{offset} is an integer giving the number of seconds ahead of UTC -(east of Greenwich). A negative value means west of Greenwich. The -second element, @var{name}, is a string giving the name of the time -zone. Both elements change when daylight saving time begins or ends; -if the user has specified a time zone that does not use a seasonal time -adjustment, then the value is constant through time. - -If the operating system doesn't supply all the information necessary to -compute the value, the unknown elements of the list are @code{nil}. - -The argument @var{time-value}, if given, specifies a time to analyze -instead of the current time. The argument should have the same form -as for @code{current-time-string} (see above). Thus, you can use -times obtained from @code{current-time} (see above) and from -@code{file-attributes}. @xref{Definition of file-attributes}. -@end defun - -@defun set-time-zone-rule tz -This function specifies the local time zone according to @var{tz}. If -@var{tz} is @code{nil}, that means to use an implementation-defined -default time zone. If @var{tz} is @code{t}, that means to use -Universal Time. Otherwise, @var{tz} should be a string specifying a -time zone rule. -@end defun - -@defun float-time &optional time-value -This function returns the current time as a floating-point number of -seconds since the epoch. The argument @var{time-value}, if given, -specifies a time to convert instead of the current time. The argument -should have the same form as for @code{current-time-string} (see -above). Thus, it accepts the output of @code{current-time} and -@code{file-attributes}. - -@emph{Warning}: Since the result is floating point, it may not be -exact. Do not use this function if precise time stamps are required. -@end defun - -@node Time Conversion -@section Time Conversion - - These functions convert time values (lists of two or three integers) -to calendrical information and vice versa. You can get time values -from the functions @code{current-time} (@pxref{Time of Day}) and -@code{file-attributes} (@pxref{Definition of file-attributes}). - - Many operating systems are limited to time values that contain 32 bits -of information; these systems typically handle only the times from -1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some -operating systems have larger time values, and can represent times far -in the past or future. - - Time conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 B.C., and do not skip zero -as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 B.C@. - -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@item minutes -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are not treated specially. If you want them -to stand for years above 1900, or years above 2000, you must alter them -yourself before you call @code{encode-time}. - -The optional argument @var{zone} defaults to the current time zone and -its daylight saving time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}), a string as in the -@code{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight saving time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example - -You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. - -The operating system puts limits on the range of possible time values; -if you try to encode a time that is out of range, an error results. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - -@node Time Parsing -@section Parsing and Formatting Times - - These functions convert time values (lists of two or three integers) -to text in a string, and vice versa. - -@defun date-to-time string -This function parses the time-string @var{string} and returns the -corresponding time value. -@end defun - -@defun format-time-string format-string &optional time universal -This function converts @var{time} (or the current time, if @var{time} is -omitted) to a string according to @var{format-string}. The argument -@var{format-string} may contain @samp{%}-sequences which say to -substitute parts of the time. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %a -This stands for the abbreviated name of the day of week. -@item %A -This stands for the full name of the day of week. -@item %b -This stands for the abbreviated name of the month. -@item %B -This stands for the full name of the month. -@item %c -This is a synonym for @samp{%x %X}. -@item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. -@item %d -This stands for the day of month, zero-padded. -@item %D -This is a synonym for @samp{%m/%d/%y}. -@item %e -This stands for the day of month, blank-padded. -@item %h -This is a synonym for @samp{%b}. -@item %H -This stands for the hour (00-23). -@item %I -This stands for the hour (01-12). -@item %j -This stands for the day of the year (001-366). -@item %k -This stands for the hour (0-23), blank padded. -@item %l -This stands for the hour (1-12), blank padded. -@item %m -This stands for the month (01-12). -@item %M -This stands for the minute (00-59). -@item %n -This stands for a newline. -@item %p -This stands for @samp{AM} or @samp{PM}, as appropriate. -@item %r -This is a synonym for @samp{%I:%M:%S %p}. -@item %R -This is a synonym for @samp{%H:%M}. -@item %S -This stands for the seconds (00-59). -@item %t -This stands for a tab character. -@item %T -This is a synonym for @samp{%H:%M:%S}. -@item %U -This stands for the week of the year (01-52), assuming that weeks -start on Sunday. -@item %w -This stands for the numeric day of week (0-6). Sunday is day 0. -@item %W -This stands for the week of the year (01-52), assuming that weeks -start on Monday. -@item %x -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%D}. -@item %X -This has a locale-specific meaning. In the default locale (named -@samp{C}), it is equivalent to @samp{%T}. -@item %y -This stands for the year without century (00-99). -@item %Y -This stands for the year with century. -@item %Z -This stands for the time zone abbreviation (e.g., @samp{EST}). -@item %z -This stands for the time zone numerical offset (e.g., @samp{-0500}). -@end table - -You can also specify the field width and type of padding for any of -these @samp{%}-sequences. This works as in @code{printf}: you write -the field width as digits in the middle of a @samp{%}-sequences. If you -start the field width with @samp{0}, it means to pad with zeros. If you -start the field width with @samp{_}, it means to pad with spaces. - -For example, @samp{%S} specifies the number of seconds since the minute; -@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to -pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, -because that is how @samp{%S} normally pads to two positions. - -The characters @samp{E} and @samp{O} act as modifiers when used between -@samp{%} and one of the letters in the table above. @samp{E} specifies -using the current locale's ``alternative'' version of the date and time. -In a Japanese locale, for example, @code{%Ex} might yield a date format -based on the Japanese Emperors' reigns. @samp{E} is allowed in -@samp{%Ec}, @samp{%EC}, @samp{%Ex}, @samp{%EX}, @samp{%Ey}, and -@samp{%EY}. - -@samp{O} means to use the current locale's ``alternative'' -representation of numbers, instead of the ordinary decimal digits. This -is allowed with most letters, all the ones that output numbers. - -If @var{universal} is non-@code{nil}, that means to describe the time as -Universal Time; @code{nil} means describe it using what Emacs believes -is the local time zone (see @code{current-time-zone}). - -This function uses the C library function @code{strftime} -(@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference -Manual}) to do most of the work. In order to communicate with that -function, it first encodes its argument using the coding system -specified by @code{locale-coding-system} (@pxref{Locales}); after -@code{strftime} returns the resulting string, -@code{format-time-string} decodes the string using that same coding -system. -@end defun - -@defun seconds-to-time seconds -This function converts @var{seconds}, a floating point number of -seconds since the epoch, to a time value and returns that. To perform -the inverse conversion, use @code{float-time}. -@end defun - -@defun format-seconds format-string seconds -This function converts its argument @var{seconds} into a string of -years, days, hours, etc., according to @var{format-string}. The -argument @var{format-string} may contain @samp{%}-sequences which -control the conversion. Here is a table of what the -@samp{%}-sequences mean: - -@table @samp -@item %y -@itemx %Y -The integer number of 365-day years. -@item %d -@itemx %D -The integer number of days. -@item %h -@itemx %H -The integer number of hours. -@item %m -@itemx %M -The integer number of minutes. -@item %s -@itemx %S -The integer number of seconds. -@item %z -Non-printing control flag. When it is used, other specifiers must be -given in the order of decreasing size, i.e.@: years before days, hours -before minutes, etc. Nothing will be produced in the result string to -the left of @samp{%z} until the first non-zero conversion is -encountered. For example, the default format used by -@code{emacs-uptime} (@pxref{Processor Run Time, emacs-uptime}) -@w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds -will always be produced, but years, days, hours, and minutes will only -be shown if they are non-zero. -@item %% -Produces a literal @samp{%}. -@end table - -Upper-case format sequences produce the units in addition to the -numbers, lower-case formats produce only the numbers. - -You can also specify the field width by following the @samp{%} with a -number; shorter numbers will be padded with blanks. An optional -period before the width requests zero-padding instead. For example, -@code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). -@end defun - -@node Processor Run Time -@section Processor Run time -@cindex processor run time -@cindex Emacs process run time - - Emacs provides several functions and primitives that return time, -both elapsed and processor time, used by the Emacs process. - -@deffn Command emacs-uptime &optional format -This function returns a string representing the Emacs -@dfn{uptime}---the elapsed wall-clock time this instance of Emacs is -running. The string is formatted by @code{format-seconds} according -to the optional argument @var{format}. For the available format -descriptors, see @ref{Time Parsing, format-seconds}. If @var{format} -is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M, -%z%S"}. - -When called interactively, it prints the uptime in the echo area. -@end deffn - -@defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of three integers: @code{(@var{high} @var{low} @var{microsec})}. The -integers @var{high} and @var{low} combine to give the number of -seconds, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds (or 0 for -systems that return time with the resolution of only one second). - -Note that the time returned by this function excludes the time Emacs -was not using the processor, and if the Emacs process has several -threads, the returned value is the sum of the processor times used up -by all Emacs threads. - -If the system doesn't provide a way to determine the processor run -time, @code{get-internal-run-time} returns the same time as -@code{current-time}. -@end defun - -@deffn Command emacs-init-time -This function returns the duration of the Emacs initialization -(@pxref{Startup Summary}) in seconds, as a string. When called -interactively, it prints the duration in the echo area. -@end deffn - -@node Time Calculations -@section Time Calculations - - These functions perform calendrical computations using time values -(the kind of list that @code{current-time} returns). - -@defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value -@var{t2}. -@end defun - -@defun time-subtract t1 t2 -This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, in the same format as a time value. -@end defun - -@defun time-add t1 t2 -This returns the sum of two time values, one of which ought to -represent a time difference rather than a point in time. -Here is how to add a number of seconds to a time value: - -@example -(time-add @var{time} (seconds-to-time @var{seconds})) -@end example -@end defun - -@defun time-to-days time -This function returns the number of days between the beginning of year -1 and @var{time}. -@end defun - -@defun time-to-day-in-year time -This returns the day number within the year corresponding to @var{time}. -@end defun - -@defun date-leap-year-p year -This function returns @code{t} if @var{year} is a leap year. -@end defun - -@node Timers -@section Timers for Delayed Execution -@cindex timer - - You can set up a @dfn{timer} to call a function at a specified -future time or after a certain length of idleness. - - Emacs cannot run timers at any arbitrary point in a Lisp program; it -can run them only when Emacs could accept output from a subprocess: -namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a -timer's execution may be delayed if Emacs is busy. However, the time of -execution is very precise if Emacs is idle. - - Emacs binds @code{inhibit-quit} to @code{t} before calling the timer -function, because quitting out of many timer functions can leave -things in an inconsistent state. This is normally unproblematical -because most timer functions don't do a lot of work. Indeed, for a -timer to call a function that takes substantial time to run is likely -to be annoying. If a timer function needs to allow quitting, it -should use @code{with-local-quit} (@pxref{Quitting}). For example, if -a timer function calls @code{accept-process-output} to receive output -from an external process, that call should be wrapped inside -@code{with-local-quit}, to ensure that @kbd{C-g} works if the external -process hangs. - - It is usually a bad idea for timer functions to alter buffer -contents. When they do, they usually should call @code{undo-boundary} -both before and after changing the buffer, to separate the timer's -changes from user commands' changes and prevent a single undo entry -from growing to be quite large. - - Timer functions should also avoid calling functions that cause Emacs -to wait, such as @code{sit-for} (@pxref{Waiting}). This can lead to -unpredictable effects, since other timers (or even the same timer) can -run while waiting. If a timer function needs to perform an action -after a certain time has elapsed, it can do this by scheduling a new -timer. - - If a timer function calls functions that can change the match data, -it should save and restore the match data. @xref{Saving Match Data}. - -@deffn Command run-at-time time repeat function &rest args -This sets up a timer that calls the function @var{function} with -arguments @var{args} at time @var{time}. If @var{repeat} is a number -(integer or floating point), the timer is scheduled to run again every -@var{repeat} seconds after @var{time}. If @var{repeat} is @code{nil}, -the timer runs only once. - -@var{time} may specify an absolute or a relative time. - -Absolute times may be specified using a string with a limited variety -of formats, and are taken to be times @emph{today}, even if already in -the past. The recognized forms are @samp{@var{xxxx}}, -@samp{@var{x}:@var{xx}}, or @samp{@var{xx}:@var{xx}} (military time), -and @samp{@var{xx}am}, @samp{@var{xx}AM}, @samp{@var{xx}pm}, -@samp{@var{xx}PM}, @samp{@var{xx}:@var{xx}am}, -@samp{@var{xx}:@var{xx}AM}, @samp{@var{xx}:@var{xx}pm}, or -@samp{@var{xx}:@var{xx}PM}. A period can be used instead of a colon -to separate the hour and minute parts. - -To specify a relative time as a string, use numbers followed by units. -For example: - -@table @samp -@item 1 min -denotes 1 minute from now. -@item 1 min 5 sec -denotes 65 seconds from now. -@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year -denotes exactly 103 months, 123 days, and 10862 seconds from now. -@end table - -For relative time values, Emacs considers a month to be exactly thirty -days, and a year to be exactly 365.25 days. - -Not all convenient formats are strings. If @var{time} is a number -(integer or floating point), that specifies a relative time measured in -seconds. The result of @code{encode-time} can also be used to specify -an absolute value for @var{time}. - -In most cases, @var{repeat} has no effect on when @emph{first} call -takes place---@var{time} alone specifies that. There is one exception: -if @var{time} is @code{t}, then the timer runs whenever the time is a -multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. - -The function @code{run-at-time} returns a timer value that identifies -the particular scheduled future action. You can use this value to call -@code{cancel-timer} (see below). -@end deffn - - A repeating timer nominally ought to run every @var{repeat} seconds, -but remember that any invocation of a timer can be late. Lateness of -one repetition has no effect on the scheduled time of the next -repetition. For instance, if Emacs is busy computing for long enough -to cover three scheduled repetitions of the timer, and then starts to -wait, it will immediately call the timer function three times in -immediate succession (presuming no other timers trigger before or -between them). If you want a timer to run again no less than @var{n} -seconds after the last invocation, don't use the @var{repeat} argument. -Instead, the timer function should explicitly reschedule the timer. - -@defvar timer-max-repeats -This variable's value specifies the maximum number of times to repeat -calling a timer function in a row, when many previously scheduled -calls were unavoidably delayed. -@end defvar - -@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} -Execute @var{body}, but give up after @var{seconds} seconds. If -@var{body} finishes before the time is up, @code{with-timeout} returns -the value of the last form in @var{body}. If, however, the execution of -@var{body} is cut short by the timeout, then @code{with-timeout} -executes all the @var{timeout-forms} and returns the value of the last -of them. - -This macro works by setting a timer to run after @var{seconds} seconds. If -@var{body} finishes before that time, it cancels the timer. If the -timer actually runs, it terminates execution of @var{body}, then -executes @var{timeout-forms}. - -Since timers can run within a Lisp program only when the program calls a -primitive that can wait, @code{with-timeout} cannot stop executing -@var{body} while it is in the midst of a computation---only when it -calls one of those primitives. So use @code{with-timeout} only with a -@var{body} that waits for input, not one that does a long computation. -@end defmac - - The function @code{y-or-n-p-with-timeout} provides a simple way to use -a timer to avoid waiting too long for an answer. @xref{Yes-or-No -Queries}. - -@defun cancel-timer timer -This cancels the requested action for @var{timer}, which should be a -timer---usually, one previously returned by @code{run-at-time} or -@code{run-with-idle-timer}. This cancels the effect of that call to -one of these functions; the arrival of the specified time will not -cause anything special to happen. -@end defun - -@node Idle Timers -@section Idle Timers - - Here is how to set up a timer that runs when Emacs is idle for a -certain length of time. Aside from how to set them up, idle timers -work just like ordinary timers. - -@deffn Command run-with-idle-timer secs repeat function &rest args -Set up a timer which runs when Emacs has been idle for @var{secs} -seconds. The value of @var{secs} may be an integer or a floating point -number; a value of the type returned by @code{current-idle-time} -is also allowed. - -If @var{repeat} is @code{nil}, the timer runs just once, the first time -Emacs remains idle for a long enough time. More often @var{repeat} is -non-@code{nil}, which means to run the timer @emph{each time} Emacs -remains idle for @var{secs} seconds. - -The function @code{run-with-idle-timer} returns a timer value which you -can use in calling @code{cancel-timer} (@pxref{Timers}). -@end deffn - -@cindex idleness - Emacs becomes ``idle'' when it starts waiting for user input, and it -remains idle until the user provides some input. If a timer is set for -five seconds of idleness, it runs approximately five seconds after Emacs -first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer -will not run again as long as Emacs remains idle, because the duration -of idleness will continue to increase and will not go down to five -seconds again. - - Emacs can do various things while idle: garbage collect, autosave or -handle data from a subprocess. But these interludes during idleness do -not interfere with idle timers, because they do not reset the clock of -idleness to zero. An idle timer set for 600 seconds will run when ten -minutes have elapsed since the last user command was finished, even if -subprocess output has been accepted thousands of times within those ten -minutes, and even if there have been garbage collections and autosaves. - - When the user supplies input, Emacs becomes non-idle while executing the -input. Then it becomes idle again, and all the idle timers that are -set up to repeat will subsequently run another time, one by one. - -@c Emacs 19 feature -@defun current-idle-time -If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of three integers: @code{(@var{high} @var{low} -@var{microsec})}. The integers @var{high} and @var{low} combine to -give the number of seconds of idleness, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). - -When Emacs is not idle, @code{current-idle-time} returns @code{nil}. -This is a convenient way to test whether Emacs is idle. - -The main use of this function is when an idle timer function wants to -``take a break'' for a while. It can set up another idle timer to -call the same function again, after a few seconds more idleness. -Here's an example: - -@smallexample -(defvar resume-timer nil - "Timer that `timer-function' used to reschedule itself, or nil.") - -(defun timer-function () - ;; @r{If the user types a command while @code{resume-timer}} - ;; @r{is active, the next time this function is called from} - ;; @r{its main idle timer, deactivate @code{resume-timer}.} - (when resume-timer - (cancel-timer resume-timer)) - ...@var{do the work for a while}... - (when @var{taking-a-break} - (setq resume-timer - (run-with-idle-timer - ;; Compute an idle time @var{break-length} - ;; more than the current value. - (time-add (current-idle-time) - (seconds-to-time @var{break-length})) - nil - 'timer-function)))) -@end smallexample -@end defun - - Some idle timer functions in user Lisp packages have a loop that -does a certain amount of processing each time around, and exits when -@code{(input-pending-p)} is non-@code{nil}. That approach seems very -natural but has two problems: - -@itemize -@item -It blocks out all process output (since Emacs accepts process output -only while waiting). - -@item -It blocks out any idle timers that ought to run during that time. -@end itemize - -@noindent -To avoid these problems, don't use that technique. Instead, write -such idle timers to reschedule themselves after a brief pause, using -the method in the @code{timer-function} example above. - -@node Terminal Input -@section Terminal Input -@cindex terminal input - - This section describes functions and variables for recording or -manipulating terminal input. See @ref{Display}, for related -functions. - -@menu -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. -@end menu - -@node Input Modes -@subsection Input Modes -@cindex input modes -@cindex terminal input modes - -@defun set-input-mode interrupt flow meta &optional quit-char -This function sets the mode for reading keyboard input. If -@var{interrupt} is non-null, then Emacs uses input interrupts. If it is -@code{nil}, then it uses @sc{cbreak} mode. The default setting is -system-dependent. Some systems always use @sc{cbreak} mode regardless -of what is specified. - -When Emacs communicates directly with X, it ignores this argument and -uses interrupts if that is the way it knows how to communicate. - -If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} -(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This -has no effect except in @sc{cbreak} mode. - -@c Emacs 19 feature -The argument @var{meta} controls support for input character codes -above 127. If @var{meta} is @code{t}, Emacs converts characters with -the 8th bit set into Meta characters. If @var{meta} is @code{nil}, -Emacs disregards the 8th bit; this is necessary when the terminal uses -it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, -Emacs uses all 8 bits of input unchanged. This is good for terminals -that use 8-bit character sets. - -@c Emacs 19 feature -If @var{quit-char} is non-@code{nil}, it specifies the character to -use for quitting. Normally this character is @kbd{C-g}. -@xref{Quitting}. -@end defun - -The @code{current-input-mode} function returns the input mode settings -Emacs is currently using. - -@c Emacs 19 feature -@defun current-input-mode -This function returns the current mode for reading keyboard input. It -returns a list, corresponding to the arguments of @code{set-input-mode}, -of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in -which: -@table @var -@item interrupt -is non-@code{nil} when Emacs is using interrupt-driven input. If -@code{nil}, Emacs is using @sc{cbreak} mode. -@item flow -is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) -flow control for output to the terminal. This value is meaningful only -when @var{interrupt} is @code{nil}. -@item meta -is @code{t} if Emacs treats the eighth bit of input characters as -the meta bit; @code{nil} means Emacs clears the eighth bit of every -input character; any other value means Emacs uses all eight bits as the -basic character code. -@item quit -is the character Emacs currently uses for quitting, usually @kbd{C-g}. -@end table -@end defun - -@node Recording Input -@subsection Recording Input -@cindex recording input - -@defun recent-keys -This function returns a vector containing the last 300 input events from -the keyboard or mouse. All input events are included, whether or not -they were used as parts of key sequences. Thus, you always get the last -100 input events, not counting events generated by keyboard macros. -(These are excluded because they are less interesting for debugging; it -should be enough to see the events that invoked the macros.) - -A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) -causes this function to return an empty vector immediately afterward. -@end defun - -@deffn Command open-dribble-file filename -@cindex dribble file -This function opens a @dfn{dribble file} named @var{filename}. When a -dribble file is open, each input event from the keyboard or mouse (but -not those from keyboard macros) is written in that file. A -non-character event is expressed using its printed representation -surrounded by @samp{<@dots{}>}. - -You close the dribble file by calling this function with an argument -of @code{nil}. - -This function is normally used to record the input necessary to -trigger an Emacs bug, for the sake of a bug report. - -@example -@group -(open-dribble-file "~/dribble") - @result{} nil -@end group -@end example -@end deffn - - See also the @code{open-termscript} function (@pxref{Terminal Output}). - -@node Terminal Output -@section Terminal Output -@cindex terminal output - - The terminal output functions send output to a text terminal, or keep -track of output sent to the terminal. The variable @code{baud-rate} -tells you what Emacs thinks is the output speed of the terminal. - -@defopt baud-rate -This variable's value is the output speed of the terminal, as far as -Emacs knows. Setting this variable does not change the speed of actual -data transmission, but the value is used for calculations such as -padding. - - It also affects decisions about whether to scroll part of the -screen or repaint on text terminals. @xref{Forcing Redisplay}, -for the corresponding functionality on graphical terminals. - -The value is measured in baud. -@end defopt - - If you are running across a network, and different parts of the -network work at different baud rates, the value returned by Emacs may be -different from the value used by your local terminal. Some network -protocols communicate the local terminal speed to the remote machine, so -that Emacs and other programs can get the proper value, but others do -not. If Emacs has the wrong value, it makes decisions that are less -than optimal. To fix the problem, set @code{baud-rate}. - -@defun send-string-to-terminal string &optional terminal -This function sends @var{string} to @var{terminal} without alteration. -Control characters in @var{string} have terminal-dependent effects. -This function operates only on text terminals. @var{terminal} may be -a terminal object, a frame, or @code{nil} for the selected frame's -terminal. - -One use of this function is to define function keys on terminals that -have downloadable function key definitions. For example, this is how (on -certain terminals) to define function key 4 to move forward four -characters (by transmitting the characters @kbd{C-u C-f} to the -computer): - -@example -@group -(send-string-to-terminal "\eF4\^U\^F") - @result{} nil -@end group -@end example -@end defun - -@deffn Command open-termscript filename -@cindex termscript file -This function is used to open a @dfn{termscript file} that will record -all the characters sent by Emacs to the terminal. It returns -@code{nil}. Termscript files are useful for investigating problems -where Emacs garbles the screen, problems that are due to incorrect -Termcap entries or to undesirable settings of terminal options more -often than to actual Emacs bugs. Once you are certain which characters -were actually output, you can determine reliably whether they correspond -to the Termcap specifications in use. - -You close the termscript file by calling this function with an -argument of @code{nil}. - -See also @code{open-dribble-file} in @ref{Recording Input}. - -@example -@group -(open-termscript "../junk/termscript") - @result{} nil -@end group -@end example -@end deffn - -@node Sound Output -@section Sound Output -@cindex sound - - To play sound using Emacs, use the function @code{play-sound}. Only -certain systems are supported; if you call @code{play-sound} on a system -which cannot really do the job, it gives an error. Emacs version 20 and -earlier did not support sound at all. - - The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) -or Sun Audio format (@samp{.au}). - -@defun play-sound sound -This function plays a specified sound. The argument, @var{sound}, has -the form @code{(sound @var{properties}...)}, where the @var{properties} -consist of alternating keywords (particular symbols recognized -specially) and values corresponding to them. - -Here is a table of the keywords that are currently meaningful in -@var{sound}, and their meanings: - -@table @code -@item :file @var{file} -This specifies the file containing the sound to play. -If the file name is not absolute, it is expanded against -the directory @code{data-directory}. - -@item :data @var{data} -This specifies the sound to play without need to refer to a file. The -value, @var{data}, should be a string containing the same bytes as a -sound file. We recommend using a unibyte string. - -@item :volume @var{volume} -This specifies how loud to play the sound. It should be a number in the -range of 0 to 1. The default is to use whatever volume has been -specified before. - -@item :device @var{device} -This specifies the system device on which to play the sound, as a -string. The default device is system-dependent. -@end table - -Before actually playing the sound, @code{play-sound} -calls the functions in the list @code{play-sound-functions}. -Each function is called with one argument, @var{sound}. -@end defun - -@defun play-sound-file file &optional volume device -This function is an alternative interface to playing a sound @var{file} -specifying an optional @var{volume} and @var{device}. -@end defun - -@defvar play-sound-functions -A list of functions to be called before playing a sound. Each function -is called with one argument, a property list that describes the sound. -@end defvar - -@node X11 Keysyms -@section Operating on X11 Keysyms -@cindex X11 keysyms - -To define system-specific X11 keysyms, set the variable -@code{system-key-alist}. - -@defvar system-key-alist -This variable's value should be an alist with one element for each -system-specific keysym. Each element has the form @code{(@var{code} -. @var{symbol})}, where @var{code} is the numeric keysym code (not -including the ``vendor specific'' bit, -@ifnottex --2**28), -@end ifnottex -@tex -$-2^{28}$), -@end tex -and @var{symbol} is the name for the function key. - -For example @code{(168 . mute-acute)} defines a system-specific key (used -by HP X servers) whose numeric code is -@ifnottex --2**28 -@end ifnottex -@tex -$-2^{28}$ -@end tex -+ 168. - -It is not crucial to exclude from the alist the keysyms of other X -servers; those do no harm, as long as they don't conflict with the ones -used by the X server actually in use. - -The variable is always local to the current terminal, and cannot be -buffer-local. @xref{Multiple Terminals}. -@end defvar - -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: - -@defvar x-alt-keysym -@defvarx x-meta-keysym -@defvarx x-hyper-keysym -@defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is -how to swap the Meta and Alt modifiers within Emacs: -@lisp -(setq x-alt-keysym 'meta) -(setq x-meta-keysym 'alt) -@end lisp -@end defvar - -@node Batch Mode -@section Batch Mode -@cindex batch mode - - The command-line option @samp{-batch} causes Emacs to run -noninteractively. In this mode, Emacs does not read commands from the -terminal, it does not alter the terminal modes, and it does not expect -to be outputting to an erasable screen. The idea is that you specify -Lisp programs to run; when they are finished, Emacs should exit. The -way to specify the programs to run is with @samp{-l @var{file}}, which -loads the library named @var{file}, or @samp{-f @var{function}}, which -calls @var{function} with no arguments, or @samp{--eval @var{form}}. - - Any Lisp program output that would normally go to the echo area, -either using @code{message}, or using @code{prin1}, etc., with @code{t} -as the stream, goes instead to Emacs's standard error descriptor when -in batch mode. Similarly, input that would normally come from the -minibuffer is read from the standard input descriptor. -Thus, Emacs behaves much like a noninteractive -application program. (The echo area output that Emacs itself normally -generates, such as command echoing, is suppressed entirely.) - -@defvar noninteractive -This variable is non-@code{nil} when Emacs is running in batch mode. -@end defvar - -@node Session Management -@section Session Management -@cindex session manager - -Emacs supports the X Session Management Protocol, which is used to -suspend and restart applications. In the X Window System, a program -called the @dfn{session manager} is responsible for keeping track of -the applications that are running. When the X server shuts down, the -session manager asks applications to save their state, and delays the -actual shutdown until they respond. An application can also cancel -the shutdown. - -When the session manager restarts a suspended session, it directs -these applications to individually reload their saved state. It does -this by specifying a special command-line argument that says what -saved session to restore. For Emacs, this argument is @samp{--smid -@var{session}}. - -@defvar emacs-save-session-functions -Emacs supports saving state via a hook called -@code{emacs-save-session-functions}. Emacs runs this hook when the -session manager tells it that the window system is shutting down. The -functions are called with no arguments, and with the current buffer -set to a temporary buffer. Each function can use @code{insert} to add -Lisp code to this buffer. At the end, Emacs saves the buffer in a -file, called the @dfn{session file}. - -@findex emacs-session-restore -Subsequently, when the session manager restarts Emacs, it loads the -session file automatically (@pxref{Loading}). This is performed by a -function named @code{emacs-session-restore}, which is called during -startup. @xref{Startup Summary}. - -If a function in @code{emacs-save-session-functions} returns -non-@code{nil}, Emacs tells the session manager to cancel the -shutdown. -@end defvar - -Here is an example that just inserts some text into @samp{*scratch*} when -Emacs is restarted by the session manager. - -@example -@group -(add-hook 'emacs-save-session-functions 'save-yourself-test) -@end group - -@group -(defun save-yourself-test () - (insert "(save-excursion - (switch-to-buffer \"*scratch*\") - (insert \"I am restored\"))") - nil) -@end group -@end example - -@ignore - arch-tag: 8378814a-30d7-467c-9615-74a80b9988a7 -@end ignore diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi deleted file mode 100644 index d3c13a3eb08..00000000000 --- a/doc/lispref/positions.texi +++ /dev/null @@ -1,1016 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/positions -@node Positions, Markers, Frames, Top -@chapter Positions -@cindex position (in buffer) - - A @dfn{position} is the index of a character in the text of a buffer. -More precisely, a position identifies the place between two characters -(or before the first character, or after the last character), so we can -speak of the character before or after a given position. However, we -often speak of the character ``at'' a position, meaning the character -after that position. - - Positions are usually represented as integers starting from 1, but -can also be represented as @dfn{markers}---special objects that -relocate automatically when text is inserted or deleted so they stay -with the surrounding characters. Functions that expect an argument to -be a position (an integer), but accept a marker as a substitute, -normally ignore which buffer the marker points into; they convert the -marker to an integer, and use that integer, exactly as if you had -passed the integer as the argument, even if the marker points to the -``wrong'' buffer. A marker that points nowhere cannot convert to an -integer; using it instead of an integer causes an error. -@xref{Markers}. - - See also the ``field'' feature (@pxref{Fields}), which provides -functions that are used by many cursor-motion commands. - -@menu -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. -@end menu - -@node Point -@section Point -@cindex point - - @dfn{Point} is a special buffer position used by many editing -commands, including the self-inserting typed characters and text -insertion functions. Other commands move point through the text -to allow editing and insertion at different places. - - Like other positions, point designates a place between two characters -(or before the first character, or after the last character), rather -than a particular character. Usually terminals display the cursor over -the character that immediately follows point; point is actually before -the character on which the cursor sits. - -@cindex point with narrowing - The value of point is a number no less than 1, and no greater than the -buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then -point is constrained to fall within the accessible portion of the buffer -(possibly at one end of it). - - Each buffer has its own value of point, which is independent of the -value of point in other buffers. Each window also has a value of point, -which is independent of the value of point in other windows on the same -buffer. This is why point can have different values in various windows -that display the same buffer. When a buffer appears in only one window, -the buffer's point and the window's point normally have the same value, -so the distinction is rarely important. @xref{Window Point}, for more -details. - -@defun point -@cindex current buffer position -This function returns the value of point in the current buffer, -as an integer. - -@need 700 -@example -@group -(point) - @result{} 175 -@end group -@end example -@end defun - -@defun point-min -This function returns the minimum accessible value of point in the -current buffer. This is normally 1, but if narrowing is in effect, it -is the position of the start of the region that you narrowed to. -(@xref{Narrowing}.) -@end defun - -@defun point-max -This function returns the maximum accessible value of point in the -current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is -in effect, in which case it is the position of the end of the region -that you narrowed to. (@xref{Narrowing}.) -@end defun - -@defun buffer-end flag -This function returns @code{(point-max)} if @var{flag} is greater than -0, @code{(point-min)} otherwise. The argument @var{flag} must be a -number. -@end defun - -@defun buffer-size &optional buffer -This function returns the total number of characters in the current -buffer. In the absence of any narrowing (@pxref{Narrowing}), -@code{point-max} returns a value one larger than this. - -If you specify a buffer, @var{buffer}, then the value is the -size of @var{buffer}. - -@example -@group -(buffer-size) - @result{} 35 -@end group -@group -(point-max) - @result{} 36 -@end group -@end example -@end defun - -@node Motion -@section Motion -@cindex motion by chars, words, lines, lists - - Motion functions change the value of point, either relative to the -current value of point, relative to the beginning or end of the buffer, -or relative to the edges of the selected window. @xref{Point}. - -@menu -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. -@end menu - -@node Character Motion -@subsection Motion by Characters - - These functions move point based on a count of characters. -@code{goto-char} is the fundamental primitive; the other functions use -that. - -@deffn Command goto-char position -This function sets point in the current buffer to the value -@var{position}. If @var{position} is less than 1, it moves point to the -beginning of the buffer. If @var{position} is greater than the length -of the buffer, it moves point to the end. - -If narrowing is in effect, @var{position} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. If @var{position} is out of range, @code{goto-char} moves -point to the beginning or the end of the accessible portion. - -When this function is called interactively, @var{position} is the -numeric prefix argument, if provided; otherwise it is read from the -minibuffer. - -@code{goto-char} returns @var{position}. -@end deffn - -@deffn Command forward-char &optional count -@c @kindex beginning-of-buffer -@c @kindex end-of-buffer -This function moves point @var{count} characters forward, towards the -end of the buffer (or backward, towards the beginning of the buffer, if -@var{count} is negative). If @var{count} is @code{nil}, the default -is 1. - -If this attempts to move past the beginning or end of the buffer (or -the limits of the accessible portion, when narrowing is in effect), it -signals an error with error symbol @code{beginning-of-buffer} or -@code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@deffn Command backward-char &optional count -This is just like @code{forward-char} except that it moves -in the opposite direction. -@end deffn - -@node Word Motion -@subsection Motion by Words - - These functions for parsing words use the syntax table to decide -whether a given character is part of a word. @xref{Syntax Tables}. - -@deffn Command forward-word &optional count -This function moves point forward @var{count} words (or backward if -@var{count} is negative). If @var{count} is @code{nil}, it moves -forward one word. - -``Moving one word'' means moving until point crosses a -word-constituent character and then encounters a word-separator -character. However, this function cannot move point past the boundary -of the accessible portion of the buffer, or across a field boundary -(@pxref{Fields}). The most common case of a field boundary is the end -of the prompt in the minibuffer. - -If it is possible to move @var{count} words, without being stopped -prematurely by the buffer boundary or a field boundary, the value is -@code{t}. Otherwise, the return value is @code{nil} and point stops at -the buffer boundary or field boundary. - -If @code{inhibit-field-text-motion} is non-@code{nil}, -this function ignores field boundaries. - -In an interactive call, @var{count} is specified by the numeric prefix -argument. If @var{count} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command backward-word &optional count -This function is just like @code{forward-word}, except that it moves -backward until encountering the front of a word, rather than forward. -@end deffn - -@defopt words-include-escapes -@c Emacs 19 feature -This variable affects the behavior of @code{forward-word} and everything -that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of -words. Otherwise, they do not. -@end defopt - -@defvar inhibit-field-text-motion -If this variable is non-@code{nil}, certain motion functions including -@code{forward-word}, @code{forward-sentence}, and -@code{forward-paragraph} ignore field boundaries. -@end defvar - -@node Buffer End Motion -@subsection Motion to an End of the Buffer -@cindex move to beginning or end of buffer - - To move point to the beginning of the buffer, write: - -@example -@group -(goto-char (point-min)) -@end group -@end example - -@noindent -Likewise, to move to the end of the buffer, use: - -@example -@group -(goto-char (point-max)) -@end group -@end example - - Here are two commands that users use to do these things. They are -documented here to warn you not to use them in Lisp programs, because -they set the mark and display messages in the echo area. - -@deffn Command beginning-of-buffer &optional n -This function moves point to the beginning of the buffer (or the limits -of the accessible portion, when narrowing is in effect), setting the -mark at the previous position (except in Transient Mark mode, if -the mark is already active, it does not set the mark.) - -If @var{n} is non-@code{nil}, then it puts point @var{n} tenths of the -way from the beginning of the accessible portion of the buffer. In an -interactive call, @var{n} is the numeric prefix argument, if provided; -otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position (except in Transient Mark mode when the mark -is already active). If @var{n} is non-@code{nil}, then it puts point -@var{n} tenths of the way from the end of the accessible portion of -the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -@strong{Warning:} Don't use this function in Lisp programs! -@end deffn - -@node Text Lines -@subsection Motion by Text Lines -@cindex lines - - Text lines are portions of the buffer delimited by newline characters, -which are regarded as part of the previous line. The first text line -begins at the beginning of the buffer, and the last text line ends at -the end of the buffer whether or not the last character is a newline. -The division of the buffer into text lines is not affected by the width -of the window, by line continuation in display, or by how tabs and -control characters are displayed. - -@deffn Command goto-line line &optional buffer -This function moves point to the front of the @var{line}th line, -counting from line 1 at beginning of the buffer, and leaves mark at the -previous position. If @var{line} is less than 1, it moves point to the -beginning of the buffer. If @var{line} is greater than the number of -lines in the buffer, it moves point to the end of the buffer---that is, -the @emph{end of the last line} of the buffer. - -If narrowing is in effect, then @var{line} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. So @code{goto-line} moves point to the beginning or end of the -accessible portion, if the line number specifies an inaccessible -position. - -The return value of @code{goto-line} is the difference between -@var{line} and the line number of the line to which point actually was -able to move (in the full buffer, before taking account of narrowing). -Thus, the value is positive if the scan encounters the real end of the -buffer before finding the specified line. The value is zero if scan -encounters the end of the accessible portion, but not the real end of -the buffer. - -If you provide the optional argument @var{buffer}, @code{goto-line} uses -@var{buffer} instead of the current buffer and displays it in another -window, if it was not already visible. -@end deffn - -@deffn Command beginning-of-line &optional count -This function moves point to the beginning of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the beginning of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, either bind @code{inhibit-field-text-motion} to -@code{t}, or use the @code{forward-line} function instead. For -instance, @code{(forward-line 0)} does the same thing as -@code{(beginning-of-line)}, except that it ignores field boundaries. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-beginning-position &optional count -Return the position that @code{(beginning-of-line @var{count})} -would move to. -@end defun - -@deffn Command end-of-line &optional count -This function moves point to the end of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the end of the line. - -This function does not move point across a field boundary -(@pxref{Fields}) unless doing so would move beyond there to a -different line; therefore, if @var{count} is @code{nil} or 1, and -point starts at a field boundary, point does not move. To ignore -field boundaries, bind @code{inhibit-field-text-motion} to @code{t}. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@defun line-end-position &optional count -Return the position that @code{(end-of-line @var{count})} -would move to. -@end defun - -@deffn Command forward-line &optional count -@cindex beginning of line -This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. If @var{count} is @code{nil}, that means 1. - -If @code{forward-line} encounters the beginning or end of the buffer (or -of the accessible portion) before finding that many lines, it sets point -there. No error is signaled. - -@code{forward-line} returns the difference between @var{count} and the -number of lines actually moved. If you attempt to move down five lines -from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@defun count-lines start end -@cindex lines in region -@anchor{Definition of count-lines} -This function returns the number of lines between the positions -@var{start} and @var{end} in the current buffer. If @var{start} and -@var{end} are equal, then it returns 0. Otherwise it returns at least -1, even if @var{start} and @var{end} are on the same line. This is -because the text between them, considered in isolation, must contain at -least one line unless it is empty. - -Here is an example of using @code{count-lines}: - -@example -@group -(defun current-line () - "Return the vertical position of point@dots{}" - (+ (count-lines (window-start) (point)) - (if (= (current-column) 0) 1 0))) -@end group -@end example -@end defun - -@defun line-number-at-pos &optional pos -@cindex line number -This function returns the line number in the current buffer -corresponding to the buffer position @var{pos}. If @var{pos} is @code{nil} -or omitted, the current buffer position is used. -@end defun - -@ignore -@c ================ -The @code{previous-line} and @code{next-line} commands are functions -that should not be used in programs. They are for users and are -mentioned here only for completeness. - -@deffn Command previous-line count -@cindex goal column -This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@deffn Command next-line count -This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In the case where the @var{count} is 1, and point is on the last -line of the buffer (or clipped region), a new empty line is inserted at the -end of the buffer (or clipped region) and point moved there. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@c ================ -@end ignore - - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. -These functions do not move point, but test whether it is already at the -beginning or end of a line. - -@node Screen Lines -@subsection Motion by Screen Lines - - The line functions in the previous section count text lines, delimited -only by newline characters. By contrast, these functions count screen -lines, which are defined by the way the text appears on the screen. A -text line is a single screen line if it is short enough to fit the width -of the selected window, but otherwise it may occupy several screen -lines. - - In some cases, text lines are truncated on the screen rather than -continued onto additional screen lines. In these cases, -@code{vertical-motion} moves point much like @code{forward-line}. -@xref{Truncation}. - - Because the width of a given string depends on the flags that control -the appearance of certain characters, @code{vertical-motion} behaves -differently, for a given piece of text, depending on the buffer it is -in, and even on the selected window (because the width, the truncation -flag, and display table may vary between windows). @xref{Usual -Display}. - - These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. If you intend to -use them heavily, Emacs provides caches which may improve the -performance of your code. @xref{Truncation, cache-long-line-scans}. - -@defun vertical-motion count &optional window -This function moves point to the start of the screen line @var{count} -screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -The @var{count} argument can be a cons cell, @code{(@var{cols} -. @var{lines})}, instead of an integer. Then the function moves by -@var{lines} screen lines, and puts point @var{cols} columns from the -start of that screen line. - -The return value is the number of screen lines over which point was -moved. The value may be less in absolute value than @var{count} if -the beginning or end of the buffer was reached. - -The window @var{window} is used for obtaining parameters such as the -width, the horizontal scrolling, and the display table. But -@code{vertical-motion} always operates on the current buffer, even if -@var{window} currently displays some other buffer. -@end defun - -@defun count-screen-lines &optional beg end count-final-newline window -This function returns the number of screen lines in the text from -@var{beg} to @var{end}. The number of screen lines may be different -from the number of actual lines, due to line continuation, the display -table, etc. If @var{beg} and @var{end} are @code{nil} or omitted, -they default to the beginning and end of the accessible portion of the -buffer. - -If the region ends with a newline, that is ignored unless the optional -third argument @var{count-final-newline} is non-@code{nil}. - -The optional fourth argument @var{window} specifies the window for -obtaining parameters such as width, horizontal scrolling, and so on. -The default is to use the selected window's parameters. - -Like @code{vertical-motion}, @code{count-screen-lines} always uses the -current buffer, regardless of which buffer is displayed in -@var{window}. This makes possible to use @code{count-screen-lines} in -any buffer, whether or not it is currently displayed in some window. -@end defun - -@deffn Command move-to-window-line count -This function moves point with respect to the text currently displayed -in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). - -If @var{count} is @code{nil}, then point moves to the beginning of the -line in the middle of the window. If the absolute value of @var{count} -is greater than the size of the window, then point moves to the place -that would appear on that screen line if the window were tall enough. -This will probably cause the next redisplay to scroll to bring that -location onto the screen. - -In an interactive call, @var{count} is the numeric prefix argument. - -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. -@end deffn - -@defun compute-motion from frompos to topos width offsets window -This function scans the current buffer, calculating screen positions. -It scans the buffer forward from position @var{from}, assuming that is -at screen coordinates @var{frompos}, to position @var{to} or coordinates -@var{topos}, whichever comes first. It returns the ending buffer -position and screen coordinates. - -The coordinate arguments @var{frompos} and @var{topos} are cons cells of -the form @code{(@var{hpos} . @var{vpos})}. - -The argument @var{width} is the number of columns available to display -text; this affects handling of continuation lines. @code{nil} means -the actual number of usable text columns in the window, which is -equivalent to the value returned by @code{(window-width window)}. - -The argument @var{offsets} is either @code{nil} or a cons cell of the -form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is -the number of columns not being displayed at the left margin; most -callers get this by calling @code{window-hscroll}. Meanwhile, -@var{tab-offset} is the offset between column numbers on the screen and -column numbers in the buffer. This can be nonzero in a continuation -line, when the previous screen lines' widths do not add up to a multiple -of @code{tab-width}. It is always zero in a non-continuation line. - -The window @var{window} serves only to specify which display table to -use. @code{compute-motion} always operates on the current buffer, -regardless of what buffer is displayed in @var{window}. - -The return value is a list of five elements: - -@example -(@var{pos} @var{hpos} @var{vpos} @var{prevhpos} @var{contin}) -@end example - -@noindent -Here @var{pos} is the buffer position where the scan stopped, @var{vpos} -is the vertical screen position, and @var{hpos} is the horizontal screen -position. - -The result @var{prevhpos} is the horizontal position one character back -from @var{pos}. The result @var{contin} is @code{t} if the last line -was continued after (or within) the previous character. - -For example, to find the buffer position of column @var{col} of screen line -@var{line} of a certain window, pass the window's display start location -as @var{from} and the window's upper-left coordinates as @var{frompos}. -Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to -the end of the accessible portion of the buffer, and pass @var{line} and -@var{col} as @var{topos}. Here's a function that does this: - -@example -(defun coordinates-of-position (col line) - (car (compute-motion (window-start) - '(0 . 0) - (point-max) - (cons col line) - (window-width) - (cons (window-hscroll) 0) - (selected-window)))) -@end example - -When you use @code{compute-motion} for the minibuffer, you need to use -@code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Contents}. -@end defun - -@node List Motion -@comment node-name, next, previous, up -@subsection Moving over Balanced Expressions -@cindex sexp motion -@cindex Lisp expression motion -@cindex list motion -@cindex balanced parenthesis motion - - Here are several functions concerned with balanced-parenthesis -expressions (also called @dfn{sexps} in connection with moving across -them in Emacs). The syntax table controls how these functions interpret -various characters; see @ref{Syntax Tables}. @xref{Parsing -Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Parentheses,, Commands for -Editing with Parentheses, emacs, The GNU Emacs Manual}. - -@deffn Command forward-list &optional arg -This function moves forward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command backward-list &optional arg -This function moves backward across @var{arg} (default 1) balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command up-list &optional arg -This function moves forward out of @var{arg} (default 1) levels of parentheses. -A negative argument means move backward but still to a less deep spot. -@end deffn - -@deffn Command down-list &optional arg -This function moves forward into @var{arg} (default 1) levels of -parentheses. A negative argument means move backward but still go -deeper in parentheses (@minus{}@var{arg} levels). -@end deffn - -@deffn Command forward-sexp &optional arg -This function moves forward across @var{arg} (default 1) balanced expressions. -Balanced expressions include both those delimited by parentheses and -other kinds, such as words and string constants. -@xref{Parsing Expressions}. For example, - -@example -@group ----------- Buffer: foo ---------- -(concat@point{} "foo " (car x) y z) ----------- Buffer: foo ---------- -@end group - -@group -(forward-sexp 3) - @result{} nil - ----------- Buffer: foo ---------- -(concat "foo " (car x) y@point{} z) ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command backward-sexp &optional arg -This function moves backward across @var{arg} (default 1) balanced expressions. -@end deffn - -@deffn Command beginning-of-defun &optional arg -This function moves back to the @var{arg}th beginning of a defun. If -@var{arg} is negative, this actually moves forward, but it still moves -to the beginning of a defun, not to the end of one. @var{arg} defaults -to 1. -@end deffn - -@deffn Command end-of-defun &optional arg -This function moves forward to the @var{arg}th end of a defun. If -@var{arg} is negative, this actually moves backward, but it still moves -to the end of a defun, not to the beginning of one. @var{arg} defaults -to 1. -@end deffn - -@defopt defun-prompt-regexp -If non-@code{nil}, this buffer-local variable holds a regular -expression that specifies what text can appear before the -open-parenthesis that starts a defun. That is to say, a defun begins -on a line that starts with a match for this regular expression, -followed by a character with open-parenthesis syntax. -@end defopt - -@defopt open-paren-in-column-0-is-defun-start -If this variable's value is non-@code{nil}, an open parenthesis in -column 0 is considered to be the start of a defun. If it is -@code{nil}, an open parenthesis in column 0 has no special meaning. -The default is @code{t}. -@end defopt - -@defvar beginning-of-defun-function -If non-@code{nil}, this variable holds a function for finding the -beginning of a defun. The function @code{beginning-of-defun} -calls this function instead of using its normal method, passing it its -optional argument. If the argument is non-@code{nil}, the function -should move back by that many functions, like -@code{beginning-of-defun} does. -@end defvar - -@defvar end-of-defun-function -If non-@code{nil}, this variable holds a function for finding the end of -a defun. The function @code{end-of-defun} calls this function instead -of using its normal method. -@end defvar - -@node Skipping Characters -@comment node-name, next, previous, up -@subsection Skipping Characters -@cindex skipping characters - - The following two functions move point over a specified set of -characters. For example, they are often used to skip whitespace. For -related functions, see @ref{Motion and Syntax}. - -These functions convert the set string to multibyte if the buffer is -multibyte, and they convert it to unibyte if the buffer is unibyte, as -the search functions do (@pxref{Searching and Matching}). - -@defun skip-chars-forward character-set &optional limit -This function moves point in the current buffer forward, skipping over a -given set of characters. It examines the character following point, -then advances point if the character matches @var{character-set}. This -continues until it reaches a character that does not match. The -function returns the number of characters moved over. - -The argument @var{character-set} is a string, like the inside of a -@samp{[@dots{}]} in a regular expression except that @samp{]} does not -terminate it, and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. -Thus, @code{"a-zA-Z"} skips over all letters, stopping before the -first nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before -the first letter. See @xref{Regular Expressions}. Character classes -can also be used, e.g. @code{"[:alnum:]"}. See @pxref{Char Classes}. - -If @var{limit} is supplied (it must be a number or a marker), it -specifies the maximum position in the buffer that point can be skipped -to. Point will stop at or before @var{limit}. - -In the following example, point is initially located directly before the -@samp{T}. After the form is evaluated, point is located at the end of -that line (between the @samp{t} of @samp{hat} and the newline). The -function skips all letters and spaces, but not newlines. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(skip-chars-forward "a-zA-Z ") - @result{} 18 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun skip-chars-backward character-set &optional limit -This function moves point backward, skipping characters that match -@var{character-set}, until @var{limit}. It is just like -@code{skip-chars-forward} except for the direction of motion. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@node Excursions -@section Excursions -@cindex excursion - - It is often useful to move point ``temporarily'' within a localized -portion of the program, or to switch buffers temporarily. This is -called an @dfn{excursion}, and it is done with the @code{save-excursion} -special form. This construct initially remembers the identity of the -current buffer, and its values of point and the mark, and restores them -after the completion of the excursion. - - The forms for saving and restoring the configuration of windows are -described elsewhere (see @ref{Window Configurations}, and @pxref{Frame -Configurations}). - -@defspec save-excursion body@dots{} -@cindex mark excursion -@cindex point excursion -The @code{save-excursion} special form saves the identity of the current -buffer and the values of point and the mark in it, evaluates -@var{body}, and finally restores the buffer and its saved values of -point and the mark. All three saved values are restored even in case of -an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -The @code{save-excursion} special form is the standard way to switch -buffers or move point within one part of a program and avoid affecting -the rest of the program. It is used more than 4000 times in the Lisp -sources of Emacs. - -@code{save-excursion} does not save the values of point and the mark for -other buffers, so changes in other buffers remain in effect after -@code{save-excursion} exits. - -@cindex window excursions -Likewise, @code{save-excursion} does not restore window-buffer -correspondences altered by functions such as @code{switch-to-buffer}. -One way to restore these correspondences, and the selected window, is to -use @code{save-window-excursion} inside @code{save-excursion} -(@pxref{Window Configurations}). - -The value returned by @code{save-excursion} is the result of the last -form in @var{body}, or @code{nil} if no body forms were given. - -@example -@group -(save-excursion @var{forms}) -@equiv{} -(let ((old-buf (current-buffer)) - (old-pnt (point-marker)) -@end group - (old-mark (copy-marker (mark-marker)))) - (unwind-protect - (progn @var{forms}) - (set-buffer old-buf) -@group - (goto-char old-pnt) - (set-marker (mark-marker) old-mark))) -@end group -@end example -@end defspec - - @strong{Warning:} Ordinary insertion of text adjacent to the saved -point value relocates the saved value, just as it relocates all markers. -More precisely, the saved value is a marker with insertion type -@code{nil}. @xref{Marker Insertion Types}. Therefore, when the saved -point value is restored, it normally comes before the inserted text. - - Although @code{save-excursion} saves the location of the mark, it does -not prevent functions which modify the buffer from setting -@code{deactivate-mark}, and thus causing the deactivation of the mark -after the command finishes. @xref{The Mark}. - -@node Narrowing -@section Narrowing -@cindex narrowing -@cindex restriction (in a buffer) -@cindex accessible portion (of a buffer) - - @dfn{Narrowing} means limiting the text addressable by Emacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the @dfn{accessible portion} of the -buffer. - - Narrowing is specified with two buffer positions which become the -beginning and end of the accessible portion. For most editing commands -and most Emacs primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no text -outside the accessible portion is displayed, and point cannot move -outside the accessible portion. - - Values such as positions or line numbers, which usually count from the -beginning of the buffer, do so despite narrowing, but the functions -which use them refuse to operate on text that is inaccessible. - - The commands for saving buffers are unaffected by narrowing; they save -the entire buffer regardless of any narrowing. - - If you need to display in a single buffer several very different -types of text, consider using an alternative facility described in -@ref{Swapping Text}. - -@deffn Command narrow-to-region start end -This function sets the accessible portion of the current buffer to start -at @var{start} and end at @var{end}. Both arguments should be character -positions. - -In an interactive call, @var{start} and @var{end} are set to the bounds -of the current region (point and the mark, with the smallest first). -@end deffn - -@deffn Command narrow-to-page &optional move-count -This function sets the accessible portion of the current buffer to -include just the current page. An optional first argument -@var{move-count} non-@code{nil} means to move forward or backward by -@var{move-count} pages and then narrow to one page. The variable -@code{page-delimiter} specifies where pages start and end -(@pxref{Standard Regexps}). - -In an interactive call, @var{move-count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command widen -@cindex widening -This function cancels any narrowing in the current buffer, so that the -entire contents are accessible. This is called @dfn{widening}. -It is equivalent to the following expression: - -@example -(narrow-to-region 1 (1+ (buffer-size))) -@end example -@end deffn - -@defspec save-restriction body@dots{} -This special form saves the current bounds of the accessible portion, -evaluates the @var{body} forms, and finally restores the saved bounds, -thus restoring the same state of narrowing (or absence thereof) formerly -in effect. The state of narrowing is restored even in the event of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -Therefore, this construct is a clean way to narrow a buffer temporarily. - -The value returned by @code{save-restriction} is that returned by the -last form in @var{body}, or @code{nil} if no body forms were given. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -@strong{Caution:} it is easy to make a mistake when using the -@code{save-restriction} construct. Read the entire description here -before you try it. - -If @var{body} changes the current buffer, @code{save-restriction} still -restores the restrictions on the original buffer (the buffer whose -restrictions it saved from), but it does not restore the identity of the -current buffer. - -@code{save-restriction} does @emph{not} restore point and the mark; use -@code{save-excursion} for that. If you use both @code{save-restriction} -and @code{save-excursion} together, @code{save-excursion} should come -first (on the outside). Otherwise, the old point value would be -restored with temporary narrowing still in effect. If the old point -value were outside the limits of the temporary narrowing, this would -fail to restore it accurately. - -Here is a simple example of correct use of @code{save-restriction}: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo -This is the contents of foo -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group - -@group -(save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - ----------- Buffer: foo ---------- -This is the contents of bar -This is the contents of bar -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@ignore - arch-tag: 56e8ff26-4ffe-4832-a141-7e991a2d0f87 -@end ignore diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi deleted file mode 100644 index b80b49f38cb..00000000000 --- a/doc/lispref/processes.texi +++ /dev/null @@ -1,3003 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/processes -@node Processes, Display, Abbrevs, Top -@chapter Processes -@cindex child process -@cindex parent process -@cindex subprocess -@cindex process - - In the terminology of operating systems, a @dfn{process} is a space in -which a program can execute. Emacs runs in a process. Emacs Lisp -programs can invoke other programs in processes of their own. These are -called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, -which is their @dfn{parent process}. - - A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, -depending on how it is created. When you create a synchronous -subprocess, the Lisp program waits for the subprocess to terminate -before continuing execution. When you create an asynchronous -subprocess, it can run in parallel with the Lisp program. This kind of -subprocess is represented within Emacs by a Lisp object which is also -called a ``process.'' Lisp programs can use this object to communicate -with the subprocess or to control it. For example, you can send -signals, obtain status information, receive output from the process, or -send input to it. - -@defun processp object -This function returns @code{t} if @var{object} represents an Emacs -subprocess, @code{nil} otherwise. -@end defun - - In addition to subprocesses of the current Emacs session, you can -also access other processes running on your machine. @xref{System -Processes}. - -@menu -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for network connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. -@end menu - -@node Subprocess Creation -@section Functions that Create Subprocesses - - There are three primitives that create a new subprocess in which to run -a program. One of them, @code{start-process}, creates an asynchronous -process and returns a process object (@pxref{Asynchronous Processes}). -The other two, @code{call-process} and @code{call-process-region}, -create a synchronous process and do not return a process object -(@pxref{Synchronous Processes}). - - Synchronous and asynchronous processes are explained in the following -sections. Since the three functions are all called in a similar -fashion, their common arguments are described here. - -@cindex execute program -@cindex @code{PATH} environment variable -@cindex @code{HOME} environment variable - In all cases, the function's @var{program} argument specifies the -program to be run. An error is signaled if the file is not found or -cannot be executed. If the file name is relative, the variable -@code{exec-path} contains a list of directories to search. Emacs -initializes @code{exec-path} when it starts up, based on the value of -the environment variable @code{PATH}. The standard file name -constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as -usual in @code{exec-path}, but environment variable substitutions -(@samp{$HOME}, etc.) are not recognized; use -@code{substitute-in-file-name} to perform them (@pxref{File Name -Expansion}). @code{nil} in this list refers to -@code{default-directory}. - - Executing a program can also try adding suffixes to the specified -name: - -@defvar exec-suffixes -This variable is a list of suffixes (strings) to try adding to the -specified program file name. The list should include @code{""} if you -want the name to be tried exactly as specified. The default value is -system-dependent. -@end defvar - - @strong{Please note:} The argument @var{program} contains only the -name of the program; it may not contain any command-line arguments. You -must use @var{args} to provide those. - - Each of the subprocess-creating functions has a @var{buffer-or-name} -argument which specifies where the standard output from the program will -go. It should be a buffer or a buffer name; if it is a buffer name, -that will create the buffer if it does not already exist. It can also -be @code{nil}, which says to discard the output unless a filter function -handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) -Normally, you should avoid having multiple processes send output to the -same buffer because their output would be intermixed randomly. - -@cindex program arguments - All three of the subprocess-creating functions have a @code{&rest} -argument, @var{args}. The @var{args} must all be strings, and they are -supplied to @var{program} as separate command line arguments. Wildcard -characters and other shell constructs have no special meanings in these -strings, since the strings are passed directly to the specified program. - - The subprocess gets its current directory from the value of -@code{default-directory} (@pxref{File Name Expansion}). - -@cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs, but you can -specify overrides for it with @code{process-environment}. @xref{System -Environment}. - -@defvar exec-directory -@pindex movemail -The value of this variable is a string, the name of a directory that -contains programs that come with GNU Emacs, programs intended for Emacs -to invoke. The program @code{movemail} is an example of such a program; -Rmail uses it to fetch new mail from an inbox. -@end defvar - -@defopt exec-path -The value of this variable is a list of directories to search for -programs to run in subprocesses. Each element is either the name of a -directory (i.e., a string), or @code{nil}, which stands for the default -directory (which is the value of @code{default-directory}). -@cindex program directories - -The value of @code{exec-path} is used by @code{call-process} and -@code{start-process} when the @var{program} argument is not an absolute -file name. -@end defopt - -@node Shell Arguments -@section Shell Arguments -@cindex arguments for shell commands -@cindex shell command arguments - - Lisp programs sometimes need to run a shell and give it a command -that contains file names that were specified by the user. These -programs ought to be able to support any valid file name. But the shell -gives special treatment to certain characters, and if these characters -occur in the file name, they will confuse the shell. To handle these -characters, use the function @code{shell-quote-argument}: - -@defun shell-quote-argument argument -This function returns a string which represents, in shell syntax, -an argument whose actual contents are @var{argument}. It should -work reliably to concatenate the return value into a shell command -and then pass it to a shell for execution. - -Precisely what this function does depends on your operating system. The -function is designed to work with the syntax of your system's standard -shell; if you use an unusual shell, you will need to redefine this -function. - -@example -;; @r{This example shows the behavior on GNU and Unix systems.} -(shell-quote-argument "foo > bar") - @result{} "foo\\ \\>\\ bar" - -;; @r{This example shows the behavior on MS-DOS and MS-Windows.} -(shell-quote-argument "foo > bar") - @result{} "\"foo > bar\"" -@end example - -Here's an example of using @code{shell-quote-argument} to construct -a shell command: - -@example -(concat "diff -c " - (shell-quote-argument oldfile) - " " - (shell-quote-argument newfile)) -@end example -@end defun - -@cindex quoting and unquoting shell command line - The following two functions are useful for creating shell commands -from individual argument strings, and taking shell command lines apart -into individual arguments. - -@defun split-string-and-unquote string &optional separators -This function splits @var{string} into substrings at matches for the -regular expression @var{separators}, like @code{split-string} does -(@pxref{Creating Strings}); in addition, it removes quoting from the -substrings. It then makes a list of the substrings and returns it. - -If @var{separators} is omitted or @code{nil}, it defaults to -@code{"\\s-+"}, which is a regular expression that matches one or more -characters with whitespace syntax (@pxref{Syntax Class Table}). - -This function performs two types of quoting: enclosing a whole string -in double quotes @code{"@dots{}"}, and quoting individual characters -with a backslash escape @samp{\}. The latter is also used in Lisp -strings, so this function can handle those as well. -@end defun - -@defun combine-and-quote-strings list-of-strings &optional separator -This function concatenates @var{list-of-strings} into a single string, -quoting each string as necessary. It also sticks the @var{separator} -string between each pair of strings; if @var{separator} is omitted or -@code{nil}, it defaults to @code{" "}. The return value is the -resulting string. - -The strings in @var{list-of-strings} that need quoting are those that -include @var{separator} as their substring. Quoting a string encloses -it in double quotes @code{"@dots{}"}. In the simplest case, if you -are consing a shell command from the individual command-line -arguments, every argument that includes embedded blanks will be -quoted. -@end defun - -@node Synchronous Processes -@section Creating a Synchronous Process -@cindex synchronous subprocess - - After a @dfn{synchronous process} is created, Emacs waits for the -process to terminate before continuing. Starting Dired on GNU or -Unix@footnote{On other systems, Emacs uses a Lisp emulation of -@code{ls}; see @ref{Contents of Directories}.} is an example of this: it -runs @code{ls} in a synchronous process, then modifies the output -slightly. Because the process is synchronous, the entire directory -listing arrives in the buffer before Emacs tries to do anything with it. - - While Emacs waits for the synchronous subprocess to terminate, the -user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill -the subprocess with a @code{SIGINT} signal; but it waits until the -subprocess actually terminates before quitting. If during that time the -user types another @kbd{C-g}, that kills the subprocess instantly with -@code{SIGKILL} and quits immediately (except on MS-DOS, where killing -other processes doesn't work). @xref{Quitting}. - - The synchronous subprocess functions return an indication of how the -process terminated. - - The output from a synchronous subprocess is generally decoded using a -coding system, much like text read from a file. The input sent to a -subprocess by @code{call-process-region} is encoded using a coding -system, much like text written into a file. @xref{Coding Systems}. - -@defun call-process program &optional infile destination display &rest args -This function calls @var{program} in a separate process and waits for -it to finish. - -The standard input for the process comes from file @var{infile} if -@var{infile} is not @code{nil}, and from the null device otherwise. -The argument @var{destination} says where to put the process output. -Here are the possibilities: - -@table @asis -@item a buffer -Insert the output in that buffer, before point. This includes both the -standard output stream and the standard error stream of the process. - -@item a string -Insert the output in a buffer with that name, before point. - -@item @code{t} -Insert the output in the current buffer, before point. - -@item @code{nil} -Discard the output. - -@item 0 -Discard the output, and return @code{nil} immediately without waiting -for the subprocess to finish. - -In this case, the process is not truly synchronous, since it can run in -parallel with Emacs; but you can think of it as synchronous in that -Emacs is essentially finished with the subprocess as soon as this -function returns. - -MS-DOS doesn't support asynchronous subprocesses, so this option doesn't -work there. - -@item @code{(@var{real-destination} @var{error-destination})} -Keep the standard output stream separate from the standard error stream; -deal with the ordinary output as specified by @var{real-destination}, -and dispose of the error output according to @var{error-destination}. -If @var{error-destination} is @code{nil}, that means to discard the -error output, @code{t} means mix it with the ordinary output, and a -string specifies a file name to redirect error output into. - -You can't directly specify a buffer to put the error output in; that is -too difficult to implement. But you can achieve this result by sending -the error output to a temporary file and then inserting the file into a -buffer. -@end table - -If @var{display} is non-@code{nil}, then @code{call-process} redisplays -the buffer as output is inserted. (However, if the coding system chosen -for decoding output is @code{undecided}, meaning deduce the encoding -from the actual data, then redisplay sometimes cannot continue once -non-@acronym{ASCII} characters are encountered. There are fundamental -reasons why it is hard to fix this; see @ref{Output from Processes}.) - -Otherwise the function @code{call-process} does no redisplay, and the -results become visible on the screen only when Emacs redisplays that -buffer in the normal course of events. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The value returned by @code{call-process} (unless you told it not to -wait) indicates the reason for process termination. A number gives the -exit status of the subprocess; 0 means success, and any other value -means failure. If the process terminated with a signal, -@code{call-process} returns a string describing the signal. - -In the examples below, the buffer @samp{foo} is current. - -@smallexample -@group -(call-process "pwd" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -/usr/user/lewis/manual ----------- Buffer: foo ---------- -@end group - -@group -(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} 0 - ----------- Buffer: bar ---------- -lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh - ----------- Buffer: bar ---------- -@end group -@end smallexample - -Here is a good example of the use of @code{call-process}, which used to -be found in the definition of @code{insert-directory}: - -@smallexample -@group -(call-process insert-directory-program nil t nil @var{switches} - (if full-directory-p - (concat (file-name-as-directory file) ".") - file)) -@end group -@end smallexample -@end defun - -@defun process-file program &optional infile buffer display &rest args -This function processes files synchronously in a separate process. It -is similar to @code{call-process} but may invoke a file handler based -on the value of the variable @code{default-directory}. The current -working directory of the subprocess is @code{default-directory}. - -The arguments are handled in almost the same way as for -@code{call-process}, with the following differences: - -Some file handlers may not support all combinations and forms of the -arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, -regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error -output by way of the @var{buffer} argument. - -If a file handler is invoked, it determines the program to run based -on the first argument @var{program}. For instance, consider that a -handler for remote files is invoked. Then the path that is used for -searching the program might be different than @code{exec-path}. - -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the -@code{process-file} function itself. (For example, -@code{default-directory} could be on a remote host, whereas -@var{infile} is on another remote host. Or @code{default-directory} -could be non-special, whereas @var{infile} is on a remote host.) - -If @var{buffer} is a list of the form @code{(@var{real-destination} -@var{error-destination})}, and @var{error-destination} names a file, -then the same remarks as for @var{infile} apply. - -The remaining arguments (@var{args}) will be passed to the process -verbatim. Emacs is not involved in processing file names that are -present in @var{args}. To avoid confusion, it may be best to avoid -absolute file names in @var{args}, but rather to specify all file -names as relative to @code{default-directory}. The function -@code{file-relative-name} is useful for constructing such relative -file names. -@end defun - -@defun call-process-region start end program &optional delete destination display &rest args -This function sends the text from @var{start} to @var{end} as -standard input to a process running @var{program}. It deletes the text -sent if @var{delete} is non-@code{nil}; this is useful when -@var{destination} is @code{t}, to insert the output in the current -buffer in place of the input. - -The arguments @var{destination} and @var{display} control what to do -with the output from the subprocess, and whether to update the display -as it comes in. For details, see the description of -@code{call-process}, above. If @var{destination} is the integer 0, -@code{call-process-region} discards the output and returns @code{nil} -immediately, without waiting for the subprocess to finish (this only -works if asynchronous subprocesses are supported). - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -The return value of @code{call-process-region} is just like that of -@code{call-process}: @code{nil} if you told it to return without -waiting; otherwise, a number or string which indicates how the -subprocess terminated. - -In the following example, we use @code{call-process-region} to run the -@code{cat} utility, with standard input being the first five characters -in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its -standard input into its standard output. Since the argument -@var{destination} is @code{t}, this output is inserted in the current -buffer. - -@smallexample -@group ----------- Buffer: foo ---------- -input@point{} ----------- Buffer: foo ---------- -@end group - -@group -(call-process-region 1 6 "cat" nil t) - @result{} 0 - ----------- Buffer: foo ---------- -inputinput@point{} ----------- Buffer: foo ---------- -@end group -@end smallexample - - The @code{shell-command-on-region} command uses -@code{call-process-region} like this: - -@smallexample -@group -(call-process-region - start end - shell-file-name ; @r{Name of program.} - nil ; @r{Do not delete region.} - buffer ; @r{Send output to @code{buffer}.} - nil ; @r{No redisplay during output.} - "-c" command) ; @r{Arguments for the shell.} -@end group -@end smallexample -@end defun - -@defun call-process-shell-command command &optional infile destination display &rest args -This function executes the shell command @var{command} synchronously -in a separate process. The final arguments @var{args} are additional -arguments to add at the end of @var{command}. The other arguments -are handled as in @code{call-process}. -@end defun - -@defun process-file-shell-command command &optional infile destination display &rest args -This function is like @code{call-process-shell-command}, but uses -@code{process-file} internally. Depending on @code{default-directory}, -@var{command} can be executed also on remote hosts. -@end defun - -@defun shell-command-to-string command -This function executes @var{command} (a string) as a shell command, -then returns the command's output as a string. -@end defun - -@defun process-lines program &rest args -This function runs @var{program} in a separate process, waits for it -to finish, and returns its output as a list of strings. Each string -in the list holds a single line of text output by the program; the -end-of-line characters are stripped from each line. The arguments -beyond @var{program}, @var{args}, are strings that specify -command-line arguments with which to run the program. - -If @var{program} exits with a non-zero exit status, this function -signals an error. - -This function works by calling @code{call-process}, so program output -is decoded in the same way as for @code{call-process}. -@end defun - -@node Asynchronous Processes -@section Creating an Asynchronous Process -@cindex asynchronous subprocess - - After an @dfn{asynchronous process} is created, Emacs and the subprocess -both continue running immediately. The process thereafter runs -in parallel with Emacs, and the two can communicate with each other -using the functions described in the following sections. However, -communication is only partially asynchronous: Emacs sends data to the -process only when certain functions are called, and Emacs accepts data -from the process only when Emacs is waiting for input or for a time -delay. - - Here we describe how to create an asynchronous process. - -@defun start-process name buffer-or-name program &rest args -This function creates a new asynchronous subprocess and starts the -program @var{program} running in it. It returns a process object that -stands for the new subprocess in Lisp. The argument @var{name} -specifies the name for the process object; if a process with this name -already exists, then @var{name} is modified (by appending @samp{<1>}, -etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to -associate with the process. - -The remaining arguments, @var{args}, are strings that specify command -line arguments for the program. - -In the example below, the first process is started and runs (rather, -sleeps) for 100 seconds. Meanwhile, the second process is started, and -given the name @samp{my-process<1>} for the sake of uniqueness. It -inserts the directory listing at the end of the buffer @samp{foo}, -before the first process finishes. Then it finishes, and a message to -that effect is inserted in the buffer. Much later, the first process -finishes, and another message is inserted in the buffer for it. - -@smallexample -@group -(start-process "my-process" "foo" "sleep" "100") - @result{} # -@end group - -@group -(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") - @result{} #> - ----------- Buffer: foo ---------- -total 2 -lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs --rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon - -Process my-process<1> finished - -Process my-process finished ----------- Buffer: foo ---------- -@end group -@end smallexample -@end defun - -@defun start-file-process name buffer-or-name program &rest args -Like @code{start-process}, this function starts a new asynchronous -subprocess running @var{program} in it, and returns its process -object---when @code{default-directory} is not a magic file name. - -If @code{default-directory} is magic, the function invokes its file -handler instead. This handler ought to run @var{program}, perhaps on -the local host, perhaps on a remote host that corresponds to -@code{default-directory}. In the latter case, the local part of -@code{default-directory} becomes the working directory of the process. - -This function does not try to invoke file name handlers for -@var{program} or for the @var{program-args}. - -Depending on the implementation of the file handler, it might not be -possible to apply @code{process-filter} or @code{process-sentinel} to -the resulting process object (@pxref{Filter Functions}, @pxref{Sentinels}). - -Some file handlers may not support @code{start-file-process} (for -example @code{ange-ftp-hook-function}). In such cases, the function -does nothing and returns @code{nil}. -@end defun - -@defun start-process-shell-command name buffer-or-name command &rest command-args -This function is like @code{start-process} except that it uses a shell -to execute the specified command. The argument @var{command} is a shell -command name, and @var{command-args} are the arguments for the shell -command. The variable @code{shell-file-name} specifies which shell to -use. - -The point of running a program through the shell, rather than directly -with @code{start-process}, is so that you can employ shell features such -as wildcards in the arguments. It follows that if you include an -arbitrary user-specified arguments in the command, you should quote it -with @code{shell-quote-argument} first, so that any special shell -characters do @emph{not} have their special shell meanings. @xref{Shell -Arguments}. -@end defun - -@defun start-file-process-shell-command name buffer-or-name command &rest command-args -This function is like @code{start-process-shell-command}, but uses -@code{start-file-process} internally. By this, @var{command} can be -executed also on remote hosts, depending on @code{default-directory}. -@end defun - -@defvar process-connection-type -@cindex pipes -@cindex @acronym{PTY}s -This variable controls the type of device used to communicate with -asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are -used, when available. Otherwise, pipes are used. - -@acronym{PTY}s are usually preferable for processes visible to the user, as -in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, -etc.) to work between the process and its children, whereas pipes do -not. For subprocesses used for internal purposes by programs, it is -often better to use a pipe, because they are more efficient. In -addition, the total number of @acronym{PTY}s is limited on many systems and -it is good not to waste them. - -The value of @code{process-connection-type} takes effect when -@code{start-process} is called. So you can specify how to communicate -with one subprocess by binding the variable around the call to -@code{start-process}. - -@smallexample -@group -(let ((process-connection-type nil)) ; @r{Use a pipe.} - (start-process @dots{})) -@end group -@end smallexample - -To determine whether a given subprocess actually got a pipe or a -@acronym{PTY}, use the function @code{process-tty-name} (@pxref{Process -Information}). -@end defvar - -@node Deleting Processes -@section Deleting Processes -@cindex deleting processes - - @dfn{Deleting a process} disconnects Emacs immediately from the -subprocess. Processes are deleted automatically after they terminate, -but not necessarily right away. You can delete a process explicitly -at any time. If you delete a terminated process explicitly before it -is deleted automatically, no harm results. Deleting a running -process sends a signal to terminate it (and its child processes if -any), and calls the process sentinel if it has one. @xref{Sentinels}. - - When a process is deleted, the process object itself continues to -exist as long as other Lisp objects point to it. All the Lisp -primitives that work on process objects accept deleted processes, but -those that do I/O or send signals will report an error. The process -mark continues to point to the same place as before, usually into a -buffer where output from the process was being inserted. - -@defopt delete-exited-processes -This variable controls automatic deletion of processes that have -terminated (due to calling @code{exit} or to a signal). If it is -@code{nil}, then they continue to exist until the user runs -@code{list-processes}. Otherwise, they are deleted immediately after -they exit. -@end defopt - -@defun delete-process process -This function deletes a process, killing it with a @code{SIGKILL} -signal. The argument may be a process, the name of a process, a -buffer, or the name of a buffer. (A buffer or buffer-name stands for -the process that @code{get-buffer-process} returns.) Calling -@code{delete-process} on a running process terminates it, updates the -process status, and runs the sentinel (if any) immediately. If the -process has already terminated, calling @code{delete-process} has no -effect on its status, or on the running of its sentinel (which will -happen sooner or later). - -@smallexample -@group -(delete-process "*shell*") - @result{} nil -@end group -@end smallexample -@end defun - -@node Process Information -@section Process Information - - Several functions return information about processes. -@code{list-processes} is provided for interactive use. - -@deffn Command list-processes &optional query-only -This command displays a listing of all living processes. In addition, -it finally deletes any process whose status was @samp{Exited} or -@samp{Signaled}. It returns @code{nil}. - -If @var{query-only} is non-@code{nil} then it lists only processes -whose query flag is non-@code{nil}. @xref{Query Before Exit}. -@end deffn - -@defun process-list -This function returns a list of all processes that have not been deleted. - -@smallexample -@group -(process-list) - @result{} (# #) -@end group -@end smallexample -@end defun - -@defun get-process name -This function returns the process named @var{name}, or @code{nil} if -there is none. An error is signaled if @var{name} is not a string. - -@smallexample -@group -(get-process "shell") - @result{} # -@end group -@end smallexample -@end defun - -@defun process-command process -This function returns the command that was executed to start -@var{process}. This is a list of strings, the first string being the -program executed and the rest of the strings being the arguments that -were given to the program. - -@smallexample -@group -(process-command (get-process "shell")) - @result{} ("/bin/csh" "-i") -@end group -@end smallexample -@end defun - -@defun process-contact process &optional key - -This function returns information about how a network or serial -process was set up. For a network process, when @var{key} is -@code{nil}, it returns @code{(@var{hostname} @var{service})} which -specifies what you connected to. For a serial process, when @var{key} -is @code{nil}, it returns @code{(@var{port} @var{speed})}. For an -ordinary child process, this function always returns @code{t}. - -If @var{key} is @code{t}, the value is the complete status information -for the connection, server, or serial port; that is, the list of -keywords and values specified in @code{make-network-process} or -@code{make-serial-process}, except that some of the values represent -the current status instead of what you specified. - -For a network process: - -@table @code -@item :buffer -The associated value is the process buffer. -@item :filter -The associated value is the process filter function. -@item :sentinel -The associated value is the process sentinel function. -@item :remote -In a connection, the address in internal format of the remote peer. -@item :local -The local address, in internal format. -@item :service -In a server, if you specified @code{t} for @var{service}, -this value is the actual port number. -@end table - -@code{:local} and @code{:remote} are included even if they were not -specified explicitly in @code{make-network-process}. - -For a serial process, see @code{make-serial-process} and -@code{serial-process-configure} for a list of keys. - -If @var{key} is a keyword, the function returns the value corresponding -to that keyword. -@end defun - -@defun process-id process -This function returns the @acronym{PID} of @var{process}. This is an -integer that distinguishes the process @var{process} from all other -processes running on the same computer at the current time. The -@acronym{PID} of a process is chosen by the operating system kernel when the -process is started and remains constant as long as the process exists. -@end defun - -@defun process-name process -This function returns the name of @var{process}. -@end defun - -@defun process-status process-name -This function returns the status of @var{process-name} as a symbol. -The argument @var{process-name} must be a process, a buffer, or a -process name (a string). - -The possible values for an actual subprocess are: - -@table @code -@item run -for a process that is running. -@item stop -for a process that is stopped but continuable. -@item exit -for a process that has exited. -@item signal -for a process that has received a fatal signal. -@item open -for a network connection that is open. -@item closed -for a network connection that is closed. Once a connection -is closed, you cannot reopen it, though you might be able to open -a new connection to the same place. -@item connect -for a non-blocking connection that is waiting to complete. -@item failed -for a non-blocking connection that has failed to complete. -@item listen -for a network server that is listening. -@item nil -if @var{process-name} is not the name of an existing process. -@end table - -@smallexample -@group -(process-status (get-buffer "*shell*")) - @result{} run -@end group -@group -x - @result{} #> -(process-status x) - @result{} exit -@end group -@end smallexample - -For a network connection, @code{process-status} returns one of the symbols -@code{open} or @code{closed}. The latter means that the other side -closed the connection, or Emacs did @code{delete-process}. -@end defun - -@defun process-type process -This function returns the symbol @code{network} for a network -connection or server, @code{serial} for a serial port connection, or -@code{real} for a real subprocess. -@end defun - -@defun process-exit-status process -This function returns the exit status of @var{process} or the signal -number that killed it. (Use the result of @code{process-status} to -determine which of those it is.) If @var{process} has not yet -terminated, the value is 0. -@end defun - -@defun process-tty-name process -This function returns the terminal name that @var{process} is using for -its communication with Emacs---or @code{nil} if it is using pipes -instead of a terminal (see @code{process-connection-type} in -@ref{Asynchronous Processes}). -@end defun - -@defun process-coding-system process -@anchor{Coding systems for a subprocess} -This function returns a cons cell describing the coding systems in use -for decoding output from @var{process} and for encoding input to -@var{process} (@pxref{Coding Systems}). The value has this form: - -@example -(@var{coding-system-for-decoding} . @var{coding-system-for-encoding}) -@end example -@end defun - -@defun set-process-coding-system process &optional decoding-system encoding-system -This function specifies the coding systems to use for subsequent output -from and input to @var{process}. It will use @var{decoding-system} to -decode subprocess output, and @var{encoding-system} to encode subprocess -input. -@end defun - - Every process also has a property list that you can use to store -miscellaneous values associated with the process. - -@defun process-get process propname -This function returns the value of the @var{propname} property -of @var{process}. -@end defun - -@defun process-put process propname value -This function sets the value of the @var{propname} property -of @var{process} to @var{value}. -@end defun - -@defun process-plist process -This function returns the process plist of @var{process}. -@end defun - -@defun set-process-plist process plist -This function sets the process plist of @var{process} to @var{plist}. -@end defun - -@node Input to Processes -@section Sending Input to Processes -@cindex process input - - Asynchronous subprocesses receive input when it is sent to them by -Emacs, which is done with the functions in this section. You must -specify the process to send input to, and the input data to send. The -data appears on the ``standard input'' of the subprocess. - - Some operating systems have limited space for buffered input in a -@acronym{PTY}. On these systems, Emacs sends an @acronym{EOF} -periodically amidst the other characters, to force them through. For -most programs, these @acronym{EOF}s do no harm. - - Subprocess input is normally encoded using a coding system before the -subprocess receives it, much like text written into a file. You can use -@code{set-process-coding-system} to specify which coding system to use -(@pxref{Process Information}). Otherwise, the coding system comes from -@code{coding-system-for-write}, if that is non-@code{nil}; or else from -the defaulting mechanism (@pxref{Default Coding Systems}). - - Sometimes the system is unable to accept input for that process, -because the input buffer is full. When this happens, the send functions -wait a short while, accepting output from subprocesses, and then try -again. This gives the subprocess a chance to read more of its pending -input and make space in the buffer. It also allows filters, sentinels -and timers to run---so take account of that in writing your code. - - In these functions, the @var{process} argument can be a process or -the name of a process, or a buffer or buffer name (which stands -for a process via @code{get-buffer-process}). @code{nil} means -the current buffer's process. - -@defun process-send-string process string -This function sends @var{process} the contents of @var{string} as -standard input. If it is @code{nil}, the current buffer's process is used. - - The function returns @code{nil}. - -@smallexample -@group -(process-send-string "shell<1>" "ls\n") - @result{} nil -@end group - - -@group ----------- Buffer: *shell* ---------- -... -introduction.texi syntax-tables.texi~ -introduction.texi~ text.texi -introduction.txt text.texi~ -... ----------- Buffer: *shell* ---------- -@end group -@end smallexample -@end defun - -@defun process-send-region process start end -This function sends the text in the region defined by @var{start} and -@var{end} as standard input to @var{process}. - -An error is signaled unless both @var{start} and @var{end} are -integers or markers that indicate positions in the current buffer. (It -is unimportant which number is larger.) -@end defun - -@defun process-send-eof &optional process -This function makes @var{process} see an end-of-file in its -input. The @acronym{EOF} comes after any text already sent to it. - -The function returns @var{process}. - -@smallexample -@group -(process-send-eof "shell") - @result{} "shell" -@end group -@end smallexample -@end defun - -@defun process-running-child-p &optional process -This function will tell you whether a @var{process} has given control of -its terminal to its own child process. The value is @code{t} if this is -true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain -that this is not so. -@end defun - -@node Signals to Processes -@section Sending Signals to Processes -@cindex process signals -@cindex sending signals -@cindex signals - - @dfn{Sending a signal} to a subprocess is a way of interrupting its -activities. There are several different signals, each with its own -meaning. The set of signals and their names is defined by the operating -system. For example, the signal @code{SIGINT} means that the user has -typed @kbd{C-c}, or that some analogous thing has happened. - - Each signal has a standard effect on the subprocess. Most signals -kill the subprocess, but some stop or resume execution instead. Most -signals can optionally be handled by programs; if the program handles -the signal, then we can say nothing in general about its effects. - - You can send signals explicitly by calling the functions in this -section. Emacs also sends signals automatically at certain times: -killing a buffer sends a @code{SIGHUP} signal to all its associated -processes; killing Emacs sends a @code{SIGHUP} signal to all remaining -processes. (@code{SIGHUP} is a signal that usually indicates that the -user hung up the phone.) - - Each of the signal-sending functions takes two optional arguments: -@var{process} and @var{current-group}. - - The argument @var{process} must be either a process, a process -name, a buffer, a buffer name, or @code{nil}. A buffer or buffer name -stands for a process through @code{get-buffer-process}. @code{nil} -stands for the process associated with the current buffer. An error -is signaled if @var{process} does not identify a process. - - The argument @var{current-group} is a flag that makes a difference -when you are running a job-control shell as an Emacs subprocess. If it -is non-@code{nil}, then the signal is sent to the current process-group -of the terminal that Emacs uses to communicate with the subprocess. If -the process is a job-control shell, this means the shell's current -subjob. If it is @code{nil}, the signal is sent to the process group of -the immediate subprocess of Emacs. If the subprocess is a job-control -shell, this is the shell itself. - - The flag @var{current-group} has no effect when a pipe is used to -communicate with the subprocess, because the operating system does not -support the distinction in the case of pipes. For the same reason, -job-control shells won't work when a pipe is used. See -@code{process-connection-type} in @ref{Asynchronous Processes}. - -@defun interrupt-process &optional process current-group -This function interrupts the process @var{process} by sending the -signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt -character'' (normally @kbd{C-c} on some systems, and @code{DEL} on -others) sends this signal. When the argument @var{current-group} is -non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' -on the terminal by which Emacs talks to the subprocess. -@end defun - -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the -signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun - -@defun quit-process &optional process current-group -This function sends the signal @code{SIGQUIT} to the process -@var{process}. This signal is the one sent by the ``quit -character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside -Emacs. -@end defun - -@defun stop-process &optional process current-group -This function stops the process @var{process} by sending the -signal @code{SIGTSTP}. Use @code{continue-process} to resume its -execution. - -Outside of Emacs, on systems with job control, the ``stop character'' -(usually @kbd{C-z}) normally sends this signal. When -@var{current-group} is non-@code{nil}, you can think of this function as -``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the -subprocess. -@end defun - -@defun continue-process &optional process current-group -This function resumes execution of the process @var{process} by sending -it the signal @code{SIGCONT}. This presumes that @var{process} was -stopped previously. -@end defun - -@defun signal-process process signal -This function sends a signal to process @var{process}. The argument -@var{signal} specifies which signal to send; it should be an integer. - -The @var{process} argument can be a system process @acronym{ID}; that -allows you to send signals to processes that are not children of -Emacs. @xref{System Processes}. -@end defun - -@node Output from Processes -@section Receiving Output from Processes -@cindex process output -@cindex output from processes - - There are two ways to receive the output that a subprocess writes to -its standard output stream. The output can be inserted in a buffer, -which is called the associated buffer of the process, or a function -called the @dfn{filter function} can be called to act on the output. If -the process has no buffer and no filter function, its output is -discarded. - - When a subprocess terminates, Emacs reads any pending output, -then stops reading output from that subprocess. Therefore, if the -subprocess has children that are still live and still producing -output, Emacs won't receive that output. - - Output from a subprocess can arrive only while Emacs is waiting: when -reading terminal input, in @code{sit-for} and @code{sleep-for} -(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting -Output}). This minimizes the problem of timing errors that usually -plague parallel programming. For example, you can safely create a -process and only then specify its buffer or filter function; no output -can arrive before you finish, if the code in between does not call any -primitive that waits. - -@defvar process-adaptive-read-buffering -On some systems, when Emacs reads the output from a subprocess, the -output data is read in very small blocks, potentially resulting in -very poor performance. This behavior can be remedied to some extent -by setting the variable @var{process-adaptive-read-buffering} to a -non-@code{nil} value (the default), as it will automatically delay reading -from such processes, thus allowing them to produce more output before -Emacs tries to read it. -@end defvar - - It is impossible to separate the standard output and standard error -streams of the subprocess, because Emacs normally spawns the subprocess -inside a pseudo-TTY, and a pseudo-TTY has only one output channel. If -you want to keep the output to those streams separate, you should -redirect one of them to a file---for example, by using an appropriate -shell command. - -@menu -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. -@end menu - -@node Process Buffers -@subsection Process Buffers - - A process can (and usually does) have an @dfn{associated buffer}, -which is an ordinary Emacs buffer that is used for two purposes: storing -the output from the process, and deciding when to kill the process. You -can also use the buffer to identify a process to operate on, since in -normal practice only one process is associated with any given buffer. -Many applications of processes also use the buffer for editing input to -be sent to the process, but this is not built into Emacs Lisp. - - Unless the process has a filter function (@pxref{Filter Functions}), -its output is inserted in the associated buffer. The position to insert -the output is determined by the @code{process-mark}, which is then -updated to point to the end of the text just inserted. Usually, but not -always, the @code{process-mark} is at the end of the buffer. - -@defun process-buffer process -This function returns the associated buffer of the process -@var{process}. - -@smallexample -@group -(process-buffer (get-process "shell")) - @result{} # -@end group -@end smallexample -@end defun - -@defun process-mark process -This function returns the process marker for @var{process}, which is the -marker that says where to insert output from the process. - -If @var{process} does not have a buffer, @code{process-mark} returns a -marker that points nowhere. - -Insertion of process output in a buffer uses this marker to decide where -to insert, and updates it to point after the inserted text. That is why -successive batches of output are inserted consecutively. - -Filter functions normally should use this marker in the same fashion -as is done by direct insertion of output in the buffer. A good -example of a filter function that uses @code{process-mark} is found at -the end of the following section. - -When the user is expected to enter input in the process buffer for -transmission to the process, the process marker separates the new input -from previous output. -@end defun - -@defun set-process-buffer process buffer -This function sets the buffer associated with @var{process} to -@var{buffer}. If @var{buffer} is @code{nil}, the process becomes -associated with no buffer. -@end defun - -@defun get-buffer-process buffer-or-name -This function returns a nondeleted process associated with the buffer -specified by @var{buffer-or-name}. If there are several processes -associated with it, this function chooses one (currently, the one most -recently created, but don't count on that). Deletion of a process -(see @code{delete-process}) makes it ineligible for this function to -return. - -It is usually a bad idea to have more than one process associated with -the same buffer. - -@smallexample -@group -(get-buffer-process "*shell*") - @result{} # -@end group -@end smallexample - -Killing the process's buffer deletes the process, which kills the -subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). -@end defun - -@node Filter Functions -@subsection Process Filter Functions -@cindex filter function -@cindex process filter - - A process @dfn{filter function} is a function that receives the -standard output from the associated process. If a process has a filter, -then @emph{all} output from that process is passed to the filter. The -process buffer is used directly for output from the process only when -there is no filter. - - The filter function can only be called when Emacs is waiting for -something, because process output arrives only at such times. Emacs -waits when reading terminal input, in @code{sit-for} and -@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output} -(@pxref{Accepting Output}). - - A filter function must accept two arguments: the associated process -and a string, which is output just received from it. The function is -then free to do whatever it chooses with the output. - - Quitting is normally inhibited within a filter function---otherwise, -the effect of typing @kbd{C-g} at command level or to quit a user -command would be unpredictable. If you want to permit quitting inside -a filter function, bind @code{inhibit-quit} to @code{nil}. In most -cases, the right way to do this is with the macro -@code{with-local-quit}. @xref{Quitting}. - - If an error happens during execution of a filter function, it is -caught automatically, so that it doesn't stop the execution of whatever -program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -filter function. @xref{Debugger}. - - Many filter functions sometimes or always insert the text in the -process's buffer, mimicking the actions of Emacs when there is no -filter. Such filter functions need to use @code{set-buffer} in order to -be sure to insert in that buffer. To avoid setting the current buffer -semipermanently, these filter functions must save and restore the -current buffer. They should also update the process marker, and in some -cases update the value of point. Here is how to do these things: - -@smallexample -@group -(defun ordinary-insertion-filter (proc string) - (with-current-buffer (process-buffer proc) - (let ((moving (= (point) (process-mark proc)))) -@end group -@group - (save-excursion - ;; @r{Insert the text, advancing the process marker.} - (goto-char (process-mark proc)) - (insert string) - (set-marker (process-mark proc) (point))) - (if moving (goto-char (process-mark proc)))))) -@end group -@end smallexample - -@noindent -The reason to use @code{with-current-buffer}, rather than using -@code{save-excursion} to save and restore the current buffer, is so as -to preserve the change in point made by the second call to -@code{goto-char}. - - To make the filter force the process buffer to be visible whenever new -text arrives, insert the following line just before the -@code{with-current-buffer} construct: - -@smallexample -(display-buffer (process-buffer proc)) -@end smallexample - - To force point to the end of the new output, no matter where it was -previously, eliminate the variable @code{moving} and call -@code{goto-char} unconditionally. - - In earlier Emacs versions, every filter function that did regular -expression searching or matching had to explicitly save and restore the -match data. Now Emacs does this automatically for filter functions; -they never need to do it explicitly. @xref{Match Data}. - - A filter function that writes the output into the buffer of the -process should check whether the buffer is still alive. If it tries to -insert into a dead buffer, it will get an error. The expression -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil} -if the buffer is dead. - - The output to the function may come in chunks of any size. A program -that produces the same output twice in a row may send it as one batch of -200 characters one time, and five batches of 40 characters the next. If -the filter looks for certain text strings in the subprocess output, make -sure to handle the case where one of these strings is split across two -or more batches of output; one way to do this is to insert the -received text into a temporary buffer, which can then be searched. - -@defun set-process-filter process filter -This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process no filter. -@end defun - -@defun process-filter process -This function returns the filter function of @var{process}, or @code{nil} -if it has none. -@end defun - - Here is an example of use of a filter function: - -@smallexample -@group -(defun keep-output (process output) - (setq kept (cons output kept))) - @result{} keep-output -@end group -@group -(setq kept nil) - @result{} nil -@end group -@group -(set-process-filter (get-process "shell") 'keep-output) - @result{} keep-output -@end group -@group -(process-send-string "shell" "ls ~/other\n") - @result{} nil -kept - @result{} ("lewis@@slug[8] % " -@end group -@group -"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ -address.txt backup.psf kolstad.psf -backup.bib~ david.mss resume-Dec-86.mss~ -backup.err david.psf resume-Dec.psf -backup.mss dland syllabus.mss -" -"#backups.mss# backup.mss~ kolstad.mss -") -@end group -@end smallexample - -@ignore @c The code in this example doesn't show the right way to do things. -Here is another, more realistic example, which demonstrates how to use -the process mark to do insertion in the same fashion as is done when -there is no filter function: - -@smallexample -@group -;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} -;; @r{and make sure that buffer is shown in some window.} -(defun my-process-filter (proc str) - (let ((cur (selected-window)) - (pop-up-windows t)) - (pop-to-buffer my-shell-buffer) -@end group -@group - (goto-char (point-max)) - (insert str) - (set-marker (process-mark proc) (point-max)) - (select-window cur))) -@end group -@end smallexample -@end ignore - -@node Decoding Output -@subsection Decoding Process Output -@cindex decode process output - - When Emacs writes process output directly into a multibyte buffer, -it decodes the output according to the process output coding system. -If the coding system is @code{raw-text} or @code{no-conversion}, Emacs -converts the unibyte output to multibyte using -@code{string-to-multibyte}, and inserts the resulting multibyte text. - - You can use @code{set-process-coding-system} to specify which coding -system to use (@pxref{Process Information}). Otherwise, the coding -system comes from @code{coding-system-for-read}, if that is -non-@code{nil}; or else from the defaulting mechanism (@pxref{Default -Coding Systems}). If the text output by a process contains null -bytes, Emacs by default uses @code{no-conversion} for it; see -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to -control this behavior. - - @strong{Warning:} Coding systems such as @code{undecided} which -determine the coding system from the data do not work entirely -reliably with asynchronous subprocess output. This is because Emacs -has to process asynchronous subprocess output in batches, as it -arrives. Emacs must try to detect the proper coding system from one -batch at a time, and this does not always work. Therefore, if at all -possible, specify a coding system that determines both the character -code conversion and the end of line conversion---that is, one like -@code{latin-1-unix}, rather than @code{undecided} or @code{latin-1}. - -@c Let's keep the index entries that were there for -@c set-process-filter-multibyte and process-filter-multibyte-p, -@cindex filter multibyte flag, of process -@cindex process filter multibyte flag - When Emacs calls a process filter function, it provides the process -output as a multibyte string or as a unibyte string according to the -process's filter coding system. Emacs -decodes the output according to the process output coding system, -which usually produces a multibyte string, except for coding systems -such as @code{binary} and @code{raw-text} - -@node Accepting Output -@subsection Accepting Output from Processes -@cindex accept input from processes - - Output from asynchronous subprocesses normally arrives only while -Emacs is waiting for some sort of external event, such as elapsed time -or terminal input. Occasionally it is useful in a Lisp program to -explicitly permit output to arrive at a specific point, or even to wait -until output arrives from a process. - -@defun accept-process-output &optional process seconds millisec just-this-one -This function allows Emacs to read pending output from processes. The -output is inserted in the associated buffers or given to their filter -functions. If @var{process} is non-@code{nil} then this function does -not return until some output has been received from @var{process}. - -@c Emacs 19 feature -The arguments @var{seconds} and @var{millisec} let you specify timeout -periods. The former specifies a period measured in seconds and the -latter specifies one measured in milliseconds. The two time periods -thus specified are added together, and @code{accept-process-output} -returns after that much time, whether or not there has been any -subprocess output. - -The argument @var{millisec} is semi-obsolete nowadays because -@var{seconds} can be a floating point number to specify waiting a -fractional number of seconds. If @var{seconds} is 0, the function -accepts whatever output is pending but does not wait. - -@c Emacs 22.1 feature -If @var{process} is a process, and the argument @var{just-this-one} is -non-@code{nil}, only output from that process is handled, suspending output -from other processes until some output has been received from that -process or the timeout expires. If @var{just-this-one} is an integer, -also inhibit running timers. This feature is generally not -recommended, but may be necessary for specific applications, such as -speech synthesis. - -The function @code{accept-process-output} returns non-@code{nil} if it -did get some output, or @code{nil} if the timeout expired before output -arrived. -@end defun - -@node Sentinels -@section Sentinels: Detecting Process Status Changes -@cindex process sentinel -@cindex sentinel (of process) - - A @dfn{process sentinel} is a function that is called whenever the -associated process changes status for any reason, including signals -(whether sent by Emacs or caused by the process's own actions) that -terminate, stop, or continue the process. The process sentinel is -also called if the process exits. The sentinel receives two -arguments: the process for which the event occurred, and a string -describing the type of event. - - The string describing the event looks like one of the following: - -@itemize @bullet -@item -@code{"finished\n"}. - -@item -@code{"exited abnormally with code @var{exitcode}\n"}. - -@item -@code{"@var{name-of-signal}\n"}. - -@item -@code{"@var{name-of-signal} (core dumped)\n"}. -@end itemize - - A sentinel runs only while Emacs is waiting (e.g., for terminal -input, or for time to elapse, or for process output). This avoids the -timing errors that could result from running them at random places in -the middle of other Lisp programs. A program can wait, so that -sentinels will run, by calling @code{sit-for} or @code{sleep-for} -(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting -Output}). Emacs also allows sentinels to run when the command loop is -reading input. @code{delete-process} calls the sentinel when it -terminates a running process. - - Emacs does not keep a queue of multiple reasons to call the sentinel -of one process; it records just the current status and the fact that -there has been a change. Therefore two changes in status, coming in -quick succession, can call the sentinel just once. However, process -termination will always run the sentinel exactly once. This is -because the process status can't change again after termination. - - Emacs explicitly checks for output from the process before running -the process sentinel. Once the sentinel runs due to process -termination, no further output can arrive from the process. - - A sentinel that writes the output into the buffer of the process -should check whether the buffer is still alive. If it tries to insert -into a dead buffer, it will get an error. If the buffer is dead, -@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. - - Quitting is normally inhibited within a sentinel---otherwise, the -effect of typing @kbd{C-g} at command level or to quit a user command -would be unpredictable. If you want to permit quitting inside a -sentinel, bind @code{inhibit-quit} to @code{nil}. In most cases, the -right way to do this is with the macro @code{with-local-quit}. -@xref{Quitting}. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -sentinel. @xref{Debugger}. - - While a sentinel is running, the process sentinel is temporarily -set to @code{nil} so that the sentinel won't run recursively. -For this reason it is not possible for a sentinel to specify -a new sentinel. - - In earlier Emacs versions, every sentinel that did regular expression -searching or matching had to explicitly save and restore the match data. -Now Emacs does this automatically for sentinels; they never need to do -it explicitly. @xref{Match Data}. - -@defun set-process-sentinel process sentinel -This function associates @var{sentinel} with @var{process}. If -@var{sentinel} is @code{nil}, then the process will have no sentinel. -The default behavior when there is no sentinel is to insert a message in -the process's buffer when the process status changes. - -Changes in process sentinel take effect immediately---if the sentinel -is slated to be run but has not been called yet, and you specify a new -sentinel, the eventual call to the sentinel will use the new one. - -@smallexample -@group -(defun msg-me (process event) - (princ - (format "Process: %s had the event `%s'" process event))) -(set-process-sentinel (get-process "shell") 'msg-me) - @result{} msg-me -@end group -@group -(kill-process (get-process "shell")) - @print{} Process: # had the event `killed' - @result{} # -@end group -@end smallexample -@end defun - -@defun process-sentinel process -This function returns the sentinel of @var{process}, or @code{nil} if it -has none. -@end defun - -@defun waiting-for-user-input-p -While a sentinel or filter function is running, this function returns -non-@code{nil} if Emacs was waiting for keyboard input from the user at -the time the sentinel or filter function was called, @code{nil} if it -was not. -@end defun - -@node Query Before Exit -@section Querying Before Exit - - When Emacs exits, it terminates all its subprocesses by sending them -the @code{SIGHUP} signal. Because subprocesses may be doing -valuable work, Emacs normally asks the user to confirm that it is ok -to terminate them. Each process has a query flag which, if -non-@code{nil}, says that Emacs should ask for confirmation before -exiting and thus killing that process. The default for the query flag -is @code{t}, meaning @emph{do} query. - -@defun process-query-on-exit-flag process -This returns the query flag of @var{process}. -@end defun - -@defun set-process-query-on-exit-flag process flag -This function sets the query flag of @var{process} to @var{flag}. It -returns @var{flag}. - -@smallexample -@group -;; @r{Don't query about the shell process} -(set-process-query-on-exit-flag (get-process "shell") nil) - @result{} t -@end group -@end smallexample -@end defun - -@defun process-kill-without-query process &optional do-query -This function clears the query flag of @var{process}, so that -Emacs will not query the user on account of that process. - -Actually, the function does more than that: it returns the old value of -the process's query flag, and sets the query flag to @var{do-query}. -Please don't use this function to do those things any more---please -use the newer, cleaner functions @code{process-query-on-exit-flag} and -@code{set-process-query-on-exit-flag} in all but the simplest cases. -The only way you should use @code{process-kill-without-query} nowadays -is like this: - -@smallexample -@group -;; @r{Don't query about the shell process} -(process-kill-without-query (get-process "shell")) -@end group -@end smallexample -@end defun - -@node System Processes -@section Accessing Other Processes -@cindex system processes - - In addition to accessing and manipulating processes that are -subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish between them and Emacs -subprocesses. - - Emacs provides several primitives for accessing system processes. -Not all platforms support these primitives; on those which don't, -these primitives return @code{nil}. - -@defun list-system-processes -This function returns a list of all the processes running on the -system. Each process is identified by its @acronym{PID}, a numerical -process ID that is assigned by the OS and distinguishes the process -from all the other processes running on the same machine at the same -time. -@end defun - -@defun process-attributes pid -This function returns an alist of attributes for the process specified -by its process ID @var{pid}. Each association in the alist is of the -form @code{(@var{key} . @var{value})}, where @var{key} designates the -attribute and @var{value} is the value of that attribute. The various -attribute @var{key}'s that this function can return are listed below. -Not all platforms support all of these attributes; if an attribute is -not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating-point, -depending on the magnitude of the value. - -@table @code -@item euid -The effective user ID of the user who invoked the process. The -corresponding @var{value} is a number. If the process was invoked by -the same user who runs the current Emacs session, the value is -identical to what @code{user-uid} returns (@pxref{User -Identification}). - -@item user -User name corresponding to the process's effective user ID, a string. - -@item egid -The group ID of the effective user ID, a number. - -@item group -Group name corresponding to the effective user's group ID, a string. - -@item comm -The name of the command that runs in the process. This is a string -that usually specifies the name of the executable file of the process, -without the leading directories. However, some special system -processes can report strings that do not correspond to an executable -file of a program. - -@item state -The state code of the process. This is a short string that encodes -the scheduling state of the process. Here's a list of the most -frequently seen codes: - -@table @code -@item "D" -uninterruptible sleep (usually I/O) -@item "R" -running -@item "S" -interruptible sleep (waiting for some event) -@item "T" -stopped, e.g., by a job control signal -@item "Z" -``zombie'': a process that terminated, but was not reaped by its parent -@end table - -@noindent -For the full list of the possible states, see the manual page of the -@command{ps} command. - -@item ppid -The process ID of the parent process, a number. - -@item pgrp -The process group ID of the process, a number. - -@item sess -The session ID of the process. This is a number that is the process -ID of the process's @dfn{session leader}. - -@item ttname -A string that is the name of the process's controlling terminal. On -Unix and GNU systems, this is normally the file name of the -corresponding terminal device, such as @file{/dev/pts65}. - -@item tpgid -The numerical process group ID of the foreground process group that -uses the process's terminal. - -@item minflt -The number of minor page faults caused by the process since its -beginning. (Minor page faults are those that don't involve reading -from disk.) - -@item majflt -The number of major page faults caused by the process since its -beginning. (Major page faults require a disk to be read, and are thus -more expensive than minor page faults.) - -@item cminflt -@itemx cmajflt -Like @code{minflt} and @code{majflt}, but include the number of page -faults for all the child processes of the given process. - -@item utime -Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). - -@item stime -Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. - -@item time -The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. - -@item cutime -@itemx cstime -@itemx ctime -Like @code{utime}, @code{stime}, and @code{time}, but include the -times of all the child processes of the given process. - -@item pri -The numerical priority of the process. - -@item nice -The @dfn{nice value} of the process, a number. (Processes with smaller -nice values get scheduled more favorably.) - -@item thcount -The number of threads in the process. - -@item start -The time the process was started, in the @w{@code{(@var{high} -@var{low} @var{microsec})}} format used by @code{current-time} and -@code{file-attributes}. - -@item etime -The time elapsed since the process started, in the @w{@code{(@var{high} -@var{low} @var{microsec})}} format. - -@item vsize -The virtual memory size of the process, measured in kilobytes. - -@item rss -The size of the process's @dfn{resident set}, the number of kilobytes -occupied by the process in the machine's physical memory. - -@item pcpu -The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. - -@item pmem -The percentage of the total physical memory installed on the machine -used by the process's resident set. The value is a floating-point -number between 0 and 100. - -@item args -The command-line with which the process was invoked. This is a string -in which individual command-line arguments are separated by blanks; -whitespace characters that are embedded in the arguments are quoted as -appropriate for the system's shell: escaped by backslash characters on -GNU and Unix, and enclosed in double quote characters on Windows. -Thus, this command-line string can be directly used in primitives such -as @code{shell-command}. -@end table - -@end defun - - -@node Transaction Queues -@section Transaction Queues -@cindex transaction queue - -You can use a @dfn{transaction queue} to communicate with a subprocess -using transactions. First use @code{tq-create} to create a transaction -queue communicating with a specified process. Then you can call -@code{tq-enqueue} to send a transaction. - -@defun tq-create process -This function creates and returns a transaction queue communicating with -@var{process}. The argument @var{process} should be a subprocess -capable of sending and receiving streams of bytes. It may be a child -process, or it may be a TCP connection to a server, possibly on another -machine. -@end defun - -@defun tq-enqueue queue question regexp closure fn &optional delay-question -This function sends a transaction to queue @var{queue}. Specifying the -queue has the effect of specifying the subprocess to talk to. - -The argument @var{question} is the outgoing message that starts the -transaction. The argument @var{fn} is the function to call when the -corresponding answer comes back; it is called with two arguments: -@var{closure}, and the answer received. - -The argument @var{regexp} is a regular expression that should match -text at the end of the entire answer, but nothing before; that's how -@code{tq-enqueue} determines where the answer ends. - -If the argument @var{delay-question} is non-@code{nil}, delay sending -this question until the process has finished replying to any previous -questions. This produces more reliable results with some processes. - -The return value of @code{tq-enqueue} itself is not meaningful. -@end defun - -@defun tq-close queue -Shut down transaction queue @var{queue}, waiting for all pending transactions -to complete, and then terminate the connection or child process. -@end defun - -Transaction queues are implemented by means of a filter function. -@xref{Filter Functions}. - -@node Network -@section Network Connections -@cindex network connection -@cindex TCP -@cindex UDP - - Emacs Lisp programs can open stream (TCP) and datagram (UDP) network -connections to other processes on the same machine or other machines. -A network connection is handled by Lisp much like a subprocess, and is -represented by a process object. However, the process you are -communicating with is not a child of the Emacs process, so it has no -process @acronym{ID}, and you can't kill it or send it signals. All you -can do is send and receive data. @code{delete-process} closes the -connection, but does not kill the program at the other end; that -program must decide what to do about closure of the connection. - - Lisp programs can listen for connections by creating network -servers. A network server is also represented by a kind of process -object, but unlike a network connection, the network server never -transfers data itself. When it receives a connection request, it -creates a new network connection to represent the connection just -made. (The network connection inherits certain information, including -the process plist, from the server.) The network server then goes -back to listening for more connection requests. - - Network connections and servers are created by calling -@code{make-network-process} with an argument list consisting of -keyword/argument pairs, for example @code{:server t} to create a -server process, or @code{:type 'datagram} to create a datagram -connection. @xref{Low-Level Network}, for details. You can also use -the @code{open-network-stream} function described below. - - To distinguish the different types of processes, the -@code{process-type} function returns the symbol @code{network} for a -network connection or server, @code{serial} for a serial port -connection, or @code{real} for a real subprocess. - - The @code{process-status} function returns @code{open}, -@code{closed}, @code{connect}, and @code{failed} for network -connections. For a network server, the status is always -@code{listen}. None of those values is possible for a real -subprocess. @xref{Process Information}. - - You can stop and resume operation of a network process by calling -@code{stop-process} and @code{continue-process}. For a server -process, being stopped means not accepting new connections. (Up to 5 -connection requests will be queued for when you resume the server; you -can increase this limit, unless it is imposed by the operating -system.) For a network stream connection, being stopped means not -processing input (any arriving input waits until you resume the -connection). For a datagram connection, some number of packets may be -queued but input may be lost. You can use the function -@code{process-command} to determine whether a network connection or -server is stopped; a non-@code{nil} value means yes. - -@defun open-network-stream name buffer-or-name host service -This function opens a TCP connection, and returns a process object -that represents the connection. - -The @var{name} argument specifies the name for the process object. It -is modified as necessary to make it unique. - -The @var{buffer-or-name} argument is the buffer to associate with the -connection. Output from the connection is inserted in the buffer, -unless you specify a filter function to handle the output. If -@var{buffer-or-name} is @code{nil}, it means that the connection is not -associated with any buffer. - -The arguments @var{host} and @var{service} specify where to connect to; -@var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). -@end defun - -@node Network Servers -@section Network Servers -@cindex network servers - - You create a server by calling @code{make-network-process} with -@code{:server t}. The server will listen for connection requests from -clients. When it accepts a client connection request, that creates a -new network connection, itself a process object, with the following -parameters: - -@itemize @bullet -@item -The connection's process name is constructed by concatenating the -server process' @var{name} with a client identification string. The -client identification string for an IPv4 connection looks like -@samp{<@var{a}.@var{b}.@var{c}.@var{d}:@var{p}>}. Otherwise, it is a -unique number in brackets, as in @samp{<@var{nnn}>}. The number -is unique for each connection in the Emacs session. - -@item -If the server's filter is non-@code{nil}, the connection process does -not get a separate process buffer; otherwise, Emacs creates a new -buffer for the purpose. The buffer name is the server's buffer name -or process name, concatenated with the client identification string. - -The server's process buffer value is never used directly by Emacs, but -it is passed to the log function, which can log connections by -inserting text there. - -@item -The communication type and the process filter and sentinel are -inherited from those of the server. The server never directly -uses its filter and sentinel; their sole purpose is to initialize -connections made to the server. - -@item -The connection's process contact info is set according to the client's -addressing information (typically an IP address and a port number). -This information is associated with the @code{process-contact} -keywords @code{:host}, @code{:service}, @code{:remote}. - -@item -The connection's local address is set up according to the port -number used for the connection. - -@item -The client process' plist is initialized from the server's plist. -@end itemize - -@node Datagrams -@section Datagrams -@cindex datagrams - - A datagram connection communicates with individual packets rather -than streams of data. Each call to @code{process-send} sends one -datagram packet (@pxref{Input to Processes}), and each datagram -received results in one call to the filter function. - - The datagram connection doesn't have to talk with the same remote -peer all the time. It has a @dfn{remote peer address} which specifies -where to send datagrams to. Each time an incoming datagram is passed -to the filter function, the peer address is set to the address that -datagram came from; that way, if the filter function sends a datagram, -it will go back to that place. You can specify the remote peer -address when you create the datagram connection using the -@code{:remote} keyword. You can change it later on by calling -@code{set-process-datagram-address}. - -@defun process-datagram-address process -If @var{process} is a datagram connection or server, this function -returns its remote peer address. -@end defun - -@defun set-process-datagram-address process address -If @var{process} is a datagram connection or server, this function -sets its remote peer address to @var{address}. -@end defun - -@node Low-Level Network -@section Low-Level Network Access - - You can also create network connections by operating at a lower -level than that of @code{open-network-stream}, using -@code{make-network-process}. - -@menu -* Proc: Network Processes. Using @code{make-network-process}. -* Options: Network Options. Further control over network connections. -* Features: Network Feature Testing. - Determining which network features work on - the machine you are using. -@end menu - -@node Network Processes -@subsection @code{make-network-process} - - The basic function for creating network connections and network -servers is @code{make-network-process}. It can do either of those -jobs, depending on the arguments you give it. - -@defun make-network-process &rest args -This function creates a network connection or server and returns the -process object that represents it. The arguments @var{args} are a -list of keyword/argument pairs. Omitting a keyword is always -equivalent to specifying it with value @code{nil}, except for -@code{:coding}, @code{:filter-multibyte}, and @code{:reuseaddr}. Here -are the meaningful keywords: - -@table @asis -@item :name @var{name} -Use the string @var{name} as the process name. It is modified if -necessary to make it unique. - -@item :type @var{type} -Specify the communication type. A value of @code{nil} specifies a -stream connection (the default); @code{datagram} specifies a datagram -connection. Both connections and servers can be of either type. - -@item :server @var{server-flag} -If @var{server-flag} is non-@code{nil}, create a server. Otherwise, -create a connection. For a stream type server, @var{server-flag} may -be an integer which then specifies the length of the queue of pending -connections to the server. The default queue length is 5. - -@item :host @var{host} -Specify the host to connect to. @var{host} should be a host name or -Internet address, as a string, or the symbol @code{local} to specify -the local host. If you specify @var{host} for a server, it must -specify a valid address for the local host, and only clients -connecting to that address will be accepted. - -@item :service @var{service} -@var{service} specifies a port number to connect to, or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number -directly. For a server, it can also be @code{t}, which means to let -the system select an unused port number. - -@item :family @var{family} -@var{family} specifies the address (and protocol) family for -communication. @code{nil} means determine the proper address family -automatically for the given @var{host} and @var{service}. -@code{local} specifies a Unix socket, in which case @var{host} is -ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6 -respectively. - -@item :local @var{local-address} -For a server process, @var{local-address} is the address to listen on. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. - -@item :remote @var{remote-address} -For a connection, @var{remote-address} is the address to connect to. -It overrides @var{family}, @var{host} and @var{service}, and you -may as well not specify them. - -For a datagram server, @var{remote-address} specifies the initial -setting of the remote datagram address. - -The format of @var{local-address} or @var{remote-address} depends on -the address family: - -@itemize - -@item -An IPv4 address is represented as a five-element vector of four 8-bit -integers and one 16-bit integer -@code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} corresponding to -numeric IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port number -@var{p}. - -@item -An IPv6 address is represented as a nine-element vector of 16-bit -integers @code{[@var{a} @var{b} @var{c} @var{d} @var{e} @var{f} -@var{g} @var{h} @var{p}]} corresponding to numeric IPv6 address -@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h} and -port number @var{p}. - -@item -A local address is represented as a string which specifies the address -in the local address space. - -@item -An ``unsupported family'' address is represented by a cons -@code{(@var{f} . @var{av})}, where @var{f} is the family number and -@var{av} is a vector specifying the socket address using one element -per address data byte. Do not rely on this format in portable code, -as it may depend on implementation defined constants, data sizes, and -data structure alignment. -@end itemize - -@item :nowait @var{bool} -If @var{bool} is non-@code{nil} for a stream connection, return -without waiting for the connection to complete. When the connection -succeeds or fails, Emacs will call the sentinel function, with a -second argument matching @code{"open"} (if successful) or -@code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. - -@item :stop @var{stopped} -Start the network connection or server in the `stopped' state if -@var{stopped} is non-@code{nil}. - -@item :buffer @var{buffer} -Use @var{buffer} as the process buffer. - -@item :coding @var{coding} -Use @var{coding} as the coding system for this process. To specify -different coding systems for decoding data from the connection and for -encoding data sent to it, specify @code{(@var{decoding} . -@var{encoding})} for @var{coding}. - -If you don't specify this keyword at all, the default -is to determine the coding systems from the data. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. -@xref{Query Before Exit}. - -@item :filter @var{filter} -Initialize the process filter to @var{filter}. - -@item :filter-multibyte @var{bool} -If @var{bool} is non-@code{nil}, strings given to the process filter -are multibyte, otherwise they are unibyte. If you don't specify this -keyword at all, the default is that the strings are multibyte if -@code{default-enable-multibyte-characters} is non-@code{nil}. - -@item :sentinel @var{sentinel} -Initialize the process sentinel to @var{sentinel}. - -@item :log @var{log} -Initialize the log function of a server process to @var{log}. The log -function is called each time the server accepts a network connection -from a client. The arguments passed to the log function are -@var{server}, @var{connection}, and @var{message}, where @var{server} -is the server process, @var{connection} is the new process for the -connection, and @var{message} is a string describing what has -happened. - -@item :plist @var{plist} -Initialize the process plist to @var{plist}. -@end table - -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - -@node Network Options -@subsection Network Options - - The following network options can be specified when you create a -network process. Except for @code{:reuseaddr}, you can also set or -modify these options later, using @code{set-network-process-option}. - - For a server process, the options specified with -@code{make-network-process} are not inherited by the client -connections, so you will need to set the necessary options for each -child connection as it is created. - -@table @asis -@item :bindtodevice @var{device-name} -If @var{device-name} is a non-empty string identifying a network -interface name (see @code{network-interface-list}), only handle -packets received on that interface. If @var{device-name} is @code{nil} -(the default), handle packets received on any interface. - -Using this option may require special privileges on some systems. - -@item :broadcast @var{broadcast-flag} -If @var{broadcast-flag} is non-@code{nil} for a datagram process, the -process will receive datagram packet sent to a broadcast address, and -be able to send packets to a broadcast address. Ignored for a stream -connection. - -@item :dontroute @var{dontroute-flag} -If @var{dontroute-flag} is non-@code{nil}, the process can only send -to hosts on the same network as the local host. - -@item :keepalive @var{keepalive-flag} -If @var{keepalive-flag} is non-@code{nil} for a stream connection, -enable exchange of low-level keep-alive messages. - -@item :linger @var{linger-arg} -If @var{linger-arg} is non-@code{nil}, wait for successful -transmission of all queued packets on the connection before it is -deleted (see @code{delete-process}). If @var{linger-arg} is an -integer, it specifies the maximum time in seconds to wait for queued -packets to be sent before closing the connection. Default is -@code{nil} which means to discard unsent queued packets when the -process is deleted. - -@item :oobinline @var{oobinline-flag} -If @var{oobinline-flag} is non-@code{nil} for a stream connection, -receive out-of-band data in the normal data stream. Otherwise, ignore -out-of-band data. - -@item :priority @var{priority} -Set the priority for packets sent on this connection to the integer -@var{priority}. The interpretation of this number is protocol -specific, such as setting the TOS (type of service) field on IP -packets sent on this connection. It may also have system dependent -effects, such as selecting a specific output queue on the network -interface. - -@item :reuseaddr @var{reuseaddr-flag} -If @var{reuseaddr-flag} is non-@code{nil} (the default) for a stream -server process, allow this server to reuse a specific port number (see -@code{:service}) unless another process on this host is already -listening on that port. If @var{reuseaddr-flag} is @code{nil}, there -may be a period of time after the last use of that port (by any -process on the host), where it is not possible to make a new server on -that port. -@end table - -@defun set-network-process-option process option value &optional no-error -This function sets or modifies a network option for network process -@var{process}. See @code{make-network-process} for details of options -@var{option} and their corresponding values @var{value}. If -@var{no-error} is non-@code{nil}, this function returns @code{nil} -instead of signaling an error if @var{option} is not a supported -option. If the function successfully completes, it returns @code{t}. - -The current setting of an option is available via the -@code{process-contact} function. -@end defun - -@node Network Feature Testing -@subsection Testing Availability of Network Features - - To test for the availability of a given network feature, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '(@var{keyword} @var{value})) -@end example - -@noindent -The result of the first form is @code{t} if it works to specify -@var{keyword} with value @var{value} in @code{make-network-process}. -The result of the second form is @code{t} if @var{keyword} is -supported by @code{make-network-process}. Here are some of the -@var{keyword}---@var{value} pairs you can test in -this way. - -@table @code -@item (:nowait t) -Non-@code{nil} if non-blocking connect is supported. -@item (:type datagram) -Non-@code{nil} if datagrams are supported. -@item (:family local) -Non-@code{nil} if local (a.k.a.@: ``UNIX domain'') sockets are supported. -@item (:family ipv6) -Non-@code{nil} if IPv6 is supported. -@item (:service t) -Non-@code{nil} if the system can select the port for a server. -@end table - - To test for the availability of a given network option, use -@code{featurep} like this: - -@example -(featurep 'make-network-process '@var{keyword}) -@end example - -@noindent -Here are some of the options you can test in this way. - -@table @code -@item :bindtodevice -@itemx :broadcast -@itemx :dontroute -@itemx :keepalive -@itemx :linger -@itemx :oobinline -@itemx :priority -@itemx :reuseaddr -That particular network option is supported by -@code{make-network-process} and @code{set-network-process-option}. -@end table - -@node Misc Network -@section Misc Network Facilities - - These additional functions are useful for creating and operating -on network connections. Note that they are supported only on some -systems. - -@defun network-interface-list -This function returns a list describing the network interfaces -of the machine you are using. The value is an alist whose -elements have the form @code{(@var{name} . @var{address})}. -@var{address} has the same form as the @var{local-address} -and @var{remote-address} arguments to @code{make-network-process}. -@end defun - -@defun network-interface-info ifname -This function returns information about the network interface named -@var{ifname}. The value is a list of the form -@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. - -@table @var -@item addr -The Internet protocol address. -@item bcast -The broadcast address. -@item netmask -The network mask. -@item hwaddr -The layer 2 address (Ethernet MAC address, for instance). -@item flags -The current flags of the interface. -@end table -@end defun - -@defun format-network-address address &optional omit-port -This function converts the Lisp representation of a network address to -a string. - -A five-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{p}]} -represents an IPv4 address @var{a}.@var{b}.@var{c}.@var{d} and port -number @var{p}. @code{format-network-address} converts that to the -string @code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. - -A nine-element vector @code{[@var{a} @var{b} @var{c} @var{d} @var{e} -@var{f} @var{g} @var{h} @var{p}]} represents an IPv6 address along -with a port number. @code{format-network-address} converts that to -the string -@code{"[@var{a}:@var{b}:@var{c}:@var{d}:@var{e}:@var{f}:@var{g}:@var{h}]:@var{p}"}. - -If the vector does not include the port number, @var{p}, or if -@var{omit-port} is non-@code{nil}, the result does not include the -@code{:@var{p}} suffix. -@end defun - -@node Serial Ports -@section Communicating with Serial Ports -@cindex @file{/dev/tty} -@cindex @file{COM1} -@cindex serial connections - - Emacs can communicate with serial ports. For interactive use, -@kbd{M-x serial-term} opens a terminal window. In a Lisp program, -@code{make-serial-process} creates a process object. - - The serial port can be configured at run-time, without having to -close and re-open it. The function @code{serial-process-configure} -lets you change the speed, bytesize, and other parameters. In a -terminal window created by @code{serial-term}, you can click on the -mode line for configuration. - - A serial connection is represented by a process object which can be -used similar to a subprocess or network process. You can send and -receive data and configure the serial port. A serial process object -has no process ID, you can't send signals to it, and the status codes -are different from other types of processes. -@code{delete-process} on the process object or @code{kill-buffer} on -the process buffer close the connection, but this does not affect the -device connected to the serial port. - - The function @code{process-type} returns the symbol @code{serial} -for a process object representing a serial port connection. - - Serial ports are available on GNU/Linux, Unix, and Windows systems. - -@deffn Command serial-term port speed -Start a terminal-emulator for a serial port in a new buffer. -@var{port} is the name of the serial port to which to connect. For -example, this could be @file{/dev/ttyS0} on Unix. On Windows, this -could be @file{COM1}, or @file{\\.\COM10} (double the backslashes in -Lisp strings). - -@var{speed} is the speed of the serial port in bits per second. 9600 -is a common value. The buffer is in Term mode; see @ref{Term Mode,,, -emacs, The GNU Emacs Manual}, for the commands to use in that buffer. -You can change the speed and the configuration in the mode line menu. -@end deffn - -@defun make-serial-process &rest args -This function creates a process and a buffer. Arguments are specified -as keyword/argument pairs. Here's the list of the meaningful keywords: - -@table @code -@item :port @var{port}@r{ (mandatory)} -This is the name of the serial port. On Unix and GNU systems, this is -a file name such as @file{/dev/ttyS0}. On Windows, this could be -@file{COM1}, or @file{\\.\COM10} for ports higher than @file{COM9} -(double the backslashes in Lisp strings). - -@item :speed @var{speed}@r{ (mandatory)} -The speed of the serial port in bits per second. This function calls -@code{serial-process-configure} to handle the speed. - -@item :name @var{name} -The name of the process. If @var{name} is not given, @var{port} will -serve as the process name as well. - -@item :buffer @var{buffer} -The buffer to associate with the process. The value could be either a -buffer or a string that names a buffer. Process output goes at the -end of that buffer, unless you specify an output stream or filter -function to handle the output. If @var{buffer} is not given, the -process buffer's name is taken from the value of the @code{:name} -keyword. - -@item :coding @var{coding} -If @var{coding} is a symbol, it specifies the coding system used for -both reading and writing for this process. If @var{coding} is a cons -@code{(decoding . encoding)}, @var{decoding} is used for reading, and -@var{encoding} is used for writing. If not specified, the default is -to determine the coding systems from data itself. - -@item :noquery @var{query-flag} -Initialize the process query flag to @var{query-flag}. @xref{Query -Before Exit}. The flags defaults to @code{nil} if unspecified. - -@item :stop @var{bool} -Start process in the @code{stopped} state if @var{bool} is -non-@code{nil}. In the stopped state, a serial process does not -accept incoming data, but you can send outgoing data. The stopped -state is cleared by @code{continue-process} and set by -@code{stop-process}. - -@item :filter @var{filter} -Install @var{filter} as the process filter. - -@item :sentinel @var{sentinel} -Install @var{sentinel} as the process sentinel. - -@item :plist @var{plist} -Install @var{plist} as the initial plist of the process. - -@item :speed -@itemx :bytesize -@itemx :parity -@itemx :stopbits -@itemx :flowcontrol -These arguments are handled by @code{serial-process-configure}, which -is called by @code{make-serial-process}. -@end table - -The original argument list, possibly modified by later configuration, -is available via the function @code{process-contact}. - -Examples: - -@example -(make-serial-process :port "/dev/ttyS0" :speed 9600) - -(make-serial-process :port "COM1" :speed 115200 :stopbits 2) - -(make-serial-process :port "\\\\.\\COM13" :speed 1200 - :bytesize 7 :parity 'odd) - -(make-serial-process :port "/dev/tty.BlueConsole-SPP-1" - :speed nil) -@end example -@end defun - -@defun serial-process-configure &rest args -@cindex baud, in serial connections -@cindex bytesize, in serial connections -@cindex parity, in serial connections -@cindex stopbits, in serial connections -@cindex flowcontrol, in serial connections - -This functions configures a serial port connection. Arguments are -specified as keyword/argument pairs. Attributes that are not given -are re-initialized from the process's current configuration (available -via the function @code{process-contact}) or set to reasonable default -values. The following arguments are defined: - -@table @code -@item :process @var{process} -@itemx :name @var{name} -@itemx :buffer @var{buffer} -@itemx :port @var{port} -Any of these arguments can be given to identify the process that is to -be configured. If none of these arguments is given, the current -buffer's process is used. - -@item :speed @var{speed} -The speed of the serial port in bits per second, a.k.a.@: @dfn{baud -rate}. The value can be any number, but most serial ports work only -at a few defined values between 1200 and 115200, with 9600 being the -most common value. If @var{speed} is @code{nil}, the function ignores -all other arguments and does not configure the port. This may be -useful for special serial ports such as Bluetooth-to-serial converters -which can only be configured through AT commands sent through the -connection. The value of @code{nil} for @var{speed} is valid only for -connections that were already opened by a previous call to -@code{make-serial-process} or @code{serial-term}. - -@item :bytesize @var{bytesize} -The number of bits per byte, which can be 7 or 8. If @var{bytesize} -is not given or @code{nil}, it defaults to 8. - -@item :parity @var{parity} -The value can be @code{nil} (don't use parity), the symbol -@code{odd} (use odd parity), or the symbol @code{even} (use even -parity). If @var{parity} is not given, it defaults to no parity. - -@item :stopbits @var{stopbits} -The number of stopbits used to terminate a transmission -of each byte. @var{stopbits} can be 1 or 2. If @var{stopbits} is not -given or @code{nil}, it defaults to 1. - -@item :flowcontrol @var{flowcontrol} -The type of flow control to use for this connection, which is either -@code{nil} (don't use flow control), the symbol @code{hw} (use RTS/CTS -hardware flow control), or the symbol @code{sw} (use XON/XOFF software -flow control). If @var{flowcontrol} is not given, it defaults to no -flow control. -@end table - -@code{serial-process-configure} is called by @code{make-serial-process} for the -initial configuration of the serial port. - -Examples: - -@example -(serial-process-configure :process "/dev/ttyS0" :speed 1200) - -(serial-process-configure :buffer "COM1" :stopbits 1 - :parity 'odd :flowcontrol 'hw) - -(serial-process-configure :port "\\\\.\\COM13" :bytesize 7) -@end example -@end defun - -@node Byte Packing -@section Packing and Unpacking Byte Arrays -@cindex byte packing and unpacking - - This section describes how to pack and unpack arrays of bytes, -usually for binary network protocols. These functions convert byte arrays -to alists, and vice versa. The byte array can be represented as a -unibyte string or as a vector of integers, while the alist associates -symbols either with fixed-size objects or with recursive sub-alists. - -@cindex serializing -@cindex deserializing -@cindex packing -@cindex unpacking - Conversion from byte arrays to nested alists is also known as -@dfn{deserializing} or @dfn{unpacking}, while going in the opposite -direction is also known as @dfn{serializing} or @dfn{packing}. - -@menu -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! -@end menu - -@node Bindat Spec -@subsection Describing Data Layout - - To control unpacking and packing, you write a @dfn{data layout -specification}, a special nested list describing named and typed -@dfn{fields}. This specification controls length of each field to be -processed, and how to pack or unpack it. We normally keep bindat specs -in variables whose names end in @samp{-bindat-spec}; that kind of name -is automatically recognized as ``risky.'' - -@cindex endianness -@cindex big endian -@cindex little endian -@cindex network byte ordering - A field's @dfn{type} describes the size (in bytes) of the object -that the field represents and, in the case of multibyte fields, how -the bytes are ordered within the field. The two possible orderings -are ``big endian'' (also known as ``network byte ordering'') and -``little endian.'' For instance, the number @code{#x23cd} (decimal -9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; -and in little endian, @code{#xcd} @code{#x23}. Here are the possible -type values: - -@table @code -@item u8 -@itemx byte -Unsigned byte, with length 1. - -@item u16 -@itemx word -@itemx short -Unsigned integer in network byte order, with length 2. - -@item u24 -Unsigned integer in network byte order, with length 3. - -@item u32 -@itemx dword -@itemx long -Unsigned integer in network byte order, with length 4. -Note: These values may be limited by Emacs' integer implementation limits. - -@item u16r -@itemx u24r -@itemx u32r -Unsigned integer in little endian order, with length 2, 3 and 4, respectively. - -@item str @var{len} -String of length @var{len}. - -@item strz @var{len} -Zero-terminated string, in a fixed-size field with length @var{len}. - -@item vec @var{len} [@var{type}] -Vector of @var{len} elements of type @var{type}, or bytes if not -@var{type} is specified. -The @var{type} is any of the simple types above, or another vector -specified as a list @code{(vec @var{len} [@var{type}])}. - -@item ip -Four-byte vector representing an Internet address. For example: -@code{[127 0 0 1]} for localhost. - -@item bits @var{len} -List of set bits in @var{len} bytes. The bytes are taken in big -endian order and the bits are numbered starting with @code{8 * -@var{len} @minus{} 1} and ending with zero. For example: @code{bits -2} unpacks @code{#x28} @code{#x1c} to @code{(2 3 4 11 13)} and -@code{#x1c} @code{#x28} to @code{(3 5 10 11 12)}. - -@item (eval @var{form}) -@var{form} is a Lisp expression evaluated at the moment the field is -unpacked or packed. The result of the evaluation should be one of the -above-listed type specifications. -@end table - -For a fixed-size field, the length @var{len} is given as an integer -specifying the number of bytes in the field. - -When the length of a field is not fixed, it typically depends on the -value of a preceding field. In this case, the length @var{len} can be -given either as a list @code{(@var{name} ...)} identifying a -@dfn{field name} in the format specified for @code{bindat-get-field} -below, or by an expression @code{(eval @var{form})} where @var{form} -should evaluate to an integer, specifying the field length. - -A field specification generally has the form @code{([@var{name}] -@var{handler})}. The square braces indicate that @var{name} is -optional. (Don't use names that are symbols meaningful as type -specifications (above) or handler specifications (below), since that -would be ambiguous.) @var{name} can be a symbol or the expression -@code{(eval @var{form})}, in which case @var{form} should evaluate to -a symbol. - -@var{handler} describes how to unpack or pack the field and can be one -of the following: - -@table @code -@item @var{type} -Unpack/pack this field according to the type specification @var{type}. - -@item eval @var{form} -Evaluate @var{form}, a Lisp expression, for side-effect only. If the -field name is specified, the value is bound to that field name. - -@item fill @var{len} -Skip @var{len} bytes. In packing, this leaves them unchanged, -which normally means they remain zero. In unpacking, this means -they are ignored. - -@item align @var{len} -Skip to the next multiple of @var{len} bytes. - -@item struct @var{spec-name} -Process @var{spec-name} as a sub-specification. This describes a -structure nested within another structure. - -@item union @var{form} (@var{tag} @var{spec})@dots{} -@c ??? I don't see how one would actually use this. -@c ??? what kind of expression would be useful for @var{form}? -Evaluate @var{form}, a Lisp expression, find the first @var{tag} -that matches it, and process its associated data layout specification -@var{spec}. Matching can occur in one of three ways: - -@itemize -@item -If a @var{tag} has the form @code{(eval @var{expr})}, evaluate -@var{expr} with the variable @code{tag} dynamically bound to the value -of @var{form}. A non-@code{nil} result indicates a match. - -@item -@var{tag} matches if it is @code{equal} to the value of @var{form}. - -@item -@var{tag} matches unconditionally if it is @code{t}. -@end itemize - -@item repeat @var{count} @var{field-specs}@dots{} -Process the @var{field-specs} recursively, in order, then repeat -starting from the first one, processing all the specs @var{count} -times overall. The @var{count} is given using the same formats as a -field length---if an @code{eval} form is used, it is evaluated just once. -For correct operation, each spec in @var{field-specs} must include a name. -@end table - -For the @code{(eval @var{form})} forms used in a bindat specification, -the @var{form} can access and update these dynamically bound variables -during evaluation: - -@table @code -@item last -Value of the last field processed. - -@item bindat-raw -The data as a byte array. - -@item bindat-idx -Current index (within @code{bindat-raw}) for unpacking or packing. - -@item struct -The alist containing the structured data that have been unpacked so -far, or the entire structure being packed. You can use -@code{bindat-get-field} to access specific fields of this structure. - -@item count -@itemx index -Inside a @code{repeat} block, these contain the maximum number of -repetitions (as specified by the @var{count} parameter), and the -current repetition number (counting from 0). Setting @code{count} to -zero will terminate the inner-most repeat block after the current -repetition has completed. -@end table - -@node Bindat Functions -@subsection Functions to Unpack and Pack Bytes - - In the following documentation, @var{spec} refers to a data layout -specification, @code{bindat-raw} to a byte array, and @var{struct} to an -alist representing unpacked field data. - -@defun bindat-unpack spec bindat-raw &optional bindat-idx -This function unpacks data from the unibyte string or byte -array @code{bindat-raw} -according to @var{spec}. Normally this starts unpacking at the -beginning of the byte array, but if @var{bindat-idx} is non-@code{nil}, it -specifies a zero-based starting position to use instead. - -The value is an alist or nested alist in which each element describes -one unpacked field. -@end defun - -@defun bindat-get-field struct &rest name -This function selects a field's data from the nested alist -@var{struct}. Usually @var{struct} was returned by -@code{bindat-unpack}. If @var{name} corresponds to just one argument, -that means to extract a top-level field value. Multiple @var{name} -arguments specify repeated lookup of sub-structures. An integer name -acts as an array index. - -For example, if @var{name} is @code{(a b 2 c)}, that means to find -field @code{c} in the third element of subfield @code{b} of field -@code{a}. (This corresponds to @code{struct.a.b[2].c} in C.) -@end defun - - Although packing and unpacking operations change the organization of -data (in memory), they preserve the data's @dfn{total length}, which is -the sum of all the fields' lengths, in bytes. This value is not -generally inherent in either the specification or alist alone; instead, -both pieces of information contribute to its calculation. Likewise, the -length of a string or array being unpacked may be longer than the data's -total length as described by the specification. - -@defun bindat-length spec struct -This function returns the total length of the data in @var{struct}, -according to @var{spec}. -@end defun - -@defun bindat-pack spec struct &optional bindat-raw bindat-idx -This function returns a byte array packed according to @var{spec} from -the data in the alist @var{struct}. Normally it creates and fills a -new byte array starting at the beginning. However, if @var{bindat-raw} -is non-@code{nil}, it specifies a pre-allocated unibyte string or vector to -pack into. If @var{bindat-idx} is non-@code{nil}, it specifies the starting -offset for packing into @code{bindat-raw}. - -When pre-allocating, you should make sure @code{(length @var{bindat-raw})} -meets or exceeds the total length to avoid an out-of-range error. -@end defun - -@defun bindat-ip-to-string ip -Convert the Internet address vector @var{ip} to a string in the usual -dotted notation. - -@example -(bindat-ip-to-string [127 0 0 1]) - @result{} "127.0.0.1" -@end example -@end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing - - Here is a complete example of byte unpacking and packing: - -@lisp -(defvar fcookie-index-spec - '((:version u32) - (:count u32) - (:longest u32) - (:shortest u32) - (:flags u32) - (:delim u8) - (:ignored fill 3) - (:offset repeat (:count) - (:foo u32))) - "Description of a fortune cookie index file's contents.") - -(defun fcookie (cookies &optional index) - "Display a random fortune cookie from file COOKIES. -Optional second arg INDEX specifies the associated index -filename, which is by default constructed by appending -\".dat\" to COOKIES. Display cookie text in possibly -new buffer \"*Fortune Cookie: BASENAME*\" where BASENAME -is COOKIES without the directory part." - (interactive "fCookies file: ") - (let* ((info (with-temp-buffer - (insert-file-contents-literally - (or index (concat cookies ".dat"))) - (bindat-unpack fcookie-index-spec - (buffer-string)))) - (sel (random (bindat-get-field info :count))) - (beg (cdar (bindat-get-field info :offset sel))) - (end (or (cdar (bindat-get-field info - :offset (1+ sel))) - (nth 7 (file-attributes cookies))))) - (switch-to-buffer - (get-buffer-create - (format "*Fortune Cookie: %s*" - (file-name-nondirectory cookies)))) - (erase-buffer) - (insert-file-contents-literally - cookies nil beg (- end 3)))) - -(defun fcookie-create-index (cookies &optional index delim) - "Scan file COOKIES, and write out its index file. -Optional second arg INDEX specifies the index filename, -which is by default constructed by appending \".dat\" to -COOKIES. Optional third arg DELIM specifies the unibyte -character which, when found on a line of its own in -COOKIES, indicates the border between entries." - (interactive "fCookies file: ") - (setq delim (or delim ?%)) - (let ((delim-line (format "\n%c\n" delim)) - (count 0) - (max 0) - min p q len offsets) - (unless (= 3 (string-bytes delim-line)) - (error "Delimiter cannot be represented in one byte")) - (with-temp-buffer - (insert-file-contents-literally cookies) - (while (and (setq p (point)) - (search-forward delim-line (point-max) t) - (setq len (- (point) 3 p))) - (setq count (1+ count) - max (max max len) - min (min (or min max) len) - offsets (cons (1- p) offsets)))) - (with-temp-buffer - (set-buffer-multibyte nil) - (insert - (bindat-pack - fcookie-index-spec - `((:version . 2) - (:count . ,count) - (:longest . ,max) - (:shortest . ,min) - (:flags . 0) - (:delim . ,delim) - (:offset . ,(mapcar (lambda (o) - (list (cons :foo o))) - (nreverse offsets)))))) - (let ((coding-system-for-write 'raw-text-unix)) - (write-file (or index (concat cookies ".dat"))))))) -@end lisp - -Following is an example of defining and unpacking a complex structure. -Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* In network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* In little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ;; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ;; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -Fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp - -@ignore - arch-tag: ba9da253-e65f-4e7f-b727-08fba0a1df7a -@end ignore diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi deleted file mode 100644 index 2b89a89c3e9..00000000000 --- a/doc/lispref/searching.texi +++ /dev/null @@ -1,1842 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/searching -@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top -@chapter Searching and Matching -@cindex searching - - GNU Emacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the @dfn{match data} to -determine which text matched the whole regular expression or various -portions of it. - -@menu -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -@end menu - - The @samp{skip-chars@dots{}} functions also perform a kind of searching. -@xref{Skipping Characters}. To search for changes in character -properties, see @ref{Property Search}. - -@node String Search -@section Searching for Strings -@cindex string search - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; the -arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} -is 1. - - These search functions convert the search string to multibyte if the -buffer is multibyte; they convert the search string to unibyte if the -buffer is unibyte. @xref{Text Representations}. - -@deffn Command search-forward string &optional limit noerror repeat -This function searches forward from point for an exact match for -@var{string}. If successful, it sets point to the end of the occurrence -found, and returns the new value of point. If no match is found, the -value and side effects depend on @var{noerror} (see below). -@c Emacs 19 feature - -In the following example, point is initially at the beginning of the -line. Then @code{(search-forward "fox")} moves point after the last -letter of @samp{fox}: - -@example -@group ----------- Buffer: foo ---------- -@point{}The quick brown fox jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group - -@group -(search-forward "fox") - @result{} 20 - ----------- Buffer: foo ---------- -The quick brown fox@point{} jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group -@end example - -The argument @var{limit} specifies the upper bound to the search. (It -must be a position in the current buffer.) No match extending after -that position is accepted. If @var{limit} is omitted or @code{nil}, it -defaults to the end of the accessible portion of the buffer. - -@kindex search-failed -What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, @code{search-forward} -returns @code{nil} and does nothing. If @var{noerror} is neither -@code{nil} nor @code{t}, then @code{search-forward} moves point to the -upper bound and returns @code{nil}. (It would be more consistent now to -return the new position of point in that case, but some existing -programs may depend on a value of @code{nil}.) - -The argument @var{noerror} only affects valid searches which fail to -find a match. Invalid arguments cause errors regardless of -@var{noerror}. - -If @var{repeat} is supplied (it must be a positive number), then the -search is repeated that many times (each time starting at the end of the -previous time's match). If these successive searches succeed, the -function succeeds, moving point and returning its new value. Otherwise -the search fails, with results depending on the value of -@var{noerror}, as described above. -@end deffn - -@deffn Command search-backward string &optional limit noerror repeat -This function searches backward from point for @var{string}. It is -just like @code{search-forward} except that it searches backwards and -leaves point at the beginning of the match. -@end deffn - -@deffn Command word-search-forward string &optional limit noerror repeat -This function searches forward from point for a ``word'' match for -@var{string}. If it finds a match, it sets point to the end of the -match found, and returns the new value of point. - -Word matching regards @var{string} as a sequence of words, disregarding -punctuation that separates them. It searches the buffer for the same -sequence of words. Each word must be distinct in the buffer (searching -for the word @samp{ball} does not match the word @samp{balls}), but the -details of punctuation and spacing are ignored (searching for @samp{ball -boy} does match @samp{ball. Boy!}). - -In this example, point is initially at the beginning of the buffer; the -search leaves it between the @samp{y} and the @samp{!}. - -@example -@group ----------- Buffer: foo ---------- -@point{}He said "Please! Find -the ball boy!" ----------- Buffer: foo ---------- -@end group - -@group -(word-search-forward "Please find the ball, boy.") - @result{} 35 - ----------- Buffer: foo ---------- -He said "Please! Find -the ball boy@point{}!" ----------- Buffer: foo ---------- -@end group -@end example - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer; it specifies the upper bound to the search. The match found -must not extend after that position. - -If @var{noerror} is @code{nil}, then @code{word-search-forward} signals -an error if the search fails. If @var{noerror} is @code{t}, then it -returns @code{nil} instead of signaling an error. If @var{noerror} is -neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the -end of the accessible portion of the buffer) and returns @code{nil}. - -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. -@end deffn - -@deffn Command word-search-forward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-forward}, except that -the end of @code{string} need not match a word boundary unless it ends -in whitespace. For instance, searching for @samp{ball boy} matches -@samp{ball boyee}, but does not match @samp{aball boy}. -@end deffn - -@deffn Command word-search-backward string &optional limit noerror repeat -This function searches backward from point for a word match to -@var{string}. This function is just like @code{word-search-forward} -except that it searches backward and normally leaves point at the -beginning of the match. -@end deffn - -@deffn Command word-search-backward-lax string &optional limit noerror repeat -This command is identical to @code{word-search-backward}, except that -the end of @code{string} need not match a word boundary unless it ends -in whitespace. -@end deffn - -@node Searching and Case -@section Searching and Case -@cindex searching and case - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for @samp{FOO}, then -@samp{Foo} or @samp{foo} is also considered a match. This applies to -regular expressions, too; thus, @samp{[aB]} would match @samp{a} or -@samp{A} or @samp{b} or @samp{B}. - - If you do not want this feature, set the variable -@code{case-fold-search} to @code{nil}. Then all letters must match -exactly, including case. This is a buffer-local variable; altering the -variable affects only the current buffer. (@xref{Intro to -Buffer-Local}.) Alternatively, you may change the value of -@code{default-case-fold-search}, which is the default value of -@code{case-fold-search} for buffers that do not override it. - - Note that the user-level incremental search feature handles case -distinctions differently. When the search string contains only lower -case letters, the search ignores case, but when the search string -contains one or more upper case letters, the search becomes -case-sensitive. But this has nothing to do with the searching -functions used in Lisp code. - -@defopt case-fold-search -This buffer-local variable determines whether searches should ignore -case. If the variable is @code{nil} they do not ignore case; otherwise -they do ignore case. -@end defopt - -@defvar default-case-fold-search -The value of this variable is the default value for -@code{case-fold-search} in buffers that do not override it. This is the -same as @code{(default-value 'case-fold-search)}. -@end defvar - -@defopt case-replace -This variable determines whether the higher level replacement -functions should preserve case. If the variable is @code{nil}, that -means to use the replacement text verbatim. A non-@code{nil} value -means to convert the case of the replacement text according to the -text being replaced. - -This variable is used by passing it as an argument to the function -@code{replace-match}. @xref{Replacing Match}. -@end defopt - -@node Regular Expressions -@section Regular Expressions -@cindex regular expression -@cindex regexp - - A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to write -regexps; the following section says how to search for them. - -@findex re-builder -@cindex regular expressions, developing - For convenient interactive development of regular expressions, you -can use the @kbd{M-x re-builder} command. It provides a convenient -interface for creating regular expressions, by giving immediate visual -feedback in a separate buffer. As you edit the regexp, all its -matches in the target buffer are highlighted. Each parenthesized -sub-expression of the regexp is shown in a distinct face, which makes -it easier to verify even very complex regexps. - -@menu -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. -@end menu - -@node Syntax of Regexps -@subsection Syntax of Regular Expressions - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression that matches that character -and nothing else. The special characters are @samp{.}, @samp{*}, -@samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new -special characters will be defined in the future. The character -@samp{]} is special if it ends a character alternative (see later). -The character @samp{-} is special inside a character alternative. A -@samp{[:} and balancing @samp{:]} enclose a character class inside a -character alternative. Any other character appearing in a regular -expression is ordinary, unless a @samp{\} precedes it. - - For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{fg}, but it does match a @emph{part} of that string.) Likewise, -@samp{o} is a regular expression that matches only @samp{o}.@refill - - Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression that matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - - As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special regular expression constructs. - -@menu -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. -@end menu - -@node Regexp Special -@subsubsection Special Characters in Regular Expressions - - Here is a list of the characters that are special in a regular -expression. - -@need 800 -@table @asis -@item @samp{.}@: @r{(Period)} -@cindex @samp{.} in regexp -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item @samp{*} -@cindex @samp{*} in regexp -is not a construct by itself; it is a postfix operator that means to -match the preceding regular expression repetitively as many times as -possible. Thus, @samp{o*} matches any number of @samp{o}s (including no -@samp{o}s). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, as -many repetitions as can be found. Then it continues with the rest of -the pattern. If that fails, backtracking occurs, discarding some of the -matches of the @samp{*}-modified construct in the hope that that will -make it possible to match the rest of the pattern. For example, in -matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} -first tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. With -this choice, the rest of the regexp matches successfully. - -@strong{Warning:} Nested repetition operators can run for an -indefinitely long time, if they lead to ambiguous matching. For -example, trying to match the regular expression @samp{\(x+y*\)*a} -against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs must try each way of -grouping the @samp{x}s before concluding that none of them can work. -Even worse, @samp{\(x*\)*} can match the null string in infinitely -many ways, so it causes an infinite loop. To avoid these problems, -check nested repetitions carefully, to make sure that they do not -cause combinatorial explosions in backtracking. - -@item @samp{+} -@cindex @samp{+} in regexp -is a postfix operator, similar to @samp{*} except that it must match -the preceding expression at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item @samp{?} -@cindex @samp{?} in regexp -is a postfix operator, similar to @samp{*} except that it must match the -preceding expression either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. - -@item @samp{*?}, @samp{+?}, @samp{??} -@cindex non-greedy repetition characters in regexp -These are ``non-greedy'' variants of the operators @samp{*}, @samp{+} -and @samp{?}. Where those operators match the largest possible -substring (consistent with matching the entire containing expression), -the non-greedy variants match the smallest possible substring -(consistent with matching the entire containing expression). - -For example, the regular expression @samp{c[ad]*a} when applied to the -string @samp{cdaaada} matches the whole string; but the regular -expression @samp{c[ad]*?a}, applied to that same string, matches just -@samp{cda}. (The smallest possible match here for @samp{[ad]*?} that -permits the whole expression to match is @samp{d}.) - -@item @samp{[ @dots{} ]} -@cindex character alternative (in regexp) -@cindex @samp{[} in regexp -@cindex @samp{]} in regexp -is a @dfn{character alternative}, which begins with @samp{[} and is -terminated by @samp{]}. In the simplest case, the characters between -the two brackets are what this character alternative can match. - -Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and -@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s -(including the empty string), from which it follows that @samp{c[ad]*r} -matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. - -You can also include character ranges in a character alternative, by -writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. -Ranges may be intermixed freely with individual characters, as in -@samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter -or @samp{$}, @samp{%} or period. - -Note that the usual regexp special characters are not special inside a -character alternative. A completely different set of characters is -special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character alternative, you must make it the -first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. -To include a @samp{-}, write @samp{-} as the first or last character of -the character alternative, or put it after a range. Thus, @samp{[]-]} -matches both @samp{]} and @samp{-}. - -To include @samp{^} in a character alternative, put it anywhere but at -the beginning. - -The beginning and end of a range of multibyte characters must be in -the same character set (@pxref{Character Sets}). Thus, -@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a} -with grave accent) is in the Emacs character set for Latin-1 but the -character 0x97c (@samp{u} with diaeresis) is in the Emacs character -set for Latin-2. (We use Lisp string syntax to write that example, -and a few others in the next few paragraphs, in order to include hex -escape sequences in them.) - -If a range starts with a unibyte character @var{c} and ends with a -multibyte character @var{c2}, the range is divided into two parts: one -is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where -@var{c1} is the first character of the charset to which @var{c2} -belongs. - -You cannot always match all non-@acronym{ASCII} characters with the regular -expression @code{"[\200-\377]"}. This works when searching a unibyte -buffer or string (@pxref{Text Representations}), but not in a multibyte -buffer or string, because many non-@acronym{ASCII} characters have codes -above octal 0377. However, the regular expression @code{"[^\000-\177]"} -does match all non-@acronym{ASCII} characters (see below regarding @samp{^}), -in both multibyte and unibyte representations, because only the -@acronym{ASCII} characters are excluded. - -A character alternative can also specify named -character classes (@pxref{Char Classes}). This is a POSIX feature whose -syntax is @samp{[:@var{class}:]}. Using a character class is equivalent -to mentioning each of the characters in that class; but the latter is -not feasible in practice, since some classes include thousands of -different characters. - -@item @samp{[^ @dots{} ]} -@cindex @samp{^} in regexp -@samp{[^} begins a @dfn{complemented character alternative}. This -matches any character except the ones specified. Thus, -@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and -digits. - -@samp{^} is not special in a character alternative unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character alternative can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @samp{^} -@cindex beginning of line in regexp -When matching a buffer, @samp{^} matches the empty string, but only at the -beginning of a line in the text being matched (or the beginning of the -accessible portion of the buffer). Otherwise it fails to match -anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the -beginning of a line. - -When matching a string instead of a buffer, @samp{^} matches at the -beginning of the string or after a newline character. - -For historical compatibility reasons, @samp{^} can be used only at the -beginning of the regular expression, or after @samp{\(}, @samp{\(?:} -or @samp{\|}. - -@item @samp{$} -@cindex @samp{$} in regexp -@cindex end of line in regexp -is similar to @samp{^} but matches only at the end of a line (or the -end of the accessible portion of the buffer). Thus, @samp{x+$} -matches a string of one @samp{x} or more at the end of a line. - -When matching a string instead of a buffer, @samp{$} matches at the end -of the string or before a newline character. - -For historical compatibility reasons, @samp{$} can be used only at the -end of the regular expression, or before @samp{\)} or @samp{\|}. - -@item @samp{\} -@cindex @samp{\} in regexp -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -Note that @samp{\} also has special meaning in the read syntax of Lisp -strings (@pxref{String Type}), and must be quoted with @samp{\}. For -example, the regular expression that matches the @samp{\} character is -@samp{\\}. To write a Lisp string that contains the characters -@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another -@samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}.@refill -@end table - -@strong{Please note:} For historical compatibility, special characters -are treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, @samp{*foo} treats @samp{*} as -ordinary since there is no preceding expression on which the @samp{*} -can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears.@refill - -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. - -In practice, most @samp{]} that occur in regular expressions close a -character alternative and hence are special. However, occasionally a -regular expression may try to match a complex pattern of literal -@samp{[} and @samp{]}. In such situations, it sometimes may be -necessary to carefully parse the regexp from the start to determine -which square brackets enclose a character alternative. For example, -@samp{[^][]]} consists of the complemented character alternative -@samp{[^][]} (which matches any single character that is not a square -bracket), followed by a literal @samp{]}. - -The exact rules are that at the beginning of a regexp, @samp{[} is -special and @samp{]} not. This lasts until the first unquoted -@samp{[}, after which we are in a character alternative; @samp{[} is -no longer special (except when it starts a character class) but @samp{]} -is special, unless it immediately follows the special @samp{[} or that -@samp{[} followed by a @samp{^}. This lasts until the next special -@samp{]} that does not end a character class. This ends the character -alternative and restores the ordinary syntax of regular expressions; -an unquoted @samp{[} is special again and a @samp{]} not. - -@node Char Classes -@subsubsection Character Classes -@cindex character classes in regexp - - Here is a table of the classes you can use in a character alternative, -and what they mean: - -@table @samp -@item [:ascii:] -This matches any @acronym{ASCII} character (codes 0--127). -@item [:alnum:] -This matches any letter or digit. (At present, for multibyte -characters, it matches anything that has word syntax.) -@item [:alpha:] -This matches any letter. (At present, for multibyte characters, it -matches anything that has word syntax.) -@item [:blank:] -This matches space and tab only. -@item [:cntrl:] -This matches any @acronym{ASCII} control character. -@item [:digit:] -This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} -matches any digit, as well as @samp{+} and @samp{-}. -@item [:graph:] -This matches graphic characters---everything except @acronym{ASCII} control -characters, space, and the delete character. -@item [:lower:] -This matches any lower-case letter, as determined by -the current case table (@pxref{Case Tables}). -@item [:multibyte:] -This matches any multibyte character (@pxref{Text Representations}). -@item [:nonascii:] -This matches any non-@acronym{ASCII} character. -@item [:print:] -This matches printing characters---everything except @acronym{ASCII} control -characters and the delete character. -@item [:punct:] -This matches any punctuation character. (At present, for multibyte -characters, it matches anything that has non-word syntax.) -@item [:space:] -This matches any character that has whitespace syntax -(@pxref{Syntax Class Table}). -@item [:unibyte:] -This matches any unibyte character (@pxref{Text Representations}). -@item [:upper:] -This matches any upper-case letter, as determined by -the current case table (@pxref{Case Tables}). -@item [:word:] -This matches any character that has word syntax (@pxref{Syntax Class -Table}). -@item [:xdigit:] -This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} -through @samp{f} and @samp{A} through @samp{F}. -@end table - -@node Regexp Backslash -@subsubsection Backslash Constructs in Regular Expressions - - For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: certain -two-character sequences starting with @samp{\} that have special -meanings. (The character after the @samp{\} in such a sequence is -always ordinary when used on its own.) Here is a table of the special -@samp{\} constructs. - -@table @samp -@item \| -@cindex @samp{|} in regexp -@cindex regexp alternative -specifies an alternative. -Two regular expressions @var{a} and @var{b} with @samp{\|} in -between form an expression that matches anything that either @var{a} or -@var{b} matches.@refill - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -If you need full backtracking capability to handle multiple uses of -@samp{\|}, use the POSIX regular expression functions (@pxref{POSIX -Regexps}). - -@item \@{@var{m}\@} -is a postfix operator that repeats the previous pattern exactly @var{m} -times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx} -and nothing else. @samp{c[ad]\@{3\@}r} matches string such as -@samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on. - -@item \@{@var{m},@var{n}\@} -is a more general postfix operator that specifies repetition with a -minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m} -is omitted, the minimum is 0; if @var{n} is omitted, there is no -maximum. - -For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car}, -@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and -nothing else.@* -@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @* -@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @* -@samp{\@{1,\@}} is equivalent to @samp{+}. - -@item \( @dots{} \) -@cindex @samp{(} in regexp -@cindex @samp{)} in regexp -@cindex regexp grouping -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. Thus, -the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} -or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any -number (zero or more) of @samp{na} strings. - -@item -To record a matched substring for future reference with -@samp{\@var{digit}} (see below). -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that was assigned as a -second meaning to the same @samp{\( @dots{} \)} construct because, in -practice, there was usually no conflict between the two meanings. But -occasionally there is a conflict, and that led to the introduction of -shy groups. - -@item \(?: @dots{} \) -@cindex shy groups -@cindex non-capturing group -@cindex unnumbered group -@cindex @samp{(?:} in regexp -is the @dfn{shy group} construct. A shy group serves the first two -purposes of an ordinary group (controlling the nesting of other -operators), but it does not get a number, so you cannot refer back to -its value with @samp{\@var{digit}}. Shy groups are particularly -useful for mechanically-constructed regular expressions, because they -can be added automatically without altering the numbering of ordinary, -non-shy groups. - -Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered -groups}. - -@item \(?@var{num}: @dots{} \) -is the @dfn{explicitly numbered group} construct. Normal groups get -their number implicitly, based on their position, which can be -inconvenient. This construct allows you to force a particular group -number. There is no particular restriction on the numbering, -e.g.@: you can have several groups with the same number in which case -the last one to match (i.e.@: the rightmost match) will win. -Implicitly numbered groups always get the smallest integer larger than -the one of any previous group. - -@item \@var{digit} -matches the same text that matched the @var{digit}th occurrence of a -grouping (@samp{\( @dots{} \)}) construct. - -In other words, after the end of a group, the matcher remembers the -beginning and end of the text matched by that group. Later on in the -regular expression you can use @samp{\} followed by @var{digit} to -match that same text, whatever it may have been. - -The strings matching the first nine grouping constructs appearing in -the entire regular expression passed to a search or matching function -are assigned numbers 1 through 9 in the order that the open -parentheses appear in the regular expression. So you can use -@samp{\1} through @samp{\9} to refer to the text matched by the -corresponding grouping constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a @samp{\( @dots{} \)} construct matches more than once (which can -happen, for instance, if it is followed by @samp{*}), only the last -match is recorded. - -If a particular grouping construct in the regular expression was never -matched---for instance, if it appears inside of an alternative that -wasn't used, or inside of a repetition that repeated zero times---then -the corresponding @samp{\@var{digit}} construct never matches -anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2} -cannot match @samp{lose}: the second alternative inside the larger -group matches it, but then @samp{\2} is undefined and can't match -anything. But it can match @samp{foobb}, because the first -alternative matches @samp{foob} and @samp{\2} matches @samp{b}. - -@item \w -@cindex @samp{\w} in regexp -matches any word-constituent character. The editor syntax table -determines which characters these are. @xref{Syntax Tables}. - -@item \W -@cindex @samp{\W} in regexp -matches any character that is not a word constituent. - -@item \s@var{code} -@cindex @samp{\s} in regexp -matches any character whose syntax is @var{code}. Here @var{code} is a -character that represents a syntax code: thus, @samp{w} for word -constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, -etc. To represent whitespace syntax, use either @samp{-} or a space -character. @xref{Syntax Class Table}, for a list of syntax codes and -the characters that stand for them. - -@item \S@var{code} -@cindex @samp{\S} in regexp -matches any character whose syntax is not @var{code}. - -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. - -@item \C@var{c} -matches any character whose category is not @var{c}. -@end table - - The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the -context. For all, the beginning and end of the accessible portion of -the buffer are treated as if they were the actual beginning and end of -the buffer. - -@table @samp -@item \` -@cindex @samp{\`} in regexp -matches the empty string, but only at the beginning -of the buffer or string being matched against. - -@item \' -@cindex @samp{\'} in regexp -matches the empty string, but only at the end of -the buffer or string being matched against. - -@item \= -@cindex @samp{\=} in regexp -matches the empty string, but only at point. -(This construct is not defined when matching against a string.) - -@item \b -@cindex @samp{\b} in regexp -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer (or string) -regardless of what text appears next to it. - -@item \B -@cindex @samp{\B} in regexp -matches the empty string, but @emph{not} at the beginning or -end of a word, nor at the beginning or end of the buffer (or string). - -@item \< -@cindex @samp{\<} in regexp -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer (or string) only if a -word-constituent character follows. - -@item \> -@cindex @samp{\>} in regexp -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer (or string) only if the contents end -with a word-constituent character. - -@item \_< -@cindex @samp{\_<} in regexp -matches the empty string, but only at the beginning of a symbol. A -symbol is a sequence of one or more word or symbol constituent -characters. @samp{\_<} matches at the beginning of the buffer (or -string) only if a symbol-constituent character follows. - -@item \_> -@cindex @samp{\_>} in regexp -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer (or string) only if the contents end -with a symbol-constituent character. -@end table - -@kindex invalid-regexp - Not every string is a valid regular expression. For example, a string -that ends inside a character alternative without terminating @samp{]} -is invalid, and so is a string that ends with a single @samp{\}. If -an invalid regular expression is passed to any of the search functions, -an @code{invalid-regexp} error is signaled. - -@node Regexp Example -@comment node-name, next, previous, up -@subsection Complex Regexp Example - - Here is a complicated regexp which was formerly used by Emacs to -recognize the end of a sentence together with any whitespace that -follows. (Nowadays Emacs uses a similar but more complex default -regexp constructed by the function @code{sentence-end}. -@xref{Standard Regexps}.) - - First, we show the regexp as a string in Lisp syntax to distinguish -spaces from tab characters. The string constant begins and ends with a -double-quote. @samp{\"} stands for a double-quote as part of the -string, @samp{\\} for a backslash as part of the string, @samp{\t} for a -tab and @samp{\n} for a newline. - -@example -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" -@end example - -@noindent -In contrast, if you evaluate this string, you will see the following: - -@example -@group -"[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*" - @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[ -]*" -@end group -@end example - -@noindent -In this output, tab and newline appear as themselves. - - This regular expression contains four parts in succession and can be -deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is a character alternative that matches -any one of three characters: period, question mark, and exclamation -mark. The match must begin with one of these three characters. (This -is one point where the new default regexp used by Emacs differs from -the old. The new value also allows some non-@acronym{ASCII} -characters that end a sentence without any following whitespace.) - -@item []\"')@}]* -The second part of the pattern matches any closing braces and quotation -marks, zero or more of them, that may follow the period, question mark -or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in -a string. The @samp{*} at the end indicates that the immediately -preceding regular expression (a character alternative, in this case) may be -repeated zero or more times. - -@item \\($\\|@ $\\|\t\\|@ @ \\) -The third part of the pattern matches the whitespace that follows the -end of a sentence: the end of a line (optionally with a space), or a -tab, or two spaces. The double backslashes mark the parentheses and -vertical bars as regular expression syntax; the parentheses delimit a -group and the vertical bars separate alternatives. The dollar sign is -used to match the end of a line. - -@item [ \t\n]* -Finally, the last part of the pattern matches any additional whitespace -beyond the minimum needed to end a sentence. -@end table - -@node Regexp Functions -@subsection Regular Expression Functions - - These functions operate on regular expressions. - -@defun regexp-quote string -This function returns a regular expression whose only exact match is -@var{string}. Using this regular expression in @code{looking-at} will -succeed only if the next characters in the buffer are @var{string}; -using it in a search function will succeed if the text being searched -contains @var{string}. - -This allows you to request an exact string match or search when calling -a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @var{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@defun regexp-opt strings &optional paren -This function returns an efficient regular expression that will match -any of the strings in the list @var{strings}. This is useful when you -need to make matching or searching as fast as possible---for example, -for Font Lock mode. - -If the optional argument @var{paren} is non-@code{nil}, then the -returned regular expression is always enclosed by at least one -parentheses-grouping construct. If @var{paren} is @code{words}, then -that construct is additionally surrounded by @samp{\<} and @samp{\>}. - -This simplified definition of @code{regexp-opt} produces a -regular expression which is equivalent to the actual value -(but not as efficient): - -@example -(defun regexp-opt (strings paren) - (let ((open-paren (if paren "\\(" "")) - (close-paren (if paren "\\)" ""))) - (concat open-paren - (mapconcat 'regexp-quote strings "\\|") - close-paren))) -@end example -@end defun - -@defun regexp-opt-depth regexp -This function returns the total number of grouping constructs -(parenthesized expressions) in @var{regexp}. This does not include -shy groups (@pxref{Regexp Backslash}). -@end defun - -@node Regexp Search -@section Regular Expression Searching -@cindex regular expression searching -@cindex regexp searching -@cindex searching for regexp - - In GNU Emacs, you can search for the next match for a regular -expression either incrementally or not. For incremental search -commands, see @ref{Regexp Search, , Regular Expression Search, emacs, -The GNU Emacs Manual}. Here we describe only the search functions -useful in programs. The principal one is @code{re-search-forward}. - - These search functions convert the regular expression to multibyte if -the buffer is multibyte; they convert the regular expression to unibyte -if the buffer is unibyte. @xref{Text Representations}. - -@deffn Command re-search-forward regexp &optional limit noerror repeat -This function searches forward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}. The -function skips over any amount of text that is not matched by -@var{regexp}, and leaves point at the end of the first match found. -It returns the new value of point. - -If @var{limit} is non-@code{nil}, it must be a position in the current -buffer. It specifies the upper bound to the search. No match -extending after that position is accepted. - -If @var{repeat} is supplied, it must be a positive number; the search -is repeated that many times; each repetition starts at the end of the -previous match. If all these successive searches succeed, the search -succeeds, moving point and returning its new value. Otherwise the -search fails. What @code{re-search-forward} does when the search -fails depends on the value of @var{noerror}: - -@table @asis -@item @code{nil} -Signal a @code{search-failed} error. -@item @code{t} -Do nothing and return @code{nil}. -@item anything else -Move point to @var{limit} (or the end of the accessible portion of the -buffer) and return @code{nil}. -@end table - -In the following example, point is initially before the @samp{T}. -Evaluating the search call moves point to the end of that line (between -the @samp{t} of @samp{hat} and the newline). - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(re-search-forward "[a-z]+" nil t 5) - @result{} 27 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command re-search-backward regexp &optional limit noerror repeat -This function searches backward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}, leaving -point at the beginning of the first text found. - -This function is analogous to @code{re-search-forward}, but they are not -simple mirror images. @code{re-search-forward} finds the match whose -beginning is as close as possible to the starting point. If -@code{re-search-backward} were a perfect mirror image, it would find the -match whose end is as close as possible. However, in fact it finds the -match whose beginning is as close as possible (and yet ends before the -starting point). The reason for this is that matching a regular -expression at a given spot always works from beginning to end, and -starts at a specified beginning position. - -A true mirror-image of @code{re-search-forward} would require a special -feature for matching regular expressions from end to beginning. It's -not worth the trouble of implementing that. -@end deffn - -@defun string-match regexp string &optional start -This function returns the index of the start of the first match for -the regular expression @var{regexp} in @var{string}, or @code{nil} if -there is no match. If @var{start} is non-@code{nil}, the search starts -at that index in @var{string}. - -For example, - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly.") - @result{} 4 -@end group -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group -@end example - -@noindent -The index of the first character of the -string is 0, the index of the second character is 1, and so on. - -After this function returns, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group - -@group -(match-end 0) - @result{} 32 -@end group -@end example -@end defun - -@defun string-match-p regexp string &optional start -This predicate function does what @code{string-match} does, but it -avoids modifying the match data. -@end defun - -@defun looking-at regexp -This function determines whether the text in the current buffer directly -following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can -succeed only starting with the first character following point. The -result is @code{t} if so, @code{nil} otherwise. - -This function does not move point, but it updates the match data, which -you can access using @code{match-beginning} and @code{match-end}. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. - -In this example, point is located directly before the @samp{T}. If it -were anywhere else, the result would be @code{nil}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-at "The cat in the hat$") - @result{} t -@end group -@end example -@end defun - -@defun looking-back regexp &optional limit greedy -This function returns @code{t} if @var{regexp} matches text before -point, ending at point, and @code{nil} otherwise. - -Because regular expression matching works only going forward, this is -implemented by searching backwards from point for a match that ends at -point. That can be quite slow if it has to search a long distance. -You can bound the time required by specifying @var{limit}, which says -not to search before @var{limit}. In this case, the match that is -found must begin at or after @var{limit}. - -If @var{greedy} is non-@code{nil}, this function extends the match -backwards as far as possible, stopping when a single additional -previous character cannot be part of a match for regexp. When the -match is extended, its starting position is allowed to occur before -@var{limit}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-back "read \"" 3) - @result{} t -(looking-back "read \"" 4) - @result{} nil -@end group -@end example -@end defun - -@defun looking-at-p regexp -This predicate function works like @code{looking-at}, but without -updating the match data. -@end defun - -@defvar search-spaces-regexp -If this variable is non-@code{nil}, it should be a regular expression -that says how to search for whitespace. In that case, any group of -spaces in a regular expression being searched for stands for use of -this regular expression. However, spaces inside of constructs such as -@samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by -@code{search-spaces-regexp}. - -Since this variable affects all regular expression search and match -constructs, you should bind it temporarily for as small as possible -a part of the code. -@end defvar - -@node POSIX Regexps -@section POSIX Regular Expression Searching - - The usual regular expression functions do backtracking when necessary -to handle the @samp{\|} and repetition constructs, but they continue -this only until they find @emph{some} match. Then they succeed and -report the first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX. This is much slower, so use these -functions only when you really need the longest match. - - The POSIX search and match functions do not properly support the -non-greedy repetition operators (@pxref{Regexp Special, non-greedy}). -This is because POSIX backtracking conflicts with the semantics of -non-greedy repetition. - -@deffn Command posix-search-forward regexp &optional limit noerror repeat -This is like @code{re-search-forward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@deffn Command posix-search-backward regexp &optional limit noerror repeat -This is like @code{re-search-backward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end deffn - -@defun posix-looking-at regexp -This is like @code{looking-at} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-string-match regexp string &optional start -This is like @code{string-match} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@node Match Data -@section The Match Data -@cindex match data - - Emacs keeps track of the start and end positions of the segments of -text found during a search; this is called the @dfn{match data}. -Thanks to the match data, you can search for a complex pattern, such -as a date in a mail message, and then extract parts of the match under -control of the pattern. - - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. - -@menu -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. -@end menu - -@node Replacing Match -@subsection Replacing the Text that Matched -@cindex replace matched text - - This function replaces all or part of the text matched by the last -search. It works by means of the match data. - -@cindex case in replacements -@defun replace-match replacement &optional fixedcase literal string subexp -This function replaces the text in the buffer (or in @var{string}) that -was matched by the last search. It replaces that text with -@var{replacement}. - -If you did the last search in a buffer, you should specify @code{nil} -for @var{string} and make sure that the current buffer when you call -@code{replace-match} is the one in which you did the searching or -matching. Then @code{replace-match} does the replacement by editing -the buffer; it leaves point at the end of the replacement text, and -returns @code{t}. - -If you did the search in a string, pass the same string as @var{string}. -Then @code{replace-match} does the replacement by constructing and -returning a new string. - -If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses -the replacement text without case conversion; otherwise, it converts -the replacement text depending upon the capitalization of the text to -be replaced. If the original text is all upper case, this converts -the replacement text to upper case. If all words of the original text -are capitalized, this capitalizes all the words of the replacement -text. If all the words are one-letter and they are all upper case, -they are treated as capitalized words rather than all-upper-case -words. - -If @var{literal} is non-@code{nil}, then @var{replacement} is inserted -exactly as it is, the only alterations being case changes as needed. -If it is @code{nil} (the default), then the character @samp{\} is treated -specially. If a @samp{\} appears in @var{replacement}, then it must be -part of one of the following sequences: - -@table @asis -@item @samp{\&} -@cindex @samp{&} in replacement -@samp{\&} stands for the entire text being replaced. - -@item @samp{\@var{n}} -@cindex @samp{\@var{n}} in replacement -@samp{\@var{n}}, where @var{n} is a digit, stands for the text that -matched the @var{n}th subexpression in the original regexp. -Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. -If the @var{n}th subexpression never matched, an empty string is substituted. - -@item @samp{\\} -@cindex @samp{\} in replacement -@samp{\\} stands for a single @samp{\} in the replacement text. -@end table - -These substitutions occur after case conversion, if any, -so the strings they substitute are never case-converted. - -If @var{subexp} is non-@code{nil}, that says to replace just -subexpression number @var{subexp} of the regexp that was matched, not -the entire match. For example, after matching @samp{foo \(ba*r\)}, -calling @code{replace-match} with 1 as @var{subexp} means to replace -just the text that matched @samp{\(ba*r\)}. -@end defun - -@defun match-substitute-replacement replacement &optional fixedcase literal string subexp -This function returns the text that would be inserted into the buffer -by @code{replace-match}, but without modifying the buffer. It is -useful if you want to present the user with actual replacement result, -with constructs like @samp{\@var{n}} or @samp{\&} substituted with -matched groups. Arguments @var{replacement} and optional -@var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the -same meaning as for @code{replace-match}. -@end defun - -@node Simple Match Data -@subsection Simple Match Data Access - - This section explains how to use the match data to find out what was -matched by the last search or match operation, if it succeeded. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The @var{count} -argument in the functions below specifies which. If @var{count} is -zero, you are asking about the entire match. If @var{count} is -positive, it specifies which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The -@var{count}th subexpression is found by counting occurrences of -@samp{\(} from the beginning of the whole regular expression. The first -subexpression is numbered 1, the second 2, and so on. Only regular -expressions can have subexpressions---after a simple string search, the -only information available is about the entire match. - - Every successful search sets the match data. Therefore, you should -query the match data immediately after searching, before calling any -other function that might perform another search. Alternatively, you -may save and restore the match data (@pxref{Saving Match Data}) around -the call to functions that could perform another search. - - A search which fails may or may not alter the match data. In the -past, a failing search did not do this, but we may change it in the -future. So don't try to rely on the value of the match data after -a failing search. - -@defun match-string count &optional in-string -This function returns, as a string, the text matched in the last search -or match operation. It returns the entire text if @var{count} is zero, -or just the portion corresponding to the @var{count}th parenthetical -subexpression, if @var{count} is positive. - -If the last such operation was done against a string with -@code{string-match}, then you should pass the same string as the -argument @var{in-string}. After a buffer search or match, -you should omit @var{in-string} or pass @code{nil} for it; but you -should make sure that the current buffer when you call -@code{match-string} is the one in which you did the searching or -matching. - -The value is @code{nil} if @var{count} is out of range, or for a -subexpression inside a @samp{\|} alternative that wasn't used or a -repetition that repeated zero times. -@end defun - -@defun match-string-no-properties count &optional in-string -This function is like @code{match-string} except that the result -has no text properties. -@end defun - -@defun match-beginning count -This function returns the position of the start of text matched by the -last regular expression searched for, or a subexpression of it. - -If @var{count} is zero, then the value is the position of the start of -the entire match. Otherwise, @var{count} specifies a subexpression in -the regular expression, and the value of the function is the starting -position of the match for that subexpression. - -The value is @code{nil} for a subexpression inside a @samp{\|} -alternative that wasn't used or a repetition that repeated zero times. -@end defun - -@defun match-end count -This function is like @code{match-beginning} except that it returns the -position of the end of the match, rather than the position of the -beginning. -@end defun - - Here is an example of using the match data, with a comment showing the -positions within the text: - -@example -@group -(string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - @result{} 4 -@end group - -@group -(match-string 0 "The quick fox jumped quickly.") - @result{} "quick" -(match-string 1 "The quick fox jumped quickly.") - @result{} "qu" -(match-string 2 "The quick fox jumped quickly.") - @result{} "ick" -@end group - -@group -(match-beginning 1) ; @r{The beginning of the match} - @result{} 4 ; @r{with @samp{qu} is at index 4.} -@end group - -@group -(match-beginning 2) ; @r{The beginning of the match} - @result{} 6 ; @r{with @samp{ick} is at index 6.} -@end group - -@group -(match-end 1) ; @r{The end of the match} - @result{} 6 ; @r{with @samp{qu} is at index 6.} - -(match-end 2) ; @r{The end of the match} - @result{} 9 ; @r{with @samp{ick} is at index 9.} -@end group -@end example - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -@samp{in}. The beginning of the entire match is at the 9th character of -the buffer (@samp{T}), and the beginning of the match for the first -subexpression is at the 13th character (@samp{c}). - -@example -@group -(list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - @result{} (17 9 13) -@end group - -@group ----------- Buffer: foo ---------- -I read "The cat @point{}in the hat comes back" twice. - ^ ^ - 9 13 ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) - -@node Entire Match Data -@subsection Accessing the Entire Match Data - - The functions @code{match-data} and @code{set-match-data} read or -write the entire match data, all at once. - -@defun match-data &optional integers reuse reseat -This function returns a list of positions (markers or integers) that -record all the information on what text the last search matched. -Element zero is the position of the beginning of the match for the -whole expression; element one is the position of the end of the match -for the expression. The next two elements are the positions of the -beginning and end of the match for the first subexpression, and so on. -In general, element -@ifnottex -number 2@var{n} -@end ifnottex -@tex -number {\mathsurround=0pt $2n$} -@end tex -corresponds to @code{(match-beginning @var{n})}; and -element -@ifnottex -number 2@var{n} + 1 -@end ifnottex -@tex -number {\mathsurround=0pt $2n+1$} -@end tex -corresponds to @code{(match-end @var{n})}. - -Normally all the elements are markers or @code{nil}, but if -@var{integers} is non-@code{nil}, that means to use integers instead -of markers. (In that case, the buffer itself is appended as an -additional element at the end of the list, to facilitate complete -restoration of the match data.) If the last match was done on a -string with @code{string-match}, then integers are always used, -since markers can't point into a string. - -If @var{reuse} is non-@code{nil}, it should be a list. In that case, -@code{match-data} stores the match data in @var{reuse}. That is, -@var{reuse} is destructively modified. @var{reuse} does not need to -have the right length. If it is not long enough to contain the match -data, it is extended. If it is too long, the length of @var{reuse} -stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to reduce the need for -garbage collection. - -If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list -are reseated to point to nowhere. - -As always, there must be no possibility of intervening searches between -the call to a search function and the call to @code{match-data} that is -intended to access the match data for that search. - -@example -@group -(match-data) - @result{} (# - # - # - #) -@end group -@end example -@end defun - -@defun set-match-data match-list &optional reseat -This function sets the match data from the elements of @var{match-list}, -which should be a list that was the value of a previous call to -@code{match-data}. (More precisely, anything that has the same format -will work.) - -If @var{match-list} refers to a buffer that doesn't exist, you don't get -an error; that sets the match data in a meaningless but harmless way. - -If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list -are reseated to point to nowhere. - -@findex store-match-data -@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. -@end defun - -@node Saving Match Data -@subsection Saving and Restoring the Match Data - - When you call a function that may do a search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - -@example -@group -(re-search-forward "The \\(cat \\)") - @result{} 48 -(foo) ; @r{Perhaps @code{foo} does} - ; @r{more searching.} -(match-end 0) - @result{} 61 ; @r{Unexpected result---not 48!} -@end group -@end example - - You can save and restore the match data with @code{save-match-data}: - -@defmac save-match-data body@dots{} -This macro executes @var{body}, saving and restoring the match -data around it. The return value is the value of the last form in -@var{body}. -@end defmac - - You could use @code{set-match-data} together with @code{match-data} to -imitate the effect of the special form @code{save-match-data}. Here is -how: - -@example -@group -(let ((data (match-data))) - (unwind-protect - @dots{} ; @r{Ok to change the original match data.} - (set-match-data data))) -@end group -@end example - - Emacs automatically saves and restores the match data when it runs -process filter functions (@pxref{Filter Functions}) and process -sentinels (@pxref{Sentinels}). - -@ignore - Here is a function which restores the match data provided the buffer -associated with it still exists. - -@smallexample -@group -(defun restore-match-data (data) -@c It is incorrect to split the first line of a doc string. -@c If there's a problem here, it should be solved in some other way. - "Restore the match data DATA unless the buffer is missing." - (catch 'foo - (let ((d data)) -@end group - (while d - (and (car d) - (null (marker-buffer (car d))) -@group - ;; @file{match-data} @r{buffer is deleted.} - (throw 'foo nil)) - (setq d (cdr d))) - (set-match-data data)))) -@end group -@end smallexample -@end ignore - -@node Search and Replace -@section Search and Replace -@cindex replacement after search -@cindex searching and replacing - - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: - -@example -(while (re-search-forward "foo[ \t]+bar" nil t) - (replace-match "foobar")) -@end example - -@noindent -@xref{Replacing Match,, Replacing the Text that Matched}, for a -description of @code{replace-match}. - - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides a function to do -this. - -@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start -This function copies @var{string} and searches it for matches for -@var{regexp}, and replaces them with @var{rep}. It returns the -modified copy. If @var{start} is non-@code{nil}, the search for -matches starts at that index in @var{string}, so matches starting -before that index are not changed. - -This function uses @code{replace-match} to do the replacement, and it -passes the optional arguments @var{fixedcase}, @var{literal} and -@var{subexp} along to @code{replace-match}. - -Instead of a string, @var{rep} can be a function. In that case, -@code{replace-regexp-in-string} calls @var{rep} for each match, -passing the text of the match as its sole argument. It collects the -value @var{rep} returns and passes that to @code{replace-match} as the -replacement string. The match-data at this point are the result -of matching @var{regexp} against a substring of @var{string}. -@end defun - - If you want to write a command along the lines of @code{query-replace}, -you can use @code{perform-replace} to do the work. - -@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end -This function is the guts of @code{query-replace} and related -commands. It searches for occurrences of @var{from-string} in the -text between positions @var{start} and @var{end} and replaces some or -all of them. If @var{start} is @code{nil} (or omitted), point is used -instead, and the end of the buffer's accessible portion is used for -@var{end}. - -If @var{query-flag} is @code{nil}, it replaces all -occurrences; otherwise, it asks the user what to do about each one. - -If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is -considered a regular expression; otherwise, it must match literally. If -@var{delimited-flag} is non-@code{nil}, then only replacements -surrounded by word boundaries are considered. - -The argument @var{replacements} specifies what to replace occurrences -with. If it is a string, that string is used. It can also be a list of -strings, to be used in cyclic order. - -If @var{replacements} is a cons cell, @w{@code{(@var{function} -. @var{data})}}, this means to call @var{function} after each match to -get the replacement text. This function is called with two arguments: -@var{data}, and the number of replacements already made. - -If @var{repeat-count} is non-@code{nil}, it should be an integer. Then -it specifies how many times to use each of the strings in the -@var{replacements} list before advancing cyclically to the next one. - -If @var{from-string} contains upper-case letters, then -@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and -it uses the @code{replacements} without altering the case of them. - -Normally, the keymap @code{query-replace-map} defines the possible -user responses for queries. The argument @var{map}, if -non-@code{nil}, specifies a keymap to use instead of -@code{query-replace-map}. - -This function uses one of two functions to search for the next -occurrence of @var{from-string}. These functions are specified by the -values of two variables: @code{replace-re-search-function} and -@code{replace-search-function}. The former is called when the -argument @var{regexp-flag} is non-@code{nil}, the latter when it is -@code{nil}. -@end defun - -@defvar query-replace-map -This variable holds a special keymap that defines the valid user -responses for @code{perform-replace} and the commands that use it, as -well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual -in two ways: - -@itemize @bullet -@item -The ``key bindings'' are not commands, just symbols that are meaningful -to the functions that use this map. - -@item -Prefix keys are not supported; each key binding must be for a -single-event key sequence. This is because the functions don't use -@code{read-key-sequence} to get the input; instead, they read a single -event and look it up ``by hand.'' -@end itemize -@end defvar - -Here are the meaningful ``bindings'' for @code{query-replace-map}. -Several of them are meaningful only for @code{query-replace} and -friends. - -@table @code -@item act -Do take the action being considered---in other words, ``yes.'' - -@item skip -Do not take action for this question---in other words, ``no.'' - -@item exit -Answer this question ``no,'' and give up on the entire series of -questions, assuming that the answers will be ``no.'' - -@item act-and-exit -Answer this question ``yes,'' and give up on the entire series of -questions, assuming that subsequent answers will be ``no.'' - -@item act-and-show -Answer this question ``yes,'' but show the results---don't advance yet -to the next question. - -@item automatic -Answer this question and all subsequent questions in the series with -``yes,'' without further user interaction. - -@item backup -Move back to the previous place that a question was asked about. - -@item edit -Enter a recursive edit to deal with this question---instead of any -other action that would normally be taken. - -@item delete-and-edit -Delete the text being considered, then enter a recursive edit to replace -it. - -@item recenter -Redisplay and center the window, then ask the same question again. - -@item quit -Perform a quit right away. Only @code{y-or-n-p} and related functions -use this answer. - -@item help -Display some help, then ask again. -@end table - -@defvar multi-query-replace-map -This variable holds a keymap that extends @code{query-replace-map} by -providing additional keybindings that are useful in multi-buffer -replacements. -@end defvar - -@defvar replace-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next string to replace. Its default value is -@code{search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{search-forward} -(@pxref{String Search}). -@end defvar - -@defvar replace-re-search-function -This variable specifies a function that @code{perform-replace} calls -to search for the next regexp to replace. Its default value is -@code{re-search-forward}. Any other value should name a function of 3 -arguments: the first 3 arguments of @code{re-search-forward} -(@pxref{Regexp Search}). -@end defvar - -@node Standard Regexps -@section Standard Regular Expressions Used in Editing -@cindex regexps used standardly in editing -@cindex standard regexps used in editing - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - -@defopt page-delimiter -This is the regular expression describing line-beginnings that separate -pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or -@code{"^\C-l"}); this matches a line that starts with a formfeed -character. -@end defopt - - The following two regular expressions should @emph{not} assume the -match always starts at the beginning of a line; they should not use -@samp{^} to anchor the match. Most often, the paragraph commands do -check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a nonzero left margin, -they accept matches that start after the left margin. In that case, a -@samp{^} would be incorrect. However, a @samp{^} is harmless in modes -where a left margin is never used. - -@defopt paragraph-separate -This is the regular expression for recognizing the beginning of a line -that separates paragraphs. (If you change this, you may have to -change @code{paragraph-start} also.) The default value is -@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of -spaces, tabs, and form feeds (after its left margin). -@end defopt - -@defopt paragraph-start -This is the regular expression for recognizing the beginning of a line -that starts @emph{or} separates paragraphs. The default value is -@w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only -whitespace or starting with a form feed (after its left margin). -@end defopt - -@defopt sentence-end -If non-@code{nil}, the value should be a regular expression describing -the end of a sentence, including the whitespace following the -sentence. (All paragraph boundaries also end sentences, regardless.) - -If the value is @code{nil}, the default, then the function -@code{sentence-end} has to construct the regexp. That is why you -should always call the function @code{sentence-end} to obtain the -regexp to be used to recognize the end of a sentence. -@end defopt - -@defun sentence-end -This function returns the value of the variable @code{sentence-end}, -if non-@code{nil}. Otherwise it returns a default value based on the -values of the variables @code{sentence-end-double-space} -(@pxref{Definition of sentence-end-double-space}), -@code{sentence-end-without-period} and -@code{sentence-end-without-space}. -@end defun - -@ignore - arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f -@end ignore diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi deleted file mode 100644 index 0827ff04152..00000000000 --- a/doc/lispref/sequences.texi +++ /dev/null @@ -1,734 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/sequences -@node Sequences Arrays Vectors, Hash Tables, Lists, Top -@chapter Sequences, Arrays, and Vectors -@cindex sequence - - Recall that the @dfn{sequence} type is the union of two other Lisp -types: lists and arrays. In other words, any list is a sequence, and -any array is a sequence. The common property that all sequences have is -that each is an ordered collection of elements. - - An @dfn{array} is a fixed-length object with a slot for each of its -elements. All the elements are accessible in constant time. The four -types of arrays are strings, vectors, char-tables and bool-vectors. - - A list is a sequence of elements, but it is not a single primitive -object; it is made of cons cells, one cell per element. Finding the -@var{n}th element requires looking through @var{n} cons cells, so -elements farther from the beginning of the list take longer to access. -But it is possible to add elements to the list, or remove elements. - - The following diagram shows the relationship between these types: - -@example -@group - _____________________________________________ - | | - | Sequence | - | ______ ________________________________ | - | | | | | | - | | List | | Array | | - | | | | ________ ________ | | - | |______| | | | | | | | - | | | Vector | | String | | | - | | |________| |________| | | - | | ____________ _____________ | | - | | | | | | | | - | | | Char-table | | Bool-vector | | | - | | |____________| |_____________| | | - | |________________________________| | - |_____________________________________________| -@end group -@end example - -@menu -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. -@end menu - -@node Sequence Functions -@section Sequences - - In Emacs Lisp, a @dfn{sequence} is either a list or an array. The -common property of all sequences is that they are ordered collections of -elements. This section describes functions that accept any kind of -sequence. - -@defun sequencep object -Returns @code{t} if @var{object} is a list, vector, string, -bool-vector, or char-table, @code{nil} otherwise. -@end defun - -@defun length sequence -@cindex string length -@cindex list length -@cindex vector length -@cindex sequence length -@cindex char-table length -This function returns the number of elements in @var{sequence}. If -@var{sequence} is a dotted list, a @code{wrong-type-argument} error is -signaled. Circular lists may cause an infinite loop. For a -char-table, the value returned is always one more than the maximum -Emacs character code. - -@xref{Definition of safe-length}, for the related function @code{safe-length}. - -@example -@group -(length '(1 2 3)) - @result{} 3 -@end group -@group -(length ()) - @result{} 0 -@end group -@group -(length "foobar") - @result{} 6 -@end group -@group -(length [1 2 3]) - @result{} 3 -@end group -@group -(length (make-bool-vector 5 nil)) - @result{} 5 -@end group -@end example -@end defun - -@noindent -See also @code{string-bytes}, in @ref{Text Representations}. - -@defun elt sequence index -@cindex elements of sequences -This function returns the element of @var{sequence} indexed by -@var{index}. Legitimate values of @var{index} are integers ranging -from 0 up to one less than the length of @var{sequence}. If -@var{sequence} is a list, out-of-range values behave as for -@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values -trigger an @code{args-out-of-range} error. - -@example -@group -(elt [1 2 3 4] 2) - @result{} 3 -@end group -@group -(elt '(1 2 3 4) 2) - @result{} 3 -@end group -@group -;; @r{We use @code{string} to show clearly which character @code{elt} returns.} -(string (elt "1234" 2)) - @result{} "3" -@end group -@group -(elt [1 2 3 4] 4) - @error{} Args out of range: [1 2 3 4], 4 -@end group -@group -(elt [1 2 3 4] -1) - @error{} Args out of range: [1 2 3 4], -1 -@end group -@end example - -This function generalizes @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{Definition of nth}). -@end defun - -@defun copy-sequence sequence -@cindex copying sequences -Returns a copy of @var{sequence}. The copy is the same type of object -as the original sequence, and it has the same elements in the same order. - -Storing a new element into the copy does not affect the original -@var{sequence}, and vice versa. However, the elements of the new -sequence are not copies; they are identical (@code{eq}) to the elements -of the original. Therefore, changes made within these elements, as -found via the copied sequence, are also visible in the original -sequence. - -If the sequence is a string with text properties, the property list in -the copy is itself a copy, not shared with the original's property -list. However, the actual values of the properties are shared. -@xref{Text Properties}. - -This function does not work for dotted lists. Trying to copy a -circular list may cause an infinite loop. - -See also @code{append} in @ref{Building Lists}, @code{concat} in -@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions}, -for other ways to copy sequences. - -@example -@group -(setq bar '(1 2)) - @result{} (1 2) -@end group -@group -(setq x (vector 'foo bar)) - @result{} [foo (1 2)] -@end group -@group -(setq y (copy-sequence x)) - @result{} [foo (1 2)] -@end group - -@group -(eq x y) - @result{} nil -@end group -@group -(equal x y) - @result{} t -@end group -@group -(eq (elt x 1) (elt y 1)) - @result{} t -@end group - -@group -;; @r{Replacing an element of one sequence.} -(aset x 0 'quux) -x @result{} [quux (1 2)] -y @result{} [foo (1 2)] -@end group - -@group -;; @r{Modifying the inside of a shared element.} -(setcar (aref x 1) 69) -x @result{} [quux (69 2)] -y @result{} [foo (69 2)] -@end group -@end example -@end defun - -@node Arrays -@section Arrays -@cindex array - - An @dfn{array} object has slots that hold a number of other Lisp -objects, called the elements of the array. Any element of an array -may be accessed in constant time. In contrast, the time to access an -element of a list is proportional to the position of that element in -the list. - - Emacs defines four types of array, all one-dimensional: -@dfn{strings} (@pxref{String Type}), @dfn{vectors} (@pxref{Vector -Type}), @dfn{bool-vectors} (@pxref{Bool-Vector Type}), and -@dfn{char-tables} (@pxref{Char-Table Type}). Vectors and char-tables -can hold elements of any type, but strings can only hold characters, -and bool-vectors can only hold @code{t} and @code{nil}. - - All four kinds of array share these characteristics: - -@itemize @bullet -@item -The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. - -@item -The length of the array is fixed once you create it; you cannot -change the length of an existing array. - -@item -For purposes of evaluation, the array is a constant---in other words, -it evaluates to itself. - -@item -The elements of an array may be referenced or changed with the functions -@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). -@end itemize - - When you create an array, other than a char-table, you must specify -its length. You cannot specify the length of a char-table, because that -is determined by the range of character codes. - - In principle, if you want an array of text characters, you could use -either a string or a vector. In practice, we always choose strings for -such applications, for four reasons: - -@itemize @bullet -@item -They occupy one-fourth the space of a vector of the same elements. - -@item -Strings are printed in a way that shows the contents more clearly -as text. - -@item -Strings can hold text properties. @xref{Text Properties}. - -@item -Many of the specialized editing and I/O facilities of Emacs accept only -strings. For example, you cannot insert a vector of characters into a -buffer the way you can insert a string. @xref{Strings and Characters}. -@end itemize - - By contrast, for an array of keyboard input characters (such as a key -sequence), a vector may be necessary, because many keyboard input -characters are outside the range that will fit in a string. @xref{Key -Sequence Input}. - -@node Array Functions -@section Functions that Operate on Arrays - - In this section, we describe the functions that accept all types of -arrays. - -@defun arrayp object -This function returns @code{t} if @var{object} is an array (i.e., a -vector, a string, a bool-vector or a char-table). - -@example -@group -(arrayp [a]) - @result{} t -(arrayp "asdf") - @result{} t -(arrayp (syntax-table)) ;; @r{A char-table.} - @result{} t -@end group -@end example -@end defun - -@defun aref array index -@cindex array elements -This function returns the @var{index}th element of @var{array}. The -first element is at index zero. - -@example -@group -(setq primes [2 3 5 7 11 13]) - @result{} [2 3 5 7 11 13] -(aref primes 4) - @result{} 11 -@end group -@group -(aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.} -@end group -@end example - -See also the function @code{elt}, in @ref{Sequence Functions}. -@end defun - -@defun aset array index object -This function sets the @var{index}th element of @var{array} to be -@var{object}. It returns @var{object}. - -@example -@group -(setq w [foo bar baz]) - @result{} [foo bar baz] -(aset w 0 'fu) - @result{} fu -w - @result{} [fu bar baz] -@end group - -@group -(setq x "asdfasfd") - @result{} "asdfasfd" -(aset x 3 ?Z) - @result{} 90 -x - @result{} "asdZasfd" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. The function converts a -unibyte string to multibyte if necessary to insert a character. -@end defun - -@defun fillarray array object -This function fills the array @var{array} with @var{object}, so that -each element of @var{array} is @var{object}. It returns @var{array}. - -@example -@group -(setq a [a b c d e f g]) - @result{} [a b c d e f g] -(fillarray a 0) - @result{} [0 0 0 0 0 0 0] -a - @result{} [0 0 0 0 0 0 0] -@end group -@group -(setq s "When in the course") - @result{} "When in the course" -(fillarray s ?-) - @result{} "------------------" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -The general sequence functions @code{copy-sequence} and @code{length} -are often useful for objects known to be arrays. @xref{Sequence Functions}. - -@node Vectors -@section Vectors -@cindex vector (type) - - A @dfn{vector} is a general-purpose array whose elements can be any -Lisp objects. (By contrast, the elements of a string can only be -characters. @xref{Strings and Characters}.) Vectors are used in -Emacs for many purposes: as key sequences (@pxref{Key Sequences}), as -symbol-lookup tables (@pxref{Creating Symbols}), as part of the -representation of a byte-compiled function (@pxref{Byte Compilation}), -and more. - - In Emacs Lisp, the indices of the elements of a vector start from zero -and count up from there. - - Vectors are printed with square brackets surrounding the elements. -Thus, a vector whose elements are the symbols @code{a}, @code{b} and -@code{a} is printed as @code{[a b a]}. You can write vectors in the -same way in Lisp input. - - A vector, like a string or a number, is considered a constant for -evaluation: the result of evaluating it is the same vector. This does -not evaluate or even examine the elements of the vector. -@xref{Self-Evaluating Forms}. - - Here are examples illustrating these principles: - -@example -@group -(setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(eval avector) - @result{} [1 two (quote (three)) "four" [five]] -(eq avector (eval avector)) - @result{} t -@end group -@end example - -@node Vector Functions -@section Functions for Vectors - - Here are some functions that relate to vectors: - -@defun vectorp object -This function returns @code{t} if @var{object} is a vector. - -@example -@group -(vectorp [a]) - @result{} t -(vectorp "asdf") - @result{} nil -@end group -@end example -@end defun - -@defun vector &rest objects -This function creates and returns a vector whose elements are the -arguments, @var{objects}. - -@example -@group -(vector 'foo 23 [bar baz] "rats") - @result{} [foo 23 [bar baz] "rats"] -(vector) - @result{} [] -@end group -@end example -@end defun - -@defun make-vector length object -This function returns a new vector consisting of @var{length} elements, -each initialized to @var{object}. - -@example -@group -(setq sleepy (make-vector 9 'Z)) - @result{} [Z Z Z Z Z Z Z Z Z] -@end group -@end example -@end defun - -@defun vconcat &rest sequences -@cindex copying vectors -This function returns a new vector containing all the elements of -@var{sequences}. The arguments @var{sequences} may be true lists, -vectors, strings or bool-vectors. If no @var{sequences} are given, an -empty vector is returned. - -The value is a newly constructed vector that is not @code{eq} to any -existing vector. - -@example -@group -(setq a (vconcat '(A B C) '(D E F))) - @result{} [A B C D E F] -(eq a (vconcat a)) - @result{} nil -@end group -@group -(vconcat) - @result{} [] -(vconcat [A B C] "aa" '(foo (6 7))) - @result{} [A B C 97 97 foo (6 7)] -@end group -@end example - -The @code{vconcat} function also allows byte-code function objects as -arguments. This is a special feature to make it easy to access the entire -contents of a byte-code function object. @xref{Byte-Code Objects}. - -For other concatenation functions, see @code{mapconcat} in @ref{Mapping -Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} -in @ref{Building Lists}. -@end defun - - The @code{append} function also provides a way to convert a vector into a -list with the same elements: - -@example -@group -(setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(append avector nil) - @result{} (1 two (quote (three)) "four" [five]) -@end group -@end example - -@node Char-Tables -@section Char-Tables -@cindex char-tables -@cindex extra slots of char-table - - A char-table is much like a vector, except that it is indexed by -character codes. Any valid character code, without modifiers, can be -used as an index in a char-table. You can access a char-table's -elements with @code{aref} and @code{aset}, as with any array. In -addition, a char-table can have @dfn{extra slots} to hold additional -data not associated with particular character codes. Like vectors, -char-tables are constants when evaluated, and can hold elements of any -type. - -@cindex subtype of char-table - Each char-table has a @dfn{subtype}, a symbol, which serves two -purposes: - -@itemize @bullet -@item -The subtype provides an easy way to tell what the char-table is for. -For instance, display tables are char-tables with @code{display-table} -as the subtype, and syntax tables are char-tables with -@code{syntax-table} as the subtype. The subtype can be queried using -the function @code{char-table-subtype}, described below. - -@item -The subtype controls the number of @dfn{extra slots} in the -char-table. This number is specified by the subtype's -@code{char-table-extra-slots} symbol property, which should be an -integer between 0 and 10. If the subtype has no such symbol property, -the char-table has no extra slots. @xref{Property Lists}, for -information about symbol properties. -@end itemize - -@cindex parent of char-table - A char-table can have a @dfn{parent}, which is another char-table. If -it does, then whenever the char-table specifies @code{nil} for a -particular character @var{c}, it inherits the value specified in the -parent. In other words, @code{(aref @var{char-table} @var{c})} returns -the value from the parent of @var{char-table} if @var{char-table} itself -specifies @code{nil}. - -@cindex default value of char-table - A char-table can also have a @dfn{default value}. If so, then -@code{(aref @var{char-table} @var{c})} returns the default value -whenever the char-table does not specify any other non-@code{nil} value. - -@defun make-char-table subtype &optional init -Return a newly-created char-table, with subtype @var{subtype} (a -symbol). Each element is initialized to @var{init}, which defaults to -@code{nil}. You cannot alter the subtype of a char-table after the -char-table is created. - -There is no argument to specify the length of the char-table, because -all char-tables have room for any valid character code as an index. - -If @var{subtype} has the @code{char-table-extra-slots} symbol -property, that specifies the number of extra slots in the char-table. -This should be an integer between 0 and 10; otherwise, -@code{make-char-table} raises an error. If @var{subtype} has no -@code{char-table-extra-slots} symbol property (@pxref{Property -Lists}), the char-table has no extra slots. -@end defun - -@defun char-table-p object -This function returns @code{t} if @var{object} is a char-table, and -@code{nil} otherwise. -@end defun - -@defun char-table-subtype char-table -This function returns the subtype symbol of @var{char-table}. -@end defun - -There is no special function to access default values in a char-table. -To do that, use @code{char-table-range} (see below). - -@defun char-table-parent char-table -This function returns the parent of @var{char-table}. The parent is -always either @code{nil} or another char-table. -@end defun - -@defun set-char-table-parent char-table new-parent -This function sets the parent of @var{char-table} to @var{new-parent}. -@end defun - -@defun char-table-extra-slot char-table n -This function returns the contents of extra slot @var{n} of -@var{char-table}. The number of extra slots in a char-table is -determined by its subtype. -@end defun - -@defun set-char-table-extra-slot char-table n value -This function stores @var{value} in extra slot @var{n} of -@var{char-table}. -@end defun - - A char-table can specify an element value for a single character code; -it can also specify a value for an entire character set. - -@defun char-table-range char-table range -This returns the value specified in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun set-char-table-range char-table range value -This function sets the value in @var{char-table} for a range of -characters @var{range}. Here are the possibilities for @var{range}: - -@table @asis -@item @code{nil} -Refers to the default value. - -@item @code{t} -Refers to the whole range of character codes. - -@item @var{char} -Refers to the element for character @var{char} -(supposing @var{char} is a valid character code). - -@item @code{(@var{from} . @var{to})} -A cons cell refers to all the characters in the inclusive range -@samp{[@var{from}..@var{to}]}. -@end table -@end defun - -@defun map-char-table function char-table -This function calls its argument @var{function} for each element of -@var{char-table} that has a non-@code{nil} value. The call to -@var{function} is with two arguments, a key and a value. The key -is a possible @var{range} argument for @code{char-table-range}---either -a valid character or a cons cell @code{(@var{from} . @var{to})}, -specifying a range of characters that share the same value. The value is -what @code{(char-table-range @var{char-table} @var{key})} returns. - -Overall, the key-value pairs passed to @var{function} describe all the -values stored in @var{char-table}. - -The return value is always @code{nil}; to make calls to -@code{map-char-table} useful, @var{function} should have side effects. -For example, here is how to examine the elements of the syntax table: - -@example -(let (accumulator) - (map-char-table - #'(lambda (key value) - (setq accumulator - (cons (list - (if (consp key) - (list (car key) (cdr key)) - key) - value) - accumulator))) - (syntax-table)) - accumulator) -@result{} -(((2597602 4194303) (2)) ((2597523 2597601) (3)) - ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1)) - ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3))) -@end example -@end defun - -@node Bool-Vectors -@section Bool-vectors -@cindex Bool-vectors - - A bool-vector is much like a vector, except that it stores only the -values @code{t} and @code{nil}. If you try to store any non-@code{nil} -value into an element of the bool-vector, the effect is to store -@code{t} there. As with all arrays, bool-vector indices start from 0, -and the length cannot be changed once the bool-vector is created. -Bool-vectors are constants when evaluated. - - There are two special functions for working with bool-vectors; aside -from that, you manipulate them with same functions used for other kinds -of arrays. - -@defun make-bool-vector length initial -Return a new bool-vector of @var{length} elements, -each one initialized to @var{initial}. -@end defun - -@defun bool-vector-p object -This returns @code{t} if @var{object} is a bool-vector, -and @code{nil} otherwise. -@end defun - - Here is an example of creating, examining, and updating a -bool-vector. Note that the printed form represents up to 8 boolean -values as a single character. - -@example -(setq bv (make-bool-vector 5 t)) - @result{} #&5"^_" -(aref bv 1) - @result{} t -(aset bv 3 nil) - @result{} nil -bv - @result{} #&5"^W" -@end example - -@noindent -These results make sense because the binary codes for control-_ and -control-W are 11111 and 10111, respectively. - -@ignore - arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386 -@end ignore diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile deleted file mode 100644 index b373d00bebf..00000000000 --- a/doc/lispref/spellfile +++ /dev/null @@ -1,738 +0,0 @@ -ARPA -Abbrev -Acknowledgements -Alan -Arnold -Autoloading -BAppend -Backquote -Beeping -Beverly -Boyes -Brian -CL -CSWKg -Carl -Carroll -Chris -Cleanups -DEC -DStandard -Dan -Dired's -Disassembly -Duff -EMAC -EMACSLOADPATH -Eckelkamp -Edward -Eirik -Emacses -Eric -Erlebacher -Fcar -Fcdr -Fcons -Fcoordinates -Feval -Frazzle -Frederick -Fri -Gardiner -Gentlemen -HAL -HATTED -HS -HU -Hanchrow -Hartzell -Hess -Hewlett -IBM -ISBN -Impl -Interning -Ithought -J's -Jacobson -Jak -Joe -Jones -Jr -Jul -Keymaps -Kimmo -Kirman -Knighten -Korz -Krawitz -LTsHm -LaLiberte -LaTeX -Lammens -Local' -MAC -MONIES -MSS -Maclisp -Magill -Marick -Matthew -Minibuf -Misc -Miscellany -Mocklisp -Montanaro -Myers -NFS -Nathan -Nope -OS -OSITIONS -Oct -Ovwrt -PURESIZE -Packard -Qlistp -Qnil -RMAIL -Raul -Resizing -Robbins -Rockwell -SCO -SIGCONT -SIGHUP -SIGINT -SIGKILL -SIGQUIT -SIGTSTP -SLOAD -Scoordinates -Set' -Setcar -Setcdr -Shinichirou -Snarf -Sor -SourceFile -Stops' -Subprocess -Sugou -Sunview -Suominen -T's -TCP -ThXs -Tharp -Thu -Trost -UCB -UNEVALLED -UNGCPRO -UniPlus -UniSoft's -VMS -Vip -Void' -Warren -Welty -Wethought -Wilding -Worley -Wright -XDVI -XFASTINT -XINT -XWINDOW -Xs -Yo -Zuhn -aB -aa -aaa -abbrevname -abbrevs -abc -abcdefg -abcxyz -abd -above' -abracadabra -address' -after' -alist -alists -anchored' -and' -ar -aref -arg'th -argdecl -arith -arrayp -arrow' -asa -asdZasfd -asdf -asdfasfd -aset -assoc -assq -at' -aug -autoload -automatic' -automatically' -avector -bBuffer -bFrobnicate -ba -back' -bananana -barfoo -barx -bballs -before' -beforep -bfoo -bil -binding's -bish -bobp -bolp -bottommost -boundp -brief' -buf -buffer' -bufferp -buttercup -ca -caaaar -caaar -caddaar -cadr -callable -cbreak -ce -cell' -cells' -cf -chaprm -character' -childp -chistory -ck -column' -commandp -concat -cond -conses -consing -consp -constant' -contains' -continuable -convert' -copyleft -correct' -counterintuitive -cr -creatable -customie -deactivate -deactivated -deassigns -decrement' -deffnx -definition' -defmacro -defsubr -deletable -deletion' -delq -depiction -descendents -deselecting -destructive' -destructively' -diffs -ding -directory' -dired -dirname -disassembler -dland -docfile -docstring -doesnt -dont -down' -downcasing -downloadable -dribble -dup -ef -efg -electric' -elided -elt -enablement -endkeyfun -endrecfun -environment' -eobp -eof -eol -eolp -eq -eqlsign -erminal -erste -etags -eval -evalled -evals -evaluate' -excess' -exec -exitcode -expression' -extendible -extra' -fails' -fascist -fboundp -featurep -ff -fg -fi -file' -filespec -filesystems -fillarray -firstchar -firstonly -fixedcase -fixit -fixup -floatp -fmakunbound -fns -fo -fol -folded' -following' -fooba -foobaz -foox -for' -formfeed -forms' -forw -forwa -found' -frob -from' -front' -fset -fstab -ftp -fu -funtions -garbles -gc -gcpro -gd -getenv -getprv -gid -gnuemacs -gp -grep -gtr -halves' -hand' -hashes' -hd -hexadecimal -hf -hfil -hookvar -horsechestnut -hostname -hpux -hscroll -ibmapa -ick -id -idiom -ii -indrm -inode -input' -inputinput -inserting' -integerp -intermixed -ints -inturned -irreversibly -jum -keymapp -kill' -killed' -killp -kludge -kolstad -language' -lastchar -lcl -ledit -leif -lessp -level' -lewis -library' -link' -lisplib -listexp -loadable -loadst -loadup -logand -logior -lognot -logxor -long' -loop's -lru -lrwxrwxrwx -ls -lsh -m's -macroexpand -makunbound -malloc -mapatoms -mapconcat -mapvar -mark' -marker's -markerp -mathsurround -medit -memq -mh -mim -mini -minibuffer's -minibuffers -misalignment -misnamed -mode's -modename -modes' -mods -modtime -mqueue -msg -multicharacter -myfile -nCount -nXExpression -na -name's -natnump -nb -nbBuffer -nconc -newdef -newelt -newname -nextrecfun -nfsusr -ninett -nlines -nlinks -nlistp -noconfirm -nodigits -noerror -noforce -nomessage -nominees -nomsg -nonblank -nonconstant -nondestructive -nondirectory -nonidentical -noninteractive -noninteractively -nonletter -nonletters -nonlocally -nonoverlapping -nonprinting -nonselected -nonsequentially -nonvoid -nonwarranty -nonwritable -noop -noprint -norecord -normal' -noselect -nosuffix -nots -noundo -nr -nreverse -ns -nsRename -nth -nthcdr -num -number' -numberp -nums -obarray -obarrays -object' -oldbuf -olddef -oldname -oo -oops -op -or' -otl -out' -over' -overful -overfullrule -overstrike -overstriking -overstruck -p' -paren -part' -passwd -pe -ped -perverse -pid -plist -pnt -pointer' -pointm -pos -preallocate -predicale -preload -prepend -prepended -prepends -pretty' -prin -princ -print' -printenv -printer' -proc -process' -processp -programmer' -prolog -protect' -ps -psf -psychotherapy -pty -purecopy -qu -quux -rassq -reader' -readin -rebind -rec -rechecking -recursively' -recycler' -redo -redrawing -redraws -redump -reenabled -reexposed -reg -region' -reindent -reindents -reinitialization -reinitialize -reinitialized -reinstall -reinstalled -resize -resized -resizes -reversibly -reworded -rhetorical -right' -ring' -risky -rmailedit -rms -rplaca -rplacd -rtu -runnable -rw -rwxrwxrwx -sDescribe -sans -se -searching' -section' -seed' -sequence' -sequencep -setp -setplist -setprv -settable -setuid -sexp -sexps -shape' -shell's -sideline -special' -specpdl -st -stanford -startkeyfun -str -stringp -stty -subcategories -subcommands -subexp -subform -subforms -subjob -submap -subprocesses -subr -subr' -subroutine' -subrp -subrs -subwindows -sugar' -suid -supersession -suspension' -symbolp -symlink -syms -syntatic -tabname -temacs -temporarily' -tempvar -tenths -termcap -termcaps -terminfo -termscript -termtype -terpri -text' -textrm -textsl -texttt -than' -the' -tildes -time's -to' -towars -transportable -txt -types' -uid -unbind -unbinding -unbinds -unchanged' -unclutters -undefine -undefines -underfull -undo's -undodata -unevaluated' -unexec -unexpand -unhesitatingly -uninterned -unisoft -unpaired -unread -unreadable -unreading -unsaved -untyped -ununderline -up' -uptime -usecount -used' -user' -userlock -usg -val -varbind -varname -varref -vars -varset -vb -vconcat -vectorp -vfil -vi -vn -voidness -vrs -vt -window' -windowing -windowp -wrapped' -xSpecify -xcoord -xcssun -xemacs -xenix -xf -xfirst -xoff -xon -xx -xxxxx -xxxxxxxxx -xy -xyz -ycoord -yes' -zA -zap -zerop diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi deleted file mode 100644 index 1e7d53340c1..00000000000 --- a/doc/lispref/streams.texi +++ /dev/null @@ -1,843 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/streams -@node Read and Print, Minibuffers, Debugging, Top -@comment node-name, next, previous, up -@chapter Reading and Printing Lisp Objects - - @dfn{Printing} and @dfn{reading} are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in @ref{Lisp Data Types}. - - This chapter describes the Lisp functions for reading and printing. -It also describes @dfn{streams}, which specify where to get the text (if -reading) or where to put it (if printing). - -@menu -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing functions do. -@end menu - -@node Streams Intro -@section Introduction to Reading and Printing -@cindex Lisp reader -@cindex printing -@cindex reading - - @dfn{Reading} a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} -is the read syntax for a cons cell whose @sc{car} is @code{a} and whose -@sc{cdr} is the number 5. - - @dfn{Printing} a Lisp object means producing text that represents that -object---converting the object to its @dfn{printed representation} -(@pxref{Printed Representation}). Printing the cons cell described -above produces the text @samp{(a .@: 5)}. - - Reading and printing are more or less inverse operations: printing the -object that results from reading a given piece of text often produces -the same text, and reading the text that results from printing an object -usually produces a similar-looking object. For example, printing the -symbol @code{foo} produces the text @samp{foo}, and reading that text -returns the symbol @code{foo}. Printing a list whose elements are -@code{a} and @code{b} produces the text @samp{(a b)}, and reading that -text produces a list (but not the same list) with elements @code{a} -and @code{b}. - - However, these two operations are not precisely inverse to each other. -There are three kinds of exceptions: - -@itemize @bullet -@item -Printing can produce text that cannot be read. For example, buffers, -windows, frames, subprocesses and markers print as text that starts -with @samp{#}; if you try to read this text, you get an error. There is -no way to read those data types. - -@item -One object can have multiple textual representations. For example, -@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and -@samp{(a .@: (b))} represent the same list. Reading will accept any of -the alternatives, but printing must choose one of them. - -@item -Comments can appear at certain points in the middle of an object's -read sequence without affecting the result of reading it. -@end itemize - -@node Input Streams -@section Input Streams -@cindex stream (for reading) -@cindex input stream - - Most of the Lisp functions for reading text take an @dfn{input stream} -as an argument. The input stream specifies where or how to get the -characters of the text to be read. Here are the possible types of input -stream: - -@table @asis -@item @var{buffer} -@cindex buffer input stream -The input characters are read from @var{buffer}, starting with the -character directly after point. Point advances as characters are read. - -@item @var{marker} -@cindex marker input stream -The input characters are read from the buffer that @var{marker} is in, -starting with the character directly after the marker. The marker -position advances as characters are read. The value of point in the -buffer has no effect when the stream is a marker. - -@item @var{string} -@cindex string input stream -The input characters are taken from @var{string}, starting at the first -character in the string and using as many characters as required. - -@item @var{function} -@cindex function input stream -The input characters are generated by @var{function}, which must support -two kinds of calls: - -@itemize @bullet -@item -When it is called with no arguments, it should return the next character. - -@item -When it is called with one argument (always a character), @var{function} -should save the argument and arrange to return it on the next call. -This is called @dfn{unreading} the character; it happens when the Lisp -reader reads one character too many and wants to ``put it back where it -came from.'' In this case, it makes no difference what value -@var{function} returns. -@end itemize - -@item @code{t} -@cindex @code{t} input stream -@code{t} used as a stream means that the input is read from the -minibuffer. In fact, the minibuffer is invoked once and the text -given by the user is made into a string that is then used as the -input stream. If Emacs is running in batch mode, standard input is used -instead of the minibuffer. For example, -@example -(message "%s" (read t)) -@end example -will read a Lisp expression from standard input and print the result -to standard output. - -@item @code{nil} -@cindex @code{nil} input stream -@code{nil} supplied as an input stream means to use the value of -@code{standard-input} instead; that value is the @dfn{default input -stream}, and must be a non-@code{nil} input stream. - -@item @var{symbol} -A symbol as input stream is equivalent to the symbol's function -definition (if any). -@end table - - Here is an example of reading from a stream that is a buffer, showing -where point is located before and after: - -@example -@group ----------- Buffer: foo ---------- -This@point{} is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(read (get-buffer "foo")) - @result{} is -@end group -@group -(read (get-buffer "foo")) - @result{} the -@end group - -@group ----------- Buffer: foo ---------- -This is the@point{} contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -Note that the first read skips a space. Reading skips any amount of -whitespace preceding the significant text. - - Here is an example of reading from a stream that is a marker, -initially positioned at the beginning of the buffer shown. The value -read is the symbol @code{This}. - -@example -@group - ----------- Buffer: foo ---------- -This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) - @result{} # -@end group -@group -(read m) - @result{} This -@end group -@group -m - @result{} # ;; @r{Before the first space.} -@end group -@end example - - Here we read from the contents of a string: - -@example -@group -(read "(When in) the course") - @result{} (When in) -@end group -@end example - - The following example reads from the minibuffer. The -prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt -used when you read from the stream @code{t}.) The user's input is shown -following the prompt. - -@example -@group -(read t) - @result{} 23 ----------- Buffer: Minibuffer ---------- -Lisp expression: @kbd{23 @key{RET}} ----------- Buffer: Minibuffer ---------- -@end group -@end example - - Finally, here is an example of a stream that is a function, named -@code{useless-stream}. Before we use the stream, we initialize the -variable @code{useless-list} to a list of characters. Then each call to -the function @code{useless-stream} obtains the next character in the list -or unreads a character by adding it to the front of the list. - -@example -@group -(setq useless-list (append "XY()" nil)) - @result{} (88 89 40 41) -@end group - -@group -(defun useless-stream (&optional unread) - (if unread - (setq useless-list (cons unread useless-list)) - (prog1 (car useless-list) - (setq useless-list (cdr useless-list))))) - @result{} useless-stream -@end group -@end example - -@noindent -Now we read using the stream thus constructed: - -@example -@group -(read 'useless-stream) - @result{} XY -@end group - -@group -useless-list - @result{} (40 41) -@end group -@end example - -@noindent -Note that the open and close parentheses remain in the list. The Lisp -reader encountered the open parenthesis, decided that it ended the -input, and unread it. Another attempt to read from the stream at this -point would read @samp{()} and return @code{nil}. - -@defun get-file-char -This function is used internally as an input stream to read from the -input file opened by the function @code{load}. Don't use this function -yourself. -@end defun - -@node Input Functions -@section Input Functions - - This section describes the Lisp functions and variables that pertain -to reading. - - In the functions below, @var{stream} stands for an input stream (see -the previous section). If @var{stream} is @code{nil} or omitted, it -defaults to the value of @code{standard-input}. - -@kindex end-of-file - An @code{end-of-file} error is signaled if reading encounters an -unterminated list, vector, or string. - -@defun read &optional stream -This function reads one textual Lisp expression from @var{stream}, -returning it as a Lisp object. This is the basic Lisp input function. -@end defun - -@defun read-from-string string &optional start end -@cindex string to object -This function reads the first textual Lisp expression from the text in -@var{string}. It returns a cons cell whose @sc{car} is that expression, -and whose @sc{cdr} is an integer giving the position of the next -remaining character in the string (i.e., the first one not read). - -If @var{start} is supplied, then reading begins at index @var{start} in -the string (where the first character is at index 0). If you specify -@var{end}, then reading is forced to stop just before that index, as if -the rest of the string were not there. - -For example: - -@example -@group -(read-from-string "(setq x 55) (setq y 5)") - @result{} ((setq x 55) . 11) -@end group -@group -(read-from-string "\"A short string\"") - @result{} ("A short string" . 16) -@end group - -@group -;; @r{Read starting at the first character.} -(read-from-string "(list 112)" 0) - @result{} ((list 112) . 10) -@end group -@group -;; @r{Read starting at the second character.} -(read-from-string "(list 112)" 1) - @result{} (list . 5) -@end group -@group -;; @r{Read starting at the seventh character,} -;; @r{and stopping at the ninth.} -(read-from-string "(list 112)" 6 8) - @result{} (11 . 8) -@end group -@end example -@end defun - -@defvar standard-input -This variable holds the default input stream---the stream that -@code{read} uses when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning use the minibuffer. -@end defvar - -@defvar read-circle -If non-@code{nil}, this variable enables the reading of circular and -shared structures. @xref{Circular Objects}. Its default value is -@code{t}. -@end defvar - -@node Output Streams -@section Output Streams -@cindex stream (for printing) -@cindex output stream - - An output stream specifies what to do with the characters produced -by printing. Most print functions accept an output stream as an -optional argument. Here are the possible types of output stream: - -@table @asis -@item @var{buffer} -@cindex buffer output stream -The output characters are inserted into @var{buffer} at point. -Point advances as characters are inserted. - -@item @var{marker} -@cindex marker output stream -The output characters are inserted into the buffer that @var{marker} -points into, at the marker position. The marker position advances as -characters are inserted. The value of point in the buffer has no effect -on printing when the stream is a marker, and this kind of printing -does not move point (except that if the marker points at or before the -position of point, point advances with the surrounding text, as -usual). - -@item @var{function} -@cindex function output stream -The output characters are passed to @var{function}, which is responsible -for storing them away. It is called with a single character as -argument, as many times as there are characters to be output, and -is responsible for storing the characters wherever you want to put them. - -@item @code{t} -@cindex @code{t} output stream -The output characters are displayed in the echo area. - -@item @code{nil} -@cindex @code{nil} output stream -@code{nil} specified as an output stream means to use the value of -@code{standard-output} instead; that value is the @dfn{default output -stream}, and must not be @code{nil}. - -@item @var{symbol} -A symbol as output stream is equivalent to the symbol's function -definition (if any). -@end table - - Many of the valid output streams are also valid as input streams. The -difference between input and output streams is therefore more a matter -of how you use a Lisp object, than of different types of object. - - Here is an example of a buffer used as an output stream. Point is -initially located as shown immediately before the @samp{h} in -@samp{the}. At the end, point is located directly before that same -@samp{h}. - -@cindex print example -@example -@group ----------- Buffer: foo ---------- -This is t@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group - -(print "This is the output" (get-buffer "foo")) - @result{} "This is the output" - -@group ----------- Buffer: foo ---------- -This is t -"This is the output" -@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - - Now we show a use of a marker as an output stream. Initially, the -marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in -the word @samp{the}. At the end, the marker has advanced over the -inserted text so that it remains positioned before the same @samp{h}. -Note that the location of point, shown in the usual fashion, has no -effect. - -@example -@group ----------- Buffer: foo ---------- -This is the @point{}output ----------- Buffer: foo ---------- -@end group - -@group -(setq m (copy-marker 10)) - @result{} # -@end group - -@group -(print "More output for foo." m) - @result{} "More output for foo." -@end group - -@group ----------- Buffer: foo ---------- -This is t -"More output for foo." -he @point{}output ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} # -@end group -@end example - - The following example shows output to the echo area: - -@example -@group -(print "Echo Area output" t) - @result{} "Echo Area output" ----------- Echo Area ---------- -"Echo Area output" ----------- Echo Area ---------- -@end group -@end example - - Finally, we show the use of a function as an output stream. The -function @code{eat-output} takes each character that it is given and -conses it onto the front of the list @code{last-output} (@pxref{Building -Lists}). At the end, the list contains all the characters output, but -in reverse order. - -@example -@group -(setq last-output nil) - @result{} nil -@end group - -@group -(defun eat-output (c) - (setq last-output (cons c last-output))) - @result{} eat-output -@end group - -@group -(print "This is the output" 'eat-output) - @result{} "This is the output" -@end group - -@group -last-output - @result{} (10 34 116 117 112 116 117 111 32 101 104 - 116 32 115 105 32 115 105 104 84 34 10) -@end group -@end example - -@noindent -Now we can put the output in the proper order by reversing the list: - -@example -@group -(concat (nreverse last-output)) - @result{} " -\"This is the output\" -" -@end group -@end example - -@noindent -Calling @code{concat} converts the list to a string so you can see its -contents more clearly. - -@node Output Functions -@section Output Functions - - This section describes the Lisp functions for printing Lisp -objects---converting objects into their printed representation. - -@cindex @samp{"} in printing -@cindex @samp{\} in printing -@cindex quoting characters in printing -@cindex escape characters in printing - Some of the Emacs printing functions add quoting characters to the -output when necessary so that it can be read properly. The quoting -characters used are @samp{"} and @samp{\}; they distinguish strings from -symbols, and prevent punctuation characters in strings and symbols from -being taken as delimiters when reading. @xref{Printed Representation}, -for full details. You specify quoting or no quoting by the choice of -printing function. - - If the text is to be read back into Lisp, then you should print with -quoting characters to avoid ambiguity. Likewise, if the purpose is to -describe a Lisp object clearly for a Lisp programmer. However, if the -purpose of the output is to look nice for humans, then it is usually -better to print without quoting. - - Lisp objects can refer to themselves. Printing a self-referential -object in the normal way would require an infinite amount of text, and -the attempt could cause infinite recursion. Emacs detects such -recursion and prints @samp{#@var{level}} instead of recursively printing -an object already being printed. For example, here @samp{#0} indicates -a recursive reference to the object at level 0 of the current print -operation: - -@example -(setq foo (list nil)) - @result{} (nil) -(setcar foo foo) - @result{} (#0) -@end example - - In the functions below, @var{stream} stands for an output stream. -(See the previous section for a description of output streams.) If -@var{stream} is @code{nil} or omitted, it defaults to the value of -@code{standard-output}. - -@defun print object &optional stream -@cindex Lisp printer -The @code{print} function is a convenient way of printing. It outputs -the printed representation of @var{object} to @var{stream}, printing in -addition one newline before @var{object} and another after it. Quoting -characters are used. @code{print} returns @var{object}. For example: - -@example -@group -(progn (print 'The\ cat\ in) - (print "the hat") - (print " came back")) - @print{} - @print{} The\ cat\ in - @print{} - @print{} "the hat" - @print{} - @print{} " came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun prin1 object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It does not print newlines to separate output as -@code{print} does, but it does use quoting characters just like -@code{print}. It returns @var{object}. - -@example -@group -(progn (prin1 'The\ cat\ in) - (prin1 "the hat") - (prin1 " came back")) - @print{} The\ cat\ in"the hat"" came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun princ object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It returns @var{object}. - -This function is intended to produce output that is readable by people, -not by @code{read}, so it doesn't insert quoting characters and doesn't -put double-quotes around the contents of strings. It does not add any -spacing between calls. - -@example -@group -(progn - (princ 'The\ cat) - (princ " in the \"hat\"")) - @print{} The cat in the "hat" - @result{} " in the \"hat\"" -@end group -@end example -@end defun - -@defun terpri &optional stream -@cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print.'' -@end defun - -@defun write-char character &optional stream -This function outputs @var{character} to @var{stream}. It returns -@var{character}. -@end defun - -@defun prin1-to-string object &optional noescape -@cindex object to string -This function returns a string containing the text that @code{prin1} -would have printed for the same argument. - -@example -@group -(prin1-to-string 'foo) - @result{} "foo" -@end group -@group -(prin1-to-string (mark-marker)) - @result{} "#" -@end group -@end example - -If @var{noescape} is non-@code{nil}, that inhibits use of quoting -characters in the output. (This argument is supported in Emacs versions -19 and later.) - -@example -@group -(prin1-to-string "foo") - @result{} "\"foo\"" -@end group -@group -(prin1-to-string "foo" t) - @result{} "foo" -@end group -@end example - -See @code{format}, in @ref{Formatting Strings}, for other ways to obtain -the printed representation of a Lisp object as a string. -@end defun - -@defmac with-output-to-string body@dots{} -This macro executes the @var{body} forms with @code{standard-output} set -up to feed output into a string. Then it returns that string. - -For example, if the current buffer name is @samp{foo}, - -@example -(with-output-to-string - (princ "The buffer is ") - (princ (buffer-name))) -@end example - -@noindent -returns @code{"The buffer is foo"}. -@end defmac - -@node Output Variables -@section Variables Affecting Output -@cindex output-controlling variables - -@defvar standard-output -The value of this variable is the default output stream---the stream -that print functions use when the @var{stream} argument is @code{nil}. -The default is @code{t}, meaning display in the echo area. -@end defvar - -@defvar print-quoted -If this is non-@code{nil}, that means to print quoted forms using -abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo}, -@code{(function foo)} as @code{#'foo}, and backquoted forms print -using modern backquote syntax. -@end defvar - -@defvar print-escape-newlines -@cindex @samp{\n} in print -@cindex escape characters -If this variable is non-@code{nil}, then newline characters in strings -are printed as @samp{\n} and formfeeds are printed as @samp{\f}. -Normally these characters are printed as actual newlines and formfeeds. - -This variable affects the print functions @code{prin1} and @code{print} -that print with quoting. It does not affect @code{princ}. Here is an -example using @code{prin1}: - -@example -@group -(prin1 "a\nb") - @print{} "a - @print{} b" - @result{} "a -b" -@end group - -@group -(let ((print-escape-newlines t)) - (prin1 "a\nb")) - @print{} "a\nb" - @result{} "a -b" -@end group -@end example - -@noindent -In the second expression, the local binding of -@code{print-escape-newlines} is in effect during the call to -@code{prin1}, but not during the printing of the result. -@end defvar - -@defvar print-escape-nonascii -If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for unibyte non-@acronym{ASCII} -characters, regardless of the value of this variable, when the output -stream is a multibyte buffer or a marker pointing into one. -@end defvar - -@defvar print-escape-multibyte -If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII} -characters in strings are unconditionally printed as backslash sequences -by the print functions @code{prin1} and @code{print} that print with -quoting. - -Those functions also use backslash sequences for multibyte -non-@acronym{ASCII} characters, regardless of the value of this variable, -when the output stream is a unibyte buffer or a marker pointing into -one. -@end defvar - -@defvar print-length -@cindex printing limits -The value of this variable is the maximum number of elements to print in -any list, vector or bool-vector. If an object being printed has more -than this many elements, it is abbreviated with an ellipsis. - -If the value is @code{nil} (the default), then there is no limit. - -@example -@group -(setq print-length 2) - @result{} 2 -@end group -@group -(print '(1 2 3 4 5)) - @print{} (1 2 ...) - @result{} (1 2 ...) -@end group -@end example -@end defvar - -@defvar print-level -The value of this variable is the maximum depth of nesting of -parentheses and brackets when printed. Any list or vector at a depth -exceeding this limit is abbreviated with an ellipsis. A value of -@code{nil} (which is the default) means no limit. -@end defvar - -@defopt eval-expression-print-length -@defoptx eval-expression-print-level -These are the values for @code{print-length} and @code{print-level} -used by @code{eval-expression}, and thus, indirectly, by many -interactive evaluation commands (@pxref{Lisp Eval,, Evaluating -Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}). -@end defopt - - These variables are used for detecting and reporting circular -and shared structure: - -@defvar print-circle -If non-@code{nil}, this variable enables detection of circular and -shared structure in printing. @xref{Circular Objects}. -@end defvar - -@defvar print-gensym -If non-@code{nil}, this variable enables detection of uninterned symbols -(@pxref{Creating Symbols}) in printing. When this is enabled, -uninterned symbols print with the prefix @samp{#:}, which tells the Lisp -reader to produce an uninterned symbol. -@end defvar - -@defvar print-continuous-numbering -If non-@code{nil}, that means number continuously across print calls. -This affects the numbers printed for @samp{#@var{n}=} labels and -@samp{#@var{m}#} references. - -Don't set this variable with @code{setq}; you should only bind it -temporarily to @code{t} with @code{let}. When you do that, you should -also bind @code{print-number-table} to @code{nil}. -@end defvar - -@defvar print-number-table -This variable holds a vector used internally by printing to implement -the @code{print-circle} feature. You should not use it except -to bind it to @code{nil} when you bind @code{print-continuous-numbering}. -@end defvar - -@defvar float-output-format -This variable specifies how to print floating point numbers. Its -default value is @code{nil}, meaning use the shortest output -that represents the number without losing information. - -To control output format more precisely, you can put a string in this -variable. The string should hold a @samp{%}-specification to be used -in the C function @code{sprintf}. For further restrictions on what -you can use, see the variable's documentation string. -@end defvar - -@ignore - arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434 -@end ignore diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi deleted file mode 100644 index 5dd5e802b89..00000000000 --- a/doc/lispref/strings.texi +++ /dev/null @@ -1,1160 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/strings -@node Strings and Characters, Lists, Numbers, Top -@comment node-name, next, previous, up -@chapter Strings and Characters -@cindex strings -@cindex character arrays -@cindex characters -@cindex bytes - - A string in Emacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files; to send messages to users; to hold text being copied between -buffers; and for many other purposes. Because strings are so important, -Emacs Lisp has many functions expressly for manipulating them. Emacs -Lisp programs use strings more often than individual characters. - - @xref{Strings of Events}, for special considerations for strings of -keyboard character events. - -@menu -* Basics: String Basics. Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. -@end menu - -@node String Basics -@section String and Character Basics - - Characters are represented in Emacs Lisp as integers; -whether an integer is a character or not is determined only by how it is -used. Thus, strings really contain integers. @xref{Character Codes}, -for details about character representation in Emacs. - - The length of a string (like any array) is fixed, and cannot be -altered once the string exists. Strings in Lisp are @emph{not} -terminated by a distinguished character code. (By contrast, strings in -C are terminated by a character with @acronym{ASCII} code 0.) - - Since strings are arrays, and therefore sequences as well, you can -operate on them with the general array and sequence functions. -(@xref{Sequences Arrays Vectors}.) For example, you can access or -change individual characters in a string using the functions @code{aref} -and @code{aset} (@pxref{Array Functions}). - - There are two text representations for non-@acronym{ASCII} characters in -Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text -Representations}). For most Lisp programming, you don't need to be -concerned with these two representations. - - Sometimes key sequences are represented as unibyte strings. When a -unibyte string is a key sequence, string elements in the range 128 to -255 represent meta characters (which are large integers) rather than -character codes in the range 128 to 255. Strings cannot hold -characters that have the hyper, super or alt modifiers; they can hold -@acronym{ASCII} control characters, but no other control characters. -They do not distinguish case in @acronym{ASCII} control characters. -If you want to store such characters in a sequence, such as a key -sequence, you must use a vector instead of a string. @xref{Character -Type}, for more information about keyboard input characters. - - Strings are useful for holding regular expressions. You can also -match regular expressions against strings with @code{string-match} -(@pxref{Regexp Search}). The functions @code{match-string} -(@pxref{Simple Match Data}) and @code{replace-match} (@pxref{Replacing -Match}) are useful for decomposing and modifying strings after -matching regular expressions against them. - - Like a buffer, a string can contain text properties for the characters -in it, as well as the characters themselves. @xref{Text Properties}. -All the Lisp primitives that copy text from strings to buffers or other -strings also copy the properties of the characters being copied. - - @xref{Text}, for information about functions that display strings or -copy them into buffers. @xref{Character Type}, and @ref{String Type}, -for information about the syntax of characters and strings. -@xref{Non-ASCII Characters}, for functions to convert between text -representations and to encode and decode character codes. - -@node Predicates for Strings -@section The Predicates for Strings - -For more information about general sequence and array predicates, -see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. - -@defun stringp object -This function returns @code{t} if @var{object} is a string, @code{nil} -otherwise. -@end defun - -@defun string-or-null-p object -This function returns @code{t} if @var{object} is a string or -@code{nil}. It returns @code{nil} otherwise. -@end defun - -@defun char-or-string-p object -This function returns @code{t} if @var{object} is a string or a -character (i.e., an integer), @code{nil} otherwise. -@end defun - -@node Creating Strings -@section Creating Strings - - The following functions create strings, either from scratch, or by -putting strings together, or by taking them apart. - -@defun make-string count character -This function returns a string made up of @var{count} repetitions of -@var{character}. If @var{count} is negative, an error is signaled. - -@example -(make-string 5 ?x) - @result{} "xxxxx" -(make-string 0 ?x) - @result{} "" -@end example - - Other functions to compare with this one include @code{char-to-string} -(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and -@code{make-list} (@pxref{Building Lists}). -@end defun - -@defun string &rest characters -This returns a string containing the characters @var{characters}. - -@example -(string ?a ?b ?c) - @result{} "abc" -@end example -@end defun - -@defun substring string start &optional end -This function returns a new string which consists of those characters -from @var{string} in the range from (and including) the character at the -index @var{start} up to (but excluding) the character at the index -@var{end}. The first character is at index zero. - -@example -@group -(substring "abcdefg" 0 3) - @result{} "abc" -@end group -@end example - -@noindent -In the above example, the index for @samp{a} is 0, the index for -@samp{b} is 1, and the index for @samp{c} is 2. The index 3---which -is the the fourth character in the string---marks the character -position up to which the substring is copied. Thus, @samp{abc} is -copied from the string @code{"abcdefg"}. - -A negative number counts from the end of the string, so that @minus{}1 -signifies the index of the last character of the string. For example: - -@example -@group -(substring "abcdefg" -3 -1) - @result{} "ef" -@end group -@end example - -@noindent -In this example, the index for @samp{e} is @minus{}3, the index for -@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. -Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. - -When @code{nil} is used for @var{end}, it stands for the length of the -string. Thus, - -@example -@group -(substring "abcdefg" -3 nil) - @result{} "efg" -@end group -@end example - -Omitting the argument @var{end} is equivalent to specifying @code{nil}. -It follows that @code{(substring @var{string} 0)} returns a copy of all -of @var{string}. - -@example -@group -(substring "abcdefg" 0) - @result{} "abcdefg" -@end group -@end example - -@noindent -But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence -Functions}). - -If the characters copied from @var{string} have text properties, the -properties are copied into the new string also. @xref{Text Properties}. - -@code{substring} also accepts a vector for the first argument. -For example: - -@example -(substring [a b (c) "d"] 1 3) - @result{} [b (c)] -@end example - -A @code{wrong-type-argument} error is signaled if @var{start} is not -an integer or if @var{end} is neither an integer nor @code{nil}. An -@code{args-out-of-range} error is signaled if @var{start} indicates a -character following @var{end}, or if either integer is out of range -for @var{string}. - -Contrast this function with @code{buffer-substring} (@pxref{Buffer -Contents}), which returns a string containing a portion of the text in -the current buffer. The beginning of a string is at index 0, but the -beginning of a buffer is at index 1. -@end defun - -@defun substring-no-properties string &optional start end -This works like @code{substring} but discards all text properties from -the value. Also, @var{start} may be omitted or @code{nil}, which is -equivalent to 0. Thus, @w{@code{(substring-no-properties -@var{string})}} returns a copy of @var{string}, with all text -properties removed. -@end defun - -@defun concat &rest sequences -@cindex copying strings -@cindex concatenating strings -This function returns a new string consisting of the characters in the -arguments passed to it (along with their text properties, if any). The -arguments may be strings, lists of numbers, or vectors of numbers; they -are not themselves changed. If @code{concat} receives no arguments, it -returns an empty string. - -@example -(concat "abc" "-def") - @result{} "abc-def" -(concat "abc" (list 120 121) [122]) - @result{} "abcxyz" -;; @r{@code{nil} is an empty sequence.} -(concat "abc" nil "-def") - @result{} "abc-def" -(concat "The " "quick brown " "fox.") - @result{} "The quick brown fox." -(concat) - @result{} "" -@end example - -@noindent -This function always constructs a new string that is not @code{eq} to -any existing string, except when the result is the empty string (to -save space, Emacs makes only one empty multibyte string). - -For information about other concatenation functions, see the -description of @code{mapconcat} in @ref{Mapping Functions}, -@code{vconcat} in @ref{Vector Functions}, and @code{append} in @ref{Building -Lists}. For concatenating individual command-line arguments into a -string to be used as a shell command, see @ref{Shell Arguments, -combine-and-quote-strings}. -@end defun - -@defun split-string string &optional separators omit-nulls -This function splits @var{string} into substrings based on the regular -expression @var{separators} (@pxref{Regular Expressions}). Each match -for @var{separators} defines a splitting point; the substrings between -splitting points are made into a list, which is returned. - -If @var{omit-nulls} is @code{nil} (or omitted), the result contains -null strings whenever there are two consecutive matches for -@var{separators}, or a match is adjacent to the beginning or end of -@var{string}. If @var{omit-nulls} is @code{t}, these null strings are -omitted from the result. - -If @var{separators} is @code{nil} (or omitted), the default is the -value of @code{split-string-default-separators}. - -As a special case, when @var{separators} is @code{nil} (or omitted), -null strings are always omitted from the result. Thus: - -@example -(split-string " two words ") - @result{} ("two" "words") -@end example - -The result is not @code{("" "two" "words" "")}, which would rarely be -useful. If you need such a result, use an explicit value for -@var{separators}: - -@example -(split-string " two words " - split-string-default-separators) - @result{} ("" "two" "words" "") -@end example - -More examples: - -@example -(split-string "Soup is good food" "o") - @result{} ("S" "up is g" "" "d f" "" "d") -(split-string "Soup is good food" "o" t) - @result{} ("S" "up is g" "d f" "d") -(split-string "Soup is good food" "o+") - @result{} ("S" "up is g" "d f" "d") -@end example - -Empty matches do count, except that @code{split-string} will not look -for a final empty match when it already reached the end of the string -using a non-empty match or when @var{string} is empty: - -@example -(split-string "aooob" "o*") - @result{} ("" "a" "" "b" "") -(split-string "ooaboo" "o*") - @result{} ("" "" "a" "b" "") -(split-string "" "") - @result{} ("") -@end example - -However, when @var{separators} can match the empty string, -@var{omit-nulls} is usually @code{t}, so that the subtleties in the -three previous examples are rarely relevant: - -@example -(split-string "Soup is good food" "o*" t) - @result{} ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d") -(split-string "Nice doggy!" "" t) - @result{} ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!") -(split-string "" "" t) - @result{} nil -@end example - -Somewhat odd, but predictable, behavior can occur for certain -``non-greedy'' values of @var{separators} that can prefer empty -matches over non-empty matches. Again, such values rarely occur in -practice: - -@example -(split-string "ooo" "o*" t) - @result{} nil -(split-string "ooo" "\\|o+" t) - @result{} ("o" "o" "o") -@end example - -If you need to split a string that is a shell command, where -individual arguments could be quoted, see @ref{Shell Arguments, -split-string-and-unquote}. -@end defun - -@defvar split-string-default-separators -The default value of @var{separators} for @code{split-string}. Its -usual value is @w{@code{"[ \f\t\n\r\v]+"}}. -@end defvar - -@node Modifying Strings -@section Modifying Strings - - The most basic way to alter the contents of an existing string is with -@code{aset} (@pxref{Array Functions}). @code{(aset @var{string} -@var{idx} @var{char})} stores @var{char} into @var{string} at index -@var{idx}. Each character occupies one or more bytes, and if @var{char} -needs a different number of bytes from the character already present at -that index, @code{aset} signals an error. - - A more powerful function is @code{store-substring}: - -@defun store-substring string idx obj -This function alters part of the contents of the string @var{string}, by -storing @var{obj} starting at index @var{idx}. The argument @var{obj} -may be either a character or a (smaller) string. - -Since it is impossible to change the length of an existing string, it is -an error if @var{obj} doesn't fit within @var{string}'s actual length, -or if any new character requires a different number of bytes from the -character currently present at that point in @var{string}. -@end defun - - To clear out a string that contained a password, use -@code{clear-string}: - -@defun clear-string string -This makes @var{string} a unibyte string and clears its contents to -zeros. It may also change @var{string}'s length. -@end defun - -@need 2000 -@node Text Comparison -@section Comparison of Characters and Strings -@cindex string equality - -@defun char-equal character1 character2 -This function returns @code{t} if the arguments represent the same -character, @code{nil} otherwise. This function ignores differences -in case if @code{case-fold-search} is non-@code{nil}. - -@example -(char-equal ?x ?x) - @result{} t -(let ((case-fold-search nil)) - (char-equal ?x ?X)) - @result{} nil -@end example -@end defun - -@defun string= string1 string2 -This function returns @code{t} if the characters of the two strings -match exactly. Symbols are also allowed as arguments, in which case -their print names are used. -Case is always significant, regardless of @code{case-fold-search}. - -@example -(string= "abc" "abc") - @result{} t -(string= "abc" "ABC") - @result{} nil -(string= "ab" "ABC") - @result{} nil -@end example - -The function @code{string=} ignores the text properties of the two -strings. When @code{equal} (@pxref{Equality Predicates}) compares two -strings, it uses @code{string=}. - -For technical reasons, a unibyte and a multibyte string are -@code{equal} if and only if they contain the same sequence of -character codes and all these codes are either in the range 0 through -127 (@acronym{ASCII}) or 160 through 255 (@code{eight-bit-graphic}). -However, when a unibyte string is converted to a multibyte string, all -characters with codes in the range 160 through 255 are converted to -characters with higher codes, whereas @acronym{ASCII} characters -remain unchanged. Thus, a unibyte string and its conversion to -multibyte are only @code{equal} if the string is all @acronym{ASCII}. -Character codes 160 through 255 are not entirely proper in multibyte -text, even though they can occur. As a consequence, the situation -where a unibyte and a multibyte string are @code{equal} without both -being all @acronym{ASCII} is a technical oddity that very few Emacs -Lisp programmers ever get confronted with. @xref{Text -Representations}. -@end defun - -@defun string-equal string1 string2 -@code{string-equal} is another name for @code{string=}. -@end defun - -@cindex lexical comparison -@defun string< string1 string2 -@c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. It -scans both the strings at the same time to find the first pair of corresponding -characters that do not match. If the lesser character of these two is -the character from @var{string1}, then @var{string1} is less, and this -function returns @code{t}. If the lesser character is the one from -@var{string2}, then @var{string1} is greater, and this function returns -@code{nil}. If the two strings match entirely, the value is @code{nil}. - -Pairs of characters are compared according to their character codes. -Keep in mind that lower case letters have higher numeric values in the -@acronym{ASCII} character set than their upper case counterparts; digits and -many punctuation characters have a lower numeric value than upper case -letters. An @acronym{ASCII} character is less than any non-@acronym{ASCII} -character; a unibyte non-@acronym{ASCII} character is always less than any -multibyte non-@acronym{ASCII} character (@pxref{Text Representations}). - -@example -@group -(string< "abc" "abd") - @result{} t -(string< "abd" "abc") - @result{} nil -(string< "123" "abc") - @result{} t -@end group -@end example - -When the strings have different lengths, and they match up to the -length of @var{string1}, then the result is @code{t}. If they match up -to the length of @var{string2}, the result is @code{nil}. A string of -no characters is less than any other string. - -@example -@group -(string< "" "abc") - @result{} t -(string< "ab" "abc") - @result{} t -(string< "abc" "") - @result{} nil -(string< "abc" "ab") - @result{} nil -(string< "" "") - @result{} nil -@end group -@end example - -Symbols are also allowed as arguments, in which case their print names -are used. -@end defun - -@defun string-lessp string1 string2 -@code{string-lessp} is another name for @code{string<}. -@end defun - -@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case -This function compares the specified part of @var{string1} with the -specified part of @var{string2}. The specified part of @var{string1} -runs from index @var{start1} up to index @var{end1} (@code{nil} means -the end of the string). The specified part of @var{string2} runs from -index @var{start2} up to index @var{end2} (@code{nil} means the end of -the string). - -The strings are both converted to multibyte for the comparison -(@pxref{Text Representations}) so that a unibyte string and its -conversion to multibyte are always regarded as equal. If -@var{ignore-case} is non-@code{nil}, then case is ignored, so that -upper case letters can be equal to lower case letters. - -If the specified portions of the two strings match, the value is -@code{t}. Otherwise, the value is an integer which indicates how many -leading characters agree, and which string is less. Its absolute value -is one plus the number of characters that agree at the beginning of the -two strings. The sign is negative if @var{string1} (or its specified -portion) is less. -@end defun - -@defun assoc-string key alist &optional case-fold -This function works like @code{assoc}, except that @var{key} must be a -string or symbol, and comparison is done using @code{compare-strings}. -Symbols are converted to strings before testing. -If @var{case-fold} is non-@code{nil}, it ignores case differences. -Unlike @code{assoc}, this function can also match elements of the alist -that are strings or symbols rather than conses. In particular, @var{alist} can -be a list of strings or symbols rather than an actual alist. -@xref{Association Lists}. -@end defun - - See also the function @code{compare-buffer-substrings} in -@ref{Comparing Text}, for a way to compare text in buffers. The -function @code{string-match}, which matches a regular expression -against a string, can be used for a kind of string comparison; see -@ref{Regexp Search}. - -@node String Conversion -@comment node-name, next, previous, up -@section Conversion of Characters and Strings -@cindex conversion of strings - - This section describes functions for converting between characters, -strings and integers. @code{format} (@pxref{Formatting Strings}) and -@code{prin1-to-string} (@pxref{Output Functions}) can also convert -Lisp objects into strings. @code{read-from-string} (@pxref{Input -Functions}) can ``convert'' a string representation of a Lisp object -into an object. The functions @code{string-make-multibyte} and -@code{string-make-unibyte} convert the text representation of a string -(@pxref{Converting Representations}). - - @xref{Documentation}, for functions that produce textual descriptions -of text characters and general input events -(@code{single-key-description} and @code{text-char-description}). These -are used primarily for making help messages. - -@defun char-to-string character -@cindex character to string -This function returns a new string containing one character, -@var{character}. This function is semi-obsolete because the function -@code{string} is more general. @xref{Creating Strings}. -@end defun - -@defun string-to-char string -@cindex string to character - This function returns the first character in @var{string}. If the -string is empty, the function returns 0. The value is also 0 when the -first character of @var{string} is the null character, @acronym{ASCII} code -0. - -@example -(string-to-char "ABC") - @result{} 65 - -(string-to-char "xyz") - @result{} 120 -(string-to-char "") - @result{} 0 -@group -(string-to-char "\000") - @result{} 0 -@end group -@end example - -This function may be eliminated in the future if it does not seem useful -enough to retain. -@end defun - -@defun number-to-string number -@cindex integer to string -@cindex integer to decimal -This function returns a string consisting of the printed base-ten -representation of @var{number}, which may be an integer or a floating -point number. The returned value starts with a minus sign if the argument is -negative. - -@example -(number-to-string 256) - @result{} "256" -@group -(number-to-string -23) - @result{} "-23" -@end group -(number-to-string -23.5) - @result{} "-23.5" -@end example - -@cindex int-to-string -@code{int-to-string} is a semi-obsolete alias for this function. - -See also the function @code{format} in @ref{Formatting Strings}. -@end defun - -@defun string-to-number string &optional base -@cindex string to number -This function returns the numeric value of the characters in -@var{string}. If @var{base} is non-@code{nil}, it must be an integer -between 2 and 16 (inclusive), and integers are converted in that base. -If @var{base} is @code{nil}, then base ten is used. Floating point -conversion only works in base ten; we have not implemented other -radices for floating point numbers, because that would be much more -work and does not seem useful. If @var{string} looks like an integer -but its value is too large to fit into a Lisp integer, -@code{string-to-number} returns a floating point result. - -The parsing skips spaces and tabs at the beginning of @var{string}, -then reads as much of @var{string} as it can interpret as a number in -the given base. (On some systems it ignores other whitespace at the -beginning, not just spaces and tabs.) If the first character after -the ignored whitespace is neither a digit in the given base, nor a -plus or minus sign, nor the leading dot of a floating point number, -this function returns 0. - -@example -(string-to-number "256") - @result{} 256 -(string-to-number "25 is a perfect square.") - @result{} 25 -(string-to-number "X256") - @result{} 0 -(string-to-number "-4.5") - @result{} -4.5 -(string-to-number "1e5") - @result{} 100000.0 -@end example - -@findex string-to-int -@code{string-to-int} is an obsolete alias for this function. -@end defun - - Here are some other functions that can convert to or from a string: - -@table @code -@item concat -@code{concat} can convert a vector or a list into a string. -@xref{Creating Strings}. - -@item vconcat -@code{vconcat} can convert a string into a vector. @xref{Vector -Functions}. - -@item append -@code{append} can convert a string into a list. @xref{Building Lists}. -@end table - -@node Formatting Strings -@comment node-name, next, previous, up -@section Formatting Strings -@cindex formatting strings -@cindex strings, formatting them - - @dfn{Formatting} means constructing a string by substituting -computed values at various places in a constant string. This constant -string controls how the other values are printed, as well as where -they appear; it is called a @dfn{format string}. - - Formatting is often useful for computing messages to be displayed. In -fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only -in how they use the result of formatting. - -@defun format string &rest objects -This function returns a new string that is made by copying -@var{string} and then replacing any format specification -in the copy with encodings of the corresponding @var{objects}. The -arguments @var{objects} are the computed values to be formatted. - -The characters in @var{string}, other than the format specifications, -are copied directly into the output, including their text properties, -if any. -@end defun - -@cindex @samp{%} in format -@cindex format specification - A format specification is a sequence of characters beginning with a -@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the -@code{format} function replaces it with the printed representation of -one of the values to be formatted (one of the arguments @var{objects}). -For example: - -@example -@group -(format "The value of fill-column is %d." fill-column) - @result{} "The value of fill-column is 72." -@end group -@end example - - Since @code{format} interprets @samp{%} characters as format -specifications, you should @emph{never} pass an arbitrary string as -the first argument. This is particularly true when the string is -generated by some Lisp code. Unless the string is @emph{known} to -never include any @samp{%} characters, pass @code{"%s"}, described -below, as the first argument, and the string as the second, like this: - -@example - (format "%s" @var{arbitrary-string}) -@end example - - If @var{string} contains more than one format specification, the -format specifications correspond to successive values from -@var{objects}. Thus, the first format specification in @var{string} -uses the first such value, the second format specification uses the -second such value, and so on. Any extra format specifications (those -for which there are no corresponding values) cause an error. Any -extra values to be formatted are ignored. - - Certain format specifications require values of particular types. If -you supply a value that doesn't fit the requirements, an error is -signaled. - - Here is a table of valid format specifications: - -@table @samp -@item %s -Replace the specification with the printed representation of the object, -made without quoting (that is, using @code{princ}, not -@code{prin1}---@pxref{Output Functions}). Thus, strings are represented -by their contents alone, with no @samp{"} characters, and symbols appear -without @samp{\} characters. - -If the object is a string, its text properties are -copied into the output. The text properties of the @samp{%s} itself -are also copied, but those of the object take priority. - -@item %S -Replace the specification with the printed representation of the object, -made with quoting (that is, using @code{prin1}---@pxref{Output -Functions}). Thus, strings are enclosed in @samp{"} characters, and -@samp{\} characters appear where necessary before special characters. - -@item %o -@cindex integer to octal -Replace the specification with the base-eight representation of an -integer. - -@item %d -Replace the specification with the base-ten representation of an -integer. - -@item %x -@itemx %X -@cindex integer to hexadecimal -Replace the specification with the base-sixteen representation of an -integer. @samp{%x} uses lower case and @samp{%X} uses upper case. - -@item %c -Replace the specification with the character which is the value given. - -@item %e -Replace the specification with the exponential notation for a floating -point number. - -@item %f -Replace the specification with the decimal-point notation for a floating -point number. - -@item %g -Replace the specification with notation for a floating point number, -using either exponential notation or decimal-point notation, whichever -is shorter. - -@item %% -Replace the specification with a single @samp{%}. This format -specification is unusual in that it does not use a value. For example, -@code{(format "%% %d" 30)} returns @code{"% 30"}. -@end table - - Any other format character results in an @samp{Invalid format -operation} error. - - Here are several examples: - -@example -@group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - -(format "The octal value of %d is %o, - and the hex value is %x." 18 18 18) - @result{} "The octal value of 18 is 22, - and the hex value is 12." -@end group -@end example - -@cindex field width -@cindex padding - A specification can have a @dfn{width}, which is a decimal number -between the @samp{%} and the specification character. If the printed -representation of the object contains fewer characters than this -width, @code{format} extends it with padding. The width specifier is -ignored for the @samp{%%} specification. Any padding introduced by -the width specifier normally consists of spaces inserted on the left: - -@example -(format "%5d is padded on the left with spaces" 123) - @result{} " 123 is padded on the left with spaces" -@end example - -@noindent -If the width is too small, @code{format} does not truncate the -object's printed representation. Thus, you can use a width to specify -a minimum spacing between columns with no risk of losing information. -In the following three examples, @samp{%7s} specifies a minimum width -of 7. In the first case, the string inserted in place of @samp{%7s} -has only 3 letters, and needs 4 blank spaces as padding. In the -second case, the string @code{"specification"} is 13 letters wide but -is not truncated. - -@example -@group -(format "The word `%7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word ` foo' actually has 3 letters in it." -(format "The word `%7s' actually has %d letters in it." - "specification" (length "specification")) - @result{} "The word `specification' actually has 13 letters in it." -@end group -@end example - -@cindex flags in format specifications - Immediately after the @samp{%} and before the optional width -specifier, you can also put certain @dfn{flag characters}. - - The flag @samp{+} inserts a plus sign before a positive number, so -that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are -ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if -both flags are used, @samp{+} takes precedence. - - The flag @samp{#} specifies an ``alternate form'' which depends on -the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result -with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g}, -the @samp{#} flag means include a decimal point even if the precision -is zero. - - The flag @samp{-} causes the padding inserted by the width -specifier, if any, to be inserted on the right rather than the left. -The flag @samp{0} ensures that the padding consists of @samp{0} -characters instead of spaces, inserted on the left. These flags are -ignored for specification characters for which they do not make sense: -@samp{%s}, @samp{%S} and @samp{%c} accept the @samp{0} flag, but still -pad with @emph{spaces} on the left. If both @samp{-} and @samp{0} are -present and valid, @samp{-} takes precedence. - -@example -@group -(format "%06d is padded on the left with zeros" 123) - @result{} "000123 is padded on the left with zeros" - -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" - -(format "The word `%-7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." -@end group -@end example - -@cindex precision in format specifications - All the specification characters allow an optional @dfn{precision} -before the character (after the width, if present). The precision is -a decimal-point @samp{.} followed by a digit-string. For the -floating-point specifications (@samp{%e}, @samp{%f}, @samp{%g}), the -precision specifies how many decimal places to show; if zero, the -decimal-point itself is also omitted. For @samp{%s} and @samp{%S}, -the precision truncates the string to the given width, so @samp{%.3s} -shows only the first three characters of the representation for -@var{object}. Precision has no effect for other specification -characters. - -@node Case Conversion -@comment node-name, next, previous, up -@section Case Conversion in Lisp -@cindex upper case -@cindex lower case -@cindex character case -@cindex case conversion in Lisp - - The character case functions change the case of single characters or -of the contents of strings. The functions normally convert only -alphabetic characters (the letters @samp{A} through @samp{Z} and -@samp{a} through @samp{z}, as well as non-@acronym{ASCII} letters); other -characters are not altered. You can specify a different case -conversion mapping by specifying a case table (@pxref{Case Tables}). - - These functions do not modify the strings that are passed to them as -arguments. - - The examples below use the characters @samp{X} and @samp{x} which have -@acronym{ASCII} codes 88 and 120 respectively. - -@defun downcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to lower case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is upper case is -converted to lower case. When @var{string-or-char} is a character, -this function returns the corresponding lower case character (an -integer); if the original character is lower case, or is not a letter, -the return value is equal to the original character. - -@example -(downcase "The cat in the hat") - @result{} "the cat in the hat" - -(downcase ?X) - @result{} 120 -@end example -@end defun - -@defun upcase string-or-char -This function converts @var{string-or-char}, which should be either a -character or a string, to upper case. - -When @var{string-or-char} is a string, this function returns a new -string in which each letter in the argument that is lower case is -converted to upper case. When @var{string-or-char} is a character, -this function returns the corresponding upper case character (an an -integer); if the original character is upper case, or is not a letter, -the return value is equal to the original character. - -@example -(upcase "The cat in the hat") - @result{} "THE CAT IN THE HAT" - -(upcase ?x) - @result{} 88 -@end example -@end defun - -@defun capitalize string-or-char -@cindex capitalization -This function capitalizes strings or characters. If -@var{string-or-char} is a string, the function returns a new string -whose contents are a copy of @var{string-or-char} in which each word -has been capitalized. This means that the first character of each -word is converted to upper case, and the rest are converted to lower -case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When @var{string-or-char} is a character, this function does the same -thing as @code{upcase}. - -@example -@group -(capitalize "The cat in the hat") - @result{} "The Cat In The Hat" -@end group - -@group -(capitalize "THE 77TH-HATTED CAT") - @result{} "The 77th-Hatted Cat" -@end group - -@group -(capitalize ?x) - @result{} 88 -@end group -@end example -@end defun - -@defun upcase-initials string-or-char -If @var{string-or-char} is a string, this function capitalizes the -initials of the words in @var{string-or-char}, without altering any -letters other than the initials. It returns a new string whose -contents are a copy of @var{string-or-char}, in which each word has -had its initial letter converted to upper case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@pxref{Syntax Class Table}). - -When the argument to @code{upcase-initials} is a character, -@code{upcase-initials} has the same result as @code{upcase}. - -@example -@group -(upcase-initials "The CAT in the hAt") - @result{} "The CAT In The HAt" -@end group -@end example -@end defun - - @xref{Text Comparison}, for functions that compare strings; some of -them ignore case differences, or can optionally ignore case differences. - -@node Case Tables -@section The Case Table - - You can customize case conversion by installing a special @dfn{case -table}. A case table specifies the mapping between upper case and lower -case letters. It affects both the case conversion functions for Lisp -objects (see the previous section) and those that apply to text in the -buffer (@pxref{Case Changes}). Each buffer has a case table; there is -also a standard case table which is used to initialize the case table -of new buffers. - - A case table is a char-table (@pxref{Char-Tables}) whose subtype is -@code{case-table}. This char-table maps each character into the -corresponding lower case character. It has three extra slots, which -hold related tables: - -@table @var -@item upcase -The upcase table maps each character into the corresponding upper -case character. -@item canonicalize -The canonicalize table maps all of a set of case-related characters -into a particular member of that set. -@item equivalences -The equivalences table maps each one of a set of case-related characters -into the next character in that set. -@end table - - In simple cases, all you need to specify is the mapping to lower-case; -the three related tables will be calculated automatically from that one. - - For some languages, upper and lower case letters are not in one-to-one -correspondence. There may be two different lower case letters with the -same upper case equivalent. In these cases, you need to specify the -maps for both lower case and upper case. - - The extra table @var{canonicalize} maps each character to a canonical -equivalent; any two characters that are related by case-conversion have -the same canonical equivalent character. For example, since @samp{a} -and @samp{A} are related by case-conversion, they should have the same -canonical equivalent character (which should be either @samp{a} for both -of them, or @samp{A} for both of them). - - The extra table @var{equivalences} is a map that cyclically permutes -each equivalence class (of characters with the same canonical -equivalent). (For ordinary @acronym{ASCII}, this would map @samp{a} into -@samp{A} and @samp{A} into @samp{a}, and likewise for each set of -equivalent characters.) - - When constructing a case table, you can provide @code{nil} for -@var{canonicalize}; then Emacs fills in this slot from the lower case -and upper case mappings. You can also provide @code{nil} for -@var{equivalences}; then Emacs fills in this slot from -@var{canonicalize}. In a case table that is actually in use, those -components are non-@code{nil}. Do not try to specify -@var{equivalences} without also specifying @var{canonicalize}. - - Here are the functions for working with case tables: - -@defun case-table-p object -This predicate returns non-@code{nil} if @var{object} is a valid case -table. -@end defun - -@defun set-standard-case-table table -This function makes @var{table} the standard case table, so that it will -be used in any buffers created subsequently. -@end defun - -@defun standard-case-table -This returns the standard case table. -@end defun - -@defun current-case-table -This function returns the current buffer's case table. -@end defun - -@defun set-case-table table -This sets the current buffer's case table to @var{table}. -@end defun - -@defmac with-case-table table body@dots{} -The @code{with-case-table} macro saves the current case table, makes -@var{table} the current case table, evaluates the @var{body} forms, -and finally restores the case table. The return value is the value of -the last form in @var{body}. The case table is restored even in case -of an abnormal exit via @code{throw} or error (@pxref{Nonlocal -Exits}). -@end defmac - - Some language environments modify the case conversions of -@acronym{ASCII} characters; for example, in the Turkish language -environment, the @acronym{ASCII} character @samp{I} is downcased into -a Turkish ``dotless i''. This can interfere with code that requires -ordinary ASCII case conversion, such as implementations of -@acronym{ASCII}-based network protocols. In that case, use the -@code{with-case-table} macro with the variable @var{ascii-case-table}, -which stores the unmodified case table for the @acronym{ASCII} -character set. - -@defvar ascii-case-table -The case table for the @acronym{ASCII} character set. This should not be -modified by any language environment settings. -@end defvar - - The following three functions are convenient subroutines for packages -that define non-@acronym{ASCII} character sets. They modify the specified -case table @var{case-table}; they also modify the standard syntax table. -@xref{Syntax Tables}. Normally you would use these functions to change -the standard case table. - -@defun set-case-syntax-pair uc lc case-table -This function specifies a pair of corresponding letters, one upper case -and one lower case. -@end defun - -@defun set-case-syntax-delims l r case-table -This function makes characters @var{l} and @var{r} a matching pair of -case-invariant delimiters. -@end defun - -@defun set-case-syntax char syntax case-table -This function makes @var{char} case-invariant, with syntax -@var{syntax}. -@end defun - -@deffn Command describe-buffer-case-table -This command displays a description of the contents of the current -buffer's case table. -@end deffn - -@ignore - arch-tag: 700b8e95-7aa5-4b52-9eb3-8f2e1ea152b4 -@end ignore diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi deleted file mode 100644 index d5d5bb05f73..00000000000 --- a/doc/lispref/symbols.texi +++ /dev/null @@ -1,596 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/symbols -@node Symbols, Evaluation, Hash Tables, Top -@chapter Symbols -@cindex symbol - - A @dfn{symbol} is an object with a unique name. This chapter -describes symbols, their components, their property lists, and how they -are created and interned. Separate chapters describe the use of symbols -as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. - - You can test whether an arbitrary Lisp object is a symbol -with @code{symbolp}: - -@defun symbolp object -This function returns @code{t} if @var{object} is a symbol, @code{nil} -otherwise. -@end defun - -@menu -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. -@end menu - -@node Symbol Components, Definitions, Symbols, Symbols -@section Symbol Components -@cindex symbol components - - Each symbol has four components (or ``cells''), each of which -references another object: - -@table @asis -@item Print name -@cindex print name cell -The @dfn{print name cell} holds a string that names the symbol for -reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. - -@item Value -@cindex value cell -The @dfn{value cell} holds the current value of the symbol as a -variable. When a symbol is used as a form, the value of the form is the -contents of the symbol's value cell. See @code{symbol-value} in -@ref{Accessing Variables}. - -@item Function -@cindex function cell -The @dfn{function cell} holds the function definition of the symbol. -When a symbol is used as a function, its function definition is used in -its place. This cell is also used to make a symbol stand for a keymap -or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables names and function names do -not conflict. See @code{symbol-function} in @ref{Function Cells}. - -@item Property list -@cindex property list cell -The @dfn{property list cell} holds the property list of the symbol. See -@code{symbol-plist} in @ref{Property Lists}. -@end table - - The print name cell always holds a string, and cannot be changed. The -other three cells can be set individually to any specified Lisp object. - - The print name cell holds the string that is the name of the symbol. -Since symbols are represented textually by their names, it is important -not to have two symbols with the same name. The Lisp reader ensures -this: every time it reads a symbol, it looks for an existing symbol with -the specified name before it creates a new one. (In GNU Emacs Lisp, -this lookup uses a hashing algorithm and an obarray; see @ref{Creating -Symbols}.) - - The value cell holds the symbol's value as a variable -(@pxref{Variables}). That is what you get if you evaluate the symbol as -a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate -value. Certain symbols have values that cannot be changed; these -include @code{nil} and @code{t}, and any symbol whose name starts with -@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}. - - We often refer to ``the function @code{foo}'' when we really mean -the function stored in the function cell of the symbol @code{foo}. We -make the distinction explicit only when necessary. In normal -usage, the function cell usually contains a function -(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the -Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard -macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and -autoload objects (@pxref{Autoloading}) are also sometimes stored in -the function cells of symbols. - - The property list cell normally should hold a correctly formatted -property list (@pxref{Property Lists}), as a number of functions expect -to see a property list there. - - The function cell or the value cell may be @dfn{void}, which means -that the cell does not reference any object. (This is not the same -thing as holding the symbol @code{void}, nor the same as holding the -symbol @code{nil}.) Examining a function or value cell that is void -results in an error, such as @samp{Symbol's value as variable is void}. - - The four functions @code{symbol-name}, @code{symbol-value}, -@code{symbol-plist}, and @code{symbol-function} return the contents of -the four cells of a symbol. Here as an example we show the contents of -the four cells of the symbol @code{buffer-file-name}: - -@example -(symbol-name 'buffer-file-name) - @result{} "buffer-file-name" -(symbol-value 'buffer-file-name) - @result{} "/gnu/elisp/symbols.texi" -(symbol-function 'buffer-file-name) - @result{} # -(symbol-plist 'buffer-file-name) - @result{} (variable-documentation 29529) -@end example - -@noindent -Because this symbol is the variable which holds the name of the file -being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the Emacs Lisp Manual. -The property list cell contains the list @code{(variable-documentation -29529)} which tells the documentation functions where to find the -documentation string for the variable @code{buffer-file-name} in the -@file{DOC-@var{version}} file. (29529 is the offset from the beginning -of the @file{DOC-@var{version}} file to where that documentation string -begins---see @ref{Documentation Basics}.) The function cell contains -the function for returning the name of the file. -@code{buffer-file-name} names a primitive function, which has no read -syntax and prints in hash notation (@pxref{Primitive Function Type}). A -symbol naming a function written in Lisp would have a lambda expression -(or a byte-code object) in this cell. - -@node Definitions, Creating Symbols, Symbol Components, Symbols -@section Defining Symbols -@cindex definitions of symbols - - A @dfn{definition} in Lisp is a special form that announces your -intention to use a certain symbol in a particular way. In Emacs Lisp, -you can define a symbol as a variable, or define it as a function (or -macro), or both independently. - - A definition construct typically specifies a value or meaning for the -symbol for one kind of use, plus documentation for its meaning when used -in this way. Thus, when you define a symbol as a variable, you can -supply an initial value for the variable, plus documentation for the -variable. - - @code{defvar} and @code{defconst} are special forms that define a -symbol as a global variable. They are documented in detail in -@ref{Defining Variables}. For defining user option variables that can -be customized, use @code{defcustom} (@pxref{Customization}). - - @code{defun} defines a symbol as a function, creating a lambda -expression and storing it in the function cell of the symbol. This -lambda expression thus becomes the function definition of the symbol. -(The term ``function definition,'' meaning the contents of the function -cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @code{defsubst} and @code{defalias} are two -other ways of defining a function. @xref{Functions}. - - @code{defmacro} defines a symbol as a macro. It creates a macro -object and stores it in the function cell of the symbol. Note that a -given symbol can be a macro or a function, but not both at once, because -both macro and function definitions are kept in the function cell, and -that cell can hold only one Lisp object at any given time. -@xref{Macros}. - - In Emacs Lisp, a definition is not required in order to use a symbol -as a variable or function. Thus, you can make a symbol a global -variable with @code{setq}, whether you define it first or not. The real -purpose of definitions is to guide programmers and programming tools. -They inform programmers who read the code that certain symbols are -@emph{intended} to be used as variables, or as functions. In addition, -utilities such as @file{etags} and @file{make-docfile} recognize -definitions, and add appropriate information to tag tables and the -@file{DOC-@var{version}} file. @xref{Accessing Documentation}. - -@node Creating Symbols, Property Lists, Definitions, Symbols -@section Creating and Interning Symbols -@cindex reading symbols - - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. - -@cindex symbol name hashing -@cindex hashing -@cindex obarray -@cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. (The -same idea is used for general Emacs hash tables, but they are a -different data type; see @ref{Hash Tables}.) - -@cindex interning - If a symbol with the desired name is found, the reader uses that -symbol. If the obarray does not contain a symbol with that name, the -reader makes a new symbol and adds it to the obarray. Finding or adding -a symbol with a certain name is called @dfn{interning} it, and the -symbol is then called an @dfn{interned symbol}. - - Interning ensures that each obarray has just one symbol with any -particular name. Other like-named symbols may exist, but not in the -same obarray. Thus, the reader gets the same symbols for the same -names, as long as you keep reading with the same obarray. - - Interning usually happens automatically in the reader, but sometimes -other programs need to do it. For example, after the @kbd{M-x} command -obtains the command name as a string using the minibuffer, it then -interns the string, to get the interned symbol with that name. - -@cindex symbol equality -@cindex uninterned symbol - No obarray contains all symbols; in fact, some symbols are not in any -obarray. They are called @dfn{uninterned symbols}. An uninterned -symbol has the same four cells as other symbols; however, the only way -to gain access to it is by finding it in some other object or as the -value of a variable. - - Creating an uninterned symbol is useful in generating Lisp code, -because an uninterned symbol used as a variable in the code you generate -cannot clash with any variables used in other Lisp programs. - - In Emacs Lisp, an obarray is actually a vector. Each element of the -vector is a bucket; its value is either an interned symbol whose name -hashes to that bucket, or 0 if the bucket is empty. Each interned -symbol has an internal link (invisible to the user) to the next symbol -in the bucket. Because these links are invisible, there is no way to -find all the symbols in an obarray except using @code{mapatoms} (below). -The order of symbols in a bucket is not significant. - - In an empty obarray, every element is 0, so you can create an obarray -with @code{(make-vector @var{length} 0)}. @strong{This is the only -valid way to create an obarray.} Prime numbers as lengths tend -to result in good hashing; lengths one less than a power of two are also -good. - - @strong{Do not try to put symbols in an obarray yourself.} This does -not work---only @code{intern} can enter a symbol in an obarray properly. - -@cindex CL note---symbol in obarrays -@quotation -@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in -several obarrays. -@end quotation - - Most of the functions below take a name and sometimes an obarray as -arguments. A @code{wrong-type-argument} error is signaled if the name -is not a string, or if the obarray is not a vector. - -@defun symbol-name symbol -This function returns the string that is @var{symbol}'s name. For example: - -@example -@group -(symbol-name 'foo) - @result{} "foo" -@end group -@end example - -@strong{Warning:} Changing the string by substituting characters does -change the name of the symbol, but fails to update the obarray, so don't -do it! -@end defun - -@defun make-symbol name -This function returns a newly-allocated, uninterned symbol whose name is -@var{name} (which must be a string). Its value and function definition -are void, and its property list is @code{nil}. In the example below, -the value of @code{sym} is not @code{eq} to @code{foo} because it is a -distinct uninterned symbol whose name is also @samp{foo}. - -@example -(setq sym (make-symbol "foo")) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern name &optional obarray -This function returns the interned symbol whose name is @var{name}. If -there is no such symbol in the obarray @var{obarray}, @code{intern} -creates a new one, adds it to the obarray, and returns it. If -@var{obarray} is omitted, the value of the global variable -@code{obarray} is used. - -@example -(setq sym (intern "foo")) - @result{} foo -(eq sym 'foo) - @result{} t - -(setq sym1 (intern "foo" other-obarray)) - @result{} foo -(eq sym1 'foo) - @result{} nil -@end example -@end defun - -@cindex CL note---interning existing symbol -@quotation -@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol -in an obarray. In Emacs Lisp, you cannot do this, because the argument -to @code{intern} must be a string, not a symbol. -@end quotation - -@defun intern-soft name &optional obarray -This function returns the symbol in @var{obarray} whose name is -@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. -Therefore, you can use @code{intern-soft} to test whether a symbol with -a given name is already interned. If @var{obarray} is omitted, the -value of the global variable @code{obarray} is used. - -The argument @var{name} may also be a symbol; in that case, -the function returns @var{name} if @var{name} is interned -in the specified obarray, and otherwise @code{nil}. - -@smallexample -(intern-soft "frazzle") ; @r{No such symbol exists.} - @result{} nil -(make-symbol "frazzle") ; @r{Create an uninterned one.} - @result{} frazzle -@group -(intern-soft "frazzle") ; @r{That one cannot be found.} - @result{} nil -@end group -@group -(setq sym (intern "frazzle")) ; @r{Create an interned one.} - @result{} frazzle -@end group -@group -(intern-soft "frazzle") ; @r{That one can be found!} - @result{} frazzle -@end group -@group -(eq sym 'frazzle) ; @r{And it is the same one.} - @result{} t -@end group -@end smallexample -@end defun - -@defvar obarray -This variable is the standard obarray for use by @code{intern} and -@code{read}. -@end defvar - -@defun mapatoms function &optional obarray -@anchor{Definition of mapatoms} -This function calls @var{function} once with each symbol in the obarray -@var{obarray}. Then it returns @code{nil}. If @var{obarray} is -omitted, it defaults to the value of @code{obarray}, the standard -obarray for ordinary symbols. - -@smallexample -(setq count 0) - @result{} 0 -(defun count-syms (s) - (setq count (1+ count))) - @result{} count-syms -(mapatoms 'count-syms) - @result{} nil -count - @result{} 1871 -@end smallexample - -See @code{documentation} in @ref{Accessing Documentation}, for another -example using @code{mapatoms}. -@end defun - -@defun unintern symbol &optional obarray -This function deletes @var{symbol} from the obarray @var{obarray}. If -@code{symbol} is not actually in the obarray, @code{unintern} does -nothing. If @var{obarray} is @code{nil}, the current obarray is used. - -If you provide a string instead of a symbol as @var{symbol}, it stands -for a symbol name. Then @code{unintern} deletes the symbol (if any) in -the obarray which has that name. If there is no such symbol, -@code{unintern} does nothing. - -If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise -it returns @code{nil}. -@end defun - -@node Property Lists,, Creating Symbols, Symbols -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements. Each of the pairs associates a property name (usually a -symbol) with a property or value. - - Every symbol has a cell that stores a property list (@pxref{Symbol -Components}). This property list is used to record information about -the symbol, such as its variable documentation and the name of the -file where it was defined. - - Property lists can also be used in other contexts. For instance, -you can assign property lists to character positions in a string or -buffer. @xref{Text Properties}. - - The property names and values in a property list can be any Lisp -objects, but the names are usually symbols. Property list functions -compare the property names using @code{eq}. Here is an example of a -property list, found on the symbol @code{progn} when the compiler is -loaded: - -@example -(lisp-indent-function 0 byte-compile byte-compile-progn) -@end example - -@noindent -Here @code{lisp-indent-function} and @code{byte-compile} are property -names, and the other two elements are the corresponding values. - -@menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. -@end menu - -@node Plists and Alists -@subsection Property Lists and Association Lists -@cindex plist vs. alist -@cindex alist vs. plist - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant since the property names -must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If your -program keeps all of its associations in one association list, it will -typically need to search that entire list each time it checks for an -association. This could be slow. By contrast, if you keep the same -information in the property lists of the function names or variables -themselves, each search will scan only the length of one property list, -which is usually short. This is why the documentation for a variable is -recorded in a property named @code{variable-documentation}. The byte -compiler likewise uses properties to record those functions needing -special treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by beginning the property name with the program's usual -name-prefix for variables and functions.) An association list may be -used like a stack where associations are pushed on the front of the list -and later discarded; this is not possible with a property list. - -@node Symbol Plists -@subsection Property List Functions for Symbols - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. The return value is @var{plist}. - -@smallexample -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end smallexample - -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). -@end defun - -@defun get symbol property -This function finds the value of the property named @var{property} in -@var{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. - -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. - -See @code{put} for an example. -@end defun - -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under -the property name @var{property}, replacing any previous property value. -The @code{put} function returns @var{value}. - -@smallexample -(put 'fly 'verb 'transitive) - @result{}'transitive -(put 'fly 'noun '(a buzzing little bug)) - @result{} (a buzzing little bug) -(get 'fly 'verb) - @result{} transitive -(symbol-plist 'fly) - @result{} (verb transitive noun (a buzzing little bug)) -@end smallexample -@end defun - -@node Other Plists -@subsection Property Lists Outside Symbols - - These functions are useful for manipulating property lists -that are stored in places other than symbols: - -@defun plist-get plist property -This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} -argument. If @var{property} is not found in the @var{plist}, it -returns @code{nil}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'foo) - @result{} 4 -(plist-get '(foo 4 bad) 'bad) - @result{} @code{nil} -(plist-get '(foo 4 bad) 'bar) - @result{} nil -@end example -@end defun - -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, - -@example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (bar t foo 69 quux (a)) -@end example -@end defun - - You could define @code{put} in terms of @code{plist-put} as follows: - -@example -(defun put (symbol prop value) - (setplist symbol - (plist-put (symbol-plist symbol) prop value))) -@end example - -@defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. -@end defun - -@defun plist-member plist property -This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. -@end defun - -@ignore - arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce -@end ignore diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi deleted file mode 100644 index 5b7be7c8ffa..00000000000 --- a/doc/lispref/syntax.texi +++ /dev/null @@ -1,1196 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/syntax -@node Syntax Tables, Abbrevs, Searching and Matching, Top -@chapter Syntax Tables -@cindex parsing buffer text -@cindex syntax table -@cindex text parsing - - A @dfn{syntax table} specifies the syntactic textual function of each -character. This information is used by the @dfn{parsing functions}, the -complex movement commands, and others to determine where words, symbols, -and other syntactic constructs begin and end. The current syntax table -controls the meaning of the word motion functions (@pxref{Word Motion}) -and the list motion functions (@pxref{List Motion}), as well as the -functions in this chapter. - -@menu -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Desc: Syntax Descriptors. How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. -@end menu - -@node Syntax Basics -@section Syntax Table Concepts - -@ifnottex - A @dfn{syntax table} provides Emacs with the information that -determines the syntactic use of each character in a buffer. This -information is used by the parsing commands, the complex movement -commands, and others to determine where words, symbols, and other -syntactic constructs begin and end. The current syntax table controls -the meaning of the word motion functions (@pxref{Word Motion}) and the -list motion functions (@pxref{List Motion}) as well as the functions in -this chapter. -@end ifnottex - - A syntax table is a char-table (@pxref{Char-Tables}). The element at -index @var{c} describes the character with code @var{c}. The element's -value should be a list that encodes the syntax of the character in -question. - - Syntax tables are used only for moving across text, not for the Emacs -Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp -expressions, and these rules cannot be changed. (Some Lisp systems -provide ways to redefine the read syntax, but we decided to leave this -feature out of Emacs Lisp for simplicity.) - - Each buffer has its own major mode, and each major mode has its own -idea of the syntactic class of various characters. For example, in Lisp -mode, the character @samp{;} begins a comment, but in C mode, it -terminates a statement. To support these variations, Emacs makes the -choice of syntax table local to each buffer. Typically, each major -mode has its own syntax table and installs that table in each buffer -that uses that mode. Changing this table alters the syntax in all -those buffers as well as in any buffers subsequently put in that mode. -Occasionally several similar modes share one syntax table. -@xref{Example Major Modes}, for an example of how to set up a syntax -table. - -A syntax table can inherit the data for some characters from the -standard syntax table, while specifying other characters itself. The -``inherit'' syntax class means ``inherit this character's syntax from -the standard syntax table.'' Just changing the standard syntax for a -character affects all syntax tables that inherit from it. - -@defun syntax-table-p object -This function returns @code{t} if @var{object} is a syntax table. -@end defun - -@node Syntax Descriptors -@section Syntax Descriptors -@cindex syntax class - - This section describes the syntax classes and flags that denote the -syntax of a character, and how they are represented as a @dfn{syntax -descriptor}, which is a Lisp string that you pass to -@code{modify-syntax-entry} to specify the syntax you want. - - The syntax table specifies a syntax class for each character. There -is no necessary relationship between the class of a character in one -syntax table and its class in any other table. - - Each class is designated by a mnemonic character, which serves as the -name of the class when you need to specify a class. Usually the -designator character is one that is often assigned that class; however, -its meaning as a designator is unvarying and independent of what syntax -that character currently has. Thus, @samp{\} as a designator character -always gives ``escape character'' syntax, regardless of what syntax -@samp{\} currently has. - -@cindex syntax descriptor - A syntax descriptor is a Lisp string that specifies a syntax class, a -matching character (used only for the parenthesis classes) and flags. -The first character is the designator for a syntax class. The second -character is the character to match; if it is unused, put a space there. -Then come the characters for any desired flags. If no matching -character or flags are needed, one character is sufficient. - - For example, the syntax descriptor for the character @samp{*} in C -mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot -unused, second character of a comment-starter, first character of a -comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., -punctuation, matching character slot unused, first character of a -comment-starter, second character of a comment-ender). - -@menu -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. -@end menu - -@node Syntax Class Table -@subsection Table of Syntax Classes - - Here is a table of syntax classes, the characters that stand for them, -their meanings, and examples of their use. - -@deffn {Syntax class} @w{whitespace character} -@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-}) -separate symbols and words from each other. Typically, whitespace -characters have no other syntactic significance, and multiple whitespace -characters are syntactically equivalent to a single one. Space, tab, -newline and formfeed are classified as whitespace in almost all major -modes. -@end deffn - -@deffn {Syntax class} @w{word constituent} -@dfn{Word constituents} (designated by @samp{w}) are parts of words in -human languages, and are typically used in variable and command names -in programs. All upper- and lower-case letters, and the digits, are -typically word constituents. -@end deffn - -@deffn {Syntax class} @w{symbol constituent} -@dfn{Symbol constituents} (designated by @samp{_}) are the extra -characters that are used in variable and command names along with word -constituents. For example, the symbol constituents class is used in -Lisp mode to indicate that certain characters may be part of symbol -names even though they are not part of English words. These characters -are @samp{$&*+-_<>}. In standard C, the only non-word-constituent -character that is valid in symbols is underscore (@samp{_}). -@end deffn - -@deffn {Syntax class} @w{punctuation character} -@dfn{Punctuation characters} (designated by @samp{.}) are those -characters that are used as punctuation in English, or are used in some -way in a programming language to separate symbols from one another. -Some programming language modes, such as Emacs Lisp mode, have no -characters in this class since the few characters that are not symbol or -word constituents all have other uses. Other programming language modes, -such as C mode, use punctuation syntax for operators. -@end deffn - -@deffn {Syntax class} @w{open parenthesis character} -@deffnx {Syntax class} @w{close parenthesis character} -@cindex parenthesis syntax -Open and close @dfn{parenthesis characters} are characters used in -dissimilar pairs to surround sentences or expressions. Such a grouping -is begun with an open parenthesis character and terminated with a close. -Each open parenthesis character matches a particular close parenthesis -character, and vice versa. Normally, Emacs indicates momentarily the -matching open parenthesis when you insert a close parenthesis. -@xref{Blinking}. - -The class of open parentheses is designated by @samp{(}, and that of -close parentheses by @samp{)}. - -In English text, and in C code, the parenthesis pairs are @samp{()}, -@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and -vectors (@samp{()} and @samp{[]}) are classified as parenthesis -characters. -@end deffn - -@deffn {Syntax class} @w{string quote} -@dfn{String quote characters} (designated by @samp{"}) are used in -many languages, including Lisp and C, to delimit string constants. The -same string quote character appears at the beginning and the end of a -string. Such quoted strings do not nest. - -The parsing facilities of Emacs consider a string as a single token. -The usual syntactic meanings of the characters in the string are -suppressed. - -The Lisp modes have two string quote characters: double-quote (@samp{"}) -and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it -is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character -constants. - -English text has no string quote characters because English is not a -programming language. Although quotation marks are used in English, -we do not want them to turn off the usual syntactic properties of -other characters in the quotation. -@end deffn - -@deffn {Syntax class} @w{escape-syntax character} -An @dfn{escape character} (designated by @samp{\}) starts an escape -sequence such as is used in C string and character constants. The -character @samp{\} belongs to this class in both C and Lisp. (In C, it -is used thus only inside strings, but it turns out to cause no trouble -to treat it this way throughout C code.) - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. -@end deffn - -@deffn {Syntax class} @w{character quote} -A @dfn{character quote character} (designated by @samp{/}) quotes the -following character so that it loses its normal syntactic meaning. This -differs from an escape character in that only the character immediately -following is ever affected. - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -This class is used for backslash in @TeX{} mode. -@end deffn - -@deffn {Syntax class} @w{paired delimiter} -@dfn{Paired delimiter characters} (designated by @samp{$}) are like -string quote characters except that the syntactic properties of the -characters between the delimiters are not suppressed. Only @TeX{} mode -uses a paired delimiter presently---the @samp{$} that both enters and -leaves math mode. -@end deffn - -@deffn {Syntax class} @w{expression prefix} -An @dfn{expression prefix operator} (designated by @samp{'}) is used for -syntactic operators that are considered as part of an expression if they -appear next to one. In Lisp modes, these characters include the -apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in -macros), and @samp{#} (used in the read syntax for certain data types). -@end deffn - -@deffn {Syntax class} @w{comment starter} -@deffnx {Syntax class} @w{comment ender} -@cindex comment syntax -The @dfn{comment starter} and @dfn{comment ender} characters are used in -various languages to delimit comments. These classes are designated -by @samp{<} and @samp{>}, respectively. - -English text has no comment characters. In Lisp, the semicolon -(@samp{;}) starts a comment and a newline or formfeed ends one. -@end deffn - -@deffn {Syntax class} @w{inherit standard syntax} -This syntax class does not specify a particular syntax. It says to look -in the standard syntax table to find the syntax of this character. The -designator for this syntax class is @samp{@@}. -@end deffn - -@deffn {Syntax class} @w{generic comment delimiter} -A @dfn{generic comment delimiter} (designated by @samp{!}) starts -or ends a special kind of comment. @emph{Any} generic comment delimiter -matches @emph{any} generic comment delimiter, but they cannot match -a comment starter or comment ender; generic comment delimiters can only -match each other. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You can -mark any range of characters as forming a comment, by giving the first -and last characters of the range @code{syntax-table} properties -identifying them as generic comment delimiters. -@end deffn - -@deffn {Syntax class} @w{generic string delimiter} -A @dfn{generic string delimiter} (designated by @samp{|}) starts or ends -a string. This class differs from the string quote class in that @emph{any} -generic string delimiter can match any other generic string delimiter; but -they do not match ordinary string quote characters. - -This syntax class is primarily meant for use with the -@code{syntax-table} text property (@pxref{Syntax Properties}). You can -mark any range of characters as forming a string constant, by giving the -first and last characters of the range @code{syntax-table} properties -identifying them as generic string delimiters. -@end deffn - -@node Syntax Flags -@subsection Syntax Flags -@cindex syntax flags - - In addition to the classes, entries for characters in a syntax table -can specify flags. There are seven possible flags, represented by the -characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b}, @samp{n}, -and @samp{p}. - - All the flags except @samp{n} and @samp{p} are used to describe -multi-character comment delimiters. The digit flags indicate that a -character can @emph{also} be part of a comment sequence, in addition to -the syntactic properties associated with its character class. The flags -are independent of the class and each other for the sake of characters -such as @samp{*} in C mode, which is a punctuation character, @emph{and} -the second character of a start-of-comment sequence (@samp{/*}), -@emph{and} the first character of an end-of-comment sequence -(@samp{*/}). - - Here is a table of the possible flags for a character @var{c}, -and what they mean: - -@itemize @bullet -@item -@samp{1} means @var{c} is the start of a two-character comment-start -sequence. - -@item -@samp{2} means @var{c} is the second character of such a sequence. - -@item -@samp{3} means @var{c} is the start of a two-character comment-end -sequence. - -@item -@samp{4} means @var{c} is the second character of such a sequence. - -@item -@c Emacs 19 feature -@samp{b} means that @var{c} as a comment delimiter belongs to the -alternative ``b'' comment style. - -Emacs supports two comment styles simultaneously in any one syntax -table. This is for the sake of C++. Each style of comment syntax has -its own comment-start sequence and its own comment-end sequence. Each -comment must stick to one style or the other; thus, if it starts with -the comment-start sequence of style ``b,'' it must also end with the -comment-end sequence of style ``b.'' - -The two comment-start sequences must begin with the same character; only -the second character may differ. Mark the second character of the -``b''-style comment-start sequence with the @samp{b} flag. - -A comment-end sequence (one or two characters) applies to the ``b'' -style if its first character has the @samp{b} flag set; otherwise, it -applies to the ``a'' style. - -The appropriate comment syntax settings for C++ are as follows: - -@table @asis -@item @samp{/} -@samp{124b} -@item @samp{*} -@samp{23} -@item newline -@samp{>b} -@end table - -This defines four comment-delimiting sequences: - -@table @asis -@item @samp{/*} -This is a comment-start sequence for ``a'' style because the -second character, @samp{*}, does not have the @samp{b} flag. - -@item @samp{//} -This is a comment-start sequence for ``b'' style because the second -character, @samp{/}, does have the @samp{b} flag. - -@item @samp{*/} -This is a comment-end sequence for ``a'' style because the first -character, @samp{*}, does not have the @samp{b} flag. - -@item newline -This is a comment-end sequence for ``b'' style, because the newline -character has the @samp{b} flag. -@end table - -@item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. - -@item -@c Emacs 19 feature -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. -These characters are treated as whitespace when they appear between -expressions. When they appear within an expression, they are handled -according to their usual syntax classes. - -The function @code{backward-prefix-chars} moves back over these -characters, as well as over characters whose primary syntax class is -prefix (@samp{'}). @xref{Motion and Syntax}. -@end itemize - -@node Syntax Table Functions -@section Syntax Table Functions - - In this section we describe functions for creating, accessing and -altering syntax tables. - -@defun make-syntax-table &optional table -This function creates a new syntax table, with all values initialized -to @code{nil}. If @var{table} is non-@code{nil}, it becomes the -parent of the new syntax table, otherwise the standard syntax table is -the parent. Like all char-tables, a syntax table inherits from its -parent. Thus the original syntax of all characters in the returned -syntax table is determined by the parent. @xref{Char-Tables}. - -Most major mode syntax tables are created in this way. -@end defun - -@defun copy-syntax-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard syntax table. Otherwise, an error is signaled if @var{table} is -not a syntax table. -@end defun - -@deffn Command modify-syntax-entry char syntax-descriptor &optional table -This function sets the syntax entry for @var{char} according to -@var{syntax-descriptor}. @var{char} can be a character, or a cons -cell of the form @code{(@var{min} . @var{max})}; in the latter case, -the function sets the syntax entries for all characters in the range -between @var{min} and @var{max}, inclusive. - -The syntax is changed only for @var{table}, which defaults to the -current buffer's syntax table, and not in any other syntax table. The -argument @var{syntax-descriptor} specifies the desired syntax; this is -a string beginning with a class designator character, and optionally -containing a matching character and flags as well. @xref{Syntax -Descriptors}. - -This function always returns @code{nil}. The old syntax information in -the table for this character is discarded. - -An error is signaled if the first character of the syntax descriptor is not -one of the seventeen syntax class designator characters. An error is also -signaled if @var{char} is not a character. - -@example -@group -@exdent @r{Examples:} - -;; @r{Put the space character in class whitespace.} -(modify-syntax-entry ?\s " ") - @result{} nil -@end group - -@group -;; @r{Make @samp{$} an open parenthesis character,} -;; @r{with @samp{^} as its matching close.} -(modify-syntax-entry ?$ "(^") - @result{} nil -@end group - -@group -;; @r{Make @samp{^} a close parenthesis character,} -;; @r{with @samp{$} as its matching open.} -(modify-syntax-entry ?^ ")$") - @result{} nil -@end group - -@group -;; @r{Make @samp{/} a punctuation character,} -;; @r{the first character of a start-comment sequence,} -;; @r{and the second character of an end-comment sequence.} -;; @r{This is used in C mode.} -(modify-syntax-entry ?/ ". 14") - @result{} nil -@end group -@end example -@end deffn - -@defun char-syntax character -This function returns the syntax class of @var{character}, represented -by its mnemonic designator character. This returns @emph{only} the -class, not any matching parenthesis or flags. - -An error is signaled if @var{char} is not a character. - -The following examples apply to C mode. The first example shows that -the syntax class of space is whitespace (represented by a space). The -second example shows that the syntax of @samp{/} is punctuation. This -does not show the fact that it is also part of comment-start and -end -sequences. The third example shows that open parenthesis is in the class -of open parentheses. This does not show the fact that it has a matching -character, @samp{)}. - -@example -@group -(string (char-syntax ?\s)) - @result{} " " -@end group - -@group -(string (char-syntax ?/)) - @result{} "." -@end group - -@group -(string (char-syntax ?\()) - @result{} "(" -@end group -@end example - -We use @code{string} to make it easier to see the character returned by -@code{char-syntax}. -@end defun - -@defun set-syntax-table table -This function makes @var{table} the syntax table for the current buffer. -It returns @var{table}. -@end defun - -@defun syntax-table -This function returns the current syntax table, which is the table for -the current buffer. -@end defun - -@defmac with-syntax-table @var{table} @var{body}@dots{} -This macro executes @var{body} using @var{table} as the current syntax -table. It returns the value of the last form in @var{body}, after -restoring the old current syntax table. - -Since each buffer has its own current syntax table, we should make that -more precise: @code{with-syntax-table} temporarily alters the current -syntax table of whichever buffer is current at the time the macro -execution starts. Other buffers are not affected. -@end defmac - -@node Syntax Properties -@section Syntax Properties -@kindex syntax-table @r{(text property)} - -When the syntax table is not flexible enough to specify the syntax of -a language, you can use @code{syntax-table} text properties to -override the syntax table for specific character occurrences in the -buffer. @xref{Text Properties}. You can use Font Lock mode to set -@code{syntax-table} text properties. @xref{Setting Syntax -Properties}. - -The valid values of @code{syntax-table} text property are: - -@table @asis -@item @var{syntax-table} -If the property value is a syntax table, that table is used instead of -the current buffer's syntax table to determine the syntax for this -occurrence of the character. - -@item @code{(@var{syntax-code} . @var{matching-char})} -A cons cell of this format specifies the syntax for this -occurrence of the character. (@pxref{Syntax Table Internals}) - -@item @code{nil} -If the property is @code{nil}, the character's syntax is determined from -the current syntax table in the usual way. -@end table - -@defvar parse-sexp-lookup-properties -If this is non-@code{nil}, the syntax scanning functions pay attention -to syntax text properties. Otherwise they use only the current syntax -table. -@end defvar - -@node Motion and Syntax -@section Motion and Syntax - - This section describes functions for moving across characters that -have certain syntax classes. - -@defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax -classes mentioned in @var{syntaxes} (a string of syntax class -characters). It stops when it encounters the end of the buffer, or -position @var{limit} (if specified), or a character it is not supposed -to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value is the distance traveled, which is a nonnegative -integer. -@end defun - -@defun skip-syntax-backward syntaxes &optional limit -This function moves point backward across characters whose syntax -classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or -a character it is not supposed to skip. - -If @var{syntaxes} starts with @samp{^}, then the function skips -characters whose syntax is @emph{not} in @var{syntaxes}. - -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end defun - -@defun backward-prefix-chars -This function moves point backward over any number of characters with -expression prefix syntax. This includes both characters in the -expression prefix syntax class, and characters with the @samp{p} flag. -@end defun - -@node Parsing Expressions -@section Parsing Expressions - - This section describes functions for parsing and scanning balanced -expressions, also known as @dfn{sexps}. Basically, a sexp is either a -balanced parenthetical grouping, a string, or a symbol name (a -sequence of characters whose syntax is either word constituent or -symbol constituent). However, characters whose syntax is expression -prefix are treated as part of the sexp if they appear next to it. - - The syntax table controls the interpretation of characters, so these -functions can be used for Lisp expressions when in Lisp mode and for C -expressions when in C mode. @xref{List Motion}, for convenient -higher-level functions for moving over balanced expressions. - - A character's syntax controls how it changes the state of the -parser, rather than describing the state itself. For example, a -string delimiter character toggles the parser state between -``in-string'' and ``in-code,'' but the syntax of characters does not -directly say whether they are inside a string. For example (note that -15 is the syntax code for generic string delimiters), - -@example -(put-text-property 1 9 'syntax-table '(15 . nil)) -@end example - -@noindent -does not tell Emacs that the first eight chars of the current buffer -are a string, but rather that they are all string delimiters. As a -result, Emacs treats them as four consecutive empty string constants. - -@menu -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. -@end menu - -@node Motion via Parsing -@subsection Motion Commands Based on Parsing - - This section describes simple point-motion functions that operate -based on parsing expressions. - -@defun scan-lists from count depth -This function scans forward @var{count} balanced parenthetical groupings -from position @var{from}. It returns the position where the scan stops. -If @var{count} is negative, the scan moves backwards. - -If @var{depth} is nonzero, parenthesis depth counting begins from that -value. The only candidates for stopping are places where the depth in -parentheses becomes zero; @code{scan-lists} counts @var{count} such -places and then stops. Thus, a positive value for @var{depth} means go -out @var{depth} levels of parenthesis. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of the buffer (or its -accessible portion), and the depth is not zero, an error is signaled. -If the depth is zero but the count is not used up, @code{nil} is -returned. -@end defun - -@defun scan-sexps from count -This function scans forward @var{count} sexps from position @var{from}. -It returns the position where the scan stops. If @var{count} is -negative, the scan moves backwards. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of (the accessible part of) the -buffer while in the middle of a parenthetical grouping, an error is -signaled. If it reaches the beginning or end between groupings but -before count is used up, @code{nil} is returned. -@end defun - -@defun forward-comment count -This function moves point forward across @var{count} complete comments - (that is, including the starting delimiter and the terminating -delimiter if any), plus any whitespace encountered on the way. It -moves backward if @var{count} is negative. If it encounters anything -other than a comment or whitespace, it stops, leaving point at the -place where it stopped. This includes (for instance) finding the end -of a comment when moving forward and expecting the beginning of one. -The function also stops immediately after moving over the specified -number of complete comments. If @var{count} comments are found as -expected, with nothing except whitespace between them, it returns -@code{t}; otherwise it returns @code{nil}. - -This function cannot tell whether the ``comments'' it traverses are -embedded within a string. If they look like comments, it treats them -as comments. -@end defun - -To move forward over all comments and whitespace following point, use -@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good -argument to use, because the number of comments in the buffer cannot -exceed that many. - -@node Position Parse -@subsection Finding the Parse State for a Position - - For syntactic analysis, such as in indentation, often the useful -thing is to compute the syntactic state corresponding to a given buffer -position. This function does that conveniently. - -@defun syntax-ppss &optional pos -This function returns the parser state (see next section) that the -parser would reach at position @var{pos} starting from the beginning -of the buffer. This is equivalent to @code{(parse-partial-sexp -(point-min) @var{pos})}, except that @code{syntax-ppss} uses a cache -to speed up the computation. Due to this optimization, the 2nd value -(previous complete subexpression) and 6th value (minimum parenthesis -depth) of the returned parser state are not meaningful. -@end defun - - @code{syntax-ppss} automatically hooks itself to -@code{before-change-functions} to keep its cache consistent. But -updating can fail if @code{syntax-ppss} is called while -@code{before-change-functions} is temporarily let-bound, or if the -buffer is modified without obeying the hook, such as when using -@code{inhibit-modification-hooks}. For this reason, it is sometimes -necessary to flush the cache manually. - -@defun syntax-ppss-flush-cache beg &rest ignored-args -This function flushes the cache used by @code{syntax-ppss}, starting -at position @var{beg}. The remaining arguments, @var{ignored-args}, -are ignored; this function accepts them so that it can be directly -used on hooks such as @code{before-change-functions} (@pxref{Change -Hooks}). -@end defun - - Major modes can make @code{syntax-ppss} run faster by specifying -where it needs to start parsing. - -@defvar syntax-begin-function -If this is non-@code{nil}, it should be a function that moves to an -earlier buffer position where the parser state is equivalent to -@code{nil}---in other words, a position outside of any comment, -string, or parenthesis. @code{syntax-ppss} uses it to further -optimize its computations, when the cache gives no help. -@end defvar - -@node Parser State -@subsection Parser State -@cindex parser state - - A @dfn{parser state} is a list of ten elements describing the final -state of parsing text syntactically as part of an expression. The -parsing functions in the following sections return a parser state as -the value, and in some cases accept one as an argument also, so that -you can resume parsing after it stops. Here are the meanings of the -elements of the parser state: - -@enumerate 0 -@item -The depth in parentheses, counting from 0. @strong{Warning:} this can -be negative if there are more close parens than open parens between -the start of the defun and point. - -@item -@cindex innermost containing parentheses -The character position of the start of the innermost parenthetical -grouping containing the stopping point; @code{nil} if none. - -@item -@cindex previous complete subexpression -The character position of the start of the last complete subexpression -terminated; @code{nil} if none. - -@item -@cindex inside string -Non-@code{nil} if inside a string. More precisely, this is the -character that will terminate the string, or @code{t} if a generic -string delimiter character should terminate it. - -@item -@cindex inside comment -@code{t} if inside a comment (of either style), -or the comment nesting level if inside a kind of comment -that can be nested. - -@item -@cindex quote character -@code{t} if point is just after a quote character. - -@item -The minimum parenthesis depth encountered during this scan. - -@item -What kind of comment is active: @code{nil} for a comment of style -``a'' or when not inside a comment, @code{t} for a comment of style -``b,'' and @code{syntax-table} for a comment that should be ended by a -generic comment delimiter character. - -@item -The string or comment start position. While inside a comment, this is -the position where the comment began; while inside a string, this is the -position where the string began. When outside of strings and comments, -this element is @code{nil}. - -@item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. -@end enumerate - - Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements serve primarily to convey information -to the Lisp program which does the parsing. - - One additional piece of useful information is available from a -parser state using this function: - -@defun syntax-ppss-toplevel-pos state -This function extracts, from parser state @var{state}, the last -position scanned in the parse which was at top level in grammatical -structure. ``At top level'' means outside of any parentheses, -comments, or strings. - -The value is @code{nil} if @var{state} represents a parse which has -arrived at a top level position. -@end defun - - We have provided this access function rather than document how the -data is represented in the state, because we plan to change the -representation in the future. - -@node Low-Level Parsing -@subsection Low-Level Parsing - - The most basic way to use the expression parser is to tell it -to start at a given position with a certain state, and parse up to -a specified end position. - -@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment -This function parses a sexp in the current buffer starting at -@var{start}, not scanning past @var{limit}. It stops at position -@var{limit} or when certain criteria described below are met, and sets -point to the location where parsing stops. It returns a parser state -describing the status of the parse at the point where it stops. - -@cindex parenthesis depth -If the third argument @var{target-depth} is non-@code{nil}, parsing -stops if the depth in parentheses becomes equal to @var{target-depth}. -The depth starts at 0, or at whatever is given in @var{state}. - -If the fourth argument @var{stop-before} is non-@code{nil}, parsing -stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. - -If @var{state} is @code{nil}, @var{start} is assumed to be at the top -level of parenthesis structure, such as the beginning of a function -definition. Alternatively, you might wish to resume parsing in the -middle of the structure. To do this, you must provide a @var{state} -argument that describes the initial status of parsing. The value -returned by a previous call to @code{parse-partial-sexp} will do -nicely. -@end defun - -@node Control Parsing -@subsection Parameters to Control Parsing - -@defvar multibyte-syntax-as-symbol -If this variable is non-@code{nil}, @code{scan-sexps} treats all -non-@acronym{ASCII} characters as symbol constituents regardless -of what the syntax table says about them. (However, text properties -can still override the syntax.) -@end defvar - -@defopt parse-sexp-ignore-comments -@cindex skipping comments -If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}, -@code{scan-lists} and @code{scan-sexps}. -@end defopt - -@vindex parse-sexp-lookup-properties -The behavior of @code{parse-partial-sexp} is also affected by -@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). - -You can use @code{forward-comment} to move forward or backward over -one comment or several comments. - -@node Standard Syntax Tables -@section Some Standard Syntax Tables - - Most of the major modes in Emacs have their own syntax tables. Here -are several of them: - -@defun standard-syntax-table -This function returns the standard syntax table, which is the syntax -table used in Fundamental mode. -@end defun - -@defvar text-mode-syntax-table -The value of this variable is the syntax table used in Text mode. -@end defvar - -@defvar c-mode-syntax-table -The value of this variable is the syntax table for C-mode buffers. -@end defvar - -@defvar emacs-lisp-mode-syntax-table -The value of this variable is the syntax table used in Emacs Lisp mode -by editing commands. (It has no effect on the Lisp @code{read} -function.) -@end defvar - -@node Syntax Table Internals -@section Syntax Table Internals -@cindex syntax table internals - - Lisp programs don't usually work with the elements directly; the -Lisp-level syntax table functions usually work with syntax descriptors -(@pxref{Syntax Descriptors}). Nonetheless, here we document the -internal format. This format is used mostly when manipulating -syntax properties. - - Each element of a syntax table is a cons cell of the form -@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car}, -@var{syntax-code}, is an integer that encodes the syntax class, and any -flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if -a character to match was specified. - - This table gives the value of @var{syntax-code} which corresponds -to each syntactic type. - -@multitable @columnfractions .05 .3 .3 .31 -@item -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@tab -@i{Integer} @i{Class} -@item -@tab -0 @ @ whitespace -@tab -5 @ @ close parenthesis -@tab -10 @ @ character quote -@item -@tab -1 @ @ punctuation -@tab -6 @ @ expression prefix -@tab -11 @ @ comment-start -@item -@tab -2 @ @ word -@tab -7 @ @ string quote -@tab -12 @ @ comment-end -@item -@tab -3 @ @ symbol -@tab -8 @ @ paired delimiter -@tab -13 @ @ inherit -@item -@tab -4 @ @ open parenthesis -@tab -9 @ @ escape -@tab -14 @ @ generic comment -@item -@tab -15 @ generic string -@end multitable - - For example, the usual syntax value for @samp{(} is @code{(4 . 41)}. -(41 is the character code for @samp{)}.) - - The flags are encoded in higher order bits, starting 16 bits from the -least significant bit. This table gives the power of two which -corresponds to each syntax flag. - -@multitable @columnfractions .05 .3 .3 .3 -@item -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@tab -@i{Prefix} @i{Flag} -@item -@tab -@samp{1} @ @ @code{(lsh 1 16)} -@tab -@samp{4} @ @ @code{(lsh 1 19)} -@tab -@samp{b} @ @ @code{(lsh 1 21)} -@item -@tab -@samp{2} @ @ @code{(lsh 1 17)} -@tab -@samp{p} @ @ @code{(lsh 1 20)} -@tab -@samp{n} @ @ @code{(lsh 1 22)} -@item -@tab -@samp{3} @ @ @code{(lsh 1 18)} -@end multitable - -@defun string-to-syntax @var{desc} -This function returns the internal form corresponding to the syntax -descriptor @var{desc}, a cons cell @code{(@var{syntax-code} -. @var{matching-char})}. -@end defun - -@defun syntax-after pos -This function returns the syntax code of the character in the buffer -after position @var{pos}, taking account of syntax properties as well -as the syntax table. If @var{pos} is outside the buffer's accessible -portion (@pxref{Narrowing, accessible portion}), this function returns -@code{nil}. -@end defun - -@defun syntax-class syntax -This function returns the syntax class of the syntax code -@var{syntax}. (It masks off the high 16 bits that hold the flags -encoded in the syntax descriptor.) If @var{syntax} is @code{nil}, it -returns @code{nil}; this is so evaluating the expression - -@example -(syntax-class (syntax-after pos)) -@end example - -@noindent -where @code{pos} is outside the buffer's accessible portion, will -yield @code{nil} without throwing errors or producing wrong syntax -class codes. -@end defun - -@node Categories -@section Categories -@cindex categories of characters -@cindex character categories - - @dfn{Categories} provide an alternate way of classifying characters -syntactically. You can define several categories as needed, then -independently assign each character to one or more categories. Unlike -syntax classes, categories are not mutually exclusive; it is normal for -one character to belong to several categories. - -@cindex category table - Each buffer has a @dfn{category table} which records which categories -are defined and also which characters belong to each category. Each -category table defines its own categories, but normally these are -initialized by copying from the standard categories table, so that the -standard categories are available in all modes. - - Each category has a name, which is an @acronym{ASCII} printing character in -the range @w{@samp{ }} to @samp{~}. You specify the name of a category -when you define it with @code{define-category}. - - The category table is actually a char-table (@pxref{Char-Tables}). -The element of the category table at index @var{c} is a @dfn{category -set}---a bool-vector---that indicates which categories character @var{c} -belongs to. In this category set, if the element at index @var{cat} is -@code{t}, that means category @var{cat} is a member of the set, and that -character @var{c} belongs to category @var{cat}. - -For the next three functions, the optional argument @var{table} -defaults to the current buffer's category table. - -@defun define-category char docstring &optional table -This function defines a new category, with name @var{char} and -documentation @var{docstring}, for the category table @var{table}. -@end defun - -@defun category-docstring category &optional table -This function returns the documentation string of category @var{category} -in category table @var{table}. - -@example -(category-docstring ?a) - @result{} "ASCII" -(category-docstring ?l) - @result{} "Latin" -@end example -@end defun - -@defun get-unused-category &optional table -This function returns a category name (a character) which is not -currently defined in @var{table}. If all possible categories are in use -in @var{table}, it returns @code{nil}. -@end defun - -@defun category-table -This function returns the current buffer's category table. -@end defun - -@defun category-table-p object -This function returns @code{t} if @var{object} is a category table, -otherwise @code{nil}. -@end defun - -@defun standard-category-table -This function returns the standard category table. -@end defun - -@defun copy-category-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -standard category table. Otherwise, an error is signaled if @var{table} -is not a category table. -@end defun - -@defun set-category-table table -This function makes @var{table} the category table for the current -buffer. It returns @var{table}. -@end defun - -@defun make-category-table -This creates and returns an empty category table. In an empty category -table, no categories have been allocated, and no characters belong to -any categories. -@end defun - -@defun make-category-set categories -This function returns a new category set---a bool-vector---whose initial -contents are the categories listed in the string @var{categories}. The -elements of @var{categories} should be category names; the new category -set has @code{t} for each of those categories, and @code{nil} for all -other categories. - -@example -(make-category-set "al") - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun char-category-set char -This function returns the category set for character @var{char} in the -current buffer's category table. This is the bool-vector which -records which categories the character @var{char} belongs to. The -function @code{char-category-set} does not allocate storage, because -it returns the same bool-vector that exists in the category table. - -@example -(char-category-set ?a) - @result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0" -@end example -@end defun - -@defun category-set-mnemonics category-set -This function converts the category set @var{category-set} into a string -containing the characters that designate the categories that are members -of the set. - -@example -(category-set-mnemonics (char-category-set ?a)) - @result{} "al" -@end example -@end defun - -@defun modify-category-entry char category &optional table reset -This function modifies the category set of @var{char} in category -table @var{table} (which defaults to the current buffer's category -table). @var{char} can be a character, or a cons cell of the form -@code{(@var{min} . @var{max})}; in the latter case, the function -modifies the category sets of all characters in the range between -@var{min} and @var{max}, inclusive. - -Normally, it modifies a category set by adding @var{category} to it. -But if @var{reset} is non-@code{nil}, then it deletes @var{category} -instead. -@end defun - -@deffn Command describe-categories &optional buffer-or-name -This function describes the category specifications in the current -category table. It inserts the descriptions in a buffer, and then -displays that buffer. If @var{buffer-or-name} is non-@code{nil}, it -describes the category table of that buffer instead. -@end deffn - -@ignore - arch-tag: 4d914e96-0283-445c-9233-75d33662908c -@end ignore diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi deleted file mode 100644 index 5c2a3ce99c7..00000000000 --- a/doc/lispref/text.texi +++ /dev/null @@ -1,4276 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/text -@node Text, Non-ASCII Characters, Markers, Top -@chapter Text -@cindex text - - This chapter describes the functions that deal with the text in a -buffer. Most examine, insert, or delete text in the current buffer, -often operating at point or on text adjacent to point. Many are -interactive. All the functions that change the text provide for undoing -the changes (@pxref{Undo}). - - Many text-related functions operate on a region of text defined by two -buffer positions passed in arguments named @var{start} and @var{end}. -These arguments should be either markers (@pxref{Markers}) or numeric -character positions (@pxref{Positions}). The order of these arguments -does not matter; it is all right for @var{start} to be the end of the -region and @var{end} the beginning. For example, @code{(delete-region 1 -10)} and @code{(delete-region 10 1)} are equivalent. An -@code{args-out-of-range} error is signaled if either @var{start} or -@var{end} is outside the accessible portion of the buffer. In an -interactive call, point and the mark are used for these arguments. - -@cindex buffer contents - Throughout this chapter, ``text'' refers to the characters in the -buffer, together with their properties (when relevant). Keep in mind -that point is always between two characters, and the cursor appears on -the character after point. - -@menu -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing the text or - position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. -@end menu - -@node Near Point -@section Examining Text Near Point -@cindex text near point - - Many functions are provided to look at the characters around point. -Several simple functions are described here. See also @code{looking-at} -in @ref{Regexp Search}. - -In the following four functions, ``beginning'' or ``end'' of buffer -refers to the beginning or end of the accessible portion. - -@defun char-after &optional position -This function returns the character in the current buffer at (i.e., -immediately after) position @var{position}. If @var{position} is out of -range for this purpose, either before the beginning of the buffer, or at -or beyond the end, then the value is @code{nil}. The default for -@var{position} is point. - -In the following example, assume that the first character in the -buffer is @samp{@@}: - -@example -@group -(char-to-string (char-after 1)) - @result{} "@@" -@end group -@end example -@end defun - -@defun char-before &optional position -This function returns the character in the current buffer immediately -before position @var{position}. If @var{position} is out of range for -this purpose, either at or before the beginning of the buffer, or beyond -the end, then the value is @code{nil}. The default for -@var{position} is point. -@end defun - -@defun following-char -This function returns the character following point in the current -buffer. This is similar to @code{(char-after (point))}. However, if -point is at the end of the buffer, then @code{following-char} returns 0. - -Remember that point is always between characters, and the cursor -normally appears over the character following point. Therefore, the -character returned by @code{following-char} is the character the -cursor is over. - -In this example, point is between the @samp{a} and the @samp{c}. - -@example -@group ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- -@end group - -@group -(char-to-string (preceding-char)) - @result{} "a" -(char-to-string (following-char)) - @result{} "c" -@end group -@end example -@end defun - -@defun preceding-char -This function returns the character preceding point in the current -buffer. See above, under @code{following-char}, for an example. If -point is at the beginning of the buffer, @code{preceding-char} returns -0. -@end defun - -@defun bobp -This function returns @code{t} if point is at the beginning of the -buffer. If narrowing is in effect, this means the beginning of the -accessible portion of the text. See also @code{point-min} in -@ref{Point}. -@end defun - -@defun eobp -This function returns @code{t} if point is at the end of the buffer. -If narrowing is in effect, this means the end of accessible portion of -the text. See also @code{point-max} in @xref{Point}. -@end defun - -@defun bolp -This function returns @code{t} if point is at the beginning of a line. -@xref{Text Lines}. The beginning of the buffer (or of its accessible -portion) always counts as the beginning of a line. -@end defun - -@defun eolp -This function returns @code{t} if point is at the end of a line. The -end of the buffer (or of its accessible portion) is always considered -the end of a line. -@end defun - -@node Buffer Contents -@section Examining Buffer Contents - - This section describes functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. - -@defun buffer-substring start end -This function returns a string containing a copy of the text of the -region defined by positions @var{start} and @var{end} in the current -buffer. If the arguments are not positions in the accessible portion of -the buffer, @code{buffer-substring} signals an @code{args-out-of-range} -error. - -It is not necessary for @var{start} to be less than @var{end}; the -arguments can be given in either order. But most often the smaller -argument is written first. - -Here's an example which assumes Font-Lock mode is not enabled: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- -@end group - -@group -(buffer-substring 1 10) - @result{} "This is t" -@end group -@group -(buffer-substring (point-max) 10) - @result{} "he contents of buffer foo\n" -@end group -@end example - -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. - -For example, if Font-Lock mode is enabled, you might get results like -these: - -@example -@group -(buffer-substring 1 10) - @result{} #("This is t" 0 1 (fontified t) 1 9 (fontified t)) -@end group -@end example -@end defun - -@defun buffer-substring-no-properties start end -This is like @code{buffer-substring}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun filter-buffer-substring start end &optional delete noprops -This function passes the buffer text between @var{start} and @var{end} -through the filter functions specified by the variable -@code{buffer-substring-filters}, and returns the value from the last -filter function. If @code{buffer-substring-filters} is @code{nil}, -the value is the unaltered text from the buffer, what -@code{buffer-substring} would return. - -If @var{delete} is non-@code{nil}, this function deletes the text -between @var{start} and @var{end} after copying it, like -@code{delete-and-extract-region}. - -If @var{noprops} is non-@code{nil}, the final string returned does not -include text properties, while the string passed through the filters -still includes text properties from the buffer text. - -Lisp code should use this function instead of @code{buffer-substring}, -@code{buffer-substring-no-properties}, -or @code{delete-and-extract-region} when copying into user-accessible -data structures such as the kill-ring, X clipboard, and registers. -Major and minor modes can add functions to -@code{buffer-substring-filters} to alter such text as it is copied out -of the buffer. -@end defun - -@defvar buffer-substring-filters -This variable should be a list of functions that accept a single -argument, a string, and return a string. -@code{filter-buffer-substring} passes the buffer substring to the -first function in this list, and the return value of each function is -passed to the next function. The return value of the last function is -used as the return value of @code{filter-buffer-substring}. - -As a special convention, point is set to the start of the buffer text -being operated on (i.e., the @var{start} argument for -@code{filter-buffer-substring}) before these functions are called. - -If this variable is @code{nil}, no filtering is performed. -@end defvar - -@defun buffer-string -This function returns the contents of the entire accessible portion of -the current buffer as a string. It is equivalent to - -@example -(buffer-substring (point-min) (point-max)) -@end example - -@example -@group ----------- Buffer: foo ---------- -This is the contents of buffer foo - ----------- Buffer: foo ---------- - -(buffer-string) - @result{} "This is the contents of buffer foo\n" -@end group -@end example -@end defun - -@defun current-word &optional strict really-word -This function returns the symbol (or word) at or near point, as a string. -The return value includes no text properties. - -If the optional argument @var{really-word} is non-@code{nil}, it finds a -word; otherwise, it finds a symbol (which includes both word -characters and symbol constituent characters). - -If the optional argument @var{strict} is non-@code{nil}, then point -must be in or next to the symbol or word---if no symbol or word is -there, the function returns @code{nil}. Otherwise, a nearby symbol or -word on the same line is acceptable. -@end defun - -@defun thing-at-point thing -Return the @var{thing} around or next to point, as a string. - -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. - -@example ----------- Buffer: foo ---------- -Gentlemen may cry ``Pea@point{}ce! Peace!,'' -but there is no peace. ----------- Buffer: foo ---------- - -(thing-at-point 'word) - @result{} "Peace" -(thing-at-point 'line) - @result{} "Gentlemen may cry ``Peace! Peace!,''\n" -(thing-at-point 'whitespace) - @result{} nil -@end example -@end defun - -@node Comparing Text -@section Comparing Text -@cindex comparing buffer text - - This function lets you compare portions of the text in a buffer, without -copying them into strings first. - -@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 -This function lets you compare two substrings of the same buffer or two -different buffers. The first three arguments specify one substring, -giving a buffer (or a buffer name) and two positions within the -buffer. The last three arguments specify the other substring in the -same way. You can use @code{nil} for @var{buffer1}, @var{buffer2}, or -both to stand for the current buffer. - -The value is negative if the first substring is less, positive if the -first is greater, and zero if they are equal. The absolute value of -the result is one plus the index of the first differing characters -within the substrings. - -This function ignores case when comparing characters -if @code{case-fold-search} is non-@code{nil}. It always ignores -text properties. - -Suppose the current buffer contains the text @samp{foobarbar -haha!rara!}; then in this example the two substrings are @samp{rbar } -and @samp{rara!}. The value is 2 because the first substring is greater -at the second character. - -@example -(compare-buffer-substrings nil 6 11 nil 16 21) - @result{} 2 -@end example -@end defun - -@node Insertion -@section Inserting Text -@cindex insertion of text -@cindex text insertion - -@cindex insertion before point -@cindex before point, insertion - @dfn{Insertion} means adding new text to a buffer. The inserted text -goes at point---between the character before point and the character -after point. Some insertion functions leave point before the inserted -text, while other functions leave it after. We call the former -insertion @dfn{after point} and the latter insertion @dfn{before point}. - - Insertion relocates markers that point at positions after the -insertion point, so that they stay with the surrounding text -(@pxref{Markers}). When a marker points at the place of insertion, -insertion may or may not relocate the marker, depending on the marker's -insertion type (@pxref{Marker Insertion Types}). Certain special -functions such as @code{insert-before-markers} relocate all such markers -to point after the inserted text, regardless of the markers' insertion -type. - - Insertion functions signal an error if the current buffer is -read-only or if they insert within read-only text. - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - - The insertion functions convert text from unibyte to multibyte in -order to insert in a multibyte buffer, and vice versa---if the text -comes from a string or from a buffer. However, they do not convert -unibyte character codes 128 through 255 to multibyte characters, not -even if the current buffer is a multibyte buffer. @xref{Converting -Representations}. - -@defun insert &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. In other words, it -inserts the text before point. An error is signaled unless all -@var{args} are either strings or characters. The value is @code{nil}. -@end defun - -@defun insert-before-markers &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. An error is signaled -unless all @var{args} are either strings or characters. The value is -@code{nil}. - -This function is unlike the other insertion functions in that it -relocates markers initially pointing at the insertion point, to point -after the inserted text. If an overlay begins at the insertion point, -the inserted text falls outside the overlay; if a nonempty overlay -ends at the insertion point, the inserted text falls inside that -overlay. -@end defun - -@defun insert-char character count &optional inherit -This function inserts @var{count} instances of @var{character} into the -current buffer before point. The argument @var{count} should be an -integer, and @var{character} must be a character. The value is @code{nil}. - -This function does not convert unibyte character codes 128 through 255 -to multibyte characters, not even if the current buffer is a multibyte -buffer. @xref{Converting Representations}. - -If @var{inherit} is non-@code{nil}, then the inserted characters inherit -sticky text properties from the two characters before and after the -insertion point. @xref{Sticky Properties}. -@end defun - -@defun insert-buffer-substring from-buffer-or-name &optional start end -This function inserts a portion of buffer @var{from-buffer-or-name} -(which must already exist) into the current buffer before point. The -text inserted is the region between @var{start} and @var{end}. (These -arguments default to the beginning and end of the accessible portion of -that buffer.) This function returns @code{nil}. - -In this example, the form is executed with buffer @samp{bar} as the -current buffer. We assume that buffer @samp{bar} is initially empty. - -@example -@group ----------- Buffer: foo ---------- -We hold these truths to be self-evident, that all ----------- Buffer: foo ---------- -@end group - -@group -(insert-buffer-substring "foo" 1 20) - @result{} nil - ----------- Buffer: bar ---------- -We hold these truth@point{} ----------- Buffer: bar ---------- -@end group -@end example -@end defun - -@defun insert-buffer-substring-no-properties from-buffer-or-name &optional start end -This is like @code{insert-buffer-substring} except that it does not -copy any text properties. -@end defun - - @xref{Sticky Properties}, for other insertion functions that inherit -text properties from the nearby text in addition to inserting it. -Whitespace inserted by indentation functions also inherits text -properties. - -@node Commands for Insertion -@section User-Level Insertion Commands - - This section describes higher-level commands for inserting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command insert-buffer from-buffer-or-name -This command inserts the entire accessible contents of -@var{from-buffer-or-name} (which must exist) into the current buffer -after point. It leaves the mark after the inserted text. The value -is @code{nil}. -@end deffn - -@deffn Command self-insert-command count -@cindex character insertion -@cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. - -In an interactive call, @var{count} is the numeric prefix argument. - -Self-insertion translates the input character through -@code{translation-table-for-input}. @xref{Translation of Characters}. - -This command calls @code{auto-fill-function} whenever that is -non-@code{nil} and the character inserted is in the table -@code{auto-fill-chars} (@pxref{Auto Filling}). - -@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 -This command performs abbrev expansion if Abbrev mode is enabled and -the inserted character does not have word-constituent -syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) It is also -responsible for calling @code{blink-paren-function} when the inserted -character has close parenthesis syntax (@pxref{Blinking}). - -Do not try substituting your own definition of -@code{self-insert-command} for the standard one. The editor command -loop handles this function specially. -@end deffn - -@deffn Command newline &optional number-of-newlines -This command inserts newlines into the current buffer before point. -If @var{number-of-newlines} is supplied, that many newline characters -are inserted. - -@cindex newline and Auto Fill mode -This function calls @code{auto-fill-function} if the current column -number is greater than the value of @code{fill-column} and -@var{number-of-newlines} is @code{nil}. Typically what -@code{auto-fill-function} does is insert a newline; thus, the overall -result in this case is to insert two newlines at different places: one -at point, and another earlier in the line. @code{newline} does not -auto-fill if @var{number-of-newlines} is non-@code{nil}. - -This command indents to the left margin if that is not zero. -@xref{Margins}. - -The value returned is @code{nil}. In an interactive call, @var{count} -is the numeric prefix argument. -@end deffn - -@defvar overwrite-mode -This variable controls whether overwrite mode is in effect. The value -should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, -or @code{nil}. @code{overwrite-mode-textual} specifies textual -overwrite mode (treats newlines and tabs specially), and -@code{overwrite-mode-binary} specifies binary overwrite mode (treats -newlines and tabs like any other characters). -@end defvar - -@node Deletion -@section Deleting Text -@cindex text deletion - -@cindex deleting text vs killing - Deletion means removing part of the text in a buffer, without saving -it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be -yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). -Some deletion functions do save text in the kill ring in some special -cases. - - All of the deletion functions operate on the current buffer. - -@deffn Command erase-buffer -This function deletes the entire text of the current buffer -(@emph{not} just the accessible portion), leaving it -empty. If the buffer is read-only, it signals a @code{buffer-read-only} -error; if some of the text in it is read-only, it signals a -@code{text-read-only} error. Otherwise, it deletes the text without -asking for any confirmation. It returns @code{nil}. - -Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk.'' However, -@code{erase-buffer} does not do this, the idea being that the future -text is not really related to the former text, and its size should not -be compared with that of the former text. -@end deffn - -@deffn Command delete-region start end -This command deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns @code{nil}. If point was -inside the deleted region, its value afterward is @var{start}. -Otherwise, point relocates with the surrounding text, as markers do. -@end deffn - -@defun delete-and-extract-region start end -This function deletes the text between positions @var{start} and -@var{end} in the current buffer, and returns a string containing the -text just deleted. - -If point was inside the deleted region, its value afterward is -@var{start}. Otherwise, point relocates with the surrounding text, as -markers do. -@end defun - -@deffn Command delete-char count &optional killp -This command deletes @var{count} characters directly after point, or -before point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command delete-backward-char count &optional killp -@cindex deleting previous char -This command deletes @var{count} characters directly before point, or -after point if @var{count} is negative. If @var{killp} is -non-@code{nil}, then it saves the deleted characters in the kill ring. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@deffn Command backward-delete-char-untabify count &optional killp -@cindex tab deletion -This command deletes @var{count} characters backward, changing tabs -into spaces. When the next character to be deleted is a tab, it is -first replaced with the proper number of spaces to preserve alignment -and then one of those spaces is deleted instead of the tab. If -@var{killp} is non-@code{nil}, then the command saves the deleted -characters in the kill ring. - -Conversion of tabs to spaces happens only if @var{count} is positive. -If it is negative, exactly @minus{}@var{count} characters after point -are deleted. - -In an interactive call, @var{count} is the numeric prefix argument, and -@var{killp} is the unprocessed prefix argument. Therefore, if a prefix -argument is supplied, the text is saved in the kill ring. If no prefix -argument is supplied, then one character is deleted, but not saved in -the kill ring. - -The value returned is always @code{nil}. -@end deffn - -@defopt backward-delete-char-untabify-method -This option specifies how @code{backward-delete-char-untabify} should -deal with whitespace. Possible values include @code{untabify}, the -default, meaning convert a tab to many spaces and delete one; -@code{hungry}, meaning delete all tabs and spaces before point with -one command; @code{all} meaning delete all tabs, spaces and newlines -before point, and @code{nil}, meaning do nothing special for -whitespace characters. -@end defopt - -@node User-Level Deletion -@section User-Level Deletion Commands - - This section describes higher-level commands for deleting text, -commands intended primarily for the user but useful also in Lisp -programs. - -@deffn Command delete-horizontal-space &optional backward-only -@cindex deleting whitespace -This function deletes all spaces and tabs around point. It returns -@code{nil}. - -If @var{backward-only} is non-@code{nil}, the function deletes -spaces and tabs before point, but not after point. - -In the following examples, we call @code{delete-horizontal-space} four -times, once on each line, with point between the second and third -characters on the line each time. - -@example -@group ----------- Buffer: foo ---------- -I @point{}thought -I @point{} thought -We@point{} thought -Yo@point{}u thought ----------- Buffer: foo ---------- -@end group - -@group -(delete-horizontal-space) ; @r{Four times.} - @result{} nil - ----------- Buffer: foo ---------- -Ithought -Ithought -Wethought -You thought ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command delete-indentation &optional join-following-p -This function joins the line point is on to the previous line, deleting -any whitespace at the join and in some cases replacing it with one -space. If @var{join-following-p} is non-@code{nil}, -@code{delete-indentation} joins this line to the following line -instead. The function returns @code{nil}. - -If there is a fill prefix, and the second of the lines being joined -starts with the prefix, then @code{delete-indentation} deletes the -fill prefix before joining the lines. @xref{Margins}. - -In the example below, point is located on the line starting -@samp{events}, and it makes no difference if there are trailing spaces -in the preceding line. - -@smallexample -@group ----------- Buffer: foo ---------- -When in the course of human -@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group - -(delete-indentation) - @result{} nil - -@group ----------- Buffer: foo ---------- -When in the course of human@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group -@end smallexample - -After the lines are joined, the function @code{fixup-whitespace} is -responsible for deciding whether to leave a space at the junction. -@end deffn - -@deffn Command fixup-whitespace -This function replaces all the horizontal whitespace surrounding point -with either one space or no space, according to the context. It -returns @code{nil}. - -At the beginning or end of a line, the appropriate amount of space is -none. Before a character with close parenthesis syntax, or after a -character with open parenthesis or expression-prefix syntax, no space is -also appropriate. Otherwise, one space is appropriate. @xref{Syntax -Class Table}. - -In the example below, @code{fixup-whitespace} is called the first time -with point before the word @samp{spaces} in the first line. For the -second invocation, point is directly after the @samp{(}. - -@smallexample -@group ----------- Buffer: foo ---------- -This has too many @point{}spaces -This has too many spaces at the start of (@point{} this list) ----------- Buffer: foo ---------- -@end group - -@group -(fixup-whitespace) - @result{} nil -(fixup-whitespace) - @result{} nil -@end group - -@group ----------- Buffer: foo ---------- -This has too many spaces -This has too many spaces at the start of (this list) ----------- Buffer: foo ---------- -@end group -@end smallexample -@end deffn - -@deffn Command just-one-space &optional n -@comment !!SourceFile simple.el -This command replaces any spaces and tabs around point with a single -space, or @var{n} spaces if @var{n} is specified. It returns -@code{nil}. -@end deffn - -@deffn Command delete-blank-lines -This function deletes blank lines surrounding point. If point is on a -blank line with one or more blank lines before or after it, then all but -one of them are deleted. If point is on an isolated blank line, then it -is deleted. If point is on a nonblank line, the command deletes all -blank lines immediately following it. - -A blank line is defined as a line containing only tabs and spaces. - -@code{delete-blank-lines} returns @code{nil}. -@end deffn - -@node The Kill Ring -@section The Kill Ring -@cindex kill ring - - @dfn{Kill functions} delete text like the deletion functions, but save -it so that the user can reinsert it by @dfn{yanking}. Most of these -functions have @samp{kill-} in their name. By contrast, the functions -whose names start with @samp{delete-} normally do not save text for -yanking (though they can still be undone); these are ``deletion'' -functions. - - Most of the kill commands are primarily for interactive use, and are -not described here. What we do describe are the functions provided for -use in writing such commands. You can use these functions to write -commands for killing text. When you need to delete text for internal -purposes within a Lisp function, you should normally use deletion -functions, so as not to disturb the kill ring contents. -@xref{Deletion}. - - Killed text is saved for later yanking in the @dfn{kill ring}. This -is a list that holds a number of recent kills, not just the last text -kill. We call this a ``ring'' because yanking treats it as having -elements in a cyclic order. The list is kept in the variable -@code{kill-ring}, and can be operated on with the usual functions for -lists; there are also specialized functions, described in this section, -that treat it as a ring. - - Some people think this use of the word ``kill'' is unfortunate, since -it refers to operations that specifically @emph{do not} destroy the -entities ``killed.'' This is in sharp contrast to ordinary life, in -which death is permanent and ``killed'' entities do not come back to -life. Therefore, other metaphors have been proposed. For example, the -term ``cut ring'' makes sense to people who, in pre-computer days, used -scissors and paste to cut up and rearrange manuscripts. However, it -would be difficult to change the terminology now. - -@menu -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. -@end menu - -@node Kill Ring Concepts -@comment node-name, next, previous, up -@subsection Kill Ring Concepts - - The kill ring records killed text as strings in a list, most recent -first. A short kill ring, for example, might look like this: - -@example -("some text" "a different piece of text" "even older text") -@end example - -@noindent -When the list reaches @code{kill-ring-max} entries in length, adding a -new entry automatically deletes the last entry. - - When kill commands are interwoven with other commands, each kill -command makes a new entry in the kill ring. Multiple kill commands in -succession build up a single kill ring entry, which would be yanked as a -unit; the second and subsequent consecutive kill commands add text to -the entry made by the first one. - - For yanking, one entry in the kill ring is designated the ``front'' of -the ring. Some yank commands ``rotate'' the ring by designating a -different element as the ``front.'' But this virtual rotation doesn't -change the list itself---the most recent entry always comes first in the -list. - -@node Kill Functions -@comment node-name, next, previous, up -@subsection Functions for Killing - - @code{kill-region} is the usual subroutine for killing text. Any -command that calls this function is a ``kill command'' (and should -probably have @samp{kill} in its name). @code{kill-region} puts the -newly killed text in a new element at the beginning of the kill ring or -adds it to the most recent element. It determines automatically (using -@code{last-command}) whether the previous command was a kill command, -and if so appends the killed text to the most recent entry. - -@deffn Command kill-region start end &optional yank-handler -This function kills the text in the region defined by @var{start} and -@var{end}. The text is deleted but saved in the kill ring, along with -its text properties. The value is always @code{nil}. - -In an interactive call, @var{start} and @var{end} are point and -the mark. - -@c Emacs 19 feature -If the buffer or text is read-only, @code{kill-region} modifies the kill -ring just the same, then signals an error without modifying the buffer. -This is convenient because it lets the user use a series of kill -commands to copy text from a read-only buffer into the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} text property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, any -@code{yank-handler} properties present on the killed text are copied -onto the kill ring, like other text properties. -@end deffn - -@defopt kill-read-only-ok -If this option is non-@code{nil}, @code{kill-region} does not signal an -error if the buffer or text is read-only. Instead, it simply returns, -updating the kill ring but not changing the buffer. -@end defopt - -@deffn Command copy-region-as-kill start end -This command saves the region defined by @var{start} and @var{end} on -the kill ring (including text properties), but does not delete the text -from the buffer. It returns @code{nil}. - -The command does not set @code{this-command} to @code{kill-region}, so a -subsequent kill command does not append to the same kill ring entry. - -Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to -support Emacs 18. For newer Emacs versions, it is better to use -@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill -Ring}. -@end deffn - -@node Yanking -@subsection Yanking - - Yanking means inserting text from the kill ring, but it does -not insert the text blindly. Yank commands and some other commands -use @code{insert-for-yank} to perform special processing on the -text that they copy into the buffer. - -@defun insert-for-yank string -This function normally works like @code{insert} except that it doesn't -insert the text properties in the @code{yank-excluded-properties} -list. However, if any part of @var{string} has a non-@code{nil} -@code{yank-handler} text property, that property can do various -special processing on that part of the text being inserted. -@end defun - -@defun insert-buffer-substring-as-yank buf &optional start end -This function resembles @code{insert-buffer-substring} except that it -doesn't insert the text properties in the -@code{yank-excluded-properties} list. -@end defun - - You can put a @code{yank-handler} text property on all or part of -the text to control how it will be inserted if it is yanked. The -@code{insert-for-yank} function looks for that property. The property -value must be a list of one to four elements, with the following -format (where elements after the first may be omitted): - -@example -(@var{function} @var{param} @var{noexclude} @var{undo}) -@end example - - Here is what the elements do: - -@table @var -@item function -When @var{function} is present and non-@code{nil}, it is called instead of -@code{insert} to insert the string. @var{function} takes one -argument---the string to insert. - -@item param -If @var{param} is present and non-@code{nil}, it replaces @var{string} -(or the part of @var{string} being processed) as the object passed to -@var{function} (or @code{insert}); for example, if @var{function} is -@code{yank-rectangle}, @var{param} should be a list of strings to -insert as a rectangle. - -@item noexclude -If @var{noexclude} is present and non-@code{nil}, the normal removal of the -yank-excluded-properties is not performed; instead @var{function} is -responsible for removing those properties. This may be necessary -if @var{function} adjusts point before or after inserting the object. - -@item undo -If @var{undo} is present and non-@code{nil}, it is a function that will be -called by @code{yank-pop} to undo the insertion of the current object. -It is called with two arguments, the start and end of the current -region. @var{function} can set @code{yank-undo-function} to override -the @var{undo} value. -@end table - -@node Yank Commands -@comment node-name, next, previous, up -@subsection Functions for Yanking - - This section describes higher-level commands for yanking, which are -intended primarily for the user but useful also in Lisp programs. -Both @code{yank} and @code{yank-pop} honor the -@code{yank-excluded-properties} variable and @code{yank-handler} text -property (@pxref{Yanking}). - -@deffn Command yank &optional arg -@cindex inserting killed text -This command inserts before point the text at the front of the kill -ring. It sets the mark at the beginning of that text, using -@code{push-mark} (@pxref{The Mark}), and puts point at the end. - -If @var{arg} is a non-@code{nil} list (which occurs interactively when -the user types @kbd{C-u} with no digits), then @code{yank} inserts the -text as described above, but puts point before the yanked text and -sets the mark after it. - -If @var{arg} is a number, then @code{yank} inserts the @var{arg}th -most recently killed text---the @var{arg}th element of the kill ring -list, counted cyclically from the front, which is considered the -first element for this purpose. - -@code{yank} does not alter the contents of the kill ring, unless it -used text provided by another program, in which case it pushes that text -onto the kill ring. However if @var{arg} is an integer different from -one, it rotates the kill ring to place the yanked string at the front. - -@code{yank} returns @code{nil}. -@end deffn - -@deffn Command yank-pop &optional arg -This command replaces the just-yanked entry from the kill ring with a -different entry from the kill ring. - -This is allowed only immediately after a @code{yank} or another -@code{yank-pop}. At such a time, the region contains text that was just -inserted by yanking. @code{yank-pop} deletes that text and inserts in -its place a different piece of killed text. It does not add the deleted -text to the kill ring, since it is already in the kill ring somewhere. -It does however rotate the kill ring to place the newly yanked string at -the front. - -If @var{arg} is @code{nil}, then the replacement text is the previous -element of the kill ring. If @var{arg} is numeric, the replacement is -the @var{arg}th previous kill. If @var{arg} is negative, a more recent -kill is the replacement. - -The sequence of kills in the kill ring wraps around, so that after the -oldest one comes the newest one, and before the newest one goes the -oldest. - -The return value is always @code{nil}. -@end deffn - -@defvar yank-undo-function -If this variable is non-@code{nil}, the function @code{yank-pop} uses -its value instead of @code{delete-region} to delete the text -inserted by the previous @code{yank} or -@code{yank-pop} command. The value must be a function of two -arguments, the start and end of the current region. - -The function @code{insert-for-yank} automatically sets this variable -according to the @var{undo} element of the @code{yank-handler} -text property, if there is one. -@end defvar - -@node Low-Level Kill Ring -@subsection Low-Level Kill Ring - - These functions and variables provide access to the kill ring at a -lower level, but still convenient for use in Lisp programs, because they -take care of interaction with window system selections -(@pxref{Window System Selections}). - -@defun current-kill n &optional do-not-move -The function @code{current-kill} rotates the yanking pointer, which -designates the ``front'' of the kill ring, by @var{n} places (from newer -kills to older ones), and returns the text at that place in the ring. - -If the optional second argument @var{do-not-move} is non-@code{nil}, -then @code{current-kill} doesn't alter the yanking pointer; it just -returns the @var{n}th kill, counting from the current yanking pointer. - -If @var{n} is zero, indicating a request for the latest kill, -@code{current-kill} calls the value of -@code{interprogram-paste-function} (documented below) before -consulting the kill ring. If that value is a function and calling it -returns a string or a list of several string, @code{current-kill} -pushes the strings onto the kill ring and returns the first string. -It also sets the yanking pointer to point to the kill-ring entry of -the first string returned by @code{interprogram-paste-function}, -regardless of the value of @var{do-not-move}. Otherwise, -@code{current-kill} does not treat a zero value for @var{n} specially: -it returns the entry pointed at by the yanking pointer and does not -move the yanking pointer. -@end defun - -@defun kill-new string &optional replace yank-handler -This function pushes the text @var{string} onto the kill ring and -makes the yanking pointer point to it. It discards the oldest entry -if appropriate. It also invokes the value of -@code{interprogram-cut-function} (see below). - -If @var{replace} is non-@code{nil}, then @code{kill-new} replaces the -first element of the kill ring with @var{string}, rather than pushing -@var{string} onto the kill ring. - -If @var{yank-handler} is non-@code{nil}, this puts that value onto -the string of killed text, as a @code{yank-handler} property. -@xref{Yanking}. Note that if @var{yank-handler} is @code{nil}, then -@code{kill-new} copies any @code{yank-handler} properties present on -@var{string} onto the kill ring, as it does with other text properties. -@end defun - -@defun kill-append string before-p &optional yank-handler -This function appends the text @var{string} to the first entry in the -kill ring and makes the yanking pointer point to the combined entry. -Normally @var{string} goes at the end of the entry, but if -@var{before-p} is non-@code{nil}, it goes at the beginning. This -function also invokes the value of @code{interprogram-cut-function} -(see below). This handles @var{yank-handler} just like -@code{kill-new}, except that if @var{yank-handler} is different from -the @code{yank-handler} property of the first entry of the kill ring, -@code{kill-append} pushes the concatenated string onto the kill ring, -instead of replacing the original first entry with it. -@end defun - -@defvar interprogram-paste-function -This variable provides a way of transferring killed text from other -programs, when you are using a window system. Its value should be -@code{nil} or a function of no arguments. - -If the value is a function, @code{current-kill} calls it to get the -``most recent kill.'' If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill.'' If it returns -@code{nil}, then the front of the kill ring is used. - -To facilitate support for window systems that support multiple -selections, this function may also return a list of strings. In that -case, the first string is used as the ``most recent kill'', and all -the other strings are pushed onto the kill ring, for easy access by -@code{yank-pop}. - -The normal use of this function is to get the window system's primary -selection as the most recent kill, even if the selection belongs to -another application. @xref{Window System Selections}. However, if -the selection was provided by the current Emacs session, this function -should return @code{nil}. (If it is hard to tell whether Emacs or -some other program provided the selection, it should be good enough to -use @code{string=} to compare it with the last text Emacs provided.) -@end defvar - -@defvar interprogram-cut-function -This variable provides a way of communicating killed text to other -programs, when you are using a window system. Its value should be -@code{nil} or a function of one required and one optional argument. - -If the value is a function, @code{kill-new} and @code{kill-append} call -it with the new first element of the kill ring as the first argument. -The second, optional, argument has the same meaning as the @var{push} -argument to @code{x-set-cut-buffer} (@pxref{Definition of -x-set-cut-buffer}) and only affects the second and later cut buffers. - -The normal use of this function is to set the window system's primary -selection (and first cut buffer) from the newly killed text. -@xref{Window System Selections}. -@end defvar - -@node Internals of Kill Ring -@comment node-name, next, previous, up -@subsection Internals of the Kill Ring - - The variable @code{kill-ring} holds the kill ring contents, in the -form of a list of strings. The most recent kill is always at the front -of the list. - - The @code{kill-ring-yank-pointer} variable points to a link in the -kill ring list, whose @sc{car} is the text to yank next. We say it -identifies the ``front'' of the ring. Moving -@code{kill-ring-yank-pointer} to a different link is called -@dfn{rotating the kill ring}. We call the kill ring a ``ring'' because -the functions that move the yank pointer wrap around from the end of the -list to the beginning, or vice-versa. Rotation of the kill ring is -virtual; it does not change the value of @code{kill-ring}. - - Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp -variables whose values are normally lists. The word ``pointer'' in the -name of the @code{kill-ring-yank-pointer} indicates that the variable's -purpose is to identify one element of the list for use by the next yank -command. - - The value of @code{kill-ring-yank-pointer} is always @code{eq} to one -of the links in the kill ring list. The element it identifies is the -@sc{car} of that link. Kill commands, which change the kill ring, also -set this variable to the value of @code{kill-ring}. The effect is to -rotate the ring so that the newly killed text is at the front. - - Here is a diagram that shows the variable @code{kill-ring-yank-pointer} -pointing to the second entry in the kill ring @code{("some text" "a -different piece of text" "yet older text")}. - -@example -@group -kill-ring ---- kill-ring-yank-pointer - | | - | v - | --- --- --- --- --- --- - --> | | |------> | | |--> | | |--> nil - --- --- --- --- --- --- - | | | - | | | - | | -->"yet older text" - | | - | --> "a different piece of text" - | - --> "some text" -@end group -@end example - -@noindent -This state of affairs might occur after @kbd{C-y} (@code{yank}) -immediately followed by @kbd{M-y} (@code{yank-pop}). - -@defvar kill-ring -This variable holds the list of killed text sequences, most recently -killed first. -@end defvar - -@defvar kill-ring-yank-pointer -This variable's value indicates which element of the kill ring is at the -``front'' of the ring for yanking. More precisely, the value is a tail -of the value of @code{kill-ring}, and its @sc{car} is the kill string -that @kbd{C-y} should yank. -@end defvar - -@defopt kill-ring-max -The value of this variable is the maximum length to which the kill -ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. -@end defopt - -@node Undo -@comment node-name, next, previous, up -@section Undo -@cindex redo - - Most buffers have an @dfn{undo list}, which records all changes made -to the buffer's text so that they can be undone. (The buffers that -don't have one are usually special-purpose buffers for which Emacs -assumes that undoing is not useful. In particular, any buffer whose -name begins with a space has its undo recording off by default; -see @ref{Buffer Names}.) All the primitives that modify the -text in the buffer automatically add elements to the front of the undo -list, which is in the variable @code{buffer-undo-list}. - -@defvar buffer-undo-list -This buffer-local variable's value is the undo list of the current -buffer. A value of @code{t} disables the recording of undo information. -@end defvar - -Here are the kinds of elements an undo list can have: - -@table @code -@item @var{position} -This kind of element records a previous value of point; undoing this -element moves point to @var{position}. Ordinary cursor motion does not -make any sort of undo record, but deletion operations use these entries -to record where point was before the command. - -@item (@var{beg} . @var{end}) -This kind of element indicates how to delete text that was inserted. -Upon insertion, the text occupied the range @var{beg}--@var{end} in the -buffer. - -@item (@var{text} . @var{position}) -This kind of element indicates how to reinsert text that was deleted. -The deleted text itself is the string @var{text}. The place to -reinsert it is @code{(abs @var{position})}. If @var{position} is -positive, point was at the beginning of the deleted text, otherwise it -was at the end. - -@item (t @var{high} . @var{low}) -This kind of element indicates that an unmodified buffer became -modified. The elements @var{high} and @var{low} are two integers, each -recording 16 bits of the visited file's modification time as of when it -was previously visited or saved. @code{primitive-undo} uses those -values to determine whether to mark the buffer as unmodified once again; -it does so only if the file's modification time matches those numbers. - -@item (nil @var{property} @var{value} @var{beg} . @var{end}) -This kind of element records a change in a text property. -Here's how you might undo the change: - -@example -(put-text-property @var{beg} @var{end} @var{property} @var{value}) -@end example - -@item (@var{marker} . @var{adjustment}) -This kind of element records the fact that the marker @var{marker} was -relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. Undoing this element moves -@var{marker} @minus{} @var{adjustment} characters. - -@item (apply @var{funname} . @var{args}) -This is an extensible undo item, which is undone by calling -@var{funname} with arguments @var{args}. - -@item (apply @var{delta} @var{beg} @var{end} @var{funname} . @var{args}) -This is an extensible undo item, which records a change limited to the -range @var{beg} to @var{end}, which increased the size of the buffer -by @var{delta}. It is undone by calling @var{funname} with arguments -@var{args}. - -This kind of element enables undo limited to a region to determine -whether the element pertains to that region. - -@item nil -This element is a boundary. The elements between two boundaries are -called a @dfn{change group}; normally, each change group corresponds to -one keyboard command, and undo commands normally undo an entire group as -a unit. -@end table - -@defun undo-boundary -This function places a boundary element in the undo list. The undo -command stops at such a boundary, and successive undo commands undo -to earlier and earlier boundaries. This function returns @code{nil}. - -The editor command loop automatically creates an undo boundary before -each key sequence is executed. Thus, each undo normally undoes the -effects of one command. Self-inserting input characters are an -exception. The command loop makes a boundary for the first such -character; the next 19 consecutive self-inserting input characters do -not make boundaries, and then the 20th does, and so on as long as -self-inserting characters continue. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This is to ensure that -each command makes a boundary in each buffer where it makes changes. - -Calling this function explicitly is useful for splitting the effects of -a command into more than one unit. For example, @code{query-replace} -calls @code{undo-boundary} after each replacement, so that the user can -undo individual replacements one by one. -@end defun - -@defvar undo-in-progress -This variable is normally @code{nil}, but the undo commands bind it to -@code{t}. This is so that various kinds of change hooks can tell when -they're being called for the sake of undoing. -@end defvar - -@defun primitive-undo count list -This is the basic function for undoing elements of an undo list. -It undoes the first @var{count} elements of @var{list}, returning -the rest of @var{list}. - -@code{primitive-undo} adds elements to the buffer's undo list when it -changes the buffer. Undo commands avoid confusion by saving the undo -list value at the beginning of a sequence of undo operations. Then the -undo operations use and update the saved value. The new elements added -by undoing are not part of this saved value, so they don't interfere with -continuing to undo. - -This function does not bind @code{undo-in-progress}. -@end defun - -@node Maintaining Undo -@section Maintaining Undo Lists - - This section describes how to enable and disable undo information for -a given buffer. It also explains how the undo list is truncated -automatically so it doesn't get too big. - - Recording of undo information in a newly created buffer is normally -enabled to start with; but if the buffer name starts with a space, the -undo recording is initially disabled. You can explicitly enable or -disable undo recording with the following two functions, or by setting -@code{buffer-undo-list} yourself. - -@deffn Command buffer-enable-undo &optional buffer-or-name -This command enables recording undo information for buffer -@var{buffer-or-name}, so that subsequent changes can be undone. If no -argument is supplied, then the current buffer is used. This function -does nothing if undo recording is already enabled in the buffer. It -returns @code{nil}. - -In an interactive call, @var{buffer-or-name} is the current buffer. -You cannot specify any other buffer. -@end deffn - -@deffn Command buffer-disable-undo &optional buffer-or-name -@cindex disabling undo -This function discards the undo list of @var{buffer-or-name}, and disables -further recording of undo information. As a result, it is no longer -possible to undo either previous changes or any subsequent changes. If -the undo list of @var{buffer-or-name} is already disabled, this function -has no effect. - -This function returns @code{nil}. -@end deffn - - As editing continues, undo lists get longer and longer. To prevent -them from using up all available memory space, garbage collection trims -them back to size limits you can set. (For this purpose, the ``size'' -of an undo list measures the cons cells that make up the list, plus the -strings of deleted text.) Three variables control the range of acceptable -sizes: @code{undo-limit}, @code{undo-strong-limit} and -@code{undo-outer-limit}. In these variables, size is counted as the -number of bytes occupied, which includes both saved text and other -data. - -@defopt undo-limit -This is the soft limit for the acceptable size of an undo list. The -change group at which this size is exceeded is the last one kept. -@end defopt - -@defopt undo-strong-limit -This is the upper limit for the acceptable size of an undo list. The -change group at which this size is exceeded is discarded itself (along -with all older change groups). There is one exception: the very latest -change group is only discarded if it exceeds @code{undo-outer-limit}. -@end defopt - -@defopt undo-outer-limit -If at garbage collection time the undo info for the current command -exceeds this limit, Emacs discards the info and displays a warning. -This is a last ditch limit to prevent memory overflow. -@end defopt - -@defopt undo-ask-before-discard -If this variable is non-@code{nil}, when the undo info exceeds -@code{undo-outer-limit}, Emacs asks in the echo area whether to -discard the info. The default value is @code{nil}, which means to -discard it automatically. - -This option is mainly intended for debugging. Garbage collection is -inhibited while the question is asked, which means that Emacs might -leak memory if the user waits too long before answering the question. -@end defopt - -@node Filling -@comment node-name, next, previous, up -@section Filling -@cindex filling text - - @dfn{Filling} means adjusting the lengths of lines (by moving the line -breaks) so that they are nearly (but no greater than) a specified -maximum width. Additionally, lines can be @dfn{justified}, which means -inserting spaces to make the left and/or right margins line up -precisely. The width is controlled by the variable @code{fill-column}. -For ease of reading, lines should be no longer than 70 or so columns. - - You can use Auto Fill mode (@pxref{Auto Filling}) to fill text -automatically as you insert it, but changes to existing text may leave -it improperly filled. Then you must fill the text explicitly. - - Most of the commands in this section return values that are not -meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style -(@pxref{Margins}). If the current justification style is -@code{none}, the filling functions don't actually do anything. - - Several of the filling functions have an argument @var{justify}. -If it is non-@code{nil}, that requests some kind of justification. It -can be @code{left}, @code{right}, @code{full}, or @code{center}, to -request a specific style of justification. If it is @code{t}, that -means to use the current justification style for this part of the text -(see @code{current-justification}, below). Any other value is treated -as @code{full}. - - When you call the filling functions interactively, using a prefix -argument implies the value @code{full} for @var{justify}. - -@deffn Command fill-paragraph &optional justify region -This command fills the paragraph at or after point. If -@var{justify} is non-@code{nil}, each line is justified as well. -It uses the ordinary paragraph motion commands to find paragraph -boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}. - -When @var{region} is non-@code{nil}, then if Transient Mark mode is -enabled and the mark is active, this command calls @code{fill-region} -to fill all the paragraphs in the region, instead of filling only the -current paragraph. When this command is called interactively, -@var{region} is @code{t}. -@end deffn - -@deffn Command fill-region start end &optional justify nosqueeze to-eop -This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify} is -non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{to-eop} is non-@code{nil}, -that means to keep filling to the end of the paragraph---or the next hard -newline, if @code{use-hard-newlines} is enabled (see below). - -The variable @code{paragraph-separate} controls how to distinguish -paragraphs. @xref{Standard Regexps}. -@end deffn - -@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp -This command fills each paragraph in the region according to its -individual fill prefix. Thus, if the lines of a paragraph were indented -with spaces, the filled paragraph will remain indented in the same -fashion. - -The first two arguments, @var{start} and @var{end}, are the beginning -and end of the region to be filled. The third and fourth arguments, -@var{justify} and @var{citation-regexp}, are optional. If -@var{justify} is non-@code{nil}, the paragraphs are justified as -well as filled. If @var{citation-regexp} is non-@code{nil}, it means the -function is operating on a mail message and therefore should not fill -the header lines. If @var{citation-regexp} is a string, it is used as -a regular expression; if it matches the beginning of a line, that line -is treated as a citation marker. - -Ordinarily, @code{fill-individual-paragraphs} regards each change in -indentation as starting a new paragraph. If -@code{fill-individual-varying-indent} is non-@code{nil}, then only -separator lines separate paragraphs. That mode can handle indented -paragraphs with additional indentation on the first line. -@end deffn - -@defopt fill-individual-varying-indent -This variable alters the action of @code{fill-individual-paragraphs} as -described above. -@end defopt - -@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after -This command considers a region of text as a single paragraph and fills -it. If the region was made up of many paragraphs, the blank lines -between paragraphs are removed. This function justifies as well as -filling when @var{justify} is non-@code{nil}. - -If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace -other than line breaks untouched. If @var{squeeze-after} is -non-@code{nil}, it specifies a position in the region, and means don't -canonicalize spaces before that position. - -In Adaptive Fill mode, this command calls @code{fill-context-prefix} to -choose a fill prefix by default. @xref{Adaptive Fill}. -@end deffn - -@deffn Command justify-current-line &optional how eop nosqueeze -This command inserts spaces between the words of the current line so -that the line ends exactly at @code{fill-column}. It returns -@code{nil}. - -The argument @var{how}, if non-@code{nil} specifies explicitly the style -of justification. It can be @code{left}, @code{right}, @code{full}, -@code{center}, or @code{none}. If it is @code{t}, that means to do -follow specified justification style (see @code{current-justification}, -below). @code{nil} means to do full justification. - -If @var{eop} is non-@code{nil}, that means do only left-justification -if @code{current-justification} specifies full justification. This is -used for the last line of a paragraph; even if the paragraph as a -whole is fully justified, the last line should not be. - -If @var{nosqueeze} is non-@code{nil}, that means do not change interior -whitespace. -@end deffn - -@defopt default-justification -This variable's value specifies the style of justification to use for -text that doesn't specify a style with a text property. The possible -values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. The default value is @code{left}. -@end defopt - -@defun current-justification -This function returns the proper justification style to use for filling -the text around point. - -This returns the value of the @code{justification} text property at -point, or the variable @var{default-justification} if there is no such -text property. However, it returns @code{nil} rather than @code{none} -to mean ``don't justify''. -@end defun - -@defopt sentence-end-double-space -@anchor{Definition of sentence-end-double-space} -If this variable is non-@code{nil}, a period followed by just one space -does not count as the end of a sentence, and the filling functions -avoid breaking the line at such a place. -@end defopt - -@defopt sentence-end-without-period -If this variable is non-@code{nil}, a sentence can end without a -period. This is used for languages like Thai, where sentences end -with a double space but without a period. -@end defopt - -@defopt sentence-end-without-space -If this variable is non-@code{nil}, it should be a string of -characters that can end a sentence without following spaces. -@end defopt - -@defvar fill-paragraph-function -This variable provides a way to override the filling of paragraphs. -If its value is non-@code{nil}, @code{fill-paragraph} calls this -function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - -@defvar fill-forward-paragraph-function -This variable provides a way to override how the filling functions, -such as @code{fill-region} and @code{fill-paragraph}, move forward to -the next paragraph. Its value should be a function, which is called -with a single argument @var{n}, the number of paragraphs to move, and -should return the difference between @var{n} and the number of -paragraphs actually moved. The default value of this variable is -@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs -Manual}. -@end defvar - -@defvar use-hard-newlines -If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. -@end defvar - -@node Margins -@section Margins for Filling - -@defopt fill-prefix -This buffer-local variable, if non-@code{nil}, specifies a string of -text that appears at the beginning of normal text lines and should be -disregarded when filling them. Any line that fails to start with the -fill prefix is considered the start of a paragraph; so is any line -that starts with the fill prefix followed by additional whitespace. -Lines that start with the fill prefix but no additional whitespace are -ordinary text lines that can be filled together. The resulting filled -lines also start with the fill prefix. - -The fill prefix follows the left margin whitespace, if any. -@end defopt - -@defopt fill-column -This buffer-local variable specifies the maximum width of filled lines. -Its value should be an integer, which is a number of columns. All the -filling, justification, and centering commands are affected by this -variable, including Auto Fill mode (@pxref{Auto Filling}). - -As a practical matter, if you are writing text for other people to -read, you should set @code{fill-column} to no more than 70. Otherwise -the line will be too long for people to read comfortably, and this can -make the text seem clumsy. -@end defopt - -@defvar default-fill-column -The value of this variable is the default value for @code{fill-column} in -buffers that do not override it. This is the same as -@code{(default-value 'fill-column)}. - -The default value for @code{default-fill-column} is 70. -@end defvar - -@deffn Command set-left-margin from to margin -This sets the @code{left-margin} property on the text from @var{from} to -@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this -command also refills the region to fit the new margin. -@end deffn - -@deffn Command set-right-margin from to margin -This sets the @code{right-margin} property on the text from @var{from} -to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, -this command also refills the region to fit the new margin. -@end deffn - -@defun current-left-margin -This function returns the proper left margin value to use for filling -the text around point. The value is the sum of the @code{left-margin} -property of the character at the start of the current line (or zero if -none), and the value of the variable @code{left-margin}. -@end defun - -@defun current-fill-column -This function returns the proper fill column value to use for filling -the text around point. The value is the value of the @code{fill-column} -variable, minus the value of the @code{right-margin} property of the -character after point. -@end defun - -@deffn Command move-to-left-margin &optional n force -This function moves point to the left margin of the current line. The -column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, -@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. - -If @var{force} is non-@code{nil}, that says to fix the line's -indentation if that doesn't match the left margin value. -@end deffn - -@defun delete-to-left-margin &optional from to -This function removes left margin indentation from the text between -@var{from} and @var{to}. The amount of indentation to delete is -determined by calling @code{current-left-margin}. In no case does this -function delete non-whitespace. If @var{from} and @var{to} are omitted, -they default to the whole buffer. -@end defun - -@defun indent-to-left-margin -This function adjusts the indentation at the beginning of the current -line to the value specified by the variable @code{left-margin}. (That -may involve either inserting or deleting whitespace.) This function -is value of @code{indent-line-function} in Paragraph-Indent Text mode. -@end defun - -@defopt left-margin -This variable specifies the base left margin column. In Fundamental -mode, @kbd{C-j} indents to this column. This variable automatically -becomes buffer-local when set in any fashion. -@end defopt - -@defopt fill-nobreak-predicate -This variable gives major modes a way to specify not to break a line -at certain places. Its value should be a list of functions. Whenever -filling considers breaking the line at a certain place in the buffer, -it calls each of these functions with no arguments and with point -located at that place. If any of the functions returns -non-@code{nil}, then the line won't be broken there. -@end defopt - -@node Adaptive Fill -@section Adaptive Fill Mode -@c @cindex Adaptive Fill mode "adaptive-fill-mode" is adjacent. - - When @dfn{Adaptive Fill Mode} is enabled, Emacs determines the fill -prefix automatically from the text in each paragraph being filled -rather than using a predetermined value. During filling, this fill -prefix gets inserted at the start of the second and subsequent lines -of the paragraph as described in @ref{Filling}, and in @ref{Auto -Filling}. - -@defopt adaptive-fill-mode -Adaptive Fill mode is enabled when this variable is non-@code{nil}. -It is @code{t} by default. -@end defopt - -@defun fill-context-prefix from to -This function implements the heart of Adaptive Fill mode; it chooses a -fill prefix based on the text between @var{from} and @var{to}, -typically the start and end of a paragraph. It does this by looking -at the first two lines of the paragraph, based on the variables -described below. -@c The optional argument first-line-regexp is not documented -@c because it exists for internal purposes and might be eliminated -@c in the future. - -Usually, this function returns the fill prefix, a string. However, -before doing this, the function makes a final check (not specially -mentioned in the following) that a line starting with this prefix -wouldn't look like the start of a paragraph. Should this happen, the -function signals the anomaly by returning @code{nil} instead. - -In detail, @code{fill-context-prefix} does this: - -@enumerate -@item -It takes a candidate for the fill prefix from the first line---it -tries first the function in @code{adaptive-fill-function} (if any), -then the regular expression @code{adaptive-fill-regexp} (see below). -The first non-@code{nil} result of these, or the empty string if -they're both @code{nil}, becomes the first line's candidate. -@item -If the paragraph has as yet only one line, the function tests the -validity of the prefix candidate just found. The function then -returns the candidate if it's valid, or a string of spaces otherwise. -(see the description of @code{adaptive-fill-first-line-regexp} below). -@item -When the paragraph already has two lines, the function next looks for -a prefix candidate on the second line, in just the same way it did for -the first line. If it doesn't find one, it returns @code{nil}. -@item -The function now compares the two candidate prefixes heuristically: if -the non-whitespace characters in the line 2 candidate occur in the -same order in the line 1 candidate, the function returns the line 2 -candidate. Otherwise, it returns the largest initial substring which -is common to both candidates (which might be the empty string). -@end enumerate -@end defun - -@defopt adaptive-fill-regexp -Adaptive Fill mode matches this regular expression against the text -starting after the left margin whitespace (if any) on a line; the -characters it matches are that line's candidate for the fill prefix. - -The default value matches whitespace with certain punctuation -characters intermingled. -@end defopt - -@defopt adaptive-fill-first-line-regexp -Used only in one-line paragraphs, this regular expression acts as an -additional check of the validity of the one available candidate fill -prefix: the candidate must match this regular expression, or match -@code{comment-start-skip}. If it doesn't, @code{fill-context-prefix} -replaces the candidate with a string of spaces ``of the same width'' -as it. - -The default value of this variable is @w{@code{"\\`[ \t]*\\'"}}, which -matches only a string of whitespace. The effect of this default is to -force the fill prefixes found in one-line paragraphs always to be pure -whitespace. -@end defopt - -@defopt adaptive-fill-function -You can specify more complex ways of choosing a fill prefix -automatically by setting this variable to a function. The function is -called with point after the left margin (if any) of a line, and it -must preserve point. It should return either ``that line's'' fill -prefix or @code{nil}, meaning it has failed to determine a prefix. -@end defopt - -@node Auto Filling -@comment node-name, next, previous, up -@section Auto Filling -@cindex filling, automatic -@cindex Auto Fill mode - - Auto Fill mode is a minor mode that fills lines automatically as text -is inserted. This section describes the hook used by Auto Fill mode. -For a description of functions that you can call explicitly to fill and -justify existing text, see @ref{Filling}. - - Auto Fill mode also enables the functions that change the margins and -justification style to refill portions of the text. @xref{Margins}. - -@defvar auto-fill-function -The value of this buffer-local variable should be a function (of no -arguments) to be called after self-inserting a character from the table -@code{auto-fill-chars}. It may be @code{nil}, in which case nothing -special is done in that case. - -The value of @code{auto-fill-function} is @code{do-auto-fill} when -Auto-Fill mode is enabled. That is a function whose sole purpose is to -implement the usual strategy for breaking a line. - -@quotation -In older Emacs versions, this variable was named @code{auto-fill-hook}, -but since it is not called with the standard convention for hooks, it -was renamed to @code{auto-fill-function} in version 19. -@end quotation -@end defvar - -@defvar normal-auto-fill-function -This variable specifies the function to use for -@code{auto-fill-function}, if and when Auto Fill is turned on. Major -modes can set buffer-local values for this variable to alter how Auto -Fill works. -@end defvar - -@defvar auto-fill-chars -A char table of characters which invoke @code{auto-fill-function} when -self-inserted---space and newline in most language environments. They -have an entry @code{t} in the table. -@end defvar - -@node Sorting -@section Sorting Text -@cindex sorting text - - The sorting functions described in this section all rearrange text in -a buffer. This is in contrast to the function @code{sort}, which -rearranges the order of the elements of a list (@pxref{Rearrangement}). -The values returned by these functions are not meaningful. - -@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate -This function is the general text-sorting routine that subdivides a -buffer into records and then sorts them. Most of the commands in this -section use this function. - -To understand how @code{sort-subr} works, consider the whole accessible -portion of the buffer as being divided into disjoint pieces called -@dfn{sort records}. The records may or may not be contiguous, but they -must not overlap. A portion of each sort record (perhaps all of it) is -designated as the sort key. Sorting rearranges the records in order by -their sort keys. - -Usually, the records are rearranged in order of ascending sort key. -If the first argument to the @code{sort-subr} function, @var{reverse}, -is non-@code{nil}, the sort records are rearranged in order of -descending sort key. - -The next four arguments to @code{sort-subr} are functions that are -called to move point across a sort record. They are called many times -from within @code{sort-subr}. - -@enumerate -@item -@var{nextrecfun} is called with point at the end of a record. This -function moves point to the start of the next record. The first record -is assumed to start at the position of point when @code{sort-subr} is -called. Therefore, you should usually move point to the beginning of -the buffer before calling @code{sort-subr}. - -This function can indicate there are no more sort records by leaving -point at the end of the buffer. - -@item -@var{endrecfun} is called with point within a record. It moves point to -the end of the record. - -@item -@var{startkeyfun} is called to move point from the start of a record to -the start of the sort key. This argument is optional; if it is omitted, -the whole record is the sort key. If supplied, the function should -either return a non-@code{nil} value to be used as the sort key, or -return @code{nil} to indicate that the sort key is in the buffer -starting at point. In the latter case, @var{endkeyfun} is called to -find the end of the sort key. - -@item -@var{endkeyfun} is called to move point from the start of the sort key -to the end of the sort key. This argument is optional. If -@var{startkeyfun} returns @code{nil} and this argument is omitted (or -@code{nil}), then the sort key extends to the end of the record. There -is no need for @var{endkeyfun} if @var{startkeyfun} returns a -non-@code{nil} value. -@end enumerate - -The argument @var{predicate} is the function to use to compare keys. -If keys are numbers, it defaults to @code{<}; otherwise it defaults to -@code{string<}. - -As an example of @code{sort-subr}, here is the complete function -definition for @code{sort-lines}: - -@example -@group -;; @r{Note that the first two lines of doc string} -;; @r{are effectively one line when viewed by a user.} -(defun sort-lines (reverse beg end) - "Sort lines in region alphabetically;\ - argument means descending order. -Called from a program, there are three arguments: -@end group -@group -REVERSE (non-nil means reverse order),\ - BEG and END (region to sort). -The variable `sort-fold-case' determines\ - whether alphabetic case affects -the sort order." -@end group -@group - (interactive "P\nr") - (save-excursion - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (let ((inhibit-field-text-motion t)) - (sort-subr reverse 'forward-line 'end-of-line))))) -@end group -@end example - -Here @code{forward-line} moves point to the start of the next record, -and @code{end-of-line} moves point to the end of record. We do not pass -the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire -record is used as the sort key. - -The @code{sort-paragraphs} function is very much the same, except that -its @code{sort-subr} call looks like this: - -@example -@group -(sort-subr reverse - (function - (lambda () - (while (and (not (eobp)) - (looking-at paragraph-separate)) - (forward-line 1)))) - 'forward-paragraph) -@end group -@end example - -Markers pointing into any sort records are left with no useful -position after @code{sort-subr} returns. -@end defun - -@defopt sort-fold-case -If this variable is non-@code{nil}, @code{sort-subr} and the other -buffer sorting functions ignore case when comparing strings. -@end defopt - -@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end -This command sorts the region between @var{start} and @var{end} -alphabetically as specified by @var{record-regexp} and @var{key-regexp}. -If @var{reverse} is a negative integer, then sorting is in reverse -order. - -Alphabetical sorting means that two sort keys are compared by -comparing the first characters of each, the second characters of each, -and so on. If a mismatch is found, it means that the sort keys are -unequal; the sort key whose character is less at the point of first -mismatch is the lesser sort key. The individual characters are compared -according to their numerical character codes in the Emacs character set. - -The value of the @var{record-regexp} argument specifies how to divide -the buffer into sort records. At the end of each record, a search is -done for this regular expression, and the text that matches it is taken -as the next record. For example, the regular expression @samp{^.+$}, -which matches lines with at least one character besides a newline, would -make each such line into a sort record. @xref{Regular Expressions}, for -a description of the syntax and meaning of regular expressions. - -The value of the @var{key-regexp} argument specifies what part of each -record is the sort key. The @var{key-regexp} could match the whole -record, or only a part. In the latter case, the rest of the record has -no effect on the sorted order of records, but it is carried along when -the record moves to its new position. - -The @var{key-regexp} argument can refer to the text matched by a -subexpression of @var{record-regexp}, or it can be a regular expression -on its own. - -If @var{key-regexp} is: - -@table @asis -@item @samp{\@var{digit}} -then the text matched by the @var{digit}th @samp{\(...\)} parenthesis -grouping in @var{record-regexp} is the sort key. - -@item @samp{\&} -then the whole record is the sort key. - -@item a regular expression -then @code{sort-regexp-fields} searches for a match for the regular -expression within the record. If such a match is found, it is the sort -key. If there is no match for @var{key-regexp} within a record then -that record is ignored, which means its position in the buffer is not -changed. (The other records may move around it.) -@end table - -For example, if you plan to sort all the lines in the region by the -first word on each line starting with the letter @samp{f}, you should -set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to -@samp{\}. The resulting expression looks like this: - -@example -@group -(sort-regexp-fields nil "^.*$" "\\" - (region-beginning) - (region-end)) -@end group -@end example - -If you call @code{sort-regexp-fields} interactively, it prompts for -@var{record-regexp} and @var{key-regexp} in the minibuffer. -@end deffn - -@deffn Command sort-lines reverse start end -This command alphabetically sorts lines in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-paragraphs reverse start end -This command alphabetically sorts paragraphs in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-pages reverse start end -This command alphabetically sorts pages in the region between -@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort -is in reverse order. -@end deffn - -@deffn Command sort-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them alphabetically by the @var{field}th field -of each line. Fields are separated by whitespace and numbered starting -from 1. If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This command -is useful for sorting tables. -@end deffn - -@deffn Command sort-numeric-fields field start end -This command sorts lines in the region between @var{start} and -@var{end}, comparing them numerically by the @var{field}th field of -each line. Fields are separated by whitespace and numbered starting -from 1. The specified field must contain a number in each line of the -region. Numbers starting with 0 are treated as octal, and numbers -starting with @samp{0x} are treated as hexadecimal. - -If @var{field} is negative, sorting is by the -@w{@minus{}@var{field}th} field from the end of the line. This -command is useful for sorting tables. -@end deffn - -@defopt sort-numeric-base -This variable specifies the default radix for -@code{sort-numeric-fields} to parse numbers. -@end defopt - -@deffn Command sort-columns reverse &optional beg end -This command sorts the lines in the region between @var{beg} and -@var{end}, comparing them alphabetically by a certain range of -columns. The column positions of @var{beg} and @var{end} bound the -range of columns to sort on. - -If @var{reverse} is non-@code{nil}, the sort is in reverse order. - -One unusual thing about this command is that the entire line -containing position @var{beg}, and the entire line containing position -@var{end}, are included in the region sorted. - -Note that @code{sort-columns} rejects text that contains tabs, because -tabs could be split across the specified columns. Use @kbd{M-x -untabify} to convert tabs to spaces before sorting. - -When possible, this command actually works by calling the @code{sort} -utility program. -@end deffn - -@node Columns -@comment node-name, next, previous, up -@section Counting Columns -@cindex columns -@cindex counting columns -@cindex horizontal position - - The column functions convert between a character position (counting -characters from the beginning of the buffer) and a column position -(counting screen characters from the beginning of a line). - - These functions count each character according to the number of -columns it occupies on the screen. This means control characters count -as occupying 2 or 4 columns, depending upon the value of -@code{ctl-arrow}, and tabs count as occupying a number of columns that -depends on the value of @code{tab-width} and on the column where the tab -begins. @xref{Usual Display}. - - Column number computations ignore the width of the window and the -amount of horizontal scrolling. Consequently, a column value can be -arbitrarily high. The first (or leftmost) column is numbered 0. They -also ignore overlays and text properties, aside from invisibility. - -@defun current-column -This function returns the horizontal position of point, measured in -columns, counting from 0 at the left margin. The column position is the -sum of the widths of all the displayed representations of the characters -between the start of the current line and point. - -For an example of using @code{current-column}, see the description of -@code{count-lines} in @ref{Text Lines}. -@end defun - -@deffn Command move-to-column column &optional force -This function moves point to @var{column} in the current line. The -calculation of @var{column} takes into account the widths of the -displayed representations of the characters between the start of the -line and point. - -When called interactively, @var{column} is the value of prefix numeric -argument. If @var{column} is not an integer, an error is signaled. - -If column @var{column} is beyond the end of the line, point moves to -the end of the line. If @var{column} is negative, point moves to the -beginning of the line. - -If it is impossible to move to column @var{column} because that is in -the middle of a multicolumn character such as a tab, point moves to the -end of that character. However, if @var{force} is non-@code{nil}, and -@var{column} is in the middle of a tab, then @code{move-to-column} -converts the tab into spaces so that it can move precisely to column -@var{column}. Other multicolumn characters can cause anomalies despite -@var{force}, since there is no way to split them. - -The argument @var{force} also has an effect if the line isn't long -enough to reach column @var{column}; if it is @code{t}, that means to -add whitespace at the end of the line to reach that column. - -The return value is the column number actually moved to. -@end deffn - -@node Indentation -@section Indentation -@cindex indentation - - The indentation functions are used to examine, move to, and change -whitespace that is at the beginning of a line. Some of the functions -can also change whitespace elsewhere on a line. Columns and indentation -count from zero at the left margin. - -@menu -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. -@end menu - -@node Primitive Indent -@subsection Indentation Primitives - - This section describes the primitive functions used to count and -insert indentation. The functions in the following sections use these -primitives. @xref{Width}, for related functions. - -@defun current-indentation -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function returns the indentation of the current line, which is -the horizontal position of the first nonblank character. If the -contents are entirely blank, then this is the horizontal position of the -end of the line. -@end defun - -@deffn Command indent-to column &optional minimum -@comment !!Type Primitive Function -@comment !!SourceFile indent.c -This function indents from point with tabs and spaces until @var{column} -is reached. If @var{minimum} is specified and non-@code{nil}, then at -least that many spaces are inserted even if this requires going beyond -@var{column}. Otherwise the function does nothing if point is already -beyond @var{column}. The value is the column at which the inserted -indentation ends. - -The inserted whitespace characters inherit text properties from the -surrounding text (usually, from the preceding text only). @xref{Sticky -Properties}. -@end deffn - -@defopt indent-tabs-mode -@comment !!SourceFile indent.c -If this variable is non-@code{nil}, indentation functions can insert -tabs as well as spaces. Otherwise, they insert only spaces. Setting -this variable automatically makes it buffer-local in the current buffer. -@end defopt - -@node Mode-Specific Indent -@subsection Indentation Controlled by Major Mode - - An important function of each major mode is to customize the @key{TAB} -key to indent properly for the language being edited. This section -describes the mechanism of the @key{TAB} key and how to control it. -The functions in this section return unpredictable values. - -@defvar indent-line-function -This variable's value is the function to be used by @key{TAB} (and -various commands) to indent the current line. The command -@code{indent-according-to-mode} does no more than call this function. - -In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C -mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. -The default value is @code{indent-relative}. -@end defvar - -@deffn Command indent-according-to-mode -This command calls the function in @code{indent-line-function} to -indent the current line in a way appropriate for the current major mode. -@end deffn - -@deffn Command indent-for-tab-command &optional rigid -This command calls the function in @code{indent-line-function} to -indent the current line; however, if that function is -@code{indent-to-left-margin}, @code{insert-tab} is called instead. -(That is a trivial command that inserts a tab character.) If -@var{rigid} is non-@code{nil}, this function also rigidly indents the -entire balanced expression that starts at the beginning of the current -line, to reflect change in indentation of the current line. -@end deffn - -@deffn Command newline-and-indent -This function inserts a newline, then indents the new line (the one -following the newline just inserted) according to the major mode. - -It does indentation by calling the current @code{indent-line-function}. -In programming language modes, this is the same thing @key{TAB} does, -but in some text modes, where @key{TAB} inserts a tab, -@code{newline-and-indent} indents to the column specified by -@code{left-margin}. -@end deffn - -@deffn Command reindent-then-newline-and-indent -@comment !!SourceFile simple.el -This command reindents the current line, inserts a newline at point, -and then indents the new line (the one following the newline just -inserted). - -This command does indentation on both lines according to the current -major mode, by calling the current value of @code{indent-line-function}. -In programming language modes, this is the same thing @key{TAB} does, -but in some text modes, where @key{TAB} inserts a tab, -@code{reindent-then-newline-and-indent} indents to the column specified -by @code{left-margin}. -@end deffn - -@node Region Indent -@subsection Indenting an Entire Region - - This section describes commands that indent all the lines in the -region. They return unpredictable values. - -@deffn Command indent-region start end &optional to-column -This command indents each nonblank line starting between @var{start} -(inclusive) and @var{end} (exclusive). If @var{to-column} is -@code{nil}, @code{indent-region} indents each nonblank line by calling -the current mode's indentation function, the value of -@code{indent-line-function}. - -If @var{to-column} is non-@code{nil}, it should be an integer -specifying the number of columns of indentation; then this function -gives each line exactly that much indentation, by either adding or -deleting whitespace. - -If there is a fill prefix, @code{indent-region} indents each line -by making it start with the fill prefix. -@end deffn - -@defvar indent-region-function -The value of this variable is a function that can be used by -@code{indent-region} as a short cut. It should take two arguments, the -start and end of the region. You should design the function so -that it will produce the same results as indenting the lines of the -region one by one, but presumably faster. - -If the value is @code{nil}, there is no short cut, and -@code{indent-region} actually works line by line. - -A short-cut function is useful in modes such as C mode and Lisp mode, -where the @code{indent-line-function} must scan from the beginning of -the function definition: applying it to each line would be quadratic in -time. The short cut can update the scan information as it moves through -the lines indenting them; this takes linear time. In a mode where -indenting a line individually is fast, there is no need for a short cut. - -@code{indent-region} with a non-@code{nil} argument @var{to-column} has -a different meaning and does not use this variable. -@end defvar - -@deffn Command indent-rigidly start end count -This command indents all lines starting between @var{start} -(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. -This ``preserves the shape'' of the affected region, moving it as a -rigid unit. Consequently, this command is useful not only for indenting -regions of unindented text, but also for indenting regions of formatted -code. - -For example, if @var{count} is 3, this command adds 3 columns of -indentation to each of the lines beginning in the region specified. - -In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses -@code{indent-rigidly} to indent the text copied from the message being -replied to. -@end deffn - -@deffn Command indent-code-rigidly start end columns &optional nochange-regexp -This is like @code{indent-rigidly}, except that it doesn't alter lines -that start within strings or comments. - -In addition, it doesn't alter a line if @var{nochange-regexp} matches at -the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). -@end deffn - -@node Relative Indent -@subsection Indentation Relative to Previous Lines - - This section describes two commands that indent the current line -based on the contents of previous lines. - -@deffn Command indent-relative &optional unindented-ok -This command inserts whitespace at point, extending to the same -column as the next @dfn{indent point} of the previous nonblank line. An -indent point is a non-whitespace character following whitespace. The -next indent point is the first one at a column greater than the current -column of point. For example, if point is underneath and to the left of -the first non-blank character of a line of text, it moves to that column -by inserting whitespace. - -If the previous nonblank line has no next indent point (i.e., none at a -great enough column position), @code{indent-relative} either does -nothing (if @var{unindented-ok} is non-@code{nil}) or calls -@code{tab-to-tab-stop}. Thus, if point is underneath and to the right -of the last column of a short line of text, this command ordinarily -moves point to the next tab stop by inserting whitespace. - -The return value of @code{indent-relative} is unpredictable. - -In the following example, point is at the beginning of the second -line: - -@example -@group - This line is indented twelve spaces. -@point{}The quick brown fox jumped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. - @point{}The quick brown fox jumped. -@end group -@end example - - In this next example, point is between the @samp{m} and @samp{p} of -@samp{jumped}: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum@point{}ped. -@end group -@end example - -@noindent -Evaluation of the expression @code{(indent-relative nil)} produces the -following: - -@example -@group - This line is indented twelve spaces. -The quick brown fox jum @point{}ped. -@end group -@end example -@end deffn - -@deffn Command indent-relative-maybe -@comment !!SourceFile indent.el -This command indents the current line like the previous nonblank line, -by calling @code{indent-relative} with @code{t} as the -@var{unindented-ok} argument. The return value is unpredictable. - -If the previous nonblank line has no indent points beyond the current -column, this command does nothing. -@end deffn - -@node Indent Tabs -@comment node-name, next, previous, up -@subsection Adjustable ``Tab Stops'' -@cindex tabs stops for indentation - - This section explains the mechanism for user-specified ``tab stops'' -and the mechanisms that use and set them. The name ``tab stops'' is -used because the feature is similar to that of the tab stops on a -typewriter. The feature works by inserting an appropriate number of -spaces and tab characters to reach the next tab stop column; it does not -affect the display of tab characters in the buffer (@pxref{Usual -Display}). Note that the @key{TAB} character as input uses this tab -stop feature only in a few major modes, such as Text mode. -@xref{Tab Stops,,, emacs, The GNU Emacs Manual}. - -@deffn Command tab-to-tab-stop -This command inserts spaces or tabs before point, up to the next tab -stop column defined by @code{tab-stop-list}. It searches the list for -an element greater than the current column number, and uses that element -as the column to indent to. It does nothing if no such element is -found. -@end deffn - -@defopt tab-stop-list -This variable is the list of tab stop columns used by -@code{tab-to-tab-stops}. The elements should be integers in increasing -order. The tab stop columns need not be evenly spaced. - -Use @kbd{M-x edit-tab-stops} to edit the location of tab stops -interactively. -@end defopt - -@node Motion by Indent -@subsection Indentation-Based Motion Commands - - These commands, primarily for interactive use, act based on the -indentation in the text. - -@deffn Command back-to-indentation -@comment !!SourceFile simple.el -This command moves point to the first non-whitespace character in the -current line (which is the line in which point is located). It returns -@code{nil}. -@end deffn - -@deffn Command backward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point backward @var{arg} lines and then to the -first nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@deffn Command forward-to-indentation &optional arg -@comment !!SourceFile simple.el -This command moves point forward @var{arg} lines and then to the first -nonblank character on that line. It returns @code{nil}. -If @var{arg} is omitted or @code{nil}, it defaults to 1. -@end deffn - -@node Case Changes -@comment node-name, next, previous, up -@section Case Changes -@cindex case conversion in buffers - - The case change commands described here work on text in the current -buffer. @xref{Case Conversion}, for case conversion functions that work -on strings and characters. @xref{Case Tables}, for how to customize -which characters are upper or lower case and how to convert them. - -@deffn Command capitalize-region start end -This function capitalizes all words in the region defined by -@var{start} and @var{end}. To capitalize means to convert each word's -first character to upper case and convert the rest of each word to lower -case. The function returns @code{nil}. - -If one end of the region is in the middle of a word, the part of the -word within the region is treated as an entire word. - -When @code{capitalize-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the 5th foo. ----------- Buffer: foo ---------- -@end group - -@group -(capitalize-region 1 44) -@result{} nil - ----------- Buffer: foo ---------- -This Is The Contents Of The 5th Foo. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command downcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to lower case. The function returns -@code{nil}. - -When @code{downcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command upcase-region start end -This function converts all of the letters in the region defined by -@var{start} and @var{end} to upper case. The function returns -@code{nil}. - -When @code{upcase-region} is called interactively, @var{start} and -@var{end} are point and the mark, with the smallest first. -@end deffn - -@deffn Command capitalize-word count -This function capitalizes @var{count} words after point, moving point -over as it does. To capitalize means to convert each word's first -character to upper case and convert the rest of each word to lower case. -If @var{count} is negative, the function capitalizes the -@minus{}@var{count} previous words but does not move point. The value -is @code{nil}. - -If point is in the middle of a word, the part of the word before point -is ignored when moving forward. The rest is treated as an entire word. - -When @code{capitalize-word} is called interactively, @var{count} is -set to the numeric prefix argument. -@end deffn - -@deffn Command downcase-word count -This function converts the @var{count} words after point to all lower -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{downcase-word} is called interactively, @var{count} is set -to the numeric prefix argument. -@end deffn - -@deffn Command upcase-word count -This function converts the @var{count} words after point to all upper -case, moving point over as it does. If @var{count} is negative, it -converts the @minus{}@var{count} previous words but does not move point. -The value is @code{nil}. - -When @code{upcase-word} is called interactively, @var{count} is set to -the numeric prefix argument. -@end deffn - -@node Text Properties -@section Text Properties -@cindex text properties -@cindex attributes of text -@cindex properties of text - - Each character position in a buffer or a string can have a @dfn{text -property list}, much like the property list of a symbol (@pxref{Property -Lists}). The properties belong to a particular character at a -particular place, such as, the letter @samp{T} at the beginning of this -sentence or the first @samp{o} in @samp{foo}---if the same character -occurs in two different places, the two occurrences in general have -different properties. - - Each property has a name and a value. Both of these can be any Lisp -object, but the name is normally a symbol. Typically each property -name symbol is used for a particular purpose; for instance, the text -property @code{face} specifies the faces for displaying the character -(@pxref{Special Properties}). The usual way to access the property -list is to specify a name and ask what value corresponds to it. - - If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of the symbol serve as defaults for the properties of the -character. - - Copying text between strings and buffers preserves the properties -along with the characters; this includes such diverse functions as -@code{substring}, @code{insert}, and @code{buffer-substring}. - -@menu -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. -@end menu - -@node Examining Properties -@subsection Examining Text Properties - - The simplest way to examine text properties is to ask for the value of -a particular property of a particular character. For that, use -@code{get-text-property}. Use @code{text-properties-at} to get the -entire property list of a character. @xref{Property Search}, for -functions to examine the properties of a number of characters at once. - - These functions handle both strings and buffers. Keep in mind that -positions in a string start from 0, whereas positions in a buffer start -from 1. - -@defun get-text-property pos prop &optional object -This function returns the value of the @var{prop} property of the -character after position @var{pos} in @var{object} (a buffer or -string). The argument @var{object} is optional and defaults to the -current buffer. - -If there is no @var{prop} property strictly speaking, but the character -has a property category that is a symbol, then @code{get-text-property} returns -the @var{prop} property of that symbol. -@end defun - -@defun get-char-property position prop &optional object -This function is like @code{get-text-property}, except that it checks -overlays first and then text properties. @xref{Overlays}. - -The argument @var{object} may be a string, a buffer, or a window. If -it is a window, then the buffer displayed in that window is used for -text properties and overlays, but only the overlays active for that -window are considered. If @var{object} is a buffer, then overlays in -that buffer are considered first, in order of decreasing priority, -followed by the text properties. If @var{object} is a string, only -text properties are considered, since strings never have overlays. -@end defun - -@defun get-char-property-and-overlay position prop &optional object -This is like @code{get-char-property}, but gives extra information -about the overlay that the property value comes from. - -Its value is a cons cell whose @sc{car} is the property value, the -same value @code{get-char-property} would return with the same -arguments. Its @sc{cdr} is the overlay in which the property was -found, or @code{nil}, if it was found as a text property or not found -at all. - -If @var{position} is at the end of @var{object}, both the @sc{car} and -the @sc{cdr} of the value are @code{nil}. -@end defun - -@defvar char-property-alias-alist -This variable holds an alist which maps property names to a list of -alternative property names. If a character does not specify a direct -value for a property, the alternative property names are consulted in -order; the first non-@code{nil} value is used. This variable takes -precedence over @code{default-text-properties}, and @code{category} -properties take precedence over this variable. -@end defvar - -@defun text-properties-at position &optional object -This function returns the entire property list of the character at -@var{position} in the string or buffer @var{object}. If @var{object} is -@code{nil}, it defaults to the current buffer. -@end defun - -@defvar default-text-properties -This variable holds a property list giving default values for text -properties. Whenever a character does not specify a value for a -property, neither directly, through a category symbol, or through -@code{char-property-alias-alist}, the value stored in this list is -used instead. Here is an example: - -@example -(setq default-text-properties '(foo 69) - char-property-alias-alist nil) -;; @r{Make sure character 1 has no properties of its own.} -(set-text-properties 1 2 nil) -;; @r{What we get, when we ask, is the default value.} -(get-text-property 1 'foo) - @result{} 69 -@end example -@end defvar - -@node Changing Properties -@subsection Changing Text Properties - - The primitives for changing properties apply to a specified range of -text in a buffer or string. The function @code{set-text-properties} -(see end of section) sets the entire property list of the text in that -range; more often, it is useful to add, change, or delete just certain -properties specified by name. - - Since text properties are considered part of the contents of the -buffer (or string), and can affect how a buffer looks on the screen, -any change in buffer text properties marks the buffer as modified. -Buffer text property changes are undoable also (@pxref{Undo}). -Positions in a string start from 0, whereas positions in a buffer -start from 1. - -@defun put-text-property start end prop value &optional object -This function sets the @var{prop} property to @var{value} for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. -@end defun - -@defun add-text-properties start end props &optional object -This function adds or overrides text properties for the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to add. It should -have the form of a property list (@pxref{Property Lists}): a list whose -elements include the property names followed alternately by the -corresponding values. - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -its values agree with those in the text). - -For example, here is how to set the @code{comment} and @code{face} -properties of a range of text: - -@example -(add-text-properties @var{start} @var{end} - '(comment t face highlight)) -@end example -@end defun - -@defun remove-text-properties start end props &optional object -This function deletes specified text properties from the text between -@var{start} and @var{end} in the string or buffer @var{object}. If -@var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} specifies which properties to delete. It -should have the form of a property list (@pxref{Property Lists}): a list -whose elements are property names alternating with corresponding values. -But only the names matter---the values that accompany them are ignored. -For example, here's how to remove the @code{face} property. - -@example -(remove-text-properties @var{start} @var{end} '(face nil)) -@end example - -The return value is @code{t} if the function actually changed some -property's value; @code{nil} otherwise (if @var{props} is @code{nil} or -if no character in the specified text had any of those properties). - -To remove all text properties from certain text, use -@code{set-text-properties} and specify @code{nil} for the new property -list. -@end defun - -@defun remove-list-of-text-properties start end list-of-properties &optional object -Like @code{remove-text-properties} except that -@var{list-of-properties} is a list of property names only, not an -alternating list of property names and values. -@end defun - -@defun set-text-properties start end props &optional object -This function completely replaces the text property list for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. - -The argument @var{props} is the new property list. It should be a list -whose elements are property names alternating with corresponding values. - -After @code{set-text-properties} returns, all the characters in the -specified range have identical properties. - -If @var{props} is @code{nil}, the effect is to get rid of all properties -from the specified range of text. Here's an example: - -@example -(set-text-properties @var{start} @var{end} nil) -@end example - -Do not rely on the return value of this function. -@end defun - - The easiest way to make a string with text properties -is with @code{propertize}: - -@defun propertize string &rest properties -This function returns a copy of @var{string} which has the text -properties @var{properties}. These properties apply to all the -characters in the string that is returned. Here is an example that -constructs a string with a @code{face} property and a @code{mouse-face} -property: - -@smallexample -(propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - @result{} #("foo" 0 3 (mouse-face bold-italic face italic)) -@end smallexample - -To put different properties on various parts of a string, you can -construct each part with @code{propertize} and then combine them with -@code{concat}: - -@smallexample -(concat - (propertize "foo" 'face 'italic - 'mouse-face 'bold-italic) - " and " - (propertize "bar" 'face 'italic - 'mouse-face 'bold-italic)) - @result{} #("foo and bar" - 0 3 (face italic mouse-face bold-italic) - 3 8 nil - 8 11 (face italic mouse-face bold-italic)) -@end smallexample -@end defun - - See also the function @code{buffer-substring-no-properties} -(@pxref{Buffer Contents}) which copies text from the buffer -but does not copy its properties. - -@node Property Search -@subsection Text Property Search Functions - - In typical use of text properties, most of the time several or many -consecutive characters have the same value for a property. Rather than -writing your programs to examine characters one by one, it is much -faster to process chunks of text that have the same property value. - - Here are functions you can use to do this. They use @code{eq} for -comparing property values. In all cases, @var{object} defaults to the -current buffer. - - For high performance, it's very important to use the @var{limit} -argument to these functions, especially the ones that search for a -single property---otherwise, they may spend a long time scanning to the -end of the buffer, if the property you are interested in does not change. - - These functions do not move point; instead, they return a position (or -@code{nil}). Remember that a position is always between two characters; -the position returned by these functions is between two characters with -different properties. - -@defun next-property-change pos &optional object limit -The function scans the text forward from position @var{pos} in the -string or buffer @var{object} till it finds a change in some text -property, then returns the position of the change. In other words, it -returns the position of the first character beyond @var{pos} whose -properties are not identical to those of the character just after -@var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-property-change} returns @var{limit}. - -The value is @code{nil} if the properties remain unchanged all the way -to the end of @var{object} and @var{limit} is @code{nil}. If the value -is non-@code{nil}, it is a position greater than or equal to @var{pos}. -The value equals @var{pos} only when @var{limit} equals @var{pos}. - -Here is an example of how to scan the buffer by chunks of text within -which all properties are constant: - -@smallexample -(while (not (eobp)) - (let ((plist (text-properties-at (point))) - (next-change - (or (next-property-change (point) (current-buffer)) - (point-max)))) - @r{Process text from point to @var{next-change}@dots{}} - (goto-char next-change))) -@end smallexample -@end defun - -@defun previous-property-change pos &optional object limit -This is like @code{next-property-change}, but scans back from @var{pos} -instead of forward. If the value is non-@code{nil}, it is a position -less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} -equals @var{pos}. -@end defun - -@defun next-single-property-change pos prop &optional object limit -The function scans text for a change in the @var{prop} property, then -returns the position of the change. The scan goes forward from -position @var{pos} in the string or buffer @var{object}. In other -words, this function returns the position of the first character -beyond @var{pos} whose @var{prop} property differs from that of the -character just after @var{pos}. - -If @var{limit} is non-@code{nil}, then the scan ends at position -@var{limit}. If there is no property change before that point, -@code{next-single-property-change} returns @var{limit}. - -The value is @code{nil} if the property remains unchanged all the way to -the end of @var{object} and @var{limit} is @code{nil}. If the value is -non-@code{nil}, it is a position greater than or equal to @var{pos}; it -equals @var{pos} only if @var{limit} equals @var{pos}. -@end defun - -@defun previous-single-property-change pos prop &optional object limit -This is like @code{next-single-property-change}, but scans back from -@var{pos} instead of forward. If the value is non-@code{nil}, it is a -position less than or equal to @var{pos}; it equals @var{pos} only if -@var{limit} equals @var{pos}. -@end defun - -@defun next-char-property-change pos &optional limit -This is like @code{next-property-change} except that it considers -overlay properties as well as text properties, and if no change is -found before the end of the buffer, it returns the maximum buffer -position rather than @code{nil} (in this sense, it resembles the -corresponding overlay function @code{next-overlay-change}, rather than -@code{next-property-change}). There is no @var{object} operand -because this function operates only on the current buffer. It returns -the next address at which either kind of property changes. -@end defun - -@defun previous-char-property-change pos &optional limit -This is like @code{next-char-property-change}, but scans back from -@var{pos} instead of forward, and returns the minimum buffer -position if no change is found. -@end defun - -@defun next-single-char-property-change pos prop &optional object limit -This is like @code{next-single-property-change} except that it -considers overlay properties as well as text properties, and if no -change is found before the end of the @var{object}, it returns the -maximum valid position in @var{object} rather than @code{nil}. Unlike -@code{next-char-property-change}, this function @emph{does} have an -@var{object} operand; if @var{object} is not a buffer, only -text-properties are considered. -@end defun - -@defun previous-single-char-property-change pos prop &optional object limit -This is like @code{next-single-char-property-change}, but scans back -from @var{pos} instead of forward, and returns the minimum valid -position in @var{object} if no change is found. -@end defun - -@defun text-property-any start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} has a property @var{prop} whose value is -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@defun text-property-not-all start end prop value &optional object -This function returns non-@code{nil} if at least one character between -@var{start} and @var{end} does not have a property @var{prop} with value -@var{value}. More precisely, it returns the position of the first such -character. Otherwise, it returns @code{nil}. - -The optional fifth argument, @var{object}, specifies the string or -buffer to scan. Positions are relative to @var{object}. The default -for @var{object} is the current buffer. -@end defun - -@node Special Properties -@subsection Properties with Special Meanings - - Here is a table of text property names that have special built-in -meanings. The following sections list a few additional special property -names that control filling and property inheritance. All other names -have no standard meaning, and you can use them as you like. - - Note: the properties @code{composition}, @code{display}, -@code{invisible} and @code{intangible} can also cause point to move to -an acceptable place, after each Emacs command. @xref{Adjusting -Point}. - -@table @code -@cindex property category of text character -@kindex category @r{(text property)} -@item category -If a character has a @code{category} property, we call it the -@dfn{property category} of the character. It should be a symbol. The -properties of this symbol serve as defaults for the properties of the -character. - -@item face -@cindex face codes of text -@kindex face @r{(text property)} -You can use the property @code{face} to control the font and color of -text. @xref{Faces}, for more information. - -In the simplest case, the value is a face name. It can also be a list; -then each element can be any of these possibilities; - -@itemize @bullet -@item -A face name (a symbol or string). - -@item -A property list of face attributes. This has the -form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a -face attribute name and @var{value} is a meaningful value for that -attribute. With this feature, you do not need to create a face each -time you want to specify a particular attribute for certain text. -@xref{Face Attributes}. - -@item -A cons cell with the form @code{(foreground-color . @var{color-name})} -or @code{(background-color . @var{color-name})}. These are old, -deprecated equivalents for @code{(:foreground @var{color-name})} and -@code{(:background @var{color-name})}. Please convert code that uses -them. -@end itemize - -It works to use the latter two forms directly as the value -of the @code{face} property. - -Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by -dynamically updating the @code{face} property of characters based on -the context. - -@item font-lock-face -@kindex font-lock-face @r{(text property)} -The @code{font-lock-face} property is equivalent to the @code{face} -property when Font Lock mode is enabled. When Font Lock mode is disabled, -@code{font-lock-face} has no effect. - -The @code{font-lock-mode} property is useful for special modes that -implement their own highlighting. @xref{Precalculated Fontification}. - -@item mouse-face -@kindex mouse-face @r{(text property)} -The property @code{mouse-face} is used instead of @code{face} when the -mouse is on or near the character. For this purpose, ``near'' means -that all text between the character and where the mouse is have the same -@code{mouse-face} property value. - -@item fontified -@kindex fontified @r{(text property)} -This property says whether the text is ready for display. If -@code{nil}, Emacs's redisplay routine calls the functions in -@code{fontification-functions} (@pxref{Auto Faces}) to prepare this -part of the buffer before it is displayed. It is used internally by -the ``just in time'' font locking code. - -@item display -This property activates various features that change the -way text is displayed. For example, it can make text appear taller -or shorter, higher or lower, wider or narrow, or replaced with an image. -@xref{Display Property}. - -@item help-echo -@kindex help-echo @r{(text property)} -@cindex tooltip -@anchor{Text help-echo} -If text has a string as its @code{help-echo} property, then when you -move the mouse onto that text, Emacs displays that string in the echo -area, or in the tooltip window (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}). - -If the value of the @code{help-echo} property is a function, that -function is called with three arguments, @var{window}, @var{object} and -@var{pos} and should return a help string or @code{nil} for -none. The first argument, @var{window} is the window in which -the help was found. The second, @var{object}, is the buffer, overlay or -string which had the @code{help-echo} property. The @var{pos} -argument is as follows: - -@itemize @bullet{} -@item -If @var{object} is a buffer, @var{pos} is the position in the buffer. -@item -If @var{object} is an overlay, that overlay has a @code{help-echo} -property, and @var{pos} is the position in the overlay's buffer. -@item -If @var{object} is a string (an overlay string or a string displayed -with the @code{display} property), @var{pos} is the position in that -string. -@end itemize - -If the value of the @code{help-echo} property is neither a function nor -a string, it is evaluated to obtain a help string. - -You can alter the way help text is displayed by setting the variable -@code{show-help-function} (@pxref{Help display}). - -This feature is used in the mode line and for other active text. - -@item keymap -@cindex keymap of character -@kindex keymap @r{(text property)} -The @code{keymap} property specifies an additional keymap for -commands. When this keymap applies, it is used for key lookup before -the minor mode keymaps and before the buffer's local map. -@xref{Active Keymaps}. If the property value is a symbol, the -symbol's function definition is used as the keymap. - -The property's value for the character before point applies if it is -non-@code{nil} and rear-sticky, and the property's value for the -character after point applies if it is non-@code{nil} and -front-sticky. (For mouse clicks, the position of the click is used -instead of the position of point.) - -@item local-map -@kindex local-map @r{(text property)} -This property works like @code{keymap} except that it specifies a -keymap to use @emph{instead of} the buffer's local map. For most -purposes (perhaps all purposes), it is better to use the @code{keymap} -property. - -@item syntax-table -The @code{syntax-table} property overrides what the syntax table says -about this particular character. @xref{Syntax Properties}. - -@item read-only -@cindex read-only character -@kindex read-only @r{(text property)} -If a character has the property @code{read-only}, then modifying that -character is not allowed. Any command that would do so gets an error, -@code{text-read-only}. If the property value is a string, that string -is used as the error message. - -Insertion next to a read-only character is an error if inserting -ordinary text there would inherit the @code{read-only} property due to -stickiness. Thus, you can control permission to insert next to -read-only text by controlling the stickiness. @xref{Sticky Properties}. - -Since changing properties counts as modifying the buffer, it is not -possible to remove a @code{read-only} property unless you know the -special trick: bind @code{inhibit-read-only} to a non-@code{nil} value -and then remove the property. @xref{Read Only Buffers}. - -@item invisible -@kindex invisible @r{(text property)} -A non-@code{nil} @code{invisible} property can make a character invisible -on the screen. @xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(text property)} -If a group of consecutive characters have equal and non-@code{nil} -@code{intangible} properties, then you cannot place point between them. -If you try to move point forward into the group, point actually moves to -the end of the group. If you try to move point backward into the group, -point actually moves to the start of the group. - -If consecutive characters have unequal non-@code{nil} -@code{intangible} properties, they belong to separate groups; each -group is separately treated as described above. - -When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, -the @code{intangible} property is ignored. - -@item field -@kindex field @r{(text property)} -Consecutive characters with the same @code{field} property constitute a -@dfn{field}. Some motion functions including @code{forward-word} and -@code{beginning-of-line} stop moving at a field boundary. -@xref{Fields}. - -@item cursor -@kindex cursor @r{(text property)} -Normally, the cursor is displayed at the end of any overlay and text -property strings present at the current window position. You can -place the cursor on any desired character of these strings by giving -that character a non-@code{nil} @var{cursor} text property. - -@item pointer -@kindex pointer @r{(text property)} -This specifies a specific pointer shape when the mouse pointer is over -this text or image. @xref{Pointer Shape}, for possible pointer -shapes. - -@item line-spacing -@kindex line-spacing @r{(text property)} -A newline can have a @code{line-spacing} text or overlay property that -controls the height of the display line ending with that newline. The -property value overrides the default frame line spacing and the buffer -local @code{line-spacing} variable. @xref{Line Height}. - -@item line-height -@kindex line-height @r{(text property)} -A newline can have a @code{line-height} text or overlay property that -controls the total height of the display line ending in that newline. -@xref{Line Height}. - -@item wrap-prefix -If text has a @code{wrap-prefix} property, the prefix it defines will -be added at display-time to the beginning of every continuation line -due to text wrapping (so if lines are truncated, the wrap-prefix is -never used). It may be a string, an image, or a stretch-glyph such as -used by the @code{display} text-property. @xref{Display Property}. - -A wrap-prefix may also be specified for an entire buffer using the -@code{wrap-prefix} buffer-local variable (however, a -@code{wrap-prefix} text-property takes precedence over the value of -the @code{wrap-prefix} variable). @xref{Truncation}. - -@item line-prefix -If text has a @code{line-prefix} property, the prefix it defines will -be added at display-time to the beginning of every non-continuation -line. It may be a string, an image, or a stretch-glyph such as used -by the @code{display} text-property. @xref{Display Property}. - -A line-prefix may also be specified for an entire buffer using the -@code{line-prefix} buffer-local variable (however, a -@code{line-prefix} text-property takes precedence over the value of -the @code{line-prefix} variable). @xref{Truncation}. - -@item modification-hooks -@cindex change hooks for a character -@cindex hooks for changing a character -@kindex modification-hooks @r{(text property)} -If a character has the property @code{modification-hooks}, then its -value should be a list of functions; modifying that character calls all -of those functions. Each function receives two arguments: the beginning -and end of the part of the buffer being modified. Note that if a -particular modification hook function appears on several characters -being modified by a single primitive, you can't predict how many times -the function will be called. - -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. - -Overlays also support the @code{modification-hooks} property, but the -details are somewhat different (@pxref{Overlay Properties}). - -@item insert-in-front-hooks -@itemx insert-behind-hooks -@kindex insert-in-front-hooks @r{(text property)} -@kindex insert-behind-hooks @r{(text property)} -The operation of inserting text in a buffer also calls the functions -listed in the @code{insert-in-front-hooks} property of the following -character and in the @code{insert-behind-hooks} property of the -preceding character. These functions receive two arguments, the -beginning and end of the inserted text. The functions are called -@emph{after} the actual insertion takes place. - -See also @ref{Change Hooks}, for other hooks that are called -when you change text in a buffer. - -@item point-entered -@itemx point-left -@cindex hooks for motion of point -@kindex point-entered @r{(text property)} -@kindex point-left @r{(text property)} -The special properties @code{point-entered} and @code{point-left} -record hook functions that report motion of point. Each time point -moves, Emacs compares these two property values: - -@itemize @bullet -@item -the @code{point-left} property of the character after the old location, -and -@item -the @code{point-entered} property of the character after the new -location. -@end itemize - -@noindent -If these two values differ, each of them is called (if not @code{nil}) -with two arguments: the old value of point, and the new one. - -The same comparison is made for the characters before the old and new -locations. The result may be to execute two @code{point-left} functions -(which may be the same function) and/or two @code{point-entered} -functions (which may be the same function). In any case, all the -@code{point-left} functions are called first, followed by all the -@code{point-entered} functions. - -It is possible with @code{char-after} to examine characters at various -buffer positions without moving point to those positions. Only an -actual change in the value of point runs these hook functions. - -@defvar inhibit-point-motion-hooks -When this variable is non-@code{nil}, @code{point-left} and -@code{point-entered} hooks are not run, and the @code{intangible} -property has no effect. Do not set this variable globally; bind it with -@code{let}. -@end defvar - -@defvar show-help-function -@anchor{Help display} If this variable is non-@code{nil}, it specifies a -function called to display help strings. These may be @code{help-echo} -properties, menu help strings (@pxref{Simple Menu Items}, -@pxref{Extended Menu Items}), or tool bar help strings (@pxref{Tool -Bar}). The specified function is called with one argument, the help -string to display. Tooltip mode (@pxref{Tooltips,,, emacs, The GNU Emacs -Manual}) provides an example. -@end defvar - -@item composition -@kindex composition @r{(text property)} -This text property is used to display a sequence of characters as a -single glyph composed from components. But the value of the property -itself is completely internal to Emacs and should not be manipulated -directly by, for instance, @code{put-text-property}. - -@end table - -@node Format Properties -@subsection Formatted Text Properties - - These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}, and -@ref{Margins}. - -@table @code -@item hard -If a newline character has this property, it is a ``hard'' newline. -The fill commands do not alter hard newlines and do not move words -across them. However, this property takes effect only if the -@code{use-hard-newlines} minor mode is enabled. @xref{Hard and Soft -Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}. - -@item right-margin -This property specifies an extra right margin for filling this part of the -text. - -@item left-margin -This property specifies an extra left margin for filling this part of the -text. - -@item justification -This property specifies the style of justification for filling this part -of the text. -@end table - -@node Sticky Properties -@subsection Stickiness of Text Properties -@cindex sticky text properties -@cindex inheritance of text properties - - Self-inserting characters normally take on the same properties as the -preceding character. This is called @dfn{inheritance} of properties. - - In a Lisp program, you can do insertion with inheritance or without, -depending on your choice of insertion primitive. The ordinary text -insertion functions such as @code{insert} do not inherit any properties. -They insert text with precisely the properties of the string being -inserted, and no others. This is correct for programs that copy text -from one context to another---for example, into or out of the kill ring. -To insert with inheritance, use the special primitives described in this -section. Self-inserting characters inherit properties because they work -using these primitives. - - When you do insertion with inheritance, @emph{which} properties are -inherited, and from where, depends on which properties are @dfn{sticky}. -Insertion after a character inherits those of its properties that are -@dfn{rear-sticky}. Insertion before a character inherits those of its -properties that are @dfn{front-sticky}. When both sides offer different -sticky values for the same property, the previous character's value -takes precedence. - - By default, a text property is rear-sticky but not front-sticky; thus, -the default is to inherit all the properties of the preceding character, -and nothing from the following character. - - You can control the stickiness of various text properties with two -specific text properties, @code{front-sticky} and @code{rear-nonsticky}, -and with the variable @code{text-property-default-nonsticky}. You can -use the variable to specify a different default for a given property. -You can use those two text properties to make any specific properties -sticky or nonsticky in any particular part of the text. - - If a character's @code{front-sticky} property is @code{t}, then all -its properties are front-sticky. If the @code{front-sticky} property is -a list, then the sticky properties of the character are those whose -names are in the list. For example, if a character has a -@code{front-sticky} property whose value is @code{(face read-only)}, -then insertion before the character can inherit its @code{face} property -and its @code{read-only} property, but no others. - - The @code{rear-nonsticky} property works the opposite way. Most -properties are rear-sticky by default, so the @code{rear-nonsticky} -property says which properties are @emph{not} rear-sticky. If a -character's @code{rear-nonsticky} property is @code{t}, then none of its -properties are rear-sticky. If the @code{rear-nonsticky} property is a -list, properties are rear-sticky @emph{unless} their names are in the -list. - -@defvar text-property-default-nonsticky -This variable holds an alist which defines the default rear-stickiness -of various text properties. Each element has the form -@code{(@var{property} . @var{nonstickiness})}, and it defines the -stickiness of a particular text property, @var{property}. - -If @var{nonstickiness} is non-@code{nil}, this means that the property -@var{property} is rear-nonsticky by default. Since all properties are -front-nonsticky by default, this makes @var{property} nonsticky in both -directions by default. - -The text properties @code{front-sticky} and @code{rear-nonsticky}, when -used, take precedence over the default @var{nonstickiness} specified in -@code{text-property-default-nonsticky}. -@end defvar - - Here are the functions that insert text with inheritance of properties: - -@defun insert-and-inherit &rest strings -Insert the strings @var{strings}, just like the function @code{insert}, -but inherit any sticky properties from the adjoining text. -@end defun - -@defun insert-before-markers-and-inherit &rest strings -Insert the strings @var{strings}, just like the function -@code{insert-before-markers}, but inherit any sticky properties from the -adjoining text. -@end defun - - @xref{Insertion}, for the ordinary insertion functions which do not -inherit. - -@node Lazy Properties -@subsection Lazy Computation of Text Properties - - Instead of computing text properties for all the text in the buffer, -you can arrange to compute the text properties for parts of the text -when and if something depends on them. - - The primitive that extracts text from the buffer along with its -properties is @code{buffer-substring}. Before examining the properties, -this function runs the abnormal hook @code{buffer-access-fontify-functions}. - -@defvar buffer-access-fontify-functions -This variable holds a list of functions for computing text properties. -Before @code{buffer-substring} copies the text and text properties for a -portion of the buffer, it calls all the functions in this list. Each of -the functions receives two arguments that specify the range of the -buffer being accessed. (The buffer itself is always the current -buffer.) -@end defvar - - The function @code{buffer-substring-no-properties} does not call these -functions, since it ignores text properties anyway. - - In order to prevent the hook functions from being called more than -once for the same part of the buffer, you can use the variable -@code{buffer-access-fontified-property}. - -@defvar buffer-access-fontified-property -If this variable's value is non-@code{nil}, it is a symbol which is used -as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed.'' - -If all the characters in the range specified for @code{buffer-substring} -have a non-@code{nil} value for this property, @code{buffer-substring} -does not call the @code{buffer-access-fontify-functions} functions. It -assumes these characters already have the right text properties, and -just copies the properties they already have. - -The normal way to use this feature is that the -@code{buffer-access-fontify-functions} functions add this property, as -well as others, to the characters they operate on. That way, they avoid -being called over and over for the same text. -@end defvar - -@node Clickable Text -@subsection Defining Clickable Text -@cindex clickable text -@cindex follow links -@cindex mouse-1 - - @dfn{Clickable text} is text that can be clicked, with either the -mouse or via a keyboard command, to produce some result. Many major -modes use clickable text to implement textual hyper-links, or -@dfn{links} for short. - - The easiest way to insert and manipulate links is to use the -@code{button} package. @xref{Buttons}. In this section, we will -explain how to manually set up clickable text in a buffer, using text -properties. For simplicity, we will refer to the clickable text as a -@dfn{link}. - - Implementing a link involves three separate steps: (1) indicating -clickability when the mouse moves over the link; (2) making @kbd{RET} -or @kbd{Mouse-2} on that link do something; and (3) setting up a -@code{follow-link} condition so that the link obeys -@code{mouse-1-click-follows-link}. - - To indicate clickability, add the @code{mouse-face} text property to -the text of the link; then Emacs will highlight the link when the -mouse moves over it. In addition, you should define a tooltip or echo -area message, using the @code{help-echo} text property. @xref{Special -Properties}. For instance, here is how Dired indicates that file -names are clickable: - -@smallexample - (if (dired-move-to-filename) - (add-text-properties - (point) - (save-excursion - (dired-move-to-end-of-filename) - (point)) - '(mouse-face highlight - help-echo "mouse-2: visit this file in other window"))) -@end smallexample - - To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to -commands that perform the desired action. Each command should check -to see whether it was called on a link, and act accordingly. For -instance, Dired's major mode keymap binds @kbd{Mouse-2} to the -following command: - -@smallexample -(defun dired-mouse-find-file-other-window (event) - "In Dired, visit the file or directory name you click on." - (interactive "e") - (let (window pos file) - (save-excursion - (setq window (posn-window (event-end event)) - pos (posn-point (event-end event))) - (if (not (windowp window)) - (error "No file chosen")) - (set-buffer (window-buffer window)) - (goto-char pos) - (setq file (dired-get-file-for-visit))) - (if (file-directory-p file) - (or (and (cdr dired-subdir-alist) - (dired-goto-subdir file)) - (progn - (select-window window) - (dired-other-window file))) - (select-window window) - (find-file-other-window (file-name-sans-versions file t))))) -@end smallexample - -@noindent -This command uses the functions @code{posn-window} and -@code{posn-point} to determine where the click occurred, and -@code{dired-get-file-for-visit} to determine which file to visit. - - Instead of binding the mouse command in a major mode keymap, you can -bind it within the link text, using the @code{keymap} text property -(@pxref{Special Properties}). For instance: - -@example -(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] 'operate-this-button) - (put-text-property link-start link-end 'keymap map)) -@end example - -@noindent -With this method, you can easily define different commands for -different links. Furthermore, the global definition of @key{RET} and -@kbd{Mouse-2} remain available for the rest of the text in the buffer. - -@vindex mouse-1-click-follows-link - The basic Emacs command for clicking on links is @kbd{Mouse-2}. -However, for compatibility with other graphical applications, Emacs -also recognizes @kbd{Mouse-1} clicks on links, provided the user -clicks on the link quickly without moving the mouse. This behavior is -controlled by the user option @code{mouse-1-click-follows-link}. -@xref{Mouse References,,, emacs, The GNU Emacs Manual}. - - To set up the link so that it obeys -@code{mouse-1-click-follows-link}, you must either (1) apply a -@code{follow-link} text or overlay property to the link text, or (2) -bind the @code{follow-link} event to a keymap (which can be a major -mode keymap or a local keymap specified via the @code{keymap} text -property). The value of the @code{follow-link} property, or the -binding for the @code{follow-link} event, acts as a ``condition'' for -the link action. This condition tells Emacs two things: the -circumstances under which a @kbd{Mouse-1} click should be regarded as -occurring ``inside'' the link, and how to compute an ``action code'' -that says what to translate the @kbd{Mouse-1} click into. The link -action condition can be one of the following: - -@table @asis -@item @code{mouse-face} -If the condition is the symbol @code{mouse-face}, a position is inside -a link if there is a non-@code{nil} @code{mouse-face} property at that -position. The action code is always @code{t}. - -For example, here is how Info mode handles @key{Mouse-1}: - -@smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) -@end smallexample - -@item a function -If the condition is a function, @var{func}, then a position @var{pos} -is inside a link if @code{(@var{func} @var{pos})} evaluates to -non-@code{nil}. The value returned by @var{func} serves as the action -code. - -For example, here is how pcvs enables @kbd{Mouse-1} to follow links on -file names only: - -@smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) -@end smallexample - -@item anything else -If the condition value is anything else, then the position is inside a -link and the condition itself is the action code. Clearly, you should -specify this kind of condition only when applying the condition via a -text or property overlay on the link text (so that it does not apply -to the entire buffer). -@end table - -@noindent -The action code tells @kbd{Mouse-1} how to follow the link: - -@table @asis -@item a string or vector -If the action code is a string or vector, the @kbd{Mouse-1} event is -translated into the first element of the string or vector; i.e., the -action of the @kbd{Mouse-1} click is the local or global binding of -that character or symbol. Thus, if the action code is @code{"foo"}, -@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]}, -@kbd{Mouse-1} translates into @key{foo}. - -@item anything else -For any other non-@code{nil} action code, the @kbd{Mouse-1} event is -translated into a @kbd{Mouse-2} event at the same position. -@end table - - To define @kbd{Mouse-1} to activate a button defined with -@code{define-button-type}, give the button a @code{follow-link} -property. The property value should be a link action condition, as -described above. @xref{Buttons}. For example, here is how Help mode -handles @kbd{Mouse-1}: - -@smallexample -(define-button-type 'help-xref - 'follow-link t - 'action #'help-button-action) -@end smallexample - - To define @kbd{Mouse-1} on a widget defined with -@code{define-widget}, give the widget a @code{:follow-link} property. -The property value should be a link action condition, as described -above. For example, here is how the @code{link} widget specifies that -a @key{Mouse-1} click shall be translated to @key{RET}: - -@smallexample -(define-widget 'link 'item - "An embedded link." - :button-prefix 'widget-link-prefix - :button-suffix 'widget-link-suffix - :follow-link "\C-m" - :help-echo "Follow the link." - :format "%[%t%]") -@end smallexample - -@defun mouse-on-link-p pos -This function returns non-@code{nil} if position @var{pos} in the -current buffer is on a link. @var{pos} can also be a mouse event -location, as returned by @code{event-start} (@pxref{Accessing Mouse}). -@end defun - -@node Fields -@subsection Defining and Using Fields -@cindex fields - - A field is a range of consecutive characters in the buffer that are -identified by having the same value (comparing with @code{eq}) of the -@code{field} property (either a text-property or an overlay property). -This section describes special functions that are available for -operating on fields. - - You specify a field with a buffer position, @var{pos}. We think of -each field as containing a range of buffer positions, so the position -you specify stands for the field containing that position. - - When the characters before and after @var{pos} are part of the same -field, there is no doubt which field contains @var{pos}: the one those -characters both belong to. When @var{pos} is at a boundary between -fields, which field it belongs to depends on the stickiness of the -@code{field} properties of the two surrounding characters (@pxref{Sticky -Properties}). The field whose property would be inherited by text -inserted at @var{pos} is the field that contains @var{pos}. - - There is an anomalous case where newly inserted text at @var{pos} -would not inherit the @code{field} property from either side. This -happens if the previous character's @code{field} property is not -rear-sticky, and the following character's @code{field} property is not -front-sticky. In this case, @var{pos} belongs to neither the preceding -field nor the following field; the field functions treat it as belonging -to an empty field whose beginning and end are both at @var{pos}. - - In all of these functions, if @var{pos} is omitted or @code{nil}, the -value of point is used by default. If narrowing is in effect, then -@var{pos} should fall within the accessible portion. @xref{Narrowing}. - -@defun field-beginning &optional pos escape-from-edge limit -This function returns the beginning of the field specified by @var{pos}. - -If @var{pos} is at the beginning of its field, and -@var{escape-from-edge} is non-@code{nil}, then the return value is -always the beginning of the preceding field that @emph{ends} at @var{pos}, -regardless of the stickiness of the @code{field} properties around -@var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the -beginning of the field is before @var{limit}, then @var{limit} will be -returned instead. -@end defun - -@defun field-end &optional pos escape-from-edge limit -This function returns the end of the field specified by @var{pos}. - -If @var{pos} is at the end of its field, and @var{escape-from-edge} is -non-@code{nil}, then the return value is always the end of the following -field that @emph{begins} at @var{pos}, regardless of the stickiness of -the @code{field} properties around @var{pos}. - -If @var{limit} is non-@code{nil}, it is a buffer position; if the end -of the field is after @var{limit}, then @var{limit} will be returned -instead. -@end defun - -@defun field-string &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string. -@end defun - -@defun field-string-no-properties &optional pos -This function returns the contents of the field specified by @var{pos}, -as a string, discarding text properties. -@end defun - -@defun delete-field &optional pos -This function deletes the text of the field specified by @var{pos}. -@end defun - -@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property -This function ``constrains'' @var{new-pos} to the field that -@var{old-pos} belongs to---in other words, it returns the position -closest to @var{new-pos} that is in the same field as @var{old-pos}. - -If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses -the value of point instead, and moves point to the resulting position -as well as returning it. - -If @var{old-pos} is at the boundary of two fields, then the acceptable -final positions depend on the argument @var{escape-from-edge}. If -@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in -the field whose @code{field} property equals what new characters -inserted at @var{old-pos} would inherit. (This depends on the -stickiness of the @code{field} property for the characters before and -after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, -@var{new-pos} can be anywhere in the two adjacent fields. -Additionally, if two fields are separated by another field with the -special value @code{boundary}, then any point within this special -field is also considered to be ``on the boundary.'' - -Commands like @kbd{C-a} with no argumemt, that normally move backward -to a specific kind of location and stay there once there, probably -should specify @code{nil} for @var{escape-from-edge}. Other motion -commands that check fields should probably pass @code{t}. - -If the optional argument @var{only-in-line} is non-@code{nil}, and -constraining @var{new-pos} in the usual way would move it to a different -line, @var{new-pos} is returned unconstrained. This used in commands -that move by line, such as @code{next-line} and -@code{beginning-of-line}, so that they respect field boundaries only in -the case where they can still move to the right line. - -If the optional argument @var{inhibit-capture-property} is -non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that -name, then any field boundaries are ignored. - -You can cause @code{constrain-to-field} to ignore all field boundaries -(and so never constrain anything) by binding the variable -@code{inhibit-field-text-motion} to a non-@code{nil} value. -@end defun - -@node Not Intervals -@subsection Why Text Properties are not Intervals -@cindex intervals - - Some editors that support adding attributes to text in the buffer do -so by letting the user specify ``intervals'' within the text, and adding -the properties to the intervals. Those editors permit the user or the -programmer to determine where individual intervals start and end. We -deliberately provided a different sort of interface in Emacs Lisp to -avoid certain paradoxical behavior associated with text modification. - - If the actual subdivision into intervals is meaningful, that means you -can distinguish between a buffer that is just one interval with a -certain property, and a buffer containing the same text subdivided into -two intervals, both of which have that property. - - Suppose you take the buffer with just one interval and kill part of -the text. The text remaining in the buffer is one interval, and the -copy in the kill ring (and the undo list) becomes a separate interval. -Then if you yank back the killed text, you get two intervals with the -same properties. Thus, editing does not preserve the distinction -between one interval and two. - - Suppose we ``fix'' this problem by coalescing the two intervals when -the text is inserted. That works fine if the buffer originally was a -single interval. But suppose instead that we have two adjacent -intervals with the same properties, and we kill the text of one interval -and yank it back. The same interval-coalescence feature that rescues -the other case causes trouble in this one: after yanking, we have just -one interval. One again, editing does not preserve the distinction -between one interval and two. - - Insertion of text at the border between intervals also raises -questions that have no satisfactory answer. - - However, it is easy to arrange for editing to behave consistently for -questions of the form, ``What are the properties of this character?'' -So we have decided these are the only questions that make sense; we have -not implemented asking questions about where intervals start or end. - - In practice, you can usually use the text property search functions in -place of explicit interval boundaries. You can think of them as finding -the boundaries of intervals, assuming that intervals are always -coalesced whenever possible. @xref{Property Search}. - - Emacs also provides explicit intervals as a presentation feature; see -@ref{Overlays}. - -@node Substitution -@section Substituting for a Character Code - - The following functions replace characters within a specified region -based on their character codes. - -@defun subst-char-in-region start end old-char new-char &optional noundo -@cindex replace characters -This function replaces all occurrences of the character @var{old-char} -with the character @var{new-char} in the region of the current buffer -defined by @var{start} and @var{end}. - -@cindex undo avoidance -If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does -not record the change for undo and does not mark the buffer as modified. -This was useful for controlling the old selective display feature -(@pxref{Selective Display}). - -@code{subst-char-in-region} does not move point and returns -@code{nil}. - -@example -@group ----------- Buffer: foo ---------- -This is the contents of the buffer before. ----------- Buffer: foo ---------- -@end group - -@group -(subst-char-in-region 1 20 ?i ?X) - @result{} nil - ----------- Buffer: foo ---------- -ThXs Xs the contents of the buffer before. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@deffn Command translate-region start end table -This function applies a translation table to the characters in the -buffer between positions @var{start} and @var{end}. - -The translation table @var{table} is a string or a char-table; -@code{(aref @var{table} @var{ochar})} gives the translated character -corresponding to @var{ochar}. If @var{table} is a string, any -characters with codes larger than the length of @var{table} are not -altered by the translation. - -The return value of @code{translate-region} is the number of -characters that were actually changed by the translation. This does -not count characters that were mapped into themselves in the -translation table. -@end deffn - -@node Registers -@section Registers -@cindex registers - - A register is a sort of variable used in Emacs editing that can hold a -variety of different kinds of values. Each register is named by a -single character. All @acronym{ASCII} characters and their meta variants -(but with the exception of @kbd{C-g}) can be used to name registers. -Thus, there are 255 possible registers. A register is designated in -Emacs Lisp by the character that is its name. - -@defvar register-alist -This variable is an alist of elements of the form @code{(@var{name} . -@var{contents})}. Normally, there is one element for each Emacs -register that has been used. - -The object @var{name} is a character (an integer) identifying the -register. -@end defvar - - The @var{contents} of a register can have several possible types: - -@table @asis -@item a number -A number stands for itself. If @code{insert-register} finds a number -in the register, it converts the number to decimal. - -@item a marker -A marker represents a buffer position to jump to. - -@item a string -A string is text saved in the register. - -@item a rectangle -A rectangle is represented by a list of strings. - -@item @code{(@var{window-configuration} @var{position})} -This represents a window configuration to restore in one frame, and a -position to jump to in the current buffer. - -@item @code{(@var{frame-configuration} @var{position})} -This represents a frame configuration to restore, and a position -to jump to in the current buffer. - -@item (file @var{filename}) -This represents a file to visit; jumping to this value visits file -@var{filename}. - -@item (file-query @var{filename} @var{position}) -This represents a file to visit and a position in it; jumping to this -value visits file @var{filename} and goes to buffer position -@var{position}. Restoring this type of position asks the user for -confirmation first. -@end table - - The functions in this section return unpredictable values unless -otherwise stated. - -@defun get-register reg -This function returns the contents of the register -@var{reg}, or @code{nil} if it has no contents. -@end defun - -@defun set-register reg value -This function sets the contents of register @var{reg} to @var{value}. -A register can be set to any value, but the other register functions -expect only certain data types. The return value is @var{value}. -@end defun - -@deffn Command view-register reg -This command displays what is contained in register @var{reg}. -@end deffn - -@deffn Command insert-register reg &optional beforep -This command inserts contents of register @var{reg} into the current -buffer. - -Normally, this command puts point before the inserted text, and the -mark after it. However, if the optional second argument @var{beforep} -is non-@code{nil}, it puts the mark before and point after. -You can pass a non-@code{nil} second argument @var{beforep} to this -function interactively by supplying any prefix argument. - -If the register contains a rectangle, then the rectangle is inserted -with its upper left corner at point. This means that text is inserted -in the current line and underneath it on successive lines. - -If the register contains something other than saved text (a string) or -a rectangle (a list), currently useless things happen. This may be -changed in the future. -@end deffn - -@node Transposition -@section Transposition of Text - - This subroutine is used by the transposition commands. - -@defun transpose-regions start1 end1 start2 end2 &optional leave-markers -This function exchanges two nonoverlapping portions of the buffer. -Arguments @var{start1} and @var{end1} specify the bounds of one portion -and arguments @var{start2} and @var{end2} specify the bounds of the -other portion. - -Normally, @code{transpose-regions} relocates markers with the transposed -text; a marker previously positioned within one of the two transposed -portions moves along with that portion, thus remaining between the same -two characters in their new position. However, if @var{leave-markers} -is non-@code{nil}, @code{transpose-regions} does not do this---it leaves -all markers unrelocated. -@end defun - -@node Base 64 -@section Base 64 Encoding -@cindex base 64 encoding - - Base 64 code is used in email to encode a sequence of 8-bit bytes as -a longer sequence of @acronym{ASCII} graphic characters. It is defined in -Internet RFC@footnote{ -An RFC, an acronym for @dfn{Request for Comments}, is a numbered -Internet informational document describing a standard. RFCs are -usually written by technical experts acting on their own initiative, -and are traditionally written in a pragmatic, experience-driven -manner. -}2045. This section describes the functions for -converting to and from this code. - -@deffn Command base64-encode-region beg end &optional no-line-break -This function converts the region from @var{beg} to @var{end} into base -64 code. It returns the length of the encoded text. An error is -signaled if a character in the region is multibyte, i.e.@: in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the output is just one long line. -@end deffn - -@deffn Command base64-encode-string string &optional no-line-break -This function converts the string @var{string} into base 64 code. It -returns a string containing the encoded text. As for -@code{base64-encode-region}, an error is signaled if a character in the -string is multibyte. - -Normally, this function inserts newline characters into the encoded -text, to avoid overlong lines. However, if the optional argument -@var{no-line-break} is non-@code{nil}, these newlines are not added, so -the result string is just one long line. -@end deffn - -@defun base64-decode-region beg end -This function converts the region from @var{beg} to @var{end} from base -64 code into the corresponding decoded text. It returns the length of -the decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@defun base64-decode-string string -This function converts the string @var{string} from base 64 code into -the corresponding decoded text. It returns a unibyte string containing the -decoded text. - -The decoding functions ignore newline characters in the encoded text. -@end defun - -@node MD5 Checksum -@section MD5 Checksum -@cindex MD5 checksum -@cindex message digest computation - - MD5 cryptographic checksums, or @dfn{message digests}, are 128-bit -``fingerprints'' of a document or program. They are used to verify -that you have an exact and unaltered copy of the data. The algorithm -to calculate the MD5 message digest is defined in Internet -RFC@footnote{ -For an explanation of what is an RFC, see the footnote in @ref{Base -64}. -}1321. This section describes the Emacs facilities for computing -message digests. - -@defun md5 object &optional start end coding-system noerror -This function returns the MD5 message digest of @var{object}, which -should be a buffer or a string. - -The two optional arguments @var{start} and @var{end} are character -positions specifying the portion of @var{object} to compute the -message digest for. If they are @code{nil} or omitted, the digest is -computed for the whole of @var{object}. - -The function @code{md5} does not compute the message digest directly -from the internal Emacs representation of the text (@pxref{Text -Representations}). Instead, it encodes the text using a coding -system, and computes the message digest from the encoded text. The -optional fourth argument @var{coding-system} specifies which coding -system to use for encoding the text. It should be the same coding -system that you used to read the text, or that you used or will use -when saving or sending the text. @xref{Coding Systems}, for more -information about coding systems. - -If @var{coding-system} is @code{nil} or omitted, the default depends -on @var{object}. If @var{object} is a buffer, the default for -@var{coding-system} is whatever coding system would be chosen by -default for writing this text into a file. If @var{object} is a -string, the user's most preferred coding system (@pxref{Recognize -Coding, prefer-coding-system, the description of -@code{prefer-coding-system}, emacs, GNU Emacs Manual}) is used. - -Normally, @code{md5} signals an error if the text can't be encoded -using the specified or chosen coding system. However, if -@var{noerror} is non-@code{nil}, it silently uses @code{raw-text} -coding instead. -@end defun - -@node Atomic Changes -@section Atomic Change Groups -@cindex atomic changes - - In data base terminology, an @dfn{atomic} change is an indivisible -change---it can succeed entirely or it can fail entirely, but it -cannot partly succeed. A Lisp program can make a series of changes to -one or several buffers as an @dfn{atomic change group}, meaning that -either the entire series of changes will be installed in their buffers -or, in case of an error, none of them will be. - - To do this for one buffer, the one already current, simply write a -call to @code{atomic-change-group} around the code that makes the -changes, like this: - -@example -(atomic-change-group - (insert foo) - (delete-region x y)) -@end example - -@noindent -If an error (or other nonlocal exit) occurs inside the body of -@code{atomic-change-group}, it unmakes all the changes in that buffer -that were during the execution of the body. This kind of change group -has no effect on any other buffers---any such changes remain. - - If you need something more sophisticated, such as to make changes in -various buffers constitute one atomic group, you must directly call -lower-level functions that @code{atomic-change-group} uses. - -@defun prepare-change-group &optional buffer -This function sets up a change group for buffer @var{buffer}, which -defaults to the current buffer. It returns a ``handle'' that -represents the change group. You must use this handle to activate the -change group and subsequently to finish it. -@end defun - - To use the change group, you must @dfn{activate} it. You must do -this before making any changes in the text of @var{buffer}. - -@defun activate-change-group handle -This function activates the change group that @var{handle} designates. -@end defun - - After you activate the change group, any changes you make in that -buffer become part of it. Once you have made all the desired changes -in the buffer, you must @dfn{finish} the change group. There are two -ways to do this: you can either accept (and finalize) all the changes, -or cancel them all. - -@defun accept-change-group handle -This function accepts all the changes in the change group specified by -@var{handle}, making them final. -@end defun - -@defun cancel-change-group handle -This function cancels and undoes all the changes in the change group -specified by @var{handle}. -@end defun - - Your code should use @code{unwind-protect} to make sure the group is -always finished. The call to @code{activate-change-group} should be -inside the @code{unwind-protect}, in case the user types @kbd{C-g} -just after it runs. (This is one reason why -@code{prepare-change-group} and @code{activate-change-group} are -separate functions, because normally you would call -@code{prepare-change-group} before the start of that -@code{unwind-protect}.) Once you finish the group, don't use the -handle again---in particular, don't try to finish the same group -twice. - - To make a multibuffer change group, call @code{prepare-change-group} -once for each buffer you want to cover, then use @code{nconc} to -combine the returned values, like this: - -@example -(nconc (prepare-change-group buffer-1) - (prepare-change-group buffer-2)) -@end example - -You can then activate the multibuffer change group with a single call -to @code{activate-change-group}, and finish it with a single call to -@code{accept-change-group} or @code{cancel-change-group}. - - Nested use of several change groups for the same buffer works as you -would expect. Non-nested use of change groups for the same buffer -will get Emacs confused, so don't let it happen; the first change -group you start for any given buffer should be the last one finished. - -@node Change Hooks -@section Change Hooks -@cindex change hooks -@cindex hooks for text changes - - These hook variables let you arrange to take notice of all changes in -all buffers (or in a particular buffer, if you make them buffer-local). -See also @ref{Special Properties}, for how to detect changes to specific -parts of the text. - - The functions you use in these hooks should save and restore the match -data if they do anything that uses regular expressions; otherwise, they -will interfere in bizarre ways with the editing operations that call -them. - -@defvar before-change-functions -This variable holds a list of functions to call before any buffer -modification. Each function gets two arguments, the beginning and end -of the region that is about to change, represented as integers. The -buffer that is about to change is always the current buffer. -@end defvar - -@defvar after-change-functions -This variable holds a list of functions to call after any buffer -modification. Each function receives three arguments: the beginning and -end of the region just changed, and the length of the text that existed -before the change. All three arguments are integers. The buffer that's -about to change is always the current buffer. - -The length of the old text is the difference between the buffer positions -before and after that text as it was before the change. As for the -changed text, its length is simply the difference between the first two -arguments. -@end defvar - - Output of messages into the @samp{*Messages*} buffer does not -call these functions. - -@defmac combine-after-change-calls body@dots{} -The macro executes @var{body} normally, but arranges to call the -after-change functions just once for a series of several changes---if -that seems safe. - -If a program makes several text changes in the same area of the buffer, -using the macro @code{combine-after-change-calls} around that part of -the program can make it run considerably faster when after-change hooks -are in use. When the after-change hooks are ultimately called, the -arguments specify a portion of the buffer including all of the changes -made within the @code{combine-after-change-calls} body. - -@strong{Warning:} You must not alter the values of -@code{after-change-functions} within -the body of a @code{combine-after-change-calls} form. - -@strong{Warning:} if the changes you combine occur in widely scattered -parts of the buffer, this will still work, but it is not advisable, -because it may lead to inefficient behavior for some change hook -functions. -@end defmac - -@defvar first-change-hook -This variable is a normal hook that is run whenever a buffer is changed -that was previously in the unmodified state. -@end defvar - -@defvar inhibit-modification-hooks -If this variable is non-@code{nil}, all of the change hooks are -disabled; none of them run. This affects all the hook variables -described above in this section, as well as the hooks attached to -certain special text properties (@pxref{Special Properties}) and overlay -properties (@pxref{Overlay Properties}). - -Also, this variable is bound to non-@code{nil} while running those -same hook variables, so that by default modifying the buffer from -a modification hook does not cause other modification hooks to be run. -If you do want modification hooks to be run in a particular piece of -code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. -@end defvar - -@ignore - arch-tag: 3721e738-a1cb-4085-bc1a-6cb8d8e1d32b -@end ignore diff --git a/doc/lispref/tindex.pl b/doc/lispref/tindex.pl deleted file mode 100755 index b9cff85d827..00000000000 --- a/doc/lispref/tindex.pl +++ /dev/null @@ -1,126 +0,0 @@ -#! /usr/bin/perl - -# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -# 2008, 2009 Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -require 5; -use Getopt::Long; - -my $USAGE = < \$help, 'version' => \$version, - 'old=s' => \$old); -if ($version) { - print "0.1\n"; - exit 0; -} elsif (!$rc || !$old || @ARGV) { - print $USAGE; - exit 1; -} elsif ($help) { - print $USAGE; - exit 0; -} - -# Fill the hash %tindex with associations VAR -> COUNT where -# the keys VAR are identifiers mentioned in @tindex lines in the older -# files to process and COUNT is the number of times they are seen in -# the files. - -my %tindex; -my %removed; -my @old_files = glob "$old/*.texi"; -my @new_files = glob "*.texi"; -fatal ("No Texinfo files found in `$old'") unless @old_files; -fatal ("No Texinfo files found in current directory") unless @new_files; - -print "Scanning old files for \@tindex lines\n"; -foreach $file (@old_files) { - open (IN, "<$file") or fatal "Cannot open $file: $!"; - while () { - ++$tindex{$1} if /^\s*\@tindex\s+(\S+)/; - } - close IN; -} - -# Process current files and remove those @tindex lines which we -# know were already present in the files scanned above. - -print "Removing old \@tindex lines\n"; -foreach $file (@new_files) { - my $modified = 0; - my $contents = ""; - - open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!"; - while () { - if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) { - ++$removed{$1}; - $modified = 1; - } else { - $contents = $contents . $_; - } - } - - close IN; - - if ($modified) { - print " $file\n"; - system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!"; - open (OUT, ">$file") or fatal "Cannot open $file for writing: $!"; - print OUT $contents; - close OUT; - } -} - -# Print a list of identifiers removed. - -print "Removed \@tindex commands for:\n"; -my $key; -foreach $key (keys %removed) { - print " $key\n"; -} - -# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi deleted file mode 100644 index fcf91d878ac..00000000000 --- a/doc/lispref/tips.texi +++ /dev/null @@ -1,1095 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/tips -@node Tips, GNU Emacs Internals, GPL, Top -@appendix Tips and Conventions -@cindex tips for writing Lisp -@cindex standards of coding style -@cindex coding standards - - This chapter describes no additional features of Emacs Lisp. Instead -it gives advice on making effective use of the features described in the -previous chapters, and describes conventions Emacs Lisp programmers -should follow. - - You can automatically check some of the conventions described below by -running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. -It cannot check all of the conventions, and not all the warnings it -gives necessarily correspond to problems, but it is worth examining them -all. - -@menu -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. -@end menu - -@node Coding Conventions -@section Emacs Lisp Coding Conventions - -@cindex coding conventions in Emacs Lisp - Here are conventions that you should follow when writing Emacs Lisp -code intended for widespread use: - -@itemize @bullet -@item -Simply loading a package should not change Emacs's editing behavior. -Include a command or commands to enable and disable the feature, -or to invoke it. - -This convention is mandatory for any file that includes custom -definitions. If fixing such a file to follow this convention requires -an incompatible change, go ahead and make the incompatible change; -don't postpone it. - -@item -You should choose a short word to distinguish your program from other -Lisp programs. The names of all global variables, constants, and -functions in your program should begin with that chosen prefix. -Separate the prefix from the rest of the name with a hyphen, @samp{-}. -This practice helps avoid name conflicts, since all global variables -in Emacs Lisp share the same name space, and all functions share -another name space@footnote{The benefits of a Common Lisp-style -package system are considered not to outweigh the costs.} - -Occasionally, for a command name intended for users to use, it is more -convenient if some words come before the package's name prefix. And -constructs that define functions, variables, etc., work better if they -start with @samp{defun} or @samp{defvar}, so put the name prefix later -on in the name. - -This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---such as -@code{copy-list}. Believe it or not, there is more than one plausible -way to define @code{copy-list}. Play it safe; append your name prefix -to produce a name like @code{foo-copy-list} or @code{mylib-copy-list} -instead. - -If you write a function that you think ought to be added to Emacs under -a certain name, such as @code{twiddle-files}, don't call it by that name -in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add -it to Emacs. If and when we do, we can change the name easily enough. - -If one prefix is insufficient, your package can use two or three -alternative common prefixes, so long as they make sense. - -@item -Put a call to @code{provide} at the end of each separate Lisp file. -@xref{Named Features}. - -@item -If a file requires certain other Lisp programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. Also, use @code{require} to make sure they are loaded. -x@xref{Named Features}. - -@item -If a file @var{foo} uses a macro defined in another file @var{bar}, -but does not use any functions or variables defined in @var{bar}, then -@var{foo} should contain the following expression: - -@example -(eval-when-compile (require '@var{bar})) -@end example - -@noindent -This tells Emacs to load @var{bar} just before byte-compiling -@var{foo}, so that the macro definition is available during -compilation. Using @code{eval-when-compile} avoids loading @var{bar} -when the compiled version of @var{foo} is @emph{used}. It should be -called before the first use of the macro in the file. @xref{Compiling -Macros}. - -@item -Please don't require the @code{cl} package of Common Lisp extensions at -run time. Use of this package is optional, and it is not part of the -standard Emacs namespace. If your package loads @code{cl} at run time, -that could cause name clashes for users who don't use that package. - -However, there is no problem with using the @code{cl} package at -compile time, with @code{(eval-when-compile (require 'cl))}. That's -sufficient for using the macros in the @code{cl} package, because the -compiler expands them before generating the byte-code. - -@item -When defining a major mode, please follow the major mode -conventions. @xref{Major Mode Conventions}. - -@item -When defining a minor mode, please follow the minor mode -conventions. @xref{Minor Mode Conventions}. - -@item -If the purpose of a function is to tell you whether a certain -condition is true or false, give the function a name that ends in -@samp{p} (which stands for ``predicate''). If the name is one word, -add just @samp{p}; if the name is multiple words, add @samp{-p}. -Examples are @code{framep} and @code{frame-live-p}. - -@item -If the purpose of a variable is to store a single function, give it a -name that ends in @samp{-function}. If the purpose of a variable is -to store a list of functions (i.e., the variable is a hook), please -follow the naming conventions for hooks. @xref{Hooks}. - -@item -@cindex unloading packages, preparing for -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-hook}, where @var{feature} is the name of -the feature the package provides, and make it undo any such changes. -Using @code{unload-feature} to unload the file will run this function. -@xref{Unloading}. - -@item -It is a bad idea to define aliases for the Emacs primitives. Normally -you should use the standard names instead. The case where an alias -may be useful is where it facilitates backwards compatibility or -portability. - -@item -If a package needs to define an alias or a new function for -compatibility with some other version of Emacs, name it with the package -prefix, not with the raw name with which it occurs in the other version. -Here is an example from Gnus, which provides many examples of such -compatibility issues. - -@example -(defalias 'gnus-point-at-bol - (if (fboundp 'point-at-bol) - 'point-at-bol - 'line-beginning-position)) -@end example - -@item -Redefining or advising an Emacs primitive is a bad idea. It may do -the right thing for a particular program, but there is no telling what -other programs might break as a result. - -@item -It is likewise a bad idea for one Lisp package to advise a function in -another Lisp package (@pxref{Advising Functions}). - -@item -Avoid using @code{eval-after-load} in libraries and packages -(@pxref{Hooks for Loading}). This feature is meant for personal -customizations; using it in a Lisp program is unclean, because it -modifies the behavior of another Lisp file in a way that's not visible -in that file. This is an obstacle for debugging, much like advising a -function in the other package. - -@item -If a file does replace any of the standard functions or library -programs of Emacs, prominent comments at the beginning of the file -should say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Constructs that define a function or variable should be macros, -not functions, and their names should start with @samp{def}. - -@item -A macro that defines a function or variable should have a name that -starts with @samp{define-}. The macro should receive the name to be -defined as the first argument. That will help various tools find the -definition automatically. Avoid constructing the names in the macro -itself, since that would confuse these tools. - -@item -Please keep the names of your Emacs Lisp source files to 13 characters -or less. This way, if the files are compiled, the compiled files' names -will be 14 characters or less, which is short enough to fit on all kinds -of Unix systems. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for special-purpose buffers.) The users will find Emacs more -coherent if all libraries use the same conventions. - -@item -If your program contains non-ASCII characters in string or character -constants, you should make sure Emacs always decodes these characters -the same way, regardless of the user's settings. The easiest way to -do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding -System Basics}), and specify that coding in the @samp{-*-} line or the -local variables list. @xref{File variables, , Local Variables in -Files, emacs, The GNU Emacs Manual}. - -@example -;; XXX.el -*- coding: utf-8-emacs; -*- -@end example - -@item -Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the -default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by -themselves; Lisp programmers find this disconcerting. - -@item -Please put a copyright notice and copying permission notice on the -file if you distribute copies. Use a notice like this one: - -@smallexample -;; Copyright (C) @var{year} @var{name} - -;; This program is free software: you can redistribute it and/or -;; modify it under the terms of the GNU General Public License as -;; published by the Free Software Foundation, either version 3 of -;; the License, or (at your option) any later version. - -;; This program is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with this program. If not, see . -@end smallexample - -If you have signed papers to assign the copyright to the Foundation, -then use @samp{Free Software Foundation, Inc.} as @var{name}. -Otherwise, use your name. @xref{Library Headers}. -@end itemize - -@node Key Binding Conventions -@section Key Binding Conventions -@cindex key binding, conventions for - -@itemize @bullet -@item -@cindex mouse-2 -@cindex references, following -Many special major modes, like Dired, Info, Compilation, and Occur, -are designed to handle read-only text that contains @dfn{hyper-links}. -Such a major mode should redefine @kbd{mouse-2} and @key{RET} to -follow the links. It should also set up a @code{follow-link} -condition, so that the link obeys @code{mouse-1-click-follows-link}. -@xref{Clickable Text}. @xref{Buttons}, for an easy method of -implementing such clickable links. - -@item -@cindex reserved keys -@cindex keys, reserved -Don't define @kbd{C-c @var{letter}} as a key in Lisp programs. -Sequences consisting of @kbd{C-c} and a letter (either upper or lower -case) are reserved for users; they are the @strong{only} sequences -reserved for users, so do not block them. - -Changing all the Emacs major modes to respect this convention was a -lot of work; abandoning this convention would make that work go to -waste, and inconvenience users. Please comply with it. - -@item -Function keys @key{F5} through @key{F9} without modifier keys are -also reserved for users to define. - -@item -Sequences consisting of @kbd{C-c} followed by a control character or a -digit are reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, -@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by any other punctuation -character are allocated for minor modes. Using them in a major mode is -not absolutely prohibited, but if you do that, the major mode binding -may be shadowed from time to time by minor modes. - -@item -Don't bind @kbd{C-h} following any prefix character (including -@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically -available as a help character for listing the subcommands of the -prefix character. - -@item -Don't bind a key sequence ending in @key{ESC} except following another -@key{ESC}. (That is, it is OK to bind a sequence ending in -@kbd{@key{ESC} @key{ESC}}.) - -The reason for this rule is that a non-prefix binding for @key{ESC} in -any context prevents recognition of escape sequences as function keys in -that context. - -@item -Anything which acts like a temporary mode or state which the user can -enter and leave should define @kbd{@key{ESC} @key{ESC}} or -@kbd{@key{ESC} @key{ESC} @key{ESC}} as a way to escape. - -For a state which accepts ordinary Emacs commands, or more generally any -kind of state in which @key{ESC} followed by a function key or arrow key -is potentially meaningful, then you must not define @kbd{@key{ESC} -@key{ESC}}, since that would preclude recognizing an escape sequence -after @key{ESC}. In these states, you should define @kbd{@key{ESC} -@key{ESC} @key{ESC}} as the way to escape. Otherwise, define -@kbd{@key{ESC} @key{ESC}} instead. -@end itemize - -@node Programming Tips -@section Emacs Programming Tips -@cindex programming conventions - - Following these conventions will make your program fit better -into Emacs when it runs. - -@itemize @bullet -@item -Don't use @code{next-line} or @code{previous-line} in programs; nearly -always, @code{forward-line} is more convenient as well as more -predictable and robust. @xref{Text Lines}. - -@item -Don't call functions that set the mark, unless setting the mark is one -of the intended features of your program. The mark is a user-level -feature, so it is incorrect to change the mark except to supply a value -for the user's benefit. @xref{The Mark}. - -In particular, don't use any of these functions: - -@itemize @bullet -@item -@code{beginning-of-buffer}, @code{end-of-buffer} -@item -@code{replace-string}, @code{replace-regexp} -@item -@code{insert-file}, @code{insert-buffer} -@end itemize - -If you just want to move point, or replace a certain string, or insert -a file or buffer's contents, without any of the other features -intended for interactive users, you can replace these functions with -one or two lines of simple Lisp code. - -@item -Use lists rather than vectors, except when there is a particular reason -to use a vector. Lisp has more facilities for manipulating lists than -for vectors, and working with lists is usually more convenient. - -Vectors are advantageous for tables that are substantial in size and are -accessed in random order (not searched front to back), provided there is -no need to insert or delete elements (only lists allow that). - -@item -The recommended way to show a message in the echo area is with -the @code{message} function, not @code{princ}. @xref{The Echo Area}. - -@item -When you encounter an error condition, call the function @code{error} -(or @code{signal}). The function @code{error} does not return. -@xref{Signaling Errors}. - -Don't use @code{message}, @code{throw}, @code{sleep-for}, or -@code{beep} to report errors. - -@item -An error message should start with a capital letter but should not end -with a period. - -@item -A question asked in the minibuffer with @code{y-or-n-p} or -@code{yes-or-no-p} should start with a capital letter and end with -@samp{? }. - -@item -When you mention a default value in a minibuffer prompt, -put it and the word @samp{default} inside parentheses. -It should look like this: - -@example -Enter the answer (default 42): -@end example - -@item -In @code{interactive}, if you use a Lisp expression to produce a list -of arguments, don't try to provide the ``correct'' default values for -region or position arguments. Instead, provide @code{nil} for those -arguments if they were not specified, and have the function body -compute the default value when the argument is @code{nil}. For -instance, write this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos}))) - (unless pos (setq pos @var{default-pos})) - ...) -@end example - -@noindent -rather than this: - -@example -(defun foo (pos) - (interactive - (list (if @var{specified} @var{specified-pos} - @var{default-pos}))) - ...) -@end example - -@noindent -This is so that repetition of the command will recompute -these defaults based on the current circumstances. - -You do not need to take such precautions when you use interactive -specs @samp{d}, @samp{m} and @samp{r}, because they make special -arrangements to recompute the argument values on repetition of the -command. - -@item -Many commands that take a long time to execute display a message that -says something like @samp{Operating...} when they start, and change it -to @samp{Operating...done} when they finish. Please keep the style of -these messages uniform: @emph{no} space around the ellipsis, and -@emph{no} period after @samp{done}. @xref{Progress}, for an easy way -to generate such messages. - -@item -Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} -command does: use a new local keymap that contains one command defined -to switch back to the old local keymap. Or do what the -@code{edit-options} command does: switch to another buffer and let the -user switch back at will. @xref{Recursive Editing}. -@end itemize - -@node Compilation Tips -@section Tips for Making Compiled Code Fast -@cindex execution speed -@cindex speedups - - Here are ways of improving the execution speed of byte-compiled -Lisp programs. - -@itemize @bullet -@item -@cindex profiling -@cindex timing programs -@cindex @file{elp.el} -Profile your program with the @file{elp} library. See the file -@file{elp.el} for instructions. - -@item -@cindex @file{benchmark.el} -@cindex benchmarking -Check the speed of individual Emacs Lisp forms using the -@file{benchmark} library. See the functions @code{benchmark-run} and -@code{benchmark-run-compiled} in @file{benchmark.el}. - -@item -Use iteration rather than recursion whenever possible. -Function calls are slow in Emacs Lisp even when a compiled function -is calling another compiled function. - -@item -Using the primitive list-searching functions @code{memq}, @code{member}, -@code{assq}, or @code{assoc} is even faster than explicit iteration. It -can be worth rearranging a data structure so that one of these primitive -search functions can be used. - -@item -Certain built-in functions are handled specially in byte-compiled code, -avoiding the need for an ordinary function call. It is a good idea to -use these functions rather than alternatives. To see whether a function -is handled specially by the compiler, examine its @code{byte-compile} -property. If the property is non-@code{nil}, then the function is -handled specially. - -For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}): - -@example -@group -(get 'aref 'byte-compile) - @result{} byte-compile-two-args -@end group -@end example - -@item -If calling a small function accounts for a substantial part of your -program's running time, make the function inline. This eliminates -the function call overhead. Since making a function inline reduces -the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough that users care about -the speed. @xref{Inline Functions}. -@end itemize - -@node Warning Tips -@section Tips for Avoiding Compiler Warnings -@cindex byte compiler warnings, how to avoid - -@itemize @bullet -@item -Try to avoid compiler warnings about undefined free variables, by adding -dummy @code{defvar} definitions for these variables, like this: - -@example -(defvar foo) -@end example - -Such a definition has no effect except to tell the compiler -not to warn about uses of the variable @code{foo} in this file. - -@item -If you use many functions and variables from a certain file, you can -add a @code{require} for that package to avoid compilation warnings -for them. For instance, - -@example -(eval-when-compile - (require 'foo)) -@end example - -@item -If you bind a variable in one function, and use it or set it in -another function, the compiler warns about the latter function unless -the variable has a definition. But adding a definition would be -unclean if the variable has a short name, since Lisp packages should -not define short variable names. The right thing to do is to rename -this variable to start with the name prefix used for the other -functions and variables in your package. - -@item -The last resort for avoiding a warning, when you want to do something -that usually is a mistake but it's not a mistake in this one case, -is to put a call to @code{with-no-warnings} around it. -@end itemize - -@node Documentation Tips -@section Tips for Documentation Strings -@cindex documentation strings, conventions and tips - -@findex checkdoc-minor-mode - Here are some tips and conventions for the writing of documentation -strings. You can check many of these conventions by running the command -@kbd{M-x checkdoc-minor-mode}. - -@itemize @bullet -@item -Every command, function, or variable intended for users to know about -should have a documentation string. - -@item -An internal variable or subroutine of a Lisp program might as well have -a documentation string. In earlier Emacs versions, you could save space -by using a comment instead of a documentation string, but that is no -longer the case---documentation strings now take up very little space in -a running Emacs. - -@item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line should not be wider than 67 characters -or it will look bad in the output of @code{apropos}. - -You can fill the text if that looks good. However, rather than blindly -filling the entire documentation string, you can often make it much more -readable by choosing certain line breaks with care. Use blank lines -between topics if the documentation string is long. - -@item -The first line of the documentation string should consist of one or two -complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if that line's contents don't -stand on their own, the result looks bad. In particular, start the -first line with a capital letter and end with a period. - -For a function, the first line should briefly answer the question, -``What does this function do?'' For a variable, the first line should -briefly answer the question, ``What does this value mean?'' - -Don't limit the documentation string to one line; use as many lines as -you need to explain the details of how to use the function or -variable. Please use complete sentences for the rest of the text too. - -@item -When the user tries to use a disabled command, Emacs displays just the -first paragraph of its documentation string---everything through the -first blank line. If you wish, you can choose which information to -include before the first blank line so as to make this display useful. - -@item -The first line should mention all the important arguments of the -function, and should mention them in the order that they are written -in a function call. If the function has many arguments, then it is -not feasible to mention them all in the first line; in that case, the -first line should mention the first few arguments, including the most -important arguments. - -@item -When a function's documentation string mentions the value of an argument -of the function, use the argument name in capital letters as if it were -a name for that value. Thus, the documentation string of the function -@code{eval} refers to its second argument as @samp{FORM}, because the -actual argument name is @code{form}: - -@example -Evaluate FORM and return its value. -@end example - -Also write metasyntactic variables in capital letters, such as when you -show the decomposition of a list or vector into subunits, some of which -may vary. @samp{KEY} and @samp{VALUE} in the following example -illustrate this practice: - -@example -The argument TABLE should be an alist whose elements -have the form (KEY . VALUE). Here, KEY is ... -@end example - -@item -Never change the case of a Lisp symbol when you mention it in a doc -string. If the symbol's name is @code{foo}, write ``foo,'' not -``Foo'' (which is a different symbol). - -This might appear to contradict the policy of writing function -argument values, but there is no real contradiction; the argument -@emph{value} is not the same thing as the @emph{symbol} which the -function uses to hold the value. - -If this puts a lower-case letter at the beginning of a sentence -and that annoys you, rewrite the sentence so that the symbol -is not at the start of it. - -@item -Do not start or end a documentation string with whitespace. - -@item -@strong{Do not} indent subsequent lines of a documentation string so -that the text is lined up in the source code with the text of the first -line. This looks nice in the source code, but looks bizarre when users -view the documentation. Remember that the indentation before the -starting double-quote is not part of the string! - -@anchor{Docstring hyperlinks} -@item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifnottex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we use a different -convention, with single-quotes for all symbols.) -@end ifnottex - -@cindex hyperlinks in documentation strings -Help mode automatically creates a hyperlink when a documentation string -uses a symbol name inside single quotes, if the symbol has either a -function or a variable definition. You do not need to do anything -special to make use of this feature. However, when a symbol has both a -function definition and a variable definition, and you want to refer to -just one of them, you can specify which one by writing one of the words -@samp{variable}, @samp{option}, @samp{function}, or @samp{command}, -immediately before the symbol name. (Case makes no difference in -recognizing these indicator words.) For example, if you write - -@example -This function sets the variable `buffer-file-name'. -@end example - -@noindent -then the hyperlink will refer only to the variable documentation of -@code{buffer-file-name}, and not to its function documentation. - -If a symbol has a function definition and/or a variable definition, but -those are irrelevant to the use of the symbol that you are documenting, -you can write the words @samp{symbol} or @samp{program} before the -symbol name to prevent making any hyperlink. For example, - -@example -If the argument KIND-OF-RESULT is the symbol `list', -this function returns a list of all the objects -that satisfy the criterion. -@end example - -@noindent -does not make a hyperlink to the documentation, irrelevant here, of the -function @code{list}. - -Normally, no hyperlink is made for a variable without variable -documentation. You can force a hyperlink for such variables by -preceding them with one of the words @samp{variable} or -@samp{option}. - -Hyperlinks for faces are only made if the face name is preceded or -followed by the word @samp{face}. In that case, only the face -documentation will be shown, even if the symbol is also defined as a -variable or as a function. - -To make a hyperlink to Info documentation, write the name of the Info -node (or anchor) in single quotes, preceded by @samp{info node}, -@samp{Info node}, @samp{info anchor} or @samp{Info anchor}. The Info -file name defaults to @samp{emacs}. For example, - -@smallexample -See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. -@end smallexample - -Finally, to create a hyperlink to URLs, write the URL in single -quotes, preceded by @samp{URL}. For example, - -@smallexample -The home page for the GNU project has more information (see URL -`http://www.gnu.org/'). -@end smallexample - -@item -Don't write key sequences directly in documentation strings. Instead, -use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write the construct -@samp{\\[forward-char]}. When Emacs displays the documentation string, -it substitutes whatever key is currently bound to @code{forward-char}. -(This is normally @samp{C-f}, but it may be some other character if the -user has moved key bindings.) @xref{Keys in Documentation}. - -@item -In documentation strings for a major mode, you will want to refer to the -key bindings of that mode's local map, rather than global ones. -Therefore, use the construct @samp{\\<@dots{}>} once in the -documentation string to specify which key map to use. Do this before -the first use of @samp{\\[@dots{}]}. The text inside the -@samp{\\<@dots{}>} should be the name of the variable containing the -local keymap for the major mode. - -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -For consistency, phrase the verb in the first sentence of a function's -documentation string as an imperative---for instance, use ``Return the -cons of A and B.'' in preference to ``Returns the cons of A and B@.'' -Usually it looks good to do likewise for the rest of the first -paragraph. Subsequent paragraphs usually look better if each sentence -is indicative and has a proper subject. - -@item -The documentation string for a function that is a yes-or-no predicate -should start with words such as ``Return t if,'' to indicate -explicitly what constitutes ``truth.'' The word ``return'' avoids -starting the sentence with lower-case ``t,'' which could be somewhat -distracting. - -@item -If a line in a documentation string begins with an open-parenthesis, -write a backslash before the open-parenthesis, like this: - -@example -The argument FOO can be either a number -\(a buffer position) or a string (a file name). -@end example - -This prevents the open-parenthesis from being treated as the start of a -defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). - -@item -Write documentation strings in the active voice, not the passive, and in -the present tense, not the future. For instance, use ``Return a list -containing A and B.'' instead of ``A list containing A and B will be -returned.'' - -@item -Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Emacs to display text in boldface,'' write just -``Display text in boldface.'' - -@item -Avoid using ``iff'' (a mathematics term meaning ``if and only if''), -since many people are unfamiliar with it and mistake it for a typo. In -most cases, the meaning is clear with just ``if''. Otherwise, try to -find an alternate phrasing that conveys the meaning. - -@item -When a command is meaningful only in a certain mode or situation, -do mention that in the documentation string. For example, -the documentation of @code{dired-find-file} is: - -@example -In Dired, visit the file or directory named on this line. -@end example - -@item -When you define a variable that users ought to set interactively, you -normally should use @code{defcustom}. However, if for some reason you -use @code{defvar} instead, start the doc string with a @samp{*}. -@xref{Defining Variables}. - -@item -The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means,'' to make it clear that -all non-@code{nil} values are equivalent and indicate explicitly what -@code{nil} and non-@code{nil} mean. -@end itemize - -@node Comment Tips -@section Tips on Writing Comments -@cindex comments, Lisp convention for - - We recommend these conventions for where to put comments and how to -indent them: - -@table @samp -@item ; -Comments that start with a single semicolon, @samp{;}, should all be -aligned to the same column on the right of the source code. Such -comments usually explain how the code on the same line does its job. In -Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment}) -command automatically inserts such a @samp{;} in the right place, or -aligns such a comment if it is already present. - -This and following examples are taken from the Emacs sources. - -@smallexample -@group -(setq base-version-list ; there was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion -@end group -@end smallexample - -@item ;; -Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments usually -describe the purpose of the following lines or the state of the program -at that point. For example: - -@smallexample -@group -(prog1 (setq auto-fill-function - @dots{} - @dots{} - ;; update mode line - (force-mode-line-update))) -@end group -@end smallexample - -We also normally use two semicolons for comments outside functions. - -@smallexample -@group -;; This Lisp code is run in Emacs -;; when it is to operate as a server -;; for other processes. -@end group -@end smallexample - -Every function that has no documentation string (presumably one that is -used only internally within the package it belongs to), should instead -have a two-semicolon comment right before the function, explaining what -the function does and how to call it properly. Explain precisely what -each argument means and how the function interprets its possible values. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. These are used, occasionally, for comments within -functions that should start at the margin. We also use them sometimes -for comments that are between functions---whether to use two or three -semicolons depends on whether the comment should be considered a -``heading'' by Outline minor mode. By default, comments starting with -at least three semicolons (followed by a single space and a -non-whitespace character) are considered headings, comments starting -with two or less are not. - -Another use for triple-semicolon comments is for commenting out lines -within a function. We use three semicolons for this precisely so that -they remain at the left margin. By default, Outline minor mode does -not consider a comment to be a heading (even if it starts with at -least three semicolons) if the semicolons are followed by at least two -spaces. Thus, if you add an introductory comment to the commented out -code, make sure to indent it by at least two spaces after the three -semicolons. - -@smallexample -(defun foo (a) -;;; This is no longer necessary. -;;; (force-mode-line-update) - (message "Finished with %s" a)) -@end smallexample - -When commenting out entire functions, use two semicolons. - -@item ;;;; -Comments that start with four semicolons, @samp{;;;;}, should be aligned -to the left margin and are used for headings of major sections of a -program. For example: - -@smallexample -;;;; The kill ring -@end smallexample -@end table - -@noindent -The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} -(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}), -automatically indent comments according to these conventions, -depending on the number of semicolons. @xref{Comments,, -Manipulating Comments, emacs, The GNU Emacs Manual}. - -@node Library Headers -@section Conventional Headers for Emacs Libraries -@cindex header comments -@cindex library header comments - - Emacs has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. This section explains these conventions. - - We'll start with an example, a package that is included in the Emacs -distribution. - - Parts of this example reflect its status as part of Emacs; for -example, the copyright notice lists the Free Software Foundation as the -copyright holder, and the copying permission says the file is part of -Emacs. When you write a package and post it, the copyright holder would -be you (unless your employer claims to own it instead), and you should -get the suggested copying permission from the end of the GNU General -Public License itself. Don't say your file is part of Emacs -if we haven't installed it in Emacs yet! - - With that warning out of the way, on to the example: - -@smallexample -@group -;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers - -;; Copyright (C) 1992 Free Software Foundation, Inc. -@end group - -;; Author: Eric S. Raymond -;; Maintainer: Eric S. Raymond -;; Created: 14 Jul 1992 -;; Version: 1.2 -@group -;; Keywords: docs - -;; This file is part of GNU Emacs. -@dots{} -;; along with GNU Emacs. If not, see . -@end group -@end smallexample - - The very first line should have this format: - -@example -;;; @var{filename} --- @var{description} -@end example - -@noindent -The description should be complete in one line. If the file -needs a @samp{-*-} specification, put it after @var{description}. - - After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;; @var{header-name}:}. Here is a table of -the conventional possibilities for @var{header-name}: - -@table @samp -@item Author -This line states the name and net address of at least the principal -author of the library. - -If there are multiple authors, you can list them on continuation lines -led by @code{;;} and a tab character, like this: - -@smallexample -@group -;; Author: Ashwin Ram -;; Dave Sill -;; Dave Brennan -;; Eric Raymond -@end group -@end smallexample - -@item Maintainer -This line should contain a single name/address as in the Author line, or -an address only, or the string @samp{FSF}. If there is no maintainer -line, the person(s) in the Author field are presumed to be the -maintainers. The example above is mildly bogus because the maintainer -line is redundant. - -The idea behind the @samp{Author} and @samp{Maintainer} lines is to make -possible a Lisp function to ``send mail to the maintainer'' without -having to mine the name out by hand. - -Be sure to surround the network address with @samp{<@dots{}>} if -you include the person's full name as well as the network address. - -@item Created -This optional line gives the original creation date of the -file. For historical interest only. - -@item Version -If you wish to record version numbers for the individual Lisp program, put -them in this line. - -@item Adapted-By -In this header line, place the name of the person who adapted the -library for installation (to make it fit the style conventions, for -example). - -@item Keywords -This line lists keywords for the @code{finder-by-keyword} help command. -Please use that command to see a list of the meaningful keywords. - -This field is important; it's how people will find your package when -they're looking for things by topic area. To separate the keywords, you -can use spaces, commas, or both. -@end table - - Just about every Lisp library ought to have the @samp{Author} and -@samp{Keywords} header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names---they have no standard meanings, so they can't do any harm. - - We use additional stylized comments to subdivide the contents of the -library file. These should be separated by blank lines from anything -else. Here is a table of them: - -@table @samp -@item ;;; Commentary: -This begins introductory comments that explain how the library works. -It should come right after the copying permissions, terminated by a -@samp{Change Log}, @samp{History} or @samp{Code} comment line. This -text is used by the Finder package, so it should make sense in that -context. - -@item ;;; Documentation: -This was used in some files in place of @samp{;;; Commentary:}, -but it is deprecated. - -@item ;;; Change Log: -This begins change log information stored in the library file (if you -store the change history there). For Lisp files distributed with Emacs, -the change history is kept in the file @file{ChangeLog} and not in the -source file at all; these files generally do not have a @samp{;;; Change -Log:} line. @samp{History} is an alternative to @samp{Change Log}. - -@item ;;; Code: -This begins the actual code of the program. - -@item ;;; @var{filename} ends here -This is the @dfn{footer line}; it appears at the very end of the file. -Its purpose is to enable people to detect truncated versions of the file -from the lack of a footer line. -@end table - -@ignore - arch-tag: 9ea911c2-6b1d-47dd-88b7-0a94e8b27c2e -@end ignore diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt deleted file mode 100644 index 0d80abdcd22..00000000000 --- a/doc/lispref/two-volume-cross-refs.txt +++ /dev/null @@ -1,320 +0,0 @@ -Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 - Free Software Foundation, Inc. - See end for copying conditions. - -Two Volume Cross References -=========================== - -12 June 2007 (karl) - -For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly -Makefile, in the file two-volume.make, to encapsulate all the steps -below, without manual intervention. In theory, simply running "make -f -two-volume.make" should create a vol1.pdf and vol2.pdf with all the -niceties worked out. - -One issue not explicitly discussed below is getting page numbers right. -It's not enough to go through the whole process. You have to go through -the whole process twice -- otherwise, some index entries and/or toc -entries will be off by one. See two-volume.make for a few more comments. - -For future editions, it should suffice to update the usual things in -vol[12].texi (as well as elisp.texi). That was my hope, anyway. - - -18 March 1992 (bob) - -This enables you to create manuals in *two* volumes, with tables of -contents, cross references, and indices in each volume referring to -*both* volumes. - -The procedure is tedious. However, the resulting two volumes are -conveniently organized. Each has an index of the whole two volumes. -Each volume starts with page 1. (I don't like multi-volume works -where each volume starts with a higher page number since I find it -harder to go to the right place in the volume.) - -References to the same volume are just the page number; references to -the other volume are a volumne number (in Roman numerals) preceding -the page number. - -For example, in Volume I: - - list length ......... 90 - list motion ......II:117 - -and in Volume II: - - list length ....... I:90 - list motion .........117 - -All other references and the table of contents work the same way. I -find this *very* helpful. - - -In brief: you run tex on a .texi file with - - a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file - b. redone .aux file - c. redone .fns file - - -Here are the steps in detail: - -% tex vol1.texi -% texindex vol1.?? -% tex vol1.texi - -% tex vol2.texi -% texindex vol2.?? -% tex vol2.texi - -### Create .aux files with volume numbers for other volume. - -% cp vol1.aux elisp1-aux -% cp vol2.aux elisp2-aux - -% cp vol1.aux elisp1-aux-vol-added -% cp vol2.aux elisp2-aux-vol-added - -on elisp1-aux-vol-number-added -(volume-aux-markup 1) see defun for volume-aux-markup below. -to create elisp1-aux-vol-added - -on elisp2-aux-vol-number-added -(volume-aux-markup 2) -to create elisp2-aux-vol-added - -insert elisp2-aux-vol-added into vol1.aux (append) -insert elisp1-aux-vol-added into vol2.aux (prepend) - -(so you dont have to do it again) -% cp vol1.aux elisp1-aux-ready -% cp vol2.aux elisp2-aux-ready - - -### Create .fn files with volume numbers for other volume. - -% cp vol1.fn elisp1-fn -% cp vol2.fn elisp2-fn - -% cp vol1.fn elisp1-fn-vol-number-added -% cp vol2.fn elisp2-fn-vol-number-added - -on elisp1-fn-vol-number-added -(volume-index-markup "I") -to create elisp1-fn-vol-number-added - -on elisp2-fn-vol-number-added -(volume-index-markup "II") -to create elisp2-fn-vol-number-added - -insert elisp2-fn-vol-number-added into vol1.fn: do following `cat' -insert elisp1-fn-vol-number-added into vol2.fn: do following `cat' - -% cat elisp2-fn-vol-number-added >> vol1.fn -% cat elisp1-fn-vol-number-added >> vol2.fn - -Be sure to handle special case entries by hand. -Be sure that .fn file has no blank lines. - -% texindex vol1.fn -% texindex vol2.fn - -(so you dont have to do it again) -% cp vol1.fns elisp1-fns-2vol-ready -% cp vol2.fns elisp2-fns-2vol-ready - -### Create merged .toc file with volume number headings. - -append vol2.toc to vol1.toc with following `cat' - -% cat vol1.toc vol2.toc > elisp-toc-2vol.toc - -and edit in Volume titles - -\unnumbchapentry {Volume 1}{} -\unnumbchapentry {}{} - -\unnumbchapentry {Index}{295} -\unnumbchapentry {}{} -\unnumbchapentry {Volume 2}{} -\unnumbchapentry {}{} - -If you want to put in volume numbers for TOC, then do this: -Create volume specific .toc files with volume numbers in them. - -% cp elisp-toc-2vol.toc elisp1-toc.toc -% cp elisp-toc-2vol.toc elisp2-toc.toc - -Use keyboard macro to put I: in first half of elisp1-toc.toc and -II: in first half of elisp2-toc.toc - -Copy the tocs to something you can remember more easily - -% cp elisp2-toc.toc elisp1-toc-ready.toc -% cp elisp1-toc.toc elisp2-toc-ready.toc - -Then, edit vol1.texi to input elisp1-toc-ready.toc -and vol2.texi to input elisp2-toc-ready.toc - - -### Now format the two volumes: - -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -% tex vol1.texi -% tex vol2.texi - - - -For every additional run: - -### recopy aux files so the correct ones are read: -% cp elisp1-aux-2vol-ready vol1.aux -% cp elisp2-aux-2vol-ready vol2.aux - -Do not run texindex. Then proper sorted index will stay. - else do: % cp elisp2-fns-2vol-ready vol2.fns - -Do not change the .texi files; they will call the elisp-toc-2vol.toc file. - -% tex vol1.texi -% tex vol2.texi - -================================================================ - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - - -================================================================ - - -The steps: - -1. Run TeX, texindex and TeX on file1. -2. Run TeX, texindex and TeX on file2. - -3. Copy both .aux files into specially named files - -4. In the case of the elisp ref manual, - - copy the *unsorted* function index files into specially named files - (no other index used in elisp ref manual) - - -5. For aux files: - - Run a function on the specially named .aux files to label each - entry according to volume. Save these files. - - i.e., convert - 'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1} - -5a.Insert each specially named .aux file into the regular .aux file of - the other volume. - -6. For index files: - - Run a function on the specially named unsorted index files to label - each entry according to volume. Save these files. - -6b.Insert each specially named marked unsorted index file into the - regular unsorted file of the other volume. Run texindex on this - -7. Insert the other volumes .toc file into the .toc, edit, and rename to - elisp-toc-2vol.toc - -7a. insert special @contents and @summarycontents defs into .texi files. - -8. Run TeX on each .texi file. - -================ - - - -Here is the discursive commentary: - -I've been running some small test files, called test1.texi and -test2.texi. As far as I can see, if we run tex on the two test files, -tex creates a .aux for each that includes the names of all the nodes -in that file. The node names are used for cross references. - -If you insert the .aux file for the second test file, test2.aux, into -the .aux file for the first test file, test1.aux, then when you next -run TeX on the first test file, test1.texi, the second volume cross -references are inserted. - -You can edit the text of the cross reference in test2.aux to include -the volume number. - -For example, you can take the following two lines from test1.texi and -insert them into test2.texi: - - 'xrdef {Special-pg}{7} - 'xrdef {Special-snt}{Section'tie1.6} - -You can re-edit this to show that the page is in volume 1: - - 'xrdef {Special-pg}{7, vol.'tie1} - 'xrdef {Special-snt}{Section'tie1.6} - -(The 'tie is a TeX special command to keep the number tied on one -line to the previous word. I don't know if it works after a period in -the "vol." but figure it is worth trying. {The ' is the @ of .aux files.} -Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the -definition for 'tie is the following: - - \def\tie{\penalty 10000\ } % Save plain tex definition of ~. - -) - -After running tex on the test2.texi file with the augmented test2.aux -file, you can see the following in the resulting DVI file: - - See Section 1.6 [Special], page 7, vol. 1 - -Note that TeX rewrites the .aux file each time TeX is run, so after -running Tex using an .aux file augmented with the .aux file from the -other volume, the new .aux file will *lack* the other volumes cross -references. Save your augmented .aux file in some other name for -another run! - - -COPYING CONDITIONS - -This file is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This file is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this file. If not, see . diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make deleted file mode 100644 index ca13397b306..00000000000 --- a/doc/lispref/two-volume.make +++ /dev/null @@ -1,224 +0,0 @@ -# Copyright (C) 2007, 2008, 2009 Free Software Foundation, Inc. -# See end for copying conditions. - -# although it would be nice to use tex rather than pdftex to avoid -# colors, spurious warnings about names being referenced but not -# existing, etc., dvips | ps2pdf doesn't preserve the page size. -# Instead of creating a special dvips config file, put up with the warnings. -texinfodir=../misc - -tex = TEXINPUTS=".:$(texinfodir):${TEXINPUTS}" pdftex -interaction=nonstopmode - -all: vol1.pdf vol2.pdf - -# vol1.texi and vol2.texi specially define \tocreadfilename so we can -# use our premade .toc's. -# -vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready - @echo -e "\f Final TeX run for volume 1..." - cp elisp1med-toc-ready elisp1-toc-ready.toc - cp elisp1med-fns-ready vol1.fns - cp elisp1med-aux-ready vol1.aux - $(tex) vol1.texi -# -vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." - cp elisp2med-toc-ready elisp2-toc-ready.toc - cp elisp2med-fns-ready vol2.fns - cp elisp2med-aux-ready vol2.aux - $(tex) vol2.texi - -# intermediate toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2med-toc-ready: elisp1med-init elisp2med-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2med-toc >>$@ - - -# intermediate aux files. -# -# append vol2's fixed aux to normal vol1. -elisp1med-aux-ready: elisp2med-aux-vol-added - cat elisp1med-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2med-aux-ready: elisp1med-aux-vol-added - cat $< elisp2med-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1med-aux-vol-added: elisp1med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@ -# -elisp2med-aux-vol-added: elisp2med-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@ - -# intermediate index (fns) file. -# -elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp2med-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added - cat elisp1med-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1med-fn-vol-added: elisp1med-init - cp vol1.fn elisp1med-fn - sed 's/}{/}{I:/' elisp1med-fn >$@ -# -elisp2med-fn-vol-added: elisp2med-init - cp vol2.fn elisp2med-fn - sed 's/}{/}{II:/' elisp2med-fn >$@ - -# ----------------------------------------------------------------------------- -# everything above is essentially a duplicate of everything below. sorry. -# ----------------------------------------------------------------------------- - -# intermediate TeX runs. -# -# this generates what would be the final versions -- except the page -# numbers aren't right. The process of adding the I: and II: changes -# the page breaks, so a few index entries, at least are wrong. (In -# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had -# it on page 375 from the initial run.) -# -# So, we start all over again, from these fns/aux/toc files. -# -elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfodir)/texinfo.tex - @echo -e "\f Intermediate TeX run for volume 1..." - cp elisp1init-toc-ready elisp1-toc-ready.toc - cp elisp1-fns-ready vol1.fns - cp elisp1-aux-ready vol1.aux - $(tex) vol1.texi - texindex vol1.?? - mv vol1.aux elisp1med-aux - mv vol1.toc elisp1med-toc -# -elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex - @echo "Final TeX run for volume 2..." - cp elisp2init-toc-ready elisp2-toc-ready.toc - cp elisp2-fns-ready vol2.fns - cp elisp2-aux-ready vol2.aux - $(tex) vol2.texi - texindex vol2.?? - mv vol2.aux elisp2med-aux - mv vol2.toc elisp2med-toc - - -# initial toc files. -# -# vol1 toc: volume 1, page break, volume 2 (with II: prepended). -elisp1init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - cat elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@ -# -# vol2 toc: volume 1 (with I: prepended), page break, volume 2. -elisp2init-toc-ready: elisp1-init elisp2-init - echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@ - sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@ - echo '@page' >>$@ - echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@ - cat elisp2-toc >>$@ - - -# initial aux files. -# -# append vol2's fixed aux to normal vol1. The initial runs saved -# elisp1-aux and elisp2-aux. -elisp1-aux-ready: elisp2-aux-vol-added - cat elisp1-aux $< >$@ -# -# prepend vol1's fixed aux to vol2. -elisp2-aux-ready: elisp1-aux-vol-added - cat $< elisp2-aux >$@ - -# on -pg entries, append volume number after page number. -elisp1-aux-vol-added: elisp1-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@ -# -elisp2-aux-vol-added: elisp2-init - sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@ - -# initial index (fns) file. -# -# Append other volume's index entries to this one's. -# Index entries in this volume will then take precedence. -elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp2-fn-vol-added >>vol1.fn - texindex vol1.fn - cp vol1.fns $@ -# -elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added - cat elisp1-fn-vol-added >>vol2.fn - texindex vol2.fn - cp vol2.fns $@ - -# Insert volume number (I: or II:) into index file. -elisp1-fn-vol-added: elisp1-init - cp vol1.fn elisp1-fn - sed 's/}{/}{I:/' elisp1-fn >$@ -# -elisp2-fn-vol-added: elisp2-init - cp vol2.fn elisp2-fn - sed 's/}{/}{II:/' elisp2-fn >$@ - - -# initial TeX runs. -# -# We use the .fn, .aux, and .toc files created here in subsequent -# processing. The page numbers generated here will not be correct yet, -# but we run texindex and TeX a second time just to get them closer. -# Otherwise it might take even longer for them to converge. -# -elisp1-init: vol1.texi - @echo -e "\f Initial TeX run for volume 1..." - rm -f vol1.aux vol1.toc - $(tex) $< - texindex vol1.?? - mv vol1.aux elisp1-aux - mv vol1.toc elisp1-toc - touch $@ -# -elisp2-init: vol2.texi - @echo "Initial TeX run for volume 2..." - rm -f vol2.aux vol2.toc - $(tex) $< - texindex vol2.?? - mv vol2.aux elisp2-aux - mv vol2.toc elisp2-toc - touch $@ - -# COPYING CONDITIONS -# -# This file is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# This file is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this file. If not, see . - -# arch-tag: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb diff --git a/doc/lispref/two.el b/doc/lispref/two.el deleted file mode 100644 index 124e51858d9..00000000000 --- a/doc/lispref/two.el +++ /dev/null @@ -1,80 +0,0 @@ -;; Auxiliary functions for preparing a two volume manual. - -;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -;; Free Software Foundation, Inc. - -;; --rjc 30mar92 - -;; This file is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; This file is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with this file. If not, see . - - -(defun volume-aux-markup (arg) - "Append `vol. NUMBER' to page number. -Apply to aux file that you save. -Then insert marked file into other volume's .aux file." - (interactive "sType volume number, 1 or 2: " ) - (goto-char (point-min)) - (while (search-forward "-pg" nil t) - (end-of-line 1) - (delete-backward-char 1 nil) - (insert ", vol.'tie" arg "}"))) - -(defun volume-index-markup (arg) - "Prepend `NUMBER:' to page number. Use Roman Numeral. -Apply only to unsorted index file, -Then insert marked file into other volume's unsorted index file. -Then run texindex on that file and save." - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "\\entry" nil t) - (search-forward "}{" (save-excursion (end-of-line) (point)) nil) - (insert arg ":"))) - -(defun volume-numbers-toc-markup (arg) - (interactive - "sType volume number, roman number I or II: " ) - (goto-char (point-min)) - (while (search-forward "chapentry" nil t) - (end-of-line) - (search-backward "{" nil t) - (forward-char 1) - (insert arg ":"))) - -(defun volume-header-toc-markup () - "Insert Volume I and Volume II text into .toc file. -NOTE: this auxilary function is file specific. -This is for the *Elisp Ref Manual*" - (interactive) - (goto-char (point-min)) - (insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n") - (search-forward "\\unnumbchapentry {Index}") - (forward-line 1) - (insert - "\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n")) - - -;;; In batch mode, you cannot call functions with args; hence this kludge: - -(defun volume-aux-markup-1 () (volume-aux-markup "1")) -(defun volume-aux-markup-2 () (volume-aux-markup "2")) - -(defun volume-index-markup-I () (volume-index-markup "I")) -(defun volume-index-markup-II () (volume-index-markup "II")) - -(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I")) -(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II")) - -;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5 -;;; two.el ends here diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi deleted file mode 100644 index 89fb19b8d62..00000000000 --- a/doc/lispref/variables.texi +++ /dev/null @@ -1,1927 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/variables -@node Variables, Functions, Control Structures, Top -@chapter Variables -@cindex variable - - A @dfn{variable} is a name used in a program to stand for a value. -Nearly all programming languages have variables of some sort. In the -text of a Lisp program, variables are written using the syntax for -symbols. - - In Lisp, unlike most programming languages, programs are represented -primarily as Lisp objects and only secondarily as text. The Lisp -objects used for variables are symbols: the symbol name is the -variable name, and the variable's value is stored in the value cell of -the symbol. The use of a symbol as a variable is independent of its -use as a function name. @xref{Symbol Components}. - - The textual form of a Lisp program is given by the read syntax of -the Lisp objects that constitute the program. Hence, a variable in a -textual Lisp program is written using the read syntax for the symbol -representing the variable. - -@menu -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. -@end menu - -@node Global Variables -@section Global Variables -@cindex global variable - - The simplest way to use a variable is @dfn{globally}. This means that -the variable has just one value at a time, and this value is in effect -(at least for the moment) throughout the Lisp system. The value remains -in effect until you specify a new one. When a new value replaces the -old one, no trace of the old value remains in the variable. - - You specify a value for a symbol with @code{setq}. For example, - -@example -(setq x '(a b)) -@end example - -@noindent -gives the variable @code{x} the value @code{(a b)}. Note that -@code{setq} is a special form (@pxref{Special Forms}); it does not -evaluate its first argument, the name of the variable, but it does -evaluate the second argument, the new value. - - Once the variable has a value, you can refer to it by using the -symbol itself as an expression. Thus, - -@example -@group -x @result{} (a b) -@end group -@end example - -@noindent -assuming the @code{setq} form shown above has already been executed. - - If you do set the same variable again, the new value replaces the old -one: - -@example -@group -x - @result{} (a b) -@end group -@group -(setq x 4) - @result{} 4 -@end group -@group -x - @result{} 4 -@end group -@end example - -@node Constant Variables -@section Variables that Never Change -@kindex setting-constant -@cindex keyword symbol -@cindex variable with constant value -@cindex constant variables -@cindex symbol that evaluates to itself -@cindex symbol with constant value - - In Emacs Lisp, certain symbols normally evaluate to themselves. These -include @code{nil} and @code{t}, as well as any symbol whose name starts -with @samp{:} (these are called @dfn{keywords}). These symbols cannot -be rebound, nor can their values be changed. Any attempt to set or bind -@code{nil} or @code{t} signals a @code{setting-constant} error. The -same is true for a keyword (a symbol whose name starts with @samp{:}), -if it is interned in the standard obarray, except that setting such a -symbol to itself is not an error. - -@example -@group -nil @equiv{} 'nil - @result{} nil -@end group -@group -(setq nil 500) -@error{} Attempt to set constant symbol: nil -@end group -@end example - -@defun keywordp object -function returns @code{t} if @var{object} is a symbol whose name -starts with @samp{:}, interned in the standard obarray, and returns -@code{nil} otherwise. -@end defun - -@node Local Variables -@section Local Variables -@cindex binding local variables -@cindex local variables -@cindex local binding -@cindex global binding - - Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to create variable values that -exist temporarily---only until a certain part of the program finishes. -These values are called @dfn{local}, and the variables so used are -called @dfn{local variables}. - - For example, when a function is called, its argument variables receive -new local values that last until the function exits. The @code{let} -special form explicitly establishes new local values for specified -variables; these last until exit from the @code{let} form. - -@cindex shadowing of variables - Establishing a local value saves away the variable's previous value -(or lack of one). We say that the previous value is @dfn{shadowed} -and @dfn{not visible}. Both global and local values may be shadowed -(@pxref{Scope}). After the life span of the local value is over, the -previous value (or lack of one) is restored. - - If you set a variable (such as with @code{setq}) while it is local, -this replaces the local value; it does not alter the global value, or -previous local values, that are shadowed. To model this behavior, we -speak of a @dfn{local binding} of the variable as well as a local value. - - The local binding is a conceptual place that holds a local value. -Entering a function, or a special form such as @code{let}, creates the -local binding; exiting the function or the @code{let} removes the -local binding. While the local binding lasts, the variable's value is -stored within it. Using @code{setq} or @code{set} while there is a -local binding stores a different value into the local binding; it does -not create a new binding. - - We also speak of the @dfn{global binding}, which is where -(conceptually) the global value is kept. - -@cindex current binding - A variable can have more than one local binding at a time (for -example, if there are nested @code{let} forms that bind it). In such a -case, the most recently created local binding that still exists is the -@dfn{current binding} of the variable. (This rule is called -@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no -local bindings, the variable's global binding is its current binding. -We sometimes call the current binding the @dfn{most-local existing -binding}, for emphasis. Ordinary evaluation of a symbol always returns -the value of its current binding. - - The special forms @code{let} and @code{let*} exist to create -local bindings. - -@defspec let (bindings@dots{}) forms@dots{} -This special form binds variables according to @var{bindings} and then -evaluates all of the @var{forms} in textual order. The @code{let}-form -returns the value of the last form in @var{forms}. - -Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is bound to @code{nil}; or @w{(ii) a} list of the form -@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is -bound to the result of evaluating @var{value-form}. If @var{value-form} -is omitted, @code{nil} is used. - -All of the @var{value-form}s in @var{bindings} are evaluated in the -order they appear and @emph{before} binding any of the symbols to them. -Here is an example of this: @code{z} is bound to the old value of -@code{y}, which is 2, not the new value of @code{y}, which is 1. - -@example -@group -(setq y 2) - @result{} 2 -@end group -@group -(let ((y 1) - (z y)) - (list y z)) - @result{} (1 2) -@end group -@end example -@end defspec - -@defspec let* (bindings@dots{}) forms@dots{} -This special form is like @code{let}, but it binds each variable right -after computing its local value, before computing the local value for -the next variable. Therefore, an expression in @var{bindings} can -reasonably refer to the preceding symbols bound in this @code{let*} -form. Compare the following example with the example above for -@code{let}. - -@example -@group -(setq y 2) - @result{} 2 -@end group -@group -(let* ((y 1) - (z y)) ; @r{Use the just-established value of @code{y}.} - (list y z)) - @result{} (1 1) -@end group -@end example -@end defspec - - Here is a complete list of the other facilities that create local -bindings: - -@itemize @bullet -@item -Function calls (@pxref{Functions}). - -@item -Macro calls (@pxref{Macros}). - -@item -@code{condition-case} (@pxref{Errors}). -@end itemize - - Variables can also have buffer-local bindings (@pxref{Buffer-Local -Variables}); a few variables have terminal-local bindings -(@pxref{Multiple Terminals}). These kinds of bindings work somewhat -like ordinary local bindings, but they are localized depending on -``where'' you are in Emacs, rather than localized in time. - -@defopt max-specpdl-size -@anchor{Definition of max-specpdl-size} -@cindex variable limit error -@cindex evaluation error -@cindex infinite recursion -This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, -Cleaning Up from Nonlocal Exits}) that are allowed before Emacs -signals an error (with data @code{"Variable binding depth exceeds -max-specpdl-size"}). - -This limit, with the associated error when it is exceeded, is one way -that Lisp avoids infinite recursion on an ill-defined function. -@code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Definition of max-lisp-eval-depth,, Eval}. - -The default value is 1000. Entry to the Lisp debugger increases the -value, if there is little room left, to make sure the debugger itself -has room to execute. -@end defopt - -@node Void Variables -@section When a Variable is ``Void'' -@kindex void-variable -@cindex void variable - - If you have never given a symbol any value as a global variable, we -say that that symbol's global value is @dfn{void}. In other words, the -symbol's value cell does not have any Lisp object in it. If you try to -evaluate the symbol, you get a @code{void-variable} error rather than -a value. - - Note that a value of @code{nil} is not the same as void. The symbol -@code{nil} is a Lisp object and can be the value of a variable just as any -other object can be; but it is @emph{a value}. A void variable does not -have any value. - - After you have given a variable a value, you can make it void once more -using @code{makunbound}. - -@defun makunbound symbol -This function makes the current variable binding of @var{symbol} void. -Subsequent attempts to use this symbol's value as a variable will signal -the error @code{void-variable}, unless and until you set it again. - -@code{makunbound} returns @var{symbol}. - -@example -@group -(makunbound 'x) ; @r{Make the global value of @code{x} void.} - @result{} x -@end group -@group -x -@error{} Symbol's value as variable is void: x -@end group -@end example - -If @var{symbol} is locally bound, @code{makunbound} affects the most -local existing binding. This is the only way a symbol can have a void -local binding, since all the constructs that create local bindings -create them with values. In this case, the voidness lasts at most as -long as the binding does; when the binding is removed due to exit from -the construct that made it, the previous local or global binding is -reexposed as usual, and the variable is no longer void unless the newly -reexposed binding was void all along. - -@smallexample -@group -(setq x 1) ; @r{Put a value in the global binding.} - @result{} 1 -(let ((x 2)) ; @r{Locally bind it.} - (makunbound 'x) ; @r{Void the local binding.} - x) -@error{} Symbol's value as variable is void: x -@end group -@group -x ; @r{The global binding is unchanged.} - @result{} 1 - -(let ((x 2)) ; @r{Locally bind it.} - (let ((x 3)) ; @r{And again.} - (makunbound 'x) ; @r{Void the innermost-local binding.} - x)) ; @r{And refer: it's void.} -@error{} Symbol's value as variable is void: x -@end group - -@group -(let ((x 2)) - (let ((x 3)) - (makunbound 'x)) ; @r{Void inner binding, then remove it.} - x) ; @r{Now outer @code{let} binding is visible.} - @result{} 2 -@end group -@end smallexample -@end defun - - A variable that has been made void with @code{makunbound} is -indistinguishable from one that has never received a value and has -always been void. - - You can use the function @code{boundp} to test whether a variable is -currently void. - -@defun boundp variable -@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; -more precisely, if its current binding is not void. It returns -@code{nil} otherwise. - -@smallexample -@group -(boundp 'abracadabra) ; @r{Starts out void.} - @result{} nil -@end group -@group -(let ((abracadabra 5)) ; @r{Locally bind it.} - (boundp 'abracadabra)) - @result{} t -@end group -@group -(boundp 'abracadabra) ; @r{Still globally void.} - @result{} nil -@end group -@group -(setq abracadabra 5) ; @r{Make it globally nonvoid.} - @result{} 5 -@end group -@group -(boundp 'abracadabra) - @result{} t -@end group -@end smallexample -@end defun - -@node Defining Variables -@section Defining Global Variables -@cindex variable definition - - You may announce your intention to use a symbol as a global variable -with a @dfn{variable definition}: a special form, either @code{defconst} -or @code{defvar}. - - In Emacs Lisp, definitions serve three purposes. First, they inform -people who read the code that certain symbols are @emph{intended} to be -used a certain way (as variables). Second, they inform the Lisp system -of these things, supplying a value and documentation. Third, they -provide information to utilities such as @code{etags} and -@code{make-docfile}, which create data bases of the functions and -variables in a program. - - The difference between @code{defconst} and @code{defvar} is primarily -a matter of intent, serving to inform human readers of whether the value -should ever change. Emacs Lisp does not restrict the ways in which a -variable can be used based on @code{defconst} or @code{defvar} -declarations. However, it does make a difference for initialization: -@code{defconst} unconditionally initializes the variable, while -@code{defvar} initializes it only if it is void. - -@ignore - One would expect user option variables to be defined with -@code{defconst}, since programs do not change them. Unfortunately, this -has bad results if the definition is in a library that is not preloaded: -@code{defconst} would override any prior value when the library is -loaded. Users would like to be able to set user options in their init -files, and override the default values given in the definitions. For -this reason, user options must be defined with @code{defvar}. -@end ignore - -@defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a variable and can also -initialize and document it. The definition informs a person reading -your code that @var{symbol} is used as a variable that might be set or -changed. Note that @var{symbol} is not evaluated; the symbol to be -defined must appear explicitly in the @code{defvar}. - -If @var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates it and sets @var{symbol} to the result. But if @var{symbol} -already has a value (i.e., it is not void), @var{value} is not even -evaluated, and @var{symbol}'s value remains unchanged. If @var{value} -is omitted, the value of @var{symbol} is not changed in any case. - -If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} operates on the default value, which is buffer-independent, -not the current (buffer-local) binding. It sets the default value if -the default value is void. @xref{Buffer-Local Variables}. - -When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in -Emacs Lisp mode (@code{eval-defun}), a special feature of -@code{eval-defun} arranges to set the variable unconditionally, without -testing whether its value is void. - -If the @var{doc-string} argument appears, it specifies the documentation -for the variable. (This opportunity to specify documentation is one of -the main benefits of defining the variable.) The documentation is -stored in the symbol's @code{variable-documentation} property. The -Emacs help functions (@pxref{Documentation}) look for this property. - -If the documentation string begins with the character @samp{*}, Emacs -allows users to set it interactively using the @code{set-variable} -command. However, you should nearly always use @code{defcustom} -instead of @code{defvar} to define such variables, so that users can -use @kbd{M-x customize} and related commands to set them. In that -case, it is not necessary to begin the documentation string with -@samp{*}. @xref{Customization}. - -Here are some examples. This form defines @code{foo} but does not -initialize it: - -@example -@group -(defvar foo) - @result{} foo -@end group -@end example - -This example initializes the value of @code{bar} to @code{23}, and gives -it a documentation string: - -@example -@group -(defvar bar 23 - "The normal weight of a bar.") - @result{} bar -@end group -@end example - -The following form changes the documentation string for @code{bar}, -making it a user option, but does not change the value, since @code{bar} -already has a value. (The addition @code{(1+ nil)} would get an error -if it were evaluated, but since it is not evaluated, there is no error.) - -@example -@group -(defvar bar (1+ nil) - "*The normal weight of a bar.") - @result{} bar -@end group -@group -bar - @result{} 23 -@end group -@end example - -Here is an equivalent expression for the @code{defvar} special form: - -@example -@group -(defvar @var{symbol} @var{value} @var{doc-string}) -@equiv{} -(progn - (if (not (boundp '@var{symbol})) - (setq @var{symbol} @var{value})) - (if '@var{doc-string} - (put '@var{symbol} 'variable-documentation '@var{doc-string})) - '@var{symbol}) -@end group -@end example - -The @code{defvar} form returns @var{symbol}, but it is normally used -at top level in a file where its value does not matter. -@end defspec - -@defspec defconst symbol value [doc-string] -This special form defines @var{symbol} as a value and initializes it. -It informs a person reading your code that @var{symbol} has a standard -global value, established here, that should not be changed by the user -or by other programs. Note that @var{symbol} is not evaluated; the -symbol to be defined must appear explicitly in the @code{defconst}. - -@code{defconst} always evaluates @var{value}, and sets the value of -@var{symbol} to the result. If @var{symbol} does have a buffer-local -binding in the current buffer, @code{defconst} sets the default value, -not the buffer-local value. (But you should not be making -buffer-local bindings for a symbol that is defined with -@code{defconst}.) - -Here, @code{pi} is a constant that presumably ought not to be changed -by anyone (attempts by the Indiana State Legislature notwithstanding). -As the second form illustrates, however, this is only advisory. - -@example -@group -(defconst pi 3.1415 "Pi to five places.") - @result{} pi -@end group -@group -(setq pi 3) - @result{} pi -@end group -@group -pi - @result{} 3 -@end group -@end example -@end defspec - -@defun user-variable-p variable -@cindex user option -This function returns @code{t} if @var{variable} is a user option---a -variable intended to be set by the user for customization---and -@code{nil} otherwise. (Variables other than user options exist for the -internal purposes of Lisp programs, and users need not know about them.) - -User option variables are distinguished from other variables either -though being declared using @code{defcustom}@footnote{They may also be -declared equivalently in @file{cus-start.el}.} or by the first character -of their @code{variable-documentation} property. If the property exists -and is a string, and its first character is @samp{*}, then the variable -is a user option. Aliases of user options are also user options. -@end defun - -@kindex variable-interactive - If a user option variable has a @code{variable-interactive} property, -the @code{set-variable} command uses that value to control reading the -new value for the variable. The property's value is used as if it were -specified in @code{interactive} (@pxref{Using Interactive}). However, -this feature is largely obsoleted by @code{defcustom} -(@pxref{Customization}). - - @strong{Warning:} If the @code{defconst} and @code{defvar} special -forms are used while the variable has a local binding (made with -@code{let}, or a function argument), they set the local-binding's -value; the top-level binding is not changed. This is not what you -usually want. To prevent it, use these special forms at top level in -a file, where normally no local binding is in effect, and make sure to -load the file before making a local binding for the variable. - -@node Tips for Defining -@section Tips for Defining Variables Robustly - - When you define a variable whose value is a function, or a list of -functions, use a name that ends in @samp{-function} or -@samp{-functions}, respectively. - - There are several other variable name conventions; -here is a complete list: - -@table @samp -@item @dots{}-hook -The variable is a normal hook (@pxref{Hooks}). - -@item @dots{}-function -The value is a function. - -@item @dots{}-functions -The value is a list of functions. - -@item @dots{}-form -The value is a form (an expression). - -@item @dots{}-forms -The value is a list of forms (expressions). - -@item @dots{}-predicate -The value is a predicate---a function of one argument that returns -non-@code{nil} for ``good'' arguments and @code{nil} for ``bad'' -arguments. - -@item @dots{}-flag -The value is significant only as to whether it is @code{nil} or not. -Since such variables often end up acquiring more values over time, -this convention is not strongly recommended. - -@item @dots{}-program -The value is a program name. - -@item @dots{}-command -The value is a whole shell command. - -@item @dots{}-switches -The value specifies options for a command. -@end table - - When you define a variable, always consider whether you should mark -it as ``safe'' or ``risky''; see @ref{File Local Variables}. - - When defining and initializing a variable that holds a complicated -value (such as a keymap with bindings in it), it's best to put the -entire computation of the value into the @code{defvar}, like this: - -@example -(defvar my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - map) - @var{docstring}) -@end example - -@noindent -This method has several benefits. First, if the user quits while -loading the file, the variable is either still uninitialized or -initialized properly, never in-between. If it is still uninitialized, -reloading the file will initialize it properly. Second, reloading the -file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents (such -as, to rebind keys). Third, evaluating the @code{defvar} form with -@kbd{C-M-x} @emph{will} reinitialize the map completely. - - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - - But be careful not to write the code like this: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (setq my-mode-map (make-sparse-keymap)) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{}) -@end example - -@noindent -This code sets the variable, then alters it, but it does so in more than -one step. If the user quits just after the @code{setq}, that leaves the -variable neither correctly initialized nor void nor @code{nil}. Once -that happens, reloading the file will not initialize the variable; it -will remain incomplete. - -@node Accessing Variables -@section Accessing Variable Values - - The usual way to reference a variable is to write the symbol which -names it (@pxref{Symbol Forms}). This requires you to specify the -variable name when you write the program. Usually that is exactly what -you want to do. Occasionally you need to choose at run time which -variable to reference; then you can use @code{symbol-value}. - -@defun symbol-value symbol -This function returns the value of @var{symbol}. This is the value in -the innermost local binding of the symbol, or its global value if it -has no local bindings. - -@example -@group -(setq abracadabra 5) - @result{} 5 -@end group -@group -(setq foo 9) - @result{} 9 -@end group - -@group -;; @r{Here the symbol @code{abracadabra}} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value 'abracadabra)) - @result{} foo -@end group - -@group -;; @r{Here, the value of @code{abracadabra},} -;; @r{which is @code{foo},} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value abracadabra)) - @result{} 9 -@end group - -@group -(symbol-value 'abracadabra) - @result{} 5 -@end group -@end example - -A @code{void-variable} error is signaled if the current binding of -@var{symbol} is void. -@end defun - -@node Setting Variables -@section How to Alter a Variable Value - - The usual way to change the value of a variable is with the special -form @code{setq}. When you need to compute the choice of variable at -run time, use the function @code{set}. - -@defspec setq [symbol form]@dots{} -This special form is the most common method of changing a variable's -value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The most-local existing -binding of the symbol is changed. - -@code{setq} does not evaluate @var{symbol}; it sets the symbol that you -write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted.'' - -The value of the @code{setq} form is the value of the last @var{form}. - -@example -@group -(setq x (1+ 2)) - @result{} 3 -@end group -x ; @r{@code{x} now has a global value.} - @result{} 3 -@group -(let ((x 5)) - (setq x 6) ; @r{The local binding of @code{x} is set.} - x) - @result{} 6 -@end group -x ; @r{The global value is unchanged.} - @result{} 3 -@end example - -Note that the first @var{form} is evaluated, then the first -@var{symbol} is set, then the second @var{form} is evaluated, then the -second @var{symbol} is set, and so on: - -@example -@group -(setq x 10 ; @r{Notice that @code{x} is set before} - y (1+ x)) ; @r{the value of @code{y} is computed.} - @result{} 11 -@end group -@end example -@end defspec - -@defun set symbol value -This function sets @var{symbol}'s value to @var{value}, then returns -@var{value}. Since @code{set} is a function, the expression written for -@var{symbol} is evaluated to obtain the symbol to set. - -The most-local existing binding of the variable is the binding that is -set; shadowed bindings are not affected. - -@example -@group -(set one 1) -@error{} Symbol's value as variable is void: one -@end group -@group -(set 'one 1) - @result{} 1 -@end group -@group -(set 'two 'one) - @result{} one -@end group -@group -(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} - @result{} 2 -@end group -@group -one ; @r{So it is @code{one} that was set.} - @result{} 2 -(let ((one 1)) ; @r{This binding of @code{one} is set,} - (set 'one 3) ; @r{not the global value.} - one) - @result{} 3 -@end group -@group -one - @result{} 2 -@end group -@end example - -If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} -error is signaled. - -@example -(set '(x y) 'z) -@error{} Wrong type argument: symbolp, (x y) -@end example - -Logically speaking, @code{set} is a more fundamental primitive than -@code{setq}. Any use of @code{setq} can be trivially rewritten to use -@code{set}; @code{setq} could even be defined as a macro, given the -availability of @code{set}. However, @code{set} itself is rarely used; -beginners hardly need to know about it. It is useful only for choosing -at run time which variable to set. For example, the command -@code{set-variable}, which reads a variable name from the user and then -sets the variable, needs to use @code{set}. - -@cindex CL note---@code{set} local -@quotation -@b{Common Lisp note:} In Common Lisp, @code{set} always changes the -symbol's ``special'' or dynamic value, ignoring any lexical bindings. -In Emacs Lisp, all variables and all bindings are dynamic, so @code{set} -always affects the most local existing binding. -@end quotation -@end defun - -@node Variable Scoping -@section Scoping Rules for Variable Bindings - - A given symbol @code{foo} can have several local variable bindings, -established at different places in the Lisp program, as well as a global -binding. The most recently established binding takes precedence over -the others. - -@cindex scope -@cindex extent -@cindex dynamic scoping -@cindex lexical scoping - Local bindings in Emacs Lisp have @dfn{indefinite scope} and -@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. ``Indefinite scope'' means -that any part of the program can potentially access the variable -binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. ``Dynamic extent'' means that the binding -lasts as long as the activation of the construct that established it. - - The combination of dynamic extent and indefinite scope is called -@dfn{dynamic scoping}. By contrast, most programming languages use -@dfn{lexical scoping}, in which references to a local variable must be -located textually within the function or block that binds the variable. - -@cindex CL note---special variables -@quotation -@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are -dynamically scoped, like all variables in Emacs Lisp. -@end quotation - -@menu -* Scope:: Scope means where in the program a value is visible. - Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and avoid problems. -@end menu - -@node Scope -@subsection Scope - - Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. -This means that any function anywhere in the program text might access a -given binding of a variable. Consider the following function -definitions: - -@example -@group -(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} - (foo 5)) ; @r{@code{foo} is some other function.} -@end group - -@group -(defun user () ; @r{@code{x} is used ``free'' in @code{user}.} - (list x)) -@end group -@end example - - In a lexically scoped language, the binding of @code{x} in -@code{binder} would never be accessible in @code{user}, because -@code{user} is not textually contained within the function -@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} -may or may not refer to the binding of @code{x} established in -@code{binder}, depending on the circumstances: - -@itemize @bullet -@item -If we call @code{user} directly without calling @code{binder} at all, -then whatever binding of @code{x} is found, it cannot come from -@code{binder}. - -@item -If we define @code{foo} as follows and then call @code{binder}, then the -binding made in @code{binder} will be seen in @code{user}: - -@example -@group -(defun foo (lose) - (user)) -@end group -@end example - -@item -However, if we define @code{foo} as follows and then call @code{binder}, -then the binding made in @code{binder} @emph{will not} be seen in -@code{user}: - -@example -(defun foo (x) - (user)) -@end example - -@noindent -Here, when @code{foo} is called by @code{binder}, it binds @code{x}. -(The binding in @code{foo} is said to @dfn{shadow} the one made in -@code{binder}.) Therefore, @code{user} will access the @code{x} bound -by @code{foo} instead of the one bound by @code{binder}. -@end itemize - -Emacs Lisp uses dynamic scoping because simple implementations of -lexical scoping are slow. In addition, every Lisp system needs to offer -dynamic scoping at least as an option; if lexical scoping is the norm, -there must be a way to specify dynamic scoping instead for a particular -variable. It might not be a bad thing for Emacs to offer both, but -implementing it with dynamic scoping only was much easier. - -@node Extent -@subsection Extent - - @dfn{Extent} refers to the time during program execution that a -variable name is valid. In Emacs Lisp, a variable is valid only while -the form that bound it is executing. This is called @dfn{dynamic -extent}. ``Local'' or ``automatic'' variables in most languages, -including C and Pascal, have dynamic extent. - - One alternative to dynamic extent is @dfn{indefinite extent}. This -means that a variable binding can live on past the exit from the form -that made the binding. Common Lisp and Scheme, for example, support -this, but Emacs Lisp does not. - - To illustrate this, the function below, @code{make-add}, returns a -function that purports to add @var{n} to its own argument @var{m}. This -would work in Common Lisp, but it does not do the job in Emacs Lisp, -because after the call to @code{make-add} exits, the variable @code{n} -is no longer bound to the actual argument 2. - -@example -(defun make-add (n) - (function (lambda (m) (+ n m)))) ; @r{Return a function.} - @result{} make-add -(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} - ; @r{with @code{(make-add 2)}.} - @result{} (lambda (m) (+ n m)) -(add2 4) ; @r{Try to add 2 to 4.} -@error{} Symbol's value as variable is void: n -@end example - -@cindex closures not available - Some Lisp dialects have ``closures,'' objects that are like functions -but record additional variable bindings. Emacs Lisp does not have -closures. - -@node Impl of Scope -@subsection Implementation of Dynamic Scoping -@cindex deep binding - - A simple sample implementation (which is not how Emacs Lisp actually -works) may help you understand dynamic binding. This technique is -called @dfn{deep binding} and was used in early Lisp systems. - - Suppose there is a stack of bindings, which are variable-value pairs. -At entry to a function or to a @code{let} form, we can push bindings -onto the stack for the arguments or local variables created there. We -can pop those bindings from the stack at exit from the binding -construct. - - We can find the value of a variable by searching the stack from top to -bottom for a binding for that variable; the value from that binding is -the value of the variable. To set the variable, we search for the -current binding, then store the new value into that binding. - - As you can see, a function's bindings remain in effect as long as it -continues execution, even during its calls to other functions. That is -why we say the extent of the binding is dynamic. And any other function -can refer to the bindings, if it uses the same variables while the -bindings are in effect. That is why we say the scope is indefinite. - -@cindex shallow binding - The actual implementation of variable scoping in GNU Emacs Lisp uses a -technique called @dfn{shallow binding}. Each variable has a standard -place in which its current value is always found---the value cell of the -symbol. - - In shallow binding, setting the variable works by storing a value in -the value cell. Creating a new binding works by pushing the old value -(belonging to a previous binding) onto a stack, and storing the new -local value in the value cell. Eliminating a binding works by popping -the old value off the stack, into the value cell. - - We use shallow binding because it has the same results as deep -binding, but runs faster, since there is never a need to search for a -binding. - -@node Using Scoping -@subsection Proper Use of Dynamic Scoping - - Binding a variable in one function and using it in another is a -powerful technique, but if used without restraint, it can make programs -hard to understand. There are two clean ways to use this technique: - -@itemize @bullet -@item -Use or bind the variable only in a few related functions, written close -together in one file. Such a variable is used for communication within -one program. - -You should write comments to inform other programmers that they can see -all uses of the variable before them, and to advise them not to add uses -elsewhere. - -@item -Give the variable a well-defined, documented meaning, and make all -appropriate functions refer to it (but not bind it or set it) wherever -that meaning is relevant. For example, the variable -@code{case-fold-search} is defined as ``non-@code{nil} means ignore case -when searching''; various search and replace functions refer to it -directly or through their subroutines, but do not bind or set it. - -Then you can bind the variable in other programs, knowing reliably what -the effect will be. -@end itemize - - In either case, you should define the variable with @code{defvar}. -This helps other people understand your program by telling them to look -for inter-function usage. It also avoids a warning from the byte -compiler. Choose the variable's name to avoid name conflicts---don't -use short names like @code{x}. - -@node Buffer-Local Variables -@section Buffer-Local Variables -@cindex variable, buffer-local -@cindex buffer-local variables - - Global and local variable bindings are found in most programming -languages in one form or another. Emacs, however, also supports -additional, unusual kinds of variable binding, such as -@dfn{buffer-local} bindings, which apply only in one buffer. Having -different values for a variable in different buffers is an important -customization method. (Variables can also have bindings that are -local to each terminal, or to each frame. @xref{Multiple Terminals}, -and @xref{Frame-Local Variables}.) - -@menu -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. -@end menu - -@node Intro to Buffer-Local -@subsection Introduction to Buffer-Local Variables - - A buffer-local variable has a buffer-local binding associated with a -particular buffer. The binding is in effect when that buffer is -current; otherwise, it is not in effect. If you set the variable while -a buffer-local binding is in effect, the new value goes in that binding, -so its other bindings are unchanged. This means that the change is -visible only in the buffer where you made it. - - The variable's ordinary binding, which is not associated with any -specific buffer, is called the @dfn{default binding}. In most cases, -this is the global binding. - - A variable can have buffer-local bindings in some buffers but not in -other buffers. The default binding is shared by all the buffers that -don't have their own bindings for the variable. (This includes all -newly-created buffers.) If you set the variable in a buffer that does -not have a buffer-local binding for it, this sets the default binding, -so the new value is visible in all the buffers that see the default -binding. - - The most common use of buffer-local bindings is for major modes to change -variables that control the behavior of commands. For example, C mode and -Lisp mode both set the variable @code{paragraph-start} to specify that only -blank lines separate paragraphs. They do this by making the variable -buffer-local in the buffer that is being put into C mode or Lisp mode, and -then setting it to the new value for that mode. @xref{Major Modes}. - - The usual way to make a buffer-local binding is with -@code{make-local-variable}, which is what major mode commands typically -use. This affects just the current buffer; all other buffers (including -those yet to be created) will continue to share the default value unless -they are explicitly given their own buffer-local bindings. - -@cindex automatically buffer-local - A more powerful operation is to mark the variable as -@dfn{automatically buffer-local} by calling -@code{make-variable-buffer-local}. You can think of this as making the -variable local in all buffers, even those yet to be created. More -precisely, the effect is that setting the variable automatically makes -the variable local to the current buffer if it is not already so. All -buffers start out by sharing the default value of the variable as usual, -but setting the variable creates a buffer-local binding for the current -buffer. The new value is stored in the buffer-local binding, leaving -the default binding untouched. This means that the default value cannot -be changed with @code{setq} in any buffer; the only way to change it is -with @code{setq-default}. - - @strong{Warning:} When a variable has buffer-local -bindings in one or more buffers, @code{let} rebinds the binding that's -currently in effect. For instance, if the current buffer has a -buffer-local value, @code{let} temporarily rebinds that. If no -buffer-local bindings are in effect, @code{let} rebinds -the default value. If inside the @code{let} you then change to a -different current buffer in which a different binding is in effect, -you won't see the @code{let} binding any more. And if you exit the -@code{let} while still in the other buffer, you won't see the -unbinding occur (though it will occur properly). Here is an example -to illustrate: - -@example -@group -(setq foo 'g) -(set-buffer "a") -(make-local-variable 'foo) -@end group -(setq foo 'a) -(let ((foo 'temp)) - ;; foo @result{} 'temp ; @r{let binding in buffer @samp{a}} - (set-buffer "b") - ;; foo @result{} 'g ; @r{the global value since foo is not local in @samp{b}} - @var{body}@dots{}) -@group -foo @result{} 'g ; @r{exiting restored the local value in buffer @samp{a},} - ; @r{but we don't see that in buffer @samp{b}} -@end group -@group -(set-buffer "a") ; @r{verify the local value was restored} -foo @result{} 'a -@end group -@end example - - Note that references to @code{foo} in @var{body} access the -buffer-local binding of buffer @samp{b}. - - When a file specifies local variable values, these become buffer-local -values when you visit the file. @xref{File Variables,,, emacs, The -GNU Emacs Manual}. - - A buffer-local variable cannot be made frame-local -(@pxref{Frame-Local Variables}) or terminal-local (@pxref{Multiple -Terminals}). - -@node Creating Buffer-Local -@subsection Creating and Deleting Buffer-Local Bindings - -@deffn Command make-local-variable variable -This function creates a buffer-local binding in the current buffer for -@var{variable} (a symbol). Other buffers are not affected. The value -returned is @var{variable}. - -The buffer-local value of @var{variable} starts out as the same value -@var{variable} previously had. If @var{variable} was void, it remains -void. - -@example -@group -;; @r{In buffer @samp{b1}:} -(setq foo 5) ; @r{Affects all buffers.} - @result{} 5 -@end group -@group -(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} - @result{} foo -@end group -@group -foo ; @r{That did not change} - @result{} 5 ; @r{the value.} -@end group -@group -(setq foo 6) ; @r{Change the value} - @result{} 6 ; @r{in @samp{b1}.} -@end group -@group -foo - @result{} 6 -@end group - -@group -;; @r{In buffer @samp{b2}, the value hasn't changed.} -(save-excursion - (set-buffer "b2") - foo) - @result{} 5 -@end group -@end example - -Making a variable buffer-local within a @code{let}-binding for that -variable does not work reliably, unless the buffer in which you do this -is not current either on entry to or exit from the @code{let}. This is -because @code{let} does not distinguish between different kinds of -bindings; it knows only which variable the binding was made for. - -If the variable is terminal-local (@pxref{Multiple Terminals}), or -frame-local (@pxref{Frame-Local Variables}), this function signals an -error. Such variables cannot have buffer-local bindings as well. - -@strong{Warning:} do not use @code{make-local-variable} for a hook -variable. The hook variables are automatically made buffer-local as -needed if you use the @var{local} argument to @code{add-hook} or -@code{remove-hook}. -@end deffn - -@deffn Command make-variable-buffer-local variable -This function marks @var{variable} (a symbol) automatically -buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. - -A peculiar wrinkle of this feature is that binding the variable (with -@code{let} or other binding constructs) does not create a buffer-local -binding for it. Only setting the variable (with @code{set} or -@code{setq}), while the variable does not have a @code{let}-style -binding that was made in the current buffer, does so. - -If @var{variable} does not have a default value, then calling this -command will give it a default value of @code{nil}. If @var{variable} -already has a default value, that value remains unchanged. -Subsequently calling @code{makunbound} on @var{variable} will result -in a void buffer-local value and leave the default value unaffected. - -The value returned is @var{variable}. - -@strong{Warning:} Don't assume that you should use -@code{make-variable-buffer-local} for user-option variables, simply -because users @emph{might} want to customize them differently in -different buffers. Users can make any variable local, when they wish -to. It is better to leave the choice to them. - -The time to use @code{make-variable-buffer-local} is when it is crucial -that no two buffers ever share the same binding. For example, when a -variable is used for internal purposes in a Lisp program which depends -on having separate values in separate buffers, then using -@code{make-variable-buffer-local} can be the best solution. -@end deffn - -@defun local-variable-p variable &optional buffer -This returns @code{t} if @var{variable} is buffer-local in buffer -@var{buffer} (which defaults to the current buffer); otherwise, -@code{nil}. -@end defun - -@defun local-variable-if-set-p variable &optional buffer -This returns @code{t} if @var{variable} will become buffer-local in -buffer @var{buffer} (which defaults to the current buffer) if it is -set there. -@end defun - -@defun buffer-local-value variable buffer -This function returns the buffer-local binding of @var{variable} (a -symbol) in buffer @var{buffer}. If @var{variable} does not have a -buffer-local binding in buffer @var{buffer}, it returns the default -value (@pxref{Default Value}) of @var{variable} instead. -@end defun - -@defun buffer-local-variables &optional buffer -This function returns a list describing the buffer-local variables in -buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is -used.) It returns an association list (@pxref{Association Lists}) in -which each element contains one buffer-local variable and its value. -However, when a variable's buffer-local binding in @var{buffer} is void, -then the variable appears directly in the resulting list. - -@example -@group -(make-local-variable 'foobar) -(makunbound 'foobar) -(make-local-variable 'bind-me) -(setq bind-me 69) -@end group -(setq lcl (buffer-local-variables)) - ;; @r{First, built-in variables local in all buffers:} -@result{} ((mark-active . nil) - (buffer-undo-list . nil) - (mode-name . "Fundamental") - @dots{} -@group - ;; @r{Next, non-built-in buffer-local variables.} - ;; @r{This one is buffer-local and void:} - foobar - ;; @r{This one is buffer-local and nonvoid:} - (bind-me . 69)) -@end group -@end example - -Note that storing new values into the @sc{cdr}s of cons cells in this -list does @emph{not} change the buffer-local values of the variables. -@end defun - -@deffn Command kill-local-variable variable -This function deletes the buffer-local binding (if any) for -@var{variable} (a symbol) in the current buffer. As a result, the -default binding of @var{variable} becomes visible in this buffer. This -typically results in a change in the value of @var{variable}, since the -default value is usually different from the buffer-local value just -eliminated. - -If you kill the buffer-local binding of a variable that automatically -becomes buffer-local when set, this makes the default value visible in -the current buffer. However, if you set the variable again, that will -once again create a buffer-local binding for it. - -@code{kill-local-variable} returns @var{variable}. - -This function is a command because it is sometimes useful to kill one -buffer-local variable interactively, just as it is useful to create -buffer-local variables interactively. -@end deffn - -@defun kill-all-local-variables -This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent'' and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. - -This function also resets certain other information pertaining to the -buffer: it sets the local keymap to @code{nil}, the syntax table to the -value of @code{(standard-syntax-table)}, the case table to -@code{(standard-case-table)}, and the abbrev table to the value of -@code{fundamental-mode-abbrev-table}. - -The very first thing this function does is run the normal hook -@code{change-major-mode-hook} (see below). - -Every major mode command begins by calling this function, which has the -effect of switching to Fundamental mode and erasing most of the effects -of the previous major mode. To ensure that this does its job, the -variables that major modes set should not be marked permanent. - -@code{kill-all-local-variables} returns @code{nil}. -@end defun - -@defvar change-major-mode-hook -The function @code{kill-all-local-variables} runs this normal hook -before it does anything else. This gives major modes a way to arrange -for something special to be done if the user switches to a different -major mode. It is also useful for buffer-specific minor modes -that should be forgotten if the user changes the major mode. - -For best results, make this variable buffer-local, so that it will -disappear after doing its job and will not interfere with the -subsequent major mode. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@cindex permanent local variable -A buffer-local variable is @dfn{permanent} if the variable name (a -symbol) has a @code{permanent-local} property that is non-@code{nil}. -Permanent locals are appropriate for data pertaining to where the file -came from or how to save it, rather than with how to edit the contents. - -@node Default Value -@subsection The Default Value of a Buffer-Local Variable -@cindex default value - - The global value of a variable with buffer-local bindings is also -called the @dfn{default} value, because it is the value that is in -effect whenever neither the current buffer nor the selected frame has -its own binding for the variable. - - The functions @code{default-value} and @code{setq-default} access and -change a variable's default value regardless of whether the current -buffer has a buffer-local binding. For example, you could use -@code{setq-default} to change the default setting of -@code{paragraph-start} for most buffers; and this would work even when -you are in a C or Lisp mode buffer that has a buffer-local value for -this variable. - -@c Emacs 19 feature - The special forms @code{defvar} and @code{defconst} also set the -default value (if they set the variable at all), rather than any -buffer-local value. - -@defun default-value symbol -This function returns @var{symbol}'s default value. This is the value -that is seen in buffers and frames that do not have their own values for -this variable. If @var{symbol} is not buffer-local, this is equivalent -to @code{symbol-value} (@pxref{Accessing Variables}). -@end defun - -@c Emacs 19 feature -@defun default-boundp symbol -The function @code{default-boundp} tells you whether @var{symbol}'s -default value is nonvoid. If @code{(default-boundp 'foo)} returns -@code{nil}, then @code{(default-value 'foo)} would get an error. - -@code{default-boundp} is to @code{default-value} as @code{boundp} is to -@code{symbol-value}. -@end defun - -@defspec setq-default [symbol form]@dots{} -This special form gives each @var{symbol} a new default value, which is -the result of evaluating the corresponding @var{form}. It does not -evaluate @var{symbol}, but does evaluate @var{form}. The value of the -@code{setq-default} form is the value of the last @var{form}. - -If a @var{symbol} is not buffer-local for the current buffer, and is not -marked automatically buffer-local, @code{setq-default} has the same -effect as @code{setq}. If @var{symbol} is buffer-local for the current -buffer, then this changes the value that other buffers will see (as long -as they don't have a buffer-local value), but not the value that the -current buffer sees. - -@example -@group -;; @r{In buffer @samp{foo}:} -(make-local-variable 'buffer-local) - @result{} buffer-local -@end group -@group -(setq buffer-local 'value-in-foo) - @result{} value-in-foo -@end group -@group -(setq-default buffer-local 'new-default) - @result{} new-default -@end group -@group -buffer-local - @result{} value-in-foo -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group - -@group -;; @r{In (the new) buffer @samp{bar}:} -buffer-local - @result{} new-default -@end group -@group -(default-value 'buffer-local) - @result{} new-default -@end group -@group -(setq buffer-local 'another-default) - @result{} another-default -@end group -@group -(default-value 'buffer-local) - @result{} another-default -@end group - -@group -;; @r{Back in buffer @samp{foo}:} -buffer-local - @result{} value-in-foo -(default-value 'buffer-local) - @result{} another-default -@end group -@end example -@end defspec - -@defun set-default symbol value -This function is like @code{setq-default}, except that @var{symbol} is -an ordinary evaluated argument. - -@example -@group -(set-default (car '(a b c)) 23) - @result{} 23 -@end group -@group -(default-value 'a) - @result{} 23 -@end group -@end example -@end defun - -@node File Local Variables -@section File Local Variables -@cindex file local variables - - A file can specify local variable values; Emacs uses these to create -buffer-local bindings for those variables in the buffer visiting that -file. @xref{File variables, , Local Variables in Files, emacs, The -GNU Emacs Manual}, for basic information about file-local variables. -This section describes the functions and variables that affect how -file-local variables are processed. - - If a file-local variable could specify an arbitrary function or Lisp -expression that would be called later, visiting a file could take over -your Emacs. Emacs protects against this by automatically setting only -those file-local variables whose specified values are known to be -safe. Other file-local variables are set only if the user agrees. - - For additional safety, @code{read-circle} is temporarily bound to -@code{nil} when Emacs reads file-local variables (@pxref{Input -Functions}). This prevents the Lisp reader from recognizing circular -and shared Lisp structures (@pxref{Circular Objects}). - -@defopt enable-local-variables -This variable controls whether to process file-local variables. -The possible values are: - -@table @asis -@item @code{t} (the default) -Set the safe variables, and query (once) about any unsafe variables. -@item @code{:safe} -Set only the safe variables and do not query. -@item @code{:all} -Set all the variables and do not query. -@item @code{nil} -Don't set any variables. -@item anything else -Query (once) about all the variables. -@end table -@end defopt - -@defun hack-local-variables &optional mode-only -This function parses, and binds or evaluates as appropriate, any local -variables specified by the contents of the current buffer. The variable -@code{enable-local-variables} has its effect here. However, this -function does not look for the @samp{mode:} local variable in the -@w{@samp{-*-}} line. @code{set-auto-mode} does that, also taking -@code{enable-local-variables} into account (@pxref{Auto Major Mode}). - -This function works by walking the alist stored in -@code{file-local-variables-alist} and applying each local variable in -turn. It calls @code{before-hack-local-variables-hook} and -@code{hack-local-variables-hook} before and after applying the -variables, respectively. - -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return @code{t} if the @w{@samp{-*-}} line or -the local variables list specifies a mode and @code{nil} otherwise. -It does not set the mode nor any other file-local variable. -@end defun - -@defvar file-local-variables-alist -This buffer-local variable holds the alist of file-local variable -settings. Each element of the alist is of the form -@w{@code{(@var{var} . @var{value})}}, where @var{var} is a symbol of -the local variable and @var{value} is its value. When Emacs visits a -file, it first collects all the file-local variables into this alist, -and then the @code{hack-local-variables} function applies them one by -one. -@end defvar - -@defvar before-hack-local-variables-hook -Emacs calls this hook immediately before applying file-local variables -stored in @code{file-local-variables-alist}. -@end defvar - -@defvar hack-local-variables-hook -Emacs calls this hook immediately after it finishes applying -file-local variables stored in @code{file-local-variables-alist}. -@end defvar - -@cindex safe local variable - You can specify safe values for a variable with a -@code{safe-local-variable} property. The property has to be a -function of one argument; any value is safe if the function returns -non-@code{nil} given that value. Many commonly-encountered file -variables have @code{safe-local-variable} properties; these include -@code{fill-column}, @code{fill-prefix}, and @code{indent-tabs-mode}. -For boolean-valued variables that are safe, use @code{booleanp} as the -property value. Lambda expressions should be quoted so that -@code{describe-variable} can display the predicate. - -@defopt safe-local-variable-values -This variable provides another way to mark some variable values as -safe. It is a list of cons cells @code{(@var{var} . @var{val})}, -where @var{var} is a variable name and @var{val} is a value which is -safe for that variable. - -When Emacs asks the user whether or not to obey a set of file-local -variable specifications, the user can choose to mark them as safe. -Doing so adds those variable/value pairs to -@code{safe-local-variable-values}, and saves it to the user's custom -file. -@end defopt - -@defun safe-local-variable-p sym val -This function returns non-@code{nil} if it is safe to give @var{sym} -the value @var{val}, based on the above criteria. -@end defun - -@c @cindex risky local variable Duplicates risky-local-variable - Some variables are considered @dfn{risky}. A variable whose name -ends in any of @samp{-command}, @samp{-frame-alist}, @samp{-function}, -@samp{-functions}, @samp{-hook}, @samp{-hooks}, @samp{-form}, -@samp{-forms}, @samp{-map}, @samp{-map-alist}, @samp{-mode-alist}, -@samp{-program}, or @samp{-predicate} is considered risky. The -variables @samp{font-lock-keywords}, @samp{font-lock-keywords} -followed by a digit, and @samp{font-lock-syntactic-keywords} are also -considered risky. Finally, any variable whose name has a -non-@code{nil} @code{risky-local-variable} property is considered -risky. - -@defun risky-local-variable-p sym -This function returns non-@code{nil} if @var{sym} is a risky variable, -based on the above criteria. -@end defun - - If a variable is risky, it will not be entered automatically into -@code{safe-local-variable-values} as described above. Therefore, -Emacs will always query before setting a risky variable, unless the -user explicitly allows the setting by customizing -@code{safe-local-variable-values} directly. - -@defvar ignored-local-variables -This variable holds a list of variables that should not be given local -values by files. Any value specified for one of these variables is -completely ignored. -@end defvar - - The @samp{Eval:} ``variable'' is also a potential loophole, so Emacs -normally asks for confirmation before handling it. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in @samp{-*-} lines -or local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - -@defopt safe-local-eval-forms -This variable holds a list of expressions that are safe to -evaluate when found in the @samp{Eval:} ``variable'' in a file -local variables list. -@end defopt - - If the expression is a function call and the function has a -@code{safe-local-eval-function} property, the property value -determines whether the expression is safe to evaluate. The property -value can be a predicate to call to test the expression, a list of -such predicates (it's safe if any predicate succeeds), or @code{t} -(always safe provided the arguments are constant). - - Text properties are also potential loopholes, since their values -could include functions to call. So Emacs discards all text -properties from string values specified for file-local variables. - -@node Directory Local Variables -@section Directory Local Variables -@cindex directory local variables - - A directory can specify local variable values common to all files in -that directory; Emacs uses these to create buffer-local bindings for -those variables in buffers visiting any file in that directory. This -is useful when the files in the directory belong to some @dfn{project} -and therefore share the same local variables. - - There are two different methods for specifying directory local -variables: by putting them in a special file, or by defining a -@dfn{project class} for that directory. - -@defvr Constant dir-locals-file -This constant is the name of the file where Emacs expects to find the -directory-local variables. The name of the file is -@file{.dir-locals.el}@footnote{ -The MS-DOS version of Emacs uses @file{_dir-locals.el} instead, due to -limitations of the DOS filesystems. -}. A file by that name in a directory causes Emacs to apply its -settings to any file in that directory or any of its subdirectories. -If some of the subdirectories have their own @file{.dir-locals.el} -files, Emacs uses the settings from the deepest file it finds starting -from the file's directory and moving up the directory tree. The file -specifies local variables as a specially formatted list; see -@ref{Directory Variables, , Per-directory Local Variables, emacs, The -GNU Emacs Manual}, for more details. -@end defvr - -@defun hack-dir-local-variables -This function reads the @code{.dir-locals.el} file and stores the -directory-local variables in @code{file-local-variables-alist} that is -local to the buffer visiting any file in the directory, without -applying them. It also stores the directory-local settings in -@code{dir-locals-class-alist}, where it defines a special class for -the directory in which @file{.dir-locals.el} file was found. This -function works by calling @code{dir-locals-set-class-variables} and -@code{dir-locals-set-directory-class}, described below. -@end defun - -@defun dir-locals-set-class-variables class variables -This function defines a set of variable settings for the named -@var{class}, which is a symbol. You can later assign the class to one -or more directories, and Emacs will apply those variable settings to -all files in those directories. The list in @var{variables} can be of -one of the two forms: @code{(@var{major-mode} . @var{alist})} or -@code{(@var{directory} . @var{list})}. With the first form, if the -file's buffer turns on a mode that is derived from @var{major-mode}, -then the all the variables in the associated @var{alist} are applied; -@var{alist} should be of the form @code{(@var{name} . @var{value})}. -A special value @code{nil} for @var{major-mode} means the settings are -applicable to any mode. - -With the second form of @var{variables}, if @var{directory} is the -initial substring of the file's directory, then @var{list} is applied -recursively by following the above rules; @var{list} should be of one -of the two forms accepted by this function in @var{variables}. -@end defun - -@defun dir-locals-set-directory-class directory class -This function assigns @var{class} to all the files in @code{directory} -and its subdirectories. Thereafter, all the variable settings -specified for @var{class} will be applied to any visited file in -@var{directory} and its children. @var{class} must have been already -defined by @code{dir-locals-set-class-variables} -@end defun - -@defvar dir-locals-class-alist -This alist holds the class symbols and the associated variable -settings. It is updated by @code{dir-locals-set-class-variables}. -@end defvar - -@defvar dir-locals-directory-cache -This alist holds directory names, their assigned class names, and -modification times of the associated directory local variables file. -It is updated by @code{dir-locals-set-directory-class}. -@end defvar - -@node Frame-Local Variables -@section Frame-Local Values for Variables -@cindex frame-local variables - - In addition to buffer-local variable bindings (@pxref{Buffer-Local -Variables}), Emacs supports @dfn{frame-local} bindings. A frame-local -binding for a variable is in effect in a frame for which it was -defined. - - In practice, frame-local variables have not proven very useful. -Ordinary frame parameters are generally used instead (@pxref{Frame -Parameters}). The function @code{make-variable-frame-local}, which -was used to define frame-local variables, has been deprecated since -Emacs 22.2. However, you can still define a frame-specific binding -for a variable @var{var} in frame @var{frame}, by setting the -@var{var} frame parameter for that frame: - -@lisp - (modify-frame-parameters @var{frame} '((@var{var} . @var{value}))) -@end lisp - -@noindent -This causes the variable @var{var} to be bound to the specified -@var{value} in the named @var{frame}. To check the frame-specific -values of such variables, use @code{frame-parameter}. @xref{Parameter -Access}. - - Note that you cannot have a frame-local binding for a variable that -has a buffer-local binding. - -@node Variable Aliases -@section Variable Aliases -@cindex variable aliases - - It is sometimes useful to make two variables synonyms, so that both -variables always have the same value, and changing either one also -changes the other. Whenever you change the name of a -variable---either because you realize its old name was not well -chosen, or because its meaning has partly changed---it can be useful -to keep the old name as an @emph{alias} of the new one for -compatibility. You can do this with @code{defvaralias}. - -@defun defvaralias new-alias base-variable &optional docstring -This function defines the symbol @var{new-alias} as a variable alias -for symbol @var{base-variable}. This means that retrieving the value -of @var{new-alias} returns the value of @var{base-variable}, and -changing the value of @var{new-alias} changes the value of -@var{base-variable}. The two aliased variable names always share the -same value and the same bindings. - -If the @var{docstring} argument is non-@code{nil}, it specifies the -documentation for @var{new-alias}; otherwise, the alias gets the same -documentation as @var{base-variable} has, if any, unless -@var{base-variable} is itself an alias, in which case @var{new-alias} gets -the documentation of the variable at the end of the chain of aliases. - -This function returns @var{base-variable}. -@end defun - - Variable aliases are convenient for replacing an old name for a -variable with a new name. @code{make-obsolete-variable} declares that -the old name is obsolete and therefore that it may be removed at some -stage in the future. - -@defun make-obsolete-variable obsolete-name current-name &optional when -This function makes the byte compiler warn that the variable -@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, it is -the variable's new name; then the warning message says to use -@var{current-name} instead of @var{obsolete-name}. If @var{current-name} -is a string, this is the message and there is no replacement variable. - -If provided, @var{when} should be a string indicating when the -variable was first made obsolete---for example, a date or a release -number. -@end defun - - You can make two variables synonyms and declare one obsolete at the -same time using the macro @code{define-obsolete-variable-alias}. - -@defmac define-obsolete-variable-alias obsolete-name current-name &optional when docstring -This macro marks the variable @var{obsolete-name} as obsolete and also -makes it an alias for the variable @var{current-name}. It is -equivalent to the following: - -@example -(defvaralias @var{obsolete-name} @var{current-name} @var{docstring}) -(make-obsolete-variable @var{obsolete-name} @var{current-name} @var{when}) -@end example -@end defmac - -@defun indirect-variable variable -This function returns the variable at the end of the chain of aliases -of @var{variable}. If @var{variable} is not a symbol, or if @var{variable} is -not defined as an alias, the function returns @var{variable}. - -This function signals a @code{cyclic-variable-indirection} error if -there is a loop in the chain of symbols. -@end defun - -@example -(defvaralias 'foo 'bar) -(indirect-variable 'foo) - @result{} bar -(indirect-variable 'bar) - @result{} bar -(setq bar 2) -bar - @result{} 2 -@group -foo - @result{} 2 -@end group -(setq foo 0) -bar - @result{} 0 -foo - @result{} 0 -@end example - -@node Variables with Restricted Values -@section Variables with Restricted Values - - Ordinary Lisp variables can be assigned any value that is a valid -Lisp object. However, certain Lisp variables are not defined in Lisp, -but in C. Most of these variables are defined in the C code using -@code{DEFVAR_LISP}. Like variables defined in Lisp, these can take on -any value. However, some variables are defined using -@code{DEFVAR_INT} or @code{DEFVAR_BOOL}. @xref{Defining Lisp -variables in C,, Writing Emacs Primitives}, in particular the -description of functions of the type @code{syms_of_@var{filename}}, -for a brief discussion of the C implementation. - - Variables of type @code{DEFVAR_BOOL} can only take on the values -@code{nil} or @code{t}. Attempting to assign them any other value -will set them to @code{t}: - -@example -(let ((display-hourglass 5)) - display-hourglass) - @result{} t -@end example - -@defvar byte-boolean-vars -This variable holds a list of all variables of type @code{DEFVAR_BOOL}. -@end defvar - - Variables of type @code{DEFVAR_INT} can only take on integer values. -Attempting to assign them any other value will result in an error: - -@example -(setq window-min-height 5.0) -@error{} Wrong type argument: integerp, 5.0 -@end example - -@ignore - arch-tag: 5ff62c44-2b51-47bb-99d4-fea5aeec5d3e -@end ignore diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi deleted file mode 100644 index 4aa5783e332..00000000000 --- a/doc/lispref/vol1.texi +++ /dev/null @@ -1,1548 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 1 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 1...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp1-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 1 chapter numbering at 1; this must be listed as chapno0. -\global\chapno=0 -@end tex - -@c Version of the manual and of Emacs. -@c Please remember to update the edition number in README as well. -@set VERSION 3.0 -@set EMACSVER 23.1 -@set DATE July 2009 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 1 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 - -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. -@end ifnottex - -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Writing customization declarations. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 22. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will open code. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Writing Customization Definitions - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: How the Emacs Lisp debugger is implemented. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Compilation Errors:: How to find errors that show up in - byte compilation. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Styles:: Specifying rules for performing completion. -* Programmed Completion:: Writing your own completion-function. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: How a mode can provide a menu - of definitions in the buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Basics:: -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-level functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text-only terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for - network connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs' Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: The usual conventions for displaying - nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include hash.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include customize.texi -@include loading.texi -@include compile.texi -@include advice.texi - -@c This includes edebug.texi. -@include debugging.texi -@include streams.texi -@include minibuf.texi -@include commands.texi - -@include keymaps.texi -@include modes.texi -@include help.texi -@include files.texi - -@include backups.texi - -@c ================ Beginning of Volume 2 ================ -@c include buffers.texi -@c include windows.texi -@c include frames.texi - -@c include positions.texi -@c include markers.texi -@c include text.texi -@c include nonascii.texi - -@c include searching.texi -@c include syntax.texi -@c include abbrevs.texi -@c include processes.texi - -@c include display.texi -@c include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@c include anti.texi -@c include doclicense.texi -@c include gpl.texi -@c include tips.texi -@c include internals.texi -@c include errors.texi -@c include locals.texi -@c include maps.texi -@c include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. - -@ignore - arch-tag: 9594760d-8801-4d1b-aeb9-f3b3166b5be2 -@end ignore diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi deleted file mode 100644 index e4ea5c7f276..00000000000 --- a/doc/lispref/vol2.texi +++ /dev/null @@ -1,1547 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c This file is used for printing the GNU Emacs Lisp Reference Manual -@c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 2 -@c %**end of header - -@c See two-volume-cross-refs.txt. -@tex -\message{Formatting for two volume edition...Volume 2...} -% -% Read special toc file, set up in two-volume.make. -\gdef\tocreadfilename{elisp2-toc-ready.toc} -% -% Don't make outlines, they're not needed and \readdatafile can't pay -% attention to the special definition above. -\global\let\pdfmakeoutlines=\relax -% -% Start volume 2 chapter numbering at 27; this must be listed as chapno26 -\global\chapno=26 -@end tex - -@c Version of the manual and of Emacs. -@c Please remember to update the edition number in README as well. -@set VERSION 3.0 -@set EMACSVER 23.1 -@set DATE July 2009 - -@dircategory Emacs -@direntry -* Elisp: (elisp). The Emacs Lisp Reference Manual. -@end direntry - -@c in general, keep the following line commented out, unless doing a -@c copy of this manual that will be published. the manual should go -@c onto the distribution in the full, 8.5 x 11" size. -@set smallbook - -@ifset smallbook -@smallbook -@end ifset - -@c per rms and peterb, use 10pt fonts for the main text, mostly to -@c save on paper cost. -@c Do this inside @tex for now, so current makeinfo does not complain. -@tex -@ifset smallbook -@fonttextsize 10 -\global\let\urlcolor=\Black % don't print links in grayscale -\global\let\linkcolor=\Black -@end ifset -\global\hbadness=6666 % don't worry about not-too-underfull boxes -@end tex - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@c We use the "type index" to index new functions and variables. -@c @syncodeindex tp fn - -@copying -This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* -corresponding to Emacs version @value{EMACSVER}. - -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License,'' with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle Volume 2 -@subtitle For Emacs Version @value{EMACSVER} -@subtitle Revision @value{VERSION}, @value{DATE} - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -@insertcopying - -@sp 2 -Published by the Free Software Foundation @* -51 Franklin St, Fifth Floor @* -Boston, MA 02110-1301 @* -USA @* -ISBN 1-882114-74-4 - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage - - -@c Print the tables of contents -@summarycontents -@contents - - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Emacs Lisp - -This Info file contains edition @value{VERSION} of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version @value{EMACSVER}. -@end ifnottex - -@menu -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Hash Tables:: Very fast lookup-tables. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. -* Customization:: Writing customization declarations. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Advising Functions:: Adding to the definition of a function. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple system-level windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Non-ASCII Characters:: Non-ASCII text in buffers and strings. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* Display:: Features for controlling the screen display. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. - -Appendices - -* Antinews:: Info for users downgrading to Emacs 22. -* GNU Free Documentation License:: The license for this documentation. -* GPL:: Conditions for copying and changing GNU Emacs. -* Tips:: Advice and coding conventions for Emacs Lisp. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: - List of variables buffer-local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - -@ignore -* New Symbols:: New functions and variables in Emacs @value{EMACSVER}. -@end ignore - -@c Do NOT modify the following 3 lines! They must have this form to -@c be correctly identified by `texinfo-multiple-files-update'. In -@c particular, the detailed menu header line MUST be identical to the -@c value of `texinfo-master-menu-header'. See texnfo-upd.el. - -@detailmenu - --- The Detailed Node Listing --- - --------------------------------- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Version Info:: Which Emacs version is running? -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use when examples print text. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, @code{electric-future-map}. - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Circular Objects:: Read syntax for circular structure. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Char-Table Type:: One-dimensional sparse arrays indexed by characters. -* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. -* Hash Table Type:: Super-fast lookup tables. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -Character Type - -* Basic Char Syntax:: Syntax for regular characters. -* General Escape Syntax:: How to specify characters by their codes. -* Ctl-Char Syntax:: Syntax for control characters. -* Meta-Char Syntax:: Syntax for meta-characters. -* Other Char Bits:: Syntax for hyper-, super-, and alt-characters. - -Cons Cell and List Types - -* Box Diagrams:: Drawing pictures of lists. -* Dotted Pair Notation:: A general syntax for cons cells. -* Association List Type:: A specially constructed list. - -String Type - -* Syntax for Strings:: How to specify Lisp strings. -* Non-ASCII in Strings:: International characters in strings. -* Nonprinting Characters:: Literal unprintable characters in strings. -* Text Props and Strings:: Strings with text properties. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Terminal Type:: A terminal device displays frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Frame Configuration Type:: Recording the status of all frames. -* Process Type:: A subprocess of Emacs running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. -* Font Type:: Fonts for displaying text. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Modifying Strings:: Altering the contents of an existing string. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting to and from characters and strings. -* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. -* Case Conversion:: Case conversion functions. -* Case Tables:: Customizing case conversion. - -Lists - -* Cons Cells:: How lists are made out of cons cells. -* List-related Predicates:: Is this object a list? Comparing two lists. -* List Elements:: Extracting the pieces of a list. -* Building Lists:: Creating list structure. -* List Variables:: Modifying lists stored in variables. -* Modifying Lists:: Storing new pieces into an existing list. -* Sets And Lists:: A list can represent a finite mathematical set. -* Association Lists:: A list can represent a finite relation or mapping. -* Rings:: Managing a fixed-size ring of objects. - -Modifying Existing List Structure - -* Setcar:: Replacing an element in a list. -* Setcdr:: Replacing part of the list backbone. - This can be used to remove or add elements. -* Rearrangement:: Reordering the elements in a list; combining lists. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -* Char-Tables:: How to work with char-tables. -* Bool-Vectors:: How to work with bool-vectors. - -Hash Tables - -* Creating Hash:: Functions to create hash tables. -* Hash Access:: Reading and writing the hash table contents. -* Defining Hash:: Defining new comparison methods. -* Other Hash:: Miscellaneous. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Property Lists - -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. - -Evaluation - -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in - the program). -* Eval:: How to invoke the Lisp interpreter explicitly. - -Kinds of Forms - -* Self-Evaluating Forms:: Forms that evaluate to themselves. -* Symbol Forms:: Symbols evaluate as variables. -* Classifying Lists:: How to distinguish various sorts of list forms. -* Function Indirection:: When a symbol appears as the car of a list, - we find the real function via the symbol. -* Function Forms:: Forms that call functions. -* Macro Forms:: Forms that call macros. -* Special Forms:: "Special forms" are idiosyncratic primitives, - most of them extremely important. -* Autoloading:: Functions set up to load files - containing their real definitions. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: Things you should think about when you - define a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -* File Local Variables:: Handling local variable lists in files. -* Directory Local Variables:: Local variables common to all files in a - directory. -* Frame-Local Variables:: Frame-local bindings for variables. -* Variable Aliases:: Variables that are aliases for other variables. -* Variables with Restricted Values:: Non-constant variables whose value can - @emph{not} be an arbitrary Lisp object. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own buffer-local values. - -Functions - -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Obsolete Functions:: Declaring functions obsolete. -* Inline Functions:: Defining functions that the compiler - will open code. -* Declaring Functions:: Telling the compiler that a function is defined. -* Function Safety:: Determining whether a function is safe to call. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* Simple Macro:: A basic example. -* Expansion:: How, when and why macros are expanded. -* Compiling Macros:: How macros are expanded by the compiler. -* Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. -* Problems with Macros:: Don't evaluate the macro arguments too many times. - Don't hide the user's variables. -* Indenting Macros:: Specifying how to indent macro calls. - -Common Problems Using Macros - -* Wrong Time:: Do the work in the expansion, not in the macro. -* Argument Evaluation:: The expansion should evaluate each macro arg once. -* Surprising Local Vars:: Local variable bindings in the expansion - require special care. -* Eval During Expansion:: Don't evaluate them; put them in the expansion. -* Repeated Expansion:: Avoid depending on how many times expansion is done. - -Writing Customization Definitions - -* Common Keywords:: Common keyword arguments for all kinds of - customization declarations. -* Group Definitions:: Writing customization group definitions. -* Variable Definitions:: Declaring user options. -* Customization Types:: Specifying the type of a user option. - -Customization Types - -* Simple Types:: Simple customization types: sexp, integer, number, - string, file, directory, alist. -* Composite Types:: Build new types from other types or data. -* Splicing into Lists:: Splice elements into list with @code{:inline}. -* Type Keywords:: Keyword-argument pairs in a customization type. -* Defining New Types:: Give your type a name. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Load Suffixes:: Details about the suffixes that @code{load} tries. -* Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to "unload" a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. - -Byte Compilation - -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Compiler Errors:: Handling compiler error messages. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Advising Emacs Lisp Functions - -* Simple Advice:: A simple example to explain the basics of advice. -* Defining Advice:: Detailed description of @code{defadvice}. -* Around-Advice:: Wrapping advice around a function's definition. -* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. -* Activation of Advice:: Advice doesn't do anything until you activate it. -* Enabling Advice:: You can enable or disable each piece of advice. -* Preactivation:: Preactivation is a way of speeding up the - loading of compiled advice. -* Argument Access in Advice:: How advice can access the function's arguments. -* Advising Primitives:: Accessing arguments when advising a primitive. -* Combined Definition:: How advice is implemented. - -Debugging Lisp Programs - -* Debugger:: How the Emacs Lisp debugger is implemented. -* Edebug:: A source-level Emacs Lisp debugger. -* Syntax Errors:: How to find syntax errors. -* Test Coverage:: Ensuring you have tested all branches in your code. -* Compilation Errors:: How to find errors that show up in - byte compilation. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* Infinite Loops:: Stopping and debugging a program that doesn't exit. -* Function Debugging:: Entering it when a certain function is called. -* Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. -* Debugger Commands:: Commands used while in the debugger. -* Invoking the Debugger:: How to call the function @code{debug}. -* Internals of Debugger:: Subroutines of the debugger, and global variables. - -Edebug - -* Using Edebug:: Introduction to use of Edebug. -* Instrumenting:: You must instrument your code - in order to debug it with Edebug. -* Edebug Execution Modes:: Execution modes, stopping more or less often. -* Jumping:: Commands to jump to a specified place. -* Edebug Misc:: Miscellaneous commands. -* Breaks:: Setting breakpoints to make the program stop. -* Trapping Errors:: Trapping errors with Edebug. -* Edebug Views:: Views inside and outside of Edebug. -* Edebug Eval:: Evaluating expressions within Edebug. -* Eval List:: Expressions whose values are displayed - each time you enter Edebug. -* Printing in Edebug:: Customization of printing. -* Trace Buffer:: How to produce trace output in a buffer. -* Coverage Testing:: How to test evaluation coverage. -* The Outside Context:: Data that Edebug saves and restores. -* Edebug and Macros:: Specifying how to handle macro calls. -* Edebug Options:: Option variables for customizing Edebug. - -Breaks - -* Breakpoints:: Breakpoints at stop points. -* Global Break Condition:: Breaking on an event. -* Source Breakpoints:: Embedding breakpoints in source code. - -The Outside Context - -* Checking Whether to Stop::When Edebug decides what to do. -* Edebug Display Update:: When Edebug updates the display. -* Edebug Recursive Edit:: When Edebug stops execution. - -Edebug and Macros - -* Instrumenting Macro Calls::The basic problem. -* Specification List:: How to specify complex patterns of evaluation. -* Backtracking:: What Edebug does when matching fails. -* Specification Examples:: To help understand specifications. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing - functions do. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Initial Input:: Specifying initial contents for the minibuffer. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. -* Minibuffer Commands:: Commands used as key bindings in minibuffers. -* Minibuffer Contents:: How such commands access the minibuffer text. -* Minibuffer Windows:: Operating on the special minibuffer windows. -* Recursive Mini:: Whether recursive entry to minibuffer is allowed. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.). -* Reading File Names:: Using completion to read file names and - shell commands. -* Completion Styles:: Specifying rules for performing completion. -* Programmed Completion:: Writing your own completion-function. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Distinguish Interactive:: Making a command distinguish interactive calls. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Adjusting Point:: Adjustment of point after a command. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Special Events:: Events processed immediately and individually. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Input Events - -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events the system can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Mouse:: Functions to extract info from mouse events. -* Accessing Scroll:: Functions to get info from scroll bar events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. - -Reading Input - -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Event Mod:: How Emacs modifies events as they are read. -* Invoking the Input Method:: How reading an event uses the input method. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. - -Keymaps - -* Key Sequences:: Key sequences as Lisp objects. -* Keymap Basics:: Basic concepts of keymaps. -* Format of Keymaps:: What a keymap looks like as a Lisp object. -* Creating Keymaps:: Functions to create and copy keymaps. -* Inheritance and Keymaps:: How one keymap can inherit the bindings - of another keymap. -* Prefix Keys:: Defining a key with a keymap as its definition. -* Active Keymaps:: How Emacs searches the active keymaps - for a key binding. -* Searching Keymaps:: A pseudo-Lisp summary of searching active maps. -* Controlling Active Maps:: Each buffer has a local keymap - to override the standard (global) bindings. - A minor mode can also override them. -* Key Lookup:: Finding a key's binding in one keymap. -* Functions for Key Lookup:: How to request key lookup. -* Changing Key Bindings:: Redefining a key in a keymap. -* Remapping Commands:: A keymap can translate one command to another. -* Translation Keymaps:: Keymaps for translating sequences of events. -* Key Binding Commands:: Interactive interfaces for redefining keys. -* Scanning Keymaps:: Looking through all keymaps, for printing help. -* Menu Keymaps:: Defining a menu as a keymap. - -Menu Keymaps - -* Defining Menus:: How to make a keymap that defines a menu. -* Mouse Menus:: How users actuate the menu with the mouse. -* Keyboard Menus:: How users actuate the menu with the keyboard. -* Menu Example:: Making a simple menu. -* Menu Bar:: How to customize the menu bar. -* Tool Bar:: A tool bar is a row of images. -* Modifying Menus:: How to add new items to a menu. - -Defining Menus - -* Simple Menu Items:: A simple kind of menu key binding, - limited in capabilities. -* Extended Menu Items:: More powerful menu item definitions - let you specify keywords to enable - various features. -* Menu Separators:: Drawing a horizontal line through a menu. -* Alias Menu Items:: Using command aliases in menu items. - -Major and Minor Modes - -* Hooks:: How to use hooks; how to write code that provides hooks. -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Imenu:: How a mode can provide a menu - of definitions in the buffer. -* Font Lock Mode:: How modes can highlight text according to syntax. -* Desktop Save Mode:: How modes can have buffer state saved between - Emacs sessions. - -Hooks - -* Running Hooks:: How to run a hook. -* Setting Hooks:: How to put functions on a hook, or remove them. - -Major Modes - -* Major Mode Basics:: -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -* Generic Modes:: Defining a simple major mode that supports - comment syntax and Font Lock mode. -* Mode Hooks:: Hooks run at the end of major mode functions. -* Example Major Modes:: Text mode and Lisp modes. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -* Defining Minor Modes:: A convenient facility for defining minor modes. - -Mode Line Format - -* Mode Line Basics:: Basic ideas of mode line control. -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Top:: The top level variable, mode-line-format. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -* Properties in Mode:: Using text properties in the mode line. -* Header Lines:: Like a mode line, but at the top. -* Emulating Mode Line:: Formatting text as the mode line would. - -Font Lock Mode - -* Font Lock Basics:: Overview of customizing Font Lock. -* Search-based Fontification:: Fontification based on regexps. -* Customizing Keywords:: Customizing search-based fontification. -* Other Font Lock Variables:: Additional customization facilities. -* Levels of Font Lock:: Each mode can define alternative levels - so that the user can select more or less. -* Precalculated Fontification:: How Lisp programs that produce the buffer - contents can also specify how to fontify it. -* Faces for Font Lock:: Special faces specifically for Font Lock. -* Syntactic Font Lock:: Fontification based on syntax tables. -* Setting Syntax Properties:: Defining character syntax based on context - using the Font Lock mechanism. -* Multiline Font Lock:: How to coerce Font Lock into properly - highlighting multiline constructs. - -Multiline Font Lock Constructs - -* Font Lock Multiline:: Marking multiline chunks with a text property. -* Region to Fontify:: Controlling which region gets refontified - after a buffer change. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing Files:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Format Conversion:: Conversion to and from various file formats. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -* Locating Files:: How to find a file in standard places. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Relative File Names:: Some file names are relative to a current directory. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. - -File Format Conversion - -* Format Conversion Overview:: @code{insert-file-contents} and @code{write-region}. -* Format Conversion Round-Trip:: Using @code{format-alist}. -* Format Conversion Piecemeal:: Specifying non-paired conversion. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so that primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some - other buffer. -* Swapping Text:: Swapping text between two buffers. -* Buffer Gap:: The gap in the buffer. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-level functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Terminals:: Displaying on several different devices. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Terminal Parameters:: Parameters common for all frames on terminal. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other windows; - lowering it makes the others hide it. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shape:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. -* Color Names:: Getting the definitions of color names. -* Text Terminal Colors:: Defining colors for text-only terminals. -* Resources:: Getting resource values from the server. -* Display Feature Testing:: Determining the features of a terminal. - -Frame Parameters - -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. -* Geometry:: Parsing geometry specifications. - -Window Frame Parameters - -* Basic Parameters:: Parameters that are fundamental. -* Position Parameters:: The position of the frame on the screen. -* Size Parameters:: Frame's size. -* Layout Parameters:: Size of parts of the frame, and - enabling or disabling some parts. -* Buffer Parameters:: Which buffers have been or should be shown. -* Management Parameters:: Communicating with the window manager. -* Cursor Parameters:: Controlling the cursor appearance. -* Font and Color Parameters:: Fonts and colors for the frame text. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers::Finding the marker's buffer or character position. -* Marker Insertion Types:: Two ways a marker can relocate when you - insert where it points. -* Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How "the mark" is implemented with a marker. -* The Region:: How to access "the region". - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for - later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Adaptive Fill:: Adaptive Fill mode chooses a fill prefix - from context. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Transposition:: Swapping two portions of a buffer. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. -* Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". -* Atomic Changes:: Installing several buffer changes "atomically". -* Change Hooks:: Supplying functions to be run when text is changed. - -The Kill Ring - -* Kill Ring Concepts:: What text looks like in the kill ring. -* Kill Functions:: Functions that kill text. -* Yanking:: How yanking is done. -* Yank Commands:: Commands that access the kill ring. -* Low-Level Kill Ring:: Functions and variables for kill ring access. -* Internals of Kill Ring:: Variables that hold kill ring data. - -Indentation - -* Primitive Indent:: Functions used to count and insert indentation. -* Mode-Specific Indent:: Customize indentation for different modes. -* Region Indent:: Indent all the lines in a region. -* Relative Indent:: Indent the current line based on previous lines. -* Indent Tabs:: Adjustable, typewriter-like tab stops. -* Motion by Indent:: Move to first non-blank character. - -Text Properties - -* Examining Properties:: Looking at the properties of one character. -* Changing Properties:: Setting the properties of a range of text. -* Property Search:: Searching for where a property changes value. -* Special Properties:: Particular properties with special meanings. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Clickable Text:: Using text properties to make regions of text - do something when you click on them. -* Fields:: The @code{field} property defines - fields within the buffer. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Non-@acronym{ASCII} Characters - -* Text Representations:: How Emacs represents text. -* Converting Representations:: Converting unibyte to multibyte and vice versa. -* Selecting a Representation:: Treating a byte sequence as unibyte or multi. -* Character Codes:: How unibyte and multibyte relate to - codes of individual characters. -* Character Properties:: Character attributes that define their - behavior and handling. -* Character Sets:: The space of possible character codes - is divided into various character sets. -* Scanning Charsets:: Which character sets are used in a buffer? -* Translation of Characters:: Translation tables are used for conversion. -* Coding Systems:: Coding systems are conversions for saving files. -* Input Methods:: Input methods allow users to enter various - non-ASCII characters without special keyboards. -* Locales:: Interacting with the POSIX locale. - -Coding Systems - -* Coding System Basics:: Basic concepts. -* Encoding and I/O:: How file I/O functions handle coding systems. -* Lisp and Coding Systems:: Functions to operate on coding system names. -* User-Chosen Coding Systems:: Asking the user to choose a coding system. -* Default Coding Systems:: Controlling the default choices. -* Specifying Coding Systems:: Requesting a particular coding system - for a single file operation. -* Explicit Encoding:: Encoding or decoding text without doing I/O. -* Terminal I/O Encoding:: Use of encoding for terminal I/O. -* MS-DOS File Types:: How DOS "text" and "binary" files - relate to coding systems. - -Searching and Matching - -* String Search:: Search for an exact match. -* Searching and Case:: Case-independent or case-significant searching. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Match Data:: Finding out which part of the text matched, - after a string or regexp search. -* Search and Replace:: Commands that loop, searching and replacing. -* Standard Regexps:: Useful regexps for finding sentences, pages,... - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -* Regexp Functions:: Functions for operating on regular expressions. - -Syntax of Regular Expressions - -* Regexp Special:: Special characters in regular expressions. -* Char Classes:: Character classes used in regular expressions. -* Regexp Backslash:: Backslash-sequences in regular expressions. - -The Match Data - -* Replacing Match:: Replacing a substring that was matched. -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. - -Syntax Tables - -* Syntax Basics:: Basic concepts of syntax tables. -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Syntax Properties:: Overriding syntax with text properties. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -* Categories:: Another way of classifying character syntax. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Parsing Expressions - -* Motion via Parsing:: Motion functions that work by parsing. -* Position Parse:: Determining the syntactic state of a position. -* Parser State:: How Emacs represents a syntactic state. -* Low-Level Parsing:: Parsing across a specified region. -* Control Parsing:: Parameters that affect parsing. - -Abbrevs and Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Abbrev Tables:: Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Abbrev Files:: Saving abbrevs in files. -* Abbrev Expansion:: Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -* Abbrev Properties:: How to read and set abbrev properties. - Which properties have which effect. -* Abbrev Table Properties:: How to read and set abbrev table properties. - Which properties have which effect. - -Processes - -* Subprocess Creation:: Functions that start subprocesses. -* Shell Arguments:: Quoting an argument to pass it to a shell. -* Synchronous Processes:: Details of using synchronous subprocesses. -* Asynchronous Processes:: Starting up an asynchronous subprocess. -* Deleting Processes:: Eliminating an asynchronous subprocess. -* Process Information:: Accessing run-status and other attributes. -* Input to Processes:: Sending input to an asynchronous subprocess. -* Signals to Processes:: Stopping, continuing or interrupting - an asynchronous subprocess. -* Output from Processes:: Collecting output from an asynchronous subprocess. -* Sentinels:: Sentinels run when process run-status changes. -* Query Before Exit:: Whether to query if exiting will kill a process. -* System Processes:: Accessing other processes running on your system. -* Transaction Queues:: Transaction-based communication with subprocesses. -* Network:: Opening network connections. -* Network Servers:: Network servers let Emacs accept net connections. -* Datagrams:: UDP network connections. -* Low-Level Network:: Lower-level but more general function - to create connections and servers. -* Misc Network:: Additional relevant functions for - network connections. -* Serial Ports:: Communicating with serial ports. -* Byte Packing:: Using bindat to pack and unpack binary data. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Decoding Output:: Filters can get unibyte or multibyte strings. -* Accepting Output:: How to wait until process output arrives. - -Low-Level Network Access - -* Network Processes:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on - the machine you are using. - -Packing and Unpacking Byte Arrays - -* Bindat Spec:: Describing data layout. -* Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Forcing Redisplay:: Forcing redisplay. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Displaying messages at the bottom of the screen. -* Warnings:: Displaying warning messages for the user. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Width:: How wide a character or string is on the screen. -* Line Height:: Controlling the height of lines. -* Faces:: A face defines a graphics style - for text characters: font, colors, etc. -* Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. -* Display Property:: Enabling special display features. -* Images:: Displaying images in Emacs buffers. -* Buttons:: Adding clickable buttons to Emacs buffers. -* Abstract Display:: Emacs' Widget for Object Collections. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: The usual conventions for displaying - nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -The Echo Area - -* Displaying Messages:: Explicitly displaying text in the echo area. -* Progress:: Informing user about progress of a long operation. -* Logging Messages:: Echo area messages are logged for the user. -* Echo Area Customization:: Controlling the echo area. - -Reporting Warnings - -* Warning Basics:: Warnings concepts and functions to report them. -* Warning Variables:: Variables programs bind to customize - their warnings. -* Warning Options:: Variables users set to control display of warnings. - -Overlays - -* Managing Overlays:: Creating and moving overlays. -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Finding Overlays:: Searching for overlays. - -Faces - -* Defining Faces:: How to define a face with @code{defface}. -* Face Attributes:: What is in a face? -* Attribute Functions:: Functions to examine and set face attributes. -* Displaying Faces:: How Emacs combines the faces specified for - a character. -* Face Remapping:: Remapping faces to alternative definitions. -* Face Functions:: How to define and examine faces. -* Auto Faces:: Hook for automatic face assignment. -* Font Selection:: Finding the best available font for a face. -* Font Lookup:: Looking up the names of available fonts - and information about them. -* Fontsets:: A fontset is a collection of fonts - that handle a range of character sets. -* Low-Level Font:: Lisp representation for character display fonts. - -Fringes - -* Fringe Size/Pos:: Specifying where to put the window fringes. -* Fringe Indicators:: Displaying indicator icons in the window fringes. -* Fringe Cursors:: Displaying cursors in the right fringe. -* Fringe Bitmaps:: Specifying bitmaps for fringe indicators. -* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes. -* Overlay Arrow:: Display of an arrow to indicate position. - -The @code{display} Property - -* Replacing Specs:: Display specs that replace the text. -* Specified Space:: Displaying one space with a specified width. -* Pixel Specification:: Specifying space width or height in pixels. -* Other Display Specs:: Displaying an image; magnifying text; moving it - up or down on the page; adjusting the width - of spaces within text. -* Display Margins:: Displaying text or images to the side of - the main text. - -Images - -* Image Formats:: Supported image formats. -* Image Descriptors:: How to specify an image for use in @code{:display}. -* XBM Images:: Special features for XBM format. -* XPM Images:: Special features for XPM format. -* GIF Images:: Special features for GIF format. -* TIFF Images:: Special features for TIFF format. -* PostScript Images:: Special features for PostScript format. -* Other Image Types:: Various other formats are supported. -* Defining Images:: Convenient ways to define an image for later use. -* Showing Images:: Convenient ways to display an image once - it is defined. -* Image Cache:: Internal mechanisms of image display. - -Buttons - -* Button Properties:: Button properties with special meanings. -* Button Types:: Defining common properties for classes of buttons. -* Making Buttons:: Adding buttons to Emacs buffers. -* Manipulating Buttons:: Getting and setting properties of buttons. -* Button Buffer Commands:: Buffer-wide commands and bindings for buttons. - -Abstract Display - -* Abstract Display Functions:: Functions in the Ewoc package. -* Abstract Display Example:: Example of using Ewoc. - -Display Tables - -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. - -Operating System Interface - -* Starting Up:: Customizing Emacs startup processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* User Identification:: Finding the name and user id of the user. -* Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to - calendrical data and vice versa. -* Time Parsing:: Converting a time from numeric form to text - and vice versa. -* Processor Run Time:: Getting the run time used by Emacs. -* Time Calculations:: Adding, subtracting, comparing times, etc. -* Timers:: Setting a timer to call a function at a - certain time. -* Idle Timers:: Setting a timer to call a function when Emacs has - been idle for a certain length of time. -* Terminal Input:: Accessing and recording terminal input. -* Terminal Output:: Controlling and recording terminal output. -* Sound Output:: Playing sounds on the computer's speaker. -* X11 Keysyms:: Operating on key symbols for X Windows. -* Batch Mode:: Running Emacs without terminal interaction. -* Session Management:: Saving and restoring state with - X Session Management. - -Starting Up Emacs - -* Startup Summary:: Sequence of actions Emacs performs at startup. -* Init File:: Details on reading the init file. -* Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command-Line Arguments:: How command-line arguments are processed, - and how you can customize them. - -Getting Out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Terminal Input - -* Input Modes:: Options for how input is processed. -* Recording Input:: Saving histories of recent or all input events. - -Tips and Conventions - -* Coding Conventions:: Conventions for clean and robust programs. -* Key Binding Conventions:: Which keys should be bound by which programs. -* Programming Tips:: Making Emacs code fit smoothly in Emacs. -* Compilation Tips:: Making compiled code run fast. -* Warning Tips:: Turning off compiler warnings. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. - -GNU Emacs Internals - -* Building Emacs:: How the dumped Emacs is made. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Memory Usage:: Info about total size of Lisp objects made so far. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end detailmenu -@end menu - -@c include intro.texi -@c include objects.texi -@c include numbers.texi -@c include strings.texi - -@c include lists.texi -@c include sequences.texi -@c include hash.texi -@c include symbols.texi -@c include eval.texi - -@c include control.texi -@c include variables.texi -@c include functions.texi -@c include macros.texi - -@c include customize.texi -@c include loading.texi -@c include compile.texi -@c include advice.texi - -@c This includes edebug.texi. -@c include debugging.texi -@c include streams.texi -@c include minibuf.texi -@c include commands.texi - -@c include keymaps.texi -@c include modes.texi -@c include help.texi -@c include files.texi - -@c include backups.texi - -@c ================ Beginning of Volume 2 ================ -@include buffers.texi -@include windows.texi -@include frames.texi - -@include positions.texi -@include markers.texi -@include text.texi -@include nonascii.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi -@include processes.texi - -@include display.texi -@include os.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include anti.texi -@include doclicense.texi -@include gpl.texi -@include tips.texi -@include internals.texi -@include errors.texi -@include locals.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@ignore -@node New Symbols, , Index, Top -@unnumbered New Symbols Since the Previous Edition - -@printindex tp -@end ignore - -@bye - - -These words prevent "local variables" above from confusing Emacs. - -@ignore - arch-tag: dfdbecf8-fec2-49c1-8427-3e8ac8b0b849 -@end ignore diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi deleted file mode 100644 index 539ed6e4514..00000000000 --- a/doc/lispref/windows.texi +++ /dev/null @@ -1,2603 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../../info/windows -@node Windows, Frames, Buffers, Top -@chapter Windows - - This chapter describes most of the functions and variables related to -Emacs windows. @xref{Frames and Windows}, for how windows relate to -frames. @xref{Display}, for information on how text is displayed in -windows. - -@menu -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-level functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Dedicated Windows:: How to avoid displaying another buffer in - a specific window. -* Window Point:: Each window has its own location of point. -* Window Start and End:: Buffer positions indicating which text is - on-screen in a window. -* Textual Scrolling:: Moving text up and down through the window. -* Vertical Scrolling:: Moving the contents up and down on the window. -* Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. -* Window Configurations:: Saving and restoring the state of the screen. -* Window Parameters:: Associating additional information with windows. -* Window Hooks:: Hooks for scrolling, window size changes, - redisplay going past a certain point, - or window configuration changes. -@end menu - -@node Basic Windows -@section Basic Concepts of Emacs Windows -@cindex window -@cindex selected window - - A @dfn{window} in Emacs is the physical area of the screen in which a -buffer is displayed. The term is also used to refer to a Lisp object that -represents that screen area in Emacs Lisp. It should be -clear from the context which is meant. - - Emacs groups windows into frames; see @ref{Frames}. A frame -represents an area of screen available for Emacs to use. Each frame -always contains at least one window, but you can subdivide it -vertically or horizontally into multiple, nonoverlapping Emacs -windows. - - In each frame, at any time, one and only one window is designated as -@dfn{selected within the frame}. The frame's cursor appears in that -window, but the other windows have ``non-selected'' cursors, normally -less visible. (@xref{Cursor Parameters}, for customizing this.) At -any time, one frame is the selected frame; and the window selected -within that frame is @dfn{the selected window}. The selected window's -buffer is usually the current buffer (except when @code{set-buffer} has -been used); see @ref{Current Buffer}. - - For practical purposes, a window exists only while it is displayed in -a frame. Once removed from the frame, the window is effectively deleted -and should not be used, @emph{even though there may still be references -to it} from other Lisp objects; see @ref{Deleting Windows}. Restoring a -saved window configuration is the only way for a window no longer on the -screen to come back to life; see @ref{Window Configurations}. - -@cindex multiple windows - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. - - The meaning of ``window'' in Emacs is similar to what it means in the -context of general-purpose window systems such as X, but not identical. -The X Window System places X windows on the screen; Emacs uses one or -more X windows as frames, and subdivides them into -Emacs windows. When you use Emacs on a character-only terminal, Emacs -treats the whole terminal screen as one frame. - -@cindex terminal screen -@cindex screen of terminal -@cindex tiled windows - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are @dfn{tiled}; they never overlap, and -together they fill the whole screen or frame. Because of the way in -which Emacs creates new windows (@pxref{Splitting Windows}) and resizes -them (@pxref{Resizing Windows}), not all conceivable tilings of windows -on an Emacs frame are actually possible. - -@defun windowp object -This function returns @code{t} if @var{object} is a window. -@end defun - -@node Splitting Windows -@section Splitting Windows -@cindex splitting windows -@cindex window splitting - -The functions described below are the primitives used to split a window -into two windows. They do not accept a buffer as an argument. Rather, -the two ``halves'' of the split window initially display the same buffer -previously visible in the window that was split. - -@deffn Command split-window &optional window size horizontal -This function splits a new window out of @var{window}'s screen area. It -returns the new window. The default for @var{window} is the selected -window. When you split the selected window, it remains selected. - -If @var{horizontal} is non-@code{nil}, then @var{window} splits into two -side by side windows. The original window keeps the leftmost @var{size} -columns, and gives the rest of the columns to the new window. -Otherwise, @var{window} splits into windows one above the other, the -original window keeps the upper @var{size} lines and gives the rest of -the lines to the new window. The original window @var{window} is -therefore the left-hand or upper of the two, and the new window is the -right-hand or lower. - -If @var{size} is omitted or @code{nil}, then @var{window} is divided -evenly into two parts. (If there is an odd line, it is allocated to -the new window.) When @code{split-window} is called interactively, -all its arguments are @code{nil}. - -If splitting would result in making a window that is smaller than -@code{window-min-height} or @code{window-min-width} (@pxref{Resizing -Windows}), @code{split-window} signals an error and does not split the -window at all. - -The following example starts with one window on a screen that is 50 -lines high by 80 columns wide; then it splits the window. - -@smallexample -@group -(setq w (selected-window)) - @result{} # -(window-edges) ; @r{Edges in order:} - @result{} (0 0 80 50) ; @r{left--top--right--bottom} -@end group - -@group -;; @r{Returns window created} -(setq w2 (split-window w 15)) - @result{} # -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window;} - ; @r{top is line 15} -@end group -@group -(window-edges w) - @result{} (0 0 80 15) ; @r{Top window} -@end group -@end smallexample - -The screen looks like this: - -@smallexample -@group - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Next, split the top window horizontally: - -@smallexample -@group -(setq w3 (split-window w 35 t)) - @result{} # -@end group -@group -(window-edges w3) - @result{} (35 0 80 15) ; @r{Left edge at column 35} -@end group -@group -(window-edges w) - @result{} (0 0 35 15) ; @r{Right edge at column 35} -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window unchanged} -@end group -@end smallexample - -@need 3000 -Now the screen looks like this: - -@smallexample -@group - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Normally, Emacs indicates the border between two side-by-side windows -with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The -display table can specify alternative border characters; see @ref{Display -Tables}. -@end deffn - -@deffn Command split-window-vertically &optional size -This function splits the selected window into two windows, one above the -other, leaving the upper of the two windows selected, with @var{size} -lines. (If @var{size} is negative, then the lower of the two windows -gets @minus{}@var{size} lines and the upper window gets the rest, but -the upper window is still the one selected.) However, if -@code{split-window-keep-point} (see below) is @code{nil}, then either -window can be selected. - -In other respects, this function is similar to @code{split-window}. -In particular, the upper window is the original one and the return -value is the new, lower window. -@end deffn - -@defopt split-window-keep-point -If this variable is non-@code{nil} (the default), then -@code{split-window-vertically} behaves as described above. - -If it is @code{nil}, then @code{split-window-vertically} adjusts point -in each of the two windows to avoid scrolling. (This is useful on -slow terminals.) It selects whichever window contains the screen line -that point was previously on. - -This variable affects the behavior of @code{split-window-vertically} -only. It has no effect on the other functions described here. -@end defopt - -@deffn Command split-window-horizontally &optional size -This function splits the selected window into two windows -side-by-side, leaving the selected window on the left with @var{size} -columns. If @var{size} is negative, the rightmost window gets -@minus{}@var{size} columns, but the leftmost window still remains -selected. - -This function is basically an interface to @code{split-window}. -You could define a simplified version of the function like this: - -@smallexample -@group -(defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") -@end group -@group - (let ((size (and arg (prefix-numeric-value arg)))) - (and size (< size 0) - (setq size (+ (window-width) size))) - (split-window nil size t))) -@end group -@end smallexample -@end deffn - -@defun one-window-p &optional no-mini all-frames -This function returns non-@code{nil} if there is only one window. The -argument @var{no-mini}, if non-@code{nil}, means don't count the -minibuffer even if it is active; otherwise, the minibuffer window is -counted when it is active. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Count the windows in the selected frame, plus the minibuffer used -by that frame even if it lies in some other frame. - -@item @code{t} -Count all windows in all existing frames. - -@item @code{visible} -Count all windows in all visible frames. - -@item 0 -Count all windows in all visible or iconified frames. - -@item anything else -Count precisely the windows in the selected frame, and no others. -@end table -@end defun - -@node Deleting Windows -@section Deleting Windows -@cindex deleting windows - -A window remains visible on its frame unless you @dfn{delete} it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration -(@pxref{Window Configurations}). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one of -its sibling windows adjacent to it. - -@c Emacs 19 feature -@defun window-live-p window -This function returns @code{nil} if @var{window} is deleted, and -@code{t} otherwise. - -@strong{Warning:} Erroneous information or fatal errors may result from -using a deleted window as if it were live. -@end defun - -@deffn Command delete-window &optional window -This function removes @var{window} from display and returns @code{nil}. -The default for @var{window} is the selected window. An error is -signaled if @var{window} is the only window on its frame. -@end deffn - -@deffn Command delete-other-windows &optional window -This function makes @var{window} the only window on its frame, by -deleting the other windows in that frame. The default for @var{window} -is the selected window. The return value is @code{nil}. -@end deffn - -@deffn Command delete-windows-on &optional buffer-or-name frame -This function deletes all windows showing @var{buffer-or-name}. If -there are no windows showing @var{buffer-or-name}, it does nothing. The -optional argument @var{buffer-or-name} may be a buffer or the name of an -existing buffer and defaults to the current buffer. - -@code{delete-windows-on} operates frame by frame. If a frame has -several windows showing different buffers, then those showing -@var{buffer-or-name} are removed, and the others expand to fill the -space. If all windows in some frame are showing @var{buffer-or-name} -(including the case where there is only one window), then the frame -winds up with a single window showing another buffer chosen with -@code{other-buffer} (@pxref{The Buffer List}). If, however, the window -showing @var{buffer-or-name} is dedicated to its buffer -(@pxref{Dedicated Windows}), and there are other frames left, that -window's frame is deleted. - -The optional argument @var{frame} specifies which frames to operate on. -This function does not use it in quite the same way as the other -functions which scan all windows; specifically, the values @code{t} and -@code{nil} have the opposite of their meanings in other functions. Here -are the full details: - -@itemize @bullet -@item -If it is @code{nil}, operate on all frames. -@item -If it is @code{t}, operate on the selected frame. -@item -If it is @code{visible}, operate on all visible frames. -@item -If it is 0, operate on all visible or iconified frames. -@item -If it is a frame, operate on that frame. -@end itemize - -This function always returns @code{nil}. -@end deffn - -@node Selecting Windows -@section Selecting Windows -@cindex selecting a window - - When a window is selected, the buffer in the window becomes the current -buffer, and the cursor will appear in it. - -@defun selected-window -This function returns the selected window. This is the window in -which the cursor appears and to which many commands apply. -@end defun - -@defun select-window window &optional norecord -This function makes @var{window} the selected window. The cursor then -appears in @var{window} (after redisplay). Unless @var{window} was -already selected, @code{select-window} makes @var{window}'s buffer the -current buffer. The return value is @var{window}. - -Normally, @var{window}'s selected buffer is moved to the front of the -buffer list (@pxref{The Buffer List}) and @var{window} becomes the most -recently selected window. But if @var{norecord} is non-@code{nil}, the -buffer list remains unchanged and @var{window} does not become the most -recently selected one. - - -@example -@group -(setq w (next-window)) -(select-window w) - @result{} # -@end group -@end example -@end defun - -@defmac save-selected-window forms@dots{} -This macro records the selected frame, as well as the selected window -of each frame, executes @var{forms} in sequence, then restores the -earlier selected frame and windows. It also saves and restores the -current buffer. It returns the value of the last form in @var{forms}. - -This macro does not save or restore anything about the sizes, -arrangement or contents of windows; therefore, if @var{forms} change -them, the change persists. If the previously selected window of some -frame is no longer live at the time of exit from @var{forms}, that -frame's selected window is left alone. If the previously selected -window is no longer live, then whatever window is selected at the end of -@var{forms} remains selected. The current buffer is restored if and -only if it is still live when exiting @var{forms}. - -This macro changes neither the ordering of recently selected windows nor -the buffer list. -@end defmac - -@defmac with-selected-window window forms@dots{} -This macro selects @var{window}, executes @var{forms} in sequence, then -restores the previously selected window and current buffer. The ordering -of recently selected windows and the buffer list remain unchanged unless -you deliberately change them within @var{forms}, for example, by calling -@code{select-window} with argument @var{norecord} @code{nil}. -@end defmac - -@cindex finding windows - The following functions choose one of the windows on the screen, -offering various criteria for the choice. - -@defun get-lru-window &optional frame dedicated -This function returns the window least recently ``used'' (that is, -selected) among a set of candidate windows. If any full-width windows -are present, it only considers these. - -The selected window is returned if it is the only candidate. A -minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. - -The optional argument @var{frame} specifies which windows are -considered. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@defun get-largest-window &optional frame dedicated -This function returns the window with the largest area (height times -width). If there are no side-by-side windows, then this is the window -with the most lines. A minibuffer window is never a candidate. A -dedicated window (@pxref{Dedicated Windows}) is never a candidate unless -the optional argument @var{dedicated} is non-@code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window (@pxref{Cyclic Window Ordering}). - -The optional argument @var{frame} specifies which set of windows to -consider, see @code{get-lru-window} above. -@end defun - -@cindex window that satisfies a predicate -@cindex conditional selection of windows -@defun get-window-with-predicate predicate &optional minibuf all-frames default -This function returns a window satisfying @var{predicate}. It cycles -through all visible windows using @code{walk-windows} (@pxref{Cyclic -Window Ordering}), calling @var{predicate} on each one of them with that -window as its argument. The function returns the first window for which -@var{predicate} returns a non-@code{nil} value; if that never happens, -it returns @var{default} (which defaults to @code{nil}). - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the scan. See the description of -@code{next-window} in @ref{Cyclic Window Ordering}, for details. -@end defun - -@node Cyclic Window Ordering -@comment node-name, next, previous, up -@section Cyclic Ordering of Windows -@cindex cyclic ordering of windows -@cindex ordering of windows, cyclic -@cindex window ordering, cyclic - - When you use the command @kbd{C-x o} (@code{other-window}) to select -some other window, it moves through the windows on the screen in a -specific order. For any given configuration of windows, this order -never varies. It is called the @dfn{cyclic ordering of windows}. - - For a particular frame, this ordering generally goes from top to -bottom, and from left to right. But it may go down first or go right -first, depending on the order in which windows were split. - - If the first split was vertical (into windows one above each other), -and then the subwindows were split horizontally, then the ordering is -left to right in the top of the frame, and then left to right in the -next lower part of the frame, and so on. If the first split was -horizontal, the ordering is top to bottom in the left part, and so on. -In general, within each set of siblings at any level in the window tree -(@pxref{Window Tree}), the order is left to right, or top to bottom. - -@deffn next-window &optional window minibuf all-frames -@cindex minibuffer window, and @code{next-window} -This function returns the window following @var{window} in the cyclic -ordering of windows. This is the window @kbd{C-x o} selects if typed -when @var{window} is selected. The default for @var{window} is the -selected window. - -The value of the optional argument @var{minibuf} specifies whether the -minibuffer is included in the window order. Normally, when -@var{minibuf} is @code{nil}, the minibuffer is included only if it is -currently ``active''; this matches the behavior of @kbd{C-x o}. (The -minibuffer window is active while the minibuffer is in use; see -@ref{Minibuffers}.) - -If @var{minibuf} is @code{t}, the cyclic ordering includes the -minibuffer window even if it is not active. If @var{minibuf} is neither -@code{t} nor @code{nil}, the minibuffer window is not included even if -it is active. - -The optional argument @var{all-frames} specifies which frames to -consider. Here are the possible values and their meanings: - -@table @asis -@item @code{nil} -Consider all the windows in @var{window}'s frame, plus the minibuffer -used by that frame even if it lies in some other frame. If the -minibuffer counts (as determined by @var{minibuf}), then all windows on -all frames that share that minibuffer count too. - -@item @code{t} -Consider all windows in all existing frames. - -@item @code{visible} -Consider all windows in all visible frames. (To get useful results, you -must ensure @var{window} is in a visible frame.) - -@item 0 -Consider all windows in all visible or iconified frames. - -@item a frame -Consider all windows on that frame. - -@item anything else -Consider precisely the windows in @var{window}'s frame, and no others. -@end table - -This example assumes there are two windows, both displaying the -buffer @samp{windows.texi}: - -@example -@group -(selected-window) - @result{} # -@end group -@group -(next-window (selected-window)) - @result{} # -@end group -@group -(next-window (next-window (selected-window))) - @result{} # -@end group -@end example -@end deffn - -@deffn previous-window &optional window minibuf all-frames -This function returns the window preceding @var{window} in the cyclic -ordering of windows. The other arguments specify which windows to -include in the cycle, as in @code{next-window}. -@end deffn - -@deffn Command other-window count &optional all-frames -This function selects another window in the cyclic ordering of windows. -@var{count} specifies the number of windows to skip in the ordering, -starting with the selected window, before making the selection. If -@var{count} is a positive number, it skips @var{count} windows forwards. -@var{count} negative means skip @minus{}@var{count} windows backwards. -If @var{count} is zero, it does not skip any window, thus re-selecting -the selected window. In an interactive call, @var{count} is the numeric -prefix argument. - -The optional argument @var{all-frames} has the same meaning as in -@code{next-window}, but the @var{minibuf} argument of @code{next-window} -is always effectively @code{nil}. This function returns @code{nil}. -@end deffn - -@c Emacs 19 feature -@defun walk-windows proc &optional minibuf all-frames -This function cycles through all windows. It calls the function -@code{proc} once for each window, with the window as its sole -argument. - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the walk. See @code{next-window}, above, -for details. -@end defun - -@defun window-list &optional frame minibuf window -This function returns a list of all windows on @var{frame}, starting -with @var{window}. The default for @var{frame} is the selected frame; -the default for @var{window} is the selected window. - -The value of @var{minibuf} specifies if the minibuffer window shall be -included in the result list. If @var{minibuf} is @code{t}, the result -always includes the minibuffer window. If @var{minibuf} is @code{nil} -or omitted, that includes the minibuffer window if it is active. If -@var{minibuf} is neither @code{nil} nor @code{t}, the result never -includes the minibuffer window. -@end defun - -@node Buffers and Windows -@section Buffers and Windows -@cindex examining windows -@cindex windows, controlling precisely -@cindex buffers, controlled in windows - - This section describes low-level functions to examine windows or to -display buffers in windows in a precisely controlled fashion. -@iftex -See the following section for -@end iftex -@ifnottex -@xref{Displaying Buffers}, for -@end ifnottex -related functions that find a window to use and specify a buffer for it. -The functions described there are easier to use, but they employ -heuristics in choosing or creating a window; use the functions described -here when you need complete control. - -@defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name} as its -contents. It returns @code{nil}. The default for @var{window} is the -selected window. The argument @var{buffer-or-name} must specify a -buffer or the name of an existing buffer. - -@code{set-window-buffer} is the fundamental primitive for changing which -buffer is displayed in a window, and all ways of doing that call this -function. - -@example -@group -(set-window-buffer (selected-window) "foo") - @result{} nil -@end group -@end example - -Normally, displaying @var{buffer-or-name} in @var{window} resets the -window's position, display margins, fringe widths, and scroll bar -settings based on the local variables of that buffer. -However, if @var{keep-margins} is non-@code{nil}, display margins and -fringe widths of @var{window} remain unchanged. @xref{Fringes}. - -@code{set-window-buffer} signals an error when @var{window} is -@dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and -does not already display @var{buffer-or-name}. - -Note that this function runs @code{window-scroll-functions} before -running @code{window-configuration-change-hook}. -@end defun - -@defvar buffer-display-count -This buffer-local variable records the number of times a buffer has been -displayed in a window. It is incremented each time -@code{set-window-buffer} is called for the buffer. -@end defvar - -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. The -default for @var{window} is the selected window. - -@example -@group -(window-buffer) - @result{} # -@end group -@end example -@end defun - -@defun get-buffer-window &optional buffer-or-name all-frames -This function returns a window currently displaying -@var{buffer-or-name}, or @code{nil} if there is none. If there are -several such windows, then the function returns the first one in the -cyclic ordering of windows, starting from the selected window. -@xref{Cyclic Window Ordering}. - -The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and -defaults to the current buffer. The optional argument @var{all-frames} -specifies which windows to consider: - -@itemize @bullet -@item -@code{nil} means consider windows on the selected frame. -@item -@code{t} means consider windows on all existing frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@end itemize - -Observe that the behavior of @code{get-buffer-window} may differ from -that of @code{next-window} (@pxref{Cyclic Window Ordering}) when -@var{all-frames} equals @code{nil} or any value not listed here. -Perhaps we will change @code{get-buffer-window} in the future to make it -compatible with the other functions. -@end defun - -@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames -This function returns a list of all windows currently displaying -@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer -or the name of an existing buffer and defaults to the current buffer. - -The two remaining arguments work like the same-named arguments of -@code{next-window}; they are @emph{not} like the optional arguments of -@code{get-buffer-window}. -@end defun - -@defvar buffer-display-time -This variable records the time at which a buffer was last made visible -in a window. It is always local in each buffer; each time -@code{set-window-buffer} is called, it sets this variable to -@code{(current-time)} in the specified buffer (@pxref{Time of Day}). -When a buffer is first created, @code{buffer-display-time} starts out -with the value @code{nil}. -@end defvar - -@node Displaying Buffers -@section Displaying Buffers in Windows -@cindex switching to a buffer -@cindex displaying a buffer - - In this section we describe convenient functions that choose a window -automatically and use it to display a specified buffer. These functions -can also split an existing window in certain circumstances. We also -describe variables that parameterize the heuristics used for choosing a -window. -@iftex -See the preceding section for -@end iftex -@ifnottex -@xref{Buffers and Windows}, for -@end ifnottex -low-level primitives that give you more precise control. All of these -functions work by calling @code{set-window-buffer}. - - Do not use the functions in this section in order to make a buffer -current so that a Lisp program can access or modify it; they are too -drastic for that purpose, since they change the display of buffers in -windows, which would be gratuitous and surprise the user. Instead, use -@code{set-buffer} and @code{save-current-buffer} (@pxref{Current -Buffer}), which designate buffers as current for programmed access -without affecting the display of buffers in windows. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord -This function makes @var{buffer-or-name} the current buffer, and also -displays the buffer in the selected window. This means that a human can -see the buffer and subsequent keyboard commands will apply to it. -Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} -the current buffer but does not display it in the selected window; -see @ref{Current Buffer}. - -If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a -buffer using @code{other-buffer}. If @var{buffer-or-name} is a string -that does not identify an existing buffer, then a new buffer by that -name is created. The major mode for the new buffer is set according to -the variable @code{default-major-mode}; see @ref{Auto Major Mode}. - -When the selected window is the minibuffer window or is strongly -dedicated to its buffer (@pxref{Dedicated Windows}), this function calls -@code{pop-to-buffer} (see below) to display the buffer in some other -window. - -Normally the specified buffer is put at the front of the buffer list -(both the selected frame's buffer list and the frame-independent buffer -list). This affects the operation of @code{other-buffer}. However, if -@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer -List}. - -The @code{switch-to-buffer} function is often used interactively, as -the binding of @kbd{C-x b}. It is also used frequently in programs. It -returns the buffer that it switched to. -@end deffn - -The next two functions are similar to @code{switch-to-buffer}, except -for the described features. - -@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} current -and displays it in a window not currently selected, using the function -@code{pop-to-buffer} (see below). - -The currently selected window is absolutely never used to do the job. -If the selected window already displays @var{buffer-or-name}, then it -continues to do so, but another window is nonetheless found to display -it in as well. - -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end deffn - -@deffn pop-to-buffer buffer-or-name &optional other-window norecord -This command makes @var{buffer-or-name} the current buffer and switches -to it in some window, preferably not the window previously selected. -The ``popped-to'' window becomes the selected window. Its frame is -given the X server's focus, if possible; see @ref{Input Focus}. The -return value is the buffer that was switched to. - -If @var{buffer-or-name} is @code{nil}, that means to choose some other -buffer, but you don't specify which. If @var{buffer-or-name} is a -string that does not name an existing buffer, a buffer by that name is -created. The major mode for the new buffer is set according to the -variable @code{default-major-mode}. @xref{Auto Major Mode}. - -If either of the variables @code{display-buffer-reuse-frames} or -@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a -window in any visible frame already displaying the buffer; if there is -one, it selects and returns that window. If no such window exists and -@code{pop-up-frames} is non-@code{nil}, it creates a new frame and -displays the buffer in it. Otherwise, @code{pop-to-buffer} operates -entirely within the selected frame. (If the selected frame has just a -minibuffer, @code{pop-to-buffer} operates within the most recently -selected frame that was not just a minibuffer.) - -If the variable @code{pop-up-windows} is non-@code{nil}, windows may be -split to create a new window that is different from the original window. -For details, see @ref{Choosing Window}. - -If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or -creates another window even if @var{buffer-or-name} is already visible -in the selected window. Thus @var{buffer-or-name} could end up -displayed in two windows. On the other hand, if @var{buffer-or-name} is -already displayed in the selected window and @var{other-window} is -@code{nil}, then the selected window is considered sufficient for -displaying @var{buffer-or-name}, so that nothing needs to be done. - -All the variables that affect @code{display-buffer} affect -@code{pop-to-buffer} as well. @xref{Choosing Window}. - -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end deffn - -@deffn Command replace-buffer-in-windows &optional buffer-or-name -This function replaces @var{buffer-or-name} in all windows displaying -it with some other buffer. It uses @code{other-buffer} to choose the -other buffer. In the usual applications of this function, you -don't care which other buffer is used; you just want to make sure that -@var{buffer-or-name} is no longer displayed. - -The argument @var{buffer-or-name} may be a buffer or the name of an -existing buffer and defaults to the current buffer. - -If a window displaying @var{buffer-or-name} is dedicated -(@pxref{Dedicated Windows}), and is not the only window on its frame, -that window is deleted. If that window is the only window on its frame -and there are other frames left, the window's frame is deleted too. If -there are no other frames left, some other buffer is displayed in that -window. - -This function returns @code{nil}. -@end deffn - -@node Choosing Window -@section Choosing a Window for Display - - This section describes the basic facility that chooses a window to -display a buffer in---@code{display-buffer}. Higher-level functions and -commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this -subroutine. Here we describe how to use @code{display-buffer} and how -to customize it. - -@deffn Command display-buffer buffer-or-name &optional not-this-window frame -This command makes @var{buffer-or-name} appear in some window, but it -does not select that window and does not make the buffer specified by -@var{buffer-or-name} current. The identity of the selected window is -unaltered by this function. The argument @var{buffer-or-name} must be a -buffer or the name of an existing buffer. - -@var{not-this-window} non-@code{nil} means to display the specified -buffer in a window other than the selected one, even if it is already -displayed in the selected window. This can cause the buffer to appear -in two windows at once. Otherwise, if @var{buffer-or-name} is already -being displayed in any window, that is good enough, so this function -does nothing. - -@code{display-buffer} returns the window chosen to display -@var{buffer-or-name}. - -If the optional argument @var{frame} is non-@code{nil}, it specifies -which frames to check when deciding whether the buffer is already -displayed. If the buffer is already displayed in some window on one of -these frames, @code{display-buffer} simply returns that window. Here -are the possible values of @var{frame}: - -@itemize @bullet -@item -@code{nil} means consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) -@item -@code{t} means consider windows on all frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@end itemize - -Precisely how @code{display-buffer} finds or creates a window depends on -the variables described below. -@end deffn - -@defopt display-buffer-reuse-frames -If this variable is non-@code{nil}, @code{display-buffer} searches -visible and iconified frames for a window displaying -@var{buffer-or-name}. If there is such a window, @code{display-buffer} -makes that window's frame visible and raises it if necessary, and -returns the window. If there is no such window or -@code{display-buffer-reuse-frames} is @code{nil}, the behavior of -@code{display-buffer} is determined by the variables described next. -@end defopt - -@defopt pop-up-windows -This variable specifies whether @code{display-buffer} is allowed to -split (@pxref{Splitting Windows}) an existing window. If this variable -is non-@code{nil}, @code{display-buffer} tries to split the largest or -least recently used window on the selected frame. (If the selected -frame is a minibuffer-only frame, @code{display-buffer} tries to split a -window on another frame instead.) If this variable is @code{nil} or the -variable @code{pop-up-frames} (see below) is non-@code{nil}, -@code{display-buffer} does not split any window. -@end defopt - -@defopt split-window-preferred-function -This variable must specify a function with one argument, which is a -window. The @code{display-buffer} routines will call this function with -one or more candidate windows when they look for a window to split. The -function is expected to split that window and return the new window. If -the function returns @code{nil}, this means that the argument window -cannot (or shall not) be split. - -The default value of @code{split-window-preferred-function} is the -function @code{split-window-sensibly} described below. If you -customize this option, bear in mind that the @code{display-buffer} -routines may call your function up to two times when trying to split a -window. The argument of the first call is the largest window on the -chosen frame (as returned by @code{get-largest-window}). If that call -fails to return a live window, your function is called a second time -with the least recently used window on that frame (as returned by -@code{get-lru-window}). - -The function specified by this option may try to split any other window -instead of the argument window. Note that the window selected at the -time @code{display-buffer} was invoked is still selected when your -function is called. Hence, you can split the selected window (instead -of the largest or least recently used one) by simply ignoring the window -argument in the body of your function. You can even choose to not split -any window as long as the return value of your function specifies a live -window or @code{nil}, but you are not encouraged to do so -unconditionally. If you want @code{display-buffer} to never split any -windows, set @code{pop-up-windows} to @code{nil}. -@end defopt - -@defun split-window-sensibly window -This function takes a window as argument and tries to split that window -in a suitable way. The two variables described next are useful for -tuning the behavior of this function. -@end defun - -@defopt split-height-threshold -This variable specifies whether @code{split-window-sensibly} may split -windows vertically. If it is an integer, @code{split-window-sensibly} -tries to vertically split a window only if it has at least this many -lines. If the window has less lines, splitting fails, or the value of -this variable is @code{nil}, @code{split-window-sensibly} will try to -split the window horizontally, subject to restrictions of -@code{split-width-threshold} (see below). If splitting horizontally -fails too and the window is the only window on its frame, -@code{split-window-sensibly} will try to split the window vertically -disregarding the value of @code{split-height-threshold}. If this fails -as well, @code{split-window-sensibly} returns @code{nil}. - -@code{split-window-sensibly} does not split vertically a window whose -height is fixed (@pxref{Resizing Windows}). Also, it vertically splits -a window only if the space taken up by that window can accommodate two -windows one above the other that are both at least -@code{window-min-height} lines tall. Moreover, if the window that shall -be split has a mode line, @code{split-window-sensibly} does not split -the window unless the new window can accomodate a mode line too. -@end defopt - -@defopt split-width-threshold -This variable specifies whether @code{split-window-sensibly} may split -windows horizontally. If it is an integer, @code{split-window-sensibly} -tries to horizontally split a window only if it has at least this many -columns. If it is @code{nil}, @code{split-window-sensibly} will not -split the window horizontally. (It still might split the window -vertically, though, see above.) - -@code{split-window-sensibly} does not split horizontally a window if -that window's width is fixed (@pxref{Resizing Windows}). Also, it -horizontally splits a window only if the space that window takes up can -accommodate two windows side by side that are both at least -@code{window-min-width} columns wide. -@end defopt - -@defopt even-window-heights -This variable specifies whether @code{display-buffer} should even out -window heights if the buffer gets displayed in an existing window, above -or beneath another window. If @code{even-window-heights} is -non-@code{nil}, the default, window heights will be evened out. If -either of the involved window has fixed height (@pxref{Resizing -Windows}) or @code{even-window-heights} is @code{nil}, the original -window heights will be left alone. -@end defopt - -@c Emacs 19 feature -@defopt pop-up-frames -This variable specifies whether @code{display-buffer} should make new -frames. If it is non-@code{nil}, @code{display-buffer} looks for a -window already displaying @var{buffer-or-name} on any visible or -iconified frame. If it finds such a window, it makes that window's -frame visible and raises it if necessary, and returns the window. -Otherwise it makes a new frame, unless the variable's value is -@code{graphic-only} and the selected frame is not on a graphic display. -@xref{Frames}, for more information. - -Note that the value of @code{pop-up-windows} does not matter if -@code{pop-up-frames} is non-@code{nil}. If @code{pop-up-frames} is -@code{nil}, then @code{display-buffer} either splits a window or reuses -one. -@end defopt - -@c Emacs 19 feature -@defopt pop-up-frame-function -This variable specifies how to make a new frame if @code{pop-up-frames} -is non-@code{nil}. - -The value of this variable must be a function of no arguments. When -@code{display-buffer} makes a new frame, it does so by calling that -function, which should return a frame. The default value of this -variable is a function that creates a frame using the parameters -specified by @code{pop-up-frame-alist} described next. -@end defopt - -@defopt pop-up-frame-alist -This variable holds an alist specifying frame parameters used by the -default value of @code{pop-up-frame-function} for making new frames. -@xref{Frame Parameters}, for more information about frame parameters. -@end defopt - -@defopt special-display-buffer-names -A list of buffer names identifying buffers that should be displayed -specially. If the name of @var{buffer-or-name} is in this list, -@code{display-buffer} handles the buffer specially. By default, special -display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of that -list is the buffer name, and the rest of that list says how to create -the frame. There are two possibilities for the rest of that list (its -@sc{cdr}): It can be an alist, specifying frame parameters, or it can -contain a function and arguments to give to it. (The function's first -argument is always the buffer to be displayed; the arguments from the -list come after that.) - -For example: - -@example -(("myfile" (minibuffer) (menu-bar-lines . 0))) -@end example - -@noindent -specifies to display a buffer named @samp{myfile} in a dedicated frame -with specified @code{minibuffer} and @code{menu-bar-lines} parameters. - -The list of frame parameters can also use the phony frame parameters -@code{same-frame} and @code{same-window}. If the specified frame -parameters include @code{(same-window . @var{value})} and @var{value} -is non-@code{nil}, that means to display the buffer in the current -selected window. Otherwise, if they include @code{(same-frame . -@var{value})} and @var{value} is non-@code{nil}, that means to display -the buffer in a new window in the currently selected frame. -@end defopt - -@defopt special-display-regexps -A list of regular expressions specifying buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. By default, special display means to give the buffer a -dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See @code{special-display-buffer-names} above. -@end defopt - -@defun special-display-p buffer-name -This function returns non-@code{nil} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -create a special frame. The value is @code{t} if it would -use the default frame parameters, or else the specified list -of frame parameters. -@end defun - -@defopt special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. The default value of this variable is -@code{special-display-popup-frame}, see below. -@end defopt - -@defun special-display-popup-frame buffer &optional args -This function tries to make @var{buffer} visible in a frame of its own. -If @var{buffer} is already displayed in some window, it makes that -window's frame visible and raises it. Otherwise, it creates a frame -that is dedicated to @var{buffer}. The return value is the window used -to display @var{buffer}. - -If @var{args} is an alist, it specifies frame parameters for the new -frame. If @var{args} is a list whose @sc{car} is a symbol, then -@code{(car @var{args})} is called as a function to actually create and -set up the frame; it is called with @var{buffer} as first argument, and -@code{(cdr @var{args})} as additional arguments. - -This function always uses an existing window displaying @var{buffer}, -whether or not it is in a frame of its own; but if you set up the above -variables in your init file, before @var{buffer} was created, then -presumably the window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -@anchor{Definition of special-display-frame-alist} -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If the buffer's name is in this list, -@code{display-buffer} handles the buffer by switching to it in the -selected window. -@end defopt - -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by switching to it in the selected window. -@end defopt - -@defun same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. -@end defun - -@c Emacs 19 feature -@defopt display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the first two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer in it, and then return the window. - -This variable takes precedence over all the other options described -above. -@end defopt - -If all options described above fail to produce a suitable window, -@code{display-buffer} tries to reuse an existing window. As a last -resort, it will try to display @var{buffer-or-name} on a separate frame. -In that case, the value of @code{pop-up-frames} is disregarded. - -@node Dedicated Windows -@section Dedicated Windows -@cindex dedicated window - -Functions for displaying a buffer can be told to not use specific -windows by marking these windows as @dfn{dedicated} to their buffers. -@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated -window for displaying another buffer in it. @code{get-lru-window} and -@code{get-largest-window} (@pxref{Selecting Windows}) do not consider -dedicated windows as candidates when their @var{dedicated} argument is -non-@code{nil}. The behavior of @code{set-window-buffer} -(@pxref{Buffers and Windows}) with respect to dedicated windows is -slightly different, see below. - -When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete -a dedicated window and that window is the only window on its frame, it -deletes the window's frame too, provided there are other frames left. -@code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to -delete all dedicated windows showing its buffer argument. When such a -window is the only window on its frame, that frame is deleted, provided -there are other frames left. If there are no more frames left, some -other buffer is displayed in the window, and the window is marked as -non-dedicated. - -When you kill a buffer (@pxref{Killing Buffers}) displayed in a -dedicated window, any such window usually gets deleted too, since -@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning -up windows. Burying a buffer (@pxref{The Buffer List}) deletes the -selected window if it is dedicated to that buffer. If, however, that -window is the only window on its frame, @code{bury-buffer} displays -another buffer in it and iconifies the frame. - -@defun window-dedicated-p &optional window -This function returns non-@code{nil} if @var{window} is dedicated to its -buffer and @code{nil} otherwise. More precisely, the return value is -the value assigned by the last call of @code{set-window-dedicated-p} for -@var{window} or @code{nil} if that function was never called with -@var{window} as its argument. The default for @var{window} is the -selected window. -@end defun - -@defun set-window-dedicated-p window flag -This function marks @var{window} as dedicated to its buffer if -@var{flag} is non-@code{nil}, and non-dedicated otherwise. - -As a special case, if @var{flag} is @code{t}, @var{window} becomes -@dfn{strongly} dedicated to its buffer. @code{set-window-buffer} -signals an error when the window it acts upon is strongly dedicated to -its buffer and does not already display the buffer it is asked to -display. Other functions do not treat @code{t} differently from any -non-@code{nil} value. -@end defun - -@node Window Point -@section Windows and Point -@cindex window position -@cindex window point -@cindex position in window -@cindex point in window - - Each window has its own value of point (@pxref{Point}), independent of -the value of point in other windows displaying the same buffer. This -makes it useful to have multiple windows showing one buffer. - -@itemize @bullet -@item -The window point is established when a window is first created; it is -initialized from the buffer's point, or from the window point of another -window opened on the buffer if such a window exists. - -@item -Selecting a window sets the value of point in its buffer from the -window's value of point. Conversely, deselecting a window sets the -window's value of point from that of the buffer. Thus, when you switch -between windows that display a given buffer, the point value for the -selected window is in effect in the buffer, while the point values for -the other windows are stored in those windows. - -@item -As long as the selected window displays the current buffer, the window's -point and the buffer's point always move together; they remain equal. -@end itemize - -@cindex cursor - As far as the user is concerned, point is where the cursor is, and -when the user switches to another buffer, the cursor jumps to the -position of point in that buffer. - -@defun window-point &optional window -This function returns the current position of point in @var{window}. -For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. The default for -@var{window} is the selected window. - -When @var{window} is the selected window and its buffer is also the -current buffer, the value returned is the same as point in that buffer. -Strictly speaking, it would be more correct to return the ``top-level'' -value of point, outside of any @code{save-excursion} forms. But that -value is hard to find. -@end defun - -@defun set-window-point window position -This function positions point in @var{window} at position -@var{position} in @var{window}'s buffer. It returns @var{position}. - -If @var{window} is selected, and its buffer is current, -this simply does @code{goto-char}. -@end defun - -@defvar window-point-insertion-type -This variable specifies the marker insertion type (@pxref{Marker -Insertion Types}) of @code{window-point}. The default is @code{nil}, -so @code{window-point} will stay behind text inserted there. -@end defvar - -@node Window Start and End -@section The Window Start and End Positions -@cindex window start position - - Each window maintains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the @dfn{display-start} position of the window (or just the -@dfn{start}). The character after this position is the one that appears -at the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - - After switching windows or buffers, and in some other cases, if the -window start is in the middle of a line, Emacs adjusts the window -start to the start of a line. This prevents certain operations from -leaving the window start at a meaningless point within a line. This -feature may interfere with testing some Lisp code by executing it -using the commands of Lisp mode, because they trigger this -readjustment. To test such code, put it into a command and bind the -command to a key. - -@defun window-start &optional window -@cindex window top line -This function returns the display-start position of window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. For example, - -@example -@group -(window-start) - @result{} 7058 -@end group -@end example - -When you create a window, or display a different buffer in it, the -display-start position is set to a display-start position recently used -for the same buffer, or to @code{point-min} if the buffer doesn't have -any. - -Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay)---to make sure point appears -on the screen. Nothing except redisplay automatically changes the -window-start position; if you move point, do not expect the window-start -position to change in response until after the next redisplay. - -For a realistic example of using @code{window-start}, see the -description of @code{count-lines}. @xref{Definition of count-lines}. -@end defun - -@cindex window end position -@defun window-end &optional window update -This function returns the position where display of its buffer ends in -@var{window}. The default for @var{window} is the selected window. - -Simply changing the buffer text or moving point does not update the -value that @code{window-end} returns. The value is updated only when -Emacs redisplays and redisplay completes without being preempted. - -If the last redisplay of @var{window} was preempted, and did not finish, -Emacs does not know the position of the end of display in that window. -In that case, this function returns @code{nil}. - -If @var{update} is non-@code{nil}, @code{window-end} always returns an -up-to-date value for where display ends, based on the current -@code{window-start} value. If a previously saved value of that position -is still valid, @code{window-end} returns that value; otherwise it -computes the correct value by scanning the buffer text. - -Even if @var{update} is non-@code{nil}, @code{window-end} does not -attempt to scroll the display if point has moved off the screen, the -way real redisplay would do. It does not alter the -@code{window-start} value. In effect, it reports where the displayed -text will end if scrolling is not required. -@end defun - -@defun set-window-start window position &optional noforce -This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. It returns @var{position}. - -The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. - -For example, if point @w{is 1} and you set the start of the window -@w{to 37}, the start of the next line, point will be ``above'' the top -of the window. The display routines will automatically move point if -it is still 1 when redisplay occurs. Here is an example: - -@example -@group -;; @r{Here is what @samp{foo} looks like before executing} -;; @r{the @code{set-window-start} expression.} -@end group - -@group ----------- Buffer: foo ---------- -@point{}This is the contents of buffer foo. -2 -3 -4 -5 -6 ----------- Buffer: foo ---------- -@end group - -@group -(set-window-start - (selected-window) - (save-excursion - (goto-char 1) - (forward-line 1) - (point))) -@result{} 37 -@end group - -@group -;; @r{Here is what @samp{foo} looks like after executing} -;; @r{the @code{set-window-start} expression.} ----------- Buffer: foo ---------- -2 -3 -@point{}4 -5 -6 ----------- Buffer: foo ---------- -@end group -@end example - -If @var{noforce} is non-@code{nil}, and @var{position} would place point -off screen at the next redisplay, then redisplay computes a new window-start -position that works well with point, and thus @var{position} is not used. -@end defun - -@defun pos-visible-in-window-p &optional position window partially -This function returns non-@code{nil} if @var{position} is within the -range of text currently visible on the screen in @var{window}. It -returns @code{nil} if @var{position} is scrolled vertically out of view. -Locations that are partially obscured are not considered visible unless -@var{partially} is non-@code{nil}. The argument @var{position} defaults -to the current position of point in @var{window}; @var{window}, to the -selected window. If @var{position} is @code{t}, that means to check the -last visible position in @var{window}. - -The @code{pos-visible-in-window-p} function considers only vertical -scrolling. If @var{position} is out of view only because @var{window} -has been scrolled horizontally, @code{pos-visible-in-window-p} returns -non-@code{nil} anyway. @xref{Horizontal Scrolling}. - -If @var{position} is visible, @code{pos-visible-in-window-p} returns -@code{t} if @var{partially} is @code{nil}; if @var{partially} is -non-@code{nil}, and the character following @var{position} is fully -visible, it returns a list of the form @code{(@var{x} @var{y})}, where -@var{x} and @var{y} are the pixel coordinates relative to the top left -corner of the window; otherwise it returns an extended list of the form -@code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} @var{vpos})}, -where @var{rtop} and @var{rbot} specify the number of off-window pixels -at the top and bottom of the row at @var{position}, @var{rowh} specifies -the visible height of that row, and @var{vpos} specifies the vertical -position (zero-based row number) of that row. - -Here is an example: - -@example -@group -;; @r{If point is off the screen now, recenter it now.} -(or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) -@end group -@end example -@end defun - -@defun window-line-height &optional line window -This function returns the height of text line @var{line} in -@var{window}. If @var{line} is one of @code{header-line} or -@code{mode-line}, @code{window-line-height} returns information about -the corresponding line of the window. Otherwise, @var{line} is a text -line number starting from 0. A negative number counts from the end of -the window. The default for @var{line} is the current line in -@var{window}; the default for @var{window} is the selected window. - -If the display is not up to date, @code{window-line-height} returns -@code{nil}. In that case, @code{pos-visible-in-window-p} may be used -to obtain related information. - -If there is no line corresponding to the specified @var{line}, -@code{window-line-height} returns @code{nil}. Otherwise, it returns -a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, -where @var{height} is the height in pixels of the visible part of the -line, @var{vpos} and @var{ypos} are the vertical position in lines and -pixels of the line relative to the top of the first text line, and -@var{offbot} is the number of off-window pixels at the bottom of the -text line. If there are off-window pixels at the top of the (first) -text line, @var{ypos} is negative. -@end defun - -@node Textual Scrolling -@section Textual Scrolling -@cindex textual scrolling -@cindex scrolling textually - - @dfn{Textual scrolling} means moving the text up or down through a -window. It works by changing the value of the window's display-start -location. It may also change the value of @code{window-point} to keep -point on the screen. - - Textual scrolling was formerly called ``vertical scrolling,'' but we -changed its name to distinguish it from the new vertical fractional -scrolling feature (@pxref{Vertical Scrolling}). - - In the commands @code{scroll-up} and @code{scroll-down}, the directions -``up'' and ``down'' refer to the motion of the text in the buffer at which -you are looking through the window. Imagine that the text is -written on a long roll of paper and that the scrolling commands move the -paper up and down. Thus, if you are looking at text in the middle of a -buffer and repeatedly call @code{scroll-down}, you will eventually see -the beginning of the buffer. - - Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -``down'' commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The textual scrolling functions (aside from -@code{scroll-other-window}) have unpredictable results if the current -buffer is different from the buffer that is displayed in the selected -window. @xref{Current Buffer}. - - If the window contains a row which is taller than the height of the -window (for example in the presence of a large image), the scroll -functions will adjust the window's vertical scroll position to scroll -the partially visible row. To disable this feature, Lisp code may bind -the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical -Scrolling}). - -@deffn Command scroll-up &optional count -This function scrolls the text in the selected window upward -@var{count} lines. If @var{count} is negative, scrolling is actually -downward. - -If @var{count} is @code{nil} (or omitted), then the length of scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-up} returns @code{nil}, unless it gets an error -because it can't scroll any further. -@end deffn - -@deffn Command scroll-down &optional count -This function scrolls the text in the selected window downward -@var{count} lines. If @var{count} is negative, scrolling is actually -upward. - -If @var{count} is omitted or @code{nil}, then the length of the scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-down} returns @code{nil}, unless it gets an error because -it can't scroll any further. -@end deffn - -@deffn Command scroll-other-window &optional count -This function scrolls the text in another window upward @var{count} -lines. Negative values of @var{count}, or @code{nil}, are handled -as in @code{scroll-up}. - -You can specify which buffer to scroll by setting the variable -@code{other-window-scroll-buffer} to a buffer. If that buffer isn't -already displayed, @code{scroll-other-window} displays it in some -window. - -When the selected window is the minibuffer, the next window is normally -the one at the top left corner. You can specify a different window to -scroll, when the minibuffer is selected, by setting the variable -@code{minibuffer-scroll-window}. This variable has no effect when any -other window is selected. When it is non-@code{nil} and the -minibuffer is selected, it takes precedence over -@code{other-window-scroll-buffer}. @xref{Definition of -minibuffer-scroll-window}. - -When the minibuffer is active, it is the next window if the selected -window is the one at the bottom right corner. In this case, -@code{scroll-other-window} attempts to scroll the minibuffer. If the -minibuffer contains just one line, it has nowhere to scroll to, so the -line reappears after the echo area momentarily displays the message -@samp{Beginning of buffer}. -@end deffn - -@c Emacs 19 feature -@defvar other-window-scroll-buffer -If this variable is non-@code{nil}, it tells @code{scroll-other-window} -which buffer's window to scroll. -@end defvar - -@defopt scroll-margin -This option specifies the size of the scroll margin---a minimum number -of lines between point and the top or bottom of a window. Whenever -point gets within this many lines of the top or bottom of the window, -redisplay scrolls the text automatically (if possible) to move point -out of the margin, closer to the center of the window. -@end defopt - -@defopt scroll-conservatively -This variable controls how scrolling is done automatically when point -moves off the screen (or into the scroll margin). If the value is a -positive integer @var{n}, then redisplay scrolls the text up to -@var{n} lines in either direction, if that will bring point back into -proper view. This behavior is called @dfn{conservative scrolling}. -Otherwise, scrolling happens in the usual way, under the control of -other variables such as @code{scroll-up-aggressively} and -@code{scroll-down-aggressively}. - -The default value is zero, which means that conservative scrolling -never happens. -@end defopt - -@defopt scroll-down-aggressively -The value of this variable should be either @code{nil} or a fraction -@var{f} between 0 and 1. If it is a fraction, that specifies where on -the screen to put point when scrolling down. More precisely, when a -window scrolls down because point is above the window start, the new -start position is chosen to put point @var{f} part of the window -height from the top. The larger @var{f}, the more aggressive the -scrolling. - -A value of @code{nil} is equivalent to .5, since its effect is to center -point. This variable automatically becomes buffer-local when set in any -fashion. -@end defopt - -@defopt scroll-up-aggressively -Likewise, for scrolling up. The value, @var{f}, specifies how far -point should be placed from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value scrolls more aggressively. -@end defopt - -@defopt scroll-step -This variable is an older variant of @code{scroll-conservatively}. The -difference is that it if its value is @var{n}, that permits scrolling -only by precisely @var{n} lines, not a smaller number. This feature -does not work with @code{scroll-margin}. The default value is zero. -@end defopt - -@defopt scroll-preserve-screen-position -If this option is @code{t}, scrolling which would move the current -point position out of the window chooses the new position of point -so that the vertical position of the cursor is unchanged, if possible. - -If it is non-@code{nil} and not @code{t}, then the scrolling functions -always preserve the vertical position of point, if possible. -@end defopt - -@defopt next-screen-context-lines -The value of this variable is the number of lines of continuity to -retain when scrolling by full screens. For example, @code{scroll-up} -with an argument of @code{nil} scrolls so that this many lines at the -bottom of the window appear instead at the top. The default value is -@code{2}. -@end defopt - -@deffn Command recenter &optional count -@cindex centering point -This function scrolls the text in the selected window so that point is -displayed at a specified vertical position within the window. It does -not ``move point'' with respect to the text. - -If @var{count} is a nonnegative number, that puts the line containing -point @var{count} lines down from the top of the window. If -@var{count} is a negative number, then it counts upward from the -bottom of the window, so that @minus{}1 stands for the last usable -line in the window. If @var{count} is a non-@code{nil} list, then it -stands for the line in the middle of the window. - -If @var{count} is @code{nil}, @code{recenter} puts the line containing -point in the middle of the window, then clears and redisplays the entire -selected frame. - -When @code{recenter} is called interactively, @var{count} is the raw -prefix argument. Thus, typing @kbd{C-u} as the prefix sets the -@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets -@var{count} to 4, which positions the current line four lines from the -top. - -With an argument of zero, @code{recenter} positions the current line at -the top of the window. This action is so handy that some people make a -separate key binding to do this. For example, - -@example -@group -(defun line-to-top-of-window () - "Scroll current line to top of window. -Replaces three keystroke sequence C-u 0 C-l." - (interactive) - (recenter 0)) - -(global-set-key [kp-multiply] 'line-to-top-of-window) -@end group -@end example -@end deffn - -@node Vertical Scrolling -@section Vertical Fractional Scrolling -@cindex vertical fractional scrolling -@cindex vertical scroll position - - @dfn{Vertical fractional scrolling} means shifting text in a window -up or down by a specified multiple or fraction of a line. Each window -has a @dfn{vertical scroll position}, which is a number, never less than -zero. It specifies how far to raise the contents of the window. -Raising the window contents generally makes all or part of some lines -disappear off the top, and all or part of some other lines appear at the -bottom. The usual value is zero. - - The vertical scroll position is measured in units of the normal line -height, which is the height of the default font. Thus, if the value is -.5, that means the window contents are scrolled up half the normal line -height. If it is 3.3, that means the window contents are scrolled up -somewhat over three times the normal line height. - - What fraction of a line the vertical scrolling covers, or how many -lines, depends on what the lines contain. A value of .5 could scroll a -line whose height is very short off the screen, while a value of 3.3 -could scroll just part of the way through a tall line or an image. - -@defun window-vscroll &optional window pixels-p -This function returns the current vertical scroll position of -@var{window}. The default for @var{window} is the selected window. -If @var{pixels-p} is non-@code{nil}, the return value is measured in -pixels, rather than in units of the normal line height. - -@example -@group -(window-vscroll) - @result{} 0 -@end group -@end example -@end defun - -@defun set-window-vscroll window lines &optional pixels-p -This function sets @var{window}'s vertical scroll position to -@var{lines}. If @var{window} is @code{nil}, the selected window is -used. The argument @var{lines} should be zero or positive; if not, it -is taken as zero. - - -The actual vertical scroll position must always correspond -to an integral number of pixels, so the value you specify -is rounded accordingly. - -The return value is the result of this rounding. - -@example -@group -(set-window-vscroll (selected-window) 1.2) - @result{} 1.13 -@end group -@end example - -If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of -pixels. In this case, the return value is @var{lines}. -@end defun - -@defvar auto-window-vscroll -If this variable is non-@code{nil}, the line-move, scroll-up, and -scroll-down functions will automatically modify the vertical scroll -position to scroll through display rows that are taller than the height -of the window, for example in the presence of large images. -@end defvar - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting the image in the window left -or right by a specified multiple of the normal character width. Each -window has a @dfn{horizontal scroll position}, which is a number, never -less than zero. It specifies how far to shift the contents left. -Shifting the window contents left generally makes all or part of some -characters disappear off the left, and all or part of some other -characters appear at the right. The usual value is zero. - - The horizontal scroll position is measured in units of the normal -character width, which is the width of space in the default font. Thus, -if the value is 5, that means the window contents are scrolled left by 5 -times the normal character width. How many characters actually -disappear off to the left depends on their width, and could vary from -line to line. - - Because we read from side to side in the ``inner loop,'' and from top -to bottom in the ``outer loop,'' the effect of horizontal scrolling is -not like that of textual or vertical scrolling. Textual scrolling -involves selection of a portion of text to display, and vertical -scrolling moves the window contents contiguously; but horizontal -scrolling causes part of @emph{each line} to go off screen. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the edge -to be revealed by it; so this is not allowed. Scrolling to the left is -allowed; it scrolls the first columns of text off the edge of the window -and can reveal additional columns on the right that were truncated -before. Once a window has a nonzero amount of leftward horizontal -scrolling, you can scroll it back to the right, but only so far as to -reduce the net horizontal scroll to zero. There is no limit to how far -left you can scroll, but eventually all the text will disappear off the -left edge. - -@vindex auto-hscroll-mode - If @code{auto-hscroll-mode} is set, redisplay automatically alters -the horizontal scrolling of a window as necessary to ensure that point -is always visible. However, you can still set the horizontal -scrolling value explicitly. The value you specify serves as a lower -bound for automatic scrolling, i.e. automatic scrolling will not -scroll a window to a column less than the specified one. - -@deffn Command scroll-left &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The default -for @var{count} is the window width, minus 2. - -The return value is the total amount of leftward horizontal scrolling in -effect after the change---just like the value returned by -@code{window-hscroll} (below). - -Once you scroll a window as far right as it can go, back to its normal -position where the total leftward scrolling is zero, attempts to scroll -any farther right have no effect. - -If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes -the lower bound for automatic scrolling; that is, automatic scrolling -will not scroll a window to a column less than the value returned by -this function. Interactive calls pass non-@code{nil} for -@var{set-minimum}. -@end deffn - -@deffn Command scroll-right &optional count set-minimum -This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The default -for @var{count} is the window width, minus 2. Aside from the direction -of scrolling, this works just like @code{scroll-left}. -@end deffn - -@defun window-hscroll &optional window -This function returns the total leftward horizontal scrolling of -@var{window}---the number of columns by which the text in @var{window} -is scrolled left past the left margin. The default for -@var{window} is the selected window. - -The return value is never negative. It is zero when no horizontal -scrolling has been done in @var{window} (which is usually the case). - - -@example -@group -(window-hscroll) - @result{} 0 -@end group -@group -(scroll-left 5) - @result{} 5 -@end group -@group -(window-hscroll) - @result{} 5 -@end group -@end example -@end defun - -@defun set-window-hscroll window columns -This function sets horizontal scrolling of @var{window}. The value of -@var{columns} specifies the amount of scrolling, in terms of columns -from the left margin. The argument @var{columns} should be zero or -positive; if not, it is taken as zero. Fractional values of -@var{columns} are not supported at present. - -Note that @code{set-window-hscroll} may appear not to work if you test -it by evaluating a call with @kbd{M-:} in a simple way. What happens -is that the function sets the horizontal scroll value and returns, but -then redisplay adjusts the horizontal scrolling to make point visible, -and this overrides what the function did. You can observe the -function's effect if you call it while point is sufficiently far from -the left margin that it will remain visible. - -The value returned is @var{columns}. - -@example -@group -(set-window-hscroll (selected-window) 10) - @result{} 10 -@end group -@end example -@end defun - - Here is how you can determine whether a given position @var{position} -is off the screen due to horizontal scrolling: - -@example -@group -(defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) -@end group -@end example - -@node Size of Window -@section The Size of a Window -@cindex window size -@cindex size of window - - An Emacs window is rectangular, and its size information consists of -the height (the number of lines) and the width (the number of character -positions in each line). The mode line is included in the height. But -the width does not count the scroll bar or the column of @samp{|} -characters that separates side-by-side windows. - - The following three functions return size information about a window: - -@defun window-height &optional window -This function returns the number of lines in @var{window}, including its -mode line and header line, if any. If @var{window} fills its entire -frame except for the echo area, this is typically one less than the -value of @code{frame-height} on that frame. The default for -@var{window} is the selected window. - -@example -@group -(window-height) - @result{} 23 -@end group -@group -(split-window-vertically) - @result{} # -@end group -@group -(window-height) - @result{} 11 -@end group -@end example -@end defun - -@defun window-body-height &optional window -Like @code{window-height} but the value does not include the -mode line (if any) or the header line (if any). -@end defun - -@defun window-width &optional window -This function returns the number of columns in @var{window}. The -default for @var{window} is the selected window. - -The return value does not include the window's scroll bar or the column -of @samp{|} characters that separates side-by-side windows. Moreover, -the return value does not include the space used for displaying fringes -and margins. Hence you cannot, in general, compare the return values of -@code{window-width} and @code{frame-width} for equality to determine -whether a window is a wide as the containing frame. Use the function -@code{window-full-width-p}, see below, instead. - -@example -@group -(window-width) - @result{} 80 -@end group -@end example -@end defun - -@defun window-full-width-p &optional window -This function returns non-@code{nil} if @var{window} is as wide as the -frame that contains it; otherwise @code{nil}. The default for -@var{window} is the selected window. -@end defun - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -The default for @var{window} is the selected window. - -The order of the list is @code{(@var{left} @var{top} @var{right} -@var{bottom})}, all elements relative to 0, 0 at the top left corner of -the frame. The element @var{right} of the value is one more than the -rightmost column used by @var{window}, and @var{bottom} is one more than -the bottommost row used by @var{window} and its mode-line. - -The edges include the space used by the window's scroll bar, display -margins, fringes, header line, and mode line, if it has them. Also, -if the window has a neighbor on the right, its right edge value -includes the width of the separator line between the window and that -neighbor. Since the width of the window does not include this -separator, the width does not usually equal the difference between the -right and left edges. -@end defun - -@defun window-inside-edges &optional window -This is similar to @code{window-edges}, but the edge values -it returns include only the text area of the window. They -do not include the header line, mode line, scroll bar or -vertical separator, fringes, or display margins. -@end defun - -Here are the results obtained on a typical 24-line terminal with just -one window, with menu bar enabled: - -@example -@group -(window-edges (selected-window)) - @result{} (0 1 80 23) -@end group -@group -(window-inside-edges (selected-window)) - @result{} (0 1 80 22) -@end group -@end example - -@noindent -The bottom edge is at line 23 because the last line is the echo area. -The bottom inside edge is at line 22, which is the window's mode line. - -If @var{window} is at the upper left corner of its frame, and there is -no menu bar, then @var{bottom} returned by @code{window-edges} is the -same as the value of @code{(window-height)}, @var{right} is almost the -same as the value of @code{(window-width)}, and @var{top} and -@var{left} are zero. For example, the edges of the following window -are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 -columns, the last column of the window (column 7) holds a border -rather than text. The last row (row 4) holds the mode line, shown -here with @samp{xxxxxxxxx}. - -@example -@group - 0 - _______ - 0 | | - | | - | | - | | - xxxxxxxxx 4 - - 7 -@end group -@end example - -In the following example, let's suppose that the frame is 7 -columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} -and the edges of the right window are @w{@samp{4 0 7 3}}. -The inside edges of the left window are @w{@samp{0 0 3 2}}, -and the inside edges of the right window are @w{@samp{4 0 7 2}}, - -@example -@group - ___ ___ - | | | - | | | - xxxxxxxxx - - 0 34 7 -@end group -@end example - -@defun window-pixel-edges &optional window -This function is like @code{window-edges} except that, on a graphical -display, the edge values are measured in pixels instead of in -character lines and columns. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-inside-edges} except that, on a -graphical display, the edge values are measured in pixels instead of -in character lines and columns. -@end defun - -@node Resizing Windows -@section Changing the Size of a Window -@cindex window resizing -@cindex resize window -@cindex changing window size -@cindex window size, changing - - The window size functions fall into two classes: high-level commands -that change the size of windows and low-level functions that access -window size. Emacs does not permit overlapping windows or gaps between -windows, so resizing a window always affects at least one other window. - -@deffn Command enlarge-window size &optional horizontal -This function makes the selected window @var{size} lines taller by -stealing lines from windows above or below. In a first round, it takes -lines from one window at a time until that window is -@code{window-min-height} lines tall, then takes from another. If, at -the end of the first round, the selected window is still not tall -enough, @code{enlarge-window} starts a second round, where it deletes -windows above or below the selected one. - -If @var{horizontal} is non-@code{nil}, this function makes the window -@var{size} columns wider, stealing columns instead of lines. If a -window from which columns are stolen shrinks below -@code{window-min-width} columns, that window disappears. - -If the requested size would exceed that of the window's frame, then the -function makes the window occupy the entire height (or width) of the -frame. - -If there are various other windows from which lines or columns can be -stolen, and some of them specify fixed size (using -@code{window-size-fixed}, see below), they are left untouched while -other windows are ``robbed.'' If it would be necessary to alter the -size of a fixed-size window, @code{enlarge-window} gets an error -instead. - -If @var{size} is negative, this function shrinks the selected window by -@minus{}@var{size} lines or columns. If that makes the window smaller -than the minimum size (@code{window-min-height} and -@code{window-min-width}), then @code{enlarge-window} deletes the window. - -@code{enlarge-window} returns @code{nil}. -@end deffn - -@deffn Command enlarge-window-horizontally columns -This function makes the selected window @var{columns} wider. -It could be defined as follows: - -@example -@group -(defun enlarge-window-horizontally (columns) - (interactive "p") - (enlarge-window columns t)) -@end group -@end example -@end deffn - -@deffn Command shrink-window size &optional horizontal -This function is like @code{enlarge-window} but negates the argument -@var{size}, making the selected window smaller by giving lines (or -columns) to the other windows. If the window shrinks below -@code{window-min-height} or @code{window-min-width}, then it disappears. - -If @var{size} is negative, the window is enlarged by @minus{}@var{size} -lines or columns. -@end deffn - -@deffn Command shrink-window-horizontally columns -This function makes the selected window @var{columns} narrower. -It could be defined as follows: - -@example -@group -(defun shrink-window-horizontally (columns) - (interactive "p") - (shrink-window columns t)) -@end group -@end example -@end deffn - -@defun adjust-window-trailing-edge window delta horizontal -This function makes the selected window @var{delta} lines taller or -@var{delta} columns wider, by moving the bottom or right edge. This -function does not delete other windows; if it cannot make the -requested size adjustment, it signals an error. On success, this -function returns @code{nil}. -@end defun - -@deffn Command fit-window-to-buffer &optional window max-height min-height -This command makes @var{window} the right height to display its -contents exactly. The default for @var{window} is the selected window. - -The optional argument @var{max-height} specifies the maximum height the -window is allowed to be; @code{nil} means use the maximum permissible -height of a window on @var{window}'s frame. The optional argument -@var{min-height} specifies the minimum height for the window; @code{nil} -means use @code{window-min-height}. All these height values include the -mode line and/or header line. - -This function can delete windows when their height shrinks below -@var{min-height}. It returns non-@code{nil} if it orderly resized -@var{window}, and @code{nil} otherwise. -@end deffn - -@deffn Command shrink-window-if-larger-than-buffer &optional window -This command shrinks @var{window} vertically to be as small as possible -while still showing the full contents of its buffer---but not less than -@code{window-min-height} lines. The default for @var{window} is -the selected window. - -However, this command does nothing if the window is already too small to -display the whole text of the buffer, or if part of the contents are -currently scrolled off screen, or if the window is not the full width of -its frame, or if the window is the only window in its frame. - -This command returns non-@code{nil} if it actually shrank the window -and @code{nil} otherwise. -@end deffn - -@cindex fixed-size window -@defvar window-size-fixed -If this variable is non-@code{nil}, in a given buffer, then the size of -any window displaying that buffer remains fixed unless you either -explicitly change it or Emacs has no other choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -This variable automatically becomes buffer-local when set. - -Explicit size-change functions such as @code{enlarge-window} -get an error if they would have to change a window size which is fixed. -Therefore, when you want to change the size of such a window, -you should bind @code{window-size-fixed} to @code{nil}, like this: - -@example -(let ((window-size-fixed nil)) - (enlarge-window 10)) -@end example - -Deleting an adjacent window or changing the frame size may change the -size of a fixed-size window, if there is no other alternative. -@end defvar - -@cindex minimum window size - The following two variables constrain the window-structure-changing -functions to a minimum height and width. - -@defopt window-min-height -The value of this variable specifies how short a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-height} automatically deletes it, and no window may be -created shorter than this. The value is measured in line units. When -the window wants a mode line and/or a header line, they are counted as -one line each. The default value is @code{4}. A value less than -@code{1} is ignored. -@end defopt - -@defopt window-min-width -The value of this variable specifies how narrow a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-width} automatically deletes it, and no window may be -created narrower than this. The value is measured in characters and -includes any fringes or the scroll bar. The default value is @code{10}. -A value less than @code{2} is ignored. -@end defopt - -@cindex balancing window sizes -Emacs provides two functions to balance windows, that is, to even out -the sizes of windows on the same frame. The minibuffer window and -fixed-size windows are not resized by these functions. - -@deffn Command balance-windows &optional window-or-frame -This function balances windows in a way that gives more space to -full-width and/or full-height windows. If @var{window-or-frame} -specifies a frame, it balances all windows on that frame. If -@var{window-or-frame} specifies a window, it balances this window and -its ``siblings'' only. Think of a sibling as the other (original or -new) window with respect to the present one, involved in the process of -splitting; see @ref{Splitting Windows}. Since a sibling may have been -split again, a window can have more than one sibling. -@end deffn - -@deffn Command balance-windows-area -This function attempts to give all windows on the selected frame -approximately the same share of the screen area. This means that -full-width or full-height windows are not given more space than other -windows. -@end deffn - -@node Coordinates and Windows -@section Coordinates and Windows - -This section describes how to relate screen coordinates to windows. - -@defun window-at x y &optional frame -This function returns the window containing the specified cursor -position in the frame @var{frame}. The coordinates @var{x} and @var{y} -are measured in characters and count from the top left corner of the -frame. If they are out of range, @code{window-at} returns @code{nil}. - -If you omit @var{frame}, the selected frame is used. -@end defun - -@defun coordinates-in-window-p coordinates window -This function checks whether a particular frame position falls within -the window @var{window}. - -The argument @var{coordinates} is a cons cell of the form @code{(@var{x} -. @var{y})}. The coordinates @var{x} and @var{y} are measured in -characters, and count from the top left corner of the screen or frame. - -The value returned by @code{coordinates-in-window-p} is non-@code{nil} -if the coordinates are inside @var{window}. The value also indicates -what part of the window the position is in, as follows: - -@table @code -@item (@var{relx} . @var{rely}) -The coordinates are inside @var{window}. The numbers @var{relx} and -@var{rely} are the equivalent window-relative coordinates for the -specified position, counting from 0 at the top left corner of the -window. - -@item mode-line -The coordinates are in the mode line of @var{window}. - -@item header-line -The coordinates are in the header line of @var{window}. - -@item vertical-line -The coordinates are in the vertical line between @var{window} and its -neighbor to the right. This value occurs only if the window doesn't -have a scroll bar; positions in a scroll bar are considered outside the -window for these purposes. - -@item left-fringe -@itemx right-fringe -The coordinates are in the left or right fringe of the window. - -@item left-margin -@itemx right-margin -The coordinates are in the left or right margin of the window. - -@item nil -The coordinates are not in any part of @var{window}. -@end table - -The function @code{coordinates-in-window-p} does not require a frame as -argument because it always uses the frame that @var{window} is on. -@end defun - -@node Window Tree -@section The Window Tree -@cindex window tree - - A @dfn{window tree} specifies the layout, size, and relationship -between all windows in one frame. - -@defun window-tree &optional frame -This function returns the window tree for frame @var{frame}. -If @var{frame} is omitted, the selected frame is used. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's -root window, and @var{mini} is the frame's minibuffer window. - -If the root window is not split, @var{root} is the root window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, -and @code{t} for a vertical split, @var{edges} gives the combined size and -position of the subwindows in the split, and the rest of the elements -are the subwindows in the split. Each of the subwindows may again be -a window or a list representing a window split, and so on. The -@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} -similar to the value returned by @code{window-edges}. -@end defun - -@node Window Configurations -@section Window Configurations -@cindex window configurations -@cindex saving window information - - A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their values of point and the mark; also their -fringes, margins, and scroll bar settings. It also includes the value -of @code{minibuffer-scroll-window}. As a special exception, the window -configuration does not record the value of point in the selected window -for the current buffer. Also, the window configuration does not record -the values of window parameters; see @ref{Window Parameters}. - - You can bring back an entire frame layout by restoring a previously -saved window configuration. If you want to record the layout of all -frames instead of just one, use a frame configuration instead of a -window configuration; see @ref{Frame Configurations}. - -@defun current-window-configuration &optional frame -This function returns a new object representing @var{frame}'s current -window configuration. The default for @var{frame} is the selected -frame. -@end defun - -@defun set-window-configuration configuration -This function restores the configuration of windows and buffers as -specified by @var{configuration}, for the frame that @var{configuration} -was created for. - -The argument @var{configuration} must be a value that was previously -returned by @code{current-window-configuration}. The configuration is -restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. - -If the frame which @var{configuration} was saved from is dead, all this -function does is restore the three variables @code{window-min-height}, -@code{window-min-width} and @code{minibuffer-scroll-window}. In this -case, the function returns @code{nil}. Otherwise, it returns @code{t}. - -Here is a way of using this function to get the same effect -as @code{save-window-excursion}: - -@example -@group -(let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-vertically nil) - @dots{}) - (set-window-configuration config))) -@end group -@end example -@end defun - -@defspec save-window-excursion forms@dots{} -This special form records the window configuration, executes @var{forms} -in sequence, then restores the earlier window configuration. The window -configuration includes, for each window, the value of point and the -portion of the buffer that is visible. It also includes the choice of -selected window. However, it does not include the value of point in -the current buffer; use @code{save-excursion} also, if you wish to -preserve that. - -Don't use this construct when @code{save-selected-window} is sufficient. - -Exit from @code{save-window-excursion} always triggers execution of -@code{window-size-change-functions}. (It doesn't know how to tell -whether the restored configuration actually differs from the one in -effect at the end of the @var{forms}.) - -The return value is the value of the final form in @var{forms}. -For example: - -@example -@group -(split-window) - @result{} # -@end group -@group -(setq w (selected-window)) - @result{} # -@end group -@group -(save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - @result{} do-something - ;; @r{The screen is now split again.} -@end group -@end example -@end defspec - -@defun window-configuration-p object -This function returns @code{t} if @var{object} is a window configuration. -@end defun - -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and mark and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point or mark. -@end defun - -@defun window-configuration-frame config -This function returns the frame for which the window configuration -@var{config} was made. -@end defun - - Other primitives to look inside of window configurations would make -sense, but are not implemented because we did not need them. See the -file @file{winner.el} for some more operations on windows -configurations. - -@node Window Parameters -@section Window Parameters -@cindex window parameters - -This sections describes how window parameters can be used to associate -additional information with windows. - -@defun window-parameter window parameter -This function returns @var{window}'s value for @var{parameter}. The -default for @var{window} is the selected window. If @var{window} -has no setting for @var{parameter}, this function returns @code{nil}. -@end defun - -@defun window-parameters &optional window -This function returns all parameters of @var{window} and their values. -The default for @var{window} is the selected window. The return value -is an association list of elements of the form @code{(@var{parameter} -. @var{value})}. -@end defun - -@defun set-window-parameter window parameter value -This function sets @var{window}'s value of @var{parameter} to -@var{value} and returns @var{value}. The default for @var{window} -is the selected window. -@end defun - -Currently, window parameters are not saved in window configurations and -consequently not restored by @code{set-window-configuration}. Hence, -any change of a parameter introduced via @code{set-window-parameter} can -be undone only by invoking @code{set-window-parameter} for the same -parameter again. Since @code{save-window-excursion} relies on window -configurations (@pxref{Window Configurations}), window parameters are -not saved and restored by that special form, either. - -@node Window Hooks -@section Hooks for Window Scrolling and Changes -@cindex hooks for window operations - -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. - -@defvar window-scroll-functions -This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. Displaying a different buffer in -the window also runs these functions. - -This variable is not a normal hook, because each function is called with -two arguments: the window, and its new display-start position. - -These functions must be careful in using @code{window-end} -(@pxref{Window Start and End}); if you need an up-to-date value, you -must use the @var{update} argument to ensure you get it. - -@strong{Warning:} don't use this feature to alter the way the window -is scrolled. It's not designed for that, and such use probably won't -work. -@end defvar - -@defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called just once per -redisplay, and just once for each frame on which size changes have -occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. - -It is not a good idea to use @code{save-window-excursion} (@pxref{Window -Configurations}) in these functions, because that always counts as a -size change, and it would cause these functions to be called over and -over. In most cases, @code{save-selected-window} (@pxref{Selecting -Windows}) is what you need here. -@end defvar - -@defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. - -The buffer-local part of this hook is run once per each window on the -affected frame, with the relevant window selected and its buffer -current. The global part is run once for the modified frame, with that -frame selected. -@end defvar - - In addition, you can use @code{jit-lock-register} to register a Font -Lock fontification function, which will be called whenever parts of a -buffer are (re)fontified because a window was scrolled or its size -changed. @xref{Other Font Lock Variables}. - -@ignore - arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 -@end ignore diff --git a/doc/misc/.cvsignore b/doc/misc/.cvsignore deleted file mode 100644 index 3ff56b474dd..00000000000 --- a/doc/misc/.cvsignore +++ /dev/null @@ -1,23 +0,0 @@ -*.aux -*.cp -*.cps -*.dvi -*.fn -*.fns -*.ky -*.kys -*.log -*.op -*.ops -*.pdf -*.pg -*.pgs -*.ps -*.tmp -*.toc -*.tp -*.tps -*.vr -*.vrs -Makefile -makefile diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi deleted file mode 100644 index 8a2f10239e4..00000000000 --- a/doc/misc/ada-mode.texi +++ /dev/null @@ -1,1530 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/ada-mode -@settitle Ada Mode - -@copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Ada mode: (ada-mode). Emacs mode for editing and compiling Ada code. -@end direntry - -@titlepage -@sp 10 -@title{Ada Mode} -@sp 2 -@subtitle An Emacs major mode for programming in Ada -@subtitle Ada Mode Version 4.00 -@sp 2 -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Overview, (dir), (dir) - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Installation:: Installing Ada mode on your system -* Customization:: Setting up Ada mode to your taste -* Compiling Executing:: Working with your application within Emacs -* Project files:: Describing the organization of your project -* Compiling Examples:: A small tutorial -* Moving Through Ada Code:: Moving easily through Ada sources -* Identifier completion:: Finishing words automatically -* Automatic Smart Indentation:: Indenting your code automatically as you type -* Formatting Parameter Lists:: Formatting subprograms' parameter lists - automatically -* Automatic Casing:: Adjusting the case of words automatically -* Statement Templates:: Inserting code templates -* Comment Handling:: Reformatting comments easily -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - - -@node Overview, Installation, Top, Top -@chapter Overview - -The Emacs mode for programming in Ada helps the user in understanding -existing code and facilitates writing new code. - -When the Gnu Ada compiler GNAT is used, the cross-reference -information output by the compiler is used to provide powerful code -navigation (jump to definition, find all uses, etc). - -When you open a file with a file extension of @file{.ads} or -@file{.adb}, Emacs will automatically load and activate Ada mode. - -Ada mode works without any customization, if you are using the GNAT -compiler (@url{https://libre2.adacore.com/}) and the GNAT default -naming convention. - -You must customize a few things if you are using a different compiler -or file naming convention; @xref{Other compiler}, @xref{Non-standard -file names}. - -In addition, you may want to customize the indentation, -capitalization, and other things; @xref{Other customization}. - -Finally, for large Ada projects, you will want to set up an Emacs -Ada mode project file for each project; @xref{Project files}. Note -that these are different from the GNAT project files used by gnatmake -and other GNAT commands. - -See the Emacs info manual, section 'Running Debuggers Under Emacs', -for general information on debugging. - -@node Installation, Customization, Overview, Top -@chapter Installation - -Ada mode is part of the standard Emacs distribution; if you use that, -no files need to be installed. - -Ada mode is also available as a separate distribution, from the Emacs -Ada mode website -@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The -separate distribution may be more recent. - -For installing the separate distribution, see the @file{README} file -in the distribution. - -To see what version of Ada mode you have installed, do @kbd{M-x -ada-mode-version}. - -The following files are provided with the Ada mode distribution: - -@itemize @bullet - -@item -@file{ada-mode.el}: The main file for Ada mode, providing indentation, -formatting of parameter lists, moving through code, comment handling -and automatic casing. - -@item -@file{ada-prj.el}: GUI editing of Ada mode project files, using Emacs -widgets. - -@item -@file{ada-stmt.el}: Ada statement templates. - -@item -@file{ada-xref.el}: GNAT cross-references, completion of identifiers, -and compilation. Also provides project files (which are not -GNAT-specific). - -@end itemize - -@node Customization, Compiling Executing, Installation, Top -@chapter Customizing Ada mode - -Here we assume you are familiar with setting variables in Emacs, -either thru 'customize' or in elisp (in your @file{.emacs} file). For -a basic introduction to customize, elisp, and Emacs in general, see -the tutorial in -@iftex -@cite{The GNU Emacs Manual}. -@end iftex -@ifhtml -@cite{The GNU Emacs Manual}. -@end ifhtml -@ifinfo -@ref{Top, , The GNU Emacs Manual, emacs, The GNU Emacs Manual}. -@end ifinfo - -These global Emacs settings are strongly recommended (put them in your -.emacs): - -@example -(global-font-lock-mode t) -(transient-mark-mode t) -@end example - -@samp{(global-font-lock-mode t)} turns on syntax -highlighting for all buffers (it is off by default because it may be -too slow for some machines). - -@samp{(transient-mark-mode t)} highlights selected text. - -See the Emacs help for each of these variables for more information. - -@menu -* Non-standard file names:: -* Other compiler:: -* Other customization:: -@end menu - -@node Non-standard file names, Other compiler, Customization, Customization -@section Non-standard file names - -By default, Ada mode is configured to use the GNAT file naming -convention, where file names are a simple modification of the Ada -names, and the extension for specs and bodies are -@samp{.ads} and @samp{.adb}, respectively. - -Ada mode uses the file extentions to allow moving from a package body -to the corresponding spec and back. - -Ada mode supports a list of alternative file extensions for specs and bodies. - -For instance, if your spec and bodies files are called -@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you -can add the following to your @file{.emacs} file: - -@example -(ada-add-extensions "_s.ada" "_b.ada") -@end example - -You can define additional extensions: - -@example -(ada-add-extensions ".ads" "_b.ada") -(ada-add-extensions ".ads" ".body") -@end example - -This means that whenever Ada mode looks for the body for a file -whose extension is @file{.ads}, it will take the first available file -that ends with either @file{.adb}, @file{_b.ada} or -@file{.body}. - -Simililarly, if Ada mode is looking for a spec, it will look for -@file{.ads} or @file{_s.ada}. - -If the filename is not derived from the Ada name following the GNAT -convention, things are a little more complicated. You then need to -rewrite the function @code{ada-make-filename-from-adaname}. Doing that -is beyond the scope of this manual; see the current definitions in -@file{ada-mode.el} and @file{ada-xref.el} for examples. - -@node Other compiler, Other customization, Non-standard file names, Customization -@section Other compiler - -By default, Ada mode is configured to use the Gnu Ada compiler GNAT. - -To use a different Ada compiler, you must specify the command lines -used to run that compiler, either in lisp variables or in Emacs -Ada mode project files. See @ref{Project file variables} for the list -of project variables, and the corresponding lisp variables. - -@node Other customization, , Other compiler, Customization -@section Other customization - -All user-settable Ada mode variables can be set via the menu -@samp{Ada | Customize}. Click on the @samp{Help} button there for help -on using customize. - -To modify a specific variable, you can directly call the function -@code{customize-variable}; just type @kbd{M-x customize-variable -@key{RET} @var{variable-name} @key{RET}}). - -Alternately, you can specify variable settings in the Emacs -configuration file, @file{.emacs}. This file is coded in Emacs lisp, -and the syntax to set a variable is the following: -@example -(setq variable-name value) -@end example - -@node Compiling Executing, Project files, Customization, Top -@chapter Compiling Executing - -Ada projects can be compiled, linked, and executed using commands on -the Ada menu. All of these commands can be customized via a project -file (@pxref{Project files}), but the defaults are sufficient for using -the GNAT compiler for simple projects (single files, or several files -in a single directory). - -Even when no project file is used, the GUI project editor (menu -@samp{Ada | Project | Edit}) shows the settings of the various project -file variables referenced here. - -@menu -* Compile commands:: -* Compiler errors:: -@end menu - -@node Compile commands, Compiler errors, Compiling Executing, Compiling Executing -@section Compile commands - -Here are the commands for building and using an Ada project, as -listed in the Ada menu. - -In multi-file projects, there must be one file that is the main -program. That is given by the @code{main} project file variable; -it defaults to the current file if not yet set, but is also set by the -``set main and build'' command. - -@table @code - -@item Check file -Compiles the current file in syntax check mode, by running -@code{check_cmd} defined in the current project file. This typically -runs faster than full compile mode, speeding up finding and fixing -compilation errors. - -This sets @code{main} only if it has not been set yet. - -@item Compile file -Compiles the current file, by running @code{comp_cmd} from the current -project file. - -This does not set @code{main}. - -@item Set main and Build -Sets @code{main} to the current file, then executes the Build -command. - -@item Show main -Display @code{main} in the message buffer. - -@item Build -Compiles all obsolete units of the current @code{main}, and links -@code{main}, by running @code{make_cmd} from the current project. - -This sets @code{main} only if it has not been set yet. - -@item Run -Executes the main program in a shell, displayed in a separate Emacs -buffer. This runs @code{run_cmd} from the current project. The -execution buffer allows for interactive input/output. - -To modify the run command, in particular to provide or change the -command line arguments, type @kbd{C-u} before invoking the command. - -This command is not available for a cross-compilation toolchain. - -@end table -It is important when using these commands to understand how -@code{main} is used and changed. - -Build runs 'gnatmake' on the main unit. During a typical edit/compile -session, this is the only command you need to invoke, which is why it -is bound to @kbd{C-c C-c}. It will compile all files needed by the -main unit, and display compilation errors in any of them. - -Note that Build can be invoked from any Ada buffer; typically you will -be fixing errors in files other than the main, but you don't have to -switch back to the main to invoke the compiler again. - -Novices and students typically work on single-file Ada projects. In -this case, @kbd{C-c C-m} will normally be the only command needed; it -will build the current file, rather than the last-built main. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main} and -@code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Compiler errors, , Compile commands, Compiling Executing -@section Compiler errors - -The @code{Check file}, @code{Compile file}, and @code{Build} commands -all place compilation errors in a separate buffer named -@code{*compilation*}. - -Each line in this buffer will become active: you can simply click on -it with the middle button of the mouse, or move point to it and press -@key{RET}. Emacs will then display the relevant source file and put -point on the line and column where the error was found. - -You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs -will jump to the first error. If you press that key again, it will -move you to the second error, and so on. - -Some error messages might also include references to other files. These -references are also clickable in the same way, or put point after the -line number and press @key{RET}. - -@node Project files, Compiling Examples, Compiling Executing, Top -@chapter Project files - -An Emacs Ada mode project file specifies what directories hold sources -for your project, and allows you to customize the compilation commands -and other things on a per-project basis. - -Note that Ada mode project files @samp{*.adp} are different than GNAT -compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a -GNAT project file to specify the project directories. If no -other customization is needed, a GNAT project file can be used without -an Emacs Ada mode project file. - -@menu -* Project File Overview:: -* GUI Editor:: -* Project file variables:: -@end menu - -@node Project File Overview, GUI Editor, Project files, Project files -@section Project File Overview - -Project files have a simple syntax; they may be edited directly. Each -line specifies a project variable name and its value, separated by ``='': -@example -src_dir=/Projects/my_project/src_1 -src_dir=/Projects/my_project/src_2 -@end example - -Some variables (like @code{src_dir}) are lists; multiple occurances -are concatenated. - -There must be no space between the variable name and ``='', and no -trailing spaces. - -Alternately, a GUI editor for project files is available (@pxref{GUI -Editor}). It uses Emacs widgets, similar to Emacs customize. - -The GUI editor also provides a convenient way to view current project -settings, if they have been modified using menu commands rather than -by editing the project file. - -After the first Ada mode build command is invoked, there is always a -current project file, given by the lisp variable -@code{ada-prj-default-project-file}. Currently, the only way to show -the current project file is to invoke the GUI editor. - -To find the project file the first time, Ada mode uses the following -search algorithm: - -@itemize @bullet -@item -If @code{ada-prj-default-project-file} is set, use that. - -@item -Otherwise, search for a file in the current directory with -the same base name as the Ada file, but extension given by -@code{ada-prj-file-extension} (default @code{".adp"}). - -@item -If not found, search for @file{*.adp} in the current directory; if -several are found, prompt the user to select one. - -@item -If none are found, use @file{default.adp} in the current directory (even -if it does not exist). - -@end itemize - -This algorithm always sets @code{ada-prj-default-project-file}, even -when the file does not actually exist. - -To change the project file before or after the first one is found, -invoke @samp{Ada | Project | Load ...}. - -Or, in lisp, evaluate @code{(ada-set-default-project-file "/path/file.adp")}. -This sets @code{ada-prj-default-project-file}, and reads the project file. - -You can also specify a GNAT project file to @samp{Ada | Project | Load -...} or @code{ada-set-default-project-file}. Emacs Ada mode checks the -file extension; if it is @code{.gpr}, the file is treated as a GNAT -project file. Any other extension is treated as an Emacs Ada mode -project file. - -@node GUI Editor, Project file variables, Project File Overview, Project files -@section GUI Editor - -The project file editor is invoked with the menu @samp{Ada | Projects -| Edit}. - -Once in the buffer for editing the project file, you can save your -modification using the @samp{[save]} button at the bottom of the -buffer, or the @kbd{C-x C-s} binding. To cancel your modifications, -kill the buffer or click on the @samp{[cancel]} button. - -@node Project file variables, , GUI Editor, Project files -@section Project file variables - -The following variables can be defined in a project file; some can -also be defined in lisp variables. - -To set a project variable that is a list, specify each element of the -list on a separate line in the project file. - -Any project variable can be referenced in other project variables, -using a shell-like notation. For instance, if the variable -@code{comp_cmd} contains @code{$@{comp_opt@}}, the value of the -@code{comp_opt} variable will be substituted when @code{comp_cmd} is -used. - -In addition, process environment variables can be referenced using the -same syntax, or the normal @code{$var} syntax. - -Most project variables have defaults that can be changed by setting -lisp variables; the table below identifies the lisp variable for each -project variable. Lisp variables corresponding to project variables -that are lists are lisp lists. - -In general, project variables are evaluated when referenced in -Emacs Ada mode commands. Relative file paths are expanded to -absolute relative to @code{$@{build_dir@}}. - -Here is the list of variables. In the default values, the current -directory @code{"."} is the project file directory. - -@table @asis -@c defined in ada-default-prj-properties; alphabetical order - -@item @code{ada_project_path_sep} [default: @code{":" or ";"}] -Path separator for @code{ADA_PROJECT_PATH}. It defaults to the correct -value for a native implementation of GNAT for the current operating -system. The user must override this when using Windows native GNAT -with Cygwin Emacs, and perhaps in other cases. - -Lisp variable: @code{ada-prj-ada-project-path-sep}. - -@item @code{ada_project_path} [default: @code{""}] -A list of directories to search for GNAT project files. - -If set, the @code{ADA_PROJECT_PATH} process environment variable is -set to this value in the Emacs process when the Emacs Ada mode project -is selected via menu @samp{Ada | Project | Load}. - -For @code{ada_project_path}, relative file paths are expanded to -absolute when the Emacs Ada project file is read, rather than when the -project file is selected. - -For example if the project file is in the directory -@file{/home/myproject}, the environment variable @code{GDS_ROOT} is -set to @code{/home/shared}, and the project file contains: -@example -ada_project_path_sep=: -ada_project_path=$GDS_ROOT/makerules -ada_project_path=../opentoken -@end example -the environment variable @code{ADA_PROJECT_PATH} will be set to -@code{"/home/shared/makerules:/home/opentoken/"}. - -The default value is not the current value of this environment -variable, because that will typically have been set by another -project, and will therefore be incorrect for this project. - -If you have the environment variable set correctly for all of your -projects, you do not need to set this project variable. - -@item @code{bind_opt} [default: @code{""}] -Holds user binder options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-bind-opt}. - -@item @code{build_dir} [default: @code{"."}] -The compile commands will be issued in this directory. - -@item @code{casing} [default: @code{("~/.emacs_case_exceptions")} -List of files containing casing exceptions. See the help on -@code{ada-case-exception-file} for more info. -@c FIXME: section on case exceptions - -Lisp variable: @code{ada-case-exception-file}. - -@item @code{check_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c -gnatc $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to syntax check a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-check-cmd} - -@item @code{comp_cmd} [default: @code{"$@{cross_prefix@}gnatmake -u -c $@{gnatmake_opt@} $@{full_current@} -cargs $@{comp_opt@}"}] -Command used to compile a single file. -The name of the file is substituted for @code{full_current}. - -Lisp variable: @code{ada-prj-default-comp-cmd}. - -@item @code{comp_opt} [default: @code{"-gnatq -gnatQ"}] -Holds user compiler options; used in the default compile commands. The -default value tells gnatmake to generate library files for -cross-referencing even when there are errors. - -If source code for the project is in multiple directories, the -appropriate compiler options must be added here. @ref{Set source -search path} for examples of this. Alternately, GNAT project files may -be used; @ref{Use GNAT project file}. - -Lisp variable: @code{ada-prj-default-comp-opt}. - -@item @code{cross_prefix} [default: @code{""}] -Name of target machine in a cross-compilation environment. Used in -default compile and build commands. - -@item @code{debug_cmd} [default: @code{"$@{cross_prefix@}gdb $@{main@}"}] -Command used to debug the application - -Lisp variable: @code{ada-prj-default-debugger}. - -@item @code{debug_post_cmd} [default: @code{""}] -Command executed after @code{debug_cmd}. - -@item @code{debug_pre_cmd} [default: @code{"cd $@{build_dir@}"}] -Command executed before @code{debug_cmd}. - -@item @code{gnatfind_opt} [default: @code{"-rf"}] -Holds user gnatfind options; used in the default find commands. - -Lisp variable: @code{ada-prj-gnatfind-switches}. - -@item @code{gnatmake_opt} [default: @code{"-g"}] -Holds user gnatmake options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-gnatmake-opt}. - -@item @code{gpr_file} [default: @code{""}] -Specify GNAT project file. - -If set, the source and object directories specified in the GNAT -project file are appended to @code{src_dir} and @code{obj_dir}. This -allows specifying Ada source directories with a GNAT project file, and -other source directories with the Emacs project file. - -In addition, @code{-P@{gpr_file@}} is added to the project variable -@code{gnatmake_opt} whenever it is referenced. With the default -project variables, this passes the project file to all gnatmake -commands. - -Lisp variable: @code{ada-prj-default-gpr-file}. - -@c FIXME: add gnatstub-opts - -@item @code{link_opt} [default: @code{""}] -Holds user linker options; used in the default build commands. - -Lisp variable: @code{ada-prj-default-link-opt}. - -@item @code{main} [default: current file] -Specifies the name of the executable file for the project; used in the -default build commands. - -@item @code{make_cmd} [default: @code{"$@{cross_prefix@}gnatmake -o $@{main@} $@{main@} $@{gnatmake_opt@} -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}] -Command used to build the application. - -Lisp variable: @code{ada-prj-default-make-cmd}. - -@item @code{obj_dir} [default: @code{"."}] -A list of directories to search for library files. Ada mode searches -this list for the @samp{.ali} files generated by GNAT that contain -cross-reference information. - -The compiler commands must place the @samp{.ali} files in one of these -directories; the default commands do that. - -@item @code{remote_machine} [default: @code{""}] -Name of the machine to log into before issuing the compile and build -commands. If this variable is empty, the command will be run on the -local machine. - -@item @code{run_cmd} [default: @code{"./$@{main@}"}] -Command used to run the application. - -@item @code{src_dir} [default: @code{"."}] -A list of directories to search for source files, both for compile -commands and source navigation. - -@end table - -@node Compiling Examples, Moving Through Ada Code, Project files, Top -@chapter Compiling Examples - -We present several small projects, and walk thru the process of -compiling, linking, and running them. - -The first example illustrates more Ada mode features than the others; -you should work thru that example before doing the others. - -All of these examples assume you are using GNAT. - -The source for these examples is available on the Emacs Ada mode -website mentioned in @xref{Installation}. - -@menu -* No project files:: Just menus -* Set compiler options:: A basic Ada mode project file -* Set source search path:: Source in multiple directories -* Use GNAT project file:: -* Use multiple GNAT project files:: -@end menu - -@node No project files, Set compiler options, Compiling Examples, Compiling Examples -@section No project files -This example uses no project files. - -First, create a directory @file{Example_1}, containing: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate -compiler error handling. - -@file{hello_2.adb}: - -@example -with Hello_Pkg; -procedure Hello_2 -is begin - Hello_Pkg.Say_Hello; -end Hello_2; -@end example - -This file has no errors. - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -This file has no errors. - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -Yes, this is missing the keyword @code{body}; another compiler error -example. - -In buffer @file{hello.adb}, invoke @samp{Ada | Check file}. You should -get a @code{*compilation*} buffer containing something like (the -directory paths will be different): - -@example -cd c:/Examples/Example_1/ -gnatmake -u -c -gnatc -g c:/Examples/Example_1/hello.adb -cargs -gnatq -gnatQ -gcc -c -Ic:/Examples/Example_1/ -gnatc -g -gnatq -gnatQ -I- c:/Examples/Example_1/hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -gnatmake: "c:/Examples/Example_1/hello.adb" compilation error -@end example - -If you have enabled font-lock, the lines with actual errors (starting -with @file{hello.adb}) are highlighted, with the file name in red. - -Now type @kbd{C-x `} (on a PC keyboard, @key{`} is next to @key{1}). -Or you can click the middle mouse button on the first error line. The -compilation buffer scrolls to put the first error on the top line, and -point is put at the place of the error in the @file{hello.adb} buffer. - -To fix the error, change the line to be - -@example - Ada.Text_IO.Put_Line ("hello from hello.adb"); -@end example - -Now invoke @samp{Ada | Show main}; this displays @samp{Ada mode main: hello}. - -Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build}. You are -prompted to save the file (if you haven't already). Then the -compilation buffer is displayed again, containing: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello hello -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello.adb -gnatbind -x hello.ali -gnatlink hello.ali -o hello.exe -g -@end example - -The compilation has succeeded without errors; @file{hello.exe} now -exists in the same directory as @file{hello.adb}. - -Now invoke @samp{Ada | Run}. A @file{*run*} buffer is displayed, -containing - -@example -Hello from hello.adb - -Process run finished -@end example - -That completes the first part of this example. - -Now we will compile a multi-file project. Open the file -@file{hello_2.adb}, and invoke @samp{Ada | Set main and Build}. This -finds an error in @file{hello_pkg.adb}: - -@example -cd c:/Examples/Example_1/ -gnatmake -o hello_2 hello_2 -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatq -gnatQ hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "hello_pkg.adb" compilation error -@end example - -This demonstrates that gnatmake finds the files needed by the main -program. However, it cannot find files in a different directory, -unless you use an Emacs Ada mode project file to specify the other directories; -@xref{Set source search path}, or a GNAT project file; @ref{Use GNAT -project file}. - -Invoke @samp{Ada | Show main}; this displays @file{Ada mode main: hello_2}. - -Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}: - -@example -package body Hello_Pkg is -@end example - -Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build}. -gnatmake successfully builds @file{hello_2}. This demonstrates that -Emacs has remembered the main file, in the project variable -@code{main}, and used it for the Build command. - -Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Run}. -The @code{*run*} buffer displays @code{Hello from hello_pkg.adb}. - -One final point. If you switch back to buffer @file{hello.adb}, and -invoke @samp{Ada | Run}, @file{hello_2.exe} will be run. That is -because @code{main} is still set to @code{hello_2}, as you can -see when you invoke @samp{Ada | Project | Edit}. - -There are three ways to change @code{main}: - -@enumerate -@item -Invoke @samp{Ada | Set main and Build}, which sets @code{main} to -the current file. - -@item -Invoke @samp{Ada | Project | Edit}, edit @code{main}, and click @samp{[save]} - -@item -Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main} - -@end enumerate - -@node Set compiler options, Set source search path, No project files, Compiling Examples -@section Set compiler options - -This example illustrates using an Emacs Ada mode project file to set a -compiler option. - -If you have files from @file{Example_1} open in Emacs, you should -close them so you don't get confused. Use menu @samp{File | Close -(current buffer)}. - -In directory @file{Example_2}, create these files: - -@file{hello.adb}: - -@example -with Ada.Text_IO; -procedure Hello -is begin - Put_Line("Hello from hello.adb"); -end Hello; -@end example - -This is the same as @file{hello.adb} from @file{Example_1}. It has two -errors; missing ``use Ada.Text_IO;'', and no space between -@code{Put_Line} and its argument list. - -@file{hello.adp}: - -@example -comp_opt=-gnatyt -@end example - -This tells the GNAT compiler to check for token spacing; in -particular, there must be a space preceding a parenthesis. - -In buffer @file{hello.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_2/hello.adp}. - -Then, again in buffer @file{hello.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_2/ -gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs -gcc -c -g -gnatyt hello.adb -hello.adb:4:04: "Put_Line" is not visible -hello.adb:4:04: non-visible declaration at a-textio.ads:264 -hello.adb:4:04: non-visible declaration at a-textio.ads:260 -hello.adb:4:12: (style) space required -gnatmake: "hello.adb" compilation error -@end example - -Compare this to the compiler output in @ref{No project files}; the -gnatmake option @code{-cargs -gnatq -gnatQ} has been replaced by -@code{-cargs -gnaty}, and an additional error is reported in -@file{hello.adb} on line 4. This shows that @file{hello.adp} is being -used to set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples -@section Set source search path - -In this example, we show how to deal with files in more than one -directory. We start with the same code as in @ref{No project files}; -create those files (with the errors present) - -Create the directory @file{Example_3}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_3/Other}, containing these files: - -@file{Other/hello_3.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_3 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_3"); -end Hello_3; -@end example - -There are no errors in this file. - -@file{Other/other.adp}: - -@example -src_dir=.. -comp_opt=-I.. -@end example - -Note that there must be no trailing spaces. - -In buffer @file{hello_3.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_3/Other/other.adp}. - -Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_3/Other/ -gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs -gcc -c -g -I.. hello_3.adb -gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error -@end example - -Compare the @code{-cargs} option to the compiler output in @ref{Set -compiler options}; this shows that @file{other.adp} is being used to -set the compiler options. - -Move to the error with @kbd{C-x `}. Ada mode searches the list of -directories given by @code{src_dir} for the file mentioned in the -compiler error message. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples -@section Use GNAT project file - -In this example, we show how to use a GNAT project file, with no Ada -mode project file. - -Create the directory @file{Example_4}, containing: - -@file{hello_pkg.ads}: - -@example -package Hello_Pkg is - procedure Say_Hello; -end Hello_Pkg; -@end example - -@file{hello_pkg.adb}: - -@example -with Ada.Text_IO; -package Hello_Pkg is - procedure Say_Hello - is begin - Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb"); - end Say_Hello; -end Hello_Pkg; -@end example - -These are the same files from example 1; @file{hello_pkg.adb} has an -error on line 2. - -In addition, create a directory @file{Example_4/Gnat_Project}, -containing these files: - -@file{Gnat_Project/hello_4.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_4 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_4"); -end Hello_4; -@end example - -There are no errors in this file. - -@file{Gnat_Project/hello_4.gpr}: - -@example -Project Hello_4 is - for Source_Dirs use (".", ".."); -end Hello_4; -@end example - -In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_4/Gnat_Project/hello_4.gpr}. - -Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_4/Gnat_Project/ -gnatmake -o hello_4 hello_4 -Phello_4.gpr -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\Gnat_Project\hello_4.adb -gcc -c -g -gnatyt -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end example - -Compare the @code{gcc} options to the compiler output in @ref{Set -compiler options}; this shows that @file{hello_4.gpr} is being used to -set the compiler options. - -Fixing the error, linking and running the code proceed as in @ref{No -project files}. - -@node Use multiple GNAT project files, , Use GNAT project file, Compiling Examples -@section Use multiple GNAT project files - -In this example, we show how to use multiple GNAT project files, -specifying the GNAT project search path in an Ada mode project file. - -Create the directory @file{Example_4} as specified in @ref{Use GNAT -project file}. - -Create the directory @file{Example_5}, containing: - -@file{hello_5.adb}: - -@example -with Hello_Pkg; -with Ada.Text_IO; use Ada.Text_IO; -procedure Hello_5 -is begin - Hello_Pkg.Say_Hello; - Put_Line ("From hello_5"); -end Hello_5; -@end example - -There are no errors in this file. - -@file{hello_5.adp}: - -@example -ada_project_path=../Example_4/Gnat_Project -gpr_file=hello_5.gpr -@end example - -@file{hello_5.gpr}: - -@example -with "hello_4"; -Project Hello_5 is - for Source_Dirs use ("."); - package Compiler is - for Default_Switches ("Ada") use ("-g", "-gnatyt"); - end Compiler; -end Hello_5; -@end example - -In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Load...}, and -select @file{Example_5/hello_5.adp}. - -Then, again in @file{hello_5.adb}, invoke @samp{Ada | Set main and -Build}. You should get a @code{*compilation*} buffer containing -something like (the directory paths will be different): - -@example -cd c:/Examples/Example_5/ -gnatmake -o hello_5 hello_5 -Phello_5.gpr -g -cargs -gnatq -gnatQ -bargs -largs -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_5\hello_5.adb -gcc -c -g -gnatyt -g -gnatq -gnatQ -I- -gnatA c:\Examples\Example_4\hello_pkg.adb -hello_pkg.adb:2:08: keyword "body" expected here [see file name] -gnatmake: "c:\examples\example_4\hello_pkg.adb" compilation error -@end example - -Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown, -demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being -used to set the compilation search path. - -@node Moving Through Ada Code, Identifier completion, Compiling Examples, Top -@chapter Moving Through Ada Code - -There are several easy to use commands to navigate through Ada code. All -these functions are available through the Ada menu, and you can also -use the following key bindings or the command names. Some of these -menu entries are available only if the GNAT compiler is used, since -the implementation relies on the GNAT cross-referencing information. - -@table @kbd -@item M-C-e -@findex ada-next-procedure -Move to the next function/procedure/task, which ever comes next -(@code{ada-next-procedure}). -@item M-C-a -@findex ada-previous-procedure -Move to previous function/procedure/task -(@code{ada-previous-procedure}). -@item M-x ada-next-package -@findex ada-next-package -Move to next package. -@item M-x ada-previous-package -@findex ada-previous-package -Move to previous package. -@item C-c C-a -@findex ada-move-to-start -Move to matching start of @code{end} (@code{ada-move-to-start}). If -point is at the end of a subprogram, this command jumps to the -corresponding @code{begin} if the user option -@code{ada-move-to-declaration} is @code{nil} (default), otherwise it jumps to -the subprogram declaration. -@item C-c C-e -@findex ada-move-to-end -Move point to end of current block (@code{ada-move-to-end}). -@item C-c o -Switch between corresponding spec and body file -(@code{ff-find-other-file}). If point is in a subprogram, position -point on the corresponding declaration or body in the other file. -@item C-c c-d -@findex ada-goto-declaration -Move from any reference to its declaration, for from a declaration to -its body (for procedures, tasks, private and incomplete types). -@item C-c C-r -@findex ada-find-references -Runs the @file{gnatfind} command to search for all references to the -identifier surrounding point (@code{ada-find-references}). Use -@kbd{C-x `} (@code{next-error}) to visit each reference (as for -compilation errors). -@end table - -If the @code{ada-xref-create-ali} variable is non-@code{nil}, Emacs -will try to run GNAT for you whenever cross-reference information is -needed, and is older than the current source file. - -@node Identifier completion, Automatic Smart Indentation, Moving Through Ada Code, Top -@chapter Identifier completion - -Emacs and Ada mode provide two general ways for the completion of -identifiers. This is an easy way to type faster: you just have to type -the first few letters of an identifiers, and then loop through all the -possible completions. - -The first method is general for Emacs. It works by parsing all open -files for possible completions. - -For instance, if the words @samp{my_identifier}, @samp{my_subprogram} -are the only words starting with @samp{my} in any of the opened files, -then you will have this scenario: - -@example -You type: my@kbd{M-/} -Emacs inserts: @samp{my_identifier} -If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with -@samp{my_subprogram}. -Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}. -@end example - -This is a very fast way to do completion, and the casing of words will -also be respected. - -The second method (@kbd{C-@key{TAB}}) is specific to Ada mode and the GNAT -compiler. Emacs will search the cross-information for possible -completions. - -The main advantage is that this completion is more accurate: only -existing identifier will be suggested. - -On the other hand, this completion is a little bit slower and requires -that you have compiled your file at least once since you created that -identifier. - -@table @kbd -@item C-@key{TAB} -@findex ada-complete-identifier -Complete current identifier using cross-reference information. -@item M-/ -Complete identifier using buffer information (not Ada-specific). -@end table - -@node Automatic Smart Indentation, Formatting Parameter Lists, Identifier completion, Top -@chapter Automatic Smart Indentation - -Ada mode comes with a full set of rules for automatic indentation. You -can also configure the indentation, via the following variables: - -@table @asis -@item @code{ada-broken-indent} (default value: 2) -Number of columns to indent the continuation of a broken line. - -@item @code{ada-indent} (default value: 3) -Number of columns for default indentation. - -@item @code{ada-indent-record-rel-type} (default value: 3) -Indentation for @code{record} relative to @code{type} or @code{use}. - -@item @code{ada-indent-return} (default value: 0) -Indentation for @code{return} relative to @code{function} (if -@code{ada-indent-return} is greater than 0), or the open parenthesis -(if @code{ada-indent-return} is negative or 0). Note that in the second -case, when there is no open parenthesis, the indentation is done -relative to @code{function} with the value of @code{ada-broken-indent}. - -@item @code{ada-label-indent} (default value: -4) -Number of columns to indent a label. - -@item @code{ada-stmt-end-indent} (default value: 0) -Number of columns to indent a statement @code{end} keyword on a separate line. - -@item @code{ada-when-indent} (default value: 3) -Indentation for @code{when} relative to @code{exception} or @code{case}. - -@item @code{ada-indent-is-separate} (default value: t) -Non-@code{nil} means indent @code{is separate} or @code{is abstract} if on a single line. - -@item @code{ada-indent-to-open-paren} (default value: t) -Non-@code{nil} means indent according to the innermost open parenthesis. - -@item @code{ada-indent-after-return} (default value: t) -Non-@code{nil} means that the current line will also be re-indented -before inserting a newline, when you press @key{RET}. -@end table - -Most of the time, the indentation will be automatic, i.e when you -press @key{RET}, the cursor will move to the correct column on the -next line. - -You can also indent single lines, or the current region, with @key{TAB}. - -Another mode of indentation exists that helps you to set up your -indentation scheme. If you press @kbd{C-c @key{TAB}}, Ada mode will do -the following: - -@itemize @bullet -@item -Reindent the current line, as @key{TAB} would do. -@item -Temporarily move the cursor to a reference line, i.e., the line that -was used to calculate the current indentation. -@item -Display in the message window the name of the variable that provided -the offset for the indentation. -@end itemize - -The exact indentation of the current line is the same as the one for the -reference line, plus an offset given by the variable. - -@table @kbd -@item @key{TAB} -Indent the current line or the current region. -@item C-M-\ -Indent lines in the current region. -@item C-c @key{TAB} -Indent the current line and display the name of the variable used for -indentation. -@end table - -@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top -@chapter Formatting Parameter Lists - -@table @kbd -@item C-c C-f -@findex ada-format-paramlist -Format the parameter list (@code{ada-format-paramlist}). -@end table - -This aligns the declarations on the colon (@samp{:}) separating -argument names and argument types, and aligns the @code{in}, -@code{out} and @code{in out} keywords. - -@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top -@chapter Automatic Casing - -Casing of identifiers, attributes and keywords is automatically -performed while typing when the variable @code{ada-auto-case} is set. -Every time you press a word separator, the previous word is -automatically cased. - -You can customize the automatic casing differently for keywords, -attributes and identifiers. The relevant variables are the following: -@code{ada-case-keyword}, @code{ada-case-attribute} and -@code{ada-case-identifier}. - -All these variables can have one of the following values: - -@table @code -@item downcase-word -The word will be lowercase. For instance @code{My_vARIable} is -converted to @code{my_variable}. - -@item upcase-word -The word will be uppercase. For instance @code{My_vARIable} is -converted to @code{MY_VARIABLE}. - -@item ada-capitalize-word -The first letter and each letter following an underscore (@samp{_}) -are uppercase, others are lowercase. For instance @code{My_vARIable} -is converted to @code{My_Variable}. - -@item ada-loose-case-word -Characters after an underscore @samp{_} character are uppercase, -others are not modified. For instance @code{My_vARIable} is converted -to @code{My_VARIable}. -@end table - -Ada mode allows you to define exceptions to these rules, in a file -specified by the variable @code{ada-case-exception-file} -(default @file{~/.emacs_case_exceptions}). Each line in this file -specifies the casing of one word or word fragment. Comments may be -included, separated from the word by a space. - -If the word starts with an asterisk (@key{*}), it defines the casing -af a word fragemnt (or ``substring''); part of a word between two -underscores or word boundary. - -For example: - -@example -DOD Department of Defense -*IO -GNAT The GNAT compiler from Ada Core Technologies -@end example - -The word fragment @code{*IO} applies to any word containing ``_io''; -@code{Text_IO}, @code{Hardware_IO}, etc. - -@findex ada-create-case-exception -There are two ways to add new items to this file: you can simply edit -it as you would edit any text file. Or you can position point on the -word you want to add, and select menu @samp{Ada | Edit | Create Case -Exception}, or press @kbd{C-c C-y} (@code{ada-create-case-exception}). -The word will automatically be added to the current list of exceptions -and to the file. - -To define a word fragment case exception, select the word fragment, -then select menu @samp{Ada | Edit | Create Case Exception Substring}. - -It is sometimes useful to have multiple exception files around (for -instance, one could be the standard Ada acronyms, the second some -company specific exceptions, and the last one some project specific -exceptions). If you set up the variable @code{ada-case-exception-file} -as a list of files, each of them will be parsed and used in your emacs -session. However, when you save a new exception through the menu, as -described above, the new exception will be added to the first file in -the list. - -@table @kbd -@item C-c C-b -@findex ada-adjust-case-buffer -Adjust case in the whole buffer (@code{ada-adjust-case-buffer}). -@item C-c C-y -Create a new entry in the exception dictionary, with the word under -the cursor (@code{ada-create-case-exception}) -@item C-c C-t -@findex ada-case-read-exceptions -Rereads the exception dictionary from the file -@code{ada-case-exception-file} (@code{ada-case-read-exceptions}). -@end table - -@node Statement Templates, Comment Handling, Automatic Casing, Top -@chapter Statement Templates - -Templates are defined for most Ada statements, using the Emacs -``skeleton'' package. They can be inserted in the buffer using the -following commands: - -@table @kbd -@item C-c t b -@findex ada-exception-block -exception Block (@code{ada-exception-block}). -@item C-c t c -@findex ada-case -case (@code{ada-case}). -@item C-c t d -@findex ada-declare-block -declare Block (@code{ada-declare-block}). -@item C-c t e -@findex ada-else -else (@code{ada-else}). -@item C-c t f -@findex ada-for-loop -for Loop (@code{ada-for-loop}). -@item C-c t h -@findex ada-header -Header (@code{ada-header}). -@item C-c t i -@findex ada-if -if (@code{ada-if}). -@item C-c t k -@findex ada-package-body -package Body (@code{ada-package-body}). -@item C-c t l -@findex ada-loop -loop (@code{ada-loop}). -@item C-c p -@findex ada-subprogram-body -subprogram body (@code{ada-subprogram-body}). -@item C-c t t -@findex ada-task-body -task Body (@code{ada-task-body}). -@item C-c t w -@findex ada-while -while Loop (@code{ada-while}). -@item C-c t u -@findex ada-use -use (@code{ada-use}). -@item C-c t x -@findex ada-exit -exit (@code{ada-exit}). -@item C-c t C-a -@findex ada-array -array (@code{ada-array}). -@item C-c t C-e -@findex ada-elsif -elsif (@code{ada-elsif}). -@item C-c t C-f -@findex ada-function-spec -function Spec (@code{ada-function-spec}). -@item C-c t C-k -@findex ada-package-spec -package Spec (@code{ada-package-spec}). -@item C-c t C-p -@findex ada-procedure-spec -procedure Spec (@code{ada-package-spec}. -@item C-c t C-r -@findex ada-record -record (@code{ada-record}). -@item C-c t C-s -@findex ada-subtype -subtype (@code{ada-subtype}). -@item C-c t C-t -@findex ada-task-spec -task Spec (@code{ada-task-spec}). -@item C-c t C-u -@findex ada-with -with (@code{ada-with}). -@item C-c t C-v -@findex ada-private -private (@code{ada-private}). -@item C-c t C-w -@findex ada-when -when (@code{ada-when}). -@item C-c t C-x -@findex ada-exception -exception (@code{ada-exception}). -@item C-c t C-y -@findex ada-type -type (@code{ada-type}). -@end table - -@node Comment Handling, GNU Free Documentation License, Statement Templates, Top -@chapter Comment Handling - -By default, comment lines get indented like Ada code. There are a few -additional functions to handle comments: - -@table @kbd -@item M-; -Start a comment in default column. -@item M-j -Continue comment on next line. -@item C-c ; -Comment the selected region (add -- at the beginning of lines). -@item C-c : -Uncomment the selected region -@item M-q -autofill the current comment. -@end table - -@node GNU Free Documentation License, Index, Comment Handling, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index - -@printindex fn - -@bye - -@ignore - arch-tag: 68cf0d8a-55cc-4190-a28d-4984fa56ed1e -@end ignore diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi deleted file mode 100644 index e4eaedbbc75..00000000000 --- a/doc/misc/auth.texi +++ /dev/null @@ -1,197 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/auth -@settitle Emacs auth-source Library @value{VERSION} - -@set VERSION 0.1 - -@copying -This file describes the Emacs auth-source library. - -Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Auth-source: (auth). The Emacs auth-source library. -@end direntry - -@titlepage -@title Emacs auth-source Library -@author by Ted Zlatanov -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs auth-source -This manual describes the Emacs auth-source library. - -It is a way for multiple applications to share a single configuration -(in Emacs and in files) for user convenience. - -@insertcopying - -@menu -* Overview:: Overview of the auth-source library. -* Help for users:: -* Help for developers:: -* Index:: -* Function Index:: -* Variable Index:: -@end menu -@end ifnottex - -@node Overview -@chapter Overview - -To be done. - -@node Help for users -@chapter Help for users - -If you have problems with the port, turn up @code{gnus-verbose} and -see what port the library is checking. Ditto for any other -problems, your first step is to see what's being checked. - -Setup: - -@lisp -(require 'auth-source) -(customize-variable 'auth-sources) ;; optional, do it once -@end lisp - -@defvar auth-sources - -The @var{auth-sources} variable tells the auth-source library where -your netrc files live for a particular host and protocol. While you -can get fancy, the default and simplest configuration is: - -@lisp -(setq auth-sources '((:source "~/.authinfo.gpg" :host t :protocol t))) -@end lisp - -By adding multiple entries to that list with a particular host or -protocol, you can have specific netrc files for that host or protocol. - -@end defvar - - -``Netrc'' files are a de facto standard. They look like this: -@example -machine mymachine login myloginname password mypassword port myport -@end example - -The port is optional. If it's missing, auth-source will assume any -port is OK. Actually the port is a protocol name or a port number so -you can have separate entries for port 143 and for protocol ``imap'' -if you fancy that. - -If you don't customize @var{auth-sources}, you'll have to live with -the defaults: any host and any port are looked up in the netrc -file @code{~/.authinfo.gpg}. This is an encrypted file if and only if -you set up EPA, which is strongly recommended. - -@lisp -(require 'epa-file) -(epa-file-enable) -(setq epa-file-cache-passphrase-for-symmetric-encryption t) ; VERY important -@end lisp - -For url-auth authentication (HTTP/HTTPS), you need to put this in your -netrc file: - -@example -machine yourmachine.com:80 port http login testuser password testpass -@end example - -This will match any realm and authentication method (basic or -digest). If you want finer controls, explore the url-auth source -code and variables. - -For Tramp authentication, use: - -@example -machine yourmachine.com port scp login testuser password testpass -@end example - -Note that the port denotes the Tramp connection method. When you -don't use a port entry, you match any Tramp method, as explained -earlier. - -@node Help for developers -@chapter Help for developers - -The auth-source library only has one function for external use. - -@defun auth-source-user-or-password mode host port - -Retrieve appropriate authentication tokens, determined by @var{mode}, -for host @var{host} and @var{port}. If @code{gnus-verbose} is 9 or -higher, debugging messages will be printed. - -If @var{mode} is a list of strings, the function will return a list of -strings or @code{nil} objects. If it's a string, the function will -return a string or a @code{nil} object. Currently only the modes -``login'' and ``password'' are recognized but more may be added in the -future. - -@var{host} is a string containing the host name. - -@var{port} contains the protocol name (e.g. ``imap'') or -a port number. It must be a string, corresponding to the port in the -users' netrc files. - -@example -;; IMAP example -(setq auth (auth-source-user-or-password - '("login" "password") - "anyhostnamehere" - "imap")) -(nth 0 auth) ; the login name -(nth 1 auth) ; the password -@end example - -@end defun - -@node Index -@chapter Index -@printindex cp - -@node Function Index -@chapter Function Index -@printindex fn - -@node Variable Index -@chapter Variable Index -@printindex vr - -@bye - -@c End: - -@ignore - arch-tag: 7b835fd3-473f-40fc-9776-1c4e49d26c94 -@end ignore diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi deleted file mode 100644 index 0ca6b8105ea..00000000000 --- a/doc/misc/autotype.texi +++ /dev/null @@ -1,670 +0,0 @@ -\input texinfo -@c This is an annex of the Emacs manual. -@c Author: Daniel.Pfeiffer@Informatik.START.dbp.de, fax (+49 69) 7588-2389 -@setfilename ../../info/autotype -@c @node Autotypist, Picture, Abbrevs, Top -@c @chapter Features for Automatic Typing -@settitle Features for Automatic Typing -@c @cindex text -@c @cindex selfinserting text -@c @cindex autotypist - -@copying -Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Autotype: (autotype). Convenient features for text that you enter frequently - in Emacs. -@end direntry - -@titlepage -@sp 10 - -@center @titlefont{Autotyping} -@sp 2 -@center @subtitlefont{Convenient features for text that you enter -frequently in Emacs} -@sp 2 -@center Daniel Pfeiffer -@center additions by Dave Love - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Autotyping - - Under certain circumstances you will find yourself typing similar things -over and over again. This is especially true of form letters and programming -language constructs. Project-specific header comments, flow-control -constructs or magic numbers are essentially the same every time. Emacs has -various features for doing tedious and repetitive typing chores for you -in addition to the Abbrev features (@pxref{(emacs)Abbrevs}). - - One solution is using skeletons, flexible rules that say what to -insert, and how to do it. Various programming language modes offer some -ready-to-use skeletons, and you can adapt them to suit your needs or -taste, or define new ones. - - Another feature is automatic insertion of what you want into empty files, -depending on the file-name or the mode as appropriate. You can have a file or -a skeleton inserted, or you can call a function. Then there is the -possibility to have Un*x interpreter scripts automatically take on a magic -number and be executable as soon as they are saved. Or you can have a -copyright notice's year updated, if necessary, every time you save a -file. Similarly for time stamps in the file. - - URLs can be inserted based on a word at point. Flexible templates can -be defined for inserting and navigating between text more generally. A -sort of meta-expansion facility can be used to try a set of alternative -completions and expansions of text at point. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Using Skeletons:: How to insert a skeleton into your text. -* Wrapping Skeletons:: Putting existing text within a skeleton. -* Skeletons as Abbrevs:: An alternative for issuing skeleton commands. -* Skeleton Language:: Making skeleton commands insert what you want. -* Inserting Pairs:: Typing one character and getting another - after point. -* Autoinserting:: Filling up empty files as soon as you visit them. -* Copyrights:: Inserting and updating copyrights. -* Executables:: Turning interpreter scripts into executables. -* Timestamps:: Updating dates and times in modified files. -* QuickURL:: Inserting URLs based on text at point. -* Tempo:: Flexible template insertion. -* Hippie Expand:: Expansion of text trying various methods. - -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Command Index:: -* Variable Index:: -@end menu - - -@node Using Skeletons -@chapter Using Skeletons -@cindex skeletons -@cindex using skeletons - - When you want Emacs to insert a form letter or a typical construct of the -programming language you are using, skeletons are a means of accomplishing -this. Normally skeletons each have a command of their own, that, when called, -will insert the skeleton. These commands can be issued in the usual ways -(@pxref{(emacs)Commands}). Modes that offer various skeletons will often -bind these to key-sequences on the @kbd{C-c} prefix, as well as having -an @cite{Insert} menu and maybe even predefined abbrevs for them -(@pxref{Skeletons as Abbrevs}). - - The simplest kind of skeleton will simply insert some text indented -according to the major mode and leave the cursor at a likely place in the -middle. Interactive skeletons may prompt you for a string that will be part -of the inserted text. - - Skeletons may ask for input several times. They even have a looping -mechanism in which you will be asked for input as long as you are willing to -furnish it. An example would be multiple ``else if'' conditions. You can -recognize this situation by a prompt ending in @key{RET}, @kbd{C-g} -or @kbd{C-h}. This -means that entering an empty string will simply assume that you are finished. -Typing quit on the other hand terminates the loop but also the rest of the -skeleton, e.g. an ``else'' clause is skipped. Only a syntactically necessary -termination still gets inserted. - - - -@node Wrapping Skeletons -@chapter Wrapping Skeletons Around Existing Text -@cindex wrapping skeletons - - Often you will find yourself with some code that for whatever reason -suddenly becomes conditional. Or you have written a bit of text and want to -put it in the middle of a form letter. Skeletons provide a means for -accomplishing this, and can even, in the case of programming languages, -reindent the wrapped code for you. - - Skeleton commands take an optional numeric prefix argument -(@pxref{(emacs)Arguments}). This is interpreted in two different ways depending -on whether the prefix is positive, i.e. forwards oriented or negative, -i.e. backwards oriented. - - A positive prefix means to wrap the skeleton around that many -following words. This is accomplished by putting the words there where -the point is normally left after that skeleton is inserted (@pxref{Using -Skeletons}). The point (@pxref{(emacs)Point}) is left at the next -interesting spot in the skeleton instead. - - A negative prefix means to do something similar with that many precedingly -marked interregions (@pxref{(emacs)Mark}). In the simplest case, if you type -@kbd{M--} just before issuing the skeleton command, that will wrap the -skeleton around the current region, just like a positive argument would have -wrapped it around a number of words. - - Smaller negative arguments will wrap that many interregions into successive -interesting spots within the skeleton, again leaving the point at the next one. -We speak about interregions rather than regions here, because we treat them in -the order they appear in the buffer, which coincides with successive regions -only if they were marked in order. - - That is, if you marked in alphabetical order the points A B C [] (where [] -represents the point) and call a skeleton command with @kbd{M-- 3}, you will -wrap the text from A to B into the first interesting spot of the skeleton, the -text from B to C into the next one, the text from C to the point into the -third one, and leave the point in the fourth one. If there are less marks in -the buffer, or if the skeleton defines less interesting points, the surplus is -ignored. - - If, on the other hand, you marked in alphabetical order the points [] A C B, -and call a skeleton command with @kbd{M-- 3}, you will wrap the text from -point to A, then the text from A to C and finally the text from C to B. This -is done because the regions overlap and Emacs would be helplessly lost if it -tried to follow the order in which you marked these points. - - - -@node Skeletons as Abbrevs -@chapter Skeletons as Abbrev Expansions -@cindex skeletons as abbrevs - - Rather than use a key binding for every skeleton command, you can also -define an abbreviation (@pxref{(emacs)Defining Abbrevs}) that will expand -(@pxref{(emacs)Expanding Abbrevs}) into the skeleton. - - Say you want @samp{ifst} to be an abbreviation for the C language if -statement. You will tell Emacs that @samp{ifst} expands to the empty string -and then calls the skeleton command. In Emacs Lisp you can say something like -@code{(define-abbrev c-mode-abbrev-table "ifst" "" 'c-if)}. Or you can edit -the output from @kbd{M-x list-abbrevs} to make it look like this: - -@example -(c-mode-abbrev-table) -"if" 0 "" c-if -@end example - -@noindent -(Some blank lines of no semantic significance, and other abbrev tables, -have been omitted.) - - - -@node Skeleton Language -@chapter Skeleton Language -@cindex skeleton language - -@findex skeleton-insert - Skeletons are an shorthand extension to the Lisp language, where various -atoms directly perform either actions on the current buffer or rudimentary -flow control mechanisms. Skeletons are interpreted by the function -@code{skeleton-insert}. - - A skeleton is a list starting with an interactor, which is usually a -prompt-string, or @code{nil} when not needed, but can also be a Lisp -expression for complex read functions or for returning some calculated value. -The rest of the list are any number of elements as described in the following -table: - -@table @asis -@item @code{"@var{string}"}, @code{?@var{c}}, @code{?\@var{c}} -@vindex skeleton-transformation -Insert string or character. Literal strings and characters are passed through -@code{skeleton-transformation} when that is non-@code{nil}. -@item @code{?\n} -@c ??? something seems very wrong here. -Insert a newline and align under current line. Use newline character -@code{?\n} to prevent alignment. -@item @code{_} -Interesting point. When wrapping skeletons around successive regions, they are -put at these places. Point is left at first @code{_} where nothing is wrapped. -@item @code{>} -Indent line according to major mode. When following element is @code{_}, and -there is a interregion that will be wrapped here, indent that interregion. -@item @code{&} -Logical and. Iff preceding element moved point, i.e. usually inserted -something, do following element. -@item @code{|} -Logical xor. Iff preceding element didn't move point, i.e. usually inserted -nothing, do following element. -@item @code{-@var{number}} -Delete preceding number characters. Depends on value of -@code{skeleton-untabify}. -@item @code{()} or @code{nil} -Ignored. -@item @var{lisp-expression} -Evaluated, and the return value is again interpreted as a skeleton element. -@item @code{str} -A special variable that, when evaluated the first time, usually prompts -for input according to the skeleton's interactor. It is then set to the -return value resulting from the interactor. Each subskeleton has its local -copy of this variable. -@item @code{v1}, @code{v2} -Skeleton-local user variables. -@item @code{'@var{expression}} -Evaluate following Lisp expression for its side-effect, but prevent it from -being interpreted as a skeleton element. -@item @var{skeleton} -Subskeletons are inserted recursively, not once, but as often as the user -enters something at the subskeletons interactor. Thus there must be a -@code{str} in the subskeleton. They can also be used non-interactively, when -prompt is a lisp-expression that returns successive list-elements. -@item @code{resume:} -Ignored. Execution resumes here if the user quits during skeleton -interpretation. -@item @code{quit} -A constant which is non-@code{nil} when the @code{resume:} section was entered -because the user quit. -@end table - -@findex skeleton-further-elements - Some modes also use other skeleton elements they themselves defined. For -example in shell script mode's skeletons you will find @code{<} which does a -rigid indentation backwards, or in CC mode's skeletons you find the -self-inserting elements @code{@{} and @code{@}}. These are defined by the -buffer-local variable @code{skeleton-further-elements} which is a list of -variables bound while interpreting a skeleton. - -@findex define-skeleton - The macro @code{define-skeleton} defines a command for interpreting a -skeleton. The first argument is the command name, the second is a -documentation string, and the rest is an interactor and any number of skeleton -elements together forming a skeleton. This skeleton is assigned to a variable -of the same name as the command and can thus be overridden from your -@file{~/.emacs} file (@pxref{(emacs)Init File}). - - - -@node Inserting Pairs -@chapter Inserting Matching Pairs of Characters -@cindex inserting pairs -@cindex pairs - - Various characters usually appear in pairs. When, for example, you insert -an open parenthesis, no matter whether you are programming or writing prose, -you will surely enter a closing one later. By entering both at the same time -and leaving the cursor inbetween, Emacs can guarantee you that such -parentheses are always balanced. And if you have a non-qwerty keyboard, where -typing some of the stranger programming language symbols makes you bend your -fingers backwards, this can be quite relieving too. - -@findex skeleton-pair-insert-maybe -@vindex skeleton-pair - This is done by binding the first key (@pxref{(emacs)Rebinding}) of -the pair to @code{skeleton-pair-insert-maybe} instead of -@code{self-insert-command}. The ``maybe'' comes from the fact that -this at-first surprising behavior is initially turned off. To enable -it, you must set @code{skeleton-pair} to some non-@code{nil} value. -And even then, a positive argument (@pxref{(emacs)Arguments}) will -make this key behave like a self-inserting key -(@pxref{(emacs)Inserting Text}). - -@vindex skeleton-pair-on-word - While this breaks with the stated intention of always balancing pairs, it -turns out that one often doesn't want pairing to occur, when the following -character is part of a word. If you want pairing to occur even then, set -@code{skeleton-pair-on-word} to some non-@code{nil} value. - -@vindex skeleton-pair-alist - Pairing is possible for all visible characters. By default the -parenthesis @samp{(}, the square bracket @samp{[}, the brace -@samp{@{}, the pointed bracket @samp{<} and the backquote @samp{`} all -pair with the symmetrical character. All other characters pair -themselves. This behavior can be modified by the variable -@code{skeleton-pair-alist}. This is in fact an alist of skeletons -(@pxref{Skeleton Language}), with the first part of each sublist -matching the typed character. This is the position of the interactor, -but since pairs don't need the @code{str} element, this is ignored. - - Some modes have bound the command @code{skeleton-pair-insert-maybe} -to relevant keys. These modes also configure the pairs as -appropriate. For example, when typing english prose, you'd expect the -backquote (@samp{`}) to pair with the quote (@samp{'}), while in Shell -script mode it must pair to itself. They can also inhibit pairing in -certain contexts. For example an escaped character stands for itself. - - - -@node Autoinserting -@chapter Autoinserting Text in Empty Files -@cindex autoinserting - -@findex auto-insert - @kbd{M-x auto-insert} will put some predefined text at the beginning of -the buffer. The main application for this function, as its name suggests, -is to have it be called automatically every time an empty, and only an -empty file is visited. This is accomplished by putting @code{(add-hook -'find-file-hook 'auto-insert)} into your @file{~/.emacs} file -(@pxref{(emacs)Init File}). - -@vindex auto-insert-alist - What gets inserted, if anything, is determined by the variable -@code{auto-insert-alist}. The @sc{car}s of this list are each either -a mode name, making an element applicable when a buffer is in that -mode. Or they can be a string, which is a regexp matched against the -buffer's file name. In that way different kinds of files that have -the same mode in Emacs can be distinguished. The @sc{car}s may also -be cons cells consisting of mode name or regexp as above and an -additional descriptive string. - - When a matching element is found, the @sc{cdr} says what to do. It may -be a string, which is a file name, whose contents are to be inserted, if -that file is found in the directory @code{auto-insert-directory} or under a -absolute file name. Or it can be a skeleton (@pxref{Skeleton Language}) to -be inserted. - - It can also be a function, which allows doing various things. The function -can simply insert some text, indeed, it can be skeleton command (@pxref{Using -Skeletons}). It can be a lambda function which will for example conditionally -call another function. Or it can even reset the mode for the buffer. If you -want to perform several such actions in order, you use a vector, i.e. several -of the above elements between square brackets (@samp{[@r{@dots{}}]}). - - By default C and C++ headers insert a definition of a symbol derived from -the filename to prevent multiple inclusions. C and C++ sources insert an -include of the header. Makefiles insert the file makefile.inc if it exists. - - TeX and bibTeX mode files insert the file tex-insert.tex if it exists, while -LaTeX mode files insert a typical @code{\documentclass} frame. Html -files insert a skeleton with the usual frame. - - Ada mode files call the Ada header skeleton command. Emacs lisp -source files insert the usual header, with a copyright of your -environment variable @env{$ORGANIZATION} or else the FSF, and prompt -for valid keywords describing the contents. Files in a @file{bin} -directory for which Emacs could determine no specialized mode -(@pxref{(emacs)Choosing Modes}) are set to Shell script mode. - -@findex define-auto-insert - In Lisp (@pxref{(emacs)Init File}) you can use the function -@code{define-auto-insert} to add to or modify -@code{auto-insert-alist}. See its documentation with @kbd{C-h f -define-auto-insert}. - -@vindex auto-insert - The variable @code{auto-insert} says what to do when @code{auto-insert} is -called non-interactively, e.g. when a newly found file is empty (see above): -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert something if possible, i.e. there is a matching entry in -@code{auto-insert-alist}. -@item other -Insert something if possible, but mark as unmodified. -@end table - -@vindex auto-insert-query - The variable @code{auto-insert-query} controls whether to ask about -inserting something. When this is @code{nil}, inserting is only done with -@kbd{M-x auto-insert}. When this is @code{function}, you are queried -whenever @code{auto-insert} is called as a function, such as when Emacs -visits an empty file and you have set the above-mentioned hook. Otherwise -you are alway queried. - -@vindex auto-insert-prompt - When querying, the variable @code{auto-insert-prompt}'s value is used as a -prompt for a y-or-n-type question. If this includes a @samp{%s} construct, -that is replaced by what caused the insertion rule to be chosen. This is -either a descriptive text, the mode-name of the buffer or the regular -expression that matched the filename. - - - -@node Copyrights -@chapter Inserting and Updating Copyrights -@cindex copyrights - -@findex copyright - @kbd{M-x copyright} is a skeleton inserting command, that adds a copyright -notice at the point. The ``by'' part is taken from your environment variable -@env{$ORGANIZATION} or if that isn't set you are prompted for it. If the -buffer has a comment syntax (@pxref{(emacs)Comments}), this is inserted as a comment. - -@findex copyright-update -@vindex copyright-limit -@vindex copyright-current-year - @kbd{M-x copyright-update} looks for a copyright notice in the first -@code{copyright-limit} characters of the buffer and updates it when necessary. -The current year (variable @code{copyright-current-year}) is added to the -existing ones, in the same format as the preceding year, i.e. 1994, '94 or 94. -If a dash-separated year list up to last year is found, that is extended to -current year, else the year is added separated by a comma. Or it replaces -them when this is called with a prefix argument. If a header referring to a -wrong version of the GNU General Public License (@pxref{(emacs)Copying}) is found, -that is updated too. - - An interesting application for this function is to have it be called -automatically every time a file is saved. This is accomplished by -putting @code{(add-hook 'before-save-hook 'copyright-update)} into -your @file{~/.emacs} file (@pxref{(emacs)Init File}). Alternative, -you can do @kbd{M-x customize-variable @key{RET} before-save-hook -@key{RET}}. @code{copyright-update} is conveniently listed as an -option in the customization buffer. - -@vindex copyright-query - The variable @code{copyright-query} controls whether to update the -copyright or whether to ask about it. When this is @code{nil} updating is -only done with @kbd{M-x copyright-update}. When this is @code{function} -you are queried whenever @code{copyright-update} is called as a function, -such as in the @code{before-save-hook} feature mentioned above. Otherwise -you are always queried. - - - -@node Executables -@chapter Making Interpreter Scripts Executable -@cindex executables - -@vindex executable-prefix -@vindex executable-chmod - Various interpreter modes such as Shell script mode or AWK mode will -automatically insert or update the buffer's magic number, a special -comment on the first line that makes the @code{exec} systemcall know -how to execute the script. To this end the script is automatically -made executable upon saving, with @code{executable-chmod} as argument -to the system @code{chmod} command. The magic number is prefixed by -the value of @code{executable-prefix}. - -@vindex executable-magicless-file-regexp - Any file whose name matches @code{executable-magicless-file-regexp} is not -furnished with a magic number, nor is it made executable. This is mainly -intended for resource files, which are only meant to be read in. - -@vindex executable-insert - The variable @code{executable-insert} says what to do when -@code{executable-set-magic} is called non-interactively, e.g. when file has no -or the wrong magic number: -@table @asis -@item @code{nil} -Do nothing. -@item @code{t} -Insert or update magic number. -@item other -Insert or update magic number, but mark as unmodified. -@end table - -@findex executable-set-magic -@vindex executable-query - The variable @code{executable-query} controls whether to ask about -inserting or updating the magic number. When this is @code{nil} updating -is only done with @kbd{M-x executable-set-magic}. When this is -@code{function} you are queried whenever @code{executable-set-magic} is -called as a function, such as when Emacs puts a buffer in Shell script -mode. Otherwise you are alway queried. - -@findex executable-self-display - @kbd{M-x executable-self-display} adds a magic number to the buffer, which -will turn it into a self displaying text file, when called as a Un*x command. -The ``interpreter'' used is @code{executable-self-display} with argument -@samp{+2}. - -@node Timestamps -@chapter Maintaining Timestamps in Modified Files -@cindex timestamps - -@findex time-stamp -@vindex before-save-hook -The @code{time-stamp} command can be used to update automatically a -template in a file with a new time stamp every time you save the file. -Customize the hook @code{before-save-hook} to add the function -@code{time-stamp} to arrange this. It you use Custom to do this, -then @code{time-stamp} is conveniently listed as an option in the -customization buffer. - -@vindex time-stamp-active -@vindex time-stamp-format -@vindex time-stamp-start -The time stamp is updated only if the customizable variable -@code{time-stamp-active} is on, which it is by default; the command -@code{time-stamp-toggle-active} can be used to toggle it. The format of -the time stamp is set by the customizable variable -@code{time-stamp-format}. - -@vindex time-stamp-line-limit -@vindex time-stamp-end -@vindex time-stamp-count -@vindex time-stamp-inserts-lines -The variables @code{time-stamp-line-limit}, @code{time-stamp-start}, -@code{time-stamp-end}, @code{time-stamp-count}, and -@code{time-stamp-inserts-lines} control finding the template. Do not -change these in your init file or you will be incompatible with other -people's files. If you must change them, do so only in the local -variables section of the file itself. - -Normally the template must appear in the first 8 lines of a file and -look like one of the following: - -@example -Time-stamp: <> -Time-stamp: " " -@end example - -The time stamp is written between the brackets or quotes: - -@example -Time-stamp: <1998-02-18 10:20:51 gildea> -@end example - -@node QuickURL -@chapter QuickURL: Inserting URLs Based on Text at Point - -@vindex quickurl-url-file -@findex quickurl -@cindex URLs -@kbd{M-x quickurl} can be used to insert a URL into a buffer based on -the text at point. The URLs are stored in an external file defined by -the variable @code{quickurl-url-file} as a list of either cons cells of -the form @code{(@var{key} . @var{URL})} or -lists of the form @code{(@var{key} @var{URL} @var{comment})}. These -specify that @kbd{M-x quickurl} should insert @var{URL} if the word -@var{key} is at point, for example: - -@example -(("FSF" "http://www.fsf.org/" "The Free Software Foundation") - ("emacs" . "http://www.emacs.org/") - ("hagbard" "http://www.hagbard.demon.co.uk" "Hagbard's World")) -@end example - -@findex quickurl-add-url -@findex quickurl-list -@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} -pair. @kbd{M-x quickurl-list} provides interactive editing of the URL -list. - -@node Tempo -@chapter Tempo: Flexible Template Insertion - -@cindex templates -The Tempo package provides a simple way to define powerful templates, or -macros, if you wish. It is mainly intended for, but not limited to, -programmers to be used for creating shortcuts for editing -certain kinds of documents. - -@findex tempo-backward-mark -@findex tempo-forward-mark -A template is defined as a list of items to be inserted in the current -buffer at point. Some can be simple strings, while others can control -formatting or define special points of interest in the inserted text. -@kbd{M-x tempo-backward-mark} and @kbd{M-x tempo-forward-mark} can be -used to jump between such points. - -More flexible templates can be created by including Lisp symbols, which -will be evaluated as variables, or lists, which will be evaluated -as Lisp expressions. Automatic completion of specified tags to expanded -templates can be provided. - -@findex tempo-define-template -See the documentation for @code{tempo-define-template} for the different -items that can be used to define a tempo template with a command for -inserting it. - -See the commentary in @file{tempo.el} for more information on using the -Tempo package. - -@node Hippie Expand -@chapter `Hippie' Expansion - -@findex hippie-expand -@kindex M-/ -@vindex hippie-expand-try-functions-list -@kbd{M-x hippie-expand} is a single command providing a variety of -completions and expansions. Called repeatedly, it tries all possible -completions in succession. - -Which ones to try, and in which order, is determined by the contents of -the customizable option @code{hippie-expand-try-functions-list}. Much -customization of the expansion behavior can be made by changing the -order of, removing, or inserting new functions in this list. Given a -positive numeric argument, @kbd{M-x hippie-expand} jumps directly that -number of functions forward in this list. Given some other argument (a -negative argument or just @kbd{C-u}) it undoes the tried completion. - -See the commentary in @file{hippie-exp.el} for more information on the -possibilities. - -Typically you would bind @code{hippie-expand} to @kbd{M-/} with -@code{dabbrev-expand}, the standard binding of @kbd{M-/}, providing one -of the expansion possibilities. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Command Index -@unnumbered Command Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@ignore - arch-tag: 54001b27-5ef8-4a9d-a199-905d650fafba -@end ignore diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi deleted file mode 100644 index 0475ee27fc6..00000000000 --- a/doc/misc/calc.texi +++ /dev/null @@ -1,36383 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header (This is for running Texinfo on a region.) -@c smallbook -@setfilename ../../info/calc -@c [title] -@settitle GNU Emacs Calc Manual -@setchapternewpage odd -@comment %**end of header (This is for running Texinfo on a region.) - -@c The following macros are used for conditional output for single lines. -@c @texline foo -@c `foo' will appear only in TeX output -@c @infoline foo -@c `foo' will appear only in non-TeX output - -@c @expr{expr} will typeset an expression; -@c $x$ in TeX, @samp{x} otherwise. - -@iftex -@macro texline -@end macro -@alias infoline=comment -@alias expr=math -@alias tfn=code -@alias mathit=expr -@alias summarykey=key -@macro cpi{} -@math{@pi{}} -@end macro -@macro cpiover{den} -@math{@pi/\den\} -@end macro -@end iftex - -@ifnottex -@alias texline=comment -@macro infoline{stuff} -\stuff\ -@end macro -@alias expr=samp -@alias tfn=t -@alias mathit=i -@macro summarykey{ky} -\ky\ -@end macro -@macro cpi{} -@expr{pi} -@end macro -@macro cpiover{den} -@expr{pi/\den\} -@end macro -@end ifnottex - - -@tex -% Suggested by Karl Berry -\gdef\!{\mskip-\thinmuskip} -@end tex - -@c Fix some other things specifically for this manual. -@iftex -@finalout -@mathcode`@:=`@: @c Make Calc fractions come out right in math mode -@tex -\gdef\coloneq{\mathrel{\mathord:\mathord=}} - -\gdef\beforedisplay{\vskip-10pt} -\gdef\afterdisplay{\vskip-5pt} -\gdef\beforedisplayh{\vskip-25pt} -\gdef\afterdisplayh{\vskip-10pt} -@end tex -@newdimen@kyvpos @kyvpos=0pt -@newdimen@kyhpos @kyhpos=0pt -@newcount@calcclubpenalty @calcclubpenalty=1000 -@ignore -@newcount@calcpageno -@newtoks@calcoldeverypar @calcoldeverypar=@everypar -@everypar={@calceverypar@the@calcoldeverypar} -@ifx@turnoffactive@undefinedzzz@def@turnoffactive{}@fi -@ifx@ninett@undefinedzzz@font@ninett=cmtt9@fi -@catcode`@\=0 \catcode`\@=11 -\r@ggedbottomtrue -\catcode`\@=0 @catcode`@\=@active -@end ignore -@end iftex - -@copying -@ifinfo -This file documents Calc, the GNU Emacs calculator. -@end ifinfo -@ifnotinfo -This file documents Calc, the GNU Emacs calculator, included with GNU Emacs 23.1. -@end ifnotinfo - -Copyright @copyright{} 1990, 1991, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with the -Invariant Sections being just ``GNU GENERAL PUBLIC LICENSE'', with the -Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover -Texts as in (a) below. A copy of the license is included in the section -entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Calc: (calc). Advanced desk calculator and mathematical tool. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Calc Manual} -@sp 4 -@center GNU Emacs Calc -@c [volume] -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@summarycontents - -@c [end] - -@contents - -@c [begin] -@ifnottex -@node Top, Getting Started, (dir), (dir) -@chapter The GNU Emacs Calculator - -@noindent -@dfn{Calc} is an advanced desk calculator and mathematical tool -written by Dave Gillespie that runs as part of the GNU Emacs environment. - -This manual, also written (mostly) by Dave Gillespie, is divided into -three major parts: ``Getting Started,'' the ``Calc Tutorial,'' and the -``Calc Reference.'' The Tutorial introduces all the major aspects of -Calculator use in an easy, hands-on way. The remainder of the manual is -a complete reference to the features of the Calculator. -@end ifnottex - -@ifinfo -For help in the Emacs Info system (which you are using to read this -file), type @kbd{?}. (You can also type @kbd{h} to run through a -longer Info tutorial.) -@end ifinfo - -@insertcopying - -@menu -* Getting Started:: General description and overview. -@ifinfo -* Interactive Tutorial:: -@end ifinfo -* Tutorial:: A step-by-step introduction for beginners. - -* Introduction:: Introduction to the Calc reference manual. -* Data Types:: Types of objects manipulated by Calc. -* Stack and Trail:: Manipulating the stack and trail buffers. -* Mode Settings:: Adjusting display format and other modes. -* Arithmetic:: Basic arithmetic functions. -* Scientific Functions:: Transcendentals and other scientific functions. -* Matrix Functions:: Operations on vectors and matrices. -* Algebra:: Manipulating expressions algebraically. -* Units:: Operations on numbers with units. -* Store and Recall:: Storing and recalling variables. -* Graphics:: Commands for making graphs of data. -* Kill and Yank:: Moving data into and out of Calc. -* Keypad Mode:: Operating Calc from a keypad. -* Embedded Mode:: Working with formulas embedded in a file. -* Programming:: Calc as a programmable calculator. - -* Copying:: How you can copy and share Calc. -* GNU Free Documentation License:: The license for this documentation. -* Customizing Calc:: Customizing Calc. -* Reporting Bugs:: How to report bugs and make suggestions. - -* Summary:: Summary of Calc commands and functions. - -* Key Index:: The standard Calc key sequences. -* Command Index:: The interactive Calc commands. -* Function Index:: Functions (in algebraic formulas). -* Concept Index:: General concepts. -* Variable Index:: Variables used by Calc (both user and internal). -* Lisp Function Index:: Internal Lisp math functions. -@end menu - -@ifinfo -@node Getting Started, Interactive Tutorial, Top, Top -@end ifinfo -@ifnotinfo -@node Getting Started, Tutorial, Top, Top -@end ifnotinfo -@chapter Getting Started -@noindent -This chapter provides a general overview of Calc, the GNU Emacs -Calculator: What it is, how to start it and how to exit from it, -and what are the various ways that it can be used. - -@menu -* What is Calc:: -* About This Manual:: -* Notations Used in This Manual:: -* Demonstration of Calc:: -* Using Calc:: -* History and Acknowledgements:: -@end menu - -@node What is Calc, About This Manual, Getting Started, Getting Started -@section What is Calc? - -@noindent -@dfn{Calc} is an advanced calculator and mathematical tool that runs as -part of the GNU Emacs environment. Very roughly based on the HP-28/48 -series of calculators, its many features include: - -@itemize @bullet -@item -Choice of algebraic or RPN (stack-based) entry of calculations. - -@item -Arbitrary precision integers and floating-point numbers. - -@item -Arithmetic on rational numbers, complex numbers (rectangular and polar), -error forms with standard deviations, open and closed intervals, vectors -and matrices, dates and times, infinities, sets, quantities with units, -and algebraic formulas. - -@item -Mathematical operations such as logarithms and trigonometric functions. - -@item -Programmer's features (bitwise operations, non-decimal numbers). - -@item -Financial functions such as future value and internal rate of return. - -@item -Number theoretical features such as prime factorization and arithmetic -modulo @var{m} for any @var{m}. - -@item -Algebraic manipulation features, including symbolic calculus. - -@item -Moving data to and from regular editing buffers. - -@item -Embedded mode for manipulating Calc formulas and data directly -inside any editing buffer. - -@item -Graphics using GNUPLOT, a versatile (and free) plotting program. - -@item -Easy programming using keyboard macros, algebraic formulas, -algebraic rewrite rules, or extended Emacs Lisp. -@end itemize - -Calc tries to include a little something for everyone; as a result it is -large and might be intimidating to the first-time user. If you plan to -use Calc only as a traditional desk calculator, all you really need to -read is the ``Getting Started'' chapter of this manual and possibly the -first few sections of the tutorial. As you become more comfortable with -the program you can learn its additional features. Calc does not -have the scope and depth of a fully-functional symbolic math package, -but Calc has the advantages of convenience, portability, and freedom. - -@node About This Manual, Notations Used in This Manual, What is Calc, Getting Started -@section About This Manual - -@noindent -This document serves as a complete description of the GNU Emacs -Calculator. It works both as an introduction for novices and as -a reference for experienced users. While it helps to have some -experience with GNU Emacs in order to get the most out of Calc, -this manual ought to be readable even if you don't know or use Emacs -regularly. - -This manual is divided into three major parts:@: the ``Getting -Started'' chapter you are reading now, the Calc tutorial, and the Calc -reference manual. -@c [when-split] -@c This manual has been printed in two volumes, the @dfn{Tutorial} and the -@c @dfn{Reference}. Both volumes include a copy of the ``Getting Started'' -@c chapter. - -If you are in a hurry to use Calc, there is a brief ``demonstration'' -below which illustrates the major features of Calc in just a couple of -pages. If you don't have time to go through the full tutorial, this -will show you everything you need to know to begin. -@xref{Demonstration of Calc}. - -The tutorial chapter walks you through the various parts of Calc -with lots of hands-on examples and explanations. If you are new -to Calc and you have some time, try going through at least the -beginning of the tutorial. The tutorial includes about 70 exercises -with answers. These exercises give you some guided practice with -Calc, as well as pointing out some interesting and unusual ways -to use its features. - -The reference section discusses Calc in complete depth. You can read -the reference from start to finish if you want to learn every aspect -of Calc. Or, you can look in the table of contents or the Concept -Index to find the parts of the manual that discuss the things you -need to know. - -@c @cindex Marginal notes -Every Calc keyboard command is listed in the Calc Summary, and also -in the Key Index. Algebraic functions, @kbd{M-x} commands, and -variables also have their own indices. -@c @texline Each -@c @infoline In the printed manual, each -@c paragraph that is referenced in the Key or Function Index is marked -@c in the margin with its index entry. - -@c [fix-ref Help Commands] -You can access this manual on-line at any time within Calc by pressing -the @kbd{h i} key sequence. Outside of the Calc window, you can press -@kbd{C-x * i} to read the manual on-line. From within Calc the command -@kbd{h t} will jump directly to the Tutorial; from outside of Calc the -command @kbd{C-x * t} will jump to the Tutorial and start Calc if -necessary. Pressing @kbd{h s} or @kbd{C-x * s} will take you directly -to the Calc Summary. Within Calc, you can also go to the part of the -manual describing any Calc key, function, or variable using -@w{@kbd{h k}}, @kbd{h f}, or @kbd{h v}, respectively. @xref{Help Commands}. - -@ifnottex -The Calc manual can be printed, but because the manual is so large, you -should only make a printed copy if you really need it. To print the -manual, you will need the @TeX{} typesetting program (this is a free -program by Donald Knuth at Stanford University) as well as the -@file{texindex} program and @file{texinfo.tex} file, both of which can -be obtained from the FSF as part of the @code{texinfo} package. -To print the Calc manual in one huge tome, you will need the -source code to this manual, @file{calc.texi}, available as part of the -Emacs source. Once you have this file, type @kbd{texi2dvi calc.texi}. -Alternatively, change to the @file{man} subdirectory of the Emacs -source distribution, and type @kbd{make calc.dvi}. (Don't worry if you -get some ``overfull box'' warnings while @TeX{} runs.) -The result will be a device-independent output file called -@file{calc.dvi}, which you must print in whatever way is right -for your system. On many systems, the command is - -@example -lpr -d calc.dvi -@end example - -@noindent -or - -@example -dvips calc.dvi -@end example -@end ifnottex -@c Printed copies of this manual are also available from the Free Software -@c Foundation. - -@node Notations Used in This Manual, Demonstration of Calc, About This Manual, Getting Started -@section Notations Used in This Manual - -@noindent -This section describes the various notations that are used -throughout the Calc manual. - -In keystroke sequences, uppercase letters mean you must hold down -the shift key while typing the letter. Keys pressed with Control -held down are shown as @kbd{C-x}. Keys pressed with Meta held down -are shown as @kbd{M-x}. Other notations are @key{RET} for the -Return key, @key{SPC} for the space bar, @key{TAB} for the Tab key, -@key{DEL} for the Delete key, and @key{LFD} for the Line-Feed key. -The @key{DEL} key is called Backspace on some keyboards, it is -whatever key you would use to correct a simple typing error when -regularly using Emacs. - -(If you don't have the @key{LFD} or @key{TAB} keys on your keyboard, -the @kbd{C-j} and @kbd{C-i} keys are equivalent to them, respectively. -If you don't have a Meta key, look for Alt or Extend Char. You can -also press @key{ESC} or @kbd{C-[} first to get the same effect, so -that @kbd{M-x}, @kbd{@key{ESC} x}, and @kbd{C-[ x} are all equivalent.) - -Sometimes the @key{RET} key is not shown when it is ``obvious'' -that you must press @key{RET} to proceed. For example, the @key{RET} -is usually omitted in key sequences like @kbd{M-x calc-keypad @key{RET}}. - -Commands are generally shown like this: @kbd{p} (@code{calc-precision}) -or @kbd{C-x * k} (@code{calc-keypad}). This means that the command is -normally used by pressing the @kbd{p} key or @kbd{C-x * k} key sequence, -but it also has the full-name equivalent shown, e.g., @kbd{M-x calc-precision}. - -Commands that correspond to functions in algebraic notation -are written: @kbd{C} (@code{calc-cos}) [@code{cos}]. This means -the @kbd{C} key is equivalent to @kbd{M-x calc-cos}, and that -the corresponding function in an algebraic-style formula would -be @samp{cos(@var{x})}. - -A few commands don't have key equivalents: @code{calc-sincos} -[@code{sincos}]. - -@node Demonstration of Calc, Using Calc, Notations Used in This Manual, Getting Started -@section A Demonstration of Calc - -@noindent -@cindex Demonstration of Calc -This section will show some typical small problems being solved with -Calc. The focus is more on demonstration than explanation, but -everything you see here will be covered more thoroughly in the -Tutorial. - -To begin, start Emacs if necessary (usually the command @code{emacs} -does this), and type @kbd{C-x * c} to start the -Calculator. (You can also use @kbd{M-x calc} if this doesn't work. -@xref{Starting Calc}, for various ways of starting the Calculator.) - -Be sure to type all the sample input exactly, especially noting the -difference between lower-case and upper-case letters. Remember, -@key{RET}, @key{TAB}, @key{DEL}, and @key{SPC} are the Return, Tab, -Delete, and Space keys. - -@strong{RPN calculation.} In RPN, you type the input number(s) first, -then the command to operate on the numbers. - -@noindent -Type @kbd{2 @key{RET} 3 + Q} to compute -@texline @math{\sqrt{2+3} = 2.2360679775}. -@infoline the square root of 2+3, which is 2.2360679775. - -@noindent -Type @kbd{P 2 ^} to compute -@texline @math{\pi^2 = 9.86960440109}. -@infoline the value of `pi' squared, 9.86960440109. - -@noindent -Type @key{TAB} to exchange the order of these two results. - -@noindent -Type @kbd{- I H S} to subtract these results and compute the Inverse -Hyperbolic sine of the difference, 2.72996136574. - -@noindent -Type @key{DEL} to erase this result. - -@strong{Algebraic calculation.} You can also enter calculations using -conventional ``algebraic'' notation. To enter an algebraic formula, -use the apostrophe key. - -@noindent -Type @kbd{' sqrt(2+3) @key{RET}} to compute -@texline @math{\sqrt{2+3}}. -@infoline the square root of 2+3. - -@noindent -Type @kbd{' pi^2 @key{RET}} to enter -@texline @math{\pi^2}. -@infoline `pi' squared. -To evaluate this symbolic formula as a number, type @kbd{=}. - -@noindent -Type @kbd{' arcsinh($ - $$) @key{RET}} to subtract the second-most-recent -result from the most-recent and compute the Inverse Hyperbolic sine. - -@strong{Keypad mode.} If you are using the X window system, press -@w{@kbd{C-x * k}} to get Keypad mode. (If you don't use X, skip to -the next section.) - -@noindent -Click on the @key{2}, @key{ENTER}, @key{3}, @key{+}, and @key{SQRT} -``buttons'' using your left mouse button. - -@noindent -Click on @key{PI}, @key{2}, and @tfn{y^x}. - -@noindent -Click on @key{INV}, then @key{ENTER} to swap the two results. - -@noindent -Click on @key{-}, @key{INV}, @key{HYP}, and @key{SIN}. - -@noindent -Click on @key{<-} to erase the result, then click @key{OFF} to turn -the Keypad Calculator off. - -@strong{Grabbing data.} Type @kbd{C-x * x} if necessary to exit Calc. -Now select the following numbers as an Emacs region: ``Mark'' the -front of the list by typing @kbd{C-@key{SPC}} or @kbd{C-@@} there, -then move to the other end of the list. (Either get this list from -the on-line copy of this manual, accessed by @w{@kbd{C-x * i}}, or just -type these numbers into a scratch file.) Now type @kbd{C-x * g} to -``grab'' these numbers into Calc. - -@example -@group -1.23 1.97 -1.6 2 -1.19 1.08 -@end group -@end example - -@noindent -The result @samp{[1.23, 1.97, 1.6, 2, 1.19, 1.08]} is a Calc ``vector.'' -Type @w{@kbd{V R +}} to compute the sum of these numbers. - -@noindent -Type @kbd{U} to Undo this command, then type @kbd{V R *} to compute -the product of the numbers. - -@noindent -You can also grab data as a rectangular matrix. Place the cursor on -the upper-leftmost @samp{1} and set the mark, then move to just after -the lower-right @samp{8} and press @kbd{C-x * r}. - -@noindent -Type @kbd{v t} to transpose this -@texline @math{3\times2} -@infoline 3x2 -matrix into a -@texline @math{2\times3} -@infoline 2x3 -matrix. Type @w{@kbd{v u}} to unpack the rows into two separate -vectors. Now type @w{@kbd{V R + @key{TAB} V R +}} to compute the sums -of the two original columns. (There is also a special -grab-and-sum-columns command, @kbd{C-x * :}.) - -@strong{Units conversion.} Units are entered algebraically. -Type @w{@kbd{' 43 mi/hr @key{RET}}} to enter the quantity 43 miles-per-hour. -Type @w{@kbd{u c km/hr @key{RET}}}. Type @w{@kbd{u c m/s @key{RET}}}. - -@strong{Date arithmetic.} Type @kbd{t N} to get the current date and -time. Type @kbd{90 +} to find the date 90 days from now. Type -@kbd{' <25 dec 87> @key{RET}} to enter a date, then @kbd{- 7 /} to see how -many weeks have passed since then. - -@strong{Algebra.} Algebraic entries can also include formulas -or equations involving variables. Type @kbd{@w{' [x + y} = a, x y = 1] @key{RET}} -to enter a pair of equations involving three variables. -(Note the leading apostrophe in this example; also, note that the space -in @samp{x y} is required.) Type @w{@kbd{a S x,y @key{RET}}} to solve -these equations for the variables @expr{x} and @expr{y}. - -@noindent -Type @kbd{d B} to view the solutions in more readable notation. -Type @w{@kbd{d C}} to view them in C language notation, @kbd{d T} -to view them in the notation for the @TeX{} typesetting system, -and @kbd{d L} to view them in the notation for the La@TeX{} typesetting -system. Type @kbd{d N} to return to normal notation. - -@noindent -Type @kbd{7.5}, then @kbd{s l a @key{RET}} to let @expr{a = 7.5} in these formulas. -(That's the letter @kbd{l}, not the numeral @kbd{1}.) - -@ifnotinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Type @kbd{C-x * c} to return to Calc after each of these -commands: @kbd{h k t N} to read about the @kbd{t N} command, -@kbd{h f sqrt @key{RET}} to read about the @code{sqrt} function, and -@kbd{h s} to read the Calc summary. -@end ifnotinfo -@ifinfo -@strong{Help functions.} You can read about any command in the on-line -manual. Remember to type the letter @kbd{l}, then @kbd{C-x * c}, to -return here after each of these commands: @w{@kbd{h k t N}} to read -about the @w{@kbd{t N}} command, @kbd{h f sqrt @key{RET}} to read about the -@code{sqrt} function, and @kbd{h s} to read the Calc summary. -@end ifinfo - -Press @key{DEL} repeatedly to remove any leftover results from the stack. -To exit from Calc, press @kbd{q} or @kbd{C-x * c} again. - -@node Using Calc, History and Acknowledgements, Demonstration of Calc, Getting Started -@section Using Calc - -@noindent -Calc has several user interfaces that are specialized for -different kinds of tasks. As well as Calc's standard interface, -there are Quick mode, Keypad mode, and Embedded mode. - -@menu -* Starting Calc:: -* The Standard Interface:: -* Quick Mode Overview:: -* Keypad Mode Overview:: -* Standalone Operation:: -* Embedded Mode Overview:: -* Other C-x * Commands:: -@end menu - -@node Starting Calc, The Standard Interface, Using Calc, Using Calc -@subsection Starting Calc - -@noindent -On most systems, you can type @kbd{C-x *} to start the Calculator. -The key sequence @kbd{C-x *} is bound to the command @code{calc-dispatch}, -which can be rebound if convenient (@pxref{Customizing Calc}). - -When you press @kbd{C-x *}, Emacs waits for you to press a second key to -complete the command. In this case, you will follow @kbd{C-x *} with a -letter (upper- or lower-case, it doesn't matter for @kbd{C-x *}) that says -which Calc interface you want to use. - -To get Calc's standard interface, type @kbd{C-x * c}. To get -Keypad mode, type @kbd{C-x * k}. Type @kbd{C-x * ?} to get a brief -list of the available options, and type a second @kbd{?} to get -a complete list. - -To ease typing, @kbd{C-x * *} also works to start Calc. It starts the -same interface (either @kbd{C-x * c} or @w{@kbd{C-x * k}}) that you last -used, selecting the @kbd{C-x * c} interface by default. - -If @kbd{C-x *} doesn't work for you, you can always type explicit -commands like @kbd{M-x calc} (for the standard user interface) or -@w{@kbd{M-x calc-keypad}} (for Keypad mode). First type @kbd{M-x} -(that's Meta with the letter @kbd{x}), then, at the prompt, -type the full command (like @kbd{calc-keypad}) and press Return. - -The same commands (like @kbd{C-x * c} or @kbd{C-x * *}) that start -the Calculator also turn it off if it is already on. - -@node The Standard Interface, Quick Mode Overview, Starting Calc, Using Calc -@subsection The Standard Calc Interface - -@noindent -@cindex Standard user interface -Calc's standard interface acts like a traditional RPN calculator, -operated by the normal Emacs keyboard. When you type @kbd{C-x * c} -to start the Calculator, the Emacs screen splits into two windows -with the file you were editing on top and Calc on the bottom. - -@smallexample -@group - -... ---**-Emacs: myfile (Fundamental)----All---------------------- ---- Emacs Calculator Mode --- |Emacs Calculator Trail -2: 17.3 | 17.3 -1: -5 | 3 - . | 2 - | 4 - | * 8 - | ->-5 - | ---%*-Calc: 12 Deg (Calculator)----All----- --%*- *Calc Trail* -@end group -@end smallexample - -In this figure, the mode-line for @file{myfile} has moved up and the -``Calculator'' window has appeared below it. As you can see, Calc -actually makes two windows side-by-side. The lefthand one is -called the @dfn{stack window} and the righthand one is called the -@dfn{trail window.} The stack holds the numbers involved in the -calculation you are currently performing. The trail holds a complete -record of all calculations you have done. In a desk calculator with -a printer, the trail corresponds to the paper tape that records what -you do. - -In this case, the trail shows that four numbers (17.3, 3, 2, and 4) -were first entered into the Calculator, then the 2 and 4 were -multiplied to get 8, then the 3 and 8 were subtracted to get @mathit{-5}. -(The @samp{>} symbol shows that this was the most recent calculation.) -The net result is the two numbers 17.3 and @mathit{-5} sitting on the stack. - -Most Calculator commands deal explicitly with the stack only, but -there is a set of commands that allow you to search back through -the trail and retrieve any previous result. - -Calc commands use the digits, letters, and punctuation keys. -Shifted (i.e., upper-case) letters are different from lowercase -letters. Some letters are @dfn{prefix} keys that begin two-letter -commands. For example, @kbd{e} means ``enter exponent'' and shifted -@kbd{E} means @expr{e^x}. With the @kbd{d} (``display modes'') prefix -the letter ``e'' takes on very different meanings: @kbd{d e} means -``engineering notation'' and @kbd{d E} means ``@dfn{eqn} language mode.'' - -There is nothing stopping you from switching out of the Calc -window and back into your editing window, say by using the Emacs -@w{@kbd{C-x o}} (@code{other-window}) command. When the cursor is -inside a regular window, Emacs acts just like normal. When the -cursor is in the Calc stack or trail windows, keys are interpreted -as Calc commands. - -When you quit by pressing @kbd{C-x * c} a second time, the Calculator -windows go away but the actual Stack and Trail are not gone, just -hidden. When you press @kbd{C-x * c} once again you will get the -same stack and trail contents you had when you last used the -Calculator. - -The Calculator does not remember its state between Emacs sessions. -Thus if you quit Emacs and start it again, @kbd{C-x * c} will give you -a fresh stack and trail. There is a command (@kbd{m m}) that lets -you save your favorite mode settings between sessions, though. -One of the things it saves is which user interface (standard or -Keypad) you last used; otherwise, a freshly started Emacs will -always treat @kbd{C-x * *} the same as @kbd{C-x * c}. - -The @kbd{q} key is another equivalent way to turn the Calculator off. - -If you type @kbd{C-x * b} first and then @kbd{C-x * c}, you get a -full-screen version of Calc (@code{full-calc}) in which the stack and -trail windows are still side-by-side but are now as tall as the whole -Emacs screen. When you press @kbd{q} or @kbd{C-x * c} again to quit, -the file you were editing before reappears. The @kbd{C-x * b} key -switches back and forth between ``big'' full-screen mode and the -normal partial-screen mode. - -Finally, @kbd{C-x * o} (@code{calc-other-window}) is like @kbd{C-x * c} -except that the Calc window is not selected. The buffer you were -editing before remains selected instead. If you are in a Calc window, -then @kbd{C-x * o} will switch you out of it, being careful not to -switch you to the Calc Trail window. So @kbd{C-x * o} is a handy -way to switch out of Calc momentarily to edit your file; you can then -type @kbd{C-x * c} to switch back into Calc when you are done. - -@node Quick Mode Overview, Keypad Mode Overview, The Standard Interface, Using Calc -@subsection Quick Mode (Overview) - -@noindent -@dfn{Quick mode} is a quick way to use Calc when you don't need the -full complexity of the stack and trail. To use it, type @kbd{C-x * q} -(@code{quick-calc}) in any regular editing buffer. - -Quick mode is very simple: It prompts you to type any formula in -standard algebraic notation (like @samp{4 - 2/3}) and then displays -the result at the bottom of the Emacs screen (@mathit{3.33333333333} -in this case). You are then back in the same editing buffer you -were in before, ready to continue editing or to type @kbd{C-x * q} -again to do another quick calculation. The result of the calculation -will also be in the Emacs ``kill ring'' so that a @kbd{C-y} command -at this point will yank the result into your editing buffer. - -Calc mode settings affect Quick mode, too, though you will have to -go into regular Calc (with @kbd{C-x * c}) to change the mode settings. - -@c [fix-ref Quick Calculator mode] -@xref{Quick Calculator}, for further information. - -@node Keypad Mode Overview, Standalone Operation, Quick Mode Overview, Using Calc -@subsection Keypad Mode (Overview) - -@noindent -@dfn{Keypad mode} is a mouse-based interface to the Calculator. -It is designed for use with terminals that support a mouse. If you -don't have a mouse, you will have to operate Keypad mode with your -arrow keys (which is probably more trouble than it's worth). - -Type @kbd{C-x * k} to turn Keypad mode on or off. Once again you -get two new windows, this time on the righthand side of the screen -instead of at the bottom. The upper window is the familiar Calc -Stack; the lower window is a picture of a typical calculator keypad. - -@tex -\dimen0=\pagetotal% -\advance \dimen0 by 24\baselineskip% -\ifdim \dimen0>\pagegoal \vfill\eject \fi% -\medskip -@end tex -@smallexample -@group -|--- Emacs Calculator Mode --- -|2: 17.3 -|1: -5 -| . -|--%*-Calc: 12 Deg (Calcul -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -Keypad mode is much easier for beginners to learn, because there -is no need to memorize lots of obscure key sequences. But not all -commands in regular Calc are available on the Keypad. You can -always switch the cursor into the Calc stack window to use -standard Calc commands if you need. Serious Calc users, though, -often find they prefer the standard interface over Keypad mode. - -To operate the Calculator, just click on the ``buttons'' of the -keypad using your left mouse button. To enter the two numbers -shown here you would click @w{@kbd{1 7 .@: 3 ENTER 5 +/- ENTER}}; to -add them together you would then click @kbd{+} (to get 12.3 on -the stack). - -If you click the right mouse button, the top three rows of the -keypad change to show other sets of commands, such as advanced -math functions, vector operations, and operations on binary -numbers. - -Because Keypad mode doesn't use the regular keyboard, Calc leaves -the cursor in your original editing buffer. You can type in -this buffer in the usual way while also clicking on the Calculator -keypad. One advantage of Keypad mode is that you don't need an -explicit command to switch between editing and calculating. - -If you press @kbd{C-x * b} first, you get a full-screen Keypad mode -(@code{full-calc-keypad}) with three windows: The keypad in the lower -left, the stack in the lower right, and the trail on top. - -@c [fix-ref Keypad Mode] -@xref{Keypad Mode}, for further information. - -@node Standalone Operation, Embedded Mode Overview, Keypad Mode Overview, Using Calc -@subsection Standalone Operation - -@noindent -@cindex Standalone Operation -If you are not in Emacs at the moment but you wish to use Calc, -you must start Emacs first. If all you want is to run Calc, you -can give the commands: - -@example -emacs -f full-calc -@end example - -@noindent -or - -@example -emacs -f full-calc-keypad -@end example - -@noindent -which run a full-screen Calculator (as if by @kbd{C-x * b C-x * c}) or -a full-screen X-based Calculator (as if by @kbd{C-x * b C-x * k}). -In standalone operation, quitting the Calculator (by pressing -@kbd{q} or clicking on the keypad @key{EXIT} button) quits Emacs -itself. - -@node Embedded Mode Overview, Other C-x * Commands, Standalone Operation, Using Calc -@subsection Embedded Mode (Overview) - -@noindent -@dfn{Embedded mode} is a way to use Calc directly from inside an -editing buffer. Suppose you have a formula written as part of a -document like this: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -@end group -@end smallexample - -@noindent -and you wish to have Calc compute and format the derivative for -you and store this derivative in the buffer automatically. To -do this with Embedded mode, first copy the formula down to where -you want the result to be, leaving a blank line before and after the -formula: - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - - ln(ln(x)) -@end group -@end smallexample - -Now, move the cursor onto this new formula and press @kbd{C-x * e}. -Calc will read the formula (using the surrounding blank lines to tell -how much text to read), then push this formula (invisibly) onto the Calc -stack. The cursor will stay on the formula in the editing buffer, but -the line with the formula will now appear as it would on the Calc stack -(in this case, it will be left-aligned) and the buffer's mode line will -change to look like the Calc mode line (with mode indicators like -@samp{12 Deg} and so on). Even though you are still in your editing -buffer, the keyboard now acts like the Calc keyboard, and any new result -you get is copied from the stack back into the buffer. To take the -derivative, you would type @kbd{a d x @key{RET}}. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is - -1 / ln(x) x -@end group -@end smallexample - -(Note that by default, Calc gives division lower precedence than multiplication, -so that @samp{1 / ln(x) x} is equivalent to @samp{1 / (ln(x) x)}.) - -To make this look nicer, you might want to press @kbd{d =} to center -the formula, and even @kbd{d B} to use Big display mode. - -@smallexample -@group -The derivative of - - ln(ln(x)) - -is -% [calc-mode: justify: center] -% [calc-mode: language: big] - - 1 - ------- - ln(x) x -@end group -@end smallexample - -Calc has added annotations to the file to help it remember the modes -that were used for this formula. They are formatted like comments -in the @TeX{} typesetting language, just in case you are using @TeX{} or -La@TeX{}. (In this example @TeX{} is not being used, so you might want -to move these comments up to the top of the file or otherwise put them -out of the way.) - -As an extra flourish, we can add an equation number using a -righthand label: Type @kbd{d @} (1) @key{RET}}. - -@smallexample -@group -% [calc-mode: justify: center] -% [calc-mode: language: big] -% [calc-mode: right-label: " (1)"] - - 1 - ------- (1) - ln(x) x -@end group -@end smallexample - -To leave Embedded mode, type @kbd{C-x * e} again. The mode line -and keyboard will revert to the way they were before. - -The related command @kbd{C-x * w} operates on a single word, which -generally means a single number, inside text. It searches for an -expression which ``looks'' like a number containing the point. -Here's an example of its use: - -@smallexample -A slope of one-third corresponds to an angle of 1 degrees. -@end smallexample - -Place the cursor on the @samp{1}, then type @kbd{C-x * w} to enable -Embedded mode on that number. Now type @kbd{3 /} (to get one-third), -and @kbd{I T} (the Inverse Tangent converts a slope into an angle), -then @w{@kbd{C-x * w}} again to exit Embedded mode. - -@smallexample -A slope of one-third corresponds to an angle of 18.4349488229 degrees. -@end smallexample - -@c [fix-ref Embedded Mode] -@xref{Embedded Mode}, for full details. - -@node Other C-x * Commands, , Embedded Mode Overview, Using Calc -@subsection Other @kbd{C-x *} Commands - -@noindent -Two more Calc-related commands are @kbd{C-x * g} and @kbd{C-x * r}, -which ``grab'' data from a selected region of a buffer into the -Calculator. The region is defined in the usual Emacs way, by -a ``mark'' placed at one end of the region, and the Emacs -cursor or ``point'' placed at the other. - -The @kbd{C-x * g} command reads the region in the usual left-to-right, -top-to-bottom order. The result is packaged into a Calc vector -of numbers and placed on the stack. Calc (in its standard -user interface) is then started. Type @kbd{v u} if you want -to unpack this vector into separate numbers on the stack. Also, -@kbd{C-u C-x * g} interprets the region as a single number or -formula. - -The @kbd{C-x * r} command reads a rectangle, with the point and -mark defining opposite corners of the rectangle. The result -is a matrix of numbers on the Calculator stack. - -Complementary to these is @kbd{C-x * y}, which ``yanks'' the -value at the top of the Calc stack back into an editing buffer. -If you type @w{@kbd{C-x * y}} while in such a buffer, the value is -yanked at the current position. If you type @kbd{C-x * y} while -in the Calc buffer, Calc makes an educated guess as to which -editing buffer you want to use. The Calc window does not have -to be visible in order to use this command, as long as there -is something on the Calc stack. - -Here, for reference, is the complete list of @kbd{C-x *} commands. -The shift, control, and meta keys are ignored for the keystroke -following @kbd{C-x *}. - -@noindent -Commands for turning Calc on and off: - -@table @kbd -@item * -Turn Calc on or off, employing the same user interface as last time. - -@item =, +, -, /, \, &, # -Alternatives for @kbd{*}. - -@item C -Turn Calc on or off using its standard bottom-of-the-screen -interface. If Calc is already turned on but the cursor is not -in the Calc window, move the cursor into the window. - -@item O -Same as @kbd{C}, but don't select the new Calc window. If -Calc is already turned on and the cursor is in the Calc window, -move it out of that window. - -@item B -Control whether @kbd{C-x * c} and @kbd{C-x * k} use the full screen. - -@item Q -Use Quick mode for a single short calculation. - -@item K -Turn Calc Keypad mode on or off. - -@item E -Turn Calc Embedded mode on or off at the current formula. - -@item J -Turn Calc Embedded mode on or off, select the interesting part. - -@item W -Turn Calc Embedded mode on or off at the current word (number). - -@item Z -Turn Calc on in a user-defined way, as defined by a @kbd{Z I} command. - -@item X -Quit Calc; turn off standard, Keypad, or Embedded mode if on. -(This is like @kbd{q} or @key{OFF} inside of Calc.) -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for moving data into and out of the Calculator: - -@table @kbd -@item G -Grab the region into the Calculator as a vector. - -@item R -Grab the rectangular region into the Calculator as a matrix. - -@item : -Grab the rectangular region and compute the sums of its columns. - -@item _ -Grab the rectangular region and compute the sums of its rows. - -@item Y -Yank a value from the Calculator into the current editing buffer. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Commands for use with Embedded mode: - -@table @kbd -@item A -``Activate'' the current buffer. Locate all formulas that -contain @samp{:=} or @samp{=>} symbols and record their locations -so that they can be updated automatically as variables are changed. - -@item D -Duplicate the current formula immediately below and select -the duplicate. - -@item F -Insert a new formula at the current point. - -@item N -Move the cursor to the next active formula in the buffer. - -@item P -Move the cursor to the previous active formula in the buffer. - -@item U -Update (i.e., as if by the @kbd{=} key) the formula at the current point. - -@item ` -Edit (as if by @code{calc-edit}) the formula at the current point. -@end table -@iftex -@sp 2 -@end iftex - -@noindent -Miscellaneous commands: - -@table @kbd -@item I -Run the Emacs Info system to read the Calc manual. -(This is the same as @kbd{h i} inside of Calc.) - -@item T -Run the Emacs Info system to read the Calc Tutorial. - -@item S -Run the Emacs Info system to read the Calc Summary. - -@item L -Load Calc entirely into memory. (Normally the various parts -are loaded only as they are needed.) - -@item M -Read a region of written keystroke names (like @kbd{C-n a b c @key{RET}}) -and record them as the current keyboard macro. - -@item 0 -(This is the ``zero'' digit key.) Reset the Calculator to -its initial state: Empty stack, and initial mode settings. -@end table - -@node History and Acknowledgements, , Using Calc, Getting Started -@section History and Acknowledgements - -@noindent -Calc was originally started as a two-week project to occupy a lull -in the author's schedule. Basically, a friend asked if I remembered -the value of -@texline @math{2^{32}}. -@infoline @expr{2^32}. -I didn't offhand, but I said, ``that's easy, just call up an -@code{xcalc}.'' @code{Xcalc} duly reported that the answer to our -question was @samp{4.294967e+09}---with no way to see the full ten -digits even though we knew they were there in the program's memory! I -was so annoyed, I vowed to write a calculator of my own, once and for -all. - -I chose Emacs Lisp, a) because I had always been curious about it -and b) because, being only a text editor extension language after -all, Emacs Lisp would surely reach its limits long before the project -got too far out of hand. - -To make a long story short, Emacs Lisp turned out to be a distressingly -solid implementation of Lisp, and the humble task of calculating -turned out to be more open-ended than one might have expected. - -Emacs Lisp didn't have built-in floating point math (now it does), so -this had to be simulated in software. In fact, Emacs integers would -only comfortably fit six decimal digits or so---not enough for a decent -calculator. So I had to write my own high-precision integer code as -well, and once I had this I figured that arbitrary-size integers were -just as easy as large integers. Arbitrary floating-point precision was -the logical next step. Also, since the large integer arithmetic was -there anyway it seemed only fair to give the user direct access to it, -which in turn made it practical to support fractions as well as floats. -All these features inspired me to look around for other data types that -might be worth having. - -Around this time, my friend Rick Koshi showed me his nifty new HP-28 -calculator. It allowed the user to manipulate formulas as well as -numerical quantities, and it could also operate on matrices. I -decided that these would be good for Calc to have, too. And once -things had gone this far, I figured I might as well take a look at -serious algebra systems for further ideas. Since these systems did -far more than I could ever hope to implement, I decided to focus on -rewrite rules and other programming features so that users could -implement what they needed for themselves. - -Rick complained that matrices were hard to read, so I put in code to -format them in a 2D style. Once these routines were in place, Big mode -was obligatory. Gee, what other language modes would be useful? - -Scott Hemphill and Allen Knutson, two friends with a strong mathematical -bent, contributed ideas and algorithms for a number of Calc features -including modulo forms, primality testing, and float-to-fraction conversion. - -Units were added at the eager insistence of Mass Sivilotti. Later, -Ulrich Mueller at CERN and Przemek Klosowski at NIST provided invaluable -expert assistance with the units table. As far as I can remember, the -idea of using algebraic formulas and variables to represent units dates -back to an ancient article in Byte magazine about muMath, an early -algebra system for microcomputers. - -Many people have contributed to Calc by reporting bugs and suggesting -features, large and small. A few deserve special mention: Tim Peters, -who helped develop the ideas that led to the selection commands, rewrite -rules, and many other algebra features; -@texline Fran\c{c}ois -@infoline Francois -Pinard, who contributed an early prototype of the Calc Summary appendix -as well as providing valuable suggestions in many other areas of Calc; -Carl Witty, whose eagle eyes discovered many typographical and factual -errors in the Calc manual; Tim Kay, who drove the development of -Embedded mode; Ove Ewerlid, who made many suggestions relating to the -algebra commands and contributed some code for polynomial operations; -Randal Schwartz, who suggested the @code{calc-eval} function; Juha -Sarlin, who first worked out how to split Calc into quickly-loading -parts; Bob Weiner, who helped immensely with the Lucid Emacs port; and -Robert J. Chassell, who suggested the Calc Tutorial and exercises as -well as many other things. - -@cindex Bibliography -@cindex Knuth, Art of Computer Programming -@cindex Numerical Recipes -@c Should these be expanded into more complete references? -Among the books used in the development of Calc were Knuth's @emph{Art -of Computer Programming} (especially volume II, @emph{Seminumerical -Algorithms}); @emph{Numerical Recipes} by Press, Flannery, Teukolsky, -and Vetterling; Bevington's @emph{Data Reduction and Error Analysis -for the Physical Sciences}; @emph{Concrete Mathematics} by Graham, -Knuth, and Patashnik; Steele's @emph{Common Lisp, the Language}; the -@emph{CRC Standard Math Tables} (William H. Beyer, ed.); and -Abramowitz and Stegun's venerable @emph{Handbook of Mathematical -Functions}. Also, of course, Calc could not have been written without -the excellent @emph{GNU Emacs Lisp Reference Manual}, by Bil Lewis and -Dan LaLiberte. - -Final thanks go to Richard Stallman, without whose fine implementations -of the Emacs editor, language, and environment, Calc would have been -finished in two weeks. - -@c [tutorial] - -@ifinfo -@c This node is accessed by the `C-x * t' command. -@node Interactive Tutorial, Tutorial, Getting Started, Top -@chapter Tutorial - -@noindent -Some brief instructions on using the Emacs Info system for this tutorial: - -Press the space bar and Delete keys to go forward and backward in a -section by screenfuls (or use the regular Emacs scrolling commands -for this). - -Press @kbd{n} or @kbd{p} to go to the Next or Previous section. -If the section has a @dfn{menu}, press a digit key like @kbd{1} -or @kbd{2} to go to a sub-section from the menu. Press @kbd{u} to -go back up from a sub-section to the menu it is part of. - -Exercises in the tutorial all have cross-references to the -appropriate page of the ``answers'' section. Press @kbd{f}, then -the exercise number, to see the answer to an exercise. After -you have followed a cross-reference, you can press the letter -@kbd{l} to return to where you were before. - -You can press @kbd{?} at any time for a brief summary of Info commands. - -Press the number @kbd{1} now to enter the first section of the Tutorial. - -@menu -* Tutorial:: -@end menu - -@node Tutorial, Introduction, Interactive Tutorial, Top -@end ifinfo -@ifnotinfo -@node Tutorial, Introduction, Getting Started, Top -@end ifnotinfo -@chapter Tutorial - -@noindent -This chapter explains how to use Calc and its many features, in -a step-by-step, tutorial way. You are encouraged to run Calc and -work along with the examples as you read (@pxref{Starting Calc}). -If you are already familiar with advanced calculators, you may wish -@c [not-split] -to skip on to the rest of this manual. -@c [when-split] -@c to skip on to volume II of this manual, the @dfn{Calc Reference}. - -@c [fix-ref Embedded Mode] -This tutorial describes the standard user interface of Calc only. -The Quick mode and Keypad mode interfaces are fairly -self-explanatory. @xref{Embedded Mode}, for a description of -the Embedded mode interface. - -The easiest way to read this tutorial on-line is to have two windows on -your Emacs screen, one with Calc and one with the Info system. Press -@kbd{C-x * t} to set this up; the on-line tutorial will be opened in the -current window and Calc will be started in another window. From the -Info window, the command @kbd{C-x * c} can be used to switch to the Calc -window and @kbd{C-x * o} can be used to switch back to the Info window. -(If you have a printed copy of the manual you can use that instead; in -that case you only need to press @kbd{C-x * c} to start Calc.) - -This tutorial is designed to be done in sequence. But the rest of this -manual does not assume you have gone through the tutorial. The tutorial -does not cover everything in the Calculator, but it touches on most -general areas. - -@ifnottex -You may wish to print out a copy of the Calc Summary and keep notes on -it as you learn Calc. @xref{About This Manual}, to see how to make a -printed summary. @xref{Summary}. -@end ifnottex -@iftex -The Calc Summary at the end of the reference manual includes some blank -space for your own use. You may wish to keep notes there as you learn -Calc. -@end iftex - -@menu -* Basic Tutorial:: -* Arithmetic Tutorial:: -* Vector/Matrix Tutorial:: -* Types Tutorial:: -* Algebra Tutorial:: -* Programming Tutorial:: - -* Answers to Exercises:: -@end menu - -@node Basic Tutorial, Arithmetic Tutorial, Tutorial, Tutorial -@section Basic Tutorial - -@noindent -In this section, we learn how RPN and algebraic-style calculations -work, how to undo and redo an operation done by mistake, and how -to control various modes of the Calculator. - -@menu -* RPN Tutorial:: Basic operations with the stack. -* Algebraic Tutorial:: Algebraic entry; variables. -* Undo Tutorial:: If you make a mistake: Undo and the trail. -* Modes Tutorial:: Common mode-setting commands. -@end menu - -@node RPN Tutorial, Algebraic Tutorial, Basic Tutorial, Basic Tutorial -@subsection RPN Calculations and the Stack - -@cindex RPN notation -@ifnottex -@noindent -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan Lukasiewicz.) -@end ifnottex -@tex -\noindent -Calc normally uses RPN notation. You may be familiar with the RPN -system from Hewlett-Packard calculators, FORTH, or PostScript. -(Reverse Polish Notation, RPN, is named after the Polish mathematician -Jan \L ukasiewicz.) -@end tex - -The central component of an RPN calculator is the @dfn{stack}. A -calculator stack is like a stack of dishes. New dishes (numbers) are -added at the top of the stack, and numbers are normally only removed -from the top of the stack. - -@cindex Operators -@cindex Operands -In an operation like @expr{2+3}, the 2 and 3 are called the @dfn{operands} -and the @expr{+} is the @dfn{operator}. In an RPN calculator you always -enter the operands first, then the operator. Each time you type a -number, Calc adds or @dfn{pushes} it onto the top of the Stack. -When you press an operator key like @kbd{+}, Calc @dfn{pops} the appropriate -number of operands from the stack and pushes back the result. - -Thus we could add the numbers 2 and 3 in an RPN calculator by typing: -@kbd{2 @key{RET} 3 @key{RET} +}. (The @key{RET} key, Return, corresponds to -the @key{ENTER} key on traditional RPN calculators.) Try this now if -you wish; type @kbd{C-x * c} to switch into the Calc window (you can type -@kbd{C-x * c} again or @kbd{C-x * o} to switch back to the Tutorial window). -The first four keystrokes ``push'' the numbers 2 and 3 onto the stack. -The @kbd{+} key ``pops'' the top two numbers from the stack, adds them, -and pushes the result (5) back onto the stack. Here's how the stack -will look at various points throughout the calculation: - -@smallexample -@group - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - C-x * c 2 @key{RET} 3 @key{RET} + @key{DEL} -@end group -@end smallexample - -The @samp{.} symbol is a marker that represents the top of the stack. -Note that the ``top'' of the stack is really shown at the bottom of -the Stack window. This may seem backwards, but it turns out to be -less distracting in regular use. - -@cindex Stack levels -@cindex Levels of stack -The numbers @samp{1:} and @samp{2:} on the left are @dfn{stack level -numbers}. Old RPN calculators always had four stack levels called -@expr{x}, @expr{y}, @expr{z}, and @expr{t}. Calc's stack can grow -as large as you like, so it uses numbers instead of letters. Some -stack-manipulation commands accept a numeric argument that says -which stack level to work on. Normal commands like @kbd{+} always -work on the top few levels of the stack. - -@c [fix-ref Truncating the Stack] -The Stack buffer is just an Emacs buffer, and you can move around in -it using the regular Emacs motion commands. But no matter where the -cursor is, even if you have scrolled the @samp{.} marker out of -view, most Calc commands always move the cursor back down to level 1 -before doing anything. It is possible to move the @samp{.} marker -upwards through the stack, temporarily ``hiding'' some numbers from -commands like @kbd{+}. This is called @dfn{stack truncation} and -we will not cover it in this tutorial; @pxref{Truncating the Stack}, -if you are interested. - -You don't really need the second @key{RET} in @kbd{2 @key{RET} 3 -@key{RET} +}. That's because if you type any operator name or -other non-numeric key when you are entering a number, the Calculator -automatically enters that number and then does the requested command. -Thus @kbd{2 @key{RET} 3 +} will work just as well. - -Examples in this tutorial will often omit @key{RET} even when the -stack displays shown would only happen if you did press @key{RET}: - -@smallexample -@group -1: 2 2: 2 1: 5 - . 1: 3 . - . - - 2 @key{RET} 3 + -@end group -@end smallexample - -@noindent -Here, after pressing @kbd{3} the stack would really show @samp{1: 2} -with @samp{Calc:@: 3} in the minibuffer. In these situations, you can -press the optional @key{RET} to see the stack as the figure shows. - -(@bullet{}) @strong{Exercise 1.} (This tutorial will include exercises -at various points. Try them if you wish. Answers to all the exercises -are located at the end of the Tutorial chapter. Each exercise will -include a cross-reference to its particular answer. If you are -reading with the Emacs Info system, press @kbd{f} and the -exercise number to go to the answer, then the letter @kbd{l} to -return to where you were.) - -@noindent -Here's the first exercise: What will the keystrokes @kbd{1 @key{RET} 2 -@key{RET} 3 @key{RET} 4 + * -} compute? (@samp{*} is the symbol for -multiplication.) Figure it out by hand, then try it with Calc to see -if you're right. @xref{RPN Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Compute -@texline @math{(2\times4) + (7\times9.4) + {5\over4}} -@infoline @expr{2*4 + 7*9.5 + 5/4} -using the stack. @xref{RPN Answer 2, 2}. (@bullet{}) - -The @key{DEL} key is called Backspace on some keyboards. It is -whatever key you would use to correct a simple typing error when -regularly using Emacs. The @key{DEL} key pops and throws away the -top value on the stack. (You can still get that value back from -the Trail if you should need it later on.) There are many places -in this tutorial where we assume you have used @key{DEL} to erase the -results of the previous example at the beginning of a new example. -In the few places where it is really important to use @key{DEL} to -clear away old results, the text will remind you to do so. - -(It won't hurt to let things accumulate on the stack, except that -whenever you give a display-mode-changing command Calc will have to -spend a long time reformatting such a large stack.) - -Since the @kbd{-} key is also an operator (it subtracts the top two -stack elements), how does one enter a negative number? Calc uses -the @kbd{_} (underscore) key to act like the minus sign in a number. -So, typing @kbd{-5 @key{RET}} won't work because the @kbd{-} key -will try to do a subtraction, but @kbd{_5 @key{RET}} works just fine. - -You can also press @kbd{n}, which means ``change sign.'' It changes -the number at the top of the stack (or the number being entered) -from positive to negative or vice-versa: @kbd{5 n @key{RET}}. - -@cindex Duplicating a stack entry -If you press @key{RET} when you're not entering a number, the effect -is to duplicate the top number on the stack. Consider this calculation: - -@smallexample -@group -1: 3 2: 3 1: 9 2: 9 1: 81 - . 1: 3 . 1: 9 . - . . - - 3 @key{RET} @key{RET} * @key{RET} * -@end group -@end smallexample - -@noindent -(Of course, an easier way to do this would be @kbd{3 @key{RET} 4 ^}, -to raise 3 to the fourth power.) - -The space-bar key (denoted @key{SPC} here) performs the same function -as @key{RET}; you could replace all three occurrences of @key{RET} in -the above example with @key{SPC} and the effect would be the same. - -@cindex Exchanging stack entries -Another stack manipulation key is @key{TAB}. This exchanges the top -two stack entries. Suppose you have computed @kbd{2 @key{RET} 3 +} -to get 5, and then you realize what you really wanted to compute -was @expr{20 / (2+3)}. - -@smallexample -@group -1: 5 2: 5 2: 20 1: 4 - . 1: 20 1: 5 . - . . - - 2 @key{RET} 3 + 20 @key{TAB} / -@end group -@end smallexample - -@noindent -Planning ahead, the calculation would have gone like this: - -@smallexample -@group -1: 20 2: 20 3: 20 2: 20 1: 4 - . 1: 2 2: 2 1: 5 . - . 1: 3 . - . - - 20 @key{RET} 2 @key{RET} 3 + / -@end group -@end smallexample - -A related stack command is @kbd{M-@key{TAB}} (hold @key{META} and type -@key{TAB}). It rotates the top three elements of the stack upward, -bringing the object in level 3 to the top. - -@smallexample -@group -1: 10 2: 10 3: 10 3: 20 3: 30 - . 1: 20 2: 20 2: 30 2: 10 - . 1: 30 1: 10 1: 20 - . . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Suppose the numbers 10, 20, and 30 are -on the stack. Figure out how to add one to the number in level 2 -without affecting the rest of the stack. Also figure out how to add -one to the number in level 3. @xref{RPN Answer 3, 3}. (@bullet{}) - -Operations like @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, and @kbd{^} pop two -arguments from the stack and push a result. Operations like @kbd{n} and -@kbd{Q} (square root) pop a single number and push the result. You can -think of them as simply operating on the top element of the stack. - -@smallexample -@group -1: 3 1: 9 2: 9 1: 25 1: 5 - . . 1: 16 . . - . - - 3 @key{RET} @key{RET} * 4 @key{RET} @key{RET} * + Q -@end group -@end smallexample - -@noindent -(Note that capital @kbd{Q} means to hold down the Shift key while -typing @kbd{q}. Remember, plain unshifted @kbd{q} is the Quit command.) - -@cindex Pythagorean Theorem -Here we've used the Pythagorean Theorem to determine the hypotenuse of a -right triangle. Calc actually has a built-in command for that called -@kbd{f h}, but let's suppose we can't remember the necessary keystrokes. -We can still enter it by its full name using @kbd{M-x} notation: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} M-x calc-hypot -@end group -@end smallexample - -All Calculator commands begin with the word @samp{calc-}. Since it -gets tiring to type this, Calc provides an @kbd{x} key which is just -like the regular Emacs @kbd{M-x} key except that it types the @samp{calc-} -prefix for you: - -@smallexample -@group -1: 3 2: 3 1: 5 - . 1: 4 . - . - - 3 @key{RET} 4 @key{RET} x hypot -@end group -@end smallexample - -What happens if you take the square root of a negative number? - -@smallexample -@group -1: 4 1: -4 1: (0, 2) - . . . - - 4 @key{RET} n Q -@end group -@end smallexample - -@noindent -The notation @expr{(a, b)} represents a complex number. -Complex numbers are more traditionally written @expr{a + b i}; -Calc can display in this format, too, but for now we'll stick to the -@expr{(a, b)} notation. - -If you don't know how complex numbers work, you can safely ignore this -feature. Complex numbers only arise from operations that would be -errors in a calculator that didn't have complex numbers. (For example, -taking the square root or logarithm of a negative number produces a -complex result.) - -Complex numbers are entered in the notation shown. The @kbd{(} and -@kbd{,} and @kbd{)} keys manipulate ``incomplete complex numbers.'' - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 1: (2, ... 1: (2, 3) - . 1: 2 . 3 . - . . - - ( 2 , 3 ) -@end group -@end smallexample - -You can perform calculations while entering parts of incomplete objects. -However, an incomplete object cannot actually participate in a calculation: - -@smallexample -@group -1: ( ... 2: ( ... 3: ( ... 1: ( ... 1: ( ... - . 1: 2 2: 2 5 5 - . 1: 3 . . - . - (error) - ( 2 @key{RET} 3 + + -@end group -@end smallexample - -@noindent -Adding 5 to an incomplete object makes no sense, so the last command -produces an error message and leaves the stack the same. - -Incomplete objects can't participate in arithmetic, but they can be -moved around by the regular stack commands. - -@smallexample -@group -2: 2 3: 2 3: 3 1: ( ... 1: (2, 3) -1: 3 2: 3 2: ( ... 2 . - . 1: ( ... 1: 2 3 - . . . - -2 @key{RET} 3 @key{RET} ( M-@key{TAB} M-@key{TAB} ) -@end group -@end smallexample - -@noindent -Note that the @kbd{,} (comma) key did not have to be used here. -When you press @kbd{)} all the stack entries between the incomplete -entry and the top are collected, so there's never really a reason -to use the comma. It's up to you. - -(@bullet{}) @strong{Exercise 4.} To enter the complex number @expr{(2, 3)}, -your friend Joe typed @kbd{( 2 , @key{SPC} 3 )}. What happened? -(Joe thought of a clever way to correct his mistake in only two -keystrokes, but it didn't quite work. Try it to find out why.) -@xref{RPN Answer 4, 4}. (@bullet{}) - -Vectors are entered the same way as complex numbers, but with square -brackets in place of parentheses. We'll meet vectors again later in -the tutorial. - -Any Emacs command can be given a @dfn{numeric prefix argument} by -typing a series of @key{META}-digits beforehand. If @key{META} is -awkward for you, you can instead type @kbd{C-u} followed by the -necessary digits. Numeric prefix arguments can be negative, as in -@kbd{M-- M-3 M-5} or @w{@kbd{C-u - 3 5}}. Calc commands use numeric -prefix arguments in a variety of ways. For example, a numeric prefix -on the @kbd{+} operator adds any number of stack entries at once: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 1: 60 - . 1: 20 2: 20 2: 20 . - . 1: 30 1: 30 - . . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u 3 + -@end group -@end smallexample - -For stack manipulation commands like @key{RET}, a positive numeric -prefix argument operates on the top @var{n} stack entries at once. A -negative argument operates on the entry in level @var{n} only. An -argument of zero operates on the entire stack. In this example, we copy -the second-to-top element of the stack: - -@smallexample -@group -1: 10 2: 10 3: 10 3: 10 4: 10 - . 1: 20 2: 20 2: 20 3: 20 - . 1: 30 1: 30 2: 30 - . . 1: 20 - . - - 10 @key{RET} 20 @key{RET} 30 @key{RET} C-u -2 @key{RET} -@end group -@end smallexample - -@cindex Clearing the stack -@cindex Emptying the stack -Another common idiom is @kbd{M-0 @key{DEL}}, which clears the stack. -(The @kbd{M-0} numeric prefix tells @key{DEL} to operate on the -entire stack.) - -@node Algebraic Tutorial, Undo Tutorial, RPN Tutorial, Basic Tutorial -@subsection Algebraic-Style Calculations - -@noindent -If you are not used to RPN notation, you may prefer to operate the -Calculator in Algebraic mode, which is closer to the way -non-RPN calculators work. In Algebraic mode, you enter formulas -in traditional @expr{2+3} notation. - -@strong{Notice:} Calc gives @samp{/} lower precedence than @samp{*}, so -that @samp{a/b*c} is interpreted as @samp{a/(b*c)}; this is not -standard across all computer languages. See below for details. - -You don't really need any special ``mode'' to enter algebraic formulas. -You can enter a formula at any time by pressing the apostrophe (@kbd{'}) -key. Answer the prompt with the desired formula, then press @key{RET}. -The formula is evaluated and the result is pushed onto the RPN stack. -If you don't want to think in RPN at all, you can enter your whole -computation as a formula, read the result from the stack, then press -@key{DEL} to delete it from the stack. - -Try pressing the apostrophe key, then @kbd{2+3+4}, then @key{RET}. -The result should be the number 9. - -Algebraic formulas use the operators @samp{+}, @samp{-}, @samp{*}, -@samp{/}, and @samp{^}. You can use parentheses to make the order -of evaluation clear. In the absence of parentheses, @samp{^} is -evaluated first, then @samp{*}, then @samp{/}, then finally -@samp{+} and @samp{-}. For example, the expression - -@example -2 + 3*4*5 / 6*7^8 - 9 -@end example - -@noindent -is equivalent to - -@example -2 + ((3*4*5) / (6*(7^8)) - 9 -@end example - -@noindent -or, in large mathematical notation, - -@ifnottex -@example -@group - 3 * 4 * 5 -2 + --------- - 9 - 8 - 6 * 7 -@end group -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ 2 + { 3 \times 4 \times 5 \over 6 \times 7^8 } - 9 $$ -\afterdisplay -@end tex - -@noindent -The result of this expression will be the number @mathit{-6.99999826533}. - -Calc's order of evaluation is the same as for most computer languages, -except that @samp{*} binds more strongly than @samp{/}, as the above -example shows. As in normal mathematical notation, the @samp{*} symbol -can often be omitted: @samp{2 a} is the same as @samp{2*a}. - -Operators at the same level are evaluated from left to right, except -that @samp{^} is evaluated from right to left. Thus, @samp{2-3-4} is -equivalent to @samp{(2-3)-4} or @mathit{-5}, whereas @samp{2^3^4} is equivalent -to @samp{2^(3^4)} (a very large integer; try it!). - -If you tire of typing the apostrophe all the time, there is -Algebraic mode, where Calc automatically senses -when you are about to type an algebraic expression. To enter this -mode, press the two letters @w{@kbd{m a}}. (An @samp{Alg} indicator -should appear in the Calc window's mode line.) - -Press @kbd{m a}, then @kbd{2+3+4} with no apostrophe, then @key{RET}. - -In Algebraic mode, when you press any key that would normally begin -entering a number (such as a digit, a decimal point, or the @kbd{_} -key), or if you press @kbd{(} or @kbd{[}, Calc automatically begins -an algebraic entry. - -Functions which do not have operator symbols like @samp{+} and @samp{*} -must be entered in formulas using function-call notation. For example, -the function name corresponding to the square-root key @kbd{Q} is -@code{sqrt}. To compute a square root in a formula, you would use -the notation @samp{sqrt(@var{x})}. - -Press the apostrophe, then type @kbd{sqrt(5*2) - 3}. The result should -be @expr{0.16227766017}. - -Note that if the formula begins with a function name, you need to use -the apostrophe even if you are in Algebraic mode. If you type @kbd{arcsin} -out of the blue, the @kbd{a r} will be taken as an Algebraic Rewrite -command, and the @kbd{csin} will be taken as the name of the rewrite -rule to use! - -Some people prefer to enter complex numbers and vectors in algebraic -form because they find RPN entry with incomplete objects to be too -distracting, even though they otherwise use Calc as an RPN calculator. - -Still in Algebraic mode, type: - -@smallexample -@group -1: (2, 3) 2: (2, 3) 1: (8, -1) 2: (8, -1) 1: (9, -1) - . 1: (1, -2) . 1: 1 . - . . - - (2,3) @key{RET} (1,-2) @key{RET} * 1 @key{RET} + -@end group -@end smallexample - -Algebraic mode allows us to enter complex numbers without pressing -an apostrophe first, but it also means we need to press @key{RET} -after every entry, even for a simple number like @expr{1}. - -(You can type @kbd{C-u m a} to enable a special Incomplete Algebraic -mode in which the @kbd{(} and @kbd{[} keys use algebraic entry even -though regular numeric keys still use RPN numeric entry. There is also -Total Algebraic mode, started by typing @kbd{m t}, in which all -normal keys begin algebraic entry. You must then use the @key{META} key -to type Calc commands: @kbd{M-m t} to get back out of Total Algebraic -mode, @kbd{M-q} to quit, etc.) - -If you're still in Algebraic mode, press @kbd{m a} again to turn it off. - -Actual non-RPN calculators use a mixture of algebraic and RPN styles. -In general, operators of two numbers (like @kbd{+} and @kbd{*}) -use algebraic form, but operators of one number (like @kbd{n} and @kbd{Q}) -use RPN form. Also, a non-RPN calculator allows you to see the -intermediate results of a calculation as you go along. You can -accomplish this in Calc by performing your calculation as a series -of algebraic entries, using the @kbd{$} sign to tie them together. -In an algebraic formula, @kbd{$} represents the number on the top -of the stack. Here, we perform the calculation -@texline @math{\sqrt{2\times4+1}}, -@infoline @expr{sqrt(2*4+1)}, -which on a traditional calculator would be done by pressing -@kbd{2 * 4 + 1 =} and then the square-root key. - -@smallexample -@group -1: 8 1: 9 1: 3 - . . . - - ' 2*4 @key{RET} $+1 @key{RET} Q -@end group -@end smallexample - -@noindent -Notice that we didn't need to press an apostrophe for the @kbd{$+1}, -because the dollar sign always begins an algebraic entry. - -(@bullet{}) @strong{Exercise 1.} How could you get the same effect as -pressing @kbd{Q} but using an algebraic entry instead? How about -if the @kbd{Q} key on your keyboard were broken? -@xref{Algebraic Answer 1, 1}. (@bullet{}) - -The notations @kbd{$$}, @kbd{$$$}, and so on stand for higher stack -entries. For example, @kbd{' $$+$ @key{RET}} is just like typing @kbd{+}. - -Algebraic formulas can include @dfn{variables}. To store in a -variable, press @kbd{s s}, then type the variable name, then press -@key{RET}. (There are actually two flavors of store command: -@kbd{s s} stores a number in a variable but also leaves the number -on the stack, while @w{@kbd{s t}} removes a number from the stack and -stores it in the variable.) A variable name should consist of one -or more letters or digits, beginning with a letter. - -@smallexample -@group -1: 17 . 1: a + a^2 1: 306 - . . . - - 17 s t a @key{RET} ' a+a^2 @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key @dfn{evaluates} a formula by replacing all its -variables by the values that were stored in them. - -For RPN calculations, you can recall a variable's value on the -stack either by entering its name as a formula and pressing @kbd{=}, -or by using the @kbd{s r} command. - -@smallexample -@group -1: 17 2: 17 3: 17 2: 17 1: 306 - . 1: 17 2: 17 1: 289 . - . 1: 2 . - . - - s r a @key{RET} ' a @key{RET} = 2 ^ + -@end group -@end smallexample - -If you press a single digit for a variable name (as in @kbd{s t 3}, you -get one of ten @dfn{quick variables} @code{q0} through @code{q9}. -They are ``quick'' simply because you don't have to type the letter -@code{q} or the @key{RET} after their names. In fact, you can type -simply @kbd{s 3} as a shorthand for @kbd{s s 3}, and likewise for -@kbd{t 3} and @w{@kbd{r 3}}. - -Any variables in an algebraic formula for which you have not stored -values are left alone, even when you evaluate the formula. - -@smallexample -@group -1: 2 a + 2 b 1: 34 + 2 b - . . - - ' 2a+2b @key{RET} = -@end group -@end smallexample - -Calls to function names which are undefined in Calc are also left -alone, as are calls for which the value is undefined. - -@smallexample -@group -1: 2 + log10(0) + log10(x) + log10(5, 6) + foo(3) - . - - ' log10(100) + log10(0) + log10(x) + log10(5,6) + foo(3) @key{RET} -@end group -@end smallexample - -@noindent -In this example, the first call to @code{log10} works, but the other -calls are not evaluated. In the second call, the logarithm is -undefined for that value of the argument; in the third, the argument -is symbolic, and in the fourth, there are too many arguments. In the -fifth case, there is no function called @code{foo}. You will see a -``Wrong number of arguments'' message referring to @samp{log10(5,6)}. -Press the @kbd{w} (``why'') key to see any other messages that may -have arisen from the last calculation. In this case you will get -``logarithm of zero,'' then ``number expected: @code{x}''. Calc -automatically displays the first message only if the message is -sufficiently important; for example, Calc considers ``wrong number -of arguments'' and ``logarithm of zero'' to be important enough to -report automatically, while a message like ``number expected: @code{x}'' -will only show up if you explicitly press the @kbd{w} key. - -(@bullet{}) @strong{Exercise 2.} Joe entered the formula @samp{2 x y}, -stored 5 in @code{x}, pressed @kbd{=}, and got the expected result, -@samp{10 y}. He then tried the same for the formula @samp{2 x (1+y)}, -expecting @samp{10 (1+y)}, but it didn't work. Why not? -@xref{Algebraic Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} What result would you expect -@kbd{1 @key{RET} 0 /} to give? What if you then type @kbd{0 *}? -@xref{Algebraic Answer 3, 3}. (@bullet{}) - -One interesting way to work with variables is to use the -@dfn{evaluates-to} (@samp{=>}) operator. It works like this: -Enter a formula algebraically in the usual way, but follow -the formula with an @samp{=>} symbol. (There is also an @kbd{s =} -command which builds an @samp{=>} formula using the stack.) On -the stack, you will see two copies of the formula with an @samp{=>} -between them. The lefthand formula is exactly like you typed it; -the righthand formula has been evaluated as if by typing @kbd{=}. - -@smallexample -@group -2: 2 + 3 => 5 2: 2 + 3 => 5 -1: 2 a + 2 b => 34 + 2 b 1: 2 a + 2 b => 20 + 2 b - . . - -' 2+3 => @key{RET} ' 2a+2b @key{RET} s = 10 s t a @key{RET} -@end group -@end smallexample - -@noindent -Notice that the instant we stored a new value in @code{a}, all -@samp{=>} operators already on the stack that referred to @expr{a} -were updated to use the new value. With @samp{=>}, you can push a -set of formulas on the stack, then change the variables experimentally -to see the effects on the formulas' values. - -You can also ``unstore'' a variable when you are through with it: - -@smallexample -@group -2: 2 + 5 => 5 -1: 2 a + 2 b => 2 a + 2 b - . - - s u a @key{RET} -@end group -@end smallexample - -We will encounter formulas involving variables and functions again -when we discuss the algebra and calculus features of the Calculator. - -@node Undo Tutorial, Modes Tutorial, Algebraic Tutorial, Basic Tutorial -@subsection Undo and Redo - -@noindent -If you make a mistake, you can usually correct it by pressing shift-@kbd{U}, -the ``undo'' command. First, clear the stack (@kbd{M-0 @key{DEL}}) and exit -and restart Calc (@kbd{C-x * * C-x * *}) to make sure things start off -with a clean slate. Now: - -@smallexample -@group -1: 2 2: 2 1: 8 2: 2 1: 6 - . 1: 3 . 1: 3 . - . . - - 2 @key{RET} 3 ^ U * -@end group -@end smallexample - -You can undo any number of times. Calc keeps a complete record of -all you have done since you last opened the Calc window. After the -above example, you could type: - -@smallexample -@group -1: 6 2: 2 1: 2 . . - . 1: 3 . - . - (error) - U U U U -@end group -@end smallexample - -You can also type @kbd{D} to ``redo'' a command that you have undone -mistakenly. - -@smallexample -@group - . 1: 2 2: 2 1: 6 1: 6 - . 1: 3 . . - . - (error) - D D D D -@end group -@end smallexample - -@noindent -It was not possible to redo past the @expr{6}, since that was placed there -by something other than an undo command. - -@cindex Time travel -You can think of undo and redo as a sort of ``time machine.'' Press -@kbd{U} to go backward in time, @kbd{D} to go forward. If you go -backward and do something (like @kbd{*}) then, as any science fiction -reader knows, you have changed your future and you cannot go forward -again. Thus, the inability to redo past the @expr{6} even though there -was an earlier undo command. - -You can always recall an earlier result using the Trail. We've ignored -the trail so far, but it has been faithfully recording everything we -did since we loaded the Calculator. If the Trail is not displayed, -press @kbd{t d} now to turn it on. - -Let's try grabbing an earlier result. The @expr{8} we computed was -undone by a @kbd{U} command, and was lost even to Redo when we pressed -@kbd{*}, but it's still there in the trail. There should be a little -@samp{>} arrow (the @dfn{trail pointer}) resting on the last trail -entry. If there isn't, press @kbd{t ]} to reset the trail pointer. -Now, press @w{@kbd{t p}} to move the arrow onto the line containing -@expr{8}, and press @w{@kbd{t y}} to ``yank'' that number back onto the -stack. - -If you press @kbd{t ]} again, you will see that even our Yank command -went into the trail. - -Let's go further back in time. Earlier in the tutorial we computed -a huge integer using the formula @samp{2^3^4}. We don't remember -what it was, but the first digits were ``241''. Press @kbd{t r} -(which stands for trail-search-reverse), then type @kbd{241}. -The trail cursor will jump back to the next previous occurrence of -the string ``241'' in the trail. This is just a regular Emacs -incremental search; you can now press @kbd{C-s} or @kbd{C-r} to -continue the search forwards or backwards as you like. - -To finish the search, press @key{RET}. This halts the incremental -search and leaves the trail pointer at the thing we found. Now we -can type @kbd{t y} to yank that number onto the stack. If we hadn't -remembered the ``241'', we could simply have searched for @kbd{2^3^4}, -then pressed @kbd{@key{RET} t n} to halt and then move to the next item. - -You may have noticed that all the trail-related commands begin with -the letter @kbd{t}. (The store-and-recall commands, on the other hand, -all began with @kbd{s}.) Calc has so many commands that there aren't -enough keys for all of them, so various commands are grouped into -two-letter sequences where the first letter is called the @dfn{prefix} -key. If you type a prefix key by accident, you can press @kbd{C-g} -to cancel it. (In fact, you can press @kbd{C-g} to cancel almost -anything in Emacs.) To get help on a prefix key, press that key -followed by @kbd{?}. Some prefixes have several lines of help, -so you need to press @kbd{?} repeatedly to see them all. -You can also type @kbd{h h} to see all the help at once. - -Try pressing @kbd{t ?} now. You will see a line of the form, - -@smallexample -trail/time: Display; Fwd, Back; Next, Prev, Here, [, ]; Yank: [MORE] t- -@end smallexample - -@noindent -The word ``trail'' indicates that the @kbd{t} prefix key contains -trail-related commands. Each entry on the line shows one command, -with a single capital letter showing which letter you press to get -that command. We have used @kbd{t n}, @kbd{t p}, @kbd{t ]}, and -@kbd{t y} so far. The @samp{[MORE]} means you can press @kbd{?} -again to see more @kbd{t}-prefix commands. Notice that the commands -are roughly divided (by semicolons) into related groups. - -When you are in the help display for a prefix key, the prefix is -still active. If you press another key, like @kbd{y} for example, -it will be interpreted as a @kbd{t y} command. If all you wanted -was to look at the help messages, press @kbd{C-g} afterwards to cancel -the prefix. - -One more way to correct an error is by editing the stack entries. -The actual Stack buffer is marked read-only and must not be edited -directly, but you can press @kbd{`} (the backquote or accent grave) -to edit a stack entry. - -Try entering @samp{3.141439} now. If this is supposed to represent -@cpi{}, it's got several errors. Press @kbd{`} to edit this number. -Now use the normal Emacs cursor motion and editing keys to change -the second 4 to a 5, and to transpose the 3 and the 9. When you -press @key{RET}, the number on the stack will be replaced by your -new number. This works for formulas, vectors, and all other types -of values you can put on the stack. The @kbd{`} key also works -during entry of a number or algebraic formula. - -@node Modes Tutorial, , Undo Tutorial, Basic Tutorial -@subsection Mode-Setting Commands - -@noindent -Calc has many types of @dfn{modes} that affect the way it interprets -your commands or the way it displays data. We have already seen one -mode, namely Algebraic mode. There are many others, too; we'll -try some of the most common ones here. - -Perhaps the most fundamental mode in Calc is the current @dfn{precision}. -Notice the @samp{12} on the Calc window's mode line: - -@smallexample ---%*-Calc: 12 Deg (Calculator)----All------ -@end smallexample - -@noindent -Most of the symbols there are Emacs things you don't need to worry -about, but the @samp{12} and the @samp{Deg} are mode indicators. -The @samp{12} means that calculations should always be carried to -12 significant figures. That is why, when we type @kbd{1 @key{RET} 7 /}, -we get @expr{0.142857142857} with exactly 12 digits, not counting -leading and trailing zeros. - -You can set the precision to anything you like by pressing @kbd{p}, -then entering a suitable number. Try pressing @kbd{p 30 @key{RET}}, -then doing @kbd{1 @key{RET} 7 /} again: - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 - . -@end group -@end smallexample - -Although the precision can be set arbitrarily high, Calc always -has to have @emph{some} value for the current precision. After -all, the true value @expr{1/7} is an infinitely repeating decimal; -Calc has to stop somewhere. - -Of course, calculations are slower the more digits you request. -Press @w{@kbd{p 12}} now to set the precision back down to the default. - -Calculations always use the current precision. For example, even -though we have a 30-digit value for @expr{1/7} on the stack, if -we use it in a calculation in 12-digit mode it will be rounded -down to 12 digits before it is used. Try it; press @key{RET} to -duplicate the number, then @w{@kbd{1 +}}. Notice that the @key{RET} -key didn't round the number, because it doesn't do any calculation. -But the instant we pressed @kbd{+}, the number was rounded down. - -@smallexample -@group -1: 0.142857142857 -2: 0.142857142857142857142857142857 -3: 1.14285714286 - . -@end group -@end smallexample - -@noindent -In fact, since we added a digit on the left, we had to lose one -digit on the right from even the 12-digit value of @expr{1/7}. - -How did we get more than 12 digits when we computed @samp{2^3^4}? The -answer is that Calc makes a distinction between @dfn{integers} and -@dfn{floating-point} numbers, or @dfn{floats}. An integer is a number -that does not contain a decimal point. There is no such thing as an -``infinitely repeating fraction integer,'' so Calc doesn't have to limit -itself. If you asked for @samp{2^10000} (don't try this!), you would -have to wait a long time but you would eventually get an exact answer. -If you ask for @samp{2.^10000}, you will quickly get an answer which is -correct only to 12 places. The decimal point tells Calc that it should -use floating-point arithmetic to get the answer, not exact integer -arithmetic. - -You can use the @kbd{F} (@code{calc-floor}) command to convert a -floating-point value to an integer, and @kbd{c f} (@code{calc-float}) -to convert an integer to floating-point form. - -Let's try entering that last calculation: - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311689e3010 - . 1: 10000 . - . - - 2.0 @key{RET} 10000 @key{RET} ^ -@end group -@end smallexample - -@noindent -@cindex Scientific notation, entry of -Notice the letter @samp{e} in there. It represents ``times ten to the -power of,'' and is used by Calc automatically whenever writing the -number out fully would introduce more extra zeros than you probably -want to see. You can enter numbers in this notation, too. - -@smallexample -@group -1: 2. 2: 2. 1: 1.99506311678e3010 - . 1: 10000. . - . - - 2.0 @key{RET} 1e4 @key{RET} ^ -@end group -@end smallexample - -@cindex Round-off errors -@noindent -Hey, the answer is different! Look closely at the middle columns -of the two examples. In the first, the stack contained the -exact integer @expr{10000}, but in the second it contained -a floating-point value with a decimal point. When you raise a -number to an integer power, Calc uses repeated squaring and -multiplication to get the answer. When you use a floating-point -power, Calc uses logarithms and exponentials. As you can see, -a slight error crept in during one of these methods. Which -one should we trust? Let's raise the precision a bit and find -out: - -@smallexample -@group - . 1: 2. 2: 2. 1: 1.995063116880828e3010 - . 1: 10000. . - . - - p 16 @key{RET} 2. @key{RET} 1e4 ^ p 12 @key{RET} -@end group -@end smallexample - -@noindent -@cindex Guard digits -Presumably, it doesn't matter whether we do this higher-precision -calculation using an integer or floating-point power, since we -have added enough ``guard digits'' to trust the first 12 digits -no matter what. And the verdict is@dots{} Integer powers were more -accurate; in fact, the result was only off by one unit in the -last place. - -@cindex Guard digits -Calc does many of its internal calculations to a slightly higher -precision, but it doesn't always bump the precision up enough. -In each case, Calc added about two digits of precision during -its calculation and then rounded back down to 12 digits -afterward. In one case, it was enough; in the other, it -wasn't. If you really need @var{x} digits of precision, it -never hurts to do the calculation with a few extra guard digits. - -What if we want guard digits but don't want to look at them? -We can set the @dfn{float format}. Calc supports four major -formats for floating-point numbers, called @dfn{normal}, -@dfn{fixed-point}, @dfn{scientific notation}, and @dfn{engineering -notation}. You get them by pressing @w{@kbd{d n}}, @kbd{d f}, -@kbd{d s}, and @kbd{d e}, respectively. In each case, you can -supply a numeric prefix argument which says how many digits -should be displayed. As an example, let's put a few numbers -onto the stack and try some different display modes. First, -use @kbd{M-0 @key{DEL}} to clear the stack, then enter the four -numbers shown here: - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345. 3: 12300. 3: 1.2345e4 3: 1.23e4 3: 12345.000 -2: 123.45 2: 123. 2: 1.2345e2 2: 1.23e2 2: 123.450 -1: 12.345 1: 12.3 1: 1.2345e1 1: 1.23e1 1: 12.345 - . . . . . - - d n M-3 d n d s M-3 d s M-3 d f -@end group -@end smallexample - -@noindent -Notice that when we typed @kbd{M-3 d n}, the numbers were rounded down -to three significant digits, but then when we typed @kbd{d s} all -five significant figures reappeared. The float format does not -affect how numbers are stored, it only affects how they are -displayed. Only the current precision governs the actual rounding -of numbers in the Calculator's memory. - -Engineering notation, not shown here, is like scientific notation -except the exponent (the power-of-ten part) is always adjusted to be -a multiple of three (as in ``kilo,'' ``micro,'' etc.). As a result -there will be one, two, or three digits before the decimal point. - -Whenever you change a display-related mode, Calc redraws everything -in the stack. This may be slow if there are many things on the stack, -so Calc allows you to type shift-@kbd{H} before any mode command to -prevent it from updating the stack. Anything Calc displays after the -mode-changing command will appear in the new format. - -@smallexample -@group -4: 12345 4: 12345 4: 12345 4: 12345 4: 12345 -3: 12345.000 3: 12345.000 3: 12345.000 3: 1.2345e4 3: 12345. -2: 123.450 2: 123.450 2: 1.2345e1 2: 1.2345e1 2: 123.45 -1: 12.345 1: 1.2345e1 1: 1.2345e2 1: 1.2345e2 1: 12.345 - . . . . . - - H d s @key{DEL} U @key{TAB} d @key{SPC} d n -@end group -@end smallexample - -@noindent -Here the @kbd{H d s} command changes to scientific notation but without -updating the screen. Deleting the top stack entry and undoing it back -causes it to show up in the new format; swapping the top two stack -entries reformats both entries. The @kbd{d @key{SPC}} command refreshes the -whole stack. The @kbd{d n} command changes back to the normal float -format; since it doesn't have an @kbd{H} prefix, it also updates all -the stack entries to be in @kbd{d n} format. - -Notice that the integer @expr{12345} was not affected by any -of the float formats. Integers are integers, and are always -displayed exactly. - -@cindex Large numbers, readability -Large integers have their own problems. Let's look back at -the result of @kbd{2^3^4}. - -@example -2417851639229258349412352 -@end example - -@noindent -Quick---how many digits does this have? Try typing @kbd{d g}: - -@example -2,417,851,639,229,258,349,412,352 -@end example - -@noindent -Now how many digits does this have? It's much easier to tell! -We can actually group digits into clumps of any size. Some -people prefer @kbd{M-5 d g}: - -@example -24178,51639,22925,83494,12352 -@end example - -Let's see what happens to floating-point numbers when they are grouped. -First, type @kbd{p 25 @key{RET}} to make sure we have enough precision -to get ourselves into trouble. Now, type @kbd{1e13 /}: - -@example -24,17851,63922.9258349412352 -@end example - -@noindent -The integer part is grouped but the fractional part isn't. Now try -@kbd{M-- M-5 d g} (that's meta-minus-sign, meta-five): - -@example -24,17851,63922.92583,49412,352 -@end example - -If you find it hard to tell the decimal point from the commas, try -changing the grouping character to a space with @kbd{d , @key{SPC}}: - -@example -24 17851 63922.92583 49412 352 -@end example - -Type @kbd{d , ,} to restore the normal grouping character, then -@kbd{d g} again to turn grouping off. Also, press @kbd{p 12} to -restore the default precision. - -Press @kbd{U} enough times to get the original big integer back. -(Notice that @kbd{U} does not undo each mode-setting command; if -you want to undo a mode-setting command, you have to do it yourself.) -Now, type @kbd{d r 16 @key{RET}}: - -@example -16#200000000000000000000 -@end example - -@noindent -The number is now displayed in @dfn{hexadecimal}, or ``base-16'' form. -Suddenly it looks pretty simple; this should be no surprise, since we -got this number by computing a power of two, and 16 is a power of 2. -In fact, we can use @w{@kbd{d r 2 @key{RET}}} to see it in actual binary -form: - -@example -2#1000000000000000000000000000000000000000000000000000000 @dots{} -@end example - -@noindent -We don't have enough space here to show all the zeros! They won't -fit on a typical screen, either, so you will have to use horizontal -scrolling to see them all. Press @kbd{<} and @kbd{>} to scroll the -stack window left and right by half its width. Another way to view -something large is to press @kbd{`} (back-quote) to edit the top of -stack in a separate window. (Press @kbd{C-c C-c} when you are done.) - -You can enter non-decimal numbers using the @kbd{#} symbol, too. -Let's see what the hexadecimal number @samp{5FE} looks like in -binary. Type @kbd{16#5FE} (the letters can be typed in upper or -lower case; they will always appear in upper case). It will also -help to turn grouping on with @kbd{d g}: - -@example -2#101,1111,1110 -@end example - -Notice that @kbd{d g} groups by fours by default if the display radix -is binary or hexadecimal, but by threes if it is decimal, octal, or any -other radix. - -Now let's see that number in decimal; type @kbd{d r 10}: - -@example -1,534 -@end example - -Numbers are not @emph{stored} with any particular radix attached. They're -just numbers; they can be entered in any radix, and are always displayed -in whatever radix you've chosen with @kbd{d r}. The current radix applies -to integers, fractions, and floats. - -@cindex Roundoff errors, in non-decimal numbers -(@bullet{}) @strong{Exercise 1.} Your friend Joe tried to enter one-third -as @samp{3#0.1} in @kbd{d r 3} mode with a precision of 12. He got -@samp{3#0.0222222...} (with 25 2's) in the display. When he multiplied -that by three, he got @samp{3#0.222222...} instead of the expected -@samp{3#1}. Next, Joe entered @samp{3#0.2} and, to his great relief, -saw @samp{3#0.2} on the screen. But when he typed @kbd{2 /}, he got -@samp{3#0.10000001} (some zeros omitted). What's going on here? -@xref{Modes Answer 1, 1}. (@bullet{}) - -@cindex Scientific notation, in non-decimal numbers -(@bullet{}) @strong{Exercise 2.} Scientific notation works in non-decimal -modes in the natural way (the exponent is a power of the radix instead of -a power of ten, although the exponent itself is always written in decimal). -Thus @samp{8#1.23e3 = 8#1230.0}. Suppose we have the hexadecimal number -@samp{f.e8f} times 16 to the 15th power: We write @samp{16#f.e8fe15}. -What is wrong with this picture? What could we write instead that would -work better? @xref{Modes Answer 2, 2}. (@bullet{}) - -The @kbd{m} prefix key has another set of modes, relating to the way -Calc interprets your inputs and does computations. Whereas @kbd{d}-prefix -modes generally affect the way things look, @kbd{m}-prefix modes affect -the way they are actually computed. - -The most popular @kbd{m}-prefix mode is the @dfn{angular mode}. Notice -the @samp{Deg} indicator in the mode line. This means that if you use -a command that interprets a number as an angle, it will assume the -angle is measured in degrees. For example, - -@smallexample -@group -1: 45 1: 0.707106781187 1: 0.500000000001 1: 0.5 - . . . . - - 45 S 2 ^ c 1 -@end group -@end smallexample - -@noindent -The shift-@kbd{S} command computes the sine of an angle. The sine -of 45 degrees is -@texline @math{\sqrt{2}/2}; -@infoline @expr{sqrt(2)/2}; -squaring this yields @expr{2/4 = 0.5}. However, there has been a slight -roundoff error because the representation of -@texline @math{\sqrt{2}/2} -@infoline @expr{sqrt(2)/2} -wasn't exact. The @kbd{c 1} command is a handy way to clean up numbers -in this case; it temporarily reduces the precision by one digit while it -re-rounds the number on the top of the stack. - -@cindex Roundoff errors, examples -(@bullet{}) @strong{Exercise 3.} Your friend Joe computed the sine -of 45 degrees as shown above, then, hoping to avoid an inexact -result, he increased the precision to 16 digits before squaring. -What happened? @xref{Modes Answer 3, 3}. (@bullet{}) - -To do this calculation in radians, we would type @kbd{m r} first. -(The indicator changes to @samp{Rad}.) 45 degrees corresponds to -@cpiover{4} radians. To get @cpi{}, press the @kbd{P} key. (Once -again, this is a shifted capital @kbd{P}. Remember, unshifted -@kbd{p} sets the precision.) - -@smallexample -@group -1: 3.14159265359 1: 0.785398163398 1: 0.707106781187 - . . . - - P 4 / m r S -@end group -@end smallexample - -Likewise, inverse trigonometric functions generate results in -either radians or degrees, depending on the current angular mode. - -@smallexample -@group -1: 0.707106781187 1: 0.785398163398 1: 45. - . . . - - .5 Q m r I S m d U I S -@end group -@end smallexample - -@noindent -Here we compute the Inverse Sine of -@texline @math{\sqrt{0.5}}, -@infoline @expr{sqrt(0.5)}, -first in radians, then in degrees. - -Use @kbd{c d} and @kbd{c r} to convert a number from radians to degrees -and vice-versa. - -@smallexample -@group -1: 45 1: 0.785398163397 1: 45. - . . . - - 45 c r c d -@end group -@end smallexample - -Another interesting mode is @dfn{Fraction mode}. Normally, -dividing two integers produces a floating-point result if the -quotient can't be expressed as an exact integer. Fraction mode -causes integer division to produce a fraction, i.e., a rational -number, instead. - -@smallexample -@group -2: 12 1: 1.33333333333 1: 4:3 -1: 9 . . - . - - 12 @key{RET} 9 / m f U / m f -@end group -@end smallexample - -@noindent -In the first case, we get an approximate floating-point result. -In the second case, we get an exact fractional result (four-thirds). - -You can enter a fraction at any time using @kbd{:} notation. -(Calc uses @kbd{:} instead of @kbd{/} as the fraction separator -because @kbd{/} is already used to divide the top two stack -elements.) Calculations involving fractions will always -produce exact fractional results; Fraction mode only says -what to do when dividing two integers. - -@cindex Fractions vs. floats -@cindex Floats vs. fractions -(@bullet{}) @strong{Exercise 4.} If fractional arithmetic is exact, -why would you ever use floating-point numbers instead? -@xref{Modes Answer 4, 4}. (@bullet{}) - -Typing @kbd{m f} doesn't change any existing values in the stack. -In the above example, we had to Undo the division and do it over -again when we changed to Fraction mode. But if you use the -evaluates-to operator you can get commands like @kbd{m f} to -recompute for you. - -@smallexample -@group -1: 12 / 9 => 1.33333333333 1: 12 / 9 => 1.333 1: 12 / 9 => 4:3 - . . . - - ' 12/9 => @key{RET} p 4 @key{RET} m f -@end group -@end smallexample - -@noindent -In this example, the righthand side of the @samp{=>} operator -on the stack is recomputed when we change the precision, then -again when we change to Fraction mode. All @samp{=>} expressions -on the stack are recomputed every time you change any mode that -might affect their values. - -@node Arithmetic Tutorial, Vector/Matrix Tutorial, Basic Tutorial, Tutorial -@section Arithmetic Tutorial - -@noindent -In this section, we explore the arithmetic and scientific functions -available in the Calculator. - -The standard arithmetic commands are @kbd{+}, @kbd{-}, @kbd{*}, @kbd{/}, -and @kbd{^}. Each normally takes two numbers from the top of the stack -and pushes back a result. The @kbd{n} and @kbd{&} keys perform -change-sign and reciprocal operations, respectively. - -@smallexample -@group -1: 5 1: 0.2 1: 5. 1: -5. 1: 5. - . . . . . - - 5 & & n n -@end group -@end smallexample - -@cindex Binary operators -You can apply a ``binary operator'' like @kbd{+} across any number of -stack entries by giving it a numeric prefix. You can also apply it -pairwise to several stack elements along with the top one if you use -a negative prefix. - -@smallexample -@group -3: 2 1: 9 3: 2 4: 2 3: 12 -2: 3 . 2: 3 3: 3 2: 13 -1: 4 1: 4 2: 4 1: 14 - . . 1: 10 . - . - -2 @key{RET} 3 @key{RET} 4 M-3 + U 10 M-- M-3 + -@end group -@end smallexample - -@cindex Unary operators -You can apply a ``unary operator'' like @kbd{&} to the top @var{n} -stack entries with a numeric prefix, too. - -@smallexample -@group -3: 2 3: 0.5 3: 0.5 -2: 3 2: 0.333333333333 2: 3. -1: 4 1: 0.25 1: 4. - . . . - -2 @key{RET} 3 @key{RET} 4 M-3 & M-2 & -@end group -@end smallexample - -Notice that the results here are left in floating-point form. -We can convert them back to integers by pressing @kbd{F}, the -``floor'' function. This function rounds down to the next lower -integer. There is also @kbd{R}, which rounds to the nearest -integer. - -@smallexample -@group -7: 2. 7: 2 7: 2 -6: 2.4 6: 2 6: 2 -5: 2.5 5: 2 5: 3 -4: 2.6 4: 2 4: 3 -3: -2. 3: -2 3: -2 -2: -2.4 2: -3 2: -2 -1: -2.6 1: -3 1: -3 - . . . - - M-7 F U M-7 R -@end group -@end smallexample - -Since dividing-and-flooring (i.e., ``integer quotient'') is such a -common operation, Calc provides a special command for that purpose, the -backslash @kbd{\}. Another common arithmetic operator is @kbd{%}, which -computes the remainder that would arise from a @kbd{\} operation, i.e., -the ``modulo'' of two numbers. For example, - -@smallexample -@group -2: 1234 1: 12 2: 1234 1: 34 -1: 100 . 1: 100 . - . . - -1234 @key{RET} 100 \ U % -@end group -@end smallexample - -These commands actually work for any real numbers, not just integers. - -@smallexample -@group -2: 3.1415 1: 3 2: 3.1415 1: 0.1415 -1: 1 . 1: 1 . - . . - -3.1415 @key{RET} 1 \ U % -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} The @kbd{\} command would appear to be a -frill, since you could always do the same thing with @kbd{/ F}. Think -of a situation where this is not true---@kbd{/ F} would be inadequate. -Now think of a way you could get around the problem if Calc didn't -provide a @kbd{\} command. @xref{Arithmetic Answer 1, 1}. (@bullet{}) - -We've already seen the @kbd{Q} (square root) and @kbd{S} (sine) -commands. Other commands along those lines are @kbd{C} (cosine), -@kbd{T} (tangent), @kbd{E} (@expr{e^x}) and @kbd{L} (natural -logarithm). These can be modified by the @kbd{I} (inverse) and -@kbd{H} (hyperbolic) prefix keys. - -Let's compute the sine and cosine of an angle, and verify the -identity -@texline @math{\sin^2x + \cos^2x = 1}. -@infoline @expr{sin(x)^2 + cos(x)^2 = 1}. -We'll arbitrarily pick @mathit{-64} degrees as a good value for @expr{x}. -With the angular mode set to degrees (type @w{@kbd{m d}}), do: - -@smallexample -@group -2: -64 2: -64 2: -0.89879 2: -0.89879 1: 1. -1: -64 1: -0.89879 1: -64 1: 0.43837 . - . . . . - - 64 n @key{RET} @key{RET} S @key{TAB} C f h -@end group -@end smallexample - -@noindent -(For brevity, we're showing only five digits of the results here. -You can of course do these calculations to any precision you like.) - -Remember, @kbd{f h} is the @code{calc-hypot}, or square-root of sum -of squares, command. - -Another identity is -@texline @math{\displaystyle\tan x = {\sin x \over \cos x}}. -@infoline @expr{tan(x) = sin(x) / cos(x)}. -@smallexample -@group - -2: -0.89879 1: -2.0503 1: -64. -1: 0.43837 . . - . - - U / I T -@end group -@end smallexample - -A physical interpretation of this calculation is that if you move -@expr{0.89879} units downward and @expr{0.43837} units to the right, -your direction of motion is @mathit{-64} degrees from horizontal. Suppose -we move in the opposite direction, up and to the left: - -@smallexample -@group -2: -0.89879 2: 0.89879 1: -2.0503 1: -64. -1: 0.43837 1: -0.43837 . . - . . - - U U M-2 n / I T -@end group -@end smallexample - -@noindent -How can the angle be the same? The answer is that the @kbd{/} operation -loses information about the signs of its inputs. Because the quotient -is negative, we know exactly one of the inputs was negative, but we -can't tell which one. There is an @kbd{f T} [@code{arctan2}] function which -computes the inverse tangent of the quotient of a pair of numbers. -Since you feed it the two original numbers, it has enough information -to give you a full 360-degree answer. - -@smallexample -@group -2: 0.89879 1: 116. 3: 116. 2: 116. 1: 180. -1: -0.43837 . 2: -0.89879 1: -64. . - . 1: 0.43837 . - . - - U U f T M-@key{RET} M-2 n f T - -@end group -@end smallexample - -@noindent -The resulting angles differ by 180 degrees; in other words, they -point in opposite directions, just as we would expect. - -The @key{META}-@key{RET} we used in the third step is the -``last-arguments'' command. It is sort of like Undo, except that it -restores the arguments of the last command to the stack without removing -the command's result. It is useful in situations like this one, -where we need to do several operations on the same inputs. We could -have accomplished the same thing by using @kbd{M-2 @key{RET}} to duplicate -the top two stack elements right after the @kbd{U U}, then a pair of -@kbd{M-@key{TAB}} commands to cycle the 116 up around the duplicates. - -A similar identity is supposed to hold for hyperbolic sines and cosines, -except that it is the @emph{difference} -@texline @math{\cosh^2x - \sinh^2x} -@infoline @expr{cosh(x)^2 - sinh(x)^2} -that always equals one. Let's try to verify this identity. - -@smallexample -@group -2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 -1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 - . . . . . - - 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ -@end group -@end smallexample - -@noindent -@cindex Roundoff errors, examples -Something's obviously wrong, because when we subtract these numbers -the answer will clearly be zero! But if you think about it, if these -numbers @emph{did} differ by one, it would be in the 55th decimal -place. The difference we seek has been lost entirely to roundoff -error. - -We could verify this hypothesis by doing the actual calculation with, -say, 60 decimal places of precision. This will be slow, but not -enormously so. Try it if you wish; sure enough, the answer is -0.99999, reasonably close to 1. - -Of course, a more reasonable way to verify the identity is to use -a more reasonable value for @expr{x}! - -@cindex Common logarithm -Some Calculator commands use the Hyperbolic prefix for other purposes. -The logarithm and exponential functions, for example, work to the base -@expr{e} normally but use base-10 instead if you use the Hyperbolic -prefix. - -@smallexample -@group -1: 1000 1: 6.9077 1: 1000 1: 3 - . . . . - - 1000 L U H L -@end group -@end smallexample - -@noindent -First, we mistakenly compute a natural logarithm. Then we undo -and compute a common logarithm instead. - -The @kbd{B} key computes a general base-@var{b} logarithm for any -value of @var{b}. - -@smallexample -@group -2: 1000 1: 3 1: 1000. 2: 1000. 1: 6.9077 -1: 10 . . 1: 2.71828 . - . . - - 1000 @key{RET} 10 B H E H P B -@end group -@end smallexample - -@noindent -Here we first use @kbd{B} to compute the base-10 logarithm, then use -the ``hyperbolic'' exponential as a cheap hack to recover the number -1000, then use @kbd{B} again to compute the natural logarithm. Note -that @kbd{P} with the hyperbolic prefix pushes the constant @expr{e} -onto the stack. - -You may have noticed that both times we took the base-10 logarithm -of 1000, we got an exact integer result. Calc always tries to give -an exact rational result for calculations involving rational numbers -where possible. But when we used @kbd{H E}, the result was a -floating-point number for no apparent reason. In fact, if we had -computed @kbd{10 @key{RET} 3 ^} we @emph{would} have gotten an -exact integer 1000. But the @kbd{H E} command is rigged to generate -a floating-point result all of the time so that @kbd{1000 H E} will -not waste time computing a thousand-digit integer when all you -probably wanted was @samp{1e1000}. - -(@bullet{}) @strong{Exercise 2.} Find a pair of integer inputs to -the @kbd{B} command for which Calc could find an exact rational -result but doesn't. @xref{Arithmetic Answer 2, 2}. (@bullet{}) - -The Calculator also has a set of functions relating to combinatorics -and statistics. You may be familiar with the @dfn{factorial} function, -which computes the product of all the integers up to a given number. - -@smallexample -@group -1: 100 1: 93326215443... 1: 100. 1: 9.3326e157 - . . . . - - 100 ! U c f ! -@end group -@end smallexample - -@noindent -Recall, the @kbd{c f} command converts the integer or fraction at the -top of the stack to floating-point format. If you take the factorial -of a floating-point number, you get a floating-point result -accurate to the current precision. But if you give @kbd{!} an -exact integer, you get an exact integer result (158 digits long -in this case). - -If you take the factorial of a non-integer, Calc uses a generalized -factorial function defined in terms of Euler's Gamma function -@texline @math{\Gamma(n)} -@infoline @expr{gamma(n)} -(which is itself available as the @kbd{f g} command). - -@smallexample -@group -3: 4. 3: 24. 1: 5.5 1: 52.342777847 -2: 4.5 2: 52.3427777847 . . -1: 5. 1: 120. - . . - - M-3 ! M-0 @key{DEL} 5.5 f g -@end group -@end smallexample - -@noindent -Here we verify the identity -@texline @math{n! = \Gamma(n+1)}. -@infoline @expr{@var{n}!@: = gamma(@var{n}+1)}. - -The binomial coefficient @var{n}-choose-@var{m} -@texline or @math{\displaystyle {n \choose m}} -is defined by -@texline @math{\displaystyle {n! \over m! \, (n-m)!}} -@infoline @expr{n!@: / m!@: (n-m)!} -for all reals @expr{n} and @expr{m}. The intermediate results in this -formula can become quite large even if the final result is small; the -@kbd{k c} command computes a binomial coefficient in a way that avoids -large intermediate values. - -The @kbd{k} prefix key defines several common functions out of -combinatorics and number theory. Here we compute the binomial -coefficient 30-choose-20, then determine its prime factorization. - -@smallexample -@group -2: 30 1: 30045015 1: [3, 3, 5, 7, 11, 13, 23, 29] -1: 20 . . - . - - 30 @key{RET} 20 k c k f -@end group -@end smallexample - -@noindent -You can verify these prime factors by using @kbd{V R *} to multiply -together the elements of this vector. The result is the original -number, 30045015. - -@cindex Hash tables -Suppose a program you are writing needs a hash table with at least -10000 entries. It's best to use a prime number as the actual size -of a hash table. Calc can compute the next prime number after 10000: - -@smallexample -@group -1: 10000 1: 10007 1: 9973 - . . . - - 10000 k n I k n -@end group -@end smallexample - -@noindent -Just for kicks we've also computed the next prime @emph{less} than -10000. - -@c [fix-ref Financial Functions] -@xref{Financial Functions}, for a description of the Calculator -commands that deal with business and financial calculations (functions -like @code{pv}, @code{rate}, and @code{sln}). - -@c [fix-ref Binary Number Functions] -@xref{Binary Functions}, to read about the commands for operating -on binary numbers (like @code{and}, @code{xor}, and @code{lsh}). - -@node Vector/Matrix Tutorial, Types Tutorial, Arithmetic Tutorial, Tutorial -@section Vector/Matrix Tutorial - -@noindent -A @dfn{vector} is a list of numbers or other Calc data objects. -Calc provides a large set of commands that operate on vectors. Some -are familiar operations from vector analysis. Others simply treat -a vector as a list of objects. - -@menu -* Vector Analysis Tutorial:: -* Matrix Tutorial:: -* List Tutorial:: -@end menu - -@node Vector Analysis Tutorial, Matrix Tutorial, Vector/Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vector Analysis - -@noindent -If you add two vectors, the result is a vector of the sums of the -elements, taken pairwise. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [8, 8, 3] - . 1: [7, 6, 0] . - . - - [1,2,3] s 1 [7 6 0] s 2 + -@end group -@end smallexample - -@noindent -Note that we can separate the vector elements with either commas or -spaces. This is true whether we are using incomplete vectors or -algebraic entry. The @kbd{s 1} and @kbd{s 2} commands save these -vectors so we can easily reuse them later. - -If you multiply two vectors, the result is the sum of the products -of the elements taken pairwise. This is called the @dfn{dot product} -of the vectors. - -@smallexample -@group -2: [1, 2, 3] 1: 19 -1: [7, 6, 0] . - . - - r 1 r 2 * -@end group -@end smallexample - -@cindex Dot product -The dot product of two vectors is equal to the product of their -lengths times the cosine of the angle between them. (Here the vector -is interpreted as a line from the origin @expr{(0,0,0)} to the -specified point in three-dimensional space.) The @kbd{A} -(absolute value) command can be used to compute the length of a -vector. - -@smallexample -@group -3: 19 3: 19 1: 0.550782 1: 56.579 -2: [1, 2, 3] 2: 3.741657 . . -1: [7, 6, 0] 1: 9.219544 - . . - - M-@key{RET} M-2 A * / I C -@end group -@end smallexample - -@noindent -First we recall the arguments to the dot product command, then -we compute the absolute values of the top two stack entries to -obtain the lengths of the vectors, then we divide the dot product -by the product of the lengths to get the cosine of the angle. -The inverse cosine finds that the angle between the vectors -is about 56 degrees. - -@cindex Cross product -@cindex Perpendicular vectors -The @dfn{cross product} of two vectors is a vector whose length -is the product of the lengths of the inputs times the sine of the -angle between them, and whose direction is perpendicular to both -input vectors. Unlike the dot product, the cross product is -defined only for three-dimensional vectors. Let's double-check -our computation of the angle using the cross product. - -@smallexample -@group -2: [1, 2, 3] 3: [-18, 21, -8] 1: [-0.52, 0.61, -0.23] 1: 56.579 -1: [7, 6, 0] 2: [1, 2, 3] . . - . 1: [7, 6, 0] - . - - r 1 r 2 V C s 3 M-@key{RET} M-2 A * / A I S -@end group -@end smallexample - -@noindent -First we recall the original vectors and compute their cross product, -which we also store for later reference. Now we divide the vector -by the product of the lengths of the original vectors. The length of -this vector should be the sine of the angle; sure enough, it is! - -@c [fix-ref General Mode Commands] -Vector-related commands generally begin with the @kbd{v} prefix key. -Some are uppercase letters and some are lowercase. To make it easier -to type these commands, the shift-@kbd{V} prefix key acts the same as -the @kbd{v} key. (@xref{General Mode Commands}, for a way to make all -prefix keys have this property.) - -If we take the dot product of two perpendicular vectors we expect -to get zero, since the cosine of 90 degrees is zero. Let's check -that the cross product is indeed perpendicular to both inputs: - -@smallexample -@group -2: [1, 2, 3] 1: 0 2: [7, 6, 0] 1: 0 -1: [-18, 21, -8] . 1: [-18, 21, -8] . - . . - - r 1 r 3 * @key{DEL} r 2 r 3 * -@end group -@end smallexample - -@cindex Normalizing a vector -@cindex Unit vectors -(@bullet{}) @strong{Exercise 1.} Given a vector on the top of the -stack, what keystrokes would you use to @dfn{normalize} the -vector, i.e., to reduce its length to one without changing its -direction? @xref{Vector Answer 1, 1}. (@bullet{}) - -(@bullet{}) @strong{Exercise 2.} Suppose a certain particle can be -at any of several positions along a ruler. You have a list of -those positions in the form of a vector, and another list of the -probabilities for the particle to be at the corresponding positions. -Find the average position of the particle. -@xref{Vector Answer 2, 2}. (@bullet{}) - -@node Matrix Tutorial, List Tutorial, Vector Analysis Tutorial, Vector/Matrix Tutorial -@subsection Matrices - -@noindent -A @dfn{matrix} is just a vector of vectors, all the same length. -This means you can enter a matrix using nested brackets. You can -also use the semicolon character to enter a matrix. We'll show -both methods here: - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . . - - [[1 2 3] [4 5 6]] ' [1 2 3; 4 5 6] @key{RET} -@end group -@end smallexample - -@noindent -We'll be using this matrix again, so type @kbd{s 4} to save it now. - -Note that semicolons work with incomplete vectors, but they work -better in algebraic entry. That's why we use the apostrophe in -the second example. - -When two matrices are multiplied, the lefthand matrix must have -the same number of columns as the righthand matrix has rows. -Row @expr{i}, column @expr{j} of the result is effectively the -dot product of row @expr{i} of the left matrix by column @expr{j} -of the right matrix. - -If we try to duplicate this matrix and multiply it by itself, -the dimensions are wrong and the multiplication cannot take place: - -@smallexample -@group -1: [ [ 1, 2, 3 ] * [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . - - @key{RET} * -@end group -@end smallexample - -@noindent -Though rather hard to read, this is a formula which shows the product -of two matrices. The @samp{*} function, having invalid arguments, has -been left in symbolic form. - -We can multiply the matrices if we @dfn{transpose} one of them first. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [ [ 14, 32 ] 1: [ [ 17, 22, 27 ] - [ 4, 5, 6 ] ] [ 32, 77 ] ] [ 22, 29, 36 ] -1: [ [ 1, 4 ] . [ 27, 36, 45 ] ] - [ 2, 5 ] . - [ 3, 6 ] ] - . - - U v t * U @key{TAB} * -@end group -@end smallexample - -Matrix multiplication is not commutative; indeed, switching the -order of the operands can even change the dimensions of the result -matrix, as happened here! - -If you multiply a plain vector by a matrix, it is treated as a -single row or column depending on which side of the matrix it is -on. The result is a plain vector which should also be interpreted -as a row or column as appropriate. - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [14, 32] - [ 4, 5, 6 ] ] . -1: [1, 2, 3] - . - - r 4 r 1 * -@end group -@end smallexample - -Multiplying in the other order wouldn't work because the number of -rows in the matrix is different from the number of elements in the -vector. - -(@bullet{}) @strong{Exercise 1.} Use @samp{*} to sum along the rows -of the above -@texline @math{2\times3} -@infoline 2x3 -matrix to get @expr{[6, 15]}. Now use @samp{*} to sum along the columns -to get @expr{[5, 7, 9]}. -@xref{Matrix Answer 1, 1}. (@bullet{}) - -@cindex Identity matrix -An @dfn{identity matrix} is a square matrix with ones along the -diagonal and zeros elsewhere. It has the property that multiplication -by an identity matrix, on the left or on the right, always produces -the original matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 2, 3 ] 1: [ [ 1, 2, 3 ] - [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] [ 4, 5, 6 ] ] - . 1: [ [ 1, 0, 0 ] . - [ 0, 1, 0 ] - [ 0, 0, 1 ] ] - . - - r 4 v i 3 @key{RET} * -@end group -@end smallexample - -If a matrix is square, it is often possible to find its @dfn{inverse}, -that is, a matrix which, when multiplied by the original matrix, yields -an identity matrix. The @kbd{&} (reciprocal) key also computes the -inverse of a matrix. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 1: [ [ -2.4, 1.2, -0.2 ] - [ 4, 5, 6 ] [ 2.8, -1.4, 0.4 ] - [ 7, 6, 0 ] ] [ -0.73333, 0.53333, -0.2 ] ] - . . - - r 4 r 2 | s 5 & -@end group -@end smallexample - -@noindent -The vertical bar @kbd{|} @dfn{concatenates} numbers, vectors, and -matrices together. Here we have used it to add a new row onto -our matrix to make it square. - -We can multiply these two matrices in either order to get an identity. - -@smallexample -@group -1: [ [ 1., 0., 0. ] 1: [ [ 1., 0., 0. ] - [ 0., 1., 0. ] [ 0., 1., 0. ] - [ 0., 0., 1. ] ] [ 0., 0., 1. ] ] - . . - - M-@key{RET} * U @key{TAB} * -@end group -@end smallexample - -@cindex Systems of linear equations -@cindex Linear equations, systems of -Matrix inverses are related to systems of linear equations in algebra. -Suppose we had the following set of equations: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 -@end example -@end group -@end ifnottex -@tex -\turnoffactive -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -This can be cast into the matrix equation, - -@ifnottex -@group -@example - [ [ 1, 2, 3 ] [ [ a ] [ [ 6 ] - [ 4, 5, 6 ] * [ b ] = [ 2 ] - [ 7, 6, 0 ] ] [ c ] ] [ 3 ] ] -@end example -@end group -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 \cr 4 & 5 & 6 \cr 7 & 6 & 0 } - \times - \pmatrix{ a \cr b \cr c } = \pmatrix{ 6 \cr 2 \cr 3 } -$$ -\afterdisplay -@end tex - -We can solve this system of equations by multiplying both sides by the -inverse of the matrix. Calc can do this all in one step: - -@smallexample -@group -2: [6, 2, 3] 1: [-12.6, 15.2, -3.93333] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] ] - . - - [6,2,3] r 5 / -@end group -@end smallexample - -@noindent -The result is the @expr{[a, b, c]} vector that solves the equations. -(Dividing by a square matrix is equivalent to multiplying by its -inverse.) - -Let's verify this solution: - -@smallexample -@group -2: [ [ 1, 2, 3 ] 1: [6., 2., 3.] - [ 4, 5, 6 ] . - [ 7, 6, 0 ] ] -1: [-12.6, 15.2, -3.93333] - . - - r 5 @key{TAB} * -@end group -@end smallexample - -@noindent -Note that we had to be careful about the order in which we multiplied -the matrix and vector. If we multiplied in the other order, Calc would -assume the vector was a row vector in order to make the dimensions -come out right, and the answer would be incorrect. If you -don't feel safe letting Calc take either interpretation of your -vectors, use explicit -@texline @math{N\times1} -@infoline Nx1 -or -@texline @math{1\times N} -@infoline 1xN -matrices instead. In this case, you would enter the original column -vector as @samp{[[6], [2], [3]]} or @samp{[6; 2; 3]}. - -(@bullet{}) @strong{Exercise 2.} Algebraic entry allows you to make -vectors and matrices that include variables. Solve the following -system of equations to get expressions for @expr{x} and @expr{y} -in terms of @expr{a} and @expr{b}. - -@ifnottex -@group -@example - x + a y = 6 - x + b y = 10 -@end example -@end group -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -@noindent -@xref{Matrix Answer 2, 2}. (@bullet{}) - -@cindex Least-squares for over-determined systems -@cindex Over-determined systems of equations -(@bullet{}) @strong{Exercise 3.} A system of equations is ``over-determined'' -if it has more equations than variables. It is often the case that -there are no values for the variables that will satisfy all the -equations at once, but it is still useful to find a set of values -which ``nearly'' satisfy all the equations. In terms of matrix equations, -you can't solve @expr{A X = B} directly because the matrix @expr{A} -is not square for an over-determined system. Matrix inversion works -only for square matrices. One common trick is to multiply both sides -on the left by the transpose of @expr{A}: -@ifnottex -@samp{trn(A)*A*X = trn(A)*B}. -@end ifnottex -@tex -\turnoffactive -$A^T A \, X = A^T B$, where $A^T$ is the transpose \samp{trn(A)}. -@end tex -Now -@texline @math{A^T A} -@infoline @expr{trn(A)*A} -is a square matrix so a solution is possible. It turns out that the -@expr{X} vector you compute in this way will be a ``least-squares'' -solution, which can be regarded as the ``closest'' solution to the set -of equations. Use Calc to solve the following over-determined -system: - -@ifnottex -@group -@example - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end example -@end group -@end ifnottex -@tex -\turnoffactive -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -@noindent -@xref{Matrix Answer 3, 3}. (@bullet{}) - -@node List Tutorial, , Matrix Tutorial, Vector/Matrix Tutorial -@subsection Vectors as Lists - -@noindent -@cindex Lists -Although Calc has a number of features for manipulating vectors and -matrices as mathematical objects, you can also treat vectors as -simple lists of values. For example, we saw that the @kbd{k f} -command returns a vector which is a list of the prime factors of a -number. - -You can pack and unpack stack entries into vectors: - -@smallexample -@group -3: 10 1: [10, 20, 30] 3: 10 -2: 20 . 2: 20 -1: 30 1: 30 - . . - - M-3 v p v u -@end group -@end smallexample - -You can also build vectors out of consecutive integers, or out -of many copies of a given value: - -@smallexample -@group -1: [1, 2, 3, 4] 2: [1, 2, 3, 4] 2: [1, 2, 3, 4] - . 1: 17 1: [17, 17, 17, 17] - . . - - v x 4 @key{RET} 17 v b 4 @key{RET} -@end group -@end smallexample - -You can apply an operator to every element of a vector using the -@dfn{map} command. - -@smallexample -@group -1: [17, 34, 51, 68] 1: [289, 1156, 2601, 4624] 1: [17, 34, 51, 68] - . . . - - V M * 2 V M ^ V M Q -@end group -@end smallexample - -@noindent -In the first step, we multiply the vector of integers by the vector -of 17's elementwise. In the second step, we raise each element to -the power two. (The general rule is that both operands must be -vectors of the same length, or else one must be a vector and the -other a plain number.) In the final step, we take the square root -of each element. - -(@bullet{}) @strong{Exercise 1.} Compute a vector of powers of two -from -@texline @math{2^{-4}} -@infoline @expr{2^-4} -to @expr{2^4}. @xref{List Answer 1, 1}. (@bullet{}) - -You can also @dfn{reduce} a binary operator across a vector. -For example, reducing @samp{*} computes the product of all the -elements in the vector: - -@smallexample -@group -1: 123123 1: [3, 7, 11, 13, 41] 1: 123123 - . . . - - 123123 k f V R * -@end group -@end smallexample - -@noindent -In this example, we decompose 123123 into its prime factors, then -multiply those factors together again to yield the original number. - -We could compute a dot product ``by hand'' using mapping and -reduction: - -@smallexample -@group -2: [1, 2, 3] 1: [7, 12, 0] 1: 19 -1: [7, 6, 0] . . - . - - r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Recalling two vectors from the previous section, we compute the -sum of pairwise products of the elements to get the same answer -for the dot product as before. - -A slight variant of vector reduction is the @dfn{accumulate} operation, -@kbd{V U}. This produces a vector of the intermediate results from -a corresponding reduction. Here we compute a table of factorials: - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6] 1: [1, 2, 6, 24, 120, 720] - . . - - v x 6 @key{RET} V U * -@end group -@end smallexample - -Calc allows vectors to grow as large as you like, although it gets -rather slow if vectors have more than about a hundred elements. -Actually, most of the time is spent formatting these large vectors -for display, not calculating on them. Try the following experiment -(if your computer is very fast you may need to substitute a larger -vector size). - -@smallexample -@group -1: [1, 2, 3, 4, ... 1: [2, 3, 4, 5, ... - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -Now press @kbd{v .} (the letter @kbd{v}, then a period) and try the -experiment again. In @kbd{v .} mode, long vectors are displayed -``abbreviated'' like this: - -@smallexample -@group -1: [1, 2, 3, ..., 500] 1: [2, 3, 4, ..., 501] - . . - - v x 500 @key{RET} 1 V M + -@end group -@end smallexample - -@noindent -(where now the @samp{...} is actually part of the Calc display). -You will find both operations are now much faster. But notice that -even in @w{@kbd{v .}} mode, the full vectors are still shown in the Trail. -Type @w{@kbd{t .}} to cause the trail to abbreviate as well, and try the -experiment one more time. Operations on long vectors are now quite -fast! (But of course if you use @kbd{t .} you will lose the ability -to get old vectors back using the @kbd{t y} command.) - -An easy way to view a full vector when @kbd{v .} mode is active is -to press @kbd{`} (back-quote) to edit the vector; editing always works -with the full, unabbreviated value. - -@cindex Least-squares for fitting a straight line -@cindex Fitting data to a line -@cindex Line, fitting data to -@cindex Data, extracting from buffers -@cindex Columns of data, extracting -As a larger example, let's try to fit a straight line to some data, -using the method of least squares. (Calc has a built-in command for -least-squares curve fitting, but we'll do it by hand here just to -practice working with vectors.) Suppose we have the following list -of values in a file we have loaded into Emacs: - -@smallexample - x y - --- --- - 1.34 0.234 - 1.41 0.298 - 1.49 0.402 - 1.56 0.412 - 1.64 0.466 - 1.73 0.473 - 1.82 0.601 - 1.91 0.519 - 2.01 0.603 - 2.11 0.637 - 2.22 0.645 - 2.33 0.705 - 2.45 0.917 - 2.58 1.009 - 2.71 0.971 - 2.85 1.062 - 3.00 1.148 - 3.15 1.157 - 3.32 1.354 -@end smallexample - -@noindent -If you are reading this tutorial in printed form, you will find it -easiest to press @kbd{C-x * i} to enter the on-line Info version of -the manual and find this table there. (Press @kbd{g}, then type -@kbd{List Tutorial}, to jump straight to this section.) - -Position the cursor at the upper-left corner of this table, just -to the left of the @expr{1.34}. Press @kbd{C-@@} to set the mark. -(On your system this may be @kbd{C-2}, @kbd{C-@key{SPC}}, or @kbd{NUL}.) -Now position the cursor to the lower-right, just after the @expr{1.354}. -You have now defined this region as an Emacs ``rectangle.'' Still -in the Info buffer, type @kbd{C-x * r}. This command -(@code{calc-grab-rectangle}) will pop you back into the Calculator, with -the contents of the rectangle you specified in the form of a matrix. - -@smallexample -@group -1: [ [ 1.34, 0.234 ] - [ 1.41, 0.298 ] - @dots{} -@end group -@end smallexample - -@noindent -(You may wish to use @kbd{v .} mode to abbreviate the display of this -large matrix.) - -We want to treat this as a pair of lists. The first step is to -transpose this matrix into a pair of rows. Remember, a matrix is -just a vector of vectors. So we can unpack the matrix into a pair -of row vectors on the stack. - -@smallexample -@group -1: [ [ 1.34, 1.41, 1.49, ... ] 2: [1.34, 1.41, 1.49, ... ] - [ 0.234, 0.298, 0.402, ... ] ] 1: [0.234, 0.298, 0.402, ... ] - . . - - v t v u -@end group -@end smallexample - -@noindent -Let's store these in quick variables 1 and 2, respectively. - -@smallexample -@group -1: [1.34, 1.41, 1.49, ... ] . - . - - t 2 t 1 -@end group -@end smallexample - -@noindent -(Recall that @kbd{t 2} is a variant of @kbd{s 2} that removes the -stored value from the stack.) - -In a least squares fit, the slope @expr{m} is given by the formula - -@ifnottex -@example -m = (N sum(x y) - sum(x) sum(y)) / (N sum(x^2) - sum(x)^2) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ m = {N \sum x y - \sum x \sum y \over - N \sum x^2 - \left( \sum x \right)^2} $$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum x} -@infoline @expr{sum(x)} -represents the sum of all the values of @expr{x}. While there is an -actual @code{sum} function in Calc, it's easier to sum a vector using a -simple reduction. First, let's compute the four different sums that -this formula uses. - -@smallexample -@group -1: 41.63 1: 98.0003 - . . - - r 1 V R + t 3 r 1 2 V M ^ V R + t 4 - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 13.613 1: 33.36554 - . . - - r 2 V R + t 5 r 1 r 2 V M * V R + t 6 -@end group -@end smallexample - -@ifnottex -@noindent -These are @samp{sum(x)}, @samp{sum(x^2)}, @samp{sum(y)}, and @samp{sum(x y)}, -respectively. (We could have used @kbd{*} to compute @samp{sum(x^2)} and -@samp{sum(x y)}.) -@end ifnottex -@tex -\turnoffactive -These are $\sum x$, $\sum x^2$, $\sum y$, and $\sum x y$, -respectively. (We could have used \kbd{*} to compute $\sum x^2$ and -$\sum x y$.) -@end tex - -Finally, we also need @expr{N}, the number of data points. This is just -the length of either of our lists. - -@smallexample -@group -1: 19 - . - - r 1 v l t 7 -@end group -@end smallexample - -@noindent -(That's @kbd{v} followed by a lower-case @kbd{l}.) - -Now we grind through the formula: - -@smallexample -@group -1: 633.94526 2: 633.94526 1: 67.23607 - . 1: 566.70919 . - . - - r 7 r 6 * r 3 r 5 * - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 67.23607 3: 67.23607 2: 67.23607 1: 0.52141679 -1: 1862.0057 2: 1862.0057 1: 128.9488 . - . 1: 1733.0569 . - . - - r 7 r 4 * r 3 2 ^ - / t 8 -@end group -@end smallexample - -That gives us the slope @expr{m}. The y-intercept @expr{b} can now -be found with the simple formula, - -@ifnottex -@example -b = (sum(y) - m sum(x)) / N -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ b = {\sum y - m \sum x \over N} $$ -\afterdisplay -\vskip10pt -@end tex - -@smallexample -@group -1: 13.613 2: 13.613 1: -8.09358 1: -0.425978 - . 1: 21.70658 . . - . - - r 5 r 8 r 3 * - r 7 / t 9 -@end group -@end smallexample - -Let's ``plot'' this straight line approximation, -@texline @math{y \approx m x + b}, -@infoline @expr{m x + b}, -and compare it with the original data. - -@smallexample -@group -1: [0.699, 0.735, ... ] 1: [0.273, 0.309, ... ] - . . - - r 1 r 8 * r 9 + s 0 -@end group -@end smallexample - -@noindent -Notice that multiplying a vector by a constant, and adding a constant -to a vector, can be done without mapping commands since these are -common operations from vector algebra. As far as Calc is concerned, -we've just been doing geometry in 19-dimensional space! - -We can subtract this vector from our original @expr{y} vector to get -a feel for the error of our fit. Let's find the maximum error: - -@smallexample -@group -1: [0.0387, 0.0112, ... ] 1: [0.0387, 0.0112, ... ] 1: 0.0897 - . . . - - r 2 - V M A V R X -@end group -@end smallexample - -@noindent -First we compute a vector of differences, then we take the absolute -values of these differences, then we reduce the @code{max} function -across the vector. (The @code{max} function is on the two-key sequence -@kbd{f x}; because it is so common to use @code{max} in a vector -operation, the letters @kbd{X} and @kbd{N} are also accepted for -@code{max} and @code{min} in this context. In general, you answer -the @kbd{V M} or @kbd{V R} prompt with the actual key sequence that -invokes the function you want. You could have typed @kbd{V R f x} or -even @kbd{V R x max @key{RET}} if you had preferred.) - -If your system has the GNUPLOT program, you can see graphs of your -data and your straight line to see how well they match. (If you have -GNUPLOT 3.0 or higher, the following instructions will work regardless -of the kind of display you have. Some GNUPLOT 2.0, non-X-windows systems -may require additional steps to view the graphs.) - -Let's start by plotting the original data. Recall the ``@var{x}'' and ``@var{y}'' -vectors onto the stack and press @kbd{g f}. This ``fast'' graphing -command does everything you need to do for simple, straightforward -plotting of data. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.234, 0.298, 0.402, ... ] - . - - r 1 r 2 g f -@end group -@end smallexample - -If all goes well, you will shortly get a new window containing a graph -of the data. (If not, contact your GNUPLOT or Calc installer to find -out what went wrong.) In the X window system, this will be a separate -graphics window. For other kinds of displays, the default is to -display the graph in Emacs itself using rough character graphics. -Press @kbd{q} when you are done viewing the character graphics. - -Next, let's add the line we got from our least-squares fit. -@ifinfo -(If you are reading this tutorial on-line while running Calc, typing -@kbd{g a} may cause the tutorial to disappear from its window and be -replaced by a buffer named @samp{*Gnuplot Commands*}. The tutorial -will reappear when you terminate GNUPLOT by typing @kbd{g q}.) -@end ifinfo - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] -1: [0.273, 0.309, 0.351, ... ] - . - - @key{DEL} r 0 g a g p -@end group -@end smallexample - -It's not very useful to get symbols to mark the data points on this -second curve; you can type @kbd{g S g p} to remove them. Type @kbd{g q} -when you are done to remove the X graphics window and terminate GNUPLOT. - -(@bullet{}) @strong{Exercise 2.} An earlier exercise showed how to do -least squares fitting to a general system of equations. Our 19 data -points are really 19 equations of the form @expr{y_i = m x_i + b} for -different pairs of @expr{(x_i,y_i)}. Use the matrix-transpose method -to solve for @expr{m} and @expr{b}, duplicating the above result. -@xref{List Answer 2, 2}. (@bullet{}) - -@cindex Geometric mean -(@bullet{}) @strong{Exercise 3.} If the input data do not form a -rectangle, you can use @w{@kbd{C-x * g}} (@code{calc-grab-region}) -to grab the data the way Emacs normally works with regions---it reads -left-to-right, top-to-bottom, treating line breaks the same as spaces. -Use this command to find the geometric mean of the following numbers. -(The geometric mean is the @var{n}th root of the product of @var{n} numbers.) - -@example -2.3 6 22 15.1 7 - 15 14 7.5 - 2.5 -@end example - -@noindent -The @kbd{C-x * g} command accepts numbers separated by spaces or commas, -with or without surrounding vector brackets. -@xref{List Answer 3, 3}. (@bullet{}) - -@ifnottex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -@var{n}-choose-0 minus @var{n}-choose-1 plus @var{n}-choose-2, and so -on up to @var{n}-choose-@var{n}, -always comes out to zero. Let's verify this -for @expr{n=6}. -@end ifnottex -@tex -As another example, a theorem about binomial coefficients tells -us that the alternating sum of binomial coefficients -${n \choose 0} - {n \choose 1} + {n \choose 2} - \cdots \pm {n \choose n}$ -always comes out to zero. Let's verify this -for \cite{n=6}. -@end tex - -@smallexample -@group -1: [1, 2, 3, 4, 5, 6, 7] 1: [0, 1, 2, 3, 4, 5, 6] - . . - - v x 7 @key{RET} 1 - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, -6, 15, -20, 15, -6, 1] 1: 0 - . . - - V M ' (-1)^$ choose(6,$) @key{RET} V R + -@end group -@end smallexample - -The @kbd{V M '} command prompts you to enter any algebraic expression -to define the function to map over the vector. The symbol @samp{$} -inside this expression represents the argument to the function. -The Calculator applies this formula to each element of the vector, -substituting each element's value for the @samp{$} sign(s) in turn. - -To define a two-argument function, use @samp{$$} for the first -argument and @samp{$} for the second: @kbd{V M ' $$-$ @key{RET}} is -equivalent to @kbd{V M -}. This is analogous to regular algebraic -entry, where @samp{$$} would refer to the next-to-top stack entry -and @samp{$} would refer to the top stack entry, and @kbd{' $$-$ @key{RET}} -would act exactly like @kbd{-}. - -Notice that the @kbd{V M '} command has recorded two things in the -trail: The result, as usual, and also a funny-looking thing marked -@samp{oper} that represents the operator function you typed in. -The function is enclosed in @samp{< >} brackets, and the argument is -denoted by a @samp{#} sign. If there were several arguments, they -would be shown as @samp{#1}, @samp{#2}, and so on. (For example, -@kbd{V M ' $$-$} will put the function @samp{<#1 - #2>} on the -trail.) This object is a ``nameless function''; you can use nameless -@w{@samp{< >}} notation to answer the @kbd{V M '} prompt if you like. -Nameless function notation has the interesting, occasionally useful -property that a nameless function is not actually evaluated until -it is used. For example, @kbd{V M ' $+random(2.0)} evaluates -@samp{random(2.0)} once and adds that random number to all elements -of the vector, but @kbd{V M ' <#+random(2.0)>} evaluates the -@samp{random(2.0)} separately for each vector element. - -Another group of operators that are often useful with @kbd{V M} are -the relational operators: @kbd{a =}, for example, compares two numbers -and gives the result 1 if they are equal, or 0 if not. Similarly, -@w{@kbd{a <}} checks for one number being less than another. - -Other useful vector operations include @kbd{v v}, to reverse a -vector end-for-end; @kbd{V S}, to sort the elements of a vector -into increasing order; and @kbd{v r} and @w{@kbd{v c}}, to extract -one row or column of a matrix, or (in both cases) to extract one -element of a plain vector. With a negative argument, @kbd{v r} -and @kbd{v c} instead delete one row, column, or vector element. - -@cindex Divisor functions -(@bullet{}) @strong{Exercise 4.} The @expr{k}th @dfn{divisor function} -@tex -$\sigma_k(n)$ -@end tex -is the sum of the @expr{k}th powers of all the divisors of an -integer @expr{n}. Figure out a method for computing the divisor -function for reasonably small values of @expr{n}. As a test, -the 0th and 1st divisor functions of 30 are 8 and 72, respectively. -@xref{List Answer 4, 4}. (@bullet{}) - -@cindex Square-free numbers -@cindex Duplicate values in a list -(@bullet{}) @strong{Exercise 5.} The @kbd{k f} command produces a -list of prime factors for a number. Sometimes it is important to -know that a number is @dfn{square-free}, i.e., that no prime occurs -more than once in its list of prime factors. Find a sequence of -keystrokes to tell if a number is square-free; your method should -leave 1 on the stack if it is, or 0 if it isn't. -@xref{List Answer 5, 5}. (@bullet{}) - -@cindex Triangular lists -(@bullet{}) @strong{Exercise 6.} Build a list of lists that looks -like the following diagram. (You may wish to use the @kbd{v /} -command to enable multi-line display of vectors.) - -@smallexample -@group -1: [ [1], - [1, 2], - [1, 2, 3], - [1, 2, 3, 4], - [1, 2, 3, 4, 5], - [1, 2, 3, 4, 5, 6] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 6, 6}. (@bullet{}) - -(@bullet{}) @strong{Exercise 7.} Build the following list of lists. - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] -@end group -@end smallexample - -@noindent -@xref{List Answer 7, 7}. (@bullet{}) - -@cindex Maximizing a function over a list of values -@c [fix-ref Numerical Solutions] -(@bullet{}) @strong{Exercise 8.} Compute a list of values of Bessel's -@texline @math{J_1(x)} -@infoline @expr{J1} -function @samp{besJ(1,x)} for @expr{x} from 0 to 5 in steps of 0.25. -Find the value of @expr{x} (from among the above set of values) for -which @samp{besJ(1,x)} is a maximum. Use an ``automatic'' method, -i.e., just reading along the list by hand to find the largest value -is not allowed! (There is an @kbd{a X} command which does this kind -of thing automatically; @pxref{Numerical Solutions}.) -@xref{List Answer 8, 8}. (@bullet{}) - -@cindex Digits, vectors of -(@bullet{}) @strong{Exercise 9.} You are given an integer in the range -@texline @math{0 \le N < 10^m} -@infoline @expr{0 <= N < 10^m} -for @expr{m=12} (i.e., an integer of less than -twelve digits). Convert this integer into a vector of @expr{m} -digits, each in the range from 0 to 9. In vector-of-digits notation, -add one to this integer to produce a vector of @expr{m+1} digits -(since there could be a carry out of the most significant digit). -Convert this vector back into a regular integer. A good integer -to try is 25129925999. @xref{List Answer 9, 9}. (@bullet{}) - -(@bullet{}) @strong{Exercise 10.} Your friend Joe tried to use -@kbd{V R a =} to test if all numbers in a list were equal. What -happened? How would you do this test? @xref{List Answer 10, 10}. (@bullet{}) - -(@bullet{}) @strong{Exercise 11.} The area of a circle of radius one -is @cpi{}. The area of the -@texline @math{2\times2} -@infoline 2x2 -square that encloses that circle is 4. So if we throw @var{n} darts at -random points in the square, about @cpiover{4} of them will land inside -the circle. This gives us an entertaining way to estimate the value of -@cpi{}. The @w{@kbd{k r}} -command picks a random number between zero and the value on the stack. -We could get a random floating-point number between @mathit{-1} and 1 by typing -@w{@kbd{2.0 k r 1 -}}. Build a vector of 100 random @expr{(x,y)} points in -this square, then use vector mapping and reduction to count how many -points lie inside the unit circle. Hint: Use the @kbd{v b} command. -@xref{List Answer 11, 11}. (@bullet{}) - -@cindex Matchstick problem -(@bullet{}) @strong{Exercise 12.} The @dfn{matchstick problem} provides -another way to calculate @cpi{}. Say you have an infinite field -of vertical lines with a spacing of one inch. Toss a one-inch matchstick -onto the field. The probability that the matchstick will land crossing -a line turns out to be -@texline @math{2/\pi}. -@infoline @expr{2/pi}. -Toss 100 matchsticks to estimate @cpi{}. (If you want still more fun, -the probability that the GCD (@w{@kbd{k g}}) of two large integers is -one turns out to be -@texline @math{6/\pi^2}. -@infoline @expr{6/pi^2}. -That provides yet another way to estimate @cpi{}.) -@xref{List Answer 12, 12}. (@bullet{}) - -(@bullet{}) @strong{Exercise 13.} An algebraic entry of a string in -double-quote marks, @samp{"hello"}, creates a vector of the numerical -(ASCII) codes of the characters (here, @expr{[104, 101, 108, 108, 111]}). -Sometimes it is convenient to compute a @dfn{hash code} of a string, -which is just an integer that represents the value of that string. -Two equal strings have the same hash code; two different strings -@dfn{probably} have different hash codes. (For example, Calc has -over 400 function names, but Emacs can quickly find the definition for -any given name because it has sorted the functions into ``buckets'' by -their hash codes. Sometimes a few names will hash into the same bucket, -but it is easier to search among a few names than among all the names.) -One popular hash function is computed as follows: First set @expr{h = 0}. -Then, for each character from the string in turn, set @expr{h = 3h + c_i} -where @expr{c_i} is the character's ASCII code. If we have 511 buckets, -we then take the hash code modulo 511 to get the bucket number. Develop a -simple command or commands for converting string vectors into hash codes. -The hash code for @samp{"Testing, 1, 2, 3"} is 1960915098, which modulo -511 is 121. @xref{List Answer 13, 13}. (@bullet{}) - -(@bullet{}) @strong{Exercise 14.} The @kbd{H V R} and @kbd{H V U} -commands do nested function evaluations. @kbd{H V U} takes a starting -value and a number of steps @var{n} from the stack; it then applies the -function you give to the starting value 0, 1, 2, up to @var{n} times -and returns a vector of the results. Use this command to create a -``random walk'' of 50 steps. Start with the two-dimensional point -@expr{(0,0)}; then take one step a random distance between @mathit{-1} and 1 -in both @expr{x} and @expr{y}; then take another step, and so on. Use the -@kbd{g f} command to display this random walk. Now modify your random -walk to walk a unit distance, but in a random direction, at each step. -(Hint: The @code{sincos} function returns a vector of the cosine and -sine of an angle.) @xref{List Answer 14, 14}. (@bullet{}) - -@node Types Tutorial, Algebra Tutorial, Vector/Matrix Tutorial, Tutorial -@section Types Tutorial - -@noindent -Calc understands a variety of data types as well as simple numbers. -In this section, we'll experiment with each of these types in turn. - -The numbers we've been using so far have mainly been either @dfn{integers} -or @dfn{floats}. We saw that floats are usually a good approximation to -the mathematical concept of real numbers, but they are only approximations -and are susceptible to roundoff error. Calc also supports @dfn{fractions}, -which can exactly represent any rational number. - -@smallexample -@group -1: 3628800 2: 3628800 1: 518400:7 1: 518414:7 1: 7:518414 - . 1: 49 . . . - . - - 10 ! 49 @key{RET} : 2 + & -@end group -@end smallexample - -@noindent -The @kbd{:} command divides two integers to get a fraction; @kbd{/} -would normally divide integers to get a floating-point result. -Notice we had to type @key{RET} between the @kbd{49} and the @kbd{:} -since the @kbd{:} would otherwise be interpreted as part of a -fraction beginning with 49. - -You can convert between floating-point and fractional format using -@kbd{c f} and @kbd{c F}: - -@smallexample -@group -1: 1.35027217629e-5 1: 7:518414 - . . - - c f c F -@end group -@end smallexample - -The @kbd{c F} command replaces a floating-point number with the -``simplest'' fraction whose floating-point representation is the -same, to within the current precision. - -@smallexample -@group -1: 3.14159265359 1: 1146408:364913 1: 3.1416 1: 355:113 - . . . . - - P c F @key{DEL} p 5 @key{RET} P c F -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} A calculation has produced the -result 1.26508260337. You suspect it is the square root of the -product of @cpi{} and some rational number. Is it? (Be sure -to allow for roundoff error!) @xref{Types Answer 1, 1}. (@bullet{}) - -@dfn{Complex numbers} can be stored in both rectangular and polar form. - -@smallexample -@group -1: -9 1: (0, 3) 1: (3; 90.) 1: (6; 90.) 1: (2.4495; 45.) - . . . . . - - 9 n Q c p 2 * Q -@end group -@end smallexample - -@noindent -The square root of @mathit{-9} is by default rendered in rectangular form -(@w{@expr{0 + 3i}}), but we can convert it to polar form (3 with a -phase angle of 90 degrees). All the usual arithmetic and scientific -operations are defined on both types of complex numbers. - -Another generalized kind of number is @dfn{infinity}. Infinity -isn't really a number, but it can sometimes be treated like one. -Calc uses the symbol @code{inf} to represent positive infinity, -i.e., a value greater than any real number. Naturally, you can -also write @samp{-inf} for minus infinity, a value less than any -real number. The word @code{inf} can only be input using -algebraic entry. - -@smallexample -@group -2: inf 2: -inf 2: -inf 2: -inf 1: nan -1: -17 1: -inf 1: -inf 1: inf . - . . . . - -' inf @key{RET} 17 n * @key{RET} 72 + A + -@end group -@end smallexample - -@noindent -Since infinity is infinitely large, multiplying it by any finite -number (like @mathit{-17}) has no effect, except that since @mathit{-17} -is negative, it changes a plus infinity to a minus infinity. -(``A huge positive number, multiplied by @mathit{-17}, yields a huge -negative number.'') Adding any finite number to infinity also -leaves it unchanged. Taking an absolute value gives us plus -infinity again. Finally, we add this plus infinity to the minus -infinity we had earlier. If you work it out, you might expect -the answer to be @mathit{-72} for this. But the 72 has been completely -lost next to the infinities; by the time we compute @w{@samp{inf - inf}} -the finite difference between them, if any, is undetectable. -So we say the result is @dfn{indeterminate}, which Calc writes -with the symbol @code{nan} (for Not A Number). - -Dividing by zero is normally treated as an error, but you can get -Calc to write an answer in terms of infinity by pressing @kbd{m i} -to turn on Infinite mode. - -@smallexample -@group -3: nan 2: nan 2: nan 2: nan 1: nan -2: 1 1: 1 / 0 1: uinf 1: uinf . -1: 0 . . . - . - - 1 @key{RET} 0 / m i U / 17 n * + -@end group -@end smallexample - -@noindent -Dividing by zero normally is left unevaluated, but after @kbd{m i} -it instead gives an infinite result. The answer is actually -@code{uinf}, ``undirected infinity.'' If you look at a graph of -@expr{1 / x} around @w{@expr{x = 0}}, you'll see that it goes toward -plus infinity as you approach zero from above, but toward minus -infinity as you approach from below. Since we said only @expr{1 / 0}, -Calc knows that the answer is infinite but not in which direction. -That's what @code{uinf} means. Notice that multiplying @code{uinf} -by a negative number still leaves plain @code{uinf}; there's no -point in saying @samp{-uinf} because the sign of @code{uinf} is -unknown anyway. Finally, we add @code{uinf} to our @code{nan}, -yielding @code{nan} again. It's easy to see that, because -@code{nan} means ``totally unknown'' while @code{uinf} means -``unknown sign but known to be infinite,'' the more mysterious -@code{nan} wins out when it is combined with @code{uinf}, or, for -that matter, with anything else. - -(@bullet{}) @strong{Exercise 2.} Predict what Calc will answer -for each of these formulas: @samp{inf / inf}, @samp{exp(inf)}, -@samp{exp(-inf)}, @samp{sqrt(-inf)}, @samp{sqrt(uinf)}, -@samp{abs(uinf)}, @samp{ln(0)}. -@xref{Types Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} We saw that @samp{inf - inf = nan}, -which stands for an unknown value. Can @code{nan} stand for -a complex number? Can it stand for infinity? -@xref{Types Answer 3, 3}. (@bullet{}) - -@dfn{HMS forms} represent a value in terms of hours, minutes, and -seconds. - -@smallexample -@group -1: 2@@ 30' 0" 1: 3@@ 30' 0" 2: 3@@ 30' 0" 1: 2. - . . 1: 1@@ 45' 0." . - . - - 2@@ 30' @key{RET} 1 + @key{RET} 2 / / -@end group -@end smallexample - -HMS forms can also be used to hold angles in degrees, minutes, and -seconds. - -@smallexample -@group -1: 0.5 1: 26.56505 1: 26@@ 33' 54.18" 1: 0.44721 - . . . . - - 0.5 I T c h S -@end group -@end smallexample - -@noindent -First we convert the inverse tangent of 0.5 to degrees-minutes-seconds -form, then we take the sine of that angle. Note that the trigonometric -functions will accept HMS forms directly as input. - -@cindex Beatles -(@bullet{}) @strong{Exercise 4.} The Beatles' @emph{Abbey Road} is -47 minutes and 26 seconds long, and contains 17 songs. What is the -average length of a song on @emph{Abbey Road}? If the Extended Disco -Version of @emph{Abbey Road} added 20 seconds to the length of each -song, how long would the album be? @xref{Types Answer 4, 4}. (@bullet{}) - -A @dfn{date form} represents a date, or a date and time. Dates must -be entered using algebraic entry. Date forms are surrounded by -@samp{< >} symbols; most standard formats for dates are recognized. - -@smallexample -@group -2: 1: 2.25 -1: <6:00pm Thu Jan 10, 1991> . - . - -' <13 Jan 1991>, <1/10/91, 6pm> @key{RET} - -@end group -@end smallexample - -@noindent -In this example, we enter two dates, then subtract to find the -number of days between them. It is also possible to add an -HMS form or a number (of days) to a date form to get another -date form. - -@smallexample -@group -1: <4:45:59pm Mon Jan 14, 1991> 1: <2:50:59am Thu Jan 17, 1991> - . . - - t N 2 + 10@@ 5' + -@end group -@end smallexample - -@c [fix-ref Date Arithmetic] -@noindent -The @kbd{t N} (``now'') command pushes the current date and time on the -stack; then we add two days, ten hours and five minutes to the date and -time. Other date-and-time related commands include @kbd{t J}, which -does Julian day conversions, @kbd{t W}, which finds the beginning of -the week in which a date form lies, and @kbd{t I}, which increments a -date by one or several months. @xref{Date Arithmetic}, for more. - -(@bullet{}) @strong{Exercise 5.} How many days until the next -Friday the 13th? @xref{Types Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} How many leap years will there be -between now and the year 10001 A.D.? @xref{Types Answer 6, 6}. (@bullet{}) - -@cindex Slope and angle of a line -@cindex Angle and slope of a line -An @dfn{error form} represents a mean value with an attached standard -deviation, or error estimate. Suppose our measurements indicate that -a certain telephone pole is about 30 meters away, with an estimated -error of 1 meter, and 8 meters tall, with an estimated error of 0.2 -meters. What is the slope of a line from here to the top of the -pole, and what is the equivalent angle in degrees? - -@smallexample -@group -1: 8 +/- 0.2 2: 8 +/- 0.2 1: 0.266 +/- 0.011 1: 14.93 +/- 0.594 - . 1: 30 +/- 1 . . - . - - 8 p .2 @key{RET} 30 p 1 / I T -@end group -@end smallexample - -@noindent -This means that the angle is about 15 degrees, and, assuming our -original error estimates were valid standard deviations, there is about -a 60% chance that the result is correct within 0.59 degrees. - -@cindex Torus, volume of -(@bullet{}) @strong{Exercise 7.} The volume of a torus (a donut shape) is -@texline @math{2 \pi^2 R r^2} -@infoline @w{@expr{2 pi^2 R r^2}} -where @expr{R} is the radius of the circle that -defines the center of the tube and @expr{r} is the radius of the tube -itself. Suppose @expr{R} is 20 cm and @expr{r} is 4 cm, each known to -within 5 percent. What is the volume and the relative uncertainty of -the volume? @xref{Types Answer 7, 7}. (@bullet{}) - -An @dfn{interval form} represents a range of values. While an -error form is best for making statistical estimates, intervals give -you exact bounds on an answer. Suppose we additionally know that -our telephone pole is definitely between 28 and 31 meters away, -and that it is between 7.7 and 8.1 meters tall. - -@smallexample -@group -1: [7.7 .. 8.1] 2: [7.7 .. 8.1] 1: [0.24 .. 0.28] 1: [13.9 .. 16.1] - . 1: [28 .. 31] . . - . - - [ 7.7 .. 8.1 ] [ 28 .. 31 ] / I T -@end group -@end smallexample - -@noindent -If our bounds were correct, then the angle to the top of the pole -is sure to lie in the range shown. - -The square brackets around these intervals indicate that the endpoints -themselves are allowable values. In other words, the distance to the -telephone pole is between 28 and 31, @emph{inclusive}. You can also -make an interval that is exclusive of its endpoints by writing -parentheses instead of square brackets. You can even make an interval -which is inclusive (``closed'') on one end and exclusive (``open'') on -the other. - -@smallexample -@group -1: [1 .. 10) 1: (0.1 .. 1] 2: (0.1 .. 1] 1: (0.2 .. 3) - . . 1: [2 .. 3) . - . - - [ 1 .. 10 ) & [ 2 .. 3 ) * -@end group -@end smallexample - -@noindent -The Calculator automatically keeps track of which end values should -be open and which should be closed. You can also make infinite or -semi-infinite intervals by using @samp{-inf} or @samp{inf} for one -or both endpoints. - -(@bullet{}) @strong{Exercise 8.} What answer would you expect from -@samp{@w{1 /} @w{(0 .. 10)}}? What about @samp{@w{1 /} @w{(-10 .. 0)}}? What -about @samp{@w{1 /} @w{[0 .. 10]}} (where the interval actually includes -zero)? What about @samp{@w{1 /} @w{(-10 .. 10)}}? -@xref{Types Answer 8, 8}. (@bullet{}) - -(@bullet{}) @strong{Exercise 9.} Two easy ways of squaring a number -are @kbd{@key{RET} *} and @w{@kbd{2 ^}}. Normally these produce the same -answer. Would you expect this still to hold true for interval forms? -If not, which of these will result in a larger interval? -@xref{Types Answer 9, 9}. (@bullet{}) - -A @dfn{modulo form} is used for performing arithmetic modulo @var{m}. -For example, arithmetic involving time is generally done modulo 12 -or 24 hours. - -@smallexample -@group -1: 17 mod 24 1: 3 mod 24 1: 21 mod 24 1: 9 mod 24 - . . . . - - 17 M 24 @key{RET} 10 + n 5 / -@end group -@end smallexample - -@noindent -In this last step, Calc has divided by 5 modulo 24; i.e., it has found a -new number which, when multiplied by 5 modulo 24, produces the original -number, 21. If @var{m} is prime and the divisor is not a multiple of -@var{m}, it is always possible to find such a number. For non-prime -@var{m} like 24, it is only sometimes possible. - -@smallexample -@group -1: 10 mod 24 1: 16 mod 24 1: 1000000... 1: 16 - . . . . - - 10 M 24 @key{RET} 100 ^ 10 @key{RET} 100 ^ 24 % -@end group -@end smallexample - -@noindent -These two calculations get the same answer, but the first one is -much more efficient because it avoids the huge intermediate value -that arises in the second one. - -@cindex Fermat, primality test of -(@bullet{}) @strong{Exercise 10.} A theorem of Pierre de Fermat -says that -@texline @w{@math{x^{n-1} \bmod n = 1}} -@infoline @expr{x^(n-1) mod n = 1} -if @expr{n} is a prime number and @expr{x} is an integer less than -@expr{n}. If @expr{n} is @emph{not} a prime number, this will -@emph{not} be true for most values of @expr{x}. Thus we can test -informally if a number is prime by trying this formula for several -values of @expr{x}. Use this test to tell whether the following numbers -are prime: 811749613, 15485863. @xref{Types Answer 10, 10}. (@bullet{}) - -It is possible to use HMS forms as parts of error forms, intervals, -modulo forms, or as the phase part of a polar complex number. -For example, the @code{calc-time} command pushes the current time -of day on the stack as an HMS/modulo form. - -@smallexample -@group -1: 17@@ 34' 45" mod 24@@ 0' 0" 1: 6@@ 22' 15" mod 24@@ 0' 0" - . . - - x time @key{RET} n -@end group -@end smallexample - -@noindent -This calculation tells me it is six hours and 22 minutes until midnight. - -(@bullet{}) @strong{Exercise 11.} A rule of thumb is that one year -is about -@texline @math{\pi \times 10^7} -@infoline @w{@expr{pi * 10^7}} -seconds. What time will it be that many seconds from right now? -@xref{Types Answer 11, 11}. (@bullet{}) - -(@bullet{}) @strong{Exercise 12.} You are preparing to order packaging -for the CD release of the Extended Disco Version of @emph{Abbey Road}. -You are told that the songs will actually be anywhere from 20 to 60 -seconds longer than the originals. One CD can hold about 75 minutes -of music. Should you order single or double packages? -@xref{Types Answer 12, 12}. (@bullet{}) - -Another kind of data the Calculator can manipulate is numbers with -@dfn{units}. This isn't strictly a new data type; it's simply an -application of algebraic expressions, where we use variables with -suggestive names like @samp{cm} and @samp{in} to represent units -like centimeters and inches. - -@smallexample -@group -1: 2 in 1: 5.08 cm 1: 0.027778 fath 1: 0.0508 m - . . . . - - ' 2in @key{RET} u c cm @key{RET} u c fath @key{RET} u b -@end group -@end smallexample - -@noindent -We enter the quantity ``2 inches'' (actually an algebraic expression -which means two times the variable @samp{in}), then we convert it -first to centimeters, then to fathoms, then finally to ``base'' units, -which in this case means meters. - -@smallexample -@group -1: 9 acre 1: 3 sqrt(acre) 1: 190.84 m 1: 190.84 m + 30 cm - . . . . - - ' 9 acre @key{RET} Q u s ' $+30 cm @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 191.14 m 1: 36536.3046 m^2 1: 365363046 cm^2 - . . . - - u s 2 ^ u c cgs -@end group -@end smallexample - -@noindent -Since units expressions are really just formulas, taking the square -root of @samp{acre} is undefined. After all, @code{acre} might be an -algebraic variable that you will someday assign a value. We use the -``units-simplify'' command to simplify the expression with variables -being interpreted as unit names. - -In the final step, we have converted not to a particular unit, but to a -units system. The ``cgs'' system uses centimeters instead of meters -as its standard unit of length. - -There is a wide variety of units defined in the Calculator. - -@smallexample -@group -1: 55 mph 1: 88.5139 kph 1: 88.5139 km / hr 1: 8.201407e-8 c - . . . . - - ' 55 mph @key{RET} u c kph @key{RET} u c km/hr @key{RET} u c c @key{RET} -@end group -@end smallexample - -@noindent -We express a speed first in miles per hour, then in kilometers per -hour, then again using a slightly more explicit notation, then -finally in terms of fractions of the speed of light. - -Temperature conversions are a bit more tricky. There are two ways to -interpret ``20 degrees Fahrenheit''---it could mean an actual -temperature, or it could mean a change in temperature. For normal -units there is no difference, but temperature units have an offset -as well as a scale factor and so there must be two explicit commands -for them. - -@smallexample -@group -1: 20 degF 1: 11.1111 degC 1: -20:3 degC 1: -6.666 degC - . . . . - - ' 20 degF @key{RET} u c degC @key{RET} U u t degC @key{RET} c f -@end group -@end smallexample - -@noindent -First we convert a change of 20 degrees Fahrenheit into an equivalent -change in degrees Celsius (or Centigrade). Then, we convert the -absolute temperature 20 degrees Fahrenheit into Celsius. Since -this comes out as an exact fraction, we then convert to floating-point -for easier comparison with the other result. - -For simple unit conversions, you can put a plain number on the stack. -Then @kbd{u c} and @kbd{u t} will prompt for both old and new units. -When you use this method, you're responsible for remembering which -numbers are in which units: - -@smallexample -@group -1: 55 1: 88.5139 1: 8.201407e-8 - . . . - - 55 u c mph @key{RET} kph @key{RET} u c km/hr @key{RET} c @key{RET} -@end group -@end smallexample - -To see a complete list of built-in units, type @kbd{u v}. Press -@w{@kbd{C-x * c}} again to re-enter the Calculator when you're done looking -at the units table. - -(@bullet{}) @strong{Exercise 13.} How many seconds are there really -in a year? @xref{Types Answer 13, 13}. (@bullet{}) - -@cindex Speed of light -(@bullet{}) @strong{Exercise 14.} Supercomputer designs are limited by -the speed of light (and of electricity, which is nearly as fast). -Suppose a computer has a 4.1 ns (nanosecond) clock cycle, and its -cabinet is one meter across. Is speed of light going to be a -significant factor in its design? @xref{Types Answer 14, 14}. (@bullet{}) - -(@bullet{}) @strong{Exercise 15.} Sam the Slug normally travels about -five yards in an hour. He has obtained a supply of Power Pills; each -Power Pill he eats doubles his speed. How many Power Pills can he -swallow and still travel legally on most US highways? -@xref{Types Answer 15, 15}. (@bullet{}) - -@node Algebra Tutorial, Programming Tutorial, Types Tutorial, Tutorial -@section Algebra and Calculus Tutorial - -@noindent -This section shows how to use Calc's algebra facilities to solve -equations, do simple calculus problems, and manipulate algebraic -formulas. - -@menu -* Basic Algebra Tutorial:: -* Rewrites Tutorial:: -@end menu - -@node Basic Algebra Tutorial, Rewrites Tutorial, Algebra Tutorial, Algebra Tutorial -@subsection Basic Algebra - -@noindent -If you enter a formula in Algebraic mode that refers to variables, -the formula itself is pushed onto the stack. You can manipulate -formulas as regular data objects. - -@smallexample -@group -1: 2 x^2 - 6 1: 6 - 2 x^2 1: (6 - 2 x^2) (3 x^2 + y) - . . . - - ' 2x^2-6 @key{RET} n ' 3x^2+y @key{RET} * -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 1.} Do @kbd{' x @key{RET} Q 2 ^} and -@kbd{' x @key{RET} 2 ^ Q} both wind up with the same result (@samp{x})? -Why or why not? @xref{Algebra Answer 1, 1}. (@bullet{}) - -There are also commands for doing common algebraic operations on -formulas. Continuing with the formula from the last example, - -@smallexample -@group -1: 18 x^2 + 6 y - 6 x^4 - 2 x^2 y 1: (18 - 2 y) x^2 - 6 x^4 + 6 y - . . - - a x a c x @key{RET} -@end group -@end smallexample - -@noindent -First we ``expand'' using the distributive law, then we ``collect'' -terms involving like powers of @expr{x}. - -Let's find the value of this expression when @expr{x} is 2 and @expr{y} -is one-half. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: -25 - . . - - 1:2 s l y @key{RET} 2 s l x @key{RET} -@end group -@end smallexample - -@noindent -The @kbd{s l} command means ``let''; it takes a number from the top of -the stack and temporarily assigns it as the value of the variable -you specify. It then evaluates (as if by the @kbd{=} key) the -next expression on the stack. After this command, the variable goes -back to its original value, if any. - -(An earlier exercise in this tutorial involved storing a value in the -variable @code{x}; if this value is still there, you will have to -unstore it with @kbd{s u x @key{RET}} before the above example will work -properly.) - -@cindex Maximum of a function using Calculus -Let's find the maximum value of our original expression when @expr{y} -is one-half and @expr{x} ranges over all possible values. We can -do this by taking the derivative with respect to @expr{x} and examining -values of @expr{x} for which the derivative is zero. If the second -derivative of the function at that value of @expr{x} is negative, -the function has a local maximum there. - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 34 x - 24 x^3 - . . - - U @key{DEL} s 1 a d x @key{RET} s 2 -@end group -@end smallexample - -@noindent -Well, the derivative is clearly zero when @expr{x} is zero. To find -the other root(s), let's divide through by @expr{x} and then solve: - -@smallexample -@group -1: (34 x - 24 x^3) / x 1: 34 x / x - 24 x^3 / x 1: 34 - 24 x^2 - . . . - - ' x @key{RET} / a x a s - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 34 - 24 x^2 = 0 1: x = 1.19023 - . . - - 0 a = s 3 a S x @key{RET} -@end group -@end smallexample - -@noindent -Notice the use of @kbd{a s} to ``simplify'' the formula. When the -default algebraic simplifications don't do enough, you can use -@kbd{a s} to tell Calc to spend more time on the job. - -Now we compute the second derivative and plug in our values of @expr{x}: - -@smallexample -@group -1: 1.19023 2: 1.19023 2: 1.19023 - . 1: 34 x - 24 x^3 1: 34 - 72 x^2 - . . - - a . r 2 a d x @key{RET} s 4 -@end group -@end smallexample - -@noindent -(The @kbd{a .} command extracts just the righthand side of an equation. -Another method would have been to use @kbd{v u} to unpack the equation -@w{@samp{x = 1.19}} to @samp{x} and @samp{1.19}, then use @kbd{M-- M-2 @key{DEL}} -to delete the @samp{x}.) - -@smallexample -@group -2: 34 - 72 x^2 1: -68. 2: 34 - 72 x^2 1: 34 -1: 1.19023 . 1: 0 . - . . - - @key{TAB} s l x @key{RET} U @key{DEL} 0 s l x @key{RET} -@end group -@end smallexample - -@noindent -The first of these second derivatives is negative, so we know the function -has a maximum value at @expr{x = 1.19023}. (The function also has a -local @emph{minimum} at @expr{x = 0}.) - -When we solved for @expr{x}, we got only one value even though -@expr{34 - 24 x^2 = 0} is a quadratic equation that ought to have -two solutions. The reason is that @w{@kbd{a S}} normally returns a -single ``principal'' solution. If it needs to come up with an -arbitrary sign (as occurs in the quadratic formula) it picks @expr{+}. -If it needs an arbitrary integer, it picks zero. We can get a full -solution by pressing @kbd{H} (the Hyperbolic flag) before @kbd{a S}. - -@smallexample -@group -1: 34 - 24 x^2 = 0 1: x = 1.19023 s1 1: x = -1.19023 - . . . - - r 3 H a S x @key{RET} s 5 1 n s l s1 @key{RET} -@end group -@end smallexample - -@noindent -Calc has invented the variable @samp{s1} to represent an unknown sign; -it is supposed to be either @mathit{+1} or @mathit{-1}. Here we have used -the ``let'' command to evaluate the expression when the sign is negative. -If we plugged this into our second derivative we would get the same, -negative, answer, so @expr{x = -1.19023} is also a maximum. - -To find the actual maximum value, we must plug our two values of @expr{x} -into the original formula. - -@smallexample -@group -2: 17 x^2 - 6 x^4 + 3 1: 24.08333 s1^2 - 12.04166 s1^4 + 3 -1: x = 1.19023 s1 . - . - - r 1 r 5 s l @key{RET} -@end group -@end smallexample - -@noindent -(Here we see another way to use @kbd{s l}; if its input is an equation -with a variable on the lefthand side, then @kbd{s l} treats the equation -like an assignment to that variable if you don't give a variable name.) - -It's clear that this will have the same value for either sign of -@code{s1}, but let's work it out anyway, just for the exercise: - -@smallexample -@group -2: [-1, 1] 1: [15.04166, 15.04166] -1: 24.08333 s1^2 ... . - . - - [ 1 n , 1 ] @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Here we have used a vector mapping operation to evaluate the function -at several values of @samp{s1} at once. @kbd{V M $} is like @kbd{V M '} -except that it takes the formula from the top of the stack. The -formula is interpreted as a function to apply across the vector at the -next-to-top stack level. Since a formula on the stack can't contain -@samp{$} signs, Calc assumes the variables in the formula stand for -different arguments. It prompts you for an @dfn{argument list}, giving -the list of all variables in the formula in alphabetical order as the -default list. In this case the default is @samp{(s1)}, which is just -what we want so we simply press @key{RET} at the prompt. - -If there had been several different values, we could have used -@w{@kbd{V R X}} to find the global maximum. - -Calc has a built-in @kbd{a P} command that solves an equation using -@w{@kbd{H a S}} and returns a vector of all the solutions. It simply -automates the job we just did by hand. Applied to our original -cubic polynomial, it would produce the vector of solutions -@expr{[1.19023, -1.19023, 0]}. (There is also an @kbd{a X} command -which finds a local maximum of a function. It uses a numerical search -method rather than examining the derivatives, and thus requires you -to provide some kind of initial guess to show it where to look.) - -(@bullet{}) @strong{Exercise 2.} Given a vector of the roots of a -polynomial (such as the output of an @kbd{a P} command), what -sequence of commands would you use to reconstruct the original -polynomial? (The answer will be unique to within a constant -multiple; choose the solution where the leading coefficient is one.) -@xref{Algebra Answer 2, 2}. (@bullet{}) - -The @kbd{m s} command enables Symbolic mode, in which formulas -like @samp{sqrt(5)} that can't be evaluated exactly are left in -symbolic form rather than giving a floating-point approximate answer. -Fraction mode (@kbd{m f}) is also useful when doing algebra. - -@smallexample -@group -2: 34 x - 24 x^3 2: 34 x - 24 x^3 -1: 34 x - 24 x^3 1: [sqrt(51) / 6, sqrt(51) / -6, 0] - . . - - r 2 @key{RET} m s m f a P x @key{RET} -@end group -@end smallexample - -One more mode that makes reading formulas easier is Big mode. - -@smallexample -@group - 3 -2: 34 x - 24 x - - ____ ____ - V 51 V 51 -1: [-----, -----, 0] - 6 -6 - - . - - d B -@end group -@end smallexample - -Here things like powers, square roots, and quotients and fractions -are displayed in a two-dimensional pictorial form. Calc has other -language modes as well, such as C mode, FORTRAN mode, @TeX{} mode -and La@TeX{} mode. - -@smallexample -@group -2: 34*x - 24*pow(x, 3) 2: 34*x - 24*x**3 -1: @{sqrt(51) / 6, sqrt(51) / -6, 0@} 1: /sqrt(51) / 6, sqrt(51) / -6, 0/ - . . - - d C d F - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 34 x - 24 x^3 -2: [@{\sqrt@{51@} \over 6@}, @{\sqrt@{51@} \over -6@}, 0] -1: @{2 \over 3@} \sqrt@{5@} - . - - d T ' 2 \sqrt@{5@} \over 3 @key{RET} -@end group -@end smallexample - -@noindent -As you can see, language modes affect both entry and display of -formulas. They affect such things as the names used for built-in -functions, the set of arithmetic operators and their precedences, -and notations for vectors and matrices. - -Notice that @samp{sqrt(51)} may cause problems with older -implementations of C and FORTRAN, which would require something more -like @samp{sqrt(51.0)}. It is always wise to check over the formulas -produced by the various language modes to make sure they are fully -correct. - -Type @kbd{m s}, @kbd{m f}, and @kbd{d N} to reset these modes. (You -may prefer to remain in Big mode, but all the examples in the tutorial -are shown in normal mode.) - -@cindex Area under a curve -What is the area under the portion of this curve from @expr{x = 1} to @expr{2}? -This is simply the integral of the function: - -@smallexample -@group -1: 17 x^2 - 6 x^4 + 3 1: 5.6666 x^3 - 1.2 x^5 + 3 x - . . - - r 1 a i x -@end group -@end smallexample - -@noindent -We want to evaluate this at our two values for @expr{x} and subtract. -One way to do it is again with vector mapping and reduction: - -@smallexample -@group -2: [2, 1] 1: [12.93333, 7.46666] 1: 5.46666 -1: 5.6666 x^3 ... . . - - [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 3.} Find the integral from 1 to @expr{y} -of -@texline @math{x \sin \pi x} -@infoline @w{@expr{x sin(pi x)}} -(where the sine is calculated in radians). Find the values of the -integral for integers @expr{y} from 1 to 5. @xref{Algebra Answer 3, -3}. (@bullet{}) - -Calc's integrator can do many simple integrals symbolically, but many -others are beyond its capabilities. Suppose we wish to find the area -under the curve -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -over the same range of @expr{x}. If you entered this formula and typed -@kbd{a i x @key{RET}} (don't bother to try this), Calc would work for a -long time but would be unable to find a solution. In fact, there is no -closed-form solution to this integral. Now what do we do? - -@cindex Integration, numerical -@cindex Numerical integration -One approach would be to do the integral numerically. It is not hard -to do this by hand using vector mapping and reduction. It is rather -slow, though, since the sine and logarithm functions take a long time. -We can save some time by reducing the working precision. - -@smallexample -@group -3: 10 1: [1, 1.1, 1.2, ... , 1.8, 1.9] -2: 1 . -1: 0.1 - . - - 10 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x -@end group -@end smallexample - -@noindent -(Note that we have used the extended version of @kbd{v x}; we could -also have used plain @kbd{v x} as follows: @kbd{v x 10 @key{RET} 9 + .1 *}.) - -@smallexample -@group -2: [1, 1.1, ... ] 1: [0., 0.084941, 0.16993, ... ] -1: sin(x) ln(x) . - . - - ' sin(x) ln(x) @key{RET} s 1 m r p 5 @key{RET} V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 3.4195 0.34195 - . . - - V R + 0.1 * -@end group -@end smallexample - -@noindent -(If you got wildly different results, did you remember to switch -to Radians mode?) - -Here we have divided the curve into ten segments of equal width; -approximating these segments as rectangular boxes (i.e., assuming -the curve is nearly flat at that resolution), we compute the areas -of the boxes (height times width), then sum the areas. (It is -faster to sum first, then multiply by the width, since the width -is the same for every box.) - -The true value of this integral turns out to be about 0.374, so -we're not doing too well. Let's try another approach. - -@smallexample -@group -1: sin(x) ln(x) 1: 0.84147 x - 0.84147 + 0.11957 (x - 1)^2 - ... - . . - - r 1 a t x=1 @key{RET} 4 @key{RET} -@end group -@end smallexample - -@noindent -Here we have computed the Taylor series expansion of the function -about the point @expr{x=1}. We can now integrate this polynomial -approximation, since polynomials are easy to integrate. - -@smallexample -@group -1: 0.42074 x^2 + ... 1: [-0.0446, -0.42073] 1: 0.3761 - . . . - - a i x @key{RET} [ 2 , 1 ] @key{TAB} V M $ @key{RET} V R - -@end group -@end smallexample - -@noindent -Better! By increasing the precision and/or asking for more terms -in the Taylor series, we can get a result as accurate as we like. -(Taylor series converge better away from singularities in the -function such as the one at @code{ln(0)}, so it would also help to -expand the series about the points @expr{x=2} or @expr{x=1.5} instead -of @expr{x=1}.) - -@cindex Simpson's rule -@cindex Integration by Simpson's rule -(@bullet{}) @strong{Exercise 4.} Our first method approximated the -curve by stairsteps of width 0.1; the total area was then the sum -of the areas of the rectangles under these stairsteps. Our second -method approximated the function by a polynomial, which turned out -to be a better approximation than stairsteps. A third method is -@dfn{Simpson's rule}, which is like the stairstep method except -that the steps are not required to be flat. Simpson's rule boils -down to the formula, - -@ifnottex -@example -(h/3) * (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + ... - + 2 f(a+(n-2)*h) + 4 f(a+(n-1)*h) + f(a+n*h)) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \displaylines{ - \qquad {h \over 3} (f(a) + 4 f(a+h) + 2 f(a+2h) + 4 f(a+3h) + \cdots - \hfill \cr \hfill {} + 2 f(a+(n-2)h) + 4 f(a+(n-1)h) + f(a+n h)) \qquad -} $$ -\afterdisplay -@end tex - -@noindent -where @expr{n} (which must be even) is the number of slices and @expr{h} -is the width of each slice. These are 10 and 0.1 in our example. -For reference, here is the corresponding formula for the stairstep -method: - -@ifnottex -@example -h * (f(a) + f(a+h) + f(a+2h) + f(a+3h) + ... - + f(a+(n-2)*h) + f(a+(n-1)*h)) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ h (f(a) + f(a+h) + f(a+2h) + f(a+3h) + \cdots - + f(a+(n-2)h) + f(a+(n-1)h)) $$ -\afterdisplay -@end tex - -Compute the integral from 1 to 2 of -@texline @math{\sin x \ln x} -@infoline @expr{sin(x) ln(x)} -using Simpson's rule with 10 slices. -@xref{Algebra Answer 4, 4}. (@bullet{}) - -Calc has a built-in @kbd{a I} command for doing numerical integration. -It uses @dfn{Romberg's method}, which is a more sophisticated cousin -of Simpson's rule. In particular, it knows how to keep refining the -result until the current precision is satisfied. - -@c [fix-ref Selecting Sub-Formulas] -Aside from the commands we've seen so far, Calc also provides a -large set of commands for operating on parts of formulas. You -indicate the desired sub-formula by placing the cursor on any part -of the formula before giving a @dfn{selection} command. Selections won't -be covered in the tutorial; @pxref{Selecting Subformulas}, for -details and examples. - -@c hard exercise: simplify (2^(n r) - 2^(r*(n - 1))) / (2^r - 1) 2^(n - 1) -@c to 2^((n-1)*(r-1)). - -@node Rewrites Tutorial, , Basic Algebra Tutorial, Algebra Tutorial -@subsection Rewrite Rules - -@noindent -No matter how many built-in commands Calc provided for doing algebra, -there would always be something you wanted to do that Calc didn't have -in its repertoire. So Calc also provides a @dfn{rewrite rule} system -that you can use to define your own algebraic manipulations. - -Suppose we want to simplify this trigonometric formula: - -@smallexample -@group -1: 1 / cos(x) - sin(x) tan(x) - . - - ' 1/cos(x) - sin(x) tan(x) @key{RET} s 1 -@end group -@end smallexample - -@noindent -If we were simplifying this by hand, we'd probably replace the -@samp{tan} with a @samp{sin/cos} first, then combine over a common -denominator. There is no Calc command to do the former; the @kbd{a n} -algebra command will do the latter but we'll do both with rewrite -rules just for practice. - -Rewrite rules are written with the @samp{:=} symbol. - -@smallexample -@group -1: 1 / cos(x) - sin(x)^2 / cos(x) - . - - a r tan(a) := sin(a)/cos(a) @key{RET} -@end group -@end smallexample - -@noindent -(The ``assignment operator'' @samp{:=} has several uses in Calc. All -by itself the formula @samp{tan(a) := sin(a)/cos(a)} doesn't do anything, -but when it is given to the @kbd{a r} command, that command interprets -it as a rewrite rule.) - -The lefthand side, @samp{tan(a)}, is called the @dfn{pattern} of the -rewrite rule. Calc searches the formula on the stack for parts that -match the pattern. Variables in a rewrite pattern are called -@dfn{meta-variables}, and when matching the pattern each meta-variable -can match any sub-formula. Here, the meta-variable @samp{a} matched -the actual variable @samp{x}. - -When the pattern part of a rewrite rule matches a part of the formula, -that part is replaced by the righthand side with all the meta-variables -substituted with the things they matched. So the result is -@samp{sin(x) / cos(x)}. Calc's normal algebraic simplifications then -mix this in with the rest of the original formula. - -To merge over a common denominator, we can use another simple rule: - -@smallexample -@group -1: (1 - sin(x)^2) / cos(x) - . - - a r a/x + b/x := (a+b)/x @key{RET} -@end group -@end smallexample - -This rule points out several interesting features of rewrite patterns. -First, if a meta-variable appears several times in a pattern, it must -match the same thing everywhere. This rule detects common denominators -because the same meta-variable @samp{x} is used in both of the -denominators. - -Second, meta-variable names are independent from variables in the -target formula. Notice that the meta-variable @samp{x} here matches -the subformula @samp{cos(x)}; Calc never confuses the two meanings of -@samp{x}. - -And third, rewrite patterns know a little bit about the algebraic -properties of formulas. The pattern called for a sum of two quotients; -Calc was able to match a difference of two quotients by matching -@samp{a = 1}, @samp{b = -sin(x)^2}, and @samp{x = cos(x)}. - -@c [fix-ref Algebraic Properties of Rewrite Rules] -We could just as easily have written @samp{a/x - b/x := (a-b)/x} for -the rule. It would have worked just the same in all cases. (If we -really wanted the rule to apply only to @samp{+} or only to @samp{-}, -we could have used the @code{plain} symbol. @xref{Algebraic Properties -of Rewrite Rules}, for some examples of this.) - -One more rewrite will complete the job. We want to use the identity -@samp{sin(x)^2 + cos(x)^2 = 1}, but of course we must first rearrange -the identity in a way that matches our formula. The obvious rule -would be @samp{@w{1 - sin(x)^2} := cos(x)^2}, but a little thought shows -that the rule @samp{sin(x)^2 := 1 - cos(x)^2} will also work. The -latter rule has a more general pattern so it will work in many other -situations, too. - -@smallexample -@group -1: (1 + cos(x)^2 - 1) / cos(x) 1: cos(x) - . . - - a r sin(x)^2 := 1 - cos(x)^2 @key{RET} a s -@end group -@end smallexample - -You may ask, what's the point of using the most general rule if you -have to type it in every time anyway? The answer is that Calc allows -you to store a rewrite rule in a variable, then give the variable -name in the @kbd{a r} command. In fact, this is the preferred way to -use rewrites. For one, if you need a rule once you'll most likely -need it again later. Also, if the rule doesn't work quite right you -can simply Undo, edit the variable, and run the rule again without -having to retype it. - -@smallexample -@group -' tan(x) := sin(x)/cos(x) @key{RET} s t tsc @key{RET} -' a/x + b/x := (a+b)/x @key{RET} s t merge @key{RET} -' sin(x)^2 := 1 - cos(x)^2 @key{RET} s t sinsqr @key{RET} - -1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) - . . - - r 1 a r tsc @key{RET} a r merge @key{RET} a r sinsqr @key{RET} a s -@end group -@end smallexample - -To edit a variable, type @kbd{s e} and the variable name, use regular -Emacs editing commands as necessary, then type @kbd{C-c C-c} to store -the edited value back into the variable. -You can also use @w{@kbd{s e}} to create a new variable if you wish. - -Notice that the first time you use each rule, Calc puts up a ``compiling'' -message briefly. The pattern matcher converts rules into a special -optimized pattern-matching language rather than using them directly. -This allows @kbd{a r} to apply even rather complicated rules very -efficiently. If the rule is stored in a variable, Calc compiles it -only once and stores the compiled form along with the variable. That's -another good reason to store your rules in variables rather than -entering them on the fly. - -(@bullet{}) @strong{Exercise 1.} Type @kbd{m s} to get Symbolic -mode, then enter the formula @samp{@w{(2 + sqrt(2))} / @w{(1 + sqrt(2))}}. -Using a rewrite rule, simplify this formula by multiplying the top and -bottom by the conjugate @w{@samp{1 - sqrt(2)}}. The result will have -to be expanded by the distributive law; do this with another -rewrite. @xref{Rewrites Answer 1, 1}. (@bullet{}) - -The @kbd{a r} command can also accept a vector of rewrite rules, or -a variable containing a vector of rules. - -@smallexample -@group -1: [tsc, merge, sinsqr] 1: [tan(x) := sin(x) / cos(x), ... ] - . . - - ' [tsc,merge,sinsqr] @key{RET} = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 1 / cos(x) - sin(x) tan(x) 1: cos(x) - . . - - s t trig @key{RET} r 1 a r trig @key{RET} a s -@end group -@end smallexample - -@c [fix-ref Nested Formulas with Rewrite Rules] -Calc tries all the rules you give against all parts of the formula, -repeating until no further change is possible. (The exact order in -which things are tried is rather complex, but for simple rules like -the ones we've used here the order doesn't really matter. -@xref{Nested Formulas with Rewrite Rules}.) - -Calc actually repeats only up to 100 times, just in case your rule set -has gotten into an infinite loop. You can give a numeric prefix argument -to @kbd{a r} to specify any limit. In particular, @kbd{M-1 a r} does -only one rewrite at a time. - -@smallexample -@group -1: 1 / cos(x) - sin(x)^2 / cos(x) 1: (1 - sin(x)^2) / cos(x) - . . - - r 1 M-1 a r trig @key{RET} M-1 a r trig @key{RET} -@end group -@end smallexample - -You can type @kbd{M-0 a r} if you want no limit at all on the number -of rewrites that occur. - -Rewrite rules can also be @dfn{conditional}. Simply follow the rule -with a @samp{::} symbol and the desired condition. For example, - -@smallexample -@group -1: exp(2 pi i) + exp(3 pi i) + exp(4 pi i) - . - - ' exp(2 pi i) + exp(3 pi i) + exp(4 pi i) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 1 + exp(3 pi i) + 1 - . - - a r exp(k pi i) := 1 :: k % 2 = 0 @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{k % 2} is the remainder from dividing @samp{k} by 2, -which will be zero only when @samp{k} is an even integer.) - -An interesting point is that the variables @samp{pi} and @samp{i} -were matched literally rather than acting as meta-variables. -This is because they are special-constant variables. The special -constants @samp{e}, @samp{phi}, and so on also match literally. -A common error with rewrite -rules is to write, say, @samp{f(a,b,c,d,e) := g(a+b+c+d+e)}, expecting -to match any @samp{f} with five arguments but in fact matching -only when the fifth argument is literally @samp{e}! - -@cindex Fibonacci numbers -@ignore -@starindex -@end ignore -@tindex fib -Rewrite rules provide an interesting way to define your own functions. -Suppose we want to define @samp{fib(n)} to produce the @var{n}th -Fibonacci number. The first two Fibonacci numbers are each 1; -later numbers are formed by summing the two preceding numbers in -the sequence. This is easy to express in a set of three rules: - -@smallexample -@group -' [fib(1) := 1, fib(2) := 1, fib(n) := fib(n-1) + fib(n-2)] @key{RET} s t fib - -1: fib(7) 1: 13 - . . - - ' fib(7) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -One thing that is guaranteed about the order that rewrites are tried -is that, for any given subformula, earlier rules in the rule set will -be tried for that subformula before later ones. So even though the -first and third rules both match @samp{fib(1)}, we know the first will -be used preferentially. - -This rule set has one dangerous bug: Suppose we apply it to the -formula @samp{fib(x)}? (Don't actually try this.) The third rule -will match @samp{fib(x)} and replace it with @w{@samp{fib(x-1) + fib(x-2)}}. -Each of these will then be replaced to get @samp{fib(x-2) + 2 fib(x-3) + -fib(x-4)}, and so on, expanding forever. What we really want is to apply -the third rule only when @samp{n} is an integer greater than two. Type -@w{@kbd{s e fib @key{RET}}}, then edit the third rule to: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 -@end smallexample - -@noindent -Now: - -@smallexample -@group -1: fib(6) + fib(x) + fib(0) 1: 8 + fib(x) + fib(0) - . . - - ' fib(6)+fib(x)+fib(0) @key{RET} a r fib @key{RET} -@end group -@end smallexample - -@noindent -We've created a new function, @code{fib}, and a new command, -@w{@kbd{a r fib @key{RET}}}, which means ``evaluate all @code{fib} calls in -this formula.'' To make things easier still, we can tell Calc to -apply these rules automatically by storing them in the special -variable @code{EvalRules}. - -@smallexample -@group -1: [fib(1) := ...] . 1: [8, 13] - . . - - s r fib @key{RET} s t EvalRules @key{RET} ' [fib(6), fib(7)] @key{RET} -@end group -@end smallexample - -It turns out that this rule set has the problem that it does far -more work than it needs to when @samp{n} is large. Consider the -first few steps of the computation of @samp{fib(6)}: - -@smallexample -@group -fib(6) = -fib(5) + fib(4) = -fib(4) + fib(3) + fib(3) + fib(2) = -fib(3) + fib(2) + fib(2) + fib(1) + fib(2) + fib(1) + 1 = ... -@end group -@end smallexample - -@noindent -Note that @samp{fib(3)} appears three times here. Unless Calc's -algebraic simplifier notices the multiple @samp{fib(3)}s and combines -them (and, as it happens, it doesn't), this rule set does lots of -needless recomputation. To cure the problem, type @code{s e EvalRules} -to edit the rules (or just @kbd{s E}, a shorthand command for editing -@code{EvalRules}) and add another condition: - -@smallexample -fib(n) := fib(n-1) + fib(n-2) :: integer(n) :: n > 2 :: remember -@end smallexample - -@noindent -If a @samp{:: remember} condition appears anywhere in a rule, then if -that rule succeeds Calc will add another rule that describes that match -to the front of the rule set. (Remembering works in any rule set, but -for technical reasons it is most effective in @code{EvalRules}.) For -example, if the rule rewrites @samp{fib(7)} to something that evaluates -to 13, then the rule @samp{fib(7) := 13} will be added to the rule set. - -Type @kbd{' fib(8) @key{RET}} to compute the eighth Fibonacci number, then -type @kbd{s E} again to see what has happened to the rule set. - -With the @code{remember} feature, our rule set can now compute -@samp{fib(@var{n})} in just @var{n} steps. In the process it builds -up a table of all Fibonacci numbers up to @var{n}. After we have -computed the result for a particular @var{n}, we can get it back -(and the results for all smaller @var{n}) later in just one step. - -All Calc operations will run somewhat slower whenever @code{EvalRules} -contains any rules. You should type @kbd{s u EvalRules @key{RET}} now to -un-store the variable. - -(@bullet{}) @strong{Exercise 2.} Sometimes it is possible to reformulate -a problem to reduce the amount of recursion necessary to solve it. -Create a rule that, in about @var{n} simple steps and without recourse -to the @code{remember} option, replaces @samp{fib(@var{n}, 1, 1)} with -@samp{fib(1, @var{x}, @var{y})} where @var{x} and @var{y} are the -@var{n}th and @var{n+1}st Fibonacci numbers, respectively. This rule is -rather clunky to use, so add a couple more rules to make the ``user -interface'' the same as for our first version: enter @samp{fib(@var{n})}, -get back a plain number. @xref{Rewrites Answer 2, 2}. (@bullet{}) - -There are many more things that rewrites can do. For example, there -are @samp{&&&} and @samp{|||} pattern operators that create ``and'' -and ``or'' combinations of rules. As one really simple example, we -could combine our first two Fibonacci rules thusly: - -@example -[fib(1 ||| 2) := 1, fib(n) := ... ] -@end example - -@noindent -That means ``@code{fib} of something matching either 1 or 2 rewrites -to 1.'' - -You can also make meta-variables optional by enclosing them in @code{opt}. -For example, the pattern @samp{a + b x} matches @samp{2 + 3 x} but not -@samp{2 + x} or @samp{3 x} or @samp{x}. The pattern @samp{opt(a) + opt(b) x} -matches all of these forms, filling in a default of zero for @samp{a} -and one for @samp{b}. - -(@bullet{}) @strong{Exercise 3.} Your friend Joe had @samp{2 + 3 x} -on the stack and tried to use the rule -@samp{opt(a) + opt(b) x := f(a, b, x)}. What happened? -@xref{Rewrites Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Starting with a positive integer @expr{a}, -divide @expr{a} by two if it is even, otherwise compute @expr{3 a + 1}. -Now repeat this step over and over. A famous unproved conjecture -is that for any starting @expr{a}, the sequence always eventually -reaches 1. Given the formula @samp{seq(@var{a}, 0)}, write a set of -rules that convert this into @samp{seq(1, @var{n})} where @var{n} -is the number of steps it took the sequence to reach the value 1. -Now enhance the rules to accept @samp{seq(@var{a})} as a starting -configuration, and to stop with just the number @var{n} by itself. -Now make the result be a vector of values in the sequence, from @var{a} -to 1. (The formula @samp{@var{x}|@var{y}} appends the vectors @var{x} -and @var{y}.) For example, rewriting @samp{seq(6)} should yield the -vector @expr{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. -@xref{Rewrites Answer 4, 4}. (@bullet{}) - -(@bullet{}) @strong{Exercise 5.} Define, using rewrite rules, a function -@samp{nterms(@var{x})} that returns the number of terms in the sum -@var{x}, or 1 if @var{x} is not a sum. (A @dfn{sum} for our purposes -is one or more non-sum terms separated by @samp{+} or @samp{-} signs, -so that @expr{2 - 3 (x + y) + x y} is a sum of three terms.) -@xref{Rewrites Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} A Taylor series for a function is an -infinite series that exactly equals the value of that function at -values of @expr{x} near zero. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + x^4 / 4! - x^6 / 6! + ... -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + {x^4 \over 4!} - {x^6 \over 6!} + \cdots $$ -\afterdisplay -@end tex - -The @kbd{a t} command produces a @dfn{truncated Taylor series} which -is obtained by dropping all the terms higher than, say, @expr{x^2}. -Calc represents the truncated Taylor series as a polynomial in @expr{x}. -Mathematicians often write a truncated series using a ``big-O'' notation -that records what was the lowest term that was truncated. - -@ifnottex -@example -cos(x) = 1 - x^2 / 2! + O(x^3) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \cos x = 1 - {x^2 \over 2!} + O(x^3) $$ -\afterdisplay -@end tex - -@noindent -The meaning of @expr{O(x^3)} is ``a quantity which is negligibly small -if @expr{x^3} is considered negligibly small as @expr{x} goes to zero.'' - -The exercise is to create rewrite rules that simplify sums and products of -power series represented as @samp{@var{polynomial} + O(@var{var}^@var{n})}. -For example, given @samp{1 - x^2 / 2 + O(x^3)} and @samp{x - x^3 / 6 + O(x^4)} -on the stack, we want to be able to type @kbd{*} and get the result -@samp{x - 2:3 x^3 + O(x^4)}. Don't worry if the terms of the sum are -rearranged or if @kbd{a s} needs to be typed after rewriting. (This one -is rather tricky; the solution at the end of this chapter uses 6 rewrite -rules. Hint: The @samp{constant(x)} condition tests whether @samp{x} is -a number.) @xref{Rewrites Answer 6, 6}. (@bullet{}) - -Just for kicks, try adding the rule @code{2+3 := 6} to @code{EvalRules}. -What happens? (Be sure to remove this rule afterward, or you might get -a nasty surprise when you use Calc to balance your checkbook!) - -@xref{Rewrite Rules}, for the whole story on rewrite rules. - -@node Programming Tutorial, Answers to Exercises, Algebra Tutorial, Tutorial -@section Programming Tutorial - -@noindent -The Calculator is written entirely in Emacs Lisp, a highly extensible -language. If you know Lisp, you can program the Calculator to do -anything you like. Rewrite rules also work as a powerful programming -system. But Lisp and rewrite rules take a while to master, and often -all you want to do is define a new function or repeat a command a few -times. Calc has features that allow you to do these things easily. - -One very limited form of programming is defining your own functions. -Calc's @kbd{Z F} command allows you to define a function name and -key sequence to correspond to any formula. Programming commands use -the shift-@kbd{Z} prefix; the user commands they create use the lower -case @kbd{z} prefix. - -@smallexample -@group -1: 1 + x + x^2 / 2 + x^3 / 6 1: 1 + x + x^2 / 2 + x^3 / 6 - . . - - ' 1 + x + x^2/2! + x^3/3! @key{RET} Z F e myexp @key{RET} @key{RET} @key{RET} y -@end group -@end smallexample - -This polynomial is a Taylor series approximation to @samp{exp(x)}. -The @kbd{Z F} command asks a number of questions. The above answers -say that the key sequence for our function should be @kbd{z e}; the -@kbd{M-x} equivalent should be @code{calc-myexp}; the name of the -function in algebraic formulas should also be @code{myexp}; the -default argument list @samp{(x)} is acceptable; and finally @kbd{y} -answers the question ``leave it in symbolic form for non-constant -arguments?'' - -@smallexample -@group -1: 1.3495 2: 1.3495 3: 1.3495 - . 1: 1.34986 2: 1.34986 - . 1: myexp(a + 1) - . - - .3 z e .3 E ' a+1 @key{RET} z e -@end group -@end smallexample - -@noindent -First we call our new @code{exp} approximation with 0.3 as an -argument, and compare it with the true @code{exp} function. Then -we note that, as requested, if we try to give @kbd{z e} an -argument that isn't a plain number, it leaves the @code{myexp} -function call in symbolic form. If we had answered @kbd{n} to the -final question, @samp{myexp(a + 1)} would have evaluated by plugging -in @samp{a + 1} for @samp{x} in the defining formula. - -@cindex Sine integral Si(x) -@ignore -@starindex -@end ignore -@tindex Si -(@bullet{}) @strong{Exercise 1.} The ``sine integral'' function -@texline @math{{\rm Si}(x)} -@infoline @expr{Si(x)} -is defined as the integral of @samp{sin(t)/t} for -@expr{t = 0} to @expr{x} in radians. (It was invented because this -integral has no solution in terms of basic functions; if you give it -to Calc's @kbd{a i} command, it will ponder it for a long time and then -give up.) We can use the numerical integration command, however, -which in algebraic notation is written like @samp{ninteg(f(t), t, 0, x)} -with any integrand @samp{f(t)}. Define a @kbd{z s} command and -@code{Si} function that implement this. You will need to edit the -default argument list a bit. As a test, @samp{Si(1)} should return -0.946083. (If you don't get this answer, you might want to check that -Calc is in Radians mode. Also, @code{ninteg} will run a lot faster if -you reduce the precision to, say, six digits beforehand.) -@xref{Programming Answer 1, 1}. (@bullet{}) - -The simplest way to do real ``programming'' of Emacs is to define a -@dfn{keyboard macro}. A keyboard macro is simply a sequence of -keystrokes which Emacs has stored away and can play back on demand. -For example, if you find yourself typing @kbd{H a S x @key{RET}} often, -you may wish to program a keyboard macro to type this for you. - -@smallexample -@group -1: y = sqrt(x) 1: x = y^2 - . . - - ' y=sqrt(x) @key{RET} C-x ( H a S x @key{RET} C-x ) - -1: y = cos(x) 1: x = s1 arccos(y) + 2 pi n1 - . . - - ' y=cos(x) @key{RET} X -@end group -@end smallexample - -@noindent -When you type @kbd{C-x (}, Emacs begins recording. But it is also -still ready to execute your keystrokes, so you're really ``training'' -Emacs by walking it through the procedure once. When you type -@w{@kbd{C-x )}}, the macro is recorded. You can now type @kbd{X} to -re-execute the same keystrokes. - -You can give a name to your macro by typing @kbd{Z K}. - -@smallexample -@group -1: . 1: y = x^4 1: x = s2 sqrt(s1 sqrt(y)) - . . - - Z K x @key{RET} ' y=x^4 @key{RET} z x -@end group -@end smallexample - -@noindent -Notice that we use shift-@kbd{Z} to define the command, and lower-case -@kbd{z} to call it up. - -Keyboard macros can call other macros. - -@smallexample -@group -1: abs(x) 1: x = s1 y 1: 2 / x 1: x = 2 / y - . . . . - - ' abs(x) @key{RET} C-x ( ' y @key{RET} a = z x C-x ) ' 2/x @key{RET} X -@end group -@end smallexample - -(@bullet{}) @strong{Exercise 2.} Define a keyboard macro to negate -the item in level 3 of the stack, without disturbing the rest of -the stack. @xref{Programming Answer 2, 2}. (@bullet{}) - -(@bullet{}) @strong{Exercise 3.} Define keyboard macros to compute -the following functions: - -@enumerate -@item -Compute -@texline @math{\displaystyle{\sin x \over x}}, -@infoline @expr{sin(x) / x}, -where @expr{x} is the number on the top of the stack. - -@item -Compute the base-@expr{b} logarithm, just like the @kbd{B} key except -the arguments are taken in the opposite order. - -@item -Produce a vector of integers from 1 to the integer on the top of -the stack. -@end enumerate -@noindent -@xref{Programming Answer 3, 3}. (@bullet{}) - -(@bullet{}) @strong{Exercise 4.} Define a keyboard macro to compute -the average (mean) value of a list of numbers. -@xref{Programming Answer 4, 4}. (@bullet{}) - -In many programs, some of the steps must execute several times. -Calc has @dfn{looping} commands that allow this. Loops are useful -inside keyboard macros, but actually work at any time. - -@smallexample -@group -1: x^6 2: x^6 1: 360 x^2 - . 1: 4 . - . - - ' x^6 @key{RET} 4 Z < a d x @key{RET} Z > -@end group -@end smallexample - -@noindent -Here we have computed the fourth derivative of @expr{x^6} by -enclosing a derivative command in a ``repeat loop'' structure. -This structure pops a repeat count from the stack, then -executes the body of the loop that many times. - -If you make a mistake while entering the body of the loop, -type @w{@kbd{Z C-g}} to cancel the loop command. - -@cindex Fibonacci numbers -Here's another example: - -@smallexample -@group -3: 1 2: 10946 -2: 1 1: 17711 -1: 20 . - . - -1 @key{RET} @key{RET} 20 Z < @key{TAB} C-j + Z > -@end group -@end smallexample - -@noindent -The numbers in levels 2 and 1 should be the 21st and 22nd Fibonacci -numbers, respectively. (To see what's going on, try a few repetitions -of the loop body by hand; @kbd{C-j}, also on the Line-Feed or @key{LFD} -key if you have one, makes a copy of the number in level 2.) - -@cindex Golden ratio -@cindex Phi, golden ratio -A fascinating property of the Fibonacci numbers is that the @expr{n}th -Fibonacci number can be found directly by computing -@texline @math{\phi^n / \sqrt{5}} -@infoline @expr{phi^n / sqrt(5)} -and then rounding to the nearest integer, where -@texline @math{\phi} (``phi''), -@infoline @expr{phi}, -the ``golden ratio,'' is -@texline @math{(1 + \sqrt{5}) / 2}. -@infoline @expr{(1 + sqrt(5)) / 2}. -(For convenience, this constant is available from the @code{phi} -variable, or the @kbd{I H P} command.) - -@smallexample -@group -1: 1.61803 1: 24476.0000409 1: 10945.9999817 1: 10946 - . . . . - - I H P 21 ^ 5 Q / R -@end group -@end smallexample - -@cindex Continued fractions -(@bullet{}) @strong{Exercise 5.} The @dfn{continued fraction} -representation of -@texline @math{\phi} -@infoline @expr{phi} -is -@texline @math{1 + 1/(1 + 1/(1 + 1/( \ldots )))}. -@infoline @expr{1 + 1/(1 + 1/(1 + 1/( ...@: )))}. -We can compute an approximate value by carrying this however far -and then replacing the innermost -@texline @math{1/( \ldots )} -@infoline @expr{1/( ...@: )} -by 1. Approximate -@texline @math{\phi} -@infoline @expr{phi} -using a twenty-term continued fraction. -@xref{Programming Answer 5, 5}. (@bullet{}) - -(@bullet{}) @strong{Exercise 6.} Linear recurrences like the one for -Fibonacci numbers can be expressed in terms of matrices. Given a -vector @w{@expr{[a, b]}} determine a matrix which, when multiplied by this -vector, produces the vector @expr{[b, c]}, where @expr{a}, @expr{b} and -@expr{c} are three successive Fibonacci numbers. Now write a program -that, given an integer @expr{n}, computes the @expr{n}th Fibonacci number -using matrix arithmetic. @xref{Programming Answer 6, 6}. (@bullet{}) - -@cindex Harmonic numbers -A more sophisticated kind of loop is the @dfn{for} loop. Suppose -we wish to compute the 20th ``harmonic'' number, which is equal to -the sum of the reciprocals of the integers from 1 to 20. - -@smallexample -@group -3: 0 1: 3.597739 -2: 1 . -1: 20 - . - -0 @key{RET} 1 @key{RET} 20 Z ( & + 1 Z ) -@end group -@end smallexample - -@noindent -The ``for'' loop pops two numbers, the lower and upper limits, then -repeats the body of the loop as an internal counter increases from -the lower limit to the upper one. Just before executing the loop -body, it pushes the current loop counter. When the loop body -finishes, it pops the ``step,'' i.e., the amount by which to -increment the loop counter. As you can see, our loop always -uses a step of one. - -This harmonic number function uses the stack to hold the running -total as well as for the various loop housekeeping functions. If -you find this disorienting, you can sum in a variable instead: - -@smallexample -@group -1: 0 2: 1 . 1: 3.597739 - . 1: 20 . - . - - 0 t 7 1 @key{RET} 20 Z ( & s + 7 1 Z ) r 7 -@end group -@end smallexample - -@noindent -The @kbd{s +} command adds the top-of-stack into the value in a -variable (and removes that value from the stack). - -It's worth noting that many jobs that call for a ``for'' loop can -also be done more easily by Calc's high-level operations. Two -other ways to compute harmonic numbers are to use vector mapping -and reduction (@kbd{v x 20}, then @w{@kbd{V M &}}, then @kbd{V R +}), -or to use the summation command @kbd{a +}. Both of these are -probably easier than using loops. However, there are some -situations where loops really are the way to go: - -(@bullet{}) @strong{Exercise 7.} Use a ``for'' loop to find the first -harmonic number which is greater than 4.0. -@xref{Programming Answer 7, 7}. (@bullet{}) - -Of course, if we're going to be using variables in our programs, -we have to worry about the programs clobbering values that the -caller was keeping in those same variables. This is easy to -fix, though: - -@smallexample -@group - . 1: 0.6667 1: 0.6667 3: 0.6667 - . . 2: 3.597739 - 1: 0.6667 - . - - Z ` p 4 @key{RET} 2 @key{RET} 3 / s 7 s s a @key{RET} Z ' r 7 s r a @key{RET} -@end group -@end smallexample - -@noindent -When we type @kbd{Z `} (that's a back-quote character), Calc saves -its mode settings and the contents of the ten ``quick variables'' -for later reference. When we type @kbd{Z '} (that's an apostrophe -now), Calc restores those saved values. Thus the @kbd{p 4} and -@kbd{s 7} commands have no effect outside this sequence. Wrapping -this around the body of a keyboard macro ensures that it doesn't -interfere with what the user of the macro was doing. Notice that -the contents of the stack, and the values of named variables, -survive past the @kbd{Z '} command. - -@cindex Bernoulli numbers, approximate -The @dfn{Bernoulli numbers} are a sequence with the interesting -property that all of the odd Bernoulli numbers are zero, and the -even ones, while difficult to compute, can be roughly approximated -by the formula -@texline @math{\displaystyle{2 n! \over (2 \pi)^n}}. -@infoline @expr{2 n!@: / (2 pi)^n}. -Let's write a keyboard macro to compute (approximate) Bernoulli numbers. -(Calc has a command, @kbd{k b}, to compute exact Bernoulli numbers, but -this command is very slow for large @expr{n} since the higher Bernoulli -numbers are very large fractions.) - -@smallexample -@group -1: 10 1: 0.0756823 - . . - - 10 C-x ( @key{RET} 2 % Z [ @key{DEL} 0 Z : ' 2 $! / (2 pi)^$ @key{RET} = Z ] C-x ) -@end group -@end smallexample - -@noindent -You can read @kbd{Z [} as ``then,'' @kbd{Z :} as ``else,'' and -@kbd{Z ]} as ``end-if.'' There is no need for an explicit ``if'' -command. For the purposes of @w{@kbd{Z [}}, the condition is ``true'' -if the value it pops from the stack is a nonzero number, or ``false'' -if it pops zero or something that is not a number (like a formula). -Here we take our integer argument modulo 2; this will be nonzero -if we're asking for an odd Bernoulli number. - -The actual tenth Bernoulli number is @expr{5/66}. - -@smallexample -@group -3: 0.0756823 1: 0 1: 0.25305 1: 0 1: 1.16659 -2: 5:66 . . . . -1: 0.0757575 - . - -10 k b @key{RET} c f M-0 @key{DEL} 11 X @key{DEL} 12 X @key{DEL} 13 X @key{DEL} 14 X -@end group -@end smallexample - -Just to exercise loops a bit more, let's compute a table of even -Bernoulli numbers. - -@smallexample -@group -3: [] 1: [0.10132, 0.03079, 0.02340, 0.033197, ...] -2: 2 . -1: 30 - . - - [ ] 2 @key{RET} 30 Z ( X | 2 Z ) -@end group -@end smallexample - -@noindent -The vertical-bar @kbd{|} is the vector-concatenation command. When -we execute it, the list we are building will be in stack level 2 -(initially this is an empty list), and the next Bernoulli number -will be in level 1. The effect is to append the Bernoulli number -onto the end of the list. (To create a table of exact fractional -Bernoulli numbers, just replace @kbd{X} with @kbd{k b} in the above -sequence of keystrokes.) - -With loops and conditionals, you can program essentially anything -in Calc. One other command that makes looping easier is @kbd{Z /}, -which takes a condition from the stack and breaks out of the enclosing -loop if the condition is true (non-zero). You can use this to make -``while'' and ``until'' style loops. - -If you make a mistake when entering a keyboard macro, you can edit -it using @kbd{Z E}. First, you must attach it to a key with @kbd{Z K}. -One technique is to enter a throwaway dummy definition for the macro, -then enter the real one in the edit command. - -@smallexample -@group -1: 3 1: 3 Calc Macro Edit Mode. - . . Original keys: 1 2 + - - 1 ;; calc digits - RET ;; calc-enter - 2 ;; calc digits - + ;; calc-plus - -C-x ( 1 @key{RET} 2 + C-x ) Z K h @key{RET} Z E h -@end group -@end smallexample - -@noindent -A keyboard macro is stored as a pure keystroke sequence. The -@file{edmacro} package (invoked by @kbd{Z E}) scans along the -macro and tries to decode it back into human-readable steps. -Descriptions of the keystrokes are given as comments, which begin with -@samp{;;}, and which are ignored when the edited macro is saved. -Spaces and line breaks are also ignored when the edited macro is saved. -To enter a space into the macro, type @code{SPC}. All the special -characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, @code{DEL}, -and @code{NUL} must be written in all uppercase, as must the prefixes -@code{C-} and @code{M-}. - -Let's edit in a new definition, for computing harmonic numbers. -First, erase the four lines of the old definition. Then, type -in the new definition (or use Emacs @kbd{M-w} and @kbd{C-y} commands -to copy it from this page of the Info file; you can of course skip -typing the comments, which begin with @samp{;;}). - -@smallexample -Z` ;; calc-kbd-push (Save local values) -0 ;; calc digits (Push a zero onto the stack) -st ;; calc-store-into (Store it in the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (Initial value for the loop) -TAB ;; calc-roll-down (Swap initial and final) -Z( ;; calc-kbd-for (Begin the "for" loop) -& ;; calc-inv (Take the reciprocal) -s+ ;; calc-store-plus (Add to the following variable) -1 ;; calc quick variable (Quick variable q1) -1 ;; calc digits (The loop step is 1) -Z) ;; calc-kbd-end-for (End the "for" loop) -sr ;; calc-recall (Recall the final accumulated value) -1 ;; calc quick variable (Quick variable q1) -Z' ;; calc-kbd-pop (Restore values) -@end smallexample - -@noindent -Press @kbd{C-c C-c} to finish editing and return to the Calculator. - -@smallexample -@group -1: 20 1: 3.597739 - . . - - 20 z h -@end group -@end smallexample - -The @file{edmacro} package defines a handy @code{read-kbd-macro} command -which reads the current region of the current buffer as a sequence of -keystroke names, and defines that sequence on the @kbd{X} -(and @kbd{C-x e}) key. Because this is so useful, Calc puts this -command on the @kbd{C-x * m} key. Try reading in this macro in the -following form: Press @kbd{C-@@} (or @kbd{C-@key{SPC}}) at -one end of the text below, then type @kbd{C-x * m} at the other. - -@example -@group -Z ` 0 t 1 - 1 TAB - Z ( & s + 1 1 Z ) - r 1 -Z ' -@end group -@end example - -(@bullet{}) @strong{Exercise 8.} A general algorithm for solving -equations numerically is @dfn{Newton's Method}. Given the equation -@expr{f(x) = 0} for any function @expr{f}, and an initial guess -@expr{x_0} which is reasonably close to the desired solution, apply -this formula over and over: - -@ifnottex -@example -new_x = x - f(x)/f'(x) -@end example -@end ifnottex -@tex -\beforedisplay -$$ x_{\rm new} = x - {f(x) \over f'(x)} $$ -\afterdisplay -@end tex - -@noindent -where @expr{f'(x)} is the derivative of @expr{f}. The @expr{x} -values will quickly converge to a solution, i.e., eventually -@texline @math{x_{\rm new}} -@infoline @expr{new_x} -and @expr{x} will be equal to within the limits -of the current precision. Write a program which takes a formula -involving the variable @expr{x}, and an initial guess @expr{x_0}, -on the stack, and produces a value of @expr{x} for which the formula -is zero. Use it to find a solution of -@texline @math{\sin(\cos x) = 0.5} -@infoline @expr{sin(cos(x)) = 0.5} -near @expr{x = 4.5}. (Use angles measured in radians.) Note that -the built-in @w{@kbd{a R}} (@code{calc-find-root}) command uses Newton's -method when it is able. @xref{Programming Answer 8, 8}. (@bullet{}) - -@cindex Digamma function -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -(@bullet{}) @strong{Exercise 9.} The @dfn{digamma} function -@texline @math{\psi(z) (``psi'')} -@infoline @expr{psi(z)} -is defined as the derivative of -@texline @math{\ln \Gamma(z)}. -@infoline @expr{ln(gamma(z))}. -For large values of @expr{z}, it can be approximated by the infinite sum - -@ifnottex -@example -psi(z) ~= ln(z) - 1/2z - sum(bern(2 n) / 2 n z^(2 n), n, 1, inf) -@end example -@end ifnottex -@tex -\beforedisplay -$$ \psi(z) \approx \ln z - {1\over2z} - - \sum_{n=1}^\infty {\code{bern}(2 n) \over 2 n z^{2n}} -$$ -\afterdisplay -@end tex - -@noindent -where -@texline @math{\sum} -@infoline @expr{sum} -represents the sum over @expr{n} from 1 to infinity -(or to some limit high enough to give the desired accuracy), and -the @code{bern} function produces (exact) Bernoulli numbers. -While this sum is not guaranteed to converge, in practice it is safe. -An interesting mathematical constant is Euler's gamma, which is equal -to about 0.5772. One way to compute it is by the formula, -@texline @math{\gamma = -\psi(1)}. -@infoline @expr{gamma = -psi(1)}. -Unfortunately, 1 isn't a large enough argument -for the above formula to work (5 is a much safer value for @expr{z}). -Fortunately, we can compute -@texline @math{\psi(1)} -@infoline @expr{psi(1)} -from -@texline @math{\psi(5)} -@infoline @expr{psi(5)} -using the recurrence -@texline @math{\psi(z+1) = \psi(z) + {1 \over z}}. -@infoline @expr{psi(z+1) = psi(z) + 1/z}. -Your task: Develop a program to compute -@texline @math{\psi(z)}; -@infoline @expr{psi(z)}; -it should ``pump up'' @expr{z} -if necessary to be greater than 5, then use the above summation -formula. Use looping commands to compute the sum. Use your function -to compute -@texline @math{\gamma} -@infoline @expr{gamma} -to twelve decimal places. (Calc has a built-in command -for Euler's constant, @kbd{I P}, which you can use to check your answer.) -@xref{Programming Answer 9, 9}. (@bullet{}) - -@cindex Polynomial, list of coefficients -(@bullet{}) @strong{Exercise 10.} Given a polynomial in @expr{x} and -a number @expr{m} on the stack, where the polynomial is of degree -@expr{m} or less (i.e., does not have any terms higher than @expr{x^m}), -write a program to convert the polynomial into a list-of-coefficients -notation. For example, @expr{5 x^4 + (x + 1)^2} with @expr{m = 6} -should produce the list @expr{[1, 2, 1, 0, 5, 0, 0]}. Also develop -a way to convert from this form back to the standard algebraic form. -@xref{Programming Answer 10, 10}. (@bullet{}) - -@cindex Recursion -(@bullet{}) @strong{Exercise 11.} The @dfn{Stirling numbers of the -first kind} are defined by the recurrences, - -@ifnottex -@example -s(n,n) = 1 for n >= 0, -s(n,0) = 0 for n > 0, -s(n+1,m) = s(n,m-1) - n s(n,m) for n >= m >= 1. -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \eqalign{ s(n,n) &= 1 \qquad \hbox{for } n \ge 0, \cr - s(n,0) &= 0 \qquad \hbox{for } n > 0, \cr - s(n+1,m) &= s(n,m-1) - n \, s(n,m) \qquad - \hbox{for } n \ge m \ge 1.} -$$ -\afterdisplay -\vskip5pt -(These numbers are also sometimes written $\displaystyle{n \brack m}$.) -@end tex - -This can be implemented using a @dfn{recursive} program in Calc; the -program must invoke itself in order to calculate the two righthand -terms in the general formula. Since it always invokes itself with -``simpler'' arguments, it's easy to see that it must eventually finish -the computation. Recursion is a little difficult with Emacs keyboard -macros since the macro is executed before its definition is complete. -So here's the recommended strategy: Create a ``dummy macro'' and assign -it to a key with, e.g., @kbd{Z K s}. Now enter the true definition, -using the @kbd{z s} command to call itself recursively, then assign it -to the same key with @kbd{Z K s}. Now the @kbd{z s} command will run -the complete recursive program. (Another way is to use @w{@kbd{Z E}} -or @kbd{C-x * m} (@code{read-kbd-macro}) to read the whole macro at once, -thus avoiding the ``training'' phase.) The task: Write a program -that computes Stirling numbers of the first kind, given @expr{n} and -@expr{m} on the stack. Test it with @emph{small} inputs like -@expr{s(4,2)}. (There is a built-in command for Stirling numbers, -@kbd{k s}, which you can use to check your answers.) -@xref{Programming Answer 11, 11}. (@bullet{}) - -The programming commands we've seen in this part of the tutorial -are low-level, general-purpose operations. Often you will find -that a higher-level function, such as vector mapping or rewrite -rules, will do the job much more easily than a detailed, step-by-step -program can: - -(@bullet{}) @strong{Exercise 12.} Write another program for -computing Stirling numbers of the first kind, this time using -rewrite rules. Once again, @expr{n} and @expr{m} should be taken -from the stack. @xref{Programming Answer 12, 12}. (@bullet{}) - -@example - -@end example -This ends the tutorial section of the Calc manual. Now you know enough -about Calc to use it effectively for many kinds of calculations. But -Calc has many features that were not even touched upon in this tutorial. -@c [not-split] -The rest of this manual tells the whole story. -@c [when-split] -@c Volume II of this manual, the @dfn{Calc Reference}, tells the whole story. - -@page -@node Answers to Exercises, , Programming Tutorial, Tutorial -@section Answers to Exercises - -@noindent -This section includes answers to all the exercises in the Calc tutorial. - -@menu -* RPN Answer 1:: 1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * - -* RPN Answer 2:: 2*4 + 7*9.5 + 5/4 -* RPN Answer 3:: Operating on levels 2 and 3 -* RPN Answer 4:: Joe's complex problems -* Algebraic Answer 1:: Simulating Q command -* Algebraic Answer 2:: Joe's algebraic woes -* Algebraic Answer 3:: 1 / 0 -* Modes Answer 1:: 3#0.1 = 3#0.0222222? -* Modes Answer 2:: 16#f.e8fe15 -* Modes Answer 3:: Joe's rounding bug -* Modes Answer 4:: Why floating point? -* Arithmetic Answer 1:: Why the \ command? -* Arithmetic Answer 2:: Tripping up the B command -* Vector Answer 1:: Normalizing a vector -* Vector Answer 2:: Average position -* Matrix Answer 1:: Row and column sums -* Matrix Answer 2:: Symbolic system of equations -* Matrix Answer 3:: Over-determined system -* List Answer 1:: Powers of two -* List Answer 2:: Least-squares fit with matrices -* List Answer 3:: Geometric mean -* List Answer 4:: Divisor function -* List Answer 5:: Duplicate factors -* List Answer 6:: Triangular list -* List Answer 7:: Another triangular list -* List Answer 8:: Maximum of Bessel function -* List Answer 9:: Integers the hard way -* List Answer 10:: All elements equal -* List Answer 11:: Estimating pi with darts -* List Answer 12:: Estimating pi with matchsticks -* List Answer 13:: Hash codes -* List Answer 14:: Random walk -* Types Answer 1:: Square root of pi times rational -* Types Answer 2:: Infinities -* Types Answer 3:: What can "nan" be? -* Types Answer 4:: Abbey Road -* Types Answer 5:: Friday the 13th -* Types Answer 6:: Leap years -* Types Answer 7:: Erroneous donut -* Types Answer 8:: Dividing intervals -* Types Answer 9:: Squaring intervals -* Types Answer 10:: Fermat's primality test -* Types Answer 11:: pi * 10^7 seconds -* Types Answer 12:: Abbey Road on CD -* Types Answer 13:: Not quite pi * 10^7 seconds -* Types Answer 14:: Supercomputers and c -* Types Answer 15:: Sam the Slug -* Algebra Answer 1:: Squares and square roots -* Algebra Answer 2:: Building polynomial from roots -* Algebra Answer 3:: Integral of x sin(pi x) -* Algebra Answer 4:: Simpson's rule -* Rewrites Answer 1:: Multiplying by conjugate -* Rewrites Answer 2:: Alternative fib rule -* Rewrites Answer 3:: Rewriting opt(a) + opt(b) x -* Rewrites Answer 4:: Sequence of integers -* Rewrites Answer 5:: Number of terms in sum -* Rewrites Answer 6:: Truncated Taylor series -* Programming Answer 1:: Fresnel's C(x) -* Programming Answer 2:: Negate third stack element -* Programming Answer 3:: Compute sin(x) / x, etc. -* Programming Answer 4:: Average value of a list -* Programming Answer 5:: Continued fraction phi -* Programming Answer 6:: Matrix Fibonacci numbers -* Programming Answer 7:: Harmonic number greater than 4 -* Programming Answer 8:: Newton's method -* Programming Answer 9:: Digamma function -* Programming Answer 10:: Unpacking a polynomial -* Programming Answer 11:: Recursive Stirling numbers -* Programming Answer 12:: Stirling numbers with rewrites -@end menu - -@c The following kludgery prevents the individual answers from -@c being entered on the table of contents. -@tex -\global\let\oldwrite=\write -\gdef\skipwrite#1#2{\let\write=\oldwrite} -\global\let\oldchapternofonts=\chapternofonts -\gdef\chapternofonts{\let\write=\skipwrite\oldchapternofonts} -@end tex - -@node RPN Answer 1, RPN Answer 2, Answers to Exercises, Answers to Exercises -@subsection RPN Tutorial Exercise 1 - -@noindent -@kbd{1 @key{RET} 2 @key{RET} 3 @key{RET} 4 + * -} - -The result is -@texline @math{1 - (2 \times (3 + 4)) = -13}. -@infoline @expr{1 - (2 * (3 + 4)) = -13}. - -@node RPN Answer 2, RPN Answer 3, RPN Answer 1, Answers to Exercises -@subsection RPN Tutorial Exercise 2 - -@noindent -@texline @math{2\times4 + 7\times9.5 + {5\over4} = 75.75} -@infoline @expr{2*4 + 7*9.5 + 5/4 = 75.75} - -After computing the intermediate term -@texline @math{2\times4 = 8}, -@infoline @expr{2*4 = 8}, -you can leave that result on the stack while you compute the second -term. With both of these results waiting on the stack you can then -compute the final term, then press @kbd{+ +} to add everything up. - -@smallexample -@group -2: 2 1: 8 3: 8 2: 8 -1: 4 . 2: 7 1: 66.5 - . 1: 9.5 . - . - - 2 @key{RET} 4 * 7 @key{RET} 9.5 * - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 8 3: 8 2: 8 1: 75.75 -3: 66.5 2: 66.5 1: 67.75 . -2: 5 1: 1.25 . -1: 4 . - . - - 5 @key{RET} 4 / + + -@end group -@end smallexample - -Alternatively, you could add the first two terms before going on -with the third term. - -@smallexample -@group -2: 8 1: 74.5 3: 74.5 2: 74.5 1: 75.75 -1: 66.5 . 2: 5 1: 1.25 . - . 1: 4 . - . - - ... + 5 @key{RET} 4 / + -@end group -@end smallexample - -On an old-style RPN calculator this second method would have the -advantage of using only three stack levels. But since Calc's stack -can grow arbitrarily large this isn't really an issue. Which method -you choose is purely a matter of taste. - -@node RPN Answer 3, RPN Answer 4, RPN Answer 2, Answers to Exercises -@subsection RPN Tutorial Exercise 3 - -@noindent -The @key{TAB} key provides a way to operate on the number in level 2. - -@smallexample -@group -3: 10 3: 10 4: 10 3: 10 3: 10 -2: 20 2: 30 3: 30 2: 30 2: 21 -1: 30 1: 20 2: 20 1: 21 1: 30 - . . 1: 1 . . - . - - @key{TAB} 1 + @key{TAB} -@end group -@end smallexample - -Similarly, @kbd{M-@key{TAB}} gives you access to the number in level 3. - -@smallexample -@group -3: 10 3: 21 3: 21 3: 30 3: 11 -2: 21 2: 30 2: 30 2: 11 2: 21 -1: 30 1: 10 1: 11 1: 21 1: 30 - . . . . . - - M-@key{TAB} 1 + M-@key{TAB} M-@key{TAB} -@end group -@end smallexample - -@node RPN Answer 4, Algebraic Answer 1, RPN Answer 3, Answers to Exercises -@subsection RPN Tutorial Exercise 4 - -@noindent -Either @kbd{( 2 , 3 )} or @kbd{( 2 @key{SPC} 3 )} would have worked, -but using both the comma and the space at once yields: - -@smallexample -@group -1: ( ... 2: ( ... 1: (2, ... 2: (2, ... 2: (2, ... - . 1: 2 . 1: (2, ... 1: (2, 3) - . . . - - ( 2 , @key{SPC} 3 ) -@end group -@end smallexample - -Joe probably tried to type @kbd{@key{TAB} @key{DEL}} to swap the -extra incomplete object to the top of the stack and delete it. -But a feature of Calc is that @key{DEL} on an incomplete object -deletes just one component out of that object, so he had to press -@key{DEL} twice to finish the job. - -@smallexample -@group -2: (2, ... 2: (2, 3) 2: (2, 3) 1: (2, 3) -1: (2, 3) 1: (2, ... 1: ( ... . - . . . - - @key{TAB} @key{DEL} @key{DEL} -@end group -@end smallexample - -(As it turns out, deleting the second-to-top stack entry happens often -enough that Calc provides a special key, @kbd{M-@key{DEL}}, to do just that. -@kbd{M-@key{DEL}} is just like @kbd{@key{TAB} @key{DEL}}, except that it doesn't exhibit -the ``feature'' that tripped poor Joe.) - -@node Algebraic Answer 1, Algebraic Answer 2, RPN Answer 4, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 1 - -@noindent -Type @kbd{' sqrt($) @key{RET}}. - -If the @kbd{Q} key is broken, you could use @kbd{' $^0.5 @key{RET}}. -Or, RPN style, @kbd{0.5 ^}. - -(Actually, @samp{$^1:2}, using the fraction one-half as the power, is -a closer equivalent, since @samp{9^0.5} yields @expr{3.0} whereas -@samp{sqrt(9)} and @samp{9^1:2} yield the exact integer @expr{3}.) - -@node Algebraic Answer 2, Algebraic Answer 3, Algebraic Answer 1, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 2 - -@noindent -In the formula @samp{2 x (1+y)}, @samp{x} was interpreted as a function -name with @samp{1+y} as its argument. Assigning a value to a variable -has no relation to a function by the same name. Joe needed to use an -explicit @samp{*} symbol here: @samp{2 x*(1+y)}. - -@node Algebraic Answer 3, Modes Answer 1, Algebraic Answer 2, Answers to Exercises -@subsection Algebraic Entry Tutorial Exercise 3 - -@noindent -The result from @kbd{1 @key{RET} 0 /} will be the formula @expr{1 / 0}. -The ``function'' @samp{/} cannot be evaluated when its second argument -is zero, so it is left in symbolic form. When you now type @kbd{0 *}, -the result will be zero because Calc uses the general rule that ``zero -times anything is zero.'' - -@c [fix-ref Infinities] -The @kbd{m i} command enables an @dfn{Infinite mode} in which @expr{1 / 0} -results in a special symbol that represents ``infinity.'' If you -multiply infinity by zero, Calc uses another special new symbol to -show that the answer is ``indeterminate.'' @xref{Infinities}, for -further discussion of infinite and indeterminate values. - -@node Modes Answer 1, Modes Answer 2, Algebraic Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 1 - -@noindent -Calc always stores its numbers in decimal, so even though one-third has -an exact base-3 representation (@samp{3#0.1}), it is still stored as -0.3333333 (chopped off after 12 or however many decimal digits) inside -the calculator's memory. When this inexact number is converted back -to base 3 for display, it may still be slightly inexact. When we -multiply this number by 3, we get 0.999999, also an inexact value. - -When Calc displays a number in base 3, it has to decide how many digits -to show. If the current precision is 12 (decimal) digits, that corresponds -to @samp{12 / log10(3) = 25.15} base-3 digits. Because 25.15 is not an -exact integer, Calc shows only 25 digits, with the result that stored -numbers carry a little bit of extra information that may not show up on -the screen. When Joe entered @samp{3#0.2}, the stored number 0.666666 -happened to round to a pleasing value when it lost that last 0.15 of a -digit, but it was still inexact in Calc's memory. When he divided by 2, -he still got the dreaded inexact value 0.333333. (Actually, he divided -0.666667 by 2 to get 0.333334, which is why he got something a little -higher than @code{3#0.1} instead of a little lower.) - -If Joe didn't want to be bothered with all this, he could have typed -@kbd{M-24 d n} to display with one less digit than the default. (If -you give @kbd{d n} a negative argument, it uses default-minus-that, -so @kbd{M-- d n} would be an easier way to get the same effect.) Those -inexact results would still be lurking there, but they would now be -rounded to nice, natural-looking values for display purposes. (Remember, -@samp{0.022222} in base 3 is like @samp{0.099999} in base 10; rounding -off one digit will round the number up to @samp{0.1}.) Depending on the -nature of your work, this hiding of the inexactness may be a benefit or -a danger. With the @kbd{d n} command, Calc gives you the choice. - -Incidentally, another consequence of all this is that if you type -@kbd{M-30 d n} to display more digits than are ``really there,'' -you'll see garbage digits at the end of the number. (In decimal -display mode, with decimally-stored numbers, these garbage digits are -always zero so they vanish and you don't notice them.) Because Calc -rounds off that 0.15 digit, there is the danger that two numbers could -be slightly different internally but still look the same. If you feel -uneasy about this, set the @kbd{d n} precision to be a little higher -than normal; you'll get ugly garbage digits, but you'll always be able -to tell two distinct numbers apart. - -An interesting side note is that most computers store their -floating-point numbers in binary, and convert to decimal for display. -Thus everyday programs have the same problem: Decimal 0.1 cannot be -represented exactly in binary (try it: @kbd{0.1 d 2}), so @samp{0.1 * 10} -comes out as an inexact approximation to 1 on some machines (though -they generally arrange to hide it from you by rounding off one digit as -we did above). Because Calc works in decimal instead of binary, you can -be sure that numbers that look exact @emph{are} exact as long as you stay -in decimal display mode. - -It's not hard to show that any number that can be represented exactly -in binary, octal, or hexadecimal is also exact in decimal, so the kinds -of problems we saw in this exercise are likely to be severe only when -you use a relatively unusual radix like 3. - -@node Modes Answer 2, Modes Answer 3, Modes Answer 1, Answers to Exercises -@subsection Modes Tutorial Exercise 2 - -If the radix is 15 or higher, we can't use the letter @samp{e} to mark -the exponent because @samp{e} is interpreted as a digit. When Calc -needs to display scientific notation in a high radix, it writes -@samp{16#F.E8F*16.^15}. You can enter a number like this as an -algebraic entry. Also, pressing @kbd{e} without any digits before it -normally types @kbd{1e}, but in a high radix it types @kbd{16.^} and -puts you in algebraic entry: @kbd{16#f.e8f @key{RET} e 15 @key{RET} *} is another -way to enter this number. - -The reason Calc puts a decimal point in the @samp{16.^} is to prevent -huge integers from being generated if the exponent is large (consider -@samp{16#1.23*16^1000}, where we compute @samp{16^1000} as a giant -exact integer and then throw away most of the digits when we multiply -it by the floating-point @samp{16#1.23}). While this wouldn't normally -matter for display purposes, it could give you a nasty surprise if you -copied that number into a file and later moved it back into Calc. - -@node Modes Answer 3, Modes Answer 4, Modes Answer 2, Answers to Exercises -@subsection Modes Tutorial Exercise 3 - -@noindent -The answer he got was @expr{0.5000000000006399}. - -The problem is not that the square operation is inexact, but that the -sine of 45 that was already on the stack was accurate to only 12 places. -Arbitrary-precision calculations still only give answers as good as -their inputs. - -The real problem is that there is no 12-digit number which, when -squared, comes out to 0.5 exactly. The @kbd{f [} and @kbd{f ]} -commands decrease or increase a number by one unit in the last -place (according to the current precision). They are useful for -determining facts like this. - -@smallexample -@group -1: 0.707106781187 1: 0.500000000001 - . . - - 45 S 2 ^ - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 0.707106781187 1: 0.707106781186 1: 0.499999999999 - . . . - - U @key{DEL} f [ 2 ^ -@end group -@end smallexample - -A high-precision calculation must be carried out in high precision -all the way. The only number in the original problem which was known -exactly was the quantity 45 degrees, so the precision must be raised -before anything is done after the number 45 has been entered in order -for the higher precision to be meaningful. - -@node Modes Answer 4, Arithmetic Answer 1, Modes Answer 3, Answers to Exercises -@subsection Modes Tutorial Exercise 4 - -@noindent -Many calculations involve real-world quantities, like the width and -height of a piece of wood or the volume of a jar. Such quantities -can't be measured exactly anyway, and if the data that is input to -a calculation is inexact, doing exact arithmetic on it is a waste -of time. - -Fractions become unwieldy after too many calculations have been -done with them. For example, the sum of the reciprocals of the -integers from 1 to 10 is 7381:2520. The sum from 1 to 30 is -9304682830147:2329089562800. After a point it will take a long -time to add even one more term to this sum, but a floating-point -calculation of the sum will not have this problem. - -Also, rational numbers cannot express the results of all calculations. -There is no fractional form for the square root of two, so if you type -@w{@kbd{2 Q}}, Calc has no choice but to give you a floating-point answer. - -@node Arithmetic Answer 1, Arithmetic Answer 2, Modes Answer 4, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 1 - -@noindent -Dividing two integers that are larger than the current precision may -give a floating-point result that is inaccurate even when rounded -down to an integer. Consider @expr{123456789 / 2} when the current -precision is 6 digits. The true answer is @expr{61728394.5}, but -with a precision of 6 this will be rounded to -@texline @math{12345700.0/2.0 = 61728500.0}. -@infoline @expr{12345700.@: / 2.@: = 61728500.}. -The result, when converted to an integer, will be off by 106. - -Here are two solutions: Raise the precision enough that the -floating-point round-off error is strictly to the right of the -decimal point. Or, convert to Fraction mode so that @expr{123456789 / 2} -produces the exact fraction @expr{123456789:2}, which can be rounded -down by the @kbd{F} command without ever switching to floating-point -format. - -@node Arithmetic Answer 2, Vector Answer 1, Arithmetic Answer 1, Answers to Exercises -@subsection Arithmetic Tutorial Exercise 2 - -@noindent -@kbd{27 @key{RET} 9 B} could give the exact result @expr{3:2}, but it -does a floating-point calculation instead and produces @expr{1.5}. - -Calc will find an exact result for a logarithm if the result is an integer -or (when in Fraction mode) the reciprocal of an integer. But there is -no efficient way to search the space of all possible rational numbers -for an exact answer, so Calc doesn't try. - -@node Vector Answer 1, Vector Answer 2, Arithmetic Answer 2, Answers to Exercises -@subsection Vector Tutorial Exercise 1 - -@noindent -Duplicate the vector, compute its length, then divide the vector -by its length: @kbd{@key{RET} A /}. - -@smallexample -@group -1: [1, 2, 3] 2: [1, 2, 3] 1: [0.27, 0.53, 0.80] 1: 1. - . 1: 3.74165738677 . . - . - - r 1 @key{RET} A / A -@end group -@end smallexample - -The final @kbd{A} command shows that the normalized vector does -indeed have unit length. - -@node Vector Answer 2, Matrix Answer 1, Vector Answer 1, Answers to Exercises -@subsection Vector Tutorial Exercise 2 - -@noindent -The average position is equal to the sum of the products of the -positions times their corresponding probabilities. This is the -definition of the dot product operation. So all you need to do -is to put the two vectors on the stack and press @kbd{*}. - -@node Matrix Answer 1, Matrix Answer 2, Vector Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 1 - -@noindent -The trick is to multiply by a vector of ones. Use @kbd{r 4 [1 1 1] *} to -get the row sum. Similarly, use @kbd{[1 1] r 4 *} to get the column sum. - -@node Matrix Answer 2, Matrix Answer 3, Matrix Answer 1, Answers to Exercises -@subsection Matrix Tutorial Exercise 2 - -@ifnottex -@example -@group - x + a y = 6 - x + b y = 10 -@end group -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \eqalign{ x &+ a y = 6 \cr - x &+ b y = 10} -$$ -\afterdisplay -@end tex - -Just enter the righthand side vector, then divide by the lefthand side -matrix as usual. - -@smallexample -@group -1: [6, 10] 2: [6, 10] 1: [6 - 4 a / (b - a), 4 / (b - a) ] - . 1: [ [ 1, a ] . - [ 1, b ] ] - . - -' [6 10] @key{RET} ' [1 a; 1 b] @key{RET} / -@end group -@end smallexample - -This can be made more readable using @kbd{d B} to enable Big display -mode: - -@smallexample -@group - 4 a 4 -1: [6 - -----, -----] - b - a b - a -@end group -@end smallexample - -Type @kbd{d N} to return to Normal display mode afterwards. - -@node Matrix Answer 3, List Answer 1, Matrix Answer 2, Answers to Exercises -@subsection Matrix Tutorial Exercise 3 - -@noindent -To solve -@texline @math{A^T A \, X = A^T B}, -@infoline @expr{trn(A) * A * X = trn(A) * B}, -first we compute -@texline @math{A' = A^T A} -@infoline @expr{A2 = trn(A) * A} -and -@texline @math{B' = A^T B}; -@infoline @expr{B2 = trn(A) * B}; -now, we have a system -@texline @math{A' X = B'} -@infoline @expr{A2 * X = B2} -which we can solve using Calc's @samp{/} command. - -@ifnottex -@example -@group - a + 2b + 3c = 6 - 4a + 5b + 6c = 2 - 7a + 6b = 3 - 2a + 4b + 6c = 11 -@end group -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplayh -$$ \openup1\jot \tabskip=0pt plus1fil -\halign to\displaywidth{\tabskip=0pt - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&$\hfil{}#{}$& - $\hfil#$&${}#\hfil$\tabskip=0pt plus1fil\cr - a&+&2b&+&3c&=6 \cr - 4a&+&5b&+&6c&=2 \cr - 7a&+&6b& & &=3 \cr - 2a&+&4b&+&6c&=11 \cr} -$$ -\afterdisplayh -@end tex - -The first step is to enter the coefficient matrix. We'll store it in -quick variable number 7 for later reference. Next, we compute the -@texline @math{B'} -@infoline @expr{B2} -vector. - -@smallexample -@group -1: [ [ 1, 2, 3 ] 2: [ [ 1, 4, 7, 2 ] 1: [57, 84, 96] - [ 4, 5, 6 ] [ 2, 5, 6, 4 ] . - [ 7, 6, 0 ] [ 3, 6, 0, 6 ] ] - [ 2, 4, 6 ] ] 1: [6, 2, 3, 11] - . . - -' [1 2 3; 4 5 6; 7 6 0; 2 4 6] @key{RET} s 7 v t [6 2 3 11] * -@end group -@end smallexample - -@noindent -Now we compute the matrix -@texline @math{A'} -@infoline @expr{A2} -and divide. - -@smallexample -@group -2: [57, 84, 96] 1: [-11.64, 14.08, -3.64] -1: [ [ 70, 72, 39 ] . - [ 72, 81, 60 ] - [ 39, 60, 81 ] ] - . - - r 7 v t r 7 * / -@end group -@end smallexample - -@noindent -(The actual computed answer will be slightly inexact due to -round-off error.) - -Notice that the answers are similar to those for the -@texline @math{3\times3} -@infoline 3x3 -system solved in the text. That's because the fourth equation that was -added to the system is almost identical to the first one multiplied -by two. (If it were identical, we would have gotten the exact same -answer since the -@texline @math{4\times3} -@infoline 4x3 -system would be equivalent to the original -@texline @math{3\times3} -@infoline 3x3 -system.) - -Since the first and fourth equations aren't quite equivalent, they -can't both be satisfied at once. Let's plug our answers back into -the original system of equations to see how well they match. - -@smallexample -@group -2: [-11.64, 14.08, -3.64] 1: [5.6, 2., 3., 11.2] -1: [ [ 1, 2, 3 ] . - [ 4, 5, 6 ] - [ 7, 6, 0 ] - [ 2, 4, 6 ] ] - . - - r 7 @key{TAB} * -@end group -@end smallexample - -@noindent -This is reasonably close to our original @expr{B} vector, -@expr{[6, 2, 3, 11]}. - -@node List Answer 1, List Answer 2, Matrix Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 1 - -@noindent -We can use @kbd{v x} to build a vector of integers. This needs to be -adjusted to get the range of integers we desire. Mapping @samp{-} -across the vector will accomplish this, although it turns out the -plain @samp{-} key will work just as well. - -@smallexample -@group -2: 2 2: 2 -1: [1, 2, 3, 4, 5, 6, 7, 8, 9] 1: [-4, -3, -2, -1, 0, 1, 2, 3, 4] - . . - - 2 v x 9 @key{RET} 5 V M - or 5 - -@end group -@end smallexample - -@noindent -Now we use @kbd{V M ^} to map the exponentiation operator across the -vector. - -@smallexample -@group -1: [0.0625, 0.125, 0.25, 0.5, 1, 2, 4, 8, 16] - . - - V M ^ -@end group -@end smallexample - -@node List Answer 2, List Answer 3, List Answer 1, Answers to Exercises -@subsection List Tutorial Exercise 2 - -@noindent -Given @expr{x} and @expr{y} vectors in quick variables 1 and 2 as before, -the first job is to form the matrix that describes the problem. - -@ifnottex -@example - m*x + b*1 = y -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ m \times x + b \times 1 = y $$ -\afterdisplay -@end tex - -Thus we want a -@texline @math{19\times2} -@infoline 19x2 -matrix with our @expr{x} vector as one column and -ones as the other column. So, first we build the column of ones, then -we combine the two columns to form our @expr{A} matrix. - -@smallexample -@group -2: [1.34, 1.41, 1.49, ... ] 1: [ [ 1.34, 1 ] -1: [1, 1, 1, ...] [ 1.41, 1 ] - . [ 1.49, 1 ] - @dots{} - - r 1 1 v b 19 @key{RET} M-2 v p v t s 3 -@end group -@end smallexample - -@noindent -Now we compute -@texline @math{A^T y} -@infoline @expr{trn(A) * y} -and -@texline @math{A^T A} -@infoline @expr{trn(A) * A} -and divide. - -@smallexample -@group -1: [33.36554, 13.613] 2: [33.36554, 13.613] - . 1: [ [ 98.0003, 41.63 ] - [ 41.63, 19 ] ] - . - - v t r 2 * r 3 v t r 3 * -@end group -@end smallexample - -@noindent -(Hey, those numbers look familiar!) - -@smallexample -@group -1: [0.52141679, -0.425978] - . - - / -@end group -@end smallexample - -Since we were solving equations of the form -@texline @math{m \times x + b \times 1 = y}, -@infoline @expr{m*x + b*1 = y}, -these numbers should be @expr{m} and @expr{b}, respectively. Sure -enough, they agree exactly with the result computed using @kbd{V M} and -@kbd{V R}! - -The moral of this story: @kbd{V M} and @kbd{V R} will probably solve -your problem, but there is often an easier way using the higher-level -arithmetic functions! - -@c [fix-ref Curve Fitting] -In fact, there is a built-in @kbd{a F} command that does least-squares -fits. @xref{Curve Fitting}. - -@node List Answer 3, List Answer 4, List Answer 2, Answers to Exercises -@subsection List Tutorial Exercise 3 - -@noindent -Move to one end of the list and press @kbd{C-@@} (or @kbd{C-@key{SPC}} or -whatever) to set the mark, then move to the other end of the list -and type @w{@kbd{C-x * g}}. - -@smallexample -@group -1: [2.3, 6, 22, 15.1, 7, 15, 14, 7.5, 2.5] - . -@end group -@end smallexample - -To make things interesting, let's assume we don't know at a glance -how many numbers are in this list. Then we could type: - -@smallexample -@group -2: [2.3, 6, 22, ... ] 2: [2.3, 6, 22, ... ] -1: [2.3, 6, 22, ... ] 1: 126356422.5 - . . - - @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 126356422.5 2: 126356422.5 1: 7.94652913734 -1: [2.3, 6, 22, ... ] 1: 9 . - . . - - @key{TAB} v l I ^ -@end group -@end smallexample - -@noindent -(The @kbd{I ^} command computes the @var{n}th root of a number. -You could also type @kbd{& ^} to take the reciprocal of 9 and -then raise the number to that power.) - -@node List Answer 4, List Answer 5, List Answer 3, Answers to Exercises -@subsection List Tutorial Exercise 4 - -@noindent -A number @expr{j} is a divisor of @expr{n} if -@texline @math{n \mathbin{\hbox{\code{\%}}} j = 0}. -@infoline @samp{n % j = 0}. -The first step is to get a vector that identifies the divisors. - -@smallexample -@group -2: 30 2: [0, 0, 0, 2, ...] 1: [1, 1, 1, 0, ...] -1: [1, 2, 3, 4, ...] 1: 0 . - . . - - 30 @key{RET} v x 30 @key{RET} s 1 V M % 0 V M a = s 2 -@end group -@end smallexample - -@noindent -This vector has 1's marking divisors of 30 and 0's marking non-divisors. - -The zeroth divisor function is just the total number of divisors. -The first divisor function is the sum of the divisors. - -@smallexample -@group -1: 8 3: 8 2: 8 2: 8 - 2: [1, 2, 3, 4, ...] 1: [1, 2, 3, 0, ...] 1: 72 - 1: [1, 1, 1, 0, ...] . . - . - - V R + r 1 r 2 V M * V R + -@end group -@end smallexample - -@noindent -Once again, the last two steps just compute a dot product for which -a simple @kbd{*} would have worked equally well. - -@node List Answer 5, List Answer 6, List Answer 4, Answers to Exercises -@subsection List Tutorial Exercise 5 - -@noindent -The obvious first step is to obtain the list of factors with @kbd{k f}. -This list will always be in sorted order, so if there are duplicates -they will be right next to each other. A suitable method is to compare -the list with a copy of itself shifted over by one. - -@smallexample -@group -1: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19] 2: [3, 7, 7, 7, 19, 0] - . 1: [3, 7, 7, 7, 19, 0] 1: [0, 3, 7, 7, 7, 19] - . . - - 19551 k f @key{RET} 0 | @key{TAB} 0 @key{TAB} | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 1, 1, 0, 0] 1: 2 1: 0 - . . . - - V M a = V R + 0 a = -@end group -@end smallexample - -@noindent -Note that we have to arrange for both vectors to have the same length -so that the mapping operation works; no prime factor will ever be -zero, so adding zeros on the left and right is safe. From then on -the job is pretty straightforward. - -Incidentally, Calc provides the -@texline @dfn{M@"obius} @math{\mu} -@infoline @dfn{Moebius mu} -function which is zero if and only if its argument is square-free. It -would be a much more convenient way to do the above test in practice. - -@node List Answer 6, List Answer 7, List Answer 5, Answers to Exercises -@subsection List Tutorial Exercise 6 - -@noindent -First use @kbd{v x 6 @key{RET}} to get a list of integers, then @kbd{V M v x} -to get a list of lists of integers! - -@node List Answer 7, List Answer 8, List Answer 6, Answers to Exercises -@subsection List Tutorial Exercise 7 - -@noindent -Here's one solution. First, compute the triangular list from the previous -exercise and type @kbd{1 -} to subtract one from all the elements. - -@smallexample -@group -1: [ [0], - [0, 1], - [0, 1, 2], - @dots{} - - 1 - -@end group -@end smallexample - -The numbers down the lefthand edge of the list we desire are called -the ``triangular numbers'' (now you know why!). The @expr{n}th -triangular number is the sum of the integers from 1 to @expr{n}, and -can be computed directly by the formula -@texline @math{n (n+1) \over 2}. -@infoline @expr{n * (n+1) / 2}. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [0, 1, 2, 3, 4, 5] 1: [0, 1, 3, 6, 10, 15] - . . - - v x 6 @key{RET} 1 - V M ' $ ($+1)/2 @key{RET} -@end group -@end smallexample - -@noindent -Adding this list to the above list of lists produces the desired -result: - -@smallexample -@group -1: [ [0], - [1, 2], - [3, 4, 5], - [6, 7, 8, 9], - [10, 11, 12, 13, 14], - [15, 16, 17, 18, 19, 20] ] - . - - V M + -@end group -@end smallexample - -If we did not know the formula for triangular numbers, we could have -computed them using a @kbd{V U +} command. We could also have -gotten them the hard way by mapping a reduction across the original -triangular list. - -@smallexample -@group -2: [ [0], [0, 1], ... ] 2: [ [0], [0, 1], ... ] -1: [ [0], [0, 1], ... ] 1: [0, 1, 3, 6, 10, 15] - . . - - @key{RET} V M V R + -@end group -@end smallexample - -@noindent -(This means ``map a @kbd{V R +} command across the vector,'' and -since each element of the main vector is itself a small vector, -@kbd{V R +} computes the sum of its elements.) - -@node List Answer 8, List Answer 9, List Answer 7, Answers to Exercises -@subsection List Tutorial Exercise 8 - -@noindent -The first step is to build a list of values of @expr{x}. - -@smallexample -@group -1: [1, 2, 3, ..., 21] 1: [0, 1, 2, ..., 20] 1: [0, 0.25, 0.5, ..., 5] - . . . - - v x 21 @key{RET} 1 - 4 / s 1 -@end group -@end smallexample - -Next, we compute the Bessel function values. - -@smallexample -@group -1: [0., 0.124, 0.242, ..., -0.328] - . - - V M ' besJ(1,$) @key{RET} -@end group -@end smallexample - -@noindent -(Another way to do this would be @kbd{1 @key{TAB} V M f j}.) - -A way to isolate the maximum value is to compute the maximum using -@kbd{V R X}, then compare all the Bessel values with that maximum. - -@smallexample -@group -2: [0., 0.124, 0.242, ... ] 1: [0, 0, 0, ... ] 2: [0, 0, 0, ... ] -1: 0.5801562 . 1: 1 - . . - - @key{RET} V R X V M a = @key{RET} V R + @key{DEL} -@end group -@end smallexample - -@noindent -It's a good idea to verify, as in the last step above, that only -one value is equal to the maximum. (After all, a plot of -@texline @math{\sin x} -@infoline @expr{sin(x)} -might have many points all equal to the maximum value, 1.) - -The vector we have now has a single 1 in the position that indicates -the maximum value of @expr{x}. Now it is a simple matter to convert -this back into the corresponding value itself. - -@smallexample -@group -2: [0, 0, 0, ... ] 1: [0, 0., 0., ... ] 1: 1.75 -1: [0, 0.25, 0.5, ... ] . . - . - - r 1 V M * V R + -@end group -@end smallexample - -If @kbd{a =} had produced more than one @expr{1} value, this method -would have given the sum of all maximum @expr{x} values; not very -useful! In this case we could have used @kbd{v m} (@code{calc-mask-vector}) -instead. This command deletes all elements of a ``data'' vector that -correspond to zeros in a ``mask'' vector, leaving us with, in this -example, a vector of maximum @expr{x} values. - -The built-in @kbd{a X} command maximizes a function using more -efficient methods. Just for illustration, let's use @kbd{a X} -to maximize @samp{besJ(1,x)} over this same interval. - -@smallexample -@group -2: besJ(1, x) 1: [1.84115, 0.581865] -1: [0 .. 5] . - . - -' besJ(1,x), [0..5] @key{RET} a X x @key{RET} -@end group -@end smallexample - -@noindent -The output from @kbd{a X} is a vector containing the value of @expr{x} -that maximizes the function, and the function's value at that maximum. -As you can see, our simple search got quite close to the right answer. - -@node List Answer 9, List Answer 10, List Answer 8, Answers to Exercises -@subsection List Tutorial Exercise 9 - -@noindent -Step one is to convert our integer into vector notation. - -@smallexample -@group -1: 25129925999 3: 25129925999 - . 2: 10 - 1: [11, 10, 9, ..., 1, 0] - . - - 25129925999 @key{RET} 10 @key{RET} 12 @key{RET} v x 12 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 25129925999 1: [0, 2, 25, 251, 2512, ... ] -2: [100000000000, ... ] . - . - - V M ^ s 1 V M \ -@end group -@end smallexample - -@noindent -(Recall, the @kbd{\} command computes an integer quotient.) - -@smallexample -@group -1: [0, 2, 5, 1, 2, 9, 9, 2, 5, 9, 9, 9] - . - - 10 V M % s 2 -@end group -@end smallexample - -Next we must increment this number. This involves adding one to -the last digit, plus handling carries. There is a carry to the -left out of a digit if that digit is a nine and all the digits to -the right of it are nines. - -@smallexample -@group -1: [0, 0, 0, 0, 0, 1, 1, 0, 0, 1, 1, 1] 1: [1, 1, 1, 0, 0, 1, ... ] - . . - - 9 V M a = v v - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 0, 0, ... ] 1: [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1] - . . - - V U * v v 1 | -@end group -@end smallexample - -@noindent -Accumulating @kbd{*} across a vector of ones and zeros will preserve -only the initial run of ones. These are the carries into all digits -except the rightmost digit. Concatenating a one on the right takes -care of aligning the carries properly, and also adding one to the -rightmost digit. - -@smallexample -@group -2: [0, 0, 0, 0, ... ] 1: [0, 0, 2, 5, 1, 2, 9, 9, 2, 6, 0, 0, 0] -1: [0, 0, 2, 5, ... ] . - . - - 0 r 2 | V M + 10 V M % -@end group -@end smallexample - -@noindent -Here we have concatenated 0 to the @emph{left} of the original number; -this takes care of shifting the carries by one with respect to the -digits that generated them. - -Finally, we must convert this list back into an integer. - -@smallexample -@group -3: [0, 0, 2, 5, ... ] 2: [0, 0, 2, 5, ... ] -2: 1000000000000 1: [1000000000000, 100000000000, ... ] -1: [100000000000, ... ] . - . - - 10 @key{RET} 12 ^ r 1 | - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 0, 20000000000, 5000000000, ... ] 1: 25129926000 - . . - - V M * V R + -@end group -@end smallexample - -@noindent -Another way to do this final step would be to reduce the formula -@w{@samp{10 $$ + $}} across the vector of digits. - -@smallexample -@group -1: [0, 0, 2, 5, ... ] 1: 25129926000 - . . - - V R ' 10 $$ + $ @key{RET} -@end group -@end smallexample - -@node List Answer 10, List Answer 11, List Answer 9, Answers to Exercises -@subsection List Tutorial Exercise 10 - -@noindent -For the list @expr{[a, b, c, d]}, the result is @expr{((a = b) = c) = d}, -which will compare @expr{a} and @expr{b} to produce a 1 or 0, which is -then compared with @expr{c} to produce another 1 or 0, which is then -compared with @expr{d}. This is not at all what Joe wanted. - -Here's a more correct method: - -@smallexample -@group -1: [7, 7, 7, 8, 7] 2: [7, 7, 7, 8, 7] - . 1: 7 - . - - ' [7,7,7,8,7] @key{RET} @key{RET} v r 1 @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, 1, 0, 1] 1: 0 - . . - - V M a = V R * -@end group -@end smallexample - -@node List Answer 11, List Answer 12, List Answer 10, Answers to Exercises -@subsection List Tutorial Exercise 11 - -@noindent -The circle of unit radius consists of those points @expr{(x,y)} for which -@expr{x^2 + y^2 < 1}. We start by generating a vector of @expr{x^2} -and a vector of @expr{y^2}. - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -2: [2., 2., ..., 2.] 2: [2., 2., ..., 2.] -1: [2., 2., ..., 2.] 1: [1.16, 1.98, ..., 0.81] - . . - - v . t . 2. v b 100 @key{RET} @key{RET} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [2., 2., ..., 2.] 1: [0.026, 0.96, ..., 0.036] -1: [0.026, 0.96, ..., 0.036] 2: [0.53, 0.81, ..., 0.094] - . . - - 1 - 2 V M ^ @key{TAB} V M k r 1 - 2 V M ^ -@end group -@end smallexample - -Now we sum the @expr{x^2} and @expr{y^2} values, compare with 1 to -get a vector of 1/0 truth values, then sum the truth values. - -@smallexample -@group -1: [0.56, 1.78, ..., 0.13] 1: [1, 0, ..., 1] 1: 84 - . . . - - + 1 V M a < V R + -@end group -@end smallexample - -@noindent -The ratio @expr{84/100} should approximate the ratio @cpiover{4}. - -@smallexample -@group -1: 0.84 1: 3.36 2: 3.36 1: 1.0695 - . . 1: 3.14159 . - - 100 / 4 * P / -@end group -@end smallexample - -@noindent -Our estimate, 3.36, is off by about 7%. We could get a better estimate -by taking more points (say, 1000), but it's clear that this method is -not very efficient! - -(Naturally, since this example uses random numbers your own answer -will be slightly different from the one shown here!) - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 12, List Answer 13, List Answer 11, Answers to Exercises -@subsection List Tutorial Exercise 12 - -@noindent -This problem can be made a lot easier by taking advantage of some -symmetries. First of all, after some thought it's clear that the -@expr{y} axis can be ignored altogether. Just pick a random @expr{x} -component for one end of the match, pick a random direction -@texline @math{\theta}, -@infoline @expr{theta}, -and see if @expr{x} and -@texline @math{x + \cos \theta} -@infoline @expr{x + cos(theta)} -(which is the @expr{x} coordinate of the other endpoint) cross a line. -The lines are at integer coordinates, so this happens when the two -numbers surround an integer. - -Since the two endpoints are equivalent, we may as well choose the leftmost -of the two endpoints as @expr{x}. Then @expr{theta} is an angle pointing -to the right, in the range -90 to 90 degrees. (We could use radians, but -it would feel like cheating to refer to @cpiover{2} radians while trying -to estimate @cpi{}!) - -In fact, since the field of lines is infinite we can choose the -coordinates 0 and 1 for the lines on either side of the leftmost -endpoint. The rightmost endpoint will be between 0 and 1 if the -match does not cross a line, or between 1 and 2 if it does. So: -Pick random @expr{x} and -@texline @math{\theta}, -@infoline @expr{theta}, -compute -@texline @math{x + \cos \theta}, -@infoline @expr{x + cos(theta)}, -and count how many of the results are greater than one. Simple! - -We can make this go a bit faster by using the @kbd{v .} and @kbd{t .} -commands. - -@smallexample -@group -1: [0.52, 0.71, ..., 0.72] 2: [0.52, 0.71, ..., 0.72] - . 1: [78.4, 64.5, ..., -42.9] - . - -v . t . 1. v b 100 @key{RET} V M k r 180. v b 100 @key{RET} V M k r 90 - -@end group -@end smallexample - -@noindent -(The next step may be slow, depending on the speed of your computer.) - -@smallexample -@group -2: [0.52, 0.71, ..., 0.72] 1: [0.72, 1.14, ..., 1.45] -1: [0.20, 0.43, ..., 0.73] . - . - - m d V M C + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0, 1, ..., 1] 1: 0.64 1: 3.125 - . . . - - 1 V M a > V R + 100 / 2 @key{TAB} / -@end group -@end smallexample - -Let's try the third method, too. We'll use random integers up to -one million. The @kbd{k r} command with an integer argument picks -a random integer. - -@smallexample -@group -2: [1000000, 1000000, ..., 1000000] 2: [78489, 527587, ..., 814975] -1: [1000000, 1000000, ..., 1000000] 1: [324014, 358783, ..., 955450] - . . - - 1000000 v b 100 @key{RET} @key{RET} V M k r @key{TAB} V M k r - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [1, 1, ..., 25] 1: [1, 1, ..., 0] 1: 0.56 - . . . - - V M k g 1 V M a = V R + 100 / - -@end group -@end smallexample -@noindent -@smallexample -@group -1: 10.714 1: 3.273 - . . - - 6 @key{TAB} / Q -@end group -@end smallexample - -For a proof of this property of the GCD function, see section 4.5.2, -exercise 10, of Knuth's @emph{Art of Computer Programming}, volume II. - -If you typed @kbd{v .} and @kbd{t .} before, type them again to -return to full-sized display of vectors. - -@node List Answer 13, List Answer 14, List Answer 12, Answers to Exercises -@subsection List Tutorial Exercise 13 - -@noindent -First, we put the string on the stack as a vector of ASCII codes. - -@smallexample -@group -1: [84, 101, 115, ..., 51] - . - - "Testing, 1, 2, 3 @key{RET} -@end group -@end smallexample - -@noindent -Note that the @kbd{"} key, like @kbd{$}, initiates algebraic entry so -there was no need to type an apostrophe. Also, Calc didn't mind that -we omitted the closing @kbd{"}. (The same goes for all closing delimiters -like @kbd{)} and @kbd{]} at the end of a formula. - -We'll show two different approaches here. In the first, we note that -if the input vector is @expr{[a, b, c, d]}, then the hash code is -@expr{3 (3 (3a + b) + c) + d = 27a + 9b + 3c + d}. In other words, -it's a sum of descending powers of three times the ASCII codes. - -@smallexample -@group -2: [84, 101, 115, ..., 51] 2: [84, 101, 115, ..., 51] -1: 16 1: [15, 14, 13, ..., 0] - . . - - @key{RET} v l v x 16 @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [84, 101, 115, ..., 51] 1: 1960915098 1: 121 -1: [14348907, ..., 1] . . - . - - 3 @key{TAB} V M ^ * 511 % -@end group -@end smallexample - -@noindent -Once again, @kbd{*} elegantly summarizes most of the computation. -But there's an even more elegant approach: Reduce the formula -@kbd{3 $$ + $} across the vector. Recall that this represents a -function of two arguments that computes its first argument times three -plus its second argument. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 1960915098 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' 3$$+$ @key{RET} -@end group -@end smallexample - -@noindent -If you did the decimal arithmetic exercise, this will be familiar. -Basically, we're turning a base-3 vector of digits into an integer, -except that our ``digits'' are much larger than real digits. - -Instead of typing @kbd{511 %} again to reduce the result, we can be -cleverer still and notice that rather than computing a huge integer -and taking the modulo at the end, we can take the modulo at each step -without affecting the result. While this means there are more -arithmetic operations, the numbers we operate on remain small so -the operations are faster. - -@smallexample -@group -1: [84, 101, 115, ..., 51] 1: 121 - . . - - "Testing, 1, 2, 3 @key{RET} V R ' (3$$+$)%511 @key{RET} -@end group -@end smallexample - -Why does this work? Think about a two-step computation: -@w{@expr{3 (3a + b) + c}}. Taking a result modulo 511 basically means -subtracting off enough 511's to put the result in the desired range. -So the result when we take the modulo after every step is, - -@ifnottex -@example -3 (3 a + b - 511 m) + c - 511 n -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ 3 (3 a + b - 511 m) + c - 511 n $$ -\afterdisplay -@end tex - -@noindent -for some suitable integers @expr{m} and @expr{n}. Expanding out by -the distributive law yields - -@ifnottex -@example -9 a + 3 b + c - 511*3 m - 511 n -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ 9 a + 3 b + c - 511\times3 m - 511 n $$ -\afterdisplay -@end tex - -@noindent -The @expr{m} term in the latter formula is redundant because any -contribution it makes could just as easily be made by the @expr{n} -term. So we can take it out to get an equivalent formula with -@expr{n' = 3m + n}, - -@ifnottex -@example -9 a + 3 b + c - 511 n' -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ 9 a + 3 b + c - 511 n' $$ -\afterdisplay -@end tex - -@noindent -which is just the formula for taking the modulo only at the end of -the calculation. Therefore the two methods are essentially the same. - -Later in the tutorial we will encounter @dfn{modulo forms}, which -basically automate the idea of reducing every intermediate result -modulo some value @var{m}. - -@node List Answer 14, Types Answer 1, List Answer 13, Answers to Exercises -@subsection List Tutorial Exercise 14 - -We want to use @kbd{H V U} to nest a function which adds a random -step to an @expr{(x,y)} coordinate. The function is a bit long, but -otherwise the problem is quite straightforward. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.4288, -0.1695 ] - . [ -0.4787, -0.9027 ] - ... - - [0,0] 50 H V U ' <# + [random(2.0)-1, random(2.0)-1]> @key{RET} -@end group -@end smallexample - -Just as the text recommended, we used @samp{< >} nameless function -notation to keep the two @code{random} calls from being evaluated -before nesting even begins. - -We now have a vector of @expr{[x, y]} sub-vectors, which by Calc's -rules acts like a matrix. We can transpose this matrix and unpack -to get a pair of vectors, @expr{x} and @expr{y}, suitable for graphing. - -@smallexample -@group -2: [ 0, 0.4288, -0.4787, ... ] -1: [ 0, -0.1696, -0.9027, ... ] - . - - v t v u g f -@end group -@end smallexample - -Incidentally, because the @expr{x} and @expr{y} are completely -independent in this case, we could have done two separate commands -to create our @expr{x} and @expr{y} vectors of numbers directly. - -To make a random walk of unit steps, we note that @code{sincos} of -a random direction exactly gives us an @expr{[x, y]} step of unit -length; in fact, the new nesting function is even briefer, though -we might want to lower the precision a bit for it. - -@smallexample -@group -2: [0, 0] 1: [ [ 0, 0 ] -1: 50 [ 0.1318, 0.9912 ] - . [ -0.5965, 0.3061 ] - ... - - [0,0] 50 m d p 6 @key{RET} H V U ' <# + sincos(random(360.0))> @key{RET} -@end group -@end smallexample - -Another @kbd{v t v u g f} sequence will graph this new random walk. - -An interesting twist on these random walk functions would be to use -complex numbers instead of 2-vectors to represent points on the plane. -In the first example, we'd use something like @samp{random + random*(0,1)}, -and in the second we could use polar complex numbers with random phase -angles. (This exercise was first suggested in this form by Randal -Schwartz.) - -@node Types Answer 1, Types Answer 2, List Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 1 - -@noindent -If the number is the square root of @cpi{} times a rational number, -then its square, divided by @cpi{}, should be a rational number. - -@smallexample -@group -1: 1.26508260337 1: 0.509433962268 1: 2486645810:4881193627 - . . . - - 2 ^ P / c F -@end group -@end smallexample - -@noindent -Technically speaking this is a rational number, but not one that is -likely to have arisen in the original problem. More likely, it just -happens to be the fraction which most closely represents some -irrational number to within 12 digits. - -But perhaps our result was not quite exact. Let's reduce the -precision slightly and try again: - -@smallexample -@group -1: 0.509433962268 1: 27:53 - . . - - U p 10 @key{RET} c F -@end group -@end smallexample - -@noindent -Aha! It's unlikely that an irrational number would equal a fraction -this simple to within ten digits, so our original number was probably -@texline @math{\sqrt{27 \pi / 53}}. -@infoline @expr{sqrt(27 pi / 53)}. - -Notice that we didn't need to re-round the number when we reduced the -precision. Remember, arithmetic operations always round their inputs -to the current precision before they begin. - -@node Types Answer 2, Types Answer 3, Types Answer 1, Answers to Exercises -@subsection Types Tutorial Exercise 2 - -@noindent -@samp{inf / inf = nan}. Perhaps @samp{1} is the ``obvious'' answer. -But if @w{@samp{17 inf = inf}}, then @samp{17 inf / inf = inf / inf = 17}, too. - -@samp{exp(inf) = inf}. It's tempting to say that the exponential -of infinity must be ``bigger'' than ``regular'' infinity, but as -far as Calc is concerned all infinities are as just as big. -In other words, as @expr{x} goes to infinity, @expr{e^x} also goes -to infinity, but the fact the @expr{e^x} grows much faster than -@expr{x} is not relevant here. - -@samp{exp(-inf) = 0}. Here we have a finite answer even though -the input is infinite. - -@samp{sqrt(-inf) = (0, 1) inf}. Remember that @expr{(0, 1)} -represents the imaginary number @expr{i}. Here's a derivation: -@samp{sqrt(-inf) = @w{sqrt((-1) * inf)} = sqrt(-1) * sqrt(inf)}. -The first part is, by definition, @expr{i}; the second is @code{inf} -because, once again, all infinities are the same size. - -@samp{sqrt(uinf) = uinf}. In fact, we do know something about the -direction because @code{sqrt} is defined to return a value in the -right half of the complex plane. But Calc has no notation for this, -so it settles for the conservative answer @code{uinf}. - -@samp{abs(uinf) = inf}. No matter which direction @expr{x} points, -@samp{abs(x)} always points along the positive real axis. - -@samp{ln(0) = -inf}. Here we have an infinite answer to a finite -input. As in the @expr{1 / 0} case, Calc will only use infinities -here if you have turned on Infinite mode. Otherwise, it will -treat @samp{ln(0)} as an error. - -@node Types Answer 3, Types Answer 4, Types Answer 2, Answers to Exercises -@subsection Types Tutorial Exercise 3 - -@noindent -We can make @samp{inf - inf} be any real number we like, say, -@expr{a}, just by claiming that we added @expr{a} to the first -infinity but not to the second. This is just as true for complex -values of @expr{a}, so @code{nan} can stand for a complex number. -(And, similarly, @code{uinf} can stand for an infinity that points -in any direction in the complex plane, such as @samp{(0, 1) inf}). - -In fact, we can multiply the first @code{inf} by two. Surely -@w{@samp{2 inf - inf = inf}}, but also @samp{2 inf - inf = inf - inf = nan}. -So @code{nan} can even stand for infinity. Obviously it's just -as easy to make it stand for minus infinity as for plus infinity. - -The moral of this story is that ``infinity'' is a slippery fish -indeed, and Calc tries to handle it by having a very simple model -for infinities (only the direction counts, not the ``size''); but -Calc is careful to write @code{nan} any time this simple model is -unable to tell what the true answer is. - -@node Types Answer 4, Types Answer 5, Types Answer 3, Answers to Exercises -@subsection Types Tutorial Exercise 4 - -@smallexample -@group -2: 0@@ 47' 26" 1: 0@@ 2' 47.411765" -1: 17 . - . - - 0@@ 47' 26" @key{RET} 17 / -@end group -@end smallexample - -@noindent -The average song length is two minutes and 47.4 seconds. - -@smallexample -@group -2: 0@@ 2' 47.411765" 1: 0@@ 3' 7.411765" 1: 0@@ 53' 6.000005" -1: 0@@ 0' 20" . . - . - - 20" + 17 * -@end group -@end smallexample - -@noindent -The album would be 53 minutes and 6 seconds long. - -@node Types Answer 5, Types Answer 6, Types Answer 4, Answers to Exercises -@subsection Types Tutorial Exercise 5 - -@noindent -Let's suppose it's January 14, 1991. The easiest thing to do is -to keep trying 13ths of months until Calc reports a Friday. -We can do this by manually entering dates, or by using @kbd{t I}: - -@smallexample -@group -1: 1: 1: - . . . - - ' <2/13> @key{RET} @key{DEL} ' <3/13> @key{RET} t I -@end group -@end smallexample - -@noindent -(Calc assumes the current year if you don't say otherwise.) - -This is getting tedious---we can keep advancing the date by typing -@kbd{t I} over and over again, but let's automate the job by using -vector mapping. The @kbd{t I} command actually takes a second -``how-many-months'' argument, which defaults to one. This -argument is exactly what we want to map over: - -@smallexample -@group -2: 1: [, , -1: [1, 2, 3, 4, 5, 6] , , - . , ] - . - - v x 6 @key{RET} V M t I -@end group -@end smallexample - -@noindent -Et voil@`a, September 13, 1991 is a Friday. - -@smallexample -@group -1: 242 - . - -' - @key{RET} -@end group -@end smallexample - -@noindent -And the answer to our original question: 242 days to go. - -@node Types Answer 6, Types Answer 7, Types Answer 5, Answers to Exercises -@subsection Types Tutorial Exercise 6 - -@noindent -The full rule for leap years is that they occur in every year divisible -by four, except that they don't occur in years divisible by 100, except -that they @emph{do} in years divisible by 400. We could work out the -answer by carefully counting the years divisible by four and the -exceptions, but there is a much simpler way that works even if we -don't know the leap year rule. - -Let's assume the present year is 1991. Years have 365 days, except -that leap years (whenever they occur) have 366 days. So let's count -the number of days between now and then, and compare that to the -number of years times 365. The number of extra days we find must be -equal to the number of leap years there were. - -@smallexample -@group -1: 2: 1: 2925593 - . 1: . - . - - ' @key{RET} ' @key{RET} - - -@end group -@end smallexample -@noindent -@smallexample -@group -3: 2925593 2: 2925593 2: 2925593 1: 1943 -2: 10001 1: 8010 1: 2923650 . -1: 1991 . . - . - - 10001 @key{RET} 1991 - 365 * - -@end group -@end smallexample - -@c [fix-ref Date Forms] -@noindent -There will be 1943 leap years before the year 10001. (Assuming, -of course, that the algorithm for computing leap years remains -unchanged for that long. @xref{Date Forms}, for some interesting -background information in that regard.) - -@node Types Answer 7, Types Answer 8, Types Answer 6, Answers to Exercises -@subsection Types Tutorial Exercise 7 - -@noindent -The relative errors must be converted to absolute errors so that -@samp{+/-} notation may be used. - -@smallexample -@group -1: 1. 2: 1. - . 1: 0.2 - . - - 20 @key{RET} .05 * 4 @key{RET} .05 * -@end group -@end smallexample - -Now we simply chug through the formula. - -@smallexample -@group -1: 19.7392088022 1: 394.78 +/- 19.739 1: 6316.5 +/- 706.21 - . . . - - 2 P 2 ^ * 20 p 1 * 4 p .2 @key{RET} 2 ^ * -@end group -@end smallexample - -It turns out the @kbd{v u} command will unpack an error form as -well as a vector. This saves us some retyping of numbers. - -@smallexample -@group -3: 6316.5 +/- 706.21 2: 6316.5 +/- 706.21 -2: 6316.5 1: 0.1118 -1: 706.21 . - . - - @key{RET} v u @key{TAB} / -@end group -@end smallexample - -@noindent -Thus the volume is 6316 cubic centimeters, within about 11 percent. - -@node Types Answer 8, Types Answer 9, Types Answer 7, Answers to Exercises -@subsection Types Tutorial Exercise 8 - -@noindent -The first answer is pretty simple: @samp{1 / (0 .. 10) = (0.1 .. inf)}. -Since a number in the interval @samp{(0 .. 10)} can get arbitrarily -close to zero, its reciprocal can get arbitrarily large, so the answer -is an interval that effectively means, ``any number greater than 0.1'' -but with no upper bound. - -The second answer, similarly, is @samp{1 / (-10 .. 0) = (-inf .. -0.1)}. - -Calc normally treats division by zero as an error, so that the formula -@w{@samp{1 / 0}} is left unsimplified. Our third problem, -@w{@samp{1 / [0 .. 10]}}, also (potentially) divides by zero because zero -is now a member of the interval. So Calc leaves this one unevaluated, too. - -If you turn on Infinite mode by pressing @kbd{m i}, you will -instead get the answer @samp{[0.1 .. inf]}, which includes infinity -as a possible value. - -The fourth calculation, @samp{1 / (-10 .. 10)}, has the same problem. -Zero is buried inside the interval, but it's still a possible value. -It's not hard to see that the actual result of @samp{1 / (-10 .. 10)} -will be either greater than @mathit{0.1}, or less than @mathit{-0.1}. Thus -the interval goes from minus infinity to plus infinity, with a ``hole'' -in it from @mathit{-0.1} to @mathit{0.1}. Calc doesn't have any way to -represent this, so it just reports @samp{[-inf .. inf]} as the answer. -It may be disappointing to hear ``the answer lies somewhere between -minus infinity and plus infinity, inclusive,'' but that's the best -that interval arithmetic can do in this case. - -@node Types Answer 9, Types Answer 10, Types Answer 8, Answers to Exercises -@subsection Types Tutorial Exercise 9 - -@smallexample -@group -1: [-3 .. 3] 2: [-3 .. 3] 2: [0 .. 9] - . 1: [0 .. 9] 1: [-9 .. 9] - . . - - [ 3 n .. 3 ] @key{RET} 2 ^ @key{TAB} @key{RET} * -@end group -@end smallexample - -@noindent -In the first case the result says, ``if a number is between @mathit{-3} and -3, its square is between 0 and 9.'' The second case says, ``the product -of two numbers each between @mathit{-3} and 3 is between @mathit{-9} and 9.'' - -An interval form is not a number; it is a symbol that can stand for -many different numbers. Two identical-looking interval forms can stand -for different numbers. - -The same issue arises when you try to square an error form. - -@node Types Answer 10, Types Answer 11, Types Answer 9, Answers to Exercises -@subsection Types Tutorial Exercise 10 - -@noindent -Testing the first number, we might arbitrarily choose 17 for @expr{x}. - -@smallexample -@group -1: 17 mod 811749613 2: 17 mod 811749613 1: 533694123 mod 811749613 - . 811749612 . - . - - 17 M 811749613 @key{RET} 811749612 ^ -@end group -@end smallexample - -@noindent -Since 533694123 is (considerably) different from 1, the number 811749613 -must not be prime. - -It's awkward to type the number in twice as we did above. There are -various ways to avoid this, and algebraic entry is one. In fact, using -a vector mapping operation we can perform several tests at once. Let's -use this method to test the second number. - -@smallexample -@group -2: [17, 42, 100000] 1: [1 mod 15485863, 1 mod ... ] -1: 15485863 . - . - - [17 42 100000] 15485863 @key{RET} V M ' ($$ mod $)^($-1) @key{RET} -@end group -@end smallexample - -@noindent -The result is three ones (modulo @expr{n}), so it's very probable that -15485863 is prime. (In fact, this number is the millionth prime.) - -Note that the functions @samp{($$^($-1)) mod $} or @samp{$$^($-1) % $} -would have been hopelessly inefficient, since they would have calculated -the power using full integer arithmetic. - -Calc has a @kbd{k p} command that does primality testing. For small -numbers it does an exact test; for large numbers it uses a variant -of the Fermat test we used here. You can use @kbd{k p} repeatedly -to prove that a large integer is prime with any desired probability. - -@node Types Answer 11, Types Answer 12, Types Answer 10, Answers to Exercises -@subsection Types Tutorial Exercise 11 - -@noindent -There are several ways to insert a calculated number into an HMS form. -One way to convert a number of seconds to an HMS form is simply to -multiply the number by an HMS form representing one second: - -@smallexample -@group -1: 31415926.5359 2: 31415926.5359 1: 8726@@ 38' 46.5359" - . 1: 0@@ 0' 1" . - . - - P 1e7 * 0@@ 0' 1" * - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 8726@@ 38' 46.5359" 1: 6@@ 6' 2.5359" mod 24@@ 0' 0" -1: 15@@ 27' 16" mod 24@@ 0' 0" . - . - - x time @key{RET} + -@end group -@end smallexample - -@noindent -It will be just after six in the morning. - -The algebraic @code{hms} function can also be used to build an -HMS form: - -@smallexample -@group -1: hms(0, 0, 10000000. pi) 1: 8726@@ 38' 46.5359" - . . - - ' hms(0, 0, 1e7 pi) @key{RET} = -@end group -@end smallexample - -@noindent -The @kbd{=} key is necessary to evaluate the symbol @samp{pi} to -the actual number 3.14159... - -@node Types Answer 12, Types Answer 13, Types Answer 11, Answers to Exercises -@subsection Types Tutorial Exercise 12 - -@noindent -As we recall, there are 17 songs of about 2 minutes and 47 seconds -each. - -@smallexample -@group -2: 0@@ 2' 47" 1: [0@@ 3' 7" .. 0@@ 3' 47"] -1: [0@@ 0' 20" .. 0@@ 1' 0"] . - . - - [ 0@@ 20" .. 0@@ 1' ] + - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0@@ 52' 59." .. 1@@ 4' 19."] - . - - 17 * -@end group -@end smallexample - -@noindent -No matter how long it is, the album will fit nicely on one CD. - -@node Types Answer 13, Types Answer 14, Types Answer 12, Answers to Exercises -@subsection Types Tutorial Exercise 13 - -@noindent -Type @kbd{' 1 yr @key{RET} u c s @key{RET}}. The answer is 31557600 seconds. - -@node Types Answer 14, Types Answer 15, Types Answer 13, Answers to Exercises -@subsection Types Tutorial Exercise 14 - -@noindent -How long will it take for a signal to get from one end of the computer -to the other? - -@smallexample -@group -1: m / c 1: 3.3356 ns - . . - - ' 1 m / c @key{RET} u c ns @key{RET} -@end group -@end smallexample - -@noindent -(Recall, @samp{c} is a ``unit'' corresponding to the speed of light.) - -@smallexample -@group -1: 3.3356 ns 1: 0.81356 ns / ns 1: 0.81356 -2: 4.1 ns . . - . - - ' 4.1 ns @key{RET} / u s -@end group -@end smallexample - -@noindent -Thus a signal could take up to 81 percent of a clock cycle just to -go from one place to another inside the computer, assuming the signal -could actually attain the full speed of light. Pretty tight! - -@node Types Answer 15, Algebra Answer 1, Types Answer 14, Answers to Exercises -@subsection Types Tutorial Exercise 15 - -@noindent -The speed limit is 55 miles per hour on most highways. We want to -find the ratio of Sam's speed to the US speed limit. - -@smallexample -@group -1: 55 mph 2: 55 mph 3: 11 hr mph / yd - . 1: 5 yd / hr . - . - - ' 55 mph @key{RET} ' 5 yd/hr @key{RET} / -@end group -@end smallexample - -The @kbd{u s} command cancels out these units to get a plain -number. Now we take the logarithm base two to find the final -answer, assuming that each successive pill doubles his speed. - -@smallexample -@group -1: 19360. 2: 19360. 1: 14.24 - . 1: 2 . - . - - u s 2 B -@end group -@end smallexample - -@noindent -Thus Sam can take up to 14 pills without a worry. - -@node Algebra Answer 1, Algebra Answer 2, Types Answer 15, Answers to Exercises -@subsection Algebra Tutorial Exercise 1 - -@noindent -@c [fix-ref Declarations] -The result @samp{sqrt(x)^2} is simplified back to @expr{x} by the -Calculator, but @samp{sqrt(x^2)} is not. (Consider what happens -if @w{@expr{x = -4}}.) If @expr{x} is real, this formula could be -simplified to @samp{abs(x)}, but for general complex arguments even -that is not safe. (@xref{Declarations}, for a way to tell Calc -that @expr{x} is known to be real.) - -@node Algebra Answer 2, Algebra Answer 3, Algebra Answer 1, Answers to Exercises -@subsection Algebra Tutorial Exercise 2 - -@noindent -Suppose our roots are @expr{[a, b, c]}. We want a polynomial which -is zero when @expr{x} is any of these values. The trivial polynomial -@expr{x-a} is zero when @expr{x=a}, so the product @expr{(x-a)(x-b)(x-c)} -will do the job. We can use @kbd{a c x} to write this in a more -familiar form. - -@smallexample -@group -1: 34 x - 24 x^3 1: [1.19023, -1.19023, 0] - . . - - r 2 a P x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [x - 1.19023, x + 1.19023, x] 1: (x - 1.19023) (x + 1.19023) x - . . - - V M ' x-$ @key{RET} V R * - -@end group -@end smallexample -@noindent -@smallexample -@group -1: x^3 - 1.41666 x 1: 34 x - 24 x^3 - . . - - a c x @key{RET} 24 n * a x -@end group -@end smallexample - -@noindent -Sure enough, our answer (multiplied by a suitable constant) is the -same as the original polynomial. - -@node Algebra Answer 3, Algebra Answer 4, Algebra Answer 2, Answers to Exercises -@subsection Algebra Tutorial Exercise 3 - -@smallexample -@group -1: x sin(pi x) 1: (sin(pi x) - pi x cos(pi x)) / pi^2 - . . - - ' x sin(pi x) @key{RET} m r a i x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [y, 1] -2: (sin(pi x) - pi x cos(pi x)) / pi^2 - . - - ' [y,1] @key{RET} @key{TAB} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [(sin(pi y) - pi y cos(pi y)) / pi^2, (sin(pi) - pi cos(pi)) / pi^2] - . - - V M $ @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -1: (sin(pi y) - pi y cos(pi y)) / pi^2 + (pi cos(pi) - sin(pi)) / pi^2 - . - - V R - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: (sin(3.14159 y) - 3.14159 y cos(3.14159 y)) / 9.8696 - 0.3183 - . - - = - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [0., -0.95493, 0.63662, -1.5915, 1.2732] - . - - v x 5 @key{RET} @key{TAB} V M $ @key{RET} -@end group -@end smallexample - -@node Algebra Answer 4, Rewrites Answer 1, Algebra Answer 3, Answers to Exercises -@subsection Algebra Tutorial Exercise 4 - -@noindent -The hard part is that @kbd{V R +} is no longer sufficient to add up all -the contributions from the slices, since the slices have varying -coefficients. So first we must come up with a vector of these -coefficients. Here's one way: - -@smallexample -@group -2: -1 2: 3 1: [4, 2, ..., 4] -1: [1, 2, ..., 9] 1: [-1, 1, ..., -1] . - . . - - 1 n v x 9 @key{RET} V M ^ 3 @key{TAB} - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: [4, 2, ..., 4, 1] 1: [1, 4, 2, ..., 4, 1] - . . - - 1 | 1 @key{TAB} | -@end group -@end smallexample - -@noindent -Now we compute the function values. Note that for this method we need -eleven values, including both endpoints of the desired interval. - -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [1, 1.1, 1.2, ... , 1.8, 1.9, 2.] - . - - 11 @key{RET} 1 @key{RET} .1 @key{RET} C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 4, 2, ..., 4, 1] -1: [0., 0.084941, 0.16993, ... ] - . - - ' sin(x) ln(x) @key{RET} m r p 5 @key{RET} V M $ @key{RET} -@end group -@end smallexample - -@noindent -Once again this calls for @kbd{V M * V R +}; a simple @kbd{*} does the -same thing. - -@smallexample -@group -1: 11.22 1: 1.122 1: 0.374 - . . . - - * .1 * 3 / -@end group -@end smallexample - -@noindent -Wow! That's even better than the result from the Taylor series method. - -@node Rewrites Answer 1, Rewrites Answer 2, Algebra Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 1 - -@noindent -We'll use Big mode to make the formulas more readable. - -@smallexample -@group - ___ - 2 + V 2 -1: (2 + sqrt(2)) / (1 + sqrt(2)) 1: -------- - . ___ - 1 + V 2 - - . - - ' (2+sqrt(2)) / (1+sqrt(2)) @key{RET} d B -@end group -@end smallexample - -@noindent -Multiplying by the conjugate helps because @expr{(a+b) (a-b) = a^2 - b^2}. - -@smallexample -@group - ___ ___ -1: (2 + V 2 ) (V 2 - 1) - . - - a r a/(b+c) := a*(b-c) / (b^2-c^2) @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group - ___ ___ -1: 2 + V 2 - 2 1: V 2 - . . - - a r a*(b+c) := a*b + a*c a s -@end group -@end smallexample - -@noindent -(We could have used @kbd{a x} instead of a rewrite rule for the -second step.) - -The multiply-by-conjugate rule turns out to be useful in many -different circumstances, such as when the denominator involves -sines and cosines or the imaginary constant @code{i}. - -@node Rewrites Answer 2, Rewrites Answer 3, Rewrites Answer 1, Answers to Exercises -@subsection Rewrites Tutorial Exercise 2 - -@noindent -Here is the rule set: - -@smallexample -@group -[ fib(n) := fib(n, 1, 1) :: integer(n) :: n >= 1, - fib(1, x, y) := x, - fib(n, x, y) := fib(n-1, y, x+y) ] -@end group -@end smallexample - -@noindent -The first rule turns a one-argument @code{fib} that people like to write -into a three-argument @code{fib} that makes computation easier. The -second rule converts back from three-argument form once the computation -is done. The third rule does the computation itself. It basically -says that if @expr{x} and @expr{y} are two consecutive Fibonacci numbers, -then @expr{y} and @expr{x+y} are the next (overlapping) pair of Fibonacci -numbers. - -Notice that because the number @expr{n} was ``validated'' by the -conditions on the first rule, there is no need to put conditions on -the other rules because the rule set would never get that far unless -the input were valid. That further speeds computation, since no -extra conditions need to be checked at every step. - -Actually, a user with a nasty sense of humor could enter a bad -three-argument @code{fib} call directly, say, @samp{fib(0, 1, 1)}, -which would get the rules into an infinite loop. One thing that would -help keep this from happening by accident would be to use something like -@samp{ZzFib} instead of @code{fib} as the name of the three-argument -function. - -@node Rewrites Answer 3, Rewrites Answer 4, Rewrites Answer 2, Answers to Exercises -@subsection Rewrites Tutorial Exercise 3 - -@noindent -He got an infinite loop. First, Calc did as expected and rewrote -@w{@samp{2 + 3 x}} to @samp{f(2, 3, x)}. Then it looked for ways to -apply the rule again, and found that @samp{f(2, 3, x)} looks like -@samp{a + b x} with @w{@samp{a = 0}} and @samp{b = 1}, so it rewrote to -@samp{f(0, 1, f(2, 3, x))}. It then wrapped another @samp{f(0, 1, ...)} -around that, and so on, ad infinitum. Joe should have used @kbd{M-1 a r} -to make sure the rule applied only once. - -(Actually, even the first step didn't work as he expected. What Calc -really gives for @kbd{M-1 a r} in this situation is @samp{f(3 x, 1, 2)}, -treating 2 as the ``variable,'' and @samp{3 x} as a constant being added -to it. While this may seem odd, it's just as valid a solution as the -``obvious'' one. One way to fix this would be to add the condition -@samp{:: variable(x)} to the rule, to make sure the thing that matches -@samp{x} is indeed a variable, or to change @samp{x} to @samp{quote(x)} -on the lefthand side, so that the rule matches the actual variable -@samp{x} rather than letting @samp{x} stand for something else.) - -@node Rewrites Answer 4, Rewrites Answer 5, Rewrites Answer 3, Answers to Exercises -@subsection Rewrites Tutorial Exercise 4 - -@noindent -@ignore -@starindex -@end ignore -@tindex seq -Here is a suitable set of rules to solve the first part of the problem: - -@smallexample -@group -[ seq(n, c) := seq(n/2, c+1) :: n%2 = 0, - seq(n, c) := seq(3n+1, c+1) :: n%2 = 1 :: n > 1 ] -@end group -@end smallexample - -Given the initial formula @samp{seq(6, 0)}, application of these -rules produces the following sequence of formulas: - -@example -seq( 3, 1) -seq(10, 2) -seq( 5, 3) -seq(16, 4) -seq( 8, 5) -seq( 4, 6) -seq( 2, 7) -seq( 1, 8) -@end example - -@noindent -whereupon neither of the rules match, and rewriting stops. - -We can pretty this up a bit with a couple more rules: - -@smallexample -@group -[ seq(n) := seq(n, 0), - seq(1, c) := c, - ... ] -@end group -@end smallexample - -@noindent -Now, given @samp{seq(6)} as the starting configuration, we get 8 -as the result. - -The change to return a vector is quite simple: - -@smallexample -@group -[ seq(n) := seq(n, []) :: integer(n) :: n > 0, - seq(1, v) := v | 1, - seq(n, v) := seq(n/2, v | n) :: n%2 = 0, - seq(n, v) := seq(3n+1, v | n) :: n%2 = 1 ] -@end group -@end smallexample - -@noindent -Given @samp{seq(6)}, the result is @samp{[6, 3, 10, 5, 16, 8, 4, 2, 1]}. - -Notice that the @expr{n > 1} guard is no longer necessary on the last -rule since the @expr{n = 1} case is now detected by another rule. -But a guard has been added to the initial rule to make sure the -initial value is suitable before the computation begins. - -While still a good idea, this guard is not as vitally important as it -was for the @code{fib} function, since calling, say, @samp{seq(x, [])} -will not get into an infinite loop. Calc will not be able to prove -the symbol @samp{x} is either even or odd, so none of the rules will -apply and the rewrites will stop right away. - -@node Rewrites Answer 5, Rewrites Answer 6, Rewrites Answer 4, Answers to Exercises -@subsection Rewrites Tutorial Exercise 5 - -@noindent -@ignore -@starindex -@end ignore -@tindex nterms -If @expr{x} is the sum @expr{a + b}, then `@tfn{nterms(}@var{x}@tfn{)}' must -be `@tfn{nterms(}@var{a}@tfn{)}' plus `@tfn{nterms(}@var{b}@tfn{)}'. If @expr{x} -is not a sum, then `@tfn{nterms(}@var{x}@tfn{)}' = 1. - -@smallexample -@group -[ nterms(a + b) := nterms(a) + nterms(b), - nterms(x) := 1 ] -@end group -@end smallexample - -@noindent -Here we have taken advantage of the fact that earlier rules always -match before later rules; @samp{nterms(x)} will only be tried if we -already know that @samp{x} is not a sum. - -@node Rewrites Answer 6, Programming Answer 1, Rewrites Answer 5, Answers to Exercises -@subsection Rewrites Tutorial Exercise 6 - -@noindent -Here is a rule set that will do the job: - -@smallexample -@group -[ a*(b + c) := a*b + a*c, - opt(a) O(x^n) + opt(b) O(x^m) := O(x^n) :: n <= m - :: constant(a) :: constant(b), - opt(a) O(x^n) + opt(b) x^m := O(x^n) :: n <= m - :: constant(a) :: constant(b), - a O(x^n) := O(x^n) :: constant(a), - x^opt(m) O(x^n) := O(x^(n+m)), - O(x^n) O(x^m) := O(x^(n+m)) ] -@end group -@end smallexample - -If we really want the @kbd{+} and @kbd{*} keys to operate naturally -on power series, we should put these rules in @code{EvalRules}. For -testing purposes, it is better to put them in a different variable, -say, @code{O}, first. - -The first rule just expands products of sums so that the rest of the -rules can assume they have an expanded-out polynomial to work with. -Note that this rule does not mention @samp{O} at all, so it will -apply to any product-of-sum it encounters---this rule may surprise -you if you put it into @code{EvalRules}! - -In the second rule, the sum of two O's is changed to the smaller O. -The optional constant coefficients are there mostly so that -@samp{O(x^2) - O(x^3)} and @samp{O(x^3) - O(x^2)} are handled -as well as @samp{O(x^2) + O(x^3)}. - -The third rule absorbs higher powers of @samp{x} into O's. - -The fourth rule says that a constant times a negligible quantity -is still negligible. (This rule will also match @samp{O(x^3) / 4}, -with @samp{a = 1/4}.) - -The fifth rule rewrites, for example, @samp{x^2 O(x^3)} to @samp{O(x^5)}. -(It is easy to see that if one of these forms is negligible, the other -is, too.) Notice the @samp{x^opt(m)} to pick up terms like -@w{@samp{x O(x^3)}}. Optional powers will match @samp{x} as @samp{x^1} -but not 1 as @samp{x^0}. This turns out to be exactly what we want here. - -The sixth rule is the corresponding rule for products of two O's. - -Another way to solve this problem would be to create a new ``data type'' -that represents truncated power series. We might represent these as -function calls @samp{series(@var{coefs}, @var{x})} where @var{coefs} is -a vector of coefficients for @expr{x^0}, @expr{x^1}, @expr{x^2}, and so -on. Rules would exist for sums and products of such @code{series} -objects, and as an optional convenience could also know how to combine a -@code{series} object with a normal polynomial. (With this, and with a -rule that rewrites @samp{O(x^n)} to the equivalent @code{series} form, -you could still enter power series in exactly the same notation as -before.) Operations on such objects would probably be more efficient, -although the objects would be a bit harder to read. - -@c [fix-ref Compositions] -Some other symbolic math programs provide a power series data type -similar to this. Mathematica, for example, has an object that looks -like @samp{PowerSeries[@var{x}, @var{x0}, @var{coefs}, @var{nmin}, -@var{nmax}, @var{den}]}, where @var{x0} is the point about which the -power series is taken (we've been assuming this was always zero), -and @var{nmin}, @var{nmax}, and @var{den} allow pseudo-power-series -with fractional or negative powers. Also, the @code{PowerSeries} -objects have a special display format that makes them look like -@samp{2 x^2 + O(x^4)} when they are printed out. (@xref{Compositions}, -for a way to do this in Calc, although for something as involved as -this it would probably be better to write the formatting routine -in Lisp.) - -@node Programming Answer 1, Programming Answer 2, Rewrites Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 1 - -@noindent -Just enter the formula @samp{ninteg(sin(t)/t, t, 0, x)}, type -@kbd{Z F}, and answer the questions. Since this formula contains two -variables, the default argument list will be @samp{(t x)}. We want to -change this to @samp{(x)} since @expr{t} is really a dummy variable -to be used within @code{ninteg}. - -The exact keystrokes are @kbd{Z F s Si @key{RET} @key{RET} C-b C-b @key{DEL} @key{DEL} @key{RET} y}. -(The @kbd{C-b C-b @key{DEL} @key{DEL}} are what fix the argument list.) - -@node Programming Answer 2, Programming Answer 3, Programming Answer 1, Answers to Exercises -@subsection Programming Tutorial Exercise 2 - -@noindent -One way is to move the number to the top of the stack, operate on -it, then move it back: @kbd{C-x ( M-@key{TAB} n M-@key{TAB} M-@key{TAB} C-x )}. - -Another way is to negate the top three stack entries, then negate -again the top two stack entries: @kbd{C-x ( M-3 n M-2 n C-x )}. - -Finally, it turns out that a negative prefix argument causes a -command like @kbd{n} to operate on the specified stack entry only, -which is just what we want: @kbd{C-x ( M-- 3 n C-x )}. - -Just for kicks, let's also do it algebraically: -@w{@kbd{C-x ( ' -$$$, $$, $ @key{RET} C-x )}}. - -@node Programming Answer 3, Programming Answer 4, Programming Answer 2, Answers to Exercises -@subsection Programming Tutorial Exercise 3 - -@noindent -Each of these functions can be computed using the stack, or using -algebraic entry, whichever way you prefer: - -@noindent -Computing -@texline @math{\displaystyle{\sin x \over x}}: -@infoline @expr{sin(x) / x}: - -Using the stack: @kbd{C-x ( @key{RET} S @key{TAB} / C-x )}. - -Using algebraic entry: @kbd{C-x ( ' sin($)/$ @key{RET} C-x )}. - -@noindent -Computing the logarithm: - -Using the stack: @kbd{C-x ( @key{TAB} B C-x )} - -Using algebraic entry: @kbd{C-x ( ' log($,$$) @key{RET} C-x )}. - -@noindent -Computing the vector of integers: - -Using the stack: @kbd{C-x ( 1 @key{RET} 1 C-u v x C-x )}. (Recall that -@kbd{C-u v x} takes the vector size, starting value, and increment -from the stack.) - -Alternatively: @kbd{C-x ( ~ v x C-x )}. (The @kbd{~} key pops a -number from the stack and uses it as the prefix argument for the -next command.) - -Using algebraic entry: @kbd{C-x ( ' index($) @key{RET} C-x )}. - -@node Programming Answer 4, Programming Answer 5, Programming Answer 3, Answers to Exercises -@subsection Programming Tutorial Exercise 4 - -@noindent -Here's one way: @kbd{C-x ( @key{RET} V R + @key{TAB} v l / C-x )}. - -@node Programming Answer 5, Programming Answer 6, Programming Answer 4, Answers to Exercises -@subsection Programming Tutorial Exercise 5 - -@smallexample -@group -2: 1 1: 1.61803398502 2: 1.61803398502 -1: 20 . 1: 1.61803398875 - . . - - 1 @key{RET} 20 Z < & 1 + Z > I H P -@end group -@end smallexample - -@noindent -This answer is quite accurate. - -@node Programming Answer 6, Programming Answer 7, Programming Answer 5, Answers to Exercises -@subsection Programming Tutorial Exercise 6 - -@noindent -Here is the matrix: - -@example -[ [ 0, 1 ] * [a, b] = [b, a + b] - [ 1, 1 ] ] -@end example - -@noindent -Thus @samp{[0, 1; 1, 1]^n * [1, 1]} computes Fibonacci numbers @expr{n+1} -and @expr{n+2}. Here's one program that does the job: - -@example -C-x ( ' [0, 1; 1, 1] ^ ($-1) * [1, 1] @key{RET} v u @key{DEL} C-x ) -@end example - -@noindent -This program is quite efficient because Calc knows how to raise a -matrix (or other value) to the power @expr{n} in only -@texline @math{\log_2 n} -@infoline @expr{log(n,2)} -steps. For example, this program can compute the 1000th Fibonacci -number (a 209-digit integer!) in about 10 steps; even though the -@kbd{Z < ... Z >} solution had much simpler steps, it would have -required so many steps that it would not have been practical. - -@node Programming Answer 7, Programming Answer 8, Programming Answer 6, Answers to Exercises -@subsection Programming Tutorial Exercise 7 - -@noindent -The trick here is to compute the harmonic numbers differently, so that -the loop counter itself accumulates the sum of reciprocals. We use -a separate variable to hold the integer counter. - -@smallexample -@group -1: 1 2: 1 1: . - . 1: 4 - . - - 1 t 1 1 @key{RET} 4 Z ( t 2 r 1 1 + s 1 & Z ) -@end group -@end smallexample - -@noindent -The body of the loop goes as follows: First save the harmonic sum -so far in variable 2. Then delete it from the stack; the for loop -itself will take care of remembering it for us. Next, recall the -count from variable 1, add one to it, and feed its reciprocal to -the for loop to use as the step value. The for loop will increase -the ``loop counter'' by that amount and keep going until the -loop counter exceeds 4. - -@smallexample -@group -2: 31 3: 31 -1: 3.99498713092 2: 3.99498713092 - . 1: 4.02724519544 - . - - r 1 r 2 @key{RET} 31 & + -@end group -@end smallexample - -Thus we find that the 30th harmonic number is 3.99, and the 31st -harmonic number is 4.02. - -@node Programming Answer 8, Programming Answer 9, Programming Answer 7, Answers to Exercises -@subsection Programming Tutorial Exercise 8 - -@noindent -The first step is to compute the derivative @expr{f'(x)} and thus -the formula -@texline @math{\displaystyle{x - {f(x) \over f'(x)}}}. -@infoline @expr{x - f(x)/f'(x)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: sin(cos(x)) - 0.5 3: 4.5 -1: 4.5 2: sin(cos(x)) - 0.5 - . 1: -(sin(x) cos(cos(x))) - . - -' sin(cos(x))-0.5 @key{RET} 4.5 m r C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} - -@end group -@end smallexample -@noindent -@smallexample -@group -2: 4.5 -1: x + (sin(cos(x)) - 0.5) / sin(x) cos(cos(x)) - . - - / ' x @key{RET} @key{TAB} - t 1 -@end group -@end smallexample - -Now, we enter the loop. We'll use a repeat loop with a 20-repetition -limit just in case the method fails to converge for some reason. -(Normally, the @w{@kbd{Z /}} command will stop the loop before all 20 -repetitions are done.) - -@smallexample -@group -1: 4.5 3: 4.5 2: 4.5 - . 2: x + (sin(cos(x)) ... 1: 5.24196456928 - 1: 4.5 . - . - - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} -@end group -@end smallexample - -This is the new guess for @expr{x}. Now we compare it with the -old one to see if we've converged. - -@smallexample -@group -3: 5.24196 2: 5.24196 1: 5.24196 1: 5.26345856348 -2: 5.24196 1: 0 . . -1: 4.5 . - . - - @key{RET} M-@key{TAB} a = Z / Z > Z ' C-x ) -@end group -@end smallexample - -The loop converges in just a few steps to this value. To check -the result, we can simply substitute it back into the equation. - -@smallexample -@group -2: 5.26345856348 -1: 0.499999999997 - . - - @key{RET} ' sin(cos($)) @key{RET} -@end group -@end smallexample - -Let's test the new definition again: - -@smallexample -@group -2: x^2 - 9 1: 3. -1: 1 . - . - - ' x^2-9 @key{RET} 1 X -@end group -@end smallexample - -Once again, here's the full Newton's Method definition: - -@example -@group -C-x ( Z ` @key{TAB} @key{RET} a d x @key{RET} / ' x @key{RET} @key{TAB} - t 1 - 20 Z < @key{RET} r 1 @key{TAB} s l x @key{RET} - @key{RET} M-@key{TAB} a = Z / - Z > - Z ' -C-x ) -@end group -@end example - -@c [fix-ref Nesting and Fixed Points] -It turns out that Calc has a built-in command for applying a formula -repeatedly until it converges to a number. @xref{Nesting and Fixed Points}, -to see how to use it. - -@c [fix-ref Root Finding] -Also, of course, @kbd{a R} is a built-in command that uses Newton's -method (among others) to look for numerical solutions to any equation. -@xref{Root Finding}. - -@node Programming Answer 9, Programming Answer 10, Programming Answer 8, Answers to Exercises -@subsection Programming Tutorial Exercise 9 - -@noindent -The first step is to adjust @expr{z} to be greater than 5. A simple -``for'' loop will do the job here. If @expr{z} is less than 5, we -reduce the problem using -@texline @math{\psi(z) = \psi(z+1) - 1/z}. -@infoline @expr{psi(z) = psi(z+1) - 1/z}. We go -on to compute -@texline @math{\psi(z+1)}, -@infoline @expr{psi(z+1)}, -and remember to add back a factor of @expr{-1/z} when we're done. This -step is repeated until @expr{z > 5}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -1: 1. 1: 1. - . . - - 1.0 @key{RET} C-x ( Z ` s 1 0 t 2 -@end group -@end smallexample - -Here, variable 1 holds @expr{z} and variable 2 holds the adjustment -factor. If @expr{z < 5}, we use a loop to increase it. - -(By the way, we started with @samp{1.0} instead of the integer 1 because -otherwise the calculation below will try to do exact fractional arithmetic, -and will never converge because fractions compare equal only if they -are exactly equal, not just equal to within the current precision.) - -@smallexample -@group -3: 1. 2: 1. 1: 6. -2: 1. 1: 1 . -1: 5 . - . - - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] -@end group -@end smallexample - -Now we compute the initial part of the sum: -@texline @math{\ln z - {1 \over 2z}} -@infoline @expr{ln(z) - 1/2z} -minus the adjustment factor. - -@smallexample -@group -2: 1.79175946923 2: 1.7084261359 1: -0.57490719743 -1: 0.0833333333333 1: 2.28333333333 . - . . - - L r 1 2 * & - r 2 - -@end group -@end smallexample - -Now we evaluate the series. We'll use another ``for'' loop counting -up the value of @expr{2 n}. (Calc does have a summation command, -@kbd{a +}, but we'll use loops just to get more practice with them.) - -@smallexample -@group -3: -0.5749 3: -0.5749 4: -0.5749 2: -0.5749 -2: 2 2: 1:6 3: 1:6 1: 2.3148e-3 -1: 40 1: 2 2: 2 . - . . 1: 36. - . - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - -@end group -@end smallexample -@noindent -@smallexample -@group -3: -0.5749 3: -0.5772 2: -0.5772 1: -0.577215664892 -2: -0.5749 2: -0.5772 1: 0 . -1: 2.3148e-3 1: -0.5749 . - . . - - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / 2 Z ) Z ' C-x ) -@end group -@end smallexample - -This is the value of -@texline @math{-\gamma}, -@infoline @expr{- gamma}, -with a slight bit of roundoff error. To get a full 12 digits, let's use -a higher precision: - -@smallexample -@group -2: -0.577215664892 2: -0.577215664892 -1: 1. 1: -0.577215664901532 - - 1. @key{RET} p 16 @key{RET} X -@end group -@end smallexample - -Here's the complete sequence of keystrokes: - -@example -@group -C-x ( Z ` s 1 0 t 2 - @key{RET} 5 a < Z [ 5 Z ( & s + 2 1 s + 1 1 Z ) r 1 Z ] - L r 1 2 * & - r 2 - - 2 @key{RET} 40 Z ( @key{RET} k b @key{TAB} @key{RET} r 1 @key{TAB} ^ * / - @key{TAB} @key{RET} M-@key{TAB} - @key{RET} M-@key{TAB} a = Z / - 2 Z ) - Z ' -C-x ) -@end group -@end example - -@node Programming Answer 10, Programming Answer 11, Programming Answer 9, Answers to Exercises -@subsection Programming Tutorial Exercise 10 - -@noindent -Taking the derivative of a term of the form @expr{x^n} will produce -a term like -@texline @math{n x^{n-1}}. -@infoline @expr{n x^(n-1)}. -Taking the derivative of a constant -produces zero. From this it is easy to see that the @expr{n}th -derivative of a polynomial, evaluated at @expr{x = 0}, will equal the -coefficient on the @expr{x^n} term times @expr{n!}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @w{@kbd{C-x * m}} to load it from there. While you are -entering a @kbd{Z ` Z '} body in a macro, Calc simply collects -keystrokes without executing them. In the following diagrams we'll -pretend Calc actually executed the keystrokes as you typed them, -just for purposes of illustration.) - -@smallexample -@group -2: 5 x^4 + (x + 1)^2 3: 5 x^4 + (x + 1)^2 -1: 6 2: 0 - . 1: 6 - . - - ' 5 x^4 + (x+1)^2 @key{RET} 6 C-x ( Z ` [ ] t 1 0 @key{TAB} -@end group -@end smallexample - -@noindent -Variable 1 will accumulate the vector of coefficients. - -@smallexample -@group -2: 0 3: 0 2: 5 x^4 + ... -1: 5 x^4 + ... 2: 5 x^4 + ... 1: 1 - . 1: 1 . - . - - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 -@end group -@end smallexample - -@noindent -Note that @kbd{s | 1} appends the top-of-stack value to the vector -in a variable; it is completely analogous to @kbd{s + 1}. We could -have written instead, @kbd{r 1 @key{TAB} | t 1}. - -@smallexample -@group -1: 20 x^3 + 2 x + 2 1: 0 1: [1, 2, 1, 0, 5, 0, 0] - . . . - - a d x @key{RET} 1 Z ) @key{DEL} r 1 Z ' C-x ) -@end group -@end smallexample - -To convert back, a simple method is just to map the coefficients -against a table of powers of @expr{x}. - -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: [1, 2, 1, 0, 5, 0, 0] -1: 6 1: [0, 1, 2, 3, 4, 5, 6] - . . - - 6 @key{RET} 1 + 0 @key{RET} 1 C-u v x - -@end group -@end smallexample -@noindent -@smallexample -@group -2: [1, 2, 1, 0, 5, 0, 0] 2: 1 + 2 x + x^2 + 5 x^4 -1: [1, x, x^2, x^3, ... ] . - . - - ' x @key{RET} @key{TAB} V M ^ * -@end group -@end smallexample - -Once again, here are the whole polynomial to/from vector programs: - -@example -@group -C-x ( Z ` [ ] t 1 0 @key{TAB} - Z ( @key{TAB} @key{RET} 0 s l x @key{RET} M-@key{TAB} ! / s | 1 - a d x @key{RET} - 1 Z ) r 1 - Z ' -C-x ) - -C-x ( 1 + 0 @key{RET} 1 C-u v x ' x @key{RET} @key{TAB} V M ^ * C-x ) -@end group -@end example - -@node Programming Answer 11, Programming Answer 12, Programming Answer 10, Answers to Exercises -@subsection Programming Tutorial Exercise 11 - -@noindent -First we define a dummy program to go on the @kbd{z s} key. The true -@w{@kbd{z s}} key is supposed to take two numbers from the stack and -return one number, so @key{DEL} as a dummy definition will make -sure the stack comes out right. - -@smallexample -@group -2: 4 1: 4 2: 4 -1: 2 . 1: 2 - . . - - 4 @key{RET} 2 C-x ( @key{DEL} C-x ) Z K s @key{RET} 2 -@end group -@end smallexample - -The last step replaces the 2 that was eaten during the creation -of the dummy @kbd{z s} command. Now we move on to the real -definition. The recurrence needs to be rewritten slightly, -to the form @expr{s(n,m) = s(n-1,m-1) - (n-1) s(n-1,m)}. - -(Because this definition is long, it will be repeated in concise form -below. You can use @kbd{C-x * m} to load it from there.) - -@smallexample -@group -2: 4 4: 4 3: 4 2: 4 -1: 2 3: 2 2: 2 1: 2 - . 2: 4 1: 0 . - 1: 2 . - . - - C-x ( M-2 @key{RET} a = Z [ @key{DEL} @key{DEL} 1 Z : - -@end group -@end smallexample -@noindent -@smallexample -@group -4: 4 2: 4 2: 3 4: 3 4: 3 3: 3 -3: 2 1: 2 1: 2 3: 2 3: 2 2: 2 -2: 2 . . 2: 3 2: 3 1: 3 -1: 0 1: 2 1: 1 . - . . . - - @key{RET} 0 a = Z [ @key{DEL} @key{DEL} 0 Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s -@end group -@end smallexample - -@noindent -(Note that the value 3 that our dummy @kbd{z s} produces is not correct; -it is merely a placeholder that will do just as well for now.) - -@smallexample -@group -3: 3 4: 3 3: 3 2: 3 1: -6 -2: 3 3: 3 2: 3 1: 9 . -1: 2 2: 3 1: 3 . - . 1: 2 . - . - - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - -@end group -@end smallexample -@noindent -@smallexample -@group -1: -6 2: 4 1: 11 2: 11 - . 1: 2 . 1: 11 - . . - - Z ] Z ] C-x ) Z K s @key{RET} @key{DEL} 4 @key{RET} 2 z s M-@key{RET} k s -@end group -@end smallexample - -Even though the result that we got during the definition was highly -bogus, once the definition is complete the @kbd{z s} command gets -the right answers. - -Here's the full program once again: - -@example -@group -C-x ( M-2 @key{RET} a = - Z [ @key{DEL} @key{DEL} 1 - Z : @key{RET} 0 a = - Z [ @key{DEL} @key{DEL} 0 - Z : @key{TAB} 1 - @key{TAB} M-2 @key{RET} 1 - z s - M-@key{TAB} M-@key{TAB} @key{TAB} @key{RET} M-@key{TAB} z s * - - Z ] - Z ] -C-x ) -@end group -@end example - -You can read this definition using @kbd{C-x * m} (@code{read-kbd-macro}) -followed by @kbd{Z K s}, without having to make a dummy definition -first, because @code{read-kbd-macro} doesn't need to execute the -definition as it reads it in. For this reason, @code{C-x * m} is often -the easiest way to create recursive programs in Calc. - -@node Programming Answer 12, , Programming Answer 11, Answers to Exercises -@subsection Programming Tutorial Exercise 12 - -@noindent -This turns out to be a much easier way to solve the problem. Let's -denote Stirling numbers as calls of the function @samp{s}. - -First, we store the rewrite rules corresponding to the definition of -Stirling numbers in a convenient variable: - -@smallexample -s e StirlingRules @key{RET} -[ s(n,n) := 1 :: n >= 0, - s(n,0) := 0 :: n > 0, - s(n,m) := s(n-1,m-1) - (n-1) s(n-1,m) :: n >= m :: m >= 1 ] -C-c C-c -@end smallexample - -Now, it's just a matter of applying the rules: - -@smallexample -@group -2: 4 1: s(4, 2) 1: 11 -1: 2 . . - . - - 4 @key{RET} 2 C-x ( ' s($$,$) @key{RET} a r StirlingRules @key{RET} C-x ) -@end group -@end smallexample - -As in the case of the @code{fib} rules, it would be useful to put these -rules in @code{EvalRules} and to add a @samp{:: remember} condition to -the last rule. - -@c This ends the table-of-contents kludge from above: -@tex -\global\let\chapternofonts=\oldchapternofonts -@end tex - -@c [reference] - -@node Introduction, Data Types, Tutorial, Top -@chapter Introduction - -@noindent -This chapter is the beginning of the Calc reference manual. -It covers basic concepts such as the stack, algebraic and -numeric entry, undo, numeric prefix arguments, etc. - -@c [when-split] -@c (Chapter 2, the Tutorial, has been printed in a separate volume.) - -@menu -* Basic Commands:: -* Help Commands:: -* Stack Basics:: -* Numeric Entry:: -* Algebraic Entry:: -* Quick Calculator:: -* Prefix Arguments:: -* Undo:: -* Error Messages:: -* Multiple Calculators:: -* Troubleshooting Commands:: -@end menu - -@node Basic Commands, Help Commands, Introduction, Introduction -@section Basic Commands - -@noindent -@pindex calc -@pindex calc-mode -@cindex Starting the Calculator -@cindex Running the Calculator -To start the Calculator in its standard interface, type @kbd{M-x calc}. -By default this creates a pair of small windows, @samp{*Calculator*} -and @samp{*Calc Trail*}. The former displays the contents of the -Calculator stack and is manipulated exclusively through Calc commands. -It is possible (though not usually necessary) to create several Calc -mode buffers each of which has an independent stack, undo list, and -mode settings. There is exactly one Calc Trail buffer; it records a -list of the results of all calculations that have been done. The -Calc Trail buffer uses a variant of Calc mode, so Calculator commands -still work when the trail buffer's window is selected. It is possible -to turn the trail window off, but the @samp{*Calc Trail*} buffer itself -still exists and is updated silently. @xref{Trail Commands}. - -@kindex C-x * c -@kindex C-x * * -@ignore -@mindex @null -@end ignore -In most installations, the @kbd{C-x * c} key sequence is a more -convenient way to start the Calculator. Also, @kbd{C-x * *} -is a synonym for @kbd{C-x * c} unless you last used Calc -in its Keypad mode. - -@kindex x -@kindex M-x -@pindex calc-execute-extended-command -Most Calc commands use one or two keystrokes. Lower- and upper-case -letters are distinct. Commands may also be entered in full @kbd{M-x} form; -for some commands this is the only form. As a convenience, the @kbd{x} -key (@code{calc-execute-extended-command}) -is like @kbd{M-x} except that it enters the initial string @samp{calc-} -for you. For example, the following key sequences are equivalent: -@kbd{S}, @kbd{M-x calc-sin @key{RET}}, @kbd{x sin @key{RET}}. - -Although Calc is designed to be used from the keyboard, some of -Calc's more common commands are available from a menu. In the menu, the -arguments to the functions are given by referring to their stack level -numbers. - -@cindex Extensions module -@cindex @file{calc-ext} module -The Calculator exists in many parts. When you type @kbd{C-x * c}, the -Emacs ``auto-load'' mechanism will bring in only the first part, which -contains the basic arithmetic functions. The other parts will be -auto-loaded the first time you use the more advanced commands like trig -functions or matrix operations. This is done to improve the response time -of the Calculator in the common case when all you need to do is a -little arithmetic. If for some reason the Calculator fails to load an -extension module automatically, you can force it to load all the -extensions by using the @kbd{C-x * L} (@code{calc-load-everything}) -command. @xref{Mode Settings}. - -If you type @kbd{M-x calc} or @kbd{C-x * c} with any numeric prefix argument, -the Calculator is loaded if necessary, but it is not actually started. -If the argument is positive, the @file{calc-ext} extensions are also -loaded if necessary. User-written Lisp code that wishes to make use -of Calc's arithmetic routines can use @samp{(calc 0)} or @samp{(calc 1)} -to auto-load the Calculator. - -@kindex C-x * b -@pindex full-calc -If you type @kbd{C-x * b}, then next time you use @kbd{C-x * c} you -will get a Calculator that uses the full height of the Emacs screen. -When full-screen mode is on, @kbd{C-x * c} runs the @code{full-calc} -command instead of @code{calc}. From the Unix shell you can type -@samp{emacs -f full-calc} to start a new Emacs specifically for use -as a calculator. When Calc is started from the Emacs command line -like this, Calc's normal ``quit'' commands actually quit Emacs itself. - -@kindex C-x * o -@pindex calc-other-window -The @kbd{C-x * o} command is like @kbd{C-x * c} except that the Calc -window is not actually selected. If you are already in the Calc -window, @kbd{C-x * o} switches you out of it. (The regular Emacs -@kbd{C-x o} command would also work for this, but it has a -tendency to drop you into the Calc Trail window instead, which -@kbd{C-x * o} takes care not to do.) - -@ignore -@mindex C-x * q -@end ignore -For one quick calculation, you can type @kbd{C-x * q} (@code{quick-calc}) -which prompts you for a formula (like @samp{2+3/4}). The result is -displayed at the bottom of the Emacs screen without ever creating -any special Calculator windows. @xref{Quick Calculator}. - -@ignore -@mindex C-x * k -@end ignore -Finally, if you are using the X window system you may want to try -@kbd{C-x * k} (@code{calc-keypad}) which runs Calc with a -``calculator keypad'' picture as well as a stack display. Click on -the keys with the mouse to operate the calculator. @xref{Keypad Mode}. - -@kindex q -@pindex calc-quit -@cindex Quitting the Calculator -@cindex Exiting the Calculator -The @kbd{q} key (@code{calc-quit}) exits Calc mode and closes the -Calculator's window(s). It does not delete the Calculator buffers. -If you type @kbd{M-x calc} again, the Calculator will reappear with the -contents of the stack intact. Typing @kbd{C-x * c} or @kbd{C-x * *} -again from inside the Calculator buffer is equivalent to executing -@code{calc-quit}; you can think of @kbd{C-x * *} as toggling the -Calculator on and off. - -@kindex C-x * x -The @kbd{C-x * x} command also turns the Calculator off, no matter which -user interface (standard, Keypad, or Embedded) is currently active. -It also cancels @code{calc-edit} mode if used from there. - -@kindex d @key{SPC} -@pindex calc-refresh -@cindex Refreshing a garbled display -@cindex Garbled displays, refreshing -The @kbd{d @key{SPC}} key sequence (@code{calc-refresh}) redraws the contents -of the Calculator buffer from memory. Use this if the contents of the -buffer have been damaged somehow. - -@ignore -@mindex o -@end ignore -The @kbd{o} key (@code{calc-realign}) moves the cursor back to its -``home'' position at the bottom of the Calculator buffer. - -@kindex < -@kindex > -@pindex calc-scroll-left -@pindex calc-scroll-right -@cindex Horizontal scrolling -@cindex Scrolling -@cindex Wide text, scrolling -The @kbd{<} and @kbd{>} keys are bound to @code{calc-scroll-left} and -@code{calc-scroll-right}. These are just like the normal horizontal -scrolling commands except that they scroll one half-screen at a time by -default. (Calc formats its output to fit within the bounds of the -window whenever it can.) - -@kindex @{ -@kindex @} -@pindex calc-scroll-down -@pindex calc-scroll-up -@cindex Vertical scrolling -The @kbd{@{} and @kbd{@}} keys are bound to @code{calc-scroll-down} -and @code{calc-scroll-up}. They scroll up or down by one-half the -height of the Calc window. - -@kindex C-x * 0 -@pindex calc-reset -The @kbd{C-x * 0} command (@code{calc-reset}; that's @kbd{C-x *} followed -by a zero) resets the Calculator to its initial state. This clears -the stack, resets all the modes to their initial values (the values -that were saved with @kbd{m m} (@code{calc-save-modes})), clears the -caches (@pxref{Caches}), and so on. (It does @emph{not} erase the -values of any variables.) With an argument of 0, Calc will be reset to -its default state; namely, the modes will be given their default values. -With a positive prefix argument, @kbd{C-x * 0} preserves the contents of -the stack but resets everything else to its initial state; with a -negative prefix argument, @kbd{C-x * 0} preserves the contents of the -stack but resets everything else to its default state. - -@node Help Commands, Stack Basics, Basic Commands, Introduction -@section Help Commands - -@noindent -@cindex Help commands -@kindex ? -@pindex calc-help -The @kbd{?} key (@code{calc-help}) displays a series of brief help messages. -Some keys (such as @kbd{b} and @kbd{d}) are prefix keys, like Emacs' -@key{ESC} and @kbd{C-x} prefixes. You can type -@kbd{?} after a prefix to see a list of commands beginning with that -prefix. (If the message includes @samp{[MORE]}, press @kbd{?} again -to see additional commands for that prefix.) - -@kindex h h -@pindex calc-full-help -The @kbd{h h} (@code{calc-full-help}) command displays all the @kbd{?} -responses at once. When printed, this makes a nice, compact (three pages) -summary of Calc keystrokes. - -In general, the @kbd{h} key prefix introduces various commands that -provide help within Calc. Many of the @kbd{h} key functions are -Calc-specific analogues to the @kbd{C-h} functions for Emacs help. - -@kindex h i -@kindex C-x * i -@kindex i -@pindex calc-info -The @kbd{h i} (@code{calc-info}) command runs the Emacs Info system -to read this manual on-line. This is basically the same as typing -@kbd{C-h i} (the regular way to run the Info system), then, if Info -is not already in the Calc manual, selecting the beginning of the -manual. The @kbd{C-x * i} command is another way to read the Calc -manual; it is different from @kbd{h i} in that it works any time, -not just inside Calc. The plain @kbd{i} key is also equivalent to -@kbd{h i}, though this key is obsolete and may be replaced with a -different command in a future version of Calc. - -@kindex h t -@kindex C-x * t -@pindex calc-tutorial -The @kbd{h t} (@code{calc-tutorial}) command runs the Info system on -the Tutorial section of the Calc manual. It is like @kbd{h i}, -except that it selects the starting node of the tutorial rather -than the beginning of the whole manual. (It actually selects the -node ``Interactive Tutorial'' which tells a few things about -using the Info system before going on to the actual tutorial.) -The @kbd{C-x * t} key is equivalent to @kbd{h t} (but it works at -all times). - -@kindex h s -@kindex C-x * s -@pindex calc-info-summary -The @kbd{h s} (@code{calc-info-summary}) command runs the Info system -on the Summary node of the Calc manual. @xref{Summary}. The @kbd{C-x * s} -key is equivalent to @kbd{h s}. - -@kindex h k -@pindex calc-describe-key -The @kbd{h k} (@code{calc-describe-key}) command looks up a key -sequence in the Calc manual. For example, @kbd{h k H a S} looks -up the documentation on the @kbd{H a S} (@code{calc-solve-for}) -command. This works by looking up the textual description of -the key(s) in the Key Index of the manual, then jumping to the -node indicated by the index. - -Most Calc commands do not have traditional Emacs documentation -strings, since the @kbd{h k} command is both more convenient and -more instructive. This means the regular Emacs @kbd{C-h k} -(@code{describe-key}) command will not be useful for Calc keystrokes. - -@kindex h c -@pindex calc-describe-key-briefly -The @kbd{h c} (@code{calc-describe-key-briefly}) command reads a -key sequence and displays a brief one-line description of it at -the bottom of the screen. It looks for the key sequence in the -Summary node of the Calc manual; if it doesn't find the sequence -there, it acts just like its regular Emacs counterpart @kbd{C-h c} -(@code{describe-key-briefly}). For example, @kbd{h c H a S} -gives the description: - -@smallexample -H a S runs calc-solve-for: a `H a S' v => fsolve(a,v) (?=notes) -@end smallexample - -@noindent -which means the command @kbd{H a S} or @kbd{H M-x calc-solve-for} -takes a value @expr{a} from the stack, prompts for a value @expr{v}, -then applies the algebraic function @code{fsolve} to these values. -The @samp{?=notes} message means you can now type @kbd{?} to see -additional notes from the summary that apply to this command. - -@kindex h f -@pindex calc-describe-function -The @kbd{h f} (@code{calc-describe-function}) command looks up an -algebraic function or a command name in the Calc manual. Enter an -algebraic function name to look up that function in the Function -Index or enter a command name beginning with @samp{calc-} to look it -up in the Command Index. This command will also look up operator -symbols that can appear in algebraic formulas, like @samp{%} and -@samp{=>}. - -@kindex h v -@pindex calc-describe-variable -The @kbd{h v} (@code{calc-describe-variable}) command looks up a -variable in the Calc manual. Enter a variable name like @code{pi} or -@code{PlotRejects}. - -@kindex h b -@pindex describe-bindings -The @kbd{h b} (@code{calc-describe-bindings}) command is just like -@kbd{C-h b}, except that only local (Calc-related) key bindings are -listed. - -@kindex h n -The @kbd{h n} or @kbd{h C-n} (@code{calc-view-news}) command displays -the ``news'' or change history of Calc. This is kept in the file -@file{README}, which Calc looks for in the same directory as the Calc -source files. - -@kindex h C-c -@kindex h C-d -@kindex h C-w -The @kbd{h C-c}, @kbd{h C-d}, and @kbd{h C-w} keys display copying, -distribution, and warranty information about Calc. These work by -pulling up the appropriate parts of the ``Copying'' or ``Reporting -Bugs'' sections of the manual. - -@node Stack Basics, Numeric Entry, Help Commands, Introduction -@section Stack Basics - -@noindent -@cindex Stack basics -@c [fix-tut RPN Calculations and the Stack] -Calc uses RPN notation. If you are not familiar with RPN, @pxref{RPN -Tutorial}. - -To add the numbers 1 and 2 in Calc you would type the keys: -@kbd{1 @key{RET} 2 +}. -(@key{RET} corresponds to the @key{ENTER} key on most calculators.) -The first three keystrokes ``push'' the numbers 1 and 2 onto the stack. The -@kbd{+} key always ``pops'' the top two numbers from the stack, adds them, -and pushes the result (3) back onto the stack. This number is ready for -further calculations: @kbd{5 -} pushes 5 onto the stack, then pops the -3 and 5, subtracts them, and pushes the result (@mathit{-2}). - -Note that the ``top'' of the stack actually appears at the @emph{bottom} -of the buffer. A line containing a single @samp{.} character signifies -the end of the buffer; Calculator commands operate on the number(s) -directly above this line. The @kbd{d t} (@code{calc-truncate-stack}) -command allows you to move the @samp{.} marker up and down in the stack; -@pxref{Truncating the Stack}. - -@kindex d l -@pindex calc-line-numbering -Stack elements are numbered consecutively, with number 1 being the top of -the stack. These line numbers are ordinarily displayed on the lefthand side -of the window. The @kbd{d l} (@code{calc-line-numbering}) command controls -whether these numbers appear. (Line numbers may be turned off since they -slow the Calculator down a bit and also clutter the display.) - -@kindex o -@pindex calc-realign -The unshifted letter @kbd{o} (@code{calc-realign}) command repositions -the cursor to its top-of-stack ``home'' position. It also undoes any -horizontal scrolling in the window. If you give it a numeric prefix -argument, it instead moves the cursor to the specified stack element. - -The @key{RET} (or equivalent @key{SPC}) key is only required to separate -two consecutive numbers. -(After all, if you typed @kbd{1 2} by themselves the Calculator -would enter the number 12.) If you press @key{RET} or @key{SPC} @emph{not} -right after typing a number, the key duplicates the number on the top of -the stack. @kbd{@key{RET} *} is thus a handy way to square a number. - -The @key{DEL} key pops and throws away the top number on the stack. -The @key{TAB} key swaps the top two objects on the stack. -@xref{Stack and Trail}, for descriptions of these and other stack-related -commands. - -@node Numeric Entry, Algebraic Entry, Stack Basics, Introduction -@section Numeric Entry - -@noindent -@kindex 0-9 -@kindex . -@kindex e -@cindex Numeric entry -@cindex Entering numbers -Pressing a digit or other numeric key begins numeric entry using the -minibuffer. The number is pushed on the stack when you press the @key{RET} -or @key{SPC} keys. If you press any other non-numeric key, the number is -pushed onto the stack and the appropriate operation is performed. If -you press a numeric key which is not valid, the key is ignored. - -@cindex Minus signs -@cindex Negative numbers, entering -@kindex _ -There are three different concepts corresponding to the word ``minus,'' -typified by @expr{a-b} (subtraction), @expr{-x} -(change-sign), and @expr{-5} (negative number). Calc uses three -different keys for these operations, respectively: -@kbd{-}, @kbd{n}, and @kbd{_} (the underscore). The @kbd{-} key subtracts -the two numbers on the top of the stack. The @kbd{n} key changes the sign -of the number on the top of the stack or the number currently being entered. -The @kbd{_} key begins entry of a negative number or changes the sign of -the number currently being entered. The following sequences all enter the -number @mathit{-5} onto the stack: @kbd{0 @key{RET} 5 -}, @kbd{5 n @key{RET}}, -@kbd{5 @key{RET} n}, @kbd{_ 5 @key{RET}}, @kbd{5 _ @key{RET}}. - -Some other keys are active during numeric entry, such as @kbd{#} for -non-decimal numbers, @kbd{:} for fractions, and @kbd{@@} for HMS forms. -These notations are described later in this manual with the corresponding -data types. @xref{Data Types}. - -During numeric entry, the only editing key available is @key{DEL}. - -@node Algebraic Entry, Quick Calculator, Numeric Entry, Introduction -@section Algebraic Entry - -@noindent -@kindex ' -@pindex calc-algebraic-entry -@cindex Algebraic notation -@cindex Formulas, entering -The @kbd{'} (@code{calc-algebraic-entry}) command can be used to enter -calculations in algebraic form. This is accomplished by typing the -apostrophe key, ', followed by the expression in standard format: - -@example -' 2+3*4 @key{RET}. -@end example - -@noindent -This will compute -@texline @math{2+(3\times4) = 14} -@infoline @expr{2+(3*4) = 14} -and push it on the stack. If you wish you can -ignore the RPN aspect of Calc altogether and simply enter algebraic -expressions in this way. You may want to use @key{DEL} every so often to -clear previous results off the stack. - -You can press the apostrophe key during normal numeric entry to switch -the half-entered number into Algebraic entry mode. One reason to do -this would be to fix a typo, as the full Emacs cursor motion and editing -keys are available during algebraic entry but not during numeric entry. - -In the same vein, during either numeric or algebraic entry you can -press @kbd{`} (backquote) to switch to @code{calc-edit} mode, where -you complete your half-finished entry in a separate buffer. -@xref{Editing Stack Entries}. - -@kindex m a -@pindex calc-algebraic-mode -@cindex Algebraic Mode -If you prefer algebraic entry, you can use the command @kbd{m a} -(@code{calc-algebraic-mode}) to set Algebraic mode. In this mode, -digits and other keys that would normally start numeric entry instead -start full algebraic entry; as long as your formula begins with a digit -you can omit the apostrophe. Open parentheses and square brackets also -begin algebraic entry. You can still do RPN calculations in this mode, -but you will have to press @key{RET} to terminate every number: -@kbd{2 @key{RET} 3 @key{RET} * 4 @key{RET} +} would accomplish the same -thing as @kbd{2*3+4 @key{RET}}. - -@cindex Incomplete Algebraic Mode -If you give a numeric prefix argument like @kbd{C-u} to the @kbd{m a} -command, it enables Incomplete Algebraic mode; this is like regular -Algebraic mode except that it applies to the @kbd{(} and @kbd{[} keys -only. Numeric keys still begin a numeric entry in this mode. - -@kindex m t -@pindex calc-total-algebraic-mode -@cindex Total Algebraic Mode -The @kbd{m t} (@code{calc-total-algebraic-mode}) gives you an even -stronger algebraic-entry mode, in which @emph{all} regular letter and -punctuation keys begin algebraic entry. Use this if you prefer typing -@w{@kbd{sqrt( )}} instead of @kbd{Q}, @w{@kbd{factor( )}} instead of -@kbd{a f}, and so on. To type regular Calc commands when you are in -Total Algebraic mode, hold down the @key{META} key. Thus @kbd{M-q} -is the command to quit Calc, @kbd{M-p} sets the precision, and -@kbd{M-m t} (or @kbd{M-m M-t}, if you prefer) turns Total Algebraic -mode back off again. Meta keys also terminate algebraic entry, so -that @kbd{2+3 M-S} is equivalent to @kbd{2+3 @key{RET} M-S}. The symbol -@samp{Alg*} will appear in the mode line whenever you are in this mode. - -Pressing @kbd{'} (the apostrophe) a second time re-enters the previous -algebraic formula. You can then use the normal Emacs editing keys to -modify this formula to your liking before pressing @key{RET}. - -@kindex $ -@cindex Formulas, referring to stack -Within a formula entered from the keyboard, the symbol @kbd{$} -represents the number on the top of the stack. If an entered formula -contains any @kbd{$} characters, the Calculator replaces the top of -stack with that formula rather than simply pushing the formula onto the -stack. Thus, @kbd{' 1+2 @key{RET}} pushes 3 on the stack, and @kbd{$*2 -@key{RET}} replaces it with 6. Note that the @kbd{$} key always -initiates algebraic entry; the @kbd{'} is unnecessary if @kbd{$} is the -first character in the new formula. - -Higher stack elements can be accessed from an entered formula with the -symbols @kbd{$$}, @kbd{$$$}, and so on. The number of stack elements -removed (to be replaced by the entered values) equals the number of dollar -signs in the longest such symbol in the formula. For example, @samp{$$+$$$} -adds the second and third stack elements, replacing the top three elements -with the answer. (All information about the top stack element is thus lost -since no single @samp{$} appears in this formula.) - -A slightly different way to refer to stack elements is with a dollar -sign followed by a number: @samp{$1}, @samp{$2}, and so on are much -like @samp{$}, @samp{$$}, etc., except that stack entries referred -to numerically are not replaced by the algebraic entry. That is, while -@samp{$+1} replaces 5 on the stack with 6, @samp{$1+1} leaves the 5 -on the stack and pushes an additional 6. - -If a sequence of formulas are entered separated by commas, each formula -is pushed onto the stack in turn. For example, @samp{1,2,3} pushes -those three numbers onto the stack (leaving the 3 at the top), and -@samp{$+1,$-1} replaces a 5 on the stack with 4 followed by 6. Also, -@samp{$,$$} exchanges the top two elements of the stack, just like the -@key{TAB} key. - -You can finish an algebraic entry with @kbd{M-=} or @kbd{M-@key{RET}} instead -of @key{RET}. This uses @kbd{=} to evaluate the variables in each -formula that goes onto the stack. (Thus @kbd{' pi @key{RET}} pushes -the variable @samp{pi}, but @kbd{' pi M-@key{RET}} pushes 3.1415.) - -If you finish your algebraic entry by pressing @key{LFD} (or @kbd{C-j}) -instead of @key{RET}, Calc disables the default simplifications -(as if by @kbd{m O}; @pxref{Simplification Modes}) while the entry -is being pushed on the stack. Thus @kbd{' 1+2 @key{RET}} pushes 3 -on the stack, but @kbd{' 1+2 @key{LFD}} pushes the formula @expr{1+2}; -you might then press @kbd{=} when it is time to evaluate this formula. - -@node Quick Calculator, Prefix Arguments, Algebraic Entry, Introduction -@section ``Quick Calculator'' Mode - -@noindent -@kindex C-x * q -@pindex quick-calc -@cindex Quick Calculator -There is another way to invoke the Calculator if all you need to do -is make one or two quick calculations. Type @kbd{C-x * q} (or -@kbd{M-x quick-calc}), then type any formula as an algebraic entry. -The Calculator will compute the result and display it in the echo -area, without ever actually putting up a Calc window. - -You can use the @kbd{$} character in a Quick Calculator formula to -refer to the previous Quick Calculator result. Older results are -not retained; the Quick Calculator has no effect on the full -Calculator's stack or trail. If you compute a result and then -forget what it was, just run @code{C-x * q} again and enter -@samp{$} as the formula. - -If this is the first time you have used the Calculator in this Emacs -session, the @kbd{C-x * q} command will create the @code{*Calculator*} -buffer and perform all the usual initializations; it simply will -refrain from putting that buffer up in a new window. The Quick -Calculator refers to the @code{*Calculator*} buffer for all mode -settings. Thus, for example, to set the precision that the Quick -Calculator uses, simply run the full Calculator momentarily and use -the regular @kbd{p} command. - -If you use @code{C-x * q} from inside the Calculator buffer, the -effect is the same as pressing the apostrophe key (algebraic entry). - -The result of a Quick calculation is placed in the Emacs ``kill ring'' -as well as being displayed. A subsequent @kbd{C-y} command will -yank the result into the editing buffer. You can also use this -to yank the result into the next @kbd{C-x * q} input line as a more -explicit alternative to @kbd{$} notation, or to yank the result -into the Calculator stack after typing @kbd{C-x * c}. - -If you finish your formula by typing @key{LFD} (or @kbd{C-j}) instead -of @key{RET}, the result is inserted immediately into the current -buffer rather than going into the kill ring. - -Quick Calculator results are actually evaluated as if by the @kbd{=} -key (which replaces variable names by their stored values, if any). -If the formula you enter is an assignment to a variable using the -@samp{:=} operator, say, @samp{foo := 2 + 3} or @samp{foo := foo + 1}, -then the result of the evaluation is stored in that Calc variable. -@xref{Store and Recall}. - -If the result is an integer and the current display radix is decimal, -the number will also be displayed in hex, octal and binary formats. If -the integer is in the range from 1 to 126, it will also be displayed as -an ASCII character. - -For example, the quoted character @samp{"x"} produces the vector -result @samp{[120]} (because 120 is the ASCII code of the lower-case -`x'; @pxref{Strings}). Since this is a vector, not an integer, it -is displayed only according to the current mode settings. But -running Quick Calc again and entering @samp{120} will produce the -result @samp{120 (16#78, 8#170, x)} which shows the number in its -decimal, hexadecimal, octal, and ASCII forms. - -Please note that the Quick Calculator is not any faster at loading -or computing the answer than the full Calculator; the name ``quick'' -merely refers to the fact that it's much less hassle to use for -small calculations. - -@node Prefix Arguments, Undo, Quick Calculator, Introduction -@section Numeric Prefix Arguments - -@noindent -Many Calculator commands use numeric prefix arguments. Some, such as -@kbd{d s} (@code{calc-sci-notation}), set a parameter to the value of -the prefix argument or use a default if you don't use a prefix. -Others (like @kbd{d f} (@code{calc-fix-notation})) require an argument -and prompt for a number if you don't give one as a prefix. - -As a rule, stack-manipulation commands accept a numeric prefix argument -which is interpreted as an index into the stack. A positive argument -operates on the top @var{n} stack entries; a negative argument operates -on the @var{n}th stack entry in isolation; and a zero argument operates -on the entire stack. - -Most commands that perform computations (such as the arithmetic and -scientific functions) accept a numeric prefix argument that allows the -operation to be applied across many stack elements. For unary operations -(that is, functions of one argument like absolute value or complex -conjugate), a positive prefix argument applies that function to the top -@var{n} stack entries simultaneously, and a negative argument applies it -to the @var{n}th stack entry only. For binary operations (functions of -two arguments like addition, GCD, and vector concatenation), a positive -prefix argument ``reduces'' the function across the top @var{n} -stack elements (for example, @kbd{C-u 5 +} sums the top 5 stack entries; -@pxref{Reducing and Mapping}), and a negative argument maps the next-to-top -@var{n} stack elements with the top stack element as a second argument -(for example, @kbd{7 c-u -5 +} adds 7 to the top 5 stack elements). -This feature is not available for operations which use the numeric prefix -argument for some other purpose. - -Numeric prefixes are specified the same way as always in Emacs: Press -a sequence of @key{META}-digits, or press @key{ESC} followed by digits, -or press @kbd{C-u} followed by digits. Some commands treat plain -@kbd{C-u} (without any actual digits) specially. - -@kindex ~ -@pindex calc-num-prefix -You can type @kbd{~} (@code{calc-num-prefix}) to pop an integer from the -top of the stack and enter it as the numeric prefix for the next command. -For example, @kbd{C-u 16 p} sets the precision to 16 digits; an alternate -(silly) way to do this would be @kbd{2 @key{RET} 4 ^ ~ p}, i.e., compute 2 -to the fourth power and set the precision to that value. - -Conversely, if you have typed a numeric prefix argument the @kbd{~} key -pushes it onto the stack in the form of an integer. - -@node Undo, Error Messages, Prefix Arguments, Introduction -@section Undoing Mistakes - -@noindent -@kindex U -@kindex C-_ -@pindex calc-undo -@cindex Mistakes, undoing -@cindex Undoing mistakes -@cindex Errors, undoing -The shift-@kbd{U} key (@code{calc-undo}) undoes the most recent operation. -If that operation added or dropped objects from the stack, those objects -are removed or restored. If it was a ``store'' operation, you are -queried whether or not to restore the variable to its original value. -The @kbd{U} key may be pressed any number of times to undo successively -farther back in time; with a numeric prefix argument it undoes a -specified number of operations. The undo history is cleared only by the -@kbd{q} (@code{calc-quit}) command. (Recall that @kbd{C-x * c} is -synonymous with @code{calc-quit} while inside the Calculator; this -also clears the undo history.) - -Currently the mode-setting commands (like @code{calc-precision}) are not -undoable. You can undo past a point where you changed a mode, but you -will need to reset the mode yourself. - -@kindex D -@pindex calc-redo -@cindex Redoing after an Undo -The shift-@kbd{D} key (@code{calc-redo}) redoes an operation that was -mistakenly undone. Pressing @kbd{U} with a negative prefix argument is -equivalent to executing @code{calc-redo}. You can redo any number of -times, up to the number of recent consecutive undo commands. Redo -information is cleared whenever you give any command that adds new undo -information, i.e., if you undo, then enter a number on the stack or make -any other change, then it will be too late to redo. - -@kindex M-@key{RET} -@pindex calc-last-args -@cindex Last-arguments feature -@cindex Arguments, restoring -The @kbd{M-@key{RET}} key (@code{calc-last-args}) is like undo in that -it restores the arguments of the most recent command onto the stack; -however, it does not remove the result of that command. Given a numeric -prefix argument, this command applies to the @expr{n}th most recent -command which removed items from the stack; it pushes those items back -onto the stack. - -The @kbd{K} (@code{calc-keep-args}) command provides a related function -to @kbd{M-@key{RET}}. @xref{Stack and Trail}. - -It is also possible to recall previous results or inputs using the trail. -@xref{Trail Commands}. - -The standard Emacs @kbd{C-_} undo key is recognized as a synonym for @kbd{U}. - -@node Error Messages, Multiple Calculators, Undo, Introduction -@section Error Messages - -@noindent -@kindex w -@pindex calc-why -@cindex Errors, messages -@cindex Why did an error occur? -Many situations that would produce an error message in other calculators -simply create unsimplified formulas in the Emacs Calculator. For example, -@kbd{1 @key{RET} 0 /} pushes the formula @expr{1 / 0}; @w{@kbd{0 L}} pushes -the formula @samp{ln(0)}. Floating-point overflow and underflow are also -reasons for this to happen. - -When a function call must be left in symbolic form, Calc usually -produces a message explaining why. Messages that are probably -surprising or indicative of user errors are displayed automatically. -Other messages are simply kept in Calc's memory and are displayed only -if you type @kbd{w} (@code{calc-why}). You can also press @kbd{w} if -the same computation results in several messages. (The first message -will end with @samp{[w=more]} in this case.) - -@kindex d w -@pindex calc-auto-why -The @kbd{d w} (@code{calc-auto-why}) command controls when error messages -are displayed automatically. (Calc effectively presses @kbd{w} for you -after your computation finishes.) By default, this occurs only for -``important'' messages. The other possible modes are to report -@emph{all} messages automatically, or to report none automatically (so -that you must always press @kbd{w} yourself to see the messages). - -@node Multiple Calculators, Troubleshooting Commands, Error Messages, Introduction -@section Multiple Calculators - -@noindent -@pindex another-calc -It is possible to have any number of Calc mode buffers at once. -Usually this is done by executing @kbd{M-x another-calc}, which -is similar to @kbd{C-x * c} except that if a @samp{*Calculator*} -buffer already exists, a new, independent one with a name of the -form @samp{*Calculator*<@var{n}>} is created. You can also use the -command @code{calc-mode} to put any buffer into Calculator mode, but -this would ordinarily never be done. - -The @kbd{q} (@code{calc-quit}) command does not destroy a Calculator buffer; -it only closes its window. Use @kbd{M-x kill-buffer} to destroy a -Calculator buffer. - -Each Calculator buffer keeps its own stack, undo list, and mode settings -such as precision, angular mode, and display formats. In Emacs terms, -variables such as @code{calc-stack} are buffer-local variables. The -global default values of these variables are used only when a new -Calculator buffer is created. The @code{calc-quit} command saves -the stack and mode settings of the buffer being quit as the new defaults. - -There is only one trail buffer, @samp{*Calc Trail*}, used by all -Calculator buffers. - -@node Troubleshooting Commands, , Multiple Calculators, Introduction -@section Troubleshooting Commands - -@noindent -This section describes commands you can use in case a computation -incorrectly fails or gives the wrong answer. - -@xref{Reporting Bugs}, if you find a problem that appears to be due -to a bug or deficiency in Calc. - -@menu -* Autoloading Problems:: -* Recursion Depth:: -* Caches:: -* Debugging Calc:: -@end menu - -@node Autoloading Problems, Recursion Depth, Troubleshooting Commands, Troubleshooting Commands -@subsection Autoloading Problems - -@noindent -The Calc program is split into many component files; components are -loaded automatically as you use various commands that require them. -Occasionally Calc may lose track of when a certain component is -necessary; typically this means you will type a command and it won't -work because some function you've never heard of was undefined. - -@kindex C-x * L -@pindex calc-load-everything -If this happens, the easiest workaround is to type @kbd{C-x * L} -(@code{calc-load-everything}) to force all the parts of Calc to be -loaded right away. This will cause Emacs to take up a lot more -memory than it would otherwise, but it's guaranteed to fix the problem. - -@node Recursion Depth, Caches, Autoloading Problems, Troubleshooting Commands -@subsection Recursion Depth - -@noindent -@kindex M -@kindex I M -@pindex calc-more-recursion-depth -@pindex calc-less-recursion-depth -@cindex Recursion depth -@cindex ``Computation got stuck'' message -@cindex @code{max-lisp-eval-depth} -@cindex @code{max-specpdl-size} -Calc uses recursion in many of its calculations. Emacs Lisp keeps a -variable @code{max-lisp-eval-depth} which limits the amount of recursion -possible in an attempt to recover from program bugs. If a calculation -ever halts incorrectly with the message ``Computation got stuck or -ran too long,'' use the @kbd{M} command (@code{calc-more-recursion-depth}) -to increase this limit. (Of course, this will not help if the -calculation really did get stuck due to some problem inside Calc.) - -The limit is always increased (multiplied) by a factor of two. There -is also an @kbd{I M} (@code{calc-less-recursion-depth}) command which -decreases this limit by a factor of two, down to a minimum value of 200. -The default value is 1000. - -These commands also double or halve @code{max-specpdl-size}, another -internal Lisp recursion limit. The minimum value for this limit is 600. - -@node Caches, Debugging Calc, Recursion Depth, Troubleshooting Commands -@subsection Caches - -@noindent -@cindex Caches -@cindex Flushing caches -Calc saves certain values after they have been computed once. For -example, the @kbd{P} (@code{calc-pi}) command initially ``knows'' the -constant @cpi{} to about 20 decimal places; if the current precision -is greater than this, it will recompute @cpi{} using a series -approximation. This value will not need to be recomputed ever again -unless you raise the precision still further. Many operations such as -logarithms and sines make use of similarly cached values such as -@cpiover{4} and -@texline @math{\ln 2}. -@infoline @expr{ln(2)}. -The visible effect of caching is that -high-precision computations may seem to do extra work the first time. -Other things cached include powers of two (for the binary arithmetic -functions), matrix inverses and determinants, symbolic integrals, and -data points computed by the graphing commands. - -@pindex calc-flush-caches -If you suspect a Calculator cache has become corrupt, you can use the -@code{calc-flush-caches} command to reset all caches to the empty state. -(This should only be necessary in the event of bugs in the Calculator.) -The @kbd{C-x * 0} (with the zero key) command also resets caches along -with all other aspects of the Calculator's state. - -@node Debugging Calc, , Caches, Troubleshooting Commands -@subsection Debugging Calc - -@noindent -A few commands exist to help in the debugging of Calc commands. -@xref{Programming}, to see the various ways that you can write -your own Calc commands. - -@kindex Z T -@pindex calc-timing -The @kbd{Z T} (@code{calc-timing}) command turns on and off a mode -in which the timing of slow commands is reported in the Trail. -Any Calc command that takes two seconds or longer writes a line -to the Trail showing how many seconds it took. This value is -accurate only to within one second. - -All steps of executing a command are included; in particular, time -taken to format the result for display in the stack and trail is -counted. Some prompts also count time taken waiting for them to -be answered, while others do not; this depends on the exact -implementation of the command. For best results, if you are timing -a sequence that includes prompts or multiple commands, define a -keyboard macro to run the whole sequence at once. Calc's @kbd{X} -command (@pxref{Keyboard Macros}) will then report the time taken -to execute the whole macro. - -Another advantage of the @kbd{X} command is that while it is -executing, the stack and trail are not updated from step to step. -So if you expect the output of your test sequence to leave a result -that may take a long time to format and you don't wish to count -this formatting time, end your sequence with a @key{DEL} keystroke -to clear the result from the stack. When you run the sequence with -@kbd{X}, Calc will never bother to format the large result. - -Another thing @kbd{Z T} does is to increase the Emacs variable -@code{gc-cons-threshold} to a much higher value (two million; the -usual default in Calc is 250,000) for the duration of each command. -This generally prevents garbage collection during the timing of -the command, though it may cause your Emacs process to grow -abnormally large. (Garbage collection time is a major unpredictable -factor in the timing of Emacs operations.) - -Another command that is useful when debugging your own Lisp -extensions to Calc is @kbd{M-x calc-pass-errors}, which disables -the error handler that changes the ``@code{max-lisp-eval-depth} -exceeded'' message to the much more friendly ``Computation got -stuck or ran too long.'' This handler interferes with the Emacs -Lisp debugger's @code{debug-on-error} mode. Errors are reported -in the handler itself rather than at the true location of the -error. After you have executed @code{calc-pass-errors}, Lisp -errors will be reported correctly but the user-friendly message -will be lost. - -@node Data Types, Stack and Trail, Introduction, Top -@chapter Data Types - -@noindent -This chapter discusses the various types of objects that can be placed -on the Calculator stack, how they are displayed, and how they are -entered. (@xref{Data Type Formats}, for information on how these data -types are represented as underlying Lisp objects.) - -Integers, fractions, and floats are various ways of describing real -numbers. HMS forms also for many purposes act as real numbers. These -types can be combined to form complex numbers, modulo forms, error forms, -or interval forms. (But these last four types cannot be combined -arbitrarily:@: error forms may not contain modulo forms, for example.) -Finally, all these types of numbers may be combined into vectors, -matrices, or algebraic formulas. - -@menu -* Integers:: The most basic data type. -* Fractions:: This and above are called @dfn{rationals}. -* Floats:: This and above are called @dfn{reals}. -* Complex Numbers:: This and above are called @dfn{numbers}. -* Infinities:: -* Vectors and Matrices:: -* Strings:: -* HMS Forms:: -* Date Forms:: -* Modulo Forms:: -* Error Forms:: -* Interval Forms:: -* Incomplete Objects:: -* Variables:: -* Formulas:: -@end menu - -@node Integers, Fractions, Data Types, Data Types -@section Integers - -@noindent -@cindex Integers -The Calculator stores integers to arbitrary precision. Addition, -subtraction, and multiplication of integers always yields an exact -integer result. (If the result of a division or exponentiation of -integers is not an integer, it is expressed in fractional or -floating-point form according to the current Fraction mode. -@xref{Fraction Mode}.) - -A decimal integer is represented as an optional sign followed by a -sequence of digits. Grouping (@pxref{Grouping Digits}) can be used to -insert a comma at every third digit for display purposes, but you -must not type commas during the entry of numbers. - -@kindex # -A non-decimal integer is represented as an optional sign, a radix -between 2 and 36, a @samp{#} symbol, and one or more digits. For radix 11 -and above, the letters A through Z (upper- or lower-case) count as -digits and do not terminate numeric entry mode. @xref{Radix Modes}, for how -to set the default radix for display of integers. Numbers of any radix -may be entered at any time. If you press @kbd{#} at the beginning of a -number, the current display radix is used. - -@node Fractions, Floats, Integers, Data Types -@section Fractions - -@noindent -@cindex Fractions -A @dfn{fraction} is a ratio of two integers. Fractions are traditionally -written ``2/3'' but Calc uses the notation @samp{2:3}. (The @kbd{/} key -performs RPN division; the following two sequences push the number -@samp{2:3} on the stack: @kbd{2 :@: 3 @key{RET}}, or @kbd{2 @key{RET} 3 /} -assuming Fraction mode has been enabled.) -When the Calculator produces a fractional result it always reduces it to -simplest form, which may in fact be an integer. - -Fractions may also be entered in a three-part form, where @samp{2:3:4} -represents two-and-three-quarters. @xref{Fraction Formats}, for fraction -display formats. - -Non-decimal fractions are entered and displayed as -@samp{@var{radix}#@var{num}:@var{denom}} (or in the analogous three-part -form). The numerator and denominator always use the same radix. - -@node Floats, Complex Numbers, Fractions, Data Types -@section Floats - -@noindent -@cindex Floating-point numbers -A floating-point number or @dfn{float} is a number stored in scientific -notation. The number of significant digits in the fractional part is -governed by the current floating precision (@pxref{Precision}). The -range of acceptable values is from -@texline @math{10^{-3999999}} -@infoline @expr{10^-3999999} -(inclusive) to -@texline @math{10^{4000000}} -@infoline @expr{10^4000000} -(exclusive), plus the corresponding negative values and zero. - -Calculations that would exceed the allowable range of values (such -as @samp{exp(exp(20))}) are left in symbolic form by Calc. The -messages ``floating-point overflow'' or ``floating-point underflow'' -indicate that during the calculation a number would have been produced -that was too large or too close to zero, respectively, to be represented -by Calc. This does not necessarily mean the final result would have -overflowed, just that an overflow occurred while computing the result. -(In fact, it could report an underflow even though the final result -would have overflowed!) - -If a rational number and a float are mixed in a calculation, the result -will in general be expressed as a float. Commands that require an integer -value (such as @kbd{k g} [@code{gcd}]) will also accept integer-valued -floats, i.e., floating-point numbers with nothing after the decimal point. - -Floats are identified by the presence of a decimal point and/or an -exponent. In general a float consists of an optional sign, digits -including an optional decimal point, and an optional exponent consisting -of an @samp{e}, an optional sign, and up to seven exponent digits. -For example, @samp{23.5e-2} is 23.5 times ten to the minus-second power, -or 0.235. - -Floating-point numbers are normally displayed in decimal notation with -all significant figures shown. Exceedingly large or small numbers are -displayed in scientific notation. Various other display options are -available. @xref{Float Formats}. - -@cindex Accuracy of calculations -Floating-point numbers are stored in decimal, not binary. The result -of each operation is rounded to the nearest value representable in the -number of significant digits specified by the current precision, -rounding away from zero in the case of a tie. Thus (in the default -display mode) what you see is exactly what you get. Some operations such -as square roots and transcendental functions are performed with several -digits of extra precision and then rounded down, in an effort to make the -final result accurate to the full requested precision. However, -accuracy is not rigorously guaranteed. If you suspect the validity of a -result, try doing the same calculation in a higher precision. The -Calculator's arithmetic is not intended to be IEEE-conformant in any -way. - -While floats are always @emph{stored} in decimal, they can be entered -and displayed in any radix just like integers and fractions. Since a -float that is entered in a radix other that 10 will be converted to -decimal, the number that Calc stores may not be exactly the number that -was entered, it will be the closest decimal approximation given the -current precison. The notation @samp{@var{radix}#@var{ddd}.@var{ddd}} -is a floating-point number whose digits are in the specified radix. -Note that the @samp{.} is more aptly referred to as a ``radix point'' -than as a decimal point in this case. The number @samp{8#123.4567} is -defined as @samp{8#1234567 * 8^-4}. If the radix is 14 or less, you can -use @samp{e} notation to write a non-decimal number in scientific -notation. The exponent is written in decimal, and is considered to be a -power of the radix: @samp{8#1234567e-4}. If the radix is 15 or above, -the letter @samp{e} is a digit, so scientific notation must be written -out, e.g., @samp{16#123.4567*16^2}. The first two exercises of the -Modes Tutorial explore some of the properties of non-decimal floats. - -@node Complex Numbers, Infinities, Floats, Data Types -@section Complex Numbers - -@noindent -@cindex Complex numbers -There are two supported formats for complex numbers: rectangular and -polar. The default format is rectangular, displayed in the form -@samp{(@var{real},@var{imag})} where @var{real} is the real part and -@var{imag} is the imaginary part, each of which may be any real number. -Rectangular complex numbers can also be displayed in @samp{@var{a}+@var{b}i} -notation; @pxref{Complex Formats}. - -Polar complex numbers are displayed in the form -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}' -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}' -where @var{r} is the nonnegative magnitude and -@texline @math{\theta} -@infoline @var{theta} -is the argument or phase angle. The range of -@texline @math{\theta} -@infoline @var{theta} -depends on the current angular mode (@pxref{Angular Modes}); it is -generally between @mathit{-180} and @mathit{+180} degrees or the equivalent range -in radians. - -Complex numbers are entered in stages using incomplete objects. -@xref{Incomplete Objects}. - -Operations on rectangular complex numbers yield rectangular complex -results, and similarly for polar complex numbers. Where the two types -are mixed, or where new complex numbers arise (as for the square root of -a negative real), the current @dfn{Polar mode} is used to determine the -type. @xref{Polar Mode}. - -A complex result in which the imaginary part is zero (or the phase angle -is 0 or 180 degrees or @cpi{} radians) is automatically converted to a real -number. - -@node Infinities, Vectors and Matrices, Complex Numbers, Data Types -@section Infinities - -@noindent -@cindex Infinity -@cindex @code{inf} variable -@cindex @code{uinf} variable -@cindex @code{nan} variable -@vindex inf -@vindex uinf -@vindex nan -The word @code{inf} represents the mathematical concept of @dfn{infinity}. -Calc actually has three slightly different infinity-like values: -@code{inf}, @code{uinf}, and @code{nan}. These are just regular -variable names (@pxref{Variables}); you should avoid using these -names for your own variables because Calc gives them special -treatment. Infinities, like all variable names, are normally -entered using algebraic entry. - -Mathematically speaking, it is not rigorously correct to treat -``infinity'' as if it were a number, but mathematicians often do -so informally. When they say that @samp{1 / inf = 0}, what they -really mean is that @expr{1 / x}, as @expr{x} becomes larger and -larger, becomes arbitrarily close to zero. So you can imagine -that if @expr{x} got ``all the way to infinity,'' then @expr{1 / x} -would go all the way to zero. Similarly, when they say that -@samp{exp(inf) = inf}, they mean that -@texline @math{e^x} -@infoline @expr{exp(x)} -grows without bound as @expr{x} grows. The symbol @samp{-inf} likewise -stands for an infinitely negative real value; for example, we say that -@samp{exp(-inf) = 0}. You can have an infinity pointing in any -direction on the complex plane: @samp{sqrt(-inf) = i inf}. - -The same concept of limits can be used to define @expr{1 / 0}. We -really want the value that @expr{1 / x} approaches as @expr{x} -approaches zero. But if all we have is @expr{1 / 0}, we can't -tell which direction @expr{x} was coming from. If @expr{x} was -positive and decreasing toward zero, then we should say that -@samp{1 / 0 = inf}. But if @expr{x} was negative and increasing -toward zero, the answer is @samp{1 / 0 = -inf}. In fact, @expr{x} -could be an imaginary number, giving the answer @samp{i inf} or -@samp{-i inf}. Calc uses the special symbol @samp{uinf} to mean -@dfn{undirected infinity}, i.e., a value which is infinitely -large but with an unknown sign (or direction on the complex plane). - -Calc actually has three modes that say how infinities are handled. -Normally, infinities never arise from calculations that didn't -already have them. Thus, @expr{1 / 0} is treated simply as an -error and left unevaluated. The @kbd{m i} (@code{calc-infinite-mode}) -command (@pxref{Infinite Mode}) enables a mode in which -@expr{1 / 0} evaluates to @code{uinf} instead. There is also -an alternative type of infinite mode which says to treat zeros -as if they were positive, so that @samp{1 / 0 = inf}. While this -is less mathematically correct, it may be the answer you want in -some cases. - -Since all infinities are ``as large'' as all others, Calc simplifies, -e.g., @samp{5 inf} to @samp{inf}. Another example is -@samp{5 - inf = -inf}, where the @samp{-inf} is so large that -adding a finite number like five to it does not affect it. -Note that @samp{a - inf} also results in @samp{-inf}; Calc assumes -that variables like @code{a} always stand for finite quantities. -Just to show that infinities really are all the same size, -note that @samp{sqrt(inf) = inf^2 = exp(inf) = inf} in Calc's -notation. - -It's not so easy to define certain formulas like @samp{0 * inf} and -@samp{inf / inf}. Depending on where these zeros and infinities -came from, the answer could be literally anything. The latter -formula could be the limit of @expr{x / x} (giving a result of one), -or @expr{2 x / x} (giving two), or @expr{x^2 / x} (giving @code{inf}), -or @expr{x / x^2} (giving zero). Calc uses the symbol @code{nan} -to represent such an @dfn{indeterminate} value. (The name ``nan'' -comes from analogy with the ``NAN'' concept of IEEE standard -arithmetic; it stands for ``Not A Number.'' This is somewhat of a -misnomer, since @code{nan} @emph{does} stand for some number or -infinity, it's just that @emph{which} number it stands for -cannot be determined.) In Calc's notation, @samp{0 * inf = nan} -and @samp{inf / inf = nan}. A few other common indeterminate -expressions are @samp{inf - inf} and @samp{inf ^ 0}. Also, -@samp{0 / 0 = nan} if you have turned on Infinite mode -(as described above). - -Infinities are especially useful as parts of @dfn{intervals}. -@xref{Interval Forms}. - -@node Vectors and Matrices, Strings, Infinities, Data Types -@section Vectors and Matrices - -@noindent -@cindex Vectors -@cindex Plain vectors -@cindex Matrices -The @dfn{vector} data type is flexible and general. A vector is simply a -list of zero or more data objects. When these objects are numbers, the -whole is a vector in the mathematical sense. When these objects are -themselves vectors of equal (nonzero) length, the whole is a @dfn{matrix}. -A vector which is not a matrix is referred to here as a @dfn{plain vector}. - -A vector is displayed as a list of values separated by commas and enclosed -in square brackets: @samp{[1, 2, 3]}. Thus the following is a 2 row by -3 column matrix: @samp{[[1, 2, 3], [4, 5, 6]]}. Vectors, like complex -numbers, are entered as incomplete objects. @xref{Incomplete Objects}. -During algebraic entry, vectors are entered all at once in the usual -brackets-and-commas form. Matrices may be entered algebraically as nested -vectors, or using the shortcut notation @w{@samp{[1, 2, 3; 4, 5, 6]}}, -with rows separated by semicolons. The commas may usually be omitted -when entering vectors: @samp{[1 2 3]}. Curly braces may be used in -place of brackets: @samp{@{1, 2, 3@}}, but the commas are required in -this case. - -Traditional vector and matrix arithmetic is also supported; -@pxref{Basic Arithmetic} and @pxref{Matrix Functions}. -Many other operations are applied to vectors element-wise. For example, -the complex conjugate of a vector is a vector of the complex conjugates -of its elements. - -@ignore -@starindex -@end ignore -@tindex vec -Algebraic functions for building vectors include @samp{vec(a, b, c)} -to build @samp{[a, b, c]}, @samp{cvec(a, n, m)} to build an -@texline @math{n\times m} -@infoline @var{n}x@var{m} -matrix of @samp{a}s, and @samp{index(n)} to build a vector of integers -from 1 to @samp{n}. - -@node Strings, HMS Forms, Vectors and Matrices, Data Types -@section Strings - -@noindent -@kindex " -@cindex Strings -@cindex Character strings -Character strings are not a special data type in the Calculator. -Rather, a string is represented simply as a vector all of whose -elements are integers in the range 0 to 255 (ASCII codes). You can -enter a string at any time by pressing the @kbd{"} key. Quotation -marks and backslashes are written @samp{\"} and @samp{\\}, respectively, -inside strings. Other notations introduced by backslashes are: - -@example -@group -\a 7 \^@@ 0 -\b 8 \^a-z 1-26 -\e 27 \^[ 27 -\f 12 \^\\ 28 -\n 10 \^] 29 -\r 13 \^^ 30 -\t 9 \^_ 31 - \^? 127 -@end group -@end example - -@noindent -Finally, a backslash followed by three octal digits produces any -character from its ASCII code. - -@kindex d " -@pindex calc-display-strings -Strings are normally displayed in vector-of-integers form. The -@w{@kbd{d "}} (@code{calc-display-strings}) command toggles a mode in -which any vectors of small integers are displayed as quoted strings -instead. - -The backslash notations shown above are also used for displaying -strings. Characters 128 and above are not translated by Calc; unless -you have an Emacs modified for 8-bit fonts, these will show up in -backslash-octal-digits notation. For characters below 32, and -for character 127, Calc uses the backslash-letter combination if -there is one, or otherwise uses a @samp{\^} sequence. - -The only Calc feature that uses strings is @dfn{compositions}; -@pxref{Compositions}. Strings also provide a convenient -way to do conversions between ASCII characters and integers. - -@ignore -@starindex -@end ignore -@tindex string -There is a @code{string} function which provides a different display -format for strings. Basically, @samp{string(@var{s})}, where @var{s} -is a vector of integers in the proper range, is displayed as the -corresponding string of characters with no surrounding quotation -marks or other modifications. Thus @samp{string("ABC")} (or -@samp{string([65 66 67])}) will look like @samp{ABC} on the stack. -This happens regardless of whether @w{@kbd{d "}} has been used. The -only way to turn it off is to use @kbd{d U} (unformatted language -mode) which will display @samp{string("ABC")} instead. - -Control characters are displayed somewhat differently by @code{string}. -Characters below 32, and character 127, are shown using @samp{^} notation -(same as shown above, but without the backslash). The quote and -backslash characters are left alone, as are characters 128 and above. - -@ignore -@starindex -@end ignore -@tindex bstring -The @code{bstring} function is just like @code{string} except that -the resulting string is breakable across multiple lines if it doesn't -fit all on one line. Potential break points occur at every space -character in the string. - -@node HMS Forms, Date Forms, Strings, Data Types -@section HMS Forms - -@noindent -@cindex Hours-minutes-seconds forms -@cindex Degrees-minutes-seconds forms -@dfn{HMS} stands for Hours-Minutes-Seconds; when used as an angular -argument, the interpretation is Degrees-Minutes-Seconds. All functions -that operate on angles accept HMS forms. These are interpreted as -degrees regardless of the current angular mode. It is also possible to -use HMS as the angular mode so that calculated angles are expressed in -degrees, minutes, and seconds. - -@kindex @@ -@ignore -@mindex @null -@end ignore -@kindex ' (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex " (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex h (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex o (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex m (HMS forms) -@ignore -@mindex @null -@end ignore -@kindex s (HMS forms) -The default format for HMS values is -@samp{@var{hours}@@ @var{mins}' @var{secs}"}. During entry, the letters -@samp{h} (for ``hours'') or -@samp{o} (approximating the ``degrees'' symbol) are accepted as well as -@samp{@@}, @samp{m} is accepted in place of @samp{'}, and @samp{s} is -accepted in place of @samp{"}. -The @var{hours} value is an integer (or integer-valued float). -The @var{mins} value is an integer or integer-valued float between 0 and 59. -The @var{secs} value is a real number between 0 (inclusive) and 60 -(exclusive). A positive HMS form is interpreted as @var{hours} + -@var{mins}/60 + @var{secs}/3600. A negative HMS form is interpreted -as @mathit{- @var{hours}} @mathit{-} @var{mins}/60 @mathit{-} @var{secs}/3600. -Display format for HMS forms is quite flexible. @xref{HMS Formats}. - -HMS forms can be added and subtracted. When they are added to numbers, -the numbers are interpreted according to the current angular mode. HMS -forms can also be multiplied and divided by real numbers. Dividing -two HMS forms produces a real-valued ratio of the two angles. - -@pindex calc-time -@cindex Time of day -Just for kicks, @kbd{M-x calc-time} pushes the current time of day on -the stack as an HMS form. - -@node Date Forms, Modulo Forms, HMS Forms, Data Types -@section Date Forms - -@noindent -@cindex Date forms -A @dfn{date form} represents a date and possibly an associated time. -Simple date arithmetic is supported: Adding a number to a date -produces a new date shifted by that many days; adding an HMS form to -a date shifts it by that many hours. Subtracting two date forms -computes the number of days between them (represented as a simple -number). Many other operations, such as multiplying two date forms, -are nonsensical and are not allowed by Calc. - -Date forms are entered and displayed enclosed in @samp{< >} brackets. -The default format is, e.g., @samp{} for dates, -or @samp{<3:32:20pm Wed Jan 9, 1991>} for dates with times. -Input is flexible; date forms can be entered in any of the usual -notations for dates and times. @xref{Date Formats}. - -Date forms are stored internally as numbers, specifically the number -of days since midnight on the morning of January 1 of the year 1 AD. -If the internal number is an integer, the form represents a date only; -if the internal number is a fraction or float, the form represents -a date and time. For example, @samp{<6:00am Wed Jan 9, 1991>} -is represented by the number 726842.25. The standard precision of -12 decimal digits is enough to ensure that a (reasonable) date and -time can be stored without roundoff error. - -If the current precision is greater than 12, date forms will keep -additional digits in the seconds position. For example, if the -precision is 15, the seconds will keep three digits after the -decimal point. Decreasing the precision below 12 may cause the -time part of a date form to become inaccurate. This can also happen -if astronomically high years are used, though this will not be an -issue in everyday (or even everymillennium) use. Note that date -forms without times are stored as exact integers, so roundoff is -never an issue for them. - -You can use the @kbd{v p} (@code{calc-pack}) and @kbd{v u} -(@code{calc-unpack}) commands to get at the numerical representation -of a date form. @xref{Packing and Unpacking}. - -Date forms can go arbitrarily far into the future or past. Negative -year numbers represent years BC. Calc uses a combination of the -Gregorian and Julian calendars, following the history of Great -Britain and the British colonies. This is the same calendar that -is used by the @code{cal} program in most Unix implementations. - -@cindex Julian calendar -@cindex Gregorian calendar -Some historical background: The Julian calendar was created by -Julius Caesar in the year 46 BC as an attempt to fix the gradual -drift caused by the lack of leap years in the calendar used -until that time. The Julian calendar introduced an extra day in -all years divisible by four. After some initial confusion, the -calendar was adopted around the year we call 8 AD. Some centuries -later it became apparent that the Julian year of 365.25 days was -itself not quite right. In 1582 Pope Gregory XIII introduced the -Gregorian calendar, which added the new rule that years divisible -by 100, but not by 400, were not to be considered leap years -despite being divisible by four. Many countries delayed adoption -of the Gregorian calendar because of religious differences; -in Britain it was put off until the year 1752, by which time -the Julian calendar had fallen eleven days behind the true -seasons. So the switch to the Gregorian calendar in early -September 1752 introduced a discontinuity: The day after -Sep 2, 1752 is Sep 14, 1752. Calc follows this convention. -To take another example, Russia waited until 1918 before -adopting the new calendar, and thus needed to remove thirteen -days (between Feb 1, 1918 and Feb 14, 1918). This means that -Calc's reckoning will be inconsistent with Russian history between -1752 and 1918, and similarly for various other countries. - -Today's timekeepers introduce an occasional ``leap second'' as -well, but Calc does not take these minor effects into account. -(If it did, it would have to report a non-integer number of days -between, say, @samp{<12:00am Mon Jan 1, 1900>} and -@samp{<12:00am Sat Jan 1, 2000>}.) - -Calc uses the Julian calendar for all dates before the year 1752, -including dates BC when the Julian calendar technically had not -yet been invented. Thus the claim that day number @mathit{-10000} is -called ``August 16, 28 BC'' should be taken with a grain of salt. - -Please note that there is no ``year 0''; the day before -@samp{} is @samp{}. These are -days 0 and @mathit{-1} respectively in Calc's internal numbering scheme. - -@cindex Julian day counting -Another day counting system in common use is, confusingly, also called -``Julian.'' The Julian day number is the numbers of days since -12:00 noon (GMT) on Jan 1, 4713 BC, which in Calc's scheme (in GMT) -is @mathit{-1721423.5} (recall that Calc starts at midnight instead -of noon). Thus to convert a Calc date code obtained by unpacking a -date form into a Julian day number, simply add 1721423.5 after -compensating for the time zone difference. The built-in @kbd{t J} -command performs this conversion for you. - -The Julian day number is based on the Julian cycle, which was invented -in 1583 by Joseph Justus Scaliger. Scaliger named it the Julian cycle -since it is involves the Julian calendar, but some have suggested that -Scaliger named it in honor of his father, Julius Caesar Scaliger. The -Julian cycle is based it on three other cycles: the indiction cycle, -the Metonic cycle, and the solar cycle. The indiction cycle is a 15 -year cycle originally used by the Romans for tax purposes but later -used to date medieval documents. The Metonic cycle is a 19 year -cycle; 19 years is close to being a common multiple of a solar year -and a lunar month, and so every 19 years the phases of the moon will -occur on the same days of the year. The solar cycle is a 28 year -cycle; the Julian calendar repeats itself every 28 years. The -smallest time period which contains multiples of all three cycles is -the least common multiple of 15 years, 19 years and 28 years, which -(since they're pairwise relatively prime) is -@texline @math{15\times 19\times 28 = 7980} years. -@infoline 15*19*28 = 7980 years. -This is the length of a Julian cycle. Working backwards, the previous -year in which all three cycles began was 4713 BC, and so Scalinger -chose that year as the beginning of a Julian cycle. Since at the time -there were no historical records from before 4713 BC, using this year -as a starting point had the advantage of avoiding negative year -numbers. In 1849, the astronomer John Herschel (son of William -Herschel) suggested using the number of days since the beginning of -the Julian cycle as an astronomical dating system; this idea was taken -up by other astronomers. (At the time, noon was the start of the -astronomical day. Herschel originally suggested counting the days -since Jan 1, 4713 BC at noon Alexandria time; this was later amended to -noon GMT.) Julian day numbering is largely used in astronomy. - -@cindex Unix time format -The Unix operating system measures time as an integer number of -seconds since midnight, Jan 1, 1970. To convert a Calc date -value into a Unix time stamp, first subtract 719164 (the code -for @samp{}), then multiply by 86400 (the number of -seconds in a day) and press @kbd{R} to round to the nearest -integer. If you have a date form, you can simply subtract the -day @samp{} instead of unpacking and subtracting -719164. Likewise, divide by 86400 and add @samp{} -to convert from Unix time to a Calc date form. (Note that -Unix normally maintains the time in the GMT time zone; you may -need to subtract five hours to get New York time, or eight hours -for California time. The same is usually true of Julian day -counts.) The built-in @kbd{t U} command performs these -conversions. - -@node Modulo Forms, Error Forms, Date Forms, Data Types -@section Modulo Forms - -@noindent -@cindex Modulo forms -A @dfn{modulo form} is a real number which is taken modulo (i.e., within -an integer multiple of) some value @var{M}. Arithmetic modulo @var{M} -often arises in number theory. Modulo forms are written -`@var{a} @tfn{mod} @var{M}', -where @var{a} and @var{M} are real numbers or HMS forms, and -@texline @math{0 \le a < M}. -@infoline @expr{0 <= a < @var{M}}. -In many applications @expr{a} and @expr{M} will be -integers but this is not required. - -@ignore -@mindex M -@end ignore -@kindex M (modulo forms) -@ignore -@mindex mod -@end ignore -@tindex mod (operator) -To create a modulo form during numeric entry, press the shift-@kbd{M} -key to enter the word @samp{mod}. As a special convenience, pressing -shift-@kbd{M} a second time automatically enters the value of @expr{M} -that was most recently used before. During algebraic entry, either -type @samp{mod} by hand or press @kbd{M-m} (that's @kbd{@key{META}-m}). -Once again, pressing this a second time enters the current modulo. - -Modulo forms are not to be confused with the modulo operator @samp{%}. -The expression @samp{27 % 10} means to compute 27 modulo 10 to produce -the result 7. Further computations treat this 7 as just a regular integer. -The expression @samp{27 mod 10} produces the result @samp{7 mod 10}; -further computations with this value are again reduced modulo 10 so that -the result always lies in the desired range. - -When two modulo forms with identical @expr{M}'s are added or multiplied, -the Calculator simply adds or multiplies the values, then reduces modulo -@expr{M}. If one argument is a modulo form and the other a plain number, -the plain number is treated like a compatible modulo form. It is also -possible to raise modulo forms to powers; the result is the value raised -to the power, then reduced modulo @expr{M}. (When all values involved -are integers, this calculation is done much more efficiently than -actually computing the power and then reducing.) - -@cindex Modulo division -Two modulo forms `@var{a} @tfn{mod} @var{M}' and `@var{b} @tfn{mod} @var{M}' -can be divided if @expr{a}, @expr{b}, and @expr{M} are all -integers. The result is the modulo form which, when multiplied by -`@var{b} @tfn{mod} @var{M}', produces `@var{a} @tfn{mod} @var{M}'. If -there is no solution to this equation (which can happen only when -@expr{M} is non-prime), or if any of the arguments are non-integers, the -division is left in symbolic form. Other operations, such as square -roots, are not yet supported for modulo forms. (Note that, although -@w{`@tfn{(}@var{a} @tfn{mod} @var{M}@tfn{)^.5}'} will compute a ``modulo square root'' -in the sense of reducing -@texline @math{\sqrt a} -@infoline @expr{sqrt(a)} -modulo @expr{M}, this is not a useful definition from the -number-theoretical point of view.) - -It is possible to mix HMS forms and modulo forms. For example, an -HMS form modulo 24 could be used to manipulate clock times; an HMS -form modulo 360 would be suitable for angles. Making the modulo @expr{M} -also be an HMS form eliminates troubles that would arise if the angular -mode were inadvertently set to Radians, in which case -@w{@samp{2@@ 0' 0" mod 24}} would be interpreted as two degrees modulo -24 radians! - -Modulo forms cannot have variables or formulas for components. If you -enter the formula @samp{(x + 2) mod 5}, Calc propagates the modulus -to each of the coefficients: @samp{(1 mod 5) x + (2 mod 5)}. - -You can use @kbd{v p} and @kbd{%} to modify modulo forms. -@xref{Packing and Unpacking}. @xref{Basic Arithmetic}. - -@ignore -@starindex -@end ignore -@tindex makemod -The algebraic function @samp{makemod(a, m)} builds the modulo form -@w{@samp{a mod m}}. - -@node Error Forms, Interval Forms, Modulo Forms, Data Types -@section Error Forms - -@noindent -@cindex Error forms -@cindex Standard deviations -An @dfn{error form} is a number with an associated standard -deviation, as in @samp{2.3 +/- 0.12}. The notation -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} sigma' -stands for an uncertain value which follows -a normal or Gaussian distribution of mean @expr{x} and standard -deviation or ``error'' -@texline @math{\sigma}. -@infoline @expr{sigma}. -Both the mean and the error can be either numbers or -formulas. Generally these are real numbers but the mean may also be -complex. If the error is negative or complex, it is changed to its -absolute value. An error form with zero error is converted to a -regular number by the Calculator. - -All arithmetic and transcendental functions accept error forms as input. -Operations on the mean-value part work just like operations on regular -numbers. The error part for any function @expr{f(x)} (such as -@texline @math{\sin x} -@infoline @expr{sin(x)}) -is defined by the error of @expr{x} times the derivative of @expr{f} -evaluated at the mean value of @expr{x}. For a two-argument function -@expr{f(x,y)} (such as addition) the error is the square root of the sum -of the squares of the errors due to @expr{x} and @expr{y}. -@tex -$$ \eqalign{ - f(x \hbox{\code{ +/- }} \sigma) - &= f(x) \hbox{\code{ +/- }} \sigma \left| {df(x) \over dx} \right| \cr - f(x \hbox{\code{ +/- }} \sigma_x, y \hbox{\code{ +/- }} \sigma_y) - &= f(x,y) \hbox{\code{ +/- }} - \sqrt{\left(\sigma_x \left| {\partial f(x,y) \over \partial x} - \right| \right)^2 - +\left(\sigma_y \left| {\partial f(x,y) \over \partial y} - \right| \right)^2 } \cr -} $$ -@end tex -Note that this -definition assumes the errors in @expr{x} and @expr{y} are uncorrelated. -A side effect of this definition is that @samp{(2 +/- 1) * (2 +/- 1)} -is not the same as @samp{(2 +/- 1)^2}; the former represents the product -of two independent values which happen to have the same probability -distributions, and the latter is the product of one random value with itself. -The former will produce an answer with less error, since on the average -the two independent errors can be expected to cancel out. - -Consult a good text on error analysis for a discussion of the proper use -of standard deviations. Actual errors often are neither Gaussian-distributed -nor uncorrelated, and the above formulas are valid only when errors -are small. As an example, the error arising from -@texline `@tfn{sin(}@var{x} @tfn{+/-} @math{\sigma}@tfn{)}' -@infoline `@tfn{sin(}@var{x} @tfn{+/-} @var{sigma}@tfn{)}' -is -@texline `@math{\sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -@infoline `@var{sigma} @tfn{abs(cos(}@var{x}@tfn{))}'. -When @expr{x} is close to zero, -@texline @math{\cos x} -@infoline @expr{cos(x)} -is close to one so the error in the sine is close to -@texline @math{\sigma}; -@infoline @expr{sigma}; -this makes sense, since -@texline @math{\sin x} -@infoline @expr{sin(x)} -is approximately @expr{x} near zero, so a given error in @expr{x} will -produce about the same error in the sine. Likewise, near 90 degrees -@texline @math{\cos x} -@infoline @expr{cos(x)} -is nearly zero and so the computed error is -small: The sine curve is nearly flat in that region, so an error in @expr{x} -has relatively little effect on the value of -@texline @math{\sin x}. -@infoline @expr{sin(x)}. -However, consider @samp{sin(90 +/- 1000)}. The cosine of 90 is zero, so -Calc will report zero error! We get an obviously wrong result because -we have violated the small-error approximation underlying the error -analysis. If the error in @expr{x} had been small, the error in -@texline @math{\sin x} -@infoline @expr{sin(x)} -would indeed have been negligible. - -@ignore -@mindex p -@end ignore -@kindex p (error forms) -@tindex +/- -To enter an error form during regular numeric entry, use the @kbd{p} -(``plus-or-minus'') key to type the @samp{+/-} symbol. (If you try actually -typing @samp{+/-} the @kbd{+} key will be interpreted as the Calculator's -@kbd{+} command!) Within an algebraic formula, you can press @kbd{M-+} to -type the @samp{+/-} symbol, or type it out by hand. - -Error forms and complex numbers can be mixed; the formulas shown above -are used for complex numbers, too; note that if the error part evaluates -to a complex number its absolute value (or the square root of the sum of -the squares of the absolute values of the two error contributions) is -used. Mathematically, this corresponds to a radially symmetric Gaussian -distribution of numbers on the complex plane. However, note that Calc -considers an error form with real components to represent a real number, -not a complex distribution around a real mean. - -Error forms may also be composed of HMS forms. For best results, both -the mean and the error should be HMS forms if either one is. - -@ignore -@starindex -@end ignore -@tindex sdev -The algebraic function @samp{sdev(a, b)} builds the error form @samp{a +/- b}. - -@node Interval Forms, Incomplete Objects, Error Forms, Data Types -@section Interval Forms - -@noindent -@cindex Interval forms -An @dfn{interval} is a subset of consecutive real numbers. For example, -the interval @samp{[2 ..@: 4]} represents all the numbers from 2 to 4, -inclusive. If you multiply it by the interval @samp{[0.5 ..@: 2]} you -obtain @samp{[1 ..@: 8]}. This calculation represents the fact that if -you multiply some number in the range @samp{[2 ..@: 4]} by some other -number in the range @samp{[0.5 ..@: 2]}, your result will lie in the range -from 1 to 8. Interval arithmetic is used to get a worst-case estimate -of the possible range of values a computation will produce, given the -set of possible values of the input. - -@ifnottex -Calc supports several varieties of intervals, including @dfn{closed} -intervals of the type shown above, @dfn{open} intervals such as -@samp{(2 ..@: 4)}, which represents the range of numbers from 2 to 4 -@emph{exclusive}, and @dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -@samp{[2 ..@: 4]} means @expr{2 <= x <= 4}, whereas -@samp{[2 ..@: 4)} represents @expr{2 <= x < 4}, -@samp{(2 ..@: 4]} represents @expr{2 < x <= 4}, and -@samp{(2 ..@: 4)} represents @expr{2 < x < 4}. -@end ifnottex -@tex -Calc supports several varieties of intervals, including \dfn{closed} -intervals of the type shown above, \dfn{open} intervals such as -\samp{(2 ..\: 4)}, which represents the range of numbers from 2 to 4 -\emph{exclusive}, and \dfn{semi-open} intervals in which one end -uses a round parenthesis and the other a square bracket. In mathematical -terms, -$$ \eqalign{ - [2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 \le x \le 4 \cr - [2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 \le x < 4 \cr - (2 \hbox{\cite{..}} 4] &\quad\hbox{means}\quad 2 < x \le 4 \cr - (2 \hbox{\cite{..}} 4) &\quad\hbox{means}\quad 2 < x < 4 \cr -} $$ -@end tex - -The lower and upper limits of an interval must be either real numbers -(or HMS or date forms), or symbolic expressions which are assumed to be -real-valued, or @samp{-inf} and @samp{inf}. In general the lower limit -must be less than the upper limit. A closed interval containing only -one value, @samp{[3 ..@: 3]}, is converted to a plain number (3) -automatically. An interval containing no values at all (such as -@samp{[3 ..@: 2]} or @samp{[2 ..@: 2)}) can be represented but is not -guaranteed to behave well when used in arithmetic. Note that the -interval @samp{[3 .. inf)} represents all real numbers greater than -or equal to 3, and @samp{(-inf .. inf)} represents all real numbers. -In fact, @samp{[-inf .. inf]} represents all real numbers including -the real infinities. - -Intervals are entered in the notation shown here, either as algebraic -formulas, or using incomplete forms. (@xref{Incomplete Objects}.) -In algebraic formulas, multiple periods in a row are collected from -left to right, so that @samp{1...1e2} is interpreted as @samp{1.0 ..@: 1e2} -rather than @samp{1 ..@: 0.1e2}. Add spaces or zeros if you want to -get the other interpretation. If you omit the lower or upper limit, -a default of @samp{-inf} or @samp{inf} (respectively) is furnished. - -Infinite mode also affects operations on intervals -(@pxref{Infinities}). Calc will always introduce an open infinity, -as in @samp{1 / (0 .. 2] = [0.5 .. inf)}. But closed infinities, -@w{@samp{1 / [0 .. 2] = [0.5 .. inf]}}, arise only in Infinite mode; -otherwise they are left unevaluated. Note that the ``direction'' of -a zero is not an issue in this case since the zero is always assumed -to be continuous with the rest of the interval. For intervals that -contain zero inside them Calc is forced to give the result, -@samp{1 / (-2 .. 2) = [-inf .. inf]}. - -While it may seem that intervals and error forms are similar, they are -based on entirely different concepts of inexact quantities. An error -form -@texline `@var{x} @tfn{+/-} @math{\sigma}' -@infoline `@var{x} @tfn{+/-} @var{sigma}' -means a variable is random, and its value could -be anything but is ``probably'' within one -@texline @math{\sigma} -@infoline @var{sigma} -of the mean value @expr{x}. An interval -`@tfn{[}@var{a} @tfn{..@:} @var{b}@tfn{]}' means a -variable's value is unknown, but guaranteed to lie in the specified -range. Error forms are statistical or ``average case'' approximations; -interval arithmetic tends to produce ``worst case'' bounds on an -answer. - -Intervals may not contain complex numbers, but they may contain -HMS forms or date forms. - -@xref{Set Operations}, for commands that interpret interval forms -as subsets of the set of real numbers. - -@ignore -@starindex -@end ignore -@tindex intv -The algebraic function @samp{intv(n, a, b)} builds an interval form -from @samp{a} to @samp{b}; @samp{n} is an integer code which must -be 0 for @samp{(..)}, 1 for @samp{(..]}, 2 for @samp{[..)}, or -3 for @samp{[..]}. - -Please note that in fully rigorous interval arithmetic, care would be -taken to make sure that the computation of the lower bound rounds toward -minus infinity, while upper bound computations round toward plus -infinity. Calc's arithmetic always uses a round-to-nearest mode, -which means that roundoff errors could creep into an interval -calculation to produce intervals slightly smaller than they ought to -be. For example, entering @samp{[1..2]} and pressing @kbd{Q 2 ^} -should yield the interval @samp{[1..2]} again, but in fact it yields the -(slightly too small) interval @samp{[1..1.9999999]} due to roundoff -error. - -@node Incomplete Objects, Variables, Interval Forms, Data Types -@section Incomplete Objects - -@noindent -@ignore -@mindex [ ] -@end ignore -@kindex [ -@ignore -@mindex ( ) -@end ignore -@kindex ( -@kindex , -@ignore -@mindex @null -@end ignore -@kindex ] -@ignore -@mindex @null -@end ignore -@kindex ) -@cindex Incomplete vectors -@cindex Incomplete complex numbers -@cindex Incomplete interval forms -When @kbd{(} or @kbd{[} is typed to begin entering a complex number or -vector, respectively, the effect is to push an @dfn{incomplete} complex -number or vector onto the stack. The @kbd{,} key adds the value(s) at -the top of the stack onto the current incomplete object. The @kbd{)} -and @kbd{]} keys ``close'' the incomplete object after adding any values -on the top of the stack in front of the incomplete object. - -As a result, the sequence of keystrokes @kbd{[ 2 , 3 @key{RET} 2 * , 9 ]} -pushes the vector @samp{[2, 6, 9]} onto the stack. Likewise, @kbd{( 1 , 2 Q )} -pushes the complex number @samp{(1, 1.414)} (approximately). - -If several values lie on the stack in front of the incomplete object, -all are collected and appended to the object. Thus the @kbd{,} key -is redundant: @kbd{[ 2 @key{RET} 3 @key{RET} 2 * 9 ]}. Some people -prefer the equivalent @key{SPC} key to @key{RET}. - -As a special case, typing @kbd{,} immediately after @kbd{(}, @kbd{[}, or -@kbd{,} adds a zero or duplicates the preceding value in the list being -formed. Typing @key{DEL} during incomplete entry removes the last item -from the list. - -@kindex ; -The @kbd{;} key is used in the same way as @kbd{,} to create polar complex -numbers: @kbd{( 1 ; 2 )}. When entering a vector, @kbd{;} is useful for -creating a matrix. In particular, @kbd{[ [ 1 , 2 ; 3 , 4 ; 5 , 6 ] ]} is -equivalent to @kbd{[ [ 1 , 2 ] , [ 3 , 4 ] , [ 5 , 6 ] ]}. - -@kindex .. -@pindex calc-dots -Incomplete entry is also used to enter intervals. For example, -@kbd{[ 2 ..@: 4 )} enters a semi-open interval. Note that when you type -the first period, it will be interpreted as a decimal point, but when -you type a second period immediately afterward, it is re-interpreted as -part of the interval symbol. Typing @kbd{..} corresponds to executing -the @code{calc-dots} command. - -If you find incomplete entry distracting, you may wish to enter vectors -and complex numbers as algebraic formulas by pressing the apostrophe key. - -@node Variables, Formulas, Incomplete Objects, Data Types -@section Variables - -@noindent -@cindex Variables, in formulas -A @dfn{variable} is somewhere between a storage register on a conventional -calculator, and a variable in a programming language. (In fact, a Calc -variable is really just an Emacs Lisp variable that contains a Calc number -or formula.) A variable's name is normally composed of letters and digits. -Calc also allows apostrophes and @code{#} signs in variable names. -(The Calc variable @code{foo} corresponds to the Emacs Lisp variable -@code{var-foo}, but unless you access the variable from within Emacs -Lisp, you don't need to worry about it. Variable names in algebraic -formulas implicitly have @samp{var-} prefixed to their names. The -@samp{#} character in variable names used in algebraic formulas -corresponds to a dash @samp{-} in the Lisp variable name. If the name -contains any dashes, the prefix @samp{var-} is @emph{not} automatically -added. Thus the two formulas @samp{foo + 1} and @samp{var#foo + 1} both -refer to the same variable.) - -In a command that takes a variable name, you can either type the full -name of a variable, or type a single digit to use one of the special -convenience variables @code{q0} through @code{q9}. For example, -@kbd{3 s s 2} stores the number 3 in variable @code{q2}, and -@w{@kbd{3 s s foo @key{RET}}} stores that number in variable -@code{foo}. - -To push a variable itself (as opposed to the variable's value) on the -stack, enter its name as an algebraic expression using the apostrophe -(@key{'}) key. - -@kindex = -@pindex calc-evaluate -@cindex Evaluation of variables in a formula -@cindex Variables, evaluation -@cindex Formulas, evaluation -The @kbd{=} (@code{calc-evaluate}) key ``evaluates'' a formula by -replacing all variables in the formula which have been given values by a -@code{calc-store} or @code{calc-let} command by their stored values. -Other variables are left alone. Thus a variable that has not been -stored acts like an abstract variable in algebra; a variable that has -been stored acts more like a register in a traditional calculator. -With a positive numeric prefix argument, @kbd{=} evaluates the top -@var{n} stack entries; with a negative argument, @kbd{=} evaluates -the @var{n}th stack entry. - -@cindex @code{e} variable -@cindex @code{pi} variable -@cindex @code{i} variable -@cindex @code{phi} variable -@cindex @code{gamma} variable -@vindex e -@vindex pi -@vindex i -@vindex phi -@vindex gamma -A few variables are called @dfn{special constants}. Their names are -@samp{e}, @samp{pi}, @samp{i}, @samp{phi}, and @samp{gamma}. -(@xref{Scientific Functions}.) When they are evaluated with @kbd{=}, -their values are calculated if necessary according to the current precision -or complex polar mode. If you wish to use these symbols for other purposes, -simply undefine or redefine them using @code{calc-store}. - -The variables @samp{inf}, @samp{uinf}, and @samp{nan} stand for -infinite or indeterminate values. It's best not to use them as -regular variables, since Calc uses special algebraic rules when -it manipulates them. Calc displays a warning message if you store -a value into any of these special variables. - -@xref{Store and Recall}, for a discussion of commands dealing with variables. - -@node Formulas, , Variables, Data Types -@section Formulas - -@noindent -@cindex Formulas -@cindex Expressions -@cindex Operators in formulas -@cindex Precedence of operators -When you press the apostrophe key you may enter any expression or formula -in algebraic form. (Calc uses the terms ``expression'' and ``formula'' -interchangeably.) An expression is built up of numbers, variable names, -and function calls, combined with various arithmetic operators. -Parentheses may -be used to indicate grouping. Spaces are ignored within formulas, except -that spaces are not permitted within variable names or numbers. -Arithmetic operators, in order from highest to lowest precedence, and -with their equivalent function names, are: - -@samp{_} [@code{subscr}] (subscripts); - -postfix @samp{%} [@code{percent}] (as in @samp{25% = 0.25}); - -prefix @samp{!} [@code{lnot}] (logical ``not,'' as in @samp{!x}); - -@samp{+/-} [@code{sdev}] (the standard deviation symbol) and -@samp{mod} [@code{makemod}] (the symbol for modulo forms); - -postfix @samp{!} [@code{fact}] (factorial, as in @samp{n!}) -and postfix @samp{!!} [@code{dfact}] (double factorial); - -@samp{^} [@code{pow}] (raised-to-the-power-of); - -prefix @samp{+} and @samp{-} [@code{neg}] (as in @samp{-x}); - -@samp{*} [@code{mul}]; - -@samp{/} [@code{div}], @samp{%} [@code{mod}] (modulo), and -@samp{\} [@code{idiv}] (integer division); - -infix @samp{+} [@code{add}] and @samp{-} [@code{sub}] (as in @samp{x-y}); - -@samp{|} [@code{vconcat}] (vector concatenation); - -relations @samp{=} [@code{eq}], @samp{!=} [@code{neq}], @samp{<} [@code{lt}], -@samp{>} [@code{gt}], @samp{<=} [@code{leq}], and @samp{>=} [@code{geq}]; - -@samp{&&} [@code{land}] (logical ``and''); - -@samp{||} [@code{lor}] (logical ``or''); - -the C-style ``if'' operator @samp{a?b:c} [@code{if}]; - -@samp{!!!} [@code{pnot}] (rewrite pattern ``not''); - -@samp{&&&} [@code{pand}] (rewrite pattern ``and''); - -@samp{|||} [@code{por}] (rewrite pattern ``or''); - -@samp{:=} [@code{assign}] (for assignments and rewrite rules); - -@samp{::} [@code{condition}] (rewrite pattern condition); - -@samp{=>} [@code{evalto}]. - -Note that, unlike in usual computer notation, multiplication binds more -strongly than division: @samp{a*b/c*d} is equivalent to -@texline @math{a b \over c d}. -@infoline @expr{(a*b)/(c*d)}. - -@cindex Multiplication, implicit -@cindex Implicit multiplication -The multiplication sign @samp{*} may be omitted in many cases. In particular, -if the righthand side is a number, variable name, or parenthesized -expression, the @samp{*} may be omitted. Implicit multiplication has the -same precedence as the explicit @samp{*} operator. The one exception to -the rule is that a variable name followed by a parenthesized expression, -as in @samp{f(x)}, -is interpreted as a function call, not an implicit @samp{*}. In many -cases you must use a space if you omit the @samp{*}: @samp{2a} is the -same as @samp{2*a}, and @samp{a b} is the same as @samp{a*b}, but @samp{ab} -is a variable called @code{ab}, @emph{not} the product of @samp{a} and -@samp{b}! Also note that @samp{f (x)} is still a function call. - -@cindex Implicit comma in vectors -The rules are slightly different for vectors written with square brackets. -In vectors, the space character is interpreted (like the comma) as a -separator of elements of the vector. Thus @w{@samp{[ 2a b+c d ]}} is -equivalent to @samp{[2*a, b+c, d]}, whereas @samp{2a b+c d} is equivalent -to @samp{2*a*b + c*d}. -Note that spaces around the brackets, and around explicit commas, are -ignored. To force spaces to be interpreted as multiplication you can -enclose a formula in parentheses as in @samp{[(a b) 2(c d)]}, which is -interpreted as @samp{[a*b, 2*c*d]}. An implicit comma is also inserted -between @samp{][}, as in the matrix @samp{[[1 2][3 4]]}. - -Vectors that contain commas (not embedded within nested parentheses or -brackets) do not treat spaces specially: @samp{[a b, 2 c d]} is a vector -of two elements. Also, if it would be an error to treat spaces as -separators, but not otherwise, then Calc will ignore spaces: -@w{@samp{[a - b]}} is a vector of one element, but @w{@samp{[a -b]}} is -a vector of two elements. Finally, vectors entered with curly braces -instead of square brackets do not give spaces any special treatment. -When Calc displays a vector that does not contain any commas, it will -insert parentheses if necessary to make the meaning clear: -@w{@samp{[(a b)]}}. - -The expression @samp{5%-2} is ambiguous; is this five-percent minus two, -or five modulo minus-two? Calc always interprets the leftmost symbol as -an infix operator preferentially (modulo, in this case), so you would -need to write @samp{(5%)-2} to get the former interpretation. - -@cindex Function call notation -A function call is, e.g., @samp{sin(1+x)}. (The Calc algebraic function -@code{foo} corresponds to the Emacs Lisp function @code{calcFunc-foo}, -but unless you access the function from within Emacs Lisp, you don't -need to worry about it.) Most mathematical Calculator commands like -@code{calc-sin} have function equivalents like @code{sin}. -If no Lisp function is defined for a function called by a formula, the -call is left as it is during algebraic manipulation: @samp{f(x+y)} is -left alone. Beware that many innocent-looking short names like @code{in} -and @code{re} have predefined meanings which could surprise you; however, -single letters or single letters followed by digits are always safe to -use for your own function names. @xref{Function Index}. - -In the documentation for particular commands, the notation @kbd{H S} -(@code{calc-sinh}) [@code{sinh}] means that the key sequence @kbd{H S}, the -command @kbd{M-x calc-sinh}, and the algebraic function @code{sinh(x)} all -represent the same operation. - -Commands that interpret (``parse'') text as algebraic formulas include -algebraic entry (@kbd{'}), editing commands like @kbd{`} which parse -the contents of the editing buffer when you finish, the @kbd{C-x * g} -and @w{@kbd{C-x * r}} commands, the @kbd{C-y} command, the X window system -``paste'' mouse operation, and Embedded mode. All of these operations -use the same rules for parsing formulas; in particular, language modes -(@pxref{Language Modes}) affect them all in the same way. - -When you read a large amount of text into the Calculator (say a vector -which represents a big set of rewrite rules; @pxref{Rewrite Rules}), -you may wish to include comments in the text. Calc's formula parser -ignores the symbol @samp{%%} and anything following it on a line: - -@example -[ a + b, %% the sum of "a" and "b" - c + d, - %% last line is coming up: - e + f ] -@end example - -@noindent -This is parsed exactly the same as @samp{[ a + b, c + d, e + f ]}. - -@xref{Syntax Tables}, for a way to create your own operators and other -input notations. @xref{Compositions}, for a way to create new display -formats. - -@xref{Algebra}, for commands for manipulating formulas symbolically. - -@node Stack and Trail, Mode Settings, Data Types, Top -@chapter Stack and Trail Commands - -@noindent -This chapter describes the Calc commands for manipulating objects on the -stack and in the trail buffer. (These commands operate on objects of any -type, such as numbers, vectors, formulas, and incomplete objects.) - -@menu -* Stack Manipulation:: -* Editing Stack Entries:: -* Trail Commands:: -* Keep Arguments:: -@end menu - -@node Stack Manipulation, Editing Stack Entries, Stack and Trail, Stack and Trail -@section Stack Manipulation Commands - -@noindent -@kindex @key{RET} -@kindex @key{SPC} -@pindex calc-enter -@cindex Duplicating stack entries -To duplicate the top object on the stack, press @key{RET} or @key{SPC} -(two equivalent keys for the @code{calc-enter} command). -Given a positive numeric prefix argument, these commands duplicate -several elements at the top of the stack. -Given a negative argument, -these commands duplicate the specified element of the stack. -Given an argument of zero, they duplicate the entire stack. -For example, with @samp{10 20 30} on the stack, -@key{RET} creates @samp{10 20 30 30}, -@kbd{C-u 2 @key{RET}} creates @samp{10 20 30 20 30}, -@kbd{C-u - 2 @key{RET}} creates @samp{10 20 30 20}, and -@kbd{C-u 0 @key{RET}} creates @samp{10 20 30 10 20 30}. - -@kindex @key{LFD} -@pindex calc-over -The @key{LFD} (@code{calc-over}) command (on a key marked Line-Feed if you -have it, else on @kbd{C-j}) is like @code{calc-enter} -except that the sign of the numeric prefix argument is interpreted -oppositely. Also, with no prefix argument the default argument is 2. -Thus with @samp{10 20 30} on the stack, @key{LFD} and @kbd{C-u 2 @key{LFD}} -are both equivalent to @kbd{C-u - 2 @key{RET}}, producing -@samp{10 20 30 20}. - -@kindex @key{DEL} -@kindex C-d -@pindex calc-pop -@cindex Removing stack entries -@cindex Deleting stack entries -To remove the top element from the stack, press @key{DEL} (@code{calc-pop}). -The @kbd{C-d} key is a synonym for @key{DEL}. -(If the top element is an incomplete object with at least one element, the -last element is removed from it.) Given a positive numeric prefix argument, -several elements are removed. Given a negative argument, the specified -element of the stack is deleted. Given an argument of zero, the entire -stack is emptied. -For example, with @samp{10 20 30} on the stack, -@key{DEL} leaves @samp{10 20}, -@kbd{C-u 2 @key{DEL}} leaves @samp{10}, -@kbd{C-u - 2 @key{DEL}} leaves @samp{10 30}, and -@kbd{C-u 0 @key{DEL}} leaves an empty stack. - -@kindex M-@key{DEL} -@pindex calc-pop-above -The @kbd{M-@key{DEL}} (@code{calc-pop-above}) command is to @key{DEL} what -@key{LFD} is to @key{RET}: It interprets the sign of the numeric -prefix argument in the opposite way, and the default argument is 2. -Thus @kbd{M-@key{DEL}} by itself removes the second-from-top stack element, -leaving the first, third, fourth, and so on; @kbd{M-3 M-@key{DEL}} deletes -the third stack element. - -@kindex @key{TAB} -@pindex calc-roll-down -To exchange the top two elements of the stack, press @key{TAB} -(@code{calc-roll-down}). Given a positive numeric prefix argument, the -specified number of elements at the top of the stack are rotated downward. -Given a negative argument, the entire stack is rotated downward the specified -number of times. Given an argument of zero, the entire stack is reversed -top-for-bottom. -For example, with @samp{10 20 30 40 50} on the stack, -@key{TAB} creates @samp{10 20 30 50 40}, -@kbd{C-u 3 @key{TAB}} creates @samp{10 20 50 30 40}, -@kbd{C-u - 2 @key{TAB}} creates @samp{40 50 10 20 30}, and -@kbd{C-u 0 @key{TAB}} creates @samp{50 40 30 20 10}. - -@kindex M-@key{TAB} -@pindex calc-roll-up -The command @kbd{M-@key{TAB}} (@code{calc-roll-up}) is analogous to @key{TAB} -except that it rotates upward instead of downward. Also, the default -with no prefix argument is to rotate the top 3 elements. -For example, with @samp{10 20 30 40 50} on the stack, -@kbd{M-@key{TAB}} creates @samp{10 20 40 50 30}, -@kbd{C-u 4 M-@key{TAB}} creates @samp{10 30 40 50 20}, -@kbd{C-u - 2 M-@key{TAB}} creates @samp{30 40 50 10 20}, and -@kbd{C-u 0 M-@key{TAB}} creates @samp{50 40 30 20 10}. - -A good way to view the operation of @key{TAB} and @kbd{M-@key{TAB}} is in -terms of moving a particular element to a new position in the stack. -With a positive argument @var{n}, @key{TAB} moves the top stack -element down to level @var{n}, making room for it by pulling all the -intervening stack elements toward the top. @kbd{M-@key{TAB}} moves the -element at level @var{n} up to the top. (Compare with @key{LFD}, -which copies instead of moving the element in level @var{n}.) - -With a negative argument @mathit{-@var{n}}, @key{TAB} rotates the stack -to move the object in level @var{n} to the deepest place in the -stack, and the object in level @mathit{@var{n}+1} to the top. @kbd{M-@key{TAB}} -rotates the deepest stack element to be in level @mathit{n}, also -putting the top stack element in level @mathit{@var{n}+1}. - -@xref{Selecting Subformulas}, for a way to apply these commands to -any portion of a vector or formula on the stack. - -@node Editing Stack Entries, Trail Commands, Stack Manipulation, Stack and Trail -@section Editing Stack Entries - -@noindent -@kindex ` -@pindex calc-edit -@pindex calc-edit-finish -@cindex Editing the stack with Emacs -The @kbd{`} (@code{calc-edit}) command creates a temporary buffer -(@samp{*Calc Edit*}) for editing the top-of-stack value using regular -Emacs commands. Note that @kbd{`} is a backquote, not a quote. With a -numeric prefix argument, it edits the specified number of stack entries -at once. (An argument of zero edits the entire stack; a negative -argument edits one specific stack entry.) - -When you are done editing, press @kbd{C-c C-c} to finish and return -to Calc. The @key{RET} and @key{LFD} keys also work to finish most -sorts of editing, though in some cases Calc leaves @key{RET} with its -usual meaning (``insert a newline'') if it's a situation where you -might want to insert new lines into the editing buffer. - -When you finish editing, the Calculator parses the lines of text in -the @samp{*Calc Edit*} buffer as numbers or formulas, replaces the -original stack elements in the original buffer with these new values, -then kills the @samp{*Calc Edit*} buffer. The original Calculator buffer -continues to exist during editing, but for best results you should be -careful not to change it until you have finished the edit. You can -also cancel the edit by killing the buffer with @kbd{C-x k}. - -The formula is normally reevaluated as it is put onto the stack. -For example, editing @samp{a + 2} to @samp{3 + 2} and pressing -@kbd{C-c C-c} will push 5 on the stack. If you use @key{LFD} to -finish, Calc will put the result on the stack without evaluating it. - -If you give a prefix argument to @kbd{C-c C-c}, -Calc will not kill the @samp{*Calc Edit*} buffer. You can switch -back to that buffer and continue editing if you wish. However, you -should understand that if you initiated the edit with @kbd{`}, the -@kbd{C-c C-c} operation will be programmed to replace the top of the -stack with the new edited value, and it will do this even if you have -rearranged the stack in the meanwhile. This is not so much of a problem -with other editing commands, though, such as @kbd{s e} -(@code{calc-edit-variable}; @pxref{Operations on Variables}). - -If the @code{calc-edit} command involves more than one stack entry, -each line of the @samp{*Calc Edit*} buffer is interpreted as a -separate formula. Otherwise, the entire buffer is interpreted as -one formula, with line breaks ignored. (You can use @kbd{C-o} or -@kbd{C-q C-j} to insert a newline in the buffer without pressing @key{RET}.) - -The @kbd{`} key also works during numeric or algebraic entry. The -text entered so far is moved to the @code{*Calc Edit*} buffer for -more extensive editing than is convenient in the minibuffer. - -@node Trail Commands, Keep Arguments, Editing Stack Entries, Stack and Trail -@section Trail Commands - -@noindent -@cindex Trail buffer -The commands for manipulating the Calc Trail buffer are two-key sequences -beginning with the @kbd{t} prefix. - -@kindex t d -@pindex calc-trail-display -The @kbd{t d} (@code{calc-trail-display}) command turns display of the -trail on and off. Normally the trail display is toggled on if it was off, -off if it was on. With a numeric prefix of zero, this command always -turns the trail off; with a prefix of one, it always turns the trail on. -The other trail-manipulation commands described here automatically turn -the trail on. Note that when the trail is off values are still recorded -there; they are simply not displayed. To set Emacs to turn the trail -off by default, type @kbd{t d} and then save the mode settings with -@kbd{m m} (@code{calc-save-modes}). - -@kindex t i -@pindex calc-trail-in -@kindex t o -@pindex calc-trail-out -The @kbd{t i} (@code{calc-trail-in}) and @kbd{t o} -(@code{calc-trail-out}) commands switch the cursor into and out of the -Calc Trail window. In practice they are rarely used, since the commands -shown below are a more convenient way to move around in the -trail, and they work ``by remote control'' when the cursor is still -in the Calculator window. - -@cindex Trail pointer -There is a @dfn{trail pointer} which selects some entry of the trail at -any given time. The trail pointer looks like a @samp{>} symbol right -before the selected number. The following commands operate on the -trail pointer in various ways. - -@kindex t y -@pindex calc-trail-yank -@cindex Retrieving previous results -The @kbd{t y} (@code{calc-trail-yank}) command reads the selected value in -the trail and pushes it onto the Calculator stack. It allows you to -re-use any previously computed value without retyping. With a numeric -prefix argument @var{n}, it yanks the value @var{n} lines above the current -trail pointer. - -@kindex t < -@pindex calc-trail-scroll-left -@kindex t > -@pindex calc-trail-scroll-right -The @kbd{t <} (@code{calc-trail-scroll-left}) and @kbd{t >} -(@code{calc-trail-scroll-right}) commands horizontally scroll the trail -window left or right by one half of its width. - -@kindex t n -@pindex calc-trail-next -@kindex t p -@pindex calc-trail-previous -@kindex t f -@pindex calc-trail-forward -@kindex t b -@pindex calc-trail-backward -The @kbd{t n} (@code{calc-trail-next}) and @kbd{t p} -(@code{calc-trail-previous)} commands move the trail pointer down or up -one line. The @kbd{t f} (@code{calc-trail-forward}) and @kbd{t b} -(@code{calc-trail-backward}) commands move the trail pointer down or up -one screenful at a time. All of these commands accept numeric prefix -arguments to move several lines or screenfuls at a time. - -@kindex t [ -@pindex calc-trail-first -@kindex t ] -@pindex calc-trail-last -@kindex t h -@pindex calc-trail-here -The @kbd{t [} (@code{calc-trail-first}) and @kbd{t ]} -(@code{calc-trail-last}) commands move the trail pointer to the first or -last line of the trail. The @kbd{t h} (@code{calc-trail-here}) command -moves the trail pointer to the cursor position; unlike the other trail -commands, @kbd{t h} works only when Calc Trail is the selected window. - -@kindex t s -@pindex calc-trail-isearch-forward -@kindex t r -@pindex calc-trail-isearch-backward -@ifnottex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) commands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end ifnottex -@tex -The @kbd{t s} (@code{calc-trail-isearch-forward}) and @kbd{t r} -(@code{calc-trail-isearch-backward}) com\-mands perform an incremental -search forward or backward through the trail. You can press @key{RET} -to terminate the search; the trail pointer moves to the current line. -If you cancel the search with @kbd{C-g}, the trail pointer stays where -it was when the search began. -@end tex - -@kindex t m -@pindex calc-trail-marker -The @kbd{t m} (@code{calc-trail-marker}) command allows you to enter a -line of text of your own choosing into the trail. The text is inserted -after the line containing the trail pointer; this usually means it is -added to the end of the trail. Trail markers are useful mainly as the -targets for later incremental searches in the trail. - -@kindex t k -@pindex calc-trail-kill -The @kbd{t k} (@code{calc-trail-kill}) command removes the selected line -from the trail. The line is saved in the Emacs kill ring suitable for -yanking into another buffer, but it is not easy to yank the text back -into the trail buffer. With a numeric prefix argument, this command -kills the @var{n} lines below or above the selected one. - -The @kbd{t .} (@code{calc-full-trail-vectors}) command is described -elsewhere; @pxref{Vector and Matrix Formats}. - -@node Keep Arguments, , Trail Commands, Stack and Trail -@section Keep Arguments - -@noindent -@kindex K -@pindex calc-keep-args -The @kbd{K} (@code{calc-keep-args}) command acts like a prefix for -the following command. It prevents that command from removing its -arguments from the stack. For example, after @kbd{2 @key{RET} 3 +}, -the stack contains the sole number 5, but after @kbd{2 @key{RET} 3 K +}, -the stack contains the arguments and the result: @samp{2 3 5}. - -With the exception of keyboard macros, this works for all commands that -take arguments off the stack. (To avoid potentially unpleasant behavior, -a @kbd{K} prefix before a keyboard macro will be ignored. A @kbd{K} -prefix called @emph{within} the keyboard macro will still take effect.) -As another example, @kbd{K a s} simplifies a formula, pushing the -simplified version of the formula onto the stack after the original -formula (rather than replacing the original formula). Note that you -could get the same effect by typing @kbd{@key{RET} a s}, copying the -formula and then simplifying the copy. One difference is that for a very -large formula the time taken to format the intermediate copy in -@kbd{@key{RET} a s} could be noticeable; @kbd{K a s} would avoid this -extra work. - -Even stack manipulation commands are affected. @key{TAB} works by -popping two values and pushing them back in the opposite order, -so @kbd{2 @key{RET} 3 K @key{TAB}} produces @samp{2 3 3 2}. - -A few Calc commands provide other ways of doing the same thing. -For example, @kbd{' sin($)} replaces the number on the stack with -its sine using algebraic entry; to push the sine and keep the -original argument you could use either @kbd{' sin($1)} or -@kbd{K ' sin($)}. @xref{Algebraic Entry}. Also, the @kbd{s s} -command is effectively the same as @kbd{K s t}. @xref{Storing Variables}. - -If you execute a command and then decide you really wanted to keep -the argument, you can press @kbd{M-@key{RET}} (@code{calc-last-args}). -This command pushes the last arguments that were popped by any command -onto the stack. Note that the order of things on the stack will be -different than with @kbd{K}: @kbd{2 @key{RET} 3 + M-@key{RET}} leaves -@samp{5 2 3} on the stack instead of @samp{2 3 5}. @xref{Undo}. - -@node Mode Settings, Arithmetic, Stack and Trail, Top -@chapter Mode Settings - -@noindent -This chapter describes commands that set modes in the Calculator. -They do not affect the contents of the stack, although they may change -the @emph{appearance} or @emph{interpretation} of the stack's contents. - -@menu -* General Mode Commands:: -* Precision:: -* Inverse and Hyperbolic:: -* Calculation Modes:: -* Simplification Modes:: -* Declarations:: -* Display Modes:: -* Language Modes:: -* Modes Variable:: -* Calc Mode Line:: -@end menu - -@node General Mode Commands, Precision, Mode Settings, Mode Settings -@section General Mode Commands - -@noindent -@kindex m m -@pindex calc-save-modes -@cindex Continuous memory -@cindex Saving mode settings -@cindex Permanent mode settings -@cindex Calc init file, mode settings -You can save all of the current mode settings in your Calc init file -(the file given by the variable @code{calc-settings-file}, typically -@file{~/.calc.el}) with the @kbd{m m} (@code{calc-save-modes}) command. -This will cause Emacs to reestablish these modes each time it starts up. -The modes saved in the file include everything controlled by the @kbd{m} -and @kbd{d} prefix keys, the current precision and binary word size, -whether or not the trail is displayed, the current height of the Calc -window, and more. The current interface (used when you type @kbd{C-x * *}) -is also saved. If there were already saved mode settings in the -file, they are replaced. Otherwise, the new mode information is -appended to the end of the file. - -@kindex m R -@pindex calc-mode-record-mode -The @kbd{m R} (@code{calc-mode-record-mode}) command tells Calc to -record all the mode settings (as if by pressing @kbd{m m}) every -time a mode setting changes. If the modes are saved this way, then this -``automatic mode recording'' mode is also saved. -Type @kbd{m R} again to disable this method of recording the mode -settings. To turn it off permanently, the @kbd{m m} command will also be -necessary. (If Embedded mode is enabled, other options for recording -the modes are available; @pxref{Mode Settings in Embedded Mode}.) - -@kindex m F -@pindex calc-settings-file-name -The @kbd{m F} (@code{calc-settings-file-name}) command allows you to -choose a different file than the current value of @code{calc-settings-file} -for @kbd{m m}, @kbd{Z P}, and similar commands to save permanent information. -You are prompted for a file name. All Calc modes are then reset to -their default values, then settings from the file you named are loaded -if this file exists, and this file becomes the one that Calc will -use in the future for commands like @kbd{m m}. The default settings -file name is @file{~/.calc.el}. You can see the current file name by -giving a blank response to the @kbd{m F} prompt. See also the -discussion of the @code{calc-settings-file} variable; @pxref{Customizing Calc}. - -If the file name you give is your user init file (typically -@file{~/.emacs}), @kbd{m F} will not automatically load the new file. This -is because your user init file may contain other things you don't want -to reread. You can give -a numeric prefix argument of 1 to @kbd{m F} to force it to read the -file no matter what. Conversely, an argument of @mathit{-1} tells -@kbd{m F} @emph{not} to read the new file. An argument of 2 or @mathit{-2} -tells @kbd{m F} not to reset the modes to their defaults beforehand, -which is useful if you intend your new file to have a variant of the -modes present in the file you were using before. - -@kindex m x -@pindex calc-always-load-extensions -The @kbd{m x} (@code{calc-always-load-extensions}) command enables a mode -in which the first use of Calc loads the entire program, including all -extensions modules. Otherwise, the extensions modules will not be loaded -until the various advanced Calc features are used. Since this mode only -has effect when Calc is first loaded, @kbd{m x} is usually followed by -@kbd{m m} to make the mode-setting permanent. To load all of Calc just -once, rather than always in the future, you can press @kbd{C-x * L}. - -@kindex m S -@pindex calc-shift-prefix -The @kbd{m S} (@code{calc-shift-prefix}) command enables a mode in which -all of Calc's letter prefix keys may be typed shifted as well as unshifted. -If you are typing, say, @kbd{a S} (@code{calc-solve-for}) quite often -you might find it easier to turn this mode on so that you can type -@kbd{A S} instead. When this mode is enabled, the commands that used to -be on those single shifted letters (e.g., @kbd{A} (@code{calc-abs})) can -now be invoked by pressing the shifted letter twice: @kbd{A A}. Note -that the @kbd{v} prefix key always works both shifted and unshifted, and -the @kbd{z} and @kbd{Z} prefix keys are always distinct. Also, the @kbd{h} -prefix is not affected by this mode. Press @kbd{m S} again to disable -shifted-prefix mode. - -@node Precision, Inverse and Hyperbolic, General Mode Commands, Mode Settings -@section Precision - -@noindent -@kindex p -@pindex calc-precision -@cindex Precision of calculations -The @kbd{p} (@code{calc-precision}) command controls the precision to -which floating-point calculations are carried. The precision must be -at least 3 digits and may be arbitrarily high, within the limits of -memory and time. This affects only floats: Integer and rational -calculations are always carried out with as many digits as necessary. - -The @kbd{p} key prompts for the current precision. If you wish you -can instead give the precision as a numeric prefix argument. - -Many internal calculations are carried to one or two digits higher -precision than normal. Results are rounded down afterward to the -current precision. Unless a special display mode has been selected, -floats are always displayed with their full stored precision, i.e., -what you see is what you get. Reducing the current precision does not -round values already on the stack, but those values will be rounded -down before being used in any calculation. The @kbd{c 0} through -@kbd{c 9} commands (@pxref{Conversions}) can be used to round an -existing value to a new precision. - -@cindex Accuracy of calculations -It is important to distinguish the concepts of @dfn{precision} and -@dfn{accuracy}. In the normal usage of these words, the number -123.4567 has a precision of 7 digits but an accuracy of 4 digits. -The precision is the total number of digits not counting leading -or trailing zeros (regardless of the position of the decimal point). -The accuracy is simply the number of digits after the decimal point -(again not counting trailing zeros). In Calc you control the precision, -not the accuracy of computations. If you were to set the accuracy -instead, then calculations like @samp{exp(100)} would generate many -more digits than you would typically need, while @samp{exp(-100)} would -probably round to zero! In Calc, both these computations give you -exactly 12 (or the requested number of) significant digits. - -The only Calc features that deal with accuracy instead of precision -are fixed-point display mode for floats (@kbd{d f}; @pxref{Float Formats}), -and the rounding functions like @code{floor} and @code{round} -(@pxref{Integer Truncation}). Also, @kbd{c 0} through @kbd{c 9} -deal with both precision and accuracy depending on the magnitudes -of the numbers involved. - -If you need to work with a particular fixed accuracy (say, dollars and -cents with two digits after the decimal point), one solution is to work -with integers and an ``implied'' decimal point. For example, $8.99 -divided by 6 would be entered @kbd{899 @key{RET} 6 /}, yielding 149.833 -(actually $1.49833 with our implied decimal point); pressing @kbd{R} -would round this to 150 cents, i.e., $1.50. - -@xref{Floats}, for still more on floating-point precision and related -issues. - -@node Inverse and Hyperbolic, Calculation Modes, Precision, Mode Settings -@section Inverse and Hyperbolic Flags - -@noindent -@kindex I -@pindex calc-inverse -There is no single-key equivalent to the @code{calc-arcsin} function. -Instead, you must first press @kbd{I} (@code{calc-inverse}) to set -the @dfn{Inverse Flag}, then press @kbd{S} (@code{calc-sin}). -The @kbd{I} key actually toggles the Inverse Flag. When this flag -is set, the word @samp{Inv} appears in the mode line. - -@kindex H -@pindex calc-hyperbolic -Likewise, the @kbd{H} key (@code{calc-hyperbolic}) sets or clears the -Hyperbolic Flag, which transforms @code{calc-sin} into @code{calc-sinh}. -If both of these flags are set at once, the effect will be -@code{calc-arcsinh}. (The Hyperbolic flag is also used by some -non-trigonometric commands; for example @kbd{H L} computes a base-10, -instead of base-@mathit{e}, logarithm.) - -Command names like @code{calc-arcsin} are provided for completeness, and -may be executed with @kbd{x} or @kbd{M-x}. Their effect is simply to -toggle the Inverse and/or Hyperbolic flags and then execute the -corresponding base command (@code{calc-sin} in this case). - -The Inverse and Hyperbolic flags apply only to the next Calculator -command, after which they are automatically cleared. (They are also -cleared if the next keystroke is not a Calc command.) Digits you -type after @kbd{I} or @kbd{H} (or @kbd{K}) are treated as prefix -arguments for the next command, not as numeric entries. The same -is true of @kbd{C-u}, but not of the minus sign (@kbd{K -} means to -subtract and keep arguments). - -The third Calc prefix flag, @kbd{K} (keep-arguments), is discussed -elsewhere. @xref{Keep Arguments}. - -@node Calculation Modes, Simplification Modes, Inverse and Hyperbolic, Mode Settings -@section Calculation Modes - -@noindent -The commands in this section are two-key sequences beginning with -the @kbd{m} prefix. (That's the letter @kbd{m}, not the @key{META} key.) -The @samp{m a} (@code{calc-algebraic-mode}) command is described elsewhere -(@pxref{Algebraic Entry}). - -@menu -* Angular Modes:: -* Polar Mode:: -* Fraction Mode:: -* Infinite Mode:: -* Symbolic Mode:: -* Matrix Mode:: -* Automatic Recomputation:: -* Working Message:: -@end menu - -@node Angular Modes, Polar Mode, Calculation Modes, Calculation Modes -@subsection Angular Modes - -@noindent -@cindex Angular mode -The Calculator supports three notations for angles: radians, degrees, -and degrees-minutes-seconds. When a number is presented to a function -like @code{sin} that requires an angle, the current angular mode is -used to interpret the number as either radians or degrees. If an HMS -form is presented to @code{sin}, it is always interpreted as -degrees-minutes-seconds. - -Functions that compute angles produce a number in radians, a number in -degrees, or an HMS form depending on the current angular mode. If the -result is a complex number and the current mode is HMS, the number is -instead expressed in degrees. (Complex-number calculations would -normally be done in Radians mode, though. Complex numbers are converted -to degrees by calculating the complex result in radians and then -multiplying by 180 over @cpi{}.) - -@kindex m r -@pindex calc-radians-mode -@kindex m d -@pindex calc-degrees-mode -@kindex m h -@pindex calc-hms-mode -The @kbd{m r} (@code{calc-radians-mode}), @kbd{m d} (@code{calc-degrees-mode}), -and @kbd{m h} (@code{calc-hms-mode}) commands control the angular mode. -The current angular mode is displayed on the Emacs mode line. -The default angular mode is Degrees. - -@node Polar Mode, Fraction Mode, Angular Modes, Calculation Modes -@subsection Polar Mode - -@noindent -@cindex Polar mode -The Calculator normally ``prefers'' rectangular complex numbers in the -sense that rectangular form is used when the proper form can not be -decided from the input. This might happen by multiplying a rectangular -number by a polar one, by taking the square root of a negative real -number, or by entering @kbd{( 2 @key{SPC} 3 )}. - -@kindex m p -@pindex calc-polar-mode -The @kbd{m p} (@code{calc-polar-mode}) command toggles complex-number -preference between rectangular and polar forms. In Polar mode, all -of the above example situations would produce polar complex numbers. - -@node Fraction Mode, Infinite Mode, Polar Mode, Calculation Modes -@subsection Fraction Mode - -@noindent -@cindex Fraction mode -@cindex Division of integers -Division of two integers normally yields a floating-point number if the -result cannot be expressed as an integer. In some cases you would -rather get an exact fractional answer. One way to accomplish this is -to use the @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command, which -divides the two integers on the top of the stack to produce a fraction: -@kbd{6 @key{RET} 4 :} produces @expr{3:2} even though -@kbd{6 @key{RET} 4 /} produces @expr{1.5}. - -@kindex m f -@pindex calc-frac-mode -To set the Calculator to produce fractional results for normal integer -divisions, use the @kbd{m f} (@code{calc-frac-mode}) command. -For example, @expr{8/4} produces @expr{2} in either mode, -but @expr{6/4} produces @expr{3:2} in Fraction mode, @expr{1.5} in -Float mode. - -At any time you can use @kbd{c f} (@code{calc-float}) to convert a -fraction to a float, or @kbd{c F} (@code{calc-fraction}) to convert a -float to a fraction. @xref{Conversions}. - -@node Infinite Mode, Symbolic Mode, Fraction Mode, Calculation Modes -@subsection Infinite Mode - -@noindent -@cindex Infinite mode -The Calculator normally treats results like @expr{1 / 0} as errors; -formulas like this are left in unsimplified form. But Calc can be -put into a mode where such calculations instead produce ``infinite'' -results. - -@kindex m i -@pindex calc-infinite-mode -The @kbd{m i} (@code{calc-infinite-mode}) command turns this mode -on and off. When the mode is off, infinities do not arise except -in calculations that already had infinities as inputs. (One exception -is that infinite open intervals like @samp{[0 .. inf)} can be -generated; however, intervals closed at infinity (@samp{[0 .. inf]}) -will not be generated when Infinite mode is off.) - -With Infinite mode turned on, @samp{1 / 0} will generate @code{uinf}, -an undirected infinity. @xref{Infinities}, for a discussion of the -difference between @code{inf} and @code{uinf}. Also, @expr{0 / 0} -evaluates to @code{nan}, the ``indeterminate'' symbol. Various other -functions can also return infinities in this mode; for example, -@samp{ln(0) = -inf}, and @samp{gamma(-7) = uinf}. Once again, -note that @samp{exp(inf) = inf} regardless of Infinite mode because -this calculation has infinity as an input. - -@cindex Positive Infinite mode -The @kbd{m i} command with a numeric prefix argument of zero, -i.e., @kbd{C-u 0 m i}, turns on a Positive Infinite mode in -which zero is treated as positive instead of being directionless. -Thus, @samp{1 / 0 = inf} and @samp{-1 / 0 = -inf} in this mode. -Note that zero never actually has a sign in Calc; there are no -separate representations for @mathit{+0} and @mathit{-0}. Positive -Infinite mode merely changes the interpretation given to the -single symbol, @samp{0}. One consequence of this is that, while -you might expect @samp{1 / -0 = -inf}, actually @samp{1 / -0} -is equivalent to @samp{1 / 0}, which is equal to positive @code{inf}. - -@node Symbolic Mode, Matrix Mode, Infinite Mode, Calculation Modes -@subsection Symbolic Mode - -@noindent -@cindex Symbolic mode -@cindex Inexact results -Calculations are normally performed numerically wherever possible. -For example, the @code{calc-sqrt} command, or @code{sqrt} function in an -algebraic expression, produces a numeric answer if the argument is a -number or a symbolic expression if the argument is an expression: -@kbd{2 Q} pushes 1.4142 but @kbd{@key{'} x+1 @key{RET} Q} pushes @samp{sqrt(x+1)}. - -@kindex m s -@pindex calc-symbolic-mode -In @dfn{Symbolic mode}, controlled by the @kbd{m s} (@code{calc-symbolic-mode}) -command, functions which would produce inexact, irrational results are -left in symbolic form. Thus @kbd{16 Q} pushes 4, but @kbd{2 Q} pushes -@samp{sqrt(2)}. - -@kindex N -@pindex calc-eval-num -The shift-@kbd{N} (@code{calc-eval-num}) command evaluates numerically -the expression at the top of the stack, by temporarily disabling -@code{calc-symbolic-mode} and executing @kbd{=} (@code{calc-evaluate}). -Given a numeric prefix argument, it also -sets the floating-point precision to the specified value for the duration -of the command. - -To evaluate a formula numerically without expanding the variables it -contains, you can use the key sequence @kbd{m s a v m s} (this uses -@code{calc-alg-evaluate}, which resimplifies but doesn't evaluate -variables.) - -@node Matrix Mode, Automatic Recomputation, Symbolic Mode, Calculation Modes -@subsection Matrix and Scalar Modes - -@noindent -@cindex Matrix mode -@cindex Scalar mode -Calc sometimes makes assumptions during algebraic manipulation that -are awkward or incorrect when vectors and matrices are involved. -Calc has two modes, @dfn{Matrix mode} and @dfn{Scalar mode}, which -modify its behavior around vectors in useful ways. - -@kindex m v -@pindex calc-matrix-mode -Press @kbd{m v} (@code{calc-matrix-mode}) once to enter Matrix mode. -In this mode, all objects are assumed to be matrices unless provably -otherwise. One major effect is that Calc will no longer consider -multiplication to be commutative. (Recall that in matrix arithmetic, -@samp{A*B} is not the same as @samp{B*A}.) This assumption affects -rewrite rules and algebraic simplification. Another effect of this -mode is that calculations that would normally produce constants like -0 and 1 (e.g., @expr{a - a} and @expr{a / a}, respectively) will now -produce function calls that represent ``generic'' zero or identity -matrices: @samp{idn(0)}, @samp{idn(1)}. The @code{idn} function -@samp{idn(@var{a},@var{n})} returns @var{a} times an @var{n}x@var{n} -identity matrix; if @var{n} is omitted, it doesn't know what -dimension to use and so the @code{idn} call remains in symbolic -form. However, if this generic identity matrix is later combined -with a matrix whose size is known, it will be converted into -a true identity matrix of the appropriate size. On the other hand, -if it is combined with a scalar (as in @samp{idn(1) + 2}), Calc -will assume it really was a scalar after all and produce, e.g., 3. - -Press @kbd{m v} a second time to get Scalar mode. Here, objects are -assumed @emph{not} to be vectors or matrices unless provably so. -For example, normally adding a variable to a vector, as in -@samp{[x, y, z] + a}, will leave the sum in symbolic form because -as far as Calc knows, @samp{a} could represent either a number or -another 3-vector. In Scalar mode, @samp{a} is assumed to be a -non-vector, and the addition is evaluated to @samp{[x+a, y+a, z+a]}. - -Press @kbd{m v} a third time to return to the normal mode of operation. - -If you press @kbd{m v} with a numeric prefix argument @var{n}, you -get a special ``dimensioned'' Matrix mode in which matrices of -unknown size are assumed to be @var{n}x@var{n} square matrices. -Then, the function call @samp{idn(1)} will expand into an actual -matrix rather than representing a ``generic'' matrix. Simply typing -@kbd{C-u m v} will get you a square Matrix mode, in which matrices of -unknown size are assumed to be square matrices of unspecified size. - -@cindex Declaring scalar variables -Of course these modes are approximations to the true state of -affairs, which is probably that some quantities will be matrices -and others will be scalars. One solution is to ``declare'' -certain variables or functions to be scalar-valued. -@xref{Declarations}, to see how to make declarations in Calc. - -There is nothing stopping you from declaring a variable to be -scalar and then storing a matrix in it; however, if you do, the -results you get from Calc may not be valid. Suppose you let Calc -get the result @samp{[x+a, y+a, z+a]} shown above, and then stored -@samp{[1, 2, 3]} in @samp{a}. The result would not be the same as -for @samp{[x, y, z] + [1, 2, 3]}, but that's because you have broken -your earlier promise to Calc that @samp{a} would be scalar. - -Another way to mix scalars and matrices is to use selections -(@pxref{Selecting Subformulas}). Use Matrix mode when operating on -your formula normally; then, to apply Scalar mode to a certain part -of the formula without affecting the rest just select that part, -change into Scalar mode and press @kbd{=} to resimplify the part -under this mode, then change back to Matrix mode before deselecting. - -@node Automatic Recomputation, Working Message, Matrix Mode, Calculation Modes -@subsection Automatic Recomputation - -@noindent -The @dfn{evaluates-to} operator, @samp{=>}, has the special -property that any @samp{=>} formulas on the stack are recomputed -whenever variable values or mode settings that might affect them -are changed. @xref{Evaluates-To Operator}. - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command turns this -automatic recomputation on and off. If you turn it off, Calc will -not update @samp{=>} operators on the stack (nor those in the -attached Embedded mode buffer, if there is one). They will not -be updated unless you explicitly do so by pressing @kbd{=} or until -you press @kbd{m C} to turn recomputation back on. (While automatic -recomputation is off, you can think of @kbd{m C m C} as a command -to update all @samp{=>} operators while leaving recomputation off.) - -To update @samp{=>} operators in an Embedded buffer while -automatic recomputation is off, use @w{@kbd{C-x * u}}. -@xref{Embedded Mode}. - -@node Working Message, , Automatic Recomputation, Calculation Modes -@subsection Working Messages - -@noindent -@cindex Performance -@cindex Working messages -Since the Calculator is written entirely in Emacs Lisp, which is not -designed for heavy numerical work, many operations are quite slow. -The Calculator normally displays the message @samp{Working...} in the -echo area during any command that may be slow. In addition, iterative -operations such as square roots and trigonometric functions display the -intermediate result at each step. Both of these types of messages can -be disabled if you find them distracting. - -@kindex m w -@pindex calc-working -Type @kbd{m w} (@code{calc-working}) with a numeric prefix of 0 to -disable all ``working'' messages. Use a numeric prefix of 1 to enable -only the plain @samp{Working...} message. Use a numeric prefix of 2 to -see intermediate results as well. With no numeric prefix this displays -the current mode. - -While it may seem that the ``working'' messages will slow Calc down -considerably, experiments have shown that their impact is actually -quite small. But if your terminal is slow you may find that it helps -to turn the messages off. - -@node Simplification Modes, Declarations, Calculation Modes, Mode Settings -@section Simplification Modes - -@noindent -The current @dfn{simplification mode} controls how numbers and formulas -are ``normalized'' when being taken from or pushed onto the stack. -Some normalizations are unavoidable, such as rounding floating-point -results to the current precision, and reducing fractions to simplest -form. Others, such as simplifying a formula like @expr{a+a} (or @expr{2+3}), -are done by default but can be turned off when necessary. - -When you press a key like @kbd{+} when @expr{2} and @expr{3} are on the -stack, Calc pops these numbers, normalizes them, creates the formula -@expr{2+3}, normalizes it, and pushes the result. Of course the standard -rules for normalizing @expr{2+3} will produce the result @expr{5}. - -Simplification mode commands consist of the lower-case @kbd{m} prefix key -followed by a shifted letter. - -@kindex m O -@pindex calc-no-simplify-mode -The @kbd{m O} (@code{calc-no-simplify-mode}) command turns off all optional -simplifications. These would leave a formula like @expr{2+3} alone. In -fact, nothing except simple numbers are ever affected by normalization -in this mode. - -@kindex m N -@pindex calc-num-simplify-mode -The @kbd{m N} (@code{calc-num-simplify-mode}) command turns off simplification -of any formulas except those for which all arguments are constants. For -example, @expr{1+2} is simplified to @expr{3}, and @expr{a+(2-2)} is -simplified to @expr{a+0} but no further, since one argument of the sum -is not a constant. Unfortunately, @expr{(a+2)-2} is @emph{not} simplified -because the top-level @samp{-} operator's arguments are not both -constant numbers (one of them is the formula @expr{a+2}). -A constant is a number or other numeric object (such as a constant -error form or modulo form), or a vector all of whose -elements are constant. - -@kindex m D -@pindex calc-default-simplify-mode -The @kbd{m D} (@code{calc-default-simplify-mode}) command restores the -default simplifications for all formulas. This includes many easy and -fast algebraic simplifications such as @expr{a+0} to @expr{a}, and -@expr{a + 2 a} to @expr{3 a}, as well as evaluating functions like -@expr{@tfn{deriv}(x^2, x)} to @expr{2 x}. - -@kindex m B -@pindex calc-bin-simplify-mode -The @kbd{m B} (@code{calc-bin-simplify-mode}) mode applies the default -simplifications to a result and then, if the result is an integer, -uses the @kbd{b c} (@code{calc-clip}) command to clip the integer according -to the current binary word size. @xref{Binary Functions}. Real numbers -are rounded to the nearest integer and then clipped; other kinds of -results (after the default simplifications) are left alone. - -@kindex m A -@pindex calc-alg-simplify-mode -The @kbd{m A} (@code{calc-alg-simplify-mode}) mode does algebraic -simplification; it applies all the default simplifications, and also -the more powerful (and slower) simplifications made by @kbd{a s} -(@code{calc-simplify}). @xref{Algebraic Simplifications}. - -@kindex m E -@pindex calc-ext-simplify-mode -The @kbd{m E} (@code{calc-ext-simplify-mode}) mode does ``extended'' -algebraic simplification, as by the @kbd{a e} (@code{calc-simplify-extended}) -command. @xref{Unsafe Simplifications}. - -@kindex m U -@pindex calc-units-simplify-mode -The @kbd{m U} (@code{calc-units-simplify-mode}) mode does units -simplification; it applies the command @kbd{u s} -(@code{calc-simplify-units}), which in turn -is a superset of @kbd{a s}. In this mode, variable names which -are identifiable as unit names (like @samp{mm} for ``millimeters'') -are simplified with their unit definitions in mind. - -A common technique is to set the simplification mode down to the lowest -amount of simplification you will allow to be applied automatically, then -use manual commands like @kbd{a s} and @kbd{c c} (@code{calc-clean}) to -perform higher types of simplifications on demand. @xref{Algebraic -Definitions}, for another sample use of No-Simplification mode. - -@node Declarations, Display Modes, Simplification Modes, Mode Settings -@section Declarations - -@noindent -A @dfn{declaration} is a statement you make that promises you will -use a certain variable or function in a restricted way. This may -give Calc the freedom to do things that it couldn't do if it had to -take the fully general situation into account. - -@menu -* Declaration Basics:: -* Kinds of Declarations:: -* Functions for Declarations:: -@end menu - -@node Declaration Basics, Kinds of Declarations, Declarations, Declarations -@subsection Declaration Basics - -@noindent -@kindex s d -@pindex calc-declare-variable -The @kbd{s d} (@code{calc-declare-variable}) command is the easiest -way to make a declaration for a variable. This command prompts for -the variable name, then prompts for the declaration. The default -at the declaration prompt is the previous declaration, if any. -You can edit this declaration, or press @kbd{C-k} to erase it and -type a new declaration. (Or, erase it and press @key{RET} to clear -the declaration, effectively ``undeclaring'' the variable.) - -A declaration is in general a vector of @dfn{type symbols} and -@dfn{range} values. If there is only one type symbol or range value, -you can write it directly rather than enclosing it in a vector. -For example, @kbd{s d foo @key{RET} real @key{RET}} declares @code{foo} to -be a real number, and @kbd{s d bar @key{RET} [int, const, [1..6]] @key{RET}} -declares @code{bar} to be a constant integer between 1 and 6. -(Actually, you can omit the outermost brackets and Calc will -provide them for you: @kbd{s d bar @key{RET} int, const, [1..6] @key{RET}}.) - -@cindex @code{Decls} variable -@vindex Decls -Declarations in Calc are kept in a special variable called @code{Decls}. -This variable encodes the set of all outstanding declarations in -the form of a matrix. Each row has two elements: A variable or -vector of variables declared by that row, and the declaration -specifier as described above. You can use the @kbd{s D} command to -edit this variable if you wish to see all the declarations at once. -@xref{Operations on Variables}, for a description of this command -and the @kbd{s p} command that allows you to save your declarations -permanently if you wish. - -Items being declared can also be function calls. The arguments in -the call are ignored; the effect is to say that this function returns -values of the declared type for any valid arguments. The @kbd{s d} -command declares only variables, so if you wish to make a function -declaration you will have to edit the @code{Decls} matrix yourself. - -For example, the declaration matrix - -@smallexample -@group -[ [ foo, real ] - [ [j, k, n], int ] - [ f(1,2,3), [0 .. inf) ] ] -@end group -@end smallexample - -@noindent -declares that @code{foo} represents a real number, @code{j}, @code{k} -and @code{n} represent integers, and the function @code{f} always -returns a real number in the interval shown. - -@vindex All -If there is a declaration for the variable @code{All}, then that -declaration applies to all variables that are not otherwise declared. -It does not apply to function names. For example, using the row -@samp{[All, real]} says that all your variables are real unless they -are explicitly declared without @code{real} in some other row. -The @kbd{s d} command declares @code{All} if you give a blank -response to the variable-name prompt. - -@node Kinds of Declarations, Functions for Declarations, Declaration Basics, Declarations -@subsection Kinds of Declarations - -@noindent -The type-specifier part of a declaration (that is, the second prompt -in the @kbd{s d} command) can be a type symbol, an interval, or a -vector consisting of zero or more type symbols followed by zero or -more intervals or numbers that represent the set of possible values -for the variable. - -@smallexample -@group -[ [ a, [1, 2, 3, 4, 5] ] - [ b, [1 .. 5] ] - [ c, [int, 1 .. 5] ] ] -@end group -@end smallexample - -Here @code{a} is declared to contain one of the five integers shown; -@code{b} is any number in the interval from 1 to 5 (any real number -since we haven't specified), and @code{c} is any integer in that -interval. Thus the declarations for @code{a} and @code{c} are -nearly equivalent (see below). - -The type-specifier can be the empty vector @samp{[]} to say that -nothing is known about a given variable's value. This is the same -as not declaring the variable at all except that it overrides any -@code{All} declaration which would otherwise apply. - -The initial value of @code{Decls} is the empty vector @samp{[]}. -If @code{Decls} has no stored value or if the value stored in it -is not valid, it is ignored and there are no declarations as far -as Calc is concerned. (The @kbd{s d} command will replace such a -malformed value with a fresh empty matrix, @samp{[]}, before recording -the new declaration.) Unrecognized type symbols are ignored. - -The following type symbols describe what sorts of numbers will be -stored in a variable: - -@table @code -@item int -Integers. -@item numint -Numerical integers. (Integers or integer-valued floats.) -@item frac -Fractions. (Rational numbers which are not integers.) -@item rat -Rational numbers. (Either integers or fractions.) -@item float -Floating-point numbers. -@item real -Real numbers. (Integers, fractions, or floats. Actually, -intervals and error forms with real components also count as -reals here.) -@item pos -Positive real numbers. (Strictly greater than zero.) -@item nonneg -Nonnegative real numbers. (Greater than or equal to zero.) -@item number -Numbers. (Real or complex.) -@end table - -Calc uses this information to determine when certain simplifications -of formulas are safe. For example, @samp{(x^y)^z} cannot be -simplified to @samp{x^(y z)} in general; for example, -@samp{((-3)^2)^1:2} is 3, but @samp{(-3)^(2*1:2) = (-3)^1} is @mathit{-3}. -However, this simplification @emph{is} safe if @code{z} is known -to be an integer, or if @code{x} is known to be a nonnegative -real number. If you have given declarations that allow Calc to -deduce either of these facts, Calc will perform this simplification -of the formula. - -Calc can apply a certain amount of logic when using declarations. -For example, @samp{(x^y)^(2n+1)} will be simplified if @code{n} -has been declared @code{int}; Calc knows that an integer times an -integer, plus an integer, must always be an integer. (In fact, -Calc would simplify @samp{(-x)^(2n+1)} to @samp{-(x^(2n+1))} since -it is able to determine that @samp{2n+1} must be an odd integer.) - -Similarly, @samp{(abs(x)^y)^z} will be simplified to @samp{abs(x)^(y z)} -because Calc knows that the @code{abs} function always returns a -nonnegative real. If you had a @code{myabs} function that also had -this property, you could get Calc to recognize it by adding the row -@samp{[myabs(), nonneg]} to the @code{Decls} matrix. - -One instance of this simplification is @samp{sqrt(x^2)} (since the -@code{sqrt} function is effectively a one-half power). Normally -Calc leaves this formula alone. After the command -@kbd{s d x @key{RET} real @key{RET}}, however, it can simplify the formula to -@samp{abs(x)}. And after @kbd{s d x @key{RET} nonneg @key{RET}}, Calc can -simplify this formula all the way to @samp{x}. - -If there are any intervals or real numbers in the type specifier, -they comprise the set of possible values that the variable or -function being declared can have. In particular, the type symbol -@code{real} is effectively the same as the range @samp{[-inf .. inf]} -(note that infinity is included in the range of possible values); -@code{pos} is the same as @samp{(0 .. inf]}, and @code{nonneg} is -the same as @samp{[0 .. inf]}. Saying @samp{[real, [-5 .. 5]]} is -redundant because the fact that the variable is real can be -deduced just from the interval, but @samp{[int, [-5 .. 5]]} and -@samp{[rat, [-5 .. 5]]} are useful combinations. - -Note that the vector of intervals or numbers is in the same format -used by Calc's set-manipulation commands. @xref{Set Operations}. - -The type specifier @samp{[1, 2, 3]} is equivalent to -@samp{[numint, 1, 2, 3]}, @emph{not} to @samp{[int, 1, 2, 3]}. -In other words, the range of possible values means only that -the variable's value must be numerically equal to a number in -that range, but not that it must be equal in type as well. -Calc's set operations act the same way; @samp{in(2, [1., 2., 3.])} -and @samp{in(1.5, [1:2, 3:2, 5:2])} both report ``true.'' - -If you use a conflicting combination of type specifiers, the -results are unpredictable. An example is @samp{[pos, [0 .. 5]]}, -where the interval does not lie in the range described by the -type symbol. - -``Real'' declarations mostly affect simplifications involving powers -like the one described above. Another case where they are used -is in the @kbd{a P} command which returns a list of all roots of a -polynomial; if the variable has been declared real, only the real -roots (if any) will be included in the list. - -``Integer'' declarations are used for simplifications which are valid -only when certain values are integers (such as @samp{(x^y)^z} -shown above). - -Another command that makes use of declarations is @kbd{a s}, when -simplifying equations and inequalities. It will cancel @code{x} -from both sides of @samp{a x = b x} only if it is sure @code{x} -is non-zero, say, because it has a @code{pos} declaration. -To declare specifically that @code{x} is real and non-zero, -use @samp{[[-inf .. 0), (0 .. inf]]}. (There is no way in the -current notation to say that @code{x} is nonzero but not necessarily -real.) The @kbd{a e} command does ``unsafe'' simplifications, -including cancelling @samp{x} from the equation when @samp{x} is -not known to be nonzero. - -Another set of type symbols distinguish between scalars and vectors. - -@table @code -@item scalar -The value is not a vector. -@item vector -The value is a vector. -@item matrix -The value is a matrix (a rectangular vector of vectors). -@item sqmatrix -The value is a square matrix. -@end table - -These type symbols can be combined with the other type symbols -described above; @samp{[int, matrix]} describes an object which -is a matrix of integers. - -Scalar/vector declarations are used to determine whether certain -algebraic operations are safe. For example, @samp{[a, b, c] + x} -is normally not simplified to @samp{[a + x, b + x, c + x]}, but -it will be if @code{x} has been declared @code{scalar}. On the -other hand, multiplication is usually assumed to be commutative, -but the terms in @samp{x y} will never be exchanged if both @code{x} -and @code{y} are known to be vectors or matrices. (Calc currently -never distinguishes between @code{vector} and @code{matrix} -declarations.) - -@xref{Matrix Mode}, for a discussion of Matrix mode and -Scalar mode, which are similar to declaring @samp{[All, matrix]} -or @samp{[All, scalar]} but much more convenient. - -One more type symbol that is recognized is used with the @kbd{H a d} -command for taking total derivatives of a formula. @xref{Calculus}. - -@table @code -@item const -The value is a constant with respect to other variables. -@end table - -Calc does not check the declarations for a variable when you store -a value in it. However, storing @mathit{-3.5} in a variable that has -been declared @code{pos}, @code{int}, or @code{matrix} may have -unexpected effects; Calc may evaluate @samp{sqrt(x^2)} to @expr{3.5} -if it substitutes the value first, or to @expr{-3.5} if @code{x} -was declared @code{pos} and the formula @samp{sqrt(x^2)} is -simplified to @samp{x} before the value is substituted. Before -using a variable for a new purpose, it is best to use @kbd{s d} -or @kbd{s D} to check to make sure you don't still have an old -declaration for the variable that will conflict with its new meaning. - -@node Functions for Declarations, , Kinds of Declarations, Declarations -@subsection Functions for Declarations - -@noindent -Calc has a set of functions for accessing the current declarations -in a convenient manner. These functions return 1 if the argument -can be shown to have the specified property, or 0 if the argument -can be shown @emph{not} to have that property; otherwise they are -left unevaluated. These functions are suitable for use with rewrite -rules (@pxref{Conditional Rewrite Rules}) or programming constructs -(@pxref{Conditionals in Macros}). They can be entered only using -algebraic notation. @xref{Logical Operations}, for functions -that perform other tests not related to declarations. - -For example, @samp{dint(17)} returns 1 because 17 is an integer, as -do @samp{dint(n)} and @samp{dint(2 n - 3)} if @code{n} has been declared -@code{int}, but @samp{dint(2.5)} and @samp{dint(n + 0.5)} return 0. -Calc consults knowledge of its own built-in functions as well as your -own declarations: @samp{dint(floor(x))} returns 1. - -@ignore -@starindex -@end ignore -@tindex dint -@ignore -@starindex -@end ignore -@tindex dnumint -@ignore -@starindex -@end ignore -@tindex dnatnum -The @code{dint} function checks if its argument is an integer. -The @code{dnatnum} function checks if its argument is a natural -number, i.e., a nonnegative integer. The @code{dnumint} function -checks if its argument is numerically an integer, i.e., either an -integer or an integer-valued float. Note that these and the other -data type functions also accept vectors or matrices composed of -suitable elements, and that real infinities @samp{inf} and @samp{-inf} -are considered to be integers for the purposes of these functions. - -@ignore -@starindex -@end ignore -@tindex drat -The @code{drat} function checks if its argument is rational, i.e., -an integer or fraction. Infinities count as rational, but intervals -and error forms do not. - -@ignore -@starindex -@end ignore -@tindex dreal -The @code{dreal} function checks if its argument is real. This -includes integers, fractions, floats, real error forms, and intervals. - -@ignore -@starindex -@end ignore -@tindex dimag -The @code{dimag} function checks if its argument is imaginary, -i.e., is mathematically equal to a real number times @expr{i}. - -@ignore -@starindex -@end ignore -@tindex dpos -@ignore -@starindex -@end ignore -@tindex dneg -@ignore -@starindex -@end ignore -@tindex dnonneg -The @code{dpos} function checks for positive (but nonzero) reals. -The @code{dneg} function checks for negative reals. The @code{dnonneg} -function checks for nonnegative reals, i.e., reals greater than or -equal to zero. Note that the @kbd{a s} command can simplify an -expression like @expr{x > 0} to 1 or 0 using @code{dpos}, and that -@kbd{a s} is effectively applied to all conditions in rewrite rules, -so the actual functions @code{dpos}, @code{dneg}, and @code{dnonneg} -are rarely necessary. - -@ignore -@starindex -@end ignore -@tindex dnonzero -The @code{dnonzero} function checks that its argument is nonzero. -This includes all nonzero real or complex numbers, all intervals that -do not include zero, all nonzero modulo forms, vectors all of whose -elements are nonzero, and variables or formulas whose values can be -deduced to be nonzero. It does not include error forms, since they -represent values which could be anything including zero. (This is -also the set of objects considered ``true'' in conditional contexts.) - -@ignore -@starindex -@end ignore -@tindex deven -@ignore -@starindex -@end ignore -@tindex dodd -The @code{deven} function returns 1 if its argument is known to be -an even integer (or integer-valued float); it returns 0 if its argument -is known not to be even (because it is known to be odd or a non-integer). -The @kbd{a s} command uses this to simplify a test of the form -@samp{x % 2 = 0}. There is also an analogous @code{dodd} function. - -@ignore -@starindex -@end ignore -@tindex drange -The @code{drange} function returns a set (an interval or a vector -of intervals and/or numbers; @pxref{Set Operations}) that describes -the set of possible values of its argument. If the argument is -a variable or a function with a declaration, the range is copied -from the declaration. Otherwise, the possible signs of the -expression are determined using a method similar to @code{dpos}, -etc., and a suitable set like @samp{[0 .. inf]} is returned. If -the expression is not provably real, the @code{drange} function -remains unevaluated. - -@ignore -@starindex -@end ignore -@tindex dscalar -The @code{dscalar} function returns 1 if its argument is provably -scalar, or 0 if its argument is provably non-scalar. It is left -unevaluated if this cannot be determined. (If Matrix mode or Scalar -mode is in effect, this function returns 1 or 0, respectively, -if it has no other information.) When Calc interprets a condition -(say, in a rewrite rule) it considers an unevaluated formula to be -``false.'' Thus, @samp{dscalar(a)} is ``true'' only if @code{a} is -provably scalar, and @samp{!dscalar(a)} is ``true'' only if @code{a} -is provably non-scalar; both are ``false'' if there is insufficient -information to tell. - -@node Display Modes, Language Modes, Declarations, Mode Settings -@section Display Modes - -@noindent -The commands in this section are two-key sequences beginning with the -@kbd{d} prefix. The @kbd{d l} (@code{calc-line-numbering}) and @kbd{d b} -(@code{calc-line-breaking}) commands are described elsewhere; -@pxref{Stack Basics} and @pxref{Normal Language Modes}, respectively. -Display formats for vectors and matrices are also covered elsewhere; -@pxref{Vector and Matrix Formats}. - -One thing all display modes have in common is their treatment of the -@kbd{H} prefix. This prefix causes any mode command that would normally -refresh the stack to leave the stack display alone. The word ``Dirty'' -will appear in the mode line when Calc thinks the stack display may not -reflect the latest mode settings. - -@kindex d @key{RET} -@pindex calc-refresh-top -The @kbd{d @key{RET}} (@code{calc-refresh-top}) command reformats the -top stack entry according to all the current modes. Positive prefix -arguments reformat the top @var{n} entries; negative prefix arguments -reformat the specified entry, and a prefix of zero is equivalent to -@kbd{d @key{SPC}} (@code{calc-refresh}), which reformats the entire stack. -For example, @kbd{H d s M-2 d @key{RET}} changes to scientific notation -but reformats only the top two stack entries in the new mode. - -The @kbd{I} prefix has another effect on the display modes. The mode -is set only temporarily; the top stack entry is reformatted according -to that mode, then the original mode setting is restored. In other -words, @kbd{I d s} is equivalent to @kbd{H d s d @key{RET} H d (@var{old mode})}. - -@menu -* Radix Modes:: -* Grouping Digits:: -* Float Formats:: -* Complex Formats:: -* Fraction Formats:: -* HMS Formats:: -* Date Formats:: -* Truncating the Stack:: -* Justification:: -* Labels:: -@end menu - -@node Radix Modes, Grouping Digits, Display Modes, Display Modes -@subsection Radix Modes - -@noindent -@cindex Radix display -@cindex Non-decimal numbers -@cindex Decimal and non-decimal numbers -Calc normally displays numbers in decimal (@dfn{base-10} or @dfn{radix-10}) -notation. Calc can actually display in any radix from two (binary) to 36. -When the radix is above 10, the letters @code{A} to @code{Z} are used as -digits. When entering such a number, letter keys are interpreted as -potential digits rather than terminating numeric entry mode. - -@kindex d 2 -@kindex d 8 -@kindex d 6 -@kindex d 0 -@cindex Hexadecimal integers -@cindex Octal integers -The key sequences @kbd{d 2}, @kbd{d 8}, @kbd{d 6}, and @kbd{d 0} select -binary, octal, hexadecimal, and decimal as the current display radix, -respectively. Numbers can always be entered in any radix, though the -current radix is used as a default if you press @kbd{#} without any initial -digits. A number entered without a @kbd{#} is @emph{always} interpreted -as decimal. - -@kindex d r -@pindex calc-radix -To set the radix generally, use @kbd{d r} (@code{calc-radix}) and enter -an integer from 2 to 36. You can specify the radix as a numeric prefix -argument; otherwise you will be prompted for it. - -@kindex d z -@pindex calc-leading-zeros -@cindex Leading zeros -Integers normally are displayed with however many digits are necessary to -represent the integer and no more. The @kbd{d z} (@code{calc-leading-zeros}) -command causes integers to be padded out with leading zeros according to the -current binary word size. (@xref{Binary Functions}, for a discussion of -word size.) If the absolute value of the word size is @expr{w}, all integers -are displayed with at least enough digits to represent -@texline @math{2^w-1} -@infoline @expr{(2^w)-1} -in the current radix. (Larger integers will still be displayed in their -entirety.) - -@node Grouping Digits, Float Formats, Radix Modes, Display Modes -@subsection Grouping Digits - -@noindent -@kindex d g -@pindex calc-group-digits -@cindex Grouping digits -@cindex Digit grouping -Long numbers can be hard to read if they have too many digits. For -example, the factorial of 30 is 33 digits long! Press @kbd{d g} -(@code{calc-group-digits}) to enable @dfn{Grouping} mode, in which digits -are displayed in clumps of 3 or 4 (depending on the current radix) -separated by commas. - -The @kbd{d g} command toggles grouping on and off. -With a numeric prefix of 0, this command displays the current state of -the grouping flag; with an argument of minus one it disables grouping; -with a positive argument @expr{N} it enables grouping on every @expr{N} -digits. For floating-point numbers, grouping normally occurs only -before the decimal point. A negative prefix argument @expr{-N} enables -grouping every @expr{N} digits both before and after the decimal point. - -@kindex d , -@pindex calc-group-char -The @kbd{d ,} (@code{calc-group-char}) command allows you to choose any -character as the grouping separator. The default is the comma character. -If you find it difficult to read vectors of large integers grouped with -commas, you may wish to use spaces or some other character instead. -This command takes the next character you type, whatever it is, and -uses it as the digit separator. As a special case, @kbd{d , \} selects -@samp{\,} (@TeX{}'s thin-space symbol) as the digit separator. - -Please note that grouped numbers will not generally be parsed correctly -if re-read in textual form, say by the use of @kbd{C-x * y} and @kbd{C-x * g}. -(@xref{Kill and Yank}, for details on these commands.) One exception is -the @samp{\,} separator, which doesn't interfere with parsing because it -is ignored by @TeX{} language mode. - -@node Float Formats, Complex Formats, Grouping Digits, Display Modes -@subsection Float Formats - -@noindent -Floating-point quantities are normally displayed in standard decimal -form, with scientific notation used if the exponent is especially high -or low. All significant digits are normally displayed. The commands -in this section allow you to choose among several alternative display -formats for floats. - -@kindex d n -@pindex calc-normal-notation -The @kbd{d n} (@code{calc-normal-notation}) command selects the normal -display format. All significant figures in a number are displayed. -With a positive numeric prefix, numbers are rounded if necessary to -that number of significant digits. With a negative numerix prefix, -the specified number of significant digits less than the current -precision is used. (Thus @kbd{C-u -2 d n} displays 10 digits if the -current precision is 12.) - -@kindex d f -@pindex calc-fix-notation -The @kbd{d f} (@code{calc-fix-notation}) command selects fixed-point -notation. The numeric argument is the number of digits after the -decimal point, zero or more. This format will relax into scientific -notation if a nonzero number would otherwise have been rounded all the -way to zero. Specifying a negative number of digits is the same as -for a positive number, except that small nonzero numbers will be rounded -to zero rather than switching to scientific notation. - -@kindex d s -@pindex calc-sci-notation -@cindex Scientific notation, display of -The @kbd{d s} (@code{calc-sci-notation}) command selects scientific -notation. A positive argument sets the number of significant figures -displayed, of which one will be before and the rest after the decimal -point. A negative argument works the same as for @kbd{d n} format. -The default is to display all significant digits. - -@kindex d e -@pindex calc-eng-notation -@cindex Engineering notation, display of -The @kbd{d e} (@code{calc-eng-notation}) command selects engineering -notation. This is similar to scientific notation except that the -exponent is rounded down to a multiple of three, with from one to three -digits before the decimal point. An optional numeric prefix sets the -number of significant digits to display, as for @kbd{d s}. - -It is important to distinguish between the current @emph{precision} and -the current @emph{display format}. After the commands @kbd{C-u 10 p} -and @kbd{C-u 6 d n} the Calculator computes all results to ten -significant figures but displays only six. (In fact, intermediate -calculations are often carried to one or two more significant figures, -but values placed on the stack will be rounded down to ten figures.) -Numbers are never actually rounded to the display precision for storage, -except by commands like @kbd{C-k} and @kbd{C-x * y} which operate on the -actual displayed text in the Calculator buffer. - -@kindex d . -@pindex calc-point-char -The @kbd{d .} (@code{calc-point-char}) command selects the character used -as a decimal point. Normally this is a period; users in some countries -may wish to change this to a comma. Note that this is only a display -style; on entry, periods must always be used to denote floating-point -numbers, and commas to separate elements in a list. - -@node Complex Formats, Fraction Formats, Float Formats, Display Modes -@subsection Complex Formats - -@noindent -@kindex d c -@pindex calc-complex-notation -There are three supported notations for complex numbers in rectangular -form. The default is as a pair of real numbers enclosed in parentheses -and separated by a comma: @samp{(a,b)}. The @kbd{d c} -(@code{calc-complex-notation}) command selects this style. - -@kindex d i -@pindex calc-i-notation -@kindex d j -@pindex calc-j-notation -The other notations are @kbd{d i} (@code{calc-i-notation}), in which -numbers are displayed in @samp{a+bi} form, and @kbd{d j} -(@code{calc-j-notation}) which displays the form @samp{a+bj} preferred -in some disciplines. - -@cindex @code{i} variable -@vindex i -Complex numbers are normally entered in @samp{(a,b)} format. -If you enter @samp{2+3i} as an algebraic formula, it will be stored as -the formula @samp{2 + 3 * i}. However, if you use @kbd{=} to evaluate -this formula and you have not changed the variable @samp{i}, the @samp{i} -will be interpreted as @samp{(0,1)} and the formula will be simplified -to @samp{(2,3)}. Other commands (like @code{calc-sin}) will @emph{not} -interpret the formula @samp{2 + 3 * i} as a complex number. -@xref{Variables}, under ``special constants.'' - -@node Fraction Formats, HMS Formats, Complex Formats, Display Modes -@subsection Fraction Formats - -@noindent -@kindex d o -@pindex calc-over-notation -Display of fractional numbers is controlled by the @kbd{d o} -(@code{calc-over-notation}) command. By default, a number like -eight thirds is displayed in the form @samp{8:3}. The @kbd{d o} command -prompts for a one- or two-character format. If you give one character, -that character is used as the fraction separator. Common separators are -@samp{:} and @samp{/}. (During input of numbers, the @kbd{:} key must be -used regardless of the display format; in particular, the @kbd{/} is used -for RPN-style division, @emph{not} for entering fractions.) - -If you give two characters, fractions use ``integer-plus-fractional-part'' -notation. For example, the format @samp{+/} would display eight thirds -as @samp{2+2/3}. If two colons are present in a number being entered, -the number is interpreted in this form (so that the entries @kbd{2:2:3} -and @kbd{8:3} are equivalent). - -It is also possible to follow the one- or two-character format with -a number. For example: @samp{:10} or @samp{+/3}. In this case, -Calc adjusts all fractions that are displayed to have the specified -denominator, if possible. Otherwise it adjusts the denominator to -be a multiple of the specified value. For example, in @samp{:6} mode -the fraction @expr{1:6} will be unaffected, but @expr{2:3} will be -displayed as @expr{4:6}, @expr{1:2} will be displayed as @expr{3:6}, -and @expr{1:8} will be displayed as @expr{3:24}. Integers are also -affected by this mode: 3 is displayed as @expr{18:6}. Note that the -format @samp{:1} writes fractions the same as @samp{:}, but it writes -integers as @expr{n:1}. - -The fraction format does not affect the way fractions or integers are -stored, only the way they appear on the screen. The fraction format -never affects floats. - -@node HMS Formats, Date Formats, Fraction Formats, Display Modes -@subsection HMS Formats - -@noindent -@kindex d h -@pindex calc-hms-notation -The @kbd{d h} (@code{calc-hms-notation}) command controls the display of -HMS (hours-minutes-seconds) forms. It prompts for a string which -consists basically of an ``hours'' marker, optional punctuation, a -``minutes'' marker, more optional punctuation, and a ``seconds'' marker. -Punctuation is zero or more spaces, commas, or semicolons. The hours -marker is one or more non-punctuation characters. The minutes and -seconds markers must be single non-punctuation characters. - -The default HMS format is @samp{@@ ' "}, producing HMS values of the form -@samp{23@@ 30' 15.75"}. The format @samp{deg, ms} would display this same -value as @samp{23deg, 30m15.75s}. During numeric entry, the @kbd{h} or @kbd{o} -keys are recognized as synonyms for @kbd{@@} regardless of display format. -The @kbd{m} and @kbd{s} keys are recognized as synonyms for @kbd{'} and -@kbd{"}, respectively, but only if an @kbd{@@} (or @kbd{h} or @kbd{o}) has -already been typed; otherwise, they have their usual meanings -(@kbd{m-} prefix and @kbd{s-} prefix). Thus, @kbd{5 "}, @kbd{0 @@ 5 "}, and -@kbd{0 h 5 s} are some of the ways to enter the quantity ``five seconds.'' -The @kbd{'} key is recognized as ``minutes'' only if @kbd{@@} (or @kbd{h} or -@kbd{o}) has already been pressed; otherwise it means to switch to algebraic -entry. - -@node Date Formats, Truncating the Stack, HMS Formats, Display Modes -@subsection Date Formats - -@noindent -@kindex d d -@pindex calc-date-notation -The @kbd{d d} (@code{calc-date-notation}) command controls the display -of date forms (@pxref{Date Forms}). It prompts for a string which -contains letters that represent the various parts of a date and time. -To show which parts should be omitted when the form represents a pure -date with no time, parts of the string can be enclosed in @samp{< >} -marks. If you don't include @samp{< >} markers in the format, Calc -guesses at which parts, if any, should be omitted when formatting -pure dates. - -The default format is: @samp{Www Mmm D, YYYY}. -An example string in this format is @samp{3:32pm Wed Jan 9, 1991}. -If you enter a blank format string, this default format is -reestablished. - -Calc uses @samp{< >} notation for nameless functions as well as for -dates. @xref{Specifying Operators}. To avoid confusion with nameless -functions, your date formats should avoid using the @samp{#} character. - -@menu -* Date Formatting Codes:: -* Free-Form Dates:: -* Standard Date Formats:: -@end menu - -@node Date Formatting Codes, Free-Form Dates, Date Formats, Date Formats -@subsubsection Date Formatting Codes - -@noindent -When displaying a date, the current date format is used. All -characters except for letters and @samp{<} and @samp{>} are -copied literally when dates are formatted. The portion between -@samp{< >} markers is omitted for pure dates, or included for -date/time forms. Letters are interpreted according to the table -below. - -When dates are read in during algebraic entry, Calc first tries to -match the input string to the current format either with or without -the time part. The punctuation characters (including spaces) must -match exactly; letter fields must correspond to suitable text in -the input. If this doesn't work, Calc checks if the input is a -simple number; if so, the number is interpreted as a number of days -since Jan 1, 1 AD. Otherwise, Calc tries a much more relaxed and -flexible algorithm which is described in the next section. - -Weekday names are ignored during reading. - -Two-digit year numbers are interpreted as lying in the range -from 1941 to 2039. Years outside that range are always -entered and displayed in full. Year numbers with a leading -@samp{+} sign are always interpreted exactly, allowing the -entry and display of the years 1 through 99 AD. - -Here is a complete list of the formatting codes for dates: - -@table @asis -@item Y -Year: ``91'' for 1991, ``7'' for 2007, ``+23'' for 23 AD. -@item YY -Year: ``91'' for 1991, ``07'' for 2007, ``+23'' for 23 AD. -@item BY -Year: ``91'' for 1991, `` 7'' for 2007, ``+23'' for 23 AD. -@item YYY -Year: ``1991'' for 1991, ``23'' for 23 AD. -@item YYYY -Year: ``1991'' for 1991, ``+23'' for 23 AD. -@item aa -Year: ``ad'' or blank. -@item AA -Year: ``AD'' or blank. -@item aaa -Year: ``ad '' or blank. (Note trailing space.) -@item AAA -Year: ``AD '' or blank. -@item aaaa -Year: ``a.d.'' or blank. -@item AAAA -Year: ``A.D.'' or blank. -@item bb -Year: ``bc'' or blank. -@item BB -Year: ``BC'' or blank. -@item bbb -Year: `` bc'' or blank. (Note leading space.) -@item BBB -Year: `` BC'' or blank. -@item bbbb -Year: ``b.c.'' or blank. -@item BBBB -Year: ``B.C.'' or blank. -@item M -Month: ``8'' for August. -@item MM -Month: ``08'' for August. -@item BM -Month: `` 8'' for August. -@item MMM -Month: ``AUG'' for August. -@item Mmm -Month: ``Aug'' for August. -@item mmm -Month: ``aug'' for August. -@item MMMM -Month: ``AUGUST'' for August. -@item Mmmm -Month: ``August'' for August. -@item D -Day: ``7'' for 7th day of month. -@item DD -Day: ``07'' for 7th day of month. -@item BD -Day: `` 7'' for 7th day of month. -@item W -Weekday: ``0'' for Sunday, ``6'' for Saturday. -@item WWW -Weekday: ``SUN'' for Sunday. -@item Www -Weekday: ``Sun'' for Sunday. -@item www -Weekday: ``sun'' for Sunday. -@item WWWW -Weekday: ``SUNDAY'' for Sunday. -@item Wwww -Weekday: ``Sunday'' for Sunday. -@item d -Day of year: ``34'' for Feb. 3. -@item ddd -Day of year: ``034'' for Feb. 3. -@item bdd -Day of year: `` 34'' for Feb. 3. -@item h -Hour: ``5'' for 5 AM; ``17'' for 5 PM. -@item hh -Hour: ``05'' for 5 AM; ``17'' for 5 PM. -@item bh -Hour: `` 5'' for 5 AM; ``17'' for 5 PM. -@item H -Hour: ``5'' for 5 AM and 5 PM. -@item HH -Hour: ``05'' for 5 AM and 5 PM. -@item BH -Hour: `` 5'' for 5 AM and 5 PM. -@item p -AM/PM: ``a'' or ``p''. -@item P -AM/PM: ``A'' or ``P''. -@item pp -AM/PM: ``am'' or ``pm''. -@item PP -AM/PM: ``AM'' or ``PM''. -@item pppp -AM/PM: ``a.m.'' or ``p.m.''. -@item PPPP -AM/PM: ``A.M.'' or ``P.M.''. -@item m -Minutes: ``7'' for 7. -@item mm -Minutes: ``07'' for 7. -@item bm -Minutes: `` 7'' for 7. -@item s -Seconds: ``7'' for 7; ``7.23'' for 7.23. -@item ss -Seconds: ``07'' for 7; ``07.23'' for 7.23. -@item bs -Seconds: `` 7'' for 7; `` 7.23'' for 7.23. -@item SS -Optional seconds: ``07'' for 7; blank for 0. -@item BS -Optional seconds: `` 7'' for 7; blank for 0. -@item N -Numeric date/time: ``726842.25'' for 6:00am Wed Jan 9, 1991. -@item n -Numeric date: ``726842'' for any time on Wed Jan 9, 1991. -@item J -Julian date/time: ``2448265.75'' for 6:00am Wed Jan 9, 1991. -@item j -Julian date: ``2448266'' for any time on Wed Jan 9, 1991. -@item U -Unix time: ``663400800'' for 6:00am Wed Jan 9, 1991. -@item X -Brackets suppression. An ``X'' at the front of the format -causes the surrounding @w{@samp{< >}} delimiters to be omitted -when formatting dates. Note that the brackets are still -required for algebraic entry. -@end table - -If ``SS'' or ``BS'' (optional seconds) is preceded by a colon, the -colon is also omitted if the seconds part is zero. - -If ``bb,'' ``bbb'' or ``bbbb'' or their upper-case equivalents -appear in the format, then negative year numbers are displayed -without a minus sign. Note that ``aa'' and ``bb'' are mutually -exclusive. Some typical usages would be @samp{YYYY AABB}; -@samp{AAAYYYYBBB}; @samp{YYYYBBB}. - -The formats ``YY,'' ``YYYY,'' ``MM,'' ``DD,'' ``ddd,'' ``hh,'' ``HH,'' -``mm,'' ``ss,'' and ``SS'' actually match any number of digits during -reading unless several of these codes are strung together with no -punctuation in between, in which case the input must have exactly as -many digits as there are letters in the format. - -The ``j,'' ``J,'' and ``U'' formats do not make any time zone -adjustment. They effectively use @samp{julian(x,0)} and -@samp{unixtime(x,0)} to make the conversion; @pxref{Date Arithmetic}. - -@node Free-Form Dates, Standard Date Formats, Date Formatting Codes, Date Formats -@subsubsection Free-Form Dates - -@noindent -When reading a date form during algebraic entry, Calc falls back -on the algorithm described here if the input does not exactly -match the current date format. This algorithm generally -``does the right thing'' and you don't have to worry about it, -but it is described here in full detail for the curious. - -Calc does not distinguish between upper- and lower-case letters -while interpreting dates. - -First, the time portion, if present, is located somewhere in the -text and then removed. The remaining text is then interpreted as -the date. - -A time is of the form @samp{hh:mm:ss}, possibly with the seconds -part omitted and possibly with an AM/PM indicator added to indicate -12-hour time. If the AM/PM is present, the minutes may also be -omitted. The AM/PM part may be any of the words @samp{am}, -@samp{pm}, @samp{noon}, or @samp{midnight}; each of these may be -abbreviated to one letter, and the alternate forms @samp{a.m.}, -@samp{p.m.}, and @samp{mid} are also understood. Obviously -@samp{noon} and @samp{midnight} are allowed only on 12:00:00. -The words @samp{noon}, @samp{mid}, and @samp{midnight} are also -recognized with no number attached. - -If there is no AM/PM indicator, the time is interpreted in 24-hour -format. - -To read the date portion, all words and numbers are isolated -from the string; other characters are ignored. All words must -be either month names or day-of-week names (the latter of which -are ignored). Names can be written in full or as three-letter -abbreviations. - -Large numbers, or numbers with @samp{+} or @samp{-} signs, -are interpreted as years. If one of the other numbers is -greater than 12, then that must be the day and the remaining -number in the input is therefore the month. Otherwise, Calc -assumes the month, day and year are in the same order that they -appear in the current date format. If the year is omitted, the -current year is taken from the system clock. - -If there are too many or too few numbers, or any unrecognizable -words, then the input is rejected. - -If there are any large numbers (of five digits or more) other than -the year, they are ignored on the assumption that they are something -like Julian dates that were included along with the traditional -date components when the date was formatted. - -One of the words @samp{ad}, @samp{a.d.}, @samp{bc}, or @samp{b.c.} -may optionally be used; the latter two are equivalent to a -minus sign on the year value. - -If you always enter a four-digit year, and use a name instead -of a number for the month, there is no danger of ambiguity. - -@node Standard Date Formats, , Free-Form Dates, Date Formats -@subsubsection Standard Date Formats - -@noindent -There are actually ten standard date formats, numbered 0 through 9. -Entering a blank line at the @kbd{d d} command's prompt gives -you format number 1, Calc's usual format. You can enter any digit -to select the other formats. - -To create your own standard date formats, give a numeric prefix -argument from 0 to 9 to the @w{@kbd{d d}} command. The format you -enter will be recorded as the new standard format of that -number, as well as becoming the new current date format. -You can save your formats permanently with the @w{@kbd{m m}} -command (@pxref{Mode Settings}). - -@table @asis -@item 0 -@samp{N} (Numerical format) -@item 1 -@samp{Www Mmm D, YYYY} (American format) -@item 2 -@samp{D Mmm YYYY<, h:mm:SS>} (European format) -@item 3 -@samp{Www Mmm BD< hh:mm:ss> YYYY} (Unix written date format) -@item 4 -@samp{M/D/Y< H:mm:SSpp>} (American slashed format) -@item 5 -@samp{D.M.Y< h:mm:SS>} (European dotted format) -@item 6 -@samp{M-D-Y< H:mm:SSpp>} (American dashed format) -@item 7 -@samp{D-M-Y< h:mm:SS>} (European dashed format) -@item 8 -@samp{j<, h:mm:ss>} (Julian day plus time) -@item 9 -@samp{YYddd< hh:mm:ss>} (Year-day format) -@end table - -@node Truncating the Stack, Justification, Date Formats, Display Modes -@subsection Truncating the Stack - -@noindent -@kindex d t -@pindex calc-truncate-stack -@cindex Truncating the stack -@cindex Narrowing the stack -The @kbd{d t} (@code{calc-truncate-stack}) command moves the @samp{.}@: -line that marks the top-of-stack up or down in the Calculator buffer. -The number right above that line is considered to the be at the top of -the stack. Any numbers below that line are ``hidden'' from all stack -operations (although still visible to the user). This is similar to the -Emacs ``narrowing'' feature, except that the values below the @samp{.} -are @emph{visible}, just temporarily frozen. This feature allows you to -keep several independent calculations running at once in different parts -of the stack, or to apply a certain command to an element buried deep in -the stack. - -Pressing @kbd{d t} by itself moves the @samp{.} to the line the cursor -is on. Thus, this line and all those below it become hidden. To un-hide -these lines, move down to the end of the buffer and press @w{@kbd{d t}}. -With a positive numeric prefix argument @expr{n}, @kbd{d t} hides the -bottom @expr{n} values in the buffer. With a negative argument, it hides -all but the top @expr{n} values. With an argument of zero, it hides zero -values, i.e., moves the @samp{.} all the way down to the bottom. - -@kindex d [ -@pindex calc-truncate-up -@kindex d ] -@pindex calc-truncate-down -The @kbd{d [} (@code{calc-truncate-up}) and @kbd{d ]} -(@code{calc-truncate-down}) commands move the @samp{.} up or down one -line at a time (or several lines with a prefix argument). - -@node Justification, Labels, Truncating the Stack, Display Modes -@subsection Justification - -@noindent -@kindex d < -@pindex calc-left-justify -@kindex d = -@pindex calc-center-justify -@kindex d > -@pindex calc-right-justify -Values on the stack are normally left-justified in the window. You can -control this arrangement by typing @kbd{d <} (@code{calc-left-justify}), -@kbd{d >} (@code{calc-right-justify}), or @kbd{d =} -(@code{calc-center-justify}). For example, in Right-Justification mode, -stack entries are displayed flush-right against the right edge of the -window. - -If you change the width of the Calculator window you may have to type -@kbd{d @key{SPC}} (@code{calc-refresh}) to re-align right-justified or centered -text. - -Right-justification is especially useful together with fixed-point -notation (see @code{d f}; @code{calc-fix-notation}). With these modes -together, the decimal points on numbers will always line up. - -With a numeric prefix argument, the justification commands give you -a little extra control over the display. The argument specifies the -horizontal ``origin'' of a display line. It is also possible to -specify a maximum line width using the @kbd{d b} command (@pxref{Normal -Language Modes}). For reference, the precise rules for formatting and -breaking lines are given below. Notice that the interaction between -origin and line width is slightly different in each justification -mode. - -In Left-Justified mode, the line is indented by a number of spaces -given by the origin (default zero). If the result is longer than the -maximum line width, if given, or too wide to fit in the Calc window -otherwise, then it is broken into lines which will fit; each broken -line is indented to the origin. - -In Right-Justified mode, lines are shifted right so that the rightmost -character is just before the origin, or just before the current -window width if no origin was specified. If the line is too long -for this, then it is broken; the current line width is used, if -specified, or else the origin is used as a width if that is -specified, or else the line is broken to fit in the window. - -In Centering mode, the origin is the column number of the center of -each stack entry. If a line width is specified, lines will not be -allowed to go past that width; Calc will either indent less or -break the lines if necessary. If no origin is specified, half the -line width or Calc window width is used. - -Note that, in each case, if line numbering is enabled the display -is indented an additional four spaces to make room for the line -number. The width of the line number is taken into account when -positioning according to the current Calc window width, but not -when positioning by explicit origins and widths. In the latter -case, the display is formatted as specified, and then uniformly -shifted over four spaces to fit the line numbers. - -@node Labels, , Justification, Display Modes -@subsection Labels - -@noindent -@kindex d @{ -@pindex calc-left-label -The @kbd{d @{} (@code{calc-left-label}) command prompts for a string, -then displays that string to the left of every stack entry. If the -entries are left-justified (@pxref{Justification}), then they will -appear immediately after the label (unless you specified an origin -greater than the length of the label). If the entries are centered -or right-justified, the label appears on the far left and does not -affect the horizontal position of the stack entry. - -Give a blank string (with @kbd{d @{ @key{RET}}) to turn the label off. - -@kindex d @} -@pindex calc-right-label -The @kbd{d @}} (@code{calc-right-label}) command similarly adds a -label on the righthand side. It does not affect positioning of -the stack entries unless they are right-justified. Also, if both -a line width and an origin are given in Right-Justified mode, the -stack entry is justified to the origin and the righthand label is -justified to the line width. - -One application of labels would be to add equation numbers to -formulas you are manipulating in Calc and then copying into a -document (possibly using Embedded mode). The equations would -typically be centered, and the equation numbers would be on the -left or right as you prefer. - -@node Language Modes, Modes Variable, Display Modes, Mode Settings -@section Language Modes - -@noindent -The commands in this section change Calc to use a different notation for -entry and display of formulas, corresponding to the conventions of some -other common language such as Pascal or La@TeX{}. Objects displayed on the -stack or yanked from the Calculator to an editing buffer will be formatted -in the current language; objects entered in algebraic entry or yanked from -another buffer will be interpreted according to the current language. - -The current language has no effect on things written to or read from the -trail buffer, nor does it affect numeric entry. Only algebraic entry is -affected. You can make even algebraic entry ignore the current language -and use the standard notation by giving a numeric prefix, e.g., @kbd{C-u '}. - -For example, suppose the formula @samp{2*a[1] + atan(a[2])} occurs in a C -program; elsewhere in the program you need the derivatives of this formula -with respect to @samp{a[1]} and @samp{a[2]}. First, type @kbd{d C} -to switch to C notation. Now use @code{C-u C-x * g} to grab the formula -into the Calculator, @kbd{a d a[1] @key{RET}} to differentiate with respect -to the first variable, and @kbd{C-x * y} to yank the formula for the derivative -back into your C program. Press @kbd{U} to undo the differentiation and -repeat with @kbd{a d a[2] @key{RET}} for the other derivative. - -Without being switched into C mode first, Calc would have misinterpreted -the brackets in @samp{a[1]} and @samp{a[2]}, would not have known that -@code{atan} was equivalent to Calc's built-in @code{arctan} function, -and would have written the formula back with notations (like implicit -multiplication) which would not have been valid for a C program. - -As another example, suppose you are maintaining a C program and a La@TeX{} -document, each of which needs a copy of the same formula. You can grab the -formula from the program in C mode, switch to La@TeX{} mode, and yank the -formula into the document in La@TeX{} math-mode format. - -Language modes are selected by typing the letter @kbd{d} followed by a -shifted letter key. - -@menu -* Normal Language Modes:: -* C FORTRAN Pascal:: -* TeX and LaTeX Language Modes:: -* Eqn Language Mode:: -* Yacas Language Mode:: -* Maxima Language Mode:: -* Giac Language Mode:: -* Mathematica Language Mode:: -* Maple Language Mode:: -* Compositions:: -* Syntax Tables:: -@end menu - -@node Normal Language Modes, C FORTRAN Pascal, Language Modes, Language Modes -@subsection Normal Language Modes - -@noindent -@kindex d N -@pindex calc-normal-language -The @kbd{d N} (@code{calc-normal-language}) command selects the usual -notation for Calc formulas, as described in the rest of this manual. -Matrices are displayed in a multi-line tabular format, but all other -objects are written in linear form, as they would be typed from the -keyboard. - -@kindex d O -@pindex calc-flat-language -@cindex Matrix display -The @kbd{d O} (@code{calc-flat-language}) command selects a language -identical with the normal one, except that matrices are written in -one-line form along with everything else. In some applications this -form may be more suitable for yanking data into other buffers. - -@kindex d b -@pindex calc-line-breaking -@cindex Line breaking -@cindex Breaking up long lines -Even in one-line mode, long formulas or vectors will still be split -across multiple lines if they exceed the width of the Calculator window. -The @kbd{d b} (@code{calc-line-breaking}) command turns this line-breaking -feature on and off. (It works independently of the current language.) -If you give a numeric prefix argument of five or greater to the @kbd{d b} -command, that argument will specify the line width used when breaking -long lines. - -@kindex d B -@pindex calc-big-language -The @kbd{d B} (@code{calc-big-language}) command selects a language -which uses textual approximations to various mathematical notations, -such as powers, quotients, and square roots: - -@example - ____________ - | a + 1 2 - | ----- + c -\| b -@end example - -@noindent -in place of @samp{sqrt((a+1)/b + c^2)}. - -Subscripts like @samp{a_i} are displayed as actual subscripts in Big -mode. Double subscripts, @samp{a_i_j} (@samp{subscr(subscr(a, i), j)}) -are displayed as @samp{a} with subscripts separated by commas: -@samp{i, j}. They must still be entered in the usual underscore -notation. - -One slight ambiguity of Big notation is that - -@example - 3 -- - - 4 -@end example - -@noindent -can represent either the negative rational number @expr{-3:4}, or the -actual expression @samp{-(3/4)}; but the latter formula would normally -never be displayed because it would immediately be evaluated to -@expr{-3:4} or @expr{-0.75}, so this ambiguity is not a problem in -typical use. - -Non-decimal numbers are displayed with subscripts. Thus there is no -way to tell the difference between @samp{16#C2} and @samp{C2_16}, -though generally you will know which interpretation is correct. -Logarithms @samp{log(x,b)} and @samp{log10(x)} also use subscripts -in Big mode. - -In Big mode, stack entries often take up several lines. To aid -readability, stack entries are separated by a blank line in this mode. -You may find it useful to expand the Calc window's height using -@kbd{C-x ^} (@code{enlarge-window}) or to make the Calc window the only -one on the screen with @kbd{C-x 1} (@code{delete-other-windows}). - -Long lines are currently not rearranged to fit the window width in -Big mode, so you may need to use the @kbd{<} and @kbd{>} keys -to scroll across a wide formula. For really big formulas, you may -even need to use @kbd{@{} and @kbd{@}} to scroll up and down. - -@kindex d U -@pindex calc-unformatted-language -The @kbd{d U} (@code{calc-unformatted-language}) command altogether disables -the use of operator notation in formulas. In this mode, the formula -shown above would be displayed: - -@example -sqrt(add(div(add(a, 1), b), pow(c, 2))) -@end example - -These four modes differ only in display format, not in the format -expected for algebraic entry. The standard Calc operators work in -all four modes, and unformatted notation works in any language mode -(except that Mathematica mode expects square brackets instead of -parentheses). - -@node C FORTRAN Pascal, TeX and LaTeX Language Modes, Normal Language Modes, Language Modes -@subsection C, FORTRAN, and Pascal Modes - -@noindent -@kindex d C -@pindex calc-c-language -@cindex C language -The @kbd{d C} (@code{calc-c-language}) command selects the conventions -of the C language for display and entry of formulas. This differs from -the normal language mode in a variety of (mostly minor) ways. In -particular, C language operators and operator precedences are used in -place of Calc's usual ones. For example, @samp{a^b} means @samp{xor(a,b)} -in C mode; a value raised to a power is written as a function call, -@samp{pow(a,b)}. - -In C mode, vectors and matrices use curly braces instead of brackets. -Octal and hexadecimal values are written with leading @samp{0} or @samp{0x} -rather than using the @samp{#} symbol. Array subscripting is -translated into @code{subscr} calls, so that @samp{a[i]} in C -mode is the same as @samp{a_i} in Normal mode. Assignments -turn into the @code{assign} function, which Calc normally displays -using the @samp{:=} symbol. - -The variables @code{pi} and @code{e} would be displayed @samp{pi} -and @samp{e} in Normal mode, but in C mode they are displayed as -@samp{M_PI} and @samp{M_E}, corresponding to the names of constants -typically provided in the @file{} header. Functions whose -names are different in C are translated automatically for entry and -display purposes. For example, entering @samp{asin(x)} will push the -formula @samp{arcsin(x)} onto the stack; this formula will be displayed -as @samp{asin(x)} as long as C mode is in effect. - -@kindex d P -@pindex calc-pascal-language -@cindex Pascal language -The @kbd{d P} (@code{calc-pascal-language}) command selects Pascal -conventions. Like C mode, Pascal mode interprets array brackets and uses -a different table of operators. Hexadecimal numbers are entered and -displayed with a preceding dollar sign. (Thus the regular meaning of -@kbd{$2} during algebraic entry does not work in Pascal mode, though -@kbd{$} (and @kbd{$$}, etc.) not followed by digits works the same as -always.) No special provisions are made for other non-decimal numbers, -vectors, and so on, since there is no universally accepted standard way -of handling these in Pascal. - -@kindex d F -@pindex calc-fortran-language -@cindex FORTRAN language -The @kbd{d F} (@code{calc-fortran-language}) command selects FORTRAN -conventions. Various function names are transformed into FORTRAN -equivalents. Vectors are written as @samp{/1, 2, 3/}, and may be -entered this way or using square brackets. Since FORTRAN uses round -parentheses for both function calls and array subscripts, Calc displays -both in the same way; @samp{a(i)} is interpreted as a function call -upon reading, and subscripts must be entered as @samp{subscr(a, i)}. -If the variable @code{a} has been declared to have type -@code{vector} or @code{matrix}, however, then @samp{a(i)} will be -parsed as a subscript. (@xref{Declarations}.) Usually it doesn't -matter, though; if you enter the subscript expression @samp{a(i)} and -Calc interprets it as a function call, you'll never know the difference -unless you switch to another language mode or replace @code{a} with an -actual vector (or unless @code{a} happens to be the name of a built-in -function!). - -Underscores are allowed in variable and function names in all of these -language modes. The underscore here is equivalent to the @samp{#} in -Normal mode, or to hyphens in the underlying Emacs Lisp variable names. - -FORTRAN and Pascal modes normally do not adjust the case of letters in -formulas. Most built-in Calc names use lower-case letters. If you use a -positive numeric prefix argument with @kbd{d P} or @kbd{d F}, these -modes will use upper-case letters exclusively for display, and will -convert to lower-case on input. With a negative prefix, these modes -convert to lower-case for display and input. - -@node TeX and LaTeX Language Modes, Eqn Language Mode, C FORTRAN Pascal, Language Modes -@subsection @TeX{} and La@TeX{} Language Modes - -@noindent -@kindex d T -@pindex calc-tex-language -@cindex TeX language -@kindex d L -@pindex calc-latex-language -@cindex LaTeX language -The @kbd{d T} (@code{calc-tex-language}) command selects the conventions -of ``math mode'' in Donald Knuth's @TeX{} typesetting language, -and the @kbd{d L} (@code{calc-latex-language}) command selects the -conventions of ``math mode'' in La@TeX{}, a typesetting language that -uses @TeX{} as its formatting engine. Calc's La@TeX{} language mode can -read any formula that the @TeX{} language mode can, although La@TeX{} -mode may display it differently. - -Formulas are entered and displayed in the appropriate notation; -@texline @math{\sin(a/b)} -@infoline @expr{sin(a/b)} -will appear as @samp{\sin\left( @{a \over b@} \right)} in @TeX{} mode and -@samp{\sin\left(\frac@{a@}@{b@}\right)} in La@TeX{} mode. -Math formulas are often enclosed by @samp{$ $} signs in @TeX{} and -La@TeX{}; these should be omitted when interfacing with Calc. To Calc, -the @samp{$} sign has the same meaning it always does in algebraic -formulas (a reference to an existing entry on the stack). - -Complex numbers are displayed as in @samp{3 + 4i}. Fractions and -quotients are written using @code{\over} in @TeX{} mode (as in -@code{@{a \over b@}}) and @code{\frac} in La@TeX{} mode (as in -@code{\frac@{a@}@{b@}}); binomial coefficients are written with -@code{\choose} in @TeX{} mode (as in @code{@{a \choose b@}}) and -@code{\binom} in La@TeX{} mode (as in @code{\binom@{a@}@{b@}}). -Interval forms are written with @code{\ldots}, and error forms are -written with @code{\pm}. Absolute values are written as in -@samp{|x + 1|}, and the floor and ceiling functions are written with -@code{\lfloor}, @code{\rfloor}, etc. The words @code{\left} and -@code{\right} are ignored when reading formulas in @TeX{} and La@TeX{} -modes. Both @code{inf} and @code{uinf} are written as @code{\infty}; -when read, @code{\infty} always translates to @code{inf}. - -Function calls are written the usual way, with the function name followed -by the arguments in parentheses. However, functions for which @TeX{} -and La@TeX{} have special names (like @code{\sin}) will use curly braces -instead of parentheses for very simple arguments. During input, curly -braces and parentheses work equally well for grouping, but when the -document is formatted the curly braces will be invisible. Thus the -printed result is -@texline @math{\sin{2 x}} -@infoline @expr{sin 2x} -but -@texline @math{\sin(2 + x)}. -@infoline @expr{sin(2 + x)}. - -Function and variable names not treated specially by @TeX{} and La@TeX{} -are simply written out as-is, which will cause them to come out in -italic letters in the printed document. If you invoke @kbd{d T} or -@kbd{d L} with a positive numeric prefix argument, names of more than -one character will instead be enclosed in a protective commands that -will prevent them from being typeset in the math italics; they will be -written @samp{\hbox@{@var{name}@}} in @TeX{} mode and -@samp{\text@{@var{name}@}} in La@TeX{} mode. The -@samp{\hbox@{ @}} and @samp{\text@{ @}} notations are ignored during -reading. If you use a negative prefix argument, such function names are -written @samp{\@var{name}}, and function names that begin with @code{\} during -reading have the @code{\} removed. (Note that in this mode, long -variable names are still written with @code{\hbox} or @code{\text}. -However, you can always make an actual variable name like @code{\bar} in -any @TeX{} mode.) - -During reading, text of the form @samp{\matrix@{ ...@: @}} is replaced -by @samp{[ ...@: ]}. The same also applies to @code{\pmatrix} and -@code{\bmatrix}. In La@TeX{} mode this also applies to -@samp{\begin@{matrix@} ... \end@{matrix@}}, -@samp{\begin@{bmatrix@} ... \end@{bmatrix@}}, -@samp{\begin@{pmatrix@} ... \end@{pmatrix@}}, as well as -@samp{\begin@{smallmatrix@} ... \end@{smallmatrix@}}. -The symbol @samp{&} is interpreted as a comma, -and the symbols @samp{\cr} and @samp{\\} are interpreted as semicolons. -During output, matrices are displayed in @samp{\matrix@{ a & b \\ c & d@}} -format in @TeX{} mode and in -@samp{\begin@{pmatrix@} a & b \\ c & d \end@{pmatrix@}} format in -La@TeX{} mode; you may need to edit this afterwards to change to your -preferred matrix form. If you invoke @kbd{d T} or @kbd{d L} with an -argument of 2 or -2, then matrices will be displayed in two-dimensional -form, such as - -@example -\begin@{pmatrix@} -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -This may be convenient for isolated matrices, but could lead to -expressions being displayed like - -@example -\begin@{pmatrix@} \times x -a & b \\ -c & d -\end@{pmatrix@} -@end example - -@noindent -While this wouldn't bother Calc, it is incorrect La@TeX{}. -(Similarly for @TeX{}.) - -Accents like @code{\tilde} and @code{\bar} translate into function -calls internally (@samp{tilde(x)}, @samp{bar(x)}). The @code{\underline} -sequence is treated as an accent. The @code{\vec} accent corresponds -to the function name @code{Vec}, because @code{vec} is the name of -a built-in Calc function. The following table shows the accents -in Calc, @TeX{}, La@TeX{} and @dfn{eqn} (described in the next section): - -@ignore -@iftex -@begingroup -@let@calcindexershow=@calcindexernoshow @c Suppress marginal notes -@let@calcindexersh=@calcindexernoshow -@end iftex -@starindex -@end ignore -@tindex acute -@ignore -@starindex -@end ignore -@tindex Acute -@ignore -@starindex -@end ignore -@tindex bar -@ignore -@starindex -@end ignore -@tindex Bar -@ignore -@starindex -@end ignore -@tindex breve -@ignore -@starindex -@end ignore -@tindex Breve -@ignore -@starindex -@end ignore -@tindex check -@ignore -@starindex -@end ignore -@tindex Check -@ignore -@starindex -@end ignore -@tindex dddot -@ignore -@starindex -@end ignore -@tindex ddddot -@ignore -@starindex -@end ignore -@tindex dot -@ignore -@starindex -@end ignore -@tindex Dot -@ignore -@starindex -@end ignore -@tindex dotdot -@ignore -@starindex -@end ignore -@tindex DotDot -@ignore -@starindex -@end ignore -@tindex dyad -@ignore -@starindex -@end ignore -@tindex grave -@ignore -@starindex -@end ignore -@tindex Grave -@ignore -@starindex -@end ignore -@tindex hat -@ignore -@starindex -@end ignore -@tindex Hat -@ignore -@starindex -@end ignore -@tindex Prime -@ignore -@starindex -@end ignore -@tindex tilde -@ignore -@starindex -@end ignore -@tindex Tilde -@ignore -@starindex -@end ignore -@tindex under -@ignore -@starindex -@end ignore -@tindex Vec -@ignore -@starindex -@end ignore -@tindex VEC -@ignore -@iftex -@endgroup -@end iftex -@end ignore -@example -Calc TeX LaTeX eqn ----- --- ----- --- -acute \acute \acute -Acute \Acute -bar \bar \bar bar -Bar \Bar -breve \breve \breve -Breve \Breve -check \check \check -Check \Check -dddot \dddot -ddddot \ddddot -dot \dot \dot dot -Dot \Dot -dotdot \ddot \ddot dotdot -DotDot \Ddot -dyad dyad -grave \grave \grave -Grave \Grave -hat \hat \hat hat -Hat \Hat -Prime prime -tilde \tilde \tilde tilde -Tilde \Tilde -under \underline \underline under -Vec \vec \vec vec -VEC \Vec -@end example - -The @samp{=>} (evaluates-to) operator appears as a @code{\to} symbol: -@samp{@{@var{a} \to @var{b}@}}. @TeX{} defines @code{\to} as an -alias for @code{\rightarrow}. However, if the @samp{=>} is the -top-level expression being formatted, a slightly different notation -is used: @samp{\evalto @var{a} \to @var{b}}. The @code{\evalto} -word is ignored by Calc's input routines, and is undefined in @TeX{}. -You will typically want to include one of the following definitions -at the top of a @TeX{} file that uses @code{\evalto}: - -@example -\def\evalto@{@} -\def\evalto#1\to@{@} -@end example - -The first definition formats evaluates-to operators in the usual -way. The second causes only the @var{b} part to appear in the -printed document; the @var{a} part and the arrow are hidden. -Another definition you may wish to use is @samp{\let\to=\Rightarrow} -which causes @code{\to} to appear more like Calc's @samp{=>} symbol. -@xref{Evaluates-To Operator}, for a discussion of @code{evalto}. - -The complete set of @TeX{} control sequences that are ignored during -reading is: - -@example -\hbox \mbox \text \left \right -\, \> \: \; \! \quad \qquad \hfil \hfill -\displaystyle \textstyle \dsize \tsize -\scriptstyle \scriptscriptstyle \ssize \ssize -\rm \bf \it \sl \roman \bold \italic \slanted -\cal \mit \Cal \Bbb \frak \goth -\evalto -@end example - -Note that, because these symbols are ignored, reading a @TeX{} or -La@TeX{} formula into Calc and writing it back out may lose spacing and -font information. - -Also, the ``discretionary multiplication sign'' @samp{\*} is read -the same as @samp{*}. - -@ifnottex -The @TeX{} version of this manual includes some printed examples at the -end of this section. -@end ifnottex -@iftex -Here are some examples of how various Calc formulas are formatted in @TeX{}: - -@example -@group -sin(a^2 / b_i) -\sin\left( {a^2 \over b_i} \right) -@end group -@end example -@tex -$$ \sin\left( a^2 \over b_i \right) $$ -@end tex -@sp 1 - -@example -@group -[(3, 4), 3:4, 3 +/- 4, [3 .. inf)] -[3 + 4i, @{3 \over 4@}, 3 \pm 4, [3 \ldots \infty)] -@end group -@end example -@tex -\turnoffactive -$$ [3 + 4i, {3 \over 4}, 3 \pm 4, [ 3 \ldots \infty)] $$ -@end tex -@sp 1 - -@example -@group -[abs(a), abs(a / b), floor(a), ceil(a / b)] -[|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] -@end group -@end example -@tex -$$ [|a|, \left| a \over b \right|, - \lfloor a \rfloor, \left\lceil a \over b \right\rceil] $$ -@end tex -@sp 1 - -@example -@group -[sin(a), sin(2 a), sin(2 + a), sin(a / b)] -[\sin@{a@}, \sin@{2 a@}, \sin(2 + a), - \sin\left( @{a \over b@} \right)] -@end group -@end example -@tex -\turnoffactive -$$ [\sin{a}, \sin{2 a}, \sin(2 + a), \sin\left( {a \over b} \right)] $$ -@end tex -@sp 2 - -First with plain @kbd{d T}, then with @kbd{C-u d T}, then finally with -@kbd{C-u - d T} (using the example definition -@samp{\def\foo#1@{\tilde F(#1)@}}: - -@example -@group -[f(a), foo(bar), sin(pi)] -[f(a), foo(bar), \sin{\pi}] -[f(a), \hbox@{foo@}(\hbox@{bar@}), \sin@{\pi@}] -[f(a), \foo@{\hbox@{bar@}@}, \sin@{\pi@}] -@end group -@end example -@tex -$$ [f(a), foo(bar), \sin{\pi}] $$ -$$ [f(a), \hbox{foo}(\hbox{bar}), \sin{\pi}] $$ -$$ [f(a), \tilde F(\hbox{bar}), \sin{\pi}] $$ -@end tex -@sp 2 - -First with @samp{\def\evalto@{@}}, then with @samp{\def\evalto#1\to@{@}}: - -@example -@group -2 + 3 => 5 -\evalto 2 + 3 \to 5 -@end group -@end example -@tex -\turnoffactive -$$ 2 + 3 \to 5 $$ -$$ 5 $$ -@end tex -@sp 2 - -First with standard @code{\to}, then with @samp{\let\to\Rightarrow}: - -@example -@group -[2 + 3 => 5, a / 2 => (b + c) / 2] -[@{2 + 3 \to 5@}, @{@{a \over 2@} \to @{b + c \over 2@}@}] -@end group -@end example -@tex -\turnoffactive -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$ -{\let\to\Rightarrow -$$ [{2 + 3 \to 5}, {{a \over 2} \to {b + c \over 2}}] $$} -@end tex -@sp 2 - -Matrices normally, then changing @code{\matrix} to @code{\pmatrix}: - -@example -@group -[ [ a / b, 0 ], [ 0, 2^(x + 1) ] ] -\matrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -\pmatrix@{ @{a \over b@} & 0 \\ 0 & 2^@{(x + 1)@} @} -@end group -@end example -@tex -\turnoffactive -$$ \matrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -$$ \pmatrix{ {a \over b} & 0 \cr 0 & 2^{(x + 1)} } $$ -@end tex -@sp 2 -@end iftex - -@node Eqn Language Mode, Yacas Language Mode, TeX and LaTeX Language Modes, Language Modes -@subsection Eqn Language Mode - -@noindent -@kindex d E -@pindex calc-eqn-language -@dfn{Eqn} is another popular formatter for math formulas. It is -designed for use with the TROFF text formatter, and comes standard -with many versions of Unix. The @kbd{d E} (@code{calc-eqn-language}) -command selects @dfn{eqn} notation. - -The @dfn{eqn} language's main idiosyncrasy is that whitespace plays -a significant part in the parsing of the language. For example, -@samp{sqrt x+1 + y} treats @samp{x+1} as the argument of the -@code{sqrt} operator. @dfn{Eqn} also understands more conventional -grouping using curly braces: @samp{sqrt@{x+1@} + y}. Braces are -required only when the argument contains spaces. - -In Calc's @dfn{eqn} mode, however, curly braces are required to -delimit arguments of operators like @code{sqrt}. The first of the -above examples would treat only the @samp{x} as the argument of -@code{sqrt}, and in fact @samp{sin x+1} would be interpreted as -@samp{sin * x + 1}, because @code{sin} is not a special operator -in the @dfn{eqn} language. If you always surround the argument -with curly braces, Calc will never misunderstand. - -Calc also understands parentheses as grouping characters. Another -peculiarity of @dfn{eqn}'s syntax makes it advisable to separate -words with spaces from any surrounding characters that aren't curly -braces, so Calc writes @samp{sin ( x + y )} in @dfn{eqn} mode. -(The spaces around @code{sin} are important to make @dfn{eqn} -recognize that @code{sin} should be typeset in a roman font, and -the spaces around @code{x} and @code{y} are a good idea just in -case the @dfn{eqn} document has defined special meanings for these -names, too.) - -Powers and subscripts are written with the @code{sub} and @code{sup} -operators, respectively. Note that the caret symbol @samp{^} is -treated the same as a space in @dfn{eqn} mode, as is the @samp{~} -symbol (these are used to introduce spaces of various widths into -the typeset output of @dfn{eqn}). - -As in La@TeX{} mode, Calc's formatter omits parentheses around the -arguments of functions like @code{ln} and @code{sin} if they are -``simple-looking''; in this case Calc surrounds the argument with -braces, separated by a @samp{~} from the function name: @samp{sin~@{x@}}. - -Font change codes (like @samp{roman @var{x}}) and positioning codes -(like @samp{~} and @samp{down @var{n} @var{x}}) are ignored by the -@dfn{eqn} reader. Also ignored are the words @code{left}, @code{right}, -@code{mark}, and @code{lineup}. Quotation marks in @dfn{eqn} mode input -are treated the same as curly braces: @samp{sqrt "1+x"} is equivalent to -@samp{sqrt @{1+x@}}; this is only an approximation to the true meaning -of quotes in @dfn{eqn}, but it is good enough for most uses. - -Accent codes (@samp{@var{x} dot}) are handled by treating them as -function calls (@samp{dot(@var{x})}) internally. -@xref{TeX and LaTeX Language Modes}, for a table of these accent -functions. The @code{prime} accent is treated specially if it occurs on -a variable or function name: @samp{f prime prime @w{( x prime )}} is -stored internally as @samp{f'@w{'}(x')}. For example, taking the -derivative of @samp{f(2 x)} with @kbd{a d x} will produce @samp{2 f'(2 -x)}, which @dfn{eqn} mode will display as @samp{2 f prime ( 2 x )}. - -Assignments are written with the @samp{<-} (left-arrow) symbol, -and @code{evalto} operators are written with @samp{->} or -@samp{evalto ... ->} (@pxref{TeX and LaTeX Language Modes}, for a discussion -of this). The regular Calc symbols @samp{:=} and @samp{=>} are also -recognized for these operators during reading. - -Vectors in @dfn{eqn} mode use regular Calc square brackets, but -matrices are formatted as @samp{matrix @{ ccol @{ a above b @} ... @}}. -The words @code{lcol} and @code{rcol} are recognized as synonyms -for @code{ccol} during input, and are generated instead of @code{ccol} -if the matrix justification mode so specifies. - -@node Yacas Language Mode, Maxima Language Mode, Eqn Language Mode, Language Modes -@subsection Yacas Language Mode - -@noindent -@kindex d Y -@pindex calc-yacas-language -@cindex Yacas language -The @kbd{d Y} (@code{calc-yacas-language}) command selects the -conventions of Yacas, a free computer algebra system. While the -operators and functions in Yacas are similar to those of Calc, the names -of built-in functions in Yacas are capitalized. The Calc formula -@samp{sin(2 x)}, for example, is entered and displayed @samp{Sin(2 x)} -in Yacas mode, and `@samp{arcsin(x^2)} is @samp{ArcSin(x^2)} in Yacas -mode. Complex numbers are written are written @samp{3 + 4 I}. -The standard special constants are written @code{Pi}, @code{E}, -@code{I}, @code{GoldenRatio} and @code{Gamma}. @code{Infinity} -represents both @code{inf} and @code{uinf}, and @code{Undefined} -represents @code{nan}. - -Certain operators on functions, such as @code{D} for differentiation -and @code{Integrate} for integration, take a prefix form in Yacas. For -example, the derivative of @w{@samp{e^x sin(x)}} can be computed with -@w{@samp{D(x) Exp(x)*Sin(x)}}. - -Other notable differences between Yacas and standard Calc expressions -are that vectors and matrices use curly braces in Yacas, and subscripts -use square brackets. If, for example, @samp{A} represents the list -@samp{@{a,2,c,4@}}, then @samp{A[3]} would equal @samp{c}. - - -@node Maxima Language Mode, Giac Language Mode, Yacas Language Mode, Language Modes -@subsection Maxima Language Mode - -@noindent -@kindex d X -@pindex calc-maxima-language -@cindex Maxima language -The @kbd{d X} (@code{calc-maxima-language}) command selects the -conventions of Maxima, another free computer algebra system. The -function names in Maxima are similar, but not always identical, to Calc. -For example, instead of @samp{arcsin(x)}, Maxima will use -@samp{asin(x)}. Complex numbers are written @samp{3 + 4 %i}. The -standard special constants are written @code{%pi}, @code{%e}, -@code{%i}, @code{%phi} and @code{%gamma}. In Maxima, @code{inf} means -the same as in Calc, but @code{infinity} represents Calc's @code{uinf}. - -Underscores as well as percent signs are allowed in function and -variable names in Maxima mode. The underscore again is equivalent to -the @samp{#} in Normal mode, and the percent sign is equivalent to -@samp{o'o}. - -Maxima uses square brackets for lists and vectors, and matrices are -written as calls to the function @code{matrix}, given the row vectors of -the matrix as arguments. Square brackets are also used as subscripts. - -@node Giac Language Mode, Mathematica Language Mode, Maxima Language Mode, Language Modes -@subsection Giac Language Mode - -@noindent -@kindex d A -@pindex calc-giac-language -@cindex Giac language -The @kbd{d A} (@code{calc-giac-language}) command selects the -conventions of Giac, another free computer algebra system. The function -names in Giac are similar to Maxima. Complex numbers are written -@samp{3 + 4 i}. The standard special constants in Giac are the same as -in Calc, except that @code{infinity} represents both Calc's @code{inf} -and @code{uinf}. - -Underscores are allowed in function and variable names in Giac mode. -Brackets are used for subscripts. In Giac, indexing of lists begins at -0, instead of 1 as in Calc. So if @samp{A} represents the list -@samp{[a,2,c,4]}, then @samp{A[2]} would equal @samp{c}. In general, -@samp{A[n]} in Giac mode corresponds to @samp{A_(n+1)} in Normal mode. - -The Giac interval notation @samp{2 .. 3} has no surrounding brackets; -Calc reads @samp{2 .. 3} as the closed interval @samp{[2 .. 3]} and -writes any kind of interval as @samp{2 .. 3}. This means you cannot see -the difference between an open and a closed interval while in Giac mode. - -@node Mathematica Language Mode, Maple Language Mode, Giac Language Mode, Language Modes -@subsection Mathematica Language Mode - -@noindent -@kindex d M -@pindex calc-mathematica-language -@cindex Mathematica language -The @kbd{d M} (@code{calc-mathematica-language}) command selects the -conventions of Mathematica. Notable differences in Mathematica mode -are that the names of built-in functions are capitalized, and function -calls use square brackets instead of parentheses. Thus the Calc -formula @samp{sin(2 x)} is entered and displayed @w{@samp{Sin[2 x]}} in -Mathematica mode. - -Vectors and matrices use curly braces in Mathematica. Complex numbers -are written @samp{3 + 4 I}. The standard special constants in Calc are -written @code{Pi}, @code{E}, @code{I}, @code{GoldenRatio}, @code{EulerGamma}, -@code{Infinity}, @code{ComplexInfinity}, and @code{Indeterminate} in -Mathematica mode. -Non-decimal numbers are written, e.g., @samp{16^^7fff}. Floating-point -numbers in scientific notation are written @samp{1.23*10.^3}. -Subscripts use double square brackets: @samp{a[[i]]}. - -@node Maple Language Mode, Compositions, Mathematica Language Mode, Language Modes -@subsection Maple Language Mode - -@noindent -@kindex d W -@pindex calc-maple-language -@cindex Maple language -The @kbd{d W} (@code{calc-maple-language}) command selects the -conventions of Maple. - -Maple's language is much like C. Underscores are allowed in symbol -names; square brackets are used for subscripts; explicit @samp{*}s for -multiplications are required. Use either @samp{^} or @samp{**} to -denote powers. - -Maple uses square brackets for lists and curly braces for sets. Calc -interprets both notations as vectors, and displays vectors with square -brackets. This means Maple sets will be converted to lists when they -pass through Calc. As a special case, matrices are written as calls -to the function @code{matrix}, given a list of lists as the argument, -and can be read in this form or with all-capitals @code{MATRIX}. - -The Maple interval notation @samp{2 .. 3} is like Giac's interval -notation, and is handled the same by Calc. - -Maple writes complex numbers as @samp{3 + 4*I}. Its special constants -are @code{Pi}, @code{E}, @code{I}, and @code{infinity} (all three of -@code{inf}, @code{uinf}, and @code{nan} display as @code{infinity}). -Floating-point numbers are written @samp{1.23*10.^3}. - -Among things not currently handled by Calc's Maple mode are the -various quote symbols, procedures and functional operators, and -inert (@samp{&}) operators. - -@node Compositions, Syntax Tables, Maple Language Mode, Language Modes -@subsection Compositions - -@noindent -@cindex Compositions -There are several @dfn{composition functions} which allow you to get -displays in a variety of formats similar to those in Big language -mode. Most of these functions do not evaluate to anything; they are -placeholders which are left in symbolic form by Calc's evaluator but -are recognized by Calc's display formatting routines. - -Two of these, @code{string} and @code{bstring}, are described elsewhere. -@xref{Strings}. For example, @samp{string("ABC")} is displayed as -@samp{ABC}. When viewed on the stack it will be indistinguishable from -the variable @code{ABC}, but internally it will be stored as -@samp{string([65, 66, 67])} and can still be manipulated this way; for -example, the selection and vector commands @kbd{j 1 v v j u} would -select the vector portion of this object and reverse the elements, then -deselect to reveal a string whose characters had been reversed. - -The composition functions do the same thing in all language modes -(although their components will of course be formatted in the current -language mode). The one exception is Unformatted mode (@kbd{d U}), -which does not give the composition functions any special treatment. -The functions are discussed here because of their relationship to -the language modes. - -@menu -* Composition Basics:: -* Horizontal Compositions:: -* Vertical Compositions:: -* Other Compositions:: -* Information about Compositions:: -* User-Defined Compositions:: -@end menu - -@node Composition Basics, Horizontal Compositions, Compositions, Compositions -@subsubsection Composition Basics - -@noindent -Compositions are generally formed by stacking formulas together -horizontally or vertically in various ways. Those formulas are -themselves compositions. @TeX{} users will find this analogous -to @TeX{}'s ``boxes.'' Each multi-line composition has a -@dfn{baseline}; horizontal compositions use the baselines to -decide how formulas should be positioned relative to one another. -For example, in the Big mode formula - -@example -@group - 2 - a + b -17 + ------ - c -@end group -@end example - -@noindent -the second term of the sum is four lines tall and has line three as -its baseline. Thus when the term is combined with 17, line three -is placed on the same level as the baseline of 17. - -@tex -\bigskip -@end tex - -Another important composition concept is @dfn{precedence}. This is -an integer that represents the binding strength of various operators. -For example, @samp{*} has higher precedence (195) than @samp{+} (180), -which means that @samp{(a * b) + c} will be formatted without the -parentheses, but @samp{a * (b + c)} will keep the parentheses. - -The operator table used by normal and Big language modes has the -following precedences: - -@example -_ 1200 @r{(subscripts)} -% 1100 @r{(as in n}%@r{)} -! 1000 @r{(as in }!@r{n)} -mod 400 -+/- 300 -!! 210 @r{(as in n}!!@r{)} -! 210 @r{(as in n}!@r{)} -^ 200 -- 197 @r{(as in }-@r{n)} -* 195 @r{(or implicit multiplication)} -/ % \ 190 -+ - 180 @r{(as in a}+@r{b)} -| 170 -< = 160 @r{(and other relations)} -&& 110 -|| 100 -? : 90 -!!! 85 -&&& 80 -||| 75 -:= 50 -:: 45 -=> 40 -@end example - -The general rule is that if an operator with precedence @expr{n} -occurs as an argument to an operator with precedence @expr{m}, then -the argument is enclosed in parentheses if @expr{n < m}. Top-level -expressions and expressions which are function arguments, vector -components, etc., are formatted with precedence zero (so that they -normally never get additional parentheses). - -For binary left-associative operators like @samp{+}, the righthand -argument is actually formatted with one-higher precedence than shown -in the table. This makes sure @samp{(a + b) + c} omits the parentheses, -but the unnatural form @samp{a + (b + c)} keeps its parentheses. -Right-associative operators like @samp{^} format the lefthand argument -with one-higher precedence. - -@ignore -@starindex -@end ignore -@tindex cprec -The @code{cprec} function formats an expression with an arbitrary -precedence. For example, @samp{cprec(abc, 185)} will combine into -sums and products as follows: @samp{7 + abc}, @samp{7 (abc)} (because -this @code{cprec} form has higher precedence than addition, but lower -precedence than multiplication). - -@tex -\bigskip -@end tex - -A final composition issue is @dfn{line breaking}. Calc uses two -different strategies for ``flat'' and ``non-flat'' compositions. -A non-flat composition is anything that appears on multiple lines -(not counting line breaking). Examples would be matrices and Big -mode powers and quotients. Non-flat compositions are displayed -exactly as specified. If they come out wider than the current -window, you must use horizontal scrolling (@kbd{<} and @kbd{>}) to -view them. - -Flat compositions, on the other hand, will be broken across several -lines if they are too wide to fit the window. Certain points in a -composition are noted internally as @dfn{break points}. Calc's -general strategy is to fill each line as much as possible, then to -move down to the next line starting at the first break point that -didn't fit. However, the line breaker understands the hierarchical -structure of formulas. It will not break an ``inner'' formula if -it can use an earlier break point from an ``outer'' formula instead. -For example, a vector of sums might be formatted as: - -@example -@group -[ a + b + c, d + e + f, - g + h + i, j + k + l, m ] -@end group -@end example - -@noindent -If the @samp{m} can fit, then so, it seems, could the @samp{g}. -But Calc prefers to break at the comma since the comma is part -of a ``more outer'' formula. Calc would break at a plus sign -only if it had to, say, if the very first sum in the vector had -itself been too large to fit. - -Of the composition functions described below, only @code{choriz} -generates break points. The @code{bstring} function (@pxref{Strings}) -also generates breakable items: A break point is added after every -space (or group of spaces) except for spaces at the very beginning or -end of the string. - -Composition functions themselves count as levels in the formula -hierarchy, so a @code{choriz} that is a component of a larger -@code{choriz} will be less likely to be broken. As a special case, -if a @code{bstring} occurs as a component of a @code{choriz} or -@code{choriz}-like object (such as a vector or a list of arguments -in a function call), then the break points in that @code{bstring} -will be on the same level as the break points of the surrounding -object. - -@node Horizontal Compositions, Vertical Compositions, Composition Basics, Compositions -@subsubsection Horizontal Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex choriz -The @code{choriz} function takes a vector of objects and composes -them horizontally. For example, @samp{choriz([17, a b/c, d])} formats -as @w{@samp{17a b / cd}} in Normal language mode, or as - -@example -@group - a b -17---d - c -@end group -@end example - -@noindent -in Big language mode. This is actually one case of the general -function @samp{choriz(@var{vec}, @var{sep}, @var{prec})}, where -either or both of @var{sep} and @var{prec} may be omitted. -@var{Prec} gives the @dfn{precedence} to use when formatting -each of the components of @var{vec}. The default precedence is -the precedence from the surrounding environment. - -@var{Sep} is a string (i.e., a vector of character codes as might -be entered with @code{" "} notation) which should separate components -of the composition. Also, if @var{sep} is given, the line breaker -will allow lines to be broken after each occurrence of @var{sep}. -If @var{sep} is omitted, the composition will not be breakable -(unless any of its component compositions are breakable). - -For example, @samp{2 choriz([a, b c, d = e], " + ", 180)} is -formatted as @samp{2 a + b c + (d = e)}. To get the @code{choriz} -to have precedence 180 ``outwards'' as well as ``inwards,'' -enclose it in a @code{cprec} form: @samp{2 cprec(choriz(...), 180)} -formats as @samp{2 (a + b c + (d = e))}. - -The baseline of a horizontal composition is the same as the -baselines of the component compositions, which are all aligned. - -@node Vertical Compositions, Other Compositions, Horizontal Compositions, Compositions -@subsubsection Vertical Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex cvert -The @code{cvert} function makes a vertical composition. Each -component of the vector is centered in a column. The baseline of -the result is by default the top line of the resulting composition. -For example, @samp{f(cvert([a, bb, ccc]), cvert([a^2 + 1, b^2]))} -formats in Big mode as - -@example -@group -f( a , 2 ) - bb a + 1 - ccc 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex cbase -There are several special composition functions that work only as -components of a vertical composition. The @code{cbase} function -controls the baseline of the vertical composition; the baseline -will be the same as the baseline of whatever component is enclosed -in @code{cbase}. Thus @samp{f(cvert([a, cbase(bb), ccc]), -cvert([a^2 + 1, cbase(b^2)]))} displays as - -@example -@group - 2 - a + 1 - a 2 -f(bb , b ) - ccc -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex ctbase -@ignore -@starindex -@end ignore -@tindex cbbase -There are also @code{ctbase} and @code{cbbase} functions which -make the baseline of the vertical composition equal to the top -or bottom line (rather than the baseline) of that component. -Thus @samp{cvert([cbase(a / b)]) + cvert([ctbase(a / b)]) + -cvert([cbbase(a / b)])} gives - -@example -@group - a -a - -- + a + b -b - - b -@end group -@end example - -There should be only one @code{cbase}, @code{ctbase}, or @code{cbbase} -function in a given vertical composition. These functions can also -be written with no arguments: @samp{ctbase()} is a zero-height object -which means the baseline is the top line of the following item, and -@samp{cbbase()} means the baseline is the bottom line of the preceding -item. - -@ignore -@starindex -@end ignore -@tindex crule -The @code{crule} function builds a ``rule,'' or horizontal line, -across a vertical composition. By itself @samp{crule()} uses @samp{-} -characters to build the rule. You can specify any other character, -e.g., @samp{crule("=")}. The argument must be a character code or -vector of exactly one character code. It is repeated to match the -width of the widest item in the stack. For example, a quotient -with a thick line is @samp{cvert([a + 1, cbase(crule("=")), b^2])}: - -@example -@group -a + 1 -===== - 2 - b -@end group -@end example - -@ignore -@starindex -@end ignore -@tindex clvert -@ignore -@starindex -@end ignore -@tindex crvert -Finally, the functions @code{clvert} and @code{crvert} act exactly -like @code{cvert} except that the items are left- or right-justified -in the stack. Thus @samp{clvert([a, bb, ccc]) + crvert([a, bb, ccc])} -gives: - -@example -@group -a + a -bb bb -ccc ccc -@end group -@end example - -Like @code{choriz}, the vertical compositions accept a second argument -which gives the precedence to use when formatting the components. -Vertical compositions do not support separator strings. - -@node Other Compositions, Information about Compositions, Vertical Compositions, Compositions -@subsubsection Other Compositions - -@noindent -@ignore -@starindex -@end ignore -@tindex csup -The @code{csup} function builds a superscripted expression. For -example, @samp{csup(a, b)} looks the same as @samp{a^b} does in Big -language mode. This is essentially a horizontal composition of -@samp{a} and @samp{b}, where @samp{b} is shifted up so that its -bottom line is one above the baseline. - -@ignore -@starindex -@end ignore -@tindex csub -Likewise, the @code{csub} function builds a subscripted expression. -This shifts @samp{b} down so that its top line is one below the -bottom line of @samp{a} (note that this is not quite analogous to -@code{csup}). Other arrangements can be obtained by using -@code{choriz} and @code{cvert} directly. - -@ignore -@starindex -@end ignore -@tindex cflat -The @code{cflat} function formats its argument in ``flat'' mode, -as obtained by @samp{d O}, if the current language mode is normal -or Big. It has no effect in other language modes. For example, -@samp{a^(b/c)} is formatted by Big mode like @samp{csup(a, cflat(b/c))} -to improve its readability. - -@ignore -@starindex -@end ignore -@tindex cspace -The @code{cspace} function creates horizontal space. For example, -@samp{cspace(4)} is effectively the same as @samp{string(" ")}. -A second string (i.e., vector of characters) argument is repeated -instead of the space character. For example, @samp{cspace(4, "ab")} -looks like @samp{abababab}. If the second argument is not a string, -it is formatted in the normal way and then several copies of that -are composed together: @samp{cspace(4, a^2)} yields - -@example -@group - 2 2 2 2 -a a a a -@end group -@end example - -@noindent -If the number argument is zero, this is a zero-width object. - -@ignore -@starindex -@end ignore -@tindex cvspace -The @code{cvspace} function creates vertical space, or a vertical -stack of copies of a certain string or formatted object. The -baseline is the center line of the resulting stack. A numerical -argument of zero will produce an object which contributes zero -height if used in a vertical composition. - -@ignore -@starindex -@end ignore -@tindex ctspace -@ignore -@starindex -@end ignore -@tindex cbspace -There are also @code{ctspace} and @code{cbspace} functions which -create vertical space with the baseline the same as the baseline -of the top or bottom copy, respectively, of the second argument. -Thus @samp{cvspace(2, a/b) + ctspace(2, a/b) + cbspace(2, a/b)} -displays as: - -@example -@group - a - - -a b -- a a -b + - + - -a b b -- a -b - - b -@end group -@end example - -@node Information about Compositions, User-Defined Compositions, Other Compositions, Compositions -@subsubsection Information about Compositions - -@noindent -The functions in this section are actual functions; they compose their -arguments according to the current language and other display modes, -then return a certain measurement of the composition as an integer. - -@ignore -@starindex -@end ignore -@tindex cwidth -The @code{cwidth} function measures the width, in characters, of a -composition. For example, @samp{cwidth(a + b)} is 5, and -@samp{cwidth(a / b)} is 5 in Normal mode, 1 in Big mode, and 11 in -@TeX{} mode (for @samp{@{a \over b@}}). The argument may involve -the composition functions described in this section. - -@ignore -@starindex -@end ignore -@tindex cheight -The @code{cheight} function measures the height of a composition. -This is the total number of lines in the argument's printed form. - -@ignore -@starindex -@end ignore -@tindex cascent -@ignore -@starindex -@end ignore -@tindex cdescent -The functions @code{cascent} and @code{cdescent} measure the amount -of the height that is above (and including) the baseline, or below -the baseline, respectively. Thus @samp{cascent(@var{x}) + cdescent(@var{x})} -always equals @samp{cheight(@var{x})}. For a one-line formula like -@samp{a + b}, @code{cascent} returns 1 and @code{cdescent} returns 0. -For @samp{a / b} in Big mode, @code{cascent} returns 2 and @code{cdescent} -returns 1. The only formula for which @code{cascent} will return zero -is @samp{cvspace(0)} or equivalents. - -@node User-Defined Compositions, , Information about Compositions, Compositions -@subsubsection User-Defined Compositions - -@noindent -@kindex Z C -@pindex calc-user-define-composition -The @kbd{Z C} (@code{calc-user-define-composition}) command lets you -define the display format for any algebraic function. You provide a -formula containing a certain number of argument variables on the stack. -Any time Calc formats a call to the specified function in the current -language mode and with that number of arguments, Calc effectively -replaces the function call with that formula with the arguments -replaced. - -Calc builds the default argument list by sorting all the variable names -that appear in the formula into alphabetical order. You can edit this -argument list before pressing @key{RET} if you wish. Any variables in -the formula that do not appear in the argument list will be displayed -literally; any arguments that do not appear in the formula will not -affect the display at all. - -You can define formats for built-in functions, for functions you have -defined with @kbd{Z F} (@pxref{Algebraic Definitions}), or for functions -which have no definitions but are being used as purely syntactic objects. -You can define different formats for each language mode, and for each -number of arguments, using a succession of @kbd{Z C} commands. When -Calc formats a function call, it first searches for a format defined -for the current language mode (and number of arguments); if there is -none, it uses the format defined for the Normal language mode. If -neither format exists, Calc uses its built-in standard format for that -function (usually just @samp{@var{func}(@var{args})}). - -If you execute @kbd{Z C} with the number 0 on the stack instead of a -formula, any defined formats for the function in the current language -mode will be removed. The function will revert to its standard format. - -For example, the default format for the binomial coefficient function -@samp{choose(n, m)} in the Big language mode is - -@example -@group - n -( ) - m -@end group -@end example - -@noindent -You might prefer the notation, - -@example -@group - C -n m -@end group -@end example - -@noindent -To define this notation, first make sure you are in Big mode, -then put the formula - -@smallexample -choriz([cvert([cvspace(1), n]), C, cvert([cvspace(1), m])]) -@end smallexample - -@noindent -on the stack and type @kbd{Z C}. Answer the first prompt with -@code{choose}. The second prompt will be the default argument list -of @samp{(C m n)}. Edit this list to be @samp{(n m)} and press -@key{RET}. Now, try it out: For example, turn simplification -off with @kbd{m O} and enter @samp{choose(a,b) + choose(7,3)} -as an algebraic entry. - -@example -@group - C + C -a b 7 3 -@end group -@end example - -As another example, let's define the usual notation for Stirling -numbers of the first kind, @samp{stir1(n, m)}. This is just like -the regular format for binomial coefficients but with square brackets -instead of parentheses. - -@smallexample -choriz([string("["), cvert([n, cbase(cvspace(1)), m]), string("]")]) -@end smallexample - -Now type @kbd{Z C stir1 @key{RET}}, edit the argument list to -@samp{(n m)}, and type @key{RET}. - -The formula provided to @kbd{Z C} usually will involve composition -functions, but it doesn't have to. Putting the formula @samp{a + b + c} -onto the stack and typing @kbd{Z C foo @key{RET} @key{RET}} would define -the function @samp{foo(x,y,z)} to display like @samp{x + y + z}. -This ``sum'' will act exactly like a real sum for all formatting -purposes (it will be parenthesized the same, and so on). However -it will be computationally unrelated to a sum. For example, the -formula @samp{2 * foo(1, 2, 3)} will display as @samp{2 (1 + 2 + 3)}. -Operator precedences have caused the ``sum'' to be written in -parentheses, but the arguments have not actually been summed. -(Generally a display format like this would be undesirable, since -it can easily be confused with a real sum.) - -The special function @code{eval} can be used inside a @kbd{Z C} -composition formula to cause all or part of the formula to be -evaluated at display time. For example, if the formula is -@samp{a + eval(b + c)}, then @samp{foo(1, 2, 3)} will be displayed -as @samp{1 + 5}. Evaluation will use the default simplifications, -regardless of the current simplification mode. There are also -@code{evalsimp} and @code{evalextsimp} which simplify as if by -@kbd{a s} and @kbd{a e} (respectively). Note that these ``functions'' -operate only in the context of composition formulas (and also in -rewrite rules, where they serve a similar purpose; @pxref{Rewrite -Rules}). On the stack, a call to @code{eval} will be left in -symbolic form. - -It is not a good idea to use @code{eval} except as a last resort. -It can cause the display of formulas to be extremely slow. For -example, while @samp{eval(a + b)} might seem quite fast and simple, -there are several situations where it could be slow. For example, -@samp{a} and/or @samp{b} could be polar complex numbers, in which -case doing the sum requires trigonometry. Or, @samp{a} could be -the factorial @samp{fact(100)} which is unevaluated because you -have typed @kbd{m O}; @code{eval} will evaluate it anyway to -produce a large, unwieldy integer. - -You can save your display formats permanently using the @kbd{Z P} -command (@pxref{Creating User Keys}). - -@node Syntax Tables, , Compositions, Language Modes -@subsection Syntax Tables - -@noindent -@cindex Syntax tables -@cindex Parsing formulas, customized -Syntax tables do for input what compositions do for output: They -allow you to teach custom notations to Calc's formula parser. -Calc keeps a separate syntax table for each language mode. - -(Note that the Calc ``syntax tables'' discussed here are completely -unrelated to the syntax tables described in the Emacs manual.) - -@kindex Z S -@pindex calc-edit-user-syntax -The @kbd{Z S} (@code{calc-edit-user-syntax}) command edits the -syntax table for the current language mode. If you want your -syntax to work in any language, define it in the Normal language -mode. Type @kbd{C-c C-c} to finish editing the syntax table, or -@kbd{C-x k} to cancel the edit. The @kbd{m m} command saves all -the syntax tables along with the other mode settings; -@pxref{General Mode Commands}. - -@menu -* Syntax Table Basics:: -* Precedence in Syntax Tables:: -* Advanced Syntax Patterns:: -* Conditional Syntax Rules:: -@end menu - -@node Syntax Table Basics, Precedence in Syntax Tables, Syntax Tables, Syntax Tables -@subsubsection Syntax Table Basics - -@noindent -@dfn{Parsing} is the process of converting a raw string of characters, -such as you would type in during algebraic entry, into a Calc formula. -Calc's parser works in two stages. First, the input is broken down -into @dfn{tokens}, such as words, numbers, and punctuation symbols -like @samp{+}, @samp{:=}, and @samp{+/-}. Space between tokens is -ignored (except when it serves to separate adjacent words). Next, -the parser matches this string of tokens against various built-in -syntactic patterns, such as ``an expression followed by @samp{+} -followed by another expression'' or ``a name followed by @samp{(}, -zero or more expressions separated by commas, and @samp{)}.'' - -A @dfn{syntax table} is a list of user-defined @dfn{syntax rules}, -which allow you to specify new patterns to define your own -favorite input notations. Calc's parser always checks the syntax -table for the current language mode, then the table for the Normal -language mode, before it uses its built-in rules to parse an -algebraic formula you have entered. Each syntax rule should go on -its own line; it consists of a @dfn{pattern}, a @samp{:=} symbol, -and a Calc formula with an optional @dfn{condition}. (Syntax rules -resemble algebraic rewrite rules, but the notation for patterns is -completely different.) - -A syntax pattern is a list of tokens, separated by spaces. -Except for a few special symbols, tokens in syntax patterns are -matched literally, from left to right. For example, the rule, - -@example -foo ( ) := 2+3 -@end example - -@noindent -would cause Calc to parse the formula @samp{4+foo()*5} as if it -were @samp{4+(2+3)*5}. Notice that the parentheses were written -as two separate tokens in the rule. As a result, the rule works -for both @samp{foo()} and @w{@samp{foo ( )}}. If we had written -the rule as @samp{foo () := 2+3}, then Calc would treat @samp{()} -as a single, indivisible token, so that @w{@samp{foo( )}} would -not be recognized by the rule. (It would be parsed as a regular -zero-argument function call instead.) In fact, this rule would -also make trouble for the rest of Calc's parser: An unrelated -formula like @samp{bar()} would now be tokenized into @samp{bar ()} -instead of @samp{bar ( )}, so that the standard parser for function -calls would no longer recognize it! - -While it is possible to make a token with a mixture of letters -and punctuation symbols, this is not recommended. It is better to -break it into several tokens, as we did with @samp{foo()} above. - -The symbol @samp{#} in a syntax pattern matches any Calc expression. -On the righthand side, the things that matched the @samp{#}s can -be referred to as @samp{#1}, @samp{#2}, and so on (where @samp{#1} -matches the leftmost @samp{#} in the pattern). For example, these -rules match a user-defined function, prefix operator, infix operator, -and postfix operator, respectively: - -@example -foo ( # ) := myfunc(#1) -foo # := myprefix(#1) -# foo # := myinfix(#1,#2) -# foo := mypostfix(#1) -@end example - -Thus @samp{foo(3)} will parse as @samp{myfunc(3)}, and @samp{2+3 foo} -will parse as @samp{mypostfix(2+3)}. - -It is important to write the first two rules in the order shown, -because Calc tries rules in order from first to last. If the -pattern @samp{foo #} came first, it would match anything that could -match the @samp{foo ( # )} rule, since an expression in parentheses -is itself a valid expression. Thus the @w{@samp{foo ( # )}} rule would -never get to match anything. Likewise, the last two rules must be -written in the order shown or else @samp{3 foo 4} will be parsed as -@samp{mypostfix(3) * 4}. (Of course, the best way to avoid these -ambiguities is not to use the same symbol in more than one way at -the same time! In case you're not convinced, try the following -exercise: How will the above rules parse the input @samp{foo(3,4)}, -if at all? Work it out for yourself, then try it in Calc and see.) - -Calc is quite flexible about what sorts of patterns are allowed. -The only rule is that every pattern must begin with a literal -token (like @samp{foo} in the first two patterns above), or with -a @samp{#} followed by a literal token (as in the last two -patterns). After that, any mixture is allowed, although putting -two @samp{#}s in a row will not be very useful since two -expressions with nothing between them will be parsed as one -expression that uses implicit multiplication. - -As a more practical example, Maple uses the notation -@samp{sum(a(i), i=1..10)} for sums, which Calc's Maple mode doesn't -recognize at present. To handle this syntax, we simply add the -rule, - -@example -sum ( # , # = # .. # ) := sum(#1,#2,#3,#4) -@end example - -@noindent -to the Maple mode syntax table. As another example, C mode can't -read assignment operators like @samp{++} and @samp{*=}. We can -define these operators quite easily: - -@example -# *= # := muleq(#1,#2) -# ++ := postinc(#1) -++ # := preinc(#1) -@end example - -@noindent -To complete the job, we would use corresponding composition functions -and @kbd{Z C} to cause these functions to display in their respective -Maple and C notations. (Note that the C example ignores issues of -operator precedence, which are discussed in the next section.) - -You can enclose any token in quotes to prevent its usual -interpretation in syntax patterns: - -@example -# ":=" # := becomes(#1,#2) -@end example - -Quotes also allow you to include spaces in a token, although once -again it is generally better to use two tokens than one token with -an embedded space. To include an actual quotation mark in a quoted -token, precede it with a backslash. (This also works to include -backslashes in tokens.) - -@example -# "bad token" # "/\"\\" # := silly(#1,#2,#3) -@end example - -@noindent -This will parse @samp{3 bad token 4 /"\ 5} to @samp{silly(3,4,5)}. - -The token @kbd{#} has a predefined meaning in Calc's formula parser; -it is not valid to use @samp{"#"} in a syntax rule. However, longer -tokens that include the @samp{#} character are allowed. Also, while -@samp{"$"} and @samp{"\""} are allowed as tokens, their presence in -the syntax table will prevent those characters from working in their -usual ways (referring to stack entries and quoting strings, -respectively). - -Finally, the notation @samp{%%} anywhere in a syntax table causes -the rest of the line to be ignored as a comment. - -@node Precedence in Syntax Tables, Advanced Syntax Patterns, Syntax Table Basics, Syntax Tables -@subsubsection Precedence - -@noindent -Different operators are generally assigned different @dfn{precedences}. -By default, an operator defined by a rule like - -@example -# foo # := foo(#1,#2) -@end example - -@noindent -will have an extremely low precedence, so that @samp{2*3+4 foo 5 == 6} -will be parsed as @samp{(2*3+4) foo (5 == 6)}. To change the -precedence of an operator, use the notation @samp{#/@var{p}} in -place of @samp{#}, where @var{p} is an integer precedence level. -For example, 185 lies between the precedences for @samp{+} and -@samp{*}, so if we change this rule to - -@example -#/185 foo #/186 := foo(#1,#2) -@end example - -@noindent -then @samp{2+3 foo 4*5} will be parsed as @samp{2+(3 foo (4*5))}. -Also, because we've given the righthand expression slightly higher -precedence, our new operator will be left-associative: -@samp{1 foo 2 foo 3} will be parsed as @samp{(1 foo 2) foo 3}. -By raising the precedence of the lefthand expression instead, we -can create a right-associative operator. - -@xref{Composition Basics}, for a table of precedences of the -standard Calc operators. For the precedences of operators in other -language modes, look in the Calc source file @file{calc-lang.el}. - -@node Advanced Syntax Patterns, Conditional Syntax Rules, Precedence in Syntax Tables, Syntax Tables -@subsubsection Advanced Syntax Patterns - -@noindent -To match a function with a variable number of arguments, you could -write - -@example -foo ( # ) := myfunc(#1) -foo ( # , # ) := myfunc(#1,#2) -foo ( # , # , # ) := myfunc(#1,#2,#3) -@end example - -@noindent -but this isn't very elegant. To match variable numbers of items, -Calc uses some notations inspired regular expressions and the -``extended BNF'' style used by some language designers. - -@example -foo ( @{ # @}*, ) := apply(myfunc,#1) -@end example - -The token @samp{@{} introduces a repeated or optional portion. -One of the three tokens @samp{@}*}, @samp{@}+}, or @samp{@}?} -ends the portion. These will match zero or more, one or more, -or zero or one copies of the enclosed pattern, respectively. -In addition, @samp{@}*} and @samp{@}+} can be followed by a -separator token (with no space in between, as shown above). -Thus @samp{@{ # @}*,} matches nothing, or one expression, or -several expressions separated by commas. - -A complete @samp{@{ ... @}} item matches as a vector of the -items that matched inside it. For example, the above rule will -match @samp{foo(1,2,3)} to get @samp{apply(myfunc,[1,2,3])}. -The Calc @code{apply} function takes a function name and a vector -of arguments and builds a call to the function with those -arguments, so the net result is the formula @samp{myfunc(1,2,3)}. - -If the body of a @samp{@{ ... @}} contains several @samp{#}s -(or nested @samp{@{ ... @}} constructs), then the items will be -strung together into the resulting vector. If the body -does not contain anything but literal tokens, the result will -always be an empty vector. - -@example -foo ( @{ # , # @}+, ) := bar(#1) -foo ( @{ @{ # @}*, @}*; ) := matrix(#1) -@end example - -@noindent -will parse @samp{foo(1, 2, 3, 4)} as @samp{bar([1, 2, 3, 4])}, and -@samp{foo(1, 2; 3, 4)} as @samp{matrix([[1, 2], [3, 4]])}. Also, after -some thought it's easy to see how this pair of rules will parse -@samp{foo(1, 2, 3)} as @samp{matrix([[1, 2, 3]])}, since the first -rule will only match an even number of arguments. The rule - -@example -foo ( # @{ , # , # @}? ) := bar(#1,#2) -@end example - -@noindent -will parse @samp{foo(2,3,4)} as @samp{bar(2,[3,4])}, and -@samp{foo(2)} as @samp{bar(2,[])}. - -The notation @samp{@{ ... @}?.} (note the trailing period) works -just the same as regular @samp{@{ ... @}?}, except that it does not -count as an argument; the following two rules are equivalent: - -@example -foo ( # , @{ also @}? # ) := bar(#1,#3) -foo ( # , @{ also @}?. # ) := bar(#1,#2) -@end example - -@noindent -Note that in the first case the optional text counts as @samp{#2}, -which will always be an empty vector, but in the second case no -empty vector is produced. - -Another variant is @samp{@{ ... @}?$}, which means the body is -optional only at the end of the input formula. All built-in syntax -rules in Calc use this for closing delimiters, so that during -algebraic entry you can type @kbd{[sqrt(2), sqrt(3 @key{RET}}, omitting -the closing parenthesis and bracket. Calc does this automatically -for trailing @samp{)}, @samp{]}, and @samp{>} tokens in syntax -rules, but you can use @samp{@{ ... @}?$} explicitly to get -this effect with any token (such as @samp{"@}"} or @samp{end}). -Like @samp{@{ ... @}?.}, this notation does not count as an -argument. Conversely, you can use quotes, as in @samp{")"}, to -prevent a closing-delimiter token from being automatically treated -as optional. - -Calc's parser does not have full backtracking, which means some -patterns will not work as you might expect: - -@example -foo ( @{ # , @}? # , # ) := bar(#1,#2,#3) -@end example - -@noindent -Here we are trying to make the first argument optional, so that -@samp{foo(2,3)} parses as @samp{bar([],2,3)}. Unfortunately, Calc -first tries to match @samp{2,} against the optional part of the -pattern, finds a match, and so goes ahead to match the rest of the -pattern. Later on it will fail to match the second comma, but it -doesn't know how to go back and try the other alternative at that -point. One way to get around this would be to use two rules: - -@example -foo ( # , # , # ) := bar([#1],#2,#3) -foo ( # , # ) := bar([],#1,#2) -@end example - -More precisely, when Calc wants to match an optional or repeated -part of a pattern, it scans forward attempting to match that part. -If it reaches the end of the optional part without failing, it -``finalizes'' its choice and proceeds. If it fails, though, it -backs up and tries the other alternative. Thus Calc has ``partial'' -backtracking. A fully backtracking parser would go on to make sure -the rest of the pattern matched before finalizing the choice. - -@node Conditional Syntax Rules, , Advanced Syntax Patterns, Syntax Tables -@subsubsection Conditional Syntax Rules - -@noindent -It is possible to attach a @dfn{condition} to a syntax rule. For -example, the rules - -@example -foo ( # ) := ifoo(#1) :: integer(#1) -foo ( # ) := gfoo(#1) -@end example - -@noindent -will parse @samp{foo(3)} as @samp{ifoo(3)}, but will parse -@samp{foo(3.5)} and @samp{foo(x)} as calls to @code{gfoo}. Any -number of conditions may be attached; all must be true for the -rule to succeed. A condition is ``true'' if it evaluates to a -nonzero number. @xref{Logical Operations}, for a list of Calc -functions like @code{integer} that perform logical tests. - -The exact sequence of events is as follows: When Calc tries a -rule, it first matches the pattern as usual. It then substitutes -@samp{#1}, @samp{#2}, etc., in the conditions, if any. Next, the -conditions are simplified and evaluated in order from left to right, -as if by the @w{@kbd{a s}} algebra command (@pxref{Simplifying Formulas}). -Each result is true if it is a nonzero number, or an expression -that can be proven to be nonzero (@pxref{Declarations}). If the -results of all conditions are true, the expression (such as -@samp{ifoo(#1)}) has its @samp{#}s substituted, and that is the -result of the parse. If the result of any condition is false, Calc -goes on to try the next rule in the syntax table. - -Syntax rules also support @code{let} conditions, which operate in -exactly the same way as they do in algebraic rewrite rules. -@xref{Other Features of Rewrite Rules}, for details. A @code{let} -condition is always true, but as a side effect it defines a -variable which can be used in later conditions, and also in the -expression after the @samp{:=} sign: - -@example -foo ( # ) := hifoo(x) :: let(x := #1 + 0.5) :: dnumint(x) -@end example - -@noindent -The @code{dnumint} function tests if a value is numerically an -integer, i.e., either a true integer or an integer-valued float. -This rule will parse @code{foo} with a half-integer argument, -like @samp{foo(3.5)}, to a call like @samp{hifoo(4.)}. - -The lefthand side of a syntax rule @code{let} must be a simple -variable, not the arbitrary pattern that is allowed in rewrite -rules. - -The @code{matches} function is also treated specially in syntax -rule conditions (again, in the same way as in rewrite rules). -@xref{Matching Commands}. If the matching pattern contains -meta-variables, then those meta-variables may be used in later -conditions and in the result expression. The arguments to -@code{matches} are not evaluated in this situation. - -@example -sum ( # , # ) := sum(#1,a,b,c) :: matches(#2, a=[b..c]) -@end example - -@noindent -This is another way to implement the Maple mode @code{sum} notation. -In this approach, we allow @samp{#2} to equal the whole expression -@samp{i=1..10}. Then, we use @code{matches} to break it apart into -its components. If the expression turns out not to match the pattern, -the syntax rule will fail. Note that @kbd{Z S} always uses Calc's -Normal language mode for editing expressions in syntax rules, so we -must use regular Calc notation for the interval @samp{[b..c]} that -will correspond to the Maple mode interval @samp{1..10}. - -@node Modes Variable, Calc Mode Line, Language Modes, Mode Settings -@section The @code{Modes} Variable - -@noindent -@kindex m g -@pindex calc-get-modes -The @kbd{m g} (@code{calc-get-modes}) command pushes onto the stack -a vector of numbers that describes the various mode settings that -are in effect. With a numeric prefix argument, it pushes only the -@var{n}th mode, i.e., the @var{n}th element of this vector. Keyboard -macros can use the @kbd{m g} command to modify their behavior based -on the current mode settings. - -@cindex @code{Modes} variable -@vindex Modes -The modes vector is also available in the special variable -@code{Modes}. In other words, @kbd{m g} is like @kbd{s r Modes @key{RET}}. -It will not work to store into this variable; in fact, if you do, -@code{Modes} will cease to track the current modes. (The @kbd{m g} -command will continue to work, however.) - -In general, each number in this vector is suitable as a numeric -prefix argument to the associated mode-setting command. (Recall -that the @kbd{~} key takes a number from the stack and gives it as -a numeric prefix to the next command.) - -The elements of the modes vector are as follows: - -@enumerate -@item -Current precision. Default is 12; associated command is @kbd{p}. - -@item -Binary word size. Default is 32; associated command is @kbd{b w}. - -@item -Stack size (not counting the value about to be pushed by @kbd{m g}). -This is zero if @kbd{m g} is executed with an empty stack. - -@item -Number radix. Default is 10; command is @kbd{d r}. - -@item -Floating-point format. This is the number of digits, plus the -constant 0 for normal notation, 10000 for scientific notation, -20000 for engineering notation, or 30000 for fixed-point notation. -These codes are acceptable as prefix arguments to the @kbd{d n} -command, but note that this may lose information: For example, -@kbd{d s} and @kbd{C-u 12 d s} have similar (but not quite -identical) effects if the current precision is 12, but they both -produce a code of 10012, which will be treated by @kbd{d n} as -@kbd{C-u 12 d s}. If the precision then changes, the float format -will still be frozen at 12 significant figures. - -@item -Angular mode. Default is 1 (degrees). Other values are 2 (radians) -and 3 (HMS). The @kbd{m d} command accepts these prefixes. - -@item -Symbolic mode. Value is 0 or 1; default is 0. Command is @kbd{m s}. - -@item -Fraction mode. Value is 0 or 1; default is 0. Command is @kbd{m f}. - -@item -Polar mode. Value is 0 (rectangular) or 1 (polar); default is 0. -Command is @kbd{m p}. - -@item -Matrix/Scalar mode. Default value is @mathit{-1}. Value is 0 for Scalar -mode, @mathit{-2} for Matrix mode, @mathit{-3} for square Matrix mode, -or @var{N} for -@texline @math{N\times N} -@infoline @var{N}x@var{N} -Matrix mode. Command is @kbd{m v}. - -@item -Simplification mode. Default is 1. Value is @mathit{-1} for off (@kbd{m O}), -0 for @kbd{m N}, 2 for @kbd{m B}, 3 for @kbd{m A}, 4 for @kbd{m E}, -or 5 for @w{@kbd{m U}}. The @kbd{m D} command accepts these prefixes. - -@item -Infinite mode. Default is @mathit{-1} (off). Value is 1 if the mode is on, -or 0 if the mode is on with positive zeros. Command is @kbd{m i}. -@end enumerate - -For example, the sequence @kbd{M-1 m g @key{RET} 2 + ~ p} increases the -precision by two, leaving a copy of the old precision on the stack. -Later, @kbd{~ p} will restore the original precision using that -stack value. (This sequence might be especially useful inside a -keyboard macro.) - -As another example, @kbd{M-3 m g 1 - ~ @key{DEL}} deletes all but the -oldest (bottommost) stack entry. - -Yet another example: The HP-48 ``round'' command rounds a number -to the current displayed precision. You could roughly emulate this -in Calc with the sequence @kbd{M-5 m g 10000 % ~ c c}. (This -would not work for fixed-point mode, but it wouldn't be hard to -do a full emulation with the help of the @kbd{Z [} and @kbd{Z ]} -programming commands. @xref{Conditionals in Macros}.) - -@node Calc Mode Line, , Modes Variable, Mode Settings -@section The Calc Mode Line - -@noindent -@cindex Mode line indicators -This section is a summary of all symbols that can appear on the -Calc mode line, the highlighted bar that appears under the Calc -stack window (or under an editing window in Embedded mode). - -The basic mode line format is: - -@example ---%*-Calc: 12 Deg @var{other modes} (Calculator) -@end example - -The @samp{%*} indicates that the buffer is ``read-only''; it shows that -regular Emacs commands are not allowed to edit the stack buffer -as if it were text. - -The word @samp{Calc:} changes to @samp{CalcEmbed:} if Embedded mode -is enabled. The words after this describe the various Calc modes -that are in effect. - -The first mode is always the current precision, an integer. -The second mode is always the angular mode, either @code{Deg}, -@code{Rad}, or @code{Hms}. - -Here is a complete list of the remaining symbols that can appear -on the mode line: - -@table @code -@item Alg -Algebraic mode (@kbd{m a}; @pxref{Algebraic Entry}). - -@item Alg[( -Incomplete algebraic mode (@kbd{C-u m a}). - -@item Alg* -Total algebraic mode (@kbd{m t}). - -@item Symb -Symbolic mode (@kbd{m s}; @pxref{Symbolic Mode}). - -@item Matrix -Matrix mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Matrix@var{n} -Dimensioned Matrix mode (@kbd{C-u @var{n} m v}; @pxref{Matrix Mode}). - -@item SqMatrix -Square Matrix mode (@kbd{C-u m v}; @pxref{Matrix Mode}). - -@item Scalar -Scalar mode (@kbd{m v}; @pxref{Matrix Mode}). - -@item Polar -Polar complex mode (@kbd{m p}; @pxref{Polar Mode}). - -@item Frac -Fraction mode (@kbd{m f}; @pxref{Fraction Mode}). - -@item Inf -Infinite mode (@kbd{m i}; @pxref{Infinite Mode}). - -@item +Inf -Positive Infinite mode (@kbd{C-u 0 m i}). - -@item NoSimp -Default simplifications off (@kbd{m O}; @pxref{Simplification Modes}). - -@item NumSimp -Default simplifications for numeric arguments only (@kbd{m N}). - -@item BinSimp@var{w} -Binary-integer simplification mode; word size @var{w} (@kbd{m B}, @kbd{b w}). - -@item AlgSimp -Algebraic simplification mode (@kbd{m A}). - -@item ExtSimp -Extended algebraic simplification mode (@kbd{m E}). - -@item UnitSimp -Units simplification mode (@kbd{m U}). - -@item Bin -Current radix is 2 (@kbd{d 2}; @pxref{Radix Modes}). - -@item Oct -Current radix is 8 (@kbd{d 8}). - -@item Hex -Current radix is 16 (@kbd{d 6}). - -@item Radix@var{n} -Current radix is @var{n} (@kbd{d r}). - -@item Zero -Leading zeros (@kbd{d z}; @pxref{Radix Modes}). - -@item Big -Big language mode (@kbd{d B}; @pxref{Normal Language Modes}). - -@item Flat -One-line normal language mode (@kbd{d O}). - -@item Unform -Unformatted language mode (@kbd{d U}). - -@item C -C language mode (@kbd{d C}; @pxref{C FORTRAN Pascal}). - -@item Pascal -Pascal language mode (@kbd{d P}). - -@item Fortran -FORTRAN language mode (@kbd{d F}). - -@item TeX -@TeX{} language mode (@kbd{d T}; @pxref{TeX and LaTeX Language Modes}). - -@item LaTeX -La@TeX{} language mode (@kbd{d L}; @pxref{TeX and LaTeX Language Modes}). - -@item Eqn -@dfn{Eqn} language mode (@kbd{d E}; @pxref{Eqn Language Mode}). - -@item Math -Mathematica language mode (@kbd{d M}; @pxref{Mathematica Language Mode}). - -@item Maple -Maple language mode (@kbd{d W}; @pxref{Maple Language Mode}). - -@item Norm@var{n} -Normal float mode with @var{n} digits (@kbd{d n}; @pxref{Float Formats}). - -@item Fix@var{n} -Fixed point mode with @var{n} digits after the point (@kbd{d f}). - -@item Sci -Scientific notation mode (@kbd{d s}). - -@item Sci@var{n} -Scientific notation with @var{n} digits (@kbd{d s}). - -@item Eng -Engineering notation mode (@kbd{d e}). - -@item Eng@var{n} -Engineering notation with @var{n} digits (@kbd{d e}). - -@item Left@var{n} -Left-justified display indented by @var{n} (@kbd{d <}; @pxref{Justification}). - -@item Right -Right-justified display (@kbd{d >}). - -@item Right@var{n} -Right-justified display with width @var{n} (@kbd{d >}). - -@item Center -Centered display (@kbd{d =}). - -@item Center@var{n} -Centered display with center column @var{n} (@kbd{d =}). - -@item Wid@var{n} -Line breaking with width @var{n} (@kbd{d b}; @pxref{Normal Language Modes}). - -@item Wide -No line breaking (@kbd{d b}). - -@item Break -Selections show deep structure (@kbd{j b}; @pxref{Making Selections}). - -@item Save -Record modes in @file{~/.calc.el} (@kbd{m R}; @pxref{General Mode Commands}). - -@item Local -Record modes in Embedded buffer (@kbd{m R}). - -@item LocEdit -Record modes as editing-only in Embedded buffer (@kbd{m R}). - -@item LocPerm -Record modes as permanent-only in Embedded buffer (@kbd{m R}). - -@item Global -Record modes as global in Embedded buffer (@kbd{m R}). - -@item Manual -Automatic recomputation turned off (@kbd{m C}; @pxref{Automatic -Recomputation}). - -@item Graph -GNUPLOT process is alive in background (@pxref{Graphics}). - -@item Sel -Top-of-stack has a selection (Embedded only; @pxref{Making Selections}). - -@item Dirty -The stack display may not be up-to-date (@pxref{Display Modes}). - -@item Inv -``Inverse'' prefix was pressed (@kbd{I}; @pxref{Inverse and Hyperbolic}). - -@item Hyp -``Hyperbolic'' prefix was pressed (@kbd{H}). - -@item Keep -``Keep-arguments'' prefix was pressed (@kbd{K}). - -@item Narrow -Stack is truncated (@kbd{d t}; @pxref{Truncating the Stack}). -@end table - -In addition, the symbols @code{Active} and @code{~Active} can appear -as minor modes on an Embedded buffer's mode line. @xref{Embedded Mode}. - -@node Arithmetic, Scientific Functions, Mode Settings, Top -@chapter Arithmetic Functions - -@noindent -This chapter describes the Calc commands for doing simple calculations -on numbers, such as addition, absolute value, and square roots. These -commands work by removing the top one or two values from the stack, -performing the desired operation, and pushing the result back onto the -stack. If the operation cannot be performed, the result pushed is a -formula instead of a number, such as @samp{2/0} (because division by zero -is invalid) or @samp{sqrt(x)} (because the argument @samp{x} is a formula). - -Most of the commands described here can be invoked by a single keystroke. -Some of the more obscure ones are two-letter sequences beginning with -the @kbd{f} (``functions'') prefix key. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Basic Arithmetic:: -* Integer Truncation:: -* Complex Number Functions:: -* Conversions:: -* Date Arithmetic:: -* Financial Functions:: -* Binary Functions:: -@end menu - -@node Basic Arithmetic, Integer Truncation, Arithmetic, Arithmetic -@section Basic Arithmetic - -@noindent -@kindex + -@pindex calc-plus -@ignore -@mindex @null -@end ignore -@tindex + -The @kbd{+} (@code{calc-plus}) command adds two numbers. The numbers may -be any of the standard Calc data types. The resulting sum is pushed back -onto the stack. - -If both arguments of @kbd{+} are vectors or matrices (of matching dimensions), -the result is a vector or matrix sum. If one argument is a vector and the -other a scalar (i.e., a non-vector), the scalar is added to each of the -elements of the vector to form a new vector. If the scalar is not a -number, the operation is left in symbolic form: Suppose you added @samp{x} -to the vector @samp{[1,2]}. You may want the result @samp{[1+x,2+x]}, or -you may plan to substitute a 2-vector for @samp{x} in the future. Since -the Calculator can't tell which interpretation you want, it makes the -safest assumption. @xref{Reducing and Mapping}, for a way to add @samp{x} -to every element of a vector. - -If either argument of @kbd{+} is a complex number, the result will in general -be complex. If one argument is in rectangular form and the other polar, -the current Polar mode determines the form of the result. If Symbolic -mode is enabled, the sum may be left as a formula if the necessary -conversions for polar addition are non-trivial. - -If both arguments of @kbd{+} are HMS forms, the forms are added according to -the usual conventions of hours-minutes-seconds notation. If one argument -is an HMS form and the other is a number, that number is converted from -degrees or radians (depending on the current Angular mode) to HMS format -and then the two HMS forms are added. - -If one argument of @kbd{+} is a date form, the other can be either a -real number, which advances the date by a certain number of days, or -an HMS form, which advances the date by a certain amount of time. -Subtracting two date forms yields the number of days between them. -Adding two date forms is meaningless, but Calc interprets it as the -subtraction of one date form and the negative of the other. (The -negative of a date form can be understood by remembering that dates -are stored as the number of days before or after Jan 1, 1 AD.) - -If both arguments of @kbd{+} are error forms, the result is an error form -with an appropriately computed standard deviation. If one argument is an -error form and the other is a number, the number is taken to have zero error. -Error forms may have symbolic formulas as their mean and/or error parts; -adding these will produce a symbolic error form result. However, adding an -error form to a plain symbolic formula (as in @samp{(a +/- b) + c}) will not -work, for the same reasons just mentioned for vectors. Instead you must -write @samp{(a +/- b) + (c +/- 0)}. - -If both arguments of @kbd{+} are modulo forms with equal values of @expr{M}, -or if one argument is a modulo form and the other a plain number, the -result is a modulo form which represents the sum, modulo @expr{M}, of -the two values. - -If both arguments of @kbd{+} are intervals, the result is an interval -which describes all possible sums of the possible input values. If -one argument is a plain number, it is treated as the interval -@w{@samp{[x ..@: x]}}. - -If one argument of @kbd{+} is an infinity and the other is not, the -result is that same infinity. If both arguments are infinite and in -the same direction, the result is the same infinity, but if they are -infinite in different directions the result is @code{nan}. - -@kindex - -@pindex calc-minus -@ignore -@mindex @null -@end ignore -@tindex - -The @kbd{-} (@code{calc-minus}) command subtracts two values. The top -number on the stack is subtracted from the one behind it, so that the -computation @kbd{5 @key{RET} 2 -} produces 3, not @mathit{-3}. All options -available for @kbd{+} are available for @kbd{-} as well. - -@kindex * -@pindex calc-times -@ignore -@mindex @null -@end ignore -@tindex * -The @kbd{*} (@code{calc-times}) command multiplies two numbers. If one -argument is a vector and the other a scalar, the scalar is multiplied by -the elements of the vector to produce a new vector. If both arguments -are vectors, the interpretation depends on the dimensions of the -vectors: If both arguments are matrices, a matrix multiplication is -done. If one argument is a matrix and the other a plain vector, the -vector is interpreted as a row vector or column vector, whichever is -dimensionally correct. If both arguments are plain vectors, the result -is a single scalar number which is the dot product of the two vectors. - -If one argument of @kbd{*} is an HMS form and the other a number, the -HMS form is multiplied by that amount. It is an error to multiply two -HMS forms together, or to attempt any multiplication involving date -forms. Error forms, modulo forms, and intervals can be multiplied; -see the comments for addition of those forms. When two error forms -or intervals are multiplied they are considered to be statistically -independent; thus, @samp{[-2 ..@: 3] * [-2 ..@: 3]} is @samp{[-6 ..@: 9]}, -whereas @w{@samp{[-2 ..@: 3] ^ 2}} is @samp{[0 ..@: 9]}. - -@kindex / -@pindex calc-divide -@ignore -@mindex @null -@end ignore -@tindex / -The @kbd{/} (@code{calc-divide}) command divides two numbers. - -When combining multiplication and division in an algebraic formula, it -is good style to use parentheses to distinguish between possible -interpretations; the expression @samp{a/b*c} should be written -@samp{(a/b)*c} or @samp{a/(b*c)}, as appropriate. Without the -parentheses, Calc will interpret @samp{a/b*c} as @samp{a/(b*c)}, since -in algebraic entry Calc gives division a lower precedence than -multiplication. (This is not standard across all computer languages, and -Calc may change the precedence depending on the language mode being used. -@xref{Language Modes}.) This default ordering can be changed by setting -the customizable variable @code{calc-multiplication-has-precedence} to -@code{nil} (@pxref{Customizing Calc}); this will give multiplication and -division equal precedences. Note that Calc's default choice of -precedence allows @samp{a b / c d} to be used as a shortcut for -@smallexample -@group -a b ----. -c d -@end group -@end smallexample - -When dividing a scalar @expr{B} by a square matrix @expr{A}, the -computation performed is @expr{B} times the inverse of @expr{A}. This -also occurs if @expr{B} is itself a vector or matrix, in which case the -effect is to solve the set of linear equations represented by @expr{B}. -If @expr{B} is a matrix with the same number of rows as @expr{A}, or a -plain vector (which is interpreted here as a column vector), then the -equation @expr{A X = B} is solved for the vector or matrix @expr{X}. -Otherwise, if @expr{B} is a non-square matrix with the same number of -@emph{columns} as @expr{A}, the equation @expr{X A = B} is solved. If -you wish a vector @expr{B} to be interpreted as a row vector to be -solved as @expr{X A = B}, make it into a one-row matrix with @kbd{C-u 1 -v p} first. To force a left-handed solution with a square matrix -@expr{B}, transpose @expr{A} and @expr{B} before dividing, then -transpose the result. - -HMS forms can be divided by real numbers or by other HMS forms. Error -forms can be divided in any combination of ways. Modulo forms where both -values and the modulo are integers can be divided to get an integer modulo -form result. Intervals can be divided; dividing by an interval that -encompasses zero or has zero as a limit will result in an infinite -interval. - -@kindex ^ -@pindex calc-power -@ignore -@mindex @null -@end ignore -@tindex ^ -The @kbd{^} (@code{calc-power}) command raises a number to a power. If -the power is an integer, an exact result is computed using repeated -multiplications. For non-integer powers, Calc uses Newton's method or -logarithms and exponentials. Square matrices can be raised to integer -powers. If either argument is an error (or interval or modulo) form, -the result is also an error (or interval or modulo) form. - -@kindex I ^ -@tindex nroot -If you press the @kbd{I} (inverse) key first, the @kbd{I ^} command -computes an Nth root: @kbd{125 @key{RET} 3 I ^} computes the number 5. -(This is entirely equivalent to @kbd{125 @key{RET} 1:3 ^}.) - -@kindex \ -@pindex calc-idiv -@tindex idiv -@ignore -@mindex @null -@end ignore -@tindex \ -The @kbd{\} (@code{calc-idiv}) command divides two numbers on the stack -to produce an integer result. It is equivalent to dividing with -@key{/}, then rounding down with @kbd{F} (@code{calc-floor}), only a bit -more convenient and efficient. Also, since it is an all-integer -operation when the arguments are integers, it avoids problems that -@kbd{/ F} would have with floating-point roundoff. - -@kindex % -@pindex calc-mod -@ignore -@mindex @null -@end ignore -@tindex % -The @kbd{%} (@code{calc-mod}) command performs a ``modulo'' (or ``remainder'') -operation. Mathematically, @samp{a%b = a - (a\b)*b}, and is defined -for all real numbers @expr{a} and @expr{b} (except @expr{b=0}). For -positive @expr{b}, the result will always be between 0 (inclusive) and -@expr{b} (exclusive). Modulo does not work for HMS forms and error forms. -If @expr{a} is a modulo form, its modulo is changed to @expr{b}, which -must be positive real number. - -@kindex : -@pindex calc-fdiv -@tindex fdiv -The @kbd{:} (@code{calc-fdiv}) [@code{fdiv}] command -divides the two integers on the top of the stack to produce a fractional -result. This is a convenient shorthand for enabling Fraction mode (with -@kbd{m f}) temporarily and using @samp{/}. Note that during numeric entry -the @kbd{:} key is interpreted as a fraction separator, so to divide 8 by 6 -you would have to type @kbd{8 @key{RET} 6 @key{RET} :}. (Of course, in -this case, it would be much easier simply to enter the fraction directly -as @kbd{8:6 @key{RET}}!) - -@kindex n -@pindex calc-change-sign -The @kbd{n} (@code{calc-change-sign}) command negates the number on the top -of the stack. It works on numbers, vectors and matrices, HMS forms, date -forms, error forms, intervals, and modulo forms. - -@kindex A -@pindex calc-abs -@tindex abs -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the absolute -value of a number. The result of @code{abs} is always a nonnegative -real number: With a complex argument, it computes the complex magnitude. -With a vector or matrix argument, it computes the Frobenius norm, i.e., -the square root of the sum of the squares of the absolute values of the -elements. The absolute value of an error form is defined by replacing -the mean part with its absolute value and leaving the error part the same. -The absolute value of a modulo form is undefined. The absolute value of -an interval is defined in the obvious way. - -@kindex f A -@pindex calc-abssqr -@tindex abssqr -The @kbd{f A} (@code{calc-abssqr}) [@code{abssqr}] command computes the -absolute value squared of a number, vector or matrix, or error form. - -@kindex f s -@pindex calc-sign -@tindex sign -The @kbd{f s} (@code{calc-sign}) [@code{sign}] command returns 1 if its -argument is positive, @mathit{-1} if its argument is negative, or 0 if its -argument is zero. In algebraic form, you can also write @samp{sign(a,x)} -which evaluates to @samp{x * sign(a)}, i.e., either @samp{x}, @samp{-x}, or -zero depending on the sign of @samp{a}. - -@kindex & -@pindex calc-inv -@tindex inv -@cindex Reciprocal -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -reciprocal of a number, i.e., @expr{1 / x}. Operating on a square -matrix, it computes the inverse of that matrix. - -@kindex Q -@pindex calc-sqrt -@tindex sqrt -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] command computes the square -root of a number. For a negative real argument, the result will be a -complex number whose form is determined by the current Polar mode. - -@kindex f h -@pindex calc-hypot -@tindex hypot -The @kbd{f h} (@code{calc-hypot}) [@code{hypot}] command computes the square -root of the sum of the squares of two numbers. That is, @samp{hypot(a,b)} -is the length of the hypotenuse of a right triangle with sides @expr{a} -and @expr{b}. If the arguments are complex numbers, their squared -magnitudes are used. - -@kindex f Q -@pindex calc-isqrt -@tindex isqrt -The @kbd{f Q} (@code{calc-isqrt}) [@code{isqrt}] command computes the -integer square root of an integer. This is the true square root of the -number, rounded down to an integer. For example, @samp{isqrt(10)} -produces 3. Note that, like @kbd{\} [@code{idiv}], this uses exact -integer arithmetic throughout to avoid roundoff problems. If the input -is a floating-point number or other non-integer value, this is exactly -the same as @samp{floor(sqrt(x))}. - -@kindex f n -@kindex f x -@pindex calc-min -@tindex min -@pindex calc-max -@tindex max -The @kbd{f n} (@code{calc-min}) [@code{min}] and @kbd{f x} (@code{calc-max}) -[@code{max}] commands take the minimum or maximum of two real numbers, -respectively. These commands also work on HMS forms, date forms, -intervals, and infinities. (In algebraic expressions, these functions -take any number of arguments and return the maximum or minimum among -all the arguments.) - -@kindex f M -@kindex f X -@pindex calc-mant-part -@tindex mant -@pindex calc-xpon-part -@tindex xpon -The @kbd{f M} (@code{calc-mant-part}) [@code{mant}] function extracts -the ``mantissa'' part @expr{m} of its floating-point argument; @kbd{f X} -(@code{calc-xpon-part}) [@code{xpon}] extracts the ``exponent'' part -@expr{e}. The original number is equal to -@texline @math{m \times 10^e}, -@infoline @expr{m * 10^e}, -where @expr{m} is in the interval @samp{[1.0 ..@: 10.0)} except that -@expr{m=e=0} if the original number is zero. For integers -and fractions, @code{mant} returns the number unchanged and @code{xpon} -returns zero. The @kbd{v u} (@code{calc-unpack}) command can also be -used to ``unpack'' a floating-point number; this produces an integer -mantissa and exponent, with the constraint that the mantissa is not -a multiple of ten (again except for the @expr{m=e=0} case). - -@kindex f S -@pindex calc-scale-float -@tindex scf -The @kbd{f S} (@code{calc-scale-float}) [@code{scf}] function scales a number -by a given power of ten. Thus, @samp{scf(mant(x), xpon(x)) = x} for any -real @samp{x}. The second argument must be an integer, but the first -may actually be any numeric value. For example, @samp{scf(5,-2) = 0.05} -or @samp{1:20} depending on the current Fraction mode. - -@kindex f [ -@kindex f ] -@pindex calc-decrement -@pindex calc-increment -@tindex decr -@tindex incr -The @kbd{f [} (@code{calc-decrement}) [@code{decr}] and @kbd{f ]} -(@code{calc-increment}) [@code{incr}] functions decrease or increase -a number by one unit. For integers, the effect is obvious. For -floating-point numbers, the change is by one unit in the last place. -For example, incrementing @samp{12.3456} when the current precision -is 6 digits yields @samp{12.3457}. If the current precision had been -8 digits, the result would have been @samp{12.345601}. Incrementing -@samp{0.0} produces -@texline @math{10^{-p}}, -@infoline @expr{10^-p}, -where @expr{p} is the current -precision. These operations are defined only on integers and floats. -With numeric prefix arguments, they change the number by @expr{n} units. - -Note that incrementing followed by decrementing, or vice-versa, will -almost but not quite always cancel out. Suppose the precision is -6 digits and the number @samp{9.99999} is on the stack. Incrementing -will produce @samp{10.0000}; decrementing will produce @samp{9.9999}. -One digit has been dropped. This is an unavoidable consequence of the -way floating-point numbers work. - -Incrementing a date/time form adjusts it by a certain number of seconds. -Incrementing a pure date form adjusts it by a certain number of days. - -@node Integer Truncation, Complex Number Functions, Basic Arithmetic, Arithmetic -@section Integer Truncation - -@noindent -There are four commands for truncating a real number to an integer, -differing mainly in their treatment of negative numbers. All of these -commands have the property that if the argument is an integer, the result -is the same integer. An integer-valued floating-point argument is converted -to integer form. - -If you press @kbd{H} (@code{calc-hyperbolic}) first, the result will be -expressed as an integer-valued floating-point number. - -@cindex Integer part of a number -@kindex F -@pindex calc-floor -@tindex floor -@tindex ffloor -@ignore -@mindex @null -@end ignore -@kindex H F -The @kbd{F} (@code{calc-floor}) [@code{floor} or @code{ffloor}] command -truncates a real number to the next lower integer, i.e., toward minus -infinity. Thus @kbd{3.6 F} produces 3, but @kbd{_3.6 F} produces -@mathit{-4}. - -@kindex I F -@pindex calc-ceiling -@tindex ceil -@tindex fceil -@ignore -@mindex @null -@end ignore -@kindex H I F -The @kbd{I F} (@code{calc-ceiling}) [@code{ceil} or @code{fceil}] -command truncates toward positive infinity. Thus @kbd{3.6 I F} produces -4, and @kbd{_3.6 I F} produces @mathit{-3}. - -@kindex R -@pindex calc-round -@tindex round -@tindex fround -@ignore -@mindex @null -@end ignore -@kindex H R -The @kbd{R} (@code{calc-round}) [@code{round} or @code{fround}] command -rounds to the nearest integer. When the fractional part is .5 exactly, -this command rounds away from zero. (All other rounding in the -Calculator uses this convention as well.) Thus @kbd{3.5 R} produces 4 -but @kbd{3.4 R} produces 3; @kbd{_3.5 R} produces @mathit{-4}. - -@kindex I R -@pindex calc-trunc -@tindex trunc -@tindex ftrunc -@ignore -@mindex @null -@end ignore -@kindex H I R -The @kbd{I R} (@code{calc-trunc}) [@code{trunc} or @code{ftrunc}] -command truncates toward zero. In other words, it ``chops off'' -everything after the decimal point. Thus @kbd{3.6 I R} produces 3 and -@kbd{_3.6 I R} produces @mathit{-3}. - -These functions may not be applied meaningfully to error forms, but they -do work for intervals. As a convenience, applying @code{floor} to a -modulo form floors the value part of the form. Applied to a vector, -these functions operate on all elements of the vector one by one. -Applied to a date form, they operate on the internal numerical -representation of dates, converting a date/time form into a pure date. - -@ignore -@starindex -@end ignore -@tindex rounde -@ignore -@starindex -@end ignore -@tindex roundu -@ignore -@starindex -@end ignore -@tindex frounde -@ignore -@starindex -@end ignore -@tindex froundu -There are two more rounding functions which can only be entered in -algebraic notation. The @code{roundu} function is like @code{round} -except that it rounds up, toward plus infinity, when the fractional -part is .5. This distinction matters only for negative arguments. -Also, @code{rounde} rounds to an even number in the case of a tie, -rounding up or down as necessary. For example, @samp{rounde(3.5)} and -@samp{rounde(4.5)} both return 4, but @samp{rounde(5.5)} returns 6. -The advantage of round-to-even is that the net error due to rounding -after a long calculation tends to cancel out to zero. An important -subtle point here is that the number being fed to @code{rounde} will -already have been rounded to the current precision before @code{rounde} -begins. For example, @samp{rounde(2.500001)} with a current precision -of 6 will incorrectly, or at least surprisingly, yield 2 because the -argument will first have been rounded down to @expr{2.5} (which -@code{rounde} sees as an exact tie between 2 and 3). - -Each of these functions, when written in algebraic formulas, allows -a second argument which specifies the number of digits after the -decimal point to keep. For example, @samp{round(123.4567, 2)} will -produce the answer 123.46, and @samp{round(123.4567, -1)} will -produce 120 (i.e., the cutoff is one digit to the @emph{left} of -the decimal point). A second argument of zero is equivalent to -no second argument at all. - -@cindex Fractional part of a number -To compute the fractional part of a number (i.e., the amount which, when -added to `@tfn{floor(}@var{n}@tfn{)}', will produce @var{n}) just take @var{n} -modulo 1 using the @code{%} command. - -Note also the @kbd{\} (integer quotient), @kbd{f I} (integer logarithm), -and @kbd{f Q} (integer square root) commands, which are analogous to -@kbd{/}, @kbd{B}, and @kbd{Q}, respectively, except that they take integer -arguments and return the result rounded down to an integer. - -@node Complex Number Functions, Conversions, Integer Truncation, Arithmetic -@section Complex Number Functions - -@noindent -@kindex J -@pindex calc-conj -@tindex conj -The @kbd{J} (@code{calc-conj}) [@code{conj}] command computes the -complex conjugate of a number. For complex number @expr{a+bi}, the -complex conjugate is @expr{a-bi}. If the argument is a real number, -this command leaves it the same. If the argument is a vector or matrix, -this command replaces each element by its complex conjugate. - -@kindex G -@pindex calc-argument -@tindex arg -The @kbd{G} (@code{calc-argument}) [@code{arg}] command computes the -``argument'' or polar angle of a complex number. For a number in polar -notation, this is simply the second component of the pair -@texline `@tfn{(}@var{r}@tfn{;}@math{\theta}@tfn{)}'. -@infoline `@tfn{(}@var{r}@tfn{;}@var{theta}@tfn{)}'. -The result is expressed according to the current angular mode and will -be in the range @mathit{-180} degrees (exclusive) to @mathit{+180} degrees -(inclusive), or the equivalent range in radians. - -@pindex calc-imaginary -The @code{calc-imaginary} command multiplies the number on the -top of the stack by the imaginary number @expr{i = (0,1)}. This -command is not normally bound to a key in Calc, but it is available -on the @key{IMAG} button in Keypad mode. - -@kindex f r -@pindex calc-re -@tindex re -The @kbd{f r} (@code{calc-re}) [@code{re}] command replaces a complex number -by its real part. This command has no effect on real numbers. (As an -added convenience, @code{re} applied to a modulo form extracts -the value part.) - -@kindex f i -@pindex calc-im -@tindex im -The @kbd{f i} (@code{calc-im}) [@code{im}] command replaces a complex number -by its imaginary part; real numbers are converted to zero. With a vector -or matrix argument, these functions operate element-wise. - -@ignore -@mindex v p -@end ignore -@kindex v p (complex) -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) command can pack the top two numbers on -the stack into a composite object such as a complex number. With -a prefix argument of @mathit{-1}, it produces a rectangular complex number; -with an argument of @mathit{-2}, it produces a polar complex number. -(Also, @pxref{Building Vectors}.) - -@ignore -@mindex v u -@end ignore -@kindex v u (complex) -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the complex number -(or other composite object) on the top of the stack and unpacks it -into its separate components. - -@node Conversions, Date Arithmetic, Complex Number Functions, Arithmetic -@section Conversions - -@noindent -The commands described in this section convert numbers from one form -to another; they are two-key sequences beginning with the letter @kbd{c}. - -@kindex c f -@pindex calc-float -@tindex pfloat -The @kbd{c f} (@code{calc-float}) [@code{pfloat}] command converts the -number on the top of the stack to floating-point form. For example, -@expr{23} is converted to @expr{23.0}, @expr{3:2} is converted to -@expr{1.5}, and @expr{2.3} is left the same. If the value is a composite -object such as a complex number or vector, each of the components is -converted to floating-point. If the value is a formula, all numbers -in the formula are converted to floating-point. Note that depending -on the current floating-point precision, conversion to floating-point -format may lose information. - -As a special exception, integers which appear as powers or subscripts -are not floated by @kbd{c f}. If you really want to float a power, -you can use a @kbd{j s} command to select the power followed by @kbd{c f}. -Because @kbd{c f} cannot examine the formula outside of the selection, -it does not notice that the thing being floated is a power. -@xref{Selecting Subformulas}. - -The normal @kbd{c f} command is ``pervasive'' in the sense that it -applies to all numbers throughout the formula. The @code{pfloat} -algebraic function never stays around in a formula; @samp{pfloat(a + 1)} -changes to @samp{a + 1.0} as soon as it is evaluated. - -@kindex H c f -@tindex float -With the Hyperbolic flag, @kbd{H c f} [@code{float}] operates -only on the number or vector of numbers at the top level of its -argument. Thus, @samp{float(1)} is 1.0, but @samp{float(a + 1)} -is left unevaluated because its argument is not a number. - -You should use @kbd{H c f} if you wish to guarantee that the final -value, once all the variables have been assigned, is a float; you -would use @kbd{c f} if you wish to do the conversion on the numbers -that appear right now. - -@kindex c F -@pindex calc-fraction -@tindex pfrac -The @kbd{c F} (@code{calc-fraction}) [@code{pfrac}] command converts a -floating-point number into a fractional approximation. By default, it -produces a fraction whose decimal representation is the same as the -input number, to within the current precision. You can also give a -numeric prefix argument to specify a tolerance, either directly, or, -if the prefix argument is zero, by using the number on top of the stack -as the tolerance. If the tolerance is a positive integer, the fraction -is correct to within that many significant figures. If the tolerance is -a non-positive integer, it specifies how many digits fewer than the current -precision to use. If the tolerance is a floating-point number, the -fraction is correct to within that absolute amount. - -@kindex H c F -@tindex frac -The @code{pfrac} function is pervasive, like @code{pfloat}. -There is also a non-pervasive version, @kbd{H c F} [@code{frac}], -which is analogous to @kbd{H c f} discussed above. - -@kindex c d -@pindex calc-to-degrees -@tindex deg -The @kbd{c d} (@code{calc-to-degrees}) [@code{deg}] command converts a -number into degrees form. The value on the top of the stack may be an -HMS form (interpreted as degrees-minutes-seconds), or a real number which -will be interpreted in radians regardless of the current angular mode. - -@kindex c r -@pindex calc-to-radians -@tindex rad -The @kbd{c r} (@code{calc-to-radians}) [@code{rad}] command converts an -HMS form or angle in degrees into an angle in radians. - -@kindex c h -@pindex calc-to-hms -@tindex hms -The @kbd{c h} (@code{calc-to-hms}) [@code{hms}] command converts a real -number, interpreted according to the current angular mode, to an HMS -form describing the same angle. In algebraic notation, the @code{hms} -function also accepts three arguments: @samp{hms(@var{h}, @var{m}, @var{s})}. -(The three-argument version is independent of the current angular mode.) - -@pindex calc-from-hms -The @code{calc-from-hms} command converts the HMS form on the top of the -stack into a real number according to the current angular mode. - -@kindex c p -@kindex I c p -@pindex calc-polar -@tindex polar -@tindex rect -The @kbd{c p} (@code{calc-polar}) command converts the complex number on -the top of the stack from polar to rectangular form, or from rectangular -to polar form, whichever is appropriate. Real numbers are left the same. -This command is equivalent to the @code{rect} or @code{polar} -functions in algebraic formulas, depending on the direction of -conversion. (It uses @code{polar}, except that if the argument is -already a polar complex number, it uses @code{rect} instead. The -@kbd{I c p} command always uses @code{rect}.) - -@kindex c c -@pindex calc-clean -@tindex pclean -The @kbd{c c} (@code{calc-clean}) [@code{pclean}] command ``cleans'' the -number on the top of the stack. Floating point numbers are re-rounded -according to the current precision. Polar numbers whose angular -components have strayed from the @mathit{-180} to @mathit{+180} degree range -are normalized. (Note that results will be undesirable if the current -angular mode is different from the one under which the number was -produced!) Integers and fractions are generally unaffected by this -operation. Vectors and formulas are cleaned by cleaning each component -number (i.e., pervasively). - -If the simplification mode is set below the default level, it is raised -to the default level for the purposes of this command. Thus, @kbd{c c} -applies the default simplifications even if their automatic application -is disabled. @xref{Simplification Modes}. - -@cindex Roundoff errors, correcting -A numeric prefix argument to @kbd{c c} sets the floating-point precision -to that value for the duration of the command. A positive prefix (of at -least 3) sets the precision to the specified value; a negative or zero -prefix decreases the precision by the specified amount. - -@kindex c 0-9 -@pindex calc-clean-num -The keystroke sequences @kbd{c 0} through @kbd{c 9} are equivalent -to @kbd{c c} with the corresponding negative prefix argument. If roundoff -errors have changed 2.0 into 1.999999, typing @kbd{c 1} to clip off one -decimal place often conveniently does the trick. - -The @kbd{c c} command with a numeric prefix argument, and the @kbd{c 0} -through @kbd{c 9} commands, also ``clip'' very small floating-point -numbers to zero. If the exponent is less than or equal to the negative -of the specified precision, the number is changed to 0.0. For example, -if the current precision is 12, then @kbd{c 2} changes the vector -@samp{[1e-8, 1e-9, 1e-10, 1e-11]} to @samp{[1e-8, 1e-9, 0, 0]}. -Numbers this small generally arise from roundoff noise. - -If the numbers you are using really are legitimately this small, -you should avoid using the @kbd{c 0} through @kbd{c 9} commands. -(The plain @kbd{c c} command rounds to the current precision but -does not clip small numbers.) - -One more property of @kbd{c 0} through @kbd{c 9}, and of @kbd{c c} with -a prefix argument, is that integer-valued floats are converted to -plain integers, so that @kbd{c 1} on @samp{[1., 1.5, 2., 2.5, 3.]} -produces @samp{[1, 1.5, 2, 2.5, 3]}. This is not done for huge -numbers (@samp{1e100} is technically an integer-valued float, but -you wouldn't want it automatically converted to a 100-digit integer). - -@kindex H c 0-9 -@kindex H c c -@tindex clean -With the Hyperbolic flag, @kbd{H c c} and @kbd{H c 0} through @kbd{H c 9} -operate non-pervasively [@code{clean}]. - -@node Date Arithmetic, Financial Functions, Conversions, Arithmetic -@section Date Arithmetic - -@noindent -@cindex Date arithmetic, additional functions -The commands described in this section perform various conversions -and calculations involving date forms (@pxref{Date Forms}). They -use the @kbd{t} (for time/date) prefix key followed by shifted -letters. - -The simplest date arithmetic is done using the regular @kbd{+} and @kbd{-} -commands. In particular, adding a number to a date form advances the -date form by a certain number of days; adding an HMS form to a date -form advances the date by a certain amount of time; and subtracting two -date forms produces a difference measured in days. The commands -described here provide additional, more specialized operations on dates. - -Many of these commands accept a numeric prefix argument; if you give -plain @kbd{C-u} as the prefix, these commands will instead take the -additional argument from the top of the stack. - -@menu -* Date Conversions:: -* Date Functions:: -* Time Zones:: -* Business Days:: -@end menu - -@node Date Conversions, Date Functions, Date Arithmetic, Date Arithmetic -@subsection Date Conversions - -@noindent -@kindex t D -@pindex calc-date -@tindex date -The @kbd{t D} (@code{calc-date}) [@code{date}] command converts a -date form into a number, measured in days since Jan 1, 1 AD. The -result will be an integer if @var{date} is a pure date form, or a -fraction or float if @var{date} is a date/time form. Or, if its -argument is a number, it converts this number into a date form. - -With a numeric prefix argument, @kbd{t D} takes that many objects -(up to six) from the top of the stack and interprets them in one -of the following ways: - -The @samp{date(@var{year}, @var{month}, @var{day})} function -builds a pure date form out of the specified year, month, and -day, which must all be integers. @var{Year} is a year number, -such as 1991 (@emph{not} the same as 91!). @var{Month} must be -an integer in the range 1 to 12; @var{day} must be in the range -1 to 31. If the specified month has fewer than 31 days and -@var{day} is too large, the equivalent day in the following -month will be used. - -The @samp{date(@var{month}, @var{day})} function builds a -pure date form using the current year, as determined by the -real-time clock. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hms})} -function builds a date/time form using an @var{hms} form. - -The @samp{date(@var{year}, @var{month}, @var{day}, @var{hour}, -@var{minute}, @var{second})} function builds a date/time form. -@var{hour} should be an integer in the range 0 to 23; -@var{minute} should be an integer in the range 0 to 59; -@var{second} should be any real number in the range @samp{[0 .. 60)}. -The last two arguments default to zero if omitted. - -@kindex t J -@pindex calc-julian -@tindex julian -@cindex Julian day counts, conversions -The @kbd{t J} (@code{calc-julian}) [@code{julian}] command converts -a date form into a Julian day count, which is the number of days -since noon (GMT) on Jan 1, 4713 BC. A pure date is converted to an -integer Julian count representing noon of that day. A date/time form -is converted to an exact floating-point Julian count, adjusted to -interpret the date form in the current time zone but the Julian -day count in Greenwich Mean Time. A numeric prefix argument allows -you to specify the time zone; @pxref{Time Zones}. Use a prefix of -zero to suppress the time zone adjustment. Note that pure date forms -are never time-zone adjusted. - -This command can also do the opposite conversion, from a Julian day -count (either an integer day, or a floating-point day and time in -the GMT zone), into a pure date form or a date/time form in the -current or specified time zone. - -@kindex t U -@pindex calc-unix-time -@tindex unixtime -@cindex Unix time format, conversions -The @kbd{t U} (@code{calc-unix-time}) [@code{unixtime}] command -converts a date form into a Unix time value, which is the number of -seconds since midnight on Jan 1, 1970, or vice-versa. The numeric result -will be an integer if the current precision is 12 or less; for higher -precisions, the result may be a float with (@var{precision}@minus{}12) -digits after the decimal. Just as for @kbd{t J}, the numeric time -is interpreted in the GMT time zone and the date form is interpreted -in the current or specified zone. Some systems use Unix-like -numbering but with the local time zone; give a prefix of zero to -suppress the adjustment if so. - -@kindex t C -@pindex calc-convert-time-zones -@tindex tzconv -@cindex Time Zones, converting between -The @kbd{t C} (@code{calc-convert-time-zones}) [@code{tzconv}] -command converts a date form from one time zone to another. You -are prompted for each time zone name in turn; you can answer with -any suitable Calc time zone expression (@pxref{Time Zones}). -If you answer either prompt with a blank line, the local time -zone is used for that prompt. You can also answer the first -prompt with @kbd{$} to take the two time zone names from the -stack (and the date to be converted from the third stack level). - -@node Date Functions, Business Days, Date Conversions, Date Arithmetic -@subsection Date Functions - -@noindent -@kindex t N -@pindex calc-now -@tindex now -The @kbd{t N} (@code{calc-now}) [@code{now}] command pushes the -current date and time on the stack as a date form. The time is -reported in terms of the specified time zone; with no numeric prefix -argument, @kbd{t N} reports for the current time zone. - -@kindex t P -@pindex calc-date-part -The @kbd{t P} (@code{calc-date-part}) command extracts one part -of a date form. The prefix argument specifies the part; with no -argument, this command prompts for a part code from 1 to 9. -The various part codes are described in the following paragraphs. - -@tindex year -The @kbd{M-1 t P} [@code{year}] function extracts the year number -from a date form as an integer, e.g., 1991. This and the -following functions will also accept a real number for an -argument, which is interpreted as a standard Calc day number. -Note that this function will never return zero, since the year -1 BC immediately precedes the year 1 AD. - -@tindex month -The @kbd{M-2 t P} [@code{month}] function extracts the month number -from a date form as an integer in the range 1 to 12. - -@tindex day -The @kbd{M-3 t P} [@code{day}] function extracts the day number -from a date form as an integer in the range 1 to 31. - -@tindex hour -The @kbd{M-4 t P} [@code{hour}] function extracts the hour from -a date form as an integer in the range 0 (midnight) to 23. Note -that 24-hour time is always used. This returns zero for a pure -date form. This function (and the following two) also accept -HMS forms as input. - -@tindex minute -The @kbd{M-5 t P} [@code{minute}] function extracts the minute -from a date form as an integer in the range 0 to 59. - -@tindex second -The @kbd{M-6 t P} [@code{second}] function extracts the second -from a date form. If the current precision is 12 or less, -the result is an integer in the range 0 to 59. For higher -precisions, the result may instead be a floating-point number. - -@tindex weekday -The @kbd{M-7 t P} [@code{weekday}] function extracts the weekday -number from a date form as an integer in the range 0 (Sunday) -to 6 (Saturday). - -@tindex yearday -The @kbd{M-8 t P} [@code{yearday}] function extracts the day-of-year -number from a date form as an integer in the range 1 (January 1) -to 366 (December 31 of a leap year). - -@tindex time -The @kbd{M-9 t P} [@code{time}] function extracts the time portion -of a date form as an HMS form. This returns @samp{0@@ 0' 0"} -for a pure date form. - -@kindex t M -@pindex calc-new-month -@tindex newmonth -The @kbd{t M} (@code{calc-new-month}) [@code{newmonth}] command -computes a new date form that represents the first day of the month -specified by the input date. The result is always a pure date -form; only the year and month numbers of the input are retained. -With a numeric prefix argument @var{n} in the range from 1 to 31, -@kbd{t M} computes the @var{n}th day of the month. (If @var{n} -is greater than the actual number of days in the month, or if -@var{n} is zero, the last day of the month is used.) - -@kindex t Y -@pindex calc-new-year -@tindex newyear -The @kbd{t Y} (@code{calc-new-year}) [@code{newyear}] command -computes a new pure date form that represents the first day of -the year specified by the input. The month, day, and time -of the input date form are lost. With a numeric prefix argument -@var{n} in the range from 1 to 366, @kbd{t Y} computes the -@var{n}th day of the year (366 is treated as 365 in non-leap -years). A prefix argument of 0 computes the last day of the -year (December 31). A negative prefix argument from @mathit{-1} to -@mathit{-12} computes the first day of the @var{n}th month of the year. - -@kindex t W -@pindex calc-new-week -@tindex newweek -The @kbd{t W} (@code{calc-new-week}) [@code{newweek}] command -computes a new pure date form that represents the Sunday on or before -the input date. With a numeric prefix argument, it can be made to -use any day of the week as the starting day; the argument must be in -the range from 0 (Sunday) to 6 (Saturday). This function always -subtracts between 0 and 6 days from the input date. - -Here's an example use of @code{newweek}: Find the date of the next -Wednesday after a given date. Using @kbd{M-3 t W} or @samp{newweek(d, 3)} -will give you the @emph{preceding} Wednesday, so @samp{newweek(d+7, 3)} -will give you the following Wednesday. A further look at the definition -of @code{newweek} shows that if the input date is itself a Wednesday, -this formula will return the Wednesday one week in the future. An -exercise for the reader is to modify this formula to yield the same day -if the input is already a Wednesday. Another interesting exercise is -to preserve the time-of-day portion of the input (@code{newweek} resets -the time to midnight; hint:@: how can @code{newweek} be defined in terms -of the @code{weekday} function?). - -@ignore -@starindex -@end ignore -@tindex pwday -The @samp{pwday(@var{date})} function (not on any key) computes the -day-of-month number of the Sunday on or before @var{date}. With -two arguments, @samp{pwday(@var{date}, @var{day})} computes the day -number of the Sunday on or before day number @var{day} of the month -specified by @var{date}. The @var{day} must be in the range from -7 to 31; if the day number is greater than the actual number of days -in the month, the true number of days is used instead. Thus -@samp{pwday(@var{date}, 7)} finds the first Sunday of the month, and -@samp{pwday(@var{date}, 31)} finds the last Sunday of the month. -With a third @var{weekday} argument, @code{pwday} can be made to look -for any day of the week instead of Sunday. - -@kindex t I -@pindex calc-inc-month -@tindex incmonth -The @kbd{t I} (@code{calc-inc-month}) [@code{incmonth}] command -increases a date form by one month, or by an arbitrary number of -months specified by a numeric prefix argument. The time portion, -if any, of the date form stays the same. The day also stays the -same, except that if the new month has fewer days the day -number may be reduced to lie in the valid range. For example, -@samp{incmonth()} produces @samp{}. -Because of this, @kbd{t I t I} and @kbd{M-2 t I} do not always give -the same results (@samp{} versus @samp{} -in this case). - -@ignore -@starindex -@end ignore -@tindex incyear -The @samp{incyear(@var{date}, @var{step})} function increases -a date form by the specified number of years, which may be -any positive or negative integer. Note that @samp{incyear(d, n)} -is equivalent to @w{@samp{incmonth(d, 12*n)}}, but these do not have -simple equivalents in terms of day arithmetic because -months and years have varying lengths. If the @var{step} -argument is omitted, 1 year is assumed. There is no keyboard -command for this function; use @kbd{C-u 12 t I} instead. - -There is no @code{newday} function at all because @kbd{F} [@code{floor}] -serves this purpose. Similarly, instead of @code{incday} and -@code{incweek} simply use @expr{d + n} or @expr{d + 7 n}. - -@xref{Basic Arithmetic}, for the @kbd{f ]} [@code{incr}] command -which can adjust a date/time form by a certain number of seconds. - -@node Business Days, Time Zones, Date Functions, Date Arithmetic -@subsection Business Days - -@noindent -Often time is measured in ``business days'' or ``working days,'' -where weekends and holidays are skipped. Calc's normal date -arithmetic functions use calendar days, so that subtracting two -consecutive Mondays will yield a difference of 7 days. By contrast, -subtracting two consecutive Mondays would yield 5 business days -(assuming two-day weekends and the absence of holidays). - -@kindex t + -@kindex t - -@tindex badd -@tindex bsub -@pindex calc-business-days-plus -@pindex calc-business-days-minus -The @kbd{t +} (@code{calc-business-days-plus}) [@code{badd}] -and @kbd{t -} (@code{calc-business-days-minus}) [@code{bsub}] -commands perform arithmetic using business days. For @kbd{t +}, -one argument must be a date form and the other must be a real -number (positive or negative). If the number is not an integer, -then a certain amount of time is added as well as a number of -days; for example, adding 0.5 business days to a time in Friday -evening will produce a time in Monday morning. It is also -possible to add an HMS form; adding @samp{12@@ 0' 0"} also adds -half a business day. For @kbd{t -}, the arguments are either a -date form and a number or HMS form, or two date forms, in which -case the result is the number of business days between the two -dates. - -@cindex @code{Holidays} variable -@vindex Holidays -By default, Calc considers any day that is not a Saturday or -Sunday to be a business day. You can define any number of -additional holidays by editing the variable @code{Holidays}. -(There is an @w{@kbd{s H}} convenience command for editing this -variable.) Initially, @code{Holidays} contains the vector -@samp{[sat, sun]}. Entries in the @code{Holidays} vector may -be any of the following kinds of objects: - -@itemize @bullet -@item -Date forms (pure dates, not date/time forms). These specify -particular days which are to be treated as holidays. - -@item -Intervals of date forms. These specify a range of days, all of -which are holidays (e.g., Christmas week). @xref{Interval Forms}. - -@item -Nested vectors of date forms. Each date form in the vector is -considered to be a holiday. - -@item -Any Calc formula which evaluates to one of the above three things. -If the formula involves the variable @expr{y}, it stands for a -yearly repeating holiday; @expr{y} will take on various year -numbers like 1992. For example, @samp{date(y, 12, 25)} specifies -Christmas day, and @samp{newweek(date(y, 11, 7), 4) + 21} specifies -Thanksgiving (which is held on the fourth Thursday of November). -If the formula involves the variable @expr{m}, that variable -takes on month numbers from 1 to 12: @samp{date(y, m, 15)} is -a holiday that takes place on the 15th of every month. - -@item -A weekday name, such as @code{sat} or @code{sun}. This is really -a variable whose name is a three-letter, lower-case day name. - -@item -An interval of year numbers (integers). This specifies the span of -years over which this holiday list is to be considered valid. Any -business-day arithmetic that goes outside this range will result -in an error message. Use this if you are including an explicit -list of holidays, rather than a formula to generate them, and you -want to make sure you don't accidentally go beyond the last point -where the holidays you entered are complete. If there is no -limiting interval in the @code{Holidays} vector, the default -@samp{[1 .. 2737]} is used. (This is the absolute range of years -for which Calc's business-day algorithms will operate.) - -@item -An interval of HMS forms. This specifies the span of hours that -are to be considered one business day. For example, if this -range is @samp{[9@@ 0' 0" .. 17@@ 0' 0"]} (i.e., 9am to 5pm), then -the business day is only eight hours long, so that @kbd{1.5 t +} -on @samp{<4:00pm Fri Dec 13, 1991>} will add one business day and -four business hours to produce @samp{<12:00pm Tue Dec 17, 1991>}. -Likewise, @kbd{t -} will now express differences in time as -fractions of an eight-hour day. Times before 9am will be treated -as 9am by business date arithmetic, and times at or after 5pm will -be treated as 4:59:59pm. If there is no HMS interval in @code{Holidays}, -the full 24-hour day @samp{[0@ 0' 0" .. 24@ 0' 0"]} is assumed. -(Regardless of the type of bounds you specify, the interval is -treated as inclusive on the low end and exclusive on the high end, -so that the work day goes from 9am up to, but not including, 5pm.) -@end itemize - -If the @code{Holidays} vector is empty, then @kbd{t +} and -@kbd{t -} will act just like @kbd{+} and @kbd{-} because there will -then be no difference between business days and calendar days. - -Calc expands the intervals and formulas you give into a complete -list of holidays for internal use. This is done mainly to make -sure it can detect multiple holidays. (For example, -@samp{} is both New Year's Day and a Sunday, but -Calc's algorithms take care to count it only once when figuring -the number of holidays between two dates.) - -Since the complete list of holidays for all the years from 1 to -2737 would be huge, Calc actually computes only the part of the -list between the smallest and largest years that have been involved -in business-day calculations so far. Normally, you won't have to -worry about this. Keep in mind, however, that if you do one -calculation for 1992, and another for 1792, even if both involve -only a small range of years, Calc will still work out all the -holidays that fall in that 200-year span. - -If you add a (positive) number of days to a date form that falls on a -weekend or holiday, the date form is treated as if it were the most -recent business day. (Thus adding one business day to a Friday, -Saturday, or Sunday will all yield the following Monday.) If you -subtract a number of days from a weekend or holiday, the date is -effectively on the following business day. (So subtracting one business -day from Saturday, Sunday, or Monday yields the preceding Friday.) The -difference between two dates one or both of which fall on holidays -equals the number of actual business days between them. These -conventions are consistent in the sense that, if you add @var{n} -business days to any date, the difference between the result and the -original date will come out to @var{n} business days. (It can't be -completely consistent though; a subtraction followed by an addition -might come out a bit differently, since @kbd{t +} is incapable of -producing a date that falls on a weekend or holiday.) - -@ignore -@starindex -@end ignore -@tindex holiday -There is a @code{holiday} function, not on any keys, that takes -any date form and returns 1 if that date falls on a weekend or -holiday, as defined in @code{Holidays}, or 0 if the date is a -business day. - -@node Time Zones, , Business Days, Date Arithmetic -@subsection Time Zones - -@noindent -@cindex Time zones -@cindex Daylight saving time -Time zones and daylight saving time are a complicated business. -The conversions to and from Julian and Unix-style dates automatically -compute the correct time zone and daylight saving adjustment to use, -provided they can figure out this information. This section describes -Calc's time zone adjustment algorithm in detail, in case you want to -do conversions in different time zones or in case Calc's algorithms -can't determine the right correction to use. - -Adjustments for time zones and daylight saving time are done by -@kbd{t U}, @kbd{t J}, @kbd{t N}, and @kbd{t C}, but not by any other -commands. In particular, @samp{ - } evaluates -to exactly 30 days even though there is a daylight-saving -transition in between. This is also true for Julian pure dates: -@samp{julian() - julian()}. But Julian -and Unix date/times will adjust for daylight saving time: using Calc's -default daylight saving time rule (see the explanation below), -@samp{julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)} -evaluates to @samp{29.95833} (that's 29 days and 23 hours) -because one hour was lost when daylight saving commenced on -April 7, 1991. - -In brief, the idiom @samp{julian(@var{date1}) - julian(@var{date2})} -computes the actual number of 24-hour periods between two dates, whereas -@samp{@var{date1} - @var{date2}} computes the number of calendar -days between two dates without taking daylight saving into account. - -@pindex calc-time-zone -@ignore -@starindex -@end ignore -@tindex tzone -The @code{calc-time-zone} [@code{tzone}] command converts the time -zone specified by its numeric prefix argument into a number of -seconds difference from Greenwich mean time (GMT). If the argument -is a number, the result is simply that value multiplied by 3600. -Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If -Daylight Saving time is in effect, one hour should be subtracted from -the normal difference. - -If you give a prefix of plain @kbd{C-u}, @code{calc-time-zone} (like other -date arithmetic commands that include a time zone argument) takes the -zone argument from the top of the stack. (In the case of @kbd{t J} -and @kbd{t U}, the normal argument is then taken from the second-to-top -stack position.) This allows you to give a non-integer time zone -adjustment. The time-zone argument can also be an HMS form, or -it can be a variable which is a time zone name in upper- or lower-case. -For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)} -(for Pacific standard and daylight saving times, respectively). - -North American and European time zone names are defined as follows; -note that for each time zone there is one name for standard time, -another for daylight saving time, and a third for ``generalized'' time -in which the daylight saving adjustment is computed from context. - -@smallexample -@group -YST PST MST CST EST AST NST GMT WET MET MEZ - 9 8 7 6 5 4 3.5 0 -1 -2 -2 - -YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ - 8 7 6 5 4 3 2.5 -1 -2 -3 -3 - -YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ -9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 -@end group -@end smallexample - -@vindex math-tzone-names -To define time zone names that do not appear in the above table, -you must modify the Lisp variable @code{math-tzone-names}. This -is a list of lists describing the different time zone names; its -structure is best explained by an example. The three entries for -Pacific Time look like this: - -@smallexample -@group -( ( "PST" 8 0 ) ; Name as an upper-case string, then standard - ( "PDT" 8 -1 ) ; adjustment, then daylight saving adjustment. - ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. -@end group -@end smallexample - -@cindex @code{TimeZone} variable -@vindex TimeZone -With no arguments, @code{calc-time-zone} or @samp{tzone()} will by -default get the time zone and daylight saving information from the -calendar (@pxref{Daylight Saving,Calendar/Diary,The Calendar and the Diary, -emacs,The GNU Emacs Manual}). To use a different time zone, or if the -calendar does not give the desired result, you can set the Calc variable -@code{TimeZone} (which is by default @code{nil}) to an appropriate -time zone name. (The easiest way to do this is to edit the -@code{TimeZone} variable using Calc's @kbd{s T} command, then use the -@kbd{s p} (@code{calc-permanent-variable}) command to save the value of -@code{TimeZone} permanently.) -If the time zone given by @code{TimeZone} is a generalized time zone, -e.g., @code{EGT}, Calc examines the date being converted to tell whether -to use standard or daylight saving time. But if the current time zone -is explicit, e.g., @code{EST} or @code{EDT}, then that adjustment is -used exactly and Calc's daylight saving algorithm is not consulted. -The special time zone name @code{local} -is equivalent to no argument; i.e., it uses the information obtained -from the calendar. - -The @kbd{t J} and @code{t U} commands with no numeric prefix -arguments do the same thing as @samp{tzone()}; namely, use the -information from the calendar if @code{TimeZone} is @code{nil}, -otherwise use the time zone given by @code{TimeZone}. - -@vindex math-daylight-savings-hook -@findex math-std-daylight-savings -When Calc computes the daylight saving information itself (i.e., when -the @code{TimeZone} variable is set), it will by default consider -daylight saving time to begin at 2 a.m.@: on the second Sunday of March -(for years from 2007 on) or on the last Sunday in April (for years -before 2007), and to end at 2 a.m.@: on the first Sunday of -November. (for years from 2007 on) or the last Sunday in October (for -years before 2007). These are the rules that have been in effect in -much of North America since 1966 and take into account the rule change -that began in 2007. If you are in a country that uses different rules -for computing daylight saving time, you have two choices: Write your own -daylight saving hook, or control time zones explicitly by setting the -@code{TimeZone} variable and/or always giving a time-zone argument for -the conversion functions. - -The Lisp variable @code{math-daylight-savings-hook} holds the -name of a function that is used to compute the daylight saving -adjustment for a given date. The default is -@code{math-std-daylight-savings}, which computes an adjustment -(either 0 or @mathit{-1}) using the North American rules given above. - -The daylight saving hook function is called with four arguments: -The date, as a floating-point number in standard Calc format; -a six-element list of the date decomposed into year, month, day, -hour, minute, and second, respectively; a string which contains -the generalized time zone name in upper-case, e.g., @code{"WEGT"}; -and a special adjustment to be applied to the hour value when -converting into a generalized time zone (see below). - -@findex math-prev-weekday-in-month -The Lisp function @code{math-prev-weekday-in-month} is useful for -daylight saving computations. This is an internal version of -the user-level @code{pwday} function described in the previous -section. It takes four arguments: The floating-point date value, -the corresponding six-element date list, the day-of-month number, -and the weekday number (0-6). - -The default daylight saving hook ignores the time zone name, but a -more sophisticated hook could use different algorithms for different -time zones. It would also be possible to use different algorithms -depending on the year number, but the default hook always uses the -algorithm for 1987 and later. Here is a listing of the default -daylight saving hook: - -@smallexample -(defun math-std-daylight-savings (date dt zone bump) - (cond ((< (nth 1 dt) 4) 0) - ((= (nth 1 dt) 4) - (let ((sunday (math-prev-weekday-in-month date dt 7 0))) - (cond ((< (nth 2 dt) sunday) 0) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) - (t -1)))) - ((< (nth 1 dt) 10) -1) - ((= (nth 1 dt) 10) - (let ((sunday (math-prev-weekday-in-month date dt 31 0))) - (cond ((< (nth 2 dt) sunday) -1) - ((= (nth 2 dt) sunday) - (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) - (t 0)))) - (t 0)) -) -@end smallexample - -@noindent -The @code{bump} parameter is equal to zero when Calc is converting -from a date form in a generalized time zone into a GMT date value. -It is @mathit{-1} when Calc is converting in the other direction. The -adjustments shown above ensure that the conversion behaves correctly -and reasonably around the 2 a.m.@: transition in each direction. - -There is a ``missing'' hour between 2 a.m.@: and 3 a.m.@: at the -beginning of daylight saving time; converting a date/time form that -falls in this hour results in a time value for the following hour, -from 3 a.m.@: to 4 a.m. At the end of daylight saving time, the -hour from 1 a.m.@: to 2 a.m.@: repeats itself; converting a date/time -form that falls in this hour results in a time value for the first -manifestation of that time (@emph{not} the one that occurs one hour -later). - -If @code{math-daylight-savings-hook} is @code{nil}, then the -daylight saving adjustment is always taken to be zero. - -In algebraic formulas, @samp{tzone(@var{zone}, @var{date})} -computes the time zone adjustment for a given zone name at a -given date. The @var{date} is ignored unless @var{zone} is a -generalized time zone. If @var{date} is a date form, the -daylight saving computation is applied to it as it appears. -If @var{date} is a numeric date value, it is adjusted for the -daylight-saving version of @var{zone} before being given to -the daylight saving hook. This odd-sounding rule ensures -that the daylight-saving computation is always done in -local time, not in the GMT time that a numeric @var{date} -is typically represented in. - -@ignore -@starindex -@end ignore -@tindex dsadj -The @samp{dsadj(@var{date}, @var{zone})} function computes the -daylight saving adjustment that is appropriate for @var{date} in -time zone @var{zone}. If @var{zone} is explicitly in or not in -daylight saving time (e.g., @code{PDT} or @code{PST}) the -@var{date} is ignored. If @var{zone} is a generalized time zone, -the algorithms described above are used. If @var{zone} is omitted, -the computation is done for the current time zone. - -@node Financial Functions, Binary Functions, Date Arithmetic, Arithmetic -@section Financial Functions - -@noindent -Calc's financial or business functions use the @kbd{b} prefix -key followed by a shifted letter. (The @kbd{b} prefix followed by -a lower-case letter is used for operations on binary numbers.) - -Note that the rate and the number of intervals given to these -functions must be on the same time scale, e.g., both months or -both years. Mixing an annual interest rate with a time expressed -in months will give you very wrong answers! - -It is wise to compute these functions to a higher precision than -you really need, just to make sure your answer is correct to the -last penny; also, you may wish to check the definitions at the end -of this section to make sure the functions have the meaning you expect. - -@menu -* Percentages:: -* Future Value:: -* Present Value:: -* Related Financial Functions:: -* Depreciation Functions:: -* Definitions of Financial Functions:: -@end menu - -@node Percentages, Future Value, Financial Functions, Financial Functions -@subsection Percentages - -@kindex M-% -@pindex calc-percent -@tindex % -@tindex percent -The @kbd{M-%} (@code{calc-percent}) command takes a percentage value, -say 5.4, and converts it to an equivalent actual number. For example, -@kbd{5.4 M-%} enters 0.054 on the stack. (That's the @key{META} or -@key{ESC} key combined with @kbd{%}.) - -Actually, @kbd{M-%} creates a formula of the form @samp{5.4%}. -You can enter @samp{5.4%} yourself during algebraic entry. The -@samp{%} operator simply means, ``the preceding value divided by -100.'' The @samp{%} operator has very high precedence, so that -@samp{1+8%} is interpreted as @samp{1+(8%)}, not as @samp{(1+8)%}. -(The @samp{%} operator is just a postfix notation for the -@code{percent} function, just like @samp{20!} is the notation for -@samp{fact(20)}, or twenty-factorial.) - -The formula @samp{5.4%} would normally evaluate immediately to -0.054, but the @kbd{M-%} command suppresses evaluation as it puts -the formula onto the stack. However, the next Calc command that -uses the formula @samp{5.4%} will evaluate it as its first step. -The net effect is that you get to look at @samp{5.4%} on the stack, -but Calc commands see it as @samp{0.054}, which is what they expect. - -In particular, @samp{5.4%} and @samp{0.054} are suitable values -for the @var{rate} arguments of the various financial functions, -but the number @samp{5.4} is probably @emph{not} suitable---it -represents a rate of 540 percent! - -The key sequence @kbd{M-% *} effectively means ``percent-of.'' -For example, @kbd{68 @key{RET} 25 M-% *} computes 17, which is 25% of -68 (and also 68% of 25, which comes out to the same thing). - -@kindex c % -@pindex calc-convert-percent -The @kbd{c %} (@code{calc-convert-percent}) command converts the -value on the top of the stack from numeric to percentage form. -For example, if 0.08 is on the stack, @kbd{c %} converts it to -@samp{8%}. The quantity is the same, it's just represented -differently. (Contrast this with @kbd{M-%}, which would convert -this number to @samp{0.08%}.) The @kbd{=} key is a convenient way -to convert a formula like @samp{8%} back to numeric form, 0.08. - -To compute what percentage one quantity is of another quantity, -use @kbd{/ c %}. For example, @w{@kbd{17 @key{RET} 68 / c %}} displays -@samp{25%}. - -@kindex b % -@pindex calc-percent-change -@tindex relch -The @kbd{b %} (@code{calc-percent-change}) [@code{relch}] command -calculates the percentage change from one number to another. -For example, @kbd{40 @key{RET} 50 b %} produces the answer @samp{25%}, -since 50 is 25% larger than 40. A negative result represents a -decrease: @kbd{50 @key{RET} 40 b %} produces @samp{-20%}, since 40 is -20% smaller than 50. (The answers are different in magnitude -because, in the first case, we're increasing by 25% of 40, but -in the second case, we're decreasing by 20% of 50.) The effect -of @kbd{40 @key{RET} 50 b %} is to compute @expr{(50-40)/40}, converting -the answer to percentage form as if by @kbd{c %}. - -@node Future Value, Present Value, Percentages, Financial Functions -@subsection Future Value - -@noindent -@kindex b F -@pindex calc-fin-fv -@tindex fv -The @kbd{b F} (@code{calc-fin-fv}) [@code{fv}] command computes -the future value of an investment. It takes three arguments -from the stack: @samp{fv(@var{rate}, @var{n}, @var{payment})}. -If you give payments of @var{payment} every year for @var{n} -years, and the money you have paid earns interest at @var{rate} per -year, then this function tells you what your investment would be -worth at the end of the period. (The actual interval doesn't -have to be years, as long as @var{n} and @var{rate} are expressed -in terms of the same intervals.) This function assumes payments -occur at the @emph{end} of each interval. - -@kindex I b F -@tindex fvb -The @kbd{I b F} [@code{fvb}] command does the same computation, -but assuming your payments are at the beginning of each interval. -Suppose you plan to deposit $1000 per year in a savings account -earning 5.4% interest, starting right now. How much will be -in the account after five years? @code{fvb(5.4%, 5, 1000) = 5870.73}. -Thus you will have earned $870 worth of interest over the years. -Using the stack, this calculation would have been -@kbd{5.4 M-% 5 @key{RET} 1000 I b F}. Note that the rate is expressed -as a number between 0 and 1, @emph{not} as a percentage. - -@kindex H b F -@tindex fvl -The @kbd{H b F} [@code{fvl}] command computes the future value -of an initial lump sum investment. Suppose you could deposit -those five thousand dollars in the bank right now; how much would -they be worth in five years? @code{fvl(5.4%, 5, 5000) = 6503.89}. - -The algebraic functions @code{fv} and @code{fvb} accept an optional -fourth argument, which is used as an initial lump sum in the sense -of @code{fvl}. In other words, @code{fv(@var{rate}, @var{n}, -@var{payment}, @var{initial}) = fv(@var{rate}, @var{n}, @var{payment}) -+ fvl(@var{rate}, @var{n}, @var{initial})}. - -To illustrate the relationships between these functions, we could -do the @code{fvb} calculation ``by hand'' using @code{fvl}. The -final balance will be the sum of the contributions of our five -deposits at various times. The first deposit earns interest for -five years: @code{fvl(5.4%, 5, 1000) = 1300.78}. The second -deposit only earns interest for four years: @code{fvl(5.4%, 4, 1000) = -1234.13}. And so on down to the last deposit, which earns one -year's interest: @code{fvl(5.4%, 1, 1000) = 1054.00}. The sum of -these five values is, sure enough, $5870.73, just as was computed -by @code{fvb} directly. - -What does @code{fv(5.4%, 5, 1000) = 5569.96} mean? The payments -are now at the ends of the periods. The end of one year is the same -as the beginning of the next, so what this really means is that we've -lost the payment at year zero (which contributed $1300.78), but we're -now counting the payment at year five (which, since it didn't have -a chance to earn interest, counts as $1000). Indeed, @expr{5569.96 = -5870.73 - 1300.78 + 1000} (give or take a bit of roundoff error). - -@node Present Value, Related Financial Functions, Future Value, Financial Functions -@subsection Present Value - -@noindent -@kindex b P -@pindex calc-fin-pv -@tindex pv -The @kbd{b P} (@code{calc-fin-pv}) [@code{pv}] command computes -the present value of an investment. Like @code{fv}, it takes -three arguments: @code{pv(@var{rate}, @var{n}, @var{payment})}. -It computes the present value of a series of regular payments. -Suppose you have the chance to make an investment that will -pay $2000 per year over the next four years; as you receive -these payments you can put them in the bank at 9% interest. -You want to know whether it is better to make the investment, or -to keep the money in the bank where it earns 9% interest right -from the start. The calculation @code{pv(9%, 4, 2000)} gives the -result 6479.44. If your initial investment must be less than this, -say, $6000, then the investment is worthwhile. But if you had to -put up $7000, then it would be better just to leave it in the bank. - -Here is the interpretation of the result of @code{pv}: You are -trying to compare the return from the investment you are -considering, which is @code{fv(9%, 4, 2000) = 9146.26}, with -the return from leaving the money in the bank, which is -@code{fvl(9%, 4, @var{x})} where @var{x} is the amount of money -you would have to put up in advance. The @code{pv} function -finds the break-even point, @expr{x = 6479.44}, at which -@code{fvl(9%, 4, 6479.44)} is also equal to 9146.26. This is -the largest amount you should be willing to invest. - -@kindex I b P -@tindex pvb -The @kbd{I b P} [@code{pvb}] command solves the same problem, -but with payments occurring at the beginning of each interval. -It has the same relationship to @code{fvb} as @code{pv} has -to @code{fv}. For example @code{pvb(9%, 4, 2000) = 7062.59}, -a larger number than @code{pv} produced because we get to start -earning interest on the return from our investment sooner. - -@kindex H b P -@tindex pvl -The @kbd{H b P} [@code{pvl}] command computes the present value of -an investment that will pay off in one lump sum at the end of the -period. For example, if we get our $8000 all at the end of the -four years, @code{pvl(9%, 4, 8000) = 5667.40}. This is much -less than @code{pv} reported, because we don't earn any interest -on the return from this investment. Note that @code{pvl} and -@code{fvl} are simple inverses: @code{fvl(9%, 4, 5667.40) = 8000}. - -You can give an optional fourth lump-sum argument to @code{pv} -and @code{pvb}; this is handled in exactly the same way as the -fourth argument for @code{fv} and @code{fvb}. - -@kindex b N -@pindex calc-fin-npv -@tindex npv -The @kbd{b N} (@code{calc-fin-npv}) [@code{npv}] command computes -the net present value of a series of irregular investments. -The first argument is the interest rate. The second argument is -a vector which represents the expected return from the investment -at the end of each interval. For example, if the rate represents -a yearly interest rate, then the vector elements are the return -from the first year, second year, and so on. - -Thus, @code{npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44}. -Obviously this function is more interesting when the payments are -not all the same! - -The @code{npv} function can actually have two or more arguments. -Multiple arguments are interpreted in the same way as for the -vector statistical functions like @code{vsum}. -@xref{Single-Variable Statistics}. Basically, if there are several -payment arguments, each either a vector or a plain number, all these -values are collected left-to-right into the complete list of payments. -A numeric prefix argument on the @kbd{b N} command says how many -payment values or vectors to take from the stack. - -@kindex I b N -@tindex npvb -The @kbd{I b N} [@code{npvb}] command computes the net present -value where payments occur at the beginning of each interval -rather than at the end. - -@node Related Financial Functions, Depreciation Functions, Present Value, Financial Functions -@subsection Related Financial Functions - -@noindent -The functions in this section are basically inverses of the -present value functions with respect to the various arguments. - -@kindex b M -@pindex calc-fin-pmt -@tindex pmt -The @kbd{b M} (@code{calc-fin-pmt}) [@code{pmt}] command computes -the amount of periodic payment necessary to amortize a loan. -Thus @code{pmt(@var{rate}, @var{n}, @var{amount})} equals the -value of @var{payment} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. - -@kindex I b M -@tindex pmtb -The @kbd{I b M} [@code{pmtb}] command does the same computation -but using @code{pvb} instead of @code{pv}. Like @code{pv} and -@code{pvb}, these functions can also take a fourth argument which -represents an initial lump-sum investment. - -@kindex H b M -The @kbd{H b M} key just invokes the @code{fvl} function, which is -the inverse of @code{pvl}. There is no explicit @code{pmtl} function. - -@kindex b # -@pindex calc-fin-nper -@tindex nper -The @kbd{b #} (@code{calc-fin-nper}) [@code{nper}] command computes -the number of regular payments necessary to amortize a loan. -Thus @code{nper(@var{rate}, @var{payment}, @var{amount})} equals -the value of @var{n} such that @code{pv(@var{rate}, @var{n}, -@var{payment}) = @var{amount}}. If @var{payment} is too small -ever to amortize a loan for @var{amount} at interest rate @var{rate}, -the @code{nper} function is left in symbolic form. - -@kindex I b # -@tindex nperb -The @kbd{I b #} [@code{nperb}] command does the same computation -but using @code{pvb} instead of @code{pv}. You can give a fourth -lump-sum argument to these functions, but the computation will be -rather slow in the four-argument case. - -@kindex H b # -@tindex nperl -The @kbd{H b #} [@code{nperl}] command does the same computation -using @code{pvl}. By exchanging @var{payment} and @var{amount} you -can also get the solution for @code{fvl}. For example, -@code{nperl(8%, 2000, 1000) = 9.006}, so if you place $1000 in a -bank account earning 8%, it will take nine years to grow to $2000. - -@kindex b T -@pindex calc-fin-rate -@tindex rate -The @kbd{b T} (@code{calc-fin-rate}) [@code{rate}] command computes -the rate of return on an investment. This is also an inverse of @code{pv}: -@code{rate(@var{n}, @var{payment}, @var{amount})} computes the value of -@var{rate} such that @code{pv(@var{rate}, @var{n}, @var{payment}) = -@var{amount}}. The result is expressed as a formula like @samp{6.3%}. - -@kindex I b T -@kindex H b T -@tindex rateb -@tindex ratel -The @kbd{I b T} [@code{rateb}] and @kbd{H b T} [@code{ratel}] -commands solve the analogous equations with @code{pvb} or @code{pvl} -in place of @code{pv}. Also, @code{rate} and @code{rateb} can -accept an optional fourth argument just like @code{pv} and @code{pvb}. -To redo the above example from a different perspective, -@code{ratel(9, 2000, 1000) = 8.00597%}, which says you will need an -interest rate of 8% in order to double your account in nine years. - -@kindex b I -@pindex calc-fin-irr -@tindex irr -The @kbd{b I} (@code{calc-fin-irr}) [@code{irr}] command is the -analogous function to @code{rate} but for net present value. -Its argument is a vector of payments. Thus @code{irr(@var{payments})} -computes the @var{rate} such that @code{npv(@var{rate}, @var{payments}) = 0}; -this rate is known as the @dfn{internal rate of return}. - -@kindex I b I -@tindex irrb -The @kbd{I b I} [@code{irrb}] command computes the internal rate of -return assuming payments occur at the beginning of each period. - -@node Depreciation Functions, Definitions of Financial Functions, Related Financial Functions, Financial Functions -@subsection Depreciation Functions - -@noindent -The functions in this section calculate @dfn{depreciation}, which is -the amount of value that a possession loses over time. These functions -are characterized by three parameters: @var{cost}, the original cost -of the asset; @var{salvage}, the value the asset will have at the end -of its expected ``useful life''; and @var{life}, the number of years -(or other periods) of the expected useful life. - -There are several methods for calculating depreciation that differ in -the way they spread the depreciation over the lifetime of the asset. - -@kindex b S -@pindex calc-fin-sln -@tindex sln -The @kbd{b S} (@code{calc-fin-sln}) [@code{sln}] command computes the -``straight-line'' depreciation. In this method, the asset depreciates -by the same amount every year (or period). For example, -@samp{sln(12000, 2000, 5)} returns 2000. The asset costs $12000 -initially and will be worth $2000 after five years; it loses $2000 -per year. - -@kindex b Y -@pindex calc-fin-syd -@tindex syd -The @kbd{b Y} (@code{calc-fin-syd}) [@code{syd}] command computes the -accelerated ``sum-of-years'-digits'' depreciation. Here the depreciation -is higher during the early years of the asset's life. Since the -depreciation is different each year, @kbd{b Y} takes a fourth @var{period} -parameter which specifies which year is requested, from 1 to @var{life}. -If @var{period} is outside this range, the @code{syd} function will -return zero. - -@kindex b D -@pindex calc-fin-ddb -@tindex ddb -The @kbd{b D} (@code{calc-fin-ddb}) [@code{ddb}] command computes an -accelerated depreciation using the double-declining balance method. -It also takes a fourth @var{period} parameter. - -For symmetry, the @code{sln} function will accept a @var{period} -parameter as well, although it will ignore its value except that the -return value will as usual be zero if @var{period} is out of range. - -For example, pushing the vector @expr{[1,2,3,4,5]} (perhaps with @kbd{v x 5}) -and then mapping @kbd{V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), -ddb(12000,2000,5,$)] @key{RET}} produces a matrix that allows us to compare -the three depreciation methods: - -@example -@group -[ [ 2000, 3333, 4800 ] - [ 2000, 2667, 2880 ] - [ 2000, 2000, 1728 ] - [ 2000, 1333, 592 ] - [ 2000, 667, 0 ] ] -@end group -@end example - -@noindent -(Values have been rounded to nearest integers in this figure.) -We see that @code{sln} depreciates by the same amount each year, -@kbd{syd} depreciates more at the beginning and less at the end, -and @kbd{ddb} weights the depreciation even more toward the beginning. - -Summing columns with @kbd{V R : +} yields @expr{[10000, 10000, 10000]}; -the total depreciation in any method is (by definition) the -difference between the cost and the salvage value. - -@node Definitions of Financial Functions, , Depreciation Functions, Financial Functions -@subsection Definitions - -@noindent -For your reference, here are the actual formulas used to compute -Calc's financial functions. - -Calc will not evaluate a financial function unless the @var{rate} or -@var{n} argument is known. However, @var{payment} or @var{amount} can -be a variable. Calc expands these functions according to the -formulas below for symbolic arguments only when you use the @kbd{a "} -(@code{calc-expand-formula}) command, or when taking derivatives or -integrals or solving equations involving the functions. - -@ifnottex -These formulas are shown using the conventions of Big display -mode (@kbd{d B}); for example, the formula for @code{fv} written -linearly is @samp{pmt * ((1 + rate)^n) - 1) / rate}. - -@example - n - (1 + rate) - 1 -fv(rate, n, pmt) = pmt * --------------- - rate - - n - ((1 + rate) - 1) (1 + rate) -fvb(rate, n, pmt) = pmt * ---------------------------- - rate - - n -fvl(rate, n, pmt) = pmt * (1 + rate) - - -n - 1 - (1 + rate) -pv(rate, n, pmt) = pmt * ---------------- - rate - - -n - (1 - (1 + rate) ) (1 + rate) -pvb(rate, n, pmt) = pmt * ----------------------------- - rate - - -n -pvl(rate, n, pmt) = pmt * (1 + rate) - - -1 -2 -3 -npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) - - -1 -2 -npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmt(rate, n, amt, x) = ------------------------------- - -n - 1 - (1 + rate) - - -n - (amt - x * (1 + rate) ) * rate -pmtb(rate, n, amt, x) = ------------------------------- - -n - (1 - (1 + rate) ) (1 + rate) - - amt * rate -nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) - pmt - - amt * rate -nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) - pmt * (1 + rate) - - amt -nperl(rate, pmt, amt) = - log(---, 1 + rate) - pmt - - 1/n - pmt -ratel(n, pmt, amt) = ------ - 1 - 1/n - amt - - cost - salv -sln(cost, salv, life) = ----------- - life - - (cost - salv) * (life - per + 1) -syd(cost, salv, life, per) = -------------------------------- - life * (life + 1) / 2 - - book * 2 -ddb(cost, salv, life, per) = --------, book = cost - depreciation so far - life -@end example -@end ifnottex -@tex -\turnoffactive -$$ \code{fv}(r, n, p) = p { (1 + r)^n - 1 \over r } $$ -$$ \code{fvb}(r, n, p) = p { ((1 + r)^n - 1) (1 + r) \over r } $$ -$$ \code{fvl}(r, n, p) = p (1 + r)^n $$ -$$ \code{pv}(r, n, p) = p { 1 - (1 + r)^{-n} \over r } $$ -$$ \code{pvb}(r, n, p) = p { (1 - (1 + r)^{-n}) (1 + r) \over r } $$ -$$ \code{pvl}(r, n, p) = p (1 + r)^{-n} $$ -$$ \code{npv}(r, [a,b,c]) = a (1 + r)^{-1} + b (1 + r)^{-2} + c (1 + r)^{-3} $$ -$$ \code{npvb}(r, [a,b,c]) = a + b (1 + r)^{-1} + c (1 + r)^{-2} $$ -$$ \code{pmt}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over 1 - (1 + r)^{-n} }$$ -$$ \code{pmtb}(r, n, a, x) = { (a - x (1 + r)^{-n}) r \over - (1 - (1 + r)^{-n}) (1 + r) } $$ -$$ \code{nper}(r, p, a) = -\code{log}(1 - { a r \over p }, 1 + r) $$ -$$ \code{nperb}(r, p, a) = -\code{log}(1 - { a r \over p (1 + r) }, 1 + r) $$ -$$ \code{nperl}(r, p, a) = -\code{log}({a \over p}, 1 + r) $$ -$$ \code{ratel}(n, p, a) = { p^{1/n} \over a^{1/n} } - 1 $$ -$$ \code{sln}(c, s, l) = { c - s \over l } $$ -$$ \code{syd}(c, s, l, p) = { (c - s) (l - p + 1) \over l (l+1) / 2 } $$ -$$ \code{ddb}(c, s, l, p) = { 2 (c - \hbox{depreciation so far}) \over l } $$ -@end tex - -@noindent -In @code{pmt} and @code{pmtb}, @expr{x=0} if omitted. - -These functions accept any numeric objects, including error forms, -intervals, and even (though not very usefully) complex numbers. The -above formulas specify exactly the behavior of these functions with -all sorts of inputs. - -Note that if the first argument to the @code{log} in @code{nper} is -negative, @code{nper} leaves itself in symbolic form rather than -returning a (financially meaningless) complex number. - -@samp{rate(num, pmt, amt)} solves the equation -@samp{pv(rate, num, pmt) = amt} for @samp{rate} using @kbd{H a R} -(@code{calc-find-root}), with the interval @samp{[.01% .. 100%]} -for an initial guess. The @code{rateb} function is the same except -that it uses @code{pvb}. Note that @code{ratel} can be solved -directly; its formula is shown in the above list. - -Similarly, @samp{irr(pmts)} solves the equation @samp{npv(rate, pmts) = 0} -for @samp{rate}. - -If you give a fourth argument to @code{nper} or @code{nperb}, Calc -will also use @kbd{H a R} to solve the equation using an initial -guess interval of @samp{[0 .. 100]}. - -A fourth argument to @code{fv} simply sums the two components -calculated from the above formulas for @code{fv} and @code{fvl}. -The same is true of @code{fvb}, @code{pv}, and @code{pvb}. - -The @kbd{ddb} function is computed iteratively; the ``book'' value -starts out equal to @var{cost}, and decreases according to the above -formula for the specified number of periods. If the book value -would decrease below @var{salvage}, it only decreases to @var{salvage} -and the depreciation is zero for all subsequent periods. The @code{ddb} -function returns the amount the book value decreased in the specified -period. - -@node Binary Functions, , Financial Functions, Arithmetic -@section Binary Number Functions - -@noindent -The commands in this chapter all use two-letter sequences beginning with -the @kbd{b} prefix. - -@cindex Binary numbers -The ``binary'' operations actually work regardless of the currently -displayed radix, although their results make the most sense in a radix -like 2, 8, or 16 (as obtained by the @kbd{d 2}, @kbd{d 8}, or @w{@kbd{d 6}} -commands, respectively). You may also wish to enable display of leading -zeros with @kbd{d z}. @xref{Radix Modes}. - -@cindex Word size for binary operations -The Calculator maintains a current @dfn{word size} @expr{w}, an -arbitrary positive or negative integer. For a positive word size, all -of the binary operations described here operate modulo @expr{2^w}. In -particular, negative arguments are converted to positive integers modulo -@expr{2^w} by all binary functions. - -If the word size is negative, binary operations produce 2's complement -integers from -@texline @math{-2^{-w-1}} -@infoline @expr{-(2^(-w-1))} -to -@texline @math{2^{-w-1}-1} -@infoline @expr{2^(-w-1)-1} -inclusive. Either mode accepts inputs in any range; the sign of -@expr{w} affects only the results produced. - -@kindex b c -@pindex calc-clip -@tindex clip -The @kbd{b c} (@code{calc-clip}) -[@code{clip}] command can be used to clip a number by reducing it modulo -@expr{2^w}. The commands described in this chapter automatically clip -their results to the current word size. Note that other operations like -addition do not use the current word size, since integer addition -generally is not ``binary.'' (However, @pxref{Simplification Modes}, -@code{calc-bin-simplify-mode}.) For example, with a word size of 8 -bits @kbd{b c} converts a number to the range 0 to 255; with a word -size of @mathit{-8} @kbd{b c} converts to the range @mathit{-128} to 127. - -@kindex b w -@pindex calc-word-size -The default word size is 32 bits. All operations except the shifts and -rotates allow you to specify a different word size for that one -operation by giving a numeric prefix argument: @kbd{C-u 8 b c} clips the -top of stack to the range 0 to 255 regardless of the current word size. -To set the word size permanently, use @kbd{b w} (@code{calc-word-size}). -This command displays a prompt with the current word size; press @key{RET} -immediately to keep this word size, or type a new word size at the prompt. - -When the binary operations are written in symbolic form, they take an -optional second (or third) word-size parameter. When a formula like -@samp{and(a,b)} is finally evaluated, the word size current at that time -will be used, but when @samp{and(a,b,-8)} is evaluated, a word size of -@mathit{-8} will always be used. A symbolic binary function will be left -in symbolic form unless the all of its argument(s) are integers or -integer-valued floats. - -If either or both arguments are modulo forms for which @expr{M} is a -power of two, that power of two is taken as the word size unless a -numeric prefix argument overrides it. The current word size is never -consulted when modulo-power-of-two forms are involved. - -@kindex b a -@pindex calc-and -@tindex and -The @kbd{b a} (@code{calc-and}) [@code{and}] command computes the bitwise -AND of the two numbers on the top of the stack. In other words, for each -of the @expr{w} binary digits of the two numbers (pairwise), the corresponding -bit of the result is 1 if and only if both input bits are 1: -@samp{and(2#1100, 2#1010) = 2#1000}. - -@kindex b o -@pindex calc-or -@tindex or -The @kbd{b o} (@code{calc-or}) [@code{or}] command computes the bitwise -inclusive OR of two numbers. A bit is 1 if either of the input bits, or -both, are 1: @samp{or(2#1100, 2#1010) = 2#1110}. - -@kindex b x -@pindex calc-xor -@tindex xor -The @kbd{b x} (@code{calc-xor}) [@code{xor}] command computes the bitwise -exclusive OR of two numbers. A bit is 1 if exactly one of the input bits -is 1: @samp{xor(2#1100, 2#1010) = 2#0110}. - -@kindex b d -@pindex calc-diff -@tindex diff -The @kbd{b d} (@code{calc-diff}) [@code{diff}] command computes the bitwise -difference of two numbers; this is defined by @samp{diff(a,b) = and(a,not(b))}, -so that @samp{diff(2#1100, 2#1010) = 2#0100}. - -@kindex b n -@pindex calc-not -@tindex not -The @kbd{b n} (@code{calc-not}) [@code{not}] command computes the bitwise -NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. - -@kindex b l -@pindex calc-lshift-binary -@tindex lsh -The @kbd{b l} (@code{calc-lshift-binary}) [@code{lsh}] command shifts a -number left by one bit, or by the number of bits specified in the numeric -prefix argument. A negative prefix argument performs a logical right shift, -in which zeros are shifted in on the left. In symbolic form, @samp{lsh(a)} -is short for @samp{lsh(a,1)}, which in turn is short for @samp{lsh(a,n,w)}. -Bits shifted ``off the end,'' according to the current word size, are lost. - -@kindex H b l -@kindex H b r -@ignore -@mindex @idots -@end ignore -@kindex H b L -@ignore -@mindex @null -@end ignore -@kindex H b R -@ignore -@mindex @null -@end ignore -@kindex H b t -The @kbd{H b l} command also does a left shift, but it takes two arguments -from the stack (the value to shift, and, at top-of-stack, the number of -bits to shift). This version interprets the prefix argument just like -the regular binary operations, i.e., as a word size. The Hyperbolic flag -has a similar effect on the rest of the binary shift and rotate commands. - -@kindex b r -@pindex calc-rshift-binary -@tindex rsh -The @kbd{b r} (@code{calc-rshift-binary}) [@code{rsh}] command shifts a -number right by one bit, or by the number of bits specified in the numeric -prefix argument: @samp{rsh(a,n) = lsh(a,-n)}. - -@kindex b L -@pindex calc-lshift-arith -@tindex ash -The @kbd{b L} (@code{calc-lshift-arith}) [@code{ash}] command shifts a -number left. It is analogous to @code{lsh}, except that if the shift -is rightward (the prefix argument is negative), an arithmetic shift -is performed as described below. - -@kindex b R -@pindex calc-rshift-arith -@tindex rash -The @kbd{b R} (@code{calc-rshift-arith}) [@code{rash}] command performs -an ``arithmetic'' shift to the right, in which the leftmost bit (according -to the current word size) is duplicated rather than shifting in zeros. -This corresponds to dividing by a power of two where the input is interpreted -as a signed, twos-complement number. (The distinction between the @samp{rsh} -and @samp{rash} operations is totally independent from whether the word -size is positive or negative.) With a negative prefix argument, this -performs a standard left shift. - -@kindex b t -@pindex calc-rotate-binary -@tindex rot -The @kbd{b t} (@code{calc-rotate-binary}) [@code{rot}] command rotates a -number one bit to the left. The leftmost bit (according to the current -word size) is dropped off the left and shifted in on the right. With a -numeric prefix argument, the number is rotated that many bits to the left -or right. - -@xref{Set Operations}, for the @kbd{b p} and @kbd{b u} commands that -pack and unpack binary integers into sets. (For example, @kbd{b u} -unpacks the number @samp{2#11001} to the set of bit-numbers -@samp{[0, 3, 4]}.) Type @kbd{b u V #} to count the number of ``1'' -bits in a binary integer. - -Another interesting use of the set representation of binary integers -is to reverse the bits in, say, a 32-bit integer. Type @kbd{b u} to -unpack; type @kbd{31 @key{TAB} -} to replace each bit-number in the set -with 31 minus that bit-number; type @kbd{b p} to pack the set back -into a binary integer. - -@node Scientific Functions, Matrix Functions, Arithmetic, Top -@chapter Scientific Functions - -@noindent -The functions described here perform trigonometric and other transcendental -calculations. They generally produce floating-point answers correct to the -full current precision. The @kbd{H} (Hyperbolic) and @kbd{I} (Inverse) -flag keys must be used to get some of these functions from the keyboard. - -@kindex P -@pindex calc-pi -@cindex @code{pi} variable -@vindex pi -@kindex H P -@cindex @code{e} variable -@vindex e -@kindex I P -@cindex @code{gamma} variable -@vindex gamma -@cindex Gamma constant, Euler's -@cindex Euler's gamma constant -@kindex H I P -@cindex @code{phi} variable -@cindex Phi, golden ratio -@cindex Golden ratio -One miscellaneous command is shift-@kbd{P} (@code{calc-pi}), which pushes -the value of @cpi{} (at the current precision) onto the stack. With the -Hyperbolic flag, it pushes the value @expr{e}, the base of natural logarithms. -With the Inverse flag, it pushes Euler's constant -@texline @math{\gamma} -@infoline @expr{gamma} -(about 0.5772). With both Inverse and Hyperbolic, it -pushes the ``golden ratio'' -@texline @math{\phi} -@infoline @expr{phi} -(about 1.618). (At present, Euler's constant is not available -to unlimited precision; Calc knows only the first 100 digits.) -In Symbolic mode, these commands push the -actual variables @samp{pi}, @samp{e}, @samp{gamma}, and @samp{phi}, -respectively, instead of their values; @pxref{Symbolic Mode}. - -@ignore -@mindex Q -@end ignore -@ignore -@mindex I Q -@end ignore -@kindex I Q -@tindex sqr -The @kbd{Q} (@code{calc-sqrt}) [@code{sqrt}] function is described elsewhere; -@pxref{Basic Arithmetic}. With the Inverse flag [@code{sqr}], this command -computes the square of the argument. - -@xref{Prefix Arguments}, for a discussion of the effect of numeric -prefix arguments on commands in this chapter which do not otherwise -interpret a prefix argument. - -@menu -* Logarithmic Functions:: -* Trigonometric and Hyperbolic Functions:: -* Advanced Math Functions:: -* Branch Cuts:: -* Random Numbers:: -* Combinatorial Functions:: -* Probability Distribution Functions:: -@end menu - -@node Logarithmic Functions, Trigonometric and Hyperbolic Functions, Scientific Functions, Scientific Functions -@section Logarithmic Functions - -@noindent -@kindex L -@pindex calc-ln -@tindex ln -@ignore -@mindex @null -@end ignore -@kindex I E -The shift-@kbd{L} (@code{calc-ln}) [@code{ln}] command computes the natural -logarithm of the real or complex number on the top of the stack. With -the Inverse flag it computes the exponential function instead, although -this is redundant with the @kbd{E} command. - -@kindex E -@pindex calc-exp -@tindex exp -@ignore -@mindex @null -@end ignore -@kindex I L -The shift-@kbd{E} (@code{calc-exp}) [@code{exp}] command computes the -exponential, i.e., @expr{e} raised to the power of the number on the stack. -The meanings of the Inverse and Hyperbolic flags follow from those for -the @code{calc-ln} command. - -@kindex H L -@kindex H E -@pindex calc-log10 -@tindex log10 -@tindex exp10 -@ignore -@mindex @null -@end ignore -@kindex H I L -@ignore -@mindex @null -@end ignore -@kindex H I E -The @kbd{H L} (@code{calc-log10}) [@code{log10}] command computes the common -(base-10) logarithm of a number. (With the Inverse flag [@code{exp10}], -it raises ten to a given power.) Note that the common logarithm of a -complex number is computed by taking the natural logarithm and dividing -by -@texline @math{\ln10}. -@infoline @expr{ln(10)}. - -@kindex B -@kindex I B -@pindex calc-log -@tindex log -@tindex alog -The @kbd{B} (@code{calc-log}) [@code{log}] command computes a logarithm -to any base. For example, @kbd{1024 @key{RET} 2 B} produces 10, since -@texline @math{2^{10} = 1024}. -@infoline @expr{2^10 = 1024}. -In certain cases like @samp{log(3,9)}, the result -will be either @expr{1:2} or @expr{0.5} depending on the current Fraction -mode setting. With the Inverse flag [@code{alog}], this command is -similar to @kbd{^} except that the order of the arguments is reversed. - -@kindex f I -@pindex calc-ilog -@tindex ilog -The @kbd{f I} (@code{calc-ilog}) [@code{ilog}] command computes the -integer logarithm of a number to any base. The number and the base must -themselves be positive integers. This is the true logarithm, rounded -down to an integer. Thus @kbd{ilog(x,10)} is 3 for all @expr{x} in the -range from 1000 to 9999. If both arguments are positive integers, exact -integer arithmetic is used; otherwise, this is equivalent to -@samp{floor(log(x,b))}. - -@kindex f E -@pindex calc-expm1 -@tindex expm1 -The @kbd{f E} (@code{calc-expm1}) [@code{expm1}] command computes -@texline @math{e^x - 1}, -@infoline @expr{exp(x)-1}, -but using an algorithm that produces a more accurate -answer when the result is close to zero, i.e., when -@texline @math{e^x} -@infoline @expr{exp(x)} -is close to one. - -@kindex f L -@pindex calc-lnp1 -@tindex lnp1 -The @kbd{f L} (@code{calc-lnp1}) [@code{lnp1}] command computes -@texline @math{\ln(x+1)}, -@infoline @expr{ln(x+1)}, -producing a more accurate answer when @expr{x} is close to zero. - -@node Trigonometric and Hyperbolic Functions, Advanced Math Functions, Logarithmic Functions, Scientific Functions -@section Trigonometric/Hyperbolic Functions - -@noindent -@kindex S -@pindex calc-sin -@tindex sin -The shift-@kbd{S} (@code{calc-sin}) [@code{sin}] command computes the sine -of an angle or complex number. If the input is an HMS form, it is interpreted -as degrees-minutes-seconds; otherwise, the input is interpreted according -to the current angular mode. It is best to use Radians mode when operating -on complex numbers. - -Calc's ``units'' mechanism includes angular units like @code{deg}, -@code{rad}, and @code{grad}. While @samp{sin(45 deg)} is not evaluated -all the time, the @kbd{u s} (@code{calc-simplify-units}) command will -simplify @samp{sin(45 deg)} by taking the sine of 45 degrees, regardless -of the current angular mode. @xref{Basic Operations on Units}. - -Also, the symbolic variable @code{pi} is not ordinarily recognized in -arguments to trigonometric functions, as in @samp{sin(3 pi / 4)}, but -the @kbd{a s} (@code{calc-simplify}) command recognizes many such -formulas when the current angular mode is Radians @emph{and} Symbolic -mode is enabled; this example would be replaced by @samp{sqrt(2) / 2}. -@xref{Symbolic Mode}. Beware, this simplification occurs even if you -have stored a different value in the variable @samp{pi}; this is one -reason why changing built-in variables is a bad idea. Arguments of -the form @expr{x} plus a multiple of @cpiover{2} are also simplified. -Calc includes similar formulas for @code{cos} and @code{tan}. - -The @kbd{a s} command knows all angles which are integer multiples of -@cpiover{12}, @cpiover{10}, or @cpiover{8} radians. In Degrees mode, -analogous simplifications occur for integer multiples of 15 or 18 -degrees, and for arguments plus multiples of 90 degrees. - -@kindex I S -@pindex calc-arcsin -@tindex arcsin -With the Inverse flag, @code{calc-sin} computes an arcsine. This is also -available as the @code{calc-arcsin} command or @code{arcsin} algebraic -function. The returned argument is converted to degrees, radians, or HMS -notation depending on the current angular mode. - -@kindex H S -@pindex calc-sinh -@tindex sinh -@kindex H I S -@pindex calc-arcsinh -@tindex arcsinh -With the Hyperbolic flag, @code{calc-sin} computes the hyperbolic -sine, also available as @code{calc-sinh} [@code{sinh}]. With the -Hyperbolic and Inverse flags, it computes the hyperbolic arcsine -(@code{calc-arcsinh}) [@code{arcsinh}]. - -@kindex C -@pindex calc-cos -@tindex cos -@ignore -@mindex @idots -@end ignore -@kindex I C -@pindex calc-arccos -@ignore -@mindex @null -@end ignore -@tindex arccos -@ignore -@mindex @null -@end ignore -@kindex H C -@pindex calc-cosh -@ignore -@mindex @null -@end ignore -@tindex cosh -@ignore -@mindex @null -@end ignore -@kindex H I C -@pindex calc-arccosh -@ignore -@mindex @null -@end ignore -@tindex arccosh -@ignore -@mindex @null -@end ignore -@kindex T -@pindex calc-tan -@ignore -@mindex @null -@end ignore -@tindex tan -@ignore -@mindex @null -@end ignore -@kindex I T -@pindex calc-arctan -@ignore -@mindex @null -@end ignore -@tindex arctan -@ignore -@mindex @null -@end ignore -@kindex H T -@pindex calc-tanh -@ignore -@mindex @null -@end ignore -@tindex tanh -@ignore -@mindex @null -@end ignore -@kindex H I T -@pindex calc-arctanh -@ignore -@mindex @null -@end ignore -@tindex arctanh -The shift-@kbd{C} (@code{calc-cos}) [@code{cos}] command computes the cosine -of an angle or complex number, and shift-@kbd{T} (@code{calc-tan}) [@code{tan}] -computes the tangent, along with all the various inverse and hyperbolic -variants of these functions. - -@kindex f T -@pindex calc-arctan2 -@tindex arctan2 -The @kbd{f T} (@code{calc-arctan2}) [@code{arctan2}] command takes two -numbers from the stack and computes the arc tangent of their ratio. The -result is in the full range from @mathit{-180} (exclusive) to @mathit{+180} -(inclusive) degrees, or the analogous range in radians. A similar -result would be obtained with @kbd{/} followed by @kbd{I T}, but the -value would only be in the range from @mathit{-90} to @mathit{+90} degrees -since the division loses information about the signs of the two -components, and an error might result from an explicit division by zero -which @code{arctan2} would avoid. By (arbitrary) definition, -@samp{arctan2(0,0)=0}. - -@pindex calc-sincos -@ignore -@starindex -@end ignore -@tindex sincos -@ignore -@starindex -@end ignore -@ignore -@mindex arc@idots -@end ignore -@tindex arcsincos -The @code{calc-sincos} [@code{sincos}] command computes the sine and -cosine of a number, returning them as a vector of the form -@samp{[@var{cos}, @var{sin}]}. -With the Inverse flag [@code{arcsincos}], this command takes a two-element -vector as an argument and computes @code{arctan2} of the elements. -(This command does not accept the Hyperbolic flag.) - -@pindex calc-sec -@tindex sec -@pindex calc-csc -@tindex csc -@pindex calc-cot -@tindex cot -@pindex calc-sech -@tindex sech -@pindex calc-csch -@tindex csch -@pindex calc-coth -@tindex coth -The remaining trigonometric functions, @code{calc-sec} [@code{sec}], -@code{calc-csc} [@code{csc}] and @code{calc-cot} [@code{cot}], are also -available. With the Hyperbolic flag, these compute their hyperbolic -counterparts, which are also available separately as @code{calc-sech} -[@code{sech}], @code{calc-csch} [@code{csch}] and @code{calc-coth} -[@code{coth}]. (These commands do not accept the Inverse flag.) - -@node Advanced Math Functions, Branch Cuts, Trigonometric and Hyperbolic Functions, Scientific Functions -@section Advanced Mathematical Functions - -@noindent -Calc can compute a variety of less common functions that arise in -various branches of mathematics. All of the functions described in -this section allow arbitrary complex arguments and, except as noted, -will work to arbitrarily large precisions. They can not at present -handle error forms or intervals as arguments. - -NOTE: These functions are still experimental. In particular, their -accuracy is not guaranteed in all domains. It is advisable to set the -current precision comfortably higher than you actually need when -using these functions. Also, these functions may be impractically -slow for some values of the arguments. - -@kindex f g -@pindex calc-gamma -@tindex gamma -The @kbd{f g} (@code{calc-gamma}) [@code{gamma}] command computes the Euler -gamma function. For positive integer arguments, this is related to the -factorial function: @samp{gamma(n+1) = fact(n)}. For general complex -arguments the gamma function can be defined by the following definite -integral: -@texline @math{\Gamma(a) = \int_0^\infty t^{a-1} e^t dt}. -@infoline @expr{gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)}. -(The actual implementation uses far more efficient computational methods.) - -@kindex f G -@tindex gammaP -@ignore -@mindex @idots -@end ignore -@kindex I f G -@ignore -@mindex @null -@end ignore -@kindex H f G -@ignore -@mindex @null -@end ignore -@kindex H I f G -@pindex calc-inc-gamma -@ignore -@mindex @null -@end ignore -@tindex gammaQ -@ignore -@mindex @null -@end ignore -@tindex gammag -@ignore -@mindex @null -@end ignore -@tindex gammaG -The @kbd{f G} (@code{calc-inc-gamma}) [@code{gammaP}] command computes -the incomplete gamma function, denoted @samp{P(a,x)}. This is defined by -the integral, -@texline @math{P(a,x) = \left( \int_0^x t^{a-1} e^t dt \right) / \Gamma(a)}. -@infoline @expr{gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)}. -This implies that @samp{gammaP(a,inf) = 1} for any @expr{a} (see the -definition of the normal gamma function). - -Several other varieties of incomplete gamma function are defined. -The complement of @expr{P(a,x)}, called @expr{Q(a,x) = 1-P(a,x)} by -some authors, is computed by the @kbd{I f G} [@code{gammaQ}] command. -You can think of this as taking the other half of the integral, from -@expr{x} to infinity. - -@ifnottex -The functions corresponding to the integrals that define @expr{P(a,x)} -and @expr{Q(a,x)} but without the normalizing @expr{1/gamma(a)} -factor are called @expr{g(a,x)} and @expr{G(a,x)}, respectively -(where @expr{g} and @expr{G} represent the lower- and upper-case Greek -letter gamma). You can obtain these using the @kbd{H f G} [@code{gammag}] -and @kbd{H I f G} [@code{gammaG}] commands. -@end ifnottex -@tex -\turnoffactive -The functions corresponding to the integrals that define $P(a,x)$ -and $Q(a,x)$ but without the normalizing $1/\Gamma(a)$ -factor are called $\gamma(a,x)$ and $\Gamma(a,x)$, respectively. -You can obtain these using the \kbd{H f G} [\code{gammag}] and -\kbd{I H f G} [\code{gammaG}] commands. -@end tex - -@kindex f b -@pindex calc-beta -@tindex beta -The @kbd{f b} (@code{calc-beta}) [@code{beta}] command computes the -Euler beta function, which is defined in terms of the gamma function as -@texline @math{B(a,b) = \Gamma(a) \Gamma(b) / \Gamma(a+b)}, -@infoline @expr{beta(a,b) = gamma(a) gamma(b) / gamma(a+b)}, -or by -@texline @math{B(a,b) = \int_0^1 t^{a-1} (1-t)^{b-1} dt}. -@infoline @expr{beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)}. - -@kindex f B -@kindex H f B -@pindex calc-inc-beta -@tindex betaI -@tindex betaB -The @kbd{f B} (@code{calc-inc-beta}) [@code{betaI}] command computes -the incomplete beta function @expr{I(x,a,b)}. It is defined by -@texline @math{I(x,a,b) = \left( \int_0^x t^{a-1} (1-t)^{b-1} dt \right) / B(a,b)}. -@infoline @expr{betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)}. -Once again, the @kbd{H} (hyperbolic) prefix gives the corresponding -un-normalized version [@code{betaB}]. - -@kindex f e -@kindex I f e -@pindex calc-erf -@tindex erf -@tindex erfc -The @kbd{f e} (@code{calc-erf}) [@code{erf}] command computes the -error function -@texline @math{\hbox{erf}(x) = {2 \over \sqrt{\pi}} \int_0^x e^{-t^2} dt}. -@infoline @expr{erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)}. -The complementary error function @kbd{I f e} (@code{calc-erfc}) [@code{erfc}] -is the corresponding integral from @samp{x} to infinity; the sum -@texline @math{\hbox{erf}(x) + \hbox{erfc}(x) = 1}. -@infoline @expr{erf(x) + erfc(x) = 1}. - -@kindex f j -@kindex f y -@pindex calc-bessel-J -@pindex calc-bessel-Y -@tindex besJ -@tindex besY -The @kbd{f j} (@code{calc-bessel-J}) [@code{besJ}] and @kbd{f y} -(@code{calc-bessel-Y}) [@code{besY}] commands compute the Bessel -functions of the first and second kinds, respectively. -In @samp{besJ(n,x)} and @samp{besY(n,x)} the ``order'' parameter -@expr{n} is often an integer, but is not required to be one. -Calc's implementation of the Bessel functions currently limits the -precision to 8 digits, and may not be exact even to that precision. -Use with care! - -@node Branch Cuts, Random Numbers, Advanced Math Functions, Scientific Functions -@section Branch Cuts and Principal Values - -@noindent -@cindex Branch cuts -@cindex Principal values -All of the logarithmic, trigonometric, and other scientific functions are -defined for complex numbers as well as for reals. -This section describes the values -returned in cases where the general result is a family of possible values. -Calc follows section 12.5.3 of Steele's @dfn{Common Lisp, the Language}, -second edition, in these matters. This section will describe each -function briefly; for a more detailed discussion (including some nifty -diagrams), consult Steele's book. - -Note that the branch cuts for @code{arctan} and @code{arctanh} were -changed between the first and second editions of Steele. Recent -versions of Calc follow the second edition. - -The new branch cuts exactly match those of the HP-28/48 calculators. -They also match those of Mathematica 1.2, except that Mathematica's -@code{arctan} cut is always in the right half of the complex plane, -and its @code{arctanh} cut is always in the top half of the plane. -Calc's cuts are continuous with quadrants I and III for @code{arctan}, -or II and IV for @code{arctanh}. - -Note: The current implementations of these functions with complex arguments -are designed with proper behavior around the branch cuts in mind, @emph{not} -efficiency or accuracy. You may need to increase the floating precision -and wait a while to get suitable answers from them. - -For @samp{sqrt(a+bi)}: When @expr{a<0} and @expr{b} is small but positive -or zero, the result is close to the @expr{+i} axis. For @expr{b} small and -negative, the result is close to the @expr{-i} axis. The result always lies -in the right half of the complex plane. - -For @samp{ln(a+bi)}: The real part is defined as @samp{ln(abs(a+bi))}. -The imaginary part is defined as @samp{arg(a+bi) = arctan2(b,a)}. -Thus the branch cuts for @code{sqrt} and @code{ln} both lie on the -negative real axis. - -The following table describes these branch cuts in another way. -If the real and imaginary parts of @expr{z} are as shown, then -the real and imaginary parts of @expr{f(z)} will be as shown. -Here @code{eps} stands for a small positive value; each -occurrence of @code{eps} may stand for a different small value. - -@smallexample - z sqrt(z) ln(z) ----------------------------------------- - +, 0 +, 0 any, 0 - -, 0 0, + any, pi - -, +eps +eps, + +eps, + - -, -eps +eps, - +eps, - -@end smallexample - -For @samp{z1^z2}: This is defined by @samp{exp(ln(z1)*z2)}. -One interesting consequence of this is that @samp{(-8)^1:3} does -not evaluate to @mathit{-2} as you might expect, but to the complex -number @expr{(1., 1.732)}. Both of these are valid cube roots -of @mathit{-8} (as is @expr{(1., -1.732)}); Calc chooses a perhaps -less-obvious root for the sake of mathematical consistency. - -For @samp{arcsin(z)}: This is defined by @samp{-i*ln(i*z + sqrt(1-z^2))}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arccos(z)}: This is defined by @samp{-i*ln(z + i*sqrt(1-z^2))}, -or equivalently by @samp{pi/2 - arcsin(z)}. The branch cuts are on -the real axis, less than @mathit{-1} and greater than 1. - -For @samp{arctan(z)}: This is defined by -@samp{(ln(1+i*z) - ln(1-i*z)) / (2*i)}. The branch cuts are on the -imaginary axis, below @expr{-i} and above @expr{i}. - -For @samp{arcsinh(z)}: This is defined by @samp{ln(z + sqrt(1+z^2))}. -The branch cuts are on the imaginary axis, below @expr{-i} and -above @expr{i}. - -For @samp{arccosh(z)}: This is defined by -@samp{ln(z + (z+1)*sqrt((z-1)/(z+1)))}. The branch cut is on the -real axis less than 1. - -For @samp{arctanh(z)}: This is defined by @samp{(ln(1+z) - ln(1-z)) / 2}. -The branch cuts are on the real axis, less than @mathit{-1} and greater than 1. - -The following tables for @code{arcsin}, @code{arccos}, and -@code{arctan} assume the current angular mode is Radians. The -hyperbolic functions operate independently of the angular mode. - -@smallexample - z arcsin(z) arccos(z) -------------------------------------------------------- - (-1..1), 0 (-pi/2..pi/2), 0 (0..pi), 0 - (-1..1), +eps (-pi/2..pi/2), +eps (0..pi), -eps - (-1..1), -eps (-pi/2..pi/2), -eps (0..pi), +eps - <-1, 0 -pi/2, + pi, - - <-1, +eps -pi/2 + eps, + pi - eps, - - <-1, -eps -pi/2 + eps, - pi - eps, + - >1, 0 pi/2, - 0, + - >1, +eps pi/2 - eps, + +eps, - - >1, -eps pi/2 - eps, - +eps, + -@end smallexample - -@smallexample - z arccosh(z) arctanh(z) ------------------------------------------------------ - (-1..1), 0 0, (0..pi) any, 0 - (-1..1), +eps +eps, (0..pi) any, +eps - (-1..1), -eps +eps, (-pi..0) any, -eps - <-1, 0 +, pi -, pi/2 - <-1, +eps +, pi - eps -, pi/2 - eps - <-1, -eps +, -pi + eps -, -pi/2 + eps - >1, 0 +, 0 +, -pi/2 - >1, +eps +, +eps +, pi/2 - eps - >1, -eps +, -eps +, -pi/2 + eps -@end smallexample - -@smallexample - z arcsinh(z) arctan(z) ------------------------------------------------------ - 0, (-1..1) 0, (-pi/2..pi/2) 0, any - 0, <-1 -, -pi/2 -pi/2, - - +eps, <-1 +, -pi/2 + eps pi/2 - eps, - - -eps, <-1 -, -pi/2 + eps -pi/2 + eps, - - 0, >1 +, pi/2 pi/2, + - +eps, >1 +, pi/2 - eps pi/2 - eps, + - -eps, >1 -, pi/2 - eps -pi/2 + eps, + -@end smallexample - -Finally, the following identities help to illustrate the relationship -between the complex trigonometric and hyperbolic functions. They -are valid everywhere, including on the branch cuts. - -@smallexample -sin(i*z) = i*sinh(z) arcsin(i*z) = i*arcsinh(z) -cos(i*z) = cosh(z) arcsinh(i*z) = i*arcsin(z) -tan(i*z) = i*tanh(z) arctan(i*z) = i*arctanh(z) -sinh(i*z) = i*sin(z) cosh(i*z) = cos(z) -@end smallexample - -The ``advanced math'' functions (gamma, Bessel, etc.@:) are also defined -for general complex arguments, but their branch cuts and principal values -are not rigorously specified at present. - -@node Random Numbers, Combinatorial Functions, Branch Cuts, Scientific Functions -@section Random Numbers - -@noindent -@kindex k r -@pindex calc-random -@tindex random -The @kbd{k r} (@code{calc-random}) [@code{random}] command produces -random numbers of various sorts. - -Given a positive numeric prefix argument @expr{M}, it produces a random -integer @expr{N} in the range -@texline @math{0 \le N < M}. -@infoline @expr{0 <= N < M}. -Each possible value @expr{N} appears with equal probability. - -With no numeric prefix argument, the @kbd{k r} command takes its argument -from the stack instead. Once again, if this is a positive integer @expr{M} -the result is a random integer less than @expr{M}. However, note that -while numeric prefix arguments are limited to six digits or so, an @expr{M} -taken from the stack can be arbitrarily large. If @expr{M} is negative, -the result is a random integer in the range -@texline @math{M < N \le 0}. -@infoline @expr{M < N <= 0}. - -If the value on the stack is a floating-point number @expr{M}, the result -is a random floating-point number @expr{N} in the range -@texline @math{0 \le N < M} -@infoline @expr{0 <= N < M} -or -@texline @math{M < N \le 0}, -@infoline @expr{M < N <= 0}, -according to the sign of @expr{M}. - -If @expr{M} is zero, the result is a Gaussian-distributed random real -number; the distribution has a mean of zero and a standard deviation -of one. The algorithm used generates random numbers in pairs; thus, -every other call to this function will be especially fast. - -If @expr{M} is an error form -@texline @math{m} @code{+/-} @math{\sigma} -@infoline @samp{m +/- s} -where @var{m} and -@texline @math{\sigma} -@infoline @var{s} -are both real numbers, the result uses a Gaussian distribution with mean -@var{m} and standard deviation -@texline @math{\sigma}. -@infoline @var{s}. - -If @expr{M} is an interval form, the lower and upper bounds specify the -acceptable limits of the random numbers. If both bounds are integers, -the result is a random integer in the specified range. If either bound -is floating-point, the result is a random real number in the specified -range. If the interval is open at either end, the result will be sure -not to equal that end value. (This makes a big difference for integer -intervals, but for floating-point intervals it's relatively minor: -with a precision of 6, @samp{random([1.0..2.0))} will return any of one -million numbers from 1.00000 to 1.99999; @samp{random([1.0..2.0])} may -additionally return 2.00000, but the probability of this happening is -extremely small.) - -If @expr{M} is a vector, the result is one element taken at random from -the vector. All elements of the vector are given equal probabilities. - -@vindex RandSeed -The sequence of numbers produced by @kbd{k r} is completely random by -default, i.e., the sequence is seeded each time you start Calc using -the current time and other information. You can get a reproducible -sequence by storing a particular ``seed value'' in the Calc variable -@code{RandSeed}. Any integer will do for a seed; integers of from 1 -to 12 digits are good. If you later store a different integer into -@code{RandSeed}, Calc will switch to a different pseudo-random -sequence. If you ``unstore'' @code{RandSeed}, Calc will re-seed itself -from the current time. If you store the same integer that you used -before back into @code{RandSeed}, you will get the exact same sequence -of random numbers as before. - -@pindex calc-rrandom -The @code{calc-rrandom} command (not on any key) produces a random real -number between zero and one. It is equivalent to @samp{random(1.0)}. - -@kindex k a -@pindex calc-random-again -The @kbd{k a} (@code{calc-random-again}) command produces another random -number, re-using the most recent value of @expr{M}. With a numeric -prefix argument @var{n}, it produces @var{n} more random numbers using -that value of @expr{M}. - -@kindex k h -@pindex calc-shuffle -@tindex shuffle -The @kbd{k h} (@code{calc-shuffle}) command produces a vector of several -random values with no duplicates. The value on the top of the stack -specifies the set from which the random values are drawn, and may be any -of the @expr{M} formats described above. The numeric prefix argument -gives the length of the desired list. (If you do not provide a numeric -prefix argument, the length of the list is taken from the top of the -stack, and @expr{M} from second-to-top.) - -If @expr{M} is a floating-point number, zero, or an error form (so -that the random values are being drawn from the set of real numbers) -there is little practical difference between using @kbd{k h} and using -@kbd{k r} several times. But if the set of possible values consists -of just a few integers, or the elements of a vector, then there is -a very real chance that multiple @kbd{k r}'s will produce the same -number more than once. The @kbd{k h} command produces a vector whose -elements are always distinct. (Actually, there is a slight exception: -If @expr{M} is a vector, no given vector element will be drawn more -than once, but if several elements of @expr{M} are equal, they may -each make it into the result vector.) - -One use of @kbd{k h} is to rearrange a list at random. This happens -if the prefix argument is equal to the number of values in the list: -@kbd{[1, 1.5, 2, 2.5, 3] 5 k h} might produce the permuted list -@samp{[2.5, 1, 1.5, 3, 2]}. As a convenient feature, if the argument -@var{n} is negative it is replaced by the size of the set represented -by @expr{M}. Naturally, this is allowed only when @expr{M} specifies -a small discrete set of possibilities. - -To do the equivalent of @kbd{k h} but with duplications allowed, -given @expr{M} on the stack and with @var{n} just entered as a numeric -prefix, use @kbd{v b} to build a vector of copies of @expr{M}, then use -@kbd{V M k r} to ``map'' the normal @kbd{k r} function over the -elements of this vector. @xref{Matrix Functions}. - -@menu -* Random Number Generator:: (Complete description of Calc's algorithm) -@end menu - -@node Random Number Generator, , Random Numbers, Random Numbers -@subsection Random Number Generator - -Calc's random number generator uses several methods to ensure that -the numbers it produces are highly random. Knuth's @emph{Art of -Computer Programming}, Volume II, contains a thorough description -of the theory of random number generators and their measurement and -characterization. - -If @code{RandSeed} has no stored value, Calc calls Emacs' built-in -@code{random} function to get a stream of random numbers, which it -then treats in various ways to avoid problems inherent in the simple -random number generators that many systems use to implement @code{random}. - -When Calc's random number generator is first invoked, it ``seeds'' -the low-level random sequence using the time of day, so that the -random number sequence will be different every time you use Calc. - -Since Emacs Lisp doesn't specify the range of values that will be -returned by its @code{random} function, Calc exercises the function -several times to estimate the range. When Calc subsequently uses -the @code{random} function, it takes only 10 bits of the result -near the most-significant end. (It avoids at least the bottom -four bits, preferably more, and also tries to avoid the top two -bits.) This strategy works well with the linear congruential -generators that are typically used to implement @code{random}. - -If @code{RandSeed} contains an integer, Calc uses this integer to -seed an ``additive congruential'' method (Knuth's algorithm 3.2.2A, -computing -@texline @math{X_{n-55} - X_{n-24}}. -@infoline @expr{X_n-55 - X_n-24}). -This method expands the seed -value into a large table which is maintained internally; the variable -@code{RandSeed} is changed from, e.g., 42 to the vector @expr{[42]} -to indicate that the seed has been absorbed into this table. When -@code{RandSeed} contains a vector, @kbd{k r} and related commands -continue to use the same internal table as last time. There is no -way to extract the complete state of the random number generator -so that you can restart it from any point; you can only restart it -from the same initial seed value. A simple way to restart from the -same seed is to type @kbd{s r RandSeed} to get the seed vector, -@kbd{v u} to unpack it back into a number, then @kbd{s t RandSeed} -to reseed the generator with that number. - -Calc uses a ``shuffling'' method as described in algorithm 3.2.2B -of Knuth. It fills a table with 13 random 10-bit numbers. Then, -to generate a new random number, it uses the previous number to -index into the table, picks the value it finds there as the new -random number, then replaces that table entry with a new value -obtained from a call to the base random number generator (either -the additive congruential generator or the @code{random} function -supplied by the system). If there are any flaws in the base -generator, shuffling will tend to even them out. But if the system -provides an excellent @code{random} function, shuffling will not -damage its randomness. - -To create a random integer of a certain number of digits, Calc -builds the integer three decimal digits at a time. For each group -of three digits, Calc calls its 10-bit shuffling random number generator -(which returns a value from 0 to 1023); if the random value is 1000 -or more, Calc throws it out and tries again until it gets a suitable -value. - -To create a random floating-point number with precision @var{p}, Calc -simply creates a random @var{p}-digit integer and multiplies by -@texline @math{10^{-p}}. -@infoline @expr{10^-p}. -The resulting random numbers should be very clean, but note -that relatively small numbers will have few significant random digits. -In other words, with a precision of 12, you will occasionally get -numbers on the order of -@texline @math{10^{-9}} -@infoline @expr{10^-9} -or -@texline @math{10^{-10}}, -@infoline @expr{10^-10}, -but those numbers will only have two or three random digits since they -correspond to small integers times -@texline @math{10^{-12}}. -@infoline @expr{10^-12}. - -To create a random integer in the interval @samp{[0 .. @var{m})}, Calc -counts the digits in @var{m}, creates a random integer with three -additional digits, then reduces modulo @var{m}. Unless @var{m} is a -power of ten the resulting values will be very slightly biased toward -the lower numbers, but this bias will be less than 0.1%. (For example, -if @var{m} is 42, Calc will reduce a random integer less than 100000 -modulo 42 to get a result less than 42. It is easy to show that the -numbers 40 and 41 will be only 2380/2381 as likely to result from this -modulo operation as numbers 39 and below.) If @var{m} is a power of -ten, however, the numbers should be completely unbiased. - -The Gaussian random numbers generated by @samp{random(0.0)} use the -``polar'' method described in Knuth section 3.4.1C. This method -generates a pair of Gaussian random numbers at a time, so only every -other call to @samp{random(0.0)} will require significant calculations. - -@node Combinatorial Functions, Probability Distribution Functions, Random Numbers, Scientific Functions -@section Combinatorial Functions - -@noindent -Commands relating to combinatorics and number theory begin with the -@kbd{k} key prefix. - -@kindex k g -@pindex calc-gcd -@tindex gcd -The @kbd{k g} (@code{calc-gcd}) [@code{gcd}] command computes the -Greatest Common Divisor of two integers. It also accepts fractions; -the GCD of two fractions is defined by taking the GCD of the -numerators, and the LCM of the denominators. This definition is -consistent with the idea that @samp{a / gcd(a,x)} should yield an -integer for any @samp{a} and @samp{x}. For other types of arguments, -the operation is left in symbolic form. - -@kindex k l -@pindex calc-lcm -@tindex lcm -The @kbd{k l} (@code{calc-lcm}) [@code{lcm}] command computes the -Least Common Multiple of two integers or fractions. The product of -the LCM and GCD of two numbers is equal to the product of the -numbers. - -@kindex k E -@pindex calc-extended-gcd -@tindex egcd -The @kbd{k E} (@code{calc-extended-gcd}) [@code{egcd}] command computes -the GCD of two integers @expr{x} and @expr{y} and returns a vector -@expr{[g, a, b]} where -@texline @math{g = \gcd(x,y) = a x + b y}. -@infoline @expr{g = gcd(x,y) = a x + b y}. - -@kindex ! -@pindex calc-factorial -@tindex fact -@ignore -@mindex @null -@end ignore -@tindex ! -The @kbd{!} (@code{calc-factorial}) [@code{fact}] command computes the -factorial of the number at the top of the stack. If the number is an -integer, the result is an exact integer. If the number is an -integer-valued float, the result is a floating-point approximation. If -the number is a non-integral real number, the generalized factorial is used, -as defined by the Euler Gamma function. Please note that computation of -large factorials can be slow; using floating-point format will help -since fewer digits must be maintained. The same is true of many of -the commands in this section. - -@kindex k d -@pindex calc-double-factorial -@tindex dfact -@ignore -@mindex @null -@end ignore -@tindex !! -The @kbd{k d} (@code{calc-double-factorial}) [@code{dfact}] command -computes the ``double factorial'' of an integer. For an even integer, -this is the product of even integers from 2 to @expr{N}. For an odd -integer, this is the product of odd integers from 3 to @expr{N}. If -the argument is an integer-valued float, the result is a floating-point -approximation. This function is undefined for negative even integers. -The notation @expr{N!!} is also recognized for double factorials. - -@kindex k c -@pindex calc-choose -@tindex choose -The @kbd{k c} (@code{calc-choose}) [@code{choose}] command computes the -binomial coefficient @expr{N}-choose-@expr{M}, where @expr{M} is the number -on the top of the stack and @expr{N} is second-to-top. If both arguments -are integers, the result is an exact integer. Otherwise, the result is a -floating-point approximation. The binomial coefficient is defined for all -real numbers by -@texline @math{N! \over M! (N-M)!\,}. -@infoline @expr{N! / M! (N-M)!}. - -@kindex H k c -@pindex calc-perm -@tindex perm -@ifnottex -The @kbd{H k c} (@code{calc-perm}) [@code{perm}] command computes the -number-of-permutations function @expr{N! / (N-M)!}. -@end ifnottex -@tex -The \kbd{H k c} (\code{calc-perm}) [\code{perm}] command computes the -number-of-perm\-utations function $N! \over (N-M)!\,$. -@end tex - -@kindex k b -@kindex H k b -@pindex calc-bernoulli-number -@tindex bern -The @kbd{k b} (@code{calc-bernoulli-number}) [@code{bern}] command -computes a given Bernoulli number. The value at the top of the stack -is a nonnegative integer @expr{n} that specifies which Bernoulli number -is desired. The @kbd{H k b} command computes a Bernoulli polynomial, -taking @expr{n} from the second-to-top position and @expr{x} from the -top of the stack. If @expr{x} is a variable or formula the result is -a polynomial in @expr{x}; if @expr{x} is a number the result is a number. - -@kindex k e -@kindex H k e -@pindex calc-euler-number -@tindex euler -The @kbd{k e} (@code{calc-euler-number}) [@code{euler}] command similarly -computes an Euler number, and @w{@kbd{H k e}} computes an Euler polynomial. -Bernoulli and Euler numbers occur in the Taylor expansions of several -functions. - -@kindex k s -@kindex H k s -@pindex calc-stirling-number -@tindex stir1 -@tindex stir2 -The @kbd{k s} (@code{calc-stirling-number}) [@code{stir1}] command -computes a Stirling number of the first -@texline kind@tie{}@math{n \brack m}, -@infoline kind, -given two integers @expr{n} and @expr{m} on the stack. The @kbd{H k s} -[@code{stir2}] command computes a Stirling number of the second -@texline kind@tie{}@math{n \brace m}. -@infoline kind. -These are the number of @expr{m}-cycle permutations of @expr{n} objects, -and the number of ways to partition @expr{n} objects into @expr{m} -non-empty sets, respectively. - -@kindex k p -@pindex calc-prime-test -@cindex Primes -The @kbd{k p} (@code{calc-prime-test}) command checks if the integer on -the top of the stack is prime. For integers less than eight million, the -answer is always exact and reasonably fast. For larger integers, a -probabilistic method is used (see Knuth vol. II, section 4.5.4, algorithm P). -The number is first checked against small prime factors (up to 13). Then, -any number of iterations of the algorithm are performed. Each step either -discovers that the number is non-prime, or substantially increases the -certainty that the number is prime. After a few steps, the chance that -a number was mistakenly described as prime will be less than one percent. -(Indeed, this is a worst-case estimate of the probability; in practice -even a single iteration is quite reliable.) After the @kbd{k p} command, -the number will be reported as definitely prime or non-prime if possible, -or otherwise ``probably'' prime with a certain probability of error. - -@ignore -@starindex -@end ignore -@tindex prime -The normal @kbd{k p} command performs one iteration of the primality -test. Pressing @kbd{k p} repeatedly for the same integer will perform -additional iterations. Also, @kbd{k p} with a numeric prefix performs -the specified number of iterations. There is also an algebraic function -@samp{prime(n)} or @samp{prime(n,iters)} which returns 1 if @expr{n} -is (probably) prime and 0 if not. - -@kindex k f -@pindex calc-prime-factors -@tindex prfac -The @kbd{k f} (@code{calc-prime-factors}) [@code{prfac}] command -attempts to decompose an integer into its prime factors. For numbers up -to 25 million, the answer is exact although it may take some time. The -result is a vector of the prime factors in increasing order. For larger -inputs, prime factors above 5000 may not be found, in which case the -last number in the vector will be an unfactored integer greater than 25 -million (with a warning message). For negative integers, the first -element of the list will be @mathit{-1}. For inputs @mathit{-1}, @mathit{0}, and -@mathit{1}, the result is a list of the same number. - -@kindex k n -@pindex calc-next-prime -@ignore -@mindex nextpr@idots -@end ignore -@tindex nextprime -The @kbd{k n} (@code{calc-next-prime}) [@code{nextprime}] command finds -the next prime above a given number. Essentially, it searches by calling -@code{calc-prime-test} on successive integers until it finds one that -passes the test. This is quite fast for integers less than eight million, -but once the probabilistic test comes into play the search may be rather -slow. Ordinarily this command stops for any prime that passes one iteration -of the primality test. With a numeric prefix argument, a number must pass -the specified number of iterations before the search stops. (This only -matters when searching above eight million.) You can always use additional -@kbd{k p} commands to increase your certainty that the number is indeed -prime. - -@kindex I k n -@pindex calc-prev-prime -@ignore -@mindex prevpr@idots -@end ignore -@tindex prevprime -The @kbd{I k n} (@code{calc-prev-prime}) [@code{prevprime}] command -analogously finds the next prime less than a given number. - -@kindex k t -@pindex calc-totient -@tindex totient -The @kbd{k t} (@code{calc-totient}) [@code{totient}] command computes the -Euler ``totient'' -@texline function@tie{}@math{\phi(n)}, -@infoline function, -the number of integers less than @expr{n} which -are relatively prime to @expr{n}. - -@kindex k m -@pindex calc-moebius -@tindex moebius -The @kbd{k m} (@code{calc-moebius}) [@code{moebius}] command computes the -@texline M@"obius @math{\mu} -@infoline Moebius ``mu'' -function. If the input number is a product of @expr{k} -distinct factors, this is @expr{(-1)^k}. If the input number has any -duplicate factors (i.e., can be divided by the same prime more than once), -the result is zero. - -@node Probability Distribution Functions, , Combinatorial Functions, Scientific Functions -@section Probability Distribution Functions - -@noindent -The functions in this section compute various probability distributions. -For continuous distributions, this is the integral of the probability -density function from @expr{x} to infinity. (These are the ``upper -tail'' distribution functions; there are also corresponding ``lower -tail'' functions which integrate from minus infinity to @expr{x}.) -For discrete distributions, the upper tail function gives the sum -from @expr{x} to infinity; the lower tail function gives the sum -from minus infinity up to, but not including,@w{ }@expr{x}. - -To integrate from @expr{x} to @expr{y}, just use the distribution -function twice and subtract. For example, the probability that a -Gaussian random variable with mean 2 and standard deviation 1 will -lie in the range from 2.5 to 2.8 is @samp{utpn(2.5,2,1) - utpn(2.8,2,1)} -(``the probability that it is greater than 2.5, but not greater than 2.8''), -or equivalently @samp{ltpn(2.8,2,1) - ltpn(2.5,2,1)}. - -@kindex k B -@kindex I k B -@pindex calc-utpb -@tindex utpb -@tindex ltpb -The @kbd{k B} (@code{calc-utpb}) [@code{utpb}] function uses the -binomial distribution. Push the parameters @var{n}, @var{p}, and -then @var{x} onto the stack; the result (@samp{utpb(x,n,p)}) is the -probability that an event will occur @var{x} or more times out -of @var{n} trials, if its probability of occurring in any given -trial is @var{p}. The @kbd{I k B} [@code{ltpb}] function is -the probability that the event will occur fewer than @var{x} times. - -The other probability distribution functions similarly take the -form @kbd{k @var{X}} (@code{calc-utp@var{x}}) [@code{utp@var{x}}] -and @kbd{I k @var{X}} [@code{ltp@var{x}}], for various letters -@var{x}. The arguments to the algebraic functions are the value of -the random variable first, then whatever other parameters define the -distribution. Note these are among the few Calc functions where the -order of the arguments in algebraic form differs from the order of -arguments as found on the stack. (The random variable comes last on -the stack, so that you can type, e.g., @kbd{2 @key{RET} 1 @key{RET} 2.5 -k N M-@key{RET} @key{DEL} 2.8 k N -}, using @kbd{M-@key{RET} @key{DEL}} to -recover the original arguments but substitute a new value for @expr{x}.) - -@kindex k C -@pindex calc-utpc -@tindex utpc -@ignore -@mindex @idots -@end ignore -@kindex I k C -@ignore -@mindex @null -@end ignore -@tindex ltpc -The @samp{utpc(x,v)} function uses the chi-square distribution with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a model is -correct if its chi-square statistic is @expr{x}. - -@kindex k F -@pindex calc-utpf -@tindex utpf -@ignore -@mindex @idots -@end ignore -@kindex I k F -@ignore -@mindex @null -@end ignore -@tindex ltpf -The @samp{utpf(F,v1,v2)} function uses the F distribution, used in -various statistical tests. The parameters -@texline @math{\nu_1} -@infoline @expr{v1} -and -@texline @math{\nu_2} -@infoline @expr{v2} -are the degrees of freedom in the numerator and denominator, -respectively, used in computing the statistic @expr{F}. - -@kindex k N -@pindex calc-utpn -@tindex utpn -@ignore -@mindex @idots -@end ignore -@kindex I k N -@ignore -@mindex @null -@end ignore -@tindex ltpn -The @samp{utpn(x,m,s)} function uses a normal (Gaussian) distribution -with mean @expr{m} and standard deviation -@texline @math{\sigma}. -@infoline @expr{s}. -It is the probability that such a normal-distributed random variable -would exceed @expr{x}. - -@kindex k P -@pindex calc-utpp -@tindex utpp -@ignore -@mindex @idots -@end ignore -@kindex I k P -@ignore -@mindex @null -@end ignore -@tindex ltpp -The @samp{utpp(n,x)} function uses a Poisson distribution with -mean @expr{x}. It is the probability that @expr{n} or more such -Poisson random events will occur. - -@kindex k T -@pindex calc-ltpt -@tindex utpt -@ignore -@mindex @idots -@end ignore -@kindex I k T -@ignore -@mindex @null -@end ignore -@tindex ltpt -The @samp{utpt(t,v)} function uses the Student's ``t'' distribution -with -@texline @math{\nu} -@infoline @expr{v} -degrees of freedom. It is the probability that a -t-distributed random variable will be greater than @expr{t}. -(Note: This computes the distribution function -@texline @math{A(t|\nu)} -@infoline @expr{A(t|v)} -where -@texline @math{A(0|\nu) = 1} -@infoline @expr{A(0|v) = 1} -and -@texline @math{A(\infty|\nu) \to 0}. -@infoline @expr{A(inf|v) -> 0}. -The @code{UTPT} operation on the HP-48 uses a different definition which -returns half of Calc's value: @samp{UTPT(t,v) = .5*utpt(t,v)}.) - -While Calc does not provide inverses of the probability distribution -functions, the @kbd{a R} command can be used to solve for the inverse. -Since the distribution functions are monotonic, @kbd{a R} is guaranteed -to be able to find a solution given any initial guess. -@xref{Numerical Solutions}. - -@node Matrix Functions, Algebra, Scientific Functions, Top -@chapter Vector/Matrix Functions - -@noindent -Many of the commands described here begin with the @kbd{v} prefix. -(For convenience, the shift-@kbd{V} prefix is equivalent to @kbd{v}.) -The commands usually apply to both plain vectors and matrices; some -apply only to matrices or only to square matrices. If the argument -has the wrong dimensions the operation is left in symbolic form. - -Vectors are entered and displayed using @samp{[a,b,c]} notation. -Matrices are vectors of which all elements are vectors of equal length. -(Though none of the standard Calc commands use this concept, a -three-dimensional matrix or rank-3 tensor could be defined as a -vector of matrices, and so on.) - -@menu -* Packing and Unpacking:: -* Building Vectors:: -* Extracting Elements:: -* Manipulating Vectors:: -* Vector and Matrix Arithmetic:: -* Set Operations:: -* Statistical Operations:: -* Reducing and Mapping:: -* Vector and Matrix Formats:: -@end menu - -@node Packing and Unpacking, Building Vectors, Matrix Functions, Matrix Functions -@section Packing and Unpacking - -@noindent -Calc's ``pack'' and ``unpack'' commands collect stack entries to build -composite objects such as vectors and complex numbers. They are -described in this chapter because they are most often used to build -vectors. - -@kindex v p -@pindex calc-pack -The @kbd{v p} (@code{calc-pack}) [@code{pack}] command collects several -elements from the stack into a matrix, complex number, HMS form, error -form, etc. It uses a numeric prefix argument to specify the kind of -object to be built; this argument is referred to as the ``packing mode.'' -If the packing mode is a nonnegative integer, a vector of that -length is created. For example, @kbd{C-u 5 v p} will pop the top -five stack elements and push back a single vector of those five -elements. (@kbd{C-u 0 v p} simply creates an empty vector.) - -The same effect can be had by pressing @kbd{[} to push an incomplete -vector on the stack, using @key{TAB} (@code{calc-roll-down}) to sneak -the incomplete object up past a certain number of elements, and -then pressing @kbd{]} to complete the vector. - -Negative packing modes create other kinds of composite objects: - -@table @cite -@item -1 -Two values are collected to build a complex number. For example, -@kbd{5 @key{RET} 7 C-u -1 v p} creates the complex number -@expr{(5, 7)}. The result is always a rectangular complex -number. The two input values must both be real numbers, -i.e., integers, fractions, or floats. If they are not, Calc -will instead build a formula like @samp{a + (0, 1) b}. (The -other packing modes also create a symbolic answer if the -components are not suitable.) - -@item -2 -Two values are collected to build a polar complex number. -The first is the magnitude; the second is the phase expressed -in either degrees or radians according to the current angular -mode. - -@item -3 -Three values are collected into an HMS form. The first -two values (hours and minutes) must be integers or -integer-valued floats. The third value may be any real -number. - -@item -4 -Two values are collected into an error form. The inputs -may be real numbers or formulas. - -@item -5 -Two values are collected into a modulo form. The inputs -must be real numbers. - -@item -6 -Two values are collected into the interval @samp{[a .. b]}. -The inputs may be real numbers, HMS or date forms, or formulas. - -@item -7 -Two values are collected into the interval @samp{[a .. b)}. - -@item -8 -Two values are collected into the interval @samp{(a .. b]}. - -@item -9 -Two values are collected into the interval @samp{(a .. b)}. - -@item -10 -Two integer values are collected into a fraction. - -@item -11 -Two values are collected into a floating-point number. -The first is the mantissa; the second, which must be an -integer, is the exponent. The result is the mantissa -times ten to the power of the exponent. - -@item -12 -This is treated the same as @mathit{-11} by the @kbd{v p} command. -When unpacking, @mathit{-12} specifies that a floating-point mantissa -is desired. - -@item -13 -A real number is converted into a date form. - -@item -14 -Three numbers (year, month, day) are packed into a pure date form. - -@item -15 -Six numbers are packed into a date/time form. -@end table - -With any of the two-input negative packing modes, either or both -of the inputs may be vectors. If both are vectors of the same -length, the result is another vector made by packing corresponding -elements of the input vectors. If one input is a vector and the -other is a plain number, the number is packed along with each vector -element to produce a new vector. For example, @kbd{C-u -4 v p} -could be used to convert a vector of numbers and a vector of errors -into a single vector of error forms; @kbd{C-u -5 v p} could convert -a vector of numbers and a single number @var{M} into a vector of -numbers modulo @var{M}. - -If you don't give a prefix argument to @kbd{v p}, it takes -the packing mode from the top of the stack. The elements to -be packed then begin at stack level 2. Thus -@kbd{1 @key{RET} 2 @key{RET} 4 n v p} is another way to -enter the error form @samp{1 +/- 2}. - -If the packing mode taken from the stack is a vector, the result is a -matrix with the dimensions specified by the elements of the vector, -which must each be integers. For example, if the packing mode is -@samp{[2, 3]}, then six numbers will be taken from the stack and -returned in the form @samp{[@w{[a, b, c]}, [d, e, f]]}. - -If any elements of the vector are negative, other kinds of -packing are done at that level as described above. For -example, @samp{[2, 3, -4]} takes 12 objects and creates a -@texline @math{2\times3} -@infoline 2x3 -matrix of error forms: @samp{[[a +/- b, c +/- d ... ]]}. -Also, @samp{[-4, -10]} will convert four integers into an -error form consisting of two fractions: @samp{a:b +/- c:d}. - -@ignore -@starindex -@end ignore -@tindex pack -There is an equivalent algebraic function, -@samp{pack(@var{mode}, @var{items})} where @var{mode} is a -packing mode (an integer or a vector of integers) and @var{items} -is a vector of objects to be packed (re-packed, really) according -to that mode. For example, @samp{pack([3, -4], [a,b,c,d,e,f])} -yields @samp{[a +/- b, @w{c +/- d}, e +/- f]}. The function is -left in symbolic form if the packing mode is invalid, or if the -number of data items does not match the number of items required -by the mode. - -@kindex v u -@pindex calc-unpack -The @kbd{v u} (@code{calc-unpack}) command takes the vector, complex -number, HMS form, or other composite object on the top of the stack and -``unpacks'' it, pushing each of its elements onto the stack as separate -objects. Thus, it is the ``inverse'' of @kbd{v p}. If the value -at the top of the stack is a formula, @kbd{v u} unpacks it by pushing -each of the arguments of the top-level operator onto the stack. - -You can optionally give a numeric prefix argument to @kbd{v u} -to specify an explicit (un)packing mode. If the packing mode is -negative and the input is actually a vector or matrix, the result -will be two or more similar vectors or matrices of the elements. -For example, given the vector @samp{[@w{a +/- b}, c^2, d +/- 7]}, -the result of @kbd{C-u -4 v u} will be the two vectors -@samp{[a, c^2, d]} and @w{@samp{[b, 0, 7]}}. - -Note that the prefix argument can have an effect even when the input is -not a vector. For example, if the input is the number @mathit{-5}, then -@kbd{c-u -1 v u} yields @mathit{-5} and 0 (the components of @mathit{-5} -when viewed as a rectangular complex number); @kbd{C-u -2 v u} yields 5 -and 180 (assuming Degrees mode); and @kbd{C-u -10 v u} yields @mathit{-5} -and 1 (the numerator and denominator of @mathit{-5}, viewed as a rational -number). Plain @kbd{v u} with this input would complain that the input -is not a composite object. - -Unpacking mode @mathit{-11} converts a float into an integer mantissa and -an integer exponent, where the mantissa is not divisible by 10 -(except that 0.0 is represented by a mantissa and exponent of 0). -Unpacking mode @mathit{-12} converts a float into a floating-point mantissa -and integer exponent, where the mantissa (for non-zero numbers) -is guaranteed to lie in the range [1 .. 10). In both cases, -the mantissa is shifted left or right (and the exponent adjusted -to compensate) in order to satisfy these constraints. - -Positive unpacking modes are treated differently than for @kbd{v p}. -A mode of 1 is much like plain @kbd{v u} with no prefix argument, -except that in addition to the components of the input object, -a suitable packing mode to re-pack the object is also pushed. -Thus, @kbd{C-u 1 v u} followed by @kbd{v p} will re-build the -original object. - -A mode of 2 unpacks two levels of the object; the resulting -re-packing mode will be a vector of length 2. This might be used -to unpack a matrix, say, or a vector of error forms. Higher -unpacking modes unpack the input even more deeply. - -@ignore -@starindex -@end ignore -@tindex unpack -There are two algebraic functions analogous to @kbd{v u}. -The @samp{unpack(@var{mode}, @var{item})} function unpacks the -@var{item} using the given @var{mode}, returning the result as -a vector of components. Here the @var{mode} must be an -integer, not a vector. For example, @samp{unpack(-4, a +/- b)} -returns @samp{[a, b]}, as does @samp{unpack(1, a +/- b)}. - -@ignore -@starindex -@end ignore -@tindex unpackt -The @code{unpackt} function is like @code{unpack} but instead -of returning a simple vector of items, it returns a vector of -two things: The mode, and the vector of items. For example, -@samp{unpackt(1, 2:3 +/- 1:4)} returns @samp{[-4, [2:3, 1:4]]}, -and @samp{unpackt(2, 2:3 +/- 1:4)} returns @samp{[[-4, -10], [2, 3, 1, 4]]}. -The identity for re-building the original object is -@samp{apply(pack, unpackt(@var{n}, @var{x})) = @var{x}}. (The -@code{apply} function builds a function call given the function -name and a vector of arguments.) - -@cindex Numerator of a fraction, extracting -Subscript notation is a useful way to extract a particular part -of an object. For example, to get the numerator of a rational -number, you can use @samp{unpack(-10, @var{x})_1}. - -@node Building Vectors, Extracting Elements, Packing and Unpacking, Matrix Functions -@section Building Vectors - -@noindent -Vectors and matrices can be added, -subtracted, multiplied, and divided; @pxref{Basic Arithmetic}. - -@kindex | -@pindex calc-concat -@ignore -@mindex @null -@end ignore -@tindex | -The @kbd{|} (@code{calc-concat}) [@code{vconcat}] command ``concatenates'' two vectors -into one. For example, after @kbd{@w{[ 1 , 2 ]} [ 3 , 4 ] |}, the stack -will contain the single vector @samp{[1, 2, 3, 4]}. If the arguments -are matrices, the rows of the first matrix are concatenated with the -rows of the second. (In other words, two matrices are just two vectors -of row-vectors as far as @kbd{|} is concerned.) - -If either argument to @kbd{|} is a scalar (a non-vector), it is treated -like a one-element vector for purposes of concatenation: @kbd{1 [ 2 , 3 ] |} -produces the vector @samp{[1, 2, 3]}. Likewise, if one argument is a -matrix and the other is a plain vector, the vector is treated as a -one-row matrix. - -@kindex H | -@tindex append -The @kbd{H |} (@code{calc-append}) [@code{append}] command concatenates -two vectors without any special cases. Both inputs must be vectors. -Whether or not they are matrices is not taken into account. If either -argument is a scalar, the @code{append} function is left in symbolic form. -See also @code{cons} and @code{rcons} below. - -@kindex I | -@kindex H I | -The @kbd{I |} and @kbd{H I |} commands are similar, but they use their -two stack arguments in the opposite order. Thus @kbd{I |} is equivalent -to @kbd{@key{TAB} |}, but possibly more convenient and also a bit faster. - -@kindex v d -@pindex calc-diag -@tindex diag -The @kbd{v d} (@code{calc-diag}) [@code{diag}] function builds a diagonal -square matrix. The optional numeric prefix gives the number of rows -and columns in the matrix. If the value at the top of the stack is a -vector, the elements of the vector are used as the diagonal elements; the -prefix, if specified, must match the size of the vector. If the value on -the stack is a scalar, it is used for each element on the diagonal, and -the prefix argument is required. - -To build a constant square matrix, e.g., a -@texline @math{3\times3} -@infoline 3x3 -matrix filled with ones, use @kbd{0 M-3 v d 1 +}, i.e., build a zero -matrix first and then add a constant value to that matrix. (Another -alternative would be to use @kbd{v b} and @kbd{v a}; see below.) - -@kindex v i -@pindex calc-ident -@tindex idn -The @kbd{v i} (@code{calc-ident}) [@code{idn}] function builds an identity -matrix of the specified size. It is a convenient form of @kbd{v d} -where the diagonal element is always one. If no prefix argument is given, -this command prompts for one. - -In algebraic notation, @samp{idn(a,n)} acts much like @samp{diag(a,n)}, -except that @expr{a} is required to be a scalar (non-vector) quantity. -If @expr{n} is omitted, @samp{idn(a)} represents @expr{a} times an -identity matrix of unknown size. Calc can operate algebraically on -such generic identity matrices, and if one is combined with a matrix -whose size is known, it is converted automatically to an identity -matrix of a suitable matching size. The @kbd{v i} command with an -argument of zero creates a generic identity matrix, @samp{idn(1)}. -Note that in dimensioned Matrix mode (@pxref{Matrix Mode}), generic -identity matrices are immediately expanded to the current default -dimensions. - -@kindex v x -@pindex calc-index -@tindex index -The @kbd{v x} (@code{calc-index}) [@code{index}] function builds a vector -of consecutive integers from 1 to @var{n}, where @var{n} is the numeric -prefix argument. If you do not provide a prefix argument, you will be -prompted to enter a suitable number. If @var{n} is negative, the result -is a vector of negative integers from @var{n} to @mathit{-1}. - -With a prefix argument of just @kbd{C-u}, the @kbd{v x} command takes -three values from the stack: @var{n}, @var{start}, and @var{incr} (with -@var{incr} at top-of-stack). Counting starts at @var{start} and increases -by @var{incr} for successive vector elements. If @var{start} or @var{n} -is in floating-point format, the resulting vector elements will also be -floats. Note that @var{start} and @var{incr} may in fact be any kind -of numbers or formulas. - -When @var{start} and @var{incr} are specified, a negative @var{n} has a -different interpretation: It causes a geometric instead of arithmetic -sequence to be generated. For example, @samp{index(-3, a, b)} produces -@samp{[a, a b, a b^2]}. If you omit @var{incr} in the algebraic form, -@samp{index(@var{n}, @var{start})}, the default value for @var{incr} -is one for positive @var{n} or two for negative @var{n}. - -@kindex v b -@pindex calc-build-vector -@tindex cvec -The @kbd{v b} (@code{calc-build-vector}) [@code{cvec}] function builds a -vector of @var{n} copies of the value on the top of the stack, where @var{n} -is the numeric prefix argument. In algebraic formulas, @samp{cvec(x,n,m)} -can also be used to build an @var{n}-by-@var{m} matrix of copies of @var{x}. -(Interactively, just use @kbd{v b} twice: once to build a row, then again -to build a matrix of copies of that row.) - -@kindex v h -@kindex I v h -@pindex calc-head -@pindex calc-tail -@tindex head -@tindex tail -The @kbd{v h} (@code{calc-head}) [@code{head}] function returns the first -element of a vector. The @kbd{I v h} (@code{calc-tail}) [@code{tail}] -function returns the vector with its first element removed. In both -cases, the argument must be a non-empty vector. - -@kindex v k -@pindex calc-cons -@tindex cons -The @kbd{v k} (@code{calc-cons}) [@code{cons}] function takes a value @var{h} -and a vector @var{t} from the stack, and produces the vector whose head is -@var{h} and whose tail is @var{t}. This is similar to @kbd{|}, except -if @var{h} is itself a vector, @kbd{|} will concatenate the two vectors -whereas @code{cons} will insert @var{h} at the front of the vector @var{t}. - -@kindex H v h -@tindex rhead -@ignore -@mindex @idots -@end ignore -@kindex H I v h -@ignore -@mindex @null -@end ignore -@kindex H v k -@ignore -@mindex @null -@end ignore -@tindex rtail -@ignore -@mindex @null -@end ignore -@tindex rcons -Each of these three functions also accepts the Hyperbolic flag [@code{rhead}, -@code{rtail}, @code{rcons}] in which case @var{t} instead represents -the @emph{last} single element of the vector, with @var{h} -representing the remainder of the vector. Thus the vector -@samp{[a, b, c, d] = cons(a, [b, c, d]) = rcons([a, b, c], d)}. -Also, @samp{head([a, b, c, d]) = a}, @samp{tail([a, b, c, d]) = [b, c, d]}, -@samp{rhead([a, b, c, d]) = [a, b, c]}, and @samp{rtail([a, b, c, d]) = d}. - -@node Extracting Elements, Manipulating Vectors, Building Vectors, Matrix Functions -@section Extracting Vector Elements - -@noindent -@kindex v r -@pindex calc-mrow -@tindex mrow -The @kbd{v r} (@code{calc-mrow}) [@code{mrow}] command extracts one row of -the matrix on the top of the stack, or one element of the plain vector on -the top of the stack. The row or element is specified by the numeric -prefix argument; the default is to prompt for the row or element number. -The matrix or vector is replaced by the specified row or element in the -form of a vector or scalar, respectively. - -@cindex Permutations, applying -With a prefix argument of @kbd{C-u} only, @kbd{v r} takes the index of -the element or row from the top of the stack, and the vector or matrix -from the second-to-top position. If the index is itself a vector of -integers, the result is a vector of the corresponding elements of the -input vector, or a matrix of the corresponding rows of the input matrix. -This command can be used to obtain any permutation of a vector. - -With @kbd{C-u}, if the index is an interval form with integer components, -it is interpreted as a range of indices and the corresponding subvector or -submatrix is returned. - -@cindex Subscript notation -@kindex a _ -@pindex calc-subscript -@tindex subscr -@tindex _ -Subscript notation in algebraic formulas (@samp{a_b}) stands for the -Calc function @code{subscr}, which is synonymous with @code{mrow}. -Thus, @samp{[x, y, z]_k} produces @expr{x}, @expr{y}, or @expr{z} if -@expr{k} is one, two, or three, respectively. A double subscript -(@samp{M_i_j}, equivalent to @samp{subscr(subscr(M, i), j)}) will -access the element at row @expr{i}, column @expr{j} of a matrix. -The @kbd{a _} (@code{calc-subscript}) command creates a subscript -formula @samp{a_b} out of two stack entries. (It is on the @kbd{a} -``algebra'' prefix because subscripted variables are often used -purely as an algebraic notation.) - -@tindex mrrow -Given a negative prefix argument, @kbd{v r} instead deletes one row or -element from the matrix or vector on the top of the stack. Thus -@kbd{C-u 2 v r} replaces a matrix with its second row, but @kbd{C-u -2 v r} -replaces the matrix with the same matrix with its second row removed. -In algebraic form this function is called @code{mrrow}. - -@tindex getdiag -Given a prefix argument of zero, @kbd{v r} extracts the diagonal elements -of a square matrix in the form of a vector. In algebraic form this -function is called @code{getdiag}. - -@kindex v c -@pindex calc-mcol -@tindex mcol -@tindex mrcol -The @kbd{v c} (@code{calc-mcol}) [@code{mcol} or @code{mrcol}] command is -the analogous operation on columns of a matrix. Given a plain vector -it extracts (or removes) one element, just like @kbd{v r}. If the -index in @kbd{C-u v c} is an interval or vector and the argument is a -matrix, the result is a submatrix with only the specified columns -retained (and possibly permuted in the case of a vector index). - -To extract a matrix element at a given row and column, use @kbd{v r} to -extract the row as a vector, then @kbd{v c} to extract the column element -from that vector. In algebraic formulas, it is often more convenient to -use subscript notation: @samp{m_i_j} gives row @expr{i}, column @expr{j} -of matrix @expr{m}. - -@kindex v s -@pindex calc-subvector -@tindex subvec -The @kbd{v s} (@code{calc-subvector}) [@code{subvec}] command extracts -a subvector of a vector. The arguments are the vector, the starting -index, and the ending index, with the ending index in the top-of-stack -position. The starting index indicates the first element of the vector -to take. The ending index indicates the first element @emph{past} the -range to be taken. Thus, @samp{subvec([a, b, c, d, e], 2, 4)} produces -the subvector @samp{[b, c]}. You could get the same result using -@samp{mrow([a, b, c, d, e], @w{[2 .. 4)})}. - -If either the start or the end index is zero or negative, it is -interpreted as relative to the end of the vector. Thus -@samp{subvec([a, b, c, d, e], 2, -2)} also produces @samp{[b, c]}. In -the algebraic form, the end index can be omitted in which case it -is taken as zero, i.e., elements from the starting element to the -end of the vector are used. The infinity symbol, @code{inf}, also -has this effect when used as the ending index. - -@kindex I v s -@tindex rsubvec -With the Inverse flag, @kbd{I v s} [@code{rsubvec}] removes a subvector -from a vector. The arguments are interpreted the same as for the -normal @kbd{v s} command. Thus, @samp{rsubvec([a, b, c, d, e], 2, 4)} -produces @samp{[a, d, e]}. It is always true that @code{subvec} and -@code{rsubvec} return complementary parts of the input vector. - -@xref{Selecting Subformulas}, for an alternative way to operate on -vectors one element at a time. - -@node Manipulating Vectors, Vector and Matrix Arithmetic, Extracting Elements, Matrix Functions -@section Manipulating Vectors - -@noindent -@kindex v l -@pindex calc-vlength -@tindex vlen -The @kbd{v l} (@code{calc-vlength}) [@code{vlen}] command computes the -length of a vector. The length of a non-vector is considered to be zero. -Note that matrices are just vectors of vectors for the purposes of this -command. - -@kindex H v l -@tindex mdims -With the Hyperbolic flag, @kbd{H v l} [@code{mdims}] computes a vector -of the dimensions of a vector, matrix, or higher-order object. For -example, @samp{mdims([[a,b,c],[d,e,f]])} returns @samp{[2, 3]} since -its argument is a -@texline @math{2\times3} -@infoline 2x3 -matrix. - -@kindex v f -@pindex calc-vector-find -@tindex find -The @kbd{v f} (@code{calc-vector-find}) [@code{find}] command searches -along a vector for the first element equal to a given target. The target -is on the top of the stack; the vector is in the second-to-top position. -If a match is found, the result is the index of the matching element. -Otherwise, the result is zero. The numeric prefix argument, if given, -allows you to select any starting index for the search. - -@kindex v a -@pindex calc-arrange-vector -@tindex arrange -@cindex Arranging a matrix -@cindex Reshaping a matrix -@cindex Flattening a matrix -The @kbd{v a} (@code{calc-arrange-vector}) [@code{arrange}] command -rearranges a vector to have a certain number of columns and rows. The -numeric prefix argument specifies the number of columns; if you do not -provide an argument, you will be prompted for the number of columns. -The vector or matrix on the top of the stack is @dfn{flattened} into a -plain vector. If the number of columns is nonzero, this vector is -then formed into a matrix by taking successive groups of @var{n} elements. -If the number of columns does not evenly divide the number of elements -in the vector, the last row will be short and the result will not be -suitable for use as a matrix. For example, with the matrix -@samp{[[1, 2], @w{[3, 4]}]} on the stack, @kbd{v a 4} produces -@samp{[[1, 2, 3, 4]]} (a -@texline @math{1\times4} -@infoline 1x4 -matrix), @kbd{v a 1} produces @samp{[[1], [2], [3], [4]]} (a -@texline @math{4\times1} -@infoline 4x1 -matrix), @kbd{v a 2} produces @samp{[[1, 2], [3, 4]]} (the original -@texline @math{2\times2} -@infoline 2x2 -matrix), @w{@kbd{v a 3}} produces @samp{[[1, 2, 3], [4]]} (not a -matrix), and @kbd{v a 0} produces the flattened list -@samp{[1, 2, @w{3, 4}]}. - -@cindex Sorting data -@kindex V S -@kindex I V S -@pindex calc-sort -@tindex sort -@tindex rsort -The @kbd{V S} (@code{calc-sort}) [@code{sort}] command sorts the elements of -a vector into increasing order. Real numbers, real infinities, and -constant interval forms come first in this ordering; next come other -kinds of numbers, then variables (in alphabetical order), then finally -come formulas and other kinds of objects; these are sorted according -to a kind of lexicographic ordering with the useful property that -one vector is less or greater than another if the first corresponding -unequal elements are less or greater, respectively. Since quoted strings -are stored by Calc internally as vectors of ASCII character codes -(@pxref{Strings}), this means vectors of strings are also sorted into -alphabetical order by this command. - -The @kbd{I V S} [@code{rsort}] command sorts a vector into decreasing order. - -@cindex Permutation, inverse of -@cindex Inverse of permutation -@cindex Index tables -@cindex Rank tables -@kindex V G -@kindex I V G -@pindex calc-grade -@tindex grade -@tindex rgrade -The @kbd{V G} (@code{calc-grade}) [@code{grade}, @code{rgrade}] command -produces an index table or permutation vector which, if applied to the -input vector (as the index of @kbd{C-u v r}, say), would sort the vector. -A permutation vector is just a vector of integers from 1 to @var{n}, where -each integer occurs exactly once. One application of this is to sort a -matrix of data rows using one column as the sort key; extract that column, -grade it with @kbd{V G}, then use the result to reorder the original matrix -with @kbd{C-u v r}. Another interesting property of the @code{V G} command -is that, if the input is itself a permutation vector, the result will -be the inverse of the permutation. The inverse of an index table is -a rank table, whose @var{k}th element says where the @var{k}th original -vector element will rest when the vector is sorted. To get a rank -table, just use @kbd{V G V G}. - -With the Inverse flag, @kbd{I V G} produces an index table that would -sort the input into decreasing order. Note that @kbd{V S} and @kbd{V G} -use a ``stable'' sorting algorithm, i.e., any two elements which are equal -will not be moved out of their original order. Generally there is no way -to tell with @kbd{V S}, since two elements which are equal look the same, -but with @kbd{V G} this can be an important issue. In the matrix-of-rows -example, suppose you have names and telephone numbers as two columns and -you wish to sort by phone number primarily, and by name when the numbers -are equal. You can sort the data matrix by names first, and then again -by phone numbers. Because the sort is stable, any two rows with equal -phone numbers will remain sorted by name even after the second sort. - -@cindex Histograms -@kindex V H -@pindex calc-histogram -@ignore -@mindex histo@idots -@end ignore -@tindex histogram -The @kbd{V H} (@code{calc-histogram}) [@code{histogram}] command builds a -histogram of a vector of numbers. Vector elements are assumed to be -integers or real numbers in the range [0..@var{n}) for some ``number of -bins'' @var{n}, which is the numeric prefix argument given to the -command. The result is a vector of @var{n} counts of how many times -each value appeared in the original vector. Non-integers in the input -are rounded down to integers. Any vector elements outside the specified -range are ignored. (You can tell if elements have been ignored by noting -that the counts in the result vector don't add up to the length of the -input vector.) - -@kindex H V H -With the Hyperbolic flag, @kbd{H V H} pulls two vectors from the stack. -The second-to-top vector is the list of numbers as before. The top -vector is an equal-sized list of ``weights'' to attach to the elements -of the data vector. For example, if the first data element is 4.2 and -the first weight is 10, then 10 will be added to bin 4 of the result -vector. Without the hyperbolic flag, every element has a weight of one. - -@kindex v t -@pindex calc-transpose -@tindex trn -The @kbd{v t} (@code{calc-transpose}) [@code{trn}] command computes -the transpose of the matrix at the top of the stack. If the argument -is a plain vector, it is treated as a row vector and transposed into -a one-column matrix. - -@kindex v v -@pindex calc-reverse-vector -@tindex rev -The @kbd{v v} (@code{calc-reverse-vector}) [@code{rev}] command reverses -a vector end-for-end. Given a matrix, it reverses the order of the rows. -(To reverse the columns instead, just use @kbd{v t v v v t}. The same -principle can be used to apply other vector commands to the columns of -a matrix.) - -@kindex v m -@pindex calc-mask-vector -@tindex vmask -The @kbd{v m} (@code{calc-mask-vector}) [@code{vmask}] command uses -one vector as a mask to extract elements of another vector. The mask -is in the second-to-top position; the target vector is on the top of -the stack. These vectors must have the same length. The result is -the same as the target vector, but with all elements which correspond -to zeros in the mask vector deleted. Thus, for example, -@samp{vmask([1, 0, 1, 0, 1], [a, b, c, d, e])} produces @samp{[a, c, e]}. -@xref{Logical Operations}. - -@kindex v e -@pindex calc-expand-vector -@tindex vexp -The @kbd{v e} (@code{calc-expand-vector}) [@code{vexp}] command -expands a vector according to another mask vector. The result is a -vector the same length as the mask, but with nonzero elements replaced -by successive elements from the target vector. The length of the target -vector is normally the number of nonzero elements in the mask. If the -target vector is longer, its last few elements are lost. If the target -vector is shorter, the last few nonzero mask elements are left -unreplaced in the result. Thus @samp{vexp([2, 0, 3, 0, 7], [a, b])} -produces @samp{[a, 0, b, 0, 7]}. - -@kindex H v e -With the Hyperbolic flag, @kbd{H v e} takes a filler value from the -top of the stack; the mask and target vectors come from the third and -second elements of the stack. This filler is used where the mask is -zero: @samp{vexp([2, 0, 3, 0, 7], [a, b], z)} produces -@samp{[a, z, c, z, 7]}. If the filler value is itself a vector, -then successive values are taken from it, so that the effect is to -interleave two vectors according to the mask: -@samp{vexp([2, 0, 3, 7, 0, 0], [a, b], [x, y])} produces -@samp{[a, x, b, 7, y, 0]}. - -Another variation on the masking idea is to combine @samp{[a, b, c, d, e]} -with the mask @samp{[1, 0, 1, 0, 1]} to produce @samp{[a, 0, c, 0, e]}. -You can accomplish this with @kbd{V M a &}, mapping the logical ``and'' -operation across the two vectors. @xref{Logical Operations}. Note that -the @code{? :} operation also discussed there allows other types of -masking using vectors. - -@node Vector and Matrix Arithmetic, Set Operations, Manipulating Vectors, Matrix Functions -@section Vector and Matrix Arithmetic - -@noindent -Basic arithmetic operations like addition and multiplication are defined -for vectors and matrices as well as for numbers. Division of matrices, in -the sense of multiplying by the inverse, is supported. (Division by a -matrix actually uses LU-decomposition for greater accuracy and speed.) -@xref{Basic Arithmetic}. - -The following functions are applied element-wise if their arguments are -vectors or matrices: @code{change-sign}, @code{conj}, @code{arg}, -@code{re}, @code{im}, @code{polar}, @code{rect}, @code{clean}, -@code{float}, @code{frac}. @xref{Function Index}. - -@kindex V J -@pindex calc-conj-transpose -@tindex ctrn -The @kbd{V J} (@code{calc-conj-transpose}) [@code{ctrn}] command computes -the conjugate transpose of its argument, i.e., @samp{conj(trn(x))}. - -@ignore -@mindex A -@end ignore -@kindex A (vectors) -@pindex calc-abs (vectors) -@ignore -@mindex abs -@end ignore -@tindex abs (vectors) -The @kbd{A} (@code{calc-abs}) [@code{abs}] command computes the -Frobenius norm of a vector or matrix argument. This is the square -root of the sum of the squares of the absolute values of the -elements of the vector or matrix. If the vector is interpreted as -a point in two- or three-dimensional space, this is the distance -from that point to the origin. - -@kindex v n -@pindex calc-rnorm -@tindex rnorm -The @kbd{v n} (@code{calc-rnorm}) [@code{rnorm}] command computes the -infinity-norm of a vector, or the row norm of a matrix. For a plain -vector, this is the maximum of the absolute values of the elements. For -a matrix, this is the maximum of the row-absolute-value-sums, i.e., of -the sums of the absolute values of the elements along the various rows. - -@kindex V N -@pindex calc-cnorm -@tindex cnorm -The @kbd{V N} (@code{calc-cnorm}) [@code{cnorm}] command computes -the one-norm of a vector, or column norm of a matrix. For a plain -vector, this is the sum of the absolute values of the elements. -For a matrix, this is the maximum of the column-absolute-value-sums. -General @expr{k}-norms for @expr{k} other than one or infinity are -not provided. However, the 2-norm (or Frobenius norm) is provided for -vectors by the @kbd{A} (@code{calc-abs}) command. - -@kindex V C -@pindex calc-cross -@tindex cross -The @kbd{V C} (@code{calc-cross}) [@code{cross}] command computes the -right-handed cross product of two vectors, each of which must have -exactly three elements. - -@ignore -@mindex & -@end ignore -@kindex & (matrices) -@pindex calc-inv (matrices) -@ignore -@mindex inv -@end ignore -@tindex inv (matrices) -The @kbd{&} (@code{calc-inv}) [@code{inv}] command computes the -inverse of a square matrix. If the matrix is singular, the inverse -operation is left in symbolic form. Matrix inverses are recorded so -that once an inverse (or determinant) of a particular matrix has been -computed, the inverse and determinant of the matrix can be recomputed -quickly in the future. - -If the argument to @kbd{&} is a plain number @expr{x}, this -command simply computes @expr{1/x}. This is okay, because the -@samp{/} operator also does a matrix inversion when dividing one -by a matrix. - -@kindex V D -@pindex calc-mdet -@tindex det -The @kbd{V D} (@code{calc-mdet}) [@code{det}] command computes the -determinant of a square matrix. - -@kindex V L -@pindex calc-mlud -@tindex lud -The @kbd{V L} (@code{calc-mlud}) [@code{lud}] command computes the -LU decomposition of a matrix. The result is a list of three matrices -which, when multiplied together left-to-right, form the original matrix. -The first is a permutation matrix that arises from pivoting in the -algorithm, the second is lower-triangular with ones on the diagonal, -and the third is upper-triangular. - -@kindex V T -@pindex calc-mtrace -@tindex tr -The @kbd{V T} (@code{calc-mtrace}) [@code{tr}] command computes the -trace of a square matrix. This is defined as the sum of the diagonal -elements of the matrix. - -@kindex V K -@pindex calc-kron -@tindex kron -The @kbd{V K} (@code{calc-kron}) [@code{kron}] command computes -the Kronecker product of two matrices. - -@node Set Operations, Statistical Operations, Vector and Matrix Arithmetic, Matrix Functions -@section Set Operations using Vectors - -@noindent -@cindex Sets, as vectors -Calc includes several commands which interpret vectors as @dfn{sets} of -objects. A set is a collection of objects; any given object can appear -only once in the set. Calc stores sets as vectors of objects in -sorted order. Objects in a Calc set can be any of the usual things, -such as numbers, variables, or formulas. Two set elements are considered -equal if they are identical, except that numerically equal numbers like -the integer 4 and the float 4.0 are considered equal even though they -are not ``identical.'' Variables are treated like plain symbols without -attached values by the set operations; subtracting the set @samp{[b]} -from @samp{[a, b]} always yields the set @samp{[a]} even though if -the variables @samp{a} and @samp{b} both equaled 17, you might -expect the answer @samp{[]}. - -If a set contains interval forms, then it is assumed to be a set of -real numbers. In this case, all set operations require the elements -of the set to be only things that are allowed in intervals: Real -numbers, plus and minus infinity, HMS forms, and date forms. If -there are variables or other non-real objects present in a real set, -all set operations on it will be left in unevaluated form. - -If the input to a set operation is a plain number or interval form -@var{a}, it is treated like the one-element vector @samp{[@var{a}]}. -The result is always a vector, except that if the set consists of a -single interval, the interval itself is returned instead. - -@xref{Logical Operations}, for the @code{in} function which tests if -a certain value is a member of a given set. To test if the set @expr{A} -is a subset of the set @expr{B}, use @samp{vdiff(A, B) = []}. - -@kindex V + -@pindex calc-remove-duplicates -@tindex rdup -The @kbd{V +} (@code{calc-remove-duplicates}) [@code{rdup}] command -converts an arbitrary vector into set notation. It works by sorting -the vector as if by @kbd{V S}, then removing duplicates. (For example, -@kbd{[a, 5, 4, a, 4.0]} is sorted to @samp{[4, 4.0, 5, a, a]} and then -reduced to @samp{[4, 5, a]}). Overlapping intervals are merged as -necessary. You rarely need to use @kbd{V +} explicitly, since all the -other set-based commands apply @kbd{V +} to their inputs before using -them. - -@kindex V V -@pindex calc-set-union -@tindex vunion -The @kbd{V V} (@code{calc-set-union}) [@code{vunion}] command computes -the union of two sets. An object is in the union of two sets if and -only if it is in either (or both) of the input sets. (You could -accomplish the same thing by concatenating the sets with @kbd{|}, -then using @kbd{V +}.) - -@kindex V ^ -@pindex calc-set-intersect -@tindex vint -The @kbd{V ^} (@code{calc-set-intersect}) [@code{vint}] command computes -the intersection of two sets. An object is in the intersection if -and only if it is in both of the input sets. Thus if the input -sets are disjoint, i.e., if they share no common elements, the result -will be the empty vector @samp{[]}. Note that the characters @kbd{V} -and @kbd{^} were chosen to be close to the conventional mathematical -notation for set -@texline union@tie{}(@math{A \cup B}) -@infoline union -and -@texline intersection@tie{}(@math{A \cap B}). -@infoline intersection. - -@kindex V - -@pindex calc-set-difference -@tindex vdiff -The @kbd{V -} (@code{calc-set-difference}) [@code{vdiff}] command computes -the difference between two sets. An object is in the difference -@expr{A - B} if and only if it is in @expr{A} but not in @expr{B}. -Thus subtracting @samp{[y,z]} from a set will remove the elements -@samp{y} and @samp{z} if they are present. You can also think of this -as a general @dfn{set complement} operator; if @expr{A} is the set of -all possible values, then @expr{A - B} is the ``complement'' of @expr{B}. -Obviously this is only practical if the set of all possible values in -your problem is small enough to list in a Calc vector (or simple -enough to express in a few intervals). - -@kindex V X -@pindex calc-set-xor -@tindex vxor -The @kbd{V X} (@code{calc-set-xor}) [@code{vxor}] command computes -the ``exclusive-or,'' or ``symmetric difference'' of two sets. -An object is in the symmetric difference of two sets if and only -if it is in one, but @emph{not} both, of the sets. Objects that -occur in both sets ``cancel out.'' - -@kindex V ~ -@pindex calc-set-complement -@tindex vcompl -The @kbd{V ~} (@code{calc-set-complement}) [@code{vcompl}] command -computes the complement of a set with respect to the real numbers. -Thus @samp{vcompl(x)} is equivalent to @samp{vdiff([-inf .. inf], x)}. -For example, @samp{vcompl([2, (3 .. 4]])} evaluates to -@samp{[[-inf .. 2), (2 .. 3], (4 .. inf]]}. - -@kindex V F -@pindex calc-set-floor -@tindex vfloor -The @kbd{V F} (@code{calc-set-floor}) [@code{vfloor}] command -reinterprets a set as a set of integers. Any non-integer values, -and intervals that do not enclose any integers, are removed. Open -intervals are converted to equivalent closed intervals. Successive -integers are converted into intervals of integers. For example, the -complement of the set @samp{[2, 6, 7, 8]} is messy, but if you wanted -the complement with respect to the set of integers you could type -@kbd{V ~ V F} to get @samp{[[-inf .. 1], [3 .. 5], [9 .. inf]]}. - -@kindex V E -@pindex calc-set-enumerate -@tindex venum -The @kbd{V E} (@code{calc-set-enumerate}) [@code{venum}] command -converts a set of integers into an explicit vector. Intervals in -the set are expanded out to lists of all integers encompassed by -the intervals. This only works for finite sets (i.e., sets which -do not involve @samp{-inf} or @samp{inf}). - -@kindex V : -@pindex calc-set-span -@tindex vspan -The @kbd{V :} (@code{calc-set-span}) [@code{vspan}] command converts any -set of reals into an interval form that encompasses all its elements. -The lower limit will be the smallest element in the set; the upper -limit will be the largest element. For an empty set, @samp{vspan([])} -returns the empty interval @w{@samp{[0 .. 0)}}. - -@kindex V # -@pindex calc-set-cardinality -@tindex vcard -The @kbd{V #} (@code{calc-set-cardinality}) [@code{vcard}] command counts -the number of integers in a set. The result is the length of the vector -that would be produced by @kbd{V E}, although the computation is much -more efficient than actually producing that vector. - -@cindex Sets, as binary numbers -Another representation for sets that may be more appropriate in some -cases is binary numbers. If you are dealing with sets of integers -in the range 0 to 49, you can use a 50-bit binary number where a -particular bit is 1 if the corresponding element is in the set. -@xref{Binary Functions}, for a list of commands that operate on -binary numbers. Note that many of the above set operations have -direct equivalents in binary arithmetic: @kbd{b o} (@code{calc-or}), -@kbd{b a} (@code{calc-and}), @kbd{b d} (@code{calc-diff}), -@kbd{b x} (@code{calc-xor}), and @kbd{b n} (@code{calc-not}), -respectively. You can use whatever representation for sets is most -convenient to you. - -@kindex b p -@kindex b u -@pindex calc-pack-bits -@pindex calc-unpack-bits -@tindex vpack -@tindex vunpack -The @kbd{b u} (@code{calc-unpack-bits}) [@code{vunpack}] command -converts an integer that represents a set in binary into a set -in vector/interval notation. For example, @samp{vunpack(67)} -returns @samp{[[0 .. 1], 6]}. If the input is negative, the set -it represents is semi-infinite: @samp{vunpack(-4) = [2 .. inf)}. -Use @kbd{V E} afterwards to expand intervals to individual -values if you wish. Note that this command uses the @kbd{b} -(binary) prefix key. - -The @kbd{b p} (@code{calc-pack-bits}) [@code{vpack}] command -converts the other way, from a vector or interval representing -a set of nonnegative integers into a binary integer describing -the same set. The set may include positive infinity, but must -not include any negative numbers. The input is interpreted as a -set of integers in the sense of @kbd{V F} (@code{vfloor}). Beware -that a simple input like @samp{[100]} can result in a huge integer -representation -@texline (@math{2^{100}}, a 31-digit integer, in this case). -@infoline (@expr{2^100}, a 31-digit integer, in this case). - -@node Statistical Operations, Reducing and Mapping, Set Operations, Matrix Functions -@section Statistical Operations on Vectors - -@noindent -@cindex Statistical functions -The commands in this section take vectors as arguments and compute -various statistical measures on the data stored in the vectors. The -references used in the definitions of these functions are Bevington's -@emph{Data Reduction and Error Analysis for the Physical Sciences}, -and @emph{Numerical Recipes} by Press, Flannery, Teukolsky and -Vetterling. - -The statistical commands use the @kbd{u} prefix key followed by -a shifted letter or other character. - -@xref{Manipulating Vectors}, for a description of @kbd{V H} -(@code{calc-histogram}). - -@xref{Curve Fitting}, for the @kbd{a F} command for doing -least-squares fits to statistical data. - -@xref{Probability Distribution Functions}, for several common -probability distribution functions. - -@menu -* Single-Variable Statistics:: -* Paired-Sample Statistics:: -@end menu - -@node Single-Variable Statistics, Paired-Sample Statistics, Statistical Operations, Statistical Operations -@subsection Single-Variable Statistics - -@noindent -These functions do various statistical computations on single -vectors. Given a numeric prefix argument, they actually pop -@var{n} objects from the stack and combine them into a data -vector. Each object may be either a number or a vector; if a -vector, any sub-vectors inside it are ``flattened'' as if by -@kbd{v a 0}; @pxref{Manipulating Vectors}. By default one object -is popped, which (in order to be useful) is usually a vector. - -If an argument is a variable name, and the value stored in that -variable is a vector, then the stored vector is used. This method -has the advantage that if your data vector is large, you can avoid -the slow process of manipulating it directly on the stack. - -These functions are left in symbolic form if any of their arguments -are not numbers or vectors, e.g., if an argument is a formula, or -a non-vector variable. However, formulas embedded within vector -arguments are accepted; the result is a symbolic representation -of the computation, based on the assumption that the formula does -not itself represent a vector. All varieties of numbers such as -error forms and interval forms are acceptable. - -Some of the functions in this section also accept a single error form -or interval as an argument. They then describe a property of the -normal or uniform (respectively) statistical distribution described -by the argument. The arguments are interpreted in the same way as -the @var{M} argument of the random number function @kbd{k r}. In -particular, an interval with integer limits is considered an integer -distribution, so that @samp{[2 .. 6)} is the same as @samp{[2 .. 5]}. -An interval with at least one floating-point limit is a continuous -distribution: @samp{[2.0 .. 6.0)} is @emph{not} the same as -@samp{[2.0 .. 5.0]}! - -@kindex u # -@pindex calc-vector-count -@tindex vcount -The @kbd{u #} (@code{calc-vector-count}) [@code{vcount}] command -computes the number of data values represented by the inputs. -For example, @samp{vcount(1, [2, 3], [[4, 5], [], x, y])} returns 7. -If the argument is a single vector with no sub-vectors, this -simply computes the length of the vector. - -@kindex u + -@kindex u * -@pindex calc-vector-sum -@pindex calc-vector-prod -@tindex vsum -@tindex vprod -@cindex Summations (statistical) -The @kbd{u +} (@code{calc-vector-sum}) [@code{vsum}] command -computes the sum of the data values. The @kbd{u *} -(@code{calc-vector-prod}) [@code{vprod}] command computes the -product of the data values. If the input is a single flat vector, -these are the same as @kbd{V R +} and @kbd{V R *} -(@pxref{Reducing and Mapping}). - -@kindex u X -@kindex u N -@pindex calc-vector-max -@pindex calc-vector-min -@tindex vmax -@tindex vmin -The @kbd{u X} (@code{calc-vector-max}) [@code{vmax}] command -computes the maximum of the data values, and the @kbd{u N} -(@code{calc-vector-min}) [@code{vmin}] command computes the minimum. -If the argument is an interval, this finds the minimum or maximum -value in the interval. (Note that @samp{vmax([2..6)) = 5} as -described above.) If the argument is an error form, this returns -plus or minus infinity. - -@kindex u M -@pindex calc-vector-mean -@tindex vmean -@cindex Mean of data values -The @kbd{u M} (@code{calc-vector-mean}) [@code{vmean}] command -computes the average (arithmetic mean) of the data values. -If the inputs are error forms -@texline @math{x \pm \sigma}, -@infoline @samp{x +/- s}, -this is the weighted mean of the @expr{x} values with weights -@texline @math{1 /\sigma^2}. -@infoline @expr{1 / s^2}. -@tex -\turnoffactive -$$ \mu = { \displaystyle \sum { x_i \over \sigma_i^2 } \over - \displaystyle \sum { 1 \over \sigma_i^2 } } $$ -@end tex -If the inputs are not error forms, this is simply the sum of the -values divided by the count of the values. - -Note that a plain number can be considered an error form with -error -@texline @math{\sigma = 0}. -@infoline @expr{s = 0}. -If the input to @kbd{u M} is a mixture of -plain numbers and error forms, the result is the mean of the -plain numbers, ignoring all values with non-zero errors. (By the -above definitions it's clear that a plain number effectively -has an infinite weight, next to which an error form with a finite -weight is completely negligible.) - -This function also works for distributions (error forms or -intervals). The mean of an error form `@var{a} @tfn{+/-} @var{b}' is simply -@expr{a}. The mean of an interval is the mean of the minimum -and maximum values of the interval. - -@kindex I u M -@pindex calc-vector-mean-error -@tindex vmeane -The @kbd{I u M} (@code{calc-vector-mean-error}) [@code{vmeane}] -command computes the mean of the data points expressed as an -error form. This includes the estimated error associated with -the mean. If the inputs are error forms, the error is the square -root of the reciprocal of the sum of the reciprocals of the squares -of the input errors. (I.e., the variance is the reciprocal of the -sum of the reciprocals of the variances.) -@tex -\turnoffactive -$$ \sigma_\mu^2 = {1 \over \displaystyle \sum {1 \over \sigma_i^2}} $$ -@end tex -If the inputs are plain -numbers, the error is equal to the standard deviation of the values -divided by the square root of the number of values. (This works -out to be equivalent to calculating the standard deviation and -then assuming each value's error is equal to this standard -deviation.) -@tex -\turnoffactive -$$ \sigma_\mu^2 = {\sigma^2 \over N} $$ -@end tex - -@kindex H u M -@pindex calc-vector-median -@tindex vmedian -@cindex Median of data values -The @kbd{H u M} (@code{calc-vector-median}) [@code{vmedian}] -command computes the median of the data values. The values are -first sorted into numerical order; the median is the middle -value after sorting. (If the number of data values is even, -the median is taken to be the average of the two middle values.) -The median function is different from the other functions in -this section in that the arguments must all be real numbers; -variables are not accepted even when nested inside vectors. -(Otherwise it is not possible to sort the data values.) If -any of the input values are error forms, their error parts are -ignored. - -The median function also accepts distributions. For both normal -(error form) and uniform (interval) distributions, the median is -the same as the mean. - -@kindex H I u M -@pindex calc-vector-harmonic-mean -@tindex vhmean -@cindex Harmonic mean -The @kbd{H I u M} (@code{calc-vector-harmonic-mean}) [@code{vhmean}] -command computes the harmonic mean of the data values. This is -defined as the reciprocal of the arithmetic mean of the reciprocals -of the values. -@tex -\turnoffactive -$$ { N \over \displaystyle \sum {1 \over x_i} } $$ -@end tex - -@kindex u G -@pindex calc-vector-geometric-mean -@tindex vgmean -@cindex Geometric mean -The @kbd{u G} (@code{calc-vector-geometric-mean}) [@code{vgmean}] -command computes the geometric mean of the data values. This -is the @var{n}th root of the product of the values. This is also -equal to the @code{exp} of the arithmetic mean of the logarithms -of the data values. -@tex -\turnoffactive -$$ \exp \left ( \sum { \ln x_i } \right ) = - \left ( \prod { x_i } \right)^{1 / N} $$ -@end tex - -@kindex H u G -@tindex agmean -The @kbd{H u G} [@code{agmean}] command computes the ``arithmetic-geometric -mean'' of two numbers taken from the stack. This is computed by -replacing the two numbers with their arithmetic mean and geometric -mean, then repeating until the two values converge. -@tex -\turnoffactive -$$ a_{i+1} = { a_i + b_i \over 2 } , \qquad b_{i+1} = \sqrt{a_i b_i} $$ -@end tex - -@cindex Root-mean-square -Another commonly used mean, the RMS (root-mean-square), can be computed -for a vector of numbers simply by using the @kbd{A} command. - -@kindex u S -@pindex calc-vector-sdev -@tindex vsdev -@cindex Standard deviation -@cindex Sample statistics -The @kbd{u S} (@code{calc-vector-sdev}) [@code{vsdev}] command -computes the standard -@texline deviation@tie{}@math{\sigma} -@infoline deviation -of the data values. If the values are error forms, the errors are used -as weights just as for @kbd{u M}. This is the @emph{sample} standard -deviation, whose value is the square root of the sum of the squares of -the differences between the values and the mean of the @expr{N} values, -divided by @expr{N-1}. -@tex -\turnoffactive -$$ \sigma^2 = {1 \over N - 1} \sum (x_i - \mu)^2 $$ -@end tex - -This function also applies to distributions. The standard deviation -of a single error form is simply the error part. The standard deviation -of a continuous interval happens to equal the difference between the -limits, divided by -@texline @math{\sqrt{12}}. -@infoline @expr{sqrt(12)}. -The standard deviation of an integer interval is the same as the -standard deviation of a vector of those integers. - -@kindex I u S -@pindex calc-vector-pop-sdev -@tindex vpsdev -@cindex Population statistics -The @kbd{I u S} (@code{calc-vector-pop-sdev}) [@code{vpsdev}] -command computes the @emph{population} standard deviation. -It is defined by the same formula as above but dividing -by @expr{N} instead of by @expr{N-1}. The population standard -deviation is used when the input represents the entire set of -data values in the distribution; the sample standard deviation -is used when the input represents a sample of the set of all -data values, so that the mean computed from the input is itself -only an estimate of the true mean. -@tex -\turnoffactive -$$ \sigma^2 = {1 \over N} \sum (x_i - \mu)^2 $$ -@end tex - -For error forms and continuous intervals, @code{vpsdev} works -exactly like @code{vsdev}. For integer intervals, it computes the -population standard deviation of the equivalent vector of integers. - -@kindex H u S -@kindex H I u S -@pindex calc-vector-variance -@pindex calc-vector-pop-variance -@tindex vvar -@tindex vpvar -@cindex Variance of data values -The @kbd{H u S} (@code{calc-vector-variance}) [@code{vvar}] and -@kbd{H I u S} (@code{calc-vector-pop-variance}) [@code{vpvar}] -commands compute the variance of the data values. The variance -is the -@texline square@tie{}@math{\sigma^2} -@infoline square -of the standard deviation, i.e., the sum of the -squares of the deviations of the data values from the mean. -(This definition also applies when the argument is a distribution.) - -@ignore -@starindex -@end ignore -@tindex vflat -The @code{vflat} algebraic function returns a vector of its -arguments, interpreted in the same way as the other functions -in this section. For example, @samp{vflat(1, [2, [3, 4]], 5)} -returns @samp{[1, 2, 3, 4, 5]}. - -@node Paired-Sample Statistics, , Single-Variable Statistics, Statistical Operations -@subsection Paired-Sample Statistics - -@noindent -The functions in this section take two arguments, which must be -vectors of equal size. The vectors are each flattened in the same -way as by the single-variable statistical functions. Given a numeric -prefix argument of 1, these functions instead take one object from -the stack, which must be an -@texline @math{N\times2} -@infoline Nx2 -matrix of data values. Once again, variable names can be used in place -of actual vectors and matrices. - -@kindex u C -@pindex calc-vector-covariance -@tindex vcov -@cindex Covariance -The @kbd{u C} (@code{calc-vector-covariance}) [@code{vcov}] command -computes the sample covariance of two vectors. The covariance -of vectors @var{x} and @var{y} is the sum of the products of the -differences between the elements of @var{x} and the mean of @var{x} -times the differences between the corresponding elements of @var{y} -and the mean of @var{y}, all divided by @expr{N-1}. Note that -the variance of a vector is just the covariance of the vector -with itself. Once again, if the inputs are error forms the -errors are used as weight factors. If both @var{x} and @var{y} -are composed of error forms, the error for a given data point -is taken as the square root of the sum of the squares of the two -input errors. -@tex -\turnoffactive -$$ \sigma_{x\!y}^2 = {1 \over N-1} \sum (x_i - \mu_x) (y_i - \mu_y) $$ -$$ \sigma_{x\!y}^2 = - {\displaystyle {1 \over N-1} - \sum {(x_i - \mu_x) (y_i - \mu_y) \over \sigma_i^2} - \over \displaystyle {1 \over N} \sum {1 \over \sigma_i^2}} -$$ -@end tex - -@kindex I u C -@pindex calc-vector-pop-covariance -@tindex vpcov -The @kbd{I u C} (@code{calc-vector-pop-covariance}) [@code{vpcov}] -command computes the population covariance, which is the same as the -sample covariance computed by @kbd{u C} except dividing by @expr{N} -instead of @expr{N-1}. - -@kindex H u C -@pindex calc-vector-correlation -@tindex vcorr -@cindex Correlation coefficient -@cindex Linear correlation -The @kbd{H u C} (@code{calc-vector-correlation}) [@code{vcorr}] -command computes the linear correlation coefficient of two vectors. -This is defined by the covariance of the vectors divided by the -product of their standard deviations. (There is no difference -between sample or population statistics here.) -@tex -\turnoffactive -$$ r_{x\!y} = { \sigma_{x\!y}^2 \over \sigma_x^2 \sigma_y^2 } $$ -@end tex - -@node Reducing and Mapping, Vector and Matrix Formats, Statistical Operations, Matrix Functions -@section Reducing and Mapping Vectors - -@noindent -The commands in this section allow for more general operations on the -elements of vectors. - -@kindex V A -@pindex calc-apply -@tindex apply -The simplest of these operations is @kbd{V A} (@code{calc-apply}) -[@code{apply}], which applies a given operator to the elements of a vector. -For example, applying the hypothetical function @code{f} to the vector -@w{@samp{[1, 2, 3]}} would produce the function call @samp{f(1, 2, 3)}. -Applying the @code{+} function to the vector @samp{[a, b]} gives -@samp{a + b}. Applying @code{+} to the vector @samp{[a, b, c]} is an -error, since the @code{+} function expects exactly two arguments. - -While @kbd{V A} is useful in some cases, you will usually find that either -@kbd{V R} or @kbd{V M}, described below, is closer to what you want. - -@menu -* Specifying Operators:: -* Mapping:: -* Reducing:: -* Nesting and Fixed Points:: -* Generalized Products:: -@end menu - -@node Specifying Operators, Mapping, Reducing and Mapping, Reducing and Mapping -@subsection Specifying Operators - -@noindent -Commands in this section (like @kbd{V A}) prompt you to press the key -corresponding to the desired operator. Press @kbd{?} for a partial -list of the available operators. Generally, an operator is any key or -sequence of keys that would normally take one or more arguments from -the stack and replace them with a result. For example, @kbd{V A H C} -uses the hyperbolic cosine operator, @code{cosh}. (Since @code{cosh} -expects one argument, @kbd{V A H C} requires a vector with a single -element as its argument.) - -You can press @kbd{x} at the operator prompt to select any algebraic -function by name to use as the operator. This includes functions you -have defined yourself using the @kbd{Z F} command. (@xref{Algebraic -Definitions}.) If you give a name for which no function has been -defined, the result is left in symbolic form, as in @samp{f(1, 2, 3)}. -Calc will prompt for the number of arguments the function takes if it -can't figure it out on its own (say, because you named a function that -is currently undefined). It is also possible to type a digit key before -the function name to specify the number of arguments, e.g., -@kbd{V M 3 x f @key{RET}} calls @code{f} with three arguments even if it -looks like it ought to have only two. This technique may be necessary -if the function allows a variable number of arguments. For example, -the @kbd{v e} [@code{vexp}] function accepts two or three arguments; -if you want to map with the three-argument version, you will have to -type @kbd{V M 3 v e}. - -It is also possible to apply any formula to a vector by treating that -formula as a function. When prompted for the operator to use, press -@kbd{'} (the apostrophe) and type your formula as an algebraic entry. -You will then be prompted for the argument list, which defaults to a -list of all variables that appear in the formula, sorted into alphabetic -order. For example, suppose you enter the formula @w{@samp{x + 2y^x}}. -The default argument list would be @samp{(x y)}, which means that if -this function is applied to the arguments @samp{[3, 10]} the result will -be @samp{3 + 2*10^3}. (If you plan to use a certain formula in this -way often, you might consider defining it as a function with @kbd{Z F}.) - -Another way to specify the arguments to the formula you enter is with -@kbd{$}, @kbd{$$}, and so on. For example, @kbd{V A ' $$ + 2$^$$} -has the same effect as the previous example. The argument list is -automatically taken to be @samp{($$ $)}. (The order of the arguments -may seem backwards, but it is analogous to the way normal algebraic -entry interacts with the stack.) - -If you press @kbd{$} at the operator prompt, the effect is similar to -the apostrophe except that the relevant formula is taken from top-of-stack -instead. The actual vector arguments of the @kbd{V A $} or related command -then start at the second-to-top stack position. You will still be -prompted for an argument list. - -@cindex Nameless functions -@cindex Generic functions -A function can be written without a name using the notation @samp{<#1 - #2>}, -which means ``a function of two arguments that computes the first -argument minus the second argument.'' The symbols @samp{#1} and @samp{#2} -are placeholders for the arguments. You can use any names for these -placeholders if you wish, by including an argument list followed by a -colon: @samp{}. When you type @kbd{V A ' $$ + 2$^$$ @key{RET}}, -Calc builds the nameless function @samp{<#1 + 2 #2^#1>} as the function -to map across the vectors. When you type @kbd{V A ' x + 2y^x @key{RET} @key{RET}}, -Calc builds the nameless function @w{@samp{}}. In both -cases, Calc also writes the nameless function to the Trail so that you -can get it back later if you wish. - -If there is only one argument, you can write @samp{#} in place of @samp{#1}. -(Note that @samp{< >} notation is also used for date forms. Calc tells -that @samp{<@var{stuff}>} is a nameless function by the presence of -@samp{#} signs inside @var{stuff}, or by the fact that @var{stuff} -begins with a list of variables followed by a colon.) - -You can type a nameless function directly to @kbd{V A '}, or put one on -the stack and use it with @w{@kbd{V A $}}. Calc will not prompt for an -argument list in this case, since the nameless function specifies the -argument list as well as the function itself. In @kbd{V A '}, you can -omit the @samp{< >} marks if you use @samp{#} notation for the arguments, -so that @kbd{V A ' #1+#2 @key{RET}} is the same as @kbd{V A ' <#1+#2> @key{RET}}, -which in turn is the same as @kbd{V A ' $$+$ @key{RET}}. - -@cindex Lambda expressions -@ignore -@starindex -@end ignore -@tindex lambda -The internal format for @samp{} is @samp{lambda(x, y, x + y)}. -(The word @code{lambda} derives from Lisp notation and the theory of -functions.) The internal format for @samp{<#1 + #2>} is @samp{lambda(ArgA, -ArgB, ArgA + ArgB)}. Note that there is no actual Calc function called -@code{lambda}; the whole point is that the @code{lambda} expression is -used in its symbolic form, not evaluated for an answer until it is applied -to specific arguments by a command like @kbd{V A} or @kbd{V M}. - -(Actually, @code{lambda} does have one special property: Its arguments -are never evaluated; for example, putting @samp{<(2/3) #>} on the stack -will not simplify the @samp{2/3} until the nameless function is actually -called.) - -@tindex add -@tindex sub -@ignore -@mindex @idots -@end ignore -@tindex mul -@ignore -@mindex @null -@end ignore -@tindex div -@ignore -@mindex @null -@end ignore -@tindex pow -@ignore -@mindex @null -@end ignore -@tindex neg -@ignore -@mindex @null -@end ignore -@tindex mod -@ignore -@mindex @null -@end ignore -@tindex vconcat -As usual, commands like @kbd{V A} have algebraic function name equivalents. -For example, @kbd{V A k g} with an argument of @samp{v} is equivalent to -@samp{apply(gcd, v)}. The first argument specifies the operator name, -and is either a variable whose name is the same as the function name, -or a nameless function like @samp{<#^3+1>}. Operators that are normally -written as algebraic symbols have the names @code{add}, @code{sub}, -@code{mul}, @code{div}, @code{pow}, @code{neg}, @code{mod}, and -@code{vconcat}. - -@ignore -@starindex -@end ignore -@tindex call -The @code{call} function builds a function call out of several arguments: -@samp{call(gcd, x, y)} is the same as @samp{apply(gcd, [x, y])}, which -in turn is the same as @samp{gcd(x, y)}. The first argument of @code{call}, -like the other functions described here, may be either a variable naming a -function, or a nameless function (@samp{call(<#1+2#2>, x, y)} is the same -as @samp{x + 2y}). - -(Experts will notice that it's not quite proper to use a variable to name -a function, since the name @code{gcd} corresponds to the Lisp variable -@code{var-gcd} but to the Lisp function @code{calcFunc-gcd}. Calc -automatically makes this translation, so you don't have to worry -about it.) - -@node Mapping, Reducing, Specifying Operators, Reducing and Mapping -@subsection Mapping - -@noindent -@kindex V M -@pindex calc-map -@tindex map -The @kbd{V M} (@code{calc-map}) [@code{map}] command applies a given -operator elementwise to one or more vectors. For example, mapping -@code{A} [@code{abs}] produces a vector of the absolute values of the -elements in the input vector. Mapping @code{+} pops two vectors from -the stack, which must be of equal length, and produces a vector of the -pairwise sums of the elements. If either argument is a non-vector, it -is duplicated for each element of the other vector. For example, -@kbd{[1,2,3] 2 V M ^} squares the elements of the specified vector. -With the 2 listed first, it would have computed a vector of powers of -two. Mapping a user-defined function pops as many arguments from the -stack as the function requires. If you give an undefined name, you will -be prompted for the number of arguments to use. - -If any argument to @kbd{V M} is a matrix, the operator is normally mapped -across all elements of the matrix. For example, given the matrix -@expr{[[1, -2, 3], [-4, 5, -6]]}, @kbd{V M A} takes six absolute values to -produce another -@texline @math{3\times2} -@infoline 3x2 -matrix, @expr{[[1, 2, 3], [4, 5, 6]]}. - -@tindex mapr -The command @kbd{V M _} [@code{mapr}] (i.e., type an underscore at the -operator prompt) maps by rows instead. For example, @kbd{V M _ A} views -the above matrix as a vector of two 3-element row vectors. It produces -a new vector which contains the absolute values of those row vectors, -namely @expr{[3.74, 8.77]}. (Recall, the absolute value of a vector is -defined as the square root of the sum of the squares of the elements.) -Some operators accept vectors and return new vectors; for example, -@kbd{v v} reverses a vector, so @kbd{V M _ v v} would reverse each row -of the matrix to get a new matrix, @expr{[[3, -2, 1], [-6, 5, -4]]}. - -Sometimes a vector of vectors (representing, say, strings, sets, or lists) -happens to look like a matrix. If so, remember to use @kbd{V M _} if you -want to map a function across the whole strings or sets rather than across -their individual elements. - -@tindex mapc -The command @kbd{V M :} [@code{mapc}] maps by columns. Basically, it -transposes the input matrix, maps by rows, and then, if the result is a -matrix, transposes again. For example, @kbd{V M : A} takes the absolute -values of the three columns of the matrix, treating each as a 2-vector, -and @kbd{V M : v v} reverses the columns to get the matrix -@expr{[[-4, 5, -6], [1, -2, 3]]}. - -(The symbols @kbd{_} and @kbd{:} were chosen because they had row-like -and column-like appearances, and were not already taken by useful -operators. Also, they appear shifted on most keyboards so they are easy -to type after @kbd{V M}.) - -The @kbd{_} and @kbd{:} modifiers have no effect on arguments that are -not matrices (so if none of the arguments are matrices, they have no -effect at all). If some of the arguments are matrices and others are -plain numbers, the plain numbers are held constant for all rows of the -matrix (so that @kbd{2 V M _ ^} squares every row of a matrix; squaring -a vector takes a dot product of the vector with itself). - -If some of the arguments are vectors with the same lengths as the -rows (for @kbd{V M _}) or columns (for @kbd{V M :}) of the matrix -arguments, those vectors are also held constant for every row or -column. - -Sometimes it is useful to specify another mapping command as the operator -to use with @kbd{V M}. For example, @kbd{V M _ V A +} applies @kbd{V A +} -to each row of the input matrix, which in turn adds the two values on that -row. If you give another vector-operator command as the operator for -@kbd{V M}, it automatically uses map-by-rows mode if you don't specify -otherwise; thus @kbd{V M V A +} is equivalent to @kbd{V M _ V A +}. (If -you really want to map-by-elements another mapping command, you can use -a triple-nested mapping command: @kbd{V M V M V A +} means to map -@kbd{V M V A +} over the rows of the matrix; in turn, @kbd{V A +} is -mapped over the elements of each row.) - -@tindex mapa -@tindex mapd -Previous versions of Calc had ``map across'' and ``map down'' modes -that are now considered obsolete; the old ``map across'' is now simply -@kbd{V M V A}, and ``map down'' is now @kbd{V M : V A}. The algebraic -functions @code{mapa} and @code{mapd} are still supported, though. -Note also that, while the old mapping modes were persistent (once you -set the mode, it would apply to later mapping commands until you reset -it), the new @kbd{:} and @kbd{_} modifiers apply only to the current -mapping command. The default @kbd{V M} always means map-by-elements. - -@xref{Algebraic Manipulation}, for the @kbd{a M} command, which is like -@kbd{V M} but for equations and inequalities instead of vectors. -@xref{Storing Variables}, for the @kbd{s m} command which modifies a -variable's stored value using a @kbd{V M}-like operator. - -@node Reducing, Nesting and Fixed Points, Mapping, Reducing and Mapping -@subsection Reducing - -@noindent -@kindex V R -@pindex calc-reduce -@tindex reduce -The @kbd{V R} (@code{calc-reduce}) [@code{reduce}] command applies a given -binary operator across all the elements of a vector. A binary operator is -a function such as @code{+} or @code{max} which takes two arguments. For -example, reducing @code{+} over a vector computes the sum of the elements -of the vector. Reducing @code{-} computes the first element minus each of -the remaining elements. Reducing @code{max} computes the maximum element -and so on. In general, reducing @code{f} over the vector @samp{[a, b, c, d]} -produces @samp{f(f(f(a, b), c), d)}. - -@kindex I V R -@tindex rreduce -The @kbd{I V R} [@code{rreduce}] command is similar to @kbd{V R} except -that works from right to left through the vector. For example, plain -@kbd{V R -} on the vector @samp{[a, b, c, d]} produces @samp{a - b - c - d} -but @kbd{I V R -} on the same vector produces @samp{a - (b - (c - d))}, -or @samp{a - b + c - d}. This ``alternating sum'' occurs frequently -in power series expansions. - -@kindex V U -@tindex accum -The @kbd{V U} (@code{calc-accumulate}) [@code{accum}] command does an -accumulation operation. Here Calc does the corresponding reduction -operation, but instead of producing only the final result, it produces -a vector of all the intermediate results. Accumulating @code{+} over -the vector @samp{[a, b, c, d]} produces the vector -@samp{[a, a + b, a + b + c, a + b + c + d]}. - -@kindex I V U -@tindex raccum -The @kbd{I V U} [@code{raccum}] command does a right-to-left accumulation. -For example, @kbd{I V U -} on the vector @samp{[a, b, c, d]} produces the -vector @samp{[a - b + c - d, b - c + d, c - d, d]}. - -@tindex reducea -@tindex rreducea -@tindex reduced -@tindex rreduced -As for @kbd{V M}, @kbd{V R} normally reduces a matrix elementwise. For -example, given the matrix @expr{[[a, b, c], [d, e, f]]}, @kbd{V R +} will -compute @expr{a + b + c + d + e + f}. You can type @kbd{V R _} or -@kbd{V R :} to modify this behavior. The @kbd{V R _} [@code{reducea}] -command reduces ``across'' the matrix; it reduces each row of the matrix -as a vector, then collects the results. Thus @kbd{V R _ +} of this -matrix would produce @expr{[a + b + c, d + e + f]}. Similarly, @kbd{V R :} -[@code{reduced}] reduces down; @kbd{V R : +} would produce @expr{[a + d, -b + e, c + f]}. - -@tindex reducer -@tindex rreducer -There is a third ``by rows'' mode for reduction that is occasionally -useful; @kbd{V R =} [@code{reducer}] simply reduces the operator over -the rows of the matrix themselves. Thus @kbd{V R = +} on the above -matrix would get the same result as @kbd{V R : +}, since adding two -row vectors is equivalent to adding their elements. But @kbd{V R = *} -would multiply the two rows (to get a single number, their dot product), -while @kbd{V R : *} would produce a vector of the products of the columns. - -These three matrix reduction modes work with @kbd{V R} and @kbd{I V R}, -but they are not currently supported with @kbd{V U} or @kbd{I V U}. - -@tindex reducec -@tindex rreducec -The obsolete reduce-by-columns function, @code{reducec}, is still -supported but there is no way to get it through the @kbd{V R} command. - -The commands @kbd{C-x * :} and @kbd{C-x * _} are equivalent to typing -@kbd{C-x * r} to grab a rectangle of data into Calc, and then typing -@kbd{V R : +} or @kbd{V R _ +}, respectively, to sum the columns or -rows of the matrix. @xref{Grabbing From Buffers}. - -@node Nesting and Fixed Points, Generalized Products, Reducing, Reducing and Mapping -@subsection Nesting and Fixed Points - -@noindent -@kindex H V R -@tindex nest -The @kbd{H V R} [@code{nest}] command applies a function to a given -argument repeatedly. It takes two values, @samp{a} and @samp{n}, from -the stack, where @samp{n} must be an integer. It then applies the -function nested @samp{n} times; if the function is @samp{f} and @samp{n} -is 3, the result is @samp{f(f(f(a)))}. The number @samp{n} may be -negative if Calc knows an inverse for the function @samp{f}; for -example, @samp{nest(sin, a, -2)} returns @samp{arcsin(arcsin(a))}. - -@kindex H V U -@tindex anest -The @kbd{H V U} [@code{anest}] command is an accumulating version of -@code{nest}: It returns a vector of @samp{n+1} values, e.g., -@samp{[a, f(a), f(f(a)), f(f(f(a)))]}. If @samp{n} is negative and -@samp{F} is the inverse of @samp{f}, then the result is of the -form @samp{[a, F(a), F(F(a)), F(F(F(a)))]}. - -@kindex H I V R -@tindex fixp -@cindex Fixed points -The @kbd{H I V R} [@code{fixp}] command is like @kbd{H V R}, except -that it takes only an @samp{a} value from the stack; the function is -applied until it reaches a ``fixed point,'' i.e., until the result -no longer changes. - -@kindex H I V U -@tindex afixp -The @kbd{H I V U} [@code{afixp}] command is an accumulating @code{fixp}. -The first element of the return vector will be the initial value @samp{a}; -the last element will be the final result that would have been returned -by @code{fixp}. - -For example, 0.739085 is a fixed point of the cosine function (in radians): -@samp{cos(0.739085) = 0.739085}. You can find this value by putting, say, -1.0 on the stack and typing @kbd{H I V U C}. (We use the accumulating -version so we can see the intermediate results: @samp{[1, 0.540302, 0.857553, -0.65329, ...]}. With a precision of six, this command will take 36 steps -to converge to 0.739085.) - -Newton's method for finding roots is a classic example of iteration -to a fixed point. To find the square root of five starting with an -initial guess, Newton's method would look for a fixed point of the -function @samp{(x + 5/x) / 2}. Putting a guess of 1 on the stack -and typing @kbd{H I V R ' ($ + 5/$)/2 @key{RET}} quickly yields the result -2.23607. This is equivalent to using the @kbd{a R} (@code{calc-find-root}) -command to find a root of the equation @samp{x^2 = 5}. - -These examples used numbers for @samp{a} values. Calc keeps applying -the function until two successive results are equal to within the -current precision. For complex numbers, both the real parts and the -imaginary parts must be equal to within the current precision. If -@samp{a} is a formula (say, a variable name), then the function is -applied until two successive results are exactly the same formula. -It is up to you to ensure that the function will eventually converge; -if it doesn't, you may have to press @kbd{C-g} to stop the Calculator. - -The algebraic @code{fixp} function takes two optional arguments, @samp{n} -and @samp{tol}. The first is the maximum number of steps to be allowed, -and must be either an integer or the symbol @samp{inf} (infinity, the -default). The second is a convergence tolerance. If a tolerance is -specified, all results during the calculation must be numbers, not -formulas, and the iteration stops when the magnitude of the difference -between two successive results is less than or equal to the tolerance. -(This implies that a tolerance of zero iterates until the results are -exactly equal.) - -Putting it all together, @samp{fixp(<(# + A/#)/2>, B, 20, 1e-10)} -computes the square root of @samp{A} given the initial guess @samp{B}, -stopping when the result is correct within the specified tolerance, or -when 20 steps have been taken, whichever is sooner. - -@node Generalized Products, , Nesting and Fixed Points, Reducing and Mapping -@subsection Generalized Products - -@kindex V O -@pindex calc-outer-product -@tindex outer -The @kbd{V O} (@code{calc-outer-product}) [@code{outer}] command applies -a given binary operator to all possible pairs of elements from two -vectors, to produce a matrix. For example, @kbd{V O *} with @samp{[a, b]} -and @samp{[x, y, z]} on the stack produces a multiplication table: -@samp{[[a x, a y, a z], [b x, b y, b z]]}. Element @var{r},@var{c} of -the result matrix is obtained by applying the operator to element @var{r} -of the lefthand vector and element @var{c} of the righthand vector. - -@kindex V I -@pindex calc-inner-product -@tindex inner -The @kbd{V I} (@code{calc-inner-product}) [@code{inner}] command computes -the generalized inner product of two vectors or matrices, given a -``multiplicative'' operator and an ``additive'' operator. These can each -actually be any binary operators; if they are @samp{*} and @samp{+}, -respectively, the result is a standard matrix multiplication. Element -@var{r},@var{c} of the result matrix is obtained by mapping the -multiplicative operator across row @var{r} of the lefthand matrix and -column @var{c} of the righthand matrix, and then reducing with the additive -operator. Just as for the standard @kbd{*} command, this can also do a -vector-matrix or matrix-vector inner product, or a vector-vector -generalized dot product. - -Since @kbd{V I} requires two operators, it prompts twice. In each case, -you can use any of the usual methods for entering the operator. If you -use @kbd{$} twice to take both operator formulas from the stack, the -first (multiplicative) operator is taken from the top of the stack -and the second (additive) operator is taken from second-to-top. - -@node Vector and Matrix Formats, , Reducing and Mapping, Matrix Functions -@section Vector and Matrix Display Formats - -@noindent -Commands for controlling vector and matrix display use the @kbd{v} prefix -instead of the usual @kbd{d} prefix. But they are display modes; in -particular, they are influenced by the @kbd{I} and @kbd{H} prefix keys -in the same way (@pxref{Display Modes}). Matrix display is also -influenced by the @kbd{d O} (@code{calc-flat-language}) mode; -@pxref{Normal Language Modes}. - -@kindex V < -@pindex calc-matrix-left-justify -@kindex V = -@pindex calc-matrix-center-justify -@kindex V > -@pindex calc-matrix-right-justify -The commands @kbd{v <} (@code{calc-matrix-left-justify}), @kbd{v >} -(@code{calc-matrix-right-justify}), and @w{@kbd{v =}} -(@code{calc-matrix-center-justify}) control whether matrix elements -are justified to the left, right, or center of their columns. - -@kindex V [ -@pindex calc-vector-brackets -@kindex V @{ -@pindex calc-vector-braces -@kindex V ( -@pindex calc-vector-parens -The @kbd{v [} (@code{calc-vector-brackets}) command turns the square -brackets that surround vectors and matrices displayed in the stack on -and off. The @kbd{v @{} (@code{calc-vector-braces}) and @kbd{v (} -(@code{calc-vector-parens}) commands use curly braces or parentheses, -respectively, instead of square brackets. For example, @kbd{v @{} might -be used in preparation for yanking a matrix into a buffer running -Mathematica. (In fact, the Mathematica language mode uses this mode; -@pxref{Mathematica Language Mode}.) Note that, regardless of the -display mode, either brackets or braces may be used to enter vectors, -and parentheses may never be used for this purpose. - -@kindex V ] -@pindex calc-matrix-brackets -The @kbd{v ]} (@code{calc-matrix-brackets}) command controls the -``big'' style display of matrices. It prompts for a string of code -letters; currently implemented letters are @code{R}, which enables -brackets on each row of the matrix; @code{O}, which enables outer -brackets in opposite corners of the matrix; and @code{C}, which -enables commas or semicolons at the ends of all rows but the last. -The default format is @samp{RO}. (Before Calc 2.00, the format -was fixed at @samp{ROC}.) Here are some example matrices: - -@example -@group -[ [ 123, 0, 0 ] [ [ 123, 0, 0 ], - [ 0, 123, 0 ] [ 0, 123, 0 ], - [ 0, 0, 123 ] ] [ 0, 0, 123 ] ] - - RO ROC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 [ 123, 0, 0 ; - 0, 123, 0 0, 123, 0 ; - 0, 0, 123 ] 0, 0, 123 ] - - O OC - -@end group -@end example -@noindent -@example -@group - [ 123, 0, 0 ] 123, 0, 0 - [ 0, 123, 0 ] 0, 123, 0 - [ 0, 0, 123 ] 0, 0, 123 - - R @r{blank} -@end group -@end example - -@noindent -Note that of the formats shown here, @samp{RO}, @samp{ROC}, and -@samp{OC} are all recognized as matrices during reading, while -the others are useful for display only. - -@kindex V , -@pindex calc-vector-commas -The @kbd{v ,} (@code{calc-vector-commas}) command turns commas on and -off in vector and matrix display. - -In vectors of length one, and in all vectors when commas have been -turned off, Calc adds extra parentheses around formulas that might -otherwise be ambiguous. For example, @samp{[a b]} could be a vector -of the one formula @samp{a b}, or it could be a vector of two -variables with commas turned off. Calc will display the former -case as @samp{[(a b)]}. You can disable these extra parentheses -(to make the output less cluttered at the expense of allowing some -ambiguity) by adding the letter @code{P} to the control string you -give to @kbd{v ]} (as described above). - -@kindex V . -@pindex calc-full-vectors -The @kbd{v .} (@code{calc-full-vectors}) command turns abbreviated -display of long vectors on and off. In this mode, vectors of six -or more elements, or matrices of six or more rows or columns, will -be displayed in an abbreviated form that displays only the first -three elements and the last element: @samp{[a, b, c, ..., z]}. -When very large vectors are involved this will substantially -improve Calc's display speed. - -@kindex t . -@pindex calc-full-trail-vectors -The @kbd{t .} (@code{calc-full-trail-vectors}) command controls a -similar mode for recording vectors in the Trail. If you turn on -this mode, vectors of six or more elements and matrices of six or -more rows or columns will be abbreviated when they are put in the -Trail. The @kbd{t y} (@code{calc-trail-yank}) command will be -unable to recover those vectors. If you are working with very -large vectors, this mode will improve the speed of all operations -that involve the trail. - -@kindex V / -@pindex calc-break-vectors -The @kbd{v /} (@code{calc-break-vectors}) command turns multi-line -vector display on and off. Normally, matrices are displayed with one -row per line but all other types of vectors are displayed in a single -line. This mode causes all vectors, whether matrices or not, to be -displayed with a single element per line. Sub-vectors within the -vectors will still use the normal linear form. - -@node Algebra, Units, Matrix Functions, Top -@chapter Algebra - -@noindent -This section covers the Calc features that help you work with -algebraic formulas. First, the general sub-formula selection -mechanism is described; this works in conjunction with any Calc -commands. Then, commands for specific algebraic operations are -described. Finally, the flexible @dfn{rewrite rule} mechanism -is discussed. - -The algebraic commands use the @kbd{a} key prefix; selection -commands use the @kbd{j} (for ``just a letter that wasn't used -for anything else'') prefix. - -@xref{Editing Stack Entries}, to see how to manipulate formulas -using regular Emacs editing commands. - -When doing algebraic work, you may find several of the Calculator's -modes to be helpful, including Algebraic Simplification mode (@kbd{m A}) -or No-Simplification mode (@kbd{m O}), -Algebraic entry mode (@kbd{m a}), Fraction mode (@kbd{m f}), and -Symbolic mode (@kbd{m s}). @xref{Mode Settings}, for discussions -of these modes. You may also wish to select Big display mode (@kbd{d B}). -@xref{Normal Language Modes}. - -@menu -* Selecting Subformulas:: -* Algebraic Manipulation:: -* Simplifying Formulas:: -* Polynomials:: -* Calculus:: -* Solving Equations:: -* Numerical Solutions:: -* Curve Fitting:: -* Summations:: -* Logical Operations:: -* Rewrite Rules:: -@end menu - -@node Selecting Subformulas, Algebraic Manipulation, Algebra, Algebra -@section Selecting Sub-Formulas - -@noindent -@cindex Selections -@cindex Sub-formulas -@cindex Parts of formulas -When working with an algebraic formula it is often necessary to -manipulate a portion of the formula rather than the formula as a -whole. Calc allows you to ``select'' a portion of any formula on -the stack. Commands which would normally operate on that stack -entry will now operate only on the sub-formula, leaving the -surrounding part of the stack entry alone. - -One common non-algebraic use for selection involves vectors. To work -on one element of a vector in-place, simply select that element as a -``sub-formula'' of the vector. - -@menu -* Making Selections:: -* Changing Selections:: -* Displaying Selections:: -* Operating on Selections:: -* Rearranging with Selections:: -@end menu - -@node Making Selections, Changing Selections, Selecting Subformulas, Selecting Subformulas -@subsection Making Selections - -@noindent -@kindex j s -@pindex calc-select-here -To select a sub-formula, move the Emacs cursor to any character in that -sub-formula, and press @w{@kbd{j s}} (@code{calc-select-here}). Calc will -highlight the smallest portion of the formula that contains that -character. By default the sub-formula is highlighted by blanking out -all of the rest of the formula with dots. Selection works in any -display mode but is perhaps easiest in Big mode (@kbd{d B}). -Suppose you enter the following formula: - -@smallexample -@group - 3 ___ - (a + b) + V c -1: --------------- - 2 x + 1 -@end group -@end smallexample - -@noindent -(by typing @kbd{' ((a+b)^3 + sqrt(c)) / (2x+1)}). If you move the -cursor to the letter @samp{b} and press @w{@kbd{j s}}, the display changes -to - -@smallexample -@group - . ... - .. . b. . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -Every character not part of the sub-formula @samp{b} has been changed -to a dot. The @samp{*} next to the line number is to remind you that -the formula has a portion of it selected. (In this case, it's very -obvious, but it might not always be. If Embedded mode is enabled, -the word @samp{Sel} also appears in the mode line because the stack -may not be visible. @pxref{Embedded Mode}.) - -If you had instead placed the cursor on the parenthesis immediately to -the right of the @samp{b}, the selection would have been: - -@smallexample -@group - . ... - (a + b) . . . -1* ............... - . . . . -@end group -@end smallexample - -@noindent -The portion selected is always large enough to be considered a complete -formula all by itself, so selecting the parenthesis selects the whole -formula that it encloses. Putting the cursor on the @samp{+} sign -would have had the same effect. - -(Strictly speaking, the Emacs cursor is really the manifestation of -the Emacs ``point,'' which is a position @emph{between} two characters -in the buffer. So purists would say that Calc selects the smallest -sub-formula which contains the character to the right of ``point.'') - -If you supply a numeric prefix argument @var{n}, the selection is -expanded to the @var{n}th enclosing sub-formula. Thus, positioning -the cursor on the @samp{b} and typing @kbd{C-u 1 j s} will select -@samp{a + b}; typing @kbd{C-u 2 j s} will select @samp{(a + b)^3}, -and so on. - -If the cursor is not on any part of the formula, or if you give a -numeric prefix that is too large, the entire formula is selected. - -If the cursor is on the @samp{.} line that marks the top of the stack -(i.e., its normal ``rest position''), this command selects the entire -formula at stack level 1. Most selection commands similarly operate -on the formula at the top of the stack if you haven't positioned the -cursor on any stack entry. - -@kindex j a -@pindex calc-select-additional -The @kbd{j a} (@code{calc-select-additional}) command enlarges the -current selection to encompass the cursor. To select the smallest -sub-formula defined by two different points, move to the first and -press @kbd{j s}, then move to the other and press @kbd{j a}. This -is roughly analogous to using @kbd{C-@@} (@code{set-mark-command}) to -select the two ends of a region of text during normal Emacs editing. - -@kindex j o -@pindex calc-select-once -The @kbd{j o} (@code{calc-select-once}) command selects a formula in -exactly the same way as @kbd{j s}, except that the selection will -last only as long as the next command that uses it. For example, -@kbd{j o 1 +} is a handy way to add one to the sub-formula indicated -by the cursor. - -(A somewhat more precise definition: The @kbd{j o} command sets a flag -such that the next command involving selected stack entries will clear -the selections on those stack entries afterwards. All other selection -commands except @kbd{j a} and @kbd{j O} clear this flag.) - -@kindex j S -@kindex j O -@pindex calc-select-here-maybe -@pindex calc-select-once-maybe -The @kbd{j S} (@code{calc-select-here-maybe}) and @kbd{j O} -(@code{calc-select-once-maybe}) commands are equivalent to @kbd{j s} -and @kbd{j o}, respectively, except that if the formula already -has a selection they have no effect. This is analogous to the -behavior of some commands such as @kbd{j r} (@code{calc-rewrite-selection}; -@pxref{Selections with Rewrite Rules}) and is mainly intended to be -used in keyboard macros that implement your own selection-oriented -commands. - -Selection of sub-formulas normally treats associative terms like -@samp{a + b - c + d} and @samp{x * y * z} as single levels of the formula. -If you place the cursor anywhere inside @samp{a + b - c + d} except -on one of the variable names and use @kbd{j s}, you will select the -entire four-term sum. - -@kindex j b -@pindex calc-break-selections -The @kbd{j b} (@code{calc-break-selections}) command controls a mode -in which the ``deep structure'' of these associative formulas shows -through. Calc actually stores the above formulas as -@samp{((a + b) - c) + d} and @samp{x * (y * z)}. (Note that for certain -obscure reasons, by default Calc treats multiplication as -right-associative.) Once you have enabled @kbd{j b} mode, selecting -with the cursor on the @samp{-} sign would only select the @samp{a + b - -c} portion, which makes sense when the deep structure of the sum is -considered. There is no way to select the @samp{b - c + d} portion; -although this might initially look like just as legitimate a sub-formula -as @samp{a + b - c}, the deep structure shows that it isn't. The @kbd{d -U} command can be used to view the deep structure of any formula -(@pxref{Normal Language Modes}). - -When @kbd{j b} mode has not been enabled, the deep structure is -generally hidden by the selection commands---what you see is what -you get. - -@kindex j u -@pindex calc-unselect -The @kbd{j u} (@code{calc-unselect}) command unselects the formula -that the cursor is on. If there was no selection in the formula, -this command has no effect. With a numeric prefix argument, it -unselects the @var{n}th stack element rather than using the cursor -position. - -@kindex j c -@pindex calc-clear-selections -The @kbd{j c} (@code{calc-clear-selections}) command unselects all -stack elements. - -@node Changing Selections, Displaying Selections, Making Selections, Selecting Subformulas -@subsection Changing Selections - -@noindent -@kindex j m -@pindex calc-select-more -Once you have selected a sub-formula, you can expand it using the -@w{@kbd{j m}} (@code{calc-select-more}) command. If @samp{a + b} is -selected, pressing @w{@kbd{j m}} repeatedly works as follows: - -@smallexample -@group - 3 ... 3 ___ 3 ___ - (a + b) . . . (a + b) + V c (a + b) + V c -1* ............... 1* ............... 1* --------------- - . . . . . . . . 2 x + 1 -@end group -@end smallexample - -@noindent -In the last example, the entire formula is selected. This is roughly -the same as having no selection at all, but because there are subtle -differences the @samp{*} character is still there on the line number. - -With a numeric prefix argument @var{n}, @kbd{j m} expands @var{n} -times (or until the entire formula is selected). Note that @kbd{j s} -with argument @var{n} is equivalent to plain @kbd{j s} followed by -@kbd{j m} with argument @var{n}. If @w{@kbd{j m}} is used when there -is no current selection, it is equivalent to @w{@kbd{j s}}. - -Even though @kbd{j m} does not explicitly use the location of the -cursor within the formula, it nevertheless uses the cursor to determine -which stack element to operate on. As usual, @kbd{j m} when the cursor -is not on any stack element operates on the top stack element. - -@kindex j l -@pindex calc-select-less -The @kbd{j l} (@code{calc-select-less}) command reduces the current -selection around the cursor position. That is, it selects the -immediate sub-formula of the current selection which contains the -cursor, the opposite of @kbd{j m}. If the cursor is not inside the -current selection, the command de-selects the formula. - -@kindex j 1-9 -@pindex calc-select-part -The @kbd{j 1} through @kbd{j 9} (@code{calc-select-part}) commands -select the @var{n}th sub-formula of the current selection. They are -like @kbd{j l} (@code{calc-select-less}) except they use counting -rather than the cursor position to decide which sub-formula to select. -For example, if the current selection is @kbd{a + b + c} or -@kbd{f(a, b, c)} or @kbd{[a, b, c]}, then @kbd{j 1} selects @samp{a}, -@kbd{j 2} selects @samp{b}, and @kbd{j 3} selects @samp{c}; in each of -these cases, @kbd{j 4} through @kbd{j 9} would be errors. - -If there is no current selection, @kbd{j 1} through @kbd{j 9} select -the @var{n}th top-level sub-formula. (In other words, they act as if -the entire stack entry were selected first.) To select the @var{n}th -sub-formula where @var{n} is greater than nine, you must instead invoke -@w{@kbd{j 1}} with @var{n} as a numeric prefix argument. - -@kindex j n -@kindex j p -@pindex calc-select-next -@pindex calc-select-previous -The @kbd{j n} (@code{calc-select-next}) and @kbd{j p} -(@code{calc-select-previous}) commands change the current selection -to the next or previous sub-formula at the same level. For example, -if @samp{b} is selected in @w{@samp{2 + a*b*c + x}}, then @kbd{j n} -selects @samp{c}. Further @kbd{j n} commands would be in error because, -even though there is something to the right of @samp{c} (namely, @samp{x}), -it is not at the same level; in this case, it is not a term of the -same product as @samp{b} and @samp{c}. However, @kbd{j m} (to select -the whole product @samp{a*b*c} as a term of the sum) followed by -@w{@kbd{j n}} would successfully select the @samp{x}. - -Similarly, @kbd{j p} moves the selection from the @samp{b} in this -sample formula to the @samp{a}. Both commands accept numeric prefix -arguments to move several steps at a time. - -It is interesting to compare Calc's selection commands with the -Emacs Info system's commands for navigating through hierarchically -organized documentation. Calc's @kbd{j n} command is completely -analogous to Info's @kbd{n} command. Likewise, @kbd{j p} maps to -@kbd{p}, @kbd{j 2} maps to @kbd{2}, and Info's @kbd{u} is like @kbd{j m}. -(Note that @kbd{j u} stands for @code{calc-unselect}, not ``up''.) -The Info @kbd{m} command is somewhat similar to Calc's @kbd{j s} and -@kbd{j l}; in each case, you can jump directly to a sub-component -of the hierarchy simply by pointing to it with the cursor. - -@node Displaying Selections, Operating on Selections, Changing Selections, Selecting Subformulas -@subsection Displaying Selections - -@noindent -@kindex j d -@pindex calc-show-selections -The @kbd{j d} (@code{calc-show-selections}) command controls how -selected sub-formulas are displayed. One of the alternatives is -illustrated in the above examples; if we press @kbd{j d} we switch -to the other style in which the selected portion itself is obscured -by @samp{#} signs: - -@smallexample -@group - 3 ... # ___ - (a + b) . . . ## # ## + V c -1* ............... 1* --------------- - . . . . 2 x + 1 -@end group -@end smallexample - -@node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas -@subsection Operating on Selections - -@noindent -Once a selection is made, all Calc commands that manipulate items -on the stack will operate on the selected portions of the items -instead. (Note that several stack elements may have selections -at once, though there can be only one selection at a time in any -given stack element.) - -@kindex j e -@pindex calc-enable-selections -The @kbd{j e} (@code{calc-enable-selections}) command disables the -effect that selections have on Calc commands. The current selections -still exist, but Calc commands operate on whole stack elements anyway. -This mode can be identified by the fact that the @samp{*} markers on -the line numbers are gone, even though selections are visible. To -reactivate the selections, press @kbd{j e} again. - -To extract a sub-formula as a new formula, simply select the -sub-formula and press @key{RET}. This normally duplicates the top -stack element; here it duplicates only the selected portion of that -element. - -To replace a sub-formula with something different, you can enter the -new value onto the stack and press @key{TAB}. This normally exchanges -the top two stack elements; here it swaps the value you entered into -the selected portion of the formula, returning the old selected -portion to the top of the stack. - -@smallexample -@group - 3 ... ... ___ - (a + b) . . . 17 x y . . . 17 x y + V c -2* ............... 2* ............. 2: ------------- - . . . . . . . . 2 x + 1 - - 3 3 -1: 17 x y 1: (a + b) 1: (a + b) -@end group -@end smallexample - -In this example we select a sub-formula of our original example, -enter a new formula, @key{TAB} it into place, then deselect to see -the complete, edited formula. - -If you want to swap whole formulas around even though they contain -selections, just use @kbd{j e} before and after. - -@kindex j ' -@pindex calc-enter-selection -The @kbd{j '} (@code{calc-enter-selection}) command is another way -to replace a selected sub-formula. This command does an algebraic -entry just like the regular @kbd{'} key. When you press @key{RET}, -the formula you type replaces the original selection. You can use -the @samp{$} symbol in the formula to refer to the original -selection. If there is no selection in the formula under the cursor, -the cursor is used to make a temporary selection for the purposes of -the command. Thus, to change a term of a formula, all you have to -do is move the Emacs cursor to that term and press @kbd{j '}. - -@kindex j ` -@pindex calc-edit-selection -The @kbd{j `} (@code{calc-edit-selection}) command is a similar -analogue of the @kbd{`} (@code{calc-edit}) command. It edits the -selected sub-formula in a separate buffer. If there is no -selection, it edits the sub-formula indicated by the cursor. - -To delete a sub-formula, press @key{DEL}. This generally replaces -the sub-formula with the constant zero, but in a few suitable contexts -it uses the constant one instead. The @key{DEL} key automatically -deselects and re-simplifies the entire formula afterwards. Thus: - -@smallexample -@group - ### - 17 x y + # # 17 x y 17 # y 17 y -1* ------------- 1: ------- 1* ------- 1: ------- - 2 x + 1 2 x + 1 2 x + 1 2 x + 1 -@end group -@end smallexample - -In this example, we first delete the @samp{sqrt(c)} term; Calc -accomplishes this by replacing @samp{sqrt(c)} with zero and -resimplifying. We then delete the @kbd{x} in the numerator; -since this is part of a product, Calc replaces it with @samp{1} -and resimplifies. - -If you select an element of a vector and press @key{DEL}, that -element is deleted from the vector. If you delete one side of -an equation or inequality, only the opposite side remains. - -@kindex j @key{DEL} -@pindex calc-del-selection -The @kbd{j @key{DEL}} (@code{calc-del-selection}) command is like -@key{DEL} but with the auto-selecting behavior of @kbd{j '} and -@kbd{j `}. It deletes the selected portion of the formula -indicated by the cursor, or, in the absence of a selection, it -deletes the sub-formula indicated by the cursor position. - -@kindex j @key{RET} -@pindex calc-grab-selection -(There is also an auto-selecting @kbd{j @key{RET}} (@code{calc-copy-selection}) -command.) - -Normal arithmetic operations also apply to sub-formulas. Here we -select the denominator, press @kbd{5 -} to subtract five from the -denominator, press @kbd{n} to negate the denominator, then -press @kbd{Q} to take the square root. - -@smallexample -@group - .. . .. . .. . .. . -1* ....... 1* ....... 1* ....... 1* .......... - 2 x + 1 2 x - 4 4 - 2 x _________ - V 4 - 2 x -@end group -@end smallexample - -Certain types of operations on selections are not allowed. For -example, for an arithmetic function like @kbd{-} no more than one of -the arguments may be a selected sub-formula. (As the above example -shows, the result of the subtraction is spliced back into the argument -which had the selection; if there were more than one selection involved, -this would not be well-defined.) If you try to subtract two selections, -the command will abort with an error message. - -Operations on sub-formulas sometimes leave the formula as a whole -in an ``un-natural'' state. Consider negating the @samp{2 x} term -of our sample formula by selecting it and pressing @kbd{n} -(@code{calc-change-sign}). - -@smallexample -@group - .. . .. . -1* .......... 1* ........... - ......... .......... - . . . 2 x . . . -2 x -@end group -@end smallexample - -Unselecting the sub-formula reveals that the minus sign, which would -normally have cancelled out with the subtraction automatically, has -not been able to do so because the subtraction was not part of the -selected portion. Pressing @kbd{=} (@code{calc-evaluate}) or doing -any other mathematical operation on the whole formula will cause it -to be simplified. - -@smallexample -@group - 17 y 17 y -1: ----------- 1: ---------- - __________ _________ - V 4 - -2 x V 4 + 2 x -@end group -@end smallexample - -@node Rearranging with Selections, , Operating on Selections, Selecting Subformulas -@subsection Rearranging Formulas using Selections - -@noindent -@kindex j R -@pindex calc-commute-right -The @kbd{j R} (@code{calc-commute-right}) command moves the selected -sub-formula to the right in its surrounding formula. Generally the -selection is one term of a sum or product; the sum or product is -rearranged according to the commutative laws of algebra. - -As with @kbd{j '} and @kbd{j @key{DEL}}, the term under the cursor is used -if there is no selection in the current formula. All commands described -in this section share this property. In this example, we place the -cursor on the @samp{a} and type @kbd{j R}, then repeat. - -@smallexample -1: a + b - c 1: b + a - c 1: b - c + a -@end smallexample - -@noindent -Note that in the final step above, the @samp{a} is switched with -the @samp{c} but the signs are adjusted accordingly. When moving -terms of sums and products, @kbd{j R} will never change the -mathematical meaning of the formula. - -The selected term may also be an element of a vector or an argument -of a function. The term is exchanged with the one to its right. -In this case, the ``meaning'' of the vector or function may of -course be drastically changed. - -@smallexample -1: [a, b, c] 1: [b, a, c] 1: [b, c, a] - -1: f(a, b, c) 1: f(b, a, c) 1: f(b, c, a) -@end smallexample - -@kindex j L -@pindex calc-commute-left -The @kbd{j L} (@code{calc-commute-left}) command is like @kbd{j R} -except that it swaps the selected term with the one to its left. - -With numeric prefix arguments, these commands move the selected -term several steps at a time. It is an error to try to move a -term left or right past the end of its enclosing formula. -With numeric prefix arguments of zero, these commands move the -selected term as far as possible in the given direction. - -@kindex j D -@pindex calc-sel-distribute -The @kbd{j D} (@code{calc-sel-distribute}) command mixes the selected -sum or product into the surrounding formula using the distributive -law. For example, in @samp{a * (b - c)} with the @samp{b - c} -selected, the result is @samp{a b - a c}. This also distributes -products or quotients into surrounding powers, and can also do -transformations like @samp{exp(a + b)} to @samp{exp(a) exp(b)}, -where @samp{a + b} is the selected term, and @samp{ln(a ^ b)} -to @samp{ln(a) b}, where @samp{a ^ b} is the selected term. - -For multiple-term sums or products, @kbd{j D} takes off one term -at a time: @samp{a * (b + c - d)} goes to @samp{a * (c - d) + a b} -with the @samp{c - d} selected so that you can type @kbd{j D} -repeatedly to expand completely. The @kbd{j D} command allows a -numeric prefix argument which specifies the maximum number of -times to expand at once; the default is one time only. - -@vindex DistribRules -The @kbd{j D} command is implemented using rewrite rules. -@xref{Selections with Rewrite Rules}. The rules are stored in -the Calc variable @code{DistribRules}. A convenient way to view -these rules is to use @kbd{s e} (@code{calc-edit-variable}) which -displays and edits the stored value of a variable. Press @kbd{C-c C-c} -to return from editing mode; be careful not to make any actual changes -or else you will affect the behavior of future @kbd{j D} commands! - -To extend @kbd{j D} to handle new cases, just edit @code{DistribRules} -as described above. You can then use the @kbd{s p} command to save -this variable's value permanently for future Calc sessions. -@xref{Operations on Variables}. - -@kindex j M -@pindex calc-sel-merge -@vindex MergeRules -The @kbd{j M} (@code{calc-sel-merge}) command is the complement -of @kbd{j D}; given @samp{a b - a c} with either @samp{a b} or -@samp{a c} selected, the result is @samp{a * (b - c)}. Once -again, @kbd{j M} can also merge calls to functions like @code{exp} -and @code{ln}; examine the variable @code{MergeRules} to see all -the relevant rules. - -@kindex j C -@pindex calc-sel-commute -@vindex CommuteRules -The @kbd{j C} (@code{calc-sel-commute}) command swaps the arguments -of the selected sum, product, or equation. It always behaves as -if @kbd{j b} mode were in effect, i.e., the sum @samp{a + b + c} is -treated as the nested sums @samp{(a + b) + c} by this command. -If you put the cursor on the first @samp{+}, the result is -@samp{(b + a) + c}; if you put the cursor on the second @samp{+}, the -result is @samp{c + (a + b)} (which the default simplifications -will rearrange to @samp{(c + a) + b}). The relevant rules are stored -in the variable @code{CommuteRules}. - -You may need to turn default simplifications off (with the @kbd{m O} -command) in order to get the full benefit of @kbd{j C}. For example, -commuting @samp{a - b} produces @samp{-b + a}, but the default -simplifications will ``simplify'' this right back to @samp{a - b} if -you don't turn them off. The same is true of some of the other -manipulations described in this section. - -@kindex j N -@pindex calc-sel-negate -@vindex NegateRules -The @kbd{j N} (@code{calc-sel-negate}) command replaces the selected -term with the negative of that term, then adjusts the surrounding -formula in order to preserve the meaning. For example, given -@samp{exp(a - b)} where @samp{a - b} is selected, the result is -@samp{1 / exp(b - a)}. By contrast, selecting a term and using the -regular @kbd{n} (@code{calc-change-sign}) command negates the -term without adjusting the surroundings, thus changing the meaning -of the formula as a whole. The rules variable is @code{NegateRules}. - -@kindex j & -@pindex calc-sel-invert -@vindex InvertRules -The @kbd{j &} (@code{calc-sel-invert}) command is similar to @kbd{j N} -except it takes the reciprocal of the selected term. For example, -given @samp{a - ln(b)} with @samp{b} selected, the result is -@samp{a + ln(1/b)}. The rules variable is @code{InvertRules}. - -@kindex j E -@pindex calc-sel-jump-equals -@vindex JumpRules -The @kbd{j E} (@code{calc-sel-jump-equals}) command moves the -selected term from one side of an equation to the other. Given -@samp{a + b = c + d} with @samp{c} selected, the result is -@samp{a + b - c = d}. This command also works if the selected -term is part of a @samp{*}, @samp{/}, or @samp{^} formula. The -relevant rules variable is @code{JumpRules}. - -@kindex j I -@kindex H j I -@pindex calc-sel-isolate -The @kbd{j I} (@code{calc-sel-isolate}) command isolates the -selected term on its side of an equation. It uses the @kbd{a S} -(@code{calc-solve-for}) command to solve the equation, and the -Hyperbolic flag affects it in the same way. @xref{Solving Equations}. -When it applies, @kbd{j I} is often easier to use than @kbd{j E}. -It understands more rules of algebra, and works for inequalities -as well as equations. - -@kindex j * -@kindex j / -@pindex calc-sel-mult-both-sides -@pindex calc-sel-div-both-sides -The @kbd{j *} (@code{calc-sel-mult-both-sides}) command prompts for a -formula using algebraic entry, then multiplies both sides of the -selected quotient or equation by that formula. It simplifies each -side with @kbd{a s} (@code{calc-simplify}) before re-forming the -quotient or equation. You can suppress this simplification by -providing a prefix argument: @kbd{C-u j *}. There is also a @kbd{j /} -(@code{calc-sel-div-both-sides}) which is similar to @kbd{j *} but -dividing instead of multiplying by the factor you enter. - -If the selection is a quotient with numerator 1, then Calc's default -simplifications would normally cancel the new factors. To prevent -this, when the @kbd{j *} command is used on a selection whose numerator is -1 or -1, the denominator is expanded at the top level using the -distributive law (as if using the @kbd{C-u 1 a x} command). Suppose the -formula on the stack is @samp{1 / (a + 1)} and you wish to multiplying the -top and bottom by @samp{a - 1}. Calc's default simplifications would -normally change the result @samp{(a - 1) /(a + 1) (a - 1)} back -to the original form by cancellation; when @kbd{j *} is used, Calc -expands the denominator to @samp{a (a - 1) + a - 1} to prevent this. - -If you wish the @kbd{j *} command to completely expand the denominator -of a quotient you can call it with a zero prefix: @kbd{C-u 0 j *}. For -example, if the formula on the stack is @samp{1 / (sqrt(a) + 1)}, you may -wish to eliminate the square root in the denominator by multiplying -the top and bottom by @samp{sqrt(a) - 1}. If you did this simply by using -a simple @kbd{j *} command, you would get -@samp{(sqrt(a)-1)/ (sqrt(a) (sqrt(a) - 1) + sqrt(a) - 1)}. Instead, -you would probably want to use @kbd{C-u 0 j *}, which would expand the -bottom and give you the desired result @samp{(sqrt(a)-1)/(a-1)}. More -generally, if @kbd{j *} is called with an argument of a positive -integer @var{n}, then the denominator of the expression will be -expanded @var{n} times (as if with the @kbd{C-u @var{n} a x} command). - -If the selection is an inequality, @kbd{j *} and @kbd{j /} will -accept any factor, but will warn unless they can prove the factor -is either positive or negative. (In the latter case the direction -of the inequality will be switched appropriately.) @xref{Declarations}, -for ways to inform Calc that a given variable is positive or -negative. If Calc can't tell for sure what the sign of the factor -will be, it will assume it is positive and display a warning -message. - -For selections that are not quotients, equations, or inequalities, -these commands pull out a multiplicative factor: They divide (or -multiply) by the entered formula, simplify, then multiply (or divide) -back by the formula. - -@kindex j + -@kindex j - -@pindex calc-sel-add-both-sides -@pindex calc-sel-sub-both-sides -The @kbd{j +} (@code{calc-sel-add-both-sides}) and @kbd{j -} -(@code{calc-sel-sub-both-sides}) commands analogously add to or -subtract from both sides of an equation or inequality. For other -types of selections, they extract an additive factor. A numeric -prefix argument suppresses simplification of the intermediate -results. - -@kindex j U -@pindex calc-sel-unpack -The @kbd{j U} (@code{calc-sel-unpack}) command replaces the -selected function call with its argument. For example, given -@samp{a + sin(x^2)} with @samp{sin(x^2)} selected, the result -is @samp{a + x^2}. (The @samp{x^2} will remain selected; if you -wanted to change the @code{sin} to @code{cos}, just press @kbd{C} -now to take the cosine of the selected part.) - -@kindex j v -@pindex calc-sel-evaluate -The @kbd{j v} (@code{calc-sel-evaluate}) command performs the -normal default simplifications on the selected sub-formula. -These are the simplifications that are normally done automatically -on all results, but which may have been partially inhibited by -previous selection-related operations, or turned off altogether -by the @kbd{m O} command. This command is just an auto-selecting -version of the @w{@kbd{a v}} command (@pxref{Algebraic Manipulation}). - -With a numeric prefix argument of 2, @kbd{C-u 2 j v} applies -the @kbd{a s} (@code{calc-simplify}) command to the selected -sub-formula. With a prefix argument of 3 or more, e.g., @kbd{C-u j v} -applies the @kbd{a e} (@code{calc-simplify-extended}) command. -@xref{Simplifying Formulas}. With a negative prefix argument -it simplifies at the top level only, just as with @kbd{a v}. -Here the ``top'' level refers to the top level of the selected -sub-formula. - -@kindex j " -@pindex calc-sel-expand-formula -The @kbd{j "} (@code{calc-sel-expand-formula}) command is to @kbd{a "} -(@pxref{Algebraic Manipulation}) what @kbd{j v} is to @kbd{a v}. - -You can use the @kbd{j r} (@code{calc-rewrite-selection}) command -to define other algebraic operations on sub-formulas. @xref{Rewrite Rules}. - -@node Algebraic Manipulation, Simplifying Formulas, Selecting Subformulas, Algebra -@section Algebraic Manipulation - -@noindent -The commands in this section perform general-purpose algebraic -manipulations. They work on the whole formula at the top of the -stack (unless, of course, you have made a selection in that -formula). - -Many algebra commands prompt for a variable name or formula. If you -answer the prompt with a blank line, the variable or formula is taken -from top-of-stack, and the normal argument for the command is taken -from the second-to-top stack level. - -@kindex a v -@pindex calc-alg-evaluate -The @kbd{a v} (@code{calc-alg-evaluate}) command performs the normal -default simplifications on a formula; for example, @samp{a - -b} is -changed to @samp{a + b}. These simplifications are normally done -automatically on all Calc results, so this command is useful only if -you have turned default simplifications off with an @kbd{m O} -command. @xref{Simplification Modes}. - -It is often more convenient to type @kbd{=}, which is like @kbd{a v} -but which also substitutes stored values for variables in the formula. -Use @kbd{a v} if you want the variables to ignore their stored values. - -If you give a numeric prefix argument of 2 to @kbd{a v}, it simplifies -as if in Algebraic Simplification mode. This is equivalent to typing -@kbd{a s}; @pxref{Simplifying Formulas}. If you give a numeric prefix -of 3 or more, it uses Extended Simplification mode (@kbd{a e}). - -If you give a negative prefix argument @mathit{-1}, @mathit{-2}, or @mathit{-3}, -it simplifies in the corresponding mode but only works on the top-level -function call of the formula. For example, @samp{(2 + 3) * (2 + 3)} will -simplify to @samp{(2 + 3)^2}, without simplifying the sub-formulas -@samp{2 + 3}. As another example, typing @kbd{V R +} to sum the vector -@samp{[1, 2, 3, 4]} produces the formula @samp{reduce(add, [1, 2, 3, 4])} -in No-Simplify mode. Using @kbd{a v} will evaluate this all the way to -10; using @kbd{C-u - a v} will evaluate it only to @samp{1 + 2 + 3 + 4}. -(@xref{Reducing and Mapping}.) - -@tindex evalv -@tindex evalvn -The @kbd{=} command corresponds to the @code{evalv} function, and -the related @kbd{N} command, which is like @kbd{=} but temporarily -disables Symbolic mode (@kbd{m s}) during the evaluation, corresponds -to the @code{evalvn} function. (These commands interpret their prefix -arguments differently than @kbd{a v}; @kbd{=} treats the prefix as -the number of stack elements to evaluate at once, and @kbd{N} treats -it as a temporary different working precision.) - -The @code{evalvn} function can take an alternate working precision -as an optional second argument. This argument can be either an -integer, to set the precision absolutely, or a vector containing -a single integer, to adjust the precision relative to the current -precision. Note that @code{evalvn} with a larger than current -precision will do the calculation at this higher precision, but the -result will as usual be rounded back down to the current precision -afterward. For example, @samp{evalvn(pi - 3.1415)} at a precision -of 12 will return @samp{9.265359e-5}; @samp{evalvn(pi - 3.1415, 30)} -will return @samp{9.26535897932e-5} (computing a 25-digit result which -is then rounded down to 12); and @samp{evalvn(pi - 3.1415, [-2])} -will return @samp{9.2654e-5}. - -@kindex a " -@pindex calc-expand-formula -The @kbd{a "} (@code{calc-expand-formula}) command expands functions -into their defining formulas wherever possible. For example, -@samp{deg(x^2)} is changed to @samp{180 x^2 / pi}. Most functions, -like @code{sin} and @code{gcd}, are not defined by simple formulas -and so are unaffected by this command. One important class of -functions which @emph{can} be expanded is the user-defined functions -created by the @kbd{Z F} command. @xref{Algebraic Definitions}. -Other functions which @kbd{a "} can expand include the probability -distribution functions, most of the financial functions, and the -hyperbolic and inverse hyperbolic functions. A numeric prefix argument -affects @kbd{a "} in the same way as it does @kbd{a v}: A positive -argument expands all functions in the formula and then simplifies in -various ways; a negative argument expands and simplifies only the -top-level function call. - -@kindex a M -@pindex calc-map-equation -@tindex mapeq -The @kbd{a M} (@code{calc-map-equation}) [@code{mapeq}] command applies -a given function or operator to one or more equations. It is analogous -to @kbd{V M}, which operates on vectors instead of equations. -@pxref{Reducing and Mapping}. For example, @kbd{a M S} changes -@samp{x = y+1} to @samp{sin(x) = sin(y+1)}, and @kbd{a M +} with -@samp{x = y+1} and @expr{6} on the stack produces @samp{x+6 = y+7}. -With two equations on the stack, @kbd{a M +} would add the lefthand -sides together and the righthand sides together to get the two -respective sides of a new equation. - -Mapping also works on inequalities. Mapping two similar inequalities -produces another inequality of the same type. Mapping an inequality -with an equation produces an inequality of the same type. Mapping a -@samp{<=} with a @samp{<} or @samp{!=} (not-equal) produces a @samp{<}. -If inequalities with opposite direction (e.g., @samp{<} and @samp{>}) -are mapped, the direction of the second inequality is reversed to -match the first: Using @kbd{a M +} on @samp{a < b} and @samp{a > 2} -reverses the latter to get @samp{2 < a}, which then allows the -combination @samp{a + 2 < b + a}, which the @kbd{a s} command can -then simplify to get @samp{2 < b}. - -Using @kbd{a M *}, @kbd{a M /}, @kbd{a M n}, or @kbd{a M &} to negate -or invert an inequality will reverse the direction of the inequality. -Other adjustments to inequalities are @emph{not} done automatically; -@kbd{a M S} will change @w{@samp{x < y}} to @samp{sin(x) < sin(y)} even -though this is not true for all values of the variables. - -@kindex H a M -@tindex mapeqp -With the Hyperbolic flag, @kbd{H a M} [@code{mapeqp}] does a plain -mapping operation without reversing the direction of any inequalities. -Thus, @kbd{H a M &} would change @kbd{x > 2} to @kbd{1/x > 0.5}. -(This change is mathematically incorrect, but perhaps you were -fixing an inequality which was already incorrect.) - -@kindex I a M -@tindex mapeqr -With the Inverse flag, @kbd{I a M} [@code{mapeqr}] always reverses -the direction of the inequality. You might use @kbd{I a M C} to -change @samp{x < y} to @samp{cos(x) > cos(y)} if you know you are -working with small positive angles. - -@kindex a b -@pindex calc-substitute -@tindex subst -The @kbd{a b} (@code{calc-substitute}) [@code{subst}] command substitutes -all occurrences -of some variable or sub-expression of an expression with a new -sub-expression. For example, substituting @samp{sin(x)} with @samp{cos(y)} -in @samp{2 sin(x)^2 + x sin(x) + sin(2 x)} produces -@samp{2 cos(y)^2 + x cos(y) + @w{sin(2 x)}}. -Note that this is a purely structural substitution; the lone @samp{x} and -the @samp{sin(2 x)} stayed the same because they did not look like -@samp{sin(x)}. @xref{Rewrite Rules}, for a more general method for -doing substitutions. - -The @kbd{a b} command normally prompts for two formulas, the old -one and the new one. If you enter a blank line for the first -prompt, all three arguments are taken from the stack (new, then old, -then target expression). If you type an old formula but then enter a -blank line for the new one, the new formula is taken from top-of-stack -and the target from second-to-top. If you answer both prompts, the -target is taken from top-of-stack as usual. - -Note that @kbd{a b} has no understanding of commutativity or -associativity. The pattern @samp{x+y} will not match the formula -@samp{y+x}. Also, @samp{y+z} will not match inside the formula @samp{x+y+z} -because the @samp{+} operator is left-associative, so the ``deep -structure'' of that formula is @samp{(x+y) + z}. Use @kbd{d U} -(@code{calc-unformatted-language}) mode to see the true structure of -a formula. The rewrite rule mechanism, discussed later, does not have -these limitations. - -As an algebraic function, @code{subst} takes three arguments: -Target expression, old, new. Note that @code{subst} is always -evaluated immediately, even if its arguments are variables, so if -you wish to put a call to @code{subst} onto the stack you must -turn the default simplifications off first (with @kbd{m O}). - -@node Simplifying Formulas, Polynomials, Algebraic Manipulation, Algebra -@section Simplifying Formulas - -@noindent -@kindex a s -@pindex calc-simplify -@tindex simplify -The @kbd{a s} (@code{calc-simplify}) [@code{simplify}] command applies -various algebraic rules to simplify a formula. This includes rules which -are not part of the default simplifications because they may be too slow -to apply all the time, or may not be desirable all of the time. For -example, non-adjacent terms of sums are combined, as in @samp{a + b + 2 a} -to @samp{b + 3 a}, and some formulas like @samp{sin(arcsin(x))} are -simplified to @samp{x}. - -The sections below describe all the various kinds of algebraic -simplifications Calc provides in full detail. None of Calc's -simplification commands are designed to pull rabbits out of hats; -they simply apply certain specific rules to put formulas into -less redundant or more pleasing forms. Serious algebra in Calc -must be done manually, usually with a combination of selections -and rewrite rules. @xref{Rearranging with Selections}. -@xref{Rewrite Rules}. - -@xref{Simplification Modes}, for commands to control what level of -simplification occurs automatically. Normally only the ``default -simplifications'' occur. - -@menu -* Default Simplifications:: -* Algebraic Simplifications:: -* Unsafe Simplifications:: -* Simplification of Units:: -@end menu - -@node Default Simplifications, Algebraic Simplifications, Simplifying Formulas, Simplifying Formulas -@subsection Default Simplifications - -@noindent -@cindex Default simplifications -This section describes the ``default simplifications,'' those which are -normally applied to all results. For example, if you enter the variable -@expr{x} on the stack twice and push @kbd{+}, Calc's default -simplifications automatically change @expr{x + x} to @expr{2 x}. - -The @kbd{m O} command turns off the default simplifications, so that -@expr{x + x} will remain in this form unless you give an explicit -``simplify'' command like @kbd{=} or @kbd{a v}. @xref{Algebraic -Manipulation}. The @kbd{m D} command turns the default simplifications -back on. - -The most basic default simplification is the evaluation of functions. -For example, @expr{2 + 3} is evaluated to @expr{5}, and @expr{@tfn{sqrt}(9)} -is evaluated to @expr{3}. Evaluation does not occur if the arguments -to a function are somehow of the wrong type @expr{@tfn{tan}([2,3,4])}), -range (@expr{@tfn{tan}(90)}), or number (@expr{@tfn{tan}(3,5)}), -or if the function name is not recognized (@expr{@tfn{f}(5)}), or if -Symbolic mode (@pxref{Symbolic Mode}) prevents evaluation -(@expr{@tfn{sqrt}(2)}). - -Calc simplifies (evaluates) the arguments to a function before it -simplifies the function itself. Thus @expr{@tfn{sqrt}(5+4)} is -simplified to @expr{@tfn{sqrt}(9)} before the @code{sqrt} function -itself is applied. There are very few exceptions to this rule: -@code{quote}, @code{lambda}, and @code{condition} (the @code{::} -operator) do not evaluate their arguments, @code{if} (the @code{? :} -operator) does not evaluate all of its arguments, and @code{evalto} -does not evaluate its lefthand argument. - -Most commands apply the default simplifications to all arguments they -take from the stack, perform a particular operation, then simplify -the result before pushing it back on the stack. In the common special -case of regular arithmetic commands like @kbd{+} and @kbd{Q} [@code{sqrt}], -the arguments are simply popped from the stack and collected into a -suitable function call, which is then simplified (the arguments being -simplified first as part of the process, as described above). - -The default simplifications are too numerous to describe completely -here, but this section will describe the ones that apply to the -major arithmetic operators. This list will be rather technical in -nature, and will probably be interesting to you only if you are -a serious user of Calc's algebra facilities. - -@tex -\bigskip -@end tex - -As well as the simplifications described here, if you have stored -any rewrite rules in the variable @code{EvalRules} then these rules -will also be applied before any built-in default simplifications. -@xref{Automatic Rewrites}, for details. - -@tex -\bigskip -@end tex - -And now, on with the default simplifications: - -Arithmetic operators like @kbd{+} and @kbd{*} always take two -arguments in Calc's internal form. Sums and products of three or -more terms are arranged by the associative law of algebra into -a left-associative form for sums, @expr{((a + b) + c) + d}, and -(by default) a right-associative form for products, -@expr{a * (b * (c * d))}. Formulas like @expr{(a + b) + (c + d)} are -rearranged to left-associative form, though this rarely matters since -Calc's algebra commands are designed to hide the inner structure of sums -and products as much as possible. Sums and products in their proper -associative form will be written without parentheses in the examples -below. - -Sums and products are @emph{not} rearranged according to the -commutative law (@expr{a + b} to @expr{b + a}) except in a few -special cases described below. Some algebra programs always -rearrange terms into a canonical order, which enables them to -see that @expr{a b + b a} can be simplified to @expr{2 a b}. -Calc assumes you have put the terms into the order you want -and generally leaves that order alone, with the consequence -that formulas like the above will only be simplified if you -explicitly give the @kbd{a s} command. @xref{Algebraic -Simplifications}. - -Differences @expr{a - b} are treated like sums @expr{a + (-b)} -for purposes of simplification; one of the default simplifications -is to rewrite @expr{a + (-b)} or @expr{(-b) + a}, where @expr{-b} -represents a ``negative-looking'' term, into @expr{a - b} form. -``Negative-looking'' means negative numbers, negated formulas like -@expr{-x}, and products or quotients in which either term is -negative-looking. - -Other simplifications involving negation are @expr{-(-x)} to @expr{x}; -@expr{-(a b)} or @expr{-(a/b)} where either @expr{a} or @expr{b} is -negative-looking, simplified by negating that term, or else where -@expr{a} or @expr{b} is any number, by negating that number; -@expr{-(a + b)} to @expr{-a - b}, and @expr{-(b - a)} to @expr{a - b}. -(This, and rewriting @expr{(-b) + a} to @expr{a - b}, are the only -cases where the order of terms in a sum is changed by the default -simplifications.) - -The distributive law is used to simplify sums in some cases: -@expr{a x + b x} to @expr{(a + b) x}, where @expr{a} represents -a number or an implicit 1 or @mathit{-1} (as in @expr{x} or @expr{-x}) -and similarly for @expr{b}. Use the @kbd{a c}, @w{@kbd{a f}}, or -@kbd{j M} commands to merge sums with non-numeric coefficients -using the distributive law. - -The distributive law is only used for sums of two terms, or -for adjacent terms in a larger sum. Thus @expr{a + b + b + c} -is simplified to @expr{a + 2 b + c}, but @expr{a + b + c + b} -is not simplified. The reason is that comparing all terms of a -sum with one another would require time proportional to the -square of the number of terms; Calc relegates potentially slow -operations like this to commands that have to be invoked -explicitly, like @kbd{a s}. - -Finally, @expr{a + 0} and @expr{0 + a} are simplified to @expr{a}. -A consequence of the above rules is that @expr{0 - a} is simplified -to @expr{-a}. - -@tex -\bigskip -@end tex - -The products @expr{1 a} and @expr{a 1} are simplified to @expr{a}; -@expr{(-1) a} and @expr{a (-1)} are simplified to @expr{-a}; -@expr{0 a} and @expr{a 0} are simplified to @expr{0}, except that -in Matrix mode where @expr{a} is not provably scalar the result -is the generic zero matrix @samp{idn(0)}, and that if @expr{a} is -infinite the result is @samp{nan}. - -Also, @expr{(-a) b} and @expr{a (-b)} are simplified to @expr{-(a b)}, -where this occurs for negated formulas but not for regular negative -numbers. - -Products are commuted only to move numbers to the front: -@expr{a b 2} is commuted to @expr{2 a b}. - -The product @expr{a (b + c)} is distributed over the sum only if -@expr{a} and at least one of @expr{b} and @expr{c} are numbers: -@expr{2 (x + 3)} goes to @expr{2 x + 6}. The formula -@expr{(-a) (b - c)}, where @expr{-a} is a negative number, is -rewritten to @expr{a (c - b)}. - -The distributive law of products and powers is used for adjacent -terms of the product: @expr{x^a x^b} goes to -@texline @math{x^{a+b}} -@infoline @expr{x^(a+b)} -where @expr{a} is a number, or an implicit 1 (as in @expr{x}), -or the implicit one-half of @expr{@tfn{sqrt}(x)}, and similarly for -@expr{b}. The result is written using @samp{sqrt} or @samp{1/sqrt} -if the sum of the powers is @expr{1/2} or @expr{-1/2}, respectively. -If the sum of the powers is zero, the product is simplified to -@expr{1} or to @samp{idn(1)} if Matrix mode is enabled. - -The product of a negative power times anything but another negative -power is changed to use division: -@texline @math{x^{-2} y} -@infoline @expr{x^(-2) y} -goes to @expr{y / x^2} unless Matrix mode is -in effect and neither @expr{x} nor @expr{y} are scalar (in which -case it is considered unsafe to rearrange the order of the terms). - -Finally, @expr{a (b/c)} is rewritten to @expr{(a b)/c}, and also -@expr{(a/b) c} is changed to @expr{(a c)/b} unless in Matrix mode. - -@tex -\bigskip -@end tex - -Simplifications for quotients are analogous to those for products. -The quotient @expr{0 / x} is simplified to @expr{0}, with the same -exceptions that were noted for @expr{0 x}. Likewise, @expr{x / 1} -and @expr{x / (-1)} are simplified to @expr{x} and @expr{-x}, -respectively. - -The quotient @expr{x / 0} is left unsimplified or changed to an -infinite quantity, as directed by the current infinite mode. -@xref{Infinite Mode}. - -The expression -@texline @math{a / b^{-c}} -@infoline @expr{a / b^(-c)} -is changed to @expr{a b^c}, where @expr{-c} is any negative-looking -power. Also, @expr{1 / b^c} is changed to -@texline @math{b^{-c}} -@infoline @expr{b^(-c)} -for any power @expr{c}. - -Also, @expr{(-a) / b} and @expr{a / (-b)} go to @expr{-(a/b)}; -@expr{(a/b) / c} goes to @expr{a / (b c)}; and @expr{a / (b/c)} -goes to @expr{(a c) / b} unless Matrix mode prevents this -rearrangement. Similarly, @expr{a / (b:c)} is simplified to -@expr{(c:b) a} for any fraction @expr{b:c}. - -The distributive law is applied to @expr{(a + b) / c} only if -@expr{c} and at least one of @expr{a} and @expr{b} are numbers. -Quotients of powers and square roots are distributed just as -described for multiplication. - -Quotients of products cancel only in the leading terms of the -numerator and denominator. In other words, @expr{a x b / a y b} -is cancelled to @expr{x b / y b} but not to @expr{x / y}. Once -again this is because full cancellation can be slow; use @kbd{a s} -to cancel all terms of the quotient. - -Quotients of negative-looking values are simplified according -to @expr{(-a) / (-b)} to @expr{a / b}, @expr{(-a) / (b - c)} -to @expr{a / (c - b)}, and @expr{(a - b) / (-c)} to @expr{(b - a) / c}. - -@tex -\bigskip -@end tex - -The formula @expr{x^0} is simplified to @expr{1}, or to @samp{idn(1)} -in Matrix mode. The formula @expr{0^x} is simplified to @expr{0} -unless @expr{x} is a negative number, complex number or zero. -If @expr{x} is negative, complex or @expr{0.0}, @expr{0^x} is an -infinity or an unsimplified formula according to the current infinite -mode. The expression @expr{0^0} is simplified to @expr{1}. - -Powers of products or quotients @expr{(a b)^c}, @expr{(a/b)^c} -are distributed to @expr{a^c b^c}, @expr{a^c / b^c} only if @expr{c} -is an integer, or if either @expr{a} or @expr{b} are nonnegative -real numbers. Powers of powers @expr{(a^b)^c} are simplified to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -only when @expr{c} is an integer and @expr{b c} also -evaluates to an integer. Without these restrictions these simplifications -would not be safe because of problems with principal values. -(In other words, -@texline @math{((-3)^{1/2})^2} -@infoline @expr{((-3)^1:2)^2} -is safe to simplify, but -@texline @math{((-3)^2)^{1/2}} -@infoline @expr{((-3)^2)^1:2} -is not.) @xref{Declarations}, for ways to inform Calc that your -variables satisfy these requirements. - -As a special case of this rule, @expr{@tfn{sqrt}(x)^n} is simplified to -@texline @math{x^{n/2}} -@infoline @expr{x^(n/2)} -only for even integers @expr{n}. - -If @expr{a} is known to be real, @expr{b} is an even integer, and -@expr{c} is a half- or quarter-integer, then @expr{(a^b)^c} is -simplified to @expr{@tfn{abs}(a^(b c))}. - -Also, @expr{(-a)^b} is simplified to @expr{a^b} if @expr{b} is an -even integer, or to @expr{-(a^b)} if @expr{b} is an odd integer, -for any negative-looking expression @expr{-a}. - -Square roots @expr{@tfn{sqrt}(x)} generally act like one-half powers -@texline @math{x^{1:2}} -@infoline @expr{x^1:2} -for the purposes of the above-listed simplifications. - -Also, note that -@texline @math{1 / x^{1:2}} -@infoline @expr{1 / x^1:2} -is changed to -@texline @math{x^{-1:2}}, -@infoline @expr{x^(-1:2)}, -but @expr{1 / @tfn{sqrt}(x)} is left alone. - -@tex -\bigskip -@end tex - -Generic identity matrices (@pxref{Matrix Mode}) are simplified by the -following rules: @expr{@tfn{idn}(a) + b} to @expr{a + b} if @expr{b} -is provably scalar, or expanded out if @expr{b} is a matrix; -@expr{@tfn{idn}(a) + @tfn{idn}(b)} to @expr{@tfn{idn}(a + b)}; -@expr{-@tfn{idn}(a)} to @expr{@tfn{idn}(-a)}; @expr{a @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)} if @expr{a} is provably scalar, or to @expr{a b} -if @expr{a} is provably non-scalar; @expr{@tfn{idn}(a) @tfn{idn}(b)} to -@expr{@tfn{idn}(a b)}; analogous simplifications for quotients involving -@code{idn}; and @expr{@tfn{idn}(a)^n} to @expr{@tfn{idn}(a^n)} where -@expr{n} is an integer. - -@tex -\bigskip -@end tex - -The @code{floor} function and other integer truncation functions -vanish if the argument is provably integer-valued, so that -@expr{@tfn{floor}(@tfn{round}(x))} simplifies to @expr{@tfn{round}(x)}. -Also, combinations of @code{float}, @code{floor} and its friends, -and @code{ffloor} and its friends, are simplified in appropriate -ways. @xref{Integer Truncation}. - -The expression @expr{@tfn{abs}(-x)} changes to @expr{@tfn{abs}(x)}. -The expression @expr{@tfn{abs}(@tfn{abs}(x))} changes to -@expr{@tfn{abs}(x)}; in fact, @expr{@tfn{abs}(x)} changes to @expr{x} or -@expr{-x} if @expr{x} is provably nonnegative or nonpositive -(@pxref{Declarations}). - -While most functions do not recognize the variable @code{i} as an -imaginary number, the @code{arg} function does handle the two cases -@expr{@tfn{arg}(@tfn{i})} and @expr{@tfn{arg}(-@tfn{i})} just for convenience. - -The expression @expr{@tfn{conj}(@tfn{conj}(x))} simplifies to @expr{x}. -Various other expressions involving @code{conj}, @code{re}, and -@code{im} are simplified, especially if some of the arguments are -provably real or involve the constant @code{i}. For example, -@expr{@tfn{conj}(a + b i)} is changed to -@expr{@tfn{conj}(a) - @tfn{conj}(b) i}, or to @expr{a - b i} if @expr{a} -and @expr{b} are known to be real. - -Functions like @code{sin} and @code{arctan} generally don't have -any default simplifications beyond simply evaluating the functions -for suitable numeric arguments and infinity. The @kbd{a s} command -described in the next section does provide some simplifications for -these functions, though. - -One important simplification that does occur is that -@expr{@tfn{ln}(@tfn{e})} is simplified to 1, and @expr{@tfn{ln}(@tfn{e}^x)} is -simplified to @expr{x} for any @expr{x}. This occurs even if you have -stored a different value in the Calc variable @samp{e}; but this would -be a bad idea in any case if you were also using natural logarithms! - -Among the logical functions, @tfn{!(@var{a} <= @var{b})} changes to -@tfn{@var{a} > @var{b}} and so on. Equations and inequalities where both sides -are either negative-looking or zero are simplified by negating both sides -and reversing the inequality. While it might seem reasonable to simplify -@expr{!!x} to @expr{x}, this would not be valid in general because -@expr{!!2} is 1, not 2. - -Most other Calc functions have few if any default simplifications -defined, aside of course from evaluation when the arguments are -suitable numbers. - -@node Algebraic Simplifications, Unsafe Simplifications, Default Simplifications, Simplifying Formulas -@subsection Algebraic Simplifications - -@noindent -@cindex Algebraic simplifications -The @kbd{a s} command makes simplifications that may be too slow to -do all the time, or that may not be desirable all of the time. -If you find these simplifications are worthwhile, you can type -@kbd{m A} to have Calc apply them automatically. - -This section describes all simplifications that are performed by -the @kbd{a s} command. Note that these occur in addition to the -default simplifications; even if the default simplifications have -been turned off by an @kbd{m O} command, @kbd{a s} will turn them -back on temporarily while it simplifies the formula. - -There is a variable, @code{AlgSimpRules}, in which you can put rewrites -to be applied by @kbd{a s}. Its use is analogous to @code{EvalRules}, -but without the special restrictions. Basically, the simplifier does -@samp{@w{a r} AlgSimpRules} with an infinite repeat count on the whole -expression being simplified, then it traverses the expression applying -the built-in rules described below. If the result is different from -the original expression, the process repeats with the default -simplifications (including @code{EvalRules}), then @code{AlgSimpRules}, -then the built-in simplifications, and so on. - -@tex -\bigskip -@end tex - -Sums are simplified in two ways. Constant terms are commuted to the -end of the sum, so that @expr{a + 2 + b} changes to @expr{a + b + 2}. -The only exception is that a constant will not be commuted away -from the first position of a difference, i.e., @expr{2 - x} is not -commuted to @expr{-x + 2}. - -Also, terms of sums are combined by the distributive law, as in -@expr{x + y + 2 x} to @expr{y + 3 x}. This always occurs for -adjacent terms, but @kbd{a s} compares all pairs of terms including -non-adjacent ones. - -@tex -\bigskip -@end tex - -Products are sorted into a canonical order using the commutative -law. For example, @expr{b c a} is commuted to @expr{a b c}. -This allows easier comparison of products; for example, the default -simplifications will not change @expr{x y + y x} to @expr{2 x y}, -but @kbd{a s} will; it first rewrites the sum to @expr{x y + x y}, -and then the default simplifications are able to recognize a sum -of identical terms. - -The canonical ordering used to sort terms of products has the -property that real-valued numbers, interval forms and infinities -come first, and are sorted into increasing order. The @kbd{V S} -command uses the same ordering when sorting a vector. - -Sorting of terms of products is inhibited when Matrix mode is -turned on; in this case, Calc will never exchange the order of -two terms unless it knows at least one of the terms is a scalar. - -Products of powers are distributed by comparing all pairs of -terms, using the same method that the default simplifications -use for adjacent terms of products. - -Even though sums are not sorted, the commutative law is still -taken into account when terms of a product are being compared. -Thus @expr{(x + y) (y + x)} will be simplified to @expr{(x + y)^2}. -A subtle point is that @expr{(x - y) (y - x)} will @emph{not} -be simplified to @expr{-(x - y)^2}; Calc does not notice that -one term can be written as a constant times the other, even if -that constant is @mathit{-1}. - -A fraction times any expression, @expr{(a:b) x}, is changed to -a quotient involving integers: @expr{a x / b}. This is not -done for floating-point numbers like @expr{0.5}, however. This -is one reason why you may find it convenient to turn Fraction mode -on while doing algebra; @pxref{Fraction Mode}. - -@tex -\bigskip -@end tex - -Quotients are simplified by comparing all terms in the numerator -with all terms in the denominator for possible cancellation using -the distributive law. For example, @expr{a x^2 b / c x^3 d} will -cancel @expr{x^2} from the top and bottom to get @expr{a b / c x d}. -(The terms in the denominator will then be rearranged to @expr{c d x} -as described above.) If there is any common integer or fractional -factor in the numerator and denominator, it is cancelled out; -for example, @expr{(4 x + 6) / 8 x} simplifies to @expr{(2 x + 3) / 4 x}. - -Non-constant common factors are not found even by @kbd{a s}. To -cancel the factor @expr{a} in @expr{(a x + a) / a^2} you could first -use @kbd{j M} on the product @expr{a x} to Merge the numerator to -@expr{a (1+x)}, which can then be simplified successfully. - -@tex -\bigskip -@end tex - -Integer powers of the variable @code{i} are simplified according -to the identity @expr{i^2 = -1}. If you store a new value other -than the complex number @expr{(0,1)} in @code{i}, this simplification -will no longer occur. This is done by @kbd{a s} instead of by default -in case someone (unwisely) uses the name @code{i} for a variable -unrelated to complex numbers; it would be unfortunate if Calc -quietly and automatically changed this formula for reasons the -user might not have been thinking of. - -Square roots of integer or rational arguments are simplified in -several ways. (Note that these will be left unevaluated only in -Symbolic mode.) First, square integer or rational factors are -pulled out so that @expr{@tfn{sqrt}(8)} is rewritten as -@texline @math{2\,@tfn{sqrt}(2)}. -@infoline @expr{2 sqrt(2)}. -Conceptually speaking this implies factoring the argument into primes -and moving pairs of primes out of the square root, but for reasons of -efficiency Calc only looks for primes up to 29. - -Square roots in the denominator of a quotient are moved to the -numerator: @expr{1 / @tfn{sqrt}(3)} changes to @expr{@tfn{sqrt}(3) / 3}. -The same effect occurs for the square root of a fraction: -@expr{@tfn{sqrt}(2:3)} changes to @expr{@tfn{sqrt}(6) / 3}. - -@tex -\bigskip -@end tex - -The @code{%} (modulo) operator is simplified in several ways -when the modulus @expr{M} is a positive real number. First, if -the argument is of the form @expr{x + n} for some real number -@expr{n}, then @expr{n} is itself reduced modulo @expr{M}. For -example, @samp{(x - 23) % 10} is simplified to @samp{(x + 7) % 10}. - -If the argument is multiplied by a constant, and this constant -has a common integer divisor with the modulus, then this factor is -cancelled out. For example, @samp{12 x % 15} is changed to -@samp{3 (4 x % 5)} by factoring out 3. Also, @samp{(12 x + 1) % 15} -is changed to @samp{3 ((4 x + 1:3) % 5)}. While these forms may -not seem ``simpler,'' they allow Calc to discover useful information -about modulo forms in the presence of declarations. - -If the modulus is 1, then Calc can use @code{int} declarations to -evaluate the expression. For example, the idiom @samp{x % 2} is -often used to check whether a number is odd or even. As described -above, @w{@samp{2 n % 2}} and @samp{(2 n + 1) % 2} are simplified to -@samp{2 (n % 1)} and @samp{2 ((n + 1:2) % 1)}, respectively; Calc -can simplify these to 0 and 1 (respectively) if @code{n} has been -declared to be an integer. - -@tex -\bigskip -@end tex - -Trigonometric functions are simplified in several ways. Whenever a -products of two trigonometric functions can be replaced by a single -function, the replacement is made; for example, -@expr{@tfn{tan}(x) @tfn{cos}(x)} is simplified to @expr{@tfn{sin}(x)}. -Reciprocals of trigonometric functions are replaced by their reciprocal -function; for example, @expr{1/@tfn{sec}(x)} is simplified to -@expr{@tfn{cos}(x)}. The corresponding simplifications for the -hyperbolic functions are also handled. - -Trigonometric functions of their inverse functions are -simplified. The expression @expr{@tfn{sin}(@tfn{arcsin}(x))} is -simplified to @expr{x}, and similarly for @code{cos} and @code{tan}. -Trigonometric functions of inverses of different trigonometric -functions can also be simplified, as in @expr{@tfn{sin}(@tfn{arccos}(x))} -to @expr{@tfn{sqrt}(1 - x^2)}. - -If the argument to @code{sin} is negative-looking, it is simplified to -@expr{-@tfn{sin}(x)}, and similarly for @code{cos} and @code{tan}. -Finally, certain special values of the argument are recognized; -@pxref{Trigonometric and Hyperbolic Functions}. - -Hyperbolic functions of their inverses and of negative-looking -arguments are also handled, as are exponentials of inverse -hyperbolic functions. - -No simplifications for inverse trigonometric and hyperbolic -functions are known, except for negative arguments of @code{arcsin}, -@code{arctan}, @code{arcsinh}, and @code{arctanh}. Note that -@expr{@tfn{arcsin}(@tfn{sin}(x))} can @emph{not} safely change to -@expr{x}, since this only correct within an integer multiple of -@texline @math{2 \pi} -@infoline @expr{2 pi} -radians or 360 degrees. However, @expr{@tfn{arcsinh}(@tfn{sinh}(x))} is -simplified to @expr{x} if @expr{x} is known to be real. - -Several simplifications that apply to logarithms and exponentials -are that @expr{@tfn{exp}(@tfn{ln}(x))}, -@texline @tfn{e}@math{^{\ln(x)}}, -@infoline @expr{e^@tfn{ln}(x)}, -and -@texline @math{10^{{\rm log10}(x)}} -@infoline @expr{10^@tfn{log10}(x)} -all reduce to @expr{x}. Also, @expr{@tfn{ln}(@tfn{exp}(x))}, etc., can -reduce to @expr{x} if @expr{x} is provably real. The form -@expr{@tfn{exp}(x)^y} is simplified to @expr{@tfn{exp}(x y)}. If @expr{x} -is a suitable multiple of -@texline @math{\pi i} -@infoline @expr{pi i} -(as described above for the trigonometric functions), then -@expr{@tfn{exp}(x)} or @expr{e^x} will be expanded. Finally, -@expr{@tfn{ln}(x)} is simplified to a form involving @code{pi} and -@code{i} where @expr{x} is provably negative, positive imaginary, or -negative imaginary. - -The error functions @code{erf} and @code{erfc} are simplified when -their arguments are negative-looking or are calls to the @code{conj} -function. - -@tex -\bigskip -@end tex - -Equations and inequalities are simplified by cancelling factors -of products, quotients, or sums on both sides. Inequalities -change sign if a negative multiplicative factor is cancelled. -Non-constant multiplicative factors as in @expr{a b = a c} are -cancelled from equations only if they are provably nonzero (generally -because they were declared so; @pxref{Declarations}). Factors -are cancelled from inequalities only if they are nonzero and their -sign is known. - -Simplification also replaces an equation or inequality with -1 or 0 (``true'' or ``false'') if it can through the use of -declarations. If @expr{x} is declared to be an integer greater -than 5, then @expr{x < 3}, @expr{x = 3}, and @expr{x = 7.5} are -all simplified to 0, but @expr{x > 3} is simplified to 1. -By a similar analysis, @expr{abs(x) >= 0} is simplified to 1, -as is @expr{x^2 >= 0} if @expr{x} is known to be real. - -@node Unsafe Simplifications, Simplification of Units, Algebraic Simplifications, Simplifying Formulas -@subsection ``Unsafe'' Simplifications - -@noindent -@cindex Unsafe simplifications -@cindex Extended simplification -@kindex a e -@pindex calc-simplify-extended -@ignore -@mindex esimpl@idots -@end ignore -@tindex esimplify -The @kbd{a e} (@code{calc-simplify-extended}) [@code{esimplify}] command -is like @kbd{a s} -except that it applies some additional simplifications which are not -``safe'' in all cases. Use this only if you know the values in your -formula lie in the restricted ranges for which these simplifications -are valid. The symbolic integrator uses @kbd{a e}; -one effect of this is that the integrator's results must be used with -caution. Where an integral table will often attach conditions like -``for positive @expr{a} only,'' Calc (like most other symbolic -integration programs) will simply produce an unqualified result. - -Because @kbd{a e}'s simplifications are unsafe, it is sometimes better -to type @kbd{C-u -3 a v}, which does extended simplification only -on the top level of the formula without affecting the sub-formulas. -In fact, @kbd{C-u -3 j v} allows you to target extended simplification -to any specific part of a formula. - -The variable @code{ExtSimpRules} contains rewrites to be applied by -the @kbd{a e} command. These are applied in addition to -@code{EvalRules} and @code{AlgSimpRules}. (The @kbd{a r AlgSimpRules} -step described above is simply followed by an @kbd{a r ExtSimpRules} step.) - -Following is a complete list of ``unsafe'' simplifications performed -by @kbd{a e}. - -@tex -\bigskip -@end tex - -Inverse trigonometric or hyperbolic functions, called with their -corresponding non-inverse functions as arguments, are simplified -by @kbd{a e}. For example, @expr{@tfn{arcsin}(@tfn{sin}(x))} changes -to @expr{x}. Also, @expr{@tfn{arcsin}(@tfn{cos}(x))} and -@expr{@tfn{arccos}(@tfn{sin}(x))} both change to @expr{@tfn{pi}/2 - x}. -These simplifications are unsafe because they are valid only for -values of @expr{x} in a certain range; outside that range, values -are folded down to the 360-degree range that the inverse trigonometric -functions always produce. - -Powers of powers @expr{(x^a)^b} are simplified to -@texline @math{x^{a b}} -@infoline @expr{x^(a b)} -for all @expr{a} and @expr{b}. These results will be valid only -in a restricted range of @expr{x}; for example, in -@texline @math{(x^2)^{1:2}} -@infoline @expr{(x^2)^1:2} -the powers cancel to get @expr{x}, which is valid for positive values -of @expr{x} but not for negative or complex values. - -Similarly, @expr{@tfn{sqrt}(x^a)} and @expr{@tfn{sqrt}(x)^a} are both -simplified (possibly unsafely) to -@texline @math{x^{a/2}}. -@infoline @expr{x^(a/2)}. - -Forms like @expr{@tfn{sqrt}(1 - sin(x)^2)} are simplified to, e.g., -@expr{@tfn{cos}(x)}. Calc has identities of this sort for @code{sin}, -@code{cos}, @code{tan}, @code{sinh}, and @code{cosh}. - -Arguments of square roots are partially factored to look for -squared terms that can be extracted. For example, -@expr{@tfn{sqrt}(a^2 b^3 + a^3 b^2)} simplifies to -@expr{a b @tfn{sqrt}(a+b)}. - -The simplifications of @expr{@tfn{ln}(@tfn{exp}(x))}, -@expr{@tfn{ln}(@tfn{e}^x)}, and @expr{@tfn{log10}(10^x)} to @expr{x} are also -unsafe because of problems with principal values (although these -simplifications are safe if @expr{x} is known to be real). - -Common factors are cancelled from products on both sides of an -equation, even if those factors may be zero: @expr{a x / b x} -to @expr{a / b}. Such factors are never cancelled from -inequalities: Even @kbd{a e} is not bold enough to reduce -@expr{a x < b x} to @expr{a < b} (or @expr{a > b}, depending -on whether you believe @expr{x} is positive or negative). -The @kbd{a M /} command can be used to divide a factor out of -both sides of an inequality. - -@node Simplification of Units, , Unsafe Simplifications, Simplifying Formulas -@subsection Simplification of Units - -@noindent -The simplifications described in this section are applied by the -@kbd{u s} (@code{calc-simplify-units}) command. These are in addition -to the regular @kbd{a s} (but not @kbd{a e}) simplifications described -earlier. @xref{Basic Operations on Units}. - -The variable @code{UnitSimpRules} contains rewrites to be applied by -the @kbd{u s} command. These are applied in addition to @code{EvalRules} -and @code{AlgSimpRules}. - -Scalar mode is automatically put into effect when simplifying units. -@xref{Matrix Mode}. - -Sums @expr{a + b} involving units are simplified by extracting the -units of @expr{a} as if by the @kbd{u x} command (call the result -@expr{u_a}), then simplifying the expression @expr{b / u_a} -using @kbd{u b} and @kbd{u s}. If the result has units then the sum -is inconsistent and is left alone. Otherwise, it is rewritten -in terms of the units @expr{u_a}. - -If units auto-ranging mode is enabled, products or quotients in -which the first argument is a number which is out of range for the -leading unit are modified accordingly. - -When cancelling and combining units in products and quotients, -Calc accounts for unit names that differ only in the prefix letter. -For example, @samp{2 km m} is simplified to @samp{2000 m^2}. -However, compatible but different units like @code{ft} and @code{in} -are not combined in this way. - -Quotients @expr{a / b} are simplified in three additional ways. First, -if @expr{b} is a number or a product beginning with a number, Calc -computes the reciprocal of this number and moves it to the numerator. - -Second, for each pair of unit names from the numerator and denominator -of a quotient, if the units are compatible (e.g., they are both -units of area) then they are replaced by the ratio between those -units. For example, in @samp{3 s in N / kg cm} the units -@samp{in / cm} will be replaced by @expr{2.54}. - -Third, if the units in the quotient exactly cancel out, so that -a @kbd{u b} command on the quotient would produce a dimensionless -number for an answer, then the quotient simplifies to that number. - -For powers and square roots, the ``unsafe'' simplifications -@expr{(a b)^c} to @expr{a^c b^c}, @expr{(a/b)^c} to @expr{a^c / b^c}, -and @expr{(a^b)^c} to -@texline @math{a^{b c}} -@infoline @expr{a^(b c)} -are done if the powers are real numbers. (These are safe in the context -of units because all numbers involved can reasonably be assumed to be -real.) - -Also, if a unit name is raised to a fractional power, and the -base units in that unit name all occur to powers which are a -multiple of the denominator of the power, then the unit name -is expanded out into its base units, which can then be simplified -according to the previous paragraph. For example, @samp{acre^1.5} -is simplified by noting that @expr{1.5 = 3:2}, that @samp{acre} -is defined in terms of @samp{m^2}, and that the 2 in the power of -@code{m} is a multiple of 2 in @expr{3:2}. Thus, @code{acre^1.5} is -replaced by approximately -@texline @math{(4046 m^2)^{1.5}} -@infoline @expr{(4046 m^2)^1.5}, -which is then changed to -@texline @math{4046^{1.5} \, (m^2)^{1.5}}, -@infoline @expr{4046^1.5 (m^2)^1.5}, -then to @expr{257440 m^3}. - -The functions @code{float}, @code{frac}, @code{clean}, @code{abs}, -as well as @code{floor} and the other integer truncation functions, -applied to unit names or products or quotients involving units, are -simplified. For example, @samp{round(1.6 in)} is changed to -@samp{round(1.6) round(in)}; the lefthand term evaluates to 2, -and the righthand term simplifies to @code{in}. - -The functions @code{sin}, @code{cos}, and @code{tan} with arguments -that have angular units like @code{rad} or @code{arcmin} are -simplified by converting to base units (radians), then evaluating -with the angular mode temporarily set to radians. - -@node Polynomials, Calculus, Simplifying Formulas, Algebra -@section Polynomials - -A @dfn{polynomial} is a sum of terms which are coefficients times -various powers of a ``base'' variable. For example, @expr{2 x^2 + 3 x - 4} -is a polynomial in @expr{x}. Some formulas can be considered -polynomials in several different variables: @expr{1 + 2 x + 3 y + 4 x y^2} -is a polynomial in both @expr{x} and @expr{y}. Polynomial coefficients -are often numbers, but they may in general be any formulas not -involving the base variable. - -@kindex a f -@pindex calc-factor -@tindex factor -The @kbd{a f} (@code{calc-factor}) [@code{factor}] command factors a -polynomial into a product of terms. For example, the polynomial -@expr{x^3 + 2 x^2 + x} is factored into @samp{x*(x+1)^2}. As another -example, @expr{a c + b d + b c + a d} is factored into the product -@expr{(a + b) (c + d)}. - -Calc currently has three algorithms for factoring. Formulas which are -linear in several variables, such as the second example above, are -merged according to the distributive law. Formulas which are -polynomials in a single variable, with constant integer or fractional -coefficients, are factored into irreducible linear and/or quadratic -terms. The first example above factors into three linear terms -(@expr{x}, @expr{x+1}, and @expr{x+1} again). Finally, formulas -which do not fit the above criteria are handled by the algebraic -rewrite mechanism. - -Calc's polynomial factorization algorithm works by using the general -root-finding command (@w{@kbd{a P}}) to solve for the roots of the -polynomial. It then looks for roots which are rational numbers -or complex-conjugate pairs, and converts these into linear and -quadratic terms, respectively. Because it uses floating-point -arithmetic, it may be unable to find terms that involve large -integers (whose number of digits approaches the current precision). -Also, irreducible factors of degree higher than quadratic are not -found, and polynomials in more than one variable are not treated. -(A more robust factorization algorithm may be included in a future -version of Calc.) - -@vindex FactorRules -@ignore -@starindex -@end ignore -@tindex thecoefs -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex thefactors -The rewrite-based factorization method uses rules stored in the variable -@code{FactorRules}. @xref{Rewrite Rules}, for a discussion of the -operation of rewrite rules. The default @code{FactorRules} are able -to factor quadratic forms symbolically into two linear terms, -@expr{(a x + b) (c x + d)}. You can edit these rules to include other -cases if you wish. To use the rules, Calc builds the formula -@samp{thecoefs(x, [a, b, c, ...])} where @code{x} is the polynomial -base variable and @code{a}, @code{b}, etc., are polynomial coefficients -(which may be numbers or formulas). The constant term is written first, -i.e., in the @code{a} position. When the rules complete, they should have -changed the formula into the form @samp{thefactors(x, [f1, f2, f3, ...])} -where each @code{fi} should be a factored term, e.g., @samp{x - ai}. -Calc then multiplies these terms together to get the complete -factored form of the polynomial. If the rules do not change the -@code{thecoefs} call to a @code{thefactors} call, @kbd{a f} leaves the -polynomial alone on the assumption that it is unfactorable. (Note that -the function names @code{thecoefs} and @code{thefactors} are used only -as placeholders; there are no actual Calc functions by those names.) - -@kindex H a f -@tindex factors -The @kbd{H a f} [@code{factors}] command also factors a polynomial, -but it returns a list of factors instead of an expression which is the -product of the factors. Each factor is represented by a sub-vector -of the factor, and the power with which it appears. For example, -@expr{x^5 + x^4 - 33 x^3 + 63 x^2} factors to @expr{(x + 7) x^2 (x - 3)^2} -in @kbd{a f}, or to @expr{[ [x, 2], [x+7, 1], [x-3, 2] ]} in @kbd{H a f}. -If there is an overall numeric factor, it always comes first in the list. -The functions @code{factor} and @code{factors} allow a second argument -when written in algebraic form; @samp{factor(x,v)} factors @expr{x} with -respect to the specific variable @expr{v}. The default is to factor with -respect to all the variables that appear in @expr{x}. - -@kindex a c -@pindex calc-collect -@tindex collect -The @kbd{a c} (@code{calc-collect}) [@code{collect}] command rearranges a -formula as a -polynomial in a given variable, ordered in decreasing powers of that -variable. For example, given @expr{1 + 2 x + 3 y + 4 x y^2} on -the stack, @kbd{a c x} would produce @expr{(2 + 4 y^2) x + (1 + 3 y)}, -and @kbd{a c y} would produce @expr{(4 x) y^2 + 3 y + (1 + 2 x)}. -The polynomial will be expanded out using the distributive law as -necessary: Collecting @expr{x} in @expr{(x - 1)^3} produces -@expr{x^3 - 3 x^2 + 3 x - 1}. Terms not involving @expr{x} will -not be expanded. - -The ``variable'' you specify at the prompt can actually be any -expression: @kbd{a c ln(x+1)} will collect together all terms multiplied -by @samp{ln(x+1)} or integer powers thereof. If @samp{x} also appears -in the formula in a context other than @samp{ln(x+1)}, @kbd{a c} will -treat those occurrences as unrelated to @samp{ln(x+1)}, i.e., as constants. - -@kindex a x -@pindex calc-expand -@tindex expand -The @kbd{a x} (@code{calc-expand}) [@code{expand}] command expands an -expression by applying the distributive law everywhere. It applies to -products, quotients, and powers involving sums. By default, it fully -distributes all parts of the expression. With a numeric prefix argument, -the distributive law is applied only the specified number of times, then -the partially expanded expression is left on the stack. - -The @kbd{a x} and @kbd{j D} commands are somewhat redundant. Use -@kbd{a x} if you want to expand all products of sums in your formula. -Use @kbd{j D} if you want to expand a particular specified term of -the formula. There is an exactly analogous correspondence between -@kbd{a f} and @kbd{j M}. (The @kbd{j D} and @kbd{j M} commands -also know many other kinds of expansions, such as -@samp{exp(a + b) = exp(a) exp(b)}, which @kbd{a x} and @kbd{a f} -do not do.) - -Calc's automatic simplifications will sometimes reverse a partial -expansion. For example, the first step in expanding @expr{(x+1)^3} is -to write @expr{(x+1) (x+1)^2}. If @kbd{a x} stops there and tries -to put this formula onto the stack, though, Calc will automatically -simplify it back to @expr{(x+1)^3} form. The solution is to turn -simplification off first (@pxref{Simplification Modes}), or to run -@kbd{a x} without a numeric prefix argument so that it expands all -the way in one step. - -@kindex a a -@pindex calc-apart -@tindex apart -The @kbd{a a} (@code{calc-apart}) [@code{apart}] command expands a -rational function by partial fractions. A rational function is the -quotient of two polynomials; @code{apart} pulls this apart into a -sum of rational functions with simple denominators. In algebraic -notation, the @code{apart} function allows a second argument that -specifies which variable to use as the ``base''; by default, Calc -chooses the base variable automatically. - -@kindex a n -@pindex calc-normalize-rat -@tindex nrat -The @kbd{a n} (@code{calc-normalize-rat}) [@code{nrat}] command -attempts to arrange a formula into a quotient of two polynomials. -For example, given @expr{1 + (a + b/c) / d}, the result would be -@expr{(b + a c + c d) / c d}. The quotient is reduced, so that -@kbd{a n} will simplify @expr{(x^2 + 2x + 1) / (x^2 - 1)} by dividing -out the common factor @expr{x + 1}, yielding @expr{(x + 1) / (x - 1)}. - -@kindex a \ -@pindex calc-poly-div -@tindex pdiv -The @kbd{a \} (@code{calc-poly-div}) [@code{pdiv}] command divides -two polynomials @expr{u} and @expr{v}, yielding a new polynomial -@expr{q}. If several variables occur in the inputs, the inputs are -considered multivariate polynomials. (Calc divides by the variable -with the largest power in @expr{u} first, or, in the case of equal -powers, chooses the variables in alphabetical order.) For example, -dividing @expr{x^2 + 3 x + 2} by @expr{x + 2} yields @expr{x + 1}. -The remainder from the division, if any, is reported at the bottom -of the screen and is also placed in the Trail along with the quotient. - -Using @code{pdiv} in algebraic notation, you can specify the particular -variable to be used as the base: @code{pdiv(@var{a},@var{b},@var{x})}. -If @code{pdiv} is given only two arguments (as is always the case with -the @kbd{a \} command), then it does a multivariate division as outlined -above. - -@kindex a % -@pindex calc-poly-rem -@tindex prem -The @kbd{a %} (@code{calc-poly-rem}) [@code{prem}] command divides -two polynomials and keeps the remainder @expr{r}. The quotient -@expr{q} is discarded. For any formulas @expr{a} and @expr{b}, the -results of @kbd{a \} and @kbd{a %} satisfy @expr{a = q b + r}. -(This is analogous to plain @kbd{\} and @kbd{%}, which compute the -integer quotient and remainder from dividing two numbers.) - -@kindex a / -@kindex H a / -@pindex calc-poly-div-rem -@tindex pdivrem -@tindex pdivide -The @kbd{a /} (@code{calc-poly-div-rem}) [@code{pdivrem}] command -divides two polynomials and reports both the quotient and the -remainder as a vector @expr{[q, r]}. The @kbd{H a /} [@code{pdivide}] -command divides two polynomials and constructs the formula -@expr{q + r/b} on the stack. (Naturally if the remainder is zero, -this will immediately simplify to @expr{q}.) - -@kindex a g -@pindex calc-poly-gcd -@tindex pgcd -The @kbd{a g} (@code{calc-poly-gcd}) [@code{pgcd}] command computes -the greatest common divisor of two polynomials. (The GCD actually -is unique only to within a constant multiplier; Calc attempts to -choose a GCD which will be unsurprising.) For example, the @kbd{a n} -command uses @kbd{a g} to take the GCD of the numerator and denominator -of a quotient, then divides each by the result using @kbd{a \}. (The -definition of GCD ensures that this division can take place without -leaving a remainder.) - -While the polynomials used in operations like @kbd{a /} and @kbd{a g} -often have integer coefficients, this is not required. Calc can also -deal with polynomials over the rationals or floating-point reals. -Polynomials with modulo-form coefficients are also useful in many -applications; if you enter @samp{(x^2 + 3 x - 1) mod 5}, Calc -automatically transforms this into a polynomial over the field of -integers mod 5: @samp{(1 mod 5) x^2 + (3 mod 5) x + (4 mod 5)}. - -Congratulations and thanks go to Ove Ewerlid -(@code{ewerlid@@mizar.DoCS.UU.SE}), who contributed many of the -polynomial routines used in the above commands. - -@xref{Decomposing Polynomials}, for several useful functions for -extracting the individual coefficients of a polynomial. - -@node Calculus, Solving Equations, Polynomials, Algebra -@section Calculus - -@noindent -The following calculus commands do not automatically simplify their -inputs or outputs using @code{calc-simplify}. You may find it helps -to do this by hand by typing @kbd{a s} or @kbd{a e}. It may also help -to use @kbd{a x} and/or @kbd{a c} to arrange a result in the most -readable way. - -@menu -* Differentiation:: -* Integration:: -* Customizing the Integrator:: -* Numerical Integration:: -* Taylor Series:: -@end menu - -@node Differentiation, Integration, Calculus, Calculus -@subsection Differentiation - -@noindent -@kindex a d -@kindex H a d -@pindex calc-derivative -@tindex deriv -@tindex tderiv -The @kbd{a d} (@code{calc-derivative}) [@code{deriv}] command computes -the derivative of the expression on the top of the stack with respect to -some variable, which it will prompt you to enter. Normally, variables -in the formula other than the specified differentiation variable are -considered constant, i.e., @samp{deriv(y,x)} is reduced to zero. With -the Hyperbolic flag, the @code{tderiv} (total derivative) operation is used -instead, in which derivatives of variables are not reduced to zero -unless those variables are known to be ``constant,'' i.e., independent -of any other variables. (The built-in special variables like @code{pi} -are considered constant, as are variables that have been declared -@code{const}; @pxref{Declarations}.) - -With a numeric prefix argument @var{n}, this command computes the -@var{n}th derivative. - -When working with trigonometric functions, it is best to switch to -Radians mode first (with @w{@kbd{m r}}). The derivative of @samp{sin(x)} -in degrees is @samp{(pi/180) cos(x)}, probably not the expected -answer! - -If you use the @code{deriv} function directly in an algebraic formula, -you can write @samp{deriv(f,x,x0)} which represents the derivative -of @expr{f} with respect to @expr{x}, evaluated at the point -@texline @math{x=x_0}. -@infoline @expr{x=x0}. - -If the formula being differentiated contains functions which Calc does -not know, the derivatives of those functions are produced by adding -primes (apostrophe characters). For example, @samp{deriv(f(2x), x)} -produces @samp{2 f'(2 x)}, where the function @code{f'} represents the -derivative of @code{f}. - -For functions you have defined with the @kbd{Z F} command, Calc expands -the functions according to their defining formulas unless you have -also defined @code{f'} suitably. For example, suppose we define -@samp{sinc(x) = sin(x)/x} using @kbd{Z F}. If we then differentiate -the formula @samp{sinc(2 x)}, the formula will be expanded to -@samp{sin(2 x) / (2 x)} and differentiated. However, if we also -define @samp{sinc'(x) = dsinc(x)}, say, then Calc will write the -result as @samp{2 dsinc(2 x)}. @xref{Algebraic Definitions}. - -For multi-argument functions @samp{f(x,y,z)}, the derivative with respect -to the first argument is written @samp{f'(x,y,z)}; derivatives with -respect to the other arguments are @samp{f'2(x,y,z)} and @samp{f'3(x,y,z)}. -Various higher-order derivatives can be formed in the obvious way, e.g., -@samp{f'@var{}'(x)} (the second derivative of @code{f}) or -@samp{f'@var{}'2'3(x,y,z)} (@code{f} differentiated with respect to each -argument once). - -@node Integration, Customizing the Integrator, Differentiation, Calculus -@subsection Integration - -@noindent -@kindex a i -@pindex calc-integral -@tindex integ -The @kbd{a i} (@code{calc-integral}) [@code{integ}] command computes the -indefinite integral of the expression on the top of the stack with -respect to a prompted-for variable. The integrator is not guaranteed to -work for all integrable functions, but it is able to integrate several -large classes of formulas. In particular, any polynomial or rational -function (a polynomial divided by a polynomial) is acceptable. -(Rational functions don't have to be in explicit quotient form, however; -@texline @math{x/(1+x^{-2})} -@infoline @expr{x/(1+x^-2)} -is not strictly a quotient of polynomials, but it is equivalent to -@expr{x^3/(x^2+1)}, which is.) Also, square roots of terms involving -@expr{x} and @expr{x^2} may appear in rational functions being -integrated. Finally, rational functions involving trigonometric or -hyperbolic functions can be integrated. - -With an argument (@kbd{C-u a i}), this command will compute the definite -integral of the expression on top of the stack. In this case, the -command will again prompt for an integration variable, then prompt for a -lower limit and an upper limit. - -@ifnottex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral from @code{a} to @code{b}. -@end ifnottex -@tex -If you use the @code{integ} function directly in an algebraic formula, -you can also write @samp{integ(f,x,v)} which expresses the resulting -indefinite integral in terms of variable @code{v} instead of @code{x}. -With four arguments, @samp{integ(f(x),x,a,b)} represents a definite -integral $\int_a^b f(x) \, dx$. -@end tex - -Please note that the current implementation of Calc's integrator sometimes -produces results that are significantly more complex than they need to -be. For example, the integral Calc finds for -@texline @math{1/(x+\sqrt{x^2+1})} -@infoline @expr{1/(x+sqrt(x^2+1))} -is several times more complicated than the answer Mathematica -returns for the same input, although the two forms are numerically -equivalent. Also, any indefinite integral should be considered to have -an arbitrary constant of integration added to it, although Calc does not -write an explicit constant of integration in its result. For example, -Calc's solution for -@texline @math{1/(1+\tan x)} -@infoline @expr{1/(1+tan(x))} -differs from the solution given in the @emph{CRC Math Tables} by a -constant factor of -@texline @math{\pi i / 2} -@infoline @expr{pi i / 2}, -due to a different choice of constant of integration. - -The Calculator remembers all the integrals it has done. If conditions -change in a way that would invalidate the old integrals, say, a switch -from Degrees to Radians mode, then they will be thrown out. If you -suspect this is not happening when it should, use the -@code{calc-flush-caches} command; @pxref{Caches}. - -@vindex IntegLimit -Calc normally will pursue integration by substitution or integration by -parts up to 3 nested times before abandoning an approach as fruitless. -If the integrator is taking too long, you can lower this limit by storing -a number (like 2) in the variable @code{IntegLimit}. (The @kbd{s I} -command is a convenient way to edit @code{IntegLimit}.) If this variable -has no stored value or does not contain a nonnegative integer, a limit -of 3 is used. The lower this limit is, the greater the chance that Calc -will be unable to integrate a function it could otherwise handle. Raising -this limit allows the Calculator to solve more integrals, though the time -it takes may grow exponentially. You can monitor the integrator's actions -by creating an Emacs buffer called @code{*Trace*}. If such a buffer -exists, the @kbd{a i} command will write a log of its actions there. - -If you want to manipulate integrals in a purely symbolic way, you can -set the integration nesting limit to 0 to prevent all but fast -table-lookup solutions of integrals. You might then wish to define -rewrite rules for integration by parts, various kinds of substitutions, -and so on. @xref{Rewrite Rules}. - -@node Customizing the Integrator, Numerical Integration, Integration, Calculus -@subsection Customizing the Integrator - -@noindent -@vindex IntegRules -Calc has two built-in rewrite rules called @code{IntegRules} and -@code{IntegAfterRules} which you can edit to define new integration -methods. @xref{Rewrite Rules}. At each step of the integration process, -Calc wraps the current integrand in a call to the fictitious function -@samp{integtry(@var{expr},@var{var})}, where @var{expr} is the -integrand and @var{var} is the integration variable. If your rules -rewrite this to be a plain formula (not a call to @code{integtry}), then -Calc will use this formula as the integral of @var{expr}. For example, -the rule @samp{integtry(mysin(x),x) := -mycos(x)} would define a rule to -integrate a function @code{mysin} that acts like the sine function. -Then, putting @samp{4 mysin(2y+1)} on the stack and typing @kbd{a i y} -will produce the integral @samp{-2 mycos(2y+1)}. Note that Calc has -automatically made various transformations on the integral to allow it -to use your rule; integral tables generally give rules for -@samp{mysin(a x + b)}, but you don't need to use this much generality -in your @code{IntegRules}. - -@cindex Exponential integral Ei(x) -@ignore -@starindex -@end ignore -@tindex Ei -As a more serious example, the expression @samp{exp(x)/x} cannot be -integrated in terms of the standard functions, so the ``exponential -integral'' function -@texline @math{{\rm Ei}(x)} -@infoline @expr{Ei(x)} -was invented to describe it. -We can get Calc to do this integral in terms of a made-up @code{Ei} -function by adding the rule @samp{[integtry(exp(x)/x, x) := Ei(x)]} -to @code{IntegRules}. Now entering @samp{exp(2x)/x} on the stack -and typing @kbd{a i x} yields @samp{Ei(2 x)}. This new rule will -work with Calc's various built-in integration methods (such as -integration by substitution) to solve a variety of other problems -involving @code{Ei}: For example, now Calc will also be able to -integrate @samp{exp(exp(x))} and @samp{ln(ln(x))} (to get @samp{Ei(exp(x))} -and @samp{x ln(ln(x)) - Ei(ln(x))}, respectively). - -Your rule may do further integration by calling @code{integ}. For -example, @samp{integtry(twice(u),x) := twice(integ(u))} allows Calc -to integrate @samp{twice(sin(x))} to get @samp{twice(-cos(x))}. -Note that @code{integ} was called with only one argument. This notation -is allowed only within @code{IntegRules}; it means ``integrate this -with respect to the same integration variable.'' If Calc is unable -to integrate @code{u}, the integration that invoked @code{IntegRules} -also fails. Thus integrating @samp{twice(f(x))} fails, returning the -unevaluated integral @samp{integ(twice(f(x)), x)}. It is still valid -to call @code{integ} with two or more arguments, however; in this case, -if @code{u} is not integrable, @code{twice} itself will still be -integrated: If the above rule is changed to @samp{... := twice(integ(u,x))}, -then integrating @samp{twice(f(x))} will yield @samp{twice(integ(f(x),x))}. - -If a rule instead produces the formula @samp{integsubst(@var{sexpr}, -@var{svar})}, either replacing the top-level @code{integtry} call or -nested anywhere inside the expression, then Calc will apply the -substitution @samp{@var{u} = @var{sexpr}(@var{svar})} to try to -integrate the original @var{expr}. For example, the rule -@samp{sqrt(a) := integsubst(sqrt(x),x)} says that if Calc ever finds -a square root in the integrand, it should attempt the substitution -@samp{u = sqrt(x)}. (This particular rule is unnecessary because -Calc always tries ``obvious'' substitutions where @var{sexpr} actually -appears in the integrand.) The variable @var{svar} may be the same -as the @var{var} that appeared in the call to @code{integtry}, but -it need not be. - -When integrating according to an @code{integsubst}, Calc uses the -equation solver to find the inverse of @var{sexpr} (if the integrand -refers to @var{var} anywhere except in subexpressions that exactly -match @var{sexpr}). It uses the differentiator to find the derivative -of @var{sexpr} and/or its inverse (it has two methods that use one -derivative or the other). You can also specify these items by adding -extra arguments to the @code{integsubst} your rules construct; the -general form is @samp{integsubst(@var{sexpr}, @var{svar}, @var{sinv}, -@var{sprime})}, where @var{sinv} is the inverse of @var{sexpr} (still -written as a function of @var{svar}), and @var{sprime} is the -derivative of @var{sexpr} with respect to @var{svar}. If you don't -specify these things, and Calc is not able to work them out on its -own with the information it knows, then your substitution rule will -work only in very specific, simple cases. - -Calc applies @code{IntegRules} as if by @kbd{C-u 1 a r IntegRules}; -in other words, Calc stops rewriting as soon as any rule in your rule -set succeeds. (If it weren't for this, the @samp{integsubst(sqrt(x),x)} -example above would keep on adding layers of @code{integsubst} calls -forever!) - -@vindex IntegSimpRules -Another set of rules, stored in @code{IntegSimpRules}, are applied -every time the integrator uses @kbd{a s} to simplify an intermediate -result. For example, putting the rule @samp{twice(x) := 2 x} into -@code{IntegSimpRules} would tell Calc to convert the @code{twice} -function into a form it knows whenever integration is attempted. - -One more way to influence the integrator is to define a function with -the @kbd{Z F} command (@pxref{Algebraic Definitions}). Calc's -integrator automatically expands such functions according to their -defining formulas, even if you originally asked for the function to -be left unevaluated for symbolic arguments. (Certain other Calc -systems, such as the differentiator and the equation solver, also -do this.) - -@vindex IntegAfterRules -Sometimes Calc is able to find a solution to your integral, but it -expresses the result in a way that is unnecessarily complicated. If -this happens, you can either use @code{integsubst} as described -above to try to hint at a more direct path to the desired result, or -you can use @code{IntegAfterRules}. This is an extra rule set that -runs after the main integrator returns its result; basically, Calc does -an @kbd{a r IntegAfterRules} on the result before showing it to you. -(It also does an @kbd{a s}, without @code{IntegSimpRules}, after that -to further simplify the result.) For example, Calc's integrator -sometimes produces expressions of the form @samp{ln(1+x) - ln(1-x)}; -the default @code{IntegAfterRules} rewrite this into the more readable -form @samp{2 arctanh(x)}. Note that, unlike @code{IntegRules}, -@code{IntegSimpRules} and @code{IntegAfterRules} are applied any number -of times until no further changes are possible. Rewriting by -@code{IntegAfterRules} occurs only after the main integrator has -finished, not at every step as for @code{IntegRules} and -@code{IntegSimpRules}. - -@node Numerical Integration, Taylor Series, Customizing the Integrator, Calculus -@subsection Numerical Integration - -@noindent -@kindex a I -@pindex calc-num-integral -@tindex ninteg -If you want a purely numerical answer to an integration problem, you can -use the @kbd{a I} (@code{calc-num-integral}) [@code{ninteg}] command. This -command prompts for an integration variable, a lower limit, and an -upper limit. Except for the integration variable, all other variables -that appear in the integrand formula must have stored values. (A stored -value, if any, for the integration variable itself is ignored.) - -Numerical integration works by evaluating your formula at many points in -the specified interval. Calc uses an ``open Romberg'' method; this means -that it does not evaluate the formula actually at the endpoints (so that -it is safe to integrate @samp{sin(x)/x} from zero, for example). Also, -the Romberg method works especially well when the function being -integrated is fairly smooth. If the function is not smooth, Calc will -have to evaluate it at quite a few points before it can accurately -determine the value of the integral. - -Integration is much faster when the current precision is small. It is -best to set the precision to the smallest acceptable number of digits -before you use @kbd{a I}. If Calc appears to be taking too long, press -@kbd{C-g} to halt it and try a lower precision. If Calc still appears -to need hundreds of evaluations, check to make sure your function is -well-behaved in the specified interval. - -It is possible for the lower integration limit to be @samp{-inf} (minus -infinity). Likewise, the upper limit may be plus infinity. Calc -internally transforms the integral into an equivalent one with finite -limits. However, integration to or across singularities is not supported: -The integral of @samp{1/sqrt(x)} from 0 to 1 exists (it can be found -by Calc's symbolic integrator, for example), but @kbd{a I} will fail -because the integrand goes to infinity at one of the endpoints. - -@node Taylor Series, , Numerical Integration, Calculus -@subsection Taylor Series - -@noindent -@kindex a t -@pindex calc-taylor -@tindex taylor -The @kbd{a t} (@code{calc-taylor}) [@code{taylor}] command computes a -power series expansion or Taylor series of a function. You specify the -variable and the desired number of terms. You may give an expression of -the form @samp{@var{var} = @var{a}} or @samp{@var{var} - @var{a}} instead -of just a variable to produce a Taylor expansion about the point @var{a}. -You may specify the number of terms with a numeric prefix argument; -otherwise the command will prompt you for the number of terms. Note that -many series expansions have coefficients of zero for some terms, so you -may appear to get fewer terms than you asked for. - -If the @kbd{a i} command is unable to find a symbolic integral for a -function, you can get an approximation by integrating the function's -Taylor series. - -@node Solving Equations, Numerical Solutions, Calculus, Algebra -@section Solving Equations - -@noindent -@kindex a S -@pindex calc-solve-for -@tindex solve -@cindex Equations, solving -@cindex Solving equations -The @kbd{a S} (@code{calc-solve-for}) [@code{solve}] command rearranges -an equation to solve for a specific variable. An equation is an -expression of the form @expr{L = R}. For example, the command @kbd{a S x} -will rearrange @expr{y = 3x + 6} to the form, @expr{x = y/3 - 2}. If the -input is not an equation, it is treated like an equation of the -form @expr{X = 0}. - -This command also works for inequalities, as in @expr{y < 3x + 6}. -Some inequalities cannot be solved where the analogous equation could -be; for example, solving -@texline @math{a < b \, c} -@infoline @expr{a < b c} -for @expr{b} is impossible -without knowing the sign of @expr{c}. In this case, @kbd{a S} will -produce the result -@texline @math{b \mathbin{\hbox{\code{!=}}} a/c} -@infoline @expr{b != a/c} -(using the not-equal-to operator) to signify that the direction of the -inequality is now unknown. The inequality -@texline @math{a \le b \, c} -@infoline @expr{a <= b c} -is not even partially solved. @xref{Declarations}, for a way to tell -Calc that the signs of the variables in a formula are in fact known. - -Two useful commands for working with the result of @kbd{a S} are -@kbd{a .} (@pxref{Logical Operations}), which converts @expr{x = y/3 - 2} -to @expr{y/3 - 2}, and @kbd{s l} (@pxref{Let Command}) which evaluates -another formula with @expr{x} set equal to @expr{y/3 - 2}. - -@menu -* Multiple Solutions:: -* Solving Systems of Equations:: -* Decomposing Polynomials:: -@end menu - -@node Multiple Solutions, Solving Systems of Equations, Solving Equations, Solving Equations -@subsection Multiple Solutions - -@noindent -@kindex H a S -@tindex fsolve -Some equations have more than one solution. The Hyperbolic flag -(@code{H a S}) [@code{fsolve}] tells the solver to report the fully -general family of solutions. It will invent variables @code{n1}, -@code{n2}, @dots{}, which represent independent arbitrary integers, and -@code{s1}, @code{s2}, @dots{}, which represent independent arbitrary -signs (either @mathit{+1} or @mathit{-1}). If you don't use the Hyperbolic -flag, Calc will use zero in place of all arbitrary integers, and plus -one in place of all arbitrary signs. Note that variables like @code{n1} -and @code{s1} are not given any special interpretation in Calc except by -the equation solver itself. As usual, you can use the @w{@kbd{s l}} -(@code{calc-let}) command to obtain solutions for various actual values -of these variables. - -For example, @kbd{' x^2 = y @key{RET} H a S x @key{RET}} solves to -get @samp{x = s1 sqrt(y)}, indicating that the two solutions to the -equation are @samp{sqrt(y)} and @samp{-sqrt(y)}. Another way to -think about it is that the square-root operation is really a -two-valued function; since every Calc function must return a -single result, @code{sqrt} chooses to return the positive result. -Then @kbd{H a S} doctors this result using @code{s1} to indicate -the full set of possible values of the mathematical square-root. - -There is a similar phenomenon going the other direction: Suppose -we solve @samp{sqrt(y) = x} for @code{y}. Calc squares both sides -to get @samp{y = x^2}. This is correct, except that it introduces -some dubious solutions. Consider solving @samp{sqrt(y) = -3}: -Calc will report @expr{y = 9} as a valid solution, which is true -in the mathematical sense of square-root, but false (there is no -solution) for the actual Calc positive-valued @code{sqrt}. This -happens for both @kbd{a S} and @kbd{H a S}. - -@cindex @code{GenCount} variable -@vindex GenCount -@ignore -@starindex -@end ignore -@tindex an -@ignore -@starindex -@end ignore -@tindex as -If you store a positive integer in the Calc variable @code{GenCount}, -then Calc will generate formulas of the form @samp{as(@var{n})} for -arbitrary signs, and @samp{an(@var{n})} for arbitrary integers, -where @var{n} represents successive values taken by incrementing -@code{GenCount} by one. While the normal arbitrary sign and -integer symbols start over at @code{s1} and @code{n1} with each -new Calc command, the @code{GenCount} approach will give each -arbitrary value a name that is unique throughout the entire Calc -session. Also, the arbitrary values are function calls instead -of variables, which is advantageous in some cases. For example, -you can make a rewrite rule that recognizes all arbitrary signs -using a pattern like @samp{as(n)}. The @kbd{s l} command only works -on variables, but you can use the @kbd{a b} (@code{calc-substitute}) -command to substitute actual values for function calls like @samp{as(3)}. - -The @kbd{s G} (@code{calc-edit-GenCount}) command is a convenient -way to create or edit this variable. Press @kbd{C-c C-c} to finish. - -If you have not stored a value in @code{GenCount}, or if the value -in that variable is not a positive integer, the regular -@code{s1}/@code{n1} notation is used. - -@kindex I a S -@kindex H I a S -@tindex finv -@tindex ffinv -With the Inverse flag, @kbd{I a S} [@code{finv}] treats the expression -on top of the stack as a function of the specified variable and solves -to find the inverse function, written in terms of the same variable. -For example, @kbd{I a S x} inverts @expr{2x + 6} to @expr{x/2 - 3}. -You can use both Inverse and Hyperbolic [@code{ffinv}] to obtain a -fully general inverse, as described above. - -@kindex a P -@pindex calc-poly-roots -@tindex roots -Some equations, specifically polynomials, have a known, finite number -of solutions. The @kbd{a P} (@code{calc-poly-roots}) [@code{roots}] -command uses @kbd{H a S} to solve an equation in general form, then, for -all arbitrary-sign variables like @code{s1}, and all arbitrary-integer -variables like @code{n1} for which @code{n1} only usefully varies over -a finite range, it expands these variables out to all their possible -values. The results are collected into a vector, which is returned. -For example, @samp{roots(x^4 = 1, x)} returns the four solutions -@samp{[1, -1, (0, 1), (0, -1)]}. Generally an @var{n}th degree -polynomial will always have @var{n} roots on the complex plane. -(If you have given a @code{real} declaration for the solution -variable, then only the real-valued solutions, if any, will be -reported; @pxref{Declarations}.) - -Note that because @kbd{a P} uses @kbd{H a S}, it is able to deliver -symbolic solutions if the polynomial has symbolic coefficients. Also -note that Calc's solver is not able to get exact symbolic solutions -to all polynomials. Polynomials containing powers up to @expr{x^4} -can always be solved exactly; polynomials of higher degree sometimes -can be: @expr{x^6 + x^3 + 1} is converted to @expr{(x^3)^2 + (x^3) + 1}, -which can be solved for @expr{x^3} using the quadratic equation, and then -for @expr{x} by taking cube roots. But in many cases, like -@expr{x^6 + x + 1}, Calc does not know how to rewrite the polynomial -into a form it can solve. The @kbd{a P} command can still deliver a -list of numerical roots, however, provided that Symbolic mode (@kbd{m s}) -is not turned on. (If you work with Symbolic mode on, recall that the -@kbd{N} (@code{calc-eval-num}) key is a handy way to reevaluate the -formula on the stack with Symbolic mode temporarily off.) Naturally, -@kbd{a P} can only provide numerical roots if the polynomial coefficients -are all numbers (real or complex). - -@node Solving Systems of Equations, Decomposing Polynomials, Multiple Solutions, Solving Equations -@subsection Solving Systems of Equations - -@noindent -@cindex Systems of equations, symbolic -You can also use the commands described above to solve systems of -simultaneous equations. Just create a vector of equations, then -specify a vector of variables for which to solve. (You can omit -the surrounding brackets when entering the vector of variables -at the prompt.) - -For example, putting @samp{[x + y = a, x - y = b]} on the stack -and typing @kbd{a S x,y @key{RET}} produces the vector of solutions -@samp{[x = a - (a-b)/2, y = (a-b)/2]}. The result vector will -have the same length as the variables vector, and the variables -will be listed in the same order there. Note that the solutions -are not always simplified as far as possible; the solution for -@expr{x} here could be improved by an application of the @kbd{a n} -command. - -Calc's algorithm works by trying to eliminate one variable at a -time by solving one of the equations for that variable and then -substituting into the other equations. Calc will try all the -possibilities, but you can speed things up by noting that Calc -first tries to eliminate the first variable with the first -equation, then the second variable with the second equation, -and so on. It also helps to put the simpler (e.g., more linear) -equations toward the front of the list. Calc's algorithm will -solve any system of linear equations, and also many kinds of -nonlinear systems. - -@ignore -@starindex -@end ignore -@tindex elim -Normally there will be as many variables as equations. If you -give fewer variables than equations (an ``over-determined'' system -of equations), Calc will find a partial solution. For example, -typing @kbd{a S y @key{RET}} with the above system of equations -would produce @samp{[y = a - x]}. There are now several ways to -express this solution in terms of the original variables; Calc uses -the first one that it finds. You can control the choice by adding -variable specifiers of the form @samp{elim(@var{v})} to the -variables list. This says that @var{v} should be eliminated from -the equations; the variable will not appear at all in the solution. -For example, typing @kbd{a S y,elim(x)} would yield -@samp{[y = a - (b+a)/2]}. - -If the variables list contains only @code{elim} specifiers, -Calc simply eliminates those variables from the equations -and then returns the resulting set of equations. For example, -@kbd{a S elim(x)} produces @samp{[a - 2 y = b]}. Every variable -eliminated will reduce the number of equations in the system -by one. - -Again, @kbd{a S} gives you one solution to the system of -equations. If there are several solutions, you can use @kbd{H a S} -to get a general family of solutions, or, if there is a finite -number of solutions, you can use @kbd{a P} to get a list. (In -the latter case, the result will take the form of a matrix where -the rows are different solutions and the columns correspond to the -variables you requested.) - -Another way to deal with certain kinds of overdetermined systems of -equations is the @kbd{a F} command, which does least-squares fitting -to satisfy the equations. @xref{Curve Fitting}. - -@node Decomposing Polynomials, , Solving Systems of Equations, Solving Equations -@subsection Decomposing Polynomials - -@noindent -@ignore -@starindex -@end ignore -@tindex poly -The @code{poly} function takes a polynomial and a variable as -arguments, and returns a vector of polynomial coefficients (constant -coefficient first). For example, @samp{poly(x^3 + 2 x, x)} returns -@expr{[0, 2, 0, 1]}. If the input is not a polynomial in @expr{x}, -the call to @code{poly} is left in symbolic form. If the input does -not involve the variable @expr{x}, the input is returned in a list -of length one, representing a polynomial with only a constant -coefficient. The call @samp{poly(x, x)} returns the vector @expr{[0, 1]}. -The last element of the returned vector is guaranteed to be nonzero; -note that @samp{poly(0, x)} returns the empty vector @expr{[]}. -Note also that @expr{x} may actually be any formula; for example, -@samp{poly(sin(x)^2 - sin(x) + 3, sin(x))} returns @expr{[3, -1, 1]}. - -@cindex Coefficients of polynomial -@cindex Degree of polynomial -To get the @expr{x^k} coefficient of polynomial @expr{p}, use -@samp{poly(p, x)_(k+1)}. To get the degree of polynomial @expr{p}, -use @samp{vlen(poly(p, x)) - 1}. For example, @samp{poly((x+1)^4, x)} -returns @samp{[1, 4, 6, 4, 1]}, so @samp{poly((x+1)^4, x)_(2+1)} -gives the @expr{x^2} coefficient of this polynomial, 6. - -@ignore -@starindex -@end ignore -@tindex gpoly -One important feature of the solver is its ability to recognize -formulas which are ``essentially'' polynomials. This ability is -made available to the user through the @code{gpoly} function, which -is used just like @code{poly}: @samp{gpoly(@var{expr}, @var{var})}. -If @var{expr} is a polynomial in some term which includes @var{var}, then -this function will return a vector @samp{[@var{x}, @var{c}, @var{a}]} -where @var{x} is the term that depends on @var{var}, @var{c} is a -vector of polynomial coefficients (like the one returned by @code{poly}), -and @var{a} is a multiplier which is usually 1. Basically, -@samp{@var{expr} = @var{a}*(@var{c}_1 + @var{c}_2 @var{x} + -@var{c}_3 @var{x}^2 + ...)}. The last element of @var{c} is -guaranteed to be non-zero, and @var{c} will not equal @samp{[1]} -(i.e., the trivial decomposition @var{expr} = @var{x} is not -considered a polynomial). One side effect is that @samp{gpoly(x, x)} -and @samp{gpoly(6, x)}, both of which might be expected to recognize -their arguments as polynomials, will not because the decomposition -is considered trivial. - -For example, @samp{gpoly((x-2)^2, x)} returns @samp{[x, [4, -4, 1], 1]}, -since the expanded form of this polynomial is @expr{4 - 4 x + x^2}. - -The term @var{x} may itself be a polynomial in @var{var}. This is -done to reduce the size of the @var{c} vector. For example, -@samp{gpoly(x^4 + x^2 - 1, x)} returns @samp{[x^2, [-1, 1, 1], 1]}, -since a quadratic polynomial in @expr{x^2} is easier to solve than -a quartic polynomial in @expr{x}. - -A few more examples of the kinds of polynomials @code{gpoly} can -discover: - -@smallexample -sin(x) - 1 [sin(x), [-1, 1], 1] -x + 1/x - 1 [x, [1, -1, 1], 1/x] -x + 1/x [x^2, [1, 1], 1/x] -x^3 + 2 x [x^2, [2, 1], x] -x + x^2:3 + sqrt(x) [x^1:6, [1, 1, 0, 1], x^1:2] -x^(2a) + 2 x^a + 5 [x^a, [5, 2, 1], 1] -(exp(-x) + exp(x)) / 2 [e^(2 x), [0.5, 0.5], e^-x] -@end smallexample - -The @code{poly} and @code{gpoly} functions accept a third integer argument -which specifies the largest degree of polynomial that is acceptable. -If this is @expr{n}, then only @var{c} vectors of length @expr{n+1} -or less will be returned. Otherwise, the @code{poly} or @code{gpoly} -call will remain in symbolic form. For example, the equation solver -can handle quartics and smaller polynomials, so it calls -@samp{gpoly(@var{expr}, @var{var}, 4)} to discover whether @var{expr} -can be treated by its linear, quadratic, cubic, or quartic formulas. - -@ignore -@starindex -@end ignore -@tindex pdeg -The @code{pdeg} function computes the degree of a polynomial; -@samp{pdeg(p,x)} is the highest power of @code{x} that appears in -@code{p}. This is the same as @samp{vlen(poly(p,x))-1}, but is -much more efficient. If @code{p} is constant with respect to @code{x}, -then @samp{pdeg(p,x) = 0}. If @code{p} is not a polynomial in @code{x} -(e.g., @samp{pdeg(2 cos(x), x)}, the function remains unevaluated. -It is possible to omit the second argument @code{x}, in which case -@samp{pdeg(p)} returns the highest total degree of any term of the -polynomial, counting all variables that appear in @code{p}. Note -that @code{pdeg(c) = pdeg(c,x) = 0} for any nonzero constant @code{c}; -the degree of the constant zero is considered to be @code{-inf} -(minus infinity). - -@ignore -@starindex -@end ignore -@tindex plead -The @code{plead} function finds the leading term of a polynomial. -Thus @samp{plead(p,x)} is equivalent to @samp{poly(p,x)_vlen(poly(p,x))}, -though again more efficient. In particular, @samp{plead((2x+1)^10, x)} -returns 1024 without expanding out the list of coefficients. The -value of @code{plead(p,x)} will be zero only if @expr{p = 0}. - -@ignore -@starindex -@end ignore -@tindex pcont -The @code{pcont} function finds the @dfn{content} of a polynomial. This -is the greatest common divisor of all the coefficients of the polynomial. -With two arguments, @code{pcont(p,x)} effectively uses @samp{poly(p,x)} -to get a list of coefficients, then uses @code{pgcd} (the polynomial -GCD function) to combine these into an answer. For example, -@samp{pcont(4 x y^2 + 6 x^2 y, x)} is @samp{2 y}. The content is -basically the ``biggest'' polynomial that can be divided into @code{p} -exactly. The sign of the content is the same as the sign of the leading -coefficient. - -With only one argument, @samp{pcont(p)} computes the numerical -content of the polynomial, i.e., the @code{gcd} of the numerical -coefficients of all the terms in the formula. Note that @code{gcd} -is defined on rational numbers as well as integers; it computes -the @code{gcd} of the numerators and the @code{lcm} of the -denominators. Thus @samp{pcont(4:3 x y^2 + 6 x^2 y)} returns 2:3. -Dividing the polynomial by this number will clear all the -denominators, as well as dividing by any common content in the -numerators. The numerical content of a polynomial is negative only -if all the coefficients in the polynomial are negative. - -@ignore -@starindex -@end ignore -@tindex pprim -The @code{pprim} function finds the @dfn{primitive part} of a -polynomial, which is simply the polynomial divided (using @code{pdiv} -if necessary) by its content. If the input polynomial has rational -coefficients, the result will have integer coefficients in simplest -terms. - -@node Numerical Solutions, Curve Fitting, Solving Equations, Algebra -@section Numerical Solutions - -@noindent -Not all equations can be solved symbolically. The commands in this -section use numerical algorithms that can find a solution to a specific -instance of an equation to any desired accuracy. Note that the -numerical commands are slower than their algebraic cousins; it is a -good idea to try @kbd{a S} before resorting to these commands. - -(@xref{Curve Fitting}, for some other, more specialized, operations -on numerical data.) - -@menu -* Root Finding:: -* Minimization:: -* Numerical Systems of Equations:: -@end menu - -@node Root Finding, Minimization, Numerical Solutions, Numerical Solutions -@subsection Root Finding - -@noindent -@kindex a R -@pindex calc-find-root -@tindex root -@cindex Newton's method -@cindex Roots of equations -@cindex Numerical root-finding -The @kbd{a R} (@code{calc-find-root}) [@code{root}] command finds a -numerical solution (or @dfn{root}) of an equation. (This command treats -inequalities the same as equations. If the input is any other kind -of formula, it is interpreted as an equation of the form @expr{X = 0}.) - -The @kbd{a R} command requires an initial guess on the top of the -stack, and a formula in the second-to-top position. It prompts for a -solution variable, which must appear in the formula. All other variables -that appear in the formula must have assigned values, i.e., when -a value is assigned to the solution variable and the formula is -evaluated with @kbd{=}, it should evaluate to a number. Any assigned -value for the solution variable itself is ignored and unaffected by -this command. - -When the command completes, the initial guess is replaced on the stack -by a vector of two numbers: The value of the solution variable that -solves the equation, and the difference between the lefthand and -righthand sides of the equation at that value. Ordinarily, the second -number will be zero or very nearly zero. (Note that Calc uses a -slightly higher precision while finding the root, and thus the second -number may be slightly different from the value you would compute from -the equation yourself.) - -The @kbd{v h} (@code{calc-head}) command is a handy way to extract -the first element of the result vector, discarding the error term. - -The initial guess can be a real number, in which case Calc searches -for a real solution near that number, or a complex number, in which -case Calc searches the whole complex plane near that number for a -solution, or it can be an interval form which restricts the search -to real numbers inside that interval. - -Calc tries to use @kbd{a d} to take the derivative of the equation. -If this succeeds, it uses Newton's method. If the equation is not -differentiable Calc uses a bisection method. (If Newton's method -appears to be going astray, Calc switches over to bisection if it -can, or otherwise gives up. In this case it may help to try again -with a slightly different initial guess.) If the initial guess is a -complex number, the function must be differentiable. - -If the formula (or the difference between the sides of an equation) -is negative at one end of the interval you specify and positive at -the other end, the root finder is guaranteed to find a root. -Otherwise, Calc subdivides the interval into small parts looking for -positive and negative values to bracket the root. When your guess is -an interval, Calc will not look outside that interval for a root. - -@kindex H a R -@tindex wroot -The @kbd{H a R} [@code{wroot}] command is similar to @kbd{a R}, except -that if the initial guess is an interval for which the function has -the same sign at both ends, then rather than subdividing the interval -Calc attempts to widen it to enclose a root. Use this mode if -you are not sure if the function has a root in your interval. - -If the function is not differentiable, and you give a simple number -instead of an interval as your initial guess, Calc uses this widening -process even if you did not type the Hyperbolic flag. (If the function -@emph{is} differentiable, Calc uses Newton's method which does not -require a bounding interval in order to work.) - -If Calc leaves the @code{root} or @code{wroot} function in symbolic -form on the stack, it will normally display an explanation for why -no root was found. If you miss this explanation, press @kbd{w} -(@code{calc-why}) to get it back. - -@node Minimization, Numerical Systems of Equations, Root Finding, Numerical Solutions -@subsection Minimization - -@noindent -@kindex a N -@kindex H a N -@kindex a X -@kindex H a X -@pindex calc-find-minimum -@pindex calc-find-maximum -@tindex minimize -@tindex maximize -@cindex Minimization, numerical -The @kbd{a N} (@code{calc-find-minimum}) [@code{minimize}] command -finds a minimum value for a formula. It is very similar in operation -to @kbd{a R} (@code{calc-find-root}): You give the formula and an initial -guess on the stack, and are prompted for the name of a variable. The guess -may be either a number near the desired minimum, or an interval enclosing -the desired minimum. The function returns a vector containing the -value of the variable which minimizes the formula's value, along -with the minimum value itself. - -Note that this command looks for a @emph{local} minimum. Many functions -have more than one minimum; some, like -@texline @math{x \sin x}, -@infoline @expr{x sin(x)}, -have infinitely many. In fact, there is no easy way to define the -``global'' minimum of -@texline @math{x \sin x} -@infoline @expr{x sin(x)} -but Calc can still locate any particular local minimum -for you. Calc basically goes downhill from the initial guess until it -finds a point at which the function's value is greater both to the left -and to the right. Calc does not use derivatives when minimizing a function. - -If your initial guess is an interval and it looks like the minimum -occurs at one or the other endpoint of the interval, Calc will return -that endpoint only if that endpoint is closed; thus, minimizing @expr{17 x} -over @expr{[2..3]} will return @expr{[2, 38]}, but minimizing over -@expr{(2..3]} would report no minimum found. In general, you should -use closed intervals to find literally the minimum value in that -range of @expr{x}, or open intervals to find the local minimum, if -any, that happens to lie in that range. - -Most functions are smooth and flat near their minimum values. Because -of this flatness, if the current precision is, say, 12 digits, the -variable can only be determined meaningfully to about six digits. Thus -you should set the precision to twice as many digits as you need in your -answer. - -@ignore -@mindex wmin@idots -@end ignore -@tindex wminimize -@ignore -@mindex wmax@idots -@end ignore -@tindex wmaximize -The @kbd{H a N} [@code{wminimize}] command, analogously to @kbd{H a R}, -expands the guess interval to enclose a minimum rather than requiring -that the minimum lie inside the interval you supply. - -The @kbd{a X} (@code{calc-find-maximum}) [@code{maximize}] and -@kbd{H a X} [@code{wmaximize}] commands effectively minimize the -negative of the formula you supply. - -The formula must evaluate to a real number at all points inside the -interval (or near the initial guess if the guess is a number). If -the initial guess is a complex number the variable will be minimized -over the complex numbers; if it is real or an interval it will -be minimized over the reals. - -@node Numerical Systems of Equations, , Minimization, Numerical Solutions -@subsection Systems of Equations - -@noindent -@cindex Systems of equations, numerical -The @kbd{a R} command can also solve systems of equations. In this -case, the equation should instead be a vector of equations, the -guess should instead be a vector of numbers (intervals are not -supported), and the variable should be a vector of variables. You -can omit the brackets while entering the list of variables. Each -equation must be differentiable by each variable for this mode to -work. The result will be a vector of two vectors: The variable -values that solved the system of equations, and the differences -between the sides of the equations with those variable values. -There must be the same number of equations as variables. Since -only plain numbers are allowed as guesses, the Hyperbolic flag has -no effect when solving a system of equations. - -It is also possible to minimize over many variables with @kbd{a N} -(or maximize with @kbd{a X}). Once again the variable name should -be replaced by a vector of variables, and the initial guess should -be an equal-sized vector of initial guesses. But, unlike the case of -multidimensional @kbd{a R}, the formula being minimized should -still be a single formula, @emph{not} a vector. Beware that -multidimensional minimization is currently @emph{very} slow. - -@node Curve Fitting, Summations, Numerical Solutions, Algebra -@section Curve Fitting - -@noindent -The @kbd{a F} command fits a set of data to a @dfn{model formula}, -such as @expr{y = m x + b} where @expr{m} and @expr{b} are parameters -to be determined. For a typical set of measured data there will be -no single @expr{m} and @expr{b} that exactly fit the data; in this -case, Calc chooses values of the parameters that provide the closest -possible fit. The model formula can be entered in various ways after -the key sequence @kbd{a F} is pressed. - -If the letter @kbd{P} is pressed after @kbd{a F} but before the model -description is entered, the data as well as the model formula will be -plotted after the formula is determined. This will be indicated by a -``P'' in the minibuffer after the help message. - -@menu -* Linear Fits:: -* Polynomial and Multilinear Fits:: -* Error Estimates for Fits:: -* Standard Nonlinear Models:: -* Curve Fitting Details:: -* Interpolation:: -@end menu - -@node Linear Fits, Polynomial and Multilinear Fits, Curve Fitting, Curve Fitting -@subsection Linear Fits - -@noindent -@kindex a F -@pindex calc-curve-fit -@tindex fit -@cindex Linear regression -@cindex Least-squares fits -The @kbd{a F} (@code{calc-curve-fit}) [@code{fit}] command attempts -to fit a set of data (@expr{x} and @expr{y} vectors of numbers) to a -straight line, polynomial, or other function of @expr{x}. For the -moment we will consider only the case of fitting to a line, and we -will ignore the issue of whether or not the model was in fact a good -fit for the data. - -In a standard linear least-squares fit, we have a set of @expr{(x,y)} -data points that we wish to fit to the model @expr{y = m x + b} -by adjusting the parameters @expr{m} and @expr{b} to make the @expr{y} -values calculated from the formula be as close as possible to the actual -@expr{y} values in the data set. (In a polynomial fit, the model is -instead, say, @expr{y = a x^3 + b x^2 + c x + d}. In a multilinear fit, -we have data points of the form @expr{(x_1,x_2,x_3,y)} and our model is -@expr{y = a x_1 + b x_2 + c x_3 + d}. These will be discussed later.) - -In the model formula, variables like @expr{x} and @expr{x_2} are called -the @dfn{independent variables}, and @expr{y} is the @dfn{dependent -variable}. Variables like @expr{m}, @expr{a}, and @expr{b} are called -the @dfn{parameters} of the model. - -The @kbd{a F} command takes the data set to be fitted from the stack. -By default, it expects the data in the form of a matrix. For example, -for a linear or polynomial fit, this would be a -@texline @math{2\times N} -@infoline 2xN -matrix where the first row is a list of @expr{x} values and the second -row has the corresponding @expr{y} values. For the multilinear fit -shown above, the matrix would have four rows (@expr{x_1}, @expr{x_2}, -@expr{x_3}, and @expr{y}, respectively). - -If you happen to have an -@texline @math{N\times2} -@infoline Nx2 -matrix instead of a -@texline @math{2\times N} -@infoline 2xN -matrix, just press @kbd{v t} first to transpose the matrix. - -After you type @kbd{a F}, Calc prompts you to select a model. For a -linear fit, press the digit @kbd{1}. - -Calc then prompts for you to name the variables. By default it chooses -high letters like @expr{x} and @expr{y} for independent variables and -low letters like @expr{a} and @expr{b} for parameters. (The dependent -variable doesn't need a name.) The two kinds of variables are separated -by a semicolon. Since you generally care more about the names of the -independent variables than of the parameters, Calc also allows you to -name only those and let the parameters use default names. - -For example, suppose the data matrix - -@ifnottex -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 5, 7, 9, 11, 13 ] ] -@end group -@end example -@end ifnottex -@tex -\turnoffactive -\turnoffactive -\beforedisplay -$$ \pmatrix{ 1 & 2 & 3 & 4 & 5 \cr - 5 & 7 & 9 & 11 & 13 } -$$ -\afterdisplay -@end tex - -@noindent -is on the stack and we wish to do a simple linear fit. Type -@kbd{a F}, then @kbd{1} for the model, then @key{RET} to use -the default names. The result will be the formula @expr{3. + 2. x} -on the stack. Calc has created the model expression @kbd{a + b x}, -then found the optimal values of @expr{a} and @expr{b} to fit the -data. (In this case, it was able to find an exact fit.) Calc then -substituted those values for @expr{a} and @expr{b} in the model -formula. - -The @kbd{a F} command puts two entries in the trail. One is, as -always, a copy of the result that went to the stack; the other is -a vector of the actual parameter values, written as equations: -@expr{[a = 3, b = 2]}, in case you'd rather read them in a list -than pick them out of the formula. (You can type @kbd{t y} -to move this vector to the stack; see @ref{Trail Commands}. - -Specifying a different independent variable name will affect the -resulting formula: @kbd{a F 1 k @key{RET}} produces @kbd{3 + 2 k}. -Changing the parameter names (say, @kbd{a F 1 k;b,m @key{RET}}) will affect -the equations that go into the trail. - -@tex -\bigskip -@end tex - -To see what happens when the fit is not exact, we could change -the number 13 in the data matrix to 14 and try the fit again. -The result is: - -@example -2.6 + 2.2 x -@end example - -Evaluating this formula, say with @kbd{v x 5 @key{RET} @key{TAB} V M $ @key{RET}}, shows -a reasonably close match to the y-values in the data. - -@example -[4.8, 7., 9.2, 11.4, 13.6] -@end example - -Since there is no line which passes through all the @var{n} data points, -Calc has chosen a line that best approximates the data points using -the method of least squares. The idea is to define the @dfn{chi-square} -error measure - -@ifnottex -@example -chi^2 = sum((y_i - (a + b x_i))^2, i, 1, N) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N (y_i - (a + b x_i))^2 $$ -\afterdisplay -@end tex - -@noindent -which is clearly zero if @expr{a + b x} exactly fits all data points, -and increases as various @expr{a + b x_i} values fail to match the -corresponding @expr{y_i} values. There are several reasons why the -summand is squared, one of them being to ensure that -@texline @math{\chi^2 \ge 0}. -@infoline @expr{chi^2 >= 0}. -Least-squares fitting simply chooses the values of @expr{a} and @expr{b} -for which the error -@texline @math{\chi^2} -@infoline @expr{chi^2} -is as small as possible. - -Other kinds of models do the same thing but with a different model -formula in place of @expr{a + b x_i}. - -@tex -\bigskip -@end tex - -A numeric prefix argument causes the @kbd{a F} command to take the -data in some other form than one big matrix. A positive argument @var{n} -will take @var{N} items from the stack, corresponding to the @var{n} rows -of a data matrix. In the linear case, @var{n} must be 2 since there -is always one independent variable and one dependent variable. - -A prefix of zero or plain @kbd{C-u} is a compromise; Calc takes two -items from the stack, an @var{n}-row matrix of @expr{x} values, and a -vector of @expr{y} values. If there is only one independent variable, -the @expr{x} values can be either a one-row matrix or a plain vector, -in which case the @kbd{C-u} prefix is the same as a @w{@kbd{C-u 2}} prefix. - -@node Polynomial and Multilinear Fits, Error Estimates for Fits, Linear Fits, Curve Fitting -@subsection Polynomial and Multilinear Fits - -@noindent -To fit the data to higher-order polynomials, just type one of the -digits @kbd{2} through @kbd{9} when prompted for a model. For example, -we could fit the original data matrix from the previous section -(with 13, not 14) to a parabola instead of a line by typing -@kbd{a F 2 @key{RET}}. - -@example -2.00000000001 x - 1.5e-12 x^2 + 2.99999999999 -@end example - -Note that since the constant and linear terms are enough to fit the -data exactly, it's no surprise that Calc chose a tiny contribution -for @expr{x^2}. (The fact that it's not exactly zero is due only -to roundoff error. Since our data are exact integers, we could get -an exact answer by typing @kbd{m f} first to get Fraction mode. -Then the @expr{x^2} term would vanish altogether. Usually, though, -the data being fitted will be approximate floats so Fraction mode -won't help.) - -Doing the @kbd{a F 2} fit on the data set with 14 instead of 13 -gives a much larger @expr{x^2} contribution, as Calc bends the -line slightly to improve the fit. - -@example -0.142857142855 x^2 + 1.34285714287 x + 3.59999999998 -@end example - -An important result from the theory of polynomial fitting is that it -is always possible to fit @var{n} data points exactly using a polynomial -of degree @mathit{@var{n}-1}, sometimes called an @dfn{interpolating polynomial}. -Using the modified (14) data matrix, a model number of 4 gives -a polynomial that exactly matches all five data points: - -@example -0.04167 x^4 - 0.4167 x^3 + 1.458 x^2 - 0.08333 x + 4. -@end example - -The actual coefficients we get with a precision of 12, like -@expr{0.0416666663588}, clearly suffer from loss of precision. -It is a good idea to increase the working precision to several -digits beyond what you need when you do a fitting operation. -Or, if your data are exact, use Fraction mode to get exact -results. - -You can type @kbd{i} instead of a digit at the model prompt to fit -the data exactly to a polynomial. This just counts the number of -columns of the data matrix to choose the degree of the polynomial -automatically. - -Fitting data ``exactly'' to high-degree polynomials is not always -a good idea, though. High-degree polynomials have a tendency to -wiggle uncontrollably in between the fitting data points. Also, -if the exact-fit polynomial is going to be used to interpolate or -extrapolate the data, it is numerically better to use the @kbd{a p} -command described below. @xref{Interpolation}. - -@tex -\bigskip -@end tex - -Another generalization of the linear model is to assume the -@expr{y} values are a sum of linear contributions from several -@expr{x} values. This is a @dfn{multilinear} fit, and it is also -selected by the @kbd{1} digit key. (Calc decides whether the fit -is linear or multilinear by counting the rows in the data matrix.) - -Given the data matrix, - -@example -@group -[ [ 1, 2, 3, 4, 5 ] - [ 7, 2, 3, 5, 2 ] - [ 14.5, 15, 18.5, 22.5, 24 ] ] -@end group -@end example - -@noindent -the command @kbd{a F 1 @key{RET}} will call the first row @expr{x} and the -second row @expr{y}, and will fit the values in the third row to the -model @expr{a + b x + c y}. - -@example -8. + 3. x + 0.5 y -@end example - -Calc can do multilinear fits with any number of independent variables -(i.e., with any number of data rows). - -@tex -\bigskip -@end tex - -Yet another variation is @dfn{homogeneous} linear models, in which -the constant term is known to be zero. In the linear case, this -means the model formula is simply @expr{a x}; in the multilinear -case, the model might be @expr{a x + b y + c z}; and in the polynomial -case, the model could be @expr{a x + b x^2 + c x^3}. You can get -a homogeneous linear or multilinear model by pressing the letter -@kbd{h} followed by a regular model key, like @kbd{1} or @kbd{2}. -This will be indicated by an ``h'' in the minibuffer after the help -message. - -It is certainly possible to have other constrained linear models, -like @expr{2.3 + a x} or @expr{a - 4 x}. While there is no single -key to select models like these, a later section shows how to enter -any desired model by hand. In the first case, for example, you -would enter @kbd{a F ' 2.3 + a x}. - -Another class of models that will work but must be entered by hand -are multinomial fits, e.g., @expr{a + b x + c y + d x^2 + e y^2 + f x y}. - -@node Error Estimates for Fits, Standard Nonlinear Models, Polynomial and Multilinear Fits, Curve Fitting -@subsection Error Estimates for Fits - -@noindent -@kindex H a F -@tindex efit -With the Hyperbolic flag, @kbd{H a F} [@code{efit}] performs the same -fitting operation as @kbd{a F}, but reports the coefficients as error -forms instead of plain numbers. Fitting our two data matrices (first -with 13, then with 14) to a line with @kbd{H a F} gives the results, - -@example -3. + 2. x -2.6 +/- 0.382970843103 + 2.2 +/- 0.115470053838 x -@end example - -In the first case the estimated errors are zero because the linear -fit is perfect. In the second case, the errors are nonzero but -moderately small, because the data are still very close to linear. - -It is also possible for the @emph{input} to a fitting operation to -contain error forms. The data values must either all include errors -or all be plain numbers. Error forms can go anywhere but generally -go on the numbers in the last row of the data matrix. If the last -row contains error forms -@texline `@var{y_i}@w{ @tfn{+/-} }@math{\sigma_i}', -@infoline `@var{y_i}@w{ @tfn{+/-} }@var{sigma_i}', -then the -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistic is now, - -@ifnottex -@example -chi^2 = sum(((y_i - (a + b x_i)) / sigma_i)^2, i, 1, N) -@end example -@end ifnottex -@tex -\turnoffactive -\beforedisplay -$$ \chi^2 = \sum_{i=1}^N \left(y_i - (a + b x_i) \over \sigma_i\right)^2 $$ -\afterdisplay -@end tex - -@noindent -so that data points with larger error estimates contribute less to -the fitting operation. - -If there are error forms on other rows of the data matrix, all the -errors for a given data point are combined; the square root of the -sum of the squares of the errors forms the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -used for the data point. - -Both @kbd{a F} and @kbd{H a F} can accept error forms in the input -matrix, although if you are concerned about error analysis you will -probably use @kbd{H a F} so that the output also contains error -estimates. - -If the input contains error forms but all the -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -values are the same, it is easy to see that the resulting fitted model -will be the same as if the input did not have error forms at all -@texline (@math{\chi^2} -@infoline (@expr{chi^2} -is simply scaled uniformly by -@texline @math{1 / \sigma^2}, -@infoline @expr{1 / sigma^2}, -which doesn't affect where it has a minimum). But there @emph{will} be -a difference in the estimated errors of the coefficients reported by -@kbd{H a F}. - -Consult any text on statistical modeling of data for a discussion -of where these error estimates come from and how they should be -interpreted. - -@tex -\bigskip -@end tex - -@kindex I a F -@tindex xfit -With the Inverse flag, @kbd{I a F} [@code{xfit}] produces even more -information. The result is a vector of six items: - -@enumerate -@item -The model formula with error forms for its coefficients or -parameters. This is the result that @kbd{H a F} would have -produced. - -@item -A vector of ``raw'' parameter values for the model. These are the -polynomial coefficients or other parameters as plain numbers, in the -same order as the parameters appeared in the final prompt of the -@kbd{I a F} command. For polynomials of degree @expr{d}, this vector -will have length @expr{M = d+1} with the constant term first. - -@item -The covariance matrix @expr{C} computed from the fit. This is -an @var{m}x@var{m} symmetric matrix; the diagonal elements -@texline @math{C_{jj}} -@infoline @expr{C_j_j} -are the variances -@texline @math{\sigma_j^2} -@infoline @expr{sigma_j^2} -of the parameters. The other elements are covariances -@texline @math{\sigma_{ij}^2} -@infoline @expr{sigma_i_j^2} -that describe the correlation between pairs of parameters. (A related -set of numbers, the @dfn{linear correlation coefficients} -@texline @math{r_{ij}}, -@infoline @expr{r_i_j}, -are defined as -@texline @math{\sigma_{ij}^2 / \sigma_i \, \sigma_j}.) -@infoline @expr{sigma_i_j^2 / sigma_i sigma_j}.) - -@item -A vector of @expr{M} ``parameter filter'' functions whose -meanings are described below. If no filters are necessary this -will instead be an empty vector; this is always the case for the -polynomial and multilinear fits described so far. - -@item -The value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -for the fit, calculated by the formulas shown above. This gives a -measure of the quality of the fit; statisticians consider -@texline @math{\chi^2 \approx N - M} -@infoline @expr{chi^2 = N - M} -to indicate a moderately good fit (where again @expr{N} is the number of -data points and @expr{M} is the number of parameters). - -@item -A measure of goodness of fit expressed as a probability @expr{Q}. -This is computed from the @code{utpc} probability distribution -function using -@texline @math{\chi^2} -@infoline @expr{chi^2} -with @expr{N - M} degrees of freedom. A -value of 0.5 implies a good fit; some texts recommend that often -@expr{Q = 0.1} or even 0.001 can signify an acceptable fit. In -particular, -@texline @math{\chi^2} -@infoline @expr{chi^2} -statistics assume the errors in your inputs -follow a normal (Gaussian) distribution; if they don't, you may -have to accept smaller values of @expr{Q}. - -The @expr{Q} value is computed only if the input included error -estimates. Otherwise, Calc will report the symbol @code{nan} -for @expr{Q}. The reason is that in this case the -@texline @math{\chi^2} -@infoline @expr{chi^2} -value has effectively been used to estimate the original errors -in the input, and thus there is no redundant information left -over to use for a confidence test. -@end enumerate - -@node Standard Nonlinear Models, Curve Fitting Details, Error Estimates for Fits, Curve Fitting -@subsection Standard Nonlinear Models - -@noindent -The @kbd{a F} command also accepts other kinds of models besides -lines and polynomials. Some common models have quick single-key -abbreviations; others must be entered by hand as algebraic formulas. - -Here is a complete list of the standard models recognized by @kbd{a F}: - -@table @kbd -@item 1 -Linear or multilinear. @mathit{a + b x + c y + d z}. -@item 2-9 -Polynomials. @mathit{a + b x + c x^2 + d x^3}. -@item e -Exponential. @mathit{a} @tfn{exp}@mathit{(b x)} @tfn{exp}@mathit{(c y)}. -@item E -Base-10 exponential. @mathit{a} @tfn{10^}@mathit{(b x)} @tfn{10^}@mathit{(c y)}. -@item x -Exponential (alternate notation). @tfn{exp}@mathit{(a + b x + c y)}. -@item X -Base-10 exponential (alternate). @tfn{10^}@mathit{(a + b x + c y)}. -@item l -Logarithmic. @mathit{a + b} @tfn{ln}@mathit{(x) + c} @tfn{ln}@mathit{(y)}. -@item L -Base-10 logarithmic. @mathit{a + b} @tfn{log10}@mathit{(x) + c} @tfn{log10}@mathit{(y)}. -@item ^ -General exponential. @mathit{a b^x c^y}. -@item p -Power law. @mathit{a x^b y^c}. -@item q -Quadratic. @mathit{a + b (x-c)^2 + d (x-e)^2}. -@item g -Gaussian. -@texline @math{{a \over b \sqrt{2 \pi}} \exp\left( -{1 \over 2} \left( x - c \over b \right)^2 \right)}. -@infoline @mathit{(a / b sqrt(2 pi)) exp(-0.5*((x-c)/b)^2)}. -@item s -Logistic @emph{s} curve. -@texline @math{a/(1+e^{b(x-c)})}. -@infoline @mathit{a/(1 + exp(b (x - c)))}. -@item b -Logistic bell curve. -@texline @math{ae^{b(x-c)}/(1+e^{b(x-c)})^2}. -@infoline @mathit{a exp(b (x - c))/(1 + exp(b (x - c)))^2}. -@item o -Hubbert linearization. -@texline @math{{y \over x} = a(1-x/b)}. -@infoline @mathit{(y/x) = a (1 - x/b)}. -@end table - -All of these models are used in the usual way; just press the appropriate -letter at the model prompt, and choose variable names if you wish. The -result will be a formula as shown in the above table, with the best-fit -values of the parameters substituted. (You may find it easier to read -the parameter values from the vector that is placed in the trail.) - -All models except Gaussian, logistics, Hubbert and polynomials can -generalize as shown to any number of independent variables. Also, all -the built-in models except for the logistic and Hubbert curves have an -additive or multiplicative parameter shown as @expr{a} in the above table -which can be replaced by zero or one, as appropriate, by typing @kbd{h} -before the model key. - -Note that many of these models are essentially equivalent, but express -the parameters slightly differently. For example, @expr{a b^x} and -the other two exponential models are all algebraic rearrangements of -each other. Also, the ``quadratic'' model is just a degree-2 polynomial -with the parameters expressed differently. Use whichever form best -matches the problem. - -The HP-28/48 calculators support four different models for curve -fitting, called @code{LIN}, @code{LOG}, @code{EXP}, and @code{PWR}. -These correspond to Calc models @samp{a + b x}, @samp{a + b ln(x)}, -@samp{a exp(b x)}, and @samp{a x^b}, respectively. In each case, -@expr{a} is what the HP-48 identifies as the ``intercept,'' and -@expr{b} is what it calls the ``slope.'' - -@tex -\bigskip -@end tex - -If the model you want doesn't appear on this list, press @kbd{'} -(the apostrophe key) at the model prompt to enter any algebraic -formula, such as @kbd{m x - b}, as the model. (Not all models -will work, though---see the next section for details.) - -The model can also be an equation like @expr{y = m x + b}. -In this case, Calc thinks of all the rows of the data matrix on -equal terms; this model effectively has two parameters -(@expr{m} and @expr{b}) and two independent variables (@expr{x} -and @expr{y}), with no ``dependent'' variables. Model equations -do not need to take this @expr{y =} form. For example, the -implicit line equation @expr{a x + b y = 1} works fine as a -model. - -When you enter a model, Calc makes an alphabetical list of all -the variables that appear in the model. These are used for the -default parameters, independent variables, and dependent variable -(in that order). If you enter a plain formula (not an equation), -Calc assumes the dependent variable does not appear in the formula -and thus does not need a name. - -For example, if the model formula has the variables @expr{a,mu,sigma,t,x}, -and the data matrix has three rows (meaning two independent variables), -Calc will use @expr{a,mu,sigma} as the default parameters, and the -data rows will be named @expr{t} and @expr{x}, respectively. If you -enter an equation instead of a plain formula, Calc will use @expr{a,mu} -as the parameters, and @expr{sigma,t,x} as the three independent -variables. - -You can, of course, override these choices by entering something -different at the prompt. If you leave some variables out of the list, -those variables must have stored values and those stored values will -be used as constants in the model. (Stored values for the parameters -and independent variables are ignored by the @kbd{a F} command.) -If you list only independent variables, all the remaining variables -in the model formula will become parameters. - -If there are @kbd{$} signs in the model you type, they will stand -for parameters and all other variables (in alphabetical order) -will be independent. Use @kbd{$} for one parameter, @kbd{$$} for -another, and so on. Thus @kbd{$ x + $$} is another way to describe -a linear model. - -If you type a @kbd{$} instead of @kbd{'} at the model prompt itself, -Calc will take the model formula from the stack. (The data must then -appear at the second stack level.) The same conventions are used to -choose which variables in the formula are independent by default and -which are parameters. - -Models taken from the stack can also be expressed as vectors of -two or three elements, @expr{[@var{model}, @var{vars}]} or -@expr{[@var{model}, @var{vars}, @var{params}]}. Each of @var{vars} -and @var{params} may be either a variable or a vector of variables. -(If @var{params} is omitted, all variables in @var{model} except -those listed as @var{vars} are parameters.) - -When you enter a model manually with @kbd{'}, Calc puts a 3-vector -describing the model in the trail so you can get it back if you wish. - -@tex -\bigskip -@end tex - -@vindex Model1 -@vindex Model2 -Finally, you can store a model in one of the Calc variables -@code{Model1} or @code{Model2}, then use this model by typing -@kbd{a F u} or @kbd{a F U} (respectively). The value stored in -the variable can be any of the formats that @kbd{a F $} would -accept for a model on the stack. - -@tex -\bigskip -@end tex - -Calc uses the principal values of inverse functions like @code{ln} -and @code{arcsin} when doing fits. For example, when you enter -the model @samp{y = sin(a t + b)} Calc actually uses the easier -form @samp{arcsin(y) = a t + b}. The @code{arcsin} function always -returns results in the range from @mathit{-90} to 90 degrees (or the -equivalent range in radians). Suppose you had data that you -believed to represent roughly three oscillations of a sine wave, -so that the argument of the sine might go from zero to -@texline @math{3\times360} -@infoline @mathit{3*360} -degrees. -The above model would appear to be a good way to determine the -true frequency and phase of the sine wave, but in practice it -would fail utterly. The righthand side of the actual model -@samp{arcsin(y) = a t + b} will grow smoothly with @expr{t}, but -the lefthand side will bounce back and forth between @mathit{-90} and 90. -No values of @expr{a} and @expr{b} can make the two sides match, -even approximately. - -There is no good solution to this problem at present. You could -restrict your data to small enough ranges so that the above problem -doesn't occur (i.e., not straddling any peaks in the sine wave). -Or, in this case, you could use a totally different method such as -Fourier analysis, which is beyond the scope of the @kbd{a F} command. -(Unfortunately, Calc does not currently have any facilities for -taking Fourier and related transforms.) - -@node Curve Fitting Details, Interpolation, Standard Nonlinear Models, Curve Fitting -@subsection Curve Fitting Details - -@noindent -Calc's internal least-squares fitter can only handle multilinear -models. More precisely, it can handle any model of the form -@expr{a f(x,y,z) + b g(x,y,z) + c h(x,y,z)}, where @expr{a,b,c} -are the parameters and @expr{x,y,z} are the independent variables -(of course there can be any number of each, not just three). - -In a simple multilinear or polynomial fit, it is easy to see how -to convert the model into this form. For example, if the model -is @expr{a + b x + c x^2}, then @expr{f(x) = 1}, @expr{g(x) = x}, -and @expr{h(x) = x^2} are suitable functions. - -For most other models, Calc uses a variety of algebraic manipulations -to try to put the problem into the form - -@smallexample -Y(x,y,z) = A(a,b,c) F(x,y,z) + B(a,b,c) G(x,y,z) + C(a,b,c) H(x,y,z) -@end smallexample - -@noindent -where @expr{Y,A,B,C,F,G,H} are arbitrary functions. It computes -@expr{Y}, @expr{F}, @expr{G}, and @expr{H} for all the data points, -does a standard linear fit to find the values of @expr{A}, @expr{B}, -and @expr{C}, then uses the equation solver to solve for @expr{a,b,c} -in terms of @expr{A,B,C}. - -A remarkable number of models can be cast into this general form. -We'll look at two examples here to see how it works. The power-law -model @expr{y = a x^b} with two independent variables and two parameters -can be rewritten as follows: - -@example -y = a x^b -y = a exp(b ln(x)) -y = exp(ln(a) + b ln(x)) -ln(y) = ln(a) + b ln(x) -@end example - -@noindent -which matches the desired form with -@texline @math{Y = \ln(y)}, -@infoline @expr{Y = ln(y)}, -@texline @math{A = \ln(a)}, -@infoline @expr{A = ln(a)}, -@expr{F = 1}, @expr{B = b}, and -@texline @math{G = \ln(x)}. -@infoline @expr{G = ln(x)}. -Calc thus computes the logarithms of your @expr{y} and @expr{x} values, -does a linear fit for @expr{A} and @expr{B}, then solves to get -@texline @math{a = \exp(A)} -@infoline @expr{a = exp(A)} -and @expr{b = B}. - -Another interesting example is the ``quadratic'' model, which can -be handled by expanding according to the distributive law. - -@example -y = a + b*(x - c)^2 -y = a + b c^2 - 2 b c x + b x^2 -@end example - -@noindent -which matches with @expr{Y = y}, @expr{A = a + b c^2}, @expr{F = 1}, -@expr{B = -2 b c}, @expr{G = x} (the @mathit{-2} factor could just as easily -have been put into @expr{G} instead of @expr{B}), @expr{C = b}, and -@expr{H = x^2}. - -The Gaussian model looks quite complicated, but a closer examination -shows that it's actually similar to the quadratic model but with an -exponential that can be brought to the top and moved into @expr{Y}. - -The logistic models cannot be put into general linear form. For these -models, and the Hubbert linearization, Calc computes a rough -approximation for the parameters, then uses the Levenberg-Marquardt -iterative method to refine the approximations. - -Another model that cannot be put into general linear -form is a Gaussian with a constant background added on, i.e., -@expr{d} + the regular Gaussian formula. If you have a model like -this, your best bet is to replace enough of your parameters with -constants to make the model linearizable, then adjust the constants -manually by doing a series of fits. You can compare the fits by -graphing them, by examining the goodness-of-fit measures returned by -@kbd{I a F}, or by some other method suitable to your application. -Note that some models can be linearized in several ways. The -Gaussian-plus-@var{d} model can be linearized by setting @expr{d} -(the background) to a constant, or by setting @expr{b} (the standard -deviation) and @expr{c} (the mean) to constants. - -To fit a model with constants substituted for some parameters, just -store suitable values in those parameter variables, then omit them -from the list of parameters when you answer the variables prompt. - -@tex -\bigskip -@end tex - -A last desperate step would be to use the general-purpose -@code{minimize} function rather than @code{fit}. After all, both -functions solve the problem of minimizing an expression (the -@texline @math{\chi^2} -@infoline @expr{chi^2} -sum) by adjusting certain parameters in the expression. The @kbd{a F} -command is able to use a vastly more efficient algorithm due to its -special knowledge about linear chi-square sums, but the @kbd{a N} -command can do the same thing by brute force. - -A compromise would be to pick out a few parameters without which the -fit is linearizable, and use @code{minimize} on a call to @code{fit} -which efficiently takes care of the rest of the parameters. The thing -to be minimized would be the value of -@texline @math{\chi^2} -@infoline @expr{chi^2} -returned as the fifth result of the @code{xfit} function: - -@smallexample -minimize(xfit(gaus(a,b,c,d,x), x, [a,b,c], data)_5, d, guess) -@end smallexample - -@noindent -where @code{gaus} represents the Gaussian model with background, -@code{data} represents the data matrix, and @code{guess} represents -the initial guess for @expr{d} that @code{minimize} requires. -This operation will only be, shall we say, extraordinarily slow -rather than astronomically slow (as would be the case if @code{minimize} -were used by itself to solve the problem). - -@tex -\bigskip -@end tex - -The @kbd{I a F} [@code{xfit}] command is somewhat trickier when -nonlinear models are used. The second item in the result is the -vector of ``raw'' parameters @expr{A}, @expr{B}, @expr{C}. The -covariance matrix is written in terms of those raw parameters. -The fifth item is a vector of @dfn{filter} expressions. This -is the empty vector @samp{[]} if the raw parameters were the same -as the requested parameters, i.e., if @expr{A = a}, @expr{B = b}, -and so on (which is always true if the model is already linear -in the parameters as written, e.g., for polynomial fits). If the -parameters had to be rearranged, the fifth item is instead a vector -of one formula per parameter in the original model. The raw -parameters are expressed in these ``filter'' formulas as -@samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} for @expr{B}, -and so on. - -When Calc needs to modify the model to return the result, it replaces -@samp{fitdummy(1)} in all the filters with the first item in the raw -parameters list, and so on for the other raw parameters, then -evaluates the resulting filter formulas to get the actual parameter -values to be substituted into the original model. In the case of -@kbd{H a F} and @kbd{I a F} where the parameters must be error forms, -Calc uses the square roots of the diagonal entries of the covariance -matrix as error values for the raw parameters, then lets Calc's -standard error-form arithmetic take it from there. - -If you use @kbd{I a F} with a nonlinear model, be sure to remember -that the covariance matrix is in terms of the raw parameters, -@emph{not} the actual requested parameters. It's up to you to -figure out how to interpret the covariances in the presence of -nontrivial filter functions. - -Things are also complicated when the input contains error forms. -Suppose there are three independent and dependent variables, @expr{x}, -@expr{y}, and @expr{z}, one or more of which are error forms in the -data. Calc combines all the error values by taking the square root -of the sum of the squares of the errors. It then changes @expr{x} -and @expr{y} to be plain numbers, and makes @expr{z} into an error -form with this combined error. The @expr{Y(x,y,z)} part of the -linearized model is evaluated, and the result should be an error -form. The error part of that result is used for -@texline @math{\sigma_i} -@infoline @expr{sigma_i} -for the data point. If for some reason @expr{Y(x,y,z)} does not return -an error form, the combined error from @expr{z} is used directly for -@texline @math{\sigma_i}. -@infoline @expr{sigma_i}. -Finally, @expr{z} is also stripped of its error -for use in computing @expr{F(x,y,z)}, @expr{G(x,y,z)} and so on; -the righthand side of the linearized model is computed in regular -arithmetic with no error forms. - -(While these rules may seem complicated, they are designed to do -the most reasonable thing in the typical case that @expr{Y(x,y,z)} -depends only on the dependent variable @expr{z}, and in fact is -often simply equal to @expr{z}. For common cases like polynomials -and multilinear models, the combined error is simply used as the -@texline @math{\sigma} -@infoline @expr{sigma} -for the data point with no further ado.) - -@tex -\bigskip -@end tex - -@vindex FitRules -It may be the case that the model you wish to use is linearizable, -but Calc's built-in rules are unable to figure it out. Calc uses -its algebraic rewrite mechanism to linearize a model. The rewrite -rules are kept in the variable @code{FitRules}. You can edit this -variable using the @kbd{s e FitRules} command; in fact, there is -a special @kbd{s F} command just for editing @code{FitRules}. -@xref{Operations on Variables}. - -@xref{Rewrite Rules}, for a discussion of rewrite rules. - -@ignore -@starindex -@end ignore -@tindex fitvar -@ignore -@starindex -@end ignore -@ignore -@mindex @idots -@end ignore -@tindex fitparam -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitmodel -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitsystem -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex fitdummy -Calc uses @code{FitRules} as follows. First, it converts the model -to an equation if necessary and encloses the model equation in a -call to the function @code{fitmodel} (which is not actually a defined -function in Calc; it is only used as a placeholder by the rewrite rules). -Parameter variables are renamed to function calls @samp{fitparam(1)}, -@samp{fitparam(2)}, and so on, and independent variables are renamed -to @samp{fitvar(1)}, @samp{fitvar(2)}, etc. The dependent variable -is the highest-numbered @code{fitvar}. For example, the power law -model @expr{a x^b} is converted to @expr{y = a x^b}, then to - -@smallexample -@group -fitmodel(fitvar(2) = fitparam(1) fitvar(1)^fitparam(2)) -@end group -@end smallexample - -Calc then applies the rewrites as if by @samp{C-u 0 a r FitRules}. -(The zero prefix means that rewriting should continue until no further -changes are possible.) - -When rewriting is complete, the @code{fitmodel} call should have -been replaced by a @code{fitsystem} call that looks like this: - -@example -fitsystem(@var{Y}, @var{FGH}, @var{abc}) -@end example - -@noindent -where @var{Y} is a formula that describes the function @expr{Y(x,y,z)}, -@var{FGH} is the vector of formulas @expr{[F(x,y,z), G(x,y,z), H(x,y,z)]}, -and @var{abc} is the vector of parameter filters which refer to the -raw parameters as @samp{fitdummy(1)} for @expr{A}, @samp{fitdummy(2)} -for @expr{B}, etc. While the number of raw parameters (the length of -the @var{FGH} vector) is usually the same as the number of original -parameters (the length of the @var{abc} vector), this is not required. - -The power law model eventually boils down to - -@smallexample -@group -fitsystem(ln(fitvar(2)), - [1, ln(fitvar(1))], - [exp(fitdummy(1)), fitdummy(2)]) -@end group -@end smallexample - -The actual implementation of @code{FitRules} is complicated; it -proceeds in four phases. First, common rearrangements are done -to try to bring linear terms together and to isolate functions like -@code{exp} and @code{ln} either all the way ``out'' (so that they -can be put into @var{Y}) or all the way ``in'' (so that they can -be put into @var{abc} or @var{FGH}). In particular, all -non-constant powers are converted to logs-and-exponentials form, -and the distributive law is used to expand products of sums. -Quotients are rewritten to use the @samp{fitinv} function, where -@samp{fitinv(x)} represents @expr{1/x} while the @code{FitRules} -are operating. (The use of @code{fitinv} makes recognition of -linear-looking forms easier.) If you modify @code{FitRules}, you -will probably only need to modify the rules for this phase. - -Phase two, whose rules can actually also apply during phases one -and three, first rewrites @code{fitmodel} to a two-argument -form @samp{fitmodel(@var{Y}, @var{model})}, where @var{Y} is -initially zero and @var{model} has been changed from @expr{a=b} -to @expr{a-b} form. It then tries to peel off invertible functions -from the outside of @var{model} and put them into @var{Y} instead, -calling the equation solver to invert the functions. Finally, when -this is no longer possible, the @code{fitmodel} is changed to a -four-argument @code{fitsystem}, where the fourth argument is -@var{model} and the @var{FGH} and @var{abc} vectors are initially -empty. (The last vector is really @var{ABC}, corresponding to -raw parameters, for now.) - -Phase three converts a sum of items in the @var{model} to a sum -of @samp{fitpart(@var{a}, @var{b}, @var{c})} terms which represent -terms @samp{@var{a}*@var{b}*@var{c}} of the sum, where @var{a} -is all factors that do not involve any variables, @var{b} is all -factors that involve only parameters, and @var{c} is the factors -that involve only independent variables. (If this decomposition -is not possible, the rule set will not complete and Calc will -complain that the model is too complex.) Then @code{fitpart}s -with equal @var{b} or @var{c} components are merged back together -using the distributive law in order to minimize the number of -raw parameters needed. - -Phase four moves the @code{fitpart} terms into the @var{FGH} and -@var{ABC} vectors. Also, some of the algebraic expansions that -were done in phase 1 are undone now to make the formulas more -computationally efficient. Finally, it calls the solver one more -time to convert the @var{ABC} vector to an @var{abc} vector, and -removes the fourth @var{model} argument (which by now will be zero) -to obtain the three-argument @code{fitsystem} that the linear -least-squares solver wants to see. - -@ignore -@starindex -@end ignore -@ignore -@mindex hasfit@idots -@end ignore -@tindex hasfitparams -@ignore -@starindex -@end ignore -@ignore -@mindex @null -@end ignore -@tindex hasfitvars -Two functions which are useful in connection with @code{FitRules} -are @samp{hasfitparams(x)} and @samp{hasfitvars(x)}, which check -whether @expr{x} refers to any parameters or independent variables, -respectively. Specifically, these functions return ``true'' if the -argument contains any @code{fitparam} (or @code{fitvar}) function -calls, and ``false'' otherwise. (Recall that ``true'' means a -nonzero number, and ``false'' means zero. The actual nonzero number -returned is the largest @var{n} from all the @samp{fitparam(@var{n})}s -or @samp{fitvar(@var{n})}s, respectively, that appear in the formula.) - -@tex -\bigskip -@end tex - -The @code{fit} function in algebraic notation normally takes four -arguments, @samp{fit(@var{model}, @var{vars}, @var{params}, @var{data})}, -where @var{model} is the model formula as it would be typed after -@kbd{a F '}, @var{vars} is the independent variable or a vector of -independent variables, @var{params} likewise gives the parameter(s), -and @var{data} is the data matrix. Note that the length of @var{vars} -must be equal to the number of rows in @var{data} if @var{model} is -an equation, or one less than the number of rows if @var{model} is -a plain formula. (Actually, a name for the dependent variable is -allowed but will be ignored in the plain-formula case.) - -If @var{params} is omitted, the parameters are all variables in -@var{model} except those that appear in @var{vars}. If @var{vars} -is also omitted, Calc sorts all the variables that appear in -@var{model} alphabetically and uses the higher ones for @var{vars} -and the lower ones for @var{params}. - -Alternatively, @samp{fit(@var{modelvec}, @var{data})} is allowed -where @var{modelvec} is a 2- or 3-vector describing the model -and variables, as discussed previously. - -If Calc is unable to do the fit, the @code{fit} function is left -in symbolic form, ordinarily with an explanatory message. The -message will be ``Model expression is too complex'' if the -linearizer was unable to put the model into the required form. - -The @code{efit} (corresponding to @kbd{H a F}) and @code{xfit} -(for @kbd{I a F}) functions are completely analogous. - -@node Interpolation, , Curve Fitting Details, Curve Fitting -@subsection Polynomial Interpolation - -@kindex a p -@pindex calc-poly-interp -@tindex polint -The @kbd{a p} (@code{calc-poly-interp}) [@code{polint}] command does -a polynomial interpolation at a particular @expr{x} value. It takes -two arguments from the stack: A data matrix of the sort used by -@kbd{a F}, and a single number which represents the desired @expr{x} -value. Calc effectively does an exact polynomial fit as if by @kbd{a F i}, -then substitutes the @expr{x} value into the result in order to get an -approximate @expr{y} value based on the fit. (Calc does not actually -use @kbd{a F i}, however; it uses a direct method which is both more -efficient and more numerically stable.) - -The result of @kbd{a p} is actually a vector of two values: The @expr{y} -value approximation, and an error measure @expr{dy} that reflects Calc's -estimation of the probable error of the approximation at that value of -@expr{x}. If the input @expr{x} is equal to any of the @expr{x} values -in the data matrix, the output @expr{y} will be the corresponding @expr{y} -value from the matrix, and the output @expr{dy} will be exactly zero. - -A prefix argument of 2 causes @kbd{a p} to take separate x- and -y-vectors from the stack instead of one data matrix. - -If @expr{x} is a vector of numbers, @kbd{a p} will return a matrix of -interpolated results for each of those @expr{x} values. (The matrix will -have two columns, the @expr{y} values and the @expr{dy} values.) -If @expr{x} is a formula instead of a number, the @code{polint} function -remains in symbolic form; use the @kbd{a "} command to expand it out to -a formula that describes the fit in symbolic terms. - -In all cases, the @kbd{a p} command leaves the data vectors or matrix -on the stack. Only the @expr{x} value is replaced by the result. - -@kindex H a p -@tindex ratint -The @kbd{H a p} [@code{ratint}] command does a rational function -interpolation. It is used exactly like @kbd{a p}, except that it -uses as its model the quotient of two polynomials. If there are -@expr{N} data points, the numerator and denominator polynomials will -each have degree @expr{N/2} (if @expr{N} is odd, the denominator will -have degree one higher than the numerator). - -Rational approximations have the advantage that they can accurately -describe functions that have poles (points at which the function's value -goes to infinity, so that the denominator polynomial of the approximation -goes to zero). If @expr{x} corresponds to a pole of the fitted rational -function, then the result will be a division by zero. If Infinite mode -is enabled, the result will be @samp{[uinf, uinf]}. - -There is no way to get the actual coefficients of the rational function -used by @kbd{H a p}. (The algorithm never generates these coefficients -explicitly, and quotients of polynomials are beyond @w{@kbd{a F}}'s -capabilities to fit.) - -@node Summations, Logical Operations, Curve Fitting, Algebra -@section Summations - -@noindent -@cindex Summation of a series -@kindex a + -@pindex calc-summation -@tindex sum -The @kbd{a +} (@code{calc-summation}) [@code{sum}] command computes -the sum of a formula over a certain range of index values. The formula -is taken from the top of the stack; the command prompts for the -name of the summation index variable, the lower limit of the -sum (any formula), and the upper limit of the sum. If you -enter a blank line at any of these prompts, that prompt and -any later ones are answered by reading additional elements from -the stack. Thus, @kbd{' k^2 @key{RET} ' k @key{RET} 1 @key{RET} 5 @key{RET} a + @key{RET}} -produces the result 55. -@tex -\turnoffactive -$$ \sum_{k=1}^5 k^2 = 55 $$ -@end tex - -The choice of index variable is arbitrary, but it's best not to -use a variable with a stored value. In particular, while -@code{i} is often a favorite index variable, it should be avoided -in Calc because @code{i} has the imaginary constant @expr{(0, 1)} -as a value. If you pressed @kbd{=} on a sum over @code{i}, it would -be changed to a nonsensical sum over the ``variable'' @expr{(0, 1)}! -If you really want to use @code{i} as an index variable, use -@w{@kbd{s u i @key{RET}}} first to ``unstore'' this variable. -(@xref{Storing Variables}.) - -A numeric prefix argument steps the index by that amount rather -than by one. Thus @kbd{' a_k @key{RET} C-u -2 a + k @key{RET} 10 @key{RET} 0 @key{RET}} -yields @samp{a_10 + a_8 + a_6 + a_4 + a_2 + a_0}. A prefix -argument of plain @kbd{C-u} causes @kbd{a +} to prompt for the -step value, in which case you can enter any formula or enter -a blank line to take the step value from the stack. With the -@kbd{C-u} prefix, @kbd{a +} can take up to five arguments from -the stack: The formula, the variable, the lower limit, the -upper limit, and (at the top of the stack), the step value. - -Calc knows how to do certain sums in closed form. For example, -@samp{sum(6 k^2, k, 1, n) = @w{2 n^3} + 3 n^2 + n}. In particular, -this is possible if the formula being summed is polynomial or -exponential in the index variable. Sums of logarithms are -transformed into logarithms of products. Sums of trigonometric -and hyperbolic functions are transformed to sums of exponentials -and then done in closed form. Also, of course, sums in which the -lower and upper limits are both numbers can always be evaluated -just by grinding them out, although Calc will use closed forms -whenever it can for the sake of efficiency. - -The notation for sums in algebraic formulas is -@samp{sum(@var{expr}, @var{var}, @var{low}, @var{high}, @var{step})}. -If @var{step} is omitted, it defaults to one. If @var{high} is -omitted, @var{low} is actually the upper limit and the lower limit -is one. If @var{low} is also omitted, the limits are @samp{-inf} -and @samp{inf}, respectively. - -Infinite sums can sometimes be evaluated: @samp{sum(.5^k, k, 1, inf)} -returns @expr{1}. This is done by evaluating the sum in closed -form (to @samp{1. - 0.5^n} in this case), then evaluating this -formula with @code{n} set to @code{inf}. Calc's usual rules -for ``infinite'' arithmetic can find the answer from there. If -infinite arithmetic yields a @samp{nan}, or if the sum cannot be -solved in closed form, Calc leaves the @code{sum} function in -symbolic form. @xref{Infinities}. - -As a special feature, if the limits are infinite (or omitted, as -described above) but the formula includes vectors subscripted by -expressions that involve the iteration variable, Calc narrows -the limits to include only the range of integers which result in -valid subscripts for the vector. For example, the sum -@samp{sum(k [a,b,c,d,e,f,g]_(2k),k)} evaluates to @samp{b + 2 d + 3 f}. - -The limits of a sum do not need to be integers. For example, -@samp{sum(a_k, k, 0, 2 n, n)} produces @samp{a_0 + a_n + a_(2 n)}. -Calc computes the number of iterations using the formula -@samp{1 + (@var{high} - @var{low}) / @var{step}}, which must, -after simplification as if by @kbd{a s}, evaluate to an integer. - -If the number of iterations according to the above formula does -not come out to an integer, the sum is invalid and will be left -in symbolic form. However, closed forms are still supplied, and -you are on your honor not to misuse the resulting formulas by -substituting mismatched bounds into them. For example, -@samp{sum(k, k, 1, 10, 2)} is invalid, but Calc will go ahead and -evaluate the closed form solution for the limits 1 and 10 to get -the rather dubious answer, 29.25. - -If the lower limit is greater than the upper limit (assuming a -positive step size), the result is generally zero. However, -Calc only guarantees a zero result when the upper limit is -exactly one step less than the lower limit, i.e., if the number -of iterations is @mathit{-1}. Thus @samp{sum(f(k), k, n, n-1)} is zero -but the sum from @samp{n} to @samp{n-2} may report a nonzero value -if Calc used a closed form solution. - -Calc's logical predicates like @expr{a < b} return 1 for ``true'' -and 0 for ``false.'' @xref{Logical Operations}. This can be -used to advantage for building conditional sums. For example, -@samp{sum(prime(k)*k^2, k, 1, 20)} is the sum of the squares of all -prime numbers from 1 to 20; the @code{prime} predicate returns 1 if -its argument is prime and 0 otherwise. You can read this expression -as ``the sum of @expr{k^2}, where @expr{k} is prime.'' Indeed, -@samp{sum(prime(k)*k^2, k)} would represent the sum of @emph{all} primes -squared, since the limits default to plus and minus infinity, but -there are no such sums that Calc's built-in rules can do in -closed form. - -As another example, @samp{sum((k != k_0) * f(k), k, 1, n)} is the -sum of @expr{f(k)} for all @expr{k} from 1 to @expr{n}, excluding -one value @expr{k_0}. Slightly more tricky is the summand -@samp{(k != k_0) / (k - k_0)}, which is an attempt to describe -the sum of all @expr{1/(k-k_0)} except at @expr{k = k_0}, where -this would be a division by zero. But at @expr{k = k_0}, this -formula works out to the indeterminate form @expr{0 / 0}, which -Calc will not assume is zero. Better would be to use -@samp{(k != k_0) ? 1/(k-k_0) : 0}; the @samp{? :} operator does -an ``if-then-else'' test: This expression says, ``if -@texline @math{k \ne k_0}, -@infoline @expr{k != k_0}, -then @expr{1/(k-k_0)}, else zero.'' Now the formula @expr{1/(k-k_0)} -will not even be evaluated by Calc when @expr{k = k_0}. - -@cindex Alternating sums -@kindex a - -@pindex calc-alt-summation -@tindex asum -The @kbd{a -} (@code{calc-alt-summation}) [@code{asum}] command -computes an alternating sum. Successive terms of the sequence -are given alternating signs, with the first term (corresponding -to the lower index value) being positive. Alternating sums -are converted to normal sums with an extra term of the form -@samp{(-1)^(k-@var{low})}. This formula is adjusted appropriately -if the step value is other than one. For example, the Taylor -series for the sine function is @samp{asum(x^k / k!, k, 1, inf, 2)}. -(Calc cannot evaluate this infinite series, but it can approximate -it if you replace @code{inf} with any particular odd number.) -Calc converts this series to a regular sum with a step of one, -namely @samp{sum((-1)^k x^(2k+1) / (2k+1)!, k, 0, inf)}. - -@cindex Product of a sequence -@kindex a * -@pindex calc-product -@tindex prod -The @kbd{a *} (@code{calc-product}) [@code{prod}] command is -the analogous way to take a product of many terms. Calc also knows -some closed forms for products, such as @samp{prod(k, k, 1, n) = n!}. -Conditional products can be written @samp{prod(k^prime(k), k, 1, n)} -or @samp{prod(prime(k) ? k : 1, k, 1, n)}. - -@kindex a T -@pindex calc-tabulate -@tindex table -The @kbd{a T} (@code{calc-tabulate}) [@code{table}] command -evaluates a formula at a series of iterated index values, just -like @code{sum} and @code{prod}, but its result is simply a -vector of the results. For example, @samp{table(a_i, i, 1, 7, 2)} -produces @samp{[a_1, a_3, a_5, a_7]}. - -@node Logical Operations, Rewrite Rules, Summations, Algebra -@section Logical Operations - -@noindent -The following commands and algebraic functions return true/false values, -where 1 represents ``true'' and 0 represents ``false.'' In cases where -a truth value is required (such as for the condition part of a rewrite -rule, or as the condition for a @w{@kbd{Z [ Z ]}} control structure), any -nonzero value is accepted to mean ``true.'' (Specifically, anything -for which @code{dnonzero} returns 1 is ``true,'' and anything for -which @code{dnonzero} returns 0 or cannot decide is assumed ``false.'' -Note that this means that @w{@kbd{Z [ Z ]}} will execute the ``then'' -portion if its condition is provably true, but it will execute the -``else'' portion for any condition like @expr{a = b} that is not -provably true, even if it might be true. Algebraic functions that -have conditions as arguments, like @code{? :} and @code{&&}, remain -unevaluated if the condition is neither provably true nor provably -false. @xref{Declarations}.) - -@kindex a = -@pindex calc-equal-to -@tindex eq -@tindex = -@tindex == -The @kbd{a =} (@code{calc-equal-to}) command, or @samp{eq(a,b)} function -(which can also be written @samp{a = b} or @samp{a == b} in an algebraic -formula) is true if @expr{a} and @expr{b} are equal, either because they -are identical expressions, or because they are numbers which are -numerically equal. (Thus the integer 1 is considered equal to the float -1.0.) If the equality of @expr{a} and @expr{b} cannot be determined, -the comparison is left in symbolic form. Note that as a command, this -operation pops two values from the stack and pushes back either a 1 or -a 0, or a formula @samp{a = b} if the values' equality cannot be determined. - -Many Calc commands use @samp{=} formulas to represent @dfn{equations}. -For example, the @kbd{a S} (@code{calc-solve-for}) command rearranges -an equation to solve for a given variable. The @kbd{a M} -(@code{calc-map-equation}) command can be used to apply any -function to both sides of an equation; for example, @kbd{2 a M *} -multiplies both sides of the equation by two. Note that just -@kbd{2 *} would not do the same thing; it would produce the formula -@samp{2 (a = b)} which represents 2 if the equality is true or -zero if not. - -The @code{eq} function with more than two arguments (e.g., @kbd{C-u 3 a =} -or @samp{a = b = c}) tests if all of its arguments are equal. In -algebraic notation, the @samp{=} operator is unusual in that it is -neither left- nor right-associative: @samp{a = b = c} is not the -same as @samp{(a = b) = c} or @samp{a = (b = c)} (which each compare -one variable with the 1 or 0 that results from comparing two other -variables). - -@kindex a # -@pindex calc-not-equal-to -@tindex neq -@tindex != -The @kbd{a #} (@code{calc-not-equal-to}) command, or @samp{neq(a,b)} or -@samp{a != b} function, is true if @expr{a} and @expr{b} are not equal. -This also works with more than two arguments; @samp{a != b != c != d} -tests that all four of @expr{a}, @expr{b}, @expr{c}, and @expr{d} are -distinct numbers. - -@kindex a < -@tindex lt -@ignore -@mindex @idots -@end ignore -@kindex a > -@ignore -@mindex @null -@end ignore -@kindex a [ -@ignore -@mindex @null -@end ignore -@kindex a ] -@pindex calc-less-than -@pindex calc-greater-than -@pindex calc-less-equal -@pindex calc-greater-equal -@ignore -@mindex @null -@end ignore -@tindex gt -@ignore -@mindex @null -@end ignore -@tindex leq -@ignore -@mindex @null -@end ignore -@tindex geq -@ignore -@mindex @null -@end ignore -@tindex < -@ignore -@mindex @null -@end ignore -@tindex > -@ignore -@mindex @null -@end ignore -@tindex <= -@ignore -@mindex @null -@end ignore -@tindex >= -The @kbd{a <} (@code{calc-less-than}) [@samp{lt(a,b)} or @samp{a < b}] -operation is true if @expr{a} is less than @expr{b}. Similar functions -are @kbd{a >} (@code{calc-greater-than}) [@samp{gt(a,b)} or @samp{a > b}], -@kbd{a [} (@code{calc-less-equal}) [@samp{leq(a,b)} or @samp{a <= b}], and -@kbd{a ]} (@code{calc-greater-equal}) [@samp{geq(a,b)} or @samp{a >= b}]. - -While the inequality functions like @code{lt} do not accept more -than two arguments, the syntax @w{@samp{a <= b < c}} is translated to an -equivalent expression involving intervals: @samp{b in [a .. c)}. -(See the description of @code{in} below.) All four combinations -of @samp{<} and @samp{<=} are allowed, or any of the four combinations -of @samp{>} and @samp{>=}. Four-argument constructions like -@samp{a < b < c < d}, and mixtures like @w{@samp{a < b = c}} that -involve both equalities and inequalities, are not allowed. - -@kindex a . -@pindex calc-remove-equal -@tindex rmeq -The @kbd{a .} (@code{calc-remove-equal}) [@code{rmeq}] command extracts -the righthand side of the equation or inequality on the top of the -stack. It also works elementwise on vectors. For example, if -@samp{[x = 2.34, y = z / 2]} is on the stack, then @kbd{a .} produces -@samp{[2.34, z / 2]}. As a special case, if the righthand side is a -variable and the lefthand side is a number (as in @samp{2.34 = x}), then -Calc keeps the lefthand side instead. Finally, this command works with -assignments @samp{x := 2.34} as well as equations, always taking the -righthand side, and for @samp{=>} (evaluates-to) operators, always -taking the lefthand side. - -@kindex a & -@pindex calc-logical-and -@tindex land -@tindex && -The @kbd{a &} (@code{calc-logical-and}) [@samp{land(a,b)} or @samp{a && b}] -function is true if both of its arguments are true, i.e., are -non-zero numbers. In this case, the result will be either @expr{a} or -@expr{b}, chosen arbitrarily. If either argument is zero, the result is -zero. Otherwise, the formula is left in symbolic form. - -@kindex a | -@pindex calc-logical-or -@tindex lor -@tindex || -The @kbd{a |} (@code{calc-logical-or}) [@samp{lor(a,b)} or @samp{a || b}] -function is true if either or both of its arguments are true (nonzero). -The result is whichever argument was nonzero, choosing arbitrarily if both -are nonzero. If both @expr{a} and @expr{b} are zero, the result is -zero. - -@kindex a ! -@pindex calc-logical-not -@tindex lnot -@tindex ! -The @kbd{a !} (@code{calc-logical-not}) [@samp{lnot(a)} or @samp{!@: a}] -function is true if @expr{a} is false (zero), or false if @expr{a} is -true (nonzero). It is left in symbolic form if @expr{a} is not a -number. - -@kindex a : -@pindex calc-logical-if -@tindex if -@ignore -@mindex ? : -@end ignore -@tindex ? -@ignore -@mindex @null -@end ignore -@tindex : -@cindex Arguments, not evaluated -The @kbd{a :} (@code{calc-logical-if}) [@samp{if(a,b,c)} or @samp{a ? b :@: c}] -function is equal to either @expr{b} or @expr{c} if @expr{a} is a nonzero -number or zero, respectively. If @expr{a} is not a number, the test is -left in symbolic form and neither @expr{b} nor @expr{c} is evaluated in -any way. In algebraic formulas, this is one of the few Calc functions -whose arguments are not automatically evaluated when the function itself -is evaluated. The others are @code{lambda}, @code{quote}, and -@code{condition}. - -One minor surprise to watch out for is that the formula @samp{a?3:4} -will not work because the @samp{3:4} is parsed as a fraction instead of -as three separate symbols. Type something like @samp{a ? 3 : 4} or -@samp{a?(3):4} instead. - -As a special case, if @expr{a} evaluates to a vector, then both @expr{b} -and @expr{c} are evaluated; the result is a vector of the same length -as @expr{a} whose elements are chosen from corresponding elements of -@expr{b} and @expr{c} according to whether each element of @expr{a} -is zero or nonzero. Each of @expr{b} and @expr{c} must be either a -vector of the same length as @expr{a}, or a non-vector which is matched -with all elements of @expr{a}. - -@kindex a @{ -@pindex calc-in-set -@tindex in -The @kbd{a @{} (@code{calc-in-set}) [@samp{in(a,b)}] function is true if -the number @expr{a} is in the set of numbers represented by @expr{b}. -If @expr{b} is an interval form, @expr{a} must be one of the values -encompassed by the interval. If @expr{b} is a vector, @expr{a} must be -equal to one of the elements of the vector. (If any vector elements are -intervals, @expr{a} must be in any of the intervals.) If @expr{b} is a -plain number, @expr{a} must be numerically equal to @expr{b}. -@xref{Set Operations}, for a group of commands that manipulate sets -of this sort. - -@ignore -@starindex -@end ignore -@tindex typeof -The @samp{typeof(a)} function produces an integer or variable which -characterizes @expr{a}. If @expr{a} is a number, vector, or variable, -the result will be one of the following numbers: - -@example - 1 Integer - 2 Fraction - 3 Floating-point number - 4 HMS form - 5 Rectangular complex number - 6 Polar complex number - 7 Error form - 8 Interval form - 9 Modulo form -10 Date-only form -11 Date/time form -12 Infinity (inf, uinf, or nan) -100 Variable -101 Vector (but not a matrix) -102 Matrix -@end example - -Otherwise, @expr{a} is a formula, and the result is a variable which -represents the name of the top-level function call. - -@ignore -@starindex -@end ignore -@tindex integer -@ignore -@starindex -@end ignore -@tindex real -@ignore -@starindex -@end ignore -@tindex constant -The @samp{integer(a)} function returns true if @expr{a} is an integer. -The @samp{real(a)} function -is true if @expr{a} is a real number, either integer, fraction, or -float. The @samp{constant(a)} function returns true if @expr{a} is -any of the objects for which @code{typeof} would produce an integer -code result except for variables, and provided that the components of -an object like a vector or error form are themselves constant. -Note that infinities do not satisfy any of these tests, nor do -special constants like @code{pi} and @code{e}. - -@xref{Declarations}, for a set of similar functions that recognize -formulas as well as actual numbers. For example, @samp{dint(floor(x))} -is true because @samp{floor(x)} is provably integer-valued, but -@samp{integer(floor(x))} does not because @samp{floor(x)} is not -literally an integer constant. - -@ignore -@starindex -@end ignore -@tindex refers -The @samp{refers(a,b)} function is true if the variable (or sub-expression) -@expr{b} appears in @expr{a}, or false otherwise. Unlike the other -tests described here, this function returns a definite ``no'' answer -even if its arguments are still in symbolic form. The only case where -@code{refers} will be left unevaluated is if @expr{a} is a plain -variable (different from @expr{b}). - -@ignore -@starindex -@end ignore -@tindex negative -The @samp{negative(a)} function returns true if @expr{a} ``looks'' negative, -because it is a negative number, because it is of the form @expr{-x}, -or because it is a product or quotient with a term that looks negative. -This is most useful in rewrite rules. Beware that @samp{negative(a)} -evaluates to 1 or 0 for @emph{any} argument @expr{a}, so it can only -be stored in a formula if the default simplifications are turned off -first with @kbd{m O} (or if it appears in an unevaluated context such -as a rewrite rule condition). - -@ignore -@starindex -@end ignore -@tindex variable -The @samp{variable(a)} function is true if @expr{a} is a variable, -or false if not. If @expr{a} is a function call, this test is left -in symbolic form. Built-in variables like @code{pi} and @code{inf} -are considered variables like any others by this test. - -@ignore -@starindex -@end ignore -@tindex nonvar -The @samp{nonvar(a)} function is true if @expr{a} is a non-variable. -If its argument is a variable it is left unsimplified; it never -actually returns zero. However, since Calc's condition-testing -commands consider ``false'' anything not provably true, this is -often good enough. - -@ignore -@starindex -@end ignore -@tindex lin -@ignore -@starindex -@end ignore -@tindex linnt -@ignore -@starindex -@end ignore -@tindex islin -@ignore -@starindex -@end ignore -@tindex islinnt -@cindex Linearity testing -The functions @code{lin}, @code{linnt}, @code{islin}, and @code{islinnt} -check if an expression is ``linear,'' i.e., can be written in the form -@expr{a + b x} for some constants @expr{a} and @expr{b}, and some -variable or subformula @expr{x}. The function @samp{islin(f,x)} checks -if formula @expr{f} is linear in @expr{x}, returning 1 if so. For -example, @samp{islin(x,x)}, @samp{islin(-x,x)}, @samp{islin(3,x)}, and -@samp{islin(x y / 3 - 2, x)} all return 1. The @samp{lin(f,x)} function -is similar, except that instead of returning 1 it returns the vector -@expr{[a, b, x]}. For the above examples, this vector would be -@expr{[0, 1, x]}, @expr{[0, -1, x]}, @expr{[3, 0, x]}, and -@expr{[-2, y/3, x]}, respectively. Both @code{lin} and @code{islin} -generally remain unevaluated for expressions which are not linear, -e.g., @samp{lin(2 x^2, x)} and @samp{lin(sin(x), x)}. The second -argument can also be a formula; @samp{islin(2 + 3 sin(x), sin(x))} -returns true. - -The @code{linnt} and @code{islinnt} functions perform a similar check, -but require a ``non-trivial'' linear form, which means that the -@expr{b} coefficient must be non-zero. For example, @samp{lin(2,x)} -returns @expr{[2, 0, x]} and @samp{lin(y,x)} returns @expr{[y, 0, x]}, -but @samp{linnt(2,x)} and @samp{linnt(y,x)} are left unevaluated -(in other words, these formulas are considered to be only ``trivially'' -linear in @expr{x}). - -All four linearity-testing functions allow you to omit the second -argument, in which case the input may be linear in any non-constant -formula. Here, the @expr{a=0}, @expr{b=1} case is also considered -trivial, and only constant values for @expr{a} and @expr{b} are -recognized. Thus, @samp{lin(2 x y)} returns @expr{[0, 2, x y]}, -@samp{lin(2 - x y)} returns @expr{[2, -1, x y]}, and @samp{lin(x y)} -returns @expr{[0, 1, x y]}. The @code{linnt} function would allow the -first two cases but not the third. Also, neither @code{lin} nor -@code{linnt} accept plain constants as linear in the one-argument -case: @samp{islin(2,x)} is true, but @samp{islin(2)} is false. - -@ignore -@starindex -@end ignore -@tindex istrue -The @samp{istrue(a)} function returns 1 if @expr{a} is a nonzero -number or provably nonzero formula, or 0 if @expr{a} is anything else. -Calls to @code{istrue} can only be manipulated if @kbd{m O} mode is -used to make sure they are not evaluated prematurely. (Note that -declarations are used when deciding whether a formula is true; -@code{istrue} returns 1 when @code{dnonzero} would return 1, and -it returns 0 when @code{dnonzero} would return 0 or leave itself -in symbolic form.) - -@node Rewrite Rules, , Logical Operations, Algebra -@section Rewrite Rules - -@noindent -@cindex Rewrite rules -@cindex Transformations -@cindex Pattern matching -@kindex a r -@pindex calc-rewrite -@tindex rewrite -The @kbd{a r} (@code{calc-rewrite}) [@code{rewrite}] command makes -substitutions in a formula according to a specified pattern or patterns -known as @dfn{rewrite rules}. Whereas @kbd{a b} (@code{calc-substitute}) -matches literally, so that substituting @samp{sin(x)} with @samp{cos(x)} -matches only the @code{sin} function applied to the variable @code{x}, -rewrite rules match general kinds of formulas; rewriting using the rule -@samp{sin(x) := cos(x)} matches @code{sin} of any argument and replaces -it with @code{cos} of that same argument. The only significance of the -name @code{x} is that the same name is used on both sides of the rule. - -Rewrite rules rearrange formulas already in Calc's memory. -@xref{Syntax Tables}, to read about @dfn{syntax rules}, which are -similar to algebraic rewrite rules but operate when new algebraic -entries are being parsed, converting strings of characters into -Calc formulas. - -@menu -* Entering Rewrite Rules:: -* Basic Rewrite Rules:: -* Conditional Rewrite Rules:: -* Algebraic Properties of Rewrite Rules:: -* Other Features of Rewrite Rules:: -* Composing Patterns in Rewrite Rules:: -* Nested Formulas with Rewrite Rules:: -* Multi-Phase Rewrite Rules:: -* Selections with Rewrite Rules:: -* Matching Commands:: -* Automatic Rewrites:: -* Debugging Rewrites:: -* Examples of Rewrite Rules:: -@end menu - -@node Entering Rewrite Rules, Basic Rewrite Rules, Rewrite Rules, Rewrite Rules -@subsection Entering Rewrite Rules - -@noindent -Rewrite rules normally use the ``assignment'' operator -@samp{@var{old} := @var{new}}. -This operator is equivalent to the function call @samp{assign(old, new)}. -The @code{assign} function is undefined by itself in Calc, so an -assignment formula such as a rewrite rule will be left alone by ordinary -Calc commands. But certain commands, like the rewrite system, interpret -assignments in special ways. - -For example, the rule @samp{sin(x)^2 := 1-cos(x)^2} says to replace -every occurrence of the sine of something, squared, with one minus the -square of the cosine of that same thing. All by itself as a formula -on the stack it does nothing, but when given to the @kbd{a r} command -it turns that command into a sine-squared-to-cosine-squared converter. - -To specify a set of rules to be applied all at once, make a vector of -rules. - -When @kbd{a r} prompts you to enter the rewrite rules, you can answer -in several ways: - -@enumerate -@item -With a rule: @kbd{f(x) := g(x) @key{RET}}. -@item -With a vector of rules: @kbd{[f1(x) := g1(x), f2(x) := g2(x)] @key{RET}}. -(You can omit the enclosing square brackets if you wish.) -@item -With the name of a variable that contains the rule or rules vector: -@kbd{myrules @key{RET}}. -@item -With any formula except a rule, a vector, or a variable name; this -will be interpreted as the @var{old} half of a rewrite rule, -and you will be prompted a second time for the @var{new} half: -@kbd{f(x) @key{RET} g(x) @key{RET}}. -@item -With a blank line, in which case the rule, rules vector, or variable -will be taken from the top of the stack (and the formula to be -rewritten will come from the second-to-top position). -@end enumerate - -If you enter the rules directly (as opposed to using rules stored -in a variable), those rules will be put into the Trail so that you -can retrieve them later. @xref{Trail Commands}. - -It is most convenient to store rules you use often in a variable and -invoke them by giving the variable name. The @kbd{s e} -(@code{calc-edit-variable}) command is an easy way to create or edit a -rule set stored in a variable. You may also wish to use @kbd{s p} -(@code{calc-permanent-variable}) to save your rules permanently; -@pxref{Operations on Variables}. - -Rewrite rules are compiled into a special internal form for faster -matching. If you enter a rule set directly it must be recompiled -every time. If you store the rules in a variable and refer to them -through that variable, they will be compiled once and saved away -along with the variable for later reference. This is another good -reason to store your rules in a variable. - -Calc also accepts an obsolete notation for rules, as vectors -@samp{[@var{old}, @var{new}]}. But because it is easily confused with a -vector of two rules, the use of this notation is no longer recommended. - -@node Basic Rewrite Rules, Conditional Rewrite Rules, Entering Rewrite Rules, Rewrite Rules -@subsection Basic Rewrite Rules - -@noindent -To match a particular formula @expr{x} with a particular rewrite rule -@samp{@var{old} := @var{new}}, Calc compares the structure of @expr{x} with -the structure of @var{old}. Variables that appear in @var{old} are -treated as @dfn{meta-variables}; the corresponding positions in @expr{x} -may contain any sub-formulas. For example, the pattern @samp{f(x,y)} -would match the expression @samp{f(12, a+1)} with the meta-variable -@samp{x} corresponding to 12 and with @samp{y} corresponding to -@samp{a+1}. However, this pattern would not match @samp{f(12)} or -@samp{g(12, a+1)}, since there is no assignment of the meta-variables -that will make the pattern match these expressions. Notice that if -the pattern is a single meta-variable, it will match any expression. - -If a given meta-variable appears more than once in @var{old}, the -corresponding sub-formulas of @expr{x} must be identical. Thus -the pattern @samp{f(x,x)} would match @samp{f(12, 12)} and -@samp{f(a+1, a+1)} but not @samp{f(12, a+1)} or @samp{f(a+b, b+a)}. -(@xref{Conditional Rewrite Rules}, for a way to match the latter.) - -Things other than variables must match exactly between the pattern -and the target formula. To match a particular variable exactly, use -the pseudo-function @samp{quote(v)} in the pattern. For example, the -pattern @samp{x+quote(y)} matches @samp{x+y}, @samp{2+y}, or -@samp{sin(a)+y}. - -The special variable names @samp{e}, @samp{pi}, @samp{i}, @samp{phi}, -@samp{gamma}, @samp{inf}, @samp{uinf}, and @samp{nan} always match -literally. Thus the pattern @samp{sin(d + e + f)} acts exactly like -@samp{sin(d + quote(e) + f)}. - -If the @var{old} pattern is found to match a given formula, that -formula is replaced by @var{new}, where any occurrences in @var{new} -of meta-variables from the pattern are replaced with the sub-formulas -that they matched. Thus, applying the rule @samp{f(x,y) := g(y+x,x)} -to @samp{f(12, a+1)} would produce @samp{g(a+13, 12)}. - -The normal @kbd{a r} command applies rewrite rules over and over -throughout the target formula until no further changes are possible -(up to a limit of 100 times). Use @kbd{C-u 1 a r} to make only one -change at a time. - -@node Conditional Rewrite Rules, Algebraic Properties of Rewrite Rules, Basic Rewrite Rules, Rewrite Rules -@subsection Conditional Rewrite Rules - -@noindent -A rewrite rule can also be @dfn{conditional}, written in the form -@samp{@var{old} := @var{new} :: @var{cond}}. (There is also the obsolete -form @samp{[@var{old}, @var{new}, @var{cond}]}.) If a @var{cond} part -is present in the -rule, this is an additional condition that must be satisfied before -the rule is accepted. Once @var{old} has been successfully matched -to the target expression, @var{cond} is evaluated (with all the -meta-variables substituted for the values they matched) and simplified -with @kbd{a s} (@code{calc-simplify}). If the result is a nonzero -number or any other object known to be nonzero (@pxref{Declarations}), -the rule is accepted. If the result is zero or if it is a symbolic -formula that is not known to be nonzero, the rule is rejected. -@xref{Logical Operations}, for a number of functions that return -1 or 0 according to the results of various tests. - -For example, the formula @samp{n > 0} simplifies to 1 or 0 if @expr{n} -is replaced by a positive or nonpositive number, respectively (or if -@expr{n} has been declared to be positive or nonpositive). Thus, -the rule @samp{f(x,y) := g(y+x,x) :: x+y > 0} would apply to -@samp{f(0, 4)} but not to @samp{f(-3, 2)} or @samp{f(12, a+1)} -(assuming no outstanding declarations for @expr{a}). In the case of -@samp{f(-3, 2)}, the condition can be shown not to be satisfied; in -the case of @samp{f(12, a+1)}, the condition merely cannot be shown -to be satisfied, but that is enough to reject the rule. - -While Calc will use declarations to reason about variables in the -formula being rewritten, declarations do not apply to meta-variables. -For example, the rule @samp{f(a) := g(a+1)} will match for any values -of @samp{a}, such as complex numbers, vectors, or formulas, even if -@samp{a} has been declared to be real or scalar. If you want the -meta-variable @samp{a} to match only literal real numbers, use -@samp{f(a) := g(a+1) :: real(a)}. If you want @samp{a} to match only -reals and formulas which are provably real, use @samp{dreal(a)} as -the condition. - -The @samp{::} operator is a shorthand for the @code{condition} -function; @samp{@var{old} := @var{new} :: @var{cond}} is equivalent to -the formula @samp{condition(assign(@var{old}, @var{new}), @var{cond})}. - -If you have several conditions, you can use @samp{... :: c1 :: c2 :: c3} -or @samp{... :: c1 && c2 && c3}. The two are entirely equivalent. - -It is also possible to embed conditions inside the pattern: -@samp{f(x :: x>0, y) := g(y+x, x)}. This is purely a notational -convenience, though; where a condition appears in a rule has no -effect on when it is tested. The rewrite-rule compiler automatically -decides when it is best to test each condition while a rule is being -matched. - -Certain conditions are handled as special cases by the rewrite rule -system and are tested very efficiently: Where @expr{x} is any -meta-variable, these conditions are @samp{integer(x)}, @samp{real(x)}, -@samp{constant(x)}, @samp{negative(x)}, @samp{x >= y} where @expr{y} -is either a constant or another meta-variable and @samp{>=} may be -replaced by any of the six relational operators, and @samp{x % a = b} -where @expr{a} and @expr{b} are constants. Other conditions, like -@samp{x >= y+1} or @samp{dreal(x)}, will be less efficient to check -since Calc must bring the whole evaluator and simplifier into play. - -An interesting property of @samp{::} is that neither of its arguments -will be touched by Calc's default simplifications. This is important -because conditions often are expressions that cannot safely be -evaluated early. For example, the @code{typeof} function never -remains in symbolic form; entering @samp{typeof(a)} will put the -number 100 (the type code for variables like @samp{a}) on the stack. -But putting the condition @samp{... :: typeof(a) = 6} on the stack -is safe since @samp{::} prevents the @code{typeof} from being -evaluated until the condition is actually used by the rewrite system. - -Since @samp{::} protects its lefthand side, too, you can use a dummy -condition to protect a rule that must itself not evaluate early. -For example, it's not safe to put @samp{a(f,x) := apply(f, [x])} on -the stack because it will immediately evaluate to @samp{a(f,x) := f(x)}, -where the meta-variable-ness of @code{f} on the righthand side has been -lost. But @samp{a(f,x) := apply(f, [x]) :: 1} is safe, and of course -the condition @samp{1} is always true (nonzero) so it has no effect on -the functioning of the rule. (The rewrite compiler will ensure that -it doesn't even impact the speed of matching the rule.) - -@node Algebraic Properties of Rewrite Rules, Other Features of Rewrite Rules, Conditional Rewrite Rules, Rewrite Rules -@subsection Algebraic Properties of Rewrite Rules - -@noindent -The rewrite mechanism understands the algebraic properties of functions -like @samp{+} and @samp{*}. In particular, pattern matching takes -the associativity and commutativity of the following functions into -account: - -@smallexample -+ - * = != && || and or xor vint vunion vxor gcd lcm max min beta -@end smallexample - -For example, the rewrite rule: - -@example -a x + b x := (a + b) x -@end example - -@noindent -will match formulas of the form, - -@example -a x + b x, x a + x b, a x + x b, x a + b x -@end example - -Rewrites also understand the relationship between the @samp{+} and @samp{-} -operators. The above rewrite rule will also match the formulas, - -@example -a x - b x, x a - x b, a x - x b, x a - b x -@end example - -@noindent -by matching @samp{b} in the pattern to @samp{-b} from the formula. - -Applied to a sum of many terms like @samp{r + a x + s + b x + t}, this -pattern will check all pairs of terms for possible matches. The rewrite -will take whichever suitable pair it discovers first. - -In general, a pattern using an associative operator like @samp{a + b} -will try @var{2 n} different ways to match a sum of @var{n} terms -like @samp{x + y + z - w}. First, @samp{a} is matched against each -of @samp{x}, @samp{y}, @samp{z}, and @samp{-w} in turn, with @samp{b} -being matched to the remainders @samp{y + z - w}, @samp{x + z - w}, etc. -If none of these succeed, then @samp{b} is matched against each of the -four terms with @samp{a} matching the remainder. Half-and-half matches, -like @samp{(x + y) + (z - w)}, are not tried. - -Note that @samp{*} is not commutative when applied to matrices, but -rewrite rules pretend that it is. If you type @kbd{m v} to enable -Matrix mode (@pxref{Matrix Mode}), rewrite rules will match @samp{*} -literally, ignoring its usual commutativity property. (In the -current implementation, the associativity also vanishes---it is as -if the pattern had been enclosed in a @code{plain} marker; see below.) -If you are applying rewrites to formulas with matrices, it's best to -enable Matrix mode first to prevent algebraically incorrect rewrites -from occurring. - -The pattern @samp{-x} will actually match any expression. For example, -the rule - -@example -f(-x) := -f(x) -@end example - -@noindent -will rewrite @samp{f(a)} to @samp{-f(-a)}. To avoid this, either use -a @code{plain} marker as described below, or add a @samp{negative(x)} -condition. The @code{negative} function is true if its argument -``looks'' negative, for example, because it is a negative number or -because it is a formula like @samp{-x}. The new rule using this -condition is: - -@example -f(x) := -f(-x) :: negative(x) @r{or, equivalently,} -f(-x) := -f(x) :: negative(-x) -@end example - -In the same way, the pattern @samp{x - y} will match the sum @samp{a + b} -by matching @samp{y} to @samp{-b}. - -The pattern @samp{a b} will also match the formula @samp{x/y} if -@samp{y} is a number. Thus the rule @samp{a x + @w{b x} := (a+b) x} -will also convert @samp{a x + x / 2} to @samp{(a + 0.5) x} (or -@samp{(a + 1:2) x}, depending on the current fraction mode). - -Calc will @emph{not} take other liberties with @samp{*}, @samp{/}, and -@samp{^}. For example, the pattern @samp{f(a b)} will not match -@samp{f(x^2)}, and @samp{f(a + b)} will not match @samp{f(2 x)}, even -though conceivably these patterns could match with @samp{a = b = x}. -Nor will @samp{f(a b)} match @samp{f(x / y)} if @samp{y} is not a -constant, even though it could be considered to match with @samp{a = x} -and @samp{b = 1/y}. The reasons are partly for efficiency, and partly -because while few mathematical operations are substantively different -for addition and subtraction, often it is preferable to treat the cases -of multiplication, division, and integer powers separately. - -Even more subtle is the rule set - -@example -[ f(a) + f(b) := f(a + b), -f(a) := f(-a) ] -@end example - -@noindent -attempting to match @samp{f(x) - f(y)}. You might think that Calc -will view this subtraction as @samp{f(x) + (-f(y))} and then apply -the above two rules in turn, but actually this will not work because -Calc only does this when considering rules for @samp{+} (like the -first rule in this set). So it will see first that @samp{f(x) + (-f(y))} -does not match @samp{f(a) + f(b)} for any assignments of the -meta-variables, and then it will see that @samp{f(x) - f(y)} does -not match @samp{-f(a)} for any assignment of @samp{a}. Because Calc -tries only one rule at a time, it will not be able to rewrite -@samp{f(x) - f(y)} with this rule set. An explicit @samp{f(a) - f(b)} -rule will have to be added. - -Another thing patterns will @emph{not} do is break up complex numbers. -The pattern @samp{myconj(a + @w{b i)} := a - b i} will work for formulas -involving the special constant @samp{i} (such as @samp{3 - 4 i}), but -it will not match actual complex numbers like @samp{(3, -4)}. A version -of the above rule for complex numbers would be - -@example -myconj(a) := re(a) - im(a) (0,1) :: im(a) != 0 -@end example - -@noindent -(Because the @code{re} and @code{im} functions understand the properties -of the special constant @samp{i}, this rule will also work for -@samp{3 - 4 i}. In fact, this particular rule would probably be better -without the @samp{im(a) != 0} condition, since if @samp{im(a) = 0} the -righthand side of the rule will still give the correct answer for the -conjugate of a real number.) - -It is also possible to specify optional arguments in patterns. The rule - -@example -opt(a) x + opt(b) (x^opt(c) + opt(d)) := f(a, b, c, d) -@end example - -@noindent -will match the formula - -@example -5 (x^2 - 4) + 3 x -@end example - -@noindent -in a fairly straightforward manner, but it will also match reduced -formulas like - -@example -x + x^2, 2(x + 1) - x, x + x -@end example - -@noindent -producing, respectively, - -@example -f(1, 1, 2, 0), f(-1, 2, 1, 1), f(1, 1, 1, 0) -@end example - -(The latter two formulas can be entered only if default simplifications -have been turned off with @kbd{m O}.) - -The default value for a term of a sum is zero. The default value -for a part of a product, for a power, or for the denominator of a -quotient, is one. Also, @samp{-x} matches the pattern @samp{opt(a) b} -with @samp{a = -1}. - -In particular, the distributive-law rule can be refined to - -@example -opt(a) x + opt(b) x := (a + b) x -@end example - -@noindent -so that it will convert, e.g., @samp{a x - x}, to @samp{(a - 1) x}. - -The pattern @samp{opt(a) + opt(b) x} matches almost any formulas which -are linear in @samp{x}. You can also use the @code{lin} and @code{islin} -functions with rewrite conditions to test for this; @pxref{Logical -Operations}. These functions are not as convenient to use in rewrite -rules, but they recognize more kinds of formulas as linear: -@samp{x/z} is considered linear with @expr{b = 1/z} by @code{lin}, -but it will not match the above pattern because that pattern calls -for a multiplication, not a division. - -As another example, the obvious rule to replace @samp{sin(x)^2 + cos(x)^2} -by 1, - -@example -sin(x)^2 + cos(x)^2 := 1 -@end example - -@noindent -misses many cases because the sine and cosine may both be multiplied by -an equal factor. Here's a more successful rule: - -@example -opt(a) sin(x)^2 + opt(a) cos(x)^2 := a -@end example - -Note that this rule will @emph{not} match @samp{sin(x)^2 + 6 cos(x)^2} -because one @expr{a} would have ``matched'' 1 while the other matched 6. - -Calc automatically converts a rule like - -@example -f(x-1, x) := g(x) -@end example - -@noindent -into the form - -@example -f(temp, x) := g(x) :: temp = x-1 -@end example - -@noindent -(where @code{temp} stands for a new, invented meta-variable that -doesn't actually have a name). This modified rule will successfully -match @samp{f(6, 7)}, binding @samp{temp} and @samp{x} to 6 and 7, -respectively, then verifying that they differ by one even though -@samp{6} does not superficially look like @samp{x-1}. - -However, Calc does not solve equations to interpret a rule. The -following rule, - -@example -f(x-1, x+1) := g(x) -@end example - -@noindent -will not work. That is, it will match @samp{f(a - 1 + b, a + 1 + b)} -but not @samp{f(6, 8)}. Calc always interprets at least one occurrence -of a variable by literal matching. If the variable appears ``isolated'' -then Calc is smart enough to use it for literal matching. But in this -last example, Calc is forced to rewrite the rule to @samp{f(x-1, temp) -:= g(x) :: temp = x+1} where the @samp{x-1} term must correspond to an -actual ``something-minus-one'' in the target formula. - -A successful way to write this would be @samp{f(x, x+2) := g(x+1)}. -You could make this resemble the original form more closely by using -@code{let} notation, which is described in the next section: - -@example -f(xm1, x+1) := g(x) :: let(x := xm1+1) -@end example - -Calc does this rewriting or ``conditionalizing'' for any sub-pattern -which involves only the functions in the following list, operating -only on constants and meta-variables which have already been matched -elsewhere in the pattern. When matching a function call, Calc is -careful to match arguments which are plain variables before arguments -which are calls to any of the functions below, so that a pattern like -@samp{f(x-1, x)} can be conditionalized even though the isolated -@samp{x} comes after the @samp{x-1}. - -@smallexample -+ - * / \ % ^ abs sign round rounde roundu trunc floor ceil -max min re im conj arg -@end smallexample - -You can suppress all of the special treatments described in this -section by surrounding a function call with a @code{plain} marker. -This marker causes the function call which is its argument to be -matched literally, without regard to commutativity, associativity, -negation, or conditionalization. When you use @code{plain}, the -``deep structure'' of the formula being matched can show through. -For example, - -@example -plain(a - a b) := f(a, b) -@end example - -@noindent -will match only literal subtractions. However, the @code{plain} -marker does not affect its arguments' arguments. In this case, -commutativity and associativity is still considered while matching -the @w{@samp{a b}} sub-pattern, so the whole pattern will match -@samp{x - y x} as well as @samp{x - x y}. We could go still -further and use - -@example -plain(a - plain(a b)) := f(a, b) -@end example - -@noindent -which would do a completely strict match for the pattern. - -By contrast, the @code{quote} marker means that not only the -function name but also the arguments must be literally the same. -The above pattern will match @samp{x - x y} but - -@example -quote(a - a b) := f(a, b) -@end example - -@noindent -will match only the single formula @samp{a - a b}. Also, - -@example -quote(a - quote(a b)) := f(a, b) -@end example - -@noindent -will match only @samp{a - quote(a b)}---probably not the desired -effect! - -A certain amount of algebra is also done when substituting the -meta-variables on the righthand side of a rule. For example, -in the rule - -@example -a + f(b) := f(a + b) -@end example - -@noindent -matching @samp{f(x) - y} would produce @samp{f((-y) + x)} if -taken literally, but the rewrite mechanism will simplify the -righthand side to @samp{f(x - y)} automatically. (Of course, -the default simplifications would do this anyway, so this -special simplification is only noticeable if you have turned the -default simplifications off.) This rewriting is done only when -a meta-variable expands to a ``negative-looking'' expression. -If this simplification is not desirable, you can use a @code{plain} -marker on the righthand side: - -@example -a + f(b) := f(plain(a + b)) -@end example - -@noindent -In this example, we are still allowing the pattern-matcher to -use all the algebra it can muster, but the righthand side will -always simplify to a literal addition like @samp{f((-y) + x)}. - -@node Other Features of Rewrite Rules, Composing Patterns in Rewrite Rules, Algebraic Properties of Rewrite Rules, Rewrite Rules -@subsection Other Features of Rewrite Rules - -@noindent -Certain ``function names'' serve as markers in rewrite rules. -Here is a complete list of these markers. First are listed the -markers that work inside a pattern; then come the markers that -work in the righthand side of a rule. - -@ignore -@starindex -@end ignore -@tindex import -One kind of marker, @samp{import(x)}, takes the place of a whole -rule. Here @expr{x} is the name of a variable containing another -rule set; those rules are ``spliced into'' the rule set that -imports them. For example, if @samp{[f(a+b) := f(a) + f(b), -f(a b) := a f(b) :: real(a)]} is stored in variable @samp{linearF}, -then the rule set @samp{[f(0) := 0, import(linearF)]} will apply -all three rules. It is possible to modify the imported rules -slightly: @samp{import(x, v1, x1, v2, x2, @dots{})} imports -the rule set @expr{x} with all occurrences of -@texline @math{v_1}, -@infoline @expr{v1}, -as either a variable name or a function name, replaced with -@texline @math{x_1} -@infoline @expr{x1} -and so on. (If -@texline @math{v_1} -@infoline @expr{v1} -is used as a function name, then -@texline @math{x_1} -@infoline @expr{x1} -must be either a function name itself or a @w{@samp{< >}} nameless -function; @pxref{Specifying Operators}.) For example, @samp{[g(0) := 0, -import(linearF, f, g)]} applies the linearity rules to the function -@samp{g} instead of @samp{f}. Imports can be nested, but the -import-with-renaming feature may fail to rename sub-imports properly. - -The special functions allowed in patterns are: - -@table @samp -@item quote(x) -@ignore -@starindex -@end ignore -@tindex quote -This pattern matches exactly @expr{x}; variable names in @expr{x} are -not interpreted as meta-variables. The only flexibility is that -numbers are compared for numeric equality, so that the pattern -@samp{f(quote(12))} will match both @samp{f(12)} and @samp{f(12.0)}. -(Numbers are always treated this way by the rewrite mechanism: -The rule @samp{f(x,x) := g(x)} will match @samp{f(12, 12.0)}. -The rewrite may produce either @samp{g(12)} or @samp{g(12.0)} -as a result in this case.) - -@item plain(x) -@ignore -@starindex -@end ignore -@tindex plain -Here @expr{x} must be a function call @samp{f(x1,x2,@dots{})}. This -pattern matches a call to function @expr{f} with the specified -argument patterns. No special knowledge of the properties of the -function @expr{f} is used in this case; @samp{+} is not commutative or -associative. Unlike @code{quote}, the arguments @samp{x1,x2,@dots{}} -are treated as patterns. If you wish them to be treated ``plainly'' -as well, you must enclose them with more @code{plain} markers: -@samp{plain(plain(@w{-a}) + plain(b c))}. - -@item opt(x,def) -@ignore -@starindex -@end ignore -@tindex opt -Here @expr{x} must be a variable name. This must appear as an -argument to a function or an element of a vector; it specifies that -the argument or element is optional. -As an argument to @samp{+}, @samp{-}, @samp{*}, @samp{&&}, or @samp{||}, -or as the second argument to @samp{/} or @samp{^}, the value @var{def} -may be omitted. The pattern @samp{x + opt(y)} matches a sum by -binding one summand to @expr{x} and the other to @expr{y}, and it -matches anything else by binding the whole expression to @expr{x} and -zero to @expr{y}. The other operators above work similarly. - -For general miscellaneous functions, the default value @code{def} -must be specified. Optional arguments are dropped starting with -the rightmost one during matching. For example, the pattern -@samp{f(opt(a,0), b, opt(c,b))} will match @samp{f(b)}, @samp{f(a,b)}, -or @samp{f(a,b,c)}. Default values of zero and @expr{b} are -supplied in this example for the omitted arguments. Note that -the literal variable @expr{b} will be the default in the latter -case, @emph{not} the value that matched the meta-variable @expr{b}. -In other words, the default @var{def} is effectively quoted. - -@item condition(x,c) -@ignore -@starindex -@end ignore -@tindex condition -@tindex :: -This matches the pattern @expr{x}, with the attached condition -@expr{c}. It is the same as @samp{x :: c}. - -@item pand(x,y) -@ignore -@starindex -@end ignore -@tindex pand -@tindex &&& -This matches anything that matches both pattern @expr{x} and -pattern @expr{y}. It is the same as @samp{x &&& y}. -@pxref{Composing Patterns in Rewrite Rules}. - -@item por(x,y) -@ignore -@starindex -@end ignore -@tindex por -@tindex ||| -This matches anything that matches either pattern @expr{x} or -pattern @expr{y}. It is the same as @w{@samp{x ||| y}}. - -@item pnot(x) -@ignore -@starindex -@end ignore -@tindex pnot -@tindex !!! -This matches anything that does not match pattern @expr{x}. -It is the same as @samp{!!! x}. - -@item cons(h,t) -@ignore -@mindex cons -@end ignore -@tindex cons (rewrites) -This matches any vector of one or more elements. The first -element is matched to @expr{h}; a vector of the remaining -elements is matched to @expr{t}. Note that vectors of fixed -length can also be matched as actual vectors: The rule -@samp{cons(a,cons(b,[])) := cons(a+b,[])} is equivalent -to the rule @samp{[a,b] := [a+b]}. - -@item rcons(t,h) -@ignore -@mindex rcons -@end ignore -@tindex rcons (rewrites) -This is like @code{cons}, except that the @emph{last} element -is matched to @expr{h}, with the remaining elements matched -to @expr{t}. - -@item apply(f,args) -@ignore -@mindex apply -@end ignore -@tindex apply (rewrites) -This matches any function call. The name of the function, in -the form of a variable, is matched to @expr{f}. The arguments -of the function, as a vector of zero or more objects, are -matched to @samp{args}. Constants, variables, and vectors -do @emph{not} match an @code{apply} pattern. For example, -@samp{apply(f,x)} matches any function call, @samp{apply(quote(f),x)} -matches any call to the function @samp{f}, @samp{apply(f,[a,b])} -matches any function call with exactly two arguments, and -@samp{apply(quote(f), cons(a,cons(b,x)))} matches any call -to the function @samp{f} with two or more arguments. Another -way to implement the latter, if the rest of the rule does not -need to refer to the first two arguments of @samp{f} by name, -would be @samp{apply(quote(f), x :: vlen(x) >= 2)}. -Here's a more interesting sample use of @code{apply}: - -@example -apply(f,[x+n]) := n + apply(f,[x]) - :: in(f, [floor,ceil,round,trunc]) :: integer(n) -@end example - -Note, however, that this will be slower to match than a rule -set with four separate rules. The reason is that Calc sorts -the rules of a rule set according to top-level function name; -if the top-level function is @code{apply}, Calc must try the -rule for every single formula and sub-formula. If the top-level -function in the pattern is, say, @code{floor}, then Calc invokes -the rule only for sub-formulas which are calls to @code{floor}. - -Formulas normally written with operators like @code{+} are still -considered function calls: @code{apply(f,x)} matches @samp{a+b} -with @samp{f = add}, @samp{x = [a,b]}. - -You must use @code{apply} for meta-variables with function names -on both sides of a rewrite rule: @samp{apply(f, [x]) := f(x+1)} -is @emph{not} correct, because it rewrites @samp{spam(6)} into -@samp{f(7)}. The righthand side should be @samp{apply(f, [x+1])}. -Also note that you will have to use No-Simplify mode (@kbd{m O}) -when entering this rule so that the @code{apply} isn't -evaluated immediately to get the new rule @samp{f(x) := f(x+1)}. -Or, use @kbd{s e} to enter the rule without going through the stack, -or enter the rule as @samp{apply(f, [x]) := apply(f, [x+1]) @w{:: 1}}. -@xref{Conditional Rewrite Rules}. - -@item select(x) -@ignore -@starindex -@end ignore -@tindex select -This is used for applying rules to formulas with selections; -@pxref{Selections with Rewrite Rules}. -@end table - -Special functions for the righthand sides of rules are: - -@table @samp -@item quote(x) -The notation @samp{quote(x)} is changed to @samp{x} when the -righthand side is used. As far as the rewrite rule is concerned, -@code{quote} is invisible. However, @code{quote} has the special -property in Calc that its argument is not evaluated. Thus, -while it will not work to put the rule @samp{t(a) := typeof(a)} -on the stack because @samp{typeof(a)} is evaluated immediately -to produce @samp{t(a) := 100}, you can use @code{quote} to -protect the righthand side: @samp{t(a) := quote(typeof(a))}. -(@xref{Conditional Rewrite Rules}, for another trick for -protecting rules from evaluation.) - -@item plain(x) -Special properties of and simplifications for the function call -@expr{x} are not used. One interesting case where @code{plain} -is useful is the rule, @samp{q(x) := quote(x)}, trying to expand a -shorthand notation for the @code{quote} function. This rule will -not work as shown; instead of replacing @samp{q(foo)} with -@samp{quote(foo)}, it will replace it with @samp{foo}! The correct -rule would be @samp{q(x) := plain(quote(x))}. - -@item cons(h,t) -Where @expr{t} is a vector, this is converted into an expanded -vector during rewrite processing. Note that @code{cons} is a regular -Calc function which normally does this anyway; the only way @code{cons} -is treated specially by rewrites is that @code{cons} on the righthand -side of a rule will be evaluated even if default simplifications -have been turned off. - -@item rcons(t,h) -Analogous to @code{cons} except putting @expr{h} at the @emph{end} of -the vector @expr{t}. - -@item apply(f,args) -Where @expr{f} is a variable and @var{args} is a vector, this -is converted to a function call. Once again, note that @code{apply} -is also a regular Calc function. - -@item eval(x) -@ignore -@starindex -@end ignore -@tindex eval -The formula @expr{x} is handled in the usual way, then the -default simplifications are applied to it even if they have -been turned off normally. This allows you to treat any function -similarly to the way @code{cons} and @code{apply} are always -treated. However, there is a slight difference: @samp{cons(2+3, [])} -with default simplifications off will be converted to @samp{[2+3]}, -whereas @samp{eval(cons(2+3, []))} will be converted to @samp{[5]}. - -@item evalsimp(x) -@ignore -@starindex -@end ignore -@tindex evalsimp -The formula @expr{x} has meta-variables substituted in the usual -way, then algebraically simplified as if by the @kbd{a s} command. - -@item evalextsimp(x) -@ignore -@starindex -@end ignore -@tindex evalextsimp -The formula @expr{x} has meta-variables substituted in the normal -way, then ``extendedly'' simplified as if by the @kbd{a e} command. - -@item select(x) -@xref{Selections with Rewrite Rules}. -@end table - -There are also some special functions you can use in conditions. - -@table @samp -@item let(v := x) -@ignore -@starindex -@end ignore -@tindex let -The expression @expr{x} is evaluated with meta-variables substituted. -The @kbd{a s} command's simplifications are @emph{not} applied by -default, but @expr{x} can include calls to @code{evalsimp} or -@code{evalextsimp} as described above to invoke higher levels -of simplification. The -result of @expr{x} is then bound to the meta-variable @expr{v}. As -usual, if this meta-variable has already been matched to something -else the two values must be equal; if the meta-variable is new then -it is bound to the result of the expression. This variable can then -appear in later conditions, and on the righthand side of the rule. -In fact, @expr{v} may be any pattern in which case the result of -evaluating @expr{x} is matched to that pattern, binding any -meta-variables that appear in that pattern. Note that @code{let} -can only appear by itself as a condition, or as one term of an -@samp{&&} which is a whole condition: It cannot be inside -an @samp{||} term or otherwise buried. - -The alternate, equivalent form @samp{let(v, x)} is also recognized. -Note that the use of @samp{:=} by @code{let}, while still being -assignment-like in character, is unrelated to the use of @samp{:=} -in the main part of a rewrite rule. - -As an example, @samp{f(a) := g(ia) :: let(ia := 1/a) :: constant(ia)} -replaces @samp{f(a)} with @samp{g} of the inverse of @samp{a}, if -that inverse exists and is constant. For example, if @samp{a} is a -singular matrix the operation @samp{1/a} is left unsimplified and -@samp{constant(ia)} fails, but if @samp{a} is an invertible matrix -then the rule succeeds. Without @code{let} there would be no way -to express this rule that didn't have to invert the matrix twice. -Note that, because the meta-variable @samp{ia} is otherwise unbound -in this rule, the @code{let} condition itself always ``succeeds'' -because no matter what @samp{1/a} evaluates to, it can successfully -be bound to @code{ia}. - -Here's another example, for integrating cosines of linear -terms: @samp{myint(cos(y),x) := sin(y)/b :: let([a,b,x] := lin(y,x))}. -The @code{lin} function returns a 3-vector if its argument is linear, -or leaves itself unevaluated if not. But an unevaluated @code{lin} -call will not match the 3-vector on the lefthand side of the @code{let}, -so this @code{let} both verifies that @code{y} is linear, and binds -the coefficients @code{a} and @code{b} for use elsewhere in the rule. -(It would have been possible to use @samp{sin(a x + b)/b} for the -righthand side instead, but using @samp{sin(y)/b} avoids gratuitous -rearrangement of the argument of the sine.) - -@ignore -@starindex -@end ignore -@tindex ierf -Similarly, here is a rule that implements an inverse-@code{erf} -function. It uses @code{root} to search for a solution. If -@code{root} succeeds, it will return a vector of two numbers -where the first number is the desired solution. If no solution -is found, @code{root} remains in symbolic form. So we use -@code{let} to check that the result was indeed a vector. - -@example -ierf(x) := y :: let([y,z] := root(erf(a) = x, a, .5)) -@end example - -@item matches(v,p) -The meta-variable @var{v}, which must already have been matched -to something elsewhere in the rule, is compared against pattern -@var{p}. Since @code{matches} is a standard Calc function, it -can appear anywhere in a condition. But if it appears alone or -as a term of a top-level @samp{&&}, then you get the special -extra feature that meta-variables which are bound to things -inside @var{p} can be used elsewhere in the surrounding rewrite -rule. - -The only real difference between @samp{let(p := v)} and -@samp{matches(v, p)} is that the former evaluates @samp{v} using -the default simplifications, while the latter does not. - -@item remember -@vindex remember -This is actually a variable, not a function. If @code{remember} -appears as a condition in a rule, then when that rule succeeds -the original expression and rewritten expression are added to the -front of the rule set that contained the rule. If the rule set -was not stored in a variable, @code{remember} is ignored. The -lefthand side is enclosed in @code{quote} in the added rule if it -contains any variables. - -For example, the rule @samp{f(n) := n f(n-1) :: remember} applied -to @samp{f(7)} will add the rule @samp{f(7) := 7 f(6)} to the front -of the rule set. The rule set @code{EvalRules} works slightly -differently: There, the evaluation of @samp{f(6)} will complete before -the result is added to the rule set, in this case as @samp{f(7) := 5040}. -Thus @code{remember} is most useful inside @code{EvalRules}. - -It is up to you to ensure that the optimization performed by -@code{remember} is safe. For example, the rule @samp{foo(n) := n -:: evalv(eatfoo) > 0 :: remember} is a bad idea (@code{evalv} is -the function equivalent of the @kbd{=} command); if the variable -@code{eatfoo} ever contains 1, rules like @samp{foo(7) := 7} will -be added to the rule set and will continue to operate even if -@code{eatfoo} is later changed to 0. - -@item remember(c) -@ignore -@starindex -@end ignore -@tindex remember -Remember the match as described above, but only if condition @expr{c} -is true. For example, @samp{remember(n % 4 = 0)} in the above factorial -rule remembers only every fourth result. Note that @samp{remember(1)} -is equivalent to @samp{remember}, and @samp{remember(0)} has no effect. -@end table - -@node Composing Patterns in Rewrite Rules, Nested Formulas with Rewrite Rules, Other Features of Rewrite Rules, Rewrite Rules -@subsection Composing Patterns in Rewrite Rules - -@noindent -There are three operators, @samp{&&&}, @samp{|||}, and @samp{!!!}, -that combine rewrite patterns to make larger patterns. The -combinations are ``and,'' ``or,'' and ``not,'' respectively, and -these operators are the pattern equivalents of @samp{&&}, @samp{||} -and @samp{!} (which operate on zero-or-nonzero logical values). - -Note that @samp{&&&}, @samp{|||}, and @samp{!!!} are left in symbolic -form by all regular Calc features; they have special meaning only in -the context of rewrite rule patterns. - -The pattern @samp{@var{p1} &&& @var{p2}} matches anything that -matches both @var{p1} and @var{p2}. One especially useful case is -when one of @var{p1} or @var{p2} is a meta-variable. For example, -here is a rule that operates on error forms: - -@example -f(x &&& a +/- b, x) := g(x) -@end example - -This does the same thing, but is arguably simpler than, the rule - -@example -f(a +/- b, a +/- b) := g(a +/- b) -@end example - -@ignore -@starindex -@end ignore -@tindex ends -Here's another interesting example: - -@example -ends(cons(a, x) &&& rcons(y, b)) := [a, b] -@end example - -@noindent -which effectively clips out the middle of a vector leaving just -the first and last elements. This rule will change a one-element -vector @samp{[a]} to @samp{[a, a]}. The similar rule - -@example -ends(cons(a, rcons(y, b))) := [a, b] -@end example - -@noindent -would do the same thing except that it would fail to match a -one-element vector. - -@tex -\bigskip -@end tex - -The pattern @samp{@var{p1} ||| @var{p2}} matches anything that -matches either @var{p1} or @var{p2}. Calc first tries matching -against @var{p1}; if that fails, it goes on to try @var{p2}. - -@ignore -@starindex -@end ignore -@tindex curve -A simple example of @samp{|||} is - -@example -curve(inf ||| -inf) := 0 -@end example - -@noindent -which converts both @samp{curve(inf)} and @samp{curve(-inf)} to zero. - -Here is a larger example: - -@example -log(a, b) ||| (ln(a) :: let(b := e)) := mylog(a, b) -@end example - -This matches both generalized and natural logarithms in a single rule. -Note that the @samp{::} term must be enclosed in parentheses because -that operator has lower precedence than @samp{|||} or @samp{:=}. - -(In practice this rule would probably include a third alternative, -omitted here for brevity, to take care of @code{log10}.) - -While Calc generally treats interior conditions exactly the same as -conditions on the outside of a rule, it does guarantee that if all the -variables in the condition are special names like @code{e}, or already -bound in the pattern to which the condition is attached (say, if -@samp{a} had appeared in this condition), then Calc will process this -condition right after matching the pattern to the left of the @samp{::}. -Thus, we know that @samp{b} will be bound to @samp{e} only if the -@code{ln} branch of the @samp{|||} was taken. - -Note that this rule was careful to bind the same set of meta-variables -on both sides of the @samp{|||}. Calc does not check this, but if -you bind a certain meta-variable only in one branch and then use that -meta-variable elsewhere in the rule, results are unpredictable: - -@example -f(a,b) ||| g(b) := h(a,b) -@end example - -Here if the pattern matches @samp{g(17)}, Calc makes no promises about -the value that will be substituted for @samp{a} on the righthand side. - -@tex -\bigskip -@end tex - -The pattern @samp{!!! @var{pat}} matches anything that does not -match @var{pat}. Any meta-variables that are bound while matching -@var{pat} remain unbound outside of @var{pat}. - -For example, - -@example -f(x &&& !!! a +/- b, !!![]) := g(x) -@end example - -@noindent -converts @code{f} whose first argument is anything @emph{except} an -error form, and whose second argument is not the empty vector, into -a similar call to @code{g} (but without the second argument). - -If we know that the second argument will be a vector (empty or not), -then an equivalent rule would be: - -@example -f(x, y) := g(x) :: typeof(x) != 7 :: vlen(y) > 0 -@end example - -@noindent -where of course 7 is the @code{typeof} code for error forms. -Another final condition, that works for any kind of @samp{y}, -would be @samp{!istrue(y == [])}. (The @code{istrue} function -returns an explicit 0 if its argument was left in symbolic form; -plain @samp{!(y == [])} or @samp{y != []} would not work to replace -@samp{!!![]} since these would be left unsimplified, and thus cause -the rule to fail, if @samp{y} was something like a variable name.) - -It is possible for a @samp{!!!} to refer to meta-variables bound -elsewhere in the pattern. For example, - -@example -f(a, !!!a) := g(a) -@end example - -@noindent -matches any call to @code{f} with different arguments, changing -this to @code{g} with only the first argument. - -If a function call is to be matched and one of the argument patterns -contains a @samp{!!!} somewhere inside it, that argument will be -matched last. Thus - -@example -f(!!!a, a) := g(a) -@end example - -@noindent -will be careful to bind @samp{a} to the second argument of @code{f} -before testing the first argument. If Calc had tried to match the -first argument of @code{f} first, the results would have been -disastrous: since @code{a} was unbound so far, the pattern @samp{a} -would have matched anything at all, and the pattern @samp{!!!a} -therefore would @emph{not} have matched anything at all! - -@node Nested Formulas with Rewrite Rules, Multi-Phase Rewrite Rules, Composing Patterns in Rewrite Rules, Rewrite Rules -@subsection Nested Formulas with Rewrite Rules - -@noindent -When @kbd{a r} (@code{calc-rewrite}) is used, it takes an expression from -the top of the stack and attempts to match any of the specified rules -to any part of the expression, starting with the whole expression -and then, if that fails, trying deeper and deeper sub-expressions. -For each part of the expression, the rules are tried in the order -they appear in the rules vector. The first rule to match the first -sub-expression wins; it replaces the matched sub-expression according -to the @var{new} part of the rule. - -Often, the rule set will match and change the formula several times. -The top-level formula is first matched and substituted repeatedly until -it no longer matches the pattern; then, sub-formulas are tried, and -so on. Once every part of the formula has gotten its chance, the -rewrite mechanism starts over again with the top-level formula -(in case a substitution of one of its arguments has caused it again -to match). This continues until no further matches can be made -anywhere in the formula. - -It is possible for a rule set to get into an infinite loop. The -most obvious case, replacing a formula with itself, is not a problem -because a rule is not considered to ``succeed'' unless the righthand -side actually comes out to something different than the original -formula or sub-formula that was matched. But if you accidentally -had both @samp{ln(a b) := ln(a) + ln(b)} and the reverse -@samp{ln(a) + ln(b) := ln(a b)} in your rule set, Calc would -run forever switching a formula back and forth between the two -forms. - -To avoid disaster, Calc normally stops after 100 changes have been -made to the formula. This will be enough for most multiple rewrites, -but it will keep an endless loop of rewrites from locking up the -computer forever. (On most systems, you can also type @kbd{C-g} to -halt any Emacs command prematurely.) - -To change this limit, give a positive numeric prefix argument. -In particular, @kbd{M-1 a r} applies only one rewrite at a time, -useful when you are first testing your rule (or just if repeated -rewriting is not what is called for by your application). - -@ignore -@starindex -@end ignore -@ignore -@mindex iter@idots -@end ignore -@tindex iterations -You can also put a ``function call'' @samp{iterations(@var{n})} -in place of a rule anywhere in your rules vector (but usually at -the top). Then, @var{n} will be used instead of 100 as the default -number of iterations for this rule set. You can use -@samp{iterations(inf)} if you want no iteration limit by default. -A prefix argument will override the @code{iterations} limit in the -rule set. - -@example -[ iterations(1), - f(x) := f(x+1) ] -@end example - -More precisely, the limit controls the number of ``iterations,'' -where each iteration is a successful matching of a rule pattern whose -righthand side, after substituting meta-variables and applying the -default simplifications, is different from the original sub-formula -that was matched. - -A prefix argument of zero sets the limit to infinity. Use with caution! - -Given a negative numeric prefix argument, @kbd{a r} will match and -substitute the top-level expression up to that many times, but -will not attempt to match the rules to any sub-expressions. - -In a formula, @code{rewrite(@var{expr}, @var{rules}, @var{n})} -does a rewriting operation. Here @var{expr} is the expression -being rewritten, @var{rules} is the rule, vector of rules, or -variable containing the rules, and @var{n} is the optional -iteration limit, which may be a positive integer, a negative -integer, or @samp{inf} or @samp{-inf}. If @var{n} is omitted -the @code{iterations} value from the rule set is used; if both -are omitted, 100 is used. - -@node Multi-Phase Rewrite Rules, Selections with Rewrite Rules, Nested Formulas with Rewrite Rules, Rewrite Rules -@subsection Multi-Phase Rewrite Rules - -@noindent -It is possible to separate a rewrite rule set into several @dfn{phases}. -During each phase, certain rules will be enabled while certain others -will be disabled. A @dfn{phase schedule} controls the order in which -phases occur during the rewriting process. - -@ignore -@starindex -@end ignore -@tindex phase -@vindex all -If a call to the marker function @code{phase} appears in the rules -vector in place of a rule, all rules following that point will be -members of the phase(s) identified in the arguments to @code{phase}. -Phases are given integer numbers. The markers @samp{phase()} and -@samp{phase(all)} both mean the following rules belong to all phases; -this is the default at the start of the rule set. - -If you do not explicitly schedule the phases, Calc sorts all phase -numbers that appear in the rule set and executes the phases in -ascending order. For example, the rule set - -@example -@group -[ f0(x) := g0(x), - phase(1), - f1(x) := g1(x), - phase(2), - f2(x) := g2(x), - phase(3), - f3(x) := g3(x), - phase(1,2), - f4(x) := g4(x) ] -@end group -@end example - -@noindent -has three phases, 1 through 3. Phase 1 consists of the @code{f0}, -@code{f1}, and @code{f4} rules (in that order). Phase 2 consists of -@code{f0}, @code{f2}, and @code{f4}. Phase 3 consists of @code{f0} -and @code{f3}. - -When Calc rewrites a formula using this rule set, it first rewrites -the formula using only the phase 1 rules until no further changes are -possible. Then it switches to the phase 2 rule set and continues -until no further changes occur, then finally rewrites with phase 3. -When no more phase 3 rules apply, rewriting finishes. (This is -assuming @kbd{a r} with a large enough prefix argument to allow the -rewriting to run to completion; the sequence just described stops -early if the number of iterations specified in the prefix argument, -100 by default, is reached.) - -During each phase, Calc descends through the nested levels of the -formula as described previously. (@xref{Nested Formulas with Rewrite -Rules}.) Rewriting starts at the top of the formula, then works its -way down to the parts, then goes back to the top and works down again. -The phase 2 rules do not begin until no phase 1 rules apply anywhere -in the formula. - -@ignore -@starindex -@end ignore -@tindex schedule -A @code{schedule} marker appearing in the rule set (anywhere, but -conventionally at the top) changes the default schedule of phases. -In the simplest case, @code{schedule} has a sequence of phase numbers -for arguments; each phase number is invoked in turn until the -arguments to @code{schedule} are exhausted. Thus adding -@samp{schedule(3,2,1)} at the top of the above rule set would -reverse the order of the phases; @samp{schedule(1,2,3)} would have -no effect since this is the default schedule; and @samp{schedule(1,2,1,3)} -would give phase 1 a second chance after phase 2 has completed, before -moving on to phase 3. - -Any argument to @code{schedule} can instead be a vector of phase -numbers (or even of sub-vectors). Then the sub-sequence of phases -described by the vector are tried repeatedly until no change occurs -in any phase in the sequence. For example, @samp{schedule([1, 2], 3)} -tries phase 1, then phase 2, then, if either phase made any changes -to the formula, repeats these two phases until they can make no -further progress. Finally, it goes on to phase 3 for finishing -touches. - -Also, items in @code{schedule} can be variable names as well as -numbers. A variable name is interpreted as the name of a function -to call on the whole formula. For example, @samp{schedule(1, simplify)} -says to apply the phase-1 rules (presumably, all of them), then to -call @code{simplify} which is the function name equivalent of @kbd{a s}. -Likewise, @samp{schedule([1, simplify])} says to alternate between -phase 1 and @kbd{a s} until no further changes occur. - -Phases can be used purely to improve efficiency; if it is known that -a certain group of rules will apply only at the beginning of rewriting, -and a certain other group will apply only at the end, then rewriting -will be faster if these groups are identified as separate phases. -Once the phase 1 rules are done, Calc can put them aside and no longer -spend any time on them while it works on phase 2. - -There are also some problems that can only be solved with several -rewrite phases. For a real-world example of a multi-phase rule set, -examine the set @code{FitRules}, which is used by the curve-fitting -command to convert a model expression to linear form. -@xref{Curve Fitting Details}. This set is divided into four phases. -The first phase rewrites certain kinds of expressions to be more -easily linearizable, but less computationally efficient. After the -linear components have been picked out, the final phase includes the -opposite rewrites to put each component back into an efficient form. -If both sets of rules were included in one big phase, Calc could get -into an infinite loop going back and forth between the two forms. - -Elsewhere in @code{FitRules}, the components are first isolated, -then recombined where possible to reduce the complexity of the linear -fit, then finally packaged one component at a time into vectors. -If the packaging rules were allowed to begin before the recombining -rules were finished, some components might be put away into vectors -before they had a chance to recombine. By putting these rules in -two separate phases, this problem is neatly avoided. - -@node Selections with Rewrite Rules, Matching Commands, Multi-Phase Rewrite Rules, Rewrite Rules -@subsection Selections with Rewrite Rules - -@noindent -If a sub-formula of the current formula is selected (as by @kbd{j s}; -@pxref{Selecting Subformulas}), the @kbd{a r} (@code{calc-rewrite}) -command applies only to that sub-formula. Together with a negative -prefix argument, you can use this fact to apply a rewrite to one -specific part of a formula without affecting any other parts. - -@kindex j r -@pindex calc-rewrite-selection -The @kbd{j r} (@code{calc-rewrite-selection}) command allows more -sophisticated operations on selections. This command prompts for -the rules in the same way as @kbd{a r}, but it then applies those -rules to the whole formula in question even though a sub-formula -of it has been selected. However, the selected sub-formula will -first have been surrounded by a @samp{select( )} function call. -(Calc's evaluator does not understand the function name @code{select}; -this is only a tag used by the @kbd{j r} command.) - -For example, suppose the formula on the stack is @samp{2 (a + b)^2} -and the sub-formula @samp{a + b} is selected. This formula will -be rewritten to @samp{2 select(a + b)^2} and then the rewrite -rules will be applied in the usual way. The rewrite rules can -include references to @code{select} to tell where in the pattern -the selected sub-formula should appear. - -If there is still exactly one @samp{select( )} function call in -the formula after rewriting is done, it indicates which part of -the formula should be selected afterwards. Otherwise, the -formula will be unselected. - -You can make @kbd{j r} act much like @kbd{a r} by enclosing both parts -of the rewrite rule with @samp{select()}. However, @kbd{j r} -allows you to use the current selection in more flexible ways. -Suppose you wished to make a rule which removed the exponent from -the selected term; the rule @samp{select(a)^x := select(a)} would -work. In the above example, it would rewrite @samp{2 select(a + b)^2} -to @samp{2 select(a + b)}. This would then be returned to the -stack as @samp{2 (a + b)} with the @samp{a + b} selected. - -The @kbd{j r} command uses one iteration by default, unlike -@kbd{a r} which defaults to 100 iterations. A numeric prefix -argument affects @kbd{j r} in the same way as @kbd{a r}. -@xref{Nested Formulas with Rewrite Rules}. - -As with other selection commands, @kbd{j r} operates on the stack -entry that contains the cursor. (If the cursor is on the top-of-stack -@samp{.} marker, it works as if the cursor were on the formula -at stack level 1.) - -If you don't specify a set of rules, the rules are taken from the -top of the stack, just as with @kbd{a r}. In this case, the -cursor must indicate stack entry 2 or above as the formula to be -rewritten (otherwise the same formula would be used as both the -target and the rewrite rules). - -If the indicated formula has no selection, the cursor position within -the formula temporarily selects a sub-formula for the purposes of this -command. If the cursor is not on any sub-formula (e.g., it is in -the line-number area to the left of the formula), the @samp{select( )} -markers are ignored by the rewrite mechanism and the rules are allowed -to apply anywhere in the formula. - -As a special feature, the normal @kbd{a r} command also ignores -@samp{select( )} calls in rewrite rules. For example, if you used the -above rule @samp{select(a)^x := select(a)} with @kbd{a r}, it would apply -the rule as if it were @samp{a^x := a}. Thus, you can write general -purpose rules with @samp{select( )} hints inside them so that they -will ``do the right thing'' in both @kbd{a r} and @kbd{j r}, -both with and without selections. - -@node Matching Commands, Automatic Rewrites, Selections with Rewrite Rules, Rewrite Rules -@subsection Matching Commands - -@noindent -@kindex a m -@pindex calc-match -@tindex match -The @kbd{a m} (@code{calc-match}) [@code{match}] function takes a -vector of formulas and a rewrite-rule-style pattern, and produces -a vector of all formulas which match the pattern. The command -prompts you to enter the pattern; as for @kbd{a r}, you can enter -a single pattern (i.e., a formula with meta-variables), or a -vector of patterns, or a variable which contains patterns, or -you can give a blank response in which case the patterns are taken -from the top of the stack. The pattern set will be compiled once -and saved if it is stored in a variable. If there are several -patterns in the set, vector elements are kept if they match any -of the patterns. - -For example, @samp{match(a+b, [x, x+y, x-y, 7, x+y+z])} -will return @samp{[x+y, x-y, x+y+z]}. - -The @code{import} mechanism is not available for pattern sets. - -The @kbd{a m} command can also be used to extract all vector elements -which satisfy any condition: The pattern @samp{x :: x>0} will select -all the positive vector elements. - -@kindex I a m -@tindex matchnot -With the Inverse flag [@code{matchnot}], this command extracts all -vector elements which do @emph{not} match the given pattern. - -@ignore -@starindex -@end ignore -@tindex matches -There is also a function @samp{matches(@var{x}, @var{p})} which -evaluates to 1 if expression @var{x} matches pattern @var{p}, or -to 0 otherwise. This is sometimes useful for including into the -conditional clauses of other rewrite rules. - -@ignore -@starindex -@end ignore -@tindex vmatches -The function @code{vmatches} is just like @code{matches}, except -that if the match succeeds it returns a vector of assignments to -the meta-variables instead of the number 1. For example, -@samp{vmatches(f(1,2), f(a,b))} returns @samp{[a := 1, b := 2]}. -If the match fails, the function returns the number 0. - -@node Automatic Rewrites, Debugging Rewrites, Matching Commands, Rewrite Rules -@subsection Automatic Rewrites - -@noindent -@cindex @code{EvalRules} variable -@vindex EvalRules -It is possible to get Calc to apply a set of rewrite rules on all -results, effectively adding to the built-in set of default -simplifications. To do this, simply store your rule set in the -variable @code{EvalRules}. There is a convenient @kbd{s E} command -for editing @code{EvalRules}; @pxref{Operations on Variables}. - -For example, suppose you want @samp{sin(a + b)} to be expanded out -to @samp{sin(b) cos(a) + cos(b) sin(a)} wherever it appears, and -similarly for @samp{cos(a + b)}. The corresponding rewrite rule -set would be, - -@smallexample -@group -[ sin(a + b) := cos(a) sin(b) + sin(a) cos(b), - cos(a + b) := cos(a) cos(b) - sin(a) sin(b) ] -@end group -@end smallexample - -To apply these manually, you could put them in a variable called -@code{trigexp} and then use @kbd{a r trigexp} every time you wanted -to expand trig functions. But if instead you store them in the -variable @code{EvalRules}, they will automatically be applied to all -sines and cosines of sums. Then, with @samp{2 x} and @samp{45} on -the stack, typing @kbd{+ S} will (assuming Degrees mode) result in -@samp{0.7071 sin(2 x) + 0.7071 cos(2 x)} automatically. - -As each level of a formula is evaluated, the rules from -@code{EvalRules} are applied before the default simplifications. -Rewriting continues until no further @code{EvalRules} apply. -Note that this is different from the usual order of application of -rewrite rules: @code{EvalRules} works from the bottom up, simplifying -the arguments to a function before the function itself, while @kbd{a r} -applies rules from the top down. - -Because the @code{EvalRules} are tried first, you can use them to -override the normal behavior of any built-in Calc function. - -It is important not to write a rule that will get into an infinite -loop. For example, the rule set @samp{[f(0) := 1, f(n) := n f(n-1)]} -appears to be a good definition of a factorial function, but it is -unsafe. Imagine what happens if @samp{f(2.5)} is simplified. Calc -will continue to subtract 1 from this argument forever without reaching -zero. A safer second rule would be @samp{f(n) := n f(n-1) :: n>0}. -Another dangerous rule is @samp{g(x, y) := g(y, x)}. Rewriting -@samp{g(2, 4)}, this would bounce back and forth between that and -@samp{g(4, 2)} forever. If an infinite loop in @code{EvalRules} -occurs, Emacs will eventually stop with a ``Computation got stuck -or ran too long'' message. - -Another subtle difference between @code{EvalRules} and regular rewrites -concerns rules that rewrite a formula into an identical formula. For -example, @samp{f(n) := f(floor(n))} ``fails to match'' when @expr{n} is -already an integer. But in @code{EvalRules} this case is detected only -if the righthand side literally becomes the original formula before any -further simplification. This means that @samp{f(n) := f(floor(n))} will -get into an infinite loop if it occurs in @code{EvalRules}. Calc will -replace @samp{f(6)} with @samp{f(floor(6))}, which is different from -@samp{f(6)}, so it will consider the rule to have matched and will -continue simplifying that formula; first the argument is simplified -to get @samp{f(6)}, then the rule matches again to get @samp{f(floor(6))} -again, ad infinitum. A much safer rule would check its argument first, -say, with @samp{f(n) := f(floor(n)) :: !dint(n)}. - -(What really happens is that the rewrite mechanism substitutes the -meta-variables in the righthand side of a rule, compares to see if the -result is the same as the original formula and fails if so, then uses -the default simplifications to simplify the result and compares again -(and again fails if the formula has simplified back to its original -form). The only special wrinkle for the @code{EvalRules} is that the -same rules will come back into play when the default simplifications -are used. What Calc wants to do is build @samp{f(floor(6))}, see that -this is different from the original formula, simplify to @samp{f(6)}, -see that this is the same as the original formula, and thus halt the -rewriting. But while simplifying, @samp{f(6)} will again trigger -the same @code{EvalRules} rule and Calc will get into a loop inside -the rewrite mechanism itself.) - -The @code{phase}, @code{schedule}, and @code{iterations} markers do -not work in @code{EvalRules}. If the rule set is divided into phases, -only the phase 1 rules are applied, and the schedule is ignored. -The rules are always repeated as many times as possible. - -The @code{EvalRules} are applied to all function calls in a formula, -but not to numbers (and other number-like objects like error forms), -nor to vectors or individual variable names. (Though they will apply -to @emph{components} of vectors and error forms when appropriate.) You -might try to make a variable @code{phihat} which automatically expands -to its definition without the need to press @kbd{=} by writing the -rule @samp{quote(phihat) := (1-sqrt(5))/2}, but unfortunately this rule -will not work as part of @code{EvalRules}. - -Finally, another limitation is that Calc sometimes calls its built-in -functions directly rather than going through the default simplifications. -When it does this, @code{EvalRules} will not be able to override those -functions. For example, when you take the absolute value of the complex -number @expr{(2, 3)}, Calc computes @samp{sqrt(2*2 + 3*3)} by calling -the multiplication, addition, and square root functions directly rather -than applying the default simplifications to this formula. So an -@code{EvalRules} rule that (perversely) rewrites @samp{sqrt(13) := 6} -would not apply. (However, if you put Calc into Symbolic mode so that -@samp{sqrt(13)} will be left in symbolic form by the built-in square -root function, your rule will be able to apply. But if the complex -number were @expr{(3,4)}, so that @samp{sqrt(25)} must be calculated, -then Symbolic mode will not help because @samp{sqrt(25)} can be -evaluated exactly to 5.) - -One subtle restriction that normally only manifests itself with -@code{EvalRules} is that while a given rewrite rule is in the process -of being checked, that same rule cannot be recursively applied. Calc -effectively removes the rule from its rule set while checking the rule, -then puts it back once the match succeeds or fails. (The technical -reason for this is that compiled pattern programs are not reentrant.) -For example, consider the rule @samp{foo(x) := x :: foo(x/2) > 0} -attempting to match @samp{foo(8)}. This rule will be inactive while -the condition @samp{foo(4) > 0} is checked, even though it might be -an integral part of evaluating that condition. Note that this is not -a problem for the more usual recursive type of rule, such as -@samp{foo(x) := foo(x/2)}, because there the rule has succeeded and -been reactivated by the time the righthand side is evaluated. - -If @code{EvalRules} has no stored value (its default state), or if -anything but a vector is stored in it, then it is ignored. - -Even though Calc's rewrite mechanism is designed to compare rewrite -rules to formulas as quickly as possible, storing rules in -@code{EvalRules} may make Calc run substantially slower. This is -particularly true of rules where the top-level call is a commonly used -function, or is not fixed. The rule @samp{f(n) := n f(n-1) :: n>0} will -only activate the rewrite mechanism for calls to the function @code{f}, -but @samp{lg(n) + lg(m) := lg(n m)} will check every @samp{+} operator. - -@smallexample -apply(f, [a*b]) := apply(f, [a]) + apply(f, [b]) :: in(f, [ln, log10]) -@end smallexample - -@noindent -may seem more ``efficient'' than two separate rules for @code{ln} and -@code{log10}, but actually it is vastly less efficient because rules -with @code{apply} as the top-level pattern must be tested against -@emph{every} function call that is simplified. - -@cindex @code{AlgSimpRules} variable -@vindex AlgSimpRules -Suppose you want @samp{sin(a + b)} to be expanded out not all the time, -but only when @kbd{a s} is used to simplify the formula. The variable -@code{AlgSimpRules} holds rules for this purpose. The @kbd{a s} command -will apply @code{EvalRules} and @code{AlgSimpRules} to the formula, as -well as all of its built-in simplifications. - -Most of the special limitations for @code{EvalRules} don't apply to -@code{AlgSimpRules}. Calc simply does an @kbd{a r AlgSimpRules} -command with an infinite repeat count as the first step of @kbd{a s}. -It then applies its own built-in simplifications throughout the -formula, and then repeats these two steps (along with applying the -default simplifications) until no further changes are possible. - -@cindex @code{ExtSimpRules} variable -@cindex @code{UnitSimpRules} variable -@vindex ExtSimpRules -@vindex UnitSimpRules -There are also @code{ExtSimpRules} and @code{UnitSimpRules} variables -that are used by @kbd{a e} and @kbd{u s}, respectively; these commands -also apply @code{EvalRules} and @code{AlgSimpRules}. The variable -@code{IntegSimpRules} contains simplification rules that are used -only during integration by @kbd{a i}. - -@node Debugging Rewrites, Examples of Rewrite Rules, Automatic Rewrites, Rewrite Rules -@subsection Debugging Rewrites - -@noindent -If a buffer named @samp{*Trace*} exists, the rewrite mechanism will -record some useful information there as it operates. The original -formula is written there, as is the result of each successful rewrite, -and the final result of the rewriting. All phase changes are also -noted. - -Calc always appends to @samp{*Trace*}. You must empty this buffer -yourself periodically if it is in danger of growing unwieldy. - -Note that the rewriting mechanism is substantially slower when the -@samp{*Trace*} buffer exists, even if the buffer is not visible on -the screen. Once you are done, you will probably want to kill this -buffer (with @kbd{C-x k *Trace* @key{RET}}). If you leave it in -existence and forget about it, all your future rewrite commands will -be needlessly slow. - -@node Examples of Rewrite Rules, , Debugging Rewrites, Rewrite Rules -@subsection Examples of Rewrite Rules - -@noindent -Returning to the example of substituting the pattern -@samp{sin(x)^2 + cos(x)^2} with 1, we saw that the rule -@samp{opt(a) sin(x)^2 + opt(a) cos(x)^2 := a} does a good job of -finding suitable cases. Another solution would be to use the rule -@samp{cos(x)^2 := 1 - sin(x)^2}, followed by algebraic simplification -if necessary. This rule will be the most effective way to do the job, -but at the expense of making some changes that you might not desire. - -Another algebraic rewrite rule is @samp{exp(x+y) := exp(x) exp(y)}. -To make this work with the @w{@kbd{j r}} command so that it can be -easily targeted to a particular exponential in a large formula, -you might wish to write the rule as @samp{select(exp(x+y)) := -select(exp(x) exp(y))}. The @samp{select} markers will be -ignored by the regular @kbd{a r} command -(@pxref{Selections with Rewrite Rules}). - -A surprisingly useful rewrite rule is @samp{a/(b-c) := a*(b+c)/(b^2-c^2)}. -This will simplify the formula whenever @expr{b} and/or @expr{c} can -be made simpler by squaring. For example, applying this rule to -@samp{2 / (sqrt(2) + 3)} yields @samp{6:7 - 2:7 sqrt(2)} (assuming -Symbolic mode has been enabled to keep the square root from being -evaluated to a floating-point approximation). This rule is also -useful when working with symbolic complex numbers, e.g., -@samp{(a + b i) / (c + d i)}. - -As another example, we could define our own ``triangular numbers'' function -with the rules @samp{[tri(0) := 0, tri(n) := n + tri(n-1) :: n>0]}. Enter -this vector and store it in a variable: @kbd{@w{s t} trirules}. Now, given -a suitable formula like @samp{tri(5)} on the stack, type @samp{a r trirules} -to apply these rules repeatedly. After six applications, @kbd{a r} will -stop with 15 on the stack. Once these rules are debugged, it would probably -be most useful to add them to @code{EvalRules} so that Calc will evaluate -the new @code{tri} function automatically. We could then use @kbd{Z K} on -the keyboard macro @kbd{' tri($) @key{RET}} to make a command that applies -@code{tri} to the value on the top of the stack. @xref{Programming}. - -@cindex Quaternions -The following rule set, contributed by -@texline Fran\c cois -@infoline Francois -Pinard, implements @dfn{quaternions}, a generalization of the concept of -complex numbers. Quaternions have four components, and are here -represented by function calls @samp{quat(@var{w}, [@var{x}, @var{y}, -@var{z}])} with ``real part'' @var{w} and the three ``imaginary'' parts -collected into a vector. Various arithmetical operations on quaternions -are supported. To use these rules, either add them to @code{EvalRules}, -or create a command based on @kbd{a r} for simplifying quaternion -formulas. A convenient way to enter quaternions would be a command -defined by a keyboard macro containing: @kbd{' quat($$$$, [$$$, $$, $]) -@key{RET}}. - -@smallexample -[ quat(w, x, y, z) := quat(w, [x, y, z]), - quat(w, [0, 0, 0]) := w, - abs(quat(w, v)) := hypot(w, v), - -quat(w, v) := quat(-w, -v), - r + quat(w, v) := quat(r + w, v) :: real(r), - r - quat(w, v) := quat(r - w, -v) :: real(r), - quat(w1, v1) + quat(w2, v2) := quat(w1 + w2, v1 + v2), - r * quat(w, v) := quat(r * w, r * v) :: real(r), - plain(quat(w1, v1) * quat(w2, v2)) - := quat(w1 * w2 - v1 * v2, w1 * v2 + w2 * v1 + cross(v1, v2)), - quat(w1, v1) / r := quat(w1 / r, v1 / r) :: real(r), - z / quat(w, v) := z * quatinv(quat(w, v)), - quatinv(quat(w, v)) := quat(w, -v) / (w^2 + v^2), - quatsqr(quat(w, v)) := quat(w^2 - v^2, 2 * w * v), - quat(w, v)^k := quatsqr(quat(w, v)^(k / 2)) - :: integer(k) :: k > 0 :: k % 2 = 0, - quat(w, v)^k := quatsqr(quat(w, v)^((k - 1) / 2)) * quat(w, v) - :: integer(k) :: k > 2, - quat(w, v)^-k := quatinv(quat(w, v)^k) :: integer(k) :: k > 0 ] -@end smallexample - -Quaternions, like matrices, have non-commutative multiplication. -In other words, @expr{q1 * q2 = q2 * q1} is not necessarily true if -@expr{q1} and @expr{q2} are @code{quat} forms. The @samp{quat*quat} -rule above uses @code{plain} to prevent Calc from rearranging the -product. It may also be wise to add the line @samp{[quat(), matrix]} -to the @code{Decls} matrix, to ensure that Calc's other algebraic -operations will not rearrange a quaternion product. @xref{Declarations}. - -These rules also accept a four-argument @code{quat} form, converting -it to the preferred form in the first rule. If you would rather see -results in the four-argument form, just append the two items -@samp{phase(2), quat(w, [x, y, z]) := quat(w, x, y, z)} to the end -of the rule set. (But remember that multi-phase rule sets don't work -in @code{EvalRules}.) - -@node Units, Store and Recall, Algebra, Top -@chapter Operating on Units - -@noindent -One special interpretation of algebraic formulas is as numbers with units. -For example, the formula @samp{5 m / s^2} can be read ``five meters -per second squared.'' The commands in this chapter help you -manipulate units expressions in this form. Units-related commands -begin with the @kbd{u} prefix key. - -@menu -* Basic Operations on Units:: -* The Units Table:: -* Predefined Units:: -* User-Defined Units:: -@end menu - -@node Basic Operations on Units, The Units Table, Units, Units -@section Basic Operations on Units - -@noindent -A @dfn{units expression} is a formula which is basically a number -multiplied and/or divided by one or more @dfn{unit names}, which may -optionally be raised to integer powers. Actually, the value part need not -be a number; any product or quotient involving unit names is a units -expression. Many of the units commands will also accept any formula, -where the command applies to all units expressions which appear in the -formula. - -A unit name is a variable whose name appears in the @dfn{unit table}, -or a variable whose name is a prefix character like @samp{k} (for ``kilo'') -or @samp{u} (for ``micro'') followed by a name in the unit table. -A substantial table of built-in units is provided with Calc; -@pxref{Predefined Units}. You can also define your own unit names; -@pxref{User-Defined Units}. - -Note that if the value part of a units expression is exactly @samp{1}, -it will be removed by the Calculator's automatic algebra routines: The -formula @samp{1 mm} is ``simplified'' to @samp{mm}. This is only a -display anomaly, however; @samp{mm} will work just fine as a -representation of one millimeter. - -You may find that Algebraic mode (@pxref{Algebraic Entry}) makes working -with units expressions easier. Otherwise, you will have to remember -to hit the apostrophe key every time you wish to enter units. - -@kindex u s -@pindex calc-simplify-units -@ignore -@mindex usimpl@idots -@end ignore -@tindex usimplify -The @kbd{u s} (@code{calc-simplify-units}) [@code{usimplify}] command -simplifies a units -expression. It uses @kbd{a s} (@code{calc-simplify}) to simplify the -expression first as a regular algebraic formula; it then looks for -features that can be further simplified by converting one object's units -to be compatible with another's. For example, @samp{5 m + 23 mm} will -simplify to @samp{5.023 m}. When different but compatible units are -added, the righthand term's units are converted to match those of the -lefthand term. @xref{Simplification Modes}, for a way to have this done -automatically at all times. - -Units simplification also handles quotients of two units with the same -dimensionality, as in @w{@samp{2 in s/L cm}} to @samp{5.08 s/L}; fractional -powers of unit expressions, as in @samp{sqrt(9 mm^2)} to @samp{3 mm} and -@samp{sqrt(9 acre)} to a quantity in meters; and @code{floor}, -@code{ceil}, @code{round}, @code{rounde}, @code{roundu}, @code{trunc}, -@code{float}, @code{frac}, @code{abs}, and @code{clean} -applied to units expressions, in which case -the operation in question is applied only to the numeric part of the -expression. Finally, trigonometric functions of quantities with units -of angle are evaluated, regardless of the current angular mode. - -@kindex u c -@pindex calc-convert-units -The @kbd{u c} (@code{calc-convert-units}) command converts a units -expression to new, compatible units. For example, given the units -expression @samp{55 mph}, typing @kbd{u c m/s @key{RET}} produces -@samp{24.5872 m/s}. If you have previously converted a units expression -with the same type of units (in this case, distance over time), you will -be offered the previous choice of new units as a default. Continuing -the above example, entering the units expression @samp{100 km/hr} and -typing @kbd{u c @key{RET}} (without specifying new units) produces -@samp{27.7777777778 m/s}. - -While many of Calc's conversion factors are exact, some are necessarily -approximate. If Calc is in fraction mode (@pxref{Fraction Mode}), then -unit conversions will try to give exact, rational conversions, but it -isn't always possible. Given @samp{55 mph} in fraction mode, typing -@kbd{u c m/s @key{RET}} produces @samp{15367:625 m/s}, for example, -while typing @kbd{u c au/yr @key{RET}} produces -@samp{5.18665819999e-3 au/yr}. - -If the units you request are inconsistent with the original units, the -number will be converted into your units times whatever ``remainder'' -units are left over. For example, converting @samp{55 mph} into acres -produces @samp{6.08e-3 acre / m s}. (Recall that multiplication binds -more strongly than division in Calc formulas, so the units here are -acres per meter-second.) Remainder units are expressed in terms of -``fundamental'' units like @samp{m} and @samp{s}, regardless of the -input units. - -One special exception is that if you specify a single unit name, and -a compatible unit appears somewhere in the units expression, then -that compatible unit will be converted to the new unit and the -remaining units in the expression will be left alone. For example, -given the input @samp{980 cm/s^2}, the command @kbd{u c ms} will -change the @samp{s} to @samp{ms} to get @samp{9.8e-4 cm/ms^2}. -The ``remainder unit'' @samp{cm} is left alone rather than being -changed to the base unit @samp{m}. - -You can use explicit unit conversion instead of the @kbd{u s} command -to gain more control over the units of the result of an expression. -For example, given @samp{5 m + 23 mm}, you can type @kbd{u c m} or -@kbd{u c mm} to express the result in either meters or millimeters. -(For that matter, you could type @kbd{u c fath} to express the result -in fathoms, if you preferred!) - -In place of a specific set of units, you can also enter one of the -units system names @code{si}, @code{mks} (equivalent), or @code{cgs}. -For example, @kbd{u c si @key{RET}} converts the expression into -International System of Units (SI) base units. Also, @kbd{u c base} -converts to Calc's base units, which are the same as @code{si} units -except that @code{base} uses @samp{g} as the fundamental unit of mass -whereas @code{si} uses @samp{kg}. - -@cindex Composite units -The @kbd{u c} command also accepts @dfn{composite units}, which -are expressed as the sum of several compatible unit names. For -example, converting @samp{30.5 in} to units @samp{mi+ft+in} (miles, -feet, and inches) produces @samp{2 ft + 6.5 in}. Calc first -sorts the unit names into order of decreasing relative size. -It then accounts for as much of the input quantity as it can -using an integer number times the largest unit, then moves on -to the next smaller unit, and so on. Only the smallest unit -may have a non-integer amount attached in the result. A few -standard unit names exist for common combinations, such as -@code{mfi} for @samp{mi+ft+in}, and @code{tpo} for @samp{ton+lb+oz}. -Composite units are expanded as if by @kbd{a x}, so that -@samp{(ft+in)/hr} is first converted to @samp{ft/hr+in/hr}. - -If the value on the stack does not contain any units, @kbd{u c} will -prompt first for the old units which this value should be considered -to have, then for the new units. Assuming the old and new units you -give are consistent with each other, the result also will not contain -any units. For example, @kbd{@w{u c} cm @key{RET} in @key{RET}} -converts the number 2 on the stack to 5.08. - -@kindex u b -@pindex calc-base-units -The @kbd{u b} (@code{calc-base-units}) command is shorthand for -@kbd{u c base}; it converts the units expression on the top of the -stack into @code{base} units. If @kbd{u s} does not simplify a -units expression as far as you would like, try @kbd{u b}. - -The @kbd{u c} and @kbd{u b} commands treat temperature units (like -@samp{degC} and @samp{K}) as relative temperatures. For example, -@kbd{u c} converts @samp{10 degC} to @samp{18 degF}: A change of 10 -degrees Celsius corresponds to a change of 18 degrees Fahrenheit. - -@kindex u t -@pindex calc-convert-temperature -@cindex Temperature conversion -The @kbd{u t} (@code{calc-convert-temperature}) command converts -absolute temperatures. The value on the stack must be a simple units -expression with units of temperature only. This command would convert -@samp{10 degC} to @samp{50 degF}, the equivalent temperature on the -Fahrenheit scale. - -@kindex u r -@pindex calc-remove-units -@kindex u x -@pindex calc-extract-units -The @kbd{u r} (@code{calc-remove-units}) command removes units from the -formula at the top of the stack. The @kbd{u x} -(@code{calc-extract-units}) command extracts only the units portion of a -formula. These commands essentially replace every term of the formula -that does or doesn't (respectively) look like a unit name by the -constant 1, then resimplify the formula. - -@kindex u a -@pindex calc-autorange-units -The @kbd{u a} (@code{calc-autorange-units}) command turns on and off a -mode in which unit prefixes like @code{k} (``kilo'') are automatically -applied to keep the numeric part of a units expression in a reasonable -range. This mode affects @kbd{u s} and all units conversion commands -except @kbd{u b}. For example, with autoranging on, @samp{12345 Hz} -will be simplified to @samp{12.345 kHz}. Autoranging is useful for -some kinds of units (like @code{Hz} and @code{m}), but is probably -undesirable for non-metric units like @code{ft} and @code{tbsp}. -(Composite units are more appropriate for those; see above.) - -Autoranging always applies the prefix to the leftmost unit name. -Calc chooses the largest prefix that causes the number to be greater -than or equal to 1.0. Thus an increasing sequence of adjusted times -would be @samp{1 ms, 10 ms, 100 ms, 1 s, 10 s, 100 s, 1 ks}. -Generally the rule of thumb is that the number will be adjusted -to be in the interval @samp{[1 .. 1000)}, although there are several -exceptions to this rule. First, if the unit has a power then this -is not possible; @samp{0.1 s^2} simplifies to @samp{100000 ms^2}. -Second, the ``centi-'' prefix is allowed to form @code{cm} (centimeters), -but will not apply to other units. The ``deci-,'' ``deka-,'' and -``hecto-'' prefixes are never used. Thus the allowable interval is -@samp{[1 .. 10)} for millimeters and @samp{[1 .. 100)} for centimeters. -Finally, a prefix will not be added to a unit if the resulting name -is also the actual name of another unit; @samp{1e-15 t} would normally -be considered a ``femto-ton,'' but it is written as @samp{1000 at} -(1000 atto-tons) instead because @code{ft} would be confused with feet. - -@node The Units Table, Predefined Units, Basic Operations on Units, Units -@section The Units Table - -@noindent -@kindex u v -@pindex calc-enter-units-table -The @kbd{u v} (@code{calc-enter-units-table}) command displays the units table -in another buffer called @code{*Units Table*}. Each entry in this table -gives the unit name as it would appear in an expression, the definition -of the unit in terms of simpler units, and a full name or description of -the unit. Fundamental units are defined as themselves; these are the -units produced by the @kbd{u b} command. The fundamental units are -meters, seconds, grams, kelvins, amperes, candelas, moles, radians, -and steradians. - -The Units Table buffer also displays the Unit Prefix Table. Note that -two prefixes, ``kilo'' and ``hecto,'' accept either upper- or lower-case -prefix letters. @samp{Meg} is also accepted as a synonym for the @samp{M} -prefix. Whenever a unit name can be interpreted as either a built-in name -or a prefix followed by another built-in name, the former interpretation -wins. For example, @samp{2 pt} means two pints, not two pico-tons. - -The Units Table buffer, once created, is not rebuilt unless you define -new units. To force the buffer to be rebuilt, give any numeric prefix -argument to @kbd{u v}. - -@kindex u V -@pindex calc-view-units-table -The @kbd{u V} (@code{calc-view-units-table}) command is like @kbd{u v} except -that the cursor is not moved into the Units Table buffer. You can -type @kbd{u V} again to remove the Units Table from the display. To -return from the Units Table buffer after a @kbd{u v}, type @kbd{C-x * c} -again or use the regular Emacs @w{@kbd{C-x o}} (@code{other-window}) -command. You can also kill the buffer with @kbd{C-x k} if you wish; -the actual units table is safely stored inside the Calculator. - -@kindex u g -@pindex calc-get-unit-definition -The @kbd{u g} (@code{calc-get-unit-definition}) command retrieves a unit's -defining expression and pushes it onto the Calculator stack. For example, -@kbd{u g in} will produce the expression @samp{2.54 cm}. This is the -same definition for the unit that would appear in the Units Table buffer. -Note that this command works only for actual unit names; @kbd{u g km} -will report that no such unit exists, for example, because @code{km} is -really the unit @code{m} with a @code{k} (``kilo'') prefix. To see a -definition of a unit in terms of base units, it is easier to push the -unit name on the stack and then reduce it to base units with @kbd{u b}. - -@kindex u e -@pindex calc-explain-units -The @kbd{u e} (@code{calc-explain-units}) command displays an English -description of the units of the expression on the stack. For example, -for the expression @samp{62 km^2 g / s^2 mol K}, the description is -``Square-Kilometer Gram per (Second-squared Mole Degree-Kelvin).'' This -command uses the English descriptions that appear in the righthand -column of the Units Table. - -@node Predefined Units, User-Defined Units, The Units Table, Units -@section Predefined Units - -@noindent -The definitions of many units have changed over the years. For example, -the meter was originally defined in 1791 as one ten-millionth of the -distance from the equator to the north pole. In order to be more -precise, the definition was adjusted several times, and now a meter is -defined as the distance that light will travel in a vacuum in -1/299792458 of a second; consequently, the speed of light in a -vacuum is exactly 299792458 m/s. Many other units have been -redefined in terms of fundamental physical processes; a second, for -example, is currently defined as 9192631770 periods of a certain -radiation related to the cesium-133 atom. The only SI unit that is not -based on a fundamental physical process (although there are efforts to -change this) is the kilogram, which was originally defined as the mass -of one liter of water, but is now defined as the mass of the -International Prototype Kilogram (IPK), a cylinder of platinum-iridium -kept at the Bureau International des Poids et Mesures in S@`evres, -France. (There are several copies of the IPK throughout the world.) -The British imperial units, once defined in terms of physical objects, -were redefined in 1963 in terms of SI units. The US customary units, -which were the same as British units until the British imperial system -was created in 1824, were also defined in terms of the SI units in 1893. -Because of these redefinitions, conversions between metric, British -Imperial, and US customary units can often be done precisely. - -Since the exact definitions of many kinds of units have evolved over the -years, and since certain countries sometimes have local differences in -their definitions, it is a good idea to examine Calc's definition of a -unit before depending on its exact value. For example, there are three -different units for gallons, corresponding to the US (@code{gal}), -Canadian (@code{galC}), and British (@code{galUK}) definitions. Also, -note that @code{oz} is a standard ounce of mass, @code{ozt} is a Troy -ounce, and @code{ozfl} is a fluid ounce. - -The temperature units corresponding to degrees Kelvin and Centigrade -(Celsius) are the same in this table, since most units commands treat -temperatures as being relative. The @code{calc-convert-temperature} -command has special rules for handling the different absolute magnitudes -of the various temperature scales. - -The unit of volume ``liters'' can be referred to by either the lower-case -@code{l} or the upper-case @code{L}. - -The unit @code{A} stands for Amperes; the name @code{Ang} is used -@tex -for \AA ngstroms. -@end tex -@ifnottex -for Angstroms. -@end ifnottex - -The unit @code{pt} stands for pints; the name @code{point} stands for -a typographical point, defined by @samp{72 point = 1 in}. This is -slightly different than the point defined by the American Typefounder's -Association in 1886, but the point used by Calc has become standard -largely due to its use by the PostScript page description language. -There is also @code{texpt}, which stands for a printer's point as -defined by the @TeX{} typesetting system: @samp{72.27 texpt = 1 in}. -Other units used by @TeX{} are available; they are @code{texpc} (a pica), -@code{texbp} (a ``big point'', equal to a standard point which is larger -than the point used by @TeX{}), @code{texdd} (a Didot point), -@code{texcc} (a Cicero) and @code{texsp} (a scaled @TeX{} point, -all dimensions representable in @TeX{} are multiples of this value). - -The unit @code{e} stands for the elementary (electron) unit of charge; -because algebra command could mistake this for the special constant -@expr{e}, Calc provides the alternate unit name @code{ech} which is -preferable to @code{e}. - -The name @code{g} stands for one gram of mass; there is also @code{gf}, -one gram of force. (Likewise for @kbd{lb}, pounds, and @kbd{lbf}.) -Meanwhile, one ``@expr{g}'' of acceleration is denoted @code{ga}. - -The unit @code{ton} is a U.S. ton of @samp{2000 lb}, and @code{t} is -a metric ton of @samp{1000 kg}. - -The names @code{s} (or @code{sec}) and @code{min} refer to units of -time; @code{arcsec} and @code{arcmin} are units of angle. - -Some ``units'' are really physical constants; for example, @code{c} -represents the speed of light, and @code{h} represents Planck's -constant. You can use these just like other units: converting -@samp{.5 c} to @samp{m/s} expresses one-half the speed of light in -meters per second. You can also use this merely as a handy reference; -the @kbd{u g} command gets the definition of one of these constants -in its normal terms, and @kbd{u b} expresses the definition in base -units. - -Two units, @code{pi} and @code{alpha} (the fine structure constant, -approximately @mathit{1/137}) are dimensionless. The units simplification -commands simply treat these names as equivalent to their corresponding -values. However you can, for example, use @kbd{u c} to convert a pure -number into multiples of the fine structure constant, or @kbd{u b} to -convert this back into a pure number. (When @kbd{u c} prompts for the -``old units,'' just enter a blank line to signify that the value -really is unitless.) - -@c Describe angular units, luminosity vs. steradians problem. - -@node User-Defined Units, , Predefined Units, Units -@section User-Defined Units - -@noindent -Calc provides ways to get quick access to your selected ``favorite'' -units, as well as ways to define your own new units. - -@kindex u 0-9 -@pindex calc-quick-units -@vindex Units -@cindex @code{Units} variable -@cindex Quick units -To select your favorite units, store a vector of unit names or -expressions in the Calc variable @code{Units}. The @kbd{u 1} -through @kbd{u 9} commands (@code{calc-quick-units}) provide access -to these units. If the value on the top of the stack is a plain -number (with no units attached), then @kbd{u 1} gives it the -specified units. (Basically, it multiplies the number by the -first item in the @code{Units} vector.) If the number on the -stack @emph{does} have units, then @kbd{u 1} converts that number -to the new units. For example, suppose the vector @samp{[in, ft]} -is stored in @code{Units}. Then @kbd{30 u 1} will create the -expression @samp{30 in}, and @kbd{u 2} will convert that expression -to @samp{2.5 ft}. - -The @kbd{u 0} command accesses the tenth element of @code{Units}. -Only ten quick units may be defined at a time. If the @code{Units} -variable has no stored value (the default), or if its value is not -a vector, then the quick-units commands will not function. The -@kbd{s U} command is a convenient way to edit the @code{Units} -variable; @pxref{Operations on Variables}. - -@kindex u d -@pindex calc-define-unit -@cindex User-defined units -The @kbd{u d} (@code{calc-define-unit}) command records the units -expression on the top of the stack as the definition for a new, -user-defined unit. For example, putting @samp{16.5 ft} on the stack and -typing @kbd{u d rod} defines the new unit @samp{rod} to be equivalent to -16.5 feet. The unit conversion and simplification commands will now -treat @code{rod} just like any other unit of length. You will also be -prompted for an optional English description of the unit, which will -appear in the Units Table. If you wish the definition of this unit to -be displayed in a special way in the Units Table buffer (such as with an -asterisk to indicate an approximate value), then you can call this -command with an argument, @kbd{C-u u d}; you will then also be prompted -for a string that will be used to display the definition. - -@kindex u u -@pindex calc-undefine-unit -The @kbd{u u} (@code{calc-undefine-unit}) command removes a user-defined -unit. It is not possible to remove one of the predefined units, -however. - -If you define a unit with an existing unit name, your new definition -will replace the original definition of that unit. If the unit was a -predefined unit, the old definition will not be replaced, only -``shadowed.'' The built-in definition will reappear if you later use -@kbd{u u} to remove the shadowing definition. - -To create a new fundamental unit, use either 1 or the unit name itself -as the defining expression. Otherwise the expression can involve any -other units that you like (except for composite units like @samp{mfi}). -You can create a new composite unit with a sum of other units as the -defining expression. The next unit operation like @kbd{u c} or @kbd{u v} -will rebuild the internal unit table incorporating your modifications. -Note that erroneous definitions (such as two units defined in terms of -each other) will not be detected until the unit table is next rebuilt; -@kbd{u v} is a convenient way to force this to happen. - -Temperature units are treated specially inside the Calculator; it is not -possible to create user-defined temperature units. - -@kindex u p -@pindex calc-permanent-units -@cindex Calc init file, user-defined units -The @kbd{u p} (@code{calc-permanent-units}) command stores the user-defined -units in your Calc init file (the file given by the variable -@code{calc-settings-file}, typically @file{~/.calc.el}), so that the -units will still be available in subsequent Emacs sessions. If there -was already a set of user-defined units in your Calc init file, it -is replaced by the new set. (@xref{General Mode Commands}, for a way to -tell Calc to use a different file for the Calc init file.) - -@node Store and Recall, Graphics, Units, Top -@chapter Storing and Recalling - -@noindent -Calculator variables are really just Lisp variables that contain numbers -or formulas in a form that Calc can understand. The commands in this -section allow you to manipulate variables conveniently. Commands related -to variables use the @kbd{s} prefix key. - -@menu -* Storing Variables:: -* Recalling Variables:: -* Operations on Variables:: -* Let Command:: -* Evaluates-To Operator:: -@end menu - -@node Storing Variables, Recalling Variables, Store and Recall, Store and Recall -@section Storing Variables - -@noindent -@kindex s s -@pindex calc-store -@cindex Storing variables -@cindex Quick variables -@vindex q0 -@vindex q9 -The @kbd{s s} (@code{calc-store}) command stores the value at the top of -the stack into a specified variable. It prompts you to enter the -name of the variable. If you press a single digit, the value is stored -immediately in one of the ``quick'' variables @code{q0} through -@code{q9}. Or you can enter any variable name. - -@kindex s t -@pindex calc-store-into -The @kbd{s s} command leaves the stored value on the stack. There is -also an @kbd{s t} (@code{calc-store-into}) command, which removes a -value from the stack and stores it in a variable. - -If the top of stack value is an equation @samp{a = 7} or assignment -@samp{a := 7} with a variable on the lefthand side, then Calc will -assign that variable with that value by default, i.e., if you type -@kbd{s s @key{RET}} or @kbd{s t @key{RET}}. In this example, the -value 7 would be stored in the variable @samp{a}. (If you do type -a variable name at the prompt, the top-of-stack value is stored in -its entirety, even if it is an equation: @samp{s s b @key{RET}} -with @samp{a := 7} on the stack stores @samp{a := 7} in @code{b}.) - -In fact, the top of stack value can be a vector of equations or -assignments with different variables on their lefthand sides; the -default will be to store all the variables with their corresponding -righthand sides simultaneously. - -It is also possible to type an equation or assignment directly at -the prompt for the @kbd{s s} or @kbd{s t} command: @kbd{s s foo = 7}. -In this case the expression to the right of the @kbd{=} or @kbd{:=} -symbol is evaluated as if by the @kbd{=} command, and that value is -stored in the variable. No value is taken from the stack; @kbd{s s} -and @kbd{s t} are equivalent when used in this way. - -@kindex s 0-9 -@kindex t 0-9 -The prefix keys @kbd{s} and @kbd{t} may be followed immediately by a -digit; @kbd{s 9} is equivalent to @kbd{s s 9}, and @kbd{t 9} is -equivalent to @kbd{s t 9}. (The @kbd{t} prefix is otherwise used -for trail and time/date commands.) - -@kindex s + -@kindex s - -@ignore -@mindex @idots -@end ignore -@kindex s * -@ignore -@mindex @null -@end ignore -@kindex s / -@ignore -@mindex @null -@end ignore -@kindex s ^ -@ignore -@mindex @null -@end ignore -@kindex s | -@ignore -@mindex @null -@end ignore -@kindex s n -@ignore -@mindex @null -@end ignore -@kindex s & -@ignore -@mindex @null -@end ignore -@kindex s [ -@ignore -@mindex @null -@end ignore -@kindex s ] -@pindex calc-store-plus -@pindex calc-store-minus -@pindex calc-store-times -@pindex calc-store-div -@pindex calc-store-power -@pindex calc-store-concat -@pindex calc-store-neg -@pindex calc-store-inv -@pindex calc-store-decr -@pindex calc-store-incr -There are also several ``arithmetic store'' commands. For example, -@kbd{s +} removes a value from the stack and adds it to the specified -variable. The other arithmetic stores are @kbd{s -}, @kbd{s *}, @kbd{s /}, -@kbd{s ^}, and @w{@kbd{s |}} (vector concatenation), plus @kbd{s n} and -@kbd{s &} which negate or invert the value in a variable, and @w{@kbd{s [}} -and @kbd{s ]} which decrease or increase a variable by one. - -All the arithmetic stores accept the Inverse prefix to reverse the -order of the operands. If @expr{v} represents the contents of the -variable, and @expr{a} is the value drawn from the stack, then regular -@w{@kbd{s -}} assigns -@texline @math{v \coloneq v - a}, -@infoline @expr{v := v - a}, -but @kbd{I s -} assigns -@texline @math{v \coloneq a - v}. -@infoline @expr{v := a - v}. -While @kbd{I s *} might seem pointless, it is -useful if matrix multiplication is involved. Actually, all the -arithmetic stores use formulas designed to behave usefully both -forwards and backwards: - -@example -@group -s + v := v + a v := a + v -s - v := v - a v := a - v -s * v := v * a v := a * v -s / v := v / a v := a / v -s ^ v := v ^ a v := a ^ v -s | v := v | a v := a | v -s n v := v / (-1) v := (-1) / v -s & v := v ^ (-1) v := (-1) ^ v -s [ v := v - 1 v := 1 - v -s ] v := v - (-1) v := (-1) - v -@end group -@end example - -In the last four cases, a numeric prefix argument will be used in -place of the number one. (For example, @kbd{M-2 s ]} increases -a variable by 2, and @kbd{M-2 I s ]} replaces a variable by -minus-two minus the variable. - -The first six arithmetic stores can also be typed @kbd{s t +}, @kbd{s t -}, -etc. The commands @kbd{s s +}, @kbd{s s -}, and so on are analogous -arithmetic stores that don't remove the value @expr{a} from the stack. - -All arithmetic stores report the new value of the variable in the -Trail for your information. They signal an error if the variable -previously had no stored value. If default simplifications have been -turned off, the arithmetic stores temporarily turn them on for numeric -arguments only (i.e., they temporarily do an @kbd{m N} command). -@xref{Simplification Modes}. Large vectors put in the trail by -these commands always use abbreviated (@kbd{t .}) mode. - -@kindex s m -@pindex calc-store-map -The @kbd{s m} command is a general way to adjust a variable's value -using any Calc function. It is a ``mapping'' command analogous to -@kbd{V M}, @kbd{V R}, etc. @xref{Reducing and Mapping}, to see -how to specify a function for a mapping command. Basically, -all you do is type the Calc command key that would invoke that -function normally. For example, @kbd{s m n} applies the @kbd{n} -key to negate the contents of the variable, so @kbd{s m n} is -equivalent to @kbd{s n}. Also, @kbd{s m Q} takes the square root -of the value stored in a variable, @kbd{s m v v} uses @kbd{v v} to -reverse the vector stored in the variable, and @kbd{s m H I S} -takes the hyperbolic arcsine of the variable contents. - -If the mapping function takes two or more arguments, the additional -arguments are taken from the stack; the old value of the variable -is provided as the first argument. Thus @kbd{s m -} with @expr{a} -on the stack computes @expr{v - a}, just like @kbd{s -}. With the -Inverse prefix, the variable's original value becomes the @emph{last} -argument instead of the first. Thus @kbd{I s m -} is also -equivalent to @kbd{I s -}. - -@kindex s x -@pindex calc-store-exchange -The @kbd{s x} (@code{calc-store-exchange}) command exchanges the value -of a variable with the value on the top of the stack. Naturally, the -variable must already have a stored value for this to work. - -You can type an equation or assignment at the @kbd{s x} prompt. The -command @kbd{s x a=6} takes no values from the stack; instead, it -pushes the old value of @samp{a} on the stack and stores @samp{a = 6}. - -@kindex s u -@pindex calc-unstore -@cindex Void variables -@cindex Un-storing variables -Until you store something in them, most variables are ``void,'' that is, -they contain no value at all. If they appear in an algebraic formula -they will be left alone even if you press @kbd{=} (@code{calc-evaluate}). -The @kbd{s u} (@code{calc-unstore}) command returns a variable to the -void state. - -@kindex s c -@pindex calc-copy-variable -The @kbd{s c} (@code{calc-copy-variable}) command copies the stored -value of one variable to another. One way it differs from a simple -@kbd{s r} followed by an @kbd{s t} (aside from saving keystrokes) is -that the value never goes on the stack and thus is never rounded, -evaluated, or simplified in any way; it is not even rounded down to the -current precision. - -The only variables with predefined values are the ``special constants'' -@code{pi}, @code{e}, @code{i}, @code{phi}, and @code{gamma}. You are free -to unstore these variables or to store new values into them if you like, -although some of the algebraic-manipulation functions may assume these -variables represent their standard values. Calc displays a warning if -you change the value of one of these variables, or of one of the other -special variables @code{inf}, @code{uinf}, and @code{nan} (which are -normally void). - -Note that @code{pi} doesn't actually have 3.14159265359 stored in it, -but rather a special magic value that evaluates to @cpi{} at the current -precision. Likewise @code{e}, @code{i}, and @code{phi} evaluate -according to the current precision or polar mode. If you recall a value -from @code{pi} and store it back, this magic property will be lost. The -magic property is preserved, however, when a variable is copied with -@kbd{s c}. - -@kindex s k -@pindex calc-copy-special-constant -If one of the ``special constants'' is redefined (or undefined) so that -it no longer has its magic property, the property can be restored with -@kbd{s k} (@code{calc-copy-special-constant}). This command will prompt -for a special constant and a variable to store it in, and so a special -constant can be stored in any variable. Here, the special constant that -you enter doesn't depend on the value of the corresponding variable; -@code{pi} will represent 3.14159@dots{} regardless of what is currently -stored in the Calc variable @code{pi}. If one of the other special -variables, @code{inf}, @code{uinf} or @code{nan}, is given a value, its -original behavior can be restored by voiding it with @kbd{s u}. - -@node Recalling Variables, Operations on Variables, Storing Variables, Store and Recall -@section Recalling Variables - -@noindent -@kindex s r -@pindex calc-recall -@cindex Recalling variables -The most straightforward way to extract the stored value from a variable -is to use the @kbd{s r} (@code{calc-recall}) command. This command prompts -for a variable name (similarly to @code{calc-store}), looks up the value -of the specified variable, and pushes that value onto the stack. It is -an error to try to recall a void variable. - -It is also possible to recall the value from a variable by evaluating a -formula containing that variable. For example, @kbd{' a @key{RET} =} is -the same as @kbd{s r a @key{RET}} except that if the variable is void, the -former will simply leave the formula @samp{a} on the stack whereas the -latter will produce an error message. - -@kindex r 0-9 -The @kbd{r} prefix may be followed by a digit, so that @kbd{r 9} is -equivalent to @kbd{s r 9}. - -@node Operations on Variables, Let Command, Recalling Variables, Store and Recall -@section Other Operations on Variables - -@noindent -@kindex s e -@pindex calc-edit-variable -The @kbd{s e} (@code{calc-edit-variable}) command edits the stored -value of a variable without ever putting that value on the stack -or simplifying or evaluating the value. It prompts for the name of -the variable to edit. If the variable has no stored value, the -editing buffer will start out empty. If the editing buffer is -empty when you press @kbd{C-c C-c} to finish, the variable will -be made void. @xref{Editing Stack Entries}, for a general -description of editing. - -The @kbd{s e} command is especially useful for creating and editing -rewrite rules which are stored in variables. Sometimes these rules -contain formulas which must not be evaluated until the rules are -actually used. (For example, they may refer to @samp{deriv(x,y)}, -where @code{x} will someday become some expression involving @code{y}; -if you let Calc evaluate the rule while you are defining it, Calc will -replace @samp{deriv(x,y)} with 0 because the formula @code{x} does -not itself refer to @code{y}.) By contrast, recalling the variable, -editing with @kbd{`}, and storing will evaluate the variable's value -as a side effect of putting the value on the stack. - -@kindex s A -@kindex s D -@ignore -@mindex @idots -@end ignore -@kindex s E -@ignore -@mindex @null -@end ignore -@kindex s F -@ignore -@mindex @null -@end ignore -@kindex s G -@ignore -@mindex @null -@end ignore -@kindex s H -@ignore -@mindex @null -@end ignore -@kindex s I -@ignore -@mindex @null -@end ignore -@kindex s L -@ignore -@mindex @null -@end ignore -@kindex s P -@ignore -@mindex @null -@end ignore -@kindex s R -@ignore -@mindex @null -@end ignore -@kindex s T -@ignore -@mindex @null -@end ignore -@kindex s U -@ignore -@mindex @null -@end ignore -@kindex s X -@pindex calc-store-AlgSimpRules -@pindex calc-store-Decls -@pindex calc-store-EvalRules -@pindex calc-store-FitRules -@pindex calc-store-GenCount -@pindex calc-store-Holidays -@pindex calc-store-IntegLimit -@pindex calc-store-LineStyles -@pindex calc-store-PointStyles -@pindex calc-store-PlotRejects -@pindex calc-store-TimeZone -@pindex calc-store-Units -@pindex calc-store-ExtSimpRules -There are several special-purpose variable-editing commands that -use the @kbd{s} prefix followed by a shifted letter: - -@table @kbd -@item s A -Edit @code{AlgSimpRules}. @xref{Algebraic Simplifications}. -@item s D -Edit @code{Decls}. @xref{Declarations}. -@item s E -Edit @code{EvalRules}. @xref{Default Simplifications}. -@item s F -Edit @code{FitRules}. @xref{Curve Fitting}. -@item s G -Edit @code{GenCount}. @xref{Solving Equations}. -@item s H -Edit @code{Holidays}. @xref{Business Days}. -@item s I -Edit @code{IntegLimit}. @xref{Calculus}. -@item s L -Edit @code{LineStyles}. @xref{Graphics}. -@item s P -Edit @code{PointStyles}. @xref{Graphics}. -@item s R -Edit @code{PlotRejects}. @xref{Graphics}. -@item s T -Edit @code{TimeZone}. @xref{Time Zones}. -@item s U -Edit @code{Units}. @xref{User-Defined Units}. -@item s X -Edit @code{ExtSimpRules}. @xref{Unsafe Simplifications}. -@end table - -These commands are just versions of @kbd{s e} that use fixed variable -names rather than prompting for the variable name. - -@kindex s p -@pindex calc-permanent-variable -@cindex Storing variables -@cindex Permanent variables -@cindex Calc init file, variables -The @kbd{s p} (@code{calc-permanent-variable}) command saves a -variable's value permanently in your Calc init file (the file given by -the variable @code{calc-settings-file}, typically @file{~/.calc.el}), so -that its value will still be available in future Emacs sessions. You -can re-execute @w{@kbd{s p}} later on to update the saved value, but the -only way to remove a saved variable is to edit your calc init file -by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -If you do not specify the name of a variable to save (i.e., -@kbd{s p @key{RET}}), all Calc variables with defined values -are saved except for the special constants @code{pi}, @code{e}, -@code{i}, @code{phi}, and @code{gamma}; the variables @code{TimeZone} -and @code{PlotRejects}; -@code{FitRules}, @code{DistribRules}, and other built-in rewrite -rules; and @code{PlotData@var{n}} variables generated -by the graphics commands. (You can still save these variables by -explicitly naming them in an @kbd{s p} command.) - -@kindex s i -@pindex calc-insert-variables -The @kbd{s i} (@code{calc-insert-variables}) command writes -the values of all Calc variables into a specified buffer. -The variables are written with the prefix @code{var-} in the form of -Lisp @code{setq} commands -which store the values in string form. You can place these commands -in your Calc init file (or @file{.emacs}) if you wish, though in this case it -would be easier to use @kbd{s p @key{RET}}. (Note that @kbd{s i} -omits the same set of variables as @w{@kbd{s p @key{RET}}}; the difference -is that @kbd{s i} will store the variables in any buffer, and it also -stores in a more human-readable format.) - -@node Let Command, Evaluates-To Operator, Operations on Variables, Store and Recall -@section The Let Command - -@noindent -@kindex s l -@pindex calc-let -@cindex Variables, temporary assignment -@cindex Temporary assignment to variables -If you have an expression like @samp{a+b^2} on the stack and you wish to -compute its value where @expr{b=3}, you can simply store 3 in @expr{b} and -then press @kbd{=} to reevaluate the formula. This has the side-effect -of leaving the stored value of 3 in @expr{b} for future operations. - -The @kbd{s l} (@code{calc-let}) command evaluates a formula under a -@emph{temporary} assignment of a variable. It stores the value on the -top of the stack into the specified variable, then evaluates the -second-to-top stack entry, then restores the original value (or lack of one) -in the variable. Thus after @kbd{'@w{ }a+b^2 @key{RET} 3 s l b @key{RET}}, -the stack will contain the formula @samp{a + 9}. The subsequent command -@kbd{@w{5 s l a} @key{RET}} will replace this formula with the number 14. -The variables @samp{a} and @samp{b} are not permanently affected in any way -by these commands. - -The value on the top of the stack may be an equation or assignment, or -a vector of equations or assignments, in which case the default will be -analogous to the case of @kbd{s t @key{RET}}. @xref{Storing Variables}. - -Also, you can answer the variable-name prompt with an equation or -assignment: @kbd{s l b=3 @key{RET}} is the same as storing 3 on the stack -and typing @kbd{s l b @key{RET}}. - -The @kbd{a b} (@code{calc-substitute}) command is another way to substitute -a variable with a value in a formula. It does an actual substitution -rather than temporarily assigning the variable and evaluating. For -example, letting @expr{n=2} in @samp{f(n pi)} with @kbd{a b} will -produce @samp{f(2 pi)}, whereas @kbd{s l} would give @samp{f(6.28)} -since the evaluation step will also evaluate @code{pi}. - -@node Evaluates-To Operator, , Let Command, Store and Recall -@section The Evaluates-To Operator - -@noindent -@tindex evalto -@tindex => -@cindex Evaluates-to operator -@cindex @samp{=>} operator -The special algebraic symbol @samp{=>} is known as the @dfn{evaluates-to -operator}. (It will show up as an @code{evalto} function call in -other language modes like Pascal and La@TeX{}.) This is a binary -operator, that is, it has a lefthand and a righthand argument, -although it can be entered with the righthand argument omitted. - -A formula like @samp{@var{a} => @var{b}} is evaluated by Calc as -follows: First, @var{a} is not simplified or modified in any -way. The previous value of argument @var{b} is thrown away; the -formula @var{a} is then copied and evaluated as if by the @kbd{=} -command according to all current modes and stored variable values, -and the result is installed as the new value of @var{b}. - -For example, suppose you enter the algebraic formula @samp{2 + 3 => 17}. -The number 17 is ignored, and the lefthand argument is left in its -unevaluated form; the result is the formula @samp{2 + 3 => 5}. - -@kindex s = -@pindex calc-evalto -You can enter an @samp{=>} formula either directly using algebraic -entry (in which case the righthand side may be omitted since it is -going to be replaced right away anyhow), or by using the @kbd{s =} -(@code{calc-evalto}) command, which takes @var{a} from the stack -and replaces it with @samp{@var{a} => @var{b}}. - -Calc keeps track of all @samp{=>} operators on the stack, and -recomputes them whenever anything changes that might affect their -values, i.e., a mode setting or variable value. This occurs only -if the @samp{=>} operator is at the top level of the formula, or -if it is part of a top-level vector. In other words, pushing -@samp{2 + (a => 17)} will change the 17 to the actual value of -@samp{a} when you enter the formula, but the result will not be -dynamically updated when @samp{a} is changed later because the -@samp{=>} operator is buried inside a sum. However, a vector -of @samp{=>} operators will be recomputed, since it is convenient -to push a vector like @samp{[a =>, b =>, c =>]} on the stack to -make a concise display of all the variables in your problem. -(Another way to do this would be to use @samp{[a, b, c] =>}, -which provides a slightly different format of display. You -can use whichever you find easiest to read.) - -@kindex m C -@pindex calc-auto-recompute -The @kbd{m C} (@code{calc-auto-recompute}) command allows you to -turn this automatic recomputation on or off. If you turn -recomputation off, you must explicitly recompute an @samp{=>} -operator on the stack in one of the usual ways, such as by -pressing @kbd{=}. Turning recomputation off temporarily can save -a lot of time if you will be changing several modes or variables -before you look at the @samp{=>} entries again. - -Most commands are not especially useful with @samp{=>} operators -as arguments. For example, given @samp{x + 2 => 17}, it won't -work to type @kbd{1 +} to get @samp{x + 3 => 18}. If you want -to operate on the lefthand side of the @samp{=>} operator on -the top of the stack, type @kbd{j 1} (that's the digit ``one'') -to select the lefthand side, execute your commands, then type -@kbd{j u} to unselect. - -All current modes apply when an @samp{=>} operator is computed, -including the current simplification mode. Recall that the -formula @samp{x + y + x} is not handled by Calc's default -simplifications, but the @kbd{a s} command will reduce it to -the simpler form @samp{y + 2 x}. You can also type @kbd{m A} -to enable an Algebraic Simplification mode in which the -equivalent of @kbd{a s} is used on all of Calc's results. -If you enter @samp{x + y + x =>} normally, the result will -be @samp{x + y + x => x + y + x}. If you change to -Algebraic Simplification mode, the result will be -@samp{x + y + x => y + 2 x}. However, just pressing @kbd{a s} -once will have no effect on @samp{x + y + x => x + y + x}, -because the righthand side depends only on the lefthand side -and the current mode settings, and the lefthand side is not -affected by commands like @kbd{a s}. - -The ``let'' command (@kbd{s l}) has an interesting interaction -with the @samp{=>} operator. The @kbd{s l} command evaluates the -second-to-top stack entry with the top stack entry supplying -a temporary value for a given variable. As you might expect, -if that stack entry is an @samp{=>} operator its righthand -side will temporarily show this value for the variable. In -fact, all @samp{=>}s on the stack will be updated if they refer -to that variable. But this change is temporary in the sense -that the next command that causes Calc to look at those stack -entries will make them revert to the old variable value. - -@smallexample -@group -2: a => a 2: a => 17 2: a => a -1: a + 1 => a + 1 1: a + 1 => 18 1: a + 1 => a + 1 - . . . - - 17 s l a @key{RET} p 8 @key{RET} -@end group -@end smallexample - -Here the @kbd{p 8} command changes the current precision, -thus causing the @samp{=>} forms to be recomputed after the -influence of the ``let'' is gone. The @kbd{d @key{SPC}} command -(@code{calc-refresh}) is a handy way to force the @samp{=>} -operators on the stack to be recomputed without any other -side effects. - -@kindex s : -@pindex calc-assign -@tindex assign -@tindex := -Embedded mode also uses @samp{=>} operators. In Embedded mode, -the lefthand side of an @samp{=>} operator can refer to variables -assigned elsewhere in the file by @samp{:=} operators. The -assignment operator @samp{a := 17} does not actually do anything -by itself. But Embedded mode recognizes it and marks it as a sort -of file-local definition of the variable. You can enter @samp{:=} -operators in Algebraic mode, or by using the @kbd{s :} -(@code{calc-assign}) [@code{assign}] command which takes a variable -and value from the stack and replaces them with an assignment. - -@xref{TeX and LaTeX Language Modes}, for the way @samp{=>} appears in -@TeX{} language output. The @dfn{eqn} mode gives similar -treatment to @samp{=>}. - -@node Graphics, Kill and Yank, Store and Recall, Top -@chapter Graphics - -@noindent -The commands for graphing data begin with the @kbd{g} prefix key. Calc -uses GNUPLOT 2.0 or later to do graphics. These commands will only work -if GNUPLOT is available on your system. (While GNUPLOT sounds like -a relative of GNU Emacs, it is actually completely unrelated. -However, it is free software. It can be obtained from -@samp{http://www.gnuplot.info}.) - -@vindex calc-gnuplot-name -If you have GNUPLOT installed on your system but Calc is unable to -find it, you may need to set the @code{calc-gnuplot-name} variable -in your Calc init file or @file{.emacs}. You may also need to set some Lisp -variables to show Calc how to run GNUPLOT on your system; these -are described under @kbd{g D} and @kbd{g O} below. If you are -using the X window system, Calc will configure GNUPLOT for you -automatically. If you have GNUPLOT 3.0 or later and you are not using X, -Calc will configure GNUPLOT to display graphs using simple character -graphics that will work on any terminal. - -@menu -* Basic Graphics:: -* Three Dimensional Graphics:: -* Managing Curves:: -* Graphics Options:: -* Devices:: -@end menu - -@node Basic Graphics, Three Dimensional Graphics, Graphics, Graphics -@section Basic Graphics - -@noindent -@kindex g f -@pindex calc-graph-fast -The easiest graphics command is @kbd{g f} (@code{calc-graph-fast}). -This command takes two vectors of equal length from the stack. -The vector at the top of the stack represents the ``y'' values of -the various data points. The vector in the second-to-top position -represents the corresponding ``x'' values. This command runs -GNUPLOT (if it has not already been started by previous graphing -commands) and displays the set of data points. The points will -be connected by lines, and there will also be some kind of symbol -to indicate the points themselves. - -The ``x'' entry may instead be an interval form, in which case suitable -``x'' values are interpolated between the minimum and maximum values of -the interval (whether the interval is open or closed is ignored). - -The ``x'' entry may also be a number, in which case Calc uses the -sequence of ``x'' values @expr{x}, @expr{x+1}, @expr{x+2}, etc. -(Generally the number 0 or 1 would be used for @expr{x} in this case.) - -The ``y'' entry may be any formula instead of a vector. Calc effectively -uses @kbd{N} (@code{calc-eval-num}) to evaluate variables in the formula; -the result of this must be a formula in a single (unassigned) variable. -The formula is plotted with this variable taking on the various ``x'' -values. Graphs of formulas by default use lines without symbols at the -computed data points. Note that if neither ``x'' nor ``y'' is a vector, -Calc guesses at a reasonable number of data points to use. See the -@kbd{g N} command below. (The ``x'' values must be either a vector -or an interval if ``y'' is a formula.) - -@ignore -@starindex -@end ignore -@tindex xy -If ``y'' is (or evaluates to) a formula of the form -@samp{xy(@var{x}, @var{y})} then the result is a -parametric plot. The two arguments of the fictitious @code{xy} function -are used as the ``x'' and ``y'' coordinates of the curve, respectively. -In this case the ``x'' vector or interval you specified is not directly -visible in the graph. For example, if ``x'' is the interval @samp{[0..360]} -and ``y'' is the formula @samp{xy(sin(t), cos(t))}, the resulting graph -will be a circle. - -Also, ``x'' and ``y'' may each be variable names, in which case Calc -looks for suitable vectors, intervals, or formulas stored in those -variables. - -The ``x'' and ``y'' values for the data points (as pulled from the vectors, -calculated from the formulas, or interpolated from the intervals) should -be real numbers (integers, fractions, or floats). One exception to this -is that the ``y'' entry can consist of a vector of numbers combined with -error forms, in which case the points will be plotted with the -appropriate error bars. Other than this, if either the ``x'' -value or the ``y'' value of a given data point is not a real number, that -data point will be omitted from the graph. The points on either side -of the invalid point will @emph{not} be connected by a line. - -See the documentation for @kbd{g a} below for a description of the way -numeric prefix arguments affect @kbd{g f}. - -@cindex @code{PlotRejects} variable -@vindex PlotRejects -If you store an empty vector in the variable @code{PlotRejects} -(i.e., @kbd{[ ] s t PlotRejects}), Calc will append information to -this vector for every data point which was rejected because its -``x'' or ``y'' values were not real numbers. The result will be -a matrix where each row holds the curve number, data point number, -``x'' value, and ``y'' value for a rejected data point. -@xref{Evaluates-To Operator}, for a handy way to keep tabs on the -current value of @code{PlotRejects}. @xref{Operations on Variables}, -for the @kbd{s R} command which is another easy way to examine -@code{PlotRejects}. - -@kindex g c -@pindex calc-graph-clear -To clear the graphics display, type @kbd{g c} (@code{calc-graph-clear}). -If the GNUPLOT output device is an X window, the window will go away. -Effects on other kinds of output devices will vary. You don't need -to use @kbd{g c} if you don't want to---if you give another @kbd{g f} -or @kbd{g p} command later on, it will reuse the existing graphics -window if there is one. - -@node Three Dimensional Graphics, Managing Curves, Basic Graphics, Graphics -@section Three-Dimensional Graphics - -@kindex g F -@pindex calc-graph-fast-3d -The @kbd{g F} (@code{calc-graph-fast-3d}) command makes a three-dimensional -graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, -you will see a GNUPLOT error message if you try this command. - -The @kbd{g F} command takes three values from the stack, called ``x'', -``y'', and ``z'', respectively. As was the case for 2D graphs, there -are several options for these values. - -In the first case, ``x'' and ``y'' are each vectors (not necessarily of -the same length); either or both may instead be interval forms. The -``z'' value must be a matrix with the same number of rows as elements -in ``x'', and the same number of columns as elements in ``y''. The -result is a surface plot where -@texline @math{z_{ij}} -@infoline @expr{z_ij} -is the height of the point -at coordinate @expr{(x_i, y_j)} on the surface. The 3D graph will -be displayed from a certain default viewpoint; you can change this -viewpoint by adding a @samp{set view} to the @samp{*Gnuplot Commands*} -buffer as described later. See the GNUPLOT documentation for a -description of the @samp{set view} command. - -Each point in the matrix will be displayed as a dot in the graph, -and these points will be connected by a grid of lines (@dfn{isolines}). - -In the second case, ``x'', ``y'', and ``z'' are all vectors of equal -length. The resulting graph displays a 3D line instead of a surface, -where the coordinates of points along the line are successive triplets -of values from the input vectors. - -In the third case, ``x'' and ``y'' are vectors or interval forms, and -``z'' is any formula involving two variables (not counting variables -with assigned values). These variables are sorted into alphabetical -order; the first takes on values from ``x'' and the second takes on -values from ``y'' to form a matrix of results that are graphed as a -3D surface. - -@ignore -@starindex -@end ignore -@tindex xyz -If the ``z'' formula evaluates to a call to the fictitious function -@samp{xyz(@var{x}, @var{y}, @var{z})}, then the result is a -``parametric surface.'' In this case, the axes of the graph are -taken from the @var{x} and @var{y} values in these calls, and the -``x'' and ``y'' values from the input vectors or intervals are used only -to specify the range of inputs to the formula. For example, plotting -@samp{[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))} -will draw a sphere. (Since the default resolution for 3D plots is -5 steps in each of ``x'' and ``y'', this will draw a very crude -sphere. You could use the @kbd{g N} command, described below, to -increase this resolution, or specify the ``x'' and ``y'' values as -vectors with more than 5 elements. - -It is also possible to have a function in a regular @kbd{g f} plot -evaluate to an @code{xyz} call. Since @kbd{g f} plots a line, not -a surface, the result will be a 3D parametric line. For example, -@samp{[[0..720], xyz(sin(x), cos(x), x)]} will plot two turns of a -helix (a three-dimensional spiral). - -As for @kbd{g f}, each of ``x'', ``y'', and ``z'' may instead be -variables containing the relevant data. - -@node Managing Curves, Graphics Options, Three Dimensional Graphics, Graphics -@section Managing Curves - -@noindent -The @kbd{g f} command is really shorthand for the following commands: -@kbd{C-u g d g a g p}. Likewise, @w{@kbd{g F}} is shorthand for -@kbd{C-u g d g A g p}. You can gain more control over your graph -by using these commands directly. - -@kindex g a -@pindex calc-graph-add -The @kbd{g a} (@code{calc-graph-add}) command adds the ``curve'' -represented by the two values on the top of the stack to the current -graph. You can have any number of curves in the same graph. When -you give the @kbd{g p} command, all the curves will be drawn superimposed -on the same axes. - -The @kbd{g a} command (and many others that affect the current graph) -will cause a special buffer, @samp{*Gnuplot Commands*}, to be displayed -in another window. This buffer is a template of the commands that will -be sent to GNUPLOT when it is time to draw the graph. The first -@kbd{g a} command adds a @code{plot} command to this buffer. Succeeding -@kbd{g a} commands add extra curves onto that @code{plot} command. -Other graph-related commands put other GNUPLOT commands into this -buffer. In normal usage you never need to work with this buffer -directly, but you can if you wish. The only constraint is that there -must be only one @code{plot} command, and it must be the last command -in the buffer. If you want to save and later restore a complete graph -configuration, you can use regular Emacs commands to save and restore -the contents of the @samp{*Gnuplot Commands*} buffer. - -@vindex PlotData1 -@vindex PlotData2 -If the values on the stack are not variable names, @kbd{g a} will invent -variable names for them (of the form @samp{PlotData@var{n}}) and store -the values in those variables. The ``x'' and ``y'' variables are what -go into the @code{plot} command in the template. If you add a curve -that uses a certain variable and then later change that variable, you -can replot the graph without having to delete and re-add the curve. -That's because the variable name, not the vector, interval or formula -itself, is what was added by @kbd{g a}. - -A numeric prefix argument on @kbd{g a} or @kbd{g f} changes the way -stack entries are interpreted as curves. With a positive prefix -argument @expr{n}, the top @expr{n} stack entries are ``y'' values -for @expr{n} different curves which share a common ``x'' value in -the @expr{n+1}st stack entry. (Thus @kbd{g a} with no prefix -argument is equivalent to @kbd{C-u 1 g a}.) - -A prefix of zero or plain @kbd{C-u} means to take two stack entries, -``x'' and ``y'' as usual, but to interpret ``y'' as a vector of -``y'' values for several curves that share a common ``x''. - -A negative prefix argument tells Calc to read @expr{n} vectors from -the stack; each vector @expr{[x, y]} describes an independent curve. -This is the only form of @kbd{g a} that creates several curves at once -that don't have common ``x'' values. (Of course, the range of ``x'' -values covered by all the curves ought to be roughly the same if -they are to look nice on the same graph.) - -For example, to plot -@texline @math{\sin n x} -@infoline @expr{sin(n x)} -for integers @expr{n} -from 1 to 5, you could use @kbd{v x} to create a vector of integers -(@expr{n}), then @kbd{V M '} or @kbd{V M $} to map @samp{sin(n x)} -across this vector. The resulting vector of formulas is suitable -for use as the ``y'' argument to a @kbd{C-u g a} or @kbd{C-u g f} -command. - -@kindex g A -@pindex calc-graph-add-3d -The @kbd{g A} (@code{calc-graph-add-3d}) command adds a 3D curve -to the graph. It is not valid to intermix 2D and 3D curves in a -single graph. This command takes three arguments, ``x'', ``y'', -and ``z'', from the stack. With a positive prefix @expr{n}, it -takes @expr{n+2} arguments (common ``x'' and ``y'', plus @expr{n} -separate ``z''s). With a zero prefix, it takes three stack entries -but the ``z'' entry is a vector of curve values. With a negative -prefix @expr{-n}, it takes @expr{n} vectors of the form @expr{[x, y, z]}. -The @kbd{g A} command works by adding a @code{splot} (surface-plot) -command to the @samp{*Gnuplot Commands*} buffer. - -(Although @kbd{g a} adds a 2D @code{plot} command to the -@samp{*Gnuplot Commands*} buffer, Calc changes this to @code{splot} -before sending it to GNUPLOT if it notices that the data points are -evaluating to @code{xyz} calls. It will not work to mix 2D and 3D -@kbd{g a} curves in a single graph, although Calc does not currently -check for this.) - -@kindex g d -@pindex calc-graph-delete -The @kbd{g d} (@code{calc-graph-delete}) command deletes the most -recently added curve from the graph. It has no effect if there are -no curves in the graph. With a numeric prefix argument of any kind, -it deletes all of the curves from the graph. - -@kindex g H -@pindex calc-graph-hide -The @kbd{g H} (@code{calc-graph-hide}) command ``hides'' or ``unhides'' -the most recently added curve. A hidden curve will not appear in -the actual plot, but information about it such as its name and line and -point styles will be retained. - -@kindex g j -@pindex calc-graph-juggle -The @kbd{g j} (@code{calc-graph-juggle}) command moves the curve -at the end of the list (the ``most recently added curve'') to the -front of the list. The next-most-recent curve is thus exposed for -@w{@kbd{g d}} or similar commands to use. With @kbd{g j} you can work -with any curve in the graph even though curve-related commands only -affect the last curve in the list. - -@kindex g p -@pindex calc-graph-plot -The @kbd{g p} (@code{calc-graph-plot}) command uses GNUPLOT to draw -the graph described in the @samp{*Gnuplot Commands*} buffer. Any -GNUPLOT parameters which are not defined by commands in this buffer -are reset to their default values. The variables named in the @code{plot} -command are written to a temporary data file and the variable names -are then replaced by the file name in the template. The resulting -plotting commands are fed to the GNUPLOT program. See the documentation -for the GNUPLOT program for more specific information. All temporary -files are removed when Emacs or GNUPLOT exits. - -If you give a formula for ``y'', Calc will remember all the values that -it calculates for the formula so that later plots can reuse these values. -Calc throws out these saved values when you change any circumstances -that may affect the data, such as switching from Degrees to Radians -mode, or changing the value of a parameter in the formula. You can -force Calc to recompute the data from scratch by giving a negative -numeric prefix argument to @kbd{g p}. - -Calc uses a fairly rough step size when graphing formulas over intervals. -This is to ensure quick response. You can ``refine'' a plot by giving -a positive numeric prefix argument to @kbd{g p}. Calc goes through -the data points it has computed and saved from previous plots of the -function, and computes and inserts a new data point midway between -each of the existing points. You can refine a plot any number of times, -but beware that the amount of calculation involved doubles each time. - -Calc does not remember computed values for 3D graphs. This means the -numerix prefix argument, if any, to @kbd{g p} is effectively ignored if -the current graph is three-dimensional. - -@kindex g P -@pindex calc-graph-print -The @kbd{g P} (@code{calc-graph-print}) command is like @kbd{g p}, -except that it sends the output to a printer instead of to the -screen. More precisely, @kbd{g p} looks for @samp{set terminal} -or @samp{set output} commands in the @samp{*Gnuplot Commands*} buffer; -lacking these it uses the default settings. However, @kbd{g P} -ignores @samp{set terminal} and @samp{set output} commands and -uses a different set of default values. All of these values are -controlled by the @kbd{g D} and @kbd{g O} commands discussed below. -Provided everything is set up properly, @kbd{g p} will plot to -the screen unless you have specified otherwise and @kbd{g P} will -always plot to the printer. - -@node Graphics Options, Devices, Managing Curves, Graphics -@section Graphics Options - -@noindent -@kindex g g -@pindex calc-graph-grid -The @kbd{g g} (@code{calc-graph-grid}) command turns the ``grid'' -on and off. It is off by default; tick marks appear only at the -edges of the graph. With the grid turned on, dotted lines appear -across the graph at each tick mark. Note that this command only -changes the setting in @samp{*Gnuplot Commands*}; to see the effects -of the change you must give another @kbd{g p} command. - -@kindex g b -@pindex calc-graph-border -The @kbd{g b} (@code{calc-graph-border}) command turns the border -(the box that surrounds the graph) on and off. It is on by default. -This command will only work with GNUPLOT 3.0 and later versions. - -@kindex g k -@pindex calc-graph-key -The @kbd{g k} (@code{calc-graph-key}) command turns the ``key'' -on and off. The key is a chart in the corner of the graph that -shows the correspondence between curves and line styles. It is -off by default, and is only really useful if you have several -curves on the same graph. - -@kindex g N -@pindex calc-graph-num-points -The @kbd{g N} (@code{calc-graph-num-points}) command allows you -to select the number of data points in the graph. This only affects -curves where neither ``x'' nor ``y'' is specified as a vector. -Enter a blank line to revert to the default value (initially 15). -With no prefix argument, this command affects only the current graph. -With a positive prefix argument this command changes or, if you enter -a blank line, displays the default number of points used for all -graphs created by @kbd{g a} that don't specify the resolution explicitly. -With a negative prefix argument, this command changes or displays -the default value (initially 5) used for 3D graphs created by @kbd{g A}. -Note that a 3D setting of 5 means that a total of @expr{5^2 = 25} points -will be computed for the surface. - -Data values in the graph of a function are normally computed to a -precision of five digits, regardless of the current precision at the -time. This is usually more than adequate, but there are cases where -it will not be. For example, plotting @expr{1 + x} with @expr{x} in the -interval @samp{[0 ..@: 1e-6]} will round all the data points down -to 1.0! Putting the command @samp{set precision @var{n}} in the -@samp{*Gnuplot Commands*} buffer will cause the data to be computed -at precision @var{n} instead of 5. Since this is such a rare case, -there is no keystroke-based command to set the precision. - -@kindex g h -@pindex calc-graph-header -The @kbd{g h} (@code{calc-graph-header}) command sets the title -for the graph. This will show up centered above the graph. -The default title is blank (no title). - -@kindex g n -@pindex calc-graph-name -The @kbd{g n} (@code{calc-graph-name}) command sets the title of an -individual curve. Like the other curve-manipulating commands, it -affects the most recently added curve, i.e., the last curve on the -list in the @samp{*Gnuplot Commands*} buffer. To set the title of -the other curves you must first juggle them to the end of the list -with @kbd{g j}, or edit the @samp{*Gnuplot Commands*} buffer by hand. -Curve titles appear in the key; if the key is turned off they are -not used. - -@kindex g t -@kindex g T -@pindex calc-graph-title-x -@pindex calc-graph-title-y -The @kbd{g t} (@code{calc-graph-title-x}) and @kbd{g T} -(@code{calc-graph-title-y}) commands set the titles on the ``x'' -and ``y'' axes, respectively. These titles appear next to the -tick marks on the left and bottom edges of the graph, respectively. -Calc does not have commands to control the tick marks themselves, -but you can edit them into the @samp{*Gnuplot Commands*} buffer if -you wish. See the GNUPLOT documentation for details. - -@kindex g r -@kindex g R -@pindex calc-graph-range-x -@pindex calc-graph-range-y -The @kbd{g r} (@code{calc-graph-range-x}) and @kbd{g R} -(@code{calc-graph-range-y}) commands set the range of values on the -``x'' and ``y'' axes, respectively. You are prompted to enter a -suitable range. This should be either a pair of numbers of the -form, @samp{@var{min}:@var{max}}, or a blank line to revert to the -default behavior of setting the range based on the range of values -in the data, or @samp{$} to take the range from the top of the stack. -Ranges on the stack can be represented as either interval forms or -vectors: @samp{[@var{min} ..@: @var{max}]} or @samp{[@var{min}, @var{max}]}. - -@kindex g l -@kindex g L -@pindex calc-graph-log-x -@pindex calc-graph-log-y -The @kbd{g l} (@code{calc-graph-log-x}) and @kbd{g L} (@code{calc-graph-log-y}) -commands allow you to set either or both of the axes of the graph to -be logarithmic instead of linear. - -@kindex g C-l -@kindex g C-r -@kindex g C-t -@pindex calc-graph-log-z -@pindex calc-graph-range-z -@pindex calc-graph-title-z -For 3D plots, @kbd{g C-t}, @kbd{g C-r}, and @kbd{g C-l} (those are -letters with the Control key held down) are the corresponding commands -for the ``z'' axis. - -@kindex g z -@kindex g Z -@pindex calc-graph-zero-x -@pindex calc-graph-zero-y -The @kbd{g z} (@code{calc-graph-zero-x}) and @kbd{g Z} -(@code{calc-graph-zero-y}) commands control whether a dotted line is -drawn to indicate the ``x'' and/or ``y'' zero axes. (These are the same -dotted lines that would be drawn there anyway if you used @kbd{g g} to -turn the ``grid'' feature on.) Zero-axis lines are on by default, and -may be turned off only in GNUPLOT 3.0 and later versions. They are -not available for 3D plots. - -@kindex g s -@pindex calc-graph-line-style -The @kbd{g s} (@code{calc-graph-line-style}) command turns the connecting -lines on or off for the most recently added curve, and optionally selects -the style of lines to be used for that curve. Plain @kbd{g s} simply -toggles the lines on and off. With a numeric prefix argument, @kbd{g s} -turns lines on and sets a particular line style. Line style numbers -start at one and their meanings vary depending on the output device. -GNUPLOT guarantees that there will be at least six different line styles -available for any device. - -@kindex g S -@pindex calc-graph-point-style -The @kbd{g S} (@code{calc-graph-point-style}) command similarly turns -the symbols at the data points on or off, or sets the point style. -If you turn both lines and points off, the data points will show as -tiny dots. If the ``y'' values being plotted contain error forms and -the connecting lines are turned off, then this command will also turn -the error bars on or off. - -@cindex @code{LineStyles} variable -@cindex @code{PointStyles} variable -@vindex LineStyles -@vindex PointStyles -Another way to specify curve styles is with the @code{LineStyles} and -@code{PointStyles} variables. These variables initially have no stored -values, but if you store a vector of integers in one of these variables, -the @kbd{g a} and @kbd{g f} commands will use those style numbers -instead of the defaults for new curves that are added to the graph. -An entry should be a positive integer for a specific style, or 0 to let -the style be chosen automatically, or @mathit{-1} to turn off lines or points -altogether. If there are more curves than elements in the vector, the -last few curves will continue to have the default styles. Of course, -you can later use @kbd{g s} and @kbd{g S} to change any of these styles. - -For example, @kbd{'[2 -1 3] @key{RET} s t LineStyles} causes the first curve -to have lines in style number 2, the second curve to have no connecting -lines, and the third curve to have lines in style 3. Point styles will -still be assigned automatically, but you could store another vector in -@code{PointStyles} to define them, too. - -@node Devices, , Graphics Options, Graphics -@section Graphical Devices - -@noindent -@kindex g D -@pindex calc-graph-device -The @kbd{g D} (@code{calc-graph-device}) command sets the device name -(or ``terminal name'' in GNUPLOT lingo) to be used by @kbd{g p} commands -on this graph. It does not affect the permanent default device name. -If you enter a blank name, the device name reverts to the default. -Enter @samp{?} to see a list of supported devices. - -With a positive numeric prefix argument, @kbd{g D} instead sets -the default device name, used by all plots in the future which do -not override it with a plain @kbd{g D} command. If you enter a -blank line this command shows you the current default. The special -name @code{default} signifies that Calc should choose @code{x11} if -the X window system is in use (as indicated by the presence of a -@code{DISPLAY} environment variable), or otherwise @code{dumb} under -GNUPLOT 3.0 and later, or @code{postscript} under GNUPLOT 2.0. -This is the initial default value. - -The @code{dumb} device is an interface to ``dumb terminals,'' i.e., -terminals with no special graphics facilities. It writes a crude -picture of the graph composed of characters like @code{-} and @code{|} -to a buffer called @samp{*Gnuplot Trail*}, which Calc then displays. -The graph is made the same size as the Emacs screen, which on most -dumb terminals will be -@texline @math{80\times24} -@infoline 80x24 -characters. The graph is displayed in -an Emacs ``recursive edit''; type @kbd{q} or @kbd{C-c C-c} to exit -the recursive edit and return to Calc. Note that the @code{dumb} -device is present only in GNUPLOT 3.0 and later versions. - -The word @code{dumb} may be followed by two numbers separated by -spaces. These are the desired width and height of the graph in -characters. Also, the device name @code{big} is like @code{dumb} -but creates a graph four times the width and height of the Emacs -screen. You will then have to scroll around to view the entire -graph. In the @samp{*Gnuplot Trail*} buffer, @key{SPC}, @key{DEL}, -@kbd{<}, and @kbd{>} are defined to scroll by one screenful in each -of the four directions. - -With a negative numeric prefix argument, @kbd{g D} sets or displays -the device name used by @kbd{g P} (@code{calc-graph-print}). This -is initially @code{postscript}. If you don't have a PostScript -printer, you may decide once again to use @code{dumb} to create a -plot on any text-only printer. - -@kindex g O -@pindex calc-graph-output -The @kbd{g O} (@code{calc-graph-output}) command sets the name of -the output file used by GNUPLOT. For some devices, notably @code{x11}, -there is no output file and this information is not used. Many other -``devices'' are really file formats like @code{postscript}; in these -cases the output in the desired format goes into the file you name -with @kbd{g O}. Type @kbd{g O stdout @key{RET}} to set GNUPLOT to write -to its standard output stream, i.e., to @samp{*Gnuplot Trail*}. -This is the default setting. - -Another special output name is @code{tty}, which means that GNUPLOT -is going to write graphics commands directly to its standard output, -which you wish Emacs to pass through to your terminal. Tektronix -graphics terminals, among other devices, operate this way. Calc does -this by telling GNUPLOT to write to a temporary file, then running a -sub-shell executing the command @samp{cat tempfile >/dev/tty}. On -typical Unix systems, this will copy the temporary file directly to -the terminal, bypassing Emacs entirely. You will have to type @kbd{C-l} -to Emacs afterwards to refresh the screen. - -Once again, @kbd{g O} with a positive or negative prefix argument -sets the default or printer output file names, respectively. In each -case you can specify @code{auto}, which causes Calc to invent a temporary -file name for each @kbd{g p} (or @kbd{g P}) command. This temporary file -will be deleted once it has been displayed or printed. If the output file -name is not @code{auto}, the file is not automatically deleted. - -The default and printer devices and output files can be saved -permanently by the @kbd{m m} (@code{calc-save-modes}) command. The -default number of data points (see @kbd{g N}) and the X geometry -(see @kbd{g X}) are also saved. Other graph information is @emph{not} -saved; you can save a graph's configuration simply by saving the contents -of the @samp{*Gnuplot Commands*} buffer. - -@vindex calc-gnuplot-plot-command -@vindex calc-gnuplot-default-device -@vindex calc-gnuplot-default-output -@vindex calc-gnuplot-print-command -@vindex calc-gnuplot-print-device -@vindex calc-gnuplot-print-output -You may wish to configure the default and -printer devices and output files for the whole system. The relevant -Lisp variables are @code{calc-gnuplot-default-device} and @code{-output}, -and @code{calc-gnuplot-print-device} and @code{-output}. The output -file names must be either strings as described above, or Lisp -expressions which are evaluated on the fly to get the output file names. - -Other important Lisp variables are @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command}, which give the system commands to -display or print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. These variables are customizable -(@pxref{Customizing Calc}). - -@kindex g x -@pindex calc-graph-display -The @kbd{g x} (@code{calc-graph-display}) command lets you specify -on which X window system display your graphs should be drawn. Enter -a blank line to see the current display name. This command has no -effect unless the current device is @code{x11}. - -@kindex g X -@pindex calc-graph-geometry -The @kbd{g X} (@code{calc-graph-geometry}) command is a similar -command for specifying the position and size of the X window. -The normal value is @code{default}, which generally means your -window manager will let you place the window interactively. -Entering @samp{800x500+0+0} would create an 800-by-500 pixel -window in the upper-left corner of the screen. - -The buffer called @samp{*Gnuplot Trail*} holds a transcript of the -session with GNUPLOT. This shows the commands Calc has ``typed'' to -GNUPLOT and the responses it has received. Calc tries to notice when an -error message has appeared here and display the buffer for you when -this happens. You can check this buffer yourself if you suspect -something has gone wrong. - -@kindex g C -@pindex calc-graph-command -The @kbd{g C} (@code{calc-graph-command}) command prompts you to -enter any line of text, then simply sends that line to the current -GNUPLOT process. The @samp{*Gnuplot Trail*} buffer looks deceptively -like a Shell buffer but you can't type commands in it yourself. -Instead, you must use @kbd{g C} for this purpose. - -@kindex g v -@kindex g V -@pindex calc-graph-view-commands -@pindex calc-graph-view-trail -The @kbd{g v} (@code{calc-graph-view-commands}) and @kbd{g V} -(@code{calc-graph-view-trail}) commands display the @samp{*Gnuplot Commands*} -and @samp{*Gnuplot Trail*} buffers, respectively, in another window. -This happens automatically when Calc thinks there is something you -will want to see in either of these buffers. If you type @kbd{g v} -or @kbd{g V} when the relevant buffer is already displayed, the -buffer is hidden again. - -One reason to use @kbd{g v} is to add your own commands to the -@samp{*Gnuplot Commands*} buffer. Press @kbd{g v}, then use -@kbd{C-x o} to switch into that window. For example, GNUPLOT has -@samp{set label} and @samp{set arrow} commands that allow you to -annotate your plots. Since Calc doesn't understand these commands, -you have to add them to the @samp{*Gnuplot Commands*} buffer -yourself, then use @w{@kbd{g p}} to replot using these new commands. Note -that your commands must appear @emph{before} the @code{plot} command. -To get help on any GNUPLOT feature, type, e.g., @kbd{g C help set label}. -You may have to type @kbd{g C @key{RET}} a few times to clear the -``press return for more'' or ``subtopic of @dots{}'' requests. -Note that Calc always sends commands (like @samp{set nolabel}) to -reset all plotting parameters to the defaults before each plot, so -to delete a label all you need to do is delete the @samp{set label} -line you added (or comment it out with @samp{#}) and then replot -with @kbd{g p}. - -@kindex g q -@pindex calc-graph-quit -You can use @kbd{g q} (@code{calc-graph-quit}) to kill the GNUPLOT -process that is running. The next graphing command you give will -start a fresh GNUPLOT process. The word @samp{Graph} appears in -the Calc window's mode line whenever a GNUPLOT process is currently -running. The GNUPLOT process is automatically killed when you -exit Emacs if you haven't killed it manually by then. - -@kindex g K -@pindex calc-graph-kill -The @kbd{g K} (@code{calc-graph-kill}) command is like @kbd{g q} -except that it also views the @samp{*Gnuplot Trail*} buffer so that -you can see the process being killed. This is better if you are -killing GNUPLOT because you think it has gotten stuck. - -@node Kill and Yank, Keypad Mode, Graphics, Top -@chapter Kill and Yank Functions - -@noindent -The commands in this chapter move information between the Calculator and -other Emacs editing buffers. - -In many cases Embedded mode is an easier and more natural way to -work with Calc from a regular editing buffer. @xref{Embedded Mode}. - -@menu -* Killing From Stack:: -* Yanking Into Stack:: -* Saving Into Registers:: -* Inserting From Registers:: -* Grabbing From Buffers:: -* Yanking Into Buffers:: -* X Cut and Paste:: -@end menu - -@node Killing From Stack, Yanking Into Stack, Kill and Yank, Kill and Yank -@section Killing from the Stack - -@noindent -@kindex C-k -@pindex calc-kill -@kindex M-k -@pindex calc-copy-as-kill -@kindex C-w -@pindex calc-kill-region -@kindex M-w -@pindex calc-copy-region-as-kill -@kindex M-C-w -@cindex Kill ring -@dfn{Kill} commands are Emacs commands that insert text into the ``kill -ring,'' from which it can later be ``yanked'' by a @kbd{C-y} command. -Three common kill commands in normal Emacs are @kbd{C-k}, which kills -one line, @kbd{C-w}, which kills the region between mark and point, and -@kbd{M-w}, which puts the region into the kill ring without actually -deleting it. All of these commands work in the Calculator, too, -although in the Calculator they operate on whole stack entries, so they -``round up'' the specified region to encompass full lines. (To copy -only parts of lines, the @kbd{M-C-w} command in the Calculator will copy -the region to the kill ring without any ``rounding up'', just like the -@kbd{M-w} command in normal Emacs.) Also, @kbd{M-k} has been provided -to complete the set; it puts the current line into the kill ring without -deleting anything. - -The kill commands are unusual in that they pay attention to the location -of the cursor in the Calculator buffer. If the cursor is on or below -the bottom line, the kill commands operate on the top of the stack. -Otherwise, they operate on whatever stack element the cursor is on. The -text is copied into the kill ring exactly as it appears on the screen, -including line numbers if they are enabled. - -A numeric prefix argument to @kbd{C-k} or @kbd{M-k} affects the number -of lines killed. A positive argument kills the current line and @expr{n-1} -lines below it. A negative argument kills the @expr{-n} lines above the -current line. Again this mirrors the behavior of the standard Emacs -@kbd{C-k} command. Although a whole line is always deleted, @kbd{C-k} -with no argument copies only the number itself into the kill ring, whereas -@kbd{C-k} with a prefix argument of 1 copies the number with its trailing -newline. - -@node Yanking Into Stack, Saving Into Registers, Killing From Stack, Kill and Yank -@section Yanking into the Stack - -@noindent -@kindex C-y -@pindex calc-yank -The @kbd{C-y} command yanks the most recently killed text back into the -Calculator. It pushes this value onto the top of the stack regardless of -the cursor position. In general it re-parses the killed text as a number -or formula (or a list of these separated by commas or newlines). However if -the thing being yanked is something that was just killed from the Calculator -itself, its full internal structure is yanked. For example, if you have -set the floating-point display mode to show only four significant digits, -then killing and re-yanking 3.14159 (which displays as 3.142) will yank the -full 3.14159, even though yanking it into any other buffer would yank the -number in its displayed form, 3.142. (Since the default display modes -show all objects to their full precision, this feature normally makes no -difference.) - -@node Saving Into Registers, Inserting From Registers, Yanking Into Stack, Kill and Yank -@section Saving into Registers - -@noindent -@kindex r s -@pindex calc-copy-to-register -@pindex calc-prepend-to-register -@pindex calc-append-to-register -@cindex Registers -An alternative to killing and yanking stack entries is using -registers in Calc. Saving stack entries in registers is like -saving text in normal Emacs registers; although, like Calc's kill -commands, register commands always operate on whole stack -entries. - -Registers in Calc are places to store stack entries for later use; -each register is indexed by a single character. To store the current -region (rounded up, of course, to include full stack entries) into a -register, use the command @kbd{r s} (@code{calc-copy-to-register}). -You will then be prompted for a register to use, the next character -you type will be the index for the register. To store the region in -register @var{r}, the full command will be @kbd{r s @var{r}}. With an -argument, @kbd{C-u r s @var{r}}, the region being copied to the -register will be deleted from the Calc buffer. - -It is possible to add additional stack entries to a register. The -command @kbd{M-x calc-append-to-register} will prompt for a register, -then add the stack entries in the region to the end of the register -contents. The command @kbd{M-x calc-prepend-to-register} will -similarly prompt for a register and add the stack entries in the -region to the beginning of the register contents. Both commands take -@kbd{C-u} arguments, which will cause the region to be deleted after being -added to the register. - -@node Inserting From Registers, Grabbing From Buffers, Saving Into Registers, Kill and Yank -@section Inserting from Registers -@noindent -@kindex r i -@pindex calc-insert-register -The command @kbd{r i} (@code{calc-insert-register}) will prompt for a -register, then insert the contents of that register into the -Calculator. If the contents of the register were placed there from -within Calc, then the full internal structure of the contents will be -inserted into the Calculator, otherwise whatever text is in the -register is reparsed and then inserted into the Calculator. - -@node Grabbing From Buffers, Yanking Into Buffers, Inserting From Registers, Kill and Yank -@section Grabbing from Other Buffers - -@noindent -@kindex C-x * g -@pindex calc-grab-region -The @kbd{C-x * g} (@code{calc-grab-region}) command takes the text between -point and mark in the current buffer and attempts to parse it as a -vector of values. Basically, it wraps the text in vector brackets -@samp{[ ]} unless the text already is enclosed in vector brackets, -then reads the text as if it were an algebraic entry. The contents -of the vector may be numbers, formulas, or any other Calc objects. -If the @kbd{C-x * g} command works successfully, it does an automatic -@kbd{C-x * c} to enter the Calculator buffer. - -A numeric prefix argument grabs the specified number of lines around -point, ignoring the mark. A positive prefix grabs from point to the -@expr{n}th following newline (so that @kbd{M-1 C-x * g} grabs from point -to the end of the current line); a negative prefix grabs from point -back to the @expr{n+1}st preceding newline. In these cases the text -that is grabbed is exactly the same as the text that @kbd{C-k} would -delete given that prefix argument. - -A prefix of zero grabs the current line; point may be anywhere on the -line. - -A plain @kbd{C-u} prefix interprets the region between point and mark -as a single number or formula rather than a vector. For example, -@kbd{C-x * g} on the text @samp{2 a b} produces the vector of three -values @samp{[2, a, b]}, but @kbd{C-u C-x * g} on the same region -reads a formula which is a product of three things: @samp{2 a b}. -(The text @samp{a + b}, on the other hand, will be grabbed as a -vector of one element by plain @kbd{C-x * g} because the interpretation -@samp{[a, +, b]} would be a syntax error.) - -If a different language has been specified (@pxref{Language Modes}), -the grabbed text will be interpreted according to that language. - -@kindex C-x * r -@pindex calc-grab-rectangle -The @kbd{C-x * r} (@code{calc-grab-rectangle}) command takes the text between -point and mark and attempts to parse it as a matrix. If point and mark -are both in the leftmost column, the lines in between are parsed in their -entirety. Otherwise, point and mark define the corners of a rectangle -whose contents are parsed. - -Each line of the grabbed area becomes a row of the matrix. The result -will actually be a vector of vectors, which Calc will treat as a matrix -only if every row contains the same number of values. - -If a line contains a portion surrounded by square brackets (or curly -braces), that portion is interpreted as a vector which becomes a row -of the matrix. Any text surrounding the bracketed portion on the line -is ignored. - -Otherwise, the entire line is interpreted as a row vector as if it -were surrounded by square brackets. Leading line numbers (in the -format used in the Calc stack buffer) are ignored. If you wish to -force this interpretation (even if the line contains bracketed -portions), give a negative numeric prefix argument to the -@kbd{C-x * r} command. - -If you give a numeric prefix argument of zero or plain @kbd{C-u}, each -line is instead interpreted as a single formula which is converted into -a one-element vector. Thus the result of @kbd{C-u C-x * r} will be a -one-column matrix. For example, suppose one line of the data is the -expression @samp{2 a}. A plain @w{@kbd{C-x * r}} will interpret this as -@samp{[2 a]}, which in turn is read as a two-element vector that forms -one row of the matrix. But a @kbd{C-u C-x * r} will interpret this row -as @samp{[2*a]}. - -If you give a positive numeric prefix argument @var{n}, then each line -will be split up into columns of width @var{n}; each column is parsed -separately as a matrix element. If a line contained -@w{@samp{2 +/- 3 4 +/- 5}}, then grabbing with a prefix argument of 8 -would correctly split the line into two error forms. - -@xref{Matrix Functions}, to see how to pull the matrix apart into its -constituent rows and columns. (If it is a -@texline @math{1\times1} -@infoline 1x1 -matrix, just hit @kbd{v u} (@code{calc-unpack}) twice.) - -@kindex C-x * : -@kindex C-x * _ -@pindex calc-grab-sum-across -@pindex calc-grab-sum-down -@cindex Summing rows and columns of data -The @kbd{C-x * :} (@code{calc-grab-sum-down}) command is a handy way to -grab a rectangle of data and sum its columns. It is equivalent to -typing @kbd{C-x * r}, followed by @kbd{V R : +} (the vector reduction -command that sums the columns of a matrix; @pxref{Reducing}). The -result of the command will be a vector of numbers, one for each column -in the input data. The @kbd{C-x * _} (@code{calc-grab-sum-across}) command -similarly grabs a rectangle and sums its rows by executing @w{@kbd{V R _ +}}. - -As well as being more convenient, @kbd{C-x * :} and @kbd{C-x * _} are also -much faster because they don't actually place the grabbed vector on -the stack. In a @kbd{C-x * r V R : +} sequence, formatting the vector -for display on the stack takes a large fraction of the total time -(unless you have planned ahead and used @kbd{v .} and @kbd{t .} modes). - -For example, suppose we have a column of numbers in a file which we -wish to sum. Go to one corner of the column and press @kbd{C-@@} to -set the mark; go to the other corner and type @kbd{C-x * :}. Since there -is only one column, the result will be a vector of one number, the sum. -(You can type @kbd{v u} to unpack this vector into a plain number if -you want to do further arithmetic with it.) - -To compute the product of the column of numbers, we would have to do -it ``by hand'' since there's no special grab-and-multiply command. -Use @kbd{C-x * r} to grab the column of numbers into the calculator in -the form of a column matrix. The statistics command @kbd{u *} is a -handy way to find the product of a vector or matrix of numbers. -@xref{Statistical Operations}. Another approach would be to use -an explicit column reduction command, @kbd{V R : *}. - -@node Yanking Into Buffers, X Cut and Paste, Grabbing From Buffers, Kill and Yank -@section Yanking into Other Buffers - -@noindent -@kindex y -@pindex calc-copy-to-buffer -The plain @kbd{y} (@code{calc-copy-to-buffer}) command inserts the number -at the top of the stack into the most recently used normal editing buffer. -(More specifically, this is the most recently used buffer which is displayed -in a window and whose name does not begin with @samp{*}. If there is no -such buffer, this is the most recently used buffer except for Calculator -and Calc Trail buffers.) The number is inserted exactly as it appears and -without a newline. (If line-numbering is enabled, the line number is -normally not included.) The number is @emph{not} removed from the stack. - -With a prefix argument, @kbd{y} inserts several numbers, one per line. -A positive argument inserts the specified number of values from the top -of the stack. A negative argument inserts the @expr{n}th value from the -top of the stack. An argument of zero inserts the entire stack. Note -that @kbd{y} with an argument of 1 is slightly different from @kbd{y} -with no argument; the former always copies full lines, whereas the -latter strips off the trailing newline. - -With a lone @kbd{C-u} as a prefix argument, @kbd{y} @emph{replaces} the -region in the other buffer with the yanked text, then quits the -Calculator, leaving you in that buffer. A typical use would be to use -@kbd{C-x * g} to read a region of data into the Calculator, operate on the -data to produce a new matrix, then type @kbd{C-u y} to replace the -original data with the new data. One might wish to alter the matrix -display style (@pxref{Vector and Matrix Formats}) or change the current -display language (@pxref{Language Modes}) before doing this. Also, note -that this command replaces a linear region of text (as grabbed by -@kbd{C-x * g}), not a rectangle (as grabbed by @kbd{C-x * r}). - -If the editing buffer is in overwrite (as opposed to insert) mode, -and the @kbd{C-u} prefix was not used, then the yanked number will -overwrite the characters following point rather than being inserted -before those characters. The usual conventions of overwrite mode -are observed; for example, characters will be inserted at the end of -a line rather than overflowing onto the next line. Yanking a multi-line -object such as a matrix in overwrite mode overwrites the next @var{n} -lines in the buffer, lengthening or shortening each line as necessary. -Finally, if the thing being yanked is a simple integer or floating-point -number (like @samp{-1.2345e-3}) and the characters following point also -make up such a number, then Calc will replace that number with the new -number, lengthening or shortening as necessary. The concept of -``overwrite mode'' has thus been generalized from overwriting characters -to overwriting one complete number with another. - -@kindex C-x * y -The @kbd{C-x * y} key sequence is equivalent to @kbd{y} except that -it can be typed anywhere, not just in Calc. This provides an easy -way to guarantee that Calc knows which editing buffer you want to use! - -@node X Cut and Paste, , Yanking Into Buffers, Kill and Yank -@section X Cut and Paste - -@noindent -If you are using Emacs with the X window system, there is an easier -way to move small amounts of data into and out of the calculator: -Use the mouse-oriented cut and paste facilities of X. - -The default bindings for a three-button mouse cause the left button -to move the Emacs cursor to the given place, the right button to -select the text between the cursor and the clicked location, and -the middle button to yank the selection into the buffer at the -clicked location. So, if you have a Calc window and an editing -window on your Emacs screen, you can use left-click/right-click -to select a number, vector, or formula from one window, then -middle-click to paste that value into the other window. When you -paste text into the Calc window, Calc interprets it as an algebraic -entry. It doesn't matter where you click in the Calc window; the -new value is always pushed onto the top of the stack. - -The @code{xterm} program that is typically used for general-purpose -shell windows in X interprets the mouse buttons in the same way. -So you can use the mouse to move data between Calc and any other -Unix program. One nice feature of @code{xterm} is that a double -left-click selects one word, and a triple left-click selects a -whole line. So you can usually transfer a single number into Calc -just by double-clicking on it in the shell, then middle-clicking -in the Calc window. - -@node Keypad Mode, Embedded Mode, Kill and Yank, Top -@chapter Keypad Mode - -@noindent -@kindex C-x * k -@pindex calc-keypad -The @kbd{C-x * k} (@code{calc-keypad}) command starts the Calculator -and displays a picture of a calculator-style keypad. If you are using -the X window system, you can click on any of the ``keys'' in the -keypad using the left mouse button to operate the calculator. -The original window remains the selected window; in Keypad mode -you can type in your file while simultaneously performing -calculations with the mouse. - -@pindex full-calc-keypad -If you have used @kbd{C-x * b} first, @kbd{C-x * k} instead invokes -the @code{full-calc-keypad} command, which takes over the whole -Emacs screen and displays the keypad, the Calc stack, and the Calc -trail all at once. This mode would normally be used when running -Calc standalone (@pxref{Standalone Operation}). - -If you aren't using the X window system, you must switch into -the @samp{*Calc Keypad*} window, place the cursor on the desired -``key,'' and type @key{SPC} or @key{RET}. If you think this -is easier than using Calc normally, go right ahead. - -Calc commands are more or less the same in Keypad mode. Certain -keypad keys differ slightly from the corresponding normal Calc -keystrokes; all such deviations are described below. - -Keypad mode includes many more commands than will fit on the keypad -at once. Click the right mouse button [@code{calc-keypad-menu}] -to switch to the next menu. The bottom five rows of the keypad -stay the same; the top three rows change to a new set of commands. -To return to earlier menus, click the middle mouse button -[@code{calc-keypad-menu-back}] or simply advance through the menus -until you wrap around. Typing @key{TAB} inside the keypad window -is equivalent to clicking the right mouse button there. - -You can always click the @key{EXEC} button and type any normal -Calc key sequence. This is equivalent to switching into the -Calc buffer, typing the keys, then switching back to your -original buffer. - -@menu -* Keypad Main Menu:: -* Keypad Functions Menu:: -* Keypad Binary Menu:: -* Keypad Vectors Menu:: -* Keypad Modes Menu:: -@end menu - -@node Keypad Main Menu, Keypad Functions Menu, Keypad Mode, Keypad Mode -@section Main Menu - -@smallexample -@group -|----+----+--Calc---+----+----1 -|FLR |CEIL|RND |TRNC|CLN2|FLT | -|----+----+----+----+----+----| -| LN |EXP | |ABS |IDIV|MOD | -|----+----+----+----+----+----| -|SIN |COS |TAN |SQRT|y^x |1/x | -|----+----+----+----+----+----| -| ENTER |+/- |EEX |UNDO| <- | -|-----+---+-+--+--+-+---++----| -| INV | 7 | 8 | 9 | / | -|-----+-----+-----+-----+-----| -| HYP | 4 | 5 | 6 | * | -|-----+-----+-----+-----+-----| -|EXEC | 1 | 2 | 3 | - | -|-----+-----+-----+-----+-----| -| OFF | 0 | . | PI | + | -|-----+-----+-----+-----+-----+ -@end group -@end smallexample - -@noindent -This is the menu that appears the first time you start Keypad mode. -It will show up in a vertical window on the right side of your screen. -Above this menu is the traditional Calc stack display. On a 24-line -screen you will be able to see the top three stack entries. - -The ten digit keys, decimal point, and @key{EEX} key are used for -entering numbers in the obvious way. @key{EEX} begins entry of an -exponent in scientific notation. Just as with regular Calc, the -number is pushed onto the stack as soon as you press @key{ENTER} -or any other function key. - -The @key{+/-} key corresponds to normal Calc's @kbd{n} key. During -numeric entry it changes the sign of the number or of the exponent. -At other times it changes the sign of the number on the top of the -stack. - -The @key{INV} and @key{HYP} keys modify other keys. As well as -having the effects described elsewhere in this manual, Keypad mode -defines several other ``inverse'' operations. These are described -below and in the following sections. - -The @key{ENTER} key finishes the current numeric entry, or otherwise -duplicates the top entry on the stack. - -The @key{UNDO} key undoes the most recent Calc operation. -@kbd{INV UNDO} is the ``redo'' command, and @kbd{HYP UNDO} is -``last arguments'' (@kbd{M-@key{RET}}). - -The @key{<-} key acts as a ``backspace'' during numeric entry. -At other times it removes the top stack entry. @kbd{INV <-} -clears the entire stack. @kbd{HYP <-} takes an integer from -the stack, then removes that many additional stack elements. - -The @key{EXEC} key prompts you to enter any keystroke sequence -that would normally work in Calc mode. This can include a -numeric prefix if you wish. It is also possible simply to -switch into the Calc window and type commands in it; there is -nothing ``magic'' about this window when Keypad mode is active. - -The other keys in this display perform their obvious calculator -functions. @key{CLN2} rounds the top-of-stack by temporarily -reducing the precision by 2 digits. @key{FLT} converts an -integer or fraction on the top of the stack to floating-point. - -The @key{INV} and @key{HYP} keys combined with several of these keys -give you access to some common functions even if the appropriate menu -is not displayed. Obviously you don't need to learn these keys -unless you find yourself wasting time switching among the menus. - -@table @kbd -@item INV +/- -is the same as @key{1/x}. -@item INV + -is the same as @key{SQRT}. -@item INV - -is the same as @key{CONJ}. -@item INV * -is the same as @key{y^x}. -@item INV / -is the same as @key{INV y^x} (the @expr{x}th root of @expr{y}). -@item HYP/INV 1 -are the same as @key{SIN} / @kbd{INV SIN}. -@item HYP/INV 2 -are the same as @key{COS} / @kbd{INV COS}. -@item HYP/INV 3 -are the same as @key{TAN} / @kbd{INV TAN}. -@item INV/HYP 4 -are the same as @key{LN} / @kbd{HYP LN}. -@item INV/HYP 5 -are the same as @key{EXP} / @kbd{HYP EXP}. -@item INV 6 -is the same as @key{ABS}. -@item INV 7 -is the same as @key{RND} (@code{calc-round}). -@item INV 8 -is the same as @key{CLN2}. -@item INV 9 -is the same as @key{FLT} (@code{calc-float}). -@item INV 0 -is the same as @key{IMAG}. -@item INV . -is the same as @key{PREC}. -@item INV ENTER -is the same as @key{SWAP}. -@item HYP ENTER -is the same as @key{RLL3}. -@item INV HYP ENTER -is the same as @key{OVER}. -@item HYP +/- -packs the top two stack entries as an error form. -@item HYP EEX -packs the top two stack entries as a modulo form. -@item INV EEX -creates an interval form; this removes an integer which is one -of 0 @samp{[]}, 1 @samp{[)}, 2 @samp{(]} or 3 @samp{()}, followed -by the two limits of the interval. -@end table - -The @kbd{OFF} key turns Calc off; typing @kbd{C-x * k} or @kbd{C-x * *} -again has the same effect. This is analogous to typing @kbd{q} or -hitting @kbd{C-x * c} again in the normal calculator. If Calc is -running standalone (the @code{full-calc-keypad} command appeared in the -command line that started Emacs), then @kbd{OFF} is replaced with -@kbd{EXIT}; clicking on this actually exits Emacs itself. - -@node Keypad Functions Menu, Keypad Binary Menu, Keypad Main Menu, Keypad Mode -@section Functions Menu - -@smallexample -@group -|----+----+----+----+----+----2 -|IGAM|BETA|IBET|ERF |BESJ|BESY| -|----+----+----+----+----+----| -|IMAG|CONJ| RE |ATN2|RAND|RAGN| -|----+----+----+----+----+----| -|GCD |FACT|DFCT|BNOM|PERM|NXTP| -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -This menu provides various operations from the @kbd{f} and @kbd{k} -prefix keys. - -@key{IMAG} multiplies the number on the stack by the imaginary -number @expr{i = (0, 1)}. - -@key{RE} extracts the real part a complex number. @kbd{INV RE} -extracts the imaginary part. - -@key{RAND} takes a number from the top of the stack and computes -a random number greater than or equal to zero but less than that -number. (@xref{Random Numbers}.) @key{RAGN} is the ``random -again'' command; it computes another random number using the -same limit as last time. - -@key{INV GCD} computes the LCM (least common multiple) function. - -@key{INV FACT} is the gamma function. -@texline @math{\Gamma(x) = (x-1)!}. -@infoline @expr{gamma(x) = (x-1)!}. - -@key{PERM} is the number-of-permutations function, which is on the -@kbd{H k c} key in normal Calc. - -@key{NXTP} finds the next prime after a number. @kbd{INV NXTP} -finds the previous prime. - -@node Keypad Binary Menu, Keypad Vectors Menu, Keypad Functions Menu, Keypad Mode -@section Binary Menu - -@smallexample -@group -|----+----+----+----+----+----3 -|AND | OR |XOR |NOT |LSH |RSH | -|----+----+----+----+----+----| -|DEC |HEX |OCT |BIN |WSIZ|ARSH| -|----+----+----+----+----+----| -| A | B | C | D | E | F | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu perform operations on binary integers. -Note that both logical and arithmetic right-shifts are provided. -@key{INV LSH} rotates one bit to the left. - -The ``difference'' function (normally on @kbd{b d}) is on @key{INV AND}. -The ``clip'' function (normally on @w{@kbd{b c}}) is on @key{INV NOT}. - -The @key{DEC}, @key{HEX}, @key{OCT}, and @key{BIN} keys select the -current radix for display and entry of numbers: Decimal, hexadecimal, -octal, or binary. The six letter keys @key{A} through @key{F} are used -for entering hexadecimal numbers. - -The @key{WSIZ} key displays the current word size for binary operations -and allows you to enter a new word size. You can respond to the prompt -using either the keyboard or the digits and @key{ENTER} from the keypad. -The initial word size is 32 bits. - -@node Keypad Vectors Menu, Keypad Modes Menu, Keypad Binary Menu, Keypad Mode -@section Vectors Menu - -@smallexample -@group -|----+----+----+----+----+----4 -|SUM |PROD|MAX |MAP*|MAP^|MAP$| -|----+----+----+----+----+----| -|MINV|MDET|MTRN|IDNT|CRSS|"x" | -|----+----+----+----+----+----| -|PACK|UNPK|INDX|BLD |LEN |... | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu operate on vectors and matrices. - -@key{PACK} removes an integer @var{n} from the top of the stack; -the next @var{n} stack elements are removed and packed into a vector, -which is replaced onto the stack. Thus the sequence -@kbd{1 ENTER 3 ENTER 5 ENTER 3 PACK} enters the vector -@samp{[1, 3, 5]} onto the stack. To enter a matrix, build each row -on the stack as a vector, then use a final @key{PACK} to collect the -rows into a matrix. - -@key{UNPK} unpacks the vector on the stack, pushing each of its -components separately. - -@key{INDX} removes an integer @var{n}, then builds a vector of -integers from 1 to @var{n}. @kbd{INV INDX} takes three numbers -from the stack: The vector size @var{n}, the starting number, -and the increment. @kbd{BLD} takes an integer @var{n} and any -value @var{x} and builds a vector of @var{n} copies of @var{x}. - -@key{IDNT} removes an integer @var{n}, then builds an @var{n}-by-@var{n} -identity matrix. - -@key{LEN} replaces a vector by its length, an integer. - -@key{...} turns on or off ``abbreviated'' display mode for large vectors. - -@key{MINV}, @key{MDET}, @key{MTRN}, and @key{CROSS} are the matrix -inverse, determinant, and transpose, and vector cross product. - -@key{SUM} replaces a vector by the sum of its elements. It is -equivalent to @kbd{u +} in normal Calc (@pxref{Statistical Operations}). -@key{PROD} computes the product of the elements of a vector, and -@key{MAX} computes the maximum of all the elements of a vector. - -@key{INV SUM} computes the alternating sum of the first element -minus the second, plus the third, minus the fourth, and so on. -@key{INV MAX} computes the minimum of the vector elements. - -@key{HYP SUM} computes the mean of the vector elements. -@key{HYP PROD} computes the sample standard deviation. -@key{HYP MAX} computes the median. - -@key{MAP*} multiplies two vectors elementwise. It is equivalent -to the @kbd{V M *} command. @key{MAP^} computes powers elementwise. -The arguments must be vectors of equal length, or one must be a vector -and the other must be a plain number. For example, @kbd{2 MAP^} squares -all the elements of a vector. - -@key{MAP$} maps the formula on the top of the stack across the -vector in the second-to-top position. If the formula contains -several variables, Calc takes that many vectors starting at the -second-to-top position and matches them to the variables in -alphabetical order. The result is a vector of the same size as -the input vectors, whose elements are the formula evaluated with -the variables set to the various sets of numbers in those vectors. -For example, you could simulate @key{MAP^} using @key{MAP$} with -the formula @samp{x^y}. - -The @kbd{"x"} key pushes the variable name @expr{x} onto the -stack. To build the formula @expr{x^2 + 6}, you would use the -key sequence @kbd{"x" 2 y^x 6 +}. This formula would then be -suitable for use with the @key{MAP$} key described above. -With @key{INV}, @key{HYP}, or @key{INV} and @key{HYP}, the -@kbd{"x"} key pushes the variable names @expr{y}, @expr{z}, and -@expr{t}, respectively. - -@node Keypad Modes Menu, , Keypad Vectors Menu, Keypad Mode -@section Modes Menu - -@smallexample -@group -|----+----+----+----+----+----5 -|FLT |FIX |SCI |ENG |GRP | | -|----+----+----+----+----+----| -|RAD |DEG |FRAC|POLR|SYMB|PREC| -|----+----+----+----+----+----| -|SWAP|RLL3|RLL4|OVER|STO |RCL | -|----+----+----+----+----+----| -@end group -@end smallexample - -@noindent -The keys in this menu manipulate modes, variables, and the stack. - -The @key{FLT}, @key{FIX}, @key{SCI}, and @key{ENG} keys select -floating-point, fixed-point, scientific, or engineering notation. -@key{FIX} displays two digits after the decimal by default; the -others display full precision. With the @key{INV} prefix, these -keys pop a number-of-digits argument from the stack. - -The @key{GRP} key turns grouping of digits with commas on or off. -@kbd{INV GRP} enables grouping to the right of the decimal point as -well as to the left. - -The @key{RAD} and @key{DEG} keys switch between radians and degrees -for trigonometric functions. - -The @key{FRAC} key turns Fraction mode on or off. This affects -whether commands like @kbd{/} with integer arguments produce -fractional or floating-point results. - -The @key{POLR} key turns Polar mode on or off, determining whether -polar or rectangular complex numbers are used by default. - -The @key{SYMB} key turns Symbolic mode on or off, in which -operations that would produce inexact floating-point results -are left unevaluated as algebraic formulas. - -The @key{PREC} key selects the current precision. Answer with -the keyboard or with the keypad digit and @key{ENTER} keys. - -The @key{SWAP} key exchanges the top two stack elements. -The @key{RLL3} key rotates the top three stack elements upwards. -The @key{RLL4} key rotates the top four stack elements upwards. -The @key{OVER} key duplicates the second-to-top stack element. - -The @key{STO} and @key{RCL} keys are analogous to @kbd{s t} and -@kbd{s r} in regular Calc. @xref{Store and Recall}. Click the -@key{STO} or @key{RCL} key, then one of the ten digits. (Named -variables are not available in Keypad mode.) You can also use, -for example, @kbd{STO + 3} to add to register 3. - -@node Embedded Mode, Programming, Keypad Mode, Top -@chapter Embedded Mode - -@noindent -Embedded mode in Calc provides an alternative to copying numbers -and formulas back and forth between editing buffers and the Calc -stack. In Embedded mode, your editing buffer becomes temporarily -linked to the stack and this copying is taken care of automatically. - -@menu -* Basic Embedded Mode:: -* More About Embedded Mode:: -* Assignments in Embedded Mode:: -* Mode Settings in Embedded Mode:: -* Customizing Embedded Mode:: -@end menu - -@node Basic Embedded Mode, More About Embedded Mode, Embedded Mode, Embedded Mode -@section Basic Embedded Mode - -@noindent -@kindex C-x * e -@pindex calc-embedded -To enter Embedded mode, position the Emacs point (cursor) on a -formula in any buffer and press @kbd{C-x * e} (@code{calc-embedded}). -Note that @kbd{C-x * e} is not to be used in the Calc stack buffer -like most Calc commands, but rather in regular editing buffers that -are visiting your own files. - -Calc will try to guess an appropriate language based on the major mode -of the editing buffer. (@xref{Language Modes}.) If the current buffer is -in @code{latex-mode}, for example, Calc will set its language to La@TeX{}. -Similarly, Calc will use @TeX{} language for @code{tex-mode}, -@code{plain-tex-mode} and @code{context-mode}, C language for -@code{c-mode} and @code{c++-mode}, FORTRAN language for -@code{fortran-mode} and @code{f90-mode}, Pascal for @code{pascal-mode}, -and eqn for @code{nroff-mode} (@pxref{Customizing Calc}). -These can be overridden with Calc's mode -changing commands (@pxref{Mode Settings in Embedded Mode}). If no -suitable language is available, Calc will continue with its current language. - -Calc normally scans backward and forward in the buffer for the -nearest opening and closing @dfn{formula delimiters}. The simplest -delimiters are blank lines. Other delimiters that Embedded mode -understands are: - -@enumerate -@item -The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -@xref{Customizing Embedded Mode}, to see how to make Calc recognize -your own favorite delimiters. Delimiters like @samp{$ $} can appear -on their own separate lines or in-line with the formula. - -If you give a positive or negative numeric prefix argument, Calc -instead uses the current point as one end of the formula, and includes -that many lines forward or backward (respectively, including the current -line). Explicit delimiters are not necessary in this case. - -With a prefix argument of zero, Calc uses the current region (delimited -by point and mark) instead of formula delimiters. With a prefix -argument of @kbd{C-u} only, Calc uses the current line as the formula. - -@kindex C-x * w -@pindex calc-embedded-word -The @kbd{C-x * w} (@code{calc-embedded-word}) command will start Embedded -mode on the current ``word''; in this case Calc will scan for the first -non-numeric character (i.e., the first character that is not a digit, -sign, decimal point, or upper- or lower-case @samp{e}) forward and -backward to delimit the formula. - -When you enable Embedded mode for a formula, Calc reads the text -between the delimiters and tries to interpret it as a Calc formula. -Calc can generally identify @TeX{} formulas and -Big-style formulas even if the language mode is wrong. If Calc -can't make sense of the formula, it beeps and refuses to enter -Embedded mode. But if the current language is wrong, Calc can -sometimes parse the formula successfully (but incorrectly); -for example, the C expression @samp{atan(a[1])} can be parsed -in Normal language mode, but the @code{atan} won't correspond to -the built-in @code{arctan} function, and the @samp{a[1]} will be -interpreted as @samp{a} times the vector @samp{[1]}! - -If you press @kbd{C-x * e} or @kbd{C-x * w} to activate an embedded -formula which is blank, say with the cursor on the space between -the two delimiters @samp{$ $}, Calc will immediately prompt for -an algebraic entry. - -Only one formula in one buffer can be enabled at a time. If you -move to another area of the current buffer and give Calc commands, -Calc turns Embedded mode off for the old formula and then tries -to restart Embedded mode at the new position. Other buffers are -not affected by Embedded mode. - -When Embedded mode begins, Calc pushes the current formula onto -the stack. No Calc stack window is created; however, Calc copies -the top-of-stack position into the original buffer at all times. -You can create a Calc window by hand with @kbd{C-x * o} if you -find you need to see the entire stack. - -For example, typing @kbd{C-x * e} while somewhere in the formula -@samp{n>2} in the following line enables Embedded mode on that -inequality: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n>2$. -@end example - -@noindent -The formula @expr{n>2} will be pushed onto the Calc stack, and -the top of stack will be copied back into the editing buffer. -This means that spaces will appear around the @samp{>} symbol -to match Calc's usual display style: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $n > 2$. -@end example - -@noindent -No spaces have appeared around the @samp{+} sign because it's -in a different formula, one which we have not yet touched with -Embedded mode. - -Now that Embedded mode is enabled, keys you type in this buffer -are interpreted as Calc commands. At this point we might use -the ``commute'' command @kbd{j C} to reverse the inequality. -This is a selection-based command for which we first need to -move the cursor onto the operator (@samp{>} in this case) that -needs to be commuted. - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $2 < n$. -@end example - -The @kbd{C-x * o} command is a useful way to open a Calc window -without actually selecting that window. Giving this command -verifies that @samp{2 < n} is also on the Calc stack. Typing -@kbd{17 @key{RET}} would produce: - -@example -We define $F_n = F_(n-1)+F_(n-2)$ for all $17$. -@end example - -@noindent -with @samp{2 < n} and @samp{17} on the stack; typing @key{TAB} -at this point will exchange the two stack values and restore -@samp{2 < n} to the embedded formula. Even though you can't -normally see the stack in Embedded mode, it is still there and -it still operates in the same way. But, as with old-fashioned -RPN calculators, you can only see the value at the top of the -stack at any given time (unless you use @kbd{C-x * o}). - -Typing @kbd{C-x * e} again turns Embedded mode off. The Calc -window reveals that the formula @w{@samp{2 < n}} is automatically -removed from the stack, but the @samp{17} is not. Entering -Embedded mode always pushes one thing onto the stack, and -leaving Embedded mode always removes one thing. Anything else -that happens on the stack is entirely your business as far as -Embedded mode is concerned. - -If you press @kbd{C-x * e} in the wrong place by accident, it is -possible that Calc will be able to parse the nearby text as a -formula and will mangle that text in an attempt to redisplay it -``properly'' in the current language mode. If this happens, -press @kbd{C-x * e} again to exit Embedded mode, then give the -regular Emacs ``undo'' command (@kbd{C-_} or @kbd{C-x u}) to put -the text back the way it was before Calc edited it. Note that Calc's -own Undo command (typed before you turn Embedded mode back off) -will not do you any good, because as far as Calc is concerned -you haven't done anything with this formula yet. - -@node More About Embedded Mode, Assignments in Embedded Mode, Basic Embedded Mode, Embedded Mode -@section More About Embedded Mode - -@noindent -When Embedded mode ``activates'' a formula, i.e., when it examines -the formula for the first time since the buffer was created or -loaded, Calc tries to sense the language in which the formula was -written. If the formula contains any La@TeX{}-like @samp{\} sequences, -it is parsed (i.e., read) in La@TeX{} mode. If the formula appears to -be written in multi-line Big mode, it is parsed in Big mode. Otherwise, -it is parsed according to the current language mode. - -Note that Calc does not change the current language mode according -the formula it reads in. Even though it can read a La@TeX{} formula when -not in La@TeX{} mode, it will immediately rewrite this formula using -whatever language mode is in effect. - -@tex -\bigskip -@end tex - -@kindex d p -@pindex calc-show-plain -Calc's parser is unable to read certain kinds of formulas. For -example, with @kbd{v ]} (@code{calc-matrix-brackets}) you can -specify matrix display styles which the parser is unable to -recognize as matrices. The @kbd{d p} (@code{calc-show-plain}) -command turns on a mode in which a ``plain'' version of a -formula is placed in front of the fully-formatted version. -When Calc reads a formula that has such a plain version in -front, it reads the plain version and ignores the formatted -version. - -Plain formulas are preceded and followed by @samp{%%%} signs -by default. This notation has the advantage that the @samp{%} -character begins a comment in @TeX{} and La@TeX{}, so if your formula is -embedded in a @TeX{} or La@TeX{} document its plain version will be -invisible in the final printed copy. Certain major modes have different -delimiters to ensure that the ``plain'' version will be -in a comment for those modes, also. -See @ref{Customizing Embedded Mode} to see how to change the ``plain'' -formula delimiters. - -There are several notations which Calc's parser for ``big'' -formatted formulas can't yet recognize. In particular, it can't -read the large symbols for @code{sum}, @code{prod}, and @code{integ}, -and it can't handle @samp{=>} with the righthand argument omitted. -Also, Calc won't recognize special formats you have defined with -the @kbd{Z C} command (@pxref{User-Defined Compositions}). In -these cases it is important to use ``plain'' mode to make sure -Calc will be able to read your formula later. - -Another example where ``plain'' mode is important is if you have -specified a float mode with few digits of precision. Normally -any digits that are computed but not displayed will simply be -lost when you save and re-load your embedded buffer, but ``plain'' -mode allows you to make sure that the complete number is present -in the file as well as the rounded-down number. - -@tex -\bigskip -@end tex - -Embedded buffers remember active formulas for as long as they -exist in Emacs memory. Suppose you have an embedded formula -which is @cpi{} to the normal 12 decimal places, and then -type @w{@kbd{C-u 5 d n}} to display only five decimal places. -If you then type @kbd{d n}, all 12 places reappear because the -full number is still there on the Calc stack. More surprisingly, -even if you exit Embedded mode and later re-enter it for that -formula, typing @kbd{d n} will restore all 12 places because -each buffer remembers all its active formulas. However, if you -save the buffer in a file and reload it in a new Emacs session, -all non-displayed digits will have been lost unless you used -``plain'' mode. - -@tex -\bigskip -@end tex - -In some applications of Embedded mode, you will want to have a -sequence of copies of a formula that show its evolution as you -work on it. For example, you might want to have a sequence -like this in your file (elaborating here on the example from -the ``Getting Started'' chapter): - -@smallexample -The derivative of - - ln(ln(x)) - -is - - @r{(the derivative of }ln(ln(x))@r{)} - -whose value at x = 2 is - - @r{(the value)} - -and at x = 3 is - - @r{(the value)} -@end smallexample - -@kindex C-x * d -@pindex calc-embedded-duplicate -The @kbd{C-x * d} (@code{calc-embedded-duplicate}) command is a -handy way to make sequences like this. If you type @kbd{C-x * d}, -the formula under the cursor (which may or may not have Embedded -mode enabled for it at the time) is copied immediately below and -Embedded mode is then enabled for that copy. - -For this example, you would start with just - -@smallexample -The derivative of - - ln(ln(x)) -@end smallexample - -@noindent -and press @kbd{C-x * d} with the cursor on this formula. The result -is - -@smallexample -The derivative of - - ln(ln(x)) - - - ln(ln(x)) -@end smallexample - -@noindent -with the second copy of the formula enabled in Embedded mode. -You can now press @kbd{a d x @key{RET}} to take the derivative, and -@kbd{C-x * d C-x * d} to make two more copies of the derivative. -To complete the computations, type @kbd{3 s l x @key{RET}} to evaluate -the last formula, then move up to the second-to-last formula -and type @kbd{2 s l x @key{RET}}. - -Finally, you would want to press @kbd{C-x * e} to exit Embedded -mode, then go up and insert the necessary text in between the -various formulas and numbers. - -@tex -\bigskip -@end tex - -@kindex C-x * f -@kindex C-x * ' -@pindex calc-embedded-new-formula -The @kbd{C-x * f} (@code{calc-embedded-new-formula}) command -creates a new embedded formula at the current point. It inserts -some default delimiters, which are usually just blank lines, -and then does an algebraic entry to get the formula (which is -then enabled for Embedded mode). This is just shorthand for -typing the delimiters yourself, positioning the cursor between -the new delimiters, and pressing @kbd{C-x * e}. The key sequence -@kbd{C-x * '} is equivalent to @kbd{C-x * f}. - -@kindex C-x * n -@kindex C-x * p -@pindex calc-embedded-next -@pindex calc-embedded-previous -The @kbd{C-x * n} (@code{calc-embedded-next}) and @kbd{C-x * p} -(@code{calc-embedded-previous}) commands move the cursor to the -next or previous active embedded formula in the buffer. They -can take positive or negative prefix arguments to move by several -formulas. Note that these commands do not actually examine the -text of the buffer looking for formulas; they only see formulas -which have previously been activated in Embedded mode. In fact, -@kbd{C-x * n} and @kbd{C-x * p} are a useful way to tell which -embedded formulas are currently active. Also, note that these -commands do not enable Embedded mode on the next or previous -formula, they just move the cursor. - -@kindex C-x * ` -@pindex calc-embedded-edit -The @kbd{C-x * `} (@code{calc-embedded-edit}) command edits the -embedded formula at the current point as if by @kbd{`} (@code{calc-edit}). -Embedded mode does not have to be enabled for this to work. Press -@kbd{C-c C-c} to finish the edit, or @kbd{C-x k} to cancel. - -@node Assignments in Embedded Mode, Mode Settings in Embedded Mode, More About Embedded Mode, Embedded Mode -@section Assignments in Embedded Mode - -@noindent -The @samp{:=} (assignment) and @samp{=>} (``evaluates-to'') operators -are especially useful in Embedded mode. They allow you to make -a definition in one formula, then refer to that definition in -other formulas embedded in the same buffer. - -An embedded formula which is an assignment to a variable, as in - -@example -foo := 5 -@end example - -@noindent -records @expr{5} as the stored value of @code{foo} for the -purposes of Embedded mode operations in the current buffer. It -does @emph{not} actually store @expr{5} as the ``global'' value -of @code{foo}, however. Regular Calc operations, and Embedded -formulas in other buffers, will not see this assignment. - -One way to use this assigned value is simply to create an -Embedded formula elsewhere that refers to @code{foo}, and to press -@kbd{=} in that formula. However, this permanently replaces the -@code{foo} in the formula with its current value. More interesting -is to use @samp{=>} elsewhere: - -@example -foo + 7 => 12 -@end example - -@xref{Evaluates-To Operator}, for a general discussion of @samp{=>}. - -If you move back and change the assignment to @code{foo}, any -@samp{=>} formulas which refer to it are automatically updated. - -@example -foo := 17 - -foo + 7 => 24 -@end example - -The obvious question then is, @emph{how} can one easily change the -assignment to @code{foo}? If you simply select the formula in -Embedded mode and type 17, the assignment itself will be replaced -by the 17. The effect on the other formula will be that the -variable @code{foo} becomes unassigned: - -@example -17 - -foo + 7 => foo + 7 -@end example - -The right thing to do is first to use a selection command (@kbd{j 2} -will do the trick) to select the righthand side of the assignment. -Then, @kbd{17 @key{TAB} @key{DEL}} will swap the 17 into place (@pxref{Selecting -Subformulas}, to see how this works). - -@kindex C-x * j -@pindex calc-embedded-select -The @kbd{C-x * j} (@code{calc-embedded-select}) command provides an -easy way to operate on assignments. It is just like @kbd{C-x * e}, -except that if the enabled formula is an assignment, it uses -@kbd{j 2} to select the righthand side. If the enabled formula -is an evaluates-to, it uses @kbd{j 1} to select the lefthand side. -A formula can also be a combination of both: - -@example -bar := foo + 3 => 20 -@end example - -@noindent -in which case @kbd{C-x * j} will select the middle part (@samp{foo + 3}). - -The formula is automatically deselected when you leave Embedded -mode. - -@kindex C-x * u -@pindex calc-embedded-update-formula -Another way to change the assignment to @code{foo} would simply be -to edit the number using regular Emacs editing rather than Embedded -mode. Then, we have to find a way to get Embedded mode to notice -the change. The @kbd{C-x * u} (@code{calc-embedded-update-formula}) -command is a convenient way to do this. - -@example -foo := 6 - -foo + 7 => 13 -@end example - -Pressing @kbd{C-x * u} is much like pressing @kbd{C-x * e = C-x * e}, that -is, temporarily enabling Embedded mode for the formula under the -cursor and then evaluating it with @kbd{=}. But @kbd{C-x * u} does -not actually use @kbd{C-x * e}, and in fact another formula somewhere -else can be enabled in Embedded mode while you use @kbd{C-x * u} and -that formula will not be disturbed. - -With a numeric prefix argument, @kbd{C-x * u} updates all active -@samp{=>} formulas in the buffer. Formulas which have not yet -been activated in Embedded mode, and formulas which do not have -@samp{=>} as their top-level operator, are not affected by this. -(This is useful only if you have used @kbd{m C}; see below.) - -With a plain @kbd{C-u} prefix, @kbd{C-u C-x * u} updates only in the -region between mark and point rather than in the whole buffer. - -@kbd{C-x * u} is also a handy way to activate a formula, such as an -@samp{=>} formula that has freshly been typed in or loaded from a -file. - -@kindex C-x * a -@pindex calc-embedded-activate -The @kbd{C-x * a} (@code{calc-embedded-activate}) command scans -through the current buffer and activates all embedded formulas -that contain @samp{:=} or @samp{=>} symbols. This does not mean -that Embedded mode is actually turned on, but only that the -formulas' positions are registered with Embedded mode so that -the @samp{=>} values can be properly updated as assignments are -changed. - -It is a good idea to type @kbd{C-x * a} right after loading a file -that uses embedded @samp{=>} operators. Emacs includes a nifty -``buffer-local variables'' feature that you can use to do this -automatically. The idea is to place near the end of your file -a few lines that look like this: - -@example ---- Local Variables: --- ---- eval:(calc-embedded-activate) --- ---- End: --- -@end example - -@noindent -where the leading and trailing @samp{---} can be replaced by -any suitable strings (which must be the same on all three lines) -or omitted altogether; in a @TeX{} or La@TeX{} file, @samp{%} would be a good -leading string and no trailing string would be necessary. In a -C program, @samp{/*} and @samp{*/} would be good leading and -trailing strings. - -When Emacs loads a file into memory, it checks for a Local Variables -section like this one at the end of the file. If it finds this -section, it does the specified things (in this case, running -@kbd{C-x * a} automatically) before editing of the file begins. -The Local Variables section must be within 3000 characters of the -end of the file for Emacs to find it, and it must be in the last -page of the file if the file has any page separators. -@xref{File Variables, , Local Variables in Files, emacs, the -Emacs manual}. - -Note that @kbd{C-x * a} does not update the formulas it finds. -To do this, type, say, @kbd{M-1 C-x * u} after @w{@kbd{C-x * a}}. -Generally this should not be a problem, though, because the -formulas will have been up-to-date already when the file was -saved. - -Normally, @kbd{C-x * a} activates all the formulas it finds, but -any previous active formulas remain active as well. With a -positive numeric prefix argument, @kbd{C-x * a} first deactivates -all current active formulas, then actives the ones it finds in -its scan of the buffer. With a negative prefix argument, -@kbd{C-x * a} simply deactivates all formulas. - -Embedded mode has two symbols, @samp{Active} and @samp{~Active}, -which it puts next to the major mode name in a buffer's mode line. -It puts @samp{Active} if it has reason to believe that all -formulas in the buffer are active, because you have typed @kbd{C-x * a} -and Calc has not since had to deactivate any formulas (which can -happen if Calc goes to update an @samp{=>} formula somewhere because -a variable changed, and finds that the formula is no longer there -due to some kind of editing outside of Embedded mode). Calc puts -@samp{~Active} in the mode line if some, but probably not all, -formulas in the buffer are active. This happens if you activate -a few formulas one at a time but never use @kbd{C-x * a}, or if you -used @kbd{C-x * a} but then Calc had to deactivate a formula -because it lost track of it. If neither of these symbols appears -in the mode line, no embedded formulas are active in the buffer -(e.g., before Embedded mode has been used, or after a @kbd{M-- C-x * a}). - -Embedded formulas can refer to assignments both before and after them -in the buffer. If there are several assignments to a variable, the -nearest preceding assignment is used if there is one, otherwise the -following assignment is used. - -@example -x => 1 - -x := 1 - -x => 1 - -x := 2 - -x => 2 -@end example - -As well as simple variables, you can also assign to subscript -expressions of the form @samp{@var{var}_@var{number}} (as in -@code{x_0}), or @samp{@var{var}_@var{var}} (as in @code{x_max}). -Assignments to other kinds of objects can be represented by Calc, -but the automatic linkage between assignments and references works -only for plain variables and these two kinds of subscript expressions. - -If there are no assignments to a given variable, the global -stored value for the variable is used (@pxref{Storing Variables}), -or, if no value is stored, the variable is left in symbolic form. -Note that global stored values will be lost when the file is saved -and loaded in a later Emacs session, unless you have used the -@kbd{s p} (@code{calc-permanent-variable}) command to save them; -@pxref{Operations on Variables}. - -The @kbd{m C} (@code{calc-auto-recompute}) command turns automatic -recomputation of @samp{=>} forms on and off. If you turn automatic -recomputation off, you will have to use @kbd{C-x * u} to update these -formulas manually after an assignment has been changed. If you -plan to change several assignments at once, it may be more efficient -to type @kbd{m C}, change all the assignments, then use @kbd{M-1 C-x * u} -to update the entire buffer afterwards. The @kbd{m C} command also -controls @samp{=>} formulas on the stack; @pxref{Evaluates-To -Operator}. When you turn automatic recomputation back on, the -stack will be updated but the Embedded buffer will not; you must -use @kbd{C-x * u} to update the buffer by hand. - -@node Mode Settings in Embedded Mode, Customizing Embedded Mode, Assignments in Embedded Mode, Embedded Mode -@section Mode Settings in Embedded Mode - -@kindex m e -@pindex calc-embedded-preserve-modes -@noindent -The mode settings can be changed while Calc is in embedded mode, but -by default they will revert to their original values when embedded mode -is ended. However, the modes saved when the mode-recording mode is -@code{Save} (see below) and the modes in effect when the @kbd{m e} -(@code{calc-embedded-preserve-modes}) command is given -will be preserved when embedded mode is ended. - -Embedded mode has a rather complicated mechanism for handling mode -settings in Embedded formulas. It is possible to put annotations -in the file that specify mode settings either global to the entire -file or local to a particular formula or formulas. In the latter -case, different modes can be specified for use when a formula -is the enabled Embedded mode formula. - -When you give any mode-setting command, like @kbd{m f} (for Fraction -mode) or @kbd{d s} (for scientific notation), Embedded mode adds -a line like the following one to the file just before the opening -delimiter of the formula. - -@example -% [calc-mode: fractions: t] -% [calc-mode: float-format: (sci 0)] -@end example - -When Calc interprets an embedded formula, it scans the text before -the formula for mode-setting annotations like these and sets the -Calc buffer to match these modes. Modes not explicitly described -in the file are not changed. Calc scans all the way to the top of -the file, or up to a line of the form - -@example -% [calc-defaults] -@end example - -@noindent -which you can insert at strategic places in the file if this backward -scan is getting too slow, or just to provide a barrier between one -``zone'' of mode settings and another. - -If the file contains several annotations for the same mode, the -closest one before the formula is used. Annotations after the -formula are never used (except for global annotations, described -below). - -The scan does not look for the leading @samp{% }, only for the -square brackets and the text they enclose. In fact, the leading -characters are different for different major modes. You can edit the -mode annotations to a style that works better in context if you wish. -@xref{Customizing Embedded Mode}, to see how to change the style -that Calc uses when it generates the annotations. You can write -mode annotations into the file yourself if you know the syntax; -the easiest way to find the syntax for a given mode is to let -Calc write the annotation for it once and see what it does. - -If you give a mode-changing command for a mode that already has -a suitable annotation just above the current formula, Calc will -modify that annotation rather than generating a new, conflicting -one. - -Mode annotations have three parts, separated by colons. (Spaces -after the colons are optional.) The first identifies the kind -of mode setting, the second is a name for the mode itself, and -the third is the value in the form of a Lisp symbol, number, -or list. Annotations with unrecognizable text in the first or -second parts are ignored. The third part is not checked to make -sure the value is of a valid type or range; if you write an -annotation by hand, be sure to give a proper value or results -will be unpredictable. Mode-setting annotations are case-sensitive. - -While Embedded mode is enabled, the word @code{Local} appears in -the mode line. This is to show that mode setting commands generate -annotations that are ``local'' to the current formula or set of -formulas. The @kbd{m R} (@code{calc-mode-record-mode}) command -causes Calc to generate different kinds of annotations. Pressing -@kbd{m R} repeatedly cycles through the possible modes. - -@code{LocEdit} and @code{LocPerm} modes generate annotations -that look like this, respectively: - -@example -% [calc-edit-mode: float-format: (sci 0)] -% [calc-perm-mode: float-format: (sci 5)] -@end example - -The first kind of annotation will be used only while a formula -is enabled in Embedded mode. The second kind will be used only -when the formula is @emph{not} enabled. (Whether the formula -is ``active'' or not, i.e., whether Calc has seen this formula -yet, is not relevant here.) - -@code{Global} mode generates an annotation like this at the end -of the file: - -@example -% [calc-global-mode: fractions t] -@end example - -Global mode annotations affect all formulas throughout the file, -and may appear anywhere in the file. This allows you to tuck your -mode annotations somewhere out of the way, say, on a new page of -the file, as long as those mode settings are suitable for all -formulas in the file. - -Enabling a formula with @kbd{C-x * e} causes a fresh scan for local -mode annotations; you will have to use this after adding annotations -above a formula by hand to get the formula to notice them. Updating -a formula with @kbd{C-x * u} will also re-scan the local modes, but -global modes are only re-scanned by @kbd{C-x * a}. - -Another way that modes can get out of date is if you add a local -mode annotation to a formula that has another formula after it. -In this example, we have used the @kbd{d s} command while the -first of the two embedded formulas is active. But the second -formula has not changed its style to match, even though by the -rules of reading annotations the @samp{(sci 0)} applies to it, too. - -@example -% [calc-mode: float-format: (sci 0)] -1.23e2 - -456. -@end example - -We would have to go down to the other formula and press @kbd{C-x * u} -on it in order to get it to notice the new annotation. - -Two more mode-recording modes selectable by @kbd{m R} are available -which are also available outside of Embedded mode. -(@pxref{General Mode Commands}.) They are @code{Save}, in which mode -settings are recorded permanently in your Calc init file (the file given -by the variable @code{calc-settings-file}, typically @file{~/.calc.el}) -rather than by annotating the current document, and no-recording -mode (where there is no symbol like @code{Save} or @code{Local} in -the mode line), in which mode-changing commands do not leave any -annotations at all. - -When Embedded mode is not enabled, mode-recording modes except -for @code{Save} have no effect. - -@node Customizing Embedded Mode, , Mode Settings in Embedded Mode, Embedded Mode -@section Customizing Embedded Mode - -@noindent -You can modify Embedded mode's behavior by setting various Lisp -variables described here. These variables are customizable -(@pxref{Customizing Calc}), or you can use @kbd{M-x set-variable} -or @kbd{M-x edit-options} to adjust a variable on the fly. -(Another possibility would be to use a file-local variable annotation at -the end of the file; -@pxref{File Variables, , Local Variables in Files, emacs, the Emacs manual}.) -Many of the variables given mentioned here can be set to depend on the -major mode of the editing buffer (@pxref{Customizing Calc}). - -@vindex calc-embedded-open-formula -The @code{calc-embedded-open-formula} variable holds a regular -expression for the opening delimiter of a formula. @xref{Regexp Search, -, Regular Expression Search, emacs, the Emacs manual}, to see -how regular expressions work. Basically, a regular expression is a -pattern that Calc can search for. A regular expression that considers -blank lines, @samp{$}, and @samp{$$} to be opening delimiters is -@code{"\\`\\|^\n\\|\\$\\$?"}. Just in case the meaning of this -regular expression is not completely plain, let's go through it -in detail. - -The surrounding @samp{" "} marks quote the text between them as a -Lisp string. If you left them off, @code{set-variable} or -@code{edit-options} would try to read the regular expression as a -Lisp program. - -The most obvious property of this regular expression is that it -contains indecently many backslashes. There are actually two levels -of backslash usage going on here. First, when Lisp reads a quoted -string, all pairs of characters beginning with a backslash are -interpreted as special characters. Here, @code{\n} changes to a -new-line character, and @code{\\} changes to a single backslash. -So the actual regular expression seen by Calc is -@samp{\`\|^ @r{(newline)} \|\$\$?}. - -Regular expressions also consider pairs beginning with backslash -to have special meanings. Sometimes the backslash is used to quote -a character that otherwise would have a special meaning in a regular -expression, like @samp{$}, which normally means ``end-of-line,'' -or @samp{?}, which means that the preceding item is optional. So -@samp{\$\$?} matches either one or two dollar signs. - -The other codes in this regular expression are @samp{^}, which matches -``beginning-of-line,'' @samp{\|}, which means ``or,'' and @samp{\`}, -which matches ``beginning-of-buffer.'' So the whole pattern means -that a formula begins at the beginning of the buffer, or on a newline -that occurs at the beginning of a line (i.e., a blank line), or at -one or two dollar signs. - -The default value of @code{calc-embedded-open-formula} looks just -like this example, with several more alternatives added on to -recognize various other common kinds of delimiters. - -By the way, the reason to use @samp{^\n} rather than @samp{^$} -or @samp{\n\n}, which also would appear to match blank lines, -is that the former expression actually ``consumes'' only one -newline character as @emph{part of} the delimiter, whereas the -latter expressions consume zero or two newlines, respectively. -The former choice gives the most natural behavior when Calc -must operate on a whole formula including its delimiters. - -See the Emacs manual for complete details on regular expressions. -But just for your convenience, here is a list of all characters -which must be quoted with backslash (like @samp{\$}) to avoid -some special interpretation: @samp{. * + ? [ ] ^ $ \}. (Note -the backslash in this list; for example, to match @samp{\[} you -must use @code{"\\\\\\["}. An exercise for the reader is to -account for each of these six backslashes!) - -@vindex calc-embedded-close-formula -The @code{calc-embedded-close-formula} variable holds a regular -expression for the closing delimiter of a formula. A closing -regular expression to match the above example would be -@code{"\\'\\|\n$\\|\\$\\$?"}. This is almost the same as the -other one, except it now uses @samp{\'} (``end-of-buffer'') and -@samp{\n$} (newline occurring at end of line, yet another way -of describing a blank line that is more appropriate for this -case). - -@vindex calc-embedded-word-regexp -The @code{calc-embedded-word-regexp} variable holds a regular expression -used to define an expression to look for (a ``word'') when you type -@kbd{C-x * w} to enable Embedded mode. - -@vindex calc-embedded-open-plain -The @code{calc-embedded-open-plain} variable is a string which -begins a ``plain'' formula written in front of the formatted -formula when @kbd{d p} mode is turned on. Note that this is an -actual string, not a regular expression, because Calc must be able -to write this string into a buffer as well as to recognize it. -The default string is @code{"%%% "} (note the trailing space), but may -be different for certain major modes. - -@vindex calc-embedded-close-plain -The @code{calc-embedded-close-plain} variable is a string which -ends a ``plain'' formula. The default is @code{" %%%\n"}, but may be -different for different major modes. Without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -@vindex calc-embedded-open-new-formula -The @code{calc-embedded-open-new-formula} variable is a string -which is inserted at the front of a new formula when you type -@kbd{C-x * f}. Its default value is @code{"\n\n"}. If this -string begins with a newline character and the @kbd{C-x * f} is -typed at the beginning of a line, @kbd{C-x * f} will skip this -first newline to avoid introducing unnecessary blank lines in -the file. - -@vindex calc-embedded-close-new-formula -The @code{calc-embedded-close-new-formula} variable is the corresponding -string which is inserted at the end of a new formula. Its default -value is also @code{"\n\n"}. The final newline is omitted by -@w{@kbd{C-x * f}} if typed at the end of a line. (It follows that if -@kbd{C-x * f} is typed on a blank line, both a leading opening -newline and a trailing closing newline are omitted.) - -@vindex calc-embedded-announce-formula -The @code{calc-embedded-announce-formula} variable is a regular -expression which is sure to be followed by an embedded formula. -The @kbd{C-x * a} command searches for this pattern as well as for -@samp{=>} and @samp{:=} operators. Note that @kbd{C-x * a} will -not activate just anything surrounded by formula delimiters; after -all, blank lines are considered formula delimiters by default! -But if your language includes a delimiter which can only occur -actually in front of a formula, you can take advantage of it here. -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, but may be -different for different major modes. -This pattern will check for @samp{%Embed} followed by any number of -lines beginning with @samp{%} and a space. This last is important to -make Calc consider mode annotations part of the pattern, so that the -formula's opening delimiter really is sure to follow the pattern. - -@vindex calc-embedded-open-mode -The @code{calc-embedded-open-mode} variable is a string (not a -regular expression) which should precede a mode annotation. -Calc never scans for this string; Calc always looks for the -annotation itself. But this is the string that is inserted before -the opening bracket when Calc adds an annotation on its own. -The default is @code{"% "}, but may be different for different major -modes. - -@vindex calc-embedded-close-mode -The @code{calc-embedded-close-mode} variable is a string which -follows a mode annotation written by Calc. Its default value -is simply a newline, @code{"\n"}, but may be different for different -major modes. If you change this, it is a good idea still to end with a -newline so that mode annotations will appear on lines by themselves. - -@node Programming, Copying, Embedded Mode, Top -@chapter Programming - -@noindent -There are several ways to ``program'' the Emacs Calculator, depending -on the nature of the problem you need to solve. - -@enumerate -@item -@dfn{Keyboard macros} allow you to record a sequence of keystrokes -and play them back at a later time. This is just the standard Emacs -keyboard macro mechanism, dressed up with a few more features such -as loops and conditionals. - -@item -@dfn{Algebraic definitions} allow you to use any formula to define a -new function. This function can then be used in algebraic formulas or -as an interactive command. - -@item -@dfn{Rewrite rules} are discussed in the section on algebra commands. -@xref{Rewrite Rules}. If you put your rewrite rules in the variable -@code{EvalRules}, they will be applied automatically to all Calc -results in just the same way as an internal ``rule'' is applied to -evaluate @samp{sqrt(9)} to 3 and so on. @xref{Automatic Rewrites}. - -@item -@dfn{Lisp} is the programming language that Calc (and most of Emacs) -is written in. If the above techniques aren't powerful enough, you -can write Lisp functions to do anything that built-in Calc commands -can do. Lisp code is also somewhat faster than keyboard macros or -rewrite rules. -@end enumerate - -@kindex z -Programming features are available through the @kbd{z} and @kbd{Z} -prefix keys. New commands that you define are two-key sequences -beginning with @kbd{z}. Commands for managing these definitions -use the shift-@kbd{Z} prefix. (The @kbd{Z T} (@code{calc-timing}) -command is described elsewhere; @pxref{Troubleshooting Commands}. -The @kbd{Z C} (@code{calc-user-define-composition}) command is also -described elsewhere; @pxref{User-Defined Compositions}.) - -@menu -* Creating User Keys:: -* Keyboard Macros:: -* Invocation Macros:: -* Algebraic Definitions:: -* Lisp Definitions:: -@end menu - -@node Creating User Keys, Keyboard Macros, Programming, Programming -@section Creating User Keys - -@noindent -@kindex Z D -@pindex calc-user-define -Any Calculator command may be bound to a key using the @kbd{Z D} -(@code{calc-user-define}) command. Actually, it is bound to a two-key -sequence beginning with the lower-case @kbd{z} prefix. - -The @kbd{Z D} command first prompts for the key to define. For example, -press @kbd{Z D a} to define the new key sequence @kbd{z a}. You are then -prompted for the name of the Calculator command that this key should -run. For example, the @code{calc-sincos} command is not normally -available on a key. Typing @kbd{Z D s sincos @key{RET}} programs the -@kbd{z s} key sequence to run @code{calc-sincos}. This definition will remain -in effect for the rest of this Emacs session, or until you redefine -@kbd{z s} to be something else. - -You can actually bind any Emacs command to a @kbd{z} key sequence by -backspacing over the @samp{calc-} when you are prompted for the command name. - -As with any other prefix key, you can type @kbd{z ?} to see a list of -all the two-key sequences you have defined that start with @kbd{z}. -Initially, no @kbd{z} sequences (except @kbd{z ?} itself) are defined. - -User keys are typically letters, but may in fact be any key. -(@key{META}-keys are not permitted, nor are a terminal's special -function keys which generate multi-character sequences when pressed.) -You can define different commands on the shifted and unshifted versions -of a letter if you wish. - -@kindex Z U -@pindex calc-user-undefine -The @kbd{Z U} (@code{calc-user-undefine}) command unbinds a user key. -For example, the key sequence @kbd{Z U s} will undefine the @code{sincos} -key we defined above. - -@kindex Z P -@pindex calc-user-define-permanent -@cindex Storing user definitions -@cindex Permanent user definitions -@cindex Calc init file, user-defined commands -The @kbd{Z P} (@code{calc-user-define-permanent}) command makes a key -binding permanent so that it will remain in effect even in future Emacs -sessions. (It does this by adding a suitable bit of Lisp code into -your Calc init file; that is, the file given by the variable -@code{calc-settings-file}, typically @file{~/.calc.el}.) For example, -@kbd{Z P s} would register our @code{sincos} command permanently. If -you later wish to unregister this command you must edit your Calc init -file by hand. (@xref{General Mode Commands}, for a way to tell Calc to -use a different file for the Calc init file.) - -The @kbd{Z P} command also saves the user definition, if any, for the -command bound to the key. After @kbd{Z F} and @kbd{Z C}, a given user -key could invoke a command, which in turn calls an algebraic function, -which might have one or more special display formats. A single @kbd{Z P} -command will save all of these definitions. -To save an algebraic function, type @kbd{'} (the apostrophe) -when prompted for a key, and type the function name. To save a command -without its key binding, type @kbd{M-x} and enter a function name. (The -@samp{calc-} prefix will automatically be inserted for you.) -(If the command you give implies a function, the function will be saved, -and if the function has any display formats, those will be saved, but -not the other way around: Saving a function will not save any commands -or key bindings associated with the function.) - -@kindex Z E -@pindex calc-user-define-edit -@cindex Editing user definitions -The @kbd{Z E} (@code{calc-user-define-edit}) command edits the definition -of a user key. This works for keys that have been defined by either -keyboard macros or formulas; further details are contained in the relevant -following sections. - -@node Keyboard Macros, Invocation Macros, Creating User Keys, Programming -@section Programming with Keyboard Macros - -@noindent -@kindex X -@cindex Programming with keyboard macros -@cindex Keyboard macros -The easiest way to ``program'' the Emacs Calculator is to use standard -keyboard macros. Press @w{@kbd{C-x (}} to begin recording a macro. From -this point on, keystrokes you type will be saved away as well as -performing their usual functions. Press @kbd{C-x )} to end recording. -Press shift-@kbd{X} (or the standard Emacs key sequence @kbd{C-x e}) to -execute your keyboard macro by replaying the recorded keystrokes. -@xref{Keyboard Macros, , , emacs, the Emacs Manual}, for further -information. - -When you use @kbd{X} to invoke a keyboard macro, the entire macro is -treated as a single command by the undo and trail features. The stack -display buffer is not updated during macro execution, but is instead -fixed up once the macro completes. Thus, commands defined with keyboard -macros are convenient and efficient. The @kbd{C-x e} command, on the -other hand, invokes the keyboard macro with no special treatment: Each -command in the macro will record its own undo information and trail entry, -and update the stack buffer accordingly. If your macro uses features -outside of Calc's control to operate on the contents of the Calc stack -buffer, or if it includes Undo, Redo, or last-arguments commands, you -must use @kbd{C-x e} to make sure the buffer and undo list are up-to-date -at all times. You could also consider using @kbd{K} (@code{calc-keep-args}) -instead of @kbd{M-@key{RET}} (@code{calc-last-args}). - -Calc extends the standard Emacs keyboard macros in several ways. -Keyboard macros can be used to create user-defined commands. Keyboard -macros can include conditional and iteration structures, somewhat -analogous to those provided by a traditional programmable calculator. - -@menu -* Naming Keyboard Macros:: -* Conditionals in Macros:: -* Loops in Macros:: -* Local Values in Macros:: -* Queries in Macros:: -@end menu - -@node Naming Keyboard Macros, Conditionals in Macros, Keyboard Macros, Keyboard Macros -@subsection Naming Keyboard Macros - -@noindent -@kindex Z K -@pindex calc-user-define-kbd-macro -Once you have defined a keyboard macro, you can bind it to a @kbd{z} -key sequence with the @kbd{Z K} (@code{calc-user-define-kbd-macro}) command. -This command prompts first for a key, then for a command name. For -example, if you type @kbd{C-x ( n @key{TAB} n @key{TAB} C-x )} you will -define a keyboard macro which negates the top two numbers on the stack -(@key{TAB} swaps the top two stack elements). Now you can type -@kbd{Z K n @key{RET}} to define this keyboard macro onto the @kbd{z n} key -sequence. The default command name (if you answer the second prompt with -just the @key{RET} key as in this example) will be something like -@samp{calc-User-n}. The keyboard macro will now be available as both -@kbd{z n} and @kbd{M-x calc-User-n}. You can backspace and enter a more -descriptive command name if you wish. - -Macros defined by @kbd{Z K} act like single commands; they are executed -in the same way as by the @kbd{X} key. If you wish to define the macro -as a standard no-frills Emacs macro (to be executed as if by @kbd{C-x e}), -give a negative prefix argument to @kbd{Z K}. - -Once you have bound your keyboard macro to a key, you can use -@kbd{Z P} to register it permanently with Emacs. @xref{Creating User Keys}. - -@cindex Keyboard macros, editing -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a keyboard macro tries to use the @code{edmacro} package -edit the macro. Type @kbd{C-c C-c} to finish editing and update -the definition stored on the key, or, to cancel the edit, kill the -buffer with @kbd{C-x k}. -The special characters @code{RET}, @code{LFD}, @code{TAB}, @code{SPC}, -@code{DEL}, and @code{NUL} must be entered as these three character -sequences, written in all uppercase, as must the prefixes @code{C-} and -@code{M-}. Spaces and line breaks are ignored. Other characters are -copied verbatim into the keyboard macro. Basically, the notation is the -same as is used in all of this manual's examples, except that the manual -takes some liberties with spaces: When we say @kbd{' [1 2 3] @key{RET}}, -we take it for granted that it is clear we really mean -@kbd{' [1 @key{SPC} 2 @key{SPC} 3] @key{RET}}. - -@kindex C-x * m -@pindex read-kbd-macro -The @kbd{C-x * m} (@code{read-kbd-macro}) command reads an Emacs ``region'' -of spelled-out keystrokes and defines it as the current keyboard macro. -It is a convenient way to define a keyboard macro that has been stored -in a file, or to define a macro without executing it at the same time. - -@node Conditionals in Macros, Loops in Macros, Naming Keyboard Macros, Keyboard Macros -@subsection Conditionals in Keyboard Macros - -@noindent -@kindex Z [ -@kindex Z ] -@pindex calc-kbd-if -@pindex calc-kbd-else -@pindex calc-kbd-else-if -@pindex calc-kbd-end-if -@cindex Conditional structures -The @kbd{Z [} (@code{calc-kbd-if}) and @kbd{Z ]} (@code{calc-kbd-end-if}) -commands allow you to put simple tests in a keyboard macro. When Calc -sees the @kbd{Z [}, it pops an object from the stack and, if the object is -a non-zero value, continues executing keystrokes. But if the object is -zero, or if it is not provably nonzero, Calc skips ahead to the matching -@kbd{Z ]} keystroke. @xref{Logical Operations}, for a set of commands for -performing tests which conveniently produce 1 for true and 0 for false. - -For example, @kbd{@key{RET} 0 a < Z [ n Z ]} implements an absolute-value -function in the form of a keyboard macro. This macro duplicates the -number on the top of the stack, pushes zero and compares using @kbd{a <} -(@code{calc-less-than}), then, if the number was less than zero, -executes @kbd{n} (@code{calc-change-sign}). Otherwise, the change-sign -command is skipped. - -To program this macro, type @kbd{C-x (}, type the above sequence of -keystrokes, then type @kbd{C-x )}. Note that the keystrokes will be -executed while you are making the definition as well as when you later -re-execute the macro by typing @kbd{X}. Thus you should make sure a -suitable number is on the stack before defining the macro so that you -don't get a stack-underflow error during the definition process. - -Conditionals can be nested arbitrarily. However, there should be exactly -one @kbd{Z ]} for each @kbd{Z [} in a keyboard macro. - -@kindex Z : -The @kbd{Z :} (@code{calc-kbd-else}) command allows you to choose between -two keystroke sequences. The general format is @kbd{@var{cond} Z [ -@var{then-part} Z : @var{else-part} Z ]}. If @var{cond} is true -(i.e., if the top of stack contains a non-zero number after @var{cond} -has been executed), the @var{then-part} will be executed and the -@var{else-part} will be skipped. Otherwise, the @var{then-part} will -be skipped and the @var{else-part} will be executed. - -@kindex Z | -The @kbd{Z |} (@code{calc-kbd-else-if}) command allows you to choose -between any number of alternatives. For example, -@kbd{@var{cond1} Z [ @var{part1} Z : @var{cond2} Z | @var{part2} Z : -@var{part3} Z ]} will execute @var{part1} if @var{cond1} is true, -otherwise it will execute @var{part2} if @var{cond2} is true, otherwise -it will execute @var{part3}. - -More precisely, @kbd{Z [} pops a number and conditionally skips to the -next matching @kbd{Z :} or @kbd{Z ]} key. @w{@kbd{Z ]}} has no effect when -actually executed. @kbd{Z :} skips to the next matching @kbd{Z ]}. -@kbd{Z |} pops a number and conditionally skips to the next matching -@kbd{Z :} or @kbd{Z ]}; thus, @kbd{Z [} and @kbd{Z |} are functionally -equivalent except that @kbd{Z [} participates in nesting but @kbd{Z |} -does not. - -Calc's conditional and looping constructs work by scanning the -keyboard macro for occurrences of character sequences like @samp{Z:} -and @samp{Z]}. One side-effect of this is that if you use these -constructs you must be careful that these character pairs do not -occur by accident in other parts of the macros. Since Calc rarely -uses shift-@kbd{Z} for any purpose except as a prefix character, this -is not likely to be a problem. Another side-effect is that it will -not work to define your own custom key bindings for these commands. -Only the standard shift-@kbd{Z} bindings will work correctly. - -@kindex Z C-g -If Calc gets stuck while skipping characters during the definition of a -macro, type @kbd{Z C-g} to cancel the definition. (Typing plain @kbd{C-g} -actually adds a @kbd{C-g} keystroke to the macro.) - -@node Loops in Macros, Local Values in Macros, Conditionals in Macros, Keyboard Macros -@subsection Loops in Keyboard Macros - -@noindent -@kindex Z < -@kindex Z > -@pindex calc-kbd-repeat -@pindex calc-kbd-end-repeat -@cindex Looping structures -@cindex Iterative structures -The @kbd{Z <} (@code{calc-kbd-repeat}) and @kbd{Z >} -(@code{calc-kbd-end-repeat}) commands pop a number from the stack, -which must be an integer, then repeat the keystrokes between the brackets -the specified number of times. If the integer is zero or negative, the -body is skipped altogether. For example, @kbd{1 @key{TAB} Z < 2 * Z >} -computes two to a nonnegative integer power. First, we push 1 on the -stack and then swap the integer argument back to the top. The @kbd{Z <} -pops that argument leaving the 1 back on top of the stack. Then, we -repeat a multiply-by-two step however many times. - -Once again, the keyboard macro is executed as it is being entered. -In this case it is especially important to set up reasonable initial -conditions before making the definition: Suppose the integer 1000 just -happened to be sitting on the stack before we typed the above definition! -Another approach is to enter a harmless dummy definition for the macro, -then go back and edit in the real one with a @kbd{Z E} command. Yet -another approach is to type the macro as written-out keystroke names -in a buffer, then use @kbd{C-x * m} (@code{read-kbd-macro}) to read the -macro. - -@kindex Z / -@pindex calc-break -The @kbd{Z /} (@code{calc-kbd-break}) command allows you to break out -of a keyboard macro loop prematurely. It pops an object from the stack; -if that object is true (a non-zero number), control jumps out of the -innermost enclosing @kbd{Z <} @dots{} @kbd{Z >} loop and continues -after the @kbd{Z >}. If the object is false, the @kbd{Z /} has no -effect. Thus @kbd{@var{cond} Z /} is similar to @samp{if (@var{cond}) break;} -in the C language. - -@kindex Z ( -@kindex Z ) -@pindex calc-kbd-for -@pindex calc-kbd-end-for -The @kbd{Z (} (@code{calc-kbd-for}) and @kbd{Z )} (@code{calc-kbd-end-for}) -commands are similar to @kbd{Z <} and @kbd{Z >}, except that they make the -value of the counter available inside the loop. The general layout is -@kbd{@var{init} @var{final} Z ( @var{body} @var{step} Z )}. The @kbd{Z (} -command pops initial and final values from the stack. It then creates -a temporary internal counter and initializes it with the value @var{init}. -The @kbd{Z (} command then repeatedly pushes the counter value onto the -stack and executes @var{body} and @var{step}, adding @var{step} to the -counter each time until the loop finishes. - -@cindex Summations (by keyboard macros) -By default, the loop finishes when the counter becomes greater than (or -less than) @var{final}, assuming @var{initial} is less than (greater -than) @var{final}. If @var{initial} is equal to @var{final}, the body -executes exactly once. The body of the loop always executes at least -once. For example, @kbd{0 1 10 Z ( 2 ^ + 1 Z )} computes the sum of the -squares of the integers from 1 to 10, in steps of 1. - -If you give a numeric prefix argument of 1 to @kbd{Z (}, the loop is -forced to use upward-counting conventions. In this case, if @var{initial} -is greater than @var{final} the body will not be executed at all. -Note that @var{step} may still be negative in this loop; the prefix -argument merely constrains the loop-finished test. Likewise, a prefix -argument of @mathit{-1} forces downward-counting conventions. - -@kindex Z @{ -@kindex Z @} -@pindex calc-kbd-loop -@pindex calc-kbd-end-loop -The @kbd{Z @{} (@code{calc-kbd-loop}) and @kbd{Z @}} -(@code{calc-kbd-end-loop}) commands are similar to @kbd{Z <} and -@kbd{Z >}, except that they do not pop a count from the stack---they -effectively create an infinite loop. Every @kbd{Z @{} @dots{} @kbd{Z @}} -loop ought to include at least one @kbd{Z /} to make sure the loop -doesn't run forever. (If any error message occurs which causes Emacs -to beep, the keyboard macro will also be halted; this is a standard -feature of Emacs. You can also generally press @kbd{C-g} to halt a -running keyboard macro, although not all versions of Unix support -this feature.) - -The conditional and looping constructs are not actually tied to -keyboard macros, but they are most often used in that context. -For example, the keystrokes @kbd{10 Z < 23 @key{RET} Z >} push -ten copies of 23 onto the stack. This can be typed ``live'' just -as easily as in a macro definition. - -@xref{Conditionals in Macros}, for some additional notes about -conditional and looping commands. - -@node Local Values in Macros, Queries in Macros, Loops in Macros, Keyboard Macros -@subsection Local Values in Macros - -@noindent -@cindex Local variables -@cindex Restoring saved modes -Keyboard macros sometimes want to operate under known conditions -without affecting surrounding conditions. For example, a keyboard -macro may wish to turn on Fraction mode, or set a particular -precision, independent of the user's normal setting for those -modes. - -@kindex Z ` -@kindex Z ' -@pindex calc-kbd-push -@pindex calc-kbd-pop -Macros also sometimes need to use local variables. Assignments to -local variables inside the macro should not affect any variables -outside the macro. The @kbd{Z `} (@code{calc-kbd-push}) and @kbd{Z '} -(@code{calc-kbd-pop}) commands give you both of these capabilities. - -When you type @kbd{Z `} (with a backquote or accent grave character), -the values of various mode settings are saved away. The ten ``quick'' -variables @code{q0} through @code{q9} are also saved. When -you type @w{@kbd{Z '}} (with an apostrophe), these values are restored. -Pairs of @kbd{Z `} and @kbd{Z '} commands may be nested. - -If a keyboard macro halts due to an error in between a @kbd{Z `} and -a @kbd{Z '}, the saved values will be restored correctly even though -the macro never reaches the @kbd{Z '} command. Thus you can use -@kbd{Z `} and @kbd{Z '} without having to worry about what happens -in exceptional conditions. - -If you type @kbd{Z `} ``live'' (not in a keyboard macro), Calc puts -you into a ``recursive edit.'' You can tell you are in a recursive -edit because there will be extra square brackets in the mode line, -as in @samp{[(Calculator)]}. These brackets will go away when you -type the matching @kbd{Z '} command. The modes and quick variables -will be saved and restored in just the same way as if actual keyboard -macros were involved. - -The modes saved by @kbd{Z `} and @kbd{Z '} are the current precision -and binary word size, the angular mode (Deg, Rad, or HMS), the -simplification mode, Algebraic mode, Symbolic mode, Infinite mode, -Matrix or Scalar mode, Fraction mode, and the current complex mode -(Polar or Rectangular). The ten ``quick'' variables' values (or lack -thereof) are also saved. - -Most mode-setting commands act as toggles, but with a numeric prefix -they force the mode either on (positive prefix) or off (negative -or zero prefix). Since you don't know what the environment might -be when you invoke your macro, it's best to use prefix arguments -for all mode-setting commands inside the macro. - -In fact, @kbd{C-u Z `} is like @kbd{Z `} except that it sets the modes -listed above to their default values. As usual, the matching @kbd{Z '} -will restore the modes to their settings from before the @kbd{C-u Z `}. -Also, @w{@kbd{Z `}} with a negative prefix argument resets the algebraic mode -to its default (off) but leaves the other modes the same as they were -outside the construct. - -The contents of the stack and trail, values of non-quick variables, and -other settings such as the language mode and the various display modes, -are @emph{not} affected by @kbd{Z `} and @kbd{Z '}. - -@node Queries in Macros, , Local Values in Macros, Keyboard Macros -@subsection Queries in Keyboard Macros - -@c @noindent -@c @kindex Z = -@c @pindex calc-kbd-report -@c The @kbd{Z =} (@code{calc-kbd-report}) command displays an informative -@c message including the value on the top of the stack. You are prompted -@c to enter a string. That string, along with the top-of-stack value, -@c is displayed unless @kbd{m w} (@code{calc-working}) has been used -@c to turn such messages off. - -@noindent -@kindex Z # -@pindex calc-kbd-query -The @kbd{Z #} (@code{calc-kbd-query}) command prompts for an algebraic -entry which takes its input from the keyboard, even during macro -execution. All the normal conventions of algebraic input, including the -use of @kbd{$} characters, are supported. The prompt message itself is -taken from the top of the stack, and so must be entered (as a string) -before the @kbd{Z #} command. (Recall, as a string it can be entered by -pressing the @kbd{"} key and will appear as a vector when it is put on -the stack. The prompt message is only put on the stack to provide a -prompt for the @kbd{Z #} command; it will not play any role in any -subsequent calculations.) This command allows your keyboard macros to -accept numbers or formulas as interactive input. - -As an example, -@kbd{2 @key{RET} "Power: " @key{RET} Z # 3 @key{RET} ^} will prompt for -input with ``Power: '' in the minibuffer, then return 2 to the provided -power. (The response to the prompt that's given, 3 in this example, -will not be part of the macro.) - -@xref{Keyboard Macro Query, , , emacs, the Emacs Manual}, for a description of -@kbd{C-x q} (@code{kbd-macro-query}), the standard Emacs way to accept -keyboard input during a keyboard macro. In particular, you can use -@kbd{C-x q} to enter a recursive edit, which allows the user to perform -any Calculator operations interactively before pressing @kbd{C-M-c} to -return control to the keyboard macro. - -@node Invocation Macros, Algebraic Definitions, Keyboard Macros, Programming -@section Invocation Macros - -@kindex C-x * z -@kindex Z I -@pindex calc-user-invocation -@pindex calc-user-define-invocation -Calc provides one special keyboard macro, called up by @kbd{C-x * z} -(@code{calc-user-invocation}), that is intended to allow you to define -your own special way of starting Calc. To define this ``invocation -macro,'' create the macro in the usual way with @kbd{C-x (} and -@kbd{C-x )}, then type @kbd{Z I} (@code{calc-user-define-invocation}). -There is only one invocation macro, so you don't need to type any -additional letters after @kbd{Z I}. From now on, you can type -@kbd{C-x * z} at any time to execute your invocation macro. - -For example, suppose you find yourself often grabbing rectangles of -numbers into Calc and multiplying their columns. You can do this -by typing @kbd{C-x * r} to grab, and @kbd{V R : *} to multiply columns. -To make this into an invocation macro, just type @kbd{C-x ( C-x * r -V R : * C-x )}, then @kbd{Z I}. Then, to multiply a rectangle of data, -just mark the data in its buffer in the usual way and type @kbd{C-x * z}. - -Invocation macros are treated like regular Emacs keyboard macros; -all the special features described above for @kbd{Z K}-style macros -do not apply. @kbd{C-x * z} is just like @kbd{C-x e}, except that it -uses the macro that was last stored by @kbd{Z I}. (In fact, the -macro does not even have to have anything to do with Calc!) - -The @kbd{m m} command saves the last invocation macro defined by -@kbd{Z I} along with all the other Calc mode settings. -@xref{General Mode Commands}. - -@node Algebraic Definitions, Lisp Definitions, Invocation Macros, Programming -@section Programming with Formulas - -@noindent -@kindex Z F -@pindex calc-user-define-formula -@cindex Programming with algebraic formulas -Another way to create a new Calculator command uses algebraic formulas. -The @kbd{Z F} (@code{calc-user-define-formula}) command stores the -formula at the top of the stack as the definition for a key. This -command prompts for five things: The key, the command name, the function -name, the argument list, and the behavior of the command when given -non-numeric arguments. - -For example, suppose we type @kbd{' a+2b @key{RET}} to push the formula -@samp{a + 2*b} onto the stack. We now type @kbd{Z F m} to define this -formula on the @kbd{z m} key sequence. The next prompt is for a command -name, beginning with @samp{calc-}, which should be the long (@kbd{M-x}) form -for the new command. If you simply press @key{RET}, a default name like -@code{calc-User-m} will be constructed. In our example, suppose we enter -@kbd{spam @key{RET}} to define the new command as @code{calc-spam}. - -If you want to give the formula a long-style name only, you can press -@key{SPC} or @key{RET} when asked which single key to use. For example -@kbd{Z F @key{RET} spam @key{RET}} defines the new command as -@kbd{M-x calc-spam}, with no keyboard equivalent. - -The third prompt is for an algebraic function name. The default is to -use the same name as the command name but without the @samp{calc-} -prefix. (If this is of the form @samp{User-m}, the hyphen is removed so -it won't be taken for a minus sign in algebraic formulas.) -This is the name you will use if you want to enter your -new function in an algebraic formula. Suppose we enter @kbd{yow @key{RET}}. -Then the new function can be invoked by pushing two numbers on the -stack and typing @kbd{z m} or @kbd{x spam}, or by entering the algebraic -formula @samp{yow(x,y)}. - -The fourth prompt is for the function's argument list. This is used to -associate values on the stack with the variables that appear in the formula. -The default is a list of all variables which appear in the formula, sorted -into alphabetical order. In our case, the default would be @samp{(a b)}. -This means that, when the user types @kbd{z m}, the Calculator will remove -two numbers from the stack, substitute these numbers for @samp{a} and -@samp{b} (respectively) in the formula, then simplify the formula and -push the result on the stack. In other words, @kbd{10 @key{RET} 100 z m} -would replace the 10 and 100 on the stack with the number 210, which is -@expr{a + 2 b} with @expr{a=10} and @expr{b=100}. Likewise, the formula -@samp{yow(10, 100)} will be evaluated by substituting @expr{a=10} and -@expr{b=100} in the definition. - -You can rearrange the order of the names before pressing @key{RET} to -control which stack positions go to which variables in the formula. If -you remove a variable from the argument list, that variable will be left -in symbolic form by the command. Thus using an argument list of @samp{(b)} -for our function would cause @kbd{10 z m} to replace the 10 on the stack -with the formula @samp{a + 20}. If we had used an argument list of -@samp{(b a)}, the result with inputs 10 and 100 would have been 120. - -You can also put a nameless function on the stack instead of just a -formula, as in @samp{}. @xref{Specifying Operators}. -In this example, the command will be defined by the formula @samp{a + 2 b} -using the argument list @samp{(a b)}. - -The final prompt is a y-or-n question concerning what to do if symbolic -arguments are given to your function. If you answer @kbd{y}, then -executing @kbd{z m} (using the original argument list @samp{(a b)}) with -arguments @expr{10} and @expr{x} will leave the function in symbolic -form, i.e., @samp{yow(10,x)}. On the other hand, if you answer @kbd{n}, -then the formula will always be expanded, even for non-constant -arguments: @samp{10 + 2 x}. If you never plan to feed algebraic -formulas to your new function, it doesn't matter how you answer this -question. - -If you answered @kbd{y} to this question you can still cause a function -call to be expanded by typing @kbd{a "} (@code{calc-expand-formula}). -Also, Calc will expand the function if necessary when you take a -derivative or integral or solve an equation involving the function. - -@kindex Z G -@pindex calc-get-user-defn -Once you have defined a formula on a key, you can retrieve this formula -with the @kbd{Z G} (@code{calc-user-define-get-defn}) command. Press a -key, and this command pushes the formula that was used to define that -key onto the stack. Actually, it pushes a nameless function that -specifies both the argument list and the defining formula. You will get -an error message if the key is undefined, or if the key was not defined -by a @kbd{Z F} command. - -The @kbd{Z E} (@code{calc-user-define-edit}) command on a key that has -been defined by a formula uses a variant of the @code{calc-edit} command -to edit the defining formula. Press @kbd{C-c C-c} to finish editing and -store the new formula back in the definition, or kill the buffer with -@kbd{C-x k} to -cancel the edit. (The argument list and other properties of the -definition are unchanged; to adjust the argument list, you can use -@kbd{Z G} to grab the function onto the stack, edit with @kbd{`}, and -then re-execute the @kbd{Z F} command.) - -As usual, the @kbd{Z P} command records your definition permanently. -In this case it will permanently record all three of the relevant -definitions: the key, the command, and the function. - -You may find it useful to turn off the default simplifications with -@kbd{m O} (@code{calc-no-simplify-mode}) when entering a formula to be -used as a function definition. For example, the formula @samp{deriv(a^2,v)} -which might be used to define a new function @samp{dsqr(a,v)} will be -``simplified'' to 0 immediately upon entry since @code{deriv} considers -@expr{a} to be constant with respect to @expr{v}. Turning off -default simplifications cures this problem: The definition will be stored -in symbolic form without ever activating the @code{deriv} function. Press -@kbd{m D} to turn the default simplifications back on afterwards. - -@node Lisp Definitions, , Algebraic Definitions, Programming -@section Programming with Lisp - -@noindent -The Calculator can be programmed quite extensively in Lisp. All you -do is write a normal Lisp function definition, but with @code{defmath} -in place of @code{defun}. This has the same form as @code{defun}, but it -automagically replaces calls to standard Lisp functions like @code{+} and -@code{zerop} with calls to the corresponding functions in Calc's own library. -Thus you can write natural-looking Lisp code which operates on all of the -standard Calculator data types. You can then use @kbd{Z D} if you wish to -bind your new command to a @kbd{z}-prefix key sequence. The @kbd{Z E} command -will not edit a Lisp-based definition. - -Emacs Lisp is described in the GNU Emacs Lisp Reference Manual. This section -assumes a familiarity with Lisp programming concepts; if you do not know -Lisp, you may find keyboard macros or rewrite rules to be an easier way -to program the Calculator. - -This section first discusses ways to write commands, functions, or -small programs to be executed inside of Calc. Then it discusses how -your own separate programs are able to call Calc from the outside. -Finally, there is a list of internal Calc functions and data structures -for the true Lisp enthusiast. - -@menu -* Defining Functions:: -* Defining Simple Commands:: -* Defining Stack Commands:: -* Argument Qualifiers:: -* Example Definitions:: - -* Calling Calc from Your Programs:: -* Internals:: -@end menu - -@node Defining Functions, Defining Simple Commands, Lisp Definitions, Lisp Definitions -@subsection Defining New Functions - -@noindent -@findex defmath -The @code{defmath} function (actually a Lisp macro) is like @code{defun} -except that code in the body of the definition can make use of the full -range of Calculator data types. The prefix @samp{calcFunc-} is added -to the specified name to get the actual Lisp function name. As a simple -example, - -@example -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - 1)) -@end example - -@noindent -This actually expands to the code, - -@example -(defun calcFunc-myfact (n) - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - 1)) -@end example - -@noindent -This function can be used in algebraic expressions, e.g., @samp{myfact(5)}. - -The @samp{myfact} function as it is defined above has the bug that an -expression @samp{myfact(a+b)} will be simplified to 1 because the -formula @samp{a+b} is not considered to be @code{posp}. A robust -factorial function would be written along the following lines: - -@smallexample -(defmath myfact (n) - (if (> n 0) - (* n (myfact (1- n))) - (if (= n 0) - 1 - nil))) ; this could be simplified as: (and (= n 0) 1) -@end smallexample - -If a function returns @code{nil}, it is left unsimplified by the Calculator -(except that its arguments will be simplified). Thus, @samp{myfact(a+1+2)} -will be simplified to @samp{myfact(a+3)} but no further. Beware that every -time the Calculator reexamines this formula it will attempt to resimplify -it, so your function ought to detect the returning-@code{nil} case as -efficiently as possible. - -The following standard Lisp functions are treated by @code{defmath}: -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^} or -@code{expt}, @code{=}, @code{<}, @code{>}, @code{<=}, @code{>=}, -@code{/=}, @code{1+}, @code{1-}, @code{logand}, @code{logior}, @code{logxor}, -@code{logandc2}, @code{lognot}. Also, @code{~=} is an abbreviation for -@code{math-nearly-equal}, which is useful in implementing Taylor series. - -For other functions @var{func}, if a function by the name -@samp{calcFunc-@var{func}} exists it is used, otherwise if a function by the -name @samp{math-@var{func}} exists it is used, otherwise if @var{func} itself -is defined as a function it is used, otherwise @samp{calcFunc-@var{func}} is -used on the assumption that this is a to-be-defined math function. Also, if -the function name is quoted as in @samp{('integerp a)} the function name is -always used exactly as written (but not quoted). - -Variable names have @samp{var-} prepended to them unless they appear in -the function's argument list or in an enclosing @code{let}, @code{let*}, -@code{for}, or @code{foreach} form, -or their names already contain a @samp{-} character. Thus a reference to -@samp{foo} is the same as a reference to @samp{var-foo}. - -A few other Lisp extensions are available in @code{defmath} definitions: - -@itemize @bullet -@item -The @code{elt} function accepts any number of index variables. -Note that Calc vectors are stored as Lisp lists whose first -element is the symbol @code{vec}; thus, @samp{(elt v 2)} yields -the second element of vector @code{v}, and @samp{(elt m i j)} -yields one element of a Calc matrix. - -@item -The @code{setq} function has been extended to act like the Common -Lisp @code{setf} function. (The name @code{setf} is recognized as -a synonym of @code{setq}.) Specifically, the first argument of -@code{setq} can be an @code{nth}, @code{elt}, @code{car}, or @code{cdr} form, -in which case the effect is to store into the specified -element of a list. Thus, @samp{(setq (elt m i j) x)} stores @expr{x} -into one element of a matrix. - -@item -A @code{for} looping construct is available. For example, -@samp{(for ((i 0 10)) body)} executes @code{body} once for each -binding of @expr{i} from zero to 10. This is like a @code{let} -form in that @expr{i} is temporarily bound to the loop count -without disturbing its value outside the @code{for} construct. -Nested loops, as in @samp{(for ((i 0 10) (j 0 (1- i) 2)) body)}, -are also available. For each value of @expr{i} from zero to 10, -@expr{j} counts from 0 to @expr{i-1} in steps of two. Note that -@code{for} has the same general outline as @code{let*}, except -that each element of the header is a list of three or four -things, not just two. - -@item -The @code{foreach} construct loops over elements of a list. -For example, @samp{(foreach ((x (cdr v))) body)} executes -@code{body} with @expr{x} bound to each element of Calc vector -@expr{v} in turn. The purpose of @code{cdr} here is to skip over -the initial @code{vec} symbol in the vector. - -@item -The @code{break} function breaks out of the innermost enclosing -@code{while}, @code{for}, or @code{foreach} loop. If given a -value, as in @samp{(break x)}, this value is returned by the -loop. (Lisp loops otherwise always return @code{nil}.) - -@item -The @code{return} function prematurely returns from the enclosing -function. For example, @samp{(return (+ x y))} returns @expr{x+y} -as the value of a function. You can use @code{return} anywhere -inside the body of the function. -@end itemize - -Non-integer numbers (and extremely large integers) cannot be included -directly into a @code{defmath} definition. This is because the Lisp -reader will fail to parse them long before @code{defmath} ever gets control. -Instead, use the notation, @samp{:"3.1415"}. In fact, any algebraic -formula can go between the quotes. For example, - -@smallexample -(defmath sqexp (x) ; sqexp(x) == sqrt(exp(x)) == exp(x*0.5) - (and (numberp x) - (exp :"x * 0.5"))) -@end smallexample - -expands to - -@smallexample -(defun calcFunc-sqexp (x) - (and (math-numberp x) - (calcFunc-exp (math-mul x '(float 5 -1))))) -@end smallexample - -Note the use of @code{numberp} as a guard to ensure that the argument is -a number first, returning @code{nil} if not. The exponential function -could itself have been included in the expression, if we had preferred: -@samp{:"exp(x * 0.5)"}. As another example, the multiplication-and-recursion -step of @code{myfact} could have been written - -@example -:"n * myfact(n-1)" -@end example - -A good place to put your @code{defmath} commands is your Calc init file -(the file given by @code{calc-settings-file}, typically -@file{~/.calc.el}), which will not be loaded until Calc starts. -If a file named @file{.emacs} exists in your home directory, Emacs reads -and executes the Lisp forms in this file as it starts up. While it may -seem reasonable to put your favorite @code{defmath} commands there, -this has the unfortunate side-effect that parts of the Calculator must be -loaded in to process the @code{defmath} commands whether or not you will -actually use the Calculator! If you want to put the @code{defmath} -commands there (for example, if you redefine @code{calc-settings-file} -to be @file{.emacs}), a better effect can be had by writing - -@example -(put 'calc-define 'thing '(progn - (defmath ... ) - (defmath ... ) -)) -@end example - -@noindent -@vindex calc-define -The @code{put} function adds a @dfn{property} to a symbol. Each Lisp -symbol has a list of properties associated with it. Here we add a -property with a name of @code{thing} and a @samp{(progn ...)} form as -its value. When Calc starts up, and at the start of every Calc command, -the property list for the symbol @code{calc-define} is checked and the -values of any properties found are evaluated as Lisp forms. The -properties are removed as they are evaluated. The property names -(like @code{thing}) are not used; you should choose something like the -name of your project so as not to conflict with other properties. - -The net effect is that you can put the above code in your @file{.emacs} -file and it will not be executed until Calc is loaded. Or, you can put -that same code in another file which you load by hand either before or -after Calc itself is loaded. - -The properties of @code{calc-define} are evaluated in the same order -that they were added. They can assume that the Calc modules @file{calc.el}, -@file{calc-ext.el}, and @file{calc-macs.el} have been fully loaded, and -that the @samp{*Calculator*} buffer will be the current buffer. - -If your @code{calc-define} property only defines algebraic functions, -you can be sure that it will have been evaluated before Calc tries to -call your function, even if the file defining the property is loaded -after Calc is loaded. But if the property defines commands or key -sequences, it may not be evaluated soon enough. (Suppose it defines the -new command @code{tweak-calc}; the user can load your file, then type -@kbd{M-x tweak-calc} before Calc has had chance to do anything.) To -protect against this situation, you can put - -@example -(run-hooks 'calc-check-defines) -@end example - -@findex calc-check-defines -@noindent -at the end of your file. The @code{calc-check-defines} function is what -looks for and evaluates properties on @code{calc-define}; @code{run-hooks} -has the advantage that it is quietly ignored if @code{calc-check-defines} -is not yet defined because Calc has not yet been loaded. - -Examples of things that ought to be enclosed in a @code{calc-define} -property are @code{defmath} calls, @code{define-key} calls that modify -the Calc key map, and any calls that redefine things defined inside Calc. -Ordinary @code{defun}s need not be enclosed with @code{calc-define}. - -@node Defining Simple Commands, Defining Stack Commands, Defining Functions, Lisp Definitions -@subsection Defining New Simple Commands - -@noindent -@findex interactive -If a @code{defmath} form contains an @code{interactive} clause, it defines -a Calculator command. Actually such a @code{defmath} results in @emph{two} -function definitions: One, a @samp{calcFunc-} function as was just described, -with the @code{interactive} clause removed. Two, a @samp{calc-} function -with a suitable @code{interactive} clause and some sort of wrapper to make -the command work in the Calc environment. - -In the simple case, the @code{interactive} clause has the same form as -for normal Emacs Lisp commands: - -@smallexample -(defmath increase-precision (delta) - "Increase precision by DELTA." ; This is the "documentation string" - (interactive "p") ; Register this as a M-x-able command - (setq calc-internal-prec (+ calc-internal-prec delta))) -@end smallexample - -This expands to the pair of definitions, - -@smallexample -(defun calc-increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (calc-wrapper - (setq calc-internal-prec (math-add calc-internal-prec delta)))) - -(defun calcFunc-increase-precision (delta) - "Increase precision by DELTA." - (setq calc-internal-prec (math-add calc-internal-prec delta))) -@end smallexample - -@noindent -where in this case the latter function would never really be used! Note -that since the Calculator stores small integers as plain Lisp integers, -the @code{math-add} function will work just as well as the native -@code{+} even when the intent is to operate on native Lisp integers. - -@findex calc-wrapper -The @samp{calc-wrapper} call invokes a macro which surrounds the body of -the function with code that looks roughly like this: - -@smallexample -(let ((calc-command-flags nil)) - (unwind-protect - (save-excursion - (calc-select-buffer) - @emph{body of function} - @emph{renumber stack} - @emph{clear} Working @emph{message}) - @emph{realign cursor and window} - @emph{clear Inverse, Hyperbolic, and Keep Args flags} - @emph{update Emacs mode line})) -@end smallexample - -@findex calc-select-buffer -The @code{calc-select-buffer} function selects the @samp{*Calculator*} -buffer if necessary, say, because the command was invoked from inside -the @samp{*Calc Trail*} window. - -@findex calc-set-command-flag -You can call, for example, @code{(calc-set-command-flag 'no-align)} to -set the above-mentioned command flags. Calc routines recognize the -following command flags: - -@table @code -@item renum-stack -Stack line numbers @samp{1:}, @samp{2:}, and so on must be renumbered -after this command completes. This is set by routines like -@code{calc-push}. - -@item clear-message -Calc should call @samp{(message "")} if this command completes normally -(to clear a ``Working@dots{}'' message out of the echo area). - -@item no-align -Do not move the cursor back to the @samp{.} top-of-stack marker. - -@item position-point -Use the variables @code{calc-position-point-line} and -@code{calc-position-point-column} to position the cursor after -this command finishes. - -@item keep-flags -Do not clear @code{calc-inverse-flag}, @code{calc-hyperbolic-flag}, -and @code{calc-keep-args-flag} at the end of this command. - -@item do-edit -Switch to buffer @samp{*Calc Edit*} after this command. - -@item hold-trail -Do not move trail pointer to end of trail when something is recorded -there. -@end table - -@kindex Y -@kindex Y ? -@vindex calc-Y-help-msgs -Calc reserves a special prefix key, shift-@kbd{Y}, for user-written -extensions to Calc. There are no built-in commands that work with -this prefix key; you must call @code{define-key} from Lisp (probably -from inside a @code{calc-define} property) to add to it. Initially only -@kbd{Y ?} is defined; it takes help messages from a list of strings -(initially @code{nil}) in the variable @code{calc-Y-help-msgs}. All -other undefined keys except for @kbd{Y} are reserved for use by -future versions of Calc. - -If you are writing a Calc enhancement which you expect to give to -others, it is best to minimize the number of @kbd{Y}-key sequences -you use. In fact, if you have more than one key sequence you should -consider defining three-key sequences with a @kbd{Y}, then a key that -stands for your package, then a third key for the particular command -within your package. - -Users may wish to install several Calc enhancements, and it is possible -that several enhancements will choose to use the same key. In the -example below, a variable @code{inc-prec-base-key} has been defined -to contain the key that identifies the @code{inc-prec} package. Its -value is initially @code{"P"}, but a user can change this variable -if necessary without having to modify the file. - -Here is a complete file, @file{inc-prec.el}, which makes a @kbd{Y P I} -command that increases the precision, and a @kbd{Y P D} command that -decreases the precision. - -@smallexample -;;; Increase and decrease Calc precision. Dave Gillespie, 5/31/91. -;; (Include copyright or copyleft stuff here.) - -(defvar inc-prec-base-key "P" - "Base key for inc-prec.el commands.") - -(put 'calc-define 'inc-prec '(progn - -(define-key calc-mode-map (format "Y%sI" inc-prec-base-key) - 'increase-precision) -(define-key calc-mode-map (format "Y%sD" inc-prec-base-key) - 'decrease-precision) - -(setq calc-Y-help-msgs - (cons (format "%s + Inc-prec, Dec-prec" inc-prec-base-key) - calc-Y-help-msgs)) - -(defmath increase-precision (delta) - "Increase precision by DELTA." - (interactive "p") - (setq calc-internal-prec (+ calc-internal-prec delta))) - -(defmath decrease-precision (delta) - "Decrease precision by DELTA." - (interactive "p") - (setq calc-internal-prec (- calc-internal-prec delta))) - -)) ; end of calc-define property - -(run-hooks 'calc-check-defines) -@end smallexample - -@node Defining Stack Commands, Argument Qualifiers, Defining Simple Commands, Lisp Definitions -@subsection Defining New Stack-Based Commands - -@noindent -To define a new computational command which takes and/or leaves arguments -on the stack, a special form of @code{interactive} clause is used. - -@example -(interactive @var{num} @var{tag}) -@end example - -@noindent -where @var{num} is an integer, and @var{tag} is a string. The effect is -to pop @var{num} values off the stack, resimplify them by calling -@code{calc-normalize}, and hand them to your function according to the -function's argument list. Your function may include @code{&optional} and -@code{&rest} parameters, so long as calling the function with @var{num} -parameters is valid. - -Your function must return either a number or a formula in a form -acceptable to Calc, or a list of such numbers or formulas. These value(s) -are pushed onto the stack when the function completes. They are also -recorded in the Calc Trail buffer on a line beginning with @var{tag}, -a string of (normally) four characters or less. If you omit @var{tag} -or use @code{nil} as a tag, the result is not recorded in the trail. - -As an example, the definition - -@smallexample -(defmath myfact (n) - "Compute the factorial of the integer at the top of the stack." - (interactive 1 "fact") - (if (> n 0) - (* n (myfact (1- n))) - (and (= n 0) 1))) -@end smallexample - -@noindent -is a version of the factorial function shown previously which can be used -as a command as well as an algebraic function. It expands to - -@smallexample -(defun calc-myfact () - "Compute the factorial of the integer at the top of the stack." - (interactive) - (calc-slow-wrapper - (calc-enter-result 1 "fact" - (cons 'calcFunc-myfact (calc-top-list-n 1))))) - -(defun calcFunc-myfact (n) - "Compute the factorial of the integer at the top of the stack." - (if (math-posp n) - (math-mul n (calcFunc-myfact (math-add n -1))) - (and (math-zerop n) 1))) -@end smallexample - -@findex calc-slow-wrapper -The @code{calc-slow-wrapper} function is a version of @code{calc-wrapper} -that automatically puts up a @samp{Working...} message before the -computation begins. (This message can be turned off by the user -with an @kbd{m w} (@code{calc-working}) command.) - -@findex calc-top-list-n -The @code{calc-top-list-n} function returns a list of the specified number -of values from the top of the stack. It resimplifies each value by -calling @code{calc-normalize}. If its argument is zero it returns an -empty list. It does not actually remove these values from the stack. - -@findex calc-enter-result -The @code{calc-enter-result} function takes an integer @var{num} and string -@var{tag} as described above, plus a third argument which is either a -Calculator data object or a list of such objects. These objects are -resimplified and pushed onto the stack after popping the specified number -of values from the stack. If @var{tag} is non-@code{nil}, the values -being pushed are also recorded in the trail. - -Note that if @code{calcFunc-myfact} returns @code{nil} this represents -``leave the function in symbolic form.'' To return an actual empty list, -in the sense that @code{calc-enter-result} will push zero elements back -onto the stack, you should return the special value @samp{'(nil)}, a list -containing the single symbol @code{nil}. - -The @code{interactive} declaration can actually contain a limited -Emacs-style code string as well which comes just before @var{num} and -@var{tag}. Currently the only Emacs code supported is @samp{"p"}, as in - -@example -(defmath foo (a b &optional c) - (interactive "p" 2 "foo") - @var{body}) -@end example - -In this example, the command @code{calc-foo} will evaluate the expression -@samp{foo(a,b)} if executed with no argument, or @samp{foo(a,b,n)} if -executed with a numeric prefix argument of @expr{n}. - -The other code string allowed is @samp{"m"} (unrelated to the usual @samp{"m"} -code as used with @code{defun}). It uses the numeric prefix argument as the -number of objects to remove from the stack and pass to the function. -In this case, the integer @var{num} serves as a default number of -arguments to be used when no prefix is supplied. - -@node Argument Qualifiers, Example Definitions, Defining Stack Commands, Lisp Definitions -@subsection Argument Qualifiers - -@noindent -Anywhere a parameter name can appear in the parameter list you can also use -an @dfn{argument qualifier}. Thus the general form of a definition is: - -@example -(defmath @var{name} (@var{param} @var{param...} - &optional @var{param} @var{param...} - &rest @var{param}) - @var{body}) -@end example - -@noindent -where each @var{param} is either a symbol or a list of the form - -@example -(@var{qual} @var{param}) -@end example - -The following qualifiers are recognized: - -@table @samp -@item complete -@findex complete -The argument must not be an incomplete vector, interval, or complex number. -(This is rarely needed since the Calculator itself will never call your -function with an incomplete argument. But there is nothing stopping your -own Lisp code from calling your function with an incomplete argument.) - -@item integer -@findex integer -The argument must be an integer. If it is an integer-valued float -it will be accepted but converted to integer form. Non-integers and -formulas are rejected. - -@item natnum -@findex natnum -Like @samp{integer}, but the argument must be non-negative. - -@item fixnum -@findex fixnum -Like @samp{integer}, but the argument must fit into a native Lisp integer, -which on most systems means less than 2^23 in absolute value. The -argument is converted into Lisp-integer form if necessary. - -@item float -@findex float -The argument is converted to floating-point format if it is a number or -vector. If it is a formula it is left alone. (The argument is never -actually rejected by this qualifier.) - -@item @var{pred} -The argument must satisfy predicate @var{pred}, which is one of the -standard Calculator predicates. @xref{Predicates}. - -@item not-@var{pred} -The argument must @emph{not} satisfy predicate @var{pred}. -@end table - -For example, - -@example -(defmath foo (a (constp (not-matrixp b)) &optional (float c) - &rest (integer d)) - @var{body}) -@end example - -@noindent -expands to - -@example -(defun calcFunc-foo (a b &optional c &rest d) - (and (math-matrixp b) - (math-reject-arg b 'not-matrixp)) - (or (math-constp b) - (math-reject-arg b 'constp)) - (and c (setq c (math-check-float c))) - (setq d (mapcar 'math-check-integer d)) - @var{body}) -@end example - -@noindent -which performs the necessary checks and conversions before executing the -body of the function. - -@node Example Definitions, Calling Calc from Your Programs, Argument Qualifiers, Lisp Definitions -@subsection Example Definitions - -@noindent -This section includes some Lisp programming examples on a larger scale. -These programs make use of some of the Calculator's internal functions; -@pxref{Internals}. - -@menu -* Bit Counting Example:: -* Sine Example:: -@end menu - -@node Bit Counting Example, Sine Example, Example Definitions, Example Definitions -@subsubsection Bit-Counting - -@noindent -@ignore -@starindex -@end ignore -@tindex bcount -Calc does not include a built-in function for counting the number of -``one'' bits in a binary integer. It's easy to invent one using @kbd{b u} -to convert the integer to a set, and @kbd{V #} to count the elements of -that set; let's write a function that counts the bits without having to -create an intermediate set. - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (> n 0) - (if (oddp n) - (setq count (1+ count))) - (setq n (lsh n -1))) - count)) -@end smallexample - -@noindent -When this is expanded by @code{defmath}, it will become the following -Emacs Lisp function: - -@smallexample -(defun calcFunc-bcount (n) - (setq n (math-check-natnum n)) - (let ((count 0)) - (while (math-posp n) - (if (math-oddp n) - (setq count (math-add count 1))) - (setq n (calcFunc-lsh n -1))) - count)) -@end smallexample - -If the input numbers are large, this function involves a fair amount -of arithmetic. A binary right shift is essentially a division by two; -recall that Calc stores integers in decimal form so bit shifts must -involve actual division. - -To gain a bit more efficiency, we could divide the integer into -@var{n}-bit chunks, each of which can be handled quickly because -they fit into Lisp integers. It turns out that Calc's arithmetic -routines are especially fast when dividing by an integer less than -1000, so we can set @var{n = 9} bits and use repeated division by 512: - -@smallexample -(defmath bcount ((natnum n)) - (interactive 1 "bcnt") - (let ((count 0)) - (while (not (fixnump n)) - (let ((qr (idivmod n 512))) - (setq count (+ count (bcount-fixnum (cdr qr))) - n (car qr)))) - (+ count (bcount-fixnum n)))) - -(defun bcount-fixnum (n) - (let ((count 0)) - (while (> n 0) - (setq count (+ count (logand n 1)) - n (lsh n -1))) - count)) -@end smallexample - -@noindent -Note that the second function uses @code{defun}, not @code{defmath}. -Because this function deals only with native Lisp integers (``fixnums''), -it can use the actual Emacs @code{+} and related functions rather -than the slower but more general Calc equivalents which @code{defmath} -uses. - -The @code{idivmod} function does an integer division, returning both -the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are -more efficient ways to split off the bottom nine bits of @code{n}, -actually they are less efficient because each operation is really -a division by 512 in disguise; @code{idivmod} allows us to do the -same thing with a single division by 512. - -@node Sine Example, , Bit Counting Example, Example Definitions -@subsubsection The Sine Function - -@noindent -@ignore -@starindex -@end ignore -@tindex mysin -A somewhat limited sine function could be defined as follows, using the -well-known Taylor series expansion for -@texline @math{\sin x}: -@infoline @samp{sin(x)}: - -@smallexample -(defmath mysin ((float (anglep x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (let ((sum x) ; Initial term of Taylor expansion of sin. - newsum - (nfact 1) ; "nfact" equals "n" factorial at all times. - (xnegsqr :"-(x^2)")) ; "xnegsqr" equals -x^2. - (for ((n 3 100 2)) ; Upper limit of 100 is a good precaution. - (working "mysin" sum) ; Display "Working" message, if enabled. - (setq nfact (* nfact (1- n) n) - x (* x xnegsqr) - newsum (+ sum (/ x nfact))) - (if (~= newsum sum) ; If newsum is "nearly equal to" sum, - (break)) ; then we are done. - (setq sum newsum)) - sum)) -@end smallexample - -The actual @code{sin} function in Calc works by first reducing the problem -to a sine or cosine of a nonnegative number less than @cpiover{4}. This -ensures that the Taylor series will converge quickly. Also, the calculation -is carried out with two extra digits of precision to guard against cumulative -round-off in @samp{sum}. Finally, complex arguments are allowed and handled -by a separate algorithm. - -@smallexample -(defmath mysin ((float (scalarp x))) - (interactive 1 "mysn") - (setq x (to-radians x)) ; Convert from current angular mode. - (with-extra-prec 2 ; Evaluate with extra precision. - (cond ((complexp x) - (mysin-complex x)) - ((< x 0) - (- (mysin-raw (- x))) ; Always call mysin-raw with x >= 0. - (t (mysin-raw x)))))) - -(defmath mysin-raw (x) - (cond ((>= x 7) - (mysin-raw (% x (two-pi)))) ; Now x < 7. - ((> x (pi-over-2)) - (- (mysin-raw (- x (pi))))) ; Now -pi/2 <= x <= pi/2. - ((> x (pi-over-4)) - (mycos-raw (- x (pi-over-2)))) ; Now -pi/2 <= x <= pi/4. - ((< x (- (pi-over-4))) - (- (mycos-raw (+ x (pi-over-2))))) ; Now -pi/4 <= x <= pi/4, - (t (mysin-series x)))) ; so the series will be efficient. -@end smallexample - -@noindent -where @code{mysin-complex} is an appropriate function to handle complex -numbers, @code{mysin-series} is the routine to compute the sine Taylor -series as before, and @code{mycos-raw} is a function analogous to -@code{mysin-raw} for cosines. - -The strategy is to ensure that @expr{x} is nonnegative before calling -@code{mysin-raw}. This function then recursively reduces its argument -to a suitable range, namely, plus-or-minus @cpiover{4}. Note that each -test, and particularly the first comparison against 7, is designed so -that small roundoff errors cannot produce an infinite loop. (Suppose -we compared with @samp{(two-pi)} instead; if due to roundoff problems -the modulo operator ever returned @samp{(two-pi)} exactly, an infinite -recursion could result!) We use modulo only for arguments that will -clearly get reduced, knowing that the next rule will catch any reductions -that this rule misses. - -If a program is being written for general use, it is important to code -it carefully as shown in this second example. For quick-and-dirty programs, -when you know that your own use of the sine function will never encounter -a large argument, a simpler program like the first one shown is fine. - -@node Calling Calc from Your Programs, Internals, Example Definitions, Lisp Definitions -@subsection Calling Calc from Your Lisp Programs - -@noindent -A later section (@pxref{Internals}) gives a full description of -Calc's internal Lisp functions. It's not hard to call Calc from -inside your programs, but the number of these functions can be daunting. -So Calc provides one special ``programmer-friendly'' function called -@code{calc-eval} that can be made to do just about everything you -need. It's not as fast as the low-level Calc functions, but it's -much simpler to use! - -It may seem that @code{calc-eval} itself has a daunting number of -options, but they all stem from one simple operation. - -In its simplest manifestation, @samp{(calc-eval "1+2")} parses the -string @code{"1+2"} as if it were a Calc algebraic entry and returns -the result formatted as a string: @code{"3"}. - -Since @code{calc-eval} is on the list of recommended @code{autoload} -functions, you don't need to make any special preparations to load -Calc before calling @code{calc-eval} the first time. Calc will be -loaded and initialized for you. - -All the Calc modes that are currently in effect will be used when -evaluating the expression and formatting the result. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Additional Arguments to @code{calc-eval} - -@noindent -If the input string parses to a list of expressions, Calc returns -the results separated by @code{", "}. You can specify a different -separator by giving a second string argument to @code{calc-eval}: -@samp{(calc-eval "1+2,3+4" ";")} returns @code{"3;7"}. - -The ``separator'' can also be any of several Lisp symbols which -request other behaviors from @code{calc-eval}. These are discussed -one by one below. - -You can give additional arguments to be substituted for -@samp{$}, @samp{$$}, and so on in the main expression. For -example, @samp{(calc-eval "$/$$" nil "7" "1+1")} evaluates the -expression @code{"7/(1+1)"} to yield the result @code{"3.5"} -(assuming Fraction mode is not in effect). Note the @code{nil} -used as a placeholder for the item-separator argument. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Error Handling - -@noindent -If @code{calc-eval} encounters an error, it returns a list containing -the character position of the error, plus a suitable message as a -string. Note that @samp{1 / 0} is @emph{not} an error by Calc's -standards; it simply returns the string @code{"1 / 0"} which is the -division left in symbolic form. But @samp{(calc-eval "1/")} will -return the list @samp{(2 "Expected a number")}. - -If you bind the variable @code{calc-eval-error} to @code{t} -using a @code{let} form surrounding the call to @code{calc-eval}, -errors instead call the Emacs @code{error} function which aborts -to the Emacs command loop with a beep and an error message. - -If you bind this variable to the symbol @code{string}, error messages -are returned as strings instead of lists. The character position is -ignored. - -As a courtesy to other Lisp code which may be using Calc, be sure -to bind @code{calc-eval-error} using @code{let} rather than changing -it permanently with @code{setq}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Numbers Only - -@noindent -Sometimes it is preferable to treat @samp{1 / 0} as an error -rather than returning a symbolic result. If you pass the symbol -@code{num} as the second argument to @code{calc-eval}, results -that are not constants are treated as errors. The error message -reported is the first @code{calc-why} message if there is one, -or otherwise ``Number expected.'' - -A result is ``constant'' if it is a number, vector, or other -object that does not include variables or function calls. If it -is a vector, the components must themselves be constants. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Default Modes - -@noindent -If the first argument to @code{calc-eval} is a list whose first -element is a formula string, then @code{calc-eval} sets all the -various Calc modes to their default values while the formula is -evaluated and formatted. For example, the precision is set to 12 -digits, digit grouping is turned off, and the Normal language -mode is used. - -This same principle applies to the other options discussed below. -If the first argument would normally be @var{x}, then it can also -be the list @samp{(@var{x})} to use the default mode settings. - -If there are other elements in the list, they are taken as -variable-name/value pairs which override the default mode -settings. Look at the documentation at the front of the -@file{calc.el} file to find the names of the Lisp variables for -the various modes. The mode settings are restored to their -original values when @code{calc-eval} is done. - -For example, @samp{(calc-eval '("$+$$" calc-internal-prec 8) 'num a b)} -computes the sum of two numbers, requiring a numeric result, and -using default mode settings except that the precision is 8 instead -of the default of 12. - -It's usually best to use this form of @code{calc-eval} unless your -program actually considers the interaction with Calc's mode settings -to be a feature. This will avoid all sorts of potential ``gotchas''; -consider what happens with @samp{(calc-eval "sqrt(2)" 'num)} -when the user has left Calc in Symbolic mode or No-Simplify mode. - -As another example, @samp{(equal (calc-eval '("$<$$") nil a b) "1")} -checks if the number in string @expr{a} is less than the one in -string @expr{b}. Without using a list, the integer 1 might -come out in a variety of formats which would be hard to test for -conveniently: @code{"1"}, @code{"8#1"}, @code{"00001"}. (But -see ``Predicates'' mode, below.) - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Raw Numbers - -@noindent -Normally all input and output for @code{calc-eval} is done with strings. -You can do arithmetic with, say, @samp{(calc-eval "$+$$" nil a b)} -in place of @samp{(+ a b)}, but this is very inefficient since the -numbers must be converted to and from string format as they are passed -from one @code{calc-eval} to the next. - -If the separator is the symbol @code{raw}, the result will be returned -as a raw Calc data structure rather than a string. You can read about -how these objects look in the following sections, but usually you can -treat them as ``black box'' objects with no important internal -structure. - -There is also a @code{rawnum} symbol, which is a combination of -@code{raw} (returning a raw Calc object) and @code{num} (signaling -an error if that object is not a constant). - -You can pass a raw Calc object to @code{calc-eval} in place of a -string, either as the formula itself or as one of the @samp{$} -arguments. Thus @samp{(calc-eval "$+$$" 'raw a b)} is an -addition function that operates on raw Calc objects. Of course -in this case it would be easier to call the low-level @code{math-add} -function in Calc, if you can remember its name. - -In particular, note that a plain Lisp integer is acceptable to Calc -as a raw object. (All Lisp integers are accepted on input, but -integers of more than six decimal digits are converted to ``big-integer'' -form for output. @xref{Data Type Formats}.) - -When it comes time to display the object, just use @samp{(calc-eval a)} -to format it as a string. - -It is an error if the input expression evaluates to a list of -values. The separator symbol @code{list} is like @code{raw} -except that it returns a list of one or more raw Calc objects. - -Note that a Lisp string is not a valid Calc object, nor is a list -containing a string. Thus you can still safely distinguish all the -various kinds of error returns discussed above. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Predicates - -@noindent -If the separator symbol is @code{pred}, the result of the formula is -treated as a true/false value; @code{calc-eval} returns @code{t} or -@code{nil}, respectively. A value is considered ``true'' if it is a -non-zero number, or false if it is zero or if it is not a number. - -For example, @samp{(calc-eval "$<$$" 'pred a b)} tests whether -one value is less than another. - -As usual, it is also possible for @code{calc-eval} to return one of -the error indicators described above. Lisp will interpret such an -indicator as ``true'' if you don't check for it explicitly. If you -wish to have an error register as ``false'', use something like -@samp{(eq (calc-eval ...) t)}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Variable Values - -@noindent -Variables in the formula passed to @code{calc-eval} are not normally -replaced by their values. If you wish this, you can use the -@code{evalv} function (@pxref{Algebraic Manipulation}). For example, -if 4 is stored in Calc variable @code{a} (i.e., in Lisp variable -@code{var-a}), then @samp{(calc-eval "a+pi")} will return the -formula @code{"a + pi"}, but @samp{(calc-eval "evalv(a+pi)")} -will return @code{"7.14159265359"}. - -To store in a Calc variable, just use @code{setq} to store in the -corresponding Lisp variable. (This is obtained by prepending -@samp{var-} to the Calc variable name.) Calc routines will -understand either string or raw form values stored in variables, -although raw data objects are much more efficient. For example, -to increment the Calc variable @code{a}: - -@example -(setq var-a (calc-eval "evalv(a+1)" 'raw)) -@end example - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Stack Access - -@noindent -If the separator symbol is @code{push}, the formula argument is -evaluated (with possible @samp{$} expansions, as usual). The -result is pushed onto the Calc stack. The return value is @code{nil} -(unless there is an error from evaluating the formula, in which -case the return value depends on @code{calc-eval-error} in the -usual way). - -If the separator symbol is @code{pop}, the first argument to -@code{calc-eval} must be an integer instead of a string. That -many values are popped from the stack and thrown away. A negative -argument deletes the entry at that stack level. The return value -is the number of elements remaining in the stack after popping; -@samp{(calc-eval 0 'pop)} is a good way to measure the size of -the stack. - -If the separator symbol is @code{top}, the first argument to -@code{calc-eval} must again be an integer. The value at that -stack level is formatted as a string and returned. Thus -@samp{(calc-eval 1 'top)} returns the top-of-stack value. If the -integer is out of range, @code{nil} is returned. - -The separator symbol @code{rawtop} is just like @code{top} except -that the stack entry is returned as a raw Calc object instead of -as a string. - -In all of these cases the first argument can be made a list in -order to force the default mode settings, as described above. -Thus @samp{(calc-eval '(2 calc-number-radix 16) 'top)} returns the -second-to-top stack entry, formatted as a string using the default -instead of current display modes, except that the radix is -hexadecimal instead of decimal. - -It is, of course, polite to put the Calc stack back the way you -found it when you are done, unless the user of your program is -actually expecting it to affect the stack. - -Note that you do not actually have to switch into the @samp{*Calculator*} -buffer in order to use @code{calc-eval}; it temporarily switches into -the stack buffer if necessary. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Keyboard Macros - -@noindent -If the separator symbol is @code{macro}, the first argument must be a -string of characters which Calc can execute as a sequence of keystrokes. -This switches into the Calc buffer for the duration of the macro. -For example, @samp{(calc-eval "vx5\rVR+" 'macro)} pushes the -vector @samp{[1,2,3,4,5]} on the stack and then replaces it -with the sum of those numbers. Note that @samp{\r} is the Lisp -notation for the carriage-return, @key{RET}, character. - -If your keyboard macro wishes to pop the stack, @samp{\C-d} is -safer than @samp{\177} (the @key{DEL} character) because some -installations may have switched the meanings of @key{DEL} and -@kbd{C-h}. Calc always interprets @kbd{C-d} as a synonym for -``pop-stack'' regardless of key mapping. - -If you provide a third argument to @code{calc-eval}, evaluation -of the keyboard macro will leave a record in the Trail using -that argument as a tag string. Normally the Trail is unaffected. - -The return value in this case is always @code{nil}. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Lisp Evaluation - -@noindent -Finally, if the separator symbol is @code{eval}, then the Lisp -@code{eval} function is called on the first argument, which must -be a Lisp expression rather than a Calc formula. Remember to -quote the expression so that it is not evaluated until inside -@code{calc-eval}. - -The difference from plain @code{eval} is that @code{calc-eval} -switches to the Calc buffer before evaluating the expression. -For example, @samp{(calc-eval '(setq calc-internal-prec 17) 'eval)} -will correctly affect the buffer-local Calc precision variable. - -An alternative would be @samp{(calc-eval '(calc-precision 17) 'eval)}. -This is evaluating a call to the function that is normally invoked -by the @kbd{p} key, giving it 17 as its ``numeric prefix argument.'' -Note that this function will leave a message in the echo area as -a side effect. Also, all Calc functions switch to the Calc buffer -automatically if not invoked from there, so the above call is -also equivalent to @samp{(calc-precision 17)} by itself. -In all cases, Calc uses @code{save-excursion} to switch back to -your original buffer when it is done. - -As usual the first argument can be a list that begins with a Lisp -expression to use default instead of current mode settings. - -The result of @code{calc-eval} in this usage is just the result -returned by the evaluated Lisp expression. - -@ifinfo -@example - -@end example -@end ifinfo -@subsubsection Example - -@noindent -@findex convert-temp -Here is a sample Emacs command that uses @code{calc-eval}. Suppose -you have a document with lots of references to temperatures on the -Fahrenheit scale, say ``98.6 F'', and you wish to convert these -references to Centigrade. The following command does this conversion. -Place the Emacs cursor right after the letter ``F'' and invoke the -command to change ``98.6 F'' to ``37 C''. Or, if the temperature is -already in Centigrade form, the command changes it back to Fahrenheit. - -@example -(defun convert-temp () - (interactive) - (save-excursion - (re-search-backward "[^-.0-9]\\([-.0-9]+\\) *\\([FC]\\)") - (let* ((top1 (match-beginning 1)) - (bot1 (match-end 1)) - (number (buffer-substring top1 bot1)) - (top2 (match-beginning 2)) - (bot2 (match-end 2)) - (type (buffer-substring top2 bot2))) - (if (equal type "F") - (setq type "C" - number (calc-eval "($ - 32)*5/9" nil number)) - (setq type "F" - number (calc-eval "$*9/5 + 32" nil number))) - (goto-char top2) - (delete-region top2 bot2) - (insert-before-markers type) - (goto-char top1) - (delete-region top1 bot1) - (if (string-match "\\.$" number) ; change "37." to "37" - (setq number (substring number 0 -1))) - (insert number)))) -@end example - -Note the use of @code{insert-before-markers} when changing between -``F'' and ``C'', so that the character winds up before the cursor -instead of after it. - -@node Internals, , Calling Calc from Your Programs, Lisp Definitions -@subsection Calculator Internals - -@noindent -This section describes the Lisp functions defined by the Calculator that -may be of use to user-written Calculator programs (as described in the -rest of this chapter). These functions are shown by their names as they -conventionally appear in @code{defmath}. Their full Lisp names are -generally gotten by prepending @samp{calcFunc-} or @samp{math-} to their -apparent names. (Names that begin with @samp{calc-} are already in -their full Lisp form.) You can use the actual full names instead if you -prefer them, or if you are calling these functions from regular Lisp. - -The functions described here are scattered throughout the various -Calc component files. Note that @file{calc.el} includes @code{autoload}s -for only a few component files; when Calc wants to call an advanced -function it calls @samp{(calc-extensions)} first; this function -autoloads @file{calc-ext.el}, which in turn autoloads all the functions -in the remaining component files. - -Because @code{defmath} itself uses the extensions, user-written code -generally always executes with the extensions already loaded, so -normally you can use any Calc function and be confident that it will -be autoloaded for you when necessary. If you are doing something -special, check carefully to make sure each function you are using is -from @file{calc.el} or its components, and call @samp{(calc-extensions)} -before using any function based in @file{calc-ext.el} if you can't -prove this file will already be loaded. - -@menu -* Data Type Formats:: -* Interactive Lisp Functions:: -* Stack Lisp Functions:: -* Predicates:: -* Computational Lisp Functions:: -* Vector Lisp Functions:: -* Symbolic Lisp Functions:: -* Formatting Lisp Functions:: -* Hooks:: -@end menu - -@node Data Type Formats, Interactive Lisp Functions, Internals, Internals -@subsubsection Data Type Formats - -@noindent -Integers are stored in either of two ways, depending on their magnitude. -Integers less than one million in absolute value are stored as standard -Lisp integers. This is the only storage format for Calc data objects -which is not a Lisp list. - -Large integers are stored as lists of the form @samp{(bigpos @var{d0} -@var{d1} @var{d2} @dots{})} for positive integers 1000000 or more, or -@samp{(bigneg @var{d0} @var{d1} @var{d2} @dots{})} for negative integers -@mathit{-1000000} or less. Each @var{d} is a base-1000 ``digit,'' a Lisp integer -from 0 to 999. The least significant digit is @var{d0}; the last digit, -@var{dn}, which is always nonzero, is the most significant digit. For -example, the integer @mathit{-12345678} is stored as @samp{(bigneg 678 345 12)}. - -The distinction between small and large integers is entirely hidden from -the user. In @code{defmath} definitions, the Lisp predicate @code{integerp} -returns true for either kind of integer, and in general both big and small -integers are accepted anywhere the word ``integer'' is used in this manual. -If the distinction must be made, native Lisp integers are called @dfn{fixnums} -and large integers are called @dfn{bignums}. - -Fractions are stored as a list of the form, @samp{(frac @var{n} @var{d})} -where @var{n} is an integer (big or small) numerator, @var{d} is an -integer denominator greater than one, and @var{n} and @var{d} are relatively -prime. Note that fractions where @var{d} is one are automatically converted -to plain integers by all math routines; fractions where @var{d} is negative -are normalized by negating the numerator and denominator. - -Floating-point numbers are stored in the form, @samp{(float @var{mant} -@var{exp})}, where @var{mant} (the ``mantissa'') is an integer less than -@samp{10^@var{p}} in absolute value (@var{p} represents the current -precision), and @var{exp} (the ``exponent'') is a fixnum. The value of -the float is @samp{@var{mant} * 10^@var{exp}}. For example, the number -@mathit{-3.14} is stored as @samp{(float -314 -2) = -314*10^-2}. Other constraints -are that the number 0.0 is always stored as @samp{(float 0 0)}, and, -except for the 0.0 case, the rightmost base-10 digit of @var{mant} is -always nonzero. (If the rightmost digit is zero, the number is -rearranged by dividing @var{mant} by ten and incrementing @var{exp}.) - -Rectangular complex numbers are stored in the form @samp{(cplx @var{re} -@var{im})}, where @var{re} and @var{im} are each real numbers, either -integers, fractions, or floats. The value is @samp{@var{re} + @var{im}i}. -The @var{im} part is nonzero; complex numbers with zero imaginary -components are converted to real numbers automatically. - -Polar complex numbers are stored in the form @samp{(polar @var{r} -@var{theta})}, where @var{r} is a positive real value and @var{theta} -is a real value or HMS form representing an angle. This angle is -usually normalized to lie in the interval @samp{(-180 ..@: 180)} degrees, -or @samp{(-pi ..@: pi)} radians, according to the current angular mode. -If the angle is 0 the value is converted to a real number automatically. -(If the angle is 180 degrees, the value is usually also converted to a -negative real number.) - -Hours-minutes-seconds forms are stored as @samp{(hms @var{h} @var{m} -@var{s})}, where @var{h} is an integer or an integer-valued float (i.e., -a float with @samp{@var{exp} >= 0}), @var{m} is an integer or integer-valued -float in the range @w{@samp{[0 ..@: 60)}}, and @var{s} is any real number -in the range @samp{[0 ..@: 60)}. - -Date forms are stored as @samp{(date @var{n})}, where @var{n} is -a real number that counts days since midnight on the morning of -January 1, 1 AD. If @var{n} is an integer, this is a pure date -form. If @var{n} is a fraction or float, this is a date/time form. - -Modulo forms are stored as @samp{(mod @var{n} @var{m})}, where @var{m} is a -positive real number or HMS form, and @var{n} is a real number or HMS -form in the range @samp{[0 ..@: @var{m})}. - -Error forms are stored as @samp{(sdev @var{x} @var{sigma})}, where @var{x} -is the mean value and @var{sigma} is the standard deviation. Each -component is either a number, an HMS form, or a symbolic object -(a variable or function call). If @var{sigma} is zero, the value is -converted to a plain real number. If @var{sigma} is negative or -complex, it is automatically normalized to be a positive real. - -Interval forms are stored as @samp{(intv @var{mask} @var{lo} @var{hi})}, -where @var{mask} is one of the integers 0, 1, 2, or 3, and @var{lo} and -@var{hi} are real numbers, HMS forms, or symbolic objects. The @var{mask} -is a binary integer where 1 represents the fact that the interval is -closed on the high end, and 2 represents the fact that it is closed on -the low end. (Thus 3 represents a fully closed interval.) The interval -@w{@samp{(intv 3 @var{x} @var{x})}} is converted to the plain number @var{x}; -intervals @samp{(intv @var{mask} @var{x} @var{x})} for any other @var{mask} -represent empty intervals. If @var{hi} is less than @var{lo}, the interval -is converted to a standard empty interval by replacing @var{hi} with @var{lo}. - -Vectors are stored as @samp{(vec @var{v1} @var{v2} @dots{})}, where @var{v1} -is the first element of the vector, @var{v2} is the second, and so on. -An empty vector is stored as @samp{(vec)}. A matrix is simply a vector -where all @var{v}'s are themselves vectors of equal lengths. Note that -Calc vectors are unrelated to the Emacs Lisp ``vector'' type, which is -generally unused by Calc data structures. - -Variables are stored as @samp{(var @var{name} @var{sym})}, where -@var{name} is a Lisp symbol whose print name is used as the visible name -of the variable, and @var{sym} is a Lisp symbol in which the variable's -value is actually stored. Thus, @samp{(var pi var-pi)} represents the -special constant @samp{pi}. Almost always, the form is @samp{(var -@var{v} var-@var{v})}. If the variable name was entered with @code{#} -signs (which are converted to hyphens internally), the form is -@samp{(var @var{u} @var{v})}, where @var{u} is a symbol whose name -contains @code{#} characters, and @var{v} is a symbol that contains -@code{-} characters instead. The value of a variable is the Calc -object stored in its @var{sym} symbol's value cell. If the symbol's -value cell is void or if it contains @code{nil}, the variable has no -value. Special constants have the form @samp{(special-const -@var{value})} stored in their value cell, where @var{value} is a formula -which is evaluated when the constant's value is requested. Variables -which represent units are not stored in any special way; they are units -only because their names appear in the units table. If the value -cell contains a string, it is parsed to get the variable's value when -the variable is used. - -A Lisp list with any other symbol as the first element is a function call. -The symbols @code{+}, @code{-}, @code{*}, @code{/}, @code{%}, @code{^}, -and @code{|} represent special binary operators; these lists are always -of the form @samp{(@var{op} @var{lhs} @var{rhs})} where @var{lhs} is the -sub-formula on the lefthand side and @var{rhs} is the sub-formula on the -right. The symbol @code{neg} represents unary negation; this list is always -of the form @samp{(neg @var{arg})}. Any other symbol @var{func} represents a -function that would be displayed in function-call notation; the symbol -@var{func} is in general always of the form @samp{calcFunc-@var{name}}. -The function cell of the symbol @var{func} should contain a Lisp function -for evaluating a call to @var{func}. This function is passed the remaining -elements of the list (themselves already evaluated) as arguments; such -functions should return @code{nil} or call @code{reject-arg} to signify -that they should be left in symbolic form, or they should return a Calc -object which represents their value, or a list of such objects if they -wish to return multiple values. (The latter case is allowed only for -functions which are the outer-level call in an expression whose value is -about to be pushed on the stack; this feature is considered obsolete -and is not used by any built-in Calc functions.) - -@node Interactive Lisp Functions, Stack Lisp Functions, Data Type Formats, Internals -@subsubsection Interactive Functions - -@noindent -The functions described here are used in implementing interactive Calc -commands. Note that this list is not exhaustive! If there is an -existing command that behaves similarly to the one you want to define, -you may find helpful tricks by checking the source code for that command. - -@defun calc-set-command-flag flag -Set the command flag @var{flag}. This is generally a Lisp symbol, but -may in fact be anything. The effect is to add @var{flag} to the list -stored in the variable @code{calc-command-flags}, unless it is already -there. @xref{Defining Simple Commands}. -@end defun - -@defun calc-clear-command-flag flag -If @var{flag} appears among the list of currently-set command flags, -remove it from that list. -@end defun - -@defun calc-record-undo rec -Add the ``undo record'' @var{rec} to the list of steps to take if the -current operation should need to be undone. Stack push and pop functions -automatically call @code{calc-record-undo}, so the kinds of undo records -you might need to create take the form @samp{(set @var{sym} @var{value})}, -which says that the Lisp variable @var{sym} was changed and had previously -contained @var{value}; @samp{(store @var{var} @var{value})} which says that -the Calc variable @var{var} (a string which is the name of the symbol that -contains the variable's value) was stored and its previous value was -@var{value} (either a Calc data object, or @code{nil} if the variable was -previously void); or @samp{(eval @var{undo} @var{redo} @var{args} @dots{})}, -which means that to undo requires calling the function @samp{(@var{undo} -@var{args} @dots{})} and, if the undo is later redone, calling -@samp{(@var{redo} @var{args} @dots{})}. -@end defun - -@defun calc-record-why msg args -Record the error or warning message @var{msg}, which is normally a string. -This message will be replayed if the user types @kbd{w} (@code{calc-why}); -if the message string begins with a @samp{*}, it is considered important -enough to display even if the user doesn't type @kbd{w}. If one or more -@var{args} are present, the displayed message will be of the form, -@samp{@var{msg}: @var{arg1}, @var{arg2}, @dots{}}, where the arguments are -formatted on the assumption that they are either strings or Calc objects of -some sort. If @var{msg} is a symbol, it is the name of a Calc predicate -(such as @code{integerp} or @code{numvecp}) which the arguments did not -satisfy; it is expanded to a suitable string such as ``Expected an -integer.'' The @code{reject-arg} function calls @code{calc-record-why} -automatically; @pxref{Predicates}. -@end defun - -@defun calc-is-inverse -This predicate returns true if the current command is inverse, -i.e., if the Inverse (@kbd{I} key) flag was set. -@end defun - -@defun calc-is-hyperbolic -This predicate is the analogous function for the @kbd{H} key. -@end defun - -@node Stack Lisp Functions, Predicates, Interactive Lisp Functions, Internals -@subsubsection Stack-Oriented Functions - -@noindent -The functions described here perform various operations on the Calc -stack and trail. They are to be used in interactive Calc commands. - -@defun calc-push-list vals n -Push the Calc objects in list @var{vals} onto the stack at stack level -@var{n}. If @var{n} is omitted it defaults to 1, so that the elements -are pushed at the top of the stack. If @var{n} is greater than 1, the -elements will be inserted into the stack so that the last element will -end up at level @var{n}, the next-to-last at level @var{n}+1, etc. -The elements of @var{vals} are assumed to be valid Calc objects, and -are not evaluated, rounded, or renormalized in any way. If @var{vals} -is an empty list, nothing happens. - -The stack elements are pushed without any sub-formula selections. -You can give an optional third argument to this function, which must -be a list the same size as @var{vals} of selections. Each selection -must be @code{eq} to some sub-formula of the corresponding formula -in @var{vals}, or @code{nil} if that formula should have no selection. -@end defun - -@defun calc-top-list n m -Return a list of the @var{n} objects starting at level @var{m} of the -stack. If @var{m} is omitted it defaults to 1, so that the elements are -taken from the top of the stack. If @var{n} is omitted, it also -defaults to 1, so that the top stack element (in the form of a -one-element list) is returned. If @var{m} is greater than 1, the -@var{m}th stack element will be at the end of the list, the @var{m}+1st -element will be next-to-last, etc. If @var{n} or @var{m} are out of -range, the command is aborted with a suitable error message. If @var{n} -is zero, the function returns an empty list. The stack elements are not -evaluated, rounded, or renormalized. - -If any stack elements contain selections, and selections have not -been disabled by the @kbd{j e} (@code{calc-enable-selections}) command, -this function returns the selected portions rather than the entire -stack elements. It can be given a third ``selection-mode'' argument -which selects other behaviors. If it is the symbol @code{t}, then -a selection in any of the requested stack elements produces an -``invalid operation on selections'' error. If it is the symbol @code{full}, -the whole stack entry is always returned regardless of selections. -If it is the symbol @code{sel}, the selected portion is always returned, -or @code{nil} if there is no selection. (This mode ignores the @kbd{j e} -command.) If the symbol is @code{entry}, the complete stack entry in -list form is returned; the first element of this list will be the whole -formula, and the third element will be the selection (or @code{nil}). -@end defun - -@defun calc-pop-stack n m -Remove the specified elements from the stack. The parameters @var{n} -and @var{m} are defined the same as for @code{calc-top-list}. The return -value of @code{calc-pop-stack} is uninteresting. - -If there are any selected sub-formulas among the popped elements, and -@kbd{j e} has not been used to disable selections, this produces an -error without changing the stack. If you supply an optional third -argument of @code{t}, the stack elements are popped even if they -contain selections. -@end defun - -@defun calc-record-list vals tag -This function records one or more results in the trail. The @var{vals} -are a list of strings or Calc objects. The @var{tag} is the four-character -tag string to identify the values. If @var{tag} is omitted, a blank tag -will be used. -@end defun - -@defun calc-normalize n -This function takes a Calc object and ``normalizes'' it. At the very -least this involves re-rounding floating-point values according to the -current precision and other similar jobs. Also, unless the user has -selected No-Simplify mode (@pxref{Simplification Modes}), this involves -actually evaluating a formula object by executing the function calls -it contains, and possibly also doing algebraic simplification, etc. -@end defun - -@defun calc-top-list-n n m -This function is identical to @code{calc-top-list}, except that it calls -@code{calc-normalize} on the values that it takes from the stack. They -are also passed through @code{check-complete}, so that incomplete -objects will be rejected with an error message. All computational -commands should use this in preference to @code{calc-top-list}; the only -standard Calc commands that operate on the stack without normalizing -are stack management commands like @code{calc-enter} and @code{calc-roll-up}. -This function accepts the same optional selection-mode argument as -@code{calc-top-list}. -@end defun - -@defun calc-top-n m -This function is a convenient form of @code{calc-top-list-n} in which only -a single element of the stack is taken and returned, rather than a list -of elements. This also accepts an optional selection-mode argument. -@end defun - -@defun calc-enter-result n tag vals -This function is a convenient interface to most of the above functions. -The @var{vals} argument should be either a single Calc object, or a list -of Calc objects; the object or objects are normalized, and the top @var{n} -stack entries are replaced by the normalized objects. If @var{tag} is -non-@code{nil}, the normalized objects are also recorded in the trail. -A typical stack-based computational command would take the form, - -@smallexample -(calc-enter-result @var{n} @var{tag} (cons 'calcFunc-@var{func} - (calc-top-list-n @var{n}))) -@end smallexample - -If any of the @var{n} stack elements replaced contain sub-formula -selections, and selections have not been disabled by @kbd{j e}, -this function takes one of two courses of action. If @var{n} is -equal to the number of elements in @var{vals}, then each element of -@var{vals} is spliced into the corresponding selection; this is what -happens when you use the @key{TAB} key, or when you use a unary -arithmetic operation like @code{sqrt}. If @var{vals} has only one -element but @var{n} is greater than one, there must be only one -selection among the top @var{n} stack elements; the element from -@var{vals} is spliced into that selection. This is what happens when -you use a binary arithmetic operation like @kbd{+}. Any other -combination of @var{n} and @var{vals} is an error when selections -are present. -@end defun - -@defun calc-unary-op tag func arg -This function implements a unary operator that allows a numeric prefix -argument to apply the operator over many stack entries. If the prefix -argument @var{arg} is @code{nil}, this uses @code{calc-enter-result} -as outlined above. Otherwise, it maps the function over several stack -elements; @pxref{Prefix Arguments}. For example, - -@smallexample -(defun calc-zeta (arg) - (interactive "P") - (calc-unary-op "zeta" 'calcFunc-zeta arg)) -@end smallexample -@end defun - -@defun calc-binary-op tag func arg ident unary -This function implements a binary operator, analogously to -@code{calc-unary-op}. The optional @var{ident} and @var{unary} -arguments specify the behavior when the prefix argument is zero or -one, respectively. If the prefix is zero, the value @var{ident} -is pushed onto the stack, if specified, otherwise an error message -is displayed. If the prefix is one, the unary function @var{unary} -is applied to the top stack element, or, if @var{unary} is not -specified, nothing happens. When the argument is two or more, -the binary function @var{func} is reduced across the top @var{arg} -stack elements; when the argument is negative, the function is -mapped between the next-to-top @mathit{-@var{arg}} stack elements and the -top element. -@end defun - -@defun calc-stack-size -Return the number of elements on the stack as an integer. This count -does not include elements that have been temporarily hidden by stack -truncation; @pxref{Truncating the Stack}. -@end defun - -@defun calc-cursor-stack-index n -Move the point to the @var{n}th stack entry. If @var{n} is zero, this -will be the @samp{.} line. If @var{n} is from 1 to the current stack size, -this will be the beginning of the first line of that stack entry's display. -If line numbers are enabled, this will move to the first character of the -line number, not the stack entry itself. -@end defun - -@defun calc-substack-height n -Return the number of lines between the beginning of the @var{n}th stack -entry and the bottom of the buffer. If @var{n} is zero, this -will be one (assuming no stack truncation). If all stack entries are -one line long (i.e., no matrices are displayed), the return value will -be equal @var{n}+1 as long as @var{n} is in range. (Note that in Big -mode, the return value includes the blank lines that separate stack -entries.) -@end defun - -@defun calc-refresh -Erase the @code{*Calculator*} buffer and reformat its contents from memory. -This must be called after changing any parameter, such as the current -display radix, which might change the appearance of existing stack -entries. (During a keyboard macro invoked by the @kbd{X} key, refreshing -is suppressed, but a flag is set so that the entire stack will be refreshed -rather than just the top few elements when the macro finishes.) -@end defun - -@node Predicates, Computational Lisp Functions, Stack Lisp Functions, Internals -@subsubsection Predicates - -@noindent -The functions described here are predicates, that is, they return a -true/false value where @code{nil} means false and anything else means -true. These predicates are expanded by @code{defmath}, for example, -from @code{zerop} to @code{math-zerop}. In many cases they correspond -to native Lisp functions by the same name, but are extended to cover -the full range of Calc data types. - -@defun zerop x -Returns true if @var{x} is numerically zero, in any of the Calc data -types. (Note that for some types, such as error forms and intervals, -it never makes sense to return true.) In @code{defmath}, the expression -@samp{(= x 0)} will automatically be converted to @samp{(math-zerop x)}, -and @samp{(/= x 0)} will be converted to @samp{(not (math-zerop x))}. -@end defun - -@defun negp x -Returns true if @var{x} is negative. This accepts negative real numbers -of various types, negative HMS and date forms, and intervals in which -all included values are negative. In @code{defmath}, the expression -@samp{(< x 0)} will automatically be converted to @samp{(math-negp x)}, -and @samp{(>= x 0)} will be converted to @samp{(not (math-negp x))}. -@end defun - -@defun posp x -Returns true if @var{x} is positive (and non-zero). For complex -numbers, none of these three predicates will return true. -@end defun - -@defun looks-negp x -Returns true if @var{x} is ``negative-looking.'' This returns true if -@var{x} is a negative number, or a formula with a leading minus sign -such as @samp{-a/b}. In other words, this is an object which can be -made simpler by calling @code{(- @var{x})}. -@end defun - -@defun integerp x -Returns true if @var{x} is an integer of any size. -@end defun - -@defun fixnump x -Returns true if @var{x} is a native Lisp integer. -@end defun - -@defun natnump x -Returns true if @var{x} is a nonnegative integer of any size. -@end defun - -@defun fixnatnump x -Returns true if @var{x} is a nonnegative Lisp integer. -@end defun - -@defun num-integerp x -Returns true if @var{x} is numerically an integer, i.e., either a -true integer or a float with no significant digits to the right of -the decimal point. -@end defun - -@defun messy-integerp x -Returns true if @var{x} is numerically, but not literally, an integer. -A value is @code{num-integerp} if it is @code{integerp} or -@code{messy-integerp} (but it is never both at once). -@end defun - -@defun num-natnump x -Returns true if @var{x} is numerically a nonnegative integer. -@end defun - -@defun evenp x -Returns true if @var{x} is an even integer. -@end defun - -@defun looks-evenp x -Returns true if @var{x} is an even integer, or a formula with a leading -multiplicative coefficient which is an even integer. -@end defun - -@defun oddp x -Returns true if @var{x} is an odd integer. -@end defun - -@defun ratp x -Returns true if @var{x} is a rational number, i.e., an integer or a -fraction. -@end defun - -@defun realp x -Returns true if @var{x} is a real number, i.e., an integer, fraction, -or floating-point number. -@end defun - -@defun anglep x -Returns true if @var{x} is a real number or HMS form. -@end defun - -@defun floatp x -Returns true if @var{x} is a float, or a complex number, error form, -interval, date form, or modulo form in which at least one component -is a float. -@end defun - -@defun complexp x -Returns true if @var{x} is a rectangular or polar complex number -(but not a real number). -@end defun - -@defun rect-complexp x -Returns true if @var{x} is a rectangular complex number. -@end defun - -@defun polar-complexp x -Returns true if @var{x} is a polar complex number. -@end defun - -@defun numberp x -Returns true if @var{x} is a real number or a complex number. -@end defun - -@defun scalarp x -Returns true if @var{x} is a real or complex number or an HMS form. -@end defun - -@defun vectorp x -Returns true if @var{x} is a vector (this simply checks if its argument -is a list whose first element is the symbol @code{vec}). -@end defun - -@defun numvecp x -Returns true if @var{x} is a number or vector. -@end defun - -@defun matrixp x -Returns true if @var{x} is a matrix, i.e., a vector of one or more vectors, -all of the same size. -@end defun - -@defun square-matrixp x -Returns true if @var{x} is a square matrix. -@end defun - -@defun objectp x -Returns true if @var{x} is any numeric Calc object, including real and -complex numbers, HMS forms, date forms, error forms, intervals, and -modulo forms. (Note that error forms and intervals may include formulas -as their components; see @code{constp} below.) -@end defun - -@defun objvecp x -Returns true if @var{x} is an object or a vector. This also accepts -incomplete objects, but it rejects variables and formulas (except as -mentioned above for @code{objectp}). -@end defun - -@defun primp x -Returns true if @var{x} is a ``primitive'' or ``atomic'' Calc object, -i.e., one whose components cannot be regarded as sub-formulas. This -includes variables, and all @code{objectp} types except error forms -and intervals. -@end defun - -@defun constp x -Returns true if @var{x} is constant, i.e., a real or complex number, -HMS form, date form, or error form, interval, or vector all of whose -components are @code{constp}. -@end defun - -@defun lessp x y -Returns true if @var{x} is numerically less than @var{y}. Returns false -if @var{x} is greater than or equal to @var{y}, or if the order is -undefined or cannot be determined. Generally speaking, this works -by checking whether @samp{@var{x} - @var{y}} is @code{negp}. In -@code{defmath}, the expression @samp{(< x y)} will automatically be -converted to @samp{(lessp x y)}; expressions involving @code{>}, @code{<=}, -and @code{>=} are similarly converted in terms of @code{lessp}. -@end defun - -@defun beforep x y -Returns true if @var{x} comes before @var{y} in a canonical ordering -of Calc objects. If @var{x} and @var{y} are both real numbers, this -will be the same as @code{lessp}. But whereas @code{lessp} considers -other types of objects to be unordered, @code{beforep} puts any two -objects into a definite, consistent order. The @code{beforep} -function is used by the @kbd{V S} vector-sorting command, and also -by @kbd{a s} to put the terms of a product into canonical order: -This allows @samp{x y + y x} to be simplified easily to @samp{2 x y}. -@end defun - -@defun equal x y -This is the standard Lisp @code{equal} predicate; it returns true if -@var{x} and @var{y} are structurally identical. This is the usual way -to compare numbers for equality, but note that @code{equal} will treat -0 and 0.0 as different. -@end defun - -@defun math-equal x y -Returns true if @var{x} and @var{y} are numerically equal, either because -they are @code{equal}, or because their difference is @code{zerop}. In -@code{defmath}, the expression @samp{(= x y)} will automatically be -converted to @samp{(math-equal x y)}. -@end defun - -@defun equal-int x n -Returns true if @var{x} and @var{n} are numerically equal, where @var{n} -is a fixnum which is not a multiple of 10. This will automatically be -used by @code{defmath} in place of the more general @code{math-equal} -whenever possible. -@end defun - -@defun nearly-equal x y -Returns true if @var{x} and @var{y}, as floating-point numbers, are -equal except possibly in the last decimal place. For example, -314.159 and 314.166 are considered nearly equal if the current -precision is 6 (since they differ by 7 units), but not if the current -precision is 7 (since they differ by 70 units). Most functions which -use series expansions use @code{with-extra-prec} to evaluate the -series with 2 extra digits of precision, then use @code{nearly-equal} -to decide when the series has converged; this guards against cumulative -error in the series evaluation without doing extra work which would be -lost when the result is rounded back down to the current precision. -In @code{defmath}, this can be written @samp{(~= @var{x} @var{y})}. -The @var{x} and @var{y} can be numbers of any kind, including complex. -@end defun - -@defun nearly-zerop x y -Returns true if @var{x} is nearly zero, compared to @var{y}. This -checks whether @var{x} plus @var{y} would by be @code{nearly-equal} -to @var{y} itself, to within the current precision, in other words, -if adding @var{x} to @var{y} would have a negligible effect on @var{y} -due to roundoff error. @var{X} may be a real or complex number, but -@var{y} must be real. -@end defun - -@defun is-true x -Return true if the formula @var{x} represents a true value in -Calc, not Lisp, terms. It tests if @var{x} is a non-zero number -or a provably non-zero formula. -@end defun - -@defun reject-arg val pred -Abort the current function evaluation due to unacceptable argument values. -This calls @samp{(calc-record-why @var{pred} @var{val})}, then signals a -Lisp error which @code{normalize} will trap. The net effect is that the -function call which led here will be left in symbolic form. -@end defun - -@defun inexact-value -If Symbolic mode is enabled, this will signal an error that causes -@code{normalize} to leave the formula in symbolic form, with the message -``Inexact result.'' (This function has no effect when not in Symbolic mode.) -Note that if your function calls @samp{(sin 5)} in Symbolic mode, the -@code{sin} function will call @code{inexact-value}, which will cause your -function to be left unsimplified. You may instead wish to call -@samp{(normalize (list 'calcFunc-sin 5))}, which in Symbolic mode will -return the formula @samp{sin(5)} to your function. -@end defun - -@defun overflow -This signals an error that will be reported as a floating-point overflow. -@end defun - -@defun underflow -This signals a floating-point underflow. -@end defun - -@node Computational Lisp Functions, Vector Lisp Functions, Predicates, Internals -@subsubsection Computational Functions - -@noindent -The functions described here do the actual computational work of the -Calculator. In addition to these, note that any function described in -the main body of this manual may be called from Lisp; for example, if -the documentation refers to the @code{calc-sqrt} [@code{sqrt}] command, -this means @code{calc-sqrt} is an interactive stack-based square-root -command and @code{sqrt} (which @code{defmath} expands to @code{calcFunc-sqrt}) -is the actual Lisp function for taking square roots. - -The functions @code{math-add}, @code{math-sub}, @code{math-mul}, -@code{math-div}, @code{math-mod}, and @code{math-neg} are not included -in this list, since @code{defmath} allows you to write native Lisp -@code{+}, @code{-}, @code{*}, @code{/}, @code{%}, and unary @code{-}, -respectively, instead. - -@defun normalize val -(Full form: @code{math-normalize}.) -Reduce the value @var{val} to standard form. For example, if @var{val} -is a fixnum, it will be converted to a bignum if it is too large, and -if @var{val} is a bignum it will be normalized by clipping off trailing -(i.e., most-significant) zero digits and converting to a fixnum if it is -small. All the various data types are similarly converted to their standard -forms. Variables are left alone, but function calls are actually evaluated -in formulas. For example, normalizing @samp{(+ 2 (calcFunc-abs -4))} will -return 6. - -If a function call fails, because the function is void or has the wrong -number of parameters, or because it returns @code{nil} or calls -@code{reject-arg} or @code{inexact-result}, @code{normalize} returns -the formula still in symbolic form. - -If the current simplification mode is ``none'' or ``numeric arguments -only,'' @code{normalize} will act appropriately. However, the more -powerful simplification modes (like Algebraic Simplification) are -not handled by @code{normalize}. They are handled by @code{calc-normalize}, -which calls @code{normalize} and possibly some other routines, such -as @code{simplify} or @code{simplify-units}. Programs generally will -never call @code{calc-normalize} except when popping or pushing values -on the stack. -@end defun - -@defun evaluate-expr expr -Replace all variables in @var{expr} that have values with their values, -then use @code{normalize} to simplify the result. This is what happens -when you press the @kbd{=} key interactively. -@end defun - -@defmac with-extra-prec n body -Evaluate the Lisp forms in @var{body} with precision increased by @var{n} -digits. This is a macro which expands to - -@smallexample -(math-normalize - (let ((calc-internal-prec (+ calc-internal-prec @var{n}))) - @var{body})) -@end smallexample - -The surrounding call to @code{math-normalize} causes a floating-point -result to be rounded down to the original precision afterwards. This -is important because some arithmetic operations assume a number's -mantissa contains no more digits than the current precision allows. -@end defmac - -@defun make-frac n d -Build a fraction @samp{@var{n}:@var{d}}. This is equivalent to calling -@samp{(normalize (list 'frac @var{n} @var{d}))}, but more efficient. -@end defun - -@defun make-float mant exp -Build a floating-point value out of @var{mant} and @var{exp}, both -of which are arbitrary integers. This function will return a -properly normalized float value, or signal an overflow or underflow -if @var{exp} is out of range. -@end defun - -@defun make-sdev x sigma -Build an error form out of @var{x} and the absolute value of @var{sigma}. -If @var{sigma} is zero, the result is the number @var{x} directly. -If @var{sigma} is negative or complex, its absolute value is used. -If @var{x} or @var{sigma} is not a valid type of object for use in -error forms, this calls @code{reject-arg}. -@end defun - -@defun make-intv mask lo hi -Build an interval form out of @var{mask} (which is assumed to be an -integer from 0 to 3), and the limits @var{lo} and @var{hi}. If -@var{lo} is greater than @var{hi}, an empty interval form is returned. -This calls @code{reject-arg} if @var{lo} or @var{hi} is unsuitable. -@end defun - -@defun sort-intv mask lo hi -Build an interval form, similar to @code{make-intv}, except that if -@var{lo} is less than @var{hi} they are simply exchanged, and the -bits of @var{mask} are swapped accordingly. -@end defun - -@defun make-mod n m -Build a modulo form out of @var{n} and the modulus @var{m}. Since modulo -forms do not allow formulas as their components, if @var{n} or @var{m} -is not a real number or HMS form the result will be a formula which -is a call to @code{makemod}, the algebraic version of this function. -@end defun - -@defun float x -Convert @var{x} to floating-point form. Integers and fractions are -converted to numerically equivalent floats; components of complex -numbers, vectors, HMS forms, date forms, error forms, intervals, and -modulo forms are recursively floated. If the argument is a variable -or formula, this calls @code{reject-arg}. -@end defun - -@defun compare x y -Compare the numbers @var{x} and @var{y}, and return @mathit{-1} if -@samp{(lessp @var{x} @var{y})}, 1 if @samp{(lessp @var{y} @var{x})}, -0 if @samp{(math-equal @var{x} @var{y})}, or 2 if the order is -undefined or cannot be determined. -@end defun - -@defun numdigs n -Return the number of digits of integer @var{n}, effectively -@samp{ceil(log10(@var{n}))}, but much more efficient. Zero is -considered to have zero digits. -@end defun - -@defun scale-int x n -Shift integer @var{x} left @var{n} decimal digits, or right @mathit{-@var{n}} -digits with truncation toward zero. -@end defun - -@defun scale-rounding x n -Like @code{scale-int}, except that a right shift rounds to the nearest -integer rather than truncating. -@end defun - -@defun fixnum n -Return the integer @var{n} as a fixnum, i.e., a native Lisp integer. -If @var{n} is outside the permissible range for Lisp integers (usually -24 binary bits) the result is undefined. -@end defun - -@defun sqr x -Compute the square of @var{x}; short for @samp{(* @var{x} @var{x})}. -@end defun - -@defun quotient x y -Divide integer @var{x} by integer @var{y}; return an integer quotient -and discard the remainder. If @var{x} or @var{y} is negative, the -direction of rounding is undefined. -@end defun - -@defun idiv x y -Perform an integer division; if @var{x} and @var{y} are both nonnegative -integers, this uses the @code{quotient} function, otherwise it computes -@samp{floor(@var{x}/@var{y})}. Thus the result is well-defined but -slower than for @code{quotient}. -@end defun - -@defun imod x y -Divide integer @var{x} by integer @var{y}; return the integer remainder -and discard the quotient. Like @code{quotient}, this works only for -integer arguments and is not well-defined for negative arguments. -For a more well-defined result, use @samp{(% @var{x} @var{y})}. -@end defun - -@defun idivmod x y -Divide integer @var{x} by integer @var{y}; return a cons cell whose -@code{car} is @samp{(quotient @var{x} @var{y})} and whose @code{cdr} -is @samp{(imod @var{x} @var{y})}. -@end defun - -@defun pow x y -Compute @var{x} to the power @var{y}. In @code{defmath} code, this can -also be written @samp{(^ @var{x} @var{y})} or -@w{@samp{(expt @var{x} @var{y})}}. -@end defun - -@defun abs-approx x -Compute a fast approximation to the absolute value of @var{x}. For -example, for a rectangular complex number the result is the sum of -the absolute values of the components. -@end defun - -@findex e -@findex gamma-const -@findex ln-2 -@findex ln-10 -@findex phi -@findex pi-over-2 -@findex pi-over-4 -@findex pi-over-180 -@findex sqrt-two-pi -@findex sqrt-e -@findex two-pi -@defun pi -The function @samp{(pi)} computes @samp{pi} to the current precision. -Other related constant-generating functions are @code{two-pi}, -@code{pi-over-2}, @code{pi-over-4}, @code{pi-over-180}, @code{sqrt-two-pi}, -@code{e}, @code{sqrt-e}, @code{ln-2}, @code{ln-10}, @code{phi} and -@code{gamma-const}. Each function returns a floating-point value in the -current precision, and each uses caching so that all calls after the -first are essentially free. -@end defun - -@defmac math-defcache @var{func} @var{initial} @var{form} -This macro, usually used as a top-level call like @code{defun} or -@code{defvar}, defines a new cached constant analogous to @code{pi}, etc. -It defines a function @code{func} which returns the requested value; -if @var{initial} is non-@code{nil} it must be a @samp{(float @dots{})} -form which serves as an initial value for the cache. If @var{func} -is called when the cache is empty or does not have enough digits to -satisfy the current precision, the Lisp expression @var{form} is evaluated -with the current precision increased by four, and the result minus its -two least significant digits is stored in the cache. For example, -calling @samp{(pi)} with a precision of 30 computes @samp{pi} to 34 -digits, rounds it down to 32 digits for future use, then rounds it -again to 30 digits for use in the present request. -@end defmac - -@findex half-circle -@findex quarter-circle -@defun full-circle symb -If the current angular mode is Degrees or HMS, this function returns the -integer 360. In Radians mode, this function returns either the -corresponding value in radians to the current precision, or the formula -@samp{2*pi}, depending on the Symbolic mode. There are also similar -function @code{half-circle} and @code{quarter-circle}. -@end defun - -@defun power-of-2 n -Compute two to the integer power @var{n}, as a (potentially very large) -integer. Powers of two are cached, so only the first call for a -particular @var{n} is expensive. -@end defun - -@defun integer-log2 n -Compute the base-2 logarithm of @var{n}, which must be an integer which -is a power of two. If @var{n} is not a power of two, this function will -return @code{nil}. -@end defun - -@defun div-mod a b m -Divide @var{a} by @var{b}, modulo @var{m}. This returns @code{nil} if -there is no solution, or if any of the arguments are not integers. -@end defun - -@defun pow-mod a b m -Compute @var{a} to the power @var{b}, modulo @var{m}. If @var{a}, -@var{b}, and @var{m} are integers, this uses an especially efficient -algorithm. Otherwise, it simply computes @samp{(% (^ a b) m)}. -@end defun - -@defun isqrt n -Compute the integer square root of @var{n}. This is the square root -of @var{n} rounded down toward zero, i.e., @samp{floor(sqrt(@var{n}))}. -If @var{n} is itself an integer, the computation is especially efficient. -@end defun - -@defun to-hms a ang -Convert the argument @var{a} into an HMS form. If @var{ang} is specified, -it is the angular mode in which to interpret @var{a}, either @code{deg} -or @code{rad}. Otherwise, the current angular mode is used. If @var{a} -is already an HMS form it is returned as-is. -@end defun - -@defun from-hms a ang -Convert the HMS form @var{a} into a real number. If @var{ang} is specified, -it is the angular mode in which to express the result, otherwise the -current angular mode is used. If @var{a} is already a real number, it -is returned as-is. -@end defun - -@defun to-radians a -Convert the number or HMS form @var{a} to radians from the current -angular mode. -@end defun - -@defun from-radians a -Convert the number @var{a} from radians to the current angular mode. -If @var{a} is a formula, this returns the formula @samp{deg(@var{a})}. -@end defun - -@defun to-radians-2 a -Like @code{to-radians}, except that in Symbolic mode a degrees to -radians conversion yields a formula like @samp{@var{a}*pi/180}. -@end defun - -@defun from-radians-2 a -Like @code{from-radians}, except that in Symbolic mode a radians to -degrees conversion yields a formula like @samp{@var{a}*180/pi}. -@end defun - -@defun random-digit -Produce a random base-1000 digit in the range 0 to 999. -@end defun - -@defun random-digits n -Produce a random @var{n}-digit integer; this will be an integer -in the interval @samp{[0, 10^@var{n})}. -@end defun - -@defun random-float -Produce a random float in the interval @samp{[0, 1)}. -@end defun - -@defun prime-test n iters -Determine whether the integer @var{n} is prime. Return a list which has -one of these forms: @samp{(nil @var{f})} means the number is non-prime -because it was found to be divisible by @var{f}; @samp{(nil)} means it -was found to be non-prime by table look-up (so no factors are known); -@samp{(nil unknown)} means it is definitely non-prime but no factors -are known because @var{n} was large enough that Fermat's probabilistic -test had to be used; @samp{(t)} means the number is definitely prime; -and @samp{(maybe @var{i} @var{p})} means that Fermat's test, after @var{i} -iterations, is @var{p} percent sure that the number is prime. The -@var{iters} parameter is the number of Fermat iterations to use, in the -case that this is necessary. If @code{prime-test} returns ``maybe,'' -you can call it again with the same @var{n} to get a greater certainty; -@code{prime-test} remembers where it left off. -@end defun - -@defun to-simple-fraction f -If @var{f} is a floating-point number which can be represented exactly -as a small rational number. return that number, else return @var{f}. -For example, 0.75 would be converted to 3:4. This function is very -fast. -@end defun - -@defun to-fraction f tol -Find a rational approximation to floating-point number @var{f} to within -a specified tolerance @var{tol}; this corresponds to the algebraic -function @code{frac}, and can be rather slow. -@end defun - -@defun quarter-integer n -If @var{n} is an integer or integer-valued float, this function -returns zero. If @var{n} is a half-integer (i.e., an integer plus -@mathit{1:2} or 0.5), it returns 2. If @var{n} is a quarter-integer, -it returns 1 or 3. If @var{n} is anything else, this function -returns @code{nil}. -@end defun - -@node Vector Lisp Functions, Symbolic Lisp Functions, Computational Lisp Functions, Internals -@subsubsection Vector Functions - -@noindent -The functions described here perform various operations on vectors and -matrices. - -@defun math-concat x y -Do a vector concatenation; this operation is written @samp{@var{x} | @var{y}} -in a symbolic formula. @xref{Building Vectors}. -@end defun - -@defun vec-length v -Return the length of vector @var{v}. If @var{v} is not a vector, the -result is zero. If @var{v} is a matrix, this returns the number of -rows in the matrix. -@end defun - -@defun mat-dimens m -Determine the dimensions of vector or matrix @var{m}. If @var{m} is not -a vector, the result is an empty list. If @var{m} is a plain vector -but not a matrix, the result is a one-element list containing the length -of the vector. If @var{m} is a matrix with @var{r} rows and @var{c} columns, -the result is the list @samp{(@var{r} @var{c})}. Higher-order tensors -produce lists of more than two dimensions. Note that the object -@samp{[[1, 2, 3], [4, 5]]} is a vector of vectors not all the same size, -and is treated by this and other Calc routines as a plain vector of two -elements. -@end defun - -@defun dimension-error -Abort the current function with a message of ``Dimension error.'' -The Calculator will leave the function being evaluated in symbolic -form; this is really just a special case of @code{reject-arg}. -@end defun - -@defun build-vector args -Return a Calc vector with @var{args} as elements. -For example, @samp{(build-vector 1 2 3)} returns the Calc vector -@samp{[1, 2, 3]}, stored internally as the list @samp{(vec 1 2 3)}. -@end defun - -@defun make-vec obj dims -Return a Calc vector or matrix all of whose elements are equal to -@var{obj}. For example, @samp{(make-vec 27 3 4)} returns a 3x4 matrix -filled with 27's. -@end defun - -@defun row-matrix v -If @var{v} is a plain vector, convert it into a row matrix, i.e., -a matrix whose single row is @var{v}. If @var{v} is already a matrix, -leave it alone. -@end defun - -@defun col-matrix v -If @var{v} is a plain vector, convert it into a column matrix, i.e., a -matrix with each element of @var{v} as a separate row. If @var{v} is -already a matrix, leave it alone. -@end defun - -@defun map-vec f v -Map the Lisp function @var{f} over the Calc vector @var{v}. For example, -@samp{(map-vec 'math-floor v)} returns a vector of the floored components -of vector @var{v}. -@end defun - -@defun map-vec-2 f a b -Map the Lisp function @var{f} over the two vectors @var{a} and @var{b}. -If @var{a} and @var{b} are vectors of equal length, the result is a -vector of the results of calling @samp{(@var{f} @var{ai} @var{bi})} -for each pair of elements @var{ai} and @var{bi}. If either @var{a} or -@var{b} is a scalar, it is matched with each value of the other vector. -For example, @samp{(map-vec-2 'math-add v 1)} returns the vector @var{v} -with each element increased by one. Note that using @samp{'+} would not -work here, since @code{defmath} does not expand function names everywhere, -just where they are in the function position of a Lisp expression. -@end defun - -@defun reduce-vec f v -Reduce the function @var{f} over the vector @var{v}. For example, if -@var{v} is @samp{[10, 20, 30, 40]}, this calls @samp{(f (f (f 10 20) 30) 40)}. -If @var{v} is a matrix, this reduces over the rows of @var{v}. -@end defun - -@defun reduce-cols f m -Reduce the function @var{f} over the columns of matrix @var{m}. For -example, if @var{m} is @samp{[[1, 2], [3, 4], [5, 6]]}, the result -is a vector of the two elements @samp{(f (f 1 3) 5)} and @samp{(f (f 2 4) 6)}. -@end defun - -@defun mat-row m n -Return the @var{n}th row of matrix @var{m}. This is equivalent to -@samp{(elt m n)}. For a slower but safer version, use @code{mrow}. -(@xref{Extracting Elements}.) -@end defun - -@defun mat-col m n -Return the @var{n}th column of matrix @var{m}, in the form of a vector. -The arguments are not checked for correctness. -@end defun - -@defun mat-less-row m n -Return a copy of matrix @var{m} with its @var{n}th row deleted. The -number @var{n} must be in range from 1 to the number of rows in @var{m}. -@end defun - -@defun mat-less-col m n -Return a copy of matrix @var{m} with its @var{n}th column deleted. -@end defun - -@defun transpose m -Return the transpose of matrix @var{m}. -@end defun - -@defun flatten-vector v -Flatten nested vector @var{v} into a vector of scalars. For example, -if @var{v} is @samp{[[1, 2, 3], [4, 5]]} the result is @samp{[1, 2, 3, 4, 5]}. -@end defun - -@defun copy-matrix m -If @var{m} is a matrix, return a copy of @var{m}. This maps -@code{copy-sequence} over the rows of @var{m}; in Lisp terms, each -element of the result matrix will be @code{eq} to the corresponding -element of @var{m}, but none of the @code{cons} cells that make up -the structure of the matrix will be @code{eq}. If @var{m} is a plain -vector, this is the same as @code{copy-sequence}. -@end defun - -@defun swap-rows m r1 r2 -Exchange rows @var{r1} and @var{r2} of matrix @var{m} in-place. In -other words, unlike most of the other functions described here, this -function changes @var{m} itself rather than building up a new result -matrix. The return value is @var{m}, i.e., @samp{(eq (swap-rows m 1 2) m)} -is true, with the side effect of exchanging the first two rows of -@var{m}. -@end defun - -@node Symbolic Lisp Functions, Formatting Lisp Functions, Vector Lisp Functions, Internals -@subsubsection Symbolic Functions - -@noindent -The functions described here operate on symbolic formulas in the -Calculator. - -@defun calc-prepare-selection num -Prepare a stack entry for selection operations. If @var{num} is -omitted, the stack entry containing the cursor is used; otherwise, -it is the number of the stack entry to use. This function stores -useful information about the current stack entry into a set of -variables. @code{calc-selection-cache-num} contains the number of -the stack entry involved (equal to @var{num} if you specified it); -@code{calc-selection-cache-entry} contains the stack entry as a -list (such as @code{calc-top-list} would return with @code{entry} -as the selection mode); and @code{calc-selection-cache-comp} contains -a special ``tagged'' composition (@pxref{Formatting Lisp Functions}) -which allows Calc to relate cursor positions in the buffer with -their corresponding sub-formulas. - -A slight complication arises in the selection mechanism because -formulas may contain small integers. For example, in the vector -@samp{[1, 2, 1]} the first and last elements are @code{eq} to each -other; selections are recorded as the actual Lisp object that -appears somewhere in the tree of the whole formula, but storing -@code{1} would falsely select both @code{1}'s in the vector. So -@code{calc-prepare-selection} also checks the stack entry and -replaces any plain integers with ``complex number'' lists of the form -@samp{(cplx @var{n} 0)}. This list will be displayed the same as a -plain @var{n} and the change will be completely invisible to the -user, but it will guarantee that no two sub-formulas of the stack -entry will be @code{eq} to each other. Next time the stack entry -is involved in a computation, @code{calc-normalize} will replace -these lists with plain numbers again, again invisibly to the user. -@end defun - -@defun calc-encase-atoms x -This modifies the formula @var{x} to ensure that each part of the -formula is a unique atom, using the @samp{(cplx @var{n} 0)} trick -described above. This function may use @code{setcar} to modify -the formula in-place. -@end defun - -@defun calc-find-selected-part -Find the smallest sub-formula of the current formula that contains -the cursor. This assumes @code{calc-prepare-selection} has been -called already. If the cursor is not actually on any part of the -formula, this returns @code{nil}. -@end defun - -@defun calc-change-current-selection selection -Change the currently prepared stack element's selection to -@var{selection}, which should be @code{eq} to some sub-formula -of the stack element, or @code{nil} to unselect the formula. -The stack element's appearance in the Calc buffer is adjusted -to reflect the new selection. -@end defun - -@defun calc-find-nth-part expr n -Return the @var{n}th sub-formula of @var{expr}. This function is used -by the selection commands, and (unless @kbd{j b} has been used) treats -sums and products as flat many-element formulas. Thus if @var{expr} -is @samp{((a + b) - c) + d}, calling @code{calc-find-nth-part} with -@var{n} equal to four will return @samp{d}. -@end defun - -@defun calc-find-parent-formula expr part -Return the sub-formula of @var{expr} which immediately contains -@var{part}. If @var{expr} is @samp{a*b + (c+1)*d} and @var{part} -is @code{eq} to the @samp{c+1} term of @var{expr}, then this function -will return @samp{(c+1)*d}. If @var{part} turns out not to be a -sub-formula of @var{expr}, the function returns @code{nil}. If -@var{part} is @code{eq} to @var{expr}, the function returns @code{t}. -This function does not take associativity into account. -@end defun - -@defun calc-find-assoc-parent-formula expr part -This is the same as @code{calc-find-parent-formula}, except that -(unless @kbd{j b} has been used) it continues widening the selection -to contain a complete level of the formula. Given @samp{a} from -@samp{((a + b) - c) + d}, @code{calc-find-parent-formula} will -return @samp{a + b} but @code{calc-find-assoc-parent-formula} will -return the whole expression. -@end defun - -@defun calc-grow-assoc-formula expr part -This expands sub-formula @var{part} of @var{expr} to encompass a -complete level of the formula. If @var{part} and its immediate -parent are not compatible associative operators, or if @kbd{j b} -has been used, this simply returns @var{part}. -@end defun - -@defun calc-find-sub-formula expr part -This finds the immediate sub-formula of @var{expr} which contains -@var{part}. It returns an index @var{n} such that -@samp{(calc-find-nth-part @var{expr} @var{n})} would return @var{part}. -If @var{part} is not a sub-formula of @var{expr}, it returns @code{nil}. -If @var{part} is @code{eq} to @var{expr}, it returns @code{t}. This -function does not take associativity into account. -@end defun - -@defun calc-replace-sub-formula expr old new -This function returns a copy of formula @var{expr}, with the -sub-formula that is @code{eq} to @var{old} replaced by @var{new}. -@end defun - -@defun simplify expr -Simplify the expression @var{expr} by applying various algebraic rules. -This is what the @w{@kbd{a s}} (@code{calc-simplify}) command uses. This -always returns a copy of the expression; the structure @var{expr} points -to remains unchanged in memory. - -More precisely, here is what @code{simplify} does: The expression is -first normalized and evaluated by calling @code{normalize}. If any -@code{AlgSimpRules} have been defined, they are then applied. Then -the expression is traversed in a depth-first, bottom-up fashion; at -each level, any simplifications that can be made are made until no -further changes are possible. Once the entire formula has been -traversed in this way, it is compared with the original formula (from -before the call to @code{normalize}) and, if it has changed, -the entire procedure is repeated (starting with @code{normalize}) -until no further changes occur. Usually only two iterations are -needed:@: one to simplify the formula, and another to verify that no -further simplifications were possible. -@end defun - -@defun simplify-extended expr -Simplify the expression @var{expr}, with additional rules enabled that -help do a more thorough job, while not being entirely ``safe'' in all -circumstances. (For example, this mode will simplify @samp{sqrt(x^2)} -to @samp{x}, which is only valid when @var{x} is positive.) This is -implemented by temporarily binding the variable @code{math-living-dangerously} -to @code{t} (using a @code{let} form) and calling @code{simplify}. -Dangerous simplification rules are written to check this variable -before taking any action. -@end defun - -@defun simplify-units expr -Simplify the expression @var{expr}, treating variable names as units -whenever possible. This works by binding the variable -@code{math-simplifying-units} to @code{t} while calling @code{simplify}. -@end defun - -@defmac math-defsimplify funcs body -Register a new simplification rule; this is normally called as a top-level -form, like @code{defun} or @code{defmath}. If @var{funcs} is a symbol -(like @code{+} or @code{calcFunc-sqrt}), this simplification rule is -applied to the formulas which are calls to the specified function. Or, -@var{funcs} can be a list of such symbols; the rule applies to all -functions on the list. The @var{body} is written like the body of a -function with a single argument called @code{expr}. The body will be -executed with @code{expr} bound to a formula which is a call to one of -the functions @var{funcs}. If the function body returns @code{nil}, or -if it returns a result @code{equal} to the original @code{expr}, it is -ignored and Calc goes on to try the next simplification rule that applies. -If the function body returns something different, that new formula is -substituted for @var{expr} in the original formula. - -At each point in the formula, rules are tried in the order of the -original calls to @code{math-defsimplify}; the search stops after the -first rule that makes a change. Thus later rules for that same -function will not have a chance to trigger until the next iteration -of the main @code{simplify} loop. - -Note that, since @code{defmath} is not being used here, @var{body} must -be written in true Lisp code without the conveniences that @code{defmath} -provides. If you prefer, you can have @var{body} simply call another -function (defined with @code{defmath}) which does the real work. - -The arguments of a function call will already have been simplified -before any rules for the call itself are invoked. Since a new argument -list is consed up when this happens, this means that the rule's body is -allowed to rearrange the function's arguments destructively if that is -convenient. Here is a typical example of a simplification rule: - -@smallexample -(math-defsimplify calcFunc-arcsinh - (or (and (math-looks-negp (nth 1 expr)) - (math-neg (list 'calcFunc-arcsinh - (math-neg (nth 1 expr))))) - (and (eq (car-safe (nth 1 expr)) 'calcFunc-sinh) - (or math-living-dangerously - (math-known-realp (nth 1 (nth 1 expr)))) - (nth 1 (nth 1 expr))))) -@end smallexample - -This is really a pair of rules written with one @code{math-defsimplify} -for convenience; the first replaces @samp{arcsinh(-x)} with -@samp{-arcsinh(x)}, and the second, which is safe only for real @samp{x}, -replaces @samp{arcsinh(sinh(x))} with @samp{x}. -@end defmac - -@defun common-constant-factor expr -Check @var{expr} to see if it is a sum of terms all multiplied by the -same rational value. If so, return this value. If not, return @code{nil}. -For example, if called on @samp{6x + 9y + 12z}, it would return 3, since -3 is a common factor of all the terms. -@end defun - -@defun cancel-common-factor expr factor -Assuming @var{expr} is a sum with @var{factor} as a common factor, -divide each term of the sum by @var{factor}. This is done by -destructively modifying parts of @var{expr}, on the assumption that -it is being used by a simplification rule (where such things are -allowed; see above). For example, consider this built-in rule for -square roots: - -@smallexample -(math-defsimplify calcFunc-sqrt - (let ((fac (math-common-constant-factor (nth 1 expr)))) - (and fac (not (eq fac 1)) - (math-mul (math-normalize (list 'calcFunc-sqrt fac)) - (math-normalize - (list 'calcFunc-sqrt - (math-cancel-common-factor - (nth 1 expr) fac))))))) -@end smallexample -@end defun - -@defun frac-gcd a b -Compute a ``rational GCD'' of @var{a} and @var{b}, which must both be -rational numbers. This is the fraction composed of the GCD of the -numerators of @var{a} and @var{b}, over the GCD of the denominators. -It is used by @code{common-constant-factor}. Note that the standard -@code{gcd} function uses the LCM to combine the denominators. -@end defun - -@defun map-tree func expr many -Try applying Lisp function @var{func} to various sub-expressions of -@var{expr}. Initially, call @var{func} with @var{expr} itself as an -argument. If this returns an expression which is not @code{equal} to -@var{expr}, apply @var{func} again until eventually it does return -@var{expr} with no changes. Then, if @var{expr} is a function call, -recursively apply @var{func} to each of the arguments. This keeps going -until no changes occur anywhere in the expression; this final expression -is returned by @code{map-tree}. Note that, unlike simplification rules, -@var{func} functions may @emph{not} make destructive changes to -@var{expr}. If a third argument @var{many} is provided, it is an -integer which says how many times @var{func} may be applied; the -default, as described above, is infinitely many times. -@end defun - -@defun compile-rewrites rules -Compile the rewrite rule set specified by @var{rules}, which should -be a formula that is either a vector or a variable name. If the latter, -the compiled rules are saved so that later @code{compile-rules} calls -for that same variable can return immediately. If there are problems -with the rules, this function calls @code{error} with a suitable -message. -@end defun - -@defun apply-rewrites expr crules heads -Apply the compiled rewrite rule set @var{crules} to the expression -@var{expr}. This will make only one rewrite and only checks at the -top level of the expression. The result @code{nil} if no rules -matched, or if the only rules that matched did not actually change -the expression. The @var{heads} argument is optional; if is given, -it should be a list of all function names that (may) appear in -@var{expr}. The rewrite compiler tags each rule with the -rarest-looking function name in the rule; if you specify @var{heads}, -@code{apply-rewrites} can use this information to narrow its search -down to just a few rules in the rule set. -@end defun - -@defun rewrite-heads expr -Compute a @var{heads} list for @var{expr} suitable for use with -@code{apply-rewrites}, as discussed above. -@end defun - -@defun rewrite expr rules many -This is an all-in-one rewrite function. It compiles the rule set -specified by @var{rules}, then uses @code{map-tree} to apply the -rules throughout @var{expr} up to @var{many} (default infinity) -times. -@end defun - -@defun match-patterns pat vec not-flag -Given a Calc vector @var{vec} and an uncompiled pattern set or -pattern set variable @var{pat}, this function returns a new vector -of all elements of @var{vec} which do (or don't, if @var{not-flag} is -non-@code{nil}) match any of the patterns in @var{pat}. -@end defun - -@defun deriv expr var value symb -Compute the derivative of @var{expr} with respect to variable @var{var} -(which may actually be any sub-expression). If @var{value} is specified, -the derivative is evaluated at the value of @var{var}; otherwise, the -derivative is left in terms of @var{var}. If the expression contains -functions for which no derivative formula is known, new derivative -functions are invented by adding primes to the names; @pxref{Calculus}. -However, if @var{symb} is non-@code{nil}, the presence of undifferentiable -functions in @var{expr} instead cancels the whole differentiation, and -@code{deriv} returns @code{nil} instead. - -Derivatives of an @var{n}-argument function can be defined by -adding a @code{math-derivative-@var{n}} property to the property list -of the symbol for the function's derivative, which will be the -function name followed by an apostrophe. The value of the property -should be a Lisp function; it is called with the same arguments as the -original function call that is being differentiated. It should return -a formula for the derivative. For example, the derivative of @code{ln} -is defined by - -@smallexample -(put 'calcFunc-ln\' 'math-derivative-1 - (function (lambda (u) (math-div 1 u)))) -@end smallexample - -The two-argument @code{log} function has two derivatives, -@smallexample -(put 'calcFunc-log\' 'math-derivative-2 ; d(log(x,b)) / dx - (function (lambda (x b) ... ))) -(put 'calcFunc-log\'2 'math-derivative-2 ; d(log(x,b)) / db - (function (lambda (x b) ... ))) -@end smallexample -@end defun - -@defun tderiv expr var value symb -Compute the total derivative of @var{expr}. This is the same as -@code{deriv}, except that variables other than @var{var} are not -assumed to be constant with respect to @var{var}. -@end defun - -@defun integ expr var low high -Compute the integral of @var{expr} with respect to @var{var}. -@xref{Calculus}, for further details. -@end defun - -@defmac math-defintegral funcs body -Define a rule for integrating a function or functions of one argument; -this macro is very similar in format to @code{math-defsimplify}. -The main difference is that here @var{body} is the body of a function -with a single argument @code{u} which is bound to the argument to the -function being integrated, not the function call itself. Also, the -variable of integration is available as @code{math-integ-var}. If -evaluation of the integral requires doing further integrals, the body -should call @samp{(math-integral @var{x})} to find the integral of -@var{x} with respect to @code{math-integ-var}; this function returns -@code{nil} if the integral could not be done. Some examples: - -@smallexample -(math-defintegral calcFunc-conj - (let ((int (math-integral u))) - (and int - (list 'calcFunc-conj int)))) - -(math-defintegral calcFunc-cos - (and (equal u math-integ-var) - (math-from-radians-2 (list 'calcFunc-sin u)))) -@end smallexample - -In the @code{cos} example, we define only the integral of @samp{cos(x) dx}, -relying on the general integration-by-substitution facility to handle -cosines of more complicated arguments. An integration rule should return -@code{nil} if it can't do the integral; if several rules are defined for -the same function, they are tried in order until one returns a non-@code{nil} -result. -@end defmac - -@defmac math-defintegral-2 funcs body -Define a rule for integrating a function or functions of two arguments. -This is exactly analogous to @code{math-defintegral}, except that @var{body} -is written as the body of a function with two arguments, @var{u} and -@var{v}. -@end defmac - -@defun solve-for lhs rhs var full -Attempt to solve the equation @samp{@var{lhs} = @var{rhs}} by isolating -the variable @var{var} on the lefthand side; return the resulting righthand -side, or @code{nil} if the equation cannot be solved. The variable -@var{var} must appear at least once in @var{lhs} or @var{rhs}. Note that -the return value is a formula which does not contain @var{var}; this is -different from the user-level @code{solve} and @code{finv} functions, -which return a rearranged equation or a functional inverse, respectively. -If @var{full} is non-@code{nil}, a full solution including dummy signs -and dummy integers will be produced. User-defined inverses are provided -as properties in a manner similar to derivatives: - -@smallexample -(put 'calcFunc-ln 'math-inverse - (function (lambda (x) (list 'calcFunc-exp x)))) -@end smallexample - -This function can call @samp{(math-solve-get-sign @var{x})} to create -a new arbitrary sign variable, returning @var{x} times that sign, and -@samp{(math-solve-get-int @var{x})} to create a new arbitrary integer -variable multiplied by @var{x}. These functions simply return @var{x} -if the caller requested a non-``full'' solution. -@end defun - -@defun solve-eqn expr var full -This version of @code{solve-for} takes an expression which will -typically be an equation or inequality. (If it is not, it will be -interpreted as the equation @samp{@var{expr} = 0}.) It returns an -equation or inequality, or @code{nil} if no solution could be found. -@end defun - -@defun solve-system exprs vars full -This function solves a system of equations. Generally, @var{exprs} -and @var{vars} will be vectors of equal length. -@xref{Solving Systems of Equations}, for other options. -@end defun - -@defun expr-contains expr var -Returns a non-@code{nil} value if @var{var} occurs as a subexpression -of @var{expr}. - -This function might seem at first to be identical to -@code{calc-find-sub-formula}. The key difference is that -@code{expr-contains} uses @code{equal} to test for matches, whereas -@code{calc-find-sub-formula} uses @code{eq}. In the formula -@samp{f(a, a)}, the two @samp{a}s will be @code{equal} but not -@code{eq} to each other. -@end defun - -@defun expr-contains-count expr var -Returns the number of occurrences of @var{var} as a subexpression -of @var{expr}, or @code{nil} if there are no occurrences. -@end defun - -@defun expr-depends expr var -Returns true if @var{expr} refers to any variable the occurs in @var{var}. -In other words, it checks if @var{expr} and @var{var} have any variables -in common. -@end defun - -@defun expr-contains-vars expr -Return true if @var{expr} contains any variables, or @code{nil} if @var{expr} -contains only constants and functions with constant arguments. -@end defun - -@defun expr-subst expr old new -Returns a copy of @var{expr}, with all occurrences of @var{old} replaced -by @var{new}. This treats @code{lambda} forms specially with respect -to the dummy argument variables, so that the effect is always to return -@var{expr} evaluated at @var{old} = @var{new}. -@end defun - -@defun multi-subst expr old new -This is like @code{expr-subst}, except that @var{old} and @var{new} -are lists of expressions to be substituted simultaneously. If one -list is shorter than the other, trailing elements of the longer list -are ignored. -@end defun - -@defun expr-weight expr -Returns the ``weight'' of @var{expr}, basically a count of the total -number of objects and function calls that appear in @var{expr}. For -``primitive'' objects, this will be one. -@end defun - -@defun expr-height expr -Returns the ``height'' of @var{expr}, which is the deepest level to -which function calls are nested. (Note that @samp{@var{a} + @var{b}} -counts as a function call.) For primitive objects, this returns zero. -@end defun - -@defun polynomial-p expr var -Check if @var{expr} is a polynomial in variable (or sub-expression) -@var{var}. If so, return the degree of the polynomial, that is, the -highest power of @var{var} that appears in @var{expr}. For example, -for @samp{(x^2 + 3)^3 + 4} this would return 6. This function returns -@code{nil} unless @var{expr}, when expanded out by @kbd{a x} -(@code{calc-expand}), would consist of a sum of terms in which @var{var} -appears only raised to nonnegative integer powers. Note that if -@var{var} does not occur in @var{expr}, then @var{expr} is considered -a polynomial of degree 0. -@end defun - -@defun is-polynomial expr var degree loose -Check if @var{expr} is a polynomial in variable or sub-expression -@var{var}, and, if so, return a list representation of the polynomial -where the elements of the list are coefficients of successive powers of -@var{var}: @samp{@var{a} + @var{b} x + @var{c} x^3} would produce the -list @samp{(@var{a} @var{b} 0 @var{c})}, and @samp{(x + 1)^2} would -produce the list @samp{(1 2 1)}. The highest element of the list will -be non-zero, with the special exception that if @var{expr} is the -constant zero, the returned value will be @samp{(0)}. Return @code{nil} -if @var{expr} is not a polynomial in @var{var}. If @var{degree} is -specified, this will not consider polynomials of degree higher than that -value. This is a good precaution because otherwise an input of -@samp{(x+1)^1000} will cause a huge coefficient list to be built. If -@var{loose} is non-@code{nil}, then a looser definition of a polynomial -is used in which coefficients are no longer required not to depend on -@var{var}, but are only required not to take the form of polynomials -themselves. For example, @samp{sin(x) x^2 + cos(x)} is a loose -polynomial with coefficients @samp{((calcFunc-cos x) 0 (calcFunc-sin -x))}. The result will never be @code{nil} in loose mode, since any -expression can be interpreted as a ``constant'' loose polynomial. -@end defun - -@defun polynomial-base expr pred -Check if @var{expr} is a polynomial in any variable that occurs in it; -if so, return that variable. (If @var{expr} is a multivariate polynomial, -this chooses one variable arbitrarily.) If @var{pred} is specified, it should -be a Lisp function which is called as @samp{(@var{pred} @var{subexpr})}, -and which should return true if @code{mpb-top-expr} (a global name for -the original @var{expr}) is a suitable polynomial in @var{subexpr}. -The default predicate uses @samp{(polynomial-p mpb-top-expr @var{subexpr})}; -you can use @var{pred} to specify additional conditions. Or, you could -have @var{pred} build up a list of every suitable @var{subexpr} that -is found. -@end defun - -@defun poly-simplify poly -Simplify polynomial coefficient list @var{poly} by (destructively) -clipping off trailing zeros. -@end defun - -@defun poly-mix a ac b bc -Mix two polynomial lists @var{a} and @var{b} (in the form returned by -@code{is-polynomial}) in a linear combination with coefficient expressions -@var{ac} and @var{bc}. The result is a (not necessarily simplified) -polynomial list representing @samp{@var{ac} @var{a} + @var{bc} @var{b}}. -@end defun - -@defun poly-mul a b -Multiply two polynomial coefficient lists @var{a} and @var{b}. The -result will be in simplified form if the inputs were simplified. -@end defun - -@defun build-polynomial-expr poly var -Construct a Calc formula which represents the polynomial coefficient -list @var{poly} applied to variable @var{var}. The @kbd{a c} -(@code{calc-collect}) command uses @code{is-polynomial} to turn an -expression into a coefficient list, then @code{build-polynomial-expr} -to turn the list back into an expression in regular form. -@end defun - -@defun check-unit-name var -Check if @var{var} is a variable which can be interpreted as a unit -name. If so, return the units table entry for that unit. This -will be a list whose first element is the unit name (not counting -prefix characters) as a symbol and whose second element is the -Calc expression which defines the unit. (Refer to the Calc sources -for details on the remaining elements of this list.) If @var{var} -is not a variable or is not a unit name, return @code{nil}. -@end defun - -@defun units-in-expr-p expr sub-exprs -Return true if @var{expr} contains any variables which can be -interpreted as units. If @var{sub-exprs} is @code{t}, the entire -expression is searched. If @var{sub-exprs} is @code{nil}, this -checks whether @var{expr} is directly a units expression. -@end defun - -@defun single-units-in-expr-p expr -Check whether @var{expr} contains exactly one units variable. If so, -return the units table entry for the variable. If @var{expr} does -not contain any units, return @code{nil}. If @var{expr} contains -two or more units, return the symbol @code{wrong}. -@end defun - -@defun to-standard-units expr which -Convert units expression @var{expr} to base units. If @var{which} -is @code{nil}, use Calc's native base units. Otherwise, @var{which} -can specify a units system, which is a list of two-element lists, -where the first element is a Calc base symbol name and the second -is an expression to substitute for it. -@end defun - -@defun remove-units expr -Return a copy of @var{expr} with all units variables replaced by ones. -This expression is generally normalized before use. -@end defun - -@defun extract-units expr -Return a copy of @var{expr} with everything but units variables replaced -by ones. -@end defun - -@node Formatting Lisp Functions, Hooks, Symbolic Lisp Functions, Internals -@subsubsection I/O and Formatting Functions - -@noindent -The functions described here are responsible for parsing and formatting -Calc numbers and formulas. - -@defun calc-eval str sep arg1 arg2 @dots{} -This is the simplest interface to the Calculator from another Lisp program. -@xref{Calling Calc from Your Programs}. -@end defun - -@defun read-number str -If string @var{str} contains a valid Calc number, either integer, -fraction, float, or HMS form, this function parses and returns that -number. Otherwise, it returns @code{nil}. -@end defun - -@defun read-expr str -Read an algebraic expression from string @var{str}. If @var{str} does -not have the form of a valid expression, return a list of the form -@samp{(error @var{pos} @var{msg})} where @var{pos} is an integer index -into @var{str} of the general location of the error, and @var{msg} is -a string describing the problem. -@end defun - -@defun read-exprs str -Read a list of expressions separated by commas, and return it as a -Lisp list. If an error occurs in any expressions, an error list as -shown above is returned instead. -@end defun - -@defun calc-do-alg-entry initial prompt no-norm -Read an algebraic formula or formulas using the minibuffer. All -conventions of regular algebraic entry are observed. The return value -is a list of Calc formulas; there will be more than one if the user -entered a list of values separated by commas. The result is @code{nil} -if the user presses Return with a blank line. If @var{initial} is -given, it is a string which the minibuffer will initially contain. -If @var{prompt} is given, it is the prompt string to use; the default -is ``Algebraic:''. If @var{no-norm} is @code{t}, the formulas will -be returned exactly as parsed; otherwise, they will be passed through -@code{calc-normalize} first. - -To support the use of @kbd{$} characters in the algebraic entry, use -@code{let} to bind @code{calc-dollar-values} to a list of the values -to be substituted for @kbd{$}, @kbd{$$}, and so on, and bind -@code{calc-dollar-used} to 0. Upon return, @code{calc-dollar-used} -will have been changed to the highest number of consecutive @kbd{$}s -that actually appeared in the input. -@end defun - -@defun format-number a -Convert the real or complex number or HMS form @var{a} to string form. -@end defun - -@defun format-flat-expr a prec -Convert the arbitrary Calc number or formula @var{a} to string form, -in the style used by the trail buffer and the @code{calc-edit} command. -This is a simple format designed -mostly to guarantee the string is of a form that can be re-parsed by -@code{read-expr}. Most formatting modes, such as digit grouping, -complex number format, and point character, are ignored to ensure the -result will be re-readable. The @var{prec} parameter is normally 0; if -you pass a large integer like 1000 instead, the expression will be -surrounded by parentheses unless it is a plain number or variable name. -@end defun - -@defun format-nice-expr a width -This is like @code{format-flat-expr} (with @var{prec} equal to 0), -except that newlines will be inserted to keep lines down to the -specified @var{width}, and vectors that look like matrices or rewrite -rules are written in a pseudo-matrix format. The @code{calc-edit} -command uses this when only one stack entry is being edited. -@end defun - -@defun format-value a width -Convert the Calc number or formula @var{a} to string form, using the -format seen in the stack buffer. Beware the string returned may -not be re-readable by @code{read-expr}, for example, because of digit -grouping. Multi-line objects like matrices produce strings that -contain newline characters to separate the lines. The @var{w} -parameter, if given, is the target window size for which to format -the expressions. If @var{w} is omitted, the width of the Calculator -window is used. -@end defun - -@defun compose-expr a prec -Format the Calc number or formula @var{a} according to the current -language mode, returning a ``composition.'' To learn about the -structure of compositions, see the comments in the Calc source code. -You can specify the format of a given type of function call by putting -a @code{math-compose-@var{lang}} property on the function's symbol, -whose value is a Lisp function that takes @var{a} and @var{prec} as -arguments and returns a composition. Here @var{lang} is a language -mode name, one of @code{normal}, @code{big}, @code{c}, @code{pascal}, -@code{fortran}, @code{tex}, @code{eqn}, @code{math}, or @code{maple}. -In Big mode, Calc actually tries @code{math-compose-big} first, then -tries @code{math-compose-normal}. If this property does not exist, -or if the function returns @code{nil}, the function is written in the -normal function-call notation for that language. -@end defun - -@defun composition-to-string c w -Convert a composition structure returned by @code{compose-expr} into -a string. Multi-line compositions convert to strings containing -newline characters. The target window size is given by @var{w}. -The @code{format-value} function basically calls @code{compose-expr} -followed by @code{composition-to-string}. -@end defun - -@defun comp-width c -Compute the width in characters of composition @var{c}. -@end defun - -@defun comp-height c -Compute the height in lines of composition @var{c}. -@end defun - -@defun comp-ascent c -Compute the portion of the height of composition @var{c} which is on or -above the baseline. For a one-line composition, this will be one. -@end defun - -@defun comp-descent c -Compute the portion of the height of composition @var{c} which is below -the baseline. For a one-line composition, this will be zero. -@end defun - -@defun comp-first-char c -If composition @var{c} is a ``flat'' composition, return the first -(leftmost) character of the composition as an integer. Otherwise, -return @code{nil}. -@end defun - -@defun comp-last-char c -If composition @var{c} is a ``flat'' composition, return the last -(rightmost) character, otherwise return @code{nil}. -@end defun - -@comment @node Lisp Variables, Hooks, Formatting Lisp Functions, Internals -@comment @subsubsection Lisp Variables -@comment -@comment @noindent -@comment (This section is currently unfinished.) - -@node Hooks, , Formatting Lisp Functions, Internals -@subsubsection Hooks - -@noindent -Hooks are variables which contain Lisp functions (or lists of functions) -which are called at various times. Calc defines a number of hooks -that help you to customize it in various ways. Calc uses the Lisp -function @code{run-hooks} to invoke the hooks shown below. Several -other customization-related variables are also described here. - -@defvar calc-load-hook -This hook is called at the end of @file{calc.el}, after the file has -been loaded, before any functions in it have been called, but after -@code{calc-mode-map} and similar variables have been set up. -@end defvar - -@defvar calc-ext-load-hook -This hook is called at the end of @file{calc-ext.el}. -@end defvar - -@defvar calc-start-hook -This hook is called as the last step in a @kbd{M-x calc} command. -At this point, the Calc buffer has been created and initialized if -necessary, the Calc window and trail window have been created, -and the ``Welcome to Calc'' message has been displayed. -@end defvar - -@defvar calc-mode-hook -This hook is called when the Calc buffer is being created. Usually -this will only happen once per Emacs session. The hook is called -after Emacs has switched to the new buffer, the mode-settings file -has been read if necessary, and all other buffer-local variables -have been set up. After this hook returns, Calc will perform a -@code{calc-refresh} operation, set up the mode line display, then -evaluate any deferred @code{calc-define} properties that have not -been evaluated yet. -@end defvar - -@defvar calc-trail-mode-hook -This hook is called when the Calc Trail buffer is being created. -It is called as the very last step of setting up the Trail buffer. -Like @code{calc-mode-hook}, this will normally happen only once -per Emacs session. -@end defvar - -@defvar calc-end-hook -This hook is called by @code{calc-quit}, generally because the user -presses @kbd{q} or @kbd{C-x * c} while in Calc. The Calc buffer will -be the current buffer. The hook is called as the very first -step, before the Calc window is destroyed. -@end defvar - -@defvar calc-window-hook -If this hook is non-@code{nil}, it is called to create the Calc window. -Upon return, this new Calc window should be the current window. -(The Calc buffer will already be the current buffer when the -hook is called.) If the hook is not defined, Calc will -generally use @code{split-window}, @code{set-window-buffer}, -and @code{select-window} to create the Calc window. -@end defvar - -@defvar calc-trail-window-hook -If this hook is non-@code{nil}, it is called to create the Calc Trail -window. The variable @code{calc-trail-buffer} will contain the buffer -which the window should use. Unlike @code{calc-window-hook}, this hook -must @emph{not} switch into the new window. -@end defvar - -@defvar calc-embedded-mode-hook -This hook is called the first time that Embedded mode is entered. -@end defvar - -@defvar calc-embedded-new-buffer-hook -This hook is called each time that Embedded mode is entered in a -new buffer. -@end defvar - -@defvar calc-embedded-new-formula-hook -This hook is called each time that Embedded mode is enabled for a -new formula. -@end defvar - -@defvar calc-edit-mode-hook -This hook is called by @code{calc-edit} (and the other ``edit'' -commands) when the temporary editing buffer is being created. -The buffer will have been selected and set up to be in -@code{calc-edit-mode}, but will not yet have been filled with -text. (In fact it may still have leftover text from a previous -@code{calc-edit} command.) -@end defvar - -@defvar calc-mode-save-hook -This hook is called by the @code{calc-save-modes} command, -after Calc's own mode features have been inserted into the -Calc init file and just before the ``End of mode settings'' -message is inserted. -@end defvar - -@defvar calc-reset-hook -This hook is called after @kbd{C-x * 0} (@code{calc-reset}) has -reset all modes. The Calc buffer will be the current buffer. -@end defvar - -@defvar calc-other-modes -This variable contains a list of strings. The strings are -concatenated at the end of the modes portion of the Calc -mode line (after standard modes such as ``Deg'', ``Inv'' and -``Hyp''). Each string should be a short, single word followed -by a space. The variable is @code{nil} by default. -@end defvar - -@defvar calc-mode-map -This is the keymap that is used by Calc mode. The best time -to adjust it is probably in a @code{calc-mode-hook}. If the -Calc extensions package (@file{calc-ext.el}) has not yet been -loaded, many of these keys will be bound to @code{calc-missing-key}, -which is a command that loads the extensions package and -``retypes'' the key. If your @code{calc-mode-hook} rebinds -one of these keys, it will probably be overridden when the -extensions are loaded. -@end defvar - -@defvar calc-digit-map -This is the keymap that is used during numeric entry. Numeric -entry uses the minibuffer, but this map binds every non-numeric -key to @code{calcDigit-nondigit} which generally calls -@code{exit-minibuffer} and ``retypes'' the key. -@end defvar - -@defvar calc-alg-ent-map -This is the keymap that is used during algebraic entry. This is -mostly a copy of @code{minibuffer-local-map}. -@end defvar - -@defvar calc-store-var-map -This is the keymap that is used during entry of variable names for -commands like @code{calc-store} and @code{calc-recall}. This is -mostly a copy of @code{minibuffer-local-completion-map}. -@end defvar - -@defvar calc-edit-mode-map -This is the (sparse) keymap used by @code{calc-edit} and other -temporary editing commands. It binds @key{RET}, @key{LFD}, -and @kbd{C-c C-c} to @code{calc-edit-finish}. -@end defvar - -@defvar calc-mode-var-list -This is a list of variables which are saved by @code{calc-save-modes}. -Each entry is a list of two items, the variable (as a Lisp symbol) -and its default value. When modes are being saved, each variable -is compared with its default value (using @code{equal}) and any -non-default variables are written out. -@end defvar - -@defvar calc-local-var-list -This is a list of variables which should be buffer-local to the -Calc buffer. Each entry is a variable name (as a Lisp symbol). -These variables also have their default values manipulated by -the @code{calc} and @code{calc-quit} commands; @pxref{Multiple Calculators}. -Since @code{calc-mode-hook} is called after this list has been -used the first time, your hook should add a variable to the -list and also call @code{make-local-variable} itself. -@end defvar - -@node Copying, GNU Free Documentation License, Programming, Top -@appendix GNU GENERAL PUBLIC LICENSE -@include gpl.texi - -@node GNU Free Documentation License, Customizing Calc, Copying, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Customizing Calc, Reporting Bugs, GNU Free Documentation License, Top -@appendix Customizing Calc - -The usual prefix for Calc is the key sequence @kbd{C-x *}. If you wish -to use a different prefix, you can put - -@example -(global-set-key "NEWPREFIX" 'calc-dispatch) -@end example - -@noindent -in your .emacs file. -(@xref{Key Bindings,,Customizing Key Bindings,emacs, -The GNU Emacs Manual}, for more information on binding keys.) -A convenient way to start Calc is with @kbd{C-x * *}; to make it equally -convenient for users who use a different prefix, the prefix can be -followed by @kbd{=}, @kbd{&}, @kbd{#}, @kbd{\}, @kbd{/}, @kbd{+} or -@kbd{-} as well as @kbd{*} to start Calc, and so in many cases the last -character of the prefix can simply be typed twice. - -Calc is controlled by many variables, most of which can be reset -from within Calc. Some variables are less involved with actual -calculation, and can be set outside of Calc using Emacs's -customization facilities. These variables are listed below. -Typing @kbd{M-x customize-variable RET @var{variable-name} RET} -will bring up a buffer in which the variable's value can be redefined. -Typing @kbd{M-x customize-group RET calc RET} will bring up a buffer which -contains all of Calc's customizable variables. (These variables can -also be reset by putting the appropriate lines in your .emacs file; -@xref{Init File, ,Init File, emacs, The GNU Emacs Manual}.) - -Some of the customizable variables are regular expressions. A regular -expression is basically a pattern that Calc can search for. -See @ref{Regexp Search,, Regular Expression Search, emacs, The GNU Emacs Manual} -to see how regular expressions work. - -@defvar calc-settings-file -The variable @code{calc-settings-file} holds the file name in -which commands like @kbd{m m} and @kbd{Z P} store ``permanent'' -definitions. -If @code{calc-settings-file} is not your user init file (typically -@file{~/.emacs}) and if the variable @code{calc-loaded-settings-file} is -@code{nil}, then Calc will automatically load your settings file (if it -exists) the first time Calc is invoked. - -The default value for this variable is @code{"~/.calc.el"}. -@end defvar - -@defvar calc-gnuplot-name -See @ref{Graphics}.@* -The variable @code{calc-gnuplot-name} should be the name of the -GNUPLOT program (a string). If you have GNUPLOT installed on your -system but Calc is unable to find it, you may need to set this -variable. You may also need to set some Lisp variables to show Calc how -to run GNUPLOT on your system, see @ref{Devices, ,Graphical Devices} . -The default value of @code{calc-gnuplot-name} is @code{"gnuplot"}. -@end defvar - -@defvar calc-gnuplot-plot-command -@defvarx calc-gnuplot-print-command -See @ref{Devices, ,Graphical Devices}.@* -The variables @code{calc-gnuplot-plot-command} and -@code{calc-gnuplot-print-command} represent system commands to -display and print the output of GNUPLOT, respectively. These may be -@code{nil} if no command is necessary, or strings which can include -@samp{%s} to signify the name of the file to be displayed or printed. -Or, these variables may contain Lisp expressions which are evaluated -to display or print the output. - -The default value of @code{calc-gnuplot-plot-command} is @code{nil}, -and the default value of @code{calc-gnuplot-print-command} is -@code{"lp %s"}. -@end defvar - -@defvar calc-language-alist -See @ref{Basic Embedded Mode}.@* -The variable @code{calc-language-alist} controls the languages that -Calc will associate with major modes. When Calc embedded mode is -enabled, it will try to use the current major mode to -determine what language should be used. (This can be overridden using -Calc's mode changing commands, @xref{Mode Settings in Embedded Mode}.) -The variable @code{calc-language-alist} consists of a list of pairs of -the form @code{(@var{MAJOR-MODE} . @var{LANGUAGE})}; for example, -@code{(latex-mode . latex)} is one such pair. If Calc embedded is -activated in a buffer whose major mode is @var{MAJOR-MODE}, it will set itself -to use the language @var{LANGUAGE}. - -The default value of @code{calc-language-alist} is -@example - ((latex-mode . latex) - (tex-mode . tex) - (plain-tex-mode . tex) - (context-mode . tex) - (nroff-mode . eqn) - (pascal-mode . pascal) - (c-mode . c) - (c++-mode . c) - (fortran-mode . fortran) - (f90-mode . fortran)) -@end example -@end defvar - -@defvar calc-embedded-announce-formula -@defvarx calc-embedded-announce-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-announce-formula} helps determine -what formulas @kbd{C-x * a} will activate in a buffer. It is a -regular expression, and when activating embedded formulas with -@kbd{C-x * a}, it will tell Calc that what follows is a formula to be -activated. (Calc also uses other patterns to find formulas, such as -@samp{=>} and @samp{:=}.) - -The default pattern is @code{"%Embed\n\\(% .*\n\\)*"}, which checks -for @samp{%Embed} followed by any number of lines beginning with -@samp{%} and a space. - -The variable @code{calc-embedded-announce-formula-alist} is used to -set @code{calc-embedded-announce-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of pairs of the form @code{(@var{MAJOR-MODE} . -@var{REGEXP})}, and its default value is -@example - ((c++-mode . "//Embed\n\\(// .*\n\\)*") - (c-mode . "/\\*Embed\\*/\n\\(/\\* .*\\*/\n\\)*") - (f90-mode . "!Embed\n\\(! .*\n\\)*") - (fortran-mode . "C Embed\n\\(C .*\n\\)*") - (html-helper-mode . "\n\\(\n\\)*") - (html-mode . "\n\\(\n\\)*") - (nroff-mode . "\\\\\"Embed\n\\(\\\\\" .*\n\\)*") - (pascal-mode . "@{Embed@}\n\\(@{.*@}\n\\)*") - (sgml-mode . "\n\\(\n\\)*") - (xml-mode . "\n\\(\n\\)*") - (texinfo-mode . "@@c Embed\n\\(@@c .*\n\\)*")) -@end example -Any major modes added to @code{calc-embedded-announce-formula-alist} -should also be added to @code{calc-embedded-open-close-plain-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-formula -@defvarx calc-embedded-close-formula -@defvarx calc-embedded-open-close-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} control the region that Calc will -activate as a formula when Embedded mode is entered with @kbd{C-x * e}. -They are regular expressions; -Calc normally scans backward and forward in the buffer for the -nearest text matching these regular expressions to be the ``formula -delimiters''. - -The simplest delimiters are blank lines. Other delimiters that -Embedded mode understands by default are: -@enumerate -@item -The @TeX{} and La@TeX{} math delimiters @samp{$ $}, @samp{$$ $$}, -@samp{\[ \]}, and @samp{\( \)}; -@item -Lines beginning with @samp{\begin} and @samp{\end} (except matrix delimiters); -@item -Lines beginning with @samp{@@} (Texinfo delimiters). -@item -Lines beginning with @samp{.EQ} and @samp{.EN} (@dfn{eqn} delimiters); -@item -Lines containing a single @samp{%} or @samp{.\"} symbol and nothing else. -@end enumerate - -The variable @code{calc-embedded-open-close-formula-alist} is used to -set @code{calc-embedded-open-formula} and -@code{calc-embedded-close-formula} to different regular -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-FORMULA-REGEXP} -@var{CLOSE-FORMULA-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-word-regexp -@defvarx calc-embedded-word-regexp-alist -See @ref{Customizing Embedded Mode}.@* -The variable @code{calc-embedded-word-regexp} determines the expression -that Calc will activate when Embedded mode is entered with @kbd{C-x * -w}. It is a regular expressions. - -The default value of @code{calc-embedded-word-regexp} is -@code{"[-+]?[0-9]+\\(\\.[0-9]+\\)?\\([eE][-+]?[0-9]+\\)?"}. - -The variable @code{calc-embedded-word-regexp-alist} is used to -set @code{calc-embedded-word-regexp} to a different regular -expression depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{WORD-REGEXP})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-plain -@defvarx calc-embedded-close-plain -@defvarx calc-embedded-open-close-plain-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-plain} and -@code{calc-embedded-open-plain} are used to delimit ``plain'' -formulas. Note that these are actual strings, not regular -expressions, because Calc must be able to write these string into a -buffer as well as to recognize them. - -The default string for @code{calc-embedded-open-plain} is -@code{"%%% "}, note the trailing space. The default string for -@code{calc-embedded-close-plain} is @code{" %%%\n"}, without -the trailing newline here, the first line of a Big mode formula -that followed might be shifted over with respect to the other lines. - -The variable @code{calc-embedded-open-close-plain-alist} is used to -set @code{calc-embedded-open-plain} and -@code{calc-embedded-close-plain} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-PLAIN-STRING} -@var{CLOSE-PLAIN-STRING})}, and its default value is -@example - ((c++-mode "// %% " " %%\n") - (c-mode "/* %% " " %% */\n") - (f90-mode "! %% " " %%\n") - (fortran-mode "C %% " " %%\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" %% " " %%\n") - (pascal-mode "@{%% " " %%@}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c %% " " %%\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-plain-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-mode-alist}. -@end defvar - -@defvar calc-embedded-open-new-formula -@defvarx calc-embedded-close-new-formula -@defvarx calc-embedded-open-close-new-formula-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} are strings which are -inserted before and after a new formula when you type @kbd{C-x * f}. - -The default value of @code{calc-embedded-open-new-formula} is -@code{"\n\n"}. If this string begins with a newline character and the -@kbd{C-x * f} is typed at the beginning of a line, @kbd{C-x * f} will skip -this first newline to avoid introducing unnecessary blank lines in the -file. The default value of @code{calc-embedded-close-new-formula} is -also @code{"\n\n"}. The final newline is omitted by @w{@kbd{C-x * f}} -if typed at the end of a line. (It follows that if @kbd{C-x * f} is -typed on a blank line, both a leading opening newline and a trailing -closing newline are omitted.) - -The variable @code{calc-embedded-open-close-new-formula-alist} is used to -set @code{calc-embedded-open-new-formula} and -@code{calc-embedded-close-new-formula} to different strings -depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-NEW-FORMULA-STRING} -@var{CLOSE-NEW-FORMULA-STRING})}, and its default value is -@code{nil}. -@end defvar - -@defvar calc-embedded-open-mode -@defvarx calc-embedded-close-mode -@defvarx calc-embedded-open-close-mode-alist -See @ref{Customizing Embedded Mode}.@* -The variables @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} are strings which Calc will place before -and after any mode annotations that it inserts. Calc never scans for -these strings; Calc always looks for the annotation itself, so it is not -necessary to add them to user-written annotations. - -The default value of @code{calc-embedded-open-mode} is @code{"% "} -and the default value of @code{calc-embedded-close-mode} is -@code{"\n"}. -If you change the value of @code{calc-embedded-close-mode}, it is a good -idea still to end with a newline so that mode annotations will appear on -lines by themselves. - -The variable @code{calc-embedded-open-close-mode-alist} is used to -set @code{calc-embedded-open-mode} and -@code{calc-embedded-close-mode} to different strings -expressions depending on the major mode of the editing buffer. -It consists of a list of lists of the form -@code{(@var{MAJOR-MODE} @var{OPEN-MODE-STRING} -@var{CLOSE-MODE-STRING})}, and its default value is -@example - ((c++-mode "// " "\n") - (c-mode "/* " " */\n") - (f90-mode "! " "\n") - (fortran-mode "C " "\n") - (html-helper-mode "\n") - (html-mode "\n") - (nroff-mode "\\\" " "\n") - (pascal-mode "@{ " " @}\n") - (sgml-mode "\n") - (xml-mode "\n") - (texinfo-mode "@@c " "\n")) -@end example -Any major modes added to @code{calc-embedded-open-close-mode-alist} -should also be added to @code{calc-embedded-announce-formula-alist} -and @code{calc-embedded-open-close-plain-alist}. -@end defvar - -@defvar calc-multiplication-has-precedence -The variable @code{calc-multiplication-has-precedence} determines -whether multiplication has precedence over division in algebraic -formulas in normal language modes. If -@code{calc-multiplication-has-precedence} is non-@code{nil}, then -multiplication has precedence (and, for certain obscure reasons, is -right associative), and so for example @samp{a/b*c} will be interpreted -as @samp{a/(b*c)}. If @code{calc-multiplication-has-precedence} is -@code{nil}, then multiplication has the same precedence as division -(and, like division, is left associative), and so for example -@samp{a/b*c} will be interpreted as @samp{(a/b)*c}. The default value -of @code{calc-multiplication-has-precedence} is @code{t}. -@end defvar - -@node Reporting Bugs, Summary, Customizing Calc, Top -@appendix Reporting Bugs - -@noindent -If you find a bug in Calc, send e-mail to Jay Belanger, - -@example -jay.p.belanger@@gmail.com -@end example - -@noindent -There is an automatic command @kbd{M-x report-calc-bug} which helps -you to report bugs. This command prompts you for a brief subject -line, then leaves you in a mail editing buffer. Type @kbd{C-c C-c} to -send your mail. Make sure your subject line indicates that you are -reporting a Calc bug; this command sends mail to the maintainer's -regular mailbox. - -If you have suggestions for additional features for Calc, please send -them. Some have dared to suggest that Calc is already top-heavy with -features; this obviously cannot be the case, so if you have ideas, send -them right in. - -At the front of the source file, @file{calc.el}, is a list of ideas for -future work. If any enthusiastic souls wish to take it upon themselves -to work on these, please send a message (using @kbd{M-x report-calc-bug}) -so any efforts can be coordinated. - -The latest version of Calc is available from Savannah, in the Emacs -CVS tree. See @uref{http://savannah.gnu.org/projects/emacs}. - -@c [summary] -@node Summary, Key Index, Reporting Bugs, Top -@appendix Calc Summary - -@noindent -This section includes a complete list of Calc keystroke commands. -Each line lists the stack entries used by the command (top-of-stack -last), the keystrokes themselves, the prompts asked by the command, -and the result of the command (also with top-of-stack last). -The result is expressed using the equivalent algebraic function. -Commands which put no results on the stack show the full @kbd{M-x} -command name in that position. Numbers preceding the result or -command name refer to notes at the end. - -Algebraic functions and @kbd{M-x} commands that don't have corresponding -keystrokes are not listed in this summary. -@xref{Command Index}. @xref{Function Index}. - -@iftex -@begingroup -@tex -\vskip-2\baselineskip \null -\gdef\sumrow#1{\sumrowx#1\relax}% -\gdef\sumrowx#1\:#2\:#3\:#4\:#5\:#6\relax{% -\leavevmode% -{\smallfonts -\hbox to5em{\sl\hss#1}% -\hbox to5em{\tt#2\hss}% -\hbox to4em{\sl#3\hss}% -\hbox to5em{\rm\hss#4}% -\thinspace% -{\tt#5}% -{\sl#6}% -}}% -\gdef\sumlpar{{\rm(}}% -\gdef\sumrpar{{\rm)}}% -\gdef\sumcomma{{\rm,\thinspace}}% -\gdef\sumexcl{{\rm!}}% -\gdef\sumbreak{\vskip-2.5\baselineskip\goodbreak}% -\gdef\minus#1{{\tt-}}% -@end tex -@let@:=@sumsep -@let@r=@sumrow -@catcode`@(=@active @let(=@sumlpar -@catcode`@)=@active @let)=@sumrpar -@catcode`@,=@active @let,=@sumcomma -@catcode`@!=@active @let!=@sumexcl -@end iftex -@format -@iftex -@advance@baselineskip-2.5pt -@let@c@sumbreak -@end iftex -@r{ @: C-x * a @: @: 33 @:calc-embedded-activate@:} -@r{ @: C-x * b @: @: @:calc-big-or-small@:} -@r{ @: C-x * c @: @: @:calc@:} -@r{ @: C-x * d @: @: @:calc-embedded-duplicate@:} -@r{ @: C-x * e @: @: 34 @:calc-embedded@:} -@r{ @: C-x * f @:formula @: @:calc-embedded-new-formula@:} -@r{ @: C-x * g @: @: 35 @:calc-grab-region@:} -@r{ @: C-x * i @: @: @:calc-info@:} -@r{ @: C-x * j @: @: @:calc-embedded-select@:} -@r{ @: C-x * k @: @: @:calc-keypad@:} -@r{ @: C-x * l @: @: @:calc-load-everything@:} -@r{ @: C-x * m @: @: @:read-kbd-macro@:} -@r{ @: C-x * n @: @: 4 @:calc-embedded-next@:} -@r{ @: C-x * o @: @: @:calc-other-window@:} -@r{ @: C-x * p @: @: 4 @:calc-embedded-previous@:} -@r{ @: C-x * q @:formula @: @:quick-calc@:} -@r{ @: C-x * r @: @: 36 @:calc-grab-rectangle@:} -@r{ @: C-x * s @: @: @:calc-info-summary@:} -@r{ @: C-x * t @: @: @:calc-tutorial@:} -@r{ @: C-x * u @: @: @:calc-embedded-update-formula@:} -@r{ @: C-x * w @: @: @:calc-embedded-word@:} -@r{ @: C-x * x @: @: @:calc-quit@:} -@r{ @: C-x * y @: @:1,28,49 @:calc-copy-to-buffer@:} -@r{ @: C-x * z @: @: @:calc-user-invocation@:} -@r{ @: C-x * : @: @: 36 @:calc-grab-sum-down@:} -@r{ @: C-x * _ @: @: 36 @:calc-grab-sum-across@:} -@r{ @: C-x * ` @:editing @: 30 @:calc-embedded-edit@:} -@r{ @: C-x * 0 @:(zero) @: @:calc-reset@:} - -@c -@r{ @: 0-9 @:number @: @:@:number} -@r{ @: . @:number @: @:@:0.number} -@r{ @: _ @:number @: @:-@:number} -@r{ @: e @:number @: @:@:1e number} -@r{ @: # @:number @: @:@:current-radix@tfn{#}number} -@r{ @: P @:(in number) @: @:+/-@:} -@r{ @: M @:(in number) @: @:mod@:} -@r{ @: @@ ' " @: (in number)@: @:@:HMS form} -@r{ @: h m s @: (in number)@: @:@:HMS form} - -@c -@r{ @: ' @:formula @: 37,46 @:@:formula} -@r{ @: $ @:formula @: 37,46 @:$@:formula} -@r{ @: " @:string @: 37,46 @:@:string} - -@c -@r{ a b@: + @: @: 2 @:add@:(a,b) a+b} -@r{ a b@: - @: @: 2 @:sub@:(a,b) a@minus{}b} -@r{ a b@: * @: @: 2 @:mul@:(a,b) a b, a*b} -@r{ a b@: / @: @: 2 @:div@:(a,b) a/b} -@r{ a b@: ^ @: @: 2 @:pow@:(a,b) a^b} -@r{ a b@: I ^ @: @: 2 @:nroot@:(a,b) a^(1/b)} -@r{ a b@: % @: @: 2 @:mod@:(a,b) a%b} -@r{ a b@: \ @: @: 2 @:idiv@:(a,b) a\b} -@r{ a b@: : @: @: 2 @:fdiv@:(a,b)} -@r{ a b@: | @: @: 2 @:vconcat@:(a,b) a|b} -@r{ a b@: I | @: @: @:vconcat@:(b,a) b|a} -@r{ a b@: H | @: @: 2 @:append@:(a,b)} -@r{ a b@: I H | @: @: @:append@:(b,a)} -@r{ a@: & @: @: 1 @:inv@:(a) 1/a} -@r{ a@: ! @: @: 1 @:fact@:(a) a!} -@r{ a@: = @: @: 1 @:evalv@:(a)} -@r{ a@: M-% @: @: @:percent@:(a) a%} - -@c -@r{ ... a@: @summarykey{RET} @: @: 1 @:@:... a a} -@r{ ... a@: @summarykey{SPC} @: @: 1 @:@:... a a} -@r{... a b@: @summarykey{TAB} @: @: 3 @:@:... b a} -@r{. a b c@: M-@summarykey{TAB} @: @: 3 @:@:... b c a} -@r{... a b@: @summarykey{LFD} @: @: 1 @:@:... a b a} -@r{ ... a@: @summarykey{DEL} @: @: 1 @:@:...} -@r{... a b@: M-@summarykey{DEL} @: @: 1 @:@:... b} -@r{ @: M-@summarykey{RET} @: @: 4 @:calc-last-args@:} -@r{ a@: ` @:editing @: 1,30 @:calc-edit@:} - -@c -@r{ ... a@: C-d @: @: 1 @:@:...} -@r{ @: C-k @: @: 27 @:calc-kill@:} -@r{ @: C-w @: @: 27 @:calc-kill-region@:} -@r{ @: C-y @: @: @:calc-yank@:} -@r{ @: C-_ @: @: 4 @:calc-undo@:} -@r{ @: M-k @: @: 27 @:calc-copy-as-kill@:} -@r{ @: M-w @: @: 27 @:calc-copy-region-as-kill@:} - -@c -@r{ @: [ @: @: @:@:[...} -@r{[.. a b@: ] @: @: @:@:[a,b]} -@r{ @: ( @: @: @:@:(...} -@r{(.. a b@: ) @: @: @:@:(a,b)} -@r{ @: , @: @: @:@:vector or rect complex} -@r{ @: ; @: @: @:@:matrix or polar complex} -@r{ @: .. @: @: @:@:interval} - -@c -@r{ @: ~ @: @: @:calc-num-prefix@:} -@r{ @: < @: @: 4 @:calc-scroll-left@:} -@r{ @: > @: @: 4 @:calc-scroll-right@:} -@r{ @: @{ @: @: 4 @:calc-scroll-down@:} -@r{ @: @} @: @: 4 @:calc-scroll-up@:} -@r{ @: ? @: @: @:calc-help@:} - -@c -@r{ a@: n @: @: 1 @:neg@:(a) @minus{}a} -@r{ @: o @: @: 4 @:calc-realign@:} -@r{ @: p @:precision @: 31 @:calc-precision@:} -@r{ @: q @: @: @:calc-quit@:} -@r{ @: w @: @: @:calc-why@:} -@r{ @: x @:command @: @:M-x calc-@:command} -@r{ a@: y @: @:1,28,49 @:calc-copy-to-buffer@:} - -@c -@r{ a@: A @: @: 1 @:abs@:(a)} -@r{ a b@: B @: @: 2 @:log@:(a,b)} -@r{ a b@: I B @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: C @: @: 1 @:cos@:(a)} -@r{ a@: I C @: @: 1 @:arccos@:(a)} -@r{ a@: H C @: @: 1 @:cosh@:(a)} -@r{ a@: I H C @: @: 1 @:arccosh@:(a)} -@r{ @: D @: @: 4 @:calc-redo@:} -@r{ a@: E @: @: 1 @:exp@:(a)} -@r{ a@: H E @: @: 1 @:exp10@:(a) 10.^a} -@r{ a@: F @: @: 1,11 @:floor@:(a,d)} -@r{ a@: I F @: @: 1,11 @:ceil@:(a,d)} -@r{ a@: H F @: @: 1,11 @:ffloor@:(a,d)} -@r{ a@: I H F @: @: 1,11 @:fceil@:(a,d)} -@r{ a@: G @: @: 1 @:arg@:(a)} -@r{ @: H @:command @: 32 @:@:Hyperbolic} -@r{ @: I @:command @: 32 @:@:Inverse} -@r{ a@: J @: @: 1 @:conj@:(a)} -@r{ @: K @:command @: 32 @:@:Keep-args} -@r{ a@: L @: @: 1 @:ln@:(a)} -@r{ a@: H L @: @: 1 @:log10@:(a)} -@r{ @: M @: @: @:calc-more-recursion-depth@:} -@r{ @: I M @: @: @:calc-less-recursion-depth@:} -@r{ a@: N @: @: 5 @:evalvn@:(a)} -@r{ @: P @: @: @:@:pi} -@r{ @: I P @: @: @:@:gamma} -@r{ @: H P @: @: @:@:e} -@r{ @: I H P @: @: @:@:phi} -@r{ a@: Q @: @: 1 @:sqrt@:(a)} -@r{ a@: I Q @: @: 1 @:sqr@:(a) a^2} -@r{ a@: R @: @: 1,11 @:round@:(a,d)} -@r{ a@: I R @: @: 1,11 @:trunc@:(a,d)} -@r{ a@: H R @: @: 1,11 @:fround@:(a,d)} -@r{ a@: I H R @: @: 1,11 @:ftrunc@:(a,d)} -@r{ a@: S @: @: 1 @:sin@:(a)} -@r{ a@: I S @: @: 1 @:arcsin@:(a)} -@r{ a@: H S @: @: 1 @:sinh@:(a)} -@r{ a@: I H S @: @: 1 @:arcsinh@:(a)} -@r{ a@: T @: @: 1 @:tan@:(a)} -@r{ a@: I T @: @: 1 @:arctan@:(a)} -@r{ a@: H T @: @: 1 @:tanh@:(a)} -@r{ a@: I H T @: @: 1 @:arctanh@:(a)} -@r{ @: U @: @: 4 @:calc-undo@:} -@r{ @: X @: @: 4 @:calc-call-last-kbd-macro@:} - -@c -@r{ a b@: a = @: @: 2 @:eq@:(a,b) a=b} -@r{ a b@: a # @: @: 2 @:neq@:(a,b) a!=b} -@r{ a b@: a < @: @: 2 @:lt@:(a,b) a @: @: 2 @:gt@:(a,b) a>b} -@r{ a b@: a [ @: @: 2 @:leq@:(a,b) a<=b} -@r{ a b@: a ] @: @: 2 @:geq@:(a,b) a>=b} -@r{ a b@: a @{ @: @: 2 @:in@:(a,b)} -@r{ a b@: a & @: @: 2,45 @:land@:(a,b) a&&b} -@r{ a b@: a | @: @: 2,45 @:lor@:(a,b) a||b} -@r{ a@: a ! @: @: 1,45 @:lnot@:(a) !a} -@r{ a b c@: a : @: @: 45 @:if@:(a,b,c) a?b:c} -@r{ a@: a . @: @: 1 @:rmeq@:(a)} -@r{ a@: a " @: @: 7,8 @:calc-expand-formula@:} - -@c -@r{ a@: a + @:i, l, h @: 6,38 @:sum@:(a,i,l,h)} -@r{ a@: a - @:i, l, h @: 6,38 @:asum@:(a,i,l,h)} -@r{ a@: a * @:i, l, h @: 6,38 @:prod@:(a,i,l,h)} -@r{ a b@: a _ @: @: 2 @:subscr@:(a,b) a_b} - -@c -@r{ a b@: a \ @: @: 2 @:pdiv@:(a,b)} -@r{ a b@: a % @: @: 2 @:prem@:(a,b)} -@r{ a b@: a / @: @: 2 @:pdivrem@:(a,b) [q,r]} -@r{ a b@: H a / @: @: 2 @:pdivide@:(a,b) q+r/b} - -@c -@r{ a@: a a @: @: 1 @:apart@:(a)} -@r{ a@: a b @:old, new @: 38 @:subst@:(a,old,new)} -@r{ a@: a c @:v @: 38 @:collect@:(a,v)} -@r{ a@: a d @:v @: 4,38 @:deriv@:(a,v)} -@r{ a@: H a d @:v @: 4,38 @:tderiv@:(a,v)} -@r{ a@: a e @: @: @:esimplify@:(a)} -@r{ a@: a f @: @: 1 @:factor@:(a)} -@r{ a@: H a f @: @: 1 @:factors@:(a)} -@r{ a b@: a g @: @: 2 @:pgcd@:(a,b)} -@r{ a@: a i @:v @: 38 @:integ@:(a,v)} -@r{ a@: a m @:pats @: 38 @:match@:(a,pats)} -@r{ a@: I a m @:pats @: 38 @:matchnot@:(a,pats)} -@r{ data x@: a p @: @: 28 @:polint@:(data,x)} -@r{ data x@: H a p @: @: 28 @:ratint@:(data,x)} -@r{ a@: a n @: @: 1 @:nrat@:(a)} -@r{ a@: a r @:rules @:4,8,38 @:rewrite@:(a,rules,n)} -@r{ a@: a s @: @: @:simplify@:(a)} -@r{ a@: a t @:v, n @: 31,39 @:taylor@:(a,v,n)} -@r{ a@: a v @: @: 7,8 @:calc-alg-evaluate@:} -@r{ a@: a x @: @: 4,8 @:expand@:(a)} - -@c -@r{ data@: a F @:model, vars @: 48 @:fit@:(m,iv,pv,data)} -@r{ data@: I a F @:model, vars @: 48 @:xfit@:(m,iv,pv,data)} -@r{ data@: H a F @:model, vars @: 48 @:efit@:(m,iv,pv,data)} -@r{ a@: a I @:v, l, h @: 38 @:ninteg@:(a,v,l,h)} -@r{ a b@: a M @:op @: 22 @:mapeq@:(op,a,b)} -@r{ a b@: I a M @:op @: 22 @:mapeqr@:(op,a,b)} -@r{ a b@: H a M @:op @: 22 @:mapeqp@:(op,a,b)} -@r{ a g@: a N @:v @: 38 @:minimize@:(a,v,g)} -@r{ a g@: H a N @:v @: 38 @:wminimize@:(a,v,g)} -@r{ a@: a P @:v @: 38 @:roots@:(a,v)} -@r{ a g@: a R @:v @: 38 @:root@:(a,v,g)} -@r{ a g@: H a R @:v @: 38 @:wroot@:(a,v,g)} -@r{ a@: a S @:v @: 38 @:solve@:(a,v)} -@r{ a@: I a S @:v @: 38 @:finv@:(a,v)} -@r{ a@: H a S @:v @: 38 @:fsolve@:(a,v)} -@r{ a@: I H a S @:v @: 38 @:ffinv@:(a,v)} -@r{ a@: a T @:i, l, h @: 6,38 @:table@:(a,i,l,h)} -@r{ a g@: a X @:v @: 38 @:maximize@:(a,v,g)} -@r{ a g@: H a X @:v @: 38 @:wmaximize@:(a,v,g)} - -@c -@r{ a b@: b a @: @: 9 @:and@:(a,b,w)} -@r{ a@: b c @: @: 9 @:clip@:(a,w)} -@r{ a b@: b d @: @: 9 @:diff@:(a,b,w)} -@r{ a@: b l @: @: 10 @:lsh@:(a,n,w)} -@r{ a n@: H b l @: @: 9 @:lsh@:(a,n,w)} -@r{ a@: b n @: @: 9 @:not@:(a,w)} -@r{ a b@: b o @: @: 9 @:or@:(a,b,w)} -@r{ v@: b p @: @: 1 @:vpack@:(v)} -@r{ a@: b r @: @: 10 @:rsh@:(a,n,w)} -@r{ a n@: H b r @: @: 9 @:rsh@:(a,n,w)} -@r{ a@: b t @: @: 10 @:rot@:(a,n,w)} -@r{ a n@: H b t @: @: 9 @:rot@:(a,n,w)} -@r{ a@: b u @: @: 1 @:vunpack@:(a)} -@r{ @: b w @:w @: 9,50 @:calc-word-size@:} -@r{ a b@: b x @: @: 9 @:xor@:(a,b,w)} - -@c -@r{c s l p@: b D @: @: @:ddb@:(c,s,l,p)} -@r{ r n p@: b F @: @: @:fv@:(r,n,p)} -@r{ r n p@: I b F @: @: @:fvb@:(r,n,p)} -@r{ r n p@: H b F @: @: @:fvl@:(r,n,p)} -@r{ v@: b I @: @: 19 @:irr@:(v)} -@r{ v@: I b I @: @: 19 @:irrb@:(v)} -@r{ a@: b L @: @: 10 @:ash@:(a,n,w)} -@r{ a n@: H b L @: @: 9 @:ash@:(a,n,w)} -@r{ r n a@: b M @: @: @:pmt@:(r,n,a)} -@r{ r n a@: I b M @: @: @:pmtb@:(r,n,a)} -@r{ r n a@: H b M @: @: @:pmtl@:(r,n,a)} -@r{ r v@: b N @: @: 19 @:npv@:(r,v)} -@r{ r v@: I b N @: @: 19 @:npvb@:(r,v)} -@r{ r n p@: b P @: @: @:pv@:(r,n,p)} -@r{ r n p@: I b P @: @: @:pvb@:(r,n,p)} -@r{ r n p@: H b P @: @: @:pvl@:(r,n,p)} -@r{ a@: b R @: @: 10 @:rash@:(a,n,w)} -@r{ a n@: H b R @: @: 9 @:rash@:(a,n,w)} -@r{ c s l@: b S @: @: @:sln@:(c,s,l)} -@r{ n p a@: b T @: @: @:rate@:(n,p,a)} -@r{ n p a@: I b T @: @: @:rateb@:(n,p,a)} -@r{ n p a@: H b T @: @: @:ratel@:(n,p,a)} -@r{c s l p@: b Y @: @: @:syd@:(c,s,l,p)} - -@r{ r p a@: b # @: @: @:nper@:(r,p,a)} -@r{ r p a@: I b # @: @: @:nperb@:(r,p,a)} -@r{ r p a@: H b # @: @: @:nperl@:(r,p,a)} -@r{ a b@: b % @: @: @:relch@:(a,b)} - -@c -@r{ a@: c c @: @: 5 @:pclean@:(a,p)} -@r{ a@: c 0-9 @: @: @:pclean@:(a,p)} -@r{ a@: H c c @: @: 5 @:clean@:(a,p)} -@r{ a@: H c 0-9 @: @: @:clean@:(a,p)} -@r{ a@: c d @: @: 1 @:deg@:(a)} -@r{ a@: c f @: @: 1 @:pfloat@:(a)} -@r{ a@: H c f @: @: 1 @:float@:(a)} -@r{ a@: c h @: @: 1 @:hms@:(a)} -@r{ a@: c p @: @: @:polar@:(a)} -@r{ a@: I c p @: @: @:rect@:(a)} -@r{ a@: c r @: @: 1 @:rad@:(a)} - -@c -@r{ a@: c F @: @: 5 @:pfrac@:(a,p)} -@r{ a@: H c F @: @: 5 @:frac@:(a,p)} - -@c -@r{ a@: c % @: @: @:percent@:(a*100)} - -@c -@r{ @: d . @:char @: 50 @:calc-point-char@:} -@r{ @: d , @:char @: 50 @:calc-group-char@:} -@r{ @: d < @: @: 13,50 @:calc-left-justify@:} -@r{ @: d = @: @: 13,50 @:calc-center-justify@:} -@r{ @: d > @: @: 13,50 @:calc-right-justify@:} -@r{ @: d @{ @:label @: 50 @:calc-left-label@:} -@r{ @: d @} @:label @: 50 @:calc-right-label@:} -@r{ @: d [ @: @: 4 @:calc-truncate-up@:} -@r{ @: d ] @: @: 4 @:calc-truncate-down@:} -@r{ @: d " @: @: 12,50 @:calc-display-strings@:} -@r{ @: d @summarykey{SPC} @: @: @:calc-refresh@:} -@r{ @: d @summarykey{RET} @: @: 1 @:calc-refresh-top@:} - -@c -@r{ @: d 0 @: @: 50 @:calc-decimal-radix@:} -@r{ @: d 2 @: @: 50 @:calc-binary-radix@:} -@r{ @: d 6 @: @: 50 @:calc-hex-radix@:} -@r{ @: d 8 @: @: 50 @:calc-octal-radix@:} - -@c -@r{ @: d b @: @:12,13,50 @:calc-line-breaking@:} -@r{ @: d c @: @: 50 @:calc-complex-notation@:} -@r{ @: d d @:format @: 50 @:calc-date-notation@:} -@r{ @: d e @: @: 5,50 @:calc-eng-notation@:} -@r{ @: d f @:num @: 31,50 @:calc-fix-notation@:} -@r{ @: d g @: @:12,13,50 @:calc-group-digits@:} -@r{ @: d h @:format @: 50 @:calc-hms-notation@:} -@r{ @: d i @: @: 50 @:calc-i-notation@:} -@r{ @: d j @: @: 50 @:calc-j-notation@:} -@r{ @: d l @: @: 12,50 @:calc-line-numbering@:} -@r{ @: d n @: @: 5,50 @:calc-normal-notation@:} -@r{ @: d o @:format @: 50 @:calc-over-notation@:} -@r{ @: d p @: @: 12,50 @:calc-show-plain@:} -@r{ @: d r @:radix @: 31,50 @:calc-radix@:} -@r{ @: d s @: @: 5,50 @:calc-sci-notation@:} -@r{ @: d t @: @: 27 @:calc-truncate-stack@:} -@r{ @: d w @: @: 12,13 @:calc-auto-why@:} -@r{ @: d z @: @: 12,50 @:calc-leading-zeros@:} - -@c -@r{ @: d B @: @: 50 @:calc-big-language@:} -@r{ @: d C @: @: 50 @:calc-c-language@:} -@r{ @: d E @: @: 50 @:calc-eqn-language@:} -@r{ @: d F @: @: 50 @:calc-fortran-language@:} -@r{ @: d M @: @: 50 @:calc-mathematica-language@:} -@r{ @: d N @: @: 50 @:calc-normal-language@:} -@r{ @: d O @: @: 50 @:calc-flat-language@:} -@r{ @: d P @: @: 50 @:calc-pascal-language@:} -@r{ @: d T @: @: 50 @:calc-tex-language@:} -@r{ @: d L @: @: 50 @:calc-latex-language@:} -@r{ @: d U @: @: 50 @:calc-unformatted-language@:} -@r{ @: d W @: @: 50 @:calc-maple-language@:} - -@c -@r{ a@: f [ @: @: 4 @:decr@:(a,n)} -@r{ a@: f ] @: @: 4 @:incr@:(a,n)} - -@c -@r{ a b@: f b @: @: 2 @:beta@:(a,b)} -@r{ a@: f e @: @: 1 @:erf@:(a)} -@r{ a@: I f e @: @: 1 @:erfc@:(a)} -@r{ a@: f g @: @: 1 @:gamma@:(a)} -@r{ a b@: f h @: @: 2 @:hypot@:(a,b)} -@r{ a@: f i @: @: 1 @:im@:(a)} -@r{ n a@: f j @: @: 2 @:besJ@:(n,a)} -@r{ a b@: f n @: @: 2 @:min@:(a,b)} -@r{ a@: f r @: @: 1 @:re@:(a)} -@r{ a@: f s @: @: 1 @:sign@:(a)} -@r{ a b@: f x @: @: 2 @:max@:(a,b)} -@r{ n a@: f y @: @: 2 @:besY@:(n,a)} - -@c -@r{ a@: f A @: @: 1 @:abssqr@:(a)} -@r{ x a b@: f B @: @: @:betaI@:(x,a,b)} -@r{ x a b@: H f B @: @: @:betaB@:(x,a,b)} -@r{ a@: f E @: @: 1 @:expm1@:(a)} -@r{ a x@: f G @: @: 2 @:gammaP@:(a,x)} -@r{ a x@: I f G @: @: 2 @:gammaQ@:(a,x)} -@r{ a x@: H f G @: @: 2 @:gammag@:(a,x)} -@r{ a x@: I H f G @: @: 2 @:gammaG@:(a,x)} -@r{ a b@: f I @: @: 2 @:ilog@:(a,b)} -@r{ a b@: I f I @: @: 2 @:alog@:(a,b) b^a} -@r{ a@: f L @: @: 1 @:lnp1@:(a)} -@r{ a@: f M @: @: 1 @:mant@:(a)} -@r{ a@: f Q @: @: 1 @:isqrt@:(a)} -@r{ a@: I f Q @: @: 1 @:sqr@:(a) a^2} -@r{ a n@: f S @: @: 2 @:scf@:(a,n)} -@r{ y x@: f T @: @: @:arctan2@:(y,x)} -@r{ a@: f X @: @: 1 @:xpon@:(a)} - -@c -@r{ x y@: g a @: @: 28,40 @:calc-graph-add@:} -@r{ @: g b @: @: 12 @:calc-graph-border@:} -@r{ @: g c @: @: @:calc-graph-clear@:} -@r{ @: g d @: @: 41 @:calc-graph-delete@:} -@r{ x y@: g f @: @: 28,40 @:calc-graph-fast@:} -@r{ @: g g @: @: 12 @:calc-graph-grid@:} -@r{ @: g h @:title @: @:calc-graph-header@:} -@r{ @: g j @: @: 4 @:calc-graph-juggle@:} -@r{ @: g k @: @: 12 @:calc-graph-key@:} -@r{ @: g l @: @: 12 @:calc-graph-log-x@:} -@r{ @: g n @:name @: @:calc-graph-name@:} -@r{ @: g p @: @: 42 @:calc-graph-plot@:} -@r{ @: g q @: @: @:calc-graph-quit@:} -@r{ @: g r @:range @: @:calc-graph-range-x@:} -@r{ @: g s @: @: 12,13 @:calc-graph-line-style@:} -@r{ @: g t @:title @: @:calc-graph-title-x@:} -@r{ @: g v @: @: @:calc-graph-view-commands@:} -@r{ @: g x @:display @: @:calc-graph-display@:} -@r{ @: g z @: @: 12 @:calc-graph-zero-x@:} - -@c -@r{ x y z@: g A @: @: 28,40 @:calc-graph-add-3d@:} -@r{ @: g C @:command @: @:calc-graph-command@:} -@r{ @: g D @:device @: 43,44 @:calc-graph-device@:} -@r{ x y z@: g F @: @: 28,40 @:calc-graph-fast-3d@:} -@r{ @: g H @: @: 12 @:calc-graph-hide@:} -@r{ @: g K @: @: @:calc-graph-kill@:} -@r{ @: g L @: @: 12 @:calc-graph-log-y@:} -@r{ @: g N @:number @: 43,51 @:calc-graph-num-points@:} -@r{ @: g O @:filename @: 43,44 @:calc-graph-output@:} -@r{ @: g P @: @: 42 @:calc-graph-print@:} -@r{ @: g R @:range @: @:calc-graph-range-y@:} -@r{ @: g S @: @: 12,13 @:calc-graph-point-style@:} -@r{ @: g T @:title @: @:calc-graph-title-y@:} -@r{ @: g V @: @: @:calc-graph-view-trail@:} -@r{ @: g X @:format @: @:calc-graph-geometry@:} -@r{ @: g Z @: @: 12 @:calc-graph-zero-y@:} - -@c -@r{ @: g C-l @: @: 12 @:calc-graph-log-z@:} -@r{ @: g C-r @:range @: @:calc-graph-range-z@:} -@r{ @: g C-t @:title @: @:calc-graph-title-z@:} - -@c -@r{ @: h b @: @: @:calc-describe-bindings@:} -@r{ @: h c @:key @: @:calc-describe-key-briefly@:} -@r{ @: h f @:function @: @:calc-describe-function@:} -@r{ @: h h @: @: @:calc-full-help@:} -@r{ @: h i @: @: @:calc-info@:} -@r{ @: h k @:key @: @:calc-describe-key@:} -@r{ @: h n @: @: @:calc-view-news@:} -@r{ @: h s @: @: @:calc-info-summary@:} -@r{ @: h t @: @: @:calc-tutorial@:} -@r{ @: h v @:var @: @:calc-describe-variable@:} - -@c -@r{ @: j 1-9 @: @: @:calc-select-part@:} -@r{ @: j @summarykey{RET} @: @: 27 @:calc-copy-selection@:} -@r{ @: j @summarykey{DEL} @: @: 27 @:calc-del-selection@:} -@r{ @: j ' @:formula @: 27 @:calc-enter-selection@:} -@r{ @: j ` @:editing @: 27,30 @:calc-edit-selection@:} -@r{ @: j " @: @: 7,27 @:calc-sel-expand-formula@:} - -@c -@r{ @: j + @:formula @: 27 @:calc-sel-add-both-sides@:} -@r{ @: j - @:formula @: 27 @:calc-sel-sub-both-sides@:} -@r{ @: j * @:formula @: 27 @:calc-sel-mul-both-sides@:} -@r{ @: j / @:formula @: 27 @:calc-sel-div-both-sides@:} -@r{ @: j & @: @: 27 @:calc-sel-invert@:} - -@c -@r{ @: j a @: @: 27 @:calc-select-additional@:} -@r{ @: j b @: @: 12 @:calc-break-selections@:} -@r{ @: j c @: @: @:calc-clear-selections@:} -@r{ @: j d @: @: 12,50 @:calc-show-selections@:} -@r{ @: j e @: @: 12 @:calc-enable-selections@:} -@r{ @: j l @: @: 4,27 @:calc-select-less@:} -@r{ @: j m @: @: 4,27 @:calc-select-more@:} -@r{ @: j n @: @: 4 @:calc-select-next@:} -@r{ @: j o @: @: 4,27 @:calc-select-once@:} -@r{ @: j p @: @: 4 @:calc-select-previous@:} -@r{ @: j r @:rules @:4,8,27 @:calc-rewrite-selection@:} -@r{ @: j s @: @: 4,27 @:calc-select-here@:} -@r{ @: j u @: @: 27 @:calc-unselect@:} -@r{ @: j v @: @: 7,27 @:calc-sel-evaluate@:} - -@c -@r{ @: j C @: @: 27 @:calc-sel-commute@:} -@r{ @: j D @: @: 4,27 @:calc-sel-distribute@:} -@r{ @: j E @: @: 27 @:calc-sel-jump-equals@:} -@r{ @: j I @: @: 27 @:calc-sel-isolate@:} -@r{ @: H j I @: @: 27 @:calc-sel-isolate@: (full)} -@r{ @: j L @: @: 4,27 @:calc-commute-left@:} -@r{ @: j M @: @: 27 @:calc-sel-merge@:} -@r{ @: j N @: @: 27 @:calc-sel-negate@:} -@r{ @: j O @: @: 4,27 @:calc-select-once-maybe@:} -@r{ @: j R @: @: 4,27 @:calc-commute-right@:} -@r{ @: j S @: @: 4,27 @:calc-select-here-maybe@:} -@r{ @: j U @: @: 27 @:calc-sel-unpack@:} - -@c -@r{ @: k a @: @: @:calc-random-again@:} -@r{ n@: k b @: @: 1 @:bern@:(n)} -@r{ n x@: H k b @: @: 2 @:bern@:(n,x)} -@r{ n m@: k c @: @: 2 @:choose@:(n,m)} -@r{ n m@: H k c @: @: 2 @:perm@:(n,m)} -@r{ n@: k d @: @: 1 @:dfact@:(n) n!!} -@r{ n@: k e @: @: 1 @:euler@:(n)} -@r{ n x@: H k e @: @: 2 @:euler@:(n,x)} -@r{ n@: k f @: @: 4 @:prfac@:(n)} -@r{ n m@: k g @: @: 2 @:gcd@:(n,m)} -@r{ m n@: k h @: @: 14 @:shuffle@:(n,m)} -@r{ n m@: k l @: @: 2 @:lcm@:(n,m)} -@r{ n@: k m @: @: 1 @:moebius@:(n)} -@r{ n@: k n @: @: 4 @:nextprime@:(n)} -@r{ n@: I k n @: @: 4 @:prevprime@:(n)} -@r{ n@: k p @: @: 4,28 @:calc-prime-test@:} -@r{ m@: k r @: @: 14 @:random@:(m)} -@r{ n m@: k s @: @: 2 @:stir1@:(n,m)} -@r{ n m@: H k s @: @: 2 @:stir2@:(n,m)} -@r{ n@: k t @: @: 1 @:totient@:(n)} - -@c -@r{ n p x@: k B @: @: @:utpb@:(x,n,p)} -@r{ n p x@: I k B @: @: @:ltpb@:(x,n,p)} -@r{ v x@: k C @: @: @:utpc@:(x,v)} -@r{ v x@: I k C @: @: @:ltpc@:(x,v)} -@r{ n m@: k E @: @: @:egcd@:(n,m)} -@r{v1 v2 x@: k F @: @: @:utpf@:(x,v1,v2)} -@r{v1 v2 x@: I k F @: @: @:ltpf@:(x,v1,v2)} -@r{ m s x@: k N @: @: @:utpn@:(x,m,s)} -@r{ m s x@: I k N @: @: @:ltpn@:(x,m,s)} -@r{ m x@: k P @: @: @:utpp@:(x,m)} -@r{ m x@: I k P @: @: @:ltpp@:(x,m)} -@r{ v x@: k T @: @: @:utpt@:(x,v)} -@r{ v x@: I k T @: @: @:ltpt@:(x,v)} - -@c -@r{ @: m a @: @: 12,13 @:calc-algebraic-mode@:} -@r{ @: m d @: @: @:calc-degrees-mode@:} -@r{ @: m e @: @: @:calc-embedded-preserve-modes@:} -@r{ @: m f @: @: 12 @:calc-frac-mode@:} -@r{ @: m g @: @: 52 @:calc-get-modes@:} -@r{ @: m h @: @: @:calc-hms-mode@:} -@r{ @: m i @: @: 12,13 @:calc-infinite-mode@:} -@r{ @: m m @: @: @:calc-save-modes@:} -@r{ @: m p @: @: 12 @:calc-polar-mode@:} -@r{ @: m r @: @: @:calc-radians-mode@:} -@r{ @: m s @: @: 12 @:calc-symbolic-mode@:} -@r{ @: m t @: @: 12 @:calc-total-algebraic-mode@:} -@r{ @: m v @: @: 12,13 @:calc-matrix-mode@:} -@r{ @: m w @: @: 13 @:calc-working@:} -@r{ @: m x @: @: @:calc-always-load-extensions@:} - -@c -@r{ @: m A @: @: 12 @:calc-alg-simplify-mode@:} -@r{ @: m B @: @: 12 @:calc-bin-simplify-mode@:} -@r{ @: m C @: @: 12 @:calc-auto-recompute@:} -@r{ @: m D @: @: @:calc-default-simplify-mode@:} -@r{ @: m E @: @: 12 @:calc-ext-simplify-mode@:} -@r{ @: m F @:filename @: 13 @:calc-settings-file-name@:} -@r{ @: m N @: @: 12 @:calc-num-simplify-mode@:} -@r{ @: m O @: @: 12 @:calc-no-simplify-mode@:} -@r{ @: m R @: @: 12,13 @:calc-mode-record-mode@:} -@r{ @: m S @: @: 12 @:calc-shift-prefix@:} -@r{ @: m U @: @: 12 @:calc-units-simplify-mode@:} - -@c -@r{ @: r s @:register @: 27 @:calc-copy-to-register@:} -@r{ @: r i @:register @: @:calc-insert-register@:} - -@c -@r{ @: s c @:var1, var2 @: 29 @:calc-copy-variable@:} -@r{ @: s d @:var, decl @: @:calc-declare-variable@:} -@r{ @: s e @:var, editing @: 29,30 @:calc-edit-variable@:} -@r{ @: s i @:buffer @: @:calc-insert-variables@:} -@r{ @: s k @:const, var @: 29 @:calc-copy-special-constant@:} -@r{ a b@: s l @:var @: 29 @:@:a (letting var=b)} -@r{ a ...@: s m @:op, var @: 22,29 @:calc-store-map@:} -@r{ @: s n @:var @: 29,47 @:calc-store-neg@: (v/-1)} -@r{ @: s p @:var @: 29 @:calc-permanent-variable@:} -@r{ @: s r @:var @: 29 @:@:v (recalled value)} -@r{ @: r 0-9 @: @: @:calc-recall-quick@:} -@r{ a@: s s @:var @: 28,29 @:calc-store@:} -@r{ a@: s 0-9 @: @: @:calc-store-quick@:} -@r{ a@: s t @:var @: 29 @:calc-store-into@:} -@r{ a@: t 0-9 @: @: @:calc-store-into-quick@:} -@r{ @: s u @:var @: 29 @:calc-unstore@:} -@r{ a@: s x @:var @: 29 @:calc-store-exchange@:} - -@c -@r{ @: s A @:editing @: 30 @:calc-edit-AlgSimpRules@:} -@r{ @: s D @:editing @: 30 @:calc-edit-Decls@:} -@r{ @: s E @:editing @: 30 @:calc-edit-EvalRules@:} -@r{ @: s F @:editing @: 30 @:calc-edit-FitRules@:} -@r{ @: s G @:editing @: 30 @:calc-edit-GenCount@:} -@r{ @: s H @:editing @: 30 @:calc-edit-Holidays@:} -@r{ @: s I @:editing @: 30 @:calc-edit-IntegLimit@:} -@r{ @: s L @:editing @: 30 @:calc-edit-LineStyles@:} -@r{ @: s P @:editing @: 30 @:calc-edit-PointStyles@:} -@r{ @: s R @:editing @: 30 @:calc-edit-PlotRejects@:} -@r{ @: s T @:editing @: 30 @:calc-edit-TimeZone@:} -@r{ @: s U @:editing @: 30 @:calc-edit-Units@:} -@r{ @: s X @:editing @: 30 @:calc-edit-ExtSimpRules@:} - -@c -@r{ a@: s + @:var @: 29,47 @:calc-store-plus@: (v+a)} -@r{ a@: s - @:var @: 29,47 @:calc-store-minus@: (v-a)} -@r{ a@: s * @:var @: 29,47 @:calc-store-times@: (v*a)} -@r{ a@: s / @:var @: 29,47 @:calc-store-div@: (v/a)} -@r{ a@: s ^ @:var @: 29,47 @:calc-store-power@: (v^a)} -@r{ a@: s | @:var @: 29,47 @:calc-store-concat@: (v|a)} -@r{ @: s & @:var @: 29,47 @:calc-store-inv@: (v^-1)} -@r{ @: s [ @:var @: 29,47 @:calc-store-decr@: (v-1)} -@r{ @: s ] @:var @: 29,47 @:calc-store-incr@: (v-(-1))} -@r{ a b@: s : @: @: 2 @:assign@:(a,b) a @tfn{:=} b} -@r{ a@: s = @: @: 1 @:evalto@:(a,b) a @tfn{=>}} - -@c -@r{ @: t [ @: @: 4 @:calc-trail-first@:} -@r{ @: t ] @: @: 4 @:calc-trail-last@:} -@r{ @: t < @: @: 4 @:calc-trail-scroll-left@:} -@r{ @: t > @: @: 4 @:calc-trail-scroll-right@:} -@r{ @: t . @: @: 12 @:calc-full-trail-vectors@:} - -@c -@r{ @: t b @: @: 4 @:calc-trail-backward@:} -@r{ @: t d @: @: 12,50 @:calc-trail-display@:} -@r{ @: t f @: @: 4 @:calc-trail-forward@:} -@r{ @: t h @: @: @:calc-trail-here@:} -@r{ @: t i @: @: @:calc-trail-in@:} -@r{ @: t k @: @: 4 @:calc-trail-kill@:} -@r{ @: t m @:string @: @:calc-trail-marker@:} -@r{ @: t n @: @: 4 @:calc-trail-next@:} -@r{ @: t o @: @: @:calc-trail-out@:} -@r{ @: t p @: @: 4 @:calc-trail-previous@:} -@r{ @: t r @:string @: @:calc-trail-isearch-backward@:} -@r{ @: t s @:string @: @:calc-trail-isearch-forward@:} -@r{ @: t y @: @: 4 @:calc-trail-yank@:} - -@c -@r{ d@: t C @:oz, nz @: @:tzconv@:(d,oz,nz)} -@r{d oz nz@: t C @:$ @: @:tzconv@:(d,oz,nz)} -@r{ d@: t D @: @: 15 @:date@:(d)} -@r{ d@: t I @: @: 4 @:incmonth@:(d,n)} -@r{ d@: t J @: @: 16 @:julian@:(d,z)} -@r{ d@: t M @: @: 17 @:newmonth@:(d,n)} -@r{ @: t N @: @: 16 @:now@:(z)} -@r{ d@: t P @:1 @: 31 @:year@:(d)} -@r{ d@: t P @:2 @: 31 @:month@:(d)} -@r{ d@: t P @:3 @: 31 @:day@:(d)} -@r{ d@: t P @:4 @: 31 @:hour@:(d)} -@r{ d@: t P @:5 @: 31 @:minute@:(d)} -@r{ d@: t P @:6 @: 31 @:second@:(d)} -@r{ d@: t P @:7 @: 31 @:weekday@:(d)} -@r{ d@: t P @:8 @: 31 @:yearday@:(d)} -@r{ d@: t P @:9 @: 31 @:time@:(d)} -@r{ d@: t U @: @: 16 @:unixtime@:(d,z)} -@r{ d@: t W @: @: 17 @:newweek@:(d,w)} -@r{ d@: t Y @: @: 17 @:newyear@:(d,n)} - -@c -@r{ a b@: t + @: @: 2 @:badd@:(a,b)} -@r{ a b@: t - @: @: 2 @:bsub@:(a,b)} - -@c -@r{ @: u a @: @: 12 @:calc-autorange-units@:} -@r{ a@: u b @: @: @:calc-base-units@:} -@r{ a@: u c @:units @: 18 @:calc-convert-units@:} -@r{ defn@: u d @:unit, descr @: @:calc-define-unit@:} -@r{ @: u e @: @: @:calc-explain-units@:} -@r{ @: u g @:unit @: @:calc-get-unit-definition@:} -@r{ @: u p @: @: @:calc-permanent-units@:} -@r{ a@: u r @: @: @:calc-remove-units@:} -@r{ a@: u s @: @: @:usimplify@:(a)} -@r{ a@: u t @:units @: 18 @:calc-convert-temperature@:} -@r{ @: u u @:unit @: @:calc-undefine-unit@:} -@r{ @: u v @: @: @:calc-enter-units-table@:} -@r{ a@: u x @: @: @:calc-extract-units@:} -@r{ a@: u 0-9 @: @: @:calc-quick-units@:} - -@c -@r{ v1 v2@: u C @: @: 20 @:vcov@:(v1,v2)} -@r{ v1 v2@: I u C @: @: 20 @:vpcov@:(v1,v2)} -@r{ v1 v2@: H u C @: @: 20 @:vcorr@:(v1,v2)} -@r{ v@: u G @: @: 19 @:vgmean@:(v)} -@r{ a b@: H u G @: @: 2 @:agmean@:(a,b)} -@r{ v@: u M @: @: 19 @:vmean@:(v)} -@r{ v@: I u M @: @: 19 @:vmeane@:(v)} -@r{ v@: H u M @: @: 19 @:vmedian@:(v)} -@r{ v@: I H u M @: @: 19 @:vhmean@:(v)} -@r{ v@: u N @: @: 19 @:vmin@:(v)} -@r{ v@: u S @: @: 19 @:vsdev@:(v)} -@r{ v@: I u S @: @: 19 @:vpsdev@:(v)} -@r{ v@: H u S @: @: 19 @:vvar@:(v)} -@r{ v@: I H u S @: @: 19 @:vpvar@:(v)} -@r{ @: u V @: @: @:calc-view-units-table@:} -@r{ v@: u X @: @: 19 @:vmax@:(v)} - -@c -@r{ v@: u + @: @: 19 @:vsum@:(v)} -@r{ v@: u * @: @: 19 @:vprod@:(v)} -@r{ v@: u # @: @: 19 @:vcount@:(v)} - -@c -@r{ @: V ( @: @: 50 @:calc-vector-parens@:} -@r{ @: V @{ @: @: 50 @:calc-vector-braces@:} -@r{ @: V [ @: @: 50 @:calc-vector-brackets@:} -@r{ @: V ] @:ROCP @: 50 @:calc-matrix-brackets@:} -@r{ @: V , @: @: 50 @:calc-vector-commas@:} -@r{ @: V < @: @: 50 @:calc-matrix-left-justify@:} -@r{ @: V = @: @: 50 @:calc-matrix-center-justify@:} -@r{ @: V > @: @: 50 @:calc-matrix-right-justify@:} -@r{ @: V / @: @: 12,50 @:calc-break-vectors@:} -@r{ @: V . @: @: 12,50 @:calc-full-vectors@:} - -@c -@r{ s t@: V ^ @: @: 2 @:vint@:(s,t)} -@r{ s t@: V - @: @: 2 @:vdiff@:(s,t)} -@r{ s@: V ~ @: @: 1 @:vcompl@:(s)} -@r{ s@: V # @: @: 1 @:vcard@:(s)} -@r{ s@: V : @: @: 1 @:vspan@:(s)} -@r{ s@: V + @: @: 1 @:rdup@:(s)} - -@c -@r{ m@: V & @: @: 1 @:inv@:(m) 1/m} - -@c -@r{ v@: v a @:n @: @:arrange@:(v,n)} -@r{ a@: v b @:n @: @:cvec@:(a,n)} -@r{ v@: v c @:n >0 @: 21,31 @:mcol@:(v,n)} -@r{ v@: v c @:n <0 @: 31 @:mrcol@:(v,-n)} -@r{ m@: v c @:0 @: 31 @:getdiag@:(m)} -@r{ v@: v d @: @: 25 @:diag@:(v,n)} -@r{ v m@: v e @: @: 2 @:vexp@:(v,m)} -@r{ v m f@: H v e @: @: 2 @:vexp@:(v,m,f)} -@r{ v a@: v f @: @: 26 @:find@:(v,a,n)} -@r{ v@: v h @: @: 1 @:head@:(v)} -@r{ v@: I v h @: @: 1 @:tail@:(v)} -@r{ v@: H v h @: @: 1 @:rhead@:(v)} -@r{ v@: I H v h @: @: 1 @:rtail@:(v)} -@r{ @: v i @:n @: 31 @:idn@:(1,n)} -@r{ @: v i @:0 @: 31 @:idn@:(1)} -@r{ h t@: v k @: @: 2 @:cons@:(h,t)} -@r{ h t@: H v k @: @: 2 @:rcons@:(h,t)} -@r{ v@: v l @: @: 1 @:vlen@:(v)} -@r{ v@: H v l @: @: 1 @:mdims@:(v)} -@r{ v m@: v m @: @: 2 @:vmask@:(v,m)} -@r{ v@: v n @: @: 1 @:rnorm@:(v)} -@r{ a b c@: v p @: @: 24 @:calc-pack@:} -@r{ v@: v r @:n >0 @: 21,31 @:mrow@:(v,n)} -@r{ v@: v r @:n <0 @: 31 @:mrrow@:(v,-n)} -@r{ m@: v r @:0 @: 31 @:getdiag@:(m)} -@r{ v i j@: v s @: @: @:subvec@:(v,i,j)} -@r{ v i j@: I v s @: @: @:rsubvec@:(v,i,j)} -@r{ m@: v t @: @: 1 @:trn@:(m)} -@r{ v@: v u @: @: 24 @:calc-unpack@:} -@r{ v@: v v @: @: 1 @:rev@:(v)} -@r{ @: v x @:n @: 31 @:index@:(n)} -@r{ n s i@: C-u v x @: @: @:index@:(n,s,i)} - -@c -@r{ v@: V A @:op @: 22 @:apply@:(op,v)} -@r{ v1 v2@: V C @: @: 2 @:cross@:(v1,v2)} -@r{ m@: V D @: @: 1 @:det@:(m)} -@r{ s@: V E @: @: 1 @:venum@:(s)} -@r{ s@: V F @: @: 1 @:vfloor@:(s)} -@r{ v@: V G @: @: @:grade@:(v)} -@r{ v@: I V G @: @: @:rgrade@:(v)} -@r{ v@: V H @:n @: 31 @:histogram@:(v,n)} -@r{ v w@: H V H @:n @: 31 @:histogram@:(v,w,n)} -@r{ v1 v2@: V I @:mop aop @: 22 @:inner@:(mop,aop,v1,v2)} -@r{ m@: V J @: @: 1 @:ctrn@:(m)} -@r{ m1 m2@: V K @: @: @:kron@:(m1,m2)} -@r{ m@: V L @: @: 1 @:lud@:(m)} -@r{ v@: V M @:op @: 22,23 @:map@:(op,v)} -@r{ v@: V N @: @: 1 @:cnorm@:(v)} -@r{ v1 v2@: V O @:op @: 22 @:outer@:(op,v1,v2)} -@r{ v@: V R @:op @: 22,23 @:reduce@:(op,v)} -@r{ v@: I V R @:op @: 22,23 @:rreduce@:(op,v)} -@r{ a n@: H V R @:op @: 22 @:nest@:(op,a,n)} -@r{ a@: I H V R @:op @: 22 @:fixp@:(op,a)} -@r{ v@: V S @: @: @:sort@:(v)} -@r{ v@: I V S @: @: @:rsort@:(v)} -@r{ m@: V T @: @: 1 @:tr@:(m)} -@r{ v@: V U @:op @: 22 @:accum@:(op,v)} -@r{ v@: I V U @:op @: 22 @:raccum@:(op,v)} -@r{ a n@: H V U @:op @: 22 @:anest@:(op,a,n)} -@r{ a@: I H V U @:op @: 22 @:afixp@:(op,a)} -@r{ s t@: V V @: @: 2 @:vunion@:(s,t)} -@r{ s t@: V X @: @: 2 @:vxor@:(s,t)} - -@c -@r{ @: Y @: @: @:@:user commands} - -@c -@r{ @: z @: @: @:@:user commands} - -@c -@r{ c@: Z [ @: @: 45 @:calc-kbd-if@:} -@r{ c@: Z | @: @: 45 @:calc-kbd-else-if@:} -@r{ @: Z : @: @: @:calc-kbd-else@:} -@r{ @: Z ] @: @: @:calc-kbd-end-if@:} - -@c -@r{ @: Z @{ @: @: 4 @:calc-kbd-loop@:} -@r{ c@: Z / @: @: 45 @:calc-kbd-break@:} -@r{ @: Z @} @: @: @:calc-kbd-end-loop@:} -@r{ n@: Z < @: @: @:calc-kbd-repeat@:} -@r{ @: Z > @: @: @:calc-kbd-end-repeat@:} -@r{ n m@: Z ( @: @: @:calc-kbd-for@:} -@r{ s@: Z ) @: @: @:calc-kbd-end-for@:} - -@c -@r{ @: Z C-g @: @: @:@:cancel if/loop command} - -@c -@r{ @: Z ` @: @: @:calc-kbd-push@:} -@r{ @: Z ' @: @: @:calc-kbd-pop@:} -@r{ @: Z # @: @: @:calc-kbd-query@:} - -@c -@r{ comp@: Z C @:func, args @: 50 @:calc-user-define-composition@:} -@r{ @: Z D @:key, command @: @:calc-user-define@:} -@r{ @: Z E @:key, editing @: 30 @:calc-user-define-edit@:} -@r{ defn@: Z F @:k, c, f, a, n@: 28 @:calc-user-define-formula@:} -@r{ @: Z G @:key @: @:calc-get-user-defn@:} -@r{ @: Z I @: @: @:calc-user-define-invocation@:} -@r{ @: Z K @:key, command @: @:calc-user-define-kbd-macro@:} -@r{ @: Z P @:key @: @:calc-user-define-permanent@:} -@r{ @: Z S @: @: 30 @:calc-edit-user-syntax@:} -@r{ @: Z T @: @: 12 @:calc-timing@:} -@r{ @: Z U @:key @: @:calc-user-undefine@:} - -@end format - -@noindent -NOTES - -@enumerate -@c 1 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the @expr{-n}th stack entry. -A prefix of zero applies to the entire stack. (For @key{LFD} and -@kbd{M-@key{DEL}}, the meaning of the sign is reversed.) - -@c 2 -@item -Positive prefix arguments apply to @expr{n} stack entries. -Negative prefix arguments apply to the top stack entry -and the next @expr{-n} stack entries. - -@c 3 -@item -Positive prefix arguments rotate top @expr{n} stack entries by one. -Negative prefix arguments rotate the entire stack by @expr{-n}. -A prefix of zero reverses the entire stack. - -@c 4 -@item -Prefix argument specifies a repeat count or distance. - -@c 5 -@item -Positive prefix arguments specify a precision @expr{p}. -Negative prefix arguments reduce the current precision by @expr{-p}. - -@c 6 -@item -A prefix argument is interpreted as an additional step-size parameter. -A plain @kbd{C-u} prefix means to prompt for the step size. - -@c 7 -@item -A prefix argument specifies simplification level and depth. -1=Default, 2=like @kbd{a s}, 3=like @kbd{a e}. - -@c 8 -@item -A negative prefix operates only on the top level of the input formula. - -@c 9 -@item -Positive prefix arguments specify a word size of @expr{w} bits, unsigned. -Negative prefix arguments specify a word size of @expr{w} bits, signed. - -@c 10 -@item -Prefix arguments specify the shift amount @expr{n}. The @expr{w} argument -cannot be specified in the keyboard version of this command. - -@c 11 -@item -From the keyboard, @expr{d} is omitted and defaults to zero. - -@c 12 -@item -Mode is toggled; a positive prefix always sets the mode, and a negative -prefix always clears the mode. - -@c 13 -@item -Some prefix argument values provide special variations of the mode. - -@c 14 -@item -A prefix argument, if any, is used for @expr{m} instead of taking -@expr{m} from the stack. @expr{M} may take any of these values: -@iftex -{@advance@tableindent10pt -@end iftex -@table @asis -@item Integer -Random integer in the interval @expr{[0 .. m)}. -@item Float -Random floating-point number in the interval @expr{[0 .. m)}. -@item 0.0 -Gaussian with mean 1 and standard deviation 0. -@item Error form -Gaussian with specified mean and standard deviation. -@item Interval -Random integer or floating-point number in that interval. -@item Vector -Random element from the vector. -@end table -@iftex -} -@end iftex - -@c 15 -@item -A prefix argument from 1 to 6 specifies number of date components -to remove from the stack. @xref{Date Conversions}. - -@c 16 -@item -A prefix argument specifies a time zone; @kbd{C-u} says to take the -time zone number or name from the top of the stack. @xref{Time Zones}. - -@c 17 -@item -A prefix argument specifies a day number (0-6, 0-31, or 0-366). - -@c 18 -@item -If the input has no units, you will be prompted for both the old and -the new units. - -@c 19 -@item -With a prefix argument, collect that many stack entries to form the -input data set. Each entry may be a single value or a vector of values. - -@c 20 -@item -With a prefix argument of 1, take a single -@texline @var{n}@math{\times2} -@infoline @mathit{@var{N}x2} -matrix from the stack instead of two separate data vectors. - -@c 21 -@item -The row or column number @expr{n} may be given as a numeric prefix -argument instead. A plain @kbd{C-u} prefix says to take @expr{n} -from the top of the stack. If @expr{n} is a vector or interval, -a subvector/submatrix of the input is created. - -@c 22 -@item -The @expr{op} prompt can be answered with the key sequence for the -desired function, or with @kbd{x} or @kbd{z} followed by a function name, -or with @kbd{$} to take a formula from the top of the stack, or with -@kbd{'} and a typed formula. In the last two cases, the formula may -be a nameless function like @samp{<#1+#2>} or @samp{}, or it -may include @kbd{$}, @kbd{$$}, etc. (where @kbd{$} will correspond to the -last argument of the created function), or otherwise you will be -prompted for an argument list. The number of vectors popped from the -stack by @kbd{V M} depends on the number of arguments of the function. - -@c 23 -@item -One of the mapping direction keys @kbd{_} (horizontal, i.e., map -by rows or reduce across), @kbd{:} (vertical, i.e., map by columns or -reduce down), or @kbd{=} (map or reduce by rows) may be used before -entering @expr{op}; these modify the function name by adding the letter -@code{r} for ``rows,'' @code{c} for ``columns,'' @code{a} for ``across,'' -or @code{d} for ``down.'' - -@c 24 -@item -The prefix argument specifies a packing mode. A nonnegative mode -is the number of items (for @kbd{v p}) or the number of levels -(for @kbd{v u}). A negative mode is as described below. With no -prefix argument, the mode is taken from the top of the stack and -may be an integer or a vector of integers. -@iftex -{@advance@tableindent-20pt -@end iftex -@table @cite -@item -1 -(@var{2}) Rectangular complex number. -@item -2 -(@var{2}) Polar complex number. -@item -3 -(@var{3}) HMS form. -@item -4 -(@var{2}) Error form. -@item -5 -(@var{2}) Modulo form. -@item -6 -(@var{2}) Closed interval. -@item -7 -(@var{2}) Closed .. open interval. -@item -8 -(@var{2}) Open .. closed interval. -@item -9 -(@var{2}) Open interval. -@item -10 -(@var{2}) Fraction. -@item -11 -(@var{2}) Float with integer mantissa. -@item -12 -(@var{2}) Float with mantissa in @expr{[1 .. 10)}. -@item -13 -(@var{1}) Date form (using date numbers). -@item -14 -(@var{3}) Date form (using year, month, day). -@item -15 -(@var{6}) Date form (using year, month, day, hour, minute, second). -@end table -@iftex -} -@end iftex - -@c 25 -@item -A prefix argument specifies the size @expr{n} of the matrix. With no -prefix argument, @expr{n} is omitted and the size is inferred from -the input vector. - -@c 26 -@item -The prefix argument specifies the starting position @expr{n} (default 1). - -@c 27 -@item -Cursor position within stack buffer affects this command. - -@c 28 -@item -Arguments are not actually removed from the stack by this command. - -@c 29 -@item -Variable name may be a single digit or a full name. - -@c 30 -@item -Editing occurs in a separate buffer. Press @kbd{C-c C-c} (or -@key{LFD}, or in some cases @key{RET}) to finish the edit, or kill the -buffer with @kbd{C-x k} to cancel the edit. The @key{LFD} key prevents evaluation -of the result of the edit. - -@c 31 -@item -The number prompted for can also be provided as a prefix argument. - -@c 32 -@item -Press this key a second time to cancel the prefix. - -@c 33 -@item -With a negative prefix, deactivate all formulas. With a positive -prefix, deactivate and then reactivate from scratch. - -@c 34 -@item -Default is to scan for nearest formula delimiter symbols. With a -prefix of zero, formula is delimited by mark and point. With a -non-zero prefix, formula is delimited by scanning forward or -backward by that many lines. - -@c 35 -@item -Parse the region between point and mark as a vector. A nonzero prefix -parses @var{n} lines before or after point as a vector. A zero prefix -parses the current line as a vector. A @kbd{C-u} prefix parses the -region between point and mark as a single formula. - -@c 36 -@item -Parse the rectangle defined by point and mark as a matrix. A positive -prefix @var{n} divides the rectangle into columns of width @var{n}. -A zero or @kbd{C-u} prefix parses each line as one formula. A negative -prefix suppresses special treatment of bracketed portions of a line. - -@c 37 -@item -A numeric prefix causes the current language mode to be ignored. - -@c 38 -@item -Responding to a prompt with a blank line answers that and all -later prompts by popping additional stack entries. - -@c 39 -@item -Answer for @expr{v} may also be of the form @expr{v = v_0} or -@expr{v - v_0}. - -@c 40 -@item -With a positive prefix argument, stack contains many @expr{y}'s and one -common @expr{x}. With a zero prefix, stack contains a vector of -@expr{y}s and a common @expr{x}. With a negative prefix, stack -contains many @expr{[x,y]} vectors. (For 3D plots, substitute -@expr{z} for @expr{y} and @expr{x,y} for @expr{x}.) - -@c 41 -@item -With any prefix argument, all curves in the graph are deleted. - -@c 42 -@item -With a positive prefix, refines an existing plot with more data points. -With a negative prefix, forces recomputation of the plot data. - -@c 43 -@item -With any prefix argument, set the default value instead of the -value for this graph. - -@c 44 -@item -With a negative prefix argument, set the value for the printer. - -@c 45 -@item -Condition is considered ``true'' if it is a nonzero real or complex -number, or a formula whose value is known to be nonzero; it is ``false'' -otherwise. - -@c 46 -@item -Several formulas separated by commas are pushed as multiple stack -entries. Trailing @kbd{)}, @kbd{]}, @kbd{@}}, @kbd{>}, and @kbd{"} -delimiters may be omitted. The notation @kbd{$$$} refers to the value -in stack level three, and causes the formula to replace the top three -stack levels. The notation @kbd{$3} refers to stack level three without -causing that value to be removed from the stack. Use @key{LFD} in place -of @key{RET} to prevent evaluation; use @kbd{M-=} in place of @key{RET} -to evaluate variables. - -@c 47 -@item -The variable is replaced by the formula shown on the right. The -Inverse flag reverses the order of the operands, e.g., @kbd{I s - x} -assigns -@texline @math{x \coloneq a-x}. -@infoline @expr{x := a-x}. - -@c 48 -@item -Press @kbd{?} repeatedly to see how to choose a model. Answer the -variables prompt with @expr{iv} or @expr{iv;pv} to specify -independent and parameter variables. A positive prefix argument -takes @mathit{@var{n}+1} vectors from the stack; a zero prefix takes a matrix -and a vector from the stack. - -@c 49 -@item -With a plain @kbd{C-u} prefix, replace the current region of the -destination buffer with the yanked text instead of inserting. - -@c 50 -@item -All stack entries are reformatted; the @kbd{H} prefix inhibits this. -The @kbd{I} prefix sets the mode temporarily, redraws the top stack -entry, then restores the original setting of the mode. - -@c 51 -@item -A negative prefix sets the default 3D resolution instead of the -default 2D resolution. - -@c 52 -@item -This grabs a vector of the form [@var{prec}, @var{wsize}, @var{ssize}, -@var{radix}, @var{flfmt}, @var{ang}, @var{frac}, @var{symb}, @var{polar}, -@var{matrix}, @var{simp}, @var{inf}]. A prefix argument from 1 to 12 -grabs the @var{n}th mode value only. -@end enumerate - -@iftex -(Space is provided below for you to keep your own written notes.) -@page -@endgroup -@end iftex - - -@c [end-summary] - -@node Key Index, Command Index, Summary, Top -@unnumbered Index of Key Sequences - -@printindex ky - -@node Command Index, Function Index, Key Index, Top -@unnumbered Index of Calculator Commands - -Since all Calculator commands begin with the prefix @samp{calc-}, the -@kbd{x} key has been provided as a variant of @kbd{M-x} which automatically -types @samp{calc-} for you. Thus, @kbd{x last-args} is short for -@kbd{M-x calc-last-args}. - -@printindex pg - -@node Function Index, Concept Index, Command Index, Top -@unnumbered Index of Algebraic Functions - -This is a list of built-in functions and operators usable in algebraic -expressions. Their full Lisp names are derived by adding the prefix -@samp{calcFunc-}, as in @code{calcFunc-sqrt}. -@iftex -All functions except those noted with ``*'' have corresponding -Calc keystrokes and can also be found in the Calc Summary. -@end iftex - -@printindex tp - -@node Concept Index, Variable Index, Function Index, Top -@unnumbered Concept Index - -@printindex cp - -@node Variable Index, Lisp Function Index, Concept Index, Top -@unnumbered Index of Variables - -The variables in this list that do not contain dashes are accessible -as Calc variables. Add a @samp{var-} prefix to get the name of the -corresponding Lisp variable. - -The remaining variables are Lisp variables suitable for @code{setq}ing -in your Calc init file or @file{.emacs} file. - -@printindex vr - -@node Lisp Function Index, , Variable Index, Top -@unnumbered Index of Lisp Math Functions - -The following functions are meant to be used with @code{defmath}, not -@code{defun} definitions. For names that do not start with @samp{calc-}, -the corresponding full Lisp name is derived by adding a prefix of -@samp{math-}. - -@printindex fn - -@bye - - -@ignore - arch-tag: 77a71809-fa4d-40be-b2cc-da3e8fb137c0 -@end ignore diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi deleted file mode 100644 index 0d8385ed968..00000000000 --- a/doc/misc/cc-mode.texi +++ /dev/null @@ -1,6998 +0,0 @@ -\input texinfo -@c Notes to self regarding line handling: -@c -@c Empty lines are often significant before @end directives; avoid them. -@c -@c Empty lines before and after @example directives are significant in -@c info output but not in TeX. Empty lines inside @example directives -@c are significant. - -@c Conventions for formatting examples: -@c o If the example contains empty lines then put the surrounding empty -@c lines inside the @example directives. Put them outside otherwise. -@c o Use @group inside the example only if it shows indentation where -@c the relation between lines inside is relevant. -@c o Format line number columns like this: -@c 1: foo -@c 2: bar -@c ^ one space -@c ^^ two columns, right alignment -@c o Check line lengths in TeX output; they can typically be no longer -@c than 70 chars, 60 if the paragraph is indented. - -@comment TBD: Document the finer details of statement anchoring? - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment %**start of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment How to make the various output formats: -@comment (Thanks to Robert Chassell for supplying this information.) -@comment Note that Texinfo 4.7 (or later) is needed. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@ignore -In each of the following pairs of commands, the first generates a -version with cross references pointing to the GNU Emacs manuals, -the second with them pointing to the XEmacs manuals. - ## Info output - makeinfo cc-mode.texi - makeinfo -DXEMACS cc-mode.texi - - ## DVI output - ## You may need to set up the environment variable TEXINPUTS so - ## that tex can find the file texinfo.tex - See the tex - ## manpage. - texi2dvi cc-mode.texi - texi2dvi -t "@set XEMACS " cc-mode.texi - - ## HTML output. (The --no-split parameter is optional) - makeinfo --html --no-split cc-mode.texi - makeinfo --html --no-split -DXEMACS cc-mode.texi - - ## Plain text output - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt cc-mode.texi - makeinfo --fill-column=70 --no-split --paragraph-indent=0 \ - --no-headers --output=cc-mode.txt -DXEMACS cc-mode.texi - - ## DocBook output - makeinfo --docbook --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --docbook --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - ## XML output - makeinfo --xml --no-split --paragraph-indent=0 \ - cc-mode.texi - makeinfo --xml --no-split --paragraph-indent=0 \ - -DXEMACS cc-mode.texi - - #### (You must be in the same directory as the viewed file.) - - ## View DVI output - xdvi cc-mode.dvi & - - ## View HTML output - mozilla cc-mode.html -@end ignore - -@comment No overfull hbox marks in the dvi file. -@finalout - -@setfilename ../../info/ccmode -@settitle CC Mode Manual -@footnotestyle end - -@c The following four macros generate the filenames and titles of the -@c main (X)Emacs manual and the Elisp/Lispref manual. Leave the -@c Texinfo variable `XEMACS' unset to generate a GNU Emacs version, set it -@c to generate an XEmacs version, e.g. with -@c "makeinfo -DXEMACS cc-mode.texi". -@ifset XEMACS -@macro emacsman -xemacs -@end macro -@macro emacsmantitle -XEmacs User's Manual -@end macro -@macro lispref -lispref -@end macro -@macro lispreftitle -XEmacs Lisp Reference Manual -@end macro -@end ifset - -@ifclear XEMACS -@macro emacsman -emacs -@end macro -@macro emacsmantitle -GNU Emacs Manual -@end macro -@macro lispref -elisp -@end macro -@macro lispreftitle -GNU Emacs Lisp Reference Manual -@end macro -@end ifclear - - -@macro ccmode -CC Mode -@end macro - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment @setchapternewpage odd !! we don't want blank pages !! -@comment %**end of header (This is for running Texinfo on a region) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment -@comment Texinfo manual for CC Mode -@comment Generated from the original README file by Krishna Padmasola -@comment -@comment -@comment Authors: -@comment Barry A. Warsaw -@comment Martin Stjernholm -@comment Alan Mackenzie -@comment -@comment Maintained by Martin Stjernholm and Alan Mackenzie -@comment -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment Define an index for syntactic symbols. -@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss - @c For Info, unlike tex, @syncodeindex needs a matching @defindex. -@defindex ss -@end ifnottex - -@comment Combine key, syntactic symbol and concept indices into one. -@syncodeindex ss cp -@syncodeindex ky cp - -@copying -This manual is for CC Mode in Emacs. - -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@comment Info directory entry for use by install-info. The indentation -@comment here is by request from the FSF folks. -@dircategory Emacs -@direntry -* CC Mode: (ccmode). Emacs mode for editing C, C++, Objective-C, - Java, Pike, AWK, and CORBA IDL code. -@end direntry - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment TeX title page -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@titlepage -@sp 10 - -@center @titlefont{CC Mode 5.31} -@sp 2 -@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} -@sp 2 -@center Barry A. Warsaw, Martin Stjernholm, Alan Mackenzie - -@page -@vskip 0pt plus 1filll -@insertcopying - -This manual was generated from cc-mode.texi, which can be downloaded -from -@url{http://cvs.savannah.gnu.org/viewcvs/emacs/emacs/doc/misc/cc-mode.texi}. -@end titlepage - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment The Top node contains the master menu for the Info file. -@comment This appears only in the Info file, not the printed manual. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@summarycontents -@contents - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifnottex -@top @ccmode{} - -@ccmode{} is a GNU Emacs mode for editing files containing C, C++, -Objective-C, Java, CORBA IDL (and the variants PSDL and CIDL), Pike -and AWK code. It provides syntax-based indentation, font locking, and -has several handy commands and some minor modes to make the editing -easier. It does not provide tools to look up and navigate between -functions, classes etc - there are other packages for that. - -@insertcopying -@end ifnottex - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@menu -* Introduction:: -* Overview:: -* Getting Started:: -* Commands:: -* Font Locking:: -* Config Basics:: -* Custom Filling and Breaking:: -* Custom Auto-newlines:: -* Clean-ups:: -* Indentation Engine Basics:: -* Customizing Indentation:: -* Custom Macros:: -* Odds and Ends:: -* Sample .emacs File:: -* Performance Issues:: -* Limitations and Known Bugs:: -* FAQ:: -* Updating CC Mode:: -* Mailing Lists and Bug Reports:: -* GNU Free Documentation License:: -* Command and Function Index:: -* Variable Index:: -* Concept and Key Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Commands - -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: - -Font Locking - -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: - -Configuration Basics - -* CC Hooks:: -* Style Variables:: -* Styles:: - -Styles - -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* File Styles:: - -Customizing Auto-newlines - -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: - -Hanging Braces - -* Custom Braces:: - -Indentation Engine Basics - -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: - -Syntactic Symbols - -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Anonymous Class Symbol:: -* Statement Block Symbols:: -* K&R Symbols:: - -Customizing Indentation - -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: - -Line-Up Functions - -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: - -@end detailmenu -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Introduction, Overview, Top, Top -@comment node-name, next, previous, up -@chapter Introduction -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex BOCM -@cindex history -@cindex awk-mode.el -@cindex c-mode.el -@cindex c++-mode.el - -Welcome to @ccmode{}, a GNU Emacs mode for editing files containing C, -C++, Objective-C, Java, CORBA IDL (and the variants CORBA PSDL and -CIDL), Pike and AWK code. This incarnation of the mode is descended -from @file{c-mode.el} (also called ``Boring Old C Mode'' or BOCM -@t{:-)}, @file{c++-mode.el} version 2, which Barry Warsaw had been -maintaining since 1992, and @file{awk-mode.el}, a long neglected mode -in the (X)Emacs base. - -Late in 1997, Martin Stjernholm joined Barry on the @ccmode{} -Maintainers Team, and implemented the Pike support. In 2000 Martin -took over as the sole maintainer. In 2001 Alan Mackenzie joined the -team, implementing AWK support in version 5.30. @ccmode{} did not -originally contain the font lock support for its languages --- that -was added in version 5.30. - -This manual describes @ccmode{} -@comment The following line must appear on its own, so that the -version 5.31. -@comment Release.py script can update the version number automatically - -@ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, -Java, CORBA's Interface Definition Language, Pike@footnote{A C-like -scripting language with its roots in the LPC language used in some MUD -engines. See @uref{http://pike.ida.liu.se/}.} and AWK files. In this -way, you can easily set up consistent font locking and coding styles for -use in editing all of these languages, although AWK is not yet as -uniformly integrated as the other languages. - -@findex c-mode -@findex c++-mode -@findex objc-mode -@findex java-mode -@findex idl-mode -@findex pike-mode -@findex awk-mode -Note that the name of this package is ``@ccmode{}'', but there is no top -level @code{cc-mode} entry point. All of the variables, commands, and -functions in @ccmode{} are prefixed with @code{c-@var{thing}}, and -@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, -@code{idl-mode}, @code{pike-mode}, and @code{awk-mode} entry points are -provided. This package is intended to be a replacement for -@file{c-mode.el}, @file{c++-mode.el} and @file{awk-mode.el}. - -A special word of thanks goes to Krishna Padmasola for his work in -converting the original @file{README} file to Texinfo format. I'd -also like to thank all the @ccmode{} victims who help enormously -during the early beta stages of @ccmode{}'s development. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Overview, Getting Started, Introduction, Top -@comment node-name, next, previous, up@cindex organization of the manual -@chapter Overview of the Manual -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@noindent -The manual starts with several introductory chapters (including this -one). - -@noindent -The next chunk of the manual describes the day to day @emph{use} of -@ccmode{} (as contrasted with how to customize it). - -@itemize @bullet -@item -The chapter ``Commands'' describes in detail how to use (nearly) all -of @ccmode{}'s features. There are extensive cross-references from -here to the corresponding sections later in the manual which tell you -how to customize these features. - -@item -``Font Locking'' describes how ``syntax highlighting'' is applied to -your buffers. It is mainly background information and can be skipped -over at a first reading. -@end itemize - -@noindent -The next chunk of the manual describes how to @emph{customize} -@ccmode{}. Typically, an overview of a topic is given at the chapter -level, then the sections and subsections describe the material in -increasing detail. - -@itemize @bullet -@item -The chapter ``Configuration Basics'' tells you @emph{how} to write -customizations - whether in hooks, in styles, in both, or in neither, -depending on your needs. It describes the @ccmode{} style system and -lists the standard styles that @ccmode{} supplies. - -@item -The next few chapters describe in detail how to customize the various -features of @ccmode{}. - -@item -Finally, there is a sample @file{.emacs} fragment, which might help you -in creating your own customization. -@end itemize - -@noindent -The manual ends with ``this and that'', things that don't fit cleanly -into any of the previous chunks. - -@itemize @bullet -@item -Two chapters discuss the performance of @ccmode{} and known -bugs/limitations. - -@item -The FAQ contains a list of common problems and questions. - -@item -The next two chapters tell you how to get in touch with the @ccmode{} -project - whether for updating @ccmode{} or submitting bug reports. -@end itemize - -@noindent -Finally, there are the customary indices. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Getting Started, Commands, Overview, Top -@comment node-name, next, previous, up -@chapter Getting Started -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you got this version of @ccmode{} with Emacs or XEmacs, it should -work just fine right out of the box. Note however that you might not -have the latest @ccmode{} release and might want to upgrade your copy -(see below). - -You should probably start by skimming through the entire Commands chapter -(@pxref{Commands}) to get an overview of @ccmode{}'s capabilities. - -After trying out some commands, you may dislike some aspects of -@ccmode{}'s default configuration. Here is an outline of how to -change some of the settings that newcomers to @ccmode{} most often -want to change: - -@table @asis -@item c-basic-offset -This Lisp variable holds an integer, the number of columns @ccmode{} -indents nested code. To set this value to 6, customize -@code{c-basic-offset} or put this into your @file{.emacs}: - -@example -(setq c-basic-offset 6) -@end example - -@item The (indentation) style -The basic ``shape'' of indentation created by @ccmode{}---by default, -this is @code{gnu} style (except for Java and AWK buffers). A list of -the available styles and their descriptions can be found in -@ref{Built-in Styles}. A complete specification of the @ccmode{} -style system, including how to create your own style, can be found in -the chapter @ref{Styles}. To set your style to @code{linux}, either -customize @code{c-default-style} or put this into your @file{.emacs}: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "linux"))) -@end example - -@item Electric Indentation -Normally, when you type ``punctuation'' characters such as @samp{;} or -@samp{@{}, @ccmode{} instantly reindents the current line. This can -be disconcerting until you get used to it. To disable @dfn{electric -indentation} in the current buffer, type @kbd{C-c C-l}. Type the same -thing to enable it again. To have electric indentation disabled by -default, put the following into your @file{.emacs} file@footnote{There -is no ``easy customization'' facility for making this change.}: - -@example -(setq-default c-electric-flag nil) -@end example - -@noindent -Details of this and other similar ``Minor Modes'' appear in the -section @ref{Minor Modes}. - -@item Making the @key{RET} key indent the new line -The standard Emacs binding for @key{RET} just adds a new line. If you -want it to reindent the new line as well, rebind the key. Note that -the action of rebinding would fail if the pertinent keymap didn't yet -exist---we thus need to delay the action until after @ccmode{} has -been loaded. Put the following code into your @file{.emacs}: - -@example -(defun my-make-CR-do-indent () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-make-CR-do-indent) -@end example - -@noindent -This example demonstrates the use of a very powerful @ccmode{} (and -Emacs) facility, the hook. The use of @ccmode{}'s hooks is described -in @ref{CC Hooks}. -@end table - -All these settings should occur in your @file{.emacs} @emph{before} -any @ccmode{} buffers get loaded---in particular, before any call of -@code{desktop-read}. - -As you get to know the mode better, you may want to make more -ambitious changes to your configuration. For this, you should start -reading the chapter @ref{Config Basics}. - -If you are upgrading an existing @ccmode{} installation, please see -the @file{README} file for installation details. In particular, if -you are going to be editing AWK files, @file{README} describes how to -configure your (X)Emacs so that @ccmode{} will supersede the obsolete -@code{awk-mode.el} which might have been supplied with your (X)Emacs. -@ccmode{} might not work with older versions of Emacs or XEmacs. See -the @ccmode{} release notes at @uref{http://cc-mode.sourceforge.net} -for the latest information on Emacs version and package compatibility -(@pxref{Updating CC Mode}). - -@deffn Command c-version -@findex version (c-) -You can find out what version of @ccmode{} you are using by visiting a C -file and entering @kbd{M-x c-version RET}. You should see this message in -the echo area: - -@example -Using CC Mode version 5.XX -@end example - -@noindent -where @samp{XX} is the minor release number. -@end deffn - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Commands, Font Locking, Getting Started, Top -@comment node-name, next, previous, up -@chapter Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter specifies all of CC Mode's commands, and thus contains -nearly everything you need to know to @emph{use} @ccmode{} (as -contrasted with configuring it). @dfn{Commands} here means both -control key sequences and @dfn{electric keys}, these being characters -such as @samp{;} which, as well as inserting themselves into the -buffer, also do other things. - -You might well want to review -@ifset XEMACS -@ref{Lists,,,@emacsman{}, @emacsmantitle{}}, -@end ifset -@ifclear XEMACS -@ref{Moving by Parens,,,@emacsman{}, @emacsmantitle{}}, -@end ifclear -which describes commands for moving around brace and parenthesis -structures. - - -@menu -* Indentation Commands:: -* Comment Commands:: -* Movement Commands:: -* Filling and Breaking:: -* Minor Modes:: -* Electric Keys:: -* Auto-newlines:: -* Hungry WS Deletion:: -* Subword Movement:: -* Other Commands:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Commands, Comment Commands, Commands, Commands -@comment node-name, next, previous,up -@section Indentation Commands -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The following commands reindent C constructs. Note that when you -change your coding style, either interactively or through some other -means, your file does @emph{not} automatically get reindented. You -will need to execute one of the following commands to see the effects -of your changes. - -@cindex GNU indent program -Also, variables like @code{c-hanging-*} and @code{c-cleanup-list} -(@pxref{Custom Auto-newlines}) only affect how on-the-fly code is -formatted. Changing the ``hanginess'' of a brace and then -reindenting, will not move the brace to a different line. For this, -you're better off getting an external program like GNU @code{indent}, -which will rearrange brace location, amongst other things. - -Preprocessor directives are handled as syntactic whitespace from other -code, i.e. they can be interspersed anywhere without affecting the -indentation of the surrounding code, just like comments. - -The code inside macro definitions is, by default, still analyzed -syntactically so that you get relative indentation there just as you'd -get if the same code was outside a macro. However, since there is no -hint about the syntactic context, i.e. whether the macro expands to an -expression, to some statements, or perhaps to whole functions, the -syntactic recognition can be wrong. @ccmode{} manages to figure it -out correctly most of the time, though. - -Reindenting large sections of code can take a long time. When -@ccmode{} reindents a region of code, it is essentially equivalent to -hitting @key{TAB} on every line of the region. - -These commands indent code: - -@table @asis -@item @kbd{@key{TAB}} (@code{c-indent-command}) -@kindex TAB -@findex c-indent-command -@findex indent-command (c-) -This command indents the current line. That is all you need to know -about it for normal use. - -@code{c-indent-command} does different things, depending on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): - -@itemize @bullet -@item -When it's non-@code{nil} (which it normally is), the command indents -the line according to its syntactic context. With a prefix argument -(@kbd{C-u @key{TAB}}), it will re-indent the entire -expression@footnote{this is only useful for a line starting with a -comment opener or an opening brace, parenthesis, or string quote.} -that begins at the line's left margin. - -@item -When it's @code{nil}, the command indents the line by an extra -@code{c-basic-offset} columns. A prefix argument acts as a -multiplier. A bare prefix (@kbd{C-u @key{TAB}}) is equivalent to -1, -removing @code{c-basic-offset} columns from the indentation. -@end itemize - -The precise behavior is modified by several variables: With -@code{c-tab-always-indent}, you can make @key{TAB} insert whitespace -in some circumstances---@code{c-insert-tab-function} then defines -precisely what sort of ``whitespace'' this will be. Set the standard -Emacs variable @code{indent-tabs-mode} to @code{t} if you want real -@samp{tab} characters to be used in the indentation, to @code{nil} if -you want only spaces. @xref{Just Spaces,,, @emacsman{}, -@emacsmantitle{}}. - -@defopt c-tab-always-indent -@vindex tab-always-indent (c-) -@cindex literal -This variable modifies how @key{TAB} operates. -@itemize @bullet -@item -When it is @code{t} (the default), @key{TAB} simply indents the -current line. -@item -When it is @code{nil}, @key{TAB} (re)indents the line only if point is -to the left of the first non-whitespace character on the line. -Otherwise it inserts some whitespace (a tab or an equivalent number of -spaces - see below) at point. -@item -With some other value, the line is reindented. Additionally, if point -is within a string or comment, some whitespace is inserted. -@end itemize -@end defopt - -@defopt c-insert-tab-function -@vindex insert-tab-function (c-) -@findex tab-to-tab-stop -When ``some whitespace'' is inserted as described above, what actually -happens is that the function stored in @code{c-insert-tab-function} is -called. Normally, this is @code{insert-tab}, which inserts a real tab -character or the equivalent number of spaces (depending on -@code{indent-tabs-mode}). Some people, however, set -@code{c-insert-tab-function} to @code{tab-to-tab-stop} so as to get -hard tab stops when indenting. -@end defopt -@end table - -@noindent -The kind of indentation the next five commands do depends on the -setting of @code{c-syntactic-indentation} (@pxref{Indentation Engine -Basics}): -@itemize @bullet -@item -when it is non-@code{nil} (the default), the commands indent lines -according to their syntactic context; -@item -when it is @code{nil}, they just indent each line the same amount as -the previous non-blank line. The commands that indent a region aren't -very useful in this case. -@end itemize - -@table @asis -@item @kbd{C-j} (@code{newline-and-indent}) -@kindex C-j -@findex newline-and-indent -Inserts a newline and indents the new blank line, ready to start -typing. This is a standard (X)Emacs command. - -@item @kbd{C-M-q} (@code{c-indent-exp}) -@kindex C-M-q -@findex c-indent-exp -@findex indent-exp (c-) -Indents an entire balanced brace or parenthesis expression. Note that -point must be on the opening brace or parenthesis of the expression -you want to indent. - -@item @kbd{C-c C-q} (@code{c-indent-defun}) -@kindex C-c C-q -@findex c-indent-defun -@findex indent-defun (c-) -Indents the entire top-level function, class or macro definition -encompassing point. It leaves point unchanged. This function can't be -used to reindent a nested brace construct, such as a nested class or -function, or a Java method. The top-level construct being reindented -must be complete, i.e. it must have both a beginning brace and an ending -brace. - -@item @kbd{C-M-\} (@code{indent-region}) -@kindex C-M-\ -@findex indent-region -Indents an arbitrary region of code. This is a standard Emacs command, -tailored for C code in a @ccmode{} buffer. Note, of course, that point -and mark must delineate the region you want to indent. - -@item @kbd{C-M-h} (@code{c-mark-function}) -@kindex C-M-h -@findex c-mark-function -@findex mark-function (c-) -While not strictly an indentation command, this is useful for marking -the current top-level function or class definition as the current -region. As with @code{c-indent-defun}, this command operates on -top-level constructs, and can't be used to mark say, a Java method. -@end table - -These variables are also useful when indenting code: - -@defopt indent-tabs-mode -This is a standard Emacs variable that controls how line indentation -is composed. When it's non-@code{nil}, tabs can be used in a line's -indentation, otherwise only spaces are used. -@end defopt - -@defopt c-progress-interval -@vindex progress-interval (c-) -When indenting large regions of code, this variable controls how often a -progress message is displayed. Set this variable to @code{nil} to -inhibit the progress messages, or set it to an integer which is how -often (in seconds) progress messages are to be displayed. -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Commands, Movement Commands, Indentation Commands, Commands -@comment node-name, next, previous, up -@section Comment Commands -@cindex comments (insertion of) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@table @asis -@item @kbd{C-c C-c} (@code{comment-region}) -@kindex C-c C-c -@findex comment-region -This command comments out the lines that start in the region. With a -negative argument, it does the opposite - it deletes the comment -delimiters from these lines. @xref{Multi-Line Comments,,, emacs, GNU -Emacs Manual}, for fuller details. @code{comment-region} isn't -actually part of @ccmode{} - it is given a @ccmode{} binding for -convenience. - -@item @kbd{M-;} (@code{comment-dwim} or @code{indent-for-comment} @footnote{The name of this command varies between (X)Emacs versions.}) -@kindex M-; -@findex comment-dwim -@findex indent-for-comment -Insert a comment at the end of the current line, if none is there -already. Then reindent the comment according to @code{comment-column} -@ifclear XEMACS -(@pxref{Options for Comments,,, emacs, GNU Emacs Manual}) -@end ifclear -@ifset XEMACS -(@pxref{Comments,,, xemacs, XEmacs User's Manual}) -@end ifset -and the variables below. Finally, position the point after the -comment starter. @kbd{C-u M-;} kills any comment on the current line, -together with any whitespace before it. This is a standard Emacs -command, but @ccmode{} enhances it a bit with two variables: - -@defopt c-indent-comment-alist -@vindex indent-comment-alist (c-) -@vindex comment-column -This style variable allows you to vary the column that @kbd{M-;} puts -the comment at, depending on what sort of code is on the line, and -possibly the indentation of any similar comment on the preceding line. -It is an association list that maps different types of lines to -actions describing how they should be handled. If a certain line type -isn't present on the list then the line is indented to the column -specified by @code{comment-column}. - -See the documentation string for a full description of this -variable (use @kbd{C-h v c-indent-comment-alist}). -@end defopt - -@defopt c-indent-comments-syntactically-p -@vindex indent-comments-syntactically-p (c-) -Normally, when this style variable is @code{nil}, @kbd{M-;} will -indent comment-only lines according to @code{c-indent-comment-alist}, -just as it does with lines where other code precede the comments. -However, if you want it to act just like @key{TAB} for comment-only -lines you can get that by setting -@code{c-indent-comments-syntactically-p} to non-@code{nil}. - -If @code{c-indent-comments-syntactically-p} is non-@code{nil} then -@code{c-indent-comment-alist} won't be consulted at all for comment-only -lines. -@end defopt -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Movement Commands, Filling and Breaking, Comment Commands, Commands -@comment node-name, next, previous, up -@section Movement Commands -@cindex movement -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains some useful commands for moving around in C code. - -@table @asis -@item @kbd{C-M-a} (@code{c-beginning-of-defun}) -@itemx @kbd{C-M-e} (@code{c-end-of-defun}) -@findex c-beginning-of-defun -@findex c-end-of-defun - -Move to the beginning or end of the current or next function. Other -constructs (such as a structs or classes) which have a brace block -also count as ``functions'' here. To move over several functions, you -can give these commands a repeat count. - -The start of a function is at its header. The end of the function is -after its closing brace, or after the semicolon of a construct (such -as a @code{struct}) which doesn't end at the brace. These two -commands try to leave point at the beginning of a line near the actual -start or end of the function. This occasionally causes point not to -move at all. - -These functions are analogous to the Emacs built-in commands -@code{beginning-of-defun} and @code{end-of-defun}, except they -eliminate the constraint that the top-level opening brace of the defun -must be in column zero. See @ref{Defuns,,,@emacsman{}, -@emacsmantitle{}}, for more information. - -@item @kbd{C-M-a} (AWK Mode) (@code{c-awk-beginning-of-defun}) -@itemx @kbd{C-M-e} (AWK Mode) (@code{c-awk-end-of-defun}) -@kindex C-M-a (AWK Mode) -@kindex C-M-e (AWK Mode) -@findex c-awk-beginning-of-defun -@findex awk-beginning-of-defun (c-) -@findex c-awk-end-of-defun -@findex awk-end-of-defun (c-) -Move to the beginning or end of the current or next AWK defun. These -commands can take prefix-arguments, their functionality being entirely -equivalent to @code{beginning-of-defun} and @code{end-of-defun}. - -AWK Mode @dfn{defuns} are either pattern/action pairs (either of which -might be implicit) or user defined functions. Having the @samp{@{} and -@samp{@}} (if there are any) in column zero, as is suggested for some -modes, is neither necessary nor helpful in AWK mode. - -@item @kbd{M-a} (@code{c-beginning-of-statement}) -@itemx @kbd{M-e} (@code{c-end-of-statement}) -@kindex M-a -@kindex M-e -@findex c-beginning-of-statement -@findex c-end-of-statement -@findex beginning-of-statement (c-) -@findex end-of-statement (c-) -Move to the beginning or end of the innermost C statement. If point -is already there, move to the next beginning or end of a statement, -even if that means moving into a block. (Use @kbd{C-M-b} or -@kbd{C-M-f} to move over a balanced block.) A prefix argument @var{n} -means move over @var{n} statements. - -If point is within or next to a comment or a string which spans more -than one line, these commands move by sentences instead of statements. - -When called from a program, these functions take three optional -arguments: the repetition count, a buffer position limit which is the -farthest back to search for the syntactic context, and a flag saying -whether to do sentence motion in or near comments and multiline -strings. - -@item @kbd{C-c C-u} (@code{c-up-conditional}) -@kindex C-c C-u -@findex c-up-conditional -@findex up-conditional (c-) -Move back to the containing preprocessor conditional, leaving the mark -behind. A prefix argument acts as a repeat count. With a negative -argument, move forward to the end of the containing preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going backward, but not when going -forward. - -This key sequence is not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-up-conditional-with-else} -@findex c-up-conditional-with-else -@findex up-conditional-with-else (c-) -A variety of @code{c-up-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{M-x c-down-conditional} -@findex c-down-conditional -@findex down-conditional (c-) -Move forward into the next nested preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move backward into the previous nested preprocessor -conditional. - -@samp{#elif} is treated like @samp{#else} followed by @samp{#if}, so the -function stops at them when going forward, but not when going backward. - -@item @kbd{M-x c-down-conditional-with-else} -@findex c-down-conditional-with-else -@findex down-conditional-with-else (c-) -A variety of @code{c-down-conditional} that also stops at @samp{#else} -lines. Normally those lines are ignored. - -@item @kbd{C-c C-p} (@code{c-backward-conditional}) -@itemx @kbd{C-c C-n} (@code{c-forward-conditional}) -@kindex C-c C-p -@kindex C-c C-n -@findex c-backward-conditional -@findex c-forward-conditional -@findex backward-conditional (c-) -@findex forward-conditional (c-) -Move backward or forward across a preprocessor conditional, leaving -the mark behind. A prefix argument acts as a repeat count. With a -negative argument, move in the opposite direction. - -These key sequences are not bound in AWK Mode, which doesn't have -preprocessor statements. - -@item @kbd{M-x c-backward-into-nomenclature} -@itemx @kbd{M-x c-forward-into-nomenclature} -@findex c-backward-into-nomenclature -@findex c-forward-into-nomenclature -@findex backward-into-nomenclature (c-) -@findex forward-into-nomenclature (c-) -A popular programming style, especially for object-oriented languages -such as C++ is to write symbols in a mixed case format, where the -first letter of each word is capitalized, and not separated by -underscores. E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. - -These commands move backward or forward to the beginning of the next -capitalized word. With prefix argument @var{n}, move @var{n} times. -If @var{n} is negative, move in the opposite direction. - -Note that these two commands have been superseded by -@code{c-subword-mode}, which you should use instead. @xref{Subword -Movement}. They might be removed from a future release of @ccmode{}. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Filling and Breaking, Minor Modes, Movement Commands, Commands -@comment node-name, next, previous, up -@section Filling and Line Breaking Commands -@cindex text filling -@cindex line breaking -@cindex comment handling -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. The goal -is to do it seamlessly, i.e. you can use auto fill mode, sentence and -paragraph movement, paragraph filling, adaptive filling etc. wherever -there's a piece of normal text without having to think much about it. -@ccmode{} keeps the indentation, fixes suitable comment line prefixes, -and so on. - -You can configure the exact way comments get filled and broken, and -where Emacs does auto-filling (see @pxref{Custom Filling and -Breaking}). Typically, the style system (@pxref{Styles}) will have -set this up for you, so you probably won't have to bother. - -@findex auto-fill-mode -@cindex Auto Fill mode -@cindex paragraph filling -Line breaks are by default handled (almost) the same regardless of -whether they are made by auto fill mode (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}}), by paragraph filling (e.g. with -@kbd{M-q}), or explicitly with @kbd{M-j} or similar methods. In -string literals, the new line gets the same indentation as the -previous nonempty line.@footnote{You can change this default by -setting the @code{string} syntactic symbol (@pxref{Syntactic Symbols} -and @pxref{Customizing Indentation})}. - -@table @asis -@item @kbd{M-q} (@code{c-fill-paragraph}) -@kindex M-q -@findex c-fill-paragraph -@findex fill-paragraph (c-) -@cindex Javadoc markup -@cindex Pike autodoc markup -This command fills multiline string literals and both block -and line style comments. In Java buffers, the Javadoc markup words -are recognized as paragraph starters. The line oriented Pike autodoc -markup words are recognized in the same way in Pike mode. - -The formatting of the starters (@code{/*}) and enders (@code{*/}) of -block comments are kept as they were before the filling. I.e., if -either the starter or ender were on a line of its own, then it stays -on its own line; conversely, if the delimiter has comment text on its -line, it keeps at least one word of that text with it on the line. - -This command is the replacement for @code{fill-paragraph} in @ccmode{} -buffers. - -@item @kbd{M-j} (@code{c-indent-new-comment-line}) -@kindex M-j -@findex c-indent-new-comment-line -@findex indent-new-comment-line (c-) -This breaks the current line at point and indents the new line. If -point was in a comment, the new line gets the proper comment line -prefix. If point was inside a macro, a backslash is inserted before -the line break. It is the replacement for -@code{indent-new-comment-line}. - -@item @kbd{M-x c-context-line-break} -@findex c-context-line-break -@findex context-line-break (c-) -Insert a line break suitable to the context: If the point is inside a -comment, the new line gets the suitable indentation and comment line -prefix like @code{c-indent-new-comment-line}. In normal code it's -indented like @code{newline-and-indent} would do. In macros it acts -like @code{newline-and-indent} but additionally inserts and optionally -aligns the line ending backslash so that the macro remains unbroken. -@xref{Custom Macros}, for details about the backslash alignment. In a -string, a backslash is inserted only if the string is within a -macro@footnote{In GCC, unescaped line breaks within strings are -valid.}. - -This function is not bound to a key by default, but it's intended to be -used on the @kbd{RET} key. If you like the behavior of -@code{newline-and-indent} on @kbd{RET}, you should consider switching to -this function. @xref{Sample .emacs File}. - -@item @kbd{M-x c-context-open-line} -@findex c-context-open-line -@findex context-open-line (c-) -This is to @kbd{C-o} (@kbd{M-x open-line}) as -@code{c-context-line-break} is to @kbd{RET}. I.e. it works just like -@code{c-context-line-break} but leaves the point before the inserted -line break. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Minor Modes, Electric Keys, Filling and Breaking, Commands -@comment node-name, next, previous, up -@section Minor Modes -@cindex Minor Modes -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} contains several minor-mode-like features that you might -find useful while writing new code or editing old code: - -@table @asis -@item electric mode -When this is enabled, certain visible characters cause reformatting as -they are typed. This is normally helpful, but can be a nuisance when -editing chaotically formatted code. It can also be disconcerting, -especially for users who are new to @ccmode{}. -@item auto-newline mode -This automatically inserts newlines where you'd probably want to type -them yourself, e.g. after typing @samp{@}}s. Its action is suppressed -when electric mode is disabled. -@item hungry-delete mode -This lets you delete a contiguous block of whitespace with a single -key - for example, the newline and indentation just inserted by -auto-newline when you want to back up and write a comment after the -last statement. -@item subword mode -This mode makes basic word movement commands like @kbd{M-f} -(@code{forward-word}) and @kbd{M-b} (@code{backward-word}) treat the -parts of sillycapsed symbols as different words. -E.g. @samp{NSGraphicsContext} is treated as three words @samp{NS}, -@samp{Graphics}, and @samp{Context}. -@item syntactic-indentation mode -When this is enabled (which it normally is), indentation commands such -as @kbd{C-j} indent lines of code according to their syntactic -structure. Otherwise, a line is simply indented to the same level as -the previous one and @kbd{@key{TAB}} adjusts the indentation in steps -of `c-basic-offset'. -@end table - -Full details on how these minor modes work are at @ref{Electric Keys}, -@ref{Auto-newlines}, @ref{Hungry WS Deletion}, @ref{Subword Movement}, -and @ref{Indentation Engine Basics}. - -You can toggle each of these minor modes on and off, and you can -configure @ccmode{} so that it starts up with your favourite -combination of them (@pxref{Sample .emacs File}). By default, when -you initialize a buffer, electric mode and syntactic-indentation mode -are enabled but the other two modes are disabled. - -@ccmode{} displays the current state of the first four of these minor -modes on the modeline by appending letters to the major mode's name, -one letter for each enabled minor mode - @samp{l} for electric mode, -@samp{a} for auto-newline mode, @samp{h} for hungry delete mode, and -@samp{w} for subword mode. If all these modes were enabled, you'd see -@samp{C/lahw}@footnote{The @samp{C} would be replaced with the name of -the language in question for the other languages @ccmode{} supports.}. - -Here are the commands to toggle these modes: - -@table @asis -@item @kbd{C-c C-l} (@code{c-toggle-electric-state}) -@kindex C-c C-l -@findex c-toggle-electric-state -@findex toggle-electric-state (c-) -Toggle electric minor mode. When the command turns the mode off, it -also suppresses auto-newline mode. - -@item @kbd{C-c C-a} (@code{c-toggle-auto-newline}) -@kindex C-c C-a -@findex c-toggle-auto-newline -@findex toggle-auto-newline (c-) -Toggle auto-newline minor mode. When the command turns the mode on, -it also enables electric minor mode. - -@item @kbd{M-x c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-d}.} -@findex c-toggle-hungry-state -@findex toggle-hungry-state (c-) -Toggle hungry-delete minor mode. - -@item @kbd{M-x c-toggle-auto-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command was bound to @kbd{C-c C-t}.} -@findex c-toggle-auto-hungry-state -@findex toggle-auto-hungry-state (c-) -Toggle both auto-newline and hungry delete minor modes. - -@item @kbd{C-c C-w} (@code{M-x c-subword-mode}) -@kindex C-c C-w -@findex c-subword-mode -@findex subword-mode (c-) -Toggle subword mode. - -@item @kbd{M-x c-toggle-syntactic-indentation} -@findex c-toggle-syntactic-indentation -@findex toggle-syntactic-indentation (c-) -Toggle syntactic-indentation mode. -@end table - -Common to all the toggle functions above is that if they are called -programmatically, they take an optional numerical argument. A -positive value will turn on the minor mode (or both of them in the -case of @code{c-toggle-auto-hungry-state}) and a negative value will -turn it (or them) off. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Electric Keys, Auto-newlines, Minor Modes, Commands -@comment node-name, next, previous, up -@section Electric Keys and Keywords -@cindex electric characters -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Most punctuation keys provide @dfn{electric} behavior - as well as -inserting themselves they perform some other action, such as -reindenting the line. This reindentation saves you from having to -reindent a line manually after typing, say, a @samp{@}}. A few -keywords, such as @code{else}, also trigger electric action. - -You can inhibit the electric behavior described here by disabling -electric minor mode (@pxref{Minor Modes}). - -Common to all these keys is that they only behave electrically when -used in normal code (as contrasted with getting typed in a string -literal or comment). Those which cause re-indentation do so only when -@code{c-syntactic-indentation} has a non-@code{nil} value (which it -does by default). - -These keys and keywords are: -@c ACM, 2004/8/24: c-electric-pound doesn't check c-s-i: this is more -@c like a bug in the code than a bug in this document. It'll get -@c fixed in the code sometime. - -@table @kbd -@item # -@kindex # -@findex c-electric-pound -@findex electric-pound (c-) -@vindex c-electric-pound-behavior -@vindex electric-pound-behavior (c-) -Pound (bound to @code{c-electric-pound}) is electric when typed as the -first non-whitespace character on a line and not within a macro -definition. In this case, the variable @code{c-electric-pound-behavior} -is consulted for the electric behavior. This variable takes a list -value, although the only element currently defined is @code{alignleft}, -which tells this command to force the @samp{#} character into column -zero. This is useful for entering preprocessor macro definitions. - -Pound is not electric in AWK buffers, where @samp{#} starts a comment, -and is bound to @code{self-insert-command} like any typical printable -character. -@c ACM, 2004/8/24: Change this (and the code) to do AWK comment -@c reindentation. - -@item * -@kindex * -@itemx / -@kindex / -@findex c-electric-star -@findex electric-star (c-) -@findex c-electric-slash -@findex electric-slash (c-) -A star (bound to @code{c-electric-star}) or a slash -(@code{c-electric-slash}) causes reindentation when you type it as the -second component of a C style block comment opener (@samp{/*}) or a -C++ line comment opener (@samp{//}) respectively, but only if the -comment opener is the first thing on the line (i.e. there's only -whitespace before it). - -Additionally, you can configure @ccmode{} so that typing a slash at -the start of a line within a block comment will terminate the -comment. You don't need to have electric minor mode enabled to get -this behavior. @xref{Clean-ups}. - -In AWK mode, @samp{*} and @samp{/} do not delimit comments and are not -electric. - -@item < -@kindex < -@itemx > -@kindex > -@findex c-electric-lt-gt -@findex electric-lt-gt (c-) -A less-than or greater-than sign (bound to @code{c-electric-lt-gt}) is -electric in two circumstances: when it is an angle bracket in a C++ -@samp{template} declaration (and similar constructs in other -languages) and when it is the second of two @kbd{<} or @kbd{>} -characters in a C++ style stream operator. In either case, the line -is reindented. Angle brackets in C @samp{#include} directives are not -electric. - -@item ( -@kindex ( -@itemx ) -@kindex ) -@findex c-electric-paren -@findex electric-paren (c-) -The normal parenthesis characters @samp{(} and @samp{)} (bound to -@code{c-electric-paren}) reindent the current line. This is useful -for getting the closing parenthesis of an argument list aligned -automatically. - -You can also configure @ccmode{} to insert a space automatically -between a function name and the @samp{(} you've just typed, and to -remove it automatically after typing @samp{)}, should the argument -list be empty. You don't need to have electric minor mode enabled to -get these actions. @xref{Clean-ups}. - -@item @{ -@kindex @{ -@itemx @} -@kindex @} -@findex c-electric-brace -@findex electric-brace (c-) -Typing a brace (bound to @code{c-electric-brace}) reindents the -current line. Also, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} to compact excess whitespace -inserted by auto-newline mode in certain circumstances. -@xref{Clean-ups}. - -@item : -@kindex : -@findex c-electric-colon -@findex electric-colon (c-) -Typing a colon (bound to @code{c-electric-colon}) reindents the -current line. Additionally, one or more newlines might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. If you -type a second colon immediately after such an auto-newline, by default -the whitespace between the two colons is removed, leaving a C++ scope -operator. @xref{Clean-ups}. - -If you prefer, you can insert @samp{::} in a single operation, -avoiding all these spurious reindentations, newlines, and clean-ups. -@xref{Other Commands}. - -@item ; -@kindex ; -@itemx , -@kindex , -@findex c-electric-semi&comma -@findex electric-semi&comma (c-) -Typing a semicolon or comma (bound to @code{c-electric-semi&comma}) -reindents the current line. Also, a newline might be inserted if -auto-newline minor mode is enabled. @xref{Auto-newlines}. -Additionally, you can configure @ccmode{} so that when auto-newline -has inserted whitespace after a @samp{@}}, it will be removed again -when you type a semicolon or comma just after it. @xref{Clean-ups}. - -@end table - -@deffn Command c-electric-continued-statement -@findex electric-continued-statement (c-) - -Certain keywords are electric, causing reindentation when they are -preceded only by whitespace on the line. The keywords are those that -continue an earlier statement instead of starting a new one: -@code{else}, @code{while}, @code{catch} (only in C++ and Java) and -@code{finally} (only in Java). - -An example: - -@example -@group -for (i = 0; i < 17; i++) - if (a[i]) - res += a[i]->offset; -else -@end group -@end example - -Here, the @code{else} should be indented like the preceding @code{if}, -since it continues that statement. @ccmode{} will automatically -reindent it after the @code{else} has been typed in full, since only -then is it possible to decide whether it's a new statement or a -continuation of the preceding @code{if}. - -@vindex abbrev-mode -@findex abbrev-mode -@cindex Abbrev mode -@ccmode{} uses Abbrev mode (@pxref{Abbrevs,,, @emacsman{}, @emacsmantitle{}}) -to accomplish this. It's therefore turned on by default in all language -modes except IDL mode, since CORBA IDL doesn't have any statements. -@end deffn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Auto-newlines, Hungry WS Deletion, Electric Keys, Commands -@comment node-name, next, previous, up -@section Auto-newline Insertion -@cindex auto-newline -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you have @dfn{Auto-newline minor mode} enabled (@pxref{Minor -Modes}), @ccmode{} inserts newlines for you automatically (in certain -syntactic contexts) when you type a left or right brace, a colon, a -semicolon, or a comma. Sometimes a newline appears before the -character you type, sometimes after it, sometimes both. - -Auto-newline only triggers when the following conditions hold: - -@itemize @bullet -@item -Auto-newline minor mode is enabled, as evidenced by the indicator -@samp{a} after the mode name on the modeline (e.g. @samp{C/a} or -@samp{C/la}). - -@item -The character was typed at the end of a line, or with only whitespace -after it, and possibly a @samp{\} escaping the newline. - -@item -The character is not on its own line already. (This applies only to -insertion of a newline @emph{before} the character.) - -@item -@cindex literal -@cindex syntactic whitespace -The character was not typed inside of a literal @footnote{A -@dfn{literal} is defined as any comment, string, or preprocessor macro -definition. These constructs are also known as @dfn{syntactic -whitespace} since they are usually ignored when scanning C code.}. - -@item -No numeric argument was supplied to the command (i.e. it was typed as -normal, with no @kbd{C-u} prefix). -@end itemize - -You can configure the precise circumstances in which newlines get -inserted (see @pxref{Custom Auto-newlines}). Typically, the style -system (@pxref{Styles}) will have set this up for you, so you probably -won't have to bother. - -Sometimes @ccmode{} inserts an auto-newline where you don't want one, -such as after a @samp{@}} when you're about to type a @samp{;}. -Hungry deletion can help here (@pxref{Hungry WS Deletion}), or you can -activate an appropriate @dfn{clean-up}, which will remove the excess -whitespace after you've typed the @samp{;}. See @ref{Clean-ups} for a -full description. See also @ref{Electric Keys} for a summary of -clean-ups listed by key. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hungry WS Deletion, Subword Movement, Auto-newlines, Commands -@comment node-name, next, previous, up -@section Hungry Deletion of Whitespace -@cindex hungry-deletion -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you want to delete an entire block of whitespace at point, you can -use @dfn{hungry deletion}. This deletes all the contiguous whitespace -either before point or after point in a single operation. -``Whitespace'' here includes tabs and newlines, but not comments or -preprocessor commands. Hungry deletion can markedly cut down on the -number of times you have to hit deletion keys when, for example, -you've made a mistake on the preceding line and have already pressed -@kbd{C-j}. - -Hungry deletion is a simple feature that some people find extremely -useful. In fact, you might find yourself wanting it in @strong{all} -your editing modes! - -Loosely speaking, in what follows, @dfn{@key{DEL}} means ``the -backspace key'' and @dfn{@key{DELETE}} means ``the forward delete -key''. This is discussed in more detail below. - -There are two different ways you can use hungry deletion: - -@table @asis -@item Using @dfn{Hungry Delete Mode} with @kbd{@key{DEL}} and @kbd{C-d} -Here you toggle Hungry Delete minor mode with @kbd{M-x -c-toggle-hungry-state}@footnote{Prior to @ccmode{} 5.31, this command -was bound to @kbd{C-c C-d}. @kbd{C-c C-d} is now the default binding -for @code{c-hungry-delete-forward}.} (@pxref{Minor Modes}.) This -makes @kbd{@key{DEL}} and @kbd{C-d} do backwards and forward hungry -deletion. - -@table @asis -@item @kbd{@key{DEL}} (@code{c-electric-backspace}) -@kindex DEL -@findex c-electric-backspace -@findex electric-backspace (c-) -This command is run by default when you hit the @kbd{DEL} key. When -hungry delete mode is enabled, it deletes any amount of whitespace in -the backwards direction. Otherwise, or when used with a prefix -argument or in a literal (@pxref{Auto-newlines}), the command just -deletes backwards in the usual way. (More precisely, it calls the -function contained in the variable @code{c-backspace-function}, -passing it the prefix argument, if any.) - -@item @code{c-backspace-function} -@vindex c-backspace-function -@vindex backspace-function (c-) -@findex backward-delete-char-untabify -Hook that gets called by @code{c-electric-backspace} when it doesn't -do an ``electric'' deletion of the preceding whitespace. The default -value is @code{backward-delete-char-untabify} -(@pxref{Deletion,,,@lispref{}, @lispreftitle{}}, the function which -deletes a single character. - -@item @kbd{C-d} (@code{c-electric-delete-forward}) -@kindex C-d -@findex c-electric-delete-forward -@findex electric-delete-forward (c-) -This function, which is bound to @kbd{C-d} by default, works just like -@code{c-electric-backspace} but in the forward direction. When it -doesn't do an ``electric'' deletion of the following whitespace, it -just does @code{delete-char}, more or less. (Strictly speaking, it -calls the function in @code{c-delete-function} with the prefix -argument.) - -@item @code{c-delete-function} -@vindex c-delete-function -@vindex delete-function (c-) -@findex delete-char -Hook that gets called by @code{c-electric-delete-forward} when it -doesn't do an ``electric'' deletion of the following whitespace. The -default value is @code{delete-char}. -@end table - -@item Using Distinct Bindings -The other (newer and recommended) way to use hungry deletion is to -perform @code{c-hungry-delete-backwards} and -@code{c-hungry-delete-forward} directly through their key sequences -rather than using the minor mode toggling. - -@table @asis -@item @kbd{C-c C-@key{DEL}}, or @kbd{C-c @key{DEL}} (@code{c-hungry-delete-backwards})@footnote{This command was formerly known as @code{c-hungry-backspace}.} -@kindex C-c C- -@kindex C-c -@kindex C-c C-DEL -@kindex C-c DEL -@findex c-hungry-delete-backwards -@findex hungry-delete-backwards (c-) -Delete any amount of whitespace in the backwards direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DEL}} and @kbd{C-c @key{DEL}}, since the more -natural one, @kbd{C-c C-@key{DEL}}, is sometimes difficult to type at -a character terminal. - -@item @kbd{C-c C-d}, @kbd{C-c C-@key{DELETE}}, or @kbd{C-c @key{DELETE}} (@code{c-hungry-delete-forward}) -@kindex C-c C-d -@kindex C-c C- -@kindex C-c -@findex c-hungry-delete-forward -@findex hungry-delete-forward (c-) -Delete any amount of whitespace in the forward direction (regardless -whether hungry-delete mode is enabled or not). This command is bound -to both @kbd{C-c C-@key{DELETE}} and @kbd{C-c @key{DELETE}} for the -same reason as for @key{DEL} above. -@end table -@end table - -@kindex -@kindex - -When we talk about @kbd{@key{DEL}}, and @kbd{@key{DELETE}} above, we -actually do so without connecting them to the physical keys commonly -known as @key{Backspace} and @key{Delete}. The default bindings to -those two keys depends on the flavor of (X)Emacs you are using. - -@findex c-electric-delete -@findex electric-delete (c-) -@findex c-hungry-delete -@findex hungry-delete (c-) -@vindex delete-key-deletes-forward -In XEmacs 20.3 and beyond, the @key{Backspace} key is bound to -@code{c-electric-backspace} and the @key{Delete} key is bound to -@code{c-electric-delete}. You control the direction it deletes in by -setting the variable @code{delete-key-deletes-forward}, a standard -XEmacs variable. -@c This variable is encapsulated by XEmacs's (defsubst delete-forward-p ...). -When this variable is non-@code{nil}, @code{c-electric-delete} will do -forward deletion with @code{c-electric-delete-forward}, otherwise it -does backward deletion with @code{c-electric-backspace}. Similarly, -@kbd{C-c @key{Delete}} and @kbd{C-c C-@key{Delete}} are bound to -@code{c-hungry-delete} which is controlled in the same way by -@code{delete-key-deletes-forward}. - -@findex normal-erase-is-backspace-mode - -Emacs 21 and later automatically binds @key{Backspace} and -@key{Delete} to @kbd{DEL} and @kbd{C-d} according to your environment, -and @ccmode{} extends those bindings to @kbd{C-c C-@key{Backspace}} -etc. If you need to change the bindings through -@code{normal-erase-is-backspace-mode} then @ccmode{} will also adapt -its extended bindings accordingly. - -In earlier (X)Emacs versions, @ccmode{} doesn't bind either -@key{Backspace} or @key{Delete} directly. Only the key codes -@kbd{DEL} and @kbd{C-d} are bound, and it's up to the default bindings -to map the physical keys to them. You might need to modify this -yourself if the defaults are unsuitable. - -Getting your @key{Backspace} and @key{Delete} keys properly set up can -sometimes be tricky. The information in @ref{DEL Does Not -Delete,,,emacs, GNU Emacs Manual}, might be helpful if you're having -trouble with this in GNU Emacs. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Subword Movement, Other Commands, Hungry WS Deletion, Commands -@comment node-name, next, previous, up -@section Subword Movement and Editing -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex nomenclature -@cindex subword -In spite of the GNU Coding Standards, it is popular to name a symbol -by mixing uppercase and lowercase letters, e.g. @samp{GtkWidget}, -@samp{EmacsFrameClass}, or @samp{NSGraphicsContext}. Here we call -these mixed case symbols @dfn{nomenclatures}. Also, each capitalized -(or completely uppercase) part of a nomenclature is called a -@dfn{subword}. Here are some examples: - -@multitable {@samp{NSGraphicsContext}} {@samp{NS}, @samp{Graphics}, and @samp{Context}} -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Nomenclature} - @tab @b{Subwords} -@end iftex -@ifnottex -@item Nomenclature - @tab Subwords -@item --------------------------------------------------------- -@end ifnottex -@item @samp{GtkWindow} - @tab @samp{Gtk} and @samp{Window} -@item @samp{EmacsFrameClass} - @tab @samp{Emacs}, @samp{Frame}, and @samp{Class} -@item @samp{NSGraphicsContext} - @tab @samp{NS}, @samp{Graphics}, and @samp{Context} -@end multitable - -The subword minor mode replaces the basic word oriented movement and -editing commands with variants that recognize subwords in a -nomenclature and treat them as separate words: - -@findex c-forward-subword -@findex forward-subword (c-) -@findex c-backward-subword -@findex backward-subword (c-) -@findex c-mark-subword -@findex mark-subword (c-) -@findex c-kill-subword -@findex kill-subword (c-) -@findex c-backward-kill-subword -@findex backward-kill-subword (c-) -@findex c-transpose-subwords -@findex transpose-subwords (c-) -@findex c-capitalize-subword -@findex capitalize-subword (c-) -@findex c-upcase-subword -@findex upcase-subword (c-) -@findex c-downcase-subword -@findex downcase-subword (c-) -@multitable @columnfractions .20 .40 .40 -@c This could be converted to @headitem when we require Texinfo 4.7 -@iftex -@item @b{Key} @tab @b{Word oriented command} @tab @b{Subword oriented command} -@end iftex -@ifnottex -@item Key @tab Word oriented command @tab Subword oriented command -@item ---------------------------------------------------------------------------- -@end ifnottex -@item @kbd{M-f} @tab @code{forward-word} @tab @code{c-forward-subword} -@item @kbd{M-b} @tab @code{backward-word} @tab @code{c-backward-subword} -@item @kbd{M-@@} @tab @code{mark-word} @tab @code{c-mark-subword} -@item @kbd{M-d} @tab @code{kill-word} @tab @code{c-kill-subword} -@item @kbd{M-DEL} @tab @code{backward-kill-word} @tab @code{c-backward-kill-subword} -@item @kbd{M-t} @tab @code{transpose-words} @tab @code{c-transpose-subwords} -@item @kbd{M-c} @tab @code{capitalize-word} @tab @code{c-capitalize-subword} -@item @kbd{M-u} @tab @code{upcase-word} @tab @code{c-upcase-subword} -@item @kbd{M-l} @tab @code{downcase-word} @tab @code{c-downcase-subword} -@end multitable - -Note that if you have changed the key bindings for the word oriented -commands in your @file{.emacs} or a similar place, the keys you have -configured are also used for the corresponding subword oriented -commands. - -Type @kbd{C-c C-w} to toggle subword mode on and off. To make the -mode turn on automatically, put the following code in your -@file{.emacs}: - -@example -(add-hook 'c-mode-common-hook - (lambda () (c-subword-mode 1))) -@end example - -As a bonus, you can also use @code{c-subword-mode} in non-@ccmode{} -buffers by typing @kbd{M-x c-subword-mode}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Commands, , Subword Movement, Commands -@comment node-name, next, previous, up -@section Other Commands -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here are the various other commands that didn't fit anywhere else: - -@table @asis -@item @kbd{C-c .} (@code{c-set-style}) -@kindex C-c . -@findex c-set-style -@findex set-style (c-) -Switch to the specified style in the current buffer. Use like this: - -@example -@kbd{C-c . @var{style-name} @key{RET}} -@end example - -You can use the @key{TAB} in the normal way to do completion on the -style name. Note that all style names are case insensitive, even the -ones you define yourself. - -Setting a style in this way does @emph{not} automatically reindent your -file. For commands that you can use to view the effect of your changes, -see @ref{Indentation Commands} and @ref{Filling and Breaking}. - -For details of the @ccmode{} style system, see @ref{Styles}. -@item @kbd{C-c :} (@code{c-scope-operator}) -@kindex C-c : -@findex c-scope-operator -@findex scope-operator (c-) -In C++, it is also sometimes desirable to insert the double-colon scope -operator without performing the electric behavior of colon insertion. -@kbd{C-c :} does just this. - -@item @kbd{C-c C-\} (@code{c-backslash-region}) -@kindex C-c C-\ -@findex c-backslash-region -@findex backslash-region (c-) -This function inserts and aligns or deletes end-of-line backslashes in -the current region. These are typically used in multi-line macros. - -With no prefix argument, it inserts any missing backslashes and aligns -them according to the @code{c-backslash-column} and -@code{c-backslash-max-column} variables. With a prefix argument, it -deletes any backslashes. - -The function does not modify blank lines at the start of the region. If -the region ends at the start of a line, it always deletes the backslash -(if any) at the end of the previous line. - -To customize the precise workings of this command, @ref{Custom Macros}. -@end table - -@noindent -The recommended line breaking function, @code{c-context-line-break} -(@pxref{Filling and Breaking}), is especially nice if you edit -multiline macros frequently. When used inside a macro, it -automatically inserts and adjusts the mandatory backslash at the end -of the line to keep the macro together, and it leaves the point at the -right indentation column for the code. Thus you can write code inside -macros almost exactly as you can elsewhere, without having to bother -with the trailing backslashes. - -@table @asis -@item @kbd{C-c C-e} (@code{c-macro-expand}) -@kindex C-c C-e -@findex c-macro-expand -@findex macro-expand (c-) -This command expands C, C++, Objective C or Pike macros in the region, -using an appropriate external preprocessor program. Normally it -displays its output in a temporary buffer, but if you give it a prefix -arg (with @kbd{C-u C-c C-e}) it will overwrite the original region -with the expansion. - -The command does not work in any of the other modes, and the key -sequence is not bound in these other modes. - -@code{c-macro-expand} isn't actually part of @ccmode{}, even though it -is bound to a @ccmode{} key sequence. If you need help setting it up -or have other problems with it, you can either read its source code or -ask for help in the standard (X)Emacs forums. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking, Config Basics, Commands, Top -@comment node-name, next, previous, up -@chapter Font Locking -@cindex font locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Font Lock mode - -@ccmode{} provides font locking for its supported languages by -supplying patterns for use with Font Lock mode. This means that you -get distinct faces on the various syntactic parts such as comments, -strings, keywords and types, which is very helpful in telling them -apart at a glance and discovering syntactic errors. @xref{Font -Lock,,, emacs, GNU Emacs Manual}, for ways to enable font locking in -@ccmode{} buffers. - -@strong{Please note:} The font locking in AWK mode is currently not -integrated with the rest of @ccmode{}. Only the last section of this -chapter, @ref{AWK Mode Font Locking}, applies to AWK. The other -sections apply to the other languages. - -@menu -* Font Locking Preliminaries:: -* Faces:: -* Doc Comments:: -* AWK Mode Font Locking:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Font Locking Preliminaries, Faces, Font Locking, Font Locking -@comment node-name, next, previous, up -@section Font Locking Preliminaries -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The font locking for most of the @ccmode{} languages were provided -directly by the Font Lock package prior to version 5.30 of @ccmode{}. -In the transition to @ccmode{} the patterns have been reworked -completely and are applied uniformly across all the languages except AWK -mode, just like the indentation rules (although each language still has -some peculiarities of its own, of course). Since the languages -previously had completely separate font locking patterns, this means -that it's a bit different in most languages now. - -The main goal for the font locking in @ccmode{} is accuracy, to provide -a dependable aid in recognizing the various constructs. Some, like -strings and comments, are easy to recognize while others, like -declarations and types, can be very tricky. @ccmode{} can go to great -lengths to recognize declarations and casts correctly, especially when -the types aren't recognized by standard patterns. This is a fairly -demanding analysis which can be slow on older hardware, and it can -therefore be disabled by choosing a lower decoration level with the -variable @code{font-lock-maximum-decoration} (@pxref{Font Lock,,, -emacs, GNU Emacs Manual}). - -@vindex font-lock-maximum-decoration - -The decoration levels are used as follows: - -@enumerate -@comment 1 -@item -Minimal font locking: Fontify only comments, strings and preprocessor -directives (in the languages that use cpp). - -@comment 2 -@item -Fast font locking: In addition to level 1, fontify keywords, simple -types and declarations that are easy to recognize. The variables -@code{*-font-lock-extra-types} (where @samp{*} is the name of the -language) are used to recognize types (see below). Documentation -comments like Javadoc are fontified according to -@code{c-doc-comment-style} (@pxref{Doc Comments}). - -Use this if you think the font locking is too slow. It's the closest -corresponding level to level 3 in the old font lock patterns. - -@comment 3 -@item -Accurate font locking: Like level 2 but uses a different approach that -can recognize types and declarations much more accurately. The -@code{*-font-lock-extra-types} variables are still used, but user -defined types are recognized correctly anyway in most cases. Therefore -those variables should be fairly restrictive and not contain patterns -that are uncertain. - -@cindex Lazy Lock mode -@cindex Just-in-time Lock mode - -This level is designed for fairly modern hardware and a font lock -support mode like Lazy Lock or Just-in-time Lock mode that only -fontifies the parts that are actually shown. Fontifying the whole -buffer at once can easily get bothersomely slow even on contemporary -hardware. @xref{Font Lock,,,@emacsman{}, @emacsmantitle{}}. -@end enumerate - -@cindex user defined types -@cindex types, user defined - -Since user defined types are hard to recognize you can provide -additional regexps to match those you use: - -@defopt c-font-lock-extra-types -@defoptx c++-font-lock-extra-types -@defoptx objc-font-lock-extra-types -@defoptx java-font-lock-extra-types -@defoptx idl-font-lock-extra-types -@defoptx pike-font-lock-extra-types -For each language there's a variable @code{*-font-lock-extra-types}, -where @samp{*} stands for the language in question. It contains a list -of regexps that matches identifiers that should be recognized as types, -e.g. @samp{\\sw+_t} to recognize all identifiers ending with @samp{_t} -as is customary in C code. Each regexp should not match more than a -single identifier. - -The default values contain regexps for many types in standard runtime -libraries that are otherwise difficult to recognize, and patterns for -standard type naming conventions like the @samp{_t} suffix in C and C++. -Java, Objective-C and Pike have as a convention to start class names -with capitals, so there are patterns for that in those languages. - -Despite the names of these variables, they are not only used for -fontification but in other places as well where @ccmode{} needs to -recognize types. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Faces, Doc Comments, Font Locking Preliminaries, Font Locking -@comment node-name, next, previous, up -@section Faces -@cindex faces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} attempts to use the standard faces for programming languages -in accordance with their intended purposes as far as possible. No extra -faces are currently provided, with the exception of a replacement face -@code{c-invalid-face} for emacsen that don't provide -@code{font-lock-warning-face}. - -@itemize @bullet -@item -@vindex font-lock-comment-face -Normal comments are fontified in @code{font-lock-comment-face}. - -@item -@vindex font-lock-doc-face -@vindex font-lock-doc-string-face -@vindex font-lock-comment-face -Comments that are recognized as documentation (@pxref{Doc Comments}) -get @code{font-lock-doc-face} (Emacs) or -@code{font-lock-doc-string-face} (XEmacs) if those faces exist. If -they don't then @code{font-lock-comment-face} is used. - -@item -@vindex font-lock-string-face -String and character literals are fontified in -@code{font-lock-string-face}. - -@item -@vindex font-lock-keyword-face -Keywords are fontified with @code{font-lock-keyword-face}. - -@item -@vindex font-lock-function-name-face -@code{font-lock-function-name-face} is used for function names in -declarations and definitions, and classes in those contexts. It's also -used for preprocessor defines with arguments. - -@item -@vindex font-lock-variable-name-face -Variables in declarations and definitions, and other identifiers in such -variable contexts, get @code{font-lock-variable-name-face}. It's also -used for preprocessor defines without arguments. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Builtin constants are fontified in @code{font-lock-constant-face} if it -exists, @code{font-lock-reference-face} otherwise. As opposed to the -preceding two faces, this is used on the names in expressions, and it's -not used in declarations, even if there happen to be a @samp{const} in -them somewhere. - -@item -@vindex font-lock-type-face -@code{font-lock-type-face} is put on types (both predefined and user -defined) and classes in type contexts. - -@item -@vindex font-lock-constant-face -@vindex font-lock-reference-face -Label identifiers get @code{font-lock-constant-face} if it exists, -@code{font-lock-reference-face} otherwise. - -@item -Name qualifiers and identifiers for scope constructs are fontified like -labels. - -@item -Special markup inside documentation comments are also fontified like -labels. - -@item -@vindex font-lock-preprocessor-face -@vindex font-lock-builtin-face -@vindex font-lock-reference-face -Preprocessor directives get @code{font-lock-preprocessor-face} if it -exists (i.e. XEmacs). In Emacs they get @code{font-lock-builtin-face} -or @code{font-lock-reference-face}, for lack of a closer equivalent. - -@item -@vindex font-lock-warning-face -@vindex c-invalid-face -@vindex invalid-face (c-) -Some kinds of syntactic errors are fontified with -@code{font-lock-warning-face} in Emacs. In older XEmacs versions -there's no corresponding standard face, so there a special -@code{c-invalid-face} is used, which is defined to stand out sharply by -default. - -Note that it's not used for @samp{#error} or @samp{#warning} directives, -since those aren't syntactic errors in themselves. -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Doc Comments, AWK Mode Font Locking, Faces, Font Locking -@comment node-name, next, previous, up -@section Documentation Comments -@cindex documentation comments -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are various tools to supply documentation in the source as -specially structured comments, e.g. the standard Javadoc tool in Java. -@ccmode{} provides an extensible mechanism to fontify such comments and -the special markup inside them. - -@defopt c-doc-comment-style -@vindex doc-comment-style (c-) -This is a style variable that specifies which documentation comment -style to recognize, e.g. @code{javadoc} for Javadoc comments. - -The value may also be a list of styles, in which case all of them are -recognized simultaneously (presumably with markup cues that don't -conflict). - -The value may also be an association list to specify different comment -styles for different languages. The symbol for the major mode is then -looked up in the alist, and the value of that element is interpreted as -above if found. If it isn't found then the symbol `other' is looked up -and its value is used instead. - -The default value for @code{c-doc-comment-style} is -@w{@code{((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc))}}. - -Note that @ccmode{} uses this variable to set other variables that -handle fontification etc. That's done at mode initialization or when -you switch to a style which sets this variable. Thus, if you change it -in some other way, e.g. interactively in a CC Mode buffer, you will need -to do @kbd{M-x java-mode} (or whatever mode you're currently using) to -reinitialize. - -@findex c-setup-doc-comment-style -@findex setup-doc-comment-style (c-) -Note also that when @ccmode{} starts up, the other variables are -modified before the mode hooks are run. If you change this variable in -a mode hook, you'll have to call @code{c-setup-doc-comment-style} -afterwards to redo that work. -@end defopt - -@ccmode{} currently provides handing of the following doc comment -styles: - -@table @code -@item javadoc -@cindex Javadoc markup -Javadoc comments, the standard tool in Java. - -@item autodoc -@cindex Pike autodoc markup -For Pike autodoc markup, the standard in Pike. - -@item gtkdoc -@cindex GtkDoc markup -For GtkDoc markup, widely used in the Gnome community. -@end table - -The above is by no means complete. If you'd like to see support for -other doc comment styles, please let us know (@pxref{Mailing Lists and -Bug Reports}). - -You can also write your own doc comment fontification support to use -with @code{c-doc-comment-style}: Supply a variable or function -@code{*-font-lock-keywords} where @samp{*} is the name you want to use -in @code{c-doc-comment-style}. If it's a variable, it's prepended to -@code{font-lock-keywords}. If it's a function, it's called at mode -initialization and the result is prepended. For an example, see -@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. - -If you add support for another doc comment style, please consider -contributing it - send a note to @email{bug-cc-mode@@gnu.org}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node AWK Mode Font Locking, , Doc Comments, Font Locking -@comment node-name, next, previous, up -@section AWK Mode Font Locking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The general appearance of font-locking in AWK mode is much like in any -other programming mode. @xref{Faces For Font Lock,,,elisp, GNU Emacs -Lisp Reference Manual}. - -The following faces are, however, used in a non-standard fashion in -AWK mode: - -@table @asis -@item @code{font-lock-variable-name-face} -This face was intended for variable declarations. Since variables are -not declared in AWK, this face is used instead for AWK system -variables (such as @code{NF}) and ``Special File Names'' (such as -@code{"/dev/stderr"}). - -@item @code{font-lock-builtin-face} (Emacs)/@code{font-lock-preprocessor-face} (XEmacs) -This face is normally used for preprocessor directives in @ccmode{}. -There are no such things in AWK, so this face is used instead for -standard functions (such as @code{match}). - -@item @code{font-lock-string-face} -As well as being used for strings, including localizable strings, -(delimited by @samp{"} and @samp{_"}), this face is also used for AWK -regular expressions (delimited by @samp{/}). - -@item @code{font-lock-warning-face} (Emacs)/@code{c-invalid-face} (XEmacs) -This face highlights the following syntactically invalid AWK -constructs: - -@itemize @bullet -@item -An unterminated string or regular expression. Here the opening -delimiter (@samp{"} or @samp{/} or @samp{_"}) is displayed in -@code{font-lock-warning-face}. This is most noticeable when typing in a -new string/regular expression into a buffer, when the warning-face -serves as a continual reminder to terminate the construct. - -AWK mode fontifies unterminated strings/regular expressions -differently from other modes: Only the text up to the end of the line -is fontified as a string (escaped newlines being handled correctly), -rather than the text up to the next string quote. - -@item -A space between the function name and opening parenthesis when calling -a user function. The last character of the function name and the -opening parenthesis are highlighted. This font-locking rule will -spuriously highlight a valid concatenation expression where an -identifier precedes a parenthesised expression. Unfortunately. - -@item -Whitespace following the @samp{\} in what otherwise looks like an -escaped newline. The @samp{\} is highlighted. -@end itemize -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Config Basics, Custom Filling and Breaking, Font Locking, Top -@comment node-name, next, previous, up -@chapter Configuration Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex Emacs Initialization File -@cindex Configuration -You configure @ccmode{} by setting Lisp variables and calling (and -perhaps writing) Lisp functions@footnote{DON'T PANIC!!! This isn't -difficult.}, which is usually done by adding code to an Emacs -initialization file. This file might be @file{site-start.el} or -@file{.emacs} or @file{init.el} or @file{default.el} or perhaps some -other file. @xref{Init File,,,@emacsman{}, @emacsmantitle{}}. For -the sake of conciseness, we just call this file ``your @file{.emacs}'' -throughout the rest of the manual. - -Several of these variables (currently 16), are known collectively as -@dfn{style variables}. @ccmode{} provides a special mechanism, known -as @dfn{styles} to make it easier to set these variables as a group, -to ``inherit'' settings from one style into another, and so on. Style -variables remain ordinary Lisp variables, whose values can be read and -changed independently of the style system. @xref{Style Variables}. - -There are several ways you can write the code, depending on the -precise effect you want---they are described further down on this page. -If you are new to @ccmode{}, we suggest you begin with the simplest -method, ``Top-level commands or the customization interface''. - -If you make conflicting settings in several of these ways, the way -that takes precedence is the one that appears latest in this list: -@itemize @asis -@item -@table @asis -@item Style -@itemx Top-level command or ``customization interface'' -@itemx Hook -@itemx File Style -@end table -@end itemize - -Here is a summary of the different ways of writing your configuration -settings: - -@table @asis -@item Top-level commands or the ``customization interface'' -Most simply, you can write @code{setq} and similar commands at the top -level of your @file{.emacs} file. When you load a @ccmode{} buffer, -it initializes its configuration from these global values (at least, -for those settings you have given values to), so it makes sense to -have these @code{setq} commands run @emph{before} @ccmode{} is first -initialized---in particular, before any call to @code{desktop-read} -(@pxref{Saving Emacs Sessions,,, emacs, GNU Emacs Manual}). For -example, you might set c-basic-offset thus: - -@example -(setq c-basic-offset 4) -@end example - -You can use the more user friendly Customization interface instead, -but this manual does not cover in detail how that works. To do this, -start by typing @kbd{M-x customize-group @key{RET} c @key{RET}}. -@xref{Easy Customization,,,@emacsman{}, @emacsmantitle{}}. -@c The following note really belongs in the Emacs manual. -Emacs normally writes the customizations at the end of your -@file{.emacs} file. If you use @code{desktop-read}, you should edit -your @file{.emacs} to place the call to @code{desktop-read} @emph{after} -the customizations. - -The first initialization of @ccmode{} puts a snapshot of the -configuration settings into the special style @code{user}. -@xref{Built-in Styles}. - -For basic use of Emacs, either of these ways of configuring is -adequate. However, the settings are then the same in all @ccmode{} -buffers and it can be clumsy to communicate them between programmers. -For more flexibility, you'll want to use one (or both) of @ccmode{}'s -more sophisticated facilities, hooks and styles. - -@item Hooks -An Emacs @dfn{hook} is a place to put Lisp functions that you want -Emacs to execute later in specific circumstances. -@xref{Hooks,,,@lispref{}, @lispreftitle{}}. @ccmode{} supplies a main -hook and a language-specific hook for each language it supports - any -functions you put onto these hooks get executed as the last part of a -buffer's initialization. Typically you put most of your customization -within the main hook, and use the language-specific hooks to vary the -customization settings between language modes. For example, if you -wanted different (non-standard) values of @code{c-basic-offset} in C -Mode and Java Mode buffers, you could do it like this: - -@example -@group -(defun my-c-mode-hook () - (setq c-basic-offset 3)) -(add-hook 'c-mode-hook 'my-c-mode-hook) - -(defun my-java-mode-hook () - (setq c-basic-offset 6)) -(add-hook 'java-mode-hook 'my-java-mode-hook) -@end group -@end example - -See @ref{CC Hooks} for more details on the use of @ccmode{} hooks. - -@item Styles -A @ccmode{} @dfn{style} is a coherent collection of customizations -with a name. At any time, exactly one style is active in each -@ccmode{} buffer, either the one you have selected or a default. -@ccmode{} is delivered with several existing styles. Additionally, -you can create your own styles, possibly based on these existing -styles. If you worked in a programming team called the ``Free -Group'', which had its own coding standards, you might well have this -in your @file{.emacs} file: - -@example -(setq c-default-style '((java-mode . "java") - (awk-mode . "awk") - (other . "free-group-style"))) -@end example - -See @ref{Styles} for fuller details on using @ccmode{} styles and how -to create them. - -@item File Styles -A @dfn{file style} is a rarely used variant of the ``style'' mechanism -described above, which applies to an individual source file. To use -it, you set certain Emacs local variables in a special block at the -end of the source file. @xref{File Styles}. - -@item Hooks with Styles -For ultimate flexibility, you can use hooks and styles together. For -example, if your team were developing a product which required a -Linux driver, you'd probably want to use the ``linux'' style for the -driver, and your own team's style for the rest of the code. You -could achieve this with code like this in your @file{.emacs}: - -@example -@group -(defun my-c-mode-hook () - (c-set-style - (if (and (buffer-file-name) - (string-match "/usr/src/linux" (buffer-file-name))) - "linux" - "free-group-style"))) -(add-hook 'c-mode-hook 'my-c-mode-hook) -@end group -@end example - -In a programming team, a hook is a also a good place for each member -to put his own personal preferences. For example, you might be the -only person in your team who likes Auto-newline minor mode. You could -have it enabled by default by placing the following in your -@file{.emacs}: - -@example -@group -(defun my-turn-on-auto-newline () - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-turn-on-auto-newline) -@end group -@end example -@end table - -@menu -* CC Hooks:: -* Style Variables:: -* Styles:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node CC Hooks, Style Variables, Config Basics, Config Basics -@comment node-name, next, previous, up -@section Hooks -@cindex mode hooks -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@c The node name is "CC Hooks" rather than "Hooks" because of a bug in -@c some older versions of Info, e.g. the info.el in GNU Emacs 21.3. -@c If you go to "Config Basics" and hit on the xref to "CC -@c Hooks" the function Info-follow-reference searches for "*Note: CC -@c Hooks" from the beginning of the page. If this node were instead -@c named "Hooks", that search would spuriously find "*Note: -@c Hooks(elisp)" and go to the wrong node. - -@ccmode{} provides several hooks that you can use to customize the -mode for your coding style. The main hook is -@code{c-mode-common-hook}; typically, you'll put the bulk of your -customizations here. In addition, each language mode has its own -hook, allowing you to fine tune your settings individually for the -different @ccmode{} languages, and there is a package initialization -hook. Finally, there is @code{c-special-indent-hook}, which enables -you to solve anomalous indentation problems. It is described in -@ref{Other Indentation}, not here. All these hooks adhere to the -standard Emacs conventions. - -When you open a buffer, @ccmode{} first initializes it with the -currently active style (@pxref{Styles}). Then it calls -@code{c-mode-common-hook}, and finally it calls the language-specific -hook. Thus, any style settings done in these hooks will override -those set by @code{c-default-style}. - -@defvar c-initialization-hook -@vindex initialization-hook (c-) -Hook run only once per Emacs session, when @ccmode{} is initialized. -This is a good place to change key bindings (or add new ones) in any -of the @ccmode{} key maps. @xref{Sample .emacs File}. -@end defvar - -@defvar c-mode-common-hook -@vindex mode-common-hook (c-) -Common hook across all languages. It's run immediately before the -language specific hook. -@end defvar - -@defvar c-mode-hook -@defvarx c++-mode-hook -@defvarx objc-mode-hook -@defvarx java-mode-hook -@defvarx idl-mode-hook -@defvarx pike-mode-hook -@defvarx awk-mode-hook -The language specific mode hooks. The appropriate one is run as the -last thing when you enter that language mode. -@end defvar - -Although these hooks are variables defined in @ccmode{}, you can give -them values before @ccmode{}'s code is loaded---indeed, this is the -only way to use @code{c-initialization-hook}. Their values aren't -overwritten when @ccmode{} gets loaded. - -Here's a simplified example of what you can add to your @file{.emacs} -file to do things whenever any @ccmode{} language is edited. See the -Emacs manuals for more information on customizing Emacs via hooks. -@xref{Sample .emacs File}, for a more complete sample @file{.emacs} -file. - -@example -(defun my-c-mode-common-hook () - ;; my customizations for all of c-mode and related modes - (no-case-fold-search) - ) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Style Variables, Styles, CC Hooks, Config Basics -@comment node-name, next, previous, up -@section Style Variables -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex style variables -The variables that @ccmode{}'s style system control are called -@dfn{style variables}. Note that style variables are ordinary Lisp -variables, which the style system initializes; you can change their -values at any time (e.g. in a hook function). The style system can -also set other variables, to some extent. @xref{Styles}. - -@dfn{Style variables} are handled specially in several ways: - -@itemize @bullet -@item -Style variables are by default buffer-local variables. However, they -can instead be made global by setting -@code{c-style-variables-are-local-p} to @code{nil} before @ccmode{} is -initialized. - -@item -@vindex c-old-style-variable-behavior -@vindex old-style-variable-behavior (c-) -The default global binding of any style variable (with two exceptions -- see below) is the special symbol @code{set-from-style}. When the -style system initializes a buffer-local copy of a style variable for a -@ccmode{} buffer, if its global binding is still that symbol then it -will be set from the current style. Otherwise it will retain its -global default@footnote{This is a big change from versions of -@ccmode{} earlier than 5.26, where such settings would get overridden -by the style system unless special precautions were taken. That was -changed since it was counterintuitive and confusing, especially to -novice users. If your configuration depends on the old overriding -behavior, you can set the variable -@code{c-old-style-variable-behavior} to non-@code{nil}.}. This -``otherwise'' happens, for example, when you've set the variable with -@code{setq} at the top level of your @file{.emacs} (@pxref{Config -Basics}). - -@item -The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is -an association list with an element for each syntactic symbol. It's -handled a little differently from the other style variables. It's -default global binding is the empty list @code{nil}, rather than -@code{set-from-style}. Before the style system is initialized, you -can add individual elements to @code{c-offsets-alist} by calling -@code{c-set-offset}(@pxref{c-offsets-alist}) just like you would set -other style variables with @code{setq}. Those elements will then -prevail when the style system later initializes a buffer-local copy of -@code{c-offsets-alist}. - -@item -The style variable @code{c-special-indent-hook} is also handled in a -special way. Styles can only add functions to this hook, not remove -them, so any global settings you put on it are always -preserved@footnote{This did not change in version 5.26.}. The value -you give this variable in a style definition can be either a function -or a list of functions. - -@item -The global bindings of the style variables get captured in the special -@code{user} style when the style system is first initialized. -@xref{Built-in Styles}, for details. -@end itemize - -The style variables are:@* -@code{c-indent-comment-alist}, -@code{c-indent-comments-syntactically-p} (@pxref{Indentation -Commands});@* -@code{c-doc-comment-style} (@pxref{Doc Comments});@* -@code{c-block-comment-prefix}, @code{c-comment-prefix-regexp} -(@pxref{Custom Filling and Breaking});@* -@code{c-hanging-braces-alist} (@pxref{Hanging Braces});@* -@code{c-hanging-colons-alist} (@pxref{Hanging Colons});@* -@code{c-hanging-semi&comma-criteria} (@pxref{Hanging Semicolons and -Commas});@* -@code{c-cleanup-list} (@pxref{Clean-ups});@* -@code{c-basic-offset} (@pxref{Customizing Indentation});@* -@code{c-offsets-alist} (@pxref{c-offsets-alist});@* -@code{c-comment-only-line-offset} (@pxref{Comment Line-Up});@* -@code{c-special-indent-hook}, @code{c-label-minimum-indentation} -(@pxref{Other Indentation});@* -@code{c-backslash-column}, @code{c-backslash-max-column} -(@pxref{Custom Macros}). - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Styles, , Style Variables, Config Basics -@comment node-name, next, previous, up -@section Styles -@cindex styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -By @dfn{style} we mean the layout of the code---things like how many -columns to indent a block of code, whether an opening brace gets -indented to the level of the code it encloses, or of the construct -that introduces it, or ``hangs'' at the end of a line. - -Most people only need to edit code formatted in just a few well-defined -and consistent styles. For example, their organization might impose a -``blessed'' style that all its programmers must conform to. Similarly, -people who work on GNU software will have to use the GNU coding style. -Some shops are more lenient, allowing a variety of coding styles, and as -programmers come and go, there could be a number of styles in use. For -this reason, @ccmode{} makes it convenient for you to set up logical -groupings of customizations called @dfn{styles}, associate a single name -for any particular style, and pretty easily start editing new or -existing code using these styles. - -@menu -* Built-in Styles:: -* Choosing a Style:: -* Adding Styles:: -* File Styles:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Built-in Styles, Choosing a Style, Styles, Styles -@comment node-name, next, previous, up -@subsection Built-in Styles -@cindex styles, built-in -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If you're lucky, one of @ccmode{}'s built-in styles might be just -what you're looking for. These are: - -@table @code -@item gnu -@cindex GNU style -Coding style blessed by the Free Software Foundation -for C code in GNU programs. - -@item k&r -@cindex K&R style -The classic Kernighan and Ritchie style for C code. - -@item bsd -@cindex BSD style -Also known as ``Allman style'' after Eric Allman. - -@item whitesmith -@cindex Whitesmith style -Popularized by the examples that came with Whitesmiths C, an early -commercial C compiler. - -@item stroustrup -@cindex Stroustrup style -The classic Stroustrup style for C++ code. - -@item ellemtel -@cindex Ellemtel style -Popular C++ coding standards as defined by ``Programming in C++, Rules -and Recommendations,'' Erik Nyquist and Mats Henricson, -Ellemtel@footnote{This document is available at -@uref{http://www.doc.ic.ac.uk/lab/cplus/c++.rules/} among other -places.}. -@c N.B. This URL was still valid at 2005/8/28 (ACM). - -@item linux -@cindex Linux style -C coding standard for Linux (the kernel). - -@item python -@cindex Python style -C coding standard for Python extension modules@footnote{Python is a -high level scripting language with a C/C++ foreign function interface. -For more information, see @uref{http://www.python.org/}.}. - -@item java -@cindex Java style -The style for editing Java code. Note that the default -value for @code{c-default-style} installs this style when you enter -@code{java-mode}. - -@item awk -@cindex AWK style -The style for editing AWK code. Note that the default value for -@code{c-default-style} installs this style when you enter -@code{awk-mode}. - -@item user -@cindex User style -This is a special style created by you. It consists of the factory -defaults for all the style variables as modified by the customizations -you do either with the Customization interface or by writing -@code{setq}s and @code{c-set-offset}s at the top level of your -@file{.emacs} file (@pxref{Config Basics}). The style system creates -this style as part of its initialization and doesn't modify it -afterwards. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Choosing a Style, Adding Styles, Built-in Styles, Styles -@comment node-name, next, previous, up -@subsection Choosing a Style -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -When you create a new buffer, its style will be set from -@code{c-default-style}. The factory default is the style @code{gnu}, -except in Java and AWK modes where it's @code{java} and @code{awk}. - -Remember that if you set a style variable with the Customization -interface or at the top level of your @file{.emacs} file before the -style system is initialized (@pxref{Config Basics}), this setting will -override the one that the style system would have given the variable. - -To set a buffer's style interactively, use the command @kbd{C-c .} -(@pxref{Other Commands}). To set it from a file's local variable -list, @ref{File Styles}. - -@defopt c-default-style -@vindex default-style (c-) -This variable specifies which style to install by default in new -buffers. It takes either a style name string, or an association list -of major mode symbols to style names: - -@enumerate -@item -When @code{c-default-style} is a string, it must be an existing style -name. This style is then used for all modes. - -@item -When @code{c-default-style} is an association list, the mode language -is looked up to find a style name string. - -@item -If @code{c-default-style} is an association list where the mode -language mode isn't found then the special symbol @samp{other} is -looked up. If it's found then the associated style is used. - -@item -If @samp{other} is not found then the @samp{gnu} style is used. -@end enumerate - -In all cases, the style described in @code{c-default-style} is installed -@emph{before} the language hooks are run, so you can always override -this setting by including an explicit call to @code{c-set-style} in your -language mode hook, or in @code{c-mode-common-hook}. - -The standard value of @code{c-default-style} is @w{@code{((java-mode -. "java") (awk-mode . "awk") (other . "gnu"))}}. -@end defopt - -@defvar c-indentation-style -@vindex indentation-style (c-) -This variable always contains the buffer's current style name, as a -string. -@end defvar - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Adding Styles, File Styles, Choosing a Style, Styles -@comment node-name, next, previous, up -@subsection Adding and Amending Styles -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -If none of the built-in styles is appropriate, you'll probably want to -create a new @dfn{style definition}, possibly based on an existing -style. To do this, put the new style's settings into a list with the -following format - the list can then be passed as an argument to the -function @code{c-add-style}. You can see an example of a style -definition in @ref{Sample .emacs File}. - -@cindex style definition -@c @defvr {List} style definition -@table @asis -@item Structure of a Style Definition List -([@var{base-style}] [(@var{variable} . @var{value}) @dots{}]) - -Optional @var{base-style}, if present, must be a string which is the -name of the @dfn{base style} from which this style inherits. At most -one @var{base-style} is allowed in a style definition. If -@var{base-style} is not specified, the style inherits from the table -of factory default values@footnote{This table is stored internally in -the variable c-fallback-style.} instead. All styles eventually -inherit from this internal table. Style loops generate errors. The -list of pre-existing styles can be seen in @ref{Built-in Styles}. - -The dotted pairs (@var{variable} . @var{value}) each consist of a -variable and the value it is to be set to when the style is later -activated.@footnote{Note that if the variable has been given a value -by the Customization interface or a @code{setq} at the top level of -your @file{.emacs}, this value will override the one the style system -tries to give it. @xref{Config Basics}.} The variable can be either a -@ccmode{} style variable or an arbitrary Emacs variable. In the -latter case, it is @emph{not} made buffer-local by the @ccmode{} style -system. -@c @end defvr - -Two variables are treated specially in the dotted pair list: - -@table @code -@item c-offsets-alist -The value is in turn a list of dotted pairs of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{offset}}) -@end example - -as described in @ref{c-offsets-alist}. These are passed to -@code{c-set-offset} so there is no need to set every syntactic symbol -in your style, only those that are different from the inherited style. - -@item c-special-indent-hook -The value is added to @code{c-special-indent-hook} using -@code{add-hook}, so any functions already on it are kept. If the value -is a list, each element of the list is added with @code{add-hook}. -@end table -@end table - -Styles are kept in the @code{c-style-alist} variable, but you -should never modify this variable directly. Instead, @ccmode{} -provides the function @code{c-add-style} for this purpose. - -@defun c-add-style stylename description &optional set-p -@findex add-style (c-) -Add or update a style called @var{stylename}, a string. -@var{description} is the new style definition in the form described -above. If @var{stylename} already exists in @code{c-style-alist} then -it is replaced by @var{description}. (Note, this replacement is -total. The old style is @emph{not} merged into the new one.) -Otherwise, a new style is added. - -If the optional @var{set-p} is non-@code{nil} then the new style is -applied to the current buffer as well. The use of this facility is -deprecated and it might be removed from @ccmode{} in a future release. -You should use @code{c-set-style} instead. - -The sample @file{.emacs} file provides a concrete example of how a new -style can be added and automatically set. @xref{Sample .emacs File}. -@end defun - -@defvar c-style-alist -@vindex style-alist (c-) -This is the variable that holds the definitions for the styles. It -should not be changed directly; use @code{c-add-style} instead. -@end defvar - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node File Styles, , Adding Styles, Styles -@comment node-name, next, previous, up -@subsection File Styles -@cindex styles, file local -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex file local variables - -The Emacs manual describes how you can customize certain variables on a -per-file basis by including a @dfn{file local variable} block at the end -of the file (@pxref{File Variables,, Local Variables in Files, @emacsman{}, -@emacsmantitle{}}). - -So far, you've only seen a functional interface for setting styles in -@ccmode{}, and this can't be used here. @ccmode{} fills the gap by -providing two variables for use in a file's local variable list. -Don't use them anywhere else! These allow you to customize the style -on a per-file basis: - -@defvar c-file-style -@vindex file-style (c-) -Set this variable to a style name string in the Local Variables list. -From now on, when you visit the file, @ccmode{} will automatically set -the file's style to this one using @code{c-set-style}. -@end defvar - -@defvar c-file-offsets -@vindex file-offsets (c-) -Set this variable (in the Local Variables list) to an association list -of the same format as @code{c-offsets-alist}. From now on, when you -visit the file, @ccmode{} will automatically institute these offsets -using @code{c-set-offset}. -@end defvar - -Note that file style settings (i.e. @code{c-file-style}) are applied -before file offset settings -(i.e. @code{c-file-offsets})@footnote{Also, if either of these are set -in a file's local variable section, all the style variable values are -made local to that buffer, even if -@code{c-style-variables-are-local-p} is @code{nil}. Since this -variable is virtually always non-@code{nil} anyhow, you're unlikely to -notice this effect.}. - -If you set any variables, including style variables, by the file local -variables mechanism, these settings take priority over all other -settings, even those in your mode hooks (@pxref{CC Hooks}). If you -use @code{c-file-style} or @code{c-file-offsets} and also explicitly -set a style variable in a local variable block, the explicit setting -will take priority. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Filling and Breaking, Custom Auto-newlines, Config Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Filling and Line Breaking -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since there's a lot of normal text in comments and string literals, -@ccmode{} provides features to edit these like in text mode. It does -this by hooking in on the different line breaking functions and tuning -relevant variables as necessary. - -@vindex c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -@cindex comment line prefix -@vindex comment-start -@vindex comment-end -@vindex comment-start-skip -@vindex paragraph-start -@vindex paragraph-separate -@vindex paragraph-ignore-fill-prefix -@vindex adaptive-fill-mode -@vindex adaptive-fill-regexp -@vindex adaptive-fill-first-line-regexp -To make Emacs recognize comments and treat text in them as normal -paragraphs, @ccmode{} makes several standard -variables@footnote{@code{comment-start}, @code{comment-end}, -@code{comment-start-skip}, @code{paragraph-start}, -@code{paragraph-separate}, @code{paragraph-ignore-fill-prefix}, -@code{adaptive-fill-mode}, @code{adaptive-fill-regexp}, and -@code{adaptive-fill-first-line-regexp}.} buffer-local and modifies them -according to the language syntax and the comment line prefix. - -@defopt c-comment-prefix-regexp -@vindex comment-prefix-regexp (c-) -This style variable contains the regexp used to recognize the -@dfn{comment line prefix}, which is the line decoration that starts -every line in a comment. The variable is either the comment line -prefix itself, or (more usually) an association list with different -values for different languages. The symbol for the major mode is -looked up in the alist to get the regexp for the language, and if it -isn't found then the special symbol @samp{other} is looked up instead. - -When a comment line gets divided by @kbd{M-j} or the like, @ccmode{} -inserts the comment line prefix from a neighboring line at the start -of the new line. The default value of c-comment-prefix-regexp is -@samp{//+\\|\\**}, which matches C++ style line comments like - -@example -// blah blah -@end example - -@noindent -with two or more slashes in front of them, and the second and -subsequent lines of C style block comments like - -@example -@group -/* - * blah blah - */ -@end group -@end example - -@noindent -with zero or more stars at the beginning of every line. If you change -this variable, please make sure it still matches the comment starter -(i.e. @code{//}) of line comments @emph{and} the line prefix inside -block comments. - -@findex c-setup-paragraph-variables -@findex setup-paragraph-variables (c-) -Also note that since @ccmode{} uses the value of -@code{c-comment-prefix-regexp} to set up several other variables at -mode initialization, there won't be any effect if you just change it -inside a @ccmode{} buffer. You need to call the command -@code{c-setup-paragraph-variables} too, to update those other -variables. That's also the case if you modify -@code{c-comment-prefix-regexp} in a mode hook, since @ccmode{} will -already have set up these variables before calling the hook. -@end defopt - -In comments, @ccmode{} uses @code{c-comment-prefix-regexp} to adapt -the line prefix from the other lines in the comment. - -@vindex adaptive-fill-mode -@cindex Adaptive Fill mode -@ccmode{} uses adaptive fill mode (@pxref{Adaptive Fill,,, emacs, GNU -Emacs Manual}) to make Emacs correctly keep the line prefix when -filling paragraphs. That also makes Emacs preserve the text -indentation @emph{inside} the comment line prefix. E.g. in the -following comment, both paragraphs will be filled with the left -margins of the texts kept intact: - -@example -@group -/* Make a balanced b-tree of the nodes in the incoming - * stream. But, to quote the famous words of Donald E. - * Knuth, - * - * Beware of bugs in the above code; I have only - * proved it correct, not tried it. - */ -@end group -@end example - -@findex c-setup-filladapt -@findex setup-filladapt (c-) -@findex filladapt-mode -@vindex filladapt-mode -@cindex Filladapt mode -It's also possible to use other adaptive filling packages, notably Kyle -E. Jones' Filladapt package@footnote{It's available from -@uref{http://www.wonderworks.com/}. As of version 2.12, it does however -lack a feature that makes it work suboptimally when -@code{c-comment-prefix-regexp} matches the empty string (which it does -by default). A patch for that is available from -@uref{http://cc-mode.sourceforge.net/,, the CC Mode web site}.}, -@c 2005/11/22: The above is still believed to be the case. -which handles things like bulleted lists nicely. There's a convenience -function @code{c-setup-filladapt} that tunes the relevant variables in -Filladapt for use in @ccmode{}. Call it from a mode hook, e.g. with -something like this in your @file{.emacs}: - -@example -(defun my-c-mode-common-hook () - (c-setup-filladapt) - (filladapt-mode 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end example - -@defopt c-block-comment-prefix -@vindex block-comment-prefix (c-) -@vindex c-comment-continuation-stars -@vindex comment-continuation-stars (c-) -Normally the comment line prefix inserted for a new line inside a -comment is deduced from other lines in it. However there's one -situation when there's no hint about what the prefix should look like, -namely when a block comment is broken for the first time. This style -variable@footnote{In versions before 5.26, this variable was called -@code{c-comment-continuation-stars}. As a compatibility measure, -@ccmode{} still uses the value on that variable if it's set.} is used -then as the comment prefix. It defaults to @samp{* -}@footnote{Actually, this default setting of -@code{c-block-comment-prefix} typically gets overridden by the default -style @code{gnu}, which sets it to blank. You can see the line -splitting effect described here by setting a different style, -e.g. @code{k&r} @xref{Choosing a Style}.}, which makes a comment - -@example -/* Got O(n^2) here, which is a Bad Thing. */ -@end example - -@noindent -break into - -@example -@group -/* Got O(n^2) here, which - * is a Bad Thing. */ -@end group -@end example - -Note that it won't work to adjust the indentation by putting leading -spaces in @code{c-block-comment-prefix}, since @ccmode{} still uses the -normal indentation engine to indent the line. Thus, the right way to -fix the indentation is by customizing the @code{c} syntactic symbol. It -defaults to @code{c-lineup-C-comments}, which handles the indentation of -most common comment styles, see @ref{Line-Up Functions}. -@end defopt - -@defopt c-ignore-auto-fill -@vindex ignore-auto-fill (c-) -When auto fill mode is enabled, @ccmode{} can selectively ignore it -depending on the context the line break would occur in, e.g. to never -break a line automatically inside a string literal. This variable -takes a list of symbols for the different contexts where auto-filling -never should occur: - -@table @code -@item string -Inside a string or character literal. -@item c -Inside a C style block comment. -@item c++ -Inside a C++ style line comment. -@item cpp -Inside a preprocessor directive. -@item code -Anywhere else, i.e. in normal code. -@end table - -By default, @code{c-ignore-auto-fill} is set to @code{(string cpp -code)}, which means that when auto-fill mode is activated, -auto-filling only occurs in comments. In literals, it's often -desirable to have explicit control over newlines. In preprocessor -directives, the necessary @samp{\} escape character before the newline -is not automatically inserted, so an automatic line break would -produce invalid code. In normal code, line breaks are normally -dictated by some logical structure in the code rather than the last -whitespace character, so automatic line breaks there will produce poor -results in the current implementation. -@end defopt - -@vindex comment-multi-line -If inside a comment and @code{comment-multi-line} (@pxref{Auto Fill,,, -@emacsman{}, @emacsmantitle{}} is non-@code{nil}, the indentation and -line prefix are preserved. If inside a comment and -@code{comment-multi-line} is @code{nil}, a new comment of the same -type is started on the next line and indented as appropriate for -comments. - -Note that @ccmode{} sets @code{comment-multi-line} to @code{t} at -startup. The reason is that @kbd{M-j} could otherwise produce sequences -of single line block comments for texts that should logically be treated -as one comment, and the rest of the paragraph handling code -(e.g. @kbd{M-q} and @kbd{M-a}) can't cope with that, which would lead to -inconsistent behavior. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Auto-newlines, Clean-ups, Custom Filling and Breaking, Top -@comment node-name, next, previous, up -@chapter Customizing Auto-newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} determines whether to insert auto-newlines in two basically -different ways, depending on the character just typed: - -@table @asis -@item Braces and Colons -@ccmode{} first determines the syntactic context of the brace or colon -(@pxref{Syntactic Symbols}), then looks for a corresponding element in -an alist. This element specifies where to put newlines - this is any -combination of before and after the brace or colon. If no alist -element is found, newlines are inserted both before and after a brace, -but none are inserted around a colon. See @ref{Hanging Braces} and -@ref{Hanging Colons}. - -@item Semicolons and Commas -The variable @code{c-hanging-semi&comma-criteria} contains a list of -functions which determine whether to insert a newline after a newly -typed semicolon or comma. @xref{Hanging Semicolons and Commas}. -@end table - -The names of these configuration variables contain @samp{hanging} -because they let you @dfn{hang} the pertinent characters. A character -which introduces a C construct is said to @dfn{hang on the right} when -it appears at the end of a line after other code, being separated by a -line break from the construct it introduces, like the opening brace in: - -@example -@group -while (i < MAX) @{ - total += entry[i]; - entry [i++] = 0; -@} -@end group -@end example - -@noindent -A character @dfn{hangs on the left} when it appears at the start of -the line after the construct it closes off, like the above closing -brace. - -The next chapter, ``Clean-ups'', describes how to configure @ccmode{} -to remove these automatically added newlines in certain specific -circumstances. @xref{Clean-ups}. - -@menu -* Hanging Braces:: -* Hanging Colons:: -* Hanging Semicolons and Commas:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Braces, Hanging Colons, Custom Auto-newlines, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Braces -@cindex hanging braces -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -To specify which kinds of braces you want auto-newlines put around, -you set the style variable @code{c-hanging-braces-alist}. Its -structure and semantics are described in this section. Details of how -to set it up, and its relationship to CC Mode's style system are given -in @ref{Style Variables}. - -Say you wanted an auto-newline after (but not before) the following -@samp{@{}: - -@example -if (foo < 17) @{ -@end example - -@noindent -First you need to find the @dfn{syntactic context} of the brace---type -a @key{RET} before the brace to get it on a line of its -own@footnote{Also insert a @samp{\} at the end of the previous line if -you're in AWK Mode.}, then type @kbd{C-c C-s}. That will tell you -something like: - -@example -((substatement-open 1061)) -@end example - -@noindent -So here you need to put the entry @code{(substatement-open . (after))} -into @code{c-hanging-braces-alist}. - -If you don't want any auto-newlines for a particular syntactic symbol, -put this into @code{c-hanging-braces-alist}: - -@example -(brace-entry-open) -@end example - -If some brace syntactic symbol is not in @code{c-hanging-brace-alist}, -its entry is taken by default as @code{(before after)}---insert a -newline both before and after the brace. In place of a -``before/after'' list you can specify a function in this alist---this -is useful when the auto newlines depend on the code around the brace. - -@defopt c-hanging-braces-alist -@vindex hanging-braces-alist (c-) - -This variable is an association list which maps syntactic symbols to -lists of places to insert a newline. @xref{Association -Lists,,,@lispref{}, @lispreftitle{}}. The key of each element is the -syntactic symbol, the associated value is either @code{nil}, a list, -or a function. - -@table @asis -@item The Key - the syntactic symbol -The syntactic symbols that are useful as keys in this list are -@code{brace-list-intro}, @code{statement-cont}, -@code{inexpr-class-open}, @code{inexpr-class-close}, and all the -@code{*-open} and @code{*-close} symbols. @xref{Syntactic Symbols}, -for a more detailed description of these syntactic symbols, except for -@code{inexpr-class-open} and @code{inexpr-class-close}, which aren't -actual syntactic symbols. Elements with any other value as a key get -ignored. - -The braces of anonymous inner classes in Java are given the special -symbols @code{inexpr-class-open} and @code{inexpr-class-close}, so that -they can be distinguished from the braces of normal classes@footnote{The -braces of anonymous classes produce a combination of -@code{inexpr-class}, and @code{class-open} or @code{class-close} in -normal indentation analysis.}. - -Note that the aggregate constructs in Pike mode, @samp{(@{}, @samp{@})}, -@samp{([}, @samp{])}, and @samp{(<}, @samp{>)}, do not count as brace -lists in this regard, even though they do for normal indentation -purposes. It's currently not possible to set automatic newlines on -these constructs. - -@item The associated value - the ``ACTION'' list or function -The value associated with each syntactic symbol in this association -list is called an @var{action}, which can be either a list or a -function which returns a list. @xref{Custom Braces}, for how to use -a function as a brace hanging @var{action}. - -The list @var{action} (or the list returned by @var{action} when it's -a function) contains some combination of the symbols @code{before} and -@code{after}, directing @ccmode{} where to put newlines in -relationship to the brace being inserted. Thus, if the list contains -only the symbol @code{after}, then the brace hangs on the right side -of the line, as in: - -@example -// here, open braces always `hang' -void spam( int i ) @{ - if( i == 7 ) @{ - dosomething(i); - @} -@} -@end example - -When the list contains both @code{after} and @code{before}, the braces -will appear on a line by themselves, as shown by the close braces in -the above example. The list can also be empty, in which case newlines -are added neither before nor after the brace. -@end table - -If a syntactic symbol is missing entirely from -@code{c-hanging-braces-alist}, it's treated in the same way as an -@var{action} with a list containing @code{before} and @code{after}, so -that braces by default end up on their own line. - -For example, the default value of @code{c-hanging-braces-alist} is: - -@example -((brace-list-open) - (brace-entry-open) - (statement-cont) - (substatement-open after) - (block-close . c-snug-do-while) - (extern-lang-open after) - (namespace-open after) - (module-open after) - (composition-open after) - (inexpr-class-open after) - (inexpr-class-close before)) -@end example - -@noindent which says that @code{brace-list-open}, -@code{brace-entry-open} and @code{statement-cont}@footnote{Brace lists -inside statements, such as initializers for static array variables -inside functions in C, are recognized as @code{statement-cont}. All -normal substatement blocks are recognized with other symbols.} braces -should both hang on the right side and allow subsequent text to follow -on the same line as the brace. Also, @code{substatement-open}, -@code{extern-lang-open}, and @code{inexpr-class-open} braces should hang -on the right side, but subsequent text should follow on the next line. -The opposite holds for @code{inexpr-class-close} braces; they won't -hang, but the following text continues on the same line. Here, in the -@code{block-close} entry, you also see an example of using a function as -an @var{action}. In all other cases, braces are put on a line by -themselves. -@end defopt - -@menu -* Custom Braces:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Braces, , Hanging Braces, Hanging Braces -@comment node-name, next, previous, up -@subsection Custom Brace Hanging -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@vindex c-hanging-braces-alist -@vindex hanging-braces-alist (c-) -@cindex action functions -Syntactic symbols aren't the only place where you can customize -@ccmode{} with the lisp equivalent of callback functions. Remember -that @var{action}s are usually a list containing some combination of -the symbols @code{before} and @code{after} (@pxref{Hanging Braces}). -For more flexibility, you can instead specify brace ``hanginess'' by -giving a syntactic symbol an @dfn{action function} in -@code{c-hanging-braces-alist}; this function determines the -``hanginess'' of a brace, usually by looking at the code near it. - -@cindex customization, brace hanging -An action function is called with two arguments: the syntactic symbol -for the brace (e.g. @code{substatement-open}), and the buffer position -where the brace has been inserted. Point is undefined on entry to an -action function, but the function must preserve it (e.g. by using -@code{save-excursion}). The return value should be a list containing -some combination of @code{before} and @code{after}, including neither -of them (i.e. @code{nil}). - -@defvar c-syntactic-context -@vindex syntactic-context (c-) -During the call to the indentation or brace hanging @var{action} -function, this variable is bound to the full syntactic analysis list. -This might be, for example, @samp{((block-close 73))}. Don't ever -give @code{c-syntactic-context} a value yourself---this would disrupt -the proper functioning of @ccmode{}. - -This variable is also bound in three other circumstances: -(i)@w{ }when calling a c-hanging-semi&comma-criteria function -(@pxref{Hanging Semicolons and Commas}); (ii)@w{ }when calling a -line-up function (@pxref{Custom Line-Up}); (iii)@w{ }when calling a -c-special-indent-hook function (@pxref{Other Indentation}). -@end defvar - -As an example, @ccmode{} itself uses this feature to dynamically -determine the hanginess of braces which close ``do-while'' -constructs: - -@example -void do_list( int count, char** atleast_one_string ) -@{ - int i=0; - do @{ - handle_string( atleast_one_string[i] ); - i++; - @} while( i < count ); -@} -@end example - -@ccmode{} assigns the @code{block-close} syntactic symbol to the -brace that closes the @code{do} construct, and normally we'd like the -line that follows a @code{block-close} brace to begin on a separate -line. However, with ``do-while'' constructs, we want the -@code{while} clause to follow the closing brace. To do this, we -associate the @code{block-close} symbol with the @var{action} function -@code{c-snug-do-while}: - -@example -(defun c-snug-do-while (syntax pos) - "Dynamically calculate brace hanginess for do-while statements." - (save-excursion - (let (langelem) - (if (and (eq syntax 'block-close) - (setq langelem (assq 'block-close c-syntactic-context)) - (progn (goto-char (cdr langelem)) - (if (= (following-char) ?@{) - (forward-sexp -1)) - (looking-at "\\[^_]"))) - '(before) - '(before after))))) -@end example - -@findex c-snug-do-while -@findex snug-do-while (c-) -This function simply looks to see if the brace closes a ``do-while'' -clause and if so, returns the list @samp{(before)} indicating -that a newline should be inserted before the brace, but not after it. -In all other cases, it returns the list @samp{(before after)} so -that the brace appears on a line by itself. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Colons, Hanging Semicolons and Commas, Hanging Braces, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Colons -@cindex hanging colons -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex customization, colon hanging -@vindex c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -Using a mechanism similar to brace hanging (@pxref{Hanging Braces}), -colons can also be made to hang using the style variable -@code{c-hanging-colons-alist} - When a colon is typed, @ccmode -determines its syntactic context, looks this up in the alist -@code{c-changing-colons-alist} and inserts up to two newlines -accordingly. Here, however, If @ccmode fails to find an entry for a -syntactic symbol in the alist, no newlines are inserted around the -newly typed colon. - -@defopt c-hanging-colons-alist -@vindex hanging-colons-alist (c-) - -@table @asis -@item The Key - the syntactic symbol -The syntactic symbols appropriate as keys in this association list -are: @code{case-label}, @code{label}, @code{access-label}, -@code{member-init-intro}, and @code{inher-intro}. @xref{Syntactic -Symbols}. Elements with any other value as a key get ignored. - -@item The associate value - the ``ACTION'' list -The @var{action} here is simply a list containing a combination of the -symbols @code{before} and @code{after}. Unlike in -@code{c-hanging-braces-alist}, functions as @var{actions} are not -supported - there doesn't seem to be any need for them. -@end table -@end defopt - -In C++, double-colons are used as a scope operator but because these -colons always appear right next to each other, newlines before and after -them are controlled by a different mechanism, called @dfn{clean-ups} in -@ccmode{}. @xref{Clean-ups}, for details. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Hanging Semicolons and Commas, , Hanging Colons, Custom Auto-newlines -@comment node-name, next, previous, up -@section Hanging Semicolons and Commas -@cindex hanging semicolons -@cindex hanging commas -@cindex customization, semicolon newlines -@cindex customization, comma newlines -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@defopt c-hanging-semi&comma-criteria -@vindex hanging-semi&comma-criteria (c-) -This style variable takes a list of functions; these get called when -you type a semicolon or comma. The functions are called in order -without arguments. When these functions are entered, point is just -after the newly inserted @samp{;} or @samp{,} and they must preserve -point (e.g., by using @code{save-excursion}). During the call, the -variable @code{c-syntactic-context} is bound to the syntactic context -of the current line@footnote{This was first introduced in @ccmode{} -5.31.} @pxref{Custom Braces}. These functions don't insert newlines -themselves, rather they direct @ccmode{} whether or not to do so. -They should return one of the following values: - -@table @code -@item t -A newline is to be inserted after the @samp{;} or @samp{,}, and no -more functions from the list are to be called. -@item stop -No more functions from the list are to be called, and no newline is to -be inserted. -@item nil -No determination has been made, and the next function in the list is -to be called. -@end table - -Note that auto-newlines are never inserted @emph{before} a semicolon -or comma. If every function in the list is called without a -determination being made, then no newline is added. - -In AWK mode, this variable is set by default to @code{nil}. In the -other modes, the default value is a list containing a single function, -@code{c-semi&comma-inside-parenlist}. This inserts newlines after all -semicolons, apart from those separating @code{for}-clause statements. -@end defopt - -@defun c-semi&comma-no-newlines-before-nonblanks -@findex semi&comma-no-newlines-before-nonblanks (c-) -This is an example of a criteria function, provided by @ccmode{}. It -prevents newlines from being inserted after semicolons when there is a -non-blank following line. Otherwise, it makes no determination. To -use, add this function to the front of the -@code{c-hanging-semi&comma-criteria} list. - -@example -(defun c-semi&comma-no-newlines-before-nonblanks () - (save-excursion - (if (and (eq last-command-char ?\;) - (zerop (forward-line 1)) - (not (looking-at "^[ \t]*$"))) - 'stop - nil))) -@end example -@end defun - -@defun c-semi&comma-inside-parenlist -@findex semi&comma-inside-parenlist (c-) -@defunx c-semi&comma-no-newlines-for-oneline-inliners -@findex semi&comma-no-newlines-for-oneline-inliners (c-) -The function @code{c-semi&comma-inside-parenlist} is what prevents -newlines from being inserted inside the parenthesis list of @code{for} -statements. In addition to -@code{c-semi&comma-no-newlines-before-nonblanks} described above, -@ccmode{} also comes with the criteria function -@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses -newlines after semicolons inside one-line inline method definitions -(e.g. in C++ or Java). -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Clean-ups, Indentation Engine Basics, Custom Auto-newlines, Top -@comment node-name, next, previous, up -@chapter Clean-ups -@cindex clean-ups -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@dfn{Clean-ups} are mechanisms which remove (or exceptionally, add) -whitespace in specific circumstances and are complementary to colon -and brace hanging. You enable a clean-up by adding its symbol into -@code{c-cleanup-list}, e.g. like this: - -@example -(add-to-list 'c-cleanup-list 'space-before-funcall) -@end example - -On the surface, it would seem that clean-ups overlap the functionality -provided by the @code{c-hanging-*-alist} variables. Clean-ups, -however, are used to adjust code ``after-the-fact'', i.e. to adjust -the whitespace in constructs later than when they were typed. - -Most of the clean-ups remove automatically inserted newlines, and are -only active when auto-newline minor mode is turned on. Others will -work all the time. Note that clean-ups are only performed when there -is nothing but whitespace appearing between the individual components -of the construct, and (apart from @code{comment-close-slash}) when the -construct does not occur within a literal (@pxref{Auto-newlines}). - -@defopt c-cleanup-list -@vindex cleanup-list (c-) -@cindex literal - -You configure @ccmode{}'s clean-ups by setting the style variable -@code{c-cleanup-list}, which is a list of clean-up symbols. By -default, @ccmode{} cleans up only the @code{scope-operator} construct, -which is necessary for proper C++ support. -@end defopt - -These are the clean-ups that are only active when electric and -auto-newline minor modes are enabled: - -@c TBD: Would like to use some sort of @deffoo here; @table indents a -@c bit too much in dvi output. -@table @code -@item brace-else-brace -Clean up @samp{@} else @{} constructs by placing the entire construct on -a single line. Clean up occurs when the open brace after the -@samp{else} is typed. So for example, this: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else - @{ -@end group -@end example - -@noindent -appears like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else @{ -@end group -@end example - -@item brace-elseif-brace -Similar to the @code{brace-else-brace} clean-up, but this cleans up -@samp{@} else if (...) @{} constructs. For example: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} - else if( i==3 ) - @{ -@end group -@end example - -@noindent -appears like this after the last open parenthesis is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( -@end group -@end example - -@noindent -and like this after the last open brace is typed: - -@example -@group -void spam(int i) -@{ - if( i==7 ) @{ - dosomething(); - @} else if( i==3 ) @{ -@end group -@end example - -@item brace-catch-brace -Analogous to @code{brace-elseif-brace}, but cleans up @samp{@} catch -(...) @{} in C++ and Java mode. - -@item empty-defun-braces -Clean up braces following a top-level function or class definition that -contains no body. Clean up occurs when the closing brace is typed. -Thus the following: - -@example -@group -class Spam -@{ -@} -@end group -@end example - -@noindent -is transformed into this when the close brace is typed: - -@example -@group -class Spam -@{@} -@end group -@end example - -@item defun-close-semi -Clean up the terminating semicolon on top-level function or class -definitions when they follow a close brace. Clean up occurs when the -semicolon is typed. So for example, the following: - -@example -@group -class Spam -@{ -... -@} -; -@end group -@end example - -@noindent -is transformed into this when the semicolon is typed: - -@example -@group -class Spam -@{ -... -@}; -@end group -@end example - -@item list-close-comma -Clean up commas following braces in array and aggregate initializers. -Clean up occurs when the comma is typed. The space before the comma -is zapped just like the space before the semicolon in -@code{defun-close-semi}. - -@item scope-operator -Clean up double colons which might designate a C++ scope operator split -across multiple lines@footnote{Certain C++ constructs introduce -ambiguous situations, so @code{scope-operator} clean-ups might not -always be correct. This usually only occurs when scoped identifiers -appear in switch label tags.}. Clean up occurs when the second colon is -typed. You will always want @code{scope-operator} in the -@code{c-cleanup-list} when you are editing C++ code. - -@item one-liner-defun -Clean up a single line of code enclosed by defun braces by removing -the whitespace before and after the code. The clean-up happens when -the closing brace is typed. If the variable -@code{c-max-one-liner-length} is set, the cleanup is only done if the -resulting line would be no longer than the value of that variable. - -For example, consider this AWK code: - -@example -@group -BEGIN @{ - FS = "\t" # use as a field separator -@} -@end group -@end example - -@noindent -It gets compacted to the following when the closing brace is typed: - -@example -@group -BEGIN @{FS = "\t"@} # use as a field separator -@end group -@end example - -@defopt c-max-one-liner-length -@vindex max-one-liner-length (c-) -The maximum length of the resulting line for which the clean-up -@code{one-liner-defun} will be triggered. This length is that of the entire -line, including any leading whitespace and any trailing comment. Its -default value is 80. If the value is zero or @code{nil}, no limit -applies. -@end defopt -@end table - -The following clean-ups are always active when they occur on -@code{c-cleanup-list}, regardless of whether Electric minor mode or -Auto-newline minor mode are enabled: - -@table @code -@item space-before-funcall -Insert a space between the function name and the opening parenthesis -of a function call. This produces function calls in the style -mandated by the GNU coding standards, e.g. @samp{signal@w{ }(SIGINT, -SIG_IGN)} and @samp{abort@w{ }()}. Clean up occurs when the opening -parenthesis is typed. This clean-up should never be active in AWK -Mode, since such a space is syntactically invalid for user defined -functions. - -@item compact-empty-funcall -Clean up any space between the function name and the opening parenthesis -of a function call that has no arguments. This is typically used -together with @code{space-before-funcall} if you prefer the GNU function -call style for functions with arguments but think it looks ugly when -it's only an empty parenthesis pair. I.e. you will get @samp{signal -(SIGINT, SIG_IGN)}, but @samp{abort()}. Clean up occurs when the -closing parenthesis is typed. - -@item comment-close-slash -When inside a block comment, terminate the comment when you type a slash -at the beginning of a line (i.e. immediately after the comment prefix). -This clean-up removes whitespace preceding the slash and if needed, -inserts a star to complete the token @samp{*/}. Type @kbd{C-q /} in this -situation if you just want a literal @samp{/} inserted. -@end table - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Engine Basics, Customizing Indentation, Clean-ups, Top -@comment node-name, next, previous, up -@chapter Indentation Engine Basics -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This chapter will briefly cover how @ccmode{} indents lines of code. -It is helpful to understand the indentation model being used so that -you will know how to customize @ccmode{} for your personal coding -style. All the details are in @ref{Customizing Indentation}. - -@ccmode{} has an indentation engine that provides a flexible and -general mechanism for customizing indentation. When @ccmode{} indents -a line of code, it separates its calculations into two steps: - -@enumerate -@item -@cindex syntactic symbol -@cindex anchor position -It analyzes the line to determine its @dfn{syntactic symbol(s)} (the -kind of language construct it's looking at) and its @dfn{anchor -position} (the position earlier in the file that @ccmode{} will indent -the line relative to). The anchor position might be the location of -an opening brace in the previous line, for example. @xref{Syntactic -Analysis}. -@item -@cindex offsets -@cindex indentation offset specifications -It looks up the syntactic symbol(s) in the configuration to get the -corresponding @dfn{offset(s)}. The symbol @code{+}, which means -``indent this line one more level'' is a typical offset. @ccmode{} -then applies these offset(s) to the anchor position, giving the -indentation for the line. The different sorts of offsets are -described in @ref{c-offsets-alist}. -@end enumerate - -In exceptional circumstances, the syntax directed indentation -described here may be a nuisance rather than a help. You can disable -it by setting @code{c-syntactic-indentation} to @code{nil}. (To set -the variable interactively, @ref{Minor Modes}). - -@defopt c-syntactic-indentation -@vindex syntactic-indentation (c-) -When this is non-@code{nil} (which it is by default), the indentation -of code is done according to its syntactic structure. When it's -@code{nil}, every line is just indented to the same level as the -previous one, and @kbd{TAB} (@code{c-indent-command}) adjusts the -indentation in steps of @code{c-basic-offset}. The current style -(@pxref{Config Basics}) then has no effect on indentation, nor do any -of the variables associated with indentation, not even -@code{c-special-indent-hook}. -@end defopt - -@menu -* Syntactic Analysis:: -* Syntactic Symbols:: -* Indentation Calculation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Analysis, Syntactic Symbols, Indentation Engine Basics, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Analysis -@cindex syntactic analysis -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic element -@cindex syntactic context -The first thing @ccmode{} does when indenting a line of code, is to -analyze the line, determining the @dfn{syntactic context} of the -(first) construct on that line. It's a list of @dfn{syntactic -elements}, where each syntactic element in turn is a list@footnote{In -@ccmode 5.28 and earlier, a syntactic element was a dotted pair; the -cons was the syntactic symbol and the cdr was the anchor position. -For compatibility's sake, the parameter passed to a line-up function -still has this dotted pair form (@pxref{Custom Line-Up}).} Here is a -brief and typical example: - -@example -((defun-block-intro 1959)) -@end example - -@cindex syntactic symbol -@noindent -The first thing inside each syntactic element is always a -@dfn{syntactic symbol}. It describes the kind of construct that was -recognized, e.g. @code{statement}, @code{substatement}, -@code{class-open}, @code{class-close}, etc. @xref{Syntactic Symbols}, -for a complete list of currently recognized syntactic symbols and -their semantics. The remaining entries are various data associated -with the recognized construct - there might be zero or more. - -@cindex anchor position -Conceptually, a line of code is always indented relative to some -position higher up in the buffer (typically the indentation of the -previous line). That position is the @dfn{anchor position} in the -syntactic element. If there is an entry after the syntactic symbol in -the syntactic element list then it's either nil or that anchor position. - -Here is an example. Suppose we had the following code as the only thing -in a C++ buffer @footnote{The line numbers in this and future examples -don't actually appear in the buffer, of course!}: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -@noindent -We can use @kbd{C-c C-s} (@code{c-show-syntactic-information}) to -report what the syntactic analysis is for the current line: - -@table @asis -@item @kbd{C-c C-s} (@code{c-show-syntactic-information}) -@kindex C-c C-s -@findex c-show-syntactic-information -@findex show-syntactic-information (c-) -This command calculates the syntactic analysis of the current line and -displays it in the minibuffer. The command also highlights the anchor -position(s). -@end table - - Running this command on line 4 of this example, we'd see in the echo -area@footnote{With a universal argument (i.e. @kbd{C-u C-c C-s}) the -analysis is inserted into the buffer as a comment on the current -line.}: - -@example -((statement 35)) -@end example - -@noindent -and the @samp{i} of @code{int} on line 3 would be highlighted. This -tells us that the line is a statement and it is indented relative to -buffer position 35, the highlighted position. If you were to move -point to line 3 and hit @kbd{C-c C-s}, you would see: - -@example -((defun-block-intro 29)) -@end example - -@noindent -This indicates that the @samp{int} line is the first statement in a top -level function block, and is indented relative to buffer position 29, -which is the brace just after the function header. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 4 gives us: - -@example -((substatement-open 46)) -@end example - -@cindex substatement -@cindex substatement block -@noindent -which tells us that this is a brace that @emph{opens} a substatement -block. @footnote{A @dfn{substatement} is the line after a -conditional statement, such as @code{if}, @code{else}, @code{while}, -@code{do}, @code{switch}, etc. A @dfn{substatement -block} is a brace block following one of these conditional statements.} - -@cindex comment-only line -Syntactic contexts can contain more than one element, and syntactic -elements need not have anchor positions. The most common example of -this is a @dfn{comment-only line}: - -@example - 1: void draw_list( List& drawables ) - 2: @{ - 3: // call the virtual draw() method on each element in list - 4: for( int i=0; i < drawables.count(), ++i ) - 5: @{ - 6: drawables[i].draw(); - 7: @} - 8: @} -@end example - -@noindent -Hitting @kbd{C-c C-s} on line 3 of this example gives: - -@example -((comment-intro) (defun-block-intro 46)) -@end example - -@noindent -and you can see that the syntactic context contains two syntactic -elements. Notice that the first element, @samp{(comment-intro)}, has no -anchor position. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Syntactic Symbols, Indentation Calculation, Syntactic Analysis, Indentation Engine Basics -@comment node-name, next, previous, up -@section Syntactic Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex syntactic symbols, brief list -@vindex c-offsets-alist -@vindex offsets-alist (c-) -This section is a complete list of the syntactic symbols which appear -in the @code{c-offsets-alist} style variable, along with brief -descriptions. The previous section (@pxref{Syntactic Analysis}) -states what syntactic symbols are and how the indentation engine uses -them. - -More detailed descriptions of these symbols, together with snippets of -source code to which they apply, appear in the examples in the -subsections below. Note that, in the interests of brevity, the anchor -position associated with most syntactic symbols is @emph{not} -specified. In cases of doubt, type @kbd{C-c C-s} on a pertinent -line---this highlights the anchor position. - -@ssindex -open symbols -@ssindex -close symbols -@ssindex -block-intro symbols -The syntactic symbols which indicate brace constructs follow a general -naming convention. When a line begins with an open or close brace, -its syntactic symbol will contain the suffix @code{-open} or -@code{-close} respectively. The first line within the brace block -construct will contain the suffix @code{-block-intro}. - -@ssindex -intro symbols -@ssindex -cont symbols -In constructs which can span several lines, a distinction is usually -made between the first line that introduces the construct and the -lines that continue it. The syntactic symbols that indicate these -lines will contain the suffixes @code{-intro} or @code{-cont} -respectively. - -The best way to understand how all this works is by looking at some -examples. Remember that you can see the syntax of any source code -line by using @kbd{C-c C-s}. - -@table @code -@item string -Inside a multiline string. @ref{Literal Symbols}. -@item c -Inside a multiline C style block comment. @ref{Literal Symbols}. -@item defun-open -Brace that opens a top-level function definition. @ref{Function -Symbols}. -@item defun-close -Brace that closes a top-level function definition. @ref{Function -Symbols}. -@item defun-block-intro -The first line in a top-level defun. @ref{Function Symbols}. -@item class-open -Brace that opens a class definition. @ref{Class Symbols}. -@item class-close -Brace that closes a class definition. @ref{Class Symbols}. -@item inline-open -Brace that opens an in-class inline method. @ref{Class Symbols}. -@item inline-close -Brace that closes an in-class inline method. @ref{Class Symbols}. -@item func-decl-cont -The region between a function definition's argument list and the -function opening brace (excluding K&R argument declarations). In C, -you cannot put anything but whitespace and comments in this region, -however in C++ and Java, @code{throws} declarations and other things -can appear here. @ref{Literal Symbols}. @c @emph{FIXME!!! Can it not -@c go somewhere better?} -@item knr-argdecl-intro -First line of a K&R C argument declaration. @ref{K&R Symbols}. -@item knr-argdecl -Subsequent lines in a K&R C argument declaration. @ref{K&R Symbols}. -@item topmost-intro -The first line in a ``topmost'' definition. @ref{Function Symbols}. -@item topmost-intro-cont -Topmost definition continuation lines. This is only used in the parts -that aren't covered by other symbols such as @code{func-decl-cont} and -@code{knr-argdecl}. @ref{Function Symbols}. -@item member-init-intro -First line in a member initialization list. @ref{Class Symbols}. -@item member-init-cont -Subsequent member initialization list lines. @ref{Class Symbols}. -@item inher-intro -First line of a multiple inheritance list. @ref{Class Symbols}. -@item inher-cont -Subsequent multiple inheritance lines. @ref{Class Symbols}. -@item block-open -Statement block open brace. @ref{Literal Symbols}. -@item block-close -Statement block close brace. @ref{Conditional Construct Symbols}. -@item brace-list-open -Open brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-close -Close brace of an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-intro -First line in an enum or static array list. @ref{Brace List Symbols}. -@item brace-list-entry -Subsequent lines in an enum or static array list. @ref{Brace List -Symbols}. -@item brace-entry-open -Subsequent lines in an enum or static array list where the line begins -with an open brace. @ref{Brace List Symbols}. -@item statement -A statement. @ref{Function Symbols}. -@item statement-cont -A continuation of a statement. @ref{Function Symbols}. -@item statement-block-intro -The first line in a new statement block. @ref{Conditional Construct -Symbols}. -@item statement-case-intro -The first line in a case block. @ref{Switch Statement Symbols}. -@item statement-case-open -The first line in a case block that starts with a brace. @ref{Switch -Statement Symbols}. -@item substatement -The first line after a conditional or loop construct. -@ref{Conditional Construct Symbols}. -@item substatement-open -The brace that opens a substatement block. @ref{Conditional Construct -Symbols}. -@item substatement-label -The first line after a conditional or loop construct if it's a label. -@ref{Conditional Construct Symbols}. -@item case-label -A label in a @code{switch} block. @ref{Switch Statement Symbols}. -@item access-label -C++ access control label. @ref{Class Symbols}. -@item label -Any other label. @ref{Literal Symbols}. -@item do-while-closure -The @code{while} line that ends a @code{do}-@code{while} construct. -@ref{Conditional Construct Symbols}. -@item else-clause -The @code{else} line of an @code{if}-@code{else} construct. -@ref{Conditional Construct Symbols}. -@item catch-clause -The @code{catch} or @code{finally} (in Java) line of a -@code{try}-@code{catch} construct. @ref{Conditional Construct -Symbols}. -@item comment-intro -A line containing only a comment introduction. @ref{Literal Symbols}. -@item arglist-intro -The first line in an argument list. @ref{Paren List Symbols}. -@item arglist-cont -Subsequent argument list lines when no arguments follow on the same -line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-cont-nonempty -Subsequent argument list lines when at least one argument follows on -the same line as the arglist opening paren. @ref{Paren List Symbols}. -@item arglist-close -The solo close paren of an argument list. @ref{Paren List Symbols}. -@item stream-op -Lines continuing a stream operator (C++ only). @ref{Literal -Symbols}. @c @emph{FIXME!!! Can this not be moved somewhere better?} -@item inclass -The line is nested inside a class definition. @ref{Class Symbols}. -@item cpp-macro -The start of a preprocessor macro definition. @ref{Literal Symbols}. -@item cpp-define-intro -The first line inside a multiline preprocessor macro if -@code{c-syntactic-indentation-in-macros} is set. @ref{Multiline Macro -Symbols}. -@item cpp-macro-cont -All lines inside multiline preprocessor macros if -@code{c-syntactic-indentation-in-macros} is @code{nil}. -@ref{Multiline Macro Symbols}. -@item friend -A C++ friend declaration. @ref{Class Symbols}. -@item objc-method-intro -The first line of an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-args-cont -Lines continuing an Objective-C method definition. @ref{Objective-C -Method Symbols}. -@item objc-method-call-cont -Lines continuing an Objective-C method call. @ref{Objective-C Method -Symbols}. -@item extern-lang-open -Brace that opens an @code{extern} block (e.g. @code{extern "C" -@{...@}}). @ref{External Scope Symbols}. -@item extern-lang-close -Brace that closes an @code{extern} block. @ref{External Scope -Symbols}. -@item inextern-lang -Analogous to @code{inclass} syntactic symbol, but used inside -@code{extern} blocks. @ref{External Scope Symbols}. -@item namespace-open -@itemx namespace-close -@itemx innamespace -These are analogous to the three @code{extern-lang} symbols above, but -are returned for C++ namespace blocks. @ref{External Scope Symbols}. -@item module-open -@itemx module-close -@itemx inmodule -Analogous to the above, but for CORBA IDL @code{module} blocks. -@ref{External Scope Symbols}. -@item composition-open -@itemx composition-close -@itemx incomposition -Analogous to the above, but for CORBA CIDL @code{composition} blocks. -@ref{External Scope Symbols}. -@item template-args-cont -C++ template argument list continuations. @ref{Class Symbols}. -@item inlambda -Analogous to @code{inclass} syntactic symbol, but used inside lambda -(i.e. anonymous) functions. Only used in Pike mode. @ref{Statement -Block Symbols}. -@item lambda-intro-cont -Lines continuing the header of a lambda function, i.e. between the -@code{lambda} keyword and the function body. Only used in Pike mode. -@ref{Statement Block Symbols}. -@item inexpr-statement -A statement block inside an expression. The gcc C and C++ extension -for this is recognized. It's also used for the special functions that -take a statement block as an argument in Pike. @ref{Statement Block -Symbols}. -@item inexpr-class -A class definition inside an expression. This is used for anonymous -classes in Java. It's also used for anonymous array initializers in -Java. @ref{Anonymous Class Symbol}. -@end table - -@menu -* Function Symbols:: -* Class Symbols:: -* Conditional Construct Symbols:: -* Switch Statement Symbols:: -* Brace List Symbols:: -* External Scope Symbols:: -* Paren List Symbols:: -* Literal Symbols:: -* Multiline Macro Symbols:: -* Objective-C Method Symbols:: -* Anonymous Class Symbol:: -* Statement Block Symbols:: -* K&R Symbols:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Function Symbols, Class Symbols, Syntactic Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Function Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This example shows a typical function declaration. - -@example - 1: void - 2: swap( int& a, int& b ) - 3: @{ - 4: int tmp = a; - 5: a = b; - 6: b = tmp; - 7: int ignored = - 8: a + b; - 9: @} -@end example - -@ssindex topmost-intro -@ssindex topmost-intro-cont -@ssindex defun-open -@ssindex defun-close -@ssindex defun-block-intro -Line 1 shows a @code{topmost-intro} since it is the first line that -introduces a top-level construct. Line 2 is a continuation of the -top-level construct introduction so it has the syntax -@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is -the brace that opens a top-level function definition. Line 9 is the -corresponding -@code{defun-close} since it contains the brace that closes the top-level -function definition. Line 4 is a @code{defun-block-intro}, i.e. it is -the first line of a brace-block, enclosed in a -top-level function definition. - -@ssindex statement -@ssindex statement-cont -Lines 5, 6, and 7 are all given @code{statement} syntax since there -isn't much special about them. Note however that line 8 is given -@code{statement-cont} syntax since it continues the statement begun -on the previous line. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Class Symbols, Conditional Construct Symbols, Function Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Class related Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's an example which illustrates some C++ class syntactic symbols: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass() - 7: : eString( new BassString( 0.105 )), - 8: aString( new BassString( 0.085 )), - 9: dString( new BassString( 0.065 )), -10: gString( new BassString( 0.045 )) -11: @{ -12: eString.tune( 'E' ); -13: aString.tune( 'A' ); -14: dString.tune( 'D' ); -15: gString.tune( 'G' ); -16: @} -17: friend class Luthier; -18: @}; -@end example - -@ssindex class-open -@ssindex class-close -As in the previous example, line 1 has the @code{topmost-intro} syntax. -Here however, the brace that opens a C++ class definition on line 4 is -assigned the @code{class-open} syntax. Note that in C++, classes, -structs, and unions are essentially equivalent syntactically (and are -very similar semantically), so replacing the @code{class} keyword in the -example above with @code{struct} or @code{union} would still result in a -syntax of @code{class-open} for line 4 @footnote{This is the case even -for C and Objective-C. For consistency, structs in all supported -languages are syntactically equivalent to classes. Note however that -the keyword @code{class} is meaningless in C and Objective-C.}. -Similarly, line 18 is assigned @code{class-close} syntax. - -@ssindex inher-intro -@ssindex inher-cont -Line 2 introduces the inheritance list for the class so it is assigned -the @code{inher-intro} syntax, and line 3, which continues the -inheritance list is given @code{inher-cont} syntax. - -@ssindex access-label -@ssindex inclass -Hitting @kbd{C-c C-s} on line 5 shows the following analysis: - -@example -((inclass 58) (access-label 58)) -@end example - -@noindent -The primary syntactic symbol for this line is @code{access-label} as -this a label keyword that specifies access protection in C++. However, -because this line is also a top-level construct inside a class -definition, the analysis actually shows two syntactic symbols. The -other syntactic symbol assigned to this line is @code{inclass}. -Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} -syntax: - -@example -((inclass 58) (topmost-intro 60)) -@end example - -@ssindex member-init-intro -@ssindex member-init-cont -Line 7 introduces a C++ member initialization list and as such is given -@code{member-init-intro} syntax. Note that in this case it is -@emph{not} assigned @code{inclass} since this is not considered a -top-level construct. Lines 8 through 10 are all assigned -@code{member-init-cont} since they continue the member initialization -list started on line 7. - -@cindex in-class inline methods -@ssindex inline-open -@ssindex inline-close -Line 11's analysis is a bit more complicated: - -@example -((inclass 58) (inline-open)) -@end example - -This line is assigned a syntax of both @code{inline-open} and -@code{inclass} because it opens an @dfn{in-class} C++ inline method -definition. This is distinct from, but related to, the C++ notion of an -inline function in that its definition occurs inside an enclosing class -definition, which in C++ implies that the function should be inlined. -However, if the definition of the @code{Bass} constructor appeared -outside the class definition, the construct would be given the -@code{defun-open} syntax, even if the keyword @code{inline} appeared -before the method name, as in: - -@example - 1: class Bass - 2: : public Guitar, - 3: public Amplifiable - 4: @{ - 5: public: - 6: Bass(); - 7: @}; - 8: - 9: inline -10: Bass::Bass() -11: : eString( new BassString( 0.105 )), -12: aString( new BassString( 0.085 )), -13: dString( new BassString( 0.065 )), -14: gString( new BassString( 0.045 )) -15: @{ -16: eString.tune( 'E' ); -17: aString.tune( 'A' ); -18: dString.tune( 'D' ); -19: gString.tune( 'G' ); -20: @} -@end example - -@ssindex friend -Returning to the previous example, line 16 is given @code{inline-close} -syntax, while line 12 is given @code{defun-block-open} syntax, and lines -13 through 15 are all given @code{statement} syntax. Line 17 is -interesting in that its syntactic analysis list contains three -elements: - -@example -((inclass 58) (topmost-intro 380) (friend)) -@end example - -The @code{friend} and @code{inline-open} syntactic symbols are -modifiers that do not have anchor positions. - -@ssindex template-args-cont -Template definitions introduce yet another syntactic symbol: - -@example - 1: ThingManager framework_callbacks; -@end example - -Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 -are both analyzed as @code{template-args-cont} lines. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Conditional Construct Symbols, Switch Statement Symbols, Class Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Conditional Construct Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here is a (totally contrived) example which illustrates how syntax is -assigned to various conditional constructs: - -@example - 1: void spam( int index ) - 2: @{ - 3: for( int i=0; i 0 ); -15: @} -@end example - -Only the lines that illustrate new syntactic symbols will be discussed. - -@ssindex substatement-open -@ssindex statement-block-intro -@ssindex block-close -Line 4 has a brace which opens a conditional's substatement block. It -is thus assigned @code{substatement-open} syntax, and since line 5 is -the first line in the substatement block, it is assigned -@code{statement-block-intro} syntax. Line 10 contains the brace -that closes the inner substatement block, and is therefore given the -syntax @code{block-close}@footnote{@code{block-open} is used only for -``free-standing'' blocks, and is somewhat rare (@pxref{Literal -Symbols} for an example.)}. Line 13 is treated the same way. - -@ssindex substatement -Lines 6 and 9 are also substatements of conditionals, but since they -don't start blocks they are given @code{substatement} syntax -instead of @code{substatement-open}. - -@ssindex substatement-label -Line 8 contains a label, which is normally given @code{label} syntax. -This one is however a bit special since it's between a conditional and -its substatement. It's analyzed as @code{substatement-label} to let you -handle this rather odd case differently from normal labels. - -@ssindex else-clause -@ssindex catch-clause -Line 7 start with an @code{else} that matches the @code{if} statement on -line 5. It is therefore given the @code{else-clause} syntax and is -anchored on the matching @code{if}. The @code{try}-@code{catch} -constructs in C++ and Java are treated this way too, except that -@code{catch} and (in Java) @code{finally}, are marked with -@code{catch-clause}. - -@ssindex do-while-closure -The @code{while} construct on line 14 that closes a @code{do} -conditional is given the special syntax @code{do-while-closure} if it -appears on a line by itself. Note that if the @code{while} appeared on -the same line as the preceding close brace, that line would still have -@code{block-close} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Switch Statement Symbols, Brace List Symbols, Conditional Construct Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Switch Statement Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Switch statements have their own set of syntactic symbols. Here's an -example: - -@example - 1: void spam( enum Ingredient i ) - 2: @{ - 3: switch( i ) @{ - 4: case Ham: - 5: be_a_pig(); - 6: break; - 7: case Salt: - 8: drink_some_water(); - 9: break; -10: default: -11: @{ -12: what_is_it(); -13: break; -14: @} -15: @} -14: @} -@end example - -@ssindex case-label -@ssindex statement-case-intro -@ssindex statement-case-open -Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, -while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 -is treated slightly differently since it contains a brace that opens a -block --- it is given @code{statement-case-open} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace List Symbols, External Scope Symbols, Switch Statement Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Brace List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex brace lists -There are a set of syntactic symbols that are used to recognize -constructs inside of brace lists. A brace list is defined as an -@code{enum} or aggregate initializer list, such as might statically -initialize an array of structs. The three special aggregate constructs -in Pike, @code{(@{ @})}, @code{([ ])} and @code{(< >)}, are treated as -brace lists too. An example: - -@example - 1: static char* ingredients[] = - 2: @{ - 3: "Ham", - 4: "Salt", - 5: NULL - 6: @}; -@end example - -@ssindex brace-list-open -@ssindex brace-list-intro -@ssindex brace-list-close -@ssindex brace-list-entry -Following convention, line 2 in this example is assigned -@code{brace-list-open} syntax, and line 3 is assigned -@code{brace-list-intro} syntax. Likewise, line 6 is assigned -@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned -@code{brace-list-entry} syntax, as would all subsequent lines in this -initializer list. - -@ssindex brace-entry-open -Your static initializer might be initializing nested structures, for -example: - -@example - 1: struct intpairs[] = - 2: @{ - 3: @{ 1, 2 @}, - 4: @{ - 5: 3, - 6: 4 - 7: @} - 8: @{ 1, - 9: 2 @}, -10: @{ 3, 4 @} -11: @}; -@end example - -Here, you've already seen the analysis of lines 1, 2, 3, and 11. On -line 4, things get interesting; this line is assigned -@code{brace-entry-open} syntactic symbol because it's a bracelist entry -line that starts with an open brace. Lines 5 and 6 (and line 9) are -pretty standard, and line 7 is a @code{brace-list-close} as you'd -expect. Once again, line 8 is assigned as @code{brace-entry-open} as is -line 10. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node External Scope Symbols, Paren List Symbols, Brace List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection External Scope Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -External language definition blocks also have their own syntactic -symbols. In this example: - -@example - 1: extern "C" - 2: @{ - 3: int thing_one( int ); - 4: int thing_two( double ); - 5: @} -@end example - -@ssindex extern-lang-open -@ssindex extern-lang-close -@ssindex inextern-lang -@ssindex inclass -@noindent -line 2 is given the @code{extern-lang-open} syntax, while line 5 is given -the @code{extern-lang-close} syntax. The analysis for line 3 yields: - -@example -((inextern-lang) (topmost-intro 14)) -@end example - -@noindent -where @code{inextern-lang} is a modifier similar in purpose to -@code{inclass}. - -There are various other top level blocks like @code{extern}, and they -are all treated in the same way except that the symbols are named after -the keyword that introduces the block. E.g. C++ namespace blocks get -the three symbols @code{namespace-open}, @code{namespace-close} and -@code{innamespace}. The currently recognized top level blocks are: - -@table @asis -@item @code{extern-lang-open}, @code{extern-lang-close}, @code{inextern-lang} -@code{extern} blocks in C and C++.@footnote{These should logically be -named @code{extern-open}, @code{extern-close} and @code{inextern}, but -that isn't the case for historical reasons.} - -@item @code{namespace-open}, @code{namespace-close}, @code{innamespace} -@ssindex namespace-open -@ssindex namespace-close -@ssindex innamespace -@code{namespace} blocks in C++. - -@item @code{module-open}, @code{module-close}, @code{inmodule} -@ssindex module-open -@ssindex module-close -@ssindex inmodule -@code{module} blocks in CORBA IDL. - -@item @code{composition-open}, @code{composition-close}, @code{incomposition} -@ssindex composition-open -@ssindex composition-close -@ssindex incomposition -@code{composition} blocks in CORBA CIDL. -@end table - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Paren List Symbols, Literal Symbols, External Scope Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Parenthesis (Argument) List Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A number of syntactic symbols are associated with parenthesis lists, -a.k.a argument lists, as found in function declarations and function -calls. This example illustrates these: - -@example - 1: void a_function( int line1, - 2: int line2 ); - 3: - 4: void a_longer_function( - 5: int line1, - 6: int line2 - 7: ); - 8: - 9: void call_them( int line1, int line2 ) -10: @{ -11: a_function( -12: line1, -13: line2 -14: ); -15: -16: a_longer_function( line1, -17: line2 ); -18: @} -@end example - -@ssindex arglist-intro -@ssindex arglist-close -Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are -the first line following the open parenthesis, and lines 7 and 14 are -assigned @code{arglist-close} syntax since they contain the parenthesis -that closes the argument list. - -@ssindex arglist-cont-nonempty -@ssindex arglist-cont -Lines that continue argument lists can be assigned one of two syntactic -symbols. For example, Lines 2 and 17 -are assigned @code{arglist-cont-nonempty} syntax. What this means -is that they continue an argument list, but that the line containing the -parenthesis that opens the list is @emph{not empty} following the open -parenthesis. Contrast this against lines 6 and 13 which are assigned -@code{arglist-cont} syntax. This is because the parenthesis that opens -their argument lists is the last character on that line. - -Syntactic elements with @code{arglist-intro}, -@code{arglist-cont-nonempty}, and @code{arglist-close} contain two -buffer positions: the anchor position (the beginning of the -declaration or statement) and the position of the open parenthesis. -The latter position can be used in a line-up function (@pxref{Line-Up -Functions}). - -Note that there is no @code{arglist-open} syntax. This is because any -parenthesis that opens an argument list, appearing on a separate line, -is assigned the @code{statement-cont} syntax instead. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Literal Symbols, Multiline Macro Symbols, Paren List Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Comment String Label and Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -A few miscellaneous syntactic symbols that haven't been previously -covered are illustrated by this C++ example: - -@example - 1: void Bass::play( int volume ) - 2: const - 3: @{ - 4: /* this line starts a multiline - 5: * comment. This line should get `c' syntax */ - 6: - 7: char* a_multiline_string = "This line starts a multiline \ - 8: string. This line should get `string' syntax."; - 9: -10: note: -11: @{ -12: #ifdef LOCK -13: Lock acquire(); -14: #endif // LOCK -15: slap_pop(); -16: cout << "I played " -17: << "a note\n"; -18: @} -19: @} -@end example - -The lines to note in this example include: - -@itemize @bullet -@item -@ssindex func-decl-cont -Line 2 is assigned the @code{func-decl-cont} syntax. - -@item -@ssindex comment-intro -Line 4 is assigned both @code{defun-block-intro} @emph{and} -@code{comment-intro} syntax. A syntactic element with -@code{comment-intro} has no anchor point --- It is always accompanied -by another syntactic element which does have one. - -@item -@ssindex c -Line 5 is assigned @code{c} syntax. - -@item -@cindex syntactic whitespace -Line 6 which, even though it contains nothing but whitespace, is -assigned @code{defun-block-intro}. Note that the appearance of the -comment on lines 4 and 5 do not cause line 6 to be assigned -@code{statement} syntax because comments are considered to be -@dfn{syntactic whitespace}, which are ignored when analyzing -code. - -@item -@ssindex string -Line 8 is assigned @code{string} syntax. - -@item -@ssindex label -Line 10 is assigned @code{label} syntax. - -@item -@ssindex block-open -Line 11 is assigned @code{block-open} as well as @code{statement} -syntax. A @code{block-open} syntactic element doesn't have an anchor -position, since it always appears with another syntactic element which -does have one. - -@item -@ssindex cpp-macro -Lines 12 and 14 are assigned @code{cpp-macro} syntax in addition to the -normal syntactic symbols (@code{statement-block-intro} and -@code{statement}, respectively). Normally @code{cpp-macro} is -configured to cancel out the normal syntactic context to make all -preprocessor directives stick to the first column, but that's easily -changed if you want preprocessor directives to be indented like the rest -of the code. Like @code{comment-intro}, a syntactic element with -@code{cpp-macro} doesn't contain an anchor position. - -@item -@ssindex stream-op -Line 17 is assigned @code{stream-op} syntax. -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Multiline Macro Symbols, Objective-C Method Symbols, Literal Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Multiline Macro Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex multiline macros -@cindex syntactic whitespace -@ssindex cpp-define-intro -@ssindex cpp-macro-cont -Multiline preprocessor macro definitions are normally handled just like -other code, i.e. the lines inside them are indented according to the -syntactic analysis of the preceding lines inside the macro. The first -line inside a macro definition (i.e. the line after the starting line of -the cpp directive itself) gets @code{cpp-define-intro}. In this example: - -@example - 1: #define LIST_LOOP(cons, listp) \ - 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ - 3: if (!CONSP (cons)) \ - 4: signal_error ("Invalid list format", listp); \ - 5: else -@end example - -@noindent -line 1 is given the syntactic symbol @code{cpp-macro}. The first line -of a cpp directive is always given that symbol. Line 2 is given -@code{cpp-define-intro}, so that you can give the macro body as a whole -some extra indentation. Lines 3 through 5 are then analyzed as normal -code, i.e. @code{substatement} on lines 3 and 4, and @code{else-clause} -on line 5. - -The syntactic analysis inside macros can be turned off with -@code{c-syntactic-indentation-in-macros} (@pxref{Custom Macros}). In -that case, lines 2 through 5 would all be given @code{cpp-macro-cont} -with an anchor position pointing to the @code{#} which starts the cpp -directive@footnote{This is how @ccmode{} 5.28 and earlier analyzed -macros.}. - -@xref{Custom Macros}, for more info about the treatment of macros. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Objective-C Method Symbols, Anonymous Class Symbol, Multiline Macro Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Objective-C Method Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -In Objective-C buffers, there are three additional syntactic symbols -assigned to various message calling constructs. Here's an example -illustrating these: - -@example - 1: - (void)setDelegate:anObject - 2: withStuff:stuff - 3: @{ - 4: [delegate masterWillRebind:self - 5: toDelegate:anObject - 6: withExtraStuff:stuff]; - 7: @} -@end example - -@ssindex objc-method-intro -@ssindex objc-method-args-cont -@ssindex objc-method-call-cont -Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is -assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both -assigned @code{objc-method-call-cont} syntax. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Anonymous Class Symbol, Statement Block Symbols, Objective-C Method Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Anonymous Class Symbol (Java) -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Java has a concept of anonymous classes which can look something like -this: - -@example - 1: public void watch(Observable o) @{ - 2: o.addObserver(new Observer() @{ - 3: public void update(Observable o, Object arg) @{ - 4: history.addElement(arg); - 5: @} - 6: @}); - 7: @} -@end example - -@ssindex inexpr-class -The brace following the @code{new} operator opens the anonymous class. -Lines 3 and 6 are assigned the @code{inexpr-class} syntax, besides the -@code{inclass} symbol used in normal classes. Thus, the class will be -indented just like a normal class, with the added indentation given to -@code{inexpr-class}. An @code{inexpr-class} syntactic element doesn't -have an anchor position. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Statement Block Symbols, K&R Symbols, Anonymous Class Symbol, Syntactic Symbols -@comment node-name, next, previous, up -@subsection Statement Block Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -There are a few occasions where a statement block might be used inside -an expression. One is in C or C++ code using the gcc extension for -this, e.g: - -@example - 1: int res = (@{ - 2: int y = foo (); int z; - 3: if (y > 0) z = y; else z = - y; - 4: z; - 5: @}); -@end example - -@ssindex inexpr-statement -Lines 2 and 5 get the @code{inexpr-statement} syntax, besides the -symbols they'd get in a normal block. Therefore, the indentation put on -@code{inexpr-statement} is added to the normal statement block -indentation. An @code{inexpr-statement} syntactic element doesn't -contain an anchor position. - -In Pike code, there are a few other situations where blocks occur inside -statements, as illustrated here: - -@example - 1: array itgob() - 2: @{ - 3: string s = map (backtrace()[-2][3..], - 4: lambda - 5: (mixed arg) - 6: @{ - 7: return sprintf ("%t", arg); - 8: @}) * ", " + "\n"; - 9: return catch @{ -10: write (s + "\n"); -11: @}; -12: @} -@end example - -@ssindex inlambda -@ssindex lambda-intro-cont -Lines 4 through 8 contain a lambda function, which @ccmode{} recognizes -by the @code{lambda} keyword. If the function argument list is put -on a line of its own, as in line 5, it gets the @code{lambda-intro-cont} -syntax. The function body is handled as an inline method body, with the -addition of the @code{inlambda} syntactic symbol. This means that line -6 gets @code{inlambda} and @code{inline-open}, and line 8 gets -@code{inline-close}@footnote{You might wonder why it doesn't get -@code{inlambda} too. It's because the closing brace is relative to the -opening brace, which stands on its own line in this example. If the -opening brace was hanging on the previous line, then the closing brace -would get the @code{inlambda} syntax too to be indented correctly.}. - -@ssindex inexpr-statement -On line 9, @code{catch} is a special function taking a statement block -as its argument. The block is handled as an in-expression statement -with the @code{inexpr-statement} syntax, just like the gcc extended C -example above. The other similar special function, @code{gauge}, is -handled like this too. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node K&R Symbols, , Statement Block Symbols, Syntactic Symbols -@comment node-name, next, previous, up -@subsection K&R Symbols -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ssindex knr-argdecl-intro -@ssindex knr-argdecl -Two other syntactic symbols can appear in old style, non-prototyped C -code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: - -@example - 1: int add_three_integers(a, b, c) - 2: int a; - 3: int b; - 4: int c; - 5: @{ - 6: return a + b + c; - 7: @} -@end example - -Here, line 2 is the first line in an argument declaration list and so is -given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines -(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} -syntax. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Indentation Calculation, , Syntactic Symbols, Indentation Engine Basics -@comment node-name, next, previous, up -@section Indentation Calculation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Indentation for a line is calculated from the syntactic context -(@pxref{Syntactic Analysis}). - -First, a buffer position is found whose column will be the base for the -indentation calculation. It's the anchor position in the first -syntactic element that provides one that is used. If no syntactic -element has an anchor position then column zero is used. - -Second, the syntactic symbols in each syntactic element are looked up -in the @code{c-offsets-alist} style variable -(@pxref{c-offsets-alist}), which is an association list of syntactic -symbols and the offsets to apply for those symbols. These offsets are -added together with the base column to produce the new indentation -column. - -Let's use our two code examples above to see how this works. Here is -our first example again: - -@example - 1: void swap( int& a, int& b ) - 2: @{ - 3: int tmp = a; - 4: a = b; - 5: b = tmp; - 6: @} -@end example - -Let's say point is on line 3 and we hit the @key{TAB} key to reindent -the line. The syntactic context for that line is: - -@example -((defun-block-intro 29)) -@end example - -@noindent -Since buffer position 29 is the first and only anchor position in the -list, @ccmode{} goes there and asks for the current column. This brace -is in column zero, so @ccmode{} uses @samp{0} as the base column. - -Next, @ccmode{} looks up @code{defun-block-intro} in the -@code{c-offsets-alist} style variable. Let's say it finds the value -@samp{4}; it adds this to the base column @samp{0}, yielding a running -total indentation of 4 spaces. - -Since there is only one syntactic element on the list for this line, -indentation calculation is complete, and the total indentation for the -line is 4 spaces. - -Here's another example: - -@example - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end example - -If we were to hit @kbd{TAB} on line 4 in the above example, the same -basic process is performed, despite the differences in the syntactic -context. The context for this line is: - -@example -((substatement-open 46)) -@end example - -Here, @ccmode{} goes to buffer position 46, which is the @samp{i} in -@code{if} on line 3. This character is in the fourth column on that -line so the base column is @samp{4}. Then @ccmode{} looks up the -@code{substatement-open} symbol in @code{c-offsets-alist}. Let's say it -finds the value @samp{4}. It's added with the base column and yields an -indentation for the line of 8 spaces. - -Simple, huh? - -Actually, it's a bit more complicated than that since the entries on -@code{c-offsets-alist} can be much more than plain offsets. -@xref{c-offsets-alist}, for the full story. - -Anyway, the mode usually just does The Right Thing without you having to -think about it in this much detail. But when customizing indentation, -it's helpful to understand the general indentation model being used. - -As you configure @ccmode{}, you might want to set the variable -@code{c-echo-syntactic-information-p} to non-@code{nil} so that the -syntactic context and calculated offset always is echoed in the -minibuffer when you hit @kbd{TAB}. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Customizing Indentation, Custom Macros, Indentation Engine Basics, Top -@comment node-name, next, previous, up -@chapter Customizing Indentation -@cindex customization, indentation -@cindex indentation -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The principal variable for customizing indentation is the style -variable @code{c-offsets-alist}, which gives an @dfn{offset} (an -indentation rule) for each syntactic symbol. Its structure and -semantics are completely described in @ref{c-offsets-alist}. The -various ways you can set the variable, including the use of the -@ccmode{} style system, are described in @ref{Config Basics} and its -sections, in particular @ref{Style Variables}. - -The simplest and most used kind of ``offset'' setting in -@code{c-offsets-alist} is in terms of multiples of -@code{c-basic-offset}: - -@defopt c-basic-offset -@vindex basic-offset (c-) -This style variable holds the basic offset between indentation levels. -It's factory default is 4, but all the built-in styles set it -themselves, to some value between 2 (for @code{gnu} style) and 8 (for -@code{bsd}, @code{linux}, and @code{python} styles). -@end defopt - -The most flexible ``offset'' setting you can make in -@code{c-offsets-alist} is a line-up function (or even a list of them), -either one supplied by @ccmode{} (@pxref{Line-Up Functions}) or one -you write yourself (@pxref{Custom Line-Up}). - -Finally, in @ref{Other Indentation} you'll find the tool of last -resort: a hook which is called after a line has been indented. You -can install functions here to make ad-hoc adjustments to any line's -indentation. - -@menu -* c-offsets-alist:: -* Interactive Customization:: -* Line-Up Functions:: -* Custom Line-Up:: -* Other Indentation:: -@end menu - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node c-offsets-alist, Interactive Customization, Customizing Indentation, Customizing Indentation -@comment node-name, next, previous, up -@section c-offsets-alist -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -This section explains the structure and semantics of the style -variable @code{c-offset-alist}, the principal variable for configuring -indentation. Details of how to set it up, and its relationship to -@ccmode{}'s style system are given in @ref{Style Variables}. - -@defopt c-offsets-alist -@vindex offsets-alist (c-) -This is an alist which associates an offset with each syntactic -symbol. This @dfn{offset} is a rule specifying how to indent a line -whose syntactic context matches the symbol. @xref{Syntactic -Analysis}. - -Note that the buffer-local binding of this alist in a @ccmode{} buffer -contains an entry for @emph{every} syntactic symbol. Its global -binding and its settings within style specifications usually contain -only a few entries. @xref{Style Variables}. - -The offset specification associated with any particular syntactic -symbol can be an integer, a variable name, a vector, a function or -lambda expression, a list, or one of the following special symbols: -@code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The -meanings of these values are described in detail below. - -Here is an example fragment of a @code{c-offsets-alist}, showing some -of these kinds of offsets: - -@example -((statement . 0) - (substatement . +) - (cpp-macro . [0]) - (topmost-intro-cont . c-lineup-topmost-intro-cont) - (statement-block-intro . (add c-lineup-whitesmith-in-block - c-indent-multi-line-block)) - @dots{} -@*) -@end example -@end defopt - -@deffn Command c-set-offset (@kbd{C-c C-o}) -@findex set-offset (c-) -@kindex C-c C-o -This command changes the entry for a syntactic symbol in the current -binding of @code{c-offsets-alist}, or it inserts a new entry if there -isn't already one for that syntactic symbol. - -You can use @code{c-set-offsets} interactively within a @ccmode{} -buffer to make experimental changes to your indentation settings. -@kbd{C-c C-o} prompts you for the syntactic symbol to change -(defaulting to that of the current line) and the new offset -(defaulting to the current offset). - -@code{c-set-offsets} takes two arguments when used programmatically: -@var{symbol}, the syntactic element symbol to change and @var{offset}, -the new offset for that syntactic element. You can call the command -in your @file{.emacs} to change the global binding of -@code{c-offsets-alist} (@pxref{Style Variables}); you can use it in a -hook function to make changes from the current style. @ccmode{} -itself uses this function when initializing styles. -@end deffn - -@cindex offset specification -The ``offset specifications'' in @code{c-offsets-alist} can be any of -the following: - -@table @asis -@item An integer -The integer specifies a relative offset. All relative -offsets@footnote{The syntactic context @code{@w{((defun-block-intro -2724) (comment-intro))}} would likely have two relative offsets.} will -be added together and used to calculate the indentation relative to an -anchor position earlier in the buffer. @xref{Indentation -Calculation}, for details. Most of the time, it's probably better to -use one of the special symbols like @code{+} than an integer (apart -from zero). - -@item One of the symbols @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or @code{/} -These special symbols describe a relative offset in multiples of -@code{c-basic-offset}: - -By defining a style's indentation in terms of @code{c-basic-offset}, -you can change the amount of whitespace given to an indentation level -while maintaining the same basic shape of your code. Here are the -values that the special symbols correspond to: - -@table @code -@item + -@code{c-basic-offset} times 1 -@item - -@code{c-basic-offset} times -1 -@item ++ -@code{c-basic-offset} times 2 -@item -- -@code{c-basic-offset} times -2 -@item * -@code{c-basic-offset} times 0.5 -@item / -@code{c-basic-offset} times -0.5 -@end table - -@item A vector -The first element of the vector, an integer, sets the absolute -indentation column. This will override any previously calculated -indentation, but won't override relative indentation calculated from -syntactic elements later on in the syntactic context of the line being -indented. @xref{Indentation Calculation}. Any elements in the vector -beyond the first will be ignored. - -@item A function or lambda expression -The function will be called and its return value will in turn be -evaluated as an offset specification. Functions are useful when more -context than just the syntactic symbol is needed to get the desired -indentation. @xref{Line-Up Functions}, and @ref{Custom Line-Up}, for -details about them. - -@item A symbol with a variable binding -If the symbol also has a function binding, the function takes -precedence over the variable. Otherwise the value of the variable is -used. It must be an integer (which is used as relative offset) or a -vector (an absolute offset). - -@item A list -The offset can also be a list containing several offset -specifications; these are evaluated recursively and combined. A list -is typically only useful when some of the offsets are line-up -functions. A common strategy is calling a sequence of functions in -turn until one of them recognizes that it is appropriate for the -source line and returns a non-@code{nil} value. - -@code{nil} values are always ignored when the offsets are combined. -The first element of the list specifies the method of combining the -non-@code{nil} offsets from the remaining elements: - -@table @code -@item first -Use the first offset that doesn't evaluate to @code{nil}. Subsequent -elements of the list don't get evaluated. -@item min -Use the minimum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item max -Use the maximum of all the offsets. All must be either relative or -absolute - they can't be mixed. -@item add -Add all the evaluated offsets together. Exactly one of them may be -absolute, in which case the result is absolute. Any relative offsets -that preceded the absolute one in the list will be ignored in that case. -@end table - -As a compatibility measure, if the first element is none of the above -then it too will be taken as an offset specification and the whole list -will be combined according to the method @code{first}. -@end table - -@vindex c-strict-syntax-p -@vindex strict-syntax-p (c-) -If an offset specification evaluates to @code{nil}, then a relative -offset of 0 (zero) is used@footnote{There is however a variable -@code{c-strict-syntax-p} that when set to non-@code{nil} will cause an -error to be signaled in that case. It's now considered obsolete since -it doesn't work well with some of the alignment functions that return -@code{nil} instead of zero. You should therefore leave -@code{c-strict-syntax-p} set to @code{nil}.}. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Interactive Customization, Line-Up Functions, c-offsets-alist, Customizing Indentation -@comment node-name, next, previous, up -@section Interactive Customization -@cindex customization, interactive -@cindex interactive customization -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -As an example of how to customize indentation, let's change the -style of this example@footnote{In this and subsequent examples, the -original code is formatted using the @samp{gnu} style unless otherwise -indicated. @xref{Styles}.}: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -@noindent -to: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -In other words, we want to change the indentation of braces that open a -block following a condition so that the braces line up under the -conditional, instead of being indented. Notice that the construct we -want to change starts on line 4. To change the indentation of a line, -we need to see which syntactic symbols affect the offset calculations -for that line. Hitting @kbd{C-c C-s} on line 4 yields: - -@example -((substatement-open 44)) -@end example - -@noindent -so we know that to change the offset of the open brace, we need to -change the indentation for the @code{substatement-open} syntactic -symbol. - -To do this interactively, just hit @kbd{C-c C-o}. This prompts -you for the syntactic symbol to change, providing a reasonable default. -In this case, the default is @code{substatement-open}, which is just the -syntactic symbol we want to change! - -After you hit return, @ccmode{} will then prompt you for the new -offset value, with the old value as the default. The default in this -case is @samp{+}, but we want no extra indentation so enter -@samp{0} and @kbd{RET}. This will associate the offset 0 with the -syntactic symbol @code{substatement-open}. - -To check your changes quickly, just hit @kbd{C-c C-q} -(@code{c-indent-defun}) to reindent the entire function. The example -should now look like: - -@example -@group - 1: int add( int val, int incr, int doit ) - 2: @{ - 3: if( doit ) - 4: @{ - 5: return( val + incr ); - 6: @} - 7: return( val ); - 8: @} -@end group -@end example - -Notice how just changing the open brace offset on line 4 is all we -needed to do. Since the other affected lines are indented relative to -line 4, they are automatically indented the way you'd expect. For more -complicated examples, this might not always work. The general approach -to take is to always start adjusting offsets for lines higher up in the -file, then reindent and see if any following lines need further -adjustments. - -@c Move this bit to "Styles" (2005/10/7) -@deffn Command c-set-offset symbol offset -@findex set-offset (c-) -@kindex C-c C-o -This is the command bound to @kbd{C-c C-o}. It provides a convenient -way to set offsets on @code{c-offsets-alist} both interactively (see -the example above) and from your mode hook. - -It takes two arguments when used programmatically: @var{symbol} is the -syntactic element symbol to change and @var{offset} is the new offset -for that syntactic element. -@end deffn -@c End of MOVE THIS BIT. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Line-Up Functions, Custom Line-Up, Interactive Customization, Customizing Indentation -@comment node-name, next, previous, up -@section Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@cindex line-up function -@cindex indentation function -Often there are cases when a simple offset setting on a syntactic -symbol isn't enough to get the desired indentation---for example, you -might want to line up a closing parenthesis with the matching opening -one rather than indenting relative to its ``anchor point''. @ccmode{} -provides this flexibility with @dfn{line-up functions}. - -The way you associate a line-up function with a syntactic symbol is -described in @ref{c-offsets-alist}. @ccmode{} comes with many -predefined line-up functions for common situations. If none of these -does what you want, you can write your own. @xref{Custom Line-Up}. -Sometimes, it is easier to tweak the standard indentation by adding a -function to @code{c-special-indent-hook} (@pxref{Other Indentation}). - -The line-up functions haven't been adapted for AWK buffers or tested -with them. Some of them might work serendipitously. There shouldn't be -any problems writing custom line-up functions for AWK mode. - -The calling convention for line-up functions is described fully in -@ref{Custom Line-Up}. Roughly speaking, the return value is either an -offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, -meaning ``this function is inappropriate in this case - try a -different one''. @xref{c-offsets-alist}. - -The subsections below describe all the standard line-up functions, -categorized by the sort of token the lining-up centers around. For -each of these functions there is a ``works with'' list that indicates -which syntactic symbols the function is intended to be used with. - -@macro workswith -@emph{Works with:@ } -@end macro -@ifinfo -@unmacro workswith -@macro workswith -Works with: -@end macro -@end ifinfo - -@macro sssTBasicOffset -<--> @i{c-basic-offset}@c -@end macro - -@macro sssTsssTBasicOffset -<--><--> @i{c-basic-offset}@c -@end macro - -@macro hereFn{func} -<- @i{\func\}@c -@end macro - -@c The TeX backend seems to insert extra spaces around the argument. :P -@iftex -@unmacro hereFn -@macro hereFn{func} -<-@i{\func\}@c -@end macro -@end iftex - -@menu -* Brace/Paren Line-Up:: -* List Line-Up:: -* Operator Line-Up:: -* Comment Line-Up:: -* Misc Line-Up:: -@end menu - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Brace/Paren Line-Up, List Line-Up, Line-Up Functions, Line-Up Functions -@comment node-name, next, previous, up -@subsection Brace and Parenthesis Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for braces, -parentheses and statements within brace blocks. - -@defun c-lineup-close-paren -@findex lineup-close-paren (c-) -Line up the closing paren under its corresponding open paren if the -open paren is followed by code. If the open paren ends its line, no -indentation is added. E.g: - -@example -@group -main (int, - char ** - ) @hereFn{c-lineup-close-paren} -@end group -@end example - -@noindent -and - -@example -@group -main ( - int, char ** -) @hereFn{c-lineup-close-paren} -@end group -@end example - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} instead of the open paren column. See -@code{c-lineup-arglist} for further discussion of this ``DWIM'' measure. - -@workswith All @code{*-close} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@anchor{c-lineup-arglist-close-under-paren} -@defun c-lineup-arglist-close-under-paren -@findex lineup-arglist-close-under-paren (c-) -Set your @code{arglist-close} syntactic symbol to this line-up function -so that parentheses that close argument lists will line up under the -parenthesis that opened the argument list. It can also be used with -@code{arglist-cont} and @code{arglist-cont-nonempty} to line up all -lines inside a parenthesis under the open paren. - -As a special case, if a brace block is opened at the same line as the -open parenthesis of the argument list, the indentation is -@code{c-basic-offset} only. See @code{c-lineup-arglist} for further -discussion of this ``DWIM'' measure. - -@workswith Almost all symbols, but are typically most useful on -@code{arglist-close}, @code{brace-list-close}, @code{arglist-cont} and -@code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-one-line-block -@findex indent-one-line-block (c-) -Indent a one line block @code{c-basic-offset} extra. E.g: - -@example -@group -if (n > 0) - @{m+=n; n=0;@} @hereFn{c-indent-one-line-block} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -if (n > 0) -@{ @hereFn{c-indent-one-line-block} - m+=n; n=0; -@} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a one line block, -which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-indent-multi-line-block -@findex indent-multi-line-block (c-) -Indent a multiline block @code{c-basic-offset} extra. E.g: - -@example -@group -int *foo[] = @{ - NULL, - @{17@}, @hereFn{c-indent-multi-line-block} -@end group -@end example - -@noindent -and - -@example -@group -int *foo[] = @{ - NULL, - @{ @hereFn{c-indent-multi-line-block} - 17 - @}, - @sssTBasicOffset{} -@end group -@end example - -The block may be surrounded by any kind of parenthesis characters. -@code{nil} is returned if the line doesn't start with a multiline -block, which makes the function usable in list expressions. - -@workswith Almost all syntactic symbols, but most useful on the -@code{-open} symbols. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-runin-statements -@findex lineup-runin-statements (c-) -Line up statements for coding standards which place the first statement -in a block on the same line as the block opening brace@footnote{Run-in -style doesn't really work too well. You might need to write your own -custom line-up functions to better support this style.}. E.g: - -@example -@group -int main() -@{ puts ("Hello!"); - return 0; @hereFn{c-lineup-runin-statements} -@} -@end group -@end example - -If there is no statement after the opening brace to align with, -@code{nil} is returned. This makes the function usable in list -expressions. - -@workswith The @code{statement} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-inexpr-block -@findex lineup-inexpr-block (c-) -This can be used with the in-expression block symbols to indent the -whole block to the column where the construct is started. E.g. for Java -anonymous classes, this lines up the class under the @samp{new} keyword, -and in Pike it lines up the lambda function body under the @samp{lambda} -keyword. Returns @code{nil} if the block isn't part of such a -construct. - -@workswith @code{inlambda}, @code{inexpr-statement}, -@code{inexpr-class}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-after-whitesmith-blocks -@findex lineup-after-whitesmith-blocks (c-) -Compensate for Whitesmith style indentation of blocks. Due to the way -@ccmode{} calculates anchor positions for normal lines inside blocks, -this function is necessary for those lines to get correct Whitesmith -style indentation. Consider the following examples: - -@example -@group -int foo() - @{ - a; - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -@example -@group -int foo() - @{ - @{ - a; - @} - x; @hereFn{c-lineup-after-whitesmith-blocks} -@end group -@end example - -The fact that the line with @code{x} is preceded by a Whitesmith style -indented block in the latter case and not the first should not affect -its indentation. But since CC Mode in cases like this uses the -indentation of the preceding statement as anchor position, the @code{x} -would in the second case be indented too much if the offset for -@code{statement} was set simply to zero. - -This lineup function corrects for this situation by detecting if the -anchor position is at an open paren character. In that case, it instead -indents relative to the surrounding block just like -@code{c-lineup-whitesmith-in-block}. - -@workswith @code{brace-list-entry}, @code{brace-entry-open}, -@code{statement}, @code{arglist-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-whitesmith-in-block -@findex lineup-whitesmith-in-block (c-) -Line up lines inside a block in Whitesmith style. It's done in a way -that works both when the opening brace hangs and when it doesn't. E.g: - -@example -@group -something - @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@end group -@end example - -@noindent -and - -@example -@group -something @{ - foo; @hereFn{c-lineup-whitesmith-in-block} - @} -@sssTBasicOffset{} -@end group -@end example - -In the first case the indentation is kept unchanged, in the second -@code{c-basic-offset} is added. - -@workswith @code{defun-close}, @code{defun-block-intro}, -@code{inline-close}, @code{block-close}, @code{brace-list-close}, -@code{brace-list-intro}, @code{statement-block-intro}, -@code{arglist-intro}, @code{arglist-cont-nonempty}, -@code{arglist-close}, and all @code{in*} symbols, e.g. @code{inclass} -and @code{inextern-lang}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node List Line-Up, Operator Line-Up, Brace/Paren Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection List Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -form lists of items, usually separated by commas. - -The function @ref{c-lineup-arglist-close-under-paren}, which is mainly -for indenting a close parenthesis, is also useful for the lines -contained within parentheses. - -@defun c-lineup-arglist -@findex lineup-arglist (c-) -Line up the current argument line under the first argument. - -As a special case, if an argument on the same line as the open -parenthesis starts with a brace block opener, the indentation is -@code{c-basic-offset} only. This is intended as a ``DWIM'' measure in -cases like macros that contain statement blocks, e.g: - -@example -@group -A_VERY_LONG_MACRO_NAME (@{ - some (code, with + long, lines * in[it]); - @}); -@sssTBasicOffset{} -@end group -@end example - -This is motivated partly because it's more in line with how code -blocks are handled, and partly since it approximates the behavior of -earlier CC Mode versions, which due to inaccurate analysis tended to -indent such cases this way. - -@workswith @code{arglist-cont-nonempty}, @code{arglist-close}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-intro-after-paren -@findex lineup-arglist-intro-after-paren (c-) -Line up a line to just after the open paren of the surrounding paren or -brace block. - -@workswith @code{defun-block-intro}, @code{brace-list-intro}, -@code{statement-block-intro}, @code{statement-case-intro}, -@code{arglist-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-multi-inher -@findex lineup-multi-inher (c-) -Line up the classes in C++ multiple inheritance clauses and member -initializers under each other. E.g: - -@example -@group -Foo::Foo (int a, int b): - Cyphr (a), - Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - : public Cyphr, - public Bar @hereFn{c-lineup-multi-inher} -@end group -@end example - -@noindent -and - -@example -@group -Foo::Foo (int a, int b) - : Cyphr (a) - , Bar (b) @hereFn{c-lineup-multi-inher} -@end group -@end example - -@workswith @code{inher-cont}, @code{member-init-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-inher -@findex lineup-java-inher (c-) -Line up Java implements and extends declarations. If class names -follow on the same line as the @samp{implements}/@samp{extends} -keyword, they are lined up under each other. Otherwise, they are -indented by adding @code{c-basic-offset} to the column of the keyword. -E.g: - -@example -@group -class Foo - extends - Bar @hereFn{c-lineup-java-inher} - @sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -class Foo - extends Cyphr, - Bar @hereFn{c-lineup-java-inher} -@end group -@end example - -@workswith @code{inher-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-java-throws -@findex lineup-java-throws (c-) -Line up Java throws declarations. If exception names follow on the -same line as the throws keyword, they are lined up under each other. -Otherwise, they are indented by adding @code{c-basic-offset} to the -column of the @samp{throws} keyword. The @samp{throws} keyword itself -is also indented by @code{c-basic-offset} from the function declaration -start if it doesn't hang. E.g: - -@example -@group -int foo() - throws @hereFn{c-lineup-java-throws} - Bar @hereFn{c-lineup-java-throws} -@sssTsssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -int foo() throws Cyphr, - Bar, @hereFn{c-lineup-java-throws} - Vlod @hereFn{c-lineup-java-throws} -@end group -@end example - -@workswith @code{func-decl-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-template-args -@findex lineup-template-args (c-) -Line up the arguments of a template argument list under each other, but -only in the case where the first argument is on the same line as the -opening @samp{<}. - -To allow this function to be used in a list expression, @code{nil} is -returned if there's no template argument on the first line. - -@workswith @code{template-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-call -@findex lineup-ObjC-method-call (c-) -For Objective-C code, line up selector args as Emacs Lisp mode does -with function args: go to the position right after the message receiver, -and if you are at the end of the line, indent the current line -c-basic-offset columns from the opening bracket; otherwise you are -looking at the first character of the first method call argument, so -lineup the current line with it. - -@workswith @code{objc-method-call-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args -@findex lineup-ObjC-method-args (c-) -For Objective-C code, line up the colons that separate args. The colon -on the current line is aligned with the one on the first line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-ObjC-method-args-2 -@findex lineup-ObjC-method-args-2 (c-) -Similar to @code{c-lineup-ObjC-method-args} but lines up the colon on -the current line with the colon on the previous line. - -@workswith @code{objc-method-args-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Operator Line-Up, Comment Line-Up, List Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Operator Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here calculate the indentation for lines which -start with an operator, by lining it up with something on the previous -line. - -@defun c-lineup-argcont -@findex lineup-argcont (c-) -Line up a continued argument. E.g: - -@example -@group -foo (xyz, aaa + bbb + ccc - + ddd + eee + fff); @hereFn{c-lineup-argcont} -@end group -@end example - -Only continuation lines like this are touched, @code{nil} is returned on -lines which are the start of an argument. - -Within a gcc @code{asm} block, @code{:} is recognized as an argument -separator, but of course only between operand specifications, not in the -expressions for the operands. - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-arglist-operators -@findex lineup-arglist-operators (c-) -Line up lines starting with an infix operator under the open paren. -Return @code{nil} on lines that don't start with an operator, to leave -those cases to other line-up functions. Example: - -@example -@group -if ( x < 10 - || at_limit (x, @hereFn{c-lineup-arglist-operators} - list) @hereFn{c-lineup-arglist-operators@r{ returns nil}} - ) -@end group -@end example - -Since this function doesn't do anything for lines without an infix -operator you typically want to use it together with some other lineup -settings, e.g. as follows (the @code{arglist-close} setting is just a -suggestion to get a consistent style): - -@example -(c-set-offset 'arglist-cont - '(c-lineup-arglist-operators 0)) -(c-set-offset 'arglist-cont-nonempty - '(c-lineup-arglist-operators c-lineup-arglist)) -(c-set-offset 'arglist-close - '(c-lineup-arglist-close-under-paren)) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-assignments -@findex lineup-assignments (c-) -Line up the current line after the assignment operator on the first line -in the statement. If there isn't any, return nil to allow stacking with -other line-up functions. If the current line contains an assignment -operator too, try to align it with the first one. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. - -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-math -@findex lineup-math (c-) -Like @code{c-lineup-assignments} but indent with @code{c-basic-offset} -if no assignment operator was found on the first line. I.e. this -function is the same as specifying a list @code{(c-lineup-assignments -+)}. It's provided for compatibility with old configurations. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cascaded-calls -@findex lineup-cascaded-calls (c-) -Line up ``cascaded calls'' under each other. If the line begins with -@code{->} or @code{.} and the preceding line ends with one or more -function calls preceded by the same token, then the arrow is lined up -with the first of those tokens. E.g: - -@example -@group -r = proc->add(17)->add(18) - ->add(19) + @hereFn{c-lineup-cascaded-calls} - offset; @hereFn{c-lineup-cascaded-calls@r{ (inactive)}} -@end group -@end example - -In any other situation @code{nil} is returned to allow use in list -expressions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-streamop -@findex lineup-streamop (c-) -Line up C++ stream operators (i.e. @samp{<<} and @samp{>>}). - -@workswith @code{stream-op}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-string-cont -@findex lineup-string-cont (c-) -Line up a continued string under the one it continues. A continued -string in this sense is where a string literal follows directly after -another one. E.g: - -@example -@group -result = prefix + "A message " - "string."; @hereFn{c-lineup-string-cont} -@end group -@end example - -@code{nil} is returned in other situations, to allow stacking with other -lineup functions. - -@workswith @code{topmost-intro-cont}, @code{statement-cont}, -@code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Comment Line-Up, Misc Line-Up, Operator Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Comment Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The lineup functions here calculate the indentation for several types -of comment structure. - -@defun c-lineup-C-comments -@findex lineup-C-comments (c-) -Line up C block comment continuation lines. Various heuristics are used -to handle most of the common comment styles. Some examples: - -@example -@group -/* /** /* - * text * text text - */ */ */ -@end group -@end example - -@example -@group -/* text /* /** - text ** text ** text -*/ */ */ -@end group -@end example - -@example -@group -/************************************************** - * text - *************************************************/ -@end group -@end example - -@vindex comment-start-skip -@example -@group -/************************************************** - Free form text comments: - In comments with a long delimiter line at the - start, the indentation is kept unchanged for lines - that start with an empty comment line prefix. The - delimiter line is whatever matches the - @code{comment-start-skip} regexp. -**************************************************/ -@end group -@end example - -The style variable @code{c-comment-prefix-regexp} is used to recognize -the comment line prefix, e.g. the @samp{*} that usually starts every -line inside a comment. - -@workswith The @code{c} syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-comment -@findex lineup-comment (c-) -Line up a comment-only line according to the style variable -@code{c-comment-only-line-offset}. If the comment is lined up with a -comment starter on the previous line, that alignment is preserved. - -@defopt c-comment-only-line-offset -@vindex comment-only-line-offset (c-) -This style variable specifies the extra offset for the line. It can -contain an integer or a cons cell of the form - -@example -(@r{@var{non-anchored-offset}} . @r{@var{anchored-offset}}) -@end example - -@noindent -where @var{non-anchored-offset} is the amount of offset given to -non-column-zero anchored lines, and @var{anchored-offset} is the amount -of offset to give column-zero anchored lines. Just an integer as value -is equivalent to @code{(@r{@var{value}} . -1000)}. -@end defopt - -@workswith @code{comment-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-knr-region-comment -@findex lineup-knr-region-comment (c-) -Line up a comment in the ``K&R region'' with the declaration. That is -the region between the function or class header and the beginning of the -block. E.g: - -@example -@group -int main() -/* Called at startup. */ @hereFn{c-lineup-knr-region-comment} -@{ - return 0; -@} -@end group -@end example - -Return @code{nil} if called in any other situation, to be useful in list -expressions. - -@workswith @code{comment-intro}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Misc Line-Up, , Comment Line-Up, Line-Up Functions -@comment node-name, next, previous, up -@subsection Miscellaneous Line-Up Functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The line-up functions here are the odds and ends which didn't fit into -any earlier category. - -@defun c-lineup-dont-change -@findex lineup-dont-change (c-) -This lineup function makes the line stay at whatever indentation it -already has; think of it as an identity function for lineups. - -@workswith Any syntactic symbol. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-cpp-define -@findex lineup-cpp-define (c-) -Line up macro continuation lines according to the indentation of the -construct preceding the macro. E.g: - -@example -@group -const char msg[] = @hereFn{@r{The beginning of the preceding construct.}} - \"Some text.\"; - -#define X(A, B) \ -do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ -@} while (0) -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) @hereFn{@r{The beginning of the preceding construct.}} - error(\"Not running!\"); - -#define X(A, B) \ - do @{ \ @hereFn{c-lineup-cpp-define} - printf (A, B); \ - @} while (0) -@end group -@end example - -If @code{c-syntactic-indentation-in-macros} is non-@code{nil}, the -function returns the relative indentation to the macro start line to -allow accumulation with other offsets. E.g. in the following cases, -@code{cpp-define-intro} is combined with the -@code{statement-block-intro} that comes from the @samp{do @{} that hangs -on the @samp{#define} line: - -@example -@group -const char msg[] = - \"Some text.\"; - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ -@} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -@noindent -and: - -@example -@group -int dribble() @{ - if (!running) - error(\"Not running!\"); - -#define X(A, B) do @{ \ - printf (A, B); \ @hereFn{c-lineup-cpp-define} - this->refs++; \ - @} while (0) @hereFn{c-lineup-cpp-define} -@end group -@end example - -The relative indentation returned by @code{c-lineup-cpp-define} is zero -and two, respectively, on the two lines in each of these examples. They -are then added to the two column indentation that -@code{statement-block-intro} gives in both cases here. - -If the relative indentation is zero, then @code{nil} is returned -instead. That is useful in a list expression to specify the default -indentation on the top level. - -If @code{c-syntactic-indentation-in-macros} is @code{nil} then this -function keeps the current indentation, except for empty lines (ignoring -the ending backslash) where it takes the indentation from the closest -preceding nonempty line in the macro. If there's no such line in the -macro then the indentation is taken from the construct preceding it, as -described above. - -@workswith @code{cpp-define-intro}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-gcc-asm-reg -@findex lineup-gcc-asm-reg (c-) -Line up a gcc asm register under one on a previous line. - -@example -@group - asm ("foo %1, %0\n" - "bar %0, %1" - : "=r" (w), - "=r" (x) - : "0" (y), - "1" (z)); -@end group -@end example - -The @samp{x} line is aligned to the text after the @samp{:} on the -@samp{w} line, and similarly @samp{z} under @samp{y}. - -This is done only in an @samp{asm} or @samp{__asm__} block, and only to -those lines mentioned. Anywhere else @code{nil} is returned. The usual -arrangement is to have this routine as an extra feature at the start of -arglist lineups, e.g. - -@example -(c-lineup-gcc-asm-reg c-lineup-arglist) -@end example - -@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. -@end defun - -@comment ------------------------------------------------------------ - -@defun c-lineup-topmost-intro-cont -@findex lineup-topmost-intro-cont (c-) -Line up declaration continuation lines zero or one indentation -step@footnote{This function is mainly provided to mimic the behavior of -CC Mode 5.28 and earlier where this case wasn't handled consistently so -that those lines could be analyzed as either topmost-intro-cont or -statement-cont. It's used for @code{topmost-intro-cont} by default, but -you might consider using @code{+} instead.}. For lines preceding a -definition, zero is used. For other lines, @code{c-basic-offset} is -added to the indentation. E.g: - -@example -@group -int -neg (int i) @hereFn{c-lineup-topmost-intro-cont} -@{ - return -i; -@} -@end group -@end example - -@noindent -and - -@example -@group -struct -larch @hereFn{c-lineup-topmost-intro-cont} -@{ - double height; -@} - the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@sssTBasicOffset{} -@end group -@end example - -@noindent -and - -@example -@group -struct larch -the_larch, @hereFn{c-lineup-topmost-intro-cont} - another_larch; @hereFn{c-lineup-topmost-intro-cont} -@end group -@end example - -@workswith @code{topmost-intro-cont}. -@end defun - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Line-Up, Other Indentation, Line-Up Functions, Customizing Indentation -@comment node-name, next, previous, up -@section Custom Line-Up Functions -@cindex customization, indentation functions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The most flexible way to customize indentation is by writing custom -line-up functions, and associating them with specific syntactic -symbols (@pxref{c-offsets-alist}). Depending on the effect you want, -it might be better to write a @code{c-special-indent-hook} function -rather than a line-up function (@pxref{Other Indentation}). - -@ccmode{} comes with an extensive set of predefined line-up functions, -not all of which are used by the default styles. So there's a good -chance the function you want already exists. @xref{Line-Up -Functions}, for a list of them. If you write your own line-up -function, it's probably a good idea to start working from one of these -predefined functions, which can be found in the file -@file{cc-align.el}. If you have written a line-up function that you -think is generally useful, you're very welcome to contribute it; -please contact @email{bug-cc-mode@@gnu.org}. - - Line-up functions are passed a single argument, the syntactic -element (see below). The return value is a @code{c-offsets-alist} -offset specification: for example, an integer, a symbol such as -@code{+}, a vector, @code{nil}@footnote{Returning @code{nil} is useful -when the offset specification for a syntactic element is a list -containing the line-up function (@pxref{c-offsets-alist}).}, or even -another line-up function. Full details of these are in -@ref{c-offsets-alist}. - -Line-up functions must not move point or change the content of the -buffer (except temporarily). They are however allowed to do -@dfn{hidden buffer changes}, i.e. setting text properties for caching -purposes etc. Buffer undo recording is disabled while they run. - -The syntactic element passed as the parameter to a line-up function is -a cons cell of the form - -@example -(@r{@var{syntactic-symbol}} . @r{@var{anchor-position}}) -@end example - -@noindent -@c FIXME!!! The following sentence might be better omitted, since the -@c information is in the cross reference "Syntactic Analysis". 2005/10/2. -where @var{syntactic-symbol} is the symbol that the function was -called for, and @var{anchor-position} is the anchor position (if any) -for the construct that triggered the syntactic symbol -(@pxref{Syntactic Analysis}). This cons cell is how the syntactic -element of a line used to be represented in @ccmode{} 5.28 and -earlier. Line-up functions are still passed this cons cell, so as to -preserve compatibility with older configurations. In the future, we -may decide to convert to using the full list format---you can prepare -your setup for this by using the access functions -(@code{c-langelem-sym}, etc.) described below. - -@vindex c-syntactic-element -@vindex syntactic-element (c-) -@vindex c-syntactic-context -@vindex syntactic-context (c-) -Some syntactic symbols, e.g. @code{arglist-cont-nonempty}, have more -info in the syntactic element - typically other positions that can be -interesting besides the anchor position. That info can't be accessed -through the passed argument, which is a cons cell. Instead, you can -get this information from the variable @code{c-syntactic-element}, -which is dynamically bound to the complete syntactic element. The -variable @code{c-syntactic-context} might also be useful - it gets -dynamically bound to the complete syntactic context. @xref{Custom -Braces}. - -@ccmode{} provides a few functions to access parts of syntactic -elements in a more abstract way. Besides making the code easier to -read, they also hide the difference between the old cons cell form -used in the line-up function argument and the new list form used in -@code{c-syntactic-element} and everywhere else. The functions are: - -@defun c-langelem-sym langelem -@findex langelem-sym (c-) -Return the syntactic symbol in @var{langelem}. -@end defun - -@defun c-langelem-pos langelem -@findex langelem-pos (c-) -Return the anchor position in @var{langelem}, or nil if there is none. -@end defun - -@defun c-langelem-col langelem &optional preserve-point -@findex langelem-col (c-) -Return the column of the anchor position in @var{langelem}. Also move -the point to that position unless @var{preserve-point} is -non-@code{nil}. -@end defun - -@defun c-langelem-2nd-pos langelem -@findex langelem-2nd-pos (c-) -Return the secondary position in @var{langelem}, or @code{nil} if there -is none. - -Note that the return value of this function is always @code{nil} if -@var{langelem} is in the old cons cell form. Thus this function is -only meaningful when used on syntactic elements taken from -@code{c-syntactic-element} or @code{c-syntactic-context}. -@end defun - -Custom line-up functions can be as simple or as complex as you like, and -any syntactic symbol that appears in @code{c-offsets-alist} can have a -custom line-up function associated with it. - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Other Indentation, , Custom Line-Up, Customizing Indentation -@comment node-name, next, previous, up -@section Other Special Indentations -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here are the remaining odds and ends regarding indentation: - -@defopt c-label-minimum-indentation -@vindex label-minimum-indentation (c-) -In @samp{gnu} style (@pxref{Built-in Styles}), a minimum indentation is -imposed on lines inside code blocks. This minimum indentation is -controlled by this style variable. The default value is 1. - -@findex c-gnu-impose-minimum -@findex gnu-impose-minimum (c-) -It's the function @code{c-gnu-impose-minimum} that enforces this minimum -indentation. It must be present on @code{c-special-indent-hook} to -work. -@end defopt - -@defopt c-special-indent-hook -@vindex special-indent-hook (c-) -This style variable is a standard hook variable that is called after -every line is indented by @ccmode{}. It is called only if -@code{c-syntactic-indentation} is non-@code{nil} (which it is by -default (@pxref{Indentation Engine Basics})). You can put a function -on this hook to do any special indentation or ad hoc line adjustments -your style dictates, such as adding extra indentation to constructors -or destructor declarations in a class definition, etc. Sometimes it -is better to write a custom Line-up Function instead (@pxref{Custom -Line-Up}). - -When the indentation engine calls this hook, the variable -@code{c-syntactic-context} is bound to the current syntactic context -(i.e. what you would get by typing @kbd{C-c C-s} on the source line. -@xref{Custom Braces}.). Note that you should not change point or mark -inside a @code{c-special-indent-hook} function, i.e. you'll probably -want to wrap your function in a @code{save-excursion}@footnote{The -numerical value returned by @code{point} will change if you change the -indentation of the line within a @code{save-excursion} form, but point -itself will still be over the same piece of text.}. - -Setting @code{c-special-indent-hook} in style definitions is handled -slightly differently from other variables---A style can only add -functions to this hook, not remove them. @xref{Style Variables}. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Custom Macros, Odds and Ends, Customizing Indentation, Top -@comment node-name, next, previous, up -@chapter Customizing Macros -@cindex macros -@cindex preprocessor directives -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Normally, the lines in a multi-line macro are indented relative to -each other as though they were code. You can suppress this behavior -by setting the following user option: - -@defopt c-syntactic-indentation-in-macros -@vindex syntactic-indentation-in-macros (c-) -Enable syntactic analysis inside macros, which is the default. If this -is @code{nil}, all lines inside macro definitions are analyzed as -@code{cpp-macro-cont}. -@end defopt - -@ccmode{} provides some tools to help keep the line continuation -backslashes in macros neat and tidy. Their precise action is -customized with these variables: - -@defopt c-backslash-column -@vindex backslash-column (c-) -@defoptx c-backslash-max-column -@vindex backslash-max-column (c-) -These variables control the alignment columns for line continuation -backslashes in multiline macros. They are used by the functions that -automatically insert or align such backslashes, -e.g. @code{c-backslash-region} and @code{c-context-line-break}. - -@code{c-backslash-column} specifies the minimum column for the -backslashes. If any line in the macro goes past this column, then the -next tab stop (i.e. next multiple of @code{tab-width}) in that line is -used as the alignment column for all the backslashes, so that they -remain in a single column. However, if any lines go past -@code{c-backslash-max-column} then the backslashes in the rest of the -macro will be kept at that column, so that the lines which are too -long ``stick out'' instead. - -Don't ever set these variables to @code{nil}. If you want to disable -the automatic alignment of backslashes, use -@code{c-auto-align-backslashes}. -@end defopt - -@defopt c-auto-align-backslashes -@vindex auto-align-backslashes (c-) -Align automatically inserted line continuation backslashes if -non-@code{nil}. When line continuation backslashes are inserted -automatically for line breaks in multiline macros, e.g. by -@code{c-context-line-break}, they are aligned with the other -backslashes in the same macro if this flag is set. - -If @code{c-auto-align-backslashes} is @code{nil}, automatically -inserted backslashes are preceded by a single space, and backslashes -get aligned only when you explicitly invoke the command -@code{c-backslash-region} (@kbd{C-c C-\}). -@end defopt - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Odds and Ends, Sample .emacs File, Custom Macros, Top -@comment node-name, next, previous, up -@chapter Odds and Ends -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -The stuff that didn't fit in anywhere else is documented here. - -@defopt c-require-final-newline -@vindex require-final-newline (c-) -Controls whether a final newline is enforced when the file is saved. -The value is an association list that for each language mode specifies -the value to give to @code{require-final-newline} (@pxref{Saving -Buffers,,, @lispref{}, @lispreftitle{}}) at mode initialization. If a -language isn't present on the association list, CC Mode won't touch -@code{require-final-newline} in buffers for that language. - -The default is to set @code{require-final-newline} to @code{t} in the -languages that mandate that source files should end with newlines. -These are C, C++ and Objective-C. -@end defopt - -@defopt c-echo-syntactic-information-p -@vindex echo-syntactic-information-p (c-) -If non-@code{nil}, the syntactic analysis for the current line is shown -in the echo area when it's indented (unless -@code{c-syntactic-indentation} is @code{nil}). That's useful when -finding out which syntactic symbols to modify to get the indentation you -want. -@end defopt - -@defopt c-report-syntactic-errors -@vindex report-syntactic-errors (c-) -If non-@code{nil}, certain syntactic errors are reported with a ding and -a message, for example when an @code{else} is indented for which there -is no corresponding @code{if}. - -Note however that @ccmode{} doesn't make any special effort to check for -syntactic errors; that's the job of the compiler. The reason it can -report cases like the one above is that it can't find the correct -anchoring position to indent the line in that case. -@end defopt - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Sample .emacs File, Performance Issues, Odds and Ends, Top -@comment node-name, next, previous, up -@appendix Sample .emacs File -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Here's a sample .emacs file fragment that might help you along the way. -Just copy this region and paste it into your .emacs file. You might want -to change some of the actual values. - -@verbatim -;; Make a non-standard key binding. We can put this in -;; c-mode-base-map because c-mode-map, c++-mode-map, and so on, -;; inherit from it. -(defun my-c-initialization-hook () - (define-key c-mode-base-map "\C-m" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-c-initialization-hook) - -;; offset customizations not in my-c-style -;; This will take precedence over any setting of the syntactic symbol -;; made by a style. -(setq c-offsets-alist '((member-init-intro . ++))) - -;; Create my personal style. -(defconst my-c-style - '((c-tab-always-indent . t) - (c-comment-only-line-offset . 4) - (c-hanging-braces-alist . ((substatement-open after) - (brace-list-open))) - (c-hanging-colons-alist . ((member-init-intro before) - (inher-intro) - (case-label after) - (label after) - (access-label after))) - (c-cleanup-list . (scope-operator - empty-defun-braces - defun-close-semi)) - (c-offsets-alist . ((arglist-close . c-lineup-arglist) - (substatement-open . 0) - (case-label . 4) - (block-open . 0) - (knr-argdecl-intro . -))) - (c-echo-syntactic-information-p . t)) - "My C Programming Style") -(c-add-style "PERSONAL" my-c-style) - -;; Customizations for all modes in CC Mode. -(defun my-c-mode-common-hook () - ;; set my personal style for the current buffer - (c-set-style "PERSONAL") - ;; other customizations - (setq tab-width 8 - ;; this will make sure spaces are used instead of tabs - indent-tabs-mode nil) - ;; we like auto-newline, but not hungry-delete - (c-toggle-auto-newline 1)) -(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) -@end verbatim - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Performance Issues, Limitations and Known Bugs, Sample .emacs File, Top -@comment node-name, next, previous, up -@chapter Performance Issues -@cindex performance -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@comment FIXME: (ACM, 2003/5/24). Check whether AWK needs mentioning here. - -C and its derivative languages are highly complex creatures. Often, -ambiguous code situations arise that require @ccmode{} to scan large -portions of the buffer to determine syntactic context. Such -pathological code can cause @ccmode{} to perform fairly badly. This -section gives some insight in how @ccmode{} operates, how that interacts -with some coding styles, and what you can use to improve performance. - -The overall goal is that @ccmode{} shouldn't be overly slow (i.e. take -more than a fraction of a second) in any interactive operation. -I.e. it's tuned to limit the maximum response time in single operations, -which is sometimes at the expense of batch-like operations like -reindenting whole blocks. If you find that @ccmode{} gradually gets -slower and slower in certain situations, perhaps as the file grows in -size or as the macro or comment you're editing gets bigger, then chances -are that something isn't working right. You should consider reporting -it, unless it's something that's mentioned in this section. - -Because @ccmode{} has to scan the buffer backwards from the current -insertion point, and because C's syntax is fairly difficult to parse in -the backwards direction, @ccmode{} often tries to find the nearest -position higher up in the buffer from which to begin a forward scan -(it's typically an opening or closing parenthesis of some kind). The -farther this position is from the current insertion point, the slower it -gets. - -@findex beginning-of-defun -In earlier versions of @ccmode{}, we used to recommend putting the -opening brace of a top-level construct@footnote{E.g. a function in C, -or outermost class definition in C++ or Java.} into the leftmost -column. Earlier still, this used to be a rigid Emacs constraint, as -embodied in the @code{beginning-of-defun} function. @ccmode now -caches syntactic information much better, so that the delay caused by -searching for such a brace when it's not in column 0 is minimal, -except perhaps when you've just moved a long way inside the file. - -@findex defun-prompt-regexp -@vindex c-Java-defun-prompt-regexp -@vindex Java-defun-prompt-regexp (c-) -A special note about @code{defun-prompt-regexp} in Java mode: The common -style is to hang the opening braces of functions and classes on the -right side of the line, and that doesn't work well with the Emacs -approach. @ccmode{} comes with a constant -@code{c-Java-defun-prompt-regexp} which tries to define a regular -expression usable for this style, but there are problems with it. In -some cases it can cause @code{beginning-of-defun} to hang@footnote{This -has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, -it is not used by default, but if you feel adventurous, you can set -@code{defun-prompt-regexp} to it in your mode hook. In any event, -setting and relying on @code{defun-prompt-regexp} will definitely slow -things down because (X)Emacs will be doing regular expression searches a -lot, so you'll probably be taking a hit either way! - -@ccmode{} maintains a cache of the opening parentheses of the blocks -surrounding the point, and it adapts that cache as the point is moved -around. That means that in bad cases it can take noticeable time to -indent a line in a new surrounding, but after that it gets fast as long -as the point isn't moved far off. The farther the point is moved, the -less useful is the cache. Since editing typically is done in ``chunks'' -rather than on single lines far apart from each other, the cache -typically gives good performance even when the code doesn't fit the -Emacs approach to finding the defun starts. - -@vindex c-enable-xemacs-performance-kludge-p -@vindex enable-xemacs-performance-kludge-p (c-) -XEmacs users can set the variable -@code{c-enable-xemacs-performance-kludge-p} to non-@code{nil}. This -tells @ccmode{} to use XEmacs-specific built-in functions which, in some -circumstances, can locate the top-most opening brace much more quickly than -@code{beginning-of-defun}. Preliminary testing has shown that for -styles where these braces are hung (e.g. most JDK-derived Java styles), -this hack can improve performance of the core syntax parsing routines -from 3 to 60 times. However, for styles which @emph{do} conform to -Emacs' recommended style of putting top-level braces in column zero, -this hack can degrade performance by about as much. Thus this variable -is set to @code{nil} by default, since the Emacs-friendly styles should -be more common (and encouraged!). Note that this variable has no effect -in Emacs since the necessary built-in functions don't exist (in Emacs -22.1 as of this writing in February 2007). - -Text properties are used to speed up skipping over syntactic whitespace, -i.e. comments and preprocessor directives. Indenting a line after a -huge macro definition can be slow the first time, but after that the -text properties are in place and it should be fast (even after you've -edited other parts of the file and then moved back). - -Font locking can be a CPU hog, especially the font locking done on -decoration level 3 which tries to be very accurate. Note that that -level is designed to be used with a font lock support mode that only -fontifies the text that's actually shown, i.e. Lazy Lock or Just-in-time -Lock mode, so make sure you use one of them. Fontification of a whole -buffer with some thousand lines can often take over a minute. That is -a known weakness; the idea is that it never should happen. - -The most effective way to speed up font locking is to reduce the -decoration level to 2 by setting @code{font-lock-maximum-decoration} -appropriately. That level is designed to be as pretty as possible -without sacrificing performance. @xref{Font Locking Preliminaries}, for -more info. - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Limitations and Known Bugs, FAQ, Performance Issues, Top -@comment node-name, next, previous, up -@chapter Limitations and Known Bugs -@cindex limitations -@cindex bugs -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@ccmode{} doesn't support trigraphs. (These are character sequences -such as @samp{??(}, which represents @samp{[}. They date from a time -when some character sets didn't have all the characters that C needs, -and are now utterly obsolete.) - -@item -There is no way to apply auto newline settings (@pxref{Auto-newlines}) -on already typed lines. That's only a feature to ease interactive -editing. - -To generalize this issue a bit: @ccmode{} is not intended to be used as -a reformatter for old code in some more or less batch-like way. With -the exception of some functions like @code{c-indent-region}, it's only -geared to be used interactively to edit new code. There's currently no -intention to change this goal. - -If you want to reformat old code, you're probably better off using some -other tool instead, e.g. @ref{Top, , GNU indent, indent, The `indent' -Manual}, which has more powerful reformatting capabilities than -@ccmode{}. - -@item -The support for C++ templates (in angle brackets) is not yet complete. -When a non-nested template is used in a declaration, @ccmode{} indents -it and font-locks it OK. Templates used in expressions, and nested -templates do not fare so well. Sometimes a workaround is to refontify -the expression after typing the closing @samp{>}. - -@item -In a @dfn{k&r region} (the part of an old-fashioned C function -declaration which specifies the types of its parameters, coming -between the parameter list and the opening brace), there should be at -most 20 top-level parenthesis and bracket pairs. This limit has been -imposed for performance reasons. If it is violated, the source file -might be incorrectly indented or fontified. - -@item -On loading @ccmode{}, sometimes this error message appears: - -@example -File mode specification error: (void-variable c-font-lock-keywords-3) -@end example - -This is due to a bug in the function @code{eval-after-load} in some -versions of (X)Emacs. It can manifest itself when there is a symbolic -link in the path of the directory which contains (X)Emacs. As a -workaround, put the following into your @file{.emacs} file, fairly -early on: - -@example -(defun my-load-cc-fonts () - (require "cc-fonts")) -(add-hook 'c-initialization-hook 'my-load-cc-fonts) -@end example -@end itemize - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node FAQ, Updating CC Mode, Limitations and Known Bugs, Top -@comment node-name, next, previous, up -@appendix Frequently Asked Questions -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@itemize @bullet -@item -@emph{How can I change the indent level from 4 spaces to 2 spaces?} - -Set the variable @code{c-basic-offset}. @xref{Getting Started}. - -@item -@kindex RET -@kindex C-j -@emph{Why doesn't the @kbd{RET} key indent the new line?} - -Emacs' convention is that @kbd{RET} just adds a newline, and that -@kbd{C-j} adds a newline and indents it. You can make @kbd{RET} do this -too by adding this to your @code{c-initialization-hook}: - -@example -(define-key c-mode-base-map "\C-m" 'c-context-line-break) -@end example - -@xref{Getting Started}. This is a very common question. If you want -this to be the default behavior, don't lobby us, lobby RMS! @t{:-)} - -@item -@emph{How do I stop my code jumping all over the place when I type?} - -Deactivate ``electric minor mode'' with @kbd{C-c C-l}. @xref{Getting -Started}. - -@item -@kindex C-x h -@kindex C-M-\ -@emph{How do I reindent the whole file?} - -Visit the file and hit @kbd{C-x h} to mark the whole buffer. Then hit -@kbd{C-M-\}. @xref{Indentation Commands}. - -@item -@kindex C-M-q -@kindex C-M-u -@emph{How do I reindent the current block?} - -First move to the brace which opens the block with @kbd{C-M-u}, then -reindent that expression with @kbd{C-M-q}. @xref{Indentation -Commands}. - -@item -@emph{I put @code{(c-set-offset 'substatement-open 0)} in my -@file{.emacs} file but I get an error saying that @code{c-set-offset}'s -function definition is void. What's wrong?} - -This means that @ccmode{} hasn't yet been loaded into your Emacs -session by the time the @code{c-set-offset} call is reached, most -likely because @ccmode{} is being autoloaded. Instead of putting the -@code{c-set-offset} line in your top-level @file{.emacs} file, put it -in your @code{c-initialization-hook} (@pxref{CC Hooks}), or simply -modify @code{c-offsets-alist} directly: - -@example -(setq c-offsets-alist '((substatement-open . 0))) -@end example - -@item -@cindex open paren in column zero -@emph{I have an open paren character at column zero inside a comment or -multiline string literal, and it causes the fontification and/or -indentation to go haywire. What gives?} - -It's due to the ad-hoc rule in (X)Emacs that such open parens always -start defuns (which translates to functions, classes, namespaces or any -other top-level block constructs in the @ccmode{} languages). -@ifset XEMACS -@xref{Defuns,,, xemacs, XEmacs User's Manual}, for details. -@end ifset -@ifclear XEMACS -@xref{Left Margin Paren,,, emacs, GNU Emacs Manual}, for details -(@xref{Defuns,,, emacs, GNU Emacs Manual}, in the Emacs 20 manual). -@end ifclear - -This heuristic is built into the core syntax analysis routines in -(X)Emacs, so it's not really a @ccmode{} issue. However, in Emacs -21.1 it became possible to turn it off@footnote{Using the variable -@code{open-paren-in-column-0-is-defun-start}.} and @ccmode{} does so -there since it's got its own system to keep track of blocks. - -@end itemize - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Updating CC Mode, Mailing Lists and Bug Reports, FAQ, Top -@comment node-name, next, previous, up -@appendix Getting the Latest CC Mode Release -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@ccmode{} has been standard with all versions of Emacs since 19.34 and -of XEmacs since 19.16. - -@cindex web site -Due to release schedule skew, it is likely that all of these Emacsen -have old versions of @ccmode{} and so should be upgraded. Access to the -@ccmode{} source code, as well as more detailed information on Emacsen -compatibility, etc. are all available on the web site: - -@quotation -@uref{http://cc-mode.sourceforge.net/} -@end quotation - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Mailing Lists and Bug Reports, GNU Free Documentation License, Updating CC Mode, Top -@comment node-name, next, previous, up -@appendix Mailing Lists and Submitting Bug Reports -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@kindex C-c C-b -@findex c-submit-bug-report -@findex submit-bug-report (c-) -To report bugs, use the @kbd{C-c C-b} (bound to -@code{c-submit-bug-report}) command. This provides vital information -we need to reproduce your problem. Make sure you include a concise, -but complete code example. Please try to boil your example down to -just the essential code needed to reproduce the problem, and include -an exact recipe of steps needed to expose the bug. Be especially sure -to include any code that appears @emph{before} your bug example, if -you think it might affect our ability to reproduce it. - -Please try to produce the problem in an Emacs instance without any -customizations loaded (i.e. start it with the @samp{-q --no-site-file} -arguments). If it works correctly there, the problem might be caused -by faulty customizations in either your own or your site -configuration. In that case, we'd appreciate it if you isolate the -Emacs Lisp code that triggers the bug and include it in your report. - -@cindex bug report mailing list -Bug reports should be sent to @email{bug-cc-mode@@gnu.org}. You can -also send other questions and suggestions (kudos? @t{;-)} to that -address. It's a mailing list which you can join or browse an archive -of; see the web site at @uref{http://cc-mode.sourceforge.net/} for -further details. - -@cindex announcement mailing list -If you want to get announcements of new @ccmode{} releases, send the -word @emph{subscribe} in the body of a message to -@email{cc-mode-announce-request@@lists.sourceforge.net}. It's possible -to subscribe from the web site too. Announcements will also be posted -to the Usenet newsgroups @code{gnu.emacs.sources}, @code{comp.emacs}, -@code{comp.emacs.xemacs}, @code{comp.lang.c}, @code{comp.lang.c++}, -@code{comp.lang.objective-c}, @code{comp.lang.java.softwaretools}, -@code{comp.lang.idl}, and @code{comp.lang.awk}. -@c There is no newsgroup for Pike. :-( - - -@node GNU Free Documentation License, Command and Function Index, Mailing Lists and Bug Reports, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@c Removed the tentative node "Mode Initialization" from here, 2005/8/27. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Command and Function Index, Variable Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} commands are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex fn - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Variable Index, Concept and Key Index, Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -Since most @ccmode{} variables are prepended with the string -@samp{c-}, each appears under its @code{c-@var{thing}} name and its -@code{@var{thing} (c-)} name. -@iftex -@sp 2 -@end iftex -@printindex vr - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Concept and Key Index, , Variable Index, Top -@comment node-name, next, previous, up -@unnumbered Concept and Key Index -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@printindex cp - - -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@comment Epilogue. -@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! - -@bye - -@ignore - arch-tag: c4cab162-5e57-4366-bdce-4a9db2fc97f0 -@end ignore diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi deleted file mode 100644 index fb1aace9bc6..00000000000 --- a/doc/misc/cl.texi +++ /dev/null @@ -1,5342 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/cl -@settitle Common Lisp Extensions - -@copying -This file documents the GNU Emacs Common Lisp emulation package. - -Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* CL: (cl). Partial Common Lisp support for Emacs Lisp. -@end direntry - -@finalout - -@titlepage -@sp 6 -@center @titlefont{Common Lisp Extensions} -@sp 4 -@center For GNU Emacs Lisp -@sp 1 -@center Version 2.02 -@sp 5 -@center Dave Gillespie -@center daveg@@synaptics.com -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Overview, (dir), (dir) -@chapter Introduction - -@noindent -This document describes a set of Emacs Lisp facilities borrowed from -Common Lisp. All the facilities are described here in detail. While -this document does not assume any prior knowledge of Common Lisp, it -does assume a basic familiarity with Emacs Lisp. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: Installation, usage, etc. -* Program Structure:: Arglists, `eval-when', `defalias' -* Predicates:: `typep' and `equalp' -* Control Structure:: `setf', `do', `loop', etc. -* Macros:: Destructuring, `define-compiler-macro' -* Declarations:: `proclaim', `declare', etc. -* Symbols:: Property lists, `gensym' -* Numbers:: Predicates, functions, random numbers -* Sequences:: Mapping, functions, searching, sorting -* Lists:: `caddr', `sublis', `member*', `assoc*', etc. -* Structures:: `defstruct' -* Assertions:: `check-type', `assert', `ignore-errors'. - -* Efficiency Concerns:: Hints and techniques -* Common Lisp Compatibility:: All known differences with Steele -* Old CL Compatibility:: All known differences with old cl.el -* Porting Common Lisp:: Hints for porting Common Lisp code - -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu - -@node Overview, Program Structure, Top, Top -@ifnottex -@chapter Overview -@end ifnottex - -@noindent -Common Lisp is a huge language, and Common Lisp systems tend to be -massive and extremely complex. Emacs Lisp, by contrast, is rather -minimalist in the choice of Lisp features it offers the programmer. -As Emacs Lisp programmers have grown in number, and the applications -they write have grown more ambitious, it has become clear that Emacs -Lisp could benefit from many of the conveniences of Common Lisp. - -The @dfn{CL} package adds a number of Common Lisp functions and -control structures to Emacs Lisp. While not a 100% complete -implementation of Common Lisp, @dfn{CL} adds enough functionality -to make Emacs Lisp programming significantly more convenient. - -@strong{Please note:} the @dfn{CL} functions are not standard parts of -the Emacs Lisp name space, so it is legitimate for users to define -them with other, conflicting meanings. To avoid conflicting with -those user activities, we have a policy that packages installed in -Emacs must not load @dfn{CL} at run time. (It is ok for them to load -@dfn{CL} at compile time only, with @code{eval-when-compile}, and use -the macros it provides.) If you are writing packages that you plan to -distribute and invite widespread use for, you might want to observe -the same rule. - -Some Common Lisp features have been omitted from this package -for various reasons: - -@itemize @bullet -@item -Some features are too complex or bulky relative to their benefit -to Emacs Lisp programmers. CLOS and Common Lisp streams are fine -examples of this group. - -@item -Other features cannot be implemented without modification to the -Emacs Lisp interpreter itself, such as multiple return values, -lexical scoping, case-insensitive symbols, and complex numbers. -The @dfn{CL} package generally makes no attempt to emulate these -features. - -@item -Some features conflict with existing things in Emacs Lisp. For -example, Emacs' @code{assoc} function is incompatible with the -Common Lisp @code{assoc}. In such cases, this package usually -adds the suffix @samp{*} to the function name of the Common -Lisp version of the function (e.g., @code{assoc*}). -@end itemize - -The package described here was written by Dave Gillespie, -@file{daveg@@synaptics.com}. It is a total rewrite of the original -1986 @file{cl.el} package by Cesar Quiroz. Most features of the -Quiroz package have been retained; any incompatibilities are -noted in the descriptions below. Care has been taken in this -version to ensure that each function is defined efficiently, -concisely, and with minimal impact on the rest of the Emacs -environment. - -@menu -* Usage:: How to use the CL package -* Organization:: The package's five component files -* Installation:: Compiling and installing CL -* Naming Conventions:: Notes on CL function names -@end menu - -@node Usage, Organization, Overview, Overview -@section Usage - -@noindent -Lisp code that uses features from the @dfn{CL} package should -include at the beginning: - -@example -(require 'cl) -@end example - -@noindent -If you want to ensure that the new (Gillespie) version of @dfn{CL} -is the one that is present, add an additional @code{(require 'cl-19)} -call: - -@example -(require 'cl) -(require 'cl-19) -@end example - -@noindent -The second call will fail (with ``@file{cl-19.el} not found'') if -the old @file{cl.el} package was in use. - -It is safe to arrange to load @dfn{CL} at all times, e.g., -in your @file{.emacs} file. But it's a good idea, for portability, -to @code{(require 'cl)} in your code even if you do this. - -@node Organization, Installation, Usage, Overview -@section Organization - -@noindent -The Common Lisp package is organized into four files: - -@table @file -@item cl.el -This is the ``main'' file, which contains basic functions -and information about the package. This file is relatively -compact---about 700 lines. - -@item cl-extra.el -This file contains the larger, more complex or unusual functions. -It is kept separate so that packages which only want to use Common -Lisp fundamentals like the @code{cadr} function won't need to pay -the overhead of loading the more advanced functions. - -@item cl-seq.el -This file contains most of the advanced functions for operating -on sequences or lists, such as @code{delete-if} and @code{assoc*}. - -@item cl-macs.el -This file contains the features of the packages which are macros -instead of functions. Macros expand when the caller is compiled, -not when it is run, so the macros generally only need to be -present when the byte-compiler is running (or when the macros are -used in uncompiled code such as a @file{.emacs} file). Most of -the macros of this package are isolated in @file{cl-macs.el} so -that they won't take up memory unless you are compiling. -@end table - -The file @file{cl.el} includes all necessary @code{autoload} -commands for the functions and macros in the other three files. -All you have to do is @code{(require 'cl)}, and @file{cl.el} -will take care of pulling in the other files when they are -needed. - -There is another file, @file{cl-compat.el}, which defines some -routines from the older @file{cl.el} package that are no longer -present in the new package. This includes internal routines -like @code{setelt} and @code{zip-lists}, deprecated features -like @code{defkeyword}, and an emulation of the old-style -multiple-values feature. @xref{Old CL Compatibility}. - -@node Installation, Naming Conventions, Organization, Overview -@section Installation - -@noindent -Installation of the @dfn{CL} package is simple: Just put the -byte-compiled files @file{cl.elc}, @file{cl-extra.elc}, -@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc} -into a directory on your @code{load-path}. - -There are no special requirements to compile this package: -The files do not have to be loaded before they are compiled, -nor do they need to be compiled in any particular order. - -You may choose to put the files into your main @file{lisp/} -directory, replacing the original @file{cl.el} file there. Or, -you could put them into a directory that comes before @file{lisp/} -on your @code{load-path} so that the old @file{cl.el} is -effectively hidden. - -Also, format the @file{cl.texinfo} file and put the resulting -Info files in the @file{info/} directory or another suitable place. - -You may instead wish to leave this package's components all in -their own directory, and then add this directory to your -@code{load-path} and @code{Info-directory-list}. -Add the directory to the front of the list so the old @dfn{CL} -package and its documentation are hidden. - -@node Naming Conventions, , Installation, Overview -@section Naming Conventions - -@noindent -Except where noted, all functions defined by this package have the -same names and calling conventions as their Common Lisp counterparts. - -Following is a complete list of functions whose names were changed -from Common Lisp, usually to avoid conflicts with Emacs. In each -case, a @samp{*} has been appended to the Common Lisp name to obtain -the Emacs name: - -@example -defun* defsubst* defmacro* function* -member* assoc* rassoc* get* -remove* delete* mapcar* sort* -floor* ceiling* truncate* round* -mod* rem* random* -@end example - -Internal function and variable names in the package are prefixed -by @code{cl-}. Here is a complete list of functions @emph{not} -prefixed by @code{cl-} which were not taken from Common Lisp: - -@example -floatp-safe lexical-let lexical-let* -callf callf2 letf letf* -defsubst* -@end example - -The following simple functions and macros are defined in @file{cl.el}; -they do not cause other components like @file{cl-extra} to be loaded. - -@example -floatp-safe endp -evenp oddp plusp minusp -caaar .. cddddr -list* ldiff rest first .. tenth -copy-list subst mapcar* [2] -adjoin [3] acons pairlis pop [4] -push [4] pushnew [3,4] incf [4] decf [4] -proclaim declaim -@end example - -@noindent -[2] Only for one sequence argument or two list arguments. - -@noindent -[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, -and @code{:key} is not used. - -@noindent -[4] Only when @var{place} is a plain variable name. - -@iftex -@chapno=4 -@end iftex - -@node Program Structure, Predicates, Overview, Top -@chapter Program Structure - -@noindent -This section describes features of the @dfn{CL} package which have to -do with programs as a whole: advanced argument lists for functions, -and the @code{eval-when} construct. - -@menu -* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. -* Time of Evaluation:: The `eval-when' construct. -@end menu - -@iftex -@secno=1 -@end iftex - -@node Argument Lists, Time of Evaluation, Program Structure, Program Structure -@section Argument Lists - -@noindent -Emacs Lisp's notation for argument lists of functions is a subset of -the Common Lisp notation. As well as the familiar @code{&optional} -and @code{&rest} markers, Common Lisp allows you to specify default -values for optional arguments, and it provides the additional markers -@code{&key} and @code{&aux}. - -Since argument parsing is built-in to Emacs, there is no way for -this package to implement Common Lisp argument lists seamlessly. -Instead, this package defines alternates for several Lisp forms -which you must use if you need Common Lisp argument lists. - -@defspec defun* name arglist body... -This form is identical to the regular @code{defun} form, except -that @var{arglist} is allowed to be a full Common Lisp argument -list. Also, the function body is enclosed in an implicit block -called @var{name}; @pxref{Blocks and Exits}. -@end defspec - -@defspec defsubst* name arglist body... -This is just like @code{defun*}, except that the function that -is defined is automatically proclaimed @code{inline}, i.e., -calls to it may be expanded into in-line code by the byte compiler. -This is analogous to the @code{defsubst} form; -@code{defsubst*} uses a different method (compiler macros) which -works in all version of Emacs, and also generates somewhat more -efficient inline expansions. In particular, @code{defsubst*} -arranges for the processing of keyword arguments, default values, -etc., to be done at compile-time whenever possible. -@end defspec - -@defspec defmacro* name arglist body... -This is identical to the regular @code{defmacro} form, -except that @var{arglist} is allowed to be a full Common Lisp -argument list. The @code{&environment} keyword is supported as -described in Steele. The @code{&whole} keyword is supported only -within destructured lists (see below); top-level @code{&whole} -cannot be implemented with the current Emacs Lisp interpreter. -The macro expander body is enclosed in an implicit block called -@var{name}. -@end defspec - -@defspec function* symbol-or-lambda -This is identical to the regular @code{function} form, -except that if the argument is a @code{lambda} form then that -form may use a full Common Lisp argument list. -@end defspec - -Also, all forms (such as @code{defsetf} and @code{flet}) defined -in this package that include @var{arglist}s in their syntax allow -full Common Lisp argument lists. - -Note that it is @emph{not} necessary to use @code{defun*} in -order to have access to most @dfn{CL} features in your function. -These features are always present; @code{defun*}'s only -difference from @code{defun} is its more flexible argument -lists and its implicit block. - -The full form of a Common Lisp argument list is - -@example -(@var{var}... - &optional (@var{var} @var{initform} @var{svar})... - &rest @var{var} - &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... - &aux (@var{var} @var{initform})...) -@end example - -Each of the five argument list sections is optional. The @var{svar}, -@var{initform}, and @var{keyword} parts are optional; if they are -omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. - -The first section consists of zero or more @dfn{required} arguments. -These arguments must always be specified in a call to the function; -there is no difference between Emacs Lisp and Common Lisp as far as -required arguments are concerned. - -The second section consists of @dfn{optional} arguments. These -arguments may be specified in the function call; if they are not, -@var{initform} specifies the default value used for the argument. -(No @var{initform} means to use @code{nil} as the default.) The -@var{initform} is evaluated with the bindings for the preceding -arguments already established; @code{(a &optional (b (1+ a)))} -matches one or two arguments, with the second argument defaulting -to one plus the first argument. If the @var{svar} is specified, -it is an auxiliary variable which is bound to @code{t} if the optional -argument was specified, or to @code{nil} if the argument was omitted. -If you don't use an @var{svar}, then there will be no way for your -function to tell whether it was called with no argument, or with -the default value passed explicitly as an argument. - -The third section consists of a single @dfn{rest} argument. If -more arguments were passed to the function than are accounted for -by the required and optional arguments, those extra arguments are -collected into a list and bound to the ``rest'' argument variable. -Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. -Common Lisp accepts @code{&body} as a synonym for @code{&rest} in -macro contexts; this package accepts it all the time. - -The fourth section consists of @dfn{keyword} arguments. These -are optional arguments which are specified by name rather than -positionally in the argument list. For example, - -@example -(defun* foo (a &optional b &key c d (e 17))) -@end example - -@noindent -defines a function which may be called with one, two, or more -arguments. The first two arguments are bound to @code{a} and -@code{b} in the usual way. The remaining arguments must be -pairs of the form @code{:c}, @code{:d}, or @code{:e} followed -by the value to be bound to the corresponding argument variable. -(Symbols whose names begin with a colon are called @dfn{keywords}, -and they are self-quoting in the same way as @code{nil} and -@code{t}.) - -For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five -arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword -appears more than once in the function call, the first occurrence -takes precedence over the later ones. Note that it is not possible -to specify keyword arguments without specifying the optional -argument @code{b} as well, since @code{(foo 1 :c 2)} would bind -@code{b} to the keyword @code{:c}, then signal an error because -@code{2} is not a valid keyword. - -If a @var{keyword} symbol is explicitly specified in the argument -list as shown in the above diagram, then that keyword will be -used instead of just the variable name prefixed with a colon. -You can specify a @var{keyword} symbol which does not begin with -a colon at all, but such symbols will not be self-quoting; you -will have to quote them explicitly with an apostrophe in the -function call. - -Ordinarily it is an error to pass an unrecognized keyword to -a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask -Lisp to ignore unrecognized keywords, either by adding the -marker @code{&allow-other-keys} after the keyword section -of the argument list, or by specifying an @code{:allow-other-keys} -argument in the call whose value is non-@code{nil}. If the -function uses both @code{&rest} and @code{&key} at the same time, -the ``rest'' argument is bound to the keyword list as it appears -in the call. For example: - -@smallexample -(defun* find-thing (thing &rest rest &key need &allow-other-keys) - (or (apply 'member* thing thing-list :allow-other-keys t rest) - (if need (error "Thing not found")))) -@end smallexample - -@noindent -This function takes a @code{:need} keyword argument, but also -accepts other keyword arguments which are passed on to the -@code{member*} function. @code{allow-other-keys} is used to -keep both @code{find-thing} and @code{member*} from complaining -about each others' keywords in the arguments. - -The fifth section of the argument list consists of @dfn{auxiliary -variables}. These are not really arguments at all, but simply -variables which are bound to @code{nil} or to the specified -@var{initforms} during execution of the function. There is no -difference between the following two functions, except for a -matter of stylistic taste: - -@example -(defun* foo (a b &aux (c (+ a b)) d) - @var{body}) - -(defun* foo (a b) - (let ((c (+ a b)) d) - @var{body})) -@end example - -Argument lists support @dfn{destructuring}. In Common Lisp, -destructuring is only allowed with @code{defmacro}; this package -allows it with @code{defun*} and other argument lists as well. -In destructuring, any argument variable (@var{var} in the above -diagram) can be replaced by a list of variables, or more generally, -a recursive argument list. The corresponding argument value must -be a list whose elements match this recursive argument list. -For example: - -@example -(defmacro* dolist ((var listform &optional resultform) - &rest body) - ...) -@end example - -This says that the first argument of @code{dolist} must be a list -of two or three items; if there are other arguments as well as this -list, they are stored in @code{body}. All features allowed in -regular argument lists are allowed in these recursive argument lists. -In addition, the clause @samp{&whole @var{var}} is allowed at the -front of a recursive argument list. It binds @var{var} to the -whole list being matched; thus @code{(&whole all a b)} matches -a list of two things, with @code{a} bound to the first thing, -@code{b} bound to the second thing, and @code{all} bound to the -list itself. (Common Lisp allows @code{&whole} in top-level -@code{defmacro} argument lists as well, but Emacs Lisp does not -support this usage.) - -One last feature of destructuring is that the argument list may be -dotted, so that the argument list @code{(a b . c)} is functionally -equivalent to @code{(a b &rest c)}. - -If the optimization quality @code{safety} is set to 0 -(@pxref{Declarations}), error checking for wrong number of -arguments and invalid keyword arguments is disabled. By default, -argument lists are rigorously checked. - -@node Time of Evaluation, , Argument Lists, Program Structure -@section Time of Evaluation - -@noindent -Normally, the byte-compiler does not actually execute the forms in -a file it compiles. For example, if a file contains @code{(setq foo t)}, -the act of compiling it will not actually set @code{foo} to @code{t}. -This is true even if the @code{setq} was a top-level form (i.e., not -enclosed in a @code{defun} or other form). Sometimes, though, you -would like to have certain top-level forms evaluated at compile-time. -For example, the compiler effectively evaluates @code{defmacro} forms -at compile-time so that later parts of the file can refer to the -macros that are defined. - -@defspec eval-when (situations...) forms... -This form controls when the body @var{forms} are evaluated. -The @var{situations} list may contain any set of the symbols -@code{compile}, @code{load}, and @code{eval} (or their long-winded -ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, -and @code{:execute}). - -The @code{eval-when} form is handled differently depending on -whether or not it is being compiled as a top-level form. -Specifically, it gets special treatment if it is being compiled -by a command such as @code{byte-compile-file} which compiles files -or buffers of code, and it appears either literally at the -top level of the file or inside a top-level @code{progn}. - -For compiled top-level @code{eval-when}s, the body @var{forms} are -executed at compile-time if @code{compile} is in the @var{situations} -list, and the @var{forms} are written out to the file (to be executed -at load-time) if @code{load} is in the @var{situations} list. - -For non-compiled-top-level forms, only the @code{eval} situation is -relevant. (This includes forms executed by the interpreter, forms -compiled with @code{byte-compile} rather than @code{byte-compile-file}, -and non-top-level forms.) The @code{eval-when} acts like a -@code{progn} if @code{eval} is specified, and like @code{nil} -(ignoring the body @var{forms}) if not. - -The rules become more subtle when @code{eval-when}s are nested; -consult Steele (second edition) for the gruesome details (and -some gruesome examples). - -Some simple examples: - -@example -;; Top-level forms in foo.el: -(eval-when (compile) (setq foo1 'bar)) -(eval-when (load) (setq foo2 'bar)) -(eval-when (compile load) (setq foo3 'bar)) -(eval-when (eval) (setq foo4 'bar)) -(eval-when (eval compile) (setq foo5 'bar)) -(eval-when (eval load) (setq foo6 'bar)) -(eval-when (eval compile load) (setq foo7 'bar)) -@end example - -When @file{foo.el} is compiled, these variables will be set during -the compilation itself: - -@example -foo1 foo3 foo5 foo7 ; `compile' -@end example - -When @file{foo.elc} is loaded, these variables will be set: - -@example -foo2 foo3 foo6 foo7 ; `load' -@end example - -And if @file{foo.el} is loaded uncompiled, these variables will -be set: - -@example -foo4 foo5 foo6 foo7 ; `eval' -@end example - -If these seven @code{eval-when}s had been, say, inside a @code{defun}, -then the first three would have been equivalent to @code{nil} and the -last four would have been equivalent to the corresponding @code{setq}s. - -Note that @code{(eval-when (load eval) @dots{})} is equivalent -to @code{(progn @dots{})} in all contexts. The compiler treats -certain top-level forms, like @code{defmacro} (sort-of) and -@code{require}, as if they were wrapped in @code{(eval-when -(compile load eval) @dots{})}. -@end defspec - -Emacs includes two special forms related to @code{eval-when}. -One of these, @code{eval-when-compile}, is not quite equivalent to -any @code{eval-when} construct and is described below. - -The other form, @code{(eval-and-compile @dots{})}, is exactly -equivalent to @samp{(eval-when (compile load eval) @dots{})} and -so is not itself defined by this package. - -@defspec eval-when-compile forms... -The @var{forms} are evaluated at compile-time; at execution time, -this form acts like a quoted constant of the resulting value. Used -at top-level, @code{eval-when-compile} is just like @samp{eval-when -(compile eval)}. In other contexts, @code{eval-when-compile} -allows code to be evaluated once at compile-time for efficiency -or other reasons. - -This form is similar to the @samp{#.} syntax of true Common Lisp. -@end defspec - -@defspec load-time-value form -The @var{form} is evaluated at load-time; at execution time, -this form acts like a quoted constant of the resulting value. - -Early Common Lisp had a @samp{#,} syntax that was similar to -this, but ANSI Common Lisp replaced it with @code{load-time-value} -and gave it more well-defined semantics. - -In a compiled file, @code{load-time-value} arranges for @var{form} -to be evaluated when the @file{.elc} file is loaded and then used -as if it were a quoted constant. In code compiled by -@code{byte-compile} rather than @code{byte-compile-file}, the -effect is identical to @code{eval-when-compile}. In uncompiled -code, both @code{eval-when-compile} and @code{load-time-value} -act exactly like @code{progn}. - -@example -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - (eval-when-compile (current-time-string)) - ;; or '#.(current-time-string) in real Common Lisp - ", and loaded on: " - (load-time-value (current-time-string)))) -@end example - -@noindent -Byte-compiled, the above defun will result in the following code -(or its compiled equivalent, of course) in the @file{.elc} file: - -@example -(setq --temp-- (current-time-string)) -(defun report () - (insert "This function was executed on: " - (current-time-string) - ", compiled on: " - '"Wed Jun 23 18:33:43 1993" - ", and loaded on: " - --temp--)) -@end example -@end defspec - -@node Predicates, Control Structure, Program Structure, Top -@chapter Predicates - -@noindent -This section describes functions for testing whether various -facts are true or false. - -@menu -* Type Predicates:: `typep', `deftype', and `coerce' -* Equality Predicates:: `equalp' -@end menu - -@node Type Predicates, Equality Predicates, Predicates, Predicates -@section Type Predicates - -@noindent -The @dfn{CL} package defines a version of the Common Lisp @code{typep} -predicate. - -@defun typep object type -Check if @var{object} is of type @var{type}, where @var{type} is a -(quoted) type name of the sort used by Common Lisp. For example, -@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. -@end defun - -The @var{type} argument to the above function is either a symbol -or a list beginning with a symbol. - -@itemize @bullet -@item -If the type name is a symbol, Emacs appends @samp{-p} to the -symbol name to form the name of a predicate function for testing -the type. (Built-in predicates whose names end in @samp{p} rather -than @samp{-p} are used when appropriate.) - -@item -The type symbol @code{t} stands for the union of all types. -@code{(typep @var{object} t)} is always true. Likewise, the -type symbol @code{nil} stands for nothing at all, and -@code{(typep @var{object} nil)} is always false. - -@item -The type symbol @code{null} represents the symbol @code{nil}. -Thus @code{(typep @var{object} 'null)} is equivalent to -@code{(null @var{object})}. - -@item -The type symbol @code{atom} represents all objects that are not cons -cells. Thus @code{(typep @var{object} 'atom)} is equivalent to -@code{(atom @var{object})}. - -@item -The type symbol @code{real} is a synonym for @code{number}, and -@code{fixnum} is a synonym for @code{integer}. - -@item -The type symbols @code{character} and @code{string-char} match -integers in the range from 0 to 255. - -@item -The type symbol @code{float} uses the @code{floatp-safe} predicate -defined by this package rather than @code{floatp}, so it will work -correctly even in Emacs versions without floating-point support. - -@item -The type list @code{(integer @var{low} @var{high})} represents all -integers between @var{low} and @var{high}, inclusive. Either bound -may be a list of a single integer to specify an exclusive limit, -or a @code{*} to specify no limit. The type @code{(integer * *)} -is thus equivalent to @code{integer}. - -@item -Likewise, lists beginning with @code{float}, @code{real}, or -@code{number} represent numbers of that type falling in a particular -range. - -@item -Lists beginning with @code{and}, @code{or}, and @code{not} form -combinations of types. For example, @code{(or integer (float 0 *))} -represents all objects that are integers or non-negative floats. - -@item -Lists beginning with @code{member} or @code{member*} represent -objects @code{eql} to any of the following values. For example, -@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, -and @code{(member nil)} is equivalent to @code{null}. - -@item -Lists of the form @code{(satisfies @var{predicate})} represent -all objects for which @var{predicate} returns true when called -with that object as an argument. -@end itemize - -The following function and macro (not technically predicates) are -related to @code{typep}. - -@defun coerce object type -This function attempts to convert @var{object} to the specified -@var{type}. If @var{object} is already of that type as determined by -@code{typep}, it is simply returned. Otherwise, certain types of -conversions will be made: If @var{type} is any sequence type -(@code{string}, @code{list}, etc.) then @var{object} will be -converted to that type if possible. If @var{type} is -@code{character}, then strings of length one and symbols with -one-character names can be coerced. If @var{type} is @code{float}, -then integers can be coerced in versions of Emacs that support -floats. In all other circumstances, @code{coerce} signals an -error. -@end defun - -@defspec deftype name arglist forms... -This macro defines a new type called @var{name}. It is similar -to @code{defmacro} in many ways; when @var{name} is encountered -as a type name, the body @var{forms} are evaluated and should -return a type specifier that is equivalent to the type. The -@var{arglist} is a Common Lisp argument list of the sort accepted -by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} -is expanded by calling the expander with those arguments; the type -symbol @samp{@var{name}} is expanded by calling the expander with -no arguments. The @var{arglist} is processed the same as for -@code{defmacro*} except that optional arguments without explicit -defaults use @code{*} instead of @code{nil} as the ``default'' -default. Some examples: - -@example -(deftype null () '(satisfies null)) ; predefined -(deftype list () '(or null cons)) ; predefined -(deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) -(unsigned-byte 8) @equiv{} (integer 0 255) -(unsigned-byte) @equiv{} (integer 0 *) -unsigned-byte @equiv{} (integer 0 *) -@end example - -@noindent -The last example shows how the Common Lisp @code{unsigned-byte} -type specifier could be implemented if desired; this package does -not implement @code{unsigned-byte} by default. -@end defspec - -The @code{typecase} and @code{check-type} macros also use type -names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, -@code{concatenate}, and @code{merge} functions take type-name -arguments to specify the type of sequence to return. @xref{Sequences}. - -@node Equality Predicates, , Type Predicates, Predicates -@section Equality Predicates - -@noindent -This package defines the Common Lisp predicate @code{equalp}. - -@defun equalp a b -This function is a more flexible version of @code{equal}. In -particular, it compares strings case-insensitively, and it compares -numbers without regard to type (so that @code{(equalp 3 3.0)} is -true). Vectors and conses are compared recursively. All other -objects are compared as if by @code{equal}. - -This function differs from Common Lisp @code{equalp} in several -respects. First, Common Lisp's @code{equalp} also compares -@emph{characters} case-insensitively, which would be impractical -in this package since Emacs does not distinguish between integers -and characters. In keeping with the idea that strings are less -vector-like in Emacs Lisp, this package's @code{equalp} also will -not compare strings against vectors of integers. -@end defun - -Also note that the Common Lisp functions @code{member} and @code{assoc} -use @code{eql} to compare elements, whereas Emacs Lisp follows the -MacLisp tradition and uses @code{equal} for these two functions. -In Emacs, use @code{member*} and @code{assoc*} to get functions -which use @code{eql} for comparisons. - -@node Control Structure, Macros, Predicates, Top -@chapter Control Structure - -@noindent -The features described in the following sections implement -various advanced control structures, including the powerful -@code{setf} facility and a number of looping and conditional -constructs. - -@menu -* Assignment:: The `psetq' form -* Generalized Variables:: `setf', `incf', `push', etc. -* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' -* Conditionals:: `case', `typecase' -* Blocks and Exits:: `block', `return', `return-from' -* Iteration:: `do', `dotimes', `dolist', `do-symbols' -* Loop Facility:: The Common Lisp `loop' macro -* Multiple Values:: `values', `multiple-value-bind', etc. -@end menu - -@node Assignment, Generalized Variables, Control Structure, Control Structure -@section Assignment - -@noindent -The @code{psetq} form is just like @code{setq}, except that multiple -assignments are done in parallel rather than sequentially. - -@defspec psetq [symbol form]@dots{} -This special form (actually a macro) is used to assign to several -variables simultaneously. Given only one @var{symbol} and @var{form}, -it has the same effect as @code{setq}. Given several @var{symbol} -and @var{form} pairs, it evaluates all the @var{form}s in advance -and then stores the corresponding variables afterwards. - -@example -(setq x 2 y 3) -(setq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed after @code{x} was set.} - @result{} 15 -(setq x 2 y 3) -(psetq x (+ x y) y (* x y)) -x - @result{} 5 -y ; @r{@code{y} was computed before @code{x} was set.} - @result{} 6 -@end example - -The simplest use of @code{psetq} is @code{(psetq x y y x)}, which -exchanges the values of two variables. (The @code{rotatef} form -provides an even more convenient way to swap two variables; -@pxref{Modify Macros}.) - -@code{psetq} always returns @code{nil}. -@end defspec - -@node Generalized Variables, Variable Bindings, Assignment, Control Structure -@section Generalized Variables - -@noindent -A ``generalized variable'' or ``place form'' is one of the many places -in Lisp memory where values can be stored. The simplest place form is -a regular Lisp variable. But the cars and cdrs of lists, elements -of arrays, properties of symbols, and many other locations are also -places where Lisp values are stored. - -The @code{setf} form is like @code{setq}, except that it accepts -arbitrary place forms on the left side rather than just -symbols. For example, @code{(setf (car a) b)} sets the car of -@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} -but without having to remember two separate functions for setting -and accessing every type of place. - -Generalized variables are analogous to ``lvalues'' in the C -language, where @samp{x = a[i]} gets an element from an array -and @samp{a[i] = x} stores an element using the same notation. -Just as certain forms like @code{a[i]} can be lvalues in C, there -is a set of forms that can be generalized variables in Lisp. - -@menu -* Basic Setf:: `setf' and place forms -* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. -* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' -@end menu - -@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables -@subsection Basic Setf - -@noindent -The @code{setf} macro is the most basic way to operate on generalized -variables. - -@defspec setf [place form]@dots{} -This macro evaluates @var{form} and stores it in @var{place}, which -must be a valid generalized variable form. If there are several -@var{place} and @var{form} pairs, the assignments are done sequentially -just as with @code{setq}. @code{setf} returns the value of the last -@var{form}. - -The following Lisp forms will work as generalized variables, and -so may appear in the @var{place} argument of @code{setf}: - -@itemize @bullet -@item -A symbol naming a variable. In other words, @code{(setf x y)} is -exactly equivalent to @code{(setq x y)}, and @code{setq} itself is -strictly speaking redundant now that @code{setf} exists. Many -programmers continue to prefer @code{setq} for setting simple -variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, -so there is no performance penalty for using it in compiled code. - -@item -A call to any of the following Lisp functions: - -@smallexample -car cdr caar .. cddddr -nth rest first .. tenth -aref elt nthcdr -symbol-function symbol-value symbol-plist -get get* getf -gethash subseq -@end smallexample - -@noindent -Note that for @code{nthcdr} and @code{getf}, the list argument -of the function must itself be a valid @var{place} form. For -example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself -to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} -place can be used to insert or delete at any position in a list. -The use of @code{nthcdr} as a @var{place} form is an extension -to standard Common Lisp. - -@item -The following Emacs-specific functions are also @code{setf}-able. - -@smallexample -buffer-file-name marker-position -buffer-modified-p match-data -buffer-name mouse-position -buffer-string overlay-end -buffer-substring overlay-get -current-buffer overlay-start -current-case-table point -current-column point-marker -current-global-map point-max -current-input-mode point-min -current-local-map process-buffer -current-window-configuration process-filter -default-file-modes process-sentinel -default-value read-mouse-position -documentation-property screen-height -extent-data screen-menubar -extent-end-position screen-width -extent-start-position selected-window -face-background selected-screen -face-background-pixmap selected-frame -face-font standard-case-table -face-foreground syntax-table -face-underline-p window-buffer -file-modes window-dedicated-p -frame-height window-display-table -frame-parameters window-height -frame-visible-p window-hscroll -frame-width window-point -get-register window-start -getenv window-width -global-key-binding x-get-cut-buffer -keymap-parent x-get-cutbuffer -local-key-binding x-get-secondary-selection -mark x-get-selection -mark-marker -@end smallexample - -Most of these have directly corresponding ``set'' functions, like -@code{use-local-map} for @code{current-local-map}, or @code{goto-char} -for @code{point}. A few, like @code{point-min}, expand to longer -sequences of code when they are @code{setf}'d (@code{(narrow-to-region -x (point-max))} in this case). - -@item -A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, -where @var{subplace} is itself a valid generalized variable whose -current value is a string, and where the value stored is also a -string. The new string is spliced into the specified part of the -destination string. For example: - -@example -(setq a (list "hello" "world")) - @result{} ("hello" "world") -(cadr a) - @result{} "world" -(substring (cadr a) 2 4) - @result{} "rl" -(setf (substring (cadr a) 2 4) "o") - @result{} "o" -(cadr a) - @result{} "wood" -a - @result{} ("hello" "wood") -@end example - -The generalized variable @code{buffer-substring}, listed above, -also works in this way by replacing a portion of the current buffer. - -@item -A call of the form @code{(apply '@var{func} @dots{})} or -@code{(apply (function @var{func}) @dots{})}, where @var{func} -is a @code{setf}-able function whose store function is ``suitable'' -in the sense described in Steele's book; since none of the standard -Emacs place functions are suitable in this sense, this feature is -only interesting when used with places you define yourself with -@code{define-setf-method} or the long form of @code{defsetf}. - -@item -A macro call, in which case the macro is expanded and @code{setf} -is applied to the resulting form. - -@item -Any form for which a @code{defsetf} or @code{define-setf-method} -has been made. -@end itemize - -Using any forms other than these in the @var{place} argument to -@code{setf} will signal an error. - -The @code{setf} macro takes care to evaluate all subforms in -the proper left-to-right order; for example, - -@example -(setf (aref vec (incf i)) i) -@end example - -@noindent -looks like it will evaluate @code{(incf i)} exactly once, before the -following access to @code{i}; the @code{setf} expander will insert -temporary variables as necessary to ensure that it does in fact work -this way no matter what setf-method is defined for @code{aref}. -(In this case, @code{aset} would be used and no such steps would -be necessary since @code{aset} takes its arguments in a convenient -order.) - -However, if the @var{place} form is a macro which explicitly -evaluates its arguments in an unusual order, this unusual order -will be preserved. Adapting an example from Steele, given - -@example -(defmacro wrong-order (x y) (list 'aref y x)) -@end example - -@noindent -the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will -evaluate @var{b} first, then @var{a}, just as in an actual call -to @code{wrong-order}. -@end defspec - -@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables -@subsection Modify Macros - -@noindent -This package defines a number of other macros besides @code{setf} -that operate on generalized variables. Many are interesting and -useful even when the @var{place} is just a variable name. - -@defspec psetf [place form]@dots{} -This macro is to @code{setf} what @code{psetq} is to @code{setq}: -When several @var{place}s and @var{form}s are involved, the -assignments take place in parallel rather than sequentially. -Specifically, all subforms are evaluated from left to right, then -all the assignments are done (in an undefined order). -@end defspec - -@defspec incf place &optional x -This macro increments the number stored in @var{place} by one, or -by @var{x} if specified. The incremented value is returned. For -example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and -@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. - -Once again, care is taken to preserve the ``apparent'' order of -evaluation. For example, - -@example -(incf (aref vec (incf i))) -@end example - -@noindent -appears to increment @code{i} once, then increment the element of -@code{vec} addressed by @code{i}; this is indeed exactly what it -does, which means the above form is @emph{not} equivalent to the -``obvious'' expansion, - -@example -(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! -@end example - -@noindent -but rather to something more like - -@example -(let ((temp (incf i))) - (setf (aref vec temp) (1+ (aref vec temp)))) -@end example - -@noindent -Again, all of this is taken care of automatically by @code{incf} and -the other generalized-variable macros. - -As a more Emacs-specific example of @code{incf}, the expression -@code{(incf (point) @var{n})} is essentially equivalent to -@code{(forward-char @var{n})}. -@end defspec - -@defspec decf place &optional x -This macro decrements the number stored in @var{place} by one, or -by @var{x} if specified. -@end defspec - -@defspec pop place -This macro removes and returns the first element of the list stored -in @var{place}. It is analogous to @code{(prog1 (car @var{place}) -(setf @var{place} (cdr @var{place})))}, except that it takes care -to evaluate all subforms only once. -@end defspec - -@defspec push x place -This macro inserts @var{x} at the front of the list stored in -@var{place}. It is analogous to @code{(setf @var{place} (cons -@var{x} @var{place}))}, except for evaluation of the subforms. -@end defspec - -@defspec pushnew x place @t{&key :test :test-not :key} -This macro inserts @var{x} at the front of the list stored in -@var{place}, but only if @var{x} was not @code{eql} to any -existing element of the list. The optional keyword arguments -are interpreted in the same way as for @code{adjoin}. -@xref{Lists as Sets}. -@end defspec - -@defspec shiftf place@dots{} newvalue -This macro shifts the @var{place}s left by one, shifting in the -value of @var{newvalue} (which may be any Lisp expression, not just -a generalized variable), and returning the value shifted out of -the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} -@var{d})} is equivalent to - -@example -(prog1 - @var{a} - (psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d})) -@end example - -@noindent -except that the subforms of @var{a}, @var{b}, and @var{c} are actually -evaluated only once each and in the apparent order. -@end defspec - -@defspec rotatef place@dots{} -This macro rotates the @var{place}s left by one in circular fashion. -Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to - -@example -(psetf @var{a} @var{b} - @var{b} @var{c} - @var{c} @var{d} - @var{d} @var{a}) -@end example - -@noindent -except for the evaluation of subforms. @code{rotatef} always -returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} -conveniently exchanges @var{a} and @var{b}. -@end defspec - -The following macros were invented for this package; they have no -analogues in Common Lisp. - -@defspec letf (bindings@dots{}) forms@dots{} -This macro is analogous to @code{let}, but for generalized variables -rather than just symbols. Each @var{binding} should be of the form -@code{(@var{place} @var{value})}; the original contents of the -@var{place}s are saved, the @var{value}s are stored in them, and -then the body @var{form}s are executed. Afterwards, the @var{places} -are set back to their original saved contents. This cleanup happens -even if the @var{form}s exit irregularly due to a @code{throw} or an -error. - -For example, - -@example -(letf (((point) (point-min)) - (a 17)) - ...) -@end example - -@noindent -moves ``point'' in the current buffer to the beginning of the buffer, -and also binds @code{a} to 17 (as if by a normal @code{let}, since -@code{a} is just a regular variable). After the body exits, @code{a} -is set back to its original value and point is moved back to its -original position. - -Note that @code{letf} on @code{(point)} is not quite like a -@code{save-excursion}, as the latter effectively saves a marker -which tracks insertions and deletions in the buffer. Actually, -a @code{letf} of @code{(point-marker)} is much closer to this -behavior. (@code{point} and @code{point-marker} are equivalent -as @code{setf} places; each will accept either an integer or a -marker as the stored value.) - -Since generalized variables look like lists, @code{let}'s shorthand -of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would -be ambiguous in @code{letf} and is not allowed. - -However, a @var{binding} specifier may be a one-element list -@samp{(@var{place})}, which is similar to @samp{(@var{place} -@var{place})}. In other words, the @var{place} is not disturbed -on entry to the body, and the only effect of the @code{letf} is -to restore the original value of @var{place} afterwards. (The -redundant access-and-store suggested by the @code{(@var{place} -@var{place})} example does not actually occur.) - -In most cases, the @var{place} must have a well-defined value on -entry to the @code{letf} form. The only exceptions are plain -variables and calls to @code{symbol-value} and @code{symbol-function}. -If the symbol is not bound on entry, it is simply made unbound by -@code{makunbound} or @code{fmakunbound} on exit. -@end defspec - -@defspec letf* (bindings@dots{}) forms@dots{} -This macro is to @code{letf} what @code{let*} is to @code{let}: -It does the bindings in sequential rather than parallel order. -@end defspec - -@defspec callf @var{function} @var{place} @var{args}@dots{} -This is the ``generic'' modify macro. It calls @var{function}, -which should be an unquoted function name, macro name, or lambda. -It passes @var{place} and @var{args} as arguments, and assigns the -result back to @var{place}. For example, @code{(incf @var{place} -@var{n})} is the same as @code{(callf + @var{place} @var{n})}. -Some more examples: - -@example -(callf abs my-number) -(callf concat (buffer-name) "<" (int-to-string n) ">") -(callf union happy-people (list joe bob) :test 'same-person) -@end example - -@xref{Customizing Setf}, for @code{define-modify-macro}, a way -to create even more concise notations for modify macros. Note -again that @code{callf} is an extension to standard Common Lisp. -@end defspec - -@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} -This macro is like @code{callf}, except that @var{place} is -the @emph{second} argument of @var{function} rather than the -first. For example, @code{(push @var{x} @var{place})} is -equivalent to @code{(callf2 cons @var{x} @var{place})}. -@end defspec - -The @code{callf} and @code{callf2} macros serve as building -blocks for other macros like @code{incf}, @code{pushnew}, and -@code{define-modify-macro}. The @code{letf} and @code{letf*} -macros are used in the processing of symbol macros; -@pxref{Macro Bindings}. - -@node Customizing Setf, , Modify Macros, Generalized Variables -@subsection Customizing Setf - -@noindent -Common Lisp defines three macros, @code{define-modify-macro}, -@code{defsetf}, and @code{define-setf-method}, that allow the -user to extend generalized variables in various ways. - -@defspec define-modify-macro name arglist function [doc-string] -This macro defines a ``read-modify-write'' macro similar to -@code{incf} and @code{decf}. The macro @var{name} is defined -to take a @var{place} argument followed by additional arguments -described by @var{arglist}. The call - -@example -(@var{name} @var{place} @var{args}...) -@end example - -@noindent -will be expanded to - -@example -(callf @var{func} @var{place} @var{args}...) -@end example - -@noindent -which in turn is roughly equivalent to - -@example -(setf @var{place} (@var{func} @var{place} @var{args}...)) -@end example - -For example: - -@example -(define-modify-macro incf (&optional (n 1)) +) -(define-modify-macro concatf (&rest args) concat) -@end example - -Note that @code{&key} is not allowed in @var{arglist}, but -@code{&rest} is sufficient to pass keywords on to the function. - -Most of the modify macros defined by Common Lisp do not exactly -follow the pattern of @code{define-modify-macro}. For example, -@code{push} takes its arguments in the wrong order, and @code{pop} -is completely irregular. You can define these macros ``by hand'' -using @code{get-setf-method}, or consult the source file -@file{cl-macs.el} to see how to use the internal @code{setf} -building blocks. -@end defspec - -@defspec defsetf access-fn update-fn -This is the simpler of two @code{defsetf} forms. Where -@var{access-fn} is the name of a function which accesses a place, -this declares @var{update-fn} to be the corresponding store -function. From now on, - -@example -(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) -@end example - -@noindent -will be expanded to - -@example -(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) -@end example - -@noindent -The @var{update-fn} is required to be either a true function, or -a macro which evaluates its arguments in a function-like way. Also, -the @var{update-fn} is expected to return @var{value} as its result. -Otherwise, the above expansion would not obey the rules for the way -@code{setf} is supposed to behave. - -As a special (non-Common-Lisp) extension, a third argument of @code{t} -to @code{defsetf} says that the @code{update-fn}'s return value is -not suitable, so that the above @code{setf} should be expanded to -something more like - -@example -(let ((temp @var{value})) - (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) - temp) -@end example - -Some examples of the use of @code{defsetf}, drawn from the standard -suite of setf methods, are: - -@example -(defsetf car setcar) -(defsetf symbol-value set) -(defsetf buffer-name rename-buffer t) -@end example -@end defspec - -@defspec defsetf access-fn arglist (store-var) forms@dots{} -This is the second, more complex, form of @code{defsetf}. It is -rather like @code{defmacro} except for the additional @var{store-var} -argument. The @var{forms} should return a Lisp form which stores -the value of @var{store-var} into the generalized variable formed -by a call to @var{access-fn} with arguments described by @var{arglist}. -The @var{forms} may begin with a string which documents the @code{setf} -method (analogous to the doc string that appears at the front of a -function). - -For example, the simple form of @code{defsetf} is shorthand for - -@example -(defsetf @var{access-fn} (&rest args) (store) - (append '(@var{update-fn}) args (list store))) -@end example - -The Lisp form that is returned can access the arguments from -@var{arglist} and @var{store-var} in an unrestricted fashion; -macros like @code{setf} and @code{incf} which invoke this -setf-method will insert temporary variables as needed to make -sure the apparent order of evaluation is preserved. - -Another example drawn from the standard package: - -@example -(defsetf nth (n x) (store) - (list 'setcar (list 'nthcdr n x) store)) -@end example -@end defspec - -@defspec define-setf-method access-fn arglist forms@dots{} -This is the most general way to create new place forms. When -a @code{setf} to @var{access-fn} with arguments described by -@var{arglist} is expanded, the @var{forms} are evaluated and -must return a list of five items: - -@enumerate -@item -A list of @dfn{temporary variables}. - -@item -A list of @dfn{value forms} corresponding to the temporary variables -above. The temporary variables will be bound to these value forms -as the first step of any operation on the generalized variable. - -@item -A list of exactly one @dfn{store variable} (generally obtained -from a call to @code{gensym}). - -@item -A Lisp form which stores the contents of the store variable into -the generalized variable, assuming the temporaries have been -bound as described above. - -@item -A Lisp form which accesses the contents of the generalized variable, -assuming the temporaries have been bound. -@end enumerate - -This is exactly like the Common Lisp macro of the same name, -except that the method returns a list of five values rather -than the five values themselves, since Emacs Lisp does not -support Common Lisp's notion of multiple return values. - -Once again, the @var{forms} may begin with a documentation string. - -A setf-method should be maximally conservative with regard to -temporary variables. In the setf-methods generated by -@code{defsetf}, the second return value is simply the list of -arguments in the place form, and the first return value is a -list of a corresponding number of temporary variables generated -by @code{gensym}. Macros like @code{setf} and @code{incf} which -use this setf-method will optimize away most temporaries that -turn out to be unnecessary, so there is little reason for the -setf-method itself to optimize. -@end defspec - -@defun get-setf-method place &optional env -This function returns the setf-method for @var{place}, by -invoking the definition previously recorded by @code{defsetf} -or @code{define-setf-method}. The result is a list of five -values as described above. You can use this function to build -your own @code{incf}-like modify macros. (Actually, it is -better to use the internal functions @code{cl-setf-do-modify} -and @code{cl-setf-do-store}, which are a bit easier to use and -which also do a number of optimizations; consult the source -code for the @code{incf} function for a simple example.) - -The argument @var{env} specifies the ``environment'' to be -passed on to @code{macroexpand} if @code{get-setf-method} should -need to expand a macro in @var{place}. It should come from -an @code{&environment} argument to the macro or setf-method -that called @code{get-setf-method}. - -See also the source code for the setf-methods for @code{apply} -and @code{substring}, each of which works by calling -@code{get-setf-method} on a simpler case, then massaging -the result in various ways. -@end defun - -Modern Common Lisp defines a second, independent way to specify -the @code{setf} behavior of a function, namely ``@code{setf} -functions'' whose names are lists @code{(setf @var{name})} -rather than symbols. For example, @code{(defun (setf foo) @dots{})} -defines the function that is used when @code{setf} is applied to -@code{foo}. This package does not currently support @code{setf} -functions. In particular, it is a compile-time error to use -@code{setf} on a form which has not already been @code{defsetf}'d -or otherwise declared; in newer Common Lisps, this would not be -an error since the function @code{(setf @var{func})} might be -defined later. - -@iftex -@secno=4 -@end iftex - -@node Variable Bindings, Conditionals, Generalized Variables, Control Structure -@section Variable Bindings - -@noindent -These Lisp forms make bindings to variables and function names, -analogous to Lisp's built-in @code{let} form. - -@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which -are also related to variable bindings. - -@menu -* Dynamic Bindings:: The `progv' form -* Lexical Bindings:: `lexical-let' and lexical closures -* Function Bindings:: `flet' and `labels' -* Macro Bindings:: `macrolet' and `symbol-macrolet' -@end menu - -@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings -@subsection Dynamic Bindings - -@noindent -The standard @code{let} form binds variables whose names are known -at compile-time. The @code{progv} form provides an easy way to -bind variables whose names are computed at run-time. - -@defspec progv symbols values forms@dots{} -This form establishes @code{let}-style variable bindings on a -set of variables computed at run-time. The expressions -@var{symbols} and @var{values} are evaluated, and must return lists -of symbols and values, respectively. The symbols are bound to the -corresponding values for the duration of the body @var{form}s. -If @var{values} is shorter than @var{symbols}, the last few symbols -are made unbound (as if by @code{makunbound}) inside the body. -If @var{symbols} is shorter than @var{values}, the excess values -are ignored. -@end defspec - -@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings -@subsection Lexical Bindings - -@noindent -The @dfn{CL} package defines the following macro which -more closely follows the Common Lisp @code{let} form: - -@defspec lexical-let (bindings@dots{}) forms@dots{} -This form is exactly like @code{let} except that the bindings it -establishes are purely lexical. Lexical bindings are similar to -local variables in a language like C: Only the code physically -within the body of the @code{lexical-let} (after macro expansion) -may refer to the bound variables. - -@example -(setq a 5) -(defun foo (b) (+ a b)) -(let ((a 2)) (foo a)) - @result{} 4 -(lexical-let ((a 2)) (foo a)) - @result{} 7 -@end example - -@noindent -In this example, a regular @code{let} binding of @code{a} actually -makes a temporary change to the global variable @code{a}, so @code{foo} -is able to see the binding of @code{a} to 2. But @code{lexical-let} -actually creates a distinct local variable @code{a} for use within its -body, without any effect on the global variable of the same name. - -The most important use of lexical bindings is to create @dfn{closures}. -A closure is a function object that refers to an outside lexical -variable. For example: - -@example -(defun make-adder (n) - (lexical-let ((n n)) - (function (lambda (m) (+ n m))))) -(setq add17 (make-adder 17)) -(funcall add17 4) - @result{} 21 -@end example - -@noindent -The call @code{(make-adder 17)} returns a function object which adds -17 to its argument. If @code{let} had been used instead of -@code{lexical-let}, the function object would have referred to the -global @code{n}, which would have been bound to 17 only during the -call to @code{make-adder} itself. - -@example -(defun make-counter () - (lexical-let ((n 0)) - (function* (lambda (&optional (m 1)) (incf n m))))) -(setq count-1 (make-counter)) -(funcall count-1 3) - @result{} 3 -(funcall count-1 14) - @result{} 17 -(setq count-2 (make-counter)) -(funcall count-2 5) - @result{} 5 -(funcall count-1 2) - @result{} 19 -(funcall count-2) - @result{} 6 -@end example - -@noindent -Here we see that each call to @code{make-counter} creates a distinct -local variable @code{n}, which serves as a private counter for the -function object that is returned. - -Closed-over lexical variables persist until the last reference to -them goes away, just like all other Lisp objects. For example, -@code{count-2} refers to a function object which refers to an -instance of the variable @code{n}; this is the only reference -to that variable, so after @code{(setq count-2 nil)} the garbage -collector would be able to delete this instance of @code{n}. -Of course, if a @code{lexical-let} does not actually create any -closures, then the lexical variables are free as soon as the -@code{lexical-let} returns. - -Many closures are used only during the extent of the bindings they -refer to; these are known as ``downward funargs'' in Lisp parlance. -When a closure is used in this way, regular Emacs Lisp dynamic -bindings suffice and will be more efficient than @code{lexical-let} -closures: - -@example -(defun add-to-list (x list) - (mapcar (lambda (y) (+ x y))) list) -(add-to-list 7 '(1 2 5)) - @result{} (8 9 12) -@end example - -@noindent -Since this lambda is only used while @code{x} is still bound, -it is not necessary to make a true closure out of it. - -You can use @code{defun} or @code{flet} inside a @code{lexical-let} -to create a named closure. If several closures are created in the -body of a single @code{lexical-let}, they all close over the same -instance of the lexical variable. - -The @code{lexical-let} form is an extension to Common Lisp. In -true Common Lisp, all bindings are lexical unless declared otherwise. -@end defspec - -@defspec lexical-let* (bindings@dots{}) forms@dots{} -This form is just like @code{lexical-let}, except that the bindings -are made sequentially in the manner of @code{let*}. -@end defspec - -@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings -@subsection Function Bindings - -@noindent -These forms make @code{let}-like bindings to functions instead -of variables. - -@defspec flet (bindings@dots{}) forms@dots{} -This form establishes @code{let}-style bindings on the function -cells of symbols rather than on the value cells. Each @var{binding} -must be a list of the form @samp{(@var{name} @var{arglist} -@var{forms}@dots{})}, which defines a function exactly as if -it were a @code{defun*} form. The function @var{name} is defined -accordingly for the duration of the body of the @code{flet}; then -the old function definition, or lack thereof, is restored. - -While @code{flet} in Common Lisp establishes a lexical binding of -@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The -result is that @code{flet} affects indirect calls to a function as -well as calls directly inside the @code{flet} form itself. - -You can use @code{flet} to disable or modify the behavior of a -function in a temporary fashion. This will even work on Emacs -primitives, although note that some calls to primitive functions -internal to Emacs are made without going through the symbol's -function cell, and so will not be affected by @code{flet}. For -example, - -@example -(flet ((message (&rest args) (push args saved-msgs))) - (do-something)) -@end example - -This code attempts to replace the built-in function @code{message} -with a function that simply saves the messages in a list rather -than displaying them. The original definition of @code{message} -will be restored after @code{do-something} exits. This code will -work fine on messages generated by other Lisp code, but messages -generated directly inside Emacs will not be caught since they make -direct C-language calls to the message routines rather than going -through the Lisp @code{message} function. - -@c Bug#411. -Also note that many primitives (e.g. @code{+}) have special byte-compile -handling. Attempts to redefine such functions using @code{flet} will -fail if byte-compiled. In such cases, use @code{labels} instead. - -Functions defined by @code{flet} may use the full Common Lisp -argument notation supported by @code{defun*}; also, the function -body is enclosed in an implicit block as if by @code{defun*}. -@xref{Program Structure}. -@end defspec - -@defspec labels (bindings@dots{}) forms@dots{} -The @code{labels} form is like @code{flet}, except that it -makes lexical bindings of the function names rather than -dynamic bindings. (In true Common Lisp, both @code{flet} and -@code{labels} make lexical bindings of slightly different sorts; -since Emacs Lisp is dynamically bound by default, it seemed -more appropriate for @code{flet} also to use dynamic binding. -The @code{labels} form, with its lexical binding, is fully -compatible with Common Lisp.) - -Lexical scoping means that all references to the named -functions must appear physically within the body of the -@code{labels} form. References may appear both in the body -@var{forms} of @code{labels} itself, and in the bodies of -the functions themselves. Thus, @code{labels} can define -local recursive functions, or mutually-recursive sets of -functions. - -A ``reference'' to a function name is either a call to that -function, or a use of its name quoted by @code{quote} or -@code{function} to be passed on to, say, @code{mapcar}. -@end defspec - -@node Macro Bindings, , Function Bindings, Variable Bindings -@subsection Macro Bindings - -@noindent -These forms create local macros and ``symbol macros.'' - -@defspec macrolet (bindings@dots{}) forms@dots{} -This form is analogous to @code{flet}, but for macros instead of -functions. Each @var{binding} is a list of the same form as the -arguments to @code{defmacro*} (i.e., a macro name, argument list, -and macro-expander forms). The macro is defined accordingly for -use within the body of the @code{macrolet}. - -Because of the nature of macros, @code{macrolet} is lexically -scoped even in Emacs Lisp: The @code{macrolet} binding will -affect only calls that appear physically within the body -@var{forms}, possibly after expansion of other macros in the -body. -@end defspec - -@defspec symbol-macrolet (bindings@dots{}) forms@dots{} -This form creates @dfn{symbol macros}, which are macros that look -like variable references rather than function calls. Each -@var{binding} is a list @samp{(@var{var} @var{expansion})}; -any reference to @var{var} within the body @var{forms} is -replaced by @var{expansion}. - -@example -(setq bar '(5 . 9)) -(symbol-macrolet ((foo (car bar))) - (incf foo)) -bar - @result{} (6 . 9) -@end example - -A @code{setq} of a symbol macro is treated the same as a @code{setf}. -I.e., @code{(setq foo 4)} in the above would be equivalent to -@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. - -Likewise, a @code{let} or @code{let*} binding a symbol macro is -treated like a @code{letf} or @code{letf*}. This differs from true -Common Lisp, where the rules of lexical scoping cause a @code{let} -binding to shadow a @code{symbol-macrolet} binding. In this package, -only @code{lexical-let} and @code{lexical-let*} will shadow a symbol -macro. - -There is no analogue of @code{defmacro} for symbol macros; all symbol -macros are local. A typical use of @code{symbol-macrolet} is in the -expansion of another macro: - -@example -(defmacro* my-dolist ((x list) &rest body) - (let ((var (gensym))) - (list 'loop 'for var 'on list 'do - (list* 'symbol-macrolet (list (list x (list 'car var))) - body)))) - -(setq mylist '(1 2 3 4)) -(my-dolist (x mylist) (incf x)) -mylist - @result{} (2 3 4 5) -@end example - -@noindent -In this example, the @code{my-dolist} macro is similar to @code{dolist} -(@pxref{Iteration}) except that the variable @code{x} becomes a true -reference onto the elements of the list. The @code{my-dolist} call -shown here expands to - -@example -(loop for G1234 on mylist do - (symbol-macrolet ((x (car G1234))) - (incf x))) -@end example - -@noindent -which in turn expands to - -@example -(loop for G1234 on mylist do (incf (car G1234))) -@end example - -@xref{Loop Facility}, for a description of the @code{loop} macro. -This package defines a nonstandard @code{in-ref} loop clause that -works much like @code{my-dolist}. -@end defspec - -@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure -@section Conditionals - -@noindent -These conditional forms augment Emacs Lisp's simple @code{if}, -@code{and}, @code{or}, and @code{cond} forms. - -@defspec case keyform clause@dots{} -This macro evaluates @var{keyform}, then compares it with the key -values listed in the various @var{clause}s. Whichever clause matches -the key is executed; comparison is done by @code{eql}. If no clause -matches, the @code{case} form returns @code{nil}. The clauses are -of the form - -@example -(@var{keylist} @var{body-forms}@dots{}) -@end example - -@noindent -where @var{keylist} is a list of key values. If there is exactly -one value, and it is not a cons cell or the symbol @code{nil} or -@code{t}, then it can be used by itself as a @var{keylist} without -being enclosed in a list. All key values in the @code{case} form -must be distinct. The final clauses may use @code{t} in place of -a @var{keylist} to indicate a default clause that should be taken -if none of the other clauses match. (The symbol @code{otherwise} -is also recognized in place of @code{t}. To make a clause that -matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, -enclose the symbol in a list.) - -For example, this expression reads a keystroke, then does one of -four things depending on whether it is an @samp{a}, a @samp{b}, -a @key{RET} or @kbd{C-j}, or anything else. - -@example -(case (read-char) - (?a (do-a-thing)) - (?b (do-b-thing)) - ((?\r ?\n) (do-ret-thing)) - (t (do-other-thing))) -@end example -@end defspec - -@defspec ecase keyform clause@dots{} -This macro is just like @code{case}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defspec - -@defspec typecase keyform clause@dots{} -This macro is a version of @code{case} that checks for types -rather than values. Each @var{clause} is of the form -@samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, -for a description of type specifiers. For example, - -@example -(typecase x - (integer (munch-integer x)) - (float (munch-float x)) - (string (munch-integer (string-to-int x))) - (t (munch-anything x))) -@end example - -The type specifier @code{t} matches any type of object; the word -@code{otherwise} is also allowed. To make one clause match any of -several types, use an @code{(or ...)} type specifier. -@end defspec - -@defspec etypecase keyform clause@dots{} -This macro is just like @code{typecase}, except that if the key does -not match any of the clauses, an error is signaled rather than -simply returning @code{nil}. -@end defspec - -@node Blocks and Exits, Iteration, Conditionals, Control Structure -@section Blocks and Exits - -@noindent -Common Lisp @dfn{blocks} provide a non-local exit mechanism very -similar to @code{catch} and @code{throw}, but lexically rather than -dynamically scoped. This package actually implements @code{block} -in terms of @code{catch}; however, the lexical scoping allows the -optimizing byte-compiler to omit the costly @code{catch} step if the -body of the block does not actually @code{return-from} the block. - -@defspec block name forms@dots{} -The @var{forms} are evaluated as if by a @code{progn}. However, -if any of the @var{forms} execute @code{(return-from @var{name})}, -they will jump out and return directly from the @code{block} form. -The @code{block} returns the result of the last @var{form} unless -a @code{return-from} occurs. - -The @code{block}/@code{return-from} mechanism is quite similar to -the @code{catch}/@code{throw} mechanism. The main differences are -that block @var{name}s are unevaluated symbols, rather than forms -(such as quoted symbols) which evaluate to a tag at run-time; and -also that blocks are lexically scoped whereas @code{catch}/@code{throw} -are dynamically scoped. This means that functions called from the -body of a @code{catch} can also @code{throw} to the @code{catch}, -but the @code{return-from} referring to a block name must appear -physically within the @var{forms} that make up the body of the block. -They may not appear within other called functions, although they may -appear within macro expansions or @code{lambda}s in the body. Block -names and @code{catch} names form independent name-spaces. - -In true Common Lisp, @code{defun} and @code{defmacro} surround -the function or expander bodies with implicit blocks with the -same name as the function or macro. This does not occur in Emacs -Lisp, but this package provides @code{defun*} and @code{defmacro*} -forms which do create the implicit block. - -The Common Lisp looping constructs defined by this package, -such as @code{loop} and @code{dolist}, also create implicit blocks -just as in Common Lisp. - -Because they are implemented in terms of Emacs Lisp @code{catch} -and @code{throw}, blocks have the same overhead as actual -@code{catch} constructs (roughly two function calls). However, -the optimizing byte compiler will optimize away the @code{catch} -if the block does -not in fact contain any @code{return} or @code{return-from} calls -that jump to it. This means that @code{do} loops and @code{defun*} -functions which don't use @code{return} don't pay the overhead to -support it. -@end defspec - -@defspec return-from name [result] -This macro returns from the block named @var{name}, which must be -an (unevaluated) symbol. If a @var{result} form is specified, it -is evaluated to produce the result returned from the @code{block}. -Otherwise, @code{nil} is returned. -@end defspec - -@defspec return [result] -This macro is exactly like @code{(return-from nil @var{result})}. -Common Lisp loops like @code{do} and @code{dolist} implicitly enclose -themselves in @code{nil} blocks. -@end defspec - -@node Iteration, Loop Facility, Blocks and Exits, Control Structure -@section Iteration - -@noindent -The macros described here provide more sophisticated, high-level -looping constructs to complement Emacs Lisp's basic @code{while} -loop. - -@defspec loop forms@dots{} -The @dfn{CL} package supports both the simple, old-style meaning of -@code{loop} and the extremely powerful and flexible feature known as -the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced -facility is discussed in the following section; @pxref{Loop Facility}. -The simple form of @code{loop} is described here. - -If @code{loop} is followed by zero or more Lisp expressions, -then @code{(loop @var{exprs}@dots{})} simply creates an infinite -loop executing the expressions over and over. The loop is -enclosed in an implicit @code{nil} block. Thus, - -@example -(loop (foo) (if (no-more) (return 72)) (bar)) -@end example - -@noindent -is exactly equivalent to - -@example -(block nil (while t (foo) (if (no-more) (return 72)) (bar))) -@end example - -If any of the expressions are plain symbols, the loop is instead -interpreted as a Loop Macro specification as described later. -(This is not a restriction in practice, since a plain symbol -in the above notation would simply access and throw away the -value of a variable.) -@end defspec - -@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This macro creates a general iterative loop. Each @var{spec} is -of the form - -@example -(@var{var} [@var{init} [@var{step}]]) -@end example - -The loop works as follows: First, each @var{var} is bound to the -associated @var{init} value as if by a @code{let} form. Then, in -each iteration of the loop, the @var{end-test} is evaluated; if -true, the loop is finished. Otherwise, the body @var{forms} are -evaluated, then each @var{var} is set to the associated @var{step} -expression (as if by a @code{psetq} form) and the next iteration -begins. Once the @var{end-test} becomes true, the @var{result} -forms are evaluated (with the @var{var}s still bound to their -values) to produce the result returned by @code{do}. - -The entire @code{do} loop is enclosed in an implicit @code{nil} -block, so that you can use @code{(return)} to break out of the -loop at any time. - -If there are no @var{result} forms, the loop returns @code{nil}. -If a given @var{var} has no @var{step} form, it is bound to its -@var{init} value but not otherwise modified during the @code{do} -loop (unless the code explicitly modifies it); this case is just -a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} -around the loop. If @var{init} is also omitted it defaults to -@code{nil}, and in this case a plain @samp{@var{var}} can be used -in place of @samp{(@var{var})}, again following the analogy with -@code{let}. - -This example (from Steele) illustrates a loop which applies the -function @code{f} to successive pairs of values from the lists -@code{foo} and @code{bar}; it is equivalent to the call -@code{(mapcar* 'f foo bar)}. Note that this loop has no body -@var{forms} at all, performing all its work as side effects of -the rest of the loop. - -@example -(do ((x foo (cdr x)) - (y bar (cdr y)) - (z nil (cons (f (car x) (car y)) z))) - ((or (null x) (null y)) - (nreverse z))) -@end example -@end defspec - -@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} -This is to @code{do} what @code{let*} is to @code{let}. In -particular, the initial values are bound as if by @code{let*} -rather than @code{let}, and the steps are assigned as if by -@code{setq} rather than @code{psetq}. - -Here is another way to write the above loop: - -@example -(do* ((xp foo (cdr xp)) - (yp bar (cdr yp)) - (x (car xp) (car xp)) - (y (car yp) (car yp)) - z) - ((or (null xp) (null yp)) - (nreverse z)) - (push (f x y) z)) -@end example -@end defspec - -@defspec dolist (var list [result]) forms@dots{} -This is a more specialized loop which iterates across the elements -of a list. @var{list} should evaluate to a list; the body @var{forms} -are executed with @var{var} bound to each element of the list in -turn. Finally, the @var{result} form (or @code{nil}) is evaluated -with @var{var} bound to @code{nil} to produce the result returned by -the loop. Unlike with Emacs's built in @code{dolist}, the loop is -surrounded by an implicit @code{nil} block. -@end defspec - -@defspec dotimes (var count [result]) forms@dots{} -This is a more specialized loop which iterates a specified number -of times. The body is executed with @var{var} bound to the integers -from zero (inclusive) to @var{count} (exclusive), in turn. Then -the @code{result} form is evaluated with @var{var} bound to the total -number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. Unlike with Emacs's built in -@code{dolist}, the loop is surrounded by an implicit @code{nil} block. -@end defspec - -@defspec do-symbols (var [obarray [result]]) forms@dots{} -This loop iterates over all interned symbols. If @var{obarray} -is specified and is not @code{nil}, it loops over all symbols in -that obarray. For each symbol, the body @var{forms} are evaluated -with @var{var} bound to that symbol. The symbols are visited in -an unspecified order. Afterward the @var{result} form, if any, -is evaluated (with @var{var} bound to @code{nil}) to get the return -value. The loop is surrounded by an implicit @code{nil} block. -@end defspec - -@defspec do-all-symbols (var [result]) forms@dots{} -This is identical to @code{do-symbols} except that the @var{obarray} -argument is omitted; it always iterates over the default obarray. -@end defspec - -@xref{Mapping over Sequences}, for some more functions for -iterating over vectors or lists. - -@node Loop Facility, Multiple Values, Iteration, Control Structure -@section Loop Facility - -@noindent -A common complaint with Lisp's traditional looping constructs is -that they are either too simple and limited, such as Common Lisp's -@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and -obscure, like Common Lisp's @code{do} loop. - -To remedy this, recent versions of Common Lisp have added a new -construct called the ``Loop Facility'' or ``@code{loop} macro,'' -with an easy-to-use but very powerful and expressive syntax. - -@menu -* Loop Basics:: `loop' macro, basic clause structure -* Loop Examples:: Working examples of `loop' macro -* For Clauses:: Clauses introduced by `for' or `as' -* Iteration Clauses:: `repeat', `while', `thereis', etc. -* Accumulation Clauses:: `collect', `sum', `maximize', etc. -* Other Clauses:: `with', `if', `initially', `finally' -@end menu - -@node Loop Basics, Loop Examples, Loop Facility, Loop Facility -@subsection Loop Basics - -@noindent -The @code{loop} macro essentially creates a mini-language within -Lisp that is specially tailored for describing loops. While this -language is a little strange-looking by the standards of regular Lisp, -it turns out to be very easy to learn and well-suited to its purpose. - -Since @code{loop} is a macro, all parsing of the loop language -takes place at byte-compile time; compiled @code{loop}s are just -as efficient as the equivalent @code{while} loops written longhand. - -@defspec loop clauses@dots{} -A loop construct consists of a series of @var{clause}s, each -introduced by a symbol like @code{for} or @code{do}. Clauses -are simply strung together in the argument list of @code{loop}, -with minimal extra parentheses. The various types of clauses -specify initializations, such as the binding of temporary -variables, actions to be taken in the loop, stepping actions, -and final cleanup. - -Common Lisp specifies a certain general order of clauses in a -loop: - -@example -(loop @var{name-clause} - @var{var-clauses}@dots{} - @var{action-clauses}@dots{}) -@end example - -The @var{name-clause} optionally gives a name to the implicit -block that surrounds the loop. By default, the implicit block -is named @code{nil}. The @var{var-clauses} specify what -variables should be bound during the loop, and how they should -be modified or iterated throughout the course of the loop. The -@var{action-clauses} are things to be done during the loop, such -as computing, collecting, and returning values. - -The Emacs version of the @code{loop} macro is less restrictive about -the order of clauses, but things will behave most predictably if -you put the variable-binding clauses @code{with}, @code{for}, and -@code{repeat} before the action clauses. As in Common Lisp, -@code{initially} and @code{finally} clauses can go anywhere. - -Loops generally return @code{nil} by default, but you can cause -them to return a value by using an accumulation clause like -@code{collect}, an end-test clause like @code{always}, or an -explicit @code{return} clause to jump out of the implicit block. -(Because the loop body is enclosed in an implicit block, you can -also use regular Lisp @code{return} or @code{return-from} to -break out of the loop.) -@end defspec - -The following sections give some examples of the Loop Macro in -action, and describe the particular loop clauses in great detail. -Consult the second edition of Steele's @dfn{Common Lisp, the Language}, -for additional discussion and examples of the @code{loop} macro. - -@node Loop Examples, For Clauses, Loop Basics, Loop Facility -@subsection Loop Examples - -@noindent -Before listing the full set of clauses that are allowed, let's -look at a few example loops just to get a feel for the @code{loop} -language. - -@example -(loop for buf in (buffer-list) - collect (buffer-file-name buf)) -@end example - -@noindent -This loop iterates over all Emacs buffers, using the list -returned by @code{buffer-list}. For each buffer @code{buf}, -it calls @code{buffer-file-name} and collects the results into -a list, which is then returned from the @code{loop} construct. -The result is a list of the file names of all the buffers in -Emacs' memory. The words @code{for}, @code{in}, and @code{collect} -are reserved words in the @code{loop} language. - -@example -(loop repeat 20 do (insert "Yowsa\n")) -@end example - -@noindent -This loop inserts the phrase ``Yowsa'' twenty times in the -current buffer. - -@example -(loop until (eobp) do (munch-line) (forward-line 1)) -@end example - -@noindent -This loop calls @code{munch-line} on every line until the end -of the buffer. If point is already at the end of the buffer, -the loop exits immediately. - -@example -(loop do (munch-line) until (eobp) do (forward-line 1)) -@end example - -@noindent -This loop is similar to the above one, except that @code{munch-line} -is always called at least once. - -@example -(loop for x from 1 to 100 - for y = (* x x) - until (>= y 729) - finally return (list x (= y 729))) -@end example - -@noindent -This more complicated loop searches for a number @code{x} whose -square is 729. For safety's sake it only examines @code{x} -values up to 100; dropping the phrase @samp{to 100} would -cause the loop to count upwards with no limit. The second -@code{for} clause defines @code{y} to be the square of @code{x} -within the loop; the expression after the @code{=} sign is -reevaluated each time through the loop. The @code{until} -clause gives a condition for terminating the loop, and the -@code{finally} clause says what to do when the loop finishes. -(This particular example was written less concisely than it -could have been, just for the sake of illustration.) - -Note that even though this loop contains three clauses (two -@code{for}s and an @code{until}) that would have been enough to -define loops all by themselves, it still creates a single loop -rather than some sort of triple-nested loop. You must explicitly -nest your @code{loop} constructs if you want nested loops. - -@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility -@subsection For Clauses - -@noindent -Most loops are governed by one or more @code{for} clauses. -A @code{for} clause simultaneously describes variables to be -bound, how those variables are to be stepped during the loop, -and usually an end condition based on those variables. - -The word @code{as} is a synonym for the word @code{for}. This -word is followed by a variable name, then a word like @code{from} -or @code{across} that describes the kind of iteration desired. -In Common Lisp, the phrase @code{being the} sometimes precedes -the type of iteration; in this package both @code{being} and -@code{the} are optional. The word @code{each} is a synonym -for @code{the}, and the word that follows it may be singular -or plural: @samp{for x being the elements of y} or -@samp{for x being each element of y}. Which form you use -is purely a matter of style. - -The variable is bound around the loop as if by @code{let}: - -@example -(setq i 'happy) -(loop for i from 1 to 10 do (do-something-with i)) -i - @result{} happy -@end example - -@table @code -@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} -This type of @code{for} clause creates a counting loop. Each of -the three sub-terms is optional, though there must be at least one -term so that the clause is marked as a counting clause. - -The three expressions are the starting value, the ending value, and -the step value, respectively, of the variable. The loop counts -upwards by default (@var{expr3} must be positive), from @var{expr1} -to @var{expr2} inclusively. If you omit the @code{from} term, the -loop counts from zero; if you omit the @code{to} term, the loop -counts forever without stopping (unless stopped by some other -loop clause, of course); if you omit the @code{by} term, the loop -counts in steps of one. - -You can replace the word @code{from} with @code{upfrom} or -@code{downfrom} to indicate the direction of the loop. Likewise, -you can replace @code{to} with @code{upto} or @code{downto}. -For example, @samp{for x from 5 downto 1} executes five times -with @code{x} taking on the integers from 5 down to 1 in turn. -Also, you can replace @code{to} with @code{below} or @code{above}, -which are like @code{upto} and @code{downto} respectively except -that they are exclusive rather than inclusive limits: - -@example -(loop for x to 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9 10) -(loop for x below 10 collect x) - @result{} (0 1 2 3 4 5 6 7 8 9) -@end example - -The @code{by} value is always positive, even for downward-counting -loops. Some sort of @code{from} value is required for downward -loops; @samp{for x downto 5} is not a valid loop clause all by -itself. - -@item for @var{var} in @var{list} by @var{function} -This clause iterates @var{var} over all the elements of @var{list}, -in turn. If you specify the @code{by} term, then @var{function} -is used to traverse the list instead of @code{cdr}; it must be a -function taking one argument. For example: - -@example -(loop for x in '(1 2 3 4 5 6) collect (* x x)) - @result{} (1 4 9 16 25 36) -(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) - @result{} (1 9 25) -@end example - -@item for @var{var} on @var{list} by @var{function} -This clause iterates @var{var} over all the cons cells of @var{list}. - -@example -(loop for x on '(1 2 3 4) collect x) - @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) -@end example - -With @code{by}, there is no real reason that the @code{on} expression -must be a list. For example: - -@example -(loop for x on first-animal by 'next-animal collect x) -@end example - -@noindent -where @code{(next-animal x)} takes an ``animal'' @var{x} and returns -the next in the (assumed) sequence of animals, or @code{nil} if -@var{x} was the last animal in the sequence. - -@item for @var{var} in-ref @var{list} by @var{function} -This is like a regular @code{in} clause, but @var{var} becomes -a @code{setf}-able ``reference'' onto the elements of the list -rather than just a temporary variable. For example, - -@example -(loop for x in-ref my-list do (incf x)) -@end example - -@noindent -increments every element of @code{my-list} in place. This clause -is an extension to standard Common Lisp. - -@item for @var{var} across @var{array} -This clause iterates @var{var} over all the elements of @var{array}, -which may be a vector or a string. - -@example -(loop for x across "aeiou" - do (use-vowel (char-to-string x))) -@end example - -@item for @var{var} across-ref @var{array} -This clause iterates over an array, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the elements of @var{sequence} -This clause iterates over the elements of @var{sequence}, which may -be a list, vector, or string. Since the type must be determined -at run-time, this is somewhat less efficient than @code{in} or -@code{across}. The clause may be followed by the additional term -@samp{using (index @var{var2})} to cause @var{var2} to be bound to -the successive indices (starting at 0) of the elements. - -This clause type is taken from older versions of the @code{loop} macro, -and is not present in modern Common Lisp. The @samp{using (sequence ...)} -term of the older macros is not supported. - -@item for @var{var} being the elements of-ref @var{sequence} -This clause iterates over a sequence, with @var{var} a @code{setf}-able -reference onto the elements; see @code{in-ref} above. - -@item for @var{var} being the symbols [of @var{obarray}] -This clause iterates over symbols, either over all interned symbols -or over all symbols in @var{obarray}. The loop is executed with -@var{var} bound to each symbol in turn. The symbols are visited in -an unspecified order. - -As an example, - -@example -(loop for sym being the symbols - when (fboundp sym) - when (string-match "^map" (symbol-name sym)) - collect sym) -@end example - -@noindent -returns a list of all the functions whose names begin with @samp{map}. - -The Common Lisp words @code{external-symbols} and @code{present-symbols} -are also recognized but are equivalent to @code{symbols} in Emacs Lisp. - -Due to a minor implementation restriction, it will not work to have -more than one @code{for} clause iterating over symbols, hash tables, -keymaps, overlays, or intervals in a given @code{loop}. Fortunately, -it would rarely if ever be useful to do so. It @emph{is} valid to mix -one of these types of clauses with other clauses like @code{for ... to} -or @code{while}. - -@item for @var{var} being the hash-keys of @var{hash-table} -This clause iterates over the entries in @var{hash-table}. For each -hash table entry, @var{var} is bound to the entry's key. If you write -@samp{the hash-values} instead, @var{var} is bound to the values -of the entries. The clause may be followed by the additional -term @samp{using (hash-values @var{var2})} (where @code{hash-values} -is the opposite word of the word following @code{the}) to cause -@var{var} and @var{var2} to be bound to the two parts of each -hash table entry. - -@item for @var{var} being the key-codes of @var{keymap} -This clause iterates over the entries in @var{keymap}. -The iteration does not enter nested keymaps but does enter inherited -(parent) keymaps. -You can use @samp{the key-bindings} to access the commands bound to -the keys rather than the key codes, and you can add a @code{using} -clause to access both the codes and the bindings together. - -@item for @var{var} being the key-seqs of @var{keymap} -This clause iterates over all key sequences defined by @var{keymap} -and its nested keymaps, where @var{var} takes on values which are -vectors. The strings or vectors -are reused for each iteration, so you must copy them if you wish to keep -them permanently. You can add a @samp{using (key-bindings ...)} -clause to get the command bindings as well. - -@item for @var{var} being the overlays [of @var{buffer}] @dots{} -This clause iterates over the ``overlays'' of a buffer -(the clause @code{extents} is synonymous -with @code{overlays}). If the @code{of} term is omitted, the current -buffer is used. -This clause also accepts optional @samp{from @var{pos}} and -@samp{to @var{pos}} terms, limiting the clause to overlays which -overlap the specified region. - -@item for @var{var} being the intervals [of @var{buffer}] @dots{} -This clause iterates over all intervals of a buffer with constant -text properties. The variable @var{var} will be bound to conses -of start and end positions, where one start position is always equal -to the previous end position. The clause allows @code{of}, -@code{from}, @code{to}, and @code{property} terms, where the latter -term restricts the search to just the specified property. The -@code{of} term may specify either a buffer or a string. - -@item for @var{var} being the frames -This clause iterates over all frames, i.e., X window system windows -open on Emacs files. The -clause @code{screens} is a synonym for @code{frames}. The frames -are visited in @code{next-frame} order starting from -@code{selected-frame}. - -@item for @var{var} being the windows [of @var{frame}] -This clause iterates over the windows (in the Emacs sense) of -the current frame, or of the specified @var{frame}. - -@item for @var{var} being the buffers -This clause iterates over all buffers in Emacs. It is equivalent -to @samp{for @var{var} in (buffer-list)}. - -@item for @var{var} = @var{expr1} then @var{expr2} -This clause does a general iteration. The first time through -the loop, @var{var} will be bound to @var{expr1}. On the second -and successive iterations it will be set by evaluating @var{expr2} -(which may refer to the old value of @var{var}). For example, -these two loops are effectively the same: - -@example -(loop for x on my-list by 'cddr do ...) -(loop for x = my-list then (cddr x) while x do ...) -@end example - -Note that this type of @code{for} clause does not imply any sort -of terminating condition; the above example combines it with a -@code{while} clause to tell when to end the loop. - -If you omit the @code{then} term, @var{expr1} is used both for -the initial setting and for successive settings: - -@example -(loop for x = (random) when (> x 0) return x) -@end example - -@noindent -This loop keeps taking random numbers from the @code{(random)} -function until it gets a positive one, which it then returns. -@end table - -If you include several @code{for} clauses in a row, they are -treated sequentially (as if by @code{let*} and @code{setq}). -You can instead use the word @code{and} to link the clauses, -in which case they are processed in parallel (as if by @code{let} -and @code{psetq}). - -@example -(loop for x below 5 for y = nil then x collect (list x y)) - @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) -(loop for x below 5 and y = nil then x collect (list x y)) - @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) -@end example - -@noindent -In the first loop, @code{y} is set based on the value of @code{x} -that was just set by the previous clause; in the second loop, -@code{x} and @code{y} are set simultaneously so @code{y} is set -based on the value of @code{x} left over from the previous time -through the loop. - -Another feature of the @code{loop} macro is @dfn{destructuring}, -similar in concept to the destructuring provided by @code{defmacro}. -The @var{var} part of any @code{for} clause can be given as a list -of variables instead of a single variable. The values produced -during loop execution must be lists; the values in the lists are -stored in the corresponding variables. - -@example -(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) - @result{} (5 9 13) -@end example - -In loop destructuring, if there are more values than variables -the trailing values are ignored, and if there are more variables -than values the trailing variables get the value @code{nil}. -If @code{nil} is used as a variable name, the corresponding -values are ignored. Destructuring may be nested, and dotted -lists of variables like @code{(x . y)} are allowed. - -@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility -@subsection Iteration Clauses - -@noindent -Aside from @code{for} clauses, there are several other loop clauses -that control the way the loop operates. They might be used by -themselves, or in conjunction with one or more @code{for} clauses. - -@table @code -@item repeat @var{integer} -This clause simply counts up to the specified number using an -internal temporary variable. The loops - -@example -(loop repeat (1+ n) do ...) -(loop for temp to n do ...) -@end example - -@noindent -are identical except that the second one forces you to choose -a name for a variable you aren't actually going to use. - -@item while @var{condition} -This clause stops the loop when the specified condition (any Lisp -expression) becomes @code{nil}. For example, the following two -loops are equivalent, except for the implicit @code{nil} block -that surrounds the second one: - -@example -(while @var{cond} @var{forms}@dots{}) -(loop while @var{cond} do @var{forms}@dots{}) -@end example - -@item until @var{condition} -This clause stops the loop when the specified condition is true, -i.e., non-@code{nil}. - -@item always @var{condition} -This clause stops the loop when the specified condition is @code{nil}. -Unlike @code{while}, it stops the loop using @code{return nil} so that -the @code{finally} clauses are not executed. If all the conditions -were non-@code{nil}, the loop returns @code{t}: - -@example -(if (loop for size in size-list always (> size 10)) - (some-big-sizes) - (no-big-sizes)) -@end example - -@item never @var{condition} -This clause is like @code{always}, except that the loop returns -@code{t} if any conditions were false, or @code{nil} otherwise. - -@item thereis @var{condition} -This clause stops the loop when the specified form is non-@code{nil}; -in this case, it returns that non-@code{nil} value. If all the -values were @code{nil}, the loop returns @code{nil}. -@end table - -@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility -@subsection Accumulation Clauses - -@noindent -These clauses cause the loop to accumulate information about the -specified Lisp @var{form}. The accumulated result is returned -from the loop unless overridden, say, by a @code{return} clause. - -@table @code -@item collect @var{form} -This clause collects the values of @var{form} into a list. Several -examples of @code{collect} appear elsewhere in this manual. - -The word @code{collecting} is a synonym for @code{collect}, and -likewise for the other accumulation clauses. - -@item append @var{form} -This clause collects lists of values into a result list using -@code{append}. - -@item nconc @var{form} -This clause collects lists of values into a result list by -destructively modifying the lists rather than copying them. - -@item concat @var{form} -This clause concatenates the values of the specified @var{form} -into a string. (It and the following clause are extensions to -standard Common Lisp.) - -@item vconcat @var{form} -This clause concatenates the values of the specified @var{form} -into a vector. - -@item count @var{form} -This clause counts the number of times the specified @var{form} -evaluates to a non-@code{nil} value. - -@item sum @var{form} -This clause accumulates the sum of the values of the specified -@var{form}, which must evaluate to a number. - -@item maximize @var{form} -This clause accumulates the maximum value of the specified @var{form}, -which must evaluate to a number. The return value is undefined if -@code{maximize} is executed zero times. - -@item minimize @var{form} -This clause accumulates the minimum value of the specified @var{form}. -@end table - -Accumulation clauses can be followed by @samp{into @var{var}} to -cause the data to be collected into variable @var{var} (which is -automatically @code{let}-bound during the loop) rather than an -unnamed temporary variable. Also, @code{into} accumulations do -not automatically imply a return value. The loop must use some -explicit mechanism, such as @code{finally return}, to return -the accumulated result. - -It is valid for several accumulation clauses of the same type to -accumulate into the same place. From Steele: - -@example -(loop for name in '(fred sue alice joe june) - for kids in '((bob ken) () () (kris sunshine) ()) - collect name - append kids) - @result{} (fred bob ken sue alice joe kris sunshine june) -@end example - -@node Other Clauses, , Accumulation Clauses, Loop Facility -@subsection Other Clauses - -@noindent -This section describes the remaining loop clauses. - -@table @code -@item with @var{var} = @var{value} -This clause binds a variable to a value around the loop, but -otherwise leaves the variable alone during the loop. The following -loops are basically equivalent: - -@example -(loop with x = 17 do ...) -(let ((x 17)) (loop do ...)) -(loop for x = 17 then x do ...) -@end example - -Naturally, the variable @var{var} might be used for some purpose -in the rest of the loop. For example: - -@example -(loop for x in my-list with res = nil do (push x res) - finally return res) -@end example - -This loop inserts the elements of @code{my-list} at the front of -a new list being accumulated in @code{res}, then returns the -list @code{res} at the end of the loop. The effect is similar -to that of a @code{collect} clause, but the list gets reversed -by virtue of the fact that elements are being pushed onto the -front of @code{res} rather than the end. - -If you omit the @code{=} term, the variable is initialized to -@code{nil}. (Thus the @samp{= nil} in the above example is -unnecessary.) - -Bindings made by @code{with} are sequential by default, as if -by @code{let*}. Just like @code{for} clauses, @code{with} clauses -can be linked with @code{and} to cause the bindings to be made by -@code{let} instead. - -@item if @var{condition} @var{clause} -This clause executes the following loop clause only if the specified -condition is true. The following @var{clause} should be an accumulation, -@code{do}, @code{return}, @code{if}, or @code{unless} clause. -Several clauses may be linked by separating them with @code{and}. -These clauses may be followed by @code{else} and a clause or clauses -to execute if the condition was false. The whole construct may -optionally be followed by the word @code{end} (which may be used to -disambiguate an @code{else} or @code{and} in a nested @code{if}). - -The actual non-@code{nil} value of the condition form is available -by the name @code{it} in the ``then'' part. For example: - -@example -(setq funny-numbers '(6 13 -1)) - @result{} (6 13 -1) -(loop for x below 10 - if (oddp x) - collect x into odds - and if (memq x funny-numbers) return (cdr it) end - else - collect x into evens - finally return (vector odds evens)) - @result{} [(1 3 5 7 9) (0 2 4 6 8)] -(setq funny-numbers '(6 7 13 -1)) - @result{} (6 7 13 -1) -(loop <@r{same thing again}>) - @result{} (13 -1) -@end example - -Note the use of @code{and} to put two clauses into the ``then'' -part, one of which is itself an @code{if} clause. Note also that -@code{end}, while normally optional, was necessary here to make -it clear that the @code{else} refers to the outermost @code{if} -clause. In the first case, the loop returns a vector of lists -of the odd and even values of @var{x}. In the second case, the -odd number 7 is one of the @code{funny-numbers} so the loop -returns early; the actual returned value is based on the result -of the @code{memq} call. - -@item when @var{condition} @var{clause} -This clause is just a synonym for @code{if}. - -@item unless @var{condition} @var{clause} -The @code{unless} clause is just like @code{if} except that the -sense of the condition is reversed. - -@item named @var{name} -This clause gives a name other than @code{nil} to the implicit -block surrounding the loop. The @var{name} is the symbol to be -used as the block name. - -@item initially [do] @var{forms}... -This keyword introduces one or more Lisp forms which will be -executed before the loop itself begins (but after any variables -requested by @code{for} or @code{with} have been bound to their -initial values). @code{initially} clauses can appear anywhere; -if there are several, they are executed in the order they appear -in the loop. The keyword @code{do} is optional. - -@item finally [do] @var{forms}... -This introduces Lisp forms which will be executed after the loop -finishes (say, on request of a @code{for} or @code{while}). -@code{initially} and @code{finally} clauses may appear anywhere -in the loop construct, but they are executed (in the specified -order) at the beginning or end, respectively, of the loop. - -@item finally return @var{form} -This says that @var{form} should be executed after the loop -is done to obtain a return value. (Without this, or some other -clause like @code{collect} or @code{return}, the loop will simply -return @code{nil}.) Variables bound by @code{for}, @code{with}, -or @code{into} will still contain their final values when @var{form} -is executed. - -@item do @var{forms}... -The word @code{do} may be followed by any number of Lisp expressions -which are executed as an implicit @code{progn} in the body of the -loop. Many of the examples in this section illustrate the use of -@code{do}. - -@item return @var{form} -This clause causes the loop to return immediately. The following -Lisp form is evaluated to give the return value of the @code{loop} -form. The @code{finally} clauses, if any, are not executed. -Of course, @code{return} is generally used inside an @code{if} or -@code{unless}, as its use in a top-level loop clause would mean -the loop would never get to ``loop'' more than once. - -The clause @samp{return @var{form}} is equivalent to -@samp{do (return @var{form})} (or @code{return-from} if the loop -was named). The @code{return} clause is implemented a bit more -efficiently, though. -@end table - -While there is no high-level way to add user extensions to @code{loop} -(comparable to @code{defsetf} for @code{setf}, say), this package -does offer two properties called @code{cl-loop-handler} and -@code{cl-loop-for-handler} which are functions to be called when -a given symbol is encountered as a top-level loop clause or -@code{for} clause, respectively. Consult the source code in -file @file{cl-macs.el} for details. - -This package's @code{loop} macro is compatible with that of Common -Lisp, except that a few features are not implemented: @code{loop-finish} -and data-type specifiers. Naturally, the @code{for} clauses which -iterate over keymaps, overlays, intervals, frames, windows, and -buffers are Emacs-specific extensions. - -@node Multiple Values, , Loop Facility, Control Structure -@section Multiple Values - -@noindent -Common Lisp functions can return zero or more results. Emacs Lisp -functions, by contrast, always return exactly one result. This -package makes no attempt to emulate Common Lisp multiple return -values; Emacs versions of Common Lisp functions that return more -than one value either return just the first value (as in -@code{compiler-macroexpand}) or return a list of values (as in -@code{get-setf-method}). This package @emph{does} define placeholders -for the Common Lisp functions that work with multiple values, but -in Emacs Lisp these functions simply operate on lists instead. -The @code{values} form, for example, is a synonym for @code{list} -in Emacs. - -@defspec multiple-value-bind (var@dots{}) values-form forms@dots{} -This form evaluates @var{values-form}, which must return a list of -values. It then binds the @var{var}s to these respective values, -as if by @code{let}, and then executes the body @var{forms}. -If there are more @var{var}s than values, the extra @var{var}s -are bound to @code{nil}. If there are fewer @var{var}s than -values, the excess values are ignored. -@end defspec - -@defspec multiple-value-setq (var@dots{}) form -This form evaluates @var{form}, which must return a list of values. -It then sets the @var{var}s to these respective values, as if by -@code{setq}. Extra @var{var}s or values are treated the same as -in @code{multiple-value-bind}. -@end defspec - -The older Quiroz package attempted a more faithful (but still -imperfect) emulation of Common Lisp multiple values. The old -method ``usually'' simulated true multiple values quite well, -but under certain circumstances would leave spurious return -values in memory where a later, unrelated @code{multiple-value-bind} -form would see them. - -Since a perfect emulation is not feasible in Emacs Lisp, this -package opts to keep it as simple and predictable as possible. - -@node Macros, Declarations, Control Structure, Top -@chapter Macros - -@noindent -This package implements the various Common Lisp features of -@code{defmacro}, such as destructuring, @code{&environment}, -and @code{&body}. Top-level @code{&whole} is not implemented -for @code{defmacro} due to technical difficulties. -@xref{Argument Lists}. - -Destructuring is made available to the user by way of the -following macro: - -@defspec destructuring-bind arglist expr forms@dots{} -This macro expands to code which executes @var{forms}, with -the variables in @var{arglist} bound to the list of values -returned by @var{expr}. The @var{arglist} can include all -the features allowed for @code{defmacro} argument lists, -including destructuring. (The @code{&environment} keyword -is not allowed.) The macro expansion will signal an error -if @var{expr} returns a list of the wrong number of arguments -or with incorrect keyword arguments. -@end defspec - -This package also includes the Common Lisp @code{define-compiler-macro} -facility, which allows you to define compile-time expansions and -optimizations for your functions. - -@defspec define-compiler-macro name arglist forms@dots{} -This form is similar to @code{defmacro}, except that it only expands -calls to @var{name} at compile-time; calls processed by the Lisp -interpreter are not expanded, nor are they expanded by the -@code{macroexpand} function. - -The argument list may begin with a @code{&whole} keyword and a -variable. This variable is bound to the macro-call form itself, -i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. -If the macro expander returns this form unchanged, then the -compiler treats it as a normal function call. This allows -compiler macros to work as optimizers for special cases of a -function, leaving complicated cases alone. - -For example, here is a simplified version of a definition that -appears as a standard part of this package: - -@example -(define-compiler-macro member* (&whole form a list &rest keys) - (if (and (null keys) - (eq (car-safe a) 'quote) - (not (floatp-safe (cadr a)))) - (list 'memq a list) - form)) -@end example - -@noindent -This definition causes @code{(member* @var{a} @var{list})} to change -to a call to the faster @code{memq} in the common case where @var{a} -is a non-floating-point constant; if @var{a} is anything else, or -if there are any keyword arguments in the call, then the original -@code{member*} call is left intact. (The actual compiler macro -for @code{member*} optimizes a number of other cases, including -common @code{:test} predicates.) -@end defspec - -@defun compiler-macroexpand form -This function is analogous to @code{macroexpand}, except that it -expands compiler macros rather than regular macros. It returns -@var{form} unchanged if it is not a call to a function for which -a compiler macro has been defined, or if that compiler macro -decided to punt by returning its @code{&whole} argument. Like -@code{macroexpand}, it expands repeatedly until it reaches a form -for which no further expansion is possible. -@end defun - -@xref{Macro Bindings}, for descriptions of the @code{macrolet} -and @code{symbol-macrolet} forms for making ``local'' macro -definitions. - -@node Declarations, Symbols, Macros, Top -@chapter Declarations - -@noindent -Common Lisp includes a complex and powerful ``declaration'' -mechanism that allows you to give the compiler special hints -about the types of data that will be stored in particular variables, -and about the ways those variables and functions will be used. This -package defines versions of all the Common Lisp declaration forms: -@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, -and @code{the}. - -Most of the Common Lisp declarations are not currently useful in -Emacs Lisp, as the byte-code system provides little opportunity -to benefit from type information, and @code{special} declarations -are redundant in a fully dynamically-scoped Lisp. A few -declarations are meaningful when the optimizing byte -compiler is being used, however. Under the earlier non-optimizing -compiler, these declarations will effectively be ignored. - -@defun proclaim decl-spec -This function records a ``global'' declaration specified by -@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} -is evaluated and thus should normally be quoted. -@end defun - -@defspec declaim decl-specs@dots{} -This macro is like @code{proclaim}, except that it takes any number -of @var{decl-spec} arguments, and the arguments are unevaluated and -unquoted. The @code{declaim} macro also puts an @code{(eval-when -(compile load eval) ...)} around the declarations so that they will -be registered at compile-time as well as at run-time. (This is vital, -since normally the declarations are meant to influence the way the -compiler treats the rest of the file that contains the @code{declaim} -form.) -@end defspec - -@defspec declare decl-specs@dots{} -This macro is used to make declarations within functions and other -code. Common Lisp allows declarations in various locations, generally -at the beginning of any of the many ``implicit @code{progn}s'' -throughout Lisp syntax, such as function bodies, @code{let} bodies, -etc. Currently the only declaration understood by @code{declare} -is @code{special}. -@end defspec - -@defspec locally declarations@dots{} forms@dots{} -In this package, @code{locally} is no different from @code{progn}. -@end defspec - -@defspec the type form -Type information provided by @code{the} is ignored in this package; -in other words, @code{(the @var{type} @var{form})} is equivalent -to @var{form}. Future versions of the optimizing byte-compiler may -make use of this information. - -For example, @code{mapcar} can map over both lists and arrays. It is -hard for the compiler to expand @code{mapcar} into an in-line loop -unless it knows whether the sequence will be a list or an array ahead -of time. With @code{(mapcar 'car (the vector foo))}, a future -compiler would have enough information to expand the loop in-line. -For now, Emacs Lisp will treat the above code as exactly equivalent -to @code{(mapcar 'car foo)}. -@end defspec - -Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or -@code{declare} should be a list beginning with a symbol that says -what kind of declaration it is. This package currently understands -@code{special}, @code{inline}, @code{notinline}, @code{optimize}, -and @code{warn} declarations. (The @code{warn} declaration is an -extension of standard Common Lisp.) Other Common Lisp declarations, -such as @code{type} and @code{ftype}, are silently ignored. - -@table @code -@item special -Since all variables in Emacs Lisp are ``special'' (in the Common -Lisp sense), @code{special} declarations are only advisory. They -simply tell the optimizing byte compiler that the specified -variables are intentionally being referred to without being -bound in the body of the function. The compiler normally emits -warnings for such references, since they could be typographical -errors for references to local variables. - -The declaration @code{(declare (special @var{var1} @var{var2}))} is -equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the -optimizing compiler, or to nothing at all in older compilers (which -do not warn for non-local references). - -In top-level contexts, it is generally better to write -@code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, -since @code{defvar} makes your intentions clearer. But the older -byte compilers can not handle @code{defvar}s appearing inside of -functions, while @code{(declare (special @var{var}))} takes care -to work correctly with all compilers. - -@item inline -The @code{inline} @var{decl-spec} lists one or more functions -whose bodies should be expanded ``in-line'' into calling functions -whenever the compiler is able to arrange for it. For example, -the Common Lisp function @code{cadr} is declared @code{inline} -by this package so that the form @code{(cadr @var{x})} will -expand directly into @code{(car (cdr @var{x}))} when it is called -in user functions, for a savings of one (relatively expensive) -function call. - -The following declarations are all equivalent. Note that the -@code{defsubst} form is a convenient way to define a function -and declare it inline all at once. - -@example -(declaim (inline foo bar)) -(eval-when (compile load eval) (proclaim '(inline foo bar))) -(defsubst foo (...) ...) ; instead of defun -@end example - -@strong{Please note:} this declaration remains in effect after the -containing source file is done. It is correct to use it to -request that a function you have defined should be inlined, -but it is impolite to use it to request inlining of an external -function. - -In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} -before a particular call to a function to cause just that call to -be inlined; the current byte compilers provide no way to implement -this, so @code{(declare (inline @dots{}))} is currently ignored by -this package. - -@item notinline -The @code{notinline} declaration lists functions which should -not be inlined after all; it cancels a previous @code{inline} -declaration. - -@item optimize -This declaration controls how much optimization is performed by -the compiler. Naturally, it is ignored by the earlier non-optimizing -compilers. - -The word @code{optimize} is followed by any number of lists like -@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several -optimization ``qualities''; this package ignores all but @code{speed} -and @code{safety}. The value of a quality should be an integer from -0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' -The default level for both qualities is 1. - -In this package, with the optimizing compiler, the -@code{speed} quality is tied to the @code{byte-compile-optimize} -flag, which is set to @code{nil} for @code{(speed 0)} and to -@code{t} for higher settings; and the @code{safety} quality is -tied to the @code{byte-compile-delete-errors} flag, which is -set to @code{t} for @code{(safety 3)} and to @code{nil} for all -lower settings. (The latter flag controls whether the compiler -is allowed to optimize out code whose only side-effect could -be to signal an error, e.g., rewriting @code{(progn foo bar)} to -@code{bar} when it is not known whether @code{foo} will be bound -at run-time.) - -Note that even compiling with @code{(safety 0)}, the Emacs -byte-code system provides sufficient checking to prevent real -harm from being done. For example, barring serious bugs in -Emacs itself, Emacs will not crash with a segmentation fault -just because of an error in a fully-optimized Lisp program. - -The @code{optimize} declaration is normally used in a top-level -@code{proclaim} or @code{declaim} in a file; Common Lisp allows -it to be used with @code{declare} to set the level of optimization -locally for a given form, but this will not work correctly with the -current version of the optimizing compiler. (The @code{declare} -will set the new optimization level, but that level will not -automatically be unset after the enclosing form is done.) - -@item warn -This declaration controls what sorts of warnings are generated -by the byte compiler. Again, only the optimizing compiler -generates warnings. The word @code{warn} is followed by any -number of ``warning qualities,'' similar in form to optimization -qualities. The currently supported warning types are -@code{redefine}, @code{callargs}, @code{unresolved}, and -@code{free-vars}; in the current system, a value of 0 will -disable these warnings and any higher value will enable them. -See the documentation for the optimizing byte compiler for details. -@end table - -@node Symbols, Numbers, Declarations, Top -@chapter Symbols - -@noindent -This package defines several symbol-related features that were -missing from Emacs Lisp. - -@menu -* Property Lists:: `get*', `remprop', `getf', `remf' -* Creating Symbols:: `gensym', `gentemp' -@end menu - -@node Property Lists, Creating Symbols, Symbols, Symbols -@section Property Lists - -@noindent -These functions augment the standard Emacs Lisp functions @code{get} -and @code{put} for operating on properties attached to symbols. -There are also functions for working with property lists as -first-class data structures not attached to particular symbols. - -@defun get* symbol property &optional default -This function is like @code{get}, except that if the property is -not found, the @var{default} argument provides the return value. -(The Emacs Lisp @code{get} function always uses @code{nil} as -the default; this package's @code{get*} is equivalent to Common -Lisp's @code{get}.) - -The @code{get*} function is @code{setf}-able; when used in this -fashion, the @var{default} argument is allowed but ignored. -@end defun - -@defun remprop symbol property -This function removes the entry for @var{property} from the property -list of @var{symbol}. It returns a true value if the property was -indeed found and removed, or @code{nil} if there was no such property. -(This function was probably omitted from Emacs originally because, -since @code{get} did not allow a @var{default}, it was very difficult -to distinguish between a missing property and a property whose value -was @code{nil}; thus, setting a property to @code{nil} was close -enough to @code{remprop} for most purposes.) -@end defun - -@defun getf place property &optional default -This function scans the list @var{place} as if it were a property -list, i.e., a list of alternating property names and values. If -an even-numbered element of @var{place} is found which is @code{eq} -to @var{property}, the following odd-numbered element is returned. -Otherwise, @var{default} is returned (or @code{nil} if no default -is given). - -In particular, - -@example -(get sym prop) @equiv{} (getf (symbol-plist sym) prop) -@end example - -It is valid to use @code{getf} as a @code{setf} place, in which case -its @var{place} argument must itself be a valid @code{setf} place. -The @var{default} argument, if any, is ignored in this context. -The effect is to change (via @code{setcar}) the value cell in the -list that corresponds to @var{property}, or to cons a new property-value -pair onto the list if the property is not yet present. - -@example -(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) -@end example - -The @code{get} and @code{get*} functions are also @code{setf}-able. -The fact that @code{default} is ignored can sometimes be useful: - -@example -(incf (get* 'foo 'usage-count 0)) -@end example - -Here, symbol @code{foo}'s @code{usage-count} property is incremented -if it exists, or set to 1 (an incremented 0) otherwise. - -When not used as a @code{setf} form, @code{getf} is just a regular -function and its @var{place} argument can actually be any Lisp -expression. -@end defun - -@defspec remf place property -This macro removes the property-value pair for @var{property} from -the property list stored at @var{place}, which is any @code{setf}-able -place expression. It returns true if the property was found. Note -that if @var{property} happens to be first on the list, this will -effectively do a @code{(setf @var{place} (cddr @var{place}))}, -whereas if it occurs later, this simply uses @code{setcdr} to splice -out the property and value cells. -@end defspec - -@iftex -@secno=2 -@end iftex - -@node Creating Symbols, , Property Lists, Symbols -@section Creating Symbols - -@noindent -These functions create unique symbols, typically for use as -temporary variables. - -@defun gensym &optional x -This function creates a new, uninterned symbol (using @code{make-symbol}) -with a unique name. (The name of an uninterned symbol is relevant -only if the symbol is printed.) By default, the name is generated -from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, -@samp{G1002}, etc. If the optional argument @var{x} is a string, that -string is used as a prefix instead of @samp{G}. Uninterned symbols -are used in macro expansions for temporary variables, to ensure that -their names will not conflict with ``real'' variables in the user's -code. -@end defun - -@defvar *gensym-counter* -This variable holds the counter used to generate @code{gensym} names. -It is incremented after each use by @code{gensym}. In Common Lisp -this is initialized with 0, but this package initializes it with a -random (time-dependent) value to avoid trouble when two files that -each used @code{gensym} in their compilation are loaded together. -(Uninterned symbols become interned when the compiler writes them -out to a file and the Emacs loader loads them, so their names have to -be treated a bit more carefully than in Common Lisp where uninterned -symbols remain uninterned after loading.) -@end defvar - -@defun gentemp &optional x -This function is like @code{gensym}, except that it produces a new -@emph{interned} symbol. If the symbol that is generated already -exists, the function keeps incrementing the counter and trying -again until a new symbol is generated. -@end defun - -The Quiroz @file{cl.el} package also defined a @code{defkeyword} -form for creating self-quoting keyword symbols. This package -automatically creates all keywords that are called for by -@code{&key} argument specifiers, and discourages the use of -keywords as data unrelated to keyword arguments, so the -@code{defkeyword} form has been discontinued. - -@iftex -@chapno=11 -@end iftex - -@node Numbers, Sequences, Symbols, Top -@chapter Numbers - -@noindent -This section defines a few simple Common Lisp operations on numbers -which were left out of Emacs Lisp. - -@menu -* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. -* Numerical Functions:: `abs', `floor*', etc. -* Random Numbers:: `random*', `make-random-state' -* Implementation Parameters:: `most-positive-float' -@end menu - -@iftex -@secno=1 -@end iftex - -@node Predicates on Numbers, Numerical Functions, Numbers, Numbers -@section Predicates on Numbers - -@noindent -These functions return @code{t} if the specified condition is -true of the numerical argument, or @code{nil} otherwise. - -@defun plusp number -This predicate tests whether @var{number} is positive. It is an -error if the argument is not a number. -@end defun - -@defun minusp number -This predicate tests whether @var{number} is negative. It is an -error if the argument is not a number. -@end defun - -@defun oddp integer -This predicate tests whether @var{integer} is odd. It is an -error if the argument is not an integer. -@end defun - -@defun evenp integer -This predicate tests whether @var{integer} is even. It is an -error if the argument is not an integer. -@end defun - -@defun floatp-safe object -This predicate tests whether @var{object} is a floating-point -number. On systems that support floating-point, this is equivalent -to @code{floatp}. On other systems, this always returns @code{nil}. -@end defun - -@iftex -@secno=3 -@end iftex - -@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers -@section Numerical Functions - -@noindent -These functions perform various arithmetic operations on numbers. - -@defun gcd &rest integers -This function returns the Greatest Common Divisor of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns zero. -@end defun - -@defun lcm &rest integers -This function returns the Least Common Multiple of the arguments. -For one argument, it returns the absolute value of that argument. -For zero arguments, it returns one. -@end defun - -@defun isqrt integer -This function computes the ``integer square root'' of its integer -argument, i.e., the greatest integer less than or equal to the true -square root of the argument. -@end defun - -@defun floor* number &optional divisor -This function implements the Common Lisp @code{floor} function. -It is called @code{floor*} to avoid name conflicts with the -simpler @code{floor} function built-in to Emacs. - -With one argument, @code{floor*} returns a list of two numbers: -The argument rounded down (toward minus infinity) to an integer, -and the ``remainder'' which would have to be added back to the -first return value to yield the argument again. If the argument -is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. -If the argument is a floating-point number, the first -result is a Lisp integer and the second is a Lisp float between -0 (inclusive) and 1 (exclusive). - -With two arguments, @code{floor*} divides @var{number} by -@var{divisor}, and returns the floor of the quotient and the -corresponding remainder as a list of two numbers. If -@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})}, -then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} -between 0 (inclusive) and @var{r} (exclusive). Also, note -that @code{(floor* @var{x})} is exactly equivalent to -@code{(floor* @var{x} 1)}. - -This function is entirely compatible with Common Lisp's @code{floor} -function, except that it returns the two results in a list since -Emacs Lisp does not support multiple-valued functions. -@end defun - -@defun ceiling* number &optional divisor -This function implements the Common Lisp @code{ceiling} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments up toward plus infinity. -The remainder will be between 0 and minus @var{r}. -@end defun - -@defun truncate* number &optional divisor -This function implements the Common Lisp @code{truncate} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments toward zero. Thus it is -equivalent to @code{floor*} if the argument or quotient is -positive, or to @code{ceiling*} otherwise. The remainder has -the same sign as @var{number}. -@end defun - -@defun round* number &optional divisor -This function implements the Common Lisp @code{round} function, -which is analogous to @code{floor} except that it rounds the -argument or quotient of the arguments to the nearest integer. -In the case of a tie (the argument or quotient is exactly -halfway between two integers), it rounds to the even integer. -@end defun - -@defun mod* number divisor -This function returns the same value as the second return value -of @code{floor}. -@end defun - -@defun rem* number divisor -This function returns the same value as the second return value -of @code{truncate}. -@end defun - -These definitions are compatible with those in the Quiroz -@file{cl.el} package, except that this package appends @samp{*} -to certain function names to avoid conflicts with existing -Emacs functions, and that the mechanism for returning -multiple values is different. - -@iftex -@secno=8 -@end iftex - -@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers -@section Random Numbers - -@noindent -This package also provides an implementation of the Common Lisp -random number generator. It uses its own additive-congruential -algorithm, which is much more likely to give statistically clean -random numbers than the simple generators supplied by many -operating systems. - -@defun random* number &optional state -This function returns a random nonnegative number less than -@var{number}, and of the same type (either integer or floating-point). -The @var{state} argument should be a @code{random-state} object -which holds the state of the random number generator. The -function modifies this state object as a side effect. If -@var{state} is omitted, it defaults to the variable -@code{*random-state*}, which contains a pre-initialized -@code{random-state} object. -@end defun - -@defvar *random-state* -This variable contains the system ``default'' @code{random-state} -object, used for calls to @code{random*} that do not specify an -alternative state object. Since any number of programs in the -Emacs process may be accessing @code{*random-state*} in interleaved -fashion, the sequence generated from this variable will be -irreproducible for all intents and purposes. -@end defvar - -@defun make-random-state &optional state -This function creates or copies a @code{random-state} object. -If @var{state} is omitted or @code{nil}, it returns a new copy of -@code{*random-state*}. This is a copy in the sense that future -sequences of calls to @code{(random* @var{n})} and -@code{(random* @var{n} @var{s})} (where @var{s} is the new -random-state object) will return identical sequences of random -numbers. - -If @var{state} is a @code{random-state} object, this function -returns a copy of that object. If @var{state} is @code{t}, this -function returns a new @code{random-state} object seeded from the -date and time. As an extension to Common Lisp, @var{state} may also -be an integer in which case the new object is seeded from that -integer; each different integer seed will result in a completely -different sequence of random numbers. - -It is valid to print a @code{random-state} object to a buffer or -file and later read it back with @code{read}. If a program wishes -to use a sequence of pseudo-random numbers which can be reproduced -later for debugging, it can call @code{(make-random-state t)} to -get a new sequence, then print this sequence to a file. When the -program is later rerun, it can read the original run's random-state -from the file. -@end defun - -@defun random-state-p object -This predicate returns @code{t} if @var{object} is a -@code{random-state} object, or @code{nil} otherwise. -@end defun - -@node Implementation Parameters, , Random Numbers, Numbers -@section Implementation Parameters - -@noindent -This package defines several useful constants having to with numbers. - -The following parameters have to do with floating-point numbers. -This package determines their values by exercising the computer's -floating-point arithmetic in various ways. Because this operation -might be slow, the code for initializing them is kept in a separate -function that must be called before the parameters can be used. - -@defun cl-float-limits -This function makes sure that the Common Lisp floating-point parameters -like @code{most-positive-float} have been initialized. Until it is -called, these parameters will be @code{nil}. If this version of Emacs -does not support floats, the parameters will remain @code{nil}. If the -parameters have already been initialized, the function returns -immediately. - -The algorithm makes assumptions that will be valid for most modern -machines, but will fail if the machine's arithmetic is extremely -unusual, e.g., decimal. -@end defun - -Since true Common Lisp supports up to four different floating-point -precisions, it has families of constants like -@code{most-positive-single-float}, @code{most-positive-double-float}, -@code{most-positive-long-float}, and so on. Emacs has only one -floating-point precision, so this package omits the precision word -from the constants' names. - -@defvar most-positive-float -This constant equals the largest value a Lisp float can hold. -For those systems whose arithmetic supports infinities, this is -the largest @emph{finite} value. For IEEE machines, the value -is approximately @code{1.79e+308}. -@end defvar - -@defvar most-negative-float -This constant equals the most-negative value a Lisp float can hold. -(It is assumed to be equal to @code{(- most-positive-float)}.) -@end defvar - -@defvar least-positive-float -This constant equals the smallest Lisp float value greater than zero. -For IEEE machines, it is about @code{4.94e-324} if denormals are -supported or @code{2.22e-308} if not. -@end defvar - -@defvar least-positive-normalized-float -This constant equals the smallest @emph{normalized} Lisp float greater -than zero, i.e., the smallest value for which IEEE denormalization -will not result in a loss of precision. For IEEE machines, this -value is about @code{2.22e-308}. For machines that do not support -the concept of denormalization and gradual underflow, this constant -will always equal @code{least-positive-float}. -@end defvar - -@defvar least-negative-float -This constant is the negative counterpart of @code{least-positive-float}. -@end defvar - -@defvar least-negative-normalized-float -This constant is the negative counterpart of -@code{least-positive-normalized-float}. -@end defvar - -@defvar float-epsilon -This constant is the smallest positive Lisp float that can be added -to 1.0 to produce a distinct value. Adding a smaller number to 1.0 -will yield 1.0 again due to roundoff. For IEEE machines, epsilon -is about @code{2.22e-16}. -@end defvar - -@defvar float-negative-epsilon -This is the smallest positive value that can be subtracted from -1.0 to produce a distinct value. For IEEE machines, it is about -@code{1.11e-16}. -@end defvar - -@iftex -@chapno=13 -@end iftex - -@node Sequences, Lists, Numbers, Top -@chapter Sequences - -@noindent -Common Lisp defines a number of functions that operate on -@dfn{sequences}, which are either lists, strings, or vectors. -Emacs Lisp includes a few of these, notably @code{elt} and -@code{length}; this package defines most of the rest. - -@menu -* Sequence Basics:: Arguments shared by all sequence functions -* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. -* Sequence Functions:: `subseq', `remove*', `substitute', etc. -* Searching Sequences:: `find', `position', `count', `search', etc. -* Sorting Sequences:: `sort*', `stable-sort', `merge' -@end menu - -@node Sequence Basics, Mapping over Sequences, Sequences, Sequences -@section Sequence Basics - -@noindent -Many of the sequence functions take keyword arguments; @pxref{Argument -Lists}. All keyword arguments are optional and, if specified, -may appear in any order. - -The @code{:key} argument should be passed either @code{nil}, or a -function of one argument. This key function is used as a filter -through which the elements of the sequence are seen; for example, -@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: -It searches for an element of the list whose @code{car} equals -@code{x}, rather than for an element which equals @code{x} itself. -If @code{:key} is omitted or @code{nil}, the filter is effectively -the identity function. - -The @code{:test} and @code{:test-not} arguments should be either -@code{nil}, or functions of two arguments. The test function is -used to compare two sequence elements, or to compare a search value -with sequence elements. (The two values are passed to the test -function in the same order as the original sequence function -arguments from which they are derived, or, if they both come from -the same sequence, in the same order as they appear in that sequence.) -The @code{:test} argument specifies a function which must return -true (non-@code{nil}) to indicate a match; instead, you may use -@code{:test-not} to give a function which returns @emph{false} to -indicate a match. The default test function is @code{eql}. - -Many functions which take @var{item} and @code{:test} or @code{:test-not} -arguments also come in @code{-if} and @code{-if-not} varieties, -where a @var{predicate} function is passed instead of @var{item}, -and sequence elements match if the predicate returns true on them -(or false in the case of @code{-if-not}). For example: - -@example -(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) -@end example - -@noindent -to remove all zeros from sequence @code{seq}. - -Some operations can work on a subsequence of the argument sequence; -these function take @code{:start} and @code{:end} arguments which -default to zero and the length of the sequence, respectively. -Only elements between @var{start} (inclusive) and @var{end} -(exclusive) are affected by the operation. The @var{end} argument -may be passed @code{nil} to signify the length of the sequence; -otherwise, both @var{start} and @var{end} must be integers, with -@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. -If the function takes two sequence arguments, the limits are -defined by keywords @code{:start1} and @code{:end1} for the first, -and @code{:start2} and @code{:end2} for the second. - -A few functions accept a @code{:from-end} argument, which, if -non-@code{nil}, causes the operation to go from right-to-left -through the sequence instead of left-to-right, and a @code{:count} -argument, which specifies an integer maximum number of elements -to be removed or otherwise processed. - -The sequence functions make no guarantees about the order in -which the @code{:test}, @code{:test-not}, and @code{:key} functions -are called on various elements. Therefore, it is a bad idea to depend -on side effects of these functions. For example, @code{:from-end} -may cause the sequence to be scanned actually in reverse, or it may -be scanned forwards but computing a result ``as if'' it were scanned -backwards. (Some functions, like @code{mapcar*} and @code{every}, -@emph{do} specify exactly the order in which the function is called -so side effects are perfectly acceptable in those cases.) - -Strings may contain ``text properties'' as well -as character data. Except as noted, it is undefined whether or -not text properties are preserved by sequence functions. For -example, @code{(remove* ?A @var{str})} may or may not preserve -the properties of the characters copied from @var{str} into the -result. - -@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences -@section Mapping over Sequences - -@noindent -These functions ``map'' the function you specify over the elements -of lists or arrays. They are all variations on the theme of the -built-in function @code{mapcar}. - -@defun mapcar* function seq &rest more-seqs -This function calls @var{function} on successive parallel sets of -elements from its argument sequences. Given a single @var{seq} -argument it is equivalent to @code{mapcar}; given @var{n} sequences, -it calls the function with the first elements of each of the sequences -as the @var{n} arguments to yield the first element of the result -list, then with the second elements, and so on. The mapping stops as -soon as the shortest sequence runs out. The argument sequences may -be any mixture of lists, strings, and vectors; the return sequence -is always a list. - -Common Lisp's @code{mapcar} accepts multiple arguments but works -only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence -argument. This package's @code{mapcar*} works as a compatible -superset of both. -@end defun - -@defun map result-type function seq &rest more-seqs -This function maps @var{function} over the argument sequences, -just like @code{mapcar*}, but it returns a sequence of type -@var{result-type} rather than a list. @var{result-type} must -be one of the following symbols: @code{vector}, @code{string}, -@code{list} (in which case the effect is the same as for -@code{mapcar*}), or @code{nil} (in which case the results are -thrown away and @code{map} returns @code{nil}). -@end defun - -@defun maplist function list &rest more-lists -This function calls @var{function} on each of its argument lists, -then on the @code{cdr}s of those lists, and so on, until the -shortest list runs out. The results are returned in the form -of a list. Thus, @code{maplist} is like @code{mapcar*} except -that it passes in the list pointers themselves rather than the -@code{car}s of the advancing pointers. -@end defun - -@defun mapc function seq &rest more-seqs -This function is like @code{mapcar*}, except that the values returned -by @var{function} are ignored and thrown away rather than being -collected into a list. The return value of @code{mapc} is @var{seq}, -the first sequence. This function is more general than the Emacs -primitive @code{mapc}. -@end defun - -@defun mapl function list &rest more-lists -This function is like @code{maplist}, except that it throws away -the values returned by @var{function}. -@end defun - -@defun mapcan function seq &rest more-seqs -This function is like @code{mapcar*}, except that it concatenates -the return values (which must be lists) using @code{nconc}, -rather than simply collecting them into a list. -@end defun - -@defun mapcon function list &rest more-lists -This function is like @code{maplist}, except that it concatenates -the return values using @code{nconc}. -@end defun - -@defun some predicate seq &rest more-seqs -This function calls @var{predicate} on each element of @var{seq} -in turn; if @var{predicate} returns a non-@code{nil} value, -@code{some} returns that value, otherwise it returns @code{nil}. -Given several sequence arguments, it steps through the sequences -in parallel until the shortest one runs out, just as in -@code{mapcar*}. You can rely on the left-to-right order in which -the elements are visited, and on the fact that mapping stops -immediately as soon as @var{predicate} returns non-@code{nil}. -@end defun - -@defun every predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -@code{nil} for any element, or @code{t} if the predicate was true -for all elements. -@end defun - -@defun notany predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns @code{nil} as soon as @var{predicate} returns -a non-@code{nil} value for any element, or @code{t} if the predicate -was @code{nil} for all elements. -@end defun - -@defun notevery predicate seq &rest more-seqs -This function calls @var{predicate} on each element of the sequence(s) -in turn; it returns a non-@code{nil} value as soon as @var{predicate} -returns @code{nil} for any element, or @code{t} if the predicate was -true for all elements. -@end defun - -@defun reduce function seq @t{&key :from-end :start :end :initial-value :key} -This function combines the elements of @var{seq} using an associative -binary operation. Suppose @var{function} is @code{*} and @var{seq} is -the list @code{(2 3 4 5)}. The first two elements of the list are -combined with @code{(* 2 3) = 6}; this is combined with the next -element, @code{(* 6 4) = 24}, and that is combined with the final -element: @code{(* 24 5) = 120}. Note that the @code{*} function happens -to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as -an explicit call to @code{reduce}. - -If @code{:from-end} is true, the reduction is right-associative instead -of left-associative: - -@example -(reduce '- '(1 2 3 4)) - @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 -(reduce '- '(1 2 3 4) :from-end t) - @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 -@end example - -If @code{:key} is specified, it is a function of one argument which -is called on each of the sequence elements in turn. - -If @code{:initial-value} is specified, it is effectively added to the -front (or rear in the case of @code{:from-end}) of the sequence. -The @code{:key} function is @emph{not} applied to the initial value. - -If the sequence, including the initial value, has exactly one element -then that element is returned without ever calling @var{function}. -If the sequence is empty (and there is no initial value), then -@var{function} is called with no arguments to obtain the return value. -@end defun - -All of these mapping operations can be expressed conveniently in -terms of the @code{loop} macro. In compiled code, @code{loop} will -be faster since it generates the loop as in-line code with no -function calls. - -@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences -@section Sequence Functions - -@noindent -This section describes a number of Common Lisp functions for -operating on sequences. - -@defun subseq sequence start &optional end -This function returns a given subsequence of the argument -@var{sequence}, which may be a list, string, or vector. -The indices @var{start} and @var{end} must be in range, and -@var{start} must be no greater than @var{end}. If @var{end} -is omitted, it defaults to the length of the sequence. The -return value is always a copy; it does not share structure -with @var{sequence}. - -As an extension to Common Lisp, @var{start} and/or @var{end} -may be negative, in which case they represent a distance back -from the end of the sequence. This is for compatibility with -Emacs' @code{substring} function. Note that @code{subseq} is -the @emph{only} sequence function that allows negative -@var{start} and @var{end}. - -You can use @code{setf} on a @code{subseq} form to replace a -specified range of elements with elements from another sequence. -The replacement is done as if by @code{replace}, described below. -@end defun - -@defun concatenate result-type &rest seqs -This function concatenates the argument sequences together to -form a result sequence of type @var{result-type}, one of the -symbols @code{vector}, @code{string}, or @code{list}. The -arguments are always copied, even in cases such as -@code{(concatenate 'list '(1 2 3))} where the result is -identical to an argument. -@end defun - -@defun fill seq item @t{&key :start :end} -This function fills the elements of the sequence (or the specified -part of the sequence) with the value @var{item}. -@end defun - -@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} -This function copies part of @var{seq2} into part of @var{seq1}. -The sequence @var{seq1} is not stretched or resized; the amount -of data copied is simply the shorter of the source and destination -(sub)sequences. The function returns @var{seq1}. - -If @var{seq1} and @var{seq2} are @code{eq}, then the replacement -will work correctly even if the regions indicated by the start -and end arguments overlap. However, if @var{seq1} and @var{seq2} -are lists which share storage but are not @code{eq}, and the -start and end arguments specify overlapping regions, the effect -is undefined. -@end defun - -@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} -This returns a copy of @var{seq} with all elements matching -@var{item} removed. The result may share storage with or be -@code{eq} to @var{seq} in some circumstances, but the original -@var{seq} will not be modified. The @code{:test}, @code{:test-not}, -and @code{:key} arguments define the matching test that is used; -by default, elements @code{eql} to @var{item} are removed. The -@code{:count} argument specifies the maximum number of matching -elements that can be removed (only the leftmost @var{count} matches -are removed). The @code{:start} and @code{:end} arguments specify -a region in @var{seq} in which elements will be removed; elements -outside that region are not matched or removed. The @code{:from-end} -argument, if true, says that elements should be deleted from the -end of the sequence rather than the beginning (this matters only -if @var{count} was also specified). -@end defun - -@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} -This deletes all elements of @var{seq} which match @var{item}. -It is a destructive operation. Since Emacs Lisp does not support -stretchable strings or vectors, this is the same as @code{remove*} -for those sequence types. On lists, @code{remove*} will copy the -list if necessary to preserve the original list, whereas -@code{delete*} will splice out parts of the argument list. -Compare @code{append} and @code{nconc}, which are analogous -non-destructive and destructive list operations in Emacs Lisp. -@end defun - -@findex remove-if -@findex remove-if-not -@findex delete-if -@findex delete-if-not -The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, -@code{delete-if}, and @code{delete-if-not} are defined similarly. - -@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function returns a copy of @var{seq} with duplicate elements -removed. Specifically, if two elements from the sequence match -according to the @code{:test}, @code{:test-not}, and @code{:key} -arguments, only the rightmost one is retained. If @code{:from-end} -is true, the leftmost one is retained instead. If @code{:start} or -@code{:end} is specified, only elements within that subsequence are -examined or removed. -@end defun - -@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} -This function deletes duplicate elements from @var{seq}. It is -a destructive version of @code{remove-duplicates}. -@end defun - -@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This function returns a copy of @var{seq}, with all elements -matching @var{old} replaced with @var{new}. The @code{:count}, -@code{:start}, @code{:end}, and @code{:from-end} arguments may be -used to limit the number of substitutions made. -@end defun - -@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} -This is a destructive version of @code{substitute}; it performs -the substitution using @code{setcar} or @code{aset} rather than -by returning a changed copy of the sequence. -@end defun - -@findex substitute-if -@findex substitute-if-not -@findex nsubstitute-if -@findex nsubstitute-if-not -The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, -and @code{nsubstitute-if-not} functions are defined similarly. For -these, a @var{predicate} is given in place of the @var{old} argument. - -@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences -@section Searching Sequences - -@noindent -These functions search for elements or subsequences in a sequence. -(See also @code{member*} and @code{assoc*}; @pxref{Lists}.) - -@defun find item seq @t{&key :test :test-not :key :start :end :from-end} -This function searches @var{seq} for an element matching @var{item}. -If it finds a match, it returns the matching element. Otherwise, -it returns @code{nil}. It returns the leftmost match, unless -@code{:from-end} is true, in which case it returns the rightmost -match. The @code{:start} and @code{:end} arguments may be used to -limit the range of elements that are searched. -@end defun - -@defun position item seq @t{&key :test :test-not :key :start :end :from-end} -This function is like @code{find}, except that it returns the -integer position in the sequence of the matching item rather than -the item itself. The position is relative to the start of the -sequence as a whole, even if @code{:start} is non-zero. The function -returns @code{nil} if no matching element was found. -@end defun - -@defun count item seq @t{&key :test :test-not :key :start :end} -This function returns the number of elements of @var{seq} which -match @var{item}. The result is always a nonnegative integer. -@end defun - -@findex find-if -@findex find-if-not -@findex position-if -@findex position-if-not -@findex count-if -@findex count-if-not -The @code{find-if}, @code{find-if-not}, @code{position-if}, -@code{position-if-not}, @code{count-if}, and @code{count-if-not} -functions are defined similarly. - -@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} -This function compares the specified parts of @var{seq1} and -@var{seq2}. If they are the same length and the corresponding -elements match (according to @code{:test}, @code{:test-not}, -and @code{:key}), the function returns @code{nil}. If there is -a mismatch, the function returns the index (relative to @var{seq1}) -of the first mismatching element. This will be the leftmost pair of -elements which do not match, or the position at which the shorter of -the two otherwise-matching sequences runs out. - -If @code{:from-end} is true, then the elements are compared from right -to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. -If the sequences differ, then one plus the index of the rightmost -difference (relative to @var{seq1}) is returned. - -An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, -which compares two strings case-insensitively. -@end defun - -@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} -This function searches @var{seq2} for a subsequence that matches -@var{seq1} (or part of it specified by @code{:start1} and -@code{:end1}.) Only matches which fall entirely within the region -defined by @code{:start2} and @code{:end2} will be considered. -The return value is the index of the leftmost element of the -leftmost match, relative to the start of @var{seq2}, or @code{nil} -if no matches were found. If @code{:from-end} is true, the -function finds the @emph{rightmost} matching subsequence. -@end defun - -@node Sorting Sequences, , Searching Sequences, Sequences -@section Sorting Sequences - -@defun sort* seq predicate @t{&key :key} -This function sorts @var{seq} into increasing order as determined -by using @var{predicate} to compare pairs of elements. @var{predicate} -should return true (non-@code{nil}) if and only if its first argument -is less than (not equal to) its second argument. For example, -@code{<} and @code{string-lessp} are suitable predicate functions -for sorting numbers and strings, respectively; @code{>} would sort -numbers into decreasing rather than increasing order. - -This function differs from Emacs' built-in @code{sort} in that it -can operate on any type of sequence, not just lists. Also, it -accepts a @code{:key} argument which is used to preprocess data -fed to the @var{predicate} function. For example, - -@example -(setq data (sort* data 'string-lessp :key 'downcase)) -@end example - -@noindent -sorts @var{data}, a sequence of strings, into increasing alphabetical -order without regard to case. A @code{:key} function of @code{car} -would be useful for sorting association lists. It should only be a -simple accessor though, it's used heavily in the current -implementation. - -The @code{sort*} function is destructive; it sorts lists by actually -rearranging the @code{cdr} pointers in suitable fashion. -@end defun - -@defun stable-sort seq predicate @t{&key :key} -This function sorts @var{seq} @dfn{stably}, meaning two elements -which are equal in terms of @var{predicate} are guaranteed not to -be rearranged out of their original order by the sort. - -In practice, @code{sort*} and @code{stable-sort} are equivalent -in Emacs Lisp because the underlying @code{sort} function is -stable by default. However, this package reserves the right to -use non-stable methods for @code{sort*} in the future. -@end defun - -@defun merge type seq1 seq2 predicate @t{&key :key} -This function merges two sequences @var{seq1} and @var{seq2} by -interleaving their elements. The result sequence, of type @var{type} -(in the sense of @code{concatenate}), has length equal to the sum -of the lengths of the two input sequences. The sequences may be -modified destructively. Order of elements within @var{seq1} and -@var{seq2} is preserved in the interleaving; elements of the two -sequences are compared by @var{predicate} (in the sense of -@code{sort}) and the lesser element goes first in the result. -When elements are equal, those from @var{seq1} precede those from -@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are -both sorted according to @var{predicate}, then the result will be -a merged sequence which is (stably) sorted according to -@var{predicate}. -@end defun - -@node Lists, Structures, Sequences, Top -@chapter Lists - -@noindent -The functions described here operate on lists. - -@menu -* List Functions:: `caddr', `first', `list*', etc. -* Substitution of Expressions:: `subst', `sublis', etc. -* Lists as Sets:: `member*', `adjoin', `union', etc. -* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' -@end menu - -@node List Functions, Substitution of Expressions, Lists, Lists -@section List Functions - -@noindent -This section describes a number of simple operations on lists, -i.e., chains of cons cells. - -@defun caddr x -This function is equivalent to @code{(car (cdr (cdr @var{x})))}. -Likewise, this package defines all 28 @code{c@var{xxx}r} functions -where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. -All of these functions are @code{setf}-able, and calls to them -are expanded inline by the byte-compiler for maximum efficiency. -@end defun - -@defun first x -This function is a synonym for @code{(car @var{x})}. Likewise, -the functions @code{second}, @code{third}, @dots{}, through -@code{tenth} return the given element of the list @var{x}. -@end defun - -@defun rest x -This function is a synonym for @code{(cdr @var{x})}. -@end defun - -@defun endp x -Common Lisp defines this function to act like @code{null}, but -signaling an error if @code{x} is neither a @code{nil} nor a -cons cell. This package simply defines @code{endp} as a synonym -for @code{null}. -@end defun - -@defun list-length x -This function returns the length of list @var{x}, exactly like -@code{(length @var{x})}, except that if @var{x} is a circular -list (where the cdr-chain forms a loop rather than terminating -with @code{nil}), this function returns @code{nil}. (The regular -@code{length} function would get stuck if given a circular list.) -@end defun - -@defun list* arg &rest others -This function constructs a list of its arguments. The final -argument becomes the @code{cdr} of the last cell constructed. -Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to -@code{(cons @var{a} (cons @var{b} @var{c}))}, and -@code{(list* @var{a} @var{b} nil)} is equivalent to -@code{(list @var{a} @var{b})}. - -(Note that this function really is called @code{list*} in Common -Lisp; it is not a name invented for this package like @code{member*} -or @code{defun*}.) -@end defun - -@defun ldiff list sublist -If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to -one of the cons cells of @var{list}, then this function returns -a copy of the part of @var{list} up to but not including -@var{sublist}. For example, @code{(ldiff x (cddr x))} returns -the first two elements of the list @code{x}. The result is a -copy; the original @var{list} is not modified. If @var{sublist} -is not a sublist of @var{list}, a copy of the entire @var{list} -is returned. -@end defun - -@defun copy-list list -This function returns a copy of the list @var{list}. It copies -dotted lists like @code{(1 2 . 3)} correctly. -@end defun - -@defun copy-tree x &optional vecp -This function returns a copy of the tree of cons cells @var{x}. -Unlike @code{copy-sequence} (and its alias @code{copy-list}), -which copies only along the @code{cdr} direction, this function -copies (recursively) along both the @code{car} and the @code{cdr} -directions. If @var{x} is not a cons cell, the function simply -returns @var{x} unchanged. If the optional @var{vecp} argument -is true, this function copies vectors (recursively) as well as -cons cells. -@end defun - -@defun tree-equal x y @t{&key :test :test-not :key} -This function compares two trees of cons cells. If @var{x} and -@var{y} are both cons cells, their @code{car}s and @code{cdr}s are -compared recursively. If neither @var{x} nor @var{y} is a cons -cell, they are compared by @code{eql}, or according to the -specified test. The @code{:key} function, if specified, is -applied to the elements of both trees. @xref{Sequences}. -@end defun - -@iftex -@secno=3 -@end iftex - -@node Substitution of Expressions, Lists as Sets, List Functions, Lists -@section Substitution of Expressions - -@noindent -These functions substitute elements throughout a tree of cons -cells. (@xref{Sequence Functions}, for the @code{substitute} -function, which works on just the top-level elements of a list.) - -@defun subst new old tree @t{&key :test :test-not :key} -This function substitutes occurrences of @var{old} with @var{new} -in @var{tree}, a tree of cons cells. It returns a substituted -tree, which will be a copy except that it may share storage with -the argument @var{tree} in parts where no substitutions occurred. -The original @var{tree} is not modified. This function recurses -on, and compares against @var{old}, both @code{car}s and @code{cdr}s -of the component cons cells. If @var{old} is itself a cons cell, -then matching cells in the tree are substituted as usual without -recursively substituting in that cell. Comparisons with @var{old} -are done according to the specified test (@code{eql} by default). -The @code{:key} function is applied to the elements of the tree -but not to @var{old}. -@end defun - -@defun nsubst new old tree @t{&key :test :test-not :key} -This function is like @code{subst}, except that it works by -destructive modification (by @code{setcar} or @code{setcdr}) -rather than copying. -@end defun - -@findex subst-if -@findex subst-if-not -@findex nsubst-if -@findex nsubst-if-not -The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and -@code{nsubst-if-not} functions are defined similarly. - -@defun sublis alist tree @t{&key :test :test-not :key} -This function is like @code{subst}, except that it takes an -association list @var{alist} of @var{old}-@var{new} pairs. -Each element of the tree (after applying the @code{:key} -function, if any), is compared with the @code{car}s of -@var{alist}; if it matches, it is replaced by the corresponding -@code{cdr}. -@end defun - -@defun nsublis alist tree @t{&key :test :test-not :key} -This is a destructive version of @code{sublis}. -@end defun - -@node Lists as Sets, Association Lists, Substitution of Expressions, Lists -@section Lists as Sets - -@noindent -These functions perform operations on lists which represent sets -of elements. - -@defun member* item list @t{&key :test :test-not :key} -This function searches @var{list} for an element matching @var{item}. -If a match is found, it returns the cons cell whose @code{car} was -the matching element. Otherwise, it returns @code{nil}. Elements -are compared by @code{eql} by default; you can use the @code{:test}, -@code{:test-not}, and @code{:key} arguments to modify this behavior. -@xref{Sequences}. - -Note that this function's name is suffixed by @samp{*} to avoid -the incompatible @code{member} function defined in Emacs. -(That function uses @code{equal} for comparisons; it is equivalent -to @code{(member* @var{item} @var{list} :test 'equal)}.) -@end defun - -@findex member-if -@findex member-if-not -The @code{member-if} and @code{member-if-not} functions -analogously search for elements which satisfy a given predicate. - -@defun tailp sublist list -This function returns @code{t} if @var{sublist} is a sublist of -@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to -any of its @code{cdr}s. -@end defun - -@defun adjoin item list @t{&key :test :test-not :key} -This function conses @var{item} onto the front of @var{list}, -like @code{(cons @var{item} @var{list})}, but only if @var{item} -is not already present on the list (as determined by @code{member*}). -If a @code{:key} argument is specified, it is applied to -@var{item} as well as to the elements of @var{list} during -the search, on the reasoning that @var{item} is ``about'' to -become part of the list. -@end defun - -@defun union list1 list2 @t{&key :test :test-not :key} -This function combines two lists which represent sets of items, -returning a list that represents the union of those two sets. -The result list will contain all items which appear in @var{list1} -or @var{list2}, and no others. If an item appears in both -@var{list1} and @var{list2} it will be copied only once. If -an item is duplicated in @var{list1} or @var{list2}, it is -undefined whether or not that duplication will survive in the -result list. The order of elements in the result list is also -undefined. -@end defun - -@defun nunion list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{union}; rather than copying, -it tries to reuse the storage of the argument lists if possible. -@end defun - -@defun intersection list1 list2 @t{&key :test :test-not :key} -This function computes the intersection of the sets represented -by @var{list1} and @var{list2}. It returns the list of items -which appear in both @var{list1} and @var{list2}. -@end defun - -@defun nintersection list1 list2 @t{&key :test :test-not :key} -This is a destructive version of @code{intersection}. It -tries to reuse storage of @var{list1} rather than copying. -It does @emph{not} reuse the storage of @var{list2}. -@end defun - -@defun set-difference list1 list2 @t{&key :test :test-not :key} -This function computes the ``set difference'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -@var{list1} but @emph{not} in @var{list2}. -@end defun - -@defun nset-difference list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{set-difference}, which will try -to reuse @var{list1} if possible. -@end defun - -@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} -This function computes the ``set exclusive or'' of @var{list1} -and @var{list2}, i.e., the set of elements that appear in -exactly one of @var{list1} and @var{list2}. -@end defun - -@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} -This is a destructive @code{set-exclusive-or}, which will try -to reuse @var{list1} and @var{list2} if possible. -@end defun - -@defun subsetp list1 list2 @t{&key :test :test-not :key} -This function checks whether @var{list1} represents a subset -of @var{list2}, i.e., whether every element of @var{list1} -also appears in @var{list2}. -@end defun - -@node Association Lists, , Lists as Sets, Lists -@section Association Lists - -@noindent -An @dfn{association list} is a list representing a mapping from -one set of values to another; any list whose elements are cons -cells is an association list. - -@defun assoc* item a-list @t{&key :test :test-not :key} -This function searches the association list @var{a-list} for an -element whose @code{car} matches (in the sense of @code{:test}, -@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) -a given @var{item}. It returns the matching element, if any, -otherwise @code{nil}. It ignores elements of @var{a-list} which -are not cons cells. (This corresponds to the behavior of -@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's -@code{assoc} ignores @code{nil}s but considers any other non-cons -elements of @var{a-list} to be an error.) -@end defun - -@defun rassoc* item a-list @t{&key :test :test-not :key} -This function searches for an element whose @code{cdr} matches -@var{item}. If @var{a-list} represents a mapping, this applies -the inverse of the mapping to @var{item}. -@end defun - -@findex assoc-if -@findex assoc-if-not -@findex rassoc-if -@findex rassoc-if-not -The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, -and @code{rassoc-if-not} functions are defined similarly. - -Two simple functions for constructing association lists are: - -@defun acons key value alist -This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. -@end defun - -@defun pairlis keys values &optional alist -This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) -@var{alist})}. -@end defun - -@iftex -@chapno=18 -@end iftex - -@node Structures, Assertions, Lists, Top -@chapter Structures - -@noindent -The Common Lisp @dfn{structure} mechanism provides a general way -to define data types similar to C's @code{struct} types. A -structure is a Lisp object containing some number of @dfn{slots}, -each of which can hold any Lisp data object. Functions are -provided for accessing and setting the slots, creating or copying -structure objects, and recognizing objects of a particular structure -type. - -In true Common Lisp, each structure type is a new type distinct -from all existing Lisp types. Since the underlying Emacs Lisp -system provides no way to create new distinct types, this package -implements structures as vectors (or lists upon request) with a -special ``tag'' symbol to identify them. - -@defspec defstruct name slots@dots{} -The @code{defstruct} form defines a new structure type called -@var{name}, with the specified @var{slots}. (The @var{slots} -may begin with a string which documents the structure type.) -In the simplest case, @var{name} and each of the @var{slots} -are symbols. For example, - -@example -(defstruct person name age sex) -@end example - -@noindent -defines a struct type called @code{person} which contains three -slots. Given a @code{person} object @var{p}, you can access those -slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, -and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms: - -@example -(incf (person-age birthday-boy)) -@end example - -You can create a new @code{person} by calling @code{make-person}, -which takes keyword arguments @code{:name}, @code{:age}, and -@code{:sex} to specify the initial values of these slots in the -new object. (Omitting any of these arguments leaves the corresponding -slot ``undefined,'' according to the Common Lisp standard; in Emacs -Lisp, such uninitialized slots are filled with @code{nil}.) - -Given a @code{person}, @code{(copy-person @var{p})} makes a new -object of the same type whose slots are @code{eq} to those of @var{p}. - -Given any Lisp object @var{x}, @code{(person-p @var{x})} returns -true if @var{x} looks like a @code{person}, false otherwise. (Again, -in Common Lisp this predicate would be exact; in Emacs Lisp the -best it can do is verify that @var{x} is a vector of the correct -length which starts with the correct tag symbol.) - -Accessors like @code{person-name} normally check their arguments -(effectively using @code{person-p}) and signal an error if the -argument is the wrong type. This check is affected by -@code{(optimize (safety @dots{}))} declarations. Safety level 1, -the default, uses a somewhat optimized check that will detect all -incorrect arguments, but may use an uninformative error message -(e.g., ``expected a vector'' instead of ``expected a @code{person}''). -Safety level 0 omits all checks except as provided by the underlying -@code{aref} call; safety levels 2 and 3 do rigorous checking that will -always print a descriptive error message for incorrect inputs. -@xref{Declarations}. - -@example -(setq dave (make-person :name "Dave" :sex 'male)) - @result{} [cl-struct-person "Dave" nil male] -(setq other (copy-person dave)) - @result{} [cl-struct-person "Dave" nil male] -(eq dave other) - @result{} nil -(eq (person-name dave) (person-name other)) - @result{} t -(person-p dave) - @result{} t -(person-p [1 2 3 4]) - @result{} nil -(person-p "Bogus") - @result{} nil -(person-p '[cl-struct-person counterfeit person object]) - @result{} t -@end example - -In general, @var{name} is either a name symbol or a list of a name -symbol followed by any number of @dfn{struct options}; each @var{slot} -is either a slot symbol or a list of the form @samp{(@var{slot-name} -@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} -is a Lisp form which is evaluated any time an instance of the -structure type is created without specifying that slot's value. - -Common Lisp defines several slot options, but the only one -implemented in this package is @code{:read-only}. A non-@code{nil} -value for this option means the slot should not be @code{setf}-able; -the slot's value is determined when the object is created and does -not change afterward. - -@example -(defstruct person - (name nil :read-only t) - age - (sex 'unknown)) -@end example - -Any slot options other than @code{:read-only} are ignored. - -For obscure historical reasons, structure options take a different -form than slot options. A structure option is either a keyword -symbol, or a list beginning with a keyword symbol possibly followed -by arguments. (By contrast, slot options are key-value pairs not -enclosed in lists.) - -@example -(defstruct (person (:constructor create-person) - (:type list) - :named) - name age sex) -@end example - -The following structure options are recognized. - -@table @code -@iftex -@itemmax=0 in -@advance@leftskip-.5@tableindent -@end iftex -@item :conc-name -The argument is a symbol whose print name is used as the prefix for -the names of slot accessor functions. The default is the name of -the struct type followed by a hyphen. The option @code{(:conc-name p-)} -would change this prefix to @code{p-}. Specifying @code{nil} as an -argument means no prefix, so that the slot names themselves are used -to name the accessor functions. - -@item :constructor -In the simple case, this option takes one argument which is an -alternate name to use for the constructor function. The default -is @code{make-@var{name}}, e.g., @code{make-person}. The above -example changes this to @code{create-person}. Specifying @code{nil} -as an argument means that no standard constructor should be -generated at all. - -In the full form of this option, the constructor name is followed -by an arbitrary argument list. @xref{Program Structure}, for a -description of the format of Common Lisp argument lists. All -options, such as @code{&rest} and @code{&key}, are supported. -The argument names should match the slot names; each slot is -initialized from the corresponding argument. Slots whose names -do not appear in the argument list are initialized based on the -@var{default-value} in their slot descriptor. Also, @code{&optional} -and @code{&key} arguments which don't specify defaults take their -defaults from the slot descriptor. It is valid to include arguments -which don't correspond to slot names; these are useful if they are -referred to in the defaults for optional, keyword, or @code{&aux} -arguments which @emph{do} correspond to slots. - -You can specify any number of full-format @code{:constructor} -options on a structure. The default constructor is still generated -as well unless you disable it with a simple-format @code{:constructor} -option. - -@example -(defstruct - (person - (:constructor nil) ; no default constructor - (:constructor new-person (name sex &optional (age 0))) - (:constructor new-hound (&key (name "Rover") - (dog-years 0) - &aux (age (* 7 dog-years)) - (sex 'canine)))) - name age sex) -@end example - -The first constructor here takes its arguments positionally rather -than by keyword. (In official Common Lisp terminology, constructors -that work By Order of Arguments instead of by keyword are called -``BOA constructors.'' No, I'm not making this up.) For example, -@code{(new-person "Jane" 'female)} generates a person whose slots -are @code{"Jane"}, 0, and @code{female}, respectively. - -The second constructor takes two keyword arguments, @code{:name}, -which initializes the @code{name} slot and defaults to @code{"Rover"}, -and @code{:dog-years}, which does not itself correspond to a slot -but which is used to initialize the @code{age} slot. The @code{sex} -slot is forced to the symbol @code{canine} with no syntax for -overriding it. - -@item :copier -The argument is an alternate name for the copier function for -this type. The default is @code{copy-@var{name}}. @code{nil} -means not to generate a copier function. (In this implementation, -all copier functions are simply synonyms for @code{copy-sequence}.) - -@item :predicate -The argument is an alternate name for the predicate which recognizes -objects of this type. The default is @code{@var{name}-p}. @code{nil} -means not to generate a predicate function. (If the @code{:type} -option is used without the @code{:named} option, no predicate is -ever generated.) - -In true Common Lisp, @code{typep} is always able to recognize a -structure object even if @code{:predicate} was used. In this -package, @code{typep} simply looks for a function called -@code{@var{typename}-p}, so it will work for structure types -only if they used the default predicate name. - -@item :include -This option implements a very limited form of C++-style inheritance. -The argument is the name of another structure type previously -created with @code{defstruct}. The effect is to cause the new -structure type to inherit all of the included structure's slots -(plus, of course, any new slots described by this struct's slot -descriptors). The new structure is considered a ``specialization'' -of the included one. In fact, the predicate and slot accessors -for the included type will also accept objects of the new type. - -If there are extra arguments to the @code{:include} option after -the included-structure name, these options are treated as replacement -slot descriptors for slots in the included structure, possibly with -modified default values. Borrowing an example from Steele: - -@example -(defstruct person name (age 0) sex) - @result{} person -(defstruct (astronaut (:include person (age 45))) - helmet-size - (favorite-beverage 'tang)) - @result{} astronaut - -(setq joe (make-person :name "Joe")) - @result{} [cl-struct-person "Joe" 0 nil] -(setq buzz (make-astronaut :name "Buzz")) - @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] - -(list (person-p joe) (person-p buzz)) - @result{} (t t) -(list (astronaut-p joe) (astronaut-p buzz)) - @result{} (nil t) - -(person-name buzz) - @result{} "Buzz" -(astronaut-name joe) - @result{} error: "astronaut-name accessing a non-astronaut" -@end example - -Thus, if @code{astronaut} is a specialization of @code{person}, -then every @code{astronaut} is also a @code{person} (but not the -other way around). Every @code{astronaut} includes all the slots -of a @code{person}, plus extra slots that are specific to -astronauts. Operations that work on people (like @code{person-name}) -work on astronauts just like other people. - -@item :print-function -In full Common Lisp, this option allows you to specify a function -which is called to print an instance of the structure type. The -Emacs Lisp system offers no hooks into the Lisp printer which would -allow for such a feature, so this package simply ignores -@code{:print-function}. - -@item :type -The argument should be one of the symbols @code{vector} or @code{list}. -This tells which underlying Lisp data type should be used to implement -the new structure type. Vectors are used by default, but -@code{(:type list)} will cause structure objects to be stored as -lists instead. - -The vector representation for structure objects has the advantage -that all structure slots can be accessed quickly, although creating -vectors is a bit slower in Emacs Lisp. Lists are easier to create, -but take a relatively long time accessing the later slots. - -@item :named -This option, which takes no arguments, causes a characteristic ``tag'' -symbol to be stored at the front of the structure object. Using -@code{:type} without also using @code{:named} will result in a -structure type stored as plain vectors or lists with no identifying -features. - -The default, if you don't specify @code{:type} explicitly, is to -use named vectors. Therefore, @code{:named} is only useful in -conjunction with @code{:type}. - -@example -(defstruct (person1) name age sex) -(defstruct (person2 (:type list) :named) name age sex) -(defstruct (person3 (:type list)) name age sex) - -(setq p1 (make-person1)) - @result{} [cl-struct-person1 nil nil nil] -(setq p2 (make-person2)) - @result{} (person2 nil nil nil) -(setq p3 (make-person3)) - @result{} (nil nil nil) - -(person1-p p1) - @result{} t -(person2-p p2) - @result{} t -(person3-p p3) - @result{} error: function person3-p undefined -@end example - -Since unnamed structures don't have tags, @code{defstruct} is not -able to make a useful predicate for recognizing them. Also, -accessors like @code{person3-name} will be generated but they -will not be able to do any type checking. The @code{person3-name} -function, for example, will simply be a synonym for @code{car} in -this case. By contrast, @code{person2-name} is able to verify -that its argument is indeed a @code{person2} object before -proceeding. - -@item :initial-offset -The argument must be a nonnegative integer. It specifies a -number of slots to be left ``empty'' at the front of the -structure. If the structure is named, the tag appears at the -specified position in the list or vector; otherwise, the first -slot appears at that position. Earlier positions are filled -with @code{nil} by the constructors and ignored otherwise. If -the type @code{:include}s another type, then @code{:initial-offset} -specifies a number of slots to be skipped between the last slot -of the included type and the first new slot. -@end table -@end defspec - -Except as noted, the @code{defstruct} facility of this package is -entirely compatible with that of Common Lisp. - -@iftex -@chapno=23 -@end iftex - -@node Assertions, Efficiency Concerns, Structures, Top -@chapter Assertions and Errors - -@noindent -This section describes two macros that test @dfn{assertions}, i.e., -conditions which must be true if the program is operating correctly. -Assertions never add to the behavior of a Lisp program; they simply -make ``sanity checks'' to make sure everything is as it should be. - -If the optimization property @code{speed} has been set to 3, and -@code{safety} is less than 3, then the byte-compiler will optimize -away the following assertions. Because assertions might be optimized -away, it is a bad idea for them to include side-effects. - -@defspec assert test-form [show-args string args@dots{}] -This form verifies that @var{test-form} is true (i.e., evaluates to -a non-@code{nil} value). If so, it returns @code{nil}. If the test -is not satisfied, @code{assert} signals an error. - -A default error message will be supplied which includes @var{test-form}. -You can specify a different error message by including a @var{string} -argument plus optional extra arguments. Those arguments are simply -passed to @code{error} to signal the error. - -If the optional second argument @var{show-args} is @code{t} instead -of @code{nil}, then the error message (with or without @var{string}) -will also include all non-constant arguments of the top-level -@var{form}. For example: - -@example -(assert (> x 10) t "x is too small: %d") -@end example - -This usage of @var{show-args} is an extension to Common Lisp. In -true Common Lisp, the second argument gives a list of @var{places} -which can be @code{setf}'d by the user before continuing from the -error. Since Emacs Lisp does not support continuable errors, it -makes no sense to specify @var{places}. -@end defspec - -@defspec check-type form type [string] -This form verifies that @var{form} evaluates to a value of type -@var{type}. If so, it returns @code{nil}. If not, @code{check-type} -signals a @code{wrong-type-argument} error. The default error message -lists the erroneous value along with @var{type} and @var{form} -themselves. If @var{string} is specified, it is included in the -error message in place of @var{type}. For example: - -@example -(check-type x (integer 1 *) "a positive integer") -@end example - -@xref{Type Predicates}, for a description of the type specifiers -that may be used for @var{type}. - -Note that in Common Lisp, the first argument to @code{check-type} -must be a @var{place} suitable for use by @code{setf}, because -@code{check-type} signals a continuable error that allows the -user to modify @var{place}. -@end defspec - -The following error-related macro is also defined: - -@defspec ignore-errors forms@dots{} -This executes @var{forms} exactly like a @code{progn}, except that -errors are ignored during the @var{forms}. More precisely, if -an error is signaled then @code{ignore-errors} immediately -aborts execution of the @var{forms} and returns @code{nil}. -If the @var{forms} complete successfully, @code{ignore-errors} -returns the result of the last @var{form}. -@end defspec - -@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top -@appendix Efficiency Concerns - -@appendixsec Macros - -@noindent -Many of the advanced features of this package, such as @code{defun*}, -@code{loop}, and @code{setf}, are implemented as Lisp macros. In -byte-compiled code, these complex notations will be expanded into -equivalent Lisp code which is simple and efficient. For example, -the forms - -@example -(incf i n) -(push x (car p)) -@end example - -@noindent -are expanded at compile-time to the Lisp forms - -@example -(setq i (+ i n)) -(setcar p (cons x (car p))) -@end example - -@noindent -which are the most efficient ways of doing these respective operations -in Lisp. Thus, there is no performance penalty for using the more -readable @code{incf} and @code{push} forms in your compiled code. - -@emph{Interpreted} code, on the other hand, must expand these macros -every time they are executed. For this reason it is strongly -recommended that code making heavy use of macros be compiled. -(The features labeled ``Special Form'' instead of ``Function'' in -this manual are macros.) A loop using @code{incf} a hundred times -will execute considerably faster if compiled, and will also -garbage-collect less because the macro expansion will not have -to be generated, used, and thrown away a hundred times. - -You can find out how a macro expands by using the -@code{cl-prettyexpand} function. - -@defun cl-prettyexpand form &optional full -This function takes a single Lisp form as an argument and inserts -a nicely formatted copy of it in the current buffer (which must be -in Lisp mode so that indentation works properly). It also expands -all Lisp macros which appear in the form. The easiest way to use -this function is to go to the @code{*scratch*} buffer and type, say, - -@example -(cl-prettyexpand '(loop for x below 10 collect x)) -@end example - -@noindent -and type @kbd{C-x C-e} immediately after the closing parenthesis; -the expansion - -@example -(block nil - (let* ((x 0) - (G1004 nil)) - (while (< x 10) - (setq G1004 (cons x G1004)) - (setq x (+ x 1))) - (nreverse G1004))) -@end example - -@noindent -will be inserted into the buffer. (The @code{block} macro is -expanded differently in the interpreter and compiler, so -@code{cl-prettyexpand} just leaves it alone. The temporary -variable @code{G1004} was created by @code{gensym}.) - -If the optional argument @var{full} is true, then @emph{all} -macros are expanded, including @code{block}, @code{eval-when}, -and compiler macros. Expansion is done as if @var{form} were -a top-level form in a file being compiled. For example, - -@example -(cl-prettyexpand '(pushnew 'x list)) - @print{} (setq list (adjoin 'x list)) -(cl-prettyexpand '(pushnew 'x list) t) - @print{} (setq list (if (memq 'x list) list (cons 'x list))) -(cl-prettyexpand '(caddr (member* 'a list)) t) - @print{} (car (cdr (cdr (memq 'a list)))) -@end example - -Note that @code{adjoin}, @code{caddr}, and @code{member*} all -have built-in compiler macros to optimize them in common cases. -@end defun - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec Error Checking - -@noindent -Common Lisp compliance has in general not been sacrificed for the -sake of efficiency. A few exceptions have been made for cases -where substantial gains were possible at the expense of marginal -incompatibility. - -The Common Lisp standard (as embodied in Steele's book) uses the -phrase ``it is an error if'' to indicate a situation which is not -supposed to arise in complying programs; implementations are strongly -encouraged but not required to signal an error in these situations. -This package sometimes omits such error checking in the interest of -compactness and efficiency. For example, @code{do} variable -specifiers are supposed to be lists of one, two, or three forms; -extra forms are ignored by this package rather than signaling a -syntax error. The @code{endp} function is simply a synonym for -@code{null} in this package. Functions taking keyword arguments -will accept an odd number of arguments, treating the trailing -keyword as if it were followed by the value @code{nil}. - -Argument lists (as processed by @code{defun*} and friends) -@emph{are} checked rigorously except for the minor point just -mentioned; in particular, keyword arguments are checked for -validity, and @code{&allow-other-keys} and @code{:allow-other-keys} -are fully implemented. Keyword validity checking is slightly -time consuming (though not too bad in byte-compiled code); -you can use @code{&allow-other-keys} to omit this check. Functions -defined in this package such as @code{find} and @code{member*} -do check their keyword arguments for validity. - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec Optimizing Compiler - -@noindent -Use of the optimizing Emacs compiler is highly recommended; many of the Common -Lisp macros emit -code which can be improved by optimization. In particular, -@code{block}s (whether explicit or implicit in constructs like -@code{defun*} and @code{loop}) carry a fair run-time penalty; the -optimizing compiler removes @code{block}s which are not actually -referenced by @code{return} or @code{return-from} inside the block. - -@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top -@appendix Common Lisp Compatibility - -@noindent -Following is a list of all known incompatibilities between this -package and Common Lisp as documented in Steele (2nd edition). - -Certain function names, such as @code{member}, @code{assoc}, and -@code{floor}, were already taken by (incompatible) Emacs Lisp -functions; this package appends @samp{*} to the names of its -Common Lisp versions of these functions. - -The word @code{defun*} is required instead of @code{defun} in order -to use extended Common Lisp argument lists in a function. Likewise, -@code{defmacro*} and @code{function*} are versions of those forms -which understand full-featured argument lists. The @code{&whole} -keyword does not work in @code{defmacro} argument lists (except -inside recursive argument lists). - -The @code{equal} predicate does not distinguish -between IEEE floating-point plus and minus zero. The @code{equalp} -predicate has several differences with Common Lisp; @pxref{Predicates}. - -The @code{setf} mechanism is entirely compatible, except that -setf-methods return a list of five values rather than five -values directly. Also, the new ``@code{setf} function'' concept -(typified by @code{(defun (setf foo) @dots{})}) is not implemented. - -The @code{do-all-symbols} form is the same as @code{do-symbols} -with no @var{obarray} argument. In Common Lisp, this form would -iterate over all symbols in all packages. Since Emacs obarrays -are not a first-class package mechanism, there is no way for -@code{do-all-symbols} to locate any but the default obarray. - -The @code{loop} macro is complete except that @code{loop-finish} -and type specifiers are unimplemented. - -The multiple-value return facility treats lists as multiple -values, since Emacs Lisp cannot support multiple return values -directly. The macros will be compatible with Common Lisp if -@code{values} or @code{values-list} is always used to return to -a @code{multiple-value-bind} or other multiple-value receiver; -if @code{values} is used without @code{multiple-value-@dots{}} -or vice-versa the effect will be different from Common Lisp. - -Many Common Lisp declarations are ignored, and others match -the Common Lisp standard in concept but not in detail. For -example, local @code{special} declarations, which are purely -advisory in Emacs Lisp, do not rigorously obey the scoping rules -set down in Steele's book. - -The variable @code{*gensym-counter*} starts out with a pseudo-random -value rather than with zero. This is to cope with the fact that -generated symbols become interned when they are written to and -loaded back from a file. - -The @code{defstruct} facility is compatible, except that structures -are of type @code{:type vector :named} by default rather than some -special, distinct type. Also, the @code{:type} slot option is ignored. - -The second argument of @code{check-type} is treated differently. - -@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top -@appendix Old CL Compatibility - -@noindent -Following is a list of all known incompatibilities between this package -and the older Quiroz @file{cl.el} package. - -This package's emulation of multiple return values in functions is -incompatible with that of the older package. That package attempted -to come as close as possible to true Common Lisp multiple return -values; unfortunately, it could not be 100% reliable and so was prone -to occasional surprises if used freely. This package uses a simpler -method, namely replacing multiple values with lists of values, which -is more predictable though more noticeably different from Common Lisp. - -The @code{defkeyword} form and @code{keywordp} function are not -implemented in this package. - -The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, -@code{round}, @code{mod}, and @code{rem} functions are suffixed -by @samp{*} in this package to avoid collision with existing -functions in Emacs. The older package simply -redefined these functions, overwriting the built-in meanings and -causing serious portability problems. (Some more -recent versions of the Quiroz package changed the names to -@code{cl-member}, etc.; this package defines the latter names as -aliases for @code{member*}, etc.) - -Certain functions in the old package which were buggy or inconsistent -with the Common Lisp standard are incompatible with the conforming -versions in this package. For example, @code{eql} and @code{member} -were synonyms for @code{eq} and @code{memq} in that package, @code{setf} -failed to preserve correct order of evaluation of its arguments, etc. - -Finally, unlike the older package, this package is careful to -prefix all of its internal names with @code{cl-}. Except for a -few functions which are explicitly defined as additional features -(such as @code{floatp-safe} and @code{letf}), this package does not -export any non-@samp{cl-} symbols which are not also part of Common -Lisp. - -@ifinfo -@example - -@end example -@end ifinfo -@appendixsec The @code{cl-compat} package - -@noindent -The @dfn{CL} package includes emulations of some features of the -old @file{cl.el}, in the form of a compatibility package -@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in -your program. - -The old package defined a number of internal routines without -@code{cl-} prefixes or other annotations. Call to these routines -may have crept into existing Lisp code. @code{cl-compat} -provides emulations of the following internal routines: -@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, -@code{reassemble-arglists}, @code{duplicate-symbols-p}, -@code{safe-idiv}. - -Some @code{setf} forms translated into calls to internal -functions that user code might call directly. The functions -@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in -this category; they are defined by @code{cl-compat}, but the -best fix is to change to use @code{setf} properly. - -The @code{cl-compat} file defines the keyword functions -@code{keywordp}, @code{keyword-of}, and @code{defkeyword}, -which are not defined by the new @dfn{CL} package because the -use of keywords as data is discouraged. - -The @code{build-klist} mechanism for parsing keyword arguments -is emulated by @code{cl-compat}; the @code{with-keyword-args} -macro is not, however, and in any case it's best to change to -use the more natural keyword argument processing offered by -@code{defun*}. - -Multiple return values are treated differently by the two -Common Lisp packages. The old package's method was more -compatible with true Common Lisp, though it used heuristics -that caused it to report spurious multiple return values in -certain cases. The @code{cl-compat} package defines a set -of multiple-value macros that are compatible with the old -CL package; again, they are heuristic in nature, but they -are guaranteed to work in any case where the old package's -macros worked. To avoid name collision with the ``official'' -multiple-value facilities, the ones in @code{cl-compat} have -capitalized names: @code{Values}, @code{Values-list}, -@code{Multiple-value-bind}, etc. - -The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, -and @code{cl-round} are defined by @code{cl-compat} to use the -old-style multiple-value mechanism, just as they did in the old -package. The newer @code{floor*} and friends return their two -results in a list rather than as multiple values. Note that -older versions of the old package used the unadorned names -@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use -these names because they conflict with Emacs built-ins. - -@node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top -@appendix Porting Common Lisp - -@noindent -This package is meant to be used as an extension to Emacs Lisp, -not as an Emacs implementation of true Common Lisp. Some of the -remaining differences between Emacs Lisp and Common Lisp make it -difficult to port large Common Lisp applications to Emacs. For -one, some of the features in this package are not fully compliant -with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there -are also quite a few features that this package does not provide -at all. Here are some major omissions that you will want to watch out -for when bringing Common Lisp code into Emacs. - -@itemize @bullet -@item -Case-insensitivity. Symbols in Common Lisp are case-insensitive -by default. Some programs refer to a function or variable as -@code{foo} in one place and @code{Foo} or @code{FOO} in another. -Emacs Lisp will treat these as three distinct symbols. - -Some Common Lisp code is written entirely in upper case. While Emacs -is happy to let the program's own functions and variables use -this convention, calls to Lisp builtins like @code{if} and -@code{defun} will have to be changed to lower case. - -@item -Lexical scoping. In Common Lisp, function arguments and @code{let} -bindings apply only to references physically within their bodies -(or within macro expansions in their bodies). Emacs Lisp, by -contrast, uses @dfn{dynamic scoping} wherein a binding to a -variable is visible even inside functions called from the body. - -Variables in Common Lisp can be made dynamically scoped by -declaring them @code{special} or using @code{defvar}. In Emacs -Lisp it is as if all variables were declared @code{special}. - -Often you can use code that was written for lexical scoping -even in a dynamically scoped Lisp, but not always. Here is -an example of a Common Lisp code fragment that would fail in -Emacs Lisp: - -@example -(defun map-odd-elements (func list) - (loop for x in list - for flag = t then (not flag) - collect (if flag x (funcall func x)))) - -(defun add-odd-elements (list x) - (map-odd-elements (lambda (a) (+ a x)) list)) -@end example - -@noindent -In Common Lisp, the two functions' usages of @code{x} are completely -independent. In Emacs Lisp, the binding to @code{x} made by -@code{add-odd-elements} will have been hidden by the binding -in @code{map-odd-elements} by the time the @code{(+ a x)} function -is called. - -(This package avoids such problems in its own mapping functions -by using names like @code{cl-x} instead of @code{x} internally; -as long as you don't use the @code{cl-} prefix for your own -variables no collision can occur.) - -@xref{Lexical Bindings}, for a description of the @code{lexical-let} -form which establishes a Common Lisp-style lexical binding, and some -examples of how it differs from Emacs' regular @code{let}. - -@item -Reader macros. Common Lisp includes a second type of macro that -works at the level of individual characters. For example, Common -Lisp implements the quote notation by a reader macro called @code{'}, -whereas Emacs Lisp's parser just treats quote as a special case. -Some Lisp packages use reader macros to create special syntaxes -for themselves, which the Emacs parser is incapable of reading. - -@item -Other syntactic features. Common Lisp provides a number of -notations beginning with @code{#} that the Emacs Lisp parser -won't understand. For example, @samp{#| ... |#} is an -alternate comment notation, and @samp{#+lucid (foo)} tells -the parser to ignore the @code{(foo)} except in Lucid Common -Lisp. - -@item -Packages. In Common Lisp, symbols are divided into @dfn{packages}. -Symbols that are Lisp built-ins are typically stored in one package; -symbols that are vendor extensions are put in another, and each -application program would have a package for its own symbols. -Certain symbols are ``exported'' by a package and others are -internal; certain packages ``use'' or import the exported symbols -of other packages. To access symbols that would not normally be -visible due to this importing and exporting, Common Lisp provides -a syntax like @code{package:symbol} or @code{package::symbol}. - -Emacs Lisp has a single namespace for all interned symbols, and -then uses a naming convention of putting a prefix like @code{cl-} -in front of the name. Some Emacs packages adopt the Common Lisp-like -convention of using @code{cl:} or @code{cl::} as the prefix. -However, the Emacs parser does not understand colons and just -treats them as part of the symbol name. Thus, while @code{mapcar} -and @code{lisp:mapcar} may refer to the same symbol in Common -Lisp, they are totally distinct in Emacs Lisp. Common Lisp -programs which refer to a symbol by the full name sometimes -and the short name other times will not port cleanly to Emacs. - -Emacs Lisp does have a concept of ``obarrays,'' which are -package-like collections of symbols, but this feature is not -strong enough to be used as a true package mechanism. - -@item -The @code{format} function is quite different between Common -Lisp and Emacs Lisp. It takes an additional ``destination'' -argument before the format string. A destination of @code{nil} -means to format to a string as in Emacs Lisp; a destination -of @code{t} means to write to the terminal (similar to -@code{message} in Emacs). Also, format control strings are -utterly different; @code{~} is used instead of @code{%} to -introduce format codes, and the set of available codes is -much richer. There are no notations like @code{\n} for -string literals; instead, @code{format} is used with the -``newline'' format code, @code{~%}. More advanced formatting -codes provide such features as paragraph filling, case -conversion, and even loops and conditionals. - -While it would have been possible to implement most of Common -Lisp @code{format} in this package (under the name @code{format*}, -of course), it was not deemed worthwhile. It would have required -a huge amount of code to implement even a decent subset of -@code{format*}, yet the functionality it would provide over -Emacs Lisp's @code{format} would rarely be useful. - -@item -Vector constants use square brackets in Emacs Lisp, but -@code{#(a b c)} notation in Common Lisp. To further complicate -matters, Emacs has its own @code{#(} notation for -something entirely different---strings with properties. - -@item -Characters are distinct from integers in Common Lisp. The notation -for character constants is also different: @code{#\A} in Common Lisp -where Emacs Lisp uses @code{?A}. Also, @code{string=} and -@code{string-equal} are synonyms in Emacs Lisp, whereas the latter is -case-insensitive in Common Lisp. - -@item -Data types. Some Common Lisp data types do not exist in Emacs -Lisp. Rational numbers and complex numbers are not present, -nor are large integers (all integers are ``fixnums''). All -arrays are one-dimensional. There are no readtables or pathnames; -streams are a set of existing data types rather than a new data -type of their own. Hash tables, random-states, structures, and -packages (obarrays) are built from Lisp vectors or lists rather -than being distinct types. - -@item -The Common Lisp Object System (CLOS) is not implemented, -nor is the Common Lisp Condition System. However, the EIEIO package -from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some -CLOS functionality. - -@item -Common Lisp features that are completely redundant with Emacs -Lisp features of a different name generally have not been -implemented. For example, Common Lisp writes @code{defconstant} -where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} -takes its arguments in different ways in the two Lisps but does -exactly the same thing, so this package has not bothered to -implement a Common Lisp-style @code{make-list}. - -@item -A few more notable Common Lisp features not included in this -package: @code{compiler-let}, @code{tagbody}, @code{prog}, -@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. - -@item -Recursion. While recursion works in Emacs Lisp just like it -does in Common Lisp, various details of the Emacs Lisp system -and compiler make recursion much less efficient than it is in -most Lisps. Some schools of thought prefer to use recursion -in Lisp over other techniques; they would sum a list of -numbers using something like - -@example -(defun sum-list (list) - (if list - (+ (car list) (sum-list (cdr list))) - 0)) -@end example - -@noindent -where a more iteratively-minded programmer might write one of -these forms: - -@example -(let ((total 0)) (dolist (x my-list) (incf total x)) total) -(loop for x in my-list sum x) -@end example - -While this would be mainly a stylistic choice in most Common Lisps, -in Emacs Lisp you should be aware that the iterative forms are -much faster than recursion. Also, Lisp programmers will want to -note that the current Emacs Lisp compiler does not optimize tail -recursion. -@end itemize - -@node GNU Free Documentation License, Function Index, Porting Common Lisp, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index, Variable Index, GNU Free Documentation License, Top -@unnumbered Function Index - -@printindex fn - -@node Variable Index, , Function Index, Top -@unnumbered Variable Index - -@printindex vr - -@bye - -@ignore - arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8 -@end ignore diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi deleted file mode 100644 index f1385f66b34..00000000000 --- a/doc/misc/dbus.texi +++ /dev/null @@ -1,1582 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/dbus -@c %**start of header -@settitle Using of D-Bus -@c @setchapternewpage odd -@c %**end of header - -@copying -Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* D-Bus: (dbus). Using D-Bus in Emacs. -@end direntry - -@contents - -@node Top, Overview, (dir), (dir) -@top D-Bus integration in Emacs - -This manual documents an API for usage of D-Bus in -Emacs.@footnote{D-Bus is not enabled by default. You must run -@command{./configure --with-dbus} in Emacs' top level directory, -before you compile Emacs.} D-Bus is a message bus system, a simple -way for applications to talk to one another. An overview of D-Bus can -be found at @uref{http://dbus.freedesktop.org/}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: An overview of D-Bus. -* Inspection:: Inspection of D-Bus services. -* Type Conversion:: Mapping Lisp types and D-Bus types. -* Synchronous Methods:: Calling methods in a blocking way. -* Asynchronous Methods:: Calling methods non-blocking. -* Receiving Method Calls:: Offering own methods. -* Signals:: Sending and receiving signals. -* Errors and Events:: Errors and events. -* GNU Free Documentation License:: The license for this documentation. -@end menu - - -@node Overview -@chapter An overview of D-Bus -@cindex overview - -D-Bus is an inter-process communication mechanism for applications -residing on the same host. The communication is based on -@dfn{messages}. Data in the messages is carried in a structured way, -it is not just a byte stream. - -The communication is connection oriented to two kinds of message -buses: a so called @dfn{system bus}, and a @dfn{session bus}. On a -given machine, there is always one single system bus for miscellaneous -system-wide communication, like changing of hardware configuration. -On the other hand, the session bus is always related to a single -user's session. - -Every client application, which is connected to a bus, registers under -a @dfn{unique name} at the bus. This name is used for identifying the -client application. Such a unique name starts always with a colon, -and looks like @samp{:1.42}. - -Additionally, a client application can register itself to a so called -@dfn{known name}, which is a series of identifiers separated by dots, -as in @samp{org.gnu.Emacs}. If several applications register to the -same known name, these registrations are queued, and only the first -application which has registered for the known name is reachable via -this name. If this application disconnects from the bus, the next -queued unique name becomes the owner of this known name. - -An application can install one or several objects under its name. -Such objects are identified by an @dfn{object path}, which looks -similar to paths in a filesystem. An example of such an object path -could be @samp{/org/gnu/Emacs/}. - -Applications might send a request to an object, that means sending a -message with some data as input parameters, and receiving a message -from that object with the result of this message, the output -parameters. Such a request is called @dfn{method} in D-Bus. - -The other form of communication are @dfn{signals}. The underlying -message is emitted from an object and will be received by all other -applications which have registered for such a signal. - -All methods and signals an object supports are called @dfn{interface} -of the object. Interfaces are specified under a hierarchical name in -D-Bus; an object can support several interfaces. Such an interface -name could be @samp{org.gnu.Emacs.TextEditor} or -@samp{org.gnu.Emacs.FileManager}. - - -@node Inspection -@chapter Inspection of D-Bus services. -@cindex inspection - -@menu -* Bus names:: Discovering D-Bus names. -* Introspection:: Knowing the details of D-Bus services. -* Nodes and Interfaces:: Detecting object paths and interfaces. -* Methods and Signal:: Applying the functionality. -* Properties and Annotations:: What else to know about interfaces. -* Arguments and Signatures:: The final details. -@end menu - - -@node Bus names -@section Bus names. - -There are several basic functions which inspect the buses for -registered names. Internally they use the basic interface -@samp{org.freedesktop.DBus}, which is supported by all objects of a bus. - -@defun dbus-list-activatable-names -This function returns the D-Bus service names, which can be activated. -An activatable service is described in a service registration file. -Under GNU/Linux, such files are located at -@file{/usr/share/dbus-1/services/}. - -The result is a list of strings, which is @code{nil} when there are no -activatable service names at all. -@end defun - -@defun dbus-list-names bus -All service names, which are registered at D-Bus @var{bus}, are -returned. The result is a list of strings, which is @code{nil} when -there are no registered service names at all. Well known names are -strings like @samp{org.freedesktop.DBus}. Names starting with -@samp{:} are unique names for services. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-known-names bus -Retrieves all services which correspond to a known name in @var{bus}. -A service has a known name if it doesn't start with @samp{:}. The -result is a list of strings, which is @code{nil} when there are no -known names at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - -@defun dbus-list-queued-owners bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, all queued unique names are returned. The result is a -list of strings, or @code{nil} when there are no queued names for -@var{service} at all. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-get-name-owner bus service -For a given service, registered at D-Bus @var{bus} under the name -@var{service}, the unique name of the name owner is returned. The -result is a string, or @code{nil} when there exist no name owner of -@var{service}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name as -string. -@end defun - -@defun dbus-ping bus service -Check whether the service name @var{service} is registered at D-Bus -@var{bus}. @var{service} might not have been started yet. The result -is either @code{t} or @code{nil}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a string. Example: - -@lisp -(message - "%s screensaver on board." - (cond - ((dbus-ping :session "org.gnome.ScreenSaver") "Gnome") - ((dbus-ping :session "org.freedesktop.ScreenSaver") "KDE") - (t "No"))) -@end lisp -@end defun - -@defun dbus-get-unique-name bus -The unique name, under which Emacs is registered at D-Bus @var{bus}, -is returned as string. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. -@end defun - - -@node Introspection -@section Knowing the details of D-Bus services. - -D-Bus services publish their interfaces. This can be retrieved and -analyzed during runtime, in order to understand the used -implementation. - -The resulting introspection data are in XML format. The root -introspection element is always a @code{node} element. It might have -a @code{name} attribute, which denotes the (absolute) object path an -interface is introspected. - -The root @code{node} element may have @code{node} and @code{interface} -children. A child @code{node} element must have a @code{name} -attribute, this case it is the relative object path to the root -@code{node} element. - -An @code{interface} element has just one attribute, @code{name}, which -is the full name of that interface. The default interface -@samp{org.freedesktop.DBus.Introspectable} is always present. Example: - -@example - - - @dots{} - - - @dots{} - - - @dots{} - - - @dots{} - - - - - - -@end example - -Children of an @code{interface} element can be @code{method}, -@code{signal} and @code{property} elements. A @code{method} element -stands for a D-Bus method of the surrounding interface. The element -itself has a @code{name} attribute, showing the method name. Children -elements @code{arg} stand for the arguments of a method. Example: - -@example - - - - - - - - - - - - - -@end example - -@code{arg} elements can have the attributes @code{name}, @code{type} -and @code{direction}. The @code{name} attribute is optional. The -@code{type} attribute stands for the @dfn{signature} of the argument -in D-Bus. For a discussion of D-Bus types and their Lisp -representation see @ref{Type Conversion}.@footnote{D-Bus signatures -are explained in the D-Bus specification -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures}.} -The @code{direction} attribute of an @code{arg} element can be only -@samp{in} or @samp{out}; in case it is omitted, it defaults to -@samp{in}. - -A @code{signal} element of an @code{interface} has a similar -structure. The @code{direction} attribute of an @code{arg} child -element can be only @samp{out} here; which is also the default value. -Example: - -@example - - - - -@end example - -A @code{property} element has no @code{arg} child -element. It just has the attributes @code{name}, @code{type} and -@code{access}, which are all mandatory. The @code{access} attribute -allows the values @samp{readwrite}, @samp{read}, and @samp{write}. -Example: - -@example - -@end example - -@code{annotation} elements can be children of @code{interface}, -@code{method}, @code{signal}, and @code{property} elements. Unlike -properties, which can change their values during lifetime of a D-Bus -object, annotations are static. Often they are used for code -generators of D-Bus langugae bindings. Example: - -@example - -@end example - -Annotations have just @code{name} and @code{value} attributes, both -must be strings. - -@defun dbus-introspect bus service path -This function returns all interfaces and sub-nodes of @var{service}, -registered at object path @var{path} at bus @var{bus}. - -@var{bus} must be either the symbol @code{:system} or the symbol -@code{:session}. @var{service} must be a known service name, and -@var{path} must be a valid object path. The last two parameters are -strings. The result, the introspection data, is a string in XML -format. Example: - -@lisp -(dbus-introspect - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} " - - - - - - @dots{} - - - - - - @dots{} - " -@end lisp - -This example informs us, that the service @samp{org.freedesktop.Hal} -at object path @samp{/org/freedesktop/Hal/devices/computer} offers the -interface @samp{org.freedesktop.Hal.Device} (and 2 other interfaces -not documented here). This interface contains the method -@samp{GetAllProperties}, which needs no input parameters, but returns -as output parameter an array of dictionary entries (key-value pairs). -Every dictionary entry has a string as key, and a variant as value. - -The interface offers also a signal, which returns 2 parameters: an -integer, and an array consisting of elements which are a struct of a -string and 2 boolean values.@footnote{ The interfaces of the service -@samp{org.freedesktop.Hal} are described at -@uref{http://people.freedesktop.org/~david/hal-spec/hal-spec.html#interfaces}.} -@end defun - -@defun dbus-introspect-xml bus service path -This function has the same intention as function -@code{dbus-introspect}. The returned value is a parsed XML tree, -which can be used for further analysis. Example: - -@lisp -(dbus-introspect-xml - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main") - -@result{} (node ((name . "/org/freedesktop/xesam/searcher/main")) - (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) - @dots{} - ) -@end lisp -@end defun - -@defun dbus-introspect-get-attribute object attribute -It returns the @var{attribute} value of a D-Bus introspection -@var{object}. @var{object} can be every subtree of a parsed XML tree -as retrieved with @code{dbus-introspect-xml}. @var{attribute} must be -a string according to the attribute names in the D-Bus specification. -Example: - -@lisp -(dbus-introspect-get-attribute - (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends" - "/org/freedesktop/SystemToolsBackends/UsersConfig") - "name") - -@result{} "/org/freedesktop/SystemToolsBackends/UsersConfig" -@end lisp - -If @var{object} has no @var{attribute}, the function returns nil. -@end defun - - -@node Nodes and Interfaces -@section Detecting object paths and interfaces. - -The first elements, to be introspected for a D-Bus object, are further -object paths and interfaces. - -@defun dbus-introspect-get-node-names bus service path -All node names of @var{service} in D-Bus @var{bus} at object path -@var{path} are returned as list of strings. Example: - -@lisp -(dbus-introspect-get-node-names - :session "org.gnome.seahorse" "/org/gnome/seahorse") - -@result{} ("crypto" "keys") -@end lisp - -The node names stand for further object paths of the D-Bus -@var{service}, relative to @var{path}. In the example, -@samp{/org/gnome/seahorse/crypto} and @samp{/org/gnome/seahorse/keys} -are also object paths of the D-Bus service @samp{org.gnome.seahorse}. -@end defun - -@defun dbus-introspect-get-all-nodes bus service path -This function returns all node names of @var{service} in D-Bus -@var{bus} at object path @var{path}. It returns a list of strings -with all object paths of @var{service}, starting at @var{path}. -Example: - -@lisp -(dbus-introspect-get-all-nodes :session "org.gnome.seahorse" "/") - -@result{} ("/" "/org" "/org/gnome" "/org/gnome/seahorse" - "/org/gnome/seahorse/crypto" - "/org/gnome/seahorse/keys" - "/org/gnome/seahorse/keys/openpgp" - "/org/gnome/seahorse/keys/openpgp/local" - "/org/gnome/seahorse/keys/openssh" - "/org/gnome/seahorse/keys/openssh/local") -@end lisp -@end defun - -@defun dbus-introspect-get-interface-names bus service path -There will be returned a list strings of all interface names of -@var{service} in D-Bus @var{bus} at object path @var{path}. This list -will contain the default interface @samp{org.freedesktop.DBus.Introspectable}. - -Another default interface is @samp{org.freedesktop.DBus.Properties}. -If present, @code{interface} elements can also have @code{property} -children. Example: - -@lisp -(dbus-introspect-get-interface-names - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer") - -@result{} ("org.freedesktop.DBus.Introspectable" - "org.freedesktop.Hal.Device" - "org.freedesktop.Hal.Device.SystemPowerManagement" - "org.freedesktop.Hal.Device.CPUFreq") -@end lisp -@end defun - -@defun dbus-introspect-get-interface bus service path interface -Return @var{interface} of @var{service} in D-Bus @var{bus} at object -path @var{path}. The return value is an XML element. @var{interface} -must be a string, element of the list returned by -@code{dbus-introspect-get-interface-names}. Example: - -@lisp -(dbus-introspect-get-interface - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} (interface ((name . "org.freedesktop.xesam.Search")) - (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) - @dots{} - (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) - ) -@end lisp -@end defun - -@noindent -With these functions, it is possible to retrieve all introspection -data from a running system: - -@lisp -(with-current-buffer (switch-to-buffer "*introspect*") - (erase-buffer) - (dolist (service (dbus-list-known-names :session)) - (dolist (path (dbus-introspect-get-all-nodes :session service "/")) - ;; We want to introspect only elements, which have more than - ;; the default interface "org.freedesktop.DBus.Introspectable". - (when (delete - "org.freedesktop.DBus.Introspectable" - (dbus-introspect-get-interface-names :session service path)) - (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path) - (dbus-introspect :session service path)) - (redisplay t))))) -@end lisp - - -@node Methods and Signal -@section Applying the functionality. - -Methods and signals are the communicatione means to D-Bus. The -following functions return their specifications. - -@defun dbus-introspect-get-method-names bus service path interface -Return a list of strings of all method names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-method-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession" - "CloseSession" "GetHitData" "SetProperty" "NewSearch" - "GetProperty" "CloseSearch") -@end lisp -@end defun - -@defun dbus-introspect-get-method bus service path interface method -This function returns @var{method} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{method} must be a string, element of the list -returned by @code{dbus-introspect-get-method-names}. Example: - -@lisp -(dbus-introspect-get-method - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} (method ((name . "GetHitData")) - (arg ((name . "search") (type . "s") (direction . "in"))) - (arg ((name . "hit_ids") (type . "au") (direction . "in"))) - (arg ((name . "fields") (type . "as") (direction . "in"))) - (arg ((name . "hit_data") (type . "aav") (direction . "out"))) - ) -@end lisp -@end defun - -@defun dbus-introspect-get-signal-names bus service path interface -Return a list of strings of all signal names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-signal-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search") - -@result{} ("StateChanged" "SearchDone" "HitsModified" - "HitsRemoved" "HitsAdded") -@end lisp -@end defun - -@defun dbus-introspect-get-signal bus service path interface signal -This function returns @var{signal} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{signal} must be a string, element of the list -returned by @code{dbus-introspect-get-signal-names}. Example: - -@lisp -(dbus-introspect-get-signal - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} (signal ((name . "HitsAdded")) - (arg ((name . "search") (type . "s"))) - (arg ((name . "count") (type . "u"))) - ) -@end lisp -@end defun - - -@node Properties and Annotations -@section What else to know about interfaces. - -Interfaces can have properties. These can be exposed via the -@samp{org.freedesktop.DBus.Properties} interface@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}. -That is, properties can be retrieved and changed during lifetime of an -element. - -Annotations, on the other hand, are static values for an element. -Often, they are used to instruct generators, how to generate code from -the interface for a given language binding. - -@defun dbus-introspect-get-property-names bus service path interface -Return a list of strings with all property names of @var{interface} of -@var{service} in D-Bus @var{bus} at object path @var{path}. Example: - -@lisp -(dbus-introspect-get-property-names - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client") - -@result{} ("Status") -@end lisp - -If an interface declares properties, the corresponding element supports -also the @samp{org.freedesktop.DBus.Properties} interface. -@end defun - -@defun dbus-introspect-get-property bus service path interface property -This function returns @var{property} of @var{interface} as XML element. -It must be located at @var{service} in D-Bus @var{bus} at object path -@var{path}. @var{property} must be a string, element of the list -returned by @code{dbus-introspect-get-property-names}. - -A @var{property} value can be retrieved by the function -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} (property ((access . "read") (type . "u") (name . "Status"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - "access") - -@result{} "read" -@end lisp -@end defun - -@defun dbus-get-property bus service path interface property -This function returns the value of @var{property} of @var{interface}. -It will be checked at @var{bus}, @var{service}, @var{path}. The -result can be any valid D-Bus value, or nil if there is no -@var{property}. Example: - -@lisp -(dbus-get-property - :session "org.kde.kded" "/modules/networkstatus" - "org.kde.Solid.Networking.Client" "Status") - -@result{} 4 -@end lisp -@end defun - -@defun dbus-set-property bus service path interface property value -Set value of @var{property} of @var{interface} to @var{value}. It -will be checked at @var{bus}, @var{service}, @var{path}. When the -value has been set successful, the result is @var{value}. Otherwise, -@code{nil} is returned. Example: - -@lisp -(dbus-set-property - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication" "doubleClickInterval" 500) - -@result{} 500 -@end lisp -@end defun - -@defun dbus-get-all-properties bus service path interface -This function returns all properties of @var{interface}. It will be -checked at @var{bus}, @var{service}, @var{path}. The result is a list -of cons. Every cons contains the name of the property, and its value. -If there are no properties, @code{nil} is returned. Example: - -@lisp -(dbus-get-all-properties - :session "org.kde.kaccess" "/MainApplication" - "com.trolltech.Qt.QApplication") - -@result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500) - ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3) - ("globalStrut" 0 0) ("startDragTime" . 500) - ("startDragDistance" . 4) ("quitOnLastWindowClosed" . t) - ("styleSheet" . "")) -@end lisp -@end defun - -@defun dbus-introspect-get-annotation-names bus service path interface &optional name -Return a list of all annotation names as list of strings. If -@var{name} is @code{nil}, the annotations are children of -@var{interface}, otherwise @var{name} must be a @code{method}, -@code{signal}, or @code{property} XML element, where the annotations -belong to. Example: - -@lisp -(dbus-introspect-get-annotation-names - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics") - -@result{} ("de.berlios.Pinot.GetStatistics") -@end lisp - -Default annotation names@footnote{See -@uref{http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format}} -are - -@table @samp -@item org.freedesktop.DBus.Deprecated -Whether or not the entity is deprecated; defaults to @code{nil} - -@item org.freedesktop.DBus.GLib.CSymbol -The C symbol; may be used for @code{methods} and @code{interfaces} - -@item org.freedesktop.DBus.Method.NoReply -If set, don't expect a reply to the @code{method} call; defaults to @code{nil} -@end table -@end defun - -@defun dbus-introspect-get-annotation bus service path interface name annotation -Return annotation @var{ANNOTATION} as XML object. If @var{name} is -@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise -@var{name} must be the name of a @code{method}, @code{signal}, or -@code{property} XML element, where the @var{ANNOTATION} belongs to. - -An attribute value can be retrieved by -@code{dbus-introspect-get-attribute}. Example: - -@lisp -(dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - -@result{} (annotation ((name . "de.berlios.Pinot.GetStatistics") - (value . "pinotDBus"))) - -(dbus-introspect-get-attribute - (dbus-introspect-get-annotation - :session "de.berlios.Pinot" "/de/berlios/Pinot" - "de.berlios.Pinot" "GetStatistics" - "de.berlios.Pinot.GetStatistics") - "value") - -@result{} "pinotDBus" -@end lisp -@end defun - - -@node Arguments and Signatures -@section The final details. - -Methods and signals have arguments. They are described in the -@code{arg} XML elements. - -@defun dbus-introspect-get-argument-names bus service path interface name -Return a list of all argument names as list of strings. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument-names - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData") - -@result{} ("search" "hit_ids" "fields" "hit_data") -@end lisp - -Argument names are optional; the function can return @code{nil} -therefore, even if the method or signal has arguments. -@end defun - -@defun dbus-introspect-get-argument bus service path interface name arg -Return argument @var{ARG} as XML object. @var{name} -must be a @code{method} or @code{signal} XML element. Example: - -@lisp -(dbus-introspect-get-argument - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "search") - -@result{} (arg ((name . "search") (type . "s") (direction . "in"))) -@end lisp -@end defun - -@defun dbus-introspect-get-signature bus service path interface name &optional direction -Return signature of a @code{method} or @code{signal}, represented by -@var{name}, as string. - -If @var{name} is a @code{method}, @var{direction} can be either -@samp{in} or @samp{out}. If @var{direction} is @code{nil}, @samp{in} -is assumed. - -If @var{name} is a @code{signal}, and @var{direction} is -non-@code{nil}, @var{direction} must be @samp{out}. Example: - -@lisp -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "GetHitData" "in") - -@result{} "sauas" - -(dbus-introspect-get-signature - :session "org.freedesktop.xesam.searcher" - "/org/freedesktop/xesam/searcher/main" - "org.freedesktop.xesam.Search" "HitsAdded") - -@result{} "su" -@end lisp -@end defun - - -@node Type Conversion -@chapter Mapping Lisp types and D-Bus types. -@cindex type conversion - -D-Bus method calls and signals accept usually several arguments as -parameters, either as input parameter, or as output parameter. Every -argument belongs to a D-Bus type. - -Such arguments must be mapped between the value encoded as a D-Bus -type, and the corresponding type of Lisp objects. The mapping is -applied Lisp object @expansion{} D-Bus type for input parameters, and -D-Bus type @expansion{} Lisp object for output parameters. - - -@section Input parameters. - -Input parameters for D-Bus methods and signals occur as arguments of a -Lisp function call. The following mapping to D-Bus types is -applied, when the corresponding D-Bus message is created: - -@example -@multitable {@code{t} and @code{nil}} {@expansion{}} {DBUS_TYPE_BOOLEAN} -@item Lisp type @tab @tab D-Bus type -@item -@item @code{t} and @code{nil} @tab @expansion{} @tab DBUS_TYPE_BOOLEAN -@item number @tab @expansion{} @tab DBUS_TYPE_UINT32 -@item integer @tab @expansion{} @tab DBUS_TYPE_INT32 -@item float @tab @expansion{} @tab DBUS_TYPE_DOUBLE -@item string @tab @expansion{} @tab DBUS_TYPE_STRING -@item list @tab @expansion{} @tab DBUS_TYPE_ARRAY -@end multitable -@end example - -Other Lisp objects, like symbols or hash tables, are not accepted as -input parameter. - -If it is necessary to use another D-Bus type, a corresponding type -symbol can be preceeded to the corresponding Lisp object. Basic D-Bus -types are represented by the type symbols @code{:byte}, -@code{:boolean}, @code{:int16}, @code{:uint16}, @code{:int32}, -@code{:uint32}, @code{:int64}, @code{:uint64}, @code{:double}, -@code{:string}, @code{:object-path} and @code{:signature}. - -@noindent -Example: - -@lisp -(dbus-call-method @dots{} @var{NUMBER} @var{STRING}) -@end lisp - -is equivalent to - -@lisp -(dbus-call-method @dots{} :uint32 @var{NUMBER} :string @var{STRING}) -@end lisp - -but different to - -@lisp -(dbus-call-method @dots{} :int32 @var{NUMBER} :signature @var{STRING}) -@end lisp - -The value for a byte D-Bus type can be any integer in the range 0 -through 255. If a character is used as argument, modifiers -represented outside this range are stripped of. For example, -@code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to -@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. - -A D-Bus compound type is always represented as a list. The @sc{car} -of this list can be the type symbol @code{:array}, @code{:variant}, -@code{:struct} or @code{:dict-entry}, which would result in a -corresponding D-Bus container. @code{:array} is optional, because -this is the default compound D-Bus type for a list. - -The objects being elements of the list are checked according to the -D-Bus compound type rules. - -@itemize -@item An array must contain only elements of the same D-Bus type. It -can be empty. - -@item A variant must contain only one single element. - -@item A dictionary entry must be element of an array, and it must -contain only a key-value pair of two elements, with a basic D-Bus type -key. - -@item There is no restriction for structs. -@end itemize - -If an empty array needs an element D-Bus type other than string, it -can contain exactly one element of D-Bus type @code{:signature}. The -value of this element (a string) is used as the signature of the -elements of this array. Example: - -@lisp -(dbus-call-method - :session "org.freedesktop.Notifications" - "/org/freedesktop/Notifications" - "org.freedesktop.Notifications" "Notify" - "GNU Emacs" ;; Application name. - 0 ;; No replacement of other notifications. - "" ;; No icon. - "Notification summary" ;; Summary. - (format ;; Body. - "This is a test notification, raised from %s" (emacs-version)) - '(:array) ;; No actions (empty array of strings). - '(:array :signature "@{sv@}") ;; No hints - ;; (empty array of dictionary entries). - ':int32 -1) ;; Default timeout. - -@result{} 3 -@end lisp - -@defun dbus-string-to-byte-array string -Sometimes, D-Bus methods require as input parameter an array of bytes, -instead of a string. If it is guaranteed, that @var{string} is an -UTF8 string, this function performs the conversion. Example: - -@lisp -(dbus-string-to-byte-array "/etc/hosts") - -@result{} (:array :byte 47 :byte 101 :byte 116 :byte 99 :byte 47 - :byte 104 :byte 111 :byte 115 :byte 116 :byte 115) -@end lisp -@end defun - -@defun dbus-escape-as-identifier string -Escape an arbitrary @var{string} so it follows the rules for a C -identifier. The escaped string can be used as object path component, -interface element component, bus name component or member name in -D-Bus. - -The escaping consists of replacing all non-alphanumerics, and the -first character if it's a digit, with an underscore and two -lower-case hex digits. As a special case, "" is escaped to -"_". Example: - -@lisp -(dbus-escape-as-identifier "0123abc_xyz\x01\xff") - -@result{} "_30123abc_5fxyz_01_ff" -@end lisp -@end defun - - -@section Output parameters. - -Output parameters of D-Bus methods and signals are mapped to Lisp -objects. - -@example -@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {@code{t} or @code{nil}} -@item D-Bus type @tab @tab Lisp type -@item -@item DBUS_TYPE_BOOLEAN @tab @expansion{} @tab @code{t} or @code{nil} -@item DBUS_TYPE_BYTE @tab @expansion{} @tab number -@item DBUS_TYPE_UINT16 @tab @expansion{} @tab number -@item DBUS_TYPE_INT16 @tab @expansion{} @tab number -@item DBUS_TYPE_UINT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT32 @tab @expansion{} @tab number or float -@item DBUS_TYPE_UINT64 @tab @expansion{} @tab number or float -@item DBUS_TYPE_INT64 @tab @expansion{} @tab number or float -@item DBUS_TYPE_DOUBLE @tab @expansion{} @tab float -@item DBUS_TYPE_STRING @tab @expansion{} @tab string -@item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string -@item DBUS_TYPE_SIGNATURE @tab @expansion{} @tab string -@item DBUS_TYPE_ARRAY @tab @expansion{} @tab list -@item DBUS_TYPE_VARIANT @tab @expansion{} @tab list -@item DBUS_TYPE_STRUCT @tab @expansion{} @tab list -@item DBUS_TYPE_DICT_ENTRY @tab @expansion{} @tab list -@end multitable -@end example - -A float object in case of @code{DBUS_TYPE_UINT32}, -@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64} and -@code{DBUS_TYPE_INT6432} is returned, when the C value exceeds the -Emacs number size range. - -The resulting list of the last 4 D-Bus compound types contains as -elements the elements of the D-Bus container, mapped according to the -same rules. - -The signal @code{PropertyModified}, discussed as example in -@ref{Inspection}, would offer as Lisp data the following object -(@var{BOOL} stands here for either @code{nil} or @code{t}): - -@lisp -(@var{NUMBER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{})) -@end lisp - -@defun dbus-byte-array-to-string byte-array -If a D-Bus method or signal returns an array of bytes, which are known -to represent an UTF8 string, this function converts @var{byte-array} -to the corresponding string. Example: - -@lisp -(dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115)) - -@result{} "/etc/hosts" -@end lisp -@end defun - -@defun dbus-unescape-from-identifier string -Retrieve the original string from the encoded @var{string}. -@var{string} must have been coded with -@code{dbus-escape-as-identifier}. Example: - -@lisp -(dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff") - -@ifinfo -@result{} "0123abc_xyz^Aÿ" -@end ifinfo -@ifnotinfo -@result{} "0123abc_xyz^A@"y" -@end ifnotinfo -@end lisp -@end defun - - -@node Synchronous Methods -@chapter Calling methods in a blocking way. -@cindex method calls, synchronous -@cindex synchronous method calls - -Methods can be called synchronously (@dfn{blocking}) or asynchronously -(@dfn{non-blocking}). - -At D-Bus level, a method call consist of two messages: one message -which carries the input parameters to the object owning the method to -be called, and a reply message returning the resulting output -parameters from the object. - -@defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds the method -call must return. The default value is 25.000. If the method call -doesn't return in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -The function returns the resulting values of @var{method} as a list of -Lisp objects, according to the type conversion rules described in -@ref{Type Conversion}. Example: - -@lisp -(dbus-call-method - :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp" - "org.gnome.seahorse.Keys" "GetKeyField" - "openpgp:657984B8C7A966DD" "simple-name") - -@result{} (t ("Philip R. Zimmermann")) -@end lisp - -If the result of the method call is just one value, the converted Lisp -object is returned instead of a list containing this single Lisp -object. Example: - -@lisp -(dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" - "system.kernel.machine") - -@result{} "i686" -@end lisp - -With the @code{dbus-introspect} function it is possible to explore the -interfaces of @samp{org.freedesktop.Hal} service. It offers the -interfaces @samp{org.freedesktop.Hal.Manager} for the object at the -path @samp{/org/freedesktop/Hal/Manager} as well as the interface -@samp{org.freedesktop.Hal.Device} for all objects prefixed with the -path @samp{/org/freedesktop/Hal/devices}. With the methods -@samp{GetAllDevices} and @samp{GetAllProperties}, it is simple to -emulate the @code{lshal} command on GNU/Linux systems: - -@lisp -(dolist (device - (dbus-call-method - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "GetAllDevices")) - (message "\nudi = %s" device) - (dolist (properties - (dbus-call-method - :system "org.freedesktop.Hal" device - "org.freedesktop.Hal.Device" "GetAllProperties")) - (message " %s = %S" - (car properties) (or (caar (cdr properties)) "")))) - -@print{} "udi = /org/freedesktop/Hal/devices/computer - info.addons = (\"hald-addon-acpi\") - info.bus = \"unknown\" - info.product = \"Computer\" - info.subsystem = \"unknown\" - info.udi = \"/org/freedesktop/Hal/devices/computer\" - linux.sysfs_path_device = \"(none)\" - power_management.acpi.linux.version = \"20051216\" - power_management.can_suspend_to_disk = t - power_management.can_suspend_to_ram = \"\" - power_management.type = \"acpi\" - smbios.bios.release_date = \"11/07/2001\" - system.chassis.manufacturer = \"COMPAL\" - system.chassis.type = \"Notebook\" - system.firmware.release_date = \"03/19/2005\" - @dots{}" -@end lisp -@end defun - -@defun dbus-call-method-non-blocking bus service path interface method &optional :timeout timeout &rest args -Call @var{method} on the D-Bus @var{bus}, but don't block the event queue. -This is necessary for communicating to registered D-Bus methods, -which are running in the same Emacs process. - -The arguments are the same as in @code{dbus-call-method}. Example: - -@lisp -(dbus-call-method-non-blocking - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" - "system.kernel.machine") - -@result{} "i686" -@end lisp -@end defun - - -@node Asynchronous Methods -@chapter Calling methods non-blocking. -@cindex method calls, asynchronous -@cindex asynchronous method calls - -@defun dbus-call-method-asynchronously bus service path interface method handler &optional :timeout timeout &rest args -This function calls @var{method} on the D-Bus @var{bus} -asynchronously. @var{bus} is either the symbol @code{:system} or the -symbol @code{:session}. - -@var{service} is the D-Bus service name to be used. @var{path} is the -D-Bus object path, @var{service} is registered at. @var{interface} is -an interface offered by @var{service}. It must provide @var{method}. - -@var{handler} is a Lisp function, which is called when the -corresponding return message has arrived. - -If the parameter @code{:timeout} is given, the following integer -@var{timeout} specifies the maximum number of milliseconds a reply -message must arrive. The default value is 25.000. If there is no -reply message in time, a D-Bus error is raised (@pxref{Errors and -Events}). - -All other arguments args are passed to @var{method} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. - -The function returns a key into the hash table -@code{dbus-registered-functions-table}. The corresponding entry in -the hash table is removed, when the return message has been arrived, -and @var{handler} is called. Example: - -@lisp -(dbus-call-method-asynchronously - :system "org.freedesktop.Hal" - "/org/freedesktop/Hal/devices/computer" - "org.freedesktop.Hal.Device" "GetPropertyString" 'message - "system.kernel.machine") - -@result{} (:system 2) - -@print{} i686 -@end lisp -@end defun - - -@node Receiving Method Calls -@chapter Offering own methods. -@cindex method calls, returning -@cindex returning method calls - -Emacs can also offer own methods, which can be called by other -applications. These methods could be an implementation of an -interface of a well known service, like @samp{org.freedesktop.TextEditor}. - -It could be also an implementation of an own interface. In this case, -the service name must be @samp{org.gnu.Emacs}. The object path shall -begin with @samp{/org/gnu/Emacs/@strong{Application}/}, and the -interface name shall be @code{org.gnu.Emacs.@strong{Application}}. -@samp{@strong{Application}} is the name of the application which -provides the interface. - -@deffn Constant dbus-service-emacs -The well known service name of Emacs. -@end deffn - -@deffn Constant dbus-path-emacs -The object path head "/org/gnu/Emacs" used by Emacs. All object -paths, used by offered methods or signals, shall start with this -string. -@end deffn - -@defun dbus-register-method bus service path interface method handler -With this function, an application registers @var{method} on the D-Bus -@var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name of the D-Bus object -@var{method} is registered for. It must be a known name. - -@var{path} is the D-Bus object path @var{service} is -registered. - -@var{interface} is the interface offered by @var{service}. It must -provide @var{method}. - -@var{handler} is a Lisp function to be called when a @var{method} call -is received. It must accept as arguments the input arguments of -@var{method}. @var{handler} should return a list, whose elements are -to be used as arguments for the reply message of @var{method}. This -list can be composed like the input parameters in @ref{Type -Conversion}. - -If @var{handler} wants to return just one Lisp object and it is not a -cons cell, @var{handler} can return this object directly, instead of -returning a list containing the object. - -The default D-Bus timeout when waiting for a message reply is 25 -seconds. This value could be even smaller, depending on the calling -client. Therefore, @var{handler} shall not last longer than -absolutely necessary. - -@code{dbus-register-method} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{method}. Example: - -@lisp -(defun my-dbus-method-handler (filename) - (let (result) - (if (find-file filename) - (setq result '(:boolean t)) - (setq result '(:boolean nil))) - result)) - -@result{} my-dbus-method-handler - -(dbus-register-method - :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - "org.freedesktop.TextEditor" "OpenFile" - 'my-dbus-method-handler) - -@result{} ((:session "org.freedesktop.TextEditor" "OpenFile") - ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor" - my-dbus-method-handler)) -@end lisp - -If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile} -from another D-Bus application with a filename as parameter, the file -is opened in Emacs, and the method returns either @var{true} or -@var{false}, indicating the success if the method. As test tool one -could use the command line tool @code{dbus-send} in a shell: - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" string:"/etc/hosts" - -@print{} method return sender=:1.22 -> dest=:1.23 reply_serial=2 - boolean true -@end example - -You can indicate an error by raising the Emacs signal -@code{dbus-error}. The handler above could be changed like this: - -@lisp -(defun my-dbus-method-handler (&rest args) - (unless (and (= (length args) 1) (stringp (car args))) - (signal 'dbus-error (list (format "Wrong argument list: %S" args)))) - (condition-case err - (find-file (car args)) - (error (signal 'dbus-error (cdr err)))) - t) - -@result{} my-dbus-method-handler -@end lisp - -The test runs then - -@example -# dbus-send --session --print-reply \ - --dest="org.freedesktop.TextEditor" \ - "/org/freedesktop/TextEditor" \ - "org.freedesktop.TextEditor.OpenFile" \ - string:"/etc/hosts" string:"/etc/passwd" - -@print{} Error org.freedesktop.DBus.Error.Failed: - Wrong argument list: ("/etc/hosts" "/etc/passwd") -@end example -@end defun - - -@node Signals -@chapter Sending and receiving signals. -@cindex signals - -Signals are broadcast messages. They carry input parameters, which -are received by all objects which have registered for such a signal. - -@defun dbus-send-signal bus service path interface signal &rest args -This function is similar to @code{dbus-call-method}. The difference -is, that there are no returning output parameters. - -The function emits @var{signal} on the D-Bus @var{bus}. @var{bus} is -either the symbol @code{:system} or the symbol @code{:session}. It -doesn't matter whether another object has registered for @var{signal}. - -@var{service} is the D-Bus service name of the object the signal is -emitted from. @var{path} is the corresponding D-Bus object path, -@var{service} is registered at. @var{interface} is an interface -offered by @var{service}. It must provide @var{signal}. - -All other arguments args are passed to @var{signal} as arguments. -They are converted into D-Bus types as described in @ref{Type -Conversion}. Example: - -@lisp -(dbus-send-signal - :session dbus-service-emacs dbus-path-emacs - (concat dbus-service-emacs ".FileManager") "FileModified" - "/home/albinus/.emacs") -@end lisp -@end defun - -@defun dbus-register-signal bus service path interface signal handler &rest args -With this function, an application registers for @var{signal} on the -D-Bus @var{bus}. - -@var{bus} is either the symbol @code{:system} or the symbol -@code{:session}. - -@var{service} is the D-Bus service name used by the sending D-Bus -object. It can be either a known name or the unique name of the D-Bus -object sending the signal. In case of a unique name, signals won't be -received any longer once the object owning this unique name has -disappeared, and a new queued object has replaced it. - -When @var{service} is @code{nil}, related signals from all D-Bus -objects shall be accepted. - -@var{path} is the corresponding D-Bus object path, @var{service} is -registered at. It can also be @code{nil} if the path name of incoming -signals shall not be checked. - -@var{interface} is an interface offered by @var{service}. It must -provide @var{signal}. - -@var{handler} is a Lisp function to be called when the @var{signal} is -received. It must accept as arguments the output parameters -@var{signal} is sending. - -All other arguments @var{args}, if specified, must be strings. They -stand for the respective arguments of @var{signal} in their order, and -are used for filtering as well. A @code{nil} argument might be used -to preserve the order. - -@code{dbus-register-signal} returns a Lisp object, which can be used -as argument in @code{dbus-unregister-object} for removing the -registration for @var{signal}. Example: - -@lisp -(defun my-dbus-signal-handler (device) - (message "Device %s added" device)) - -@result{} my-dbus-signal-handler - -(dbus-register-signal - :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - "org.freedesktop.Hal.Manager" "DeviceAdded" - 'my-dbus-signal-handler) - -@result{} ((:system "org.freedesktop.Hal.Manager" "DeviceAdded") - ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager" - my-signal-handler)) -@end lisp - -As we know from the introspection data of interface -@samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded} -provides one single parameter, which is mapped into a Lisp string. -The callback function @code{my-dbus-signal-handler} must define one -single string argument therefore. Plugging an USB device to your -machine, when registered for signal @samp{DeviceAdded}, will show you -which objects the GNU/Linux @code{hal} daemon adds. -@end defun - -@defun dbus-unregister-object object -Unregister @var{object} from the D-Bus. @var{object} must be the -result of a preceding @code{dbus-register-signal} or -@code{dbus-register-method} call. It returns @code{t} if @var{object} -has been unregistered, @code{nil} otherwise. -@end defun - - -@node Errors and Events -@chapter Errors and events. -@cindex errors -@cindex events - -Input parameters of @code{dbus-call-method}, -@code{dbus-call-method-non-blocking}, -@code{dbus-call-method-asynchronously}, and -@code{dbus-register-signal} are checked for correct D-Bus types. If -there is a type mismatch, the Lisp error @code{wrong-type-argument} -@code{D-Bus ARG} is raised. - -All errors raised by D-Bus are signaled with the error symbol -@code{dbus-error}. If possible, error messages from D-Bus are -appended to the @code{dbus-error}. - -@defspec dbus-ignore-errors forms@dots{} -This executes @var{forms} exactly like a @code{progn}, except that -@code{dbus-error} errors are ignored during the @var{forms}. These -errors can be made visible when variable @code{dbus-debug} is set to -@code{t}. -@end defspec - -Incoming D-Bus messages are handled as Emacs events (see @pxref{Misc -Events, , , elisp}). The generated event has this form: - -@lisp -(dbus-event @var{bus} @var{type} @var{serial} @var{service} @var{path} @var{interface} @var{member} @var{handler} - &rest @var{args}) -@end lisp - -@var{bus} identifies the D-Bus the message is coming from. It is -either the symbol @code{:system} or the symbol @code{:session}. - -@var{type} is the D-Bus message type which has caused the event. It -can be @code{dbus-message-type-invalid}, -@code{dbus-message-type-method-call}, -@code{dbus-message-type-method-return}, -@code{dbus-message-type-error}, or @code{dbus-message-type-signal}. -@var{serial} is the serial number of the received D-Bus message. - -@var{service} and @var{path} are the unique name and the object path -of the D-Bus object emitting the message. @var{interface} and -@var{member} denote the message which has been sent. - -@var{handler} is the callback function which has been registered for -this message (see @pxref{Signals}). When a @code{dbus-event} event -arrives, @var{handler} is called with @var{args} as arguments. - -In order to inspect the @code{dbus-event} data, you could extend the -definition of the callback function in @ref{Signals}: - -@lisp -(defun my-dbus-signal-handler (&rest args) - (message "my-dbus-signal-handler: %S" last-input-event)) -@end lisp - -There exist convenience functions which could be called inside a -callback function in order to retrieve the information from the event. - -@defun dbus-event-bus-name event -Returns the bus name @var{event} is coming from. -The result is either the symbol @code{:system} or the symbol @code{:session}. -@end defun - -@defun dbus-event-message-type event -Returns the message type of the corresponding D-Bus message. The -result is a number. -@end defun - -@defun dbus-event-serial-number event -Returns the serial number of the corresponding D-Bus message. -The result is a number. -@end defun - -@defun dbus-event-service-name event -Returns the unique name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-path-name event -Returns the object path of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-interface-name event -Returns the interface name of the D-Bus object @var{event} is coming from. -@end defun - -@defun dbus-event-member-name event -Returns the member name of the D-Bus object @var{event} is coming -from. It is either a signal name or a method name. -@end defun - -D-Bus errors are not propagated during event handling, because it is -usually not desired. D-Bus errors in events can be made visible by -setting the variable @code{dbus-debug} to @code{t}. They can also be -handled by a hook function. - -@defvar dbus-event-error-hooks -This hook variable keeps a list of functions, which are called when a -D-Bus error happens in the event handler. Every function must accept -two arguments, the event and the error variable catched in -@code{condition-case} by @code{dbus-error}. - -Such functions can be used the adapt the error signal to be raised. -Example: - -@lisp -(defun my-dbus-event-error-handler (event error) - (when (string-equal (concat dbus-service-emacs ".FileManager") - (dbus-event-interface-name event)) - (message "my-dbus-event-error-handler: %S %S" event error) - (signal 'file-error (cdr error)))) - -(add-hook 'dbus-event-error-hooks 'my-dbus-event-error-handler) -@end lisp -@end defvar - -Hook functions shall take into account, that there might be other -D-Bus applications running. Therefore, they shall check carefully, -whether a given D-Bus error is related to them. - - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye - -@ignore - arch-tag: 2eeec19d-0caf-44e0-a193-329d7f9951d8 -@end ignore diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi deleted file mode 100644 index 56e2c86d1e9..00000000000 --- a/doc/misc/dired-x.texi +++ /dev/null @@ -1,1266 +0,0 @@ -\input texinfo @comment -*-texinfo-*- - -@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs -@c -@c Author: Sebastian Kremer -@c Lawrence R. Dodd -@c [Dodd's address no longer valid.] - -@comment %**start of header (This is for running Texinfo on a region.) -@c FOR GNU EMACS USE ../info/dired-x BELOW -@setfilename ../../info/dired-x -@c dired-x.el REVISION NUMBER -@settitle Dired Extra Version 2 User's Manual -@iftex -@finalout -@end iftex -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -Copyright @copyright{} 1994, 1995, 1999, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Dired-X: (dired-x). Dired Extra Features. -@end direntry - -@c @smallbook -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % For printing in double spaces -@end tex - -@titlepage -@sp 6 -@c dired-x.el REVISION NUMBER -@center @titlefont{Dired Extra Version 2} -@sp 2 -@center @titlefont{For The GNU Emacs} -@sp 1 -@center @titlefont{Directory Editor} -@sp 4 -@center Lawrence R@. Dodd -@c @center @t{dodd@@roebling.poly.edu} -@sp 5 -@center (Based on @file{dired.texi} by Sebastian Kremer ) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - - -@ifnottex - -@node Top -@comment node-name, next, previous, up - -@noindent -This documents the ``extra'' features for Dired Mode for GNU Emacs that are -provided by the file @file{dired-x.el}. - -@itemize @bullet - -@item -Based on @file{dired.texi} by Sebastian Kremer - -@c dired-x.el REVISION NUMBER -@item -For @file{dired-x.el} revision 2 - -@c @item -@c Revision of this manual: 2.53 (2001/02/25 14:05:46) - -@c @item -@c Bugs to Lawrence R. Dodd . @emph{Please} type -@c @kbd{M-x dired-x-submit-report} to submit a bug report (@pxref{Bugs}). - -@c @item -@c You can obtain a copy of this package via anonymous ftp in -@c @t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz} - -@end itemize - -@insertcopying - -@menu -* Introduction:: -* Installation:: -* Omitting Files in Dired:: -* Local Variables:: -* Shell Command Guessing:: -* Virtual Dired:: -* Advanced Mark Commands:: -* Multiple Dired Directories:: -* Find File At Point:: -* Miscellaneous Commands:: -* Bugs:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: - -@end menu - -@end ifnottex - -@node Introduction, Installation, Top, Top -@comment node-name, next, previous, up -@chapter Introduction - -This documents the @emph{extra} features for Dired Mode for GNU Emacs. It -is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el}. - -In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has -been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs -19 distribution has been removed and some material was modified for agreement -with the functions in @file{dired.el} and @file{dired-aux.el}. For example, -the code using @code{gmhist} history functions was replaced with code using -the mini-buffer history now built into GNU Emacs. Finally, a few other -features have been added and a few more functions have been bound to keys. - -@ifnottex -@menu -* Features:: -* Technical Details:: -@end menu -@end ifnottex - -@node Features, Technical Details, , Introduction -@comment node-name, next, previous, up -@section Features -@cindex Features - -Some features provided by Dired Extra - -@enumerate -@item -Omitting uninteresting files from Dired listing. -@itemize @bullet -@xref{Omitting Files in Dired}. -@end itemize -@item -Local variables for Dired directories. -@itemize @bullet -@xref{Local Variables}. -@end itemize -@item -Guessing shell commands in Dired buffers. -@itemize @bullet -@xref{Shell Command Guessing}. -@end itemize -@item -Running Dired command in non-Dired buffers. -@itemize @bullet -@xref{Virtual Dired}. -@end itemize -@item -Finding a file mentioned in a buffer -@itemize @bullet -@xref{Find File At Point}. -@end itemize -@item -Commands using file marking. -@itemize @bullet -@xref{Advanced Mark Commands}. -@end itemize -@end enumerate - -@noindent -@file{dired-x.el} binds some functions to keys in Dired Mode (@pxref{Key -Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to -@code{dired-jump} (@pxref{Miscellaneous Commands}). It may also bind @kbd{C-x -C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and -@code{dired-x-find-file-other-window}, respectively (@pxref{Find File At -Point}). - -@node Technical Details, , Features, Introduction -@comment node-name, next, previous, up -@section Technical Details -@cindex Redefined functions -@cindex @file{dired-aux.el} - -When loaded this code @emph{redefines} the following functions of GNU Emacs -from @file{dired.el} - -@itemize @bullet -@item -@code{dired-clean-up-after-deletion} -@item -@code{dired-find-buffer-nocreate} -@item -@code{dired-initial-position} -@item -@code{dired-up-directory} -@end itemize - -@noindent -and the following functions from @file{dired-aux.el} - -@itemize @bullet -@item -@code{dired-add-entry} -@item -@code{dired-read-shell-command} -@end itemize - -@node Installation, Omitting Files in Dired, Introduction, Top -@comment node-name, next, previous, up -@chapter Installation - -@noindent -This manual describes the Dired features provided by the file -@file{dired-x.el}. To take advantage of these features, you must load the -file and (optionally) set some variables. - -@noindent -In your @file{.emacs} file in your home directory, or in the system-wide -initialization file @file{default.el} in the @file{site-lisp} directory, put - -@example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") - ;; (setq dired-x-hands-off-my-keys nil) - )) -(add-hook 'dired-mode-hook - (lambda () - ;; Set dired-x buffer-local variables here. For example: - ;; (dired-omit-mode 1) - )) -@end example - -@noindent -This will load @file{dired-x.el} when Dired is first invoked (for example, -when you first type @kbd{C-x d}). - -@ifnottex -@menu -* Optional Installation Dired Jump:: -* Optional Installation File At Point:: -@end menu -@end ifnottex - -@node Optional Installation Dired Jump, Optional Installation File At Point, , Installation -@comment node-name, next, previous, up -@section Optional Installation Dired Jump - -@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} - -In order to have @code{dired-jump} and @code{dired-jump-other-window} -(@pxref{Miscellaneous Commands}) work @emph{before} @code{dired} and -@code{dired-x} have been properly loaded the user should set-up an autoload -for these functions. In your @file{.emacs} file put - -@example -;; Autoload `dired-jump' and `dired-jump-other-window'. -;; We autoload from FILE dired.el. This will then load dired-x.el -;; and hence define `dired-jump' and `dired-jump-other-window'. -(define-key global-map "\C-x\C-j" 'dired-jump) -(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) - -(autoload (quote dired-jump) "dired" "\ -Jump to Dired buffer corresponding to current buffer. -If in a file, Dired the current directory and move to file's line. -If in Dired already, pop up a level and goto old directory's line. -In case the proper Dired file line cannot be found, refresh the Dired -buffer and try again." t nil) - -(autoload (quote dired-jump-other-window) "dired" "\ -Like \\[dired-jump] (dired-jump) but in other window." t nil) -@end example - -Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file -@file{../lisp/loaddefs.el} of the Emacs distribution already contains the -proper auto-loading for @code{dired-jump} so you need only put - -@example -(define-key global-map "\C-x\C-j" 'dired-jump) -@end example - -@noindent -in your @file{.emacs} file in order to have @kbd{C-x C-j} work -before @code{dired} is loaded. - -@node Optional Installation File At Point, , Optional Installation Dired Jump, Installation -@comment node-name, next, previous, up -@section Optional Installation File At Point - -@cindex Binding @code{dired-x-find-file} -If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over -@code{find-file} (@pxref{Find File At Point}), then you will need to set -@code{dired-x-hands-off-my-keys} and make a call to the function -@code{dired-x-bind-find-file} in the @code{dired-load-hook}: - -@example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - ;; Make sure our binding preference is invoked. - (dired-x-bind-find-file) - )) -@end example - -Alternatively, you can set the variable @emph{before} @file{dired-x.el} is -loaded - -@example -(add-hook 'dired-load-hook - (lambda () - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - (load "dired-x") - )) -@end example - -@node Omitting Files in Dired, Local Variables, Installation, Top -@comment node-name, next, previous, up -@chapter Omitting Files in Dired - -@cindex Omitting Files in Dired -@cindex Uninteresting files -@dfn{Omitting} a file means removing it from the directory listing. Omitting -is useful for keeping Dired buffers free of ``uninteresting'' files (for -instance, auto-save, auxiliary, backup, and revision control files) so that -the user can concentrate on the interesting files. Like hidden files, omitted -files are never seen by Dired. Omitting differs from hiding in several -respects: - -@itemize @bullet - -@item -Omitting works on individual files, not on directories; an entire directory -cannot be omitted (though each of its files could be). - -@item -Omitting is wholesale; if omitting is turned on for a Dired buffer, then all -uninteresting files listed in that buffer are omitted. The user does not omit -(or unomit) files one at a time. - -@item -Omitting can be automatic; uninteresting file lines in the buffer can be -removed before the user ever sees them. - -@item -Marked files are never omitted. -@end itemize - -@table @kbd -@item M-o -@kindex M-o -@findex dired-omit-mode -(@code{dired-omit-mode}) Toggle between displaying and omitting -``uninteresting'' files. -@item * O -@kindex * O -@findex dired-mark-omitted -(@code{dired-mark-omitted}) Mark ``uninteresting'' files. -@end table - -@noindent -In order to make Dired Omit work you first need to load @file{dired-x.el} -inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate -@code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). - -@ifnottex -@menu -* Omitting Variables:: -* Omitting Examples:: -* Omitting Technical:: -@end menu -@end ifnottex - -@node Omitting Variables, Omitting Examples, , Omitting Files in Dired -@comment node-name, next, previous, up - -@section Omitting Variables - -@cindex Customizing file omitting -The following variables can be used to customize omitting. - -@table @code - -@vindex dired-omit-mode -@item dired-omit-mode - -Default: @code{nil} - -@cindex How to make omitting the default in Dired -If non-@code{nil}, ``uninteresting'' files are not listed. -Uninteresting files are those whose files whose names match regexp -@code{dired-omit-files}, plus those ending with extensions in -@code{dired-omit-extensions}. @kbd{M-o} (@code{dired-omit-mode}) -toggles its value, which is buffer-local. Put - -@example -(dired-omit-mode 1) -@end example - -@noindent -inside your @code{dired-mode-hook} to have omitting initially turned on in -@emph{every} Dired buffer (@pxref{Installation}). You can then use @kbd{M-o} to -unomit in that buffer. - -To enable omitting automatically only in certain directories one can use Dired -Local Variables and put - -@example -Local Variables: -dired-omit-mode: t -End: -@end example - -@noindent -into a file @file{.dired} (the default value of -@code{dired-local-variables-file}) in that directory (@pxref{Local Variables}). - -@table @code -@findex dired-omit-here-always -@item dired-omit-here-always - -This is an interactive function that creates a local variables file exactly -like the example above (if it does not already exist) in the file -@code{dired-local-variables-file} in the current directory and then refreshes -the directory listing (@pxref{Local Variables}). -@end table - -@vindex dired-omit-files -@item dired-omit-files - -Default: @code{"^#\\|\\.$"} - -Files whose names match this buffer-local regexp will not be displayed. -This only has effect when @code{dired-omit-mode}'s value is @code{t}. - -The default value omits the special directories @file{.} and @file{..} and -autosave files (plus other files ending in @file{.}) (@pxref{Omitting Examples}). - -@vindex dired-omit-extensions -@item dired-omit-extensions - -Default: The elements of @code{completion-ignored-extensions}, -@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} -and @code{dired-texinfo-unclean-extensions}. - -If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. -Its format is the same as that of @code{completion-ignored-extensions}. - -@vindex dired-omit-localp -@item dired-omit-localp - -Default: @code{no-dir} - -The @var{localp} argument @code{dired-omit-expunge} passes to -@code{dired-get-filename}. If it is @code{no-dir}, omitting is much faster, -but you can only match against the non-directory part of the file name. Set it -to @code{nil} if you need to match the whole file name or @code{t} to match the -file name relative to the buffer's top-level directory. - -@item dired-omit-marker-char -@vindex dired-omit-marker-char -@cindex Omitting additional files -Default: @kbd{C-o} - -Temporary marker used by Dired to implement omitting. Should never be used -as marker by the user or other packages. There is one exception to this rule: -by adding - -@example -(setq dired-mark-keys "\C-o") -;; i.e., the value of dired-omit-marker-char -;; (which is not defined yet) -@end example - -@noindent -to your @file{~/.emacs}, you can bind the @kbd{C-o} key to insert a -@kbd{C-o} marker, thus causing these files to be omitted in addition to the -usually omitted files. Unfortunately the files you omitted manually this way -will show up again after reverting the buffer, unlike the others. - -@end table - -@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired -@comment node-name, next, previous, up -@section Examples of Omitting Various File Types - -@itemize @bullet - -@item -@cindex RCS files, how to omit them in Dired -@cindex Omitting RCS files in Dired -If you wish to avoid seeing RCS files and the @file{RCS} directory, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^RCS$\\|,v$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). This assumes -@code{dired-omit-localp} has its default value of @code{no-dir} to make the -@code{^}-anchored matches work. As a slower alternative, with -@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of -@code{^} in the regexp. - -@item -@cindex Tib files, how to omit them in Dired -@cindex Omitting tib files in Dired -If you use @code{tib}, the bibliography program for use with @TeX{} and -La@TeX{}, and you -want to omit the @file{INDEX} and the @file{*-t.tex} files, then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). - -@item -@cindex Dot files, how to omit them in Dired -@cindex Omitting dot files in Dired -If you do not wish to see @samp{dot} files (files starting with a @file{.}), -then put - -@example -(setq dired-omit-files - (concat dired-omit-files "\\|^\\..+$")) -@end example - -@noindent -in the @code{dired-load-hook} (@pxref{Installation}). - -@end itemize - -@node Omitting Technical, , Omitting Examples, Omitting Files in Dired -@comment node-name, next, previous, up -@section Some Technical Details of Omitting - -Loading @file{dired-x.el} will install Dired Omit by putting -@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will -call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} -in your @code{dired-mode-hook}. - -@node Local Variables, Shell Command Guessing, Omitting Files in Dired, Top -@comment node-name, next, previous, up -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -When Dired visits a directory, it looks for a file whose name is the value of -variable @code{dired-local-variables-file} (default: @file{.dired}). If such -a file is found, Dired will temporarily insert it into the Dired buffer and -run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that if may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. The value can be @code{t}, -@code{nil}, or something else. A value of @code{t} means local-variables -lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means -they are ignored; anything else means query. This variable temporarily -overrides the value of @code{enable-local-variables} when the Dired Local -Variables are hacked. -@end table - -@node Shell Command Guessing, Virtual Dired, Local Variables, Top -@comment node-name, next, previous, up -@chapter Shell Command Guessing -@cindex Guessing shell commands for files. - -Based upon the name of a file, Dired tries to guess what shell -command you might want to apply to it. For example, if you have point -on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess -you want to @samp{tar xvf} it and suggest that as the default shell -command. - -The default is mentioned in brackets and you can type @kbd{M-n} to get -the default into the minibuffer and then edit it, e.g., to change -@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given -file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type -@kbd{M-n} several times to see each of the matching commands. - -Dired only tries to guess a command for a single file, never for a list -of marked files. - -@table @code -@item dired-guess-shell-alist-default -@vindex dired-guess-shell-alist-default -Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. -The elements of @code{dired-guess-shell-alist-user} (defined by the -user) will override these rules.@refill - -@item dired-guess-shell-alist-user -@vindex dired-guess-shell-alist-user -If non-@code{nil}, a user-defined alist of file regexps and their suggested -commands. These rules take precedence over the predefined rules in the -variable @code{dired-guess-shell-alist-default} (to which they are prepended) -when @code{dired-do-shell-command} is run). -@refill - -Each element of the alist looks like - -@example -(@var{regexp} @var{command}@dots{}) -@end example - -@noindent -where each @var{command} can either be a string or a Lisp expression -that evaluates to a string. If several commands are given, all of -them will temporarily be pushed onto the history. - -If @samp{*} in the shell command, that means to substitute the file -name. - -You can set this variable in your @file{~/.emacs}. For example, -to add rules for @samp{.foo} and @samp{.bar} file extensions, write - -@example -(setq dired-guess-shell-alist-user - (list - (list "\\.foo$" "@var{foo-command}");; fixed rule - ;; possibly more rules... - (list "\\.bar$";; rule with condition test - '(if @var{condition} - "@var{bar-command-1}" - "@var{bar-command-2}")))) -@end example - -@noindent -This will override any predefined rules for the same extensions. - -@item dired-guess-shell-case-fold-search -@vindex dired-guess-shell-case-fold-search -Default: @code{t} - -Non-@code{nil} means @code{dired-guess-shell-alist-default} and -@code{dired-guess-shell-alist-user} are matched case-insensitively. - -@item dired-guess-shell-gnutar -@vindex dired-guess-shell-gnutar -@cindex Passing GNU Tar its @samp{z} switch. -Default: @code{nil} - -If non-@code{nil}, this is the name of the GNU Tar executable (e.g., -@samp{tar} or @samp{gnutar}). GNU Tar's @samp{z} switch is used for -compressed tar files. -If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is -then used. - -@item dired-guess-shell-gzip-quiet -@vindex dired-guess-shell-gzip-quiet -@cindex @code{gzip} -Default: @code{t} - -A non-@code{nil} value means that @samp{-q} is passed to @code{gzip} -overriding a verbose option in the @env{GZIP} environment variable. - -@item dired-guess-shell-znew-switches nil -@vindex dired-guess-shell-znew-switches nil -@cindex @code{znew} -Default: @code{nil} - -A string of switches passed to @code{znew}. An example is -@samp{-K} which will make @code{znew} keep a @file{.Z} file when it is -smaller than the @file{.gz} file. - -@item dired-shell-command-history nil -@vindex dired-shell-command-history nil - -History list for commands that read dired-shell commands. -@end table - -@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top -@comment node-name, next, previous, up -@chapter Virtual Dired - -@cindex Virtual Dired -@cindex Perusing @code{ls} listings -@cindex @code{ls} listings, how to peruse them in Dired -Using @dfn{Virtual Dired} means putting a buffer with Dired-like -contents in Dired mode. The files described by the buffer contents need -not actually exist. This is useful if you want to peruse an @samp{ls -lR} -output file, for example one you got from an FTP server. You can use -all motion commands usually available in Dired. You can also use -it to save a Dired buffer in a file and resume it in a later session. - -@findex dired-virtual -@kindex g -@findex dired-virtual-revert -Type @kbd{M-x dired-virtual} to put the current buffer into virtual -Dired mode. You will be prompted for the top level directory of this -buffer, with a default value guessed from the buffer contents. To -convert the virtual to a real Dired buffer again, type @kbd{g} (which -calls @code{dired-virtual-revert}) in the virtual Dired buffer and -answer @samp{y}. You don't have to do this, though: you can relist -single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory -headerline, leaving the buffer in virtual Dired mode all the time. - -@findex dired-virtual-mode -@vindex auto-mode-alist -The function @samp{dired-virtual-mode} is specially designed to turn on -virtual Dired mode from the @code{auto-mode-alist}. To edit all -@file{*.dired} files automatically in virtual Dired mode, put this into your -@file{~/.emacs}: - -@example -(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode) - auto-mode-alist)) -@end example - -@noindent -The regexp is a bit more complicated than usual to exclude @file{.dired} -local-variable files. - -@node Advanced Mark Commands, Multiple Dired Directories, Virtual Dired, Top -@comment node-name, next, previous, up -@chapter Advanced Mark Commands - -@table @kbd -@item F -@kindex F -@cindex Visiting several files at once -@cindex Simultaneous visiting of several files -@findex dired-do-find-marked-files -(@code{dired-do-find-marked-files}) Find all marked files at once displaying -them simultaneously. If optional @var{noselect} is non-@code{nil} then just -find the -files but do not select. If you want to keep the Dired buffer displayed, type -@kbd{C-x 2} first. If you want just the marked files displayed and nothing -else, type @kbd{C-x 1} first. - -The current window is split across all files marked, as evenly as possible. -Remaining lines go to the bottom-most window. The number of files that can be -displayed this way is restricted by the height of the current window and the -variable @code{window-min-height}. -@end table - -@table @code -@item dired-mark-extension -@findex dired-mark-extension -Mark all files with a certain extension for use in later commands. A @samp{.} -is not automatically prepended to the string entered, you must type it -explicitly. - -When called from Lisp, @var{extension} may also be a list of extensions -and an optional argument @var{marker-char} specifies the marker used. - -@item dired-flag-extension -@findex dired-flag-extension -Flag all files with a certain extension for deletion. A @samp{.} is -@emph{not} automatically prepended to the string entered. -@end table - -@ifnottex -@menu -* Advanced Cleaning Functions:: -* Advanced Cleaning Variables:: -* Special Marking Function:: -@end menu -@end ifnottex - -@node Advanced Cleaning Functions, Advanced Cleaning Variables, , Advanced Mark Commands -@comment node-name, next, previous, up - -@section Advanced Cleaning Functions - -@table @code -@item dired-clean-patch -@findex dired-clean-patch -Flag dispensable files created by the @samp{patch} program for deletion. See -variable @code{dired-patch-unclean-extensions}. - -@item dired-clean-tex -@findex dired-clean-tex -Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for -deletion. See the following variables (@pxref{Advanced Cleaning Variables}): - -@itemize @bullet -@item -@code{dired-tex-unclean-extensions} -@item -@code{dired-texinfo-unclean-extensions} -@item -@code{dired-latex-unclean-extensions} -@item -@code{dired-bibtex-unclean-extensions} -@end itemize - -@item dired-very-clean-tex -@findex dired-very-clean-tex -Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, -and @file{*.dvi} files for deletion. -@end table - -@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands -@comment node-name, next, previous, up - -@section Advanced Cleaning Variables - -@noindent Variables used by the above cleaning commands (and in the default value for -variable @code{dired-omit-extensions}, @pxref{Omitting Variables}) - -@table @code -@item dired-patch-unclean-extensions -@vindex dired-patch-unclean-extensions -Default: @code{(".rej" ".orig")} - -List of extensions of dispensable files created by the @samp{patch} program. - -@item dired-tex-unclean-extensions -@vindex dired-tex-unclean-extensions -Default: @code{(".toc" ".log" ".aux")} - -List of extensions of dispensable files created by @TeX{}. - -@item dired-texinfo-unclean-extensions -@vindex dired-texinfo-unclean-extensions -Default: @code{(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} -@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} - -List of extensions of dispensable files created by @samp{texinfo}. - -@item dired-latex-unclean-extensions -@vindex dired-latex-unclean-extensions -Default: @code{(".idx" ".lof" ".lot" ".glo")} - -List of extensions of dispensable files created by La@TeX{}. - -@item dired-bibtex-unclean-extensions -@vindex dired-bibtex-unclean-extensions -Default: @code{(".blg" ".bbl")} - -List of extensions of dispensable files created by Bib@TeX{}. -@end table - -@node Special Marking Function, , Advanced Cleaning Variables, Advanced Mark Commands -@comment node-name, next, previous, up - -@section Special Marking Function - -@table @kbd -@item M-( -@kindex M-( -@findex dired-mark-sexp -@cindex Lisp expression, marking files with in Dired -@cindex Mark file by Lisp expression -(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns -non-@code{nil}. With a prefix argument, unflag those files instead. - -The @var{predicate} is a Lisp expression that can refer to the following -symbols: -@table @code -@item inode -[@i{integer}] the inode of the file (only for @samp{ls -i} output) -@item s -[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or, -with @samp{-k}, in KBytes) -@item mode -[@i{string}] file permission bits, e.g., @samp{-rw-r--r--} -@item nlink -[@i{integer}] number of links to file -@item uid -[@i{string}] owner -@item gid -[@i{string}] group (If the gid is not displayed by @samp{ls}, this -will still be set (to the same as uid)) -@item size -[@i{integer}] file size in bytes -@item time -[@i{string}] the time that @samp{ls} displays, e.g., @samp{Feb 12 14:17} -@item name -[@i{string}] the name of the file -@item sym -[@i{string}] if file is a symbolic link, the linked-to name, else @code{""} -@end table - -@noindent -For example, use -@example -(equal 0 size) -@end example -to mark all zero length files. - -To find out all not yet compiled Emacs Lisp files in a directory, Dired -all @file{.el} files in the lisp directory using the wildcard -@samp{*.el}. Then use @kbd{M-(} with -@example -(not (file-exists-p (concat name "c"))) -@end example -to mark all @file{.el} files without a corresponding @file{.elc} file. - -@end table - -@node Multiple Dired Directories, Find File At Point, Advanced Mark Commands, Top -@comment node-name, next, previous, up -@chapter Multiple Dired Directories and Non-Dired Commands - -@cindex Multiple Dired directories -@cindex Working directory -An Emacs buffer can have but one working directory, stored in the -buffer-local variable @code{default-directory}. A Dired buffer may have -several subdirectories inserted, but it still has only one working -directory: that of the top-level Dired directory in that buffer. For -some commands it is appropriate that they use the current Dired -directory instead of @code{default-directory}, e.g., @code{find-file} and -@code{compile}. - -A general mechanism is provided for special handling of the working -directory in special major modes: - -@table @code -@item default-directory-alist -@vindex default-directory-alist -Default: @code{((dired-mode . (dired-current-directory)))} - -Alist of major modes and their notion of @code{default-directory}, as a -Lisp expression to evaluate. A resulting value of @code{nil} is ignored -in favor of @code{default-directory}. - -@item dired-default-directory -@findex dired-default-directory -Use this function like you would use the variable -@code{default-directory}, except that @code{dired-default-directory} -also consults the variable @code{default-directory-alist}. -@end table - -@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top -@comment node-name, next, previous, up - -@section Find File At Point -@cindex Visiting a file mentioned in a buffer -@cindex Finding a file at point - -@file{dired-x} provides a method of visiting or editing a file mentioned in -the buffer you are viewing (e.g., a mail buffer, a news article, a -@file{README} file, etc.) or to test if that file exists. You can then modify -this in the minibuffer after snatching the file name. - -When installed @file{dired-x} will substitute @code{dired-x-find-file} for -@code{find-file} (normally bound to @kbd{C-x C-f}) and -@code{dired-x-find-file-other-window} for @code{find-file-other-window} -(normally bound to @kbd{C-x 4 C-f}). - -In order to use this feature, you will need to set -@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} -(@pxref{Optional Installation File At Point}). - -@table @code -@item dired-x-find-file -@findex dired-x-find-file -@kindex C-x C-f - -@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound -to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which -case it will use the file name at point as a guess for the file to visit. - -For example, if the buffer you were reading contained the words - -@example -Available via anonymous ftp in - - /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -then you could move your cursor to the line containing the ftp address and -type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The -minibuffer would read - -@example -Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz -@end example - -@noindent -with the point after the last @code{/}. If you hit @key{RET}, emacs will visit -the file at that address. This also works with files on your own computer. - -@item dired-x-find-file-other-window -@findex dired-x-find-file-other-window -@kindex C-x 4 C-f - -@code{dired-x-find-file-other-window} behaves exactly like -@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a -prefix argument is used. See @code{dired-x-find-file} for more information. - -@item dired-x-hands-off-my-keys -@vindex dired-x-hands-off-my-keys -If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind -@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it -should not bind @code{dired-x-find-file-other-window} over -@code{find-file-other-window}. If you change this variable after -@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The -default value of this variable is @code{t}; by default, the binding is not -done. See @xref{Optional Installation File At Point}. - -@item dired-x-bind-find-file -@findex dired-x-bind-find-file -A function, which can be called interactively or in your @file{~/.emacs} file, -that uses the value of @code{dired-x-hands-off-my-keys} to determine if -@code{dired-x-find-file} should be bound over @code{find-file} and -@code{dired-x-find-file-other-window} bound over -@code{find-file-other-window}. See @xref{Optional Installation File At Point}. -@end table - -@node Miscellaneous Commands, Bugs, Find File At Point, Top -@comment node-name, next, previous, up -@chapter Miscellaneous Commands - -Miscellaneous features not fitting anywhere else: - -@table @code -@item dired-find-subdir -@vindex dired-find-subdir -Default: @code{nil} - -If non-@code{nil}, Dired does not make a new buffer for a directory if it can -be found (perhaps as subdirectory) in some existing Dired buffer. - -If there are several Dired buffers for a directory, the most recently -used is chosen. - -Dired avoids switching to the current buffer, so that if you have a -normal and a wildcard buffer for the same directory, @kbd{C-x d RET} -will toggle between those two. -@end table - -@table @kbd -@findex dired-goto-subdir -@kindex M-G -@item M-G -(@code{dired-goto-subdir}) Go to the header line of an inserted directory. -This command reads its argument, with completion derived from the names of the -inserted subdirectories. -@end table - -@table @code -@item dired-smart-shell-command -@findex dired-smart-shell-command -@findex shell-command -@kindex M-! -Like function @code{shell-command}, but in the current Dired directory. -Bound to @kbd{M-!} in Dired buffers. - -@item dired-jump -@findex dired-jump -@kindex C-x C-j -@cindex Jumping to Dired listing containing file. -Bound to @kbd{C-x C-j}. Jump back to Dired: If in a file, edit the current -directory and move to file's line. If in Dired already, pop up a level and -go to old directory's line. In case the proper Dired file line cannot be -found, refresh the Dired buffer and try again. - -@item dired-jump-other-window -@findex dired-jump-other-window -@kindex C-x 4 C-j -Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. - -These functions can be autoloaded so they work even though @file{dired-x.el} -has not been loaded yet (@pxref{Optional Installation Dired Jump}). - -@vindex dired-bind-jump -If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be -bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to -@kbd{C-x 4 C-j}. - -@item dired-vm -@cindex Reading mail. -@kindex V -@findex dired-vm -Bound to @kbd{V} if @code{dired-bind-vm} is @code{t}. Run VM on this -file (assumed to be a UNIX mail folder). - -@vindex dired-vm-read-only-folders -If you give this command a prefix argument, it will visit the folder -read-only. This only works in VM 5, not VM 4. - -If the variable @code{dired-vm-read-only-folders} is @code{t}, -@code{dired-vm} will -visit all folders read-only. If it is neither @code{nil} nor @code{t}, e.g., -the symbol @code{if-file-read-only}, only files not writable by you are -visited read-only. This is the recommended value if you run VM 5. - -@vindex dired-bind-vm -If the variable @code{dired-bind-vm} is @code{t}, @code{dired-vm} will be bound -to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. - -@item dired-rmail -@cindex Reading mail. -@findex dired-rmail -Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this -file (assumed to be mail folder in Rmail format). - -@item dired-info -@kindex I -@cindex Running info. -@findex dired-info -Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info -format). - -@vindex dired-bind-info -If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will -not be bound to @kbd{I}. - -@item dired-man -@cindex Running man. -@kindex N -@findex dired-man -Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} -format). - -@vindex dired-bind-man -If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not -be bound to @kbd{N}. - -@item dired-do-relsymlink -@cindex Relative symbolic links. -@kindex Y -@findex dired-do-relsymlink -Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a -directory, or make a relative symbolic link to the current file. This creates -relative symbolic links like - -@example - foo -> ../bar/foo -@end example - -@noindent -not absolute ones like - -@example - foo -> /ugly/path/that/may/change/any/day/bar/foo -@end example - -@item dired-do-relsymlink-regexp -@kindex %Y -@findex dired-do-relsymlink-regexp -Bound to @kbd{%Y}. Relative symlink all marked files containing -@var{regexp} to @var{newname}. See functions -@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more -info. -@end table - -@node Bugs, GNU Free Documentation License, Miscellaneous Commands, Top -@comment node-name, next, previous, up -@chapter Bugs -@cindex Bugs -@findex dired-x-submit-report - -@noindent -If you encounter a bug in this package, wish to suggest an -enhancement, or want to make a smart remark, then type - -@example -@kbd{M-x dired-x-submit-report} -@end example - -@noindent -to set up an outgoing mail buffer, with the proper address to the -@file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field. -This command also inserts information that the Dired X maintainer can use to -recreate your exact setup, making it easier to verify your bug or social -maladjustment. - -Lawrence R. Dodd -@c - -@node GNU Free Documentation License, Concept Index, Bugs, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, Command Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Concept Index -@printindex cp - -@node Command Index, Key Index, Concept Index, Top -@comment node-name, next, previous, up -@unnumbered Function Index -@printindex fn - -@node Key Index, Variable Index, Command Index, Top -@comment node-name, next, previous, up -@unnumbered Key Index -@printindex ky - -@node Variable Index, , Key Index, Top -@comment node-name, next, previous, up -@unnumbered Variable Index -@printindex vr - -@bye - -@ignore - arch-tag: 201727aa-9318-4c74-a0d7-4f51c550c4de -@end ignore diff --git a/doc/misc/doclicense.texi b/doc/misc/doclicense.texi deleted file mode 100644 index d3ae2f92b20..00000000000 --- a/doc/misc/doclicense.texi +++ /dev/null @@ -1,511 +0,0 @@ -@c -*-texinfo-*- -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{free} in the sense of freedom: to -assure everyone the effective freedom to copy and redistribute it, -with or without modifying it, either commercially or noncommercially. -Secondarily, this License preserves for the author and publisher a way -to get credit for their work, while not being considered responsible -for modifications made by others. - -This License is a kind of ``copyleft'', which means that derivative -works of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft -license designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free -program should come with manuals providing the same freedoms that the -software does. But this License is not limited to software manuals; -it can be used for any textual work, regardless of subject matter or -whether it is published as a printed book. We recommend this License -principally for works whose purpose is instruction or reference. - -@item -APPLICABILITY AND DEFINITIONS - -This License applies to any manual or other work, in any medium, that -contains a notice placed by the copyright holder saying it can be -distributed under the terms of this License. Such a notice grants a -world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, -refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you -copy, modify or distribute the work in a way requiring permission -under copyright law. - -A ``Modified Version'' of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - -A ``Secondary Section'' is a named appendix or a front-matter section -of the Document that deals exclusively with the relationship of the -publishers or authors of the Document to the Document's overall -subject (or to related matters) and contains nothing that could fall -directly within that overall subject. (Thus, if the Document is in -part a textbook of mathematics, a Secondary Section may not explain -any mathematics.) The relationship could be a matter of historical -connection with the subject or with related matters, or of legal, -commercial, philosophical, ethical or political position regarding -them. - -The ``Invariant Sections'' are certain Secondary Sections whose titles -are designated, as being those of Invariant Sections, in the notice -that says that the Document is released under this License. If a -section does not fit the above definition of Secondary then it is not -allowed to be designated as Invariant. The Document may contain zero -Invariant Sections. If the Document does not identify any Invariant -Sections then there are none. - -The ``Cover Texts'' are certain short passages of text that are listed, -as Front-Cover Texts or Back-Cover Texts, in the notice that says that -the Document is released under this License. A Front-Cover Text may -be at most 5 words, and a Back-Cover Text may be at most 25 words. - -A ``Transparent'' copy of the Document means a machine-readable copy, -represented in a format whose specification is available to the -general public, that is suitable for revising the document -straightforwardly with generic text editors or (for images composed of -pixels) generic paint programs or (for drawings) some widely available -drawing editor, and that is suitable for input to text formatters or -for automatic translation to a variety of formats suitable for input -to text formatters. A copy made in an otherwise Transparent file -format whose markup, or absence of markup, has been arranged to thwart -or discourage subsequent modification by readers is not Transparent. -An image format is not Transparent if used for any substantial amount -of text. A copy that is not ``Transparent'' is called ``Opaque''. - -Examples of suitable formats for Transparent copies include plain -@sc{ascii} without markup, Texinfo input format, La@TeX{} input -format, @acronym{SGML} or @acronym{XML} using a publicly available -@acronym{DTD}, and standard-conforming simple @acronym{HTML}, -PostScript or @acronym{PDF} designed for human modification. Examples -of transparent image formats include @acronym{PNG}, @acronym{XCF} and -@acronym{JPG}. Opaque formats include proprietary formats that can be -read and edited only by proprietary word processors, @acronym{SGML} or -@acronym{XML} for which the @acronym{DTD} and/or processing tools are -not generally available, and the machine-generated @acronym{HTML}, -PostScript or @acronym{PDF} produced by some word processors for -output purposes only. - -The ``Title Page'' means, for a printed book, the title page itself, -plus such following pages as are needed to hold, legibly, the material -this License requires to appear in the title page. For works in -formats which do not have any title page as such, ``Title Page'' means -the text near the most prominent appearance of the work's title, -preceding the beginning of the body of the text. - -The ``publisher'' means any person or entity that distributes copies -of the Document to the public. - -A section ``Entitled XYZ'' means a named subunit of the Document whose -title either is precisely XYZ or contains XYZ in parentheses following -text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' -of such a section when you modify the Document means that it remains a -section ``Entitled XYZ'' according to this definition. - -The Document may include Warranty Disclaimers next to the notice which -states that this License applies to the Document. These Warranty -Disclaimers are considered to be included by reference in this -License, but only as regards disclaiming warranties: any other -implication that these Warranty Disclaimers may have is void and has -no effect on the meaning of this License. - -@item -VERBATIM COPYING - -You may copy and distribute the Document in any medium, either -commercially or noncommercially, provided that this License, the -copyright notices, and the license notice saying this License applies -to the Document are reproduced in all copies, and that you add no other -conditions whatsoever to those of this License. You may not use -technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in section 3. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - -@item -COPYING IN QUANTITY - -If you publish printed copies (or copies in media that commonly have -printed covers) of the Document, numbering more than 100, and the -Document's license notice requires Cover Texts, you must enclose the -copies in covers that carry, clearly and legibly, all these Cover -Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on -the back cover. Both covers must also clearly and legibly identify -you as the publisher of these copies. The front cover must present -the full title with all words of the title equally prominent and -visible. You may add other material on the covers in addition. -Copying with changes limited to the covers, as long as they preserve -the title of the Document and satisfy these conditions, can be treated -as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute Opaque copies of the Document numbering -more than 100, you must either include a machine-readable Transparent -copy along with each Opaque copy, or state in or with each Opaque copy -a computer-network location from which the general network-using -public has access to download using public-standard network protocols -a complete Transparent copy of the Document, free of added material. -If you use the latter option, you must take reasonably prudent steps, -when you begin distribution of Opaque copies in quantity, to ensure -that this Transparent copy will remain thus accessible at the stated -location until at least one year after the last time you distribute an -Opaque copy (directly or through your agents or retailers) of that -edition to the public. - -It is requested, but not required, that you contact the authors of the -Document well before redistributing any large number of copies, to give -them a chance to provide you with an updated version of the Document. - -@item -MODIFICATIONS - -You may copy and distribute a Modified Version of the Document under -the conditions of sections 2 and 3 above, provided that you release -the Modified Version under precisely this License, with the Modified -Version filling the role of the Document, thus licensing distribution -and modification of the Modified Version to whoever possesses a copy -of it. In addition, you must do these things in the Modified Version: - -@enumerate A -@item -Use in the Title Page (and on the covers, if any) a title distinct -from that of the Document, and from those of previous versions -(which should, if there were any, be listed in the History section -of the Document). You may use the same title as a previous version -if the original publisher of that version gives permission. - -@item -List on the Title Page, as authors, one or more persons or entities -responsible for authorship of the modifications in the Modified -Version, together with at least five of the principal authors of the -Document (all of its principal authors, if it has fewer than five), -unless they release you from this requirement. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -Include, immediately after the copyright notices, a license notice -giving the public permission to use the Modified Version under the -terms of this License, in the form shown in the Addendum below. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -Preserve the section Entitled ``History'', Preserve its Title, and add -to it an item stating at least the title, year, new authors, and -publisher of the Modified Version as given on the Title Page. If -there is no section Entitled ``History'' in the Document, create one -stating the title, year, authors, and publisher of the Document as -given on its Title Page, then add an item describing the Modified -Version as stated in the previous sentence. - -@item -Preserve the network location, if any, given in the Document for -public access to a Transparent copy of the Document, and likewise -the network locations given in the Document for previous versions -it was based on. These may be placed in the ``History'' section. -You may omit a network location for a work that was published at -least four years before the Document itself, or if the original -publisher of the version it refers to gives permission. - -@item -For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve -the Title of the section, and preserve in the section all the -substance and tone of each of the contributor acknowledgements and/or -dedications given therein. - -@item -Preserve all the Invariant Sections of the Document, -unaltered in their text and in their titles. Section numbers -or the equivalent are not considered part of the section titles. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -If the Modified Version includes new front-matter sections or -appendices that qualify as Secondary Sections and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the -list of Invariant Sections in the Modified Version's license notice. -These titles must be distinct from any other section titles. - -You may add a section Entitled ``Endorsements'', provided it contains -nothing but endorsements of your Modified Version by various -parties---for example, statements of peer review or that the text has -been approved by an organization as the authoritative definition of a -standard. - -You may add a passage of up to five words as a Front-Cover Text, and a -passage of up to 25 words as a Back-Cover Text, to the end of the list -of Cover Texts in the Modified Version. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or -through arrangements made by) any one entity. If the Document already -includes a cover text for the same cover, previously added by you or -by arrangement made by the same entity you are acting on behalf of, -you may not add another; but you may replace the old one, on explicit -permission from the previous publisher that added the old one. - -The author(s) and publisher(s) of the Document do not by this License -give permission to use their names for publicity for or to assert or -imply endorsement of any Modified Version. - -@item -COMBINING DOCUMENTS - -You may combine the Document with other documents released under this -License, under the terms defined in section 4 above for modified -versions, provided that you include in the combination all of the -Invariant Sections of all of the original documents, unmodified, and -list them all as Invariant Sections of your combined work in its -license notice, and that you preserve all their Warranty Disclaimers. - -The combined work need only contain one copy of this License, and -multiple identical Invariant Sections may be replaced with a single -copy. If there are multiple Invariant Sections with the same name but -different contents, make the title of each such section unique by -adding at the end of it, in parentheses, the name of the original -author or publisher of that section if known, or else a unique number. -Make the same adjustment to the section titles in the list of -Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections Entitled ``History'' -in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', -and any sections Entitled ``Dedications''. You must delete all -sections Entitled ``Endorsements.'' - -@item -COLLECTIONS OF DOCUMENTS - -You may make a collection consisting of the Document and other documents -released under this License, and replace the individual copies of this -License in the various documents with a single copy that is included in -the collection, provided that you follow the rules of this License for -verbatim copying of each of the documents in all other respects. - -You may extract a single document from such a collection, and distribute -it individually under this License, provided you insert a copy of this -License into the extracted document, and follow this License in all -other respects regarding verbatim copying of that document. - -@item -AGGREGATION WITH INDEPENDENT WORKS - -A compilation of the Document or its derivatives with other separate -and independent documents or works, in or on a volume of a storage or -distribution medium, is called an ``aggregate'' if the copyright -resulting from the compilation is not used to limit the legal rights -of the compilation's users beyond what the individual works permit. -When the Document is included in an aggregate, this License does not -apply to the other works in the aggregate which are not themselves -derivative works of the Document. - -If the Cover Text requirement of section 3 is applicable to these -copies of the Document, then if the Document is less than one half of -the entire aggregate, the Document's Cover Texts may be placed on -covers that bracket the Document within the aggregate, or the -electronic equivalent of covers if the Document is in electronic form. -Otherwise they must appear on printed covers that bracket the whole -aggregate. - -@item -TRANSLATION - -Translation is considered a kind of modification, so you may -distribute translations of the Document under the terms of section 4. -Replacing Invariant Sections with translations requires special -permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License, and all the license notices in the -Document, and any Warranty Disclaimers, provided that you also include -the original English version of this License and the original versions -of those notices and disclaimers. In case of a disagreement between -the translation and the original version of this License or a notice -or disclaimer, the original version will prevail. - -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve -its Title (section 1) will typically require changing the actual -title. - -@item -TERMINATION - -You may not copy, modify, sublicense, or distribute the Document -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense, or distribute it is void, and -will automatically terminate your rights under this License. - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, receipt of a copy of some or all of the same material does -not give you any rights to use it. - -@item -FUTURE REVISIONS OF THIS LICENSE - -The Free Software Foundation may publish new, revised versions -of the GNU Free Documentation License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. See -@uref{http://www.gnu.org/copyleft/}. - -Each version of the License is given a distinguishing version number. -If the Document specifies that a particular numbered version of this -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that specified version or -of any later version that has been published (not as a draft) by the -Free Software Foundation. If the Document does not specify a version -number of this License, you may choose any version ever published (not -as a draft) by the Free Software Foundation. If the Document -specifies that a proxy can decide which future versions of this -License can be used, that proxy's public statement of acceptance of a -version permanently authorizes you to choose that version for the -Document. - -@item -RELICENSING - -``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any -World Wide Web server that publishes copyrightable works and also -provides prominent facilities for anybody to edit those works. A -public wiki that anybody can edit is an example of such a server. A -``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the -site means any set of copyrightable works thus published on the MMC -site. - -``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 -license published by Creative Commons Corporation, a not-for-profit -corporation with a principal place of business in San Francisco, -California, as well as future copyleft versions of that license -published by that same organization. - -``Incorporate'' means to publish or republish a Document, in whole or -in part, as part of another Document. - -An MMC is ``eligible for relicensing'' if it is licensed under this -License, and if all works that were first published under this License -somewhere other than this MMC, and subsequently incorporated in whole -or in part into the MMC, (1) had no cover texts or invariant sections, -and (2) were thus incorporated prior to November 1, 2008. - -The operator of an MMC Site may republish an MMC contained in the site -under CC-BY-SA on the same site at any time before August 1, 2009, -provided the MMC is eligible for relicensing. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover - Texts. A copy of the license is included in the section entitled ``GNU - Free Documentation License''. -@end group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - -@ignore - arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165 -@end ignore diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi deleted file mode 100644 index 9642c3c1dd6..00000000000 --- a/doc/misc/ebrowse.texi +++ /dev/null @@ -1,1459 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@comment %**start of header -@setfilename ../../info/ebrowse -@settitle A Class Browser for C++ -@setchapternewpage odd -@syncodeindex fn cp -@comment %**end of header - -@copying -This file documents Ebrowse, a C++ class browser for GNU Emacs. - -Copyright @copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Ebrowse: (ebrowse). A C++ class browser for Emacs. -@end direntry - -@titlepage -@title Ebrowse User's Manual -@sp 4 -@subtitle Ebrowse/Emacs -@sp 5 -@author Gerd Moellmann -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) - -You can browse C++ class hierarchies from within Emacs by using -Ebrowse. - -@insertcopying -@end ifnottex - -@menu -* Overview:: What is it and how does it work? -* Generating browser files:: How to process C++ source files -* Loading a Tree:: How to start browsing -* Tree Buffers:: Traversing class hierarchies -* Member Buffers:: Looking at member information -* Tags-like Functions:: Finding members from source files -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: An entry for each concept defined -@end menu - - - - -@node Overview, Generating browser files, Top, Top -@chapter Introduction - -When working in software projects using C++, I frequently missed -software support for two things: - -@itemize @bullet -@item -When you get a new class library, or you have to work on source code you -haven't written yourself (or written sufficiently long ago), you need a -tool to let you navigate class hierarchies and investigate -features of the software. Without such a tool you often end up -@command{grep}ing through dozens or even hundreds of files. - -@item -Once you are productive, it would be nice to have a tool that knows your -sources and can help you while you are editing source code. Imagine to -be able to jump to the definition of an identifier while you are -editing, or something that can complete long identifier names because it -knows what identifiers are defined in your program@dots{}. -@end itemize - -The design of Ebrowse reflects these two needs. - -How does it work? - -@cindex parser for C++ sources -A fast parser written in C is used to process C++ source files. -The parser generates a data base containing information about classes, -members, global functions, defines, types etc.@: found in the sources. - -The second part of Ebrowse is a Lisp program. This program reads -the data base generated by the parser. It displays its contents in -various forms and allows you to perform operations on it, or do -something with the help of the knowledge contained in the data base. - -@cindex major modes, of Ebrowse buffers -@dfn{Navigational} use of Ebrowse is centered around two -types of buffers which define their own major modes: - -@cindex tree buffer -@dfn{Tree buffers} are used to view class hierarchies in tree form. -They allow you to quickly find classes, find or view class declarations, -perform operations like query replace on sets of your source files, and -finally tree buffers are used to produce the second buffer form---member -buffers. @xref{Tree Buffers}. - -@cindex member buffer -Members are displayed in @dfn{member buffers}. Ebrowse -distinguishes between six different types of members; each type is -displayed as a member list of its own: - -@itemize @bullet -@item -Instance member variables; - -@item -Instance member functions; - -@item -Static member variables; - -@item -Static member functions; - -@item -Friends/Defines. The list of defines is contained in the friends -list of the pseudo-class @samp{*Globals*}; - -@item -Types (@code{enum}s, and @code{typedef}s defined with class -scope).@refill -@end itemize - -You can switch member buffers from one list to another, or to another -class. You can include inherited members in the display, you can set -filters that remove categories of members from the display, and most -importantly you can find or view member declarations and definitions -with a keystroke. @xref{Member Buffers}. - -These two buffer types and the commands they provide support the -navigational use of the browser. The second form resembles Emacs' Tags -package for C and other procedural languages. Ebrowse's commands of -this type are not confined to special buffers; they are most often used -while you are editing your source code. - -To list just a subset of what you can use the Tags part of Ebrowse for: - -@itemize @bullet -@item -Jump to the definition or declaration of an identifier in your source -code, with an electric position stack that lets you easily navigate -back and forth. - -@item -Complete identifiers in your source with a completion list containing -identifiers from your source code only. - -@item -Perform search and query replace operations over some or all of your -source files. - -@item -Show all identifiers matching a regular expression---and jump to one of -them, if you like. -@end itemize - - - - -@node Generating browser files, Loading a Tree, Overview, Top -@comment node-name, next, previous, up -@chapter Processing Source Files - -@cindex @command{ebrowse}, the program -@cindex class data base creation -Before you can start browsing a class hierarchy, you must run the parser -@command{ebrowse} on your source files in order to generate a Lisp data -base describing your program. - -@cindex command line for @command{ebrowse} -The operation of @command{ebrowse} can be tailored with command line -options. Under normal circumstances it suffices to let the parser use -its default settings. If you want to do that, call it with a command -line like: - -@example -ebrowse *.h *.cc -@end example - -@noindent -or, if your shell doesn't allow all the file names to be specified on -the command line, - -@example -ebrowse --files=@var{file} -@end example - -@noindent -where @var{file} contains the names of the files to be parsed, one -per line. - -@findex --help -When invoked with option @samp{--help}, @command{ebrowse} prints a list of -available command line options.@refill - -@menu -* Input files:: Specifying which files to parse -* Output file:: Changing the output file name -* Structs and unions:: Omitting @code{struct}s and @code{union}s -* Matching:: Setting regular expression lengths -* Verbosity:: Getting feedback for lengthy operations -@end menu - - - - -@comment name, next, prev, up -@node Input files, Output file, Generating browser files, Generating browser files -@section Specifying Input Files - -@table @samp -@cindex input files, for @command{ebrowse} -@item file -Each file name on the command line tells @command{ebrowse} to parse -that file. - -@cindex response files -@findex --files -@item --files=@var{file} -This command line switch specifies that @var{file} contains a list of -file names to parse. Each line in @var{file} must contain one file -name. More than one option of this kind is allowed. You might, for -instance, want to use one file for header files, and another for source -files. - -@cindex standard input, specifying input files -@item standard input -When @command{ebrowse} finds no file names on the command line, and no -@samp{--file} option is specified, it reads file names from standard -input. This is sometimes convenient when @command{ebrowse} is used as part -of a command pipe. - -@findex --search-path -@item --search-path=@var{paths} -This option lets you specify search paths for your input files. -@var{paths} is a list of directory names, separated from each other by a -either a colon or a semicolon, depending on the operating system. -@end table - -@cindex header files -@cindex friend functions -It is generally a good idea to specify input files so that header files -are parsed before source files. This facilitates the parser's work of -properly identifying friend functions of a class. - - - -@comment name, next, prev, up -@node Output file, Structs and unions, Input files, Generating browser files -@section Changing the Output File Name - -@table @samp -@cindex output file name -@findex --output-file -@cindex @file{BROWSE} file -@item --output-file=@var{file} -This option instructs @command{ebrowse} to generate a Lisp data base with -name @var{file}. By default, the data base is named @file{BROWSE}, and -is written in the directory in which @command{ebrowse} is invoked. - -If you regularly use data base names different from the default, you -might want to add this to your init file: - -@lisp -(add-to-list 'auto-mode-alist '(@var{NAME} . ebrowse-tree-mode)) -@end lisp - -@noindent -where @var{NAME} is the Lisp data base name you are using. - -@findex --append -@cindex appending output to class data base -@item --append -By default, each run of @command{ebrowse} erases the old contents of the -output file when writing to it. You can instruct @command{ebrowse} to -append its output to an existing file produced by @command{ebrowse} -with this command line option. -@end table - - - - -@comment name, next, prev, up -@node Structs and unions, Matching, Output file, Generating browser files -@section Structs and Unions -@cindex structs -@cindex unions - -@table @samp -@findex --no-structs-or-unions -@item --no-structs-or-unions -This switch suppresses all classes in the data base declared as -@code{struct} or @code{union} in the output. - -This is mainly useful when you are converting an existing -C program to C++, and do not want to see the old C structs in a class -tree. -@end table - - - - -@comment name, next, prev, up -@node Matching, Verbosity, Structs and unions, Generating browser files -@section Regular Expressions - -@cindex regular expressions, recording -The parser @command{ebrowse} normally writes regular expressions to its -output file that help the Lisp part of Ebrowse to find functions, -variables etc.@: in their source files. - -You can instruct @command{ebrowse} to omit these regular expressions by -calling it with the command line switch @samp{--no-regexps}. - -When you do this, the Lisp part of Ebrowse tries to guess, from member -or class names, suitable regular expressions to locate that class or -member in source files. This works fine in most cases, but the -automatic generation of regular expressions can be too weak if unusual -coding styles are used. - -@table @samp -@findex --no-regexps -@item --no-regexps -This option turns off regular expression recording. - -@findex --min-regexp-length -@cindex minimum regexp length for recording -@item --min-regexp-length=@var{n} -The number @var{n} following this option specifies the minimum length of -the regular expressions recorded to match class and member declarations -and definitions. The default value is set at compilation time of -@command{ebrowse}. - -The smaller the minimum length, the higher the probability that -Ebrowse will find a wrong match. The larger the value, the -larger the output file and therefore the memory consumption once the -file is read from Emacs. - -@findex --max-regexp-length -@cindex maximum regexp length for recording -@item --max-regexp-length=@var{n} -The number following this option specifies the maximum length of the -regular expressions used to match class and member declarations and -definitions. The default value is set at compilation time of -@command{ebrowse}. - -The larger the maximum length, the higher the probability that the -browser will find a correct match, but the larger the value the larger -the output file and therefore the memory consumption once the data is -read. As a second effect, the larger the regular expression, the higher -the probability that it will no longer match after editing the file. -@end table - - - - -@node Verbosity, , Matching, Generating browser files -@comment node-name, next, previous, up -@section Verbose Mode -@cindex verbose operation - -@table @samp -@findex --verbose -@item --verbose -When this option is specified on the command line, @command{ebrowse} prints -a period for each file parsed, and it displays a @samp{+} for each -class written to the output file. - -@findex --very-verbose -@item --very-verbose -This option makes @command{ebrowse} print out the names of the files and -the names of the classes seen. -@end table - - - - -@node Loading a Tree, Tree Buffers, Generating browser files, Top -@comment node-name, next, previous, up -@chapter Starting to Browse -@cindex loading -@cindex browsing - -You start browsing a class hierarchy parsed by @command{ebrowse} by just -finding the @file{BROWSE} file with @kbd{C-x C-f}. - -An example of a tree buffer display is shown below. - -@example -| Collection -| IndexedCollection -| Array -| FixedArray -| Set -| Dictionary -@end example - -@cindex mouse highlight in tree buffers -When you run Emacs on a display which supports colors and the mouse, you -will notice that certain areas in the tree buffer are highlighted -when you move the mouse over them. This highlight marks mouse-sensitive -regions in the buffer. Please notice the help strings in the echo area -when the mouse moves over a sensitive region. - -@cindex context menu -A click with @kbd{Mouse-3} on a mouse-sensitive region opens a context -menu. In addition to this, each buffer also has a buffer-specific menu -that is opened with a click with @kbd{Mouse-3} somewhere in the buffer -where no highlight is displayed. - - - -@comment **************************************************************** -@comment *** -@comment *** TREE BUFFERS -@comment *** -@comment **************************************************************** - -@node Tree Buffers, Member Buffers, Loading a Tree, Top -@comment node-name, next, previous, up -@chapter Tree Buffers -@cindex tree buffer mode -@cindex class trees - -Class trees are displayed in @dfn{tree buffers} which install their own -major mode. Most Emacs keys work in tree buffers in the usual way, -e.g.@: you can move around in the buffer with the usual @kbd{C-f}, -@kbd{C-v} etc., or you can search with @kbd{C-s}. - -Tree-specific commands are bound to simple keystrokes, similar to -@code{Gnus}. You can take a look at the key bindings by entering -@kbd{?} which calls @code{M-x describe-mode} in both tree and member -buffers. - -@menu -* Source Display:: Viewing and finding a class declaration -* Member Display:: Showing members, switching to member buffers -* Go to Class:: Finding a class -* Quitting:: Discarding and burying the tree buffer -* File Name Display:: Showing file names in the tree -* Expanding and Collapsing:: Expanding and collapsing branches -* Tree Indentation:: Changing the tree indentation -* Killing Classes:: Removing class from the tree -* Saving a Tree:: Saving a modified tree -* Statistics:: Displaying class tree statistics -* Marking Classes:: Marking and unmarking classes -@end menu - - - -@node Source Display, Member Display, Tree Buffers, Tree Buffers -@comment node-name, next, previous, up -@section Viewing and Finding Class Declarations -@cindex viewing, class -@cindex finding a class -@cindex class declaration - -You can view or find a class declaration when the cursor is on a class -name. - -@table @kbd -@item SPC -This command views the class declaration if the database -contains informations about it. If you don't parse the entire source -you are working on, some classes will only be known to exist but the -location of their declarations and definitions will not be known.@refill - -@item RET -Works like @kbd{SPC}, except that it finds the class -declaration rather than viewing it, so that it is ready for -editing.@refill -@end table - -The same functionality is available from the menu opened with -@kbd{Mouse-3} on the class name. - - - - -@node Member Display, Go to Class, Source Display, Tree Buffers -@comment node-name, next, previous, up -@section Displaying Members -@cindex @samp{*Members*} buffer -@cindex @samp{*Globals*} -@cindex freezing a member buffer -@cindex member lists, in tree buffers - -Ebrowse distinguishes six different kinds of members, each of -which is displayed as a separate @dfn{member list}: instance variables, -instance functions, static variables, static functions, friend -functions, and types. - -Each of these lists can be displayed in a member buffer with a command -starting with @kbd{L} when the cursor is on a class name. By default, -there is only one member buffer named @dfn{*Members*} that is reused -each time you display a member list---this has proven to be more -practical than to clutter up the buffer list with dozens of member -buffers. - -If you want to display more than one member list at a time you can -@dfn{freeze} its member buffer. Freezing a member buffer prevents it -from being overwritten the next time you display a member list. You can -toggle this buffer status at any time. - -Every member list display command in the tree buffer can be used with a -prefix argument (@kbd{C-u}). Without a prefix argument, the command will -pop to a member buffer displaying the member list. With prefix argument, -the member buffer will additionally be @dfn{frozen}. - -@table @kbd -@cindex instance member variables, list -@item L v -This command displays the list of instance member variables. - -@cindex static variables, list -@item L V -Display the list of static variables. - -@cindex friend functions, list -@item L d -Display the list of friend functions. This list is used for defines if -you are viewing the class @samp{*Globals*} which is a place holder for -global symbols. - -@cindex member functions, list -@item L f -Display the list of member functions. - -@cindex static member functions, list -@item L F -Display the list of static member functions. - -@cindex types, list -@item L t -Display a list of types. -@end table - -These lists are also available from the class' context menu invoked with -@kbd{Mouse-3} on the class name. - - - - -@node Go to Class, Quitting, Member Display, Tree Buffers -@comment node-name, next, previous, up -@section Finding a Class -@cindex locate class -@cindex expanding branches -@cindex class location - -@table @kbd -@cindex search for class -@item / -This command reads a class name from the minibuffer with completion and -positions the cursor on the class in the class tree. - -If the branch of the class tree containing the class searched for is -currently collapsed, the class itself and all its base classes are -recursively made visible. (See also @ref{Expanding and -Collapsing}.)@refill - -This function is also available from the tree buffer's context menu. - -@item n -Repeat the last search done with @kbd{/}. Each tree buffer has its own -local copy of the regular expression last searched in it. -@end table - - - - -@node Quitting, File Name Display, Go to Class, Tree Buffers -@comment node-name, next, previous, up -@section Burying a Tree Buffer -@cindex burying tree buffer - -@table @kbd -@item q -Is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node File Name Display, Expanding and Collapsing, Quitting, Tree Buffers -@comment node-name, next, previous, up -@section Displaying File Names - -@table @kbd -@cindex file names in tree buffers -@item T f -This command toggles the display of file names in a tree buffer. If -file name display is switched on, the names of the files containing the -class declaration are shown to the right of the class names. If the -file is not known, the string @samp{unknown} is displayed. - -This command is also provided in the tree buffer's context menu. - -@item s -Display file names for the current line, or for the number of lines -given by a prefix argument. -@end table - -Here is an example of a tree buffer with file names displayed. - -@example -| Collection (unknown) -| IndexedCollection (indexedcltn.h) -| Array (array.h) -| FixedArray (fixedarray.h) -| Set (set.h) -| Dictionary (dict.h) -@end example - - - - -@node Expanding and Collapsing, Tree Indentation, File Name Display, Tree Buffers -@comment node-name, next, previous, up -@section Expanding and Collapsing a Tree -@cindex expand tree branch -@cindex collapse tree branch -@cindex branches of class tree -@cindex class tree, collapse or expand - -You can expand and collapse parts of a tree to reduce the complexity of -large class hierarchies. Expanding or collapsing branches of a tree has -no impact on the functionality of other commands, like @kbd{/}. (See -also @ref{Go to Class}.)@refill - -Collapsed branches are indicated with an ellipsis following the class -name like in the example below. - -@example -| Collection -| IndexedCollection... -| Set -| Dictionary -@end example - -@table @kbd -@item - -This command collapses the branch of the tree starting at the class the -cursor is on. - -@item + -This command expands the branch of the tree starting at the class the -cursor is on. Both commands for collapsing and expanding branches are -also available from the class' object menu. - -@item * -This command expands all collapsed branches in the tree. -@end table - - - - -@node Tree Indentation, Killing Classes, Expanding and Collapsing, Tree Buffers -@comment node-name, next, previous, up -@section Changing the Tree Indentation -@cindex tree indentation -@cindex indentation of the tree - -@table @kbd -@item T w -This command reads a new indentation width from the minibuffer and -redisplays the tree buffer with the new indentation It is also -available from the tree buffer's context menu. -@end table - - - - -@node Killing Classes, Saving a Tree, Tree Indentation, Tree Buffers -@comment node-name, next, previous, up -@section Removing Classes from the Tree -@cindex killing classes -@cindex class, remove from tree - -@table @kbd -@item C-k -This command removes the class the cursor is on and all its derived -classes from the tree. The user is asked for confirmation before the -deletion is actually performed. -@end table - - - - -@node Saving a Tree, Statistics, Killing Classes, Tree Buffers -@comment node-name, next, previous, up -@comment node-name, next, previous, up -@section Saving a Tree -@cindex save tree to a file -@cindex tree, save to a file -@cindex class tree, save to a file - -@table @kbd -@item C-x C-s -This command writes a class tree to the file from which it was read. -This is useful after classes have been deleted from a tree. - -@item C-x C-w -Writes the tree to a file whose name is read from the minibuffer. -@end table - - - - -@node Statistics, Marking Classes, Saving a Tree, Tree Buffers -@comment node-name, next, previous, up -@cindex statistics for a tree -@cindex tree statistics -@cindex class statistics - -@table @kbd -@item x -Display statistics for the tree, like number of classes in it, number of -member functions, etc. This command can also be found in the buffer's -context menu. -@end table - - - - -@node Marking Classes, , Statistics, Tree Buffers -@comment node-name, next, previous, up -@cindex marking classes -@cindex operations on marked classes - -Classes can be marked for operations similar to the standard Emacs -commands @kbd{M-x tags-search} and @kbd{M-x tags-query-replace} (see -also @xref{Tags-like Functions}.)@refill - -@table @kbd -@cindex toggle mark -@item M t -Toggle the mark of the line point is in or for as many lines as given by -a prefix command. This command can also be found in the class' context -menu. - -@cindex unmark all -@item M a -Unmark all classes. With prefix argument @kbd{C-u}, mark all classes in -the tree. Since this command operates on the whole buffer, it can also be -found in the buffer's object menu. -@end table - -Marked classes are displayed with an @code{>} in column one of the tree -display, like in the following example - -@example -|> Collection -| IndexedCollection... -|> Set -| Dictionary -@end example - - - - -@c **************************************************************** -@c *** -@c *** MEMBER BUFFERS -@c *** -@c **************************************************************** - -@node Member Buffers, Tags-like Functions, Tree Buffers, Top -@comment node-name, next, previous, up -@chapter Member Buffers -@cindex members -@cindex member buffer mode - -@cindex class members, types -@cindex types of class members -@dfn{Member buffers} are used to operate on lists of members of a class. -Ebrowse distinguishes six kinds of lists: - -@itemize @bullet -@item -Instance variables (normal member variables); -@item -Instance functions (normal member functions); -@item -Static variables; -@item -Static member functions; -@item -Friend functions; -@item -Types (@code{enum}s and @code{typedef}s defined with class scope. -Nested classes will be shown in the class tree like normal classes. -@end itemize - -Like tree buffers, member buffers install their own major mode. Also -like in tree buffers, menus are provided for certain areas in the -buffer: members, classes, and the buffer itself. - -@menu -* Switching Member Lists:: Choosing which members to display -* Finding/Viewing:: Modifying source code -* Inherited Members:: Display of Inherited Members -* Searching Members:: Finding members in member buffer -* Switching to Tree:: Going back to the tree buffer -* Filters:: Selective member display -* Attributes:: Display of @code{virtual} etc. -* Long and Short Display:: Comprehensive and verbose display -* Regexp Display:: Showing matching regular expressions -* Switching Classes:: Displaying another class -* Killing/Burying:: Getting rid of the member buffer -* Column Width:: Display style -* Redisplay:: Redrawing the member list -* Getting Help:: How to get help for key bindings -@end menu - - - - -@node Switching Member Lists, Finding/Viewing, Member Buffers, Member Buffers -@comment node-name, next, previous, up -@section Switching Member Lists -@cindex member lists, in member buffers -@cindex static members -@cindex friends -@cindex types -@cindex defines - -@table @kbd -@cindex next member list -@item L n -This command switches the member buffer display to the next member list. - -@cindex previous member list -@item L p -This command switches the member buffer display to the previous member -list. - -@item L f -Switch to the list of member functions. - -@cindex static -@item L F -Switch to the list of static member functions. - -@item L v -Switch to the list of member variables. - -@item L V -Switch to the list of static member variables. - -@item L d -Switch to the list of friends or defines. - -@item L t -Switch to the list of types. -@end table - -Both commands cycle through the member list. - -Most of the commands are also available from the member buffer's -context menu. - - - - -@node Finding/Viewing, Inherited Members, Switching Member Lists, Member Buffers -@comment node-name, next, previous, up -@section Finding and Viewing Member Source -@cindex finding members, in member buffers -@cindex viewing members, in member buffers -@cindex member definitions, in member buffers -@cindex member declarations, in member buffers -@cindex definition of a member, in member buffers -@cindex declaration of a member, in member buffers - -@table @kbd -@item RET -This command finds the definition of the member the cursor is on. -Finding involves roughly the same as the standard Emacs tags facility -does---loading the file and searching for a regular expression matching -the member. - -@item f -This command finds the declaration of the member the cursor is on. - -@item SPC -This is the same command as @kbd{RET}, but views the member definition -instead of finding the member's source file. - -@item v -This is the same command as @kbd{f}, but views the member's declaration -instead of finding the file the declaration is in. -@end table - -You can install a hook function to perform actions after a member or -class declaration or definition has been found, or when it is not found. - -All the commands described above can also be found in the context menu -displayed when clicking @kbd{Mouse-2} on a member name. - - - - -@node Inherited Members, Searching Members, Finding/Viewing, Member Buffers -@comment node-name, next, previous, up -@section Display of Inherited Members -@cindex superclasses, members -@cindex base classes, members -@cindex inherited members - -@table @kbd -@item D b -This command toggles the display of inherited members in the member -buffer. This is also in the buffer's context menu. -@end table - - - - -@node Searching Members, Switching to Tree, Inherited Members, Member Buffers -@comment node-name, next, previous, up -@section Searching Members -@cindex searching members - -@table @kbd -@item G v -Position the cursor on a member whose name is read from the minibuffer; -only members shown in the current member buffer appear in the completion -list. - -@item G m -Like the above command, but all members for the current class appear in -the completion list. If necessary, the current member list is switched -to the one containing the member. - -With a prefix argument (@kbd{C-u}), all members in the class tree, -i.e.@: all members the browser knows about appear in the completion -list. The member display will be switched to the class and member list -containing the member. - -@item G n -Repeat the last member search. -@end table - -Look into the buffer's context menu for a convenient way to do this with -a mouse. - - - -@node Switching to Tree, Filters, Searching Members, Member Buffers -@comment node-name, next, previous, up -@section Switching to Tree Buffer -@cindex tree buffer, switch to -@cindex buffer switching -@cindex switching buffers - -@table @kbd -@item @key{TAB} -Pop up the tree buffer to which the member buffer belongs. - -@item t -Do the same as @key{TAB} but also position the cursor on the class -displayed in the member buffer. -@end table - - - - -@node Filters, Attributes, Switching to Tree, Member Buffers -@comment node-name, next, previous, up -@section Filters -@cindex filters - -@table @kbd -@cindex @code{public} members -@item F a u -This command toggles the display of @code{public} members. The -@samp{a} stands for `access'. - -@cindex @code{protected} members -@item F a o -This command toggles the display of @code{protected} members. - -@cindex @code{private} members -@item F a i -This command toggles the display of @code{private} members. - -@cindex @code{virtual} members -@item F v -This command toggles the display of @code{virtual} members. - -@cindex @code{inline} members -@item F i -This command toggles the display of @code{inline} members. - -@cindex @code{const} members -@item F c -This command toggles the display of @code{const} members. - -@cindex pure virtual members -@item F p -This command toggles the display of pure virtual members. - -@cindex remove filters -@item F r -This command removes all filters. -@end table - -These commands are also found in the buffer's context menu. - - - - -@node Attributes, Long and Short Display, Filters, Member Buffers -@comment node-name, next, previous, up -@section Displaying Member Attributes -@cindex attributes -@cindex member attribute display - -@table @kbd -@item D a -Toggle the display of member attributes (default is on). - -The nine member attributes Ebrowse knows about are displayed -as a list a single-characters flags enclosed in angle brackets in front -the of the member's name. A @samp{-} at a given position means that -the attribute is false. The list of attributes from left to right is - -@table @samp -@cindex @code{template} attribute -@item T -The member is a template. - -@cindex @code{extern "C"} attribute -@item C -The member is declared @code{extern "C"}. - -@cindex @code{virtual} attribute -@item v -Means the member is declared @code{virtual}. - -@cindex @code{inline} -@item i -The member is declared @code{inline}. - -@cindex @code{const} attribute -@item c -The member is @code{const}. - -@cindex pure virtual function attribute -@item 0 -The member is a pure virtual function. - -@cindex @code{mutable} attribute -@item m -The member is declared @code{mutable}. - -@cindex @code{explicit} attribute -@item e -The member is declared @code{explicit}. - -@item t -The member is a function with a throw list. -@end table -@end table - -This command is also in the buffer's context menu. - - - -@node Long and Short Display, Regexp Display, Attributes, Member Buffers -@comment node-name, next, previous, up -@section Long and Short Member Display -@cindex display form -@cindex long display -@cindex short display - -@table @kbd -@item D l -This command toggles the member buffer between short and long display -form. The short display form displays member names, only: - -@example -| isEmpty contains hasMember create -| storeSize hash isEqual restoreGuts -| saveGuts -@end example - -The long display shows one member per line with member name and regular -expressions matching the member (if known): - -@example -| isEmpty Bool isEmpty () const... -| hash unsigned hash () const... -| isEqual int isEqual (... -@end example - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}. -@xref{Matching, --no-regexps, Regular Expressions}. -@end table - - - - -@node Regexp Display, Switching Classes, Long and Short Display, Member Buffers -@comment node-name, next, previous, up -@section Display of Regular Expressions -@cindex regular expression display - -@table @kbd -@item D r -This command toggles the long display form from displaying the regular -expressions matching the member declarations to those expressions -matching member definitions. -@end table - -Regular expressions will only be displayed when the Lisp database has -not been produced with the @command{ebrowse} option @samp{--no-regexps}, -see @ref{Matching, --no-regexps, Regular Expressions}. - - - - -@node Switching Classes, Killing/Burying, Regexp Display, Member Buffers -@comment node-name, next, previous, up -@section Displaying Another Class -@cindex base class, display -@cindex derived class, display -@cindex superclass, display -@cindex subclass, display -@cindex class display - -@table @kbd -@item C c -This command lets you switch the member buffer to another class. It -reads the name of the new class from the minibuffer with completion. - -@item C b -This is the same command as @kbd{C c} but restricts the classes shown in -the completion list to immediate base classes, only. If only one base -class exists, this one is immediately shown in the minibuffer. - -@item C d -Same as @kbd{C b}, but for derived classes. - -@item C p -Switch to the previous class in the class hierarchy on the same level as -the class currently displayed. - -@item C n -Switch to the next sibling of the class in the class tree. -@end table - - - - -@node Killing/Burying, Column Width, Switching Classes, Member Buffers -@comment node-name, next, previous, up -@section Burying a Member Buffer -@cindex burying member buffers - -@table @kbd -@item q -This command is a synonym for @kbd{M-x bury-buffer}. -@end table - - - - -@node Column Width, Redisplay, Killing/Burying, Member Buffers -@comment node-name, next, previous, up -@section Setting the Column Width -@cindex column width -@cindex member indentation -@cindex indentation, member - -@table @kbd -@item D w -This command sets the column width depending on the display form used -(long or short display). -@end table - - - - -@node Redisplay, Getting Help, Column Width, Member Buffers -@comment node-name, next, previous, up -@section Forced Redisplay -@cindex redisplay of member buffers - -@table @kbd -@item C-l -This command forces a redisplay of the member buffer. If the width -of the window displaying the member buffer is changed this command -redraws the member list with the appropriate column widths and number of -columns. -@end table - - - - -@node Getting Help, , Redisplay, Member Buffers -@comment node-name, next, previous, up -@cindex help - -@table @kbd -@item ? -This key is bound to @code{describe-mode}. -@end table - - - - -@comment ************************************************************** -@comment *** TAGS LIKE FUNCTIONS -@comment ************************************************************** - -@node Tags-like Functions, GNU Free Documentation License, Member Buffers, Top -@comment node-name, next, previous, up -@chapter Tags-like Functions - -Ebrowse provides tags functions similar to those of the standard -Emacs Tags facility, but better suited to the needs of C++ programmers. - -@menu -* Finding and Viewing:: Going to a member declaration/definition -* Position Stack:: Moving to previous locations -* Search & Replace:: Searching and replacing over class tree files -* Members in Files:: Listing all members in a given file -* Apropos:: Listing members matching a regular expression -* Symbol Completion:: Completing names while editing -* Member Buffer Display:: Quickly display a member buffer for some - identifier -@end menu - - - -@node Finding and Viewing, Position Stack, Tags-like Functions, Tags-like Functions -@comment node-name, next, previous, up -@section Finding and Viewing Members -@cindex finding class member, in C++ source -@cindex viewing class member, in C++ source -@cindex tags -@cindex member definition, finding, in C++ source -@cindex member declaration, finding, in C++ source - -The functions in this section are similar to those described in -@ref{Source Display}, and also in @ref{Finding/Viewing}, except that -they work in a C++ source buffer, not in member and tree buffers created -by Ebrowse. - -@table @kbd -@item C-c C-m f -Find the definition of the member around point. If you invoke this -function with a prefix argument, the declaration is searched. - -If more than one class contains a member with the given name you can -select the class with completion. If there is a scope declaration in -front of the member name, this class name is used as initial input for -the completion. - -@item C-c C-m F -Find the declaration of the member around point. - -@item C-c C-m v -View the definition of the member around point. - -@item C-c C-m V -View the declaration of the member around point. - -@item C-c C-m 4 f -Find a member's definition in another window. - -@item C-c C-m 4 F -Find a member's declaration in another window. - -@item C-c C-m 4 v -View a member's definition in another window. - -@item C-c C-m 4 V -View a member's declaration in another window. - -@item C-c C-m 5 f -Find a member's definition in another frame. - -@item C-c C-m 5 F -Find a member's declaration in another frame. - -@item C-c C-m 5 v -View a member's definition in another frame. - -@item C-c C-m 5 V -View a member's declaration in another frame. -@end table - - - -@node Position Stack, Search & Replace, Finding and Viewing, Tags-like Functions -@comment node-name, next, previous, up -@section The Position Stack -@cindex position stack - -When jumping to a member declaration or definition with one of -Ebrowse's commands, the position from where you performed the -jump and the position where you jumped to are recorded in a -@dfn{position stack}. There are several ways in which you can quickly -move to positions in the stack:@refill - -@table @kbd -@cindex return to original position -@item C-c C-m - -This command sets point to the previous position in the position stack. -Directly after you performed a jump, this will put you back to the -position where you came from. - -The stack is not popped, i.e.@: you can always switch back and forth -between positions in the stack. To avoid letting the stack grow to -infinite size there is a maximum number of positions defined. When this -number is reached, older positions are discarded when new positions are -pushed on the stack. - -@item C-c C-m + -This command moves forward in the position stack, setting point to -the next position stored in the position stack. - -@item C-c C-m p -Displays an electric buffer showing all positions saved in the stack. -You can select a position by pressing @kbd{SPC} in a line. You can -view a position with @kbd{v}. -@end table - - - - -@node Search & Replace, Members in Files, Position Stack, Tags-like Functions -@comment node-name, next, previous, up -@section Searching and Replacing -@cindex searching multiple C++ files -@cindex replacing in multiple C++ files -@cindex restart tags-operation - -Ebrowse allows you to perform operations on all or a subset of the files -mentioned in a class tree. When you invoke one of the following -functions and more than one class tree is loaded, you must choose a -class tree to use from an electric tree menu. If the selected tree -contains marked classes, the following commands operate on the files -mentioned in the marked classes only. Otherwise all files in the class -tree are used. - -@table @kbd -@item C-c C-m s -This function performs a regular expression search in the chosen set of -files. - -@item C-c C-m u -This command performs a search for calls of a given member which is -selected in the usual way with completion. - -@item C-c C-m % -Perform a query replace over the set of files. - -@item C-c C-m , -All three operations above stop when finding a match. You can restart -the operation with this command. - -@item C-c C-m n -This restarts the last tags operation with the next file in the list. -@end table - - - - -@node Members in Files, Apropos, Search & Replace, Tags-like Functions -@comment node-name, next, previous, up -@section Members in Files -@cindex files -@cindex members in file, listing -@cindex list class members in a file -@cindex file, members - -The command @kbd{C-c C-m l}, lists all members in a given file. The file -name is read from the minibuffer with completion. - - - - -@node Apropos, Symbol Completion, Members in Files, Tags-like Functions -@comment node-name, next, previous, up -@section Member Apropos -@cindex apropos on class members -@cindex members, matching regexp - -The command @kbd{C-c C-m a} can be used to display all members matching a -given regular expression. This command can be very useful if you -remember only part of a member name, and not its beginning. - -A special buffer is popped up containing all identifiers matching the -regular expression, and what kind of symbol it is (e.g.@: a member -function, or a type). You can then switch to this buffer, and use the -command @kbd{C-c C-m f}, for example, to jump to a specific member. - - - - -@node Symbol Completion, Member Buffer Display, Apropos, Tags-like Functions -@comment node-name, next, previous, up -@section Symbol Completion -@cindex completion -@cindex symbol completion - -The command @kbd{C-c C-m @key{TAB}} completes the symbol in front of point. - - - - -@node Member Buffer Display, , Symbol Completion, Tags-like Functions -@section Quick Member Display -@cindex member buffer, for member at point - -You can quickly display a member buffer containing the member the cursor -in on with the command @kbd{C-c C-m m}. - - -@node GNU Free Documentation License, Concept Index, Tags-like Functions, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Concept Index, , GNU Free Documentation License, Top -@unnumbered Concept Index -@printindex cp - -@bye - -@ignore - arch-tag: 52fe78ac-a1c4-48e7-815e-0a31acfad4bf -@end ignore diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi deleted file mode 100644 index 80540ea19e8..00000000000 --- a/doc/misc/ediff.texi +++ /dev/null @@ -1,2541 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for Ediff -@c Written by Michael Kifer - -@comment %**start of header (This is for running Texinfo on a region.) - -@comment Using ediff.info instead of ediff in setfilename breaks DOS. -@comment @setfilename ediff -@comment @setfilename ediff.info -@setfilename ../../info/ediff - -@settitle Ediff User's Manual -@synindex vr cp -@synindex fn cp -@synindex pg cp -@synindex ky cp - -@iftex -@finalout -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This file documents Ediff, a comprehensive visual interface to Unix diff -and patch utilities. - -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Ediff: (ediff). A visual interface for comparing and merging programs. -@end direntry - -@titlepage -@title Ediff User's Manual -@sp 4 -@subtitle Ediff version 2.81.2 -@sp 1 -@subtitle November 2008 -@sp 5 -@author Michael Kifer -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, Introduction, (dir), (dir) - -@insertcopying - -@menu -* Introduction:: About Ediff. -* Major Entry Points:: How to use Ediff. -* Session Commands:: Ediff commands used within a session. -* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. -* Session Groups:: Comparing and merging directories. -* Remote and Compressed Files:: You may want to know about this. -* Customization:: How to make Ediff work the way YOU want. -* Credits:: Thanks to those who helped. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction, Major Entry Points, Top, Top -@chapter Introduction - -@cindex Comparing files and buffers -@cindex Merging files and buffers -@cindex Patching files and buffers -@cindex Finding differences - -Ediff provides a convenient way for simultaneous browsing through -the differences between a pair (or a triple) of files or buffers -(which are called @samp{variants} for our purposes). The -files being compared, file-A, file-B, and file-C (if applicable) are -shown in separate windows (side by side, one above the another, or in -separate frames), and the differences are highlighted as you step -through them. You can also copy difference regions from one buffer to -another (and recover old differences if you change your mind). - -Another powerful feature is the ability to merge a pair of files into a -third buffer. Merging with an ancestor file is also supported. -Furthermore, Ediff is equipped with directory-level capabilities that -allow the user to conveniently launch browsing or merging sessions on -groups of files in two (or three) different directories. - -In addition, Ediff can apply a patch to a file and then let you step through -both files, the patched and the original one, simultaneously, -difference-by-difference. You can even apply a patch right out of a mail -buffer, i.e., patches received by mail don't even have to be saved. Since -Ediff lets you copy differences between variants, you can, in effect, apply -patches selectively (i.e., you can copy a difference region from -@file{file.orig} to @file{file}, thereby undoing any particular patch that -you don't like). - -Ediff even understands multi-file patches and can apply them interactively! -(Ediff can recognize multi-file patches only if they are in the context -format or GNU unified format. All other patches are treated as 1-file -patches. Ediff is [hopefully] using the same algorithm as @code{patch} to -determine which files need to be patched.) - -Ediff is aware of version control, which lets you compare -files with their older versions. Ediff also works with remote and -compressed files, automatically ftp'ing them over and uncompressing them. -@xref{Remote and Compressed Files}, for details. - -This package builds upon ideas borrowed from Emerge, and several of Ediff's -functions are adaptations from Emerge. Although Ediff subsumes and greatly -extends Emerge, much of the functionality in Ediff is influenced by Emerge. -The architecture and the interface are, of course, drastically different. - -@node Major Entry Points, Session Commands, Introduction, Top -@chapter Major Entry Points - -When Ediff starts up, it displays a small control window, which accepts the -Ediff commands, and two or three windows displaying the files to be compared -or merged. The control window can be in its own small frame or it can be -part of a bigger frame that displays other buffers. In any case, it is -important that the control window be active (i.e., be the one receiving the -keystrokes) when you use Ediff. You can switch to other Emacs buffers at -will and even edit the files currently being compared with Ediff and then -switch back to Ediff at any time by activating the appropriate Emacs windows. - -Ediff can be invoked interactively using the following functions, which can -be run either from the minibuffer or from the menu bar. In the menu bar, -all Ediff's entry points belong to three submenus of the Tools menu: -Compare, Merge, and Apply Patch. - -@table @code -@item ediff-files -@itemx ediff -@findex ediff-files -@findex ediff -Compare two files. - -@item ediff-backup -@findex ediff-backup -Compare a file with its backup. If there are several numerical backups, use -the latest. If the file is itself a backup, then compare it with its -original. - -@item ediff-buffers -@findex ediff-buffers -Compare two buffers. - -@item ediff-files3 -@itemx ediff3 -@findex ediff-files3 -@findex ediff3 -Compare three files. - -@item ediff-buffers3 -@findex ediff-buffers3 -Compare three buffers. - -@item edirs -@itemx ediff-directories -@findex edirs -@findex ediff-directories - Compare files common to two directories. -@item edirs3 -@itemx ediff-directories3 -@findex edirs3 -@findex ediff-directories3 - Compare files common to three directories. -@item edir-revisions -@itemx ediff-directory-revisions -@findex ediff-directory-revisions -@findex edir-revisions - Compare versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions -@itemx ediff-merge-directory-revisions -@findex edir-merge-revisions -@findex ediff-merge-directory-revisions - Merge versions of files in a given directory. Ediff selects only the -files that are under version control. -@item edir-merge-revisions-with-ancestor -@itemx ediff-merge-directory-revisions-with-ancestor -@findex edir-merge-revisions-with-ancestor -@findex ediff-merge-directory-revisions-with-ancestor - Merge versions of files in a given directory using other versions as -ancestors. Ediff selects only the files that are under version control. - -@item ediff-windows-wordwise -@findex ediff-windows-wordwise -Compare windows word-by-word. - -@item ediff-windows-linewise -@findex ediff-windows-linewise -Compare windows line-by-line. - -@item ediff-regions-wordwise -@findex ediff-regions-wordwise -Compare regions word-by-word. The regions can come from the same buffer -and they can even overlap. You will be asked to specify the buffers that -contain the regions, which you want to compare. For each buffer, you will -also be asked to mark the regions to be compared. Pay attention to the -messages that appear in the minibuffer. - -@item ediff-regions-linewise -@findex ediff-regions-linewise -Similar to @code{ediff-windows-linewise}, but compares the regions -line-by-line. See @code{ediff-windows-linewise} for more details. - -@item ediff-revision -@findex ediff-revision - Compare versions of the current buffer, if the buffer is visiting - a file under version control. - -@item ediff-patch-file -@itemx epatch -@findex ediff-patch-file -@findex epatch - -Patch a file or multiple files, then compare. If the patch applies to just -one file, Ediff will invoke a regular comparison session. If it is a -multi-file patch, then a session group interface will be used and the user -will be able to patch the files selectively. @xref{Session Groups}, for -more details. - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -Note that @code{ediff-patch-file} will actually use the @code{patch} -utility to change the original files on disk. This is not that -dangerous, since you will always have the original contents of the file -saved in another file that has the extension @file{.orig}. -Furthermore, if the file is under version control, then you can always back -out to one of the previous versions (see the section on Version Control in -the Emacs manual). - -@code{ediff-patch-file} is careful about versions control: if the file -to be patched is checked in, then Ediff will offer to check it out, because -failing to do so may result in the loss of the changes when the file is -checked out the next time. - -If you don't intend to modify the file via the patch and just want to see -what the patch is all about (and decide later), then -@code{ediff-patch-buffer} might be a better choice. - -@item ediff-patch-buffer -@itemx epatch-buffer -@findex ediff-patch-buffer -@findex epatch-buffer -Patch a buffer, then compare. The buffer being patched and the file visited -by that buffer (if any) is @emph{not} modified. The result of the patch -appears in some other buffer that has the name ending with @emph{_patched}. - -This function would refuse to apply a multifile patch to a buffer. Use -@code{ediff-patch-file} for that (and when you want the original file to be -modified by the @code{patch} utility). - -Since the patch might be in a buffer or a file, you will be asked which is -the case. To avoid this extra prompt, you can invoke this command with a -prefix argument. With an odd prefix argument, Ediff assumes the patch -is in a file; with an even argument, a buffer is assumed. - -@item ediff-merge-files -@itemx ediff-merge -@findex ediff-merge-files -@findex ediff-merge -Merge two files. - -@item ediff-merge-files-with-ancestor -@itemx ediff-merge-with-ancestor -@findex ediff-merge-files-with-ancestor -@findex ediff-merge-with-ancestor -Like @code{ediff-merge}, but with a third ancestor file. - -@item ediff-merge-buffers -@findex ediff-merge-buffers -Merge two buffers. - -@item ediff-merge-buffers-with-ancestor -@findex ediff-merge-buffers-with-ancestor -Same but with ancestor. - - -@item edirs-merge -@itemx ediff-merge-directories -@findex edirs-merge -@findex ediff-merge-directories - Merge files common to two directories. -@item edirs-merge-with-ancestor -@itemx ediff-merge-directories-with-ancestor -@findex edirs-merge-with-ancestor -@findex ediff-merge-directories-with-ancestor - Same but using files in a third directory as ancestors. - If a pair of files doesn't have an ancestor in the ancestor-directory, you - will still be able to merge them without the ancestor. - -@item ediff-merge-revisions -@findex ediff-merge-revisions -Merge two versions of the file visited by the current buffer. - -@item ediff-merge-revisions-with-ancestor -@findex ediff-merge-revisions-with-ancestor -Same but with ancestor. - -@item ediff-documentation -@findex ediff-documentation -Brings up this manual. - -@item ediff-show-registry -@itemx eregistry -Brings up Ediff session registry. This feature enables you to quickly find -and restart active Ediff sessions. -@end table - -@noindent -If you want Ediff to be loaded from the very beginning of your Emacs -session, you should put this line in your @file{~/.emacs} file: - -@example -(require 'ediff) -@end example - -@noindent -Otherwise, Ediff will be loaded automatically when you use one of the -above functions, either directly or through the menus. - -When the above functions are invoked, the user is prompted for all the -necessary information---typically the files or buffers to compare, merge, or -patch. Ediff tries to be smart about these prompts. For instance, in -comparing/merging files, it will offer the visible buffers as defaults. In -prompting for files, if the user enters a directory, the previously input -file name will be appended to that directory. In addition, if the variable -@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer -previously entered directories as defaults (which will be maintained -separately for each type of file, A, B, or C). -@vindex @code{ediff-use-last-dir} - -All the above functions use the POSIX @code{diff} or @code{diff3} programs -to find differences between two files. They process the @code{diff} output -and display it in a convenient form. At present, Ediff understands only -the plain output from diff. Options such as @samp{-c} are not supported, -nor is the format produced by incompatible file comparison programs such as -the VMS version of @code{diff}. - -The functions @code{ediff-files}, @code{ediff-buffers}, -@code{ediff-files3}, @code{ediff-buffers3} first display the coarse, -line-based difference regions, as reported by the @code{diff} program. The -total number of difference regions and the current difference number are -always displayed in the mode line of the control window. - -Since @code{diff} may report fairly large chunks of text as being different, -even though the difference may be localized to just a few words or even -to the white space or line breaks, Ediff further @emph{refines} the -regions to indicate which exact words differ. If the only difference is -in the white space and line breaks, Ediff says so. - -On a color display, fine differences are highlighted with color; on a -monochrome display, they are underlined. @xref{Highlighting Difference -Regions}, for information on how to customize this. - -The commands @code{ediff-windows-wordwise}, -@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and -@code{ediff-regions-linewise} do comparison on parts of existing Emacs -buffers. The commands @code{ediff-windows-wordwise} and -@code{ediff-regions-wordwise} are intended for relatively small segments -of buffers (e.g., up to 100 lines, depending on the speed of your machine), -as they perform comparison on the basis of words rather than lines. -(Word-wise comparison of large chunks of text can be slow.) - -To compare large regions, use @code{ediff-regions-linewise}. This -command displays differences much like @code{ediff-files} and -@code{ediff-buffers}. - -The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a -patch to a file or a buffer and then run Ediff on the appropriate -files/buffers, displaying the difference regions. - -The entry points @code{ediff-directories}, @code{ediff-merge-directories}, -etc., provide a convenient interface for comparing and merging files in -different directories. The user is presented with Dired-like interface from -which one can run a group of related Ediff sessions. - -For files under version control, @code{ediff-revision} lets you compare -the file visited by the current buffer to one of its checked-in versions. -You can also compare two checked-in versions of the visited file. -Moreover, the functions @code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, etc., let you run a group of -related Ediff sessions by taking a directory and comparing (or merging) -versions of files in that directory. - -@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top -@chapter Session Commands - -All Ediff commands are displayed in a Quick Help window, unless you type -@kbd{?} to shrink the window to just one line. You can redisplay the help -window by typing @kbd{?} again. The Quick Help commands are detailed below. - -Many Ediff commands take numeric prefix arguments. For instance, if you -type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), -Ediff moves to the third difference region. Typing 3 and then @kbd{a} -(@code{ediff-diff-to-diff}) copies the 3rd difference region from variant A -to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference -region in buffer A (if it was previously written over via the command -@kbd{a}). - -Some commands take negative prefix arguments as well. For instance, typing -@kbd{-} and then @kbd{j} will make the last difference region -current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference -region current, etc. - -Without the prefix argument, all commands operate on the currently -selected difference region. You can make any difference region -current using the various commands explained below. - -For some commands, the actual value of the prefix argument is -immaterial. However, if supplied, the prefix argument may modify the -command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}). - -@menu -* Quick Help Commands:: Frequently used commands. -* Other Session Commands:: Commands that are not bound to keys. -@end menu - -@node Quick Help Commands,Other Session Commands,,Session Commands -@section Quick Help Commands - -@table @kbd -@item ? -@kindex ? -Toggles the Ediff Quick Help window ON and OFF. -@item G -@kindex G -Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer. - -@item E -@kindex E -Brings up the top node of this manual, where you can find further -information on the various Ediff functions and advanced issues, such as -customization, session groups, etc. - -@item v -@kindex v -Scrolls up buffers A and B (and buffer C where appropriate) in a -coordinated fashion. -@item V -@kindex V -Scrolls the buffers down. - -@item < -@kindex < -Scrolls the buffers to the left simultaneously. -@item > -@kindex > -Scrolls buffers to the right. - -@item wd -@kindex wd -Saves the output from the diff utility, for further reference. - -With prefix argument, saves the plain output from @code{diff} (see -@code{ediff-diff-program} and @code{ediff-diff-options}). Without the -argument, it saves customized @code{diff} output (see -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if -it is available. - -@item wa -@kindex wa -Saves buffer A, if it was modified. -@item wb -@kindex wb -Saves buffer B, if it was modified. -@item wc -@kindex wc -Saves buffer C, if it was modified (if you are in a session that -compares three files simultaneously). - -@item a -@kindex a -@emph{In comparison sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B. -Ediff saves the old contents of buffer B's region; it can -be restored via the command @kbd{rb}, which see. - -@emph{In merge sessions:} -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to the merge buffer. The old contents of -this region in buffer C can be restored via the command @kbd{r}. - -@item b -@kindex b -Works similarly, but copies the current difference region from buffer B to -buffer A (in @emph{comparison sessions}) or the merge buffer (in -@emph{merge sessions}). - -Ediff saves the old contents of the difference region copied over; it can -be reinstated via the command @kbd{ra} in comparison sessions and -@kbd{r} in merge sessions. - -@item ab -@kindex ab -Copies the current difference region (or the region specified as the prefix -to this command) from buffer A to buffer B. This (and the next five) -command is enabled only in sessions that compare three files -simultaneously. The old region in buffer B is saved and can be restored -via the command @kbd{rb}. -@item ac -@kindex ac -Copies the difference region from buffer A to buffer C. -The old region in buffer C is saved and can be restored via the command -@kbd{rc}. -@item ba -@kindex ba -Copies the difference region from buffer B to buffer A. -The old region in buffer A is saved and can be restored via the command -@kbd{ra}. -@item bc -@kindex bc -Copies the difference region from buffer B to buffer C. -The command @kbd{rc} undoes this. -@item ca -@kindex ca -Copies the difference region from buffer C to buffer A. -The command @kbd{ra} undoes this. -@item cb -@kindex cb -Copies the difference region from buffer C to buffer B. -The command @kbd{rb} undoes this. - -@item p -@itemx DEL -@kindex p -@kindex DEL -Makes the previous difference region current. -@item n -@itemx SPC -@kindex n -@kindex SPC -Makes the next difference region current. - -@item j -@itemx -j -@itemx Nj -@kindex j -Makes the very first difference region current. - -@kbd{-j} makes the last region current. Typing a number, N, and then `j' -makes the difference region N current. Typing -N (a negative number) then -`j' makes current the region Last - N. - -@item ga -@kindex ga -Makes current the difference region closest to the position of the point in -buffer A. - -However, with a prefix argument, Ediff would position all variants -around the area indicated by the current point in buffer A: if -the point is inside a difference region, then the variants will be -positioned at this difference region. If the point is not in any difference -region, then it is in an area where all variants agree with each other. In -this case, the variants will be positioned so that each would display this -area (of agreement). -@item gb -@kindex gb -Makes current the difference region closest to the position of the point in -buffer B. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B. -@item gc -@kindex gc -@emph{In merge sessions:} -makes current the difference region closest to the point in the merge buffer. - -@emph{In 3-file comparison sessions:} -makes current the region closest to the point in buffer C. - -With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C. - -@item ! -@kindex ! -Recomputes the difference regions, bringing them up to date. This is often -needed because it is common to do all sorts of editing during Ediff -sessions, so after a while, the highlighted difference regions may no -longer reflect the actual differences among the buffers. - -@item * -@kindex * -Forces refinement of the current difference region, which highlights the exact -words of disagreement among the buffers. With a negative prefix argument, -unhighlights the current region. - -Forceful refinement may be needed if Ediff encounters a difference region -that is larger than @code{ediff-auto-refine-limit}. In this situation, -Ediff doesn't do automatic refinement in order to improve response time. -(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still -works there. However, the only useful piece of information it can tell you -is whether or not the difference regions disagree only in the amount of -white space.) - -This command is also useful when the highlighted fine differences are -no longer current, due to user editing. - -@item m -@kindex m -Displays the current Ediff session in a frame as wide as the physical -display. This is useful when comparing files side-by-side. Typing `m' again -restores the original size of the frame. - -@item | -@kindex | -Toggles the horizontal/vertical split of the Ediff display. Horizontal -split is convenient when it is possible to compare files -side-by-side. If the frame in which files are displayed is too narrow -and lines are cut off, typing @kbd{m} may help some. - -@item @@ -@kindex @@ -Toggles auto-refinement of difference regions (i.e., automatic highlighting -of the exact words that differ among the variants). Auto-refinement is -turned off on devices where Emacs doesn't support highlighting. - -On slow machines, it may be advantageous to turn auto-refinement off. The -user can always forcefully refine specific difference regions by typing -@kbd{*}. - -@item h -@kindex h -Cycles between full highlighting, the mode where fine differences are not -highlighted (but computed), and the mode where highlighting is done with -@acronym{ASCII} strings. The latter is not really recommended, unless on a dumb TTY. - -@item r -@kindex r -Restores the old contents of the region in the merge buffer. -(If you copied a difference region from buffer A or B into the merge buffer -using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the -region in case you change your mind.) - -This command is enabled in merge sessions only. - -@item ra -@kindex ra -Restores the old contents of the current difference region in buffer A, -which was previously saved when the user invoked one of these commands: -@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in -comparison sessions only. -@item rb -@kindex rb -Restores the old contents of the current difference region in buffer B, -which was previously saved when the user invoked one of these commands: -@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in -comparison sessions only. -@item rc -@kindex rc -Restores the old contents of the current difference region in buffer C, -which was previously saved when the user invoked one of these commands: -@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file -comparison sessions only. - -@item ## -@kindex ## -Tell Ediff to skip over regions that disagree among themselves only in the -amount of white space and line breaks. - -Even though such regions will be skipped over, you can still jump to any -one of them by typing the region number and then `j'. Typing @kbd{##} -again puts Ediff back in the original state. - -@item #c -@kindex #c -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Toggle case sensitivity in the diff program. All diffs are recomputed. -Case sensitivity is controlled by the variables -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, -and @code{ediff-ignore-case}, which are explained elsewhere. - -@item #h -@itemx #f -@kindex #f -@kindex #h -Ediff works hard to ameliorate the effects of boredom in the workplace... - -Quite often differences are due to identical replacements (e.g., the word -`foo' is replaced with the word `bar' everywhere). If the number of regions -with such boring differences exceeds your tolerance threshold, you may be -tempted to tell Ediff to skip these regions altogether (you will still be able -to jump to them via the command @kbd{j}). The above commands, @kbd{#h} -and @kbd{#f}, may well save your day! - -@kbd{#h} prompts you to specify regular expressions for each -variant. Difference regions where each variant's region matches the -corresponding regular expression will be skipped from then on. (You can -also tell Ediff to skip regions where at least one variant matches its -regular expression.) - -@kbd{#f} does dual job: it focuses on regions that match the corresponding -regular expressions. All other regions will be skipped -over. @xref{Selective Browsing}, for more. - -@item A -@kindex A -Toggles the read-only property in buffer A. -If file A is under version control and is checked in, it is checked out -(with your permission). -@item B -@kindex B -Toggles the read-only property in buffer B. -If file B is under version control and is checked in, it is checked out. -@item C -@kindex C -Toggles the read-only property in buffer C (in 3-file comparison sessions). -If file C is under version control and is checked in, it is checked out. - -@item ~ -@kindex ~ -Swaps the windows where buffers A and B are displayed. If you are comparing -three buffers at once, then this command would rotate the windows among -buffers A, B, and C. - -@item i -@kindex i -Displays all kinds of useful data about the current Ediff session. -@item D -@kindex D -Runs @code{ediff-custom-diff-program} on the variants and displays the -buffer containing the output. This is useful when you must send the output -to your Mom. - -With a prefix argument, displays the plain @code{diff} output. -@xref{Patch and Diff Programs}, for details. - -@item R -@kindex R -Displays a list of currently active Ediff sessions---the Ediff Registry. -You can then restart any of these sessions by either clicking on a session -record or by putting the cursor over it and then typing the return key. - -(Some poor souls leave so many active Ediff sessions around that they loose -track of them completely... The `R' command is designed to save these -people from the recently discovered Ediff Proficiency Syndrome.) - -Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff -Control Panel. If you don't have a control panel handy, type this in the -minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}. - -@item M -@kindex M -Shows the session group buffer that invoked the current Ediff session. -@xref{Session Groups}, for more information on session groups. - -@item z -@kindex z -Suspends the current Ediff session. (If you develop a condition known as -Repetitive Ediff Injury---a serious but curable illness---you must change -your current activity. This command tries hard to hide all Ediff-related -buffers.) - -The easiest way to resume a suspended Ediff session is through the registry -of active sessions. @xref{Registry of Ediff Sessions}, for details. -@item q -@kindex q -Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks -if you also want to delete the buffers of the variants. -Modified files and the results of merges are never deleted. - -@item % -@kindex % -Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you -are comparing only parts of these buffers via the commands -@code{ediff-windows-*} and @code{ediff-regions-*}, which see. - -@item C-l -@kindex C-l -Restores the usual Ediff window setup. This is the quickest way to resume -an Ediff session, but it works only if the control panel of that session is -visible. - -@item $$ -@kindex $$ -While merging with an ancestor file, Ediff is determined to reduce user's -wear and tear by saving him and her much of unproductive, repetitive -typing. If it notices that, say, file A's difference region is identical to -the same difference region in the ancestor file, then the merge buffer will -automatically get the difference region taken from buffer B. The rationale -is that this difference region in buffer A is as old as that in the -ancestor buffer, so the contents of that region in buffer B represents real -change. - -You may want to ignore such `obvious' merges and concentrate on difference -regions where both files `clash' with the ancestor, since this means that -two different people have been changing this region independently and they -had different ideas on how to do this. - -The above command does this for you by skipping the regions where only one -of the variants clashes with the ancestor but the other variant agrees with -it. Typing @kbd{$$} again undoes this setting. - -@item $* -@kindex $* -When merging files with large number of differences, it is sometimes -convenient to be able to skip the difference regions for which you already -decided which variant is most appropriate. Typing @kbd{$*} will accomplish -precisely this. - -To be more precise, this toggles the check for whether the current merge is -identical to its default setting, as originally decided by Ediff. For -instance, if Ediff is merging according to the `combined' policy, then the -merge region is skipped over if it is different from the combination of the -regions in buffers A and B. (Warning: swapping buffers A and B will confuse -things in this respect.) If the merge region is marked as `prefer-A' then -this region will be skipped if it differs from the current difference -region in buffer A, etc. - -@item / -@kindex / -Displays the ancestor file during merges. -@item & -@kindex & -In some situations, such as when one of the files agrees with the ancestor file -on a difference region and the other doesn't, Ediff knows what to do: it copies -the current difference region from the second buffer into the merge buffer. - -In other cases, the right course of action is not that clearcut, and Ediff -would use a default action. The above command changes the default action. -The default action can be @samp{default-A} (choose the region from buffer -A), @samp{default-B} (choose the region from buffer B), or @samp{combined} -(combine the regions from the two buffers). -@xref{Merging and diff3}, for further details. - -The command @kbd{&} also affects the regions in the merge buffers that have -@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided -they weren't changed with respect to the original. For instance, if such a -region has the status @samp{default-A} then changing the default action to -@samp{default-B} will also replace this merge-buffer's region with the -corresponding region from buffer B. - -@item s -@kindex s -Causes the merge window shrink to its minimum size, thereby exposing as much -of the variant buffers as possible. Typing `s' again restores -the original size of that window. - -With a positive prefix argument, this command enlarges the merge window. -E.g., @kbd{4s} increases the size of the window by about 4 lines, if -possible. With a negative numeric argument, the size of the merge window -shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window -by about 1 line and @kbd{-3s} by about 3 lines. - -This command is intended only for temporary viewing; therefore, Ediff -restores window C to its original size whenever it makes any other change -in the window configuration. However, redisplaying (@kbd{C-l}) or jumping -to another difference does not affect window C's size. - -The split between the merge window and the variant windows is controlled by -the variable @code{ediff-merge-window-share}, which see. - -@item + -@kindex + -Combines the difference regions from buffers A and B and copies the -result into the merge buffer. @xref{Merging and diff3}, and the -variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}. - - -@item = -@kindex = -You may run into situations when a large chunk of text in one file has been -edited and then moved to a different place in another file. In such a case, -these two chunks of text are unlikely to belong to the same difference -region, so the refinement feature of Ediff will not be able to tell you -what exactly differs inside these chunks. Since eyeballing large pieces of -text is contrary to human nature, Ediff has a special command to help -reduce the risk of developing a cataract. - -In other situations, the currently highlighted region might be big and you -might want to reconcile of them interactively. - -All of this can be done with the above command, @kbd{=}, which -compares regions within Ediff buffers. Typing @kbd{=} creates a -child Ediff session for comparing regions in buffers A, B, or -C as follows. - -First, you will be asked whether you want to compare the fine differences -between the currently highlighted buffers on a word-by-word basis. If you -accept, a child Ediff session will start using the currently highlighted -regions. Ediff will let you step over the differences word-wise. - -If you reject the offer, you will be asked to select regions of your choice. - -@emph{If you are comparing 2 files or buffers:} -Ediff will ask you to select regions in buffers A and B. - -@emph{If you are comparing 3 files or buffers simultaneously:} Ediff will -ask you to choose buffers and then select regions inside those buffers. - -@emph{If you are merging files or buffers (with or without ancestor):} -Ediff will ask you to choose which buffer (A or B) to compare with the -merge buffer and then select regions in those buffers. - -@end table - -@node Other Session Commands,,Quick Help Commands,Session Commands -@section Other Session Commands - -The following commands can be invoked from within any Ediff session, -although some of them are not bound to a key. - -@table @code -@item eregistry -@itemx ediff-show-registry -@findex eregistry -@findex ediff-show-registry -This command brings up the registry of active Ediff sessions. Ediff -registry is a device that can be used to resume any active Ediff session -(which may have been postponed because the user switched to some other -activity). This command is also useful for switching between multiple -active Ediff sessions that are run at the same time. The function -@code{eregistry} is an alias for @code{ediff-show-registry}. -@xref{Registry of Ediff Sessions}, for more information on this registry. - -@item ediff-toggle-multiframe -@findex ediff-toggle-multiframe -Changes the display from the multi-frame mode (where the quick help window -is in a separate frame) to the single-frame mode (where all Ediff buffers -share the same frame), and vice versa. See -@code{ediff-window-setup-function} for details on how to make either of -these modes the default one. - -This function can also be invoked from the Menubar. However, in some -cases, the change will take place only after you execute one of the Ediff -commands, such as going to the next difference or redisplaying. - -@item ediff-toggle-use-toolbar -@findex ediff-toggle-use-toolbar -Available in XEmacs only. The Ediff toolbar provides quick access to some -of the common Ediff functions. This function toggles the display of the -toolbar. If invoked from the menubar, the function may take sometimes -effect only after you execute an Ediff command, such as going to the next -difference. - -@item ediff-use-toolbar-p -@vindex ediff-use-toolbar-p -The use of the toolbar can also be specified via the variable -@code{ediff-use-toolbar-p} (default is @code{t}). This variable can be set -only in @file{.emacs} --- do @strong{not} change it interactively. Use the -function @code{ediff-toggle-use-toolbar} instead. - -@item ediff-revert-buffers-then-recompute-diffs -@findex ediff-revert-buffers-then-recompute-diffs -This command reverts the buffers you are comparing and recomputes their -differences. It is useful when, after making changes, you decided to -make a fresh start, or if at some point you changed the files being -compared but want to discard any changes to comparison buffers that were -done since then. - -This command normally asks for confirmation before reverting files. -With a prefix argument, it reverts files without asking. - - -@item ediff-profile -@findex ediff-profile -Ediff has an admittedly primitive (but useful) facility for profiling -Ediff's commands. It is meant for Ediff maintenance---specifically, for -making it run faster. The function @code{ediff-profile} toggles -profiling of ediff commands. -@end table - -@node Registry of Ediff Sessions, Session Groups, Session Commands, Top -@chapter Registry of Ediff Sessions - -Ediff maintains a registry of all its invocations that are -still @emph{active}. This feature is very convenient for switching among -active Ediff sessions or for quickly restarting a suspended Ediff session. - -The focal point of this activity is a buffer -called @emph{*Ediff Registry*}. You can display this buffer by typing -@kbd{R} in any Ediff Control Buffer or Session Group Buffer -(@pxref{Session Groups}), or by typing -@kbd{M-x eregistry} into the Minibuffer. -The latter would be the fastest way to bring up the registry -buffer if no control or group buffer is displayed in any of the visible -Emacs windows. -If you are in a habit of running multiple long Ediff sessions and often need to -suspend, resume, or switch between them, it may be a good idea to have the -registry buffer permanently displayed in a separate, dedicated window. - -The registry buffer has several convenient key bindings. -For instance, clicking mouse button 2 or typing -@kbd{RET} or @kbd{v} over any session record resumes that session. -Session records in the registry buffer provide a fairly complete -description of each session, so it is usually easy to identify the right -session to resume. - -Other useful commands are bound to @kbd{SPC} (next registry record) -and @kbd{DEL} (previous registry record). There are other commands as well, -but you don't need to memorize them, since they are listed at the top of -the registry buffer. - -@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top -@chapter Session Groups - -Several major entries of Ediff perform comparison and merging on -directories. On entering @code{ediff-directories}, -@code{ediff-directories3}, -@code{ediff-merge-directories}, -@code{ediff-merge-directories-with-ancestor}, -@code{ediff-directory-revisions}, -@code{ediff-merge-directory-revisions}, or -@code{ediff-merge-directory-revisions-with-ancestor}, -the user is presented with a -Dired-like buffer that lists files common to the directories involved along -with their sizes. (The list of common files can be further filtered through -a regular expression, which the user is prompted for.) We call this buffer -@emph{Session Group Panel} because all Ediff sessions associated with the -listed files will have this buffer as a common focal point. - -Clicking button 2 or typing @kbd{RET} or @kbd{v} over a -record describing files invokes Ediff in the appropriate mode on these -files. You can come back to the session group buffer associated with a -particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of -that invocation. - -Many commands are available in the session group buffer; some are -applicable only to certain types of work. The relevant commands are always -listed at the top of each session group buffer, so there is no need to -memorize them. - -In directory comparison or merging, a session group panel displays only the -files common to all directories involved. The differences are kept in a -separate @emph{directory difference buffer} and are conveniently displayed -by typing @kbd{D} to the corresponding session group panel. Thus, as an -added benefit, Ediff can be used to compare the contents of up to three -directories. - -@cindex Directory difference buffer -Sometimes it is desirable to copy some files from one directory to another -without exiting Ediff. The @emph{directory difference buffer}, which is -displayed by typing @kbd{D} as discussed above, can be used for this -purpose. If a file is, say, in Ediff's Directory A, but is missing in -Ediff's Directory B (Ediff will refuse to override existing files), then -typing @kbd{C} or clicking mouse button 2 over that file (which must be -displayed in directory difference buffer) will copy that file from -Directory A to Directory B. - -Session records in session group panels are also marked with @kbd{+}, for -active sessions, and with @kbd{-}, for finished sessions. - -Sometimes, it is convenient to exclude certain sessions from a group. -Usually this happens when the user doesn't intend to run Ediff of certain -files in the group, and the corresponding session records just add clutter -to the session group buffer. To help alleviate this problem, the user can -type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to -actually hide the marked sessions. There actions are reversible: with a -prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x} -brings the hidden sessions into the view (@kbd{x} doesn't unmark them, -though, so the user has to explicitly unmark the sessions of interest). - -Group sessions also understand the command @kbd{m}, which marks sessions -for future operations (other than hiding) on a group of sessions. At present, -the only such group-level operation is the creation of a multi-file patch. - -@vindex ediff-autostore-merges -For group sessions created to merge files, Ediff can store all merges -automatically in a directory. The user is asked to specify such directory -if the value of @code{ediff-autostore-merges} is non-@code{nil}. If the value is -@code{nil}, nothing is done to the merge buffers---it will be the user's -responsibility to save them. If the value is @code{t}, the user will be -asked where to save the merge buffers in all merge jobs, even those that do -not originate from a session group. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a session group. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set on a per-buffer basis. Therefore, use @code{setq-default} to change -this variable globally. - -@cindex Multi-file patches -A multi-file patch is a concatenated output of several runs of the Unix -@code{diff} command (some versions of @code{diff} let you create a -multi-file patch in just one run). Ediff facilitates creation of -multi-file patches as follows. If you are in a session group buffer -created in response to @code{ediff-directories} or -@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the -desired Ediff sessions and then type @kbd{P} to create a -multi-file patch of those marked sessions. -Ediff will then display a buffer containing the patch. -The patch is generated by invoking @code{diff} on all marked individual -sessions (represented by files) and session groups (represented by -directories). Ediff will also recursively descend into any @emph{unmarked} -session group and will search for marked sessions there. In this way, you -can create multi-file patches that span file subtrees that grow out of -any given directory. - -In an @code{ediff-directories} session, it is enough to just mark the -requisite sessions. In @code{ediff-directory-revisions} revisions, the -marked sessions must also be active, or else Ediff will refuse to produce a -multi-file patch. This is because, in the latter-style sessions, there are -many ways to create diff output, and it is easier to handle by running -Ediff on the inactive sessions. - -Last, but not least, by typing @kbd{==}, you can quickly find out which -sessions have identical entries, so you won't have to run Ediff on those -sessions. This, however, works only on local, uncompressed files. -For compressed or remote files, this command won't report anything. -Likewise, you can use @kbd{=h} to mark sessions with identical entries -for hiding or, with @kbd{=m}, for further operations. - -The comparison operations @kbd{==}, @kbd{=h}, and @kbd{=m} can recurse into -subdirectories to see if they have identical contents (so the user will not -need to descend into those subdirectories manually). These commands ask the -user whether or not to do a recursive descent. - - - -@node Remote and Compressed Files, Customization, Session Groups, Top -@chapter Remote and Compressed Files - -Ediff works with remote, compressed, and encrypted files. Ediff -supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el} -and @file{crypt++.el}, but it may work with other similar packages as -well. This means that you can compare files residing on another -machine, or you can apply a patch to a file on another machine. Even -the patch itself can be a remote file! - -When patching compressed or remote files, Ediff does not rename the source -file (unlike what the @code{patch} utility would usually do). Instead, the -source file retains its name and the result of applying the patch is placed -in a temporary file that has the suffix @file{_patched} attached. -Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption -packages also use this method). - -Regular files are treated by the @code{patch} utility in the usual manner, -i.e., the original is renamed into @file{source-name.orig} and the result -of the patch is placed into the file source-name (@file{_orig} is used -on systems like DOS, etc.) - -@node Customization, Credits, Remote and Compressed Files, Top -@chapter Customization - -Ediff has a rather self-explanatory interface, and in most cases you -won't need to change anything. However, should the need arise, there are -extensive facilities for changing the default behavior. - -Most of the customization can be done by setting various variables in the -@file{.emacs} file. Some customization (mostly window-related -customization and faces) can be done by putting appropriate lines in -@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. - -With respect to the latter, please note that the X resource -for Ediff customization is `Ediff', @emph{not} `emacs'. -@xref{Window and Frame Configuration}, -@xref{Highlighting Difference Regions}, for further details. Please also -refer to Emacs manual for the information on how to set Emacs X resources. - -@menu -* Hooks:: Customization via the hooks. -* Quick Help Customization:: How to customize Ediff's quick help feature. -* Window and Frame Configuration:: Controlling the way Ediff displays things. -* Selective Browsing:: Advanced browsing through difference regions. -* Highlighting Difference Regions:: Controlling highlighting. -* Narrowing:: Comparing regions, windows, etc. -* Refinement of Difference Regions:: How to control the refinement process. -* Patch and Diff Programs:: Changing the utilities that compute differences - and apply patches. -* Merging and diff3:: How to customize Ediff in its Merge Mode. -* Support for Version Control:: Changing the version control package. - You are not likely to do that. -* Customizing the Mode Line:: Changing the look of the mode line in Ediff. -* Miscellaneous:: Other customization. -* Notes on Heavy-duty Customization:: Customization for the gurus. -@end menu - -@node Hooks, Quick Help Customization, Customization, Customization -@section Hooks - -The bulk of customization can be done via the following hooks: - -@table @code -@item ediff-load-hook -@vindex ediff-load-hook -This hook can be used to change defaults after Ediff is loaded. - -@item ediff-before-setup-hook -@vindex ediff-before-setup-hook -Hook that is run just before Ediff rearranges windows to its liking. -Can be used to save windows configuration. - -@item ediff-keymap-setup-hook -@vindex ediff-keymap-setup-hook -@vindex ediff-mode-map -This hook can be used to alter bindings in Ediff's keymap, -@code{ediff-mode-map}. These hooks are -run right after the default bindings are set but before -@code{ediff-load-hook}. The regular user needs not be concerned with this -hook---it is provided for implementors of other Emacs packages built on top -of Ediff. - -@item ediff-before-setup-windows-hook -@itemx ediff-after-setup-windows-hook -@vindex ediff-before-setup-windows-hook -@vindex ediff-after-setup-windows-hook -These two hooks are called before and after Ediff sets up its window -configuration. These hooks are run each time Ediff rearranges windows to -its liking. This happens whenever it detects that the user changed the -windows setup. - -@item ediff-suspend-hook -@itemx ediff-quit-hook -@vindex ediff-suspend-hook -@vindex ediff-quit-hook -These two hooks are run when you suspend or quit Ediff. They can be -used to set desired window configurations, delete files Ediff didn't -want to clean up after exiting, etc. - -By default, @code{ediff-quit-hook} holds one hook function, -@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in -most cases. You probably won't want to change it, but you might -want to add other hook functions. - -Keep in mind that hooks executing before @code{ediff-cleanup-mess} start -in @code{ediff-control-buffer;} they should also leave -@code{ediff-control-buffer} as the current buffer when they finish. -Hooks that are executed after @code{ediff-cleanup-mess} should expect -the current buffer be either buffer A or buffer B. -@code{ediff-cleanup-mess} doesn't kill the buffers being compared or -merged (see @code{ediff-cleanup-hook}, below). - -@item ediff-cleanup-hook -@vindex ediff-cleanup-hook -This hook is run just before @code{ediff-quit-hook}. This is a good -place to do various cleanups, such as deleting the variant buffers. -Ediff provides a function, @code{ediff-janitor}, as one such possible -hook, which you can add to @code{ediff-cleanup-hook} with -@code{add-hooks}. - -@findex ediff-janitor -This function kills buffers A, B, and, possibly, C, if these buffers aren't -modified. In merge jobs, buffer C is never deleted. However, the side -effect of using this function is that you may not be able to compare the -same buffer in two separate Ediff sessions: quitting one of them will -delete this buffer in another session as well. - -@item ediff-quit-merge-hook -@vindex ediff-quit-merge-hook -@vindex ediff-autostore-merges -@findex ediff-maybe-save-and-delete-merge -This hook is called when Ediff quits a merge job. By default, the value is -@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts -to save the merge buffer according to the value of -@code{ediff-autostore-merges}, as described later. - -@item ediff-before-setup-control-frame-hook -@itemx ediff-after-setup-control-frame-hook -@vindex ediff-before-setup-control-frame-hook -@vindex ediff-after-setup-control-frame-hook -These two hooks run before and after Ediff sets up the control frame. -They can be used to relocate Ediff control frame when Ediff runs in a -multiframe mode (i.e., when the control buffer is in its own dedicated -frame). Be aware that many variables that drive Ediff are local to -Ediff Control Panel (@code{ediff-control-buffer}), which requires -special care in writing these hooks. Take a look at -@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to -see what's involved. - -@item ediff-startup-hook -@vindex ediff-startup-hook -This hook is run at the end of Ediff startup. - -@item ediff-select-hook -@vindex ediff-select-hook -This hook is run after Ediff selects the next difference region. - -@item ediff-unselect-hook -@vindex ediff-unselect-hook -This hook is run after Ediff unselects the current difference region. - -@item ediff-prepare-buffer-hook -@vindex ediff-prepare-buffer-hook -This hook is run for each Ediff buffer (A, B, C) right after the buffer -is arranged. - -@item ediff-display-help-hook -@vindex ediff-display-help-hook -Ediff runs this hook each time after setting up the help message. It -can be used to alter the help message for custom packages that run on -top of Ediff. - -@item ediff-mode-hook -@vindex ediff-mode-hook -This hook is run just after Ediff mode is set up in the control -buffer. This is done before any Ediff window is created. You can use it to -set local variables that alter the look of the display. - -@item ediff-registry-setup-hook -@vindex ediff-registry-setup-hook -Hooks run after setting up the registry for all active Ediff session. -@xref{Session Groups}, for details. -@item ediff-before-session-group-setup-hook -@vindex ediff-before-session-group-setup-hook -Hooks run before setting up a control panel for a group of related Ediff -sessions. Can be used, for example, to save window configuration to restore -later. -@item ediff-after-session-group-setup-hook -@vindex ediff-after-session-group-setup-hook -Hooks run after setting up a control panel for a group of related Ediff -sessions. @xref{Session Groups}, for details. -@item ediff-quit-session-group-hook -@vindex ediff-quit-session-group-hook -Hooks run just before exiting a session group. -@item ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-keymap-setup-hook -@vindex ediff-meta-buffer-map -Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the -map that controls key bindings in the meta buffer. Since -@code{ediff-meta-buffer-map} is a local variable, you can set different -bindings for different kinds of meta buffers. -@end table - -@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization -@section Quick Help Customization -@vindex ediff-use-long-help-message -@vindex ediff-control-buffer -@vindex ediff-startup-hook -@vindex ediff-help-message - -Ediff provides quick help using its control panel window. Since this window -takes a fair share of the screen real estate, you can toggle it off by -typing @kbd{?}. The control window will then shrink to just one line and a -mode line, displaying a short help message. - -The variable @code{ediff-use-long-help-message} tells Ediff whether -you use the short message or the long one. By default, it -is set to @code{nil}, meaning that the short message is used. -Set this to @code{t}, if you want Ediff to use the long -message by default. This property can always be changed interactively, by -typing @kbd{?} into Ediff Control Buffer. - -If you want to change the appearance of the help message on a per-buffer -basis, you must use @code{ediff-startup-hook} to change the value of -the variable @code{ediff-help-message}, which is local to -@code{ediff-control-buffer}. - -@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization -@section Window and Frame Configuration - -On a non-windowing display, Ediff sets things up in one frame, splitting -it between a small control window and the windows for buffers A, B, and C. -The split between these windows can be horizontal or -vertical, which can be changed interactively by typing @kbd{|} while the -cursor is in the control window. - -On a window display, Ediff sets up a dedicated frame for Ediff Control -Panel and then it chooses windows as follows: If one of the buffers -is invisible, it is displayed in the currently selected frame. If -a buffer is visible, it is displayed in the frame where it is visible. -If, according to the above criteria, the two buffers fall into the same -frame, then so be it---the frame will be shared by the two. The same -algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p} -(@code{ediff-previous-difference}), @kbd{n} -(@code{ediff-next-difference}), etc. - -The above behavior also depends on whether the current frame is splittable, -dedicated, etc. Unfortunately, the margin of this book is too narrow to -present the details of this remarkable algorithm. - -The upshot of all this is that you can compare buffers in one frame or -in different frames. The former is done by default, while the latter can -be achieved by arranging buffers A, B (and C, if applicable) to be seen in -different frames. Ediff respects these arrangements, automatically -adapting itself to the multi-frame mode. - -Ediff uses the following variables to set up its control panel -(a.k.a.@: control buffer, a.k.a.@: quick help window): - -@table @code -@item ediff-control-frame-parameters -@vindex ediff-control-frame-parameters -You can change or augment this variable including the font, color, -etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under -X-windows, you can use this name to set up preferences in your -@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in -use. Usually this is preferable to changing -@code{ediff-control-frame-parameters} directly. For instance, you can -specify in @file{~/.Xdefaults} the color of the control frame -using the resource @samp{Ediff*background}. - -In general, any X resource pertaining the control frame can be reached -via the prefix @code{Ediff*}. - -@item ediff-control-frame-position-function -@vindex ediff-control-frame-position-function -The preferred way of specifying the position of the control frame is by -setting the variable @code{ediff-control-frame-position-function} to an -appropriate function. -The default value of this variable is -@code{ediff-make-frame-position}. This function places the control frame in -the vicinity of the North-East corner of the frame displaying buffer A. - -@findex ediff-make-frame-position -@end table - -The following variables can be used to adjust the location produced by -@code{ediff-make-frame-position} and for related customization. - -@table @code -@item ediff-narrow-control-frame-leftward-shift -@vindex ediff-narrow-control-frame-leftward-shift -Specifies the number of characters for shifting -the control frame from the rightmost edge of frame A when the control -frame is displayed as a small window. - -@item ediff-wide-control-frame-rightward-shift -@vindex ediff-wide-control-frame-rightward-shift -Specifies the rightward shift of the control frame -from the left edge of frame A when the control frame shows the full -menu of options. - -@item ediff-control-frame-upward-shift -@vindex ediff-control-frame-upward-shift -Specifies the number of pixels for the upward shift -of the control frame. - -@item ediff-prefer-iconified-control-frame -@vindex ediff-prefer-iconified-control-frame -If this variable is @code{t}, the control frame becomes iconified -automatically when you toggle the quick help message off. This saves -valuable real estate on the screen. Toggling help back will deiconify -the control frame. - -To start Ediff with an iconified Control Panel, you should set this -variable to @code{t} and @code{ediff-prefer-long-help-message} to -@code{nil} (@pxref{Quick Help Customization}). This behavior is useful -only if icons are allowed to accept keyboard input (which depends on the -window manager and other factors). -@end table - -@findex ediff-setup-windows -To make more creative changes in the way Ediff sets up windows, you can -rewrite the function @code{ediff-setup-windows}. However, we believe -that detaching Ediff Control Panel from the rest and making it into a -separate frame offers an important opportunity by allowing you to -iconify that frame. The icon will usually accept all of the Ediff -commands, but will free up valuable real estate on your screen (this may -depend on your window manager, though). - -The following variable controls how windows are set up: - -@table @code -@item ediff-window-setup-function -@vindex ediff-window-setup-function -The multiframe setup is done by the -@code{ediff-setup-windows-multiframe} function, which is the default on -windowing displays. The plain setup, one where all windows are always -in one frame, is done by @code{ediff-setup-windows-plain}, which is the -default on a non-windowing display (or in an xterm window). In fact, -under Emacs, you can switch freely between these two setups by executing -the command @code{ediff-toggle-multiframe} using the Minibuffer of the -Menubar. -@findex ediff-setup-windows-multiframe -@findex ediff-setup-windows-plain -@findex ediff-toggle-multiframe - -If you don't like any of these setups, write your own function. See the -documentation for @code{ediff-window-setup-function} for the basic -guidelines. However, writing window setups is not easy, so you should -first take a close look at @code{ediff-setup-windows-plain} and -@code{ediff-setup-windows-multiframe}. -@end table - -You can run multiple Ediff sessions at once, by invoking Ediff several -times without exiting previous Ediff sessions. Different sessions -may even operate on the same pair of files. - -Each session has its own Ediff Control Panel and all the regarding a -particular session is local to the associated control panel buffer. You -can switch between sessions by suspending one session and then switching -to another control panel. (Different control panel buffers are -distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.) - -@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization -@section Selective Browsing - -Sometimes it is convenient to be able to step through only some difference -regions, those that match certain regular expressions, and to ignore all -others. On other occasions, you may want to ignore difference regions that -match some regular expressions, and to look only at the rest. - -The commands @kbd{#f} and @kbd{#h} let you do precisely this. - -Typing @kbd{#f} lets you specify regular expressions that match difference -regions you want to focus on. -We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and -@var{regexp-C}. -Ediff will then start stepping through only those difference regions -where the region in buffer A matches @var{regexp-A} and/or the region in -buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used -depends on how you respond to a question. - -When scanning difference regions for the aforesaid regular expressions, -Ediff narrows the buffers to those regions. This means that you can use -the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end -of the difference regions. - -On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting -regions. That is, if a difference region in buffer A matches -@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B} -and (if applicable) buffer C's region matches @var{regexp-C}, then the -region will be ignored by the commands @kbd{n}/@key{SPC} -(@code{ediff-next-difference}) and @kbd{p}/@key{DEL} -(@code{ediff-previous-difference}) commands. - -Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off. - -Note that selective browsing affects only @code{ediff-next-difference} -and @code{ediff-previous-difference}, i.e., the commands -@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not -change the position of the point in the buffers. And you can still jump -directly (using @kbd{j}) to any numbered -difference. - -Users can supply their own functions to specify how Ediff should do -selective browsing. To change the default Ediff function, add a function to -@code{ediff-load-hook} which will do the following assignments: - -@example -(setq ediff-hide-regexp-matches-function 'your-hide-function) -(setq ediff-focus-on-regexp-matches-function 'your-focus-function) -@end example - -@strong{Useful hint}: To specify a regexp that matches everything, don't -simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff -to accept the default value, which may not be what you want. Instead, you -should enter something like @key{^} or @key{$}. These match every -line. - -You can use the status command, @kbd{i}, to find out whether -selective browsing is currently in effect. - -The regular expressions you specified are kept in the local variables -@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B}, -@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A}, -@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value -is the empty string (i.e., nothing is hidden or focused on). To change the -default, set these variables in @file{.emacs} using @code{setq-default}. - -In addition to the ability to ignore regions that match regular -expressions, Ediff can be ordered to start skipping over certain -``uninteresting'' difference regions. This is controlled by the following -variable: - -@table @code -@item ediff-ignore-similar-regions -@vindex ediff-ignore-similar-regions -If @code{t}, causes Ediff to skip over "uninteresting" difference regions, -which are the regions where the variants differ only in the amount of the -white space and newlines. This feature can be toggled on/off interactively, -via the command @kbd{##}. -@end table - -@strong{Please note:} in order for this feature to work, auto-refining of -difference regions must be on, since otherwise Ediff won't know if there -are fine differences between regions. On devices where Emacs can display -faces, auto-refining is a default, but it is not turned on by default on -text-only terminals. In that case, you must explicitly turn auto-refining -on (such as, by typing @kbd{@@}). - -@strong{Reassurance:} If many such uninteresting regions appear in a row, -Ediff may take a long time to skip over them because it has to compute fine -differences of all intermediate regions. This delay does not indicate any -problem. - -@vindex ediff-ignore-case-option -@vindex ediff-ignore-case-option3 -@vindex ediff-ignore-case -Finally, Ediff can be told to ignore the case of the letters. This behavior -can be toggled with @kbd{#c} and it is controlled with three variables: -@code{ediff-ignore-case-option}, @code{ediff-ignore-case-option3}, and -@code{ediff-ignore-case}. - -The variable @code{ediff-ignore-case-option} specifies the option to pass -to the diff program for comparing two files or buffers. For GNU -@code{diff}, this option is @code{"-i"}. The variable -@code{ediff-ignore-case-option3} specifies the option to pass to the -@code{diff3} program in order to make it case-insensitive. GNU @code{diff3} -does not have such an option, so when merging or comparing three files with -this program, ignoring the letter case is not supported. - -The variable @code{ediff-ignore-case} controls whether Ediff starts out by -ignoring letter case or not. It can be set in @file{.emacs} using -@code{setq-default}. - -When case sensitivity is toggled, all difference -regions are recomputed. - -@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization -@section Highlighting Difference Regions - -The following variables control the way Ediff highlights difference -regions: - -@table @code -@item ediff-before-flag-bol -@itemx ediff-after-flag-eol -@itemx ediff-before-flag-mol -@itemx ediff-after-flag-mol -@vindex ediff-before-flag-bol -@vindex ediff-after-flag-eol -@vindex ediff-before-flag-mol -@vindex ediff-after-flag-mol -These variables hold strings that Ediff uses to mark the beginning and the -end of the differences found in files A, B, and C on devices where Emacs -cannot display faces. Ediff uses different flags to highlight regions that -begin/end at the beginning/end of a line or in a middle of a line. - -@item ediff-current-diff-face-A -@itemx ediff-current-diff-face-B -@itemx ediff-current-diff-face-C -@vindex ediff-current-diff-face-A -@vindex ediff-current-diff-face-B -@vindex ediff-current-diff-face-C -Ediff uses these faces to highlight current differences on devices where -Emacs can display faces. These and subsequently described faces can be set -either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff -is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for -the information on how to set X resources. -@item ediff-fine-diff-face-A -@itemx ediff-fine-diff-face-B -@itemx ediff-fine-diff-face-C -@vindex ediff-fine-diff-face-A -@vindex ediff-fine-diff-face-B -@vindex ediff-fine-diff-face-C -Ediff uses these faces to show the fine differences between the current -differences regions in buffers A, B, and C, respectively. - -@item ediff-even-diff-face-A -@itemx ediff-even-diff-face-B -@itemx ediff-even-diff-face-C -@itemx ediff-odd-diff-face-A -@itemx ediff-odd-diff-face-B -@itemx ediff-odd-diff-face-C -@vindex ediff-even-diff-face-A -@vindex ediff-even-diff-face-B -@vindex ediff-even-diff-face-C -@vindex ediff-odd-diff-face-A -@vindex ediff-odd-diff-face-B -@vindex ediff-odd-diff-face-C -Non-current difference regions are displayed using these alternating -faces. The odd and the even faces are actually identical on monochrome -displays, because without colors options are limited. -So, Ediff uses italics to highlight non-current differences. - -@item ediff-force-faces -@vindex ediff-force-faces -Ediff generally can detect when Emacs is running on a device where it can -use highlighting with faces. However, if it fails to determine that faces -can be used, the user can set this variable to @code{t} to make sure that -Ediff uses faces to highlight differences. - -@item ediff-highlight-all-diffs -@vindex ediff-highlight-all-diffs -Indicates whether---on a windowing display---Ediff should highlight -differences using inserted strings (as on text-only terminals) or using -colors and highlighting. Normally, Ediff highlights all differences, but -the selected difference is highlighted more visibly. One can cycle through -various modes of highlighting by typing @kbd{h}. By default, Ediff starts -in the mode where all difference regions are highlighted. If you prefer to -start in the mode where unselected differences are not highlighted, you -should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to -restore highlighting for all differences. - -Ediff lets you switch between the two modes of highlighting. That is, -you can switch interactively from highlighting using faces to -highlighting using string flags, and back. Of course, switching has -effect only under a windowing system. On a text-only terminal or in an -xterm window, the only available option is highlighting with strings. -@end table - -@noindent -If you want to change the default settings for @code{ediff-force-faces} and -@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is -loaded. - -You can also change the defaults for the faces used to highlight the -difference regions. There are two ways to do this. The simplest and the -preferred way is to use the customization widget accessible from the -menubar. Ediff's customization group is located under "Tools", which in -turn is under "Programming". The faces that are used to highlight -difference regions are located in the "Highlighting" subgroup of the Ediff -customization group. - -The second, much more arcane, method to change default faces is to include -some Lisp code in @file{~/.emacs}. For instance, - -@example -(setq ediff-current-diff-face-A - (copy-face 'bold-italic 'ediff-current-diff-face-A)) -@end example - -@noindent -would use the pre-defined face @code{bold-italic} to highlight the current -difference region in buffer A (this face is not a good choice, by the way). - -If you are unhappy with just @emph{some} of the aspects of the default -faces, you can modify them when Ediff is being loaded using -@code{ediff-load-hook}. For instance: - -@smallexample -(add-hook 'ediff-load-hook - (lambda () - (set-face-foreground - ediff-current-diff-face-B "blue") - (set-face-background - ediff-current-diff-face-B "red") - (make-face-italic - ediff-current-diff-face-B))) -@end smallexample - -@strong{Please note:} to set Ediff's faces, use only @code{copy-face} -or @code{set/make-face-@dots{}} as shown above. Emacs' low-level -face-manipulation functions should be avoided. - -@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization -@section Narrowing - -If buffers being compared are narrowed at the time of invocation of -Ediff, @code{ediff-buffers} will preserve the narrowing range. However, -if @code{ediff-files} is invoked on the files visited by these buffers, -that would widen the buffers, since this command is defined to compare the -entire files. - -Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or -the corresponding @samp{-wordwise} commands, narrows the variants to the -particular regions being compared. The original accessible ranges are -restored when you quit Ediff. During the command, you can toggle this -narrowing on and off with the @kbd{%} command. - -These two variables control this narrowing behavior: - -@table @code -@item ediff-start-narrowed -@vindex ediff-start-narrowed -If @code{t}, Ediff narrows the display to the appropriate range when it -is invoked with an @samp{ediff-regions@dots{}} or -@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do -not automatically narrow, but you can still toggle narrowing on and off -by typing @kbd{%}. - -@item ediff-quit-widened -@vindex ediff-quit-widened -Controls whether on quitting Ediff should restore the accessible range -that existed before the current invocation. -@end table - -@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization -@section Refinement of Difference Regions - -Ediff has variables to control the way fine differences are -highlighted. This feature gives you control over the process of refinement. -Note that refinement ignores spaces, tabs, and newlines. - -@table @code -@item ediff-auto-refine -@vindex ediff-auto-refine -This variable controls whether fine differences within regions are -highlighted automatically (``auto-refining''). The default is yes -(@samp{on}). - -On a slow machine, automatic refinement may be painful. In that case, -you can turn auto-refining on or off interactively by typing -@kbd{@@}. You can also turn off display of refining that has -already been done. - -When auto-refining is off, fine differences are shown only for regions -for which these differences have been computed and saved before. If -auto-refining and display of refining are both turned off, fine -differences are not shown at all. - -Typing @kbd{*} computes and displays fine differences for the current -difference region, regardless of whether auto-refining is turned on. - -@item ediff-auto-refine-limit -@vindex ediff-auto-refine-limit -If auto-refining is on, this variable limits the size of the regions to -be auto-refined. This guards against the possible slowdown that may be -caused by extraordinary large difference regions. - -You can always refine the current region by typing @kbd{*}. - -@item ediff-forward-word-function -@vindex ediff-forward-word-function -This variable controls how fine differences are computed. The -value must be a Lisp function that determines how the current difference -region should be split into words. - -@vindex ediff-diff-program -@vindex ediff-forward-word-function -@findex ediff-forward-word -Fine differences are computed by first splitting the current difference -region into words and then passing the result to -@code{ediff-diff-program}. For the default forward word function (which is -@code{ediff-forward-word}), a word is a string consisting of letters, -@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits, -or a string consisting of symbols that are neither space, nor a letter. - -This default behavior is controlled by four variables: @code{ediff-word-1}, -..., @code{ediff-word-4}. See the on-line documentation for these variables -and for the function @code{ediff-forward-word} for an explanation of how to -modify these variables. -@vindex ediff-word-1 -@vindex ediff-word-2 -@vindex ediff-word-3 -@vindex ediff-word-4 -@end table - -Sometimes, when a region has too many differences between the variants, -highlighting of fine differences is inconvenient, especially on -color displays. If that is the case, type @kbd{*} with a negative -prefix argument. This unhighlights fine differences for the current -region. - -To unhighlight fine differences in all difference regions, use the -command @kbd{@@}. Repeated typing of this key cycles through three -different states: auto-refining, no-auto-refining, and no-highlighting -of fine differences. - -@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization -@section Patch and Diff Programs - -This section describes variables that specify the programs to be used for -applying patches and for computing the main difference regions (not the -fine difference regions): - -@table @code -@item ediff-diff-program -@itemx ediff-diff3-program -@vindex ediff-patch-program -@vindex ediff-diff-program -@vindex ediff-diff3-program -These variables specify the programs to use to produce differences -and do patching. - -@item ediff-diff-options -@itemx ediff-diff3-options -@vindex ediff-patch-options -@vindex ediff-diff-options -@vindex ediff-diff3-options -These variables specify the options to pass to the above utilities. - -In @code{ediff-diff-options}, it may be useful to specify options -such as @samp{-w} that ignore certain kinds of changes. However, -Ediff does not let you use the option @samp{-c}, as it doesn't recognize this -format yet. - -@item ediff-coding-system-for-read -@vindex ediff-coding-system-for-read -This variable specifies the coding system to use when reading the output -that the programs @code{diff3} and @code{diff} send to Emacs. The default -is @code{raw-text}, and this should work fine in Unix and in most -cases under Windows NT/95/98/2000. There are @code{diff} programs -for which the default option doesn't work under Windows. In such cases, -@code{raw-text-dos} might work. If not, you will have to experiment with -other coding systems or use GNU diff. - -@item ediff-patch-program -The program to use to apply patches. Since there are certain -incompatibilities between the different versions of the patch program, the -best way to stay out of trouble is to use a GNU-compatible version. -Otherwise, you may have to tune the values of the variables -@code{ediff-patch-options}, @code{ediff-backup-specs}, and -@code{ediff-backup-extension} as described below. -@item ediff-patch-options -Options to pass to @code{ediff-patch-program}. - -Note: the `-b' and `-z' options should be specified in -`ediff-backup-specs', not in @code{ediff-patch-options}. - -It is recommended to pass the `-f' option to the patch program, so it won't -ask questions. However, some implementations don't accept this option, in -which case the default value of this variable should be changed. - -@item ediff-backup-extension -Backup extension used by the patch program. Must be specified, even if -@code{ediff-backup-specs} is given. -@item ediff-backup-specs -Backup directives to pass to the patch program. -Ediff requires that the old version of the file (before applying the patch) -is saved in a file named @file{the-patch-file.extension}. Usually -`extension' is `.orig', but this can be changed by the user, and may also be -system-dependent. Therefore, Ediff needs to know the backup extension used -by the patch program. - -Some versions of the patch program let the user specify `-b backup-extension'. -Other versions only permit `-b', which (usually) assumes the extension `.orig'. -Yet others force you to use `-z'. - -Note that both `ediff-backup-extension' and `ediff-backup-specs' must be -properly set. If your patch program takes the option `-b', but not -`-b extension', the variable `ediff-backup-extension' must still -be set so Ediff will know which extension to use. - -@item ediff-custom-diff-program -@itemx ediff-custom-diff-options -@vindex ediff-custom-diff-program -@vindex ediff-custom-diff-options -@findex ediff-save-buffer -Because Ediff limits the options you may want to pass to the @code{diff} -program, it partially makes up for this drawback by letting you save the -output from @code{diff} in your preferred format, which is specified via -the above two variables. - -The output generated by @code{ediff-custom-diff-program} (which doesn't -even have to be a standard-style @code{diff}!)@: is not used by Ediff. It is -provided exclusively so that you can -refer to -it later, send it over email, etc. For instance, after reviewing the -differences, you may want to send context differences to a colleague. -Since Ediff ignores the @samp{-c} option in -@code{ediff-diff-program}, you would have to run @code{diff -c} separately -just to produce the list of differences. Fortunately, -@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options} -eliminate this nuisance by keeping a copy of a difference list in the -desired format in a buffer that can be displayed via the command @kbd{D}. - -@item ediff-patch-default-directory -@vindex ediff-patch-default-directory -Specifies the default directory to look for patches. - -@end table - -@noindent -@strong{Warning:} Ediff does not support the output format of VMS -@code{diff}. Instead, make sure you are using some implementation of POSIX -@code{diff}, such as @code{gnudiff}. - -@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization -@section Merging and diff3 - -Ediff supports three-way comparison via the functions @code{ediff-files3} and -@code{ediff-buffers3}. The interface is the same as for two-way comparison. -In three-way comparison and merging, Ediff reports if any two difference -regions are identical. For instance, if the current region in buffer A -is the same as the region in buffer C, then the mode line of buffer A will -display @samp{[=diff(C)]} and the mode line of buffer C will display -@samp{[=diff(A)]}. - -Merging is done according to the following algorithm. - -If a difference region in one of the buffers, say B, differs from the ancestor -file while the region in the other buffer, A, doesn't, then the merge buffer, -C, gets B's region. Similarly when buffer A's region differs from -the ancestor and B's doesn't, A's region is used. - -@vindex ediff-default-variant -If both regions in buffers A and B differ from the ancestor file, Ediff -chooses the region according to the value of the variable -@code{ediff-default-variant}. If its value is @code{default-A} then A's -region is chosen. If it is @code{default-B} then B's region is chosen. -If it is @code{combined} then the region in buffer C will look like -this: - -@comment Use @set to avoid triggering merge conflict detectors like CVS. -@set seven-left <<<<<<< -@set seven-right >>>>>>> -@example -@value{seven-left} variant A -the difference region from buffer A -@value{seven-right} variant B -the difference region from buffer B -####### Ancestor -the difference region from the ancestor buffer, if available -======= end -@end example - -The above is the default template for the combined region. The user can -customize this template using the variable -@code{ediff-combination-pattern}. - -@vindex ediff-combination-pattern -The variable @code{ediff-combination-pattern} specifies the template that -determines how the combined merged region looks like. The template is -represented as a list of the form @code{(STRING1 Symbol1 STRING2 Symbol2 -STRING3 Symbol3 STRING4)}. The symbols here must be atoms of the form -@code{A}, @code{B}, or @code{Ancestor}. They determine the order in which -the corresponding difference regions (from buffers A, B, and the ancestor -buffer) are displayed in the merged region of buffer C. The strings in the -template determine the text that separates the aforesaid regions. The -default template is - -@smallexample -("@value{seven-left} variant A" A "@value{seven-right} variant B" B - "####### Ancestor" Ancestor "======= end") -@end smallexample - -@noindent -(this is one long line) and the corresponding combined region is shown -above. The order in which the regions are shown (and the separator -strings) can be changed by changing the above template. It is even -possible to add or delete region specifiers in this template (although -the only possibly useful such modification seems to be the deletion of -the ancestor). - -In addition to the state of the difference, Ediff displays the state of the -merge for each region. If a difference came from buffer A by default -(because both regions A and B were different from the ancestor and -@code{ediff-default-variant} was set to @code{default-A}) then -@samp{[=diff(A) default-A]} is displayed in the mode line. If the -difference in buffer C came, say, from buffer B because the difference -region in that buffer differs from the ancestor, but the region in buffer A -does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is -displayed. The indicators default-A/B and prefer-A/B are inspired by -Emerge and have the same meaning. - -Another indicator of the state of merge is @samp{combined}. It appears -with any difference region in buffer C that was obtained by combining -the difference regions in buffers A and B as explained above. - -In addition to the state of merge and state of difference indicators, while -merging with an ancestor file or buffer, Ediff informs the user when the -current difference region in the (normally invisible) ancestor buffer is -empty via the @emph{AncestorEmpty} indicator. This helps determine if the -changes made to the original in variants A and B represent pure insertion -or deletion of text: if the mode line shows @emph{AncestorEmpty} and the -corresponding region in buffers A or B is not empty, this means that new -text was inserted. If this indicator is not present and the difference -regions in buffers A or B are non-empty, this means that text was -modified. Otherwise, the original text was deleted. - -Although the ancestor buffer is normally invisible, Ediff maintains -difference regions there and advances the current difference region -accordingly. All highlighting of difference regions is provided in the -ancestor buffer, except for the fine differences. Therefore, if desired, the -user can put the ancestor buffer in a separate frame and watch it -there. However, on a TTY, only one frame can be visible at any given time, -and Ediff doesn't support any single-frame window configuration where all -buffers, including the ancestor buffer, would be visible. However, the -ancestor buffer can be displayed by typing @kbd{/} to the control -window. (Type @kbd{C-l} to hide it again.) - -Note that the state-of-difference indicators @samp{=diff(A)} and -@samp{=diff(B)} above are not redundant, even in the presence of a -state-of-merge indicator. In fact, the two serve different purposes. - -For instance, if the mode line displays @samp{=diff(B) prefer(B)} and -you copy a difference region from buffer A to buffer C then -@samp{=diff(B)} will change to @samp{diff-A} and the mode line will -display @samp{=diff(A) prefer-B}. This indicates that the difference -region in buffer C is identical to that in buffer A, but originally -buffer C's region came from buffer B. This is useful to know because -you can recover the original difference region in buffer C by typing -@kbd{r}. - - -Ediff never changes the state-of-merge indicator, except in response to -the @kbd{!} command (see below), in which case the indicator is lost. -On the other hand, the state-of-difference indicator is changed -automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r}, -@kbd{+}. - -The @kbd{!} command loses the information about origins of the regions -in the merge buffer (default-A, prefer-B, or combined). This is because -recomputing differences in this case means running @code{diff3} on -buffers A, B, and the merge buffer, not on the ancestor buffer. (It -makes no sense to recompute differences using the ancestor file, since -in the merging mode Ediff assumes that you have not edited buffers A and -B, but that you may have edited buffer C, and these changes are to be -preserved.) Since some difference regions may disappear as a result of -editing buffer C and others may arise, there is generally no simple way -to tell where the various regions in the merge buffer came from. - -In three-way comparison, Ediff tries to disregard regions that consist -entirely of white space. For instance, if, say, the current region in -buffer A consists of the white space only (or if it is empty), Ediff will -not take it into account for the purpose of computing fine differences. The -result is that Ediff can provide a better visual information regarding the -actual fine differences in the non-white regions in buffers B and -C. Moreover, if the regions in buffers B and C differ in the white space -only, then a message to this effect will be displayed. - -@vindex ediff-merge-window-share -In the merge mode, the share of the split between window C (the window -displaying the merge-buffer) and the windows displaying buffers A and B -is controlled by the variable @code{ediff-merge-window-share}. Its -default value is 0.5. To make the merge-buffer window smaller, reduce -this amount. - -We don't recommend increasing the size of the merge-window to more than -half the frame (i.e., to increase the value of -@code{ediff-merge-window-share}) to more than 0.5, since it would be -hard to see the contents of buffers A and B. - -You can temporarily shrink the merge window to just one line by -typing @kbd{s}. This change is temporary, until Ediff finds a reason to -redraw the screen. Typing @kbd{s} again restores the original window size. - -With a positive prefix argument, the @kbd{s} command will make the merge -window slightly taller. This change is persistent. With `@kbd{-}' or -with a negative prefix argument, the command @kbd{s} makes the merge -window slightly shorter. This change also persistent. - -@vindex ediff-show-clashes-only -Ediff lets you automatically ignore the regions where only one of the -buffers A and B disagrees with the ancestor. To do this, set the -variable @code{ediff-show-clashes-only} to non-@code{nil}. - -You can toggle this feature interactively by typing @kbd{$$}. - -Note that this variable affects only the show next/previous difference -commands. You can still jump directly to any difference region directly -using the command @kbd{j} (with a prefix argument specifying the difference -number). - -@vindex ediff-autostore-merges -@vindex ediff-quit-merge-hook -@findex ediff-maybe-save-and-delete-merge -The variable @code{ediff-autostore-merges} controls what happens to the -merge buffer when Ediff quits. If the value is @code{nil}, nothing is done -to the merge buffer---it will be the user's responsibility to save it. -If the value is @code{t}, the user will be asked where to save the buffer -and whether to delete it afterwards. It the value is neither @code{nil} nor -@code{t}, the merge buffer is saved @emph{only} if this merge session was -invoked from a group of related Ediff session, such as those that result -from @code{ediff-merge-directories}, -@code{ediff-merge-directory-revisions}, etc. -@xref{Session Groups}. This behavior is implemented in the function -@code{ediff-maybe-save-and-delete-merge}, which is a hook in -@code{ediff-quit-merge-hook}. The user can supply a different hook, if -necessary. - -The variable @code{ediff-autostore-merges} is buffer-local, so it can be -set in a per-buffer manner. Therefore, use @code{setq-default} to globally -change this variable. - -@vindex ediff-merge-filename-prefix -When merge buffers are saved automatically as directed by -@code{ediff-autostore-merges}, Ediff attaches a prefix to each file, as -specified by the variable @code{ediff-merge-filename-prefix}. The default -is @code{merge_}, but this can be changed by the user. - -@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization -@section Support for Version Control - - -Ediff supports version control and lets you compare versions of files -visited by Emacs buffers via the function @code{ediff-revision}. This -feature is controlled by the following variables: - -@table @code -@item ediff-version-control-package -@vindex ediff-version-control-package -A symbol. The default is @samp{vc}. - -If you are like most Emacs users, Ediff will use VC as the version control -package. This is the standard Emacs interface to RCS, CVS, and SCCS. - -However, if your needs are better served by other interfaces, you will -have to tell Ediff which version control package you are using, e.g., -@example -(setq ediff-version-control-package 'rcs) -@end example - -Apart from the standard @file{vc.el}, Ediff supports three other interfaces -to version control: @file{rcs.el}, @file{pcl-cvs.el} (recently renamed -pcvs.el), and @file{generic-sc.el}. The package @file{rcs.el} is written -by Sebastian Kremer and is available as -@example -@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z} -@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z} -@end example -@pindex @file{vc.el} -@pindex @file{rcs.el} -@pindex @file{pcl-cvs.el} -@pindex @file{generic-sc.el} -@end table - -Ediff's interface to the above packages allows the user to compare the -versions of the current buffer or to merge them (with or without an -ancestor-version). These operations can also be performed on directories -containing files under version control. - -In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function -@code{run-ediff-from-cvs-buffer}---see the documentation string for this -function. - -@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization -@section Customizing the Mode Line - -When Ediff is running, the mode line of @samp{Ediff Control Panel} -buffer shows the current difference number and the total number of -difference regions in the two files. - -The mode line of the buffers being compared displays the type of the -buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name. -Ediff tries to be intelligent in choosing the mode line buffer -identification. In particular, it works well with the -@file{uniquify.el} and @file{mode-line.el} packages (which improve on -the default way in which Emacs displays buffer identification). If you -don't like the way Ediff changes the mode line, you can use -@code{ediff-prepare-buffer-hook} to modify the mode line. -@vindex ediff-prepare-buffer-hook -@pindex @file{uniquify.el} -@pindex @file{mode-line.el} - -@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization -@section Miscellaneous - -Here are a few other variables for customizing Ediff: - -@table @code -@item ediff-split-window-function -@vindex ediff-split-window-function -Controls the way you want the window be split between file-A and file-B -(and file-C, if applicable). It defaults to the vertical split -(@code{split-window-vertically}, but you can set it to -@code{split-window-horizontally}, if you so wish. -Ediff also lets you switch from vertical to horizontal split and back -interactively. - -Note that if Ediff detects that all the buffers it compares are displayed in -separate frames, it assumes that the user wants them to be so displayed -and stops splitting windows. Instead, it arranges for each buffer to -be displayed in a separate frame. You can switch to the one-frame mode -by hiding one of the buffers A/B/C. - -You can also swap the windows where buffers are displayed by typing -@kbd{~}. - -@item ediff-merge-split-window-function -@vindex ediff-merge-split-window-function -Controls how windows are -split between buffers A and B in the merge mode. -This variable is like @code{ediff-split-window-function}, but it defaults -to @code{split-window-horizontally} instead of -@code{split-window-vertically}. - -@item ediff-make-wide-display-function -@vindex ediff-make-wide-display-function -The value is a function to be called to widen the frame for displaying -the Ediff buffers. See the on-line documentation for -@code{ediff-make-wide-display-function} for details. It is also -recommended to look into the source of the default function -@code{ediff-make-wide-display}. - -You can toggle wide/regular display by typing @kbd{m}. In the wide -display mode, buffers A, B (and C, when applicable) are displayed in a -single frame that is as wide as the entire workstation screen. This is -useful when files are compared side-by-side. By default, the display is -widened without changing its height. - -@item ediff-use-last-dir -@vindex ediff-use-last-dir -Controls the way Ediff presents the -default directory when it prompts the user for files to compare. If -@code{nil}, -Ediff uses the default directory of the current buffer when it -prompts the user for file names. Otherwise, it will use the -directories it had previously used for files A, B, or C, respectively. - -@item ediff-no-emacs-help-in-control-buffer -@vindex ediff-no-emacs-help-in-control-buffer -If @code{t}, makes @kbd{C-h} -behave like the @key{DEL} key, i.e., it will move you back to the previous -difference rather than invoking help. This is useful when, in an xterm -window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is -positioned more conveniently than the @key{DEL} key. - -@item ediff-toggle-read-only-function -@vindex ediff-toggle-read-only-function -This variable's value is a function that Ediff uses to toggle -the read-only property in its buffers. - -The default function that Ediff uses simply toggles the read-only property, -unless the file is under version control. For a checked-in file under -version control, Ediff first tries to check the file out. - -@item ediff-make-buffers-readonly-at-startup nil -@vindex ediff-make-buffers-readonly-at-startup -If @code{t}, all variant buffers are made read-only at Ediff startup. - -@item ediff-keep-variants -@vindex @code{ediff-keep-variants} -The default is @code{t}, meaning that the buffers being compared or merged will -be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to -offer the user a chance to delete these buffers (if they are not modified). -Supplying a prefix argument to the quit command (@code{q}) temporarily -reverses the meaning of this variable. This is convenient when the user -prefers one of the behaviors most of the time, but occasionally needs the -other behavior. - -However, Ediff temporarily resets this variable to @code{t} if it is -invoked via one of the "buffer" jobs, such as @code{ediff-buffers}. -This is because it is all too easy to loose day's work otherwise. -Besides, in a "buffer" job, the variant buffers have already been loaded -prior to starting Ediff, so Ediff just preserves status quo here. - -Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants -unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). - -@item ediff-keep-tmp-versions -@vindex @code{ediff-keep-tmp-versions} -Default is @code{nil}. If @code{t}, the versions of the files being -compared or merged using operations such as @code{ediff-revision} or -@code{ediff-merge-revisions} are not deleted on exit. The normal action is -to clean up and delete these version files. - -@item ediff-grab-mouse -@vindex @code{ediff-grab-mouse} -Default is @code{t}. Normally, Ediff grabs mouse and puts it in its -control frame. This is useful since the user can be sure that when he -needs to type an Ediff command the focus will be in an appropriate Ediff's -frame. However, some users prefer to move the mouse by themselves. The -above variable, if set to @code{maybe}, will prevent Ediff from grabbing -the mouse in many situations, usually after commands that may take more -time than usual. In other situation, Ediff will continue grabbing the mouse -and putting it where it believes is appropriate. If the value is -@code{nil}, then mouse is entirely user's responsibility. -Try different settings and see which one is for you. -@end table - - -@node Notes on Heavy-duty Customization, , Miscellaneous, Customization -@section Notes on Heavy-duty Customization - -Some users need to customize Ediff in rather sophisticated ways, which -requires different defaults for different kinds of files (e.g., SGML, -etc.). Ediff supports this kind of customization in several ways. First, -most customization variables are buffer-local. Those that aren't are -usually accessible from within Ediff Control Panel, so one can make them -local to the panel by calling make-local-variable from within -@code{ediff-startup-hook}. - -Second, the function @code{ediff-setup} accepts an optional sixth -argument which has the form @code{((@var{var-name-1} .@: @var{val-1}) -(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function -@code{ediff-setup} sets the variables in the list to the respective -values, locally in the Ediff control buffer. This is an easy way to -throw in custom variables (which usually should be buffer-local) that -can then be tested in various hooks. - -Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set -properly in this case, as some things in Ediff depend on this. - -Finally, if you want custom-tailored help messages, you can set the -variables @code{ediff-brief-help-message-function} and -@code{ediff-long-help-message-function} -to functions that return help strings. -@vindex ediff-startup-hook -@findex ediff-setup -@vindex ediff-job-name -@vindex ediff-word-mode -@vindex ediff-brief-help-message-function -@vindex ediff-long-help-message-function - -When customizing Ediff, some other variables are useful, although they are -not user-definable. They are local to the Ediff control buffer, so this -buffer must be current when you access these variables. The control buffer -is accessible via the variable @code{ediff-control-buffer}, which is also -local to that buffer. It is usually used for checking if the current buffer -is also the control buffer. - -Other variables of interest are: -@table @code -@item ediff-buffer-A -The first of the data buffers being compared. - -@item ediff-buffer-B -The second of the data buffers being compared. - -@item ediff-buffer-C -In three-way comparisons, this is the third buffer being compared. -In merging, this is the merge buffer. -In two-way comparison, this variable is @code{nil}. - -@item ediff-window-A -The window displaying buffer A. If buffer A is not visible, this variable -is @code{nil} or it may be a dead window. - -@item ediff-window-B -The window displaying buffer B. - -@item ediff-window-C -The window displaying buffer C, if any. - -@item ediff-control-frame -A dedicated frame displaying the control buffer, if it exists. It is -non-@code{nil} only if Ediff uses the multiframe display, i.e., when -the control buffer is in its own frame. -@end table - -@node Credits, GNU Free Documentation License, Customization, Top -@chapter Credits - -Ediff was written by Michael Kifer . It was inspired -by emerge.el written by Dale R.@: Worley . An idea due to -Boris Goldowsky made it possible to highlight -fine differences in Ediff buffers. Alastair Burt -ported Ediff to XEmacs, Eric Freudenthal -made it work with VC, Marc Paquette wrote the -toolbar support package for Ediff, and Hrvoje Niksic -adapted it to the Emacs customization package. - -Many people provided help with bug reports, feature suggestions, and advice. -Without them, Ediff would not be nearly as useful as it is today. -Here is a hopefully full list of contributors: - -@example -Adrian Aichner (aichner@@ecf.teradyne.com), -Drew Adams (drew.adams@@oracle.com), -Steve Baur (steve@@xemacs.org), -Neal Becker (neal@@ctd.comsat.com), -E.@: Jay Berkenbilt (ejb@@ql.org), -Alastair Burt (burt@@dfki.uni-kl.de), -Paul Bibilo (peb@@delcam.co.uk), -Kevin Broadey (KevinB@@bartley.demon.co.uk), -Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de), -Bradley A.@: Bosch (brad@@lachman.com), -Michael D.@: Carney (carney@@ltx-tr.com), -Jin S.@: Choi (jin@@atype.com), -Scott Cummings (cummings@@adc.com), -Albert Dvornik (bert@@mit.edu), -Eric Eide (eeide@@asylum.cs.utah.edu), -Paul Eggert (eggert@@twinsun.com), -Urban Engberg (ue@@cci.dk), -Kevin Esler (esler@@ch.hp.com), -Robert Estes (estes@@ece.ucdavis.edu), -Jay Finger (jayf@@microsoft.com), -Xavier Fornari (xavier@@europe.cma.fr), -Eric Freudenthal (freudent@@jan.ultra.nyu.edu), -Job Ganzevoort (Job.Ganzevoort@@cwi.nl), -Felix Heinrich Gatzemeier (felix.g@@tzemeier.info), -Boris Goldowsky (boris@@cs.rochester.edu), -Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu), -Aaron Gross (aaron@@bfr.co.il), -Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de), -Marcus Harnisch (marcus_harnisch@@mint-tech.com), -Steven E. Harris (seh@@panix.com), -Aaron S. Hawley (Aaron.Hawley@@uvm.edu), -Xiaoli Huang (hxl@@epic.com), -Andreas Jaeger (aj@@suse.de), -Lars Magne Ingebrigtsen (larsi@@ifi.uio.no), -Larry Gouge (larry@@itginc.com), -Karl Heuer (kwzh@@gnu.org), -(irvine@@lks.csi.com), -(jaffe@@chipmunk.cita.utoronto.ca), -David Karr (dkarr@@nmo.gtegsc.com), -Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de), -Steffen Kilb (skilb@@gmx.net), -Leigh L Klotz (klotz@@adoc.xerox.com), -Fritz Knabe (Fritz.Knabe@@ecrc.de), -Heinz Knutzen (hk@@informatik.uni-kiel.d400.de), -Andrew Koenig (ark@@research.att.com), -Hannu Koivisto (azure@@iki.fi), -Ken Laprade (laprade@@dw3f.ess.harris.com), -Will C Lauer (wcl@@cadre.com), -Richard Levitte (levitte@@e.kth.se), -Mike Long (mike.long@@analog.com), -Dave Love (d.love@@dl.ac.uk), -Martin Maechler (maechler@@stat.math.ethz.ch), -Simon Marshall (simon@@gnu.org), -Paul C. Meuse (pmeuse@@delcomsys.com), -Richard Mlynarik (mly@@adoc.xerox.com), -Stefan Monnier (monnier@@cs.yale.edu), -Chris Murphy (murphycm@@sun.aston.ac.uk), -Erik Naggum (erik@@naggum.no), -Eyvind Ness (Eyvind.Ness@@hrp.no), -Ray Nickson (nickson@@cs.uq.oz.au), -Dan Nicolaescu (dann@@ics.uci.edu), -David Petchey (petchey_david@@jpmorgan.com), -Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk), -Francois Pinard (pinard@@iro.umontreal.ca), -Tibor Polgar (tlp00@@spg.amdahl.com), -David Prince (dave0d@@fegs.co.uk), -Paul Raines (raines@@slac.stanford.edu), -Stefan Reicher (xsteve@@riic.at), -Charles Rich (rich@@merl.com), -Bill Richter (richter@@math.nwu.edu), -C.S.@: Roberson (roberson@@aur.alcatel.com), -Kevin Rodgers (kevin.rodgers@@ihs.com), -Sandy Rutherford (sandy@@ibm550.sissa.it), -Heribert Schuetz (schuetz@@ecrc.de), -Andy Scott (ascott@@pcocd2.intel.com), -Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de), -Vin Shelton (acs@@xemacs.org), -Scott O. Sherman (Scott.Sherman@@mci.com), -Nikolaj Schumacher (n_schumacher@@web.de), -Richard Stallman (rms@@gnu.org), -Richard Stanton (stanton@@haas.berkeley.edu), -Sam Steingold (sds@@goems.com), -Ake Stenhoff (etxaksf@@aom.ericsson.se), -Stig (stig@@hackvan.com), -Peter Stout (Peter_Stout@@cs.cmu.edu), -Chuck Thompson (cthomp@@cs.uiuc.edu), -Ray Tomlinson (tomlinso@@bbn.com), -Raymond Toy (toy@@rtp.ericsson.se), -Stephen J. Turnbull (stephen@@xemacs.org), -Jan Vroonhof (vroonhof@@math.ethz.ch), -Colin Walters (walters@@cis.ohio-state.edu), -Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be), -Klaus Weber (gizmo@@zork.north.de), -Ben Wing (ben@@xemacs.org), -Tom Wurgler (twurgler@@goodyear.com), -Steve Youngs (youngs@@xemacs.org), -Ilya Zakharevich (ilya@@math.ohio-state.edu), -Eli Zaretskii (eliz@@is.elta.co.il) -@end example - -@node GNU Free Documentation License, Index, Credits, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: 165ecb88-d03c-44b1-a921-b93f50b05b46 -@end ignore diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi deleted file mode 100644 index e9a03595502..00000000000 --- a/doc/misc/emacs-mime.texi +++ /dev/null @@ -1,1892 +0,0 @@ -\input texinfo - -@setfilename ../../info/emacs-mime -@settitle Emacs MIME Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs MIME interface functionality. - -Copyright @copyright{} 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, -2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c Node ``Interface Functions'' uses Latin-1 characters -@documentencoding ISO-8859-1 - -@dircategory Emacs -@direntry -* Emacs MIME: (emacs-mime). Emacs MIME de/composition library. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@title Emacs MIME Manual - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top Emacs MIME - -This manual documents the libraries used to compose and display -@acronym{MIME} messages. - -This manual is directed at users who want to modify the behavior of -the @acronym{MIME} encoding/decoding process or want a more detailed -picture of how the Emacs @acronym{MIME} library works, and people who want -to write functions and commands that manipulate @acronym{MIME} elements. - -@acronym{MIME} is short for @dfn{Multipurpose Internet Mail Extensions}. -This standard is documented in a number of RFCs; mainly RFC2045 (Format -of Internet Message Bodies), RFC2046 (Media Types), RFC2047 (Message -Header Extensions for Non-@acronym{ASCII} Text), RFC2048 (Registration -Procedures), RFC2049 (Conformance Criteria and Examples). It is highly -recommended that anyone who intends writing @acronym{MIME}-compliant software -read at least RFC2045 and RFC2047. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Decoding and Viewing:: A framework for decoding and viewing. -* Composing:: @acronym{MML}; a language for describing @acronym{MIME} parts. -* Interface Functions:: An abstraction over the basic functions. -* Basic Functions:: Utility and basic parsing functions. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Decoding and Viewing -@chapter Decoding and Viewing - -This chapter deals with decoding and viewing @acronym{MIME} messages on a -higher level. - -The main idea is to first analyze a @acronym{MIME} article, and then allow -other programs to do things based on the list of @dfn{handles} that are -returned as a result of this analysis. - -@menu -* Dissection:: Analyzing a @acronym{MIME} message. -* Non-MIME:: Analyzing a non-@acronym{MIME} message. -* Handles:: Handle manipulations. -* Display:: Displaying handles. -* Display Customization:: Variables that affect display. -* Files and Directories:: Saving and naming attachments. -* New Viewers:: How to write your own viewers. -@end menu - - -@node Dissection -@section Dissection - -The @code{mm-dissect-buffer} is the function responsible for dissecting -a @acronym{MIME} article. If given a multipart message, it will recursively -descend the message, following the structure, and return a tree of -@acronym{MIME} handles that describes the structure of the message. - -@node Non-MIME -@section Non-MIME -@vindex mm-uu-configure-list - -Gnus also understands some non-@acronym{MIME} attachments, such as -postscript, uuencode, binhex, yenc, shar, forward, gnatsweb, pgp, -diff. Each of these features can be disabled by add an item into -@code{mm-uu-configure-list}. For example, - -@lisp -(require 'mm-uu) -(add-to-list 'mm-uu-configure-list '(pgp-signed . disabled)) -@end lisp - -@table @code -@item postscript -@findex postscript -PostScript file. - -@item uu -@findex uu -Uuencoded file. - -@item binhex -@findex binhex -Binhex encoded file. - -@item yenc -@findex yenc -Yenc encoded file. - -@item shar -@findex shar -Shar archive file. - -@item forward -@findex forward -Non-@acronym{MIME} forwarded message. - -@item gnatsweb -@findex gnatsweb -Gnatsweb attachment. - -@item pgp-signed -@findex pgp-signed -@acronym{PGP} signed clear text. - -@item pgp-encrypted -@findex pgp-encrypted -@acronym{PGP} encrypted clear text. - -@item pgp-key -@findex pgp-key -@acronym{PGP} public keys. - -@item emacs-sources -@findex emacs-sources -@vindex mm-uu-emacs-sources-regexp -Emacs source code. This item works only in the groups matching -@code{mm-uu-emacs-sources-regexp}. - -@item diff -@vindex diff -@vindex mm-uu-diff-groups-regexp -Patches. This is intended for groups where diffs of committed files -are automatically sent to. It only works in groups matching -@code{mm-uu-diff-groups-regexp}. - -@item verbatim-marks -@cindex verbatim-marks -Slrn-style verbatim marks. - -@item LaTeX -@cindex LaTeX -LaTeX documents. It only works in groups matching -@code{mm-uu-tex-groups-regexp}. - -@end table - -@cindex text/x-verbatim -@c Is @vindex suitable for a face? -@vindex mm-uu-extract -Some inlined non-@acronym{MIME} attachments are displayed using the face -@code{mm-uu-extract}. By default, no @acronym{MIME} button for these -parts is displayed. You can force displaying a button using @kbd{K b} -(@code{gnus-summary-display-buttonized}) or add @code{text/x-verbatim} -to @code{gnus-buttonized-mime-types}, @xref{MIME Commands, ,MIME -Commands, gnus, Gnus Manual}. - -@node Handles -@section Handles - -A @acronym{MIME} handle is a list that fully describes a @acronym{MIME} -component. - -The following macros can be used to access elements in a handle: - -@table @code -@item mm-handle-buffer -@findex mm-handle-buffer -Return the buffer that holds the contents of the undecoded @acronym{MIME} -part. - -@item mm-handle-type -@findex mm-handle-type -Return the parsed @code{Content-Type} of the part. - -@item mm-handle-encoding -@findex mm-handle-encoding -Return the @code{Content-Transfer-Encoding} of the part. - -@item mm-handle-undisplayer -@findex mm-handle-undisplayer -Return the object that can be used to remove the displayed part (if it -has been displayed). - -@item mm-handle-set-undisplayer -@findex mm-handle-set-undisplayer -Set the undisplayer object. - -@item mm-handle-disposition -@findex mm-handle-disposition -Return the parsed @code{Content-Disposition} of the part. - -@item mm-get-content-id -Returns the handle(s) referred to by @code{Content-ID}. - -@end table - - -@node Display -@section Display - -Functions for displaying, removing and saving. - -@table @code -@item mm-display-part -@findex mm-display-part -Display the part. - -@item mm-remove-part -@findex mm-remove-part -Remove the part (if it has been displayed). - -@item mm-inlinable-p -@findex mm-inlinable-p -Say whether a @acronym{MIME} type can be displayed inline. - -@item mm-automatic-display-p -@findex mm-automatic-display-p -Say whether a @acronym{MIME} type should be displayed automatically. - -@item mm-destroy-part -@findex mm-destroy-part -Free all resources occupied by a part. - -@item mm-save-part -@findex mm-save-part -Offer to save the part in a file. - -@item mm-pipe-part -@findex mm-pipe-part -Offer to pipe the part to some process. - -@item mm-interactively-view-part -@findex mm-interactively-view-part -Prompt for a mailcap method to use to view the part. - -@end table - - -@node Display Customization -@section Display Customization - -@table @code - -@item mm-inline-media-tests -@vindex mm-inline-media-tests -This is an alist where the key is a @acronym{MIME} type, the second element -is a function to display the part @dfn{inline} (i.e., inside Emacs), and -the third element is a form to be @code{eval}ed to say whether the part -can be displayed inline. - -This variable specifies whether a part @emph{can} be displayed inline, -and, if so, how to do it. It does not say whether parts are -@emph{actually} displayed inline. - -@item mm-inlined-types -@vindex mm-inlined-types -This, on the other hand, says what types are to be displayed inline, if -they satisfy the conditions set by the variable above. It's a list of -@acronym{MIME} media types. - -@item mm-automatic-display -@vindex mm-automatic-display -This is a list of types that are to be displayed ``automatically'', but -only if the above variable allows it. That is, only inlinable parts can -be displayed automatically. - -@item mm-automatic-external-display -@vindex mm-automatic-external-display -This is a list of types that will be displayed automatically in an -external viewer. - -@item mm-keep-viewer-alive-types -@vindex mm-keep-viewer-alive-types -This is a list of media types for which the external viewer will not -be killed when selecting a different article. - -@item mm-attachment-override-types -@vindex mm-attachment-override-types -Some @acronym{MIME} agents create parts that have a content-disposition of -@samp{attachment}. This variable allows overriding that disposition and -displaying the part inline. (Note that the disposition is only -overridden if we are able to, and want to, display the part inline.) - -@item mm-discouraged-alternatives -@vindex mm-discouraged-alternatives -List of @acronym{MIME} types that are discouraged when viewing -@samp{multipart/alternative}. Viewing agents are supposed to view the -last possible part of a message, as that is supposed to be the richest. -However, users may prefer other types instead, and this list says what -types are most unwanted. If, for instance, @samp{text/html} parts are -very unwanted, and @samp{text/richtext} parts are somewhat unwanted, -you could say something like: - -@lisp -(setq mm-discouraged-alternatives - '("text/html" "text/richtext") - mm-automatic-display - (remove "text/html" mm-automatic-display)) -@end lisp - -Adding @code{"image/.*"} might also be useful. Spammers use images as -the preferred part of @samp{multipart/alternative} messages, so you might -not notice there are other parts. See also -@code{gnus-buttonized-mime-types}, @ref{MIME Commands, ,MIME Commands, -gnus, Gnus Manual}. After adding @code{"multipart/alternative"} to -@code{gnus-buttonized-mime-types} you can choose manually which -alternative you'd like to view. For example, you can set those -variables like: - -@lisp -(setq gnus-buttonized-mime-types - '("multipart/alternative" "multipart/signed") - mm-discouraged-alternatives - '("text/html" "image/.*")) -@end lisp - -In this case, Gnus will display radio buttons for such a kind of spam -message as follows: - -@example -1. (*) multipart/alternative ( ) image/gif - -2. (*) text/plain ( ) text/html -@end example - -@item mm-inline-large-images -@vindex mm-inline-large-images -When displaying inline images that are larger than the window, Emacs -does not enable scrolling, which means that you cannot see the whole -image. To prevent this, the library tries to determine the image size -before displaying it inline, and if it doesn't fit the window, the -library will display it externally (e.g. with @samp{ImageMagick} or -@samp{xv}). Setting this variable to @code{t} disables this check and -makes the library display all inline images as inline, regardless of -their size. - -@item mm-inline-override-types -@vindex mm-inline-override-types -@code{mm-inlined-types} may include regular expressions, for example to -specify that all @samp{text/.*} parts be displayed inline. If a user -prefers to have a type that matches such a regular expression be treated -as an attachment, that can be accomplished by setting this variable to a -list containing that type. For example assuming @code{mm-inlined-types} -includes @samp{text/.*}, then including @samp{text/html} in this -variable will cause @samp{text/html} parts to be treated as attachments. - -@item mm-text-html-renderer -@vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{w3}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be -called with a @acronym{MIME} handle as the argument. - -@item mm-inline-text-html-with-images -@vindex mm-inline-text-html-with-images -Some @acronym{HTML} mails might have the trick of spammers using -@samp{} tags. It is likely to be intended to verify whether you -have read the mail. You can prevent your personal informations from -leaking by setting this option to @code{nil} (which is the default). -It is currently ignored by Emacs/w3. For emacs-w3m, you may use the -command @kbd{t} on the image anchor to show an image even if it is -@code{nil}.@footnote{The command @kbd{T} will load all images. If you -have set the option @code{w3m-key-binding} to @code{info}, use @kbd{i} -or @kbd{I} instead.} - -@item mm-w3m-safe-url-regexp -@vindex mm-w3m-safe-url-regexp -A regular expression that matches safe URL names, i.e. URLs that are -unlikely to leak personal information when rendering @acronym{HTML} -email (the default value is @samp{\\`cid:}). If @code{nil} consider -all URLs safe. - -@item mm-inline-text-html-with-w3m-keymap -@vindex mm-inline-text-html-with-w3m-keymap -You can use emacs-w3m command keys in the inlined text/html part by -setting this option to non-@code{nil}. The default value is @code{t}. - -@item mm-external-terminal-program -@vindex mm-external-terminal-program -The program used to start an external terminal. - -@item mm-enable-external -@vindex mm-enable-external -Indicate whether external @acronym{MIME} handlers should be used. - -If @code{t}, all defined external @acronym{MIME} handlers are used. If -@code{nil}, files are saved to disk (@code{mailcap-save-binary-file}). -If it is the symbol @code{ask}, you are prompted before the external -@acronym{MIME} handler is invoked. - -When you launch an attachment through mailcap (@pxref{mailcap}) an -attempt is made to use a safe viewer with the safest options---this isn't -the case if you save it to disk and launch it in a different way -(command line or double-clicking). Anyhow, if you want to be sure not -to launch any external programs, set this variable to @code{nil} or -@code{ask}. - -@end table - -@node Files and Directories -@section Files and Directories - -@table @code - -@item mm-default-directory -@vindex mm-default-directory -The default directory for saving attachments. If @code{nil} use -@code{default-directory}. - -@item mm-tmp-directory -@vindex mm-tmp-directory -Directory for storing temporary files. - -@item mm-file-name-rewrite-functions -@vindex mm-file-name-rewrite-functions -A list of functions used for rewriting file names of @acronym{MIME} -parts. Each function is applied successively to the file name. -Ready-made functions include - -@table @code -@item mm-file-name-delete-control -@findex mm-file-name-delete-control -Delete all control characters. - -@item mm-file-name-delete-gotchas -@findex mm-file-name-delete-gotchas -Delete characters that could have unintended consequences when used -with flawed shell scripts, i.e. @samp{|}, @samp{>} and @samp{<}; and -@samp{-}, @samp{.} as the first character. - -@item mm-file-name-delete-whitespace -@findex mm-file-name-delete-whitespace -Remove all whitespace. - -@item mm-file-name-trim-whitespace -@findex mm-file-name-trim-whitespace -Remove leading and trailing whitespace. - -@item mm-file-name-collapse-whitespace -@findex mm-file-name-collapse-whitespace -Collapse multiple whitespace characters. - -@item mm-file-name-replace-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace -Replace whitespace with underscores. Set the variable -@code{mm-file-name-replace-whitespace} to any other string if you do -not like underscores. -@end table - -The standard Emacs functions @code{capitalize}, @code{downcase}, -@code{upcase} and @code{upcase-initials} might also prove useful. - -@item mm-path-name-rewrite-functions -@vindex mm-path-name-rewrite-functions -List of functions used for rewriting the full file names of @acronym{MIME} -parts. This is used when viewing parts externally, and is meant for -transforming the absolute name so that non-compliant programs can find -the file where it's saved. - -@end table - -@node New Viewers -@section New Viewers - -Here's an example viewer for displaying @code{text/enriched} inline: - -@lisp -(defun mm-display-enriched-inline (handle) - (let (text) - (with-temp-buffer - (mm-insert-part handle) - (save-window-excursion - (enriched-decode (point-min) (point-max)) - (setq text (buffer-string)))) - (mm-insert-inline handle text))) -@end lisp - -We see that the function takes a @acronym{MIME} handle as its parameter. It -then goes to a temporary buffer, inserts the text of the part, does some -work on the text, stores the result, goes back to the buffer it was -called from and inserts the result. - -The two important helper functions here are @code{mm-insert-part} and -@code{mm-insert-inline}. The first function inserts the text of the -handle in the current buffer. It handles charset and/or content -transfer decoding. The second function just inserts whatever text you -tell it to insert, but it also sets things up so that the text can be -``undisplayed'' in a convenient manner. - - -@node Composing -@chapter Composing -@cindex Composing -@cindex MIME Composing -@cindex MML -@cindex MIME Meta Language - -Creating a @acronym{MIME} message is boring and non-trivial. Therefore, -a library called @code{mml} has been defined that parses a language -called @acronym{MML} (@acronym{MIME} Meta Language) and generates -@acronym{MIME} messages. - -@findex mml-generate-mime -The main interface function is @code{mml-generate-mime}. It will -examine the contents of the current (narrowed-to) buffer and return a -string containing the @acronym{MIME} message. - -@menu -* Simple MML Example:: An example @acronym{MML} document. -* MML Definition:: All valid @acronym{MML} elements. -* Advanced MML Example:: Another example @acronym{MML} document. -* Encoding Customization:: Variables that affect encoding. -* Charset Translation:: How charsets are mapped from @sc{mule} to @acronym{MIME}. -* Conversion:: Going from @acronym{MIME} to @acronym{MML} and vice versa. -* Flowed text:: Soft and hard newlines. -@end menu - - -@node Simple MML Example -@section Simple MML Example - -Here's a simple @samp{multipart/alternative}: - -@example -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched> -
This is a centered enriched part
-<#/multipart> -@end example - -After running this through @code{mml-generate-mime}, we get this: - -@example -Content-Type: multipart/alternative; boundary="=-=-=" - - ---=-=-= - - -This is a plain text part. - ---=-=-= -Content-Type: text/enriched - - -
This is a centered enriched part
- ---=-=-=-- -@end example - - -@node MML Definition -@section MML Definition - -The @acronym{MML} language is very simple. It looks a bit like an SGML -application, but it's not. - -The main concept of @acronym{MML} is the @dfn{part}. Each part can be of a -different type or use a different charset. The way to delineate a part -is with a @samp{<#part ...>} tag. Multipart parts can be introduced -with the @samp{<#multipart ...>} tag. Parts are ended by the -@samp{<#/part>} or @samp{<#/multipart>} tags. Parts started with the -@samp{<#part ...>} tags are also closed by the next open tag. - -There's also the @samp{<#external ...>} tag. These introduce -@samp{external/message-body} parts. - -Each tag can contain zero or more parameters on the form -@samp{parameter=value}. The values may be enclosed in quotation marks, -but that's not necessary unless the value contains white space. So -@samp{filename=/home/user/#hello$^yes} is perfectly valid. - -The following parameters have meaning in @acronym{MML}; parameters that have no -meaning are ignored. The @acronym{MML} parameter names are the same as the -@acronym{MIME} parameter names; the things in the parentheses say which -header it will be used in. - -@table @samp -@item type -The @acronym{MIME} type of the part (@code{Content-Type}). - -@item filename -Use the contents of the file in the body of the part -(@code{Content-Disposition}). - -@item charset -The contents of the body of the part are to be encoded in the character -set specified (@code{Content-Type}). @xref{Charset Translation}. - -@item name -Might be used to suggest a file name if the part is to be saved -to a file (@code{Content-Type}). - -@item disposition -Valid values are @samp{inline} and @samp{attachment} -(@code{Content-Disposition}). - -@item encoding -Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and -@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset -Translation}. - -@item description -A description of the part (@code{Content-Description}). - -@item creation-date -RFC822 date when the part was created (@code{Content-Disposition}). - -@item modification-date -RFC822 date when the part was modified (@code{Content-Disposition}). - -@item read-date -RFC822 date when the part was read (@code{Content-Disposition}). - -@item recipients -Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. - -@item sender -Identity used to sign the part. This field is used to override the -default key used. - -@item size -The size (in octets) of the part (@code{Content-Disposition}). - -@item sign -What technology to sign this @acronym{MML} part with (@code{smime}, @code{pgp} -or @code{pgpmime}) - -@item encrypt -What technology to encrypt this @acronym{MML} part with (@code{smime}, -@code{pgp} or @code{pgpmime}) - -@end table - -Parameters for @samp{text/plain}: - -@table @samp -@item format -Formatting parameter for the text, valid values include @samp{fixed} -(the default) and @samp{flowed}. Normally you do not specify this -manually, since it requires the textual body to be formatted in a -special way described in RFC 2646. @xref{Flowed text}. -@end table - -Parameters for @samp{application/octet-stream}: - -@table @samp -@item type -Type of the part; informal---meant for human readers -(@code{Content-Type}). -@end table - -Parameters for @samp{message/external-body}: - -@table @samp -@item access-type -A word indicating the supported access mechanism by which the file may -be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp}, -@samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.) - -@item expiration -The RFC822 date after which the file may no longer be fetched. -(@code{Content-Type}.) - -@item size -The size (in octets) of the file. (@code{Content-Type}.) - -@item permission -Valid values are @samp{read} and @samp{read-write} -(@code{Content-Type}). - -@end table - -Parameters for @samp{sign=smime}: - -@table @samp - -@item keyfile -File containing key and certificate for signer. - -@end table - -Parameters for @samp{encrypt=smime}: - -@table @samp - -@item certfile -File containing certificate for recipient. - -@end table - - -@node Advanced MML Example -@section Advanced MML Example - -Here's a complex multipart message. It's a @samp{multipart/mixed} that -contains many parts, one of which is a @samp{multipart/alternative}. - -@example -<#multipart type=mixed> -<#part type=image/jpeg filename=~/rms.jpg disposition=inline> -<#multipart type=alternative> -This is a plain text part. -<#part type=text/enriched name=enriched.txt> -
This is a centered enriched part
-<#/multipart> -This is a new plain text part. -<#part disposition=attachment> -This plain text part is an attachment. -<#/multipart> -@end example - -And this is the resulting @acronym{MIME} message: - -@example -Content-Type: multipart/mixed; boundary="=-=-=" - - ---=-=-= - - - ---=-=-= -Content-Type: image/jpeg; - filename="~/rms.jpg" -Content-Disposition: inline; - filename="~/rms.jpg" -Content-Transfer-Encoding: base64 - -/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof -Hh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAAwADABAREA/8QAHwAA -AQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQR -BRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RF -RkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ip -qrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEB -AAA/AO/rifFHjldNuGsrDa0qcSSHkA+gHrXKw+LtWLrMb+RgTyhbr+HSug07xNqV9fQtZrNI -AyiaE/NuBPOOOP0rvRNE880KOC8TbXXGCv1FPqjrF4LDR7u5L7SkTFT/ALWOP1xXgTuXfc7E -sx6nua6rwp4IvvEM8chCxWxOdzn7wz6V9AaB4S07w9p5itow0rDLSY5Pt9K43xO66P4xs71m -2QXiGCbA4yOVJ9+1aYORkdK434lyNH4ahCnG66VT9Nj15JFbPdX0MS43M4VQf5/yr2vSpLnw -5ZW8dlCZ8KFXjOPX0/mK6rSPEGt3Angu44fNEReHYNvIH3TzXDeKNO8RX+kSX2ouZkicTIOc -L+g7E810ulFjpVtv3bwgB3HJyK5L4quY/C9sVxk3ij/xx6850u7t1mtp/wDlpEw3An3Jr3Dw -34gsbWza4nBlhC5LDsaW6+IFgupQyCF3iHH7gA7c9R9ay7zx6t7aX9jHC4smhfBkGCvHGfrm -tLQ7hbnRrV1GPkAP1x1/Hr+Ncr8Vzjwrbf8AX6v/AKA9eQRyYlQk8Yx9K6XTNbkgia2ciSIn -7p5Ga9Atte0LTLKO6it4i7dVRFJDcZ4PvXN+JvEMF9bILVGXJLSZ4zkjivRPDaeX4b08HOTC -pOffmua+KkbS+GLVUGT9tT/0B68eeIpIFYjB70+OOVXyoOM9+M1eaWeCLzHPyHGO/NVWvJJm -jQ8KGH1NfQWhXSXmh2c8eArRLwO3HSv/2Q== - ---=-=-= -Content-Type: multipart/alternative; boundary="==-=-=" - - ---==-=-= - - -This is a plain text part. - ---==-=-= -Content-Type: text/enriched; - name="enriched.txt" - - -
This is a centered enriched part
- ---==-=-=-- - ---=-=-= - -This is a new plain text part. - ---=-=-= -Content-Disposition: attachment - - -This plain text part is an attachment. - ---=-=-=-- -@end example - -@node Encoding Customization -@section Encoding Customization - -@table @code - -@item mm-body-charset-encoding-alist -@vindex mm-body-charset-encoding-alist -Mapping from @acronym{MIME} charset to encoding to use. This variable is -usually used except, e.g., when other requirements force a specific -encoding (digitally signed messages require 7bit encodings). The -default is - -@lisp -((iso-2022-jp . 7bit) - (iso-2022-jp-2 . 7bit) - (utf-16 . base64) - (utf-16be . base64) - (utf-16le . base64)) -@end lisp - -As an example, if you do not want to have ISO-8859-1 characters -quoted-printable encoded, you may add @code{(iso-8859-1 . 8bit)} to -this variable. You can override this setting on a per-message basis -by using the @code{encoding} @acronym{MML} tag (@pxref{MML Definition}). - -@item mm-coding-system-priorities -@vindex mm-coding-system-priorities -Prioritize coding systems to use for outgoing messages. The default -is @code{nil}, which means to use the defaults in Emacs, but is -@code{(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8)} when -running Emacs in the Japanese language environment. It is a list of -coding system symbols (aliases of coding systems are also allowed, use -@kbd{M-x describe-coding-system} to make sure you are specifying correct -coding system names). For example, if you have configured Emacs -to prefer UTF-8, but wish that outgoing messages should be sent in -ISO-8859-1 if possible, you can set this variable to -@code{(iso-8859-1)}. You can override this setting on a per-message -basis by using the @code{charset} @acronym{MML} tag (@pxref{MML Definition}). - -As different hierarchies prefer different charsets, you may want to set -@code{mm-coding-system-priorities} according to the hierarchy in Gnus. -Here's an example: - -@c Corrections about preferred charsets are welcome. de, fr and fj -@c should be correct, I don't know about the rest (so these are only -@c examples): -@lisp -(add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) -(setq gnus-parameters - (nconc - ;; Some charsets are just examples! - '(("^cn\\." ;; Chinese - (mm-coding-system-priorities - '(iso-8859-1 cn-big5 chinese-iso-7bit utf-8))) - ("^cz\\.\\|^pl\\." ;; Central and Eastern European - (mm-coding-system-priorities '(iso-8859-2 utf-8))) - ("^de\\." ;; German language - (mm-coding-system-priorities '(iso-8859-1 iso-8859-15 utf-8))) - ("^fr\\." ;; French - (mm-coding-system-priorities '(iso-8859-15 iso-8859-1 utf-8))) - ("^fj\\." ;; Japanese - (mm-coding-system-priorities - '(iso-8859-1 iso-2022-jp iso-2022-jp-2 shift_jis utf-8))) - ("^ru\\." ;; Cyrillic - (mm-coding-system-priorities - '(koi8-r iso-8859-5 iso-8859-1 utf-8)))) - gnus-parameters)) -@end lisp - -@item mm-content-transfer-encoding-defaults -@vindex mm-content-transfer-encoding-defaults -Mapping from @acronym{MIME} types to encoding to use. This variable is usually -used except, e.g., when other requirements force a safer encoding -(digitally signed messages require 7bit encoding). Besides the normal -@acronym{MIME} encodings, @code{qp-or-base64} may be used to indicate that for -each case the most efficient of quoted-printable and base64 should be -used. - -@code{qp-or-base64} has another effect. It will fold long lines so that -MIME parts may not be broken by MTA. So do @code{quoted-printable} and -@code{base64}. - -Note that it affects body encoding only when a part is a raw forwarded -message (which will be made by @code{gnus-summary-mail-forward} with the -arg 2 for example) or is neither the @samp{text/*} type nor the -@samp{message/*} type. Even though in those cases, you can override -this setting on a per-message basis by using the @code{encoding} -@acronym{MML} tag (@pxref{MML Definition}). - -@item mm-use-ultra-safe-encoding -@vindex mm-use-ultra-safe-encoding -When this is non-@code{nil}, it means that textual parts are encoded as -quoted-printable if they contain lines longer than 76 characters or -starting with "From " in the body. Non-7bit encodings (8bit, binary) -are generally disallowed. This reduce the probability that a non-8bit -clean MTA or MDA changes the message. This should never be set -directly, but bound by other functions when necessary (e.g., when -encoding messages that are to be digitally signed). - -@end table - -@node Charset Translation -@section Charset Translation -@cindex charsets - -During translation from @acronym{MML} to @acronym{MIME}, for each -@acronym{MIME} part which has been composed inside Emacs, an appropriate -charset has to be chosen. - -@vindex mail-parse-charset -If you are running a non-@sc{mule} Emacs, this process is simple: If the -part contains any non-@acronym{ASCII} (8-bit) characters, the @acronym{MIME} charset -given by @code{mail-parse-charset} (a symbol) is used. (Never set this -variable directly, though. If you want to change the default charset, -please consult the documentation of the package which you use to process -@acronym{MIME} messages. -@xref{Various Message Variables, , Various Message Variables, message, - Message Manual}, for example.) -If there are only @acronym{ASCII} characters, the @acronym{MIME} charset US-ASCII is -used, of course. - -@cindex MULE -@cindex UTF-8 -@cindex Unicode -@vindex mm-mime-mule-charset-alist -Things are slightly more complicated when running Emacs with @sc{mule} -support. In this case, a list of the @sc{mule} charsets used in the -part is obtained, and the @sc{mule} charsets are translated to -@acronym{MIME} charsets by consulting the table provided by Emacs itself -or the variable @code{mm-mime-mule-charset-alist} for XEmacs. -If this results in a single @acronym{MIME} charset, this is used to encode -the part. But if the resulting list of @acronym{MIME} charsets contains more -than one element, two things can happen: If it is possible to encode the -part via UTF-8, this charset is used. (For this, Emacs must support -the @code{utf-8} coding system, and the part must consist entirely of -characters which have Unicode counterparts.) If UTF-8 is not available -for some reason, the part is split into several ones, so that each one -can be encoded with a single @acronym{MIME} charset. The part can only be -split at line boundaries, though---if more than one @acronym{MIME} charset is -required to encode a single line, it is not possible to encode the part. - -When running Emacs with @sc{mule} support, the preferences for which -coding system to use is inherited from Emacs itself. This means that -if Emacs is set up to prefer UTF-8, it will be used when encoding -messages. You can modify this by altering the -@code{mm-coding-system-priorities} variable though (@pxref{Encoding -Customization}). - -The charset to be used can be overridden by setting the @code{charset} -@acronym{MML} tag (@pxref{MML Definition}) when composing the message. - -The encoding of characters (quoted-printable, 8bit etc) is orthogonal -to the discussion here, and is controlled by the variables -@code{mm-body-charset-encoding-alist} and -@code{mm-content-transfer-encoding-defaults} (@pxref{Encoding -Customization}). - -@node Conversion -@section Conversion - -@findex mime-to-mml -A (multipart) @acronym{MIME} message can be converted to @acronym{MML} -with the @code{mime-to-mml} function. It works on the message in the -current buffer, and substitutes @acronym{MML} markup for @acronym{MIME} -boundaries. Non-textual parts do not have their contents in the buffer, -but instead have the contents in separate buffers that are referred to -from the @acronym{MML} tags. - -@findex mml-to-mime -An @acronym{MML} message can be converted back to @acronym{MIME} by the -@code{mml-to-mime} function. - -These functions are in certain senses ``lossy''---you will not get back -an identical message if you run @code{mime-to-mml} and then -@code{mml-to-mime}. Not only will trivial things like the order of the -headers differ, but the contents of the headers may also be different. -For instance, the original message may use base64 encoding on text, -while @code{mml-to-mime} may decide to use quoted-printable encoding, and -so on. - -In essence, however, these two functions should be the inverse of each -other. The resulting contents of the message should remain equivalent, -if not identical. - - -@node Flowed text -@section Flowed text -@cindex format=flowed - -The Emacs @acronym{MIME} library will respect the @code{use-hard-newlines} -variable (@pxref{Hard and Soft Newlines, ,Hard and Soft Newlines, -emacs, Emacs Manual}) when encoding a message, and the -``format=flowed'' Content-Type parameter when decoding a message. - -On encoding text, regardless of @code{use-hard-newlines}, lines -terminated by soft newline characters are filled together and wrapped -after the column decided by @code{fill-flowed-encode-column}. -Quotation marks (matching @samp{^>* ?}) are respected. The variable -controls how the text will look in a client that does not support -flowed text, the default is to wrap after 66 characters. If hard -newline characters are not present in the buffer, no flow encoding -occurs. - -On decoding flowed text, lines with soft newline characters are filled -together and wrapped after the column decided by -@code{fill-flowed-display-column}. The default is to wrap after -@code{fill-column}. - -@table @code -@item mm-fill-flowed -@vindex mm-fill-flowed -If non-@code{nil} a format=flowed article will be displayed flowed. -@end table - - -@node Interface Functions -@chapter Interface Functions -@cindex interface functions -@cindex mail-parse - -The @code{mail-parse} library is an abstraction over the actual -low-level libraries that are described in the next chapter. - -Standards change, and so programs have to change to fit in the new -mold. For instance, RFC2045 describes a syntax for the -@code{Content-Type} header that only allows @acronym{ASCII} characters in the -parameter list. RFC2231 expands on RFC2045 syntax to provide a scheme -for continuation headers and non-@acronym{ASCII} characters. - -The traditional way to deal with this is just to update the library -functions to parse the new syntax. However, this is sometimes the wrong -thing to do. In some instances it may be vital to be able to understand -both the old syntax as well as the new syntax, and if there is only one -library, one must choose between the old version of the library and the -new version of the library. - -The Emacs @acronym{MIME} library takes a different tack. It defines a -series of low-level libraries (@file{rfc2047.el}, @file{rfc2231.el} -and so on) that parses strictly according to the corresponding -standard. However, normal programs would not use the functions -provided by these libraries directly, but instead use the functions -provided by the @code{mail-parse} library. The functions in this -library are just aliases to the corresponding functions in the latest -low-level libraries. Using this scheme, programs get a consistent -interface they can use, and library developers are free to create -write code that handles new standards. - -The following functions are defined by this library: - -@table @code -@item mail-header-parse-content-type -@findex mail-header-parse-content-type -Parse a @code{Content-Type} header and return a list on the following -format: - -@lisp -("type/subtype" - (attribute1 . value1) - (attribute2 . value2) - ...) -@end lisp - -Here's an example: - -@example -(mail-header-parse-content-type - "image/gif; name=\"b980912.gif\"") -@result{} ("image/gif" (name . "b980912.gif")) -@end example - -@item mail-header-parse-content-disposition -@findex mail-header-parse-content-disposition -Parse a @code{Content-Disposition} header and return a list on the same -format as the function above. - -@item mail-content-type-get -@findex mail-content-type-get -Takes two parameters---a list on the format above, and an attribute. -Returns the value of the attribute. - -@example -(mail-content-type-get - '("image/gif" (name . "b980912.gif")) 'name) -@result{} "b980912.gif" -@end example - -@item mail-header-encode-parameter -@findex mail-header-encode-parameter -Takes a parameter string and returns an encoded version of the string. -This is used for parameters in headers like @code{Content-Type} and -@code{Content-Disposition}. - -@item mail-header-remove-comments -@findex mail-header-remove-comments -Return a comment-free version of a header. - -@example -(mail-header-remove-comments - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Gnus/5.070027 " -@end example - -@item mail-header-remove-whitespace -@findex mail-header-remove-whitespace -Remove linear white space from a header. Space inside quoted strings -and comments is preserved. - -@example -(mail-header-remove-whitespace - "image/gif; name=\"Name with spaces\"") -@result{} "image/gif;name=\"Name with spaces\"" -@end example - -@item mail-header-get-comment -@findex mail-header-get-comment -Return the last comment in a header. - -@example -(mail-header-get-comment - "Gnus/5.070027 (Pterodactyl Gnus v0.27) (Finnish Landrace)") -@result{} "Finnish Landrace" -@end example - -@item mail-header-parse-address -@findex mail-header-parse-address -Parse an address and return a list containing the mailbox and the -plaintext name. - -@example -(mail-header-parse-address - "Hrvoje Niksic ") -@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") -@end example - -@item mail-header-parse-addresses -@findex mail-header-parse-addresses -Parse a string with list of addresses and return a list of elements like -the one described above. - -@example -(mail-header-parse-addresses - "Hrvoje Niksic , Steinar Bang ") -@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") - ("sb@@metis.no" . "Steinar Bang")) -@end example - -@item mail-header-parse-date -@findex mail-header-parse-date -Parse a date string and return an Emacs time structure. - -@item mail-narrow-to-head -@findex mail-narrow-to-head -Narrow the buffer to the header section of the buffer. Point is placed -at the beginning of the narrowed buffer. - -@item mail-header-narrow-to-field -@findex mail-header-narrow-to-field -Narrow the buffer to the header under point. Understands continuation -headers. - -@item mail-header-fold-field -@findex mail-header-fold-field -Fold the header under point. - -@item mail-header-unfold-field -@findex mail-header-unfold-field -Unfold the header under point. - -@item mail-header-field-value -@findex mail-header-field-value -Return the value of the field under point. - -@item mail-encode-encoded-word-region -@findex mail-encode-encoded-word-region -Encode the non-@acronym{ASCII} words in the region. For instance, -@samp{Na@"{@dotless{i}}ve} is encoded as @samp{=?iso-8859-1?q?Na=EFve?=}. - -@item mail-encode-encoded-word-buffer -@findex mail-encode-encoded-word-buffer -Encode the non-@acronym{ASCII} words in the current buffer. This function is -meant to be called narrowed to the headers of a message. - -@item mail-encode-encoded-word-string -@findex mail-encode-encoded-word-string -Encode the words that need encoding in a string, and return the result. - -@example -(mail-encode-encoded-word-string - "This is na@"{@dotless{i}}ve, baby") -@result{} "This is =?iso-8859-1?q?na=EFve,?= baby" -@end example - -@item mail-decode-encoded-word-region -@findex mail-decode-encoded-word-region -Decode the encoded words in the region. - -@item mail-decode-encoded-word-string -@findex mail-decode-encoded-word-string -Decode the encoded words in the string and return the result. - -@example -(mail-decode-encoded-word-string - "This is =?iso-8859-1?q?na=EFve,?= baby") -@result{} "This is na@"{@dotless{i}}ve, baby" -@end example - -@end table - -Currently, @code{mail-parse} is an abstraction over @code{ietf-drums}, -@code{rfc2047}, @code{rfc2045} and @code{rfc2231}. These are documented -in the subsequent sections. - - - -@node Basic Functions -@chapter Basic Functions - -This chapter describes the basic, ground-level functions for parsing and -handling. Covered here is parsing @code{From} lines, removing comments -from header lines, decoding encoded words, parsing date headers and so -on. High-level functionality is dealt with in the first chapter -(@pxref{Decoding and Viewing}). - -@menu -* rfc2045:: Encoding @code{Content-Type} headers. -* rfc2231:: Parsing @code{Content-Type} headers. -* ietf-drums:: Handling mail headers defined by RFC822bis. -* rfc2047:: En/decoding encoded words in headers. -* time-date:: Functions for parsing dates and manipulating time. -* qp:: Quoted-Printable en/decoding. -* base64:: Base64 en/decoding. -* binhex:: Binhex decoding. -* uudecode:: Uuencode decoding. -* yenc:: Yenc decoding. -* rfc1843:: Decoding HZ-encoded text. -* mailcap:: How parts are displayed is specified by the @file{.mailcap} file -@end menu - - -@node rfc2045 -@section rfc2045 - -RFC2045 is the ``main'' @acronym{MIME} document, and as such, one would -imagine that there would be a lot to implement. But there isn't, since -most of the implementation details are delegated to the subsequent -RFCs. - -So @file{rfc2045.el} has only a single function: - -@table @code -@item rfc2045-encode-string -@findex rfc2045-encode-string -Takes a parameter and a value and returns a @samp{PARAM=VALUE} string. -@var{value} will be quoted if there are non-safe characters in it. -@end table - - -@node rfc2231 -@section rfc2231 - -RFC2231 defines a syntax for the @code{Content-Type} and -@code{Content-Disposition} headers. Its snappy name is @dfn{MIME -Parameter Value and Encoded Word Extensions: Character Sets, Languages, -and Continuations}. - -In short, these headers look something like this: - -@example -Content-Type: application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2="isn't it!" -@end example - -They usually aren't this bad, though. - -The following functions are defined by this library: - -@table @code -@item rfc2231-parse-string -@findex rfc2231-parse-string -Parse a @code{Content-Type} header and return a list describing its -elements. - -@example -(rfc2231-parse-string - "application/x-stuff; - title*0*=us-ascii'en'This%20is%20even%20more%20; - title*1*=%2A%2A%2Afun%2A%2A%2A%20; - title*2=\"isn't it!\"") -@result{} ("application/x-stuff" - (title . "This is even more ***fun*** isn't it!")) -@end example - -@item rfc2231-get-value -@findex rfc2231-get-value -Takes one of the lists on the format above and returns -the value of the specified attribute. - -@item rfc2231-encode-string -@findex rfc2231-encode-string -Encode a parameter in headers likes @code{Content-Type} and -@code{Content-Disposition}. - -@end table - - -@node ietf-drums -@section ietf-drums - -@dfn{drums} is an IETF working group that is working on the replacement -for RFC822. - -The functions provided by this library include: - -@table @code -@item ietf-drums-remove-comments -@findex ietf-drums-remove-comments -Remove the comments from the argument and return the results. - -@item ietf-drums-remove-whitespace -@findex ietf-drums-remove-whitespace -Remove linear white space from the string and return the results. -Spaces inside quoted strings and comments are left untouched. - -@item ietf-drums-get-comment -@findex ietf-drums-get-comment -Return the last most comment from the string. - -@item ietf-drums-parse-address -@findex ietf-drums-parse-address -Parse an address string and return a list that contains the mailbox and -the plain text name. - -@item ietf-drums-parse-addresses -@findex ietf-drums-parse-addresses -Parse a string that contains any number of comma-separated addresses and -return a list that contains mailbox/plain text pairs. - -@item ietf-drums-parse-date -@findex ietf-drums-parse-date -Parse a date string and return an Emacs time structure. - -@item ietf-drums-narrow-to-header -@findex ietf-drums-narrow-to-header -Narrow the buffer to the header section of the current buffer. - -@end table - - -@node rfc2047 -@section rfc2047 - -RFC2047 (Message Header Extensions for Non-@acronym{ASCII} Text) specifies how -non-@acronym{ASCII} text in headers are to be encoded. This is actually rather -complicated, so a number of variables are necessary to tweak what this -library does. - -The following variables are tweakable: - -@table @code -@item rfc2047-header-encoding-alist -@vindex rfc2047-header-encoding-alist -This is an alist of header / encoding-type pairs. Its main purpose is -to prevent encoding of certain headers. - -The keys can either be header regexps, or @code{t}. - -The values can be @code{nil}, in which case the header(s) in question -won't be encoded, @code{mime}, which means that they will be encoded, or -@code{address-mime}, which means the header(s) will be encoded carefully -assuming they contain addresses. - -@item rfc2047-charset-encoding-alist -@vindex rfc2047-charset-encoding-alist -RFC2047 specifies two forms of encoding---@code{Q} (a -Quoted-Printable-like encoding) and @code{B} (base64). This alist -specifies which charset should use which encoding. - -@item rfc2047-encode-function-alist -@vindex rfc2047-encode-function-alist -This is an alist of encoding / function pairs. The encodings are -@code{Q}, @code{B} and @code{nil}. - -@item rfc2047-encoded-word-regexp -@vindex rfc2047-encoded-word-regexp -When decoding words, this library looks for matches to this regexp. - -@item rfc2047-encoded-word-regexp-loose -@vindex rfc2047-encoded-word-regexp-loose -This is a version from which the regexp for the Q encoding pattern of -@code{rfc2047-encoded-word-regexp} is made loose. - -@item rfc2047-encode-encoded-words -@vindex rfc2047-encode-encoded-words -The boolean variable specifies whether encoded words -(e.g. @samp{=?us-ascii?q?hello?=}) should be encoded again. -@code{rfc2047-encoded-word-regexp} is used to look for such words. - -@item rfc2047-allow-irregular-q-encoded-words -@vindex rfc2047-allow-irregular-q-encoded-words -The boolean variable specifies whether irregular Q encoded words -(e.g. @samp{=?us-ascii?q?hello??=}) should be decoded. If it is -non-@code{nil}, @code{rfc2047-encoded-word-regexp-loose} is used instead -of @code{rfc2047-encoded-word-regexp} to look for encoded words. - -@end table - -Those were the variables, and these are this functions: - -@table @code -@item rfc2047-narrow-to-field -@findex rfc2047-narrow-to-field -Narrow the buffer to the header on the current line. - -@item rfc2047-encode-message-header -@findex rfc2047-encode-message-header -Should be called narrowed to the header of a message. Encodes according -to @code{rfc2047-header-encoding-alist}. - -@item rfc2047-encode-region -@findex rfc2047-encode-region -Encodes all encodable words in the region specified. - -@item rfc2047-encode-string -@findex rfc2047-encode-string -Encode a string and return the results. - -@item rfc2047-decode-region -@findex rfc2047-decode-region -Decode the encoded words in the region. - -@item rfc2047-decode-string -@findex rfc2047-decode-string -Decode a string and return the results. - -@item rfc2047-encode-parameter -@findex rfc2047-encode-parameter -Encode a parameter in the RFC2047-like style. This is a replacement for -the @code{rfc2231-encode-string} function. @xref{rfc2231}. - -When attaching files as @acronym{MIME} parts, we should use the RFC2231 -encoding to specify the file names containing non-@acronym{ASCII} -characters. However, many mail softwares don't support it in practice -and recipients won't be able to extract files with correct names. -Instead, the RFC2047-like encoding is acceptable generally. This -function provides the very RFC2047-like encoding, resigning to such a -regrettable trend. To use it, put the following line in your -@file{~/.gnus.el} file: - -@lisp -(defalias 'mail-header-encode-parameter 'rfc2047-encode-parameter) -@end lisp - -@end table - - -@node time-date -@section time-date - -While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers -and manipulating time. (Not by using tesseracts, though, I'm sorry to -say.) - -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. - -Here's a bunch of time/date/second/day examples: - -@example -(parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) - -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) - -(time-to-seconds '(13818 19266)) -@result{} 905595714.0 - -(seconds-to-time 905595714.0) -@result{} (13818 19266 0) - -(time-to-days '(13818 19266)) -@result{} 729644 - -(days-to-time 729644) -@result{} (961933 65536) - -(time-since '(13818 19266)) -@result{} (0 430) - -(time-less-p '(13818 19266) '(13818 19145)) -@result{} nil - -(subtract-time '(13818 19266) '(13818 19145)) -@result{} (0 121) - -(days-between "Sat Sep 12 12:21:54 1998 +0200" - "Sat Sep 07 12:21:54 1998 +0200") -@result{} 5 - -(date-leap-year-p 2000) -@result{} t - -(time-to-day-in-year '(13818 19266)) -@result{} 255 - -(time-to-number-of-days - (time-since - (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4.146122685185185 -@end example - -And finally, we have @code{safe-date-to-time}, which does the same as -@code{date-to-time}, but returns a zero time if the date is -syntactically malformed. - -The five data representations used are the following: - -@table @var -@item date -An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 -12:21:54 1998 +0200"}. - -@item time -An internal Emacs time. For instance: @code{(13818 26466)}. - -@item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. - -@item days -An integer number representing the number of days since 00000101. For -instance: @code{729644}. - -@item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t -7200)}. -@end table - -All the examples above represent the same moment. - -These are the functions available: - -@table @code -@item date-to-time -Take a date and return a time. - -@item time-to-seconds -Take a time and return seconds. - -@item seconds-to-time -Take seconds and return a time. - -@item time-to-days -Take a time and return days. - -@item days-to-time -Take days and return a time. - -@item date-to-day -Take a date and return days. - -@item time-to-number-of-days -Take a time and return the number of days that represents. - -@item safe-date-to-time -Take a date and return a time. If the date is not syntactically valid, -return a ``zero'' time. - -@item time-less-p -Take two times and say whether the first time is less (i. e., earlier) -than the second time. - -@item time-since -Take a time and return a time saying how long it was since that time. - -@item subtract-time -Take two times and subtract the second from the first. I. e., return -the time between the two times. - -@item days-between -Take two days and return the number of days between those two days. - -@item date-leap-year-p -Take a year number and say whether it's a leap year. - -@item time-to-day-in-year -Take a time and return the day number within the year that the time is -in. - -@end table - - -@node qp -@section qp - -This library deals with decoding and encoding Quoted-Printable text. - -Very briefly explained, qp encoding means translating all 8-bit -characters (and lots of control characters) into things that look like -@samp{=EF}; that is, an equal sign followed by the byte encoded as a hex -string. - -The following functions are defined by the library: - -@table @code -@item quoted-printable-decode-region -@findex quoted-printable-decode-region -QP-decode all the encoded text in the specified region. - -@item quoted-printable-decode-string -@findex quoted-printable-decode-string -Decode the QP-encoded text in a string and return the results. - -@item quoted-printable-encode-region -@findex quoted-printable-encode-region -QP-encode all the encodable characters in the specified region. The third -optional parameter @var{fold} specifies whether to fold long lines. -(Long here means 72.) - -@item quoted-printable-encode-string -@findex quoted-printable-encode-string -QP-encode all the encodable characters in a string and return the -results. - -@end table - - -@node base64 -@section base64 -@cindex base64 - -Base64 is an encoding that encodes three bytes into four characters, -thereby increasing the size by about 33%. The alphabet used for -encoding is very resistant to mangling during transit. - -The following functions are defined by this library: - -@table @code -@item base64-encode-region -@findex base64-encode-region -base64 encode the selected region. Return the length of the encoded -text. Optional third argument @var{no-line-break} means do not break -long lines into shorter lines. - -@item base64-encode-string -@findex base64-encode-string -base64 encode a string and return the result. - -@item base64-decode-region -@findex base64-decode-region -base64 decode the selected region. Return the length of the decoded -text. If the region can't be decoded, return @code{nil} and don't -modify the buffer. - -@item base64-decode-string -@findex base64-decode-string -base64 decode a string and return the result. If the string can't be -decoded, @code{nil} is returned. - -@end table - - -@node binhex -@section binhex -@cindex binhex -@cindex Apple -@cindex Macintosh - -@code{binhex} is an encoding that originated in Macintosh environments. -The following function is supplied to deal with these: - -@table @code -@item binhex-decode-region -@findex binhex-decode-region -Decode the encoded text in the region. If given a third parameter, only -decode the @code{binhex} header and return the filename. - -@end table - -@node uudecode -@section uudecode -@cindex uuencode -@cindex uudecode - -@code{uuencode} is probably still the most popular encoding of binaries -used on Usenet, although @code{base64} rules the mail world. - -The following function is supplied by this package: - -@table @code -@item uudecode-decode-region -@findex uudecode-decode-region -Decode the text in the region. -@end table - - -@node yenc -@section yenc -@cindex yenc - -@code{yenc} is used for encoding binaries on Usenet. The following -function is supplied by this package: - -@table @code -@item yenc-decode-region -@findex yenc-decode-region -Decode the encoded text in the region. - -@end table - - -@node rfc1843 -@section rfc1843 -@cindex rfc1843 -@cindex HZ -@cindex Chinese - -RFC1843 deals with mixing Chinese and @acronym{ASCII} characters in messages. In -essence, RFC1843 switches between @acronym{ASCII} and Chinese by doing this: - -@example -This sentence is in @acronym{ASCII}. -The next sentence is in GB.~@{<:Ky2;S@{#,NpJ)l6HK!#~@}Bye. -@end example - -Simple enough, and widely used in China. - -The following functions are available to handle this encoding: - -@table @code -@item rfc1843-decode-region -Decode HZ-encoded text in the region. - -@item rfc1843-decode-string -Decode a HZ-encoded string and return the result. - -@end table - - -@node mailcap -@section mailcap - -The @file{~/.mailcap} file is parsed by most @acronym{MIME}-aware message -handlers and describes how elements are supposed to be displayed. -Here's an example file: - -@example -image/*; gimp -8 %s -audio/wav; wavplayer %s -application/msword; catdoc %s ; copiousoutput ; nametemplate=%s.doc -@end example - -This says that all image files should be displayed with @code{gimp}, -that WAVE audio files should be played by @code{wavplayer}, and that -MS-WORD files should be inlined by @code{catdoc}. - -The @code{mailcap} library parses this file, and provides functions for -matching types. - -@table @code -@item mailcap-mime-data -@vindex mailcap-mime-data -This variable is an alist of alists containing backup viewing rules. - -@end table - -Interface functions: - -@table @code -@item mailcap-parse-mailcaps -@findex mailcap-parse-mailcaps -Parse the @file{~/.mailcap} file. - -@item mailcap-mime-info -Takes a @acronym{MIME} type as its argument and returns the matching viewer. - -@end table - - - - -@node Standards -@chapter Standards - -The Emacs @acronym{MIME} library implements handling of various elements -according to a (somewhat) large number of RFCs, drafts and standards -documents. This chapter lists the relevant ones. They can all be -fetched from @uref{http://quimby.gnus.org/notes/}. - -@table @dfn -@item RFC822 -@itemx STD11 -Standard for the Format of ARPA Internet Text Messages. - -@item RFC1036 -Standard for Interchange of USENET Messages - -@item RFC2045 -Format of Internet Message Bodies - -@item RFC2046 -Media Types - -@item RFC2047 -Message Header Extensions for Non-@acronym{ASCII} Text - -@item RFC2048 -Registration Procedures - -@item RFC2049 -Conformance Criteria and Examples - -@item RFC2231 -@acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets, -Languages, and Continuations - -@item RFC1843 -HZ - A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and -@acronym{ASCII} characters - -@item draft-ietf-drums-msg-fmt-05.txt -Draft for the successor of RFC822 - -@item RFC2112 -The @acronym{MIME} Multipart/Related Content-type - -@item RFC1892 -The Multipart/Report Content Type for the Reporting of Mail System -Administrative Messages - -@item RFC2183 -Communicating Presentation Information in Internet Messages: The -Content-Disposition Header Field - -@item RFC2646 -Documentation of the text/plain format parameter for flowed text. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@bye - - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: - -@ignore - arch-tag: c7ef2fd0-a91c-4e10-aa52-c1a2b11b1a8d -@end ignore diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi deleted file mode 100644 index 97a61cd5547..00000000000 --- a/doc/misc/epa.texi +++ /dev/null @@ -1,405 +0,0 @@ -\input texinfo @c -*- mode: texinfo -*- -@c %**start of header -@setfilename ../../info/epa -@settitle EasyPG Assistant User's Manual -@c %**end of header - -@set VERSION 1.0.0 - -@copying -This file describes EasyPG Assistant @value{VERSION}. - -Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* EasyPG Assistant: (epa). An Emacs user interface to GNU Privacy Guard. -@end direntry - -@titlepage -@title EasyPG Assistant - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top EasyPG Assistant user's manual - -EasyPG Assistant is an Emacs user interface to GNU Privacy Guard -(GnuPG, @pxref{Top, , Top, gnupg, Using the GNU Privacy Guard}). - -EasyPG Assistant is a part of the package called EasyPG, an all-in-one -GnuPG interface for Emacs. EasyPG also contains the library interface -called EasyPG Library. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: -* Quick start:: -* Commands:: -@end menu - -@node Overview -@chapter Overview - -EasyPG Assistant provides the following features. - -@itemize @bullet -@item Key management. -@item Cryptographic operations on regions. -@item Cryptographic operations on files. -@item Dired integration. -@item Mail-mode integration. -@item Automatic encryption/decryption of *.gpg files. -@end itemize - -@node Quick start -@chapter Quick start - -EasyPG Assistant commands are prefixed by @samp{epa-}. For example, - -@itemize @bullet -@item To browse your keyring, type @kbd{M-x epa-list-keys} - -@item To create a cleartext signature of the region, type @kbd{M-x epa-sign-region} - -@item To encrypt a file, type @kbd{M-x epa-encrypt-file} -@end itemize - -EasyPG Assistant provides several cryptographic features which can be -integrated into other Emacs functionalities. For example, automatic -encryption/decryption of @samp{*.gpg} files. - -To install these features, do @kbd{C-u 1 M-x epa-mode}. It can also -be turned on by customize. Try @kbd{M-x customize-variable epa-mode}. - -@node Commands -@chapter Commands - -This chapter introduces various commands for typical use cases. - -@menu -* Key management:: -* Cryptographic operations on regions:: -* Cryptographic operations on files:: -* Dired integration:: -* Mail-mode integration:: -* Encrypting/decrypting *.gpg files:: -@end menu - -@node Key management -@section Key management -Probably the first step of using EasyPG Assistant is to browse your -keyring. @kbd{M-x epa-list-keys} is corresponding to @samp{gpg ---list-keys} from the command line. - -@deffn Command epa-list-keys name mode -Show all keys matched with @var{name} from the public keyring. -@end deffn - -@noindent -The output looks as follows. - -@example - u A5B6B2D4B15813FE Daiki Ueno -@end example - -@noindent -A character on the leftmost column indicates the trust level of the -key. If it is @samp{u}, the key is marked as ultimately trusted. The -second column is the key ID, and the rest is the user ID. - -You can move over entries by @key{TAB}. If you type @key{RET} or -click button1 on an entry, you will see more detailed information -about the key you selected. - -@example - u Daiki Ueno - u A5B6B2D4B15813FE 1024bits DSA - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: sign certify - Fingerprint: 8003 7CD0 0F1A 9400 03CA 50AA A5B6 B2D4 B158 13FE - u 4447461B2A9BEA2D 2048bits ELGAMAL_E - Created: 2001-10-09 - Expires: 2007-09-04 - Capabilities: encrypt - Fingerprint: 9003 D76B 73B7 4A8A E588 10AF 4447 461B 2A9B EA2D -@end example - -@noindent -To browse your private keyring, use @kbd{M-x epa-list-secret-keys}. - -@deffn Command epa-list-secret-keys name -Show all keys matched with @var{name} from the private keyring. -@end deffn - -@noindent -In @samp{*Keys*} buffer, several commands are available. The common -use case is to export some keys to a file. To do that, type @kbd{m} -to select keys, type @kbd{o}, and then supply the filename. - -Below are other commands related to key management. Some of them take -a file as input/output, and others take the current region. - -@deffn Command epa-insert-keys keys -Insert selected @var{keys} after the point. It will let you select -keys before insertion. By default, it will encode keys in the OpenPGP -armor format. -@end deffn - -@deffn Command epa-import-keys file -Import keys from @var{file} to your keyring. -@end deffn - -@deffn Command epa-import-keys-region start end -Import keys from the current region between @var{start} and @var{end} -to your keyring. -@end deffn - -@deffn Command epa-import-armor-in-region start end -Import keys in the OpenPGP armor format in the current region between -@var{start} and @var{end}. The difference from -@code{epa-import-keys-region} is that -@code{epa-import-armor-in-region} searches armors in the region and -applies @code{epa-import-keys-region} to each of them. -@end deffn - -@deffn Command epa-delete-keys allow-secret -Delete selected keys. If @var{allow-secret} is non-@code{nil}, it -also delete the secret keys. -@end deffn - -@node Cryptographic operations on regions -@section Cryptographic operations on regions - -@deffn Command epa-decrypt-region start end -Decrypt the current region between @var{start} and @var{end}. It -replaces the region with the decrypted text. -@end deffn - -@deffn Command epa-decrypt-armor-in-region start end -Decrypt OpenPGP armors in the current region between @var{start} and -@var{end}. The difference from @code{epa-decrypt-region} is that -@code{epa-decrypt-armor-in-region} searches armors in the region -and applies @code{epa-decrypt-region} to each of them. That is, this -command does not alter the original text around armors. -@end deffn - -@deffn Command epa-verify-region start end -Verify the current region between @var{start} and @var{end}. It sends -the verification result to the minibuffer or a popup window. It -replaces the region with the signed text. -@end deffn - -@deffn Command epa-verify-cleartext-in-region -Verify OpenPGP cleartext blocks in the current region between -@var{start} and @var{end}. The difference from -@code{epa-verify-region} is that @code{epa-verify-cleartext-in-region} -searches OpenPGP cleartext blocks in the region and applies -@code{epa-verify-region} to each of them. That is, this command does -not alter the original text around OpenPGP cleartext blocks. -@end deffn - -@deffn Command epa-sign-region start end signers type -Sign the current region between @var{start} and @var{end}. By -default, it creates a cleartext signature. If a prefix argument is -given, it will let you select signing keys, and then a signature -type. -@end deffn - -@deffn Command epa-encrypt-region start end recipients sign signers -Encrypt the current region between @var{start} and @var{end}. It will -let you select recipients. If a prefix argument is given, it will -also ask you whether or not to sign the text before encryption and if -you answered yes, it will let you select the signing keys. -@end deffn - -@node Cryptographic operations on files -@section Cryptographic operations on files - -@deffn Command epa-decrypt-file file -Decrypt @var{file}. -@end deffn - -@deffn Command epa-verify-file file -Verify @var{file}. -@end deffn - -@deffn Command epa-sign-file file signers type -Sign @var{file}. If a prefix argument is given, it will let you -select signing keys, and then a signature type. -@end deffn - -@deffn Command epa-encrypt-file file recipients -Encrypt @var{file}. It will let you select recipients. -@end deffn - -@node Dired integration -@section Dired integration - -EasyPG Assistant extends Dired Mode for GNU Emacs to allow users to -easily do cryptographic operations on files. For example, - -@example -M-x dired -(mark some files) -: e (or M-x epa-dired-do-encrypt) -(select recipients by 'm' and click [OK]) -@end example - -@noindent -The following keys are assigned. - -@table @kbd -@item : d -@kindex @kbd{: d} -@findex epa-dired-do-decrypt -Decrypt marked files. - -@item : v -@kindex @kbd{: v} -@findex epa-dired-do-verify -Verify marked files. - -@item : s -@kindex @kbd{: s} -@findex epa-dired-do-sign -Sign marked files. - -@item : e -@kindex @kbd{: e} -@findex epa-dired-do-encrypt -Encrypt marked files. - -@end table - -@node Mail-mode integration -@section Mail-mode integration - -EasyPG Assistant provides a minor mode to help user compose inline PGP -messages. Inline PGP is sending the OpenPGP blobs directly inside a -mail message and it is not recommended and you should consider to use -PGP/MIME. See -@uref{http://josefsson.org/inline-openpgp-considered-harmful.html, -Inline PGP in E-mail is bad, Mm'kay?}. - -@noindent -The following keys are assigned. - -@table @kbd -@item C-c C-e d -@kindex @kbd{C-c C-e d} -@findex epa-mail-decrypt -Decrypt OpenPGP armors in the current buffer. - -@item C-c C-e v -@kindex @kbd{C-c C-e v} -@findex epa-mail-verify -Verify OpenPGP cleartext signed messages in the current buffer. - -@item C-c C-e s -@kindex @kbd{C-c C-e s} -@findex epa-mail-sign -Compose a signed message from the current buffer. - -@item C-c C-e e -@kindex @kbd{C-c C-e e} -@findex epa-mail-encrypt -Compose an encrypted message from the current buffer. -By default it tries to build the recipient list from @samp{to}, -@samp{cc}, and @samp{bcc} fields of the mail header. To include your -key in the recipient list, use @samp{encrypt-to} option in -@file{~/.gnupg/gpg.conf}. - -@end table - -@node Encrypting/decrypting *.gpg files -@section Encrypting/decrypting *.gpg files -Once @code{epa-setup} is loaded, every file whose extension is -@samp{.gpg} will be treated as encrypted. That is, when you attempt -to open such a file which already exists, the decrypted text is -inserted in the buffer rather than encrypted one. On the other hand, -when you attempt to save the buffer to a file whose extension is -@samp{.gpg}, encrypted data is written. - -If you want to temporarily disable this behavior, use @kbd{M-x -epa-file-disable}, and then to enable this behavior use @kbd{M-x -epa-file-enable}. - -@deffn Command epa-file-disable -Disable automatic encryption/decryption of *.gpg files. -@end deffn - -@deffn Command epa-file-enable -Enable automatic encryption/decryption of *.gpg files. -@end deffn - -@noindent -@code{epa-file} will let you select recipients. If you want to -suppress this question, it might be a good idea to put the following -line on the first line of the text being encrypted. -@vindex epa-file-encrypt-to - -@cartouche -@lisp -;; -*- epa-file-encrypt-to: ("ueno@@unixuser.org") -*- -@end lisp -@end cartouche - -The file name extension of encrypted files can be controlled by -@var{epa-file-name-regexp}. - -@defvar epa-file-name-regexp -Regexp which matches filenames treated as encrypted. -@end defvar - -Other variables which control the automatic encryption/decryption -behavior are below. - -@defvar epa-file-cache-passphrase-for-symmetric-encryption -If non-@code{nil}, cache passphrase for symmetric encryption. The -default value is @code{nil}. -@end defvar - -@defvar epa-file-inhibit-auto-save -If non-@code{nil}, disable auto-saving when opening an encrypted file. -The default value is @code{t}. -@end defvar - -@bye - -@c End: - -@ignore - arch-tag: 7404e246-7d4c-4db4-9332-c1293a455a4f -@end ignore diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi deleted file mode 100644 index 09e9479449e..00000000000 --- a/doc/misc/erc.texi +++ /dev/null @@ -1,1066 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/erc -@settitle ERC Manual -@syncodeindex fn cp -@c %**end of header - -@copying -This manual is for ERC version 5.3. - -Copyright @copyright{} 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -All Emacs Lisp code contained in this document may be used, distributed, -and modified without restriction. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* ERC: (erc). Powerful, modular, and extensible IRC client for Emacs. -@end direntry - -@titlepage -@title ERC manual -@subtitle a full-featured IRC client -@subtitle for GNU Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up -@top ERC - -@insertcopying -@end ifnottex - -@menu -* Introduction:: What is ERC? -* Obtaining ERC:: How to get ERC releases and development - versions. -* Installation:: Compiling and installing ERC. -* Getting Started:: Quick Start guide to using ERC. -* Keystroke Summary:: Keystrokes used in ERC buffers. -* Modules:: Available modules for ERC. -* Advanced Usage:: Cool ways of using ERC. -* Getting Help and Reporting Bugs:: -* History:: The history of ERC. -* Copying:: The GNU General Public License gives you - permission to redistribute ERC on - certain terms; it also explains that - there is no warranty. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Obtaining ERC - -* Releases:: Released versions of ERC. -* Development:: Latest unreleased development changes. - -Getting Started - -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients - -Advanced Usage - -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. - -@end detailmenu -@end menu - -@node Introduction, Obtaining ERC, Top, Top -@comment node-name, next, previous, up -@chapter Introduction - -ERC is a powerful, modular, and extensible IRC client for Emacs. - -It comes with the following capabilities enabled by default. - -@itemize @bullet -@item Flood control -@item Timestamps -@item Join channels automatically -@item Buttonize URLs, nicknames, and other text -@item Wrap long lines -@item Highlight or remove IRC control characters -@item Highlight pals, fools, and other keywords -@item Detect netsplits -@item Complete nicknames and commands in a programmable fashion -@item Make displayed lines read-only -@item Input history -@item Track channel activity in the mode-line - -@end itemize - -@node Obtaining ERC, Installation, Introduction, Top -@comment node-name, next, previous, up -@chapter Obtaining ERC - -@menu -* Releases:: Released versions of ERC. -* Development:: Latest unreleased development changes. -@end menu - -Note that some ERC files are not included with Emacs due to copyright or -dependency issues. If desired, they may be found at the following -locations, or from your local GNU mirror. - -@itemize @bullet -@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.tar.gz} -@item @uref{http://ftp.gnu.org/gnu/erc/erc-5.3-extras.zip} -@end itemize - -The rest of this chapter may be skipped if you are using the version of -ERC that comes with Emacs. - -@node Releases, Development, Obtaining ERC, Obtaining ERC -@comment node-name, next, previous, up -@section Releases - -Choose to install a release if you want to minimize risk. - -Errors are corrected in development first. User-visible changes will be -announced on the @email{erc-discuss@@gnu.org} mailing list. -@pxref{Getting Help and Reporting Bugs}. - -@cindex releases, Debian package -@cindex Debian package for ERC -Debian users can get ERC via apt-get. The @file{erc} package is -available in the official Debian repository. - -@cindex releases, from source -Alternatively, you can download the latest release from -@uref{http://ftp.gnu.org/gnu/erc}, or your local GNU mirror. - -@node Development, , Releases, Obtaining ERC -@comment node-name, next, previous, up -@section Development -@cindex development - -Choose the development version if you want to live on the bleeding edge -of ERC development or try out new features before release. - -@cindex git version control system, using -The git version control system allows you to keep up-to-date with the -latest changes to the development version of ERC. It also allows you -to contribute changes (via commits, if you are have developer access to -the repository, or via patches, otherwise). If you would like to -contribute to ERC development, it is highly recommended that you use -git. - -If you are new to git, you might find this tutorial helpful: -@uref{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html}. - -Downloading ERC with git and staying up-to-date involves the following -steps. - -@enumerate -@item Install git. - -@itemize @bullet -@item Debian and Ubuntu: @kbd{apt-get install git-core}. -@item Windows: @uref{http://git.or.cz/gitwiki/WindowsInstall}. -@item Other operating systems: download, compile, and install the source -from @uref{http://www.kernel.org/pub/software/scm/git/}, or find a git -package for your operating system. -@end itemize - -@item Download the ERC development branch. - -If you have developer access to ERC, do: - -@example -git clone ssh://loginname@@git.sv.gnu.org/srv/git/erc.git -@end example - -otherwise, do: - -@example -git clone git://git.sv.gnu.org/erc.git -@end example - -If you are behind a restrictive firewall, and do not have developer -access, then do the following instead: - -@example -git clone http://git.sv.gnu.org/r/erc.git -@end example - -@item List upstream changes that are missing from your local copy. -Do this whenever you want to see whether new changes have been committed -to ERC. If you wish, you may skip this step and proceed directly to -the ``update'' step. - -@example -# Change to the source directory you are interested in. -cd erc - -# Fetch new changes from the repository, but don't apply them yet -git fetch origin - -# Display log messages for the new changes -git log HEAD..origin -@end example - -``origin'' is git's name for the location where you originally got ERC -from. You can change this location at any time by editing the -@file{.git/config} file in the directory where the ERC source was -placed. - -@cindex updating ERC with git -@item Update to the latest version by pulling in any missing changes. - -@example -cd erc -git pull origin -@end example - -git will show how many files changed, and will provide a visual display -for how many lines were changed in each file. - -@end enumerate - -There are other ways to interact with the ERC repository. - -@itemize -@item Browse git repo: @uref{http://git.sv.gnu.org/gitweb/?p=erc.git} -@item Latest development snapshot: @uref{http://mwolson.org/static/dist/erc-latest.tar.gz} -@item Latest development snapshot (zip file): @uref{http://mwolson.org/static/dist/erc-latest.zip} -@end itemize - -The latest development snapshot can lag behind the git repo by as much -as 20 minutes, but never more than that. - -For further information on committing changes to ERC and performing -development, please consult -@uref{http://emacswiki.org/cgi-bin/wiki/ErcDevelopment}. - - -@node Installation, Getting Started, Obtaining ERC, Top -@comment node-name, next, previous, up -@chapter Installation - -ERC may be compiled and installed on your machine. - -This section may be skipped if you are using the version of ERC that -comes with Emacs. - -@subsubheading Compilation - -This is an optional step, since Emacs Lisp source code does not -necessarily have to be byte-compiled. It will yield a speed increase, -though. - -A working copy of Emacs or XEmacs is needed in order to compile ERC. By -default, the program that is installed with the name @command{emacs} -will be used. - -If you want to use the @command{xemacs} binary to perform the -compilation, you would need to edit @file{Makefile} in the top-level -directory as follows. You can put either a full path to an Emacs or -XEmacs binary or just the command name, as long as it is in the -@env{PATH}. - -@example -EMACS = xemacs -SITEFLAG = -no-site-file -@end example - -Running @code{make} should compile the ERC source files in the -@file{lisp} directory. - -@subsubheading Installation - -ERC may be installed into your file hierarchy by doing the following. - -Edit the @file{Makefile} file so that @env{ELISPDIR} points to where you -want the source and compiled ERC files to be installed and -@env{INFODIR} indicates where to put the ERC manual. Of course, you -will want to edit @env{EMACS} and @env{SITEFLAG} as shown in the -Compilation section if you are using XEmacs. - -If you are installing ERC on a Debian system, you might want to change -the value of @env{INSTALLINFO} as specified in @file{Makefile}. - -Run @code{make} as a normal user. - -Run @code{make install} as the root user if you have chosen installation -locations that require this. - - -@node Getting Started, Keystroke Summary, Installation, Top -@comment node-name, next, previous, up -@chapter Getting Started -@cindex settings - -To use ERC, add the directory containing its files to your -@code{load-path} variable, in your @file{.emacs} file. Then, load ERC -itself. An example follows. - -@lisp -(require 'erc) -@end lisp - -Once ERC is loaded, the command @kbd{M-x erc} will start ERC and -prompt for the server to connect to. - -If you want to place ERC settings in their own file, you can place them -in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. - -If you would rather use the Customize interface to change how ERC works, -do @kbd{M-x customize-group RET erc RET}. In particular, ERC comes with -lots of modules that may be enabled or disabled; to select which ones -you want, do @kbd{M-x customize-variable RET erc-modules RET}. - -@menu -* Sample Session:: Example of connecting to the #emacs channel -* Special Features:: Differences from standalone IRC clients -@end menu - -@node Sample Session, Special Features, Getting Started, Getting Started -@comment node-name, next, previous, up -@section Sample Session - -This is an example ERC session which shows how to connect to the #emacs -channel on Freenode. Another IRC channel on Freenode that may be of -interest is #erc, which is a channel where ERC users and developers hang -out. - -@itemize @bullet - -@item Connect to Freenode - -Run @kbd{M-x erc}. Use ``irc.freenode.net'' as the IRC server, ``6667'' -as the port, and choose a nickname. - -@item Get used to the interface - -Switch to the ``irc.freenode.net:6667'' buffer, if you're not already -there. You will see first some messages about checking for ident, and -then a bunch of other messages that describe the current IRC server. - -@item Join the #emacs channel - -In that buffer, type ``/join SPC #emacs'' and hit @kbd{RET}. Depending -on how you've set up ERC, either a new buffer for ``#emacs'' will be -displayed, or a new buffer called ``#emacs'' will be created in the -background. If the latter, switch to the ``#emacs'' buffer. You will -see the channel topic and a list of the people who are currently on the -channel. - -@item Register your nickname with Freenode - -If you would like to be able to talk with people privately on the -Freenode network, you will have to ``register'' your nickname. To do -so, switch to the ``irc.freenode.net:6667'' buffer and type ``/msg -NickServ register '', replacing ``'' with your -desired password. It should tell you that the operation was successful. - -@item Talk to people in the channel - -If you switch back to the ``#emacs'' buffer, you can type a message, and -everyone on the channel will see it. - -@item Open a query buffer to talk to someone - -If you want to talk with someone in private (this should usually not be -done for technical help, only for personal questions), type ``/query -'', replacing ``'' with the nickname of the person you would -like to talk to. Depending on how ERC is set up, you will either see a -new buffer with the name of the person, or such a buffer will be created -in the background and you will have to switch to it. Begin typing -messages, and you will be able to have a conversation. - -Note that if the other person is not registered, you will not be able to -talk with them. - -@end itemize - -@node Special Features, , Sample Session, Getting Started -@comment node-name, next, previous, up -@section Special Features - -ERC has some features that distinguish it from some IRC clients. - -@itemize @bullet - -@item multiple channels and multiple servers - -Every channel is put in a separate buffer. Several IRC servers may be -connected to at the same time. - -@cindex query buffers -@item private message separation - -Private conversations are treated as channels, and are put into separate -buffers in Emacs. We call these ``query buffers''. - -@item highlighting - -Some occurrences of words can be highlighted, which makes it easier to -track different kinds of conversations. - -@item notification - -ERC can notify you that certain users are online. - -@item channel tracking - -Channels can be hidden and conversation continue in the background. You -are notified when something is said in such a channel that is not -currently visible. This makes it easy to get Real Work done while still -maintaining an IRC presence. - -@item nick completion - -ERC can complete words upon hitting @kbd{TAB}, which eases the writing -of nicknames in messages. - -@cindex history ring -@item history - -Past actions are kept in history rings for future use. To navigate a -history ring, hit @kbd{M-p} to go backwards and @kbd{M-n} to go -forwards. - -@item multiple languages - -Different channels and servers may have different language encodings. - -In addition, it is possible to translate the messages that ERC uses into -multiple languages. Please contact the developers of ERC at -@email{erc-discuss@@gnu.org} if you are interested in helping with the -translation effort. - -@item user scripting - -Users can load scripts (e.g. auto greeting scripts) when ERC starts up. - -It is also possible to make custom IRC commands, if you know a little -Emacs Lisp. Just make an Emacs Lisp function and call it -@code{erc-cmd-NEWCOMMAND}, where @code{NEWCOMMAND} is the name of the -new command in capital letters. - -@item auto reconnect - -If the connection goes away at some point, ERC will try to reconnect -automatically. If it fails to reconnect, and you want to try to -manually reestablish the connection at some later point, switch to an -ERC buffer and run the @code{/RECONNECT} command. - -@end itemize - - -@node Keystroke Summary, Modules, Getting Started, Top -@comment node-name, next, previous, up -@chapter Keys Used in ERC -@cindex keystrokes - -This is a summary of keystrokes available in every ERC buffer. - -@table @kbd - -@item C-a or (`erc-bol') -Go to beginning of line or end of prompt. - -@item RET (`erc-send-current-line') -Send the current line - -@item TAB (`erc-complete-word') -If at prompt, complete the current word. -Otherwise, move to the next link or button. - -@item M-TAB (`ispell-complete-word') -Complete the given word, using ispell. - -@item C-c C-a (`erc-bol') -Go to beginning of line or end of prompt. - -@item C-c C-b (`erc-iswitchb') -Use `iswitchb-read-buffer' to prompt for a ERC buffer to switch to. - -@item C-c C-c (`erc-toggle-interpret-controls') -Toggle interpretation of control sequences in messages. - -@item C-c C-d (`erc-input-action') -Interactively input a user action and send it to IRC. - -@item C-c C-e (`erc-toggle-ctcp-autoresponse') -Toggle automatic CTCP replies (like VERSION and PING). - -@item C-c C-f (`erc-toggle-flood-control') -Toggle use of flood control on sent messages. - -@item C-c TAB (`erc-invite-only-mode') -Turn on the invite only mode (+i) for the current channel. - -@item C-c C-j (`erc-join-channel') -Join channel. If point is at the beginning of a channel name, use that -as default. - -@item C-c C-k (`erc-go-to-log-matches-buffer') -Interactively open an erc-log-matches buffer - -@item C-c C-l (`erc-save-buffer-in-logs') -Append buffer contents to the log file, if logging is enabled. - -@item C-c C-n (`erc-channel-names') -Run "/names #channel" in the current channel. - -@item C-c C-o (`erc-get-channel-mode-from-keypress') -Read a key sequence and call the corresponding channel mode function. -After doing @kbd{C-c C-o}, type in a channel mode letter. - -@kbd{C-g} means quit. -@kbd{RET} lets you type more than one mode at a time. -If @kbd{l} is pressed, @code{erc-set-channel-limit} gets called. -If @kbd{k} is pressed, @code{erc-set-channel-key} gets called. -Anything else will be sent to `erc-toggle-channel-mode'. - -@item C-c C-p (`erc-part-from-channel') -Part from the current channel and prompt for a reason. - -@item C-c C-q (`erc-quit-server') -Disconnect from current server after prompting for reason. - -@item C-c C-r (`erc-remove-text-properties-region') -Clears the region (start,end) in object from all colors, etc. - -@item C-c C-t (`erc-set-topic') -Prompt for a topic for the current channel. - -@item C-c C-u (`erc-kill-input') -Kill current input line using `erc-bol' followed by `kill-line'. - -@end table - - -@node Modules, Advanced Usage, Keystroke Summary, Top -@comment node-name, next, previous, up -@chapter Modules -@cindex modules - -One way to add functionality to ERC is to customize which of its many -modules are loaded. - -There is a spiffy customize interface, which may be reached by typing -@kbd{M-x customize-option erc-modules RET}. Alternatively, set -@code{erc-modules} manually and then call @code{erc-update-modules}. - -The following is a list of available modules. - -@table @code - -@cindex modules, autoaway -@item autoaway -Set away status automatically - -@cindex modules, autojoin -@item autojoin -Join channels automatically - -@cindex modules, bbdb -@item bbdb -Integrate with the Big Brother Database - -@cindex modules, button -@item button -Buttonize URLs, nicknames, and other text - -@cindex modules, capab-identify -@item capab-identify -Mark unidentified users on freenode and other servers supporting CAPAB. - -@cindex modules, completion -@cindex modules, pcomplete -@item completion (aka pcomplete) -Complete nicknames and commands (programmable) - -@cindex modules, fill -@item fill -Wrap long lines - -@cindex modules, hecomplete -@item hecomplete -Complete nicknames and commands (old). This is the old module---you -might prefer the ``completion'' module instead. - -@cindex modules, identd -@item identd -Launch an identd server on port 8113 - -@cindex modules, irccontrols -@item irccontrols -Highlight or remove IRC control characters - -@cindex modules, log -@item log -Save buffers in logs - -@cindex modules, match -@item match -Highlight pals, fools, and other keywords - -@cindex modules, menu -@item menu -Display a menu in ERC buffers - -@cindex modules, netsplit -@item netsplit -Detect netsplits - -@cindex modules, noncommands -@item noncommands -Don't display non-IRC commands after evaluation - -@cindex modules, notify -@item notify -Notify when the online status of certain users changes - -@cindex modules, page -@item page -Process CTCP PAGE requests from IRC - -@cindex modules, readonly -@item readonly -Make displayed lines read-only - -@cindex modules, replace -@item replace -Replace text in messages - -@cindex modules, ring -@item ring -Enable an input history - -@cindex modules, scrolltobottom -@item scrolltobottom -Scroll to the bottom of the buffer - -@cindex modules, services -@item services -Identify to Nickserv (IRC Services) automatically - -@cindex modules, smiley -@item smiley -Convert smileys to pretty icons - -@cindex modules, sound -@item sound -Play sounds when you receive CTCP SOUND requests - -@cindex modules, spelling -@item spelling -Check spelling of messages - -@cindex modules, stamp -@item stamp -Add timestamps to messages - -@cindex modules, track -@item track -Track channel activity in the mode-line - -@cindex modules, truncate -@item truncate -Truncate buffers to a certain size - -@cindex modules, unmorse -@item unmorse -Translate morse code in messages - -@end table - -@c PRE5_4: Document every option of every module in its own subnode - - -@node Advanced Usage, Getting Help and Reporting Bugs, Modules, Top -@comment node-name, next, previous, up -@chapter Advanced Usage -@cindex advanced topics - -@menu -* Connecting:: Ways of connecting to an IRC server. -* Sample Configuration:: An example configuration file. -* Options:: Options that are available for ERC. -@end menu - -@node Connecting, Sample Configuration, Advanced Usage, Advanced Usage -@comment node-name, next, previous, up -@section Connecting to an IRC Server -@cindex connecting - -The easiest way to connect to an IRC server is to call @kbd{M-x erc}. -If you want to assign this function to a keystroke, the following will -help you figure out its parameters. - -@defun erc -Select connection parameters and run ERC. -Non-interactively, it takes the following keyword arguments. - -@itemize @bullet -@item @var{server} -@item @var{port} -@item @var{nick} -@item @var{password} -@item @var{full-name} -@end itemize - -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port}, @code{erc-compute-nick} and -@code{erc-compute-full-name} will be invoked for the values of the other -parameters. - -@example -(erc :server "irc.freenode.net" :full-name "Harry S Truman") -@end example -@end defun - -@subheading Server - -@defun erc-compute-server &optional server -Return an IRC server name. - -This tries a number of increasingly more default methods until a non-nil -value is found. - -@itemize @bullet -@item @var{server} (the argument passed to this function) -@item The @code{erc-server} option -@item The value of the IRCSERVER environment variable -@item The @code{erc-default-server} variable -@end itemize - -@end defun - -@defopt erc-server nil -IRC server to use if one is not provided. -@end defopt - -@subheading Port - -@defun erc-compute-port &optional port -Return a port for an IRC server. - -This tries a number of increasingly more default methods until a non-nil -value is found. - -@itemize @bullet -@item @var{port} (the argument passed to this function) -@item The @code{erc-port} option -@item The @code{erc-default-port} variable -@end itemize - -@end defun - -@defopt erc-port -IRC port to use if not specified. - -This can be either a string or a number. -@end defopt - -@subheading Nick - -@defun erc-compute-nick &optional nick -Return user's IRC nick. - -This tries a number of increasingly more default methods until a -non-nil value is found. - -@itemize -@item @var{nick} (the argument passed to this function) -@item The @code{erc-nick} option -@item The value of the IRCNICK environment variable -@item The result from the @code{user-login-name} function -@end itemize - -@end defun - -@defopt erc-nick -Nickname to use if one is not provided. - -This can be either a string, or a list of strings. -In the latter case, if the first nick in the list is already in use, -other nicks are tried in the list order. -@end defopt - -@defopt erc-nick-uniquifier -The string to append to the nick if it is already in use. -@end defopt - -@defopt erc-try-new-nick-p -If the nickname you chose isn't available, and this option is non-nil, -ERC should automatically attempt to connect with another nickname. - -You can manually set another nickname with the /NICK command. -@end defopt - -@subheading Full name - -@defun erc-compute-full-name &optional full-name -Return user's full name. - -This tries a number of increasingly more default methods until a -non-nil value is found. - -@itemize @bullet -@item @var{full-name} (the argument passed to this function) -@item The @code{erc-user-full-name} option -@item The value of the IRCNAME environment variable -@item The result from the @code{user-full-name} function -@end itemize - -@end defun - -@defopt erc-user-full-name -User full name. - -This can be either a string or a function to call. -@end defopt - -@node Sample Configuration, Options, Connecting, Advanced Usage -@comment node-name, next, previous, up -@section Sample Configuration -@cindex configuration, sample - -Here is an example of configuration settings for ERC. This can go into -your Emacs configuration file. Everything after the @code{(require -'erc)} command can optionally go into @file{~/.emacs.d/.ercrc.el}. - -@lisp -;;; Sample ERC configuration - -;; Add the ERC directory to load path -- you don't need this if you are -;; using the version of ERC that comes with Emacs -(add-to-list 'load-path "~/elisp/erc") - -;; Load ERC -(require 'erc) - -;; Load authentication info from an external source. Put sensitive -;; passwords and the like in here. -(load "~/.emacs.d/.erc-auth") - -;; This is an example of how to make a new command. Type "/uptime" to -;; use it. -(defun erc-cmd-UPTIME (&rest ignore) - "Display the uptime of the system, as well as some load-related -stuff, to the current ERC buffer." - (let ((uname-output - (replace-regexp-in-string - ", load average: " "] @{Load average@} [" - ;; Collapse spaces, remove - (replace-regexp-in-string - " +" " " - ;; Remove beginning and trailing whitespace - (replace-regexp-in-string - "^ +\\|[ \n]+$" "" - (shell-command-to-string "uptime")))))) - (erc-send-message - (concat "@{Uptime@} [" uname-output "]")))) - -;; This causes ERC to connect to the Freenode network upon hitting -;; C-c e f. Replace MYNICK with your IRC nick. -(global-set-key "\C-cef" (lambda () (interactive) - (erc :server "irc.freenode.net" :port "6667" - :nick "MYNICK"))) - -;; This causes ERC to connect to the IRC server on your own machine (if -;; you have one) upon hitting C-c e b. Replace MYNICK with your IRC -;; nick. Often, people like to run bitlbee (http://bitlbee.org/) as an -;; AIM/Jabber/MSN to IRC gateway, so that they can use ERC to chat with -;; people on those networks. -(global-set-key "\C-ceb" (lambda () (interactive) - (erc :server "localhost" :port "6667" - :nick "MYNICK"))) - -;; Make C-c RET (or C-c C-RET) send messages instead of RET. This has -;; been commented out to avoid confusing new users. -;; (define-key erc-mode-map (kbd "RET") nil) -;; (define-key erc-mode-map (kbd "C-c RET") 'erc-send-current-line) -;; (define-key erc-mode-map (kbd "C-c C-RET") 'erc-send-current-line) - -;;; Options - -;; Join the #emacs and #erc channels whenever connecting to Freenode. -(setq erc-autojoin-channels-alist '(("freenode.net" "#emacs" "#erc"))) - -;; Interpret mIRC-style color commands in IRC chats -(setq erc-interpret-mirc-color t) - -;; The following are commented out by default, but users of other -;; non-Emacs IRC clients might find them useful. -;; Kill buffers for channels after /part -;; (setq erc-kill-buffer-on-part t) -;; Kill buffers for private queries after quitting the server -;; (setq erc-kill-queries-on-quit t) -;; Kill buffers for server messages after quitting the server -;; (setq erc-kill-server-buffer-on-quit t) -@end lisp - -@node Options, , Sample Configuration, Advanced Usage -@comment node-name, next, previous, up -@section Options -@cindex options - -@c PRE5_4: (Node) Document every ERC option (module options go in -@c previous chapter) - -This section has not yet been written. For now, the easiest way to -check out the available options for ERC is to do -@kbd{M-x customize-group erc RET}. - - -@node Getting Help and Reporting Bugs, History, Advanced Usage, Top -@comment node-name, next, previous, up -@chapter Getting Help and Reporting Bugs -@cindex help, getting -@cindex bugs, reporting - -After you have read this guide, if you still have questions about ERC, -or if you have bugs to report, there are several places you can go. - -@itemize @bullet - -@item -@uref{http://www.emacswiki.org/cgi-bin/wiki/ERC} is the -emacswiki.org page for ERC. Anyone may add tips, hints, or bug -descriptions to it. - -@item -There are several mailing lists for ERC. To subscribe, visit -@uref{http://savannah.gnu.org/mail/?group=erc}. - -The mailing lists are also available on Gmane. -(@url{http://gmane.org/}). Gmane provides additional methods for -accessing the mailing lists, adding content to them, and searching them. - -@enumerate -@item gmane.emacs.erc.announce: Announcements - -@item gmane.emacs.erc.discuss: General discussion - -@item gmane.emacs.erc.cvs: Log messages for changes to the ERC source code - -@end enumerate - -@item -You can visit the IRC Freenode channel @samp{#emacs}. Many of the -contributors are frequently around and willing to answer your -questions. - -@end itemize - - -@node History, Copying, Getting Help and Reporting Bugs, Top -@comment node-name, next, previous, up -@chapter History -@cindex history, of ERC - -ERC was originally written by Alexander L. Belikoff -@email{abel@@bfr.co.il} and Sergey Berezin -@email{sergey.berezin@@cs.cmu.edu}. They stopped development around -December 1999. Their last released version was ERC 2.0. - -P.S.: If one of the original developers of ERC reads this, we'd like to -receive additional information for this file and hear comments in -general. - -@itemize -@item 2001 - -In June 2001, Mario Lang @email{mlang@@delysid.org} and Alex Schroeder -@email{alex@@gnu.org} took over development and created a ERC Project at -@uref{http://sourceforge.net/projects/erc}. - -In reaction to a mail about the new ERC development effort, Sergey -Berezin said, ``First of all, I'm glad that my version of ERC is being -used out there. The thing is, I do not have free time and enough -incentive anymore to work on ERC, so I would be happy if you guys take -over the project entirely.'' - -So we happily hacked away on ERC, and soon after (September 2001) -released the next "stable" version, 2.1. - -Most of the development of the new ERC happened on #emacs on -irc.openprojects.net. Over time, many people contributed code, ideas, -bugfixes, and a lot of alpha/beta/gamma testing. - -See the @file{CREDITS} file for a list of contributors. - -@item 2003 - -ERC 3.0 was released. - -@item 2004 - -ERC 4.0 was released. - -@item 2005 - -ERC 5.0 was released. Michael Olson @email{mwolson@@gnu.org} became -the release manager and eventually the maintainer. - -After some discussion between him and the Emacs developers, it was -decided to include ERC in Emacs. - -@item 2006 - -ERC 5.1 was released. It was subsequently included in Emacs 22. - -ERC became an official GNU project, and development moved to -@uref{http://sv.gnu.org/projects/erc}. We switched to using GNU Arch as -our revision control system. Our mailing list address changed as well. - -@item 2007 - -We switched to using git for our version control system. - -@end itemize - -@node Copying, GNU Free Documentation License, History, Top -@comment node-name, next, previous, up -@include gpl.texi - -@node GNU Free Documentation License, Concept Index, Copying, Top -@comment node-name, next, previous, up -@include doclicense.texi - -@node Concept Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@printindex cp - -@bye - -@ignore - arch-tag: cf9cfaff-fc12-4297-ad15-ec2493002b1e -@end ignore diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi deleted file mode 100644 index e7d4132c4b8..00000000000 --- a/doc/misc/eshell.texi +++ /dev/null @@ -1,942 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/eshell -@settitle Eshell: The Emacs Shell -@synindex vr fn -@c %**end of header - -@copying -This manual is for Eshell, the Emacs shell. - -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Eshell: (eshell). A command shell implemented in Emacs Lisp. -@end direntry - -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp -@center @titlefont{to} -@sp -@center @titlefont{Eshell: The Emacs Shell} -@ignore -@sp 2 -@center release 2.4 -@c -release- -@end ignore -@sp 3 -@center John Wiegley -@c -date- - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@ifnottex -@node Top, What is Eshell?, (dir), (dir) -@top Eshell - -Eshell is a shell-like command interpretor -implemented in Emacs Lisp. It invokes no external processes except for -those requested by the user. It is intended to be a functional -replacement for command shells such as @command{bash}, @command{zsh}, -@command{rc}, or @command{4dos}; since Emacs itself is capable of -handling the sort of tasks accomplished by those tools. -@c This manual is updated to release 2.4 of Eshell. - -@insertcopying -@end ifnottex - -@menu -* What is Eshell?:: A brief introduction to the Emacs Shell. -* Command basics:: The basics of command usage. -* Commands:: -* Arguments:: -* Input/Output:: -* Process control:: -* Extension modules:: -* Extras and Goodies:: -* Bugs and ideas:: Known problems, and future ideas. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: -* Function and Variable Index:: -* Key Index:: -@end menu - -@node What is Eshell? -@chapter What is Eshell? -@cindex what is Eshell? -@cindex Eshell, what it is - -Eshell is a @dfn{command shell} written in Emacs Lisp. Everything it -does, it uses Emacs' facilities to do. This means that Eshell is as -portable as Emacs itself. It also means that cooperation with Lisp code -is natural and seamless. - -What is a command shell? To properly understand the role of a shell, -it's necessary to visualize what a computer does for you. Basically, a -computer is a tool; in order to use that tool, you must tell it what to -do---or give it ``commands.'' These commands take many forms, such as -clicking with a mouse on certain parts of the screen. But that is only -one form of command input. - -By far the most versatile way to express what you want the computer to -do is by using an abbreviated language called @dfn{script}. In -script, instead of telling the computer, ``list my files, please'', -one writes a standard abbreviated command word---@samp{ls}. Typing -@samp{ls} in a command shell is a script way of telling the computer -to list your files.@footnote{This is comparable to viewing the -contents of a folder using a graphical display.} - -The real flexibility of this approach is apparent only when you realize -that there are many, many different ways to list files. Perhaps you -want them sorted by name, sorted by date, in reverse order, or grouped -by type. Most graphical browsers have simple ways to express this. But -what about showing only a few files, or only files that meet a certain -criteria? In very complex and specific situations, the request becomes -too difficult to express using a mouse or pointing device. It is just -these kinds of requests that are easily solved using a command shell. - -For example, what if you want to list every Word file on your hard -drive, larger than 100 kilobytes in size, and which hasn't been looked -at in over six months? That is a good candidate list for deletion, when -you go to clean up your hard drive. But have you ever tried asking your -computer for such a list? There is no way to do it! At least, not -without using a command shell. - -The role of a command shell is to give you more control over what your -computer does for you. Not everyone needs this amount of control, and -it does come at a cost: Learning the necessary script commands to -express what you want done. A complicated query, such as the example -above, takes time to learn. But if you find yourself using your -computer frequently enough, it is more than worthwhile in the long run. -Any tool you use often deserves the time spent learning to master it. -@footnote{For the understandably curious, here is what that command -looks like: But don't let it fool you; once you know what's going on, -it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} - -@menu -* Contributors to Eshell:: People who have helped out! -@end menu - -@node Contributors to Eshell -@section Contributors to Eshell -@cindex contributors -@cindex authors - -Contributions to Eshell are welcome. I have limited time to work on -this project, but I will gladly add any code you contribute to me to -this package. - -The following persons have made contributions to Eshell. - -@itemize @bullet -@item -Eli Zaretskii made it possible for Eshell to run without requiring -asynchronous subprocess support. This is important for MS-DOS, which -does not have such support.@refill - -@item -Miles Bader contributed many fixes during the port to Emacs 21.@refill - -@item -Stefan Monnier fixed the things which bothered him, which of course made -things better for all.@refill - -@item -Gerd Moellmann also helped to contribute bug fixes during the initial -integration with Emacs 21.@refill - -@item -Alex Schroeder contributed code for interactively querying the user -before overwriting files.@refill - -@item -Sudish Joseph helped with some XEmacs compatibility issues.@refill -@end itemize - -Apart from these, a lot of people have sent suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of Eshell. - -@node Command basics -@chapter Basic overview - -A command shell is a means of entering verbally-formed commands. This -is really all that it does, and every feature described in this manual -is a means to that end. Therefore, it's important to take firm hold on -exactly what a command is, and how it fits in the overall picture of -things. - -@menu -* Commands verbs:: Commands always begin with a verb. -* Command arguments:: Some verbs require arguments. -@end menu - -@node Commands verbs -@section Commands verbs - -Commands are expressed using @dfn{script}, a special shorthand language -computers can understand with no trouble. Script is an extremely simple -language; oddly enough, this is what makes it look so complicated! -Whereas normal languages use a variety of embellishments, the form of a -script command is always: - -@example -@var{verb} [@var{arguments}] -@end example - -The verb expresses what you want your computer to do. There are a fixed -number of verbs, although this number is usually quite large. On the -author's computer, it reaches almost 1400 in number. But of course, -only a handful of these are really necessary. - -Sometimes, the verb is all that's written. A verb is always a single -word, usually related to the task it performs. @command{reboot} is a -good example. Entering that on GNU/Linux will reboot the -computer---assuming you have sufficient privileges. - -Other verbs require more information. These are usually very capable -verbs, and must be told specifically what to do. The extra information -is given in the form of @dfn{arguments}. For example, the -@command{echo} verb prints back whatever arguments you type. It -requires these arguments to know what to echo. A proper use of -@command{echo} looks like this: - -@example -echo This is an example of using echo! -@end example - -This script command causes the computer to echo back: ``This is an -example of using echo!'' - -Although command verbs are always simple words, like @command{reboot} or -@command{echo}, arguments may have a wide variety of forms. There are -textual arguments, numerical arguments---even Lisp arguments. -Distinguishing these different types of arguments requires special -typing, for the computer to know exactly what you mean. - -@node Command arguments -@section Command arguments - -Eshell recognizes several different kinds of command arguments: - -@enumerate -@item Strings (also called textual arguments) -@item Numbers (floating point or integer) -@item Lisp lists -@item Lisp symbols -@item Emacs buffers -@item Emacs process handles -@end enumerate - -Most users need to worry only about the first two. The third, Lisp lists, -occur very frequently, but almost always behind the scenes. - -Strings are the most common type of argument, and consist of nearly any -character. Special characters---those used by Eshell -specifically---must be preceded by a backslash (@samp{\}). When in doubt, it -is safe to add backslashes anywhere and everywhere. - -Here is a more complicated @command{echo} example: - -@example -echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar -@end example - -Beyond this, things get a bit more complicated. While not beyond the -reach of someone wishing to learn, it is definitely beyond the scope of -this manual to present it all in a simplistic manner. Get comfortable -with Eshell as a basic command invocation tool, and learn more about the -commands on your system; then come back when it all sits more familiarly -on your mind. Have fun! - -@node Commands -@chapter Commands - -@menu -* Invocation:: -* Completion:: -* Aliases:: -* History:: -* Scripts:: -* Built-ins:: -@end menu - -Essentially, a command shell is all about invoking commands---and -everything that entails. So understanding how Eshell invokes commands -is the key to comprehending how it all works. - -@node Invocation -@section Invocation - -Unlike regular system shells, Eshell never invokes kernel functions -directly, such as @code{exec(3)}. Instead, it uses the Lisp functions -available in the Emacs Lisp library. It does this by transforming the -command you specify into a callable Lisp form.@footnote{To see the Lisp -form that will be invoked, type: @samp{eshell-parse-command "echo -hello"}} - -This transformation, from the string of text typed at the command -prompt, to the ultimate invocation of either a Lisp function or external -command, follows these steps: - -@enumerate -@item Parse the command string into separate arguments. -@item -@end enumerate - -@node Completion -@section Completion - -@node Aliases -@section Aliases - -@node History -@section History - -Eshell knows a few built-in variables: - -@table @code - -@item $+ -@vindex $+ -This variable always contains the current working directory. - -@item $- -@vindex $- -This variable always contains the previous working directory (the -current working directory from before the last @code{cd} command). - -@end table - -@node Scripts -@section Scripts - - -@node Built-ins -@section Built-in commands - -Here is a list of built-in commands that Eshell knows about: - -@table @code - -@item cd -@findex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working -directory. But @code{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. - -With @samp{cd =foo}, Eshell searches the directory stack for a -directory matching the regular expression @samp{foo} and changes to -that directory. - -With @samp{cd -42}, you can access the directory stack by number. - -@end table - - -@node Arguments -@chapter Arguments - -@menu -* The Parser:: -* Variables:: -* Substitution:: -* Globbing:: -* Predicates:: -@end menu - -@node The Parser -@section The Parser - -@node Variables -@section Variables - -@node Substitution -@section Substitution - -@node Globbing -@section Globbing - -@node Predicates -@section Predicates - - -@node Input/Output -@chapter Input/Output - -@node Process control -@chapter Process control - - -@node Extension modules -@chapter Extension modules - -@menu -* Writing a module:: -* Module testing:: -* Directory handling:: -* Key rebinding:: -* Smart scrolling:: -* Terminal emulation:: -* Built-in UNIX commands:: -@end menu - -@node Writing a module -@section Writing a module - -@node Module testing -@section Module testing - -@node Directory handling -@section Directory handling - -@node Key rebinding -@section Key rebinding - -@node Smart scrolling -@section Smart scrolling - -@node Terminal emulation -@section Terminal emulation - -@node Built-in UNIX commands -@section Built-in UNIX commands - - -@node Extras and Goodies -@chapter Extras and Goodies - -@node Bugs and ideas -@chapter Bugs and ideas -@cindex reporting bugs and ideas -@cindex bugs, how to report them -@cindex author, how to reach -@cindex email to the author -@cindex FAQ -@cindex problems, list of common - -If you find a bug or misfeature, don't hesitate to let me know! Send -email to @email{johnw@@gnu.org}. Feature requests should also be sent -there. I prefer discussing one thing at a time. If you find several -unrelated bugs, please report them separately. - -If you have ideas for improvements, or if you have written some -extensions to this package, I would like to hear from you. I hope you -find this package useful! - -@menu -* Known problems:: -@end menu - -@node Known problems -@section Known problems -@cindex known bugs -@cindex bugs, known - -Below is complete list of known problems with Eshell version 2.4.2, -which is the version included with Emacs 22. - -@table @asis -@item Documentation incomplete - -@item Differentiate between aliases and functions - -Allow for a bash-compatible syntax, such as: - -@example -alias arg=blah -function arg () @{ blah $* @} -@end example - -@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt - -In fact, piping to a process from a looping construct doesn't work in -general. If I change the call to @code{eshell-copy-handles} in -@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems -to work, but the output occurs after the prompt is displayed. The whole -structured command thing is too complicated at present. - -@item Error with @command{bc} in @code{eshell-test} - -On some XEmacs system, the subprocess interaction test fails -inexplicably, although @command{bc} works fine at the command prompt. - -@item Eshell does not delete @file{*Help*} buffers in XEmacs 21.1.8+ - -In XEmacs 21.1.8, the @file{*Help*} buffer has been renamed such that -multiple instances of the @file{*Help*} buffer can exist. - -@item Pcomplete sometimes gets stuck - -You press @key{TAB}, but no completions appear, even though the -directory has matching files. This behavior is rare. - -@item @samp{grep python $} doesn't work, but using @samp{*grep} does - -This happens because the @code{grep} Lisp function returns immediately, -and then the asynchronous @command{grep} process expects to examine the -temporary file, which has since been deleted. - -@item Problem with C-r repeating text - -If the text @emph{before point} reads "./run", and you type @kbd{C-r r u -n}, it will repeat the line for every character typed. - -@item Backspace doesn't scroll back after continuing (in smart mode) - -Hitting space during a process invocation, such as @command{make}, will -cause it to track the bottom of the output; but backspace no longer -scrolls back. - -@item It's not possible to fully @code{unload-feature} Eshell - -@item Menu support was removed, but never put back - -@item Using C-p and C-n with rebind gets into a locked state - -This happened a few times in Emacs 21, but has been unreproducible -since. - -@item If an interactive process is currently running, @kbd{M-!} doesn't work - -@item Use a timer instead of @code{sleep-for} when killing child processes - -@item Piping to a Lisp function is not supported - -Make it so that the Lisp command on the right of the pipe is repeatedly -called with the input strings as arguments. This will require changing -@code{eshell-do-pipeline} to handle non-process targets. - -@item Input redirection is not supported - -See the above entry. - -@item Problem running @command{less} without arguments on Windows - -The result in the Eshell buffer is: - -@example -Spawning child process: invalid argument -@end example - -Also a new @command{less} buffer was created with nothing in it@dots{} -(presumably this holds the output of @command{less}). - -If @command{less.exe} is invoked from the Eshell command line, the -expected output is written to the buffer. - -Note that this happens on NT-Emacs 20.6.1 on Windows 2000. The term.el -package and the supplied shell both use the @command{cmdproxy} program -for running shells. - -@item Implement @samp{-r}, @samp{-n} and @samp{-s} switches for @command{cp} - -@item Make @kbd{M-5 M-x eshell} switch to ``*eshell<5>*'', creating if need be - -@item @samp{mv @var{dir} @var{file}.tar} does not remove directories - -This is because the tar option --remove-files doesn't do so. Should it -be Eshell's job? - -@item Bind @code{standard-output} and @code{standard-error} - -This would be so that if a Lisp function calls @code{print}, everything -will happen as it should (albeit slowly). - -@item When an extension module fails to load, @samp{cd /} gives a Lisp error - -@item If a globbing pattern returns one match, should it be a list? - -@item Make sure syntax table is correct in Eshell mode - -So that @kbd{M-DEL} acts in a predictable manner, etc. - -@item Allow all Eshell buffers to share the same history and list-dir - -@item There is a problem with script commands that output to @file{/dev/null} - -If a script file, somewhere in the middle, uses @samp{> /dev/null}, -output from all subsequent commands is swallowed. - -@item Split up parsing of text after @samp{$} in @file{esh-var.el} - -Make it similar to the way that @file{esh-arg.el} is structured. -Then add parsing of @samp{$[?\n]}. - -@item After pressing @kbd{M-RET}, redisplay before running the next command - -@item Argument predicates and modifiers should work anywhere in a path - -@example -/usr/local/src/editors/vim $ vi **/CVS(/)/Root(.) -Invalid regexp: "Unmatched ( or \\(" -@end example - -With @command{zsh}, the glob above expands to all files named -@file{Root} in directories named @file{CVS}. - -@item Typing @samp{echo $@{locate locate@}/bin} results in a Lisp error - -Perhaps it should interpolate all permutations, and make that the -globbing result, since otherwise hitting return here will result in -``(list of filenames)/bin'', which is never valuable. Thus, one could -@command{cat} only C backup files by using @samp{ls $@{identity *.c@}~}. -In that case, having an alias command name @command{glob} for -@command{identity} would be useful. - -@item Once symbolic mode is supported for @command{umask}, implement @command{chmod} in Lisp - -@item Create @code{eshell-expand-file-name} - -This would use a data table to transform things such as @samp{~+}, -@samp{...}, etc. - -@item Abstract @file{em-smart.el} into @file{smart-scroll.el} - -It only really needs: to be hooked onto the output filter and the -pre-command hook, and to have the input-end and input-start markers. -And to know whether the last output group was ``successful.'' - -@item Allow for fully persisting the state of Eshell - -This would include: variables, history, buffer, input, dir stack, etc. - -@item Implement D as an argument predicate - -It means that files beginning with a dot should be included in the -glob match. - -@item A comma in a predicate list should mean OR - -At the moment, this is not supported. - -@item Error if a glob doesn't expand due to a predicate - -An error should be generated only if @code{eshell-error-if-no-glob} is -non-@code{nil}. - -@item @samp{(+ RET SPC TAB} does not cause @code{indent-according-to-mode} to occur - -@item Create @code{eshell-auto-accumulate-list} - -This is a list of commands for which, if the user presses @kbd{RET}, the -text is staged as the next Eshell command, rather than being sent to the -current interactive process. - -@item Display file and line number if an error occurs in a script - -@item @command{wait} doesn't work with process ids at the moment - -@item Enable the direct-to-process input code in @file{em-term.el} - -@item Problem with repeating @samp{echo $@{find /tmp@}} - -With smart display active, if @kbd{RET} is held down, after a while it -can't keep up anymore and starts outputting blank lines. It only -happens if an asynchronous process is involved@dots{} - -I think the problem is that @code{eshell-send-input} is resetting the -input target location, so that if the asynchronous process is not done -by the time the next @kbd{RET} is received, the input processor thinks -that the input is meant for the process; which, when smart display is -enabled, will be the text of the last command line! That is a bug in -itself. - -In holding down @kbd{RET} while an asynchronous process is running, -there will be a point in between termination of the process, and the -running of @code{eshell-post-command-hook}, which would cause -@code{eshell-send-input} to call @code{eshell-copy-old-input}, and then -process that text as a command to be run after the process. Perhaps -there should be a way of killing pending input between the death of the -process, and the @code{post-command-hook}. - -@item Allow for a more aggressive smart display mode - -Perhaps toggled by a command, that makes each output block a smart -display block. - -@item Create more meta variables - -@table @samp -@item $! -The reason for the failure of the last disk command, or the text of the -last Lisp error. - -@item $= -A special associate array, which can take references of the form -@samp{$=[REGEXP]}. It indexes into the directory ring. -@end table - -@item Eshell scripts can't execute in the background - -@item Support zsh's ``Parameter Expansion'' syntax, i.e. @samp{$@{@var{name}:-@var{val}@}} - -@item Write an @command{info} alias that can take arguments - -So that the user can enter @samp{info chmod}, for example. - -@item Create a mode @code{eshell-browse} - -It would treat the Eshell buffer as a outline. Collapsing the outline -hides all of the output text. Collapsing again would show only the -first command run in each directory - -@item Allow other revisions of a file to be referenced using @samp{file@{rev@}} - -This would be expanded by @code{eshell-expand-file-name} (see above). - -@item Print ``You have new mail'' when the ``Mail'' icon is turned on - -@item Implement @kbd{M-|} for Eshell - -@item Implement input redirection - -If it's a Lisp function, input redirection implies @command{xargs} (in a -way@dots{}). If input redirection is added, also update the -@code{file-name-quote-list}, and the delimiter list. - -@item Allow @samp{#<@var{word} @var{arg}>} as a generic syntax - -With the handling of @emph{word} specified by an -@code{eshell-special-alist}. - -@item In @code{eshell-veal-using-options}, allow a @code{:complete} tag - -It would be used to provide completion rules for that command. Then the -macro will automagically define the completion function. - -@item For @code{eshell-command-on-region}, apply redirections to the result - -So that @samp{+ > 'blah} would cause the result of the @code{+} (using -input from the current region) to be inserting into the symbol -@code{blah}. - -If an external command is being invoked, the input is sent as standard -input, as if a @samp{cat |} had been invoked. - -If a Lisp command, or an alias, is invoked, then if the line has no -newline characters, it is divided by whitespace and passed as arguments -to the Lisp function. Otherwise, it is divided at the newline -characters. Thus, invoking @code{+} on a series of numbers will add -them; @code{min} would display the smallest figure, etc. - -@item Write @code{eshell-script-mode} as a minor mode - -It would provide syntax, abbrev, highlighting and indenting support like -@code{emacs-lisp-mode} and @code{shell-mode}. - -@item In the history mechanism, finish the @command{bash}-style support - -This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate -from @samp{!:1*}. - -@item Support the -n command line option for @command{history} - -@item Implement @command{fc} in Lisp - -@item Specifying a frame as a redirection target should imply the currently active window's buffer - -@item Implement @samp{>@var{func-or-func-list}} - -This would allow for an ``output translators'', that take a function to -modify output with, and a target. Devise a syntax that works well with -pipes, and can accommodate multiple functions (i.e., @samp{>'(upcase -regexp-quote)} or @samp{>'upcase}). - -@item Allow Eshell to read/write to/from standard input and output - -This would be optional, rather than always using the Eshell buffer. -This would allow it to be run from the command line (perhaps). - -@item Write a @command{help} command - -It would call subcommands with @option{--help}, or @option{-h} or -@option{/?}, as appropriate. - -@item Implement @command{stty} in Lisp - -@item Support @command{rc}'s matching operator, e.g. @samp{~ (@var{list}) @var{regexp}} - -@item Implement @command{bg} and @command{fg} as editors of @code{eshell-process-list} - -Using @command{bg} on a process that is already in the background does -nothing. Specifying redirection targets replaces (or adds) to the list -current being used. - -@item Have @command{jobs} print only the processes for the current shell - -@item How can Eshell learn if a background process has requested input? - -@item Support @samp{2>&1} and @samp{>&} and @samp{2>} and @samp{|&} - -The syntax table for parsing these should be customizable, such that the -user could change it to use rc syntax: @samp{>[2=1]}. - -@item Allow @samp{$_[-1]}, which would indicate the last element of the array - -@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x} - -Return them as a list, so that @samp{$_[*]} is all the arguments of the -last command. - -@item Copy ANSI code handling from @file{term.el} into @file{em-term.el} - -Make it possible for the user to send char-by-char to the underlying -process. Ultimately, I should be able to move away from using term.el -altogether, since everything but the ANSI code handling is already part -of Eshell. Then, things would work correctly on MS-Windows as well -(which doesn't have @file{/bin/sh}, although @file{term.el} tries to use -it). - -@item Make the shell spawning commands be visual - -That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.) be part of -@code{eshell-visual-commands}. The only exception is if the shell is -being used to invoke a single command. Then, the behavior should be -based on what that command is. - -@item Create a smart viewing command named @command{open} - -This would search for some way to open its argument (similar to opening -a file in the Windows Explorer). - -@item Alias @command{read} to be the same as @command{open}, only read-only - -@item Write a @command{tail} command which uses @code{view-file} - -It would move point to the end of the buffer, and then turns on -auto-revert mode in that buffer at frequent intervals---and a -@command{head} alias which assumes an upper limit of -@code{eshell-maximum-line-length} characters per line. - -@item Make @command{dgrep} load @code{dired}, mark everything, then invoke @code{dired-do-search} - -@item Write mesh.c - -This would run Emacs with the appropriate arguments to invoke Eshell -only. That way, it could be listed as a login shell. - -@item Use an intangible @code{PS2} string for multi-line input prompts - -@item Auto-detect when a command is visual, by checking @code{TERMCAP} usage - -@item The first keypress after @kbd{M-x watson} triggers `eshell-send-input' - -@item Make @kbd{/} electric - -So that it automatically expands and corrects pathnames. Or make -pathname completion for Pcomplete auto-expand @samp{/u/i/std} to -@samp{/usr/include/std}. - -@item Write the @command{pushd} stack to disk along with @code{last-dir-ring} - -@item Add options to @code{eshell/cat} which would allow it to sort and uniq - -@item Implement @command{wc} in Lisp - -Add support for counting sentences, paragraphs, pages, etc. - -@item Once piping is added, implement @command{sort} and @command{uniq} in Lisp - -@item Implement @command{touch} in Lisp - -@item Implement @command{comm} in Lisp - -@item Implement an @command{epatch} command in Lisp - -This would call @code{ediff-patch-file}, or @code{ediff-patch-buffer}, -depending on its argument. - -@item Have an option such that @samp{ls -l} generates a dired buffer - -@item Write a version of @command{xargs} based on command rewriting - -That is, @samp{find X | xargs Y} would be indicated using @samp{Y -$@{find X@}}. Maybe @code{eshell-do-pipelines} could be changed to -perform this on-thy-fly rewriting. - -@item Write an alias for @command{less} that brings up a @code{view-mode} buffer - -Such that the user can press @key{SPC} and @key{DEL}, and then @key{q} -to return to Eshell. It would be equivalent to: -@samp{X > #; view-buffer #}. - -@item Make @code{eshell-mode} as much a full citizen as @code{shell-mode} - -Everywhere in Emacs where @code{shell-mode} is specially noticed, add -@code{eshell-mode} there. - -@item Permit the umask to be selectively set on a @command{cp} target - -@item Problem using @kbd{M-x eshell} after using @code{eshell-command} - -If the first thing that I do after entering Emacs is to run -@code{eshell-command} and invoke @command{ls}, and then use @kbd{M-x -eshell}, it doesn't display anything. - -@item @kbd{M-RET} during a long command (using smart display) doesn't work - -Since it keeps the cursor up where the command was invoked. - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - -@node Function and Variable Index -@unnumbered Function and Variable Index - -@printindex fn - -@node Key Index -@unnumbered Key Index - -@printindex ky -@bye - -@ignore - arch-tag: 776409ba-cb15-42b9-b2b6-d2bdc7ebad01 -@end ignore diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi deleted file mode 100644 index c3adbb44b4a..00000000000 --- a/doc/misc/eudc.texi +++ /dev/null @@ -1,974 +0,0 @@ -\input texinfo.tex -@c %**start of header -@setfilename ../../info/eudc -@settitle Emacs Unified Directory Client (EUDC) Manual -@afourpaper -@c %**end of header - -@copying -This file documents EUDC v1.30b. - -EUDC is the Emacs Unified Directory Client, a common interface to -directory servers using various protocols such as LDAP or the CCSO white -pages directory system (PH/QI) - -Copyright @copyright{} 1998, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* EUDC: (eudc). An Emacs client for directory servers (LDAP, PH). -@end direntry - -@footnotestyle end - -@titlepage -@title{EUDC Manual} -@subtitle{The Emacs Unified Directory Client} -@author by Oscar Figueiredo -@code{1.30b} - -@page -@vskip 0pt plus 1fill -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@comment node-name, next, previous, up - -@insertcopying -@end ifnottex - -@menu -* Overview:: Summary of EUDC features -* Installation:: How to install EUDC -* Usage:: The various usage possibilities explained -* Credits:: Who's done what -* GNU Free Documentation License:: The license for this documentation. -* Command and Function Index:: -* Variables Index:: -@end menu - - - - - -@node Overview, Installation, Top, Top -@comment node-name, next, previous, up -@chapter Overview - -EUDC, the @dfn{Emacs Unified Directory Client}, provides a common user -interface to access directory servers using different directory -protocols. - -Currently supported back-ends are: - -@itemize @bullet -@item -LDAP, Lightweight Directory Access Protocol -@item -CCSO PH/QI -@item -BBDB, Big Brother's Insidious Database -@end itemize - -The main features of the EUDC interface are: - -@itemize @bullet -@item -Queries using a customizable form -@item -Inline query expansion (for instance you can expand a name -to an email address in a mail message buffer using a server as an -address book) -@item -Multiple servers can be tried in turn until a match is found for an -inline query -@item -Fast minibuffer queries for email addresses and phone numbers -@item -Interface to BBDB to let you insert server records into your own BBDB database -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) -@end itemize - -@menu -* LDAP:: What is LDAP ? -* CCSO PH/QI:: What is CCSO, PH, QI ? -* BBDB:: What is BBDB ? -@end menu - - - -@node LDAP, CCSO PH/QI, Overview, Overview -@comment node-name, next, previous, up -@section LDAP - -LDAP, @dfn{the Lightweight Directory Access Protocol}, is a communication -protocol for directory applications defined in RFC 1777. - -Quoted from RFC 1777: - -@quotation -[LDAP] is designed to provide access to the X.500 Directory while not -incurring the resource requirements of the Directory Access Protocol -(DAP). This protocol is specifically targeted at simple management -applications and browser applications that provide simple read/write -interactive access to the X.500 Directory, and is intended to be a -complement to the DAP itself. -@end quotation - -LDAP servers usually store (but are not limited to) information about -people such as their name, phone number, email address, office -location, etc@enddots{} More information about LDAP can be found at -@url{http://www.openldap.org/} - -EUDC requires external support to access LDAP directory servers -(@pxref{LDAP Requirements}) - - -@node CCSO PH/QI, BBDB, LDAP, Overview -@comment node-name, next, previous, up -@section CCSO PH/QI - -The Central Computing Services Office (CCSO) of the University of -Illinois at Urbana Champaign (UIUC) created and freely distributes a -directory system that is currently in use in more than 300 organizations -around the world. The system records information about people such as -their address, phone number, email, academic information or any other -details it was configured to. - -The system consists of two parts: a database server traditionally called -@samp{qi} and a command-line client called @samp{ph}. -@url{ftp://uiarchive.cso.uiuc.edu/pub/packages/ph} is the main -distribution site. @url{http://www.uiuc.edu/cgi-bin/ph/lookup?Query=.} -provides a listing of the active @samp{qi} servers. - -The original command-line @samp{ph} client that comes with the -@samp{ph/qi} distribution provides additional features like the -possibility to communicate with the server in login-mode which makes it -possible to change records in the database. This is not implemented in -EUDC. - - -@node BBDB, , CCSO PH/QI, Overview -@comment node-name, next, previous, up -@section BBDB - -BBDB is the @dfn{Big Brother's Insidious Database}, a package for Emacs -originally written by Jamie Zawinski which provides rolodex-like -database functionality featuring tight integration with the Emacs mail -and news readers. - -It is often used as an enhanced email address book. - -EUDC considers BBDB as a directory server back end just like LDAP or -PH/QI servers, though BBDB has no client/server protocol and thus always -resides locally on your machine. The point in this is not to offer an -alternate way to query your BBDB database (BBDB itself provides much -more flexible ways to do that), but rather to offer an interface to your -local directory that is consistent with the interface to external -directories (LDAP, PH/QI). This is particularly interesting when -performing queries on multiple servers. - -EUDC also offers a means to insert results from directory queries into -your own local BBDB (@pxref{Creating BBDB Records}) - -@node Installation, Usage, Overview, Top -@comment node-name, next, previous, up -@chapter Installation - -Add the following to your @file{.emacs} init file: -@lisp -(require 'eudc) -@end lisp -This will install EUDC at startup. - -After installing EUDC you will find (the next time you launch Emacs) a -new @code{Directory Search} submenu in the @samp{Tools} menu that will -give you access to EUDC. - -You may also find it useful to add the following to your @file{.emacs} -initialization file to add a shortcut for email address expansion in -email composition buffers (@pxref{Inline Query Expansion}) - -@lisp -(eval-after-load - "message" - '(define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -(eval-after-load - "sendmail" - '(define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) -@end lisp - -@menu -* LDAP Requirements:: EUDC needs external support for LDAP -@end menu - -@node LDAP Requirements, , Installation, Installation -@comment node-name, next, previous, up -@section LDAP Requirements - -LDAP support is added by means of @file{ldap.el} which is part of Emacs. -@file{ldap.el} needs an external command line utility named -@file{ldapsearch} which is available as part of LDAP toolkits: - -@itemize @bullet -@item -Open LDAP Libraries -(@url{http://www.openldap.org/}) -@item -University of Michigan's LDAP Client software -(@url{http://www.umich.edu/~dirsvcs/ldap/}) -@end itemize - - -@node Usage, Credits, Installation, Top -@comment node-name, next, previous, up -@chapter Usage - -This chapter describes the usage of EUDC. Most functions and -customization options are available through the @samp{Directory Search} -submenu of the @samp{Tools} submenu. - -@menu -* Querying Servers:: How queries are performed and handled -* Query Form:: How to use and customize the query form -* Display of Query Results:: Controlling how query results are presented -* Inline Query Expansion:: How to use and customize inline queries -* The Server Hotlist:: How to use and manage the server hotlist -* Multi-server Queries:: How to query multiple servers successively -* Creating BBDB Records:: How to insert query results into your BBDB -* Server/Protocol Locals:: Customizing on a per server/protocol basis -@end menu - - -@node Querying Servers, Query Form, Usage, Usage -@comment node-name, next, previous, up -@section Querying Servers - -EUDC's basic functionality is to let you query a directory server and -return the results back to you. There are several things you may want -to customize in this process. - - -@menu -* Selecting a Server:: The first thing to do -* Return Attributes:: Configuring what the server should return -* Duplicate Attributes:: What to do when records have duplicate attributes -@end menu - -@node Selecting a Server, Return Attributes, Querying Servers, Querying Servers -@subsection Selecting a Server - -Before doing any query you will need to set the directory server. You -need to specify the name of the host machine running the server software -and the protocol to use. If you do not set the server in any fashion, -EUDC will ask you for one when you make your first query. - -You can set the server by selecting one from your hotlist of servers -(@pxref{The Server Hotlist}) available in the @samp{Server} submenu or -by selecting @samp{New Server} in that same menu. - -LDAP servers generally require some configuration before you can perform -queries on them. In particular, the @dfn{search base} must be -configured. If the server you select has no configured search base then -EUDC will propose you to configure it at this point. A customization -buffer will be displayed where you can edit the search base and other -parameters for the server. - -@defvar eudc-server -The name or IP address of the remote directory server. A TCP port number -may be specified by appending a colon and a number to the name of the -server. You will not need this unless your server runs on a port other -than the default (which depends on the protocol). -If the directory server resides on your own computer (which is the case -if you use the BBDB back end) then `localhost' is a reasonable value but -it will be ignored anyway. -@end defvar - -@defvar eudc-protocol -The directory protocol to use to query the server. Currently supported -protocols in this version of EUDC are @code{ph}, @code{ldap} and @code{bbdb}. -@end defvar - -@deffn Command eudc-set-server -This command accessible from @samp{New Server} submenu lets you specify a -new directory server and protocol. -@end deffn - -@node Return Attributes, Duplicate Attributes, Selecting a Server, Querying Servers -@subsection Return Attributes - -Directory servers may be configured to return a default set of -attributes for each record matching a query if the query specifies none. -The variable @code{eudc-default-return-attributes} controls the return -attributes you want to see, if different from the server defaults. - -@defvar eudc-default-return-attributes -A list of the default attributes to extract from directory entries. If -set to the symbol @code{all} then all available attributes are -returned. A value of @code{nil}, the default, means to return the -default attributes as configured in the server. -@end defvar - -The server may return several matching records to a query. Some of the -records may however not contain all the attributes you requested. You can -discard those records. - -@defopt eudc-strict-return-matches -If non-@code{nil}, entries that do not contain all the requested return -attributes are ignored. Default is @code{t}. -@end defopt - -@node Duplicate Attributes, , Return Attributes, Querying Servers -@subsection Duplicate Attributes - -Directory standards may authorize different instances of the same -attribute in a record. For instance the record of a person may contain -several email fields containing different email addresses. When using -a QI directory server this is difficult to distinguish from attributes -having multi-line values such as the postal address that may contain a -line for the street and another one for the zip code and city name. In -both cases, EUDC will consider the attribute duplicated. - -EUDC has several methods to deal with duplicated attributes. The -available methods are: - -@table @code -@item list -Makes a list with the different values of the duplicate attribute. The -record is returned with only one instance of the attribute with a list -of all the different values as a value. This is the default method that -is used to handle duplicate fields for which no other method has been -specified. -@item first -Discards all the duplicate values of the field keeping only the first -one. -@item concat -Concatenates the different values using a newline as a separator. The -record keeps only one instance of the field the value of which is a -single multi-line string. -@item duplicate -Duplicates the whole record into as many instances as there are different -values for the field. This is the default for the email field. Thus a -record containing 3 different email addresses is duplicated into three -different records each having a single email address. This is -particularly useful in combination with @code{select} as the method to -handle multiple matches in inline expansion queries (@pxref{Inline Query -Expansion}) because you are presented with the 3 addresses in a -selection buffer -@end table - -Because a method may not be applicable to all fields, the variable -@code{eudc-duplicate-attribute-handling-method} lets you specify either a -default method for all fields or a method for each individual field. - -@defvar eudc-duplicate-attribute-handling-method -A method to handle entries containing duplicate attributes. This is -either an alist of elements @code{(@var{attr} . @var{method})}, or a symbol -@var{method}. The alist form of the variable associates a method to an -individual attribute name; the second form specifies a method applicable -to all attribute names. Available methods are: @code{list}, -@code{first}, @code{concat}, and @code{duplicate} (see above). The default is -@code{list}. -@end defvar - - - -@node Query Form, Display of Query Results, Querying Servers, Usage -@comment node-name, next, previous, up -@section Query Form - -The simplest way to query your directory server is to use the query -form. You display the query form with the @samp{Query with Form} menu -item or by invoking the command @kbd{M-x eudc-query-form}. The attribute -names presented in this form are defined by the -@code{eudc-query-form-attributes} variable (unless a non-@code{nil} -argument is supplied to @code{eudc-query-form}). - -Since the different directory protocols to which EUDC interfaces may -use different names for equivalent attributes, EUDC defines its own set -of attribute names and a mapping between these names and their -protocol-specific equivalent through the variable -@code{eudc-protocol-attributes-translation-alist}. Names currently -defined by EUDC are @code{name}, @code{firstname}, @code{email} and -@code{phone}. - -@defvar eudc-query-form-attributes -@findex eudc-get-attribute-list -A list of attributes presented in the query form. Attribute names in -this list should be either EUDC attribute names or valid attribute -names. You can get a list of valid attribute names for the current -protocol with the @samp{List Valid Attribute Names} menu item or the -@kbd{M-x eudc-get-attribute-list} command. Defaults to @code{name}, -@code{email} and @code{phone}. -@end defvar - -@deffn Command eudc-query-form get-fields-from-server -Display a form to query the directory server. If given a non-@code{nil} -argument the function first queries the server for the existing fields -and displays a corresponding form. Not all protocols may support a -non-@code{nil} argument here. -@end deffn - -Since the names of the fields may not be explicit enough or adapted to -be directly displayed as prompt strings in the form, the variable -@code{eudc-user-attribute-names-alist} lets you define more explicit -names for directory attribute names. This variable is ignored if -@code{eudc-use-raw-directory-names} is non-@code{nil}. - -@defvar eudc-user-attribute-names-alist -This is an alist of user-defined names for the directory attributes used in -query/response forms. Prompt strings for attributes that are not in this -alist are derived by splitting the attribute name at underscores and -capitalizing the individual words. -@end defvar - -@defvar eudc-use-raw-directory-names -If non-@code{nil}, use attributes names as defined in the directory. -Otherwise, directory query/response forms display the user attribute -names defined in @code{eudc-user-attribute-names-alist}. -@end defvar - -@node Display of Query Results, Inline Query Expansion, Query Form, Usage -@comment node-name, next, previous, up -@section Display of Query Results - -Upon successful completion of a form query, EUDC will display a buffer -containing the results of the query. - -The fields that are returned for each record -are controlled by @code{eudc-default-return-attributes} (@pxref{Return -Attributes}). - -The display of each individual field can be performed by an arbitrary -function which allows specific processing for binary values, such as -images or audio samples, as well as values with semantics, such as -URLs. - -@defvar eudc-attribute-display-method-alist -An alist specifying methods to display attribute values. Each member of -the list is of the form @code{(@var{name} . @var{func})} where -@var{name} is a lowercased string naming a directory attribute -(translated according to @code{eudc-user-attribute-names-alist} if -@code{eudc-use-raw-directory-names} is non-@code{nil}) and @var{func} a -function that will be passed the corresponding attribute values for -display. -@end defvar - -This variable has protocol-local definitions (see @pxref{Server/Protocol -Locals}). For instance, it is defined as follows for LDAP: - -@lisp -(eudc-protocol-set 'eudc-attribute-display-method-alist - '(("jpegphoto" . eudc-display-jpeg-inline) - ("labeledurl" . eudc-display-url) - ("audio" . eudc-display-sound) - ("labeledurl" . eudc-display-url) - ("url" . eudc-display-url)) - 'ldap) -@end lisp - -EUDC provides a set of built-in functions to display binary value types: - -@defun eudc-display-generic-binary data -Display a button for unidentified binary @var{data}. -@end defun - -@defun eudc-display-url url -Display URL and make it clickable. -@end defun - -@defun eudc-display-sound data -Display a button to play the sound @var{data}. -@end defun - -@defun eudc-display-jpeg-inline data -Display the JPEG @var{data} inline at point if possible. -@end defun - -@defun eudc-display-jpeg-as-button data -Display a button for the JPEG @var{data}. -@end defun - -Right-clicking on a binary value button pops up a contextual menu with -options to process the value. Among these are saving the attribute -value to a file or sending it to an external viewer command. External -viewers should expect the value on their standard input and should -display it or perform arbitrary processing on it. Messages sent to -standard output are discarded. External viewers are listed in the -variable @code{eudc-external-viewers} which you can customize. - -@defvar eudc-external-viewers -This is a list of viewer program specifications. Each specification is -a list whose first element is a string naming the viewer for unique -identification, the second element is the executable program which -should be invoked and the following elements are arguments that should -be passed to the program. -@end defvar - - -@node Inline Query Expansion, The Server Hotlist, Display of Query Results, Usage -@comment node-name, next, previous, up -@section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, -@code{eudc-expanding-overwrites-query} and -@code{eudc-multiple-match-handling-method}. - -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). - -@deffn Command eudc-expand-inline replace-p -Query the server and expand the query string before point. The query -string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by -@code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. -@end deffn - -@defvar eudc-inline-query-format -Format of an inline expansion query. -This is actually a list of @var{format}s. A @var{format} is a list of -one or more EUDC attribute names. A @var{format} applies if it contains -as many attributes as individual words in the inline query string. If -several @var{format}s apply then they are tried in order until a match -is found. If @code{nil} all the words will be mapped onto the default -server/protocol attribute name (generally @code{name}). - -For instance, use the following -@lisp -(setq eudc-inline-query-format '((name) - (firstname) - (firstname name))) -@end lisp -@noindent -to indicate that single word expansion queries are to be considered as -surnames and if no match is found then they should be tried as first -names. Inline queries consisting of two words are considered as -consisting of a first name followed by a surname. If the query consists -of more than two words, then the first one is considered as the first -name and the remaining words are all considered as surname constituents. - -@var{format}s are in fact not limited to EUDC attribute names, you can -use server or protocol specific names in them. It may be safer if you -do so, to set the variable @code{eudc-inline-query-format} in a protocol -or server local fashion (see @pxref{Server/Protocol Locals}). - -For instance you could use the following to match up to three words -against the @code{cn} attribute of LDAP servers: -@lisp -(eudc-protocol-set 'eudc-inline-query-format - '((cn) - (cn cn) - (cn cn cn)) - 'ldap) -@end lisp -@end defvar - -@defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s" email)} but you may want to consider a value like @code{("%s -<%s>" name email)} -@end defvar - -@defvar eudc-multiple-match-handling-method -This variable controls what to do when multiple entries match a query -for an inline expansion. Possible values are: -@table @code -@item first -The first match is considered as being the only one, the others are -discarded. -@item select -A selection buffer pops up where you can choose a particular match. This -is the default value of the variable. -@item all -The expansion uses all records successively -@item abort -An error is signaled. The expansion aborts. -@end table - -Default is @code{select} -@end defvar - - - -@node The Server Hotlist, Multi-server Queries, Inline Query Expansion, Usage -@comment node-name, next, previous, up -@section The Server Hotlist - -EUDC lets you maintain a list of frequently used servers so that you -can easily switch from one to another. This hotlist appears in the -@samp{Server} submenu. You select a server in this list by clicking on -its name. You can add the current server to the list with the command -@kbd{M-x eudc-bookmark-current-server}. The list is contained in the variable -@code{eudc-server-hotlist} which is stored in and retrieved from the file -designated by @code{eudc-options-file}. EUDC also provides a facility to -edit the hotlist interactively (@pxref{The Hotlist Edit Buffer}). - -The hotlist is also used to make queries on multiple servers -successively (@pxref{Multi-server Queries}). The order in which the -servers are tried is the order they appear in the hotlist, therefore it -is important to sort the hotlist appropriately. - -@deffn Command eudc-bookmark-server server -Add @var{server} to the hotlist of servers -@end deffn - -@deffn Command eudc-bookmark-current-server -Add the current server to the hotlist of servers -@end deffn - -@defvar eudc-options-file -The name of a file where EUDC stores its internal variables -(the hotlist and the current server). EUDC will try to load -that file upon initialization so, if you choose a file name -different from the defaults @file{~/.eudc-options}, be sure to set this -variable to the appropriate value @emph{before} EUDC is itself -loaded. -@end defvar - -@menu -* The Hotlist Edit Buffer:: An interactive hotlist editing facility -@end menu - -@node The Hotlist Edit Buffer, , The Server Hotlist, The Server Hotlist -@comment node-name, next, previous, up -@subsection The Hotlist Edit Buffer - -The hotlist edit buffer offers a means to manage a list of frequently -used servers. Commands are available in the context pop-up menu -generally bound to the right mouse button. Those commands also have -equivalent key bindings. - -@deffn Command eudc-hotlist-add-server -Bound to @kbd{a}. -Add a new server to the hotlist on the line after point -@end deffn - -@deffn Command eudc-hotlist-delete-server -Bound to @kbd{d}. -Delete the server on the line point is on -@end deffn - -@deffn Command eudc-hotlist-select-server -Bound to @kbd{s}. -Select the server the point is on as the current directory server for -the next queries -@end deffn - -@deffn Command eudc-hotlist-transpose-servers -Bound to @kbd{t}. -Bubble up the server the point is on to the top of the list -@end deffn - -@deffn Command eudc-hotlist-quit-edit -Bound to @kbd{q}. -Save the changes and quit the hotlist edit buffer. Use @kbd{x} or -@kbd{M-x kill-buffer} to exit without saving. -@end deffn - - -@node Multi-server Queries, Creating BBDB Records, The Server Hotlist, Usage -@comment node-name, next, previous, up -@section Multi-server Queries - -When using inline query expansion (@pxref{Inline Query Expansion}), EUDC -can try to query successively a sequence of directory servers until one -of them successfully finds a match for the query. - -@defvar eudc-inline-expansion-servers -This variable controls which servers are tried and in which order when -trying to perform an inline query. Possible values are: -@table @code -@item current-server -Only the current directory server is tried -@item hotlist -The servers in the hotlist are tried in order until one finds a match -for the query or `eudc-max-servers-to-query' is reached -@item server-then-hotlist -The current server then the servers in the hotlist are tried in the -order they appear in the hotlist until one of them finds a match or -`eudc-max-servers-to-query' is reached. This is the default. -@end table -@end defvar - -@defvar eudc-max-servers-to-query -This variable indicates the maximum number of servers to query when -performing a multi-server query. The default, @code{nil}, indicates -that all available servers should be tried. -@end defvar - - - -@node Creating BBDB Records, Server/Protocol Locals, Multi-server Queries, Usage -@comment node-name, next, previous, up -@section Creating BBDB Records - -@findex eudc-insert-record-at-point-into-bbdb -@findex eudc-try-bbdb-insert -With EUDC, you can automatically create BBDB records -(@pxref{Top,,BBDB,bbdb,BBDB Manual}) from records you get from a -directory server. You do this by moving point to the appropriate -record in a query result display buffer and invoking the command -@kbd{M-x eudc-insert-record-at-point-into-bbdb} with the -keyboard binding @kbd{b}@footnote{This key binding does not actually -call @code{eudc-insert-record-at-point-into-bbdb} but uses -@code{eudc-try-bbdb-insert} instead.}, or with the menu. EUDC -cannot update an existing BBDB record and will signal an error if you -try to insert a record matching an existing one. - -@findex eudc-batch-export-records-to-bbdb -It is also possible to export to BBDB the whole batch of records -contained in the directory query result with the command -@kbd{M-x eudc-batch-export-records-to-bbdb}. - -Because directory systems may not enforce a strict record format, local -server installations may use different attribute names and have -different ways to organize the information. Furthermore BBDB has its own -record structure. For these reasons converting a record from its -external directory format to the BBDB format is a highly customizable -process. - -@defvar eudc-bbdb-conversion-alist -The value of this variable should be a symbol naming an alist defining a -mapping between BBDB field names onto directory attribute names records. -This is a protocol-local variable and is initialized upon protocol -switch (@pxref{Server/Protocol Locals}). The alist is made of cells of the -form @code{(@var{bbdb-field} . @var{spec-or-list})}. -@var{bbdb-field} is the name of a field -that must be defined in your BBDB environment (standard field names are -@code{name}, @code{company}, @code{net}, @code{phone}, @code{address} -and @code{notes}). -@var{spec-or-list} is either a single mapping specification or a list of -mapping specifications. Lists of mapping specifications are valid for -the @code{phone} and @code{address} BBDB fields only. @var{spec}s are -actually s-expressions which are evaluated as follows: - -@table @asis -@item a string -evaluates to itself -@item a symbol -evaluates to the symbol value. Symbols corresponding to directory -attribute names present in the record evaluate to the value of the field -in the record -@item a form -is evaluated as a function. The argument list may contain attribute -names which evaluate to the corresponding values in the record. The form -evaluation should return something appropriate for the particular -@var{bbdb-field} (see @code{bbdb-create-internal}). -@code{eudc-bbdbify-phone} and @code{eudc-bbdbify-address} are provided as -convenience functions to parse phones and addresses. -@end table -@end defvar - -The default value of the PH-specific value of that variable is -@code{eudc-ph-bbdb-conversion-alist}: - -@lisp -((name . name) - (net . email) - (address . (eudc-bbdbify-address address "Address")) - (phone . ((eudc-bbdbify-phone phone "Phone") - (eudc-bbdbify-phone office_phone "Office Phone")))) -@end lisp - -This means that: - -@itemize @bullet -@item -the @code{name} field of the BBDB record gets its value -from the @code{name} attribute of the directory record -@item -the @code{net} field of the BBDB record gets its value -from the @code{email} attribute of the directory record -@item -the @code{address} field of the BBDB record is obtained by parsing the -@code{address} attribute of the directory record with the function -@code{eudc-bbdbify-address} -@item -two @code{phone} fields are created (when possible) in the BBDB record. -The first one has @cite{Phone} for location and its value is obtained by -parsing the @code{phone} attribute of the PH/QI record with the function -@code{eudc-bbdbify-phone}. The second one has @cite{Office Phone} for location -its value is obtained by parsing the @code{office_phone} attribute of the -PH/QI record with the function @code{eudc-bbdbify-phone}. -@end itemize - -@defun eudc-bbdbify-phone phone location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{phone} into a vector -compatible with @code{bbdb-create-internal}. @var{phone} is either a string -supposedly containing a phone number or a list of such strings which are -concatenated. @var{location} is used as the phone location for BBDB. -@end defun - -@defun eudc-bbdbify-address addr location -This is a convenience function provided for use in -@code{eudc-bbdb-conversion-alist}. It parses @var{addr} into a vector -compatible with @code{bbdb-create-internal}. @var{addr} should be an -address string of no more than four lines or a list of lines. The last -line is searched for the zip code, city and state name. @var{location} -is used as the phone location for BBDB. -@end defun - -Note that only a subset of the attributes you selected with -@code{eudc-default-return-attributes} and that are actually displayed may -actually be inserted as part of the newly created BBDB record. - - -@node Server/Protocol Locals, , Creating BBDB Records, Usage -@comment node-name, next, previous, up -@section Server/Protocol Locals - -EUDC can be customized independently for each server or directory -protocol. All variables can be given local bindings that are activated -when a particular server and/or protocol becomes active. This is much -like buffer-local bindings but on a per server or per protocol basis. - -@menu -* Manipulating local bindings:: Functions to set and query local bindings -@end menu - -@node Manipulating local bindings, , Server/Protocol Locals, Server/Protocol Locals -@comment node-name, next, previous, up -@subsection Manipulating local bindings - -EUDC offers functions that let you set and query variables on a per -server or per protocol basis. - -The following predicates allow you to test the existence of -server/protocol local bindings for a particular variable. - -@defun eudc-server-local-variable-p var -Return non-@code{nil} if @var{var} has server-local bindings -@end defun - -@defun eudc-protocol-local-variable-p var -Return non-@code{nil} if @var{var} has protocol-local bindings -@end defun - -The following functions allow you to set the value of a variable with -various degrees of locality. - -@defun eudc-default-set var val -Set the EUDC default value of @var{var} to @var{val}. -The current binding of @var{var} (if local to the current server or -protocol) is not changed. -@end defun - -@defun eudc-protocol-set var val &optional protocol -Set the binding of @var{var} local to @var{protocol} to @var{val}. If -omitted, @var{protocol} defaults to the current value of -@code{eudc-protocol}. The current binding of @var{var} is changed only -if @var{protocol} is omitted. -@end defun - -@defun eudc-server-set var val &optional server -Set the binding of @var{var} local to @var{server} to @var{val}. If -omitted, @var{server} defaults to the current value of -@code{eudc-server}. The current binding of @var{var} is changed only if -@var{server} is omitted. -@end defun - -@defun eudc-set var val -Set the most local (server, protocol or default) binding of @var{var} to -@var{val}. The current binding of @var{var} is also set to @var{val}. -@end defun - -The following variables allow you to query the various bindings of a -variable (local or non-local). - -@defun eudc-variable-default-value var -Return the default binding of @var{var} (outside of a particular server -or protocol local binding). -Return @code{unbound} if @var{var} has no EUDC default value. -@end defun - -@defun eudc-variable-protocol-value var &optional protocol -Return the value of @var{var} local to @var{protocol}. Return -@code{unbound} if @var{var} has no value local to @var{protocol}. -@var{protocol} defaults to @code{eudc-protocol}. -@end defun - -@defun eudc-variable-server-value var [server] -Return the value of @var{var} local to @var{server}. -Return @code{unbound} if @var{var} has no value local to @var{server}. -@var{server} defaults to @code{eudc-server}. -@end defun - -Changing a protocol-local or server-local value of a variable has no -effect on its current value. The following command is used to -synchronize the current values of variables with their local values -given the current @code{eudc-server} and @code{eudc-protocol}: - -@defun eudc-update-local-variables -Update all EUDC variables according to their local settings. -@end defun - - - -@node Credits, GNU Free Documentation License, Usage, Top -@comment node-name, next, previous, up -@chapter Credits - -EUDC was written by Oscar Figueiredo based on @file{ph.el} by the -same author. - -Thanks to Soren Dayton for his suggestions, his enthusiasm and his help -in testing and proofreading the code and docs of @file{ph.el}. - -@node GNU Free Documentation License, Command and Function Index, Credits, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Command and Function Index, Variables Index, GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Command and Function Index - -@printindex fn - -@node Variables Index, , Command and Function Index, Top -@comment node-name, next, previous, up -@unnumbered Variables Index - -@printindex vr - -@bye - -@ignore - arch-tag: 1b79460b-4ea1-441d-ab45-05ddd16ef241 -@end ignore diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi deleted file mode 100644 index a713d7ccee4..00000000000 --- a/doc/misc/flymake.texi +++ /dev/null @@ -1,755 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/flymake -@set VERSION 0.3 -@set UPDATED April 2004 -@settitle GNU Flymake @value{VERSION} -@syncodeindex pg cp -@comment %**end of header - -@copying -This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), -which is a universal on-the-fly syntax checker for GNU Emacs. - -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Flymake: (flymake). A universal on-the-fly syntax checker. -@end direntry - -@titlepage -@title GNU Flymake -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top GNU Flymake -@insertcopying -@end ifnottex - -@menu -* Overview of Flymake:: -* Installing Flymake:: -* Using Flymake:: -* Configuring Flymake:: -* Flymake Implementation:: -* GNU Free Documentation License:: -* Index:: -@end menu - -@node Overview of Flymake -@chapter Overview -@cindex Overview of Flymake - -Flymake is a universal on-the-fly syntax checker implemented as an -Emacs minor mode. Flymake runs the pre-configured syntax check tool -(compiler for C++ files, @code{perl} for perl files, etc.) in the -background, passing it a temporary copy of the current buffer, and -parses the output for known error/warning message patterns. Flymake -then highlights erroneous lines (i.e. lines for which at least one -error or warning has been reported by the syntax check tool), and -displays an overall buffer status in the mode line. Status information -displayed by Flymake contains total number of errors and warnings -reported for the buffer during the last syntax check. - -@code{flymake-goto-next-error} and @code{flymake-goto-prev-error} -functions allow for easy navigation to the next/previous erroneous -line, respectively. - -Calling @code{flymake-display-err-menu-for-current-line} will popup a -menu containing error messages reported by the syntax check tool for -the current line. Errors/warnings belonging to another file, such as a -@code{.h} header file included by a @code{.c} file, are shown in the -current buffer as belonging to the first line. Menu items for such -messages also contain a filename and a line number. Selecting such a -menu item will automatically open the file and jump to the line with -error. - -Syntax check is done 'on-the-fly'. It is started whenever - -@itemize @bullet -@item buffer is loaded -@item a newline character is added to the buffer -@item some changes were made to the buffer more than @code{0.5} seconds ago (the -delay is configurable). -@end itemize - -Flymake is a universal syntax checker in the sense that it's easily -extended to support new syntax check tools and error message -patterns. @xref{Configuring Flymake}. - -@node Installing Flymake -@chapter Installing -@cindex Installing Flymake - - -Flymake is packaged in a single file, @code{flymake.el}. - -To install/update Flymake, place @code{flymake.el} to a directory -somewhere on Emacs load path. You might also want to byte-compile -@code{flymake.el} to improve performance. - -Also, place the following line in the @code{.emacs} file. - -@lisp -(require 'flymake) -@end lisp - -You might also map the most frequently used Flymake functions, such as -@code{flymake-goto-next-error}, to some keyboard shortcuts: - -@lisp -(global-set-key [f3] 'flymake-display-err-menu-for-current-line) -(global-set-key [f4] 'flymake-goto-next-error) -@end lisp - -@node Using Flymake -@chapter Using Flymake -@cindex Using Flymake - -@menu -* Flymake mode:: -* Running the syntax check:: -* Navigating to error lines:: -* Viewing error messages:: -* Syntax check statuses:: -* Troubleshooting:: -@end menu - -@node Flymake mode -@section Flymake mode -@cindex flymake-mode - -Flymake is an Emacs minor mode. To use Flymake, you -must first activate @code{flymake-mode} by using the -@code{flymake-mode} function. - -Instead of manually activating @code{flymake-mode}, you can configure -Flymake to automatically enable @code{flymake-mode} upon opening any -file for which syntax check is possible. To do so, place the following -line in @code{.emacs}: - -@lisp -(add-hook 'find-file-hook 'flymake-find-file-hook) -@end lisp - -@node Running the syntax check -@section Running the syntax check -@cindex Manually starting the syntax check - -When @code{flymake-mode} is active, syntax check is started -automatically on any of the three conditions mentioned above. Syntax -check can also be started manually by using the -@code{flymake-start-syntax-check-for-current-buffer} function. This -can be used, for example, when changes were made to some other buffer -affecting the current buffer. - -@node Navigating to error lines -@section Navigating to error lines -@cindex Navigating to error lines - -After syntax check is completed, lines for which at least one error or -warning has been reported are highlighted, and total number of errors -and warning is shown in the mode line. Use the following functions to -navigate the highlighted lines. - -@multitable @columnfractions 0.25 0.75 - -@item @code{flymake-goto-next-error} -@tab Moves point to the next erroneous line, if any. - -@item @code{flymake-goto-prev-error} -@tab Moves point to the previous erroneous line. - -@end multitable - -These functions treat erroneous lines as a linked list. Therefore, -@code{flymake-goto-next-error} will go to the first erroneous line -when invoked in the end of the buffer. - -@node Viewing error messages -@section Viewing error messages -@cindex Viewing error messages - -To view error messages belonging to the current line, use the -@code{flymake-display-err-menu-for-current-line} function. If there's -at least one error or warning reported for the current line, this -function will display a popup menu with error/warning texts. -Selecting the menu item whose error belongs to another file brings -forward that file with the help of the -@code{flymake-goto-file-and-line} function. - -@node Syntax check statuses -@section Syntax check statuses -@cindex Syntax check statuses - -After syntax check is finished, its status is displayed in the mode line. -The following statuses are defined. - -@multitable @columnfractions 0.25 0.75 -@item Flymake* or Flymake:E/W* -@tab Flymake is currently running. For the second case, E/W contains the - error and warning count for the previous run. - -@item Flymake -@tab Syntax check is not running. Usually this means syntax check was - successfully passed (no errors, no warnings). Other possibilities are: - syntax check was killed as a result of executing - @code{flymake-compile}, or syntax check cannot start as compilation - is currently in progress. - -@item Flymake:E/W -@tab Number of errors/warnings found by the syntax check process. - -@item Flymake:! -@tab Flymake was unable to find master file for the current buffer. -@end multitable - -The following errors cause a warning message and switch flymake mode -OFF for the buffer. - -@multitable @columnfractions 0.25 0.75 -@item CFGERR -@tab Syntax check process returned nonzero exit code, but no - errors/warnings were reported. This indicates a possible configuration - error (for example, no suitable error message patterns for the - syntax check tool). - -@item NOMASTER -@tab Flymake was unable to find master file for the current buffer. - -@item NOMK -@tab Flymake was unable to find a suitable buildfile for the current buffer. - -@item PROCERR -@tab Flymake was unable to launch a syntax check process. -@end multitable - - -@node Troubleshooting -@section Troubleshooting -@cindex Logging -@cindex Troubleshooting - -Flymake uses a simple logging facility for indicating important points -in the control flow. The logging facility sends logging messages to -the @code{*Messages*} buffer. The information logged can be used for -resolving various problems related to Flymake. - -Logging output is controlled by the @code{flymake-log-level} -variable. @code{3} is the most verbose level, and @code{-1} switches -logging off. - -@node Configuring Flymake -@chapter Configuring and Extending Flymake -@cindex Configuring and Extending Flymake - -@menu -* Customizable variables:: -* Adding support for a new syntax check tool:: -@end menu - -Flymake was designed to be easily extended for supporting new syntax -check tools and error message patterns. - -@node Customizable variables -@section Customizable variables -@cindex Customizable variables - -This section summarizes variables used for Flymake -configuration. - -@table @code -@item flymake-log-level -Controls logging output, see @ref{Troubleshooting}. - -@item flymake-allowed-file-name-masks -A list of @code{(filename-regexp, init-function, cleanup-function -getfname-function)} for configuring syntax check tools. @xref{Adding -support for a new syntax check tool}. - -@item flymake-buildfile-dirs -A list of directories (relative paths) for searching a -buildfile. @xref{Locating the buildfile}. - -@item flymake-master-file-dirs -A list of directories for searching a master file. @xref{Locating a -master file}. - -@item flymake-get-project-include-dirs-function -A function used for obtaining a list of project include dirs (C/C++ -specific). @xref{Getting the include directories}. - -@item flymake-master-file-count-limit -@itemx flymake-check-file-limit -Used when looking for a master file. @xref{Locating a master file}. - -@item flymake-err-line-patterns -Patterns for error/warning messages in the form @code{(regexp file-idx -line-idx col-idx err-text-idx)}. @xref{Parsing the output}. - -@item flymake-compilation-prevents-syntax-check -A flag indicating whether compilation and syntax check of the same -file cannot be run simultaneously. - -@item flymake-no-changes-timeout -If any changes are made to the buffer, syntax check is automatically -started after @code{flymake-no-changes-timeout} seconds. - -@item flymake-gui-warnings-enabled -A boolean flag indicating whether Flymake will show message boxes for -non-recoverable errors. If @code{flymake-gui-warnings-enabled} is -@code{nil}, these errors will only be logged to the @code{*Messages*} -buffer. - -@item flymake-start-syntax-check-on-newline -A boolean flag indicating whether to start syntax check after a -newline character is added to the buffer. - -@item flymake-errline -A custom face for highlighting lines for which at least one error has -been reported. - -@item flymake-warnline -A custom face for highlighting lines for which at least one warning -and no errors have been reported. - -@end table - -@node Adding support for a new syntax check tool -@section Adding support for a new syntax check tool -@cindex Adding support for a new syntax check tool - -@menu -* Example -- Configuring a tool called directly:: -* Example -- Configuring a tool called via make:: -@end menu - -Syntax check tools are configured using the -@code{flymake-allowed-file-name-masks} list. Each item of this list -has the following format: - -@lisp -(filename-regexp, init-function, cleanup-function, getfname-function) -@end lisp - -@table @code -@item filename-regexp -This field is used as a key for locating init/cleanup/getfname -functions for the buffer. Items in -@code{flymake-allowed-file-name-masks} are searched sequentially. The -first item with @code{filename-regexp} matching buffer filename is -selected. If no match is found, @code{flymake-mode} is switched off. - -@item init-function -@code{init-function} is required to initialize the syntax check, -usually by creating a temporary copy of the buffer contents. The -function must return @code{(list cmd-name arg-list)}. If -@code{init-function} returns null, syntax check is aborted, by -@code{flymake-mode} is not switched off. - -@item cleanup-function -@code{cleanup-function} is called after the syntax check process is -complete and should take care of proper deinitialization, which is -usually deleting a temporary copy created by the @code{init-function}. - -@item getfname-function -This function is used for translating filenames reported by the syntax -check tool into ``real'' filenames. Filenames reported by the tool -will be different from the real ones, as actually the tool works with -the temporary copy. In most cases, the default implementation -provided by Flymake, @code{flymake-get-real-file-name}, can be used as -@code{getfname-function}. - -@end table - -To add support for a new syntax check tool, write corresponding -@code{init-function}, and, optionally @code{cleanup-function} and -@code{getfname-function}. If the format of error messages reported by -the new tool is not yet supported by Flymake, add a new entry to -the @code{flymake-err-line-patterns} list. - -The following sections contain some examples of configuring Flymake -support for various syntax check tools. - -@node Example -- Configuring a tool called directly -@subsection Example -- Configuring a tool called directly -@cindex Adding support for perl - -In this example, we will add support for @code{perl} as a syntax check -tool. @code{perl} supports the @code{-c} option which does syntax -checking. - -First, we write the @code{init-function}: - -@lisp -(defun flymake-perl-init () - (let* ((temp-file (flymake-init-create-temp-buffer-copy - 'flymake-create-temp-inplace)) - (local-file (file-relative-name - temp-file - (file-name-directory buffer-file-name)))) - (list "perl" (list "-wc " local-file)))) -@end lisp - -@code{flymake-perl-init} creates a temporary copy of the buffer -contents with the help of -@code{flymake-init-create-temp-buffer-copy}, and builds an appropriate -command line. - -Next, we add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.pl$" - flymake-perl-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -Note that we use standard @code{cleanup-function} and -@code{getfname-function}. - -Finally, we add an entry to @code{flymake-err-line-patterns}: - -@lisp -(setq flymake-err-line-patterns - (cons '("\\(.*\\) at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" - 2 3 nil 1) - flymake-err-line-patterns)) -@end lisp - -@node Example -- Configuring a tool called via make -@subsection Example -- Configuring a tool called via make -@cindex Adding support for C (gcc+make) - -In this example we will add support for C files syntax checked by -@code{gcc} called via @code{make}. - -We're not required to write any new functions, as Flymake already has -functions for @code{make}. We just add a new entry to the -@code{flymake-allowed-file-name-masks}: - -@lisp -(setq flymake-allowed-file-name-masks - (cons '(".+\\.c$" - flymake-simple-make-init - flymake-simple-cleanup - flymake-get-real-file-name) - flymake-allowed-file-name-masks)) -@end lisp - -@code{flymake-simple-make-init} builds the following @code{make} -command line: - -@lisp -(list "make" - (list "-s" "-C" - base-dir - (concat "CHK_SOURCES=" source) - "SYNTAX_CHECK_MODE=1" - "check-syntax")) -@end lisp - -@code{base-dir} is a directory containing @code{Makefile}, see @ref{Locating the buildfile}. - -Thus, @code{Makefile} must contain the @code{check-syntax} target. In -our case this target might look like this: - -@verbatim -check-syntax: - gcc -o nul -S ${CHK_SOURCES} -@end verbatim - -The format of error messages reported by @code{gcc} is already -supported by Flymake, so we don't have to add a new entry to -@code{flymake-err-line-patterns}. - -@node Flymake Implementation -@chapter Flymake Implementation -@cindex Implementation details - -@menu -* Determining whether syntax check is possible:: -* Making a temporary copy:: -* Locating a master file:: -* Getting the include directories:: -* Locating the buildfile:: -* Starting the syntax check process:: -* Parsing the output:: -* Highlighting erroneous lines:: -* Interaction with other modes:: -@end menu - -Syntax check is started by calling @code{flymake-start-syntax-check-for-current-buffer}. -Flymake first determines whether it is able to do syntax -check. It then saves a copy of the buffer in a temporary file in the -buffer's directory (or in the system temp directory -- for java -files), creates a syntax check command and launches a process with -this command. The output is parsed using a list of error message patterns, -and error information (file name, line number, type and text) is -saved. After the process has finished, Flymake highlights erroneous -lines in the buffer using the accumulated error information. - -@node Determining whether syntax check is possible -@section Determining whether syntax check is possible -@cindex Syntax check models -@cindex Master file - -Syntax check is considered possible if there's an entry in -@code{flymake-allowed-file-name-masks} matching buffer's filename and -its @code{init-function} returns non-@code{nil} value. - -Two syntax check modes are distinguished: - -@enumerate - -@item -Buffer can be syntax checked in a standalone fashion, that is, the -file (its temporary copy, in fact) can be passed over to the compiler to -do the syntax check. Examples are C/C++ (.c, .cpp) and Java (.java) -sources. - -@item -Buffer can be syntax checked, but additional file, called master file, -is required to perform this operation. A master file is a file that -includes the current file, so that running a syntax check tool on it -will also check syntax in the current file. Examples are C/C++ (.h, -.hpp) headers. - -@end enumerate - -These modes are handled inside init/cleanup/getfname functions, see -@ref{Adding support for a new syntax check tool}. - -Flymake contains implementations of all functionality required to -support different syntax check modes described above (making -temporary copies, finding master files, etc.), as well as some -tool-specific (routines for @code{make}, @code{Ant}, etc.) code. - - -@node Making a temporary copy -@section Making a temporary copy -@cindex Temporary copy of the buffer -@cindex Master file - -After the possibility of the syntax check has been determined, a -temporary copy of the current buffer is made so that the most recent -unsaved changes could be seen by the syntax check tool. Making a copy -is quite straightforward in a standalone case (mode @code{1}), as it's -just saving buffer contents to a temporary file. - -Things get trickier, however, when master file is involved, as it -requires to - -@itemize @bullet -@item locate a master file -@item patch it to include the current file using its new (temporary) -name. -@end itemize - -Locating a master file is discussed in the following section. - -Patching just changes all appropriate lines of the master file so that they -use the new (temporary) name of the current file. For example, suppose current -file name is @code{file.h}, the master file is @code{file.cpp}, and -it includes current file via @code{#include "file.h"}. Current file's copy -is saved to file @code{file_flymake.h}, so the include line must be -changed to @code{#include "file_flymake.h"}. Finally, patched master file -is saved to @code{file_flymake_master.cpp}, and the last one is passed to -the syntax check tool. - -@node Locating a master file -@section Locating a master file -@cindex Master file - -Master file is located in two steps. - -First, a list of possible master files is built. A simple name -matching is used to find the files. For a C++ header @code{file.h}, -Flymake searches for all @code{.cpp} files in the directories whose relative paths are -stored in a customizable variable @code{flymake-master-file-dirs}, which -usually contains something like @code{("." "./src")}. No more than -@code{flymake-master-file-count-limit} entries is added to the master file -list. The list is then sorted to move files with names @code{file.cpp} to -the top. - -Next, each master file in a list is checked to contain the appropriate -include directives. No more than @code{flymake-check-file-limit} of each -file are parsed. - -For @code{file.h}, the include directives to look for are -@code{#include "file.h"}, @code{#include "../file.h"}, etc. Each -include is checked against a list of include directories -(see @ref{Getting the include directories}) to be sure it points to the -correct @code{file.h}. - -First matching master file found stops the search. The master file is then -patched and saved to disk. In case no master file is found, syntax check is -aborted, and corresponding status (!) is reported in the mode line. - -@node Getting the include directories -@section Getting the include directories -@cindex Include directories (C/C++ specific) - -Two sets of include directories are distinguished: system include directories -and project include directories. The former is just the contents of the -@code{INCLUDE} environment variable. The latter is not so easy to obtain, -and the way it can be obtained can vary greatly for different projects. -Therefore, a customizable variable -@code{flymake-get-project-include-dirs-function} is used to provide the -way to implement the desired behavior. - -The default implementation, @code{flymake-get-project-include-dirs-imp}, -uses a @code{make} call. This requires a correct base directory, that is, a -directory containing a correct @code{Makefile}, to be determined. - -As obtaining the project include directories might be a costly operation, its -return value is cached in the hash table. The cache is cleared in the beginning -of every syntax check attempt. - -@node Locating the buildfile -@section Locating the buildfile -@cindex Locating the buildfile -@cindex buildfile, locating -@cindex Makefile, locating - -Flymake can be configured to use different tools for performing syntax -checks. For example, it can use direct compiler call to syntax check a perl -script or a call to @code{make} for a more complicated case of a -@code{C/C++} source. The general idea is that simple files, like perl -scripts and html pages, can be checked by directly invoking a -corresponding tool. Files that are usually more complex and generally -used as part of larger projects, might require non-trivial options to -be passed to the syntax check tool, like include directories for -C++. The latter files are syntax checked using some build tool, like -@code{make} or @code{Ant}. - -All @code{make} configuration data is usually stored in a file called -@code{Makefile}. To allow for future extensions, flymake uses a notion of -buildfile to reference the 'project configuration' file. - -Special function, @code{flymake-find-buildfile} is provided for locating buildfiles. -Searching for a buildfile is done in a manner similar to that of searching -for possible master files. A customizable variable -@code{flymake-buildfile-dirs} holds a list of relative paths to the -buildfile. They are checked sequentially until a buildfile is found. In case -there's no build file, syntax check is aborted. - -Buildfile values are also cached. - -@node Starting the syntax check process -@section Starting the syntax check process -@cindex Syntax check process - -The command line (command name and the list of arguments) for launching a process is returned by the -initialization function. Flymake then just calls @code{start-process} -to start an asynchronous process and configures process filter and -sentinel which is used for processing the output of the syntax check -tool. - -@node Parsing the output -@section Parsing the output -@cindex Parsing the output - -The output generated by the syntax check tool is parsed in the process -filter/sentinel using the error message patterns stored in the -@code{flymake-err-line-patterns} variable. This variable contains a -list of items of the form @code{(regexp file-idx line-idx -err-text-idx)}, used to determine whether a particular line is an -error message and extract file name, line number and error text, -respectively. Error type (error/warning) is also guessed by matching -error text with the '@code{^[wW]arning}' pattern. Anything that was not -classified as a warning is considered an error. Type is then used to -sort error menu items, which shows error messages first. - -Flymake is also able to interpret error message patterns missing err-text-idx -information. This is done by merely taking the rest of the matched line -(@code{(substring line (match-end 0))}) as error text. This trick allows -to make use of a huge collection of error message line patterns from -@code{compile.el}. All these error patterns are appended to -the end of @code{flymake-err-line-patterns}. - -The error information obtained is saved in a buffer local -variable. The buffer for which the process output belongs is -determined from the process-id@w{}->@w{}buffer mapping updated -after every process launch/exit. - -@node Highlighting erroneous lines -@section Highlighting erroneous lines -@cindex Erroneous lines, faces - -Highlighting is implemented with overlays and happens in the process -sentinel, after calling the cleanup function. Two customizable faces -are used: @code{flymake-errline} and -@code{flymake-warnline}. Errors belonging outside the current -buffer are considered to belong to line 1 of the current buffer. - -@node Interaction with other modes -@section Interaction with other modes -@cindex Interaction with other modes -@cindex Interaction with compile mode - -The only mode flymake currently knows about is @code{compile}. - -Flymake can be configured to not start syntax check if it thinks the -compilation is in progress. The check is made by the -@code{flymake-compilation-is-running}, which tests the -@code{compilation-in-progress} variable. The reason why this might be -useful is saving CPU time in case both syntax check and compilation -are very CPU intensive. The original reason for adding this feature, -though, was working around a locking problem with MS Visual C++ compiler. - -Flymake also provides an alternative command for starting compilation, -@code{flymake-compile}: - -@lisp -(defun flymake-compile () - "Kill all flymake syntax checks then start compilation." - (interactive) - (flymake-stop-all-syntax-checks) - (call-interactively 'compile)) -@end lisp - -It just kills all the active syntax check processes before calling -@code{compile}. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye - -@ignore - arch-tag: 9f0db077-5598-49ab-90b9-8df9248a63ec -@end ignore diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi deleted file mode 100644 index 4f6280b47ca..00000000000 --- a/doc/misc/forms.texi +++ /dev/null @@ -1,982 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c documentation for forms-mode -@c Written by Johan Vromans, and edited by Richard Stallman - -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/forms -@settitle Forms Mode User's Manual -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex ky cp -@iftex -@finalout -@setchapternewpage odd -@end iftex -@c @smallbook -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This file documents Forms mode, a form-editing major mode for GNU Emacs. - -Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Forms: (forms). Emacs package for editing data bases - by filling in forms. -@end direntry - -@titlepage -@sp 6 -@center @titlefont{Forms Mode User's Manual} -@sp 4 -@center Forms-Mode version 2 -@sp 1 -@center for GNU Emacs 22.1 -@sp 1 -@center April 2007 -@sp 5 -@center Johan Vromans -@center @i{jvromans@@squirrel.nl} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Forms Mode - -Forms mode is an Emacs major mode for working with simple textual data -bases in a forms-oriented manner. In Forms mode, the information in -these files is presented in an Emacs window in a user-defined format, -one record at a time. The user can view records or modify their -contents. - -Forms mode is not a simple major mode, but requires two files to do its -job: a control file and a data file. The data file holds the -actual data to be presented. The control file describes -how to present it. - -@insertcopying - -@menu -* Forms Example:: An example: editing the password data base. -* Entering and Exiting Forms Mode:: - How to visit a file in Forms mode. -* Forms Commands:: Special commands to use while in Forms mode. -* Data File Format:: How to format the data file. -* Control File Format:: How to control forms mode. -* Format Description:: How to define the forms layout. -* Modifying Forms Contents:: How to modify. -* Miscellaneous:: Forms mode messages and other remarks. -* Error Messages:: List of error messages forms mode can produce. -* Long Example:: A more complex control file example. -* GNU Free Documentation License:: The license for this documentation. -* Credits:: Thanks everyone. -* Index:: Index to this manual. -@end menu -@end ifnottex - -@node Forms Example -@chapter Forms Example - -Let's illustrate Forms mode with an example. Suppose you are looking at -the @file{/etc/passwd} file, and the screen looks like this: - -@example -====== /etc/passwd ====== - -User : root Uid: 0 Gid: 1 - -Name : Super User - -Home : / - -Shell: /bin/sh -@end example - -As you can see, the familiar fields from the entry for the super user -are all there, but instead of being colon-separated on one single line, -they make up a forms. - -The contents of the forms consist of the contents of the fields of the -record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) -interspersed with normal text (e.g @samp{User : }, @samp{Uid: }). - -If you modify the contents of the fields, Forms mode will analyze your -changes and update the file appropriately. You cannot modify the -interspersed explanatory text (unless you go to some trouble about it), -because that is marked read-only (@pxref{Text Properties,,, elisp, The -Emacs Lisp Reference Manual}). - -The Forms mode control file specifies the relationship between the -format of @file{/etc/passwd} and what appears on the screen in Forms -mode. @xref{Control File Format}. - -@node Entering and Exiting Forms Mode -@chapter Entering and Exiting Forms Mode - -@table @kbd -@findex forms-find-file -@item M-x forms-find-file @key{RET} @var{control-file} @key{RET} -Visit a database using Forms mode. Specify the name of the -@strong{control file}, not the data file! - -@findex forms-find-file-other-window -@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} -Similar, but displays the file in another window. -@end table - -The command @code{forms-find-file} evaluates the file -@var{control-file}, and also visits it in Forms mode. What you see in -its buffer is not the contents of this file, but rather a single record -of the corresponding data file that is visited in its own buffer. So -there are two buffers involved in Forms mode: the @dfn{forms buffer} -that is initially used to visit the control file and that shows the -records being browsed, and the @dfn{data buffer} that holds the data -file being visited. The latter buffer is normally not visible. - -Initially, the first record is displayed in the forms buffer. -The mode line displays the major mode name @samp{Forms}, followed by the -minor mode @samp{View} if the data base is read-only. The number of the -current record (@var{n}) and the total number of records in the -file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For -example: - -@example ---%%-Emacs: passwd-demo (Forms View 1/54)----All------- -@end example - -If the buffer is not read-only, you may change the buffer to modify the -fields in the record. When you move to a different record, the contents -of the buffer are parsed using the specifications in -@code{forms-format-list}, and the data file is updated. If the record -has fields that aren't included in the display, they are not changed. - -@vindex forms-mode-hooks -Entering Forms mode runs the normal hook @code{forms-mode-hooks} to -perform user-defined customization. - -To save any modified data, you can use @kbd{C-x C-s} -(@code{forms-save-buffer}). This does not save the forms buffer (which would -be rather useless), but instead saves the buffer visiting the data file. - -To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) -and then kill the forms buffer. However, the data buffer will still -remain. If this is not desired, you have to kill this buffer too. - -@node Forms Commands -@chapter Forms Commands - -The commands of Forms mode belong to the @kbd{C-c} prefix, with one -exception: @key{TAB}, which moves to the next field. Forms mode uses -different key maps for normal mode and read-only mode. In read-only -Forms mode, you can access most of the commands without the @kbd{C-c} -prefix, but you must type ordinary letters instead of control -characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. - -If your Emacs has been built with X-toolkit support, Forms mode will -provide its own menu with a number of Forms mode commands. - -@table @kbd -@findex forms-next-record -@kindex C-c C-n -@item C-c C-n -Show the next record (@code{forms-next-record}). With a numeric -argument @var{n}, show the @var{n}th next record. - -@findex forms-prev-record -@kindex C-c C-p -@item C-c C-p -Show the previous record (@code{forms-prev-record}). With a numeric -argument @var{n}, show the @var{n}th previous record. - -@findex forms-jump-record -@kindex C-c C-l -@item C-c C-l -Jump to a record by number (@code{forms-jump-record}). Specify -the record number with a numeric argument. - -@findex forms-first-record -@kindex C-c < -@item C-c < -Jump to the first record (@code{forms-first-record}). - -@findex forms-last-record -@kindex C-c > -@item C-c > -Jump to the last record (@code{forms-last-record}). This command also -recalculates the number of records in the data file. - -@findex forms-next-field -@kindex TAB -@item @key{TAB} -@kindex C-c TAB -@itemx C-c @key{TAB} -Jump to the next field in the current record (@code{forms-next-field}). -With a numeric argument @var{n}, jump forward @var{n} fields. If this command -would move past the last field, it wraps around to the first field. - -@findex forms-toggle-read-only -@kindex C-c C-q -@item C-c C-q -Toggles read-only mode (@code{forms-toggle-read-only}). In read-only -Forms mode, you cannot edit the fields; most Forms mode commands can be -accessed without the prefix @kbd{C-c} if you use the normal letter -instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit -mode, you can edit the fields and thus change the contents of the data -base; you must begin Forms mode commands with @code{C-c}. Switching -to edit mode is allowed only if you have write access to the data file. - -@findex forms-insert-record -@kindex C-c C-o -@item C-c C-o -Create a new record and insert it before the current record -(@code{forms-insert-record}). It starts out with empty (or default) -contents for its fields; you can then edit the fields. With a numeric -argument, the new record is created @emph{after} the current one. -See also @code{forms-modified-record-filter} in @ref{Modifying Forms -Contents}. - -@findex forms-delete-record -@kindex C-c C-k -@item C-c C-k -Delete the current record (@code{forms-delete-record}). You are -prompted for confirmation before the record is deleted unless a numeric -argument has been provided. - -@findex forms-search-forward -@kindex C-c C-s @var{regexp} @key{RET} -@item C-c C-s @var{regexp} @key{RET} -Search forward for @var{regexp} in all records following this one -(@code{forms-search-forward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@findex forms-search-backward -@kindex C-c C-r @var{regexp} @key{RET} -@item C-c C-r @var{regexp} @key{RET} -Search backward for @var{regexp} in all records following this one -(@code{forms-search-backward}). If found, this record is shown. -If you give an empty argument, the previous regexp is used again. - -@ignore -@findex forms-exit -@kindex C-c C-x -@item C-c C-x -Terminate Forms mode processing (@code{forms-exit}). The data file is -saved if it has been modified. - -@findex forms-exit-no-save -@item M-x forms-exit-no-save -Terminates forms mode processing without saving modified data first. -@end ignore - -@findex forms-prev-field -@item M-x forms-prev-field -Similar to @code{forms-next-field} but moves backwards. - -@findex forms-save-buffer -@item M-x forms-save-buffer -@kindex C-x C-s -@itemx C-x C-s -Forms mode replacement for @code{save-buffer}. When executed in the -forms buffer it will save the contents of the (modified) data buffer -instead. In Forms mode this function will be bound to @kbd{C-x C-s}. - -@findex forms-print -@item M-x forms-print -This command can be used to make a formatted print -of the contents of the data file. - -@end table - -In addition the command @kbd{M-x revert-buffer} is useful in Forms mode -just as in other modes. - -@ignore -@vindex forms-forms-scroll -@findex scroll-up -@findex scroll-down -If the variable @code{forms-forms-scrolls} is set to a value other -than @code{nil} (which it is, by default), the Emacs functions -@code{scroll-up} and @code{scroll-down} will perform a -@code{forms-next-record} and @code{forms-prev-record} when in forms -mode. So you can use your favorite page commands to page through the -data file. - -@vindex forms-forms-jump -@findex beginning-of-buffer -@findex end-of-buffer -Likewise, if the variable @code{forms-forms-jump} is not @code{nil} -(which it is, by default), Emacs functions @code{beginning-of-buffer} -and @code{end-of-buffer} will perform @code{forms-first-record} and -@code{forms-last-record} when in forms mode. -@end ignore - -The following function key definitions are set up in Forms mode -(whether read-only or not): - -@table @kbd -@kindex next -@item next -forms-next-record - -@kindex prior -@item prior -forms-prev-record - -@kindex begin -@item begin -forms-first-record - -@kindex end -@item end -forms-last-record - -@kindex S-Tab -@findex forms-prev-field -@item S-Tab -forms-prev-field -@end table - -@node Data File Format -@chapter Data File Format - -@cindex record -@cindex field -@vindex forms-field-sep -Files for use with Forms mode are very simple---each @dfn{record} -(usually one line) forms the contents of one form. Each record consists -of a number of @dfn{fields}, which are separated by the value of the -string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. - -@vindex forms-read-file-filter -@vindex forms-write-file-filter -If the format of the data file is not suitable enough you can define the -filter functions @code{forms-read-file-filter} and -@code{forms-write-file-filter}. @code{forms-read-file-filter} is called -when the data file is read from disk into the data buffer. It operates -on the data buffer, ignoring read-only protections. When the data file -is saved to disk @code{forms-write-file-filter} is called to cancel the -effects of @code{forms-read-file-filter}. After being saved, -@code{forms-read-file-filter} is called again to prepare the data buffer -for further processing. - -@cindex pseudo-newline -@vindex forms-multi-line -Fields may contain text which shows up in the forms in multiple lines. -These lines are separated in the field using a ``pseudo-newline'' -character which is defined by the value of the string -@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K -character). If it is -set to @code{nil}, multiple line fields are prohibited. - -If the data file does not exist, it is automatically created. - -@node Control File Format -@chapter Control File Format - -@cindex control file -The Forms mode @dfn{control file} serves two purposes. First, it names -the data file to use, and defines its format and properties. Second, -the Emacs buffer it occupies is used by Forms mode to display the forms. - -The contents of the control file are evaluated as a Lisp program. It -should set the following Lisp variables to suitable values: - -@table @code -@vindex forms-file -@item forms-file -This variable specifies the name of the data file. Example: - -@example -(setq forms-file "my/data-file") -@end example - -If the control file doesn't set @code{forms-file}, Forms mode -reports an error. - -@vindex forms-format-list -@item forms-format-list -This variable describes the way the fields of the record are formatted on -the screen. For details, see @ref{Format Description}. - -@vindex forms-number-of-fields -@item forms-number-of-fields -This variable holds the number of fields in each record of the data -file. Example: - -@example -(setq forms-number-of-fields 10) -@end example -@end table - -If the control file does not set @code{forms-format-list} a default -format is used. In this situation, Forms mode will deduce the number of -fields from the data file providing this file exists and -@code{forms-number-of-records} has not been set in the control file. - -The control file can optionally set the following additional Forms mode -variables. Most of them have default values that are good for most -applications. - -@table @code -@vindex forms-field-sep -@item forms-field-sep -This variable may be used to designate the string which separates the -fields in the records of the data file. If not set, it defaults to the -string @code{"\t"} (a Tab character). Example: - -@example -(setq forms-field-sep "\t") -@end example - -@vindex forms-read-only -@item forms-read-only -If the value is non-@code{nil}, the data file is treated read-only. (Forms -mode also treats the data file as read-only if you don't have access to -write it.) Example: - -@example -(set forms-read-only t) -@end example - -@vindex forms-multi-line -@item forms-multi-line -This variable specifies the @dfn{pseudo newline} separator that allows -multi-line fields. This separator goes between the ``lines'' within a -field---thus, the field doesn't really contain multiple lines, but it -appears that way when displayed in Forms mode. If the value is -@code{nil}, multi-line text fields are prohibited. The pseudo newline -must not be a character contained in @code{forms-field-sep}. - -The default value is @code{"\^k"}, the character Control-K. Example: - -@example -(setq forms-multi-line "\^k") -@end example - -@ignore -@vindex forms-forms-scroll -@item forms-forms-scroll -@xref{Forms Mode Commands}, for details. - -@vindex forms-forms-jump -@item forms-forms-jump -@xref{Forms Mode Commands}, for details. -@end ignore - -@findex forms-read-file-filter -@item forms-read-file-filter -This variable holds the name of a function to be called after the data -file has been read in. This can be used to transform the contents of the -data file into a format more suitable for forms processing. -If it is @code{nil}, no function is called. For example, to maintain a -gzipped database: - -@example -(defun gzip-read-file-filter () - (shell-command-on-region (point-min) (point-max) - "gzip -d" t t)) -(setq forms-read-file-filter 'gzip-read-file-filter) -@end example - -@findex forms-write-file-filter -@item forms-write-file-filter -This variable holds the name of a function to be called before writing -out the contents of the data file. -This can be used to undo the effects of @code{forms-read-file-filter}. -If it is @code{nil}, no function is called. Example: - -@example -(defun gzip-write-file-filter () - (make-variable-buffer-local 'require-final-newline) - (setq require-final-newline nil) - (shell-command-on-region (point-min) (point-max) - "gzip" t t)) -(setq forms-write-file-filter 'gzip-write-file-filter) -@end example - -@findex forms-new-record-filter -@item forms-new-record-filter -This variable holds a function to be called whenever a new record is created -to supply default values for fields. If it is @code{nil}, no function is -called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-modified-record-filter -@item forms-modified-record-filter -This variable holds a function to be called whenever a record is -modified, just before updating the Forms data file. If it is -@code{nil}, no function is called. -@xref{Modifying Forms Contents}, for details. - -@findex forms-insert-after -@item forms-insert-after -If this variable is not @code{nil}, new records are created @emph{after} the -current record. Also, upon visiting a file, the initial position will be -at the last record instead of the first one. - -@findex forms-check-number-of-fields -@item forms-check-number-of-fields -Normally each record is checked to contain the correct number of fields. -Under certain circumstances, this can be undesirable. -If this variable is set to @code{nil}, these checks will be bypassed. -@end table - -@node Format Description -@chapter The Format Description - -@vindex forms-format-list - The variable @code{forms-format-list} specifies the format of the data -in the data file, and how to convert the data for display in Forms mode. -Its value must be a list of Forms mode @dfn{formatting elements}, each -of which can be a string, a number, a Lisp list, or a Lisp symbol that -evaluates to one of those. The formatting elements are processed in the -order they appear in the list. - -@table @var -@item string -A string formatting element is inserted in the forms ``as is,'' as text -that the user cannot alter. - -@item number -A number element selects a field of the record. The contents of this -field are inserted in the display at this point. Field numbers count -starting from 1 (one). - -@item list -A formatting element that is a list specifies a function call. This -function is called every time a record is displayed, and its result, -which must be a string, is inserted in the display text. The function -should do nothing but returning a string. - -@vindex forms-fields -The function you call can access the fields of the record as a list in -the variable -@code{forms-fields}. - -@item symbol -A symbol used as a formatting element should evaluate to a string, number, -or list; the value is interpreted as a formatting element, as described -above. -@end table - -If a record does not contain the number of fields as specified in -@code{forms-number-of-fields}, a warning message will be printed. Excess -fields are ignored, missing fields are set to empty. - -The control file which displays @file{/etc/passwd} file as demonstrated -in the beginning of this manual might look as follows: - -@example -;; @r{This demo visits @file{/etc/passwd}.} - -(setq forms-file "/etc/passwd") -(setq forms-number-of-fields 7) -(setq forms-read-only t) ; @r{to make sure} -(setq forms-field-sep ":") -;; @r{Don't allow multi-line fields.} -(setq forms-multi-line nil) - -(setq forms-format-list - (list - "====== /etc/passwd ======\n\n" - "User : " 1 - " Uid: " 3 - " Gid: " 4 - "\n\n" - "Name : " 5 - "\n\n" - "Home : " 6 - "\n\n" - "Shell: " 7 - "\n")) -@end example - -When you construct the value of @code{forms-format-list}, you should -usually either quote the whole value, like this, - -@example -(setq forms-format-list - '( - "====== " forms-file " ======\n\n" - "User : " 1 - (make-string 20 ?-) - @dots{} - )) -@end example - -@noindent -or quote the elements which are lists, like this: - -@example -(setq forms-format-list - (list - "====== " forms-file " ======\n\n" - "User : " 1 - '(make-string 20 ?-) - @dots{} - )) -@end example - -Forms mode validates the contents of @code{forms-format-list} when you -visit a database. If there are errors, processing is aborted with an -error message which includes a descriptive text. @xref{Error Messages}, -for a detailed list of error messages. - -If no @code{forms-format-list} is specified, Forms mode will supply a -default format list. This list contains the name of the file being -visited, and a simple label for each field indicating the field number. - -@node Modifying Forms Contents -@chapter Modifying The Forms Contents - -If @code{forms-read-only} is @code{nil}, the user can modify the fields -and records of the database. - -All normal editing commands are available for editing the contents of the -displayed record. You cannot delete or modify the fixed, explanatory -text that comes from string formatting elements, but you can modify the -actual field contents. - -@ignore -@c This is for the Emacs 18 version only. -If the contents of the forms cannot be recognized properly, this is -signaled using a descriptive text. @xref{Error Messages}, for more info. -The cursor will indicate the last part of the forms which was -successfully parsed. It's important to avoid entering field contents -that would cause confusion with the field-separating fixed text. -@end ignore - -If the variable @code{forms-modified-record-filter} is non-@code{nil}, -it is called as a function before the new data is written to the data -file. The function receives one argument, a vector that contains the -contents of the fields of the record. - -The function can refer to fields with @code{aref} and modify them with -@code{aset}. The first field has number 1 (one); thus, element 0 of the -vector is not used. The function should return the same vector it was -passed; the (possibly modified) contents of the vector determine what is -actually written in the file. Here is an example: - -@example -(defun my-modified-record-filter (record) - ;; @r{Modify second field.} - (aset record 2 (current-time-string)) - ;; @r{Return the field vector.} - record) - -(setq forms-modified-record-filter 'my-modified-record-filter) -@end example - -If the variable @code{forms-new-record-filter} is non-@code{nil}, its -value is a function to be called to fill in default values for the -fields of a new record. The function is passed a vector of empty -strings, one for each field; it should return the same vector, with -the desired field values stored in it. Fields are numbered starting -from 1 (one). Example: - -@example -(defun my-new-record-filter (fields) - (aset fields 5 (login-name)) - (aset fields 1 (current-time-string)) - fields) - -(setq forms-new-record-filter 'my-new-record-filter) -@end example - -@node Miscellaneous -@chapter Miscellaneous - -@vindex forms-version -The global variable @code{forms-version} holds the version information -of the Forms mode software. - -@findex forms-enumerate -It is very convenient to use symbolic names for the fields in a record. -The function @code{forms-enumerate} provides an elegant means to define -a series of variables whose values are consecutive integers. The -function returns the highest number used, so it can be used to set -@code{forms-number-of-fields} also. For example: - -@example -(setq forms-number-of-fields - (forms-enumerate - '(field1 field2 field3 @dots{}))) -@end example - -This sets @code{field1} to 1, @code{field2} to 2, and so on. - -Care has been taken to keep the Forms mode variables buffer-local, so it -is possible to visit multiple files in Forms mode simultaneously, even -if they have different properties. - -@findex forms-mode -If you have visited the control file in normal fashion with -@code{find-file} or a like command, you can switch to Forms mode with -the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in -the first line of the control file, then visiting it enables Forms mode -automatically. But this makes it hard to edit the control file itself, -so you'd better think twice before using this. - -The default format for the data file, using @code{"\t"} to separate -fields and @code{"\^k"} to separate lines within a field, matches the -file format of some popular database programs, e.g. FileMaker. So -@code{forms-mode} can decrease the need to use proprietary software. - -@node Error Messages -@chapter Error Messages - -This section describes all error messages which can be generated by -forms mode. Error messages that result from parsing the control file -all start with the text @samp{Forms control file error}. Messages -generated while analyzing the definition of @code{forms-format-list} -start with @samp{Forms format error}. - -@table @code -@item Forms control file error: `forms-file' has not been set -The variable @code{forms-file} was not set by the control file. - -@item Forms control file error: `forms-number-of-fields' has not been set -The variable @code{forms-number-of-fields} was not set by the control -file. - -@item Forms control file error: `forms-number-of-fields' must be a number > 0 -The variable @code{forms-number-of-fields} did not contain a positive -number. - -@item Forms control file error: `forms-field-sep' is not a string -@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string -The variable @code{forms-multi-line} was set to something other than -@code{nil} or a single-character string. - -@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' -The variable @code{forms-multi-line} may not be equal to -@code{forms-field-sep} for this would make it impossible to distinguish -fields and the lines in the fields. - -@item Forms control file error: `forms-new-record-filter' is not a function -@itemx Forms control file error: `forms-modified-record-filter' is not a function -The variable has been set to something else than a function. - -@item Forms control file error: `forms-format-list' is not a list -The variable @code{forms-format-list} was not set to a Lisp list -by the control file. - -@item Forms format error: field number @var{xx} out of range 1..@var{nn} -A field number was supplied in @code{forms-format-list} with a value of -@var{xx}, which was not greater than zero and smaller than or equal to -the number of fields in the forms, @var{nn}. - -@item Forms format error: @var{fun} is not a function -The first element of a list which is an element of -@code{forms-format-list} was not a valid Lisp function. - -@item Forms format error: invalid element @var{xx} -A list element was supplied in @code{forms-format-list} which was not a -string, number or list. - -@ignore -@c This applies to Emacs 18 only. -@c Error messages generated while a modified form is being analyzed. - -@item Parse error: not looking at `...' -When re-parsing the contents of a forms, the text shown could not -be found. - -@item Parse error: cannot find `...' -When re-parsing the contents of a forms, the text shown, which -separates two fields, could not be found. - -@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} -Fields @var{xx} and @var{yy} were not separated by text, so could not be -parsed again. -@end ignore - -@item Warning: this record has @var{xx} fields instead of @var{yy} -The number of fields in this record in the data file did not match -@code{forms-number-of-fields}. Missing fields will be made empty. - -@item Multi-line fields in this record - update refused! -The current record contains newline characters, hence can not be written -back to the data file, for it would corrupt it. Probably you inserted a -newline in a field, while @code{forms-multi-line} was @code{nil}. - -@item Field separator occurs in record - update refused! -The current record contains the field separator string inside one of the -fields. It can not be written back to the data file, for it would -corrupt it. Probably you inserted the field separator string in a field. - -@item Record number @var{xx} out of range 1..@var{yy} -A jump was made to non-existing record @var{xx}. @var{yy} denotes the -number of records in the file. - -@item Stuck at record @var{xx} -An internal error prevented a specific record from being retrieved. - -@item No write access to @code{"}@var{file}@code{"} -An attempt was made to enable edit mode on a file that has been write -protected. - -@item Search failed: @var{regexp} -The @var{regexp} could not be found in the data file. Forward searching -is done from the current location until the end of the file, then -retrying from the beginning of the file until the current location. -Backward searching is done from the current location until the beginning -of the file, then retrying from the end of the file until the current -location. - -@item Wrapped -A search completed successfully after wrapping around. - -@item Warning: number of records changed to @var{nn} -Forms mode's idea of the number of records has been adjusted to the -number of records actually present in the data file. - -@item Problem saving buffers? -An error occurred while saving the data file buffer. Most likely, Emacs -did ask to confirm deleting the buffer because it had been modified, and -you said `no'. -@end table - -@node Long Example -@chapter Long Example - -The following example exploits most of the features of Forms mode. -This example is included in the distribution as file @file{forms-d2.el}. - -@example -;; demo2 -- demo forms-mode -*- emacs-lisp -*- - -;; @r{This sample forms exploit most of the features of forms mode.} - -;; @r{Set the name of the data file.} -(setq forms-file "forms-d2.dat") - -;; @r{Use @code{forms-enumerate} to set field names and number thereof.} -(setq forms-number-of-fields - (forms-enumerate - '(arch-newsgroup ; 1 - arch-volume ; 2 - arch-issue ; and ... - arch-article ; ... so - arch-shortname ; ... ... on - arch-parts - arch-from - arch-longname - arch-keywords - arch-date - arch-remarks))) - -;; @r{The following functions are used by this form for layout purposes.} -;; -(defun arch-tocol (target &optional fill) - "Produces a string to skip to column TARGET. -Prepends newline if needed. -The optional FILL should be a character, used to fill to the column." - (if (null fill) - (setq fill ? )) - (if (< target (current-column)) - (concat "\n" (make-string target fill)) - (make-string (- target (current-column)) fill))) -;; -(defun arch-rj (target field &optional fill) - "Produces a string to skip to column TARGET\ - minus the width of field FIELD. -Prepends newline if needed. -The optional FILL should be a character, -used to fill to the column." - (arch-tocol (- target (length (nth field forms-fields))) fill)) - -;; @r{Record filters.} -;; -(defun new-record-filter (the-record) - "Form a new record with some defaults." - (aset the-record arch-from (user-full-name)) - (aset the-record arch-date (current-time-string)) - the-record) ; return it -(setq forms-new-record-filter 'new-record-filter) - -;; @r{The format list.} -(setq forms-format-list - (list - "====== Public Domain Software Archive ======\n\n" - arch-shortname - " - " arch-longname - "\n\n" - "Article: " arch-newsgroup - "/" arch-article - " " - '(arch-tocol 40) - "Issue: " arch-issue - " " - '(arch-rj 73 10) - "Date: " arch-date - "\n\n" - "Submitted by: " arch-from - "\n" - '(arch-tocol 79 ?-) - "\n" - "Keywords: " arch-keywords - "\n\n" - "Parts: " arch-parts - "\n\n====== Remarks ======\n\n" - arch-remarks - )) - -;; @r{That's all, folks!} -@end example - -@node Credits -@chapter Credits - -Bug fixes and other useful suggestions were supplied by -Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), -@code{cwitty@@portia.stanford.edu}, -Jonathan I. Kamens, -Per Cederqvist (@code{ceder@@signum.se}), -Michael Lipka (@code{lipka@@lip.hanse.de}), -Andy Piper (@code{ajp@@eng.cam.ac.uk}), -Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), -Ignatios Souvatzis -and Richard Stallman (@code{rms@@gnu.org}). - -This documentation was slightly inspired by the documentation of ``rolo -mode'' by Paul Davis at Schlumberger Cambridge Research -(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). - -None of this would have been possible without GNU Emacs of the Free -Software Foundation. Thanks, Richard! - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed -@end ignore diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi deleted file mode 100644 index a384e8b1634..00000000000 --- a/doc/misc/gnus-coding.texi +++ /dev/null @@ -1,387 +0,0 @@ -\input texinfo - -@setfilename gnus-coding -@settitle Gnus Coding Style and Maintainance Guide -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@copying -Copyright @copyright{} 2004, 2005, 2007, 2008, 2009 Free Software -Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual'', and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Gnus manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - - -@titlepage -@title Gnus Coding Style and Maintainance Guide - -@author by Reiner Steib - -@insertcopying -@end titlepage - -@c Obviously this is only a very rudimentary draft. We put it in CVS -@c anyway hoping that it might annoy someone enough to fix it. ;-) -@c Fixing only a paragraph also is appreciated. - -@ifnottex -@node Top -@top Gnus Coding Style and Maintainance Guide -This manual describes @dots{} - -@insertcopying -@end ifnottex - -@menu -* Gnus Coding Style:: Gnus Coding Style -* Gnus Maintainance Guide:: Gnus Maintainance Guide -@end menu - -@c @ref{Gnus Reference Guide, ,Gnus Reference Guide, gnus, The Gnus Newsreader} - -@node Gnus Coding Style -@chapter Gnus Coding Style -@section Dependencies - -The Gnus distribution contains a lot of libraries that have been written -for Gnus and used intensively for Gnus. But many of those libraries are -useful on their own. E.g. other Emacs Lisp packages might use the -@acronym{MIME} library @xref{Top, ,Top, emacs-mime, The Emacs MIME -Manual}. - -@subsection General purpose libraries - -@table @file - -@item netrc.el -@file{.netrc} parsing functionality. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item format-spec.el -Functions for formatting arbitrary formatting strings. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item hex-util.el -Functions to encode/decode hexadecimal string. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Encryption and security - -@table @file -@item encrypt.el -File encryption routines -@c As of 2005-10-25... -There are no Gnus dependencies in this file. - -@item password.el -Read passwords from user, possibly using a password cache. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item tls.el -TLS/SSL support via wrapper around GnuTLS -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item pgg*.el -Glue for the various PGP implementations. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. - -@item sha1.el -SHA1 Secure Hash Algorithm. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@end table - -@subsection Networking - -@table @file -@item dig.el -Domain Name System dig interface. -@c As of 2005-10-21... -There are no serious Gnus dependencies in this file. Uses -@code{gnus-run-mode-hooks} (a wrapper function). - -@item dns.el, dns-mode.el -Domain Name Service lookups. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. -@end table - -@subsection Mail and News related RFCs - -@table @file -@item pop3.el -Post Office Protocol (RFC 1460) interface. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item imap.el -@acronym{IMAP} library. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item ietf-drums.el -Functions for parsing RFC822bis headers. -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item rfc1843.el -HZ (rfc1843) decoding. HZ is a data format for exchanging files of -arbitrarily mixed Chinese and @acronym{ASCII} characters. -@c As of 2005-10-21... -@code{rfc1843-gnus-setup} seem to be useful only for Gnus. Maybe this -function should be relocated to remove dependencies on Gnus. Other -minor dependencies: @code{gnus-newsgroup-name} could be eliminated by -using an optional argument to @code{rfc1843-decode-article-body}. - -@item rfc2045.el -Functions for decoding rfc2045 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2047.el -Functions for encoding and decoding rfc2047 messages -@c As of 2007-08-25... -There are no Gnus dependencies in these files. -@c -Only a couple of tests for gnusy symbols. - -@item rfc2104.el -RFC2104 Hashed Message Authentication Codes -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item rfc2231.el -Functions for decoding rfc2231 headers -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@item flow-fill.el -Interpret RFC2646 "flowed" text. -@c As of 2005-10-27... -There are no Gnus dependencies in this file. - -@item uudecode.el -Elisp native uudecode. -@c As of 2005-12-06... -There are no Gnus dependencies in this file. -@c ... but the custom group is gnus-extract. - -@item canlock.el -Functions for Cancel-Lock feature -@c Cf. draft-ietf-usefor-cancel-lock-01.txt -@c Although this draft has expired, Canlock-Lock revived in 2007 when -@c major news providers (e.g. news.individual.org) started to use it. -@c As of 2007-08-25... -There are no Gnus dependencies in these files. - -@end table - -@subsection message - -All message composition from Gnus (both mail and news) takes place in -Message mode buffers. Message mode is intended to be a replacement for -Emacs mail mode. There should be no Gnus dependencies in -@file{message.el}. Alas it is not anymore. Patches and suggestions to -remove the dependencies are welcome. - -@c message.el requires nnheader which requires gnus-util. - -@subsection Emacs @acronym{MIME} - -The files @file{mml*.el} and @file{mm-*.el} provide @acronym{MIME} -functionality for Emacs. - -@acronym{MML} (@acronym{MIME} Meta Language) is supposed to be -independent from Gnus. Alas it is not anymore. Patches and suggestions -to remove the dependencies are welcome. - -@subsection Gnus backends - -The files @file{nn*.el} provide functionality for accessing NNTP -(@file{nntp.el}), IMAP (@file{nnimap.el}) and several other Mail back -ends (probably @file{nnml.el}, @file{nnfolder.el} and -@file{nnmaildir.el} are the most widely used mail back ends). - -@c mm-uu requires nnheader which requires gnus-util. message.el also -@c requires nnheader. - - -@section Compatibility - -No Gnus and Gnus 5.10.10 and up should work on: -@itemize @bullet -@item -Emacs 21.1 and up. -@item -XEmacs 21.4 and up. -@end itemize - -Gnus 5.10.8 and below should work on: -@itemize @bullet -@item -Emacs 20.7 and up. -@item -XEmacs 21.1 and up. -@end itemize - -@node Gnus Maintainance Guide -@chapter Gnus Maintainance Guide - -@section Stable and development versions - -The development of Gnus normally is done on the CVS trunk, i.e. there -are no separate branches to develop and test new features. Most of the -time, the trunk is developed quite actively with more or less daily -changes. Only after a new major release, e.g. 5.10.1, there's usually a -feature period of several months. After the release of Gnus 5.10.6 the -development of new features started again on the trunk while the 5.10 -series is continued on the stable branch (v5-10) from which more stable -releases will be done when needed (5.10.8, @dots{}). -@ref{Gnus Development, ,Gnus Development, gnus, The Gnus Newsreader} - -Stable releases of Gnus finally become part of Emacs. E.g. Gnus 5.8 -became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series -became part of Emacs 22 as Gnus 5.11. - -@section Syncing - -@c Some MIDs related to this follow. Use http://thread.gmane.org/MID -@c (and click on the subject) to get the thread on Gmane. - -@c Some quotes from Miles Bader follow... - -@c -@c - -In the past, the inclusion of Gnus into Emacs was quite cumbersome. For -each change made to Gnus in Emacs repository, it had to be checked that -it was applied to the new Gnus version, too. Else, bug fixes done in -Emacs repository might have been lost. - -With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus -gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus -CVS semi-automatically. These bug fixes are installed on the stable -branch and on the trunk. Basically the idea is that the gateway will -cause all common files in Emacs and Gnus v5-10 to be identical except -when there's a very good reason (e.g., the Gnus version string in Emacs -says @samp{5.11}, but the v5-10 version string remains @samp{5.10.x}). -Furthermore, all changes in these files in either Emacs or the v5-10 -branch will be installed into the Gnus CVS trunk, again except where -there's a good reason. -@c (typically so far the only exception has been that the changes -@c already exist in the trunk in modified form). -Because of this, when the next major version of Gnus will be included in -Emacs, it should be very easy -- just plonk in the files from the Gnus -trunk without worrying about lost changes from the Emacs tree. - -The effect of this is that as hacker, you should generally only have to -make changes in one place: - -@itemize -@item -If it's a file which is thought of as being outside of Gnus (e.g., the -new @file{encrypt.el}), you should probably make the change in the Emacs -tree, and it will show up in the Gnus tree a few days later. - -If you don't have Emacs CVS access (or it's inconvenient), you can -change such a file in the v5-10 branch, and it should propagate to Emacs -CVS -- however, it will get some extra scrutiny (by Miles) to see if the -changes are possibly controversial and need discussion on the mailing -list. Many changes are obvious bug-fixes however, so often there won't -be any problem. - -@item -If it's to a Gnus file, and it's important enough that it should be part -of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs CVS and the Gnus CVS trunk (a few days -later). The most prominent examples for such changes are bug-fixed -including improvements on the documentation. - -If you know that there will be conflicts (perhaps because the affected -source code is different in v5-10 and the Gnus CVS trunk), then you can -install your change in both places, and when I try to sync them, there -will be a conflict -- however, since in most such cases there would be a -conflict @emph{anyway}, it's often easier for me to resolve it simply if -I see two @samp{identical} changes, and can just choose the proper one, -rather than having to actually fix the code. - -@item -For general Gnus development changes, of course you just make the -change on the Gnus CVS trunk and it goes into Emacs a few years -later... :-) -@end itemize - -Of course in any case, if you just can't wait for me to sync your -change, you can commit it in more than one place and probably there will -be no problem; usually the changes are textually identical anyway, so -can be easily resolved automatically (sometimes I notice silly things in -such multiple commits, like whitespace differences, and unify those ;-). - - -@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to -@c require more manual work. - -@c By default I sync about once a week. I also try to follow any Gnus -@c threads on the mailing lists and make sure any changes being discussed -@c are kept more up-to-date (so say 1-2 days delay for "topical" changes). - -@c - -@c BTW, just to add even more verbose explanation about the syncing thing: - -@section Miscellanea - -@heading @file{GNUS-NEWS} - -Starting from No Gnus, the @file{GNUS-NEWS} is created from -@file{texi/gnus-news.texi}. Don't edit @file{GNUS-NEWS}. Edit -@file{texi/gnus-news.texi}, type @command{make GNUS-NEWS} in the -@file{texi} directory and commit @file{GNUS-NEWS} and -@file{texi/gnus-news.texi}. - -@heading Conventions for version information in defcustoms - -For new customizable variables introduced in Oort Gnus (including the -v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the -comment) or e.g. @code{:version "22.2" ;; Gnus 5.10.10} if the feature -was added for Emacs 22.2 and Gnus 5.10.10. -@c -If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. - -The same applies for customizable variables when its default value was -changed. - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: - -@ignore - arch-tag: ab15234c-2c8a-4cbd-8111-1811bcc6f931 -@end ignore diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi deleted file mode 100644 index d374dfdabb2..00000000000 --- a/doc/misc/gnus-faq.texi +++ /dev/null @@ -1,2337 +0,0 @@ -@c \input texinfo @c -*-texinfo-*- -@c Uncomment 1st line before texing this file alone. -@c %**start of header -@c Copyright (C) 1995, 2001, 2002, 2003, 2004, 2005, 2006, 2007, -@c 2008, 2009 Free Software Foundation, Inc. -@c -@c Do not modify this file, it was generated from gnus-faq.xml, available from -@c . -@c -@setfilename gnus-faq.info -@settitle Frequently Asked Questions -@c %**end of header -@c - -@node Frequently Asked Questions -@section Frequently Asked Questions - -@menu -* FAQ - Changes:: -* FAQ - Introduction:: About Gnus and this FAQ. -* FAQ 1 - Installation FAQ:: Installation of Gnus. -* FAQ 2 - Startup / Group buffer:: Start up questions and the - first buffer Gnus shows you. -* FAQ 3 - Getting Messages:: Making Gnus read your mail - and news. -* FAQ 4 - Reading messages:: How to efficiently read - messages. -* FAQ 5 - Composing messages:: Composing mails or Usenet - postings. -* FAQ 6 - Old messages:: Importing, archiving, - searching and deleting messages. -* FAQ 7 - Gnus in a dial-up environment:: Reading mail and news while - offline. -* FAQ 8 - Getting help:: When this FAQ isn't enough. -* FAQ 9 - Tuning Gnus:: How to make Gnus faster. -* FAQ - Glossary:: Terms used in the FAQ - explained. -@end menu - -@subheading Abstract - -This is the new Gnus Frequently Asked Questions list. -If you have a Web browser, the official hypertext version is at -@uref{http://my.gnus.org/FAQ/}, -the Docbook source is available from -@uref{http://sourceforge.net/projects/gnus/, http://sourceforge.net}. - -Please submit features and suggestions to the -@email{faq-discuss@@my.gnus.org, FAQ discussion list}. -The list is protected against junk mail with -@uref{http://smarden.org/qconfirm/index.html, qconfirm}. As -a subscriber, your submissions will automatically pass. You can -also subscribe to the list by sending a blank email to -@email{faq-discuss-subscribe@@my.gnus.org, faq-discuss-subscribe@@my.gnus.org} -and @uref{http://mail1.kens.com/cgi-bin/ezmlm-browse?command=monthbythread%26list=faq-discuss, browse -the archive (BROKEN)}. - -@node FAQ - Changes -@subheading Changes - - - -@itemize @bullet - -@item -2008-06-15: Adjust for message-fill-column. Add x-face-file. -Clarify difference between ding and gnu.emacs.gnus. Remove -reference to discontinued service. - -@item -2006-04-15: Added tip on how to delete sent buffer on exit. -@end itemize - -@node FAQ - Introduction -@subheading Introduction - -This is the Gnus Frequently Asked Questions list. - -Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented -as a part of Emacs. It's been around in some form for almost a decade -now, and has been distributed as a standard part of Emacs for much of -that time. Gnus 5 is the latest (and greatest) incarnation. The -original version was called GNUS, and was written by Masanobu UMEDA. -When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and -decided to rewrite Gnus. - -Its biggest strength is the fact that it is extremely -customizable. It is somewhat intimidating at first glance, but -most of the complexity can be ignored until you're ready to take -advantage of it. If you receive a reasonable volume of e-mail -(you're on various mailing lists), or you would like to read -high-volume mailing lists but cannot keep up with them, or read -high volume newsgroups or are just bored, then Gnus is what you -want. - -This FAQ was maintained by Justin Sheehy until March 2002. He -would like to thank Steve Baur and Per Abrahamsen for doing a wonderful -job with this FAQ before him. We would like to do the same - thanks, -Justin! - -If you have a Web browser, the official hypertext version is at: -@uref{http://my.gnus.org/FAQ/}. -This version is much nicer than the unofficial hypertext -versions that are archived at Utrecht, Oxford, Smart Pages, Ohio -State, and other FAQ archives. See the resources question below -if you want information on obtaining it in another format. - -The information contained here was compiled with the assistance -of the Gnus development mailing list, and any errors or -misprints are the my.gnus.org team's fault, sorry. - -@node FAQ 1 - Installation FAQ -@subsection Installation FAQ - -@menu -* FAQ 1-1:: What is the latest version of Gnus? -* FAQ 1-2:: What's new in 5.10? -* FAQ 1-3:: Where and how to get Gnus? -* FAQ 1-4:: What to do with the tarball now? -* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, - what are those? -* FAQ 1-6:: Which version of Emacs do I need? -* FAQ 1-7:: How do I run Gnus on both Emacs and XEmacs? -@end menu - -@node FAQ 1-1 -@subsubheading Question 1.1 - -What is the latest version of Gnus? - -@subsubheading Answer - -Jingle please: Gnus 5.10 is released, get it while it's -hot! As well as the step in version number is rather -small, Gnus 5.10 has tons of new features which you -shouldn't miss. The current release (5.13) should be at -least as stable as the latest release of the 5.8 series. - -@node FAQ 1-2 -@subsubheading Question 1.2 - -What's new in 5.10? - -@subsubheading Answer - -First of all, you should have a look into the file -GNUS-NEWS in the toplevel directory of the Gnus tarball, -there the most important changes are listed. Here's a -short list of the changes I find especially -important/interesting: - -@itemize @bullet - -@item -Major rewrite of the Gnus agent, Gnus agent is now -active by default. - -@item -Many new article washing functions for dealing with -ugly formatted articles. - -@item -Anti Spam features. - -@item -Message-utils now included in Gnus. - -@item -New format specifiers for summary lines, e.g. %B for -a complex trn-style thread tree. -@end itemize - -@node FAQ 1-3 -@subsubheading Question 1.3 - -Where and how to get Gnus? - -@subsubheading Answer - -Gnus is released independent from releases of Emacs and XEmacs. -Therefore, the version bundled with Emacs or the version in XEmacs' -package system might not be up to date (e.g. Gnus 5.9 bundled with Emacs -21 is outdated). -You can get the latest released version of Gnus from -@uref{http://www.gnus.org/dist/gnus.tar.gz} -or via anonymous FTP from -@uref{ftp://ftp.gnus.org/pub/gnus/gnus.tar.gz}. - -@node FAQ 1-4 -@subsubheading Question 1.4 - -What to do with the tarball now? - -@subsubheading Answer - -Untar it via @samp{tar xvzf gnus.tar.gz} and do the common -@samp{./configure; make; make install} circle. -(under MS-Windows either get the Cygwin environment from -@uref{http://www.cygwin.com} -which allows you to do what's described above or unpack the -tarball with some packer (e.g. Winace from -@uref{http://www.winace.com}) -and use the batch-file make.bat included in the tarball to install -Gnus.) If you don't want to (or aren't allowed to) install Gnus -system-wide, you can install it in your home directory and add the -following lines to your ~/.xemacs/init.el or ~/.emacs: - -@example -(add-to-list 'load-path "/path/to/gnus/lisp") -(if (featurep 'xemacs) - (add-to-list 'Info-directory-list "/path/to/gnus/texi/") - (add-to-list 'Info-default-directory-list "/path/to/gnus/texi/")) -@end example -@noindent - -Make sure that you don't have any Gnus related stuff -before this line, on MS Windows use something like -"C:/path/to/lisp" (yes, "/"). - -@node FAQ 1-5 -@subsubheading Question 1.5 - -I sometimes read references to No Gnus and Oort Gnus, -what are those? - -@subsubheading Answer - -Oort Gnus was the name of the development version of -Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is -the name of the current development version which will -once become Gnus 5.12 or Gnus 6. (If you're wondering why -not 5.11, the odd version numbers are normally used for -the Gnus versions bundled with Emacs) - -@node FAQ 1-6 -@subsubheading Question 1.6 - -Which version of Emacs do I need? - -@subsubheading Answer - -Gnus 5.10 requires an Emacs version that is greater than or equal -to Emacs 20.7 or XEmacs 21.1. -The development versions of Gnus (aka No Gnus) requires Emacs 21 -or XEmacs 21.4. - -@node FAQ 1-7 -@subsubheading Question 1.7 - -How do I run Gnus on both Emacs and XEmacs? - -@subsubheading Answer - -You can't use the same copy of Gnus in both as the Lisp -files are byte-compiled to a format which is different -depending on which Emacs did the compilation. Get one copy -of Gnus for Emacs and one for XEmacs. - -@node FAQ 2 - Startup / Group buffer -@subsection Startup / Group buffer - -@menu -* FAQ 2-1:: Every time I start Gnus I get a message "Gnus auto-save - file exists. Do you want to read it?", what does this mean and - how to prevent it? -* FAQ 2-2:: Gnus doesn't remember which groups I'm subscribed to, - what's this? -* FAQ 2-3:: How to change the format of the lines in Group buffer? -* FAQ 2-4:: My group buffer becomes a bit crowded, is there a way to - sort my groups into categories so I can easier browse through - them? -* FAQ 2-5:: How to manually sort the groups in Group buffer? How to - sort the groups in a topic? -@end menu - -@node FAQ 2-1 -@subsubheading Question 2.1 - -Every time I start Gnus I get a message "Gnus auto-save -file exists. Do you want to read it?", what does this mean -and how to prevent it? - -@subsubheading Answer - -This message means that the last time you used Gnus, it -wasn't properly exited and therefor couldn't write its -informations to disk (e.g. which messages you read), you -are now asked if you want to restore those informations -from the auto-save file. - -To prevent this message make sure you exit Gnus -via @samp{q} in group buffer instead of -just killing Emacs. - -@node FAQ 2-2 -@subsubheading Question 2.2 - -Gnus doesn't remember which groups I'm subscribed to, -what's this? - -@subsubheading Answer - -You get the message described in the q/a pair above while -starting Gnus, right? It's an other symptom for the same -problem, so read the answer above. - -@node FAQ 2-3 -@subsubheading Question 2.3 - -How to change the format of the lines in Group buffer? - -@subsubheading Answer - -You've got to tweak the value of the variable -gnus-group-line-format. See the manual node "Group Line -Specification" for information on how to do this. An -example for this (guess from whose .gnus :-)): - -@example -(setq gnus-group-line-format "%P%M%S[%5t]%5y : %(%g%)\n") -@end example -@noindent - -@node FAQ 2-4 -@subsubheading Question 2.4 - -My group buffer becomes a bit crowded, is there a way to -sort my groups into categories so I can easier browse -through them? - -@subsubheading Answer - -Gnus offers the topic mode, it allows you to sort your -groups in, well, topics, e.g. all groups dealing with -Linux under the topic linux, all dealing with music under -the topic music and all dealing with scottish music under -the topic scottish which is a subtopic of music. - -To enter topic mode, just hit t while in Group buffer. Now -you can use @samp{T n} to create a topic -at point and @samp{T m} to move a group to -a specific topic. For more commands see the manual or the -menu. You might want to include the %P specifier at the -beginning of your gnus-group-line-format variable to have -the groups nicely indented. - -@node FAQ 2-5 -@subsubheading Question 2.5 - -How to manually sort the groups in Group buffer? How to -sort the groups in a topic? - -@subsubheading Answer - -Move point over the group you want to move and -hit @samp{C-k}, now move point to the -place where you want the group to be and -hit @samp{C-y}. - -@node FAQ 3 - Getting Messages -@subsection Getting Messages - -@menu -* FAQ 3-1:: I just installed Gnus, started it via @samp{M-x gnus} - but it only says "nntp (news) open error", what to do? -* FAQ 3-2:: I'm working under Windows and have no idea what - ~/.gnus.el means. -* FAQ 3-3:: My news server requires authentication, how to store - user name and password on disk? -* FAQ 3-4:: Gnus seems to start up OK, but I can't find out how to - subscribe to a group. -* FAQ 3-5:: Gnus doesn't show all groups / Gnus says I'm not allowed - to post on this server as well as I am, what's that? -* FAQ 3-6:: I want Gnus to fetch news from several servers, is this - possible? -* FAQ 3-7:: And how about local spool files? -* FAQ 3-8:: OK, reading news works now, but I want to be able to - read my mail with Gnus, too. How to do it? -* FAQ 3-9:: And what about IMAP? -* FAQ 3-10:: At the office we use one of those MS Exchange servers, - can I use Gnus to read my mail from it? -* FAQ 3-11:: Can I tell Gnus not to delete the mails on the server it - retrieves via POP3? -@end menu - -@node FAQ 3-1 -@subsubheading Question 3.1 - -I just installed Gnus, started it via -@samp{M-x gnus} -but it only says "nntp (news) open error", what to do? - -@subsubheading Answer - -You've got to tell Gnus where to fetch the news from. Read -the documentation for information on how to do this. As a -first start, put those lines in ~/.gnus.el: - -@example -(setq gnus-select-method '(nntp "news.yourprovider.net")) -(setq user-mail-address "you@@yourprovider.net") -(setq user-full-name "Your Name") -@end example -@noindent - -@node FAQ 3-2 -@subsubheading Question 3.2 - -I'm working under Windows and have no idea what ~/.gnus.el means. - -@subsubheading Answer - -The ~/ means the home directory where Gnus and Emacs look -for the configuration files. However, you don't really -need to know what this means, it suffices that Emacs knows -what it means :-) You can type -@samp{C-x C-f ~/.gnus.el RET } -(yes, with the forward slash, even on Windows), and -Emacs will open the right file for you. (It will most -likely be new, and thus empty.) -However, I'd discourage you from doing so, since the -directory Emacs chooses will most certainly not be what -you want, so let's do it the correct way. -The first thing you've got to do is to -create a suitable directory (no blanks in directory name -please) e.g. c:\myhome. Then you must set the environment -variable HOME to this directory. To do this under Win9x -or Me include the line - -@example -SET HOME=C:\myhome -@end example -@noindent - -in your autoexec.bat and reboot. Under NT, 2000 and XP, hit -Winkey+Pause/Break to enter system options (if it doesn't work, go -to Control Panel -> System -> Advanced). There you'll find the -possibility to set environment variables. Create a new one with -name HOME and value C:\myhome. Rebooting is not necessary. - -Now to create ~/.gnus.el, say -@samp{C-x C-f ~/.gnus.el RET C-x C-s}. -in Emacs. - -@node FAQ 3-3 -@subsubheading Question 3.3 - -My news server requires authentication, how to store -user name and password on disk? - -@subsubheading Answer - -Create a file ~/.authinfo which includes for each server a line like this - -@example -machine news.yourprovider.net login YourUserName password YourPassword -@end example -@noindent -. -Make sure that the file isn't readable to others if you -work on a OS which is capable of doing so. (Under Unix -say -@example -chmod 600 ~/.authinfo -@end example -@noindent - -in a shell.) - -@node FAQ 3-4 -@subsubheading Question 3.4 - -Gnus seems to start up OK, but I can't find out how to -subscribe to a group. - -@subsubheading Answer - -If you know the name of the group say @samp{U -name.of.group RET} in group buffer (use the -tab-completion Luke). Otherwise hit ^ in group buffer, -this brings you to the server buffer. Now place point (the -cursor) over the server which carries the group you want, -hit @samp{RET}, move point to the group -you want to subscribe to and say @samp{u} -to subscribe to it. - -@node FAQ 3-5 -@subsubheading Question 3.5 - -Gnus doesn't show all groups / Gnus says I'm not allowed to -post on this server as well as I am, what's that? - -@subsubheading Answer - -Some providers allow restricted anonymous access and full -access only after authorization. To make Gnus send authinfo -to those servers append - -@example -force yes -@end example -@noindent - -to the line for those servers in ~/.authinfo. - -@node FAQ 3-6 -@subsubheading Question 3.6 - -I want Gnus to fetch news from several servers, is this possible? - -@subsubheading Answer - -Of course. You can specify more sources for articles in the -variable gnus-secondary-select-methods. Add something like -this in ~/.gnus.el: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourSecondProvider.net")) -(add-to-list 'gnus-secondary-select-methods - '(nntp "news.yourThirdProvider.net")) -@end example -@noindent - -@node FAQ 3-7 -@subsubheading Question 3.7 - -And how about local spool files? - -@subsubheading Answer - -No problem, this is just one more select method called -nnspool, so you want this: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnspool "")) -@end example -@noindent - -Or this if you don't want an NNTP Server as primary news source: - -@example -(setq gnus-select-method '(nnspool "")) -@end example -@noindent - -Gnus will look for the spool file in /usr/spool/news, if you -want something different, change the line above to something like this: - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnspool "" - (nnspool-directory "/usr/local/myspoolddir"))) -@end example -@noindent - -This sets the spool directory for this server only. -You might have to specify more stuff like the program used -to post articles, see the Gnus manual on how to do this. - -@node FAQ 3-8 -@subsubheading Question 3.8 - -OK, reading news works now, but I want to be able to read my mail -with Gnus, too. How to do it? - -@subsubheading Answer - -That's a bit harder since there are many possible sources -for mail, many possible ways for storing mail and many -different ways for sending mail. The most common cases are -these: 1: You want to read your mail from a pop3 server and -send them directly to a SMTP Server 2: Some program like -fetchmail retrieves your mail and stores it on disk from -where Gnus shall read it. Outgoing mail is sent by -Sendmail, Postfix or some other MTA. Sometimes, you even -need a combination of the above cases. - -However, the first thing to do is to tell Gnus in which way -it should store the mail, in Gnus terminology which back end -to use. Gnus supports many different back ends, the most -commonly used one is nnml. It stores every mail in one file -and is therefor quite fast. However you might prefer a one -file per group approach if your file system has problems with -many small files, the nnfolder back end is then probably the -choice for you. To use nnml add the following to ~/.gnus.el: - -@example -(add-to-list 'gnus-secondary-select-methods '(nnml "")) -@end example -@noindent - -As you might have guessed, if you want nnfolder, it's - -@example -(add-to-list 'gnus-secondary-select-methods '(nnfolder "")) -@end example -@noindent - -Now we need to tell Gnus, where to get it's mail from. If -it's a POP3 server, then you need something like this: - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(pop :server "pop.YourProvider.net" - :user "yourUserName" - :password "yourPassword"))) -@end example -@noindent - -Make sure ~/.gnus.el isn't readable to others if you store -your password there. If you want to read your mail from a -traditional spool file on your local machine, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(file :path "/path/to/spool/file")) -@end example -@noindent - -If it's a Maildir, with one file per message as used by -postfix, Qmail and (optionally) fetchmail it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources '(maildir :path "/path/to/Maildir/" - :subdirs ("cur" "new"))) -@end example -@noindent - -And finally if you want to read your mail from several files -in one directory, for example because procmail already split your -mail, it's - -@example -(eval-after-load "mail-source" - '(add-to-list 'mail-sources - '(directory :path "/path/to/procmail-dir/" - :suffix ".prcml"))) -@end example -@noindent - -Where :suffix ".prcml" tells Gnus only to use files with the -suffix .prcml. - -OK, now you only need to tell Gnus how to send mail. If you -want to send mail via sendmail (or whichever MTA is playing -the role of sendmail on your system), you don't need to do -anything. However, if you want to send your mail to an -SMTP Server you need the following in your ~/.gnus.el - -@example -(setq send-mail-function 'smtpmail-send-it) -(setq message-send-mail-function 'smtpmail-send-it) -(setq smtpmail-default-smtp-server "smtp.yourProvider.net") -@end example -@noindent - -@node FAQ 3-9 -@subsubheading Question 3.9 - -And what about IMAP? - -@subsubheading Answer - -There are two ways of using IMAP with Gnus. The first one is -to use IMAP like POP3, that means Gnus fetches the mail from -the IMAP server and stores it on disk. If you want to do -this (you don't really want to do this) add the following to -~/.gnus.el - -@example -(add-to-list 'mail-sources '(imap :server "mail.mycorp.com" - :user "username" - :pass "password" - :stream network - :authentication login - :mailbox "INBOX" - :fetchflag "\\Seen")) -@end example -@noindent - -You might have to tweak the values for stream and/or -authentication, see the Gnus manual node "Mail Source -Specifiers" for possible values. - -If you want to use IMAP the way it's intended, you've got to -follow a different approach. You've got to add the nnimap -back end to your select method and give the information -about the server there. - -@example -(add-to-list 'gnus-secondary-select-methods - '(nnimap "Give the baby a name" - (nnimap-address "imap.yourProvider.net") - (nnimap-port 143) - (nnimap-list-pattern "archive.*"))) -@end example -@noindent - -Again, you might have to specify how to authenticate to the -server if Gnus can't guess the correct way, see the Manual -Node "IMAP" for detailed information. - -@node FAQ 3-10 -@subsubheading Question 3.10 - -At the office we use one of those MS Exchange servers, can I use -Gnus to read my mail from it? - -@subsubheading Answer - -Offer your administrator a pair of new running shoes for -activating IMAP on the server and follow the instructions -above. - -@node FAQ 3-11 -@subsubheading Question 3.11 - -Can I tell Gnus not to delete the mails on the server it -retrieves via POP3? - -@subsubheading Answer - -First of all, that's not the way POP3 is intended to work, -if you have the possibility, you should use the IMAP -Protocol if you want your messages to stay on the -server. Nevertheless there might be situations where you -need the feature, but sadly Gnus itself has no predefined -functionality to do so. - -However this is Gnus county so there are possibilities to -achieve what you want. The easiest way is to get an external -program which retrieves copies of the mail and stores them -on disk, so Gnus can read it from there. On Unix systems you -could use e.g. fetchmail for this, on MS Windows you can use -Hamster, an excellent local news and mail server. - -The other solution would be, to replace the method Gnus -uses to get mail from POP3 servers by one which is capable -of leaving the mail on the server. If you use XEmacs, get -the package mail-lib, it includes an enhanced pop3.el, -look in the file, there's documentation on how to tell -Gnus to use it and not to delete the retrieved mail. For -GNU Emacs look for the file epop3.el which can do the same -(If you know the home of this file, please send me an -e-mail). You can also tell Gnus to use an external program -(e.g. fetchmail) to fetch your mail, see the info node -"Mail Source Specifiers" in the Gnus manual on how to do -it. - -@node FAQ 4 - Reading messages -@subsection Reading messages - -@menu -* FAQ 4-1:: When I enter a group, all read messages are gone. How to - view them again? -* FAQ 4-2:: How to tell Gnus to show an important message every time - I enter a group, even when it's read? -* FAQ 4-3:: How to view the headers of a message? -* FAQ 4-4:: How to view the raw unformatted message? -* FAQ 4-5:: How can I change the headers Gnus displays by default at - the top of the article buffer? -* FAQ 4-6:: I'd like Gnus NOT to render HTML-mails but show me the - text part if it's available. How to do it? -* FAQ 4-7:: Can I use some other browser than w3 to render my - HTML-mails? -* FAQ 4-8:: Is there anything I can do to make poorly formatted - mails more readable? -* FAQ 4-9:: Is there a way to automatically ignore posts by specific - authors or with specific words in the subject? And can I - highlight more interesting ones in some way? -* FAQ 4-10:: How can I disable threading in some (e.g. mail-) groups, - or set other variables specific for some groups? -* FAQ 4-11:: Can I highlight messages written by me and follow-ups to - those? -* FAQ 4-12:: The number of total messages in a group which Gnus - displays in group buffer is by far to high, especially in mail - groups. Is this a bug? -* FAQ 4-13:: I don't like the layout of summary and article buffer, - how to change it? Perhaps even a three pane display? -* FAQ 4-14:: I don't like the way the Summary buffer looks, how to - tweak it? -* FAQ 4-15:: How to split incoming mails in several groups? -@end menu - -@node FAQ 4-1 -@subsubheading Question 4.1 - -When I enter a group, all read messages are gone. How to view them again? - -@subsubheading Answer - -If you enter the group by saying -@samp{RET} -in group buffer with point over the group, only unread and ticked messages are loaded. Say -@samp{C-u RET} -instead to load all available messages. If you want only the e.g. 300 newest say -@samp{C-u 300 RET} - -Loading only unread messages can be annoying if you have threaded view enabled, say - -@example -(setq gnus-fetch-old-headers 'some) -@end example -@noindent - -in ~/.gnus.el to load enough old articles to prevent teared threads, replace 'some with t to load -all articles (Warning: Both settings enlarge the amount of data which is -fetched when you enter a group and slow down the process of entering a group). - -If you already use Gnus 5.10, you can say -@samp{/o N} -In summary buffer to load the last N messages, this feature is not available in 5.8.8 - -If you don't want all old messages, but the parent of the message you're just reading, -you can say @samp{^}, if you want to retrieve the whole thread -the message you're just reading belongs to, @samp{A T} is your friend. - -@node FAQ 4-2 -@subsubheading Question 4.2 - -How to tell Gnus to show an important message every time I -enter a group, even when it's read? - -@subsubheading Answer - -You can tick important messages. To do this hit -@samp{u} while point is in summary buffer -over the message. When you want to remove the mark, hit -either @samp{d} (this deletes the tick -mark and set's unread mark) or @samp{M c} -(which deletes all marks for the message). - -@node FAQ 4-3 -@subsubheading Question 4.3 - -How to view the headers of a message? - -@subsubheading Answer - -Say @samp{t} -to show all headers, one more -@samp{t} -hides them again. - -@node FAQ 4-4 -@subsubheading Question 4.4 - -How to view the raw unformatted message? - -@subsubheading Answer - -Say -@samp{C-u g} -to show the raw message -@samp{g} -returns to normal view. - -@node FAQ 4-5 -@subsubheading Question 4.5 - -How can I change the headers Gnus displays by default at -the top of the article buffer? - -@subsubheading Answer - -The variable gnus-visible-headers controls which headers -are shown, its value is a regular expression, header lines -which match it are shown. So if you want author, subject, -date, and if the header exists, Followup-To and MUA / NUA -say this in ~/.gnus.el: - -@example -(setq gnus-visible-headers - '("^From" "^Subject" "^Date" "^Newsgroups" "^Followup-To" - "^User-Agent" "^X-Newsreader" "^X-Mailer")) -@end example -@noindent - -@node FAQ 4-6 -@subsubheading Question 4.6 - -I'd like Gnus NOT to render HTML-mails but show me the -text part if it's available. How to do it? - -@subsubheading Answer - -Say - -@example -(eval-after-load "mm-decode" - '(progn - (add-to-list 'mm-discouraged-alternatives "text/html") - (add-to-list 'mm-discouraged-alternatives "text/richtext"))) -@end example -@noindent - -in ~/.gnus.el. If you don't want HTML rendered, even if there's no text alternative add - -@example -(setq mm-automatic-display (remove "text/html" mm-automatic-display)) -@end example -@noindent - -too. - -@node FAQ 4-7 -@subsubheading Question 4.7 - -Can I use some other browser than w3 to render my HTML-mails? - -@subsubheading Answer - -Only if you use Gnus 5.10 or younger. In this case you've got the -choice between w3, w3m, links, lynx and html2text, which -one is used can be specified in the variable -mm-text-html-renderer, so if you want links to render your -mail say - -@example -(setq mm-text-html-renderer 'links) -@end example -@noindent - -@node FAQ 4-8 -@subsubheading Question 4.8 - -Is there anything I can do to make poorly formatted mails -more readable? - -@subsubheading Answer - -Gnus offers you several functions to "wash" incoming mail, you can -find them if you browse through the menu, item -Article->Washing. The most interesting ones are probably "Wrap -long lines" (@samp{W w}), "Decode ROT13" -(@samp{W r}) and "Outlook Deuglify" which repairs -the dumb quoting used by many users of Microsoft products -(@samp{W Y f} gives you full deuglify. -See @samp{W Y C-h} or have a look at the menus for -other deuglifications). Outlook deuglify is only available since -Gnus 5.10. - -@node FAQ 4-9 -@subsubheading Question 4.9 - -Is there a way to automatically ignore posts by specific -authors or with specific words in the subject? And can I -highlight more interesting ones in some way? - -@subsubheading Answer - -You want Scoring. Scoring means, that you define rules -which assign each message an integer value. Depending on -the value the message is highlighted in summary buffer (if -it's high, say +2000) or automatically marked read (if the -value is low, say -800) or some other action happens. - -There are basically three ways of setting up rules which assign -the scoring-value to messages. The first and easiest way is to set -up rules based on the article you are just reading. Say you're -reading a message by a guy who always writes nonsense and you want -to ignore his messages in the future. Hit -@samp{L}, to set up a rule which lowers the score. -Now Gnus asks you which the criteria for lowering the Score shall -be. Hit @samp{?} twice to see all possibilities, -we want @samp{a} which means the author (the from -header). Now Gnus wants to know which kind of matching we want. -Hit either @samp{e} for an exact match or -@samp{s} for substring-match and delete afterwards -everything but the name to score down all authors with the given -name no matter which email address is used. Now you need to tell -Gnus when to apply the rule and how long it should last, hit e.g. -@samp{p} to apply the rule now and let it last -forever. If you want to raise the score instead of lowering it say -@samp{I} instead of @samp{L}. - -You can also set up rules by hand. To do this say @samp{V -f} in summary buffer. Then you are asked for the name -of the score file, it's name.of.group.SCORE for rules valid in -only one group or all.Score for rules valid in all groups. See the -Gnus manual for the exact syntax, basically it's one big list -whose elements are lists again. the first element of those lists -is the header to score on, then one more list with what to match, -which score to assign, when to expire the rule and how to do the -matching. If you find me very interesting, you could e.g. add the -following to your all.Score: - -@example -(("references" ("hschmi22.userfqdn.rz-online.de" 500 nil s)) - ("message-id" ("hschmi22.userfqdn.rz-online.de" 999 nil s))) -@end example -@noindent - -This would add 999 to the score of messages written by me -and 500 to the score of messages which are a (possibly -indirect) answer to a message written by me. Of course -nobody with a sane mind would do this :-) - -The third alternative is adaptive scoring. This means Gnus -watches you and tries to find out what you find -interesting and what annoying and sets up rules -which reflect this. Adaptive scoring can be a huge help -when reading high traffic groups. If you want to activate -adaptive scoring say - -@example -(setq gnus-use-adaptive-scoring t) -@end example -@noindent - -in ~/.gnus.el. - -@node FAQ 4-10 -@subsubheading Question 4.10 - -How can I disable threading in some (e.g. mail-) groups, or -set other variables specific for some groups? - -@subsubheading Answer - -While in group buffer move point over the group and hit -@samp{G c}, this opens a buffer where you -can set options for the group. At the bottom of the buffer -you'll find an item that allows you to set variables -locally for the group. To disable threading enter -gnus-show-threads as name of variable and nil as -value. Hit button done at the top of the buffer when -you're ready. - -@node FAQ 4-11 -@subsubheading Question 4.11 - -Can I highlight messages written by me and follow-ups to -those? - -@subsubheading Answer - -Stop those "Can I ..." questions, the answer is always yes -in Gnus Country :-). It's a three step process: First we -make faces (specifications of how summary-line shall look -like) for those postings, then we'll give them some -special score and finally we'll tell Gnus to use the new -faces. You can find detailed instructions on how to do it on -@uref{http://my.gnus.org/node/view/224, my.gnus.org} - -@node FAQ 4-12 -@subsubheading Question 4.12 - -The number of total messages in a group which Gnus -displays in group buffer is by far to high, especially in -mail groups. Is this a bug? - -@subsubheading Answer - -No, that's a matter of design of Gnus, fixing this would -mean reimplementation of major parts of Gnus' -back ends. Gnus thinks "highest-article-number - -lowest-article-number = total-number-of-articles". This -works OK for Usenet groups, but if you delete and move -many messages in mail groups, this fails. To cure the -symptom, enter the group via @samp{C-u RET} -(this makes Gnus get all messages), then -hit @samp{M P b} to mark all messages and -then say @samp{B m name.of.group} to move -all messages to the group they have been in before, they -get new message numbers in this process and the count is -right again (until you delete and move your mail to other -groups again). - -@node FAQ 4-13 -@subsubheading Question 4.13 - -I don't like the layout of summary and article buffer, how -to change it? Perhaps even a three pane display? - -@subsubheading Answer - -You can control the windows configuration by calling the -function gnus-add-configuration. The syntax is a bit -complicated but explained very well in the manual node -"Window Layout". Some popular examples: - -Instead 25% summary 75% article buffer 35% summary and 65% -article (the 1.0 for article means "take the remaining -space"): - -@example -(gnus-add-configuration - '(article (vertical 1.0 (summary .35 point) (article 1.0)))) -@end example -@noindent - -A three pane layout, Group buffer on the left, summary -buffer top-right, article buffer bottom-right: - -@example -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 0.25 point) - (article 1.0))))) -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 - (group 1.0)) - (vertical 1.0 - (summary 1.0 point))))) -@end example -@noindent - -@node FAQ 4-14 -@subsubheading Question 4.14 - -I don't like the way the Summary buffer looks, how to tweak it? - -@subsubheading Answer - -You've got to play around with the variable -gnus-summary-line-format. It's value is a string of -symbols which stand for things like author, date, subject -etc. A list of the available specifiers can be found in the -manual node "Summary Buffer Lines" and the often forgotten -node "Formatting Variables" and it's sub-nodes. There -you'll find useful things like positioning the cursor and -tabulators which allow you a summary in table form, but -sadly hard tabulators are broken in 5.8.8. - -Since 5.10, Gnus offers you some very nice new specifiers, -e.g. %B which draws a thread-tree and %&user-date which -gives you a date where the details are dependent of the -articles age. Here's an example which uses both: - -@example -(setq gnus-summary-line-format ":%U%R %B %s %-60=|%4L |%-20,20f |%&user-date; \n") -@end example -@noindent - -resulting in: - -@example -:O Re: [Richard Stallman] rfc2047.el | 13 |Lars Magne Ingebrigt |Sat 23:06 -:O Re: Revival of the ding-patches list | 13 |Lars Magne Ingebrigt |Sat 23:12 -:R > Re: Find correct list of articles for a gro| 25 |Lars Magne Ingebrigt |Sat 23:16 -:O \-> ... | 21 |Kai Grossjohann | 0:01 -:R > Re: Cry for help: deuglify.el - moving stuf| 28 |Lars Magne Ingebrigt |Sat 23:34 -:O \-> ... | 115 |Raymond Scholz | 1:24 -:O \-> ... | 19 |Lars Magne Ingebrigt |15:33 -:O Slow mailing list | 13 |Lars Magne Ingebrigt |Sat 23:49 -:O Re: `@@' mark not documented | 13 |Lars Magne Ingebrigt |Sat 23:50 -:R > Re: Gnus still doesn't count messages prope| 23 |Lars Magne Ingebrigt |Sat 23:57 -:O \-> ... | 18 |Kai Grossjohann | 0:35 -:O \-> ... | 13 |Lars Magne Ingebrigt | 0:56 -@end example -@noindent - -@node FAQ 4-15 -@subsubheading Question 4.15 - -How to split incoming mails in several groups? - -@subsubheading Answer - -Gnus offers two possibilities for splitting mail, the easy -nnmail-split-methods and the more powerful Fancy Mail -Splitting. I'll only talk about the first one, refer to -the manual, node "Fancy Mail Splitting" for the latter. - -The value of nnmail-split-methods is a list, each element -is a list which stands for a splitting rule. Each rule has -the form "group where matching articles should go to", -"regular expression which has to be matched", the first -rule which matches wins. The last rule must always be a -general rule (regular expression .*) which denotes where -articles should go which don't match any other rule. If -the folder doesn't exist yet, it will be created as soon -as an article lands there. By default the mail will be -send to all groups whose rules match. If you -don't want that (you probably don't want), say - -@example -(setq nnmail-crosspost nil) -@end example -@noindent - -in ~/.gnus.el. - -An example might be better than thousand words, so here's -my nnmail-split-methods. Note that I send duplicates in a -special group and that the default group is spam, since I -filter all mails out which are from some list I'm -subscribed to or which are addressed directly to me -before. Those rules kill about 80% of the Spam which -reaches me (Email addresses are changed to prevent spammers -from using them): - -@example -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") - ("Tagesschau" "^From: tagesschau $") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") - ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") - ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") - ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") - ("Spam" "^Subject:.*\\(\=\?ks_c_5601-1987\?\\|\=\?euc-kr\?\\|\=\?big5\?\\).*") - ("Spam" "^X-Mailer:\\(.*BulkMailer.*\\|.*MIME::Lite.*\\|\\)") - ("Spam" "^X-Mailer:\\(.*CyberCreek Avalanche\\|.*http\:\/\/GetResponse\.com\\)") - ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") - ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") - ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") - ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|adress@@two.invalid\\)") - ("Spam" ""))) -@end example -@noindent - -@node FAQ 5 - Composing messages -@subsection Composing messages - -@menu -* FAQ 5-1:: What are the basic commands I need to know for sending - mail and postings? -* FAQ 5-2:: How to enable automatic word-wrap when composing - messages? -* FAQ 5-3:: How to set stuff like From, Organization, Reply-To, - signature...? -* FAQ 5-4:: Can I set things like From, Signature etc group based on - the group I post too? -* FAQ 5-5:: Is there a spell-checker? Perhaps even on-the-fly - spell-checking? -* FAQ 5-6:: Can I set the dictionary based on the group I'm posting - to? -* FAQ 5-7:: Is there some kind of address-book, so I needn't - remember all those email addresses? -* FAQ 5-8:: Sometimes I see little images at the top of article - buffer. What's that and how can I send one with my postings, - too? -* FAQ 5-9:: Sometimes I accidentally hit r instead of f in - newsgroups. Can Gnus warn me, when I'm replying by mail in - newsgroups? -* FAQ 5-10:: How to tell Gnus not to generate a sender header? -* FAQ 5-11:: I want Gnus to locally store copies of my send mail and - news, how to do it? -* FAQ 5-12:: I want Gnus to kill the buffer after successful sending - instead of keeping it alive as "Sent mail to...", how to do it? -* FAQ 5-13:: People tell me my Message-IDs are not correct, why - aren't they and how to fix it? -@end menu - -@node FAQ 5-1 -@subsubheading Question 5.1 - -What are the basic commands I need to know for sending mail and postings? - -@subsubheading Answer - -To start composing a new mail hit @samp{m} -either in Group or Summary buffer, for a posting, it's -either @samp{a} in Group buffer and -filling the Newsgroups header manually -or @samp{a} in the Summary buffer of the -group where the posting shall be send to. Replying by mail -is -@samp{r} if you don't want to cite the -author, or import the cited text manually and -@samp{R} to cite the text of the original -message. For a follow up to a newsgroup, it's -@samp{f} and @samp{F} -(analogously to @samp{r} and -@samp{R}). - -Enter new headers above the line saying "--text follows -this line--", enter the text below the line. When ready -hit @samp{C-c C-c}, to send the message, -if you want to finish it later hit @samp{C-c -C-d} to save it in the drafts group, where you -can start editing it again by saying @samp{D -e}. - -@node FAQ 5-2 -@subsubheading Question 5.2 - -How to enable automatic word-wrap when composing messages? - -@subsubheading Answer - -Starting from No Gnus, automatic word-wrap is already enabled by -default, see the variable message-fill-column. - -For other versions of Gnus, say - -@example -(unless (boundp 'message-fill-column) - (add-hook 'message-mode-hook - (lambda () - (setq fill-column 72) - (turn-on-auto-fill)))) -@end example -@noindent - -in ~/.gnus.el. - -You can reformat a paragraph by hitting @samp{M-q} -(as usual). - -@node FAQ 5-3 -@subsubheading Question 5.3 - -How to set stuff like From, Organization, Reply-To, signature...? - -@subsubheading Answer - -There are other ways, but you should use posting styles -for this. (See below why). -This example should make the syntax clear: - -@example -(setq gnus-posting-styles - '((".*" - (name "Frank Schmitt") - (address "me@@there.invalid") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature") - ("X-SampleHeader" "foobar") - (eval (setq some-variable "Foo bar"))))) -@end example -@noindent - -The ".*" means that this settings are the default ones -(see below), valid values for the first element of the -following lists are signature, signature-file, -organization, address, name or body. The attribute name -can also be a string. In that case, this will be used as -a header name, and the value will be inserted in the -headers of the article; if the value is `nil', the header -name will be removed. You can also say (eval (foo bar)), -then the function foo will be evaluated with argument bar -and the result will be thrown away. - -@node FAQ 5-4 -@subsubheading Question 5.4 - -Can I set things like From, Signature etc group based on the group I post too? - -@subsubheading Answer - -That's the strength of posting styles. Before, we used ".*" -to set the default for all groups. You can use a regexp -like "^gmane" and the following settings are only applied -to postings you send to the gmane hierarchy, use -".*binaries" instead and they will be applied to postings -send to groups containing the string binaries in their -name etc. - -You can instead of specifying a regexp specify a function -which is evaluated, only if it returns true, the -corresponding settings take effect. Two interesting -candidates for this are message-news-p which returns t if -the current Group is a newsgroup and the corresponding -message-mail-p. - -Note that all forms that match are applied, that means in -the example below, when I post to -gmane.mail.spam.spamassassin.general, the settings under -".*" are applied and the settings under message-news-p and -those under "^gmane" and those under -"^gmane\\.mail\\.spam\\.spamassassin\\.general$". Because -of this put general settings at the top and specific ones -at the bottom. - -@example -(setq gnus-posting-styles - '((".*" ;;default - (name "Frank Schmitt") - (organization "Hamme net, kren mer och nimmi") - (signature-file "~/.signature")) - ((message-news-p) ;;Usenet news? - (address "mySpamTrap@@Frank-Schmitt.invalid") - (reply-to "hereRealRepliesOnlyPlease@@Frank-Schmitt.invalid")) - ((message-mail-p) ;;mail? - (address "usedForMails@@Frank-Schmitt.invalid")) - ("^gmane" ;;this is mail, too in fact - (address "usedForMails@@Frank-Schmitt.invalid") - (reply-to nil)) - ("^gmane\\.mail\\.spam\\.spamassassin\\.general$" - (eval (set (make-local-variable 'message-sendmail-envelope-from) - "Azzrael@@rz-online.de"))))) -@end example -@noindent - -@node FAQ 5-5 -@subsubheading Question 5.5 - -Is there a spell-checker? Perhaps even on-the-fly spell-checking? - -@subsubheading Answer - -You can use ispell.el to spell-check stuff in Emacs. So the -first thing to do is to make sure that you've got either -@uref{http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html, ispell} -or @uref{http://aspell.sourceforge.net/, aspell} -installed and in your Path. Then you need -@uref{http://www.kdstevens.com/~stevens/ispell-page.html, ispell.el} -and for on-the-fly spell-checking -@uref{http://www-sop.inria.fr/mimosa/personnel/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}. -Ispell.el is shipped with Emacs and available through the XEmacs package system, -flyspell.el is shipped with Emacs and part of XEmacs text-modes package which is -available through the package system, so there should be no need to install them -manually. - -Ispell.el assumes you use ispell, if you choose aspell say - -@example -(setq ispell-program-name "aspell") -@end example -@noindent - -in your Emacs configuration file. - -If you want your outgoing messages to be spell-checked, say - -@example -(add-hook 'message-send-hook 'ispell-message) -@end example -@noindent - -In your ~/.gnus.el, if you prefer on-the-fly spell-checking say - -@example -(add-hook 'message-mode-hook (lambda () (flyspell-mode 1))) -@end example -@noindent - -@node FAQ 5-6 -@subsubheading Question 5.6 - -Can I set the dictionary based on the group I'm posting to? - -@subsubheading Answer - -Yes, say something like - -@example -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch8")) - (t - (ispell-change-dictionary "english"))))) -@end example -@noindent - -in ~/.gnus.el. Change "^de\\." and "deutsch8" to something -that suits your needs. - -@node FAQ 5-7 -@subsubheading Question 5.7 - -Is there some kind of address-book, so I needn't remember -all those email addresses? - -@subsubheading Answer - -There's an very basic solution for this, mail aliases. -You can store your mail addresses in a ~/.mailrc file using a simple -alias syntax: - -@example -alias al "Al " -@end example -@noindent - -Then typing your alias (followed by a space or punctuation -character) on a To: or Cc: line in the message buffer will -cause Gnus to insert the full address for you. See the -node "Mail Aliases" in Message (not Gnus) manual for -details. - -However, what you really want is the Insidious Big Brother -Database bbdb. Get it through the XEmacs package system or from -@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. -Now place the following in ~/.gnus.el, to activate bbdb for Gnus: - -@example -(require 'bbdb) -(bbdb-initialize 'gnus 'message) -@end example -@noindent - -Now you probably want some general bbdb configuration, -place them in ~/.emacs: - -@example -(require 'bbdb) -;;If you don't live in Northern America, you should disable the -;;syntax check for telephone numbers by saying -(setq bbdb-north-american-phone-numbers-p nil) -;;Tell bbdb about your email address: -(setq bbdb-user-mail-names - (regexp-opt '("Your.Email@@here.invalid" - "Your.other@@mail.there.invalid"))) -;;cycling while completing email addresses -(setq bbdb-complete-name-allow-cycling t) -;;No popup-buffers -(setq bbdb-use-pop-up nil) -@end example -@noindent - -Now you should be ready to go. Say @samp{M-x bbdb RET -RET} to open a bbdb buffer showing all -entries. Say @samp{c} to create a new -entry, @samp{b} to search your BBDB and -@samp{C-o} to add a new field to an -entry. If you want to add a sender to the BBDB you can -also just hit `:' on the posting in the summary buffer and -you are done. When you now compose a new mail, -hit @samp{TAB} to cycle through know -recipients. - -@node FAQ 5-8 -@subsubheading Question 5.8 - -Sometimes I see little images at the top of article -buffer. What's that and how can I send one with my -postings, too? - -@subsubheading Answer - -Those images are called X-Faces. They are 48*48 pixel b/w -pictures, encoded in a header line. If you want to include -one in your posts, you've got to convert some image to a -X-Face. So fire up some image manipulation program (say -Gimp), open the image you want to include, cut out the -relevant part, reduce color depth to 1 bit, resize to -48*48 and save as bitmap. Now you should get the compface -package from -@uref{ftp://ftp.cs.indiana.edu:/pub/faces/, this site}. -and create the actual X-face by saying - -@example -cat file.xbm | xbm2ikon | compface > file.face -cat file.face | sed 's/\\/\\\\/g;s/\"/\\\"/g;' > file.face.quoted -@end example -@noindent - -If you can't use compface, there's an online X-face converter at -@uref{http://www.dairiki.org/xface/}. -If you use MS Windows, you could also use the WinFace program from -@uref{http://www.xs4all.nl/~walterln/winface/}. -Now you only have to tell Gnus to include the X-face in your postings by saying - -@example -(setq message-default-headers - (with-temp-buffer - (insert "X-Face: ") - (insert-file-contents "~/.xface") - (buffer-string))) -@end example -@noindent - -in ~/.gnus.el. If you use Gnus 5.10, you can simply add an entry - -@example -(x-face-file "~/.xface") -@end example -@noindent - -to gnus-posting-styles. - -@node FAQ 5-9 -@subsubheading Question 5.9 - -Sometimes I accidentally hit r instead of f in -newsgroups. Can Gnus warn me, when I'm replying by mail in -newsgroups? - -@subsubheading Answer - -Put this in ~/.gnus.el: - -@example -(setq gnus-confirm-mail-reply-to-news t) -@end example -@noindent - -if you already use Gnus 5.10, if you still use 5.8.8 or -5.9 try this instead: - -@example -(eval-after-load "gnus-msg" - '(unless (boundp 'gnus-confirm-mail-reply-to-news) - (defadvice gnus-summary-reply (around reply-in-news activate) - "Request confirmation when replying to news." - (interactive) - (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author? ")) - ad-do-it)))) -@end example -@noindent - -@node FAQ 5-10 -@subsubheading Question 5.10 - -How to tell Gnus not to generate a sender header? - -@subsubheading Answer - -Since 5.10 Gnus doesn't generate a sender header by -default. For older Gnus' try this in ~/.gnus.el: - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -@node FAQ 5-11 -@subsubheading Question 5.11 - -I want Gnus to locally store copies of my send mail and -news, how to do it? - -@subsubheading Answer - -You must set the variable gnus-message-archive-group to do -this. You can set it to a string giving the name of the -group where the copies shall go or like in the example -below use a function which is evaluated and which returns -the group to use. - -@example -(setq gnus-message-archive-group - '((if (message-news-p) - "nnml:Send-News" - "nnml:Send-Mail"))) -@end example -@noindent - -@node FAQ 5-12 -@subsubheading Question 5.12 - -I want Gnus to kill the buffer after successful sending instead of keeping -it alive as "Sent mail to...", how to do it? - -@subsubheading Answer - -Add this to your ~/.gnus: - -@example -(setq message-kill-buffer-on-exit t) -@end example -@noindent - -@node FAQ 5-13 -@subsubheading Question 5.13 - -People tell me my Message-IDs are not correct, why -aren't they and how to fix it? - -@subsubheading Answer - -The message-ID is an unique identifier for messages you -send. To make it unique, Gnus need to know which machine -name to put after the "@@". If the name of the machine -where Gnus is running isn't suitable (it probably isn't -at most private machines) you can tell Gnus what to use -by saying: - -@example -(setq message-user-fqdn "yourmachine.yourdomain.tld") -@end example -@noindent - -in ~/.gnus.el. If you use Gnus 5.9 or earlier, you can use this -instead (works for newer versions as well): - -@example -(eval-after-load "message" - '(let ((fqdn "yourmachine.yourdomain.tld"));; <-- Edit this! - (if (boundp 'message-user-fqdn) - (setq message-user-fqdn fqdn) - (gnus-message 1 "Redefining `message-make-fqdn'.") - (defun message-make-fqdn () - "Return user's fully qualified domain name." - fqdn)))) -@end example -@noindent - -If you have no idea what to insert for -"yourmachine.yourdomain.tld", you've got several -choices. You can either ask your provider if he allows -you to use something like -yourUserName.userfqdn.provider.net, or you can use -somethingUnique.yourdomain.tld if you own the domain -yourdomain.tld, or you can register at a service which -gives private users a FQDN for free. - -Finally you can tell Gnus not to generate a Message-ID -for News at all (and letting the server do the job) by saying - -@example -(setq message-required-news-headers - (remove' Message-ID message-required-news-headers)) -@end example -@noindent - -you can also tell Gnus not to generate Message-IDs for mail by saying - -@example -(setq message-required-mail-headers - (remove' Message-ID message-required-mail-headers)) -@end example -@noindent - -, however some mail servers don't generate proper -Message-IDs, too, so test if your Mail Server behaves -correctly by sending yourself a Mail and looking at the Message-ID. - -@node FAQ 6 - Old messages -@subsection Old messages - -@menu -* FAQ 6-1:: How to import my old mail into Gnus? -* FAQ 6-2:: How to archive interesting messages? -* FAQ 6-3:: How to search for a specific message? -* FAQ 6-4:: How to get rid of old unwanted mail? -* FAQ 6-5:: I want that all read messages are expired (at least in - some groups). How to do it? -* FAQ 6-6:: I don't want expiration to delete my mails but to move - them to another group. -@end menu - -@node FAQ 6-1 -@subsubheading Question 6.1 - -How to import my old mail into Gnus? - -@subsubheading Answer - -The easiest way is to tell your old mail program to -export the messages in mbox format. Most Unix mailers -are able to do this, if you come from the MS Windows -world, you may find tools at -@uref{http://mbx2mbox.sourceforge.net/}. - -Now you've got to import this mbox file into Gnus. To do -this, create a nndoc group based on the mbox file by -saying @samp{G f /path/file.mbox RET} in -Group buffer. You now have read-only access to your -mail. If you want to import the messages to your normal -Gnus mail groups hierarchy, enter the nndoc group you've -just created by saying @samp{C-u RET} -(thus making sure all messages are retrieved), mark all -messages by saying @samp{M P b} and -either copy them to the desired group by saying -@samp{B c name.of.group RET} or send them -through nnmail-split-methods (respool them) by saying -@samp{B r}. - -@node FAQ 6-2 -@subsubheading Question 6.2 - -How to archive interesting messages? - -@subsubheading Answer - -If you stumble across an interesting message, say in -gnu.emacs.gnus and want to archive it there are several -solutions. The first and easiest is to save it to a file -by saying @samp{O f}. However, wouldn't -it be much more convenient to have more direct access to -the archived message from Gnus? If you say yes, put this -snippet by Frank Haun in -~/.gnus.el: - -@example -(defun my-archive-article (&optional n) - "Copies one or more article(s) to a corresponding `nnml:' group, e.g. -`gnus.ding' goes to `nnml:1.gnus.ding'. And `nnml:List-gnus.ding' goes -to `nnml:1.List-gnus-ding'. - -Use process marks or mark a region in the summary buffer to archive -more then one article." - (interactive "P") - (let ((archive-name - (format - "nnml:1.%s" - (if (featurep 'xemacs) - (replace-in-string gnus-newsgroup-name "^.*:" "") - (replace-regexp-in-string "^.*:" "" gnus-newsgroup-name))))) - (gnus-summary-copy-article n archive-name))) -@end example -@noindent - -You can now say @samp{M-x -my-archive-article} in summary buffer to -archive the article under the cursor in a nnml -group. (Change nnml to your preferred back end) - -Of course you can also make sure the cache is enabled by saying - -@example -(setq gnus-use-cache t) -@end example -@noindent - -then you only have to set either the tick or the dormant -mark for articles you want to keep, setting the read -mark will remove them from cache. - -@node FAQ 6-3 -@subsubheading Question 6.3 - -How to search for a specific message? - -@subsubheading Answer - -There are several ways for this, too. For a posting from -a Usenet group the easiest solution is probably to ask -@uref{http://groups.google.com, groups.google.com}, -if you found the posting there, tell Google to display -the raw message, look for the message-id, and say -@samp{M-^ the@@message.id RET} in a -summary buffer. -Since Gnus 5.10 there's also a Gnus interface for -groups.google.com which you can call with -@samp{G W}) in group buffer. - -Another idea which works for both mail and news groups -is to enter the group where the message you are -searching is and use the standard Emacs search -@samp{C-s}, it's smart enough to look at -articles in collapsed threads, too. If you want to -search bodies, too try @samp{M-s} -instead. Further on there are the -gnus-summary-limit-to-foo functions, which can help you, -too. - -Of course you can also use grep to search through your -local mail, but this is both slow for big archives and -inconvenient since you are not displaying the found mail -in Gnus. Here comes nnir into action. Nnir is a front end -to search engines like swish-e or swish++ and -others. You index your mail with one of those search -engines and with the help of nnir you can search trough -the indexed mail and generate a temporary group with all -messages which met your search criteria. If this sound -cool to you get nnir.el from -@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/} -or @uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}. -Instructions on how to use it are at the top of the file. - -@node FAQ 6-4 -@subsubheading Question 6.4 - -How to get rid of old unwanted mail? - -@subsubheading Answer - -You can of course just mark the mail you don't need -anymore by saying @samp{#} with point -over the mail and then say @samp{B DEL} -to get rid of them forever. You could also instead of -actually deleting them, send them to a junk-group by -saying @samp{B m nnml:trash-bin} which -you clear from time to time, but both are not the intended -way in Gnus. - -In Gnus, we let mail expire like news expires on a news -server. That means you tell Gnus the message is -expirable (you tell Gnus "I don't need this mail -anymore") by saying @samp{E} with point -over the mail in summary buffer. Now when you leave the -group, Gnus looks at all messages which you marked as -expirable before and if they are old enough (default is -older than a week) they are deleted. - -@node FAQ 6-5 -@subsubheading Question 6.5 - -I want that all read messages are expired (at least in -some groups). How to do it? - -@subsubheading Answer - -If you want all read messages to be expired (e.g. in -mailing lists where there's an online archive), you've -got two choices: auto-expire and -total-expire. Auto-expire means, that every article -which has no marks set and is selected for reading is -marked as expirable, Gnus hits @samp{E} -for you every time you read a message. Total-expire -follows a slightly different approach, here all article -where the read mark is set are expirable. - -To activate auto-expire, include auto-expire in the -Group parameters for the group. (Hit @samp{G -c} in summary buffer with point over the -group to change group parameters). For total-expire add -total-expire to the group-parameters. - -Which method you choose is merely a matter of taste: -Auto-expire is faster, but it doesn't play together with -Adaptive Scoring, so if you want to use this feature, -you should use total-expire. - -If you want a message to be excluded from expiration in -a group where total or auto expire is active, set either -tick (hit @samp{u}) or dormant mark (hit -@samp{u}), when you use auto-expire, you -can also set the read mark (hit -@samp{d}). - -@node FAQ 6-6 -@subsubheading Question 6.6 - -I don't want expiration to delete my mails but to move them -to another group. - -@subsubheading Answer - -Say something like this in ~/.gnus.el: - -@example -(setq nnmail-expiry-target "nnml:expired") -@end example -@noindent - -(If you want to change the value of nnmail-expiry-target -on a per group basis see the question "How can I disable -threading in some (e.g. mail-) groups, or set other -variables specific for some groups?") - -@node FAQ 7 - Gnus in a dial-up environment -@subsection Gnus in a dial-up environment - -@menu -* FAQ 7-1:: I don't have a permanent connection to the net, how can I - minimize the time I've got to be connected? -* FAQ 7-2:: So what was this thing about the Agent? -* FAQ 7-3:: I want to store article bodies on disk, too. How to do - it? -* FAQ 7-4:: How to tell Gnus not to try to send mails / postings - while I'm offline? -@end menu - -@node FAQ 7-1 -@subsubheading Question 7.1 - -I don't have a permanent connection to the net, how can -I minimize the time I've got to be connected? - -@subsubheading Answer - -You've got basically two options: Either you use the -Gnus Agent (see below) for this, or you can install -programs which fetch your news and mail to your local -disk and Gnus reads the stuff from your local -machine. - -If you want to follow the second approach, you need a -program which fetches news and offers them to Gnus, a -program which does the same for mail and a program which -receives the mail you write from Gnus and sends them -when you're online. - -Let's talk about Unix systems first: For the news part, -the easiest solution is a small nntp server like -@uref{http://www.leafnode.org/, Leafnode} or -@uref{http://infa.abo.fi/~patrik/sn/, sn}, -of course you can also install a full featured news -server like -@uref{http://www.isc.org/products/INN/, inn}. -Then you want to fetch your Mail, popular choices -are @uref{http://www.catb.org/~esr/fetchmail/, fetchmail} -and @uref{http://www.qcc.ca/~charlesc/software/getmail-3.0/, getmail}. -You should tell those to write the mail to your disk and -Gnus to read it from there. Last but not least the mail -sending part: This can be done with every MTA like -@uref{http://www.sendmail.org/, sendmail}, -@uref{http://www.qmail.org/, postfix}, -@uref{http://www.exim.org/, exim} or -@uref{http://www.qmail.org/, qmail}. - -On windows boxes I'd vote for -@uref{http://www.tglsoft.de/, Hamster}, -it's a small freeware, open-source program which fetches -your mail and news from remote servers and offers them -to Gnus (or any other mail and/or news reader) via nntp -respectively POP3 or IMAP. It also includes a smtp -server for receiving mails from Gnus. - -@node FAQ 7-2 -@subsubheading Question 7.2 - -So what was this thing about the Agent? - -@subsubheading Answer - -The Gnus agent is part of Gnus, it allows you to fetch -mail and news and store them on disk for reading them -later when you're offline. It kind of mimics offline -newsreaders like e.g. Forte Agent. If you want to use -the Agent place the following in ~/.gnus.el if you are -still using 5.8.8 or 5.9 (it's the default since 5.10): - -@example -(setq gnus-agent t) -@end example -@noindent - -Now you've got to select the servers whose groups can be -stored locally. To do this, open the server buffer -(that is press @samp{^} while in the -group buffer). Now select a server by moving point to -the line naming that server. Finally, agentize the -server by typing @samp{J a}. If you -make a mistake, or change your mind, you can undo this -action by typing @samp{J r}. When -you're done, type 'q' to return to the group buffer. -Now the next time you enter a group on a agentized -server, the headers will be stored on disk and read from -there the next time you enter the group. - -@node FAQ 7-3 -@subsubheading Question 7.3 - -I want to store article bodies on disk, too. How to do it? - -@subsubheading Answer - -You can tell the agent to automatically fetch the bodies -of articles which fulfill certain predicates, this is -done in a special buffer which can be reached by -saying @samp{J c} in group -buffer. Please refer to the documentation for -information which predicates are possible and how -exactly to do it. - -Further on you can tell the agent manually which -articles to store on disk. There are two ways to do -this: Number one: In the summary buffer, process mark a -set of articles that shall be stored in the agent by -saying @samp{#} with point over the -article and then type @samp{J s}. The -other possibility is to set, again in the summary -buffer, downloadable (%) marks for the articles you -want by typing @samp{@@} with point over -the article and then typing @samp{J u}. -What's the difference? Well, process marks are erased as -soon as you exit the summary buffer while downloadable -marks are permanent. You can actually set downloadable -marks in several groups then use fetch session ('J s' in -the GROUP buffer) to fetch all of those articles. The -only downside is that fetch session also fetches all of -the headers for every selected group on an agentized -server. Depending on the volume of headers, the initial -fetch session could take hours. - -@node FAQ 7-4 -@subsubheading Question 7.4 - -How to tell Gnus not to try to send mails / postings -while I'm offline? - -@subsubheading Answer - -All you've got to do is to tell Gnus when you are online -(plugged) and when you are offline (unplugged), the rest -works automatically. You can toggle plugged/unplugged -state by saying @samp{J j} in group -buffer. To start Gnus unplugged say @samp{M-x -gnus-unplugged} instead of -@samp{M-x gnus}. Note that for this to -work, the agent must be active. - -@node FAQ 8 - Getting help -@subsection Getting help - -@menu -* FAQ 8-1:: How to find information and help inside Emacs? -* FAQ 8-2:: I can't find anything in the Gnus manual about X (e.g. - attachments, PGP, MIME...), is it not documented? -* FAQ 8-3:: Which websites should I know? -* FAQ 8-4:: Which mailing lists and newsgroups are there? -* FAQ 8-5:: Where to report bugs? -* FAQ 8-6:: I need real-time help, where to find it? -@end menu - -@node FAQ 8-1 -@subsubheading Question 8.1 - -How to find information and help inside Emacs? - -@subsubheading Answer - -The first stop should be the Gnus manual (Say -@samp{C-h i d m Gnus RET} to start the -Gnus manual, then walk through the menus or do a -full-text search with @samp{s}). Then -there are the general Emacs help commands starting with -C-h, type @samp{C-h ? ?} to get a list -of all available help commands and their meaning. Finally -@samp{M-x apropos-command} lets you -search through all available functions and @samp{M-x -apropos} searches the bound variables. - -@node FAQ 8-2 -@subsubheading Question 8.2 - -I can't find anything in the Gnus manual about X -(e.g. attachments, PGP, MIME...), is it not documented? - -@subsubheading Answer - -There's not only the Gnus manual but also the manuals -for message, emacs-mime, sieve and pgg. Those packages -are distributed with Gnus and used by Gnus but aren't -really part of core Gnus, so they are documented in -different info files, you should have a look in those -manuals, too. - -@node FAQ 8-3 -@subsubheading Question 8.3 - -Which websites should I know? - -@subsubheading Answer - -The two most important ones are the -@uref{http://www.gnus.org, official Gnus website}. -and it's sister site -@uref{http://my.gnus.org, my.gnus.org (MGO)}, -hosting an archive of lisp snippets, howtos, a (not -really finished) tutorial and this FAQ. - -Tell me about other sites which are interesting. - -@node FAQ 8-4 -@subsubheading Question 8.4 - -Which mailing lists and newsgroups are there? - -@subsubheading Answer - -There's the newsgroup gnu.emacs.gnus (also available as -@uref{http://dir.gmane.org/gmane.emacs.gnus.user, -gmane.emacs.gnus.user}) which deals with general Gnus -questions. If you have questions about development versions of -Gnus, you should better ask on the ding mailing list, see below. - -If you want to stay in the big8, -news.software.readers is also read by some Gnus -users (but chances for qualified help are much better in -the above groups). If you speak German, there's -de.comm.software.gnus. - -The ding mailing list (ding@@gnus.org) deals with development of -Gnus. You can read the ding list via NNTP, too under the name -@uref{http://dir.gmane.org/gmane.emacs.gnus.general, -gmane.emacs.gnus.general} from news.gmane.org. - -@node FAQ 8-5 -@subsubheading Question 8.5 - -Where to report bugs? - -@subsubheading Answer - -Say @samp{M-x gnus-bug}, this will start -a message to the -@email{bugs@@gnus.org, gnus bug mailing list} -including information about your environment which make -it easier to help you. - -@node FAQ 8-6 -@subsubheading Question 8.6 - -I need real-time help, where to find it? - -@subsubheading Answer - -Point your IRC client to irc.freenode.net, channel #gnus. - -@node FAQ 9 - Tuning Gnus -@subsection Tuning Gnus - -@menu -* FAQ 9-1:: Starting Gnus is really slow, how to speed it up? -* FAQ 9-2:: How to speed up the process of entering a group? -* FAQ 9-3:: Sending mail becomes slower and slower, what's up? -@end menu - -@node FAQ 9-1 -@subsubheading Question 9.1 - -Starting Gnus is really slow, how to speed it up? - -@subsubheading Answer - -The reason for this could be the way Gnus reads it's -active file, see the node "The Active File" in the Gnus -manual for things you might try to speed the process up. -An other idea would be to byte compile your ~/.gnus.el (say -@samp{M-x byte-compile-file RET ~/.gnus.el -RET} to do it). Finally, if you have require -statements in your .gnus, you could replace them with -eval-after-load, which loads the stuff not at startup -time, but when it's needed. Say you've got this in your -~/.gnus.el: - -@example -(require 'message) -(add-to-list 'message-syntax-checks '(sender . disabled)) -@end example -@noindent - -then as soon as you start Gnus, message.el is loaded. If -you replace it with - -@example -(eval-after-load "message" - '(add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent - -it's loaded when it's needed. - -@node FAQ 9-2 -@subsubheading Question 9.2 - -How to speed up the process of entering a group? - -@subsubheading Answer - -A speed killer is setting the variable -gnus-fetch-old-headers to anything different from nil, -so don't do this if speed is an issue. To speed up -building of summary say - -@example -(gnus-compile) -@end example -@noindent - -at the bottom of your ~/.gnus.el, this will make gnus -byte-compile things like -gnus-summary-line-format. -then you could increase the value of gc-cons-threshold -by saying something like - -@example -(setq gc-cons-threshold 3500000) -@end example -@noindent - -in ~/.emacs. If you don't care about width of CJK -characters or use Gnus 5.10 or younger together with a -recent GNU Emacs, you should say - -@example -(setq gnus-use-correct-string-widths nil) -@end example -@noindent - -in ~/.gnus.el (thanks to Jesper harder for the last -two suggestions). Finally if you are still using 5.8.8 -or 5.9 and experience speed problems with summary -buffer generation, you definitely should update to -5.10 since there quite some work on improving it has -been done. - -@node FAQ 9-3 -@subsubheading Question 9.3 - -Sending mail becomes slower and slower, what's up? - -@subsubheading Answer - -The reason could be that you told Gnus to archive the -messages you wrote by setting -gnus-message-archive-group. Try to use a nnml group -instead of an archive group, this should bring you back -to normal speed. - -@node FAQ - Glossary -@subsection Glossary - -@table @dfn - -@item ~/.gnus.el -When the term ~/.gnus.el is used it just means your Gnus -configuration file. You might as well call it ~/.gnus or -specify another name. - -@item Back End -In Gnus terminology a back end is a virtual server, a layer -between core Gnus and the real NNTP-, POP3-, IMAP- or -whatever-server which offers Gnus a standardized interface -to functions like "get message", "get Headers" etc. - -@item Emacs -When the term Emacs is used in this FAQ, it means either GNU -Emacs or XEmacs. - -@item Message -In this FAQ message means a either a mail or a posting to a -Usenet Newsgroup or to some other fancy back end, no matter -of which kind it is. - -@item MUA -MUA is an acronym for Mail User Agent, it's the program you -use to read and write e-mails. - -@item NUA -NUA is an acronym for News User Agent, it's the program you -use to read and write Usenet news. - -@end table - -@ignore -arch-tag: 64dc5692-edb4-4848-a965-7aa0181acbb8 -@end ignore diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el deleted file mode 100644 index 05192f1a1a6..00000000000 --- a/doc/misc/gnus-news.el +++ /dev/null @@ -1,117 +0,0 @@ -;;; gnus-news.el --- a hack to create GNUS-NEWS from texinfo source -;; Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -;; Author: Reiner Steib -;; Keywords: tools - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;;; Code: - -(defvar gnus-news-header-disclaimer -"GNUS NEWS -- history of user-visible changes. - -Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, - 2006, 2007, 2008, 2009 Free Software Foundation, Inc. -See the end of the file for license conditions. - -Please send Gnus bug reports to bugs@gnus.org. -For older news, see Gnus info node \"New Features\".\n\n") - -(defvar gnus-news-trailer -" -* For older news, see Gnus info node \"New Features\". - ----------------------------------------------------------------------- - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -\(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see . - - \nLocal variables:\nmode: outline -paragraph-separate: \"[ ]*$\"\nend:\n") - -(defvar gnus-news-makeinfo-command "makeinfo") - -(defvar gnus-news-fill-column 80) - -(defvar gnus-news-makeinfo-switches - (concat " --no-headers --paragraph-indent=0" - " --no-validate" ;; Allow unresolved references. - " --fill-column=" (number-to-string - (+ 3 ;; will strip leading spaces later - (or gnus-news-fill-column 80))))) - -(defun batch-gnus-news () - "Make GNUS-NEWS in batch mode." - (let (infile outfile) - (setq infile (car command-line-args-left) - command-line-args-left (cdr command-line-args-left) - outfile (car command-line-args-left) - command-line-args-left nil) - (if (and infile outfile) - (message "Creating `%s' from `%s'..." outfile infile) - (error "Not enough files given.")) - (gnus-news-translate-file infile outfile))) - -(defun gnus-news-translate-file (infile outfile) - "Translate INFILE (texinfo) to OUTFILE (GNUS-NEWS)." - (let* ((dir (concat (or (getenv "srcdir") ".") "/")) - (infile (concat dir infile)) - (buffer (find-file-noselect (concat dir outfile)))) - (with-temp-buffer - ;; Could be done using `texinfmt' stuff as in `infohack.el'. - (insert - (shell-command-to-string - (concat gnus-news-makeinfo-command " " - gnus-news-makeinfo-switches " " infile))) - (goto-char (point-max)) - (delete-char -1) - (goto-char (point-min)) - (save-excursion - (while (re-search-forward "^ \\* " nil t) - (replace-match "\f\n* "))) - (save-excursion - (while (re-search-forward "^ \\* " nil t) - (replace-match "** "))) - (save-excursion - (while (re-search-forward "^ " nil t) - (replace-match ""))) - ;; Avoid `*' from @ref at beginning of line: - (save-excursion - (while (re-search-forward "^\\*Note" nil t) - (replace-match " \\&"))) - (goto-char (point-min)) - (insert gnus-news-header-disclaimer) - (goto-char (point-max)) - (insert gnus-news-trailer) - (write-region (point-min) (point-max) outfile)))) - -;; arch-tag: e23cdd27-eafd-4ba0-816f-98f5edb0dc29 -;;; gnus-news.el ends here diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi deleted file mode 100644 index 09d7be56a7a..00000000000 --- a/doc/misc/gnus-news.texi +++ /dev/null @@ -1,322 +0,0 @@ -@c -*-texinfo-*- - -@c Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document as received, in any medium, provided that the -@c copyright notice and this permission notice are preserved, -@c thus giving the recipient permission to redistribute in turn. - -@c Permission is granted to distribute modified versions -@c of this document, or of portions of it, -@c under the above conditions, provided also that they -@c carry prominent notices stating who last changed them. - -@c This file contains a list of news features Gnus. It is supposed to be -@c included in `gnus.texi'. `GNUS-NEWS' is automatically generated from -@c this file (see `gnus-news.el'). - -@itemize @bullet - -@item Installation changes - -@itemize @bullet -@item Upgrading from previous (stable) version if you have used No Gnus. - -If you have tried No Gnus (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading -to this version. In particular, you will probably want to remove the -@file{~/News/marks} directory (perhaps selectively), so that flags are -read from your @file{~/.newsrc.eld} instead of from the stale marks -file, where this release will store flags for nntp. See a later entry -for more information about nntp marks. Note that downgrading isn't -safe in general. - -@item Incompatibility when switching from Emacs 23 to Emacs 22 -In Emacs 23, Gnus uses Emacs' new internal coding system @code{utf-8-emacs} -for saving articles drafts and @file{~/.newsrc.eld}. These files may not -be read correctly in Emacs 22 and below. If you want to use Gnus across -different Emacs versions, you may set @code{mm-auto-save-coding-system} -to @code{emacs-mule}. -@c FIXME: Untested. (Or did anyone test it?) -@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 - -@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item The installation directory name is allowed to have spaces and/or tabs. -@end itemize - -@item New packages and libraries within Gnus - -@itemize @bullet - -@item Gnus includes the Emacs Lisp @acronym{SASL} library. - -This provides a clean @acronym{API} to @acronym{SASL} mechanisms from -within Emacs. The user visible aspects of this, compared to the earlier -situation, include support for @acronym{DIGEST}-@acronym{MD5} and -@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. - -@item ManageSieve connections uses the @acronym{SASL} library by default. - -The primary change this brings is support for @acronym{DIGEST-MD5} and -@acronym{NTLM}, when the server supports it. - -@item Gnus includes a password cache mechanism in password.el. - -It is enabled by default (see @code{password-cache}), with a short -timeout of 16 seconds (see @code{password-cache-expiry}). If -@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} -passphrase is managed by this mechanism. Passwords for ManageSieve -connections are managed by this mechanism, after querying the user -about whether to do so. - -@item Using EasyPG with Gnus -When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. -EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, -,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. -EasyPG is included in Emacs 23 and available separately as well. -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. -(New in Gnus 5.10.10 / No Gnus 0.8) -@c This entry is also present in the node "Oort Gnus". - -@end itemize - -@item Changes in summary and article mode - -@itemize @bullet - -@item Gnus now supports sticky article buffers. Those are article buffers -that are not reused when you select another article. @xref{Sticky -Articles}. - -@c @item Bookmarks -@c FIXME: To be added - -@item Gnus can selectively display @samp{text/html} articles -with a WWW browser with @kbd{K H}. @xref{MIME Commands}. - -@c gnus-registry-marks -@c FIXME: To be added - -@item International host names (@acronym{IDNA}) can now be decoded -inside article bodies using @kbd{W i} -(@code{gnus-summary-idna-message}). This requires that GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) has been installed. -@c FIXME: Also mention @code{message-use-idna}? - -@item The non-@acronym{ASCII} group names handling has been much -improved. The back ends that fully support non-@acronym{ASCII} group -names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the -agent, the cache, and the marks features work with those back ends. -@xref{Non-ASCII Group Names}. - -@item Gnus now displays @acronym{DNS} master files sent as text/dns -using dns-mode. - -@item Gnus supports new limiting commands in the Summary buffer: -@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} -(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. - -@item You can now fetch all ticked articles from the server using -@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary -Generation Commands}. - -@item Gnus supports a new sort command in the Summary buffer: -@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary -Sorting}. - -@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. -You need to configure the server in @code{smime-ldap-host-list}. - -@item URLs inside Open@acronym{PGP} headers are retrieved and imported -to your PGP key ring when you click on them. - -@item -Picons can be displayed right from the textual address, see -@code{gnus-picon-style}. @xref{Picons}. - -@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed -using @kbd{W A}. - -@acronym{ANSI} sequences are used in some Chinese hierarchies for -highlighting articles (@code{gnus-article-treat-ansi-sequences}). - -@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. -This changes the default of @code{gnus-article-loose-mime}. - -@item @code{gnus-decay-scores} can be a regexp matching score files. -For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files -will be decayed. @xref{Score Decays}. - -@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in -summary lines when using @code{gnus-ignored-from-addresses} can be -customized with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. - -@item You can replace @acronym{MIME} parts with external bodies. -See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. -@xref{MIME Commands}, @ref{Using MIME}. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -format=flowed messages. Also, flowed text is disabled when sending -inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "Oort Gnus". - -@item Now the new command @kbd{S W} -(@code{gnus-article-wide-reply-with-original}) for a wide reply in the -article buffer yanks a text that is in the active region, if it is set, -as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. -Note that the @kbd{R} command in the article buffer no longer accepts a -prefix argument, which was used to make it do a wide reply. -@xref{Article Keymap}. - -@item The new command @kbd{C-h b} -(@code{gnus-article-describe-bindings}) used in the article buffer now -shows not only the article commands but also the real summary commands -that are accessible from the article buffer. - -@end itemize - -@item Changes in Message mode - -@itemize @bullet -@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. -Use @code{(setq message-generate-hashcash t)} to enable. -@xref{Hashcash}. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. - -@item The option @code{message-yank-empty-prefix} now controls how -empty lines are prefixed in cited text. @xref{Insertion Variables, -,Insertion Variables, message, Message Manual}. - -@item Gnus uses narrowing to hide headers in Message buffers. -The @code{References} header is hidden by default. To make all -headers visible, use @code{(setq message-hidden-headers nil)}. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@item You can highlight different levels of citations like in the -article buffer. See @code{gnus-message-highlight-citation}. - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. - -@item You can now store signature files in a special directory -named @code{message-signature-directory}. - -@item The option @code{message-citation-line-format} controls the format -of the "Whomever writes:" line. You need to set -@code{message-citation-line-function} to -@code{message-insert-formatted-citation-line} as well. -@end itemize - -@item Changes in back ends - -@itemize @bullet -@item The nntp back end stores article marks in @file{~/News/marks}. - -The directory can be changed using the (customizable) variable -@code{nntp-marks-directory}, and marks can be disabled using the -(back end) variable @code{nntp-marks-is-evil}. The advantage of this -is that you can copy @file{~/News/marks} (using rsync, scp or -whatever) to another Gnus installation, and it will realize what -articles you have read and marked. The data in @file{~/News/marks} -has priority over the same data in @file{~/.newsrc.eld}. - -@item -You can import and export your @acronym{RSS} subscriptions from -@acronym{OPML} files. @xref{RSS}. - -@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. - -By default, Gnus does not send any information about itself, but you can -customize it using the variable @code{nnimap-id}. - -@item The @code{nnrss} back end now supports multilingual text. -Non-@acronym{ASCII} group names for the @code{nnrss} groups are also -supported. @xref{RSS}. - -@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. - -@item The nnml back end allows other compression programs beside @file{gzip} -for compressed message files. @xref{Mail Spool}. - -@item The nnml back end supports group compaction. - -This feature, accessible via the functions -@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and -@code{gnus-server-compact-server} (@kbd{z} in the server buffer) -renumbers all articles in a group, starting from 1 and removing gaps. -As a consequence, you get a correct total article count (until -messages are deleted again). - -@c @item nnmairix.el -@c FIXME - -@c @item nnir.el -@c FIXME - -@end itemize - -@item Appearance -@c Maybe it's not worth to separate this from "Miscellaneous"? - -@itemize @bullet - -@item The tool bar has been updated to use GNOME icons. -You can also customize the tool bars: @kbd{M-x customize-apropos RET --tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) -@c FIXME: Document this in the manual - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. -@c FIXME: Document this in the manual - -@item You can change the location of XEmacs' toolbars in Gnus buffers. -See @code{gnus-use-toolbar} and @code{message-use-toolbar}. - -@end itemize - -@item Miscellaneous changes - -@itemize @bullet -@item Having edited the select-method for the foreign server in the -server buffer is immediately reflected to the subscription of the groups -which use the server in question. For instance, if you change -@code{nntp-via-address} into @samp{bar.example.com} from -@samp{foo.example.com}, Gnus will connect to the news host by way of the -intermediate host @samp{bar.example.com} from next time. - -@item The @file{all.SCORE} file can be edited from the group buffer -using @kbd{W e}. - -@end itemize - -@end itemize - -@c gnus-news.texi ends here. - -@ignore - arch-tag: 872c7569-4340-4d73-9d1d-7826d9f94a51 -@end ignore diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi deleted file mode 100644 index a7eb08101a2..00000000000 --- a/doc/misc/gnus.texi +++ /dev/null @@ -1,31302 +0,0 @@ -\input texinfo - -@setfilename ../../info/gnus -@settitle Gnus Manual -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex pg cp - -@documentencoding ISO-8859-1 - -@copying -Copyright @copyright{} 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@iftex -@iflatex -\documentclass[twoside,a4paper,openright,11pt]{book} -\usepackage[latin1]{inputenc} -\usepackage{pagestyle} -\usepackage{epsfig} -\usepackage{pixidx} -\input{gnusconfig.tex} - -\ifx\pdfoutput\undefined -\else -\usepackage[pdftex,bookmarks,colorlinks=true]{hyperref} -\usepackage{thumbpdf} -\pdfcompresslevel=9 -\fi - -\makeindex -\begin{document} - -% Adjust ../Makefile.in if you change the following line: -\newcommand{\gnusversionname}{Gnus v5.13} -\newcommand{\gnuschaptername}{} -\newcommand{\gnussectionname}{} - -\newcommand{\gnusbackslash}{/} - -\newcommand{\gnusref}[1]{``#1'' on page \pageref{#1}} -\ifx\pdfoutput\undefined -\newcommand{\gnusuref}[1]{\gnustt{#1}} -\else -\newcommand{\gnusuref}[1]{\href{#1}{\gnustt{#1}}} -\fi -\newcommand{\gnusxref}[1]{See ``#1'' on page \pageref{#1}} -\newcommand{\gnuspxref}[1]{see ``#1'' on page \pageref{#1}} - -\newcommand{\gnuskindex}[1]{\index{#1}} -\newcommand{\gnusindex}[1]{\index{#1}} - -\newcommand{\gnustt}[1]{{\gnusselectttfont{}#1}} -\newcommand{\gnuscode}[1]{\gnustt{#1}} -\newcommand{\gnusasis}[1]{\gnustt{#1}} -\newcommand{\gnusurl}[1]{\gnustt{#1}} -\newcommand{\gnuscommand}[1]{\gnustt{#1}} -\newcommand{\gnusenv}[1]{\gnustt{#1}} -\newcommand{\gnussamp}[1]{``{\fontencoding{OT1}\gnusselectttfont{}#1}''} -\newcommand{\gnuslisp}[1]{\gnustt{#1}} -\newcommand{\gnuskbd}[1]{`\gnustt{#1}'} -\newcommand{\gnuskey}[1]{`\gnustt{#1}'} -\newcommand{\gnusfile}[1]{`\gnustt{#1}'} -\newcommand{\gnusdfn}[1]{\textit{#1}} -\newcommand{\gnusi}[1]{\textit{#1}} -\newcommand{\gnusr}[1]{\textrm{#1}} -\newcommand{\gnusstrong}[1]{\textbf{#1}} -\newcommand{\gnusemph}[1]{\textit{#1}} -\newcommand{\gnusvar}[1]{{\fontsize{10pt}{10}\selectfont\textsl{\textsf{#1}}}} -\newcommand{\gnussc}[1]{\textsc{#1}} -\newcommand{\gnustitle}[1]{{\huge\textbf{#1}}} -\newcommand{\gnusversion}[1]{{\small\textit{#1}}} -\newcommand{\gnusauthor}[1]{{\large\textbf{#1}}} -\newcommand{\gnusresult}[1]{\gnustt{=> #1}} -\newcommand{\gnusacronym}[1]{\textsc{#1}} -\newcommand{\gnusemail}[1]{\textit{#1}} - -\newcommand{\gnusbullet}{{${\bullet}$}} -\newcommand{\gnusdollar}{\$} -\newcommand{\gnusampersand}{\&} -\newcommand{\gnuspercent}{\%} -\newcommand{\gnushash}{\#} -\newcommand{\gnushat}{\symbol{"5E}} -\newcommand{\gnusunderline}{\symbol{"5F}} -\newcommand{\gnusnot}{$\neg$} -\newcommand{\gnustilde}{\symbol{"7E}} -\newcommand{\gnusless}{{$<$}} -\newcommand{\gnusgreater}{{$>$}} -\newcommand{\gnusbraceleft}{{$>$}} -\newcommand{\gnusbraceright}{{$>$}} - -\newcommand{\gnushead}{\raisebox{-1cm}{\epsfig{figure=ps/gnus-head,height=1cm}}} -\newcommand{\gnusinteresting}{ -\marginpar[\mbox{}\hfill\gnushead]{\gnushead} -} - -\newcommand{\gnuscleardoublepage}{\ifodd\count0\mbox{}\clearpage\thispagestyle{empty}\mbox{}\clearpage\else\clearpage\fi} - -\newcommand{\gnuspagechapter}[1]{ -{\mbox{}} -} - -\newdimen{\gnusdimen} -\gnusdimen 0pt - -\newcommand{\gnuschapter}[2]{ -\gnuscleardoublepage -\ifdim \gnusdimen = 0pt\setcounter{page}{1}\pagestyle{gnus}\pagenumbering{arabic} \gnusdimen 1pt\fi -\chapter{#2} -\renewcommand{\gnussectionname}{} -\renewcommand{\gnuschaptername}{#2} -\thispagestyle{empty} -\hspace*{-2cm} -\begin{picture}(500,500)(0,0) -\put(480,350){\makebox(0,0)[tr]{#1}} -\put(40,300){\makebox(500,50)[bl]{{\Huge\bf{#2}}}} -\end{picture} -\clearpage -} - -\newcommand{\gnusfigure}[3]{ -\begin{figure} -\mbox{}\ifodd\count0\hspace*{-0.8cm}\else\hspace*{-3cm}\fi\begin{picture}(440,#2) -#3 -\end{picture} -\caption{#1} -\end{figure} -} - -\newcommand{\gnusicon}[1]{ -\marginpar[\mbox{}\hfill\raisebox{-1.5cm}{\epsfig{figure=ps/#1-up,height=1.5cm}}]{\raisebox{-1cm}{\epsfig{figure=ps/#1-up,height=1cm}}} -} - -\newcommand{\gnuspicon}[1]{ -\margindex{\epsfig{figure=#1,width=2cm}} -} - -\newcommand{\gnusxface}[2]{ -\margindex{\epsfig{figure=#1,width=1cm}\epsfig{figure=#2,width=1cm}} -} - -\newcommand{\gnussmiley}[2]{ -\margindex{\makebox[2cm]{\hfill\epsfig{figure=#1,width=0.5cm}\hfill\epsfig{figure=#2,width=0.5cm}\hfill}} -} - -\newcommand{\gnusitemx}[1]{\mbox{}\vspace*{-\itemsep}\vspace*{-\parsep}\item#1} - -\newcommand{\gnussection}[1]{ -\renewcommand{\gnussectionname}{#1} -\section{#1} -} - -\newenvironment{codelist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{asislist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{kbdlist}% -{\begin{list}{}{ -\labelwidth=0cm -} -}{\end{list}} - -\newenvironment{dfnlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{stronglist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{samplist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{varlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newenvironment{emphlist}% -{\begin{list}{}{ -} -}{\end{list}} - -\newlength\gnusheadtextwidth -\setlength{\gnusheadtextwidth}{\headtextwidth} -\addtolength{\gnusheadtextwidth}{1cm} - -\newpagestyle{gnuspreamble}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\mbox{}}\textbf{\hfill\roman{page}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\roman{page}\hfill\mbox{}}} -} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnusindex}% -{ -{ -\ifodd\count0 -{ -\hspace*{-0.23cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\gnuschaptername\hfill\arabic{page}}}} -} -\else -{ -\hspace*{-3.25cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\newpagestyle{gnus}% -{ -{ -\ifodd\count0 -{ -\makebox[12cm]{\hspace*{3.1cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{chapter}.\arabic{section}} \textbf{\gnussectionname\hfill\arabic{page}}}}} -} -\else -{ -\makebox[12cm]{\hspace*{-2.95cm}\underline{\makebox[\gnusheadtextwidth]{\textbf{\arabic{page}\hfill\gnuschaptername}}}} -} -\fi -} -} -{ -\ifodd\count0 -\mbox{} \hfill -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\else -\raisebox{-0.5cm}{\epsfig{figure=ps/gnus-big-logo,height=1cm}} -\hfill \mbox{} -\fi -} - -\pagenumbering{roman} -\pagestyle{gnuspreamble} - -@end iflatex -@end iftex - -@iftex -@iflatex - -\begin{titlepage} -{ - -%\addtolength{\oddsidemargin}{-5cm} -%\addtolength{\evensidemargin}{-5cm} -\parindent=0cm -\addtolength{\textheight}{2cm} - -\gnustitle{\gnustitlename}\hfill\gnusversion{\gnusversionname}\\ -\rule{15cm}{1mm}\\ -\vfill -\hspace*{0cm}\epsfig{figure=ps/gnus-big-logo,height=15cm} -\vfill -\rule{15cm}{1mm}\\ -\gnusauthor{by Lars Magne Ingebrigtsen} -\newpage -} - -\mbox{} -\vfill - -\thispagestyle{empty} - -@c @insertcopying -\newpage -\end{titlepage} -@end iflatex -@end iftex - -@dircategory Emacs -@direntry -* Gnus: (gnus). The newsreader Gnus. -@end direntry -@iftex -@finalout -@end iftex - - -@titlepage -@title Gnus Manual - -@author by Lars Magne Ingebrigtsen -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top The Gnus Newsreader - -@ifinfo - -You can read news (and mail) from within Emacs by using Gnus. The news -can be gotten by any nefarious means you can think of---@acronym{NNTP}, local -spool or your mbox file. All at the same time, if you want to push your -luck. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@ifnottex -@insertcopying -@end ifnottex - -@end ifinfo - -@iftex - -@iflatex -\tableofcontents -\gnuscleardoublepage -@end iflatex - -Gnus is the advanced, self-documenting, customizable, extensible -unreal-time newsreader for GNU Emacs. - -Oops. That sounds oddly familiar, so let's start over again to avoid -being accused of plagiarism: - -Gnus is a message-reading laboratory. It will let you look at just -about anything as if it were a newsgroup. You can read mail with it, -you can browse directories with it, you can @code{ftp} with it---you -can even read news with it! - -Gnus tries to empower people who read news the same way Emacs empowers -people who edit text. Gnus sets no limits to what the user should be -allowed to do. Users are encouraged to extend Gnus to make it behave -like they want it to behave. A program should not control people; -people should be empowered to do what they want by using (or abusing) -the program. - -@c Adjust ../Makefile.in if you change the following line: -This manual corresponds to Gnus v5.13 - -@heading Other related manuals -@itemize -@item Message manual: Composing messages -@item Emacs-MIME: Composing messages; @acronym{MIME}-specific parts. -@item Sieve: Managing Sieve scripts in Emacs. -@item PGG: @acronym{PGP/MIME} with Gnus. -@item SASL: @acronym{SASL} authentication in Emacs. -@end itemize - -@end iftex - -@menu -* Starting Up:: Finding news can be a pain. -* Group Buffer:: Selecting, subscribing and killing groups. -* Summary Buffer:: Reading, saving and posting articles. -* Article Buffer:: Displaying and handling articles. -* Composing Messages:: Information on sending mail and news. -* Select Methods:: Gnus reads all messages from various select methods. -* Scoring:: Assigning values to articles. -* Various:: General purpose settings. -* The End:: Farewell and goodbye. -* Appendices:: Terminology, Emacs intro, @acronym{FAQ}, History, Internals. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function and concept index. -* Key Index:: Key Index. - -Other related manuals - -* Message:(message). Composing messages. -* Emacs-MIME:(emacs-mime). Composing messages; @acronym{MIME}-specific parts. -* Sieve:(sieve). Managing Sieve scripts in Emacs. -* PGG:(pgg). @acronym{PGP/MIME} with Gnus. -* SASL:(sasl). @acronym{SASL} authentication in Emacs. - -@detailmenu - --- The Detailed Node Listing --- - -Starting Gnus - -* Finding the News:: Choosing a method for getting news. -* The First Time:: What does Gnus do the first time you start it? -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* Fetching a Group:: Starting Gnus just to read a group. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. - -New Groups - -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. - -Group Buffer - -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Misc Group Stuff:: Other stuff that you can to do. - -Group Buffer Format - -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. - -Group Topics - -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. - -Misc Group Stuff - -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. - -Summary Buffer - -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. - -Summary Buffer Format - -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. - -Choosing Articles - -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. - -Reply, Followup and Post - -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: - -Marking Articles - -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. - -Threading - -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. - -Customizing Threading - -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! - -Decoding Articles - -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? - -Decoding Variables - -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. - -Article Treatment - -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff---X-Face, Picons, Smileys -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. - -Alternative Approaches - -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. - -Various Summary Stuff - -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. - -Article Buffer - -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. - -Composing Messages - -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. - -Select Methods - -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* IMAP:: Using Gnus as a @acronym{IMAP} client. -* Other Sources:: Reading directories, files, SOUP packets. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. - -Server Buffer - -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. - -Getting News - -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. - -@acronym{NNTP} - -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. -* NNTP marks:: Storing marks for @acronym{NNTP} servers. - -Getting Mail - -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. - -Mail Sources - -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. - -Choosing a Mail Back End - -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. - -Browsing the Web - -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* Slashdot:: Reading the Slashdot comments. -* Ultimate:: The Ultimate Bulletin Board systems. -* Web Archive:: Reading mailing list archived on web. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. - -@acronym{IMAP} - -* Splitting in IMAP:: Splitting mail with nnimap. -* Expiring in IMAP:: Expiring mail with nnimap. -* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. -* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. -* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. -* Debugging IMAP:: What to do when things don't work. - -Other Sources - -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* SOUP:: Reading @sc{soup} packets ``offline''. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. - -Document Groups - -* Document Server Internals:: How to add your own document types. - -SOUP - -* SOUP Commands:: Commands for creating and sending @sc{soup} packets -* SOUP Groups:: A back end for reading @sc{soup} packets. -* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. - -Combined Groups - -* Virtual Groups:: Combining articles from many groups. -* Kibozed Groups:: Looking through parts of the newsfeed for articles. - -Email Based Diary - -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. - -The NNDiary Back End - -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. - -The Gnus Diary Library - -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. - -Gnus Unplugged - -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. - -Agent Categories - -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. - -Agent Commands - -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. - -Scoring - -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. - -Advanced Scoring - -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. - -Various - -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Compilation:: How to speed Gnus up. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Buttons:: Get tendinitis in ten easy steps! -* Daemons:: Gnus can do things behind your back. -* NoCeM:: How to avoid spam and other fatty foods. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. - -Formatting Variables - -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. - -Image Enhancements - -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were - meant to be shown. -* Picons:: How to display pictures of what you're reading. -* XVarious:: Other XEmacsy Gnusey variables. - -Thwarting Email Spam - -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. - -Spam Package - -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: - -Spam Statistics Package - -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: - -Appendices - -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ - -History - -* Gnus Versions:: What Gnus versions have been released. -* Other Gnus Versions:: Other Gnus versions that also have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. - -New Features - -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. - -Customization - -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. - -Gnus Reference Guide - -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. - -Back End Interface - -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. - -Various File Formats - -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. - -Emacs for Heathens - -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. - -@end detailmenu -@end menu - -@node Starting Up -@chapter Starting Gnus -@cindex starting up - -If you haven't used Emacs much before using Gnus, read @ref{Emacs for -Heathens} first. - -@kindex M-x gnus -@findex gnus -If your system administrator has set things up properly, starting Gnus -and reading news is extremely easy---you just type @kbd{M-x gnus} in -your Emacs. If not, you should customize the variable -@code{gnus-select-method} as described in @ref{Finding the News}. For a -minimal setup for posting should also customize the variables -@code{user-full-name} and @code{user-mail-address}. - -@findex gnus-other-frame -@kindex M-x gnus-other-frame -If you want to start Gnus in a different frame, you can use the command -@kbd{M-x gnus-other-frame} instead. - -If things do not go smoothly at startup, you have to twiddle some -variables in your @file{~/.gnus.el} file. This file is similar to -@file{~/.emacs}, but is read when Gnus starts. - -If you puzzle at any terms used in this manual, please refer to the -terminology section (@pxref{Terminology}). - -@menu -* Finding the News:: Choosing a method for getting news. -* The First Time:: What does Gnus do the first time you start it? -* The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. -* New Groups:: What is Gnus supposed to do with new groups? -* Changing Servers:: You may want to move from one server to another. -* Startup Files:: Those pesky startup files---@file{.newsrc}. -* Auto Save:: Recovering from a crash. -* The Active File:: Reading the active file over a slow line Takes Time. -* Startup Variables:: Other variables you might change. -@end menu - - -@node Finding the News -@section Finding the News -@cindex finding news - -@vindex gnus-select-method -@c @head -The @code{gnus-select-method} variable says where Gnus should look for -news. This variable should be a list where the first element says -@dfn{how} and the second element says @dfn{where}. This method is your -native method. All groups not fetched with this method are -foreign groups. - -For instance, if the @samp{news.somewhere.edu} @acronym{NNTP} server is where -you want to get your daily dosage of news from, you'd say: - -@lisp -(setq gnus-select-method '(nntp "news.somewhere.edu")) -@end lisp - -If you want to read directly from the local spool, say: - -@lisp -(setq gnus-select-method '(nnspool "")) -@end lisp - -If you can use a local spool, you probably should, as it will almost -certainly be much faster. But do not use the local spool if your -server is running Leafnode (which is a simple, standalone private news -server); in this case, use @code{(nntp "localhost")}. - -@vindex gnus-nntpserver-file -@cindex NNTPSERVER -@cindex @acronym{NNTP} server -If this variable is not set, Gnus will take a look at the -@env{NNTPSERVER} environment variable. If that variable isn't set, -Gnus will see whether @code{gnus-nntpserver-file} -(@file{/etc/nntpserver} by default) has any opinions on the matter. -If that fails as well, Gnus will try to use the machine running Emacs -as an @acronym{NNTP} server. That's a long shot, though. - -@vindex gnus-nntp-server -If @code{gnus-nntp-server} is set, this variable will override -@code{gnus-select-method}. You should therefore set -@code{gnus-nntp-server} to @code{nil}, which is what it is by default. - -@vindex gnus-secondary-servers -@vindex gnus-nntp-server -You can also make Gnus prompt you interactively for the name of an -@acronym{NNTP} server. If you give a non-numerical prefix to @code{gnus} -(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers -in the @code{gnus-secondary-servers} list (if any). You can also just -type in the name of any server you feel like visiting. (Note that this -will set @code{gnus-nntp-server}, which means that if you then @kbd{M-x -gnus} later in the same Emacs session, Gnus will contact the same -server.) - -@findex gnus-group-browse-foreign-server -@kindex B (Group) -However, if you use one @acronym{NNTP} server regularly and are just -interested in a couple of groups from a different server, you would be -better served by using the @kbd{B} command in the group buffer. It will -let you have a look at what groups are available, and you can subscribe -to any of the groups you want to. This also makes @file{.newsrc} -maintenance much tidier. @xref{Foreign Groups}. - -@vindex gnus-secondary-select-methods -@c @head -A slightly different approach to foreign groups is to set the -@code{gnus-secondary-select-methods} variable. The select methods -listed in this variable are in many ways just as native as the -@code{gnus-select-method} server. They will also be queried for active -files during startup (if that's required), and new newsgroups that -appear on these servers will be subscribed (or not) just as native -groups are. - -For instance, if you use the @code{nnmbox} back end to read your mail, -you would typically set this variable to - -@lisp -(setq gnus-secondary-select-methods '((nnmbox ""))) -@end lisp - -Note: the @acronym{NNTP} back end stores marks in marks files -(@pxref{NNTP marks}). This feature makes it easy to share marks between -several Gnus installations, but may slow down things a bit when fetching -new articles. @xref{NNTP marks}, for more information. - - -@node The First Time -@section The First Time -@cindex first time usage - -If no startup files exist (@pxref{Startup Files}), Gnus will try to -determine what groups should be subscribed by default. - -@vindex gnus-default-subscribed-newsgroups -If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus -will subscribe you to just those groups in that list, leaving the rest -killed. Your system administrator should have set this variable to -something useful. - -Since she hasn't, Gnus will just subscribe you to a few arbitrarily -picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined -here as @dfn{whatever Lars thinks you should read}.) - -You'll also be subscribed to the Gnus documentation group, which should -help you with most common problems. - -If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just -use the normal functions for handling new groups, and not do anything -special. - - -@node The Server is Down -@section The Server is Down -@cindex server errors - -If the default server is down, Gnus will understandably have some -problems starting. However, if you have some mail groups in addition to -the news groups, you may want to start Gnus anyway. - -Gnus, being the trusting sort of program, will ask whether to proceed -without a native select method if that server can't be contacted. This -will happen whether the server doesn't actually exist (i.e., you have -given the wrong address) or the server has just momentarily taken ill -for some reason or other. If you decide to continue and have no foreign -groups, you'll find it difficult to actually do anything in the group -buffer. But, hey, that's your problem. Blllrph! - -@findex gnus-no-server -@kindex M-x gnus-no-server -@c @head -If you know that the server is definitely down, or you just want to read -your mail without bothering with the server at all, you can use the -@code{gnus-no-server} command to start Gnus. That might come in handy -if you're in a hurry as well. This command will not attempt to contact -your primary server---instead, it will just activate all groups on level -1 and 2. (You should preferably keep no native groups on those two -levels.) Also @pxref{Group Levels}. - - -@node Slave Gnusae -@section Slave Gnusae -@cindex slave - -You might want to run more than one Emacs with more than one Gnus at the -same time. If you are using different @file{.newsrc} files (e.g., if you -are using the two different Gnusae to read from two different servers), -that is no problem whatsoever. You just do it. - -The problem appears when you want to run two Gnusae that use the same -@file{.newsrc} file. - -To work around that problem some, we here at the Think-Tank at the Gnus -Towers have come up with a new concept: @dfn{Masters} and -@dfn{slaves}. (We have applied for a patent on this concept, and have -taken out a copyright on those words. If you wish to use those words in -conjunction with each other, you have to send $1 per usage instance to -me. Usage of the patent (@dfn{Master/Slave Relationships In Computer -Applications}) will be much more expensive, of course.) - -@findex gnus-slave -Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or -however you do it). Each subsequent slave Gnusae should be started with -@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} -files, but instead save @dfn{slave files} that contain information only -on what groups have been read in the slave session. When a master Gnus -starts, it will read (and delete) these slave files, incorporating all -information from them. (The slave files will be read in the sequence -they were created, so the latest changes will have precedence.) - -Information from the slave files has, of course, precedence over the -information in the normal (i.e., master) @file{.newsrc} file. - -If the @file{.newsrc*} files have not been saved in the master when the -slave starts, you may be prompted as to whether to read an auto-save -file. If you answer ``yes'', the unsaved changes to the master will be -incorporated into the slave. If you answer ``no'', the slave may see some -messages as unread that have been read in the master. - - - -@node New Groups -@section New Groups -@cindex new groups -@cindex subscription - -@vindex gnus-check-new-newsgroups -If you are satisfied that you really never want to see any new groups, -you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will -also save you some time at startup. Even if this variable is -@code{nil}, you can always subscribe to the new groups just by pressing -@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable -is @code{ask-server} by default. If you set this variable to -@code{always}, then Gnus will query the back ends for new groups even -when you do the @kbd{g} command (@pxref{Scanning New Messages}). - -@menu -* Checking New Groups:: Determining what groups are new. -* Subscription Methods:: What Gnus should do with new groups. -* Filtering New Groups:: Making Gnus ignore certain new groups. -@end menu - - -@node Checking New Groups -@subsection Checking New Groups - -Gnus normally determines whether a group is new or not by comparing the -list of groups from the active file(s) with the lists of subscribed and -dead groups. This isn't a particularly fast method. If -@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the -server for new groups since the last time. This is both faster and -cheaper. This also means that you can get rid of the list of killed -groups altogether, so you may set @code{gnus-save-killed-list} to -@code{nil}, which will save time both at startup, at exit, and all over. -Saves disk space, too. Why isn't this the default, then? -Unfortunately, not all servers support this command. - -I bet I know what you're thinking now: How do I find out whether my -server supports @code{ask-server}? No? Good, because I don't have a -fail-safe answer. I would suggest just setting this variable to -@code{ask-server} and see whether any new groups appear within the next -few days. If any do, then it works. If none do, then it doesn't -work. I could write a function to make Gnus guess whether the server -supports @code{ask-server}, but it would just be a guess. So I won't. -You could @code{telnet} to the server and say @code{HELP} and see -whether it lists @samp{NEWGROUPS} among the commands it understands. If -it does, then it might work. (But there are servers that lists -@samp{NEWGROUPS} without supporting the function properly.) - -This variable can also be a list of select methods. If so, Gnus will -issue an @code{ask-server} command to each of the select methods, and -subscribe them (or not) using the normal methods. This might be handy -if you are monitoring a few servers for new groups. A side effect is -that startup will take much longer, so you can meditate while waiting. -Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss. - - -@node Subscription Methods -@subsection Subscription Methods - -@vindex gnus-subscribe-newsgroup-method -What Gnus does when it encounters a new group is determined by the -@code{gnus-subscribe-newsgroup-method} variable. - -This variable should contain a function. This function will be called -with the name of the new group as the only parameter. - -Some handy pre-fab functions are: - -@table @code - -@item gnus-subscribe-zombies -@vindex gnus-subscribe-zombies -Make all new groups zombies. This is the default. You can browse the -zombies later (with @kbd{A z}) and either kill them all off properly -(with @kbd{S z}), or subscribe to them (with @kbd{u}). - -@item gnus-subscribe-randomly -@vindex gnus-subscribe-randomly -Subscribe all new groups in arbitrary order. This really means that all -new groups will be added at ``the top'' of the group buffer. - -@item gnus-subscribe-alphabetically -@vindex gnus-subscribe-alphabetically -Subscribe all new groups in alphabetical order. - -@item gnus-subscribe-hierarchically -@vindex gnus-subscribe-hierarchically -Subscribe all new groups hierarchically. The difference between this -function and @code{gnus-subscribe-alphabetically} is slight. -@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly -alphabetical fashion, while this function will enter groups into its -hierarchy. So if you want to have the @samp{rec} hierarchy before the -@samp{comp} hierarchy, this function will not mess that configuration -up. Or something like that. - -@item gnus-subscribe-interactively -@vindex gnus-subscribe-interactively -Subscribe new groups interactively. This means that Gnus will ask -you about @strong{all} new groups. The groups you choose to subscribe -to will be subscribed hierarchically. - -@item gnus-subscribe-killed -@vindex gnus-subscribe-killed -Kill all new groups. - -@item gnus-subscribe-topics -@vindex gnus-subscribe-topics -Put the groups into the topic that has a matching @code{subscribe} topic -parameter (@pxref{Topic Parameters}). For instance, a @code{subscribe} -topic parameter that looks like - -@example -"nnslashdot" -@end example - -will mean that all groups that match that regex will be subscribed under -that topic. - -If no topics match the groups, the groups will be subscribed in the -top-level topic. - -@end table - -@vindex gnus-subscribe-hierarchical-interactive -A closely related variable is -@code{gnus-subscribe-hierarchical-interactive}. (That's quite a -mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a -hierarchical fashion whether to subscribe to new groups or not. Gnus -will ask you for each sub-hierarchy whether you want to descend the -hierarchy or not. - -One common mistake is to set the variable a few paragraphs above -(@code{gnus-subscribe-newsgroup-method}) to -@code{gnus-subscribe-hierarchical-interactive}. This is an error. This -will not work. This is ga-ga. So don't do it. - - -@node Filtering New Groups -@subsection Filtering New Groups - -A nice and portable way to control which new newsgroups should be -subscribed (or ignored) is to put an @dfn{options} line at the start of -the @file{.newsrc} file. Here's an example: - -@example -options -n !alt.all !rec.all sci.all -@end example - -@vindex gnus-subscribe-options-newsgroup-method -This line obviously belongs to a serious-minded intellectual scientific -person (or she may just be plain old boring), because it says that all -groups that have names beginning with @samp{alt} and @samp{rec} should -be ignored, and all groups with names beginning with @samp{sci} should -be subscribed. Gnus will not use the normal subscription method for -subscribing these groups. -@code{gnus-subscribe-options-newsgroup-method} is used instead. This -variable defaults to @code{gnus-subscribe-alphabetically}. - -@vindex gnus-options-not-subscribe -@vindex gnus-options-subscribe -If you don't want to mess with your @file{.newsrc} file, you can just -set the two variables @code{gnus-options-subscribe} and -@code{gnus-options-not-subscribe}. These two variables do exactly the -same as the @file{.newsrc} @samp{options -n} trick. Both are regexps, -and if the new group matches the former, it will be unconditionally -subscribed, and if it matches the latter, it will be ignored. - -@vindex gnus-auto-subscribed-groups -Yet another variable that meddles here is -@code{gnus-auto-subscribed-groups}. It works exactly like -@code{gnus-options-subscribe}, and is therefore really superfluous, -but I thought it would be nice to have two of these. This variable is -more meant for setting some ground rules, while the other variable is -used more for user fiddling. By default this variable makes all new -groups that come from mail back ends (@code{nnml}, @code{nnbabyl}, -@code{nnfolder}, @code{nnmbox}, @code{nnmh}, and @code{nnmaildir}) -subscribed. If you don't like that, just set this variable to -@code{nil}. - -New groups that match this regexp are subscribed using -@code{gnus-subscribe-options-newsgroup-method}. - - -@node Changing Servers -@section Changing Servers -@cindex changing servers - -Sometimes it is necessary to move from one @acronym{NNTP} server to another. -This happens very rarely, but perhaps you change jobs, or one server is -very flaky and you want to use another. - -Changing the server is pretty easy, right? You just change -@code{gnus-select-method} to point to the new server? - -@emph{Wrong!} - -Article numbers are not (in any way) kept synchronized between different -@acronym{NNTP} servers, and the only way Gnus keeps track of what articles -you have read is by keeping track of article numbers. So when you -change @code{gnus-select-method}, your @file{.newsrc} file becomes -worthless. - -Gnus provides a few functions to attempt to translate a @file{.newsrc} -file from one server to another. They all have one thing in -common---they take a looong time to run. You don't want to use these -functions more than absolutely necessary. - -@kindex M-x gnus-change-server -@findex gnus-change-server -If you have access to both servers, Gnus can request the headers for all -the articles you have read and compare @code{Message-ID}s and map the -article numbers of the read articles and article marks. The @kbd{M-x -gnus-change-server} command will do this for all your native groups. It -will prompt for the method you want to move to. - -@kindex M-x gnus-group-move-group-to-server -@findex gnus-group-move-group-to-server -You can also move individual groups with the @kbd{M-x -gnus-group-move-group-to-server} command. This is useful if you want to -move a (foreign) group from one server to another. - -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -If you don't have access to both the old and new server, all your marks -and read ranges have become worthless. You can use the @kbd{M-x -gnus-group-clear-data-on-native-groups} command to clear out all data -that you have on your native groups. Use with caution. - -@kindex M-x gnus-group-clear-data -@findex gnus-group-clear-data -Clear the data from the current group only---nix out marks and the -list of read articles (@code{gnus-group-clear-data}). - -After changing servers, you @strong{must} move the cache hierarchy away, -since the cached articles will have wrong article numbers, which will -affect which articles Gnus thinks are read. -@code{gnus-group-clear-data-on-native-groups} will ask you if you want -to have it done automatically; for @code{gnus-group-clear-data}, you -can use @kbd{M-x gnus-cache-move-cache} (but beware, it will move the -cache for all groups). - - -@node Startup Files -@section Startup Files -@cindex startup files -@cindex .newsrc -@cindex .newsrc.el -@cindex .newsrc.eld - -Most common Unix news readers use a shared startup file called -@file{.newsrc}. This file contains all the information about what -groups are subscribed, and which articles in these groups have been -read. - -Things got a bit more complicated with @sc{gnus}. In addition to -keeping the @file{.newsrc} file updated, it also used a file called -@file{.newsrc.el} for storing all the information that didn't fit into -the @file{.newsrc} file. (Actually, it also duplicated everything in -the @file{.newsrc} file.) @sc{gnus} would read whichever one of these -files was the most recently saved, which enabled people to swap between -@sc{gnus} and other newsreaders. - -That was kinda silly, so Gnus went one better: In addition to the -@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called -@file{.newsrc.eld}. It will read whichever of these files that are most -recent, but it will never write a @file{.newsrc.el} file. You should -never delete the @file{.newsrc.eld} file---it contains much information -not stored in the @file{.newsrc} file. - -@vindex gnus-save-newsrc-file -@vindex gnus-read-newsrc-file -You can turn off writing the @file{.newsrc} file by setting -@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete -the file and save some space, as well as exiting from Gnus faster. -However, this will make it impossible to use other newsreaders than -Gnus. But hey, who would want to, right? Similarly, setting -@code{gnus-read-newsrc-file} to @code{nil} makes Gnus ignore the -@file{.newsrc} file and any @file{.newsrc-SERVER} files, which can be -convenient if you use a different news reader occasionally, and you -want to read a different subset of the available groups with that -news reader. - -@vindex gnus-save-killed-list -If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus -will not save the list of killed groups to the startup file. This will -save both time (when starting and quitting) and space (on disk). It -will also mean that Gnus has no record of what groups are new or old, -so the automatic new groups subscription methods become meaningless. -You should always set @code{gnus-check-new-newsgroups} to @code{nil} or -@code{ask-server} if you set this variable to @code{nil} (@pxref{New -Groups}). This variable can also be a regular expression. If that's -the case, remove all groups that do not match this regexp before -saving. This can be useful in certain obscure situations that involve -several servers where not all servers support @code{ask-server}. - -@vindex gnus-startup-file -@vindex gnus-backup-startup-file -@vindex version-control -The @code{gnus-startup-file} variable says where the startup files are. -The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup -file being whatever that one is, with a @samp{.eld} appended. -If you want version control for this file, set -@code{gnus-backup-startup-file}. It respects the same values as the -@code{version-control} variable. - -@vindex gnus-save-newsrc-hook -@vindex gnus-save-quick-newsrc-hook -@vindex gnus-save-standard-newsrc-hook -@code{gnus-save-newsrc-hook} is called before saving any of the newsrc -files, while @code{gnus-save-quick-newsrc-hook} is called just before -saving the @file{.newsrc.eld} file, and -@code{gnus-save-standard-newsrc-hook} is called just before saving the -@file{.newsrc} file. The latter two are commonly used to turn version -control on or off. Version control is on by default when saving the -startup files. If you want to turn backup creation off, say something like: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup) -(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup) -@end lisp - -@vindex gnus-init-file -@vindex gnus-site-init-file -When Gnus starts, it will read the @code{gnus-site-init-file} -(@file{.../site-lisp/gnus-init} by default) and @code{gnus-init-file} -(@file{~/.gnus} by default) files. These are normal Emacs Lisp files -and can be used to avoid cluttering your @file{~/.emacs} and -@file{site-init} files with Gnus stuff. Gnus will also check for files -with the same names as these, but with @file{.elc} and @file{.el} -suffixes. In other words, if you have set @code{gnus-init-file} to -@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el}, -and finally @file{~/.gnus} (in this order). If Emacs was invoked with -the @option{-q} or @option{--no-init-file} options (@pxref{Initial -Options, ,Initial Options, emacs, The Emacs Manual}), Gnus doesn't read -@code{gnus-init-file}. - - -@node Auto Save -@section Auto Save -@cindex dribble file -@cindex auto-save - -Whenever you do something that changes the Gnus data (reading articles, -catching up, killing/subscribing groups), the change is added to a -special @dfn{dribble buffer}. This buffer is auto-saved the normal -Emacs way. If your Emacs should crash before you have saved the -@file{.newsrc} files, all changes you have made can be recovered from -this file. - -If Gnus detects this file at startup, it will ask the user whether to -read it. The auto save file is deleted whenever the real startup file is -saved. - -@vindex gnus-use-dribble-file -If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and -maintain a dribble buffer. The default is @code{t}. - -@vindex gnus-dribble-directory -Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If -this variable is @code{nil}, which it is by default, Gnus will dribble -into the directory where the @file{.newsrc} file is located. (This is -normally the user's home directory.) The dribble file will get the same -file permissions as the @file{.newsrc} file. - -@vindex gnus-always-read-dribble-file -If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will -read the dribble file on startup without querying the user. - - -@node The Active File -@section The Active File -@cindex active file -@cindex ignored groups - -When Gnus starts, or indeed whenever it tries to determine whether new -articles have arrived, it reads the active file. This is a very large -file that lists all the active groups and articles on the server. - -@vindex gnus-ignored-newsgroups -Before examining the active file, Gnus deletes all lines that match the -regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject -any groups with bogus names, but you can use this variable to make Gnus -ignore hierarchies you aren't ever interested in. However, this is not -recommended. In fact, it's highly discouraged. Instead, @pxref{New -Groups} for an overview of other variables that can be used instead. - -@c This variable is -@c @code{nil} by default, and will slow down active file handling somewhat -@c if you set it to anything else. - -@vindex gnus-read-active-file -@c @head -The active file can be rather Huge, so if you have a slow network, you -can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from -reading the active file. This variable is @code{some} by default. - -Gnus will try to make do by getting information just on the groups that -you actually subscribe to. - -Note that if you subscribe to lots and lots of groups, setting this -variable to @code{nil} will probably make Gnus slower, not faster. At -present, having this variable @code{nil} will slow Gnus down -considerably, unless you read news over a 2400 baud modem. - -This variable can also have the value @code{some}. Gnus will then -attempt to read active info only on the subscribed groups. On some -servers this is quite fast (on sparkling, brand new INN servers that -support the @code{LIST ACTIVE group} command), on others this isn't fast -at all. In any case, @code{some} should be faster than @code{nil}, and -is certainly faster than @code{t} over slow lines. - -Some news servers (old versions of Leafnode and old versions of INN, for -instance) do not support the @code{LIST ACTIVE group}. For these -servers, @code{nil} is probably the most efficient value for this -variable. - -If this variable is @code{nil}, Gnus will ask for group info in total -lock-step, which isn't very fast. If it is @code{some} and you use an -@acronym{NNTP} server, Gnus will pump out commands as fast as it can, and -read all the replies in one swoop. This will normally result in better -performance, but if the server does not support the aforementioned -@code{LIST ACTIVE group} command, this isn't very nice to the server. - -If you think that starting up Gnus takes too long, try all the three -different values for this variable and see what works best for you. - -In any case, if you use @code{some} or @code{nil}, you should definitely -kill all groups that you aren't interested in to speed things up. - -Note that this variable also affects active file retrieval from -secondary select methods. - - -@node Startup Variables -@section Startup Variables - -@table @code - -@item gnus-load-hook -@vindex gnus-load-hook -A hook run while Gnus is being loaded. Note that this hook will -normally be run just once in each Emacs session, no matter how many -times you start Gnus. - -@item gnus-before-startup-hook -@vindex gnus-before-startup-hook -A hook called as the first thing when Gnus is started. - -@item gnus-startup-hook -@vindex gnus-startup-hook -A hook run as the very last thing after starting up Gnus - -@item gnus-started-hook -@vindex gnus-started-hook -A hook that is run as the very last thing after starting up Gnus -successfully. - -@item gnus-setup-news-hook -@vindex gnus-setup-news-hook -A hook that is run after reading the @file{.newsrc} file(s), but before -generating the group buffer. - -@item gnus-check-bogus-newsgroups -@vindex gnus-check-bogus-newsgroups -If non-@code{nil}, Gnus will check for and delete all bogus groups at -startup. A @dfn{bogus group} is a group that you have in your -@file{.newsrc} file, but doesn't exist on the news server. Checking for -bogus groups can take quite a while, so to save time and resources it's -best to leave this option off, and do the checking for bogus groups once -in a while from the group buffer instead (@pxref{Group Maintenance}). - -@item gnus-inhibit-startup-message -@vindex gnus-inhibit-startup-message -If non-@code{nil}, the startup message won't be displayed. That way, -your boss might not notice as easily that you are reading news instead -of doing your job. Note that this variable is used before -@file{~/.gnus.el} is loaded, so it should be set in @file{.emacs} instead. - -@item gnus-no-groups-message -@vindex gnus-no-groups-message -Message displayed by Gnus when no groups are available. - -@item gnus-play-startup-jingle -@vindex gnus-play-startup-jingle -If non-@code{nil}, play the Gnus jingle at startup. - -@item gnus-startup-jingle -@vindex gnus-startup-jingle -Jingle to be played if the above variable is non-@code{nil}. The -default is @samp{Tuxedomoon.Jingle4.au}. - -@end table - - -@node Group Buffer -@chapter Group Buffer -@cindex group buffer - -@c Alex Schroeder suggests to rearrange this as follows: -@c -@c ok, just save it for reference. I'll go to bed in a minute. -@c 1. Selecting a Group, 2. (new) Finding a Group, 3. Group Levels, -@c 4. Subscription Commands, 5. Group Maneuvering, 6. Group Data, -@c 7. Group Score, 8. Group Buffer Format -@c Group Levels should have more information on levels 5 to 9. I -@c suggest to split the 4th paragraph ("Gnus considers groups...") as follows: -@c First, "Gnus considers groups... (default 9)." -@c New, a table summarizing what levels 1 to 9 mean. -@c Third, "Gnus treats subscribed ... reasons of efficiency" -@c Then expand the next paragraph or add some more to it. -@c This short one sentence explains levels 1 and 2, therefore I understand -@c that I should keep important news at 3 and boring news at 4. -@c Say so! Then go on to explain why I should bother with levels 6 to 9. -@c Maybe keep those that you don't want to read temporarily at 6, -@c those that you never want to read at 8, those that offend your -@c human rights at 9... - - -The @dfn{group buffer} lists all (or parts) of the available groups. It -is the first buffer shown when Gnus starts, and will never be killed as -long as Gnus is active. - -@iftex -@iflatex -\gnusfigure{The Group Buffer}{320}{ -\put(75,50){\epsfig{figure=ps/group,height=9cm}} -\put(120,37){\makebox(0,0)[t]{Buffer name}} -\put(120,38){\vector(1,2){10}} -\put(40,60){\makebox(0,0)[r]{Mode line}} -\put(40,58){\vector(1,0){30}} -\put(200,28){\makebox(0,0)[t]{Native select method}} -\put(200,26){\vector(-1,2){15}} -} -@end iflatex -@end iftex - -@menu -* Group Buffer Format:: Information listed and how you can change it. -* Group Maneuvering:: Commands for moving in the group buffer. -* Selecting a Group:: Actually reading news. -* Subscription Commands:: Unsubscribing, killing, subscribing. -* Group Data:: Changing the info for a group. -* Group Levels:: Levels? What are those, then? -* Group Score:: A mechanism for finding out what groups you like. -* Marking Groups:: You can mark groups for later processing. -* Foreign Groups:: Creating and editing groups. -* Group Parameters:: Each group may have different parameters set. -* Listing Groups:: Gnus can list various subsets of the groups. -* Sorting Groups:: Re-arrange the group order. -* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. -* Browse Foreign Server:: You can browse a server. See what it has to offer. -* Exiting Gnus:: Stop reading news and get some work done. -* Group Topics:: A folding group mode divided into topics. -* Non-ASCII Group Names:: Accessing groups of non-English names. -* Searching:: Mail search engines. -* Misc Group Stuff:: Other stuff that you can to do. -@end menu - - -@node Group Buffer Format -@section Group Buffer Format - -@menu -* Group Line Specification:: Deciding how the group buffer is to look. -* Group Mode Line Specification:: The group buffer mode line. -* Group Highlighting:: Having nice colors in the group buffer. -@end menu - -You can customize the Group Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-group-tool-bar}. This feature is only -available in Emacs. - -The tool bar icons are now (de)activated correctly depending on the -cursor position. Therefore, moving around in the Group Buffer is -slower. You can disable this via the variable -@code{gnus-group-update-tool-bar}. Its default value depends on your -Emacs version. - -@node Group Line Specification -@subsection Group Line Specification -@cindex group buffer format - -The default format of the group buffer is nice and dull, but you can -make it as exciting and ugly as you feel like. - -Here's a couple of example group lines: - -@example - 25: news.announce.newusers - * 0: alt.fan.andrea-dworkin -@end example - -Quite simple, huh? - -You can see that there are 25 unread articles in -@samp{news.announce.newusers}. There are no unread articles, but some -ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little -asterisk at the beginning of the line?). - -@vindex gnus-group-line-format -You can change that format to whatever you want by fiddling with the -@code{gnus-group-line-format} variable. This variable works along the -lines of a @code{format} specification, which is pretty much the same as -a @code{printf} specifications, for those of you who use (feh!) C. -@xref{Formatting Variables}. - -@samp{%M%S%5y:%B%(%g%)\n} is the value that produced those lines above. - -There should always be a colon on the line; the cursor always moves to -the colon after performing an operation. @xref{Positioning -Point}. Nothing else is required---not even the group name. All -displayed text is just window dressing, and is never examined by Gnus. -Gnus stores all real information it needs using text properties. - -(Note that if you make a really strange, wonderful, spreadsheet-like -layout, everybody will believe you are hard at work with the accounting -instead of wasting time reading news.) - -Here's a list of all available format characters: - -@table @samp - -@item M -An asterisk if the group only has marked articles. - -@item S -Whether the group is subscribed. - -@item L -Level of subscribedness. - -@item N -Number of unread articles. - -@item I -Number of dormant articles. - -@item T -Number of ticked articles. - -@item R -Number of read articles. - -@item U -Number of unseen articles. - -@item t -Estimated total number of articles. (This is really @var{max-number} -minus @var{min-number} plus 1.) - -Gnus uses this estimation because the @acronym{NNTP} protocol provides -efficient access to @var{max-number} and @var{min-number} but getting -the true unread message count is not possible efficiently. For -hysterical raisins, even the mail back ends, where the true number of -unread messages might be available efficiently, use the same limited -interface. To remove this restriction from Gnus means that the back -end interface has to be changed, which is not an easy job. - -The nnml backend (@pxref{Mail Spool}) has a feature called ``group -compaction'' which circumvents this deficiency: the idea is to -renumber all articles from 1, removing all gaps between numbers, hence -getting a correct total count. Other backends may support this in the -future. In order to keep your total article count relatively up to -date, you might want to compact your groups (or even directly your -server) from time to time. @xref{Misc Group Stuff}, @xref{Server Commands}. - -@item y -Number of unread, unticked, non-dormant articles. - -@item i -Number of ticked and dormant articles. - -@item g -Full group name. - -@item G -Group name. - -@item C -Group comment (@pxref{Group Parameters}) or group name if there is no -comment element in the group parameters. - -@item D -Newsgroup description. You need to read the group descriptions -before these will appear, and to do that, you either have to set -@code{gnus-read-active-file} or use the group buffer @kbd{M-d} -command. - -@item o -@samp{m} if moderated. - -@item O -@samp{(m)} if moderated. - -@item s -Select method. - -@item B -If the summary buffer for the group is open or not. - -@item n -Select from where. - -@item z -A string that looks like @samp{<%s:%n>} if a foreign select method is -used. - -@item P -Indentation based on the level of the topic (@pxref{Group Topics}). - -@item c -@vindex gnus-group-uncollapsed-levels -Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} -variable says how many levels to leave at the end of the group name. -The default is 1---this will mean that group names like -@samp{gnu.emacs.gnus} will be shortened to @samp{g.e.gnus}. - -@item m -@vindex gnus-new-mail-mark -@cindex % -@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to -the group lately. - -@item p -@samp{#} (@code{gnus-process-mark}) if the group is process marked. - -@item d -A string that says when you last read the group (@pxref{Group -Timestamp}). - -@item F -The disk space used by the articles fetched by both the cache and -agent. The value is automatically scaled to bytes(B), kilobytes(K), -megabytes(M), or gigabytes(G) to minimize the column width. A format -of %7F is sufficient for a fixed-width column. - -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter -following @samp{%u}. The function will be passed a single dummy -parameter as argument. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. -@end table - -@cindex * -All the ``number-of'' specs will be filled with an asterisk (@samp{*}) -if no info is available---for instance, if it is a non-activated foreign -group, or a bogus native group. - - -@node Group Mode Line Specification -@subsection Group Mode Line Specification -@cindex group mode line - -@vindex gnus-group-mode-line-format -The mode line can be changed by setting -@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It -doesn't understand that many format specifiers: - -@table @samp -@item S -The native news server. -@item M -The native select method. -@end table - - -@node Group Highlighting -@subsection Group Highlighting -@cindex highlighting -@cindex group highlighting - -@vindex gnus-group-highlight -Highlighting in the group buffer is controlled by the -@code{gnus-group-highlight} variable. This is an alist with elements -that look like @code{(@var{form} . @var{face})}. If @var{form} evaluates to -something non-@code{nil}, the @var{face} will be used on the line. - -Here's an example value for this variable that might look nice if the -background is dark: - -@lisp -(cond (window-system - (setq custom-background-mode 'light) - (defface my-group-face-1 - '((t (:foreground "Red" :bold t))) "First group face") - (defface my-group-face-2 - '((t (:foreground "DarkSeaGreen4" :bold t))) - "Second group face") - (defface my-group-face-3 - '((t (:foreground "Green4" :bold t))) "Third group face") - (defface my-group-face-4 - '((t (:foreground "SteelBlue" :bold t))) "Fourth group face") - (defface my-group-face-5 - '((t (:foreground "Blue" :bold t))) "Fifth group face"))) - -(setq gnus-group-highlight - '(((> unread 200) . my-group-face-1) - ((and (< level 3) (zerop unread)) . my-group-face-2) - ((< level 3) . my-group-face-3) - ((zerop unread) . my-group-face-4) - (t . my-group-face-5))) -@end lisp - -Also @pxref{Faces and Fonts}. - -Variables that are dynamically bound when the forms are evaluated -include: - -@table @code -@item group -The group name. -@item unread -The number of unread articles in the group. -@item method -The select method. -@item mailp -Whether the group is a mail group. -@item level -The level of the group. -@item score -The score of the group. -@item ticked -The number of ticked articles in the group. -@item total -The total number of articles in the group. Or rather, -@var{max-number} minus @var{min-number} plus one. -@item topic -When using the topic minor mode, this variable is bound to the current -topic being inserted. -@end table - -When the forms are @code{eval}ed, point is at the beginning of the line -of the group in question, so you can use many of the normal Gnus -functions for snarfing info on the group. - -@vindex gnus-group-update-hook -@findex gnus-group-highlight-line -@code{gnus-group-update-hook} is called when a group line is changed. -It will not be called when @code{gnus-visual} is @code{nil}. This hook -calls @code{gnus-group-highlight-line} by default. - - -@node Group Maneuvering -@section Group Maneuvering -@cindex group movement - -All movement commands understand the numeric prefix and will behave as -expected, hopefully. - -@table @kbd - -@item n -@kindex n (Group) -@findex gnus-group-next-unread-group -Go to the next group that has unread articles -(@code{gnus-group-next-unread-group}). - -@item p -@itemx DEL -@kindex DEL (Group) -@kindex p (Group) -@findex gnus-group-prev-unread-group -Go to the previous group that has unread articles -(@code{gnus-group-prev-unread-group}). - -@item N -@kindex N (Group) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item P -@kindex P (Group) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item M-n -@kindex M-n (Group) -@findex gnus-group-next-unread-group-same-level -Go to the next unread group on the same (or lower) level -(@code{gnus-group-next-unread-group-same-level}). - -@item M-p -@kindex M-p (Group) -@findex gnus-group-prev-unread-group-same-level -Go to the previous unread group on the same (or lower) level -(@code{gnus-group-prev-unread-group-same-level}). -@end table - -Three commands for jumping to groups: - -@table @kbd - -@item j -@kindex j (Group) -@findex gnus-group-jump-to-group -Jump to a group (and make it visible if it isn't already) -(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just -like living groups. - -@item , -@kindex , (Group) -@findex gnus-group-best-unread-group -Jump to the unread group with the lowest level -(@code{gnus-group-best-unread-group}). - -@item . -@kindex . (Group) -@findex gnus-group-first-unread-group -Jump to the first group with unread articles -(@code{gnus-group-first-unread-group}). -@end table - -@vindex gnus-group-goto-unread -If @code{gnus-group-goto-unread} is @code{nil}, all the movement -commands will move to the next group, not the next unread group. Even -the commands that say they move to the next unread group. The default -is @code{t}. - -@vindex gnus-summary-next-group-on-exit -If @code{gnus-summary-next-group-on-exit} is @code{t}, when a summary is -exited, the point in the group buffer is moved to the next unread group. -Otherwise, the point is set to the group just exited. The default is -@code{t}. - -@node Selecting a Group -@section Selecting a Group -@cindex group selection - -@table @kbd - -@item SPACE -@kindex SPACE (Group) -@findex gnus-group-read-group -Select the current group, switch to the summary buffer and display the -first unread article (@code{gnus-group-read-group}). If there are no -unread articles in the group, or if you give a non-numerical prefix to -this command, Gnus will offer to fetch all the old articles in this -group from the server. If you give a numerical prefix @var{n}, @var{n} -determines the number of articles Gnus will fetch. If @var{n} is -positive, Gnus fetches the @var{n} newest articles, if @var{n} is -negative, Gnus fetches the @code{abs(@var{n})} oldest articles. - -Thus, @kbd{SPC} enters the group normally, @kbd{C-u SPC} offers old -articles, @kbd{C-u 4 2 SPC} fetches the 42 newest articles, and @kbd{C-u -- 4 2 SPC} fetches the 42 oldest ones. - -When you are in the group (in the Summary buffer), you can type -@kbd{M-g} to fetch new articles, or @kbd{C-u M-g} to also show the old -ones. - -@item RET -@kindex RET (Group) -@findex gnus-group-select-group -Select the current group and switch to the summary buffer -(@code{gnus-group-select-group}). Takes the same arguments as -@code{gnus-group-read-group}---the only difference is that this command -does not display the first unread article automatically upon group -entry. - -@item M-RET -@kindex M-RET (Group) -@findex gnus-group-quick-select-group -This does the same as the command above, but tries to do it with the -minimum amount of fuzz (@code{gnus-group-quick-select-group}). No -scoring/killing will be performed, there will be no highlights and no -expunging. This might be useful if you're in a real hurry and have to -enter some humongous group. If you give a 0 prefix to this command -(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer, -which is useful if you want to toggle threading before generating the -summary buffer (@pxref{Summary Generation Commands}). - -@item M-SPACE -@kindex M-SPACE (Group) -@findex gnus-group-visible-select-group -This is yet one more command that does the same as the @kbd{RET} -command, but this one does it without expunging and hiding dormants -(@code{gnus-group-visible-select-group}). - -@item C-M-RET -@kindex C-M-RET (Group) -@findex gnus-group-select-group-ephemerally -Finally, this command selects the current group ephemerally without -doing any processing of its contents -(@code{gnus-group-select-group-ephemerally}). Even threading has been -turned off. Everything you do in the group after selecting it in this -manner will have no permanent effects. - -@end table - -@vindex gnus-large-newsgroup -The @code{gnus-large-newsgroup} variable says what Gnus should -consider to be a big group. If it is @code{nil}, no groups are -considered big. The default value is 200. If the group has more -(unread and/or ticked) articles than this, Gnus will query the user -before entering the group. The user can then specify how many -articles should be fetched from the server. If the user specifies a -negative number (@var{-n}), the @var{n} oldest articles will be -fetched. If it is positive, the @var{n} articles that have arrived -most recently will be fetched. - -@vindex gnus-large-ephemeral-newsgroup -@code{gnus-large-ephemeral-newsgroup} is the same as -@code{gnus-large-newsgroup}, but is only used for ephemeral -newsgroups. - -@vindex gnus-newsgroup-maximum-articles -In groups in some news servers, there might be a big gap between a few -very old articles that will never be expired and the recent ones. In -such a case, the server will return the data like @code{(1 . 30000000)} -for the @code{LIST ACTIVE group} command, for example. Even if there -are actually only the articles 1-10 and 29999900-30000000, Gnus doesn't -know it at first and prepares for getting 30000000 articles. However, -it will consume hundreds megabytes of memories and might make Emacs get -stuck as the case may be. If you use such news servers, set the -variable @code{gnus-newsgroup-maximum-articles} to a positive number. -The value means that Gnus ignores articles other than this number of the -latest ones in every group. For instance, the value 10000 makes Gnus -get only the articles 29990001-30000000 (if the latest article number is -30000000 in a group). Note that setting this variable to a number might -prevent you from reading very old articles. The default value of the -variable @code{gnus-newsgroup-maximum-articles} is @code{nil}, which -means Gnus never ignores old articles. - -@vindex gnus-select-group-hook -@vindex gnus-auto-select-first -@vindex gnus-auto-select-subject -If @code{gnus-auto-select-first} is non-@code{nil}, select an article -automatically when entering a group with the @kbd{SPACE} command. -Which article this is controlled by the -@code{gnus-auto-select-subject} variable. Valid values for this -variable are: - -@table @code - -@item unread -Place point on the subject line of the first unread article. - -@item first -Place point on the subject line of the first article. - -@item unseen -Place point on the subject line of the first unseen article. - -@item unseen-or-unread -Place point on the subject line of the first unseen article, and if -there is no such article, place point on the subject line of the first -unread article. - -@item best -Place point on the subject line of the highest-scored unread article. - -@end table - -This variable can also be a function. In that case, that function -will be called to place point on a subject line. - -If you want to prevent automatic selection in some group (say, in a -binary group with Huge articles) you can set the -@code{gnus-auto-select-first} variable to @code{nil} in -@code{gnus-select-group-hook}, which is called when a group is -selected. - - -@node Subscription Commands -@section Subscription Commands -@cindex subscription - -@table @kbd - -@item S t -@itemx u -@kindex S t (Group) -@kindex u (Group) -@findex gnus-group-unsubscribe-current-group -@c @icon{gnus-group-unsubscribe} -Toggle subscription to the current group -(@code{gnus-group-unsubscribe-current-group}). - -@item S s -@itemx U -@kindex S s (Group) -@kindex U (Group) -@findex gnus-group-unsubscribe-group -Prompt for a group to subscribe, and then subscribe it. If it was -subscribed already, unsubscribe it instead -(@code{gnus-group-unsubscribe-group}). - -@item S k -@itemx C-k -@kindex S k (Group) -@kindex C-k (Group) -@findex gnus-group-kill-group -@c @icon{gnus-group-kill-group} -Kill the current group (@code{gnus-group-kill-group}). - -@item S y -@itemx C-y -@kindex S y (Group) -@kindex C-y (Group) -@findex gnus-group-yank-group -Yank the last killed group (@code{gnus-group-yank-group}). - -@item C-x C-t -@kindex C-x C-t (Group) -@findex gnus-group-transpose-groups -Transpose two groups (@code{gnus-group-transpose-groups}). This isn't -really a subscription command, but you can use it instead of a -kill-and-yank sequence sometimes. - -@item S w -@itemx C-w -@kindex S w (Group) -@kindex C-w (Group) -@findex gnus-group-kill-region -Kill all groups in the region (@code{gnus-group-kill-region}). - -@item S z -@kindex S z (Group) -@findex gnus-group-kill-all-zombies -Kill all zombie groups (@code{gnus-group-kill-all-zombies}). - -@item S C-k -@kindex S C-k (Group) -@findex gnus-group-kill-level -Kill all groups on a certain level (@code{gnus-group-kill-level}). -These groups can't be yanked back after killing, so this command should -be used with some caution. The only time where this command comes in -really handy is when you have a @file{.newsrc} with lots of unsubscribed -groups that you want to get rid off. @kbd{S C-k} on level 7 will -kill off all unsubscribed groups that do not have message numbers in the -@file{.newsrc} file. - -@end table - -Also @pxref{Group Levels}. - - -@node Group Data -@section Group Data - -@table @kbd - -@item c -@kindex c (Group) -@findex gnus-group-catchup-current -@vindex gnus-group-catchup-group-hook -@c @icon{gnus-group-catchup-current} -Mark all unticked articles in this group as read -(@code{gnus-group-catchup-current}). -@code{gnus-group-catchup-group-hook} is called when catching up a group from -the group buffer. - -@item C -@kindex C (Group) -@findex gnus-group-catchup-current-all -Mark all articles in this group, even the ticked ones, as read -(@code{gnus-group-catchup-current-all}). - -@item M-c -@kindex M-c (Group) -@findex gnus-group-clear-data -Clear the data from the current group---nix out marks and the list of -read articles (@code{gnus-group-clear-data}). - -@item M-x gnus-group-clear-data-on-native-groups -@kindex M-x gnus-group-clear-data-on-native-groups -@findex gnus-group-clear-data-on-native-groups -If you have switched from one @acronym{NNTP} server to another, all your marks -and read ranges have become worthless. You can use this command to -clear out all data that you have on your native groups. Use with -caution. - -@end table - - -@node Group Levels -@section Group Levels -@cindex group level -@cindex level - -All groups have a level of @dfn{subscribedness}. For instance, if a -group is on level 2, it is more subscribed than a group on level 5. You -can ask Gnus to just list groups on a given level or lower -(@pxref{Listing Groups}), or to just check for new articles in groups on -a given level or lower (@pxref{Scanning New Messages}). - -Remember: The higher the level of the group, the less important it is. - -@table @kbd - -@item S l -@kindex S l (Group) -@findex gnus-group-set-current-level -Set the level of the current group. If a numeric prefix is given, the -next @var{n} groups will have their levels set. The user will be -prompted for a level. -@end table - -@vindex gnus-level-killed -@vindex gnus-level-zombie -@vindex gnus-level-unsubscribed -@vindex gnus-level-subscribed -Gnus considers groups from levels 1 to -@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, -@code{gnus-level-subscribed} (exclusive) and -@code{gnus-level-unsubscribed} (inclusive) (default 7) to be -unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) -(default 8) and @code{gnus-level-killed} to be killed (completely dead) -(default 9). Gnus treats subscribed and unsubscribed groups exactly the -same, but zombie and killed groups have no information on what articles -you have read, etc, stored. This distinction between dead and living -groups isn't done because it is nice or clever, it is done purely for -reasons of efficiency. - -It is recommended that you keep all your mail groups (if any) on quite -low levels (e.g. 1 or 2). - -Maybe the following description of the default behavior of Gnus helps to -understand what these levels are all about. By default, Gnus shows you -subscribed nonempty groups, but by hitting @kbd{L} you can have it show -empty subscribed groups and unsubscribed groups, too. Type @kbd{l} to -go back to showing nonempty subscribed groups again. Thus, unsubscribed -groups are hidden, in a way. - -Zombie and killed groups are similar to unsubscribed groups in that they -are hidden by default. But they are different from subscribed and -unsubscribed groups in that Gnus doesn't ask the news server for -information (number of messages, number of unread messages) on zombie -and killed groups. Normally, you use @kbd{C-k} to kill the groups you -aren't interested in. If most groups are killed, Gnus is faster. - -Why does Gnus distinguish between zombie and killed groups? Well, when -a new group arrives on the server, Gnus by default makes it a zombie -group. This means that you are normally not bothered with new groups, -but you can type @kbd{A z} to get a list of all new groups. Subscribe -the ones you like and kill the ones you don't want. (@kbd{A k} shows a -list of killed groups.) - -If you want to play with the level variables, you should show some care. -Set them once, and don't touch them ever again. Better yet, don't touch -them at all unless you know exactly what you're doing. - -@vindex gnus-level-default-unsubscribed -@vindex gnus-level-default-subscribed -Two closely related variables are @code{gnus-level-default-subscribed} -(default 3) and @code{gnus-level-default-unsubscribed} (default 6), -which are the levels that new groups will be put on if they are -(un)subscribed. These two variables should, of course, be inside the -relevant valid ranges. - -@vindex gnus-keep-same-level -If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands -will only move to groups of the same level (or lower). In -particular, going from the last article in one group to the next group -will go to the next group of the same level (or lower). This might be -handy if you want to read the most important groups before you read the -rest. - -If this variable is @code{best}, Gnus will make the next newsgroup the -one with the best level. - -@vindex gnus-group-default-list-level -All groups with a level less than or equal to -@code{gnus-group-default-list-level} will be listed in the group buffer -by default. - -@vindex gnus-group-list-inactive-groups -If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active -groups will be listed along with the unread groups. This variable is -@code{t} by default. If it is @code{nil}, inactive groups won't be -listed. - -@vindex gnus-group-use-permanent-levels -If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you -give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will -use this level as the ``work'' level. - -@vindex gnus-activate-level -Gnus will normally just activate (i. e., query the server about) groups -on level @code{gnus-activate-level} or less. If you don't want to -activate unsubscribed groups, for instance, you might set this variable -to 5. The default is 6. - - -@node Group Score -@section Group Score -@cindex group score -@cindex group rank -@cindex rank - -You would normally keep important groups on high levels, but that scheme -is somewhat restrictive. Don't you wish you could have Gnus sort the -group buffer according to how often you read groups, perhaps? Within -reason? - -This is what @dfn{group score} is for. You can have Gnus assign a score -to each group through the mechanism described below. You can then sort -the group buffer based on this score. Alternatively, you can sort on -score and then level. (Taken together, the level and the score is -called the @dfn{rank} of the group. A group that is on level 4 and has -a score of 1 has a higher rank than a group on level 5 that has a score -of 300. (The level is the most significant part and the score is the -least significant part.)) - -@findex gnus-summary-bubble-group -If you want groups you read often to get higher scores than groups you -read seldom you can add the @code{gnus-summary-bubble-group} function to -the @code{gnus-summary-exit-hook} hook. This will result (after -sorting) in a bubbling sort of action. If you want to see that in -action after each summary exit, you can add -@code{gnus-group-sort-groups-by-rank} or -@code{gnus-group-sort-groups-by-score} to the same hook, but that will -slow things down somewhat. - - -@node Marking Groups -@section Marking Groups -@cindex marking groups - -If you want to perform some command on several groups, and they appear -subsequently in the group buffer, you would normally just give a -numerical prefix to the command. Most group commands will then do your -bidding on those groups. - -However, if the groups are not in sequential order, you can still -perform a command on several groups. You simply mark the groups first -with the process mark and then execute the command. - -@table @kbd - -@item # -@kindex # (Group) -@itemx M m -@kindex M m (Group) -@findex gnus-group-mark-group -Set the mark on the current group (@code{gnus-group-mark-group}). - -@item M-# -@kindex M-# (Group) -@itemx M u -@kindex M u (Group) -@findex gnus-group-unmark-group -Remove the mark from the current group -(@code{gnus-group-unmark-group}). - -@item M U -@kindex M U (Group) -@findex gnus-group-unmark-all-groups -Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). - -@item M w -@kindex M w (Group) -@findex gnus-group-mark-region -Mark all groups between point and mark (@code{gnus-group-mark-region}). - -@item M b -@kindex M b (Group) -@findex gnus-group-mark-buffer -Mark all groups in the buffer (@code{gnus-group-mark-buffer}). - -@item M r -@kindex M r (Group) -@findex gnus-group-mark-regexp -Mark all groups that match some regular expression -(@code{gnus-group-mark-regexp}). -@end table - -Also @pxref{Process/Prefix}. - -@findex gnus-group-universal-argument -If you want to execute some command on all groups that have been marked -with the process mark, you can use the @kbd{M-&} -(@code{gnus-group-universal-argument}) command. It will prompt you for -the command to be executed. - - -@node Foreign Groups -@section Foreign Groups -@cindex foreign groups - -Below are some group mode commands for making and editing general foreign -groups, as well as commands to ease the creation of a few -special-purpose groups. All these commands insert the newly created -groups under point---@code{gnus-subscribe-newsgroup-method} is not -consulted. - -Changes from the group editing commands are stored in -@file{~/.newsrc.eld} (@code{gnus-startup-file}). An alternative is the -variable @code{gnus-parameters}, @xref{Group Parameters}. - -@table @kbd - -@item G m -@kindex G m (Group) -@findex gnus-group-make-group -@cindex making groups -Make a new group (@code{gnus-group-make-group}). Gnus will prompt you -for a name, a method and possibly an @dfn{address}. For an easier way -to subscribe to @acronym{NNTP} groups (@pxref{Browse Foreign Server}). - -@item G M -@kindex G M (Group) -@findex gnus-group-read-ephemeral-group -Make an ephemeral group (@code{gnus-group-read-ephemeral-group}). Gnus -will prompt you for a name, a method and an @dfn{address}. - -@item G r -@kindex G r (Group) -@findex gnus-group-rename-group -@cindex renaming groups -Rename the current group to something else -(@code{gnus-group-rename-group}). This is valid only on some -groups---mail groups mostly. This command might very well be quite slow -on some back ends. - -@item G c -@kindex G c (Group) -@cindex customizing -@findex gnus-group-customize -Customize the group parameters (@code{gnus-group-customize}). - -@item G e -@kindex G e (Group) -@findex gnus-group-edit-group-method -@cindex renaming groups -Enter a buffer where you can edit the select method of the current -group (@code{gnus-group-edit-group-method}). - -@item G p -@kindex G p (Group) -@findex gnus-group-edit-group-parameters -Enter a buffer where you can edit the group parameters -(@code{gnus-group-edit-group-parameters}). - -@item G E -@kindex G E (Group) -@findex gnus-group-edit-group -Enter a buffer where you can edit the group info -(@code{gnus-group-edit-group}). - -@item G d -@kindex G d (Group) -@findex gnus-group-make-directory-group -@cindex nndir -Make a directory group (@pxref{Directory Groups}). You will be prompted -for a directory name (@code{gnus-group-make-directory-group}). - -@item G h -@kindex G h (Group) -@cindex help group -@findex gnus-group-make-help-group -Make the Gnus help group (@code{gnus-group-make-help-group}). - -@item G a -@kindex G a (Group) -@cindex (ding) archive -@cindex archive group -@findex gnus-group-make-archive-group -@vindex gnus-group-archive-directory -@vindex gnus-group-recent-archive-directory -Make a Gnus archive group (@code{gnus-group-make-archive-group}). By -default a group pointing to the most recent articles will be created -(@code{gnus-group-recent-archive-directory}), but given a prefix, a full -group will be created from @code{gnus-group-archive-directory}. - -@item G k -@kindex G k (Group) -@findex gnus-group-make-kiboze-group -@cindex nnkiboze -Make a kiboze group. You will be prompted for a name, for a regexp to -match groups to be ``included'' in the kiboze group, and a series of -strings to match on headers (@code{gnus-group-make-kiboze-group}). -@xref{Kibozed Groups}. - -@item G D -@kindex G D (Group) -@findex gnus-group-enter-directory -@cindex nneething -Read an arbitrary directory as if it were a newsgroup with the -@code{nneething} back end (@code{gnus-group-enter-directory}). -@xref{Anything Groups}. - -@item G f -@kindex G f (Group) -@findex gnus-group-make-doc-group -@cindex ClariNet Briefs -@cindex nndoc -Make a group based on some file or other -(@code{gnus-group-make-doc-group}). If you give a prefix to this -command, you will be prompted for a file name and a file type. -Currently supported types are @code{mbox}, @code{babyl}, -@code{digest}, @code{news}, @code{rnews}, @code{mmdf}, @code{forward}, -@code{rfc934}, @code{rfc822-forward}, @code{mime-parts}, -@code{standard-digest}, @code{slack-digest}, @code{clari-briefs}, -@code{nsmail}, @code{outlook}, @code{oe-dbx}, and @code{mailman}. If -you run this command without a prefix, Gnus will guess at the file -type. @xref{Document Groups}. - -@item G u -@kindex G u (Group) -@vindex gnus-useful-groups -@findex gnus-group-make-useful-group -Create one of the groups mentioned in @code{gnus-useful-groups} -(@code{gnus-group-make-useful-group}). - -@item G w -@kindex G w (Group) -@findex gnus-group-make-web-group -@cindex Google -@cindex nnweb -@cindex gmane -Make an ephemeral group based on a web search -(@code{gnus-group-make-web-group}). If you give a prefix to this -command, make a solid group instead. You will be prompted for the -search engine type and the search string. Valid search engine types -include @code{google}, @code{dejanews}, and @code{gmane}. -@xref{Web Searches}. - -If you use the @code{google} search engine, you can limit the search -to a particular group by using a match string like -@samp{shaving group:alt.sysadmin.recovery}. - -@item G R -@kindex G R (Group) -@findex gnus-group-make-rss-group -Make a group based on an @acronym{RSS} feed -(@code{gnus-group-make-rss-group}). You will be prompted for an URL. -@xref{RSS}. - -@item G DEL -@kindex G DEL (Group) -@findex gnus-group-delete-group -This function will delete the current group -(@code{gnus-group-delete-group}). If given a prefix, this function will -actually delete all the articles in the group, and forcibly remove the -group itself from the face of the Earth. Use a prefix only if you are -absolutely sure of what you are doing. This command can't be used on -read-only groups (like @code{nntp} groups), though. - -@item G V -@kindex G V (Group) -@findex gnus-group-make-empty-virtual -Make a new, fresh, empty @code{nnvirtual} group -(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. - -@item G v -@kindex G v (Group) -@findex gnus-group-add-to-virtual -Add the current group to an @code{nnvirtual} group -(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. -@end table - -@xref{Select Methods}, for more information on the various select -methods. - -@vindex gnus-activate-foreign-newsgroups -If @code{gnus-activate-foreign-newsgroups} is a positive number, -Gnus will check all foreign groups with this level or lower at startup. -This might take quite a while, especially if you subscribe to lots of -groups from different @acronym{NNTP} servers. Also @pxref{Group Levels}; -@code{gnus-activate-level} also affects activation of foreign -newsgroups. - - -The following commands create ephemeral groups. They can be called not -only from the Group buffer, but in any Gnus buffer. - -@table @code -@item gnus-read-ephemeral-gmane-group -@findex gnus-read-ephemeral-gmane-group -@vindex gnus-gmane-group-download-format -Read an ephemeral group on Gmane.org. The articles are downloaded via -HTTP using the URL specified by @code{gnus-gmane-group-download-format}. -Gnus will prompt you for a group name, the start article number and an -the article range. - -@item gnus-read-ephemeral-gmane-group-url -@findex gnus-read-ephemeral-gmane-group-url -This command is similar to @code{gnus-read-ephemeral-gmane-group}, but -the group name and the article number and range are constructed from a -given @acronym{URL}. Supported @acronym{URL} formats include e.g. -@url{http://thread.gmane.org/gmane.foo.bar/12300/focus=12399}, -@url{http://thread.gmane.org/gmane.foo.bar/12345/}, -@url{http://article.gmane.org/gmane.foo.bar/12345/}, -@url{http://permalink.gmane.org/gmane.foo.bar/12345/}, and -@url{http://news.gmane.org/group/gmane.foo.bar/thread=12345}. - -@item gnus-read-ephemeral-emacs-bug-group -@findex gnus-read-ephemeral-emacs-bug-group -Read an Emacs bug report in an ephemeral group. Gnus will prompt for a -bug number. The default is the number at point. The @acronym{URL} is -specified in @code{gnus-bug-group-download-format-alist}. - -@item gnus-read-ephemeral-debian-bug-group -@findex gnus-read-ephemeral-debian-bug-group -Read a Debian bug report in an ephemeral group. Analog to -@code{gnus-read-ephemeral-emacs-bug-group}. -@end table - -Some of these command are also useful for article buttons, @xref{Article -Buttons}. - -Here is an example: -@lisp -(require 'gnus-art) -(add-to-list - 'gnus-button-alist - '("#\\([0-9]+\\)\\>" 1 - (string-match "\\" (or gnus-newsgroup-name "")) - gnus-read-ephemeral-emacs-bug-group 1)) -@end lisp - - -@node Group Parameters -@section Group Parameters -@cindex group parameters - -The group parameters store information local to a particular group. - -Use the @kbd{G p} or the @kbd{G c} command to edit group parameters of a -group. (@kbd{G p} presents you with a Lisp-based interface, @kbd{G c} -presents you with a Customize-like interface. The latter helps avoid -silly Lisp errors.) You might also be interested in reading about topic -parameters (@pxref{Topic Parameters}). -Additionally, you can set group parameters via the -@code{gnus-parameters} variable, see below. - -Here's an example group parameter list: - -@example -((to-address . "ding@@gnus.org") - (auto-expire . t)) -@end example - -We see that each element consists of a ``dotted pair''---the thing before -the dot is the key, while the thing after the dot is the value. All the -parameters have this form @emph{except} local variable specs, which are -not dotted pairs, but proper lists. - -Some parameters have correspondent customizable variables, each of which -is an alist of regexps and values. - -The following group parameters can be used: - -@table @code -@item to-address -@cindex to-address -Address used by when doing followups and new posts. - -@example -(to-address . "some@@where.com") -@end example - -This is primarily useful in mail groups that represent closed mailing -lists---mailing lists where it's expected that everybody that writes to -the mailing list is subscribed to it. Since using this parameter -ensures that the mail only goes to the mailing list itself, it means -that members won't receive two copies of your followups. - -Using @code{to-address} will actually work whether the group is foreign -or not. Let's say there's a group on the server that is called -@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten -the articles from a mail-to-news gateway. Posting directly to this -group is therefore impossible---you have to send mail to the mailing -list address instead. - -See also @code{gnus-parameter-to-address-alist}. - -@item to-list -@cindex to-list -Address used when doing @kbd{a} in that group. - -@example -(to-list . "some@@where.com") -@end example - -It is totally ignored -when doing a followup---except that if it is present in a news group, -you'll get mail group semantics when doing @kbd{f}. - -If you do an @kbd{a} command in a mail group and you have neither a -@code{to-list} group parameter nor a @code{to-address} group parameter, -then a @code{to-list} group parameter will be added automatically upon -sending the message if @code{gnus-add-to-list} is set to @code{t}. -@vindex gnus-add-to-list - -@findex gnus-mailing-list-mode -@cindex mail list groups -If this variable is set, @code{gnus-mailing-list-mode} is turned on when -entering summary buffer. - -See also @code{gnus-parameter-to-list-alist}. - -@anchor{subscribed} -@item subscribed -@cindex subscribed -@cindex Mail-Followup-To -@findex gnus-find-subscribed-addresses -If this parameter is set to @code{t}, Gnus will consider the -to-address and to-list parameters for this group as addresses of -mailing lists you are subscribed to. Giving Gnus this information is -(only) a first step in getting it to generate correct Mail-Followup-To -headers for your posts to these lists. The second step is to put the -following in your @file{.gnus.el} - -@lisp -(setq message-subscribed-address-functions - '(gnus-find-subscribed-addresses)) -@end lisp - -@xref{Mailing Lists, ,Mailing Lists, message, The Message Manual}, for -a complete treatment of available MFT support. - -@item visible -@cindex visible -If the group parameter list has the element @code{(visible . t)}, -that group will always be visible in the Group buffer, regardless -of whether it has any unread articles. - -This parameter cannot be set via @code{gnus-parameters}. See -@code{gnus-permanently-visible-groups} as an alternative. - -@item broken-reply-to -@cindex broken-reply-to -Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} -headers in this group are to be ignored, and for the header to be hidden -if @code{reply-to} is part of @code{gnus-boring-article-headers}. This -can be useful if you're reading a mailing list group where the listserv -has inserted @code{Reply-To} headers that point back to the listserv -itself. That is broken behavior. So there! - -@item to-group -@cindex to-group -Elements like @code{(to-group . "some.group.name")} means that all -posts in that group will be sent to @code{some.group.name}. - -@item newsgroup -@cindex newsgroup -If you have @code{(newsgroup . t)} in the group parameter list, Gnus -will treat all responses as if they were responses to news articles. -This can be useful if you have a mail group that's really a mirror of a -news group. - -@item gcc-self -@cindex gcc-self -If @code{(gcc-self . t)} is present in the group parameter list, newly -composed messages will be @code{Gcc}'d to the current group. If -@code{(gcc-self . none)} is present, no @code{Gcc:} header will be -generated, if @code{(gcc-self . "string")} is present, this string will -be inserted literally as a @code{gcc} header. This parameter takes -precedence over any default @code{Gcc} rules as described later -(@pxref{Archived Messages}). - -@strong{Caveat}: Adding @code{(gcc-self . t)} to the parameter list of -@code{nntp} groups (or the like) isn't valid. An @code{nntp} server -doesn't accept articles. - -@item auto-expire -@cindex auto-expire -@cindex expiring mail -If the group parameter has an element that looks like @code{(auto-expire -. t)}, all articles read will be marked as expirable. For an -alternative approach, @pxref{Expiring Mail}. - -See also @code{gnus-auto-expirable-newsgroups}. - -@item total-expire -@cindex total-expire -@cindex expiring mail -If the group parameter has an element that looks like -@code{(total-expire . t)}, all read articles will be put through the -expiry process, even if they are not marked as expirable. Use with -caution. Unread, ticked and dormant articles are not eligible for -expiry. - -See also @code{gnus-total-expirable-newsgroups}. - -@item expiry-wait -@cindex expiry-wait -@vindex nnmail-expiry-wait-function -If the group parameter has an element that looks like -@code{(expiry-wait . 10)}, this value will override any -@code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function} -(@pxref{Expiring Mail}) when expiring expirable messages. The value -can either be a number of days (not necessarily an integer) or the -symbols @code{never} or @code{immediate}. - -@item expiry-target -@cindex expiry-target -Where expired messages end up. This parameter overrides -@code{nnmail-expiry-target}. - -@item score-file -@cindex score file group parameter -Elements that look like @code{(score-file . "file")} will make -@file{file} into the current score file for the group in question. All -interactive score entries will be put into this file. - -@item adapt-file -@cindex adapt file group parameter -Elements that look like @code{(adapt-file . "file")} will make -@file{file} into the current adaptive file for the group in question. -All adaptive score entries will be put into this file. - -@item admin-address -@cindex admin-address -When unsubscribing from a mailing list you should never send the -unsubscription notice to the mailing list itself. Instead, you'd send -messages to the administrative address. This parameter allows you to -put the admin address somewhere convenient. - -@item display -@cindex display -Elements that look like @code{(display . MODE)} say which articles to -display on entering the group. Valid values are: - -@table @code -@item all -Display all articles, both read and unread. - -@item an integer -Display the last @var{integer} articles in the group. This is the same as -entering the group with @kbd{C-u @var{integer}}. - -@item default -Display the default visible articles, which normally includes unread and -ticked articles. - -@item an array -Display articles that satisfy a predicate. - -Here are some examples: - -@table @code -@item [unread] -Display only unread articles. - -@item [not expire] -Display everything except expirable articles. - -@item [and (not reply) (not expire)] -Display everything except expirable and articles you've already -responded to. -@end table - -The available operators are @code{not}, @code{and} and @code{or}. -Predicates include @code{tick}, @code{unsend}, @code{undownload}, -@code{unread}, @code{dormant}, @code{expire}, @code{reply}, -@code{killed}, @code{bookmark}, @code{score}, @code{save}, -@code{cache}, @code{forward}, @code{unseen} and @code{recent}. - -@end table - -The @code{display} parameter works by limiting the summary buffer to -the subset specified. You can pop the limit by using the @kbd{/ w} -command (@pxref{Limiting}). - -@item comment -@cindex comment -Elements that look like @code{(comment . "This is a comment")} are -arbitrary comments on the group. You can display comments in the -group line (@pxref{Group Line Specification}). - -@item charset -@cindex charset -Elements that look like @code{(charset . iso-8859-1)} will make -@code{iso-8859-1} the default charset; that is, the charset that will be -used for all articles that do not specify a charset. - -See also @code{gnus-group-charset-alist}. - -@item ignored-charsets -@cindex ignored-charset -Elements that look like @code{(ignored-charsets x-unknown iso-8859-1)} -will make @code{iso-8859-1} and @code{x-unknown} ignored; that is, the -default charset will be used for decoding articles. - -See also @code{gnus-group-ignored-charsets-alist}. - -@item posting-style -@cindex posting-style -You can store additional posting style information for this group -here (@pxref{Posting Styles}). The format is that of an entry in the -@code{gnus-posting-styles} alist, except that there's no regexp matching -the group name (of course). Style elements in this group parameter will -take precedence over the ones found in @code{gnus-posting-styles}. - -For instance, if you want a funky name and signature in this group only, -instead of hacking @code{gnus-posting-styles}, you could put something -like this in the group parameters: - -@example -(posting-style - (name "Funky Name") - ("X-My-Header" "Funky Value") - (signature "Funky Signature")) -@end example - -If you're using topics to organize your group buffer -(@pxref{Group Topics}), note that posting styles can also be set in -the topics parameters. Posting styles in topic parameters apply to all -groups in this topic. More precisely, the posting-style settings for a -group result from the hierarchical merging of all posting-style -entries in the parameters of this group and all the topics it belongs -to. - - -@item post-method -@cindex post-method -If it is set, the value is used as the method for posting message -instead of @code{gnus-post-method}. - -@item mail-source -@cindex mail-source -If it is set, and the setting of @code{mail-sources} includes a -@code{group} mail source (@pxref{Mail Sources}), the value is a -mail source for this group. - -@item banner -@cindex banner -An item like @code{(banner . @var{regexp})} causes any part of an article -that matches the regular expression @var{regexp} to be stripped. Instead of -@var{regexp}, you can also use the symbol @code{signature} which strips the -last signature or any of the elements of the alist -@code{gnus-article-banner-alist}. - -@item sieve -@cindex sieve -This parameter contains a Sieve test that should match incoming mail -that should be placed in this group. From this group parameter, a -Sieve @samp{IF} control structure is generated, having the test as the -condition and @samp{fileinto "group.name";} as the body. - -For example, if the @samp{INBOX.list.sieve} group has the @code{(sieve -address "sender" "sieve-admin@@extundo.com")} group parameter, when -translating the group parameter into a Sieve script (@pxref{Sieve -Commands}) the following Sieve code is generated: - -@example -if address "sender" "sieve-admin@@extundo.com" @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -To generate tests for multiple email-addresses use a group parameter -like @code{(sieve address "sender" ("name@@one.org" else@@two.org"))}. -When generating a sieve script (@pxref{Sieve Commands}) Sieve code -like the following is generated: - -@example -if address "sender" ["name@@one.org", "else@@two.org"] @{ - fileinto "INBOX.list.sieve"; -@} -@end example - -See @pxref{Sieve Commands} for commands and variables that might be of -interest in relation to the sieve parameter. - -The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, -Top, sieve, Emacs Sieve}. - -@item (agent parameters) -If the agent has been enabled, you can set any of the its parameters -to control the behavior of the agent in individual groups. See Agent -Parameters in @ref{Category Syntax}. Most users will choose to set -agent parameters in either an agent category or group topic to -minimize the configuration effort. - -@item (@var{variable} @var{form}) -You can use the group parameters to set variables local to the group you -are entering. If you want to turn threading off in @samp{news.answers}, -you could put @code{(gnus-show-threads nil)} in the group parameters of -that group. @code{gnus-show-threads} will be made into a local variable -in the summary buffer you enter, and the form @code{nil} will be -@code{eval}ed there. - -Note that this feature sets the variable locally to the summary buffer -if and only if @var{variable} has been bound as a variable. Otherwise, -only evaluating the form will take place. So, you may want to bind the -variable in advance using @code{defvar} or other if the result of the -form needs to be set to it. - -But some variables are evaluated in the article buffer, or in the -message buffer (of a reply or followup or otherwise newly created -message). As a workaround, it might help to add the variable in -question to @code{gnus-newsgroup-variables}. @xref{Various Summary -Stuff}. So if you want to set @code{message-from-style} via the group -parameters, then you may need the following statement elsewhere in your -@file{~/.gnus.el} file: - -@lisp -(add-to-list 'gnus-newsgroup-variables 'message-from-style) -@end lisp - -@vindex gnus-list-identifiers -A use for this feature is to remove a mailing list identifier tag in -the subject fields of articles. E.g. if the news group - -@example -nntp+news.gnus.org:gmane.text.docbook.apps -@end example - -has the tag @samp{DOC-BOOK-APPS:} in the subject of all articles, this -tag can be removed from the article subjects in the summary buffer for -the group by putting @code{(gnus-list-identifiers "DOCBOOK-APPS:")} -into the group parameters for the group. - -This can also be used as a group-specific hook function. If you want to -hear a beep when you enter a group, you could put something like -@code{(dummy-variable (ding))} in the parameters of that group. If -@code{dummy-variable} has been bound (see above), it will be set to the -(meaningless) result of the @code{(ding)} form. - -Alternatively, since the VARIABLE becomes local to the group, this -pattern can be used to temporarily change a hook. For example, if the -following is added to a group parameter - -@lisp -(gnus-summary-prepared-hook - '(lambda nil (local-set-key "d" (local-key-binding "n")))) -@end lisp - -when the group is entered, the 'd' key will not mark the article as -expired. - -@end table - -@vindex gnus-parameters -Group parameters can be set via the @code{gnus-parameters} variable too. -But some variables, such as @code{visible}, have no effect (For this -case see @code{gnus-permanently-visible-groups} as an alternative.). -For example: - -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil) - (gnus-summary-line-format - "%U%R%z%I%(%[%d:%ub%-23,23f%]%) %s\n") - (gcc-self . t) - (display . all)) - - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")) - - ("mail\\.me" - (gnus-use-scoring t)) - - ("list\\..*" - (total-expire . t) - (broken-reply-to . t)))) -@end lisp - -String value of parameters will be subjected to regexp substitution, as -the @code{to-group} example shows. - -@vindex gnus-parameters-case-fold-search -By default, whether comparing the group name and one of those regexps -specified in @code{gnus-parameters} is done in a case-sensitive manner -or a case-insensitive manner depends on the value of -@code{case-fold-search} at the time when the comparison is done. The -value of @code{case-fold-search} is typically @code{t}; it means, for -example, the element @code{("INBOX\\.FOO" (total-expire . t))} might be -applied to both the @samp{INBOX.FOO} group and the @samp{INBOX.foo} -group. If you want to make those regexps always case-sensitive, set the -value of the @code{gnus-parameters-case-fold-search} variable to -@code{nil}. Otherwise, set it to @code{t} if you want to compare them -always in a case-insensitive manner. - -You can define different sorting to different groups via -@code{gnus-parameters}. Here is an example to sort an @acronym{NNTP} -group by reverse date to see the latest news at the top and an -@acronym{RSS} group by subject. In this example, the first group is the -Debian daily news group @code{gmane.linux.debian.user.news} from -news.gmane.org. The @acronym{RSS} group corresponds to the Debian -weekly news RSS feed -@url{http://packages.debian.org/unstable/newpkg_main.en.rdf}, -@xref{RSS}. - -@lisp -(setq - gnus-parameters - '(("nntp.*gmane\\.debian\\.user\\.news" - (gnus-show-threads nil) - (gnus-article-sort-functions '((not gnus-article-sort-by-date))) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring nil)) - ("nnrss.*debian" - (gnus-show-threads nil) - (gnus-article-sort-functions 'gnus-article-sort-by-subject) - (gnus-use-adaptive-scoring nil) - (gnus-use-scoring t) - (gnus-score-find-score-files-function 'gnus-score-find-single) - (gnus-summary-line-format "%U%R%z%d %I%(%[ %s %]%)\n")))) -@end lisp - - -@node Listing Groups -@section Listing Groups -@cindex group listing - -These commands all list various slices of the groups available. - -@table @kbd - -@item l -@itemx A s -@kindex A s (Group) -@kindex l (Group) -@findex gnus-group-list-groups -List all groups that have unread articles -(@code{gnus-group-list-groups}). If the numeric prefix is used, this -command will list only groups of level ARG and lower. By default, it -only lists groups of level five (i.e., -@code{gnus-group-default-list-level}) or lower (i.e., just subscribed -groups). - -@item L -@itemx A u -@kindex A u (Group) -@kindex L (Group) -@findex gnus-group-list-all-groups -List all groups, whether they have unread articles or not -(@code{gnus-group-list-all-groups}). If the numeric prefix is used, -this command will list only groups of level ARG and lower. By default, -it lists groups of level seven or lower (i.e., just subscribed and -unsubscribed groups). - -@item A l -@kindex A l (Group) -@findex gnus-group-list-level -List all unread groups on a specific level -(@code{gnus-group-list-level}). If given a prefix, also list the groups -with no unread articles. - -@item A k -@kindex A k (Group) -@findex gnus-group-list-killed -List all killed groups (@code{gnus-group-list-killed}). If given a -prefix argument, really list all groups that are available, but aren't -currently (un)subscribed. This could entail reading the active file -from the server. - -@item A z -@kindex A z (Group) -@findex gnus-group-list-zombies -List all zombie groups (@code{gnus-group-list-zombies}). - -@item A m -@kindex A m (Group) -@findex gnus-group-list-matching -List all unread, subscribed groups with names that match a regexp -(@code{gnus-group-list-matching}). - -@item A M -@kindex A M (Group) -@findex gnus-group-list-all-matching -List groups that match a regexp (@code{gnus-group-list-all-matching}). - -@item A A -@kindex A A (Group) -@findex gnus-group-list-active -List absolutely all groups in the active file(s) of the -server(s) you are connected to (@code{gnus-group-list-active}). This -might very well take quite a while. It might actually be a better idea -to do a @kbd{A M} to list all matching, and just give @samp{.} as the -thing to match on. Also note that this command may list groups that -don't exist (yet)---these will be listed as if they were killed groups. -Take the output with some grains of salt. - -@item A a -@kindex A a (Group) -@findex gnus-group-apropos -List all groups that have names that match a regexp -(@code{gnus-group-apropos}). - -@item A d -@kindex A d (Group) -@findex gnus-group-description-apropos -List all groups that have names or descriptions that match a regexp -(@code{gnus-group-description-apropos}). - -@item A c -@kindex A c (Group) -@findex gnus-group-list-cached -List all groups with cached articles (@code{gnus-group-list-cached}). - -@item A ? -@kindex A ? (Group) -@findex gnus-group-list-dormant -List all groups with dormant articles (@code{gnus-group-list-dormant}). - -@item A / -@kindex A / (Group) -@findex gnus-group-list-limit -List groups limited within the current selection -(@code{gnus-group-list-limit}). - -@item A f -@kindex A f (Group) -@findex gnus-group-list-flush -Flush groups from the current selection (@code{gnus-group-list-flush}). - -@item A p -@kindex A p (Group) -@findex gnus-group-list-plus -List groups plus the current selection (@code{gnus-group-list-plus}). - -@end table - -@vindex gnus-permanently-visible-groups -@cindex visible group parameter -Groups that match the @code{gnus-permanently-visible-groups} regexp will -always be shown, whether they have unread articles or not. You can also -add the @code{visible} element to the group parameters in question to -get the same effect. - -@vindex gnus-list-groups-with-ticked-articles -Groups that have just ticked articles in it are normally listed in the -group buffer. If @code{gnus-list-groups-with-ticked-articles} is -@code{nil}, these groups will be treated just like totally empty -groups. It is @code{t} by default. - - -@node Sorting Groups -@section Sorting Groups -@cindex sorting groups - -@kindex C-c C-s (Group) -@findex gnus-group-sort-groups -@vindex gnus-group-sort-function -The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the -group buffer according to the function(s) given by the -@code{gnus-group-sort-function} variable. Available sorting functions -include: - -@table @code - -@item gnus-group-sort-by-alphabet -@findex gnus-group-sort-by-alphabet -Sort the group names alphabetically. This is the default. - -@item gnus-group-sort-by-real-name -@findex gnus-group-sort-by-real-name -Sort the group alphabetically on the real (unprefixed) group names. - -@item gnus-group-sort-by-level -@findex gnus-group-sort-by-level -Sort by group level. - -@item gnus-group-sort-by-score -@findex gnus-group-sort-by-score -Sort by group score. @xref{Group Score}. - -@item gnus-group-sort-by-rank -@findex gnus-group-sort-by-rank -Sort by group score and then the group level. The level and the score -are, when taken together, the group's @dfn{rank}. @xref{Group Score}. - -@item gnus-group-sort-by-unread -@findex gnus-group-sort-by-unread -Sort by number of unread articles. - -@item gnus-group-sort-by-method -@findex gnus-group-sort-by-method -Sort alphabetically on the select method. - -@item gnus-group-sort-by-server -@findex gnus-group-sort-by-server -Sort alphabetically on the Gnus server name. - - -@end table - -@code{gnus-group-sort-function} can also be a list of sorting -functions. In that case, the most significant sort key function must be -the last one. - - -There are also a number of commands for sorting directly according to -some sorting criteria: - -@table @kbd -@item G S a -@kindex G S a (Group) -@findex gnus-group-sort-groups-by-alphabet -Sort the group buffer alphabetically by group name -(@code{gnus-group-sort-groups-by-alphabet}). - -@item G S u -@kindex G S u (Group) -@findex gnus-group-sort-groups-by-unread -Sort the group buffer by the number of unread articles -(@code{gnus-group-sort-groups-by-unread}). - -@item G S l -@kindex G S l (Group) -@findex gnus-group-sort-groups-by-level -Sort the group buffer by group level -(@code{gnus-group-sort-groups-by-level}). - -@item G S v -@kindex G S v (Group) -@findex gnus-group-sort-groups-by-score -Sort the group buffer by group score -(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. - -@item G S r -@kindex G S r (Group) -@findex gnus-group-sort-groups-by-rank -Sort the group buffer by group rank -(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. - -@item G S m -@kindex G S m (Group) -@findex gnus-group-sort-groups-by-method -Sort the group buffer alphabetically by back end name@* -(@code{gnus-group-sort-groups-by-method}). - -@item G S n -@kindex G S n (Group) -@findex gnus-group-sort-groups-by-real-name -Sort the group buffer alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-groups-by-real-name}). - -@end table - -All the commands below obey the process/prefix convention -(@pxref{Process/Prefix}). - -When given a symbolic prefix (@pxref{Symbolic Prefixes}), all these -commands will sort in reverse order. - -You can also sort a subset of the groups: - -@table @kbd -@item G P a -@kindex G P a (Group) -@findex gnus-group-sort-selected-groups-by-alphabet -Sort the groups alphabetically by group name -(@code{gnus-group-sort-selected-groups-by-alphabet}). - -@item G P u -@kindex G P u (Group) -@findex gnus-group-sort-selected-groups-by-unread -Sort the groups by the number of unread articles -(@code{gnus-group-sort-selected-groups-by-unread}). - -@item G P l -@kindex G P l (Group) -@findex gnus-group-sort-selected-groups-by-level -Sort the groups by group level -(@code{gnus-group-sort-selected-groups-by-level}). - -@item G P v -@kindex G P v (Group) -@findex gnus-group-sort-selected-groups-by-score -Sort the groups by group score -(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. - -@item G P r -@kindex G P r (Group) -@findex gnus-group-sort-selected-groups-by-rank -Sort the groups by group rank -(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. - -@item G P m -@kindex G P m (Group) -@findex gnus-group-sort-selected-groups-by-method -Sort the groups alphabetically by back end name@* -(@code{gnus-group-sort-selected-groups-by-method}). - -@item G P n -@kindex G P n (Group) -@findex gnus-group-sort-selected-groups-by-real-name -Sort the groups alphabetically by real (unprefixed) group name -(@code{gnus-group-sort-selected-groups-by-real-name}). - -@item G P s -@kindex G P s (Group) -@findex gnus-group-sort-selected-groups -Sort the groups according to @code{gnus-group-sort-function}. - -@end table - -And finally, note that you can use @kbd{C-k} and @kbd{C-y} to manually -move groups around. - - -@node Group Maintenance -@section Group Maintenance -@cindex bogus groups - -@table @kbd -@item b -@kindex b (Group) -@findex gnus-group-check-bogus-groups -Find bogus groups and delete them -(@code{gnus-group-check-bogus-groups}). - -@item F -@kindex F (Group) -@findex gnus-group-find-new-groups -Find new groups and process them (@code{gnus-group-find-new-groups}). -With 1 @kbd{C-u}, use the @code{ask-server} method to query the server -for new groups. With 2 @kbd{C-u}'s, use most complete method possible -to query the server for new groups, and subscribe the new groups as -zombies. - -@item C-c C-x -@kindex C-c C-x (Group) -@findex gnus-group-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (if any) (@code{gnus-group-expire-articles}). That is, delete -all expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item C-c C-M-x -@kindex C-c C-M-x (Group) -@findex gnus-group-expire-all-groups -@cindex expiring mail -Run all expirable articles in all groups through the expiry process -(@code{gnus-group-expire-all-groups}). - -@end table - - -@node Browse Foreign Server -@section Browse Foreign Server -@cindex foreign servers -@cindex browsing servers - -@table @kbd -@item B -@kindex B (Group) -@findex gnus-group-browse-foreign-server -You will be queried for a select method and a server name. Gnus will -then attempt to contact this server and let you browse the groups there -(@code{gnus-group-browse-foreign-server}). -@end table - -@findex gnus-browse-mode -A new buffer with a list of available groups will appear. This buffer -will use the @code{gnus-browse-mode}. This buffer looks a bit (well, -a lot) like a normal group buffer. - -Here's a list of keystrokes available in the browse mode: - -@table @kbd -@item n -@kindex n (Browse) -@findex gnus-group-next-group -Go to the next group (@code{gnus-group-next-group}). - -@item p -@kindex p (Browse) -@findex gnus-group-prev-group -Go to the previous group (@code{gnus-group-prev-group}). - -@item SPACE -@kindex SPACE (Browse) -@findex gnus-browse-read-group -Enter the current group and display the first article -(@code{gnus-browse-read-group}). - -@item RET -@kindex RET (Browse) -@findex gnus-browse-select-group -Enter the current group (@code{gnus-browse-select-group}). - -@item u -@kindex u (Browse) -@findex gnus-browse-unsubscribe-current-group -Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). - -@item l -@itemx q -@kindex q (Browse) -@kindex l (Browse) -@findex gnus-browse-exit -Exit browse mode (@code{gnus-browse-exit}). - -@item d -@kindex d (Browse) -@findex gnus-browse-describe-group -Describe the current group (@code{gnus-browse-describe-group}). - -@item ? -@kindex ? (Browse) -@findex gnus-browse-describe-briefly -Describe browse mode briefly (well, there's not much to describe, is -there) (@code{gnus-browse-describe-briefly}). -@end table - - -@node Exiting Gnus -@section Exiting Gnus -@cindex exiting Gnus - -Yes, Gnus is ex(c)iting. - -@table @kbd -@item z -@kindex z (Group) -@findex gnus-group-suspend -Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus, -but it kills all buffers except the Group buffer. I'm not sure why this -is a gain, but then who am I to judge? - -@item q -@kindex q (Group) -@findex gnus-group-exit -@c @icon{gnus-group-exit} -Quit Gnus (@code{gnus-group-exit}). - -@item Q -@kindex Q (Group) -@findex gnus-group-quit -Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}). -The dribble file will be saved, though (@pxref{Auto Save}). -@end table - -@vindex gnus-exit-gnus-hook -@vindex gnus-suspend-gnus-hook -@vindex gnus-after-exiting-gnus-hook -@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and -@code{gnus-exit-gnus-hook} is called when you quit Gnus, while -@code{gnus-after-exiting-gnus-hook} is called as the final item when -exiting Gnus. - -Note: - -@quotation -Miss Lisa Cannifax, while sitting in English class, felt her feet go -numbly heavy and herself fall into a hazy trance as the boy sitting -behind her drew repeated lines with his pencil across the back of her -plastic chair. -@end quotation - - -@node Group Topics -@section Group Topics -@cindex topics - -If you read lots and lots of groups, it might be convenient to group -them hierarchically according to topics. You put your Emacs groups over -here, your sex groups over there, and the rest (what, two groups or so?) -you put in some misc section that you never bother with anyway. You can -even group the Emacs sex groups as a sub-topic to either the Emacs -groups or the sex groups---or both! Go wild! - -@iftex -@iflatex -\gnusfigure{Group Topics}{400}{ -\put(75,50){\epsfig{figure=ps/group-topic,height=9cm}} -} -@end iflatex -@end iftex - -Here's an example: - -@example -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end example - -@findex gnus-topic-mode -@kindex t (Group) -To get this @emph{fab} functionality you simply turn on (ooh!) the -@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This -is a toggling command.) - -Go ahead, just try it. I'll still be here when you get back. La de -dum@dots{} Nice tune, that@dots{} la la la@dots{} What, you're back? -Yes, and now press @kbd{l}. There. All your groups are now listed -under @samp{misc}. Doesn't that make you feel all warm and fuzzy? -Hot and bothered? - -If you want this permanently enabled, you should add that minor mode to -the hook for the group mode. Put the following line in your -@file{~/.gnus.el} file: - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@menu -* Topic Commands:: Interactive E-Z commands. -* Topic Variables:: How to customize the topics the Lisp Way. -* Topic Sorting:: Sorting each topic individually. -* Topic Topology:: A map of the world. -* Topic Parameters:: Parameters that apply to all groups in a topic. -@end menu - - -@node Topic Commands -@subsection Topic Commands -@cindex topic commands - -When the topic minor mode is turned on, a new @kbd{T} submap will be -available. In addition, a few of the standard keys change their -definitions slightly. - -In general, the following kinds of operations are possible on topics. -First of all, you want to create topics. Secondly, you want to put -groups in topics and to move them around until you have an order you -like. The third kind of operation is to show/hide parts of the whole -shebang. You might want to hide a topic including its subtopics and -groups, to get a better overview of the other groups. - -Here is a list of the basic keys that you might need to set up topics -the way you like. - -@table @kbd - -@item T n -@kindex T n (Topic) -@findex gnus-topic-create-topic -Prompt for a new topic name and create it -(@code{gnus-topic-create-topic}). - -@item T TAB -@itemx TAB -@kindex T TAB (Topic) -@kindex TAB (Topic) -@findex gnus-topic-indent -``Indent'' the current topic so that it becomes a sub-topic of the -previous topic (@code{gnus-topic-indent}). If given a prefix, -``un-indent'' the topic instead. - -@item M-TAB -@kindex M-TAB (Topic) -@findex gnus-topic-unindent -``Un-indent'' the current topic so that it becomes a sub-topic of the -parent of its current parent (@code{gnus-topic-unindent}). - -@end table - -The following two keys can be used to move groups and topics around. -They work like the well-known cut and paste. @kbd{C-k} is like cut and -@kbd{C-y} is like paste. Of course, this being Emacs, we use the terms -kill and yank rather than cut and paste. - -@table @kbd - -@item C-k -@kindex C-k (Topic) -@findex gnus-topic-kill-group -Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the -topic will be removed along with the topic. - -@item C-y -@kindex C-y (Topic) -@findex gnus-topic-yank-group -Yank the previously killed group or topic -(@code{gnus-topic-yank-group}). Note that all topics will be yanked -before all groups. - -So, to move a topic to the beginning of the list of topics, just hit -@kbd{C-k} on it. This is like the ``cut'' part of cut and paste. Then, -move the cursor to the beginning of the buffer (just below the ``Gnus'' -topic) and hit @kbd{C-y}. This is like the ``paste'' part of cut and -paste. Like I said -- E-Z. - -You can use @kbd{C-k} and @kbd{C-y} on groups as well as on topics. So -you can move topics around as well as groups. - -@end table - -After setting up the topics the way you like them, you might wish to -hide a topic, or to show it again. That's why we have the following -key. - -@table @kbd - -@item RET -@kindex RET (Topic) -@findex gnus-topic-select-group -@itemx SPACE -Either select a group or fold a topic (@code{gnus-topic-select-group}). -When you perform this command on a group, you'll enter the group, as -usual. When done on a topic line, the topic will be folded (if it was -visible) or unfolded (if it was folded already). So it's basically a -toggling command on topics. In addition, if you give a numerical -prefix, group on that level (and lower) will be displayed. - -@end table - -Now for a list of other commands, in no particular order. - -@table @kbd - -@item T m -@kindex T m (Topic) -@findex gnus-topic-move-group -Move the current group to some other topic -(@code{gnus-topic-move-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T j -@kindex T j (Topic) -@findex gnus-topic-jump-to-topic -Go to a topic (@code{gnus-topic-jump-to-topic}). - -@item T c -@kindex T c (Topic) -@findex gnus-topic-copy-group -Copy the current group to some other topic -(@code{gnus-topic-copy-group}). This command uses the process/prefix -convention (@pxref{Process/Prefix}). - -@item T h -@kindex T h (Topic) -@findex gnus-topic-hide-topic -Hide the current topic (@code{gnus-topic-hide-topic}). If given -a prefix, hide the topic permanently. - -@item T s -@kindex T s (Topic) -@findex gnus-topic-show-topic -Show the current topic (@code{gnus-topic-show-topic}). If given -a prefix, show the topic permanently. - -@item T D -@kindex T D (Topic) -@findex gnus-topic-remove-group -Remove a group from the current topic (@code{gnus-topic-remove-group}). -This command is mainly useful if you have the same group in several -topics and wish to remove it from one of the topics. You may also -remove a group from all topics, but in that case, Gnus will add it to -the root topic the next time you start Gnus. In fact, all new groups -(which, naturally, don't belong to any topic) will show up in the root -topic. - -This command uses the process/prefix convention -(@pxref{Process/Prefix}). - -@item T M -@kindex T M (Topic) -@findex gnus-topic-move-matching -Move all groups that match some regular expression to a topic -(@code{gnus-topic-move-matching}). - -@item T C -@kindex T C (Topic) -@findex gnus-topic-copy-matching -Copy all groups that match some regular expression to a topic -(@code{gnus-topic-copy-matching}). - -@item T H -@kindex T H (Topic) -@findex gnus-topic-toggle-display-empty-topics -Toggle hiding empty topics -(@code{gnus-topic-toggle-display-empty-topics}). - -@item T # -@kindex T # (Topic) -@findex gnus-topic-mark-topic -Mark all groups in the current topic with the process mark -(@code{gnus-topic-mark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item T M-# -@kindex T M-# (Topic) -@findex gnus-topic-unmark-topic -Remove the process mark from all groups in the current topic -(@code{gnus-topic-unmark-topic}). This command works recursively on -sub-topics unless given a prefix. - -@item C-c C-x -@kindex C-c C-x (Topic) -@findex gnus-topic-expire-articles -@cindex expiring mail -Run all expirable articles in the current group or topic through the -expiry process (if any) -(@code{gnus-topic-expire-articles}). (@pxref{Expiring Mail}). - -@item T r -@kindex T r (Topic) -@findex gnus-topic-rename -Rename a topic (@code{gnus-topic-rename}). - -@item T DEL -@kindex T DEL (Topic) -@findex gnus-topic-delete -Delete an empty topic (@code{gnus-topic-delete}). - -@item A T -@kindex A T (Topic) -@findex gnus-topic-list-active -List all groups that Gnus knows about in a topics-ified way -(@code{gnus-topic-list-active}). - -@item T M-n -@kindex T M-n (Topic) -@findex gnus-topic-goto-next-topic -Go to the next topic (@code{gnus-topic-goto-next-topic}). - -@item T M-p -@kindex T M-p (Topic) -@findex gnus-topic-goto-previous-topic -Go to the previous topic (@code{gnus-topic-goto-previous-topic}). - -@item G p -@kindex G p (Topic) -@findex gnus-topic-edit-parameters -@cindex group parameters -@cindex topic parameters -@cindex parameters -Edit the topic parameters (@code{gnus-topic-edit-parameters}). -@xref{Topic Parameters}. - -@end table - - -@node Topic Variables -@subsection Topic Variables -@cindex topic variables - -The previous section told you how to tell Gnus which topics to display. -This section explains how to tell Gnus what to display about each topic. - -@vindex gnus-topic-line-format -The topic lines themselves are created according to the -@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). -Valid elements are: - -@table @samp -@item i -Indentation. -@item n -Topic name. -@item v -Visibility. -@item l -Level. -@item g -Number of groups in the topic. -@item a -Number of unread articles in the topic. -@item A -Number of unread articles in the topic and all its subtopics. -@end table - -@vindex gnus-topic-indent-level -Each sub-topic (and the groups in the sub-topics) will be indented with -@code{gnus-topic-indent-level} times the topic level number of spaces. -The default is 2. - -@vindex gnus-topic-mode-hook -@code{gnus-topic-mode-hook} is called in topic minor mode buffers. - -@vindex gnus-topic-display-empty-topics -The @code{gnus-topic-display-empty-topics} says whether to display even -topics that have no unread articles in them. The default is @code{t}. - - -@node Topic Sorting -@subsection Topic Sorting -@cindex topic sorting - -You can sort the groups in each topic individually with the following -commands: - - -@table @kbd -@item T S a -@kindex T S a (Topic) -@findex gnus-topic-sort-groups-by-alphabet -Sort the current topic alphabetically by group name -(@code{gnus-topic-sort-groups-by-alphabet}). - -@item T S u -@kindex T S u (Topic) -@findex gnus-topic-sort-groups-by-unread -Sort the current topic by the number of unread articles -(@code{gnus-topic-sort-groups-by-unread}). - -@item T S l -@kindex T S l (Topic) -@findex gnus-topic-sort-groups-by-level -Sort the current topic by group level -(@code{gnus-topic-sort-groups-by-level}). - -@item T S v -@kindex T S v (Topic) -@findex gnus-topic-sort-groups-by-score -Sort the current topic by group score -(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. - -@item T S r -@kindex T S r (Topic) -@findex gnus-topic-sort-groups-by-rank -Sort the current topic by group rank -(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. - -@item T S m -@kindex T S m (Topic) -@findex gnus-topic-sort-groups-by-method -Sort the current topic alphabetically by back end name -(@code{gnus-topic-sort-groups-by-method}). - -@item T S e -@kindex T S e (Topic) -@findex gnus-topic-sort-groups-by-server -Sort the current topic alphabetically by server name -(@code{gnus-topic-sort-groups-by-server}). - -@item T S s -@kindex T S s (Topic) -@findex gnus-topic-sort-groups -Sort the current topic according to the function(s) given by the -@code{gnus-group-sort-function} variable -(@code{gnus-topic-sort-groups}). - -@end table - -When given a prefix argument, all these commands will sort in reverse -order. @xref{Sorting Groups}, for more information about group -sorting. - - -@node Topic Topology -@subsection Topic Topology -@cindex topic topology -@cindex topology - -So, let's have a look at an example group buffer: - -@example -@group -Gnus - Emacs -- I wuw it! - 3: comp.emacs - 2: alt.religion.emacs - Naughty Emacs - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix -@end group -@end example - -So, here we have one top-level topic (@samp{Gnus}), two topics under -that, and one sub-topic under one of the sub-topics. (There is always -just one (1) top-level topic). This topology can be expressed as -follows: - -@lisp -(("Gnus" visible) - (("Emacs -- I wuw it!" visible) - (("Naughty Emacs" visible))) - (("Misc" visible))) -@end lisp - -@vindex gnus-topic-topology -This is in fact how the variable @code{gnus-topic-topology} would look -for the display above. That variable is saved in the @file{.newsrc.eld} -file, and shouldn't be messed with manually---unless you really want -to. Since this variable is read from the @file{.newsrc.eld} file, -setting it in any other startup files will have no effect. - -This topology shows what topics are sub-topics of what topics (right), -and which topics are visible. Two settings are currently -allowed---@code{visible} and @code{invisible}. - - -@node Topic Parameters -@subsection Topic Parameters -@cindex topic parameters - -All groups in a topic will inherit group parameters from the parent -(and ancestor) topic parameters. All valid group parameters are valid -topic parameters (@pxref{Group Parameters}). When the agent is -enabled, all agent parameters (See Agent Parameters in @ref{Category -Syntax}) are also valid topic parameters. - -In addition, the following parameters are only valid as topic -parameters: - -@table @code -@item subscribe -When subscribing new groups by topic (@pxref{Subscription Methods}), the -@code{subscribe} topic parameter says what groups go in what topic. Its -value should be a regexp to match the groups that should go in that -topic. - -@item subscribe-level -When subscribing new groups by topic (see the @code{subscribe} parameter), -the group will be subscribed with the level specified in the -@code{subscribe-level} instead of @code{gnus-level-default-subscribed}. - -@end table - -Group parameters (of course) override topic parameters, and topic -parameters in sub-topics override topic parameters in super-topics. You -know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a -verb, although you may feel free to disagree with me here.) - -@example -@group -Gnus - Emacs - 3: comp.emacs - 2: alt.religion.emacs - 452: alt.sex.emacs - Relief - 452: alt.sex.emacs - 0: comp.talk.emacs.recovery - Misc - 8: comp.binaries.fractals - 13: comp.sources.unix - 452: alt.sex.emacs -@end group -@end example - -The @samp{Emacs} topic has the topic parameter @code{(score-file -. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter -@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the -topic parameter @code{(score-file . "emacs.SCORE")}. In addition, -@* @samp{alt.religion.emacs} has the group parameter @code{(score-file -. "religion.SCORE")}. - -Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you -will get the @file{relief.SCORE} home score file. If you enter the same -group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home -score file. If you enter the group @samp{alt.religion.emacs}, you'll -get the @file{religion.SCORE} home score file. - -This seems rather simple and self-evident, doesn't it? Well, yes. But -there are some problems, especially with the @code{total-expiry} -parameter. Say you have a mail group in two topics; one with -@code{total-expiry} and one without. What happens when you do @kbd{M-x -gnus-expire-all-expirable-groups}? Gnus has no way of telling which one -of these topics you mean to expire articles from, so anything may -happen. In fact, I hereby declare that it is @dfn{undefined} what -happens. You just have to be careful if you do stuff like that. - - -@node Non-ASCII Group Names -@section Accessing groups of non-English names -@cindex non-ascii group names - -There are some news servers that provide groups of which the names are -expressed with their native languages in the world. For instance, in a -certain news server there are some newsgroups of which the names are -spelled in Chinese, where people are talking in Chinese. You can, of -course, subscribe to such news groups using Gnus. Currently Gnus -supports non-@acronym{ASCII} group names not only with the @code{nntp} -back end but also with the @code{nnml} back end and the @code{nnrss} -back end. - -Every such group name is encoded by a certain charset in the server -side (in an @acronym{NNTP} server its administrator determines the -charset, but for groups in the other back ends it is determined by you). -Gnus has to display the decoded ones for you in the group buffer and the -article buffer, and needs to use the encoded ones when communicating -with servers. However, Gnus doesn't know what charset is used for each -non-@acronym{ASCII} group name. The following two variables are just -the ones for telling Gnus what charset should be used for each group: - -@table @code -@item gnus-group-name-charset-method-alist -@vindex gnus-group-name-charset-method-alist -An alist of select methods and charsets. The default value is -@code{nil}. The names of groups in the server specified by that select -method are all supposed to use the corresponding charset. For example: - -@lisp -(setq gnus-group-name-charset-method-alist - '(((nntp "news.com.cn") . cn-gb-2312))) -@end lisp - -Charsets specified for groups with this variable are preferred to the -ones specified for the same groups with the -@code{gnus-group-name-charset-group-alist} variable (see below). - -A select method can be very long, like: - -@lisp -(nntp "gmane" - (nntp-address "news.gmane.org") - (nntp-end-of-line "\n") - (nntp-open-connection-function - nntp-open-via-rlogin-and-telnet) - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches - ("-C" "-t" "-e" "none")) - (nntp-via-address @dots{})) -@end lisp - -In that case, you can truncate it into @code{(nntp "gmane")} in this -variable. That is, it is enough to contain only the back end name and -the server name. - -@item gnus-group-name-charset-group-alist -@cindex UTF-8 group names -@vindex gnus-group-name-charset-group-alist -An alist of regexp of group name and the charset for group names. -@code{((".*" . utf-8))} is the default value if UTF-8 is supported, -otherwise the default is @code{nil}. For example: - -@lisp -(setq gnus-group-name-charset-group-alist - '(("\\.com\\.cn:" . cn-gb-2312) - (".*" . utf-8))) -@end lisp - -Note that this variable is ignored if the match is made with -@code{gnus-group-name-charset-method-alist}. -@end table - -Those two variables are used also to determine the charset for encoding -and decoding non-@acronym{ASCII} group names that are in the back ends -other than @code{nntp}. It means that it is you who determine it. If -you do nothing, the charset used for group names in those back ends will -all be @code{utf-8} because of the last element of -@code{gnus-group-name-charset-group-alist}. - -There is one more important variable for non-@acronym{ASCII} group -names: - -@table @code -@item nnmail-pathname-coding-system -@vindex nnmail-pathname-coding-system -The value of this variable should be a coding system or @code{nil}. The -default is @code{nil} in Emacs, or is the aliasee of the coding system -named @code{file-name} (a certain coding system of which an alias is -@code{file-name}) in XEmacs. - -The @code{nnml} back end, the @code{nnrss} back end, the @acronym{NNTP} -marks feature (@pxref{NNTP marks}), the agent, and the cache use -non-@acronym{ASCII} group names in those files and directories. This -variable overrides the value of @code{file-name-coding-system} which -specifies the coding system used when encoding and decoding those file -names and directory names. - -In XEmacs (with the @code{mule} feature), @code{file-name-coding-system} -is the only means to specify the coding system used to encode and decode -file names. On the other hand, Emacs uses the value of -@code{default-file-name-coding-system} if @code{file-name-coding-system} -is @code{nil} or it is bound to the value of -@code{nnmail-pathname-coding-system} which is @code{nil}. - -Normally the value of @code{default-file-name-coding-system} in Emacs or -@code{nnmail-pathname-coding-system} in XEmacs is initialized according -to the locale, so you will need to do nothing if the value is suitable -to encode and decode non-@acronym{ASCII} group names. - -The value of this variable (or @code{default-file-name-coding-system}) -does not necessarily need to be the same value that is determined by -@code{gnus-group-name-charset-method-alist} and -@code{gnus-group-name-charset-group-alist}. - -If @code{default-file-name-coding-system} or this variable is -initialized by default to @code{iso-latin-1} for example, although you -want to subscribe to the groups spelled in Chinese, that is the most -typical case where you have to customize -@code{nnmail-pathname-coding-system}. The @code{utf-8} coding system is -a good candidate for it. Otherwise, you may change the locale in your -system so that @code{default-file-name-coding-system} or this variable -may be initialized to an appropriate value. -@end table - -Note that when you copy or move articles from a non-@acronym{ASCII} -group to another group, the charset used to encode and decode group -names should be the same in both groups. Otherwise the Newsgroups -header will be displayed incorrectly in the article buffer. - - -@node Searching -@section Searching - -@menu -* nnir:: Searching on IMAP, with swish, namazu, etc. -* nnmairix:: Searching maildir, MH or mbox with Mairix. -@end menu - -@cindex Searching - -FIXME: This node is a stub. - -FIXME: Add a brief overview of Gnus search capabilities. A brief -comparison of nnir, nnmairix, contrib/gnus-namazu would be nice -as well. - -FIXME: Explain difference to @ref{Searching for Articles}, add reference -and back-reference. - -@node nnir -@subsection nnir - -FIXME: As a first step, convert the commentary of @file{nnir} to texi. -@cindex nnir - -@node nnmairix -@subsection nnmairix - -@cindex mairix -@cindex nnmairix -This paragraph describes how to set up mairix and the back end -@code{nnmairix} for indexing and searching your mail from within -Gnus. Additionally, you can create permanent ``smart'' groups which are -bound to mairix searches and are automatically updated. - -@menu -* About mairix:: About the mairix mail search engine -* nnmairix requirements:: What you will need for using nnmairix -* What nnmairix does:: What does nnmairix actually do? -* Setting up mairix:: Set up your mairix installation -* Configuring nnmairix:: Set up the nnmairix back end -* nnmairix keyboard shortcuts:: List of available keyboard shortcuts -* Propagating marks:: How to propagate marks from nnmairix groups -* nnmairix tips and tricks:: Some tips, tricks and examples -* nnmairix caveats:: Some more stuff you might want to know -@end menu - -@c FIXME: The markup in this section might need improvement. -@c E.g. adding @samp, @var, @file, @command, etc. -@c Cf. (info "(texinfo)Indicating") - -@node About mairix -@subsubsection About mairix - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, which you can use via the @code{nnir} back end, it -has the prime advantage of being incredibly fast. On current systems, it -can easily search through headers and message bodies of thousands and -thousands of mails in well under a second. Building the database -necessary for searching might take a minute or two, but only has to be -done once fully. Afterwards, the updates are done incrementally and -therefore are really fast, too. Additionally, mairix is very easy to set -up. - -For maximum speed though, mairix should be used with mails stored in -@code{Maildir} or @code{MH} format (this includes the @code{nnml} back -end), although it also works with mbox. Mairix presents the search -results by populating a @emph{virtual} maildir/MH folder with symlinks -which point to the ``real'' message files (if mbox is used, copies are -made). Since mairix already presents search results in such a virtual -mail folder, it is very well suited for using it as an external program -for creating @emph{smart} mail folders, which represent certain mail -searches. This is similar to a Kiboze group (@pxref{Kibozed Groups}), -but much faster. - -@node nnmairix requirements -@subsubsection nnmairix requirements - -Mairix searches local mail---that means, mairix absolutely must have -direct access to your mail folders. If your mail resides on another -server (e.g. an @acronym{IMAP} server) and you happen to have shell -access, @code{nnmairix} supports running mairix remotely, e.g. via ssh. - -Additionally, @code{nnmairix} only supports the following Gnus back -ends: @code{nnml}, @code{nnmaildir}, and @code{nnimap}. You must use -one of these back ends for using @code{nnmairix}. Other back ends, like -@code{nnmbox}, @code{nnfolder} or @code{nnmh}, won't work. - -If you absolutely must use mbox and still want to use @code{nnmairix}, -you can set up a local @acronym{IMAP} server, which you then access via -@code{nnimap}. This is a rather massive setup for accessing some mbox -files, so just change to MH or Maildir already... However, if you're -really, really passionate about using mbox, you might want to look into -the package @file{mairix.el}, which comes with Emacs 23. - -@node What nnmairix does -@subsubsection What nnmairix does - -The back end @code{nnmairix} enables you to call mairix from within Gnus, -either to query mairix with a search term or to update the -database. While visiting a message in the summary buffer, you can use -several pre-defined shortcuts for calling mairix, e.g. to quickly -search for all mails from the sender of the current message or to -display the whole thread associated with the message, even if the -mails are in different folders. - -Additionally, you can create permanent @code{nnmairix} groups which are bound -to certain mairix searches. This way, you can easily create a group -containing mails from a certain sender, with a certain subject line or -even for one specific thread based on the Message-ID. If you check for -new mail in these folders (e.g. by pressing @kbd{g} or @kbd{M-g}), they -automatically update themselves by calling mairix. - -You might ask why you need @code{nnmairix} at all, since mairix already -creates the group, populates it with links to the mails so that you can -then access it with Gnus, right? Well, this @emph{might} work, but often -does not---at least not without problems. Most probably you will get -strange article counts, and sometimes you might see mails which Gnus -claims have already been canceled and are inaccessible. This is due to -the fact that Gnus isn't really amused when things are happening behind -its back. Another problem can be the mail back end itself, e.g. if you -use mairix with an @acronym{IMAP} server (I had Dovecot complaining -about corrupt index files when mairix changed the contents of the search -group). Using @code{nnmairix} should circumvent these problems. - -@code{nnmairix} is not really a mail back end---it's actually more like -a wrapper, sitting between a ``real'' mail back end where mairix stores -the searches and the Gnus front end. You can choose between three -different mail back ends for the mairix folders: @code{nnml}, -@code{nnmaildir} or @code{nnimap}. @code{nnmairix} will call the mairix -binary so that the search results are stored in folders named -@code{zz_mairix--} on this mail back end, but it will -present these folders in the Gnus front end only with @code{}. -You can use an existing mail back end where you already store your mail, -but if you're uncomfortable with @code{nnmairix} creating new mail -groups alongside your other mail, you can also create e.g. a new -@code{nnmaildir} or @code{nnml} server exclusively for mairix, but then -make sure those servers do not accidentally receive your new mail -(@pxref{nnmairix caveats}). A special case exists if you want to use -mairix remotely on an IMAP server with @code{nnimap}---here the mairix -folders and your other mail must be on the same @code{nnimap} back end. - -@node Setting up mairix -@subsubsection Setting up mairix - -First: create a backup of your mail folders (@pxref{nnmairix caveats}). - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your Maildir/MH base folder -base=~/Maildir -@end example - -This is the base folder for your mails. All the following directories -are relative to this base folder. If you want to use @code{nnmairix} -with @code{nnimap}, this base directory has to point to the mail -directory where the @acronym{IMAP} server stores the mail folders! - -@example -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -mbox = ... your mbox files which should be indexed ... -@end example - -This specifies all your mail folders and mbox files (relative to the -base directory!) you want to index with mairix. Note that the -@code{nnml} back end saves mails in MH format, so you have to put those -directories in the @code{mh} line. See the example at the end of this -section and mairixrc's man-page for further details. - -@example -omit=zz_mairix-* -@end example - -@vindex nnmairix-group-prefix -This should make sure that you don't accidentally index the mairix -search results. You can change the prefix of these folders with the -variable @code{nnmairix-group-prefix}. - -@example -mformat= ... 'maildir' or 'mh' ... -database= ... location of database file ... -@end example - -The @code{format} setting specifies the output format for the mairix -search folder. Set this to @code{mh} if you want to access search results -with @code{nnml}. Otherwise choose @code{maildir}. - -To summarize, here is my shortened @file{.mairixrc} file as an example: - -@example -base=~/Maildir -maildir=.personal:.work:.logcheck:.sent -mh=../Mail/nnml/*... -mbox=../mboxmail/mailarchive_year* -mformat=maildir -omit=zz_mairix-* -database=~/.mairixdatabase -@end example - -In this case, the base directory is @file{~/Maildir}, where all my Maildir -folders are stored. As you can see, the folders are separated by -colons. If you wonder why every folder begins with a dot: this is -because I use Dovecot as @acronym{IMAP} server, which again uses -@code{Maildir++} folders. For testing nnmairix, I also have some -@code{nnml} mail, which is saved in @file{~/Mail/nnml}. Since this has -to be specified relative to the @code{base} directory, the @code{../Mail} -notation is needed. Note that the line ends in @code{*...}, which means -to recursively scan all files under this directory. Without the three -dots, the wildcard @code{*} will not work recursively. I also have some -old mbox files with archived mail lying around in @file{~/mboxmail}. -The other lines should be obvious. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Configuring nnmairix -@subsubsection Configuring nnmairix - -In group mode, type @kbd{G b c} -(@code{nnmairix-create-server-and-default-group}). This will ask you for all -necessary information and create a @code{nnmairix} server as a foreign -server. You will have to specify the following: - -@itemize @bullet - -@item -The @strong{name} of the @code{nnmairix} server---choose whatever you -want. - -@item -The name of the @strong{back end server} where mairix should store its -searches. This must be a full server name, like @code{nnml:mymail}. -Just hit @kbd{TAB} to see the available servers. Currently, servers -which are accessed through @code{nnmaildir}, @code{nnimap} and -@code{nnml} are supported. As explained above, for locally stored -mails, this can be an existing server where you store your mails. -However, you can also create e.g. a new @code{nnmaildir} or @code{nnml} -server exclusively for @code{nnmairix} in your secondary select methods -(@pxref{Finding the News}). If you use a secondary @code{nnml} server -just for mairix, make sure that you explicitly set the server variable -@code{nnml-get-new-mail} to @code{nil}, or you might loose mail -(@pxref{nnmairix caveats}). If you want to use mairix remotely on an -@acronym{IMAP} server, you have to choose the corresponding -@code{nnimap} server here. - -@item -@vindex nnmairix-mairix-search-options -The @strong{command} to call the mairix binary. This will usually just -be @code{mairix}, but you can also choose something like @code{ssh -SERVER mairix} if you want to call mairix remotely, e.g. on your -@acronym{IMAP} server. If you want to add some default options to -mairix, you could do this here, but better use the variable -@code{nnmairix-mairix-search-options} instead. - -@item -The name of the @strong{default search group}. This will be the group -where all temporary mairix searches are stored, i.e. all searches which -are not bound to permanent @code{nnmairix} groups. Choose whatever you -like. - -@item -If the mail back end is @code{nnimap} or @code{nnmaildir}, you will be -asked if you work with @strong{Maildir++}, i.e. with hidden maildir -folders (=beginning with a dot). For example, you have to answer -@samp{yes} here if you work with the Dovecot @acronym{IMAP} -server. Otherwise, you should answer @samp{no} here. - -@end itemize - -@node nnmairix keyboard shortcuts -@subsubsection nnmairix keyboard shortcuts - -In group mode: - -@table @kbd - -@item G b c -@kindex G b c (Group) -@findex nnmairix-create-server-and-default-group -Creates @code{nnmairix} server and default search group for this server -(@code{nnmairix-create-server-and-default-group}). You should have done -this by now (@pxref{Configuring nnmairix}). - -@item G b s -@kindex G b s (Group) -@findex nnmairix-search -Prompts for query which is then sent to the mairix binary. Search -results are put into the default search group which is automatically -displayed (@code{nnmairix-search}). - -@item G b m -@kindex G b m (Group) -@findex nnmairix-widget-search -Allows you to create a mairix search or a permanent group more -comfortably using graphical widgets, similar to a customization -group. Just try it to see how it works (@code{nnmairix-widget-search}). - -@item G b i -@kindex G b i (Group) -@findex nnmairix-search-interactive -Another command for creating a mairix query more comfortably, but uses -only the minibuffer (@code{nnmairix-search-interactive}). - -@item G b g -@kindex G b g (Group) -@findex nnmairix-create-search-group -Creates a permanent group which is associated with a search query -(@code{nnmairix-create-search-group}). The @code{nnmairix} back end -automatically calls mairix when you update this group with @kbd{g} or -@kbd{M-g}. - -@item G b q -@kindex G b q (Group) -@findex nnmairix-group-change-query-this-group -Changes the search query for the @code{nnmairix} group under cursor -(@code{nnmairix-group-change-query-this-group}). - -@item G b t -@kindex G b t (Group) -@findex nnmairix-group-toggle-threads-this-group -Toggles the 'threads' parameter for the @code{nnmairix} group under cursor, -i.e. if you want see the whole threads of the found messages -(@code{nnmairix-group-toggle-threads-this-group}). - -@item G b u -@kindex G b u (Group) -@findex nnmairix-update-database -@vindex nnmairix-mairix-update-options -Calls mairix binary for updating the database -(@code{nnmairix-update-database}). The default parameters are @code{-F} -and @code{-Q} for making this as fast as possible (see variable -@code{nnmairix-mairix-update-options} for defining these default -options). - -@item G b r -@kindex G b r (Group) -@findex nnmairix-group-toggle-readmarks-this-group -Keep articles in this @code{nnmairix} group always read or unread, or leave the -marks unchanged (@code{nnmairix-group-toggle-readmarks-this-group}). - -@item G b d -@kindex G b d (Group) -@findex nnmairix-group-delete-recreate-this-group -Recreate @code{nnmairix} group on the ``real'' mail back end -(@code{nnmairix-group-delete-recreate-this-group}). You can do this if -you always get wrong article counts with a @code{nnmairix} group. - -@item G b a -@kindex G b a (Group) -@findex nnmairix-group-toggle-allowfast-this-group -Toggles the @code{allow-fast} parameters for group under cursor -(@code{nnmairix-group-toggle-allowfast-this-group}). The default -behavior of @code{nnmairix} is to do a mairix search every time you -update or enter the group. With the @code{allow-fast} parameter set, -mairix will only be called when you explicitly update the group, but not -upon entering. This makes entering the group faster, but it may also -lead to dangling symlinks if something changed between updating and -entering the group which is not yet in the mairix database. - -@item G b p -@kindex G b p (Group) -@findex nnmairix-group-toggle-propmarks-this-group -Toggle marks propagation for this group -(@code{nnmairix-group-toggle-propmarks-this-group}). (@pxref{Propagating -marks}). - -@item G b o -@kindex G b o (Group) -@findex nnmairix-propagate-marks -Manually propagate marks (@code{nnmairix-propagate-marks}); needed only when -@code{nnmairix-propagate-marks-upon-close} is set to @code{nil}. - -@end table - -In summary mode: - -@table @kbd - -@item $ m -@kindex $ m (Summary) -@findex nnmairix-widget-search-from-this-article -Allows you to create a mairix query or group based on the current -message using graphical widgets (same as @code{nnmairix-widget-search}) -(@code{nnmairix-widget-search-from-this-article}). - -@item $ g -@kindex $ g (Summary) -@findex nnmairix-create-search-group-from-message -Interactively creates a new search group with query based on the current -message, but uses the minibuffer instead of graphical widgets -(@code{nnmairix-create-search-group-from-message}). - -@item $ t -@kindex $ t (Summary) -@findex nnmairix-search-thread-this-article -Searches thread for the current article -(@code{nnmairix-search-thread-this-article}). This is effectively a -shortcut for calling @code{nnmairix-search} with @samp{m:msgid} of the -current article and enabled threads. - -@item $ f -@kindex $ f (Summary) -@findex nnmairix-search-from-this-article -Searches all messages from sender of the current article -(@code{nnmairix-search-from-this-article}). This is a shortcut for -calling @code{nnmairix-search} with @samp{f:From}. - -@item $ o -@kindex $ o (Summary) -@findex nnmairix-goto-original-article -(Only in @code{nnmairix} groups!) Tries determine the group this article -originally came from and displays the article in this group, so that -e.g. replying to this article the correct posting styles/group -parameters are applied (@code{nnmairix-goto-original-article}). This -function will use the registry if available, but can also parse the -article file name as a fallback method. - -@item $ u -@kindex $ u (Summary) -@findex nnmairix-remove-tick-mark-original-article -Remove possibly existing tick mark from original article -(@code{nnmairix-remove-tick-mark-original-article}). (@pxref{nnmairix -tips and tricks}). - -@end table - -@node Propagating marks -@subsubsection Propagating marks - -First of: you really need a patched mairix binary for using the marks -propagation feature efficiently. Otherwise, you would have to update -the mairix database all the time. You can get the patch at - -@uref{http://www.randomsample.de/mairix-maildir-patch.tar} - -You need the mairix v0.21 source code for this patch; everything else -is explained in the accompanied readme file. If you don't want to use -marks propagation, you don't have to apply these patches, but they also -fix some annoyances regarding changing maildir flags, so it might still -be useful to you. - -With the patched mairix binary, you can use @code{nnmairix} as an -alternative to mail splitting (@pxref{Fancy Mail Splitting}). For -example, instead of splitting all mails from @samp{david@@foobar.com} -into a group, you can simply create a search group with the query -@samp{f:david@@foobar.com}. This is actually what ``smart folders'' are -all about: simply put everything in one mail folder and dynamically -create searches instead of splitting. This is more flexible, since you -can dynamically change your folders any time you want to. This also -implies that you will usually read your mails in the @code{nnmairix} -groups instead of your ``real'' mail groups. - -There is one problem, though: say you got a new mail from -@samp{david@@foobar.com}; it will now show up in two groups, the -``real'' group (your INBOX, for example) and in the @code{nnmairix} -search group (provided you have updated the mairix database). Now you -enter the @code{nnmairix} group and read the mail. The mail will be -marked as read, but only in the @code{nnmairix} group---in the ``real'' -mail group it will be still shown as unread. - -You could now catch up the mail group (@pxref{Group Data}), but this is -tedious and error prone, since you may overlook mails you don't have -created @code{nnmairix} groups for. Of course, you could first use -@code{nnmairix-goto-original-article} (@pxref{nnmairix keyboard -shortcuts}) and then read the mail in the original group, but that's -even more cumbersome. - -Clearly, the easiest way would be if marks could somehow be -automatically set for the original article. This is exactly what -@emph{marks propagation} is about. - -Marks propagation is deactivated by default. You can activate it for a -certain @code{nnmairix} group with -@code{nnmairix-group-toggle-propmarks-this-group} (bound to @kbd{G b -p}). This function will warn you if you try to use it with your default -search group; the reason is that the default search group is used for -temporary searches, and it's easy to accidentally propagate marks from -this group. However, you can ignore this warning if you really want to. - -With marks propagation enabled, all the marks you set in a @code{nnmairix} -group should now be propagated to the original article. For example, -you can now tick an article (by default with @kbd{!}) and this mark should -magically be set for the original article, too. - -A few more remarks which you may or may not want to know: - -@vindex nnmairix-propagate-marks-upon-close -Marks will not be set immediately, but only upon closing a group. This -not only makes marks propagation faster, it also avoids problems with -dangling symlinks when dealing with maildir files (since changing flags -will change the file name). You can also control when to propagate marks -via @code{nnmairix-propagate-marks-upon-close} (see the doc-string for -details). - -Obviously, @code{nnmairix} will have to look up the original group for every -article you want to set marks for. If available, @code{nnmairix} will first use -the registry for determining the original group. The registry is very -fast, hence you should really, really enable the registry when using -marks propagation. If you don't have to worry about RAM and disc space, -set @code{gnus-registry-max-entries} to a large enough value; to be on -the safe side, choose roughly the amount of mails you index with mairix. - -@vindex nnmairix-only-use-registry -If you don't want to use the registry or the registry hasn't seen the -original article yet, @code{nnmairix} will use an additional mairix -search for determining the file name of the article. This, of course, is -way slower than the registry---if you set hundreds or even thousands of -marks this way, it might take some time. You can avoid this situation by -setting @code{nnmairix-only-use-registry} to t. - -Maybe you also want to propagate marks the other way round, i.e. if you -tick an article in a "real" mail group, you'd like to have the same -article in a @code{nnmairix} group ticked, too. For several good -reasons, this can only be done efficiently if you use maildir. To -immediately contradict myself, let me mention that it WON'T work with -@code{nnmaildir}, since @code{nnmaildir} stores the marks externally and -not in the file name. Therefore, propagating marks to @code{nnmairix} -groups will usually only work if you use an IMAP server which uses -maildir as its file format. - -@vindex nnmairix-propagate-marks-to-nnmairix-groups -If you work with this setup, just set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t} and see what -happens. If you don't like what you see, just set it to @code{nil} again. One -problem might be that you get a wrong number of unread articles; this -usually happens when you delete or expire articles in the original -groups. When this happens, you can recreate the @code{nnmairix} group on the -back end using @kbd{G b d}. - -@node nnmairix tips and tricks -@subsubsection nnmairix tips and tricks - -@itemize -@item -Checking Mail - -@findex nnmairix-update-groups -I put all my important mail groups at group level 1. The mairix groups -have group level 5, so they do not get checked at start up (@pxref{Group -Levels}). - -I use the following to check for mails: - -@lisp -(defun my-check-mail-mairix-update (level) - (interactive "P") - ;; if no prefix given, set level=1 - (gnus-group-get-new-news (or level 1)) - (nnmairix-update-groups "mairixsearch" t t) - (gnus-group-list-groups)) - -(define-key gnus-group-mode-map "g" 'my-check-mail-mairix-update) -@end lisp - -Instead of @samp{"mairixsearch"} use the name of your @code{nnmairix} -server. See the doc string for @code{nnmairix-update-groups} for -details. - -@item -Example: search group for ticked articles - -For example, you can create a group for all ticked articles, where the -articles always stay unread: - -Hit @kbd{G b g}, enter group name (e.g. @samp{important}), use -@samp{F:f} as query and do not include threads. - -Now activate marks propagation for this group by using @kbd{G b p}. Then -activate the always-unread feature by using @kbd{G b r} twice. - -So far so good---but how do you remove the tick marks in the @code{nnmairix} -group? There are two options: You may simply use -@code{nnmairix-remove-tick-mark-original-article} (bound to @kbd{$ u}) to remove -tick marks from the original article. The other possibility is to set -@code{nnmairix-propagate-marks-to-nnmairix-groups} to @code{t}, but see the above -comments about this option. If it works for you, the tick marks should -also exist in the @code{nnmairix} group and you can remove them as usual, -e.g. by marking an article as read. - -When you have removed a tick mark from the original article, this -article should vanish from the @code{nnmairix} group after you have updated the -mairix database and updated the group. Fortunately, there is a function -for doing exactly that: @code{nnmairix-update-groups}. See the previous code -snippet and the doc string for details. - -@item -Dealing with auto-subscription of mail groups - -As described before, all @code{nnmairix} groups are in fact stored on -the mail back end in the form @samp{zz_mairix--}. You can -see them when you enter the back end server in the server buffer. You -should not subscribe these groups! Unfortunately, these groups will -usually get @emph{auto-subscribed} when you use @code{nnmaildir} or -@code{nnml}, i.e. you will suddenly see groups of the form -@samp{zz_mairix*} pop up in your group buffer. If this happens to you, -simply kill these groups with C-k. For avoiding this, turn off -auto-subscription completely by setting the variable -@code{gnus-auto-subscribed-groups} to @code{nil} (@pxref{Filtering New -Groups}), or if you like to keep this feature use the following kludge -for turning it off for all groups beginning with @samp{zz_}: - -@lisp -(setq gnus-auto-subscribed-groups - "^\\(nnml\\|nnfolder\\|nnmbox\\|nnmh\\|nnbabyl\\|nnmaildir\\).*:\\([^z]\\|z$\\|\\z[^z]\\|zz$\\|zz[^_]\\|zz_$\\).*") -@end lisp - -@end itemize - -@node nnmairix caveats -@subsubsection nnmairix caveats - -@itemize -@item -You can create a secondary @code{nnml} server just for nnmairix, but then -you have to explicitly set the corresponding server variable -@code{nnml-get-new-mail} to @code{nil}. Otherwise, new mail might get -put into this secondary server (and would never show up again). Here's -an example server definition: - -@lisp -(nnml "mairix" (nnml-directory "mairix") (nnml-get-new-mail nil)) -@end lisp - -(The @code{nnmaildir} back end also has a server variabe -@code{get-new-mail}, but its default value is @code{nil}, so you don't -have to explicitly set it if you use a @code{nnmaildir} server just for -mairix.) - -@item -If you use the Gnus registry: don't use the registry with -@code{nnmairix} groups (put them in -@code{gnus-registry-unfollowed-groups}). Be @emph{extra careful} if -you use @code{gnus-registry-split-fancy-with-parent}; mails which are -split into @code{nnmairix} groups are usually gone for good as soon as -you check the group for new mail (yes, it has happened to me...). - -@item -Therefore: @emph{Never ever} put ``real'' mails into @code{nnmairix} -groups (you shouldn't be able to, anyway). - -@item -If you use the Gnus agent (@pxref{Gnus Unplugged}): don't agentize -@code{nnmairix} groups (though I have no idea what happens if you do). - -@item -mairix does only support us-ascii characters. - -@item -@code{nnmairix} uses a rather brute force method to force Gnus to -completely reread the group on the mail back end after mairix was -called---it simply deletes and re-creates the group on the mail -back end. So far, this has worked for me without any problems, and I -don't see how @code{nnmairix} could delete other mail groups than its -own, but anyway: you really should have a backup of your mail -folders. - -@item -All necessary information is stored in the group parameters -(@pxref{Group Parameters}). This has the advantage that no active file -is needed, but also implies that when you kill a @code{nnmairix} group, -it is gone for good. - -@item -@findex nnmairix-purge-old-groups -If you create and kill a lot of @code{nnmairix} groups, the -``zz_mairix-*'' groups will accumulate on the mail back end server. To -delete old groups which are no longer needed, call -@code{nnmairix-purge-old-groups}. Note that this assumes that you don't -save any ``real'' mail in folders of the form -@code{zz_mairix--}. You can change the prefix of -@code{nnmairix} groups by changing the variable -@code{nnmairix-group-prefix}. - -@item -The following only applies if you @emph{don't} use the mentioned patch -for mairix (@pxref{Propagating marks}): - -A problem can occur when using @code{nnmairix} with maildir folders and -comes with the fact that maildir stores mail flags like @samp{Seen} or -@samp{Replied} by appending chars @samp{S} and @samp{R} to the message -file name, respectively. This implies that currently you would have to -update the mairix database not only when new mail arrives, but also when -mail flags are changing. The same applies to new mails which are indexed -while they are still in the @samp{new} folder but then get moved to -@samp{cur} when Gnus has seen the mail. If you don't update the database -after this has happened, a mairix query can lead to symlinks pointing to -non-existing files. In Gnus, these messages will usually appear with -``(none)'' entries in the header and can't be accessed. If this happens -to you, using @kbd{G b u} and updating the group will usually fix this. - -@end itemize - -@node Misc Group Stuff -@section Misc Group Stuff - -@menu -* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. -* Group Information:: Information and help on groups and Gnus. -* Group Timestamp:: Making Gnus keep track of when you last read a group. -* File Commands:: Reading and writing the Gnus files. -* Sieve Commands:: Managing Sieve scripts. -@end menu - -@table @kbd - -@item v -@kindex v (Group) -@cindex keys, reserved for users (Group) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: - -@lisp -(define-key gnus-group-mode-map (kbd "v j d") - (lambda () - (interactive) - (gnus-group-jump-to-group "nndraft:drafts"))) -@end lisp - -On keys reserved for users in Emacs and on keybindings in general -@xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. - -@item ^ -@kindex ^ (Group) -@findex gnus-group-enter-server-mode -Enter the server buffer (@code{gnus-group-enter-server-mode}). -@xref{Server Buffer}. - -@item a -@kindex a (Group) -@findex gnus-group-post-news -Start composing a message (a news by default) -(@code{gnus-group-post-news}). If given a prefix, post to the group -under the point. If the prefix is 1, prompt for a group to post to. -Contrary to what the name of this function suggests, the prepared -article might be a mail instead of a news, if a mail group is specified -with the prefix argument. @xref{Composing Messages}. - -@item m -@kindex m (Group) -@findex gnus-group-mail -Mail a message somewhere (@code{gnus-group-mail}). If given a prefix, -use the posting style of the group under the point. If the prefix is 1, -prompt for a group name to find the posting style. -@xref{Composing Messages}. - -@item i -@kindex i (Group) -@findex gnus-group-news -Start composing a news (@code{gnus-group-news}). If given a prefix, -post to the group under the point. If the prefix is 1, prompt -for group to post to. @xref{Composing Messages}. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item G z -@kindex G z (Group) -@findex gnus-group-compact-group - -Compact the group under point (@code{gnus-group-compact-group}). -Currently implemented only in nnml (@pxref{Mail Spool}). This removes -gaps between article numbers, hence getting a correct total article -count. - -@end table - -Variables for the group buffer: - -@table @code - -@item gnus-group-mode-hook -@vindex gnus-group-mode-hook -is called after the group buffer has been -created. - -@item gnus-group-prepare-hook -@vindex gnus-group-prepare-hook -is called after the group buffer is -generated. It may be used to modify the buffer in some strange, -unnatural way. - -@item gnus-group-prepared-hook -@vindex gnus-group-prepare-hook -is called as the very last thing after the group buffer has been -generated. It may be used to move point around, for instance. - -@item gnus-permanently-visible-groups -@vindex gnus-permanently-visible-groups -Groups matching this regexp will always be listed in the group buffer, -whether they are empty or not. - -@end table - -@node Scanning New Messages -@subsection Scanning New Messages -@cindex new messages -@cindex scanning new news - -@table @kbd - -@item g -@kindex g (Group) -@findex gnus-group-get-new-news -@c @icon{gnus-group-get-new-news} -Check the server(s) for new articles. If the numerical prefix is used, -this command will check only groups of level @var{arg} and lower -(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this -command will force a total re-reading of the active file(s) from the -back end(s). - -@item M-g -@kindex M-g (Group) -@findex gnus-group-get-new-news-this-group -@vindex gnus-goto-next-group-when-activating -@c @icon{gnus-group-get-new-news-this-group} -Check whether new articles have arrived in the current group -(@code{gnus-group-get-new-news-this-group}). -@code{gnus-goto-next-group-when-activating} says whether this command is -to move point to the next group or not. It is @code{t} by default. - -@findex gnus-activate-all-groups -@cindex activating groups -@item C-c M-g -@kindex C-c M-g (Group) -Activate absolutely all groups (@code{gnus-activate-all-groups}). - -@item R -@kindex R (Group) -@cindex restarting -@findex gnus-group-restart -Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} -file(s), closes the connection to all servers, clears up all run-time -Gnus variables, and then starts Gnus all over again. - -@end table - -@vindex gnus-get-new-news-hook -@code{gnus-get-new-news-hook} is run just before checking for new news. - -@vindex gnus-after-getting-new-news-hook -@code{gnus-after-getting-new-news-hook} is run after checking for new -news. - - -@node Group Information -@subsection Group Information -@cindex group information -@cindex information on groups - -@table @kbd - - -@item H f -@kindex H f (Group) -@findex gnus-group-fetch-faq -@vindex gnus-group-faq-directory -@cindex FAQ -@cindex ange-ftp -Try to fetch the @acronym{FAQ} for the current group -(@code{gnus-group-fetch-faq}). Gnus will try to get the @acronym{FAQ} -from @code{gnus-group-faq-directory}, which is usually a directory on -a remote machine. This variable can also be a list of directories. -In that case, giving a prefix to this command will allow you to choose -between the various sites. @code{ange-ftp} (or @code{efs}) will be -used for fetching the file. - -If fetching from the first site is unsuccessful, Gnus will attempt to go -through @code{gnus-group-faq-directory} and try to open them one by one. - -@item H c -@kindex H c (Group) -@findex gnus-group-fetch-charter -@vindex gnus-group-charter-alist -@cindex charter -Try to open the charter for the current group in a web browser -(@code{gnus-group-fetch-charter}). Query for a group if given a -prefix argument. - -Gnus will use @code{gnus-group-charter-alist} to find the location of -the charter. If no location is known, Gnus will fetch the control -messages for the group, which in some cases includes the charter. - -@item H C -@kindex H C (Group) -@findex gnus-group-fetch-control -@vindex gnus-group-fetch-control-use-browse-url -@cindex control message -Fetch the control messages for the group from the archive at -@code{ftp.isc.org} (@code{gnus-group-fetch-control}). Query for a -group if given a prefix argument. - -If @code{gnus-group-fetch-control-use-browse-url} is non-@code{nil}, -Gnus will open the control messages in a browser using -@code{browse-url}. Otherwise they are fetched using @code{ange-ftp} -and displayed in an ephemeral group. - -Note that the control messages are compressed. To use this command -you need to turn on @code{auto-compression-mode} (@pxref{Compressed -Files, ,Compressed Files, emacs, The Emacs Manual}). - -@item H d -@itemx C-c C-d -@c @icon{gnus-group-describe-group} -@kindex H d (Group) -@kindex C-c C-d (Group) -@cindex describing groups -@cindex group description -@findex gnus-group-describe-group -Describe the current group (@code{gnus-group-describe-group}). If given -a prefix, force Gnus to re-read the description from the server. - -@item M-d -@kindex M-d (Group) -@findex gnus-group-describe-all-groups -Describe all groups (@code{gnus-group-describe-all-groups}). If given a -prefix, force Gnus to re-read the description file from the server. - -@item H v -@itemx V -@kindex V (Group) -@kindex H v (Group) -@cindex version -@findex gnus-version -Display current Gnus version numbers (@code{gnus-version}). - -@item ? -@kindex ? (Group) -@findex gnus-group-describe-briefly -Give a very short help message (@code{gnus-group-describe-briefly}). - -@item C-c C-i -@kindex C-c C-i (Group) -@cindex info -@cindex manual -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Group Timestamp -@subsection Group Timestamp -@cindex timestamps -@cindex group timestamps - -It can be convenient to let Gnus keep track of when you last read a -group. To set the ball rolling, you should add -@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: - -@lisp -(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) -@end lisp - -After doing this, each time you enter a group, it'll be recorded. - -This information can be displayed in various ways---the easiest is to -use the @samp{%d} spec in the group line format: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") -@end lisp - -This will result in lines looking like: - -@example -* 0: mail.ding 19961002T012943 - 0: custom 19961002T012713 -@end example - -As you can see, the date is displayed in compact ISO 8601 format. This -may be a bit too much, so to just display the date, you could say -something like: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") -@end lisp - -If you would like greater control of the time format, you can use a -user-defined format spec. Something like the following should do the -trick: - -@lisp -(setq gnus-group-line-format - "%M\%S\%p\%P\%5y: %(%-40,40g%) %ud\n") -(defun gnus-user-format-function-d (headers) - (let ((time (gnus-group-timestamp gnus-tmp-group))) - (if time - (format-time-string "%b %d %H:%M" time) - ""))) -@end lisp - - -@node File Commands -@subsection File Commands -@cindex file commands - -@table @kbd - -@item r -@kindex r (Group) -@findex gnus-group-read-init-file -@vindex gnus-init-file -@cindex reading init file -Re-read the init file (@code{gnus-init-file}, which defaults to -@file{~/.gnus.el}) (@code{gnus-group-read-init-file}). - -@item s -@kindex s (Group) -@findex gnus-group-save-newsrc -@cindex saving .newsrc -Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) -(@code{gnus-group-save-newsrc}). If given a prefix, force saving the -file(s) whether Gnus thinks it is necessary or not. - -@c @item Z -@c @kindex Z (Group) -@c @findex gnus-group-clear-dribble -@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). - -@end table - - -@node Sieve Commands -@subsection Sieve Commands -@cindex group sieve commands - -Sieve is a server-side mail filtering language. In Gnus you can use -the @code{sieve} group parameter (@pxref{Group Parameters}) to specify -sieve rules that should apply to each group. Gnus provides two -commands to translate all these group parameters into a proper Sieve -script that can be transfered to the server somehow. - -@vindex gnus-sieve-file -@vindex gnus-sieve-region-start -@vindex gnus-sieve-region-end -The generated Sieve script is placed in @code{gnus-sieve-file} (by -default @file{~/.sieve}). The Sieve code that Gnus generate is placed -between two delimiters, @code{gnus-sieve-region-start} and -@code{gnus-sieve-region-end}, so you may write additional Sieve code -outside these delimiters that will not be removed the next time you -regenerate the Sieve script. - -@vindex gnus-sieve-crosspost -The variable @code{gnus-sieve-crosspost} controls how the Sieve script -is generated. If it is non-@code{nil} (the default) articles is -placed in all groups that have matching rules, otherwise the article -is only placed in the group with the first matching rule. For -example, the group parameter @samp{(sieve address "sender" -"owner-ding@@hpc.uh.edu")} will generate the following piece of Sieve -code if @code{gnus-sieve-crosspost} is @code{nil}. (When -@code{gnus-sieve-crosspost} is non-@code{nil}, it looks the same -except that the line containing the call to @code{stop} is removed.) - -@example -if address "sender" "owner-ding@@hpc.uh.edu" @{ - fileinto "INBOX.ding"; - stop; -@} -@end example - -@xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. - -@table @kbd - -@item D g -@kindex D g (Group) -@findex gnus-sieve-generate -@vindex gnus-sieve-file -@cindex generating sieve script -Regenerate a Sieve script from the @code{sieve} group parameters and -put you into the @code{gnus-sieve-file} without saving it. - -@item D u -@kindex D u (Group) -@findex gnus-sieve-update -@vindex gnus-sieve-file -@cindex updating sieve script -Regenerates the Gnus managed part of @code{gnus-sieve-file} using the -@code{sieve} group parameters, save the file and upload it to the -server using the @code{sieveshell} program. - -@end table - - -@node Summary Buffer -@chapter Summary Buffer -@cindex summary buffer - -A line for each article is displayed in the summary buffer. You can -move around, read articles, post articles and reply to articles. - -The most common way to a summary buffer is to select a group from the -group buffer (@pxref{Selecting a Group}). - -You can have as many summary buffers open as you wish. - -You can customize the Summary Mode tool bar, see @kbd{M-x -customize-apropos RET gnus-summary-tool-bar}. This feature is only -available in Emacs. - -@kindex v (Summary) -@cindex keys, reserved for users (Summary) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. For example: -@lisp -(define-key gnus-summary-mode-map (kbd "v -") "LrS") ;; lower subthread -@end lisp - -@menu -* Summary Buffer Format:: Deciding how the summary buffer is to look. -* Summary Maneuvering:: Moving around the summary buffer. -* Choosing Articles:: Reading articles. -* Paging the Article:: Scrolling the current article. -* Reply Followup and Post:: Posting articles. -* Delayed Articles:: Send articles at a later time. -* Marking Articles:: Marking articles as read, expirable, etc. -* Limiting:: You can limit the summary buffer. -* Threading:: How threads are made. -* Sorting the Summary Buffer:: How articles and threads are sorted. -* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. -* Article Caching:: You may store articles in a cache. -* Persistent Articles:: Making articles expiry-resistant. -* Sticky Articles:: Article buffers that are not reused. -* Article Backlog:: Having already read articles hang around. -* Saving Articles:: Ways of customizing article saving. -* Decoding Articles:: Gnus can treat series of (uu)encoded articles. -* Article Treatment:: The article buffer can be mangled at will. -* MIME Commands:: Doing MIMEy things with the articles. -* Charsets:: Character set issues. -* Article Commands:: Doing various things with the article buffer. -* Summary Sorting:: Sorting the summary buffer in various ways. -* Finding the Parent:: No child support? Get the parent. -* Alternative Approaches:: Reading using non-default summaries. -* Tree Display:: A more visual display of threads. -* Mail Group Commands:: Some commands can only be used in mail groups. -* Various Summary Stuff:: What didn't fit anywhere else. -* Exiting the Summary Buffer:: Returning to the Group buffer, - or reselecting the current group. -* Crosspost Handling:: How crossposted articles are dealt with. -* Duplicate Suppression:: An alternative when crosspost handling fails. -* Security:: Decrypt and Verify. -* Mailing List:: Mailing list minor mode. -@end menu - - -@node Summary Buffer Format -@section Summary Buffer Format -@cindex summary buffer format - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{180}{ -\put(0,0){\epsfig{figure=ps/summary,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-article,width=7.5cm}}} -} -@end iflatex -@end iftex - -@menu -* Summary Buffer Lines:: You can specify how summary lines should look. -* To From Newsgroups:: How to not display your own name. -* Summary Buffer Mode Line:: You can say how the mode line should look. -* Summary Highlighting:: Making the summary buffer all pretty and nice. -@end menu - -@findex mail-extract-address-components -@findex gnus-extract-address-components -@vindex gnus-extract-address-components -Gnus will use the value of the @code{gnus-extract-address-components} -variable as a function for getting the name and address parts of a -@code{From} header. Two pre-defined functions exist: -@code{gnus-extract-address-components}, which is the default, quite -fast, and too simplistic solution; and -@code{mail-extract-address-components}, which works very nicely, but is -slower. The default function will return the wrong answer in 5% of the -cases. If this is unacceptable to you, use the other function instead: - -@lisp -(setq gnus-extract-address-components - 'mail-extract-address-components) -@end lisp - -@vindex gnus-summary-same-subject -@code{gnus-summary-same-subject} is a string indicating that the current -article has the same subject as the previous. This string will be used -with those specs that require it. The default is @code{""}. - - -@node Summary Buffer Lines -@subsection Summary Buffer Lines - -@vindex gnus-summary-line-format -You can change the format of the lines in the summary buffer by changing -the @code{gnus-summary-line-format} variable. It works along the same -lines as a normal @code{format} string, with some extensions -(@pxref{Formatting Variables}). - -There should always be a colon or a point position marker on the line; -the cursor always moves to the point position marker or the colon after -performing an operation. (Of course, Gnus wouldn't be Gnus if it wasn't -possible to change this. Just write a new function -@code{gnus-goto-colon} which does whatever you like with the cursor.) -@xref{Positioning Point}. - -The default string is @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n}. - -The following format specification characters and extended format -specification(s) are understood: - -@table @samp -@item N -Article number. -@item S -Subject string. List identifiers stripped, -@code{gnus-list-identifiers}. @xref{Article Hiding}. -@item s -Subject if the article is the root of the thread or the previous article -had a different subject, @code{gnus-summary-same-subject} otherwise. -(@code{gnus-summary-same-subject} defaults to @code{""}.) -@item F -Full @code{From} header. -@item n -The name (from the @code{From} header). -@item f -The name, @code{To} header or the @code{Newsgroups} header (@pxref{To -From Newsgroups}). -@item a -The name (from the @code{From} header). This differs from the @code{n} -spec in that it uses the function designated by the -@code{gnus-extract-address-components} variable, which is slower, but -may be more thorough. -@item A -The address (from the @code{From} header). This works the same way as -the @code{a} spec. -@item L -Number of lines in the article. -@item c -Number of characters in the article. This specifier is not supported -in some methods (like nnfolder). -@item k -Pretty-printed version of the number of characters in the article; -for example, @samp{1.2k} or @samp{0.4M}. -@item I -Indentation based on thread level (@pxref{Customizing Threading}). -@item B -A complex trn-style thread tree, showing response-connecting trace -lines. A thread could be drawn like this: - -@example -> -+-> -| +-> -| | \-> -| | \-> -| \-> -+-> -\-> -@end example - -You can customize the appearance with the following options. Note -that it is possible to make the thread display look really neat by -replacing the default @acronym{ASCII} characters with graphic -line-drawing glyphs. -@table @code -@item gnus-sum-thread-tree-root -@vindex gnus-sum-thread-tree-root -Used for the root of a thread. If @code{nil}, use subject -instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-false-root -@vindex gnus-sum-thread-tree-false-root -Used for the false root of a thread (@pxref{Loose Threads}). If -@code{nil}, use subject instead. The default is @samp{> }. - -@item gnus-sum-thread-tree-single-indent -@vindex gnus-sum-thread-tree-single-indent -Used for a thread with just one message. If @code{nil}, use subject -instead. The default is @samp{}. - -@item gnus-sum-thread-tree-vertical -@vindex gnus-sum-thread-tree-vertical -Used for drawing a vertical line. The default is @samp{| }. - -@item gnus-sum-thread-tree-indent -@vindex gnus-sum-thread-tree-indent -Used for indenting. The default is @samp{ }. - -@item gnus-sum-thread-tree-leaf-with-other -@vindex gnus-sum-thread-tree-leaf-with-other -Used for a leaf with brothers. The default is @samp{+-> }. - -@item gnus-sum-thread-tree-single-leaf -@vindex gnus-sum-thread-tree-single-leaf -Used for a leaf without brothers. The default is @samp{\-> } - -@end table - -@item T -Nothing if the article is a root and lots of spaces if it isn't (it -pushes everything after it off the screen). -@item [ -Opening bracket, which is normally @samp{[}, but can also be @samp{<} -for adopted articles (@pxref{Customizing Threading}). -@item ] -Closing bracket, which is normally @samp{]}, but can also be @samp{>} -for adopted articles. -@item > -One space for each thread level. -@item < -Twenty minus thread level spaces. -@item U -Unread. @xref{Read Articles}. - -@item R -This misleadingly named specifier is the @dfn{secondary mark}. This -mark will say whether the article has been replied to, has been cached, -or has been saved. @xref{Other Marks}. - -@item i -Score as a number (@pxref{Scoring}). -@item z -@vindex gnus-summary-zcore-fuzz -Zcore, @samp{+} if above the default level and @samp{-} if below the -default level. If the difference between -@code{gnus-summary-default-score} and the score is less than -@code{gnus-summary-zcore-fuzz}, this spec will not be used. -@item V -Total thread score. -@item x -@code{Xref}. -@item D -@code{Date}. -@item d -The @code{Date} in @code{DD-MMM} format. -@item o -The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. -@item M -@code{Message-ID}. -@item r -@code{References}. -@item t -Number of articles in the current sub-thread. Using this spec will slow -down summary buffer generation somewhat. -@item e -An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the -article has any children. -@item P -The line number. -@item O -Download mark. -@item * -Desired cursor position (instead of after first colon). -@item &user-date; -Age sensitive date format. Various date format is defined in -@code{gnus-user-date-format-alist}. -@item u -User defined specifier. The next character in the format string should -be a letter. Gnus will call the function -@code{gnus-user-format-function-@var{x}}, where @var{x} is the letter -following @samp{%u}. The function will be passed the current header as -argument. The function should return a string, which will be inserted -into the summary just like information from any other summary specifier. -@end table - -Text between @samp{%(} and @samp{%)} will be highlighted with -@code{gnus-mouse-face} when the mouse point is placed inside the area. -There can only be one such area. - -The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs -have to be handled with care. For reasons of efficiency, Gnus will -compute what column these characters will end up in, and ``hard-code'' -that. This means that it is invalid to have these specs after a -variable-length spec. Well, you might not be arrested, but your summary -buffer will look strange, which is bad enough. - -The smart choice is to have these specs as far to the left as possible. -(Isn't that the case with everything, though? But I digress.) - -This restriction may disappear in later versions of Gnus. - - -@node To From Newsgroups -@subsection To From Newsgroups -@cindex To -@cindex Newsgroups - -In some groups (particularly in archive groups), the @code{From} header -isn't very interesting, since all the articles there are written by -you. To display the information in the @code{To} or @code{Newsgroups} -headers instead, you need to decide three things: What information to -gather; where to display it; and when to display it. - -@enumerate -@item -@vindex gnus-extra-headers -The reading of extra header information is controlled by the -@code{gnus-extra-headers}. This is a list of header symbols. For -instance: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups X-Newsreader)) -@end lisp - -This will result in Gnus trying to obtain these three headers, and -storing it in header structures for later easy retrieval. - -@item -@findex gnus-extra-header -The value of these extra headers can be accessed via the -@code{gnus-extra-header} function. Here's a format line spec that will -access the @code{X-Newsreader} header: - -@example -"%~(form (gnus-extra-header 'X-Newsreader))@@" -@end example - -@item -@vindex gnus-ignored-from-addresses -The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} -summary line spec returns the @code{To}, @code{Newsreader} or -@code{From} header. If this regexp matches the contents of the -@code{From} header, the value of the @code{To} or @code{Newsreader} -headers are used instead. - -To distinguish regular articles from those where the @code{From} field -has been swapped, a string is prefixed to the @code{To} or -@code{Newsgroups} header in the summary line. By default the string is -@samp{-> } for @code{To} and @samp{=> } for @code{Newsgroups}, you can -customize these strings with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. - -@end enumerate - -@vindex nnmail-extra-headers -A related variable is @code{nnmail-extra-headers}, which controls when -to include extra headers when generating overview (@acronym{NOV}) files. -If you have old overview files, you should regenerate them after -changing this variable, by entering the server buffer using @kbd{^}, -and then @kbd{g} on the appropriate mail server (e.g. nnml) to cause -regeneration. - -@vindex gnus-summary-line-format -You also have to instruct Gnus to display the data by changing the -@code{%n} spec to the @code{%f} spec in the -@code{gnus-summary-line-format} variable. - -In summary, you'd typically put something like the following in -@file{~/.gnus.el}: - -@lisp -(setq gnus-extra-headers - '(To Newsgroups)) -(setq nnmail-extra-headers gnus-extra-headers) -(setq gnus-summary-line-format - "%U%R%z%I%(%[%4L: %-23,23f%]%) %s\n") -(setq gnus-ignored-from-addresses - "Your Name Here") -@end lisp - -(The values listed above are the default values in Gnus. Alter them -to fit your needs.) - -A note for news server administrators, or for users who wish to try to -convince their news server administrator to provide some additional -support: - -The above is mostly useful for mail groups, where you have control over -the @acronym{NOV} files that are created. However, if you can persuade your -nntp admin to add (in the usual implementation, notably INN): - -@example -Newsgroups:full -@end example - -to the end of her @file{overview.fmt} file, then you can use that just -as you would the extra headers from the mail groups. - - -@node Summary Buffer Mode Line -@subsection Summary Buffer Mode Line - -@vindex gnus-summary-mode-line-format -You can also change the format of the summary mode bar (@pxref{Mode Line -Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you -like. The default is @samp{Gnus: %%b [%A] %Z}. - -Here are the elements you can play with: - -@table @samp -@item G -Group name. -@item p -Unprefixed group name. -@item A -Current article number. -@item z -Current article score. -@item V -Gnus version. -@item U -Number of unread articles in this group. -@item e -Number of unread articles in this group that aren't displayed in the -summary buffer. -@item Z -A string with the number of unread and unselected articles represented -either as @samp{<%U(+%e) more>} if there are both unread and unselected -articles, and just as @samp{<%U more>} if there are just unread articles -and no unselected ones. -@item g -Shortish group name. For instance, @samp{rec.arts.anime} will be -shortened to @samp{r.a.anime}. -@item S -Subject of the current article. -@item u -User-defined spec (@pxref{User-Defined Specs}). -@item s -Name of the current score file (@pxref{Scoring}). -@item d -Number of dormant articles (@pxref{Unread Articles}). -@item t -Number of ticked articles (@pxref{Unread Articles}). -@item r -Number of articles that have been marked as read in this session. -@item E -Number of articles expunged by the score files. -@end table - - -@node Summary Highlighting -@subsection Summary Highlighting - -@table @code - -@item gnus-visual-mark-article-hook -@vindex gnus-visual-mark-article-hook -This hook is run after selecting an article. It is meant to be used for -highlighting the article in some way. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-update-hook -@vindex gnus-summary-update-hook -This hook is called when a summary line is changed. It is not run if -@code{gnus-visual} is @code{nil}. - -@item gnus-summary-selected-face -@vindex gnus-summary-selected-face -This is the face (or @dfn{font} as some people call it) used to -highlight the current article in the summary buffer. - -@item gnus-summary-highlight -@vindex gnus-summary-highlight -Summary lines are highlighted according to this variable, which is a -list where the elements are of the format @code{(@var{form} -. @var{face})}. If you would, for instance, like ticked articles to be -italic and high-scored articles to be bold, you could set this variable -to something like -@lisp -(((eq mark gnus-ticked-mark) . italic) - ((> score default) . bold)) -@end lisp -As you may have guessed, if @var{form} returns a non-@code{nil} value, -@var{face} will be applied to the line. -@end table - - -@node Summary Maneuvering -@section Summary Maneuvering -@cindex summary movement - -All the straight movement commands understand the numeric prefix and -behave pretty much as you'd expect. - -None of these commands select articles. - -@table @kbd -@item G M-n -@itemx M-n -@kindex M-n (Summary) -@kindex G M-n (Summary) -@findex gnus-summary-next-unread-subject -Go to the next summary line of an unread article -(@code{gnus-summary-next-unread-subject}). - -@item G M-p -@itemx M-p -@kindex M-p (Summary) -@kindex G M-p (Summary) -@findex gnus-summary-prev-unread-subject -Go to the previous summary line of an unread article -(@code{gnus-summary-prev-unread-subject}). - -@item G g -@kindex G g (Summary) -@findex gnus-summary-goto-subject -Ask for an article number and then go to the summary line of that article -without displaying the article (@code{gnus-summary-goto-subject}). -@end table - -If Gnus asks you to press a key to confirm going to the next group, you -can use the @kbd{C-n} and @kbd{C-p} keys to move around the group -buffer, searching for the next group to read without actually returning -to the group buffer. - -Variables related to summary movement: - -@table @code - -@vindex gnus-auto-select-next -@item gnus-auto-select-next -If you issue one of the movement commands (like @kbd{n}) and there are -no more unread articles after the current one, Gnus will offer to go to -the next group. If this variable is @code{t} and the next group is -empty, Gnus will exit summary mode and return to the group buffer. If -this variable is neither @code{t} nor @code{nil}, Gnus will select the -next group with unread articles. As a special case, if this variable -is @code{quietly}, Gnus will select the next group without asking for -confirmation. If this variable is @code{almost-quietly}, the same -will happen only if you are located on the last article in the group. -Finally, if this variable is @code{slightly-quietly}, the @kbd{Z n} -command will go to the next group without confirmation. Also -@pxref{Group Levels}. - -@item gnus-auto-select-same -@vindex gnus-auto-select-same -If non-@code{nil}, all the movement commands will try to go to the next -article with the same subject as the current. (@dfn{Same} here might -mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} -for details (@pxref{Customizing Threading}).) If there are no more -articles with the same subject, go to the first unread article. - -This variable is not particularly useful if you use a threaded display. - -@item gnus-summary-check-current -@vindex gnus-summary-check-current -If non-@code{nil}, all the ``unread'' movement commands will not proceed -to the next (or previous) article if the current article is unread. -Instead, they will choose the current article. - -@item gnus-auto-center-summary -@vindex gnus-auto-center-summary -If non-@code{nil}, Gnus will keep the point in the summary buffer -centered at all times. This makes things quite tidy, but if you have a -slow network connection, or simply do not like this un-Emacsism, you can -set this variable to @code{nil} to get the normal Emacs scrolling -action. This will also inhibit horizontal re-centering of the summary -buffer, which might make it more inconvenient to read extremely long -threads. - -This variable can also be a number. In that case, center the window at -the given number of lines from the top. - -@end table - - -@node Choosing Articles -@section Choosing Articles -@cindex selecting articles - -@menu -* Choosing Commands:: Commands for choosing articles. -* Choosing Variables:: Variables that influence these commands. -@end menu - - -@node Choosing Commands -@subsection Choosing Commands - -None of the following movement commands understand the numeric prefix, -and they all select and display an article. - -If you want to fetch new articles or redisplay the group, see -@ref{Exiting the Summary Buffer}. - -@table @kbd -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Select the current article, or, if that one's read already, the next -unread article (@code{gnus-summary-next-page}). - -If you have an article window open already and you press @kbd{SPACE} -again, the article will be scrolled. This lets you conveniently -@kbd{SPACE} through an entire newsgroup. @xref{Paging the Article}. - -@item G n -@itemx n -@kindex n (Summary) -@kindex G n (Summary) -@findex gnus-summary-next-unread-article -@c @icon{gnus-summary-next-unread} -Go to next unread article (@code{gnus-summary-next-unread-article}). - -@item G p -@itemx p -@kindex p (Summary) -@findex gnus-summary-prev-unread-article -@c @icon{gnus-summary-prev-unread} -Go to previous unread article (@code{gnus-summary-prev-unread-article}). - -@item G N -@itemx N -@kindex N (Summary) -@kindex G N (Summary) -@findex gnus-summary-next-article -Go to the next article (@code{gnus-summary-next-article}). - -@item G P -@itemx P -@kindex P (Summary) -@kindex G P (Summary) -@findex gnus-summary-prev-article -Go to the previous article (@code{gnus-summary-prev-article}). - -@item G C-n -@kindex G C-n (Summary) -@findex gnus-summary-next-same-subject -Go to the next article with the same subject -(@code{gnus-summary-next-same-subject}). - -@item G C-p -@kindex G C-p (Summary) -@findex gnus-summary-prev-same-subject -Go to the previous article with the same subject -(@code{gnus-summary-prev-same-subject}). - -@item G f -@itemx . -@kindex G f (Summary) -@kindex . (Summary) -@findex gnus-summary-first-unread-article -Go to the first unread article -(@code{gnus-summary-first-unread-article}). - -@item G b -@itemx , -@kindex G b (Summary) -@kindex , (Summary) -@findex gnus-summary-best-unread-article -Go to the unread article with the highest score -(@code{gnus-summary-best-unread-article}). If given a prefix argument, -go to the first unread article that has a score over the default score. - -@item G l -@itemx l -@kindex l (Summary) -@kindex G l (Summary) -@findex gnus-summary-goto-last-article -Go to the previous article read (@code{gnus-summary-goto-last-article}). - -@item G o -@kindex G o (Summary) -@findex gnus-summary-pop-article -@cindex history -@cindex article history -Pop an article off the summary history and go to this article -(@code{gnus-summary-pop-article}). This command differs from the -command above in that you can pop as many previous articles off the -history as you like, while @kbd{l} toggles the two last read articles. -For a somewhat related issue (if you use these commands a lot), -@pxref{Article Backlog}. - -@item G j -@itemx j -@kindex j (Summary) -@kindex G j (Summary) -@findex gnus-summary-goto-article -Ask for an article number or @code{Message-ID}, and then go to that -article (@code{gnus-summary-goto-article}). - -@end table - - -@node Choosing Variables -@subsection Choosing Variables - -Some variables relevant for moving and selecting articles: - -@table @code -@item gnus-auto-extend-newsgroup -@vindex gnus-auto-extend-newsgroup -All the movement commands will try to go to the previous (or next) -article, even if that article isn't displayed in the Summary buffer if -this variable is non-@code{nil}. Gnus will then fetch the article from -the server and display it in the article buffer. - -@item gnus-select-article-hook -@vindex gnus-select-article-hook -This hook is called whenever an article is selected. The default is -@code{nil}. If you would like each article to be saved in the Agent as -you read it, putting @code{gnus-agent-fetch-selected-article} on this -hook will do so. - -@item gnus-mark-article-hook -@vindex gnus-mark-article-hook -@findex gnus-summary-mark-unread-as-read -@findex gnus-summary-mark-read-and-unread-as-read -@findex gnus-unread-mark -This hook is called whenever an article is selected. It is intended to -be used for marking articles as read. The default value is -@code{gnus-summary-mark-read-and-unread-as-read}, and will change the -mark of almost any article you read to @code{gnus-read-mark}. The only -articles not affected by this function are ticked, dormant, and -expirable articles. If you'd instead like to just have unread articles -marked as read, you can use @code{gnus-summary-mark-unread-as-read} -instead. It will leave marks like @code{gnus-low-score-mark}, -@code{gnus-del-mark} (and so on) alone. - -@end table - - -@node Paging the Article -@section Scrolling the Article -@cindex article scrolling - -@table @kbd - -@item SPACE -@kindex SPACE (Summary) -@findex gnus-summary-next-page -Pressing @kbd{SPACE} will scroll the current article forward one page, -or, if you have come to the end of the current article, will choose the -next article (@code{gnus-summary-next-page}). - -@vindex gnus-article-boring-faces -@vindex gnus-article-skip-boring -If @code{gnus-article-skip-boring} is non-@code{nil} and the rest of -the article consists only of citations and signature, then it will be -skipped; the next article will be shown instead. You can customize -what is considered uninteresting with -@code{gnus-article-boring-faces}. You can manually view the article's -pages, no matter how boring, using @kbd{C-M-v}. - -@item DEL -@kindex DEL (Summary) -@findex gnus-summary-prev-page -Scroll the current article back one page (@code{gnus-summary-prev-page}). - -@item RET -@kindex RET (Summary) -@findex gnus-summary-scroll-up -Scroll the current article one line forward -(@code{gnus-summary-scroll-up}). - -@item M-RET -@kindex M-RET (Summary) -@findex gnus-summary-scroll-down -Scroll the current article one line backward -(@code{gnus-summary-scroll-down}). - -@item A g -@itemx g -@kindex A g (Summary) -@kindex g (Summary) -@findex gnus-summary-show-article -@vindex gnus-summary-show-article-charset-alist -(Re)fetch the current article (@code{gnus-summary-show-article}). If -given a prefix, fetch the current article, but don't run any of the -article treatment functions. This will give you a ``raw'' article, just -the way it came from the server. - -@cindex charset, view article with different charset -If given a numerical prefix, you can do semi-manual charset stuff. -@kbd{C-u 0 g cn-gb-2312 RET} will decode the message as if it were -encoded in the @code{cn-gb-2312} charset. If you have - -@lisp -(setq gnus-summary-show-article-charset-alist - '((1 . cn-gb-2312) - (2 . big5))) -@end lisp - -then you can say @kbd{C-u 1 g} to get the same effect. - -@item A < -@itemx < -@kindex < (Summary) -@kindex A < (Summary) -@findex gnus-summary-beginning-of-article -Scroll to the beginning of the article -(@code{gnus-summary-beginning-of-article}). - -@item A > -@itemx > -@kindex > (Summary) -@kindex A > (Summary) -@findex gnus-summary-end-of-article -Scroll to the end of the article (@code{gnus-summary-end-of-article}). - -@item A s -@itemx s -@kindex A s (Summary) -@kindex s (Summary) -@findex gnus-summary-isearch-article -Perform an isearch in the article buffer -(@code{gnus-summary-isearch-article}). - -@item h -@kindex h (Summary) -@findex gnus-summary-select-article-buffer -Select the article buffer (@code{gnus-summary-select-article-buffer}). - -@end table - - -@node Reply Followup and Post -@section Reply, Followup and Post - -@menu -* Summary Mail Commands:: Sending mail. -* Summary Post Commands:: Sending news. -* Summary Message Commands:: Other Message-related commands. -* Canceling and Superseding:: -@end menu - - -@node Summary Mail Commands -@subsection Summary Mail Commands -@cindex mail -@cindex composing mail - -Commands for composing a mail message: - -@table @kbd - -@item S r -@itemx r -@kindex S r (Summary) -@kindex r (Summary) -@findex gnus-summary-reply -@c @icon{gnus-summary-mail-reply} -@c @icon{gnus-summary-reply} -Mail a reply to the author of the current article -(@code{gnus-summary-reply}). - -@item S R -@itemx R -@kindex R (Summary) -@kindex S R (Summary) -@findex gnus-summary-reply-with-original -@c @icon{gnus-summary-reply-with-original} -Mail a reply to the author of the current article and include the -original message (@code{gnus-summary-reply-with-original}). This -command uses the process/prefix convention. - -@item S w -@kindex S w (Summary) -@findex gnus-summary-wide-reply -Mail a wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that -goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is -present, that's used instead. - -@item S W -@kindex S W (Summary) -@findex gnus-summary-wide-reply-with-original -Mail a wide reply to the current article and include the original -message (@code{gnus-summary-wide-reply-with-original}). This command uses -the process/prefix convention. - -@item S v -@kindex S v (Summary) -@findex gnus-summary-very-wide-reply -Mail a very wide reply to the author of the current article -(@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply -that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed -articles. This command uses the process/prefix convention. - -@item S V -@kindex S V (Summary) -@findex gnus-summary-very-wide-reply-with-original -Mail a very wide reply to the author of the current article and include the -original message (@code{gnus-summary-very-wide-reply-with-original}). This -command uses the process/prefix convention. - -@item S B r -@kindex S B r (Summary) -@findex gnus-summary-reply-broken-reply-to -Mail a reply to the author of the current article but ignore the -@code{Reply-To} field (@code{gnus-summary-reply-broken-reply-to}). -If you need this because a mailing list incorrectly sets a -@code{Reply-To} header pointing to the list, you probably want to set -the @code{broken-reply-to} group parameter instead, so things will work -correctly. @xref{Group Parameters}. - -@item S B R -@kindex S B R (Summary) -@findex gnus-summary-reply-broken-reply-to-with-original -Mail a reply to the author of the current article and include the -original message but ignore the @code{Reply-To} field -(@code{gnus-summary-reply-broken-reply-to-with-original}). - -@item S o m -@itemx C-c C-f -@kindex S o m (Summary) -@kindex C-c C-f (Summary) -@findex gnus-summary-mail-forward -@c @icon{gnus-summary-mail-forward} -Forward the current article to some other person -(@code{gnus-summary-mail-forward}). If no prefix is given, the message -is forwarded according to the value of (@code{message-forward-as-mime}) -and (@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. - -@item S m -@itemx m -@kindex m (Summary) -@kindex S m (Summary) -@findex gnus-summary-mail-other-window -@c @icon{gnus-summary-mail-originate} -Prepare a mail (@code{gnus-summary-mail-other-window}). By default, use -the posting style of the current group. If given a prefix, disable that. -If the prefix is 1, prompt for a group name to find the posting style. - -@item S i -@itemx i -@kindex i (Summary) -@kindex S i (Summary) -@findex gnus-summary-news-other-window -Prepare a news (@code{gnus-summary-news-other-window}). By default, -post to the current group. If given a prefix, disable that. If the -prefix is 1, prompt for a group to post to. - -This function actually prepares a news even when using mail groups. -This is useful for ``posting'' messages to mail groups without actually -sending them over the network: they're just saved directly to the group -in question. The corresponding back end must have a request-post method -for this to work though. - -@item S D b -@kindex S D b (Summary) -@findex gnus-summary-resend-bounced-mail -@cindex bouncing mail -If you have sent a mail, but the mail was bounced back to you for some -reason (wrong address, transient failure), you can use this command to -resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You -will be popped into a mail buffer where you can edit the headers before -sending the mail off again. If you give a prefix to this command, and -the bounced mail is a reply to some other mail, Gnus will try to fetch -that mail and display it for easy perusal of its headers. This might -very well fail, though. - -@item S D r -@kindex S D r (Summary) -@findex gnus-summary-resend-message -Not to be confused with the previous command, -@code{gnus-summary-resend-message} will prompt you for an address to -send the current message off to, and then send it to that place. The -headers of the message won't be altered---but lots of headers that say -@code{Resent-To}, @code{Resent-From} and so on will be added. This -means that you actually send a mail to someone that has a @code{To} -header that (probably) points to yourself. This will confuse people. -So, natcherly you'll only do that if you're really eVIl. - -This command is mainly used if you have several accounts and want to -ship a mail to a different account of yours. (If you're both -@code{root} and @code{postmaster} and get a mail for @code{postmaster} -to the @code{root} account, you may want to resend it to -@code{postmaster}. Ordnung muss sein! - -This command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item S D e -@kindex S D e (Summary) -@findex gnus-summary-resend-message-edit - -Like the previous command, but will allow you to edit the message as -if it were a new message before resending. - -@item S O m -@kindex S O m (Summary) -@findex gnus-uu-digest-mail-forward -Digest the current series (@pxref{Decoding Articles}) and forward the -result using mail (@code{gnus-uu-digest-mail-forward}). This command -uses the process/prefix convention (@pxref{Process/Prefix}). - -@item S M-c -@kindex S M-c (Summary) -@findex gnus-summary-mail-crosspost-complaint -@cindex crossposting -@cindex excessive crossposting -Send a complaint about excessive crossposting to the author of the -current article (@code{gnus-summary-mail-crosspost-complaint}). - -@findex gnus-crosspost-complaint -This command is provided as a way to fight back against the current -crossposting pandemic that's sweeping Usenet. It will compose a reply -using the @code{gnus-crosspost-complaint} variable as a preamble. This -command understands the process/prefix convention -(@pxref{Process/Prefix}) and will prompt you before sending each mail. - -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Post Commands -@subsection Summary Post Commands -@cindex post -@cindex composing news - -Commands for posting a news article: - -@table @kbd -@item S p -@itemx a -@kindex a (Summary) -@kindex S p (Summary) -@findex gnus-summary-post-news -@c @icon{gnus-summary-post-news} -Prepare for posting an article (@code{gnus-summary-post-news}). By -default, post to the current group. If given a prefix, disable that. -If the prefix is 1, prompt for another group instead. - -@item S f -@itemx f -@kindex f (Summary) -@kindex S f (Summary) -@findex gnus-summary-followup -@c @icon{gnus-summary-followup} -Post a followup to the current article (@code{gnus-summary-followup}). - -@item S F -@itemx F -@kindex S F (Summary) -@kindex F (Summary) -@c @icon{gnus-summary-followup-with-original} -@findex gnus-summary-followup-with-original -Post a followup to the current article and include the original message -(@code{gnus-summary-followup-with-original}). This command uses the -process/prefix convention. - -@item S n -@kindex S n (Summary) -@findex gnus-summary-followup-to-mail -Post a followup to the current article via news, even if you got the -message through mail (@code{gnus-summary-followup-to-mail}). - -@item S N -@kindex S N (Summary) -@findex gnus-summary-followup-to-mail-with-original -Post a followup to the current article via news, even if you got the -message through mail and include the original message -(@code{gnus-summary-followup-to-mail-with-original}). This command uses -the process/prefix convention. - -@item S o p -@kindex S o p (Summary) -@findex gnus-summary-post-forward -Forward the current article to a newsgroup -(@code{gnus-summary-post-forward}). - If no prefix is given, the message is forwarded according to the value -of (@code{message-forward-as-mime}) and -(@code{message-forward-show-mml}); if the prefix is 1, decode the -message and forward directly inline; if the prefix is 2, forward message -as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and -forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message -directly inline; otherwise, the message is forwarded as no prefix given -but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} section. - -@item S O p -@kindex S O p (Summary) -@findex gnus-uu-digest-post-forward -@cindex digests -@cindex making digests -Digest the current series and forward the result to a newsgroup -(@code{gnus-uu-digest-post-forward}). This command uses the -process/prefix convention. - -@item S u -@kindex S u (Summary) -@findex gnus-uu-post-news -@c @icon{gnus-uu-post-news} -Uuencode a file, split it into parts, and post it as a series -(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). -@end table - -Also @xref{Header Commands, ,Header Commands, message, The Message -Manual}, for more information. - - -@node Summary Message Commands -@subsection Summary Message Commands - -@table @kbd -@item S y -@kindex S y (Summary) -@findex gnus-summary-yank-message -Yank the current article into an already existing Message composition -buffer (@code{gnus-summary-yank-message}). This command prompts for -what message buffer you want to yank into, and understands the -process/prefix convention (@pxref{Process/Prefix}). - -@end table - - -@node Canceling and Superseding -@subsection Canceling Articles -@cindex canceling articles -@cindex superseding articles - -Have you ever written something, and then decided that you really, -really, really wish you hadn't posted that? - -Well, you can't cancel mail, but you can cancel posts. - -@findex gnus-summary-cancel-article -@kindex C (Summary) -@c @icon{gnus-summary-cancel-article} -Find the article you wish to cancel (you can only cancel your own -articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S -c} (@code{gnus-summary-cancel-article}). Your article will be -canceled---machines all over the world will be deleting your article. -This command uses the process/prefix convention (@pxref{Process/Prefix}). - -Be aware, however, that not all sites honor cancels, so your article may -live on here and there, while most sites will delete the article in -question. - -Gnus will use the ``current'' select method when canceling. If you -want to use the standard posting method, use the @samp{a} symbolic -prefix (@pxref{Symbolic Prefixes}). - -Gnus ensures that only you can cancel your own messages using a -@code{Cancel-Lock} header (@pxref{Canceling News, Canceling News, , -message, Message Manual}). - -If you discover that you have made some mistakes and want to do some -corrections, you can post a @dfn{superseding} article that will replace -your original article. - -@findex gnus-summary-supersede-article -@kindex S (Summary) -Go to the original article and press @kbd{S s} -(@code{gnus-summary-supersede-article}). You will be put in a buffer -where you can edit the article all you want before sending it off the -usual way. - -The same goes for superseding as for canceling, only more so: Some -sites do not honor superseding. On those sites, it will appear that you -have posted almost the same article twice. - -If you have just posted the article, and change your mind right away, -there is a trick you can use to cancel/supersede the article without -waiting for the article to appear on your site first. You simply return -to the post buffer (which is called @code{*sent ...*}). There you will -find the article you just posted, with all the headers intact. Change -the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} -header by substituting one of those words for the word -@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as -you would do normally. The previous article will be -canceled/superseded. - -Just remember, kids: There is no 'c' in 'supersede'. - -@node Delayed Articles -@section Delayed Articles -@cindex delayed sending -@cindex send delayed - -Sometimes, you might wish to delay the sending of a message. For -example, you might wish to arrange for a message to turn up just in time -to remind your about the birthday of your Significant Other. For this, -there is the @code{gnus-delay} package. Setup is simple: - -@lisp -(gnus-delay-initialize) -@end lisp - -@findex gnus-delay-article -Normally, to send a message you use the @kbd{C-c C-c} command from -Message mode. To delay a message, use @kbd{C-c C-j} -(@code{gnus-delay-article}) instead. This will ask you for how long the -message should be delayed. Possible answers are: - -@itemize @bullet -@item -A time span. Consists of an integer and a letter. For example, -@code{42d} means to delay for 42 days. Available letters are @code{m} -(minutes), @code{h} (hours), @code{d} (days), @code{w} (weeks), @code{M} -(months) and @code{Y} (years). - -@item -A specific date. Looks like @code{YYYY-MM-DD}. The message will be -delayed until that day, at a specific time (eight o'clock by default). -See also @code{gnus-delay-default-hour}. - -@item -A specific time of day. Given in @code{hh:mm} format, 24h, no am/pm -stuff. The deadline will be at that time today, except if that time has -already passed, then it's at the given time tomorrow. So if it's ten -o'clock in the morning and you specify @code{11:15}, then the deadline -is one hour and fifteen minutes hence. But if you specify @code{9:20}, -that means a time tomorrow. -@end itemize - -The action of the @code{gnus-delay-article} command is influenced by a -couple of variables: - -@table @code -@item gnus-delay-default-hour -@vindex gnus-delay-default-hour -When you specify a specific date, the message will be due on that hour -on the given date. Possible values are integers 0 through 23. - -@item gnus-delay-default-delay -@vindex gnus-delay-default-delay -This is a string and gives the default delay. It can be of any of the -formats described above. - -@item gnus-delay-group -@vindex gnus-delay-group -Delayed articles will be kept in this group on the drafts server until -they are due. You probably don't need to change this. The default -value is @code{"delayed"}. - -@item gnus-delay-header -@vindex gnus-delay-header -The deadline for each article will be stored in a header. This variable -is a string and gives the header name. You probably don't need to -change this. The default value is @code{"X-Gnus-Delayed"}. -@end table - -The way delaying works is like this: when you use the -@code{gnus-delay-article} command, you give a certain delay. Gnus -calculates the deadline of the message and stores it in the -@code{X-Gnus-Delayed} header and puts the message in the -@code{nndraft:delayed} group. - -@findex gnus-delay-send-queue -And whenever you get new news, Gnus looks through the group for articles -which are due and sends them. It uses the @code{gnus-delay-send-queue} -function for this. By default, this function is added to the hook -@code{gnus-get-new-news-hook}. But of course, you can change this. -Maybe you want to use the demon to send drafts? Just tell the demon to -execute the @code{gnus-delay-send-queue} function. - -@table @code -@item gnus-delay-initialize -@findex gnus-delay-initialize -By default, this function installs @code{gnus-delay-send-queue} in -@code{gnus-get-new-news-hook}. But it accepts the optional second -argument @code{no-check}. If it is non-@code{nil}, -@code{gnus-get-new-news-hook} is not changed. The optional first -argument is ignored. - -For example, @code{(gnus-delay-initialize nil t)} means to do nothing. -Presumably, you want to use the demon for sending due delayed articles. -Just don't forget to set that up :-) -@end table - - -@node Marking Articles -@section Marking Articles -@cindex article marking -@cindex article ticking -@cindex marks - -There are several marks you can set on an article. - -You have marks that decide the @dfn{readedness} (whoo, neato-keano -neologism ohoy!) of the article. Alphabetic marks generally mean -@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. - -In addition, you also have marks that do not affect readedness. - -@ifinfo -There's a plethora of commands for manipulating these marks. -@end ifinfo - -@menu -* Unread Articles:: Marks for unread articles. -* Read Articles:: Marks for read articles. -* Other Marks:: Marks that do not affect readedness. -* Setting Marks:: How to set and remove marks. -* Generic Marking Commands:: How to customize the marking. -* Setting Process Marks:: How to mark articles for later processing. -@end menu - - -@node Unread Articles -@subsection Unread Articles - -The following marks mark articles as (kinda) unread, in one form or -other. - -@table @samp -@item ! -@vindex gnus-ticked-mark -Marked as ticked (@code{gnus-ticked-mark}). - -@dfn{Ticked articles} are articles that will remain visible always. If -you see an article that you find interesting, or you want to put off -reading it, or replying to it, until sometime later, you'd typically -tick it. However, articles can be expired (from news servers by the -news server software, Gnus itself never expires ticked messages), so if -you want to keep an article forever, you'll have to make it persistent -(@pxref{Persistent Articles}). - -@item ? -@vindex gnus-dormant-mark -Marked as dormant (@code{gnus-dormant-mark}). - -@dfn{Dormant articles} will only appear in the summary buffer if there -are followups to it. If you want to see them even if they don't have -followups, you can use the @kbd{/ D} command (@pxref{Limiting}). -Otherwise (except for the visibility issue), they are just like ticked -messages. - -@item SPACE -@vindex gnus-unread-mark -Marked as unread (@code{gnus-unread-mark}). - -@dfn{Unread articles} are articles that haven't been read at all yet. -@end table - - -@node Read Articles -@subsection Read Articles -@cindex expirable mark - -All the following marks mark articles as read. - -@table @samp - -@item r -@vindex gnus-del-mark -These are articles that the user has marked as read with the @kbd{d} -command manually, more or less (@code{gnus-del-mark}). - -@item R -@vindex gnus-read-mark -Articles that have actually been read (@code{gnus-read-mark}). - -@item O -@vindex gnus-ancient-mark -Articles that were marked as read in previous sessions and are now -@dfn{old} (@code{gnus-ancient-mark}). - -@item K -@vindex gnus-killed-mark -Marked as killed (@code{gnus-killed-mark}). - -@item X -@vindex gnus-kill-file-mark -Marked as killed by kill files (@code{gnus-kill-file-mark}). - -@item Y -@vindex gnus-low-score-mark -Marked as read by having too low a score (@code{gnus-low-score-mark}). - -@item C -@vindex gnus-catchup-mark -Marked as read by a catchup (@code{gnus-catchup-mark}). - -@item G -@vindex gnus-canceled-mark -Canceled article (@code{gnus-canceled-mark}) - -@item F -@vindex gnus-souped-mark -@sc{soup}ed article (@code{gnus-souped-mark}). @xref{SOUP}. - -@item Q -@vindex gnus-sparse-mark -Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing -Threading}. - -@item M -@vindex gnus-duplicate-mark -Article marked as read by duplicate suppression -(@code{gnus-duplicate-mark}). @xref{Duplicate Suppression}. - -@end table - -All these marks just mean that the article is marked as read, really. -They are interpreted differently when doing adaptive scoring, though. - -One more special mark, though: - -@table @samp -@item E -@vindex gnus-expirable-mark -Marked as expirable (@code{gnus-expirable-mark}). - -Marking articles as @dfn{expirable} (or have them marked as such -automatically) doesn't make much sense in normal groups---a user doesn't -control expiring of news articles, but in mail groups, for instance, -articles marked as @dfn{expirable} can be deleted by Gnus at -any time. -@end table - - -@node Other Marks -@subsection Other Marks -@cindex process mark -@cindex bookmarks - -There are some marks that have nothing to do with whether the article is -read or not. - -@itemize @bullet - -@item -You can set a bookmark in the current article. Say you are reading a -long thesis on cats' urinary tracts, and have to go home for dinner -before you've finished reading the thesis. You can then set a bookmark -in the article, and Gnus will jump to this bookmark the next time it -encounters the article. @xref{Setting Marks}. - -@item -@vindex gnus-replied-mark -All articles that you have replied to or made a followup to (i.e., have -answered) will be marked with an @samp{A} in the second column -(@code{gnus-replied-mark}). - -@item -@vindex gnus-forwarded-mark -All articles that you have forwarded will be marked with an @samp{F} in -the second column (@code{gnus-forwarded-mark}). - -@item -@vindex gnus-cached-mark -Articles stored in the article cache will be marked with an @samp{*} in -the second column (@code{gnus-cached-mark}). @xref{Article Caching}. - -@item -@vindex gnus-saved-mark -Articles ``saved'' (in some manner or other; not necessarily -religiously) are marked with an @samp{S} in the second column -(@code{gnus-saved-mark}). - -@item -@vindex gnus-recent-mark -Articles that according to the server haven't been shown to the user -before are marked with a @samp{N} in the second column -(@code{gnus-recent-mark}). Note that not all servers support this -mark, in which case it simply never appears. Compare with -@code{gnus-unseen-mark}. - -@item -@vindex gnus-unseen-mark -Articles that haven't been seen before in Gnus by the user are marked -with a @samp{.} in the second column (@code{gnus-unseen-mark}). -Compare with @code{gnus-recent-mark}. - -@item -@vindex gnus-downloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), articles may be -downloaded for unplugged (offline) viewing. If you are using the -@samp{%O} spec, these articles get the @samp{+} mark in that spec. -(The variable @code{gnus-downloaded-mark} controls which character to -use.) - -@item -@vindex gnus-undownloaded-mark -When using the Gnus agent (@pxref{Agent Basics}), some articles might -not have been downloaded. Such articles cannot be viewed while you -are unplugged (offline). If you are using the @samp{%O} spec, these -articles get the @samp{-} mark in that spec. (The variable -@code{gnus-undownloaded-mark} controls which character to use.) - -@item -@vindex gnus-downloadable-mark -The Gnus agent (@pxref{Agent Basics}) downloads some articles -automatically, but it is also possible to explicitly mark articles for -download, even if they would not be downloaded automatically. Such -explicitly-marked articles get the @samp{%} mark in the first column. -(The variable @code{gnus-downloadable-mark} controls which character to -use.) - -@item -@vindex gnus-not-empty-thread-mark -@vindex gnus-empty-thread-mark -If the @samp{%e} spec is used, the presence of threads or not will be -marked with @code{gnus-not-empty-thread-mark} and -@code{gnus-empty-thread-mark} in the third column, respectively. - -@item -@vindex gnus-process-mark -Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A -variety of commands react to the presence of the process mark. For -instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view -all articles that have been marked with the process mark. Articles -marked with the process mark have a @samp{#} in the second column. - -@end itemize - -You might have noticed that most of these ``non-readedness'' marks -appear in the second column by default. So if you have a cached, saved, -replied article that you have process-marked, what will that look like? - -Nothing much. The precedence rules go as follows: process -> cache -> -replied -> saved. So if the article is in the cache and is replied, -you'll only see the cache mark and not the replied mark. - - -@node Setting Marks -@subsection Setting Marks -@cindex setting marks - -All the marking commands understand the numeric prefix. - -@table @kbd -@item M c -@itemx M-u -@kindex M c (Summary) -@kindex M-u (Summary) -@findex gnus-summary-clear-mark-forward -@cindex mark as unread -Clear all readedness-marks from the current article -(@code{gnus-summary-clear-mark-forward}). In other words, mark the -article as unread. - -@item M t -@itemx ! -@kindex ! (Summary) -@kindex M t (Summary) -@findex gnus-summary-tick-article-forward -Tick the current article (@code{gnus-summary-tick-article-forward}). -@xref{Article Caching}. - -@item M ? -@itemx ? -@kindex ? (Summary) -@kindex M ? (Summary) -@findex gnus-summary-mark-as-dormant -Mark the current article as dormant -(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}. - -@item M d -@itemx d -@kindex M d (Summary) -@kindex d (Summary) -@findex gnus-summary-mark-as-read-forward -Mark the current article as read -(@code{gnus-summary-mark-as-read-forward}). - -@item D -@kindex D (Summary) -@findex gnus-summary-mark-as-read-backward -Mark the current article as read and move point to the previous line -(@code{gnus-summary-mark-as-read-backward}). - -@item M k -@itemx k -@kindex k (Summary) -@kindex M k (Summary) -@findex gnus-summary-kill-same-subject-and-select -Mark all articles that have the same subject as the current one as read, -and then select the next unread article -(@code{gnus-summary-kill-same-subject-and-select}). - -@item M K -@itemx C-k -@kindex M K (Summary) -@kindex C-k (Summary) -@findex gnus-summary-kill-same-subject -Mark all articles that have the same subject as the current one as read -(@code{gnus-summary-kill-same-subject}). - -@item M C -@kindex M C (Summary) -@findex gnus-summary-catchup -@c @icon{gnus-summary-catchup} -Mark all unread articles as read (@code{gnus-summary-catchup}). - -@item M C-c -@kindex M C-c (Summary) -@findex gnus-summary-catchup-all -Mark all articles in the group as read---even the ticked and dormant -articles (@code{gnus-summary-catchup-all}). - -@item M H -@kindex M H (Summary) -@findex gnus-summary-catchup-to-here -Catchup the current group to point (before the point) -(@code{gnus-summary-catchup-to-here}). - -@item M h -@kindex M h (Summary) -@findex gnus-summary-catchup-from-here -Catchup the current group from point (after the point) -(@code{gnus-summary-catchup-from-here}). - -@item C-w -@kindex C-w (Summary) -@findex gnus-summary-mark-region-as-read -Mark all articles between point and mark as read -(@code{gnus-summary-mark-region-as-read}). - -@item M V k -@kindex M V k (Summary) -@findex gnus-summary-kill-below -Kill all articles with scores below the default score (or below the -numeric prefix) (@code{gnus-summary-kill-below}). - -@item M e -@itemx E -@kindex M e (Summary) -@kindex E (Summary) -@findex gnus-summary-mark-as-expirable -Mark the current article as expirable -(@code{gnus-summary-mark-as-expirable}). - -@item M b -@kindex M b (Summary) -@findex gnus-summary-set-bookmark -Set a bookmark in the current article -(@code{gnus-summary-set-bookmark}). - -@item M B -@kindex M B (Summary) -@findex gnus-summary-remove-bookmark -Remove the bookmark from the current article -(@code{gnus-summary-remove-bookmark}). - -@item M V c -@kindex M V c (Summary) -@findex gnus-summary-clear-above -Clear all marks from articles with scores over the default score (or -over the numeric prefix) (@code{gnus-summary-clear-above}). - -@item M V u -@kindex M V u (Summary) -@findex gnus-summary-tick-above -Tick all articles with scores over the default score (or over the -numeric prefix) (@code{gnus-summary-tick-above}). - -@item M V m -@kindex M V m (Summary) -@findex gnus-summary-mark-above -Prompt for a mark, and mark all articles with scores over the default -score (or over the numeric prefix) with this mark -(@code{gnus-summary-clear-above}). -@end table - -@vindex gnus-summary-goto-unread -The @code{gnus-summary-goto-unread} variable controls what action should -be taken after setting a mark. If non-@code{nil}, point will move to -the next/previous unread article. If @code{nil}, point will just move -one line up or down. As a special case, if this variable is -@code{never}, all the marking commands as well as other commands (like -@kbd{SPACE}) will move to the next article, whether it is unread or not. -The default is @code{t}. - - -@node Generic Marking Commands -@subsection Generic Marking Commands - -Some people would like the command that ticks an article (@kbd{!}) go to -the next article. Others would like it to go to the next unread -article. Yet others would like it to stay on the current article. And -even though I haven't heard of anybody wanting it to go to the -previous (unread) article, I'm sure there are people that want that as -well. - -Multiply these five behaviors with five different marking commands, and -you get a potentially complex set of variable to control what each -command should do. - -To sidestep that mess, Gnus provides commands that do all these -different things. They can be found on the @kbd{M M} map in the summary -buffer. Type @kbd{M M C-h} to see them all---there are too many of them -to list in this manual. - -While you can use these commands directly, most users would prefer -altering the summary mode keymap. For instance, if you would like the -@kbd{!} command to go to the next article instead of the next unread -article, you could say something like: - -@lisp -@group -(add-hook 'gnus-summary-mode-hook 'my-alter-summary-map) -(defun my-alter-summary-map () - (local-set-key "!" 'gnus-summary-put-mark-as-ticked-next)) -@end group -@end lisp - -@noindent -or - -@lisp -(defun my-alter-summary-map () - (local-set-key "!" "MM!n")) -@end lisp - - -@node Setting Process Marks -@subsection Setting Process Marks -@cindex setting process marks - -Process marks are displayed as @code{#} in the summary buffer, and are -used for marking articles in such a way that other commands will -process these articles. For instance, if you process mark four -articles and then use the @kbd{*} command, Gnus will enter these four -articles into the cache. For more information, -@pxref{Process/Prefix}. - -@table @kbd - -@item M P p -@itemx # -@kindex # (Summary) -@kindex M P p (Summary) -@findex gnus-summary-mark-as-processable -Mark the current article with the process mark -(@code{gnus-summary-mark-as-processable}). -@findex gnus-summary-unmark-as-processable - -@item M P u -@itemx M-# -@kindex M P u (Summary) -@kindex M-# (Summary) -Remove the process mark, if any, from the current article -(@code{gnus-summary-unmark-as-processable}). - -@item M P U -@kindex M P U (Summary) -@findex gnus-summary-unmark-all-processable -Remove the process mark from all articles -(@code{gnus-summary-unmark-all-processable}). - -@item M P i -@kindex M P i (Summary) -@findex gnus-uu-invert-processable -Invert the list of process marked articles -(@code{gnus-uu-invert-processable}). - -@item M P R -@kindex M P R (Summary) -@findex gnus-uu-mark-by-regexp -Mark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-mark-by-regexp}). - -@item M P G -@kindex M P G (Summary) -@findex gnus-uu-unmark-by-regexp -Unmark articles that have a @code{Subject} header that matches a regular -expression (@code{gnus-uu-unmark-by-regexp}). - -@item M P r -@kindex M P r (Summary) -@findex gnus-uu-mark-region -Mark articles in region (@code{gnus-uu-mark-region}). - -@item M P g -@kindex M P g (Summary) -@findex gnus-uu-unmark-region -Unmark articles in region (@code{gnus-uu-unmark-region}). - -@item M P t -@kindex M P t (Summary) -@findex gnus-uu-mark-thread -Mark all articles in the current (sub)thread -(@code{gnus-uu-mark-thread}). - -@item M P T -@kindex M P T (Summary) -@findex gnus-uu-unmark-thread -Unmark all articles in the current (sub)thread -(@code{gnus-uu-unmark-thread}). - -@item M P v -@kindex M P v (Summary) -@findex gnus-uu-mark-over -Mark all articles that have a score above the prefix argument -(@code{gnus-uu-mark-over}). - -@item M P s -@kindex M P s (Summary) -@findex gnus-uu-mark-series -Mark all articles in the current series (@code{gnus-uu-mark-series}). - -@item M P S -@kindex M P S (Summary) -@findex gnus-uu-mark-sparse -Mark all series that have already had some articles marked -(@code{gnus-uu-mark-sparse}). - -@item M P a -@kindex M P a (Summary) -@findex gnus-uu-mark-all -Mark all articles in series order (@code{gnus-uu-mark-all}). - -@item M P b -@kindex M P b (Summary) -@findex gnus-uu-mark-buffer -Mark all articles in the buffer in the order they appear -(@code{gnus-uu-mark-buffer}). - -@item M P k -@kindex M P k (Summary) -@findex gnus-summary-kill-process-mark -Push the current process mark set onto the stack and unmark all articles -(@code{gnus-summary-kill-process-mark}). - -@item M P y -@kindex M P y (Summary) -@findex gnus-summary-yank-process-mark -Pop the previous process mark set from the stack and restore it -(@code{gnus-summary-yank-process-mark}). - -@item M P w -@kindex M P w (Summary) -@findex gnus-summary-save-process-mark -Push the current process mark set onto the stack -(@code{gnus-summary-save-process-mark}). - -@end table - -Also see the @kbd{&} command in @ref{Searching for Articles}, for how to -set process marks based on article body contents. - - -@node Limiting -@section Limiting -@cindex limiting - -It can be convenient to limit the summary buffer to just show some -subset of the articles currently in the group. The effect most limit -commands have is to remove a few (or many) articles from the summary -buffer. - -Limiting commands work on subsets of the articles already fetched from -the servers. These commands don't query the server for additional -articles. - -@table @kbd - -@item / / -@itemx / s -@kindex / / (Summary) -@findex gnus-summary-limit-to-subject -Limit the summary buffer to articles that match some subject -(@code{gnus-summary-limit-to-subject}). If given a prefix, exclude -matching articles. - -@item / a -@kindex / a (Summary) -@findex gnus-summary-limit-to-author -Limit the summary buffer to articles that match some author -(@code{gnus-summary-limit-to-author}). If given a prefix, exclude -matching articles. - -@item / R -@kindex / R (Summary) -@findex gnus-summary-limit-to-recipient -Limit the summary buffer to articles that match some recipient -(@code{gnus-summary-limit-to-recipient}). If given a prefix, exclude -matching articles. - -@item / A -@kindex / A (Summary) -@findex gnus-summary-limit-to-address -Limit the summary buffer to articles in which contents of From, To or Cc -header match a given address (@code{gnus-summary-limit-to-address}). If -given a prefix, exclude matching articles. - -@item / S -@kindex / S (Summary) -@findex gnus-summary-limit-to-singletons -Limit the summary buffer to articles that aren't part of any displayed -threads (@code{gnus-summary-limit-to-singletons}). If given a prefix, -limit to articles that are part of displayed threads. - -@item / x -@kindex / x (Summary) -@findex gnus-summary-limit-to-extra -Limit the summary buffer to articles that match one of the ``extra'' -headers (@pxref{To From Newsgroups}) -(@code{gnus-summary-limit-to-extra}). If given a prefix, exclude -matching articles. - -@item / u -@itemx x -@kindex / u (Summary) -@kindex x (Summary) -@findex gnus-summary-limit-to-unread -Limit the summary buffer to articles not marked as read -(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the -buffer to articles strictly unread. This means that ticked and -dormant articles will also be excluded. - -@item / m -@kindex / m (Summary) -@findex gnus-summary-limit-to-marks -Ask for a mark and then limit to all articles that have been marked -with that mark (@code{gnus-summary-limit-to-marks}). - -@item / t -@kindex / t (Summary) -@findex gnus-summary-limit-to-age -Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days -(@code{gnus-summary-limit-to-age}). If given a prefix, limit to -articles younger than that number of days. - -@item / n -@kindex / n (Summary) -@findex gnus-summary-limit-to-articles -With prefix @samp{n}, limit the summary buffer to the next @samp{n} -articles. If not given a prefix, use the process marked articles -instead. (@code{gnus-summary-limit-to-articles}). - -@item / w -@kindex / w (Summary) -@findex gnus-summary-pop-limit -Pop the previous limit off the stack and restore it -(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off -the stack. - -@item / . -@kindex / . (Summary) -@findex gnus-summary-limit-to-unseen -Limit the summary buffer to the unseen articles -(@code{gnus-summary-limit-to-unseen}). - -@item / v -@kindex / v (Summary) -@findex gnus-summary-limit-to-score -Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). - -@item / p -@kindex / p (Summary) -@findex gnus-summary-limit-to-display-predicate -Limit the summary buffer to articles that satisfy the @code{display} -group parameter predicate -(@code{gnus-summary-limit-to-display-predicate}). @xref{Group -Parameters}, for more on this predicate. - -@item / r -@kindex / r (Summary) -@findex gnus-summary-limit-to-replied -Limit the summary buffer to replied articles -(@code{gnus-summary-limit-to-replied}). If given a prefix, exclude -replied articles. - -@item / E -@itemx M S -@kindex M S (Summary) -@kindex / E (Summary) -@findex gnus-summary-limit-include-expunged -Include all expunged articles in the limit -(@code{gnus-summary-limit-include-expunged}). - -@item / D -@kindex / D (Summary) -@findex gnus-summary-limit-include-dormant -Include all dormant articles in the limit -(@code{gnus-summary-limit-include-dormant}). - -@item / * -@kindex / * (Summary) -@findex gnus-summary-limit-include-cached -Include all cached articles in the limit -(@code{gnus-summary-limit-include-cached}). - -@item / d -@kindex / d (Summary) -@findex gnus-summary-limit-exclude-dormant -Exclude all dormant articles from the limit -(@code{gnus-summary-limit-exclude-dormant}). - -@item / M -@kindex / M (Summary) -@findex gnus-summary-limit-exclude-marks -Exclude all marked articles (@code{gnus-summary-limit-exclude-marks}). - -@item / T -@kindex / T (Summary) -@findex gnus-summary-limit-include-thread -Include all the articles in the current thread in the limit. - -@item / c -@kindex / c (Summary) -@findex gnus-summary-limit-exclude-childless-dormant -Exclude all dormant articles that have no children from the limit@* -(@code{gnus-summary-limit-exclude-childless-dormant}). - -@item / C -@kindex / C (Summary) -@findex gnus-summary-limit-mark-excluded-as-read -Mark all excluded unread articles as read -(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, -also mark excluded ticked and dormant articles as read. - -@item / b -@kindex / b (Summary) -@findex gnus-summary-limit-to-bodies -Limit the summary buffer to articles that have bodies that match a -certain regexp (@code{gnus-summary-limit-to-bodies}). If given a -prefix, reverse the limit. This command is quite slow since it -requires selecting each article to find the matches. - -@item / h -@kindex / h (Summary) -@findex gnus-summary-limit-to-headers -Like the previous command, only limit to headers instead -(@code{gnus-summary-limit-to-headers}). - -@end table - - -The following commands aren't limiting commands, but use the @kbd{/} -prefix as well. - -@table @kbd -@item / N -@kindex / N (Summary) -@findex gnus-summary-insert-new-articles -Insert all new articles in the summary buffer. It scans for new emails -if @var{back-end}@code{-get-new-mail} is non-@code{nil}. - -@item / o -@kindex / o (Summary) -@findex gnus-summary-insert-old-articles -Insert all old articles in the summary buffer. If given a numbered -prefix, fetch this number of articles. - -@end table - - -@node Threading -@section Threading -@cindex threading -@cindex article threading - -Gnus threads articles by default. @dfn{To thread} is to put responses -to articles directly after the articles they respond to---in a -hierarchical fashion. - -Threading is done by looking at the @code{References} headers of the -articles. In a perfect world, this would be enough to build pretty -trees, but unfortunately, the @code{References} header is often broken -or simply missing. Weird news propagation exacerbates the problem, -so one has to employ other heuristics to get pleasing results. A -plethora of approaches exists, as detailed in horrible detail in -@ref{Customizing Threading}. - -First, a quick overview of the concepts: - -@table @dfn -@item root -The top-most article in a thread; the first article in the thread. - -@item thread -A tree-like article structure. - -@item sub-thread -A small(er) section of this tree-like structure. - -@item loose threads -Threads often lose their roots due to article expiry, or due to the root -already having been read in a previous session, and not displayed in the -summary buffer. We then typically have many sub-threads that really -belong to one thread, but are without connecting roots. These are -called loose threads. - -@item thread gathering -An attempt to gather loose threads into bigger threads. - -@item sparse threads -A thread where the missing articles have been ``guessed'' at, and are -displayed as empty lines in the summary buffer. - -@end table - - -@menu -* Customizing Threading:: Variables you can change to affect the threading. -* Thread Commands:: Thread based commands in the summary buffer. -@end menu - - -@node Customizing Threading -@subsection Customizing Threading -@cindex customizing threading - -@menu -* Loose Threads:: How Gnus gathers loose threads into bigger threads. -* Filling In Threads:: Making the threads displayed look fuller. -* More Threading:: Even more variables for fiddling with threads. -* Low-Level Threading:: You thought it was over@dots{} but you were wrong! -@end menu - - -@node Loose Threads -@subsubsection Loose Threads -@cindex < -@cindex > -@cindex loose threads - -@table @code -@item gnus-summary-make-false-root -@vindex gnus-summary-make-false-root -If non-@code{nil}, Gnus will gather all loose subtrees into one big tree -and create a dummy root at the top. (Wait a minute. Root at the top? -Yup.) Loose subtrees occur when the real root has expired, or you've -read or killed the root in a previous session. - -When there is no real root of a thread, Gnus will have to fudge -something. This variable says what fudging method Gnus should use. -There are four possible values: - -@iftex -@iflatex -\gnusfigure{The Summary Buffer}{390}{ -\put(0,0){\epsfig{figure=ps/summary-adopt,width=7.5cm}} -\put(445,0){\makebox(0,0)[br]{\epsfig{figure=ps/summary-empty,width=7.5cm}}} -\put(0,400){\makebox(0,0)[tl]{\epsfig{figure=ps/summary-none,width=7.5cm}}} -\put(445,400){\makebox(0,0)[tr]{\epsfig{figure=ps/summary-dummy,width=7.5cm}}} -} -@end iflatex -@end iftex - -@cindex adopting articles - -@table @code - -@item adopt -Gnus will make the first of the orphaned articles the parent. This -parent will adopt all the other articles. The adopted articles will be -marked as such by pointy brackets (@samp{<>}) instead of the standard -square brackets (@samp{[]}). This is the default method. - -@item dummy -@vindex gnus-summary-dummy-line-format -@vindex gnus-summary-make-false-root-always -Gnus will create a dummy summary line that will pretend to be the -parent. This dummy line does not correspond to any real article, so -selecting it will just select the first real article after the dummy -article. @code{gnus-summary-dummy-line-format} is used to specify the -format of the dummy roots. It accepts only one format spec: @samp{S}, -which is the subject of the article. @xref{Formatting Variables}. -If you want all threads to have a dummy root, even the non-gathered -ones, set @code{gnus-summary-make-false-root-always} to @code{t}. - -@item empty -Gnus won't actually make any article the parent, but simply leave the -subject field of all orphans except the first empty. (Actually, it will -use @code{gnus-summary-same-subject} as the subject (@pxref{Summary -Buffer Format}).) - -@item none -Don't make any article parent at all. Just gather the threads and -display them after one another. - -@item nil -Don't gather loose threads. -@end table - -@item gnus-summary-gather-subject-limit -@vindex gnus-summary-gather-subject-limit -Loose threads are gathered by comparing subjects of articles. If this -variable is @code{nil}, Gnus requires an exact match between the -subjects of the loose threads before gathering them into one big -super-thread. This might be too strict a requirement, what with the -presence of stupid newsreaders that chop off long subject lines. If -you think so, set this variable to, say, 20 to require that only the -first 20 characters of the subjects have to match. If you set this -variable to a really low number, you'll find that Gnus will gather -everything in sight into one thread, which isn't very helpful. - -@cindex fuzzy article gathering -If you set this variable to the special value @code{fuzzy}, Gnus will -use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy -Matching}). - -@item gnus-simplify-subject-fuzzy-regexp -@vindex gnus-simplify-subject-fuzzy-regexp -This can either be a regular expression or list of regular expressions -that match strings that will be removed from subjects if fuzzy subject -simplification is used. - -@item gnus-simplify-ignored-prefixes -@vindex gnus-simplify-ignored-prefixes -If you set @code{gnus-summary-gather-subject-limit} to something as low -as 10, you might consider setting this variable to something sensible: - -@c Written by Michael Ernst -@lisp -(setq gnus-simplify-ignored-prefixes - (concat - "\\`\\[?\\(" - (mapconcat - 'identity - '("looking" - "wanted" "followup" "summary\\( of\\)?" - "help" "query" "problem" "question" - "answer" "reference" "announce" - "How can I" "How to" "Comparison of" - ;; ... - ) - "\\|") - "\\)\\s *\\(" - (mapconcat 'identity - '("for" "for reference" "with" "about") - "\\|") - "\\)?\\]?:?[ \t]*")) -@end lisp - -All words that match this regexp will be removed before comparing two -subjects. - -@item gnus-simplify-subject-functions -@vindex gnus-simplify-subject-functions -If non-@code{nil}, this variable overrides -@code{gnus-summary-gather-subject-limit}. This variable should be a -list of functions to apply to the @code{Subject} string iteratively to -arrive at the simplified version of the string. - -Useful functions to put in this list include: - -@table @code -@item gnus-simplify-subject-re -@findex gnus-simplify-subject-re -Strip the leading @samp{Re:}. - -@item gnus-simplify-subject-fuzzy -@findex gnus-simplify-subject-fuzzy -Simplify fuzzily. - -@item gnus-simplify-whitespace -@findex gnus-simplify-whitespace -Remove excessive whitespace. - -@item gnus-simplify-all-whitespace -@findex gnus-simplify-all-whitespace -Remove all whitespace. -@end table - -You may also write your own functions, of course. - - -@item gnus-summary-gather-exclude-subject -@vindex gnus-summary-gather-exclude-subject -Since loose thread gathering is done on subjects only, that might lead -to many false hits, especially with certain common subjects like -@samp{} and @samp{(none)}. To make the situation slightly better, -you can use the regexp @code{gnus-summary-gather-exclude-subject} to say -what subjects should be excluded from the gathering process.@* -The default is @samp{^ *$\\|^(none)$}. - -@item gnus-summary-thread-gathering-function -@vindex gnus-summary-thread-gathering-function -Gnus gathers threads by looking at @code{Subject} headers. This means -that totally unrelated articles may end up in the same ``thread'', which -is confusing. An alternate approach is to look at all the -@code{Message-ID}s in all the @code{References} headers to find matches. -This will ensure that no gathered threads ever include unrelated -articles, but it also means that people who have posted with broken -newsreaders won't be gathered properly. The choice is yours---plague or -cholera: - -@table @code -@item gnus-gather-threads-by-subject -@findex gnus-gather-threads-by-subject -This function is the default gathering function and looks at -@code{Subject}s exclusively. - -@item gnus-gather-threads-by-references -@findex gnus-gather-threads-by-references -This function looks at @code{References} headers exclusively. -@end table - -If you want to test gathering by @code{References}, you could say -something like: - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@end table - - -@node Filling In Threads -@subsubsection Filling In Threads - -@table @code -@item gnus-fetch-old-headers -@vindex gnus-fetch-old-headers -If non-@code{nil}, Gnus will attempt to build old threads by fetching -more old headers---headers to articles marked as read. If you would -like to display as few summary lines as possible, but still connect as -many loose threads as possible, you should set this variable to -@code{some} or a number. If you set it to a number, no more than that -number of extra old headers will be fetched. In either case, fetching -old headers only works if the back end you are using carries overview -files---this would normally be @code{nntp}, @code{nnspool}, -@code{nnml}, and @code{nnmaildir}. Also remember that if the root of -the thread has been expired by the server, there's not much Gnus can -do about that. - -This variable can also be set to @code{invisible}. This won't have any -visible effects, but is useful if you use the @kbd{A T} command a lot -(@pxref{Finding the Parent}). - -The server has to support @acronym{NOV} for any of this to work. - -@cindex Gmane, gnus-fetch-old-headers -This feature can seriously impact performance it ignores all locally -cached header entries. Setting it to @code{t} for groups for a server -that doesn't expire articles (such as news.gmane.org), leads to very -slow summary generation. - -@item gnus-fetch-old-ephemeral-headers -@vindex gnus-fetch-old-ephemeral-headers -Same as @code{gnus-fetch-old-headers}, but only used for ephemeral -newsgroups. - -@item gnus-build-sparse-threads -@vindex gnus-build-sparse-threads -Fetching old headers can be slow. A low-rent similar effect can be -gotten by setting this variable to @code{some}. Gnus will then look at -the complete @code{References} headers of all articles and try to string -together articles that belong in the same thread. This will leave -@dfn{gaps} in the threading display where Gnus guesses that an article -is missing from the thread. (These gaps appear like normal summary -lines. If you select a gap, Gnus will try to fetch the article in -question.) If this variable is @code{t}, Gnus will display all these -``gaps'' without regard for whether they are useful for completing the -thread or not. Finally, if this variable is @code{more}, Gnus won't cut -off sparse leaf nodes that don't lead anywhere. This variable is -@code{nil} by default. - -@item gnus-read-all-available-headers -@vindex gnus-read-all-available-headers -This is a rather obscure variable that few will find useful. It's -intended for those non-news newsgroups where the back end has to fetch -quite a lot to present the summary buffer, and where it's impossible to -go back to parents of articles. This is mostly the case in the -web-based groups, like the @code{nnultimate} groups. - -If you don't use those, then it's safe to leave this as the default -@code{nil}. If you want to use this variable, it should be a regexp -that matches the group name, or @code{t} for all groups. - -@end table - - -@node More Threading -@subsubsection More Threading - -@table @code -@item gnus-show-threads -@vindex gnus-show-threads -If this variable is @code{nil}, no threading will be done, and all of -the rest of the variables here will have no effect. Turning threading -off will speed group selection up a bit, but it is sure to make reading -slower and more awkward. - -@item gnus-thread-hide-subtree -@vindex gnus-thread-hide-subtree -If non-@code{nil}, all threads will be hidden when the summary buffer is -generated. - -This can also be a predicate specifier (@pxref{Predicate Specifiers}). -Available predicates are @code{gnus-article-unread-p} and -@code{gnus-article-unseen-p}. - -Here's an example: - -@lisp -(setq gnus-thread-hide-subtree - '(or gnus-article-unread-p - gnus-article-unseen-p)) -@end lisp - -(It's a pretty nonsensical example, since all unseen articles are also -unread, but you get my drift.) - - -@item gnus-thread-expunge-below -@vindex gnus-thread-expunge-below -All threads that have a total score (as defined by -@code{gnus-thread-score-function}) less than this number will be -expunged. This variable is @code{nil} by default, which means that no -threads are expunged. - -@item gnus-thread-hide-killed -@vindex gnus-thread-hide-killed -if you kill a thread and this variable is non-@code{nil}, the subtree -will be hidden. - -@item gnus-thread-ignore-subject -@vindex gnus-thread-ignore-subject -Sometimes somebody changes the subject in the middle of a thread. If -this variable is non-@code{nil}, which is the default, the subject -change is ignored. If it is @code{nil}, a change in the subject will -result in a new thread. - -@item gnus-thread-indent-level -@vindex gnus-thread-indent-level -This is a number that says how much each sub-thread should be indented. -The default is 4. - -@item gnus-sort-gathered-threads-function -@vindex gnus-sort-gathered-threads-function -Sometimes, particularly with mailing lists, the order in which mails -arrive locally is not necessarily the same as the order in which they -arrived on the mailing list. Consequently, when sorting sub-threads -using the default @code{gnus-thread-sort-by-number}, responses can end -up appearing before the article to which they are responding to. -Setting this variable to an alternate value -(e.g. @code{gnus-thread-sort-by-date}), in a group's parameters or in an -appropriate hook (e.g. @code{gnus-summary-generate-hook}) can produce a -more logical sub-thread ordering in such instances. - -@end table - - -@node Low-Level Threading -@subsubsection Low-Level Threading - -@table @code - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -Hook run before parsing any headers. - -@item gnus-alter-header-function -@vindex gnus-alter-header-function -If non-@code{nil}, this function will be called to allow alteration of -article header structures. The function is called with one parameter, -the article header vector, which it may alter in any way. For instance, -if you have a mail-to-news gateway which alters the @code{Message-ID}s -in systematic ways (by adding prefixes and such), you can use this -variable to un-scramble the @code{Message-ID}s so that they are more -meaningful. Here's one example: - -@lisp -(setq gnus-alter-header-function 'my-alter-message-id) - -(defun my-alter-message-id (header) - (let ((id (mail-header-id header))) - (when (string-match - "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) - (mail-header-set-id - (concat (match-string 1 id) "@@" (match-string 2 id)) - header)))) -@end lisp - -@end table - - -@node Thread Commands -@subsection Thread Commands -@cindex thread commands - -@table @kbd - -@item T k -@itemx C-M-k -@kindex T k (Summary) -@kindex C-M-k (Summary) -@findex gnus-summary-kill-thread -Mark all articles in the current (sub-)thread as read -(@code{gnus-summary-kill-thread}). If the prefix argument is positive, -remove all marks instead. If the prefix argument is negative, tick -articles instead. - -@item T l -@itemx C-M-l -@kindex T l (Summary) -@kindex C-M-l (Summary) -@findex gnus-summary-lower-thread -Lower the score of the current (sub-)thread -(@code{gnus-summary-lower-thread}). - -@item T i -@kindex T i (Summary) -@findex gnus-summary-raise-thread -Increase the score of the current (sub-)thread -(@code{gnus-summary-raise-thread}). - -@item T # -@kindex T # (Summary) -@findex gnus-uu-mark-thread -Set the process mark on the current (sub-)thread -(@code{gnus-uu-mark-thread}). - -@item T M-# -@kindex T M-# (Summary) -@findex gnus-uu-unmark-thread -Remove the process mark from the current (sub-)thread -(@code{gnus-uu-unmark-thread}). - -@item T T -@kindex T T (Summary) -@findex gnus-summary-toggle-threads -Toggle threading (@code{gnus-summary-toggle-threads}). - -@item T s -@kindex T s (Summary) -@findex gnus-summary-show-thread -Expose the (sub-)thread hidden under the current article, if any@* -(@code{gnus-summary-show-thread}). - -@item T h -@kindex T h (Summary) -@findex gnus-summary-hide-thread -Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). - -@item T S -@kindex T S (Summary) -@findex gnus-summary-show-all-threads -Expose all hidden threads (@code{gnus-summary-show-all-threads}). - -@item T H -@kindex T H (Summary) -@findex gnus-summary-hide-all-threads -Hide all threads (@code{gnus-summary-hide-all-threads}). - -@item T t -@kindex T t (Summary) -@findex gnus-summary-rethread-current -Re-thread the current article's thread -(@code{gnus-summary-rethread-current}). This works even when the -summary buffer is otherwise unthreaded. - -@item T ^ -@kindex T ^ (Summary) -@findex gnus-summary-reparent-thread -Make the current article the child of the marked (or previous) article -(@code{gnus-summary-reparent-thread}). - -@item T M-^ -@kindex T M-^ (Summary) -@findex gnus-summary-reparent-children -Make the current article the parent of the marked articles -(@code{gnus-summary-reparent-children}). - -@end table - -The following commands are thread movement commands. They all -understand the numeric prefix. - -@table @kbd - -@item T n -@kindex T n (Summary) -@itemx C-M-f -@kindex C-M-n (Summary) -@itemx M-down -@kindex M-down (Summary) -@findex gnus-summary-next-thread -Go to the next thread (@code{gnus-summary-next-thread}). - -@item T p -@kindex T p (Summary) -@itemx C-M-b -@kindex C-M-p (Summary) -@itemx M-up -@kindex M-up (Summary) -@findex gnus-summary-prev-thread -Go to the previous thread (@code{gnus-summary-prev-thread}). - -@item T d -@kindex T d (Summary) -@findex gnus-summary-down-thread -Descend the thread (@code{gnus-summary-down-thread}). - -@item T u -@kindex T u (Summary) -@findex gnus-summary-up-thread -Ascend the thread (@code{gnus-summary-up-thread}). - -@item T o -@kindex T o (Summary) -@findex gnus-summary-top-thread -Go to the top of the thread (@code{gnus-summary-top-thread}). -@end table - -@vindex gnus-thread-operation-ignore-subject -If you ignore subject while threading, you'll naturally end up with -threads that have several different subjects in them. If you then issue -a command like @kbd{T k} (@code{gnus-summary-kill-thread}) you might not -wish to kill the entire thread, but just those parts of the thread that -have the same subject as the current article. If you like this idea, -you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it -is non-@code{nil} (which it is by default), subjects will be ignored -when doing thread commands. If this variable is @code{nil}, articles in -the same thread with different subjects will not be included in the -operation in question. If this variable is @code{fuzzy}, only articles -that have subjects fuzzily equal will be included (@pxref{Fuzzy -Matching}). - - -@node Sorting the Summary Buffer -@section Sorting the Summary Buffer - -@findex gnus-thread-sort-by-total-score -@findex gnus-thread-sort-by-date -@findex gnus-thread-sort-by-score -@findex gnus-thread-sort-by-subject -@findex gnus-thread-sort-by-author -@findex gnus-thread-sort-by-recipient -@findex gnus-thread-sort-by-number -@findex gnus-thread-sort-by-random -@vindex gnus-thread-sort-functions -@findex gnus-thread-sort-by-most-recent-number -@findex gnus-thread-sort-by-most-recent-date -If you are using a threaded summary display, you can sort the threads by -setting @code{gnus-thread-sort-functions}, which can be either a single -function, a list of functions, or a list containing functions and -@code{(not some-function)} elements. - -By default, sorting is done on article numbers. Ready-made sorting -predicate functions include @code{gnus-thread-sort-by-number}, -@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-recipient}, -@code{gnus-thread-sort-by-subject}, -@code{gnus-thread-sort-by-date}, -@code{gnus-thread-sort-by-score}, -@code{gnus-thread-sort-by-most-recent-number}, -@code{gnus-thread-sort-by-most-recent-date}, -@code{gnus-thread-sort-by-random} and -@code{gnus-thread-sort-by-total-score}. - -Each function takes two threads and returns non-@code{nil} if the first -thread should be sorted before the other. Note that sorting really is -normally done by looking only at the roots of each thread. - -If you use more than one function, the primary sort key should be the -last function in the list. You should probably always include -@code{gnus-thread-sort-by-number} in the list of sorting -functions---preferably first. This will ensure that threads that are -equal with respect to the other sort criteria will be displayed in -ascending article order. - -If you would like to sort by reverse score, then by subject, and finally -by number, you could do something like: - -@lisp -(setq gnus-thread-sort-functions - '(gnus-thread-sort-by-number - gnus-thread-sort-by-subject - (not gnus-thread-sort-by-total-score))) -@end lisp - -The threads that have highest score will be displayed first in the -summary buffer. When threads have the same score, they will be sorted -alphabetically. The threads that have the same score and the same -subject will be sorted by number, which is (normally) the sequence in -which the articles arrived. - -If you want to sort by score and then reverse arrival order, you could -say something like: - -@lisp -(setq gnus-thread-sort-functions - '((not gnus-thread-sort-by-number) - gnus-thread-sort-by-score)) -@end lisp - -@vindex gnus-thread-score-function -The function in the @code{gnus-thread-score-function} variable (default -@code{+}) is used for calculating the total score of a thread. Useful -functions might be @code{max}, @code{min}, or squared means, or whatever -tickles your fancy. - -@findex gnus-article-sort-functions -@findex gnus-article-sort-by-date -@findex gnus-article-sort-by-most-recent-date -@findex gnus-article-sort-by-score -@findex gnus-article-sort-by-subject -@findex gnus-article-sort-by-author -@findex gnus-article-sort-by-random -@findex gnus-article-sort-by-number -@findex gnus-article-sort-by-most-recent-number -If you are using an unthreaded display for some strange reason or -other, you have to fiddle with the @code{gnus-article-sort-functions} -variable. It is very similar to the -@code{gnus-thread-sort-functions}, except that it uses slightly -different functions for article comparison. Available sorting -predicate functions are @code{gnus-article-sort-by-number}, -@code{gnus-article-sort-by-author}, -@code{gnus-article-sort-by-subject}, @code{gnus-article-sort-by-date}, -@code{gnus-article-sort-by-random}, and -@code{gnus-article-sort-by-score}. - -If you want to sort an unthreaded summary display by subject, you could -say something like: - -@lisp -(setq gnus-article-sort-functions - '(gnus-article-sort-by-number - gnus-article-sort-by-subject)) -@end lisp - -You can define group specific sorting via @code{gnus-parameters}, -@xref{Group Parameters}. - - -@node Asynchronous Fetching -@section Asynchronous Article Fetching -@cindex asynchronous article fetching -@cindex article pre-fetch -@cindex pre-fetch - -If you read your news from an @acronym{NNTP} server that's far away, the -network latencies may make reading articles a chore. You have to wait -for a while after pressing @kbd{n} to go to the next article before the -article appears. Why can't Gnus just go ahead and fetch the article -while you are reading the previous one? Why not, indeed. - -First, some caveats. There are some pitfalls to using asynchronous -article fetching, especially the way Gnus does it. - -Let's say you are reading article 1, which is short, and article 2 is -quite long, and you are not interested in reading that. Gnus does not -know this, so it goes ahead and fetches article 2. You decide to read -article 3, but since Gnus is in the process of fetching article 2, the -connection is blocked. - -To avoid these situations, Gnus will open two (count 'em two) -connections to the server. Some people may think this isn't a very nice -thing to do, but I don't see any real alternatives. Setting up that -extra connection takes some time, so Gnus startup will be slower. - -Gnus will fetch more articles than you will read. This will mean that -the link between your machine and the @acronym{NNTP} server will become more -loaded than if you didn't use article pre-fetch. The server itself will -also become more loaded---both with the extra article requests, and the -extra connection. - -Ok, so now you know that you shouldn't really use this thing@dots{} unless -you really want to. - -@vindex gnus-asynchronous -Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should -happen automatically. - -@vindex gnus-use-article-prefetch -You can control how many articles are to be pre-fetched by setting -@code{gnus-use-article-prefetch}. This is 30 by default, which means -that when you read an article in the group, the back end will pre-fetch -the next 30 articles. If this variable is @code{t}, the back end will -pre-fetch all the articles it can without bound. If it is -@code{nil}, no pre-fetching will be done. - -@vindex gnus-async-prefetch-article-p -@findex gnus-async-unread-p -There are probably some articles that you don't want to pre-fetch---read -articles, for instance. The @code{gnus-async-prefetch-article-p} -variable controls whether an article is to be pre-fetched. This -function should return non-@code{nil} when the article in question is -to be pre-fetched. The default is @code{gnus-async-unread-p}, which -returns @code{nil} on read articles. The function is called with an -article data structure as the only parameter. - -If, for instance, you wish to pre-fetch only unread articles shorter -than 100 lines, you could say something like: - -@lisp -(defun my-async-short-unread-p (data) - "Return non-nil for short, unread articles." - (and (gnus-data-unread-p data) - (< (mail-header-lines (gnus-data-header data)) - 100))) - -(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) -@end lisp - -These functions will be called many, many times, so they should -preferably be short and sweet to avoid slowing down Gnus too much. -It's probably a good idea to byte-compile things like this. - -@vindex gnus-prefetched-article-deletion-strategy -Articles have to be removed from the asynch buffer sooner or later. The -@code{gnus-prefetched-article-deletion-strategy} says when to remove -articles. This is a list that may contain the following elements: - -@table @code -@item read -Remove articles when they are read. - -@item exit -Remove articles when exiting the group. -@end table - -The default value is @code{(read exit)}. - -@c @vindex gnus-use-header-prefetch -@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles -@c from the next group. - - -@node Article Caching -@section Article Caching -@cindex article caching -@cindex caching - -If you have an @emph{extremely} slow @acronym{NNTP} connection, you may -consider turning article caching on. Each article will then be stored -locally under your home directory. As you may surmise, this could -potentially use @emph{huge} amounts of disk space, as well as eat up all -your inodes so fast it will make your head swim. In vodka. - -Used carefully, though, it could be just an easier way to save articles. - -@vindex gnus-use-long-file-name -@vindex gnus-cache-directory -@vindex gnus-use-cache -To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, -all articles ticked or marked as dormant will then be copied -over to your local cache (@code{gnus-cache-directory}). Whether this -cache is flat or hierarchical is controlled by the -@code{gnus-use-long-file-name} variable, as usual. - -When re-selecting a ticked or dormant article, it will be fetched from the -cache instead of from the server. As articles in your cache will never -expire, this might serve as a method of saving articles while still -keeping them where they belong. Just mark all articles you want to save -as dormant, and don't worry. - -When an article is marked as read, is it removed from the cache. - -@vindex gnus-cache-remove-articles -@vindex gnus-cache-enter-articles -The entering/removal of articles from the cache is controlled by the -@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} -variables. Both are lists of symbols. The first is @code{(ticked -dormant)} by default, meaning that ticked and dormant articles will be -put in the cache. The latter is @code{(read)} by default, meaning that -articles marked as read are removed from the cache. Possibly -symbols in these two lists are @code{ticked}, @code{dormant}, -@code{unread} and @code{read}. - -@findex gnus-jog-cache -So where does the massive article-fetching and storing come into the -picture? The @code{gnus-jog-cache} command will go through all -subscribed newsgroups, request all unread articles, score them, and -store them in the cache. You should only ever, ever ever ever, use this -command if 1) your connection to the @acronym{NNTP} server is really, really, -really slow and 2) you have a really, really, really huge disk. -Seriously. One way to cut down on the number of articles downloaded is -to score unwanted articles down and have them marked as read. They will -not then be downloaded by this command. - -@vindex gnus-uncacheable-groups -@vindex gnus-cacheable-groups -It is likely that you do not want caching on all groups. For instance, -if your @code{nnml} mail is located under your home directory, it makes no -sense to cache it somewhere else under your home directory. Unless you -feel that it's neat to use twice as much space. - -To limit the caching, you could set @code{gnus-cacheable-groups} to a -regexp of groups to cache, @samp{^nntp} for instance, or set the -@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. -Both variables are @code{nil} by default. If a group matches both -variables, the group is not cached. - -@findex gnus-cache-generate-nov-databases -@findex gnus-cache-generate-active -@vindex gnus-cache-active-file -The cache stores information on what articles it contains in its active -file (@code{gnus-cache-active-file}). If this file (or any other parts -of the cache) becomes all messed up for some reason or other, Gnus -offers two functions that will try to set things right. @kbd{M-x -gnus-cache-generate-nov-databases} will (re)build all the @acronym{NOV} -files, and @kbd{gnus-cache-generate-active} will (re)generate the active -file. - -@findex gnus-cache-move-cache -@code{gnus-cache-move-cache} will move your whole -@code{gnus-cache-directory} to some other location. You get asked to -where, isn't that cool? - -@node Persistent Articles -@section Persistent Articles -@cindex persistent articles - -Closely related to article caching, we have @dfn{persistent articles}. -In fact, it's just a different way of looking at caching, and much more -useful in my opinion. - -Say you're reading a newsgroup, and you happen on to some valuable gem -that you want to keep and treasure forever. You'd normally just save it -(using one of the many saving commands) in some file. The problem with -that is that it's just, well, yucky. Ideally you'd prefer just having -the article remain in the group where you found it forever; untouched by -the expiry going on at the news server. - -This is what a @dfn{persistent article} is---an article that just won't -be deleted. It's implemented using the normal cache functions, but -you use two explicit commands for managing persistent articles: - -@table @kbd - -@item * -@kindex * (Summary) -@findex gnus-cache-enter-article -Make the current article persistent (@code{gnus-cache-enter-article}). - -@item M-* -@kindex M-* (Summary) -@findex gnus-cache-remove-article -Remove the current article from the persistent articles -(@code{gnus-cache-remove-article}). This will normally delete the -article. -@end table - -Both these commands understand the process/prefix convention. - -To avoid having all ticked articles (and stuff) entered into the cache, -you should set @code{gnus-use-cache} to @code{passive} if you're just -interested in persistent articles: - -@lisp -(setq gnus-use-cache 'passive) -@end lisp - -@node Sticky Articles -@section Sticky Articles -@cindex sticky articles - -When you select an article the current article buffer will be reused -according to the value of the variable -@code{gnus-single-article-buffer}. If its value is non-@code{nil} (the -default) all articles reuse the same article buffer. Else each group -has its own article buffer. - -This implies that it's not possible to have more than one article buffer -in a group at a time. But sometimes you might want to display all the -latest emails from your mother, your father, your aunt, your uncle and -your 17 cousins to coordinate the next christmas party. - -That's where sticky articles come in handy. A sticky article buffer -basically is a normal article buffer, but it won't be reused when you -select another article. You can make an article sticky with: - -@table @kbd -@item A S -@kindex A S (Summary) -@findex gnus-sticky-article -Make the current article sticky. If a prefix arg is given, ask for a -name for this sticky article buffer. -@end table - -To close a sticky article buffer you can use these commands: - -@table @kbd -@item q -@kindex q (Article) -@findex bury-buffer -Puts this sticky article buffer at the end of the list of all buffers. - -@item k -@kindex k (Article) -@findex gnus-kill-sticky-article-buffer -Kills this sticky article buffer. -@end table - -To kill all sticky article buffers you can use: - -@defun gnus-kill-sticky-article-buffers ARG -Kill all sticky article buffers. -If a prefix ARG is given, ask for confirmation. -@end defun - -@node Article Backlog -@section Article Backlog -@cindex backlog -@cindex article backlog - -If you have a slow connection, but the idea of using caching seems -unappealing to you (and it is, really), you can help the situation some -by switching on the @dfn{backlog}. This is where Gnus will buffer -already read articles so that it doesn't have to re-fetch articles -you've already read. This only helps if you are in the habit of -re-selecting articles you've recently read, of course. If you never do -that, turning the backlog on will slow Gnus down a little bit, and -increase memory usage some. - -@vindex gnus-keep-backlog -If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store -at most @var{n} old articles in a buffer for later re-fetching. If this -variable is non-@code{nil} and is not a number, Gnus will store -@emph{all} read articles, which means that your Emacs will grow without -bound before exploding and taking your machine down with you. I put -that in there just to keep y'all on your toes. - -The default value is 20. - - -@node Saving Articles -@section Saving Articles -@cindex saving articles - -Gnus can save articles in a number of ways. Below is the documentation -for saving articles in a fairly straight-forward fashion (i.e., little -processing of the article is done before it is saved). For a different -approach (uudecoding, unsharing) you should use @code{gnus-uu} -(@pxref{Decoding Articles}). - -For the commands listed here, the target is a file. If you want to -save to a group, see the @kbd{B c} (@code{gnus-summary-copy-article}) -command (@pxref{Mail Group Commands}). - -@vindex gnus-save-all-headers -If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete -unwanted headers before saving the article. - -@vindex gnus-saved-headers -If the preceding variable is @code{nil}, all headers that match the -@code{gnus-saved-headers} regexp will be kept, while the rest will be -deleted before saving. - -@table @kbd - -@item O o -@itemx o -@kindex O o (Summary) -@kindex o (Summary) -@findex gnus-summary-save-article -@c @icon{gnus-summary-save-article} -Save the current article using the default article saver -(@code{gnus-summary-save-article}). - -@item O m -@kindex O m (Summary) -@findex gnus-summary-save-article-mail -Save the current article in a Unix mail box (mbox) file -(@code{gnus-summary-save-article-mail}). - -@item O r -@kindex O r (Summary) -@findex gnus-summary-save-article-rmail -Save the current article in Rmail format -(@code{gnus-summary-save-article-rmail}). This is mbox since Emacs 23, -Babyl in older versions. - -@item O f -@kindex O f (Summary) -@findex gnus-summary-save-article-file -@c @icon{gnus-summary-save-article-file} -Save the current article in plain file format -(@code{gnus-summary-save-article-file}). - -@item O F -@kindex O F (Summary) -@findex gnus-summary-write-article-file -Write the current article in plain file format, overwriting any previous -file contents (@code{gnus-summary-write-article-file}). - -@item O b -@kindex O b (Summary) -@findex gnus-summary-save-article-body-file -Save the current article body in plain file format -(@code{gnus-summary-save-article-body-file}). - -@item O h -@kindex O h (Summary) -@findex gnus-summary-save-article-folder -Save the current article in mh folder format -(@code{gnus-summary-save-article-folder}). - -@item O v -@kindex O v (Summary) -@findex gnus-summary-save-article-vm -Save the current article in a VM folder -(@code{gnus-summary-save-article-vm}). - -@item O p -@itemx | -@kindex O p (Summary) -@kindex | (Summary) -@findex gnus-summary-pipe-output -@vindex gnus-summary-pipe-output-default-command -Save the current article in a pipe. Uhm, like, what I mean is---Pipe -the current article to a process (@code{gnus-summary-pipe-output}). -If given a symbolic prefix (@pxref{Symbolic Prefixes}), include the -complete headers in the piped output. The symbolic prefix @code{r} is -special; it lets this command pipe a raw article including all headers. -The @code{gnus-summary-pipe-output-default-command} variable can be set -to a string containing the default command and options (default -@code{nil}). - -@item O P -@kindex O P (Summary) -@findex gnus-summary-muttprint -@vindex gnus-summary-muttprint-program -Save the current article into muttprint. That is, print it using the -external program @uref{http://muttprint.sourceforge.net/, -Muttprint}. The program name and options to use is controlled by the -variable @code{gnus-summary-muttprint-program}. -(@code{gnus-summary-muttprint}). - -@end table - -@vindex gnus-prompt-before-saving -All these commands use the process/prefix convention -(@pxref{Process/Prefix}). If you save bunches of articles using these -functions, you might get tired of being prompted for files to save each -and every article in. The prompting action is controlled by -the @code{gnus-prompt-before-saving} variable, which is @code{always} by -default, giving you that excessive prompting action you know and -loathe. If you set this variable to @code{t} instead, you'll be prompted -just once for each series of articles you save. If you like to really -have Gnus do all your thinking for you, you can even set this variable -to @code{nil}, which means that you will never be prompted for files to -save articles in. Gnus will simply save all the articles in the default -files. - - -@vindex gnus-default-article-saver -You can customize the @code{gnus-default-article-saver} variable to make -Gnus do what you want it to. You can use any of the eight ready-made -functions below, or you can create your own. - -@table @code - -@item gnus-summary-save-in-rmail -@findex gnus-summary-save-in-rmail -@vindex gnus-rmail-save-name -@findex gnus-plain-save-name -This is the default format, that used by the Rmail package. Since Emacs -23, Rmail uses standard mbox format. Before this, it used the -@dfn{Babyl} format. Accordingly, this command writes mbox format since -Emacs 23, unless appending to an existing Babyl file. In older versions -of Emacs, it always uses Babyl format. Uses the function in the -@code{gnus-rmail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-mail -@findex gnus-summary-save-in-mail -@vindex gnus-mail-save-name -Save in a Unix mail (mbox) file. Uses the function in the -@code{gnus-mail-save-name} variable to get a file name to save the -article in. The default is @code{gnus-plain-save-name}. - -@item gnus-summary-save-in-file -@findex gnus-summary-save-in-file -@vindex gnus-file-save-name -@findex gnus-numeric-save-name -Append the article straight to an ordinary file. Uses the function in -the @code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-to-file -@findex gnus-summary-write-to-file -Write the article straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-body-in-file -@findex gnus-summary-save-body-in-file -Append the article body to an ordinary file. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-write-body-to-file -@findex gnus-summary-write-body-to-file -Write the article body straight to an ordinary file. The file is -overwritten if it exists. Uses the function in the -@code{gnus-file-save-name} variable to get a file name to save the -article in. The default is @code{gnus-numeric-save-name}. - -@item gnus-summary-save-in-folder -@findex gnus-summary-save-in-folder -@findex gnus-folder-save-name -@findex gnus-Folder-save-name -@vindex gnus-folder-save-name -@cindex rcvstore -@cindex MH folders -Save the article to an MH folder using @code{rcvstore} from the MH -library. Uses the function in the @code{gnus-folder-save-name} variable -to get a file name to save the article in. The default is -@code{gnus-folder-save-name}, but you can also use -@code{gnus-Folder-save-name}, which creates capitalized names. - -@item gnus-summary-save-in-vm -@findex gnus-summary-save-in-vm -Save the article in a VM folder. You have to have the VM mail -reader to use this setting. - -@item gnus-summary-save-in-pipe -@findex gnus-summary-save-in-pipe -Pipe the article to a shell command. This function takes optional two -arguments COMMAND and RAW. Valid values for COMMAND include: - -@itemize @bullet -@item a string@* -The executable command name and possibly arguments. -@item @code{nil}@* -You will be prompted for the command in the minibuffer. -@item the symbol @code{default}@* -It will be replaced with the command which the variable -@code{gnus-summary-pipe-output-default-command} holds or the command -last used for saving. -@end itemize - -Non-@code{nil} value for RAW overrides @code{:decode} and -@code{:headers} properties (see below) and the raw article including all -headers will be piped. -@end table - -The symbol of each function may have the following properties: - -@table @code -@item :decode -The value non-@code{nil} means save decoded articles. This is -meaningful only with @code{gnus-summary-save-in-file}, -@code{gnus-summary-save-body-in-file}, -@code{gnus-summary-write-to-file}, -@code{gnus-summary-write-body-to-file}, and -@code{gnus-summary-save-in-pipe}. - -@item :function -The value specifies an alternative function which appends, not -overwrites, articles to a file. This implies that when saving many -articles at a time, @code{gnus-prompt-before-saving} is bound to -@code{t} and all articles are saved in a single file. This is -meaningful only with @code{gnus-summary-write-to-file} and -@code{gnus-summary-write-body-to-file}. - -@item :headers -The value specifies the symbol of a variable of which the value -specifies headers to be saved. If it is omitted, -@code{gnus-save-all-headers} and @code{gnus-saved-headers} control what -headers should be saved. -@end table - -@vindex gnus-article-save-directory -All of these functions, except for the last one, will save the article -in the @code{gnus-article-save-directory}, which is initialized from the -@env{SAVEDIR} environment variable. This is @file{~/News/} by -default. - -As you can see above, the functions use different functions to find a -suitable name of a file to save the article in. Below is a list of -available functions that generate names: - -@table @code - -@item gnus-Numeric-save-name -@findex gnus-Numeric-save-name -File names like @file{~/News/Alt.andrea-dworkin/45}. - -@item gnus-numeric-save-name -@findex gnus-numeric-save-name -File names like @file{~/News/alt.andrea-dworkin/45}. - -@item gnus-Plain-save-name -@findex gnus-Plain-save-name -File names like @file{~/News/Alt.andrea-dworkin}. - -@item gnus-plain-save-name -@findex gnus-plain-save-name -File names like @file{~/News/alt.andrea-dworkin}. - -@item gnus-sender-save-name -@findex gnus-sender-save-name -File names like @file{~/News/larsi}. -@end table - -@vindex gnus-split-methods -You can have Gnus suggest where to save articles by plonking a regexp into -the @code{gnus-split-methods} alist. For instance, if you would like to -save articles related to Gnus in the file @file{gnus-stuff}, and articles -related to VM in @file{vm-stuff}, you could set this variable to something -like: - -@lisp -(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") - ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") - (my-choosing-function "../other-dir/my-stuff") - ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) -@end lisp - -We see that this is a list where each element is a list that has two -elements---the @dfn{match} and the @dfn{file}. The match can either be -a string (in which case it is used as a regexp to match on the article -head); it can be a symbol (which will be called as a function with the -group name as a parameter); or it can be a list (which will be -@code{eval}ed). If any of these actions have a non-@code{nil} result, -the @dfn{file} will be used as a default prompt. In addition, the -result of the operation itself will be used if the function or form -called returns a string or a list of strings. - -You basically end up with a list of file names that might be used when -saving the current article. (All ``matches'' will be used.) You will -then be prompted for what you really want to use as a name, with file -name completion over the results from applying this variable. - -This variable is @code{((gnus-article-archive-name))} by default, which -means that Gnus will look at the articles it saves for an -@code{Archive-name} line and use that as a suggestion for the file -name. - -Here's an example function to clean up file names somewhat. If you have -lots of mail groups called things like -@samp{nnml:mail.whatever}, you may want to chop off the beginning of -these group names before creating the file name to save to. The -following will do just that: - -@lisp -(defun my-save-name (group) - (when (string-match "^nnml:mail." group) - (substring group (match-end 0)))) - -(setq gnus-split-methods - '((gnus-article-archive-name) - (my-save-name))) -@end lisp - - -@vindex gnus-use-long-file-name -Finally, you have the @code{gnus-use-long-file-name} variable. If it is -@code{nil}, all the preceding functions will replace all periods -(@samp{.}) in the group names with slashes (@samp{/})---which means that -the functions will generate hierarchies of directories instead of having -all the files in the top level directory -(@file{~/News/alt/andrea-dworkin} instead of -@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default -on most systems. However, for historical reasons, this is @code{nil} on -Xenix and usg-unix-v machines by default. - -This function also affects kill and score file names. If this variable -is a list, and the list contains the element @code{not-score}, long file -names will not be used for score files, if it contains the element -@code{not-save}, long file names will not be used for saving, and if it -contains the element @code{not-kill}, long file names will not be used -for kill files. - -If you'd like to save articles in a hierarchy that looks something like -a spool, you could - -@lisp -(setq gnus-use-long-file-name '(not-save)) ; @r{to get a hierarchy} -(setq gnus-default-article-saver - 'gnus-summary-save-in-file) ; @r{no encoding} -@end lisp - -Then just save with @kbd{o}. You'd then read this hierarchy with -ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and -the top level directory as the argument (@file{~/News/}). Then just walk -around to the groups/directories with @code{nneething}. - - -@node Decoding Articles -@section Decoding Articles -@cindex decoding articles - -Sometime users post articles (or series of articles) that have been -encoded in some way or other. Gnus can decode them for you. - -@menu -* Uuencoded Articles:: Uudecode articles. -* Shell Archives:: Unshar articles. -* PostScript Files:: Split PostScript. -* Other Files:: Plain save and binhex. -* Decoding Variables:: Variables for a happy decoding. -* Viewing Files:: You want to look at the result of the decoding? -@end menu - -@cindex series -@cindex article series -All these functions use the process/prefix convention -(@pxref{Process/Prefix}) for finding out what articles to work on, with -the extension that a ``single article'' means ``a single series''. Gnus -can find out by itself what articles belong to a series, decode all the -articles and unpack/view/save the resulting file(s). - -Gnus guesses what articles are in the series according to the following -simplish rule: The subjects must be (nearly) identical, except for the -last two numbers of the line. (Spaces are largely ignored, however.) - -For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus -will find all the articles that match the regexp @samp{^cat.gif -([0-9]+/[0-9]+).*$}. - -Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a -series}, will not be properly recognized by any of the automatic viewing -commands, and you have to mark the articles manually with @kbd{#}. - - -@node Uuencoded Articles -@subsection Uuencoded Articles -@cindex uudecode -@cindex uuencoded articles - -@table @kbd - -@item X u -@kindex X u (Summary) -@findex gnus-uu-decode-uu -@c @icon{gnus-uu-decode-uu} -Uudecodes the current series (@code{gnus-uu-decode-uu}). - -@item X U -@kindex X U (Summary) -@findex gnus-uu-decode-uu-and-save -Uudecodes and saves the current series -(@code{gnus-uu-decode-uu-and-save}). - -@item X v u -@kindex X v u (Summary) -@findex gnus-uu-decode-uu-view -Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). - -@item X v U -@kindex X v U (Summary) -@findex gnus-uu-decode-uu-and-save-view -Uudecodes, views and saves the current series -(@code{gnus-uu-decode-uu-and-save-view}). - -@end table - -Remember that these all react to the presence of articles marked with -the process mark. If, for instance, you'd like to decode and save an -entire newsgroup, you'd typically do @kbd{M P a} -(@code{gnus-uu-mark-all}) and then @kbd{X U} -(@code{gnus-uu-decode-uu-and-save}). - -All this is very much different from how @code{gnus-uu} worked with -@sc{gnus 4.1}, where you had explicit keystrokes for everything under -the sun. This version of @code{gnus-uu} generally assumes that you mark -articles in some way (@pxref{Setting Process Marks}) and then press -@kbd{X u}. - -@vindex gnus-uu-notify-files -Note: When trying to decode articles that have names matching -@code{gnus-uu-notify-files}, which is hard-coded to -@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will -automatically post an article on @samp{comp.unix.wizards} saying that -you have just viewed the file in question. This feature can't be turned -off. - - -@node Shell Archives -@subsection Shell Archives -@cindex unshar -@cindex shell archives -@cindex shared articles - -Shell archives (``shar files'') used to be a popular way to distribute -sources, but it isn't used all that much today. In any case, we have -some commands to deal with these: - -@table @kbd - -@item X s -@kindex X s (Summary) -@findex gnus-uu-decode-unshar -Unshars the current series (@code{gnus-uu-decode-unshar}). - -@item X S -@kindex X S (Summary) -@findex gnus-uu-decode-unshar-and-save -Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). - -@item X v s -@kindex X v s (Summary) -@findex gnus-uu-decode-unshar-view -Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). - -@item X v S -@kindex X v S (Summary) -@findex gnus-uu-decode-unshar-and-save-view -Unshars, views and saves the current series -(@code{gnus-uu-decode-unshar-and-save-view}). -@end table - - -@node PostScript Files -@subsection PostScript Files -@cindex PostScript - -@table @kbd - -@item X p -@kindex X p (Summary) -@findex gnus-uu-decode-postscript -Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). - -@item X P -@kindex X P (Summary) -@findex gnus-uu-decode-postscript-and-save -Unpack and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save}). - -@item X v p -@kindex X v p (Summary) -@findex gnus-uu-decode-postscript-view -View the current PostScript series -(@code{gnus-uu-decode-postscript-view}). - -@item X v P -@kindex X v P (Summary) -@findex gnus-uu-decode-postscript-and-save-view -View and save the current PostScript series -(@code{gnus-uu-decode-postscript-and-save-view}). -@end table - - -@node Other Files -@subsection Other Files - -@table @kbd -@item X o -@kindex X o (Summary) -@findex gnus-uu-decode-save -Save the current series -(@code{gnus-uu-decode-save}). - -@item X b -@kindex X b (Summary) -@findex gnus-uu-decode-binhex -Unbinhex the current series (@code{gnus-uu-decode-binhex}). This -doesn't really work yet. - -@item X Y -@kindex X Y (Summary) -@findex gnus-uu-decode-yenc -yEnc-decode the current series and save it (@code{gnus-uu-decode-yenc}). -@end table - - -@node Decoding Variables -@subsection Decoding Variables - -Adjective, not verb. - -@menu -* Rule Variables:: Variables that say how a file is to be viewed. -* Other Decode Variables:: Other decode variables. -* Uuencoding and Posting:: Variables for customizing uuencoding. -@end menu - - -@node Rule Variables -@subsubsection Rule Variables -@cindex rule variables - -Gnus uses @dfn{rule variables} to decide how to view a file. All these -variables are of the form - -@lisp - (list '(regexp1 command2) - '(regexp2 command2) - ...) -@end lisp - -@table @code - -@item gnus-uu-user-view-rules -@vindex gnus-uu-user-view-rules -@cindex sox -This variable is consulted first when viewing files. If you wish to use, -for instance, @code{sox} to convert an @file{.au} sound file, you could -say something like: -@lisp -(setq gnus-uu-user-view-rules - (list '("\\\\.au$" "sox %s -t .aiff > /dev/audio"))) -@end lisp - -@item gnus-uu-user-view-rules-end -@vindex gnus-uu-user-view-rules-end -This variable is consulted if Gnus couldn't make any matches from the -user and default view rules. - -@item gnus-uu-user-archive-rules -@vindex gnus-uu-user-archive-rules -This variable can be used to say what commands should be used to unpack -archives. -@end table - - -@node Other Decode Variables -@subsubsection Other Decode Variables - -@table @code -@vindex gnus-uu-grabbed-file-functions - -@item gnus-uu-grabbed-file-functions -All functions in this list will be called right after each file has been -successfully decoded---so that you can move or view files right away, -and don't have to wait for all files to be decoded before you can do -anything. Ready-made functions you can put in this list are: - -@table @code - -@item gnus-uu-grab-view -@findex gnus-uu-grab-view -View the file. - -@item gnus-uu-grab-move -@findex gnus-uu-grab-move -Move the file (if you're using a saving function.) -@end table - -@item gnus-uu-be-dangerous -@vindex gnus-uu-be-dangerous -Specifies what to do if unusual situations arise during decoding. If -@code{nil}, be as conservative as possible. If @code{t}, ignore things -that didn't work, and overwrite existing files. Otherwise, ask each -time. - -@item gnus-uu-ignore-files-by-name -@vindex gnus-uu-ignore-files-by-name -Files with name matching this regular expression won't be viewed. - -@item gnus-uu-ignore-files-by-type -@vindex gnus-uu-ignore-files-by-type -Files with a @acronym{MIME} type matching this variable won't be viewed. -Note that Gnus tries to guess what type the file is based on the name. -@code{gnus-uu} is not a @acronym{MIME} package (yet), so this is slightly -kludgey. - -@item gnus-uu-tmp-dir -@vindex gnus-uu-tmp-dir -Where @code{gnus-uu} does its work. - -@item gnus-uu-do-not-unpack-archives -@vindex gnus-uu-do-not-unpack-archives -Non-@code{nil} means that @code{gnus-uu} won't peek inside archives -looking for files to display. - -@item gnus-uu-view-and-save -@vindex gnus-uu-view-and-save -Non-@code{nil} means that the user will always be asked to save a file -after viewing it. - -@item gnus-uu-ignore-default-view-rules -@vindex gnus-uu-ignore-default-view-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing -rules. - -@item gnus-uu-ignore-default-archive-rules -@vindex gnus-uu-ignore-default-archive-rules -Non-@code{nil} means that @code{gnus-uu} will ignore the default archive -unpacking commands. - -@item gnus-uu-kill-carriage-return -@vindex gnus-uu-kill-carriage-return -Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns -from articles. - -@item gnus-uu-unmark-articles-not-decoded -@vindex gnus-uu-unmark-articles-not-decoded -Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully -decoded articles as unread. - -@item gnus-uu-correct-stripped-uucode -@vindex gnus-uu-correct-stripped-uucode -Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix -uuencoded files that have had trailing spaces deleted. - -@item gnus-uu-pre-uudecode-hook -@vindex gnus-uu-pre-uudecode-hook -Hook run before sending a message to @code{uudecode}. - -@item gnus-uu-view-with-metamail -@vindex gnus-uu-view-with-metamail -@cindex metamail -Non-@code{nil} means that @code{gnus-uu} will ignore the viewing -commands defined by the rule variables and just fudge a @acronym{MIME} -content type based on the file name. The result will be fed to -@code{metamail} for viewing. - -@item gnus-uu-save-in-digest -@vindex gnus-uu-save-in-digest -Non-@code{nil} means that @code{gnus-uu}, when asked to save without -decoding, will save in digests. If this variable is @code{nil}, -@code{gnus-uu} will just save everything in a file without any -embellishments. The digesting almost conforms to RFC 1153---no easy way -to specify any meaningful volume and issue numbers were found, so I -simply dropped them. - -@end table - - -@node Uuencoding and Posting -@subsubsection Uuencoding and Posting - -@table @code - -@item gnus-uu-post-include-before-composing -@vindex gnus-uu-post-include-before-composing -Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode -before you compose the article. If this variable is @code{t}, you can -either include an encoded file with @kbd{C-c C-i} or have one included -for you when you post the article. - -@item gnus-uu-post-length -@vindex gnus-uu-post-length -Maximum length of an article. The encoded file will be split into how -many articles it takes to post the entire file. - -@item gnus-uu-post-threaded -@vindex gnus-uu-post-threaded -Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a -thread. This may not be smart, as no other decoder I have seen is able -to follow threads when collecting uuencoded articles. (Well, I have -seen one package that does that---@code{gnus-uu}, but somehow, I don't -think that counts@dots{}) Default is @code{nil}. - -@item gnus-uu-post-separate-description -@vindex gnus-uu-post-separate-description -Non-@code{nil} means that the description will be posted in a separate -article. The first article will typically be numbered (0/x). If this -variable is @code{nil}, the description the user enters will be included -at the beginning of the first article, which will be numbered (1/x). -Default is @code{t}. - -@end table - - -@node Viewing Files -@subsection Viewing Files -@cindex viewing files -@cindex pseudo-articles - -After decoding, if the file is some sort of archive, Gnus will attempt -to unpack the archive and see if any of the files in the archive can be -viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} -containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will -uncompress and de-tar the main file, and then view the two pictures. -This unpacking process is recursive, so if the archive contains archives -of archives, it'll all be unpacked. - -Finally, Gnus will normally insert a @dfn{pseudo-article} for each -extracted file into the summary buffer. If you go to these -``articles'', you will be prompted for a command to run (usually Gnus -will make a suggestion), and then the command will be run. - -@vindex gnus-view-pseudo-asynchronously -If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait -until the viewing is done before proceeding. - -@vindex gnus-view-pseudos -If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert -the pseudo-articles into the summary buffer, but view them -immediately. If this variable is @code{not-confirm}, the user won't even -be asked for a confirmation before viewing is done. - -@vindex gnus-view-pseudos-separately -If @code{gnus-view-pseudos-separately} is non-@code{nil}, one -pseudo-article will be created for each file to be viewed. If -@code{nil}, all files that use the same viewing command will be given as -a list of parameters to that command. - -@vindex gnus-insert-pseudo-articles -If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert -pseudo-articles when decoding. It is @code{t} by default. - -So; there you are, reading your @emph{pseudo-articles} in your -@emph{virtual newsgroup} from the @emph{virtual server}; and you think: -Why isn't anything real anymore? How did we get here? - - -@node Article Treatment -@section Article Treatment - -Reading through this huge manual, you may have quite forgotten that the -object of newsreaders is to actually, like, read what people have -written. Reading articles. Unfortunately, people are quite bad at -writing, so there are tons of functions and variables to make reading -these articles easier. - -@menu -* Article Highlighting:: You want to make the article look like fruit salad. -* Article Fontisizing:: Making emphasized text look nice. -* Article Hiding:: You also want to make certain info go away. -* Article Washing:: Lots of way-neat functions to make life better. -* Article Header:: Doing various header transformations. -* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. -* Article Button Levels:: Controlling appearance of buttons. -* Article Date:: Grumble, UT! -* Article Display:: Display various stuff---X-Face, Picons, Smileys -* Article Signature:: What is a signature? -* Article Miscellanea:: Various other stuff. -@end menu - - -@node Article Highlighting -@subsection Article Highlighting -@cindex highlighting - -Not only do you want your article buffer to look like fruit salad, but -you want it to look like technicolor fruit salad. - -@table @kbd - -@item W H a -@kindex W H a (Summary) -@findex gnus-article-highlight -@findex gnus-article-maybe-highlight -Do much highlighting of the current article -(@code{gnus-article-highlight}). This function highlights header, cited -text, the signature, and adds buttons to the body and the head. - -@item W H h -@kindex W H h (Summary) -@findex gnus-article-highlight-headers -@vindex gnus-header-face-alist -Highlight the headers (@code{gnus-article-highlight-headers}). The -highlighting will be done according to the @code{gnus-header-face-alist} -variable, which is a list where each element has the form -@code{(@var{regexp} @var{name} @var{content})}. -@var{regexp} is a regular expression for matching the -header, @var{name} is the face used for highlighting the header name -(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting -the header value. The first match made will be used. Note that -@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. - -@item W H c -@kindex W H c (Summary) -@findex gnus-article-highlight-citation -Highlight cited text (@code{gnus-article-highlight-citation}). - -Some variables to customize the citation highlights: - -@table @code -@vindex gnus-cite-parse-max-size - -@item gnus-cite-parse-max-size -If the article size in bytes is bigger than this variable (which is -25000 by default), no citation highlighting will be performed. - -@item gnus-cite-max-prefix -@vindex gnus-cite-max-prefix -Maximum possible length for a citation prefix (default 20). - -@item gnus-cite-face-list -@vindex gnus-cite-face-list -List of faces used for highlighting citations (@pxref{Faces and Fonts}). -When there are citations from multiple articles in the same message, -Gnus will try to give each citation from each article its own face. -This should make it easier to see who wrote what. - -@item gnus-supercite-regexp -@vindex gnus-supercite-regexp -Regexp matching normal Supercite attribution lines. - -@item gnus-supercite-secondary-regexp -@vindex gnus-supercite-secondary-regexp -Regexp matching mangled Supercite attribution lines. - -@item gnus-cite-minimum-match-count -@vindex gnus-cite-minimum-match-count -Minimum number of identical prefixes we have to see before we believe -that it's a citation. - -@item gnus-cite-attribution-prefix -@vindex gnus-cite-attribution-prefix -Regexp matching the beginning of an attribution line. - -@item gnus-cite-attribution-suffix -@vindex gnus-cite-attribution-suffix -Regexp matching the end of an attribution line. - -@item gnus-cite-attribution-face -@vindex gnus-cite-attribution-face -Face used for attribution lines. It is merged with the face for the -cited text belonging to the attribution. - -@item gnus-cite-ignore-quoted-from -@vindex gnus-cite-ignore-quoted-from -If non-@code{nil}, no citation highlighting will be performed on lines -beginning with @samp{>From }. Those lines may have been quoted by MTAs -in order not to mix up with the envelope From line. The default value -is @code{t}. - -@end table - - -@item W H s -@kindex W H s (Summary) -@vindex gnus-signature-separator -@vindex gnus-signature-face -@findex gnus-article-highlight-signature -Highlight the signature (@code{gnus-article-highlight-signature}). -Everything after @code{gnus-signature-separator} (@pxref{Article -Signature}) in an article will be considered a signature and will be -highlighted with @code{gnus-signature-face}, which is @code{italic} by -default. - -@end table - -@xref{Customizing Articles}, for how to highlight articles automatically. - - -@node Article Fontisizing -@subsection Article Fontisizing -@cindex emphasis -@cindex article emphasis - -@findex gnus-article-emphasize -@kindex W e (Summary) -People commonly add emphasis to words in news articles by writing things -like @samp{_this_} or @samp{*this*} or @samp{/this/}. Gnus can make -this look nicer by running the article through the @kbd{W e} -(@code{gnus-article-emphasize}) command. - -@vindex gnus-emphasis-alist -How the emphasis is computed is controlled by the -@code{gnus-emphasis-alist} variable. This is an alist where the first -element is a regular expression to be matched. The second is a number -that says what regular expression grouping is used to find the entire -emphasized word. The third is a number that says what regexp grouping -should be displayed and highlighted. (The text between these two -groupings will be hidden.) The fourth is the face used for -highlighting. - -@lisp -(setq gnus-emphasis-alist - '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) - ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) -@end lisp - -@cindex slash -@cindex asterisk -@cindex underline -@cindex / -@cindex * - -@vindex gnus-emphasis-underline -@vindex gnus-emphasis-bold -@vindex gnus-emphasis-italic -@vindex gnus-emphasis-underline-bold -@vindex gnus-emphasis-underline-italic -@vindex gnus-emphasis-bold-italic -@vindex gnus-emphasis-underline-bold-italic -By default, there are seven rules, and they use the following faces: -@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, -@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, -@code{gnus-emphasis-underline-italic}, -@code{gnus-emphasis-underline-bold}, and -@code{gnus-emphasis-underline-bold-italic}. - -If you want to change these faces, you can either use @kbd{M-x -customize}, or you can use @code{copy-face}. For instance, if you want -to make @code{gnus-emphasis-italic} use a red face instead, you could -say something like: - -@lisp -(copy-face 'red 'gnus-emphasis-italic) -@end lisp - -@vindex gnus-group-highlight-words-alist - -If you want to highlight arbitrary words, you can use the -@code{gnus-group-highlight-words-alist} variable, which uses the same -syntax as @code{gnus-emphasis-alist}. The @code{highlight-words} group -parameter (@pxref{Group Parameters}) can also be used. - -@xref{Customizing Articles}, for how to fontize articles automatically. - - -@node Article Hiding -@subsection Article Hiding -@cindex article hiding - -Or rather, hiding certain things in each article. There usually is much -too much cruft in most articles. - -@table @kbd - -@item W W a -@kindex W W a (Summary) -@findex gnus-article-hide -Do quite a lot of hiding on the article buffer -(@kbd{gnus-article-hide}). In particular, this function will hide -headers, @acronym{PGP}, cited text and the signature. - -@item W W h -@kindex W W h (Summary) -@findex gnus-article-hide-headers -Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding -Headers}. - -@item W W b -@kindex W W b (Summary) -@findex gnus-article-hide-boring-headers -Hide headers that aren't particularly interesting -(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. - -@item W W s -@kindex W W s (Summary) -@findex gnus-article-hide-signature -Hide signature (@code{gnus-article-hide-signature}). @xref{Article -Signature}. - -@item W W l -@kindex W W l (Summary) -@findex gnus-article-hide-list-identifiers -@vindex gnus-list-identifiers -Strip list identifiers specified in @code{gnus-list-identifiers}. These -are strings some mailing list servers add to the beginning of all -@code{Subject} headers---for example, @samp{[zebra 4711]}. Any leading -@samp{Re: } is skipped before stripping. @code{gnus-list-identifiers} -may not contain @code{\\(..\\)}. - -@table @code - -@item gnus-list-identifiers -@vindex gnus-list-identifiers -A regular expression that matches list identifiers to be removed from -subject. This can also be a list of regular expressions. - -@end table - -@item W W P -@kindex W W P (Summary) -@findex gnus-article-hide-pem -Hide @acronym{PEM} (privacy enhanced messages) cruft -(@code{gnus-article-hide-pem}). - -@item W W B -@kindex W W B (Summary) -@findex gnus-article-strip-banner -@vindex gnus-article-banner-alist -@vindex gnus-article-address-banner-alist -@cindex banner -@cindex OneList -@cindex stripping advertisements -@cindex advertisements -Strip the banner specified by the @code{banner} group parameter -(@code{gnus-article-strip-banner}). This is mainly used to hide those -annoying banners and/or signatures that some mailing lists and moderated -groups adds to all the messages. The way to use this function is to add -the @code{banner} group parameter (@pxref{Group Parameters}) to the -group you want banners stripped from. The parameter either be a string, -which will be interpreted as a regular expression matching text to be -removed, or the symbol @code{signature}, meaning that the (last) -signature should be removed, or other symbol, meaning that the -corresponding regular expression in @code{gnus-article-banner-alist} is -used. - -Regardless of a group, you can hide things like advertisements only when -the sender of an article has a certain mail address specified in -@code{gnus-article-address-banner-alist}. - -@table @code - -@item gnus-article-address-banner-alist -@vindex gnus-article-address-banner-alist -Alist of mail addresses and banners. Each element has the form -@code{(@var{address} . @var{banner})}, where @var{address} is a regexp -matching a mail address in the From header, @var{banner} is one of a -symbol @code{signature}, an item in @code{gnus-article-banner-alist}, -a regexp and @code{nil}. If @var{address} matches author's mail -address, it will remove things like advertisements. For example, if a -sender has the mail address @samp{hail@@yoo-hoo.co.jp} and there is a -banner something like @samp{Do You Yoo-hoo!?} in all articles he -sends, you can use the following element to remove them: - -@lisp -("@@yoo-hoo\\.co\\.jp\\'" . - "\n_+\nDo You Yoo-hoo!\\?\n.*\n.*\n") -@end lisp - -@end table - -@item W W c -@kindex W W c (Summary) -@findex gnus-article-hide-citation -Hide citation (@code{gnus-article-hide-citation}). Some variables for -customizing the hiding: - -@table @code - -@item gnus-cited-opened-text-button-line-format -@itemx gnus-cited-closed-text-button-line-format -@vindex gnus-cited-closed-text-button-line-format -@vindex gnus-cited-opened-text-button-line-format -Gnus adds buttons to show where the cited text has been hidden, and to -allow toggle hiding the text. The format of the variable is specified -by these format-like variable (@pxref{Formatting Variables}). These -specs are valid: - -@table @samp -@item b -Starting point of the hidden text. -@item e -Ending point of the hidden text. -@item l -Number of characters in the hidden region. -@item n -Number of lines of hidden text. -@end table - -@item gnus-cited-lines-visible -@vindex gnus-cited-lines-visible -The number of lines at the beginning of the cited text to leave -shown. This can also be a cons cell with the number of lines at the top -and bottom of the text, respectively, to remain visible. - -@end table - -@item W W C-c -@kindex W W C-c (Summary) -@findex gnus-article-hide-citation-maybe - -Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the -following two variables: - -@table @code -@item gnus-cite-hide-percentage -@vindex gnus-cite-hide-percentage -If the cited text is of a bigger percentage than this variable (default -50), hide the cited text. - -@item gnus-cite-hide-absolute -@vindex gnus-cite-hide-absolute -The cited text must have at least this length (default 10) before it -is hidden. -@end table - -@item W W C -@kindex W W C (Summary) -@findex gnus-article-hide-citation-in-followups -Hide cited text in articles that aren't roots -(@code{gnus-article-hide-citation-in-followups}). This isn't very -useful as an interactive command, but might be a handy function to stick -have happen automatically (@pxref{Customizing Articles}). - -@end table - -All these ``hiding'' commands are toggles, but if you give a negative -prefix to these commands, they will show what they have previously -hidden. If you give a positive prefix, they will always hide. - -Also @pxref{Article Highlighting} for further variables for -citation customization. - -@xref{Customizing Articles}, for how to hide article elements -automatically. - - -@node Article Washing -@subsection Article Washing -@cindex washing -@cindex article washing - -We call this ``article washing'' for a really good reason. Namely, the -@kbd{A} key was taken, so we had to use the @kbd{W} key instead. - -@dfn{Washing} is defined by us as ``changing something from something to -something else'', but normally results in something looking better. -Cleaner, perhaps. - -@xref{Customizing Articles}, if you want to change how Gnus displays -articles by default. - -@table @kbd - -@item C-u g -This is not really washing, it's sort of the opposite of washing. If -you type this, you see the article exactly as it exists on disk or on -the server. - -@item g -Force redisplaying of the current article -(@code{gnus-summary-show-article}). This is also not really washing. -If you type this, you see the article without any previously applied -interactive Washing functions but with all default treatments -(@pxref{Customizing Articles}). - -@item W l -@kindex W l (Summary) -@findex gnus-summary-stop-page-breaking -Remove page breaks from the current article -(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page -delimiters. - -@item W r -@kindex W r (Summary) -@findex gnus-summary-caesar-message -@c @icon{gnus-summary-caesar-message} -Do a Caesar rotate (rot13) on the article buffer -(@code{gnus-summary-caesar-message}). -Unreadable articles that tell you to read them with Caesar rotate or rot13. -(Typically offensive jokes and such.) - -It's commonly called ``rot13'' because each letter is rotated 13 -positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter -#15). It is sometimes referred to as ``Caesar rotate'' because Caesar -is rumored to have employed this form of, uh, somewhat weak encryption. - -@item W m -@kindex W m (Summary) -@findex gnus-summary-morse-message -Morse decode the article buffer (@code{gnus-summary-morse-message}). - -@item W i -@kindex W i (Summary) -@findex gnus-summary-idna-message -Decode IDNA encoded domain names in the current articles. IDNA -encoded domain names looks like @samp{xn--bar}. If a string remain -unencoded after running invoking this, it is likely an invalid IDNA -string (@samp{xn--bar} is invalid). You must have GNU Libidn -(@url{http://www.gnu.org/software/libidn/}) installed for this command -to work. - -@item W t -@item t -@kindex W t (Summary) -@kindex t (Summary) -@findex gnus-summary-toggle-header -Toggle whether to display all headers in the article buffer -(@code{gnus-summary-toggle-header}). - -@item W v -@kindex W v (Summary) -@findex gnus-summary-verbose-headers -Toggle whether to display all headers in the article buffer permanently -(@code{gnus-summary-verbose-headers}). - -@item W o -@kindex W o (Summary) -@findex gnus-article-treat-overstrike -Treat overstrike (@code{gnus-article-treat-overstrike}). - -@item W d -@kindex W d (Summary) -@findex gnus-article-treat-dumbquotes -@vindex gnus-article-dumbquotes-map -@cindex Smartquotes -@cindex M****s*** sm*rtq**t*s -@cindex Latin 1 -Treat M****s*** sm*rtq**t*s according to -@code{gnus-article-dumbquotes-map} -(@code{gnus-article-treat-dumbquotes}). Note that this function guesses -whether a character is a sm*rtq**t* or not, so it should only be used -interactively. - -Sm*rtq**t*s are M****s***'s unilateral extension to the character map in -an attempt to provide more quoting characters. If you see something -like @code{\222} or @code{\264} where you're expecting some kind of -apostrophe or quotation mark, then try this wash. - -@item W Y f -@kindex W Y f (Summary) -@findex gnus-article-outlook-deuglify-article -@cindex Outlook Express -Full deuglify of broken Outlook (Express) articles: Treat dumbquotes, -unwrap lines, repair attribution and rearrange citation. -(@code{gnus-article-outlook-deuglify-article}). - -@item W Y u -@kindex W Y u (Summary) -@findex gnus-article-outlook-unwrap-lines -@vindex gnus-outlook-deuglify-unwrap-min -@vindex gnus-outlook-deuglify-unwrap-max -Unwrap lines that appear to be wrapped citation lines. You can control -what lines will be unwrapped by frobbing -@code{gnus-outlook-deuglify-unwrap-min} and -@code{gnus-outlook-deuglify-unwrap-max}, indicating the minimum and -maximum length of an unwrapped citation line. -(@code{gnus-article-outlook-unwrap-lines}). - -@item W Y a -@kindex W Y a (Summary) -@findex gnus-article-outlook-repair-attribution -Repair a broken attribution line.@* -(@code{gnus-article-outlook-repair-attribution}). - -@item W Y c -@kindex W Y c (Summary) -@findex gnus-article-outlook-rearrange-citation -Repair broken citations by rearranging the text. -(@code{gnus-article-outlook-rearrange-citation}). - -@item W w -@kindex W w (Summary) -@findex gnus-article-fill-cited-article -Do word wrap (@code{gnus-article-fill-cited-article}). - -You can give the command a numerical prefix to specify the width to use -when filling. - -@item W Q -@kindex W Q (Summary) -@findex gnus-article-fill-long-lines -Fill long lines (@code{gnus-article-fill-long-lines}). - -@item W C -@kindex W C (Summary) -@findex gnus-article-capitalize-sentences -Capitalize the first word in each sentence -(@code{gnus-article-capitalize-sentences}). - -@item W c -@kindex W c (Summary) -@findex gnus-article-remove-cr -Translate CRLF pairs (i. e., @samp{^M}s on the end of the lines) into LF -(this takes care of DOS line endings), and then translate any remaining -CRs into LF (this takes care of Mac line endings) -(@code{gnus-article-remove-cr}). - -@item W q -@kindex W q (Summary) -@findex gnus-article-de-quoted-unreadable -Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). -Quoted-Printable is one common @acronym{MIME} encoding employed when -sending non-@acronym{ASCII} (i.e., 8-bit) articles. It typically -makes strings like @samp{d@'ej@`a vu} look like @samp{d=E9j=E0 vu}, -which doesn't look very readable to me. Note that this is usually -done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W 6 -@kindex W 6 (Summary) -@findex gnus-article-de-base64-unreadable -Treat base64 (@code{gnus-article-de-base64-unreadable}). Base64 is -one common @acronym{MIME} encoding employed when sending -non-@acronym{ASCII} (i.e., 8-bit) articles. Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Transfer-Encoding} header that says that this encoding -has been done. If a prefix is given, a charset will be asked for. - -@item W Z -@kindex W Z (Summary) -@findex gnus-article-decode-HZ -Treat HZ or HZP (@code{gnus-article-decode-HZ}). HZ (or HZP) is one -common encoding employed when sending Chinese articles. It typically -makes strings look like @samp{~@{<:Ky2;S@{#,NpJ)l6HK!#~@}}. - -@item W A -@kindex W A (Summary) -@findex gnus-article-treat-ansi-sequences -@cindex @acronym{ANSI} control sequences -Translate @acronym{ANSI} SGR control sequences into overlays or -extents (@code{gnus-article-treat-ansi-sequences}). @acronym{ANSI} -sequences are used in some Chinese hierarchies for highlighting. - -@item W u -@kindex W u (Summary) -@findex gnus-article-unsplit-urls -Remove newlines from within URLs. Some mailers insert newlines into -outgoing email messages to keep lines short. This reformatting can -split long URLs onto multiple lines. Repair those URLs by removing -the newlines (@code{gnus-article-unsplit-urls}). - -@item W h -@kindex W h (Summary) -@findex gnus-article-wash-html -Treat @acronym{HTML} (@code{gnus-article-wash-html}). Note that this is -usually done automatically by Gnus if the message in question has a -@code{Content-Type} header that says that the message is @acronym{HTML}. - -If a prefix is given, a charset will be asked for. If it is a number, -the charset defined in @code{gnus-summary-show-article-charset-alist} -(@pxref{Paging the Article}) will be used. - -@vindex gnus-article-wash-function -The default is to use the function specified by -@code{mm-text-html-renderer} (@pxref{Display Customization, ,Display -Customization, emacs-mime, The Emacs MIME Manual}) to convert the -@acronym{HTML}, but this is controlled by the -@code{gnus-article-wash-function} variable. Pre-defined functions you -can use include: - -@table @code -@item w3 -Use Emacs/W3. - -@item w3m -Use @uref{http://emacs-w3m.namazu.org/, emacs-w3m}. - -@item w3m-standalone -Use @uref{http://w3m.sourceforge.net/, w3m}. - -@item links -Use @uref{http://links.sf.net/, Links}. - -@item lynx -Use @uref{http://lynx.isc.org/, Lynx}. - -@item html2text -Use html2text---a simple @acronym{HTML} converter included with Gnus. - -@end table - -@item W b -@kindex W b (Summary) -@findex gnus-article-add-buttons -Add clickable buttons to the article (@code{gnus-article-add-buttons}). -@xref{Article Buttons}. - -@item W B -@kindex W B (Summary) -@findex gnus-article-add-buttons-to-head -Add clickable buttons to the article headers -(@code{gnus-article-add-buttons-to-head}). - -@item W p -@kindex W p (Summary) -@findex gnus-article-verify-x-pgp-sig -Verify a signed control message -(@code{gnus-article-verify-x-pgp-sig}). Control messages such as -@code{newgroup} and @code{checkgroups} are usually signed by the -hierarchy maintainer. You need to add the @acronym{PGP} public key of -the maintainer to your keyring to verify the -message.@footnote{@acronym{PGP} keys for many hierarchies are -available at @uref{ftp://ftp.isc.org/pub/pgpcontrol/README.html}} - -@item W s -@kindex W s (Summary) -@findex gnus-summary-force-verify-and-decrypt -Verify a signed (@acronym{PGP}, @acronym{PGP/MIME} or -@acronym{S/MIME}) message -(@code{gnus-summary-force-verify-and-decrypt}). @xref{Security}. - -@item W a -@kindex W a (Summary) -@findex gnus-article-strip-headers-in-body -Strip headers like the @code{X-No-Archive} header from the beginning of -article bodies (@code{gnus-article-strip-headers-in-body}). - -@item W E l -@kindex W E l (Summary) -@findex gnus-article-strip-leading-blank-lines -Remove all blank lines from the beginning of the article -(@code{gnus-article-strip-leading-blank-lines}). - -@item W E m -@kindex W E m (Summary) -@findex gnus-article-strip-multiple-blank-lines -Replace all blank lines with empty lines and then all multiple empty -lines with a single empty line. -(@code{gnus-article-strip-multiple-blank-lines}). - -@item W E t -@kindex W E t (Summary) -@findex gnus-article-remove-trailing-blank-lines -Remove all blank lines at the end of the article -(@code{gnus-article-remove-trailing-blank-lines}). - -@item W E a -@kindex W E a (Summary) -@findex gnus-article-strip-blank-lines -Do all the three commands above -(@code{gnus-article-strip-blank-lines}). - -@item W E A -@kindex W E A (Summary) -@findex gnus-article-strip-all-blank-lines -Remove all blank lines -(@code{gnus-article-strip-all-blank-lines}). - -@item W E s -@kindex W E s (Summary) -@findex gnus-article-strip-leading-space -Remove all white space from the beginning of all lines of the article -body (@code{gnus-article-strip-leading-space}). - -@item W E e -@kindex W E e (Summary) -@findex gnus-article-strip-trailing-space -Remove all white space from the end of all lines of the article -body (@code{gnus-article-strip-trailing-space}). - -@end table - -@xref{Customizing Articles}, for how to wash articles automatically. - - -@node Article Header -@subsection Article Header - -These commands perform various transformations of article header. - -@table @kbd - -@item W G u -@kindex W G u (Summary) -@findex gnus-article-treat-unfold-headers -Unfold folded header lines (@code{gnus-article-treat-unfold-headers}). - -@item W G n -@kindex W G n (Summary) -@findex gnus-article-treat-fold-newsgroups -Fold the @code{Newsgroups} and @code{Followup-To} headers -(@code{gnus-article-treat-fold-newsgroups}). - -@item W G f -@kindex W G f (Summary) -@findex gnus-article-treat-fold-headers -Fold all the message headers -(@code{gnus-article-treat-fold-headers}). - -@item W E w -@kindex W E w (Summary) -@findex gnus-article-remove-leading-whitespace -Remove excessive whitespace from all headers -(@code{gnus-article-remove-leading-whitespace}). - -@end table - - -@node Article Buttons -@subsection Article Buttons -@cindex buttons - -People often include references to other stuff in articles, and it would -be nice if Gnus could just fetch whatever it is that people talk about -with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse -button on these references. - -@vindex gnus-button-man-handler -Gnus adds @dfn{buttons} to certain standard references by default: -Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and -Emacs or Gnus related references. This is controlled by two variables, -one that handles article bodies and one that handles article heads: - -@table @code - -@item gnus-button-alist -@vindex gnus-button-alist -This is an alist where each entry has this form: - -@lisp -(@var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@table @var - -@item regexp -All text that match this regular expression (case insensitive) will be -considered an external reference. Here's a typical regexp that matches -embedded URLs: @samp{]*\\)>}. This can also be a -variable containing a regexp, useful variables to use include -@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}. - -@item button-par -Gnus has to know which parts of the matches is to be highlighted. This -is a number that says what sub-expression of the regexp is to be -highlighted. If you want it all highlighted, you use 0 here. - -@item use-p -This form will be @code{eval}ed, and if the result is non-@code{nil}, -this is considered a match. This is useful if you want extra sifting to -avoid false matches. Often variables named -@code{gnus-button-@var{*}-level} are used here, @xref{Article Button -Levels}, but any other form may be used too. - -@c @code{use-p} is @code{eval}ed only if @code{regexp} matches. - -@item function -This function will be called when you click on this button. - -@item data-par -As with @var{button-par}, this is a sub-expression number, but this one -says which part of the match is to be sent as data to @var{function}. - -@end table - -So the full entry for buttonizing URLs is then - -@lisp -("]*\\)>" 0 t gnus-button-url 1) -@end lisp - -@item gnus-header-button-alist -@vindex gnus-header-button-alist -This is just like the other alist, except that it is applied to the -article head only, and that each entry has an additional element that is -used to say what headers to apply the buttonize coding to: - -@lisp -(@var{header} @var{regexp} @var{button-par} @var{use-p} @var{function} @var{data-par}) -@end lisp - -@var{header} is a regular expression. -@end table - -@subsubsection Related variables and functions - -@table @code -@item gnus-button-@var{*}-level -@xref{Article Button Levels}. - -@c Stuff related to gnus-button-browse-level - -@item gnus-button-url-regexp -@vindex gnus-button-url-regexp -A regular expression that matches embedded URLs. It is used in the -default values of the variables above. - -@c Stuff related to gnus-button-man-level - -@item gnus-button-man-handler -@vindex gnus-button-man-handler -The function to use for displaying man pages. It must take at least one -argument with a string naming the man page. - -@c Stuff related to gnus-button-message-level - -@item gnus-button-mid-or-mail-regexp -@vindex gnus-button-mid-or-mail-regexp -Regular expression that matches a message ID or a mail address. - -@item gnus-button-prefer-mid-or-mail -@vindex gnus-button-prefer-mid-or-mail -This variable determines what to do when the button on a string as -@samp{foo123@@bar.invalid} is pushed. Strings like this can be either a -message ID or a mail address. If it is one of the symbols @code{mid} or -@code{mail}, Gnus will always assume that the string is a message ID or -a mail address, respectively. If this variable is set to the symbol -@code{ask}, always query the user what to do. If it is a function, this -function will be called with the string as its only argument. The -function must return @code{mid}, @code{mail}, @code{invalid} or -@code{ask}. The default value is the function -@code{gnus-button-mid-or-mail-heuristic}. - -@item gnus-button-mid-or-mail-heuristic -@findex gnus-button-mid-or-mail-heuristic -Function that guesses whether its argument is a message ID or a mail -address. Returns @code{mid} if it's a message IDs, @code{mail} if -it's a mail address, @code{ask} if unsure and @code{invalid} if the -string is invalid. - -@item gnus-button-mid-or-mail-heuristic-alist -@vindex gnus-button-mid-or-mail-heuristic-alist -An alist of @code{(RATE . REGEXP)} pairs used by the function -@code{gnus-button-mid-or-mail-heuristic}. - -@c Stuff related to gnus-button-tex-level - -@item gnus-button-ctan-handler -@findex gnus-button-ctan-handler -The function to use for displaying CTAN links. It must take one -argument, the string naming the URL. - -@item gnus-ctan-url -@vindex gnus-ctan-url -Top directory of a CTAN (Comprehensive TeX Archive Network) archive used -by @code{gnus-button-ctan-handler}. - -@c Misc stuff - -@item gnus-article-button-face -@vindex gnus-article-button-face -Face used on buttons. - -@item gnus-article-mouse-face -@vindex gnus-article-mouse-face -Face used when the mouse cursor is over a button. - -@end table - -@xref{Customizing Articles}, for how to buttonize articles automatically. - - -@node Article Button Levels -@subsection Article button levels -@cindex button levels -The higher the value of the variables @code{gnus-button-@var{*}-level}, -the more buttons will appear. If the level is zero, no corresponding -buttons are displayed. With the default value (which is 5) you should -already see quite a lot of buttons. With higher levels, you will see -more buttons, but you may also get more false positives. To avoid them, -you can set the variables @code{gnus-button-@var{*}-level} local to -specific groups (@pxref{Group Parameters}). Here's an example for the -variable @code{gnus-parameters}: - -@lisp -;; @r{increase @code{gnus-button-*-level} in some groups:} -(setq gnus-parameters - '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10)) - ("\\" (gnus-button-man-level 10)) - ("\\" (gnus-button-tex-level 10)))) -@end lisp - -@table @code - -@item gnus-button-browse-level -@vindex gnus-button-browse-level -Controls the display of references to message IDs, mail addresses and -news URLs. Related variables and functions include -@code{gnus-button-url-regexp}, @code{browse-url}, and -@code{browse-url-browser-function}. - -@item gnus-button-emacs-level -@vindex gnus-button-emacs-level -Controls the display of Emacs or Gnus references. Related functions are -@code{gnus-button-handle-custom}, -@code{gnus-button-handle-describe-function}, -@code{gnus-button-handle-describe-variable}, -@code{gnus-button-handle-symbol}, -@code{gnus-button-handle-describe-key}, -@code{gnus-button-handle-apropos}, -@code{gnus-button-handle-apropos-command}, -@code{gnus-button-handle-apropos-variable}, -@code{gnus-button-handle-apropos-documentation}, and -@code{gnus-button-handle-library}. - -@item gnus-button-man-level -@vindex gnus-button-man-level -Controls the display of references to (Unix) man pages. -See @code{gnus-button-man-handler}. - -@item gnus-button-message-level -@vindex gnus-button-message-level -Controls the display of message IDs, mail addresses and news URLs. -Related variables and functions include -@code{gnus-button-mid-or-mail-regexp}, -@code{gnus-button-prefer-mid-or-mail}, -@code{gnus-button-mid-or-mail-heuristic}, and -@code{gnus-button-mid-or-mail-heuristic-alist}. - -@item gnus-button-tex-level -@vindex gnus-button-tex-level -Controls the display of references to @TeX{} or LaTeX stuff, e.g. for CTAN -URLs. See the variables @code{gnus-ctan-url}, -@code{gnus-button-ctan-handler}, -@code{gnus-button-ctan-directory-regexp}, and -@code{gnus-button-handle-ctan-bogus-regexp}. - -@end table - - -@node Article Date -@subsection Article Date - -The date is most likely generated in some obscure timezone you've never -heard of, so it's quite nice to be able to find out what the time was -when the article was sent. - -@table @kbd - -@item W T u -@kindex W T u (Summary) -@findex gnus-article-date-ut -Display the date in UT (aka. GMT, aka ZULU) -(@code{gnus-article-date-ut}). - -@item W T i -@kindex W T i (Summary) -@findex gnus-article-date-iso8601 -@cindex ISO 8601 -Display the date in international format, aka. ISO 8601 -(@code{gnus-article-date-iso8601}). - -@item W T l -@kindex W T l (Summary) -@findex gnus-article-date-local -Display the date in the local timezone (@code{gnus-article-date-local}). - -@item W T p -@kindex W T p (Summary) -@findex gnus-article-date-english -Display the date in a format that's easily pronounceable in English -(@code{gnus-article-date-english}). - -@item W T s -@kindex W T s (Summary) -@vindex gnus-article-time-format -@findex gnus-article-date-user -@findex format-time-string -Display the date using a user-defined format -(@code{gnus-article-date-user}). The format is specified by the -@code{gnus-article-time-format} variable, and is a string that's passed -to @code{format-time-string}. See the documentation of that variable -for a list of possible format specs. - -@item W T e -@kindex W T e (Summary) -@findex gnus-article-date-lapsed -@findex gnus-start-date-timer -@findex gnus-stop-date-timer -Say how much time has elapsed between the article was posted and now -(@code{gnus-article-date-lapsed}). It looks something like: - -@example -X-Sent: 6 weeks, 4 days, 1 hour, 3 minutes, 8 seconds ago -@end example - -@vindex gnus-article-date-lapsed-new-header -The value of @code{gnus-article-date-lapsed-new-header} determines -whether this header will just be added below the old Date one, or will -replace it. - -An advantage of using Gnus to read mail is that it converts simple bugs -into wonderful absurdities. - -If you want to have this line updated continually, you can put - -@lisp -(gnus-start-date-timer) -@end lisp - -in your @file{~/.gnus.el} file, or you can run it off of some hook. If -you want to stop the timer, you can use the @code{gnus-stop-date-timer} -command. - -@item W T o -@kindex W T o (Summary) -@findex gnus-article-date-original -Display the original date (@code{gnus-article-date-original}). This can -be useful if you normally use some other conversion function and are -worried that it might be doing something totally wrong. Say, claiming -that the article was posted in 1854. Although something like that is -@emph{totally} impossible. Don't you trust me? *titter* - -@end table - -@xref{Customizing Articles}, for how to display the date in your -preferred format automatically. - - -@node Article Display -@subsection Article Display -@cindex picons -@cindex x-face -@cindex smileys - -These commands add various frivolous display gimmicks to the article -buffer in Emacs versions that support them. - -@code{X-Face} headers are small black-and-white images supplied by the -message headers (@pxref{X-Face}). - -@code{Face} headers are small colored images supplied by the message -headers (@pxref{Face}). - -Smileys are those little @samp{:-)} symbols that people like to litter -their messages with (@pxref{Smileys}). - -Picons, on the other hand, reside on your own system, and Gnus will -try to match the headers to what you have (@pxref{Picons}). - -All these functions are toggles---if the elements already exist, -they'll be removed. - -@table @kbd -@item W D x -@kindex W D x (Summary) -@findex gnus-article-display-x-face -Display an @code{X-Face} in the @code{From} header. -(@code{gnus-article-display-x-face}). - -@item W D d -@kindex W D d (Summary) -@findex gnus-article-display-face -Display a @code{Face} in the @code{From} header. -(@code{gnus-article-display-face}). - -@item W D s -@kindex W D s (Summary) -@findex gnus-treat-smiley -Display smileys (@code{gnus-treat-smiley}). - -@item W D f -@kindex W D f (Summary) -@findex gnus-treat-from-picon -Piconify the @code{From} header (@code{gnus-treat-from-picon}). - -@item W D m -@kindex W D m (Summary) -@findex gnus-treat-mail-picon -Piconify all mail headers (i. e., @code{Cc}, @code{To}) -(@code{gnus-treat-mail-picon}). - -@item W D n -@kindex W D n (Summary) -@findex gnus-treat-newsgroups-picon -Piconify all news headers (i. e., @code{Newsgroups} and -@code{Followup-To}) (@code{gnus-treat-newsgroups-picon}). - -@item W D D -@kindex W D D (Summary) -@findex gnus-article-remove-images -Remove all images from the article buffer -(@code{gnus-article-remove-images}). - -@end table - - - -@node Article Signature -@subsection Article Signature -@cindex signatures -@cindex article signature - -@vindex gnus-signature-separator -Each article is divided into two parts---the head and the body. The -body can be divided into a signature part and a text part. The variable -that says what is to be considered a signature is -@code{gnus-signature-separator}. This is normally the standard -@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use -non-standard signature separators, so this variable can also be a list -of regular expressions to be tested, one by one. (Searches are done -from the end of the body towards the beginning.) One likely value is: - -@lisp -(setq gnus-signature-separator - '("^-- $" ; @r{The standard} - "^-- *$" ; @r{A common mangling} - "^-------*$" ; @r{Many people just use a looong} - ; @r{line of dashes. Shame!} - "^ *--------*$" ; @r{Double-shame!} - "^________*$" ; @r{Underscores are also popular} - "^========*$")) ; @r{Pervert!} -@end lisp - -The more permissive you are, the more likely it is that you'll get false -positives. - -@vindex gnus-signature-limit -@code{gnus-signature-limit} provides a limit to what is considered a -signature when displaying articles. - -@enumerate -@item -If it is an integer, no signature may be longer (in characters) than -that integer. -@item -If it is a floating point number, no signature may be longer (in lines) -than that number. -@item -If it is a function, the function will be called without any parameters, -and if it returns @code{nil}, there is no signature in the buffer. -@item -If it is a string, it will be used as a regexp. If it matches, the text -in question is not a signature. -@end enumerate - -This variable can also be a list where the elements may be of the types -listed above. Here's an example: - -@lisp -(setq gnus-signature-limit - '(200.0 "^---*Forwarded article")) -@end lisp - -This means that if there are more than 200 lines after the signature -separator, or the text after the signature separator is matched by -the regular expression @samp{^---*Forwarded article}, then it isn't a -signature after all. - - -@node Article Miscellanea -@subsection Article Miscellanea - -@table @kbd -@item A t -@kindex A t (Summary) -@findex gnus-article-babel -Translate the article from one language to another -(@code{gnus-article-babel}). - -@end table - - -@node MIME Commands -@section MIME Commands -@cindex MIME decoding -@cindex attachments -@cindex viewing attachments - -The following commands all understand the numerical prefix. For -instance, @kbd{3 K v} means ``view the third @acronym{MIME} part''. - -@table @kbd -@item b -@itemx K v -@kindex b (Summary) -@kindex K v (Summary) -View the @acronym{MIME} part. - -@item K o -@kindex K o (Summary) -Save the @acronym{MIME} part. - -@item K O -@kindex K O (Summary) -Prompt for a file name, then save the @acronym{MIME} part and strip it -from the article. The stripped @acronym{MIME} object will be referred -via the message/external-body @acronym{MIME} type. - -@item K r -@kindex K r (Summary) -Replace the @acronym{MIME} part with an external body. - -@item K d -@kindex K d (Summary) -Delete the @acronym{MIME} part and add some information about the -removed part. - -@item K c -@kindex K c (Summary) -Copy the @acronym{MIME} part. - -@item K e -@kindex K e (Summary) -View the @acronym{MIME} part externally. - -@item K i -@kindex K i (Summary) -View the @acronym{MIME} part internally. - -@item K | -@kindex K | (Summary) -Pipe the @acronym{MIME} part to an external command. -@end table - -The rest of these @acronym{MIME} commands do not use the numerical prefix in -the same manner: - -@table @kbd -@item K H -@kindex K H (Summary) -@findex gnus-article-browse-html-article -View @samp{text/html} parts of the current article with a WWW browser. -The message header is added to the beginning of every html part unless -the prefix argument is given. - -Warning: Spammers use links to images in HTML articles to verify whether -you have read the message. As this command passes the @acronym{HTML} -content to the browser without eliminating these ``web bugs'' you should -only use it for mails from trusted senders. - -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - -@item K b -@kindex K b (Summary) -Make all the @acronym{MIME} parts have buttons in front of them. This is -mostly useful if you wish to save (or perform other actions) on inlined -parts. - -@item K m -@kindex K m (Summary) -@findex gnus-summary-repair-multipart -Some multipart messages are transmitted with missing or faulty headers. -This command will attempt to ``repair'' these messages so that they can -be viewed in a more pleasant manner -(@code{gnus-summary-repair-multipart}). - -@item X m -@kindex X m (Summary) -@findex gnus-summary-save-parts -Save all parts matching a @acronym{MIME} type to a directory -(@code{gnus-summary-save-parts}). Understands the process/prefix -convention (@pxref{Process/Prefix}). - -@item M-t -@kindex M-t (Summary) -@findex gnus-summary-toggle-display-buttonized -Toggle the buttonized display of the article buffer -(@code{gnus-summary-toggle-display-buttonized}). - -@item W M w -@kindex W M w (Summary) -@findex gnus-article-decode-mime-words -Decode RFC 2047-encoded words in the article headers -(@code{gnus-article-decode-mime-words}). - -@item W M c -@kindex W M c (Summary) -@findex gnus-article-decode-charset -Decode encoded article bodies as well as charsets -(@code{gnus-article-decode-charset}). - -This command looks in the @code{Content-Type} header to determine the -charset. If there is no such header in the article, you can give it a -prefix, which will prompt for the charset to decode as. In regional -groups where people post using some common encoding (but do not -include @acronym{MIME} headers), you can set the @code{charset} group/topic -parameter to the required charset (@pxref{Group Parameters}). - -@item W M v -@kindex W M v (Summary) -@findex gnus-mime-view-all-parts -View all the @acronym{MIME} parts in the current article -(@code{gnus-mime-view-all-parts}). - -@end table - -Relevant variables: - -@table @code -@item gnus-ignored-mime-types -@vindex gnus-ignored-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will be completely ignored by Gnus. The default value is -@code{nil}. - -To have all Vcards be ignored, you'd say something like this: - -@lisp -(setq gnus-ignored-mime-types - '("text/x-vcard")) -@end lisp - -@item gnus-article-loose-mime -@vindex gnus-article-loose-mime -If non-@code{nil}, Gnus won't require the @samp{MIME-Version} header -before interpreting the message as a @acronym{MIME} message. This helps -when reading messages from certain broken mail user agents. The -default is @code{t}. - -@item gnus-article-emulate-mime -@vindex gnus-article-emulate-mime -@cindex uuencode -@cindex yEnc -There are other, non-@acronym{MIME} encoding methods used. The most common -is @samp{uuencode}, but yEncode is also getting to be popular. If -this variable is non-@code{nil}, Gnus will look in message bodies to -see if it finds these encodings, and if so, it'll run them through the -Gnus @acronym{MIME} machinery. The default is @code{t}. Only -single-part yEnc encoded attachments can be decoded. There's no support -for encoding in Gnus. - -@item gnus-unbuttonized-mime-types -@vindex gnus-unbuttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list won't have @acronym{MIME} buttons inserted unless they aren't -displayed or this variable is overridden by -@code{gnus-buttonized-mime-types}. The default value is -@code{(".*/.*")}. This variable is only used when -@code{gnus-inhibit-mime-unbuttonizing} is @code{nil}. - -@item gnus-buttonized-mime-types -@vindex gnus-buttonized-mime-types -This is a list of regexps. @acronym{MIME} types that match a regexp from -this list will have @acronym{MIME} buttons inserted unless they aren't -displayed. This variable overrides -@code{gnus-unbuttonized-mime-types}. The default value is @code{nil}. -This variable is only used when @code{gnus-inhibit-mime-unbuttonizing} -is @code{nil}. - -To see e.g. security buttons but no other buttons, you could set this -variable to @code{("multipart/signed")} and leave -@code{gnus-unbuttonized-mime-types} at the default value. - -You could also add @code{"multipart/alternative"} to this list to -display radio buttons that allow you to choose one of two media types -those mails include. See also @code{mm-discouraged-alternatives} -(@pxref{Display Customization, ,Display Customization, emacs-mime, The -Emacs MIME Manual}). - -@item gnus-inhibit-mime-unbuttonizing -@vindex gnus-inhibit-mime-unbuttonizing -If this is non-@code{nil}, then all @acronym{MIME} parts get buttons. The -default value is @code{nil}. - -@item gnus-article-mime-part-function -@vindex gnus-article-mime-part-function -For each @acronym{MIME} part, this function will be called with the @acronym{MIME} -handle as the parameter. The function is meant to be used to allow -users to gather information from the article (e. g., add Vcard info to -the bbdb database) or to do actions based on parts (e. g., automatically -save all jpegs into some directory). - -Here's an example function the does the latter: - -@lisp -(defun my-save-all-jpeg-parts (handle) - (when (equal (car (mm-handle-type handle)) "image/jpeg") - (with-temp-buffer - (insert (mm-get-part handle)) - (write-region (point-min) (point-max) - (read-file-name "Save jpeg to: "))))) -(setq gnus-article-mime-part-function - 'my-save-all-jpeg-parts) -@end lisp - -@vindex gnus-mime-multipart-functions -@item gnus-mime-multipart-functions -Alist of @acronym{MIME} multipart types and functions to handle them. - -@vindex gnus-mime-display-multipart-alternative-as-mixed -@item gnus-mime-display-multipart-alternative-as-mixed -Display "multipart/alternative" parts as "multipart/mixed". - -@vindex gnus-mime-display-multipart-related-as-mixed -@item gnus-mime-display-multipart-related-as-mixed -Display "multipart/related" parts as "multipart/mixed". - -If displaying @samp{text/html} is discouraged, see -@code{mm-discouraged-alternatives}, images or other material inside a -"multipart/related" part might be overlooked when this variable is -@code{nil}. @ref{Display Customization, Display Customization, , -emacs-mime, Emacs-Mime Manual}. - -@vindex gnus-mime-display-multipart-as-mixed -@item gnus-mime-display-multipart-as-mixed -Display "multipart" parts as "multipart/mixed". If @code{t}, it -overrides @code{nil} values of -@code{gnus-mime-display-multipart-alternative-as-mixed} and -@code{gnus-mime-display-multipart-related-as-mixed}. - -@vindex mm-file-name-rewrite-functions -@item mm-file-name-rewrite-functions -List of functions used for rewriting file names of @acronym{MIME} parts. -Each function takes a file name as input and returns a file name. - -Ready-made functions include@* -@code{mm-file-name-delete-whitespace}, -@code{mm-file-name-trim-whitespace}, -@code{mm-file-name-collapse-whitespace}, and -@code{mm-file-name-replace-whitespace}. The later uses the value of -the variable @code{mm-file-name-replace-whitespace} to replace each -whitespace character in a file name with that string; default value -is @code{"_"} (a single underscore). -@findex mm-file-name-delete-whitespace -@findex mm-file-name-trim-whitespace -@findex mm-file-name-collapse-whitespace -@findex mm-file-name-replace-whitespace -@vindex mm-file-name-replace-whitespace - -The standard functions @code{capitalize}, @code{downcase}, -@code{upcase}, and @code{upcase-initials} may be useful, too. - -Everybody knows that whitespace characters in file names are evil, -except those who don't know. If you receive lots of attachments from -such unenlightened users, you can make live easier by adding - -@lisp -(setq mm-file-name-rewrite-functions - '(mm-file-name-trim-whitespace - mm-file-name-collapse-whitespace - mm-file-name-replace-whitespace)) -@end lisp - -@noindent -to your @file{~/.gnus.el} file. - -@end table - - -@node Charsets -@section Charsets -@cindex charsets - -People use different charsets, and we have @acronym{MIME} to let us know what -charsets they use. Or rather, we wish we had. Many people use -newsreaders and mailers that do not understand or use @acronym{MIME}, and -just send out messages without saying what character sets they use. To -help a bit with this, some local news hierarchies have policies that say -what character set is the default. For instance, the @samp{fj} -hierarchy uses @code{iso-2022-jp}. - -@vindex gnus-group-charset-alist -This knowledge is encoded in the @code{gnus-group-charset-alist} -variable, which is an alist of regexps (use the first item to match full -group names) and default charsets to be used when reading these groups. - -@vindex gnus-newsgroup-ignored-charsets -In addition, some people do use soi-disant @acronym{MIME}-aware agents that -aren't. These blithely mark messages as being in @code{iso-8859-1} -even if they really are in @code{koi-8}. To help here, the -@code{gnus-newsgroup-ignored-charsets} variable can be used. The -charsets that are listed here will be ignored. The variable can be -set on a group-by-group basis using the group parameters (@pxref{Group -Parameters}). The default value is @code{(unknown-8bit x-unknown)}, -which includes values some agents insist on having in there. - -@vindex gnus-group-posting-charset-alist -When posting, @code{gnus-group-posting-charset-alist} is used to -determine which charsets should not be encoded using the @acronym{MIME} -encodings. For instance, some hierarchies discourage using -quoted-printable header encoding. - -This variable is an alist of regexps and permitted unencoded charsets -for posting. Each element of the alist has the form @code{(}@var{test -header body-list}@code{)}, where: - -@table @var -@item test -is either a regular expression matching the newsgroup header or a -variable to query, -@item header -is the charset which may be left unencoded in the header (@code{nil} -means encode all charsets), -@item body-list -is a list of charsets which may be encoded using 8bit content-transfer -encoding in the body, or one of the special values @code{nil} (always -encode using quoted-printable) or @code{t} (always use 8bit). -@end table - -@cindex Russian -@cindex koi8-r -@cindex koi8-u -@cindex iso-8859-5 -@cindex coding system aliases -@cindex preferred charset - -@xref{Encoding Customization, , Encoding Customization, emacs-mime, -The Emacs MIME Manual}, for additional variables that control which -MIME charsets are used when sending messages. - -Other charset tricks that may be useful, although not Gnus-specific: - -If there are several @acronym{MIME} charsets that encode the same Emacs -charset, you can choose what charset to use by saying the following: - -@lisp -(put-charset-property 'cyrillic-iso8859-5 - 'preferred-coding-system 'koi8-r) -@end lisp - -This means that Russian will be encoded using @code{koi8-r} instead of -the default @code{iso-8859-5} @acronym{MIME} charset. - -If you want to read messages in @code{koi8-u}, you can cheat and say - -@lisp -(define-coding-system-alias 'koi8-u 'koi8-r) -@end lisp - -This will almost do the right thing. - -And finally, to read charsets like @code{windows-1251}, you can say -something like - -@lisp -(codepage-setup 1251) -(define-coding-system-alias 'windows-1251 'cp1251) -@end lisp - - -@node Article Commands -@section Article Commands - -@table @kbd - -@item A P -@cindex PostScript -@cindex printing -@kindex A P (Summary) -@vindex gnus-ps-print-hook -@findex gnus-summary-print-article -Generate and print a PostScript image of the article buffer -(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will -be run just before printing the buffer. An alternative way to print -article is to use Muttprint (@pxref{Saving Articles}). - -@end table - - -@node Summary Sorting -@section Summary Sorting -@cindex summary sorting - -You can have the summary buffer sorted in various ways, even though I -can't really see why you'd want that. - -@table @kbd - -@item C-c C-s C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-number -Sort by article number (@code{gnus-summary-sort-by-number}). - -@item C-c C-s C-m C-n -@kindex C-c C-s C-n (Summary) -@findex gnus-summary-sort-by-most-recent-number -Sort by most recent article number -(@code{gnus-summary-sort-by-most-recent-number}). - -@item C-c C-s C-a -@kindex C-c C-s C-a (Summary) -@findex gnus-summary-sort-by-author -Sort by author (@code{gnus-summary-sort-by-author}). - -@item C-c C-s C-t -@kindex C-c C-s C-t (Summary) -@findex gnus-summary-sort-by-recipient -Sort by recipient (@code{gnus-summary-sort-by-recipient}). - -@item C-c C-s C-s -@kindex C-c C-s C-s (Summary) -@findex gnus-summary-sort-by-subject -Sort by subject (@code{gnus-summary-sort-by-subject}). - -@item C-c C-s C-d -@kindex C-c C-s C-d (Summary) -@findex gnus-summary-sort-by-date -Sort by date (@code{gnus-summary-sort-by-date}). - -@item C-c C-s C-m C-d -@kindex C-c C-s C-m C-d (Summary) -@findex gnus-summary-sort-by-most-recent-date -Sort by most recent date (@code{gnus-summary-sort-by-most-recent-date}). - -@item C-c C-s C-l -@kindex C-c C-s C-l (Summary) -@findex gnus-summary-sort-by-lines -Sort by lines (@code{gnus-summary-sort-by-lines}). - -@item C-c C-s C-c -@kindex C-c C-s C-c (Summary) -@findex gnus-summary-sort-by-chars -Sort by article length (@code{gnus-summary-sort-by-chars}). - -@item C-c C-s C-i -@kindex C-c C-s C-i (Summary) -@findex gnus-summary-sort-by-score -Sort by score (@code{gnus-summary-sort-by-score}). - -@item C-c C-s C-r -@kindex C-c C-s C-r (Summary) -@findex gnus-summary-sort-by-random -Randomize (@code{gnus-summary-sort-by-random}). - -@item C-c C-s C-o -@kindex C-c C-s C-o (Summary) -@findex gnus-summary-sort-by-original -Sort using the default sorting method -(@code{gnus-summary-sort-by-original}). -@end table - -These functions will work both when you use threading and when you don't -use threading. In the latter case, all summary lines will be sorted, -line by line. In the former case, sorting will be done on a -root-by-root basis, which might not be what you were looking for. To -toggle whether to use threading, type @kbd{T T} (@pxref{Thread -Commands}). - -If a prefix argument if given, the sort order is reversed. - - -@node Finding the Parent -@section Finding the Parent -@cindex parent articles -@cindex referring articles - -@table @kbd -@item ^ -@kindex ^ (Summary) -@findex gnus-summary-refer-parent-article -If you'd like to read the parent of the current article, and it is not -displayed in the summary buffer, you might still be able to. That is, -if the current group is fetched by @acronym{NNTP}, the parent hasn't expired -and the @code{References} in the current article are not mangled, you -can just press @kbd{^} or @kbd{A r} -(@code{gnus-summary-refer-parent-article}). If everything goes well, -you'll get the parent. If the parent is already displayed in the -summary buffer, point will just move to this article. - -If given a positive numerical prefix, fetch that many articles back into -the ancestry. If given a negative numerical prefix, fetch just that -ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the -grandparent and the grandgrandparent of the current article. If you say -@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current -article. - -@item A R (Summary) -@findex gnus-summary-refer-references -@kindex A R (Summary) -Fetch all articles mentioned in the @code{References} header of the -article (@code{gnus-summary-refer-references}). - -@item A T (Summary) -@findex gnus-summary-refer-thread -@kindex A T (Summary) -Display the full thread where the current article appears -(@code{gnus-summary-refer-thread}). This command has to fetch all the -headers in the current group to work, so it usually takes a while. If -you do it often, you may consider setting @code{gnus-fetch-old-headers} -to @code{invisible} (@pxref{Filling In Threads}). This won't have any -visible effects normally, but it'll make this command work a whole lot -faster. Of course, it'll make group entry somewhat slow. - -@vindex gnus-refer-thread-limit -The @code{gnus-refer-thread-limit} variable says how many old (i. e., -articles before the first displayed in the current group) headers to -fetch when doing this command. The default is 200. If @code{t}, all -the available headers will be fetched. This variable can be overridden -by giving the @kbd{A T} command a numerical prefix. - -@item M-^ (Summary) -@findex gnus-summary-refer-article -@kindex M-^ (Summary) -@cindex Message-ID -@cindex fetching by Message-ID -You can also ask Gnus for an arbitrary article, no matter what group it -belongs to. @kbd{M-^} (@code{gnus-summary-refer-article}) will ask you -for a @code{Message-ID}, which is one of those long, hard-to-read -thingies that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. -You have to get it all exactly right. No fuzzy searches, I'm afraid. - -Gnus looks for the @code{Message-ID} in the headers that have already -been fetched, but also tries all the select methods specified by -@code{gnus-refer-article-method} if it is not found. -@end table - -@vindex gnus-refer-article-method -If the group you are reading is located on a back end that does not -support fetching by @code{Message-ID} very well (like @code{nnspool}), -you can set @code{gnus-refer-article-method} to an @acronym{NNTP} method. It -would, perhaps, be best if the @acronym{NNTP} server you consult is the one -updating the spool you are reading from, but that's not really -necessary. - -It can also be a list of select methods, as well as the special symbol -@code{current}, which means to use the current select method. If it -is a list, Gnus will try all the methods in the list until it finds a -match. - -Here's an example setting that will first try the current method, and -then ask Google if that fails: - -@lisp -(setq gnus-refer-article-method - '(current - (nnweb "google" (nnweb-type google)))) -@end lisp - -Most of the mail back ends support fetching by @code{Message-ID}, but -do not do a particularly excellent job at it. That is, @code{nnmbox}, -@code{nnbabyl}, @code{nnmaildir}, @code{nnml}, are able to locate -articles from any groups, while @code{nnfolder}, and @code{nnimap} are -only able to locate articles that have been posted to the current -group. (Anything else would be too time consuming.) @code{nnmh} does -not support this at all. - - -@node Alternative Approaches -@section Alternative Approaches - -Different people like to read news using different methods. This being -Gnus, we offer a small selection of minor modes for the summary buffers. - -@menu -* Pick and Read:: First mark articles and then read them. -* Binary Groups:: Auto-decode all articles. -@end menu - - -@node Pick and Read -@subsection Pick and Read -@cindex pick and read - -Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use -a two-phased reading interface. The user first marks in a summary -buffer the articles she wants to read. Then she starts reading the -articles with just an article buffer displayed. - -@findex gnus-pick-mode -@kindex M-x gnus-pick-mode -Gnus provides a summary buffer minor mode that allows -this---@code{gnus-pick-mode}. This basically means that a few process -mark commands become one-keystroke commands to allow easy marking, and -it provides one additional command for switching to the summary buffer. - -Here are the available keystrokes when using pick mode: - -@table @kbd -@item . -@kindex . (Pick) -@findex gnus-pick-article-or-thread -Pick the article or thread on the current line -(@code{gnus-pick-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key selects the -entire thread when used at the first article of the thread. Otherwise, -it selects just the article. If given a numerical prefix, go to that -thread or article and pick it. (The line number is normally displayed -at the beginning of the summary pick lines.) - -@item SPACE -@kindex SPACE (Pick) -@findex gnus-pick-next-page -Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If -at the end of the buffer, start reading the picked articles. - -@item u -@kindex u (Pick) -@findex gnus-pick-unmark-article-or-thread. -Unpick the thread or article -(@code{gnus-pick-unmark-article-or-thread}). If the variable -@code{gnus-thread-hide-subtree} is true, then this key unpicks the -thread if used at the first article of the thread. Otherwise it unpicks -just the article. You can give this key a numerical prefix to unpick -the thread or article at that line. - -@item RET -@kindex RET (Pick) -@findex gnus-pick-start-reading -@vindex gnus-pick-display-summary -Start reading the picked articles (@code{gnus-pick-start-reading}). If -given a prefix, mark all unpicked articles as read first. If -@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer -will still be visible when you are reading. - -@end table - -All the normal summary mode commands are still available in the -pick-mode, with the exception of @kbd{u}. However @kbd{!} is available -which is mapped to the same function -@code{gnus-summary-tick-article-forward}. - -If this sounds like a good idea to you, you could say: - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@vindex gnus-pick-mode-hook -@code{gnus-pick-mode-hook} is run in pick minor mode buffers. - -@vindex gnus-mark-unpicked-articles-as-read -If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark -all unpicked articles as read. The default is @code{nil}. - -@vindex gnus-summary-pick-line-format -The summary line format in pick mode is slightly different from the -standard format. At the beginning of each line the line number is -displayed. The pick mode line format is controlled by the -@code{gnus-summary-pick-line-format} variable (@pxref{Formatting -Variables}). It accepts the same format specs that -@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). - - -@node Binary Groups -@subsection Binary Groups -@cindex binary groups - -@findex gnus-binary-mode -@kindex M-x gnus-binary-mode -If you spend much time in binary groups, you may grow tired of hitting -@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} -is a minor mode for summary buffers that makes all ordinary Gnus article -selection functions uudecode series of articles and display the result -instead of just displaying the articles the normal way. - -@kindex g (Binary) -@findex gnus-binary-show-article -The only way, in fact, to see the actual articles is the @kbd{g} -command, when you have turned on this mode -(@code{gnus-binary-show-article}). - -@vindex gnus-binary-mode-hook -@code{gnus-binary-mode-hook} is called in binary minor mode buffers. - - -@node Tree Display -@section Tree Display -@cindex trees - -@vindex gnus-use-trees -If you don't like the normal Gnus summary display, you might try setting -@code{gnus-use-trees} to @code{t}. This will create (by default) an -additional @dfn{tree buffer}. You can execute all summary mode commands -in the tree buffer. - -There are a few variables to customize the tree display, of course: - -@table @code -@item gnus-tree-mode-hook -@vindex gnus-tree-mode-hook -A hook called in all tree mode buffers. - -@item gnus-tree-mode-line-format -@vindex gnus-tree-mode-line-format -A format string for the mode bar in the tree mode buffers (@pxref{Mode -Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list -of valid specs, @pxref{Summary Buffer Mode Line}. - -@item gnus-selected-tree-face -@vindex gnus-selected-tree-face -Face used for highlighting the selected article in the tree buffer. The -default is @code{modeline}. - -@item gnus-tree-line-format -@vindex gnus-tree-line-format -A format string for the tree nodes. The name is a bit of a misnomer, -though---it doesn't define a line, but just the node. The default value -is @samp{%(%[%3,3n%]%)}, which displays the first three characters of -the name of the poster. It is vital that all nodes are of the same -length, so you @emph{must} use @samp{%4,4n}-like specifiers. - -Valid specs are: - -@table @samp -@item n -The name of the poster. -@item f -The @code{From} header. -@item N -The number of the article. -@item [ -The opening bracket. -@item ] -The closing bracket. -@item s -The subject. -@end table - -@xref{Formatting Variables}. - -Variables related to the display are: - -@table @code -@item gnus-tree-brackets -@vindex gnus-tree-brackets -This is used for differentiating between ``real'' articles and -``sparse'' articles. The format is -@example -((@var{real-open} . @var{real-close}) - (@var{sparse-open} . @var{sparse-close}) - (@var{dummy-open} . @var{dummy-close})) -@end example -and the default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. - -@item gnus-tree-parent-child-edges -@vindex gnus-tree-parent-child-edges -This is a list that contains the characters used for connecting parent -nodes to their children. The default is @code{(?- ?\\ ?|)}. - -@end table - -@item gnus-tree-minimize-window -@vindex gnus-tree-minimize-window -If this variable is non-@code{nil}, Gnus will try to keep the tree -buffer as small as possible to allow more room for the other Gnus -windows. If this variable is a number, the tree buffer will never be -higher than that number. The default is @code{t}. Note that if you -have several windows displayed side-by-side in a frame and the tree -buffer is one of these, minimizing the tree window will also resize all -other windows displayed next to it. - -You may also wish to add the following hook to keep the window minimized -at all times: - -@lisp -(add-hook 'gnus-configure-windows-hook - 'gnus-tree-perhaps-minimize) -@end lisp - -@item gnus-generate-tree-function -@vindex gnus-generate-tree-function -@findex gnus-generate-horizontal-tree -@findex gnus-generate-vertical-tree -The function that actually generates the thread tree. Two predefined -functions are available: @code{gnus-generate-horizontal-tree} and -@code{gnus-generate-vertical-tree} (which is the default). - -@end table - -Here's an example from a horizontal tree buffer: - -@example -@{***@}-(***)-[odd]-[Gun] - | \[Jan] - | \[odd]-[Eri] - | \(***)-[Eri] - | \[odd]-[Paa] - \[Bjo] - \[Gun] - \[Gun]-[Jor] -@end example - -Here's the same thread displayed in a vertical tree buffer: - -@example -@group -@{***@} - |--------------------------\-----\-----\ -(***) [Bjo] [Gun] [Gun] - |--\-----\-----\ | -[odd] [Jan] [odd] (***) [Jor] - | | |--\ -[Gun] [Eri] [Eri] [odd] - | - [Paa] -@end group -@end example - -If you're using horizontal trees, it might be nice to display the trees -side-by-side with the summary buffer. You could add something like the -following to your @file{~/.gnus.el} file: - -@lisp -(setq gnus-use-trees t - gnus-generate-tree-function 'gnus-generate-horizontal-tree - gnus-tree-minimize-window nil) -(gnus-add-configuration - '(article - (vertical 1.0 - (horizontal 0.25 - (summary 0.75 point) - (tree 1.0)) - (article 1.0)))) -@end lisp - -@xref{Window Layout}. - - -@node Mail Group Commands -@section Mail Group Commands -@cindex mail group commands - -Some commands only make sense in mail groups. If these commands are -invalid in the current group, they will raise a hell and let you know. - -All these commands (except the expiry and edit commands) use the -process/prefix convention (@pxref{Process/Prefix}). - -@table @kbd - -@item B e -@kindex B e (Summary) -@findex gnus-summary-expire-articles -@cindex expiring mail -Run all expirable articles in the current group through the expiry -process (@code{gnus-summary-expire-articles}). That is, delete all -expirable articles in the group that have been around for a while. -(@pxref{Expiring Mail}). - -@item B C-M-e -@kindex B C-M-e (Summary) -@findex gnus-summary-expire-articles-now -@cindex expiring mail -Delete all the expirable articles in the group -(@code{gnus-summary-expire-articles-now}). This means that @strong{all} -articles eligible for expiry in the current group will -disappear forever into that big @file{/dev/null} in the sky. - -@item B DEL -@kindex B DEL (Summary) -@findex gnus-summary-delete-article -@c @icon{gnus-summary-mail-delete} -Delete the mail article. This is ``delete'' as in ``delete it from your -disk forever and ever, never to return again.'' Use with caution. -(@code{gnus-summary-delete-article}). - -@item B m -@kindex B m (Summary) -@cindex move mail -@findex gnus-summary-move-article -@vindex gnus-preserve-marks -Move the article from one mail group to another -(@code{gnus-summary-move-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B c -@kindex B c (Summary) -@cindex copy mail -@findex gnus-summary-copy-article -@c @icon{gnus-summary-mail-copy} -Copy the article from one group (mail group or not) to a mail group -(@code{gnus-summary-copy-article}). Marks will be preserved if -@code{gnus-preserve-marks} is non-@code{nil} (which is the default). - -@item B B -@kindex B B (Summary) -@cindex crosspost mail -@findex gnus-summary-crosspost-article -Crosspost the current article to some other group -(@code{gnus-summary-crosspost-article}). This will create a new copy of -the article in the other group, and the Xref headers of the article will -be properly updated. - -@item B i -@kindex B i (Summary) -@findex gnus-summary-import-article -Import an arbitrary file into the current mail newsgroup -(@code{gnus-summary-import-article}). You will be prompted for a file -name, a @code{From} header and a @code{Subject} header. - -@item B I -@kindex B I (Summary) -@findex gnus-summary-create-article -Create an empty article in the current mail newsgroups -(@code{gnus-summary-create-article}). You will be prompted for a -@code{From} header and a @code{Subject} header. - -@item B r -@kindex B r (Summary) -@findex gnus-summary-respool-article -@vindex gnus-summary-respool-default-method -Respool the mail article (@code{gnus-summary-respool-article}). -@code{gnus-summary-respool-default-method} will be used as the default -select method when respooling. This variable is @code{nil} by default, -which means that the current group select method will be used instead. -Marks will be preserved if @code{gnus-preserve-marks} is non-@code{nil} -(which is the default). - -@item B w -@itemx e -@kindex B w (Summary) -@kindex e (Summary) -@findex gnus-summary-edit-article -@kindex C-c C-c (Article) -@findex gnus-summary-edit-article-done -Edit the current article (@code{gnus-summary-edit-article}). To finish -editing and make the changes permanent, type @kbd{C-c C-c} -(@code{gnus-summary-edit-article-done}). If you give a prefix to the -@kbd{C-c C-c} command, Gnus won't re-highlight the article. - -@item B q -@kindex B q (Summary) -@findex gnus-summary-respool-query -If you want to re-spool an article, you might be curious as to what group -the article will end up in before you do the re-spooling. This command -will tell you (@code{gnus-summary-respool-query}). - -@item B t -@kindex B t (Summary) -@findex gnus-summary-respool-trace -Similarly, this command will display all fancy splitting patterns used -when respooling, if any (@code{gnus-summary-respool-trace}). - -@item B p -@kindex B p (Summary) -@findex gnus-summary-article-posted-p -Some people have a tendency to send you ``courtesy'' copies when they -follow up to articles you have posted. These usually have a -@code{Newsgroups} header in them, but not always. This command -(@code{gnus-summary-article-posted-p}) will try to fetch the current -article from your news server (or rather, from -@code{gnus-refer-article-method} or @code{gnus-select-method}) and will -report back whether it found the article or not. Even if it says that -it didn't find the article, it may have been posted anyway---mail -propagation is much faster than news propagation, and the news copy may -just not have arrived yet. - -@item K E -@kindex K E (Summary) -@findex gnus-article-encrypt-body -@vindex gnus-article-encrypt-protocol -Encrypt the body of an article (@code{gnus-article-encrypt-body}). -The body is encrypted with the encryption protocol specified by the -variable @code{gnus-article-encrypt-protocol}. - -@end table - -@vindex gnus-move-split-methods -@cindex moving articles -If you move (or copy) articles regularly, you might wish to have Gnus -suggest where to put the articles. @code{gnus-move-split-methods} is a -variable that uses the same syntax as @code{gnus-split-methods} -(@pxref{Saving Articles}). You may customize that variable to create -suggestions you find reasonable. (Note that -@code{gnus-move-split-methods} uses group names where -@code{gnus-split-methods} uses file names.) - -@lisp -(setq gnus-move-split-methods - '(("^From:.*Lars Magne" "nnml:junk") - ("^Subject:.*gnus" "nnfolder:important") - (".*" "nnml:misc"))) -@end lisp - - -@node Various Summary Stuff -@section Various Summary Stuff - -@menu -* Summary Group Information:: Information oriented commands. -* Searching for Articles:: Multiple article commands. -* Summary Generation Commands:: -* Really Various Summary Commands:: Those pesky non-conformant commands. -@end menu - -@table @code -@vindex gnus-summary-display-while-building -@item gnus-summary-display-while-building -If non-@code{nil}, show and update the summary buffer as it's being -built. If @code{t}, update the buffer after every line is inserted. -If the value is an integer, @var{n}, update the display every @var{n} -lines. The default is @code{nil}. - -@vindex gnus-summary-display-arrow -@item gnus-summary-display-arrow -If non-@code{nil}, display an arrow in the fringe to indicate the -current article. - -@vindex gnus-summary-mode-hook -@item gnus-summary-mode-hook -This hook is called when creating a summary mode buffer. - -@vindex gnus-summary-generate-hook -@item gnus-summary-generate-hook -This is called as the last thing before doing the threading and the -generation of the summary buffer. It's quite convenient for customizing -the threading variables based on what data the newsgroup has. This hook -is called from the summary buffer after most summary buffer variables -have been set. - -@vindex gnus-summary-prepare-hook -@item gnus-summary-prepare-hook -It is called after the summary buffer has been generated. You might use -it to, for instance, highlight lines or modify the look of the buffer in -some other ungodly manner. I don't care. - -@vindex gnus-summary-prepared-hook -@item gnus-summary-prepared-hook -A hook called as the very last thing after the summary buffer has been -generated. - -@vindex gnus-summary-ignore-duplicates -@item gnus-summary-ignore-duplicates -When Gnus discovers two articles that have the same @code{Message-ID}, -it has to do something drastic. No articles are allowed to have the -same @code{Message-ID}, but this may happen when reading mail from some -sources. Gnus allows you to customize what happens with this variable. -If it is @code{nil} (which is the default), Gnus will rename the -@code{Message-ID} (for display purposes only) and display the article as -any other article. If this variable is @code{t}, it won't display the -article---it'll be as if it never existed. - -@vindex gnus-alter-articles-to-read-function -@item gnus-alter-articles-to-read-function -This function, which takes two parameters (the group name and the list -of articles to be selected), is called to allow the user to alter the -list of articles to be selected. - -For instance, the following function adds the list of cached articles to -the list in one particular group: - -@lisp -(defun my-add-cached-articles (group articles) - (if (string= group "some.group") - (append gnus-newsgroup-cached articles) - articles)) -@end lisp - -@vindex gnus-newsgroup-variables -@item gnus-newsgroup-variables -A list of newsgroup (summary buffer) local variables, or cons of -variables and their default expressions to be evalled (when the default -values are not @code{nil}), that should be made global while the summary -buffer is active. - -Note: The default expressions will be evaluated (using function -@code{eval}) before assignment to the local variable rather than just -assigned to it. If the default expression is the symbol @code{global}, -that symbol will not be evaluated but the global value of the local -variable will be used instead. - -These variables can be used to set variables in the group parameters -while still allowing them to affect operations done in other -buffers. For example: - -@lisp -(setq gnus-newsgroup-variables - '(message-use-followup-to - (gnus-visible-headers . - "^From:\\|^Newsgroups:\\|^Subject:\\|^Date:\\|^To:"))) -@end lisp - -Also @pxref{Group Parameters}. - -@vindex gnus-propagate-marks -@item gnus-propagate-marks -If non-@code{nil}, propagate marks to the backends for possible -storing. @xref{NNTP marks}, and friends, for a more fine-grained -sieve. - -@end table - - -@node Summary Group Information -@subsection Summary Group Information - -@table @kbd - -@item H f -@kindex H f (Summary) -@findex gnus-summary-fetch-faq -@vindex gnus-group-faq-directory -Try to fetch the @acronym{FAQ} (list of frequently asked questions) -for the current group (@code{gnus-summary-fetch-faq}). Gnus will try -to get the @acronym{FAQ} from @code{gnus-group-faq-directory}, which -is usually a directory on a remote machine. This variable can also be -a list of directories. In that case, giving a prefix to this command -will allow you to choose between the various sites. @code{ange-ftp} -or @code{efs} will probably be used for fetching the file. - -@item H d -@kindex H d (Summary) -@findex gnus-summary-describe-group -Give a brief description of the current group -(@code{gnus-summary-describe-group}). If given a prefix, force -rereading the description from the server. - -@item H h -@kindex H h (Summary) -@findex gnus-summary-describe-briefly -Give an extremely brief description of the most important summary -keystrokes (@code{gnus-summary-describe-briefly}). - -@item H i -@kindex H i (Summary) -@findex gnus-info-find-node -Go to the Gnus info node (@code{gnus-info-find-node}). -@end table - - -@node Searching for Articles -@subsection Searching for Articles - -@table @kbd - -@item M-s -@kindex M-s (Summary) -@findex gnus-summary-search-article-forward -Search through all subsequent (raw) articles for a regexp -(@code{gnus-summary-search-article-forward}). - -@item M-r -@kindex M-r (Summary) -@findex gnus-summary-search-article-backward -Search through all previous (raw) articles for a regexp -(@code{gnus-summary-search-article-backward}). - -@item M-S -@kindex M-S (Summary) -@findex gnus-summary-repeat-search-article-forward -Repeat the previous search forwards -(@code{gnus-summary-repeat-search-article-forward}). - -@item M-R -@kindex M-R (Summary) -@findex gnus-summary-repeat-search-article-backward -Repeat the previous search backwards -(@code{gnus-summary-repeat-search-article-backward}). - -@item & -@kindex & (Summary) -@findex gnus-summary-execute-command -This command will prompt you for a header, a regular expression to match -on this field, and a command to be executed if the match is made -(@code{gnus-summary-execute-command}). If the header is an empty -string, the match is done on the entire article. If given a prefix, -search backward instead. - -For instance, @kbd{& RET some.*string RET #} will put the process mark on -all articles that have heads or bodies that match @samp{some.*string}. - -@item M-& -@kindex M-& (Summary) -@findex gnus-summary-universal-argument -Perform any operation on all articles that have been marked with -the process mark (@code{gnus-summary-universal-argument}). -@end table - -@node Summary Generation Commands -@subsection Summary Generation Commands - -@table @kbd - -@item Y g -@kindex Y g (Summary) -@findex gnus-summary-prepare -Regenerate the current summary buffer (@code{gnus-summary-prepare}). - -@item Y c -@kindex Y c (Summary) -@findex gnus-summary-insert-cached-articles -Pull all cached articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-cached-articles}). - -@item Y d -@kindex Y d (Summary) -@findex gnus-summary-insert-dormant-articles -Pull all dormant articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-dormant-articles}). - -@item Y t -@kindex Y t (Summary) -@findex gnus-summary-insert-ticked-articles -Pull all ticked articles (for the current group) into the summary buffer -(@code{gnus-summary-insert-ticked-articles}). - -@end table - - -@node Really Various Summary Commands -@subsection Really Various Summary Commands - -@table @kbd - -@item A D -@itemx C-d -@kindex C-d (Summary) -@kindex A D (Summary) -@findex gnus-summary-enter-digest-group -If the current article is a collection of other articles (for instance, -a digest), you might use this command to enter a group based on the that -article (@code{gnus-summary-enter-digest-group}). Gnus will try to -guess what article type is currently displayed unless you give a prefix -to this command, which forces a ``digest'' interpretation. Basically, -whenever you see a message that is a collection of other messages of -some format, you @kbd{C-d} and read these messages in a more convenient -fashion. - -@vindex gnus-auto-select-on-ephemeral-exit -The variable @code{gnus-auto-select-on-ephemeral-exit} controls what -article should be selected after exiting a digest group. Valid values -include: - -@table @code -@item next -Select the next article. - -@item next-unread -Select the next unread article. - -@item next-noselect -Move the cursor to the next article. This is the default. - -@item next-unread-noselect -Move the cursor to the next unread article. -@end table - -If it has any other value or there is no next (unread) article, the -article selected before entering to the digest group will appear. - -@item C-M-d -@kindex C-M-d (Summary) -@findex gnus-summary-read-document -This command is very similar to the one above, but lets you gather -several documents into one biiig group -(@code{gnus-summary-read-document}). It does this by opening several -@code{nndoc} groups for each document, and then opening an -@code{nnvirtual} group on top of these @code{nndoc} groups. This -command understands the process/prefix convention -(@pxref{Process/Prefix}). - -@item C-t -@kindex C-t (Summary) -@findex gnus-summary-toggle-truncation -Toggle truncation of summary lines -(@code{gnus-summary-toggle-truncation}). This will probably confuse the -line centering function in the summary buffer, so it's not a good idea -to have truncation switched off while reading articles. - -@item = -@kindex = (Summary) -@findex gnus-summary-expand-window -Expand the summary buffer window (@code{gnus-summary-expand-window}). -If given a prefix, force an @code{article} window configuration. - -@item C-M-e -@kindex C-M-e (Summary) -@findex gnus-summary-edit-parameters -Edit the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-edit-parameters}). - -@item C-M-a -@kindex C-M-a (Summary) -@findex gnus-summary-customize-parameters -Customize the group parameters (@pxref{Group Parameters}) of the current -group (@code{gnus-summary-customize-parameters}). - -@end table - - -@node Exiting the Summary Buffer -@section Exiting the Summary Buffer -@cindex summary exit -@cindex exiting groups - -Exiting from the summary buffer will normally update all info on the -group and return you to the group buffer. - -@table @kbd - -@item Z Z -@itemx Z Q -@itemx q -@kindex Z Z (Summary) -@kindex Z Q (Summary) -@kindex q (Summary) -@findex gnus-summary-exit -@vindex gnus-summary-exit-hook -@vindex gnus-summary-prepare-exit-hook -@vindex gnus-group-no-more-groups-hook -@c @icon{gnus-summary-exit} -Exit the current group and update all information on the group -(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is -called before doing much of the exiting, which calls -@code{gnus-summary-expire-articles} by default. -@code{gnus-summary-exit-hook} is called after finishing the exit -process. @code{gnus-group-no-more-groups-hook} is run when returning to -group mode having no more (unread) groups. - -@item Z E -@itemx Q -@kindex Z E (Summary) -@kindex Q (Summary) -@findex gnus-summary-exit-no-update -Exit the current group without updating any information on the group -(@code{gnus-summary-exit-no-update}). - -@item Z c -@itemx c -@kindex Z c (Summary) -@kindex c (Summary) -@findex gnus-summary-catchup-and-exit -@c @icon{gnus-summary-catchup-and-exit} -Mark all unticked articles in the group as read and then exit -(@code{gnus-summary-catchup-and-exit}). - -@item Z C -@kindex Z C (Summary) -@findex gnus-summary-catchup-all-and-exit -Mark all articles, even the ticked ones, as read and then exit -(@code{gnus-summary-catchup-all-and-exit}). - -@item Z n -@kindex Z n (Summary) -@findex gnus-summary-catchup-and-goto-next-group -Mark all articles as read and go to the next group -(@code{gnus-summary-catchup-and-goto-next-group}). - -@item Z p -@kindex Z p (Summary) -@findex gnus-summary-catchup-and-goto-prev-group -Mark all articles as read and go to the previous group -(@code{gnus-summary-catchup-and-goto-prev-group}). - -@item Z R -@itemx C-x C-s -@kindex Z R (Summary) -@kindex C-x C-s (Summary) -@findex gnus-summary-reselect-current-group -Exit this group, and then enter it again -(@code{gnus-summary-reselect-current-group}). If given a prefix, select -all articles, both read and unread. - -@item Z G -@itemx M-g -@kindex Z G (Summary) -@kindex M-g (Summary) -@findex gnus-summary-rescan-group -@c @icon{gnus-summary-mail-get} -Exit the group, check for new articles in the group, and select the -group (@code{gnus-summary-rescan-group}). If given a prefix, select all -articles, both read and unread. - -@item Z N -@kindex Z N (Summary) -@findex gnus-summary-next-group -Exit the group and go to the next group -(@code{gnus-summary-next-group}). - -@item Z P -@kindex Z P (Summary) -@findex gnus-summary-prev-group -Exit the group and go to the previous group -(@code{gnus-summary-prev-group}). - -@item Z s -@kindex Z s (Summary) -@findex gnus-summary-save-newsrc -Save the current number of read/marked articles in the dribble buffer -and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If -given a prefix, also save the @file{.newsrc} file(s). Using this -command will make exit without updating (the @kbd{Q} command) worthless. -@end table - -@vindex gnus-exit-group-hook -@code{gnus-exit-group-hook} is called when you exit the current group -with an ``updating'' exit. For instance @kbd{Q} -(@code{gnus-summary-exit-no-update}) does not call this hook. - -@findex gnus-summary-wake-up-the-dead -@findex gnus-dead-summary-mode -@vindex gnus-kill-summary-on-exit -If you're in the habit of exiting groups, and then changing your mind -about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. -If you do that, Gnus won't kill the summary buffer when you exit it. -(Quelle surprise!) Instead it will change the name of the buffer to -something like @samp{*Dead Summary ... *} and install a minor mode -called @code{gnus-dead-summary-mode}. Now, if you switch back to this -buffer, you'll find that all keys are mapped to a function called -@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead -summary buffer will result in a live, normal summary buffer. - -There will never be more than one dead summary buffer at any one time. - -@vindex gnus-use-cross-reference -The data on the current group will be updated (which articles you have -read, which articles you have replied to, etc.) when you exit the -summary buffer. If the @code{gnus-use-cross-reference} variable is -@code{t} (which is the default), articles that are cross-referenced to -this group and are marked as read, will also be marked as read in the -other subscribed groups they were cross-posted to. If this variable is -neither @code{nil} nor @code{t}, the article will be marked as read in -both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). - - -@node Crosspost Handling -@section Crosspost Handling - -@cindex velveeta -@cindex spamming -Marking cross-posted articles as read ensures that you'll never have to -read the same article more than once. Unless, of course, somebody has -posted it to several groups separately. Posting the same article to -several groups (not cross-posting) is called @dfn{spamming}, and you are -by law required to send nasty-grams to anyone who perpetrates such a -heinous crime. You may want to try NoCeM handling to filter out spam -(@pxref{NoCeM}). - -Remember: Cross-posting is kinda ok, but posting the same article -separately to several groups is not. Massive cross-posting (aka. -@dfn{velveeta}) is to be avoided at all costs, and you can even use the -@code{gnus-summary-mail-crosspost-complaint} command to complain about -excessive crossposting (@pxref{Summary Mail Commands}). - -@cindex cross-posting -@cindex Xref -@cindex @acronym{NOV} -One thing that may cause Gnus to not do the cross-posting thing -correctly is if you use an @acronym{NNTP} server that supports @sc{xover} -(which is very nice, because it speeds things up considerably) which -does not include the @code{Xref} header in its @acronym{NOV} lines. This is -Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing -even with @sc{xover} by registering the @code{Xref} lines of all -articles you actually read, but if you kill the articles, or just mark -them as read without reading them, Gnus will not get a chance to snoop -the @code{Xref} lines out of these articles, and will be unable to use -the cross reference mechanism. - -@cindex LIST overview.fmt -@cindex overview.fmt -To check whether your @acronym{NNTP} server includes the @code{Xref} header -in its overview files, try @samp{telnet your.nntp.server nntp}, -@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST -overview.fmt}. This may not work, but if it does, and the last line you -get does not read @samp{Xref:full}, then you should shout and whine at -your news admin until she includes the @code{Xref} header in the -overview files. - -If you want Gnus to get the @code{Xref}s right all the time, you have to -set @code{nntp-nov-is-evil} to @code{t}, which slows things down -considerably. Also @pxref{Slow/Expensive Connection}. - -C'est la vie. - -For an alternative approach, @pxref{Duplicate Suppression}. - - -@node Duplicate Suppression -@section Duplicate Suppression - -By default, Gnus tries to make sure that you don't have to read the same -article more than once by utilizing the crossposting mechanism -(@pxref{Crosspost Handling}). However, that simple and efficient -approach may not work satisfactory for some users for various -reasons. - -@enumerate -@item -The @acronym{NNTP} server may fail to generate the @code{Xref} header. This -is evil and not very common. - -@item -The @acronym{NNTP} server may fail to include the @code{Xref} header in the -@file{.overview} data bases. This is evil and all too common, alas. - -@item -You may be reading the same group (or several related groups) from -different @acronym{NNTP} servers. - -@item -You may be getting mail that duplicates articles posted to groups. -@end enumerate - -I'm sure there are other situations where @code{Xref} handling fails as -well, but these four are the most common situations. - -If, and only if, @code{Xref} handling fails for you, then you may -consider switching on @dfn{duplicate suppression}. If you do so, Gnus -will remember the @code{Message-ID}s of all articles you have read or -otherwise marked as read, and then, as if by magic, mark them as read -all subsequent times you see them---in @emph{all} groups. Using this -mechanism is quite likely to be somewhat inefficient, but not overly -so. It's certainly preferable to reading the same articles more than -once. - -Duplicate suppression is not a very subtle instrument. It's more like a -sledge hammer than anything else. It works in a very simple -fashion---if you have marked an article as read, it adds this Message-ID -to a cache. The next time it sees this Message-ID, it will mark the -article as read with the @samp{M} mark. It doesn't care what group it -saw the article in. - -@table @code -@item gnus-suppress-duplicates -@vindex gnus-suppress-duplicates -If non-@code{nil}, suppress duplicates. - -@item gnus-save-duplicate-list -@vindex gnus-save-duplicate-list -If non-@code{nil}, save the list of duplicates to a file. This will -make startup and shutdown take longer, so the default is @code{nil}. -However, this means that only duplicate articles read in a single Gnus -session are suppressed. - -@item gnus-duplicate-list-length -@vindex gnus-duplicate-list-length -This variable says how many @code{Message-ID}s to keep in the duplicate -suppression list. The default is 10000. - -@item gnus-duplicate-file -@vindex gnus-duplicate-file -The name of the file to store the duplicate suppression list in. The -default is @file{~/News/suppression}. -@end table - -If you have a tendency to stop and start Gnus often, setting -@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If -you leave Gnus running for weeks on end, you may have it @code{nil}. On -the other hand, saving the list makes startup and shutdown much slower, -so that means that if you stop and start Gnus often, you should set -@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up -to you to figure out, I think. - -@node Security -@section Security - -Gnus is able to verify signed messages or decrypt encrypted messages. -The formats that are supported are @acronym{PGP}, @acronym{PGP/MIME} -and @acronym{S/MIME}, however you need some external programs to get -things to work: - -@enumerate -@item -To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to -install an OpenPGP implementation such as GnuPG. The Lisp interface -to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, -epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, -PGG Manual}), Mailcrypt, and gpg.el are also supported. - -@item -To handle @acronym{S/MIME} message, you need to install OpenSSL. OpenSSL 0.9.6 -or newer is recommended. - -@end enumerate - -The variables that control security functionality on reading messages -include: - -@table @code -@item mm-verify-option -@vindex mm-verify-option -Option of verifying signed parts. @code{never}, not verify; -@code{always}, always verify; @code{known}, only verify known -protocols. Otherwise, ask user. - -@item mm-decrypt-option -@vindex mm-decrypt-option -Option of decrypting encrypted parts. @code{never}, no decryption; -@code{always}, always decrypt; @code{known}, only decrypt known -protocols. Otherwise, ask user. - -@item mml1991-use -@vindex mml1991-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, -@code{mailcrypt}, and @code{gpg} are also supported although -deprecated. By default, Gnus uses the first available interface in -this order. - -@item mml2015-use -@vindex mml2015-use -Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP/MIME} messages. The default is @code{epg}, but -@code{pgg}, @code{mailcrypt}, and @code{gpg} are also supported -although deprecated. By default, Gnus uses the first available -interface in this order. - -@end table - -By default the buttons that display security information are not -shown, because they clutter reading the actual e-mail. You can type -@kbd{K b} manually to display the information. Use the -@code{gnus-buttonized-mime-types} and -@code{gnus-unbuttonized-mime-types} variables to control this -permanently. @ref{MIME Commands} for further details, and hints on -how to customize these variables to always display security -information. - -@cindex snarfing keys -@cindex importing PGP keys -@cindex PGP key ring import -Snarfing OpenPGP keys (i.e., importing keys from articles into your -key ring) is not supported explicitly through a menu item or command, -rather Gnus do detect and label keys as @samp{application/pgp-keys}, -allowing you to specify whatever action you think is appropriate -through the usual @acronym{MIME} infrastructure. You can use a -@file{~/.mailcap} entry (@pxref{mailcap, , mailcap, emacs-mime, The -Emacs MIME Manual}) such as the following to import keys using GNU -Privacy Guard when you click on the @acronym{MIME} button -(@pxref{Using MIME}). - -@example -application/pgp-keys; gpg --import --interactive --verbose; needsterminal -@end example -@noindent -This happens to also be the default action defined in -@code{mailcap-mime-data}. - -More information on how to set things for sending outgoing signed and -encrypted messages up can be found in the message manual -(@pxref{Security, ,Security, message, Message Manual}). - -@node Mailing List -@section Mailing List -@cindex mailing list -@cindex RFC 2396 - -@kindex A M (summary) -@findex gnus-mailing-list-insinuate -Gnus understands some mailing list fields of RFC 2369. To enable it, -add a @code{to-list} group parameter (@pxref{Group Parameters}), -possibly using @kbd{A M} (@code{gnus-mailing-list-insinuate}) in the -summary buffer. - -That enables the following commands to the summary buffer: - -@table @kbd - -@item C-c C-n h -@kindex C-c C-n h (Summary) -@findex gnus-mailing-list-help -Send a message to fetch mailing list help, if List-Help field exists. - -@item C-c C-n s -@kindex C-c C-n s (Summary) -@findex gnus-mailing-list-subscribe -Send a message to subscribe the mailing list, if List-Subscribe field exists. - -@item C-c C-n u -@kindex C-c C-n u (Summary) -@findex gnus-mailing-list-unsubscribe -Send a message to unsubscribe the mailing list, if List-Unsubscribe -field exists. - -@item C-c C-n p -@kindex C-c C-n p (Summary) -@findex gnus-mailing-list-post -Post to the mailing list, if List-Post field exists. - -@item C-c C-n o -@kindex C-c C-n o (Summary) -@findex gnus-mailing-list-owner -Send a message to the mailing list owner, if List-Owner field exists. - -@item C-c C-n a -@kindex C-c C-n a (Summary) -@findex gnus-mailing-list-archive -Browse the mailing list archive, if List-Archive field exists. - -@end table - - -@node Article Buffer -@chapter Article Buffer -@cindex article buffer - -The articles are displayed in the article buffer, of which there is only -one. All the summary buffers share the same article buffer unless you -tell Gnus otherwise. - -@menu -* Hiding Headers:: Deciding what headers should be displayed. -* Using MIME:: Pushing articles through @acronym{MIME} before reading them. -* Customizing Articles:: Tailoring the look of the articles. -* Article Keymap:: Keystrokes available in the article buffer. -* Misc Article:: Other stuff. -@end menu - - -@node Hiding Headers -@section Hiding Headers -@cindex hiding headers -@cindex deleting headers - -The top section of each article is the @dfn{head}. (The rest is the -@dfn{body}, but you may have guessed that already.) - -@vindex gnus-show-all-headers -There is a lot of useful information in the head: the name of the person -who wrote the article, the date it was written and the subject of the -article. That's well and nice, but there's also lots of information -most people do not want to see---what systems the article has passed -through before reaching you, the @code{Message-ID}, the -@code{References}, etc. ad nauseam---and you'll probably want to get rid -of some of those lines. If you want to keep all those lines in the -article buffer, you can set @code{gnus-show-all-headers} to @code{t}. - -Gnus provides you with two variables for sifting headers: - -@table @code - -@item gnus-visible-headers -@vindex gnus-visible-headers -If this variable is non-@code{nil}, it should be a regular expression -that says what headers you wish to keep in the article buffer. All -headers that do not match this variable will be hidden. - -For instance, if you only want to see the name of the person who wrote -the article and the subject, you'd say: - -@lisp -(setq gnus-visible-headers "^From:\\|^Subject:") -@end lisp - -This variable can also be a list of regexps to match headers to -remain visible. - -@item gnus-ignored-headers -@vindex gnus-ignored-headers -This variable is the reverse of @code{gnus-visible-headers}. If this -variable is set (and @code{gnus-visible-headers} is @code{nil}), it -should be a regular expression that matches all lines that you want to -hide. All lines that do not match this variable will remain visible. - -For instance, if you just want to get rid of the @code{References} line -and the @code{Xref} line, you might say: - -@lisp -(setq gnus-ignored-headers "^References:\\|^Xref:") -@end lisp - -This variable can also be a list of regexps to match headers to -be removed. - -Note that if @code{gnus-visible-headers} is non-@code{nil}, this -variable will have no effect. - -@end table - -@vindex gnus-sorted-header-list -Gnus can also sort the headers for you. (It does this by default.) You -can control the sorting by setting the @code{gnus-sorted-header-list} -variable. It is a list of regular expressions that says in what order -the headers are to be displayed. - -For instance, if you want the name of the author of the article first, -and then the subject, you might say something like: - -@lisp -(setq gnus-sorted-header-list '("^From:" "^Subject:")) -@end lisp - -Any headers that are to remain visible, but are not listed in this -variable, will be displayed in random order after all the headers listed in this variable. - -@findex gnus-article-hide-boring-headers -@vindex gnus-boring-article-headers -You can hide further boring headers by setting -@code{gnus-treat-hide-boring-headers} to @code{head}. What this function -does depends on the @code{gnus-boring-article-headers} variable. It's a -list, but this list doesn't actually contain header names. Instead it -lists various @dfn{boring conditions} that Gnus can check and remove -from sight. - -These conditions are: -@table @code -@item empty -Remove all empty headers. -@item followup-to -Remove the @code{Followup-To} header if it is identical to the -@code{Newsgroups} header. -@item reply-to -Remove the @code{Reply-To} header if it lists the same addresses as -the @code{From} header, or if the @code{broken-reply-to} group -parameter is set. -@item newsgroups -Remove the @code{Newsgroups} header if it only contains the current group -name. -@item to-address -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-address} parameter. -@item to-list -Remove the @code{To} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item cc-list -Remove the @code{Cc} header if it only contains the address identical to -the current group's @code{to-list} parameter. -@item date -Remove the @code{Date} header if the article is less than three days -old. -@item long-to -Remove the @code{To} and/or @code{Cc} header if it is very long. -@item many-to -Remove all @code{To} and/or @code{Cc} headers if there are more than one. -@end table - -To include these three elements, you could say something like: - -@lisp -(setq gnus-boring-article-headers - '(empty followup-to reply-to)) -@end lisp - -This is also the default value for this variable. - - -@node Using MIME -@section Using MIME -@cindex @acronym{MIME} - -Mime is a standard for waving your hands through the air, aimlessly, -while people stand around yawning. - -@acronym{MIME}, however, is a standard for encoding your articles, aimlessly, -while all newsreaders die of fear. - -@acronym{MIME} may specify what character set the article uses, the encoding -of the characters, and it also makes it possible to embed pictures and -other naughty stuff in innocent-looking articles. - -@vindex gnus-display-mime-function -@findex gnus-display-mime -Gnus pushes @acronym{MIME} articles through @code{gnus-display-mime-function} -to display the @acronym{MIME} parts. This is @code{gnus-display-mime} by -default, which creates a bundle of clickable buttons that can be used to -display, save and manipulate the @acronym{MIME} objects. - -The following commands are available when you have placed point over a -@acronym{MIME} button: - -@table @kbd -@findex gnus-article-press-button -@item RET (Article) -@kindex RET (Article) -@itemx BUTTON-2 (Article) -Toggle displaying of the @acronym{MIME} object -(@code{gnus-article-press-button}). If built-in viewers can not display -the object, Gnus resorts to external viewers in the @file{mailcap} -files. If a viewer has the @samp{copiousoutput} specification, the -object is displayed inline. - -@findex gnus-mime-view-part -@item M-RET (Article) -@kindex M-RET (Article) -@itemx v (Article) -Prompt for a method, and then view the @acronym{MIME} object using this -method (@code{gnus-mime-view-part}). - -@findex gnus-mime-view-part-as-type -@item t (Article) -@kindex t (Article) -View the @acronym{MIME} object as if it were a different @acronym{MIME} media type -(@code{gnus-mime-view-part-as-type}). - -@findex gnus-mime-view-part-as-charset -@item C (Article) -@kindex C (Article) -Prompt for a charset, and then view the @acronym{MIME} object using this -charset (@code{gnus-mime-view-part-as-charset}). - -@findex gnus-mime-save-part -@item o (Article) -@kindex o (Article) -Prompt for a file name, and then save the @acronym{MIME} object -(@code{gnus-mime-save-part}). - -@findex gnus-mime-save-part-and-strip -@item C-o (Article) -@kindex C-o (Article) -Prompt for a file name, then save the @acronym{MIME} object and strip it from -the article. Then proceed to article editing, where a reasonable -suggestion is being made on how the altered article should look -like. The stripped @acronym{MIME} object will be referred via the -message/external-body @acronym{MIME} type. -(@code{gnus-mime-save-part-and-strip}). - -@findex gnus-mime-replace-part -@item r (Article) -@kindex r (Article) -Prompt for a file name, replace the @acronym{MIME} object with an -external body refering to the file via the message/external-body -@acronym{MIME} type. (@code{gnus-mime-replace-part}). - -@findex gnus-mime-delete-part -@item d (Article) -@kindex d (Article) -Delete the @acronym{MIME} object from the article and replace it with some -information about the removed @acronym{MIME} object -(@code{gnus-mime-delete-part}). - -@c FIXME: gnus-auto-select-part should be documented here - -@findex gnus-mime-copy-part -@item c (Article) -@kindex c (Article) -Copy the @acronym{MIME} object to a fresh buffer and display this buffer -(@code{gnus-mime-copy-part}). If given a prefix, copy the raw contents -without decoding. If given a numerical prefix, you can do semi-manual -charset stuff (see @code{gnus-summary-show-article-charset-alist} in -@ref{Paging the Article}). Compressed files like @file{.gz} and -@file{.bz2} are automatically decompressed if -@code{auto-compression-mode} is enabled (@pxref{Compressed Files,, -Accessing Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-print-part -@item p (Article) -@kindex p (Article) -Print the @acronym{MIME} object (@code{gnus-mime-print-part}). This -command respects the @samp{print=} specifications in the -@file{.mailcap} file. - -@findex gnus-mime-inline-part -@item i (Article) -@kindex i (Article) -Insert the contents of the @acronym{MIME} object into the buffer -(@code{gnus-mime-inline-part}) as @samp{text/plain}. If given a prefix, insert -the raw contents without decoding. If given a numerical prefix, you can -do semi-manual charset stuff (see -@code{gnus-summary-show-article-charset-alist} in @ref{Paging the -Article}). Compressed files like @file{.gz} and @file{.bz2} are -automatically decompressed depending on @code{jka-compr} regardless of -@code{auto-compression-mode} (@pxref{Compressed Files,, Accessing -Compressed Files, emacs, The Emacs Editor}). - -@findex gnus-mime-view-part-internally -@item E (Article) -@kindex E (Article) -View the @acronym{MIME} object with an internal viewer. If no internal -viewer is available, use an external viewer -(@code{gnus-mime-view-part-internally}). - -@findex gnus-mime-view-part-externally -@item e (Article) -@kindex e (Article) -View the @acronym{MIME} object with an external viewer. -(@code{gnus-mime-view-part-externally}). - -@findex gnus-mime-pipe-part -@item | (Article) -@kindex | (Article) -Output the @acronym{MIME} object to a process (@code{gnus-mime-pipe-part}). - -@findex gnus-mime-action-on-part -@item . (Article) -@kindex . (Article) -Interactively run an action on the @acronym{MIME} object -(@code{gnus-mime-action-on-part}). - -@end table - -Gnus will display some @acronym{MIME} objects automatically. The way Gnus -determines which parts to do this with is described in the Emacs -@acronym{MIME} manual. - -It might be best to just use the toggling functions from the article -buffer to avoid getting nasty surprises. (For instance, you enter the -group @samp{alt.sing-a-long} and, before you know it, @acronym{MIME} has -decoded the sound file in the article and some horrible sing-a-long song -comes screaming out your speakers, and you can't find the volume button, -because there isn't one, and people are starting to look at you, and you -try to stop the program, but you can't, and you can't find the program -to control the volume, and everybody else in the room suddenly decides -to look at you disdainfully, and you'll feel rather stupid.) - -Any similarity to real events and people is purely coincidental. Ahem. - -Also @pxref{MIME Commands}. - - -@node Customizing Articles -@section Customizing Articles -@cindex article customization - -A slew of functions for customizing how the articles are to look like -exist. You can call these functions interactively -(@pxref{Article Washing}), or you can have them -called automatically when you select the articles. - -To have them called automatically, you should set the corresponding -``treatment'' variable. For instance, to have headers hidden, you'd set -@code{gnus-treat-hide-headers}. Below is a list of variables that can -be set, but first we discuss the values these variables can have. - -Note: Some values, while valid, make little sense. Check the list below -for sensible values. - -@enumerate -@item -@code{nil}: Don't do this treatment. - -@item -@code{t}: Do this treatment on all body parts. - -@item -@code{head}: Do the treatment on the headers. - -@item -@code{first}: Do this treatment on the first body part. - -@item -@code{last}: Do this treatment on the last body part. - -@item -An integer: Do this treatment on all body parts that have a length less -than this number. - -@item -A list of strings: Do this treatment on all body parts that are in -articles that are read in groups that have names that match one of the -regexps in the list. - -@item -A list where the first element is not a string: - -The list is evaluated recursively. The first element of the list is a -predicate. The following predicates are recognized: @code{or}, -@code{and}, @code{not} and @code{typep}. Here's an example: - -@lisp -(or last - (typep "text/x-vcard")) -@end lisp - -@end enumerate - -You may have noticed that the word @dfn{part} is used here. This refers -to the fact that some messages are @acronym{MIME} multipart articles that may -be divided into several parts. Articles that are not multiparts are -considered to contain just a single part. - -@vindex gnus-article-treat-types -Are the treatments applied to all sorts of multipart parts? Yes, if you -want to, but by default, only @samp{text/plain} parts are given the -treatment. This is controlled by the @code{gnus-article-treat-types} -variable, which is a list of regular expressions that are matched to the -type of the part. This variable is ignored if the value of the -controlling variable is a predicate list, as described above. - -@ifinfo -@c Avoid sort of redundant entries in the same section for the printed -@c manual, but add them in info to allow `i gnus-treat-foo-bar RET' or -@c `i foo-bar'. -@vindex gnus-treat-buttonize -@vindex gnus-treat-buttonize-head -@vindex gnus-treat-capitalize-sentences -@vindex gnus-treat-overstrike -@vindex gnus-treat-strip-cr -@vindex gnus-treat-strip-headers-in-body -@vindex gnus-treat-strip-leading-blank-lines -@vindex gnus-treat-strip-multiple-blank-lines -@vindex gnus-treat-strip-pem -@vindex gnus-treat-strip-trailing-blank-lines -@vindex gnus-treat-unsplit-urls -@vindex gnus-treat-wash-html -@vindex gnus-treat-date-english -@vindex gnus-treat-date-iso8601 -@vindex gnus-treat-date-lapsed -@vindex gnus-treat-date-local -@vindex gnus-treat-date-original -@vindex gnus-treat-date-user-defined -@vindex gnus-treat-date-ut -@vindex gnus-treat-from-picon -@vindex gnus-treat-mail-picon -@vindex gnus-treat-newsgroups-picon -@vindex gnus-treat-display-smileys -@vindex gnus-treat-body-boundary -@vindex gnus-treat-display-x-face -@vindex gnus-treat-display-face -@vindex gnus-treat-emphasize -@vindex gnus-treat-fill-article -@vindex gnus-treat-fill-long-lines -@vindex gnus-treat-hide-boring-headers -@vindex gnus-treat-hide-citation -@vindex gnus-treat-hide-citation-maybe -@vindex gnus-treat-hide-headers -@vindex gnus-treat-hide-signature -@vindex gnus-treat-strip-banner -@vindex gnus-treat-strip-list-identifiers -@vindex gnus-treat-highlight-citation -@vindex gnus-treat-highlight-headers -@vindex gnus-treat-highlight-signature -@vindex gnus-treat-play-sounds -@vindex gnus-treat-translate -@vindex gnus-treat-x-pgp-sig -@vindex gnus-treat-unfold-headers -@vindex gnus-treat-fold-headers -@vindex gnus-treat-fold-newsgroups -@vindex gnus-treat-leading-whitespace -@end ifinfo - -The following treatment options are available. The easiest way to -customize this is to examine the @code{gnus-article-treat} customization -group. Values in parenthesis are suggested sensible values. Others are -possible but those listed are probably sufficient for most people. - -@table @code -@item gnus-treat-buttonize (t, integer) -@item gnus-treat-buttonize-head (head) - -@xref{Article Buttons}. - -@item gnus-treat-capitalize-sentences (t, integer) -@item gnus-treat-overstrike (t, integer) -@item gnus-treat-strip-cr (t, integer) -@item gnus-treat-strip-headers-in-body (t, integer) -@item gnus-treat-strip-leading-blank-lines (t, first, integer) -@item gnus-treat-strip-multiple-blank-lines (t, integer) -@item gnus-treat-strip-pem (t, last, integer) -@item gnus-treat-strip-trailing-blank-lines (t, last, integer) -@item gnus-treat-unsplit-urls (t, integer) -@item gnus-treat-wash-html (t, integer) - -@xref{Article Washing}. - -@item gnus-treat-date-english (head) -@item gnus-treat-date-iso8601 (head) -@item gnus-treat-date-lapsed (head) -@item gnus-treat-date-local (head) -@item gnus-treat-date-original (head) -@item gnus-treat-date-user-defined (head) -@item gnus-treat-date-ut (head) - -@xref{Article Date}. - -@item gnus-treat-from-picon (head) -@item gnus-treat-mail-picon (head) -@item gnus-treat-newsgroups-picon (head) - -@xref{Picons}. - -@item gnus-treat-display-smileys (t, integer) - -@item gnus-treat-body-boundary (head) - -@vindex gnus-body-boundary-delimiter -Adds a delimiter between header and body, the string used as delimiter -is controlled by @code{gnus-body-boundary-delimiter}. - -@xref{Smileys}. - -@vindex gnus-treat-display-x-face -@item gnus-treat-display-x-face (head) - -@xref{X-Face}. - -@vindex gnus-treat-display-face -@item gnus-treat-display-face (head) - -@xref{Face}. - -@vindex gnus-treat-emphasize -@item gnus-treat-emphasize (t, head, integer) -@vindex gnus-treat-fill-article -@item gnus-treat-fill-article (t, integer) -@vindex gnus-treat-fill-long-lines -@item gnus-treat-fill-long-lines (t, integer) -@vindex gnus-treat-hide-boring-headers -@item gnus-treat-hide-boring-headers (head) -@vindex gnus-treat-hide-citation -@item gnus-treat-hide-citation (t, integer) -@vindex gnus-treat-hide-citation-maybe -@item gnus-treat-hide-citation-maybe (t, integer) -@vindex gnus-treat-hide-headers -@item gnus-treat-hide-headers (head) -@vindex gnus-treat-hide-signature -@item gnus-treat-hide-signature (t, last) -@vindex gnus-treat-strip-banner -@item gnus-treat-strip-banner (t, last) -@vindex gnus-treat-strip-list-identifiers -@item gnus-treat-strip-list-identifiers (head) - -@xref{Article Hiding}. - -@vindex gnus-treat-highlight-citation -@item gnus-treat-highlight-citation (t, integer) -@vindex gnus-treat-highlight-headers -@item gnus-treat-highlight-headers (head) -@vindex gnus-treat-highlight-signature -@item gnus-treat-highlight-signature (t, last, integer) - -@xref{Article Highlighting}. - -@vindex gnus-treat-play-sounds -@item gnus-treat-play-sounds -@vindex gnus-treat-translate -@item gnus-treat-translate -@item gnus-treat-ansi-sequences (t) -@vindex gnus-treat-x-pgp-sig -@item gnus-treat-x-pgp-sig (head) - -@vindex gnus-treat-unfold-headers -@item gnus-treat-unfold-headers (head) -@vindex gnus-treat-fold-headers -@item gnus-treat-fold-headers (head) -@vindex gnus-treat-fold-newsgroups -@item gnus-treat-fold-newsgroups (head) -@vindex gnus-treat-leading-whitespace -@item gnus-treat-leading-whitespace (head) - -@xref{Article Header}. - - -@end table - -@vindex gnus-part-display-hook -You can, of course, write your own functions to be called from -@code{gnus-part-display-hook}. The functions are called narrowed to the -part, and you can do anything you like, pretty much. There is no -information that you have to keep in the buffer---you can change -everything. - - -@node Article Keymap -@section Article Keymap - -Most of the keystrokes in the summary buffer can also be used in the -article buffer. They should behave as if you typed them in the summary -buffer, which means that you don't actually have to have a summary -buffer displayed while reading. You can do it all from the article -buffer. - -@kindex v (Article) -@cindex keys, reserved for users (Article) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -A few additional keystrokes are available: - -@table @kbd - -@item SPACE -@kindex SPACE (Article) -@findex gnus-article-next-page -Scroll forwards one page (@code{gnus-article-next-page}). -This is exactly the same as @kbd{h SPACE h}. - -@item DEL -@kindex DEL (Article) -@findex gnus-article-prev-page -Scroll backwards one page (@code{gnus-article-prev-page}). -This is exactly the same as @kbd{h DEL h}. - -@item C-c ^ -@kindex C-c ^ (Article) -@findex gnus-article-refer-article -If point is in the neighborhood of a @code{Message-ID} and you press -@kbd{C-c ^}, Gnus will try to get that article from the server -(@code{gnus-article-refer-article}). - -@item C-c C-m -@kindex C-c C-m (Article) -@findex gnus-article-mail -Send a reply to the address near point (@code{gnus-article-mail}). If -given a prefix, include the mail. - -@item s -@kindex s (Article) -@findex gnus-article-show-summary -Reconfigure the buffers so that the summary buffer becomes visible -(@code{gnus-article-show-summary}). - -@item ? -@kindex ? (Article) -@findex gnus-article-describe-briefly -Give a very brief description of the available keystrokes -(@code{gnus-article-describe-briefly}). - -@item TAB -@kindex TAB (Article) -@findex gnus-article-next-button -Go to the next button, if any (@code{gnus-article-next-button}). This -only makes sense if you have buttonizing turned on. - -@item M-TAB -@kindex M-TAB (Article) -@findex gnus-article-prev-button -Go to the previous button, if any (@code{gnus-article-prev-button}). - -@item R -@kindex R (Article) -@findex gnus-article-reply-with-original -Send a reply to the current article and yank the current article -(@code{gnus-article-reply-with-original}). If the region is active, -only yank the text in the region. - -@item S W -@kindex S W (Article) -@findex gnus-article-wide-reply-with-original -Send a wide reply to the current article and yank the current article -(@code{gnus-article-wide-reply-with-original}). If the region is -active, only yank the text in the region. - -@item F -@kindex F (Article) -@findex gnus-article-followup-with-original -Send a followup to the current article and yank the current article -(@code{gnus-article-followup-with-original}). If the region is active, -only yank the text in the region. - - -@end table - - -@node Misc Article -@section Misc Article - -@table @code - -@item gnus-single-article-buffer -@vindex gnus-single-article-buffer -@cindex article buffers, several -If non-@code{nil}, use the same article buffer for all the groups. -(This is the default.) If @code{nil}, each group will have its own -article buffer. - -@vindex gnus-article-decode-hook -@item gnus-article-decode-hook -@cindex @acronym{MIME} -Hook used to decode @acronym{MIME} articles. The default value is -@code{(article-decode-charset article-decode-encoded-words)} - -@vindex gnus-article-prepare-hook -@item gnus-article-prepare-hook -This hook is called right after the article has been inserted into the -article buffer. It is mainly intended for functions that do something -depending on the contents; it should probably not be used for changing -the contents of the article buffer. - -@item gnus-article-mode-hook -@vindex gnus-article-mode-hook -Hook called in article mode buffers. - -@item gnus-article-mode-syntax-table -@vindex gnus-article-mode-syntax-table -Syntax table used in article buffers. It is initialized from -@code{text-mode-syntax-table}. - -@vindex gnus-article-over-scroll -@item gnus-article-over-scroll -If non-@code{nil}, allow scrolling the article buffer even when there -no more new text to scroll in. The default is @code{nil}. - -@vindex gnus-article-mode-line-format -@item gnus-article-mode-line-format -This variable is a format string along the same lines as -@code{gnus-summary-mode-line-format} (@pxref{Summary Buffer Mode -Line}). It accepts the same format specifications as that variable, -with two extensions: - -@table @samp - -@item w -The @dfn{wash status} of the article. This is a short string with one -character for each possible article wash operation that may have been -performed. The characters and their meaning: - -@table @samp - -@item c -Displayed when cited text may be hidden in the article buffer. - -@item h -Displayed when headers are hidden in the article buffer. - -@item p -Displayed when article is digitally signed or encrypted, and Gnus has -hidden the security headers. (N.B. does not tell anything about -security status, i.e. good or bad signature.) - -@item s -Displayed when the signature has been hidden in the Article buffer. - -@item o -Displayed when Gnus has treated overstrike characters in the article buffer. - -@item e -Displayed when Gnus has treated emphasized strings in the article buffer. - -@end table - -@item m -The number of @acronym{MIME} parts in the article. - -@end table - -@vindex gnus-break-pages - -@item gnus-break-pages -Controls whether @dfn{page breaking} is to take place. If this variable -is non-@code{nil}, the articles will be divided into pages whenever a -page delimiter appears in the article. If this variable is @code{nil}, -paging will not be done. - -@item gnus-page-delimiter -@vindex gnus-page-delimiter -This is the delimiter mentioned above. By default, it is @samp{^L} -(formfeed). - -@cindex IDNA -@cindex internationalized domain names -@vindex gnus-use-idna -@item gnus-use-idna -This variable controls whether Gnus performs IDNA decoding of -internationalized domain names inside @samp{From}, @samp{To} and -@samp{Cc} headers. @xref{IDNA, ,IDNA,message, The Message Manual}, -for how to compose such messages. This requires -@uref{http://www.gnu.org/software/libidn/, GNU Libidn}, and this -variable is only enabled if you have installed it. - -@end table - - -@node Composing Messages -@chapter Composing Messages -@cindex composing messages -@cindex messages -@cindex mail -@cindex sending mail -@cindex reply -@cindex followup -@cindex post -@cindex using gpg -@cindex using s/mime -@cindex using smime - -@kindex C-c C-c (Post) -All commands for posting and mailing will put you in a message buffer -where you can edit the article all you like, before you send the -article by pressing @kbd{C-c C-c}. @xref{Top, , Overview, message, -Message Manual}. Where the message will be posted/mailed to depends -on your setup (@pxref{Posting Server}). - -@menu -* Mail:: Mailing and replying. -* Posting Server:: What server should you post and mail via? -* POP before SMTP:: You cannot send a mail unless you read a mail. -* Mail and Post:: Mailing and posting at the same time. -* Archived Messages:: Where Gnus stores the messages you've sent. -* Posting Styles:: An easier way to specify who you are. -* Drafts:: Postponing messages and rejected messages. -* Rejected Articles:: What happens if the server doesn't like your article? -* Signing and encrypting:: How to compose secure messages. -@end menu - -Also @pxref{Canceling and Superseding} for information on how to -remove articles you shouldn't have posted. - - -@node Mail -@section Mail - -Variables for customizing outgoing mail: - -@table @code -@item gnus-uu-digest-headers -@vindex gnus-uu-digest-headers -List of regexps to match headers included in digested messages. The -headers will be included in the sequence they are matched. If -@code{nil} include all headers. - -@item gnus-add-to-list -@vindex gnus-add-to-list -If non-@code{nil}, add a @code{to-list} group parameter to mail groups -that have none when you do a @kbd{a}. - -@item gnus-confirm-mail-reply-to-news -@vindex gnus-confirm-mail-reply-to-news -If non-@code{nil}, Gnus will ask you for a confirmation when you are -about to reply to news articles by mail. If it is @code{nil}, nothing -interferes in what you want to do. This can also be a function -receiving the group name as the only parameter which should return -non-@code{nil} if a confirmation is needed, or a regular expression -matching group names, where confirmation should be asked for. - -If you find yourself never wanting to reply to mail, but occasionally -press @kbd{R} anyway, this variable might be for you. - -@item gnus-confirm-treat-mail-like-news -@vindex gnus-confirm-treat-mail-like-news -If non-@code{nil}, Gnus also requests confirmation according to -@code{gnus-confirm-mail-reply-to-news} when replying to mail. This is -useful for treating mailing lists like newsgroups. - -@end table - - -@node Posting Server -@section Posting Server - -When you press those magical @kbd{C-c C-c} keys to ship off your latest -(extremely intelligent, of course) article, where does it go? - -Thank you for asking. I hate you. - -It can be quite complicated. - -@vindex gnus-post-method -When posting news, Message usually invokes @code{message-send-news} -(@pxref{News Variables, , News Variables, message, Message Manual}). -Normally, Gnus will post using the same select method as you're -reading from (which might be convenient if you're reading lots of -groups from different private servers). However. If the server -you're reading from doesn't allow posting, just reading, you probably -want to use some other server to post your (extremely intelligent and -fabulously interesting) articles. You can then set the -@code{gnus-post-method} to some other method: - -@lisp -(setq gnus-post-method '(nnspool "")) -@end lisp - -Now, if you've done this, and then this server rejects your article, or -this server is down, what do you do then? To override this variable you -can use a non-zero prefix to the @kbd{C-c C-c} command to force using -the ``current'' server, to get back the default behavior, for posting. - -If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, -Gnus will prompt you for what method to use for posting. - -You can also set @code{gnus-post-method} to a list of select methods. -If that's the case, Gnus will always prompt you for what method to use -for posting. - -Finally, if you want to always post using the native select method, -you can set this variable to @code{native}. - -@vindex message-send-mail-function -When sending mail, Message invokes the function specified by the -variable @code{message-send-mail-function}. Gnus tries to set it to a -value suitable for your system. -@xref{Mail Variables, ,Mail Variables,message,Message manual}, for more -information. - -@node POP before SMTP -@section POP before SMTP -@cindex pop before smtp -@findex message-smtpmail-send-it -@findex mail-source-touch-pop - -Does your @acronym{ISP} require the @acronym{POP}-before-@acronym{SMTP} -authentication? It is whether you need to connect to the @acronym{POP} -mail server within a certain time before sending mails. If so, there is -a convenient way. To do that, put the following lines in your -@file{~/.gnus.el} file: - -@lisp -(setq message-send-mail-function 'message-smtpmail-send-it) -(add-hook 'message-send-mail-hook 'mail-source-touch-pop) -@end lisp - -@noindent -It means to let Gnus connect to the @acronym{POP} mail server in advance -whenever you send a mail. The @code{mail-source-touch-pop} function -does only a @acronym{POP} authentication according to the value of -@code{mail-sources} without fetching mails, just before sending a mail. -Note that you have to use @code{message-smtpmail-send-it} which runs -@code{message-send-mail-hook} rather than @code{smtpmail-send-it} and -set the value of @code{mail-sources} for a @acronym{POP} connection -correctly. @xref{Mail Sources}. - -If you have two or more @acronym{POP} mail servers set in -@code{mail-sources}, you may want to specify one of them to -@code{mail-source-primary-source} as the @acronym{POP} mail server to be -used for the @acronym{POP}-before-@acronym{SMTP} authentication. If it -is your primary @acronym{POP} mail server (i.e., you are fetching mails -mainly from that server), you can set it permanently as follows: - -@lisp -(setq mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret")) -@end lisp - -@noindent -Otherwise, bind it dynamically only when performing the -@acronym{POP}-before-@acronym{SMTP} authentication as follows: - -@lisp -(add-hook 'message-send-mail-hook - (lambda () - (let ((mail-source-primary-source - '(pop :server "pop3.mail.server" - :password "secret"))) - (mail-source-touch-pop)))) -@end lisp - -@node Mail and Post -@section Mail and Post - -Here's a list of variables relevant to both mailing and -posting: - -@table @code -@item gnus-mailing-list-groups -@findex gnus-mailing-list-groups -@cindex mailing lists - -If your news server offers groups that are really mailing lists -gatewayed to the @acronym{NNTP} server, you can read those groups without -problems, but you can't post/followup to them without some difficulty. -One solution is to add a @code{to-address} to the group parameters -(@pxref{Group Parameters}). An easier thing to do is set the -@code{gnus-mailing-list-groups} to a regexp that matches the groups that -really are mailing lists. Then, at least, followups to the mailing -lists will work most of the time. Posting to these groups (@kbd{a}) is -still a pain, though. - -@item gnus-user-agent -@vindex gnus-user-agent -@cindex User-Agent - -This variable controls which information should be exposed in the -User-Agent header. It can be a list of symbols or a string. Valid -symbols are @code{gnus} (show Gnus version) and @code{emacs} (show Emacs -version). In addition to the Emacs version, you can add @code{codename} -(show (S)XEmacs codename) or either @code{config} (show system -configuration) or @code{type} (show system type). If you set it to a -string, be sure to use a valid format, see RFC 2616. - -@end table - -You may want to do spell-checking on messages that you send out. Or, if -you don't want to spell-check by hand, you could add automatic -spell-checking via the @code{ispell} package: - -@cindex ispell -@findex ispell-message -@lisp -(add-hook 'message-send-hook 'ispell-message) -@end lisp - -If you want to change the @code{ispell} dictionary based on what group -you're in, you could say something like the following: - -@lisp -(add-hook 'gnus-select-group-hook - (lambda () - (cond - ((string-match - "^de\\." (gnus-group-real-name gnus-newsgroup-name)) - (ispell-change-dictionary "deutsch")) - (t - (ispell-change-dictionary "english"))))) -@end lisp - -Modify to suit your needs. - -@vindex gnus-message-highlight-citation -If @code{gnus-message-highlight-citation} is t, different levels of -citations are highlighted like in Gnus article buffers also in message -mode buffers. - -@node Archived Messages -@section Archived Messages -@cindex archived messages -@cindex sent messages - -Gnus provides a few different methods for storing the mail and news you -send. The default method is to use the @dfn{archive virtual server} to -store the messages. If you want to disable this completely, the -@code{gnus-message-archive-group} variable should be @code{nil}, which -is the default. - -For archiving interesting messages in a group you read, see the -@kbd{B c} (@code{gnus-summary-copy-article}) command (@pxref{Mail -Group Commands}). - -@vindex gnus-message-archive-method -@code{gnus-message-archive-method} says what virtual server Gnus is to -use to store sent messages. The default is @code{"archive"}, and when -actually being used it is expanded into: - -@lisp -(nnfolder "archive" - (nnfolder-directory "~/Mail/archive") - (nnfolder-active-file "~/Mail/archive/active") - (nnfolder-get-new-mail nil) - (nnfolder-inhibit-expiry t)) -@end lisp - -@quotation -@vindex gnus-update-message-archive-method -Note: a server like this is saved in the @file{~/.newsrc.eld} file first -so that it may be used as a real method of the server which is named -@code{"archive"} (that is, for the case where -@code{gnus-message-archive-method} is set to @code{"archive"}) ever -since. If it once has been saved, it will never be updated by default -even if you change the value of @code{gnus-message-archive-method} -afterward. Therefore, the server @code{"archive"} doesn't necessarily -mean the @code{nnfolder} server like this at all times. If you want the -saved method to reflect always the value of -@code{gnus-message-archive-method}, set the -@code{gnus-update-message-archive-method} variable to a non-@code{nil} -value. The default value of this variable is @code{nil}. -@end quotation - -You can, however, use any mail select method (@code{nnml}, -@code{nnmbox}, etc.). @code{nnfolder} is a quite likable select method -for doing this sort of thing, though. If you don't like the default -directory chosen, you could say something like: - -@lisp -(setq gnus-message-archive-method - '(nnfolder "archive" - (nnfolder-inhibit-expiry t) - (nnfolder-active-file "~/News/sent-mail/active") - (nnfolder-directory "~/News/sent-mail/"))) -@end lisp - -@vindex gnus-message-archive-group -@cindex Gcc -Gnus will insert @code{Gcc} headers in all outgoing messages that point -to one or more group(s) on that server. Which group to use is -determined by the @code{gnus-message-archive-group} variable. - -This variable can be used to do the following: - -@table @asis -@item a string -Messages will be saved in that group. - -Note that you can include a select method in the group name, then the -message will not be stored in the select method given by -@code{gnus-message-archive-method}, but in the select method specified -by the group name, instead. Suppose @code{gnus-message-archive-method} -has the default value shown above. Then setting -@code{gnus-message-archive-group} to @code{"foo"} means that outgoing -messages are stored in @samp{nnfolder+archive:foo}, but if you use the -value @code{"nnml:foo"}, then outgoing messages will be stored in -@samp{nnml:foo}. - -@item a list of strings -Messages will be saved in all those groups. - -@item an alist of regexps, functions and forms -When a key ``matches'', the result is used. - -@item @code{nil} -No message archiving will take place. This is the default. -@end table - -Let's illustrate: - -Just saving to a single group called @samp{MisK}: -@lisp -(setq gnus-message-archive-group "MisK") -@end lisp - -Saving to two groups, @samp{MisK} and @samp{safe}: -@lisp -(setq gnus-message-archive-group '("MisK" "safe")) -@end lisp - -Save to different groups based on what group you are in: -@lisp -(setq gnus-message-archive-group - '(("^alt" "sent-to-alt") - ("mail" "sent-to-mail") - (".*" "sent-to-misc"))) -@end lisp - -More complex stuff: -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - "misc-mail"))) -@end lisp - -How about storing all news messages in one file, but storing all mail -messages in one file per month: - -@lisp -(setq gnus-message-archive-group - '((if (message-news-p) - "misc-news" - (concat "mail." (format-time-string "%Y-%m"))))) -@end lisp - -@c (XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to -@c use a different value for @code{gnus-message-archive-group} there.) - -Now, when you send a message off, it will be stored in the appropriate -group. (If you want to disable storing for just one particular message, -you can just remove the @code{Gcc} header that has been inserted.) The -archive group will appear in the group buffer the next time you start -Gnus, or the next time you press @kbd{F} in the group buffer. You can -enter it and read the articles in it just like you'd read any other -group. If the group gets really big and annoying, you can simply rename -if (using @kbd{G r} in the group buffer) to something -nice---@samp{misc-mail-september-1995}, or whatever. New messages will -continue to be stored in the old (now empty) group. - -That's the default method of archiving sent messages. Gnus offers a -different way for the people who don't like the default method. In that -case you should set @code{gnus-message-archive-group} to @code{nil}; -this will disable archiving. - -@table @code -@item gnus-outgoing-message-group -@vindex gnus-outgoing-message-group -All outgoing messages will be put in this group. If you want to store -all your outgoing mail and articles in the group @samp{nnml:archive}, -you set this variable to that value. This variable can also be a list of -group names. - -If you want to have greater control over what group to put each -message in, you can set this variable to a function that checks the -current newsgroup name and then returns a suitable group name (or list -of names). - -This variable can be used instead of @code{gnus-message-archive-group}, -but the latter is the preferred method. - -@item gnus-gcc-mark-as-read -@vindex gnus-gcc-mark-as-read -If non-@code{nil}, automatically mark @code{Gcc} articles as read. - -@item gnus-gcc-externalize-attachments -@vindex gnus-gcc-externalize-attachments -If @code{nil}, attach files as normal parts in Gcc copies; if a regexp -and matches the Gcc group name, attach files as external parts; if it is -@code{all}, attach local files as external parts; if it is other -non-@code{nil}, the behavior is the same as @code{all}, but it may be -changed in the future. - -@end table - - -@node Posting Styles -@section Posting Styles -@cindex posting styles -@cindex styles - -All them variables, they make my head swim. - -So what if you want a different @code{Organization} and signature based -on what groups you post to? And you post both from your home machine -and your work machine, and you want different @code{From} lines, and so -on? - -@vindex gnus-posting-styles -One way to do stuff like that is to write clever hooks that change the -variables you need to have changed. That's a bit boring, so somebody -came up with the bright idea of letting the user specify these things in -a handy alist. Here's an example of a @code{gnus-posting-styles} -variable: - -@lisp -((".*" - (signature "Peace and happiness") - (organization "What me?")) - ("^comp" - (signature "Death to everybody")) - ("comp.emacs.i-love-it" - (organization "Emacs is it"))) -@end lisp - -As you might surmise from this example, this alist consists of several -@dfn{styles}. Each style will be applicable if the first element -``matches'', in some form or other. The entire alist will be iterated -over, from the beginning towards the end, and each match will be -applied, which means that attributes in later styles that match override -the same attributes in earlier matching styles. So -@samp{comp.programming.literate} will have the @samp{Death to everybody} -signature and the @samp{What me?} @code{Organization} header. - -The first element in each style is called the @code{match}. If it's a -string, then Gnus will try to regexp match it against the group name. -If it is the form @code{(header @var{match} @var{regexp})}, then Gnus -will look in the original article for a header whose name is -@var{match} and compare that @var{regexp}. @var{match} and -@var{regexp} are strings. (The original article is the one you are -replying or following up to. If you are not composing a reply or a -followup, then there is nothing to match against.) If the -@code{match} is a function symbol, that function will be called with -no arguments. If it's a variable symbol, then the variable will be -referenced. If it's a list, then that list will be @code{eval}ed. In -any case, if this returns a non-@code{nil} value, then the style is -said to @dfn{match}. - -Each style may contain an arbitrary amount of @dfn{attributes}. Each -attribute consists of a @code{(@var{name} @var{value})} pair. In -addition, you can also use the @code{(@var{name} :file @var{value})} -form or the @code{(@var{name} :value @var{value})} form. Where -@code{:file} signifies @var{value} represents a file name and its -contents should be used as the attribute value, @code{:value} signifies -@var{value} does not represent a file name explicitly. The attribute -name can be one of: - -@itemize @bullet -@item @code{signature} -@item @code{signature-file} -@item @code{x-face-file} -@item @code{address}, overriding @code{user-mail-address} -@item @code{name}, overriding @code{(user-full-name)} -@item @code{body} -@end itemize - -Note that the @code{signature-file} attribute honors the variable -@code{message-signature-directory}. - -The attribute name can also be a string or a symbol. In that case, -this will be used as a header name, and the value will be inserted in -the headers of the article; if the value is @code{nil}, the header -name will be removed. If the attribute name is @code{eval}, the form -is evaluated, and the result is thrown away. - -The attribute value can be a string (used verbatim), a function with -zero arguments (the return value will be used), a variable (its value -will be used) or a list (it will be @code{eval}ed and the return value -will be used). The functions and sexps are called/@code{eval}ed in the -message buffer that is being set up. The headers of the current article -are available through the @code{message-reply-headers} variable, which -is a vector of the following headers: number subject from date id -references chars lines xref extra. - -@vindex message-reply-headers - -If you wish to check whether the message you are about to compose is -meant to be a news article or a mail message, you can check the values -of the @code{message-news-p} and @code{message-mail-p} functions. - -@findex message-mail-p -@findex message-news-p - -So here's a new example: - -@lisp -(setq gnus-posting-styles - '((".*" - (signature-file "~/.signature") - (name "User Name") - (x-face-file "~/.xface") - (x-url (getenv "WWW_HOME")) - (organization "People's Front Against MWM")) - ("^rec.humor" - (signature my-funny-signature-randomizer)) - ((equal (system-name) "gnarly") ;; @r{A form} - (signature my-quote-randomizer)) - (message-news-p ;; @r{A function symbol} - (signature my-news-signature)) - (window-system ;; @r{A value symbol} - ("X-Window-System" (format "%s" window-system))) - ;; @r{If I'm replying to Larsi, set the Organization header.} - ((header "from" "larsi.*org") - (Organization "Somewhere, Inc.")) - ((posting-from-work-p) ;; @r{A user defined function} - (signature-file "~/.work-signature") - (address "user@@bar.foo") - (body "You are fired.\n\nSincerely, your boss.") - (organization "Important Work, Inc")) - ("nnml:.*" - (From (save-excursion - (set-buffer gnus-article-buffer) - (message-fetch-field "to")))) - ("^nn.+:" - (signature-file "~/.mail-signature")))) -@end lisp - -The @samp{nnml:.*} rule means that you use the @code{To} address as the -@code{From} address in all your outgoing replies, which might be handy -if you fill many roles. -You may also use @code{message-alternative-emails} instead. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@node Drafts -@section Drafts -@cindex drafts - -If you are writing a message (mail or news) and suddenly remember that -you have a steak in the oven (or some pesto in the food processor, you -craaazy vegetarians), you'll probably wish there was a method to save -the message you are writing so that you can continue editing it some -other day, and send it when you feel its finished. - -Well, don't worry about it. Whenever you start composing a message of -some sort using the Gnus mail and post commands, the buffer you get will -automatically associate to an article in a special @dfn{draft} group. -If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the -article will be saved there. (Auto-save files also go to the draft -group.) - -@cindex nndraft -@vindex nndraft-directory -The draft group is a special group (which is implemented as an -@code{nndraft} group, if you absolutely have to know) called -@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where -@code{nndraft} is to store its files. What makes this group special is -that you can't tick any articles in it or mark any articles as -read---all articles in the group are permanently unread. - -If the group doesn't exist, it will be created and you'll be subscribed -to it. The only way to make it disappear from the Group buffer is to -unsubscribe it. The special properties of the draft group comes from -a group property (@pxref{Group Parameters}), and if lost the group -behaves like any other group. This means the commands below will not -be available. To restore the special properties of the group, the -simplest way is to kill the group, using @kbd{C-k}, and restart -Gnus. The group is automatically created again with the -correct parameters. The content of the group is not lost. - -@c @findex gnus-dissociate-buffer-from-draft -@c @kindex C-c M-d (Mail) -@c @kindex C-c M-d (Post) -@c @findex gnus-associate-buffer-with-draft -@c @kindex C-c C-d (Mail) -@c @kindex C-c C-d (Post) -@c If you're writing some super-secret message that you later want to -@c encode with PGP before sending, you may wish to turn the auto-saving -@c (and association with the draft group) off. You never know who might be -@c interested in reading all your extremely valuable and terribly horrible -@c and interesting secrets. The @kbd{C-c M-d} -@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. -@c If you change your mind and want to turn the auto-saving back on again, -@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. -@c -@c @vindex gnus-use-draft -@c To leave association with the draft group off by default, set -@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. - -@findex gnus-draft-edit-message -@kindex D e (Draft) -When you want to continue editing the article, you simply enter the -draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do -that. You will be placed in a buffer where you left off. - -Rejected articles will also be put in this draft group (@pxref{Rejected -Articles}). - -@findex gnus-draft-send-all-messages -@kindex D s (Draft) -@findex gnus-draft-send-message -@kindex D S (Draft) -If you have lots of rejected messages you want to post (or mail) without -doing further editing, you can use the @kbd{D s} command -(@code{gnus-draft-send-message}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} -command (@code{gnus-draft-send-all-messages}) will ship off all messages -in the buffer. - -@findex gnus-draft-toggle-sending -@kindex D t (Draft) -If you have some messages that you wish not to send, you can use the -@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message -as unsendable. This is a toggling command. - - -@node Rejected Articles -@section Rejected Articles -@cindex rejected articles - -Sometimes a news server will reject an article. Perhaps the server -doesn't like your face. Perhaps it just feels miserable. Perhaps -@emph{there be demons}. Perhaps you have included too much cited text. -Perhaps the disk is full. Perhaps the server is down. - -These situations are, of course, totally beyond the control of Gnus. -(Gnus, of course, loves the way you look, always feels great, has angels -fluttering around inside of it, doesn't care about how much cited text -you include, never runs full and never goes down.) So Gnus saves these -articles until some later time when the server feels better. - -The rejected articles will automatically be put in a special draft group -(@pxref{Drafts}). When the server comes back up again, you'd then -typically enter that group and send all the articles off. - -@node Signing and encrypting -@section Signing and encrypting -@cindex using gpg -@cindex using s/mime -@cindex using smime - -Gnus can digitally sign and encrypt your messages, using vanilla -@acronym{PGP} format or @acronym{PGP/MIME} or @acronym{S/MIME}. For -decoding such messages, see the @code{mm-verify-option} and -@code{mm-decrypt-option} options (@pxref{Security}). - -@vindex gnus-message-replysign -@vindex gnus-message-replyencrypt -@vindex gnus-message-replysignencrypted -Often, you would like to sign replies to people who send you signed -messages. Even more often, you might want to encrypt messages which -are in reply to encrypted messages. Gnus offers -@code{gnus-message-replysign} to enable the former, and -@code{gnus-message-replyencrypt} for the latter. In addition, setting -@code{gnus-message-replysignencrypted} (on by default) will sign -automatically encrypted messages. - -Instructing @acronym{MML} to perform security operations on a -@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for -signing and the @kbd{C-c C-m c} key map for encryption, as follows. - -@table @kbd - -@item C-c C-m s s -@kindex C-c C-m s s (Message) -@findex mml-secure-message-sign-smime - -Digitally sign current message using @acronym{S/MIME}. - -@item C-c C-m s o -@kindex C-c C-m s o (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP}. - -@item C-c C-m s p -@kindex C-c C-m s p (Message) -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP/MIME}. - -@item C-c C-m c s -@kindex C-c C-m c s (Message) -@findex mml-secure-message-encrypt-smime - -Digitally encrypt current message using @acronym{S/MIME}. - -@item C-c C-m c o -@kindex C-c C-m c o (Message) -@findex mml-secure-message-encrypt-pgp - -Digitally encrypt current message using @acronym{PGP}. - -@item C-c C-m c p -@kindex C-c C-m c p (Message) -@findex mml-secure-message-encrypt-pgpmime - -Digitally encrypt current message using @acronym{PGP/MIME}. - -@item C-c C-m C-n -@kindex C-c C-m C-n (Message) -@findex mml-unsecure-message -Remove security related @acronym{MML} tags from message. - -@end table - -@xref{Security, ,Security, message, Message Manual}, for more information. - -@node Select Methods -@chapter Select Methods -@cindex foreign groups -@cindex select methods - -A @dfn{foreign group} is a group not read by the usual (or -default) means. It could be, for instance, a group from a different -@acronym{NNTP} server, it could be a virtual group, or it could be your own -personal mail group. - -A foreign group (or any group, really) is specified by a @dfn{name} and -a @dfn{select method}. To take the latter first, a select method is a -list where the first element says what back end to use (e.g. @code{nntp}, -@code{nnspool}, @code{nnml}) and the second element is the @dfn{server -name}. There may be additional elements in the select method, where the -value may have special meaning for the back end in question. - -One could say that a select method defines a @dfn{virtual server}---so -we do just that (@pxref{Server Buffer}). - -The @dfn{name} of the group is the name the back end will recognize the -group as. - -For instance, the group @samp{soc.motss} on the @acronym{NNTP} server -@samp{some.where.edu} will have the name @samp{soc.motss} and select -method @code{(nntp "some.where.edu")}. Gnus will call this group -@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} -back end just knows this group as @samp{soc.motss}. - -The different methods all have their peculiarities, of course. - -@menu -* Server Buffer:: Making and editing virtual servers. -* Getting News:: Reading USENET news with Gnus. -* Getting Mail:: Reading your personal mail with Gnus. -* Browsing the Web:: Getting messages from a plethora of Web sources. -* IMAP:: Using Gnus as a @acronym{IMAP} client. -* Other Sources:: Reading directories, files, SOUP packets. -* Combined Groups:: Combining groups into one group. -* Email Based Diary:: Using mails to manage diary events in Gnus. -* Gnus Unplugged:: Reading news and mail offline. -@end menu - - -@node Server Buffer -@section Server Buffer - -Traditionally, a @dfn{server} is a machine or a piece of software that -one connects to, and then requests information from. Gnus does not -connect directly to any real servers, but does all transactions through -one back end or other. But that's just putting one layer more between -the actual media and Gnus, so we might just as well say that each -back end represents a virtual server. - -For instance, the @code{nntp} back end may be used to connect to several -different actual @acronym{NNTP} servers, or, perhaps, to many different ports -on the same actual @acronym{NNTP} server. You tell Gnus which back end to -use, and what parameters to set by specifying a @dfn{select method}. - -These select method specifications can sometimes become quite -complicated---say, for instance, that you want to read from the -@acronym{NNTP} server @samp{news.funet.fi} on port number 13, which -hangs if queried for @acronym{NOV} headers and has a buggy select. Ahem. -Anyway, if you had to specify that for each group that used this -server, that would be too much work, so Gnus offers a way of naming -select methods, which is what you do in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - -@menu -* Server Buffer Format:: You can customize the look of this buffer. -* Server Commands:: Commands to manipulate servers. -* Example Methods:: Examples server specifications. -* Creating a Virtual Server:: An example session. -* Server Variables:: Which variables to set. -* Servers and Methods:: You can use server names as select methods. -* Unavailable Servers:: Some servers you try to contact may be down. -@end menu - -@vindex gnus-server-mode-hook -@code{gnus-server-mode-hook} is run when creating the server buffer. - - -@node Server Buffer Format -@subsection Server Buffer Format -@cindex server buffer format - -@vindex gnus-server-line-format -You can change the look of the server buffer lines by changing the -@code{gnus-server-line-format} variable. This is a @code{format}-like -variable, with some simple extensions: - -@table @samp - -@item h -How the news is fetched---the back end name. - -@item n -The name of this server. - -@item w -Where the news is to be fetched from---the address. - -@item s -The opened/closed/denied status of the server. - -@item a -Whether this server is agentized. -@end table - -@vindex gnus-server-mode-line-format -The mode line can also be customized by using the -@code{gnus-server-mode-line-format} variable (@pxref{Mode Line -Formatting}). The following specs are understood: - -@table @samp -@item S -Server name. - -@item M -Server method. -@end table - -Also @pxref{Formatting Variables}. - - -@node Server Commands -@subsection Server Commands -@cindex server commands - -@table @kbd - -@item v -@kindex v (Server) -@cindex keys, reserved for users (Server) -The key @kbd{v} is reserved for users. You can bind it to some -command or better use it as a prefix key. - -@item a -@kindex a (Server) -@findex gnus-server-add-server -Add a new server (@code{gnus-server-add-server}). - -@item e -@kindex e (Server) -@findex gnus-server-edit-server -Edit a server (@code{gnus-server-edit-server}). - -@item SPACE -@kindex SPACE (Server) -@findex gnus-server-read-server -Browse the current server (@code{gnus-server-read-server}). - -@item q -@kindex q (Server) -@findex gnus-server-exit -Return to the group buffer (@code{gnus-server-exit}). - -@item k -@kindex k (Server) -@findex gnus-server-kill-server -Kill the current server (@code{gnus-server-kill-server}). - -@item y -@kindex y (Server) -@findex gnus-server-yank-server -Yank the previously killed server (@code{gnus-server-yank-server}). - -@item c -@kindex c (Server) -@findex gnus-server-copy-server -Copy the current server (@code{gnus-server-copy-server}). - -@item l -@kindex l (Server) -@findex gnus-server-list-servers -List all servers (@code{gnus-server-list-servers}). - -@item s -@kindex s (Server) -@findex gnus-server-scan-server -Request that the server scan its sources for new articles -(@code{gnus-server-scan-server}). This is mainly sensible with mail -servers. - -@item g -@kindex g (Server) -@findex gnus-server-regenerate-server -Request that the server regenerate all its data structures -(@code{gnus-server-regenerate-server}). This can be useful if you have -a mail back end that has gotten out of sync. - -@item z -@kindex z (Server) -@findex gnus-server-compact-server - -Compact all groups in the server under point -(@code{gnus-server-compact-server}). Currently implemented only in -nnml (@pxref{Mail Spool}). This removes gaps between article numbers, -hence getting a correct total article count. - -@end table - - -@node Example Methods -@subsection Example Methods - -Most select methods are pretty simple and self-explanatory: - -@lisp -(nntp "news.funet.fi") -@end lisp - -Reading directly from the spool is even simpler: - -@lisp -(nnspool "") -@end lisp - -As you can see, the first element in a select method is the name of the -back end, and the second is the @dfn{address}, or @dfn{name}, if you -will. - -After these two elements, there may be an arbitrary number of -@code{(@var{variable} @var{form})} pairs. - -To go back to the first example---imagine that you want to read from -port 15 on that machine. This is what the select method should -look like then: - -@lisp -(nntp "news.funet.fi" (nntp-port-number 15)) -@end lisp - -You should read the documentation to each back end to find out what -variables are relevant, but here's an @code{nnmh} example: - -@code{nnmh} is a mail back end that reads a spool-like structure. Say -you have two structures that you wish to access: One is your private -mail spool, and the other is a public one. Here's the possible spec for -your private mail: - -@lisp -(nnmh "private" (nnmh-directory "~/private/mail/")) -@end lisp - -(This server is then called @samp{private}, but you may have guessed -that.) - -Here's the method for a public spool: - -@lisp -(nnmh "public" - (nnmh-directory "/usr/information/spool/") - (nnmh-get-new-mail nil)) -@end lisp - -@cindex proxy -@cindex firewall - -If you are behind a firewall and only have access to the @acronym{NNTP} -server from the firewall machine, you can instruct Gnus to @code{rlogin} -on the firewall machine and connect with -@uref{http://netcat.sourceforge.net/, netcat} from there to the -@acronym{NNTP} server. -Doing this can be rather fiddly, but your virtual server definition -should probably look something like this: - -@lisp -(nntp "firewall" - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat) - (nntp-via-address "the.firewall.machine") - (nntp-address "the.real.nntp.host")) -@end lisp - -If you want to use the wonderful @code{ssh} program to provide a -compressed connection over the modem line, you could add the following -configuration to the example above: - -@lisp - (nntp-via-rlogin-command "ssh") -@end lisp - -See also @code{nntp-via-rlogin-command-switches}. Here's an example for -an indirect connection: - -@lisp -(setq gnus-select-method - '(nntp "indirect" - (nntp-address "news.server.example") - (nntp-via-user-name "intermediate_user_name") - (nntp-via-address "intermediate.host.example") - (nntp-via-rlogin-command "ssh") - (nntp-via-rlogin-command-switches ("-C")) - (nntp-open-connection-function nntp-open-via-rlogin-and-netcat))) -@end lisp - -This means that you have to have set up @code{ssh-agent} correctly to -provide automatic authorization, of course. - -If you're behind a firewall, but have direct access to the outside world -through a wrapper command like "runsocks", you could open a socksified -netcat connection to the news server as follows: - -@lisp -(nntp "outside" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - - -@node Creating a Virtual Server -@subsection Creating a Virtual Server - -If you're saving lots of articles in the cache by using persistent -articles, you may want to create a virtual server to read the cache. - -First you need to add a new server. The @kbd{a} command does that. It -would probably be best to use @code{nnml} to read the cache. You -could also use @code{nnspool} or @code{nnmh}, though. - -Type @kbd{a nnml RET cache RET}. - -You should now have a brand new @code{nnml} virtual server called -@samp{cache}. You now need to edit it to have the right definitions. -Type @kbd{e} to edit the server. You'll be entered into a buffer that -will contain the following: - -@lisp -(nnml "cache") -@end lisp - -Change that to: - -@lisp -(nnml "cache" - (nnml-directory "~/News/cache/") - (nnml-active-file "~/News/cache/active")) -@end lisp - -Type @kbd{C-c C-c} to return to the server buffer. If you now press -@kbd{RET} over this virtual server, you should be entered into a browse -buffer, and you should be able to enter any of the groups displayed. - - -@node Server Variables -@subsection Server Variables -@cindex server variables -@cindex server parameters - -One sticky point when defining variables (both on back ends and in Emacs -in general) is that some variables are typically initialized from other -variables when the definition of the variables is being loaded. If you -change the ``base'' variable after the variables have been loaded, you -won't change the ``derived'' variables. - -This typically affects directory and file variables. For instance, -@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} -directory variables are initialized from that variable, so -@code{nnml-active-file} will be @file{~/Mail/active}. If you define a -new virtual @code{nnml} server, it will @emph{not} suffice to set just -@code{nnml-directory}---you have to explicitly set all the file -variables to be what you want them to be. For a complete list of -variables for each back end, see each back end's section later in this -manual, but here's an example @code{nnml} definition: - -@lisp -(nnml "public" - (nnml-directory "~/my-mail/") - (nnml-active-file "~/my-mail/active") - (nnml-newsgroups-file "~/my-mail/newsgroups")) -@end lisp - -Server variables are often called @dfn{server parameters}. - -@node Servers and Methods -@subsection Servers and Methods - -Wherever you would normally use a select method -(e.g. @code{gnus-secondary-select-method}, in the group select method, -when browsing a foreign server) you can use a virtual server name -instead. This could potentially save lots of typing. And it's nice all -over. - - -@node Unavailable Servers -@subsection Unavailable Servers - -If a server seems to be unreachable, Gnus will mark that server as -@code{denied}. That means that any subsequent attempt to make contact -with that server will just be ignored. ``It can't be opened,'' Gnus -will tell you, without making the least effort to see whether that is -actually the case or not. - -That might seem quite naughty, but it does make sense most of the time. -Let's say you have 10 groups subscribed to on server -@samp{nephelococcygia.com}. This server is located somewhere quite far -away from you and the machine is quite slow, so it takes 1 minute just -to find out that it refuses connection to you today. If Gnus were to -attempt to do that 10 times, you'd be quite annoyed, so Gnus won't -attempt to do that. Once it has gotten a single ``connection refused'', -it will regard that server as ``down''. - -So, what happens if the machine was only feeling unwell temporarily? -How do you test to see whether the machine has come up again? - -You jump to the server buffer (@pxref{Server Buffer}) and poke it -with the following commands: - -@table @kbd - -@item O -@kindex O (Server) -@findex gnus-server-open-server -Try to establish connection to the server on the current line -(@code{gnus-server-open-server}). - -@item C -@kindex C (Server) -@findex gnus-server-close-server -Close the connection (if any) to the server -(@code{gnus-server-close-server}). - -@item D -@kindex D (Server) -@findex gnus-server-deny-server -Mark the current server as unreachable -(@code{gnus-server-deny-server}). - -@item M-o -@kindex M-o (Server) -@findex gnus-server-open-all-servers -Open the connections to all servers in the buffer -(@code{gnus-server-open-all-servers}). - -@item M-c -@kindex M-c (Server) -@findex gnus-server-close-all-servers -Close the connections to all servers in the buffer -(@code{gnus-server-close-all-servers}). - -@item R -@kindex R (Server) -@findex gnus-server-remove-denials -Remove all marks to whether Gnus was denied connection from any servers -(@code{gnus-server-remove-denials}). - -@item L -@kindex L (Server) -@findex gnus-server-offline-server -Set server status to offline (@code{gnus-server-offline-server}). - -@end table - - -@node Getting News -@section Getting News -@cindex reading news -@cindex news back ends - -A newsreader is normally used for reading news. Gnus currently provides -only two methods of getting news---it can read from an @acronym{NNTP} server, -or it can read from a local spool. - -@menu -* NNTP:: Reading news from an @acronym{NNTP} server. -* News Spool:: Reading news from the local spool. -@end menu - - -@node NNTP -@subsection NNTP -@cindex nntp - -Subscribing to a foreign group from an @acronym{NNTP} server is rather easy. -You just specify @code{nntp} as method and the address of the @acronym{NNTP} -server as the, uhm, address. - -If the @acronym{NNTP} server is located at a non-standard port, setting the -third element of the select method to this port number should allow you -to connect to the right port. You'll have to edit the group info for -that (@pxref{Foreign Groups}). - -The name of the foreign group can be the same as a native group. In -fact, you can subscribe to the same group from as many different servers -you feel like. There will be no name collisions. - -The following variables can be used to create a virtual @code{nntp} -server: - -@table @code - -@item nntp-server-opened-hook -@vindex nntp-server-opened-hook -@cindex @sc{mode reader} -@cindex authinfo -@cindex authentication -@cindex nntp authentication -@findex nntp-send-authinfo -@findex nntp-send-mode-reader -is run after a connection has been made. It can be used to send -commands to the @acronym{NNTP} server after it has been contacted. By -default it sends the command @code{MODE READER} to the server with the -@code{nntp-send-mode-reader} function. This function should always be -present in this hook. - -@item nntp-authinfo-function -@vindex nntp-authinfo-function -@findex nntp-send-authinfo -@vindex nntp-authinfo-file -This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} -server. The default function is @code{nntp-send-authinfo}, which looks -through your @file{~/.authinfo} (or whatever you've set the -@code{nntp-authinfo-file} variable to) for applicable entries. If none -are found, it will prompt you for a login name and a password. The -format of the @file{~/.authinfo} file is (almost) the same as the -@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} -manual page, but here are the salient facts: - -@enumerate -@item -The file contains one or more line, each of which define one server. - -@item -Each line may contain an arbitrary number of token/value pairs. - -The valid tokens include @samp{machine}, @samp{login}, @samp{password}, -@samp{default}. In addition Gnus introduces two new tokens, not present -in the original @file{.netrc}/@code{ftp} syntax, namely @samp{port} and -@samp{force}. (This is the only way the @file{.authinfo} file format -deviates from the @file{.netrc} file format.) @samp{port} is used to -indicate what port on the server the credentials apply to and -@samp{force} is explained below. - -@end enumerate - -Here's an example file: - -@example -machine news.uio.no login larsi password geheimnis -machine nntp.ifi.uio.no login larsi force yes -@end example - -The token/value pairs may appear in any order; @samp{machine} doesn't -have to be first, for instance. - -In this example, both login name and password have been supplied for the -former server, while the latter has only the login name listed, and the -user will be prompted for the password. The latter also has the -@samp{force} tag, which means that the authinfo will be sent to the -@var{nntp} server upon connection; the default (i.e., when there is not -@samp{force} tag) is to not send authinfo to the @var{nntp} server -until the @var{nntp} server asks for it. - -You can also add @samp{default} lines that will apply to all servers -that don't have matching @samp{machine} lines. - -@example -default force yes -@end example - -This will force sending @samp{AUTHINFO} commands to all servers not -previously mentioned. - -Remember to not leave the @file{~/.authinfo} file world-readable. - -@item nntp-server-action-alist -@vindex nntp-server-action-alist -This is a list of regexps to match on server types and actions to be -taken when matches are made. For instance, if you want Gnus to beep -every time you connect to innd, you could say something like: - -@lisp -(setq nntp-server-action-alist - '(("innd" (ding)))) -@end lisp - -You probably don't want to do that, though. - -The default value is - -@lisp -'(("nntpd 1\\.5\\.11t" - (remove-hook 'nntp-server-opened-hook - 'nntp-send-mode-reader))) -@end lisp - -This ensures that Gnus doesn't send the @code{MODE READER} command to -nntpd 1.5.11t, since that command chokes that server, I've been told. - -@item nntp-maximum-request -@vindex nntp-maximum-request -If the @acronym{NNTP} server doesn't support @acronym{NOV} headers, this back end -will collect headers by sending a series of @code{head} commands. To -speed things up, the back end sends lots of these commands without -waiting for reply, and then reads all the replies. This is controlled -by the @code{nntp-maximum-request} variable, and is 400 by default. If -your network is buggy, you should set this to 1. - -@item nntp-connection-timeout -@vindex nntp-connection-timeout -If you have lots of foreign @code{nntp} groups that you connect to -regularly, you're sure to have problems with @acronym{NNTP} servers not -responding properly, or being too loaded to reply within reasonable -time. This is can lead to awkward problems, which can be helped -somewhat by setting @code{nntp-connection-timeout}. This is an integer -that says how many seconds the @code{nntp} back end should wait for a -connection before giving up. If it is @code{nil}, which is the default, -no timeouts are done. - -@item nntp-nov-is-evil -@vindex nntp-nov-is-evil -If the @acronym{NNTP} server does not support @acronym{NOV}, you could set this -variable to @code{t}, but @code{nntp} usually checks automatically whether @acronym{NOV} -can be used. - -@item nntp-xover-commands -@vindex nntp-xover-commands -@cindex @acronym{NOV} -@cindex XOVER -List of strings used as commands to fetch @acronym{NOV} lines from a -server. The default value of this variable is @code{("XOVER" -"XOVERVIEW")}. - -@item nntp-nov-gap -@vindex nntp-nov-gap -@code{nntp} normally sends just one big request for @acronym{NOV} lines to -the server. The server responds with one huge list of lines. However, -if you have read articles 2-5000 in the group, and only want to read -article 1 and 5001, that means that @code{nntp} will fetch 4999 @acronym{NOV} -lines that you will not need. This variable says how -big a gap between two consecutive articles is allowed to be before the -@code{XOVER} request is split into several request. Note that if your -network is fast, setting this variable to a really small number means -that fetching will probably be slower. If this variable is @code{nil}, -@code{nntp} will never split requests. The default is 5. - -@item nntp-xref-number-is-evil -@vindex nntp-xref-number-is-evil -When Gnus refers to an article having the @code{Message-ID} that a user -specifies or having the @code{Message-ID} of the parent article of the -current one (@pxref{Finding the Parent}), Gnus sends a @code{HEAD} -command to the @acronym{NNTP} server to know where it is, and the server -returns the data containing the pairs of a group and an article number -in the @code{Xref} header. Gnus normally uses the article number to -refer to the article if the data shows that that article is in the -current group, while it uses the @code{Message-ID} otherwise. However, -some news servers, e.g., ones running Diablo, run multiple engines -having the same articles but article numbers are not kept synchronized -between them. In that case, the article number that appears in the -@code{Xref} header varies by which engine is chosen, so you cannot refer -to the parent article that is in the current group, for instance. If -you connect to such a server, set this variable to a non-@code{nil} -value, and Gnus never uses article numbers. For example: - -@lisp -(setq gnus-select-method - '(nntp "newszilla" - (nntp-address "newszilla.example.com") - (nntp-xref-number-is-evil t) - @dots{})) -@end lisp - -The default value of this server variable is @code{nil}. - -@item nntp-prepare-server-hook -@vindex nntp-prepare-server-hook -A hook run before attempting to connect to an @acronym{NNTP} server. - -@item nntp-record-commands -@vindex nntp-record-commands -If non-@code{nil}, @code{nntp} will log all commands it sends to the -@acronym{NNTP} server (along with a timestamp) in the @samp{*nntp-log*} -buffer. This is useful if you are debugging a Gnus/@acronym{NNTP} connection -that doesn't seem to work. - -@item nntp-open-connection-function -@vindex nntp-open-connection-function -It is possible to customize how the connection to the nntp server will -be opened. If you specify an @code{nntp-open-connection-function} -parameter, Gnus will use that function to establish the connection. -Seven pre-made functions are supplied. These functions can be grouped -in two categories: direct connection functions (four pre-made), and -indirect ones (three pre-made). - -@item nntp-never-echoes-commands -@vindex nntp-never-echoes-commands -Non-@code{nil} means the nntp server never echoes commands. It is -reported that some nntps server doesn't echo commands. So, you may want -to set this to non-@code{nil} in the method for such a server setting -@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for -example. The default value is @code{nil}. Note that the -@code{nntp-open-connection-functions-never-echo-commands} variable -overrides the @code{nil} value of this variable. - -@item nntp-open-connection-functions-never-echo-commands -@vindex nntp-open-connection-functions-never-echo-commands -List of functions that never echo commands. Add or set a function which -you set to @code{nntp-open-connection-function} to this list if it does -not echo commands. Note that a non-@code{nil} value of the -@code{nntp-never-echoes-commands} variable overrides this variable. The -default value is @code{(nntp-open-network-stream)}. - -@item nntp-prepare-post-hook -@vindex nntp-prepare-post-hook -A hook run just before posting an article. If there is no -@code{Message-ID} header in the article and the news server provides the -recommended ID, it will be added to the article before running this -hook. It is useful to make @code{Cancel-Lock} headers even if you -inhibit Gnus to add a @code{Message-ID} header, you could say: - -@lisp -(add-hook 'nntp-prepare-post-hook 'canlock-insert-header) -@end lisp - -Note that not all servers support the recommended ID. This works for -INN versions 2.3.0 and later, for instance. - -@end table - -@menu -* Direct Functions:: Connecting directly to the server. -* Indirect Functions:: Connecting indirectly to the server. -* Common Variables:: Understood by several connection functions. -* NNTP marks:: Storing marks for @acronym{NNTP} servers. -@end menu - - -@node Direct Functions -@subsubsection Direct Functions -@cindex direct connection functions - -These functions are called direct because they open a direct connection -between your machine and the @acronym{NNTP} server. The behavior of these -functions is also affected by commonly understood variables -(@pxref{Common Variables}). - -@table @code -@findex nntp-open-network-stream -@item nntp-open-network-stream -This is the default, and simply connects to some port or other on the -remote system. - -@findex nntp-open-tls-stream -@item nntp-open-tls-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.gnu.org/software/gnutls/, GNUTLS} -installed. You then define a server as follows: - -@lisp -;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{gnutls-cli -p} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-tls-stream) - (nntp-port-number ) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-ssl-stream -@item nntp-open-ssl-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{http://www.openssl.org, OpenSSL} or -@uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} installed. You -then define a server as follows: - -@lisp -;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{openssl s_client -port} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-ssl-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp - -@findex nntp-open-netcat-stream -@item nntp-open-netcat-stream -Opens a connection to an @acronym{NNTP} server using the @code{netcat} -program. You might wonder why this function exists, since we have -the default @code{nntp-open-network-stream} which would do the job. (One -of) the reason(s) is that if you are behind a firewall but have direct -connections to the outside world thanks to a command wrapper like -@code{runsocks}, you can use it like this: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-netcat-stream) - (nntp-address "the.news.server")) -@end lisp - -With the default method, you would need to wrap your whole Emacs -session, which is not a good idea. - -@findex nntp-open-telnet-stream -@item nntp-open-telnet-stream -Like @code{nntp-open-netcat-stream}, but uses @code{telnet} rather than -@code{netcat}. @code{telnet} is a bit less robust because of things -like line-end-conversion, but sometimes netcat is simply -not available. The previous example would turn into: - -@lisp -(nntp "socksified" - (nntp-pre-command "runsocks") - (nntp-open-connection-function nntp-open-telnet-stream) - (nntp-address "the.news.server") - (nntp-end-of-line "\n")) -@end lisp -@end table - - -@node Indirect Functions -@subsubsection Indirect Functions -@cindex indirect connection functions - -These functions are called indirect because they connect to an -intermediate host before actually connecting to the @acronym{NNTP} server. -All of these functions and related variables are also said to belong to -the ``via'' family of connection: they're all prefixed with ``via'' to make -things cleaner. The behavior of these functions is also affected by -commonly understood variables (@pxref{Common Variables}). - -@table @code -@item nntp-open-via-rlogin-and-netcat -@findex nntp-open-via-rlogin-and-netcat -Does an @samp{rlogin} on a remote system, and then uses @code{netcat} to connect -to the real @acronym{NNTP} server from there. This is useful for instance if -you need to connect to a firewall machine first. - -@code{nntp-open-via-rlogin-and-netcat}-specific variables: - -@table @code -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. The default is @code{nil}. If you use -@samp{ssh} for @code{nntp-via-rlogin-command}, you may set this to -@samp{("-C")} in order to compress all data connections. -@end table - -@item nntp-open-via-rlogin-and-telnet -@findex nntp-open-via-rlogin-and-telnet -Does essentially the same, but uses @code{telnet} instead of @samp{netcat} -to connect to the real @acronym{NNTP} server from the intermediate host. -@code{telnet} is a bit less robust because of things like -line-end-conversion, but sometimes @code{netcat} is simply not available. - -@code{nntp-open-via-rlogin-and-telnet}-specific variables: - -@table @code -@item nntp-telnet-command -@vindex nntp-telnet-command -Command used to connect to the real @acronym{NNTP} server from the -intermediate host. The default is @samp{telnet}. - -@item nntp-telnet-switches -@vindex nntp-telnet-switches -List of strings to be used as the switches to the -@code{nntp-telnet-command} command. The default is @code{("-8")}. - -@item nntp-via-rlogin-command -@vindex nntp-via-rlogin-command -Command used to log in on the intermediate host. The default is -@samp{rsh}, but @samp{ssh} is a popular alternative. - -@item nntp-via-rlogin-command-switches -@vindex nntp-via-rlogin-command-switches -List of strings to be used as the switches to -@code{nntp-via-rlogin-command}. If you use @samp{ssh}, you may need to set -this to @samp{("-t" "-e" "none")} or @samp{("-C" "-t" "-e" "none")} if -the telnet command requires a pseudo-tty allocation on an intermediate -host. The default is @code{nil}. -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). - -@item nntp-open-via-telnet-and-telnet -@findex nntp-open-via-telnet-and-telnet -Does essentially the same, but uses @samp{telnet} instead of -@samp{rlogin} to connect to the intermediate host. - -@code{nntp-open-via-telnet-and-telnet}-specific variables: - -@table @code -@item nntp-via-telnet-command -@vindex nntp-via-telnet-command -Command used to @code{telnet} the intermediate host. The default is -@samp{telnet}. - -@item nntp-via-telnet-switches -@vindex nntp-via-telnet-switches -List of strings to be used as the switches to the -@code{nntp-via-telnet-command} command. The default is @samp{("-8")}. - -@item nntp-via-user-password -@vindex nntp-via-user-password -Password to use when logging in on the intermediate host. - -@item nntp-via-envuser -@vindex nntp-via-envuser -If non-@code{nil}, the intermediate @code{telnet} session (client and -server both) will support the @code{ENVIRON} option and not prompt for -login name. This works for Solaris @code{telnet}, for instance. - -@item nntp-via-shell-prompt -@vindex nntp-via-shell-prompt -Regexp matching the shell prompt on the intermediate host. The default -is @samp{bash\\|\$ *\r?$\\|> *\r?}. - -@end table - -Note that you may want to change the value for @code{nntp-end-of-line} -to @samp{\n} (@pxref{Common Variables}). -@end table - - -Here are some additional variables that are understood by all the above -functions: - -@table @code - -@item nntp-via-user-name -@vindex nntp-via-user-name -User name to use when connecting to the intermediate host. - -@item nntp-via-address -@vindex nntp-via-address -Address of the intermediate host to connect to. - -@end table - - -@node Common Variables -@subsubsection Common Variables - -The following variables affect the behavior of all, or several of the -pre-made connection functions. When not specified, all functions are -affected (the values of the following variables will be used as the -default if each virtual @code{nntp} server doesn't specify those server -variables individually). - -@table @code - -@item nntp-pre-command -@vindex nntp-pre-command -A command wrapper to use when connecting through a non native -connection function (all except @code{nntp-open-network-stream}, -@code{nntp-open-tls-stream}, and @code{nntp-open-ssl-stream}). This is -where you would put a @samp{SOCKS} wrapper for instance. - -@item nntp-address -@vindex nntp-address -The address of the @acronym{NNTP} server. - -@item nntp-port-number -@vindex nntp-port-number -Port number to connect to the @acronym{NNTP} server. The default is -@samp{nntp}. If you use @acronym{NNTP} over -@acronym{TLS}/@acronym{SSL}, you may want to use integer ports rather -than named ports (i.e, use @samp{563} instead of @samp{snews} or -@samp{nntps}), because external @acronym{TLS}/@acronym{SSL} tools may -not work with named ports. - -@item nntp-end-of-line -@vindex nntp-end-of-line -String to use as end-of-line marker when talking to the @acronym{NNTP} -server. This is @samp{\r\n} by default, but should be @samp{\n} when -using a non native telnet connection function. - -@item nntp-netcat-command -@vindex nntp-netcat-command -Command to use when connecting to the @acronym{NNTP} server through -@samp{netcat}. This is @emph{not} for an intermediate host. This is -just for the real @acronym{NNTP} server. The default is -@samp{nc}. - -@item nntp-netcat-switches -@vindex nntp-netcat-switches -A list of switches to pass to @code{nntp-netcat-command}. The default -is @samp{()}. - -@end table - -@node NNTP marks -@subsubsection NNTP marks -@cindex storing NNTP marks - -Gnus stores marks (@pxref{Marking Articles}) for @acronym{NNTP} -servers in marks files. A marks file records what marks you have set -in a group and each file is specific to the corresponding server. -Marks files are stored in @file{~/News/marks} -(@code{nntp-marks-directory}) under a classic hierarchy resembling -that of a news server, for example marks for the group -@samp{gmane.discuss} on the news.gmane.org server will be stored in -the file @file{~/News/marks/news.gmane.org/gmane/discuss/.marks}. - -Marks files are useful because you can copy the @file{~/News/marks} -directory (using rsync, scp or whatever) to another Gnus installation, -and it will realize what articles you have read and marked. The data -in @file{~/News/marks} has priority over the same data in -@file{~/.newsrc.eld}. - -Note that marks files are very much server-specific: Gnus remembers -the article numbers so if you don't use the same servers on both -installations things are most likely to break (most @acronym{NNTP} -servers do not use the same article numbers as any other server). -However, if you use servers A, B, C on one installation and servers A, -D, E on the other, you can sync the marks files for A and then you'll -get synchronization for that server between the two installations. - -Using @acronym{NNTP} marks can possibly incur a performance penalty so -if Gnus feels sluggish, try setting the @code{nntp-marks-is-evil} -variable to @code{t}. Marks will then be stored in @file{~/.newsrc.eld}. - -Related variables: - -@table @code - -@item nntp-marks-is-evil -@vindex nntp-marks-is-evil -If non-@code{nil}, this back end will ignore any marks files. The -default is @code{nil}. - -@item nntp-marks-directory -@vindex nntp-marks-directory -The directory where marks for nntp groups will be stored. - -@end table - - -@node News Spool -@subsection News Spool -@cindex nnspool -@cindex news spool - -Subscribing to a foreign group from the local spool is extremely easy, -and might be useful, for instance, to speed up reading groups that -contain very big articles---@samp{alt.binaries.pictures.furniture}, for -instance. - -Anyway, you just specify @code{nnspool} as the method and @code{""} (or -anything else) as the address. - -If you have access to a local spool, you should probably use that as the -native select method (@pxref{Finding the News}). It is normally faster -than using an @code{nntp} select method, but might not be. It depends. -You just have to try to find out what's best at your site. - -@table @code - -@item nnspool-inews-program -@vindex nnspool-inews-program -Program used to post an article. - -@item nnspool-inews-switches -@vindex nnspool-inews-switches -Parameters given to the inews program when posting an article. - -@item nnspool-spool-directory -@vindex nnspool-spool-directory -Where @code{nnspool} looks for the articles. This is normally -@file{/usr/spool/news/}. - -@item nnspool-nov-directory -@vindex nnspool-nov-directory -Where @code{nnspool} will look for @acronym{NOV} files. This is normally@* -@file{/usr/spool/news/over.view/}. - -@item nnspool-lib-dir -@vindex nnspool-lib-dir -Where the news lib dir is (@file{/usr/lib/news/} by default). - -@item nnspool-active-file -@vindex nnspool-active-file -The name of the active file. - -@item nnspool-newsgroups-file -@vindex nnspool-newsgroups-file -The name of the group descriptions file. - -@item nnspool-history-file -@vindex nnspool-history-file -The name of the news history file. - -@item nnspool-active-times-file -@vindex nnspool-active-times-file -The name of the active date file. - -@item nnspool-nov-is-evil -@vindex nnspool-nov-is-evil -If non-@code{nil}, @code{nnspool} won't try to use any @acronym{NOV} files -that it finds. - -@item nnspool-sift-nov-with-sed -@vindex nnspool-sift-nov-with-sed -@cindex sed -If non-@code{nil}, which is the default, use @code{sed} to get the -relevant portion from the overview file. If @code{nil}, -@code{nnspool} will load the entire file into a buffer and process it -there. - -@end table - - -@node Getting Mail -@section Getting Mail -@cindex reading mail -@cindex mail - -Reading mail with a newsreader---isn't that just plain WeIrD? But of -course. - -@menu -* Mail in a Newsreader:: Important introductory notes. -* Getting Started Reading Mail:: A simple cookbook example. -* Splitting Mail:: How to create mail groups. -* Mail Sources:: How to tell Gnus where to get mail from. -* Mail Back End Variables:: Variables for customizing mail handling. -* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. -* Group Mail Splitting:: Use group customize to drive mail splitting. -* Incorporating Old Mail:: What about the old mail you have? -* Expiring Mail:: Getting rid of unwanted mail. -* Washing Mail:: Removing cruft from the mail you get. -* Duplicates:: Dealing with duplicated mail. -* Not Reading Mail:: Using mail back ends for reading other files. -* Choosing a Mail Back End:: Gnus can read a variety of mail formats. -@end menu - - -@node Mail in a Newsreader -@subsection Mail in a Newsreader - -If you are used to traditional mail readers, but have decided to switch -to reading mail with Gnus, you may find yourself experiencing something -of a culture shock. - -Gnus does not behave like traditional mail readers. If you want to make -it behave that way, you can, but it's an uphill battle. - -Gnus, by default, handles all its groups using the same approach. This -approach is very newsreaderly---you enter a group, see the new/unread -messages, and when you read the messages, they get marked as read, and -you don't see them any more. (Unless you explicitly ask for them.) - -In particular, you do not do anything explicitly to delete messages. - -Does this mean that all the messages that have been marked as read are -deleted? How awful! - -But, no, it means that old messages are @dfn{expired} according to some -scheme or other. For news messages, the expire process is controlled by -the news administrator; for mail, the expire process is controlled by -you. The expire process for mail is covered in depth in @ref{Expiring -Mail}. - -What many Gnus users find, after using it a while for both news and -mail, is that the transport mechanism has very little to do with how -they want to treat a message. - -Many people subscribe to several mailing lists. These are transported -via @acronym{SMTP}, and are therefore mail. But we might go for weeks without -answering, or even reading these messages very carefully. We may not -need to save them because if we should need to read one again, they are -archived somewhere else. - -Some people have local news groups which have only a handful of readers. -These are transported via @acronym{NNTP}, and are therefore news. But we may need -to read and answer a large fraction of the messages very carefully in -order to do our work. And there may not be an archive, so we may need -to save the interesting messages the same way we would personal mail. - -The important distinction turns out to be not the transport mechanism, -but other factors such as how interested we are in the subject matter, -or how easy it is to retrieve the message if we need to read it again. - -Gnus provides many options for sorting mail into ``groups'' which behave -like newsgroups, and for treating each group (whether mail or news) -differently. - -Some users never get comfortable using the Gnus (ahem) paradigm and wish -that Gnus should grow up and be a male, er, mail reader. It is possible -to whip Gnus into a more mailreaderly being, but, as said before, it's -not easy. People who prefer proper mail readers should try @sc{vm} -instead, which is an excellent, and proper, mail reader. - -I don't mean to scare anybody off, but I want to make it clear that you -may be required to learn a new way of thinking about messages. After -you've been subjected to The Gnus Way, you will come to love it. I can -guarantee it. (At least the guy who sold me the Emacs Subliminal -Brain-Washing Functions that I've put into Gnus did guarantee it. You -Will Be Assimilated. You Love Gnus. You Love The Gnus Mail Way. -You Do.) - - -@node Getting Started Reading Mail -@subsection Getting Started Reading Mail - -It's quite easy to use Gnus to read your new mail. You just plonk the -mail back end of your choice into @code{gnus-secondary-select-methods}, -and things will happen automatically. - -For instance, if you want to use @code{nnml} (which is a ``one file per -mail'' back end), you could put the following in your @file{~/.gnus.el} file: - -@lisp -(setq gnus-secondary-select-methods '((nnml ""))) -@end lisp - -Now, the next time you start Gnus, this back end will be queried for new -articles, and it will move all the messages in your spool file to its -directory, which is @file{~/Mail/} by default. The new group that will -be created (@samp{mail.misc}) will be subscribed, and you can read it -like any other group. - -You will probably want to split the mail into several groups, though: - -@lisp -(setq nnmail-split-methods - '(("junk" "^From:.*Lars Ingebrigtsen") - ("crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("other" ""))) -@end lisp - -This will result in three new @code{nnml} mail groups being created: -@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the -mail that doesn't fit into the first two groups will be placed in the -last group. - -This should be sufficient for reading mail with Gnus. You might want to -give the other sections in this part of the manual a perusal, though. -Especially @pxref{Choosing a Mail Back End} and @pxref{Expiring Mail}. - - -@node Splitting Mail -@subsection Splitting Mail -@cindex splitting mail -@cindex mail splitting -@cindex mail filtering (splitting) - -@vindex nnmail-split-methods -The @code{nnmail-split-methods} variable says how the incoming mail is -to be split into groups. - -@lisp -(setq nnmail-split-methods - '(("mail.junk" "^From:.*Lars Ingebrigtsen") - ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") - ("mail.other" ""))) -@end lisp - -This variable is a list of lists, where the first element of each of -these lists is the name of the mail group (they do not have to be called -something beginning with @samp{mail}, by the way), and the second -element is a regular expression used on the header of each mail to -determine if it belongs in this mail group. The first string may -contain @samp{\\1} forms, like the ones used by @code{replace-match} to -insert sub-expressions from the matched text. For instance: - -@lisp -("list.\\1" "From:.* \\(.*\\)-list@@majordomo.com") -@end lisp - -@noindent -In that case, @code{nnmail-split-lowercase-expanded} controls whether -the inserted text should be made lowercase. @xref{Fancy Mail Splitting}. - -The second element can also be a function. In that case, it will be -called narrowed to the headers with the first element of the rule as the -argument. It should return a non-@code{nil} value if it thinks that the -mail belongs in that group. - -@cindex @samp{bogus} group -The last of these groups should always be a general one, and the regular -expression should @emph{always} be @samp{""} so that it matches any mails -that haven't been matched by any of the other regexps. (These rules are -processed from the beginning of the alist toward the end. The first rule -to make a match will ``win'', unless you have crossposting enabled. In -that case, all matching rules will ``win''.) If no rule matched, the mail -will end up in the @samp{bogus} group. When new groups are created by -splitting mail, you may want to run @code{gnus-group-find-new-groups} to -see the new groups. This also applies to the @samp{bogus} group. - -If you like to tinker with this yourself, you can set this variable to a -function of your choice. This function will be called without any -arguments in a buffer narrowed to the headers of an incoming mail -message. The function should return a list of group names that it -thinks should carry this mail message. - -Note that the mail back ends are free to maul the poor, innocent, -incoming headers all they want to. They all add @code{Lines} headers; -some add @code{X-Gnus-Group} headers; most rename the Unix mbox -@code{From} line to something else. - -@vindex nnmail-crosspost -The mail back ends all support cross-posting. If several regexps match, -the mail will be ``cross-posted'' to all those groups. -@code{nnmail-crosspost} says whether to use this mechanism or not. Note -that no articles are crossposted to the general (@samp{""}) group. - -@vindex nnmail-crosspost-link-function -@cindex crosspost -@cindex links -@code{nnmh} and @code{nnml} makes crossposts by creating hard links to -the crossposted articles. However, not all file systems support hard -links. If that's the case for you, set -@code{nnmail-crosspost-link-function} to @code{copy-file}. (This -variable is @code{add-name-to-file} by default.) - -@kindex M-x nnmail-split-history -@findex nnmail-split-history -If you wish to see where the previous mail split put the messages, you -can use the @kbd{M-x nnmail-split-history} command. If you wish to see -where re-spooling messages would put the messages, you can use -@code{gnus-summary-respool-trace} and related commands (@pxref{Mail -Group Commands}). - -@vindex nnmail-split-header-length-limit -Header lines longer than the value of -@code{nnmail-split-header-length-limit} are excluded from the split -function. - -@vindex nnmail-mail-splitting-decodes -@vindex nnmail-mail-splitting-charset -By default, splitting does not decode headers, so you can not match on -non-@acronym{ASCII} strings. But it is useful if you want to match -articles based on the raw header data. To enable it, set the -@code{nnmail-mail-splitting-decodes} variable to a non-@code{nil} value. -In addition, the value of the @code{nnmail-mail-splitting-charset} -variable is used for decoding non-@acronym{MIME} encoded string when -@code{nnmail-mail-splitting-decodes} is non-@code{nil}. The default -value is @code{nil} which means not to decode non-@acronym{MIME} encoded -string. A suitable value for you will be @code{undecided} or be the -charset used normally in mails you are interested in. - -@vindex nnmail-resplit-incoming -By default, splitting is performed on all incoming messages. If you -specify a @code{directory} entry for the variable @code{mail-sources} -(@pxref{Mail Source Specifiers}), however, then splitting does -@emph{not} happen by default. You can set the variable -@code{nnmail-resplit-incoming} to a non-@code{nil} value to make -splitting happen even in this case. (This variable has no effect on -other kinds of entries.) - -Gnus gives you all the opportunity you could possibly want for shooting -yourself in the foot. Let's say you create a group that will contain -all the mail you get from your boss. And then you accidentally -unsubscribe from the group. Gnus will still put all the mail from your -boss in the unsubscribed group, and so, when your boss mails you ``Have -that report ready by Monday or you're fired!'', you'll never see it and, -come Tuesday, you'll still believe that you're gainfully employed while -you really should be out collecting empty bottles to save up for next -month's rent money. - - -@node Mail Sources -@subsection Mail Sources - -Mail can be gotten from many different sources---the mail spool, from -a @acronym{POP} mail server, from a procmail directory, or from a -maildir, for instance. - -@menu -* Mail Source Specifiers:: How to specify what a mail source is. -* Mail Source Customization:: Some variables that influence things. -* Fetching Mail:: Using the mail source specifiers. -@end menu - - -@node Mail Source Specifiers -@subsubsection Mail Source Specifiers -@cindex POP -@cindex mail server -@cindex procmail -@cindex mail spool -@cindex mail source - -You tell Gnus how to fetch mail by setting @code{mail-sources} -(@pxref{Fetching Mail}) to a @dfn{mail source specifier}. - -Here's an example: - -@lisp -(pop :server "pop3.mailserver.com" :user "myname") -@end lisp - -As can be observed, a mail source specifier is a list where the first -element is a @dfn{mail source type}, followed by an arbitrary number of -@dfn{keywords}. Keywords that are not explicitly specified are given -default values. - -The @code{mail-sources} is global for all mail groups. You can specify -an additional mail source for a particular group by including the -@code{group} mail specifier in @code{mail-sources}, and setting a -@code{mail-source} group parameter (@pxref{Group Parameters}) specifying -a single mail source. When this is used, @code{mail-sources} is -typically just @code{(group)}; the @code{mail-source} parameter for a -group might look like this: - -@lisp -(mail-source . (file :path "home/user/spools/foo.spool")) -@end lisp - -This means that the group's (and only this group's) messages will be -fetched from the spool file @samp{/user/spools/foo.spool}. - -The following mail source types are available: - -@table @code -@item file -Get mail from a single file; typically from the mail spool. - -Keywords: - -@table @code -@item :path -The file name. Defaults to the value of the @env{MAIL} -environment variable or the value of @code{rmail-spool-directory} -(usually something like @file{/usr/mail/spool/user-name}). - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. -@end table - -An example file mail source: - -@lisp -(file :path "/usr/spool/mail/user-name") -@end lisp - -Or using the default file name: - -@lisp -(file) -@end lisp - -If the mail spool file is not located on the local machine, it's best -to use @acronym{POP} or @acronym{IMAP} or the like to fetch the mail. -You can not use ange-ftp file names here---it has no way to lock the -mail spool while moving the mail. - -If it's impossible to set up a proper server, you can use ssh instead. - -@lisp -(setq mail-sources - '((file :prescript "ssh host bin/getmail >%t"))) -@end lisp - -The @samp{getmail} script would look something like the following: - -@example -#!/bin/sh -# getmail - move mail from spool to stdout -# flu@@iki.fi - -MOVEMAIL=/usr/lib/emacs/20.3/i386-redhat-linux/movemail -TMP=$HOME/Mail/tmp -rm -f $TMP; $MOVEMAIL $MAIL $TMP >/dev/null && cat $TMP -@end example - -Alter this script to fit the @samp{movemail} and temporary -file you want to use. - - -@item directory -@vindex nnmail-scan-directory-mail-source-once -Get mail from several files in a directory. This is typically used -when you have procmail split the incoming mail into several files. -That is, there is a one-to-one correspondence between files in that -directory and groups, so that mail from the file @file{foo.bar.spool} -will be put in the group @code{foo.bar}. (You can change the suffix -to be used instead of @code{.spool}.) Setting -@code{nnmail-scan-directory-mail-source-once} to non-@code{nil} forces -Gnus to scan the mail source only once. This is particularly useful -if you want to scan mail groups at a specified level. - -@vindex nnmail-resplit-incoming -There is also the variable @code{nnmail-resplit-incoming}, if you set -that to a non-@code{nil} value, then the normal splitting process is -applied to all the files from the directory, @ref{Splitting Mail}. - -Keywords: - -@table @code -@item :path -The name of the directory where the files are. There is no default -value. - -@item :suffix -Only files ending with this suffix are used. The default is -@samp{.spool}. - -@item :predicate -Only files that have this predicate return non-@code{nil} are returned. -The default is @code{identity}. This is used as an additional -filter---only files that have the right suffix @emph{and} satisfy this -predicate are considered. - -@item :prescript -@itemx :postscript -Script run before/after fetching mail. - -@end table - -An example directory mail source: - -@lisp -(directory :path "/home/user-name/procmail-dir/" - :suffix ".prcml") -@end lisp - -@item pop -Get mail from a @acronym{POP} server. - -Keywords: - -@table @code -@item :server -The name of the @acronym{POP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{POP} server. This can be a number (eg, -@samp{:port 1234}) or a string (eg, @samp{:port "pop3"}). If it is a -string, it should be a service name as listed in @file{/etc/services} on -Unix systems. The default is @samp{"pop3"}. On some systems you might -need to specify it as @samp{"pop-3"} instead. - -@item :user -The user name to give to the @acronym{POP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{POP} server. If not specified, -the user is prompted. - -@item :program -The program to use to fetch mail from the @acronym{POP} server. This -should be a @code{format}-like string. Here's an example: - -@example -fetchmail %u@@%s -P %p %t -@end example - -The valid format specifier characters are: - -@table @samp -@item t -The name of the file the mail is to be moved to. This must always be -included in this string. - -@item s -The name of the server. - -@item P -The port number of the server. - -@item u -The user name to use. - -@item p -The password to use. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :prescript -A script to be run before fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -@item :postscript -A script to be run after fetching the mail. The syntax is the same as -the @code{:program} keyword. This can also be a function to be run. - -@item :function -The function to use to fetch mail from the @acronym{POP} server. The -function is called with one parameter---the name of the file where the -mail should be moved to. - -@item :authentication -This can be either the symbol @code{password} or the symbol @code{apop} -and says what authentication scheme to use. The default is -@code{password}. - -@end table - -@vindex pop3-movemail -@vindex pop3-leave-mail-on-server -If the @code{:program} and @code{:function} keywords aren't specified, -@code{pop3-movemail} will be used. If @code{pop3-leave-mail-on-server} -is non-@code{nil} the mail is to be left on the @acronym{POP} server -after fetching when using @code{pop3-movemail}. Note that POP servers -maintain no state information between sessions, so what the client -believes is there and what is actually there may not match up. If they -do not, then you may get duplicate mails or the whole thing can fall -apart and leave you with a corrupt mailbox. - -Here are some examples for getting mail from a @acronym{POP} server. -Fetch from the default @acronym{POP} server, using the default user -name, and default fetcher: - -@lisp -(pop) -@end lisp - -Fetch from a named server with a named user and password: - -@lisp -(pop :server "my.pop.server" - :user "user-name" :password "secret") -@end lisp - -Use @samp{movemail} to move the mail: - -@lisp -(pop :program "movemail po:%u %t %p") -@end lisp - -@item maildir -Get mail from a maildir. This is a type of mailbox that is supported by -at least qmail and postfix, where each file in a special directory -contains exactly one mail. - -Keywords: - -@table @code -@item :path -The name of the directory where the mails are stored. The default is -taken from the @env{MAILDIR} environment variable or -@file{~/Maildir/}. -@item :subdirs -The subdirectories of the Maildir. The default is -@samp{("new" "cur")}. - -@c If you sometimes look at your mail through a pop3 daemon before fetching -@c them with Gnus, you may also have to fetch your mails from the -@c @code{cur} directory inside the maildir, like in the first example -@c below. - -You can also get mails from remote hosts (because maildirs don't suffer -from locking problems). - -@end table - -Two example maildir mail sources: - -@lisp -(maildir :path "/home/user-name/Maildir/" - :subdirs ("cur" "new")) -@end lisp - -@lisp -(maildir :path "/user@@remotehost.org:~/Maildir/" - :subdirs ("new")) -@end lisp - -@item imap -Get mail from a @acronym{IMAP} server. If you don't want to use -@acronym{IMAP} as intended, as a network mail reading protocol (ie -with nnimap), for some reason or other, Gnus let you treat it similar -to a @acronym{POP} server and fetches articles from a given -@acronym{IMAP} mailbox. @xref{IMAP}, for more information. - -Note that for the Kerberos, GSSAPI, @acronym{TLS}/@acronym{SSL} and STARTTLS support you -may need external programs and libraries, @xref{IMAP}. - -Keywords: - -@table @code -@item :server -The name of the @acronym{IMAP} server. The default is taken from the -@env{MAILHOST} environment variable. - -@item :port -The port number of the @acronym{IMAP} server. The default is @samp{143}, or -@samp{993} for @acronym{TLS}/@acronym{SSL} connections. - -@item :user -The user name to give to the @acronym{IMAP} server. The default is the login -name. - -@item :password -The password to give to the @acronym{IMAP} server. If not specified, the user is -prompted. - -@item :stream -What stream to use for connecting to the server, this is one of the -symbols in @code{imap-stream-alist}. Right now, this means -@samp{gssapi}, @samp{kerberos4}, @samp{starttls}, @samp{tls}, -@samp{ssl}, @samp{shell} or the default @samp{network}. - -@item :authentication -Which authenticator to use for authenticating to the server, this is -one of the symbols in @code{imap-authenticator-alist}. Right now, -this means @samp{gssapi}, @samp{kerberos4}, @samp{digest-md5}, -@samp{cram-md5}, @samp{anonymous} or the default @samp{login}. - -@item :program -When using the `shell' :stream, the contents of this variable is -mapped into the @code{imap-shell-program} variable. This should be a -@code{format}-like string (or list of strings). Here's an example: - -@example -ssh %s imapd -@end example - -Make sure nothing is interfering with the output of the program, e.g., -don't forget to redirect the error output to the void. The valid format -specifier characters are: - -@table @samp -@item s -The name of the server. - -@item l -User name from @code{imap-default-user}. - -@item p -The port number of the server. -@end table - -The values used for these specs are taken from the values you give the -corresponding keywords. - -@item :mailbox -The name of the mailbox to get mail from. The default is @samp{INBOX} -which normally is the mailbox which receives incoming mail. - -@item :predicate -The predicate used to find articles to fetch. The default, @samp{UNSEEN -UNDELETED}, is probably the best choice for most people, but if you -sometimes peek in your mailbox with a @acronym{IMAP} client and mark some -articles as read (or; SEEN) you might want to set this to @samp{1:*}. -Then all articles in the mailbox is fetched, no matter what. For a -complete list of predicates, see RFC 2060 section 6.4.4. - -@item :fetchflag -How to flag fetched articles on the server, the default @samp{\Deleted} -will mark them as deleted, an alternative would be @samp{\Seen} which -would simply mark them as read. These are the two most likely choices, -but more flags are defined in RFC 2060 section 2.3.2. - -@item :dontexpunge -If non-@code{nil}, don't remove all articles marked as deleted in the -mailbox after finishing the fetch. - -@end table - -An example @acronym{IMAP} mail source: - -@lisp -(imap :server "mail.mycorp.com" - :stream kerberos4 - :fetchflag "\\Seen") -@end lisp - -@item webmail -Get mail from a webmail server, such as @uref{http://www.hotmail.com/}, -@uref{http://webmail.netscape.com/}, @uref{http://www.netaddress.com/}, -@uref{http://mail.yahoo.com/}. - -NOTE: Webmail largely depends on cookies. A "one-line-cookie" patch is -required for url "4.0pre.46". - -WARNING: Mails may be lost. NO WARRANTY. - -Keywords: - -@table @code -@item :subtype -The type of the webmail server. The default is @code{hotmail}. The -alternatives are @code{netscape}, @code{netaddress}, @code{my-deja}. - -@item :user -The user name to give to the webmail server. The default is the login -name. - -@item :password -The password to give to the webmail server. If not specified, the user is -prompted. - -@item :dontexpunge -If non-@code{nil}, only fetch unread articles and don't move them to -trash folder after finishing the fetch. - -@end table - -An example webmail source: - -@lisp -(webmail :subtype 'hotmail - :user "user-name" - :password "secret") -@end lisp - -@item group -Get the actual mail source from the @code{mail-source} group parameter, -@xref{Group Parameters}. - -@end table - -@table @dfn -@item Common Keywords -Common keywords can be used in any type of mail source. - -Keywords: - -@table @code -@item :plugged -If non-@code{nil}, fetch the mail even when Gnus is unplugged. If you -use directory source to get mail, you can specify it as in this -example: - -@lisp -(setq mail-sources - '((directory :path "/home/pavel/.Spool/" - :suffix "" - :plugged t))) -@end lisp - -Gnus will then fetch your mail even when you are unplugged. This is -useful when you use local mail and news. - -@end table -@end table - -@subsubsection Function Interface - -Some of the above keywords specify a Lisp function to be executed. -For each keyword @code{:foo}, the Lisp variable @code{foo} is bound to -the value of the keyword while the function is executing. For example, -consider the following mail-source setting: - -@lisp -(setq mail-sources '((pop :user "jrl" - :server "pophost" :function fetchfunc))) -@end lisp - -While the function @code{fetchfunc} is executing, the symbol @code{user} -is bound to @code{"jrl"}, and the symbol @code{server} is bound to -@code{"pophost"}. The symbols @code{port}, @code{password}, -@code{program}, @code{prescript}, @code{postscript}, @code{function}, -and @code{authentication} are also bound (to their default values). - -See above for a list of keywords for each type of mail source. - - -@node Mail Source Customization -@subsubsection Mail Source Customization - -The following is a list of variables that influence how the mail is -fetched. You would normally not need to set or change any of these -variables. - -@table @code -@item mail-source-crash-box -@vindex mail-source-crash-box -File where mail will be stored while processing it. The default is@* -@file{~/.emacs-mail-crash-box}. - -@cindex Incoming* -@item mail-source-delete-incoming -@vindex mail-source-delete-incoming -If non-@code{nil}, delete incoming files after handling them. If -@code{t}, delete the files immediately, if @code{nil}, never delete any -files. If a positive number, delete files older than number of days -(the deletion will only happen when receiving new mail). You may also -set @code{mail-source-delete-incoming} to @code{nil} and call -@code{mail-source-delete-old-incoming} from a hook or interactively. -@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae -and @code{2} in released Gnusae. @xref{Gnus Development}. - -@item mail-source-delete-old-incoming-confirm -@vindex mail-source-delete-old-incoming-confirm -If non-@code{nil}, ask for confirmation before deleting old incoming -files. This variable only applies when -@code{mail-source-delete-incoming} is a positive number. - -@item mail-source-ignore-errors -@vindex mail-source-ignore-errors -If non-@code{nil}, ignore errors when reading mail from a mail source. - -@item mail-source-directory -@vindex mail-source-directory -Directory where incoming mail source files (if any) will be stored. The -default is @file{~/Mail/}. At present, the only thing this is used for -is to say where the incoming files will be stored if the variable -@code{mail-source-delete-incoming} is @code{nil} or a number. - -@item mail-source-incoming-file-prefix -@vindex mail-source-incoming-file-prefix -Prefix for file name for storing incoming mail. The default is -@file{Incoming}, in which case files will end up with names like -@file{Incoming30630D_} or @file{Incoming298602ZD}. This is really only -relevant if @code{mail-source-delete-incoming} is @code{nil} or a -number. - -@item mail-source-default-file-modes -@vindex mail-source-default-file-modes -All new mail files will get this file mode. The default is 384. - -@item mail-source-movemail-program -@vindex mail-source-movemail-program -If non-@code{nil}, name of program for fetching new mail. If -@code{nil}, @code{movemail} in @var{exec-directory}. - -@end table - - -@node Fetching Mail -@subsubsection Fetching Mail - -@vindex mail-sources -The way to actually tell Gnus where to get new mail from is to set -@code{mail-sources} to a list of mail source specifiers -(@pxref{Mail Source Specifiers}). - -If this variable is @code{nil}, the mail back ends will never attempt to -fetch mail by themselves. - -If you want to fetch mail both from your local spool as well as a -@acronym{POP} mail server, you'd say something like: - -@lisp -(setq mail-sources - '((file) - (pop :server "pop3.mail.server" - :password "secret"))) -@end lisp - -Or, if you don't want to use any of the keyword defaults: - -@lisp -(setq mail-sources - '((file :path "/var/spool/mail/user-name") - (pop :server "pop3.mail.server" - :user "user-name" - :port "pop3" - :password "secret"))) -@end lisp - - -When you use a mail back end, Gnus will slurp all your mail from your -inbox and plonk it down in your home directory. Gnus doesn't move any -mail if you're not using a mail back end---you have to do a lot of magic -invocations first. At the time when you have finished drawing the -pentagram, lightened the candles, and sacrificed the goat, you really -shouldn't be too surprised when Gnus moves your mail. - - - -@node Mail Back End Variables -@subsection Mail Back End Variables - -These variables are (for the most part) pertinent to all the various -mail back ends. - -@table @code -@vindex nnmail-read-incoming-hook -@item nnmail-read-incoming-hook -The mail back ends all call this hook after reading new mail. You can -use this hook to notify any mail watch programs, if you want to. - -@vindex nnmail-split-hook -@item nnmail-split-hook -@findex gnus-article-decode-encoded-words -@cindex RFC 1522 decoding -@cindex RFC 2047 decoding -Hook run in the buffer where the mail headers of each message is kept -just before the splitting based on these headers is done. The hook is -free to modify the buffer contents in any way it sees fit---the buffer -is discarded after the splitting has been done, and no changes performed -in the buffer will show up in any files. -@code{gnus-article-decode-encoded-words} is one likely function to add -to this hook. - -@vindex nnmail-pre-get-new-mail-hook -@vindex nnmail-post-get-new-mail-hook -@item nnmail-pre-get-new-mail-hook -@itemx nnmail-post-get-new-mail-hook -These are two useful hooks executed when treating new incoming -mail---@code{nnmail-pre-get-new-mail-hook} (is called just before -starting to handle the new mail) and -@code{nnmail-post-get-new-mail-hook} (is called when the mail handling -is done). Here's and example of using these two hooks to change the -default file modes the new mail files get: - -@lisp -(add-hook 'nnmail-pre-get-new-mail-hook - (lambda () (set-default-file-modes 511))) - -(add-hook 'nnmail-post-get-new-mail-hook - (lambda () (set-default-file-modes 551))) -@end lisp - -@item nnmail-use-long-file-names -@vindex nnmail-use-long-file-names -If non-@code{nil}, the mail back ends will use long file and directory -names. Groups like @samp{mail.misc} will end up in directories -(assuming use of @code{nnml} back end) or files (assuming use of -@code{nnfolder} back end) like @file{mail.misc}. If it is @code{nil}, -the same group will end up in @file{mail/misc}. - -@item nnmail-delete-file-function -@vindex nnmail-delete-file-function -@findex delete-file -Function called to delete files. It is @code{delete-file} by default. - -@item nnmail-cache-accepted-message-ids -@vindex nnmail-cache-accepted-message-ids -If non-@code{nil}, put the @code{Message-ID}s of articles imported into -the back end (via @code{Gcc}, for instance) into the mail duplication -discovery cache. The default is @code{nil}. - -@item nnmail-cache-ignore-groups -@vindex nnmail-cache-ignore-groups -This can be a regular expression or a list of regular expressions. -Group names that match any of the regular expressions will never be -recorded in the @code{Message-ID} cache. - -This can be useful, for example, when using Fancy Splitting -(@pxref{Fancy Mail Splitting}) together with the function -@code{nnmail-split-fancy-with-parent}. - -@end table - - -@node Fancy Mail Splitting -@subsection Fancy Mail Splitting -@cindex mail splitting -@cindex fancy mail splitting - -@vindex nnmail-split-fancy -@findex nnmail-split-fancy -If the rather simple, standard method for specifying how to split mail -doesn't allow you to do what you want, you can set -@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can -play with the @code{nnmail-split-fancy} variable. - -Let's look at an example value of this variable first: - -@lisp -;; @r{Messages from the mailer daemon are not crossposted to any of} -;; @r{the ordinary groups. Warnings are put in a separate group} -;; @r{from real errors.} -(| ("from" mail (| ("subject" "warn.*" "mail.warning") - "mail.misc")) - ;; @r{Non-error messages are crossposted to all relevant} - ;; @r{groups, but we don't crosspost between the group for the} - ;; @r{(ding) list and the group for other (ding) related mail.} - (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") - ("subject" "ding" "ding.misc")) - ;; @r{Other mailing lists@dots{}} - (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") - (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") - ;; @r{Both lists below have the same suffix, so prevent} - ;; @r{cross-posting to mkpkg.list of messages posted only to} - ;; @r{the bugs- list, but allow cross-posting when the} - ;; @r{message was really cross-posted.} - (any "bugs-mypackage@@somewhere" "mypkg.bugs") - (any "mypackage@@somewhere" - "bugs-mypackage" "mypkg.list") - ;; @r{People@dots{}} - (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) - ;; @r{Unmatched mail goes to the catch all group.} - "misc.misc") -@end lisp - -This variable has the format of a @dfn{split}. A split is a -(possibly) recursive structure where each split may contain other -splits. Here are the possible split syntaxes: - -@table @code - -@item group -If the split is a string, that will be taken as a group name. Normal -regexp match expansion will be done. See below for examples. - -@c Don't fold this line. -@item (@var{field} @var{value} [- @var{restrict} [@dots{}] ] @var{split} [@var{invert-partial}]) -The split can be a list containing at least three elements. If the -first element @var{field} (a regexp matching a header) contains -@var{value} (also a regexp) then store the message as specified by -@var{split}. - -If @var{restrict} (yet another regexp) matches some string after -@var{field} and before the end of the matched @var{value}, the -@var{split} is ignored. If none of the @var{restrict} clauses match, -@var{split} is processed. - -The last element @var{invert-partial} is optional. If it is -non-@code{nil}, the match-partial-words behavior controlled by the -variable @code{nnmail-split-fancy-match-partial-words} (see below) is -be inverted. (New in Gnus 5.10.7) - -@item (| @var{split} @dots{}) -If the split is a list, and the first element is @code{|} (vertical -bar), then process each @var{split} until one of them matches. A -@var{split} is said to match if it will cause the mail message to be -stored in one or more groups. - -@item (& @var{split} @dots{}) -If the split is a list, and the first element is @code{&}, then -process all @var{split}s in the list. - -@item junk -If the split is the symbol @code{junk}, then don't save (i.e., delete) -this message. Use with extreme caution. - -@item (: @var{function} @var{arg1} @var{arg2} @dots{}) -If the split is a list, and the first element is @samp{:}, then the -second element will be called as a function with @var{args} given as -arguments. The function should return a @var{split}. - -@cindex body split -For instance, the following function could be used to split based on the -body of the messages: - -@lisp -(defun split-on-body () - (save-excursion - (save-restriction - (widen) - (goto-char (point-min)) - (when (re-search-forward "Some.*string" nil t) - "string.group")))) -@end lisp - -The buffer is narrowed to the header of the message in question when -@var{function} is run. That's why @code{(widen)} needs to be called -after @code{save-excursion} and @code{save-restriction} in the example -above. Also note that with the nnimap backend, message bodies will -not be downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Splitting in IMAP}). - -@item (! @var{func} @var{split}) -If the split is a list, and the first element is @code{!}, then -@var{split} will be processed, and @var{func} will be called as a -function with the result of @var{split} as argument. @var{func} -should return a split. - -@item nil -If the split is @code{nil}, it is ignored. - -@end table - -In these splits, @var{field} must match a complete field name. - -Normally, @var{value} in these splits must match a complete @emph{word} -according to the fundamental mode syntax table. In other words, all -@var{value}'s will be implicitly surrounded by @code{\<...\>} markers, -which are word delimiters. Therefore, if you use the following split, -for example, - -@example -(any "joe" "joemail") -@end example - -@noindent -messages sent from @samp{joedavis@@foo.org} will normally not be filed -in @samp{joemail}. If you want to alter this behavior, you can use any -of the following three ways: - -@enumerate -@item -@vindex nnmail-split-fancy-match-partial-words -You can set the @code{nnmail-split-fancy-match-partial-words} variable -to non-@code{nil} in order to ignore word boundaries and instead the -match becomes more like a grep. This variable controls whether partial -words are matched during fancy splitting. The default value is -@code{nil}. - -Note that it influences all @var{value}'s in your split rules. - -@item -@var{value} beginning with @code{.*} ignores word boundaries in front of -a word. Similarly, if @var{value} ends with @code{.*}, word boundaries -in the rear of a word will be ignored. For example, the @var{value} -@code{"@@example\\.com"} does not match @samp{foo@@example.com} but -@code{".*@@example\\.com"} does. - -@item -You can set the @var{invert-partial} flag in your split rules of the -@samp{(@var{field} @var{value} @dots{})} types, aforementioned in this -section. If the flag is set, word boundaries on both sides of a word -are ignored even if @code{nnmail-split-fancy-match-partial-words} is -@code{nil}. Contrarily, if the flag is set, word boundaries are not -ignored even if @code{nnmail-split-fancy-match-partial-words} is -non-@code{nil}. (New in Gnus 5.10.7) -@end enumerate - -@vindex nnmail-split-abbrev-alist -@var{field} and @var{value} can also be Lisp symbols, in that case -they are expanded as specified by the variable -@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, -where the @sc{car} of a cell contains the key, and the @sc{cdr} -contains the associated value. Predefined entries in -@code{nnmail-split-abbrev-alist} include: - -@table @code -@item from -Matches the @samp{From}, @samp{Sender} and @samp{Resent-From} fields. -@item to -Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, -@samp{Resent-To} and @samp{Resent-Cc} fields. -@item any -Is the union of the @code{from} and @code{to} entries. -@end table - -@vindex nnmail-split-fancy-syntax-table -@code{nnmail-split-fancy-syntax-table} is the syntax table in effect -when all this splitting is performed. - -If you want to have Gnus create groups dynamically based on some -information in the headers (i.e., do @code{replace-match}-like -substitutions in the group names), you can say things like: - -@example -(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") -@end example - -In this example, messages sent to @samp{debian-foo@@lists.debian.org} -will be filed in @samp{mail.debian.foo}. - -If the string contains the element @samp{\&}, then the previously -matched string will be substituted. Similarly, the elements @samp{\\1} -up to @samp{\\9} will be substituted with the text matched by the -groupings 1 through 9. - -@vindex nnmail-split-lowercase-expanded -Where @code{nnmail-split-lowercase-expanded} controls whether the -lowercase of the matched string should be used for the substitution. -Setting it as non-@code{nil} is useful to avoid the creation of multiple -groups when users send to an address using different case -(i.e. mailing-list@@domain vs Mailing-List@@Domain). The default value -is @code{t}. - -@findex nnmail-split-fancy-with-parent -@code{nnmail-split-fancy-with-parent} is a function which allows you to -split followups into the same groups their parents are in. Sometimes -you can't make splitting rules for all your mail. For example, your -boss might send you personal mail regarding different projects you are -working on, and as you can't tell your boss to put a distinguishing -string into the subject line, you have to resort to manually moving the -messages into the right group. With this function, you only have to do -it once per thread. - -To use this feature, you have to set @code{nnmail-treat-duplicates} -and @code{nnmail-cache-accepted-message-ids} to a non-@code{nil} -value. And then you can include @code{nnmail-split-fancy-with-parent} -using the colon feature, like so: -@lisp -(setq nnmail-treat-duplicates 'warn ; @r{or @code{delete}} - nnmail-cache-accepted-message-ids t - nnmail-split-fancy - '(| (: nnmail-split-fancy-with-parent) - ;; @r{other splits go here} - )) -@end lisp - -This feature works as follows: when @code{nnmail-treat-duplicates} is -non-@code{nil}, Gnus records the message id of every message it sees -in the file specified by the variable -@code{nnmail-message-id-cache-file}, together with the group it is in -(the group is omitted for non-mail messages). When mail splitting is -invoked, the function @code{nnmail-split-fancy-with-parent} then looks -at the References (and In-Reply-To) header of each message to split -and searches the file specified by @code{nnmail-message-id-cache-file} -for the message ids. When it has found a parent, it returns the -corresponding group name unless the group name matches the regexp -@code{nnmail-split-fancy-with-parent-ignore-groups}. It is -recommended that you set @code{nnmail-message-id-cache-length} to a -somewhat higher number than the default so that the message ids are -still in the cache. (A value of 5000 appears to create a file some -300 kBytes in size.) -@vindex nnmail-cache-accepted-message-ids -When @code{nnmail-cache-accepted-message-ids} is non-@code{nil}, Gnus -also records the message ids of moved articles, so that the followup -messages goes into the new group. - -Also see the variable @code{nnmail-cache-ignore-groups} if you don't -want certain groups to be recorded in the cache. For example, if all -outgoing messages are written to an ``outgoing'' group, you could set -@code{nnmail-cache-ignore-groups} to match that group name. -Otherwise, answers to all your messages would end up in the -``outgoing'' group. - - -@node Group Mail Splitting -@subsection Group Mail Splitting -@cindex mail splitting -@cindex group mail splitting - -@findex gnus-group-split -If you subscribe to dozens of mailing lists but you don't want to -maintain mail splitting rules manually, group mail splitting is for you. -You just have to set @code{to-list} and/or @code{to-address} in group -parameters or group customization and set @code{nnmail-split-methods} to -@code{gnus-group-split}. This splitting function will scan all groups -for those parameters and split mail accordingly, i.e., messages posted -from or to the addresses specified in the parameters @code{to-list} or -@code{to-address} of a mail group will be stored in that group. - -Sometimes, mailing lists have multiple addresses, and you may want mail -splitting to recognize them all: just set the @code{extra-aliases} group -parameter to the list of additional addresses and it's done. If you'd -rather use a regular expression, set @code{split-regexp}. - -All these parameters in a group will be used to create an -@code{nnmail-split-fancy} split, in which the @var{field} is @samp{any}, -the @var{value} is a single regular expression that matches -@code{to-list}, @code{to-address}, all of @code{extra-aliases} and all -matches of @code{split-regexp}, and the @var{split} is the name of the -group. @var{restrict}s are also supported: just set the -@code{split-exclude} parameter to a list of regular expressions. - -If you can't get the right split to be generated using all these -parameters, or you just need something fancier, you can set the -parameter @code{split-spec} to an @code{nnmail-split-fancy} split. In -this case, all other aforementioned parameters will be ignored by -@code{gnus-group-split}. In particular, @code{split-spec} may be set to -@code{nil}, in which case the group will be ignored by -@code{gnus-group-split}. - -@vindex gnus-group-split-default-catch-all-group -@code{gnus-group-split} will do cross-posting on all groups that match, -by defining a single @code{&} fancy split containing one split for each -group. If a message doesn't match any split, it will be stored in the -group named in @code{gnus-group-split-default-catch-all-group}, unless -some group has @code{split-spec} set to @code{catch-all}, in which case -that group is used as the catch-all group. Even though this variable is -often used just to name a group, it may also be set to an arbitrarily -complex fancy split (after all, a group name is a fancy split), and this -may be useful to split mail that doesn't go to any mailing list to -personal mail folders. Note that this fancy split is added as the last -element of a @code{|} split list that also contains a @code{&} split -with the rules extracted from group parameters. - -It's time for an example. Assume the following group parameters have -been defined: - -@example -nnml:mail.bar: -((to-address . "bar@@femail.com") - (split-regexp . ".*@@femail\\.com")) -nnml:mail.foo: -((to-list . "foo@@nowhere.gov") - (extra-aliases "foo@@localhost" "foo-redist@@home") - (split-exclude "bugs-foo" "rambling-foo") - (admin-address . "foo-request@@nowhere.gov")) -nnml:mail.others: -((split-spec . catch-all)) -@end example - -Setting @code{nnmail-split-methods} to @code{gnus-group-split} will -behave as if @code{nnmail-split-fancy} had been selected and variable -@code{nnmail-split-fancy} had been set as follows: - -@lisp -(| (& (any "\\(bar@@femail\\.com\\|.*@@femail\\.com\\)" "mail.bar") - (any "\\(foo@@nowhere\\.gov\\|foo@@localhost\\|foo-redist@@home\\)" - - "bugs-foo" - "rambling-foo" "mail.foo")) - "mail.others") -@end lisp - -@findex gnus-group-split-fancy -If you'd rather not use group splitting for all your mail groups, you -may use it for only some of them, by using @code{nnmail-split-fancy} -splits like this: - -@lisp -(: gnus-group-split-fancy @var{groups} @var{no-crosspost} @var{catch-all}) -@end lisp - -@var{groups} may be a regular expression or a list of group names whose -parameters will be scanned to generate the output split. -@var{no-crosspost} can be used to disable cross-posting; in this case, a -single @code{|} split will be output. @var{catch-all} is the fall back -fancy split, used like @code{gnus-group-split-default-catch-all-group}. -If @var{catch-all} is @code{nil}, or if @code{split-regexp} matches the -empty string in any selected group, no catch-all split will be issued. -Otherwise, if some group has @code{split-spec} set to @code{catch-all}, -this group will override the value of the @var{catch-all} argument. - -@findex gnus-group-split-setup -Unfortunately, scanning all groups and their parameters can be quite -slow, especially considering that it has to be done for every message. -But don't despair! The function @code{gnus-group-split-setup} can be -used to enable @code{gnus-group-split} in a much more efficient way. It -sets @code{nnmail-split-methods} to @code{nnmail-split-fancy} and sets -@code{nnmail-split-fancy} to the split produced by -@code{gnus-group-split-fancy}. Thus, the group parameters are only -scanned once, no matter how many messages are split. - -@findex gnus-group-split-update -However, if you change group parameters, you'd have to update -@code{nnmail-split-fancy} manually. You can do it by running -@code{gnus-group-split-update}. If you'd rather have it updated -automatically, just tell @code{gnus-group-split-setup} to do it for -you. For example, add to your @file{~/.gnus.el}: - -@lisp -(gnus-group-split-setup @var{auto-update} @var{catch-all}) -@end lisp - -If @var{auto-update} is non-@code{nil}, @code{gnus-group-split-update} -will be added to @code{nnmail-pre-get-new-mail-hook}, so you won't ever -have to worry about updating @code{nnmail-split-fancy} again. If you -don't omit @var{catch-all} (it's optional, equivalent to @code{nil}), -@code{gnus-group-split-default-catch-all-group} will be set to its -value. - -@vindex gnus-group-split-updated-hook -Because you may want to change @code{nnmail-split-fancy} after it is set -by @code{gnus-group-split-update}, this function will run -@code{gnus-group-split-updated-hook} just before finishing. - -@node Incorporating Old Mail -@subsection Incorporating Old Mail -@cindex incorporating old mail -@cindex import old mail - -Most people have lots of old mail stored in various file formats. If -you have set up Gnus to read mail using one of the spiffy Gnus mail -back ends, you'll probably wish to have that old mail incorporated into -your mail groups. - -Doing so can be quite easy. - -To take an example: You're reading mail using @code{nnml} -(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a -satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox -file filled with important, but old, mail. You want to move it into -your @code{nnml} groups. - -Here's how: - -@enumerate -@item -Go to the group buffer. - -@item -Type @kbd{G f} and give the file name to the mbox file when prompted to create an -@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). - -@item -Type @kbd{SPACE} to enter the newly created group. - -@item -Type @kbd{M P b} to process-mark all articles in this group's buffer -(@pxref{Setting Process Marks}). - -@item -Type @kbd{B r} to respool all the process-marked articles, and answer -@samp{nnml} when prompted (@pxref{Mail Group Commands}). -@end enumerate - -All the mail messages in the mbox file will now also be spread out over -all your @code{nnml} groups. Try entering them and check whether things -have gone without a glitch. If things look ok, you may consider -deleting the mbox file, but I wouldn't do that unless I was absolutely -sure that all the mail has ended up where it should be. - -Respooling is also a handy thing to do if you're switching from one mail -back end to another. Just respool all the mail in the old mail groups -using the new mail back end. - - -@node Expiring Mail -@subsection Expiring Mail -@cindex article expiry -@cindex expiring mail - -Traditional mail readers have a tendency to remove mail articles when -you mark them as read, in some way. Gnus takes a fundamentally -different approach to mail reading. - -Gnus basically considers mail just to be news that has been received in -a rather peculiar manner. It does not think that it has the power to -actually change the mail, or delete any mail messages. If you enter a -mail group, and mark articles as ``read'', or kill them in some other -fashion, the mail articles will still exist on the system. I repeat: -Gnus will not delete your old, read mail. Unless you ask it to, of -course. - -To make Gnus get rid of your unwanted mail, you have to mark the -articles as @dfn{expirable}. (With the default key bindings, this means -that you have to type @kbd{E}.) This does not mean that the articles -will disappear right away, however. In general, a mail article will be -deleted from your system if, 1) it is marked as expirable, AND 2) it is -more than one week old. If you do not mark an article as expirable, it -will remain on your system until hell freezes over. This bears -repeating one more time, with some spurious capitalizations: IF you do -NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. - -You do not have to mark articles as expirable by hand. Gnus provides -two features, called ``auto-expire'' and ``total-expire'', that can help you -with this. In a nutshell, ``auto-expire'' means that Gnus hits @kbd{E} -for you when you select an article. And ``total-expire'' means that Gnus -considers all articles as expirable that are read. So, in addition to -the articles marked @samp{E}, also the articles marked @samp{r}, -@samp{R}, @samp{O}, @samp{K}, @samp{Y} and so on are considered -expirable. - -When should either auto-expire or total-expire be used? Most people -who are subscribed to mailing lists split each list into its own group -and then turn on auto-expire or total-expire for those groups. -(@xref{Splitting Mail}, for more information on splitting each list -into its own group.) - -Which one is better, auto-expire or total-expire? It's not easy to -answer. Generally speaking, auto-expire is probably faster. Another -advantage of auto-expire is that you get more marks to work with: for -the articles that are supposed to stick around, you can still choose -between tick and dormant and read marks. But with total-expire, you -only have dormant and ticked to choose from. The advantage of -total-expire is that it works well with adaptive scoring (@pxref{Adaptive -Scoring}). Auto-expire works with normal scoring but not with adaptive -scoring. - -@vindex gnus-auto-expirable-newsgroups -Groups that match the regular expression -@code{gnus-auto-expirable-newsgroups} will have all articles that you -read marked as expirable automatically. All articles marked as -expirable have an @samp{E} in the first column in the summary buffer. - -By default, if you have auto expiry switched on, Gnus will mark all the -articles you read as expirable, no matter if they were read or unread -before. To avoid having articles marked as read marked as expirable -automatically, you can put something like the following in your -@file{~/.gnus.el} file: - -@vindex gnus-mark-article-hook -@lisp -(remove-hook 'gnus-mark-article-hook - 'gnus-summary-mark-read-and-unread-as-read) -(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) -@end lisp - -Note that making a group auto-expirable doesn't mean that all read -articles are expired---only the articles marked as expirable -will be expired. Also note that using the @kbd{d} command won't make -articles expirable---only semi-automatic marking of articles as read will -mark the articles as expirable in auto-expirable groups. - -Let's say you subscribe to a couple of mailing lists, and you want the -articles you have read to disappear after a while: - -@lisp -(setq gnus-auto-expirable-newsgroups - "mail.nonsense-list\\|mail.nice-list") -@end lisp - -Another way to have auto-expiry happen is to have the element -@code{auto-expire} in the group parameters of the group. - -If you use adaptive scoring (@pxref{Adaptive Scoring}) and -auto-expiring, you'll have problems. Auto-expiring and adaptive scoring -don't really mix very well. - -@vindex nnmail-expiry-wait -The @code{nnmail-expiry-wait} variable supplies the default time an -expirable article has to live. Gnus starts counting days from when the -message @emph{arrived}, not from when it was sent. The default is seven -days. - -Gnus also supplies a function that lets you fine-tune how long articles -are to live, based on what group they are in. Let's say you want to -have one month expiry period in the @samp{mail.private} group, a one day -expiry period in the @samp{mail.junk} group, and a six day expiry period -everywhere else: - -@vindex nnmail-expiry-wait-function -@lisp -(setq nnmail-expiry-wait-function - (lambda (group) - (cond ((string= group "mail.private") - 31) - ((string= group "mail.junk") - 1) - ((string= group "important") - 'never) - (t - 6)))) -@end lisp - -The group names this function is fed are ``unadorned'' group -names---no @samp{nnml:} prefixes and the like. - -The @code{nnmail-expiry-wait} variable and -@code{nnmail-expiry-wait-function} function can either be a number (not -necessarily an integer) or one of the symbols @code{immediate} or -@code{never}. - -You can also use the @code{expiry-wait} group parameter to selectively -change the expiry period (@pxref{Group Parameters}). - -@vindex nnmail-expiry-target -The normal action taken when expiring articles is to delete them. -However, in some circumstances it might make more sense to move them -to other groups instead of deleting them. The variable -@code{nnmail-expiry-target} (and the @code{expiry-target} group -parameter) controls this. The variable supplies a default value for -all groups, which can be overridden for specific groups by the group -parameter. default value is @code{delete}, but this can also be a -string (which should be the name of the group the message should be -moved to), or a function (which will be called in a buffer narrowed to -the message in question, and with the name of the group being moved -from as its parameter) which should return a target---either a group -name or @code{delete}. - -Here's an example for specifying a group name: -@lisp -(setq nnmail-expiry-target "nnml:expired") -@end lisp - -@findex nnmail-fancy-expiry-target -@vindex nnmail-fancy-expiry-targets -Gnus provides a function @code{nnmail-fancy-expiry-target} which will -expire mail to groups according to the variable -@code{nnmail-fancy-expiry-targets}. Here's an example: - -@lisp - (setq nnmail-expiry-target 'nnmail-fancy-expiry-target - nnmail-fancy-expiry-targets - '((to-from "boss" "nnfolder:Work") - ("subject" "IMPORTANT" "nnfolder:IMPORTANT.%Y.%b") - ("from" ".*" "nnfolder:Archive-%Y"))) -@end lisp - -With this setup, any mail that has @code{IMPORTANT} in its Subject -header and was sent in the year @code{YYYY} and month @code{MMM}, will -get expired to the group @code{nnfolder:IMPORTANT.YYYY.MMM}. If its -From or To header contains the string @code{boss}, it will get expired -to @code{nnfolder:Work}. All other mail will get expired to -@code{nnfolder:Archive-YYYY}. - -@vindex nnmail-keep-last-article -If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never -expire the final article in a mail newsgroup. This is to make life -easier for procmail users. - -@vindex gnus-total-expirable-newsgroups -By the way: That line up there, about Gnus never expiring non-expirable -articles, is a lie. If you put @code{total-expire} in the group -parameters, articles will not be marked as expirable, but all read -articles will be put through the expiry process. Use with extreme -caution. Even more dangerous is the -@code{gnus-total-expirable-newsgroups} variable. All groups that match -this regexp will have all read articles put through the expiry process, -which means that @emph{all} old mail articles in the groups in question -will be deleted after a while. Use with extreme caution, and don't come -crying to me when you discover that the regexp you used matched the -wrong group and all your important mail has disappeared. Be a -@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable -with! So there! - -Most people make most of their mail groups total-expirable, though. - -@vindex gnus-inhibit-user-auto-expire -If @code{gnus-inhibit-user-auto-expire} is non-@code{nil}, user marking -commands will not mark an article as expirable, even if the group has -auto-expire turned on. - - -@node Washing Mail -@subsection Washing Mail -@cindex mail washing -@cindex list server brain damage -@cindex incoming mail treatment - -Mailers and list servers are notorious for doing all sorts of really, -really stupid things with mail. ``Hey, RFC 822 doesn't explicitly -prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the -end of all lines passing through our server, so let's do that!!!!1!'' -Yes, but RFC 822 wasn't designed to be read by morons. Things that were -considered to be self-evident were not discussed. So. Here we are. - -Case in point: The German version of Microsoft Exchange adds @samp{AW: -} to the subjects of replies instead of @samp{Re: }. I could pretend to -be shocked and dismayed by this, but I haven't got the energy. It is to -laugh. - -Gnus provides a plethora of functions for washing articles while -displaying them, but it might be nicer to do the filtering before -storing the mail to disk. For that purpose, we have three hooks and -various functions that can be put in these hooks. - -@table @code -@item nnmail-prepare-incoming-hook -@vindex nnmail-prepare-incoming-hook -This hook is called before doing anything with the mail and is meant for -grand, sweeping gestures. It is called in a buffer that contains all -the new, incoming mail. Functions to be used include: - -@table @code -@item nnheader-ms-strip-cr -@findex nnheader-ms-strip-cr -Remove trailing carriage returns from each line. This is default on -Emacs running on MS machines. - -@end table - -@item nnmail-prepare-incoming-header-hook -@vindex nnmail-prepare-incoming-header-hook -This hook is called narrowed to each header. It can be used when -cleaning up the headers. Functions that can be used include: - -@table @code -@item nnmail-remove-leading-whitespace -@findex nnmail-remove-leading-whitespace -Clear leading white space that ``helpful'' listservs have added to the -headers to make them look nice. Aaah. - -(Note that this function works on both the header on the body of all -messages, so it is a potentially dangerous function to use (if a body -of a message contains something that looks like a header line). So -rather than fix the bug, it is of course the right solution to make it -into a feature by documenting it.) - -@item nnmail-remove-list-identifiers -@findex nnmail-remove-list-identifiers -Some list servers add an identifier---for example, @samp{(idm)}---to the -beginning of all @code{Subject} headers. I'm sure that's nice for -people who use stone age mail readers. This function will remove -strings that match the @code{nnmail-list-identifiers} regexp, which can -also be a list of regexp. @code{nnmail-list-identifiers} may not contain -@code{\\(..\\)}. - -For instance, if you want to remove the @samp{(idm)} and the -@samp{nagnagnag} identifiers: - -@lisp -(setq nnmail-list-identifiers - '("(idm)" "nagnagnag")) -@end lisp - -This can also be done non-destructively with -@code{gnus-list-identifiers}, @xref{Article Hiding}. - -@item nnmail-remove-tabs -@findex nnmail-remove-tabs -Translate all @samp{TAB} characters into @samp{SPACE} characters. - -@item nnmail-ignore-broken-references -@findex nnmail-ignore-broken-references -@c @findex nnmail-fix-eudora-headers -@cindex Eudora -@cindex Pegasus -Some mail user agents (e.g. Eudora and Pegasus) produce broken -@code{References} headers, but correct @code{In-Reply-To} headers. This -function will get rid of the @code{References} header if the headers -contain a line matching the regular expression -@code{nnmail-broken-references-mailers}. - -@end table - -@item nnmail-prepare-incoming-message-hook -@vindex nnmail-prepare-incoming-message-hook -This hook is called narrowed to each message. Functions to be used -include: - -@table @code -@item article-de-quoted-unreadable -@findex article-de-quoted-unreadable -Decode Quoted Readable encoding. - -@end table -@end table - - -@node Duplicates -@subsection Duplicates - -@vindex nnmail-treat-duplicates -@vindex nnmail-message-id-cache-length -@vindex nnmail-message-id-cache-file -@cindex duplicate mails -If you are a member of a couple of mailing lists, you will sometimes -receive two copies of the same mail. This can be quite annoying, so -@code{nnmail} checks for and treats any duplicates it might find. To do -this, it keeps a cache of old @code{Message-ID}s--- -@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by -default. The approximate maximum number of @code{Message-ID}s stored -there is controlled by the @code{nnmail-message-id-cache-length} -variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be -stored.) If all this sounds scary to you, you can set -@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by -default), and @code{nnmail} won't delete duplicate mails. Instead it -will insert a warning into the head of the mail saying that it thinks -that this is a duplicate of a different message. - -This variable can also be a function. If that's the case, the function -will be called from a buffer narrowed to the message in question with -the @code{Message-ID} as a parameter. The function must return either -@code{nil}, @code{warn}, or @code{delete}. - -You can turn this feature off completely by setting the variable to -@code{nil}. - -If you want all the duplicate mails to be put into a special -@dfn{duplicates} group, you could do that using the normal mail split -methods: - -@lisp -(setq nnmail-split-fancy - '(| ;; @r{Messages duplicates go to a separate group.} - ("gnus-warning" "duplicat\\(e\\|ion\\) of message" "duplicate") - ;; @r{Message from daemons, postmaster, and the like to another.} - (any mail "mail.misc") - ;; @r{Other rules.} - [...] )) -@end lisp -@noindent -Or something like: -@lisp -(setq nnmail-split-methods - '(("duplicates" "^Gnus-Warning:.*duplicate") - ;; @r{Other rules.} - [...])) -@end lisp - -Here's a neat feature: If you know that the recipient reads her mail -with Gnus, and that she has @code{nnmail-treat-duplicates} set to -@code{delete}, you can send her as many insults as you like, just by -using a @code{Message-ID} of a mail that you know that she's already -received. Think of all the fun! She'll never see any of it! Whee! - - -@node Not Reading Mail -@subsection Not Reading Mail - -If you start using any of the mail back ends, they have the annoying -habit of assuming that you want to read mail with them. This might not -be unreasonable, but it might not be what you want. - -If you set @code{mail-sources} and @code{nnmail-spool-file} to -@code{nil}, none of the back ends will ever attempt to read incoming -mail, which should help. - -@vindex nnbabyl-get-new-mail -@vindex nnmbox-get-new-mail -@vindex nnml-get-new-mail -@vindex nnmh-get-new-mail -@vindex nnfolder-get-new-mail -This might be too much, if, for instance, you are reading mail quite -happily with @code{nnml} and just want to peek at some old (pre-Emacs -23) Rmail file you have stashed away with @code{nnbabyl}. All back ends have -variables called back-end-@code{get-new-mail}. If you want to disable -the @code{nnbabyl} mail reading, you edit the virtual server for the -group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. - -All the mail back ends will call @code{nn}*@code{-prepare-save-mail-hook} -narrowed to the article to be saved before saving it when reading -incoming mail. - - -@node Choosing a Mail Back End -@subsection Choosing a Mail Back End - -Gnus will read the mail spool when you activate a mail group. The mail -file is first copied to your home directory. What happens after that -depends on what format you want to store your mail in. - -There are six different mail back ends in the standard Gnus, and more -back ends are available separately. The mail back end most people use -(because it is possibly the fastest) is @code{nnml} (@pxref{Mail -Spool}). - -@menu -* Unix Mail Box:: Using the (quite) standard Un*x mbox. -* Babyl:: Babyl was used by older versions of Rmail. -* Mail Spool:: Store your mail in a private spool? -* MH Spool:: An mhspool-like back end. -* Maildir:: Another one-file-per-message format. -* Mail Folders:: Having one file for each group. -* Comparing Mail Back Ends:: An in-depth looks at pros and cons. -@end menu - - -@node Unix Mail Box -@subsubsection Unix Mail Box -@cindex nnmbox -@cindex unix mail box - -@vindex nnmbox-active-file -@vindex nnmbox-mbox-file -The @dfn{nnmbox} back end will use the standard Un*x mbox file to store -mail. @code{nnmbox} will add extra headers to each mail article to say -which group it belongs in. - -Virtual server settings: - -@table @code -@item nnmbox-mbox-file -@vindex nnmbox-mbox-file -The name of the mail box in the user's home directory. Default is -@file{~/mbox}. - -@item nnmbox-active-file -@vindex nnmbox-active-file -The name of the active file for the mail box. Default is -@file{~/.mbox-active}. - -@item nnmbox-get-new-mail -@vindex nnmbox-get-new-mail -If non-@code{nil}, @code{nnmbox} will read incoming mail and split it -into groups. Default is @code{t}. -@end table - - -@node Babyl -@subsubsection Babyl -@cindex nnbabyl - -@vindex nnbabyl-active-file -@vindex nnbabyl-mbox-file -The @dfn{nnbabyl} back end will use a Babyl mail box to store mail. -@code{nnbabyl} will add extra headers to each mail article to say which -group it belongs in. - -Virtual server settings: - -@table @code -@item nnbabyl-mbox-file -@vindex nnbabyl-mbox-file -The name of the Babyl file. The default is @file{~/RMAIL} - -@item nnbabyl-active-file -@vindex nnbabyl-active-file -The name of the active file for the Babyl file. The default is -@file{~/.rmail-active} - -@item nnbabyl-get-new-mail -@vindex nnbabyl-get-new-mail -If non-@code{nil}, @code{nnbabyl} will read incoming mail. Default is -@code{t} -@end table - - -@node Mail Spool -@subsubsection Mail Spool -@cindex nnml -@cindex mail @acronym{NOV} spool - -The @dfn{nnml} spool mail format isn't compatible with any other known -format. It should be used with some caution. - -@vindex nnml-directory -If you use this back end, Gnus will split all incoming mail into files, -one file for each mail, and put the articles into the corresponding -directories under the directory specified by the @code{nnml-directory} -variable. The default value is @file{~/Mail/}. - -You do not have to create any directories beforehand; Gnus will take -care of all that. - -If you have a strict limit as to how many files you are allowed to store -in your account, you should not use this back end. As each mail gets its -own file, you might very well occupy thousands of inodes within a few -weeks. If this is no problem for you, and it isn't a problem for you -having your friendly systems administrator walking around, madly, -shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should -know that this is probably the fastest format to use. You do not have -to trudge through a big mbox file just to read your new mail. - -@code{nnml} is probably the slowest back end when it comes to article -splitting. It has to create lots of files, and it also generates -@acronym{NOV} databases for the incoming mails. This makes it possibly the -fastest back end when it comes to reading mail. - -@cindex self contained nnml servers -@cindex marks -When the marks file is used (which it is by default), @code{nnml} -servers have the property that you may backup them using @code{tar} or -similar, and later be able to restore them into Gnus (by adding the -proper @code{nnml} server) and have all your marks be preserved. Marks -for a group are usually stored in the @code{.marks} file (but see -@code{nnml-marks-file-name}) within each @code{nnml} group's directory. -Individual @code{nnml} groups are also possible to backup, use @kbd{G m} -to restore the group (after restoring the backup into the nnml -directory). - -If for some reason you believe your @file{.marks} files are screwed -up, you can just delete them all. Gnus will then correctly regenerate -them next time it starts. - -Virtual server settings: - -@table @code -@item nnml-directory -@vindex nnml-directory -All @code{nnml} directories will be placed under this directory. The -default is the value of @code{message-directory} (whose default value -is @file{~/Mail}). - -@item nnml-active-file -@vindex nnml-active-file -The active file for the @code{nnml} server. The default is -@file{~/Mail/active}. - -@item nnml-newsgroups-file -@vindex nnml-newsgroups-file -The @code{nnml} group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups}. - -@item nnml-get-new-mail -@vindex nnml-get-new-mail -If non-@code{nil}, @code{nnml} will read incoming mail. The default is -@code{t}. - -@item nnml-nov-is-evil -@vindex nnml-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnml-nov-file-name -@vindex nnml-nov-file-name -The name of the @acronym{NOV} files. The default is @file{.overview}. - -@item nnml-prepare-save-mail-hook -@vindex nnml-prepare-save-mail-hook -Hook run narrowed to an article before saving. - -@item nnml-marks-is-evil -@vindex nnml-marks-is-evil -If non-@code{nil}, this back end will ignore any @sc{marks} files. The -default is @code{nil}. - -@item nnml-marks-file-name -@vindex nnml-marks-file-name -The name of the @dfn{marks} files. The default is @file{.marks}. - -@item nnml-use-compressed-files -@vindex nnml-use-compressed-files -If non-@code{nil}, @code{nnml} will allow using compressed message -files. This requires @code{auto-compression-mode} to be enabled -(@pxref{Compressed Files, ,Compressed Files, emacs, The Emacs Manual}). -If the value of @code{nnml-use-compressed-files} is a string, it is used -as the file extension specifying the compression program. You can set it -to @samp{.bz2} if your Emacs supports it. A value of @code{t} is -equivalent to @samp{.gz}. - -@item nnml-compressed-files-size-threshold -@vindex nnml-compressed-files-size-threshold -Default size threshold for compressed message files. Message files with -bodies larger than that many characters will be automatically compressed -if @code{nnml-use-compressed-files} is non-@code{nil}. - -@end table - -@findex nnml-generate-nov-databases -If your @code{nnml} groups and @acronym{NOV} files get totally out of -whack, you can do a complete update by typing @kbd{M-x -nnml-generate-nov-databases}. This command will trawl through the -entire @code{nnml} hierarchy, looking at each and every article, so it -might take a while to complete. A better interface to this -functionality can be found in the server buffer (@pxref{Server -Commands}). - - -@node MH Spool -@subsubsection MH Spool -@cindex nnmh -@cindex mh-e mail spool - -@code{nnmh} is just like @code{nnml}, except that is doesn't generate -@acronym{NOV} databases and it doesn't keep an active file or marks -file. This makes @code{nnmh} a @emph{much} slower back end than -@code{nnml}, but it also makes it easier to write procmail scripts -for. - -Virtual server settings: - -@table @code -@item nnmh-directory -@vindex nnmh-directory -All @code{nnmh} directories will be located under this directory. The -default is the value of @code{message-directory} (whose default is -@file{~/Mail}) - -@item nnmh-get-new-mail -@vindex nnmh-get-new-mail -If non-@code{nil}, @code{nnmh} will read incoming mail. The default is -@code{t}. - -@item nnmh-be-safe -@vindex nnmh-be-safe -If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make -sure that the articles in the folder are actually what Gnus thinks -they are. It will check date stamps and stat everything in sight, so -setting this to @code{t} will mean a serious slow-down. If you never -use anything but Gnus to read the @code{nnmh} articles, you do not -have to set this variable to @code{t}. The default is @code{nil}. -@end table - - -@node Maildir -@subsubsection Maildir -@cindex nnmaildir -@cindex maildir - -@code{nnmaildir} stores mail in the maildir format, with each maildir -corresponding to a group in Gnus. This format is documented here: -@uref{http://cr.yp.to/proto/maildir.html} and here: -@uref{http://www.qmail.org/man/man5/maildir.html}. @code{nnmaildir} -also stores extra information in the @file{.nnmaildir/} directory -within a maildir. - -Maildir format was designed to allow concurrent deliveries and -reading, without needing locks. With other back ends, you would have -your mail delivered to a spool of some kind, and then you would -configure Gnus to split mail from that spool into your groups. You -can still do that with @code{nnmaildir}, but the more common -configuration is to have your mail delivered directly to the maildirs -that appear as group in Gnus. - -@code{nnmaildir} is designed to be perfectly reliable: @kbd{C-g} will -never corrupt its data in memory, and @code{SIGKILL} will never -corrupt its data in the filesystem. - -@code{nnmaildir} stores article marks and @acronym{NOV} data in each -maildir. So you can copy a whole maildir from one Gnus setup to -another, and you will keep your marks. - -Virtual server settings: - -@table @code -@item directory -For each of your @code{nnmaildir} servers (it's very unlikely that -you'd need more than one), you need to create a directory and populate -it with maildirs or symlinks to maildirs (and nothing else; do not -choose a directory already used for other purposes). Each maildir -will be represented in Gnus as a newsgroup on that server; the -filename of the symlink will be the name of the group. Any filenames -in the directory starting with @samp{.} are ignored. The directory is -scanned when you first start Gnus, and each time you type @kbd{g} in -the group buffer; if any maildirs have been removed or added, -@code{nnmaildir} notices at these times. - -The value of the @code{directory} parameter should be a Lisp form -which is processed by @code{eval} and @code{expand-file-name} to get -the path of the directory for this server. The form is @code{eval}ed -only when the server is opened; the resulting string is used until the -server is closed. (If you don't know about forms and @code{eval}, -don't worry---a simple string will work.) This parameter is not -optional; you must specify it. I don't recommend using -@code{"~/Mail"} or a subdirectory of it; several other parts of Gnus -use that directory by default for various things, and may get confused -if @code{nnmaildir} uses it too. @code{"~/.nnmaildir"} is a typical -value. - -@item target-prefix -This should be a Lisp form which is processed by @code{eval} and -@code{expand-file-name}. The form is @code{eval}ed only when the -server is opened; the resulting string is used until the server is -closed. - -When you create a group on an @code{nnmaildir} server, the maildir is -created with @code{target-prefix} prepended to its name, and a symlink -pointing to that maildir is created, named with the plain group name. -So if @code{directory} is @code{"~/.nnmaildir"} and -@code{target-prefix} is @code{"../maildirs/"}, then when you create -the group @code{foo}, @code{nnmaildir} will create -@file{~/.nnmaildir/../maildirs/foo} as a maildir, and will create -@file{~/.nnmaildir/foo} as a symlink pointing to -@file{../maildirs/foo}. - -You can set @code{target-prefix} to a string without any slashes to -create both maildirs and symlinks in the same @code{directory}; in -this case, any maildirs found in @code{directory} whose names start -with @code{target-prefix} will not be listed as groups (but the -symlinks pointing to them will be). - -As a special case, if @code{target-prefix} is @code{""} (the default), -then when you create a group, the maildir will be created in -@code{directory} without a corresponding symlink. Beware that you -cannot use @code{gnus-group-delete-group} on such groups without the -@code{force} argument. - -@item directory-files -This should be a function with the same interface as -@code{directory-files} (such as @code{directory-files} itself). It is -used to scan the server's @code{directory} for maildirs. This -parameter is optional; the default is -@code{nnheader-directory-files-safe} if -@code{nnheader-directory-files-is-safe} is @code{nil}, and -@code{directory-files} otherwise. -(@code{nnheader-directory-files-is-safe} is checked only once when the -server is opened; if you want to check it each time the directory is -scanned, you'll have to provide your own function that does that.) - -@item get-new-mail -If non-@code{nil}, then after scanning for new mail in the group -maildirs themselves as usual, this server will also incorporate mail -the conventional Gnus way, from @code{mail-sources} according to -@code{nnmail-split-methods} or @code{nnmail-split-fancy}. The default -value is @code{nil}. - -Do @emph{not} use the same maildir both in @code{mail-sources} and as -an @code{nnmaildir} group. The results might happen to be useful, but -that would be by chance, not by design, and the results might be -different in the future. If your split rules create new groups, -remember to supply a @code{create-directory} server parameter. -@end table - -@subsubsection Group parameters - -@code{nnmaildir} uses several group parameters. It's safe to ignore -all this; the default behavior for @code{nnmaildir} is the same as the -default behavior for other mail back ends: articles are deleted after -one week, etc. Except for the expiry parameters, all this -functionality is unique to @code{nnmaildir}, so you can ignore it if -you're just trying to duplicate the behavior you already have with -another back end. - -If the value of any of these parameters is a vector, the first element -is evaluated as a Lisp form and the result is used, rather than the -original value. If the value is not a vector, the value itself is -evaluated as a Lisp form. (This is why these parameters use names -different from those of other, similar parameters supported by other -back ends: they have different, though similar, meanings.) (For -numbers, strings, @code{nil}, and @code{t}, you can ignore the -@code{eval} business again; for other values, remember to use an extra -quote and wrap the value in a vector when appropriate.) - -@table @code -@item expire-age -An integer specifying the minimum age, in seconds, of an article -before it will be expired, or the symbol @code{never} to specify that -articles should never be expired. If this parameter is not set, -@code{nnmaildir} falls back to the usual -@code{nnmail-expiry-wait}(@code{-function}) variables (the -@code{expiry-wait} group parameter overrides @code{nnmail-expiry-wait} -and makes @code{nnmail-expiry-wait-function} ineffective). If you -wanted a value of 3 days, you could use something like @code{[(* 3 24 -60 60)]}; @code{nnmaildir} will evaluate the form and use the result. -An article's age is measured starting from the article file's -modification time. Normally, this is the same as the article's -delivery time, but editing an article makes it younger. Moving an -article (other than via expiry) may also make an article younger. - -@item expire-group -If this is set to a string such as a full Gnus group name, like -@example -"backend+server.address.string:group.name" -@end example -and if it is not the name of the same group that the parameter belongs -to, then articles will be moved to the specified group during expiry -before being deleted. @emph{If this is set to an @code{nnmaildir} -group, the article will be just as old in the destination group as it -was in the source group.} So be careful with @code{expire-age} in the -destination group. If this is set to the name of the same group that -the parameter belongs to, then the article is not expired at all. If -you use the vector form, the first element is evaluated once for each -article. So that form can refer to -@code{nnmaildir-article-file-name}, etc., to decide where to put the -article. @emph{Even if this parameter is not set, @code{nnmaildir} -does not fall back to the @code{expiry-target} group parameter or the -@code{nnmail-expiry-target} variable.} - -@item read-only -If this is set to @code{t}, @code{nnmaildir} will treat the articles -in this maildir as read-only. This means: articles are not renamed -from @file{new/} into @file{cur/}; articles are only found in -@file{new/}, not @file{cur/}; articles are never deleted; articles -cannot be edited. @file{new/} is expected to be a symlink to the -@file{new/} directory of another maildir---e.g., a system-wide mailbox -containing a mailing list of common interest. Everything in the -maildir outside @file{new/} is @emph{not} treated as read-only, so for -a shared mailbox, you do still need to set up your own maildir (or -have write permission to the shared mailbox); your maildir just won't -contain extra copies of the articles. - -@item directory-files -A function with the same interface as @code{directory-files}. It is -used to scan the directories in the maildir corresponding to this -group to find articles. The default is the function specified by the -server's @code{directory-files} parameter. - -@item distrust-Lines: -If non-@code{nil}, @code{nnmaildir} will always count the lines of an -article, rather than use the @code{Lines:} header field. If -@code{nil}, the header field will be used if present. - -@item always-marks -A list of mark symbols, such as @code{['(read expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that all articles have these marks, regardless of whether the -marks stored in the filesystem say so. This is a proof-of-concept -feature that will probably be removed eventually; it ought to be done -in Gnus proper, or abandoned if it's not worthwhile. - -@item never-marks -A list of mark symbols, such as @code{['(tick expire)]}. Whenever -Gnus asks @code{nnmaildir} for article marks, @code{nnmaildir} will -say that no articles have these marks, regardless of whether the marks -stored in the filesystem say so. @code{never-marks} overrides -@code{always-marks}. This is a proof-of-concept feature that will -probably be removed eventually; it ought to be done in Gnus proper, or -abandoned if it's not worthwhile. - -@item nov-cache-size -An integer specifying the size of the @acronym{NOV} memory cache. To -speed things up, @code{nnmaildir} keeps @acronym{NOV} data in memory -for a limited number of articles in each group. (This is probably not -worthwhile, and will probably be removed in the future.) This -parameter's value is noticed only the first time a group is seen after -the server is opened---i.e., when you first start Gnus, typically. -The @acronym{NOV} cache is never resized until the server is closed -and reopened. The default is an estimate of the number of articles -that would be displayed in the summary buffer: a count of articles -that are either marked with @code{tick} or not marked with -@code{read}, plus a little extra. -@end table - -@subsubsection Article identification -Articles are stored in the @file{cur/} subdirectory of each maildir. -Each article file is named like @code{uniq:info}, where @code{uniq} -contains no colons. @code{nnmaildir} ignores, but preserves, the -@code{:info} part. (Other maildir readers typically use this part of -the filename to store marks.) The @code{uniq} part uniquely -identifies the article, and is used in various places in the -@file{.nnmaildir/} subdirectory of the maildir to store information -about the corresponding article. The full pathname of an article is -available in the variable @code{nnmaildir-article-file-name} after you -request the article in the summary buffer. - -@subsubsection NOV data -An article identified by @code{uniq} has its @acronym{NOV} data (used -to generate lines in the summary buffer) stored in -@code{.nnmaildir/nov/uniq}. There is no -@code{nnmaildir-generate-nov-databases} function. (There isn't much -need for it---an article's @acronym{NOV} data is updated automatically -when the article or @code{nnmail-extra-headers} has changed.) You can -force @code{nnmaildir} to regenerate the @acronym{NOV} data for a -single article simply by deleting the corresponding @acronym{NOV} -file, but @emph{beware}: this will also cause @code{nnmaildir} to -assign a new article number for this article, which may cause trouble -with @code{seen} marks, the Agent, and the cache. - -@subsubsection Article marks -An article identified by @code{uniq} is considered to have the mark -@code{flag} when the file @file{.nnmaildir/marks/flag/uniq} exists. -When Gnus asks @code{nnmaildir} for a group's marks, @code{nnmaildir} -looks for such files and reports the set of marks it finds. When Gnus -asks @code{nnmaildir} to store a new set of marks, @code{nnmaildir} -creates and deletes the corresponding files as needed. (Actually, -rather than create a new file for each mark, it just creates hard -links to @file{.nnmaildir/markfile}, to save inodes.) - -You can invent new marks by creating a new directory in -@file{.nnmaildir/marks/}. You can tar up a maildir and remove it from -your server, untar it later, and keep your marks. You can add and -remove marks yourself by creating and deleting mark files. If you do -this while Gnus is running and your @code{nnmaildir} server is open, -it's best to exit all summary buffers for @code{nnmaildir} groups and -type @kbd{s} in the group buffer first, and to type @kbd{g} or -@kbd{M-g} in the group buffer afterwards. Otherwise, Gnus might not -pick up the changes, and might undo them. - - -@node Mail Folders -@subsubsection Mail Folders -@cindex nnfolder -@cindex mbox folders -@cindex mail folders - -@code{nnfolder} is a back end for storing each mail group in a -separate file. Each file is in the standard Un*x mbox format. -@code{nnfolder} will add extra headers to keep track of article -numbers and arrival dates. - -@cindex self contained nnfolder servers -@cindex marks -When the marks file is used (which it is by default), @code{nnfolder} -servers have the property that you may backup them using @code{tar} or -similar, and later be able to restore them into Gnus (by adding the -proper @code{nnfolder} server) and have all your marks be preserved. -Marks for a group are usually stored in a file named as the mbox file -with @code{.mrk} concatenated to it (but see -@code{nnfolder-marks-file-suffix}) within the @code{nnfolder} -directory. Individual @code{nnfolder} groups are also possible to -backup, use @kbd{G m} to restore the group (after restoring the backup -into the @code{nnfolder} directory). - -Virtual server settings: - -@table @code -@item nnfolder-directory -@vindex nnfolder-directory -All the @code{nnfolder} mail boxes will be stored under this -directory. The default is the value of @code{message-directory} -(whose default is @file{~/Mail}) - -@item nnfolder-active-file -@vindex nnfolder-active-file -The name of the active file. The default is @file{~/Mail/active}. - -@item nnfolder-newsgroups-file -@vindex nnfolder-newsgroups-file -The name of the group descriptions file. @xref{Newsgroups File -Format}. The default is @file{~/Mail/newsgroups} - -@item nnfolder-get-new-mail -@vindex nnfolder-get-new-mail -If non-@code{nil}, @code{nnfolder} will read incoming mail. The -default is @code{t} - -@item nnfolder-save-buffer-hook -@vindex nnfolder-save-buffer-hook -@cindex backup files -Hook run before saving the folders. Note that Emacs does the normal -backup renaming of files even with the @code{nnfolder} buffers. If -you wish to switch this off, you could say something like the -following in your @file{.emacs} file: - -@lisp -(defun turn-off-backup () - (set (make-local-variable 'backup-inhibited) t)) - -(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) -@end lisp - -@item nnfolder-delete-mail-hook -@vindex nnfolder-delete-mail-hook -Hook run in a buffer narrowed to the message that is to be deleted. -This function can be used to copy the message to somewhere else, or to -extract some information from it before removing it. - -@item nnfolder-nov-is-evil -@vindex nnfolder-nov-is-evil -If non-@code{nil}, this back end will ignore any @acronym{NOV} files. The -default is @code{nil}. - -@item nnfolder-nov-file-suffix -@vindex nnfolder-nov-file-suffix -The extension for @acronym{NOV} files. The default is @file{.nov}. - -@item nnfolder-nov-directory -@vindex nnfolder-nov-directory -The directory where the @acronym{NOV} files should be stored. If -@code{nil}, @code{nnfolder-directory} is used. - -@item nnfolder-marks-is-evil -@vindex nnfolder-marks-is-evil -If non-@code{nil}, this back end will ignore any @sc{marks} files. The -default is @code{nil}. - -@item nnfolder-marks-file-suffix -@vindex nnfolder-marks-file-suffix -The extension for @sc{marks} files. The default is @file{.mrk}. - -@item nnfolder-marks-directory -@vindex nnfolder-marks-directory -The directory where the @sc{marks} files should be stored. If -@code{nil}, @code{nnfolder-directory} is used. - -@end table - - -@findex nnfolder-generate-active-file -@kindex M-x nnfolder-generate-active-file -If you have lots of @code{nnfolder}-like files you'd like to read with -@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} -command to make @code{nnfolder} aware of all likely files in -@code{nnfolder-directory}. This only works if you use long file names, -though. - -@node Comparing Mail Back Ends -@subsubsection Comparing Mail Back Ends - -First, just for terminology, the @dfn{back end} is the common word for a -low-level access method---a transport, if you will, by which something -is acquired. The sense is that one's mail has to come from somewhere, -and so selection of a suitable back end is required in order to get that -mail within spitting distance of Gnus. - -The same concept exists for Usenet itself: Though access to articles is -typically done by @acronym{NNTP} these days, once upon a midnight dreary, everyone -in the world got at Usenet by running a reader on the machine where the -articles lay (the machine which today we call an @acronym{NNTP} server), and -access was by the reader stepping into the articles' directory spool -area directly. One can still select between either the @code{nntp} or -@code{nnspool} back ends, to select between these methods, if one happens -actually to live on the server (or can see its spool directly, anyway, -via NFS). - -The goal in selecting a mail back end is to pick one which -simultaneously represents a suitable way of dealing with the original -format plus leaving mail in a form that is convenient to use in the -future. Here are some high and low points on each: - -@table @code -@item nnmbox - -UNIX systems have historically had a single, very common, and well- -defined format. All messages arrive in a single @dfn{spool file}, and -they are delineated by a line whose regular expression matches -@samp{^From_}. (My notational use of @samp{_} is to indicate a space, -to make it clear in this instance that this is not the RFC-specified -@samp{From:} header.) Because Emacs and therefore Gnus emanate -historically from the Unix environment, it is simplest if one does not -mess a great deal with the original mailbox format, so if one chooses -this back end, Gnus' primary activity in getting mail from the real spool -area to Gnus' preferred directory is simply to copy it, with no -(appreciable) format change in the process. It is the ``dumbest'' way -to move mail into availability in the Gnus environment. This makes it -fast to move into place, but slow to parse, when Gnus has to look at -what's where. - -@item nnbabyl - -Once upon a time, there was the DEC-10 and DEC-20, running operating -systems called TOPS and related things, and the usual (only?) mail -reading environment was a thing called Babyl. I don't know what format -was used for mail landing on the system, but Babyl had its own internal -format to which mail was converted, primarily involving creating a -spool-file-like entity with a scheme for inserting Babyl-specific -headers and status bits above the top of each message in the file. -Rmail was Emacs' first mail reader, it was written by Richard Stallman, -and Stallman came out of that TOPS/Babyl environment, so he wrote Rmail -to understand the mail files folks already had in existence. Gnus (and -VM, for that matter) continue to support this format because it's -perceived as having some good qualities in those mailer-specific -headers/status bits stuff. Rmail itself still exists as well, of -course, and is still maintained within Emacs. Since Emacs 23, it -uses standard mbox format rather than Babyl. - -Both of the above forms leave your mail in a single file on your -file system, and they must parse that entire file each time you take a -look at your mail. - -@item nnml - -@code{nnml} is the back end which smells the most as though you were -actually operating with an @code{nnspool}-accessed Usenet system. (In -fact, I believe @code{nnml} actually derived from @code{nnspool} code, -lo these years ago.) One's mail is taken from the original spool file, -and is then cut up into individual message files, 1:1. It maintains a -Usenet-style active file (analogous to what one finds in an INN- or -CNews-based news system in (for instance) @file{/var/lib/news/active}, -or what is returned via the @samp{NNTP LIST} verb) and also creates -@dfn{overview} files for efficient group entry, as has been defined for -@acronym{NNTP} servers for some years now. It is slower in mail-splitting, -due to the creation of lots of files, updates to the @code{nnml} active -file, and additions to overview files on a per-message basis, but it is -extremely fast on access because of what amounts to the indexing support -provided by the active file and overviews. - -@code{nnml} costs @dfn{inodes} in a big way; that is, it soaks up the -resource which defines available places in the file system to put new -files. Sysadmins take a dim view of heavy inode occupation within -tight, shared file systems. But if you live on a personal machine where -the file system is your own and space is not at a premium, @code{nnml} -wins big. - -It is also problematic using this back end if you are living in a -FAT16-based Windows world, since much space will be wasted on all these -tiny files. - -@item nnmh - -The Rand MH mail-reading system has been around UNIX systems for a very -long time; it operates by splitting one's spool file of messages into -individual files, but with little or no indexing support---@code{nnmh} -is considered to be semantically equivalent to ``@code{nnml} without -active file or overviews''. This is arguably the worst choice, because -one gets the slowness of individual file creation married to the -slowness of access parsing when learning what's new in one's groups. - -@item nnfolder - -Basically the effect of @code{nnfolder} is @code{nnmbox} (the first -method described above) on a per-group basis. That is, @code{nnmbox} -itself puts @emph{all} one's mail in one file; @code{nnfolder} provides a -little bit of optimization to this so that each of one's mail groups has -a Unix mail box file. It's faster than @code{nnmbox} because each group -can be parsed separately, and still provides the simple Unix mail box -format requiring minimal effort in moving the mail around. In addition, -it maintains an ``active'' file making it much faster for Gnus to figure -out how many messages there are in each separate group. - -If you have groups that are expected to have a massive amount of -messages, @code{nnfolder} is not the best choice, but if you receive -only a moderate amount of mail, @code{nnfolder} is probably the most -friendly mail back end all over. - -@item nnmaildir - -For configuring expiry and other things, @code{nnmaildir} uses -incompatible group parameters, slightly different from those of other -mail back ends. - -@code{nnmaildir} is largely similar to @code{nnml}, with some notable -differences. Each message is stored in a separate file, but the -filename is unrelated to the article number in Gnus. @code{nnmaildir} -also stores the equivalent of @code{nnml}'s overview files in one file -per article, so it uses about twice as many inodes as @code{nnml}. (Use -@code{df -i} to see how plentiful your inode supply is.) If this slows -you down or takes up very much space, consider switching to -@uref{http://www.namesys.com/, ReiserFS} or another non-block-structured -file system. - -Since maildirs don't require locking for delivery, the maildirs you use -as groups can also be the maildirs your mail is directly delivered to. -This means you can skip Gnus' mail splitting if your mail is already -organized into different mailboxes during delivery. A @code{directory} -entry in @code{mail-sources} would have a similar effect, but would -require one set of mailboxes for spooling deliveries (in mbox format, -thus damaging message bodies), and another set to be used as groups (in -whatever format you like). A maildir has a built-in spool, in the -@code{new/} subdirectory. Beware that currently, mail moved from -@code{new/} to @code{cur/} instead of via mail splitting will not -undergo treatment such as duplicate checking. - -@code{nnmaildir} stores article marks for a given group in the -corresponding maildir, in a way designed so that it's easy to manipulate -them from outside Gnus. You can tar up a maildir, unpack it somewhere -else, and still have your marks. @code{nnml} also stores marks, but -it's not as easy to work with them from outside Gnus as with -@code{nnmaildir}. - -@code{nnmaildir} uses a significant amount of memory to speed things up. -(It keeps in memory some of the things that @code{nnml} stores in files -and that @code{nnmh} repeatedly parses out of message files.) If this -is a problem for you, you can set the @code{nov-cache-size} group -parameter to something small (0 would probably not work, but 1 probably -would) to make it use less memory. This caching will probably be -removed in the future. - -Startup is likely to be slower with @code{nnmaildir} than with other -back ends. Everything else is likely to be faster, depending in part -on your file system. - -@code{nnmaildir} does not use @code{nnoo}, so you cannot use @code{nnoo} -to write an @code{nnmaildir}-derived back end. - -@end table - - -@node Browsing the Web -@section Browsing the Web -@cindex web -@cindex browsing the web -@cindex www -@cindex http - -Web-based discussion forums are getting more and more popular. On many -subjects, the web-based forums have become the most important forums, -eclipsing the importance of mailing lists and news groups. The reason -is easy to understand---they are friendly to new users; you just point -and click, and there's the discussion. With mailing lists, you have to -go through a cumbersome subscription procedure, and most people don't -even know what a news group is. - -The problem with this scenario is that web browsers are not very good at -being newsreaders. They do not keep track of what articles you've read; -they do not allow you to score on subjects you're interested in; they do -not allow off-line browsing; they require you to click around and drive -you mad in the end. - -So---if web browsers suck at reading discussion forums, why not use Gnus -to do it instead? - -Gnus has been getting a bit of a collection of back ends for providing -interfaces to these sources. - -@menu -* Archiving Mail:: -* Web Searches:: Creating groups from articles that match a string. -* Slashdot:: Reading the Slashdot comments. -* Ultimate:: The Ultimate Bulletin Board systems. -* Web Archive:: Reading mailing list archived on web. -* RSS:: Reading RDF site summary. -* Customizing W3:: Doing stuff to Emacs/W3 from Gnus. -@end menu - -All the web sources require Emacs/W3 and the url library or those -alternatives to work. - -The main caveat with all these web sources is that they probably won't -work for a very long time. Gleaning information from the @acronym{HTML} data -is guesswork at best, and when the layout is altered, the Gnus back end -will fail. If you have reasonably new versions of these back ends, -though, you should be ok. - -One thing all these Web methods have in common is that the Web sources -are often down, unavailable or just plain too slow to be fun. In those -cases, it makes a lot of sense to let the Gnus Agent (@pxref{Gnus -Unplugged}) handle downloading articles, and then you can read them at -leisure from your local disk. No more World Wide Wait for you. - -@node Archiving Mail -@subsection Archiving Mail -@cindex archiving mail -@cindex backup of mail - -Some of the back ends, notably @code{nnml}, @code{nnfolder}, and -@code{nnmaildir}, now actually store the article marks with each group. -For these servers, archiving and restoring a group while preserving -marks is fairly simple. - -(Preserving the group level and group parameters as well still -requires ritual dancing and sacrifices to the @file{.newsrc.eld} deity -though.) - -To archive an entire @code{nnml}, @code{nnfolder}, or @code{nnmaildir} -server, take a recursive copy of the server directory. There is no need -to shut down Gnus, so archiving may be invoked by @code{cron} or -similar. You restore the data by restoring the directory tree, and -adding a server definition pointing to that directory in Gnus. The -@ref{Article Backlog}, @ref{Asynchronous Fetching} and other things -might interfere with overwriting data, so you may want to shut down Gnus -before you restore the data. - -It is also possible to archive individual @code{nnml}, -@code{nnfolder}, or @code{nnmaildir} groups, while preserving marks. -For @code{nnml} or @code{nnmaildir}, you copy all files in the group's -directory. For @code{nnfolder} you need to copy both the base folder -file itself (@file{FOO}, say), and the marks file (@file{FOO.mrk} in -this example). Restoring the group is done with @kbd{G m} from the Group -buffer. The last step makes Gnus notice the new directory. -@code{nnmaildir} notices the new directory automatically, so @kbd{G m} -is unnecessary in that case. - -@node Web Searches -@subsection Web Searches -@cindex nnweb -@cindex Google -@cindex dejanews -@cindex gmane -@cindex Usenet searches -@cindex searching the Usenet - -It's, like, too neat to search the Usenet for articles that match a -string, but it, like, totally @emph{sucks}, like, totally, to use one of -those, like, Web browsers, and you, like, have to, rilly, like, look at -the commercials, so, like, with Gnus you can do @emph{rad}, rilly, -searches without having to use a browser. - -The @code{nnweb} back end allows an easy interface to the mighty search -engine. You create an @code{nnweb} group, enter a search pattern, and -then enter the group and read the articles like you would any normal -group. The @kbd{G w} command in the group buffer (@pxref{Foreign -Groups}) will do this in an easy-to-use fashion. - -@code{nnweb} groups don't really lend themselves to being solid -groups---they have a very fleeting idea of article numbers. In fact, -each time you enter an @code{nnweb} group (not even changing the search -pattern), you are likely to get the articles ordered in a different -manner. Not even using duplicate suppression (@pxref{Duplicate -Suppression}) will help, since @code{nnweb} doesn't even know the -@code{Message-ID} of the articles before reading them using some search -engines (Google, for instance). The only possible way to keep track -of which articles you've read is by scoring on the @code{Date} -header---mark all articles posted before the last date you read the -group as read. - -If the search engine changes its output substantially, @code{nnweb} -won't be able to parse it and will fail. One could hardly fault the Web -providers if they were to do this---their @emph{raison d'@^etre} is to -make money off of advertisements, not to provide services to the -community. Since @code{nnweb} washes the ads off all the articles, one -might think that the providers might be somewhat miffed. We'll see. - -You must have the @code{url} and @code{W3} package or those alternatives -(try @code{customize-group} on the @samp{mm-url} variable group) -installed to be able to use @code{nnweb}. - -Virtual server variables: - -@table @code -@item nnweb-type -@vindex nnweb-type -What search engine type is being used. The currently supported types -are @code{google}, @code{dejanews}, and @code{gmane}. Note that -@code{dejanews} is an alias to @code{google}. - -@item nnweb-search -@vindex nnweb-search -The search string to feed to the search engine. - -@item nnweb-max-hits -@vindex nnweb-max-hits -Advisory maximum number of hits per search to display. The default is -999. - -@item nnweb-type-definition -@vindex nnweb-type-definition -Type-to-definition alist. This alist says what @code{nnweb} should do -with the various search engine types. The following elements must be -present: - -@table @code -@item article -Function to decode the article and provide something that Gnus -understands. - -@item map -Function to create an article number to message header and URL alist. - -@item search -Function to send the search string to the search engine. - -@item address -The address the aforementioned function should send the search string -to. - -@item id -Format string URL to fetch an article by @code{Message-ID}. -@end table - -@end table - - -@node Slashdot -@subsection Slashdot -@cindex Slashdot -@cindex nnslashdot - -@uref{http://slashdot.org/, Slashdot} is a popular news site, with -lively discussion following the news articles. @code{nnslashdot} will -let you read this forum in a convenient manner. - -The easiest way to read this source is to put something like the -following in your @file{~/.gnus.el} file: - -@lisp -(setq gnus-secondary-select-methods - '((nnslashdot ""))) -@end lisp - -This will make Gnus query the @code{nnslashdot} back end for new comments -and groups. The @kbd{F} command will subscribe each new news article as -a new Gnus group, and you can read the comments by entering these -groups. (Note that the default subscription method is to subscribe new -groups as zombies. Other methods are available (@pxref{Subscription -Methods}). - -If you want to remove an old @code{nnslashdot} group, the @kbd{G DEL} -command is the most handy tool (@pxref{Foreign Groups}). - -When following up to @code{nnslashdot} comments (or posting new -comments), some light @acronym{HTML}izations will be performed. In -particular, text quoted with @samp{> } will be quoted with -@samp{blockquote} instead, and signatures will have @samp{br} added to -the end of each line. Other than that, you can just write @acronym{HTML} -directly into the message buffer. Note that Slashdot filters out some -@acronym{HTML} forms. - -The following variables can be altered to change its behavior: - -@table @code -@item nnslashdot-threaded -Whether @code{nnslashdot} should display threaded groups or not. The -default is @code{t}. To be able to display threads, @code{nnslashdot} -has to retrieve absolutely all comments in a group upon entry. If a -threaded display is not required, @code{nnslashdot} will only retrieve -the comments that are actually wanted by the user. Threading is nicer, -but much, much slower than unthreaded. - -@item nnslashdot-login-name -@vindex nnslashdot-login-name -The login name to use when posting. - -@item nnslashdot-password -@vindex nnslashdot-password -The password to use when posting. - -@item nnslashdot-directory -@vindex nnslashdot-directory -Where @code{nnslashdot} will store its files. The default is -@file{~/News/slashdot/}. - -@item nnslashdot-active-url -@vindex nnslashdot-active-url -The @acronym{URL} format string that will be used to fetch the -information on news articles and comments. The default is@* -@samp{http://slashdot.org/search.pl?section=&min=%d}. - -@item nnslashdot-comments-url -@vindex nnslashdot-comments-url -The @acronym{URL} format string that will be used to fetch comments. - -@item nnslashdot-article-url -@vindex nnslashdot-article-url -The @acronym{URL} format string that will be used to fetch the news -article. The default is -@samp{http://slashdot.org/article.pl?sid=%s&mode=nocomment}. - -@item nnslashdot-threshold -@vindex nnslashdot-threshold -The score threshold. The default is -1. - -@item nnslashdot-group-number -@vindex nnslashdot-group-number -The number of old groups, in addition to the ten latest, to keep -updated. The default is 0. - -@end table - - - -@node Ultimate -@subsection Ultimate -@cindex nnultimate -@cindex Ultimate Bulletin Board - -@uref{http://www.ultimatebb.com/, The Ultimate Bulletin Board} is -probably the most popular Web bulletin board system used. It has a -quite regular and nice interface, and it's possible to get the -information Gnus needs to keep groups updated. - -The easiest way to get started with @code{nnultimate} is to say -something like the following in the group buffer: @kbd{B nnultimate RET -http://www.tcj.com/messboard/ubbcgi/ RET}. (Substitute the @acronym{URL} -(not including @samp{Ultimate.cgi} or the like at the end) for a forum -you're interested in; there's quite a list of them on the Ultimate web -site.) Then subscribe to the groups you're interested in from the -server buffer, and read them from the group buffer. - -The following @code{nnultimate} variables can be altered: - -@table @code -@item nnultimate-directory -@vindex nnultimate-directory -The directory where @code{nnultimate} stores its files. The default is@* -@file{~/News/ultimate/}. -@end table - - -@node Web Archive -@subsection Web Archive -@cindex nnwarchive -@cindex Web Archive - -Some mailing lists only have archives on Web servers, such as -@uref{http://www.egroups.com/} and -@uref{http://www.mail-archive.com/}. It has a quite regular and nice -interface, and it's possible to get the information Gnus needs to keep -groups updated. - -@findex gnus-group-make-warchive-group -The easiest way to get started with @code{nnwarchive} is to say -something like the following in the group buffer: @kbd{M-x -gnus-group-make-warchive-group RET @var{an_egroup} RET egroups RET -www.egroups.com RET @var{your@@email.address} RET}. (Substitute the -@var{an_egroup} with the mailing list you subscribed, the -@var{your@@email.address} with your email address.), or to browse the -back end by @kbd{B nnwarchive RET mail-archive RET}. - -The following @code{nnwarchive} variables can be altered: - -@table @code -@item nnwarchive-directory -@vindex nnwarchive-directory -The directory where @code{nnwarchive} stores its files. The default is@* -@file{~/News/warchive/}. - -@item nnwarchive-login -@vindex nnwarchive-login -The account name on the web server. - -@item nnwarchive-passwd -@vindex nnwarchive-passwd -The password for your account on the web server. -@end table - -@node RSS -@subsection RSS -@cindex nnrss -@cindex RSS - -Some web sites have an RDF Site Summary (@acronym{RSS}). -@acronym{RSS} is a format for summarizing headlines from news related -sites (such as BBC or CNN). But basically anything list-like can be -presented as an @acronym{RSS} feed: weblogs, changelogs or recent -changes to a wiki (e.g. @url{http://cliki.net/recent-changes.rdf}). - -@acronym{RSS} has a quite regular and nice interface, and it's -possible to get the information Gnus needs to keep groups updated. - -Note: you had better use Emacs which supports the @code{utf-8} coding -system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII} -text by default. It is also used by default for non-@acronym{ASCII} -group names. - -@kindex G R (Group) -Use @kbd{G R} from the group buffer to subscribe to a feed---you will be -prompted for the location, the title and the description of the feed. -The title, which allows any characters, will be used for the group name -and the name of the group data file. The description can be omitted. - -An easy way to get started with @code{nnrss} is to say something like -the following in the group buffer: @kbd{B nnrss RET RET y}, then -subscribe to groups. - -The @code{nnrss} back end saves the group data file in -@code{nnrss-directory} (see below) for each @code{nnrss} group. File -names containing non-@acronym{ASCII} characters will be encoded by the -coding system specified with the @code{nnmail-pathname-coding-system} -variable or other. Also @xref{Non-ASCII Group Names}, for more -information. - -The @code{nnrss} back end generates @samp{multipart/alternative} -@acronym{MIME} articles in which each contains a @samp{text/plain} part -and a @samp{text/html} part. - -@cindex OPML -You can also use the following commands to import and export your -subscriptions from a file in @acronym{OPML} format (Outline Processor -Markup Language). - -@defun nnrss-opml-import file -Prompt for an @acronym{OPML} file, and subscribe to each feed in the -file. -@end defun - -@defun nnrss-opml-export -Write your current @acronym{RSS} subscriptions to a buffer in -@acronym{OPML} format. -@end defun - -The following @code{nnrss} variables can be altered: - -@table @code -@item nnrss-directory -@vindex nnrss-directory -The directory where @code{nnrss} stores its files. The default is -@file{~/News/rss/}. - -@item nnrss-file-coding-system -@vindex nnrss-file-coding-system -The coding system used when reading and writing the @code{nnrss} groups -data files. The default is the value of -@code{mm-universal-coding-system} (which defaults to @code{emacs-mule} -in Emacs or @code{escape-quoted} in XEmacs). - -@item nnrss-ignore-article-fields -@vindex nnrss-ignore-article-fields -Some feeds update constantly article fields during their publications, -e.g. to indicate the number of comments. However, if there is -a difference between the local article and the distant one, the latter -is considered to be new. To avoid this and discard some fields, set this -variable to the list of fields to be ignored. The default is -@code{'(slash:comments)}. - -@item nnrss-use-local -@vindex nnrss-use-local -@findex nnrss-generate-download-script -If you set @code{nnrss-use-local} to @code{t}, @code{nnrss} will read -the feeds from local files in @code{nnrss-directory}. You can use -the command @code{nnrss-generate-download-script} to generate a -download script using @command{wget}. - -@item nnrss-wash-html-in-text-plain-parts -Non-@code{nil} means that @code{nnrss} renders text in @samp{text/plain} -parts as @acronym{HTML}. The function specified by the -@code{mm-text-html-renderer} variable (@pxref{Display Customization, -,Display Customization, emacs-mime, The Emacs MIME Manual}) will be used -to render text. If it is @code{nil}, which is the default, text will -simply be folded. Leave it @code{nil} if you prefer to see -@samp{text/html} parts. -@end table - -The following code may be helpful, if you want to show the description in -the summary buffer. - -@lisp -(add-to-list 'nnmail-extra-headers nnrss-description-field) -(setq gnus-summary-line-format "%U%R%z%I%(%[%4L: %-15,15f%]%) %s%uX\n") - -(defun gnus-user-format-function-X (header) - (let ((descr - (assq nnrss-description-field (mail-header-extra header)))) - (if descr (concat "\n\t" (cdr descr)) ""))) -@end lisp - -The following code may be useful to open an nnrss url directly from the -summary buffer. - -@lisp -(require 'browse-url) - -(defun browse-nnrss-url (arg) - (interactive "p") - (let ((url (assq nnrss-url-field - (mail-header-extra - (gnus-data-header - (assq (gnus-summary-article-number) - gnus-newsgroup-data)))))) - (if url - (progn - (browse-url (cdr url)) - (gnus-summary-mark-as-read-forward 1)) - (gnus-summary-scroll-up arg)))) - -(eval-after-load "gnus" - #'(define-key gnus-summary-mode-map - (kbd "") 'browse-nnrss-url)) -(add-to-list 'nnmail-extra-headers nnrss-url-field) -@end lisp - -Even if you have added @samp{text/html} to the -@code{mm-discouraged-alternatives} variable (@pxref{Display -Customization, ,Display Customization, emacs-mime, The Emacs MIME -Manual}) since you don't want to see @acronym{HTML} parts, it might be -more useful especially in @code{nnrss} groups to display -@samp{text/html} parts. Here's an example of setting -@code{mm-discouraged-alternatives} as a group parameter (@pxref{Group -Parameters}) in order to display @samp{text/html} parts only in -@code{nnrss} groups: - -@lisp -;; @r{Set the default value of @code{mm-discouraged-alternatives}.} -(eval-after-load "gnus-sum" - '(add-to-list - 'gnus-newsgroup-variables - '(mm-discouraged-alternatives - . '("text/html" "image/.*")))) - -;; @r{Display @samp{text/html} parts in @code{nnrss} groups.} -(add-to-list - 'gnus-parameters - '("\\`nnrss:" (mm-discouraged-alternatives nil))) -@end lisp - - -@node Customizing W3 -@subsection Customizing W3 -@cindex W3 -@cindex html -@cindex url -@cindex Netscape - -Gnus uses the url library to fetch web pages and Emacs/W3 (or those -alternatives) to display web pages. Emacs/W3 is documented in its own -manual, but there are some things that may be more relevant for Gnus -users. - -For instance, a common question is how to make Emacs/W3 follow links -using the @code{browse-url} functions (which will call some external web -browser like Netscape). Here's one way: - -@lisp -(eval-after-load "w3" - '(progn - (fset 'w3-fetch-orig (symbol-function 'w3-fetch)) - (defun w3-fetch (&optional url target) - (interactive (list (w3-read-url-with-default))) - (if (eq major-mode 'gnus-article-mode) - (browse-url url) - (w3-fetch-orig url target))))) -@end lisp - -Put that in your @file{.emacs} file, and hitting links in W3-rendered -@acronym{HTML} in the Gnus article buffers will use @code{browse-url} to -follow the link. - - -@node IMAP -@section IMAP -@cindex nnimap -@cindex @acronym{IMAP} - -@acronym{IMAP} is a network protocol for reading mail (or news, or @dots{}), -think of it as a modernized @acronym{NNTP}. Connecting to a @acronym{IMAP} -server is much similar to connecting to a news server, you just -specify the network address of the server. - -@acronym{IMAP} has two properties. First, @acronym{IMAP} can do -everything that @acronym{POP} can, it can hence be viewed as a -@acronym{POP++}. Secondly, @acronym{IMAP} is a mail storage protocol, -similar to @acronym{NNTP} being a news storage protocol---however, -@acronym{IMAP} offers more features than @acronym{NNTP} because news -is more or less read-only whereas mail is read-write. - -If you want to use @acronym{IMAP} as a @acronym{POP++}, use an imap -entry in @code{mail-sources}. With this, Gnus will fetch mails from -the @acronym{IMAP} server and store them on the local disk. This is -not the usage described in this section---@xref{Mail Sources}. - -If you want to use @acronym{IMAP} as a mail storage protocol, use an nnimap -entry in @code{gnus-secondary-select-methods}. With this, Gnus will -manipulate mails stored on the @acronym{IMAP} server. This is the kind of -usage explained in this section. - -A server configuration in @file{~/.gnus.el} with a few @acronym{IMAP} -servers might look something like the following. (Note that for -@acronym{TLS}/@acronym{SSL}, you need external programs and libraries, -see below.) - -@lisp -(setq gnus-secondary-select-methods - '((nnimap "simpleserver") ; @r{no special configuration} - ; @r{perhaps a ssh port forwarded server:} - (nnimap "dolk" - (nnimap-address "localhost") - (nnimap-server-port 1430)) - ; @r{a UW server running on localhost} - (nnimap "barbar" - (nnimap-server-port 143) - (nnimap-address "localhost") - (nnimap-list-pattern ("INBOX" "mail/*"))) - ; @r{anonymous public cyrus server:} - (nnimap "cyrus.andrew.cmu.edu" - (nnimap-authenticator anonymous) - (nnimap-list-pattern "archive.*") - (nnimap-stream network)) - ; @r{a ssl server on a non-standard port:} - (nnimap "vic20" - (nnimap-address "vic20.somewhere.com") - (nnimap-server-port 9930) - (nnimap-stream ssl)))) -@end lisp - -After defining the new server, you can subscribe to groups on the -server using normal Gnus commands such as @kbd{U} in the Group Buffer -(@pxref{Subscription Commands}) or via the Server Buffer -(@pxref{Server Buffer}). - -The following variables can be used to create a virtual @code{nnimap} -server: - -@table @code - -@item nnimap-address -@vindex nnimap-address - -The address of the remote @acronym{IMAP} server. Defaults to the virtual -server name if not specified. - -@item nnimap-server-port -@vindex nnimap-server-port -Port on server to contact. Defaults to port 143, or 993 for @acronym{TLS}/@acronym{SSL}. - -Note that this should be an integer, example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-server-port 4711)) -@end lisp - -@item nnimap-list-pattern -@vindex nnimap-list-pattern -String or list of strings of mailboxes to limit available groups to. -This is used when the server has very many mailboxes and you're only -interested in a few---some servers export your home directory via -@acronym{IMAP}, you'll probably want to limit the mailboxes to those in -@file{~/Mail/*} then. - -The string can also be a cons of REFERENCE and the string as above, what -REFERENCE is used for is server specific, but on the University of -Washington server it's a directory that will be concatenated with the -mailbox. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-list-pattern ("INBOX" "Mail/*" "alt.sex.*" - ("~friend/Mail/" . "list/*")))) -@end lisp - -@item nnimap-stream -@vindex nnimap-stream -The type of stream used to connect to your server. By default, nnimap -will detect and automatically use all of the below, with the exception -of @acronym{TLS}/@acronym{SSL}. (@acronym{IMAP} over -@acronym{TLS}/@acronym{SSL} is being replaced by STARTTLS, which can -be automatically detected, but it's not widely deployed yet.) - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-stream ssl)) -@end lisp - -Please note that the value of @code{nnimap-stream} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} Connect with GSSAPI (usually Kerberos 5). Requires the -@samp{gsasl} or @samp{imtest} program. -@item -@dfn{kerberos4:} Connect with Kerberos 4. Requires the @samp{imtest} program. -@item -@dfn{starttls:} Connect via the STARTTLS extension (similar to -@acronym{TLS}/@acronym{SSL}). Requires the external library @samp{starttls.el} and program -@samp{starttls}. -@item -@dfn{tls:} Connect through @acronym{TLS}. Requires GNUTLS (the program -@samp{gnutls-cli}). -@item -@dfn{ssl:} Connect through @acronym{SSL}. Requires OpenSSL (the program -@samp{openssl}) or SSLeay (@samp{s_client}). -@item -@dfn{shell:} Use a shell command to start @acronym{IMAP} connection. -@item -@dfn{network:} Plain, TCP/IP network connection. -@end itemize - -@vindex imap-kerberos4-program -The @samp{imtest} program is shipped with Cyrus IMAPD. If you're -using @samp{imtest} from Cyrus IMAPD < 2.0.14 (which includes version -1.5.x and 1.6.x) you need to frob @code{imap-process-connection-type} -to make @code{imap.el} use a pty instead of a pipe when communicating -with @samp{imtest}. You will then suffer from a line length -restrictions on @acronym{IMAP} commands, which might make Gnus seem to hang -indefinitely if you have many articles in a mailbox. The variable -@code{imap-kerberos4-program} contain parameters to pass to the imtest -program. - -For @acronym{TLS} connection, the @code{gnutls-cli} program from GNUTLS is -needed. It is available from -@uref{http://www.gnu.org/software/gnutls/}. - -@vindex imap-gssapi-program -This parameter specifies a list of command lines that invoke a GSSAPI -authenticated @acronym{IMAP} stream in a subshell. They are tried -sequentially until a connection is made, or the list has been -exhausted. By default, @samp{gsasl} from GNU SASL, available from -@uref{http://www.gnu.org/software/gsasl/}, and the @samp{imtest} -program from Cyrus IMAPD (see @code{imap-kerberos4-program}), are -tried. - -@vindex imap-ssl-program -For @acronym{SSL} connections, the OpenSSL program is available from -@uref{http://www.openssl.org/}. OpenSSL was formerly known as SSLeay, -and nnimap support it too---although the most recent versions of -SSLeay, 0.9.x, are known to have serious bugs making it -useless. Earlier versions, especially 0.8.x, of SSLeay are known to -work. The variable @code{imap-ssl-program} contain parameters to pass -to OpenSSL/SSLeay. - -@vindex imap-shell-program -@vindex imap-shell-host -For @acronym{IMAP} connections using the @code{shell} stream, the -variable @code{imap-shell-program} specify what program to call. Make -sure nothing is interfering with the output of the program, e.g., don't -forget to redirect the error output to the void. - -@item nnimap-authenticator -@vindex nnimap-authenticator - -The authenticator used to connect to the server. By default, nnimap -will use the most secure authenticator your server is capable of. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-authenticator anonymous)) -@end lisp - -Please note that the value of @code{nnimap-authenticator} is a symbol! - -@itemize @bullet -@item -@dfn{gssapi:} GSSAPI (usually kerberos 5) authentication. Requires -external program @code{gsasl} or @code{imtest}. -@item -@dfn{kerberos4:} Kerberos 4 authentication. Requires external program -@code{imtest}. -@item -@dfn{digest-md5:} Encrypted username/password via DIGEST-MD5. Requires -external library @code{digest-md5.el}. -@item -@dfn{cram-md5:} Encrypted username/password via CRAM-MD5. -@item -@dfn{login:} Plain-text username/password via LOGIN. -@item -@dfn{anonymous:} Login as ``anonymous'', supplying your email address as password. -@end itemize - -@item nnimap-expunge-on-close -@cindex expunging -@vindex nnimap-expunge-on-close -Unlike Parmenides the @acronym{IMAP} designers have decided things that -don't exist actually do exist. More specifically, @acronym{IMAP} has -this concept of marking articles @code{Deleted} which doesn't actually -delete them, and this (marking them @code{Deleted}, that is) is what -nnimap does when you delete an article in Gnus (with @kbd{B DEL} or -similar). - -Since the articles aren't really removed when we mark them with the -@code{Deleted} flag we'll need a way to actually delete them. Feel like -running in circles yet? - -Traditionally, nnimap has removed all articles marked as @code{Deleted} -when closing a mailbox but this is now configurable by this server -variable. - -The possible options are: - -@table @code - -@item always -The default behavior, delete all articles marked as ``Deleted'' when -closing a mailbox. -@item never -Never actually delete articles. Currently there is no way of showing -the articles marked for deletion in nnimap, but other @acronym{IMAP} clients -may allow you to do this. If you ever want to run the EXPUNGE command -manually, @xref{Expunging mailboxes}. -@item ask -When closing mailboxes, nnimap will ask if you wish to expunge deleted -articles or not. - -@end table - -@item nnimap-importantize-dormant -@vindex nnimap-importantize-dormant - -If non-@code{nil} (the default), marks dormant articles as ticked (as -well), for other @acronym{IMAP} clients. Within Gnus, dormant articles will -naturally still (only) be marked as dormant. This is to make dormant -articles stand out, just like ticked articles, in other @acronym{IMAP} -clients. (In other words, Gnus has two ``Tick'' marks and @acronym{IMAP} -has only one.) - -Probably the only reason for frobbing this would be if you're trying -enable per-user persistent dormant flags, using something like: - -@lisp -(setcdr (assq 'dormant nnimap-mark-to-flag-alist) - (format "gnus-dormant-%s" (user-login-name))) -(setcdr (assq 'dormant nnimap-mark-to-predicate-alist) - (format "KEYWORD gnus-dormant-%s" (user-login-name))) -@end lisp - -In this case, you would not want the per-user dormant flag showing up -as ticked for other users. - -@item nnimap-expunge-search-string -@cindex expunging -@vindex nnimap-expunge-search-string -@cindex expiring @acronym{IMAP} mail - -This variable contain the @acronym{IMAP} search command sent to server when -searching for articles eligible for expiring. The default is -@code{"UID %s NOT SINCE %s"}, where the first @code{%s} is replaced by -UID set and the second @code{%s} is replaced by a date. - -Probably the only useful value to change this to is -@code{"UID %s NOT SENTSINCE %s"}, which makes nnimap use the Date: in -messages instead of the internal article date. See section 6.4.4 of -RFC 2060 for more information on valid strings. - -However, if @code{nnimap-search-uids-not-since-is-evil} -is true, this variable has no effect since the search logic -is reversed, as described below. - -@item nnimap-authinfo-file -@vindex nnimap-authinfo-file - -A file containing credentials used to log in on servers. The format is -(almost) the same as the @code{ftp} @file{~/.netrc} file. See the -variable @code{nntp-authinfo-file} for exact syntax; also see -@ref{NNTP}. An example of an .authinfo line for an IMAP server, is: - -@example -machine students.uio.no login larsi password geheimnis port imap -@end example - -Note that it should be @code{port imap}, or @code{port 143}, if you -use a @code{nnimap-stream} of @code{tls} or @code{ssl}, even if the -actual port number used is port 993 for secured IMAP. For -convenience, Gnus will accept @code{port imaps} as a synonym of -@code{port imap}. - -@item nnimap-need-unselect-to-notice-new-mail -@vindex nnimap-need-unselect-to-notice-new-mail - -Unselect mailboxes before looking for new mail in them. Some servers -seem to need this under some circumstances; it was reported that -Courier 1.7.1 did. - -@item nnimap-nov-is-evil -@vindex nnimap-nov-is-evil -@cindex Courier @acronym{IMAP} server -@cindex @acronym{NOV} - -Never generate or use a local @acronym{NOV} database. Defaults to the -value of @code{gnus-agent}. - -Using a @acronym{NOV} database usually makes header fetching much -faster, but it uses the @code{UID SEARCH UID} command, which is very -slow on some servers (notably some versions of Courier). Since the Gnus -Agent caches the information in the @acronym{NOV} database without using -the slow command, this variable defaults to true if the Agent is in use, -and false otherwise. - -@item nnimap-search-uids-not-since-is-evil -@vindex nnimap-search-uids-not-since-is-evil -@cindex Courier @acronym{IMAP} server -@cindex expiring @acronym{IMAP} mail - -Avoid the @code{UID SEARCH UID @var{message numbers} NOT SINCE -@var{date}} command, which is slow on some @acronym{IMAP} servers -(notably, some versions of Courier). Instead, use @code{UID SEARCH SINCE -@var{date}} and prune the list of expirable articles within Gnus. - -When Gnus expires your mail (@pxref{Expiring Mail}), it starts with a -list of expirable articles and asks the IMAP server questions like ``Of -these articles, which ones are older than a week?'' While this seems -like a perfectly reasonable question, some IMAP servers take a long time -to answer it, since they seemingly go looking into every old article to -see if it is one of the expirable ones. Curiously, the question ``Of -@emph{all} articles, which ones are newer than a week?'' seems to be -much faster to answer, so setting this variable causes Gnus to ask this -question and figure out the answer to the real question itself. - -This problem can really sneak up on you: when you first configure Gnus, -everything works fine, but once you accumulate a couple thousand -messages, you start cursing Gnus for being so slow. On the other hand, -if you get a lot of email within a week, setting this variable will -cause a lot of network traffic between Gnus and the IMAP server. - -@item nnimap-logout-timeout -@vindex nnimap-logout-timeout - -There is a case where a connection to a @acronym{IMAP} server is unable -to close, when connecting to the server via a certain kind of network, -e.g. @acronym{VPN}. In that case, it will be observed that a connection -between Emacs and the local network looks alive even if the server has -closed a connection for some reason (typically, a timeout). -Consequently, Emacs continues waiting for a response from the server for -the @code{LOGOUT} command that Emacs sent, or hangs in other words. If -you are in such a network, setting this variable to a number of seconds -will be helpful. If it is set, a hung connection will be closed -forcibly, after this number of seconds from the time Emacs sends the -@code{LOGOUT} command. It should not be too small value but too large -value will be inconvenient too. Perhaps the value 1.0 will be a good -candidate but it might be worth trying some other values. - -Example server specification: - -@lisp -(nnimap "mail.server.com" - (nnimap-logout-timeout 1.0)) -@end lisp - -@end table - -@menu -* Splitting in IMAP:: Splitting mail with nnimap. -* Expiring in IMAP:: Expiring mail with nnimap. -* Editing IMAP ACLs:: Limiting/enabling other users access to a mailbox. -* Expunging mailboxes:: Equivalent of a ``compress mailbox'' button. -* A note on namespaces:: How to (not) use @acronym{IMAP} namespace in Gnus. -* Debugging IMAP:: What to do when things don't work. -@end menu - - - -@node Splitting in IMAP -@subsection Splitting in IMAP -@cindex splitting imap mail - -Splitting is something Gnus users have loved and used for years, and now -the rest of the world is catching up. Yeah, dream on, not many -@acronym{IMAP} servers have server side splitting and those that have -splitting seem to use some non-standard protocol. This means that -@acronym{IMAP} support for Gnus has to do its own splitting. - -And it does. - -(Incidentally, people seem to have been dreaming on, and Sieve has -gaining a market share and is supported by several IMAP servers. -Fortunately, Gnus support it too, @xref{Sieve Commands}.) - -Here are the variables of interest: - -@table @code - -@item nnimap-split-crosspost -@cindex splitting, crosspost -@cindex crosspost -@vindex nnimap-split-crosspost - -If non-@code{nil}, do crossposting if several split methods match the -mail. If @code{nil}, the first match in @code{nnimap-split-rule} -found will be used. - -Nnmail equivalent: @code{nnmail-crosspost}. - -@item nnimap-split-inbox -@cindex splitting, inbox -@cindex inbox -@vindex nnimap-split-inbox - -A string or a list of strings that gives the name(s) of @acronym{IMAP} -mailboxes to split from. Defaults to @code{nil}, which means that -splitting is disabled! - -@lisp -(setq nnimap-split-inbox - '("INBOX" ("~/friend/Mail" . "lists/*") "lists.imap")) -@end lisp - -No nnmail equivalent. - -@item nnimap-split-rule -@cindex splitting, rules -@vindex nnimap-split-rule - -New mail found in @code{nnimap-split-inbox} will be split according to -this variable. - -This variable contains a list of lists, where the first element in the -sublist gives the name of the @acronym{IMAP} mailbox to move articles -matching the regexp in the second element in the sublist. Got that? -Neither did I, we need examples. - -@lisp -(setq nnimap-split-rule - '(("INBOX.nnimap" - "^Sender: owner-nnimap@@vic20.globalcom.se") - ("INBOX.junk" "^Subject:.*MAKE MONEY") - ("INBOX.private" ""))) -@end lisp - -This will put all articles from the nnimap mailing list into mailbox -INBOX.nnimap, all articles containing MAKE MONEY in the Subject: line -into INBOX.junk and everything else in INBOX.private. - -The first string may contain @samp{\\1} forms, like the ones used by -replace-match to insert sub-expressions from the matched text. For -instance: - -@lisp -("INBOX.lists.\\1" "^Sender: owner-\\([a-z-]+\\)@@") -@end lisp - -The first element can also be the symbol @code{junk} to indicate that -matching messages should simply be deleted. Use with care. - -The second element can also be a function. In that case, it will be -called with the first element of the rule as the argument, in a buffer -containing the headers of the article. It should return a -non-@code{nil} value if it thinks that the mail belongs in that group. - -Nnmail users might recollect that the last regexp had to be empty to -match all articles (like in the example above). This is not required in -nnimap. Articles not matching any of the regexps will not be moved out -of your inbox. (This might affect performance if you keep lots of -unread articles in your inbox, since the splitting code would go over -them every time you fetch new mail.) - -These rules are processed from the beginning of the alist toward the -end. The first rule to make a match will ``win'', unless you have -crossposting enabled. In that case, all matching rules will ``win''. - -This variable can also have a function as its value, the function will -be called with the headers narrowed and should return a group where it -thinks the article should be split to. See @code{nnimap-split-fancy}. - -The splitting code tries to create mailboxes if it needs to. - -To allow for different split rules on different virtual servers, and -even different split rules in different inboxes on the same server, -the syntax of this variable have been extended along the lines of: - -@lisp -(setq nnimap-split-rule - '(("my1server" (".*" (("ding" "ding@@gnus.org") - ("junk" "From:.*Simon")))) - ("my2server" ("INBOX" nnimap-split-fancy)) - ("my[34]server" (".*" (("private" "To:.*Simon") - ("junk" my-junk-func)))))) -@end lisp - -The virtual server name is in fact a regexp, so that the same rules -may apply to several servers. In the example, the servers -@code{my3server} and @code{my4server} both use the same rules. -Similarly, the inbox string is also a regexp. The actual splitting -rules are as before, either a function, or a list with group/regexp or -group/function elements. - -Nnmail equivalent: @code{nnmail-split-methods}. - -@item nnimap-split-predicate -@cindex splitting -@vindex nnimap-split-predicate - -Mail matching this predicate in @code{nnimap-split-inbox} will be -split, it is a string and the default is @samp{UNSEEN UNDELETED}. - -This might be useful if you use another @acronym{IMAP} client to read mail in -your inbox but would like Gnus to split all articles in the inbox -regardless of readedness. Then you might change this to -@samp{UNDELETED}. - -@item nnimap-split-fancy -@cindex splitting, fancy -@findex nnimap-split-fancy -@vindex nnimap-split-fancy - -It's possible to set @code{nnimap-split-rule} to -@code{nnmail-split-fancy} if you want to use fancy -splitting. @xref{Fancy Mail Splitting}. - -However, to be able to have different fancy split rules for nnmail and -nnimap back ends you can set @code{nnimap-split-rule} to -@code{nnimap-split-fancy} and define the nnimap specific fancy split -rule in @code{nnimap-split-fancy}. - -Example: - -@lisp -(setq nnimap-split-rule 'nnimap-split-fancy - nnimap-split-fancy ...) -@end lisp - -Nnmail equivalent: @code{nnmail-split-fancy}. - -@item nnimap-split-download-body -@findex nnimap-split-download-body -@vindex nnimap-split-download-body - -Set to non-@code{nil} to download entire articles during splitting. -This is generally not required, and will slow things down -considerably. You may need it if you want to use an advanced -splitting function that analyzes the body to split the article. - -@end table - -@node Expiring in IMAP -@subsection Expiring in IMAP -@cindex expiring @acronym{IMAP} mail - -Even though @code{nnimap} is not a proper @code{nnmail} derived back -end, it supports most features in regular expiring (@pxref{Expiring -Mail}). Unlike splitting in @acronym{IMAP} (@pxref{Splitting in -IMAP}) it does not clone the @code{nnmail} variables (i.e., creating -@var{nnimap-expiry-wait}) but reuse the @code{nnmail} variables. What -follows below are the variables used by the @code{nnimap} expiry -process. - -A note on how the expire mark is stored on the @acronym{IMAP} server is -appropriate here as well. The expire mark is translated into a -@code{imap} client specific mark, @code{gnus-expire}, and stored on the -message. This means that likely only Gnus will understand and treat -the @code{gnus-expire} mark properly, although other clients may allow -you to view client specific flags on the message. It also means that -your server must support permanent storage of client specific flags on -messages. Most do, fortunately. - -If expiring @acronym{IMAP} mail seems very slow, try setting the server -variable @code{nnimap-search-uids-not-since-is-evil}. - -@table @code - -@item nnmail-expiry-wait -@item nnmail-expiry-wait-function - -These variables are fully supported. The expire value can be a -number, the symbol @code{immediate} or @code{never}. - -@item nnmail-expiry-target - -This variable is supported, and internally implemented by calling the -@code{nnmail} functions that handle this. It contains an optimization -that if the destination is a @acronym{IMAP} group on the same server, the -article is copied instead of appended (that is, uploaded again). - -@end table - -@node Editing IMAP ACLs -@subsection Editing IMAP ACLs -@cindex editing imap acls -@cindex Access Control Lists -@cindex Editing @acronym{IMAP} ACLs -@kindex G l (Group) -@findex gnus-group-nnimap-edit-acl - -ACL stands for Access Control List. ACLs are used in @acronym{IMAP} for -limiting (or enabling) other users access to your mail boxes. Not all -@acronym{IMAP} servers support this, this function will give an error if it -doesn't. - -To edit an ACL for a mailbox, type @kbd{G l} -(@code{gnus-group-edit-nnimap-acl}) and you'll be presented with an ACL -editing window with detailed instructions. - -Some possible uses: - -@itemize @bullet -@item -Giving ``anyone'' the ``lrs'' rights (lookup, read, keep seen/unseen flags) -on your mailing list mailboxes enables other users on the same server to -follow the list without subscribing to it. -@item -At least with the Cyrus server, you are required to give the user -``anyone'' posting ("p") capabilities to have ``plussing'' work (that is, -mail sent to user+mailbox@@domain ending up in the @acronym{IMAP} mailbox -INBOX.mailbox). -@end itemize - -@node Expunging mailboxes -@subsection Expunging mailboxes -@cindex expunging - -@cindex expunge -@cindex manual expunging -@kindex G x (Group) -@findex gnus-group-nnimap-expunge - -If you're using the @code{never} setting of @code{nnimap-expunge-on-close}, -you may want the option of expunging all deleted articles in a mailbox -manually. This is exactly what @kbd{G x} does. - -Currently there is no way of showing deleted articles, you can just -delete them. - -@node A note on namespaces -@subsection A note on namespaces -@cindex IMAP namespace -@cindex namespaces - -The @acronym{IMAP} protocol has a concept called namespaces, described -by the following text in the RFC2060: - -@display -5.1.2. Mailbox Namespace Naming Convention - - By convention, the first hierarchical element of any mailbox name - which begins with "#" identifies the "namespace" of the remainder of - the name. This makes it possible to disambiguate between different - types of mailbox stores, each of which have their own namespaces. - - For example, implementations which offer access to USENET - newsgroups MAY use the "#news" namespace to partition the USENET - newsgroup namespace from that of other mailboxes. Thus, the - comp.mail.misc newsgroup would have an mailbox name of - "#news.comp.mail.misc", and the name "comp.mail.misc" could refer - to a different object (e.g. a user's private mailbox). -@end display - -While there is nothing in this text that warrants concern for the -@acronym{IMAP} implementation in Gnus, some servers use namespace -prefixes in a way that does not work with how Gnus uses mailbox names. - -Specifically, University of Washington's @acronym{IMAP} server uses -mailbox names like @code{#driver.mbx/read-mail} which are valid only -in the @sc{create} and @sc{append} commands. After the mailbox is -created (or a messages is appended to a mailbox), it must be accessed -without the namespace prefix, i.e. @code{read-mail}. Since Gnus do -not make it possible for the user to guarantee that user entered -mailbox names will only be used with the CREATE and APPEND commands, -you should simply not use the namespace prefixed mailbox names in -Gnus. - -See the UoW IMAPD documentation for the @code{#driver.*/} prefix -for more information on how to use the prefixes. They are a power -tool and should be used only if you are sure what the effects are. - -@node Debugging IMAP -@subsection Debugging IMAP -@cindex IMAP debugging -@cindex protocol dump (IMAP) - -@acronym{IMAP} is a complex protocol, more so than @acronym{NNTP} or -@acronym{POP3}. Implementation bugs are not unlikely, and we do our -best to fix them right away. If you encounter odd behavior, chances -are that either the server or Gnus is buggy. - -If you are familiar with network protocols in general, you will -probably be able to extract some clues from the protocol dump of the -exchanges between Gnus and the server. Even if you are not familiar -with network protocols, when you include the protocol dump in -@acronym{IMAP}-related bug reports you are helping us with data -critical to solving the problem. Therefore, we strongly encourage you -to include the protocol dump when reporting IMAP bugs in Gnus. - - -@vindex imap-log -Because the protocol dump, when enabled, generates lots of data, it is -disabled by default. You can enable it by setting @code{imap-log} as -follows: - -@lisp -(setq imap-log t) -@end lisp - -This instructs the @code{imap.el} package to log any exchanges with -the server. The log is stored in the buffer @samp{*imap-log*}. Look -for error messages, which sometimes are tagged with the keyword -@code{BAD}---but when submitting a bug, make sure to include all the -data. - -@node Other Sources -@section Other Sources - -Gnus can do more than just read news or mail. The methods described -below allow Gnus to view directories and files as if they were -newsgroups. - -@menu -* Directory Groups:: You can read a directory as if it was a newsgroup. -* Anything Groups:: Dired? Who needs dired? -* Document Groups:: Single files can be the basis of a group. -* SOUP:: Reading @sc{soup} packets ``offline''. -* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. -@end menu - - -@node Directory Groups -@subsection Directory Groups -@cindex nndir -@cindex directory groups - -If you have a directory that has lots of articles in separate files in -it, you might treat it as a newsgroup. The files have to have numerical -names, of course. - -This might be an opportune moment to mention @code{ange-ftp} (and its -successor @code{efs}), that most wonderful of all wonderful Emacs -packages. When I wrote @code{nndir}, I didn't think much about it---a -back end to read directories. Big deal. - -@code{ange-ftp} changes that picture dramatically. For instance, if you -enter the @code{ange-ftp} file name -@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, -@code{ange-ftp} or @code{efs} will actually allow you to read this -directory over at @samp{sina} as a newsgroup. Distributed news ahoy! - -@code{nndir} will use @acronym{NOV} files if they are present. - -@code{nndir} is a ``read-only'' back end---you can't delete or expire -articles with this method. You can use @code{nnmh} or @code{nnml} for -whatever you use @code{nndir} for, so you could switch to any of those -methods if you feel the need to have a non-read-only @code{nndir}. - - -@node Anything Groups -@subsection Anything Groups -@cindex nneething - -From the @code{nndir} back end (which reads a single spool-like -directory), it's just a hop and a skip to @code{nneething}, which -pretends that any arbitrary directory is a newsgroup. Strange, but -true. - -When @code{nneething} is presented with a directory, it will scan this -directory and assign article numbers to each file. When you enter such -a group, @code{nneething} must create ``headers'' that Gnus can use. -After all, Gnus is a newsreader, in case you're forgetting. -@code{nneething} does this in a two-step process. First, it snoops each -file in question. If the file looks like an article (i.e., the first -few lines look like headers), it will use this as the head. If this is -just some arbitrary file without a head (e.g. a C source file), -@code{nneething} will cobble up a header out of thin air. It will use -file ownership, name and date and do whatever it can with these -elements. - -All this should happen automatically for you, and you will be presented -with something that looks very much like a newsgroup. Totally like a -newsgroup, to be precise. If you select an article, it will be displayed -in the article buffer, just as usual. - -If you select a line that represents a directory, Gnus will pop you into -a new summary buffer for this @code{nneething} group. And so on. You can -traverse the entire disk this way, if you feel like, but remember that -Gnus is not dired, really, and does not intend to be, either. - -There are two overall modes to this action---ephemeral or solid. When -doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus -will not store information on what files you have read, and what files -are new, and so on. If you create a solid @code{nneething} group the -normal way with @kbd{G m}, Gnus will store a mapping table between -article numbers and file names, and you can treat this group like any -other groups. When you activate a solid @code{nneething} group, you will -be told how many unread articles it contains, etc., etc. - -Some variables: - -@table @code -@item nneething-map-file-directory -@vindex nneething-map-file-directory -All the mapping files for solid @code{nneething} groups will be stored -in this directory, which defaults to @file{~/.nneething/}. - -@item nneething-exclude-files -@vindex nneething-exclude-files -All files that match this regexp will be ignored. Nice to use to exclude -auto-save files and the like, which is what it does by default. - -@item nneething-include-files -@vindex nneething-include-files -Regexp saying what files to include in the group. If this variable is -non-@code{nil}, only files matching this regexp will be included. - -@item nneething-map-file -@vindex nneething-map-file -Name of the map files. -@end table - - -@node Document Groups -@subsection Document Groups -@cindex nndoc -@cindex documentation group -@cindex help group - -@code{nndoc} is a cute little thing that will let you read a single file -as a newsgroup. Several files types are supported: - -@table @code -@cindex Babyl -@item babyl -The Babyl format. - -@cindex mbox -@cindex Unix mbox -@item mbox -The standard Unix mbox file. - -@cindex MMDF mail box -@item mmdf -The MMDF mail box format. - -@item news -Several news articles appended into a file. - -@cindex rnews batch files -@item rnews -The rnews batch transport format. - -@item nsmail -Netscape mail boxes. - -@item mime-parts -@acronym{MIME} multipart messages. - -@item standard-digest -The standard (RFC 1153) digest format. - -@item mime-digest -A @acronym{MIME} digest of messages. - -@item lanl-gov-announce -Announcement messages from LANL Gov Announce. - -@cindex forwarded messages -@item rfc822-forward -A message forwarded according to RFC822. - -@item outlook -The Outlook mail box. - -@item oe-dbx -The Outlook Express dbx mail box. - -@item exim-bounce -A bounce message from the Exim MTA. - -@item forward -A message forwarded according to informal rules. - -@item rfc934 -An RFC934-forwarded message. - -@item mailman -A mailman digest. - -@item clari-briefs -A digest of Clarinet brief news items. - -@item slack-digest -Non-standard digest format---matches most things, but does it badly. - -@item mail-in-mail -The last resort. -@end table - -You can also use the special ``file type'' @code{guess}, which means -that @code{nndoc} will try to guess what file type it is looking at. -@code{digest} means that @code{nndoc} should guess what digest type the -file is. - -@code{nndoc} will not try to change the file or insert any extra headers into -it---it will simply, like, let you use the file as the basis for a -group. And that's it. - -If you have some old archived articles that you want to insert into your -new & spiffy Gnus mail back end, @code{nndoc} can probably help you with -that. Say you have an old @file{RMAIL} file with mail that you now want -to split into your new @code{nnml} groups. You look at that file using -@code{nndoc} (using the @kbd{G f} command in the group buffer -(@pxref{Foreign Groups})), set the process mark on all the articles in -the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) -using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} -file is now also stored in lots of @code{nnml} directories, and you can -delete that pesky @file{RMAIL} file. If you have the guts! - -Virtual server variables: - -@table @code -@item nndoc-article-type -@vindex nndoc-article-type -This should be one of @code{mbox}, @code{babyl}, @code{digest}, -@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, -@code{rfc822-forward}, @code{mime-parts}, @code{standard-digest}, -@code{slack-digest}, @code{clari-briefs}, @code{nsmail}, @code{outlook}, -@code{oe-dbx}, @code{mailman}, and @code{mail-in-mail} or @code{guess}. - -@item nndoc-post-type -@vindex nndoc-post-type -This variable says whether Gnus is to consider the group a news group or -a mail group. There are two valid values: @code{mail} (the default) -and @code{news}. -@end table - -@menu -* Document Server Internals:: How to add your own document types. -@end menu - - -@node Document Server Internals -@subsubsection Document Server Internals - -Adding new document types to be recognized by @code{nndoc} isn't -difficult. You just have to whip up a definition of what the document -looks like, write a predicate function to recognize that document type, -and then hook into @code{nndoc}. - -First, here's an example document type definition: - -@example -(mmdf - (article-begin . "^\^A\^A\^A\^A\n") - (body-end . "^\^A\^A\^A\^A\n")) -@end example - -The definition is simply a unique @dfn{name} followed by a series of -regexp pseudo-variable settings. Below are the possible -variables---don't be daunted by the number of variables; most document -types can be defined with very few settings: - -@table @code -@item first-article -If present, @code{nndoc} will skip past all text until it finds -something that match this regexp. All text before this will be -totally ignored. - -@item article-begin -This setting has to be present in all document type definitions. It -says what the beginning of each article looks like. To do more -complicated things that cannot be dealt with a simple regexp, you can -use @code{article-begin-function} instead of this. - -@item article-begin-function -If present, this should be a function that moves point to the beginning -of each article. This setting overrides @code{article-begin}. - -@item head-begin -If present, this should be a regexp that matches the head of the -article. To do more complicated things that cannot be dealt with a -simple regexp, you can use @code{head-begin-function} instead of this. - -@item head-begin-function -If present, this should be a function that moves point to the head of -the article. This setting overrides @code{head-begin}. - -@item head-end -This should match the end of the head of the article. It defaults to -@samp{^$}---the empty line. - -@item body-begin -This should match the beginning of the body of the article. It defaults -to @samp{^\n}. To do more complicated things that cannot be dealt with -a simple regexp, you can use @code{body-begin-function} instead of this. - -@item body-begin-function -If present, this function should move point to the beginning of the body -of the article. This setting overrides @code{body-begin}. - -@item body-end -If present, this should match the end of the body of the article. To do -more complicated things that cannot be dealt with a simple regexp, you -can use @code{body-end-function} instead of this. - -@item body-end-function -If present, this function should move point to the end of the body of -the article. This setting overrides @code{body-end}. - -@item file-begin -If present, this should match the beginning of the file. All text -before this regexp will be totally ignored. - -@item file-end -If present, this should match the end of the file. All text after this -regexp will be totally ignored. - -@end table - -So, using these variables @code{nndoc} is able to dissect a document -file into a series of articles, each with a head and a body. However, a -few more variables are needed since not all document types are all that -news-like---variables needed to transform the head or the body into -something that's palatable for Gnus: - -@table @code -@item prepare-body-function -If present, this function will be called when requesting an article. It -will be called with point at the start of the body, and is useful if the -document has encoded some parts of its contents. - -@item article-transform-function -If present, this function is called when requesting an article. It's -meant to be used for more wide-ranging transformation of both head and -body of the article. - -@item generate-head-function -If present, this function is called to generate a head that Gnus can -understand. It is called with the article number as a parameter, and is -expected to generate a nice head for the article in question. It is -called when requesting the headers of all articles. - -@item generate-article-function -If present, this function is called to generate an entire article that -Gnus can understand. It is called with the article number as a -parameter when requesting all articles. - -@item dissection-function -If present, this function is called to dissect a document by itself, -overriding @code{first-article}, @code{article-begin}, -@code{article-begin-function}, @code{head-begin}, -@code{head-begin-function}, @code{head-end}, @code{body-begin}, -@code{body-begin-function}, @code{body-end}, @code{body-end-function}, -@code{file-begin}, and @code{file-end}. - -@end table - -Let's look at the most complicated example I can come up with---standard -digests: - -@example -(standard-digest - (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) - (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) - (prepare-body-function . nndoc-unquote-dashes) - (body-end-function . nndoc-digest-body-end) - (head-end . "^ ?$") - (body-begin . "^ ?\n") - (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") - (subtype digest guess)) -@end example - -We see that all text before a 70-width line of dashes is ignored; all -text after a line that starts with that @samp{^End of} is also ignored; -each article begins with a 30-width line of dashes; the line separating -the head from the body may contain a single space; and that the body is -run through @code{nndoc-unquote-dashes} before being delivered. - -To hook your own document definition into @code{nndoc}, use the -@code{nndoc-add-type} function. It takes two parameters---the first -is the definition itself and the second (optional) parameter says -where in the document type definition alist to put this definition. -The alist is traversed sequentially, and -@code{nndoc-@var{type}-type-p} is called for a given type @var{type}. -So @code{nndoc-mmdf-type-p} is called to see whether a document is of -@code{mmdf} type, and so on. These type predicates should return -@code{nil} if the document is not of the correct type; @code{t} if it -is of the correct type; and a number if the document might be of the -correct type. A high number means high probability; a low number -means low probability with @samp{0} being the lowest valid number. - - -@node SOUP -@subsection SOUP -@cindex SOUP -@cindex offline - -In the PC world people often talk about ``offline'' newsreaders. These -are thingies that are combined reader/news transport monstrosities. -With built-in modem programs. Yecchh! - -Of course, us Unix Weenie types of human beans use things like -@code{uucp} and, like, @code{nntpd} and set up proper news and mail -transport things like Ghod intended. And then we just use normal -newsreaders. - -However, it can sometimes be convenient to do something that's a bit -easier on the brain if you have a very slow modem, and you're not really -that interested in doing things properly. - -A file format called @sc{soup} has been developed for transporting news -and mail from servers to home machines and back again. It can be a bit -fiddly. - -First some terminology: - -@table @dfn - -@item server -This is the machine that is connected to the outside world and where you -get news and/or mail from. - -@item home machine -This is the machine that you want to do the actual reading and responding -on. It is typically not connected to the rest of the world in any way. - -@item packet -Something that contains messages and/or commands. There are two kinds -of packets: - -@table @dfn -@item message packets -These are packets made at the server, and typically contain lots of -messages for you to read. These are called @file{SoupoutX.tgz} by -default, where @var{x} is a number. - -@item response packets -These are packets made at the home machine, and typically contains -replies that you've written. These are called @file{SoupinX.tgz} by -default, where @var{x} is a number. - -@end table - -@end table - - -@enumerate - -@item -You log in on the server and create a @sc{soup} packet. You can either -use a dedicated @sc{soup} thingie (like the @code{awk} program), or you -can use Gnus to create the packet with its @sc{soup} commands (@kbd{O -s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}). - -@item -You transfer the packet home. Rail, boat, car or modem will do fine. - -@item -You put the packet in your home directory. - -@item -You fire up Gnus on your home machine using the @code{nnsoup} back end as -the native or secondary server. - -@item -You read articles and mail and answer and followup to the things you -want (@pxref{SOUP Replies}). - -@item -You do the @kbd{G s r} command to pack these replies into a @sc{soup} -packet. - -@item -You transfer this packet to the server. - -@item -You use Gnus to mail this packet out with the @kbd{G s s} command. - -@item -You then repeat until you die. - -@end enumerate - -So you basically have a bipartite system---you use @code{nnsoup} for -reading and Gnus for packing/sending these @sc{soup} packets. - -@menu -* SOUP Commands:: Commands for creating and sending @sc{soup} packets -* SOUP Groups:: A back end for reading @sc{soup} packets. -* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. -@end menu - - -@node SOUP Commands -@subsubsection SOUP Commands - -These are commands for creating and manipulating @sc{soup} packets. - -@table @kbd -@item G s b -@kindex G s b (Group) -@findex gnus-group-brew-soup -Pack all unread articles in the current group -(@code{gnus-group-brew-soup}). This command understands the -process/prefix convention. - -@item G s w -@kindex G s w (Group) -@findex gnus-soup-save-areas -Save all @sc{soup} data files (@code{gnus-soup-save-areas}). - -@item G s s -@kindex G s s (Group) -@findex gnus-soup-send-replies -Send all replies from the replies packet -(@code{gnus-soup-send-replies}). - -@item G s p -@kindex G s p (Group) -@findex gnus-soup-pack-packet -Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}). - -@item G s r -@kindex G s r (Group) -@findex nnsoup-pack-replies -Pack all replies into a replies packet (@code{nnsoup-pack-replies}). - -@item O s -@kindex O s (Summary) -@findex gnus-soup-add-article -This summary-mode command adds the current article to a @sc{soup} packet -(@code{gnus-soup-add-article}). It understands the process/prefix -convention (@pxref{Process/Prefix}). - -@end table - - -There are a few variables to customize where Gnus will put all these -thingies: - -@table @code - -@item gnus-soup-directory -@vindex gnus-soup-directory -Directory where Gnus will save intermediate files while composing -@sc{soup} packets. The default is @file{~/SoupBrew/}. - -@item gnus-soup-replies-directory -@vindex gnus-soup-replies-directory -This is what Gnus will use as a temporary directory while sending our -reply packets. @file{~/SoupBrew/SoupReplies/} is the default. - -@item gnus-soup-prefix-file -@vindex gnus-soup-prefix-file -Name of the file where Gnus stores the last used prefix. The default is -@samp{gnus-prefix}. - -@item gnus-soup-packer -@vindex gnus-soup-packer -A format string command for packing a @sc{soup} packet. The default is -@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}. - -@item gnus-soup-unpacker -@vindex gnus-soup-unpacker -Format string command for unpacking a @sc{soup} packet. The default is -@samp{gunzip -c %s | tar xvf -}. - -@item gnus-soup-packet-directory -@vindex gnus-soup-packet-directory -Where Gnus will look for reply packets. The default is @file{~/}. - -@item gnus-soup-packet-regexp -@vindex gnus-soup-packet-regexp -Regular expression matching @sc{soup} reply packets in -@code{gnus-soup-packet-directory}. - -@end table - - -@node SOUP Groups -@subsubsection SOUP Groups -@cindex nnsoup - -@code{nnsoup} is the back end for reading @sc{soup} packets. It will -read incoming packets, unpack them, and put them in a directory where -you can read them at leisure. - -These are the variables you can use to customize its behavior: - -@table @code - -@item nnsoup-tmp-directory -@vindex nnsoup-tmp-directory -When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this -directory. (@file{/tmp/} by default.) - -@item nnsoup-directory -@vindex nnsoup-directory -@code{nnsoup} then moves each message and index file to this directory. -The default is @file{~/SOUP/}. - -@item nnsoup-replies-directory -@vindex nnsoup-replies-directory -All replies will be stored in this directory before being packed into a -reply packet. The default is @file{~/SOUP/replies/}. - -@item nnsoup-replies-format-type -@vindex nnsoup-replies-format-type -The @sc{soup} format of the replies packets. The default is @samp{?n} -(rnews), and I don't think you should touch that variable. I probably -shouldn't even have documented it. Drats! Too late! - -@item nnsoup-replies-index-type -@vindex nnsoup-replies-index-type -The index type of the replies packet. The default is @samp{?n}, which -means ``none''. Don't fiddle with this one either! - -@item nnsoup-active-file -@vindex nnsoup-active-file -Where @code{nnsoup} stores lots of information. This is not an ``active -file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose -this file or mess it up in any way, you're dead. The default is -@file{~/SOUP/active}. - -@item nnsoup-packer -@vindex nnsoup-packer -Format string command for packing a reply @sc{soup} packet. The default -is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}. - -@item nnsoup-unpacker -@vindex nnsoup-unpacker -Format string command for unpacking incoming @sc{soup} packets. The -default is @samp{gunzip -c %s | tar xvf -}. - -@item nnsoup-packet-directory -@vindex nnsoup-packet-directory -Where @code{nnsoup} will look for incoming packets. The default is -@file{~/}. - -@item nnsoup-packet-regexp -@vindex nnsoup-packet-regexp -Regular expression matching incoming @sc{soup} packets. The default is -@samp{Soupout}. - -@item nnsoup-always-save -@vindex nnsoup-always-save -If non-@code{nil}, save the replies buffer after each posted message. - -@end table - - -@node SOUP Replies -@subsubsection SOUP Replies - -Just using @code{nnsoup} won't mean that your postings and mailings end -up in @sc{soup} reply packets automagically. You have to work a bit -more for that to happen. - -@findex nnsoup-set-variables -The @code{nnsoup-set-variables} command will set the appropriate -variables to ensure that all your followups and replies end up in the -@sc{soup} system. - -In specific, this is what it does: - -@lisp -(setq message-send-news-function 'nnsoup-request-post) -(setq message-send-mail-function 'nnsoup-request-mail) -@end lisp - -And that's it, really. If you only want news to go into the @sc{soup} -system you just use the first line. If you only want mail to be -@sc{soup}ed you use the second. - - -@node Mail-To-News Gateways -@subsection Mail-To-News Gateways -@cindex mail-to-news gateways -@cindex gateways - -If your local @code{nntp} server doesn't allow posting, for some reason -or other, you can post using one of the numerous mail-to-news gateways. -The @code{nngateway} back end provides the interface. - -Note that you can't read anything from this back end---it can only be -used to post with. - -Server variables: - -@table @code -@item nngateway-address -@vindex nngateway-address -This is the address of the mail-to-news gateway. - -@item nngateway-header-transformation -@vindex nngateway-header-transformation -News headers often have to be transformed in some odd way or other -for the mail-to-news gateway to accept it. This variable says what -transformation should be called, and defaults to -@code{nngateway-simple-header-transformation}. The function is called -narrowed to the headers to be transformed and with one parameter---the -gateway address. - -This default function just inserts a new @code{To} header based on the -@code{Newsgroups} header and the gateway address. -For instance, an article with this @code{Newsgroups} header: - -@example -Newsgroups: alt.religion.emacs -@end example - -will get this @code{To} header inserted: - -@example -To: alt-religion-emacs@@GATEWAY -@end example - -The following pre-defined functions exist: - -@findex nngateway-simple-header-transformation -@table @code - -@item nngateway-simple-header-transformation -Creates a @code{To} header that looks like -@var{newsgroup}@@@code{nngateway-address}. - -@findex nngateway-mail2news-header-transformation - -@item nngateway-mail2news-header-transformation -Creates a @code{To} header that looks like -@code{nngateway-address}. -@end table - -@end table - -Here's an example: - -@lisp -(setq gnus-post-method - '(nngateway - "mail2news@@replay.com" - (nngateway-header-transformation - nngateway-mail2news-header-transformation))) -@end lisp - -So, to use this, simply say something like: - -@lisp -(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) -@end lisp - - - -@node Combined Groups -@section Combined Groups - -Gnus allows combining a mixture of all the other group types into bigger -groups. - -@menu -* Virtual Groups:: Combining articles from many groups. -* Kibozed Groups:: Looking through parts of the newsfeed for articles. -@end menu - - -@node Virtual Groups -@subsection Virtual Groups -@cindex nnvirtual -@cindex virtual groups -@cindex merging groups - -An @dfn{nnvirtual group} is really nothing more than a collection of -other groups. - -For instance, if you are tired of reading many small groups, you can -put them all in one big group, and then grow tired of reading one -big, unwieldy group. The joys of computing! - -You specify @code{nnvirtual} as the method. The address should be a -regexp to match component groups. - -All marks in the virtual group will stick to the articles in the -component groups. So if you tick an article in a virtual group, the -article will also be ticked in the component group from whence it -came. (And vice versa---marks from the component groups will also be -shown in the virtual group.). To create an empty virtual group, run -@kbd{G V} (@code{gnus-group-make-empty-virtual}) in the group buffer -and edit the method regexp with @kbd{M-e} -(@code{gnus-group-edit-group-method}) - -Here's an example @code{nnvirtual} method that collects all Andrea Dworkin -newsgroups into one, big, happy newsgroup: - -@lisp -(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") -@end lisp - -The component groups can be native or foreign; everything should work -smoothly, but if your computer explodes, it was probably my fault. - -Collecting the same group from several servers might actually be a good -idea if users have set the Distribution header to limit distribution. -If you would like to read @samp{soc.motss} both from a server in Japan -and a server in Norway, you could use the following as the group regexp: - -@example -"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" -@end example - -(Remember, though, that if you're creating the group with @kbd{G m}, you -shouldn't double the backslashes, and you should leave off the quote -characters at the beginning and the end of the string.) - -This should work kinda smoothly---all articles from both groups should -end up in this one, and there should be no duplicates. Threading (and -the rest) will still work as usual, but there might be problems with the -sequence of articles. Sorting on date might be an option here -(@pxref{Selecting a Group}). - -One limitation, however---all groups included in a virtual -group have to be alive (i.e., subscribed or unsubscribed). Killed or -zombie groups can't be component groups for @code{nnvirtual} groups. - -@vindex nnvirtual-always-rescan -If the @code{nnvirtual-always-rescan} variable is non-@code{nil} (which -is the default), @code{nnvirtual} will always scan groups for unread -articles when entering a virtual group. If this variable is @code{nil} -and you read articles in a component group after the virtual group has -been activated, the read articles from the component group will show up -when you enter the virtual group. You'll also see this effect if you -have two virtual groups that have a component group in common. If -that's the case, you should set this variable to @code{t}. Or you can -just tap @code{M-g} on the virtual group every time before you enter -it---it'll have much the same effect. - -@code{nnvirtual} can have both mail and news groups as component groups. -When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} -has to ask the back end of the component group the article comes from -whether it is a news or mail back end. However, when you do a @kbd{^}, -there is typically no sure way for the component back end to know this, -and in that case @code{nnvirtual} tells Gnus that the article came from a -not-news back end. (Just to be on the safe side.) - -@kbd{C-c C-n} in the message buffer will insert the @code{Newsgroups} -line from the article you respond to in these cases. - -@code{nnvirtual} groups do not inherit anything but articles and marks -from component groups---group parameters, for instance, are not -inherited. - - -@node Kibozed Groups -@subsection Kibozed Groups -@cindex nnkiboze -@cindex kibozing - -@dfn{Kibozing} is defined by the @acronym{OED} as ``grepping through -(parts of) the news feed''. @code{nnkiboze} is a back end that will -do this for you. Oh joy! Now you can grind any @acronym{NNTP} server -down to a halt with useless requests! Oh happiness! - -@kindex G k (Group) -To create a kibozed group, use the @kbd{G k} command in the group -buffer. - -The address field of the @code{nnkiboze} method is, as with -@code{nnvirtual}, a regexp to match groups to be ``included'' in the -@code{nnkiboze} group. That's where most similarities between -@code{nnkiboze} and @code{nnvirtual} end. - -In addition to this regexp detailing component groups, an -@code{nnkiboze} group must have a score file to say what articles are -to be included in the group (@pxref{Scoring}). - -@kindex M-x nnkiboze-generate-groups -@findex nnkiboze-generate-groups -You must run @kbd{M-x nnkiboze-generate-groups} after creating the -@code{nnkiboze} groups you want to have. This command will take time. -Lots of time. Oodles and oodles of time. Gnus has to fetch the -headers from all the articles in all the component groups and run them -through the scoring process to determine if there are any articles in -the groups that are to be part of the @code{nnkiboze} groups. - -Please limit the number of component groups by using restrictive -regexps. Otherwise your sysadmin may become annoyed with you, and the -@acronym{NNTP} site may throw you off and never let you back in again. -Stranger things have happened. - -@code{nnkiboze} component groups do not have to be alive---they can be dead, -and they can be foreign. No restrictions. - -@vindex nnkiboze-directory -The generation of an @code{nnkiboze} group means writing two files in -@code{nnkiboze-directory}, which is @file{~/News/kiboze/} by default. -One contains the @acronym{NOV} header lines for all the articles in -the group, and the other is an additional @file{.newsrc} file to store -information on what groups have been searched through to find -component articles. - -Articles marked as read in the @code{nnkiboze} group will have -their @acronym{NOV} lines removed from the @acronym{NOV} file. - - -@node Email Based Diary -@section Email Based Diary -@cindex diary -@cindex email based diary -@cindex calendar - -This section describes a special mail back end called @code{nndiary}, -and its companion library @code{gnus-diary}. It is ``special'' in the -sense that it is not meant to be one of the standard alternatives for -reading mail with Gnus. See @ref{Choosing a Mail Back End} for that. -Instead, it is used to treat @emph{some} of your mails in a special way, -namely, as event reminders. - -Here is a typical scenario: - -@itemize @bullet -@item -You've got a date with Andy Mc Dowell or Bruce Willis (select according -to your sexual preference) in one month. You don't want to forget it. -@item -So you send a ``reminder'' message (actually, a diary one) to yourself. -@item -You forget all about it and keep on getting and reading new mail, as usual. -@item -From time to time, as you type `g' in the group buffer and as the date -is getting closer, the message will pop up again to remind you of your -appointment, just as if it were new and unread. -@item -Read your ``new'' messages, this one included, and start dreaming again -of the night you're gonna have. -@item -Once the date is over (you actually fell asleep just after dinner), the -message will be automatically deleted if it is marked as expirable. -@end itemize - -The Gnus Diary back end has the ability to handle regular appointments -(that wouldn't ever be deleted) as well as punctual ones, operates as a -real mail back end and is configurable in many ways. All of this is -explained in the sections below. - -@menu -* The NNDiary Back End:: Basic setup and usage. -* The Gnus Diary Library:: Utility toolkit on top of nndiary. -* Sending or Not Sending:: A final note on sending diary messages. -@end menu - - -@node The NNDiary Back End -@subsection The NNDiary Back End -@cindex nndiary -@cindex the nndiary back end - -@code{nndiary} is a back end very similar to @code{nnml} (@pxref{Mail -Spool}). Actually, it could appear as a mix of @code{nnml} and -@code{nndraft}. If you know @code{nnml}, you're already familiar with -the message storing scheme of @code{nndiary}: one file per message, one -directory per group. - - Before anything, there is one requirement to be able to run -@code{nndiary} properly: you @emph{must} use the group timestamp feature -of Gnus. This adds a timestamp to each group's parameters. @ref{Group -Timestamp} to see how it's done. - -@menu -* Diary Messages:: What makes a message valid for nndiary. -* Running NNDiary:: NNDiary has two modes of operation. -* Customizing NNDiary:: Bells and whistles. -@end menu - -@node Diary Messages -@subsubsection Diary Messages -@cindex nndiary messages -@cindex nndiary mails - -@code{nndiary} messages are just normal ones, except for the mandatory -presence of 7 special headers. These headers are of the form -@code{X-Diary-}, @code{} being one of -@code{Minute}, @code{Hour}, @code{Dom}, @code{Month}, @code{Year}, -@code{Time-Zone} and @code{Dow}. @code{Dom} means ``Day of Month'', and -@code{dow} means ``Day of Week''. These headers actually behave like -crontab specifications and define the event date(s): - -@itemize @bullet -@item -For all headers except the @code{Time-Zone} one, a header value is -either a star (meaning all possible values), or a list of fields -(separated by a comma). -@item -A field is either an integer, or a range. -@item -A range is two integers separated by a dash. -@item -Possible integer values are 0--59 for @code{Minute}, 0--23 for -@code{Hour}, 1--31 for @code{Dom}, 1--12 for @code{Month}, above 1971 -for @code{Year} and 0--6 for @code{Dow} (0 meaning Sunday). -@item -As a special case, a star in either @code{Dom} or @code{Dow} doesn't -mean ``all possible values'', but ``use only the other field''. Note -that if both are star'ed, the use of either one gives the same result. -@item -The @code{Time-Zone} header is special in that it can only have one -value (@code{GMT}, for instance). A star doesn't mean ``all possible -values'' (because it makes no sense), but ``the current local time -zone''. Most of the time, you'll be using a star here. However, for a -list of available time zone values, see the variable -@code{nndiary-headers}. -@end itemize - -As a concrete example, here are the diary headers to add to your message -for specifying ``Each Monday and each 1st of month, at 12:00, 20:00, -21:00, 22:00, 23:00 and 24:00, from 1999 to 2010'' (I'll let you find -what to do then): - -@example -X-Diary-Minute: 0 -X-Diary-Hour: 12, 20-24 -X-Diary-Dom: 1 -X-Diary-Month: * -X-Diary-Year: 1999-2010 -X-Diary-Dow: 1 -X-Diary-Time-Zone: * -@end example - -@node Running NNDiary -@subsubsection Running NNDiary -@cindex running nndiary -@cindex nndiary operation modes - -@code{nndiary} has two modes of operation: ``traditional'' (the default) -and ``autonomous''. In traditional mode, @code{nndiary} does not get new -mail by itself. You have to move (@kbd{B m}) or copy (@kbd{B c}) mails -from your primary mail back end to nndiary groups in order to handle them -as diary messages. In autonomous mode, @code{nndiary} retrieves its own -mail and handles it independently from your primary mail back end. - -One should note that Gnus is not inherently designed to allow several -``master'' mail back ends at the same time. However, this does make -sense with @code{nndiary}: you really want to send and receive diary -messages to your diary groups directly. So, @code{nndiary} supports -being sort of a ``second primary mail back end'' (to my knowledge, it is -the only back end offering this feature). However, there is a limitation -(which I hope to fix some day): respooling doesn't work in autonomous -mode. - -In order to use @code{nndiary} in autonomous mode, you have several -things to do: - -@itemize @bullet -@item -Allow @code{nndiary} to retrieve new mail by itself. Put the following -line in your @file{~/.gnus.el} file: - -@lisp -(setq nndiary-get-new-mail t) -@end lisp -@item -You must arrange for diary messages (those containing @code{X-Diary-*} -headers) to be split in a private folder @emph{before} Gnus treat them. -Again, this is needed because Gnus cannot (yet ?) properly handle -multiple primary mail back ends. Getting those messages from a separate -source will compensate this misfeature to some extent. - -As an example, here's my procmailrc entry to store diary files in -@file{~/.nndiary} (the default @code{nndiary} mail source file): - -@example -:0 HD : -* ^X-Diary -.nndiary -@end example -@end itemize - -Once this is done, you might want to customize the following two options -that affect the diary mail retrieval and splitting processes: - -@defvar nndiary-mail-sources -This is the diary-specific replacement for the standard -@code{mail-sources} variable. It obeys the same syntax, and defaults to -@code{(file :path "~/.nndiary")}. -@end defvar - -@defvar nndiary-split-methods -This is the diary-specific replacement for the standard -@code{nnmail-split-methods} variable. It obeys the same syntax. -@end defvar - - Finally, you may add a permanent @code{nndiary} virtual server -(something like @code{(nndiary "diary")} should do) to your -@code{gnus-secondary-select-methods}. - - Hopefully, almost everything (see the TODO section in -@file{nndiary.el}) will work as expected when you restart Gnus: in -autonomous mode, typing @kbd{g} and @kbd{M-g} in the group buffer, will -also get your new diary mails and split them according to your -diary-specific rules, @kbd{F} will find your new diary groups etc. - -@node Customizing NNDiary -@subsubsection Customizing NNDiary -@cindex customizing nndiary -@cindex nndiary customization - -Now that @code{nndiary} is up and running, it's time to customize it. -The custom group is called @code{nndiary} (no, really ?!). You should -browse it to figure out which options you'd like to tweak. The following -two variables are probably the only ones you will want to change: - -@defvar nndiary-reminders -This is the list of times when you want to be reminded of your -appointments (e.g. 3 weeks before, then 2 days before, then 1 hour -before and that's it). Remember that ``being reminded'' means that the -diary message will pop up as brand new and unread again when you get new -mail. -@end defvar - -@defvar nndiary-week-starts-on-monday -Rather self-explanatory. Otherwise, Sunday is assumed (this is the -default). -@end defvar - - -@node The Gnus Diary Library -@subsection The Gnus Diary Library -@cindex gnus-diary -@cindex the gnus diary library - -Using @code{nndiary} manually (I mean, writing the headers by hand and -so on) would be rather boring. Fortunately, there is a library called -@code{gnus-diary} written on top of @code{nndiary}, that does many -useful things for you. - - In order to use it, add the following line to your @file{~/.gnus.el} file: - -@lisp -(require 'gnus-diary) -@end lisp - - Also, you shouldn't use any @code{gnus-user-format-function-[d|D]} -(@pxref{Summary Buffer Lines}). @code{gnus-diary} provides both of these -(sorry if you used them before). - - -@menu -* Diary Summary Line Format:: A nicer summary buffer line format. -* Diary Articles Sorting:: A nicer way to sort messages. -* Diary Headers Generation:: Not doing it manually. -* Diary Group Parameters:: Not handling them manually. -@end menu - -@node Diary Summary Line Format -@subsubsection Diary Summary Line Format -@cindex diary summary buffer line -@cindex diary summary line format - -Displaying diary messages in standard summary line format (usually -something like @samp{From Joe: Subject}) is pretty useless. Most of -the time, you're the one who wrote the message, and you mostly want to -see the event's date. - - @code{gnus-diary} provides two supplemental user formats to be used in -summary line formats. @code{D} corresponds to a formatted time string -for the next occurrence of the event (e.g. ``Sat, Sep 22 01, 12:00''), -while @code{d} corresponds to an approximative remaining time until the -next occurrence of the event (e.g. ``in 6 months, 1 week''). - - For example, here's how Joe's birthday is displayed in my -@code{nndiary+diary:birthdays} summary buffer (note that the message is -expirable, but will never be deleted, as it specifies a periodic event): - -@example - E Sat, Sep 22 01, 12:00: Joe's birthday (in 6 months, 1 week) -@end example - -In order to get something like the above, you would normally add the -following line to your diary groups'parameters: - -@lisp -(gnus-summary-line-format "%U%R%z %uD: %(%s%) (%ud)\n") -@end lisp - -However, @code{gnus-diary} does it automatically (@pxref{Diary Group -Parameters}). You can however customize the provided summary line format -with the following user options: - -@defvar gnus-diary-summary-line-format -Defines the summary line format used for diary groups (@pxref{Summary -Buffer Lines}). @code{gnus-diary} uses it to automatically update the -diary groups'parameters. -@end defvar - -@defvar gnus-diary-time-format -Defines the format to display dates in diary summary buffers. This is -used by the @code{D} user format. See the docstring for details. -@end defvar - -@defvar gnus-diary-delay-format-function -Defines the format function to use for displaying delays (remaining -times) in diary summary buffers. This is used by the @code{d} user -format. There are currently built-in functions for English and French; -you can also define your own. See the docstring for details. -@end defvar - -@node Diary Articles Sorting -@subsubsection Diary Articles Sorting -@cindex diary articles sorting -@cindex diary summary lines sorting -@findex gnus-summary-sort-by-schedule -@findex gnus-thread-sort-by-schedule -@findex gnus-article-sort-by-schedule - -@code{gnus-diary} provides new sorting functions (@pxref{Sorting the -Summary Buffer} ) called @code{gnus-summary-sort-by-schedule}, -@code{gnus-thread-sort-by-schedule} and -@code{gnus-article-sort-by-schedule}. These functions let you organize -your diary summary buffers from the closest event to the farthest one. - -@code{gnus-diary} automatically installs -@code{gnus-summary-sort-by-schedule} as a menu item in the summary -buffer's ``sort'' menu, and the two others as the primary (hence -default) sorting functions in the group parameters (@pxref{Diary Group -Parameters}). - -@node Diary Headers Generation -@subsubsection Diary Headers Generation -@cindex diary headers generation -@findex gnus-diary-check-message - -@code{gnus-diary} provides a function called -@code{gnus-diary-check-message} to help you handle the @code{X-Diary-*} -headers. This function ensures that the current message contains all the -required diary headers, and prompts you for values or corrections if -needed. - - This function is hooked into the @code{nndiary} back end, so that -moving or copying an article to a diary group will trigger it -automatically. It is also bound to @kbd{C-c C-f d} in -@code{message-mode} and @code{article-edit-mode} in order to ease the -process of converting a usual mail to a diary one. - - This function takes a prefix argument which will force prompting of -all diary headers, regardless of their presence or validity. That way, -you can very easily reschedule an already valid diary message, for -instance. - -@node Diary Group Parameters -@subsubsection Diary Group Parameters -@cindex diary group parameters - -When you create a new diary group, or visit one, @code{gnus-diary} -automatically checks your group parameters and if needed, sets the -summary line format to the diary-specific value, installs the -diary-specific sorting functions, and also adds the different -@code{X-Diary-*} headers to the group's posting-style. It is then easier -to send a diary message, because if you use @kbd{C-u a} or @kbd{C-u m} -on a diary group to prepare a message, these headers will be inserted -automatically (although not filled with proper values yet). - -@node Sending or Not Sending -@subsection Sending or Not Sending - -Well, assuming you've read all of the above, here are two final notes on -mail sending with @code{nndiary}: - -@itemize @bullet -@item -@code{nndiary} is a @emph{real} mail back end. You really send real diary -messsages for real. This means for instance that you can give -appointments to anybody (provided they use Gnus and @code{nndiary}) by -sending the diary message to them as well. -@item -However, since @code{nndiary} also has a @code{request-post} method, you -can also use @kbd{C-u a} instead of @kbd{C-u m} on a diary group and the -message won't actually be sent; just stored locally in the group. This -comes in very handy for private appointments. -@end itemize - -@node Gnus Unplugged -@section Gnus Unplugged -@cindex offline -@cindex unplugged -@cindex agent -@cindex Gnus agent -@cindex Gnus unplugged - -In olden times (ca. February '88), people used to run their newsreaders -on big machines with permanent connections to the net. News transport -was dealt with by news servers, and all the newsreaders had to do was to -read news. Believe it or not. - -Nowadays most people read news and mail at home, and use some sort of -modem to connect to the net. To avoid running up huge phone bills, it -would be nice to have a way to slurp down all the news and mail, hang up -the phone, read for several hours, and then upload any responses you -have to make. And then you repeat the procedure. - -Of course, you can use news servers for doing this as well. I've used -@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} -for some years, but doing that's a bore. Moving the news server -functionality up to the newsreader makes sense if you're the only person -reading news on a machine. - -Setting up Gnus as an ``offline'' newsreader is quite simple. In -fact, you don't have to configure anything as the agent is now enabled -by default (@pxref{Agent Variables, gnus-agent}). - -Of course, to use it as such, you have to learn a few new commands. - -@menu -* Agent Basics:: How it all is supposed to work. -* Agent Categories:: How to tell the Gnus Agent what to download. -* Agent Commands:: New commands for all the buffers. -* Agent Visuals:: Ways that the agent may effect your summary buffer. -* Agent as Cache:: The Agent is a big cache too. -* Agent Expiry:: How to make old articles go away. -* Agent Regeneration:: How to recover from lost connections and other accidents. -* Agent and flags:: How the Agent maintains flags. -* Agent and IMAP:: How to use the Agent with @acronym{IMAP}. -* Outgoing Messages:: What happens when you post/mail something? -* Agent Variables:: Customizing is fun. -* Example Setup:: An example @file{~/.gnus.el} file for offline people. -* Batching Agents:: How to fetch news from a @code{cron} job. -* Agent Caveats:: What you think it'll do and what it does. -@end menu - - -@node Agent Basics -@subsection Agent Basics - -First, let's get some terminology out of the way. - -The Gnus Agent is said to be @dfn{unplugged} when you have severed the -connection to the net (and notified the Agent that this is the case). -When the connection to the net is up again (and Gnus knows this), the -Agent is @dfn{plugged}. - -The @dfn{local} machine is the one you're running on, and which isn't -connected to the net continuously. - -@dfn{Downloading} means fetching things from the net to your local -machine. @dfn{Uploading} is doing the opposite. - -You know that Gnus gives you all the opportunity you'd ever want for -shooting yourself in the foot. Some people call it flexibility. Gnus -is also customizable to a great extent, which means that the user has a -say on how Gnus behaves. Other newsreaders might unconditionally shoot -you in your foot, but with Gnus, you have a choice! - -Gnus is never really in plugged or unplugged state. Rather, it applies -that state to each server individually. This means that some servers -can be plugged while others can be unplugged. Additionally, some -servers can be ignored by the Agent altogether (which means that -they're kinda like plugged always). - -So when you unplug the Agent and then wonder why is Gnus opening a -connection to the Net, the next step to do is to look whether all -servers are agentized. If there is an unagentized server, you found -the culprit. - -Another thing is the @dfn{offline} state. Sometimes, servers aren't -reachable. When Gnus notices this, it asks you whether you want the -server to be switched to offline state. If you say yes, then the -server will behave somewhat as if it was unplugged, except that Gnus -will ask you whether you want to switch it back online again. - -Let's take a typical Gnus session using the Agent. - -@itemize @bullet - -@item -@findex gnus-unplugged -You start Gnus with @code{gnus-unplugged}. This brings up the Gnus -Agent in a disconnected state. You can read all the news that you have -already fetched while in this mode. - -@item -You then decide to see whether any new news has arrived. You connect -your machine to the net (using PPP or whatever), and then hit @kbd{J j} -to make Gnus become @dfn{plugged} and use @kbd{g} to check for new mail -as usual. To check for new mail in unplugged mode (@pxref{Mail -Source Specifiers}). - -@item -You can then read the new news immediately, or you can download the -news onto your local machine. If you want to do the latter, you press -@kbd{g} to check if there are any new news and then @kbd{J s} to fetch -all the eligible articles in all the groups. (To let Gnus know which -articles you want to download, @pxref{Agent Categories}). - -@item -After fetching the articles, you press @kbd{J j} to make Gnus become -unplugged again, and you shut down the PPP thing (or whatever). And -then you read the news offline. - -@item -And then you go to step 2. -@end itemize - -Here are some things you should do the first time (or so) that you use -the Agent. - -@itemize @bullet - -@item -Decide which servers should be covered by the Agent. If you have a mail -back end, it would probably be nonsensical to have it covered by the -Agent. Go to the server buffer (@kbd{^} in the group buffer) and press -@kbd{J a} on the server (or servers) that you wish to have covered by the -Agent (@pxref{Server Agent Commands}), or @kbd{J r} on automatically -added servers you do not wish to have covered by the Agent. By default, -all @code{nntp} and @code{nnimap} servers in @code{gnus-select-method} and -@code{gnus-secondary-select-methods} are agentized. - -@item -Decide on download policy. It's fairly simple once you decide whether -you are going to use agent categories, topic parameters, and/or group -parameters to implement your policy. If you're new to gnus, it -is probably best to start with a category, @xref{Agent Categories}. - -Both topic parameters (@pxref{Topic Parameters}) and agent categories -(@pxref{Agent Categories}) provide for setting a policy that applies -to multiple groups. Which you use is entirely up to you. Topic -parameters do override categories so, if you mix the two, you'll have -to take that into account. If you have a few groups that deviate from -your policy, you can use group parameters (@pxref{Group Parameters}) to -configure them. - -@item -Uhm@dots{} that's it. -@end itemize - - -@node Agent Categories -@subsection Agent Categories - -One of the main reasons to integrate the news transport layer into the -newsreader is to allow greater control over what articles to download. -There's not much point in downloading huge amounts of articles, just to -find out that you're not interested in reading any of them. It's better -to be somewhat more conservative in choosing what to download, and then -mark the articles for downloading manually if it should turn out that -you're interested in the articles anyway. - -One of the more effective methods for controlling what is to be -downloaded is to create a @dfn{category} and then assign some (or all) -groups to this category. Groups that do not belong in any other -category belong to the @code{default} category. Gnus has its own -buffer for creating and managing categories. - -If you prefer, you can also use group parameters (@pxref{Group -Parameters}) and topic parameters (@pxref{Topic Parameters}) for an -alternative approach to controlling the agent. The only real -difference is that categories are specific to the agent (so there is -less to learn) while group and topic parameters include the kitchen -sink. - -Since you can set agent parameters in several different places we have -a rule to decide which source to believe. This rule specifies that -the parameter sources are checked in the following order: group -parameters, topic parameters, agent category, and finally customizable -variables. So you can mix all of these sources to produce a wide range -of behavior, just don't blame me if you don't remember where you put -your settings. - -@menu -* Category Syntax:: What a category looks like. -* Category Buffer:: A buffer for maintaining categories. -* Category Variables:: Customize'r'Us. -@end menu - - -@node Category Syntax -@subsubsection Category Syntax - -A category consists of a name, the list of groups belonging to the -category, and a number of optional parameters that override the -customizable variables. The complete list of agent parameters are -listed below. - -@cindex Agent Parameters -@table @code -@item agent-groups -The list of groups that are in this category. - -@item agent-predicate -A predicate which (generally) gives a rough outline of which articles -are eligible for downloading; and - -@item agent-score -a score rule which (generally) gives you a finer granularity when -deciding what articles to download. (Note that this @dfn{download -score} is not necessarily related to normal scores.) - -@item agent-enable-expiration -a boolean indicating whether the agent should expire old articles in -this group. Most groups should be expired to conserve disk space. In -fact, its probably safe to say that the gnus.* hierarchy contains the -only groups that should not be expired. - -@item agent-days-until-old -an integer indicating the number of days that the agent should wait -before deciding that a read article is safe to expire. - -@item agent-low-score -an integer that overrides the value of @code{gnus-agent-low-score}. - -@item agent-high-score -an integer that overrides the value of @code{gnus-agent-high-score}. - -@item agent-short-article -an integer that overrides the value of -@code{gnus-agent-short-article}. - -@item agent-long-article -an integer that overrides the value of @code{gnus-agent-long-article}. - -@item agent-enable-undownloaded-faces -a symbol indicating whether the summary buffer should display -undownloaded articles using the @code{gnus-summary-*-undownloaded-face} -faces. Any symbol other than @code{nil} will enable the use of -undownloaded faces. -@end table - -The name of a category can not be changed once the category has been -created. - -Each category maintains a list of groups that are exclusive members of -that category. The exclusivity rule is automatically enforced, add a -group to a new category and it is automatically removed from its old -category. - -A predicate in its simplest form can be a single predicate such as -@code{true} or @code{false}. These two will download every available -article or nothing respectively. In the case of these two special -predicates an additional score rule is superfluous. - -Predicates of @code{high} or @code{low} download articles in respect of -their scores in relationship to @code{gnus-agent-high-score} and -@code{gnus-agent-low-score} as described below. - -To gain even finer control of what is to be regarded eligible for -download a predicate can consist of a number of predicates with logical -operators sprinkled in between. - -Perhaps some examples are in order. - -Here's a simple predicate. (It's the default predicate, in fact, used -for all groups that don't belong to any other category.) - -@lisp -short -@end lisp - -Quite simple, eh? This predicate is true if and only if the article is -short (for some value of ``short''). - -Here's a more complex predicate: - -@lisp -(or high - (and - (not low) - (not long))) -@end lisp - -This means that an article should be downloaded if it has a high score, -or if the score is not low and the article is not long. You get the -drift. - -The available logical operators are @code{or}, @code{and} and -@code{not}. (If you prefer, you can use the more ``C''-ish operators -@samp{|}, @code{&} and @code{!} instead.) - -The following predicates are pre-defined, but if none of these fit what -you want to do, you can write your own. - -When evaluating each of these predicates, the named constant will be -bound to the value determined by calling -@code{gnus-agent-find-parameter} on the appropriate parameter. For -example, gnus-agent-short-article will be bound to -@code{(gnus-agent-find-parameter group 'agent-short-article)}. This -means that you can specify a predicate in your category then tune that -predicate to individual groups. - -@table @code -@item short -True if the article is shorter than @code{gnus-agent-short-article} -lines; default 100. - -@item long -True if the article is longer than @code{gnus-agent-long-article} -lines; default 200. - -@item low -True if the article has a download score less than -@code{gnus-agent-low-score}; default 0. - -@item high -True if the article has a download score greater than -@code{gnus-agent-high-score}; default 0. - -@item spam -True if the Gnus Agent guesses that the article is spam. The -heuristics may change over time, but at present it just computes a -checksum and sees whether articles match. - -@item true -Always true. - -@item false -Always false. -@end table - -If you want to create your own predicate function, here's what you have -to know: The functions are called with no parameters, but the -@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to -useful values. - -For example, you could decide that you don't want to download articles -that were posted more than a certain number of days ago (e.g. posted -more than @code{gnus-agent-expire-days} ago) you might write a function -something along the lines of the following: - -@lisp -(defun my-article-old-p () - "Say whether an article is old." - (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) -@end lisp - -with the predicate then defined as: - -@lisp -(not my-article-old-p) -@end lisp - -or you could append your predicate to the predefined -@code{gnus-category-predicate-alist} in your @file{~/.gnus.el} or -wherever. - -@lisp -(require 'gnus-agent) -(setq gnus-category-predicate-alist - (append gnus-category-predicate-alist - '((old . my-article-old-p)))) -@end lisp - -and simply specify your predicate as: - -@lisp -(not old) -@end lisp - -If/when using something like the above, be aware that there are many -misconfigured systems/mailers out there and so an article's date is not -always a reliable indication of when it was posted. Hell, some people -just don't give a damn. - -The above predicates apply to @emph{all} the groups which belong to the -category. However, if you wish to have a specific predicate for an -individual group within a category, or you're just too lazy to set up a -new category, you can enter a group's individual predicate in its group -parameters like so: - -@lisp -(agent-predicate . short) -@end lisp - -This is the group/topic parameter equivalent of the agent category default. -Note that when specifying a single word predicate like this, the -@code{agent-predicate} specification must be in dotted pair notation. - -The equivalent of the longer example from above would be: - -@lisp -(agent-predicate or high (and (not low) (not long))) -@end lisp - -The outer parenthesis required in the category specification are not -entered here as, not being in dotted pair notation, the value of the -predicate is assumed to be a list. - - -Now, the syntax of the download score is the same as the syntax of -normal score files, except that all elements that require actually -seeing the article itself are verboten. This means that only the -following headers can be scored on: @code{Subject}, @code{From}, -@code{Date}, @code{Message-ID}, @code{References}, @code{Chars}, -@code{Lines}, and @code{Xref}. - -As with predicates, the specification of the @code{download score rule} -to use in respect of a group can be in either the category definition if -it's to be applicable to all groups in therein, or a group's parameters -if it's to be specific to that group. - -In both of these places the @code{download score rule} can take one of -three forms: - -@enumerate -@item -Score rule - -This has the same syntax as a normal Gnus score file except only a -subset of scoring keywords are available as mentioned above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -(("from" - ("Lars Ingebrigtsen" 1000000 nil s)) -("lines" - (500 -100 nil <))) -@end lisp - -@item -Group/Topic Parameter specification - -@lisp -(agent-score ("from" - ("Lars Ingebrigtsen" 1000000 nil s)) - ("lines" - (500 -100 nil <))) -@end lisp - -Again, note the omission of the outermost parenthesis here. -@end itemize - -@item -Agent score file - -These score files must @emph{only} contain the permitted scoring -keywords stated above. - -example: - -@itemize @bullet -@item -Category specification - -@lisp -("~/News/agent.SCORE") -@end lisp - -or perhaps - -@lisp -("~/News/agent.SCORE" "~/News/agent.group.SCORE") -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score "~/News/agent.SCORE") -@end lisp - -Additional score files can be specified as above. Need I say anything -about parenthesis? -@end itemize - -@item -Use @code{normal} score files - -If you don't want to maintain two sets of scoring rules for a group, and -your desired @code{downloading} criteria for a group are the same as your -@code{reading} criteria then you can tell the agent to refer to your -@code{normal} score files when deciding what to download. - -These directives in either the category definition or a group's -parameters will cause the agent to read in all the applicable score -files for a group, @emph{filtering out} those sections that do not -relate to one of the permitted subset of scoring keywords. - -@itemize @bullet -@item -Category Specification - -@lisp -file -@end lisp - -@item -Group Parameter specification - -@lisp -(agent-score . file) -@end lisp -@end itemize -@end enumerate - -@node Category Buffer -@subsubsection Category Buffer - -You'd normally do all category maintenance from the category buffer. -When you enter it for the first time (with the @kbd{J c} command from -the group buffer), you'll only see the @code{default} category. - -The following commands are available in this buffer: - -@table @kbd -@item q -@kindex q (Category) -@findex gnus-category-exit -Return to the group buffer (@code{gnus-category-exit}). - -@item e -@kindex e (Category) -@findex gnus-category-customize-category -Use a customization buffer to set all of the selected category's -parameters at one time (@code{gnus-category-customize-category}). - -@item k -@kindex k (Category) -@findex gnus-category-kill -Kill the current category (@code{gnus-category-kill}). - -@item c -@kindex c (Category) -@findex gnus-category-copy -Copy the current category (@code{gnus-category-copy}). - -@item a -@kindex a (Category) -@findex gnus-category-add -Add a new category (@code{gnus-category-add}). - -@item p -@kindex p (Category) -@findex gnus-category-edit-predicate -Edit the predicate of the current category -(@code{gnus-category-edit-predicate}). - -@item g -@kindex g (Category) -@findex gnus-category-edit-groups -Edit the list of groups belonging to the current category -(@code{gnus-category-edit-groups}). - -@item s -@kindex s (Category) -@findex gnus-category-edit-score -Edit the download score rule of the current category -(@code{gnus-category-edit-score}). - -@item l -@kindex l (Category) -@findex gnus-category-list -List all the categories (@code{gnus-category-list}). -@end table - - -@node Category Variables -@subsubsection Category Variables - -@table @code -@item gnus-category-mode-hook -@vindex gnus-category-mode-hook -Hook run in category buffers. - -@item gnus-category-line-format -@vindex gnus-category-line-format -Format of the lines in the category buffer (@pxref{Formatting -Variables}). Valid elements are: - -@table @samp -@item c -The name of the category. - -@item g -The number of groups in the category. -@end table - -@item gnus-category-mode-line-format -@vindex gnus-category-mode-line-format -Format of the category mode line (@pxref{Mode Line Formatting}). - -@item gnus-agent-short-article -@vindex gnus-agent-short-article -Articles that have fewer lines than this are short. Default 100. - -@item gnus-agent-long-article -@vindex gnus-agent-long-article -Articles that have more lines than this are long. Default 200. - -@item gnus-agent-low-score -@vindex gnus-agent-low-score -Articles that have a score lower than this have a low score. Default -0. - -@item gnus-agent-high-score -@vindex gnus-agent-high-score -Articles that have a score higher than this have a high score. Default -0. - -@item gnus-agent-expire-days -@vindex gnus-agent-expire-days -The number of days that a @samp{read} article must stay in the agent's -local disk before becoming eligible for expiration (While the name is -the same, this doesn't mean expiring the article on the server. It -just means deleting the local copy of the article). What is also -important to understand is that the counter starts with the time the -article was written to the local disk and not the time the article was -read. -Default 7. - -@item gnus-agent-enable-expiration -@vindex gnus-agent-enable-expiration -Determines whether articles in a group are, by default, expired or -retained indefinitely. The default is @code{ENABLE} which means that -you'll have to disable expiration when desired. On the other hand, -you could set this to @code{DISABLE}. In that case, you would then -have to enable expiration in selected groups. - -@end table - - -@node Agent Commands -@subsection Agent Commands -@findex gnus-agent-toggle-plugged -@kindex J j (Agent) - -All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} -(@code{gnus-agent-toggle-plugged}) command works in all modes, and -toggles the plugged/unplugged state of the Gnus Agent. - - -@menu -* Group Agent Commands:: Configure groups and fetch their contents. -* Summary Agent Commands:: Manually select then fetch specific articles. -* Server Agent Commands:: Select the servers that are supported by the agent. -@end menu - - - - -@node Group Agent Commands -@subsubsection Group Agent Commands - -@table @kbd -@item J u -@kindex J u (Agent Group) -@findex gnus-agent-fetch-groups -Fetch all eligible articles in the current group -(@code{gnus-agent-fetch-groups}). - -@item J c -@kindex J c (Agent Group) -@findex gnus-enter-category-buffer -Enter the Agent category buffer (@code{gnus-enter-category-buffer}). - -@item J s -@kindex J s (Agent Group) -@findex gnus-agent-fetch-session -Fetch all eligible articles in all groups -(@code{gnus-agent-fetch-session}). - -@item J S -@kindex J S (Agent Group) -@findex gnus-group-send-queue -Send all sendable messages in the queue group -(@code{gnus-group-send-queue}). @xref{Drafts}. - -@item J a -@kindex J a (Agent Group) -@findex gnus-agent-add-group -Add the current group to an Agent category -(@code{gnus-agent-add-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J r -@kindex J r (Agent Group) -@findex gnus-agent-remove-group -Remove the current group from its category, if any -(@code{gnus-agent-remove-group}). This command understands the -process/prefix convention (@pxref{Process/Prefix}). - -@item J Y -@kindex J Y (Agent Group) -@findex gnus-agent-synchronize-flags -Synchronize flags changed while unplugged with remote server, if any. - - -@end table - - -@node Summary Agent Commands -@subsubsection Summary Agent Commands - -@table @kbd -@item J # -@kindex J # (Agent Summary) -@findex gnus-agent-mark-article -Mark the article for downloading (@code{gnus-agent-mark-article}). - -@item J M-# -@kindex J M-# (Agent Summary) -@findex gnus-agent-unmark-article -Remove the downloading mark from the article -(@code{gnus-agent-unmark-article}). - -@cindex % -@item @@ -@kindex @@ (Agent Summary) -@findex gnus-agent-toggle-mark -Toggle whether to download the article -(@code{gnus-agent-toggle-mark}). The download mark is @samp{%} by -default. - -@item J c -@kindex J c (Agent Summary) -@findex gnus-agent-catchup -Mark all articles as read (@code{gnus-agent-catchup}) that are neither cached, downloaded, nor downloadable. - -@item J S -@kindex J S (Agent Summary) -@findex gnus-agent-fetch-group -Download all eligible (@pxref{Agent Categories}) articles in this group. -(@code{gnus-agent-fetch-group}). - -@item J s -@kindex J s (Agent Summary) -@findex gnus-agent-summary-fetch-series -Download all processable articles in this group. -(@code{gnus-agent-summary-fetch-series}). - -@item J u -@kindex J u (Agent Summary) -@findex gnus-agent-summary-fetch-group -Download all downloadable articles in the current group -(@code{gnus-agent-summary-fetch-group}). - -@end table - - -@node Server Agent Commands -@subsubsection Server Agent Commands - -@table @kbd -@item J a -@kindex J a (Agent Server) -@findex gnus-agent-add-server -Add the current server to the list of servers covered by the Gnus Agent -(@code{gnus-agent-add-server}). - -@item J r -@kindex J r (Agent Server) -@findex gnus-agent-remove-server -Remove the current server from the list of servers covered by the Gnus -Agent (@code{gnus-agent-remove-server}). - -@end table - - -@node Agent Visuals -@subsection Agent Visuals - -If you open a summary while unplugged and, Gnus knows from the group's -active range that there are more articles than the headers currently -stored in the Agent, you may see some articles whose subject looks -something like @samp{[Undownloaded article #####]}. These are -placeholders for the missing headers. Aside from setting a mark, -there is not much that can be done with one of these placeholders. -When Gnus finally gets a chance to fetch the group's headers, the -placeholders will automatically be replaced by the actual headers. -You can configure the summary buffer's maneuvering to skip over the -placeholders if you care (See @code{gnus-auto-goto-ignores}). - -While it may be obvious to all, the only headers and articles -available while unplugged are those headers and articles that were -fetched into the Agent while previously plugged. To put it another -way, ``If you forget to fetch something while plugged, you might have a -less than satisfying unplugged session''. For this reason, the Agent -adds two visual effects to your summary buffer. These effects display -the download status of each article so that you always know which -articles will be available when unplugged. - -The first visual effect is the @samp{%O} spec. If you customize -@code{gnus-summary-line-format} to include this specifier, you will add -a single character field that indicates an article's download status. -Articles that have been fetched into either the Agent or the Cache, -will display @code{gnus-downloaded-mark} (defaults to @samp{+}). All -other articles will display @code{gnus-undownloaded-mark} (defaults to -@samp{-}). If you open a group that has not been agentized, a space -(@samp{ }) will be displayed. - -The second visual effect are the undownloaded faces. The faces, there -are three indicating the article's score (low, normal, high), seem to -result in a love/hate response from many Gnus users. The problem is -that the face selection is controlled by a list of condition tests and -face names (See @code{gnus-summary-highlight}). Each condition is -tested in the order in which it appears in the list so early -conditions have precedence over later conditions. All of this means -that, if you tick an undownloaded article, the article will continue -to be displayed in the undownloaded face rather than the ticked face. - -If you use the Agent as a cache (to avoid downloading the same article -each time you visit it or to minimize your connection time), the -undownloaded face will probably seem like a good idea. The reason -being that you do all of our work (marking, reading, deleting) with -downloaded articles so the normal faces always appear. For those -users using the agent to improve online performance by caching the NOV -database (most users since 5.10.2), the undownloaded faces may appear -to be an absolutely horrible idea. The issue being that, since none -of their articles have been fetched into the Agent, all of the -normal faces will be obscured by the undownloaded faces. - -If you would like to use the undownloaded faces, you must enable the -undownloaded faces by setting the @code{agent-enable-undownloaded-faces} -group parameter to @code{t}. This parameter, like all other agent -parameters, may be set on an Agent Category (@pxref{Agent Categories}), -a Group Topic (@pxref{Topic Parameters}), or an individual group -(@pxref{Group Parameters}). - -The one problem common to all users using the agent is how quickly it -can consume disk space. If you using the agent on many groups, it is -even more difficult to effectively recover disk space. One solution -is the @samp{%F} format available in @code{gnus-group-line-format}. -This format will display the actual disk space used by articles -fetched into both the agent and cache. By knowing which groups use -the most space, users know where to focus their efforts when ``agent -expiring'' articles. - -@node Agent as Cache -@subsection Agent as Cache - -When Gnus is plugged, it is not efficient to download headers or -articles from the server again, if they are already stored in the -Agent. So, Gnus normally only downloads headers once, and stores them -in the Agent. These headers are later used when generating the summary -buffer, regardless of whether you are plugged or unplugged. Articles -are not cached in the Agent by default though (that would potentially -consume lots of disk space), but if you have already downloaded an -article into the Agent, Gnus will not download the article from the -server again but use the locally stored copy instead. - -If you so desire, you can configure the agent (see @code{gnus-agent-cache} -@pxref{Agent Variables}) to always download headers and articles while -plugged. Gnus will almost certainly be slower, but it will be kept -synchronized with the server. That last point probably won't make any -sense if you are using a nntp or nnimap back end. - -@node Agent Expiry -@subsection Agent Expiry - -@vindex gnus-agent-expire-days -@findex gnus-agent-expire -@kindex M-x gnus-agent-expire -@kindex M-x gnus-agent-expire-group -@findex gnus-agent-expire-group -@cindex agent expiry -@cindex Gnus agent expiry -@cindex expiry, in Gnus agent - -The Agent back end, @code{nnagent}, doesn't handle expiry. Well, at -least it doesn't handle it like other back ends. Instead, there are -special @code{gnus-agent-expire} and @code{gnus-agent-expire-group} -commands that will expire all read articles that are older than -@code{gnus-agent-expire-days} days. They can be run whenever you feel -that you're running out of space. Neither are particularly fast or -efficient, and it's not a particularly good idea to interrupt them (with -@kbd{C-g} or anything else) once you've started one of them. - -Note that other functions, e.g. @code{gnus-request-expire-articles}, -might run @code{gnus-agent-expire} for you to keep the agent -synchronized with the group. - -The agent parameter @code{agent-enable-expiration} may be used to -prevent expiration in selected groups. - -@vindex gnus-agent-expire-all -If @code{gnus-agent-expire-all} is non-@code{nil}, the agent -expiration commands will expire all articles---unread, read, ticked -and dormant. If @code{nil} (which is the default), only read articles -are eligible for expiry, and unread, ticked and dormant articles will -be kept indefinitely. - -If you find that some articles eligible for expiry are never expired, -perhaps some Gnus Agent files are corrupted. There's are special -commands, @code{gnus-agent-regenerate} and -@code{gnus-agent-regenerate-group}, to fix possible problems. - -@node Agent Regeneration -@subsection Agent Regeneration - -@cindex agent regeneration -@cindex Gnus agent regeneration -@cindex regeneration - -The local data structures used by @code{nnagent} may become corrupted -due to certain exceptional conditions. When this happens, -@code{nnagent} functionality may degrade or even fail. The solution -to this problem is to repair the local data structures by removing all -internal inconsistencies. - -For example, if your connection to your server is lost while -downloaded articles into the agent, the local data structures will not -know about articles successfully downloaded prior to the connection -failure. Running @code{gnus-agent-regenerate} or -@code{gnus-agent-regenerate-group} will update the data structures -such that you don't need to download these articles a second time. - -@findex gnus-agent-regenerate -@kindex M-x gnus-agent-regenerate -The command @code{gnus-agent-regenerate} will perform -@code{gnus-agent-regenerate-group} on every agentized group. While -you can run @code{gnus-agent-regenerate} in any buffer, it is strongly -recommended that you first close all summary buffers. - -@findex gnus-agent-regenerate-group -@kindex M-x gnus-agent-regenerate-group -The command @code{gnus-agent-regenerate-group} uses the local copies -of individual articles to repair the local @acronym{NOV}(header) database. It -then updates the internal data structures that document which articles -are stored locally. An optional argument will mark articles in the -agent as unread. - -@node Agent and flags -@subsection Agent and flags - -The Agent works with any Gnus back end including those, such as -nnimap, that store flags (read, ticked, etc) on the server. Sadly, -the Agent does not actually know which backends keep their flags in -the backend server rather than in @file{.newsrc}. This means that the -Agent, while unplugged or disconnected, will always record all changes -to the flags in its own files. - -When you plug back in, Gnus will then check to see if you have any -changed any flags and ask if you wish to synchronize these with the -server. This behavior is customizable by @code{gnus-agent-synchronize-flags}. - -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -If you do not wish to synchronize flags automatically when you -re-connect, you can do it manually with the -@code{gnus-agent-synchronize-flags} command that is bound to @kbd{J Y} -in the group buffer. - -Technical note: the synchronization algorithm does not work by ``pushing'' -all local flags to the server, but rather by incrementally updated the -server view of flags by changing only those flags that were changed by -the user. Thus, if you set one flag on an article, quit the group then -re-select the group and remove the flag; the flag will be set and -removed from the server when you ``synchronize''. The queued flag -operations can be found in the per-server @code{flags} file in the Agent -directory. It's emptied when you synchronize flags. - -@node Agent and IMAP -@subsection Agent and IMAP - -The Agent works with any Gnus back end, including nnimap. However, -since there are some conceptual differences between @acronym{NNTP} and -@acronym{IMAP}, this section (should) provide you with some information to -make Gnus Agent work smoother as a @acronym{IMAP} Disconnected Mode client. - -Some things are currently not implemented in the Agent that you'd might -expect from a disconnected @acronym{IMAP} client, including: - -@itemize @bullet - -@item -Copying/moving articles into nnimap groups when unplugged. - -@item -Creating/deleting nnimap groups when unplugged. - -@end itemize - -@node Outgoing Messages -@subsection Outgoing Messages - -By default, when Gnus is unplugged, all outgoing messages (both mail -and news) are stored in the draft group ``queue'' (@pxref{Drafts}). -You can view them there after posting, and edit them at will. - -You can control the circumstances under which outgoing mail is queued -(see @code{gnus-agent-queue-mail}, @pxref{Agent Variables}). Outgoing -news is always queued when Gnus is unplugged, and never otherwise. - -You can send the messages either from the draft group with the special -commands available there, or you can use the @kbd{J S} command in the -group buffer to send all the sendable messages in the draft group. -Posting news will only work when Gnus is plugged, but you can send -mail at any time. - -If sending mail while unplugged does not work for you and you worry -about hitting @kbd{J S} by accident when unplugged, you can have Gnus -ask you to confirm your action (see -@code{gnus-agent-prompt-send-queue}, @pxref{Agent Variables}). - -@node Agent Variables -@subsection Agent Variables - -@table @code -@item gnus-agent -@vindex gnus-agent -Is the agent enabled? The default is @code{t}. When first enabled, -the agent will use @code{gnus-agent-auto-agentize-methods} to -automatically mark some back ends as agentized. You may change which -back ends are agentized using the agent commands in the server buffer. - -To enter the server buffer, use the @kbd{^} -(@code{gnus-group-enter-server-mode}) command in the group buffer. - - -@item gnus-agent-directory -@vindex gnus-agent-directory -Where the Gnus Agent will store its files. The default is -@file{~/News/agent/}. - -@item gnus-agent-handle-level -@vindex gnus-agent-handle-level -Groups on levels (@pxref{Group Levels}) higher than this variable will -be ignored by the Agent. The default is @code{gnus-level-subscribed}, -which means that only subscribed group will be considered by the Agent -by default. - -@item gnus-agent-plugged-hook -@vindex gnus-agent-plugged-hook -Hook run when connecting to the network. - -@item gnus-agent-unplugged-hook -@vindex gnus-agent-unplugged-hook -Hook run when disconnecting from the network. - -@item gnus-agent-fetched-hook -@vindex gnus-agent-fetched-hook -Hook run when finished fetching articles. - -@item gnus-agent-cache -@vindex gnus-agent-cache -Variable to control whether use the locally stored @acronym{NOV} and -articles when plugged, e.g. essentially using the Agent as a cache. -The default is non-@code{nil}, which means to use the Agent as a cache. - -@item gnus-agent-go-online -@vindex gnus-agent-go-online -If @code{gnus-agent-go-online} is @code{nil}, the Agent will never -automatically switch offline servers into online status. If it is -@code{ask}, the default, the Agent will ask if you wish to switch -offline servers into online status when you re-connect. If it has any -other value, all offline servers will be automatically switched into -online status. - -@item gnus-agent-mark-unread-after-downloaded -@vindex gnus-agent-mark-unread-after-downloaded -If @code{gnus-agent-mark-unread-after-downloaded} is non-@code{nil}, -mark articles as unread after downloading. This is usually a safe -thing to do as the newly downloaded article has obviously not been -read. The default is @code{t}. - -@item gnus-agent-synchronize-flags -@vindex gnus-agent-synchronize-flags -If @code{gnus-agent-synchronize-flags} is @code{nil}, the Agent will -never automatically synchronize flags. If it is @code{ask}, which is -the default, the Agent will check if you made any changes and if so -ask if you wish to synchronize these when you re-connect. If it has -any other value, all flags will be synchronized automatically. - -@item gnus-agent-consider-all-articles -@vindex gnus-agent-consider-all-articles -If @code{gnus-agent-consider-all-articles} is non-@code{nil}, the -agent will let the agent predicate decide whether articles need to be -downloaded or not, for all articles. When @code{nil}, the default, -the agent will only let the predicate decide whether unread articles -are downloaded or not. If you enable this, you may also want to look -into the agent expiry settings (@pxref{Category Variables}), so that -the agent doesn't download articles which the agent will later expire, -over and over again. - -@item gnus-agent-max-fetch-size -@vindex gnus-agent-max-fetch-size -The agent fetches articles into a temporary buffer prior to parsing -them into individual files. To avoid exceeding the max. buffer size, -the agent alternates between fetching and parsing until all articles -have been fetched. @code{gnus-agent-max-fetch-size} provides a size -limit to control how often the cycling occurs. A large value improves -performance. A small value minimizes the time lost should the -connection be lost while fetching (You may need to run -@code{gnus-agent-regenerate-group} to update the group's state. -However, all articles parsed prior to loosing the connection will be -available while unplugged). The default is 10M so it is unusual to -see any cycling. - -@item gnus-server-unopen-status -@vindex gnus-server-unopen-status -Perhaps not an Agent variable, but closely related to the Agent, this -variable says what will happen if Gnus cannot open a server. If the -Agent is enabled, the default, @code{nil}, makes Gnus ask the user -whether to deny the server or whether to unplug the agent. If the -Agent is disabled, Gnus always simply deny the server. Other choices -for this variable include @code{denied} and @code{offline} the latter -is only valid if the Agent is used. - -@item gnus-auto-goto-ignores -@vindex gnus-auto-goto-ignores -Another variable that isn't an Agent variable, yet so closely related -that most will look for it here, this variable tells the summary -buffer how to maneuver around undownloaded (only headers stored in the -agent) and unfetched (neither article nor headers stored) articles. - -The valid values are @code{nil} (maneuver to any article), -@code{undownloaded} (maneuvering while unplugged ignores articles that -have not been fetched), @code{always-undownloaded} (maneuvering always -ignores articles that have not been fetched), @code{unfetched} -(maneuvering ignores articles whose headers have not been fetched). - -@item gnus-agent-queue-mail -@vindex gnus-agent-queue-mail -When @code{gnus-agent-queue-mail} is @code{always}, Gnus will always -queue mail rather than sending it straight away. When @code{t}, Gnus -will queue mail when unplugged only. When @code{nil}, never queue -mail. The default is @code{t}. - -@item gnus-agent-prompt-send-queue -@vindex gnus-agent-prompt-send-queue -When @code{gnus-agent-prompt-send-queue} is non-@code{nil} Gnus will -prompt you to confirm that you really wish to proceed if you hit -@kbd{J S} while unplugged. The default is @code{nil}. - -@item gnus-agent-auto-agentize-methods -@vindex gnus-agent-auto-agentize-methods -If you have never used the Agent before (or more technically, if -@file{~/News/agent/lib/servers} does not exist), Gnus will -automatically agentize a few servers for you. This variable control -which back ends should be auto-agentized. It is typically only useful -to agentize remote back ends. The auto-agentizing has the same effect -as running @kbd{J a} on the servers (@pxref{Server Agent Commands}). -If the file exist, you must manage the servers manually by adding or -removing them, this variable is only applicable the first time you -start Gnus. The default is @samp{(nntp nnimap)}. - -@end table - - -@node Example Setup -@subsection Example Setup - -If you don't want to read this manual, and you have a fairly standard -setup, you may be able to use something like the following as your -@file{~/.gnus.el} file to get started. - -@lisp -;; @r{Define how Gnus is to fetch news. We do this over @acronym{NNTP}} -;; @r{from your ISP's server.} -(setq gnus-select-method '(nntp "news.your-isp.com")) - -;; @r{Define how Gnus is to read your mail. We read mail from} -;; @r{your ISP's @acronym{POP} server.} -(setq mail-sources '((pop :server "pop.your-isp.com"))) - -;; @r{Say how Gnus is to store the mail. We use nnml groups.} -(setq gnus-secondary-select-methods '((nnml ""))) - -;; @r{Make Gnus into an offline newsreader.} -;; (gnus-agentize) ; @r{The obsolete setting.} -;; (setq gnus-agent t) ; @r{Now the default.} -@end lisp - -That should be it, basically. Put that in your @file{~/.gnus.el} file, -edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x -gnus}. - -If this is the first time you've run Gnus, you will be subscribed -automatically to a few default newsgroups. You'll probably want to -subscribe to more groups, and to do that, you have to query the -@acronym{NNTP} server for a complete list of groups with the @kbd{A A} -command. This usually takes quite a while, but you only have to do it -once. - -After reading and parsing a while, you'll be presented with a list of -groups. Subscribe to the ones you want to read with the @kbd{u} -command. @kbd{l} to make all the killed groups disappear after you've -subscribe to all the groups you want to read. (@kbd{A k} will bring -back all the killed groups.) - -You can now read the groups at once, or you can download the articles -with the @kbd{J s} command. And then read the rest of this manual to -find out which of the other gazillion things you want to customize. - - -@node Batching Agents -@subsection Batching Agents -@findex gnus-agent-batch - -Having the Gnus Agent fetch articles (and post whatever messages you've -written) is quite easy once you've gotten things set up properly. The -following shell script will do everything that is necessary: - -You can run a complete batch command from the command line with the -following incantation: - -@example -#!/bin/sh -emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-agent-batch >/dev/null 2>&1 -@end example - - -@node Agent Caveats -@subsection Agent Caveats - -The Gnus Agent doesn't seem to work like most other offline -newsreaders. Here are some common questions that some imaginary people -may ask: - -@table @dfn -@item If I read an article while plugged, do they get entered into the Agent? - -@strong{No}. If you want this behavior, add -@code{gnus-agent-fetch-selected-article} to -@code{gnus-select-article-hook}. - -@item If I read an article while plugged, and the article already exists in -the Agent, will it get downloaded once more? - -@strong{No}, unless @code{gnus-agent-cache} is @code{nil}. - -@end table - -In short, when Gnus is unplugged, it only looks into the locally stored -articles; when it's plugged, it talks to your ISP and may also use the -locally stored articles. - - -@node Scoring -@chapter Scoring -@cindex scoring - -Other people use @dfn{kill files}, but we here at Gnus Towers like -scoring better than killing, so we'd rather switch than fight. They do -something completely different as well, so sit up straight and pay -attention! - -@vindex gnus-summary-mark-below -All articles have a default score (@code{gnus-summary-default-score}), -which is 0 by default. This score may be raised or lowered either -interactively or by score files. Articles that have a score lower than -@code{gnus-summary-mark-below} are marked as read. - -Gnus will read any @dfn{score files} that apply to the current group -before generating the summary buffer. - -There are several commands in the summary buffer that insert score -entries based on the current article. You can, for instance, ask Gnus to -lower or increase the score of all articles with a certain subject. - -There are two sorts of scoring entries: Permanent and temporary. -Temporary score entries are self-expiring entries. Any entries that are -temporary and have not been used for, say, a week, will be removed -silently to help keep the sizes of the score files down. - -@menu -* Summary Score Commands:: Adding score entries for the current group. -* Group Score Commands:: General score commands. -* Score Variables:: Customize your scoring. (My, what terminology). -* Score File Format:: What a score file may contain. -* Score File Editing:: You can edit score files by hand as well. -* Adaptive Scoring:: Big Sister Gnus knows what you read. -* Home Score File:: How to say where new score entries are to go. -* Followups To Yourself:: Having Gnus notice when people answer you. -* Scoring On Other Headers:: Scoring on non-standard headers. -* Scoring Tips:: How to score effectively. -* Reverse Scoring:: That problem child of old is not problem. -* Global Score Files:: Earth-spanning, ear-splitting score files. -* Kill Files:: They are still here, but they can be ignored. -* Converting Kill Files:: Translating kill files to score files. -* Advanced Scoring:: Using logical expressions to build score rules. -* Score Decays:: It can be useful to let scores wither away. -@end menu - - -@node Summary Score Commands -@section Summary Score Commands -@cindex score commands - -The score commands that alter score entries do not actually modify real -score files. That would be too inefficient. Gnus maintains a cache of -previously loaded score files, one of which is considered the -@dfn{current score file alist}. The score commands simply insert -entries into this list, and upon group exit, this list is saved. - -The current score file is by default the group's local score file, even -if no such score file actually exists. To insert score commands into -some other score file (e.g. @file{all.SCORE}), you must first make this -score file the current one. - -General score commands that don't actually change the score file: - -@table @kbd - -@item V s -@kindex V s (Summary) -@findex gnus-summary-set-score -Set the score of the current article (@code{gnus-summary-set-score}). - -@item V S -@kindex V S (Summary) -@findex gnus-summary-current-score -Display the score of the current article -(@code{gnus-summary-current-score}). - -@item V t -@kindex V t (Summary) -@findex gnus-score-find-trace -Display all score rules that have been used on the current article -(@code{gnus-score-find-trace}). In the @code{*Score Trace*} buffer, you -may type @kbd{e} to edit score file corresponding to the score rule on -current line and @kbd{f} to format (@code{gnus-score-pretty-print}) the -score file and edit it. - -@item V w -@kindex V w (Summary) -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). - -@item V R -@kindex V R (Summary) -@findex gnus-summary-rescore -Run the current summary through the scoring process -(@code{gnus-summary-rescore}). This might be useful if you're playing -around with your score files behind Gnus' back and want to see the -effect you're having. - -@item V c -@kindex V c (Summary) -@findex gnus-score-change-score-file -Make a different score file the current -(@code{gnus-score-change-score-file}). - -@item V e -@kindex V e (Summary) -@findex gnus-score-edit-current-scores -Edit the current score file (@code{gnus-score-edit-current-scores}). -You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score -File Editing}). - -@item V f -@kindex V f (Summary) -@findex gnus-score-edit-file -Edit a score file and make this score file the current one -(@code{gnus-score-edit-file}). - -@item V F -@kindex V F (Summary) -@findex gnus-score-flush-cache -Flush the score cache (@code{gnus-score-flush-cache}). This is useful -after editing score files. - -@item V C -@kindex V C (Summary) -@findex gnus-score-customize -Customize a score file in a visually pleasing manner -(@code{gnus-score-customize}). - -@end table - -The rest of these commands modify the local score file. - -@table @kbd - -@item V m -@kindex V m (Summary) -@findex gnus-score-set-mark-below -Prompt for a score, and mark all articles with a score below this as -read (@code{gnus-score-set-mark-below}). - -@item V x -@kindex V x (Summary) -@findex gnus-score-set-expunge-below -Prompt for a score, and add a score rule to the current score file to -expunge all articles below this score -(@code{gnus-score-set-expunge-below}). -@end table - -The keystrokes for actually making score entries follow a very regular -pattern, so there's no need to list all the commands. (Hundreds of -them.) - -@findex gnus-summary-increase-score -@findex gnus-summary-lower-score - -@enumerate -@item -The first key is either @kbd{I} (upper case i) for increasing the score -or @kbd{L} for lowering the score. -@item -The second key says what header you want to score on. The following -keys are available: -@table @kbd - -@item a -Score on the author name. - -@item s -Score on the subject line. - -@item x -Score on the @code{Xref} line---i.e., the cross-posting line. - -@item r -Score on the @code{References} line. - -@item d -Score on the date. - -@item l -Score on the number of lines. - -@item i -Score on the @code{Message-ID} header. - -@item e -Score on an ``extra'' header, that is, one of those in gnus-extra-headers, -if your @acronym{NNTP} server tracks additional header data in overviews. - -@item f -Score on followups---this matches the author name, and adds scores to -the followups to this author. (Using this key leads to the creation of -@file{ADAPT} files.) - -@item b -Score on the body. - -@item h -Score on the head. - -@item t -Score on thread. (Using this key leads to the creation of @file{ADAPT} -files.) - -@end table - -@item -The third key is the match type. Which match types are valid depends on -what headers you are scoring on. - -@table @code - -@item strings - -@table @kbd - -@item e -Exact matching. - -@item s -Substring matching. - -@item f -Fuzzy matching (@pxref{Fuzzy Matching}). - -@item r -Regexp matching -@end table - -@item date -@table @kbd - -@item b -Before date. - -@item a -After date. - -@item n -This date. -@end table - -@item number -@table @kbd - -@item < -Less than number. - -@item = -Equal to number. - -@item > -Greater than number. -@end table -@end table - -@item -The fourth and usually final key says whether this is a temporary (i.e., -expiring) score entry, or a permanent (i.e., non-expiring) score entry, -or whether it is to be done immediately, without adding to the score -file. -@table @kbd - -@item t -Temporary score entry. - -@item p -Permanent score entry. - -@item i -Immediately scoring. -@end table - -@item -If you are scoring on `e' (extra) headers, you will then be prompted for -the header name on which you wish to score. This must be a header named -in gnus-extra-headers, and @samp{TAB} completion is available. - -@end enumerate - -So, let's say you want to increase the score on the current author with -exact matching permanently: @kbd{I a e p}. If you want to lower the -score based on the subject line, using substring matching, and make a -temporary score entry: @kbd{L s s t}. Pretty easy. - -To make things a bit more complicated, there are shortcuts. If you use -a capital letter on either the second or third keys, Gnus will use -defaults for the remaining one or two keystrokes. The defaults are -``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s -t}, and @kbd{I a R} is the same as @kbd{I a r t}. - -These functions take both the numerical prefix and the symbolic prefix -(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower -(or increase) the score of the article. A symbolic prefix of @code{a} -says to use the @file{all.SCORE} file for the command instead of the -current score file. - -@vindex gnus-score-mimic-keymap -The @code{gnus-score-mimic-keymap} says whether these commands will -pretend they are keymaps or not. - - -@node Group Score Commands -@section Group Score Commands -@cindex group score commands - -There aren't many of these as yet, I'm afraid. - -@table @kbd - -@item W e -@kindex W e (Group) -@findex gnus-score-edit-all-score -Edit the apply-to-all-groups all.SCORE file. You will be popped into -a @code{gnus-score-mode} buffer (@pxref{Score File Editing}). - -@item W f -@kindex W f (Group) -@findex gnus-score-flush-cache -Gnus maintains a cache of score alists to avoid having to reload them -all the time. This command will flush the cache -(@code{gnus-score-flush-cache}). - -@end table - -You can do scoring from the command line by saying something like: - -@findex gnus-batch-score -@cindex batch scoring -@example -$ emacs -batch -l ~/.emacs -l ~/.gnus.el -f gnus-batch-score -@end example - - -@node Score Variables -@section Score Variables -@cindex score variables - -@table @code - -@item gnus-use-scoring -@vindex gnus-use-scoring -If @code{nil}, Gnus will not check for score files, and will not, in -general, do any score-related work. This is @code{t} by default. - -@item gnus-kill-killed -@vindex gnus-kill-killed -If this variable is @code{nil}, Gnus will never apply score files to -articles that have already been through the kill process. While this -may save you lots of time, it also means that if you apply a kill file -to a group, and then change the kill file and want to run it over you -group again to kill more articles, it won't work. You have to set this -variable to @code{t} to do that. (It is @code{t} by default.) - -@item gnus-kill-files-directory -@vindex gnus-kill-files-directory -All kill and score files will be stored in this directory, which is -initialized from the @env{SAVEDIR} environment variable by default. -This is @file{~/News/} by default. - -@item gnus-score-file-suffix -@vindex gnus-score-file-suffix -Suffix to add to the group name to arrive at the score file name -(@file{SCORE} by default.) - -@item gnus-score-uncacheable-files -@vindex gnus-score-uncacheable-files -@cindex score cache -All score files are normally cached to avoid excessive re-loading of -score files. However, this might make your Emacs grow big and -bloated, so this regexp can be used to weed out score files unlikely -to be needed again. It would be a bad idea to deny caching of -@file{all.SCORE}, while it might be a good idea to not cache -@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this -variable is @samp{ADAPT$} by default, so no adaptive score files will -be cached. - -@item gnus-save-score -@vindex gnus-save-score -If you have really complicated score files, and do lots of batch -scoring, then you might set this variable to @code{t}. This will make -Gnus save the scores into the @file{.newsrc.eld} file. - -If you do not set this to @code{t}, then manual scores (like those set -with @kbd{V s} (@code{gnus-summary-set-score})) will not be preserved -across group visits. - -@item gnus-score-interactive-default-score -@vindex gnus-score-interactive-default-score -Score used by all the interactive raise/lower commands to raise/lower -score with. Default is 1000, which may seem excessive, but this is to -ensure that the adaptive scoring scheme gets enough room to play with. -We don't want the small changes from the adaptive scoring to overwrite -manually entered data. - -@item gnus-summary-default-score -@vindex gnus-summary-default-score -Default score of an article, which is 0 by default. - -@item gnus-summary-expunge-below -@vindex gnus-summary-expunge-below -Don't display the summary lines of articles that have scores lower than -this variable. This is @code{nil} by default, which means that no -articles will be hidden. This variable is local to the summary buffers, -and has to be set from @code{gnus-summary-mode-hook}. - -@item gnus-score-over-mark -@vindex gnus-score-over-mark -Mark (in the third column) used for articles with a score over the -default. Default is @samp{+}. - -@item gnus-score-below-mark -@vindex gnus-score-below-mark -Mark (in the third column) used for articles with a score below the -default. Default is @samp{-}. - -@item gnus-score-find-score-files-function -@vindex gnus-score-find-score-files-function -Function used to find score files for the current group. This function -is called with the name of the group as the argument. - -Predefined functions available are: -@table @code - -@item gnus-score-find-single -@findex gnus-score-find-single -Only apply the group's own score file. - -@item gnus-score-find-bnews -@findex gnus-score-find-bnews -Apply all score files that match, using bnews syntax. This is the -default. If the current group is @samp{gnu.emacs.gnus}, for instance, -@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and -@file{gnu.all.SCORE} would all apply. In short, the instances of -@samp{all} in the score file names are translated into @samp{.*}, and -then a regexp match is done. - -This means that if you have some score entries that you want to apply to -all groups, then you put those entries in the @file{all.SCORE} file. - -The score files are applied in a semi-random order, although Gnus will -try to apply the more general score files before the more specific score -files. It does this by looking at the number of elements in the score -file names---discarding the @samp{all} elements. - -@item gnus-score-find-hierarchical -@findex gnus-score-find-hierarchical -Apply all score files from all the parent groups. This means that you -can't have score files like @file{all.SCORE}, but you can have -@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE} for each -server. - -@end table -This variable can also be a list of functions. In that case, all -these functions will be called with the group name as argument, and -all the returned lists of score files will be applied. These -functions can also return lists of lists of score alists directly. In -that case, the functions that return these non-file score alists -should probably be placed before the ``real'' score file functions, to -ensure that the last score file returned is the local score file. -Phu. - -For example, to do hierarchical scoring but use a non-server-specific -overall score file, you could use the value -@example -(list (lambda (group) ("all.SCORE")) - 'gnus-score-find-hierarchical) -@end example - -@item gnus-score-expiry-days -@vindex gnus-score-expiry-days -This variable says how many days should pass before an unused score file -entry is expired. If this variable is @code{nil}, no score file entries -are expired. It's 7 by default. - -@item gnus-update-score-entry-dates -@vindex gnus-update-score-entry-dates -If this variable is non-@code{nil}, temporary score entries that have -been triggered (matched) will have their dates updated. (This is how Gnus -controls expiry---all non-matched-entries will become too old while -matched entries will stay fresh and young.) However, if you set this -variable to @code{nil}, even matched entries will grow old and will -have to face that oh-so grim reaper. - -@item gnus-score-after-write-file-function -@vindex gnus-score-after-write-file-function -Function called with the name of the score file just written. - -@item gnus-score-thread-simplify -@vindex gnus-score-thread-simplify -If this variable is non-@code{nil}, article subjects will be -simplified for subject scoring purposes in the same manner as with -threading---according to the current value of -@code{gnus-simplify-subject-functions}. If the scoring entry uses -@code{substring} or @code{exact} matching, the match will also be -simplified in this manner. - -@end table - - -@node Score File Format -@section Score File Format -@cindex score file format - -A score file is an @code{emacs-lisp} file that normally contains just a -single form. Casual users are not expected to edit these files; -everything can be changed from the summary buffer. - -Anyway, if you'd like to dig into it yourself, here's an example: - -@lisp -(("from" - ("Lars Ingebrigtsen" -10000) - ("Per Abrahamsen") - ("larsi\\|lmi" -50000 nil R)) - ("subject" - ("Ding is Badd" nil 728373)) - ("xref" - ("alt.politics" -1000 728372 s)) - ("lines" - (2 -100 nil <)) - (mark 0) - (expunge -1000) - (mark-and-expunge -10) - (read-only nil) - (orphan -10) - (adapt t) - (files "/hom/larsi/News/gnu.SCORE") - (exclude-files "all.SCORE") - (local (gnus-newsgroup-auto-expire t) - (gnus-summary-make-false-root empty)) - (eval (ding))) -@end lisp - -This example demonstrates most score file elements. @xref{Advanced -Scoring}, for a different approach. - -Even though this looks much like Lisp code, nothing here is actually -@code{eval}ed. The Lisp reader is used to read this form, though, so it -has to be valid syntactically, if not semantically. - -Six keys are supported by this alist: - -@table @code - -@item STRING -If the key is a string, it is the name of the header to perform the -match on. Scoring can only be performed on these eight headers: -@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, -@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to -these headers, there are three strings to tell Gnus to fetch the entire -article and do the match on larger parts of the article: @code{Body} -will perform the match on the body of the article, @code{Head} will -perform the match on the head of the article, and @code{All} will -perform the match on the entire article. Note that using any of these -last three keys will slow down group entry @emph{considerably}. The -final ``header'' you can score on is @code{Followup}. These score -entries will result in new score entries being added for all follow-ups -to articles that matches these score entries. - -Following this key is an arbitrary number of score entries, where each -score entry has one to four elements. -@enumerate - -@item -The first element is the @dfn{match element}. On most headers this will -be a string, but on the Lines and Chars headers, this must be an -integer. - -@item -If the second element is present, it should be a number---the @dfn{score -element}. This number should be an integer in the neginf to posinf -interval. This number is added to the score of the article if the match -is successful. If this element is not present, the -@code{gnus-score-interactive-default-score} number will be used -instead. This is 1000 by default. - -@item -If the third element is present, it should be a number---the @dfn{date -element}. This date says when the last time this score entry matched, -which provides a mechanism for expiring the score entries. It this -element is not present, the score entry is permanent. The date is -represented by the number of days since December 31, 1 BCE. - -@item -If the fourth element is present, it should be a symbol---the @dfn{type -element}. This element specifies what function should be used to see -whether this score entry matches the article. What match types that can -be used depends on what header you wish to perform the match on. -@table @dfn - -@item From, Subject, References, Xref, Message-ID -For most header types, there are the @code{r} and @code{R} (regexp), as -well as @code{s} and @code{S} (substring) types, and @code{e} and -@code{E} (exact match), and @code{w} (word match) types. If this -element is not present, Gnus will assume that substring matching should -be used. @code{R}, @code{S}, and @code{E} differ from the others in -that the matches will be done in a case-sensitive manner. All these -one-letter types are really just abbreviations for the @code{regexp}, -@code{string}, @code{exact}, and @code{word} types, which you can use -instead, if you feel like. - -@item Extra -Just as for the standard string overview headers, if you are using -gnus-extra-headers, you can score on these headers' values. In this -case, there is a 5th element in the score entry, being the name of the -header to be scored. The following entry is useful in your -@file{all.SCORE} file in case of spam attacks from a single origin -host, if your @acronym{NNTP} server tracks @samp{NNTP-Posting-Host} in -overviews: - -@lisp -("111.222.333.444" -1000 nil s - "NNTP-Posting-Host") -@end lisp - -@item Lines, Chars -These two headers use different match types: @code{<}, @code{>}, -@code{=}, @code{>=} and @code{<=}. - -These predicates are true if - -@example -(PREDICATE HEADER MATCH) -@end example - -evaluates to non-@code{nil}. For instance, the advanced match -@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the -following form: - -@lisp -(< header-value 4) -@end lisp - -Or to put it another way: When using @code{<} on @code{Lines} with 4 as -the match, we get the score added if the article has less than 4 lines. -(It's easy to get confused and think it's the other way around. But -it's not. I think.) - -When matching on @code{Lines}, be careful because some back ends (like -@code{nndir}) do not generate @code{Lines} header, so every article ends -up being marked as having 0 lines. This can lead to strange results if -you happen to lower score of the articles with few lines. - -@item Date -For the Date header we have three kinda silly match types: -@code{before}, @code{at} and @code{after}. I can't really imagine this -ever being useful, but, like, it would feel kinda silly not to provide -this function. Just in case. You never know. Better safe than sorry. -Once burnt, twice shy. Don't judge a book by its cover. Never not have -sex on a first date. (I have been told that at least one person, and I -quote, ``found this function indispensable'', however.) - -@cindex ISO8601 -@cindex date -A more useful match type is @code{regexp}. With it, you can match the -date string using a regular expression. The date is normalized to -ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If -you want to match all articles that have been posted on April 1st in -every year, you could use @samp{....0401.........} as a match string, -for instance. (Note that the date is kept in its original time zone, so -this will match articles that were posted when it was April 1st where -the article was posted from. Time zones are such wholesome fun for the -whole family, eh?) - -@item Head, Body, All -These three match keys use the same match types as the @code{From} (etc) -header uses. - -@item Followup -This match key is somewhat special, in that it will match the -@code{From} header, and affect the score of not only the matching -articles, but also all followups to the matching articles. This allows -you e.g. increase the score of followups to your own articles, or -decrease the score of followups to the articles of some known -trouble-maker. Uses the same match types as the @code{From} header -uses. (Using this match key will lead to creation of @file{ADAPT} -files.) - -@item Thread -This match key works along the same lines as the @code{Followup} match -key. If you say that you want to score on a (sub-)thread started by an -article with a @code{Message-ID} @var{x}, then you add a @samp{thread} -match. This will add a new @samp{thread} match for each article that -has @var{x} in its @code{References} header. (These new @samp{thread} -matches will use the @code{Message-ID}s of these matching articles.) -This will ensure that you can raise/lower the score of an entire thread, -even though some articles in the thread may not have complete -@code{References} headers. Note that using this may lead to -undeterministic scores of the articles in the thread. (Using this match -key will lead to creation of @file{ADAPT} files.) -@end table -@end enumerate - -@cindex score file atoms -@item mark -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read. - -@item expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be removed from the summary buffer. - -@item mark-and-expunge -The value of this entry should be a number. Any articles with a score -lower than this number will be marked as read and removed from the -summary buffer. - -@item thread-mark-and-expunge -The value of this entry should be a number. All articles that belong to -a thread that has a total score below this number will be marked as read -and removed from the summary buffer. @code{gnus-thread-score-function} -says how to compute the total score for a thread. - -@item files -The value of this entry should be any number of file names. These files -are assumed to be score files as well, and will be loaded the same way -this one was. - -@item exclude-files -The clue of this entry should be any number of files. These files will -not be loaded, even though they would normally be so, for some reason or -other. - -@item eval -The value of this entry will be @code{eval}el. This element will be -ignored when handling global score files. - -@item read-only -Read-only score files will not be updated or saved. Global score files -should feature this atom (@pxref{Global Score Files}). (Note: -@dfn{Global} here really means @dfn{global}; not your personal -apply-to-all-groups score files.) - -@item orphan -The value of this entry should be a number. Articles that do not have -parents will get this number added to their scores. Imagine you follow -some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you -will only follow a few of the threads, also want to see any new threads. - -You can do this with the following two score file entries: - -@example - (orphan -500) - (mark-and-expunge -100) -@end example - -When you enter the group the first time, you will only see the new -threads. You then raise the score of the threads that you find -interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the -rest. Next time you enter the group, you will see new articles in the -interesting threads, plus any new threads. - -I.e.---the orphan score atom is for high-volume groups where a few -interesting threads which can't be found automatically by ordinary -scoring rules exist. - -@item adapt -This entry controls the adaptive scoring. If it is @code{t}, the -default adaptive scoring rules will be used. If it is @code{ignore}, no -adaptive scoring will be performed on this group. If it is a list, this -list will be used as the adaptive scoring rules. If it isn't present, -or is something other than @code{t} or @code{ignore}, the default -adaptive scoring rules will be used. If you want to use adaptive -scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to -@code{t}, and insert an @code{(adapt ignore)} in the groups where you do -not want adaptive scoring. If you only want adaptive scoring in a few -groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and -insert @code{(adapt t)} in the score files of the groups where you want -it. - -@item adapt-file -All adaptive score entries will go to the file named by this entry. It -will also be applied when entering the group. This atom might be handy -if you want to adapt on several groups at once, using the same adaptive -file for a number of groups. - -@item local -@cindex local variables -The value of this entry should be a list of @code{(@var{var} -@var{value})} pairs. Each @var{var} will be made buffer-local to the -current summary buffer, and set to the value specified. This is a -convenient, if somewhat strange, way of setting variables in some -groups if you don't like hooks much. Note that the @var{value} won't -be evaluated. -@end table - - -@node Score File Editing -@section Score File Editing - -You normally enter all scoring commands from the summary buffer, but you -might feel the urge to edit them by hand as well, so we've supplied you -with a mode for that. - -It's simply a slightly customized @code{emacs-lisp} mode, with these -additional commands: - -@table @kbd - -@item C-c C-c -@kindex C-c C-c (Score) -@findex gnus-score-edit-exit -Save the changes you have made and return to the summary buffer -(@code{gnus-score-edit-exit}). - -@item C-c C-d -@kindex C-c C-d (Score) -@findex gnus-score-edit-insert-date -Insert the current date in numerical format -(@code{gnus-score-edit-insert-date}). This is really the day number, if -you were wondering. - -@item C-c C-p -@kindex C-c C-p (Score) -@findex gnus-score-pretty-print -The adaptive score files are saved in an unformatted fashion. If you -intend to read one of these files, you want to @dfn{pretty print} it -first. This command (@code{gnus-score-pretty-print}) does that for -you. - -@end table - -Type @kbd{M-x gnus-score-mode} to use this mode. - -@vindex gnus-score-mode-hook -@code{gnus-score-menu-hook} is run in score mode buffers. - -In the summary buffer you can use commands like @kbd{V f}, @kbd{V e} and -@kbd{V t} to begin editing score files. - - -@node Adaptive Scoring -@section Adaptive Scoring -@cindex adaptive scoring - -If all this scoring is getting you down, Gnus has a way of making it all -happen automatically---as if by magic. Or rather, as if by artificial -stupidity, to be precise. - -@vindex gnus-use-adaptive-scoring -When you read an article, or mark an article as read, or kill an -article, you leave marks behind. On exit from the group, Gnus can sniff -these marks and add score elements depending on what marks it finds. -You turn on this ability by setting @code{gnus-use-adaptive-scoring} to -@code{t} or @code{(line)}. If you want score adaptively on separate -words appearing in the subjects, you should set this variable to -@code{(word)}. If you want to use both adaptive methods, set this -variable to @code{(word line)}. - -@vindex gnus-default-adaptive-score-alist -To give you complete control over the scoring process, you can customize -the @code{gnus-default-adaptive-score-alist} variable. For instance, it -might look something like this: - -@lisp -(setq gnus-default-adaptive-score-alist - '((gnus-unread-mark) - (gnus-ticked-mark (from 4)) - (gnus-dormant-mark (from 5)) - (gnus-del-mark (from -4) (subject -1)) - (gnus-read-mark (from 4) (subject 2)) - (gnus-expirable-mark (from -1) (subject -1)) - (gnus-killed-mark (from -1) (subject -3)) - (gnus-kill-file-mark) - (gnus-ancient-mark) - (gnus-low-score-mark) - (gnus-catchup-mark (from -1) (subject -1)))) -@end lisp - -As you see, each element in this alist has a mark as a key (either a -variable name or a ``real'' mark---a character). Following this key is -a arbitrary number of header/score pairs. If there are no header/score -pairs following the key, no adaptive scoring will be done on articles -that have that key as the article mark. For instance, articles with -@code{gnus-unread-mark} in the example above will not get adaptive score -entries. - -Each article can have only one mark, so just a single of these rules -will be applied to each article. - -To take @code{gnus-del-mark} as an example---this alist says that all -articles that have that mark (i.e., are marked with @samp{e}) will have a -score entry added to lower based on the @code{From} header by -4, and -lowered by @code{Subject} by -1. Change this to fit your prejudices. - -If you have marked 10 articles with the same subject with -@code{gnus-del-mark}, the rule for that mark will be applied ten times. -That means that that subject will get a score of ten times -1, which -should be, unless I'm much mistaken, -10. - -If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all -the read articles will be marked with the @samp{E} mark. This'll -probably make adaptive scoring slightly impossible, so auto-expiring and -adaptive scoring doesn't really mix very well. - -The headers you can score on are @code{from}, @code{subject}, -@code{message-id}, @code{references}, @code{xref}, @code{lines}, -@code{chars} and @code{date}. In addition, you can score on -@code{followup}, which will create an adaptive score entry that matches -on the @code{References} header using the @code{Message-ID} of the -current article, thereby matching the following thread. - -If you use this scheme, you should set the score file atom @code{mark} -to something small---like -300, perhaps, to avoid having small random -changes result in articles getting marked as read. - -After using adaptive scoring for a week or so, Gnus should start to -become properly trained and enhance the authors you like best, and kill -the authors you like least, without you having to say so explicitly. - -You can control what groups the adaptive scoring is to be performed on -by using the score files (@pxref{Score File Format}). This will also -let you use different rules in different groups. - -@vindex gnus-adaptive-file-suffix -The adaptive score entries will be put into a file where the name is the -group name with @code{gnus-adaptive-file-suffix} appended. The default -is @file{ADAPT}. - -@vindex gnus-adaptive-pretty-print -Adaptive score files can get huge and are not meant to be edited by -human hands. If @code{gnus-adaptive-pretty-print} is @code{nil} (the -deafult) those files will not be written in a human readable way. - -@vindex gnus-score-exact-adapt-limit -When doing adaptive scoring, substring or fuzzy matching would probably -give you the best results in most cases. However, if the header one -matches is short, the possibility for false positives is great, so if -the length of the match is less than -@code{gnus-score-exact-adapt-limit}, exact matching will be used. If -this variable is @code{nil}, exact matching will always be used to avoid -this problem. - -@vindex gnus-default-adaptive-word-score-alist -As mentioned above, you can adapt either on individual words or entire -headers. If you adapt on words, the -@code{gnus-default-adaptive-word-score-alist} variable says what score -each instance of a word should add given a mark. - -@lisp -(setq gnus-default-adaptive-word-score-alist - `((,gnus-read-mark . 30) - (,gnus-catchup-mark . -10) - (,gnus-killed-mark . -20) - (,gnus-del-mark . -15))) -@end lisp - -This is the default value. If you have adaption on words enabled, every -word that appears in subjects of articles marked with -@code{gnus-read-mark} will result in a score rule that increase the -score with 30 points. - -@vindex gnus-default-ignored-adaptive-words -@vindex gnus-ignored-adaptive-words -Words that appear in the @code{gnus-default-ignored-adaptive-words} list -will be ignored. If you wish to add more words to be ignored, use the -@code{gnus-ignored-adaptive-words} list instead. - -@vindex gnus-adaptive-word-length-limit -Some may feel that short words shouldn't count when doing adaptive -scoring. If so, you may set @code{gnus-adaptive-word-length-limit} to -an integer. Words shorter than this number will be ignored. This -variable defaults to @code{nil}. - -@vindex gnus-adaptive-word-syntax-table -When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the -syntax table in effect. It is similar to the standard syntax table, but -it considers numbers to be non-word-constituent characters. - -@vindex gnus-adaptive-word-minimum -If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive -word scoring process will never bring down the score of an article to -below this number. The default is @code{nil}. - -@vindex gnus-adaptive-word-no-group-words -If @code{gnus-adaptive-word-no-group-words} is set to @code{t}, gnus -won't adaptively word score any of the words in the group name. Useful -for groups like @samp{comp.editors.emacs}, where most of the subject -lines contain the word @samp{emacs}. - -After using this scheme for a while, it might be nice to write a -@code{gnus-psychoanalyze-user} command to go through the rules and see -what words you like and what words you don't like. Or perhaps not. - -Note that the adaptive word scoring thing is highly experimental and is -likely to change in the future. Initial impressions seem to indicate -that it's totally useless as it stands. Some more work (involving more -rigorous statistical methods) will have to be done to make this useful. - - -@node Home Score File -@section Home Score File - -The score file where new score file entries will go is called the -@dfn{home score file}. This is normally (and by default) the score file -for the group itself. For instance, the home score file for -@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. - -However, this may not be what you want. It is often convenient to share -a common home score file among many groups---all @samp{emacs} groups -could perhaps use the same home score file. - -@vindex gnus-home-score-file -The variable that controls this is @code{gnus-home-score-file}. It can -be: - -@enumerate -@item -A string. Then this file will be used as the home score file for all -groups. - -@item -A function. The result of this function will be used as the home score -file. The function will be called with the name of the group as the -parameter. - -@item -A list. The elements in this list can be: - -@enumerate -@item -@code{(@var{regexp} @var{file-name})}. If the @var{regexp} matches the -group name, the @var{file-name} will be used as the home score file. - -@item -A function. If the function returns non-@code{nil}, the result will -be used as the home score file. The function will be called with the -name of the group as the parameter. - -@item -A string. Use the string as the home score file. -@end enumerate - -The list will be traversed from the beginning towards the end looking -for matches. - -@end enumerate - -So, if you want to use just a single score file, you could say: - -@lisp -(setq gnus-home-score-file - "my-total-score-file.SCORE") -@end lisp - -If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and -@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: - -@findex gnus-hierarchial-home-score-file -@lisp -(setq gnus-home-score-file - 'gnus-hierarchial-home-score-file) -@end lisp - -This is a ready-made function provided for your convenience. -Other functions include - -@table @code -@item gnus-current-home-score-file -@findex gnus-current-home-score-file -Return the ``current'' regular score file. This will make scoring -commands add entry to the ``innermost'' matching score file. - -@end table - -If you want to have one score file for the @samp{emacs} groups and -another for the @samp{comp} groups, while letting all other groups use -their own home score files: - -@lisp -(setq gnus-home-score-file - ;; @r{All groups that match the regexp @code{"\\.emacs"}} - '(("\\.emacs" "emacs.SCORE") - ;; @r{All the comp groups in one score file} - ("^comp" "comp.SCORE"))) -@end lisp - -@vindex gnus-home-adapt-file -@code{gnus-home-adapt-file} works exactly the same way as -@code{gnus-home-score-file}, but says what the home adaptive score file -is instead. All new adaptive file entries will go into the file -specified by this variable, and the same syntax is allowed. - -In addition to using @code{gnus-home-score-file} and -@code{gnus-home-adapt-file}, you can also use group parameters -(@pxref{Group Parameters}) and topic parameters (@pxref{Topic -Parameters}) to achieve much the same. Group and topic parameters take -precedence over this variable. - - -@node Followups To Yourself -@section Followups To Yourself - -Gnus offers two commands for picking out the @code{Message-ID} header in -the current buffer. Gnus will then add a score rule that scores using -this @code{Message-ID} on the @code{References} header of other -articles. This will, in effect, increase the score of all articles that -respond to the article in the current buffer. Quite useful if you want -to easily note when people answer what you've said. - -@table @code - -@item gnus-score-followup-article -@findex gnus-score-followup-article -This will add a score to articles that directly follow up your own -article. - -@item gnus-score-followup-thread -@findex gnus-score-followup-thread -This will add a score to all articles that appear in a thread ``below'' -your own article. -@end table - -@vindex message-sent-hook -These two functions are both primarily meant to be used in hooks like -@code{message-sent-hook}, like this: -@lisp -(add-hook 'message-sent-hook 'gnus-score-followup-thread) -@end lisp - - -If you look closely at your own @code{Message-ID}, you'll notice that -the first two or three characters are always the same. Here's two of -mine: - -@example - - -@end example - -So ``my'' ident on this machine is @samp{x6}. This can be -exploited---the following rule will raise the score on all followups to -myself: - -@lisp -("references" - ("" - 1000 nil r)) -@end lisp - -Whether it's the first two or first three characters that are ``yours'' -is system-dependent. - - -@node Scoring On Other Headers -@section Scoring On Other Headers -@cindex scoring on other headers - -Gnus is quite fast when scoring the ``traditional'' -headers---@samp{From}, @samp{Subject} and so on. However, scoring -other headers requires writing a @code{head} scoring rule, which means -that Gnus has to request every single article from the back end to find -matches. This takes a long time in big groups. - -@vindex gnus-inhibit-slow-scoring -You can inhibit this slow scoring on headers or body by setting the -variable @code{gnus-inhibit-slow-scoring}. If -@code{gnus-inhibit-slow-scoring} is regexp, slow scoring is inhibited if -the group matches the regexp. If it is t, slow scoring on it is -inhibited for all groups. - -Now, there's not much you can do about the slowness for news groups, but for -mail groups, you have greater control. In @ref{To From Newsgroups}, -it's explained in greater detail what this mechanism does, but here's -a cookbook example for @code{nnml} on how to allow scoring on the -@samp{To} and @samp{Cc} headers. - -Put the following in your @file{~/.gnus.el} file. - -@lisp -(setq gnus-extra-headers '(To Cc Newsgroups Keywords) - nnmail-extra-headers gnus-extra-headers) -@end lisp - -Restart Gnus and rebuild your @code{nnml} overview files with the -@kbd{M-x nnml-generate-nov-databases} command. This will take a long -time if you have much mail. - -Now you can score on @samp{To} and @samp{Cc} as ``extra headers'' like -so: @kbd{I e s p To RET RET}. - -See? Simple. - - -@node Scoring Tips -@section Scoring Tips -@cindex scoring tips - -@table @dfn - -@item Crossposts -@cindex crossposts -@cindex scoring crossposts -If you want to lower the score of crossposts, the line to match on is -the @code{Xref} header. -@lisp -("xref" (" talk.politics.misc:" -1000)) -@end lisp - -@item Multiple crossposts -If you want to lower the score of articles that have been crossposted to -more than, say, 3 groups: -@lisp -("xref" - ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" - -1000 nil r)) -@end lisp - -@item Matching on the body -This is generally not a very good idea---it takes a very long time. -Gnus actually has to fetch each individual article from the server. But -you might want to anyway, I guess. Even though there are three match -keys (@code{Head}, @code{Body} and @code{All}), you should choose one -and stick with it in each score file. If you use any two, each article -will be fetched @emph{twice}. If you want to match a bit on the -@code{Head} and a bit on the @code{Body}, just use @code{All} for all -the matches. - -@item Marking as read -You will probably want to mark articles that have scores below a certain -number as read. This is most easily achieved by putting the following -in your @file{all.SCORE} file: -@lisp -((mark -100)) -@end lisp -You may also consider doing something similar with @code{expunge}. - -@item Negated character classes -If you say stuff like @code{[^abcd]*}, you may get unexpected results. -That will match newlines, which might lead to, well, The Unknown. Say -@code{[^abcd\n]*} instead. -@end table - - -@node Reverse Scoring -@section Reverse Scoring -@cindex reverse scoring - -If you want to keep just articles that have @samp{Sex with Emacs} in the -subject header, and expunge all other articles, you could put something -like this in your score file: - -@lisp -(("subject" - ("Sex with Emacs" 2)) - (mark 1) - (expunge 1)) -@end lisp - -So, you raise all articles that match @samp{Sex with Emacs} and mark the -rest as read, and expunge them to boot. - - -@node Global Score Files -@section Global Score Files -@cindex global score files - -Sure, other newsreaders have ``global kill files''. These are usually -nothing more than a single kill file that applies to all groups, stored -in the user's home directory. Bah! Puny, weak newsreaders! - -What I'm talking about here are Global Score Files. Score files from -all over the world, from users everywhere, uniting all nations in one -big, happy score file union! Ange-score! New and untested! - -@vindex gnus-global-score-files -All you have to do to use other people's score files is to set the -@code{gnus-global-score-files} variable. One entry for each score file, -or each score file directory. Gnus will decide by itself what score -files are applicable to which group. - -To use the score file -@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and -all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory, -say this: - -@lisp -(setq gnus-global-score-files - '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" - "/ftp@@ftp.some-where:/pub/score/")) -@end lisp - -@findex gnus-score-search-global-directories -@noindent -Simple, eh? Directory names must end with a @samp{/}. These -directories are typically scanned only once during each Gnus session. -If you feel the need to manually re-scan the remote directories, you can -use the @code{gnus-score-search-global-directories} command. - -Note that, at present, using this option will slow down group entry -somewhat. (That is---a lot.) - -If you want to start maintaining score files for other people to use, -just put your score file up for anonymous ftp and announce it to the -world. Become a retro-moderator! Participate in the retro-moderator -wars sure to ensue, where retro-moderators battle it out for the -sympathy of the people, luring them to use their score files on false -premises! Yay! The net is saved! - -Here are some tips for the would-be retro-moderator, off the top of my -head: - -@itemize @bullet - -@item -Articles heavily crossposted are probably junk. -@item -To lower a single inappropriate article, lower by @code{Message-ID}. -@item -Particularly brilliant authors can be raised on a permanent basis. -@item -Authors that repeatedly post off-charter for the group can safely be -lowered out of existence. -@item -Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest -articles completely. - -@item -Use expiring score entries to keep the size of the file down. You -should probably have a long expiry period, though, as some sites keep -old articles for a long time. -@end itemize - -@dots{} I wonder whether other newsreaders will support global score files -in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue -Wave, xrn and 1stReader are bound to implement scoring. Should we start -holding our breath yet? - - -@node Kill Files -@section Kill Files -@cindex kill files - -Gnus still supports those pesky old kill files. In fact, the kill file -entries can now be expiring, which is something I wrote before Daniel -Quinlan thought of doing score files, so I've left the code in there. - -In short, kill processing is a lot slower (and I do mean @emph{a lot}) -than score processing, so it might be a good idea to rewrite your kill -files into score files. - -Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any -forms into this file, which means that you can use kill files as some -sort of primitive hook function to be run on group entry, even though -that isn't a very good idea. - -Normal kill files look like this: - -@lisp -(gnus-kill "From" "Lars Ingebrigtsen") -(gnus-kill "Subject" "ding") -(gnus-expunge "X") -@end lisp - -This will mark every article written by me as read, and remove the -marked articles from the summary buffer. Very useful, you'll agree. - -Other programs use a totally different kill file syntax. If Gnus -encounters what looks like a @code{rn} kill file, it will take a stab at -interpreting it. - -Two summary functions for editing a @sc{gnus} kill file: - -@table @kbd - -@item M-k -@kindex M-k (Summary) -@findex gnus-summary-edit-local-kill -Edit this group's kill file (@code{gnus-summary-edit-local-kill}). - -@item M-K -@kindex M-K (Summary) -@findex gnus-summary-edit-global-kill -Edit the general kill file (@code{gnus-summary-edit-global-kill}). -@end table - -Two group mode functions for editing the kill files: - -@table @kbd - -@item M-k -@kindex M-k (Group) -@findex gnus-group-edit-local-kill -Edit this group's kill file (@code{gnus-group-edit-local-kill}). - -@item M-K -@kindex M-K (Group) -@findex gnus-group-edit-global-kill -Edit the general kill file (@code{gnus-group-edit-global-kill}). -@end table - -Kill file variables: - -@table @code -@item gnus-kill-file-name -@vindex gnus-kill-file-name -A kill file for the group @samp{soc.motss} is normally called -@file{soc.motss.KILL}. The suffix appended to the group name to get -this file name is detailed by the @code{gnus-kill-file-name} variable. -The ``global'' kill file (not in the score file sense of ``global'', of -course) is just called @file{KILL}. - -@vindex gnus-kill-save-kill-file -@item gnus-kill-save-kill-file -If this variable is non-@code{nil}, Gnus will save the -kill file after processing, which is necessary if you use expiring -kills. - -@item gnus-apply-kill-hook -@vindex gnus-apply-kill-hook -@findex gnus-apply-kill-file-unless-scored -@findex gnus-apply-kill-file -A hook called to apply kill files to a group. It is -@code{(gnus-apply-kill-file)} by default. If you want to ignore the -kill file if you have a score file for the same group, you can set this -hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want -kill files to be processed, you should set this variable to @code{nil}. - -@item gnus-kill-file-mode-hook -@vindex gnus-kill-file-mode-hook -A hook called in kill-file mode buffers. - -@end table - - -@node Converting Kill Files -@section Converting Kill Files -@cindex kill files -@cindex converting kill files - -If you have loads of old kill files, you may want to convert them into -score files. If they are ``regular'', you can use -the @file{gnus-kill-to-score.el} package; if not, you'll have to do it -by hand. - -The kill to score conversion package isn't included in Emacs by default. -You can fetch it from the contrib directory of the Gnus distribution or -from -@uref{http://heim.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. - -If your old kill files are very complex---if they contain more -non-@code{gnus-kill} forms than not, you'll have to convert them by -hand. Or just let them be as they are. Gnus will still use them as -before. - - -@node Advanced Scoring -@section Advanced Scoring - -Scoring on Subjects and From headers is nice enough, but what if you're -really interested in what a person has to say only when she's talking -about a particular subject? Or what if you really don't want to -read what person A has to say when she's following up to person B, but -want to read what she says when she's following up to person C? - -By using advanced scoring rules you may create arbitrarily complex -scoring patterns. - -@menu -* Advanced Scoring Syntax:: A definition. -* Advanced Scoring Examples:: What they look like. -* Advanced Scoring Tips:: Getting the most out of it. -@end menu - - -@node Advanced Scoring Syntax -@subsection Advanced Scoring Syntax - -Ordinary scoring rules have a string as the first element in the rule. -Advanced scoring rules have a list as the first element. The second -element is the score to be applied if the first element evaluated to a -non-@code{nil} value. - -These lists may consist of three logical operators, one redirection -operator, and various match operators. - -Logical operators: - -@table @code -@item & -@itemx and -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{false}, and then it'll stop. If all arguments -evaluate to @code{true} values, then this operator will return -@code{true}. - -@item | -@itemx or -This logical operator will evaluate each of its arguments until it finds -one that evaluates to @code{true}. If no arguments are @code{true}, -then this operator will return @code{false}. - -@item ! -@itemx not -@itemx ¬ -This logical operator only takes a single argument. It returns the -logical negation of the value of its argument. - -@end table - -There is an @dfn{indirection operator} that will make its arguments -apply to the ancestors of the current article being scored. For -instance, @code{1-} will make score rules apply to the parent of the -current article. @code{2-} will make score rules apply to the -grandparent of the current article. Alternatively, you can write -@code{^^}, where the number of @code{^}s (carets) says how far back into -the ancestry you want to go. - -Finally, we have the match operators. These are the ones that do the -real work. Match operators are header name strings followed by a match -and a match type. A typical match operator looks like @samp{("from" -"Lars Ingebrigtsen" s)}. The header names are the same as when using -simple scoring, and the match types are also the same. - - -@node Advanced Scoring Examples -@subsection Advanced Scoring Examples - -Please note that the following examples are score file rules. To -make a complete score file from them, surround them with another pair -of parentheses. - -Let's say you want to increase the score of articles written by Lars -when he's talking about Gnus: - -@example -@group -((& - ("from" "Lars Ingebrigtsen") - ("subject" "Gnus")) - 1000) -@end group -@end example - -Quite simple, huh? - -When he writes long articles, he sometimes has something nice to say: - -@example -((& - ("from" "Lars Ingebrigtsen") - (| - ("subject" "Gnus") - ("lines" 100 >))) - 1000) -@end example - -However, when he responds to things written by Reig Eigil Logge, you -really don't want to read what he's written: - -@example -((& - ("from" "Lars Ingebrigtsen") - (1- ("from" "Reig Eigil Logge"))) - -100000) -@end example - -Everybody that follows up Redmondo when he writes about disappearing -socks should have their scores raised, but only when they talk about -white socks. However, when Lars talks about socks, it's usually not -very interesting: - -@example -((& - (1- - (& - ("from" "redmondo@@.*no" r) - ("body" "disappearing.*socks" t))) - (! ("from" "Lars Ingebrigtsen")) - ("body" "white.*socks")) - 1000) -@end example - -Suppose you're reading a high volume group and you're only interested -in replies. The plan is to score down all articles that don't have -subject that begin with "Re:", "Fw:" or "Fwd:" and then score up all -parents of articles that have subjects that begin with reply marks. - -@example -((! ("subject" "re:\\|fwd?:" r)) - -200) -((1- ("subject" "re:\\|fwd?:" r)) - 200) -@end example - -The possibilities are endless. - -@node Advanced Scoring Tips -@subsection Advanced Scoring Tips - -The @code{&} and @code{|} logical operators do short-circuit logic. -That is, they stop processing their arguments when it's clear what the -result of the operation will be. For instance, if one of the arguments -of an @code{&} evaluates to @code{false}, there's no point in evaluating -the rest of the arguments. This means that you should put slow matches -(@samp{body}, @samp{header}) last and quick matches (@samp{from}, -@samp{subject}) first. - -The indirection arguments (@code{1-} and so on) will make their -arguments work on previous generations of the thread. If you say -something like: - -@example -... -(1- - (1- - ("from" "lars"))) -... -@end example - -Then that means ``score on the from header of the grandparent of the -current article''. An indirection is quite fast, but it's better to say: - -@example -(1- - (& - ("from" "Lars") - ("subject" "Gnus"))) -@end example - -than it is to say: - -@example -(& - (1- ("from" "Lars")) - (1- ("subject" "Gnus"))) -@end example - - -@node Score Decays -@section Score Decays -@cindex score decays -@cindex decays - -You may find that your scores have a tendency to grow without -bounds, especially if you're using adaptive scoring. If scores get too -big, they lose all meaning---they simply max out and it's difficult to -use them in any sensible way. - -@vindex gnus-decay-scores -@findex gnus-decay-score -@vindex gnus-decay-score-function -Gnus provides a mechanism for decaying scores to help with this problem. -When score files are loaded and @code{gnus-decay-scores} is -non-@code{nil}, Gnus will run the score files through the decaying -mechanism thereby lowering the scores of all non-permanent score rules. -If @code{gnus-decay-scores} is a regexp, only score files matching this -regexp are treated. E.g. you may set it to @samp{\\.ADAPT\\'} if only -@emph{adaptive} score files should be decayed. The decay itself if -performed by the @code{gnus-decay-score-function} function, which is -@code{gnus-decay-score} by default. Here's the definition of that -function: - -@lisp -(defun gnus-decay-score (score) - "Decay SCORE according to `gnus-score-decay-constant' -and `gnus-score-decay-scale'." - (let ((n (- score - (* (if (< score 0) -1 1) - (min (abs score) - (max gnus-score-decay-constant - (* (abs score) - gnus-score-decay-scale))))))) - (if (and (featurep 'xemacs) - ;; XEmacs' floor can handle only the floating point - ;; number below the half of the maximum integer. - (> (abs n) (lsh -1 -2))) - (string-to-number - (car (split-string (number-to-string n) "\\."))) - (floor n)))) -@end lisp - -@vindex gnus-score-decay-scale -@vindex gnus-score-decay-constant -@code{gnus-score-decay-constant} is 3 by default and -@code{gnus-score-decay-scale} is 0.05. This should cause the following: - -@enumerate -@item -Scores between -3 and 3 will be set to 0 when this function is called. - -@item -Scores with magnitudes between 3 and 60 will be shrunk by 3. - -@item -Scores with magnitudes greater than 60 will be shrunk by 5% of the -score. -@end enumerate - -If you don't like this decay function, write your own. It is called -with the score to be decayed as its only parameter, and it should return -the new score, which should be an integer. - -Gnus will try to decay scores once a day. If you haven't run Gnus for -four days, Gnus will decay the scores four times, for instance. - -@iftex -@iflatex -@chapter Message -@include message.texi -@chapter Emacs MIME -@include emacs-mime.texi -@chapter Sieve -@include sieve.texi -@chapter PGG -@include pgg.texi -@chapter SASL -@include sasl.texi -@end iflatex -@end iftex - -@node Various -@chapter Various - -@menu -* Process/Prefix:: A convention used by many treatment commands. -* Interactive:: Making Gnus ask you many questions. -* Symbolic Prefixes:: How to supply some Gnus functions with options. -* Formatting Variables:: You can specify what buffers should look like. -* Window Layout:: Configuring the Gnus buffer windows. -* Faces and Fonts:: How to change how faces look. -* Compilation:: How to speed Gnus up. -* Mode Lines:: Displaying information in the mode lines. -* Highlighting and Menus:: Making buffers look all nice and cozy. -* Buttons:: Get tendinitis in ten easy steps! -* Daemons:: Gnus can do things behind your back. -* NoCeM:: How to avoid spam and other fatty foods. -* Undo:: Some actions can be undone. -* Predicate Specifiers:: Specifying predicates. -* Moderation:: What to do if you're a moderator. -* Fetching a Group:: Starting Gnus just to read a group. -* Image Enhancements:: Modern versions of Emacs/XEmacs can display images. -* Fuzzy Matching:: What's the big fuzz? -* Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. -* Spam Package:: A package for filtering and processing spam. -* The Gnus Registry:: A package for tracking messages by Message-ID. -* Other modes:: Interaction with other modes. -* Various Various:: Things that are really various. -@end menu - - -@node Process/Prefix -@section Process/Prefix -@cindex process/prefix convention - -Many functions, among them functions for moving, decoding and saving -articles, use what is known as the @dfn{Process/Prefix convention}. - -This is a method for figuring out what articles the user wants the -command to be performed on. - -It goes like this: - -If the numeric prefix is N, perform the operation on the next N -articles, starting with the current one. If the numeric prefix is -negative, perform the operation on the previous N articles, starting -with the current one. - -@vindex transient-mark-mode -If @code{transient-mark-mode} in non-@code{nil} and the region is -active, all articles in the region will be worked upon. - -If there is no numeric prefix, but some articles are marked with the -process mark, perform the operation on the articles marked with -the process mark. - -If there is neither a numeric prefix nor any articles marked with the -process mark, just perform the operation on the current article. - -Quite simple, really, but it needs to be made clear so that surprises -are avoided. - -Commands that react to the process mark will push the current list of -process marked articles onto a stack and will then clear all process -marked articles. You can restore the previous configuration with the -@kbd{M P y} command (@pxref{Setting Process Marks}). - -@vindex gnus-summary-goto-unread -One thing that seems to shock & horrify lots of people is that, for -instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. -Since each @kbd{d} (which marks the current article as read) by default -goes to the next unread article after marking, this means that @kbd{3 d} -will mark the next three unread articles as read, no matter what the -summary buffer looks like. Set @code{gnus-summary-goto-unread} to -@code{nil} for a more straightforward action. - -Many commands do not use the process/prefix convention. All commands -that do explicitly say so in this manual. To apply the process/prefix -convention to commands that do not use it, you can use the @kbd{M-&} -command. For instance, to mark all the articles in the group as -expirable, you could say @kbd{M P b M-& E}. - - -@node Interactive -@section Interactive -@cindex interaction - -@table @code - -@item gnus-novice-user -@vindex gnus-novice-user -If this variable is non-@code{nil}, you are either a newcomer to the -World of Usenet, or you are very cautious, which is a nice thing to be, -really. You will be given questions of the type ``Are you sure you want -to do this?'' before doing anything dangerous. This is @code{t} by -default. - -@item gnus-expert-user -@vindex gnus-expert-user -If this variable is non-@code{nil}, you will seldom be asked any -questions by Gnus. It will simply assume you know what you're doing, no -matter how strange. - -@item gnus-interactive-catchup -@vindex gnus-interactive-catchup -Require confirmation before catching up a group if non-@code{nil}. It -is @code{t} by default. - -@item gnus-interactive-exit -@vindex gnus-interactive-exit -Require confirmation before exiting Gnus. This variable is @code{t} by -default. -@end table - - -@node Symbolic Prefixes -@section Symbolic Prefixes -@cindex symbolic prefixes - -Quite a lot of Emacs commands react to the (numeric) prefix. For -instance, @kbd{C-u 4 C-f} moves point four characters forward, and -@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score -rule of 900 to the current article. - -This is all nice and well, but what if you want to give a command some -additional information? Well, what most commands do is interpret the -``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one -doesn't want a backup file to be created when saving the current buffer, -for instance. But what if you want to save without making a backup -file, and you want Emacs to flash lights and play a nice tune at the -same time? You can't, and you're probably perfectly happy that way. - -@kindex M-i (Summary) -@findex gnus-symbolic-argument -I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The -prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next -character typed in is the value. You can stack as many @kbd{M-i} -prefixes as you want. @kbd{M-i a C-M-u} means ``feed the @kbd{C-M-u} -command the symbolic prefix @code{a}''. @kbd{M-i a M-i b C-M-u} means -``feed the @kbd{C-M-u} command the symbolic prefixes @code{a} and -@code{b}''. You get the drift. - -Typing in symbolic prefixes to commands that don't accept them doesn't -hurt, but it doesn't do any good either. Currently not many Gnus -functions make use of the symbolic prefix. - -If you're interested in how Gnus implements this, @pxref{Extended -Interactive}. - - -@node Formatting Variables -@section Formatting Variables -@cindex formatting variables - -Throughout this manual you've probably noticed lots of variables called -things like @code{gnus-group-line-format} and -@code{gnus-summary-mode-line-format}. These control how Gnus is to -output lines in the various buffers. There's quite a lot of them. -Fortunately, they all use the same syntax, so there's not that much to -be annoyed by. - -Here's an example format spec (from the group buffer): @samp{%M%S%5y: -%(%g%)\n}. We see that it is indeed extremely ugly, and that there are -lots of percentages everywhere. - -@menu -* Formatting Basics:: A formatting variable is basically a format string. -* Mode Line Formatting:: Some rules about mode line formatting variables. -* Advanced Formatting:: Modifying output in various ways. -* User-Defined Specs:: Having Gnus call your own functions. -* Formatting Fonts:: Making the formatting look colorful and nice. -* Positioning Point:: Moving point to a position after an operation. -* Tabulation:: Tabulating your output. -* Wide Characters:: Dealing with wide characters. -@end menu - -Currently Gnus uses the following formatting variables: -@code{gnus-group-line-format}, @code{gnus-summary-line-format}, -@code{gnus-server-line-format}, @code{gnus-topic-line-format}, -@code{gnus-group-mode-line-format}, -@code{gnus-summary-mode-line-format}, -@code{gnus-article-mode-line-format}, -@code{gnus-server-mode-line-format}, and -@code{gnus-summary-pick-line-format}. - -All these format variables can also be arbitrary elisp forms. In that -case, they will be @code{eval}ed to insert the required lines. - -@kindex M-x gnus-update-format -@findex gnus-update-format -Gnus includes a command to help you while creating your own format -specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, -update the spec in question and pop you to a buffer where you can -examine the resulting Lisp code to be run to generate the line. - - - -@node Formatting Basics -@subsection Formatting Basics - -Each @samp{%} element will be replaced by some string or other when the -buffer in question is generated. @samp{%5y} means ``insert the @samp{y} -spec, and pad with spaces to get a 5-character field''. - -As with normal C and Emacs Lisp formatting strings, the numerical -modifier between the @samp{%} and the formatting type character will -@dfn{pad} the output so that it is always at least that long. -@samp{%5y} will make the field always (at least) five characters wide by -padding with spaces to the left. If you say @samp{%-5y}, it will pad to -the right instead. - -You may also wish to limit the length of the field to protect against -particularly wide values. For that you can say @samp{%4,6y}, which -means that the field will never be more than 6 characters wide and never -less than 4 characters wide. - -Also Gnus supports some extended format specifications, such as -@samp{%&user-date;}. - - -@node Mode Line Formatting -@subsection Mode Line Formatting - -Mode line formatting variables (e.g., -@code{gnus-summary-mode-line-format}) follow the same rules as other, -buffer line oriented formatting variables (@pxref{Formatting Basics}) -with the following two differences: - -@enumerate - -@item -There must be no newline (@samp{\n}) at the end. - -@item -The special @samp{%%b} spec can be used to display the buffer name. -Well, it's no spec at all, really---@samp{%%} is just a way to quote -@samp{%} to allow it to pass through the formatting machinery unmangled, -so that Emacs receives @samp{%b}, which is something the Emacs mode line -display interprets to mean ``show the buffer name''. For a full list of -mode line specs Emacs understands, see the documentation of the -@code{mode-line-format} variable. - -@end enumerate - - -@node Advanced Formatting -@subsection Advanced Formatting - -It is frequently useful to post-process the fields in some way. -Padding, limiting, cutting off parts and suppressing certain values can -be achieved by using @dfn{tilde modifiers}. A typical tilde spec might -look like @samp{%~(cut 3)~(ignore "0")y}. - -These are the valid modifiers: - -@table @code -@item pad -@itemx pad-left -Pad the field to the left with spaces until it reaches the required -length. - -@item pad-right -Pad the field to the right with spaces until it reaches the required -length. - -@item max -@itemx max-left -Cut off characters from the left until it reaches the specified length. - -@item max-right -Cut off characters from the right until it reaches the specified -length. - -@item cut -@itemx cut-left -Cut off the specified number of characters from the left. - -@item cut-right -Cut off the specified number of characters from the right. - -@item ignore -Return an empty string if the field is equal to the specified value. - -@item form -Use the specified form as the field value when the @samp{@@} spec is -used. - -Here's an example: - -@lisp -"~(form (current-time-string))@@" -@end lisp - -@end table - -Let's take an example. The @samp{%o} spec in the summary mode lines -will return a date in compact ISO8601 format---@samp{19960809T230410}. -This is quite a mouthful, so we want to shave off the century number and -the time, leaving us with a six-character date. That would be -@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before -maxing, and we need the padding to ensure that the date is never less -than 6 characters to make it look nice in columns.) - -Ignoring is done first; then cutting; then maxing; and then as the very -last operation, padding. - -If you use lots of these advanced thingies, you'll find that Gnus gets -quite slow. This can be helped enormously by running @kbd{M-x -gnus-compile} when you are satisfied with the look of your lines. -@xref{Compilation}. - - -@node User-Defined Specs -@subsection User-Defined Specs - -All the specs allow for inserting user defined specifiers---@samp{u}. -The next character in the format string should be a letter. Gnus -will call the function @code{gnus-user-format-function-}@samp{X}, where -@samp{X} is the letter following @samp{%u}. The function will be passed -a single parameter---what the parameter means depends on what buffer -it's being called from. The function should return a string, which will -be inserted into the buffer just like information from any other -specifier. This function may also be called with dummy values, so it -should protect against that. - -Also Gnus supports extended user-defined specs, such as @samp{%u&foo;}. -Gnus will call the function @code{gnus-user-format-function-}@samp{foo}. - -You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve -much the same without defining new functions. Here's an example: -@samp{%~(form (count-lines (point-min) (point)))@@}. The form -given here will be evaluated to yield the current line number, and then -inserted. - - -@node Formatting Fonts -@subsection Formatting Fonts - -@cindex %(, %) -@vindex gnus-mouse-face -There are specs for highlighting, and these are shared by all the format -variables. Text inside the @samp{%(} and @samp{%)} specifiers will get -the special @code{mouse-face} property set, which means that it will be -highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer -over it. - -@cindex %@{, %@} -@vindex gnus-face-0 -Text inside the @samp{%@{} and @samp{%@}} specifiers will have their -normal faces set using @code{gnus-face-0}, which is @code{bold} by -default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, -and so on. Create as many faces as you wish. The same goes for the -@code{mouse-face} specs---you can say @samp{%3(hello%)} to have -@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. - -@cindex %<<, %>>, guillemets -@c @cindex %<<, %>>, %«, %», guillemets -@vindex gnus-balloon-face-0 -Text inside the @samp{%<<} and @samp{%>>} specifiers will get the -special @code{balloon-help} property set to -@code{gnus-balloon-face-0}. If you say @samp{%1<<}, you'll get -@code{gnus-balloon-face-1} and so on. The @code{gnus-balloon-face-*} -variables should be either strings or symbols naming functions that -return a string. When the mouse passes over text with this property -set, a balloon window will appear and display the string. Please -refer to @ref{Tooltips, ,Tooltips, emacs, The Emacs Manual}, -(in GNU Emacs) or the doc string of @code{balloon-help-mode} (in -XEmacs) for more information on this. (For technical reasons, the -guillemets have been approximated as @samp{<<} and @samp{>>} in this -paragraph.) - -Here's an alternative recipe for the group buffer: - -@lisp -;; @r{Create three face types.} -(setq gnus-face-1 'bold) -(setq gnus-face-3 'italic) - -;; @r{We want the article count to be in} -;; @r{a bold and green face. So we create} -;; @r{a new face called @code{my-green-bold}.} -(copy-face 'bold 'my-green-bold) -;; @r{Set the color.} -(set-face-foreground 'my-green-bold "ForestGreen") -(setq gnus-face-2 'my-green-bold) - -;; @r{Set the new & fancy format.} -(setq gnus-group-line-format - "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") -@end lisp - -I'm sure you'll be able to use this scheme to create totally unreadable -and extremely vulgar displays. Have fun! - -Note that the @samp{%(} specs (and friends) do not make any sense on the -mode-line variables. - -@node Positioning Point -@subsection Positioning Point - -Gnus usually moves point to a pre-defined place on each line in most -buffers. By default, point move to the first colon character on the -line. You can customize this behavior in three different ways. - -You can move the colon character to somewhere else on the line. - -@findex gnus-goto-colon -You can redefine the function that moves the point to the colon. The -function is called @code{gnus-goto-colon}. - -But perhaps the most convenient way to deal with this, if you don't want -to have a colon in your line, is to use the @samp{%*} specifier. If you -put a @samp{%*} somewhere in your format line definition, Gnus will -place point there. - - -@node Tabulation -@subsection Tabulation - -You can usually line up your displays by padding and cutting your -strings. However, when combining various strings of different size, it -can often be more convenient to just output the strings, and then worry -about lining up the following text afterwards. - -To do that, Gnus supplies tabulator specs---@samp{%=}. There are two -different types---@dfn{hard tabulators} and @dfn{soft tabulators}. - -@samp{%50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, nothing will be inserted. -This is the soft tabulator. - -@samp{%-50=} will insert space characters to pad the line up to column -50. If the text is already past column 50, the excess text past column -50 will be removed. This is the hard tabulator. - - -@node Wide Characters -@subsection Wide Characters - -Fixed width fonts in most countries have characters of the same width. -Some countries, however, use Latin characters mixed with wider -characters---most notable East Asian countries. - -The problem is that when formatting, Gnus assumes that if a string is 10 -characters wide, it'll be 10 Latin characters wide on the screen. In -these countries, that's not true. - -@vindex gnus-use-correct-string-widths -To help fix this, you can set @code{gnus-use-correct-string-widths} to -@code{t}. This makes buffer generation slower, but the results will be -prettier. The default value under XEmacs is @code{t} but @code{nil} -for Emacs. - - -@node Window Layout -@section Window Layout -@cindex window layout - -No, there's nothing here about X, so be quiet. - -@vindex gnus-use-full-window -If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all -other windows and occupy the entire Emacs screen by itself. It is -@code{t} by default. - -Setting this variable to @code{nil} kinda works, but there are -glitches. Use at your own peril. - -@vindex gnus-buffer-configuration -@code{gnus-buffer-configuration} describes how much space each Gnus -buffer should be given. Here's an excerpt of this variable: - -@lisp -((group (vertical 1.0 (group 1.0 point) - (if gnus-carpal (group-carpal 4)))) - (article (vertical 1.0 (summary 0.25 point) - (article 1.0)))) -@end lisp - -This is an alist. The @dfn{key} is a symbol that names some action or -other. For instance, when displaying the group buffer, the window -configuration function will use @code{group} as the key. A full list of -possible names is listed below. - -The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer -should occupy. To take the @code{article} split as an example - - -@lisp -(article (vertical 1.0 (summary 0.25 point) - (article 1.0))) -@end lisp - -This @dfn{split} says that the summary buffer should occupy 25% of upper -half of the screen, and that it is placed over the article buffer. As -you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all -reaching for that calculator there). However, the special number -@code{1.0} is used to signal that this buffer should soak up all the -rest of the space available after the rest of the buffers have taken -whatever they need. There should be only one buffer with the @code{1.0} -size spec per split. - -Point will be put in the buffer that has the optional third element -@code{point}. In a @code{frame} split, the last subsplit having a leaf -split where the tag @code{frame-focus} is a member (i.e. is the third or -fourth element in the list, depending on whether the @code{point} tag is -present) gets focus. - -Here's a more complicated example: - -@lisp -(article (vertical 1.0 (group 4) - (summary 0.25 point) - (if gnus-carpal (summary-carpal 4)) - (article 1.0))) -@end lisp - -If the size spec is an integer instead of a floating point number, -then that number will be used to say how many lines a buffer should -occupy, not a percentage. - -If the @dfn{split} looks like something that can be @code{eval}ed (to be -precise---if the @code{car} of the split is a function or a subr), this -split will be @code{eval}ed. If the result is non-@code{nil}, it will -be used as a split. This means that there will be three buffers if -@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal} -is non-@code{nil}. - -Not complicated enough for you? Well, try this on for size: - -@lisp -(article (horizontal 1.0 - (vertical 0.5 - (group 1.0) - (gnus-carpal 4)) - (vertical 1.0 - (summary 0.25 point) - (summary-carpal 4) - (article 1.0)))) -@end lisp - -Whoops. Two buffers with the mystery 100% tag. And what's that -@code{horizontal} thingie? - -If the first element in one of the split is @code{horizontal}, Gnus will -split the window horizontally, giving you two windows side-by-side. -Inside each of these strips you may carry on all you like in the normal -fashion. The number following @code{horizontal} says what percentage of -the screen is to be given to this strip. - -For each split, there @emph{must} be one element that has the 100% tag. -The splitting is never accurate, and this buffer will eat any leftover -lines from the splits. - -To be slightly more formal, here's a definition of what a valid split -may look like: - -@example -@group -split = frame | horizontal | vertical | buffer | form -frame = "(frame " size *split ")" -horizontal = "(horizontal " size *split ")" -vertical = "(vertical " size *split ")" -buffer = "(" buf-name " " size *[ "point" ] *[ "frame-focus"] ")" -size = number | frame-params -buf-name = group | article | summary ... -@end group -@end example - -The limitations are that the @code{frame} split can only appear as the -top-level split. @var{form} should be an Emacs Lisp form that should -return a valid split. We see that each split is fully recursive, and -may contain any number of @code{vertical} and @code{horizontal} splits. - -@vindex gnus-window-min-width -@vindex gnus-window-min-height -@cindex window height -@cindex window width -Finding the right sizes can be a bit complicated. No window may be less -than @code{gnus-window-min-height} (default 1) characters high, and all -windows must be at least @code{gnus-window-min-width} (default 1) -characters wide. Gnus will try to enforce this before applying the -splits. If you want to use the normal Emacs window width/height limit, -you can just set these two variables to @code{nil}. - -If you're not familiar with Emacs terminology, @code{horizontal} and -@code{vertical} splits may work the opposite way of what you'd expect. -Windows inside a @code{horizontal} split are shown side-by-side, and -windows within a @code{vertical} split are shown above each other. - -@findex gnus-configure-frame -If you want to experiment with window placement, a good tip is to call -@code{gnus-configure-frame} directly with a split. This is the function -that does all the real work when splitting buffers. Below is a pretty -nonsensical configuration with 5 windows; two for the group buffer and -three for the article buffer. (I said it was nonsensical.) If you -@code{eval} the statement below, you can get an idea of how that would -look straight away, without going through the normal Gnus channels. -Play with it until you're satisfied, and then use -@code{gnus-add-configuration} to add your new creation to the buffer -configuration list. - -@lisp -(gnus-configure-frame - '(horizontal 1.0 - (vertical 10 - (group 1.0) - (article 0.3 point)) - (vertical 1.0 - (article 1.0) - (horizontal 4 - (group 1.0) - (article 10))))) -@end lisp - -You might want to have several frames as well. No prob---just use the -@code{frame} split: - -@lisp -(gnus-configure-frame - '(frame 1.0 - (vertical 1.0 - (summary 0.25 point frame-focus) - (article 1.0)) - (vertical ((height . 5) (width . 15) - (user-position . t) - (left . -1) (top . 1)) - (picon 1.0)))) - -@end lisp - -This split will result in the familiar summary/article window -configuration in the first (or ``main'') frame, while a small additional -frame will be created where picons will be shown. As you can see, -instead of the normal @code{1.0} top-level spec, each additional split -should have a frame parameter alist as the size spec. -@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp -Reference Manual}. Under XEmacs, a frame property list will be -accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} -is such a plist. -The list of all possible keys for @code{gnus-buffer-configuration} can -be found in its default value. - -Note that the @code{message} key is used for both -@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If -it is desirable to distinguish between the two, something like this -might be used: - -@lisp -(message (horizontal 1.0 - (vertical 1.0 (message 1.0 point)) - (vertical 0.24 - (if (buffer-live-p gnus-summary-buffer) - '(summary 0.5)) - (group 1.0)))) -@end lisp - -One common desire for a multiple frame split is to have a separate frame -for composing mail and news while leaving the original frame intact. To -accomplish that, something like the following can be done: - -@lisp -(message - (frame 1.0 - (if (not (buffer-live-p gnus-summary-buffer)) - (car (cdr (assoc 'group gnus-buffer-configuration))) - (car (cdr (assoc 'summary gnus-buffer-configuration)))) - (vertical ((user-position . t) (top . 1) (left . 1) - (name . "Message")) - (message 1.0 point)))) -@end lisp - -@findex gnus-add-configuration -Since the @code{gnus-buffer-configuration} variable is so long and -complicated, there's a function you can use to ease changing the config -of a single setting: @code{gnus-add-configuration}. If, for instance, -you want to change the @code{article} setting, you could say: - -@lisp -(gnus-add-configuration - '(article (vertical 1.0 - (group 4) - (summary .25 point) - (article 1.0)))) -@end lisp - -You'd typically stick these @code{gnus-add-configuration} calls in your -@file{~/.gnus.el} file or in some startup hook---they should be run after -Gnus has been loaded. - -@vindex gnus-always-force-window-configuration -If all windows mentioned in the configuration are already visible, Gnus -won't change the window configuration. If you always want to force the -``right'' window configuration, you can set -@code{gnus-always-force-window-configuration} to non-@code{nil}. - -If you're using tree displays (@pxref{Tree Display}), and the tree -window is displayed vertically next to another window, you may also want -to fiddle with @code{gnus-tree-minimize-window} to avoid having the -windows resized. - -@subsection Example Window Configurations - -@itemize @bullet -@item -Narrow left hand side occupied by group buffer. Right hand side split -between summary buffer (top one-sixth) and article buffer (bottom). - -@ifinfo -@example -+---+---------+ -| G | Summary | -| r +---------+ -| o | | -| u | Article | -| p | | -+---+---------+ -@end example -@end ifinfo - -@lisp -(gnus-add-configuration - '(article - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 - (summary 0.16 point) - (article 1.0))))) - -(gnus-add-configuration - '(summary - (horizontal 1.0 - (vertical 25 (group 1.0)) - (vertical 1.0 (summary 1.0 point))))) -@end lisp - -@end itemize - - -@node Faces and Fonts -@section Faces and Fonts -@cindex faces -@cindex fonts -@cindex colors - -Fiddling with fonts and faces used to be very difficult, but these days -it is very simple. You simply say @kbd{M-x customize-face}, pick out -the face you want to alter, and alter it via the standard Customize -interface. - - -@node Compilation -@section Compilation -@cindex compilation -@cindex byte-compilation - -@findex gnus-compile - -Remember all those line format specification variables? -@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so -on. Now, Gnus will of course heed whatever these variables are, but, -unfortunately, changing them will mean a quite significant slow-down. -(The default values of these variables have byte-compiled functions -associated with them, while the user-generated versions do not, of -course.) - -To help with this, you can run @kbd{M-x gnus-compile} after you've -fiddled around with the variables and feel that you're (kind of) -satisfied. This will result in the new specs being byte-compiled, and -you'll get top speed again. Gnus will save these compiled specs in the -@file{.newsrc.eld} file. (User-defined functions aren't compiled by -this function, though---you should compile them yourself by sticking -them into the @file{~/.gnus.el} file and byte-compiling that file.) - - -@node Mode Lines -@section Mode Lines -@cindex mode lines - -@vindex gnus-updated-mode-lines -@code{gnus-updated-mode-lines} says what buffers should keep their mode -lines updated. It is a list of symbols. Supported symbols include -@code{group}, @code{article}, @code{summary}, @code{server}, -@code{browse}, and @code{tree}. If the corresponding symbol is present, -Gnus will keep that mode line updated with information that may be -pertinent. If this variable is @code{nil}, screen refresh may be -quicker. - -@cindex display-time - -@vindex gnus-mode-non-string-length -By default, Gnus displays information on the current article in the mode -lines of the summary and article buffers. The information Gnus wishes -to display (e.g. the subject of the article) is often longer than the -mode lines, and therefore have to be cut off at some point. The -@code{gnus-mode-non-string-length} variable says how long the other -elements on the line is (i.e., the non-info part). If you put -additional elements on the mode line (e.g. a clock), you should modify -this variable: - -@c Hook written by Francesco Potorti` -@lisp -(add-hook 'display-time-hook - (lambda () (setq gnus-mode-non-string-length - (+ 21 - (if line-number-mode 5 0) - (if column-number-mode 4 0) - (length display-time-string))))) -@end lisp - -If this variable is @code{nil} (which is the default), the mode line -strings won't be chopped off, and they won't be padded either. Note -that the default is unlikely to be desirable, as even the percentage -complete in the buffer may be crowded off the mode line; the user should -configure this variable appropriately for her configuration. - - -@node Highlighting and Menus -@section Highlighting and Menus -@cindex visual -@cindex highlighting -@cindex menus - -@vindex gnus-visual -The @code{gnus-visual} variable controls most of the Gnus-prettifying -aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy -colors or fonts. This will also inhibit loading the @file{gnus-vis.el} -file. - -This variable can be a list of visual properties that are enabled. The -following elements are valid, and are all included by default: - -@table @code -@item group-highlight -Do highlights in the group buffer. -@item summary-highlight -Do highlights in the summary buffer. -@item article-highlight -Do highlights in the article buffer. -@item highlight -Turn on highlighting in all buffers. -@item group-menu -Create menus in the group buffer. -@item summary-menu -Create menus in the summary buffers. -@item article-menu -Create menus in the article buffer. -@item browse-menu -Create menus in the browse buffer. -@item server-menu -Create menus in the server buffer. -@item score-menu -Create menus in the score buffers. -@item menu -Create menus in all buffers. -@end table - -So if you only want highlighting in the article buffer and menus in all -buffers, you could say something like: - -@lisp -(setq gnus-visual '(article-highlight menu)) -@end lisp - -If you want highlighting only and no menus whatsoever, you'd say: - -@lisp -(setq gnus-visual '(highlight)) -@end lisp - -If @code{gnus-visual} is @code{t}, highlighting and menus will be used -in all Gnus buffers. - -Other general variables that influence the look of all buffers include: - -@table @code -@item gnus-mouse-face -@vindex gnus-mouse-face -This is the face (i.e., font) used for mouse highlighting in Gnus. No -mouse highlights will be done if @code{gnus-visual} is @code{nil}. - -@end table - -There are hooks associated with the creation of all the different menus: - -@table @code - -@item gnus-article-menu-hook -@vindex gnus-article-menu-hook -Hook called after creating the article mode menu. - -@item gnus-group-menu-hook -@vindex gnus-group-menu-hook -Hook called after creating the group mode menu. - -@item gnus-summary-menu-hook -@vindex gnus-summary-menu-hook -Hook called after creating the summary mode menu. - -@item gnus-server-menu-hook -@vindex gnus-server-menu-hook -Hook called after creating the server mode menu. - -@item gnus-browse-menu-hook -@vindex gnus-browse-menu-hook -Hook called after creating the browse mode menu. - -@item gnus-score-menu-hook -@vindex gnus-score-menu-hook -Hook called after creating the score mode menu. - -@end table - - -@node Buttons -@section Buttons -@cindex buttons -@cindex mouse -@cindex click - -Those new-fangled @dfn{mouse} contraptions is very popular with the -young, hep kids who don't want to learn the proper way to do things -these days. Why, I remember way back in the summer of '89, when I was -using Emacs on a Tops 20 system. Three hundred users on one single -machine, and every user was running Simula compilers. Bah! - -Right. - -@vindex gnus-carpal -Well, you can make Gnus display bufferfuls of buttons you can click to -do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple, -really. Tell the chiropractor I sent you. - - -@table @code - -@item gnus-carpal-mode-hook -@vindex gnus-carpal-mode-hook -Hook run in all carpal mode buffers. - -@item gnus-carpal-button-face -@vindex gnus-carpal-button-face -Face used on buttons. - -@item gnus-carpal-header-face -@vindex gnus-carpal-header-face -Face used on carpal buffer headers. - -@item gnus-carpal-group-buffer-buttons -@vindex gnus-carpal-group-buffer-buttons -Buttons in the group buffer. - -@item gnus-carpal-summary-buffer-buttons -@vindex gnus-carpal-summary-buffer-buttons -Buttons in the summary buffer. - -@item gnus-carpal-server-buffer-buttons -@vindex gnus-carpal-server-buffer-buttons -Buttons in the server buffer. - -@item gnus-carpal-browse-buffer-buttons -@vindex gnus-carpal-browse-buffer-buttons -Buttons in the browse buffer. -@end table - -All the @code{buttons} variables are lists. The elements in these list -are either cons cells where the @code{car} contains a text to be displayed and -the @code{cdr} contains a function symbol, or a simple string. - - -@node Daemons -@section Daemons -@cindex demons -@cindex daemons - -Gnus, being larger than any program ever written (allegedly), does lots -of strange stuff that you may wish to have done while you're not -present. For instance, you may want it to check for new mail once in a -while. Or you may want it to close down all connections to all servers -when you leave Emacs idle. And stuff like that. - -Gnus will let you do stuff like that by defining various -@dfn{handlers}. Each handler consists of three elements: A -@var{function}, a @var{time}, and an @var{idle} parameter. - -Here's an example of a handler that closes connections when Emacs has -been idle for thirty minutes: - -@lisp -(gnus-demon-close-connections nil 30) -@end lisp - -Here's a handler that scans for @acronym{PGP} headers every hour when -Emacs is idle: - -@lisp -(gnus-demon-scan-pgp 60 t) -@end lisp - -This @var{time} parameter and that @var{idle} parameter work together -in a strange, but wonderful fashion. Basically, if @var{idle} is -@code{nil}, then the function will be called every @var{time} minutes. - -If @var{idle} is @code{t}, then the function will be called after -@var{time} minutes only if Emacs is idle. So if Emacs is never idle, -the function will never be called. But once Emacs goes idle, the -function will be called every @var{time} minutes. - -If @var{idle} is a number and @var{time} is a number, the function will -be called every @var{time} minutes only when Emacs has been idle for -@var{idle} minutes. - -If @var{idle} is a number and @var{time} is @code{nil}, the function -will be called once every time Emacs has been idle for @var{idle} -minutes. - -And if @var{time} is a string, it should look like @samp{07:31}, and -the function will then be called once every day somewhere near that -time. Modified by the @var{idle} parameter, of course. - -@vindex gnus-demon-timestep -(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} -seconds. This is 60 by default. If you change that variable, -all the timings in the handlers will be affected.) - -So, if you want to add a handler, you could put something like this in -your @file{~/.gnus.el} file: - -@findex gnus-demon-add-handler -@lisp -(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) -@end lisp - -@findex gnus-demon-add-nocem -@findex gnus-demon-add-scanmail -@findex gnus-demon-add-rescan -@findex gnus-demon-add-scan-timestamps -@findex gnus-demon-add-disconnection -Some ready-made functions to do this have been created: -@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, -@code{gnus-demon-add-nntp-close-connection}, -@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and -@code{gnus-demon-add-scanmail}. Just put those functions in your -@file{~/.gnus.el} if you want those abilities. - -@findex gnus-demon-init -@findex gnus-demon-cancel -@vindex gnus-demon-handlers -If you add handlers to @code{gnus-demon-handlers} directly, you should -run @code{gnus-demon-init} to make the changes take hold. To cancel all -daemons, you can use the @code{gnus-demon-cancel} function. - -Note that adding daemons can be pretty naughty if you over do it. Adding -functions that scan all news and mail from all servers every two seconds -is a sure-fire way of getting booted off any respectable system. So -behave. - - -@node NoCeM -@section NoCeM -@cindex nocem -@cindex spam - -@dfn{Spamming} is posting the same article lots and lots of times. -Spamming is bad. Spamming is evil. - -Spamming is usually canceled within a day or so by various anti-spamming -agencies. These agencies usually also send out @dfn{NoCeM} messages. -NoCeM is pronounced ``no see-'em'', and means what the name -implies---these are messages that make the offending articles, like, go -away. - -What use are these NoCeM messages if the articles are canceled anyway? -Some sites do not honor cancel messages and some sites just honor cancels -from a select few people. Then you may wish to make use of the NoCeM -messages, which are distributed in the newsgroups -@samp{news.lists.filters}, @samp{alt.nocem.misc}, etc. - -Gnus can read and parse the messages in this group automatically, and -this will make spam disappear. - -There are some variables to customize, of course: - -@table @code -@item gnus-use-nocem -@vindex gnus-use-nocem -Set this variable to @code{t} to set the ball rolling. It is @code{nil} -by default. - -You can also set this variable to a positive number as a group level. -In that case, Gnus scans NoCeM messages when checking new news if this -value is not exceeding a group level that you specify as the prefix -argument to some commands, e.g. @code{gnus}, -@code{gnus-group-get-new-news}, etc. Otherwise, Gnus does not scan -NoCeM messages if you specify a group level that is smaller than this -value to those commands. For example, if you use 1 or 2 on the mail -groups and the levels on the news groups remain the default, 3 is the -best choice. - -@item gnus-nocem-groups -@vindex gnus-nocem-groups -Gnus will look for NoCeM messages in the groups in this list. The -default is -@lisp -("news.lists.filters" "alt.nocem.misc") -@end lisp - -@item gnus-nocem-issuers -@vindex gnus-nocem-issuers -There are many people issuing NoCeM messages. This list says what -people you want to listen to. The default is: - -@lisp -("Adri Verhoef" - "alba-nocem@@albasani.net" - "bleachbot@@httrack.com" - "news@@arcor-online.net" - "news@@uni-berlin.de" - "nocem@@arcor.de" - "pgpmoose@@killfile.org" - "xjsppl@@gmx.de") -@end lisp - -Known despammers that you can put in this list are listed at@* -@uref{http://www.xs4all.nl/~rosalind/nocemreg/nocemreg.html}. - -You do not have to heed NoCeM messages from all these people---just the -ones you want to listen to. You also don't have to accept all NoCeM -messages from the people you like. Each NoCeM message has a @dfn{type} -header that gives the message a (more or less, usually less) rigorous -definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf}, -@samp{binary}, and @samp{troll}. To specify this, you have to use -@code{(@var{issuer} @var{conditions} @dots{})} elements in the list. -Each condition is either a string (which is a regexp that matches types -you want to use) or a list on the form @code{(not @var{string})}, where -@var{string} is a regexp that matches types you don't want to use. - -For instance, if you want all NoCeM messages from Chris Lewis except his -@samp{troll} messages, you'd say: - -@lisp -("clewis@@ferret.ocunix.on.ca" ".*" (not "troll")) -@end lisp - -On the other hand, if you just want nothing but his @samp{spam} and -@samp{spew} messages, you'd say: - -@lisp -("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam") -@end lisp - -The specs are applied left-to-right. - - -@item gnus-nocem-verifyer -@vindex gnus-nocem-verifyer -@findex gnus-nocem-epg-verify -@findex pgg-verify -This should be a function for verifying that the NoCeM issuer is who she -says she is. This variable defaults to @code{gnus-nocem-epg-verify} if -EasyPG is available, otherwise defaults to @code{pgg-verify}. The -function should return non-@code{nil} if the verification is successful, -otherwise (including the case the NoCeM message was not signed) should -return @code{nil}. If this is too slow and you don't care for -verification (which may be dangerous), you can set this variable to -@code{nil}. - -Formerly the default was @code{mc-verify}, which is a Mailcrypt -function. While you can still use it, you can change it into -@code{gnus-nocem-epg-verify} or @code{pgg-verify} running with GnuPG if -you are willing to add the @acronym{PGP} public keys to GnuPG's keyring. - -@item gnus-nocem-directory -@vindex gnus-nocem-directory -This is where Gnus will store its NoCeM cache files. The default is@* -@file{~/News/NoCeM/}. - -@item gnus-nocem-expiry-wait -@vindex gnus-nocem-expiry-wait -The number of days before removing old NoCeM entries from the cache. -The default is 15. If you make it shorter Gnus will be faster, but you -might then see old spam. - -@item gnus-nocem-check-from -@vindex gnus-nocem-check-from -Non-@code{nil} means check for valid issuers in message bodies. -Otherwise don't bother fetching articles unless their author matches a -valid issuer; that is much faster if you are selective about the -issuers. - -@item gnus-nocem-check-article-limit -@vindex gnus-nocem-check-article-limit -If non-@code{nil}, the maximum number of articles to check in any NoCeM -group. @code{nil} means no restriction. NoCeM groups can be huge and -very slow to process. - -@end table - -Using NoCeM could potentially be a memory hog. If you have many living -(i. e., subscribed or unsubscribed groups), your Emacs process will grow -big. If this is a problem, you should kill off all (or most) of your -unsubscribed groups (@pxref{Subscription Commands}). - - -@node Undo -@section Undo -@cindex undo - -It is very useful to be able to undo actions one has done. In normal -Emacs buffers, it's easy enough---you just push the @code{undo} button. -In Gnus buffers, however, it isn't that simple. - -The things Gnus displays in its buffer is of no value whatsoever to -Gnus---it's all just data designed to look nice to the user. -Killing a group in the group buffer with @kbd{C-k} makes the line -disappear, but that's just a side-effect of the real action---the -removal of the group in question from the internal Gnus structures. -Undoing something like that can't be done by the normal Emacs -@code{undo} function. - -Gnus tries to remedy this somewhat by keeping track of what the user -does and coming up with actions that would reverse the actions the user -takes. When the user then presses the @code{undo} key, Gnus will run -the code to reverse the previous action, or the previous actions. -However, not all actions are easily reversible, so Gnus currently offers -a few key functions to be undoable. These include killing groups, -yanking groups, and changing the list of read articles of groups. -That's it, really. More functions may be added in the future, but each -added function means an increase in data to be stored, so Gnus will -never be totally undoable. - -@findex gnus-undo-mode -@vindex gnus-use-undo -@findex gnus-undo -The undoability is provided by the @code{gnus-undo-mode} minor mode. It -is used if @code{gnus-use-undo} is non-@code{nil}, which is the -default. The @kbd{C-M-_} key performs the @code{gnus-undo} -command, which should feel kinda like the normal Emacs @code{undo} -command. - - -@node Predicate Specifiers -@section Predicate Specifiers -@cindex predicate specifiers - -Some Gnus variables are @dfn{predicate specifiers}. This is a special -form that allows flexible specification of predicates without having -to type all that much. - -These specifiers are lists consisting of functions, symbols and lists. - -Here's an example: - -@lisp -(or gnus-article-unseen-p - gnus-article-unread-p) -@end lisp - -The available symbols are @code{or}, @code{and} and @code{not}. The -functions all take one parameter. - -@findex gnus-make-predicate -Internally, Gnus calls @code{gnus-make-predicate} on these specifiers -to create a function that can be called. This input parameter to this -function will be passed along to all the functions in the predicate -specifier. - - -@node Moderation -@section Moderation -@cindex moderation - -If you are a moderator, you can use the @file{gnus-mdrtn.el} package. -It is not included in the standard Gnus package. Write a mail to -@samp{larsi@@gnus.org} and state what group you moderate, and you'll -get a copy. - -The moderation package is implemented as a minor mode for summary -buffers. Put - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-moderate) -@end lisp - -in your @file{~/.gnus.el} file. - -If you are the moderator of @samp{rec.zoofle}, this is how it's -supposed to work: - -@enumerate -@item -You split your incoming mail by matching on -@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted -articles in some mail group---for instance, @samp{nnml:rec.zoofle}. - -@item -You enter that group once in a while and post articles using the @kbd{e} -(edit-and-post) or @kbd{s} (just send unedited) commands. - -@item -If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some -articles that weren't approved by you, you can cancel them with the -@kbd{c} command. -@end enumerate - -To use moderation mode in these two groups, say: - -@lisp -(setq gnus-moderated-list - "^nnml:rec.zoofle$\\|^rec.zoofle$") -@end lisp - - -@node Fetching a Group -@section Fetching a Group -@cindex fetching a group - -@findex gnus-fetch-group -It is sometimes convenient to be able to just say ``I want to read this -group and I don't care whether Gnus has been started or not''. This is -perhaps more useful for people who write code than for users, but the -command @code{gnus-fetch-group} provides this functionality in any case. -It takes the group name as a parameter. - - -@node Image Enhancements -@section Image Enhancements - -XEmacs, as well as Emacs 21@footnote{Emacs 21 on MS Windows doesn't -support images, Emacs 22 does.} and up, are able to display pictures and -stuff, so Gnus has taken advantage of that. - -@menu -* X-Face:: Display a funky, teensy black-and-white image. -* Face:: Display a funkier, teensier colored image. -* Smileys:: Show all those happy faces the way they were meant to be shown. -* Picons:: How to display pictures of what you're reading. -* XVarious:: Other XEmacsy Gnusey variables. -@end menu - - -@node X-Face -@subsection X-Face -@cindex x-face - -@code{X-Face} headers describe a 48x48 pixel black-and-white (1 bit -depth) image that's supposed to represent the author of the message. -It seems to be supported by an ever-growing number of mail and news -readers. - -@cindex x-face -@findex gnus-article-display-x-face -@vindex gnus-article-x-face-command -@vindex gnus-article-x-face-too-ugly -@iftex -@iflatex -\include{xface} -@end iflatex -@end iftex -@c @anchor{X-Face} - -Viewing an @code{X-Face} header either requires an Emacs that has -@samp{compface} support (which most XEmacs versions have), or that you -have suitable conversion or display programs installed. If your Emacs -has image support the default action is to display the face before the -@code{From} header. If there's no native @code{X-Face} support, Gnus -will try to convert the @code{X-Face} header using external programs -from the @code{pbmplus} package and friends, see below. For XEmacs it's -faster if XEmacs has been compiled with @code{X-Face} support. The -default action under Emacs without image support is to fork off the -@code{display} program. - -On a GNU/Linux system, the @code{display} program is included in the -ImageMagick package. For external conversion programs look for packages -with names like @code{netpbm}, @code{libgr-progs} and @code{compface}. -On Windows, you may use the packages @code{netpbm} and @code{compface} -from @url{http://gnuwin32.sourceforge.net}. You need to add the -@code{bin} directory to your @code{PATH} environment variable. -@c In fact only the following DLLs and binaries seem to be required: -@c compface1.dll uncompface.exe libnetpbm10.dll icontopbm.exe - -The variable @code{gnus-article-x-face-command} controls which programs -are used to display the @code{X-Face} header. If this variable is a -string, this string will be executed in a sub-shell. If it is a -function, this function will be called with the face as the argument. -If @code{gnus-article-x-face-too-ugly} (which is a regexp) matches the -@code{From} header, the face will not be shown. - -(Note: @code{x-face} is used in the variable/function names, not -@code{xface}). - -@noindent -Face and variable: - -@table @code -@item gnus-x-face -@vindex gnus-x-face -Face to show X-Face. The colors from this face are used as the -foreground and background colors of the displayed X-Faces. The -default colors are black and white. - -@item gnus-face-properties-alist -@vindex gnus-face-properties-alist -Alist of image types and properties applied to Face (@pxref{Face}) and -X-Face images. The default value is @code{((pbm . (:face gnus-x-face)) -(png . nil))} for Emacs or @code{((xface . (:face gnus-x-face)))} for -XEmacs. Here are examples: - -@lisp -;; Specify the altitude of Face and X-Face images in the From header. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :ascent 80)) - (png . (:ascent 80)))) - -;; Show Face and X-Face images as pressed buttons. -(setq gnus-face-properties-alist - '((pbm . (:face gnus-x-face :relief -2)) - (png . (:relief -2)))) -@end lisp - -@pxref{Image Descriptors, ,Image Descriptors, elisp, The Emacs Lisp -Reference Manual} for the valid properties for various image types. -Currently, @code{pbm} is used for X-Face images and @code{png} is used -for Face images in Emacs. Only the @code{:face} property is effective -on the @code{xface} image type in XEmacs if it is built with the -@samp{libcompface} library. -@end table - -If you use posting styles, you can use an @code{x-face-file} entry in -@code{gnus-posting-styles}, @xref{Posting Styles}. If you don't, Gnus -provides a few convenience functions and variables to allow easier -insertion of X-Face headers in outgoing messages. You also need the -above mentioned ImageMagick, netpbm or other image conversion packages -(depending the values of the variables below) for these functions. - -@findex gnus-random-x-face -@vindex gnus-convert-pbm-to-x-face-command -@vindex gnus-x-face-directory -@code{gnus-random-x-face} goes through all the @samp{pbm} files in -@code{gnus-x-face-directory} and picks one at random, and then -converts it to the X-Face format by using the -@code{gnus-convert-pbm-to-x-face-command} shell command. The -@samp{pbm} files should be 48x48 pixels big. It returns the X-Face -header data as a string. - -@findex gnus-insert-random-x-face-header -@code{gnus-insert-random-x-face-header} calls -@code{gnus-random-x-face} and inserts a @samp{X-Face} header with the -randomly generated data. - -@findex gnus-x-face-from-file -@vindex gnus-convert-image-to-x-face-command -@code{gnus-x-face-from-file} takes a GIF file as the parameter, and then -converts the file to X-Face format by using the -@code{gnus-convert-image-to-x-face-command} shell command. - -Here's how you would typically use the first function. Put something -like the following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . gnus-random-x-face)))) -@end lisp - -Using the last function would be something like this: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(X-Face . (lambda () - (gnus-x-face-from-file - "~/My-face.gif")))))) -@end lisp - - -@node Face -@subsection Face -@cindex face - -@c #### FIXME: faces and x-faces' implementations should really be harmonized. - -@code{Face} headers are essentially a funkier version of @code{X-Face} -ones. They describe a 48x48 pixel colored image that's supposed to -represent the author of the message. - -@cindex face -@findex gnus-article-display-face -The contents of a @code{Face} header must be a base64 encoded PNG image. -See @uref{http://quimby.gnus.org/circus/face/} for the precise -specifications. - -The @code{gnus-face-properties-alist} variable affects the appearance of -displayed Face images. @xref{X-Face}. - -Viewing an @code{Face} header requires an Emacs that is able to display -PNG images. -@c Maybe add this: -@c (if (featurep 'xemacs) -@c (featurep 'png) -@c (image-type-available-p 'png)) - -Gnus provides a few convenience functions and variables to allow -easier insertion of Face headers in outgoing messages. - -@findex gnus-convert-png-to-face -@code{gnus-convert-png-to-face} takes a 48x48 PNG image, no longer than -726 bytes long, and converts it to a face. - -@findex gnus-face-from-file -@vindex gnus-convert-image-to-face-command -@code{gnus-face-from-file} takes a JPEG file as the parameter, and then -converts the file to Face format by using the -@code{gnus-convert-image-to-face-command} shell command. - -Here's how you would typically use this function. Put something like the -following in your @file{~/.gnus.el} file: - -@lisp -(setq message-required-news-headers - (nconc message-required-news-headers - (list '(Face . (lambda () - (gnus-face-from-file "~/face.jpg")))))) -@end lisp - - -@node Smileys -@subsection Smileys -@cindex smileys - -@iftex -@iflatex -\gnusfig{-3cm}{0.5cm}{\epsfig{figure=ps/BigFace,height=20cm}} -\input{smiley} -@end iflatex -@end iftex - -@dfn{Smiley} is a package separate from Gnus, but since Gnus is -currently the only package that uses Smiley, it is documented here. - -In short---to use Smiley in Gnus, put the following in your -@file{~/.gnus.el} file: - -@lisp -(setq gnus-treat-display-smileys t) -@end lisp - -Smiley maps text smiley faces---@samp{:-)}, @samp{8-)}, @samp{:-(} and -the like---to pictures and displays those instead of the text smiley -faces. The conversion is controlled by a list of regexps that matches -text and maps that to file names. - -@vindex smiley-regexp-alist -The alist used is specified by the @code{smiley-regexp-alist} -variable. The first item in each element is the regexp to be matched; -the second element is the regexp match group that is to be replaced by -the picture; and the third element is the name of the file to be -displayed. - -The following variables customize the appearance of the smileys: - -@table @code - -@item smiley-style -@vindex smiley-style -Specifies the smiley style. Predefined smiley styles include -@code{low-color} (small 13x14 pixel, three-color images), @code{medium} -(more colorful images, 16x16 pixel), and @code{grayscale} (grayscale -images, 14x14 pixel). The default depends on the height of the default -face. - -@item smiley-data-directory -@vindex smiley-data-directory -Where Smiley will look for smiley faces files. You shouldn't set this -variable anymore. Customize @code{smiley-style} instead. - -@item gnus-smiley-file-types -@vindex gnus-smiley-file-types -List of suffixes on smiley file names to try. - -@end table - - -@node Picons -@subsection Picons - -@iftex -@iflatex -\include{picons} -@end iflatex -@end iftex - -So@dots{} You want to slow down your news reader even more! This is a -good way to do so. It's also a great way to impress people staring -over your shoulder as you read news. - -What are Picons? To quote directly from the Picons Web site: - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - -@quotation -@dfn{Picons} is short for ``personal icons''. They're small, -constrained images used to represent users and domains on the net, -organized into databases so that the appropriate image for a given -e-mail address can be found. Besides users and domains, there are picon -databases for Usenet newsgroups and weather forecasts. The picons are -in either monochrome @code{XBM} format or color @code{XPM} and -@code{GIF} formats. -@end quotation - -@vindex gnus-picon-databases -For instructions on obtaining and installing the picons databases, -point your Web browser at -@uref{http://www.cs.indiana.edu/picons/ftp/index.html}. - -If you are using Debian GNU/Linux, saying @samp{apt-get install -picons.*} will install the picons where Gnus can find them. - -To enable displaying picons, simply make sure that -@code{gnus-picon-databases} points to the directory containing the -Picons databases. - -@vindex gnus-picon-style -The variable @code{gnus-picon-style} controls how picons are displayed. -If @code{inline}, the textual representation is replaced. If -@code{right}, picons are added right to the textual representation. - -The following variables offer control over where things are located. - -@table @code - -@item gnus-picon-databases -@vindex gnus-picon-databases -The location of the picons database. This is a list of directories -containing the @file{news}, @file{domains}, @file{users} (and so on) -subdirectories. Defaults to @code{("/usr/lib/picon" -"/usr/local/faces")}. - -@item gnus-picon-news-directories -@vindex gnus-picon-news-directories -List of subdirectories to search in @code{gnus-picon-databases} for -newsgroups faces. @code{("news")} is the default. - -@item gnus-picon-user-directories -@vindex gnus-picon-user-directories -List of subdirectories to search in @code{gnus-picon-databases} for user -faces. @code{("users" "usenix" "local" "misc")} is the default. - -@item gnus-picon-domain-directories -@vindex gnus-picon-domain-directories -List of subdirectories to search in @code{gnus-picon-databases} for -domain name faces. Defaults to @code{("domains")}. Some people may -want to add @samp{"unknown"} to this list. - -@item gnus-picon-file-types -@vindex gnus-picon-file-types -Ordered list of suffixes on picon file names to try. Defaults to -@code{("xpm" "gif" "xbm")} minus those not built-in your Emacs. - -@end table - - -@node XVarious -@subsection Various XEmacs Variables - -@table @code -@item gnus-xmas-glyph-directory -@vindex gnus-xmas-glyph-directory -This is where Gnus will look for pictures. Gnus will normally -auto-detect this directory, but you may set it manually if you have an -unusual directory structure. - -@item gnus-xmas-modeline-glyph -@vindex gnus-xmas-modeline-glyph -A glyph displayed in all Gnus mode lines. It is a tiny gnu head by -default. - -@end table - -@subsubsection Toolbar - -@table @code - -@item gnus-use-toolbar -@vindex gnus-use-toolbar -This variable specifies the position to display the toolbar. If -@code{nil}, don't display toolbars. If it is non-@code{nil}, it should -be one of the symbols @code{default}, @code{top}, @code{bottom}, -@code{right}, and @code{left}. @code{default} means to use the default -toolbar, the rest mean to display the toolbar on the place which those -names show. The default is @code{default}. - -@item gnus-toolbar-thickness -@vindex gnus-toolbar-thickness -Cons of the height and the width specifying the thickness of a toolbar. -The height is used for the toolbar displayed on the top or the bottom, -the width is used for the toolbar displayed on the right or the left. -The default is that of the default toolbar. - -@item gnus-group-toolbar -@vindex gnus-group-toolbar -The toolbar in the group buffer. - -@item gnus-summary-toolbar -@vindex gnus-summary-toolbar -The toolbar in the summary buffer. - -@item gnus-summary-mail-toolbar -@vindex gnus-summary-mail-toolbar -The toolbar in the summary buffer of mail groups. - -@end table - -@iftex -@iflatex -\margindex{} -@end iflatex -@end iftex - - -@node Fuzzy Matching -@section Fuzzy Matching -@cindex fuzzy matching - -Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing -things like scoring, thread gathering and thread comparison. - -As opposed to regular expression matching, fuzzy matching is very fuzzy. -It's so fuzzy that there's not even a definition of what @dfn{fuzziness} -means, and the implementation has changed over time. - -Basically, it tries to remove all noise from lines before comparing. -@samp{Re: }, parenthetical remarks, white space, and so on, are filtered -out of the strings before comparing the results. This often leads to -adequate results---even when faced with strings generated by text -manglers masquerading as newsreaders. - - -@node Thwarting Email Spam -@section Thwarting Email Spam -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -In these last days of the Usenet, commercial vultures are hanging about -and grepping through news like crazy to find email addresses they can -foist off their scams and products to. As a reaction to this, many -people have started putting nonsense addresses into their @code{From} -lines. I think this is counterproductive---it makes it difficult for -people to send you legitimate mail in response to things you write, as -well as making it difficult to see who wrote what. This rewriting may -perhaps be a bigger menace than the unsolicited commercial email itself -in the end. - -The biggest problem I have with email spam is that it comes in under -false pretenses. I press @kbd{g} and Gnus merrily informs me that I -have 10 new emails. I say ``Golly gee! Happy is me!'' and select the -mail group, only to find two pyramid schemes, seven advertisements -(``New! Miracle tonic for growing full, lustrous hair on your toes!'') -and one mail asking me to repent and find some god. - -This is annoying. Here's what you can do about it. - -@menu -* The problem of spam:: Some background, and some solutions -* Anti-Spam Basics:: Simple steps to reduce the amount of spam. -* SpamAssassin:: How to use external anti-spam tools. -* Hashcash:: Reduce spam by burning CPU time. -@end menu - -@node The problem of spam -@subsection The problem of spam -@cindex email spam -@cindex spam filtering approaches -@cindex filtering approaches, spam -@cindex UCE -@cindex unsolicited commercial email - -First, some background on spam. - -If you have access to e-mail, you are familiar with spam (technically -termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it -exists because e-mail delivery is very cheap compared to paper mail, -so only a very small percentage of people need to respond to an UCE to -make it worthwhile to the advertiser. Ironically, one of the most -common spams is the one offering a database of e-mail addresses for -further spamming. Senders of spam are usually called @emph{spammers}, -but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and -@emph{morons} are in common use as well. - -Spam comes from a wide variety of sources. It is simply impossible to -dispose of all spam without discarding useful messages. A good -example is the TMDA system, which requires senders -unknown to you to confirm themselves as legitimate senders before -their e-mail can reach you. Without getting into the technical side -of TMDA, a downside is clearly that e-mail from legitimate sources may -be discarded if those sources can't or won't confirm themselves -through the TMDA system. Another problem with TMDA is that it -requires its users to have a basic understanding of e-mail delivery -and processing. - -The simplest approach to filtering spam is filtering, at the mail -server or when you sort through incoming mail. If you get 200 spam -messages per day from @samp{random-address@@vmadmin.com}, you block -@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you -discard all messages with @samp{VIAGRA} in the message. If you get -lots of spam from Bulgaria, for example, you try to filter all mail -from Bulgarian IPs. - -This, unfortunately, is a great way to discard legitimate e-mail. The -risks of blocking a whole country (Bulgaria, Norway, Nigeria, China, -etc.) or even a continent (Asia, Africa, Europe, etc.) from contacting -you should be obvious, so don't do it if you have the choice. - -In another instance, the very informative and useful RISKS digest has -been blocked by overzealous mail filters because it @strong{contained} -words that were common in spam messages. Nevertheless, in isolated -cases, with great care, direct filtering of mail can be useful. - -Another approach to filtering e-mail is the distributed spam -processing, for instance DCC implements such a system. In essence, -@var{N} systems around the world agree that a machine @var{X} in -Ghana, Estonia, or California is sending out spam e-mail, and these -@var{N} systems enter @var{X} or the spam e-mail from @var{X} into a -database. The criteria for spam detection vary---it may be the number -of messages sent, the content of the messages, and so on. When a user -of the distributed processing system wants to find out if a message is -spam, he consults one of those @var{N} systems. - -Distributed spam processing works very well against spammers that send -a large number of messages at once, but it requires the user to set up -fairly complicated checks. There are commercial and free distributed -spam processing systems. Distributed spam processing has its risks as -well. For instance legitimate e-mail senders have been accused of -sending spam, and their web sites and mailing lists have been shut -down for some time because of the incident. - -The statistical approach to spam filtering is also popular. It is -based on a statistical analysis of previous spam messages. Usually -the analysis is a simple word frequency count, with perhaps pairs of -words or 3-word combinations thrown into the mix. Statistical -analysis of spam works very well in most of the cases, but it can -classify legitimate e-mail as spam in some cases. It takes time to -run the analysis, the full message must be analyzed, and the user has -to store the database of spam analysis. Statistical analysis on the -server is gaining popularity. This has the advantage of letting the -user Just Read Mail, but has the disadvantage that it's harder to tell -the server that it has misclassified mail. - -Fighting spam is not easy, no matter what anyone says. There is no -magic switch that will distinguish Viagra ads from Mom's e-mails. -Even people are having a hard time telling spam apart from non-spam, -because spammers are actively looking to fool us into thinking they -are Mom, essentially. Spamming is irritating, irresponsible, and -idiotic behavior from a bunch of people who think the world owes them -a favor. We hope the following sections will help you in fighting the -spam plague. - -@node Anti-Spam Basics -@subsection Anti-Spam Basics -@cindex email spam -@cindex spam -@cindex UCE -@cindex unsolicited commercial email - -One way of dealing with spam is having Gnus split out all spam into a -@samp{spam} mail group (@pxref{Splitting Mail}). - -First, pick one (1) valid mail address that you can be reached at, and -put it in your @code{From} header of all your news articles. (I've -chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form -@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your -sysadmin whether your sendmail installation accepts keywords in the local -part of the mail address.) - -@lisp -(setq message-default-news-headers - "From: Lars Magne Ingebrigtsen \n") -@end lisp - -Then put the following split rule in @code{nnmail-split-fancy} -(@pxref{Fancy Mail Splitting}): - -@lisp -(... - (to "larsi@@trym.ifi.uio.no" - (| ("subject" "re:.*" "misc") - ("references" ".*@@.*" "misc") - "spam")) - ...) -@end lisp - -This says that all mail to this address is suspect, but if it has a -@code{Subject} that starts with a @samp{Re:} or has a @code{References} -header, it's probably ok. All the rest goes to the @samp{spam} group. -(This idea probably comes from Tim Pierce.) - -In addition, many mail spammers talk directly to your @acronym{SMTP} server -and do not include your email address explicitly in the @code{To} -header. Why they do this is unknown---perhaps it's to thwart this -thwarting scheme? In any case, this is trivial to deal with---you just -put anything not addressed to you in the @samp{spam} group by ending -your fancy split rule in this way: - -@lisp -( - ... - (to "larsi" "misc") - "spam") -@end lisp - -In my experience, this will sort virtually everything into the right -group. You still have to check the @samp{spam} group from time to time to -check for legitimate mail, though. If you feel like being a good net -citizen, you can even send off complaints to the proper authorities on -each unsolicited commercial email---at your leisure. - -This works for me. It allows people an easy way to contact me (they can -just press @kbd{r} in the usual way), and I'm not bothered at all with -spam. It's a win-win situation. Forging @code{From} headers to point -to non-existent domains is yucky, in my opinion. - -Be careful with this approach. Spammers are wise to it. - - -@node SpamAssassin -@subsection SpamAssassin, Vipul's Razor, DCC, etc -@cindex SpamAssassin -@cindex Vipul's Razor -@cindex DCC - -The days where the hints in the previous section were sufficient in -avoiding spam are coming to an end. There are many tools out there -that claim to reduce the amount of spam you get. This section could -easily become outdated fast, as new products replace old, but -fortunately most of these tools seem to have similar interfaces. Even -though this section will use SpamAssassin as an example, it should be -easy to adapt it to most other tools. - -Note that this section does not involve the @code{spam.el} package, -which is discussed in the next section. If you don't care for all -the features of @code{spam.el}, you can make do with these simple -recipes. - -If the tool you are using is not installed on the mail server, you -need to invoke it yourself. Ideas on how to use the -@code{:postscript} mail source parameter (@pxref{Mail Source -Specifiers}) follow. - -@lisp -(setq mail-sources - '((file :prescript "formail -bs spamassassin < /var/mail/%u") - (pop :user "jrl" - :server "pophost" - :postscript - "mv %t /tmp/foo; formail -bs spamc < /tmp/foo > %t"))) -@end lisp - -Once you manage to process your incoming spool somehow, thus making -the mail contain e.g.@: a header indicating it is spam, you are ready to -filter it out. Using normal split methods (@pxref{Splitting Mail}): - -@lisp -(setq nnmail-split-methods '(("spam" "^X-Spam-Flag: YES") - ...)) -@end lisp - -Or using fancy split methods (@pxref{Fancy Mail Splitting}): - -@lisp -(setq nnmail-split-methods 'nnmail-split-fancy - nnmail-split-fancy '(| ("X-Spam-Flag" "YES" "spam") - ...)) -@end lisp - -Some people might not like the idea of piping the mail through various -programs using a @code{:prescript} (if some program is buggy, you -might lose all mail). If you are one of them, another solution is to -call the external tools during splitting. Example fancy split method: - -@lisp -(setq nnmail-split-fancy '(| (: kevin-spamassassin) - ...)) -(defun kevin-spamassassin () - (save-excursion - (save-restriction - (widen) - (if (eq 1 (call-process-region (point-min) (point-max) - "spamc" nil nil nil "-c")) - "spam")))) -@end lisp - -Note that with the nnimap back end, message bodies will not be -downloaded by default. You need to set -@code{nnimap-split-download-body} to @code{t} to do that -(@pxref{Splitting in IMAP}). - -That is about it. As some spam is likely to get through anyway, you -might want to have a nifty function to call when you happen to read -spam. And here is the nifty function: - -@lisp -(defun my-gnus-raze-spam () - "Submit SPAM to Vipul's Razor, then mark it as expirable." - (interactive) - (gnus-summary-save-in-pipe "razor-report -f -d" t) - (gnus-summary-mark-as-expirable 1)) -@end lisp - -@node Hashcash -@subsection Hashcash -@cindex hashcash - -A novel technique to fight spam is to require senders to do something -costly and demonstrably unique for each message they send. This has -the obvious drawback that you cannot rely on everyone in the world -using this technique, since it is not part of the Internet standards, -but it may be useful in smaller communities. - -While the tools in the previous section work well in practice, they -work only because the tools are constantly maintained and updated as -new form of spam appears. This means that a small percentage of spam -will always get through. It also means that somewhere, someone needs -to read lots of spam to update these tools. Hashcash avoids that, but -instead prefers that everyone you contact through e-mail supports the -scheme. You can view the two approaches as pragmatic vs dogmatic. -The approaches have their own advantages and disadvantages, but as -often in the real world, a combination of them is stronger than either -one of them separately. - -@cindex X-Hashcash -The ``something costly'' is to burn CPU time, more specifically to -compute a hash collision up to a certain number of bits. The -resulting hashcash cookie is inserted in a @samp{X-Hashcash:} header. -For more details, and for the external application @code{hashcash} you -need to install to use this feature, see -@uref{http://www.hashcash.org/}. Even more information can be found -at @uref{http://www.camram.org/}. - -If you wish to generate hashcash for each message you send, you can -customize @code{message-generate-hashcash} (@pxref{Mail Headers, ,Mail -Headers,message, The Message Manual}), as in: - -@lisp -(setq message-generate-hashcash t) -@end lisp - -You will need to set up some additional variables as well: - -@table @code - -@item hashcash-default-payment -@vindex hashcash-default-payment -This variable indicates the default number of bits the hash collision -should consist of. By default this is 20. Suggested useful values -include 17 to 29. - -@item hashcash-payment-alist -@vindex hashcash-payment-alist -Some receivers may require you to spend burn more CPU time than the -default. This variable contains a list of @samp{(@var{addr} -@var{amount})} cells, where @var{addr} is the receiver (email address -or newsgroup) and @var{amount} is the number of bits in the collision -that is needed. It can also contain @samp{(@var{addr} @var{string} -@var{amount})} cells, where the @var{string} is the string to use -(normally the email address or newsgroup name is used). - -@item hashcash-path -@vindex hashcash-path -Where the @code{hashcash} binary is installed. This variable should -be automatically set by @code{executable-find}, but if it's @code{nil} -(usually because the @code{hashcash} binary is not in your path) -you'll get a warning when you check hashcash payments and an error -when you generate hashcash payments. - -@end table - -Gnus can verify hashcash cookies, although this can also be done by -hand customized mail filtering scripts. To verify a hashcash cookie -in a message, use the @code{mail-check-payment} function in the -@code{hashcash.el} library. You can also use the @code{spam.el} -package with the @code{spam-use-hashcash} back end to validate hashcash -cookies in incoming mail and filter mail accordingly (@pxref{Anti-spam -Hashcash Payments}). - -@node Spam Package -@section Spam Package -@cindex spam filtering -@cindex spam - -The Spam package provides Gnus with a centralized mechanism for -detecting and filtering spam. It filters new mail, and processes -messages according to whether they are spam or ham. (@dfn{Ham} is the -name used throughout this manual to indicate non-spam messages.) - -@menu -* Spam Package Introduction:: -* Filtering Incoming Mail:: -* Detecting Spam in Groups:: -* Spam and Ham Processors:: -* Spam Package Configuration Examples:: -* Spam Back Ends:: -* Extending the Spam package:: -* Spam Statistics Package:: -@end menu - -@node Spam Package Introduction -@subsection Spam Package Introduction -@cindex spam filtering -@cindex spam filtering sequence of events -@cindex spam - -You must read this section to understand how the Spam package works. -Do not skip, speed-read, or glance through this section. - -Make sure you read the section on the @code{spam.el} sequence of -events. See @xref{Extending the Spam package}. - -@cindex spam-initialize -@vindex spam-use-stat -To use the Spam package, you @strong{must} first run the function -@code{spam-initialize}: - -@example -(spam-initialize) -@end example - -This autoloads @code{spam.el} and installs the various hooks necessary -to let the Spam package do its job. In order to make use of the Spam -package, you have to set up certain group parameters and variables, -which we will describe below. All of the variables controlling the -Spam package can be found in the @samp{spam} customization group. - -There are two ``contact points'' between the Spam package and the rest -of Gnus: checking new mail for spam, and leaving a group. - -Checking new mail for spam is done in one of two ways: while splitting -incoming mail, or when you enter a group. - -The first way, checking for spam while splitting incoming mail, is -suited to mail back ends such as @code{nnml} or @code{nnimap}, where -new mail appears in a single spool file. The Spam package processes -incoming mail, and sends mail considered to be spam to a designated -``spam'' group. @xref{Filtering Incoming Mail}. - -The second way is suited to back ends such as @code{nntp}, which have -no incoming mail spool, or back ends where the server is in charge of -splitting incoming mail. In this case, when you enter a Gnus group, -the unseen or unread messages in that group are checked for spam. -Detected spam messages are marked as spam. @xref{Detecting Spam in -Groups}. - -@cindex spam back ends -In either case, you have to tell the Spam package what method to use -to detect spam messages. There are several methods, or @dfn{spam back -ends} (not to be confused with Gnus back ends!) to choose from: spam -``blacklists'' and ``whitelists'', dictionary-based filters, and so -forth. @xref{Spam Back Ends}. - -In the Gnus summary buffer, messages that have been identified as spam -always appear with a @samp{$} symbol. - -The Spam package divides Gnus groups into three categories: ham -groups, spam groups, and unclassified groups. You should mark each of -the groups you subscribe to as either a ham group or a spam group, -using the @code{spam-contents} group parameter (@pxref{Group -Parameters}). Spam groups have a special property: when you enter a -spam group, all unseen articles are marked as spam. Thus, mail split -into a spam group is automatically marked as spam. - -Identifying spam messages is only half of the Spam package's job. The -second half comes into play whenever you exit a group buffer. At this -point, the Spam package does several things: - -First, it calls @dfn{spam and ham processors} to process the articles -according to whether they are spam or ham. There is a pair of spam -and ham processors associated with each spam back end, and what the -processors do depends on the back end. At present, the main role of -spam and ham processors is for dictionary-based spam filters: they add -the contents of the messages in the group to the filter's dictionary, -to improve its ability to detect future spam. The @code{spam-process} -group parameter specifies what spam processors to use. @xref{Spam and -Ham Processors}. - -If the spam filter failed to mark a spam message, you can mark it -yourself, so that the message is processed as spam when you exit the -group: - -@table @kbd -@item M-d -@itemx M s x -@itemx S x -@kindex M-d -@kindex S x -@kindex M s x -@findex gnus-summary-mark-as-spam -@findex gnus-summary-mark-as-spam -Mark current article as spam, showing it with the @samp{$} mark -(@code{gnus-summary-mark-as-spam}). -@end table - -@noindent -Similarly, you can unmark an article if it has been erroneously marked -as spam. @xref{Setting Marks}. - -Normally, a ham message found in a non-ham group is not processed as -ham---the rationale is that it should be moved into a ham group for -further processing (see below). However, you can force these articles -to be processed as ham by setting -@code{spam-process-ham-in-spam-groups} and -@code{spam-process-ham-in-nonham-groups}. - -@vindex gnus-ham-process-destinations -@vindex gnus-spam-process-destinations -The second thing that the Spam package does when you exit a group is -to move ham articles out of spam groups, and spam articles out of ham -groups. Ham in a spam group is moved to the group specified by the -variable @code{gnus-ham-process-destinations}, or the group parameter -@code{ham-process-destination}. Spam in a ham group is moved to the -group specified by the variable @code{gnus-spam-process-destinations}, -or the group parameter @code{spam-process-destination}. If these -variables are not set, the articles are left in their current group. -If an article cannot be moved (e.g., with a read-only backend such -as @acronym{NNTP}), it is copied. - -If an article is moved to another group, it is processed again when -you visit the new group. Normally, this is not a problem, but if you -want each article to be processed only once, load the -@code{gnus-registry.el} package and set the variable -@code{spam-log-to-registry} to @code{t}. @xref{Spam Package -Configuration Examples}. - -Normally, spam groups ignore @code{gnus-spam-process-destinations}. -However, if you set @code{spam-move-spam-nonspam-groups-only} to -@code{nil}, spam will also be moved out of spam groups, depending on -the @code{spam-process-destination} parameter. - -The final thing the Spam package does is to mark spam articles as -expired, which is usually the right thing to do. - -If all this seems confusing, don't worry. Soon it will be as natural -as typing Lisp one-liners on a neural interface@dots{} err, sorry, that's -50 years in the future yet. Just trust us, it's not so bad. - -@node Filtering Incoming Mail -@subsection Filtering Incoming Mail -@cindex spam filtering -@cindex spam filtering incoming mail -@cindex spam - -To use the Spam package to filter incoming mail, you must first set up -fancy mail splitting. @xref{Fancy Mail Splitting}. The Spam package -defines a special splitting function that you can add to your fancy -split variable (either @code{nnmail-split-fancy} or -@code{nnimap-split-fancy}, depending on your mail back end): - -@example -(: spam-split) -@end example - -@vindex spam-split-group -@noindent -The @code{spam-split} function scans incoming mail according to your -chosen spam back end(s), and sends messages identified as spam to a -spam group. By default, the spam group is a group named @samp{spam}, -but you can change this by customizing @code{spam-split-group}. Make -sure the contents of @code{spam-split-group} are an unqualified group -name. For instance, in an @code{nnimap} server @samp{your-server}, -the value @samp{spam} means @samp{nnimap+your-server:spam}. The value -@samp{nnimap+server:spam} is therefore wrong---it gives the group -@samp{nnimap+your-server:nnimap+server:spam}. - -@code{spam-split} does not modify the contents of messages in any way. - -@vindex nnimap-split-download-body -Note for IMAP users: if you use the @code{spam-check-bogofilter}, -@code{spam-check-ifile}, and @code{spam-check-stat} spam back ends, -you should also set the variable @code{nnimap-split-download-body} -to @code{t}. These spam back ends are most useful when they can -``scan'' the full message body. By default, the nnimap back end only -retrieves the message headers; @code{nnimap-split-download-body} tells -it to retrieve the message bodies as well. We don't set this by -default because it will slow @acronym{IMAP} down, and that is not an -appropriate decision to make on behalf of the user. @xref{Splitting -in IMAP}. - -You have to specify one or more spam back ends for @code{spam-split} -to use, by setting the @code{spam-use-*} variables. @xref{Spam Back -Ends}. Normally, @code{spam-split} simply uses all the spam back ends -you enabled in this way. However, you can tell @code{spam-split} to -use only some of them. Why this is useful? Suppose you are using the -@code{spam-use-regex-headers} and @code{spam-use-blackholes} spam back -ends, and the following split rule: - -@example - nnimap-split-fancy '(| - (any "ding" "ding") - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -The problem is that you want all ding messages to make it to the ding -folder. But that will let obvious spam (for example, spam detected by -SpamAssassin, and @code{spam-use-regex-headers}) through, when it's -sent to the ding list. On the other hand, some messages to the ding -list are from a mail server in the blackhole list, so the invocation -of @code{spam-split} can't be before the ding rule. - -The solution is to let SpamAssassin headers supersede ding rules, and -perform the other @code{spam-split} rules (including a second -invocation of the regex-headers check) after the ding rule. This is -done by passing a parameter to @code{spam-split}: - -@example -nnimap-split-fancy - '(| - ;; @r{spam detected by @code{spam-use-regex-headers} goes to @samp{regex-spam}} - (: spam-split "regex-spam" 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{all other spam detected by spam-split goes to @code{spam-split-group}} - (: spam-split) - ;; @r{default mailbox} - "mail") -@end example - -@noindent -This lets you invoke specific @code{spam-split} checks depending on -your particular needs, and target the results of those checks to a -particular spam group. You don't have to throw all mail into all the -spam tests. Another reason why this is nice is that messages to -mailing lists you have rules for don't have to have resource-intensive -blackhole checks performed on them. You could also specify different -spam checks for your nnmail split vs. your nnimap split. Go crazy. - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. @xref{Spam Back Ends}. - -@c @emph{TODO: spam.el needs to provide a uniform way of training all the -@c statistical databases. Some have that functionality built-in, others -@c don't.} - -@node Detecting Spam in Groups -@subsection Detecting Spam in Groups - -To detect spam when visiting a group, set the group's -@code{spam-autodetect} and @code{spam-autodetect-methods} group -parameters. These are accessible with @kbd{G c} or @kbd{G p}, as -usual (@pxref{Group Parameters}). - -You should set the @code{spam-use-*} variables for whatever spam back -ends you intend to use. The reason is that when loading -@file{spam.el}, some conditional loading is done depending on what -@code{spam-use-xyz} variables you have set. - -By default, only unseen articles are processed for spam. You can -force Gnus to recheck all messages in the group by setting the -variable @code{spam-autodetect-recheck-messages} to @code{t}. - -If you use the @code{spam-autodetect} method of checking for spam, you -can specify different spam detection methods for different groups. -For instance, the @samp{ding} group may have @code{spam-use-BBDB} as -the autodetection method, while the @samp{suspect} group may have the -@code{spam-use-blacklist} and @code{spam-use-bogofilter} methods -enabled. Unlike with @code{spam-split}, you don't have any control -over the @emph{sequence} of checks, but this is probably unimportant. - -@node Spam and Ham Processors -@subsection Spam and Ham Processors -@cindex spam filtering -@cindex spam filtering variables -@cindex spam variables -@cindex spam - -@vindex gnus-spam-process-newsgroups -Spam and ham processors specify special actions to take when you exit -a group buffer. Spam processors act on spam messages, and ham -processors on ham messages. At present, the main role of these -processors is to update the dictionaries of dictionary-based spam back -ends such as Bogofilter (@pxref{Bogofilter}) and the Spam Statistics -package (@pxref{Spam Statistics Filtering}). - -The spam and ham processors that apply to each group are determined by -the group's@code{spam-process} group parameter. If this group -parameter is not defined, they are determined by the variable -@code{gnus-spam-process-newsgroups}. - -@vindex gnus-spam-newsgroup-contents -Gnus learns from the spam you get. You have to collect your spam in -one or more spam groups, and set or customize the variable -@code{spam-junk-mailgroups} as appropriate. You can also declare -groups to contain spam by setting their group parameter -@code{spam-contents} to @code{gnus-group-spam-classification-spam}, or -by customizing the corresponding variable -@code{gnus-spam-newsgroup-contents}. The @code{spam-contents} group -parameter and the @code{gnus-spam-newsgroup-contents} variable can -also be used to declare groups as @emph{ham} groups if you set their -classification to @code{gnus-group-spam-classification-ham}. If -groups are not classified by means of @code{spam-junk-mailgroups}, -@code{spam-contents}, or @code{gnus-spam-newsgroup-contents}, they are -considered @emph{unclassified}. All groups are unclassified by -default. - -@vindex gnus-spam-mark -@cindex $ -In spam groups, all messages are considered to be spam by default: -they get the @samp{$} mark (@code{gnus-spam-mark}) when you enter the -group. If you have seen a message, had it marked as spam, then -unmarked it, it won't be marked as spam when you enter the group -thereafter. You can disable that behavior, so all unread messages -will get the @samp{$} mark, if you set the -@code{spam-mark-only-unseen-as-spam} parameter to @code{nil}. You -should remove the @samp{$} mark when you are in the group summary -buffer for every message that is not spam after all. To remove the -@samp{$} mark, you can use @kbd{M-u} to ``unread'' the article, or -@kbd{d} for declaring it read the non-spam way. When you leave a -group, all spam-marked (@samp{$}) articles are sent to a spam -processor which will study them as spam samples. - -Messages may also be deleted in various other ways, and unless -@code{ham-marks} group parameter gets overridden below, marks @samp{R} -and @samp{r} for default read or explicit delete, marks @samp{X} and -@samp{K} for automatic or explicit kills, as well as mark @samp{Y} for -low scores, are all considered to be associated with articles which -are not spam. This assumption might be false, in particular if you -use kill files or score files as means for detecting genuine spam, you -should then adjust the @code{ham-marks} group parameter. - -@defvar ham-marks -You can customize this group or topic parameter to be the list of -marks you want to consider ham. By default, the list contains the -deleted, read, killed, kill-filed, and low-score marks (the idea is -that these articles have been read, but are not spam). It can be -useful to also include the tick mark in the ham marks. It is not -recommended to make the unread mark a ham mark, because it normally -indicates a lack of classification. But you can do it, and we'll be -happy for you. -@end defvar - -@defvar spam-marks -You can customize this group or topic parameter to be the list of -marks you want to consider spam. By default, the list contains only -the spam mark. It is not recommended to change that, but you can if -you really want to. -@end defvar - -When you leave @emph{any} group, regardless of its -@code{spam-contents} classification, all spam-marked articles are sent -to a spam processor, which will study these as spam samples. If you -explicit kill a lot, you might sometimes end up with articles marked -@samp{K} which you never saw, and which might accidentally contain -spam. Best is to make sure that real spam is marked with @samp{$}, -and nothing else. - -@vindex gnus-ham-process-destinations -When you leave a @emph{spam} group, all spam-marked articles are -marked as expired after processing with the spam processor. This is -not done for @emph{unclassified} or @emph{ham} groups. Also, any -@strong{ham} articles in a spam group will be moved to a location -determined by either the @code{ham-process-destination} group -parameter or a match in the @code{gnus-ham-process-destinations} -variable, which is a list of regular expressions matched with group -names (it's easiest to customize this variable with @kbd{M-x -customize-variable @key{RET} gnus-ham-process-destinations}). Each -group name list is a standard Lisp list, if you prefer to customize -the variable manually. If the @code{ham-process-destination} -parameter is not set, ham articles are left in place. If the -@code{spam-mark-ham-unread-before-move-from-spam-group} parameter is -set, the ham articles are marked as unread before being moved. - -If ham can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your ham to a regular mail -group and to a @emph{ham training} group. - -When you leave a @emph{ham} group, all ham-marked articles are sent to -a ham processor, which will study these as non-spam samples. - -@vindex spam-process-ham-in-spam-groups -By default the variable @code{spam-process-ham-in-spam-groups} is -@code{nil}. Set it to @code{t} if you want ham found in spam groups -to be processed. Normally this is not done, you are expected instead -to send your ham to a ham group and process it there. - -@vindex spam-process-ham-in-nonham-groups -By default the variable @code{spam-process-ham-in-nonham-groups} is -@code{nil}. Set it to @code{t} if you want ham found in non-ham (spam -or unclassified) groups to be processed. Normally this is not done, -you are expected instead to send your ham to a ham group and process -it there. - -@vindex gnus-spam-process-destinations -When you leave a @emph{ham} or @emph{unclassified} group, all -@strong{spam} articles are moved to a location determined by either -the @code{spam-process-destination} group parameter or a match in the -@code{gnus-spam-process-destinations} variable, which is a list of -regular expressions matched with group names (it's easiest to -customize this variable with @kbd{M-x customize-variable @key{RET} -gnus-spam-process-destinations}). Each group name list is a standard -Lisp list, if you prefer to customize the variable manually. If the -@code{spam-process-destination} parameter is not set, the spam -articles are only expired. The group name is fully qualified, meaning -that if you see @samp{nntp:servername} before the group name in the -group buffer then you need it here as well. - -If spam can not be moved---because of a read-only back end such as -@acronym{NNTP}, for example, it will be copied. - -Note that you can use multiples destinations per group or regular -expression! This enables you to send your spam to multiple @emph{spam -training} groups. - -@vindex spam-log-to-registry -The problem with processing ham and spam is that Gnus doesn't track -this processing by default. Enable the @code{spam-log-to-registry} -variable so @code{spam.el} will use @code{gnus-registry.el} to track -what articles have been processed, and avoid processing articles -multiple times. Keep in mind that if you limit the number of registry -entries, this won't work as well as it does without a limit. - -@vindex spam-mark-only-unseen-as-spam -Set this variable if you want only unseen articles in spam groups to -be marked as spam. By default, it is set. If you set it to -@code{nil}, unread articles will also be marked as spam. - -@vindex spam-mark-ham-unread-before-move-from-spam-group -Set this variable if you want ham to be unmarked before it is moved -out of the spam group. This is very useful when you use something -like the tick mark @samp{!} to mark ham---the article will be placed -in your @code{ham-process-destination}, unmarked as if it came fresh -from the mail server. - -@vindex spam-autodetect-recheck-messages -When autodetecting spam, this variable tells @code{spam.el} whether -only unseen articles or all unread articles should be checked for -spam. It is recommended that you leave it off. - -@node Spam Package Configuration Examples -@subsection Spam Package Configuration Examples -@cindex spam filtering -@cindex spam filtering configuration examples -@cindex spam configuration examples -@cindex spam - -@subsubheading Ted's setup - -From Ted Zlatanov . -@example -;; @r{for @code{gnus-registry-split-fancy-with-parent} and spam autodetection} -;; @r{see @file{gnus-registry.el} for more information} -(gnus-registry-initialize) -(spam-initialize) - -(setq - spam-log-to-registry t ; @r{for spam autodetection} - spam-use-BBDB t - spam-use-regex-headers t ; @r{catch X-Spam-Flag (SpamAssassin)} - ;; @r{all groups with @samp{spam} in the name contain spam} - gnus-spam-newsgroup-contents - '(("spam" gnus-group-spam-classification-spam)) - ;; @r{see documentation for these} - spam-move-spam-nonspam-groups-only nil - spam-mark-only-unseen-as-spam t - spam-mark-ham-unread-before-move-from-spam-group t - nnimap-split-rule 'nnimap-split-fancy - ;; @r{understand what this does before you copy it to your own setup!} - nnimap-split-fancy '(| - ;; @r{trace references to parents and put in their group} - (: gnus-registry-split-fancy-with-parent) - ;; @r{this will catch server-side SpamAssassin tags} - (: spam-split 'spam-use-regex-headers) - (any "ding" "ding") - ;; @r{note that spam by default will go to @samp{spam}} - (: spam-split) - ;; @r{default mailbox} - "mail")) - -;; @r{my parameters, set with @kbd{G p}} - -;; @r{all nnml groups, and all nnimap groups except} -;; @r{@samp{nnimap+mail.lifelogs.com:train} and} -;; @r{@samp{nnimap+mail.lifelogs.com:spam}: any spam goes to nnimap training,} -;; @r{because it must have been detected manually} - -((spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{all @acronym{NNTP} groups} -;; @r{autodetect spam with the blacklist and ham with the BBDB} -((spam-autodetect-methods spam-use-blacklist spam-use-BBDB) -;; @r{send all spam to the training group} - (spam-process-destination . "nnimap+mail.lifelogs.com:train")) - -;; @r{only some @acronym{NNTP} groups, where I want to autodetect spam} -((spam-autodetect . t)) - -;; @r{my nnimap @samp{nnimap+mail.lifelogs.com:spam} group} - -;; @r{this is a spam group} -((spam-contents gnus-group-spam-classification-spam) - - ;; @r{any spam (which happens when I enter for all unseen messages,} - ;; @r{because of the @code{gnus-spam-newsgroup-contents} setting above), goes to} - ;; @r{@samp{nnimap+mail.lifelogs.com:train} unless I mark it as ham} - - (spam-process-destination "nnimap+mail.lifelogs.com:train") - - ;; @r{any ham goes to my @samp{nnimap+mail.lifelogs.com:mail} folder, but} - ;; @r{also to my @samp{nnimap+mail.lifelogs.com:trainham} folder for training} - - (ham-process-destination "nnimap+mail.lifelogs.com:mail" - "nnimap+mail.lifelogs.com:trainham") - ;; @r{in this group, only @samp{!} marks are ham} - (ham-marks - (gnus-ticked-mark)) - ;; @r{remembers senders in the blacklist on the way out---this is} - ;; @r{definitely not needed, it just makes me feel better} - (spam-process (gnus-group-spam-exit-processor-blacklist))) - -;; @r{Later, on the @acronym{IMAP} server I use the @samp{train} group for training} -;; @r{SpamAssassin to recognize spam, and the @samp{trainham} group fora} -;; @r{recognizing ham---but Gnus has nothing to do with it.} - -@end example - -@subsubheading Using @code{spam.el} on an IMAP server with a statistical filter on the server -From Reiner Steib . - -My provider has set up bogofilter (in combination with @acronym{DCC}) on -the mail server (@acronym{IMAP}). Recognized spam goes to -@samp{spam.detected}, the rest goes through the normal filter rules, -i.e. to @samp{some.folder} or to @samp{INBOX}. Training on false -positives or negatives is done by copying or moving the article to -@samp{training.ham} or @samp{training.spam} respectively. A cron job on -the server feeds those to bogofilter with the suitable ham or spam -options and deletes them from the @samp{training.ham} and -@samp{training.spam} folders. - -With the following entries in @code{gnus-parameters}, @code{spam.el} -does most of the job for me: - -@lisp - ("nnimap:spam\\.detected" - (gnus-article-sort-functions '(gnus-article-sort-by-chars)) - (ham-process-destination "nnimap:INBOX" "nnimap:training.ham") - (spam-contents gnus-group-spam-classification-spam)) - ("nnimap:\\(INBOX\\|other-folders\\)" - (spam-process-destination . "nnimap:training.spam") - (spam-contents gnus-group-spam-classification-ham)) -@end lisp - -@itemize - -@item @b{The Spam folder:} - -In the folder @samp{spam.detected}, I have to check for false positives -(i.e. legitimate mails, that were wrongly judged as spam by -bogofilter or DCC). - -Because of the @code{gnus-group-spam-classification-spam} entry, all -messages are marked as spam (with @code{$}). When I find a false -positive, I mark the message with some other ham mark -(@code{ham-marks}, @ref{Spam and Ham Processors}). On group exit, -those messages are copied to both groups, @samp{INBOX} (where I want -to have the article) and @samp{training.ham} (for training bogofilter) -and deleted from the @samp{spam.detected} folder. - -The @code{gnus-article-sort-by-chars} entry simplifies detection of -false positives for me. I receive lots of worms (sweN, @dots{}), that all -have a similar size. Grouping them by size (i.e. chars) makes finding -other false positives easier. (Of course worms aren't @i{spam} -(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is -an excellent tool for filtering those unwanted mails for me.) - -@item @b{Ham folders:} - -In my ham folders, I just hit @kbd{S x} -(@code{gnus-summary-mark-as-spam}) whenever I see an unrecognized spam -mail (false negative). On group exit, those messages are moved to -@samp{training.spam}. -@end itemize - -@subsubheading Reporting spam articles in Gmane groups with @code{spam-report.el} - -From Reiner Steib . - -With following entry in @code{gnus-parameters}, @kbd{S x} -(@code{gnus-summary-mark-as-spam}) marks articles in @code{gmane.*} -groups as spam and reports the to Gmane at group exit: - -@lisp - ("^gmane\\." - (spam-process (gnus-group-spam-exit-processor-report-gmane))) -@end lisp - -Additionally, I use @code{(setq spam-report-gmane-use-article-number nil)} -because I don't read the groups directly from news.gmane.org, but -through my local news server (leafnode). I.e. the article numbers are -not the same as on news.gmane.org, thus @code{spam-report.el} has to check -the @code{X-Report-Spam} header to find the correct number. - -@node Spam Back Ends -@subsection Spam Back Ends -@cindex spam back ends - -The spam package offers a variety of back ends for detecting spam. -Each back end defines a set of methods for detecting spam -(@pxref{Filtering Incoming Mail}, @pxref{Detecting Spam in Groups}), -and a pair of spam and ham processors (@pxref{Spam and Ham -Processors}). - -@menu -* Blacklists and Whitelists:: -* BBDB Whitelists:: -* Gmane Spam Reporting:: -* Anti-spam Hashcash Payments:: -* Blackholes:: -* Regular Expressions Header Matching:: -* Bogofilter:: -* SpamAssassin back end:: -* ifile spam filtering:: -* Spam Statistics Filtering:: -* SpamOracle:: -@end menu - -@node Blacklists and Whitelists -@subsubsection Blacklists and Whitelists -@cindex spam filtering -@cindex whitelists, spam filtering -@cindex blacklists, spam filtering -@cindex spam - -@defvar spam-use-blacklist - -Set this variable to @code{t} if you want to use blacklists when -splitting incoming mail. Messages whose senders are in the blacklist -will be sent to the @code{spam-split-group}. This is an explicit -filter, meaning that it acts only on mail senders @emph{declared} to -be spammers. - -@end defvar - -@defvar spam-use-whitelist - -Set this variable to @code{t} if you want to use whitelists when -splitting incoming mail. Messages whose senders are not in the -whitelist will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the whitelist, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-whitelist-exclusive - -Set this variable to @code{t} if you want to use whitelists as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the whitelist. Use with care. - -@end defvar - -@defvar gnus-group-spam-exit-processor-blacklist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -spam-marked articles will be added to the blacklist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-blacklist}, it is recommended -that you use @code{(spam spam-use-blacklist)}. Everything will work -the same way, we promise. - -@end defvar - -@defvar gnus-group-ham-exit-processor-whitelist - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -whitelist. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-whitelist}, it is recommended -that you use @code{(ham spam-use-whitelist)}. Everything will work -the same way, we promise. - -@end defvar - -Blacklists are lists of regular expressions matching addresses you -consider to be spam senders. For instance, to block mail from any -sender at @samp{vmadmin.com}, you can put @samp{vmadmin.com} in your -blacklist. You start out with an empty blacklist. Blacklist entries -use the Emacs regular expression syntax. - -Conversely, whitelists tell Gnus what addresses are considered -legitimate. All messages from whitelisted addresses are considered -non-spam. Also see @ref{BBDB Whitelists}. Whitelist entries use the -Emacs regular expression syntax. - -The blacklist and whitelist file locations can be customized with the -@code{spam-directory} variable (@file{~/News/spam} by default), or -the @code{spam-whitelist} and @code{spam-blacklist} variables -directly. The whitelist and blacklist files will by default be in the -@code{spam-directory} directory, named @file{whitelist} and -@file{blacklist} respectively. - -@node BBDB Whitelists -@subsubsection BBDB Whitelists -@cindex spam filtering -@cindex BBDB whitelists, spam filtering -@cindex BBDB, spam filtering -@cindex spam - -@defvar spam-use-BBDB - -Analogous to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses the BBDB as the source of whitelisted -addresses, without regular expressions. You must have the BBDB loaded -for @code{spam-use-BBDB} to work properly. Messages whose senders are -not in the BBDB will be sent to the next spam-split rule. This is an -explicit filter, meaning that unless someone is in the BBDB, their -messages are not assumed to be spam or ham. - -@end defvar - -@defvar spam-use-BBDB-exclusive - -Set this variable to @code{t} if you want to use the BBDB as an -implicit filter, meaning that every message will be considered spam -unless the sender is in the BBDB. Use with care. Only sender -addresses in the BBDB will be allowed through; all others will be -classified as spammers. - -While @code{spam-use-BBDB-exclusive} @emph{can} be used as an alias -for @code{spam-use-BBDB} as far as @code{spam.el} is concerned, it is -@emph{not} a separate back end. If you set -@code{spam-use-BBDB-exclusive} to t, @emph{all} your BBDB splitting -will be exclusive. - -@end defvar - -@defvar gnus-group-ham-exit-processor-BBDB - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the senders of -ham-marked articles in @emph{ham} groups will be added to the -BBDB. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-BBDB}, it is recommended -that you use @code{(ham spam-use-BBDB)}. Everything will work -the same way, we promise. - -@end defvar - -@node Gmane Spam Reporting -@subsubsection Gmane Spam Reporting -@cindex spam reporting -@cindex Gmane, spam reporting -@cindex Gmane, spam reporting -@cindex spam - -@defvar gnus-group-spam-exit-processor-report-gmane - -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles groups will be reported to the Gmane administrators via a -HTTP request. - -Gmane can be found at @uref{http://gmane.org}. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-report-gmane}, it is recommended -that you use @code{(spam spam-use-gmane)}. Everything will work the -same way, we promise. - -@end defvar - -@defvar spam-report-gmane-use-article-number - -This variable is @code{t} by default. Set it to @code{nil} if you are -running your own news server, for instance, and the local article -numbers don't correspond to the Gmane article numbers. When -@code{spam-report-gmane-use-article-number} is @code{nil}, -@code{spam-report.el} will fetch the number from the article headers. - -@end defvar - -@defvar spam-report-user-mail-address - -Mail address exposed in the User-Agent spam reports to Gmane. It allows -the Gmane administrators to contact you in case of misreports. The -default is @code{user-mail-address}. - -@end defvar - -@node Anti-spam Hashcash Payments -@subsubsection Anti-spam Hashcash Payments -@cindex spam filtering -@cindex hashcash, spam filtering -@cindex spam - -@defvar spam-use-hashcash - -Similar to @code{spam-use-whitelist} (@pxref{Blacklists and -Whitelists}), but uses hashcash tokens for whitelisting messages -instead of the sender address. Messages without a hashcash payment -token will be sent to the next spam-split rule. This is an explicit -filter, meaning that unless a hashcash token is found, the messages -are not assumed to be spam or ham. - -@end defvar - -@node Blackholes -@subsubsection Blackholes -@cindex spam filtering -@cindex blackholes, spam filtering -@cindex spam - -@defvar spam-use-blackholes - -This option is disabled by default. You can let Gnus consult the -blackhole-type distributed spam processing systems (DCC, for instance) -when you set this option. The variable @code{spam-blackhole-servers} -holds the list of blackhole servers Gnus will consult. The current -list is fairly comprehensive, but make sure to let us know if it -contains outdated servers. - -The blackhole check uses the @code{dig.el} package, but you can tell -@code{spam.el} to use @code{dns.el} instead for better performance if -you set @code{spam-use-dig} to @code{nil}. It is not recommended at -this time to set @code{spam-use-dig} to @code{nil} despite the -possible performance improvements, because some users may be unable to -use it, but you can try it and see if it works for you. - -@end defvar - -@defvar spam-blackhole-servers - -The list of servers to consult for blackhole checks. - -@end defvar - -@defvar spam-blackhole-good-server-regex - -A regular expression for IPs that should not be checked against the -blackhole server list. When set to @code{nil}, it has no effect. - -@end defvar - -@defvar spam-use-dig - -Use the @code{dig.el} package instead of the @code{dns.el} package. -The default setting of @code{t} is recommended. - -@end defvar - -Blackhole checks are done only on incoming mail. There is no spam or -ham processor for blackholes. - -@node Regular Expressions Header Matching -@subsubsection Regular Expressions Header Matching -@cindex spam filtering -@cindex regular expressions header matching, spam filtering -@cindex spam - -@defvar spam-use-regex-headers - -This option is disabled by default. You can let Gnus check the -message headers against lists of regular expressions when you set this -option. The variables @code{spam-regex-headers-spam} and -@code{spam-regex-headers-ham} hold the list of regular expressions. -Gnus will check against the message headers to determine if the -message is spam or ham, respectively. - -@end defvar - -@defvar spam-regex-headers-spam - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as spam. - -@end defvar - -@defvar spam-regex-headers-ham - -The list of regular expressions that, when matched in the headers of -the message, positively identify it as ham. - -@end defvar - -Regular expression header checks are done only on incoming mail. -There is no specific spam or ham processor for regular expressions. - -@node Bogofilter -@subsubsection Bogofilter -@cindex spam filtering -@cindex bogofilter, spam filtering -@cindex spam - -@defvar spam-use-bogofilter - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter. - -With a minimum of care for associating the @samp{$} mark for spam -articles only, Bogofilter training all gets fairly automatic. You -should do this until you get a few hundreds of articles in each -category, spam or not. The command @kbd{S t} in summary mode, either -for debugging or for curiosity, shows the @emph{spamicity} score of -the current article (between 0.0 and 1.0). - -Bogofilter determines if a message is spam based on a specific -threshold. That threshold can be customized, consult the Bogofilter -documentation. - -If the @code{bogofilter} executable is not in your path, Bogofilter -processing will be turned off. - -You should not enable this if you use @code{spam-use-bogofilter-headers}. - -@end defvar - -@table @kbd -@item M s t -@itemx S t -@kindex M s t -@kindex S t -@findex spam-bogofilter-score -Get the Bogofilter spamicity score (@code{spam-bogofilter-score}). -@end table - -@defvar spam-use-bogofilter-headers - -Set this variable if you want @code{spam-split} to use Eric Raymond's -speedy Bogofilter, looking only at the message headers. It works -similarly to @code{spam-use-bogofilter}, but the @code{X-Bogosity} header -must be in the message already. Normally you would do this with a -procmail recipe or something similar; consult the Bogofilter -installation documents for details. - -You should not enable this if you use @code{spam-use-bogofilter}. - -@end defvar - -@defvar gnus-group-spam-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, spam-marked articles -will be added to the Bogofilter spam database. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-bogofilter}, it is recommended -that you use @code{(spam spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-bogofilter -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the Bogofilter database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-bogofilter}, it is recommended -that you use @code{(ham spam-use-bogofilter)}. Everything will work -the same way, we promise. -@end defvar - -@defvar spam-bogofilter-database-directory - -This is the directory where Bogofilter will store its databases. It -is not specified by default, so Bogofilter will use its own default -database directory. - -@end defvar - -The Bogofilter mail classifier is similar to @command{ifile} in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-bogofilter} and @code{spam-use-bogofilter-headers} -variables to indicate to spam-split that Bogofilter should either be -used, or has already been used on the article. The 0.9.2.1 version of -Bogofilter was used to test this functionality. - -@node SpamAssassin back end -@subsubsection SpamAssassin back end -@cindex spam filtering -@cindex spamassassin, spam filtering -@cindex spam - -@defvar spam-use-spamassassin - -Set this variable if you want @code{spam-split} to use SpamAssassin. - -SpamAssassin assigns a score to each article based on a set of rules -and tests, including a Bayesian filter. The Bayesian filter can be -trained by associating the @samp{$} mark for spam articles. The -spam score can be viewed by using the command @kbd{S t} in summary -mode. - -If you set this variable, each article will be processed by -SpamAssassin when @code{spam-split} is called. If your mail is -preprocessed by SpamAssassin, and you want to just use the -SpamAssassin headers, set @code{spam-use-spamassassin-headers} -instead. - -You should not enable this if you use -@code{spam-use-spamassassin-headers}. - -@end defvar - -@defvar spam-use-spamassassin-headers - -Set this variable if your mail is preprocessed by SpamAssassin and -want @code{spam-split} to split based on the SpamAssassin headers. - -You should not enable this if you use @code{spam-use-spamassassin}. - -@end defvar - -@defvar spam-spamassassin-program - -This variable points to the SpamAssassin executable. If you have -@code{spamd} running, you can set this variable to the @code{spamc} -executable for faster processing. See the SpamAssassin documentation -for more information on @code{spamd}/@code{spamc}. - -@end defvar - -SpamAssassin is a powerful and flexible spam filter that uses a wide -variety of tests to identify spam. A ham and a spam processors are -provided, plus the @code{spam-use-spamassassin} and -@code{spam-use-spamassassin-headers} variables to indicate to -spam-split that SpamAssassin should be either used, or has already -been used on the article. The 2.63 version of SpamAssassin was used -to test this functionality. - -@node ifile spam filtering -@subsubsection ifile spam filtering -@cindex spam filtering -@cindex ifile, spam filtering -@cindex spam - -@defvar spam-use-ifile - -Enable this variable if you want @code{spam-split} to use @command{ifile}, a -statistical analyzer similar to Bogofilter. - -@end defvar - -@defvar spam-ifile-all-categories - -Enable this variable if you want @code{spam-use-ifile} to give you all -the ifile categories, not just spam/non-spam. If you use this, make -sure you train ifile as described in its documentation. - -@end defvar - -@defvar spam-ifile-spam-category - -This is the category of spam messages as far as ifile is concerned. -The actual string used is irrelevant, but you probably want to leave -the default value of @samp{spam}. -@end defvar - -@defvar spam-ifile-database - -This is the filename for the ifile database. It is not specified by -default, so ifile will use its own default database name. - -@end defvar - -The ifile mail classifier is similar to Bogofilter in intent and -purpose. A ham and a spam processor are provided, plus the -@code{spam-use-ifile} variable to indicate to spam-split that ifile -should be used. The 1.2.1 version of ifile was used to test this -functionality. - -@node Spam Statistics Filtering -@subsubsection Spam Statistics Filtering -@cindex spam filtering -@cindex spam-stat, spam filtering -@cindex spam-stat -@cindex spam - -This back end uses the Spam Statistics Emacs Lisp package to perform -statistics-based filtering (@pxref{Spam Statistics Package}). Before -using this, you may want to perform some additional steps to -initialize your Spam Statistics dictionary. @xref{Creating a -spam-stat dictionary}. - -@defvar spam-use-stat - -@end defvar - -@defvar gnus-group-spam-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the spam-marked -articles will be added to the spam-stat database of spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-stat}, it is recommended -that you use @code{(spam spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-stat -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameters or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is -added to a group's @code{spam-process} parameter, the ham-marked -articles in @emph{ham} groups will be added to the spam-stat database -of non-spam messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-stat}, it is recommended -that you use @code{(ham spam-use-stat)}. Everything will work -the same way, we promise. -@end defvar - -This enables @code{spam.el} to cooperate with @file{spam-stat.el}. -@file{spam-stat.el} provides an internal (Lisp-only) spam database, -which unlike ifile or Bogofilter does not require external programs. -A spam and a ham processor, and the @code{spam-use-stat} variable for -@code{spam-split} are provided. - -@node SpamOracle -@subsubsection Using SpamOracle with Gnus -@cindex spam filtering -@cindex SpamOracle -@cindex spam - -An easy way to filter out spam is to use SpamOracle. SpamOracle is an -statistical mail filtering tool written by Xavier Leroy and needs to be -installed separately. - -There are several ways to use SpamOracle with Gnus. In all cases, your -mail is piped through SpamOracle in its @emph{mark} mode. SpamOracle will -then enter an @samp{X-Spam} header indicating whether it regards the -mail as a spam mail or not. - -One possibility is to run SpamOracle as a @code{:prescript} from the -@xref{Mail Source Specifiers}, (@pxref{SpamAssassin}). This method has -the advantage that the user can see the @emph{X-Spam} headers. - -The easiest method is to make @file{spam.el} (@pxref{Spam Package}) -call SpamOracle. - -@vindex spam-use-spamoracle -To enable SpamOracle usage by @code{spam.el}, set the variable -@code{spam-use-spamoracle} to @code{t} and configure the -@code{nnmail-split-fancy} or @code{nnimap-split-fancy}. @xref{Spam -Package}. In this example the @samp{INBOX} of an nnimap server is -filtered using SpamOracle. Mails recognized as spam mails will be -moved to @code{spam-split-group}, @samp{Junk} in this case. Ham -messages stay in @samp{INBOX}: - -@example -(setq spam-use-spamoracle t - spam-split-group "Junk" - nnimap-split-inbox '("INBOX") - nnimap-split-rule 'nnimap-split-fancy - nnimap-split-fancy '(| (: spam-split) "INBOX")) -@end example - -@defvar spam-use-spamoracle -Set to @code{t} if you want Gnus to enable spam filtering using -SpamOracle. -@end defvar - -@defvar spam-spamoracle-binary -Gnus uses the SpamOracle binary called @file{spamoracle} found in the -user's PATH. Using the variable @code{spam-spamoracle-binary}, this -can be customized. -@end defvar - -@defvar spam-spamoracle-database -By default, SpamOracle uses the file @file{~/.spamoracle.db} as a database to -store its analysis. This is controlled by the variable -@code{spam-spamoracle-database} which defaults to @code{nil}. That means -the default SpamOracle database will be used. In case you want your -database to live somewhere special, set -@code{spam-spamoracle-database} to this path. -@end defvar - -SpamOracle employs a statistical algorithm to determine whether a -message is spam or ham. In order to get good results, meaning few -false hits or misses, SpamOracle needs training. SpamOracle learns -the characteristics of your spam mails. Using the @emph{add} mode -(training mode) one has to feed good (ham) and spam mails to -SpamOracle. This can be done by pressing @kbd{|} in the Summary -buffer and pipe the mail to a SpamOracle process or using -@file{spam.el}'s spam- and ham-processors, which is much more -convenient. For a detailed description of spam- and ham-processors, -@xref{Spam Package}. - -@defvar gnus-group-spam-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, spam-marked articles will be -sent to SpamOracle as spam samples. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-spam-exit-processor-spamoracle}, it is recommended -that you use @code{(spam spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@defvar gnus-group-ham-exit-processor-spamoracle -Add this symbol to a group's @code{spam-process} parameter by -customizing the group parameter or the -@code{gnus-spam-process-newsgroups} variable. When this symbol is added -to a group's @code{spam-process} parameter, the ham-marked articles in -@emph{ham} groups will be sent to the SpamOracle as samples of ham -messages. - -@emph{WARNING} - -Instead of the obsolete -@code{gnus-group-ham-exit-processor-spamoracle}, it is recommended -that you use @code{(ham spam-use-spamoracle)}. Everything will work -the same way, we promise. -@end defvar - -@emph{Example:} These are the Group Parameters of a group that has been -classified as a ham group, meaning that it should only contain ham -messages. -@example - ((spam-contents gnus-group-spam-classification-ham) - (spam-process ((ham spam-use-spamoracle) - (spam spam-use-spamoracle)))) -@end example -For this group the @code{spam-use-spamoracle} is installed for both -ham and spam processing. If the group contains spam message -(e.g. because SpamOracle has not had enough sample messages yet) and -the user marks some messages as spam messages, these messages will be -processed by SpamOracle. The processor sends the messages to -SpamOracle as new samples for spam. - -@node Extending the Spam package -@subsection Extending the Spam package -@cindex spam filtering -@cindex spam elisp package, extending -@cindex extending the spam elisp package - -Say you want to add a new back end called blackbox. For filtering -incoming mail, provide the following: - -@enumerate - -@item -Code - -@lisp -(defvar spam-use-blackbox nil - "True if blackbox should be used.") -@end lisp - -Write @code{spam-check-blackbox} if Blackbox can check incoming mail. - -Write @code{spam-blackbox-register-routine} and -@code{spam-blackbox-unregister-routine} using the bogofilter -register/unregister routines as a start, or other restister/unregister -routines more appropriate to Blackbox, if Blackbox can -register/unregister spam and ham. - -@item -Functionality - -The @code{spam-check-blackbox} function should return @samp{nil} or -@code{spam-split-group}, observing the other conventions. See the -existing @code{spam-check-*} functions for examples of what you can -do, and stick to the template unless you fully understand the reasons -why you aren't. - -@end enumerate - -For processing spam and ham messages, provide the following: - -@enumerate - -@item -Code - -Note you don't have to provide a spam or a ham processor. Only -provide them if Blackbox supports spam or ham processing. - -Also, ham and spam processors are being phased out as single -variables. Instead the form @code{(spam spam-use-blackbox)} or -@code{(ham spam-use-blackbox)} is favored. For now, spam/ham -processor variables are still around but they won't be for long. - -@lisp -(defvar gnus-group-spam-exit-processor-blackbox "blackbox-spam" - "The Blackbox summary exit spam processor. -Only applicable to spam groups.") - -(defvar gnus-group-ham-exit-processor-blackbox "blackbox-ham" - "The whitelist summary exit ham processor. -Only applicable to non-spam (unclassified and ham) groups.") - -@end lisp - -@item -Gnus parameters - -Add -@lisp -(const :tag "Spam: Blackbox" (spam spam-use-blackbox)) -(const :tag "Ham: Blackbox" (ham spam-use-blackbox)) -@end lisp -to the @code{spam-process} group parameter in @code{gnus.el}. Make -sure you do it twice, once for the parameter and once for the -variable customization. - -Add -@lisp -(variable-item spam-use-blackbox) -@end lisp -to the @code{spam-autodetect-methods} group parameter in -@code{gnus.el} if Blackbox can check incoming mail for spam contents. - -Finally, use the appropriate @code{spam-install-*-backend} function in -@code{spam.el}. Here are the available functions. - - -@enumerate - -@item -@code{spam-install-backend-alias} - -This function will simply install an alias for a back end that does -everything like the original back end. It is currently only used to -make @code{spam-use-BBDB-exclusive} act like @code{spam-use-BBDB}. - -@item -@code{spam-install-nocheck-backend} - -This function installs a back end that has no check function, but can -register/unregister ham or spam. The @code{spam-use-gmane} back end is -such a back end. - -@item -@code{spam-install-checkonly-backend} - -This function will install a back end that can only check incoming mail -for spam contents. It can't register or unregister messages. -@code{spam-use-blackholes} and @code{spam-use-hashcash} are such -back ends. - -@item -@code{spam-install-statistical-checkonly-backend} - -This function installs a statistical back end (one which requires the -full body of a message to check it) that can only check incoming mail -for contents. @code{spam-use-regex-body} is such a filter. - -@item -@code{spam-install-statistical-backend} - -This function install a statistical back end with incoming checks and -registration/unregistration routines. @code{spam-use-bogofilter} is -set up this way. - -@item -@code{spam-install-backend} - -This is the most normal back end installation, where a back end that can -check and register/unregister messages is set up without statistical -abilities. The @code{spam-use-BBDB} is such a back end. - -@item -@code{spam-install-mover-backend} - -Mover back ends are internal to @code{spam.el} and specifically move -articles around when the summary is exited. You will very probably -never install such a back end. -@end enumerate - -@end enumerate - -@node Spam Statistics Package -@subsection Spam Statistics Package -@cindex Paul Graham -@cindex Graham, Paul -@cindex naive Bayesian spam filtering -@cindex Bayesian spam filtering, naive -@cindex spam filtering, naive Bayesian - -Paul Graham has written an excellent essay about spam filtering using -statistics: @uref{http://www.paulgraham.com/spam.html,A Plan for -Spam}. In it he describes the inherent deficiency of rule-based -filtering as used by SpamAssassin, for example: Somebody has to write -the rules, and everybody else has to install these rules. You are -always late. It would be much better, he argues, to filter mail based -on whether it somehow resembles spam or non-spam. One way to measure -this is word distribution. He then goes on to describe a solution -that checks whether a new mail resembles any of your other spam mails -or not. - -The basic idea is this: Create a two collections of your mail, one -with spam, one with non-spam. Count how often each word appears in -either collection, weight this by the total number of mails in the -collections, and store this information in a dictionary. For every -word in a new mail, determine its probability to belong to a spam or a -non-spam mail. Use the 15 most conspicuous words, compute the total -probability of the mail being spam. If this probability is higher -than a certain threshold, the mail is considered to be spam. - -The Spam Statistics package adds support to Gnus for this kind of -filtering. It can be used as one of the back ends of the Spam package -(@pxref{Spam Package}), or by itself. - -Before using the Spam Statistics package, you need to set it up. -First, you need two collections of your mail, one with spam, one with -non-spam. Then you need to create a dictionary using these two -collections, and save it. And last but not least, you need to use -this dictionary in your fancy mail splitting rules. - -@menu -* Creating a spam-stat dictionary:: -* Splitting mail using spam-stat:: -* Low-level interface to the spam-stat dictionary:: -@end menu - -@node Creating a spam-stat dictionary -@subsubsection Creating a spam-stat dictionary - -Before you can begin to filter spam based on statistics, you must -create these statistics based on two mail collections, one with spam, -one with non-spam. These statistics are then stored in a dictionary -for later use. In order for these statistics to be meaningful, you -need several hundred emails in both collections. - -Gnus currently supports only the nnml back end for automated dictionary -creation. The nnml back end stores all mails in a directory, one file -per mail. Use the following: - -@defun spam-stat-process-spam-directory -Create spam statistics for every file in this directory. Every file -is treated as one spam mail. -@end defun - -@defun spam-stat-process-non-spam-directory -Create non-spam statistics for every file in this directory. Every -file is treated as one non-spam mail. -@end defun - -Usually you would call @code{spam-stat-process-spam-directory} on a -directory such as @file{~/Mail/mail/spam} (this usually corresponds to -the group @samp{nnml:mail.spam}), and you would call -@code{spam-stat-process-non-spam-directory} on a directory such as -@file{~/Mail/mail/misc} (this usually corresponds to the group -@samp{nnml:mail.misc}). - -When you are using @acronym{IMAP}, you won't have the mails available -locally, so that will not work. One solution is to use the Gnus Agent -to cache the articles. Then you can use directories such as -@file{"~/News/agent/nnimap/mail.yourisp.com/personal_spam"} for -@code{spam-stat-process-spam-directory}. @xref{Agent as Cache}. - -@defvar spam-stat -This variable holds the hash-table with all the statistics---the -dictionary we have been talking about. For every word in either -collection, this hash-table stores a vector describing how often the -word appeared in spam and often it appeared in non-spam mails. -@end defvar - -If you want to regenerate the statistics from scratch, you need to -reset the dictionary. - -@defun spam-stat-reset -Reset the @code{spam-stat} hash-table, deleting all the statistics. -@end defun - -When you are done, you must save the dictionary. The dictionary may -be rather large. If you will not update the dictionary incrementally -(instead, you will recreate it once a month, for example), then you -can reduce the size of the dictionary by deleting all words that did -not appear often enough or that do not clearly belong to only spam or -only non-spam mails. - -@defun spam-stat-reduce-size -Reduce the size of the dictionary. Use this only if you do not want -to update the dictionary incrementally. -@end defun - -@defun spam-stat-save -Save the dictionary. -@end defun - -@defvar spam-stat-file -The filename used to store the dictionary. This defaults to -@file{~/.spam-stat.el}. -@end defvar - -@node Splitting mail using spam-stat -@subsubsection Splitting mail using spam-stat - -This section describes how to use the Spam statistics -@emph{independently} of the @xref{Spam Package}. - -First, add the following to your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -This will load the necessary Gnus code, and the dictionary you -created. - -Next, you need to adapt your fancy splitting rules: You need to -determine how to use @code{spam-stat}. The following examples are for -the nnml back end. Using the nnimap back end works just as well. Just -use @code{nnimap-split-fancy} instead of @code{nnmail-split-fancy}. - -In the simplest case, you only have two groups, @samp{mail.misc} and -@samp{mail.spam}. The following expression says that mail is either -spam or it should go into @samp{mail.misc}. If it is spam, then -@code{spam-stat-split-fancy} will return @samp{mail.spam}. - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -@defvar spam-stat-split-fancy-spam-group -The group to use for spam. Default is @samp{mail.spam}. -@end defvar - -If you also filter mail with specific subjects into other groups, use -the following expression. Only mails not matching the regular -expression are considered potential spam. - -@lisp -(setq nnmail-split-fancy - `(| ("Subject" "\\bspam-stat\\b" "mail.emacs") - (: spam-stat-split-fancy) - "mail.misc")) -@end lisp - -If you want to filter for spam first, then you must be careful when -creating the dictionary. Note that @code{spam-stat-split-fancy} must -consider both mails in @samp{mail.emacs} and in @samp{mail.misc} as -non-spam, therefore both should be in your collection of non-spam -mails, when creating the dictionary! - -@lisp -(setq nnmail-split-fancy - `(| (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - -You can combine this with traditional filtering. Here, we move all -HTML-only mails into the @samp{mail.spam.filtered} group. Note that since -@code{spam-stat-split-fancy} will never see them, the mails in -@samp{mail.spam.filtered} should be neither in your collection of spam mails, -nor in your collection of non-spam mails, when creating the -dictionary! - -@lisp -(setq nnmail-split-fancy - `(| ("Content-Type" "text/html" "mail.spam.filtered") - (: spam-stat-split-fancy) - ("Subject" "\\bspam-stat\\b" "mail.emacs") - "mail.misc")) -@end lisp - - -@node Low-level interface to the spam-stat dictionary -@subsubsection Low-level interface to the spam-stat dictionary - -The main interface to using @code{spam-stat}, are the following functions: - -@defun spam-stat-buffer-is-spam -Called in a buffer, that buffer is considered to be a new spam mail. -Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-is-no-spam -Called in a buffer, that buffer is considered to be a new non-spam -mail. Use this for new mail that has not been processed before. -@end defun - -@defun spam-stat-buffer-change-to-spam -Called in a buffer, that buffer is no longer considered to be normal -mail but spam. Use this to change the status of a mail that has -already been processed as non-spam. -@end defun - -@defun spam-stat-buffer-change-to-non-spam -Called in a buffer, that buffer is no longer considered to be spam but -normal mail. Use this to change the status of a mail that has already -been processed as spam. -@end defun - -@defun spam-stat-save -Save the hash table to the file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-load -Load the hash table from a file. The filename used is stored in the -variable @code{spam-stat-file}. -@end defun - -@defun spam-stat-score-word -Return the spam score for a word. -@end defun - -@defun spam-stat-score-buffer -Return the spam score for a buffer. -@end defun - -@defun spam-stat-split-fancy -Use this function for fancy mail splitting. Add the rule @samp{(: -spam-stat-split-fancy)} to @code{nnmail-split-fancy} -@end defun - -Make sure you load the dictionary before using it. This requires the -following in your @file{~/.gnus.el} file: - -@lisp -(require 'spam-stat) -(spam-stat-load) -@end lisp - -Typical test will involve calls to the following functions: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) -Number of words: (hash-table-count spam-stat) -Test spam: (spam-stat-test-directory "~/Mail/mail/spam") -Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") -@end smallexample - -Here is how you would create your dictionary: - -@smallexample -Reset: (setq spam-stat (make-hash-table :test 'equal)) -Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") -Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") -Repeat for any other non-spam group you need... -Reduce table size: (spam-stat-reduce-size) -Save table: (spam-stat-save) -@end smallexample - -@node The Gnus Registry -@section The Gnus Registry -@cindex registry -@cindex split -@cindex track - -The Gnus registry is a package that tracks messages by their -Message-ID across all backends. This allows Gnus users to do several -cool things, be the envy of the locals, get free haircuts, and be -experts on world issues. Well, maybe not all of those, but the -features are pretty cool. - -Although they will be explained in detail shortly, here's a quick list -of said features in case your attention span is... never mind. - -@enumerate -@item -Split messages to their parent - -This keeps discussions in the same group. You can use the subject and -the sender in addition to the Message-ID. Several strategies are -available. - -@item -Store custom flags and keywords - -The registry can store custom flags and keywords for a message. For -instance, you can mark a message ``To-Do'' this way and the flag will -persist whether the message is in the nnimap, nnml, nnmaildir, -etc. backends. - -@item -Store arbitrary data - -Through a simple ELisp API, the registry can remember any data for a -message. A built-in inverse map, when activated, allows quick lookups -of all messages matching a particular set of criteria. -@end enumerate - -@menu -* Setup:: -* Fancy splitting to parent:: -* Store custom flags and keywords:: -* Store arbitrary data:: -@end menu - -@node Setup -@subsection Setup - -Fortunately, setting up the Gnus registry is pretty easy: - -@lisp -(setq gnus-registry-max-entries 2500 - gnus-registry-use-long-group-names t) - -(gnus-registry-initialize) -@end lisp - -This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @code{*Group*} buffer. It also -adds registry calls to article actions in Gnus (copy, move, etc.) so -it's not easy to undo the initialization. See -@code{gnus-registry-initialize} for the gory details. - -Here are other settings used by the author of the registry (understand -what they do before you copy them blindly). - -@lisp -(setq - gnus-registry-split-strategy 'majority - gnus-registry-ignored-groups '(("nntp" t) - ("nnrss" t) - ("spam" t) - ("train" t)) - gnus-registry-max-entries 500000 - gnus-registry-use-long-group-names t - gnus-registry-track-extra '(sender subject)) -@end lisp - -They say: keep a lot of messages around, use long group names, track -messages by sender and subject (not just parent Message-ID), and when -the registry splits incoming mail, use a majority rule to decide where -messages should go if there's more than one possibility. In addition, -the registry should ignore messages in groups that match ``nntp'', -``nnrss'', ``spam'', or ``train.'' - -You are doubtless impressed by all this, but you ask: ``I am a Gnus -user, I customize to live. Give me more.'' Here you go, these are -the general settings. - -@defvar gnus-registry-unfollowed-groups -The groups that will not be followed by -@code{gnus-registry-split-fancy-with-parent}. They will still be -remembered by the registry. This is a list of regular expressions. -@end defvar - -@defvar gnus-registry-ignored-groups -The groups that will not be remembered by the registry. This is a -list of regular expressions, also available through Group/Topic -customization (so you can ignore or keep a specific group or a whole -topic). -@end defvar - -@defvar gnus-registry-use-long-group-names -Whether the registry will use long group names. It's recommended to -set this to @code{t}, although everything works if you don't. Future -functionality will require it. -@end defvar - -@defvar gnus-registry-max-entries -The number (an integer or @code{nil} for unlimited) of entries the -registry will keep. -@end defvar - -@defvar gnus-registry-cache-file -The file where the registry will be stored between Gnus sessions. -@end defvar - -@node Fancy splitting to parent -@subsection Fancy splitting to parent - -Simply put, this lets you put followup e-mail where it belongs. - -Every message has a Message-ID, which is unique, and the registry -remembers it. When the message is moved or copied, the registry will -notice this and offer the new group as a choice to the splitting -strategy. - -When a followup is made, usually it mentions the original message's -Message-ID in the headers. The registry knows this and uses that -mention to find the group where the original message lives. You only -have to put a rule like this: - -@lisp -(setq nnimap-my-split-fancy '(| - - ;; split to parent: you need this - (: gnus-registry-split-fancy-with-parent) - - ;; other rules, as an example - (: spam-split) - ;; default mailbox - "mail") -@end lisp - -in your fancy split setup. In addition, you may want to customize the -following variables. - -@defvar gnus-registry-track-extra -This is a list of symbols, so it's best to change it from the -Customize interface. By default it's @code{nil}, but you may want to -track @code{subject} and @code{sender} as well when splitting by parent. -It may work for you. It can be annoying if your mail flow is large and -people don't stick to the same groups. -@end defvar - -@defvar gnus-registry-split-strategy -This is a symbol, so it's best to change it from the Customize -interface. By default it's @code{nil}, but you may want to set it to -@code{majority} or @code{first} to split by sender or subject based on -the majority of matches or on the first found. -@end defvar - -@node Store custom flags and keywords -@subsection Store custom flags and keywords - -The registry lets you set custom flags and keywords per message. You -can use the Gnus->Registry Marks menu or the @kbd{M M x} keyboard -shortcuts, where @code{x} is the first letter of the mark's name. - -@defvar gnus-registry-marks -The custom marks that the registry can use. You can modify the -default list, if you like. If you do, you'll have to exit Emacs -before they take effect (you can also unload the registry and reload -it or evaluate the specific macros you'll need, but you probably don't -want to bother). Use the Customize interface to modify the list. - -By default this list has the @code{Important}, @code{Work}, -@code{Personal}, @code{To-Do}, and @code{Later} marks. They all have -keyboard shortcuts like @kbd{M M i} for Important, using the first -letter. -@end defvar - -@defun gnus-registry-mark-article -Call this function to mark an article with a custom registry mark. It -will offer the available marks for completion. -@end defun - -@node Store arbitrary data -@subsection Store arbitrary data - -The registry has a simple API that uses a Message-ID as the key to -store arbitrary data (as long as it can be converted to a list for -storage). - -@defun gnus-registry-store-extra-entry (id key value) -Store @code{value} in the extra data key @code{key} for message -@code{id}. -@end defun - -@defun gnus-registry-delete-extra-entry (id key) -Delete the extra data key @code{key} for message @code{id}. -@end defun - -@defun gnus-registry-fetch-extra (id key) -Get the extra data key @code{key} for message @code{id}. -@end defun - -@defvar gnus-registry-extra-entries-precious -If any extra entries are precious, their presence will make the -registry keep the whole entry forever, even if there are no groups for -the Message-ID and if the size limit of the registry is reached. By -default this is just @code{(marks)} so the custom registry marks are -precious. -@end defvar - -@node Other modes -@section Interaction with other modes - -@subsection Dired -@cindex dired - -@code{gnus-dired-minor-mode} provides some useful functions for dired -buffers. It is enabled with -@lisp -(add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode) -@end lisp - -@table @kbd -@item C-c C-m C-a -@findex gnus-dired-attach -@cindex attachments, selection via dired -Send dired's marked files as an attachment (@code{gnus-dired-attach}). -You will be prompted for a message buffer. - -@item C-c C-m C-l -@findex gnus-dired-find-file-mailcap -Visit a file according to the appropriate mailcap entry -(@code{gnus-dired-find-file-mailcap}). With prefix, open file in a new -buffer. - -@item C-c C-m C-p -@findex gnus-dired-print -Print file according to the mailcap entry (@code{gnus-dired-print}). If -there is no print command, print in a PostScript image. -@end table - -@node Various Various -@section Various Various -@cindex mode lines -@cindex highlights - -@table @code - -@item gnus-home-directory -@vindex gnus-home-directory -All Gnus file and directory variables will be initialized from this -variable, which defaults to @file{~/}. - -@item gnus-directory -@vindex gnus-directory -Most Gnus storage file and directory variables will be initialized from -this variable, which defaults to the @env{SAVEDIR} environment -variable, or @file{~/News/} if that variable isn't set. - -Note that Gnus is mostly loaded when the @file{~/.gnus.el} file is read. -This means that other directory variables that are initialized from this -variable won't be set properly if you set this variable in -@file{~/.gnus.el}. Set this variable in @file{.emacs} instead. - -@item gnus-default-directory -@vindex gnus-default-directory -Not related to the above variable at all---this variable says what the -default directory of all Gnus buffers should be. If you issue commands -like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's -default directory. If this variable is @code{nil} (which is the -default), the default directory will be the default directory of the -buffer you were in when you started Gnus. - -@item gnus-verbose -@vindex gnus-verbose -This variable is an integer between zero and ten. The higher the value, -the more messages will be displayed. If this variable is zero, Gnus -will never flash any messages, if it is seven (which is the default), -most important messages will be shown, and if it is ten, Gnus won't ever -shut up, but will flash so many messages it will make your head swim. - -@item gnus-verbose-backends -@vindex gnus-verbose-backends -This variable works the same way as @code{gnus-verbose}, but it applies -to the Gnus back ends instead of Gnus proper. - -@item gnus-add-timestamp-to-message -@vindex gnus-add-timestamp-to-message -This variable controls whether to add timestamps to messages that are -controlled by @code{gnus-verbose} and @code{gnus-verbose-backends} and -are issued. The default value is @code{nil} which means never to add -timestamp. If it is @code{log}, add timestamps to only the messages -that go into the @samp{*Messages*} buffer (in XEmacs, it is the -@w{@samp{ *Message-Log*}} buffer). If it is neither @code{nil} nor -@code{log}, add timestamps not only to log messages but also to the ones -displayed in the echo area. - -@item nnheader-max-head-length -@vindex nnheader-max-head-length -When the back ends read straight heads of articles, they all try to read -as little as possible. This variable (default 8192) specifies -the absolute max length the back ends will try to read before giving up -on finding a separator line between the head and the body. If this -variable is @code{nil}, there is no upper read bound. If it is -@code{t}, the back ends won't try to read the articles piece by piece, -but read the entire articles. This makes sense with some versions of -@code{ange-ftp} or @code{efs}. - -@item nnheader-head-chop-length -@vindex nnheader-head-chop-length -This variable (default 2048) says how big a piece of each article to -read when doing the operation described above. - -@item nnheader-file-name-translation-alist -@vindex nnheader-file-name-translation-alist -@cindex file names -@cindex invalid characters in file names -@cindex characters in file names -This is an alist that says how to translate characters in file names. -For instance, if @samp{:} is invalid as a file character in file names -on your system (you OS/2 user you), you could say something like: - -@lisp -@group -(setq nnheader-file-name-translation-alist - '((?: . ?_))) -@end group -@end lisp - -In fact, this is the default value for this variable on OS/2 and MS -Windows (phooey) systems. - -@item gnus-hidden-properties -@vindex gnus-hidden-properties -This is a list of properties to use to hide ``invisible'' text. It is -@code{(invisible t intangible t)} by default on most systems, which -makes invisible text invisible and intangible. - -@item gnus-parse-headers-hook -@vindex gnus-parse-headers-hook -A hook called before parsing headers. It can be used, for instance, to -gather statistics on the headers fetched, or perhaps you'd like to prune -some headers. I don't see why you'd want that, though. - -@item gnus-shell-command-separator -@vindex gnus-shell-command-separator -String used to separate two shell commands. The default is @samp{;}. - -@item gnus-invalid-group-regexp -@vindex gnus-invalid-group-regexp - -Regexp to match ``invalid'' group names when querying user for a group -name. The default value catches some @strong{really} invalid group -names who could possibly mess up Gnus internally (like allowing -@samp{:} in a group name, which is normally used to delimit method and -group). - -@acronym{IMAP} users might want to allow @samp{/} in group names though. - - -@end table - -@node The End -@chapter The End - -Well, that's the manual---you can get on with your life now. Keep in -touch. Say hello to your cats from me. - -My @strong{ghod}---I just can't stand goodbyes. Sniffle. - -Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: - -@quotation -@strong{Te Deum} - -@sp 1 -Not because of victories @* -I sing,@* -having none,@* -but for the common sunshine,@* -the breeze,@* -the largess of the spring. - -@sp 1 -Not for victory@* -but for the day's work done@* -as well as I was able;@* -not for a seat upon the dais@* -but at the common table.@* -@end quotation - - -@node Appendices -@chapter Appendices - -@menu -* XEmacs:: Requirements for installing under XEmacs. -* History:: How Gnus got where it is today. -* On Writing Manuals:: Why this is not a beginner's guide. -* Terminology:: We use really difficult, like, words here. -* Customization:: Tailoring Gnus to your needs. -* Troubleshooting:: What you might try if things do not work. -* Gnus Reference Guide:: Rilly, rilly technical stuff. -* Emacs for Heathens:: A short introduction to Emacsian terms. -* Frequently Asked Questions:: The Gnus FAQ -@end menu - - -@node XEmacs -@section XEmacs -@cindex XEmacs -@cindex installing under XEmacs - -XEmacs is distributed as a collection of packages. You should install -whatever packages the Gnus XEmacs package requires. The current -requirements are @samp{gnus}, @samp{mail-lib}, @samp{xemacs-base}, -@samp{eterm}, @samp{sh-script}, @samp{net-utils}, @samp{os-utils}, -@samp{dired}, @samp{mh-e}, @samp{sieve}, @samp{ps-print}, @samp{W3}, -@samp{pgg}, @samp{mailcrypt}, @samp{ecrypto}, and @samp{sasl}. - - -@node History -@section History - -@cindex history -@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in -'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. - -If you want to investigate the person responsible for this outrage, -you can point your (feh!) web browser to -@uref{http://quimby.gnus.org/}. This is also the primary -distribution point for the new and spiffy versions of Gnus, and is -known as The Site That Destroys Newsrcs And Drives People Mad. - -During the first extended alpha period of development, the new Gnus was -called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for -@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? -(Besides, the ``Gnus'' in this abbreviation should probably be -pronounced ``news'' as @sc{Umeda} intended, which makes it a more -appropriate name, don't you think?) - -In any case, after spending all that energy on coming up with a new and -spunky name, we decided that the name was @emph{too} spunky, so we -renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. -``@sc{gnus}''. New vs. old. - -@menu -* Gnus Versions:: What Gnus versions have been released. -* Other Gnus Versions:: Other Gnus versions that also have been released. -* Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? -* Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. -* Contributors:: Oodles of people. -* New Features:: Pointers to some of the new stuff in Gnus. -@end menu - - -@node Gnus Versions -@subsection Gnus Versions -@cindex ding Gnus -@cindex September Gnus -@cindex Red Gnus -@cindex Quassia Gnus -@cindex Pterodactyl Gnus -@cindex Oort Gnus -@cindex No Gnus -@cindex Gnus versions - -The first ``proper'' release of Gnus 5 was done in November 1995 when it -was included in the Emacs 19.30 distribution (132 (ding) Gnus releases -plus 15 Gnus 5.0 releases). - -In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 -releases)) was released under the name ``Gnus 5.2'' (40 releases). - -On July 28th 1996 work on Red Gnus was begun, and it was released on -January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). - -On September 13th 1997, Quassia Gnus was started and lasted 37 releases. -It was released as ``Gnus 5.6'' on March 8th 1998 (46 releases). - -Gnus 5.6 begat Pterodactyl Gnus on August 29th 1998 and was released as -``Gnus 5.8'' (after 99 releases and a CVS repository) on December 3rd -1999. - -On the 26th of October 2000, Oort Gnus was begun and was released as -Gnus 5.10 on May 1st 2003 (24 releases). - -On the January 4th 2004, No Gnus was begun. - -If you happen upon a version of Gnus that has a prefixed name -- -``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'', -``Pterodactyl Gnus'', ``Oort Gnus'', ``No Gnus'' -- don't panic. -Don't let it know that you're frightened. Back away. Slowly. Whatever -you do, don't run. Walk away, calmly, until you're out of its reach. -Find a proper released version of Gnus and snuggle up to that instead. - - -@node Other Gnus Versions -@subsection Other Gnus Versions -@cindex Semi-gnus - -In addition to the versions of Gnus which have had their releases -coordinated by Lars, one major development has been Semi-gnus from -Japan. It's based on a library called @acronym{SEMI}, which provides -@acronym{MIME} capabilities. - -These Gnusae are based mainly on Gnus 5.6 and Pterodactyl Gnus. -Collectively, they are called ``Semi-gnus'', and different strains are -called T-gnus, ET-gnus, Nana-gnus and Chaos. These provide powerful -@acronym{MIME} and multilingualization things, especially important for -Japanese users. - - -@node Why? -@subsection Why? - -What's the point of Gnus? - -I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' -newsreader, that lets you do anything you can think of. That was my -original motivation, but while working on Gnus, it has become clear to -me that this generation of newsreaders really belong in the stone age. -Newsreaders haven't developed much since the infancy of the net. If the -volume continues to rise with the current rate of increase, all current -newsreaders will be pretty much useless. How do you deal with -newsgroups that have thousands of new articles each day? How do you -keep track of millions of people who post? - -Gnus offers no real solutions to these questions, but I would very much -like to see Gnus being used as a testing ground for new methods of -reading and fetching news. Expanding on @sc{Umeda}-san's wise decision -to separate the newsreader from the back ends, Gnus now offers a simple -interface for anybody who wants to write new back ends for fetching mail -and news from different sources. I have added hooks for customizations -everywhere I could imagine it being useful. By doing so, I'm inviting -every one of you to explore and invent. - -May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and -@kbd{C-u 100 M-x all-hail-xemacs}. - - -@node Compatibility -@subsection Compatibility - -@cindex compatibility -Gnus was designed to be fully compatible with @sc{gnus}. Almost all key -bindings have been kept. More key bindings have been added, of course, -but only in one or two obscure cases have old bindings been changed. - -Our motto is: -@quotation -@cartouche -@center In a cloud bones of steel. -@end cartouche -@end quotation - -All commands have kept their names. Some internal functions have changed -their names. - -The @code{gnus-uu} package has changed drastically. @xref{Decoding -Articles}. - -One major compatibility question is the presence of several summary -buffers. All variables relevant while reading a group are -buffer-local to the summary buffer they belong in. Although many -important variables have their values copied into their global -counterparts whenever a command is executed in the summary buffer, this -change might lead to incorrect values being used unless you are careful. - -All code that relies on knowledge of @sc{gnus} internals will probably -fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or -changing it in any way, as a matter of fact) is strictly verboten. Gnus -maintains a hash table that points to the entries in this alist (which -speeds up many functions), and changing the alist directly will lead to -peculiar results. - -@cindex hilit19 -@cindex highlighting -Old hilit19 code does not work at all. In fact, you should probably -remove all hilit code from all Gnus hooks -(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). -Gnus provides various integrated functions for highlighting. These are -faster and more accurate. To make life easier for everybody, Gnus will -by default remove all hilit calls from all hilit hooks. Uncleanliness! -Away! - -Packages like @code{expire-kill} will no longer work. As a matter of -fact, you should probably remove all old @sc{gnus} packages (and other -code) when you start using Gnus. More likely than not, Gnus already -does what you have written code to make @sc{gnus} do. (Snicker.) - -Even though old methods of doing things are still supported, only the -new methods are documented in this manual. If you detect a new method of -doing something while reading this manual, that does not mean you have -to stop doing it the old way. - -Gnus understands all @sc{gnus} startup files. - -@kindex M-x gnus-bug -@findex gnus-bug -@cindex reporting bugs -@cindex bugs -Overall, a casual user who hasn't written much code that depends on -@sc{gnus} internals should suffer no problems. If problems occur, -please let me know by issuing that magic command @kbd{M-x gnus-bug}. - -@vindex gnus-bug-create-help-buffer -If you are in the habit of sending bug reports @emph{very} often, you -may find the helpful help buffer annoying after a while. If so, set -@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop -up at you. - - -@node Conformity -@subsection Conformity - -No rebels without a clue here, ma'am. We conform to all standards known -to (wo)man. Except for those standards and/or conventions we disagree -with, of course. - -@table @strong - -@item RFC (2)822 -@cindex RFC 822 -@cindex RFC 2822 -There are no known breaches of this standard. - -@item RFC 1036 -@cindex RFC 1036 -There are no known breaches of this standard, either. - -@item Son-of-RFC 1036 -@cindex Son-of-RFC 1036 -We do have some breaches to this one. - -@table @emph - -@item X-Newsreader -@itemx User-Agent -These are considered to be ``vanity headers'', while I consider them -to be consumer information. After seeing so many badly formatted -articles coming from @code{tin} and @code{Netscape} I know not to use -either of those for posting articles. I would not have known that if -it wasn't for the @code{X-Newsreader} header. -@end table - -@item USEFOR -@cindex USEFOR -USEFOR is an IETF working group writing a successor to RFC 1036, based -on Son-of-RFC 1036. They have produced a number of drafts proposing -various changes to the format of news articles. The Gnus towers will -look into implementing the changes when the draft is accepted as an RFC. - -@item MIME - RFC 2045-2049 etc -@cindex @acronym{MIME} -All the various @acronym{MIME} RFCs are supported. - -@item Disposition Notifications - RFC 2298 -Message Mode is able to request notifications from the receiver. - -@item PGP - RFC 1991 and RFC 2440 -@cindex RFC 1991 -@cindex RFC 2440 -RFC 1991 is the original @acronym{PGP} message specification, -published as an informational RFC. RFC 2440 was the follow-up, now -called Open PGP, and put on the Standards Track. Both document a -non-@acronym{MIME} aware @acronym{PGP} format. Gnus supports both -encoding (signing and encryption) and decoding (verification and -decryption). - -@item PGP/MIME - RFC 2015/3156 -RFC 2015 (superseded by 3156 which references RFC 2440 instead of RFC -1991) describes the @acronym{MIME}-wrapping around the RFC 1991/2440 format. -Gnus supports both encoding and decoding. - -@item S/MIME - RFC 2633 -RFC 2633 describes the @acronym{S/MIME} format. - -@item IMAP - RFC 1730/2060, RFC 2195, RFC 2086, RFC 2359, RFC 2595, RFC 1731 -RFC 1730 is @acronym{IMAP} version 4, updated somewhat by RFC 2060 -(@acronym{IMAP} 4 revision 1). RFC 2195 describes CRAM-MD5 -authentication for @acronym{IMAP}. RFC 2086 describes access control -lists (ACLs) for @acronym{IMAP}. RFC 2359 describes a @acronym{IMAP} -protocol enhancement. RFC 2595 describes the proper @acronym{TLS} -integration (STARTTLS) with @acronym{IMAP}. RFC 1731 describes the -GSSAPI/Kerberos4 mechanisms for @acronym{IMAP}. - -@end table - -If you ever notice Gnus acting non-compliant with regards to the texts -mentioned above, don't hesitate to drop a note to Gnus Towers and let us -know. - - -@node Emacsen -@subsection Emacsen -@cindex Emacsen -@cindex XEmacs -@cindex Mule -@cindex Emacs - -This version of Gnus should work on: - -@itemize @bullet - -@item -Emacs 21.1 and up. - -@item -XEmacs 21.4 and up. - -@end itemize - -This Gnus version will absolutely not work on any Emacsen older than -that. Not reliably, at least. Older versions of Gnus may work on older -Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs -20.7 and XEmacs 21.1. - -@c No-merge comment: The paragraph added in v5-10 here must not be -@c synced here! - -@node Gnus Development -@subsection Gnus Development - -Gnus is developed in a two-phased cycle. The first phase involves much -discussion on the development mailing list @samp{ding@@gnus.org}, where people -propose changes and new features, post patches and new back ends. This -phase is called the @dfn{alpha} phase, since the Gnusae released in this -phase are @dfn{alpha releases}, or (perhaps more commonly in other -circles) @dfn{snapshots}. During this phase, Gnus is assumed to be -unstable and should not be used by casual users. Gnus alpha releases -have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}. - -After futzing around for 10-100 alpha releases, Gnus is declared -@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, -and is called things like ``Gnus 5.10.1'' instead. Normal people are -supposed to be able to use these, and these are mostly discussed on the -@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the -mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane -as @samp{gmane.emacs.gnus.user}. These releases are finally integrated -in Emacs. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -The division of discussion between the ding mailing list and the Gnus -newsgroup is not purely based on publicity concerns. It's true that -having people write about the horrible things that an alpha Gnus release -can do (sometimes) in a public forum may scare people off, but more -importantly, talking about new experimental features that have been -introduced may confuse casual users. New features are frequently -introduced, fiddled with, and judged to be found wanting, and then -either discarded or totally rewritten. People reading the mailing list -usually keep up with these rapid changes, while people on the newsgroup -can't be assumed to do so. - -So if you have problems with or questions about the alpha versions, -direct those to the ding mailing list @samp{ding@@gnus.org}. This list -is also available on Gmane as @samp{gmane.emacs.gnus.general}. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -@node Contributors -@subsection Contributors -@cindex contributors - -The new Gnus version couldn't have been done without the help of all the -people on the (ding) mailing list. Every day for over a year I have -gotten billions of nice bug reports from them, filling me with joy, -every single one of them. Smooches. The people on the list have been -tried beyond endurance, what with my ``oh, that's a neat idea , yup, I'll release it right away no wait, that doesn't -work at all , yup, I'll ship that one off right away no, wait, that absolutely does not work'' policy for releases. -Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that -``worser''? ``much worser''? ``worsest''?) - -I would like to take this opportunity to thank the Academy for@dots{} oops, -wrong show. - -@itemize @bullet - -@item -Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. - -@item -Shenghuo Zhu---uudecode.el, mm-uu.el, rfc1843.el, webmail.el, -nnwarchive and many, many other things connected with @acronym{MIME} and -other types of en/decoding, as well as general bug fixing, new -functionality and stuff. - -@item -Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as -well as numerous other things). - -@item -Luis Fernandes---design and graphics. - -@item -Joe Reiss---creator of the smiley faces. - -@item -Justin Sheehy---the @acronym{FAQ} maintainer. - -@item -Erik Naggum---help, ideas, support, code and stuff. - -@item -Wes Hardaker---@file{gnus-picon.el} and the manual section on -@dfn{picons} (@pxref{Picons}). - -@item -Kim-Minh Kaplan---further work on the picon code. - -@item -Brad Miller---@file{gnus-gl.el} and the GroupLens manual section. - -@item -Sudish Joseph---innumerable bug fixes. - -@item -Ilja Weis---@file{gnus-topic.el}. - -@item -Steven L. Baur---lots and lots and lots of bugs detections and fixes. - -@item -Vladimir Alexiev---the refcard and reference booklets. - -@item -Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus -distribution by Felix Lee and JWZ. - -@item -Scott Byer---@file{nnfolder.el} enhancements & rewrite. - -@item -Peter Mutsaers---orphan article scoring code. - -@item -Ken Raeburn---POP mail support. - -@item -Hallvard B Furuseth---various bits and pieces, especially dealing with -.newsrc files. - -@item -Brian Edmonds---@file{gnus-bbdb.el}. - -@item -David Moore---rewrite of @file{nnvirtual.el} and many other things. - -@item -Kevin Davidson---came up with the name @dfn{ding}, so blame him. - -@item -Fran@,{c}ois Pinard---many, many interesting and thorough bug reports, as -well as autoconf support. - -@end itemize - -This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark -Borges, and Jost Krieger proof-reading parts of the manual. - -The following people have contributed many patches and suggestions: - -Christopher Davis, -Andrew Eskilsson, -Kai Grossjohann, -Kevin Greiner, -Jesper Harder, -Paul Jarc, -Simon Josefsson, -David K@aa{}gedal, -Richard Pieri, -Fabrice Popineau, -Daniel Quinlan, -Michael Shields, -Reiner Steib, -Jason L. Tibbitts, III, -Jack Vinson, -Katsumi Yamaoka, @c Yamaoka -and -Teodor Zlatanov. - -Also thanks to the following for patches and stuff: - -Jari Aalto, -Adrian Aichner, -Vladimir Alexiev, -Russ Allbery, -Peter Arius, -Matt Armstrong, -Marc Auslander, -Miles Bader, -Alexei V. Barantsev, -Frank Bennett, -Robert Bihlmeyer, -Chris Bone, -Mark Borges, -Mark Boyns, -Lance A. Brown, -Rob Browning, -Kees de Bruin, -Martin Buchholz, -Joe Buehler, -Kevin Buhr, -Alastair Burt, -Joao Cachopo, -Zlatko Calusic, -Massimo Campostrini, -Castor, -David Charlap, -Dan Christensen, -Kevin Christian, -Jae-you Chung, @c ? -James H. Cloos, Jr., -Laura Conrad, -Michael R. Cook, -Glenn Coombs, -Andrew J. Cosgriff, -Neil Crellin, -Frank D. Cringle, -Geoffrey T. Dairiki, -Andre Deparade, -Ulrik Dickow, -Dave Disser, -Rui-Tao Dong, @c ? -Joev Dubach, -Michael Welsh Duggan, -Dave Edmondson, -Paul Eggert, -Mark W. Eichin, -Karl Eichwalder, -Enami Tsugutomo, @c Enami -Michael Ernst, -Luc Van Eycken, -Sam Falkner, -Nelson Jose dos Santos Ferreira, -Sigbjorn Finne, -Sven Fischer, -Paul Fisher, -Decklin Foster, -Gary D. Foster, -Paul Franklin, -Guy Geens, -Arne Georg Gleditsch, -David S. Goldberg, -Michelangelo Grigni, -Dale Hagglund, -D. Hall, -Magnus Hammerin, -Kenichi Handa, @c Handa -Raja R. Harinath, -Yoshiki Hayashi, @c Hayashi -P. E. Jareth Hein, -Hisashige Kenji, @c Hisashige -Scott Hofmann, -Tassilo Horn, -Marc Horowitz, -Gunnar Horrigmo, -Richard Hoskins, -Brad Howes, -Miguel de Icaza, -Fran@,{c}ois Felix Ingrand, -Tatsuya Ichikawa, @c Ichikawa -Ishikawa Ichiro, @c Ishikawa -Lee Iverson, -Iwamuro Motonori, @c Iwamuro -Rajappa Iyer, -Andreas Jaeger, -Adam P. Jenkins, -Randell Jesup, -Fred Johansen, -Gareth Jones, -Greg Klanderman, -Karl Kleinpaste, -Michael Klingbeil, -Peter Skov Knudsen, -Shuhei Kobayashi, @c Kobayashi -Petr Konecny, -Koseki Yoshinori, @c Koseki -Thor Kristoffersen, -Jens Lautenbacher, -Martin Larose, -Seokchan Lee, @c Lee -Joerg Lenneis, -Carsten Leonhardt, -James LewisMoss, -Christian Limpach, -Markus Linnala, -Dave Love, -Mike McEwan, -Tonny Madsen, -Shlomo Mahlab, -Nat Makarevitch, -Istvan Marko, -David Martin, -Jason R. Mastaler, -Gordon Matzigkeit, -Timo Metzemakers, -Richard Mlynarik, -Lantz Moore, -Morioka Tomohiko, @c Morioka -Erik Toubro Nielsen, -Hrvoje Niksic, -Andy Norman, -Fred Oberhauser, -C. R. Oldham, -Alexandre Oliva, -Ken Olstad, -Masaharu Onishi, @c Onishi -Hideki Ono, @c Ono -Ettore Perazzoli, -William Perry, -Stephen Peters, -Jens-Ulrik Holger Petersen, -Ulrich Pfeifer, -Matt Pharr, -Andy Piper, -John McClary Prevost, -Bill Pringlemeir, -Mike Pullen, -Jim Radford, -Colin Rafferty, -Lasse Rasinen, -Lars Balker Rasmussen, -Joe Reiss, -Renaud Rioboo, -Roland B. Roberts, -Bart Robinson, -Christian von Roques, -Markus Rost, -Jason Rumney, -Wolfgang Rupprecht, -Jay Sachs, -Dewey M. Sasser, -Conrad Sauerwald, -Loren Schall, -Dan Schmidt, -Ralph Schleicher, -Philippe Schnoebelen, -Andreas Schwab, -Randal L. Schwartz, -Danny Siu, -Matt Simmons, -Paul D. Smith, -Jeff Sparkes, -Toby Speight, -Michael Sperber, -Darren Stalder, -Richard Stallman, -Greg Stark, -Sam Steingold, -Paul Stevenson, -Jonas Steverud, -Paul Stodghill, -Kiyokazu Suto, @c Suto -Kurt Swanson, -Samuel Tardieu, -Teddy, -Chuck Thompson, -Tozawa Akihiko, @c Tozawa -Philippe Troin, -James Troup, -Trung Tran-Duc, -Jack Twilley, -Aaron M. Ucko, -Aki Vehtari, -Didier Verna, -Vladimir Volovich, -Jan Vroonhof, -Stefan Waldherr, -Pete Ware, -Barry A. Warsaw, -Christoph Wedler, -Joe Wells, -Lee Willis, -and -Lloyd Zusman. - - -For a full overview of what each person has done, the ChangeLogs -included in the Gnus alpha distributions should give ample reading -(550kB and counting). - -Apologies to everybody that I've forgotten, of which there are many, I'm -sure. - -Gee, that's quite a list of people. I guess that must mean that there -actually are people who are using Gnus. Who'd'a thunk it! - - -@node New Features -@subsection New Features -@cindex new features - -@menu -* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. -* September Gnus:: The Thing Formally Known As Gnus 5.2/5.3. -* Red Gnus:: Third time best---Gnus 5.4/5.5. -* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. -* Pterodactyl Gnus:: Pentad also starts with P, AKA Gnus 5.8/5.9. -* Oort Gnus:: It's big. It's far out. Gnus 5.10/5.11. -* No Gnus:: Very punny. -@end menu - -These lists are, of course, just @emph{short} overviews of the -@emph{most} important new features. No, really. There are tons more. -Yes, we have feeping creaturism in full effect. - -@node ding Gnus -@subsubsection (ding) Gnus - -New features in Gnus 5.0/5.1: - -@itemize @bullet - -@item -The look of all buffers can be changed by setting format-like variables -(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). - -@item -Local spool and several @acronym{NNTP} servers can be used at once -(@pxref{Select Methods}). - -@item -You can combine groups into virtual groups (@pxref{Virtual Groups}). - -@item -You can read a number of different mail formats (@pxref{Getting Mail}). -All the mail back ends implement a convenient mail expiry scheme -(@pxref{Expiring Mail}). - -@item -Gnus can use various strategies for gathering threads that have lost -their roots (thereby gathering loose sub-threads into one thread) or it -can go back and retrieve enough headers to build a complete thread -(@pxref{Customizing Threading}). - -@item -Killed groups can be displayed in the group buffer, and you can read -them as well (@pxref{Listing Groups}). - -@item -Gnus can do partial group updates---you do not have to retrieve the -entire active file just to check for new articles in a few groups -(@pxref{The Active File}). - -@item -Gnus implements a sliding scale of subscribedness to groups -(@pxref{Group Levels}). - -@item -You can score articles according to any number of criteria -(@pxref{Scoring}). You can even get Gnus to find out how to score -articles for you (@pxref{Adaptive Scoring}). - -@item -Gnus maintains a dribble buffer that is auto-saved the normal Emacs -manner, so it should be difficult to lose much data on what you have -read if your machine should go down (@pxref{Auto Save}). - -@item -Gnus now has its own startup file (@file{~/.gnus.el}) to avoid -cluttering up the @file{.emacs} file. - -@item -You can set the process mark on both groups and articles and perform -operations on all the marked items (@pxref{Process/Prefix}). - -@item -You can grep through a subset of groups and create a group from the -results (@pxref{Kibozed Groups}). - -@item -You can list subsets of groups according to, well, anything -(@pxref{Listing Groups}). - -@item -You can browse foreign servers and subscribe to groups from those -servers (@pxref{Browse Foreign Server}). - -@item -Gnus can fetch articles, asynchronously, on a second connection to the -server (@pxref{Asynchronous Fetching}). - -@item -You can cache articles locally (@pxref{Article Caching}). - -@item -The uudecode functions have been expanded and generalized -(@pxref{Decoding Articles}). - -@item -You can still post uuencoded articles, which was a little-known feature -of @sc{gnus}' past (@pxref{Uuencoding and Posting}). - -@item -Fetching parents (and other articles) now actually works without -glitches (@pxref{Finding the Parent}). - -@item -Gnus can fetch @acronym{FAQ}s and group descriptions (@pxref{Group Information}). - -@item -Digests (and other files) can be used as the basis for groups -(@pxref{Document Groups}). - -@item -Articles can be highlighted and customized (@pxref{Customizing -Articles}). - -@item -URLs and other external references can be buttonized (@pxref{Article -Buttons}). - -@item -You can do lots of strange stuff with the Gnus window & frame -configuration (@pxref{Window Layout}). - -@item -You can click on buttons instead of using the keyboard -(@pxref{Buttons}). - -@end itemize - - -@node September Gnus -@subsubsection September Gnus - -@iftex -@iflatex -\gnusfig{-28cm}{0cm}{\epsfig{figure=ps/september,height=20cm}} -@end iflatex -@end iftex - -New features in Gnus 5.2/5.3: - -@itemize @bullet - -@item -A new message composition mode is used. All old customization variables -for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are -now obsolete. - -@item -Gnus is now able to generate @dfn{sparse} threads---threads where -missing articles are represented by empty nodes (@pxref{Customizing -Threading}). - -@lisp -(setq gnus-build-sparse-threads 'some) -@end lisp - -@item -Outgoing articles are stored on a special archive server -(@pxref{Archived Messages}). - -@item -Partial thread regeneration now happens when articles are -referred. - -@item -Gnus can make use of GroupLens predictions. - -@item -Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). - -@item -A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). - -@lisp -(setq gnus-use-trees t) -@end lisp - -@item -An @code{nn}-like pick-and-read minor mode is available for the summary -buffers (@pxref{Pick and Read}). - -@lisp -(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) -@end lisp - -@item -In binary groups you can use a special binary minor mode (@pxref{Binary -Groups}). - -@item -Groups can be grouped in a folding topic hierarchy (@pxref{Group -Topics}). - -@lisp -(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) -@end lisp - -@item -Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). - -@item -Groups can now have a score, and bubbling based on entry frequency -is possible (@pxref{Group Score}). - -@lisp -(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) -@end lisp - -@item -Groups can be process-marked, and commands can be performed on -groups of groups (@pxref{Marking Groups}). - -@item -Caching is possible in virtual groups. - -@item -@code{nndoc} now understands all kinds of digests, mail boxes, rnews -news batches, ClariNet briefs collections, and just about everything -else (@pxref{Document Groups}). - -@item -Gnus has a new back end (@code{nnsoup}) to create/read SOUP packets -(@pxref{SOUP}). - -@item -The Gnus cache is much faster. - -@item -Groups can be sorted according to many criteria (@pxref{Sorting -Groups}). - -@item -New group parameters have been introduced to set list-addresses and -expiry times (@pxref{Group Parameters}). - -@item -All formatting specs allow specifying faces to be used -(@pxref{Formatting Fonts}). - -@item -There are several more commands for setting/removing/acting on process -marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). - -@item -The summary buffer can be limited to show parts of the available -articles based on a wide range of criteria. These commands have been -bound to keys on the @kbd{/} submap (@pxref{Limiting}). - -@item -Articles can be made persistent with the @kbd{*} command -(@pxref{Persistent Articles}). - -@item -All functions for hiding article elements are now toggles. - -@item -Article headers can be buttonized (@pxref{Article Washing}). - -@item -All mail back ends support fetching articles by @code{Message-ID}. - -@item -Duplicate mail can now be treated properly (@pxref{Duplicates}). - -@item -All summary mode commands are available directly from the article -buffer (@pxref{Article Keymap}). - -@item -Frames can be part of @code{gnus-buffer-configuration} (@pxref{Window -Layout}). - -@item -Mail can be re-scanned by a daemonic process (@pxref{Daemons}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fseptember,height=5cm}]{\epsfig{figure=ps/fseptember,height=5cm}} -@end iflatex -@end iftex - -@item -Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}). - -@lisp -(setq gnus-use-nocem t) -@end lisp - -@item -Groups can be made permanently visible (@pxref{Listing Groups}). - -@lisp -(setq gnus-permanently-visible-groups "^nnml:") -@end lisp - -@item -Many new hooks have been introduced to make customizing easier. - -@item -Gnus respects the @code{Mail-Copies-To} header. - -@item -Threads can be gathered by looking at the @code{References} header -(@pxref{Customizing Threading}). - -@lisp -(setq gnus-summary-thread-gathering-function - 'gnus-gather-threads-by-references) -@end lisp - -@item -Read articles can be stored in a special backlog buffer to avoid -refetching (@pxref{Article Backlog}). - -@lisp -(setq gnus-keep-backlog 50) -@end lisp - -@item -A clean copy of the current article is always stored in a separate -buffer to allow easier treatment. - -@item -Gnus can suggest where to save articles (@pxref{Saving Articles}). - -@item -Gnus doesn't have to do as much prompting when saving (@pxref{Saving -Articles}). - -@lisp -(setq gnus-prompt-before-saving t) -@end lisp - -@item -@code{gnus-uu} can view decoded files asynchronously while fetching -articles (@pxref{Other Decode Variables}). - -@lisp -(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) -@end lisp - -@item -Filling in the article buffer now works properly on cited text -(@pxref{Article Washing}). - -@item -Hiding cited text adds buttons to toggle hiding, and how much -cited text to hide is now customizable (@pxref{Article Hiding}). - -@lisp -(setq gnus-cited-lines-visible 2) -@end lisp - -@item -Boring headers can be hidden (@pxref{Article Hiding}). - -@item -Default scoring values can now be set from the menu bar. - -@item -Further syntax checking of outgoing articles have been added. - -@end itemize - - -@node Red Gnus -@subsubsection Red Gnus - -New features in Gnus 5.4/5.5: - -@iftex -@iflatex -\gnusfig{-5.5cm}{-4cm}{\epsfig{figure=ps/red,height=20cm}} -@end iflatex -@end iftex - -@itemize @bullet - -@item -@file{nntp.el} has been totally rewritten in an asynchronous fashion. - -@item -Article prefetching functionality has been moved up into -Gnus (@pxref{Asynchronous Fetching}). - -@item -Scoring can now be performed with logical operators like @code{and}, -@code{or}, @code{not}, and parent redirection (@pxref{Advanced -Scoring}). - -@item -Article washing status can be displayed in the -article mode line (@pxref{Misc Article}). - -@item -@file{gnus.el} has been split into many smaller files. - -@item -Suppression of duplicate articles based on Message-ID can be done -(@pxref{Duplicate Suppression}). - -@lisp -(setq gnus-suppress-duplicates t) -@end lisp - -@item -New variables for specifying what score and adapt files are to be -considered home score and adapt files (@pxref{Home Score File}) have -been added. - -@item -@code{nndoc} was rewritten to be easily extendable (@pxref{Document -Server Internals}). - -@item -Groups can inherit group parameters from parent topics (@pxref{Topic -Parameters}). - -@item -Article editing has been revamped and is now actually usable. - -@item -Signatures can be recognized in more intelligent fashions -(@pxref{Article Signature}). - -@item -Summary pick mode has been made to look more @code{nn}-like. Line -numbers are displayed and the @kbd{.} command can be used to pick -articles (@code{Pick and Read}). - -@item -Commands for moving the @file{.newsrc.eld} from one server to -another have been added (@pxref{Changing Servers}). - -@item -There's a way now to specify that ``uninteresting'' fields be suppressed -when generating lines in buffers (@pxref{Advanced Formatting}). - -@item -Several commands in the group buffer can be undone with @kbd{C-M-_} -(@pxref{Undo}). - -@item -Scoring can be done on words using the new score type @code{w} -(@pxref{Score File Format}). - -@item -Adaptive scoring can be done on a Subject word-by-word basis -(@pxref{Adaptive Scoring}). - -@lisp -(setq gnus-use-adaptive-scoring '(word)) -@end lisp - -@item -Scores can be decayed (@pxref{Score Decays}). - -@lisp -(setq gnus-decay-scores t) -@end lisp - -@item -Scoring can be performed using a regexp on the Date header. The Date is -normalized to compact ISO 8601 format first (@pxref{Score File Format}). - -@item -A new command has been added to remove all data on articles from -the native server (@pxref{Changing Servers}). - -@item -A new command for reading collections of documents -(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{C-M-d} -(@pxref{Really Various Summary Commands}). - -@item -Process mark sets can be pushed and popped (@pxref{Setting Process -Marks}). - -@item -A new mail-to-news back end makes it possible to post even when the @acronym{NNTP} -server doesn't allow posting (@pxref{Mail-To-News Gateways}). - -@item -A new back end for reading searches from Web search engines -(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added -(@pxref{Web Searches}). - -@item -Groups inside topics can now be sorted using the standard sorting -functions, and each topic can be sorted independently (@pxref{Topic -Sorting}). - -@item -Subsets of the groups can be sorted independently (@code{Sorting -Groups}). - -@item -Cached articles can be pulled into the groups (@pxref{Summary Generation -Commands}). -@iftex -@iflatex -\marginpar[\mbox{}\hfill\epsfig{figure=ps/fred,width=3cm}]{\epsfig{figure=ps/fred,width=3cm}} -@end iflatex -@end iftex - -@item -Score files are now applied in a more reliable order (@pxref{Score -Variables}). - -@item -Reports on where mail messages end up can be generated (@pxref{Splitting -Mail}). - -@item -More hooks and functions have been added to remove junk from incoming -mail before saving the mail (@pxref{Washing Mail}). - -@item -Emphasized text can be properly fontisized: - -@end itemize - - -@node Quassia Gnus -@subsubsection Quassia Gnus - -New features in Gnus 5.6: - -@itemize @bullet - -@item -New functionality for using Gnus as an offline newsreader has been -added. A plethora of new commands and modes have been added. -@xref{Gnus Unplugged}, for the full story. - -@item -The @code{nndraft} back end has returned, but works differently than -before. All Message buffers are now also articles in the @code{nndraft} -group, which is created automatically. - -@item -@code{gnus-alter-header-function} can now be used to alter header -values. - -@item -@code{gnus-summary-goto-article} now accept Message-ID's. - -@item -A new Message command for deleting text in the body of a message -outside the region: @kbd{C-c C-v}. - -@item -You can now post to component group in @code{nnvirtual} groups with -@kbd{C-u C-c C-c}. - -@item - @code{nntp-rlogin-program}---new variable to ease customization. - -@item -@code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit -re-highlighting of the article buffer. - -@item -New element in @code{gnus-boring-article-headers}---@code{long-to}. - -@item -@kbd{M-i} symbolic prefix command. @xref{Symbolic Prefixes}, for -details. - -@item -@kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix -@kbd{a} to add the score rule to the @file{all.SCORE} file. - -@item -@code{gnus-simplify-subject-functions} variable to allow greater -control over simplification. - -@item -@kbd{A T}---new command for fetching the current thread. - -@item -@kbd{/ T}---new command for including the current thread in the -limit. - -@item -@kbd{M-RET} is a new Message command for breaking cited text. - -@item -@samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. - -@item -The @code{custom-face-lookup} function has been removed. -If you used this function in your initialization files, you must -rewrite them to use @code{face-spec-set} instead. - -@item -Canceling now uses the current select method. Symbolic prefix -@kbd{a} forces normal posting method. - -@item -New command to translate M******** sm*rtq**t*s into proper -text---@kbd{W d}. - -@item -For easier debugging of @code{nntp}, you can set -@code{nntp-record-commands} to a non-@code{nil} value. - -@item -@code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for -controlling where and how to send @sc{authinfo} to @acronym{NNTP} servers. - -@item -A command for editing group parameters from the summary buffer -has been added. - -@item -A history of where mails have been split is available. - -@item -A new article date command has been added---@code{article-date-iso8601}. - -@item -Subjects can be simplified when threading by setting -@code{gnus-score-thread-simplify}. - -@item -A new function for citing in Message has been -added---@code{message-cite-original-without-signature}. - -@item -@code{article-strip-all-blank-lines}---new article command. - -@item -A new Message command to kill to the end of the article has -been added. - -@item -A minimum adaptive score can be specified by using the -@code{gnus-adaptive-word-minimum} variable. - -@item -The ``lapsed date'' article header can be kept continually -updated by the @code{gnus-start-date-timer} command. - -@item -Web listserv archives can be read with the @code{nnlistserv} back end. - -@item -Old dejanews archives can now be read by @code{nnweb}. - -@end itemize - -@node Pterodactyl Gnus -@subsubsection Pterodactyl Gnus - -New features in Gnus 5.8: - -@itemize @bullet - -@item -The mail-fetching functions have changed. See the manual for the -many details. In particular, all procmail fetching variables are gone. - -If you used procmail like in - -@lisp -(setq nnmail-use-procmail t) -(setq nnmail-spool-file 'procmail) -(setq nnmail-procmail-directory "~/mail/incoming/") -(setq nnmail-procmail-suffix "\\.in") -@end lisp - -this now has changed to - -@lisp -(setq mail-sources - '((directory :path "~/mail/incoming/" - :suffix ".in"))) -@end lisp - -@xref{Mail Source Specifiers}. - -@item -Gnus is now a @acronym{MIME}-capable reader. This affects many parts of -Gnus, and adds a slew of new commands. See the manual for details. - -@item -Gnus has also been multilingualized. This also affects too -many parts of Gnus to summarize here, and adds many new variables. - -@item -@code{gnus-auto-select-first} can now be a function to be -called to position point. - -@item -The user can now decide which extra headers should be included in -summary buffers and @acronym{NOV} files. - -@item -@code{gnus-article-display-hook} has been removed. Instead, a number -of variables starting with @code{gnus-treat-} have been added. - -@item -The Gnus posting styles have been redone again and now works in a -subtly different manner. - -@item -New web-based back ends have been added: @code{nnslashdot}, -@code{nnwarchive} and @code{nnultimate}. nnweb has been revamped, -again, to keep up with ever-changing layouts. - -@item -Gnus can now read @acronym{IMAP} mail via @code{nnimap}. - -@end itemize - -@node Oort Gnus -@subsubsection Oort Gnus -@cindex Oort Gnus - -New features in Gnus 5.10: - -@itemize @bullet - -@item Installation changes -@c *********************** - -@itemize @bullet -@item -Upgrading from previous (stable) version if you have used Oort. - -If you have tried Oort (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading to -this version. In particular, you will probably want to remove all -@file{.marks} (nnml) and @file{.mrk} (nnfolder) files, so that flags are -read from your @file{.newsrc.eld} instead of from the -@file{.marks}/@file{.mrk} file where this release store flags. See a -later entry for more information about marks. Note that downgrading -isn't save in general. - -@item -Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item -New @file{make.bat} for compiling and installing Gnus under MS Windows - -Use @file{make.bat} if you want to install Gnus under MS Windows, the -first argument to the batch-program should be the directory where -@file{xemacs.exe} respectively @file{emacs.exe} is located, if you want -to install Gnus after compiling it, give @file{make.bat} @code{/copy} as -the second parameter. - -@file{make.bat} has been rewritten from scratch, it now features -automatic recognition of XEmacs and GNU Emacs, generates -@file{gnus-load.el}, checks if errors occur while compilation and -generation of info files and reports them at the end of the build -process. It now uses @code{makeinfo} if it is available and falls -back to @file{infohack.el} otherwise. @file{make.bat} should now -install all files which are necessary to run Gnus and be generally a -complete replacement for the @code{configure; make; make install} -cycle used under Unix systems. - -The new @file{make.bat} makes @file{make-x.bat} and @file{xemacs.mak} -superfluous, so they have been removed. - -@item -@file{~/News/overview/} not used. - -As a result of the following change, the @file{~/News/overview/} -directory is not used any more. You can safely delete the entire -hierarchy. - -@c FIXME: `gnus-load' is mentioned in README, which is not included in -@c CVS. We should find a better place for this item. -@item -@code{(require 'gnus-load)} - -If you use a stand-alone Gnus distribution, you'd better add -@code{(require 'gnus-load)} into your @file{~/.emacs} after adding the Gnus -lisp directory into load-path. - -File @file{gnus-load.el} contains autoload commands, functions and variables, -some of which may not be included in distributions of Emacsen. - -@end itemize - -@item New packages and libraries within Gnus -@c ***************************************** - -@itemize @bullet - -@item -The revised Gnus @acronym{FAQ} is included in the manual, -@xref{Frequently Asked Questions}. - -@item -@acronym{TLS} wrapper shipped with Gnus - -@acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GNUTLS. The old -@acronym{TLS}/@acronym{SSL} support via (external third party) -@file{ssl.el} and OpenSSL still works. - -@item -Improved anti-spam features. - -Gnus is now able to take out spam from your mail and news streams -using a wide variety of programs and filter rules. Among the supported -methods are RBL blocklists, bogofilter and white/blacklists. Hooks -for easy use of external packages such as SpamAssassin and Hashcash -are also new. @ref{Thwarting Email Spam} and @ref{Spam Package}. -@c FIXME: @xref{Spam Package}?. Should this be under Misc? - -@item -Gnus supports server-side mail filtering using Sieve. - -Sieve rules can be added as Group Parameters for groups, and the -complete Sieve script is generated using @kbd{D g} from the Group -buffer, and then uploaded to the server using @kbd{C-c C-l} in the -generated Sieve buffer. @xref{Sieve Commands}, and the new Sieve -manual @ref{Top, , Top, sieve, Emacs Sieve}. - -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -@code{gnus-group-read-ephemeral-group} can be called interactively, -using @kbd{G M}. - -@item -Retrieval of charters and control messages - -There are new commands for fetching newsgroup charters (@kbd{H c}) and -control messages (@kbd{H C}). - -@item -The new variable @code{gnus-parameters} can be used to set group parameters. - -Earlier this was done only via @kbd{G p} (or @kbd{G c}), which stored -the parameters in @file{~/.newsrc.eld}, but via this variable you can -enjoy the powers of customize, and simplified backups since you set the -variable in @file{~/.gnus.el} instead of @file{~/.newsrc.eld}. The -variable maps regular expressions matching group names to group -parameters, a'la: -@lisp -(setq gnus-parameters - '(("mail\\..*" - (gnus-show-threads nil) - (gnus-use-scoring nil)) - ("^nnimap:\\(foo.bar\\)$" - (to-group . "\\1")))) -@end lisp - -@item -Unread count correct in nnimap groups. - -The estimated number of unread articles in the group buffer should now -be correct for nnimap groups. This is achieved by calling -@code{nnimap-fixup-unread-after-getting-new-news} from the -@code{gnus-setup-news-hook} (called on startup) and -@code{gnus-after-getting-new-news-hook}. (called after getting new -mail). If you have modified those variables from the default, you may -want to add @code{nnimap-fixup-unread-after-getting-new-news} again. If -you were happy with the estimate and want to save some (minimal) time -when getting new mail, remove the function. - -@item -Group names are treated as UTF-8 by default. - -This is supposedly what USEFOR wanted to migrate to. See -@code{gnus-group-name-charset-group-alist} and -@code{gnus-group-name-charset-method-alist} for customization. - -@item -@code{gnus-group-charset-alist} and -@code{gnus-group-ignored-charsets-alist}. - -The regexps in these variables are compared with full group names -instead of real group names in 5.8. Users who customize these -variables should change those regexps accordingly. For example: -@lisp -("^han\\>" euc-kr) -> ("\\(^\\|:\\)han\\>" euc-kr) -@end lisp - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. (New in Gnus 5.10.10 / Emacs 22.2) - -@end itemize - -@item Changes in summary and article mode -@c ************************************** - -@itemize @bullet - -@item -@kbd{F} (@code{gnus-article-followup-with-original}) and @kbd{R} -(@code{gnus-article-reply-with-original}) only yank the text in the -region if the region is active. - -@item -In draft groups, @kbd{e} is now bound to @code{gnus-draft-edit-message}. -Use @kbd{B w} for @code{gnus-summary-edit-article} instead. - -@item -Article Buttons - -More buttons for URLs, mail addresses, Message-IDs, Info links, man -pages and Emacs or Gnus related references. @xref{Article Buttons}. The -variables @code{gnus-button-@var{*}-level} can be used to control the -appearance of all article buttons. @xref{Article Button Levels}. - -@item -Single-part yenc encoded attachments can be decoded. - -@item -Picons - -The picons code has been reimplemented to work in GNU Emacs---some of -the previous options have been removed or renamed. - -Picons are small ``personal icons'' representing users, domain and -newsgroups, which can be displayed in the Article buffer. -@xref{Picons}. - -@item -If the new option @code{gnus-treat-body-boundary} is non-@code{nil}, a -boundary line is drawn at the end of the headers. - -@item -Signed article headers (X-PGP-Sig) can be verified with @kbd{W p}. - -@item -The Summary Buffer uses an arrow in the fringe to indicate the current -article. Use @code{(setq gnus-summary-display-arrow nil)} to disable it. - -@item -Warn about email replies to news - -Do you often find yourself replying to news by email by mistake? Then -the new option @code{gnus-confirm-mail-reply-to-news} is just the thing for -you. - -@item -If the new option @code{gnus-summary-display-while-building} is -non-@code{nil}, the summary buffer is shown and updated as it's being -built. - -@item -The new @code{recent} mark @samp{.} indicates newly arrived messages (as -opposed to old but unread messages). - -@item -Gnus supports RFC 2369 mailing list headers, and adds a number of -related commands in mailing list groups. @xref{Mailing List}. - -@item -The Date header can be displayed in a format that can be read aloud -in English. @xref{Article Date}. - -@item -diffs are automatically highlighted in groups matching -@code{mm-uu-diff-groups-regexp} - -@item -Better handling of Microsoft citation styles - -Gnus now tries to recognize the mangled header block that some Microsoft -mailers use to indicate that the rest of the message is a citation, even -though it is not quoted in any way. The variable -@code{gnus-cite-unsightly-citation-regexp} matches the start of these -citations. - -The new command @kbd{W Y f} -(@code{gnus-article-outlook-deuglify-article}) allows deuglifying broken -Outlook (Express) articles. - -@item -@code{gnus-article-skip-boring} - -If you set @code{gnus-article-skip-boring} to @code{t}, then Gnus will -not scroll down to show you a page that contains only boring text, -which by default means cited text and signature. You can customize -what is skippable using @code{gnus-article-boring-faces}. - -This feature is especially useful if you read many articles that -consist of a little new content at the top with a long, untrimmed -message cited below. - -@item -Smileys (@samp{:-)}, @samp{;-)} etc) are now displayed graphically in -Emacs too. - -Put @code{(setq gnus-treat-display-smileys nil)} in @file{~/.gnus.el} to -disable it. - -@item -Face headers handling. @xref{Face}. - -@item -In the summary buffer, the new command @kbd{/ N} inserts new messages -and @kbd{/ o} inserts old messages. - -@item -Gnus decodes morse encoded messages if you press @kbd{W m}. - -@item -@code{gnus-summary-line-format} - -The default value changed to @samp{%U%R%z%I%(%[%4L: %-23,23f%]%) -%s\n}. Moreover @code{gnus-extra-headers}, -@code{nnmail-extra-headers} and @code{gnus-ignored-from-addresses} -changed their default so that the users name will be replaced by the -recipient's name or the group name posting to for @acronym{NNTP} -groups. - -@item -Deleting of attachments. - -The command @code{gnus-mime-save-part-and-strip} (bound to @kbd{C-o} -on @acronym{MIME} buttons) saves a part and replaces the part with an -external one. @code{gnus-mime-delete-part} (bound to @kbd{d} on -@acronym{MIME} buttons) removes a part. It works only on back ends -that support editing. - -@item -@code{gnus-default-charset} - -The default value is determined from the -@code{current-language-environment} variable, instead of -@code{iso-8859-1}. Also the @samp{.*} item in -@code{gnus-group-charset-alist} is removed. - -@item -Printing capabilities are enhanced. - -Gnus supports Muttprint natively with @kbd{O P} from the Summary and -Article buffers. Also, each individual @acronym{MIME} part can be -printed using @kbd{p} on the @acronym{MIME} button. - -@item -Extended format specs. - -Format spec @samp{%&user-date;} is added into -@code{gnus-summary-line-format-alist}. Also, user defined extended -format specs are supported. The extended format specs look like -@samp{%u&foo;}, which invokes function -@code{gnus-user-format-function-@var{foo}}. Because @samp{&} is used as the -escape character, old user defined format @samp{%u&} is no longer supported. - -@item -@kbd{/ *} (@code{gnus-summary-limit-include-cached}) is rewritten. -@c FIXME: Was this a user-visible change? - -It was aliased to @kbd{Y c} -(@code{gnus-summary-insert-cached-articles}). The new function filters -out other articles. - -@item -Some limiting commands accept a @kbd{C-u} prefix to negate the match. - -If @kbd{C-u} is used on subject, author or extra headers, i.e., @kbd{/ -s}, @kbd{/ a}, and @kbd{/ x} -(@code{gnus-summary-limit-to-@{subject,author,extra@}}) respectively, the -result will be to display all articles that do not match the expression. - -@item -Gnus inlines external parts (message/external). - -@end itemize - -@item Changes in Message mode and related Gnus features -@c **************************************************** - -@itemize @bullet - -@item -Delayed articles - -You can delay the sending of a message with @kbd{C-c C-j} in the Message -buffer. The messages are delivered at specified time. This is useful -for sending yourself reminders. @xref{Delayed Articles}. - -@item -If the new option @code{nnml-use-compressed-files} is non-@code{nil}, -the nnml back end allows compressed message files. - -@item -The new option @code{gnus-gcc-mark-as-read} automatically marks -Gcc articles as read. - -@item -Externalizing of attachments - -If @code{gnus-gcc-externalize-attachments} or -@code{message-fcc-externalize-attachments} is non-@code{nil}, attach -local files as external parts. - -@item -The envelope sender address can be customized when using Sendmail. -@xref{Mail Variables, Mail Variables,, message, Message Manual}. - -@item -Gnus no longer generate the Sender: header automatically. - -Earlier it was generated when the user configurable email address was -different from the Gnus guessed default user address. As the guessing -algorithm is rarely correct these days, and (more controversially) the -only use of the Sender: header was to check if you are entitled to -cancel/supersede news (which is now solved by Cancel Locks instead, -see another entry), generation of the header has been disabled by -default. See the variables @code{message-required-headers}, -@code{message-required-news-headers}, and -@code{message-required-mail-headers}. - -@item -Features from third party @file{message-utils.el} added to @file{message.el}. - -Message now asks if you wish to remove @samp{(was: )} from -subject lines (see @code{message-subject-trailing-was-query}). @kbd{C-c -M-m} and @kbd{C-c M-f} inserts markers indicating included text. -@kbd{C-c C-f a} adds a X-No-Archive: header. @kbd{C-c C-f x} inserts -appropriate headers and a note in the body for cross-postings and -followups (see the variables @code{message-cross-post-@var{*}}). - -@item -References and X-Draft-From headers are no longer generated when you -start composing messages and @code{message-generate-headers-first} is -@code{nil}. - -@item -Easy inclusion of X-Faces headers. @xref{X-Face}. - -@item -Group Carbon Copy (GCC) quoting - -To support groups that contains SPC and other weird characters, groups -are quoted before they are placed in the Gcc: header. This means -variables such as @code{gnus-message-archive-group} should no longer -contain quote characters to make groups containing SPC work. Also, if -you are using the string @samp{nnml:foo, nnml:bar} (indicating Gcc -into two groups) you must change it to return the list -@code{("nnml:foo" "nnml:bar")}, otherwise the Gcc: line will be quoted -incorrectly. Note that returning the string @samp{nnml:foo, nnml:bar} -was incorrect earlier, it just didn't generate any problems since it -was inserted directly. - -@item -@code{message-insinuate-rmail} - -@c FIXME should that not be 'message-user-agent? -Adding @code{(message-insinuate-rmail)} and @code{(setq -mail-user-agent 'gnus-user-agent)} in @file{.emacs} convinces Rmail to -compose, reply and forward messages in message-mode, where you can -enjoy the power of @acronym{MML}. - -@item -@code{message-minibuffer-local-map} - -The line below enables BBDB in resending a message: -@lisp -(define-key message-minibuffer-local-map [(tab)] - 'bbdb-complete-name) -@end lisp - -@item -@code{gnus-posting-styles} - -Add a new format of match like -@lisp -((header "to" "larsi.*org") - (Organization "Somewhere, Inc.")) -@end lisp -The old format like the lines below is obsolete, but still accepted. -@lisp -(header "to" "larsi.*org" - (Organization "Somewhere, Inc.")) -@end lisp - -@item -@code{message-ignored-news-headers} and @code{message-ignored-mail-headers} - -@samp{X-Draft-From} and @samp{X-Gnus-Agent-Meta-Information} have been -added into these two variables. If you customized those, perhaps you -need add those two headers too. - -@item -Gnus supports the ``format=flowed'' (RFC 2646) parameter. On -composing messages, it is enabled by @code{use-hard-newlines}. -Decoding format=flowed was present but not documented in earlier -versions. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -``format=flowed'' messages. Also, flowed text is disabled when sending -inline PGP signed messages. @xref{Flowed text, , Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "No Gnus". - -@item -Gnus supports the generation of RFC 2298 Disposition Notification requests. - -This is invoked with the @kbd{C-c M-n} key binding from message mode. - -@item -Message supports the Importance: (RFC 2156) header. - -In the message buffer, @kbd{C-c C-f C-i} or @kbd{C-c C-u} cycles through -the valid values. - -@item -Gnus supports Cancel Locks in News. - -This means a header @samp{Cancel-Lock} is inserted in news posting. It is -used to determine if you wrote an article or not (for canceling and -superseding). Gnus generates a random password string the first time -you post a message, and saves it in your @file{~/.emacs} using the Custom -system. While the variable is called @code{canlock-password}, it is not -security sensitive data. Publishing your canlock string on the web -will not allow anyone to be able to anything she could not already do. -The behavior can be changed by customizing @code{message-insert-canlock}. - -@item -Gnus supports @acronym{PGP} (RFC 1991/2440), @acronym{PGP/MIME} (RFC -2015/3156) and @acronym{S/MIME} (RFC 2630-2633). - -It needs an external @acronym{S/MIME} and OpenPGP implementation, but no -additional Lisp libraries. This add several menu items to the -Attachments menu, and @kbd{C-c RET} key bindings, when composing -messages. This also obsoletes @code{gnus-article-hide-pgp-hook}. - -@item -@acronym{MML} (Mime compose) prefix changed from @kbd{M-m} to @kbd{C-c -C-m}. - -This change was made to avoid conflict with the standard binding of -@code{back-to-indentation}, which is also useful in message mode. - -@item -The default for @code{message-forward-show-mml} changed to the symbol -@code{best}. - -The behavior for the @code{best} value is to show @acronym{MML} (i.e., -convert to @acronym{MIME}) when appropriate. @acronym{MML} will not be -used when forwarding signed or encrypted messages, as the conversion -invalidate the digital signature. - -@item -If @code{auto-compression-mode} is enabled, attachments are automatically -decompressed when activated. -@c FIXME: Does this affect article or message mode? - -@item -Support for non-@acronym{ASCII} domain names - -Message supports non-@acronym{ASCII} domain names in From:, To: and -Cc: and will query you whether to perform encoding when you try to -send a message. The variable @code{message-use-idna} controls this. -Gnus will also decode non-@acronym{ASCII} domain names in From:, To: -and Cc: when you view a message. The variable @code{gnus-use-idna} -controls this. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. -@c New in 5.10.9 / 5.11 (Emacs 22.1) - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. -@c New in Gnus 5.10.12 / 5.11 (Emacs 22.3) - -@end itemize - -@item Changes in back ends -@c *********************** - -@itemize @bullet -@item -Gnus can display RSS newsfeeds as a newsgroup. @xref{RSS}. - -@item -The nndoc back end now supports mailman digests and exim bounces. - -@item -Gnus supports Maildir groups. - -Gnus includes a new back end @file{nnmaildir.el}. @xref{Maildir}. - -@item -The nnml and nnfolder back ends store marks for each groups. - -This makes it possible to take backup of nnml/nnfolder servers/groups -separately of @file{~/.newsrc.eld}, while preserving marks. It also -makes it possible to share articles and marks between users (without -sharing the @file{~/.newsrc.eld} file) within e.g. a department. It -works by storing the marks stored in @file{~/.newsrc.eld} in a per-group -file @file{.marks} (for nnml) and @file{@var{groupname}.mrk} (for -nnfolder, named @var{groupname}). If the nnml/nnfolder is moved to -another machine, Gnus will automatically use the @file{.marks} or -@file{.mrk} file instead of the information in @file{~/.newsrc.eld}. -The new server variables @code{nnml-marks-is-evil} and -@code{nnfolder-marks-is-evil} can be used to disable this feature. - -@end itemize - -@item Appearance -@c ************* - -@itemize @bullet - -@item -The menu bar item (in Group and Summary buffer) named ``Misc'' has -been renamed to ``Gnus''. - -@item -The menu bar item (in Message mode) named ``@acronym{MML}'' has been -renamed to ``Attachments''. Note that this menu also contains security -related stuff, like signing and encryption (@pxref{Security, Security,, -message, Message Manual}). - -@item -The tool bars have been updated to use GNOME icons in Group, Summary and -Message mode. You can also customize the tool bars: @kbd{M-x -customize-apropos RET -tool-bar$} should get you started. This is a new -feature in Gnus 5.10.10. (Only for Emacs, not in XEmacs.) - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. This is a new feature -in Gnus 5.10.9. -@end itemize - - -@item Miscellaneous changes -@c ************************ - -@itemize @bullet - -@item -@code{gnus-agent} - -The Gnus Agent has seen a major updated and is now enabled by default, -and all nntp and nnimap servers from @code{gnus-select-method} and -@code{gnus-secondary-select-method} are agentized by default. Earlier -only the server in @code{gnus-select-method} was agentized by the -default, and the agent was disabled by default. When the agent is -enabled, headers are now also retrieved from the Agent cache instead -of the back ends when possible. Earlier this only happened in the -unplugged state. You can enroll or remove servers with @kbd{J a} and -@kbd{J r} in the server buffer. Gnus will not download articles into -the Agent cache, unless you instruct it to do so, though, by using -@kbd{J u} or @kbd{J s} from the Group buffer. You revert to the old -behavior of having the Agent disabled with @code{(setq gnus-agent -nil)}. Note that putting @code{(gnus-agentize)} in @file{~/.gnus.el} -is not needed any more. - -@item -Gnus reads the @acronym{NOV} and articles in the Agent if plugged. - -If one reads an article while plugged, and the article already exists -in the Agent, it won't get downloaded once more. @code{(setq -gnus-agent-cache nil)} reverts to the old behavior. - -@item -Dired integration - -@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key -bindings in dired buffers to send a file as an attachment, open a file -using the appropriate mailcap entry, and print a file using the mailcap -entry. - -@item -The format spec @code{%C} for positioning point has changed to @code{%*}. - -@item -@code{gnus-slave-unplugged} - -A new command which starts Gnus offline in slave mode. - -@end itemize - -@end itemize - -@node No Gnus -@subsubsection No Gnus -@cindex No Gnus - -New features in No Gnus: -@c FIXME: Gnus 5.12? - -@include gnus-news.texi - -@iftex - -@page -@node The Manual -@section The Manual -@cindex colophon -@cindex manual - -This manual was generated from a TeXinfo file and then run through -either @code{texi2dvi} -@iflatex -or my own home-brewed TeXinfo to \LaTeX\ transformer, -and then run through @code{latex} and @code{dvips} -@end iflatex -to get what you hold in your hands now. - -The following conventions have been used: - -@enumerate - -@item -This is a @samp{string} - -@item -This is a @kbd{keystroke} - -@item -This is a @file{file} - -@item -This is a @code{symbol} - -@end enumerate - -So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would -mean: - -@lisp -(setq flargnoze "yes") -@end lisp - -If I say ``set @code{flumphel} to @code{yes}'', that would mean: - -@lisp -(setq flumphel 'yes) -@end lisp - -@samp{yes} and @code{yes} are two @emph{very} different things---don't -ever get them confused. - -@iflatex -@c @head -Of course, everything in this manual is of vital interest, so you should -read it all. Several times. However, if you feel like skimming the -manual, look for that gnu head you should see in the margin over -there---it means that what's being discussed is of more importance than -the rest of the stuff. (On the other hand, if everything is infinitely -important, how can anything be more important than that? Just one more -of the mysteries of this world, I guess.) -@end iflatex - -@end iftex - - -@node On Writing Manuals -@section On Writing Manuals - -I guess most manuals are written after-the-fact; documenting a program -that's already there. This is not how this manual is written. When -implementing something, I write the manual entry for that something -straight away. I then see that it's difficult to explain the -functionality, so I write how it's supposed to be, and then I change the -implementation. Writing the documentation and writing the code go hand -in hand. - -This, of course, means that this manual has no, or little, flow. It -documents absolutely everything in Gnus, but often not where you're -looking for it. It is a reference manual, and not a guide to how to get -started with Gnus. - -That would be a totally different book, that should be written using the -reference manual as source material. It would look quite different. - - -@page -@node Terminology -@section Terminology - -@cindex terminology -@table @dfn - -@item news -@cindex news -This is what you are supposed to use this thing for---reading news. -News is generally fetched from a nearby @acronym{NNTP} server, and is -generally publicly available to everybody. If you post news, the entire -world is likely to read just what you have written, and they'll all -snigger mischievously. Behind your back. - -@item mail -@cindex mail -Everything that's delivered to you personally is mail. Some news/mail -readers (like Gnus) blur the distinction between mail and news, but -there is a difference. Mail is private. News is public. Mailing is -not posting, and replying is not following up. - -@item reply -@cindex reply -Send a mail to the person who has written what you are reading. - -@item follow up -@cindex follow up -Post an article to the current newsgroup responding to the article you -are reading. - -@item back end -@cindex back end -Gnus considers mail and news to be mostly the same, really. The only -difference is how to access the actual articles. News articles are -commonly fetched via the protocol @acronym{NNTP}, whereas mail -messages could be read from a file on the local disk. The internal -architecture of Gnus thus comprises a ``front end'' and a number of -``back ends''. Internally, when you enter a group (by hitting -@key{RET}, say), you thereby invoke a function in the front end in -Gnus. The front end then ``talks'' to a back end and says things like -``Give me the list of articles in the foo group'' or ``Show me article -number 4711''. - -So a back end mainly defines either a protocol (the @code{nntp} back -end accesses news via @acronym{NNTP}, the @code{nnimap} back end -accesses mail via @acronym{IMAP}) or a file format and directory -layout (the @code{nnspool} back end accesses news via the common -``spool directory'' format, the @code{nnml} back end access mail via a -file format and directory layout that's quite similar). - -Gnus does not handle the underlying media, so to speak---this is all -done by the back ends. A back end is a collection of functions to -access the articles. - -However, sometimes the term ``back end'' is also used where ``server'' -would have been more appropriate. And then there is the term ``select -method'' which can mean either. The Gnus terminology can be quite -confusing. - -@item native -@cindex native -Gnus will always use one method (and back end) as the @dfn{native}, or -default, way of getting news. - -@item foreign -@cindex foreign -You can also have any number of foreign groups active at the same time. -These are groups that use non-native non-secondary back ends for getting -news. - -@item secondary -@cindex secondary -Secondary back ends are somewhere half-way between being native and being -foreign, but they mostly act like they are native. - -@item article -@cindex article -A message that has been posted as news. - -@item mail message -@cindex mail message -A message that has been mailed. - -@item message -@cindex message -A mail message or news article - -@item head -@cindex head -The top part of a message, where administrative information (etc.) is -put. - -@item body -@cindex body -The rest of an article. Everything not in the head is in the -body. - -@item header -@cindex header -A line from the head of an article. - -@item headers -@cindex headers -A collection of such lines, or a collection of heads. Or even a -collection of @acronym{NOV} lines. - -@item @acronym{NOV} -@cindex @acronym{NOV} -@acronym{NOV} stands for News OverView, which is a type of news server -header which provide datas containing the condensed header information -of articles. They are produced by the server itself; in the @code{nntp} -back end Gnus uses the ones that the @acronym{NNTP} server makes, but -Gnus makes them by itself for some backends (in particular, @code{nnml}). - -When Gnus enters a group, it asks the back end for the headers of all -unread articles in the group. Most servers support the News OverView -format, which is more compact and much faster to read and parse than the -normal @sc{head} format. - -The @acronym{NOV} data consist of one or more text lines (@pxref{Text -Lines, ,Motion by Text Lines, elisp, The Emacs Lisp Reference Manual}) -where each line has the header information of one article. The header -information is a tab-separated series of the header's contents including -an article number, a subject, an author, a date, a message-id, -references, etc. - -Those data enable Gnus to generate summary lines quickly. However, if -the server does not support @acronym{NOV} or you disable it purposely or -for some reason, Gnus will try to generate the header information by -parsing each article's headers one by one. It will take time. -Therefore, it is not usually a good idea to set nn*-nov-is-evil -(@pxref{Slow/Expensive Connection}) to a non-@code{nil} value unless you -know that the server makes wrong @acronym{NOV} data. - -@item level -@cindex levels -Each group is subscribed at some @dfn{level} or other (1-9). The ones -that have a lower level are ``more'' subscribed than the groups with a -higher level. In fact, groups on levels 1-5 are considered -@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 -are @dfn{killed}. Commands for listing groups and scanning for new -articles will all use the numeric prefix as @dfn{working level}. - -@item killed groups -@cindex killed groups -No information on killed groups is stored or updated, which makes killed -groups much easier to handle than subscribed groups. - -@item zombie groups -@cindex zombie groups -Just like killed groups, only slightly less dead. - -@item active file -@cindex active file -The news server has to keep track of what articles it carries, and what -groups exist. All this information in stored in the active file, which -is rather large, as you might surmise. - -@item bogus groups -@cindex bogus groups -A group that exists in the @file{.newsrc} file, but isn't known to the -server (i.e., it isn't in the active file), is a @emph{bogus group}. -This means that the group probably doesn't exist (any more). - -@item activating -@cindex activating groups -The act of asking the server for info on a group and computing the -number of unread articles is called @dfn{activating the group}. -Un-activated groups are listed with @samp{*} in the group buffer. - -@item spool -@cindex spool -News servers store their articles locally in one fashion or other. -One old-fashioned storage method is to have just one file per -article. That's called a ``traditional spool''. - -@item server -@cindex server -A machine one can connect to and get news (or mail) from. - -@item select method -@cindex select method -A structure that specifies the back end, the server and the virtual -server settings. - -@item virtual server -@cindex virtual server -A named select method. Since a select method defines all there is to -know about connecting to a (physical) server, taking the thing as a -whole is a virtual server. - -@item washing -@cindex washing -Taking a buffer and running it through a filter of some sort. The -result will (more often than not) be cleaner and more pleasing than the -original. - -@item ephemeral groups -@cindex ephemeral groups -@cindex temporary groups -Most groups store data on what articles you have read. @dfn{Ephemeral} -groups are groups that will have no data stored---when you exit the -group, it'll disappear into the aether. - -@item solid groups -@cindex solid groups -This is the opposite of ephemeral groups. All groups listed in the -group buffer are solid groups. - -@item sparse articles -@cindex sparse articles -These are article placeholders shown in the summary buffer when -@code{gnus-build-sparse-threads} has been switched on. - -@item threading -@cindex threading -To put responses to articles directly after the articles they respond -to---in a hierarchical fashion. - -@item root -@cindex root -@cindex thread root -The first article in a thread is the root. It is the ancestor of all -articles in the thread. - -@item parent -@cindex parent -An article that has responses. - -@item child -@cindex child -An article that responds to a different article---its parent. - -@item digest -@cindex digest -A collection of messages in one file. The most common digest format is -specified by RFC 1153. - -@item splitting -@cindex splitting, terminology -@cindex mail sorting -@cindex mail filtering (splitting) -The action of sorting your emails according to certain rules. Sometimes -incorrectly called mail filtering. - -@end table - - -@page -@node Customization -@section Customization -@cindex general customization - -All variables are properly documented elsewhere in this manual. This -section is designed to give general pointers on how to customize Gnus -for some quite common situations. - -@menu -* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. -* Slow Terminal Connection:: You run a remote Emacs. -* Little Disk Space:: You feel that having large setup files is icky. -* Slow Machine:: You feel like buying a faster machine. -@end menu - - -@node Slow/Expensive Connection -@subsection Slow/Expensive Connection - -If you run Emacs on a machine locally, and get your news from a machine -over some very thin strings, you want to cut down on the amount of data -Gnus has to get from the server. - -@table @code - -@item gnus-read-active-file -Set this to @code{nil}, which will inhibit Gnus from requesting the -entire active file from the server. This file is often very large. You -also have to set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus -doesn't suddenly decide to fetch the active file anyway. - -@item gnus-nov-is-evil -@vindex gnus-nov-is-evil -Usually this one must @emph{always} be @code{nil} (which is the -default). If, for example, you wish to not use @acronym{NOV} -(@pxref{Terminology}) with the @code{nntp} back end (@pxref{Crosspost -Handling}), set @code{nntp-nov-is-evil} to a non-@code{nil} value -instead of setting this. But you normally do not need to set -@code{nntp-nov-is-evil} since Gnus by itself will detect whether the -@acronym{NNTP} server supports @acronym{NOV}. Anyway, grabbing article -headers from the @acronym{NNTP} server will not be very fast if you tell -Gnus not to use @acronym{NOV}. - -As the variables for the other back ends, there are -@code{nndiary-nov-is-evil}, @code{nndir-nov-is-evil}, -@code{nnfolder-nov-is-evil}, @code{nnimap-nov-is-evil}, -@code{nnml-nov-is-evil}, @code{nnspool-nov-is-evil}, and -@code{nnwarchive-nov-is-evil}. Note that a non-@code{nil} value for -@code{gnus-nov-is-evil} overrides all those variables.@footnote{Although -the back ends @code{nnkiboze}, @code{nnslashdot}, @code{nnultimate}, and -@code{nnwfm} don't have their own nn*-nov-is-evil.} -@end table - - -@node Slow Terminal Connection -@subsection Slow Terminal Connection - -Let's say you use your home computer for dialing up the system that runs -Emacs and Gnus. If your modem is slow, you want to reduce (as much as -possible) the amount of data sent over the wires. - -@table @code - -@item gnus-auto-center-summary -Set this to @code{nil} to inhibit Gnus from re-centering the summary -buffer all the time. If it is @code{vertical}, do only vertical -re-centering. If it is neither @code{nil} nor @code{vertical}, do both -horizontal and vertical recentering. - -@item gnus-visible-headers -Cut down on the headers included in the articles to the -minimum. You can, in fact, make do without them altogether---most of the -useful data is in the summary buffer, anyway. Set this variable to -@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. - -Use the following to enable all the available hiding features: -@lisp -(setq gnus-treat-hide-headers 'head - gnus-treat-hide-signature t - gnus-treat-hide-citation t) -@end lisp - -@item gnus-use-full-window -By setting this to @code{nil}, you can make all the windows smaller. -While this doesn't really cut down much generally, it means that you -have to see smaller portions of articles before deciding that you didn't -want to read them anyway. - -@item gnus-thread-hide-subtree -If this is non-@code{nil}, all threads in the summary buffer will be -hidden initially. - - -@item gnus-updated-mode-lines -If this is @code{nil}, Gnus will not put information in the buffer mode -lines, which might save some time. -@end table - - -@node Little Disk Space -@subsection Little Disk Space -@cindex disk space - -The startup files can get rather large, so you may want to cut their -sizes a bit if you are running out of space. - -@table @code - -@item gnus-save-newsrc-file -If this is @code{nil}, Gnus will never save @file{.newsrc}---it will -only save @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-read-newsrc-file -If this is @code{nil}, Gnus will never read @file{.newsrc}---it will -only read @file{.newsrc.eld}. This means that you will not be able to -use any other newsreaders than Gnus. This variable is @code{t} by -default. - -@item gnus-save-killed-list -If this is @code{nil}, Gnus will not save the list of dead groups. You -should also set @code{gnus-check-new-newsgroups} to @code{ask-server} -and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this -variable to @code{nil}. This variable is @code{t} by default. - -@end table - - -@node Slow Machine -@subsection Slow Machine -@cindex slow machine - -If you have a slow machine, or are just really impatient, there are a -few things you can do to make Gnus run faster. - -Set @code{gnus-check-new-newsgroups} and -@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. - -Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and -@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the -summary buffer faster. Also @pxref{Slow/Expensive Connection}. - - -@page -@node Troubleshooting -@section Troubleshooting -@cindex troubleshooting - -Gnus works @emph{so} well straight out of the box---I can't imagine any -problems, really. - -Ahem. - -@enumerate - -@item -Make sure your computer is switched on. - -@item -Make sure that you really load the current Gnus version. If you have -been running @sc{gnus}, you need to exit Emacs and start it up again before -Gnus will work. - -@item -Try doing an @kbd{M-x gnus-version}. If you get something that looks -like @c -@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line! -@c -you have the right files loaded. Otherwise you have some old @file{.el} -files lying around. Delete these. - -@item -Read the help group (@kbd{G h} in the group buffer) for a -@acronym{FAQ} and a how-to. - -@item -@vindex max-lisp-eval-depth -Gnus works on many recursive structures, and in some extreme (and very -rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at -you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or -something like that. -@end enumerate - -If all else fails, report the problem as a bug. - -@cindex bugs -@cindex reporting bugs - -@kindex M-x gnus-bug -@findex gnus-bug -If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} -command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send -me the backtrace. I will fix bugs, but I can only fix them if you send -me a precise description as to how to reproduce the bug. - -You really can never be too detailed in a bug report. Always use the -@kbd{M-x gnus-bug} command when you make bug reports, even if it creates -a 10Kb mail each time you use it, and even if you have sent me your -environment 500 times before. I don't care. I want the full info each -time. - -It is also important to remember that I have no memory whatsoever. If -you send a bug report, and I send you a reply, and then you just send -back ``No, it's not! Moron!'', I will have no idea what you are -insulting me about. Always over-explain everything. It's much easier -for all of us---if I don't have all the information I need, I will just -mail you and ask for more info, and everything takes more time. - -If the problem you're seeing is very visual, and you can't quite explain -it, copy the Emacs window to a file (with @code{xwd}, for instance), put -it somewhere it can be reached, and include the URL of the picture in -the bug report. - -@cindex patches -If you would like to contribute a patch to fix bugs or make -improvements, please produce the patch using @samp{diff -u}. - -@cindex edebug -If you want to debug your problem further before reporting, possibly -in order to solve the problem yourself and send a patch, you can use -edebug. Debugging Lisp code is documented in the Elisp manual -(@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs -Lisp Reference Manual}). To get you started with edebug, consider if -you discover some weird behavior when pressing @kbd{c}, the first -step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in -the documentation buffer that leads you to the function definition, -then press @kbd{M-x edebug-defun RET} with point inside that function, -return to Gnus and press @kbd{c} to invoke the code. You will be -placed in the lisp buffer and can single step using @kbd{SPC} and -evaluate expressions using @kbd{M-:} or inspect variables using -@kbd{C-h v}, abort execution with @kbd{q}, and resume execution with -@kbd{c} or @kbd{g}. - -@cindex elp -@cindex profile -@cindex slow -Sometimes, a problem do not directly generate an elisp error but -manifests itself by causing Gnus to be very slow. In these cases, you -can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are -slow, and then try to analyze the backtrace (repeating the procedure -helps isolating the real problem areas). - -A fancier approach is to use the elisp profiler, ELP. The profiler is -(or should be) fully documented elsewhere, but to get you started -there are a few steps that need to be followed. First, instrument the -part of Gnus you are interested in for profiling, e.g. @kbd{M-x -elp-instrument-package RET gnus} or @kbd{M-x elp-instrument-package -RET message}. Then perform the operation that is slow and press -@kbd{M-x elp-results}. You will then see which operations that takes -time, and can debug them further. If the entire operation takes much -longer than the time spent in the slowest function in the profiler -output, you probably profiled the wrong part of Gnus. To reset -profiling statistics, use @kbd{M-x elp-reset-all}. @kbd{M-x -elp-restore-all} is supposed to remove profiling, but given the -complexities and dynamic code generation in Gnus, it might not always -work perfectly. - -@cindex gnu.emacs.gnus -@cindex ding mailing list -If you just need help, you are better off asking on -@samp{gnu.emacs.gnus}. I'm not very helpful. You can also ask on -@email{ding@@gnus.org, the ding mailing list}. Write to -@email{ding-request@@gnus.org} to subscribe. - - -@page -@node Gnus Reference Guide -@section Gnus Reference Guide - -It is my hope that other people will figure out smart stuff that Gnus -can do, and that other people will write those smart things as well. To -facilitate that I thought it would be a good idea to describe the inner -workings of Gnus. And some of the not-so-inner workings, while I'm at -it. - -You can never expect the internals of a program not to change, but I -will be defining (in some details) the interface between Gnus and its -back ends (this is written in stone), the format of the score files -(ditto), data structures (some are less likely to change than others) -and general methods of operation. - -@menu -* Gnus Utility Functions:: Common functions and variable to use. -* Back End Interface:: How Gnus communicates with the servers. -* Score File Syntax:: A BNF definition of the score file standard. -* Headers:: How Gnus stores headers internally. -* Ranges:: A handy format for storing mucho numbers. -* Group Info:: The group info format. -* Extended Interactive:: Symbolic prefixes and stuff. -* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. -* Various File Formats:: Formats of files that Gnus use. -@end menu - - -@node Gnus Utility Functions -@subsection Gnus Utility Functions -@cindex Gnus utility functions -@cindex utility functions -@cindex functions -@cindex internal variables - -When writing small functions to be run from hooks (and stuff), it's -vital to have access to the Gnus internal functions and variables. -Below is a list of the most common ones. - -@table @code - -@item gnus-newsgroup-name -@vindex gnus-newsgroup-name -This variable holds the name of the current newsgroup. - -@item gnus-find-method-for-group -@findex gnus-find-method-for-group -A function that returns the select method for @var{group}. - -@item gnus-group-real-name -@findex gnus-group-real-name -Takes a full (prefixed) Gnus group name, and returns the unprefixed -name. - -@item gnus-group-prefixed-name -@findex gnus-group-prefixed-name -Takes an unprefixed group name and a select method, and returns the full -(prefixed) Gnus group name. - -@item gnus-get-info -@findex gnus-get-info -Returns the group info list for @var{group}. - -@item gnus-group-unread -@findex gnus-group-unread -The number of unread articles in @var{group}, or @code{t} if that is -unknown. - -@item gnus-active -@findex gnus-active -The active entry for @var{group}. - -@item gnus-set-active -@findex gnus-set-active -Set the active entry for @var{group}. - -@item gnus-add-current-to-buffer-list -@findex gnus-add-current-to-buffer-list -Adds the current buffer to the list of buffers to be killed on Gnus -exit. - -@item gnus-continuum-version -@findex gnus-continuum-version -Takes a Gnus version string as a parameter and returns a floating point -number. Earlier versions will always get a lower number than later -versions. - -@item gnus-group-read-only-p -@findex gnus-group-read-only-p -Says whether @var{group} is read-only or not. - -@item gnus-news-group-p -@findex gnus-news-group-p -Says whether @var{group} came from a news back end. - -@item gnus-ephemeral-group-p -@findex gnus-ephemeral-group-p -Says whether @var{group} is ephemeral or not. - -@item gnus-server-to-method -@findex gnus-server-to-method -Returns the select method corresponding to @var{server}. - -@item gnus-server-equal -@findex gnus-server-equal -Says whether two virtual servers are equal. - -@item gnus-group-native-p -@findex gnus-group-native-p -Says whether @var{group} is native or not. - -@item gnus-group-secondary-p -@findex gnus-group-secondary-p -Says whether @var{group} is secondary or not. - -@item gnus-group-foreign-p -@findex gnus-group-foreign-p -Says whether @var{group} is foreign or not. - -@item gnus-group-find-parameter -@findex gnus-group-find-parameter -Returns the parameter list of @var{group}. If given a second parameter, -returns the value of that parameter for @var{group}. - -@item gnus-group-set-parameter -@findex gnus-group-set-parameter -Takes three parameters; @var{group}, @var{parameter} and @var{value}. - -@item gnus-narrow-to-body -@findex gnus-narrow-to-body -Narrows the current buffer to the body of the article. - -@item gnus-check-backend-function -@findex gnus-check-backend-function -Takes two parameters, @var{function} and @var{group}. If the back end -@var{group} comes from supports @var{function}, return non-@code{nil}. - -@lisp -(gnus-check-backend-function "request-scan" "nnml:misc") -@result{} t -@end lisp - -@item gnus-read-method -@findex gnus-read-method -Prompts the user for a select method. - -@end table - - -@node Back End Interface -@subsection Back End Interface - -Gnus doesn't know anything about @acronym{NNTP}, spools, mail or virtual -groups. It only knows how to talk to @dfn{virtual servers}. A virtual -server is a @dfn{back end} and some @dfn{back end variables}. As examples -of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As -examples of the latter we have @code{nntp-port-number} and -@code{nnmbox-directory}. - -When Gnus asks for information from a back end---say @code{nntp}---on -something, it will normally include a virtual server name in the -function parameters. (If not, the back end should use the ``current'' -virtual server.) For instance, @code{nntp-request-list} takes a virtual -server as its only (optional) parameter. If this virtual server hasn't -been opened, the function should fail. - -Note that a virtual server name has no relation to some physical server -name. Take this example: - -@lisp -(nntp "odd-one" - (nntp-address "ifi.uio.no") - (nntp-port-number 4324)) -@end lisp - -Here the virtual server name is @samp{odd-one} while the name of -the physical server is @samp{ifi.uio.no}. - -The back ends should be able to switch between several virtual servers. -The standard back ends implement this by keeping an alist of virtual -server environments that they pull down/push up when needed. - -There are two groups of interface functions: @dfn{required functions}, -which must be present, and @dfn{optional functions}, which Gnus will -always check for presence before attempting to call 'em. - -All these functions are expected to return data in the buffer -@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat -unfortunately named, but we'll have to live with it. When I talk about -@dfn{resulting data}, I always refer to the data in that buffer. When I -talk about @dfn{return value}, I talk about the function value returned by -the function call. Functions that fail should return @code{nil} as the -return value. - -Some back ends could be said to be @dfn{server-forming} back ends, and -some might be said not to be. The latter are back ends that generally -only operate on one group at a time, and have no concept of ``server'' ----they have a group, and they deliver info on that group and nothing -more. - -Gnus identifies each message by way of group name and article number. A -few remarks about these article numbers might be useful. First of all, -the numbers are positive integers. Secondly, it is normally not -possible for later articles to ``re-use'' older article numbers without -confusing Gnus. That is, if a group has ever contained a message -numbered 42, then no other message may get that number, or Gnus will get -mightily confused.@footnote{See the function -@code{nnchoke-request-update-info}, @ref{Optional Back End Functions}.} -Third, article numbers must be assigned in order of arrival in the -group; this is not necessarily the same as the date of the message. - -The previous paragraph already mentions all the ``hard'' restrictions that -article numbers must fulfill. But it seems that it might be useful to -assign @emph{consecutive} article numbers, for Gnus gets quite confused -if there are holes in the article numbering sequence. However, due to -the ``no-reuse'' restriction, holes cannot be avoided altogether. It's -also useful for the article numbers to start at 1 to avoid running out -of numbers as long as possible. - -Note that by convention, back ends are named @code{nnsomething}, but -Gnus also comes with some @code{nnnotbackends}, such as -@file{nnheader.el}, @file{nnmail.el} and @file{nnoo.el}. - -In the examples and definitions I will refer to the imaginary back end -@code{nnchoke}. - -@cindex @code{nnchoke} - -@menu -* Required Back End Functions:: Functions that must be implemented. -* Optional Back End Functions:: Functions that need not be implemented. -* Error Messaging:: How to get messages and report errors. -* Writing New Back Ends:: Extending old back ends. -* Hooking New Back Ends Into Gnus:: What has to be done on the Gnus end. -* Mail-like Back Ends:: Some tips on mail back ends. -@end menu - - -@node Required Back End Functions -@subsubsection Required Back End Functions - -@table @code - -@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) - -@var{articles} is either a range of article numbers or a list of -@code{Message-ID}s. Current back ends do not fully support either---only -sequences (lists) of article numbers, and most back ends do not support -retrieval of @code{Message-ID}s. But they should try for both. - -The result data should either be HEADs or @acronym{NOV} lines, and the result -value should either be @code{headers} or @code{nov} to reflect this. -This might later be expanded to @code{various}, which will be a mixture -of HEADs and @acronym{NOV} lines, but this is currently not supported by Gnus. - -If @var{fetch-old} is non-@code{nil} it says to try fetching ``extra -headers'', in some meaning of the word. This is generally done by -fetching (at most) @var{fetch-old} extra headers less than the smallest -article number in @code{articles}, and filling the gaps as well. The -presence of this parameter can be ignored if the back end finds it -cumbersome to follow the request. If this is non-@code{nil} and not a -number, do maximum fetches. - -Here's an example HEAD: - -@example -221 1056 Article retrieved. -Path: ifi.uio.no!sturles -From: sturles@@ifi.uio.no (Sturle Sunde) -Newsgroups: ifi.discussion -Subject: Re: Something very droll -Date: 27 Oct 1994 14:02:57 +0100 -Organization: Dept. of Informatics, University of Oslo, Norway -Lines: 26 -Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> -References: <38jdmq$4qu@@visbur.ifi.uio.no> -NNTP-Posting-Host: holmenkollen.ifi.uio.no -. -@end example - -So a @code{headers} return value would imply that there's a number of -these in the data buffer. - -Here's a BNF definition of such a buffer: - -@example -headers = *head -head = error / valid-head -error-message = [ "4" / "5" ] 2number " " eol -valid-head = valid-message *header "." eol -valid-message = "221 " " Article retrieved." eol -header = eol -@end example - -@cindex BNF -(The version of BNF used here is the one used in RFC822.) - -If the return value is @code{nov}, the data buffer should contain -@dfn{network overview database} lines. These are basically fields -separated by tabs. - -@example -nov-buffer = *nov-line -nov-line = field 7*8[ field ] eol -field = -@end example - -For a closer look at what should be in those fields, -@pxref{Headers}. - - -@item (nnchoke-open-server SERVER &optional DEFINITIONS) - -@var{server} is here the virtual server name. @var{definitions} is a -list of @code{(VARIABLE VALUE)} pairs that define this virtual server. - -If the server can't be opened, no error should be signaled. The back end -may then choose to refuse further attempts at connecting to this -server. In fact, it should do so. - -If the server is opened already, this function should return a -non-@code{nil} value. There should be no data returned. - - -@item (nnchoke-close-server &optional SERVER) - -Close connection to @var{server} and free all resources connected -to it. Return @code{nil} if the server couldn't be closed for some -reason. - -There should be no data returned. - - -@item (nnchoke-request-close) - -Close connection to all servers and free all resources that the back end -have reserved. All buffers that have been created by that back end -should be killed. (Not the @code{nntp-server-buffer}, though.) This -function is generally only called when Gnus is shutting down. - -There should be no data returned. - - -@item (nnchoke-server-opened &optional SERVER) - -If @var{server} is the current virtual server, and the connection to the -physical server is alive, then this function should return a -non-@code{nil} value. This function should under no circumstances -attempt to reconnect to a server we have lost connection to. - -There should be no data returned. - - -@item (nnchoke-status-message &optional SERVER) - -This function should return the last error message from @var{server}. - -There should be no data returned. - - -@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) - -The result data from this function should be the article specified by -@var{article}. This might either be a @code{Message-ID} or a number. -It is optional whether to implement retrieval by @code{Message-ID}, but -it would be nice if that were possible. - -If @var{to-buffer} is non-@code{nil}, the result data should be returned -in this buffer instead of the normal data buffer. This is to make it -possible to avoid copying large amounts of data from one buffer to -another, while Gnus mainly requests articles to be inserted directly -into its article buffer. - -If it is at all possible, this function should return a cons cell where -the @code{car} is the group name the article was fetched from, and the @code{cdr} is -the article number. This will enable Gnus to find out what the real -group and article numbers are when fetching articles by -@code{Message-ID}. If this isn't possible, @code{t} should be returned -on successful article retrieval. - - -@item (nnchoke-request-group GROUP &optional SERVER FAST) - -Get data on @var{group}. This function also has the side effect of -making @var{group} the current group. - -If @var{fast}, don't bother to return useful data, just make @var{group} -the current group. - -Here's an example of some result data and a definition of the same: - -@example -211 56 1000 1059 ifi.discussion -@end example - -The first number is the status, which should be 211. Next is the -total number of articles in the group, the lowest article number, the -highest article number, and finally the group name. Note that the total -number of articles may be less than one might think while just -considering the highest and lowest article numbers, but some articles -may have been canceled. Gnus just discards the total-number, so -whether one should take the bother to generate it properly (if that is a -problem) is left as an exercise to the reader. If the group contains no -articles, the lowest article number should be reported as 1 and the -highest as 0. - -@example -group-status = [ error / info ] eol -error = [ "4" / "5" ] 2 " " -info = "211 " 3* [ " " ] -@end example - - -@item (nnchoke-close-group GROUP &optional SERVER) - -Close @var{group} and free any resources connected to it. This will be -a no-op on most back ends. - -There should be no data returned. - - -@item (nnchoke-request-list &optional SERVER) - -Return a list of all groups available on @var{server}. And that means -@emph{all}. - -Here's an example from a server that only carries two groups: - -@example -ifi.test 0000002200 0000002000 y -ifi.discussion 3324 3300 n -@end example - -On each line we have a group name, then the highest article number in -that group, the lowest article number, and finally a flag. If the group -contains no articles, the lowest article number should be reported as 1 -and the highest as 0. - -@example -active-file = *active-line -active-line = name " " " " " " flags eol -name = -flags = "n" / "y" / "m" / "x" / "j" / "=" name -@end example - -The flag says whether the group is read-only (@samp{n}), is moderated -(@samp{m}), is dead (@samp{x}), is aliased to some other group -(@samp{=other-group}) or none of the above (@samp{y}). - - -@item (nnchoke-request-post &optional SERVER) - -This function should post the current buffer. It might return whether -the posting was successful or not, but that's not required. If, for -instance, the posting is done asynchronously, it has generally not been -completed by the time this function concludes. In that case, this -function should set up some kind of sentinel to beep the user loud and -clear if the posting could not be completed. - -There should be no result data from this function. - -@end table - - -@node Optional Back End Functions -@subsubsection Optional Back End Functions - -@table @code - -@item (nnchoke-retrieve-groups GROUPS &optional SERVER) - -@var{groups} is a list of groups, and this function should request data -on all those groups. How it does it is of no concern to Gnus, but it -should attempt to do this in a speedy fashion. - -The return value of this function can be either @code{active} or -@code{group}, which says what the format of the result data is. The -former is in the same format as the data from -@code{nnchoke-request-list}, while the latter is a buffer full of lines -in the same format as @code{nnchoke-request-group} gives. - -@example -group-buffer = *active-line / *group-status -@end example - - -@item (nnchoke-request-update-info GROUP INFO &optional SERVER) - -A Gnus group info (@pxref{Group Info}) is handed to the back end for -alterations. This comes in handy if the back end really carries all -the information (as is the case with virtual and imap groups). This -function should destructively alter the info to suit its needs, and -should return a non-@code{nil} value (exceptionally, -@code{nntp-request-update-info} always returns @code{nil} not to waste -the network resources). - -There should be no result data from this function. - - -@item (nnchoke-request-type GROUP &optional ARTICLE) - -When the user issues commands for ``sending news'' (@kbd{F} in the -summary buffer, for instance), Gnus has to know whether the article the -user is following up on is news or mail. This function should return -@code{news} if @var{article} in @var{group} is news, @code{mail} if it -is mail and @code{unknown} if the type can't be decided. (The -@var{article} parameter is necessary in @code{nnvirtual} groups which -might very well combine mail groups and news groups.) Both @var{group} -and @var{article} may be @code{nil}. - -There should be no result data from this function. - - -@item (nnchoke-request-set-mark GROUP ACTION &optional SERVER) - -Set/remove/add marks on articles. Normally Gnus handles the article -marks (such as read, ticked, expired etc) internally, and store them in -@file{~/.newsrc.eld}. Some back ends (such as @acronym{IMAP}) however carry -all information about the articles on the server, so Gnus need to -propagate the mark information to the server. - -@var{action} is a list of mark setting requests, having this format: - -@example -(RANGE ACTION MARK) -@end example - -@var{range} is a range of articles you wish to update marks on. -@var{action} is @code{add} or @code{del}, used to add marks or remove -marks (preserving all marks not mentioned). @var{mark} is a list of -marks; where each mark is a symbol. Currently used marks are -@code{read}, @code{tick}, @code{reply}, @code{expire}, @code{killed}, -@code{dormant}, @code{save}, @code{download}, @code{unsend}, -@code{forward} and @code{recent}, but your back end should, if -possible, not limit itself to these. - -Given contradictory actions, the last action in the list should be the -effective one. That is, if your action contains a request to add the -@code{tick} mark on article 1 and, later in the list, a request to -remove the mark on the same article, the mark should in fact be removed. - -An example action list: - -@example -(((5 12 30) 'del '(tick)) - ((10 . 90) 'add '(read expire)) - ((92 94) 'del '(read))) -@end example - -The function should return a range of articles it wasn't able to set the -mark on (currently not used for anything). - -There should be no result data from this function. - -@item (nnchoke-request-update-mark GROUP ARTICLE MARK) - -If the user tries to set a mark that the back end doesn't like, this -function may change the mark. Gnus will use whatever this function -returns as the mark for @var{article} instead of the original -@var{mark}. If the back end doesn't care, it must return the original -@var{mark}, and not @code{nil} or any other type of garbage. - -The only use for this I can see is what @code{nnvirtual} does with -it---if a component group is auto-expirable, marking an article as read -in the virtual group should result in the article being marked as -expirable. - -There should be no result data from this function. - - -@item (nnchoke-request-scan &optional GROUP SERVER) - -This function may be called at any time (by Gnus or anything else) to -request that the back end check for incoming articles, in one way or -another. A mail back end will typically read the spool file or query -the @acronym{POP} server when this function is invoked. The -@var{group} doesn't have to be heeded---if the back end decides that -it is too much work just scanning for a single group, it may do a -total scan of all groups. It would be nice, however, to keep things -local if that's practical. - -There should be no result data from this function. - - -@item (nnchoke-request-group-description GROUP &optional SERVER) - -The result data from this function should be a description of -@var{group}. - -@example -description-line = name description eol -name = -description = -@end example - -@item (nnchoke-request-list-newsgroups &optional SERVER) - -The result data from this function should be the description of all -groups available on the server. - -@example -description-buffer = *description-line -@end example - - -@item (nnchoke-request-newgroups DATE &optional SERVER) - -The result data from this function should be all groups that were -created after @samp{date}, which is in normal human-readable date format -(i.e., the date format used in mail and news headers, and returned by -the function @code{message-make-date} by default). The data should be -in the active buffer format. - -It is okay for this function to return ``too many'' groups; some back ends -might find it cheaper to return the full list of groups, rather than -just the new groups. But don't do this for back ends with many groups. -Normally, if the user creates the groups herself, there won't be too -many groups, so @code{nnml} and the like are probably safe. But for -back ends like @code{nntp}, where the groups have been created by the -server, it is quite likely that there can be many groups. - - -@item (nnchoke-request-create-group GROUP &optional SERVER) - -This function should create an empty group with name @var{group}. - -There should be no return data. - - -@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) - -This function should run the expiry process on all articles in the -@var{articles} range (which is currently a simple list of article -numbers.) It is left up to the back end to decide how old articles -should be before they are removed by this function. If @var{force} is -non-@code{nil}, all @var{articles} should be deleted, no matter how new -they are. - -This function should return a list of articles that it did not/was not -able to delete. - -There should be no result data returned. - - -@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM &optional LAST) - -This function should move @var{article} (which is a number) from -@var{group} by calling @var{accept-form}. - -This function should ready the article in question for moving by -removing any header lines it has added to the article, and generally -should ``tidy up'' the article. Then it should @code{eval} -@var{accept-form} in the buffer where the ``tidy'' article is. This -will do the actual copying. If this @code{eval} returns a -non-@code{nil} value, the article should be removed. - -If @var{last} is @code{nil}, that means that there is a high likelihood -that there will be more requests issued shortly, so that allows some -optimizations. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -There should be no data returned. - - -@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) - -This function takes the current buffer and inserts it into @var{group}. -If @var{last} in @code{nil}, that means that there will be more calls to -this function in short order. - -The function should return a cons where the @code{car} is the group name and -the @code{cdr} is the article number that the article was entered as. - -The group should exist before the back end is asked to accept the -article for that group. - -There should be no data returned. - - -@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) - -This function should remove @var{article} (which is a number) from -@var{group} and insert @var{buffer} there instead. - -There should be no data returned. - - -@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) - -This function should delete @var{group}. If @var{force}, it should -really delete all the articles in the group, and then delete the group -itself. (If there is such a thing as ``the group itself''.) - -There should be no data returned. - - -@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) - -This function should rename @var{group} into @var{new-name}. All -articles in @var{group} should move to @var{new-name}. - -There should be no data returned. - -@end table - - -@node Error Messaging -@subsubsection Error Messaging - -@findex nnheader-report -@findex nnheader-get-report -The back ends should use the function @code{nnheader-report} to report -error conditions---they should not raise errors when they aren't able to -perform a request. The first argument to this function is the back end -symbol, and the rest are interpreted as arguments to @code{format} if -there are multiple of them, or just a string if there is one of them. -This function must always returns @code{nil}. - -@lisp -(nnheader-report 'nnchoke "You did something totally bogus") - -(nnheader-report 'nnchoke "Could not request group %s" group) -@end lisp - -Gnus, in turn, will call @code{nnheader-get-report} when it gets a -@code{nil} back from a server, and this function returns the most -recently reported message for the back end in question. This function -takes one argument---the server symbol. - -Internally, these functions access @var{back-end}@code{-status-string}, -so the @code{nnchoke} back end will have its error message stored in -@code{nnchoke-status-string}. - - -@node Writing New Back Ends -@subsubsection Writing New Back Ends - -Many back ends are quite similar. @code{nnml} is just like -@code{nnspool}, but it allows you to edit the articles on the server. -@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, -and it doesn't maintain overview databases. @code{nndir} is just like -@code{nnml}, but it has no concept of ``groups'', and it doesn't allow -editing articles. - -It would make sense if it were possible to ``inherit'' functions from -back ends when writing new back ends. And, indeed, you can do that if you -want to. (You don't have to if you don't want to, of course.) - -All the back ends declare their public variables and functions by using a -package called @code{nnoo}. - -To inherit functions from other back ends (and allow other back ends to -inherit functions from the current back end), you should use the -following macros: - -@table @code - -@item nnoo-declare -This macro declares the first parameter to be a child of the subsequent -parameters. For instance: - -@lisp -(nnoo-declare nndir - nnml nnmh) -@end lisp - -@code{nndir} has declared here that it intends to inherit functions from -both @code{nnml} and @code{nnmh}. - -@item defvoo -This macro is equivalent to @code{defvar}, but registers the variable as -a public server variable. Most state-oriented variables should be -declared with @code{defvoo} instead of @code{defvar}. - -In addition to the normal @code{defvar} parameters, it takes a list of -variables in the parent back ends to map the variable to when executing -a function in those back ends. - -@lisp -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) -@end lisp - -This means that @code{nnml-current-directory} will be set to -@code{nndir-directory} when an @code{nnml} function is called on behalf -of @code{nndir}. (The same with @code{nnmh}.) - -@item nnoo-define-basics -This macro defines some common functions that almost all back ends should -have. - -@lisp -(nnoo-define-basics nndir) -@end lisp - -@item deffoo -This macro is just like @code{defun} and takes the same parameters. In -addition to doing the normal @code{defun} things, it registers the -function as being public so that other back ends can inherit it. - -@item nnoo-map-functions -This macro allows mapping of functions from the current back end to -functions from the parent back ends. - -@lisp -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0)) -@end lisp - -This means that when @code{nndir-retrieve-headers} is called, the first, -third, and fourth parameters will be passed on to -@code{nnml-retrieve-headers}, while the second parameter is set to the -value of @code{nndir-current-group}. - -@item nnoo-import -This macro allows importing functions from back ends. It should be the -last thing in the source file, since it will only define functions that -haven't already been defined. - -@lisp -(nnoo-import nndir - (nnmh - nnmh-request-list - nnmh-request-newgroups) - (nnml)) -@end lisp - -This means that calls to @code{nndir-request-list} should just be passed -on to @code{nnmh-request-list}, while all public functions from -@code{nnml} that haven't been defined in @code{nndir} yet should be -defined now. - -@end table - -Below is a slightly shortened version of the @code{nndir} back end. - -@lisp -;;; @r{nndir.el --- single directory newsgroup access for Gnus} -;; @r{Copyright (C) 1995,1996 Free Software Foundation, Inc.} - -;;; @r{Code:} - -(require 'nnheader) -(require 'nnmh) -(require 'nnml) -(require 'nnoo) -(eval-when-compile (require 'cl)) - -(nnoo-declare nndir - nnml nnmh) - -(defvoo nndir-directory nil - "Where nndir will look for groups." - nnml-current-directory nnmh-current-directory) - -(defvoo nndir-nov-is-evil nil - "*Non-nil means that nndir will never retrieve NOV headers." - nnml-nov-is-evil) - -(defvoo nndir-current-group "" - nil - nnml-current-group nnmh-current-group) -(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) -(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) - -(defvoo nndir-status-string "" nil nnmh-status-string) -(defconst nndir-version "nndir 1.0") - -;;; @r{Interface functions.} - -(nnoo-define-basics nndir) - -(deffoo nndir-open-server (server &optional defs) - (setq nndir-directory - (or (cadr (assq 'nndir-directory defs)) - server)) - (unless (assq 'nndir-directory defs) - (push `(nndir-directory ,server) defs)) - (push `(nndir-current-group - ,(file-name-nondirectory - (directory-file-name nndir-directory))) - defs) - (push `(nndir-top-directory - ,(file-name-directory (directory-file-name nndir-directory))) - defs) - (nnoo-change-server 'nndir server defs)) - -(nnoo-map-functions nndir - (nnml-retrieve-headers 0 nndir-current-group 0 0) - (nnmh-request-article 0 nndir-current-group 0 0) - (nnmh-request-group nndir-current-group 0 0) - (nnmh-close-group nndir-current-group 0)) - -(nnoo-import nndir - (nnmh - nnmh-status-message - nnmh-request-list - nnmh-request-newgroups)) - -(provide 'nndir) -@end lisp - - -@node Hooking New Back Ends Into Gnus -@subsubsection Hooking New Back Ends Into Gnus - -@vindex gnus-valid-select-methods -@findex gnus-declare-backend -Having Gnus start using your new back end is rather easy---you just -declare it with the @code{gnus-declare-backend} functions. This will -enter the back end into the @code{gnus-valid-select-methods} variable. - -@code{gnus-declare-backend} takes two parameters---the back end name and -an arbitrary number of @dfn{abilities}. - -Here's an example: - -@lisp -(gnus-declare-backend "nnchoke" 'mail 'respool 'address) -@end lisp - -The above line would then go in the @file{nnchoke.el} file. - -The abilities can be: - -@table @code -@item mail -This is a mailish back end---followups should (probably) go via mail. -@item post -This is a newsish back end---followups should (probably) go via news. -@item post-mail -This back end supports both mail and news. -@item none -This is neither a post nor mail back end---it's something completely -different. -@item respool -It supports respooling---or rather, it is able to modify its source -articles and groups. -@item address -The name of the server should be in the virtual server name. This is -true for almost all back ends. -@item prompt-address -The user should be prompted for an address when doing commands like -@kbd{B} in the group buffer. This is true for back ends like -@code{nntp}, but not @code{nnmbox}, for instance. -@end table - - -@node Mail-like Back Ends -@subsubsection Mail-like Back Ends - -One of the things that separate the mail back ends from the rest of the -back ends is the heavy dependence by most of the mail back ends on -common functions in @file{nnmail.el}. For instance, here's the -definition of @code{nnml-request-scan}: - -@lisp -(deffoo nnml-request-scan (&optional group server) - (setq nnml-article-file-alist nil) - (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) -@end lisp - -It simply calls @code{nnmail-get-new-mail} with a few parameters, -and @code{nnmail} takes care of all the moving and splitting of the -mail. - -This function takes four parameters. - -@table @var -@item method -This should be a symbol to designate which back end is responsible for -the call. - -@item exit-function -This function should be called after the splitting has been performed. - -@item temp-directory -Where the temporary files should be stored. - -@item group -This optional argument should be a group name if the splitting is to be -performed for one group only. -@end table - -@code{nnmail-get-new-mail} will call @var{back-end}@code{-save-mail} to -save each article. @var{back-end}@code{-active-number} will be called to -find the article number assigned to this article. - -The function also uses the following variables: -@var{back-end}@code{-get-new-mail} (to see whether to get new mail for -this back end); and @var{back-end}@code{-group-alist} and -@var{back-end}@code{-active-file} to generate the new active file. -@var{back-end}@code{-group-alist} should be a group-active alist, like -this: - -@example -(("a-group" (1 . 10)) - ("some-group" (34 . 39))) -@end example - - -@node Score File Syntax -@subsection Score File Syntax - -Score files are meant to be easily parseable, but yet extremely -mallable. It was decided that something that had the same read syntax -as an Emacs Lisp list would fit that spec. - -Here's a typical score file: - -@lisp -(("summary" - ("win95" -10000 nil s) - ("Gnus")) - ("from" - ("Lars" -1000)) - (mark -100)) -@end lisp - -BNF definition of a score file: - -@example -score-file = "" / "(" *element ")" -element = rule / atom -rule = string-rule / number-rule / date-rule -string-rule = "(" quote string-header quote space *string-match ")" -number-rule = "(" quote number-header quote space *number-match ")" -date-rule = "(" quote date-header quote space *date-match ")" -quote = -string-header = "subject" / "from" / "references" / "message-id" / - "xref" / "body" / "head" / "all" / "followup" -number-header = "lines" / "chars" -date-header = "date" -string-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space string-match-t ] ] ] ] ] ")" -score = "nil" / -date = "nil" / -string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / - "r" / "regex" / "R" / "Regex" / - "e" / "exact" / "E" / "Exact" / - "f" / "fuzzy" / "F" / "Fuzzy" -number-match = "(" [ "" / [ space score [ "" / - space date [ "" / [ space number-match-t ] ] ] ] ] ")" -number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" -date-match = "(" quote quote [ "" / [ space score [ "" / - space date [ "" / [ space date-match-t ] ] ] ] ")" -date-match-t = "nil" / "at" / "before" / "after" -atom = "(" [ required-atom / optional-atom ] ")" -required-atom = mark / expunge / mark-and-expunge / files / - exclude-files / read-only / touched -optional-atom = adapt / local / eval -mark = "mark" space nil-or-number -nil-or-number = "nil" / -expunge = "expunge" space nil-or-number -mark-and-expunge = "mark-and-expunge" space nil-or-number -files = "files" *[ space ] -exclude-files = "exclude-files" *[ space ] -read-only = "read-only" [ space "nil" / space "t" ] -adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] -adapt-rule = "(" *[ *[ "(" ")" ] ")" -local = "local" *[ space "(" space
")" ] -eval = "eval" space -space = *[ " " / / ] -@end example - -Any unrecognized elements in a score file should be ignored, but not -discarded. - -As you can see, white space is needed, but the type and amount of white -space is irrelevant. This means that formatting of the score file is -left up to the programmer---if it's simpler to just spew it all out on -one looong line, then that's ok. - -The meaning of the various atoms are explained elsewhere in this -manual (@pxref{Score File Format}). - - -@node Headers -@subsection Headers - -Internally Gnus uses a format for storing article headers that -corresponds to the @acronym{NOV} format in a mysterious fashion. One could -almost suspect that the author looked at the @acronym{NOV} specification and -just shamelessly @emph{stole} the entire thing, and one would be right. - -@dfn{Header} is a severely overloaded term. ``Header'' is used in -RFC 1036 to talk about lines in the head of an article (e.g., -@code{From}). It is used by many people as a synonym for -``head''---``the header and the body''. (That should be avoided, in my -opinion.) And Gnus uses a format internally that it calls ``header'', -which is what I'm talking about here. This is a 9-element vector, -basically, with each header (ouch) having one slot. - -These slots are, in order: @code{number}, @code{subject}, @code{from}, -@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, -@code{xref}, and @code{extra}. There are macros for accessing and -setting these slots---they all have predictable names beginning with -@code{mail-header-} and @code{mail-header-set-}, respectively. - -All these slots contain strings, except the @code{extra} slot, which -contains an alist of header/value pairs (@pxref{To From Newsgroups}). - - -@node Ranges -@subsection Ranges - -@sc{gnus} introduced a concept that I found so useful that I've started -using it a lot and have elaborated on it greatly. - -The question is simple: If you have a large amount of objects that are -identified by numbers (say, articles, to take a @emph{wild} example) -that you want to qualify as being ``included'', a normal sequence isn't -very useful. (A 200,000 length sequence is a bit long-winded.) - -The solution is as simple as the question: You just collapse the -sequence. - -@example -(1 2 3 4 5 6 10 11 12) -@end example - -is transformed into - -@example -((1 . 6) (10 . 12)) -@end example - -To avoid having those nasty @samp{(13 . 13)} elements to denote a -lonesome object, a @samp{13} is a valid element: - -@example -((1 . 6) 7 (10 . 12)) -@end example - -This means that comparing two ranges to find out whether they are equal -is slightly tricky: - -@example -((1 . 5) 7 8 (10 . 12)) -@end example - -and - -@example -((1 . 5) (7 . 8) (10 . 12)) -@end example - -are equal. In fact, any non-descending list is a range: - -@example -(1 2 3 4 5) -@end example - -is a perfectly valid range, although a pretty long-winded one. This is -also valid: - -@example -(1 . 5) -@end example - -and is equal to the previous range. - -Here's a BNF definition of ranges. Of course, one must remember the -semantic requirement that the numbers are non-descending. (Any number -of repetition of the same number is allowed, but apt to disappear in -range handling.) - -@example -range = simple-range / normal-range -simple-range = "(" number " . " number ")" -normal-range = "(" start-contents ")" -contents = "" / simple-range *[ " " contents ] / - number *[ " " contents ] -@end example - -Gnus currently uses ranges to keep track of read articles and article -marks. I plan on implementing a number of range operators in C if The -Powers That Be are willing to let me. (I haven't asked yet, because I -need to do some more thinking on what operators I need to make life -totally range-based without ever having to convert back to normal -sequences.) - - -@node Group Info -@subsection Group Info - -Gnus stores all permanent info on groups in a @dfn{group info} list. -This list is from three to six elements (or more) long and exhaustively -describes the group. - -Here are two example group infos; one is a very simple group while the -second is a more complex one: - -@example -("no.group" 5 ((1 . 54324))) - -("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) - ((tick (15 . 19)) (replied 3 6 (19 . 3))) - (nnml "") - ((auto-expire . t) (to-address . "ding@@gnus.org"))) -@end example - -The first element is the @dfn{group name}---as Gnus knows the group, -anyway. The second element is the @dfn{subscription level}, which -normally is a small integer. (It can also be the @dfn{rank}, which is a -cons cell where the @code{car} is the level and the @code{cdr} is the -score.) The third element is a list of ranges of read articles. The -fourth element is a list of lists of article marks of various kinds. -The fifth element is the select method (or virtual server, if you like). -The sixth element is a list of @dfn{group parameters}, which is what -this section is about. - -Any of the last three elements may be missing if they are not required. -In fact, the vast majority of groups will normally only have the first -three elements, which saves quite a lot of cons cells. - -Here's a BNF definition of the group info format: - -@example -info = "(" group space ralevel space read - [ "" / [ space marks-list [ "" / [ space method [ "" / - space parameters ] ] ] ] ] ")" -group = quote quote -ralevel = rank / level -level = -rank = "(" level "." score ")" -score = -read = range -marks-lists = nil / "(" *marks ")" -marks = "(" range ")" -method = "(" *elisp-forms ")" -parameters = "(" *elisp-forms ")" -@end example - -Actually that @samp{marks} rule is a fib. A @samp{marks} is a -@samp{} consed on to a @samp{range}, but that's a bitch to say -in pseudo-BNF. - -If you have a Gnus info and want to access the elements, Gnus offers a -series of macros for getting/setting these elements. - -@table @code -@item gnus-info-group -@itemx gnus-info-set-group -@findex gnus-info-group -@findex gnus-info-set-group -Get/set the group name. - -@item gnus-info-rank -@itemx gnus-info-set-rank -@findex gnus-info-rank -@findex gnus-info-set-rank -Get/set the group rank (@pxref{Group Score}). - -@item gnus-info-level -@itemx gnus-info-set-level -@findex gnus-info-level -@findex gnus-info-set-level -Get/set the group level. - -@item gnus-info-score -@itemx gnus-info-set-score -@findex gnus-info-score -@findex gnus-info-set-score -Get/set the group score (@pxref{Group Score}). - -@item gnus-info-read -@itemx gnus-info-set-read -@findex gnus-info-read -@findex gnus-info-set-read -Get/set the ranges of read articles. - -@item gnus-info-marks -@itemx gnus-info-set-marks -@findex gnus-info-marks -@findex gnus-info-set-marks -Get/set the lists of ranges of marked articles. - -@item gnus-info-method -@itemx gnus-info-set-method -@findex gnus-info-method -@findex gnus-info-set-method -Get/set the group select method. - -@item gnus-info-params -@itemx gnus-info-set-params -@findex gnus-info-params -@findex gnus-info-set-params -Get/set the group parameters. -@end table - -All the getter functions take one parameter---the info list. The setter -functions take two parameters---the info list and the new value. - -The last three elements in the group info aren't mandatory, so it may be -necessary to extend the group info before setting the element. If this -is necessary, you can just pass on a non-@code{nil} third parameter to -the three final setter functions to have this happen automatically. - - -@node Extended Interactive -@subsection Extended Interactive -@cindex interactive -@findex gnus-interactive - -Gnus extends the standard Emacs @code{interactive} specification -slightly to allow easy use of the symbolic prefix (@pxref{Symbolic -Prefixes}). Here's an example of how this is used: - -@lisp -(defun gnus-summary-increase-score (&optional score symp) - (interactive (gnus-interactive "P\ny")) - ... - ) -@end lisp - -The best thing to do would have been to implement -@code{gnus-interactive} as a macro which would have returned an -@code{interactive} form, but this isn't possible since Emacs checks -whether a function is interactive or not by simply doing an @code{assq} -on the lambda form. So, instead we have @code{gnus-interactive} -function that takes a string and returns values that are usable to -@code{interactive}. - -This function accepts (almost) all normal @code{interactive} specs, but -adds a few more. - -@table @samp -@item y -@vindex gnus-current-prefix-symbol -The current symbolic prefix---the @code{gnus-current-prefix-symbol} -variable. - -@item Y -@vindex gnus-current-prefix-symbols -A list of the current symbolic prefixes---the -@code{gnus-current-prefix-symbol} variable. - -@item A -The current article number---the @code{gnus-summary-article-number} -function. - -@item H -The current article header---the @code{gnus-summary-article-header} -function. - -@item g -The current group name---the @code{gnus-group-group-name} -function. - -@end table - - -@node Emacs/XEmacs Code -@subsection Emacs/XEmacs Code -@cindex XEmacs -@cindex Emacsen - -While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the -platforms must be the primary one. I chose Emacs. Not because I don't -like XEmacs or Mule, but because it comes first alphabetically. - -This means that Gnus will byte-compile under Emacs with nary a warning, -while XEmacs will pump out gigabytes of warnings while byte-compiling. -As I use byte-compilation warnings to help me root out trivial errors in -Gnus, that's very useful. - -I've also consistently used Emacs function interfaces, but have used -Gnusey aliases for the functions. To take an example: Emacs defines a -@code{run-at-time} function while XEmacs defines a @code{start-itimer} -function. I then define a function called @code{gnus-run-at-time} that -takes the same parameters as the Emacs @code{run-at-time}. When running -Gnus under Emacs, the former function is just an alias for the latter. -However, when running under XEmacs, the former is an alias for the -following function: - -@lisp -(defun gnus-xmas-run-at-time (time repeat function &rest args) - (start-itimer - "gnus-run-at-time" - `(lambda () - (,function ,@@args)) - time repeat)) -@end lisp - -This sort of thing has been done for bunches of functions. Gnus does -not redefine any native Emacs functions while running under XEmacs---it -does this @code{defalias} thing with Gnus equivalents instead. Cleaner -all over. - -In the cases where the XEmacs function interface was obviously cleaner, -I used it instead. For example @code{gnus-region-active-p} is an alias -for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. - -Of course, I could have chosen XEmacs as my native platform and done -mapping functions the other way around. But I didn't. The performance -hit these indirections impose on Gnus under XEmacs should be slight. - - -@node Various File Formats -@subsection Various File Formats - -@menu -* Active File Format:: Information on articles and groups available. -* Newsgroups File Format:: Group descriptions. -@end menu - - -@node Active File Format -@subsubsection Active File Format - -The active file lists all groups available on the server in -question. It also lists the highest and lowest current article numbers -in each group. - -Here's an excerpt from a typical active file: - -@example -soc.motss 296030 293865 y -alt.binaries.pictures.fractals 3922 3913 n -comp.sources.unix 1605 1593 m -comp.binaries.ibm.pc 5097 5089 y -no.general 1000 900 y -@end example - -Here's a pseudo-BNF definition of this file: - -@example -active = *group-line -group-line = group spc high-number spc low-number spc flag -group = -spc = " " -high-number = -low-number = -flag = "y" / "n" / "m" / "j" / "x" / "=" group -@end example - -For a full description of this file, see the manual pages for -@samp{innd}, in particular @samp{active(5)}. - - -@node Newsgroups File Format -@subsubsection Newsgroups File Format - -The newsgroups file lists groups along with their descriptions. Not all -groups on the server have to be listed, and not all groups in the file -have to exist on the server. The file is meant purely as information to -the user. - -The format is quite simple; a group name, a tab, and the description. -Here's the definition: - -@example -newsgroups = *line -line = group tab description -group = -tab = -description = -@end example - - -@page -@node Emacs for Heathens -@section Emacs for Heathens - -Believe it or not, but some people who use Gnus haven't really used -Emacs much before they embarked on their journey on the Gnus Love Boat. -If you are one of those unfortunates whom ``@kbd{C-M-a}'', ``kill the -region'', and ``set @code{gnus-flargblossen} to an alist where the key -is a regexp that is used for matching on the group name'' are magical -phrases with little or no meaning, then this appendix is for you. If -you are already familiar with Emacs, just ignore this and go fondle your -cat instead. - -@menu -* Keystrokes:: Entering text and executing commands. -* Emacs Lisp:: The built-in Emacs programming language. -@end menu - - -@node Keystrokes -@subsection Keystrokes - -@itemize @bullet -@item -Q: What is an experienced Emacs user? - -@item -A: A person who wishes that the terminal had pedals. -@end itemize - -Yes, when you use Emacs, you are apt to use the control key, the shift -key and the meta key a lot. This is very annoying to some people -(notably @code{vi}le users), and the rest of us just love the hell out -of it. Just give up and submit. Emacs really does stand for -``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you -may have heard from other disreputable sources (like the Emacs author). - -The shift keys are normally located near your pinky fingers, and are -normally used to get capital letters and stuff. You probably use it all -the time. The control key is normally marked ``CTRL'' or something like -that. The meta key is, funnily enough, never marked as such on any -keyboard. The one I'm currently at has a key that's marked ``Alt'', -which is the meta key on this keyboard. It's usually located somewhere -to the left hand side of the keyboard, usually on the bottom row. - -Now, us Emacs people don't say ``press the meta-control-m key'', -because that's just too inconvenient. We say ``press the @kbd{C-M-m} -key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the -prefix that means ``control''. So ``press @kbd{C-k}'' means ``press -down the control key, and hold it down while you press @kbd{k}''. -``Press @kbd{C-M-k}'' means ``press down and hold down the meta key and -the control key and then press @kbd{k}''. Simple, ay? - -This is somewhat complicated by the fact that not all keyboards have a -meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} -means ``press escape, release escape, press @kbd{k}''. That's much more -work than if you have a meta key, so if that's the case, I respectfully -suggest you get a real keyboard with a meta key. You can't live without -it. - - - -@node Emacs Lisp -@subsection Emacs Lisp - -Emacs is the King of Editors because it's really a Lisp interpreter. -Each and every key you tap runs some Emacs Lisp code snippet, and since -Emacs Lisp is an interpreted language, that means that you can configure -any key to run any arbitrary code. You just, like, do it. - -Gnus is written in Emacs Lisp, and is run as a bunch of interpreted -functions. (These are byte-compiled for speed, but it's still -interpreted.) If you decide that you don't like the way Gnus does -certain things, it's trivial to have it do something a different way. -(Well, at least if you know how to write Lisp code.) However, that's -beyond the scope of this manual, so we are simply going to talk about -some common constructs that you normally use in your @file{~/.gnus.el} -file to customize Gnus. (You can also use the @file{~/.emacs} file, but -in order to set things of Gnus up, it is much better to use the -@file{~/.gnus.el} file, @xref{Startup Files}.) - -If you want to set the variable @code{gnus-florgbnize} to four (4), you -write the following: - -@lisp -(setq gnus-florgbnize 4) -@end lisp - -This function (really ``special form'') @code{setq} is the one that can -set a variable to some value. This is really all you need to know. Now -you can go and fill your @file{~/.gnus.el} file with lots of these to -change how Gnus works. - -If you have put that thing in your @file{~/.gnus.el} file, it will be -read and @code{eval}ed (which is Lisp-ese for ``run'') the next time you -start Gnus. If you want to change the variable right away, simply say -@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the -previous ``form'', which is a simple @code{setq} statement here. - -Go ahead---just try it, if you're located at your Emacs. After you -@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which -is the return value of the form you @code{eval}ed. - -Some pitfalls: - -If the manual says ``set @code{gnus-read-active-file} to @code{some}'', -that means: - -@lisp -(setq gnus-read-active-file 'some) -@end lisp - -On the other hand, if the manual says ``set @code{gnus-nntp-server} to -@samp{nntp.ifi.uio.no}'', that means: - -@lisp -(setq gnus-nntp-server "nntp.ifi.uio.no") -@end lisp - -So be careful not to mix up strings (the latter) with symbols (the -former). The manual is unambiguous, but it can be confusing. - -@page -@include gnus-faq.texi - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@node Key Index -@chapter Key Index -@printindex ky - -@bye - -@iftex -@iflatex -\end{document} -@end iflatex -@end iftex - -@c Local Variables: -@c mode: texinfo -@c coding: iso-8859-1 -@c End: - -@ignore - arch-tag: c9fa47e7-78ca-4681-bda9-9fef45d1c819 -@end ignore diff --git a/doc/misc/gpl.texi b/doc/misc/gpl.texi deleted file mode 100644 index 5b416d3cb41..00000000000 --- a/doc/misc/gpl.texi +++ /dev/null @@ -1,721 +0,0 @@ -@c The GNU General Public License. -@center Version 3, 29 June 2007 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. -@end display - -@heading Preamble - -The GNU General Public License is a free, copyleft license for -software and other kinds of works. - -The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom -to share and change all versions of a program---to make sure it remains -free software for all its users. We, the Free Software Foundation, -use the GNU General Public License for most of our software; it -applies also to any other work released this way by its authors. You -can apply it to your programs, too. - -When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - -To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you -have certain responsibilities if you distribute copies of the -software, or if you modify it: responsibilities to respect the freedom -of others. - -For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, -receive or can get the source code. And you must show them these -terms so they know their rights. - -Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - -For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - -Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the -manufacturer can do so. This is fundamentally incompatible with the -aim of protecting users' freedom to change the software. The -systematic pattern of such abuse occurs in the area of products for -individuals to use, which is precisely where it is most unacceptable. -Therefore, we have designed this version of the GPL to prohibit the -practice for those products. If such problems arise substantially in -other domains, we stand ready to extend this provision to those -domains in future versions of the GPL, as needed to protect the -freedom of users. - -Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish -to avoid the special danger that patents applied to a free program -could make it effectively proprietary. To prevent this, the GPL -assures that patents cannot be used to render the program non-free. - -The precise terms and conditions for copying, distribution and -modification follow. - -@heading TERMS AND CONDITIONS - -@enumerate 0 -@item Definitions. - -``This License'' refers to version 3 of the GNU General Public License. - -``Copyright'' also means copyright-like laws that apply to other kinds -of works, such as semiconductor masks. - -``The Program'' refers to any copyrightable work licensed under this -License. Each licensee is addressed as ``you''. ``Licensees'' and -``recipients'' may be individuals or organizations. - -To ``modify'' a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of -an exact copy. The resulting work is called a ``modified version'' of -the earlier work or a work ``based on'' the earlier work. - -A ``covered work'' means either the unmodified Program or a work based -on the Program. - -To ``propagate'' a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - -To ``convey'' a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user -through a computer network, with no transfer of a copy, is not -conveying. - -An interactive user interface displays ``Appropriate Legal Notices'' to -the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - -@item Source Code. - -The ``source code'' for a work means the preferred form of the work for -making modifications to it. ``Object code'' means any non-source form -of a work. - -A ``Standard Interface'' means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - -The ``System Libraries'' of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -``Major Component'', in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - -The ``Corresponding Source'' for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - -The Corresponding Source need not include anything that users can -regenerate automatically from other parts of the Corresponding Source. - -The Corresponding Source for a work in source code form is that same -work. - -@item Basic Permissions. - -All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - -You may make, run and propagate covered works that you do not convey, -without conditions so long as your license otherwise remains in force. -You may convey covered works to others for the sole purpose of having -them make modifications exclusively for you, or provide you with -facilities for running those works, provided that you comply with the -terms of this License in conveying all material for which you do not -control copyright. Those thus making or running the covered works for -you must do so exclusively on your behalf, under your direction and -control, on terms that prohibit them from making any copies of your -copyrighted material outside their relationship with you. - -Conveying under any other circumstances is permitted solely under the -conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - -@item Protecting Users' Legal Rights From Anti-Circumvention Law. - -No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - -When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such -circumvention is effected by exercising rights under this License with -respect to the covered work, and you disclaim any intention to limit -operation or modification of the work as a means of enforcing, against -the work's users, your or third parties' legal rights to forbid -circumvention of technological measures. - -@item Conveying Verbatim Copies. - -You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - -You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - -@item Conveying Modified Source Versions. - -You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these -conditions: - -@enumerate a -@item -The work must carry prominent notices stating that you modified it, -and giving a relevant date. - -@item -The work must carry prominent notices stating that it is released -under this License and any conditions added under section 7. This -requirement modifies the requirement in section 4 to ``keep intact all -notices''. - -@item -You must license the entire work, as a whole, under this License to -anyone who comes into possession of a copy. This License will -therefore apply, along with any applicable section 7 additional terms, -to the whole of the work, and all its parts, regardless of how they -are packaged. This License gives no permission to license the work in -any other way, but it does not invalidate such permission if you have -separately received it. - -@item -If the work has interactive user interfaces, each must display -Appropriate Legal Notices; however, if the Program has interactive -interfaces that do not display Appropriate Legal Notices, your work -need not make them do so. -@end enumerate - -A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -``aggregate'' if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - -@item Conveying Non-Source Forms. - -You may convey a covered work in object code form under the terms of -sections 4 and 5, provided that you also convey the machine-readable -Corresponding Source under the terms of this License, in one of these -ways: - -@enumerate a -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by the -Corresponding Source fixed on a durable physical medium customarily -used for software interchange. - -@item -Convey the object code in, or embodied in, a physical product -(including a physical distribution medium), accompanied by a written -offer, valid for at least three years and valid for as long as you -offer spare parts or customer support for that product model, to give -anyone who possesses the object code either (1) a copy of the -Corresponding Source for all the software in the product that is -covered by this License, on a durable physical medium customarily used -for software interchange, for a price no more than your reasonable -cost of physically performing this conveying of source, or (2) access -to copy the Corresponding Source from a network server at no charge. - -@item -Convey individual copies of the object code with a copy of the written -offer to provide the Corresponding Source. This alternative is -allowed only occasionally and noncommercially, and only if you -received the object code with such an offer, in accord with subsection -6b. - -@item -Convey the object code by offering access from a designated place -(gratis or for a charge), and offer equivalent access to the -Corresponding Source in the same way through the same place at no -further charge. You need not require recipients to copy the -Corresponding Source along with the object code. If the place to copy -the object code is a network server, the Corresponding Source may be -on a different server (operated by you or a third party) that supports -equivalent copying facilities, provided you maintain clear directions -next to the object code saying where to find the Corresponding Source. -Regardless of what server hosts the Corresponding Source, you remain -obligated to ensure that it is available for as long as needed to -satisfy these requirements. - -@item -Convey the object code using peer-to-peer transmission, provided you -inform other peers where the object code and Corresponding Source of -the work are being offered to the general public at no charge under -subsection 6d. - -@end enumerate - -A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - -A ``User Product'' is either (1) a ``consumer product'', which means any -tangible personal property which is normally used for personal, -family, or household purposes, or (2) anything designed or sold for -incorporation into a dwelling. In determining whether a product is a -consumer product, doubtful cases shall be resolved in favor of -coverage. For a particular product received by a particular user, -``normally used'' refers to a typical or common use of that class of -product, regardless of the status of the particular user or of the way -in which the particular user actually uses, or expects or is expected -to use, the product. A product is a consumer product regardless of -whether the product has substantial commercial, industrial or -non-consumer uses, unless such uses represent the only significant -mode of use of the product. - -``Installation Information'' for a User Product means any methods, -procedures, authorization keys, or other information required to -install and execute modified versions of a covered work in that User -Product from a modified version of its Corresponding Source. The -information must suffice to ensure that the continued functioning of -the modified object code is in no case prevented or interfered with -solely because modification has been made. - -If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - -The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or -updates for a work that has been modified or installed by the -recipient, or for the User Product in which it has been modified or -installed. Access to a network may be denied when the modification -itself materially and adversely affects the operation of the network -or violates the rules and protocols for communication across the -network. - -Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - -@item Additional Terms. - -``Additional permissions'' are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - -When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - -Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders -of that material) supplement the terms of this License with terms: - -@enumerate a -@item -Disclaiming warranty or limiting liability differently from the terms -of sections 15 and 16 of this License; or - -@item -Requiring preservation of specified reasonable legal notices or author -attributions in that material or in the Appropriate Legal Notices -displayed by works containing it; or - -@item -Prohibiting misrepresentation of the origin of that material, or -requiring that modified versions of such material be marked in -reasonable ways as different from the original version; or - -@item -Limiting the use for publicity purposes of names of licensors or -authors of the material; or - -@item -Declining to grant rights under trademark law for use of some trade -names, trademarks, or service marks; or - -@item -Requiring indemnification of licensors and authors of that material by -anyone who conveys the material (or modified versions of it) with -contractual assumptions of liability to the recipient, for any -liability that these contractual assumptions directly impose on those -licensors and authors. -@end enumerate - -All other non-permissive additional terms are considered ``further -restrictions'' within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - -If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - -Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; the -above requirements apply either way. - -@item Termination. - -You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - -However, if you cease all violation of this License, then your license -from a particular copyright holder is reinstated (a) provisionally, -unless and until the copyright holder explicitly and finally -terminates your license, and (b) permanently, if the copyright holder -fails to notify you of the violation by some reasonable means prior to -60 days after the cessation. - -Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - -Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - -@item Acceptance Not Required for Having Copies. - -You are not required to accept this License in order to receive or run -a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - -@item Automatic Licensing of Downstream Recipients. - -Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - -An ``entity transaction'' is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - -You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - -@item Patents. - -A ``contributor'' is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's ``contributor version''. - -A contributor's ``essential patent claims'' are all patent claims owned -or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, ``control'' includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - -Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - -In the following three paragraphs, a ``patent license'' is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To ``grant'' such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - -If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. ``Knowingly relying'' means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - -If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - -A patent license is ``discriminatory'' if it does not include within the -scope of its coverage, prohibits the exercise of, or is conditioned on -the non-exercise of one or more of the rights that are specifically -granted under this License. You may not convey a covered work if you -are a party to an arrangement with a third party that is in the -business of distributing software, under which you make payment to the -third party based on the extent of your activity of conveying the -work, and under which the third party grants, to any of the parties -who would receive the covered work from you, a discriminatory patent -license (a) in connection with copies of the covered work conveyed by -you (or copies made from those copies), or (b) primarily for and in -connection with specific products or compilations that contain the -covered work, unless you entered into that arrangement, or that patent -license was granted, prior to 28 March 2007. - -Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - -@item No Surrender of Others' Freedom. - -If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey -a covered work so as to satisfy simultaneously your obligations under -this License and any other pertinent obligations, then as a -consequence you may not convey it at all. For example, if you agree -to terms that obligate you to collect a royalty for further conveying -from those to whom you convey the Program, the only way you could -satisfy both those terms and this License would be to refrain entirely -from conveying the Program. - -@item Use with the GNU Affero General Public License. - -Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - -@item Revised Versions of this License. - -The Free Software Foundation may publish revised and/or new versions -of the GNU General Public License from time to time. Such new -versions will be similar in spirit to the present version, but may -differ in detail to address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies that a certain numbered version of the GNU General Public -License ``or any later version'' applies to it, you have the option of -following the terms and conditions either of that numbered version or -of any later version published by the Free Software Foundation. If -the Program does not specify a version number of the GNU General -Public License, you may choose any version ever published by the Free -Software Foundation. - -If the Program specifies that a proxy can decide which future versions -of the GNU General Public License can be used, that proxy's public -statement of acceptance of a version permanently authorizes you to -choose that version for the Program. - -Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - -@item Disclaimer of Warranty. - -THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT -WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND -PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE -DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR -CORRECTION. - -@item Limitation of Liability. - -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR -CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES -ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT -NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR -LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM -TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER -PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -@item Interpretation of Sections 15 and 16. - -If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - -@end enumerate - -@heading END OF TERMS AND CONDITIONS - -@heading How to Apply These Terms to Your New Programs - -If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these -terms. - -To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and a brief idea of what it does.} -Copyright (C) @var{year} @var{name of author} - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or (at -your option) any later version. - -This program is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see @url{http://www.gnu.org/licenses/}. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - -@smallexample -@var{program} Copyright (C) @var{year} @var{name of author} -This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. -This is free software, and you are welcome to redistribute it -under certain conditions; type @samp{show c} for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, your -program's commands might be different; for a GUI interface, you would -use an ``about box''. - -You should also get your employer (if you work as a programmer) or school, -if any, to sign a ``copyright disclaimer'' for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -@url{http://www.gnu.org/licenses/}. - -The GNU General Public License does not permit incorporating your -program into proprietary programs. If your program is a subroutine -library, you may consider it more useful to permit linking proprietary -applications with the library. If this is what you want to do, use -the GNU Lesser General Public License instead of this License. But -first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. - -@ignore - arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67 -@end ignore diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi deleted file mode 100644 index 0d241771dcb..00000000000 --- a/doc/misc/idlwave.texi +++ /dev/null @@ -1,4301 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/idlwave -@settitle IDLWAVE User Manual -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp -@set VERSION 6.1 -@set EDITION 6.1 -@set IDLVERSION 6.3 -@set NSYSROUTINES 4346 -@set DATE April, 2007 -@set AUTHOR J.D. Smith & Carsten Dominik -@set MAINTAINER J.D. Smith -@c %**end of header -@finalout - -@copying -This file documents IDLWAVE, a major mode for editing IDL files with -Emacs, and interacting with an IDL shell run as a subprocess. - -This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE -@value{VERSION}. - -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* IDLWAVE: (idlwave). Major mode and shell for IDL files. -@end direntry - -@titlepage -@title IDLWAVE User Manual -@subtitle Emacs major mode and shell for IDL -@subtitle Edition @value{EDITION}, @value{DATE} -@author by J.D. Smith & Carsten Dominik -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) - -IDLWAVE is a package which supports editing source code written in the -Interactive Data Language (IDL), and running IDL as an inferior shell. - -@insertcopying -@end ifnottex - -@menu -* Introduction:: What IDLWAVE is, and what it is not -* IDLWAVE in a Nutshell:: One page quick-start guide -* Getting Started:: Tutorial -* The IDLWAVE Major Mode:: The mode for editing IDL programs -* The IDLWAVE Shell:: The mode for running IDL as an inferior program -* Acknowledgements:: Who did what -* Sources of Routine Info:: How does IDLWAVE know about routine XYZ -* HTML Help Browser Tips:: -* Configuration Examples:: The user is king -* Windows and MacOS:: What still works, and how -* Troubleshooting:: When good computers turn bad -* GNU Free Documentation License:: The license for this documentation. -* Index:: Fast access - -@detailmenu - --- The Detailed Node Listing --- - -Getting Started (Tutorial) - -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: - -The IDLWAVE Major Mode - -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else - -Code Formatting - -* Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: -* Comment Indentation:: Special indentation for comment lines -* Continuation Lines:: Splitting statements over lines -* Syntax Highlighting:: Font-lock support -* Octals and Highlighting:: Why "123 causes problems - -Online Help - -* Help with HTML Documentation:: -* Help with Source:: - -Completion - -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag - -Actions - -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords - -The IDLWAVE Shell - -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: - -Debugging IDL Programs - -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: - -Sources of Routine Info - -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals - -Catalogs - -* Library Catalogs:: -* User Catalog:: - -@end detailmenu -@end menu - -@node Introduction, IDLWAVE in a Nutshell, Top, Top -@chapter Introduction -@cindex Introduction -@cindex CORBA (Common Object Request Broker Architecture) -@cindex Interface Definition Language -@cindex Interactive Data Language -@cindex cc-mode.el -@cindex @file{idl.el} -@cindex @file{idl-shell.el} -@cindex Feature overview - -IDLWAVE is a package which supports editing source files written in -the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used -for editing source files for the related WAVE/CL language, but with only -limited support.}. It is a feature-rich replacement for the IDLDE -development environment included with IDL, and uses the full power of -Emacs to make editing and running IDL programs easier, quicker, and more -structured. - -IDLWAVE consists of two main parts: a major mode for editing IDL -source files (@code{idlwave-mode}) and a mode for running the IDL -program as an inferior shell (@code{idlwave-shell-mode}). Although -one mode can be used without the other, both work together closely to -form a complete development environment. Here is a brief summary of -what IDLWAVE does: - -@itemize @bullet -@item -Smart code indentation and automatic-formatting. -@item -Three level syntax highlighting support. -@item -Context-sensitive display of calling sequences and keywords for more -than 1000 native IDL routines, extendible to any additional number of -local routines, and already available with many pre-scanned libraries. -@item -Fast, context-sensitive online HTML help, or source-header help for -undocumented routines. -@item -Context sensitive completion of routine names, keywords, system -variables, class names and much more. -@item -Easy insertion of code templates and abbreviations of common constructs. -@item -Automatic corrections to enforce a variety of customizable coding -standards. -@item -Integrity checks and auto-termination of logical blocks. -@item -Routine name space conflict search with likelihood-of-use ranking. -@item -Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). -@item -Documentation support. -@item -Running IDL as an inferior Shell with history search, command line -editing and all the completion and routine info capabilities present in -IDL source buffers. -@item -Full handling of debugging with breakpoints, with interactive setting -of break conditions, and easy stepping through code. -@item -Compilation, execution and interactive single-keystroke debugging of -programs directly from the source buffer. -@item -Quick, source-guided navigation of the calling stack, with variable -inspection, etc. -@item -Examining variables and expressions with a mouse click. -@item -And much, much more... -@end itemize - -@ifnottex -@cindex Screenshots -Here are a number of screenshots showing IDLWAVE in action: - -@itemize @bullet -@item -@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} -@item -@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} -@item -@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code -stopped at a breakpoint} -@end itemize -@end ifnottex - -IDLWAVE is the distant successor to the @file{idl.el} and -@file{idl-shell.el} files written by Chris Chase. The modes and files -had to be renamed because of a name space conflict with CORBA's -@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. - -In this manual, each section ends with a list of related user options. -Don't be confused by the sheer number of options available --- in most -cases the default settings are just fine. The variables are listed here -to make sure you know where to look if you want to change anything. For -a full description of what a particular variable does and how to -configure it, see the documentation string of that variable (available -with @kbd{C-h v}). Some configuration examples are also given in the -appendix. - -@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top -@chapter IDLWAVE in a Nutshell -@cindex Summary of important commands -@cindex IDLWAVE in a Nutshell -@cindex Nutshell, IDLWAVE in a - -@subheading Editing IDL Programs - -@multitable @columnfractions .15 .85 -@item @key{TAB} -@tab Indent the current line relative to context. -@item @kbd{C-M-\} -@tab Re-indent all lines in the current region. -@item @kbd{C-M-q} -@tab Re-indent all lines in the current routine. -@item @kbd{C-u @key{TAB}} -@tab Re-indent all lines in the current statement. -@item @kbd{M-@key{RET}} -@tab Start a continuation line, splitting the current line at point. -@item @kbd{M-;} -@tab Start new comment at line beginning or after code, or (un)comment -highlighted region. -@item @kbd{M-q} -@tab Fill the current comment paragraph. -@item @kbd{C-c ?} -@tab Display calling sequence and keywords for the procedure or function call -at point. -@item @kbd{M-?} -@tab Load context sensitive online help for nearby routine, keyword, etc. -@item @kbd{M-@key{TAB}} -@tab Complete a procedure name, function name or keyword in the buffer. -@item @kbd{C-c C-i} -@tab Update IDLWAVE's knowledge about functions and procedures. -@item @kbd{C-c C-v} -@tab Visit the source code of a procedure/function. -@item @kbd{C-u C-c C-v} -@tab Visit the source code of a procedure/function in this buffer. -@item @kbd{C-c C-h} -@tab Insert a standard documentation header. -@item @kbd{C-c @key{RET}} -@tab Insert a new timestamp and history item in the documentation header. -@end multitable - -@subheading Running the IDLWAVE Shell, Debugging Programs - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-s} -@tab Start IDL as a subprocess and/or switch to the shell buffer. -@item @key{Up}, @kbd{M-p} -@tab Cycle back through IDL command history. -@item @key{Down},@kbd{M-n} -@tab Cycle forward. -@item @kbd{@key{TAB}} -@tab Complete a procedure name, function name or keyword in the shell buffer. -@item @kbd{C-c C-d C-c} -@tab Save and compile the source file in the current buffer. -@item @kbd{C-c C-d C-e} -@tab Compile and run the current region. -@item @kbd{C-c C-d C-x} -@tab Go to next syntax error. -@item @kbd{C-c C-d C-v} -@tab Switch to electric debug mode. -@item @kbd{C-c C-d C-b} -@tab Set a breakpoint at the nearest viable source line. -@item @kbd{C-c C-d C-d} -@tab Clear the nearest breakpoint. -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint. -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint. -@item @kbd{C-c C-d C-p} -@tab Print the value of the expression near point in IDL. -@end multitable - -@subheading Commonly used Settings in @file{.emacs} -@lisp -;; Change the indentation preferences -;; Start autoloading routine info after 2 idle seconds -(setq idlwave-init-rinfo-when-idle-after 2) -;; Pad operators with spaces -(setq idlwave-do-actions t - idlwave-surround-by-blank t) -;; Syntax Highlighting -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -;; Automatically start the shell when needed -(setq idlwave-shell-automatic-start t) -;; Bind debugging commands with CONTROL and SHIFT modifiers -(setq idlwave-shell-debug-modifiers '(control shift)) -@end lisp - -@html - -@end html - -@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top -@chapter Getting Started (Tutorial) -@cindex Quick-Start -@cindex Tutorial -@cindex Getting Started - -@menu -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: -@end menu - -@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started -@section Lesson I: Development Cycle - -The purpose of this tutorial is to guide you through a very basic -development cycle using IDLWAVE. We will paste a simple program into -a buffer and use the shell to compile, debug and run it. On the way -we will use many of the important IDLWAVE commands. Note, however, -that IDLWAVE has many more capabilities than covered here, which can -be discovered by reading the entire manual, or hovering over the -shoulder of your nearest IDLWAVE guru for a few days. - -It is assumed that you have access to Emacs or XEmacs with the full -IDLWAVE package including online help. We also assume that you are -familiar with Emacs and can read the nomenclature of key presses in -Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for -@key{META} (often the @key{ALT} key carries this functionality)). - -Open a new source file by typing: - -@example -@kbd{C-x C-f tutorial.pro @key{RET}} -@end example - -A buffer for this file will pop up, and it should be in IDLWAVE mode, -indicated in the mode line just below the editing window. Also, the -menu bar should contain @samp{IDLWAVE}. - -Now cut-and-paste the following code, also available as -@file{tutorial.pro} in the IDLWAVE distribution. - -@example -function daynr,d,m,y - ;; compute a sequence number for a date - ;; works 1901-2099. - if y lt 100 then y = y+1900 - if m le 2 then delta = 1 else delta = 0 - m1 = m + delta*12 + 1 - y1 = y * delta - return, d + floor(m1*30.6)+floor(y1*365.25)+5 -end - -function weekday,day,month,year - ;; compute weekday number for date - nr = daynr(day,month,year) - return, nr mod 7 -end - -pro plot_wday,day,month - ;; Plot the weekday of a date in the first 10 years of this century. - years = 2000,+indgen(10) - wdays = intarr(10) - for i=0,n_elements(wdays)-1 do begin - wdays[i] = weekday(day,month,years[i]) - end - plot,years,wdays,YS=2,YT="Wday (0=Sunday)" -end -@end example - -The indentation probably looks funny, since it's different from the -settings you use, so use the @key{TAB} key in each line to -automatically line it up (or, more quickly, @emph{select} the entire -buffer with @kbd{C-x h}, and indent the whole region with -@kbd{C-M-\}). Notice how different syntactical elements are -highlighted in different colors, if you have set up support for -font-lock. - -Let's check out two particular editing features of IDLWAVE. Place the -cursor after the @code{end} statement of the @code{for} loop and press -@key{SPC}. IDLWAVE blinks back to the beginning of the block and -changes the generic @code{end} to the specific @code{endfor} -automatically (as long as the variable @code{idlwave-expand-generic-end} -is turned on --- @pxref{Lesson II -- Customization}). Now place the -cursor in any line you would like to split and press @kbd{M-@key{RET}}. -The line is split at the cursor position, with the continuation @samp{$} -and indentation all taken care of. Use @kbd{C-/} to undo the last -change. - -The procedure @code{plot_wday} is supposed to plot the day of the week -of a given date for the first 10 years of the 21st century. As in -most code, there are a few bugs, which we are going to use IDLWAVE to -help us fix. - -First, let's launch the IDLWAVE shell. You do this with the command -@kbd{C-c C-s}. The Emacs window will split or another window will popup -to display IDL running in a shell interaction buffer. Type a few -commands like @code{print,!PI} to convince yourself that you can work -there just as well as in a terminal, or the IDLDE. Use the arrow keys -to cycle through your command history. Are we having fun now? - -Now go back to the source window and type @kbd{C-c C-d C-c} to compile -the program. If you watch the shell buffer, you see that IDLWAVE types -@samp{.run "tutorial.pro"} for you. But the compilation fails because -there is a comma in the line @samp{years=...}. The line with the error -is highlighted and the cursor positioned at the error, so remove the -comma (you should only need to hit @kbd{Delete}!). Compile again, using -the same keystrokes as before. Notice that the file is automatically -saved for you. This time everything should work fine, and you should -see the three routines compile. - -Now we want to use the command to plot the day of the week on January -1st. We could type the full command ourselves, but why do that? Go -back to the shell window, type @samp{plot_} and hit @key{TAB}. After -a bit of a delay (while IDLWAVE initializes its routine info database, -if necessary), the window will split to show all procedures it knows -starting with that string, and @w{@code{plot_wday}} should be one of -them. Saving the buffer alerted IDLWAVE about this new routine. -Click with the middle mouse button on @code{plot_wday} and it will be -copied to the shell buffer, or if you prefer, add @samp{w} to -@samp{plot_} to make it unambiguous (depending on what other routines -starting with @samp{plot_} you have installed on your system), hit -@key{TAB} again, and the full routine name will be completed. Now -provide the two arguments: - -@example -plot_wday,1,1 -@end example - -@noindent and press @key{RET}. This fails with an error message telling -you the @code{YT} keyword to plot is ambiguous. What are the allowed -keywords again? Go back to the source window and put the cursor into -the `plot' line and press @kbd{C-c ?}. This shows the routine info -window for the plot routine, which contains a list of keywords, along -with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. -Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with -@kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command -and execute again. - -This time we get a plot, but it is pretty ugly --- the points are all -connected with a line. Hmm, isn't there a way for @code{plot} to use -symbols instead? What was that keyword? Position the cursor on the -plot line after a comma (where you'd normally type a keyword), and hit -@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, -there it is, @code{PSYM}. Middle click to insert it. An @samp{=} -sign is included for you too. Now what were the values of @code{PSYM} -supposed to be? With the cursor on or after the keyword, press -@kbd{M-?} for online help (alternatively, you could have right clicked -on the colored keyword itself in the completion list). A browser will -pop up showing the HTML documentation for the @code{PYSM} keyword. -OK, let's use diamonds=4. Fix this, recompile (you know the command -by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished, -you know what to do: @kbd{C-c C-s}) and execute again. Now things -look pretty good. - -Let's try a different day --- how about April fool's day? - -@example -plot_wday,1,4 -@end example - -Oops, this looks very wrong. All April Fool's days cannot be Fridays! -We've got a bug in the program, perhaps in the @code{daynr} function. -Let's put a breakpoint on the last line there. Position the cursor on -the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a -breakpoint (as you see in the shell window), and the break line is -indicated. Back to the shell buffer, re-execute the previous command. -IDL stops at the line with the breakpoint. Now hold down the SHIFT -key and click with the middle mouse button on a few variables there: -@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't -the correct type. CONTROL-SHIFT middle-click on it for help. Well, -it's an integer, so that's not the problem. Aha, @samp{y1} is zero, -but it should be the year, depending on delta. Shift click -@samp{delta} to see that it's 0. Below, we see the offending line: -@samp{y1=y*delta...} the multiplication should have been a minus sign! -Hit @kbd{q} to exit the debugging mode, and fix the line to read: - -@example -y1 = y - delta -@end example - -Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the -command. Everything should now work fine. How about those leap years? -Change the code to plot 100 years and see that every 28 years, the -sequence of weekdays repeats. - -@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started -@section Lesson II: Customization - -Emacs is probably the most customizable piece of software ever written, -and it would be a shame if you did not make use of this to adapt IDLWAVE -to your own preferences. Customizing Emacs or IDLWAVE is accomplished -by setting Lisp variables in the @file{.emacs} file in your home -directory --- but do not be dismayed; for the most part, you can just -copy and work from the examples given here. - -Let's first use a boolean variable. These are variables which you turn -on or off, much like a checkbox. A value of @samp{t} means on, a value -of @samp{nil} means off. Copy the following line into your -@file{.emacs} file, exit and restart Emacs. - -@lisp -(setq idlwave-reserved-word-upcase t) -@end lisp - -When this option is turned on, each reserved word you type into an IDL -source buffer will be converted to upper case when you press @key{SPC} -or @key{RET} right after the word. Try it out! @samp{if} changes to -@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this -behavior, remove the option again from your @file{.emacs} file and -restart Emacs. - -You likely have your own indentation preferences for IDL code. For -example, some may prefer to indent the main block of an IDL program -slightly from the margin and use only 3 spaces as indentation between -@code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}: - -@lisp -(setq idlwave-main-block-indent 1) -(setq idlwave-block-indent 3) -(setq idlwave-end-offset -3) -@end lisp - -Restart Emacs, and re-indent the program we developed in the first part -of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep -these lines in @file{.emacs}, with values adjusted to your likings. If -you want to get more information about any of these variables, type, -e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which -variables can be customized, look for items marked @samp{User Option:} -throughout this manual. - -If you cannot seem to master this Lisp customization in @file{.emacs}, -there is another, more user-friendly way to customize all the IDLWAVE -variables. You can access it through the IDLWAVE menu in one of the -@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE -Group}. Here you'll be presented with all the various variables grouped -into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE -Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand -Generic End} to turn on @code{END} expansion), read about the variables, -change them, and `Save for Future Sessions'. Few of these variables -need customization, but you can exercise considerable control over -IDLWAVE's functionality with them. - -You may also find the key bindings used for the debugging commands too -long and complicated. Often we have heard complaints along the lines -of, ``Do I really have to go through the finger gymnastics of @kbd{C-c -C-d C-c} to run a simple command?'' Due to Emacs rules and -conventions, shorter bindings cannot be set by default, but you can -easily enable them. First, there is a way to assign all debugging -commands in a single sweep to another simpler combination. The only -problem is that we have to use something which Emacs does not need for -other important commands. One good option is to execute debugging -commands by holding down @key{CONTROL} and @key{SHIFT} while pressing -a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} -for compiling the current source file, @kbd{C-S-a} for deleting all -breakpoints (try it, it's easier). You can enable this with: - -@lisp -(setq idlwave-shell-debug-modifiers '(shift control)) -@end lisp - -@noindent If you have a special keyboard with, for example, a -@key{SUPER} key, you could even shorten that: - -@lisp -(setq idlwave-shell-debug-modifiers '(super)) -@end lisp - -@noindent to get compilation on @kbd{S-c}. Often, a modifier key like -@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise -unused key on your keyboard --- consult your system documentation. - -You can also assign specific commands to keys. This you must do in the -@emph{mode-hook}, a special function which is run when a new IDLWAVE -buffer gets set up. The possibilities for key customization are -endless. Here we set function keys f4-f8 to common debugging commands. - -@lisp -;; First for the source buffer -(add-hook 'idlwave-mode-hook - (lambda () - (local-set-key [f4] 'idlwave-shell-retall) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - (local-set-key [f7] 'idlwave-shell-cont) - (local-set-key [f8] 'idlwave-shell-clear-all-bp))) -;; Then for the shell buffer -(add-hook 'idlwave-shell-mode-hook - (lambda () - (local-set-key [f4] 'idlwave-shell-retall) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - (local-set-key [f7] 'idlwave-shell-cont) - (local-set-key [f8] 'idlwave-shell-clear-all-bp))) -@end lisp - -@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started -@section Lesson III: User and Library Catalogs - -We have already used the routine info display in the first part of this -tutorial. This was the invoked using @kbd{C-c ?}, and displays -information about the IDL routine near the cursor position. Wouldn't it -be nice to have the same kind of information available for your own -routines and for the huge amount of code in major libraries like JHUPL -or the IDL-Astro library? In many cases, you may already have this -information. Files named @file{.idlwave_catalog} in library directories -contain scanned information on the routines in that directory; many -popular libraries ship with these ``library catalogs'' pre-scanned. -Users can scan their own routines in one of two ways: either using the -supplied tool to scan directories and build their own -@file{.idlwave_catalog} files, or using the built-in method to create a -single ``user catalog'', which we'll show here. @xref{Catalogs}, for -more information on choosing which method to use. - -To build a user catalog, select @code{Routine Info/Select Catalog -Directories} from the IDLWAVE entry in the menu bar. If necessary, -start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}). -IDLWAVE will find out about the IDL @code{!PATH} variable and offer a -list of directories on the path. Simply select them all (or whichever -you want --- directories with existing library catalogs will not be -selected by default) and click on the @samp{Scan&Save} button. Then -go for a cup of coffee while IDLWAVE collects information for each and -every IDL routine on your search path. All this information is -written to the file @file{.idlwave/idlusercat.el} in your home -directory and will from now on automatically load whenever you use -IDLWAVE. You may find it necessary to rebuild the catalog on occasion -as your local libraries change, or build a library catalog for those -directories instead. Invoke routine info (@kbd{C-c ?}) or completion -(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to -be located in the library. E.g., if you have scanned the IDL-Astro -library: - -@example - a=readf@key{M-@key{TAB}} -@end example - -expands to `readfits('. Then try - -@example - a=readfits(@key{C-c ?} -@end example - -and you get: - -@example -Usage: Result = READFITS(filename, header, heap) -... -@end example - -I hope you made it until here. Now you are set to work with IDLWAVE. -On the way you will want to change other things, and to learn more -about the possibilities not discussed in this short tutorial. Read -the manual, look at the documentation strings of interesting variables -(with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the -remaining questions on the newsgroup @code{comp.lang.idl-pvwave}. - -@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top -@chapter The IDLWAVE Major Mode -@cindex IDLWAVE major mode -@cindex Major mode, @code{idlwave-mode} - -The IDLWAVE major mode supports editing IDL source files. In this -chapter we describe the main features of the mode and how to customize -them. - -@menu -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else -@end menu - -@node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode -@section Code Formatting -@cindex Code formatting -@cindex Formatting, of code - -@menu -* Code Indentation:: Reflecting the logical structure -* Continued Statement Indentation:: -* Comment Indentation:: Special indentation for comment lines -* Continuation Lines:: Splitting statements over lines -* Syntax Highlighting:: Font-lock support -* Octals and Highlighting:: Why "123 causes problems -@end menu - -The IDL language, with its early roots in FORTRAN, modern -implementation in C, and liberal borrowing of features of many vector -and other languages along its 25+ year history, has inherited an -unusual mix of syntax elements. Left to his or her own devices, a -novice IDL programmer will often conjure code which is very difficult -to read and impossible to adapt. Much can be gleaned from studying -available IDL code libraries for coding style pointers, but, due to -the variety of IDL syntax elements, replicating this style can be -challenging at best. Luckily, IDLWAVE understands the structure of -IDL code very well, and takes care of almost all formatting issues for -you. After configuring it to match your coding standards, you can -rely on it to help keep your code neat and organized. - - -@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting -@subsection Code Indentation -@cindex Code indentation -@cindex Indentation - -Like all Emacs programming modes, IDLWAVE performs code indentation. -The @key{TAB} key indents the current line relative to context. -@key{LFD} insert a newline and indents the new line. The indentation is -governed by a number of variables. IDLWAVE indents blocks (between -@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and -continuation lines. - -@cindex Foreign code, adapting -@cindex Indentation, of foreign code -@kindex C-M-\ -To re-indent a larger portion of code (e.g. when working with foreign -code written with different conventions), use @kbd{C-M-\} -(@code{indent-region}) after marking the relevant code. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). The command @kbd{C-M-q} reindents the entire current -routine. @xref{Actions}, for information how to impose additional -formatting conventions on foreign code. - -@defopt idlwave-main-block-indent (@code{2}) -Extra indentation for the main block of code. That is the block between -the FUNCTION/PRO statement and the END statement for that program -unit. -@end defopt - -@defopt idlwave-block-indent (@code{3}) -Extra indentation applied to block lines. If you change this, you -probably also want to change @code{idlwave-end-offset}. -@end defopt - -@defopt idlwave-end-offset (@code{-3}) -Extra indentation applied to block END lines. A value equal to negative -@code{idlwave-block-indent} will make END lines line up with the block -BEGIN lines. -@end defopt - -@node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting -@subsection Continued Statement Indentation -@cindex Indentation, continued statement -@cindex Continued statement indentation -Continuation lines (following a line ending with @code{$}) can receive a -fixed indentation offset from the main level, but in several situations -IDLWAVE can use a special form of indentation which aligns continued -statements more naturally. Special indentation is calculated for -continued routine definition statements and calls, enclosing parentheses -(like function calls, structure/class definitions, explicit structures -or lists, etc.), and continued assignments. An attempt is made to line -up with the first non-whitespace character after the relevant opening -punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For -lines without any non-comment characters on the line with the opening -punctuation, the continued line(s) are aligned just past the -punctuation. An example: - -@example -function foo, a, b, $ - c, d - bar = sin( a + b + $ - c + d) -end -@end example -@noindent - -The only drawback to this special continued statement indentation is -that it consumes more space, e.g., for long function names or left hand -sides of an assignment: - -@example -function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $ - c, d -@end example - -You can instruct IDLWAVE when to avoid using this special continuation -indentation by setting the variable -@code{idlwave-max-extra-continuation-indent}, which specifies the -maximum additional indentation beyond the basic indent to be -tolerated, otherwise defaulting to a fixed-offset from the enclosing -indent (the size of which offset is set in -@code{idlwave-continuation-indent}). As a special case, continuations -of routine calls without any arguments or keywords will @emph{not} -align the continued line, under the assumption that you continued -because you needed the space. - -Also, since the indentation level can be somewhat dynamic in continued -statements with special continuation indentation, especially if -@code{idlwave-max-extra-continuation-indent} is small, the key -@kbd{C-u @key{TAB}} will re-indent all lines in the current statement. -Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, -overrides the @code{idlwave-max-extra-continuation-indent} limit, for -parentheses only, forcing them always to line up. - - -@defopt idlwave-continuation-indent (@code{2}) -Extra indentation applied to normal continuation lines. -@end defopt - -@defopt idlwave-max-extra-continuation-indent (@code{20}) -The maximum additional indentation (over the basic continuation-indent) -that will be permitted for special continues. To effectively disable -special continuation indentation, set to @code{0}. To enable it -constantly, set to a large number (like @code{100}). Note that the -indentation in a long continued statement never decreases from line to -line, outside of nested parentheses statements. -@end defopt - -@defopt idlwave-indent-to-open-paren (@code{t}) -Non-@code{nil} means indent continuation lines to innermost open -parenthesis, regardless of whether the -@code{idlwave-max-extra-continuation-indent} limit is satisfied. -@end defopt - -@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting -@subsection Comment Indentation -@cindex Comment indentation -@cindex Hanging paragraphs -@cindex Paragraphs, filling -@cindex Paragraphs, hanging - -In IDL, lines starting with a @samp{;} are called @emph{comment lines}. -Comment lines are indented as follows: - -@multitable @columnfractions .1 .90 -@item @code{;;;} -@tab The indentation of lines starting with three semicolons remains -unchanged. -@item @code{;;} -@tab Lines starting with two semicolons are indented like the surrounding code. -@item @code{;} -@tab Lines starting with a single semicolon are indented to a minimum column. -@end multitable - -@noindent -The indentation of comments starting in column 0 is never changed. - -@defopt idlwave-no-change-comment -The indentation of a comment starting with this regexp will not be -changed. -@end defopt - -@defopt idlwave-begin-line-comment -A comment anchored at the beginning of line. -@end defopt - -@defopt idlwave-code-comment -A comment that starts with this regexp is indented as if it is a part of -IDL code. -@end defopt - -@node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting -@subsection Continuation Lines and Filling -@cindex Continuation lines -@cindex Line splitting -@cindex String splitting -@cindex Splitting, of lines - -@kindex M-@key{RET} -In IDL, a newline character terminates a statement unless preceded by a -@samp{$}. If you would like to start a continuation line, use -@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. -It inserts the continuation character @samp{$}, terminates the line and -indents the new line. The command @kbd{M-@key{RET}} can also be invoked -inside a string to split it at that point, in which case the @samp{+} -concatenation operator is used. - -@cindex Filling -@cindex @code{auto-fill-mode} -@cindex Hanging paragraphs -When filling comment paragraphs, IDLWAVE overloads the normal filling -functions and uses a function which creates the hanging paragraphs -customary in IDL routine headers. When @code{auto-fill-mode} is turned -on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the -first line of a paragraph contains a match for -@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent -lines are positioned to line up after it, as in the following example. - -@example -@group -;================================= -; x - an array containing -; lots of interesting numbers. -; -; y - another variable where -; a hanging paragraph is used -; to describe it. -;================================= -@end group -@end example - -@kindex M-q -You can also refill a comment at any time paragraph with @kbd{M-q}. -Comment delimiting lines as in the above example, consisting of one or -more @samp{;} followed by one or more of the characters @samp{+=-_*}, -are kept in place, as is. - -@defopt idlwave-fill-comment-line-only (@code{t}) -Non-@code{nil} means auto fill will only operate on comment lines. -@end defopt - -@defopt idlwave-auto-fill-split-string (@code{t}) -Non-@code{nil} means auto fill will split strings with the IDL @samp{+} -operator. -@end defopt - -@defopt idlwave-split-line-string (@code{t}) -Non-@code{nil} means @code{idlwave-split-line} will split strings with -@samp{+}. -@end defopt - -@defopt idlwave-hanging-indent (@code{t}) -Non-@code{nil} means comment paragraphs are indented under the hanging -indent given by @code{idlwave-hang-indent-regexp} match in the first -line of the paragraph. -@end defopt - -@defopt idlwave-hang-indent-regexp (@code{"- "}) -Regular expression matching the position of the hanging indent -in the first line of a comment paragraph. -@end defopt - -@defopt idlwave-use-last-hang-indent (@code{nil}) -Non-@code{nil} means use last match on line for -@code{idlwave-indent-regexp}. -@end defopt - -@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting -@subsection Syntax Highlighting -@cindex Syntax highlighting -@cindex Highlighting of syntax -@cindex Font lock - -Highlighting of keywords, comments, strings etc. can be accomplished -with @code{font-lock}. If you are using @code{global-font-lock-mode} -(in Emacs), or have @code{font-lock} turned on in any other buffer in -XEmacs, it should also automatically work in IDLWAVE buffers. If you'd -prefer invoking font-lock individually by mode, you can enforce it in -@code{idlwave-mode} with the following line in your @file{.emacs}: - -@lisp -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -@end lisp - -@noindent IDLWAVE supports 3 increasing levels of syntax highlighting. -The variable @code{font-lock-maximum-decoration} determines which level -is selected. Individual categories of special tokens can be selected -for highlighting using the variable -@code{idlwave-default-font-lock-items}. - -@defopt idlwave-default-font-lock-items -Items which should be fontified on the default fontification level -2. -@end defopt - -@node Octals and Highlighting, , Syntax Highlighting, Code Formatting -@subsection Octals and Highlighting -@cindex Syntax highlighting, Octals -@cindex Highlighting of syntax, Octals - -A rare syntax highlighting problem results from an extremely unfortunate -notation for octal numbers in IDL: @code{"123}. This unpaired quotation -mark is very difficult to parse, given that it can be mixed on a single -line with any number of strings. Emacs will incorrectly identify this -as a string, and the highlighting of following lines of code can be -distorted, since the string is never terminated. - -One solution to this involves terminating the mistakenly identified -string yourself by providing a closing quotation mark in a comment: - -@example - string("305B) + $ ;" <--- for font-lock - ' is an Angstrom.' -@end example - -@noindent A far better solution is to abandon this notation for octals -altogether, and use the more sensible alternative IDL provides: - -@example - string('305'OB) + ' is an Angstrom.' -@end example - -@noindent This simultaneously solves the font-lock problem and is more -consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. - -@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode -@section Routine Info -@cindex Routine info -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@kindex C-c C-i -IDL comes bundled with more than one thousand procedures, functions -and object methods, and large libraries typically contain hundreds or -even thousands more (each with a few to tens of keywords and -arguments). This large command set can make it difficult to remember -the calling sequence and keywords for the routines you use, but -IDLWAVE can help. It builds up routine information from a wide -variety of sources; IDLWAVE in fact knows far more about the -@samp{.pro} routines on your system than IDL itself! It maintains a -list of all built-in routines, with calling sequences and -keywords@footnote{This list is created by scanning the IDL manuals and -might contain (very few) errors. Please report any errors to the -maintainer, so that they can be fixed.}. It also scans Emacs buffers -for routine definitions, queries the IDLWAVE-Shell for information -about routines currently compiled there, and automatically locates -library and user-created catalogs. This information is updated -automatically, and so should usually be current. To force a global -update and refresh the routine information, use @kbd{C-c C-i} -(@code{idlwave-update-routine-info}). - -@kindex C-c ? -To display the information about a routine, press @kbd{C-c ?}, which -calls the command @code{idlwave-routine-info}. When the current cursor -position is on the name or in the argument list of a procedure or -function, information will be displayed about the routine. For example, -consider the indicated cursor positions in the following line: - -@example -plot,x,alog(x+5*sin(x) + 2), - | | | | | | | | - 1 2 3 4 5 6 7 8 -@end example - -@cindex Default routine, for info and help -On positions 1,2 and 8, information about the @samp{plot} procedure will -be shown. On positions 3,4, and 7, the @samp{alog} function will be -described, while positions 5 and 6 will investigate the @samp{sin} -function. - -When you ask for routine information about an object method, and the -method exists in several classes, IDLWAVE queries for the class of the -object, unless the class is already known through a text property on the -@samp{->} operator (@pxref{Object Method Completion and Class -Ambiguity}), or by having been explicitly included in the call -(e.g. @code{a->myclass::Foo}). - -@cindex Calling sequences -@cindex Keywords of a routine -@cindex Routine source information -The description displayed contains the calling sequence, the list of -keywords and the source location of this routine. It looks like this: - -@example -Usage: XMANAGER, NAME, ID -Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER - JUST_REG MODAL NO_BLOCK -Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro -@end example - -@cindex Categories, of routines -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -If a definition of this routine exists in several files accessible to -IDLWAVE, several @samp{Source} lines will point to the different -files. This may indicate that your routine is shadowing a system -library routine, which may or may not be what you want -(@pxref{Load-Path Shadows}). The information about the calling -sequence and keywords is derived from the first source listed. -Library routines are available only if you have scanned your local IDL -directories or are using pre-scanned libraries (@pxref{Catalogs}). -The source entry consists of a @emph{source category}, a set of -@emph{flags} and the path to the @emph{source file}. The following -default categories exist: - -@multitable @columnfractions .15 .85 -@item @i{System} -@tab A system routine of unknown origin. When the system library has -been scanned as part of a catalog (@pxref{Catalogs}), this category -will automatically split into the next two. -@item @i{Builtin} -@tab A builtin system routine with no source code available. -@item @i{SystemLib} -@tab A library system routine in the official lib directory @file{!DIR/lib}. -@item @i{Obsolete} -@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. -@item @i{Library} -@tab A routine in a file on IDL's search path @code{!PATH}. -@item @i{Other} -@tab Any other routine with a file not known to be on the search path. -@item @i{Unresolved} -@tab An otherwise unknown routine the shell lists as unresolved -(referenced, but not compiled). -@end multitable - -Any routines discovered in library catalogs (@pxref{Library -Catalogs}), will display the category assigned during creation, -e.g. @samp{NasaLib}. For routines not discovered in this way, you can -create additional categories based on the routine's filename using the -variable @code{idlwave-special-lib-alist}. - -@cindex Flags, in routine info -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -The flags @code{[LCSB]} indicate the source of the information IDLWAVE -has regarding the file: from a library catalog (@w{@code{[L---]}}), -from a user catalog (@w{@code{[-C--]}}, from the IDL Shell -(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). -Combinations are possible (a compiled library routine visited in a -buffer might read @w{@code{[L-SB]}}). If a file contains multiple -definitions of the same routine, the file name will be prefixed with -@samp{(Nx)} where @samp{N} is the number of definitions. - -@cindex Online Help from the routine info buffer -@cindex Active text, in routine info -@cindex Inserting keywords, from routine info -@cindex Source file, access from routine info -Some of the text in the @file{*Help*} routine info buffer will be active -(it is highlighted when the mouse moves over it). Typically, clicking -with the right mouse button invokes online help lookup, and clicking -with the middle mouse button inserts keywords or visits files: - -@multitable @columnfractions 0.15 0.85 -@item @i{Usage} -@tab If online help is installed, a click with the @emph{right} mouse -button on the @i{Usage:} line will access the help for the -routine (@pxref{Online Help}). -@item @i{Keyword} -@tab Online help about keywords is also available with the -@emph{right} mouse button. Clicking on a keyword with the @emph{middle} -mouse button will insert this keyword in the buffer from where -@code{idlwave-routine-info} was called. Holding down @key{SHIFT} while -clicking also adds the initial @samp{/}. -@item @i{Source} -@tab Clicking with the @emph{middle} mouse button on a @samp{Source} line -finds the source file of the routine and visits it in another window. -Another click on the same line switches back to the buffer from which -@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the -source will not be visited by a buffer, but displayed in the online help -window. -@item @i{Classes} -@tab The @i{Classes} line is only included in the routine info window if -the current class inherits from other classes. You can click with the -@emph{middle} mouse button to display routine info about the current -method in other classes on the inheritance chain, if such a method -exists there. -@end multitable - -@defopt idlwave-resize-routine-help-window (@code{t}) -Non-@code{nil} means resize the Routine-info @file{*Help*} window to -fit the content. -@end defopt - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories. -@end defopt - -@defopt idlwave-rinfo-max-source-lines (@code{5}) -Maximum number of source files displayed in the Routine Info window. -@end defopt - - -@html - -@end html -@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode -@section Online Help - -@cindex Online Help -@cindex @file{idlw-help.txt} -@cindex @file{idlw-help.el} -@cindex Installing online help -@cindex Online Help, Installation -@cindex Speed, of online help -@cindex XML Help Catalog - -For IDL system routines, extensive documentation is supplied with IDL. -IDLWAVE can access the HTML version of this documentation very quickly -and accurately, based on the local context. This can be @emph{much} -faster than using the IDL online help application, because IDLWAVE -usually gets you to the right place in the documentation directly --- -e.g. a specific keyword of a routine --- without any additional browsing -and scrolling. - -For this online help to work, an HTML version of the IDL documentation -is required. Beginning with IDL 6.2, HTML documentation is distributed -directly with IDL, along with an XML-based catalog of routine -information. By default, IDLWAVE automatically attempts to convert this -XML catalog into a format Emacs can more easily understand, and caches -this information in your @code{idlwave_config_directory} -(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if -it is newer than the current cached version. You can force rescan with -the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. - -Before IDL 6.2, the HTML help was not distributed with IDL, and was not -part of the standalone IDLWAVE distribution, but had to be downloaded -separately. This is no longer necessary: all help and routine -information is supplied with IDL versions 6.2 and later. - -There are a variety of options for displaying the HTML help: see below. -Help for routines without HTML documentation is also available, by using -the routine documentation header and/or routine source. - -@kindex M-? -In any IDL program (or, as with most IDLWAVE commands, in the IDL -Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with -@kbd{S-Mouse-3} to access context sensitive online help. The following -locations are recognized context for help: - -@cindex Context, for online help -@multitable @columnfractions .25 .75 -@item @i{Routine names} -@tab The name of a routine (function, procedure, method). -@item @i{Keyword Parameters} -@tab A keyword parameter of a routine. -@item @i{System Variables} -@tab System variables like @code{!DPI}. -@item @i{System Variable Tags} -@tab System variables tags like @code{!D.X_SIZE}. -@item @i{IDL Statements} -@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. -@item @i{IDL Controls} -@tab Control structures like @code{FOR}, @code{SWITCH}, etc. -@item @i{Class names} -@tab A class name in an @code{OBJ_NEW} call. -@item @i{Class Init Keywords} -@tab Beyond the class name in an @code{OBJ_NEW} call. -@item @i{Executive Command} -@tab An executive command like @code{.RUN}. Mostly useful in the shell. -@item @i{Structure Tags} -@tab Structure tags like @code{state.xsize} -@item @i{Class Tags} -@tab Class tags like @code{self.value}. -@item @i{Default} -@tab The routine that would be selected for routine info display. -@end multitable - -@cindex @code{OBJ_NEW}, special online help -Note that the @code{OBJ_NEW} function is special in that the help -displayed depends on the cursor position. If the cursor is on the -@samp{OBJ_NEW}, this function is described. If it is on the class -name inside the quotes, the documentation for the class is pulled up. -If the cursor is @emph{after} the class name, anywhere in the argument -list, the documentation for the corresponding @code{Init} method and -its keywords is targeted. - -Apart from an IDLWAVE buffer or shell, there are two more places from -which online help can be accessed. - -@itemize @bullet -@item -Online help for routines and keywords can be accessed through the -Routine Info display. Click with @kbd{Mouse-3} on an item to see the -corresponding help (@pxref{Routine Info}). -@item -When using completion and Emacs pops up a @file{*Completions*} buffer -with possible completions, clicking with @kbd{Mouse-3} on a completion -item invokes help on that item (@pxref{Completion}). Items for which -help is available in the online system documentation (vs. just the -program source itself) will be emphasized (e.g. colored blue). -@end itemize -@noindent -In both cases, a blue face indicates that the item is documented in -the IDL manual, but an attempt will be made to visit non-blue items -directly in the originating source file. - - -@menu -* Help with HTML Documentation:: -* Help with Source:: -@end menu - -@node Help with HTML Documentation, Help with Source, Online Help, Online Help -@subsection Help with HTML Documentation -@cindex HTML Help -@cindex Help using HTML manuals -@cindex IDL manual, HTML version -@cindex IDL Assistant - -Help using the HTML documentation is invoked with the built-in Emacs -command @code{browse-url}, which displays the relevant help topic in a -browser of your choosing. Beginning with version 6.2, IDL comes with -the help browser @emph{IDL Assistant}, which it uses by default for -displaying online help on all supported platforms. This browser -offers topical searches, an index, and is also now the default and -recommended IDLWAVE help browser. The variable -@code{idlwave-help-use-assistant} controls whether this browser is -used. Note that, due to limitations in the Assistant, invoking help -within IDLWAVE and @code{? topic} within IDL will result in two -running copies of Assistant. - -Aside from the IDL Assistant, there are many possible browsers to choose -among, with differing advantages and disadvantages. The variable -@code{idlwave-help-browser-function} controls which browser help is sent -to (as long as @code{idlwave-help-use-assistant} is not set). This -function is used to set the variable @code{browse-url-browser-function} -locally for IDLWAVE help only. Customize the latter variable to see -what choices of browsers your system offers. Certain browsers like -@code{w3} (bundled with many versions of Emacs) and @code{w3m} -(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use -Emacs buffers to display the HTML help. This can be convenient, -especially on small displays, and images can even be displayed in-line -on newer Emacs versions. However, better formatting results are often -achieved with external browsers, like Mozilla. IDLWAVE assumes any -browser function containing "w3" is displayed in a local buffer. If you -are using another Emacs-local browser for which this is not true, set -the variable @code{idlwave-help-browser-is-local}. - -With IDL 6.2 or later, it is important to ensure that the variable -@code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way -to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be -queried for this directory, and the results will be cached to file for -subsequent use. - -@xref{HTML Help Browser Tips}, for more information on selecting and -configuring a browser for use with IDL's HTML help system. - -@defopt idlwave-html-system-help-location @file{help/online_help} -Relative directory of the system-supplied HTML help directory, -considered with respect to @code{idlwave-system-directory}. Relevant -for IDL 6.2 and greater. Should not change. -@end defopt - -@defopt idlwave-html-help-location @file{/usr/local/etc/} -The directory where the @file{idl_html_help} HTML directory live. -Obsolete and ignored for IDL 6.2 and greater -(@code{idlwave-html-system-help-location} is used instead). -@end defopt - -@defopt idlwave-help-use-assistant @code{t} -If set, use the IDL Assistant if possible for online HTML help, -otherwise use the browser function specified in -@code{idlwave-help-browser-function}. -@end defopt - -@defopt idlwave-help-browser-function -The browser function to use to display IDLWAVE HTML help. Should be -one of the functions available for setting -@code{browse-url-browser-function}, which see. -@end defopt - -@defopt idlwave-help-browser-is-local -Is the browser selected in @code{idlwave-help-browser-function} run in a -local Emacs buffer or window? Defaults to @code{t} if the function -contains "-w3". -@end defopt - -@defopt idlwave-help-link-face -The face for links to IDLWAVE online help. -@end defopt - -@node Help with Source, , Help with HTML Documentation, Online Help -@subsection Help with Source -@cindex Help using routine source - -@cindex Source code, as online help -@cindex DocLib header, as online help -For routines which are not documented in an HTML manual (for example -personal or library routines), the source code itself is used as help -text. If the requested information can be found in a (more or less) -standard DocLib file header, IDLWAVE shows the header (scrolling down to -a keyword, if appropriate). Otherwise the routine definition statement -(@code{pro}/@code{function}) is shown. The doclib header sections which -are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization -support can be added by customizing the @code{idlwave-help-doclib-name} -and @code{idlwave-help-doclib-keyword} variables. - -@cindex Structure tags, in online help -@cindex Class tags, in online help -Help is also available for class structure tags (@code{self.TAG}), and -generic structure tags, if structure tag completion is enabled -(@pxref{Structure Tag Completion}). This is implemented by visiting the -tag within the class or structure definition source itself. Help is not -available on built-in system class tags. - -The help window is normally displayed in the same frame, but can be -popped-up in a separate frame. The following commands can be used to -navigate inside the help system for source files: - -@multitable @columnfractions .15 .85 -@item @kbd{@key{SPACE}} -@tab Scroll forward one page. -@item @kbd{@key{RET}} -@tab Scroll forward one line. -@item @kbd{@key{DEL}} -@tab Scroll back one page. -@item @kbd{h} -@tab Jump to DocLib Header of the routine whose source is displayed -as help. -@item @kbd{H} -@tab Jump to the first DocLib Header in the file. -@item @kbd{.} @r{(Dot)} -@tab Jump back and forth between the routine definition (the -@code{pro}/@code{function} statement) and the description of the help -item in the DocLib header. -@item @kbd{F} -@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. -@item @kbd{q} -@tab Kill the help window. -@end multitable - - -@defopt idlwave-help-use-dedicated-frame (@code{nil}) -Non-@code{nil} means use a separate frame for Online Help if possible. -@end defopt - -@defopt idlwave-help-frame-parameters -The frame parameters for the special Online Help frame. -@end defopt - -@defopt idlwave-max-popup-menu-items (@code{20}) -Maximum number of items per pane in pop-up menus. -@end defopt - -@defopt idlwave-extra-help-function -Function to call for help if the normal help fails. -@end defopt - -@defopt idlwave-help-fontify-source-code (@code{nil}) -Non-@code{nil} means fontify source code displayed as help. -@end defopt - -@defopt idlwave-help-source-try-header (@code{t}) -Non-@code{nil} means try to find help in routine header when -displaying source file. -@end defopt - -@defopt idlwave-help-doclib-name (@code{"name"}) -The case-insensitive heading word in doclib headers to locate the -@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. -@end defopt - -@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) -The case-insensitive heading word in doclib headers to locate the -@emph{keywords} section. Can be a regexp. -@end defopt - - -@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode -@section Completion -@cindex Completion -@cindex Keyword completion -@cindex Method completion -@cindex Object method completion -@cindex Class name completion -@cindex Function name completion -@cindex Procedure name completion - -@kindex M-@key{TAB} -@kindex C-c C-i -IDLWAVE offers completion for class names, routine names, keywords, -system variables, system variable tags, class structure tags, regular -structure tags and file names. As in many programming modes, completion -is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE -Shell --- @pxref{Using the Shell}). Completion uses exactly the same -internal information as routine info, so when necessary (rarely) it can -be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). - -The completion function is context sensitive and figures out what to -complete based on the location of the point. Here are example lines and -what @kbd{M-@key{TAB}} would try to complete when the cursor is on the -position marked with a @samp{_}: - -@example -plo_ @r{Procedure} -x = a_ @r{Function} -plot,xra_ @r{Keyword of @code{plot} procedure} -plot,x,y,/x_ @r{Keyword of @code{plot} procedure} -plot,min(_ @r{Keyword of @code{min} function} -obj -> a_ @r{Object method (procedure)} -a[2,3] = obj -> a_ @r{Object method (function)} -x = obj_new('IDL_ @r{Class name} -x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} -pro A_ @r{Class name} -pro _ @r{Fill in @code{Class::} of first method in this file} -!v_ @r{System variable} -!version.t_ @r{Structure tag of system variable} -self.g_ @r{Class structure tag in methods} -state.w_ @r{Structure tag, if tag completion enabled} -name = 'a_ @r{File name (default inside quotes)} -@end example - -@cindex Completion, ambiguity -@cindex Completion, forcing function name -The only place where completion is ambiguous is procedure/function -@emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE -will always assume a keyword to @samp{plot}. However, a function is -also a possible completion here. You can force completion of a function -name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. - -Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a -regular expression to search among the commands to be completed. As -an example, completing a blank line in this way will allow you to -search for a procedure matching a regexp. - -@cindex Scrolling the @file{*Completions*} window -@cindex Completion, scrolling -@cindex Completion, Online Help -@cindex Online Help in @file{*Completions*} buffer -If the list of completions is too long to fit in the -@file{*Completions*} window, the window can be scrolled by pressing -@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each -possible completion is available by clicking with @kbd{Mouse-3} on the -item. Items for which system online help (from the IDL manual) is -available will be emphasized (e.g. colored blue). For other items, the -corresponding source code or DocLib header will be used as the help -text. - -@cindex Completion, cancelling -@cindex Cancelling completion -Completion is not a blocking operation --- you are free to continue -editing, enter commands, or simply ignore the @file{*Completions*} -buffer during a completion operation. If, however, the most recent -command was a completion, @kbd{C-g} will remove the buffer and restore -the window configuration. You can also remove the buffer at any time -with no negative consequences. - -@defopt idlwave-keyword-completion-adds-equal (@code{t}) -Non-@code{nil} means completion automatically adds @samp{=} after -completed keywords. -@end defopt - -@defopt idlwave-function-completion-adds-paren (@code{t}) -Non-@code{nil} means completion automatically adds @samp{(} after -completed function. A value of `2' means also add the closing -parenthesis and position the cursor between the two. -@end defopt - -@defopt idlwave-completion-restore-window-configuration (@code{t}) -Non-@code{nil} means restore window configuration after successful -completion. -@end defopt - -@defopt idlwave-highlight-help-links-in-completion (@code{t}) -Non-@code{nil} means highlight completions for which system help is -available. -@end defopt - -@menu -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag -@end menu - -@node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion -@subsection Case of Completed Words -@cindex Case of completed words -@cindex Mixed case completion -IDL is a case-insensitive language, so casing is a matter of style -only. IDLWAVE helps maintain a consistent casing style for completed -items. The case of the completed words is determined by what is -already in the buffer. As an exception, when the partial word being -completed is all lower case, the completion will be lower case as -well. If at least one character is upper case, the string will be -completed in upper case or mixed case, depending on the value of the -variable @code{idlwave-completion-case}. The default is to use upper -case for procedures, functions and keywords, and mixed case for object -class names and methods, similar to the conventions in the IDL -manuals. For instance, to enable mixed-case completion for routines -in addition to classes and methods, you need an entry such as -@code{(routine . preserve)} in that variable. To enable total control -over the case of completed items, independent of buffer context, set -@code{idlwave-completion-force-default-case} to non-@code{nil}. - -@defopt idlwave-completion-case -Association list setting the case (UPPER/lower/Capitalized/MixedCase...) -of completed words. -@end defopt - -@defopt idlwave-completion-force-default-case (@code{nil}) -Non-@code{nil} means completion will always honor the settings in -@code{idlwave-completion-case}. When nil (the default), entirely lower -case strings will always be completed to lower case, no matter what the -settings in @code{idlwave-completion-case}. -@end defopt - -@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) -Non-@code{nil} means the empty string is considered lower case for -completion. -@end defopt - -@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion -@subsection Object Method Completion and Class Ambiguity -@cindex Object methods -@cindex Class ambiguity -@cindex @code{self} object, default class -An object method is not uniquely determined without the object's class. -Since the class is almost always omitted in the calling source (as -required to obtain the true benefits of object-based programming), -IDLWAVE considers all available methods in all classes as possible -method name completions. The combined list of keywords of the current -method in @emph{all} known classes which contain that method will be -considered for keyword completion. In the @file{*Completions*} buffer, -the matching classes will be shown next to each item (see option -@code{idlwave-completion-show-classes}). As a special case, the class -of an object called @samp{self} is always taken to be the class of the -current routine, when in an IDLWAVE buffer. All inherits classes are -considered as well. - -@cindex Forcing class query. -@cindex Class query, forcing -You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u -M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to -narrow down the number of possible completions. The variable -@code{idlwave-query-class} can be configured to make such prompting the -default for all methods (not recommended), or selectively for very -common methods for which the number of completing keywords would be too -large (e.g. @code{Init,SetProperty,GetProperty}). - -@cindex Saving object class on @code{->} -@cindex @code{->} -After you have specified the class for a particular statement (e.g. when -completing the method), IDLWAVE can remember it for the rest of the -editing session. Subsequent completions in the same statement -(e.g. keywords) can then reuse this class information. This works by -placing a text property on the method invocation operator @samp{->}, -after which the operator will be shown in a different face (bold by -default). The variable @code{idlwave-store-inquired-class} can be used -to turn it off or on. - -@defopt idlwave-completion-show-classes (@code{1}) -Non-@code{nil} means show up to that many classes in -@file{*Completions*} buffer when completing object methods and -keywords. -@end defopt - -@defopt idlwave-completion-fontify-classes (@code{t}) -Non-@code{nil} means fontify the classes in completions buffer. -@end defopt - -@defopt idlwave-query-class (@code{nil}) -Association list governing query for object classes during completion. -@end defopt - -@defopt idlwave-store-inquired-class (@code{t}) -Non-@code{nil} means store class of a method call as text property on -@samp{->}. -@end defopt - -@defopt idlwave-class-arrow-face -Face to highlight object operator arrows @samp{->} which carry a saved -class text property. -@end defopt - -@node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion -@subsection Object Method Completion in the Shell -@cindex Method Completion in Shell -In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which -methods are being invoked have a special property: they must exist as -variables, and so their class can be determined (for instance, using the -@code{obj_class()} function). In the Shell, when attempting completion, -routine info, or online help within a method routine, a query is sent to -determine the class of the object. If this query is successful, the -class found will be used to select appropriate completions, routine -info, or help. If unsuccessful, information from all known classes will -be used (as in the buffer). - -@node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion -@subsection Class and Keyword Inheritance -@cindex Inheritance, class -@cindex Keyword inheritance -@cindex Inheritance, keyword - -Class inheritance affects which methods are called in IDL. An object of -a class which inherits methods from one or more superclasses can -override that method by defining its own method of the same name, extend -the method by calling the method(s) of its superclass(es) in its -version, or inherit the method directly by making no modifications. -IDLWAVE examines class definitions during completion and routine -information display, and records all inheritance information it finds. -This information is displayed if appropriate with the calling sequence -for methods (@pxref{Routine Info}), as long as variable -@code{idlwave-support-inheritance} is non-@code{nil}. - -In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and -@code{_REF_EXTRA}) is used hand-in-hand with class inheritance and -method overriding. E.g., in a @code{SetProperty} method, this technique -allows a single call @code{obj->SetProperty} to set properties up the -entire class inheritance chain. This is often referred to as -@emph{chaining}, and is characterized by chained method calls like -@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. - -IDLWAVE can accommodate this special synergy between class and keyword -inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a -method's keyword parameters, all keywords of superclass versions of -the method being considered can be included in completion. There is -of course no guarantee that this type of keyword chaining actually -occurs, but for some methods it's a very convenient assumption. The -variable @code{idlwave-keyword-class-inheritance} can be used to -configure which methods have keyword inheritance treated in this -simple, class-driven way. By default, only @code{Init} and -@code{(Get|Set)Property} are. The completion buffer will label -keywords based on their originating class. - -@defopt idlwave-support-inheritance (@code{t}) -Non-@code{nil} means consider inheritance during completion, online help etc. -@end defopt - -@defopt idlwave-keyword-class-inheritance -A list of regular expressions to match methods for which simple -class-driven keyword inheritance will be used for Completion. -@end defopt - -@node Structure Tag Completion, , Class and Keyword Inheritance, Completion -@subsection Structure Tag Completion -@cindex Completion, structure tag -@cindex Structure tag completion - -In many programs, especially those involving widgets, large structures -(e.g. the @samp{state} structure) are used to communicate among -routines. It is very convenient to be able to complete structure tags, -in the same way as for instance variables (tags) of the @samp{self} -object (@pxref{Object Method Completion and Class Ambiguity}). Add-in -code for structure tag completion is available in the form of a loadable -completion module: @file{idlw-complete-structtag.el}. Tag completion in -structures is highly ambiguous (much more so than @samp{self} -completion), so @code{idlw-complete-structtag} makes an unusual and very -specific assumption: the exact same variable name is used to refer to -the structure in all parts of the program. This is entirely unenforced -by the IDL language, but is a typical convention. If you consistently -refer to the same structure with the same variable name -(e.g. @samp{state}), structure tags which are read from its definition -in the same file can be used for completion. - -Structure tag completion is not enabled by default. To enable it, -simply add the following to your @file{.emacs}: - -@lisp - (add-hook 'idlwave-load-hook - (lambda () (require 'idlw-complete-structtag))) -@end lisp - -Once enabled, you'll also be able to access online help on the structure -tags, using the usual methods (@pxref{Online Help}). In addition, -structure variables in the shell will be queried for tag names, similar -to the way object variables in the shell are queried for method names. -So, e.g.: - -@example -IDL> st.[Tab] -@end example - -@noindent will complete with all structure fields of the structure -@code{st}. - -@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode -@section Routine Source -@cindex Routine source file -@cindex Module source file -@cindex Source file, of a routine -@kindex C-c C-v -In addition to clicking on a @i{Source:} line in the routine info -window, there is another way to quickly visit the source file of a -routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks -for a module name, offering the same default as -@code{idlwave-routine-info} would have used, taken from nearby buffer -contents. In the minibuffer, specify a complete routine name (including -any class part). IDLWAVE will display the source file in another -window, positioned at the routine in question. You can also limit this -to a routine in the current buffer only, with completion, and a -context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) -or the convenience binding @kbd{C-c C-t}. - -@cindex Buffers, killing -@cindex Killing autoloaded buffers -Since getting the source of a routine into a buffer is so easy with -IDLWAVE, too many buffers visiting different IDL source files are -sometimes created. The special command @kbd{C-c C-k} -(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove -these buffers. - -@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode -@section Resolving Routines -@cindex @code{RESOLVE_ROUTINE} -@cindex Compiling library modules -@cindex Routines, resolving - -The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} -and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL -in order to resolve (compile) it. The default routine to be resolved is -taken from context, but you get a chance to edit it. Usually this is -not necessary, since IDL automatically discovers routines on its path. - -@code{idlwave-resolve} is one way to get a library module within reach -of IDLWAVE's routine info collecting functions. A better way is to -keep routine information available in catalogs (@pxref{Catalogs}). -Routine info on modules will then be available without the need to -compile the modules first, and even without a running shell. - -@xref{Sources of Routine Info}, for more information on the ways IDLWAVE -collects data about routines, and how to update this information. - -@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode -@section Code Templates -@cindex Code templates -@cindex Templates - -IDLWAVE can insert IDL code templates into the buffer. For a few -templates, this is done with direct key bindings: - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-c} -@tab @code{CASE} statement template -@item @kbd{C-c C-f} -@tab @code{FOR} loop template -@item @kbd{C-c C-r} -@tab @code{REPEAT} loop template -@item @kbd{C-c C-w} -@tab @code{WHILE} loop template -@end multitable - -All code templates are also available as abbreviations -(@pxref{Abbreviations}). - -@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode -@section Abbreviations -@cindex Abbreviations - -Special abbreviations exist to enable rapid entry of commonly used -commands. Emacs abbreviations are expanded by typing text into the -buffer and pressing @key{SPC} or @key{RET}. The special abbreviations -used to insert code templates all start with a @samp{\} (the backslash), -or, optionally, any other character set in -@code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are -only expanded where they should be (i.e., not in a string or comment), -and permits the point to be moved after an abbreviation expansion --- -very useful for positioning the mark inside of parentheses, etc. - -Special abbreviations are pre-defined for code templates and other -useful items. To visit the full list of abbreviations, use @kbd{M-x -idlwave-list-abbrevs}. - -Template abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\pr} -@tab @code{PROCEDURE} template -@item @code{\fu} -@tab @code{FUNCTION} template -@item @code{\c} -@tab @code{CASE} statement template -@item @code{\f} -@tab @code{FOR} loop template -@item @code{\r} -@tab @code{REPEAT} loop template -@item @code{\w} -@tab @code{WHILE} loop template -@item @code{\i} -@tab @code{IF} statement template -@item @code{\elif} -@tab @code{IF-ELSE} statement template -@end multitable - -String abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\ap} -@tab @code{arg_present()} -@item @code{\b} -@tab @code{begin} -@item @code{\cb} -@tab @code{byte()} -@item @code{\cc} -@tab @code{complex()} -@item @code{\cd} -@tab @code{double()} -@item @code{\cf} -@tab @code{float()} -@item @code{\cl} -@tab @code{long()} -@item @code{\co} -@tab @code{common} -@item @code{\cs} -@tab @code{string()} -@item @code{\cx} -@tab @code{fix()} -@item @code{\e} -@tab @code{else} -@item @code{\ec} -@tab @code{endcase} -@item @code{\ee} -@tab @code{endelse} -@item @code{\ef} -@tab @code{endfor} -@item @code{\ei} -@tab @code{endif else if} -@item @code{\el} -@tab @code{endif else} -@item @code{\en} -@tab @code{endif} -@item @code{\er} -@tab @code{endrep} -@item @code{\es} -@tab @code{endswitch} -@item @code{\ew} -@tab @code{endwhile} -@item @code{\g} -@tab @code{goto,} -@item @code{\h} -@tab @code{help,} -@item @code{\ik} -@tab @code{if keyword_set() then} -@item @code{\iap} -@tab @code{if arg_present() then} -@item @code{\ine} -@tab @code{if n_elements() eq 0 then} -@item @code{\inn} -@tab @code{if n_elements() ne 0 then} -@item @code{\k} -@tab @code{keyword_set()} -@item @code{\n} -@tab @code{n_elements()} -@item @code{\np} -@tab @code{n_params()} -@item @code{\oi} -@tab @code{on_ioerror,} -@item @code{\or} -@tab @code{openr,} -@item @code{\ou} -@tab @code{openu,} -@item @code{\ow} -@tab @code{openw,} -@item @code{\p} -@tab @code{print,} -@item @code{\pt} -@tab @code{plot,} -@item @code{\pv} -@tab @code{ptr_valid()} -@item @code{\re} -@tab @code{read,} -@item @code{\rf} -@tab @code{readf,} -@item @code{\rt} -@tab @code{return} -@item @code{\ru} -@tab @code{readu,} -@item @code{\s} -@tab @code{size()} -@item @code{\sc} -@tab @code{strcompress()} -@item @code{\sl} -@tab @code{strlowcase()} -@item @code{\sm} -@tab @code{strmid()} -@item @code{\sn} -@tab @code{strlen()} -@item @code{\sp} -@tab @code{strpos()} -@item @code{\sr} -@tab @code{strtrim()} -@item @code{\st} -@tab @code{strput()} -@item @code{\su} -@tab @code{strupcase()} -@item @code{\t} -@tab @code{then} -@item @code{\u} -@tab @code{until} -@item @code{\wc} -@tab @code{widget_control,} -@item @code{\wi} -@tab @code{widget_info()} -@item @code{\wu} -@tab @code{writeu,} -@end multitable - -@noindent You can easily add your own abbreviations or override existing -abbrevs with @code{define-abbrev} in your mode hook, using the -convenience function @code{idlwave-define-abbrev}: - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - (idlwave-define-abbrev "wb" "widget_base()" - (idlwave-keyword-abbrev 1)) - (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" - (idlwave-keyword-abbrev 11)))) -@end lisp - -Notice how the abbreviation (here @emph{wb}) and its expansion -(@emph{widget_base()}) are given as arguments, and the single argument to -@code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to -move the point upon expansion (in this example, to put it between the -parentheses). - -The abbreviations are expanded in upper or lower case, depending upon -the variables @code{idlwave-abbrev-change-case} and, for reserved word -templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). - -@defopt idlwave-abbrev-start-char (@code{"\"}) -A single character string used to start abbreviations in abbrev mode. -Beware of common characters which might naturally occur in sequence with -abbreviation strings. -@end defopt - -@defopt idlwave-abbrev-move (@code{t}) -Non-@code{nil} means the abbrev hook can move point, e.g. to end up -between the parentheses of a function call. -@end defopt - -@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode -@section Actions -@cindex Actions -@cindex Coding standards, enforcing - -@emph{Actions} are special formatting commands which are executed -automatically while you write code in order to check the structure of -the program or to enforce coding standards. Most actions which have -been implemented in IDLWAVE are turned off by default, assuming that the -average user wants her code the way she writes it. But if you are a -lazy typist and want your code to adhere to certain standards, actions -can be helpful. - -Actions can be applied in three ways: - -@itemize @bullet -@item -Some actions are applied directly while typing. For example, pressing -@samp{=} can run a check to make sure that this operator is surrounded -by spaces and insert these spaces if necessary. Pressing @key{SPC} -after a reserved word can call a command to change the word to upper -case. -@item -When a line is re-indented with @key{TAB}, actions can be applied to the -entire line. To enable this, the variable @code{idlwave-do-actions} -must be non-@code{nil}. -@item -@cindex Foreign code, adapting -@cindex Actions, applied to foreign code -Actions can also be applied to a larger piece of code, e.g. to convert -foreign code to your own style. To do this, mark the relevant part of -the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). @xref{Code Indentation}, for information how to adjust the -indentation of the code. -@end itemize - -@defopt idlwave-do-actions (@code{nil}) -Non-@code{nil} means performs actions when indenting. Individual action -settings are described below and set separately. -@end defopt - -@menu -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords -@end menu - -@node Block Boundary Check, Padding Operators, Actions, Actions -@subsection Block Boundary Check -@cindex Block boundary check -@cindex @code{END} type checking -@cindex @code{END}, automatic insertion -@cindex @code{END}, expanding -@cindex Block, closing -@cindex Closing a block - -Whenever you type an @code{END} statement, IDLWAVE finds the -corresponding start of the block and the cursor blinks back to that -location for a second. If you have typed a specific @code{END}, like -@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator -does not match the type of block it terminates. - -Set the variable @code{idlwave-expand-generic-end} in order to have all -generic @code{END} statements automatically expanded to the appropriate -type. You can also type @kbd{C-c ]} to close the current block by -inserting the appropriate @code{END} statement. - -@defopt idlwave-show-block (@code{t}) -Non-@code{nil} means point blinks to block beginning for -@code{idlwave-show-begin}. -@end defopt - -@defopt idlwave-expand-generic-end (@code{t}) -Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. -@end defopt - -@defopt idlwave-reindent-end (@code{t}) -Non-@code{nil} means re-indent line after END was typed. -@end defopt - -@node Padding Operators, Case Changes, Block Boundary Check, Actions -@subsection Padding Operators -@cindex Padding operators with spaces -@cindex Operators, padding with spaces -@cindex Space, around operators - -Some operators can be automatically surrounded by spaces. This can -happen when the operator is typed, or later when the line is indented. -IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, -and @samp{->}, as well as the modified assignment operators -(@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. -If you want to turn it on, customize the variables -@code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn -both on. You can also define similar actions for other operators by -using the function @code{idlwave-action-and-binding} in the mode hook. -For example, to enforce space padding of the @samp{+} and @samp{*} -operators (outside of strings and comments, of course), try this in -@file{.emacs} - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - (setq idlwave-surround-by-blank t) ; Turn this type of actions on - (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) - (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) -@end lisp - -Note that the modified assignment operators which begin with a word -(@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to -be recognized (e.g @code{vAND=4} would be interpreted as a variable -@code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are -both valid operators, it is impossible to surround both by blanks while -they are being typed. Similarly with @code{&} and @code{&&}. For -these, a compromise is made: the padding is placed on the left, and if -the longer operator is keyed in, on the right as well (otherwise you -must insert spaces to pad right yourself, or press simply press Tab to -repad everything if @code{idlwave-do-actions} is on). - -@defopt idlwave-surround-by-blank (@code{nil}) -Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, -@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the -modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are -surrounded with spaces by @code{idlwave-surround}. -@end defopt - -@defopt idlwave-pad-keyword (@code{t}) -Non-@code{nil} means space-pad the @samp{=} in keyword assignments. -@end defopt - -@node Case Changes, , Padding Operators, Actions -@subsection Case Changes -@cindex Case changes -@cindex Upcase, enforcing for reserved words -@cindex Downcase, enforcing for reserved words - -Actions can be used to change the case of reserved words or expanded -abbreviations by customizing the variables -@code{idlwave-abbrev-change-case} and -@code{idlwave-reserved-word-upcase}. If you want to change the case of -additional words automatically, put something like the following into -your @file{.emacs} file: - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - ;; Capitalize system vars - (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) - ;; Capitalize procedure name - (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" - '(capitalize-word 1) t) - ;; Capitalize common block name - (idlwave-action-and-binding "\\[ \t]+\\<" - '(capitalize-word 1) t))) -@end lisp - -For more information, see the documentation string for the function -@code{idlwave-action-and-binding}. For information on controlling the -case of routines, keywords, classes, and methods as they are completed, see -@ref{Completion}. - -@defopt idlwave-abbrev-change-case (@code{nil}) -Non-@code{nil} means all abbrevs will be forced to either upper or lower -case. Valid values are @code{nil}, @code{t}, and @code{down}. -@end defopt - -@defopt idlwave-reserved-word-upcase (@code{nil}) -Non-@code{nil} means reserved words will be made upper case via abbrev -expansion. -@end defopt - - -@node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode -@section Documentation Header -@cindex Documentation header -@cindex DocLib header -@cindex Modification timestamp -@cindex Header, for file documentation -@cindex Timestamp, in doc header. -@cindex Changelog, in doc header. - -@kindex C-c C-h -@kindex C-c C-m -The command @kbd{C-c C-h} inserts a standard routine header into the -buffer, with the usual fields for documentation (a different header can -be specified with @code{idlwave-file-header}). One of the keywords is -@samp{MODIFICATION HISTORY} under which the changes to a routine can be -recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION -HISTORY} of the current routine or file and inserts the user name with a -timestamp. - -@defopt idlwave-file-header -The doc-header template or a path to a file containing it. -@end defopt - -@defopt idlwave-header-to-beginning-of-file (@code{nil}) -Non-@code{nil} means the documentation header will always be at start -of file. -@end defopt - -@defopt idlwave-timestamp-hook -The hook function used to update the timestamp of a function. -@end defopt - -@defopt idlwave-doc-modifications-keyword -The modifications keyword to use with the log documentation commands. -@end defopt - -@defopt idlwave-doclib-start -Regexp matching the start of a document library header. -@end defopt - -@defopt idlwave-doclib-end -Regexp matching the start of a document library header. -@end defopt - -@node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode -@section Motion Commands -@cindex Motion commands -@cindex Program structure, moving through -@cindex Code structure, moving through -@cindex @file{Func-menu}, XEmacs package -@cindex @file{Imenu}, Emacs package -@cindex Function definitions, jumping to -@cindex Procedure definitions, jumping to - -IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages -which make it easy to jump to the definitions of functions and -procedures in the current file with a pop-up selection. To bind -@file{Imenu} to a mouse-press, use in your @file{.emacs}: - -@lisp -(define-key global-map [S-down-mouse-3] 'imenu) -@end lisp - -@cindex @file{Speedbar}, Emacs package - -In addition, @file{Speedbar} support allows convenient navigation of a -source tree of IDL routine files, quickly stepping to routine -definitions. See @code{Tools->Display Speedbar}. - -Several commands allow you to move quickly through the structure of an -IDL program: - -@multitable @columnfractions .15 .85 -@item @kbd{C-M-a} -@tab Beginning of subprogram -@item @kbd{C-M-e} -@tab End of subprogram -@item @kbd{C-c @{} -@tab Beginning of block (stay inside the block) -@item @kbd{C-c @}} -@tab End of block (stay inside the block) -@item @kbd{C-M-n} -@tab Forward block (on same level) -@item @kbd{C-M-p} -@tab Backward block (on same level) -@item @kbd{C-M-d} -@tab Down block (enters a block) -@item @kbd{C-M-u} -@tab Backward up block (leaves a block) -@item @kbd{C-c C-n} -@tab Next Statement -@end multitable - - -@node Misc Options, , Motion Commands, The IDLWAVE Major Mode -@section Miscellaneous Options -@cindex Hooks - -@defopt idlwave-help-application -The external application providing reference help for programming. -@end defopt - -@defopt idlwave-startup-message (@code{t}) -Non-@code{nil} means display a startup message when @code{idlwave-mode}' -is first called. -@end defopt - -@defopt idlwave-mode-hook -Normal hook. Executed when a buffer is put into @code{idlwave-mode}. -@end defopt - -@defopt idlwave-load-hook -Normal hook. Executed when @file{idlwave.el} is loaded. -@end defopt - -@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top -@chapter The IDLWAVE Shell -@cindex IDLWAVE shell -@cindex Major mode, @code{idlwave-shell-mode} -@cindex IDL, as Emacs subprocess -@cindex Subprocess of Emacs, IDL -@cindex Comint, Emacs package -@cindex Windows -@cindex MacOS - -The IDLWAVE shell is an Emacs major mode which permits running the IDL -program as an inferior process of Emacs, and works closely with the -IDLWAVE major mode in buffers. It can be used to work with IDL -interactively, to compile and run IDL programs in Emacs buffers and to -debug these programs. The IDLWAVE shell is built on @file{comint}, an -Emacs packages which handles the communication with the IDL program. -Unfortunately, IDL for Windows does not have command-prompt versions and -thus do not allow the interaction with Emacs --- so the IDLWAVE shell -currently only works under Unix and MacOSX. - -@menu -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: -@end menu - -@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell -@section Starting the Shell -@cindex Starting the shell -@cindex Shell, starting -@cindex Dedicated frame, for shell buffer -@cindex Frame, for shell buffer -@cindex Subprocess of Emacs, IDL - -@kindex C-c C-s -The IDLWAVE shell can be started with the command @kbd{M-x -idlwave-shell}. In @code{idlwave-mode} the function is bound to -@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to -interact with the shell. If the shell is already running, @kbd{C-c -C-s} will simply switch to the shell buffer. The command @kbd{C-c -C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell -window without selecting it. The shell can also be started -automatically when another command tries to send a command to it. To -enable auto start, set the variable -@code{idlwave-shell-automatic-start} to @code{t}. - -In order to create a separate frame for the IDLWAVE shell buffer, call -@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or -@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell -window, configure the variable -@code{idlwave-shell-use-dedicated-frame}. - -To launch a quick IDLWAVE shell directly from a shell prompt without -an IDLWAVE buffer (e.g., as a replacement for running inside an -xterm), define a system alias with the following content: - -@example -emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" -@end example - -Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer -the Emacs process to run directly inside the terminal window. - -@cindex ENVI -@cindex IDL> Prompt - -To use IDLWAVE with ENVI or other custom packages which change the -@samp{IDL> } prompt, you must change the -@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> -"}. Normally, you can just replace the @samp{IDL} in this expression -with the prompt you see. A suitable pattern which matches the prompt -for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. - -@defopt idlwave-shell-explicit-file-name (@file{idl}) -This is the command to run IDL. -@end defopt - -@defopt idlwave-shell-command-line-options -A list of command line options for calling the IDL program. -@end defopt - -@defopt idlwave-shell-prompt-pattern -Regexp to match IDL prompt at beginning of a line. -@end defopt - -@defopt idlwave-shell-process-name -Name to be associated with the IDL process. -@end defopt - -@defopt idlwave-shell-automatic-start (@code{nil}) -Non-@code{nil} means attempt to invoke idlwave-shell if not already -running. -@end defopt - -@defopt idlwave-shell-initial-commands -Initial commands, separated by newlines, to send to IDL. -@end defopt - -@defopt idlwave-shell-save-command-history (@code{t}) -Non-@code{nil} means preserve command history between sessions. -@end defopt - -@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) -The file in which the command history of the idlwave shell is saved. -Unless it's an absolute path, it goes in -@code{idlwave-config-directory}. -@end defopt - -@defopt idlwave-shell-use-dedicated-frame (@code{nil}) -Non-@code{nil} means IDLWAVE should use a special frame to display the -shell buffer. -@end defopt - -@defopt idlwave-shell-use-dedicated-window (@code{nil}) -Non-@code{nil} means use a dedicated window for the shell, taking care -not it replace it with other buffers. -@end defopt - -@defopt idlwave-shell-frame-parameters -The frame parameters for a dedicated idlwave-shell frame. -@end defopt - -@defopt idlwave-shell-raise-frame (@code{t}) -Non-@code{nil} means `idlwave-shell' raises the frame showing the shell -window. -@end defopt - -@defopt idlwave-shell-temp-pro-prefix -The prefix for temporary IDL files used when compiling regions. -@end defopt - -@cindex Hooks -@defopt idlwave-shell-mode-hook -Hook for customizing @code{idlwave-shell-mode}. -@end defopt - -@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell -@section Using the Shell -@cindex Comint -@cindex Shell, basic commands - -The IDLWAVE shell works in the same fashion as other shell modes in -Emacs. It provides command history, command line editing and job -control. The @key{UP} and @key{DOWN} arrows cycle through the input -history just like in an X terminal@footnote{This is different from -normal Emacs/Comint behavior, but more like an xterm. If you prefer the -default comint functionality, check the variable -@code{idlwave-shell-arrows-do-history}.}. The history is preserved -between emacs and IDL sessions. Here is a list of commonly used -commands: - -@multitable @columnfractions .12 .88 -@item @key{UP}, @key{M-p} -@tab Cycle backwards in input history -@item @key{DOWN}, @key{M-n} -@tab Cycle forwards in input history -@item @kbd{M-r} -@tab Previous input matching a regexp -@item @kbd{M-s} -@tab Next input matching a regexp -@item @kbd{return} -@tab Send input or copy line to current prompt -@item @kbd{C-c C-a} -@tab Beginning of line; skip prompt -@item @kbd{C-c C-u} -@tab Kill input to beginning of line -@item @kbd{C-c C-w} -@tab Kill word before cursor -@item @kbd{C-c C-c} -@tab Send ^C -@item @kbd{C-c C-z} -@tab Send ^Z -@item @kbd{C-c C-\} -@tab Send ^\ -@item @kbd{C-c C-o} -@tab Delete last batch of process output -@item @kbd{C-c C-r} -@tab Show last batch of process output -@item @kbd{C-c C-l} -@tab List input history -@end multitable - -In addition to these standard @file{comint} commands, -@code{idlwave-shell-mode} provides many of the same commands which -simplify writing IDL code available in IDLWAVE buffers. This includes -abbreviations, online help, and completion. See @ref{Routine Info} and -@ref{Online Help} and @ref{Completion} for more information on these -commands. - -@cindex Completion, in the shell -@cindex Routine info, in the shell -@cindex Online Help, in the shell -@multitable @columnfractions .12 .88 -@item @kbd{@key{TAB}} -@tab Completion of file names (between quotes and after executive -commands @samp{.run} and @samp{.compile}), routine names, class names, -keywords, system variables, system variable tags etc. -(@code{idlwave-shell-complete}). -@item @kbd{M-@key{TAB}} -@tab Same as @key{TAB} -@item @kbd{C-c ?} -@tab Routine Info display (@code{idlwave-routine-info}) -@item @kbd{M-?} -@tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) -@item @kbd{C-c C-i} -@tab Update routine info from buffers and shell -(@code{idlwave-update-routine-info}) -@item @kbd{C-c C-v} -@tab Find the source file of a routine (@code{idlwave-find-module}) -@item @kbd{C-c C-t} -@tab Find the source file of a routine in the currently visited file -(@code{idlwave-find-module-this-file}). -@item @kbd{C-c =} -@tab Compile a library routine (@code{idlwave-resolve}) -@end multitable - -@defopt idlwave-shell-arrows-do-history (@code{t}) -Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command -history like xterm. -@end defopt - -@defopt idlwave-shell-comint-settings -Alist of special settings for the comint variables in the IDLWAVE Shell. -@end defopt - -@defopt idlwave-shell-file-name-chars -The characters allowed in file names, as a string. Used for file name -completion. -@end defopt - -@defopt idlwave-shell-graphics-window-size -Size of IDL graphics windows popped up by special IDLWAVE command. -@end defopt - -@cindex Input mode -@cindex Character input mode (Shell) -@cindex Line input mode (Shell) -@cindex Magic spells, for input mode -@cindex Spells, magic -IDLWAVE works in line input mode: You compose a full command line, using -all the power Emacs gives you to do this. When you press @key{RET}, the -whole line is sent to IDL. Sometimes it is necessary to send single -characters (without a newline), for example when an IDL program is -waiting for single character input with the @code{GET_KBRD} function. -You can send a single character to IDL with the command @kbd{C-c C-x} -(@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} -(@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop -which accepts characters and immediately sends them to IDL. The loop -can be exited with @kbd{C-g}. It terminates also automatically when the -current IDL command is finished. Check the documentation of the two -variables described below for a way to make IDL programs trigger -automatic switches of the input mode. - -@defopt idlwave-shell-use-input-mode-magic (@code{nil}) -Non-@code{nil} means IDLWAVE should check for input mode spells in -output. -@end defopt - -@defopt idlwave-shell-input-mode-spells -The three regular expressions which match the magic spells for input -modes. -@end defopt - -@node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell -@section Commands Sent to the Shell -@cindex Commands in shell, showing -@cindex Showing commands in shell - -The IDLWAVE buffers and shell interact very closely. In addition to the -normal commands you enter at the @code{IDL>} prompt, many other special -commands are sent to the shell, sometimes as a direct result of invoking -a key command, menu item, or toolbar button, but also automatically, as -part of the normal flow of information updates between the buffer and -shell. - -The commands sent include @code{breakpoint}, @code{.step} and other -debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other -compilation statements (@pxref{Compiling Programs}), examination -commands like @code{print} and @code{help} (@pxref{Examining -Variables}), and other special purpose commands designed to keep -information on the running shell current. - -By default, much of this background shell input and output is hidden -from the user, but this is configurable. The custom variable -@code{idlwave-abbrev-show-commands} allows you to configure which -commands sent to the shell are shown there. For a related customization -for separating the output of @emph{examine} commands, see @ref{Examining -Variables}. - -@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) -A list of command types to echo in the shell when sent. Possible values -are @code{run} for @code{.run}, @code{.compile} and other run commands, -@code{misc} for lesser used commands like @code{window}, -@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint -setting and clearing commands, and @code{debug} for other debug, -stepping, and continue commands. In addition, if the variable is set to -the single symbol @code{'everything}, all the copious shell input is -displayed (which is probably only useful for debugging purposes). -N.B. For hidden commands which produce output by side-effect, that -output remains hidden (e.g., stepping through a @code{print} command). -As a special case, any error message in the output will be displayed -(e.g., stepping to an error). -@end defopt - -@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell -@section Debugging IDL Programs -@cindex Debugging -@cindex Keybindings for debugging -@cindex Toolbar - -Programs can be compiled, run, and debugged directly from the source -buffer in Emacs, walking through arbitrarily deeply nested code, -printing expressions and skipping up and down the calling stack along -the way. IDLWAVE makes compiling and debugging IDL programs far less -cumbersome by providing a full-featured, key/menu/toolbar-driven -interface to commands like @code{breakpoint}, @code{.step}, -@code{.run}, etc. It can even perform complex debug operations not -natively supported by IDL (like continuing to the line at the cursor). - -The IDLWAVE shell installs key bindings both in the shell buffer and -in all IDL code buffers of the current Emacs session, so debug -commands work in both places (in the shell, commands operate on the -last file compiled). On Emacs versions which support it, a debugging -toolbar is also installed. The toolbar display can be toggled with -@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). - - -@defopt idlwave-shell-use-toolbar (@code{t}) -Non-@code{nil} means use the debugging toolbar in all IDL related -buffers. -@end defopt - -@menu -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: -@end menu - - -@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs -@subsection A Tale of Two Modes -@cindex Electric Debug Mode -@cindex Debugging Interface - -The many debugging, compiling, and examination commands provided in -IDLWAVE are available simultaneously through two different interfaces: -the original, multi-key command interface, and the new Electric Debug -Mode. The functionality they offer is similar, but the way you interact -with them is quite different. The main difference is that, in Electric -Debug Mode, the source buffers are made read-only, and single -key-strokes are used to step through, examine expressions, set and -remove breakpoints, etc. The same variables, prefix arguments, and -settings apply to both versions, and both can be used interchangeably. -By default, when breakpoints are hit, Electric Debug Mode is enabled. -The traditional interface is described first. @xref{Electric Debug -Mode}, for more on that mode. Note that electric debug mode can be -prevented from activating automatically by customizing the variable -@code{idlwave-shell-automatic-electric-debug}. - -@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs -@subsection Debug Key Bindings -@kindex C-c C-d -@cindex Key bindings - -The standard debugging key bindings are always available by default on -the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is -done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c -C-d C-c}. You can also easily configure IDLWAVE to use one or more -modifier keys not in use by other commands, in lieu of the prefix -@kbd{C-c C-d} (though these bindings will typically also be available ---- see @code{idlwave-shell-activate-prefix-keybindings}). For -example, if you include in @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift)) -@end lisp - -@noindent a breakpoint can then be set by pressing @kbd{b} while holding down -@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a -source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, -etc. In the remainder of this chapter we will assume that the -@kbd{C-c C-d} bindings are active, but each of these bindings will -have an equivalent shortcut if modifiers are given in the -@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- -Customization}). A much simpler and faster form of debugging for -running code is also available by default --- see @ref{Electric Debug -Mode}. - -@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) -The prefix key for the debugging map -@code{idlwave-shell-mode-prefix-map}. -@end defopt - -@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) -Non-@code{nil} means debug commands will be bound to the prefix -key, like @kbd{C-c C-d C-b}. -@end defopt - -@defopt idlwave-shell-debug-modifiers (@code{nil}) -List of modifier keys to use for additional, alternative binding of -debugging commands in the shell and source buffers. Can be one or -more of @code{control}, @code{meta}, @code{super}, @code{hyper}, -@code{alt}, and @code{shift}. -@end defopt - -@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs -@subsection Breakpoints and Stepping -@cindex Breakpoints -@cindex Stepping -@cindex Execution, controlled - -@kindex C-c C-d C-b -@kindex C-c C-d C-b -IDLWAVE helps you set breakpoints and step through code. Setting a -breakpoint in the current line of the source buffer is accomplished -with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a -prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a -@code{/ONCE} keyword, meaning that it will be deleted after first use. -With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), -the breakpoint will only be active the @code{nth} time it is hit. -With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt -for a condition --- an IDL expression to be evaluated and trigger the -breakpoint only if true. To clear the breakpoint in the current line, -use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When -executed from the shell window, the breakpoint where IDL is currently -stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d -C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled -and re-enabled: @kbd{C-c C-d C-\} -(@code{idlwave-shell-toggle-enable-current-bp}). - -Breakpoint lines are highlighted or indicated with an icon in the source -code (different icons for conditional, after, and other break types). -Disabled breakpoints are @emph{grayed out} by default. Note that IDL -places breakpoints as close as possible on or after the line you -specify. IDLWAVE queries the shell for the actual breakpoint location -which was set, so the exact line you specify may not be marked. You can -re-sync the breakpoint list and update the display at any time (e.g., if -you add or remove some on the command line) using @kbd{C-c C-d C-l}. - -In recent IDLWAVE versions, the breakpoint line is highlighted when the -mouse is moved over it, and a tooltip pops up describing the break -details. @kbd{Mouse-3} on the breakpoint line pops up a menu of -breakpoint actions, including clearing, disabling, and adding or -changing break conditions or ``after'' break count. - -Once the program has stopped somewhere, you can step through it. The -most important stepping commands are @kbd{C-c C-d C-s} to execute one -line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, -treating procedure and function calls as a single step ("step over"); -@kbd{C-c C-d C-h} to continue execution to the line at the cursor and -@kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the -Shell}, for information on displaying or hiding the breakpoint and -stepping commands the shell receives. Here is a summary of the -breakpoint and stepping commands: - -@multitable @columnfractions .23 .77 -@item @kbd{C-c C-d C-b} -@tab Set breakpoint (@code{idlwave-shell-break-here}) -@item @kbd{C-c C-d C-i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{C-c C-d C-d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{C-c C-d C-a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) -@item @kbd{C-c C-d C-\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{C-c C-d C-j} -@tab Set a breakpoint at the beginning of the enclosing routine. -@item @kbd{C-c C-d C-s} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{C-c C-d C-n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{C-c C-d C-k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{C-c C-d C-u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{C-c C-d C-m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{C-c C-d C-o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{C-c C-d C-h} -@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{C-c C-d C-r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{C-c C-d C-up} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{C-c C-d C-down} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@end multitable - -All of these commands have equivalents in Electric Debug Mode, which -provides faster single-key access (@pxref{Electric Debug Mode}). - -The line where IDL is currently stopped, at breakpoints, halts, and -errors, etc., is marked with a color overlay or arrow, depending on the -setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is -used to mark the stop line (as it is by default), when stepping through -code, the face color is temporarily changed to gray, until IDL completes -the next command and moves to the new line. - -@defopt idlwave-shell-mark-breakpoints (@code{t}) -Non-@code{nil} means mark breakpoints in the source file buffers. The -value indicates the preferred method. Valid values are @code{nil}, -@code{t}, @code{face}, and @code{glyph}. -@end defopt - -@defopt idlwave-shell-breakpoint-face -The face for breakpoint lines in the source code if -@code{idlwave-shell-mark-breakpoints} has the value @code{face}. -@end defopt - -@defopt idlwave-shell-breakpoint-popup-menu (@code{t}) -Whether to pop-up a menu and present a tooltip description on -breakpoint lines. -@end defopt - -@defopt idlwave-shell-mark-stop-line (@code{t}) -Non-@code{nil} means mark the source code line where IDL is currently -stopped. The value specifies the preferred method. Valid values are -@code{nil}, @code{t}, @code{arrow}, and @code{face}. -@end defopt - -@defopt idlwave-shell-overlay-arrow (@code{">"}) -The overlay arrow to display at source lines where execution halts, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - -@defopt idlwave-shell-stop-line-face -The face which highlights the source line where IDL is stopped, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - - -@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs -@subsection Compiling Programs -@cindex Compiling programs -@cindex Programs, compiling -@cindex Default command line, executing -@cindex Executing a default command line - -@kindex C-c C-d C-c -In order to compile the current buffer under the IDLWAVE shell, press -@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the -current buffer and then sends the command @samp{.run path/to/file} to the -shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in -which case the most recently compiled buffer will be saved and -re-compiled. - -When developing or debugging a program, it is often necessary to execute -the same command line many times. A convenient way to do this is -@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). -This command first resets IDL from a state of interrupted execution by -closing all files and returning to the main interpreter level. Then a -default command line is send to the shell. To edit the default command -line, call @code{idlwave-shell-execute-default-command-line} with a -prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has -been set (or you give two prefix arguments), the last command on the -@code{comint} input history is sent. - -@kindex C-c C-d C-e -@cindex Compiling regions -For quickly compiling and running the currently marked region as a main -level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is -very useful. A temporary file is created holding the contents of the -current region (with @code{END} appended), and run from the shell. - -@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs -@subsection Walking the Calling Stack -@cindex Calling stack, walking - -While debugging a program, it can be very useful to check the context in -which the current routine was called, for instance to help understand -the value of the arguments passed. To do so conveniently you need to -examine the calling stack. If execution is stopped somewhere deep in a -program, you can use the commands @kbd{C-c C-d C-@key{UP}} -(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} -(@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, -to move up or down through the calling stack. The mode line of the -shell window will indicate the position within the stack with a label -like @samp{[-3:MYPRO]}. The line of IDL code at that stack position -will be highlighted. If you continue execution, IDLWAVE will -automatically return to the current level. @xref{Examining Variables}, -for information how to examine the value of variables and expressions on -higher calling stack levels. - -@html - -@end html -@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs -@subsection Electric Debug Mode -@cindex Electric Debug Mode -@cindex @samp{*Debugging*} - -Even with a convenient debug key prefix enabled, repetitive stepping, -variable examination (@pxref{Examining Variables}), and other debugging -activities can be awkward and slow using commands which require multiple -keystrokes. Luckily, there's a better way, inspired by the lisp e-debug -mode, and available through the @emph{Electric Debug Mode}. By default, -as soon as a breakpoint is hit, this minor mode is enabled. The buffer -showing the line where execution has halted is switched to Electric -Debug Mode. This mode is visible as @samp{*Debugging*} in the mode -line, and a different face (violet by default, if color is available) -for the line stopped at point. The buffer is made read-only and -single-character bindings for the most commonly used debugging commands -are enabled. These character commands (a list of which is available -with @kbd{C-?}) are: - -@multitable @columnfractions .2 .8 -@item @kbd{a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{b} -@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) -@item @kbd{d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{e} -@tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). -@item @kbd{h} -@tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{[} -@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{]} -@tab Go to the next breakpoint in the file -(@code{idlwave-shell-goto-next-bp}) -@item @kbd{\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{j} -@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) -@item @kbd{k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{p} -@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) -@item @kbd{q} -@tab End the debugging session and return to the Shell's main level -(@code{idlwave-shell-retall}) -@item @kbd{r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{s} or @kbd{@key{SPACE}} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{t} -@tab Print a calling-level traceback in the shell -@item @kbd{u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{v} -@tab Turn Electric Debug Mode off -(@code{idlwave-shell-electric-debug-mode}) -@item @kbd{x} -@tab Examine expression near point (or in region with @kbd{C-u x}) -with shortcut of examine type. -@item @kbd{z} -@tab Reset IDL (@code{idlwave-shell-reset}) -@item @kbd{+} or @kbd{=} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{-} or @kbd{_} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@item @kbd{?} -@tab Help on expression near point or in region with @kbd{C-u ?} -(@code{idlwave-shell-help-expression}) -@item @kbd{C-?} -@tab Show help on the commands available. -@end multitable - -Most single-character electric debug bindings use the final keystroke -of the equivalent multiple key commands (which are of course also -still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). -Some have additional convenience bindings (like @kbd{@key{SPACE}} for -stepping). All prefix and other argument options described in this -section for the commands invoked by electric debug bindings are still -valid. For example, @kbd{C-u b} sets a conditional breakpoint, just -as it did with @kbd{C-u C-c C-d C-b}. - -You can toggle the electric debug mode at any time in a buffer using -@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from -the Debug menu. Normally the mode will be enabled and disabled at the -appropriate times, but occasionally you might want to edit a file -while still debugging it, or switch to the mode for conveniently -setting lots of breakpoints. - -To quickly abandon a debugging session and return to normal editing at -the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). -This disables electric debug mode in all IDLWAVE buffers@footnote{Note -that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to -@code{idlwave-shell-quit}, which quits your IDL session.}. Help is -available for the command shortcuts with @kbd{C-?}. If you find this -mode gets in your way, you can keep it from automatically activating -by setting the variable @code{idlwave-shell-automatic-electric-debug} -to @code{nil}, or @code{'breakpoint}. If you'd like the convenient -electric debug shortcuts available also when run-time errors are -encountered, set to @code{t}. - -@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) -Whether to enter electric debug mode automatically when a breakpoint -or run-time error is encountered, and then disable it in all buffers -when the $MAIN$ level is reached (either through normal program -execution, or retall). In addition to @code{nil} for never, and -@code{t} for both breakpoints and errors, this can be -@code{'breakpoint} (the default) to enable it only at breakpoint -halts. -@end defopt - -@defopt idlwave-shell-electric-stop-color (Violet) -Default color of the stopped line overlay when in electric debug mode. -@end defopt - -@defopt idlwave-shell-electric-stop-line-face -The face to use for the stopped line. Defaults to a face similar to the -modeline, with color @code{idlwave-shell-electric-stop-color}. -@end defopt - -@defopt idlwave-shell-electric-zap-to-file (@code{t}) -If set, when entering electric debug mode, select the window displaying -the file where point is stopped. This takes point away from the shell -window, but is useful for immediate stepping, etc. -@end defopt - -@html - -@end html -@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell -@section Examining Variables -@cindex @code{PRINT} expressions -@cindex @code{HELP}, on expressions -@cindex Expressions, printing & help -@cindex Examining expressions -@cindex Printing expressions -@cindex Mouse binding to print expressions - -@kindex C-c C-d C-p -Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, -and similar statements to remind yourself of the -type/size/structure/value/etc. of variables and expressions in your code -or at the command line? IDLWAVE has a suite of special commands to -automate these types of variable or expression examinations. They work -by sending statements to the shell formatted to include the indicated -expression, and can be accessed in several ways. - -These @emph{examine} commands can be used in the shell or buffer at any -time (as long as the shell is running), and are very useful when -execution is stopped in a buffer due to a triggered breakpoint or error, -or while composing a long command in the IDLWAVE shell. In the latter -case, the command is sent to the shell and its output is visible, but -point remains unmoved in the command being composed --- you can inspect -the constituents of a command you're building without interrupting the -process of building it! You can even print arbitrary expressions from -older input or output further up in the shell window --- any expression, -variable, number, or function you see can be examined. - -If the variable @code{idlwave-shell-separate-examine-output} is -non-@code{nil} (the default), all examine output will be sent to a -special @file{*Examine*} buffer, rather than the shell. The output of -prior examine commands is saved in this buffer. In this buffer @key{c} -clears the contents, and @key{q} hides the buffer. - -The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to -print the expression at point, and @kbd{C-c C-d ?}, to invoke help on -this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric -Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is -either an array expression or a function call, or the contents of a pair -of parentheses. The chosen expression is highlighted, and -simultaneously the resulting output is highlighted in the shell or -separate output buffer. Calling the above commands with a prefix -argument will use the current region as expression instead of using the -one at point. which can be useful for examining complicated, multi-line -expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will -prompt for an expression to print directly. By default, when invoking -print, only an initial portion of long arrays will be printed, up to -@code{idlwave-shell-max-print-length}. - -For added speed and convenience, there are mouse bindings which allow -you to click on expressions and examine their values. Use -@kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke -help (i.e. you need to hold down @key{META} and @key{CONTROL} while -clicking with the middle mouse button). If you simply click, the -nearest expression will be selected in the same manner as described -above. You can also @emph{drag} the mouse in order to highlight -exactly the specific expression or sub-expression you want to examine. -For custom expression examination, and the powerful customizable -pop-up examine selection, @xref{Custom Expression Examination}. - -@cindex Printing expressions, on calling stack -@cindex Restrictions for expression printing -The same variable inspection commands work both in the IDL Shell and -IDLWAVE buffers, and even for variables at higher levels of the calling -stack. For instance, if you're stopped at a breakpoint in a routine, -you can examine the values of variables and expressions inside its -calling routine, and so on, all the way up through the calling stack. -Simply step up the stack, and print variables as you see them -(@pxref{Walking the Calling Stack}, for information on stepping back -through the calling stack). The following restrictions apply for all -levels except the current: - -@itemize @bullet -@item -Array expressions must use the @samp{[ ]} index delimiters. Identifiers -with a @samp{( )} will be interpreted as function calls. -@item -@cindex ROUTINE_NAMES, IDL procedure -N.B.: printing values of expressions on higher levels of the calling -stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, -which may or may not be available in future versions of IDL. Caveat -Examinor. -@end itemize - -@defopt idlwave-shell-expression-face -The face for @code{idlwave-shell-expression-overlay}. -Allows you to choose the font, color and other properties for -the expression printed by IDL. -@end defopt - -@defopt idlwave-shell-output-face -The face for @code{idlwave-shell-output-overlay}. -Allows to choose the font, color and other properties for the most -recent output of IDL when examining an expression." -@end defopt - -@defopt idlwave-shell-separate-examine-output (@code{t}) -If non-@code{nil}, re-direct the output of examine commands to a special -@file{*Examine*} buffer, instead of in the shell itself. -@end defopt - -@defopt idlwave-shell-max-print-length (200) -The maximum number of leading array entries to print, when examining -array expressions. -@end defopt - -@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell -@section Custom Expression Examination -@cindex Expressions, custom examination -@cindex Custom expression examination - -The variety of possible variable and expression examination commands is -endless (just look, for instance, at the keyword list to -@code{widget_info()}). Rather than attempt to include them all, IDLWAVE -provides two easy methods to customize your own commands, with a special -mouse examine command, and two macros for generating your own examine -key and mouse bindings. - -The most powerful and flexible mouse examine command of all is -available on @kbd{C-S-Mouse-2}. Just as for all the other mouse -examine commands, it permits click or drag expression selection, but -instead of sending hard-coded commands to the shell, it pops-up a -customizable selection list of examine functions to choose among, -configured with the @code{idlwave-shell-examine-alist} -variable@footnote{In Electric Debug Mode (@pxref{Electric Debug -Mode}), the key @kbd{x} provides a single-character shortcut interface -to the same examine functions for the expression at point or marked by -the region.}. This variable is a list of key-value pairs (an -@emph{alist} in Emacs parlance), where the key gives a name to be -shown for the examine command, and the value is the command strings -itself, in which the text @code{___} (three underscores) will be -replaced by the selected expression before being sent to the shell. -An example might be key @code{Structure Help} with value -@code{help,___,/STRUCTURE}. In that case, you'd be prompted with -@emph{Structure Help}, which might send something like -@code{help,var,/STRUCTURE} to the shell for output. -@code{idlwave-shell-examine-alist} comes configured by default with a -large list of examine commands, but you can easily customize it to add -your own. - -In addition to configuring the functions available to the pop-up mouse -command, you can easily create your own customized bindings to inspect -expressions using the two convenience macros -@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. -These create keyboard or mouse-based custom inspections of variables, -sharing all the same properties of the built-in examine commands. -Both functions take a single string argument sharing the syntax of the -@code{idlwave-shell-examine-alist} values, e.g.: - -@lisp -(add-hook 'idlwave-shell-mode-hook - (lambda () - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f9] (idlwave-shell-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine - "print,size(___,/TNAME)")) - (idlwave-shell-define-key-both [f11] (idlwave-shell-examine - "help,___,/STRUCTURE")))) -@end lisp - -@noindent Now pressing @key{f9}, or middle-mouse dragging with the -@key{SUPER} key depressed, will print the dimensions of the nearby or -highlighted expression. Pressing @key{f10} will give the type string, -and @key{f11} will show the contents of a nearby structure. As you can -see, the possibilities are only marginally finite. - -@defopt idlwave-shell-examine-alist -An alist of examine commands in which the keys name the command and -are displayed in the selection pop-up, and the values are custom IDL -examine command strings to send, after all instances of @code{___} -(three underscores) are replaced by the indicated expression. -@end defopt - -@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top -@chapter Acknowledgements -@cindex Acknowledgements -@cindex Maintainer, of IDLWAVE -@cindex Authors, of IDLWAVE -@cindex Contributors, to IDLWAVE -@cindex Email address, of Maintainer -@cindex Thanks - -@noindent -The main contributors to the IDLWAVE package have been: - -@itemize @minus -@item -@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. -Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them -for several years. - -@item -@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge -of the package from version 3.0, during which time he overhauled almost -everything, modernized IDLWAVE with many new features, and developed the -manual. - -@item -@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current -maintainer, as of version 4.10, helped shape object method completion -and most new features introduced in versions 4.x, and introduced many -new features for IDLWAVE versions 5.x and 6.x. -@end itemize - -@noindent -The following people have also contributed to the development of IDLWAVE -with patches, ideas, bug reports and suggestions. - -@itemize @minus -@item -Ulrik Dickow -@item -Eric E. Dors -@item -Stein Vidar H. Haugan -@item -David Huenemoerder -@item -Kevin Ivory -@item -Dick Jackson -@item -Xuyong Liu -@item -Simon Marshall -@item -Craig Markwardt -@item -Laurent Mugnier -@item -Lubos Pochman -@item -Bob Portmann -@item -Patrick M. Ryan -@item -Marty Ryba -@item -Phil Williams -@item -Phil Sterne -@item -Paul Sorenson -@end itemize - -Doug Dirks was instrumental in providing the crucial IDL XML catalog to -support HTML help with IDL v6.2 and later, and Ali Bahrami provided -scripts and documentation to interface with the IDL Assistant. - -@noindent -Thanks to everyone! - -@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top -@appendix Sources of Routine Info - -@cindex Sources of routine information -In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE -displays the calling sequence and keywords of routines, and completes -routine names and keywords. For these features to work, IDLWAVE must -know about the accessible routines. - -@menu -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals -@end menu - -@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info -@appendixsec Routine Definitions -@cindex Routine definitions -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex @code{CALL_EXTERNAL}, IDL routine -@cindex @code{LINKIMAGE}, IDL routine -@cindex External routines - -@noindent Routines which can be used in an IDL program can be defined in -several places: - -@enumerate -@item -@emph{Builtin routines} are defined inside IDL itself. The source code -of such routines is not available, but instead are learned about through -the IDL documentation. -@item -Routines which are @emph{part of the current program}, are defined in a -file explicitly compiled by the user. This file may or may not be -located on the IDL search path. -@item -@emph{Library routines} are defined in files located on IDL's search -path. When a library routine is called for the first time, IDL will -find the source file and compile it dynamically. A special sub-category -of library routines are the @emph{system routines} distributed with IDL, -and usually available in the @file{lib} subdirectory of the IDL -distribution. -@item -External routines written in other languages (like Fortran or C) can be -called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, -or included as dynamically loaded modules (DLMs). Currently IDLWAVE -cannot provide routine info and completion for such external routines, -except by querying the Shell for calling information (DLMs only). -@end enumerate - -@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info -@appendixsec Routine Information Sources -@cindex Routine info sources -@cindex Builtin list of routines -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@noindent To maintain the most comprehensive information about all IDL -routines on a system, IDLWAVE collects data from many sources: - -@enumerate - -@item -It has a @emph{builtin list} with information about the routines IDL -ships with. IDLWAVE @value{VERSION} is distributed with a list of -@value{NSYSROUTINES} routines and object methods, reflecting IDL version -@value{IDLVERSION}. As of IDL v6.2, the routine info is distributed -directly with IDL in the form of an XML catalog which IDLWAVE scans. -Formerly, this list was created by scanning the IDL manuals to produce -the file @file{idlw-rinfo.el}. - -@item -IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session -for routine definitions. This is done automatically when routine -information or completion is first requested by the user. Each new -buffer and each buffer saved after making changes is also scanned. The -command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used -at any time to rescan all buffers. - -@item -If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will -@emph{query the shell} for compiled routines and their arguments. This -happens automatically when routine information or completion is first -requested by the user. Each time an Emacs buffer is compiled with -@kbd{C-c C-d C-c}, the routine info for that file is queried. Though -rarely necessary, the command @kbd{C-c C-i} -(@code{idlwave-update-routine-info}) can be used to explicitly update -the shell routine data. - -@item -Many popular libraries are distributed with routine information already -scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These -per-directory catalog files can also be built by the user with the -supplied @file{idlwave_catalog} tool. They are automatically discovered -by IDLWAVE. - -@item -IDLWAVE can scan selected directories of source files and store the -result in a single @emph{user catalog} file which will be -automatically loaded just like @file{idlw-rinfo.el}. @xref{User -Catalog}, for information on how to scan files in this way. -@end enumerate - -Loading all the routine and catalog information can be a time consuming -process, especially over slow networks. Depending on the system and -network configuration it could take up to 30 seconds (though locally on -fast systems is usually only a few seconds). In order to minimize the -wait time upon your first completion or routine info command in a -session, IDLWAVE uses Emacs idle time to do the initialization in six -steps, yielding to user input in between. If this gets into your way, -set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). -The more routines documented in library and user catalogs, the slower -the loading will be, so reducing this number can help alleviate any long -load times. - -@defopt idlwave-init-rinfo-when-idle-after (@code{10}) -Seconds of idle time before routine info is automatically initialized. -@end defopt - -@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) -Non-@code{nil} means scan all buffers for IDL programs when updating -info. -@end defopt - -@defopt idlwave-query-shell-for-routine-info (@code{t}) -Non-@code{nil} means query the shell for info about compiled routines. -@end defopt - -@defopt idlwave-auto-routine-info-updates -Controls under what circumstances routine info is updated automatically. -@end defopt - -@html - -@end html -@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info -@appendixsec Catalogs -@cindex Catalogs - -@emph{Catalogs} are files containing scanned information on individual -routines, including arguments and keywords, calling sequence, file path, -class and procedure vs. function type, etc. They represent a way of -extending the internal built-in information available for IDL system -routines (@pxref{Routine Info}) to other source collections. - -Starting with version 5.0, there are two types of catalogs available -with IDLWAVE. The traditional @emph{user catalog} and the newer -@emph{library catalogs}. Although they can be used interchangeably, the -library catalogs are more flexible, and preferred. There are few -occasions when a user catalog might be preferred --- read below. Both -types of catalogs can coexist without causing problems. - -To facilitate the catalog systems, IDLWAVE stores information it gathers -from the shell about the IDL search paths, and can write this -information out automatically, or on-demand (menu @code{Debug->Save Path -Info}). On systems with no shell from which to discover the path -information (e.g. Windows), a library path must be specified in -@code{idlwave-library-path} to allow library catalogs to be located, and -to setup directories for user catalog scan (@pxref{User Catalog} for -more on this variable). Note that, before the shell is running, IDLWAVE -can only know about the IDL search path by consulting the file pointed -to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by -default). If @code{idlwave-auto-write-path} is enabled (which is the -default), the paths are written out whenever the IDLWAVE shell is -started. - -@defopt idlwave-auto-write-path (@code{t}) -Write out information on the !PATH and !DIR paths from IDL automatically -when they change and when the Shell is closed. These paths are needed -to locate library catalogs. -@end defopt - -@defopt idlwave-library-path -IDL library path for Windows and MacOS. Under Unix/MacOSX, will be -obtained from the Shell when run. -@end defopt - -@defopt idlwave-system-directory -The IDL system directory for Windows and MacOS. Also needed for -locating HTML help and the IDL Assistant for IDL v6.2 and later. Under -Unix/MacOSX, will be obtained from the Shell and recorded, if run. -@end defopt - -@defopt idlwave-config-directory (@file{~/.idlwave}) -Default path where IDLWAVE saves configuration information, a user -catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and -later). -@end defopt - -@menu -* Library Catalogs:: -* User Catalog:: -@end menu - -@html - -@end html -@node Library Catalogs, User Catalog, Catalogs, Catalogs -@appendixsubsec Library Catalogs -@cindex @file{.idlwave_catalog} -@cindex Library catalogs -@cindex @code{idlwave_catalog} - -Library catalogs consist of files named @file{.idlwave_catalog} stored -in directories containing @code{.pro} routine files. They are -discovered on the IDL search path and loaded automatically when routine -information is read. Each catalog file documents the routines found in -that directory --- one catalog per directory. Every catalog has a -library name associated with it (e.g. @emph{AstroLib}). This name will -be shown briefly when the catalog is found, and in the routine info of -routines it documents. - -Many popular libraries of routines are shipped with IDLWAVE catalog -files by default, and so will be automatically discovered. Library -catalogs are scanned externally to Emacs using a tool provided with -IDLWAVE. Each catalog can be re-scanned independently of any other. -Catalogs can easily be made available system-wide with a common source -repository, providing uniform routine information, and lifting the -burden of scanning from the user (who may not even know they're using a -scanned catalog). Since all catalogs are independent, they can be -re-scanned automatically to gather updates, e.g. in a @file{cron} job. -Scanning is much faster than with the built-in user catalog method. One -minor disadvantage: the entire IDL search path is scanned for catalog -files every time IDLWAVE starts up, which might be slow if accessing IDL -routines over a slow network. - -A Perl tool to create library catalogs is distributed with IDLWAVE: -@code{idlwave_catalog}. It can be called quite simply: -@example -idlwave_catalog MyLib -@end example - -@noindent This will scan all directories recursively beneath the current and -populate them with @file{.idlwave_catalog} files, tagging the routines -found there with the name library ``MyLib''. The full usage -information: - -@example -Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname - libname - Unique name of the catalog (4 or more alphanumeric - characters). - -l - Scan local directory only, otherwise recursively - catalog all directories at or beneath this one. - -v - Print verbose information. - -d - Instead of scanning, delete all .idlwave_catalog files - here or below. - -s - Be silent. - -f - Force overwriting any catalogs found with a different - library name. - -h - Print this usage. -@end example - -To re-load the library catalogs on the IDL path, force a system routine -info update using a single prefix to @code{idlwave-update-routine-info}: -@kbd{C-u C-c C-i}. - -@defopt idlwave-use-library-catalogs (@code{t}) -Whether to search for and load library catalogs. Disable if load -performance is a problem and/or the catalogs are not needed. -@end defopt - -@node User Catalog, , Library Catalogs, Catalogs -@appendixsubsec User Catalog -@cindex User catalog -@cindex IDL library routine info -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -The user catalog is the old routine catalog system. It is produced -within Emacs, and stored in a single file in the user's home directory -(@file{.idlwave/idlusercat.el} by default). Although library catalogs -are more flexible, there may be reasons to prefer a user catalog -instead, including: - -@itemize @bullet -@item The scan is internal to Emacs, so you don't need a working Perl -installation, as you do for library catalogs. -@item Can be used to scan directories for which the user has no write -privileges. -@item Easy widget-based path selection. -@end itemize - -However, no routine info is available in the user catalog by default; -the user must actively complete a scan. In addition, this type of -catalog is all or nothing: if a single routine changes, the entire -catalog must be rescanned to update it. Creating the user catalog is -also much slower than scanning library catalogs. - -You can scan any of the directories on the currently known path. Under -Windows and MacOS (not OSX), you need to specify the IDL search path in -the variable @code{idlwave-library-path}, and the location of the IDL -directory (the value of the @code{!DIR} system variable) in the variable -@code{idlwave-system-directory}, like this@footnote{The initial @samp{+} -leads to recursive expansion of the path, just like in IDL}: - -@lisp -(setq idlwave-library-path - '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) -(setq idlwave-system-directory "c:/RSI/IDL56/") -@end lisp - -@noindent Under GNU/Linux and UNIX, these values will be automatically -gathered from the IDLWAVE shell, if run. - -The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item -@samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be -used to create a user catalog. It brings up a widget in which you can -select some or all directories on the search path. Directories which -already contain a library catalog are marked with @samp{[LIB]}, and need -not be scanned (although there is no harm if you do so, other than the -additional memory used for the duplication). - -After selecting directories, click on the @w{@samp{[Scan & Save]}} -button in the widget to scan all files in the selected directories and -write out the resulting routine information. In order to update the -library information using the directory selection, call the command -@code{idlwave-update-routine-info} with a double prefix argument: -@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously -selected directories, write an updated version of the user catalog file -and rebuild IDLWAVE's internal lists. If you give three prefix -arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a -background job@footnote{Unix systems only, I think.}. You can continue -to work, and the library catalog will be re-read when it is ready. If -you find you need to update the user catalog often, you should consider -building a library catalog for your routines instead (@pxref{Library -Catalogs}). - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories for -labeling in routine-info display. -@end defopt - -@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info -@appendixsec Load-Path Shadows -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -@cindex Application, testing for shadowing -@cindex Buffer, testing for shadowing - -IDLWAVE can compile a list of routines which are (re-)defined in more -than one file. Since one definition will hide (shadow) the others -depending on which file is compiled first, such multiple definitions are -called "load-path shadows". IDLWAVE has several routines to scan for -load path shadows. The output is placed into the special buffer -@file{*Shadows*}. The format of the output is identical to the source -section of the routine info buffer (@pxref{Routine Info}). The -different definitions of a routine are ordered by @emph{likelihood of -use}. So the first entry will be most likely the one you'll get if an -unsuspecting command uses that routine. Before listing shadows, you -should make sure that routine info is up-to-date by pressing @kbd{C-c -C-i}. Here are the different routines (also available in the Menu -@samp{IDLWAVE->Routine Info}): - -@table @asis -@item @kbd{M-x idlwave-list-buffer-load-path-shadows} -This commands checks the names of all routines defined in the current -buffer for shadowing conflicts with other routines accessible to -IDLWAVE. The command also has a key binding: @kbd{C-c C-b} -@item @kbd{M-x idlwave-list-shell-load-path-shadows}. -Checks all routines compiled under the shell for shadowing. This is -very useful when you have written a complete application. Just compile -the application, use @code{RESOLVE_ALL} to compile any routines used by -your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and -then check for shadowing. -@item @kbd{M-x idlwave-list-all-load-path-shadows} -This command checks all routines accessible to IDLWAVE for conflicts. -@end table - -For these commands to work fully you need to scan the entire load path -in either a user or library catalog. Also, IDLWAVE should be able to -distinguish between the system library files (normally installed in -@file{/usr/local/rsi/idl/lib}) and any site specific or user specific -files. Therefore, such local files should not be installed inside the -@file{lib} directory of the IDL directory. This is also advisable for -many other reasons. - -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable -Users of Windows and MacOS (not X) also must set the variable -@code{idlwave-system-directory} to the value of the @code{!DIR} system -variable in IDL. IDLWAVE appends @file{lib} to the value of this -variable and assumes that all files found on that path are system -routines. - -Another way to find out if a specific routine has multiple definitions -on the load path is routine info display (@pxref{Routine Info}). - -@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info -@appendixsec Documentation Scan -@cindex @file{get_html_rinfo} -@cindex @file{idlw-rinfo.el} -@cindex Scanning the documentation -@cindex Perl program, to create @file{idlw-rinfo.el} - -@strong{Starting with version 6.2, IDL is distributed directly with HTML -online help, and an XML-based catalog of routine information}. This -makes scanning the manuals with the tool @file{get_html_rinfo}, and the -@file{idlw-rinfo.el} file it produced, as described here, entirely -unnecessary. The information is left here for users wishing to produce -a catalog of older IDL versions' help. - - -IDLWAVE derives its knowledge about system routines from the IDL -manuals. The file @file{idlw-rinfo.el} contains the routine information -for the IDL system routines, and links to relevant sections of the HTML -documentation. The Online Help feature of IDLWAVE requires HTML -versions of the IDL manuals to be available; the HTML documentation is -not distributed with IDLWAVE by default, but must be downloaded -separately. - -The HTML files and related images can be produced from the -@file{idl.chm} HTMLHelp file distributed with IDL using the free -Microsoft HTML Help Workshop. If you are lucky, the maintainer of -IDLWAVE will always have access to the newest version of IDL and provide -updates. The IDLWAVE distribution also contains the Perl program -@file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by -scanning the HTML documents produced from the IDL documentation. -Instructions on how to use @file{get_html_rinfo} are in the program -itself. - -@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top -@appendix HTML Help Browser Tips -@cindex Browser Tips - -There are a wide variety of possible browsers to use for displaying -the online HTML help available with IDLWAVE (starting with version -5.0). Since IDL v6.2, a single cross-platform HTML help browser, the -@emph{IDL Assistant} is distributed with IDL. If this help browser is -available, it is the preferred choice, and the default. The variable -@code{idlwave-help-use-assistant}, enabled by default, controls -whether this help browser is used. If you use the IDL Assistant, the -tips here are not relevant. - -Since IDLWAVE runs on a many different system types, a single browser -configuration is not possible, but choices abound. On many systems, -the default browser configured in @code{browse-url-browser-function}, -and hence inherited by default by -@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the -HTML manuals decompiled from the original source contain formatting -structures which Netscape 4.x does not handle well, though they are -still readable. A much better choice is Mozilla, or one of the -Mozilla-derived browsers such as -@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), -@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or -@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all -platforms). Newer versions of Emacs provide a browser-function choice -@code{browse-url-gnome-moz} which uses the Gnome-configured browser. - -Note that the HTML files decompiled from the help sources contain -specific references to the @samp{Symbol} font, which by default is not -permitted in normal encodings (it's invalid, technically). Though it -only impacts a few symbols, you can trick Mozilla-based browsers into -recognizing @samp{Symbol} by following the directions -@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With -this fix in place, HTML help pages look almost identical to their PDF -equivalents (yet can be bookmarked, browsed as history, searched, -etc.). - -@noindent Individual platform recommendations: - -@itemize @bullet -@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser -and its associated -@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode -provide in-buffer browsing with image display, and excellent speed and -formatting. Both the Emacs mode and the browser itself must be -downloaded separately. To use this browser, include - -@lisp -(setq idlwave-help-browser-function 'w3m-browse-url) -@end lisp - -in your @file{.emacs}. Setting a few other nice @code{w3m} options -cuts down on screen clutter: - -@lisp -(setq w3m-use-tab nil - w3m-use-header-line nil - w3m-use-toolbar nil) -@end lisp - -If you use a dedicated frame for help, you might want to add the -following, to get consistent behavior with the @kbd{q} key: - -@lisp -;; Close my help window when w3m closes. -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) -@end lisp - -Note that you can open the file in an external browser from within -@code{w3m} using @kbd{M}. -@end itemize - -@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top -@appendix Configuration Examples -@cindex Configuration examples -@cindex Example configuration -@cindex @file{.emacs} -@cindex Default settings, of options -@cindex Interview, with the maintainer - -@noindent -@b{Question:} You have all these complicated configuration options in -your package, but which ones do @emph{you} as the maintainer actually -set in your own configuration? - -@noindent -@b{Answer:} Not many, beyond custom key bindings. I set most defaults -the way that seems best. However, the default settings do not turn on -features which: - -@itemize @minus -@item -are not self-evident (i.e. too magic) when used by an unsuspecting user. -@item -are too intrusive. -@item -will not work properly on all Emacs installations. -@item -break with widely used standards. -@item -use function or other non-standard keys. -@item -are purely personal customizations, like additional key bindings, and -library names. -@end itemize - -@noindent To see what I mean, here is the @emph{entire} configuration -the old maintainer had in his @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift) - idlwave-store-inquired-class t - idlwave-shell-automatic-start t - idlwave-main-block-indent 2 - idlwave-init-rinfo-when-idle-after 2 - idlwave-help-dir "~/lib/emacs/idlwave" - idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") - ("/jhuapl/" . "JHUAPL-Lib") - ("/dominik/lib/idl/" . "MyLib"))) -@end lisp - -However, if you are an Emacs power-user and want IDLWAVE to work -completely differently, you can change almost every aspect of it. Here -is an example of a much more extensive configuration of IDLWAVE. The -user is King! - -@example -;;; Settings for IDLWAVE mode - -(setq idlwave-block-indent 3) ; Indentation settings -(setq idlwave-main-block-indent 3) -(setq idlwave-end-offset -3) -(setq idlwave-continuation-indent 1) -(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" - ; anchored at start of line. -(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> -(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' -(setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... -(setq idlwave-reserved-word-upcase t) ; Make reserved words upper case - ; (with abbrevs only) -(setq idlwave-abbrev-change-case nil) ; Don't force case of expansions -(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill -(setq idlwave-show-block nil) ; Turn off blinking to begin -(setq idlwave-abbrev-move t) ; Allow abbrevs to move point -(setq idlwave-query-class '((method-default . nil) ; No query for method - (keyword-default . nil); or keyword completion - ("INIT" . t) ; except for these - ("CLEANUP" . t) - ("SETPROPERTY" .t) - ("GETPROPERTY" .t))) - -;; Using w3m for help (must install w3m and emacs-w3m) -(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) -(setq idlwave-help-browser-function 'w3m-browse-url - w3m-use-tab nil ; no tabs, location line, or toolbar - w3m-use-header-line nil - w3m-use-toolbar nil) - -;; Close my help window or frame when w3m closes with `q' -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) - -;; Some setting can only be done from a mode hook. Here is an example: -(add-hook 'idlwave-mode-hook - (lambda () - (setq case-fold-search nil) ; Make searches case sensitive - ;; Run other functions here - (font-lock-mode 1) ; Turn on font-lock mode - (idlwave-auto-fill-mode 0) ; Turn off auto filling - (setq idlwave-help-browser-function 'browse-url-w3) - - ;; Pad with 1 space (if -n is used then make the - ;; padding a minimum of n spaces.) The defaults use -1 - ;; instead of 1. - (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) - (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) - (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) - (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) - - ;; Only pad after comma and with exactly 1 space - (idlwave-action-and-binding "," '(idlwave-surround nil 1)) - (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) - - ;; Pad only after `->', remove any space before the arrow - (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) - - ;; Set some personal bindings - ;; (In this case, makes `,' have the normal self-insert behavior.) - (local-set-key "," 'self-insert-command) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - - ;; Create a newline, indenting the original and new line. - ;; A similar function that does _not_ reindent the original - ;; line is on "\C-j" (The default for emacs programming modes). - (local-set-key "\n" 'idlwave-newline) - ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. - - ;; Some personal abbreviations - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "wb") "widget_base()" - (idlwave-keyword-abbrev 1)) - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "on") "obj_new()" - (idlwave-keyword-abbrev 1)) - )) - -;;; Settings for IDLWAVE SHELL mode - -(setq idlwave-shell-overlay-arrow "=>") ; default is ">" -(setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame -(setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " -(setq idlwave-shell-explicit-file-name "wave") -(setq idlwave-shell-process-name "wave") -(setq idlwave-shell-use-toolbar nil) ; No toolbar - -;; Most shell interaction settings can be done from the shell-mode-hook. -(add-hook 'idlwave-shell-mode-hook - (lambda () - ;; Set up some custom key and mouse examine commands - (idlwave-shell-define-key-both [s-down-mouse-2] - (idlwave-shell-mouse-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f9] (idlwave-shell-examine - "print, size(___,/DIMENSIONS)")) - (idlwave-shell-define-key-both [f10] (idlwave-shell-examine - "print,size(___,/TNAME)")) - (idlwave-shell-define-key-both [f11] (idlwave-shell-examine - "help,___,/STRUCTURE")))) -@end example - -@html - -@end html -@node Windows and MacOS, Troubleshooting, Configuration Examples, Top -@appendix Windows and MacOS -@cindex Windows -@cindex MacOS -@cindex MacOSX - -IDLWAVE was developed on a UNIX system. However, thanks to the -portability of Emacs, much of IDLWAVE does also work under different -operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. - -The only real problem is that there is no command-line version of IDL -for Windows or MacOS(<=9) with which IDLWAVE can interact. As a -result, the IDLWAVE Shell does not work and you have to rely on IDLDE -to run and debug your programs. However, editing IDL source files -with Emacs/IDLWAVE works with all bells and whistles, including -routine info, completion and fast online help. Only a small amount of -additional information must be specified in your @file{.emacs} file: -the path names which, on a UNIX system, are automatically gathered by -talking to the IDL program. - -Here is an example of the additional configuration needed for a Windows -system. I am assuming that IDLWAVE has been installed in -@w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in -@w{@samp{C:\RSI\IDL63}}. - -@lisp -;; location of the lisp files (only needed if IDLWAVE is not part of -;; your default X/Emacs installation) -(setq load-path (cons "c:/program files/IDLWAVE" load-path)) - -;; The location of the IDL library directories, both standard, and your own. -;; note that the initial "+" expands the path recursively -(setq idlwave-library-path - '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" )) - -;; location of the IDL system directory (try "print,!DIR") -(setq idlwave-system-directory "c:/RSI/IDL63/") - -@end lisp - -@noindent Furthermore, Windows sometimes tries to outsmart you --- make -sure you check the following things: - -@itemize @bullet -@item When you download the IDLWAVE distribution, make sure you save the -file under the names @file{idlwave.tar.gz}. -@item M-TAB switches among running programs --- use Esc-TAB -instead. -@item Other issues as yet unnamed... -@end itemize - -Windows users who'd like to make use of IDLWAVE's context-aware HTML -help can skip the browser and use the HTMLHelp functionality directly. -@xref{Help with HTML Documentation}. - -@html - -@end html -@node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top -@appendix Troubleshooting -@cindex Troubleshooting - -Although IDLWAVE usually installs and works without difficulty, a few -common problems and their solutions are documented below. - -@enumerate - -@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get -errors or strange behavior when I try to type anything into some of my -IDLWAVE buffers.} - -This is a @emph{feature}, not an error. You're in @emph{Electric -Debug Mode} (@pxref{Electric Debug Mode}). You should see -@code{*Debugging*} in the mode-line. The buffer is read-only and all -debugging and examination commands are available as single keystrokes; -@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and -customize the variable @code{idlwave-shell-automatic-electric-debug} -if you prefer not to enter electric debug on breakpoints@dots{} but -you really should try it before you disable it! You can also -customize this variable to enter debug mode when errors are -encountered. - -@item @strong{I get errors like @samp{Searching for program: no such -file or directory, idl} when attempting to start the IDL shell.} - -IDLWAVE needs to know where IDL is in order to run it as a process. -By default, it attempts to invoke it simply as @samp{idl}, which -presumes such an executable is on your search path. You need to -ensure @samp{idl} is on your @samp{$PATH}, or specify the full -pathname to the idl program with the variable -@code{idlwave-shell-explicit-file-name}. Note that you may need to -set your shell search path in two places when running Emacs as an Aqua -application with MacOSX; see the next topic. - -@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set -under MacOSX} - -If you run Emacs directly as an Aqua application, rather than from the -console shell, the environment is set not from your usual shell -configuration files (e.g. @file{.cshrc}), but from the file -@file{~/.MacOSX/environment.plist}. Either include your path settings -there, or start Emacs and IDLWAVE from the shell. - -@item @strong{I get errors like @samp{Symbol's function is void: -overlayp}} - -You don't have the @samp{fsf-compat} package installed, which IDLWAVE -needs to run under XEmacs. Install it, or find an XEmacs distribution -which includes it by default. - -@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: -cl-builtin-gethash} on completion or routine info.} - -This error arises if you upgraded Emacs from 20.x to 21.x without -re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible -in compiled lisp files. Presumably, you kept the original .elc files in -place, and this is the source of the error. If you recompile (or just -"make; make install") from source, it should resolve this problem. -Another option is to recompile the @file{idlw*.el} files by hand using -@kbd{M-x byte-compile-file}. - -@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches -windows on my desktop.} - -Your system is trapping @kbd{M-@key{TAB}} and using it for its own -nefarious purposes: Emacs never sees the keystrokes. On many Unix -systems, you can reconfigure your window manager to use another key -sequence for switching among windows. Another option is to use the -equivalent sequence @kbd{@key{ESC}-@key{TAB}}. - -@item @strong{When stopping at breakpoints or errors, IDLWAVE does not -seem to highlight the relevant line in the source.} - -IDLWAVE scans for error and halt messages and highlights the stop -location in the correct file. However, if you've changed the system -variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these -message correctly. Don't do that. - -@item @strong{IDLWAVE doesn't work correctly when using ENVI.} - -Though IDLWAVE was not written with ENVI in mind, it works just fine -with it, as long as you update the prompt it's looking for (@samp{IDL> -} by default). You can do this with the variable -@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., -in your @file{.emacs}: - -@lisp -(setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") -@end lisp - -@item @strong{Attempts to set breakpoints fail: no breakpoint is -indicated in the IDLWAVE buffer.} - -IDL changed its breakpoint reporting format starting with IDLv5.5. The -first version of IDLWAVE to support the new format is IDLWAVE v4.10. If -you have an older version and are using IDL >v5.5, you need to upgrade, -and/or make sure your recent version of IDLWAVE is being found on the -Emacs load-path (see the next entry). You can list the version being -used with @kbd{C-h v idlwave-mode-version @key{RET}}. - -@item @strong{I installed a new version of IDLWAVE, but the old -version is still being used} or @strong{IDLWAVE works, but when I -tried to install the optional modules @file{idlw-roprompt.el} or -@file{idlw-complete-structtag}, I get errors like @samp{Cannot open -load file}}. - -The problem is that your Emacs is not finding the version of IDLWAVE you -installed. Many Emacsen come with an older bundled copy of IDLWAVE -(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. -You need to make sure your Emacs @emph{load-path} contains the directory -where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by -default), @emph{before} Emacs' default search directories. You can -accomplish this by putting the following in your @file{.emacs}: - -@lisp -(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) -@end lisp - -@noindent You can check on your load-path value using @kbd{C-h v -load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show -you the version Emacs is using. - -@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} - -Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated -programming mode for CORBA's Interface Definition Language (you should -see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One -solution: don't name your file @file{.idl}, but rather @file{.pro}. -Another solution: make sure @file{.idl} files load IDLWAVE instead of -@samp{idl-mode} by adding the following to your @file{.emacs}: - -@lisp -(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) -@end lisp - -@item @strong{The routine info for my local routines is out of date!} - -IDLWAVE collects routine info from various locations (@pxref{Routine -Information Sources}). Routines in files visited in a buffer or -compiled in the shell should be up to date. For other routines, the -information is only as current as the most recent scan. If you have a -rapidly changing set of routines, and you'd like the latest routine -information to be available for it, one powerful technique is to make -use of the library catalog tool, @samp{idlwave_catalog}. Simply add a -line to your @samp{cron} file (@samp{crontab -e} will let you edit this -on some systems), like this - -@example -45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) -@end example - -@noindent where @samp{MyLib} is the name of your library. This will -rescan all @file{.pro} files at or below @file{/path/to/myidllib} every -week night at 3:45am. You can even scan site-wide libraries with this -method, and the most recent information will be available to all users. -Since the scanning is very fast, there is very little impact. - -@item @strong{All the Greek-font characters in the HTML help are -displayed as Latin characters!} - -Unfortunately, the HTMLHelp files RSI provides attempt to switch to -@samp{Symbol} font to display Greek characters, which is not really an -permitted method for doing this in HTML. There is a "workaround" for -some browsers: @xref{HTML Help Browser Tips}. - -@item @strong{In the shell, my long commands are truncated at 256 characters!} - -This actually happens when running IDL in an XTerm as well. There are -a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in -your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character -and give you a 512 character limit. You won't be able to use -@key{C-d} to quit the shell, however. Another possibility is -@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a -memory-bounded limit), but disables the processing of background -widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). - -@item @strong{When I invoke IDL HTML help on a routine, the page which -is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get -@code{CONTOUR}.} - -You have a mismatch between your help index and the HTML help package -you downloaded. You need to ensure you download a ``downgrade kit'' if -you are using anything older than the latest HTML help package. A new -help package appears with each IDL release (assuming the documentation -is updated). -Starting with IDL 6.2, the HTML help and its catalog are -distributed with IDL, and so should never be inconsistent. - -@item @strong{I get errors such as @samp{void-variable -browse-url-browser-function} or similar when attempting to load IDLWAVE -under XEmacs.} - -You don't have the @samp{browse-url} (or other required) XEmacs package. -Unlike GNU Emacs, XEmacs distributes many packages separately from the -main program. IDLWAVE is actually among these, but is not always the -most up to date. When installing IDLWAVE as an XEmacs package, it -should prompt you for required additional packages. When installing it -from source, it won't and you'll get this error. The easiest solution -is to install all the packages when you install XEmacs (the so-called -@samp{sumo} bundle). The minimum set of XEmacs packages required by -IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. - -@end enumerate - -@node GNU Free Documentation License, Index, Troubleshooting, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 -@end ignore diff --git a/doc/misc/info.texi b/doc/misc/info.texi deleted file mode 100644 index 147e0b7a5ca..00000000000 --- a/doc/misc/info.texi +++ /dev/null @@ -1,1506 +0,0 @@ -\input texinfo.tex @c -*-texinfo-*- -@c We must \input texinfo.tex instead of texinfo, otherwise make -@c distcheck in the Texinfo distribution fails, because the texinfo Info -@c file is made first, and texi2dvi must include . first in the path. -@comment %**start of header -@setfilename info.info -@settitle Info -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@comment %**end of header - -@copying -This file describes how to use Info, the on-line, menu-driven GNU -documentation system. - -Copyright @copyright{} 1989, 1992, 1996, 1997, 1998, 1999, 2000, 2001, -2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Texinfo documentation system -@direntry -* Info: (info). How to use the documentation browsing system. -@end direntry - -@titlepage -@title Info -@subtitle The online, hyper-text GNU documentation system -@author Brian Fox -@author and the GNU Texinfo community -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Info: An Introduction - -The GNU Project distributes most of its on-line manuals in the -@dfn{Info format}, which you read using an @dfn{Info reader}. You are -probably using an Info reader to read this now. - -There are two primary Info readers: @code{info}, a stand-alone program -designed just to read Info files (@pxref{Top,,What is Info?, -info-stnd, GNU Info}), and the @code{info} package in GNU Emacs, a -general-purpose editor. At present, only the Emacs reader supports -using a mouse. - -@ifinfo -If you are new to the Info reader and want to learn how to use it, -type the command @kbd{h} now. It brings you to a programmed -instruction sequence. - -To read about advanced Info commands, type @kbd{n} twice. This -brings you to @cite{Advanced Info Commands}, skipping over the `Getting -Started' chapter. -@end ifinfo -@end ifnottex - -@insertcopying - -@menu -* Getting Started:: Getting started using an Info reader. -* Advanced:: Advanced Info commands. -* Expert Info:: Info commands for experts. -* Index:: An index of topics, commands, and variables. -@end menu - -@node Getting Started, Advanced, Top, Top -@comment node-name, next, previous, up -@chapter Getting Started - -This first part of this Info manual describes how to get around inside -of Info. The second part of the manual describes various advanced -Info commands. The third part briefly explains how to generate Info -files from Texinfo files, and describes how to write an Info file -by hand. - -@ifnotinfo -This manual is primarily designed for browsing with an Info reader -program on a computer, so that you can try Info commands while reading -about them. Reading it on paper or with an HTML browser is less -effective, since you must take it on faith that the commands described -really do what the manual says. By all means go through this manual -now that you have it; but please try going through the on-line version -as well. - -@cindex Info reader, how to invoke -@cindex entering Info -There are two ways of looking at the online version of this manual: - -@enumerate -@item -Type @code{info} at your shell's command line. This approach uses a -stand-alone program designed just to read Info files. - -@item -Type @code{emacs} at the command line; then type @kbd{C-h i} -(@kbd{Control-h}, followed by @kbd{i}). This approach uses the Info -mode of the Emacs editor. -@end enumerate - -In either case, then type @kbd{mInfo} (just the letters), followed by -@key{RET}---the ``Return'' or ``Enter'' key. At this point, you should -be ready to follow the instructions in this manual as you read them on -the screen. -@c FIXME! (pesch@cygnus.com, 14 dec 1992) -@c Is it worth worrying about what-if the beginner goes to somebody -@c else's Emacs session, which already has an Info running in the middle -@c of something---in which case these simple instructions won't work? -@end ifnotinfo - -@menu -* Help-Small-Screen:: Starting Info on a Small Screen. -* Help:: How to use Info. -* Help-P:: Returning to the Previous node. -* Help-^L:: The Space, DEL, B and ^L commands. -* Help-Inv:: Invisible text in Emacs Info. -* Help-M:: Menus. -* Help-Xref:: Following cross-references. -* Help-Int:: Some intermediate Info commands. -* Help-Q:: Quitting Info. -@end menu - -@node Help-Small-Screen -@section Starting Info on a Small Screen - -@ifnotinfo -(In Info, you only see this section if your terminal has a small -number of lines; most readers pass by it without seeing it.) -@end ifnotinfo - -@cindex small screen, moving around -Since your terminal has a relatively small number of lines on its -screen, it is necessary to give you special advice at the beginning. - -If the entire text you are looking at fits on the screen, the text -@samp{All} will be displayed at the bottom of the screen. In the -stand-alone Info reader, it is displayed at the bottom right corner of -the screen; in Emacs, it is displayed on the modeline. If you see the -text @samp{Top} instead, it means that there is more text below that -does not fit. To move forward through the text and see another screen -full, press @key{SPC}, the Space bar. To move back up, press the key -labeled @samp{Backspace} or @samp{DEL} (on some keyboards, this key -might be labeled @samp{Delete}). - -@ifinfo -Here are 40 lines of junk, so you can try @key{SPC} and @key{DEL} and -see what they do. At the end are instructions of what you should do -next. - -@format -This is line 20 -This is line 21 -This is line 22 -This is line 23 -This is line 24 -This is line 25 -This is line 26 -This is line 27 -This is line 28 -This is line 29 -This is line 30 -This is line 31 -This is line 32 -This is line 33 -This is line 34 -This is line 35 -This is line 36 -This is line 37 -This is line 38 -This is line 39 -This is line 40 -This is line 41 -This is line 42 -This is line 43 -This is line 44 -This is line 45 -This is line 46 -This is line 47 -This is line 48 -This is line 49 -This is line 50 -This is line 51 -This is line 52 -This is line 53 -This is line 54 -This is line 55 -This is line 56 -This is line 57 -This is line 58 -This is line 59 -@end format - -If you have managed to get here, go back to the beginning with -@kbd{DEL} (or @key{BACKSPACE}), and come back here again, then you -understand the about the @samp{Space} and @samp{Backspace} keys. So -now type an @kbd{n}---just one character; don't type the quotes and -don't type the Return key afterward---to get to the normal start of -the course. -@end ifinfo - -@node Help, Help-P, Help-Small-Screen, Getting Started -@comment node-name, next, previous, up -@section How to use Info - -You are talking to the program Info, for reading documentation. - - There are two ways to use Info: from within Emacs or as a -stand-alone reader that you can invoke from a shell using the command -@command{info}. - -@cindex node, in Info documents - Right now you are looking at one @dfn{Node} of Information. -A node contains text describing a specific topic at a specific -level of detail. This node's topic is ``how to use Info''. The mode -line says that this is node @samp{Help} in the file @file{info}. - -@cindex header of Info node - The top line of a node is its @dfn{header}. This node's header -(look at it now) says that the @samp{Next} node after this one is the -node called @samp{Help-P}. An advanced Info command lets you go to -any node whose name you know. In the stand-alone Info reader program, -the header line shows the names of this node and the Info file as -well. In Emacs, the header line is displayed with a special typeface, -and remains at the top of the window all the time even if you scroll -through the node. - - Besides a @samp{Next}, a node can have a @samp{Previous} link, or an -@samp{Up} link, or both. As you can see, this node has all of these -links. - -@kindex n @r{(Info mode)} - Now it is time to move on to the @samp{Next} node, named @samp{Help-P}. - -@format ->> Type @kbd{n} to move there. Type just one character; - do not type the quotes and do not type a @key{RET} afterward. -@end format - -@noindent -@samp{>>} in the margin means it is really time to try a command. - -@format ->> If you are in Emacs and have a mouse, and if you already practiced - typing @kbd{n} to get to the next node, click now with the left - mouse button on the @samp{Next} link to do the same ``the mouse way''. -@end format - -@node Help-P, Help-^L, Help, Getting Started -@comment node-name, next, previous, up -@section Returning to the Previous node - -@kindex p @r{(Info mode)} -This node is called @samp{Help-P}. The @samp{Previous} node, as you see, -is @samp{Help}, which is the one you just came from using the @kbd{n} -command. Another @kbd{n} command now would take you to the next -node, @samp{Help-^L}. - -@format ->> But do not type @kbd{n} yet. First, try the @kbd{p} command, or - (in Emacs) click on the @samp{Prev} link. That takes you to - the @samp{Previous} node. Then use @kbd{n} to return here. -@end format - - If you read this in Emacs, you will see an @samp{Info} item in the -menu bar, close to its right edge. Clicking the mouse on the -@samp{Info} menu-bar item opens a menu of commands which include -@samp{Next} and @samp{Previous} (and also some others which you didn't yet -learn about). - - This all probably seems insultingly simple so far, but @emph{please -don't} start skimming. Things will get complicated soon enough! -Also, please do not try a new command until you are told it is time -to. You could make Info skip past an important warning that was -coming up. - -@format ->> Now do an @kbd{n}, or (in Emacs) click the middle mouse button on - the @samp{Next} link, to get to the node @samp{Help-^L} and learn more. -@end format - -@node Help-^L, Help-Inv, Help-P, Getting Started -@comment node-name, next, previous, up -@section The Space, DEL, B and ^L commands - - This node's mode line tells you that you are now at node -@samp{Help-^L}, and the header line tells you that @kbd{p} would get -you back to @samp{Help-P}. The node's title is highlighted and may be -underlined as well; it says what the node is about. - - This is a big node and it does not all fit on your display screen. -You can tell that there is more that is not visible because you -can see the text @samp{Top} rather than @samp{All} near the bottom of -the screen. - -@kindex SPC @r{(Info mode)} -@kindex DEL @r{(Info mode)} -@kindex BACKSPACE @r{(Info mode)} -@findex Info-scroll-up -@findex Info-scroll-down - The @key{SPC}, @key{BACKSPACE} (or @key{DEL})@footnote{The key which -we call ``Backspace or DEL'' in this manual is labeled differently on -different keyboards. Look for a key which is a little ways above the -@key{ENTER} or @key{RET} key and which you normally use outside Emacs -to erase the character before the cursor, i.e.@: the character you -typed last. It might be labeled @samp{Backspace} or @samp{<-} or -@samp{DEL}, or sometimes @samp{Delete}.} and @kbd{b} commands exist to -allow you to ``move around'' in a node that does not all fit on the -screen at once. @key{SPC} moves forward, to show what was below the -bottom of the screen. @key{DEL} or @key{BACKSPACE} moves backward, to -show what was above the top of the screen (there is not anything above -the top until you have typed some spaces). - -@format ->> Now try typing a @key{SPC} (afterward, type a @key{BACKSPACE} to - return here). -@end format - - When you type the @key{SPC}, the two lines that were at the bottom of -the screen appear at the top, followed by more lines. @key{DEL} or -@key{BACKSPACE} takes the two lines from the top and moves them to the -bottom, @emph{usually}, but if there are not a full screen's worth of -lines above them they may not make it all the way to the bottom. - - If you are reading this in Emacs, note that the header line is -always visible, never scrolling off the display. That way, you can -always see the @samp{Next}, @samp{Prev}, and @samp{Up} links, and you -can conveniently go to one of these links at any time by -clicking the middle mouse button on the link. - -@cindex reading Info documents top to bottom -@cindex Info documents as tutorials - @key{SPC} and @key{DEL} not only move forward and backward through -the current node. They also move between nodes. @key{SPC} at the end -of a node moves to the next node; @key{DEL} (or @key{BACKSPACE}) at -the beginning of a node moves to the previous node. In effect, these -commands scroll through all the nodes in an Info file as a single -logical sequence. You can read an entire manual top to bottom by just -typing @key{SPC}, and move backward through the entire manual from -bottom to top by typing @key{DEL} (or @key{BACKSPACE}). - - In this sequence, a node's subnodes appear following their parent. -If a node has a menu, @key{SPC} takes you into the subnodes listed in -the menu, one by one. Once you reach the end of a node, and have seen -all of its subnodes, @key{SPC} takes you to the next node or to the -parent's next node. - -@kindex PAGEUP @r{(Info mode)} -@kindex PAGEDOWN @r{(Info mode)} - Many keyboards nowadays have two scroll keys labeled @samp{PageUp} -and @samp{PageDown} (or maybe @samp{Prior} and @samp{Next}). If your -keyboard has these keys, you can use them to move forward and backward -through the text of one node, like @key{SPC} and @key{BACKSPACE} (or -@key{DEL}). However, @key{PAGEUP} and @key{PAGEDOWN} keys never -scroll beyond the beginning or the end of the current node. - -@kindex C-l @r{(Info mode)} - If your screen is ever garbaged, you can tell Info to display it -again by typing @kbd{C-l} (@kbd{Control-L}---that is, hold down -@key{CTRL} and type @kbd{L} or @kbd{l}). - -@format ->> Type @kbd{C-l} now. -@end format - -@kindex b @r{(Info mode)} - To move back to the beginning of the node you are on, you can type -the @key{BACKSPACE} key (or @key{DEL}) many times. You can also type -@kbd{b} just once. @kbd{b} stands for ``beginning.'' - -@format ->> Try that now. (We have put in enough verbiage to push this past - the first screenful, but screens are so big nowadays that perhaps it - isn't enough. You may need to shrink your Emacs or Info window.) - Then come back, by typing @key{SPC} one or more times. -@end format - -@kindex ? @r{(Info mode)} -@findex Info-summary - You have just learned a considerable number of commands. If you -want to use one but have trouble remembering which, you should type -@kbd{?}, which displays a brief list of commands. When you are -finished looking at the list, make it go away by typing @key{SPC} -repeatedly. - -@format ->> Type a @key{?} now. Press @key{SPC} to see consecutive screenfuls of - the list until finished. Then type @key{SPC} several times. If - you are using Emacs, the help will then go away automatically. -@end format - - (If you are using the stand-alone Info reader, type @kbd{C-x 0} to -return here, that is---press and hold @key{CTRL}, type an @kbd{x}, -then release @key{CTRL} and @kbd{x}, and press @kbd{0}; that's a zero, -not the letter ``o''.) - - From now on, you will encounter large nodes without warning, and -will be expected to know how to use @key{SPC} and @key{BACKSPACE} to -move around in them without being told. Since not all terminals have -the same size screen, it would be impossible to warn you anyway. - -@format ->> Now type @kbd{n}, or click the middle mouse button on the @samp{Next} link, - to visit the next node. -@end format - -@node Help-Inv, Help-M, Help-^L, Getting Started -@comment node-name, next, previous, up -@section Invisible text in Emacs Info - - Before discussing menus, we need to make some remarks that are only -relevant to users reading Info using Emacs. Users of the stand-alone -version can skip this node by typing @kbd{]} now. - -@cindex invisible text in Emacs - In Emacs, certain text that appears in the stand-alone version is -normally hidden, technically because it has the @samp{invisibility} -property. Invisible text is really a part of the text. It becomes -visible (by default) after killing and yanking, it appears in printed -output, it gets saved to file just like any other text, and so on. -Thus it is useful to know it is there. - -@findex visible-mode -You can make invisible text visible by using the command @kbd{M-x -visible-mode}. Visible mode is a minor mode, so using the command a -second time will make the text invisible again. Watch the effects of -the command on the ``menu'' below and the top line of this node. - -If you prefer to @emph{always} see the invisible text, you can set -@code{Info-hide-note-references} to @code{nil}. Enabling Visible mode -permanently is not a real alternative, because Emacs Info also uses -(although less extensively) another text property that can change the -text being displayed, the @samp{display} property. Only the -invisibility property is affected by Visible mode. When, in this -tutorial, we refer to the @samp{Emacs} behavior, we mean the -@emph{default} Emacs behavior. - -Now type @kbd{]}, to learn about the @kbd{]} and @kbd{[} commands. - -@menu -* ]: Help-]. Node telling about ]. -* stuff: Help-]. Same node. -* Help-]:: Yet again, same node. -@end menu - -@node Help-], , , Help-Inv -@subsection The @kbd{]} and @kbd{[} commands - -If you type @kbd{n} now, you get an error message saying that this -node has no next node. Similarly, if you type @kbd{p}, the error -message tells you that there is no previous node. (The exact message -depends on the Info reader you use.) This is because @kbd{n} and -@kbd{p} carry you to the next and previous node @emph{at the same -level}. The present node is contained in a menu (see next) of the -node you came from, and hence is considered to be at a lower level. -It is the only node in the previous node's menu (even though it was -listed three times). Hence it has no next or previous node that -@kbd{n} or @kbd{p} could move to. - -If you systematically move through a manual by typing @kbd{n}, you run -the risk of skipping many nodes. You do not run this risk if you -systematically use @kbd{@key{SPC}}, because, when you scroll to the -bottom of a node and type another @kbd{@key{SPC}}, then this carries -you to the following node in the manual @emph{regardless of level}. -If you immediately want to go to that node, without having to scroll -to the bottom of the screen first, you can type @kbd{]}. - -Similarly, @kbd{@key{BACKSPACE}} carries you to the preceding node -regardless of level, after you scrolled to the beginning of the -present node. If you want to go to the preceding node immediately, -you can type @kbd{[}. - -For instance, typing this sequence will come back here in three steps: -@kbd{[ n [}. To do the same backward, type @kbd{] p ]}. - -Now type @kbd{]} to go to the next node and learn about menus. - -@node Help-M, Help-Xref, Help-Inv, Getting Started -@comment node-name, next, previous, up -@section Menus and the @kbd{m} command - -@cindex menus in an Info document -@cindex Info menus - With only the @kbd{n} (next), @kbd{p} (previous), @kbd{@key{SPC}}, -@kbd{@key{BACKSPACE}}, @kbd{]} and @kbd{[} commands for moving between -nodes, nodes are restricted to a linear sequence. Menus allow a -branching structure. A menu is a list of other nodes you can move to. -It is actually just part of the text of the node formatted specially -so that Info can interpret it. The beginning of a menu is always -identified by a line which starts with @w{@samp{* Menu:}}. A node -contains a menu if and only if it has a line in it which starts that -way. The only menu you can use at any moment is the one in the node -you are in. To use a menu in any other node, you must move to that -node first. - - After the start of the menu, each line that starts with a @samp{*} -identifies one subtopic. The line usually contains a brief name for -the subtopic (followed by a @samp{:}, normally hidden in Emacs), the -name of the node that talks about that subtopic (again, normally -hidden in Emacs), and optionally some further description of the -subtopic. Lines in the menu that do not start with a @samp{*} have no -special meaning---they are only for the human reader's benefit and do -not define additional subtopics. Here is an example: - -@example -* Foo: Node about FOO. This tells about FOO. -@end example - -The subtopic name is Foo, and the node describing it is @samp{Node -about FOO}. The rest of the line is just for the reader's -Information. [[ But this line is not a real menu item, simply because -there is no line above it which starts with @w{@samp{* Menu:}}. Also, -in a real menu item, the @samp{*} would appear at the very start of -the line. This is why the ``normally hidden'' text in Emacs, namely -@samp{: Node about FOO.}, is actually visible in this example, even -when Visible mode is off.]] - - When you use a menu to go to another node (in a way that will be -described soon), what you specify is the subtopic name, the first -thing in the menu line. Info uses it to find the menu line, extracts -the node name from it, and goes to that node. The reason that there -is both a subtopic name and a node name is that the node name must be -meaningful to the computer and may therefore have to be ugly looking. -The subtopic name can be chosen just to be convenient for the user to -specify. Often the node name is convenient for the user to specify -and so both it and the subtopic name are the same. There is an -abbreviation for this: - -@example -* Foo:: This tells about FOO. -@end example - -@noindent -This means that the subtopic name and node name are the same; they are -both @samp{Foo}. (The @samp{::} is normally hidden in Emacs.) - -@format ->> Now use @key{SPC} to find the menu in this node, then come back to - the front with a @kbd{b} and some @key{SPC}s. As you see, a menu is - actually visible in its node. If you cannot find a menu in a node - by looking at it, then the node does not have a menu and the - @kbd{m} command is not available. -@end format - -If you keep typing @key{SPC} once the menu appears on the screen, it -will move to another node (the first one in the menu). If that -happens, type @key{BACKSPACE} to come back. - -@kindex m @r{(Info mode)} - The command to go to one of the subnodes is @kbd{m}. This is very -different from the commands you have used: it is a command that -prompts you for more input. - - The Info commands you know do not need additional input; when you -type one of them, Info processes it instantly and then is ready for -another command. The @kbd{m} command is different: it needs to know -the @dfn{name of the subtopic}. Once you have typed @kbd{m}, Info -tries to read the subtopic name. - - Now, in the stand-alone Info, look for the line containing many -dashes near the bottom of the screen. (This is the stand-alone -equivalent for the mode line in Emacs.) There is one more line -beneath that one, but usually it is blank. (In Emacs, this is the -echo area.) When it is blank, Info is ready for a command, such as -@kbd{n} or @kbd{b} or @key{SPC} or @kbd{m}. If that line contains -text ending in a colon, it means Info is reading more input for the -last command. You can't type an Info command then, because Info is -trying to read input, not commands. You must either give the input -and finish the command you started, or type @kbd{Control-g} to cancel -the command. When you have done one of those things, the input entry -line becomes blank again. Then you can type Info commands again. - -@findex Info-menu - The command to go to a subnode via a menu is @kbd{m}. After you type -the @kbd{m}, the line at the bottom of the screen says @samp{Menu item: }. -You must then type the name of the subtopic you want, and end it with -a @key{RET}. - -@cindex abbreviating Info subnodes - You can abbreviate the subtopic name. If the abbreviation is not -unique, the first matching subtopic is chosen. Some menus put -the shortest possible abbreviation for each subtopic name in capital -letters, so you can see how much you need to type. It does not -matter whether you use upper case or lower case when you type the -subtopic. You should not put any spaces at the end, or inside of the -item name, except for one space where a space appears in the item in -the menu. - -@cindex completion of Info node names - You can also use the @dfn{completion} feature to help enter the -subtopic name. If you type the @key{TAB} key after entering part of a -name, it will fill in more of the name---as much as Info can deduce -from the part you have entered. - - If you move the cursor to one of the menu subtopic lines, then you do -not need to type the argument: you just type a @key{RET}, and it -stands for the subtopic of the line you are on. You can also click -the middle mouse button directly on the subtopic line to go there. - -Here is a menu to give you a chance to practice. This menu gives you -three ways of going to one place, Help-FOO: - -@menu -* Foo: Help-FOO. A node you can visit for fun. -* Bar: Help-FOO. We have made two ways to get to the same place. -* Help-FOO:: And yet another! -@end menu - -(Turn Visible mode on if you are using Emacs.) - -@format ->> Now type just an @kbd{m} and see what happens: -@end format - - Now you are ``inside'' an @kbd{m} command. Commands cannot be used -now; the next thing you will type must be the name of a subtopic. - - You can change your mind about doing the @kbd{m} by typing -@kbd{Control-g}. - -@format ->> Try that now; notice the bottom line clear. -@end format - -@format ->> Then type another @kbd{m}. -@end format - -@format ->> Now type @kbd{BAR}, the item name. Do not type @key{RET} yet. -@end format - - While you are typing the item name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to cancel one character at a time if you make a -mistake. - -@format ->> Press @key{DEL} to cancel the @samp{R}. You could type another @kbd{R} - to replace it. But you do not have to, since @samp{BA} is a valid - abbreviation. -@end format - -@format ->> Now you are ready to go. Type a @key{RET}. -@end format - - After visiting @samp{Help-FOO}, you should return here. - - Another way to move to the menu subtopic lines and between them is -to type @key{TAB}. Each time you type a @key{TAB}, you move to the -next subtopic line. To move to a previous subtopic line in the -stand-alone reader, type @kbd{M-@key{TAB}}---that is, press and hold -the @key{META} key and then press @key{TAB}. (On some keyboards, the -@key{META} key might be labeled @samp{Alt}.) In Emacs Info, type -@kbd{S-@key{TAB}} to move to a previous subtopic line (press and hold -the @key{Shift} key and then press @key{TAB}). - - Once you move cursor to a subtopic line, press @key{RET} to go to -that subtopic's node. - -@cindex mouse support in Info mode -@kindex Mouse-2 @r{(Info mode)} - If your terminal supports a mouse, you have yet another way of going -to a subtopic. Move your mouse pointer to the subtopic line, -somewhere between the beginning @samp{*} and the colon @samp{:} which -ends the subtopic's brief name. You will see the subtopic's name -change its appearance (usually, its background color will change), and -the shape of the mouse pointer will change if your platform supports -that. After a while, if you leave the mouse on that spot, a small -window will pop up, saying ``Mouse-2: go to that node,'' or the same -message may appear at the bottom of the screen. - - @kbd{Mouse-2} is the second button of your mouse counting from the -left---the middle button on a 3-button mouse. (On a 2-button mouse, -you may have to press both buttons together to ``press the middle -button''.) The message tells you pressing @kbd{Mouse-2} with the -current position of the mouse pointer (on subtopic in the menu) will -go to that subtopic. - -@findex Info-mouse-follow-nearest-node - More generally, @kbd{Mouse-2} in an Info buffer finds the nearest -link to another node and goes there. For example, near a cross -reference it acts like @kbd{f}, in a menu it acts like @kbd{m}, on the -node's header line it acts like @kbd{n}, @kbd{p}, or @kbd{u}, etc. At -end of the node's text @kbd{Mouse-2} moves to the next node, or up if -there's no next node. - -@format ->> Type @kbd{n} to see more commands. -@end format - -@node Help-FOO, , , Help-M -@subsection The @kbd{u} command - - Congratulations! This is the node @samp{Help-FOO}. It has an @samp{Up} -pointer @samp{Help-M}, the node you just came from via the @kbd{m} -command. This is the usual convention---the nodes you reach from a menu -have @samp{Up} nodes that lead back to the menu. Menus move Down in the -tree, and @samp{Up} moves Up. @samp{Previous}, on the other hand, is -usually used to ``stay on the same level but go backwards''. - -@kindex u @r{(Info mode)} -@findex Info-up - You can go back to the node @samp{Help-M} by typing the command -@kbd{u} for ``Up''. This puts you at the menu subtopic line pointing -to the subnode that the @kbd{u} command brought you from. (Some Info -readers may put you at the @emph{front} of the node instead---to get -back to where you were reading, you have to type some @key{SPC}s.) - - Another way to go Up is to click @kbd{Mouse-2} on the @samp{Up} -pointer shown in the header line (provided that you have a mouse). - -@format ->> Now type @kbd{u} to move back up to @samp{Help-M}. -@end format - -@node Help-Xref, Help-Int, Help-M, Getting Started -@comment node-name, next, previous, up -@section Following Cross-References - -@cindex cross references in Info documents - In Info documentation, you will see many @dfn{cross references}. -Cross references look like this: @xref{Help-Cross, Cross}. That text -is a real, live cross reference, whose name is @samp{Cross} and which -points to the node named @samp{Help-Cross}. (The node name is hidden -in Emacs. Do @kbd{M-x visible-mode} to show or hide it.) - -@kindex f @r{(Info mode)} -@findex Info-follow-reference - You can follow a cross reference by moving the cursor to it and -press @key{RET}, just as in a menu. In Emacs, you can also click -@kbd{Mouse-1} on a cross reference to follow it; you can see that the -cross reference is mouse-sensitive by moving the mouse pointer to the -reference and watching how the underlying text and the mouse pointer -change in response. - - Another way to follow a cross reference is to type @kbd{f} and then -specify the name of the cross reference (in this case, @samp{Cross}) -as an argument. For this command, it does not matter where the cursor -was. If the cursor is on or near a cross reference, @kbd{f} suggests -that reference name in parentheses as the default; typing @key{RET} -will follow that reference. However, if you type a different -reference name, @kbd{f} will follow the other reference which has that -name. - -@format ->> Type @kbd{f}, followed by @kbd{Cross}, and then @key{RET}. -@end format - - As you enter the reference name, you can use the @key{DEL} (or -@key{BACKSPACE}) key to edit your input. If you change your mind -about following any reference, you can use @kbd{Control-g} to cancel -the command. Completion is available in the @kbd{f} command; you can -complete among all the cross reference names in the current node by -typing a @key{TAB}. - - To get a list of all the cross references in the current node, you -can type @kbd{?} after an @kbd{f}. The @kbd{f} continues to await a -cross reference name even after displaying the list, so if you don't -actually want to follow a reference, you should type a @kbd{Control-g} -to cancel the @kbd{f}. - -@format ->> Type @kbd{f?} to get a list of the cross references in this node. Then - type a @kbd{Control-g} and see how the @samp{f} gives up. -@end format - - The @key{TAB}, @kbd{M-@key{TAB}} and @kbd{S-@key{TAB}} keys, -which move between menu items in a menu, also move between cross -references outside of menus. - - Sometimes a cross reference (or a node) can lead to another file (in -other words another ``manual''), or, on occasion, even a file on a -remote machine (although Info files distributed with Emacs or the -stand-alone Info avoid using remote links). Such a cross reference -looks like this: @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}. (After following this link, type -@kbd{l} to get back to this node.) Here the name @samp{texinfo} -between parentheses refers to the file name. This file name appears -in cross references and node names if it differs from the current -file, so you can always know that you are going to be switching to -another manual and which one. - -However, Emacs normally hides some other text in cross-references. -If you put your mouse over the cross reference, then the information -appearing in a separate box (tool tip) or in the echo area will show -the full cross-reference including the file name and the node name of -the cross reference. If you have a mouse, just leave it over the -cross reference @xref{Top,, Overview of Texinfo, texinfo, Texinfo: -The GNU Documentation Format}, and watch what happens. If you -always like to have that information visible without having to move -your mouse over the cross reference, use @kbd{M-x visible-mode}, or -set @code{Info-hide-note-references} to a value other than @code{t} -(@pxref{Emacs Info Variables}). - -@format ->> Now type @kbd{n} to learn more commands. -@end format - -@node Help-Int, Help-Q, Help-Xref, Getting Started -@comment node-name, next, previous, up -@section Some intermediate Info commands - - The introductory course is almost over; please continue -a little longer to learn some intermediate-level commands. - - Most Info files have an index, which is actually a large node -containing little but a menu. The menu has one menu item for each -topic listed in the index. (As a special feature, menus for indices -may also include the line number within the node of the index entry. -This allows Info readers to go to the exact line of an entry, not just -the start of the containing node.) - - You can get to the index from the main menu of the file with the -@kbd{m} command and the name of the index node; then you can use the -@kbd{m} command again in the index node to go to the node that -describes the topic you want. - - There is also a short-cut Info command, @kbd{i}, which does all of -that for you. It searches the index for a given topic (a string) and -goes to the node which is listed in the index for that topic. -@xref{Search Index}, for a full explanation. - -@kindex l @r{(Info mode)} -@findex Info-history-back -@cindex going back in Info history - If you have been moving around to different nodes and wish to -retrace your steps, the @kbd{l} command (@kbd{l} for @dfn{last}) will -do that, one node-step at a time. As you move from node to node, Info -records the nodes where you have been in a special history list. The -@kbd{l} command revisits nodes in the history list; each successive -@kbd{l} command moves one step back through the history. - -@format ->> Try typing @kbd{p p n} and then three @kbd{l}'s, pausing in between -to see what each @kbd{l} does. You should wind up right back here. -@end format - - Note the difference between @kbd{l} and @kbd{p}: @kbd{l} moves to -where @emph{you} last were, whereas @kbd{p} always moves to the node -which the header says is the @samp{Previous} node (from this node, the -@samp{Prev} link leads to @samp{Help-Xref}). - -@kindex r @r{(Info mode)} -@findex Info-history-forward -@cindex going forward in Info history - You can use the @kbd{r} command (@code{Info-history-forward} in Emacs) -to revisit nodes in the history list in the forward direction, so that -@kbd{r} will return you to the node you came from by typing @kbd{l}. - -@kindex L @r{(Info mode)} -@findex Info-history -@cindex history list of visited nodes - The @kbd{L} command (@code{Info-history} in Emacs) creates a virtual -node that contains a list of all nodes you visited. You can select -a previously visited node from this menu to revisit it. - -@kindex d @r{(Info mode)} -@findex Info-directory -@cindex go to Directory node - The @kbd{d} command (@code{Info-directory} in Emacs) gets you -instantly to the Directory node. This node, which is the first one -you saw when you entered Info, has a menu which leads (directly or -indirectly, through other menus), to all the nodes that exist. The -Directory node lists all the manuals and other Info documents that -are, or could be, installed on your system. - -@format ->> Try doing a @kbd{d}, then do an @kbd{l} to return here (yes, - @emph{do} return). -@end format - -@kindex t @r{(Info mode)} -@findex Info-top-node -@cindex go to Top node - The @kbd{t} command moves to the @samp{Top} node of the manual. -This is useful if you want to browse the manual's main menu, or select -some specific top-level menu item. The Emacs command run by @kbd{t} -is @code{Info-top-node}. - -@format ->> Now type @kbd{n} to see the last node of the course. -@end format - - @xref{Advanced}, for more advanced Info features. - -@c If a menu appears at the end of this node, remove it. -@c It is an accident of the menu updating command. - -@node Help-Q, , Help-Int, Getting Started -@comment node-name, next, previous, up -@section Quitting Info - -@kindex q @r{(Info mode)} -@findex Info-exit -@cindex quitting Info mode - To get out of Info, back to what you were doing before, type @kbd{q} -for @dfn{Quit}. This runs @code{Info-exit} in Emacs. - - This is the end of the basic course on using Info. You have learned -how to move in an Info document, and how to follow menus and cross -references. This makes you ready for reading manuals top to bottom, -as new users should do when they learn a new package. - - Another set of Info commands is useful when you need to find -something quickly in a manual---that is, when you need to use a manual -as a reference rather than as a tutorial. We urge you to learn -these search commands as well. If you want to do that now, follow this -cross reference to @ref{Advanced}. - -Yet another set of commands are meant for experienced users; you can -find them by looking in the Directory node for documentation on Info. -Finding them will be a good exercise in using Info in the usual -manner. - -@format ->> Type @kbd{d} to go to the Info directory node; then type - @kbd{mInfo} and Return, to get to the node about Info and - see what other help is available. -@end format - - -@node Advanced -@chapter Advanced Info Commands - - This chapter describes various advanced Info commands. (If you -are using a stand-alone Info reader, there are additional commands -specific to it, which are documented in several chapters of @ref{Top,, -GNU Info, info-stnd, GNU Info}.) - -@kindex C-q @r{(Info mode)} - One advanced command useful with most of the others described here -is @kbd{C-q}, which ``quotes'' the next character so that it is -entered literally (@pxref{Inserting Text,,,emacs,The GNU Emacs -Manual}). For example, pressing @kbd{?} ordinarily brings up a list -of completion possibilities. If you want to (for example) search for -an actual @samp{?} character, the simplest way is to insert it using -@kbd{C-q ?}. This works the same in Emacs and stand-alone Info. - -@menu -* Search Text:: How to search Info documents. -* Search Index:: How to search the indices for specific subjects. -* Go to node:: How to go to a node by name. -* Choose menu subtopic:: How to choose a menu subtopic by its number. -* Create Info buffer:: How to create a new Info buffer in Emacs. -* Emacs Info Variables:: Variables modifying the behavior of Emacs Info. -@end menu - - -@node Search Text, Search Index, , Advanced -@comment node-name, next, previous, up -@section @kbd{s} searches Info documents - -@cindex searching Info documents -@cindex Info document as a reference - The commands which move between and inside nodes allow you to read -the entire manual or its large portions. But what if you need to find -some information in the manual as fast as you can, and you don't know -or don't remember in what node to look for it? This need arises when -you use a manual as a @dfn{reference}, or when it is impractical to -read the entire manual before you start using the programs it -describes. - - Info has powerful searching facilities that let you find things -quickly. You can search either the manual text or its indices. - -@kindex s @r{(Info mode)} -@findex Info-search - The @kbd{s} command allows you to search a whole Info file for a string. -It switches to the next node if and when that is necessary. You -type @kbd{s} followed by the string to search for, terminated by -@key{RET}. To search for the same string again, just @kbd{s} followed -by @key{RET} will do. The file's nodes are scanned in the order -they are in the file, which has no necessary relationship to the -order that they may be in the tree structure of menus and @samp{next} -pointers. But normally the two orders are not very different. In any -case, you can always look at the mode line to find out what node you have -reached, if the header is not visible (this can happen, because @kbd{s} -puts your cursor at the occurrence of the string, not at the beginning -of the node). - -@kindex C-s @r{(Info mode)} -@kindex C-r @r{(Info mode)} -@findex isearch - Instead of using @kbd{s} in Emacs Info and in the stand-alone Info, -you can use an incremental search started with @kbd{C-s} or @kbd{C-r}. -It can search through multiple Info nodes. @xref{Incremental Search,,, -emacs, The GNU Emacs Manual}. In Emacs, you can disable this behavior -by setting the variable @code{Info-isearch-search} to @code{nil} -(@pxref{Emacs Info Variables}). - -@node Search Index, Go to node, Search Text, Advanced -@comment node-name, next, previous, up -@section @kbd{i} searches the indices for specific subjects - -@cindex searching Info indices -@kindex i @r{(Info mode)} -@findex Info-index - Since most topics in the manual should be indexed, you should try -the index search first before the text search. The @kbd{i} command -prompts you for a subject and then looks up that subject in the -indices. If it finds an index entry with the subject you typed, it -goes to the node to which that index entry points. You should browse -through that node to see whether the issue you are looking for is -described there. If it isn't, type @kbd{,} one or more times to go -through additional index entries which match your subject. - - The @kbd{i} command and subsequent @kbd{,} commands find all index -entries which include the string you typed @emph{as a substring}. -For each match, Info shows in the echo area the full index entry it -found. Often, the text of the full index entry already gives you -enough information to decide whether it is relevant to what you are -looking for, so we recommend that you read what Info shows in the echo -area before looking at the node it displays. - - Since @kbd{i} looks for a substring, you can search for subjects even -if you are not sure how they are spelled in the index. For example, -suppose you want to find something that is pertinent to commands which -complete partial input (e.g., when you type @key{TAB}). If you want -to catch index entries that refer to ``complete,'' ``completion,'' and -``completing,'' you could type @kbd{icomplet@key{RET}}. - - Info documents which describe programs should index the commands, -options, and key sequences that the program provides. If you are -looking for a description of a command, an option, or a key, just type -their names when @kbd{i} prompts you for a topic. For example, if you -want to read the description of what the @kbd{C-l} key does, type -@kbd{iC-l@key{RET}} literally. - -@findex info-apropos -@findex index-apropos -If you aren't sure which manual documents the topic you are looking -for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x -index-apropos} command in the stand-alone reader. It prompts for -a string and then looks up that string in all the indices of all the -Info documents installed on your system. - -@node Go to node, Choose menu subtopic, Search Index, Advanced -@comment node-name, next, previous, up -@section @kbd{g} goes to a node by name - -@kindex g @r{(Info mode)} -@findex Info-goto-node -@cindex go to a node by name - If you know a node's name, you can go there by typing @kbd{g}, the -name, and @key{RET}. Thus, @kbd{gTop@key{RET}} would go to the node -called @samp{Top} in this file. (This is equivalent to @kbd{t}, see -@ref{Help-Int}.) @kbd{gGo to node@key{RET}} would come back here. - - Unlike @kbd{m}, @kbd{g} does not allow the use of abbreviations. -But it does allow completion, so you can type @key{TAB} to complete a -partial node name. - -@cindex go to another Info file - To go to a node in another file, you can include the file name in the -node name by putting it at the front, in parentheses. Thus, -@kbd{g(dir)Top@key{RET}} would go to the Info Directory node, which is -the node @samp{Top} in the Info file @file{dir}. Likewise, -@kbd{g(emacs)Top@key{RET}} goes to the top node of the Emacs manual. - - The node name @samp{*} specifies the whole file. So you can look at -all of the current file by typing @kbd{g*@key{RET}} or all of any -other file with @kbd{g(@var{filename})*@key{RET}}. - -@node Choose menu subtopic, Create Info buffer, Go to node, Advanced -@comment node-name, next, previous, up -@section @kbd{1}--@kbd{9} choose a menu subtopic by its number - -@kindex 1 @r{through} 9 @r{(Info mode)} -@findex Info-nth-menu-item -@cindex select @var{n}'th menu item - If you begrudge each character of type-in which your system requires, -you might like to use the commands @kbd{1}, @kbd{2}, @kbd{3}, @kbd{4}, -@dots{}, @kbd{9}. They are short for the @kbd{m} command together -with a name of a menu subtopic. @kbd{1} goes through the first item -in the current node's menu; @kbd{2} goes through the second item, etc. -In the stand-alone reader, @kbd{0} goes through the last menu item; -this is so you need not count how many entries are there. - - If your display supports multiple fonts, colors or underlining, and -you are using Emacs' Info mode to read Info files, the third, sixth -and ninth menu items have a @samp{*} that stands out, either in color -or in some other attribute, such as underline; this makes it easy to -see at a glance which number to use for an item. - - Some terminals don't support either multiple fonts, colors or -underlining. If you need to actually count items, it is better to use -@kbd{m} instead, and specify the name, or use @key{TAB} to quickly -move between menu items. - -@node Create Info buffer, Emacs Info Variables, Choose menu subtopic, Advanced -@comment node-name, next, previous, up -@section @kbd{M-n} creates a new independent Info buffer in Emacs - -@kindex M-n @r{(Info mode)} -@findex clone-buffer -@cindex multiple Info buffers - If you are reading Info in Emacs, you can select a new independent -Info buffer in a new Emacs window by typing @kbd{M-n}. The new buffer -starts out as an exact copy of the old one, but you will be able to -move independently between nodes in the two buffers. (In Info mode, -@kbd{M-n} runs the Emacs command @code{clone-buffer}.) - - In Emacs Info, you can also produce new Info buffers by giving a -numeric prefix argument to the @kbd{m} and @kbd{g} commands. @kbd{C-u -m} and @kbd{C-u g} go to a new node in exactly the same way that -@kbd{m} and @kbd{g} do, but they do so in a new Info buffer which they -select in another window. - - Another way to produce new Info buffers in Emacs is to use a numeric -prefix argument for the @kbd{C-h i} command (@code{info}) which -switches to the Info buffer with that number. Thus, @kbd{C-u 2 C-h i} -switches to the buffer @samp{*info*<2>}, creating it if necessary. - -@node Emacs Info Variables, , Create Info buffer, Advanced -@comment node-name, next, previous, up -@section Emacs Info-mode Variables - -The following variables may modify the behavior of Info-mode in Emacs; -you may wish to set one or several of these variables interactively, -or in your init file. @xref{Examining, Examining and Setting -Variables, Examining and Setting Variables, emacs, The GNU Emacs -Manual}. The stand-alone Info reader program has its own set of -variables, described in @ref{Variables,, Manipulating Variables, -info-stnd, GNU Info}. - -@vtable @code -@item Info-directory-list -The list of directories to search for Info files. Each element is a -string (directory name) or @code{nil} (try default directory). If not -initialized Info uses the environment variable @env{INFOPATH} to -initialize it, or @code{Info-default-directory-list} if there is no -@env{INFOPATH} variable in the environment. - -If you wish to customize the Info directory search list for both Emacs -Info and stand-alone Info, it is best to set the @env{INFOPATH} -environment variable, since that applies to both programs. - -@item Info-additional-directory-list -A list of additional directories to search for Info documentation files. -These directories are not searched for merging the @file{dir} file. - -@item Info-mode-hook -Hooks run when @code{Info-mode} is called. By default, it contains -the hook @code{turn-on-font-lock} which enables highlighting of Info -files. You can change how the highlighting looks by customizing the -faces @code{info-node}, @code{info-xref}, @code{info-xref-visited}, -@code{info-header-xref}, @code{info-header-node}, @code{info-menu-header}, -@code{info-menu-star}, and @code{info-title-@var{n}} (where @var{n} -is the level of the section, a number between 1 and 4). To customize -a face, type @kbd{M-x customize-face @key{RET} @var{face} @key{RET}}, -where @var{face} is one of the face names listed here. - -@item Info-fontify-maximum-menu-size -Maximum size of menu to fontify if @code{font-lock-mode} is non-@code{nil}. - -@item Info-fontify-visited-nodes -If non-@code{nil}, menu items and cross-references pointing to visited -nodes are displayed in the @code{info-xref-visited} face. - -@item Info-use-header-line -If non-@code{nil}, Emacs puts in the Info buffer a header line showing -the @samp{Next}, @samp{Prev}, and @samp{Up} links. A header line does -not scroll with the rest of the buffer, making these links always -visible. - -@item Info-hide-note-references -As explained in earlier nodes, the Emacs version of Info normally -hides some text in menus and cross-references. You can completely -disable this feature, by setting this option to @code{nil}. Setting -it to a value that is neither @code{nil} nor @code{t} produces an -intermediate behavior, hiding a limited amount of text, but showing -all text that could potentially be useful. - -@item Info-scroll-prefer-subnodes -If set to a non-@code{nil} value, @key{SPC} and @key{BACKSPACE} (or -@key{DEL}) keys in a menu visit subnodes of the current node before -scrolling to its end or beginning, respectively. For example, if the -node's menu appears on the screen, the next @key{SPC} moves to a -subnode indicated by the following menu item. Setting this option to -@code{nil} results in behavior similar to the stand-alone Info reader -program, which visits the first subnode from the menu only when you -hit the end of the current node. The default is @code{nil}. - -@item Info-isearch-search -If non-@code{nil}, isearch in Info searches through multiple nodes. - -@item Info-enable-active-nodes -When set to a non-@code{nil} value, allows Info to execute Lisp code -associated with nodes. The Lisp code is executed when the node is -selected. The Lisp code to be executed should follow the node -delimiter (the @samp{DEL} character) and an @samp{execute: } tag, like -this: - -@example -^_execute: (message "This is an active node!") -@end example -@end vtable - - -@node Expert Info -@chapter Info for Experts - - This chapter explains how to write an Info file by hand. However, -in most cases, writing a Texinfo file is better, since you can use it -to make a printed manual or produce other formats, such as HTML and -DocBook, as well as for generating Info files. - -The @code{makeinfo} command converts a Texinfo file into an Info file; -@code{texinfo-format-region} and @code{texinfo-format-buffer} are GNU -Emacs functions that do the same. - -@xref{Top,, Overview of Texinfo, texinfo, Texinfo: The GNU -Documentation Format}, for how to write a Texinfo file. - -@xref{Creating an Info File,,, texinfo, Texinfo: The GNU Documentation -Format}, for how to create an Info file from a Texinfo file. - -@xref{Installing an Info File,,, texinfo, Texinfo: The GNU -Documentation Format}, for how to install an Info file after you -have created one. - -However, if you want to edit an Info file manually and install it manually, -here is how. - -@menu -* Add:: Describes how to add new nodes to the hierarchy. - Also tells what nodes look like. -* Menus:: How to add to or create menus in Info nodes. -* Cross-refs:: How to add cross-references to Info nodes. -* Tags:: How to make tags tables for Info files. -* Checking:: Checking an Info File. -@end menu - -@node Add, Menus, , Expert Info -@comment node-name, next, previous, up -@section Adding a new node to Info - -To add a new topic to the list in the Info directory, you must: - -@enumerate -@item -Create some nodes, in some file, to document that topic. -@item -Put that topic in the menu in the directory. @xref{Menus, Menu}. -@end enumerate - -@cindex node delimiters - The new node can live in an existing documentation file, or in a new -one. It must have a @samp{^_} character before it (invisible to the -user; this node has one but you cannot see it), and it ends with either -a @samp{^_}, a @samp{^L} (``formfeed''), or the end of file.@footnote{If -you put in a @samp{^L} to end a new node, be sure that there is a -@samp{^_} after it to start the next one, since @samp{^L} cannot -@emph{start} a node. Also, a nicer way to make a node boundary be a -page boundary as well is to put a @samp{^L} @emph{right after} the -@samp{^_}.} - - The @samp{^_} starting a node must be followed by a newline or a -@samp{^L} newline, after which comes the node's header line. The -header line must give the node's name (by which Info finds it), and -state the names of the @samp{Next}, @samp{Previous}, and @samp{Up} -nodes (if there are any). As you can see, this node's @samp{Up} node -is the node @samp{Expert Info}. The @samp{Next} node is @samp{Menus}. - -@cindex node header line format -@cindex format of node headers - The keywords @dfn{Node}, @dfn{Next}, @dfn{Previous}, and @dfn{Up} -may appear in any order, anywhere in the header line, but the -recommended order is the one in this sentence. Each keyword must be -followed by a colon, spaces and tabs, and then the appropriate name. -The name may be terminated with a tab, a comma, or a newline. A space -does not end it; node names may contain spaces. The case of letters -in the names is insignificant. - -@cindex node name format -@cindex Directory node - A node name has two forms. A node in the current file is named by -what appears after the @samp{Node: } in that node's first line. For -example, this node's name is @samp{Add}. A node in another file is -named by @samp{(@var{filename})@var{node-within-file}}, as in -@samp{(info)Add} for this node. If the file name starts with @samp{./}, -then it is relative to the current directory; otherwise, it is -relative starting from the standard directory for Info files of your -site. The name @samp{(@var{filename})Top} can be abbreviated to just -@samp{(@var{filename})}. By convention, the name @samp{Top} is used -for the ``highest'' node in any single file---the node whose @samp{Up} -points out of the file. The @samp{Directory} node is @file{(dir)}, it -points to a file @file{dir} which holds a large menu listing all the -Info documents installed on your site. The @samp{Top} node of a -document file listed in the @samp{Directory} should have an @samp{Up: -(dir)} in it. - -@cindex unstructured documents - The node name @kbd{*} is special: it refers to the entire file. -Thus, @kbd{g*} shows you the whole current file. The use of the -node @kbd{*} is to make it possible to make old-fashioned, -unstructured files into nodes of the tree. - - The @samp{Node:} name, in which a node states its own name, must not -contain a file name, since when Info searches for a node, it does not -expect a file name to be there. The @samp{Next}, @samp{Previous} and -@samp{Up} names may contain them. In this node, since the @samp{Up} -node is in the same file, it was not necessary to use one. - - Note that the nodes in this file have a file name in the header -line. The file names are ignored by Info, but they serve as comments -to help identify the node for the user. - -@node Menus, Cross-refs, Add, Expert Info -@comment node-name, next, previous, up -@section How to Create Menus - - Any node in the Info hierarchy may have a @dfn{menu}---a list of subnodes. -The @kbd{m} command searches the current node's menu for the topic which it -reads from the terminal. - -@cindex menu and menu entry format - A menu begins with a line starting with @w{@samp{* Menu:}}. The -rest of the line is a comment. After the starting line, every line -that begins with a @samp{* } lists a single topic. The name of the -topic---what the user must type at the @kbd{m}'s command prompt to -select this topic---comes right after the star and space, and is -followed by a colon, spaces and tabs, and the name of the node which -discusses that topic. The node name, like node names following -@samp{Next}, @samp{Previous} and @samp{Up}, may be terminated with a -tab, comma, or newline; it may also be terminated with a period. - - If the node name and topic name are the same, then rather than -giving the name twice, the abbreviation @samp{* @var{name}::} may be -used (and should be used, whenever possible, as it reduces the visual -clutter in the menu). - - It is considerate to choose the topic names so that they differ -from each other very near the beginning---this allows the user to type -short abbreviations. In a long menu, it is a good idea to capitalize -the beginning of each item name which is the minimum acceptable -abbreviation for it (a long menu is more than 5 or so entries). - - The nodes listed in a node's menu are called its ``subnodes,'' and it -is their ``superior''. They should each have an @samp{Up:} pointing at -the superior. It is often useful to arrange all or most of the subnodes -in a sequence of @samp{Next} and @samp{Previous} pointers so that -someone who wants to see them all need not keep revisiting the Menu. - - The Info Directory is simply the menu of the node @samp{(dir)Top}---that -is, node @samp{Top} in file @file{.../info/dir}. You can put new entries -in that menu just like any other menu. The Info Directory is @emph{not} the -same as the file directory called @file{info}. It happens that many of -Info's files live in that file directory, but they do not have to; and -files in that directory are not automatically listed in the Info -Directory node. - - Also, although the Info node graph is claimed to be a ``hierarchy,'' -in fact it can be @emph{any} directed graph. Shared structures and -pointer cycles are perfectly possible, and can be used if they are -appropriate to the meaning to be expressed. There is no need for all -the nodes in a file to form a connected structure. In fact, this file -has two connected components. You are in one of them, which is under -the node @samp{Top}; the other contains the node @samp{Help} which the -@kbd{h} command goes to. In fact, since there is no garbage -collector on the node graph, nothing terrible happens if a substructure -is not pointed to, but such a substructure is rather useless since nobody -can ever find out that it exists. - -@node Cross-refs, Tags, Menus, Expert Info -@comment node-name, next, previous, up -@section Creating Cross References - -@cindex cross reference format - A cross reference can be placed anywhere in the text, unlike a menu -item which must go at the front of a line. A cross reference looks -like a menu item except that it has @samp{*note} instead of @samp{*}. -It @emph{cannot} be terminated by a @samp{)}, because @samp{)}'s are -so often part of node names. If you wish to enclose a cross reference -in parentheses, terminate it with a period first. Here are two -examples of cross references pointers: - -@example -*Note details: commands. (See *note 3: Full Proof.) -@end example - -@noindent -@emph{These are just examples.} The places they ``lead to'' do not -really exist! - -@menu -* Help-Cross:: Target of a cross-reference. -@end menu - - -@node Help-Cross, , , Cross-refs -@subsection The node reached by the cross reference in Info - - This is the node reached by the cross reference named @samp{Cross}. - - While this node is specifically intended to be reached by a cross -reference, most cross references lead to nodes that ``belong'' -someplace else far away in the structure of an Info document. So you -cannot expect this node to have a @samp{Next}, @samp{Previous} or -@samp{Up} links pointing back to where you came from. In general, the -@kbd{l} (el) command is the only way to get back there. - -@format ->> Type @kbd{l} to return to the node where the cross reference was. -@end format - -@node Tags, Checking, Cross-refs, Expert Info -@comment node-name, next, previous, up -@section Tags Tables for Info Files - -@cindex tags tables in Info files - You can speed up the access to nodes of a large Info file by giving -it a tags table. Unlike the tags table for a program, the tags table for -an Info file lives inside the file itself and is used -automatically whenever Info reads in the file. - -@findex Info-tagify - To make a tags table, go to a node in the file using Emacs Info mode and type -@kbd{M-x Info-tagify}. Then you must use @kbd{C-x C-s} to save the -file. Info files produced by the @code{makeinfo} command that is part -of the Texinfo package always have tags tables to begin with. - -@cindex stale tags tables -@cindex update Info tags table - Once the Info file has a tags table, you must make certain it is up -to date. If you edit an Info file directly (as opposed to editing its -Texinfo source), and, as a result of deletion of text, any node moves back -more than a thousand characters in the file from the position -recorded in the tags table, Info will no longer be able to find that -node. To update the tags table, use the @code{Info-tagify} command -again. - - An Info file tags table appears at the end of the file and looks like -this: - -@example -^_^L -Tag Table: -File: info, Node: Cross-refs^?21419 -File: info, Node: Tags^?22145 -^_ -End Tag Table -@end example - -@noindent -Note that it contains one line per node, and this line contains -the beginning of the node's header (ending just after the node name), -a @samp{DEL} character, and the character position in the file of the -beginning of the node. - -@node Checking, , Tags, Expert Info -@section Checking an Info File - -When creating an Info file, it is easy to forget the name of a node when -you are making a pointer to it from another node. If you put in the -wrong name for a node, this is not detected until someone tries to go -through the pointer using Info. Verification of the Info file is an -automatic process which checks all pointers to nodes and reports any -pointers which are invalid. Every @samp{Next}, @samp{Previous}, and -@samp{Up} is checked, as is every menu item and every cross reference. In -addition, any @samp{Next} which does not have a @samp{Previous} pointing -back is reported. Only pointers within the file are checked, because -checking pointers to other files would be terribly slow. But those are -usually few. - -@findex Info-validate -To check an Info file, do @kbd{M-x Info-validate} while looking at any -node of the file with Emacs Info mode. - -@node Index -@unnumbered Index - -This is an alphabetical listing of all the commands, variables, and -topics discussed in this document. - -@printindex cp - -@bye - -@ignore - arch-tag: 965c1638-01d6-4156-9227-b10418b9d8e8 -@end ignore diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi deleted file mode 100644 index a059a48193a..00000000000 --- a/doc/misc/mairix-el.texi +++ /dev/null @@ -1,355 +0,0 @@ -\input texinfo.tex - -@setfilename ../../info/mairix-el -@settitle Emacs Interface for Mairix - -@documentencoding ISO-8859-1 - -@copying -Copyright @copyright{} 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Mairix: (mairix-el). Emacs interface to the Mairix mail indexer. -@end direntry - -@titlepage -@title mairix.el - Mairix interface for Emacs - -@author David Engster -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top mairix.el - Mairix interface for Emacs - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. - -@code{mairix.el} is an interface to the mairix search engine. It allows you to -call mairix with a search term, easily create searches based on the -currently displayed mail, save regularly used searches in your -@file{.emacs} for future use and lets you call mairix for updating the -database. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* About mairix and mairix.el:: About the mairix search engine and mairix.el -* Configuring mairix:: How to configure mairix -* Setting up mairix.el:: Set up mairix.el -* Using mairix.el:: List of interactive functions -* Extending mairix.el:: Support your favorite mail reader! -@end menu - -@node About mairix and mairix.el -@chapter About mairix and mairix.el - -Mairix is a tool for indexing and searching words in locally stored -mail. It was written by Richard Curnow and is licensed under the -GPL. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), Mac OS X and Solaris. The homepage can -be found at -@uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} - -Though mairix might not be as flexible as other search tools like -swish++ or namazu, it has the prime advantage of being incredibly fast. -On current systems, it can easily search through headers and message -bodies of thousands and thousands of mails in well under a second. -Building the database necessary for searching might take a minute or -two, but only has to be done once fully. Afterwards, the updates are -done incrementally and therefore are really fast, too. Additionally, -mairix is very easy to set up. - -Mairix presents the search results by either populating a @emph{virtual} -maildir/MH folder with symlinks which point to the ``real'' message -files, or if mbox is used, it creates a new mbox file which contains -copies of the found messages. - -@code{mairix.el} is an interface to the mairix search engine. It allows -you to call mairix with a search term, easily create searches based on -the currently displayed mail, save regularly used searches in your -@file{.emacs} for future use and lets you call mairix for updating the -database. It also lets you easily create search queries using graphical -widgets, similar to a customization buffer. - -Currently, @code{mairix.el} is only tested with mbox output together -with RMail, Gnus, or VM as the Emacs mail program. However, it should -also work with Maildir or MH, and it should be very easy to integrate -other Emacs mail programs into @code{mairix.el} -(@pxref{Extending mairix.el}). - -If you use Gnus with maildir or MH, you should really use the native -Gnus back end @code{nnmairix} instead, since it is more tightly -integrated into Gnus and has more features. - -@node Configuring mairix -@chapter Configuring mairix - -Setting up mairix is easy: simply create a @file{.mairixrc} file with -(at least) the following entries: - -@example -# Your mail base folder -base=~/Mail -@end example - -This is the base folder for your mails. All the following directories, -except the one for the database, are relative to this base folder. - -@example -mbox = ... your mbox files which should be indexed ... -maildir= ... your maildir folders which should be indexed ... -mh= ... your nnml/mh folders which should be indexed ... -@end example - -Specify all your maildir/nnml folders and mbox files (relative to the -base directory!) you want to index with mairix. Use colons to separate -different files. See the man-page for @code{mairixrc} for details. - -@example -mformat = mbox -database = ... location of database file ... -@end example - -This chooses @code{mbox} as the output format for the mairix search -results. Currently, this is the supported format by mairix.el, but -technically it should be possible to also use maildir or mh; it's just -not tested (yet). - -You should make sure that you don't accidentally index the search -results produced by mairix. This can be done by pointing -`mairix-file-path' to a directory which is surely not indexed by mairix. -Another possibility is to use something like - -@example -omit = mairix* -@end example - -in the @file{.mairixrc} file, and prefix every search file you use with -``mairix''. - -@example -database = /home/user/.mairixdatabase -@end example - -This specifies the name of the database file. Note that this is not -relative to the @code{base} folder. - -See the man page for @code{mairixrc} for details and further options, -especially regarding wildcard usage, which may be a little different -than you are used to. - -Now simply call @code{mairix} to create the index for the first time. -Note that this may take a few minutes, but every following index will do -the updates incrementally and hence is very fast. - -@node Setting up mairix.el -@chapter Setting up mairix.el - -First, put @code{mairix.el} in your Emacs search path and put -@code{(require 'mairix)} into your @file{.emacs} file. Then, use -@kbd{M-x customize-group mairix RET} to set your preferences for -mairix.el. The most important items are @emph{Mairix File Path}, -@emph{Mairix Search File} and @emph{Mairix Mail Program}. The latter -specifies which mail program should be used to display the mairix search -results. Currently, RMail, Gnus with mbox files, and VM are supported. -If you use Gnus with maildir or mh, use the native Gnus back end -nnmairix instead. - -If you use another Emacs mail program which is not yet supported by -mairix.el, it is pretty easy to integrate it. @xref{Extending -mairix.el}, on how to integrate it into mairix.el. - -Now you should be ready to go. @xref{Using mairix.el}, for the available -commands. - -@node Using mairix.el -@chapter Using mairix.el - -There are currently no default key bindings for mairix.el, since those -should depend on the used mail program and I personally do not use -RMail, so I wouldn't know which key bindings are reasonable. I hope some -day this will change and @code{mairix.el} will come with some good -key bindings for the different mail programs. Feel free to send me your -suggestions. Until then, define some bindings yourself. Here's a quick -and dirty solution with global key definitions I currently use, which -might or might not collide with some other modes. Simply include them -in your @file{.emacs} and adapt to your needs: - -@lisp -(global-set-key (kbd "C-c C-o m") 'mairix-search) -(global-set-key (kbd "C-c C-o w") 'mairix-widget-search) -(global-set-key (kbd "C-c C-o u") 'mairix-update-database) -(global-set-key (kbd "C-c C-o f") 'mairix-search-from-this-article) -(global-set-key (kbd "C-c C-o t") 'mairix-search-thread-this-article) -(global-set-key (kbd "C-c C-o b") 'mairix-widget-search-based-on-article) -(global-set-key (kbd "C-c C-o s") 'mairix-save-search) -(global-set-key (kbd "C-c C-o i") 'mairix-use-saved-search) -(global-set-key (kbd "C-c C-o e") 'mairix-edit-saved-searches) -@end lisp - -Here's a description of the available interactive functions: - -@table @code - -@item mairix-search -@kindex M-x mairix-search -@findex mairix-search -@vindex mairix-search-file -@vindex mairix-file-path -@vindex mairix-command -@vindex mairix-search-options -Call mairix with a search query. You will also be asked if you want to -include whole threads. The results are saved by mairix in the default -mail file, which is set through the variable `mairix-search-file', which -again is prefixed by `mairix-file-path'. The results will then be -displayed with the chosen mail program. The command used to call mairix -is specified by the variable `mairix-command', together with the options -`mairix-search-options'. The latter has the default ``-F'' for making -searching faster. - -@item mairix-widget-search -@kindex M-x mairix-widget-search -@findex mairix-widget-search -@vindex mairix-widget-fields-list -Creates a mairix query using graphical widgets. Very handy if you're -not (yet) familiar with the mairix search syntax. Just call it to see -how it works. You can then directly call mairix with the search term or -save it for future use. Since mairix allows almost arbitrary -combinations of search commands (like ``tc'' for ``to or cc''), you -might want to include some other fields. This can be easily done by -modifying `mairix-widget-fields-list'. - -@item mairix-widget-search-based-on-article -@kindex M-x mairix-widget-search-based-on-article -@findex mairix-widget-search-based-on-article -Create a mairix query using graphical widgets, but based on the -currently displayed article, i.e. the available fields will be filled -with the current header values. - -@item mairix-search-from-this-article -@kindex M-x mairix-search-from-this-article -@findex mairix-search-from-this-article -Search messages from sender of the current article. This is effectively -a shortcut for calling @code{mairix-search} with @code{f:current_from}. -If used with a prefix, include whole threads of the found messages. - -@item mairix-search-thread-this-article -@kindex M-x mairix-search-thread-this-article -@findex mairix-search-thread-this-article -Search thread for the current article. This is effectively a shortcut -for calling @code{mairix-search} with @code{m:msgid} of the current article and -enabled threads. - -@item mairix-save-search -@kindex M-x mairix-save-search -@findex mairix-save-search -Save the last search for future use. You will have to specify a name -for the search and will then be asked if you want to save your saved -searches in your @file{.emacs}. If you answer with yes, the variable -@code{mairix-saved-searches} will be saved in the customize section of -your @file{.emacs}. You can also do this later by using -`mairix-edit-saved-searches'. - -@item mairix-use-saved-search -@kindex M-x mairix-use-saved-search -@findex mairix-use-saved-search -Call mairix with a previously saved search. You will be asked for the -name of the saved search (use @kbd{TAB} for completion). - -@item mairix-edit-saved-searches -@kindex M-x mairix-edit-saved-searches -@findex mairix-edit-saved-searches -Edit your current mairix searches. This is a simple major mode for -editing the contents of the variable @code{mairix-saved-searches}. You -can edit and delete searches and save them in your @file{.emacs}. You -can also use this mode to call mairix with one of the saved searches. -Additionally, you can specify a file name for mairix to use for a -certain search instead of the default one. This is useful if you want -to open different searches at the same time, or if you want to regularly -access certain searches without the need to call mairix. - -@item mairix-edit-saved-searches-customize -@kindex M-x mairix-edit-saved-searches-customize -@findex mairix-edit-saved-searches-customize -Edit the variable @code{mairix-saved-searches} in a normal customization -buffer. This function exists more or less for historic reasons, but -maybe you like it. - -@item mairix-update-database -@kindex M-x mairix-update-database -@findex mairix-update-database -@vindex mairix-update-options -@vindex mairix-synchronous-update -Call mairix to update the database. Mairix will be called with the -options `mairix-update-options'; the default is ``-F'' and ``-Q'' to -make updates as fast as possible. Note that by using these options, -absolutely no integrity checking is done. If your database somehow gets -corrupted, simply delete it and update. If `mairix-synchronous-update' -is nil (the default), mairix will be called in a subprocess so Emacs -will still be usable while the update is done. - -@end table - - -@node Extending mairix.el -@chapter Extending mairix.el - -Your favorite Emacs mail program is not supported? Shame on me. But -it is really easy to integrate other mail programs into mairix.el. Just -do the following: - -@table @strong -@item Write a display function -Write a function that displays the mairix search results. This function -will be called from @code{mairix.el} with the mail file/folder as the -single argument. For example, the function @code{mairix-rmail-display} -is currently used for RMail and @code{mairix-gnus-ephemeral-nndoc} is -used for Gnus. - -@item Write a get-header function -Write a function that retrieves a header from the currently active mail. -The single argument for this function is a string with the header name. -For examples, see @code{mairix-rmail-fetch-field} and -@code{mairix-gnus-fetch-field} for RMail and Gnus, respectively. - -@item Integrate the functions into mairix.el -Add your mail program to the defcustom of @code{mairix-mail-program}. -Then add the functions to @code{mairix-display-functions} and -@code{mairix-get-mail-header-functions}. - -@item Let me know... -...so that I can eventually integrate it into future versions of mairix.el. -@end table - -And that's it! - - - -@bye - -@ignore - arch-tag: cb81470f-e080-489d-bb67-0d11516b63b9 -@end ignore diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in deleted file mode 100644 index c48df1d884c..00000000000 --- a/doc/misc/makefile.w32-in +++ /dev/null @@ -1,357 +0,0 @@ -#### -*- Makefile -*- for documentation other than the Emacs manual. - -# Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -# Free Software Foundation, Inc. - -# This file is part of GNU Emacs. - -# GNU Emacs is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. - -# GNU Emacs is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GNU Emacs. If not, see . - - -# Where to find the source code. The source code for Emacs's C kernel is -# expected to be in $(srcdir)/src, and the source code for Emacs's -# utility programs is expected to be in $(srcdir)/lib-src. This is -# set by the configure script's `--srcdir' option. -srcdir=. - -infodir = $(srcdir)/../../info - -# The makeinfo program is part of the Texinfo distribution. -MAKEINFO = makeinfo --force -MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat -INFO_TARGETS = $(infodir)/ccmode \ - $(infodir)/cl $(infodir)/dbus $(infodir)/dired-x \ - $(infodir)/ediff $(infodir)/forms $(infodir)/gnus \ - $(infodir)/message $(infodir)/sieve $(infodir)/pgg \ - $(infodir)/emacs-mime $(infodir)/info $(infodir)/mh-e \ - $(infodir)/reftex $(infodir)/sc $(infodir)/vip \ - $(infodir)/viper $(infodir)/widget $(infodir)/efaq \ - $(infodir)/ada-mode $(infodir)/autotype $(infodir)/calc \ - $(infodir)/idlwave $(infodir)/eudc $(infodir)/ebrowse \ - $(infodir)/pcl-cvs $(infodir)/woman $(infodir)/eshell \ - $(infodir)/org $(infodir)/url $(infodir)/speedbar \ - $(infodir)/tramp $(infodir)/ses $(infodir)/smtpmail \ - $(infodir)/flymake $(infodir)/newsticker $(infodir)/rcirc \ - $(infodir)/erc $(infodir)/remember $(infodir)/nxml-mode \ - $(infodir)/epa $(infodir)/mairix-el $(infodir)/sasl \ - $(infodir)/auth -DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \ - ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ - sieve.dvi pgg.dvi mh-e.dvi \ - reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \ - ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ - pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ - speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ - newsticker.dvi rcirc.dvi erc.dvi remember.dvi nxml-mode.dvi \ - epa.dvi mairix-el.dvi sasl.dvi auth.dvi -INFOSOURCES = info.texi - -# The following rule does not work with all versions of `make'. -.SUFFIXES: .texi .dvi -.texi.dvi: - texi2dvi $< - -TEXI2DVI = texi2dvi -ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ - "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C - - -info: $(INFO_TARGETS) - -dvi: $(DVI_TARGETS) - -# Note that all the Info targets build the Info files -# in srcdir. There is no provision for Info files -# to exist in the build directory. -# In a distribution of Emacs, the Info files should be up to date. - -$(infodir)/dir: - $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) - -# The following target uses an explicit -o switch to work around -# the @setfilename directive in info.texi, which is required for -# the Texinfo distribution. -# Some Windows ports of makeinfo seem to require -o to come before the -# texi filename, contrary to GNU standards. - -$(infodir)/info: $(INFOSOURCES) - $(MAKEINFO) --no-split -o $@ info.texi - -info.dvi: $(INFOSOURCES) - $(ENVADD) $(TEXI2DVI) $(srcdir)/info.texi - - -$(infodir)/ccmode: cc-mode.texi - $(MAKEINFO) cc-mode.texi -cc-mode.dvi: cc-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/cc-mode.texi - -$(infodir)/ada-mode: ada-mode.texi - $(MAKEINFO) ada-mode.texi -ada-mode.dvi: ada-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ada-mode.texi - -$(infodir)/pcl-cvs: pcl-cvs.texi - $(MAKEINFO) pcl-cvs.texi -pcl-cvs.dvi: pcl-cvs.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/pcl-cvs.texi - -$(infodir)/eshell: eshell.texi - $(MAKEINFO) eshell.texi -eshell.dvi: eshell.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/eshell.texi - -$(infodir)/cl: cl.texi - $(MAKEINFO) cl.texi -cl.dvi: cl.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/cl.texi - -$(infodir)/dbus: dbus.texi - $(MAKEINFO) dbus.texi -dbus.dvi: dbus.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/dbus.texi - -$(infodir)/dired-x: dired-x.texi - $(MAKEINFO) dired-x.texi -dired-x.dvi: dired-x.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/dired-x.texi - -$(infodir)/ediff: ediff.texi - $(MAKEINFO) ediff.texi -ediff.dvi: ediff.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ediff.texi - -$(infodir)/flymake: flymake.texi - $(MAKEINFO) flymake.texi -flymake.dvi: flymake.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/flymake.texi - -$(infodir)/forms: forms.texi - $(MAKEINFO) forms.texi -forms.dvi: forms.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/forms.texi - -# gnus/message/emacs-mime/sieve/pgg are part of Gnus: -$(infodir)/gnus: gnus.texi - $(MAKEINFO) gnus.texi -gnus.dvi: gnus.texi - sed -e "/@iflatex/,/@end iflatex/d" $(srcdir)/gnus.texi > gnustmp.texi - $(ENVADD) $(TEXI2DVI) gnustmp.texi - cp gnustmp.dvi $*.dvi - rm gnustmp.* -# -$(infodir)/message: message.texi - $(MAKEINFO) message.texi -message.dvi: message.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/message.texi -# -$(infodir)/emacs-mime: emacs-mime.texi - $(MAKEINFO) --enable-encoding emacs-mime.texi -emacs-mime.dvi: emacs-mime.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-mime.texi -# -$(infodir)/sieve: sieve.texi - $(MAKEINFO) sieve.texi -sieve.dvi: sieve.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sieve.texi -# -$(infodir)/pgg: pgg.texi - $(MAKEINFO) pgg.texi -pgg.dvi: pgg.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/pgg.texi - -$(infodir)/mh-e: mh-e.texi - $(MAKEINFO) mh-e.texi -mh-e.dvi: mh-e.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/mh-e.texi - -$(infodir)/reftex: reftex.texi - $(MAKEINFO) reftex.texi -reftex.dvi: reftex.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/reftex.texi - -$(infodir)/remember: remember.texi - $(MAKEINFO) remember.texi -remember.dvi: remember.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/remember.texi - -$(infodir)/sasl: sasl.texi - $(MAKEINFO) sasl.texi -sasl.dvi: sasl.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sasl.texi - -$(infodir)/sc: sc.texi - $(MAKEINFO) sc.texi -sc.dvi: sc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/sc.texi - -$(infodir)/vip: vip.texi - $(MAKEINFO) vip.texi -vip.dvi: vip.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/vip.texi - -$(infodir)/viper: viper.texi - $(MAKEINFO) viper.texi -viper.dvi: viper.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/viper.texi - -$(infodir)/widget: widget.texi - $(MAKEINFO) widget.texi -widget.dvi: widget.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/widget.texi - -$(infodir)/efaq: faq.texi - $(MAKEINFO) faq.texi -faq.dvi: faq.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/faq.texi - -$(infodir)/autotype: autotype.texi - $(MAKEINFO) autotype.texi -autotype.dvi: autotype.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/autotype.texi - -$(infodir)/calc: calc.texi - $(MAKEINFO) calc.texi - -calc.dvi: calc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/calc.texi - -# This is produced with --no-split to avoid making files whose -# names clash on DOS 8+3 filesystems -$(infodir)/idlwave: idlwave.texi - $(MAKEINFO) --no-split idlwave.texi -idlwave.dvi: idlwave.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/idlwave.texi - -$(infodir)/eudc: eudc.texi - $(MAKEINFO) eudc.texi -eudc.dvi: eudc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/eudc.texi - -$(infodir)/ebrowse: ebrowse.texi - $(MAKEINFO) ebrowse.texi -ebrowse.dvi: ebrowse.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ebrowse.texi - -$(infodir)/woman: woman.texi - $(MAKEINFO) woman.texi -woman.dvi: woman.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/woman.texi - -$(infodir)/speedbar: speedbar.texi - $(MAKEINFO) speedbar.texi -speedbar.dvi: speedbar.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/speedbar.texi - -$(infodir)/tramp: tramp.texi - $(MAKEINFO) tramp.texi -tramp.dvi: tramp.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/tramp.texi - -$(infodir)/ses: ses.texi - $(MAKEINFO) ses.texi -ses.dvi: ses.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/ses.texi - -$(infodir)/smtpmail: smtpmail.texi - $(MAKEINFO) smtpmail.texi -smtpmail.dvi: smtpmail.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/smtpmail.texi - -$(infodir)/org: org.texi - $(MAKEINFO) org.texi -org.dvi: org.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/org.texi - -$(infodir)/url: url.texi - $(MAKEINFO) url.texi -url.dvi: url.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/url.texi - -$(infodir)/newsticker: newsticker.texi - $(MAKEINFO) newsticker.texi -newsticker.dvi: newsticker.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/newsticker.texi - -$(infodir)/nxml-mode: nxml-mode.texi - $(MAKEINFO) nxml-mode.texi -nxml-mod.dvi: nxml-mode.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/nxml-mode.texi - -$(infodir)/rcirc: rcirc.texi - $(MAKEINFO) rcirc.texi -rcirc.dvi: rcirc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/rcirc.texi - -$(infodir)/erc: erc.texi - $(MAKEINFO) erc.texi -erc.dvi: erc.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/erc.texi - -$(infodir)/epa: epa.texi - $(MAKEINFO) epa.texi -epa.dvi: epa.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/epa.texi - -$(infodir)/mairix-el: mairix-el.texi - $(MAKEINFO) mairix-el.texi -mairix-el.dvi: mairix-el.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/mairix-el.texi - -$(infodir)/auth: auth.texi - $(MAKEINFO) auth.texi -auth.dvi: auth.texi - $(ENVADD) $(TEXI2DVI) $(srcdir)/auth.texi - -mostlyclean: - - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* - -clean: mostlyclean - - $(DEL) *.dvi - - $(DEL) $(infodir)/ccmode* $(infodir)/cl* \ - $(infodir)/dbus* $(infodir)/dired-x* \ - $(infodir)/ediff* $(infodir)/forms* \ - $(infodir)/gnus* $(infodir)/info* \ - $(infodir)/message* $(infodir)/mh-e* \ - $(infodir)/reftex* $(infodir)/sc* \ - $(infodir)/vip* $(infodir)/widget* \ - $(infodir)/efaq* $(infodir)/ada-mode* \ - $(infodir)/autotype* $(infodir)/calc* \ - $(infodir)/idlwave* $(infodir)/eudc* \ - $(infodir)/ebrowse* $(infodir)/pcl-cvs* \ - $(infodir)/woman* $(infodir)/eshell* \ - $(infodir)/speedbar* $(infodir)/tramp* \ - $(infodir)/ses* $(infodir)/smtpmail* \ - $(infodir)/url* $(infodir)/org* \ - $(infodir)/flymake* $(infodir)/newsticker* \ - $(infodir)/sieve* $(infodir)/pgg* \ - $(infodir)/erc* $(infodir)/rcirc* \ - $(infodir)/remember* $(infodir)/nxml-mode* \ - $(infodir)/epa* $(infodir)/sasl* \ - $(infodir)/mairix-el* $(infodir)/auth* - -distclean: clean - - $(DEL) makefile - -maintainer-clean: distclean - - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc -# Don't delete these, because they are outside the current directory. -# for file in $(INFO_TARGETS); do rm -f $${file}*; done - - -# Formerly this directory had texindex.c and getopt.c in it -# and this makefile built them to make texindex. -# That caused trouble because this is run entirely in the source directory. -# Since we expect to get texi2dvi from elsewhere, -# it is ok to expect texindex from elsewhere also. diff --git a/doc/misc/message.texi b/doc/misc/message.texi deleted file mode 100644 index 388745c4c31..00000000000 --- a/doc/misc/message.texi +++ /dev/null @@ -1,2446 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@setfilename ../../info/message -@settitle Message Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp -@copying -This file documents Message, the Emacs message composition mode. - -Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, -2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Message: (message). Mail and news composition mode that goes with Gnus. -@end direntry -@iftex -@finalout -@end iftex - -@titlepage -@title Message Manual - -@author by Lars Magne Ingebrigtsen -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top Message - -@ifnottex -@insertcopying -@end ifnottex - -All message composition from Gnus (both mail and news) takes place in -Message mode buffers. - -@menu -* Interface:: Setting up message buffers. -* Commands:: Commands you can execute in message mode buffers. -* Variables:: Customizing the message buffers. -* Compatibility:: Making Message backwards compatible. -* Appendices:: More technical things. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function and concept index. -* Key Index:: List of Message mode keys. -@end menu - -@c Adjust ../Makefile.in if you change the following lines: -Message is distributed with Gnus. The Gnus distribution -@c -corresponding to this manual is Gnus v5.13 - - -@node Interface -@chapter Interface - -When a program (or a person) wants to respond to a message---reply, -follow up, forward, cancel---the program (or person) should just put -point in the buffer where the message is and call the required command. -@code{Message} will then pop up a new @code{message} mode buffer with -appropriate headers filled out, and the user can edit the message before -sending it. - -@menu -* New Mail Message:: Editing a brand new mail message. -* New News Message:: Editing a brand new news message. -* Reply:: Replying via mail. -* Wide Reply:: Responding to all people via mail. -* Followup:: Following up via news. -* Canceling News:: Canceling a news article. -* Superseding:: Superseding a message. -* Forwarding:: Forwarding a message via news or mail. -* Resending:: Resending a mail message. -* Bouncing:: Bouncing a mail message. -* Mailing Lists:: Send mail to mailing lists. -@end menu - -You can customize the Message Mode tool bar, see @kbd{M-x -customize-apropos RET message-tool-bar}. This feature is only available -in Emacs. - -@node New Mail Message -@section New Mail Message - -@findex message-mail -The @code{message-mail} command pops up a new message buffer. - -Two optional parameters are accepted: The first will be used as the -@code{To} header and the second as the @code{Subject} header. If these -are @code{nil}, those two headers will be empty. - - -@node New News Message -@section New News Message - -@findex message-news -The @code{message-news} command pops up a new message buffer. - -This function accepts two optional parameters. The first will be used -as the @code{Newsgroups} header and the second as the @code{Subject} -header. If these are @code{nil}, those two headers will be empty. - - -@node Reply -@section Reply - -@findex message-reply -The @code{message-reply} function pops up a message buffer that's a -reply to the message in the current buffer. - -@vindex message-reply-to-function -Message uses the normal methods to determine where replies are to go -(@pxref{Responses}), but you can change the behavior to suit your needs -by fiddling with the @code{message-reply-to-function} variable. - -If you want the replies to go to the @code{Sender} instead of the -@code{From}, you could do something like this: - -@lisp -(setq message-reply-to-function - (lambda () - (cond ((equal (mail-fetch-field "from") "somebody") - (list (cons 'To (mail-fetch-field "sender")))) - (t - nil)))) -@end lisp - -This function will be called narrowed to the head of the article that is -being replied to. - -As you can see, this function should return a list. In this case, it -returns @code{((To . "Whom"))} if it has an opinion as to what the To -header should be. If it does not, it should just return @code{nil}, and -the normal methods for determining the To header will be used. - -Each list element should be a cons, where the @sc{car} should be the -name of a header (e.g. @code{Cc}) and the @sc{cdr} should be the header -value (e.g. @samp{larsi@@ifi.uio.no}). All these headers will be -inserted into the head of the outgoing mail. - - -@node Wide Reply -@section Wide Reply - -@findex message-wide-reply -The @code{message-wide-reply} pops up a message buffer that's a wide -reply to the message in the current buffer. A @dfn{wide reply} is a -reply that goes out to all people listed in the @code{To}, @code{From} -(or @code{Reply-to}) and @code{Cc} headers. - -@vindex message-wide-reply-to-function -Message uses the normal methods to determine where wide replies are to go, -but you can change the behavior to suit your needs by fiddling with the -@code{message-wide-reply-to-function}. It is used in the same way as -@code{message-reply-to-function} (@pxref{Reply}). - -@vindex message-dont-reply-to-names -Addresses that match the @code{message-dont-reply-to-names} regular -expression (or list of regular expressions) will be removed from the -@code{Cc} header. A value of @code{nil} means exclude your name only. - -@vindex message-wide-reply-confirm-recipients -If @code{message-wide-reply-confirm-recipients} is non-@code{nil} you -will be asked to confirm that you want to reply to multiple -recipients. The default is @code{nil}. - -@node Followup -@section Followup - -@findex message-followup -The @code{message-followup} command pops up a message buffer that's a -followup to the message in the current buffer. - -@vindex message-followup-to-function -Message uses the normal methods to determine where followups are to go, -but you can change the behavior to suit your needs by fiddling with the -@code{message-followup-to-function}. It is used in the same way as -@code{message-reply-to-function} (@pxref{Reply}). - -@vindex message-use-followup-to -The @code{message-use-followup-to} variable says what to do about -@code{Followup-To} headers. If it is @code{use}, always use the value. -If it is @code{ask} (which is the default), ask whether to use the -value. If it is @code{t}, use the value unless it is @samp{poster}. If -it is @code{nil}, don't use the value. - - -@node Canceling News -@section Canceling News - -@findex message-cancel-news -The @code{message-cancel-news} command cancels the article in the -current buffer. - -@vindex message-cancel-message -The value of @code{message-cancel-message} is inserted in the body of -the cancel message. The default is @samp{I am canceling my own -article.}. - -@cindex Cancel Locks -@vindex message-insert-canlock -@cindex canlock -When Message posts news messages, it inserts @code{Cancel-Lock} -headers by default. This is a cryptographic header that ensures that -only you can cancel your own messages, which is nice. The downside -is that if you lose your @file{.emacs} file (which is where Gnus -stores the secret cancel lock password (which is generated -automatically the first time you use this feature)), you won't be -able to cancel your message. If you want to manage a password yourself, -you can put something like the following in your @file{~/.gnus.el} file: - -@lisp -(setq canlock-password "geheimnis" - canlock-password-for-verify canlock-password) -@end lisp - -Whether to insert the header or not is controlled by the -@code{message-insert-canlock} variable. - -Not many news servers respect the @code{Cancel-Lock} header yet, but -this is expected to change in the future. - - -@node Superseding -@section Superseding - -@findex message-supersede -The @code{message-supersede} command pops up a message buffer that will -supersede the message in the current buffer. - -@vindex message-ignored-supersedes-headers -Headers matching the @code{message-ignored-supersedes-headers} are -removed before popping up the new message buffer. The default is@* -@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@* -^Received:\\|^X-From-Line:\\|^X-Trace:\\|^X-Complaints-To:\\|@* -Return-Path:\\|^Supersedes:\\|^NNTP-Posting-Date:\\|^X-Trace:\\|@* -^X-Complaints-To:\\|^Cancel-Lock:\\|^Cancel-Key:\\|^X-Hashcash:\\|@* -^X-Payment:\\|^Approved:}. - - - -@node Forwarding -@section Forwarding - -@findex message-forward -The @code{message-forward} command pops up a message buffer to forward -the message in the current buffer. If given a prefix, forward using -news. - -@table @code -@item message-forward-ignored-headers -@vindex message-forward-ignored-headers -All headers that match this regexp will be deleted when forwarding a message. - -@item message-make-forward-subject-function -@vindex message-make-forward-subject-function -A list of functions that are called to generate a subject header for -forwarded messages. The subject generated by the previous function is -passed into each successive function. - -The provided functions are: - -@table @code -@item message-forward-subject-author-subject -@findex message-forward-subject-author-subject -Source of article (author or newsgroup), in brackets followed by the -subject. - -@item message-forward-subject-fwd -Subject of article with @samp{Fwd:} prepended to it. -@end table - -@item message-wash-forwarded-subjects -@vindex message-wash-forwarded-subjects -If this variable is @code{t}, the subjects of forwarded messages have -the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, -@samp{(fwd)}) removed before the new subject is -constructed. The default value is @code{nil}. - -@item message-forward-as-mime -@vindex message-forward-as-mime -If this variable is @code{t} (the default), forwarded messages are -included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded -messages will just be copied inline to the new message, like previous, -non @acronym{MIME}-savvy versions of Gnus would do. - -@item message-forward-before-signature -@vindex message-forward-before-signature -If non-@code{nil}, put forwarded message before signature, else after. - -@end table - - -@node Resending -@section Resending - -@findex message-resend -The @code{message-resend} command will prompt the user for an address -and resend the message in the current buffer to that address. - -@vindex message-ignored-resent-headers -Headers that match the @code{message-ignored-resent-headers} regexp will -be removed before sending the message. - - -@node Bouncing -@section Bouncing - -@findex message-bounce -The @code{message-bounce} command will, if the current buffer contains a -bounced mail message, pop up a message buffer stripped of the bounce -information. A @dfn{bounced message} is typically a mail you've sent -out that has been returned by some @code{mailer-daemon} as -undeliverable. - -@vindex message-ignored-bounced-headers -Headers that match the @code{message-ignored-bounced-headers} regexp -will be removed before popping up the buffer. The default is -@samp{^\\(Received\\|Return-Path\\|Delivered-To\\):}. - - -@node Mailing Lists -@section Mailing Lists - -@cindex Mail-Followup-To -Sometimes while posting to mailing lists, the poster needs to direct -followups to the post to specific places. The Mail-Followup-To (MFT) -was created to enable just this. Three example scenarios where this is -useful: - -@itemize @bullet -@item -A mailing list poster can use MFT to express that responses should be -sent to just the list, and not the poster as well. This will happen -if the poster is already subscribed to the list. - -@item -A mailing list poster can use MFT to express that responses should be -sent to the list and the poster as well. This will happen if the poster -is not subscribed to the list. - -@item -If a message is posted to several mailing lists, MFT may also be used -to direct the following discussion to one list only, because -discussions that are spread over several lists tend to be fragmented -and very difficult to follow. - -@end itemize - -Gnus honors the MFT header in other's messages (i.e. while following -up to someone else's post) and also provides support for generating -sensible MFT headers for outgoing messages as well. - -@c @menu -@c * Honoring an MFT post:: What to do when one already exists -@c * Composing with a MFT header:: Creating one from scratch. -@c @end menu - -@c @node Composing with a MFT header -@subsection Composing a correct MFT header automagically - -The first step in getting Gnus to automagically generate a MFT header -in posts you make is to give Gnus a list of the mailing lists -addresses you are subscribed to. You can do this in more than one -way. The following variables would come in handy. - -@table @code - -@vindex message-subscribed-addresses -@item message-subscribed-addresses -This should be a list of addresses the user is subscribed to. Its -default value is @code{nil}. Example: -@lisp -(setq message-subscribed-addresses - '("ding@@gnus.org" "bing@@noose.org")) -@end lisp - -@vindex message-subscribed-regexps -@item message-subscribed-regexps -This should be a list of regexps denoting the addresses of mailing -lists subscribed to. Default value is @code{nil}. Example: If you -want to achieve the same result as above: -@lisp -(setq message-subscribed-regexps - '("\\(ding@@gnus\\)\\|\\(bing@@noose\\)\\.org") -@end lisp - -@vindex message-subscribed-address-functions -@item message-subscribed-address-functions -This can be a list of functions to be called (one at a time!!) to -determine the value of MFT headers. It is advisable that these -functions not take any arguments. Default value is @code{nil}. - -There is a pre-defined function in Gnus that is a good candidate for -this variable. @code{gnus-find-subscribed-addresses} is a function -that returns a list of addresses corresponding to the groups that have -the @code{subscribed} (@pxref{Group Parameters, ,Group Parameters, -gnus, The Gnus Manual}) group parameter set to a non-@code{nil} value. -This is how you would do it. - -@lisp -(setq message-subscribed-address-functions - '(gnus-find-subscribed-addresses)) -@end lisp - -@vindex message-subscribed-address-file -@item message-subscribed-address-file -You might be one organized human freak and have a list of addresses of -all subscribed mailing lists in a separate file! Then you can just -set this variable to the name of the file and life would be good. - -@end table - -You can use one or more of the above variables. All their values are -``added'' in some way that works :-) - -Now you are all set. Just start composing a message as you normally do. -And just send it; as always. Just before the message is sent out, Gnus' -MFT generation thingy kicks in and checks if the message already has a -MFT field. If there is one, it is left alone. (Except if it's empty - -in that case, the field is removed and is not replaced with an -automatically generated one. This lets you disable MFT generation on a -per-message basis.) If there is none, then the list of recipient -addresses (in the To: and Cc: headers) is checked to see if one of them -is a list address you are subscribed to. If none of them is a list -address, then no MFT is generated; otherwise, a MFT is added to the -other headers and set to the value of all addresses in To: and Cc: - -@kindex C-c C-f C-a -@findex message-generate-unsubscribed-mail-followup-to -@kindex C-c C-f C-m -@findex message-goto-mail-followup-to -Hm. ``So'', you ask, ``what if I send an email to a list I am not -subscribed to? I want my MFT to say that I want an extra copy.'' (This -is supposed to be interpreted by others the same way as if there were no -MFT, but you can use an explicit MFT to override someone else's -to-address group parameter.) The function -@code{message-generate-unsubscribed-mail-followup-to} might come in -handy. It is bound to @kbd{C-c C-f C-a} by default. In any case, you -can insert a MFT of your own choice; @kbd{C-c C-f C-m} -(@code{message-goto-mail-followup-to}) will help you get started. - -@c @node Honoring an MFT post -@subsection Honoring an MFT post - -@vindex message-use-mail-followup-to -When you followup to a post on a mailing list, and the post has a MFT -header, Gnus' action will depend on the value of the variable -@code{message-use-mail-followup-to}. This variable can be one of: - -@table @code -@item use - Always honor MFTs. The To: and Cc: headers in your followup will be - derived from the MFT header of the original post. This is the default. - -@item nil - Always dishonor MFTs (just ignore the darned thing) - -@item ask -Gnus will prompt you for an action. - -@end table - -It is considered good netiquette to honor MFT, as it is assumed the -fellow who posted a message knows where the followups need to go -better than you do. - -@node Commands -@chapter Commands - -@menu -* Buffer Entry:: Commands after entering a Message buffer. -* Header Commands:: Commands for moving headers or changing headers. -* Movement:: Moving around in message buffers. -* Insertion:: Inserting things into message buffers. -* MIME:: @acronym{MIME} considerations. -* IDNA:: Non-@acronym{ASCII} domain name considerations. -* Security:: Signing and encrypting messages. -* Various Commands:: Various things. -* Sending:: Actually sending the message. -* Mail Aliases:: How to use mail aliases. -* Spelling:: Having Emacs check your spelling. -@end menu - - -@node Buffer Entry -@section Buffer Entry -@cindex undo -@kindex C-_ - -You most often end up in a Message buffer when responding to some other -message of some sort. Message does lots of handling of quoted text, and -may remove signatures, reformat the text, or the like---depending on -which used settings you're using. Message usually gets things right, -but sometimes it stumbles. To help the user unwind these stumblings, -Message sets the undo boundary before each major automatic action it -takes. If you press the undo key (usually located at @kbd{C-_}) a few -times, you will get back the un-edited message you're responding to. - - -@node Header Commands -@section Header Commands - -@subsection Commands for moving to headers - -These following commands move to the header in question. If it doesn't -exist, it will be inserted. - -@table @kbd - -@item C-c ? -@kindex C-c ? -@findex describe-mode -Describe the message mode. - -@item C-c C-f C-t -@kindex C-c C-f C-t -@findex message-goto-to -Go to the @code{To} header (@code{message-goto-to}). - -@item C-c C-f C-o -@kindex C-c C-f C-o -@findex message-goto-from -Go to the @code{From} header (@code{message-goto-from}). (The ``o'' -in the key binding is for Originator.) - -@item C-c C-f C-b -@kindex C-c C-f C-b -@findex message-goto-bcc -Go to the @code{Bcc} header (@code{message-goto-bcc}). - -@item C-c C-f C-w -@kindex C-c C-f C-w -@findex message-goto-fcc -Go to the @code{Fcc} header (@code{message-goto-fcc}). - -@item C-c C-f C-c -@kindex C-c C-f C-c -@findex message-goto-cc -Go to the @code{Cc} header (@code{message-goto-cc}). - -@item C-c C-f C-s -@kindex C-c C-f C-s -@findex message-goto-subject -Go to the @code{Subject} header (@code{message-goto-subject}). - -@item C-c C-f C-r -@kindex C-c C-f C-r -@findex message-goto-reply-to -Go to the @code{Reply-To} header (@code{message-goto-reply-to}). - -@item C-c C-f C-n -@kindex C-c C-f C-n -@findex message-goto-newsgroups -Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}). - -@item C-c C-f C-d -@kindex C-c C-f C-d -@findex message-goto-distribution -Go to the @code{Distribution} header (@code{message-goto-distribution}). - -@item C-c C-f C-f -@kindex C-c C-f C-f -@findex message-goto-followup-to -Go to the @code{Followup-To} header (@code{message-goto-followup-to}). - -@item C-c C-f C-k -@kindex C-c C-f C-k -@findex message-goto-keywords -Go to the @code{Keywords} header (@code{message-goto-keywords}). - -@item C-c C-f C-u -@kindex C-c C-f C-u -@findex message-goto-summary -Go to the @code{Summary} header (@code{message-goto-summary}). - -@item C-c C-f C-i -@kindex C-c C-f C-i -@findex message-insert-or-toggle-importance -This inserts the @samp{Importance:} header with a value of -@samp{high}. This header is used to signal the importance of the -message to the receiver. If the header is already present in the -buffer, it cycles between the three valid values according to RFC -1376: @samp{low}, @samp{normal} and @samp{high}. - -@item C-c C-f C-a -@kindex C-c C-f C-a -@findex message-generate-unsubscribed-mail-followup-to -Insert a reasonable @samp{Mail-Followup-To:} header -(@pxref{Mailing Lists}) in a post to an -unsubscribed list. When making original posts to a mailing list you are -not subscribed to, you have to type in a @samp{Mail-Followup-To:} header -by hand. The contents, usually, are the addresses of the list and your -own address. This function inserts such a header automatically. It -fetches the contents of the @samp{To:} header in the current mail -buffer, and appends the current @code{user-mail-address}. - -If the optional argument @code{include-cc} is non-@code{nil}, the -addresses in the @samp{Cc:} header are also put into the -@samp{Mail-Followup-To:} header. - -@end table - -@subsection Commands to change headers - -@table @kbd - -@item C-c C-o -@kindex C-c C-o -@findex message-sort-headers -@vindex message-header-format-alist -Sort headers according to @code{message-header-format-alist} -(@code{message-sort-headers}). - -@item C-c C-t -@kindex C-c C-t -@findex message-insert-to -Insert a @code{To} header that contains the @code{Reply-To} or -@code{From} header of the message you're following up -(@code{message-insert-to}). - -@item C-c C-n -@kindex C-c C-n -@findex message-insert-newsgroups -Insert a @code{Newsgroups} header that reflects the @code{Followup-To} -or @code{Newsgroups} header of the article you're replying to -(@code{message-insert-newsgroups}). - -@item C-c C-l -@kindex C-c C-l -@findex message-to-list-only -Send a message to the list only. Remove all addresses but the list -address from @code{To:} and @code{Cc:} headers. - -@item C-c M-n -@kindex C-c M-n -@findex message-insert-disposition-notification-to -Insert a request for a disposition -notification. (@code{message-insert-disposition-notification-to}). -This means that if the recipient support RFC 2298 she might send you a -notification that she received the message. - -@item M-x message-insert-importance-high -@kindex M-x message-insert-importance-high -@findex message-insert-importance-high -@cindex Importance -Insert an @samp{Importance} header with a value of @samp{high}, -deleting headers if necessary. - -@item M-x message-insert-importance-low -@kindex M-x message-insert-importance-low -@findex message-insert-importance-low -@cindex Importance -Insert an @samp{Importance} header with a value of @samp{low}, deleting -headers if necessary. - -@item C-c C-f s -@kindex C-c C-f s -@findex message-change-subject -@cindex Subject -Change the current @samp{Subject} header. Ask for new @samp{Subject} -header and append @samp{(was: )}. The old subject can be -stripped on replying, see @code{message-subject-trailing-was-query} -(@pxref{Message Headers}). - -@item C-c C-f x -@kindex C-c C-f x -@findex message-cross-post-followup-to -@vindex message-cross-post-default -@vindex message-cross-post-note-function -@cindex X-Post -@cindex cross-post -Set up the @samp{FollowUp-To} header with a target newsgroup for a -cross-post, add that target newsgroup to the @samp{Newsgroups} header if -it is not a member of @samp{Newsgroups}, and insert a note in the body. -If @code{message-cross-post-default} is @code{nil} or if this command is -called with a prefix-argument, only the @samp{FollowUp-To} header will -be set but the target newsgroup will not be added to the -@samp{Newsgroups} header. The function to insert a note is controlled -by the @code{message-cross-post-note-function} variable. - -@item C-c C-f t -@kindex C-c C-f t -@findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} or -@samp{Bcc} header. (Iff @samp{Cc} header is not present, @samp{Bcc} -header will be used instead.) - -@item C-c C-f w -@kindex C-c C-f w -@findex message-insert-wide-reply -Insert @samp{To} and @samp{Cc} headers as if you were doing a wide -reply even if the message was not made for a wide reply first. - -@item C-c C-f a -@kindex C-c C-f a -@findex message-add-archive-header -@vindex message-archive-header -@vindex message-archive-note -@cindex X-No-Archive -Insert @samp{X-No-Archive: Yes} in the header and a note in the body. -The header and the note can be customized using -@code{message-archive-header} and @code{message-archive-note}. When -called with a prefix argument, ask for a text to insert. If you don't -want the note in the body, set @code{message-archive-note} to -@code{nil}. - -@end table - - -@node Movement -@section Movement - -@table @kbd -@item C-c C-b -@kindex C-c C-b -@findex message-goto-body -Move to the beginning of the body of the message -(@code{message-goto-body}). - -@item C-c C-i -@kindex C-c C-i -@findex message-goto-signature -Move to the signature of the message (@code{message-goto-signature}). - -@item C-a -@kindex C-a -@findex message-beginning-of-line -@vindex message-beginning-of-line -If at beginning of header value, go to beginning of line, else go to -beginning of header value. (The header value comes after the header -name and the colon.) This behavior can be disabled by toggling -the variable @code{message-beginning-of-line}. - -@end table - - -@node Insertion -@section Insertion - -@table @kbd - -@item C-c C-y -@kindex C-c C-y -@findex message-yank-original -Yank the message that's being replied to into the message buffer -(@code{message-yank-original}). - -@item C-c C-M-y -@kindex C-c C-M-y -@findex message-yank-buffer -Prompt for a buffer name and yank the contents of that buffer into the -message buffer (@code{message-yank-buffer}). - -@item C-c C-q -@kindex C-c C-q -@findex message-fill-yanked-message -Fill the yanked message (@code{message-fill-yanked-message}). Warning: -Can severely mess up the yanked text if its quoting conventions are -strange. You'll quickly get a feel for when it's safe, though. Anyway, -just remember that @kbd{C-x u} (@code{undo}) is available and you'll be -all right. - -@item C-c C-w -@kindex C-c C-w -@findex message-insert-signature -Insert a signature at the end of the buffer -(@code{message-insert-signature}). - -@item C-c M-h -@kindex C-c M-h -@findex message-insert-headers -Insert the message headers (@code{message-insert-headers}). - -@item C-c M-m -@kindex C-c M-m -@findex message-mark-inserted-region -Mark some region in the current article with enclosing tags. See -@code{message-mark-insert-begin} and @code{message-mark-insert-end}. -When called with a prefix argument, use slrn style verbatim marks -(@samp{#v+} and @samp{#v-}). - -@item C-c M-f -@kindex C-c M-f -@findex message-mark-insert-file -Insert a file in the current article with enclosing tags. -See @code{message-mark-insert-begin} and @code{message-mark-insert-end}. -When called with a prefix argument, use slrn style verbatim marks -(@samp{#v+} and @samp{#v-}). - -@end table - - -@node MIME -@section MIME -@cindex MML -@cindex MIME -@cindex multipart -@cindex attachment - -Message is a @acronym{MIME}-compliant posting agent. The user generally -doesn't have to do anything to make the @acronym{MIME} happen---Message will -automatically add the @code{Content-Type} and -@code{Content-Transfer-Encoding} headers. - -@findex mml-attach-file -@kindex C-c C-a -The most typical thing users want to use the multipart things in -@acronym{MIME} for is to add ``attachments'' to mail they send out. -This can be done with the @kbd{C-c C-a} command (@kbd{M-x mml-attach-file}), -which will prompt for a file name and a @acronym{MIME} type. - -@vindex mml-dnd-protocol-alist -@vindex mml-dnd-attach-options -If your Emacs supports drag and drop, you can also drop the file in the -Message buffer. The variable @code{mml-dnd-protocol-alist} specifies -what kind of action is done when you drop a file into the Message -buffer. The variable @code{mml-dnd-attach-options} controls which -@acronym{MIME} options you want to specify when dropping a file. If it -is a list, valid members are @code{type}, @code{description} and -@code{disposition}. @code{disposition} implies @code{type}. If it is -@code{nil}, don't ask for options. If it is @code{t}, ask the user -whether or not to specify options. - -You can also create arbitrarily complex multiparts using the @acronym{MML} -language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME -Manual}). - -@node IDNA -@section IDNA -@cindex IDNA -@cindex internationalized domain names -@cindex non-ascii domain names - -Message is a @acronym{IDNA}-compliant posting agent. The user -generally doesn't have to do anything to make the @acronym{IDNA} -happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, -@code{To}, and @code{Cc} headers automatically. - -Until @acronym{IDNA} becomes more well known, Message queries you -whether @acronym{IDNA} encoding of the domain name really should -occur. Some users might not be aware that domain names can contain -non-@acronym{ASCII} now, so this gives them a safety net if they accidently -typed a non-@acronym{ASCII} domain name. - -@vindex message-use-idna -The @code{message-use-idna} variable control whether @acronym{IDNA} is -used. If the variable is @code{nil} no @acronym{IDNA} encoding will -ever happen, if it is set to the symbol @code{ask} the user will be -queried, and if set to @code{t} (which is the default if @acronym{IDNA} -is fully available) @acronym{IDNA} encoding happens automatically. - -@findex message-idna-to-ascii-rhs -If you want to experiment with the @acronym{IDNA} encoding, you can -invoke @kbd{M-x message-idna-to-ascii-rhs RET} in the message buffer -to have the non-@acronym{ASCII} domain names encoded while you edit -the message. - -Note that you must have @uref{http://www.gnu.org/software/libidn/, GNU -Libidn} installed in order to use this functionality. - -@node Security -@section Security -@cindex Security -@cindex S/MIME -@cindex PGP -@cindex PGP/MIME -@cindex sign -@cindex encrypt -@cindex secure - -Using the @acronym{MML} language, Message is able to create digitally -signed and digitally encrypted messages. Message (or rather -@acronym{MML}) currently support @acronym{PGP} (RFC 1991), -@acronym{PGP/MIME} (RFC 2015/3156) and @acronym{S/MIME}. - -@menu -* Signing and encryption:: Signing and encrypting commands. -* Using S/MIME:: Using S/MIME -* Using PGP/MIME:: Using PGP/MIME -* PGP Compatibility:: Compatibility with older implementations -@end menu - -@node Signing and encryption -@subsection Signing and encrypting commands - -Instructing @acronym{MML} to perform security operations on a -@acronym{MIME} part is done using the @kbd{C-c C-m s} key map for -signing and the @kbd{C-c C-m c} key map for encryption, as follows. -@table @kbd - -@item C-c C-m s s -@kindex C-c C-m s s -@findex mml-secure-message-sign-smime - -Digitally sign current message using @acronym{S/MIME}. - -@item C-c C-m s o -@kindex C-c C-m s o -@findex mml-secure-message-sign-pgp - -Digitally sign current message using @acronym{PGP}. - -@item C-c C-m s p -@kindex C-c C-m s p -@findex mml-secure-message-sign-pgpmime - -Digitally sign current message using @acronym{PGP/MIME}. - -@item C-c C-m c s -@kindex C-c C-m c s -@findex mml-secure-message-encrypt-smime - -Digitally encrypt current message using @acronym{S/MIME}. - -@item C-c C-m c o -@kindex C-c C-m c o -@findex mml-secure-message-encrypt-pgp - -Digitally encrypt current message using @acronym{PGP}. - -@item C-c C-m c p -@kindex C-c C-m c p -@findex mml-secure-message-encrypt-pgpmime - -Digitally encrypt current message using @acronym{PGP/MIME}. - -@item C-c C-m C-n -@kindex C-c C-m C-n -@findex mml-unsecure-message -Remove security related @acronym{MML} tags from message. - -@end table - -These commands do not immediately sign or encrypt the message, they -merely insert the proper @acronym{MML} secure tag to instruct the -@acronym{MML} engine to perform that operation when the message is -actually sent. They may perform other operations too, such as locating -and retrieving a @acronym{S/MIME} certificate of the person you wish to -send encrypted mail to. When the mml parsing engine converts your -@acronym{MML} into a properly encoded @acronym{MIME} message, the secure -tag will be replaced with either a part or a multipart tag. If your -message contains other mml parts, a multipart tag will be used; if no -other parts are present in your message a single part tag will be used. -This way, message mode will do the Right Thing (TM) with -signed/encrypted multipart messages. - -Since signing and especially encryption often is used when sensitive -information is sent, you may want to have some way to ensure that your -mail is actually signed or encrypted. After invoking the above -sign/encrypt commands, it is possible to preview the raw article by -using @kbd{C-u C-c RET P} (@code{mml-preview}). Then you can -verify that your long rant about what your ex-significant other or -whomever actually did with that funny looking person at that strange -party the other night, actually will be sent encrypted. - -@emph{Note!} Neither @acronym{PGP/MIME} nor @acronym{S/MIME} encrypt/signs -RFC822 headers. They only operate on the @acronym{MIME} object. Keep this -in mind before sending mail with a sensitive Subject line. - -By default, when encrypting a message, Gnus will use the -``signencrypt'' mode, which means the message is both signed and -encrypted. If you would like to disable this for a particular -message, give the @code{mml-secure-message-encrypt-*} command a prefix -argument, e.g., @kbd{C-u C-c C-m c p}. - -Actually using the security commands above is not very difficult. At -least not compared with making sure all involved programs talk with each -other properly. Thus, we now describe what external libraries or -programs are required to make things work, and some small general hints. - -@node Using S/MIME -@subsection Using S/MIME - -@emph{Note!} This section assume you have a basic familiarity with -modern cryptography, @acronym{S/MIME}, various PKCS standards, OpenSSL and -so on. - -The @acronym{S/MIME} support in Message (and @acronym{MML}) require -OpenSSL. OpenSSL performs the actual @acronym{S/MIME} sign/encrypt -operations. OpenSSL can be found at @uref{http://www.openssl.org/}. -OpenSSL 0.9.6 and later should work. Version 0.9.5a cannot extract mail -addresses from certificates, and it insert a spurious CR character into -@acronym{MIME} separators so you may wish to avoid it if you would like -to avoid being regarded as someone who send strange mail. (Although by -sending @acronym{S/MIME} messages you've probably already lost that -contest.) - -To be able to send encrypted mail, a personal certificate is not -required. Message (@acronym{MML}) need a certificate for the person to whom you -wish to communicate with though. You're asked for this when you type -@kbd{C-c C-m c s}. Currently there are two ways to retrieve this -certificate, from a local file or from DNS. If you chose a local -file, it need to contain a X.509 certificate in @acronym{PEM} format. -If you chose DNS, you're asked for the domain name where the -certificate is stored, the default is a good guess. To my belief, -Message (@acronym{MML}) is the first mail agent in the world to support -retrieving @acronym{S/MIME} certificates from DNS, so you're not -likely to find very many certificates out there. At least there -should be one, stored at the domain @code{simon.josefsson.org}. LDAP -is a more popular method of distributing certificates, support for it -is planned. (Meanwhile, you can use @code{ldapsearch} from the -command line to retrieve a certificate into a file and use it.) - -As for signing messages, OpenSSL can't perform signing operations -without some kind of configuration. Especially, you need to tell it -where your private key and your certificate is stored. @acronym{MML} -uses an Emacs interface to OpenSSL, aptly named @code{smime.el}, and it -contain a @code{custom} group used for this configuration. So, try -@kbd{M-x customize-group RET smime RET} and look around. - -Currently there is no support for talking to a CA (or RA) to create -your own certificate. None is planned either. You need to do this -manually with OpenSSL or using some other program. I used Netscape -and got a free @acronym{S/MIME} certificate from one of the big CA's on the -net. Netscape is able to export your private key and certificate in -PKCS #12 format. Use OpenSSL to convert this into a plain X.509 -certificate in PEM format as follows. - -@example -$ openssl pkcs12 -in ns.p12 -clcerts -nodes > key+cert.pem -@end example - -The @file{key+cert.pem} file should be pointed to from the -@code{smime-keys} variable. You should now be able to send signed mail. - -@emph{Note!} Your private key is now stored unencrypted in the file, -so take care in handling it. Storing encrypted keys on the disk are -supported, and Gnus will ask you for a passphrase before invoking -OpenSSL. Read the OpenSSL documentation for how to achieve this. If -you use unencrypted keys (e.g., if they are on a secure storage, or if -you are on a secure single user machine) simply press @code{RET} at -the passphrase prompt. - -@node Using PGP/MIME -@subsection Using PGP/MIME - -@acronym{PGP/MIME} requires an external OpenPGP implementation, such -as @uref{http://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP -implementations such as PGP 2.x and PGP 5.x are also supported. One -Emacs interface to the PGP implementations, PGG (@pxref{Top, ,PGG, -pgg, PGG Manual}), is included, but Mailcrypt and Florian Weimer's -@code{gpg.el} are also supported. @xref{PGP Compatibility}. - -@cindex gpg-agent -Message internally calls GnuPG (the @command{gpg} command) to perform -data encryption, and in certain cases (decrypting or signing for -example), @command{gpg} requires user's passphrase. Currently the -recommended way to supply your passphrase to @command{gpg} is to use the -@command{gpg-agent} program. - -To use @command{gpg-agent} in Emacs, you need to run the following -command from the shell before starting Emacs. - -@example -eval `gpg-agent --daemon` -@end example - -This will invoke @command{gpg-agent} and set the environment variable -@code{GPG_AGENT_INFO} to allow @command{gpg} to communicate with it. -It might be good idea to put this command in your @file{.xsession} or -@file{.bash_profile}. @xref{Invoking GPG-AGENT, , , gnupg, Using the -GNU Privacy Guard}. - -Once your @command{gpg-agent} is set up, it will ask you for a -passphrase as needed for @command{gpg}. Under the X Window System, -you will see a new passphrase input dialog appear. The dialog is -provided by PIN Entry (the @command{pinentry} command), and as of -version 0.7.2, @command{pinentry} cannot cooperate with Emacs on a -single tty. So, if you are using a text console, you may need to put -a passphrase into gpg-agent's cache beforehand. The following command -does the trick. - -@example -gpg --use-agent --sign < /dev/null > /dev/null -@end example - -The Lisp variable @code{pgg-gpg-use-agent} controls whether to use -@command{gpg-agent}. See also @xref{Caching passphrase, , , pgg, The -PGG Manual}. - - -@node PGP Compatibility -@subsection Compatibility with older implementations - -@vindex gpg-temp-directory -Note, if you are using the @code{gpg.el} you must make sure that the -directory specified by @code{gpg-temp-directory} have permissions -0700. - -Creating your own key is described in detail in the documentation of -your PGP implementation, so we refer to it. - -If you have imported your old PGP 2.x key into GnuPG, and want to send -signed and encrypted messages to your fellow PGP 2.x users, you'll -discover that the receiver cannot understand what you send. One -solution is to use PGP 2.x instead (i.e., if you use @code{pgg}, set -@code{pgg-default-scheme} to @code{pgp}). If you do want to use -GnuPG, you can use a compatibility script called @code{gpg-2comp} -available from -@uref{http://muppet.faveve.uni-stuttgart.de/~gero/gpg-2comp/}. You -could also convince your fellow PGP 2.x users to convert to GnuPG. -@vindex mml-signencrypt-style-alist -As a final workaround, you can make the sign and encryption work in -two steps; separately sign, then encrypt a message. If you would like -to change this behavior you can customize the -@code{mml-signencrypt-style-alist} variable. For example: - -@lisp -(setq mml-signencrypt-style-alist '(("smime" separate) - ("pgp" separate) - ("pgpauto" separate) - ("pgpmime" separate))) -@end lisp - -This causes to sign and encrypt in two passes, thus generating a -message that can be understood by PGP version 2. - -(Refer to @uref{http://www.gnupg.org/gph/en/pgp2x.html} for more -information about the problem.) - -@node Various Commands -@section Various Commands - -@table @kbd - -@item C-c C-r -@kindex C-c C-r -@findex message-caesar-buffer-body -Caesar rotate (aka. rot13) the current message -(@code{message-caesar-buffer-body}). If narrowing is in effect, just -rotate the visible portion of the buffer. A numerical prefix says how -many places to rotate the text. The default is 13. - -@item C-c C-e -@kindex C-c C-e -@findex message-elide-region -@vindex message-elide-ellipsis -Elide the text between point and mark (@code{message-elide-region}). -The text is killed and replaced with the contents of the variable -@code{message-elide-ellipsis}. The default value is to use an ellipsis -(@samp{[...]}). - -@item C-c M-k -@kindex C-c M-k -@findex message-kill-address -Kill the address under point. - -@item C-c C-z -@kindex C-c C-z -@findex message-kill-to-signature -Kill all the text up to the signature, or if that's missing, up to the -end of the message (@code{message-kill-to-signature}). - -@item C-c C-v -@kindex C-c C-v -@findex message-delete-not-region -Delete all text in the body of the message that is outside the region -(@code{message-delete-not-region}). - -@item M-RET -@kindex M-RET -@findex message-newline-and-reformat -Insert four newlines, and then reformat if inside quoted text. - -Here's an example: - -@example -> This is some quoted text. And here's more quoted text. -@end example - -If point is before @samp{And} and you press @kbd{M-RET}, you'll get: - -@example -> This is some quoted text. - -* - -> And here's more quoted text. -@end example - -@samp{*} says where point will be placed. - -@item C-c M-r -@kindex C-c M-r -@findex message-rename-buffer -Rename the buffer (@code{message-rename-buffer}). If given a prefix, -prompt for a new buffer name. - -@item TAB -@kindex TAB -@findex message-tab -@vindex message-tab-body-function -If @code{message-tab-body-function} is non-@code{nil}, execute the -function it specifies. Otherwise use the function bound to @kbd{TAB} in -@code{text-mode-map} or @code{global-map}. - -@end table - - -@node Sending -@section Sending - -@table @kbd -@item C-c C-c -@kindex C-c C-c -@findex message-send-and-exit -Send the message and bury the current buffer -(@code{message-send-and-exit}). - -@item C-c C-s -@kindex C-c C-s -@findex message-send -Send the message (@code{message-send}). - -@item C-c C-d -@kindex C-c C-d -@findex message-dont-send -Bury the message buffer and exit (@code{message-dont-send}). - -@item C-c C-k -@kindex C-c C-k -@findex message-kill-buffer -Kill the message buffer and exit (@code{message-kill-buffer}). - -@end table - - - -@node Mail Aliases -@section Mail Aliases -@cindex mail aliases -@cindex aliases -@cindex completion -@cindex ecomplete - -@vindex message-mail-alias-type -The @code{message-mail-alias-type} variable controls what type of mail -alias expansion to use. Currently two forms are supported: -@code{mailabbrev} and @code{ecomplete}. If this variable is -@code{nil}, no mail alias expansion will be performed. - -@code{mailabbrev} works by parsing the @file{/etc/mailrc} and -@file{~/.mailrc} files. These files look like: - -@example -alias lmi "Lars Magne Ingebrigtsen " -alias ding "ding@@ifi.uio.no (ding mailing list)" -@end example - -After adding lines like this to your @file{~/.mailrc} file, you should -be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so -on) headers and press @kbd{SPC} to expand the alias. - -No expansion will be performed upon sending of the message---all -expansions have to be done explicitly. - -If you're using @code{ecomplete}, all addresses from @code{To} and -@code{Cc} headers will automatically be put into the -@file{~/.ecompleterc} file. When you enter text in the @code{To} and -@code{Cc} headers, @code{ecomplete} will check out the values stored -there and ``electrically'' say what completions are possible. To -choose one of these completions, use the @kbd{M-n} command to move -down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the -list, and @kbd{RET} to choose a completion. - -@node Spelling -@section Spelling -@cindex spelling -@findex ispell-message - -There are two popular ways to have Emacs spell-check your messages: -@code{ispell} and @code{flyspell}. @code{ispell} is the older and -probably more popular package. You typically first write the message, -and then run the entire thing through @code{ispell} and fix all the -typos. To have this happen automatically when you send a message, put -something like the following in your @file{.emacs} file: - -@lisp -(add-hook 'message-send-hook 'ispell-message) -@end lisp - -@vindex ispell-message-dictionary-alist -If you're in the habit of writing in different languages, this can be -controlled by the @code{ispell-message-dictionary-alist} variable: - -@lisp -(setq ispell-message-dictionary-alist - '(("^Newsgroups:.*\\bde\\." . "deutsch8") - (".*" . "default"))) -@end lisp - -@code{ispell} depends on having the external @samp{ispell} command -installed. - -The other popular method is using @code{flyspell}. This package checks -your spelling while you're writing, and marks any mis-spelled words in -various ways. - -To use @code{flyspell}, put something like the following in your -@file{.emacs} file: - -@lisp -(defun my-message-setup-routine () - (flyspell-mode 1)) -(add-hook 'message-setup-hook 'my-message-setup-routine) -@end lisp - -@code{flyspell} depends on having the external @samp{ispell} command -installed. - - -@node Variables -@chapter Variables - -@menu -* Message Headers:: General message header stuff. -* Mail Headers:: Customizing mail headers. -* Mail Variables:: Other mail variables. -* News Headers:: Customizing news headers. -* News Variables:: Other news variables. -* Insertion Variables:: Customizing how things are inserted. -* Various Message Variables:: Other message variables. -* Sending Variables:: Variables for sending. -* Message Buffers:: How Message names its buffers. -* Message Actions:: Actions to be performed when exiting. -@end menu - - -@node Message Headers -@section Message Headers - -Message is quite aggressive on the message generation front. It has to -be---it's a combined news and mail agent. To be able to send combined -messages, it has to generate all headers itself (instead of letting the -mail/news system do it) to ensure that mail and news copies of messages -look sufficiently similar. - -@table @code - -@item message-generate-headers-first -@vindex message-generate-headers-first -If @code{t}, generate all required headers before starting to -compose the message. This can also be a list of headers to generate: - -@lisp -(setq message-generate-headers-first - '(References)) -@end lisp - -@vindex message-required-headers -The variables @code{message-required-headers}, -@code{message-required-mail-headers} and -@code{message-required-news-headers} specify which headers are -required. - -Note that some headers will be removed and re-generated before posting, -because of the variable @code{message-deletable-headers} (see below). - -@item message-draft-headers -@vindex message-draft-headers -When running Message from Gnus, the message buffers are associated -with a draft group. @code{message-draft-headers} says which headers -should be generated when a draft is written to the draft group. - -@item message-from-style -@vindex message-from-style -Specifies how @code{From} headers should look. There are four valid -values: - -@table @code -@item nil -Just the address---@samp{king@@grassland.com}. - -@item parens -@samp{king@@grassland.com (Elvis Parsley)}. - -@item angles -@samp{Elvis Parsley }. - -@item default -Look like @code{angles} if that doesn't require quoting, and -@code{parens} if it does. If even @code{parens} requires quoting, use -@code{angles} anyway. - -@end table - -@item message-deletable-headers -@vindex message-deletable-headers -Headers in this list that were previously generated by Message will be -deleted before posting. Let's say you post an article. Then you decide -to post it again to some other group, you naughty boy, so you jump back -to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and -ship it off again. By default, this variable makes sure that the old -generated @code{Message-ID} is deleted, and a new one generated. If -this isn't done, the entire empire would probably crumble, anarchy would -prevail, and cats would start walking on two legs and rule the world. -Allegedly. - -@item message-default-headers -@vindex message-default-headers -This string is inserted at the end of the headers in all message -buffers. - -@item message-subject-re-regexp -@vindex message-subject-re-regexp -@cindex Aw -@cindex Sv -@cindex Re -Responses to messages have subjects that start with @samp{Re: }. This -is @emph{not} an abbreviation of the English word ``response'', but is -Latin, and means ``in response to''. Some illiterate nincompoops have -failed to grasp this fact, and have ``internationalized'' their software -to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: } -(``svar'') instead, which is meaningless and evil. However, you may -have to deal with users that use these evil tools, in which case you may -set this variable to a regexp that matches these prefixes. Myself, I -just throw away non-compliant mail. - -Here's an example of a value to deal with these headers when -responding to a message: - -@lisp -(setq message-subject-re-regexp - (concat - "^[ \t]*" - "\\(" - "\\(" - "[Aa][Nn][Tt][Ww]\\.?\\|" ; antw - "[Aa][Ww]\\|" ; aw - "[Ff][Ww][Dd]?\\|" ; fwd - "[Oo][Dd][Pp]\\|" ; odp - "[Rr][Ee]\\|" ; re - "[Rr][\311\351][Ff]\\.?\\|" ; ref - "[Ss][Vv]" ; sv - "\\)" - "\\(\\[[0-9]*\\]\\)" - "*:[ \t]*" - "\\)" - "*[ \t]*" - )) -@end lisp - -@item message-subject-trailing-was-query -@vindex message-subject-trailing-was-query -@vindex message-subject-trailing-was-ask-regexp -@vindex message-subject-trailing-was-regexp -Controls what to do with trailing @samp{(was: )} in subject -lines. If @code{nil}, leave the subject unchanged. If it is the symbol -@code{ask}, query the user what to do. In this case, the subject is -matched against @code{message-subject-trailing-was-ask-regexp}. If -@code{message-subject-trailing-was-query} is @code{t}, always strip the -trailing old subject. In this case, -@code{message-subject-trailing-was-regexp} is used. - -@item message-alternative-emails -@vindex message-alternative-emails -Regexp matching alternative email addresses. The first address in the -To, Cc or From headers of the original article matching this variable is -used as the From field of outgoing messages, replacing the default From -value. - -For example, if you have two secondary email addresses john@@home.net -and john.doe@@work.com and want to use them in the From field when -composing a reply to a message addressed to one of them, you could set -this variable like this: - -@lisp -(setq message-alternative-emails - (regexp-opt '("john@@home.net" "john.doe@@work.com"))) -@end lisp - -This variable has precedence over posting styles and anything that runs -off @code{message-setup-hook}. - -@item message-allow-no-recipients -@vindex message-allow-no-recipients -Specifies what to do when there are no recipients other than -@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is -allowed. If it is @code{never}, the posting is not allowed. If it is -@code{ask} (the default), you are prompted. - -@item message-hidden-headers -@vindex message-hidden-headers -A regexp, a list of regexps, or a list where the first element is -@code{not} and the rest are regexps. It says which headers to keep -hidden when composing a message. - -@lisp -(setq message-hidden-headers - '(not "From" "Subject" "To" "Cc" "Newsgroups")) -@end lisp - -Headers are hidden using narrowing, you can use @kbd{M-x widen} to -expose them in the buffer. - -@item message-header-synonyms -@vindex message-header-synonyms -A list of lists of header synonyms. E.g., if this list contains a -member list with elements @code{Cc} and @code{To}, then -@code{message-carefully-insert-headers} will not insert a @code{To} -header when the message is already @code{Cc}ed to the recipient. - -@end table - - -@node Mail Headers -@section Mail Headers - -@table @code -@item message-required-mail-headers -@vindex message-required-mail-headers -@xref{News Headers}, for the syntax of this variable. It is -@code{(From Subject Date (optional . In-Reply-To) Message-ID -(optional . User-Agent))} by default. - -@item message-ignored-mail-headers -@vindex message-ignored-mail-headers -Regexp of headers to be removed before mailing. The default is@* -@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* -^X-Gnus-Agent-Meta-Information:}. - -@item message-default-mail-headers -@vindex message-default-mail-headers -This string is inserted at the end of the headers in all message -buffers that are initialized as mail. - -@item message-generate-hashcash -@vindex message-generate-hashcash -Variable that indicates whether @samp{X-Hashcash} headers -should be computed for the message. @xref{Hashcash, ,Hashcash,gnus, -The Gnus Manual}. If @code{opportunistic}, only generate the headers -when it doesn't lead to the user having to wait. - -@end table - - -@node Mail Variables -@section Mail Variables - -@table @code -@item message-send-mail-function -@vindex message-send-mail-function -@findex message-send-mail-function -@findex message-send-mail-with-sendmail -@findex message-send-mail-with-mh -@findex message-send-mail-with-qmail -@findex message-smtpmail-send-it -@findex smtpmail-send-it -@findex feedmail-send-it -@findex message-send-mail-with-mailclient -Function used to send the current buffer as mail. The default is -@code{message-send-mail-with-sendmail}, or @code{smtpmail-send-it} -according to the system. Other valid values include -@code{message-send-mail-with-mailclient}, -@code{message-send-mail-with-mh}, @code{message-send-mail-with-qmail}, -@code{message-smtpmail-send-it} and @code{feedmail-send-it}. - -The function -@code{message-send-mail-with-sendmail} pipes your article to the -@code{sendmail} binary for further queuing and sending. When your local -system is not configured for sending mail using @code{sendmail}, and you -have access to a remote @acronym{SMTP} server, you can set -@code{message-send-mail-function} to @code{smtpmail-send-it} and make -sure to setup the @code{smtpmail} package correctly. An example: - -@lisp -(setq message-send-mail-function 'smtpmail-send-it - smtpmail-default-smtp-server "YOUR SMTP HOST") -@end lisp - -To the thing similar to this, there is -@code{message-smtpmail-send-it}. It is useful if your @acronym{ISP} -requires the @acronym{POP}-before-@acronym{SMTP} authentication. -@xref{POP before SMTP, , POP before SMTP, gnus, The Gnus Manual}. - -@item message-mh-deletable-headers -@vindex message-mh-deletable-headers -Most versions of MH doesn't like being fed messages that contain the -headers in this variable. If this variable is non-@code{nil} (which is -the default), these headers will be removed before mailing when sending -messages via MH. Set it to @code{nil} if your MH can handle these -headers. - -@item message-qmail-inject-program -@vindex message-qmail-inject-program -@cindex qmail -Location of the qmail-inject program. - -@item message-qmail-inject-args -@vindex message-qmail-inject-args -Arguments passed to qmail-inject programs. -This should be a list of strings, one string for each argument. It -may also be a function. - -For e.g., if you wish to set the envelope sender address so that bounces -go to the right place or to deal with listserv's usage of that address, you -might set this variable to @code{'("-f" "you@@some.where")}. - -@item message-sendmail-f-is-evil -@vindex message-sendmail-f-is-evil -@cindex sendmail -Non-@code{nil} means don't add @samp{-f username} to the sendmail -command line. Doing so would be even more evil than leaving it out. - -@item message-sendmail-envelope-from -@vindex message-sendmail-envelope-from -When @code{message-sendmail-f-is-evil} is @code{nil}, this specifies -the address to use in the @acronym{SMTP} envelope. If it is -@code{nil}, use @code{user-mail-address}. If it is the symbol -@code{header}, use the @samp{From} header of the message. - -@item message-mailer-swallows-blank-line -@vindex message-mailer-swallows-blank-line -Set this to non-@code{nil} if the system's mailer runs the header and -body together. (This problem exists on SunOS 4 when sendmail is run -in remote mode.) The value should be an expression to test whether -the problem will actually occur. - -@item message-send-mail-partially-limit -@vindex message-send-mail-partially-limit -@cindex split large message -The limitation of messages sent as message/partial. The lower bound -of message size in characters, beyond which the message should be sent -in several parts. If it is @code{nil}, the size is unlimited. - -@end table - - -@node News Headers -@section News Headers - -@vindex message-required-news-headers -@code{message-required-news-headers} a list of header symbols. These -headers will either be automatically generated, or, if that's -impossible, they will be prompted for. The following symbols are valid: - -@table @code - -@item From -@cindex From -@findex user-full-name -@findex user-mail-address -This required header will be filled out with the result of the -@code{message-make-from} function, which depends on the -@code{message-from-style}, @code{user-full-name}, -@code{user-mail-address} variables. - -@item Subject -@cindex Subject -This required header will be prompted for if not present already. - -@item Newsgroups -@cindex Newsgroups -This required header says which newsgroups the article is to be posted -to. If it isn't present already, it will be prompted for. - -@item Organization -@cindex organization -@vindex message-user-organization -@vindex message-user-organization-file -This optional header will be filled out depending on the -@code{message-user-organization} variable. -@code{message-user-organization-file} will be used if this variable is -@code{t}. This variable can also be a string (in which case this string -will be used), or it can be a function (which will be called with no -parameters and should return a string to be used). - -@item Lines -@cindex Lines -This optional header will be computed by Message. - -@item Message-ID -@cindex Message-ID -@vindex message-user-fqdn -@vindex mail-host-address -@vindex user-mail-address -@findex system-name -@cindex Sun -@cindex i-did-not-set--mail-host-address--so-tickle-me -This required header will be generated by Message. A unique ID will be -created based on the date, time, user name (for the local part) and the -domain part. For the domain part, message will look (in this order) at -@code{message-user-fqdn}, @code{system-name}, @code{mail-host-address} -and @code{message-user-mail-address} (i.e. @code{user-mail-address}) -until a probably valid fully qualified domain name (FQDN) was found. - -@item User-Agent -@cindex User-Agent -This optional header will be filled out according to the -@code{message-newsreader} local variable. - -@item In-Reply-To -This optional header is filled out using the @code{Date} and @code{From} -header of the article being replied to. - -@item Expires -@cindex Expires -@vindex message-expires -This extremely optional header will be inserted according to the -@code{message-expires} variable. It is highly deprecated and shouldn't -be used unless you know what you're doing. - -@item Distribution -@cindex Distribution -@vindex message-distribution-function -This optional header is filled out according to the -@code{message-distribution-function} variable. It is a deprecated and -much misunderstood header. - -@item Path -@cindex path -@vindex message-user-path -This extremely optional header should probably never be used. -However, some @emph{very} old servers require that this header is -present. @code{message-user-path} further controls how this -@code{Path} header is to look. If it is @code{nil}, use the server name -as the leaf node. If it is a string, use the string. If it is neither -a string nor @code{nil}, use the user name only. However, it is highly -unlikely that you should need to fiddle with this variable at all. -@end table - -@findex yow -@cindex Mime-Version -In addition, you can enter conses into this list. The @sc{car} of this cons -should be a symbol. This symbol's name is the name of the header, and -the @sc{cdr} can either be a string to be entered verbatim as the value of -this header, or it can be a function to be called. This function should -return a string to be inserted. For instance, if you want to insert -@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")} -into the list. If you want to insert a funny quote, you could enter -something like @code{(X-Yow . yow)} into the list. The function -@code{yow} will then be called without any arguments. - -If the list contains a cons where the @sc{car} of the cons is -@code{optional}, the @sc{cdr} of this cons will only be inserted if it is -non-@code{nil}. - -If you want to delete an entry from this list, the following Lisp -snippet might be useful. Adjust accordingly if you want to remove -another element. - -@lisp -(setq message-required-news-headers - (delq 'Message-ID message-required-news-headers)) -@end lisp - -Other variables for customizing outgoing news articles: - -@table @code - -@item message-syntax-checks -@vindex message-syntax-checks -Controls what syntax checks should not be performed on outgoing posts. -To disable checking of long signatures, for instance, add - -@lisp -(signature . disabled) -@end lisp - -to this list. - -Valid checks are: - -@table @code -@item approved -@cindex approved -Check whether the article has an @code{Approved} header, which is -something only moderators should include. -@item continuation-headers -Check whether there are continuation header lines that don't begin with -whitespace. -@item control-chars -Check for invalid characters. -@item empty -Check whether the article is empty. -@item existing-newsgroups -Check whether the newsgroups mentioned in the @code{Newsgroups} and -@code{Followup-To} headers exist. -@item from -Check whether the @code{From} header seems nice. -@item illegible-text -Check whether there is any non-printable character in the body. -@item invisible-text -Check whether there is any invisible text in the buffer. -@item long-header-lines -Check for too long header lines. -@item long-lines -@cindex long lines -Check for too long lines in the body. -@item message-id -Check whether the @code{Message-ID} looks syntactically ok. -@item multiple-headers -Check for the existence of multiple equal headers. -@item new-text -Check whether there is any new text in the messages. -@item newsgroups -Check whether the @code{Newsgroups} header exists and is not empty. -@item quoting-style -Check whether text follows last quoted portion. -@item repeated-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers -contains repeated group names. -@item reply-to -Check whether the @code{Reply-To} header looks ok. -@item sender -@cindex Sender -Insert a new @code{Sender} header if the @code{From} header looks odd. -@item sendsys -@cindex sendsys -Check for the existence of version and sendsys commands. -@item shoot -Check whether the domain part of the @code{Message-ID} header looks ok. -@item shorten-followup-to -Check whether to add a @code{Followup-to} header to shorten the number -of groups to post to. -@item signature -Check the length of the signature. -@item size -Check for excessive size. -@item subject -Check whether the @code{Subject} header exists and is not empty. -@item subject-cmsg -Check the subject for commands. -@item valid-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers -are valid syntactically. -@end table - -All these conditions are checked by default, except for @code{sender} -for which the check is disabled by default if -@code{message-insert-canlock} is non-@code{nil} (@pxref{Canceling News}). - -@item message-ignored-news-headers -@vindex message-ignored-news-headers -Regexp of headers to be removed before posting. The default is@* -@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* -^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. - -@item message-default-news-headers -@vindex message-default-news-headers -This string is inserted at the end of the headers in all message -buffers that are initialized as news. - -@end table - - -@node News Variables -@section News Variables - -@table @code -@item message-send-news-function -@vindex message-send-news-function -Function used to send the current buffer as news. The default is -@code{message-send-news}. - -@item message-post-method -@vindex message-post-method -Gnusish @dfn{select method} (see the Gnus manual for details) used for -posting a prepared news message. - -@end table - - -@node Insertion Variables -@section Insertion Variables - -@table @code -@item message-ignored-cited-headers -@vindex message-ignored-cited-headers -All headers that match this regexp will be removed from yanked -messages. The default is @samp{.}, which means that all headers will be -removed. - -@item message-cite-prefix-regexp -@vindex message-cite-prefix-regexp -Regexp matching the longest possible citation prefix on a line. - -@item message-citation-line-function -@vindex message-citation-line-function -@cindex attribution line -Function called to insert the citation line. The default is -@code{message-insert-citation-line}, which will lead to citation lines -that look like: - -@example -Hallvard B Furuseth writes: -@end example - -@c FIXME: Add `message-insert-formated-citation-line' and -@c `message-citation-line-format' - -Point will be at the beginning of the body of the message when this -function is called. - -Note that Gnus provides a feature where clicking on `writes:' hides the -cited text. If you change the citation line too much, readers of your -messages will have to adjust their Gnus, too. See the variable -@code{gnus-cite-attribution-suffix}. @xref{Article Highlighting, , -Article Highlighting, gnus, The Gnus Manual}, for details. - -@item message-yank-prefix -@vindex message-yank-prefix -@cindex yanking -@cindex quoting -When you are replying to or following up an article, you normally want -to quote the person you are answering. Inserting quoted text is done by -@dfn{yanking}, and each line you yank will have -@code{message-yank-prefix} prepended to it (except for quoted lines -which use @code{message-yank-cited-prefix} and empty lines which use -@code{message-yank-empty-prefix}). The default is @samp{> }. - -@item message-yank-cited-prefix -@vindex message-yank-cited-prefix -@cindex yanking -@cindex cited -@cindex quoting -When yanking text from an article which contains already cited text, -each line will be prefixed with the contents of this variable. The -default is @samp{>}. See also @code{message-yank-prefix}. - -@item message-yank-empty-prefix -@vindex message-yank-empty-prefix -@cindex yanking -@cindex quoting -When yanking text from an article, each empty line will be prefixed with -the contents of this variable. The default is @samp{>}. You can set -this variable to an empty string to split the cited text into paragraphs -automatically. See also @code{message-yank-prefix}. - -@item message-indentation-spaces -@vindex message-indentation-spaces -Number of spaces to indent yanked messages. - -@item message-cite-function -@vindex message-cite-function -@findex message-cite-original -@findex message-cite-original-without-signature -Function for citing an original message. The default is -@code{message-cite-original}, which simply inserts the original message -and prepends @samp{> } to each line. -@code{message-cite-original-without-signature} does the same, but elides -the signature. - -@item message-indent-citation-function -@vindex message-indent-citation-function -Function for modifying a citation just inserted in the mail buffer. -This can also be a list of functions. Each function can find the -citation between @code{(point)} and @code{(mark t)}. And each function -should leave point and mark around the citation text as modified. - -@item message-mark-insert-begin -@vindex message-mark-insert-begin -String to mark the beginning of some inserted text. - -@item message-mark-insert-end -@vindex message-mark-insert-end -String to mark the end of some inserted text. - -@item message-signature -@vindex message-signature -String to be inserted at the end of the message buffer. If @code{t} -(which is the default), the @code{message-signature-file} file will be -inserted instead. If a function, the result from the function will be -used instead. If a form, the result from the form will be used instead. -If this variable is @code{nil}, no signature will be inserted at all. - -@item message-signature-file -@vindex message-signature-file -File containing the signature to be inserted at the end of the buffer. -If a path is specified, the value of -@code{message-signature-directory} is ignored, even if set. -The default is @file{~/.signature}. - -@item message-signature-directory -@vindex message-signature-directory -Name of directory containing signature files. Comes in handy if you -have many such files, handled via Gnus posting styles for instance. -If @code{nil} (the default), @code{message-signature-file} is expected -to specify the directory if needed. - - -@item message-signature-insert-empty-line -@vindex message-signature-insert-empty-line -If @code{t} (the default value) an empty line is inserted before the -signature separator. - -@end table - -Note that RFC1036bis says that a signature should be preceded by the three -characters @samp{-- } on a line by themselves. This is to make it -easier for the recipient to automatically recognize and process the -signature. So don't remove those characters, even though you might feel -that they ruin your beautiful design, like, totally. - -Also note that no signature should be more than four lines long. -Including @acronym{ASCII} graphics is an efficient way to get -everybody to believe that you are silly and have nothing important to -say. - - -@node Various Message Variables -@section Various Message Variables - -@table @code -@item message-default-charset -@vindex message-default-charset -@cindex charset -Symbol naming a @acronym{MIME} charset. Non-@acronym{ASCII} characters -in messages are assumed to be encoded using this charset. The default -is @code{iso-8859-1} on non-@sc{mule} Emacsen; otherwise @code{nil}, -which means ask the user. (This variable is used only on non-@sc{mule} -Emacsen.) @xref{Charset Translation, , Charset Translation, emacs-mime, -Emacs MIME Manual}, for details on the @sc{mule}-to-@acronym{MIME} -translation process. - -@item message-fill-column -@vindex message-fill-column -@cindex auto-fill -Local value for the column beyond which automatic line-wrapping should -happen for message buffers. If non-nil (the default), also turn on -auto-fill in message buffers. - -@item message-signature-separator -@vindex message-signature-separator -Regexp matching the signature separator. It is @samp{^-- *$} by -default. - -@item mail-header-separator -@vindex mail-header-separator -String used to separate the headers from the body. It is @samp{--text -follows this line--} by default. - -@item message-directory -@vindex message-directory -Directory used by many mailey things. The default is @file{~/Mail/}. -All other mail file variables are derived from @code{message-directory}. - -@item message-auto-save-directory -@vindex message-auto-save-directory -Directory where Message auto-saves buffers if Gnus isn't running. If -@code{nil}, Message won't auto-save. The default is @file{~/Mail/drafts/}. - -@item message-signature-setup-hook -@vindex message-signature-setup-hook -Hook run when initializing the message buffer. It is run after the -headers have been inserted but before the signature has been inserted. - -@item message-setup-hook -@vindex message-setup-hook -Hook run as the last thing when the message buffer has been initialized, -but before yanked text is inserted. - -@item message-header-setup-hook -@vindex message-header-setup-hook -Hook called narrowed to the headers after initializing the headers. - -For instance, if you're running Gnus and wish to insert a -@samp{Mail-Copies-To} header in all your news articles and all messages -you send to mailing lists, you could do something like the following: - -@lisp -(defun my-message-header-setup-hook () - (let ((group (or gnus-newsgroup-name ""))) - (when (or (message-fetch-field "newsgroups") - (gnus-group-find-parameter group 'to-address) - (gnus-group-find-parameter group 'to-list)) - (insert "Mail-Copies-To: never\n")))) - -(add-hook 'message-header-setup-hook - 'my-message-header-setup-hook) -@end lisp - -@item message-send-hook -@vindex message-send-hook -Hook run before sending messages. - -If you want to add certain headers before sending, you can use the -@code{message-add-header} function in this hook. For instance: -@findex message-add-header - -@lisp -(add-hook 'message-send-hook 'my-message-add-content) -(defun my-message-add-content () - (message-add-header "X-In-No-Sense: Nonsense") - (message-add-header "X-Whatever: no")) -@end lisp - -This function won't add the header if the header is already present. - -@item message-send-mail-hook -@vindex message-send-mail-hook -Hook run before sending mail messages. This hook is run very late -- -just before the message is actually sent as mail. - -@item message-send-news-hook -@vindex message-send-news-hook -Hook run before sending news messages. This hook is run very late -- -just before the message is actually sent as news. - -@item message-sent-hook -@vindex message-sent-hook -Hook run after sending messages. - -@item message-cancel-hook -@vindex message-cancel-hook -Hook run when canceling news articles. - -@item message-mode-syntax-table -@vindex message-mode-syntax-table -Syntax table used in message mode buffers. - -@item message-cite-articles-with-x-no-archive -@vindex message-cite-articles-with-x-no-archive -If non-@code{nil}, don't strip quoted text from articles that have -@samp{X-No-Archive} set. Even if this variable isn't set, you can -undo the stripping by hitting the @code{undo} keystroke. - -@item message-strip-special-text-properties -@vindex message-strip-special-text-properties -Emacs has a number of special text properties which can break message -composing in various ways. If this option is set, message will strip -these properties from the message composition buffer. However, some -packages requires these properties to be present in order to work. If -you use one of these packages, turn this option off, and hope the -message composition doesn't break too bad. - -@item message-send-method-alist -@vindex message-send-method-alist -@findex message-mail-p -@findex message-news-p -@findex message-send-via-mail -@findex message-send-via-news -Alist of ways to send outgoing messages. Each element has the form: - -@lisp -(@var{type} @var{predicate} @var{function}) -@end lisp - -@table @var -@item type -A symbol that names the method. - -@item predicate -A function called without any parameters to determine whether the -message is a message of type @var{type}. The function will be called in -the buffer where the message is. - -@item function -A function to be called if @var{predicate} returns non-@code{nil}. -@var{function} is called with one parameter---the prefix. -@end table - -The default is: - -@lisp -((news message-news-p message-send-via-news) - (mail message-mail-p message-send-via-mail)) -@end lisp - -The @code{message-news-p} function returns non-@code{nil} if the message -looks like news, and the @code{message-send-via-news} function sends the -message according to the @code{message-send-news-function} variable -(@pxref{News Variables}). The @code{message-mail-p} function returns -non-@code{nil} if the message looks like mail, and the -@code{message-send-via-mail} function sends the message according to the -@code{message-send-mail-function} variable (@pxref{Mail Variables}). - -All the elements in this alist will be tried in order, so a message -containing both a valid @samp{Newsgroups} header and a valid @samp{To} -header, for example, will be sent as news, and then as mail. -@end table - - - -@node Sending Variables -@section Sending Variables - -@table @code - -@item message-fcc-handler-function -@vindex message-fcc-handler-function -A function called to save outgoing articles. This function will be -called with the name of the file to store the article in. The default -function is @code{message-output} which saves in Unix mailbox format. - -@item message-courtesy-message -@vindex message-courtesy-message -When sending combined messages, this string is inserted at the start of -the mailed copy. If the string contains the format spec @samp{%s}, the -newsgroups the article has been posted to will be inserted there. If -this variable is @code{nil}, no such courtesy message will be added. -The default value is @samp{"The following message is a courtesy copy of -an article\\nthat has been posted to %s as well.\\n\\n"}. - -@item message-fcc-externalize-attachments -@vindex message-fcc-externalize-attachments -If @code{nil}, attach files as normal parts in Fcc copies; if it is -non-@code{nil}, attach local files as external parts. - -@item message-interactive -@vindex message-interactive -If non-@code{nil} wait for and display errors when sending a message; -if @code{nil} let the mailer mail back a message to report errors. - -@item message-confirm-send -@vindex message-confirm-send -When non-@code{nil}, Gnus will ask for confirmation when sending a -message. - -@end table - - -@node Message Buffers -@section Message Buffers - -Message will generate new buffers with unique buffer names when you -request a message buffer. When you send the message, the buffer isn't -normally killed off. Its name is changed and a certain number of old -message buffers are kept alive. - -@table @code -@item message-generate-new-buffers -@vindex message-generate-new-buffers -Controls whether to create a new message buffer to compose a message. -Valid values include: - -@table @code -@item nil -Generate the buffer name in the Message way (e.g., *mail*, *news*, *mail -to whom*, *news on group*, etc.) and continue editing in the existing -buffer of that name. If there is no such buffer, it will be newly -created. - -@item unique -@item t -Create the new buffer with the name generated in the Message way. This -is the default. - -@item unsent -Similar to @code{unique} but the buffer name begins with "*unsent ". - -@item standard -Similar to @code{nil} but the buffer name is simpler like *mail -message*. -@end table -@table @var -@item function -If this is a function, call that function with three parameters: The -type, the To address and the group name (any of these may be -@code{nil}). The function should return the new buffer name. -@end table - -The default value is @code{unique}. - -@item message-max-buffers -@vindex message-max-buffers -This variable says how many old message buffers to keep. If there are -more message buffers than this, the oldest buffer will be killed. The -default is 10. If this variable is @code{nil}, no old message buffers -will ever be killed. - -@item message-send-rename-function -@vindex message-send-rename-function -After sending a message, the buffer is renamed from, for instance, -@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't -like this, set this variable to a function that renames the buffer in a -manner you like. If you don't want to rename the buffer at all, you can -say: - -@lisp -(setq message-send-rename-function 'ignore) -@end lisp - -@item message-kill-buffer-on-exit -@findex message-kill-buffer-on-exit -If non-@code{nil}, kill the buffer immediately on exit. - -@end table - - -@node Message Actions -@section Message Actions - -When Message is being used from a news/mail reader, the reader is likely -to want to perform some task after the message has been sent. Perhaps -return to the previous window configuration or mark an article as -replied. - -@vindex message-kill-actions -@vindex message-postpone-actions -@vindex message-exit-actions -@vindex message-send-actions -The user may exit from the message buffer in various ways. The most -common is @kbd{C-c C-c}, which sends the message and exits. Other -possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c -C-d} which postpones the message editing and buries the message buffer, -and @kbd{C-c C-k} which kills the message buffer. Each of these actions -have lists associated with them that contains actions to be executed: -@code{message-send-actions}, @code{message-exit-actions}, -@code{message-postpone-actions}, and @code{message-kill-actions}. - -Message provides a function to interface with these lists: -@code{message-add-action}. The first parameter is the action to be -added, and the rest of the arguments are which lists to add this action -to. Here's an example from Gnus: - -@lisp - (message-add-action - `(set-window-configuration ,(current-window-configuration)) - 'exit 'postpone 'kill) -@end lisp - -This restores the Gnus window configuration when the message buffer is -killed, postponed or exited. - -An @dfn{action} can be either: a normal function, or a list where the -@sc{car} is a function and the @sc{cdr} is the list of arguments, or -a form to be @code{eval}ed. - - -@node Compatibility -@chapter Compatibility -@cindex compatibility - -Message uses virtually only its own variables---older @code{mail-} -variables aren't consulted. To force Message to take those variables -into account, you can put the following in your @file{.emacs} file: - -@lisp -(require 'messcompat) -@end lisp - -This will initialize many Message variables from the values in the -corresponding mail variables. - - -@node Appendices -@chapter Appendices - -@menu -* Responses:: Standard rules for determining where responses go. -@end menu - - -@node Responses -@section Responses - -To determine where a message is to go, the following algorithm is used -by default. - -@table @dfn -@item reply -A @dfn{reply} is when you want to respond @emph{just} to the person who -sent the message via mail. There will only be one recipient. To -determine who the recipient will be, the following headers are -consulted, in turn: - -@table @code -@item Reply-To - -@item From -@end table - - -@item wide reply -A @dfn{wide reply} is a mail response that includes @emph{all} entities -mentioned in the message you are responded to. All mailboxes from the -following headers will be concatenated to form the outgoing -@code{To}/@code{Cc} headers: - -@table @code -@item From -(unless there's a @code{Reply-To}, in which case that is used instead). - -@item Cc - -@item To -@end table - -If a @code{Mail-Copies-To} header is present, it will also be included -in the list of mailboxes. If this header is @samp{never}, that means -that the @code{From} (or @code{Reply-To}) mailbox will be suppressed. - - -@item followup -A @dfn{followup} is a response sent via news. The following headers -(listed in order of precedence) determine where the response is to be -sent: - -@table @code - -@item Followup-To - -@item Newsgroups - -@end table - -If a @code{Mail-Copies-To} header is present, it will be used as the -basis of the new @code{Cc} header, except if this header is -@samp{never}. - -@end table - - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index -@printindex cp - -@node Key Index -@chapter Key Index -@printindex ky - -@bye - -@c End: - -@ignore - arch-tag: 16ab76af-a281-4e34-aed6-5624569f7601 -@end ignore diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi deleted file mode 100644 index b9739620f38..00000000000 --- a/doc/misc/mh-e.texi +++ /dev/null @@ -1,9066 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c -@c Note: This document requires makeinfo version 4.6 or greater to build. -@c -@c %**start of header -@setfilename ../../info/mh-e -@settitle The MH-E Manual -@c %**end of header - -@c Version of the software and manual. -@set VERSION 8.2 -@c Edition of the manual. It is either empty for the first edition or -@c has the form ", nth Edition" (without the quotes). -@set EDITION -@set UPDATED 2009-06-13 -@set UPDATE-MONTH June, 2009 - -@c Other variables. -@set MH-BOOK-HOME http://rand-mh.sourceforge.net/book/mh -@set MH-E-HOME http://mh-e.sourceforge.net/ - -@c Copyright -@copying -This is version @value{VERSION}@value{EDITION} of @cite{The MH-E -Manual}, last updated @value{UPDATED}. - -Copyright @copyright{} 1995, 2001, 2002, 2003, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@c This dual license has been agreed upon by the FSF. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of either: - -@enumerate a -@item -the GNU Free Documentation License, Version 1.3 or any later version -published by the Free Software Foundation; with no Invariant Sections, -with the Front-Cover texts being ``A GNU Manual,'' and with the -Back-Cover Texts as in (a) below. A copy of the license is included in -the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -@item -the GNU General Public License as published by the Free Software -Foundation; either version 3, or (at your option) any later version. A -copy of the license is included in the section entitled ``GNU General -Public License.'' -@end enumerate - -@end quotation -@end copying - -@c Info Directory Entry -@dircategory Emacs -@direntry -* MH-E: (mh-e). Emacs interface to the MH mail system. -@end direntry - -@c Title Page -@titlepage -@title The MH-E Manual -@subtitle Version @value{VERSION}@value{EDITION} -@subtitle @value{UPDATE-MONTH} -@author Bill Wohler - -@c Copyright Page -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@ifnottex -@html - -@end html -@insertcopying -@end ifnottex - -@c Table of Contents -@contents - -@html - -@end html - -@node Preface, Conventions, Top, Top -@unnumbered Preface - -@cindex Emacs -@cindex Unix commands, Emacs -@cindex preface - -This manual introduces another interface to the MH mail system that is -accessible through the GNU Emacs editor, namely, @emph{MH-E}. MH-E is -easy to use. I don't assume that you know GNU Emacs or even MH at this -point, since I didn't know either of them when I discovered MH-E. -However, MH-E was the tip of the iceberg, and I discovered more and -more niceties about GNU Emacs and MH@. Now I'm fully hooked on both of -them. - -The MH-E package is distributed with GNU Emacs@footnote{Version -@value{VERSION} of MH-E will appear in GNU Emacs 23.1. It is supported -in GNU Emacs 21 and 22, as well as XEmacs 21 (except for versions -21.5.9-21.5.16). It is compatible with MH versions 6.8.4 and higher, -all versions of nmh, and GNU mailutils 1.0 and higher.}, so you -shouldn't have to do anything special to use it. Gnus is also -required; version 5.10 or higher is recommended. This manual covers -MH-E version @value{VERSION}. To help you decide which version you -have, see @ref{Getting Started}. - -@findex help-with-tutorial -@kindex C-h t - -If you don't already use GNU Emacs but want to learn more, you can -read an online tutorial by starting GNU Emacs and typing @kbd{C-h t} -(@code{help-with-tutorial}). (To learn about this notation, see -@ref{Conventions}.) If you want to take the plunge, consult the -@iftex -@cite{GNU Emacs Manual}, -@end iftex -@ifinfo -@ref{top, , GNU Emacs Manual, emacs, GNU Emacs Manual}, -@end ifinfo -@ifhtml -@uref{http://www.gnu.org/software/emacs/manual/html_node/, -@cite{GNU Emacs Manual}}, -@end ifhtml -from the Free Software Foundation. - -If more information is needed, you can go to the Unix manual pages of -the individual MH commands. When the name is not obvious, I'll guide -you to a relevant MH manual page that describes the action more fully. - -@cindex @cite{MH & nmh: Email for Users & Programmers} -@cindex MH book -@cindex info -@kindex C-h i - -This manual is available in both Info and online formats. The Info -version is distributed with Emacs and can be accessed with the -@command{info} command (@samp{info mh-e}) or within Emacs (@kbd{C-h i -m mh-e @key{RET}}). The online version is available at -@uref{http://mh-e.sourceforge.net/manual/, SourceForge}. Another great -online resource is the book @uref{http://www.ics.uci.edu/~mh/book/, -@cite{MH & nmh: Email for Users & Programmers}} (also known as -@dfn{the MH book}). - -I hope you enjoy this manual! If you have any comments, or suggestions -for this document, please let me know. - -@cindex Bill Wohler -@cindex Wohler, Bill - -@noindent -Bill Wohler <@i{wohler at newt.com}>@* -8 February 1995@* -24 February 2006 - -@node Conventions, Getting Started, Preface, Top -@chapter GNU Emacs Terms and Conventions - -@cindex Emacs -@cindex Emacs, conventions -@cindex Emacs, terms -@cindex Unix commands, Emacs -@cindex conventions, Emacs -@cindex terms, Emacs - -If you're an experienced Emacs user, you can skip the following -conventions and definition of terms and go directly to the next -section (@pxref{Getting Started}). - -@cindex Emacs commands -@cindex MH commands -@cindex Unix commands -@cindex commands -@cindex commands, MH -@cindex commands, Unix -@cindex commands, shell -@cindex functions -@cindex shell commands - -In general, @dfn{functions} in this text refer to Emacs Lisp functions -that one would call from within Emacs Lisp programs (for example, -@code{(mh-inc-folder)}). On the other hand, @dfn{commands} are those -things that are run by the user, such as @kbd{i} or @kbd{M-x -mh-inc-folder}. Programs outside of Emacs are specifically called MH -commands, shell commands, or Unix commands. - -@cindex conventions, key names -@cindex key names - -The conventions for key names are as follows: - -@table @kbd -@item C-x -Hold down the @key{CTRL} (Control) key and press the @kbd{x} key. -@c ------------------------- -@item M-x -Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key. - -Since some keyboards don't have a @key{META} key, you can generate -@kbd{M-x}, for example, by pressing @key{ESC} (Escape), -@emph{releasing it}, and then pressing the @kbd{x} key. -@c ------------------------- -@item @key{RET} -Press the @key{RETURN} or @key{ENTER} key. This is normally used to -complete a command. -@c ------------------------- -@item @key{SPC} -Press the space bar. -@c ------------------------- -@item @key{TAB} -Press the @key{TAB} key. -@c ------------------------- -@item @key{DEL} -Press the @key{DELETE} key. -@c ------------------------- -@item @key{BS} -Press the @key{BACKSPACE} key@footnote{If you are using Version 20 or -earlier of Emacs, you will need to use the @key{DEL} key.}. -@end table - -@cindex Emacs, prefix argument -@cindex prefix argument -@kindex C-u - -A @dfn{prefix argument} allows you to pass an argument to any Emacs -function. To pass an argument, type @kbd{C-u} before the Emacs command -or keystroke. Numeric arguments can be passed as well. For example, to -insert five f's, use @kbd{C-u 5 f}. There is a default of four when -using @kbd{C-u}, and you can use multiple prefix arguments to provide -arguments of powers of four. To continue our example, you could insert -four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with -@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative -arguments can also be inserted with the @key{META} key. Examples -include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which -specifies a negative argument with no particular value. - -@sp 1 -@center @strong{NOTE} - -@quotation -The prefix @kbd{C-u} or @kbd{M-} is not necessary in MH-E's MH-Folder -mode (@pxref{Reading Mail Tour}). In this mode, simply enter the -numerical argument before entering the command. -@end quotation -@sp 1 - -@cindex @file{.emacs} -@cindex Emacs, variables -@cindex files, @file{.emacs} -@cindex variables -@findex setq - -Emacs uses @dfn{variables} to hold values. These can be changed via -calls to the function @code{setq} in @file{~/.emacs}. - -@cindex Emacs, options -@cindex options -@findex customize-group -@findex customize-option - -Variables in MH-E that are normally modified by the user are called -@dfn{options} and are modified through the customize functions (such -as @kbd{M-x customize-option} or @kbd{M-x customize-group}). -@ifnothtml -@xref{Easy Customization,,,emacs,The GNU Emacs Manual}, in @cite{The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Easy-Customization.html, -Easy Customization} in @cite{The GNU Emacs Manual}. -@end ifhtml -@xref{Options}. - -@cindex Emacs, faces -@cindex faces -@cindex highlighting -@findex customize-face - -You can specify various styles for displaying text using @dfn{faces}. -MH-E provides a set of faces that you can use to personalize the look -of your MH-E buffers. Use the command @kbd{M-x customize-face} to do -this. -@ifnothtml -@xref{Face Customization,,,emacs,The GNU Emacs Manual}, in @cite{The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Face-Customization.html, -Face Customization} in @cite{The GNU Emacs Manual}. -@end ifhtml - -@cindex abnormal hooks -@cindex hooks -@cindex normal hooks -@findex add-hook -@findex customize-option - -Commands often offer @dfn{hooks} which enable you to extend or modify -the way a command works. -@ifnothtml -@ref{Hooks, , Hooks, emacs, The GNU Emacs Manual}, in @cite{The GNU -Emacs Manual} -@end ifnothtml -@ifhtml -See section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Hooks.html, -Hooks} in @cite{The GNU Emacs Manual} -@end ifhtml -for a description about @dfn{normal hooks} and @dfn{abnormal hooks}. -MH-E uses normal hooks in nearly all cases, so you can assume that we -are talking about normal hooks unless we explicitly mention that a -hook is abnormal. We also follow the conventions described in that -section: the name of the abnormal hooks end in @code{-hooks} and all -the rest of the MH-E hooks end in @code{-hook}. You can add hooks with -either @code{customize-option} or @code{add-hook}. - -@cindex Emacs, mark -@cindex Emacs, point -@cindex Emacs, region -@cindex mark -@cindex point -@cindex region -@kindex C-@@ -@kindex C-@key{SPC} - -There are several other terms that are used in Emacs that you should -know. The @dfn{point} is where the cursor currently is. You can save -your current place in the file by setting a @dfn{mark}. This operation -is useful in several ways. The mark can be later used when defining a -@dfn{region}, which is the text between the point and mark. Many -commands operate on regions, such as those for deleting text or -filling paragraphs. A mark can be set with @kbd{C-@@} (or -@kbd{C-@key{SPC}}). - -@cindex completion -@cindex Emacs, completion -@cindex Emacs, file completion -@cindex Emacs, folder completion -@cindex Emacs, minibuffer -@cindex file completion -@cindex folder completion -@cindex minibuffer -@kindex SPC -@kindex TAB - -The @dfn{minibuffer} is the bottom line of the Emacs window, where all -prompting and multiple-character input is directed. You can use -@dfn{completion} to enter values such as folders. Completion means -that Emacs fills in text for you when you type @key{SPC} or @key{TAB}. -A second @key{SPC} or @key{TAB} will list all possibilities at that -point. -@ifnothtml -@xref{Completion, , Completion, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -See the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, -Completion} in @cite{The GNU Emacs Manual}. -@end ifhtml -Note that @key{SPC} cannot be used for completing filenames and -folders. - -@findex help-with-tutorial -@kindex C-h t -@kindex M-x - -The minibuffer is also where you enter Emacs function names after -typing @kbd{M-x}. For example, in the preface, I mentioned that you -could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What -this means is that you can get a tutorial by typing either @kbd{C-h t} -or @kbd{M-x help-with-tutorial}. In the latter case, you are prompted -for @samp{help-with-tutorial} in the minibuffer after typing -@kbd{M-x}. - -@cindex ~ - -The @samp{~} notation in filenames represents your home directory. -This notation is used by many shells including @command{bash}, -@code{tcsh}, and @command{csh}. It is analogous to the environment -variable @samp{$HOME}. For example, @file{~/.emacs} can be written -@file{$HOME/.emacs} or using the absolute path as in -@file{/home/wohler/.emacs} instead. - -@cindex Emacs, interrupting -@cindex Emacs, quitting -@cindex interrupting -@cindex quitting - -@i{In case of trouble:} Emacs can be interrupted at any time with -@kbd{C-g}. For example, if you've started a command that requests that -you enter something in the minibuffer, but then you change your mind, -type @kbd{C-g} and you'll be back where you started. If you want to -exit Emacs entirely, use @kbd{C-x C-c}. - -@node Getting Started, Tour Through MH-E, Conventions, Top -@chapter Getting Started - -@cindex MH-E, versions -@cindex history -@cindex versions of MH-E - -Because there are many old versions of MH-E out there, it is important -to know which version you have. I'll be talking about @w{Version 8} -which is pretty close to @w{Version 6} and @w{Version 7}. It differs -from @w{Version 4} and @w{Version 5} and is vastly different from -@w{Version 3}. @xref{History}. - -@findex mh-version - -To determine which version of MH-E that you have, enter @kbd{M-x -mh-version @key{RET}}. Hopefully it says that you're running -@w{Version @value{VERSION}} which is the latest version as of this -printing. - -If your version is much older than this, please consider upgrading. -You can have your system administrator upgrade the system-wide -version, or you can install your own personal version. It's really -quite easy. @xref{Getting MH-E}, for instructions for getting and -installing MH-E. - -If the @code{mh-version} command displays @samp{No MH variant -detected}@footnote{In very old versions of MH-E, you may get the error -message, @samp{Cannot find the commands `inc' and `mhl' and the file -`components'} if MH-E can't find MH. In this case, you need to update -MH-E, and you may need to install MH too. However, newer versions of -MH-E are better at finding MH if it is on your system.}, then you need -to install MH or tell MH-E where to find MH. - -@cindex Debian -@cindex nmh -@cindex GNU mailutils MH - -If you don't have MH on your system already, you must install a -variant of MH. The Debian mh-e package does this for you automatically -(@pxref{Getting MH-E}). Most people use -@uref{http://www.nongnu.org/nmh/, nmh}, but you may be interested in -trying out @uref{http://www.gnu.org/software/mailutils/, GNU mailutils -MH}, which supports IMAP. Your GNU/Linux distribution probably has -packages for both of these. - -@cindex @command{install-mh} -@cindex MH commands, @command{install-mh} -@cindex MH book - -If you've never run MH before, you need to run @command{install-mh} -from the shell before you continue. This sets up your personal MH -environment@footnote{See the section -@uref{@value{MH-BOOK-HOME}/../overall/setup.html, Setting Up MH} in the -MH book.}. If you don't, you'll be greeted with the error message: -@samp{Install MH and run install-mh before running MH-E}. This is all -you need to know about MH to use MH-E, but the more you know about MH, -the more you can leverage its power. See the -@uref{@value{MH-BOOK-HOME}/../, MH book} to learn more about MH. - -@cindex @samp{Path:} MH profile component -@cindex MH profile -@cindex MH profile component -@cindex MH profile component, @samp{Path:} - -Your MH environment includes your @dfn{MH profile} which is found in -the file @file{~/.mh_profile}, or the file named in the environment -variable @samp{$MH}. This file contains a number of @dfn{MH -profile components}. For example, the @samp{Path:} MH profile -component contains the path to your mail directory, which is -@file{~/Mail} by default. - -@cindex @command{mhparam} -@cindex MH commands, @command{mhparam} -@vindex exec-path -@vindex mh-path -@vindex mh-sys-path -@vindex mh-variant -@vindex mh-variant-in-use - -There are several options MH-E uses to interact with your MH -installation. The option @code{mh-variant} specifies the variant used -by MH-E (@pxref{Options}). The default setting of this option is -@samp{Auto-detect} which means that MH-E will automatically choose the -first of nmh, MH, or GNU mailutils MH that it finds in the directories -listed in @code{mh-path} (which you can customize), -@code{mh-sys-path}, and @code{exec-path}. If MH-E can't find MH at -all, you may have to customize @code{mh-path} and add the directory in -which the command @command{mhparam} is located. If, on the other hand, -you have both nmh and GNU mailutils MH installed (for example) and -@code{mh-variant-in-use} was initialized to nmh but you want to use -GNU mailutils MH, then you can set @code{mh-variant} to -@samp{gnu-mh}. - -@vindex mh-flists-present-flag -@vindex mh-lib -@vindex mh-lib-progs -@vindex mh-progs - -When @code{mh-variant} is changed, MH-E resets @code{mh-progs}, -@code{mh-lib}, @code{mh-lib-progs}, @code{mh-flists-present-flag}, and -@code{mh-variant-in-use} accordingly. - -@cindex @file{.emacs} -@cindex files, @file{.emacs} - -@sp 1 -@center @strong{NOTE} - -@quotation -Prior to version 8, it was often necessary to set some of these -variables in @file{~/.emacs}; now it is no longer necessary and can -actually cause problems. -@end quotation -@sp 1 - -@cindex MH profile component, @samp{Draft-Folder:} -@cindex MH profile component, @samp{Path:} -@cindex MH profile component, @samp{Previous-Sequence:} -@cindex MH profile component, @samp{Unseen-Sequence:} -@cindex @samp{Draft-Folder:} MH profile component -@cindex @samp{Path:} MH profile component -@cindex @samp{Previous-Sequence:} MH profile component -@cindex @samp{Unseen-Sequence:} MH profile component -@findex mh-find-path -@vindex mh-draft-folder -@vindex mh-find-path-hook -@vindex mh-inbox -@vindex mh-previous-seq -@vindex mh-unseen-seq -@vindex mh-user-path - -In addition to setting variables that point to MH itself, MH-E also -sets a handful of variables that point to where you keep your mail. -During initialization, the function @code{mh-find-path} sets -@code{mh-user-path} from your @samp{Path:} MH profile component (but -defaults to @samp{Mail} if one isn't present), @code{mh-draft-folder} -from @samp{Draft-Folder:}, @code{mh-unseen-seq} from -@samp{Unseen-Sequence:}, @code{mh-previous-seq} from -@samp{Previous-Sequence:}, and @code{mh-inbox} from @samp{Inbox:} -(defaults to @samp{+inbox}). The hook @code{mh-find-path-hook} is run -after these variables have been set. This hook can be used the change -the value of these variables if you need to run with different values -between MH and MH-E. - -@node Tour Through MH-E, Using This Manual, Getting Started, Top -@chapter Tour Through MH-E - -@cindex introduction -@cindex tour -@cindex tutorial - -This chapter introduces some of the terms you'll need to know and then -takes you on a tour of MH-E@footnote{The keys mentioned in these -chapters refer to the default key bindings. If you've changed the -bindings, refer to the command summaries at the beginning of each -chapter for a mapping between default key bindings and function -names.}. When you're done, you'll be able to send, read, and file -mail, which is all that a lot of people ever do. But if you're the -curious or adventurous type, read the rest of the manual to be able to -use all the features of MH-E. I suggest you read this chapter first to -get the big picture, and then you can read the manual as you wish. - -@menu -* Sending Mail Tour:: -* Reading Mail Tour:: -* Processing Mail Tour:: -* Leaving MH-E:: -* More About MH-E:: -@end menu - -@node Sending Mail Tour, Reading Mail Tour, Tour Through MH-E, Tour Through MH-E -@section Sending Mail - -@cindex MH-Letter mode -@cindex mode -@cindex modes, MH-Letter -@cindex sending mail -@findex mh-smail -@kindex M-x mh-smail - -Let's start our tour by sending ourselves a message which we can later -read and process. Enter @kbd{M-x mh-smail} to invoke the MH-E program -to send messages. Your message appears in an Emacs buffer whose -mode@footnote{A @dfn{mode} changes Emacs to make it easier to edit a -particular type of text.} is MH-Letter. - -Enter your login name in the @samp{To:} header field. Press the -@key{TAB} twice to move the cursor past the @samp{Cc:} field, since no -carbon copies are to be sent, and on to the @samp{Subject:} field. -Enter @kbd{Test} or anything else that comes to mind. - -Press @key{TAB} again to move the cursor to the body of the message. -Enter some text, using normal Emacs commands. You should now have -something like this@footnote{If you're running Emacs under the X -Window System, then you would also see a menu bar and a tool bar. I've -left out the menu bar and tool bar in all of the example screens.}: - -@cartouche -@smallexample - - - - - - ---:-- *scratch* All L1 (Lisp Interaction)------------------------- -To: wohler -cc: -Subject: Test -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 --------- -This is a test message to get the wheels churning...# - - ---:** @{draft@} All L5 (MH-Letter)---------------------------------- -Type C-c C-c to send message, C-C ? for help -@end smallexample -@end cartouche -@i{MH-E message composition window} - -Note the line of dashes that separates the header and the body of the -message. It is essential that these dashes (or a blank line) are -present or the body of your message will be considered to be part of -the header. - -@cindex help -@findex describe-mode -@kindex C-c ? -@kindex C-c C-c -@kindex C-h m - -There are several commands specific to MH-Letter mode@footnote{You can -get quick help for the commands used most often with @kbd{C-c ?} or -more complete help with the @kbd{C-h m} (@code{describe-mode}) -command.}, but at this time we'll only use @kbd{C-c C-c} to send your -message. Type @kbd{C-c C-c} now. That's all there is to it! - -@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through MH-E -@section Receiving Mail - -@cindex @command{inc} -@cindex @command{scan} -@cindex MH commands, @command{inc} -@cindex MH commands, @command{scan} -@cindex MH-Folder mode -@cindex modes, MH-Folder -@cindex reading mail -@findex mh-rmail -@kindex M-x mh-rmail - -To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}. -This incorporates the new mail and puts the output from -@command{inc}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} (called @dfn{scan lines} after the MH program -@command{scan}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan -pick Ranges Sequences} in the MH book.} which prints a one-line -summary of each message) into a buffer called @samp{+inbox} whose -major mode is MH-Folder. - -@findex mh-rmail -@kindex F r -@kindex M-x mh-rmail - -@sp 1 -@center @strong{NOTE} - -@quotation - -The @kbd{M-x mh-rmail} command will show you only new mail, not mail -you have already read. If you were to run this tour again, you would -use @kbd{F r} to pull all your messages into MH-E. -@end quotation -@sp 1 - -@kindex @key{RET} -@kindex n -@kindex p - -You should see the scan line for your message, and perhaps others. Use -@kbd{n} or @kbd{p} to move the cursor to your test message and type -@key{RET} to read your message. You should see something like: - -@cartouche -@smallexample - 3 t08/24 root received fax files on Wed Aug 24 11:00:13 PDT 1 -# 4+t08/24 To:wohler Test< - -This is a test message to get the wheels churning... - - - ---:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- - -@end smallexample -@end cartouche -@i{After incorporating new messages} - -@kindex @key{DEL} -@kindex @key{SPC} - -If you typed a long message, you can view subsequent pages with -@key{SPC} and previous pages with @key{DEL}. - -@node Processing Mail Tour, Leaving MH-E, Reading Mail Tour, Tour Through MH-E -@section Processing Mail - -@cindex processing mail -@kindex @key{RET} -@kindex r - -The first thing we want to do is reply to the message that we sent -ourselves. Ensure that the cursor is still on the same line as your -test message and type @kbd{r}. You are prompted in the minibuffer with -@samp{Reply to whom:}. Here MH-E is asking whether you'd like to reply -to the original sender only, to the sender and primary recipients, or -to the sender and all recipients. You can press @key{TAB} to see these -choices. If you simply press @key{RET}, you'll reply only to the -sender. Press @key{RET} now. - -You'll find yourself in an Emacs buffer similar to that when you were -sending the original message, like this: - -@cartouche -@smallexample -To: -cc: -Subject: Re: Test -In-reply-to: <31054.1142621351@@stop.mail-abuse.org> -References: <31054.1142621351@@stop.mail-abuse.org> -Comments: In-reply-to Bill Wohler - message dated "Fri, 17 Mar 2006 10:49:11 -0800." -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 --------- -# - ---:-- @{draft@} All L10 (MH-Letter)---------------------------------- -To: wohler -Subject: Test -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -Date: Fri, 17 Mar 2006 10:49:11 -0800 -From: Bill Wohler - -This is a test message to get the wheels churning... - ---:-- @{show-+inbox@} 4 All L1 (MH-Show)---------------------------- -Type C-c C-c to send message, C-c ? for help -@end smallexample -@end cartouche -@i{Composition window during reply} - -@findex backward-char -@findex forward-char -@findex next-line -@findex previous-line -@kindex C-b -@kindex C-c C-c -@kindex C-c C-f C-t -@kindex C-f -@kindex C-n -@kindex C-p -@kindex @key{BS} - -By default, MH will not add you to the address list of your replies, -so if you find that the @samp{To:} header field is missing, don't -worry. In this case, type @kbd{C-c C-f C-t} to create and go to the -@samp{To:} field, where you can type your login name again. You can -move around with the arrow keys or with @kbd{C-p} -(@code{previous-line}), @kbd{C-n} (@code{next-line}), @kbd{C-b} -(@code{backward-char}), and @kbd{C-f} (@code{forward-char}) and can -delete the previous character with @key{BS}. When you're finished -editing your message, send it with @kbd{C-c C-c} as before. - -@cindex @command{refile} -@cindex MH commands, @command{refile} -@cindex folders -@kindex @key{SPC} -@kindex o - -You'll often want to save messages that were sent to you in an -organized fashion. This is done with @dfn{folders}. You can use -folders to keep messages from your friends, or messages related to a -particular topic. With your cursor in the MH-Folder buffer and -positioned on the message you sent to yourself, type @kbd{o} to output -(@command{refile} in MH parlance) that message to a folder. Enter -@kbd{test} at the @samp{Destination folder:} prompt and type @kbd{y} -(or @key{SPC}) when MH-E asks to create the folder @samp{+test}. Note -that a @samp{^} (caret) appears next to the message number, which -means that the message has been marked for refiling but has not yet -been refiled. We'll talk about how the refile is actually carried out -in a moment. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@kindex d -@kindex i -@kindex @key{RET} -@kindex n -@kindex p -@kindex x - -Your previous reply is now waiting in the system mailbox. You -incorporate this mail into your MH-Folder buffer named @samp{+inbox} -with the @kbd{i} command. Do this now. After the mail is incorporated, -use @kbd{n} or @kbd{p} to move the cursor to the new message, and read -it with @key{RET}. Let's delete this message by typing @kbd{d}. Note -that a @samp{D} appears next to the message number. This means that -the message is marked for deletion but is not yet deleted. To perform -the deletion (and the refile we did previously), use the @kbd{x} -command. - -@findex mh-smail -@kindex m -@kindex M-x mh-smail - -If you want to send another message you can use @kbd{m} instead of -@kbd{M-x mh-smail}. So go ahead, send some mail to your friends! - -@cindex help -@cindex prefix characters -@findex describe-mode -@kindex ? -@kindex C-h m -@kindex F ? - -You can get a quick reminder about these commands by typing @kbd{?}. -This lists several @dfn{prefix characters}. To list the commands -available via the prefix characters, type the prefix character -followed by a @kbd{?}, for example, @kbd{F ?}. More complete help is -available with the @kbd{C-h m} (@code{describe-mode}) command. - -@node Leaving MH-E, More About MH-E, Processing Mail Tour, Tour Through MH-E -@section Leaving MH-E - -@cindex Emacs, quitting -@cindex quitting -@kindex C-x C-c -@kindex x - -You may now wish to exit @command{emacs} entirely. Use @kbd{C-x C-c} -to exit @command{emacs}. If you exited without running @kbd{x} in the -@samp{+inbox} buffer, Emacs will offer to save it for you. Type -@kbd{y} or @key{SPC} to save @samp{+inbox} changes, which means to -perform any refiles and deletes that you did there. - -@findex mh-rmail -@kindex C-x b -@kindex C-x k -@kindex M-x mh-rmail -@kindex q - -If you don't want to leave Emacs, you can type @kbd{q} to bury (hide) -the MH-E folder or delete it entirely with @kbd{C-x k}. You can then -later recall it with @kbd{C-x b} or @kbd{M-x mh-rmail}. - -@cindex @command{packf} -@cindex MH commands, @command{packf} -@cindex exporting folders -@cindex folders, exporting -@cindex mbox-style folder - -On the other hand, if you no longer want to use MH and MH-E, you can -take your mail with you. You can copy all of your mail into a single -file, mbox-style, by using the MH command @command{packf}. For -example, to create a file called @file{msgbox} with the messages in -your @samp{+inbox} folder, use @samp{packf +inbox}. The -@command{packf} command will append the messages to the file if it -already exists, so you can use @samp{folders -recurse -fast} in a -script to copy all of your messages into a single file, or using the -@samp{-file} argument, a file for each folder. - -@node More About MH-E, , Leaving MH-E, Tour Through MH-E -@section More About MH-E - -These are the basic commands to get you going, but there are plenty -more. If you think that MH-E is for you, read the rest of the manual -to find out how you can: - -@itemize @bullet -@item -Print your messages (@pxref{Printing}). -@c ------------------------- -@item -Edit messages and include your signature (@pxref{Editing Drafts}). -@c ------------------------- -@item -Forward messages (@pxref{Forwarding}). -@c ------------------------- -@item -Read digests (@pxref{Digests}). -@c ------------------------- -@item -Edit bounced messages (@pxref{Editing Again}). -@c ------------------------- -@item -Send multimedia messages (@pxref{Adding Attachments}). -@c ------------------------- -@item -Read HTML messages (@pxref{HTML}). -@c ------------------------- -@item -Use aliases and identities (see @ref{Aliases}, @pxref{Identities}). -@c ------------------------- -@item -Create different views of your mail (see @ref{Threading}, @pxref{Limits}). -@c ------------------------- -@item -Deal with junk mail (@pxref{Junk}). -@c ------------------------- -@item -Handle signed and encrypted messages (see @ref{Reading PGP}, -@pxref{Sending PGP}). -@c ------------------------- -@item -Process mail that was sent with @command{shar} or @command{uuencode} -(@pxref{Files and Pipes}). -@c ------------------------- -@item -Use sequences conveniently (@pxref{Sequences}). -@c ------------------------- -@item -Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool -Bar}, @pxref{Menu Bar}). -@c ------------------------- -@item -Show header fields in different fonts (@pxref{Reading Mail}). -@c ------------------------- -@item -Find previously refiled messages (@pxref{Searching}). -@c ------------------------- -@item -Place messages in a file (@pxref{Files and Pipes}). -@end itemize - -Remember that you can also use MH commands when you're not running -MH-E (and when you are!). - -@node Using This Manual, Incorporating Mail, Tour Through MH-E, Top -@chapter Using This Manual - -This chapter begins the meat of the manual which goes into more detail -about every MH-E command and option. - -@cindex Emacs, info -@cindex Emacs, online help -@cindex info -@cindex online help -@findex describe-mode -@findex mh-help -@kindex ? -@kindex C-c ? -@kindex C-h C-h -@kindex C-h C-k i -@kindex C-h i -@kindex C-h m - -There are many commands, but don't get intimidated. There are command -summaries at the beginning of each chapter. In case you have or would -like to rebind the keys, the command summaries also list the -associated Emacs Lisp function. Furthermore, even if you're stranded -on a desert island with a laptop and are without your manuals, you can -get a summary of all these commands with GNU Emacs online help: use -@kbd{C-h m} (@code{describe-mode}) for a brief summary of commands, -@kbd{?} (@code{mh-help}) for an even briefer summary@footnote{This -help appears in a buffer called @samp{*MH-E Help*} -(@pxref{Miscellaneous}).} (@kbd{C-c ?} in MH-Letter mode), or @kbd{C-h -i} to read this manual via Info. The online help is quite good; try -running @kbd{C-h C-h}. This brings up a list of available help topics, -one of which displays the documentation for a given key (like @kbd{C-h -k C-n}). Another useful help feature is to view the manual section -that describes a given key (such as @kbd{C-h K i}). In addition, -review @ref{Conventions}, if any of the GNU Emacs conventions are -strange to you. - -In addition to all of the commands, it is also possible to reconfigure -MH-E to fit the needs of even the most demanding user. The following -chapters also describe all of the options, show the defaults, and make -recommendations for customization. - -However, when customizing your mail environment, first try to change -what you want in MH, and only change MH-E if changing MH is not -possible. That way you will get the same behavior inside and outside -GNU Emacs. Note that MH-E does not provide hooks for customizations -that can be done in MH; this omission is intentional. - -@cindex Emacs Lisp Manual -@cindex Emacs, Emacs Lisp Manual -@cindex Emacs, info -@cindex Emacs, online help -@cindex info -@cindex online help - -I hope I've included enough examples here to get you well on your way. -If you want to explore Emacs Lisp further, a programming manual does -exist, -@c Yes, some of the stuff in the following sections is redundant, but -@c TeX barfs if the @ifs are inside the @footnote. -@iftex -@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available -online in the Info system by typing @kbd{C-h i m Emacs Lisp -@key{RET}}. It is also available online at @* -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You -can also order a printed manual, which has the desirable side-effect -of helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end iftex -@ifinfo -@footnote{@xref{Top, The GNU Emacs Lisp Reference Manual, , elisp, GNU -Emacs Lisp Reference Manual}, which may be available online in the -Info system. It is also available online at -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/}. You -can also order a printed manual, which has the desirable side-effect -of helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end ifinfo -@ifhtml -@footnote{The -@uref{http://www.gnu.org/software/emacs/elisp-manual/html_node/, -The GNU Emacs Lisp Reference Manual} may also be available online in -the Info system by typing @kbd{C-h i m Emacs Lisp @key{RET}}. You can -also order a printed manual, which has the desirable side-effect of -helping to support the Free Software Foundation which made all this -great software available. You can find an order form by running -@kbd{C-h C-d}, or you can request an order form from @i{gnu at -gnu.org}.} -@end ifhtml -and you can look at the code itself for examples. Look in the Emacs -Lisp directory on your system (such as -@file{/usr/local/lib/emacs/lisp/mh-e}) and find all the @file{mh-*.el} -files there. When calling MH-E and other Emacs Lisp functions directly -from Emacs Lisp code, you'll need to know the correct arguments. Use -the online help for this. For example, try @kbd{C-h f -mh-execute-commands @key{RET}}. If you write your own functions, -please do not prefix your symbols (variables and functions) with -@samp{mh-}. This prefix is reserved for the MH-E package. To avoid -conflicts with existing MH-E symbols, use a prefix like @samp{my-} or -your initials. (Unless, of course, your initials happen to be @emph{mh}!) - -@menu -* Options:: -* Ranges:: -* Folder Selection:: -@end menu - -@node Options, Ranges, Using This Manual, Using This Manual -@section Options - -@cindex Emacs, customizing -@cindex Emacs, setting options -@cindex customizing MH-E -@cindex setting options -@findex customize-option -@vindex mh-lpr-command-format, example - -Many string or integer options are easy to modify using @kbd{M-x -customize-option}. For example, to modify the option that controls -printing, you would run @kbd{M-x customize-option @key{RET} -mh-lpr-command-format @key{RET}}. In the buffer that appears, modify -the string to the right of the variable. For example, you may change -the @command{lpr} command with @samp{nenscript -G -r -2 -i'%s'}. Then -use the @samp{State} combo box and select @samp{Save for Future -Sessions}. To read more about @code{mh-lpr-command-format}, see -@ref{Printing}. - -@cindex nil -@cindex off, option -@cindex on, option -@cindex option, turning on and off -@cindex t -@findex customize-option -@vindex mh-bury-show-buffer-flag, example - -Options can also hold boolean values. In Emacs Lisp, the boolean -values are @code{nil}, which means false, and @code{t}, which means -true. The @code{customize-option} function makes it easy to change -boolean values; simply click on the toggle button in the customize -buffer to switch between @samp{on} (@code{t}) and @samp{off} -(@code{nil}). For example, try setting @code{mh-bury-show-buffer-flag} -to @samp{off} to keep the MH-Show buffer at the top of the buffer -stack. Use the @samp{State} combo box and choose @samp{Set for Current -Session} to see how the option affects the show buffer. Then choose -the @samp{Erase Customization} menu item to reset the option to the -default, which places the MH-Show buffer at the bottom of the buffer -stack. - -@vindex mh-mhl-format-file, example - -The text usually says to turn on an option by setting it to a -@emph{non-@code{nil}} value, because sometimes values other than -@samp{on} are meaningful. An example of this is the variable -@code{mh-mhl-format-file} (@pxref{Viewing}). Other options, such as -hooks, involve a little more Emacs Lisp programming expertise. - -@cindex customization group, @samp{mh} -@cindex @samp{mh} customization group -@findex customize-group -@findex mh-customize - -You can browse all of the MH-E options with the @code{customize-group} -function. Try entering @kbd{M-x customize-group @key{RET} mh -@key{RET}} to view the top-level options as well as buttons for all of -the MH-E customization groups. Another way to view the MH-E -customization group is to use @kbd{M-x mh-customize @key{RET}}. - -@node Ranges, Folder Selection, Options, Using This Manual -@section Ranges - -@c Sync with mh-folder-mode docstring. - -@cindex message abbreviations -@cindex message ranges -@cindex ranges - -Many commands that operate on individual messages, such as -@code{mh-forward} or @code{mh-refile-msg} take a @code{RANGE} -argument. This argument can be used in several ways. - -@kindex C-u, with ranges - -If you provide the prefix argument @kbd{C-u} to these commands, then -you will be prompted for the message range. This can be any valid MH -range which can include messages, sequences (@pxref{Sequences}), and -the abbreviations (described in the @command{mh}(1) man page): - -@table @samp -@item - -Indicates all messages in the range to , inclusive. The -range must be nonempty. -@c ------------------------- -@item :N -@itemx :+N -@itemx :-N -Up to N messages beginning with (or ending with) message num. Num may -be any of the predefined symbols: first, prev, cur, next or last. -@c ------------------------- -@item first:N -@itemx prev:N -@itemx next:N -@itemx last:N -The first, previous, next or last messages, if they exist. -@c ------------------------- -@item all -All of the messages. -@end table - -For example, a range that shows all of these things is @samp{1 2 3 -5-10 last:5 unseen}. - -@vindex transient-mark-mode - -If the option @code{transient-mark-mode} is turned on and you set a -region in the MH-Folder buffer, then the MH-E command will perform the -operation on all messages in that region. - -@cindex @samp{mh-range} customization group -@cindex customization group, @samp{mh-range} - -The @samp{mh-range} customization group contains a single option which -affects how ranges are interpreted. - -@vtable @code -@item mh-interpret-number-as-range-flag -On means interpret a number as a range (default: @samp{on}). -@end vtable - -@vindex mh-interpret-number-as-range-flag - -Since one of the most frequent ranges used is @samp{last:N}, MH-E will -interpret input such as @samp{200} as @samp{last:200} if the -@code{mh-interpret-number-as-range-flag} option is on (which is the -default). If you need to scan just the message 200, then use the range -@samp{200:1} or @samp{200-200}. - -@node Folder Selection, , Ranges, Using This Manual -@section Folder Selection - -@cindex completion, folders -@cindex folders, completion -@cindex folders, selecting - -When you choose a folder in MH-E via a command such as @kbd{o} -(@code{mh-refile-msg}), completion is used to enter the folder -@ifnothtml -(@pxref{Completion, , , emacs, The GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Completion.html, -Completion} in @cite{The GNU Emacs Manual}). -@end ifhtml -In addition, MH-E has several ways of choosing a suitable default so -that the folder can often be selected with a single @key{RET} key. - -@cindex customization group, @samp{mh-folder-selection} -@cindex @samp{mh-folder-selection} customization group - -The @samp{mh-folder-selection} customization group contains some -options which are used to help with this. - -@vtable @code -@item mh-default-folder-for-message-function -Function to select a default folder for refiling or @samp{Fcc:} -(default: @code{nil}). -@c ------------------------- -@item mh-default-folder-list -List of addresses and folders (default: @code{nil}). -@c ------------------------- -@item mh-default-folder-must-exist-flag -On means guessed folder name must exist to be used (default: -@samp{on}). -@c ------------------------- -@item mh-default-folder-prefix -Prefix used for folder names generated from aliases (default: @code{""}). -@end vtable - -@vindex mh-default-folder-for-message-function - -You can set the option @code{mh-default-folder-for-message-function} -to a function that provides a default folder for the message to be -refiled. When this function is called, the current buffer contains the -message being refiled and point is at the start of the message. This -function should return the default folder as a string with a leading -@samp{+} sign. It can also return @code{nil} so that the last folder -name is used as the default, or an empty string to suppress the -default entirely. - -Otherwise, the name of the destination folder is derived from the -sender as follows: - -@enumerate -@vindex mh-default-folder-list -@item -The folder name associated with the first address found in the list -@code{mh-default-folder-list} is used. Each element in this list -contains a @samp{Check Recipient} item. If this item is turned on, -then the address is checked against the recipient instead of the -sender. This is useful for mailing lists. -@c ------------------------- -@vindex mh-default-folder-prefix -@item -An alias prefixed by @code{mh-default-folder-prefix} corresponding to -the address is used. The prefix is used to prevent clutter in your -mail directory. @xref{Aliases}. -@end enumerate - -@vindex mh-default-folder-must-exist-flag - -If the derived folder does not exist, and -@code{mh-default-folder-must-exist-flag} is @code{t}, then the last -folder name used is suggested. This is useful if you get mail from -various people for whom you have an alias, but file them all in the -same project folder. - -@node Incorporating Mail, Reading Mail, Using This Manual, Top -@chapter Incorporating Your Mail - -@cindex @samp{Folder} menu -@cindex incorporating -@cindex menu, @samp{Folder} - -This chapter talks about getting mail from your system mailbox into -your MH @samp{+inbox} folder. The following command accomplishes that -and is found in the @samp{Folder} menu. - -@table @kbd -@cindex @samp{Folder > Incorporate New Mail} menu item -@cindex menu item, @samp{Folder > Incorporate New Mail} -@findex mh-inc-folder -@kindex i -@item i -Incorporate new mail into a folder (@code{mh-inc-folder}). -@end table - -@cindex @samp{mh-inc} customization group -@cindex customization group, @samp{mh-inc} - -The following options in the @samp{mh-inc} customization group are -used. - -@vtable @code -@item mh-inc-prog -Program to incorporate mail (default: @code{"inc"}). -@c ------------------------- -@item mh-inc-spool-list -Alternate spool files (default: @code{nil}). -@end vtable - -The following hook is available. - -@vtable @code -@findex mh-inc-folder -@item mh-inc-folder-hook -Hook run by @code{mh-inc-folder} after incorporating mail into a -folder (default: @code{nil}). -@end vtable - -@cindex @samp{+inbox} -@findex mh-inc-folder -@kindex i - -If at any time you receive new mail, incorporate the new mail into -your @samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note -that @kbd{i} will display the @samp{+inbox} buffer, even if there -isn't any new mail. You can incorporate mail from any file into the -current folder by specifying a prefix argument; you'll be prompted for -the name of the file to use as well as the destination folder (for -example, @kbd{C-u i ~/mbox @key{RET} +tmp @key{RET}}). - -@cindex @file{.emacs} -@cindex Emacs, notification of new mail -@cindex files, @file{.emacs} -@cindex new mail -@cindex notification of new mail - -Emacs can notify you when you have new mail by displaying @samp{Mail} -in the mode line. To enable this behavior, and to have a clock in the -mode line as well, add the following to @file{~/.emacs}: - -@findex display-time - -@smalllisp -(display-time) -@end smalllisp - -@cindex @command{inc} -@cindex incorporating -@cindex MH commands, @command{inc} -@vindex mh-inc-prog -@vindex mh-progs - -The name of the program that incorporates new mail is stored in -@code{mh-inc-prog}; it is @code{"inc"} by default. This program -generates a one-line summary for each of the new messages. Unless it -is an absolute pathname, the file is assumed to be in the -@code{mh-progs} directory (@pxref{Getting Started}). You may also link -a file to @command{inc} that uses a different format (see -@samp{mh-profile}(5), and sections -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} and @uref{@value{MH-BOOK-HOME}/mhstr.html, MH Format Strings} in -the MH book). You'll then need to modify several variables -appropriately (@pxref{Scan Line Formats}). - -@vindex mh-inc-spool-list - -You can use the @code{mh-inc-spool-list} variable to direct MH-E to -retrieve mail from arbitrary spool files other than your system -mailbox, file it in folders other than your @samp{+inbox}, and assign -key bindings to incorporate this mail. - -@cindex @command{procmail} -@cindex @file{.procmailrc} -@cindex Unix commands, @command{procmail} -@cindex files, @file{.procmailrc} - -Suppose you are subscribed to the @i{mh-e-devel} mailing list and you -use @command{procmail} to filter this mail into @file{~/mail/mh-e} -with the following recipe in @file{.procmailrc}: - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` -:0: -* ^From mh-e-devel-admin@@stop.mail-abuse.org -mh-e -@end smallexample - -@findex mh-inc-spool-* -@kindex I * - -In order to incorporate @file{~/mail/mh-e} into @samp{+mh-e} with an -@kbd{I m} (@code{mh-inc-spool-mh-e}) command, customize this option, -and click on the @samp{INS} button. Enter a @samp{Spool File} of -@samp{~/mail/mh-e}, a @samp{Folder} of @samp{mh-e}, and a @samp{Key -Binding} of @samp{m}. - -@cindex @command{emacsclient} -@cindex @command{gnuclient} -@cindex @command{xbuffy} -@cindex @samp{gnuserv} -@cindex Unix commands, @command{emacsclient} -@cindex Unix commands, @command{gnuclient} -@cindex Unix commands, @command{xbuffy} - -You can use @command{xbuffy} to automate the incorporation of this -mail using the Emacs 23 command @command{emacsclient} as follows: - -@smallexample -box ~/mail/mh-e - title mh-e - origMode - polltime 10 - headertime 0 - command emacsclient --eval '(mh-inc-spool-mh-e)' -@end smallexample - -In XEmacs, the command @command{gnuclient} is used in a similar -fashion. - -@findex mh-inc-folder -@kindex i -@vindex mh-inc-folder-hook - -You can set the hook @code{mh-inc-folder-hook}, which is called after -new mail is incorporated by the @kbd{i} (@code{mh-inc-folder}) -command. A good use of this hook is to rescan the whole folder either -after running @kbd{M-x mh-rmail} the first time or when you've changed -the message numbers from outside of MH-E. - -@findex mh-execute-commands -@findex mh-rescan-folder, example -@findex mh-show, example -@vindex mh-inc-folder-hook, example - -@smalllisp -@group -(defun my-mh-inc-folder-hook () - "Hook to rescan folder after incorporating mail." - (if (buffer-modified-p) ; @r{if outstanding refiles and deletes,} - (mh-execute-commands)) ; @r{carry them out} - (mh-rescan-folder) ; @r{synchronize with +inbox} - (mh-show)) ; @r{show the current message} - -(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook) - -@i{Rescan folder after incorporating new mail via mh-inc-folder-hook} - -@end group -@end smalllisp - -@node Reading Mail, Folders, Incorporating Mail, Top -@chapter Reading Your Mail - -@cindex @samp{+inbox} -@cindex MH-Folder mode -@cindex MH-Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Show -@cindex reading mail -@findex mh-rmail -@kindex F r -@kindex F v -@kindex M-x mh-rmail - -The MH-E entry point for reading mail is @kbd{M-x mh-rmail}. This -command incorporates your mail and creates a buffer called -@samp{+inbox} in MH-Folder mode. The command @kbd{M-x mh-rmail} shows -you only new mail, not mail you have already read@footnote{If you want -to see your old mail as well, use @kbd{F r} to pull all your messages -into MH-E. Or, give a prefix argument to @code{mh-rmail} so it will -prompt you for folder to visit like @kbd{F v} (for example, @kbd{C-u -M-x mh-rmail @key{RET} bob @key{RET}}). @xref{Folders}.}. - -@findex display-time -@vindex read-mail-command - -There are some commands that need to read mail, such as @kbd{Mouse-2} -over the @samp{Mail} button that @code{display-time} adds to the mode -line. You can configure Emacs to have these commands use MH-E by -setting the option @code{read-mail-command} to @samp{mh-rmail}. - -@cindex @command{scan} -@cindex @samp{Message} menu -@cindex MH commands, @command{scan} -@cindex menu, @samp{Message} -@cindex scan lines - -The @samp{+inbox} buffer contains @dfn{scan lines}, which are one-line -summaries of each incorporated message. You can perform most MH -commands on these messages via one- or two-letter commands in either -the MH-Folder or MH-Show buffers or by using the @samp{Message} menu. -See @command{scan}(1) for a description of the contents of the scan -lines, and see the Figure in @ref{Reading Mail Tour}, for an example. - -@table @kbd -@kindex ? -@findex mh-help -@item ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Message > Show Message} menu item -@cindex menu item, @samp{Message > Show Message} -@kindex @key{RET} -@findex mh-show -@item @key{RET} -Display message (@code{mh-show}). -@c ------------------------- -@cindex @samp{Message > Show Message with Header} menu item -@cindex menu item, @samp{Message > Show Message with Header} -@kindex , (comma) -@findex mh-header-display -@item , (comma) -Display message with all header fields (@code{mh-header-display}). -@c ------------------------- -@cindex @samp{Message > Show Message with Preferred Alternative} menu item -@cindex menu item, @samp{Message > Show Message with Preferred Alternative} -@kindex : (colon) -@findex mh-show-preferred-alternative -@item : (colon) -Display message with the default preferred alternative -(@code{mh-show-preferred-alternative}). -@c ------------------------- -@kindex ; (semicolon) -@findex mh-toggle-mh-decode-mime-flag -@item ; (semicolon) -Toggle the value of @code{mh-decode-mime-flag} -(@code{mh-toggle-mh-decode-mime-flag}). -@c ------------------------- -@kindex @key{SPC} -@findex mh-page-msg -@item @key{SPC} -Display next page in message (@code{mh-page-msg}). -@c ------------------------- -@kindex @key{BS} -@findex mh-previous-page -@item @key{BS} -Display previous page in message (@code{mh-previous-page}). -@c ------------------------- -@cindex @samp{Message > Write Message to File...} menu item -@cindex menu item, @samp{Message > Write Message to File...} -@kindex > -@findex mh-write-msg-to-file -@item > -Append message to end of file (@code{mh-write-msg-to-file}). -@c ------------------------- -@cindex @samp{Message > Pipe Message to Command...} menu item -@cindex menu item, @samp{Message > Pipe Message to Command...} -@kindex | -@findex mh-pipe-msg -@item | -Pipe message through shell command (@code{mh-pipe-msg}). -@c ------------------------- -@kindex C-d -@findex mh-delete-msg-no-motion -@item C-d -Delete range, don't move to next message -(@code{mh-delete-msg-no-motion}). -@c ------------------------- -@cindex @samp{Message > Delete Message} menu item -@cindex menu item, @samp{Message > Delete Message} -@kindex d -@findex mh-delete-msg -@item d -Delete range (@code{mh-delete-msg}). -@c ------------------------- -@kindex D ? -@findex mh-prefix-help -@item D ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex D @key{SPC} -@findex mh-page-digest -@item D @key{SPC} -Display next message in digest (@code{mh-page-digest}). -@c ------------------------- -@kindex D @key{BS} -@findex mh-page-digest-backwards -@item D @key{BS} -Display previous message in digest (@code{mh-page-digest-backwards}). -@c ------------------------- -@cindex @samp{Message > Burst Digest Message} menu item -@cindex menu item, @samp{Message > Burst Digest Message} -@kindex D b -@findex mh-burst-digest -@item D b -Break up digest into separate messages (@code{mh-burst-digest}). -@c ------------------------- -@cindex @samp{Message > Go to Message by Number...} menu item -@cindex menu item, @samp{Message > Go to Message by Number...} -@kindex g -@findex mh-goto-msg -@item g -Go to a message (@code{mh-goto-msg}). -@c ------------------------- -@kindex k -@findex mh-delete-subject-or-thread -@item k -Delete messages with same subject or thread -(@code{mh-delete-subject-or-thread}). -@c ------------------------- -@kindex K ? -@findex mh-prefix-help -@item K ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex K @key{TAB} -@findex mh-next-button -@item K @key{TAB} -Go to the next button (@code{mh-next-button}). -@c ------------------------- -@kindex K S-@key{TAB} -@findex mh-prev-button -@item K S-@key{TAB} -Go to the previous button (@code{mh-prev-button}). -@c ------------------------- -@kindex K a -@findex mh-mime-save-parts -@item K a -Save attachments (@code{mh-mime-save-parts}). -@c ------------------------- -@kindex K e -@findex mh-display-with-external-viewer -@item K e -View attachment externally (@code{mh-display-with-external-viewer}). -@c ------------------------- -@kindex K i -@findex mh-folder-inline-mime-part -@item K i -Show attachment verbatim (@code{mh-folder-inline-mime-part}). -@c ------------------------- -@kindex K o -@findex mh-folder-save-mime-part -@item K o -Save (output) attachment (@code{mh-folder-save-mime-part}). -@c ------------------------- -@kindex K t -@findex mh-toggle-mime-buttons -@item K t -Toggle option @code{mh-display-buttons-for-inline-parts-flag} -(@code{mh-toggle-mime-buttons}). -@c ------------------------- -@kindex K v -@findex mh-folder-toggle-mime-part -@item K v -View attachment (@code{mh-folder-toggle-mime-part}). -@c ------------------------- -@cindex @samp{Message > Modify Message} menu item -@cindex menu item, @samp{Message > Modify Message} -@kindex M -@findex mh-modify -@item M -Edit message (@code{mh-modify}). -@c ------------------------- -@cindex @samp{Message > Go to First Message} menu item -@cindex menu item, @samp{Message > Go to First Message} -@kindex M-< -@findex mh-first-msg -@item M-< -Display first message (@code{mh-first-msg}). -@c ------------------------- -@cindex @samp{Message > Go to Last Message} menu item -@cindex menu item, @samp{Message > Go to Last Message} -@kindex M-> -@findex mh-last-msg -@item M-> -Display last message (@code{mh-last-msg}). -@c ------------------------- -@kindex M-n -@findex mh-next-unread-msg -@item M-n -Display next unread message (@code{mh-next-unread-msg}). -@c ------------------------- -@kindex M-p -@findex mh-previous-unread-msg -@item M-p -Display previous unread message (@code{mh-previous-unread-msg}). -@c ------------------------- -@cindex @samp{Message > Next Message} menu item -@cindex menu item, @samp{Message > Next Message} -@kindex n -@findex mh-next-undeleted-msg -@item n -Display next message (@code{mh-next-undeleted-msg}). -@c ------------------------- -@cindex @samp{Message > Previous Message} menu item -@cindex menu item, @samp{Message > Previous Message} -@kindex p -@findex mh-previous-undeleted-msg -@item p -Display previous message (@code{mh-previous-undeleted-msg}). -@c ------------------------- -@kindex P ? -@findex mh-prefix-help -@item P ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex P C -@findex mh-ps-print-toggle-color -@item P C -Toggle whether color is used in printing messages -(@code{mh-ps-print-toggle-color}). -@c ------------------------- -@kindex P F -@findex mh-ps-print-toggle-faces -@item P F -Toggle whether printing is done with faces or not -(@code{mh-ps-print-toggle-faces}). -@c ------------------------- -@kindex P f -@findex mh-ps-print-msg-file -@item P f -Print range to file (@code{mh-ps-print-msg-file}). -@c ------------------------- -@cindex @samp{Message > Print Message} menu item -@cindex menu item, @samp{Message > Print Message} -@kindex P l -@findex mh-print-msg -@item P l -Print range the old fashioned way -(@code{mh-print-msg}). -@c ------------------------- -@kindex P p -@findex mh-ps-print-msg -@item P p -Print range (@code{mh-ps-print-msg}). -@c ------------------------- -@kindex X ? -@findex mh-prefix-help -@item X ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Message > Unpack Uuencoded Message...} menu item -@cindex menu item, @samp{Message > Unpack Uuencoded Message...} -@kindex X s -@kindex X u -@findex mh-store-msg -@item X s -@itemx X u -Unpack message created with @command{uudecode} or @command{shar} -(@code{mh-store-msg}). -@c ------------------------- -@kindex Mouse-2 -@findex mh-show-mouse -@item Mouse-2 -Move point to mouse event and show message (@code{mh-show-mouse}). -@end table - -Within the MH-Show buffer, the following command is defined. - -@table @kbd -@kindex @key{RET} -@kindex Mouse-1 -@kindex Mouse-2 -@findex mh-press-button -@item @key{RET} -@itemx Mouse-1 -@itemx Mouse-2 -View contents of button (@code{mh-press-button}). -@end table - -@cindex @samp{mh-show} customization group -@cindex customization group, @samp{mh-show} - -The following table lists options in the @samp{mh-show} customization -group that are used while reading mail. - -@vtable @code -@item mh-bury-show-buffer-flag -On means show buffer is buried (default: @samp{on}). -@c ------------------------- -@item mh-clean-message-header-flag -On means remove extraneous header fields (default: @samp{on}). -@c ------------------------- -@item mh-decode-mime-flag -On means attachments are handled (default: @samp{on} if the Gnus -@samp{mm-decode} package is present). -@c ------------------------- -@item mh-display-buttons-for-alternatives-flag -On means display buttons for all alternative attachments (default: -@samp{off}). -@c ------------------------- -@item mh-display-buttons-for-inline-parts-flag -On means display buttons for all inline attachments (default: -@samp{off}). -@c ------------------------- -@item mh-do-not-confirm-flag -On means non-reversible commands do not prompt for confirmation -(default: @samp{off}). -@c ------------------------- -@item mh-fetch-x-image-url -Control fetching of @samp{X-Image-URL:} header field image (default: -@samp{Never Fetch}). -@c ------------------------- -@item mh-graphical-smileys-flag -On means graphical smileys are displayed (default: @samp{on}). -@c ------------------------- -@item mh-graphical-emphasis-flag -On means graphical emphasis is displayed (default: @samp{on}). -@c ------------------------- -@item mh-highlight-citation-style -Style for highlighting citations (default: @samp{Multicolor}). -@c ------------------------- -@item mh-invisible-header-fields-default -List of hidden header fields (default: a checklist too long to list -here). -@c ------------------------- -@item mh-invisible-header-fields -Additional header fields to hide (default: @code{nil}). -@c ------------------------- -@item mh-lpr-command-format -Command used to print (default: @code{"lpr -J '%s'"}). -@c ------------------------- -@item mh-max-inline-image-height -Maximum inline image height if @samp{Content-Disposition:} is not -present (default: 0). -@c ------------------------- -@item mh-max-inline-image-width -Maximum inline image width if @samp{Content-Disposition:} is not -present(default: 0). -@c ------------------------- -@item mh-mhl-format-file -Specifies the format file to pass to the @command{mhl} program -(default: @samp{Use Default mhl Format (Printing Only)}). -@c ------------------------- -@item mh-mime-save-parts-default-directory -Default directory to use for @kbd{K a}. -@c ------------------------- -@item mh-print-background-flag -On means messages should be printed in the background (default: -@samp{off}). -@c ------------------------- -@item mh-show-buffer-mode-line-buffer-id -Format string to produce @code{mode-line-buffer-identification} for -show buffers (default: @code{" @{show-%s@} %d"}). -@c ------------------------- -@item mh-show-maximum-size -Maximum size of message (in bytes) to display automatically (default: -0). -@c ------------------------- -@item mh-show-use-xface-flag -On means display face images in MH-Show buffers (default: @samp{on}). -@c ------------------------- -@item mh-store-default-directory -Default directory for @kbd{X s} (default: @samp{Current}). -@c ------------------------- -@item mh-summary-height -Number of lines in MH-Folder buffer (including the mode line) -(default: depends on size of frame). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-delete-msg-hook -Hook run after marking each message for deletion (default: @code{nil}). -@c ------------------------- -@item mh-show-hook -Hook run after @key{RET} shows a message (default: @code{nil}). -@c ------------------------- -@item mh-show-mode-hook -Hook run upon entry to @code{mh-show-mode} (default: @code{nil}). -@end vtable - -The following faces are available. - -@vtable @code -@item mh-show-cc -Face used to highlight @samp{cc:} header fields. -@c ------------------------- -@item mh-show-date -Face used to highlight @samp{Date:} header fields. -@c ------------------------- -@item mh-show-from -Face used to highlight @samp{From:} header fields. -@c ------------------------- -@item mh-show-header -Face used to deemphasize less interesting header fields. -@c ------------------------- -@item mh-show-pgg-bad -Bad PGG signature face. -@c ------------------------- -@item mh-show-pgg-good -Good PGG signature face. -@c ------------------------- -@item mh-show-pgg-unknown -Unknown or untrusted PGG signature face. -@c ------------------------- -@item mh-show-signature -Signature face. -@c ------------------------- -@item mh-show-subject -Face used to highlight @samp{Subject:} header fields. -@c ------------------------- -@item mh-show-to -Face used to highlight @samp{To:} header fields. -@c ------------------------- -@item mh-show-xface -X-Face image face. -@end vtable - -The functions and variables introduced here are explained in more -detail in the following sections. - -@menu -* Viewing:: -* Viewing Attachments:: -* HTML:: -* Digests:: -* Reading PGP:: -* Printing:: -* Files and Pipes:: -* Navigating:: -* Miscellaneous Commands and Options:: -@end menu - -@node Viewing, Viewing Attachments, Reading Mail, Reading Mail -@section Viewing Your Mail - -@findex mh-header-display -@findex mh-page-msg -@findex mh-previous-page -@findex mh-show -@findex mh-show-mouse -@kindex , (comma) -@kindex . (period) -@kindex @key{BS} -@kindex @key{RET} -@kindex @key{SPC} -@kindex Mouse-2 - -The command @key{RET} (@code{mh-show}) displays the message that the -cursor is on while @kbd{Mouse-2} (@code{mh-show-mouse}) displays the -message that the mouse cursor is on. If the message is already -displayed, it scrolls to the beginning of the message. Use @key{SPC} -(@code{mh-page-msg}) and @key{BS} (@code{mh-previous-page}) to move -forwards and backwards one page at a time through the message. You can -give either of these commands a prefix argument that specifies the -number of lines to scroll (such as @kbd{10 @key{SPC}}). The @key{SPC} -command will also show the next undeleted message if it is used at the -bottom of a message. MH-E normally hides a lot of the superfluous -header fields that mailers add to a message, but if you wish to see -all of them, use the command @kbd{,} (comma; -@code{mh-header-display}). - -@vindex mh-show-maximum-size - -The option @code{mh-show-maximum-size} provides an opportunity to skip -over large messages which may be slow to load. The default value of 0 -means that all message are shown regardless of size. - -A litany of options control what displayed messages look like. - -@vindex mh-show-cc -@vindex mh-show-date -@vindex mh-show-from -@vindex mh-show-header -@vindex mh-show-subject -@vindex mh-show-to - -First, the appearance of the header fields can be modified by -customizing the associated face: @code{mh-show-to}, @code{mh-show-cc}, -@code{mh-show-from}, @code{mh-show-date}, and @code{mh-show-subject}. -The face @code{mh-show-header} is used to deemphasize the other, less -interesting, header fields. - -@cindex regular expressions, @code{mh-invisible-header-fields} -@vindex mh-clean-message-header-flag -@vindex mh-invisible-header-fields -@vindex mh-invisible-header-fields-default - -Normally messages are delivered with a handful of uninteresting header -fields. These are hidden by turning on the option -@code{mh-clean-message-header-flag} (which it is by default). The -header fields listed in the option -@code{mh-invisible-header-fields-default} are hidden, although you can -check off any field that you would like to see. Header fields that you -would like to hide that aren't listed can be added to the option -@code{mh-invisible-header-fields} with a couple of caveats. Regular -expressions are not allowed. Unique fields should have a @samp{:} -suffix; otherwise, the element can be used to render invisible an -entire class of fields that start with the same prefix. If you think a -header field should be generally ignored, please update -@uref{https://sourceforge.net/tracker/index.php?func=detail&aid=1916032&group_id=13357&atid=113357, -SF #1916032}. - -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field -@vindex mh-show-use-xface-flag - -MH-E can display the content of @samp{Face:}, @samp{X-Face:}, and -@samp{X-Image-URL:} header fields. If any of these fields occur in the -header of your message, the sender's face will appear in the -@samp{From:} header field. If more than one of these fields appear, -then the first field found in the order @samp{Face:}, @samp{X-Face:}, -and @samp{X-Image-URL:} will be used. The option -@code{mh-show-use-xface-flag} is used to turn this feature on and off. -This feature will be turned on by default if your system supports it. - -The first header field used, if present, is the Gnus-specific -@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU -Emacs 21 and XEmacs. For more information, see -@uref{http://quimby.gnus.org/circus/face/}.}. - -@cindex @command{uncompface} -@cindex Emacs, packages, x-face -@cindex Unix commands, @command{uncompface} -@cindex x-face package -@vindex mh-show-xface - -Next is the traditional @samp{X-Face:} header field@footnote{The -display of this field requires the -@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, -@command{uncompface} program}. Recent versions of XEmacs have internal -support for @samp{X-Face:} images. If your version of XEmacs does not, -then you'll need both @command{uncompface} and the -@uref{ftp://ftp.jpl.org/pub/elisp/, @samp{x-face} package}.}. MH-E -renders the foreground and background of the image using the -associated attributes of the face @code{mh-show-xface}. - -@cindex @command{convert} -@cindex @command{wget} -@cindex ImageMagick -@cindex Unix commands, @command{convert} -@cindex Unix commands, @command{wget} -@vindex mh-fetch-x-image-url - -Finally, MH-E will display images referenced by the -@samp{X-Image-URL:} header field if neither the @samp{Face:} nor the -@samp{X-Face:} fields are present@footnote{The display of the images -requires the @uref{http://www.gnu.org/software/wget/wget.html, -@command{wget} program} to fetch the image and the @command{convert} -program from the @uref{http://www.imagemagick.org/, ImageMagick -suite}.}. Of the three header fields this is the most efficient in -terms of network usage since the image doesn't need to be transmitted -with every single mail. The option @code{mh-fetch-x-image-url} -controls the fetching of the @samp{X-Image-URL:} header field image -with the following values: - -@table @samp -@item Ask Before Fetching -You are prompted before the image is fetched. MH-E will remember your -reply and will either use the already fetched image the next time the -same URL is encountered or silently skip it if you didn't fetch it the -first time. This is a good setting. -@c ------------------------- -@item Never Fetch -Images are never fetched and only displayed if they are already -present in the cache. This is the default. -@end table - -There isn't a value of @samp{Always Fetch} for privacy and DOS (denial -of service) reasons. For example, fetching a URL can tip off a spammer -that you've read his email (which is why you shouldn't blindly answer -yes if you've set this option to @samp{Ask Before Fetching}). Someone -may also flood your network and fill your disk drive by sending a -torrent of messages, each specifying a unique URL to a very large -file. - -@cindex @file{.mhe-x-image-cache} -@cindex files, @file{.mhe-x-image-cache} - -The cache of images is found in the directory -@file{.mhe-x-image-cache} within your MH directory. You can add your -own face to the @samp{From:} field too. @xref{Picture}. - -@cindex @command{mhl} -@cindex MH commands, @command{mhl} -@vindex mh-mhl-format-file - -Normally MH-E takes care of displaying messages itself (rather than -calling an MH program to do the work). If you'd rather have -@command{mhl} display the message (within MH-E), change the option -@code{mh-mhl-format-file} from its default value of @samp{Use Default -mhl Format (Printing Only)}. You can set this option to @samp{Use -Default mhl Format} to get the same output as you would get if you ran -@command{mhl} from the shell. If you have a format file that you want -MH-E to use, you can set this option to @samp{Specify an mhl Format -File} and enter the name of your format file (@command{mhl}(1) or -section @uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in -the MH book tells you how to write one). Your format file should -specify a non-zero value for @samp{overflowoffset} to allow MH-E to -parse the header. Note that @command{mhl} is always used for printing -and forwarding; in this case, the value of @code{mh-mhl-format-file} -is consulted if you have specified a format file. - -@cindex citations, highlighting -@cindex highlighting citations -@vindex mh-highlight-citation-style - -If the sender of the message has cited other messages in his message, -then MH-E will highlight these citations to emphasize the sender's -actual response. The option @code{mh-highlight-citation-style} can be -customized to change the highlighting style. The @samp{Multicolor} -method uses a different color for each indentation while the -@samp{Monotone} method highlights all citations in red. To disable -highlighting of citations entirely, choose @samp{None}. - -@cindex URLs, highlighting -@cindex email addresses, highlighting -@cindex highlighting URLs -@cindex highlighting email addresses -@cindex links, following -@findex goto-address-at-point -@kindex C-c @key{RET} -@kindex Mouse-2 -@vindex goto-address-highlight-p - -Email addresses and URLs in the message are highlighted if the option -@code{goto-address-highlight-p} is on, which it is by default. To view -the web page for a highlighted URL or to send a message using a -highlighted email address, use @kbd{Mouse-2} or @kbd{C-c @key{RET}} -(@code{goto-address-at-point}). @xref{Sending Mail}, to see how to -configure Emacs to send the message using MH-E. - -@cindex boldface, showing -@cindex emphasis -@cindex italics, showing -@cindex smileys -@cindex typesetting -@cindex underline, showing -@vindex gnus-emphasis-alist -@vindex mh-decode-mime-flag -@vindex mh-graphical-emphasis-flag -@vindex mh-graphical-smileys-flag - -It is a long standing custom to inject body language using a -cornucopia of punctuation, also known as the @dfn{smileys}. MH-E can -render these as graphical widgets if the option -@code{mh-graphical-smileys-flag} is turned on, which it is by default. -Smileys include patterns such as :-) and ;-). Similarly, a few -typesetting features are indicated in ASCII text with certain -characters. If your terminal supports it, MH-E can render these -typesetting directives naturally if the option -@code{mh-graphical-emphasis-flag} is turned on, which it is by -default. For example, _underline_ will be -@ifhtml -@html -underlined, -@end html -@end ifhtml -@ifnothtml -underlined, -@end ifnothtml -*bold* will appear in @b{bold}, /italics/ will appear in @i{italics}, -and so on. See the option @code{gnus-emphasis-alist} for the whole -list. Both of these options are disabled if the option -@code{mh-decode-mime-flag} is turned off. @xref{Viewing Attachments}. - -@cindex signature separator -@cindex vCard -@vindex mh-show-signature - -MH-E normally renders signatures and vCards in italics so that the -body of the message stands out more. MH-E depends on the presence of -the @dfn{signature separator} (@code{"-- "}) to do this. You can also -customize the face @code{mh-show-signature} so the appearance of the -signature block is more to your liking. - -@vindex mh-show-hook -@vindex mh-show-mode-hook - -Two hooks can be used to control how messages are displayed. The first -hook, @code{mh-show-mode-hook}, is called early on in the process of -the message display. It is usually used to perform some action on the -message's content. The second hook, @code{mh-show-hook}, is the last -thing called after messages are displayed. It's used to affect the -behavior of MH-E in general or when @code{mh-show-mode-hook} is too -early. - -@cindex MH-Show mode -@cindex modes, MH-Show -@vindex mh-show-buffer-mode-line-buffer-id - -For those who like to modify their mode lines, use -@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in -the MH-Show buffers. Place the two escape strings @samp{%s} and -@samp{%d}, which will display the folder name and the message number, -respectively, somewhere in the string in that order. The default value -of @code{"@{show-%s@} %d"} yields a mode line of - -@smallexample ------@{show-+inbox@} 4 (MH-Show)--Bot-------------------------------- -@end smallexample - -@node Viewing Attachments, HTML, Viewing, Reading Mail -@section Viewing Attachments - -@cindex attachments -@cindex body parts -@cindex @command{mhshow} -@cindex @command{show} -@cindex MH commands, @command{mhshow} -@cindex MH commands, @command{show} -@cindex MIME -@cindex multimedia mail - -MH has the ability to display @dfn{@sc{mime}} (Multipurpose Internet -Mail Extensions) messages which are simply messages with additional -@dfn{body parts} or @dfn{attachments}. You can use the MH commands -@command{show}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} or @command{mhshow}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#ReMIMa, Reading MIME Mail} in -the MH book.} from the shell to read @sc{mime} messages@footnote{You -can call them directly from Emacs if you're running the X Window -System: type @kbd{M-! xterm -e mhshow @var{message-number}}. You can -leave out the @samp{xterm -e} if you use @command{mhlist} or -@command{mhstore}.}. - -@cindex Emacs, packages, mm-decode -@cindex mm-decode package -@findex mh-toggle-mh-decode-mime-flag -@kindex ; (semicolon) -@vindex mh-decode-mime-flag - -MH-E can handle attachments as well if the Gnus @samp{mm-decode} -package is present. If so, the option @code{mh-decode-mime-flag} will -be on. Otherwise, you'll see the @sc{mime} body parts rather than text -or attachments. There isn't much point in turning off the option -@code{mh-decode-mime-flag}; however, you can inspect it if it appears -that the body parts are not being interpreted correctly or toggle it -with the command @kbd{;} (semicolon; -@code{mh-toggle-mh-decode-mime-flag}) to view the raw message. This -option also controls the display of quoted-printable messages and -other graphical widgets. @xref{Viewing}. - -@cindex buttons - -Attachments in MH-E are indicated by @dfn{buttons} like this: - -@smallexample -[1. image/jpeg; foo.jpg]... -@end smallexample - -@findex mh-next-button -@findex mh-press-button -@findex mh-prev-button -@kindex @key{RET} -@kindex K @key{TAB} -@kindex K S-@key{TAB} -@kindex Mouse-1 -@kindex Mouse-2 - -To view the contents of the button, use either @kbd{Mouse-1} or -@kbd{Mouse-2} on the button or @key{RET} (@code{mh-press-button}) when -the cursor is over the button. This command is a toggle so if you use -it again on the same attachment, it is hidden. If Emacs does not know -how to display the attachment, then Emacs offers to save the -attachment in a file. To move the cursor to the next button, use the -command @kbd{K @key{TAB}} (@code{mh-next-button}). If the end of the -buffer is reached then the search wraps over to the start of the -buffer. To move the cursor to the previous button, use the command -@kbd{K S-@key{TAB}} (@code{mh-prev-button}). If the beginning of the -buffer is reached then the search wraps over to the end of the buffer. - -@cindex attachments, viewing -@cindex viewing attachments -@findex mh-folder-toggle-mime-part -@kindex K v - -Another way to view the contents of a button is to use the command -@kbd{K v} (@code{mh-folder-toggle-mime-part}). This command displays -(or hides) the attachment associated with the button under the cursor. -If the cursor is not located over a button, then the cursor first -moves to the next button, wrapping to the beginning of the message if -necessary. This command has the advantage over the previous commands -of working from the MH-Folder buffer. You can also provide a numeric -prefix argument (as in @kbd{4 K v}) to view the attachment labeled -with that number. If Emacs does not know how to display the -attachment, then Emacs offers to save the attachment in a file. - -@cindex @file{/etc/mailcap} -@cindex files, @file{/etc/mailcap} -@findex mailcap-mime-info -@findex mh-display-with-external-viewer -@kindex K e - -If Emacs does not know how to view an attachment, you could save it -into a file and then run some program to open it. It is easier, -however, to launch the program directly from MH-E with the command -@kbd{K e} (@code{mh-display-with-external-viewer}). While you'll most -likely use this to view spreadsheets and documents, it is also useful -to use your browser to view HTML attachments with higher fidelity than -what Emacs can provide. This command displays the attachment -associated with the button under the cursor. If the cursor is not -located over a button, then the cursor first moves to the next button, -wrapping to the beginning of the message if necessary. You can provide -a numeric prefix argument (as in @kbd{4 K e}) to view the attachment -labeled with that number. This command tries to provide a reasonable -default for the viewer by calling the Emacs function -@code{mailcap-mime-info}. This function usually reads the file -@file{/etc/mailcap}. - -@cindex attachments, saving -@cindex saving attachments -@findex mh-folder-save-mime-part -@kindex K o - -Use the command @kbd{K o} (@code{mh-folder-save-mime-part}) to save -attachments (the mnemonic is ``output''). This command saves the -attachment associated with the button under the cursor. If the cursor -is not located over a button, then the cursor first moves to the next -button, wrapping to the beginning of the message if necessary. You can -also provide a numeric prefix argument (as in @kbd{3 K o}) to save the -attachment labeled with that number. This command prompts you for a -filename and suggests a specific name if it is available. - -@cindex @command{mhn} -@cindex @command{mhstore} -@cindex MH commands, @command{mhn} -@cindex MH commands, @command{mhstore} -@findex mh-mime-save-parts -@kindex K a -@vindex mh-mime-save-parts-default-directory - -You can save all of the attachments at once with the command @kbd{K a} -(@code{mh-mime-save-parts}). The attachments are saved in the -directory specified by the option -@code{mh-mime-save-parts-default-directory} unless you use a prefix -argument (as in @kbd{C-u K a}) in which case you are prompted for the -directory. These directories may be superseded by MH profile -components, since this function calls on @command{mhstore} -(@command{mhn}) to do the work. - -@vindex mh-mime-save-parts-default-directory - -The default value for the option -@code{mh-mime-save-parts-default-directory} is @samp{Prompt Always} so -that you are always prompted for the directory in which to save the -attachments. However, if you usually use the same directory within a -session, then you can set this option to @samp{Prompt the First Time} -to avoid the prompt each time. you can make this directory permanent -by choosing @samp{Directory} and entering the directory's name. - -@cindex attachments, inline -@cindex inline attachments -@findex mh-toggle-mime-buttons -@kindex K t -@vindex mh-display-buttons-for-inline-parts-flag - -The sender can request that attachments should be viewed inline so -that they do not really appear like an attachment at all to the -reader. Most of the time, this is desirable, so by default MH-E -suppresses the buttons for inline attachments. On the other hand, you -may receive code or HTML which the sender has added to his message as -inline attachments so that you can read them in MH-E. In this case, it -is useful to see the buttons so that you know you don't have to cut -and paste the code into a file; you can simply save the attachment. If -you want to make the buttons visible for inline attachments, you can -use the command @kbd{K t} (@code{mh-toggle-mime-buttons}) to toggle -the visibility of these buttons. You can turn on these buttons -permanently by turning on the option -@code{mh-display-buttons-for-inline-parts-flag}. - -MH-E cannot display all attachments inline however. It can display -text (including @sc{html}) and images. - -@cindex header field, @samp{Content-Disposition:} -@cindex inline images -@cindex @samp{Content-Disposition:} header field -@vindex mh-max-inline-image-height -@vindex mh-max-inline-image-width - -Some older mail programs do not insert the needed -plumbing@footnote{This plumbing is the @samp{Content-Disposition:} -header field.} to tell MH-E whether to display the attachments inline -or not. If this is the case, MH-E will display these images inline if -they are smaller than the window. However, you might want to allow -larger images to be displayed inline. To do this, you can change the -options @code{mh-max-inline-image-width} and -@code{mh-max-inline-image-height} from their default value of zero to -a large number. The size of your screen is a good choice for these -numbers. - -@cindex alternatives -@cindex attachments, alternatives -@vindex mh-display-buttons-for-alternatives-flag - -Sometimes, a mail program will produce multiple alternatives of an -attachment in increasing degree of faithfulness to the original -content. By default, only the preferred alternative is displayed. If -the option @code{mh-display-buttons-for-alternatives-flag} is on, then -the preferred part is shown inline and buttons are shown for each of -the other alternatives. - -@vindex mm-discouraged-alternatives - -Many people prefer to see the @samp{text/plain} alternative rather -than the @samp{text/html} alternative. To do this in MH-E, customize -the option @code{mm-discouraged-alternatives}, and add -@samp{text/html}. The next best alternative, if any, will be shown. - -@findex mh-show-preferred-alternative -@kindex : (colon) - -Occasionally, though, you might want to see the preferred alternative. -The command @kbd{:} (@code{mh-show-preferred-alternative}) displays -the message with the default preferred alternative. This is as if -@code{mm-discouraged-alternatives} is set to @samp{nil}. Use the -command @key{RET} (@code{mh-show}) to show the message normally again. - -@kindex K i -@findex mh-folder-inline-mime-part - -You can view the raw contents of an attachment with the command @kbd{K -i} (@code{mh-folder-inline-mime-part}). This command displays (or -hides) the contents of the attachment associated with the button under -the cursor verbatim. If the cursor is not located over a button, then -the cursor first moves to the next button, wrapping to the beginning -of the message if necessary. You can also provide a numeric prefix -argument (as in @kbd{4 K i}) to view the attachment labeled with that -number. - -For additional information on buttons, see -@ifinfo -@ref{Article Buttons,,,gnus}, and @ref{MIME Commands,,,gnus}. -@end ifinfo -@ifnotinfo -the chapters @uref{http://www.gnus.org/manual/gnus_101.html#SEC101, -Article Buttons} and -@uref{http://www.gnus.org/manual/gnus_108.html#SEC108, MIME Commands} -in the @cite{The Gnus Manual}. -@end ifnotinfo - -@node HTML, Digests, Viewing Attachments, Reading Mail -@section HTML - -@cindex HTML -@cindex Gnus - -MH-E can display messages that have been sent in HTML@footnote{This -feature depends on a version of Gnus that is at least 5.10.}. The -content of the message will appear in the MH-Show buffer as you would -expect if the entire message is HTML, or there is an inline HTML body -part. However, if there is an HTML body part that is an attachment, -then you'll see a button like this: - -@smallexample -[1. text/html; foo.html]... -@end smallexample - -To see how to read the contents of this body part, see @ref{Viewing -Attachments}. - -@vindex mm-text-html-renderer - -The browser that MH-E uses is determined by the option -@code{mm-text-html-renderer}. The default setting is set automatically -based upon the presence of a known browser on your system. If you wish -to use a different browser, then set this option accordingly. See the -documentation for the browser you use for additional information on -how to use it. In particular, find and disable the option to render -images as this can tip off spammers that the email address they have -used is valid. - -@vindex mm-text-html-renderer - -If you're confused about which @code{mm-text-html-renderer} to use, -here's a brief description of each, sorted by popularity, that -includes the results of a quick poll of MH-E users from 2005-12-23. - -@table @asis -@cindex browser, @samp{w3m} -@cindex @samp{w3m} -@kindex Mouse-2 -@item @samp{w3m} 7 -The @samp{w3m} browser requires an external program. It's quick, -produces pretty nice output, and best of all, it's the only browser -that highlights links. These can be clicked with @kbd{Mouse-2} to view -the content of the link in @samp{w3m}. The @samp{w3m} browser handles -tables well and actually respects the table's width parameter (which -can cause text to wrap if the author didn't anticipate that the page -would be viewed in Emacs). -@c ------------------------- -@cindex browser, @samp{w3m-standalone} -@cindex @samp{w3m-standalone} -@item @samp{w3m-standalone} 3 -This browser, along with @samp{nil} for the external browser, are the -only choices that work without having to download a separate lisp -package or external program. This browser is quick, but does not show -links. It handles simple tables but some tables get rendered much -wider than the Emacs frame. This browser was the only one not to -handle the escape @samp{–} (it printed a @samp{?}), but it did -render @samp{®}. -@c ------------------------- -@cindex browser, @samp{links} -@cindex @samp{links} -@item @samp{links} 1 -The @samp{links} browser requires an external program. It's quick, and -produces nicer output than @samp{lynx} on single column mails in -tables. However, it doesn't show links and it doesn't do as nice a job -on multi-column tables as some lines wrap. At least it fits in 80 -columns and thus seems better than @samp{w3} and -@samp{w3m-standalone}. Converts escapes such as @samp{®} to (R). -@c ------------------------- -@cindex browser, @samp{lynx} -@cindex @samp{lynx} -@item @samp{lynx} 1 -The @samp{lynx} browser requires an external program. It's quick and -produces pretty decent output but it doesn't show links. It doesn't -seem to do multi-column tables which makes output much cleaner. It -centers the output and wraps long lines more than most. Handles -@samp{®}. -@c ------------------------- -@item @samp{nil} 1 -This choice obviously requires an external browser. Like -@samp{w3m-standalone}, it works out of the box. With this setting, -HTML messages have a button for the body part which you can view with -@kbd{K v} (@code{mh-folder-toggle-mime-part}). -@c ------------------------- -@cindex browser, @samp{w3} -@cindex @samp{w3} -@item @samp{w3} 0 -This choice does not require an external program as all of the -rendering is done in lisp. You do need to get the package separately. -This browser is @strong{slow}, and doesn't appear to have been updated -since 2001 and the author hasn't responded to my emails. It displays -unknown tags instead of hiding them, so you get to see all the -Microsoft crap in certain messages. Tends to make multi-column tables -wider than even a full-screen Emacs can handle. Like @samp{w3m}, you -can follow links, but you have to find them first as they are not -highlighted. Performs well on single-column tables and handles escapes -such as @samp{®}. -@c ------------------------- -@cindex browser, @samp{html2text} -@cindex @samp{html2text} -@item @samp{html2text} 0 -The @samp{html2text} browser requires an external program. I noticed -that it can do some nasty things with simple HTML mails (like filling -the entire message as if it were one paragraph, including signature). -On another message, it displayed half of the HTML tags for some -reason. -@end table - -@vindex mm-text-html-renderer - -For a couple more sources of information about -@code{mm-text-html-renderer}, -@ifinfo -@xref{Display Customization,,,emacs-mime}, and the documentation for -the Gnus command @kbd{W h} (@pxref{Article Washing,,,gnus},). -@end ifinfo -@ifnotinfo -see section @uref{http://www.gnus.org/manual/emacs-mime_6.html, -Display Customization} in the @cite{The Emacs MIME Manual} and the -documentation for the Gnus command @kbd{W h} (see section -@uref{http://www.gnus.org/manual/gnus_99.html, Article Washing} in the -@cite{The Gnus Manual}). -@end ifnotinfo - -@cindex @file{.emacs} -@cindex files, @file{.emacs} -@findex browse-url-at-mouse -@kindex S-Mouse-2 - -A useful key binding that you can add to @file{~/.emacs} is the -following which displays an HTML link or textual URL in an external -browser when clicked with @kbd{S-mouse-2}. This binding works in any -buffer, including HTML buffers. - -@smalllisp -(global-set-key [S-mouse-2] 'browse-url-at-mouse) -@end smalllisp - -@node Digests, Reading PGP, HTML, Reading Mail -@section Digests - -@cindex digests -@findex mh-page-digest -@findex mh-page-digest-backwards -@kindex D @key{BS} -@kindex D @key{SPC} -@kindex @key{BS} -@kindex @key{SPC} - -A digest is a message that contains other messages. Special MH-E -commands let you read digests conveniently. You can use @key{SPC} and -@key{BS} to page through the digest as if it were a normal message, -but if you wish to skip to the next message in the digest, use -@kbd{D @key{SPC}} (@code{mh-page-digest}). To return to a previous message, -use @kbd{D @key{BS}} (@code{mh-page-digest-backwards}). - -@cindex @command{burst} -@cindex MH commands, @command{burst} -@cindex MH-Folder Show mode -@cindex modes, MH-Folder Show -@findex mh-burst-digest -@kindex d -@kindex D b -@kindex t - -Another handy command is @kbd{D b} (@code{mh-burst-digest}). This -command uses the MH command @command{burst}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/burdig.html, Bursting Messages} in the MH -book.} to break out each message in the digest into its own message. -Using this command, you can quickly delete unwanted messages, like -this: Once the digest is split up, toggle out of MH-Folder Show mode -with @kbd{t} (@pxref{Folders}) so that the scan lines fill the screen -and messages aren't displayed. Then use @kbd{d} (@pxref{Reading Mail}) -to quickly delete messages that you don't want to read (based on the -@samp{Subject:} header field). You can also burst the digest to reply -directly to the people who posted the messages in the digest. One -problem you may encounter is that the @samp{From:} header fields are -preceded with a @samp{>} so that your reply can't create the -@samp{To:} field correctly. In this case, you must correct the -@samp{To:} field yourself. This is described later (@pxref{Editing -Drafts}). - -@node Reading PGP, Printing, Digests, Reading Mail -@section Signed and Encrypted Messages - -@cindex GPG -@cindex GnuPG -@cindex Gnus -@cindex OpenPGP -@cindex PGP -@cindex RFC 3156 -@cindex encrypted messages -@cindex security -@cindex signed messages - -You can read encrypted or signed PGP or GPG messages with -MH-E@footnote{This feature depends on post-5.10 versions of Gnus. -@cite{MIME Security with OpenPGP} is documented in -@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. However, -MH-E can also decrypt old-style PGP messages that are not in MIME -format.}. This section assumes that you already have a good -understanding of GPG and have set up your keys appropriately. - -If someone sends you a signed message, here is what you'll see: - -@smallexample -@group -[[PGP Signed Part:Bill Wohler ]] -This is a signed message. - -[[End of PGP Signed Part]] -@end group -@end smallexample - -@cindex keychain -@cindex key server -@cindex signed messages - -If the key for the given signature is not in your keychain, you'll be -given the opportunity to fetch the key from a key server and verify -the key. If the message is really large, the verification process can -take a long time. You can press @kbd{C-g} at any time to -cancel@footnote{Unfortunately in the current version, the validation -process doesn't display a message so it appears that MH-E has hung. We -hope that this will be fixed in the future.}. - -If the signature doesn't check out, you might see something like this: - -@smallexample -@group -[[PGP Signed Part:Failed]] -This is a signed message. -This is garbage added after the signature was made. - -[[End of PGP Signed Part]] -@end group -@end smallexample - -@cindex decrypting messages - -If someone sends you an encrypted message, MH-E will ask for your -passphrase to decrypt the message. You should see something like this: - -@smallexample -@group -[[PGP Encrypted Part:OK]] - -[[PGP Signed Part:Bill Wohler ]] -This is the secret message. - -[[End of PGP Signed Part]] - -[[End of PGP Encrypted Part]] -@end group -@end smallexample - -If there is a problem decrypting the message, the button will say: - -@smallexample -[[PGP Encrypted Part:Failed]] -@end smallexample - -You can read the contents of this button using the methods described in -@ref{Viewing Attachments}. If the message were corrupted, you'd see -this: - -@smallexample -[[PGP Encrypted Part:Failed] -Invalid base64 data] -@end smallexample - -If your passphrase were incorrect, you'd see something like this: - -@smallexample -[GNUPG:] ENC_TO CD9C88BB610BD9AD 1 0 -[GNUPG:] USERID_HINT CD9C88BB610BD9AD Bill Wohler -[GNUPG:] NEED_PASSPHRASE CD9C88BB610BD9AD CD9C88BB610BD9AD 1 0 -[GNUPG:] BAD_PASSPHRASE CD9C88BB610BD9AD -gpg: encrypted with 1024-bit RSA key, ID 610BD9AD, created 1997-09-09 - "Bill Wohler " -gpg: public key decryption failed: bad passphrase -[GNUPG:] BEGIN_DECRYPTION -[GNUPG:] DECRYPTION_FAILED -gpg: decryption failed: secret key not available -[GNUPG:] END_DECRYPTION - -gpg exited abnormally: '2' -@end smallexample - -@vindex mh-show-pgg-bad -@vindex mh-show-pgg-good -@vindex mh-show-pgg-unknown - -The appearance of the buttons is controlled by the faces -@code{mh-show-pgg-good}, @code{mh-show-pgg-bad}, and -@code{mh-show-pgg-unknown} depending on the validity of the signature. -The latter is used whether the signature is unknown or untrusted. - -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - -@node Printing, Files and Pipes, Reading PGP, Reading Mail -@section Printing Your Mail - -@cindex printing -@findex mh-ps-print-msg -@findex mh-ps-print-msg-file -@kindex P f -@kindex P p -@vindex mh-lpr-command-format -@vindex mh-print-background-flag - -To print messages in MH-E, use the command @kbd{P p} -(@code{mh-ps-print-msg}). You can print all the messages in a range -(as in @kbd{C-u P p 1 3 5-7 last:5 frombob @key{RET}}, -@pxref{Ranges}). You can also send the output to a file with @kbd{P f} -(@code{mh-ps-print-msg-file}). This command will print inline text -attachments but will not decrypt messages. However, when a message is -displayed in an MH-Show buffer, then that buffer is used verbatim for -printing with the caveat that only text attachments, if opened inline, -are printed. Therefore, encrypted messages can be printed by showing -and decrypting them first. The commands @kbd{P p} and @kbd{P f} do not -use the options @code{mh-lpr-command-format} or -@code{mh-print-background-flag}, described below. - -@findex mh-ps-print-toggle-color -@kindex P C -@vindex ps-print-color-p - -Colors are emulated on black-and-white printers with shades of gray. -This might produce illegible output, even if your screen colors only -use shades of gray. If this is the case, try using the command @kbd{P -C} (@code{mh-ps-print-toggle-color}) to toggle between color, no -color, and a black and white representation of the colors and see -which works best. You change this setting permanently by customizing -the option @code{ps-print-color-p}. - -@findex mh-ps-print-toggle-faces -@kindex P F - -Another related function is the command @kbd{P F} -(@code{mh-ps-print-toggle-faces}). This command toggles between using -faces and not. When faces are enabled, the printed message will look -very similar to the message in the MH-Show buffer. - -@cindex ps-print package -@cindex Emacs, packages, ps-print - -MH-E uses the @samp{ps-print} package to do the printing, so you can -customize the printing further by going to the @samp{ps-print} -customization group. - -@cindex @command{lpr} -@cindex @command{mhl} -@cindex MH commands, @command{mhl} -@cindex Unix commands, @command{lpr} -@findex mh-print-msg -@kindex P l - -An alternative to using the @samp{ps-print} package is the command -@kbd{P l} (@code{mh-print-msg}) (the @i{l} is for @i{l}ine printer or -@i{l}pr). You can print all the messages in a range. The message is -formatted with @command{mhl}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH -book.} and printed with the @command{lpr} command. - -@kindex P f -@kindex P l -@kindex P p -@vindex mh-lpr-command-format -@vindex mh-print-background-flag - -The command @kbd{P l} uses two options. The option -@code{mh-lpr-command-format} contains the Unix command line which -performs the actual printing. The string can contain one escape, -@samp{%s}, which is replaced by the name of the folder and the message -number and is useful for print job names. The default setting is -@code{"lpr -J '%s'"}. I use @code{"mpage -h'%s' -b Letter -H1of -mlrtb --P"} which produces a nice header and adds a bit of margin so the text -fits within my printer's margins. Normally messages are printed in the -foreground. If this is slow on your system, you may elect to turn on -the option @code{mh-print-background-flag} to print in the background. -If you do this, do not delete the message until it is printed or else -the output may be truncated. These options are not used by the -commands @kbd{P p} or @kbd{P f}. - -@node Files and Pipes, Navigating, Printing, Reading Mail -@section Files and Pipes - -@cindex files -@cindex pipes -@findex mh-refile-or-write-again -@findex mh-write-msg-to-file -@kindex > -@kindex ! - -MH-E does offer a couple of commands that are not a part of MH@. The -first one, @kbd{>} (@code{mh-write-msg-to-file}), writes a message to -a file. You are prompted for the filename. If the file already exists, -the message is appended to it. You can also write the message to the -file without the header by specifying a prefix argument (such as -@kbd{C-u > /tmp/foobar @key{RET}}). Subsequent writes to the same file -can be made with the command @kbd{!} -(@code{mh-refile-or-write-again}). - -@findex mh-pipe-msg -@kindex | -@kindex l - -You can also pipe the message through a Unix shell command with the -command @kbd{|} (@code{mh-pipe-msg}). You are prompted for the Unix -command through which you wish to run your message. If you give a -prefix argument to this command, the message header is included in the -text passed to the command (the contrived example @kbd{C-u | lpr} -would be done with the @kbd{l} command instead). - -@cindex @command{shar} -@cindex @command{uuencode} -@cindex Unix commands, @command{shar} -@cindex Unix commands, @command{uuencode} -@findex mh-store-msg -@kindex X s -@vindex mh-store-default-directory - -If the message is a shell archive @command{shar} or has been run -through @command{uuencode} use @kbd{X s} (@code{mh-store-msg}) to -extract the body of the message. The default directory for extraction -is the current directory; however, you have a chance to specify a -different extraction directory. The next time you use this command, -the default directory is the last directory you used. If you would -like to change the initial default directory, customize the option -@code{mh-store-default-directory}, change the value from -@samp{Current} to @samp{Directory}, and then enter the name of the -directory for storing the content of these messages. - -@findex mh-store-buffer -@kindex @key{RET} -@kindex X s - -By the way, @kbd{X s} calls the Emacs Lisp function -@code{mh-store-buffer}. I mention this because you can use it directly -if you're editing a buffer that contains a file that has been run -through @command{uuencode} or @command{shar}. For example, you can -extract the contents of the current buffer in your home directory by -typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}. - -@node Navigating, Miscellaneous Commands and Options, Files and Pipes, Reading Mail -@section Navigating - -@cindex moving between messages -@cindex navigation -@findex mh-first-msg -@findex mh-goto-msg -@findex mh-last-msg -@findex mh-next-undeleted-msg -@findex mh-next-unread-msg -@findex mh-previous-undeleted-msg -@findex mh-previous-unread-msg -@kindex g -@kindex M-< -@kindex M-> -@kindex M-n -@kindex M-p -@kindex n -@kindex p - -To move on to the next message, use the command @kbd{n} -(@code{mh-next-undeleted-msg}); use @kbd{p} -(@code{mh-previous-undeleted-msg}) to read the previous message. To -move to the next unread message, use @kbd{M-n} -(@code{mh-next-unread-msg}); use @kbd{M-p} -(@code{mh-previous-unread-msg}) to move to the previous unread -message. These commands can be given a prefix argument to specify how -many messages to skip (for example, @kbd{5 n}). You can also move to a -specific message with @kbd{g} (@code{mh-goto-msg}). You can enter the -message number either before or after typing @kbd{g}. In the latter -case, Emacs prompts you. Finally, you can go to the first or last -message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->} -(@code{mh-last-msg}) respectively. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@findex next-line -@findex previous-line -@kindex C-n -@kindex C-p -@kindex @key{RET} - -You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) -and @kbd{C-n} (@code{next-line}) to move up and down the scan lines in -the MH-Folder window. These commands can be used in conjunction with -@key{RET} to look at deleted or refiled messages. - -@cindex deleting messages -@findex mh-delete-msg -@kindex d -@kindex n -@kindex p - -To mark a message for deletion, use the command @kbd{d} -(@code{mh-delete-msg}). A @samp{D} is placed by the message in the -scan window, and the next undeleted message is displayed. If the -previous command had been @kbd{p}, then the next message displayed is -the first undeleted message previous to the message just deleted. Use -@kbd{n} to force subsequent @kbd{d} commands to move forward to the -next undeleted message after deleting the message under the cursor. -You may also specify a range (for example, @kbd{C-u d 1 3 5-7 last:5 -frombob @key{RET}}, @pxref{Ranges}). - -@findex mh-delete-msg-no-motion -@kindex C-d - -The command @kbd{C-d} (@code{mh-delete-msg-no-motion}) marks the -message (or messages in range) for deletion but leaves the cursor at -the current message in case you wish to perform other operations on -the message. - -@findex mh-delete-subject -@findex mh-delete-subject-or-thread -@findex mh-thread-delete -@findex mh-undo -@kindex k -@kindex T d -@kindex u - -And to delete more messages faster, you can use @kbd{k} -(@code{mh-delete-subject-or-thread}) to delete all the messages with -the same subject as the current message. This command puts these -messages in a sequence named @samp{subject}. You can undo this action -by using @kbd{u} (@code{mh-undo}) with a prefix argument and then -specifying the @samp{subject} sequence. However, if the buffer is -displaying a threaded view of the folder then @kbd{k} behaves like -@kbd{T d} (@code{mh-thread-delete}). @xref{Threading}. - -@findex mh-execute-commands -@kindex x - -However you mark a message for deletion, the command @kbd{x} -(@code{mh-execute-commands}) actually carries out the deletion -(@pxref{Folders}). - -@vindex mh-delete-msg-hook - -The hook @code{mh-delete-msg-hook} is called after you mark a message -for deletion. For example, a past maintainer of MH-E used this once -when he kept statistics on his mail usage. - -@node Miscellaneous Commands and Options, , Navigating, Reading Mail -@section Miscellaneous Commands and Options - -This section contains a few more miscellaneous commands and options. - -@cindex editing message -@findex mh-modify -@kindex M - -There are times when you need to edit a message. For example, you may -need to fix a broken Content-Type header field. You can do this with -the command @kbd{M} (@code{mh-modify}). It displays the raw message in -an editable buffer. When you are done editing, save and kill the -buffer as you would any other. - -@findex mh-kill-folder -@findex mh-pack-folder -@vindex mh-do-not-confirm-flag - -Commands such as @code{mh-pack-folder} prompt to confirm whether to -process outstanding moves and deletes or not before continuing. -Turning on the option @code{mh-do-not-confirm-flag} means that these -actions will be performed---which is usually desired but cannot be -retracted---without question@footnote{In previous versions of MH-E, -this option suppressed the confirmation in @code{mh-kill-folder}. -Since this kept most users from setting this option, -@code{mh-kill-folder} was modified in version 6.0 to always ask for -confirmation subject to @code{mh-kill-folder-suppress-prompt-hook}. -@xref{Folders}.}. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@vindex mh-summary-height - -The option @code{mh-summary-height} controls the number of scan lines -displayed in the MH-Folder window, including the mode line. The -default value of this option is @samp{Automatic} which means that the -MH-Folder buffer will maintain the same proportional size if the frame -is resized. If you'd prefer a fixed height, then choose the -@samp{Fixed Size} option and enter the number of lines you'd like to -see. - -@vindex mh-bury-show-buffer-flag - -Normally the buffer for displaying messages is buried at the bottom at -the buffer stack. You may wish to disable this feature by turning off -the option @code{mh-bury-show-buffer-flag}. One advantage of not -burying the show buffer is that one can delete the show buffer more -easily in an electric buffer list because of its proximity to its -associated MH-Folder buffer. Try running @kbd{M-x -electric-buffer-list} to see what I mean. - -@cindex @file{.emacs} -@cindex files, @file{.emacs} -@cindex reading mail - -Before we leave this section, I'll include a function that I use as a -front end to MH-E@footnote{Stephen Gildea's favorite binding is -@kbd{(global-set-key "\C-cr" 'mh-rmail)}.}. It toggles between your -working window configuration, which may be quite involved---windows -filled with source, compilation output, man pages, and other -documentation---and your MH-E window configuration. Like the rest of -the customization described in this section, simply add the following -code to @file{~/.emacs}. - -@iftex -@filbreak -@end iftex - -@findex mh-rmail, example - -@smalllisp -@group -(defvar my-mh-screen-saved nil - "Set to non-@code{nil} when MH-E window configuration shown.") -(defvar my-normal-screen nil "Normal window configuration.") -(defvar my-mh-screen nil "MH-E window configuration.") - -(defun my-mh-rmail (&optional arg) - "Toggle between MH-E and normal screen configurations. -With non-@code{nil} or prefix argument, @i{inc} mailbox as well -when going into mail." - (interactive "P") ; @r{user callable function, P=prefix arg} - (setq my-mh-screen-saved ; @r{save state} - (cond - ;; @r{Bring up MH-E screen if arg or normal window configuration.} - ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.} - ((or arg (null my-mh-screen-saved)) - (setq my-normal-screen (current-window-configuration)) - (if (or arg (null (get-buffer "+inbox"))) - (mh-rmail) - (set-window-configuration my-mh-screen)) - t) ; @r{set my-mh-screen-saved to @code{t}} - ;; @r{Otherwise, save MH-E screen and restore normal screen.} - (t - (setq my-mh-screen (current-window-configuration)) - (set-window-configuration my-normal-screen) - nil)))) ; @r{set my-mh-screen-saved to nil} - -(global-set-key "\C-x\r" 'my-mh-rmail) ;@r{ call with C-x @key{RET}} - -@i{Starting MH-E} - -@end group -@end smalllisp - -If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved} is -@code{nil} (meaning a non-MH-E window configuration), the current -window configuration is saved, either the @samp{+inbox} buffer is -displayed or @code{mh-rmail} is run, and the MH-E window configuration -is shown. Otherwise, the MH-E window configuration is saved and the -original configuration is displayed. - -@node Folders, Sending Mail, Reading Mail, Top -@chapter Organizing Your Mail with Folders - -@cindex @samp{Folder} menu -@cindex @samp{Message} menu -@cindex folders -@cindex menu, @samp{Folder} -@cindex menu, @samp{Message} -@cindex using folders - -This chapter discusses the things you can do with folders within MH-E. -The commands in this chapter are also found in the @samp{Folder} and -@samp{Message} menus. - -@table @kbd -@kindex ? -@findex mh-help -@item ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@kindex ! -@findex mh-refile-or-write-again -@item ! -Repeat last output command (@code{mh-refile-or-write-again}). -@c ------------------------- -@cindex @samp{Message > Copy Message to Folder...} menu item -@cindex menu item, @samp{Message > Copy Message to Folder...} -@kindex c -@findex mh-copy-msg -@item c -Copy range to folder (@code{mh-copy-msg}). -@c ------------------------- -@kindex F ? -@findex mh-prefix-help -@item F ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex F ' -@findex mh-index-ticked-messages -@item F ' -Display ticked messages (@code{mh-index-ticked-messages}). -@c ------------------------- -@kindex F c -@findex mh-catchup -@item F c -Delete range from the @samp{unseen} sequence (@code{mh-catchup}). -@c ------------------------- -@kindex F k -@findex mh-kill-folder -@item F k -Remove folder (@code{mh-kill-folder}). -@c ------------------------- -@cindex @samp{Folder > List Folders} menu item -@cindex menu item, @samp{Folder > List Folders} -@kindex F l -@findex mh-list-folders -@item F l -List all folders (@code{mh-list-folders}). -@c ------------------------- -@cindex @samp{Folder > View New Messages} menu item -@cindex menu item, @samp{Folder > View New Messages} -@kindex F n -@findex mh-index-new-messages -@item F n -Display unseen messages (@code{mh-index-new-messages}). -@c ------------------------- -@cindex @samp{Folder > Pack Folder} menu item -@cindex menu item, @samp{Folder > Pack Folder} -@kindex F p -@findex mh-pack-folder -@item F p -Pack folder (@code{mh-pack-folder}). -@c ------------------------- -@kindex F q -@findex mh-index-sequenced-messages -@item F q -Display messages in any sequence (@code{mh-index-sequenced-messages}). -@c ------------------------- -@cindex @samp{Folder > Rescan Folder} menu item -@cindex menu item, @samp{Folder > Rescan Folder} -@kindex F r -@findex mh-rescan-folder -@item F r -Rescan folder (@code{mh-rescan-folder}). -@c ------------------------- -@cindex @samp{Folder > Search...} menu item -@cindex menu item, @samp{Folder > Search...} -@kindex F s -@findex mh-search -@item F s -Search your MH mail (@code{mh-search}). -@c ------------------------- -@cindex @samp{Folder > Sort Folder} menu item -@cindex menu item, @samp{Folder > Sort Folder} -@kindex F S -@findex mh-sort-folder -@item F S -Sort folder (@code{mh-sort-folder}). -@c ------------------------- -@kindex F u -@findex mh-undo-folder -@item F u -Undo all refiles and deletes in the current folder (@code{mh-undo-folder}). -@c ------------------------- -@cindex @samp{Folder > Visit a Folder...} menu item -@cindex menu item, @samp{Folder > Visit a Folder...} -@kindex F v -@findex mh-visit-folder -@item F v -Visit folder (@code{mh-visit-folder}). -@c ------------------------- -@cindex @samp{Message > Refile Message} menu item -@cindex menu item, @samp{Message > Refile Message} -@kindex o -@findex mh-refile-msg -@item o -Refile (output) range into folder (@code{mh-refile-msg}). -@c ------------------------- -@cindex @samp{Folder > Quit MH-E} menu item -@cindex menu item, @samp{Folder > Quit MH-E} -@kindex q -@findex mh-quit -@item q -Quit the current MH-E folder (@code{mh-quit}). -@c ------------------------- -@cindex @samp{Folder > Toggle Show/Folder} menu item -@cindex menu item, @samp{Folder > Toggle Show/Folder} -@kindex t -@findex mh-toggle-showing -@item t -Toggle between MH-Folder and MH-Folder Show modes -(@code{mh-toggle-showing}). -@c ------------------------- -@cindex @samp{Message > Undo Delete/Refile} menu item -@cindex menu item, @samp{Message > Undo Delete/Refile} -@kindex u -@findex mh-undo -@item u -Undo pending deletes or refiles in range (@code{mh-undo}). -@c ------------------------- -@cindex @samp{Message > Execute Delete/Refile} menu item -@cindex menu item, @samp{Message > Execute Delete/Refile} -@kindex x -@findex mh-execute-commands -@item x -Process outstanding delete and refile requests -(@code{mh-execute-commands}). -@end table - -@cindex @samp{mh-folder} customization group -@cindex customization group, @samp{mh-folder} - -The @samp{mh-folder} customization group is used to tune these -commands. - -@vtable @code -@item mh-new-messages-folders -Folders searched for the @samp{unseen} sequence (default: -@code{Inbox}). -@c ------------------------- -@item mh-ticked-messages-folders -Folders searched for @code{mh-tick-seq} (default: @code{t}). -@c ------------------------- -@item mh-large-folder -The number of messages that indicates a large folder (default: 200). -@c ------------------------- -@item mh-recenter-summary-flag -On means to recenter the summary window (default: @samp{off}). -@c ------------------------- -@item mh-recursive-folders-flag -On means that commands which operate on folders do so recursively -(default: @samp{off}). -@c ------------------------- -@item mh-sortm-args -Additional arguments for @command{sortm} (default: @code{nil}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-after-commands-processed-hook -Hook run by @kbd{x} after performing outstanding refile and delete -requests (default: @code{nil}). -@c ------------------------- -@item mh-before-commands-processed-hook -Hook run by @kbd{x} before performing outstanding refile and delete -requests (default: @code{nil}). -@c ------------------------- -@item mh-before-quit-hook -Hook run by q before quitting MH-E (default: @code{nil}). -@c ------------------------- -@item mh-folder-mode-hook -Hook run by @code{mh-folder-mode} when visiting a new folder (default: -@code{nil}). -@c ------------------------- -@item mh-kill-folder-suppress-prompt-hook -Abnormal hook run at the beginning of @code{mh-kill-folder} (default: -@code{'mh-search-p}). -@c ------------------------- -@item mh-pack-folder-hook -Hook run by @code{mh-pack-folder} after renumbering the messages -(default: @code{nil}). -@c ------------------------- -@item mh-quit-hook -Hook run by q after quitting MH-E (default: @code{nil}). -@c ------------------------- -@item mh-refile-msg-hook -Hook run by o after marking each message for refiling (default: -@code{nil}). -@end vtable - -The following faces are available for customizing the appearance of -the MH-Folder buffer. @xref{Scan Line Formats}. - -@vtable @code -@item mh-folder-address -Recipient face. -@c ------------------------- -@item mh-folder-body -Body text face. -@c ------------------------- -@item mh-folder-cur-msg-number -Current message number face. -@c ------------------------- -@item mh-folder-date -Date face. -@c ------------------------- -@item mh-folder-deleted -Deleted message face. -@c ------------------------- -@item mh-folder-followup -@samp{Re:} face. -@c ------------------------- -@item mh-folder-msg-number -Message number face. -@c ------------------------- -@item mh-folder-refiled -Refiled message face. -@c ------------------------- -@vindex mh-scan-format-nmh -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-folder-sent-to-me-hint -Fontification hint face in messages sent directly to us. The detection -of messages sent to us is governed by the scan format -@code{mh-scan-format-nmh} and regular expression -@code{mh-scan-sent-to-me-sender-regexp}. -@c ------------------------- -@vindex mh-scan-format-nmh -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-folder-scan-format -Sender face in messages sent directly to us. The detection of messages -sent to us is governed by the scan format @code{mh-scan-format-nmh} -and regular expression @code{mh-scan-sent-to-me-sender-regexp}. -@c ------------------------- -@item mh-folder-subject -Subject face. -@c ------------------------- -@item mh-folder-tick -Ticked message face. -@c ------------------------- -@item mh-folder-to -@samp{To:} face. -@end vtable - -@vindex mh-folder-mode-hook - -The hook @code{mh-folder-mode-hook} is called when visiting a new -folder in MH-Folder mode. This could be used to set your own key -bindings, for example: - -@vindex mh-folder-mode-hook, example - -@smalllisp -@group -(defvar my-mh-init-done nil - "Non-@code{nil} when one-time MH-E settings made.") - -(defun my-mh-folder-mode-hook () - "Hook to set key bindings in MH-Folder mode." - (if (not my-mh-init-done) ; @r{only need to bind the keys once } - (progn - (local-set-key "//" 'my-search-msg) - (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}} - (setq my-mh-init-done t)))) - -(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook) - -(defun my-search-msg () - "Search for a regexp in the current message." - (interactive) ; @r{user function} - (save-window-excursion - (other-window 1) ; @r{go to next window} - (isearch-forward-regexp))) ; @r{string search; hit return} - ; @r{ when done} - -@i{Create additional key bindings via mh-folder-mode-hook} - -@end group -@end smalllisp - -@cindex @command{folder} -@cindex @command{refile} -@cindex MH commands, @command{folder} -@cindex MH commands, @command{refile} -@findex mh-refile-msg -@kindex o -@vindex mh-refile-msg-hook - -MH-E has analogies for each of the MH @command{folder} and -@command{refile} commands@footnote{See the sections -@uref{@value{MH-BOOK-HOME}/fol.html#Youfol, Your Current Folder: -folder} and @uref{@value{MH-BOOK-HOME}/fol.html#Movref, Moving and -Linking Messages: refile} in the MH book.}. To refile a message in -another folder, use the command @kbd{o} (@code{mh-refile-msg}) -(mnemonic: ``output''). You are prompted for the folder name -(@pxref{Folder Selection}). Note that this command can also be used to -create folders. If you specify a folder that does not exist, you will -be prompted to create it. The hook @code{mh-refile-msg-hook} is called -after a message is marked to be refiled. - -@findex mh-write-msg-to-file -@kindex ! - -If you are refiling several messages into the same folder, you can use -the command @kbd{!} (@code{mh-refile-or-write-again}) to repeat the -last refile or write (for the description of @kbd{>} -(@code{mh-write-msg-to-file}), @pxref{Files and Pipes}). You can use a -range in either case (for example, @kbd{C-u o 1 3 5-7 last:5 frombob -@key{RET}}, @pxref{Ranges}). - -@cindex expunging refiles and deletes -@cindex undoing refiles and deletes -@findex mh-undo -@kindex u - -If you've deleted a message or refiled it, but changed your mind, you -can cancel the action before you've executed it. Use @kbd{u} -(@code{mh-undo}) to undo a refile on or deletion of a single message. -You can also undo refiles and deletes for messages that are found in a -given range (@pxref{Ranges}). - -@findex mh-undo-folder -@kindex F u - -Alternatively, you can use @kbd{F u} (@code{mh-undo-folder}) to undo -all refiles and deletes in the current folder. - -@findex mh-execute-commands -@kindex x - -If you've marked messages to be deleted or refiled and you want to go -ahead and delete or refile the messages, use @kbd{x} -(@code{mh-execute-commands}). Many MH-E commands that may affect the -numbering of the messages (such as @kbd{F r} or @kbd{F p}) will ask if -you want to process refiles or deletes first and then either run -@kbd{x} for you or undo the pending refiles and deletes. - -@kindex x -@vindex mh-after-commands-processed-hook -@vindex mh-before-commands-processed-hook -@vindex mh-current-folder - -The command @kbd{x} runs @code{mh-before-commands-processed-hook} -before the commands are processed and -@code{mh-after-commands-processed-hook} after the commands are -processed. Variables that are useful with the former hook include -@code{mh-delete-list} and @code{mh-refile-list} which can be used to -see which changes will be made to the current folder, -@code{mh-current-folder}. Variables that are useful with the latter -hook include @code{mh-folders-changed}, which lists which folders were -affected by deletes and refiles. This list will always include the -current folder @code{mh-current-folder}. - -@findex mh-copy-msg -@kindex c -@kindex o - -If you wish to copy a message to another folder, you can use the -command @kbd{c} (@code{mh-copy-msg}) (see the @option{-link} argument -to @command{refile}(1)). Like the command @kbd{o}, this command -prompts you for the name of the target folder and you can specify a -range (@pxref{Ranges}). Note that unlike the command @kbd{o}, the copy -takes place immediately. The original copy remains in the current -folder. - -@cindex junk mail -@cindex MH-Folder mode -@cindex MH-Folder Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Folder Show -@cindex spam -@findex mh-toggle-showing -@kindex t - -The command @kbd{t} (@code{mh-toggle-showing}) switches between -MH-Folder mode and MH-Folder Show mode@footnote{For you Emacs wizards, -this is implemented as an Emacs minor mode.}. MH-Folder mode turns off -the associated show buffer so that you can perform operations on the -messages quickly without reading them. This is an excellent way to -prune out your junk mail or to refile a group of messages to another -folder for later examination. - -@cindex MH-Folder mode -@cindex MH-Show mode -@cindex modes, MH-Folder -@cindex modes, MH-Show -@cindex moving between messages -@kindex t -@vindex mh-recenter-summary-flag - -When you use @kbd{t} to toggle from MH-Folder Show mode to MH-Folder -mode, the MH-Show buffer is hidden and the MH-Folder buffer is left -alone. Setting @code{mh-recenter-summary-flag} to a non-@code{nil} -value causes the toggle to display as many scan lines as possible, -with the cursor at the middle. The effect of -@code{mh-recenter-summary-flag} is rather useful, but it can be -annoying on a slow network connection. - -@findex mh-visit-folder -@kindex F v -@vindex mh-large-folder - -When you want to read the messages that you have refiled into folders, -use the command @kbd{F v} (@code{mh-visit-folder}) to visit the -folder. You are prompted for the folder name. The folder buffer will -show just unseen messages if there are any; otherwise, it will show -all the messages in the buffer as long there are fewer than -@code{mh-large-folder} messages. If there are more, then you are -prompted for a range of messages to scan. You can provide a prefix -argument in order to specify a range of messages to show when you -visit the folder (@pxref{Ranges}). In this case, regions are not used -to specify the range and @code{mh-large-folder} is ignored. Note that -this command can also be used to create folders. If you specify a -folder that does not exist, you will be prompted to create it. - -@findex mh-search -@kindex F s - -If you forget where you've refiled your messages, you can find them -using @kbd{F s} (@code{mh-search}). @xref{Searching}. - -@cindex @command{procmail} -@cindex @samp{unseen} sequence -@cindex sequence, @samp{unseen} -@cindex Unix commands, @command{procmail} -@cindex unseen messages, viewing -@findex mh-index-new-messages -@kindex F n -@vindex mh-new-messages-folders - -If you use a program such as @command{procmail} to file your incoming -mail automatically, you can display new, unseen, messages using the -command @kbd{F n} (@code{mh-index-new-messages}). All messages in the -@samp{unseen} sequence from the folders in -@code{mh-new-messages-folders} are listed. However, this list of -folders can be overridden with a prefix argument: with a prefix -argument, enter a space-separated list of folders, or nothing to -search all folders. - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticked messages, viewing -@findex mh-index-ticked-messages -@kindex F ' -@vindex mh-ticked-messages-folders - -If you have ticked messages (@pxref{Sequences}), you can display them -using the command @kbd{F '} (@code{mh-index-ticked-messages}). All -messages in the @samp{tick} sequence from the folders in -@code{mh-ticked-messages-folders} are listed. With a prefix argument, -enter a space-separated list of folders, or nothing to search all -folders. - -@findex mh-index-sequenced-messages -@kindex F q -@vindex mh-new-messages-folders - -You can display messages in any sequence with the command @kbd{F q} -(@code{mh-index-sequenced-messages}). All messages from the folders in -@code{mh-new-messages-folders} in the sequence you provide are listed. -With a prefix argument, enter a space-separated list of folders at the -prompt, or nothing to search all folders. - -@vindex mh-new-messages-folders -@vindex mh-recursive-folders-flag -@vindex mh-ticked-messages-folders - -Set the options @code{mh-new-messages-folders} and -@code{mh-ticked-messages-folders} to @samp{Inbox} to search the -@samp{+inbox} folder or @samp{All} to search all of the top level -folders. Otherwise, list the folders that should be searched with the -@samp{Choose Folders} menu item. See @code{mh-recursive-folders-flag}. - -@cindex buffers, @samp{*MH-E Folders*} -@cindex @samp{*MH-E Folders*} -@findex mh-kill-folder -@findex mh-list-folders -@findex mh-pack-folder -@findex mh-rescan-folder -@findex mh-sort-folder -@kindex F k -@kindex F l -@kindex F p -@kindex F r -@kindex F S - -Other commands you can perform on folders include: @kbd{F l} -(@code{mh-list-folders}), to place a listing of all the folders in -your mail directory in a buffer called @samp{*MH-E Folders*} -(@pxref{Miscellaneous}); @kbd{F k} (@code{mh-kill-folder}), to remove -a folder; @kbd{F S} (@code{mh-sort-folder}), to sort the messages by -date (see @command{sortm}(1) to see how to sort by other criteria); -@kbd{F p} (@code{mh-pack-folder}), to pack a folder, removing gaps -from the numbering sequence; and @kbd{F r} (@code{mh-rescan-folder}), -to rescan the folder, which is useful to grab all messages in your -@samp{+inbox} after processing your new mail for the first time. If -you don't want to rescan the entire folder, the commands @kbd{F r} or -@kbd{F p} will accept a range (@pxref{Ranges}). - -@kindex F p -@vindex mh-pack-folder-hook - -The command @kbd{F p} runs @code{mh-pack-folder-hook} after -renumbering the messages. A variable that is useful with this hook -is @code{mh-current-folder}. - -@kindex @key{TAB} -@vindex mh-recursive-folders-flag - -By default, operations on folders work only one level at a time. Set -@code{mh-recursive-folders-flag} to non-@code{nil} to operate on all -folders. This mostly means that you'll be able to see all your folders -when you press @key{TAB} when prompted for a folder name. - -@findex mh-search-p -@kindex k -@vindex mh-kill-folder-suppress-prompt-hooks - -The hook @code{mh-kill-folder-suppress-prompt-hooks} is an abnormal -hook run at the beginning of the command @kbd{k}. The hook functions -are called with no arguments and should return a non-nil value to -suppress the normal prompt when you remove a folder. This is useful -for folders that are easily regenerated. The default value of -@code{mh-search-p} suppresses the prompt on folders generated by -searching. - -@sp 1 -@center @strong{NOTE} - -@quotation -Use this hook with care. If there is a bug in your hook which returns -@code{t} on @samp{+inbox} and you press @kbd{k} by accident in the -@code{+inbox} folder, you will not be happy. -@end quotation -@sp 1 - -@cindex @command{sortm} -@cindex @file{.mh_profile} -@cindex files, @file{.mh_profile} -@cindex MH commands, @command{sortm} -@cindex MH profile component, @samp{sortm:} -@cindex @samp{sortm:} MH profile component -@kindex F S -@vindex mh-sortm-args - -The option @code{mh-sortm-args} holds extra arguments to pass on to -the command @command{sortm}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sorsor.html, Sorting Messages: sortm} in the -MH book.} when a prefix argument is used with @kbd{F S}. Normally -default arguments to @command{sortm} are specified in the MH profile. -This option may be used to provide an alternate view. For example, -@samp{'(\"-nolimit\" \"-textfield\" \"subject\")} is a useful setting. - -@cindex exiting -@cindex quitting -@findex mh-quit -@kindex q - -When you want to quit using MH-E and go back to editing, you can use -the @kbd{q} (@code{mh-quit}) command. This buries the buffers of the -current MH-E folder and restores the buffers that were present when -you first ran @kbd{M-x mh-rmail}. It also removes any MH-E working -buffers whose name begins with @samp{ *mh-} or @samp{*MH-E } -(@pxref{Miscellaneous}). You can later restore your MH-E session by -selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} -again. - -@findex mh-execute-commands -@kindex q -@vindex mh-before-quit-hook -@vindex mh-before-quit-hook, example -@vindex mh-quit-hook -@vindex mh-quit-hook, example - -The two hooks @code{mh-before-quit-hook} and @code{mh-quit-hook} are -called by @kbd{q}. The former one is called before the quit occurs, so -you might use it to perform any MH-E operations; you could perform -some query and abort the quit or call @code{mh-execute-commands}, for -example. The latter is not run in an MH-E context, so you might use it -to modify the window setup. If you find that @kbd{q} buries a lot of -buffers that you would rather remove, you can use both -@code{mh-before-quit-hook} and @code{mh-quit-hook} to accomplish that. - -@smalllisp -@group -(defvar my-mh-folder-buffer-to-delete nil - "Folder buffer that is being quit.") - -(defun my-mh-before-quit-hook () - "Save folder buffer that is to be deleted." - (setq my-mh-folder-buffer-to-delete (current-buffer))) - -(defun my-mh-quit-hook () - "Kill folder buffer rather than just bury it." - (set-buffer my-mh-folder-buffer-to-delete) - (if (get-buffer mh-show-buffer) - (kill-buffer mh-show-buffer)) - (kill-buffer (current-buffer))) - -@i{Kill MH-Folder buffer instead of burying it} -@end group -@end smalllisp - -@cindex folders, renaming -@cindex renaming folders -@findex dired -@findex dired-do-rename - -You can use dired to manipulate the folders themselves. For example, I -renamed my @samp{+out} folder to the more common @samp{+outbox} by -running dired on my mail directory (@kbd{M-x dired RET ~/Mail RET}), -moving my cursor to @samp{out} and using the command @kbd{R} -(@code{dired-do-rename}). - -@node Sending Mail, Editing Drafts, Folders, Top -@chapter Sending Mail - -@cindex sending mail -@findex mh-smail -@kindex M-x mh-smail - -You can send a mail message in several ways. You can call @kbd{M-x -mh-smail} directly, or from the command line like this: - -@cindex starting from command line - -@smallexample -$ @kbd{emacs -f mh-smail} -@end smallexample - -@findex goto-address-at-point -@vindex mail-user-agent - -There are some commands that need to send a mail message, such as -@code{goto-address-at-point}. You can configure Emacs to have these -commands use MH-E by setting the option @code{mail-user-agent} to -@samp{Emacs interface to MH}. - -@cindex @samp{Message} menu -@cindex menu, @samp{Message} - -From within MH-E's MH-Folder mode, other methods of sending mail are -available as well. These can also be found in the @samp{Message} menu. - -@table @kbd -@cindex @samp{Message > Edit Message Again} menu item -@cindex menu item, @samp{Message > Edit Message Again} -@kindex e -@findex mh-edit-again -@item e -Edit a message to send it again (@code{mh-edit-again}). -@c ------------------------- -@cindex @samp{Message > Re-edit a Bounced Message} menu item -@cindex menu item, @samp{Message > Re-edit a Bounced Message} -@kindex E -@findex mh-extract-rejected-mail -@item E -Edit a message that was returned by the mail system -(@code{mh-extract-rejected-mail}). -@c ------------------------- -@cindex @samp{Message > Forward Message...} menu item -@cindex menu item, @samp{Message > Forward Message...} -@kindex f -@findex mh-forward -@item f -Forward message (@code{mh-forward}). -@c ------------------------- -@cindex @samp{Message > Reply to Message...} menu item -@cindex menu item, @samp{Message > Reply to Message...} -@kindex r -@findex mh-reply -@item r -Reply to a message (@code{mh-reply}). -@c ------------------------- -@cindex @samp{Message > Compose a New Message} menu item -@cindex menu item, @samp{Message > Compose a New Message} -@kindex s -@findex mh-send -@item s -Compose a message (@code{mh-send}). -@c ------------------------- -@cindex @samp{Message > Redistribute Message...} menu item -@cindex menu item, @samp{Message > Redistribute Message...} -@kindex M-d -@findex mh-redistribute -@item M-d -Redistribute a message (@code{mh-redistribute}). -@c ------------------------- -@findex mh-smail -@item M-x mh-smail -Compose a message with the MH mail system. -@c ------------------------- -@findex mh-smail-other-window -@item M-x mh-smail-other-window -Compose a message with the MH mail system in other window. -@end table - -@cindex @samp{mh-sending-mail} customization group -@cindex customization group, @samp{mh-sending-mail} - -In addition, several options from the @samp{mh-sending-mail} -customization group are useful when sending mail or replying to mail. -They are summarized in the following table. - -@vtable @code -@item mh-compose-forward-as-mime-flag -On means that messages are forwarded as attachments (default: -@samp{on}). -@c ------------------------- -@item mh-compose-letter-function -Hook run when starting a new draft (default: @code{nil}). -@c ------------------------- -@item mh-compose-prompt-flag -On means prompt for header fields when composing a new draft (default: -@samp{off}). -@c ------------------------- -@item mh-forward-subject-format -Format string for forwarded message subject (default: @code{"%s: -%s"}). -@c ------------------------- -@item mh-insert-x-mailer-flag -On means append an @samp{X-Mailer:} header field to the header -(default: @samp{on}). -@c ------------------------- -@item mh-redist-full-contents-flag -On means the @command{dist} command needs entire letter for -redistribution (default: @samp{off}). -@c ------------------------- -@item mh-reply-default-reply-to -Sets the person or persons to whom a reply will be sent (default: -@samp{Prompt}). -@c ------------------------- -@item mh-reply-show-message-flag -On means the MH-Show buffer is displayed using @kbd{r} -(@code{mh-reply}) (default: @samp{on}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mh-annotate-msg-hook -Hook run by @code{mh-annotate-msg} after annotation (default: -@code{nil}). -@c ------------------------- -@item mh-forward-hook -Hook run by @code{mh-forward} on a forwarded letter (default: -@code{nil}). -@c ------------------------- -@item mh-letter-mode-hook -Hook run by @code{mh-letter-mode} on a new letter (default: -@code{nil}). -@end vtable - -@findex mh-annotate-msg -@vindex mh-annotate-list -@vindex mh-annotate-msg-hook -@vindex mh-current-folder - -A hook that is called whenever a message is sent and after the scan -lines and message are annotated is @code{mh-annotate-msg-hook}. Hook -functions can access the current folder name with -@code{mh-current-folder} and obtain the message numbers of the -annotated messages with @code{mh-annotate-list}. - -The rest of the functions and options introduced here are explained in -more detail in the following sections. - -@menu -* Composing:: -* Replying:: -* Forwarding:: -* Redistributing:: -* Editing Again:: -@end menu - -@node Composing, Replying, Sending Mail, Sending Mail -@section Composing - -@cindex @file{.emacs} -@cindex MH-Folder mode -@cindex composing mail -@cindex draft -@cindex files, @file{.emacs} -@cindex modes, MH-Folder -@cindex sending mail -@findex mh-smail -@findex mh-smail-other-window -@kindex M-x mh-smail -@kindex M-x mh-smail-other-window - -Outside of an MH-Folder buffer, you must call either @kbd{M-x -mh-smail} or @kbd{M-x mh-smail-other-window} to compose a new message. -The former command always creates a two-window layout with the current -buffer on top and the draft on the bottom. Use the latter command if -you would rather preserve the window layout. You may find adding the -following key bindings to @file{~/.emacs} useful: - -@smalllisp -(global-set-key "\C-xm" 'mh-smail) -(global-set-key "\C-x4m" 'mh-smail-other-window) -@end smalllisp - -@cindex draft folder -@cindex MH-Letter mode -@cindex modes, MH-Letter -@findex mh-send -@kindex m - -From within a MH-Folder buffer, you can simply use the command @kbd{m} -(@code{mh-send}). However you invoke @code{mh-send}, your letter -appears in an Emacs buffer whose mode is MH-Letter (to see what the -buffer looks like, @pxref{Sending Mail Tour}). MH-Letter mode allows -you to edit your message, to check the validity of the recipients, to -insert attachments and other messages into your message, and to send -the message. We'll go more into depth about editing a -@dfn{draft}@footnote{I highly recommend that you use a @dfn{draft -folder} so that you can edit several drafts in parallel. To do so, -create a folder named @samp{+drafts} for example, and add the profile -component @samp{Draft-Folder: drafts} (see @code{mh-profile}(5)).} (a -message you're composing) in just a moment (@pxref{Editing Drafts}). - -@vindex mh-compose-prompt-flag - -If you prefer to be prompted for the recipient and subject fields -before the MH-Letter buffer appears, turn on the option -@code{mh-compose-prompt-flag}. - -@cindex header field, @samp{X-Mailer:} -@cindex @samp{X-Mailer:} header field -@vindex mh-insert-x-mailer-flag - -MH-E adds an @samp{X-Mailer:} header field to the header that includes -the version of MH-E and Emacs that you are using. If you don't want to -participate in our marketing, you can turn off the option -@code{mh-insert-x-mailer-flag}. - -@cindex @command{repl} -@cindex @file{components} -@cindex MH commands, @command{repl} -@cindex MH-Letter mode -@cindex Mail mode -@cindex files, @file{components} -@cindex modes, MH-Letter -@cindex modes, Mail -@vindex mail-mode-hook -@vindex mh-letter-mode-hook -@vindex text-mode-hook - -Two hooks are provided to run commands on your freshly created draft. -The first hook, @code{mh-letter-mode-hook}, allows you to do some -processing before editing a letter@footnote{Actually, because -MH-Letter mode inherits from Mail mode, the hooks -@code{text-mode-hook} and @code{mail-mode-hook} are run (in that -order) before @code{mh-letter-mode-hook}.}. For example, you may wish -to modify the header after @command{repl} has done its work, or you -may have a complicated @file{components} file and need to tell MH-E -where the cursor should go. Here's an example of how you would use -this hook. - -@findex mh-insert-signature, example - -@smalllisp -@group -(defvar letter-mode-init-done-flag nil - "Non-nil means one-time MH-E settings have been made.") - -(defun my-mh-letter-mode-hook () - "Prepare letter for editing." - (when (not letter-mode-init-done) ; @r{only need to bind the keys once} - (local-set-key "\C-ctb" 'add-enriched-text) - (local-set-key "\C-cti" 'add-enriched-text) - (local-set-key "\C-ctf" 'add-enriched-text) - (local-set-key "\C-cts" 'add-enriched-text) - (local-set-key "\C-ctB" 'add-enriched-text) - (local-set-key "\C-ctu" 'add-enriched-text) - (local-set-key "\C-ctc" 'add-enriched-text) - (setq letter-mode-init-done t)) - (save-excursion - (goto-char (point-max)) ; @r{go to end of message to} - (mh-insert-signature))) ; @r{insert signature} - -@i{Prepare draft for editing via mh-letter-mode-hook} - -@end group -@end smalllisp - -The function, @code{add-enriched-text} is defined in the example in -@ref{Adding Attachments}. - -@vindex mh-compose-letter-function -@vindex mh-letter-mode-hook - -The second hook, a function really, is -@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it -is called just before editing a new message; however, it is the last -function called before you edit your message. The consequence of this -is that you can write a function to write and send the message for -you. This function is passed three arguments: the contents of the -@samp{To:}, @samp{Subject:}, and @samp{Cc:} header fields. - -@node Replying, Forwarding, Composing, Sending Mail -@section Replying to Mail - -@cindex @command{mhl} -@cindex @file{mhl.reply} -@cindex MH commands, @command{mhl} -@cindex files, @file{mhl.reply} -@cindex replying -@findex mh-reply -@kindex r - -To compose a reply to a message, use the @kbd{r} (@code{mh-reply}) -command. - -When you reply to a message, you are first prompted with @samp{Reply -to whom?}. You have several choices here. - -@quotation -@multitable @columnfractions .20 .80 -@c @headitem Response @tab Reply Goes To -@c XXX @headitem not yet supported by SourceForge's texi2pdf. -@item @b{Response} @tab @b{Reply Goes To} -@c ------------------------- -@item @kbd{from} -@tab -The person who sent the message. This is the default, so @key{RET} is -sufficient. -@c ------------------------- -@item @kbd{to} -@tab -Replies to the sender, plus all recipients in the @samp{To:} header field. -@c ------------------------- -@item @kbd{cc}@*@kbd{all} -@tab -Forms a reply to the addresses in the @samp{Mail-Followup-To:} header -field if one exists; otherwise forms a reply to the sender, plus all -recipients. -@end multitable -@end quotation - -@cindex @command{repl} -@cindex MH commands, @command{repl} -@vindex mh-reply-default-reply-to - -Depending on your answer, @command{repl}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reprep.html, Replying to Messages: repl} in -the MH book.} is given a different argument to form your reply. -Specifically, a choice of @kbd{from} or none at all runs @samp{repl --nocc all}, and a choice of @kbd{to} runs @samp{repl -cc to}. Finally, -either @kbd{cc} or @kbd{all} runs @samp{repl -cc all -nocc me}. If you -find that most of the time you specify one of these choices when you -reply to a message, you can change the option -@code{mh-reply-default-reply-to} from its default value of -@samp{Prompt} to one of the choices listed above. You can always edit -the recipients in the draft. - -@cindex @samp{repl:} MH profile component -@cindex MH profile component, @samp{repl:} -@cindex MH-Letter mode -@cindex MH-Show mode -@cindex draft -@cindex modes, MH-Letter -@cindex modes, MH-Show - -Two windows are then created. One window contains the message to which -you are replying in an MH-Show buffer. Your draft, in MH-Letter mode -(@pxref{Editing Drafts}), is in the other window. If the reply draft -was not one that you expected, check the things that affect the -behavior of @command{repl} which include the @samp{repl:} profile -component and the @file{replcomps} and @file{replgroupcomps} files. - -If you supply a prefix argument (as in @kbd{C-u r}), the message you -are replying to is inserted in your reply after having first been run -through @command{mhl} with the format file @file{mhl.reply}. See -@command{mhl}(1) or the section -@uref{@value{MH-BOOK-HOME}/shomes.html#Usisho, Using mhl} in the MH -book to see how you can modify the default @file{mhl.reply} file. - -@vindex mh-yank-behavior - -Alternatively, you can customize the option @code{mh-yank-behavior} -and choose one of its @samp{Automatically} variants to do the same -thing. @xref{Inserting Letter}. If you do so, the prefix argument has -no effect. - -Another way to include the message automatically in your draft is to -use @samp{repl: -filter repl.filter} in your MH profile. - -@vindex mh-reply-show-message-flag - -If you include the message automatically, you can hide the MH-Show -buffer by turning off the option @code{mh-reply-show-message-flag}. - -If you wish to customize the header or other parts of the reply draft, -please see @command{repl}(1) and @code{mh-format}(5). - -@node Forwarding, Redistributing, Replying, Sending Mail -@section Forwarding Mail - -@cindex @command{forw} -@cindex draft -@cindex forwarding -@cindex MH commands, @command{forw} -@findex mh-forward -@kindex f -@vindex mh-forward-hook - -To forward a message, use the @kbd{f} (@code{mh-forward}) command. You -are prompted for the @samp{To:} and @samp{cc:} recipients. You are -given a draft to edit that looks like it would if you had run the MH -command @command{forw}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/forfor.html, Forwarding Messages: forw} in -the MH book.}. You can then add some text (@pxref{Editing Drafts}). -You can forward several messages by using a range (@pxref{Ranges}). -All of the messages in the range are inserted into your draft. The -hook @code{mh-forward-hook} is called on the draft. - -@cindex @file{.mh_profile} -@cindex files, @file{.mh_profile} -@cindex MH profile component, @samp{forw:} -@cindex @samp{forw:} MH profile component -@vindex mh-compose-forward-as-mime-flag - -By default, the option @code{mh-compose-forward-as-mime-flag} is on -which means that the forwarded messages are included as attachments. -These are inline attachments so the forwarded message should appear in -the body of your recipient's mail program. If you would prefer to -forward your messages verbatim (as text, inline), then turn off this -option. Forwarding messages verbatim works well for short, textual -messages, but your recipient won't be able to view any non-textual -attachments that were in the forwarded message. Be aware that if you -have @samp{forw: -mime} in your MH profile, then forwarded messages -will always be included as attachments regardless of the settings of -@code{mh-compose-forward-as-mime-flag}. - -@vindex mh-forward-subject-format - -The format of the @samp{Subject:} header field for forwarded messages -is controlled by the option @code{mh-forward-subject-format}. This -option is a string which includes two escapes (@samp{%s}). The first -@samp{%s} is replaced with the sender of the original message, and the -second one is replaced with the original @samp{Subject:}. The default -value of @code{"%s: %s"} takes a message with the header: - -@smallexample -@group -To: Bill Wohler -Subject: Re: 49er football -From: Greg DesBrisay -@end group -@end smallexample - -and creates a subject header field of: - -@smallexample -Subject: Greg DesBrisay: Re: 49er football -@end smallexample - -@node Redistributing, Editing Again, Forwarding, Sending Mail -@section Redistributing Your Mail - -@cindex @command{dist} -@cindex MH commands, @command{dist} -@cindex redistributing -@findex mh-redistribute -@kindex M-d - -The command @kbd{M-d} (@code{mh-redistribute}) is similar in function -to forwarding mail, but it does not allow you to edit the message, nor -does it add your name to the @samp{From:} header field. It appears to -the recipient as if the message had come from the original sender. -When you run this command, you are prompted for the recipients. - -@findex mh-edit-again -@kindex e - -For more information on redistributing messages, see -@command{dist}(1). Also investigate the command @kbd{e} -(@code{mh-edit-again}) for another way to redistribute messages -(@pxref{Editing Again}). - -@cindex @command{send} -@cindex MH commands, @command{send} -@vindex mh-redist-full-contents-flag - -The option @code{mh-redist-full-contents-flag} must be turned on if -@command{dist}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/disdis.html, Distributing Messages with -dist} in the MH book.} requires the whole letter for redistribution, -which is the case if @command{send}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} -in the MH book.} is compiled with the @sc{berk} option (which many -people abhor). If you find that MH will not allow you to redistribute -a message that has been redistributed before, turn off this option. - -The hook @code{mh-annotate-msg-hook} is run after annotating the -message and scan line (@pxref{Sending Mail}). - -@node Editing Again, , Redistributing, Sending Mail -@section Editing Old Drafts and Bounced Messages - -@cindex @file{draft} -@cindex files, @file{draft} -@cindex re-editing drafts -@findex mh-edit-again -@kindex F v drafts -@kindex e -@kindex n - -If you don't complete a draft for one reason or another, and if the -draft buffer is no longer available, you can pick your draft up again -with @kbd{e} (@code{mh-edit-again}). If you don't use a draft -folder, your last @file{draft} file will be used. If you use draft -folders, you'll need to visit the draft folder with @kbd{F v drafts -@key{RET}}, use @kbd{n} to move to the appropriate message, and then -use @kbd{e} to prepare the message for editing. - -@kindex e - -The @kbd{e} command can also be used to take messages that were sent -to you and to send them to more people. - -@cindex Mailer-Daemon -@findex mh-extract-rejected-mail -@kindex C-c C-c -@kindex E - -Don't use @kbd{e} to re-edit a message from a @i{Mailer-Daemon} who -complained that your mail wasn't posted for some reason or another. In -this case, use @kbd{E} (@code{mh-extract-rejected-mail}) to prepare -the message for editing by removing the @i{Mailer-Daemon} envelope and -unneeded header fields. Fix whatever addressing problem you had, and -send the message again with @kbd{C-c C-c}. - -@node Editing Drafts, Aliases, Sending Mail, Top -@chapter Editing a Draft - -@cindex @samp{Letter} menu -@cindex MH-Letter mode -@cindex draft -@cindex editing draft -@cindex menu, @samp{Letter} -@cindex modes, MH-Letter - -When you edit a message that you want to send (called a @dfn{draft} in -this case), the mode used is MH-Letter. This mode provides several -commands in addition to the normal Emacs editing commands to help you -edit your draft. These can also be found in the @samp{Letter} menu. - -@table @kbd -@kindex @key{SPC} -@findex mh-letter-complete-or-space -@item @key{SPC} -Perform completion or insert space (@code{mh-letter-complete-or-space}). -@c ------------------------- -@kindex M-@key{TAB} -@findex mh-letter-complete -@item M-@key{TAB} -Perform completion on header field or word preceding point -(@code{mh-letter-complete}). -@c ------------------------- -@kindex , (comma) -@findex mh-letter-confirm-address -@item , (comma) -Flash alias expansion (@code{mh-letter-confirm-address}). -@c ------------------------- -@kindex @key{TAB} -@findex mh-letter-next-header-field-or-indent -@item @key{TAB} -Cycle to next field (@code{mh-letter-next-header-field-or-indent}). -@c ------------------------- -@kindex S-@key{TAB} -@findex mh-letter-previous-header-field -@item S-@key{TAB} -Cycle to the previous header field -(@code{mh-letter-previous-header-field}). -@c ------------------------- -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Letter > Send This Draft} menu item -@cindex menu item, @samp{Letter > Send This Draft} -@kindex C-c C-c -@findex mh-send-letter -@item C-c C-c -Save draft and send message (@code{mh-send-letter}). -@c ------------------------- -@kindex C-c C-d -@findex mh-insert-identity -@item C-c C-d -Insert fields specified by the given identity -(@code{mh-insert-identity}). @xref{Identities}. -@c ------------------------- -@cindex @samp{Letter > Pull in All Compositions (MH)} menu item -@cindex menu item, @samp{Letter > Pull in All Compositions (MH)} -@kindex C-c C-e -@findex mh-mh-to-mime -@item C-c C-e -Compose @sc{mime} message from MH-style directives -(@code{mh-mh-to-mime}). -@c ------------------------- -@kindex C-c C-f C-a -@kindex C-c C-f a -@findex mh-to-field -@item C-c C-f C-a -@itemx C-c C-f a -Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-b -@kindex C-c C-f b -@item C-c C-f C-b -@itemx C-c C-f b -Move to @samp{Bcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-c -@kindex C-c C-f c -@item C-c C-f C-c -@itemx C-c C-f c -Move to @samp{Cc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-d -@kindex C-c C-f d -@item C-c C-f C-d -@itemx C-c C-f d -Move to @samp{Dcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-f -@kindex C-c C-f f -@findex mh-to-fcc -@item C-c C-f C-f -@itemx C-c C-f f -Move to @samp{Fcc:} header field (@code{mh-to-fcc}). -@c ------------------------- -@kindex C-c C-f C-l -@kindex C-c C-f l -@item C-c C-f C-l -@itemx C-c C-f l -Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-m -@kindex C-c C-f m -@item C-c C-f C-m -@itemx C-c C-f m -Move to @samp{From:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-r -@kindex C-c C-f r -@item C-c C-f C-r -@itemx C-c C-f r -Move to @samp{Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-s -@kindex C-c C-f s -@item C-c C-f C-s -@itemx C-c C-f s -Move to @samp{Subject:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-t -@kindex C-c C-f t -@item C-c C-f C-t -@itemx C-c C-f t -Move to @samp{To:} header field (@code{mh-to-field}). -@c ------------------------- -@cindex @samp{Letter > Insert a Message...} menu item -@cindex menu item, @samp{Letter > Insert a Message...} -@kindex C-c C-i -@findex mh-insert-letter -@item C-c C-i -Insert a message (@code{mh-insert-letter}). -@c ------------------------- -@kindex C-c C-m C-e -@findex mh-mml-secure-message-encrypt -@item C-c C-m C-e -Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). -@c ------------------------- -@cindex @samp{Letter > Compose Forward...} menu item -@cindex menu item, @samp{Letter > Compose Forward...} -@kindex C-c C-m C-f -@kindex C-c C-m f -@findex mh-compose-forward -@item C-c C-m C-f -@itemx C-c C-m f -Add tag to forward a message (@code{mh-compose-forward}). -@c ------------------------- -@cindex @samp{Letter > Compose Get File (MH)...} menu item -@cindex menu item, @samp{Letter > Compose Get File (MH)...} -@kindex C-c C-m C-g -@kindex C-c C-m g -@findex mh-mh-compose-anon-ftp -@item C-c C-m C-g -@itemx C-c C-m g -Add tag to include anonymous ftp reference to a file -(@code{mh-mh-compose-anon-ftp}). -@c ------------------------- -@cindex @samp{Letter > Compose Insertion...} menu item -@cindex menu item, @samp{Letter > Compose Insertion...} -@kindex C-c C-m C-i -@kindex C-c C-m i -@findex mh-compose-insertion -@item C-c C-m C-i -@itemx C-c C-m i -Add tag to include a file such as an image or sound -(@code{mh-compose-insertion}). -@c ------------------------- -@cindex @samp{Letter > Pull in All Compositions (MML)} menu item -@cindex menu item, @samp{Letter > Pull in All Compositions (MML)} -@kindex C-c C-m C-m -@kindex C-c C-m m -@findex mh-mml-to-mime -@item C-c C-m C-m -@itemx C-c C-m m -Compose @sc{mime} message from MML tags (@code{mh-mml-to-mime}). -@c ------------------------- -@kindex C-c C-m C-n -@kindex C-c C-m n -@findex mh-mml-unsecure-message -@item C-c C-m C-n -@itemx C-c C-m n -Remove any secure message tags (@code{mh-mml-unsecure-message}). -@c ------------------------- -@kindex C-c C-m C-s -@findex mh-mml-secure-message-sign -@item C-c C-m C-s -Add tag to sign the message (@code{mh-mml-secure-message-sign}). -@c ------------------------- -@cindex @samp{Letter > Compose Compressed tar (MH)...} menu item -@cindex menu item, @samp{Letter > Compose Compressed tar (MH)...} -@kindex C-c C-m C-t -@kindex C-c C-m t -@findex mh-mh-compose-external-compressed-tar -@item C-c C-m C-t -@itemx C-c C-m t -Add tag to include anonymous ftp reference to a compressed tar file -(@code{mh-mh-compose-external-compressed-tar}). -@c ------------------------- -@cindex @samp{Letter > Revert to Non-MIME Edit (MH)} menu item -@cindex menu item, @samp{Letter > Revert to Non-MIME Edit (MH)} -@kindex C-c C-m C-u -@kindex C-c C-m u -@findex mh-mh-to-mime-undo -@item C-c C-m C-u -@itemx C-c C-m u -Undo effects of @kbd{C-c C-e} (@code{mh-mh-to-mime-undo}). -@c ------------------------- -@kindex C-c C-m C-x -@kindex C-c C-m x -@findex mh-mh-compose-external-type -@item C-c C-m C-x -@itemx C-c C-m x -Add tag to refer to a remote file -(@code{mh-mh-compose-external-type}). -@c ------------------------- -@kindex C-c C-m e e -@findex mh-mml-secure-message-encrypt -@item C-c C-m e e -Add tag to encrypt the message (@code{mh-mml-secure-message-encrypt}). -@c ------------------------- -@kindex C-c C-m e s -@findex mh-mml-secure-message-signencrypt -@item C-c C-m e s -Add tag to encrypt and sign the message@* -(@code{mh-mml-secure-message-signencrypt}). -@c ------------------------- -@kindex C-c C-m s e -@findex mh-mml-secure-message-signencrypt -@item C-c C-m s e -Add tag to encrypt and sign the message@* -(@code{mh-mml-secure-message-signencrypt}). -@c ------------------------- -@kindex C-c C-m s s -@findex mh-mml-secure-message-sign -@item C-c C-m s s -Add tag to sign the message (@code{mh-mml-secure-message-sign}). -@c ------------------------- -@cindex @samp{Letter > Split Current Line} menu item -@cindex menu item, @samp{Letter > Split Current Line} -@kindex C-c C-o -@findex mh-open-line -@item C-c C-o -Insert a newline and leave point before it (@code{mh-open-line}). -@c ------------------------- -@cindex @samp{Letter > Kill This Draft} menu item -@cindex menu item, @samp{Letter > Kill This Draft} -@kindex C-c C-q -@findex mh-fully-kill-draft -@item C-c C-q -Quit editing and delete draft message (@code{mh-fully-kill-draft}). -@c ------------------------- -@cindex @samp{Letter > Insert Signature} menu item -@cindex menu item, @samp{Letter > Insert Signature} -@kindex C-c C-s -@findex mh-insert-signature -@item C-c C-s -Insert signature in message (@code{mh-insert-signature}). -@c ------------------------- -@kindex C-c C-t -@findex mh-letter-toggle-header-field-display -@item C-c C-t -Toggle display of header field at point -(@code{mh-letter-toggle-header-field-display}). -@c ------------------------- -@cindex @samp{Letter > Check Recipient} menu item -@cindex menu item, @samp{Letter > Check Recipient} -@kindex C-c C-w -@findex mh-check-whom -@item C-c C-w -Verify recipients, showing expansion of any aliases -(@code{mh-check-whom}). -@c ------------------------- -@cindex @samp{Letter > Yank Current Message} menu item -@cindex menu item, @samp{Letter > Yank Current Message} -@kindex C-c C-y -@findex mh-yank-cur-msg -@item C-c C-y -Insert the current message into the draft buffer -(@code{mh-yank-cur-msg}). -@c ------------------------- -@kindex C-c M-d -@findex mh-insert-auto-fields -@item C-c M-d -Insert custom fields if recipient is found in -@code{mh-auto-fields-list} (@code{mh-insert-auto-fields}). -@xref{Identities}. -@end table - -@cindex @samp{mh-letter} customization group -@cindex customization group, @samp{mh-letter} - -Several options from the @samp{mh-letter} customization group are used -while editing a draft. - -@vtable @code -@item mh-compose-insertion -Type of @sc{mime} message tags in messages (default: @samp{MML} if -available; otherwise @samp{MH}). -@c ------------------------- -@item mh-compose-skipped-header-fields -List of header fields to skip over when navigating in draft (default: -@code{'("From"} @code{"Organization"} @code{"References"} -@code{"In-Reply-To"} @code{"X-Face"} @code{"Face"} -@code{"X-Image-URL"} @code{"X-Mailer")}. -@c ------------------------- -@item mh-compose-space-does-completion-flag -On means @key{SPC} does completion in message header (default: -@samp{off}). -@c ------------------------- -@item mh-delete-yanked-msg-window-flag -On means delete any window displaying the message (default: @samp{off}). -@c ------------------------- -@item mh-extract-from-attribution-verb -Verb to use for attribution when a message is yanked by @kbd{C-c C-y} -(default: @code{"wrote:"}). -@c ------------------------- -@item mh-ins-buf-prefix -String to put before each line of a yanked or inserted message -(default: @code{"> "}). -@c ------------------------- -@item mh-letter-complete-function -Function to call when completing outside of address or folder fields -(default: @code{ispell-complete-word}). -@c ------------------------- -@item mh-letter-fill-column -Fill column to use in MH-Letter mode (default: 72). -@c ------------------------- -@item mh-mml-method-default -Default method to use in security tags (default: @samp{PGP (MIME)} if -support for it is available; otherwise @samp{None}). -@c ------------------------- -@item mh-signature-file-name -Source of user's signature (default: @code{"~/.signature"}). -@c ------------------------- -@item mh-signature-separator-flag -On means a signature separator should be inserted (default: -@samp{on}). -@c ------------------------- -@item mh-x-face-file -File containing X-Face or Face header field to insert in outgoing mail. -(default: @code{"~/.face"}). -@c ------------------------- -@item mh-yank-behavior -Controls which part of a message is yanked by @kbd{C-c C-y} (default: -@samp{Body With Attribution}). -@end vtable - -The following hooks are available. - -@vtable @code -@item mail-citation-hook -Hook for modifying a citation just inserted in the mail buffer -(default: @code{nil}). -@c ------------------------- -@item mh-before-send-letter-hook -Hook run at the beginning of the @kbd{C-c C-c} command (default: -@samp{nil}). -@c ------------------------- -@item mh-mh-to-mime-hook -Hook run on the formatted letter by @kbd{C-c C-e} (default: -@samp{nil}). -@c ------------------------- -@item mh-insert-signature-hook -Hook run by @kbd{C-c C-s} after signature has been inserted (default: -@code{nil}). -@end vtable - -The following face is available. - -@vtable @code -@item mh-letter-header-field -Editable header field value face in draft buffers. -@end vtable - -The commands and options introduced here are explained in more -detail in the following sections. - -@menu -* Editing Message:: -* Inserting Letter:: -* Inserting Messages:: -* Signature:: -* Picture:: -* Adding Attachments:: -* Sending PGP:: -* Checking Recipients:: -* Sending Message:: -* Killing Draft:: -@end menu - -@node Editing Message, Inserting Letter, Editing Drafts, Editing Drafts -@section Editing the Message - -@cindex @samp{Bcc:} header field -@cindex @samp{Cc:} header field -@cindex @samp{Dcc:} header field -@cindex @samp{From:} header field -@cindex @samp{Mail-Followup-To:} header field -@cindex @samp{Mail-Reply-To:} header field -@cindex @samp{Reply-To:} header field -@cindex @samp{Subject:} header field -@cindex @samp{To:} header field -@cindex editing header -@cindex header field, @samp{Bcc:} -@cindex header field, @samp{Cc:} -@cindex header field, @samp{Dcc:} -@cindex header field, @samp{From:} -@cindex header field, @samp{Mail-Followup-To:} -@cindex header field, @samp{Mail-Reply-To:} -@cindex header field, @samp{Reply-To:} -@cindex header field, @samp{Subject:} -@cindex header field, @samp{To:} -@findex mh-to-field -@kindex C-c C-f C-t -@kindex C-c C-f t - -Because the header is part of the message, you can edit the header -fields as you wish. However, several convenience commands exist to -help you create and edit them. For example, the command @kbd{C-c C-f -C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the -cursor to the @samp{To:} header field, creating it if necessary. The -commands for moving to the @samp{Cc:}, @samp{Subject:}, @samp{From:}, -@samp{Reply-To:}, @samp{Mail-Reply-To:}, @samp{Mail-Followup-To}, -@samp{Bcc:}, and @samp{Dcc:} header fields are similar. - -@findex mh-to-fcc -@kindex C-c C-f C-f -@kindex C-c C-f f - -One command behaves differently from the others, namely, @kbd{C-c C-f -C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This command -will prompt you for the folder name in which to file a copy of the -draft. @xref{Folder Selection}. - -@findex indent-relative -@findex mh-letter-next-header-field-or-indent -@findex mh-letter-previous-header-field -@kindex @key{TAB} -@kindex S-@key{TAB} -@vindex mh-compose-skipped-header-fields -@vindex mh-letter-header-field - -Within the header of the message, the command@* @key{TAB} -(@code{mh-letter-next-header-field-or-indent}) moves between fields -that are highlighted with the face @code{mh-letter-header-field}, -skipping those fields listed in -@code{mh-compose-skipped-header-fields}. After the last field, this -command then moves point to the message body before cycling back to -the first field. If point is already past the first line of the -message body, then this command indents by calling -@code{indent-relative} with the given prefix argument. The command -@kbd{S-@key{TAB}} (@code{mh-letter-previous-header-field}) moves -backwards between the fields and cycles to the body of the message -after the first field. Unlike the command @key{TAB}, it will always -take point to the last field from anywhere in the body. - -@cindex alias completion -@cindex completion -@cindex spell check -@findex ispell-complete-word -@findex mh-letter-complete -@findex mh-letter-complete-or-space -@findex mh-letter-confirm-address -@kindex , (comma) -@kindex @key{SPC} -@kindex M-@key{TAB} -@vindex mh-alias-flash-on-comma -@vindex mh-compose-space-does-completion-flag -@vindex mh-letter-complete-function - -If the field contains addresses (for example, @samp{To:} or -@samp{Cc:}) or folders (for example, @samp{Fcc:}) then the command -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) will provide alias -completion (@pxref{Aliases}). In the body of the message, -@kbd{M-@key{TAB}} runs @code{mh-letter-complete-function} instead, -which is set to @samp{'ispell-complete-word} by default. The command -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) takes a prefix argument -that is passed to the @code{mh-letter-complete-function}. In addition, -turn on the option @code{mh-compose-space-does-completion-flag} to use -the command @key{SPC} (@code{mh-letter-complete-or-space}) to perform -completion in the header as well; use a prefix argument to specify -more than one space. Addresses are separated by a comma; when you -press the comma, the command @code{mh-letter-confirm-address} flashes -the alias expansion in the minibuffer if -@code{mh-alias-flash-on-comma} is turned on. - -@c XXX Document the replacement for the inaccessible 'long argument. - -@findex mh-letter-toggle-header-field-display -@kindex C-c C-t - -Use the command @kbd{C-c C-t} -@code{mh-letter-toggle-header-field-display} to display truncated -header fields. This command is a toggle so entering it again will hide -the field. This command takes a prefix argument: if negative then the -field is hidden, if positive then the field is displayed (for example, -@kbd{C-u C-c C-t}). - -Be sure to leave a row of dashes or a blank line between the header -and the body of the message. - -@vindex mh-letter-fill-column - -The body of the message is edited as you would edit any Emacs buffer -although there are a few commands and options to assist you. You can -change the fill column in MH-Letter mode with the option -@code{mh-letter-fill-column}. By default, this option is 72 to allow -others to quote your message without line wrapping. - -@cindex filling paragraphs -@cindex paragraphs, filling -@findex fill-paragraph -@kindex M-q -@vindex mh-ins-buf-prefix - -You'll often include messages that were sent from user agents that -haven't yet realized that paragraphs consist of more than a single -line. This makes for long lines that wrap in an ugly fashion. You'll -find that @kbd{M-q} (@code{fill-paragraph}) works well even on these -quoted messages, even if they are nested, just as long as all of the -quotes match the value of @code{mh-ins-buf-prefix} (@pxref{Inserting -Letter}). For example, let's assume you have the following in your -draft: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. I'm \ -not sure yet whether I'm completely satisfied with my setup, but \ -it's worked okay for me so far. -@end group -@end smallexample - -Running @kbd{M-q} on this paragraph produces: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@findex mh-open-line -@findex open-line -@kindex C-c C-o -@kindex C-o - -The command @kbd{C-c C-o} (@code{mh-open-line}) is similar to the -command @kbd{C-o} (@code{open-line}) in that it inserts a newline -after point. It differs in that it also inserts the right number of -quoting characters and spaces so that the next line begins in the same -column as it was. This is useful when breaking up paragraphs in -replies. For example, if this command was used when point was after -the first period in the paragraph above, the result would be this: - -@smallexample -@group -> Hopefully this gives you an idea of what I'm currently doing. - -> I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@node Inserting Letter, Inserting Messages, Editing Message, Editing Drafts -@section Inserting Letter to Which You're Replying - -@cindex inserting messages -@cindex replying to messages -@cindex yanking messages -@findex mh-yank-cur-msg -@kindex C-c C-y -@vindex mh-ins-buf-prefix - -It is often useful to insert a snippet of text from a letter that -someone mailed to provide some context for your reply. The command -@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by adding an -attribution, yanking a portion of text from the message to which -you're replying, and inserting @code{mh-ins-buf-prefix} (@samp{> }) -before each line. - -@smallexample -@group -Michael W Thelen wrote: - -> Hopefully this gives you an idea of what I'm currently doing. I'm not -> sure yet whether I'm completely satisfied with my setup, but it's -> worked okay for me so far. -@end group -@end smallexample - -@vindex mh-extract-from-attribution-verb - -The attribution consists of the sender's name and email address -followed by the content of the option -@code{mh-extract-from-attribution-verb}. This option can be set to -@samp{wrote:}, @samp{a écrit:}, and @samp{schrieb:}. You can also use -the @samp{Custom String} menu item to enter your own verb. - -@vindex mail-citation-hook -@vindex mh-ins-buf-prefix -@vindex mh-yank-behavior - -The prefix @code{"> "} is the default setting for the option -@code{mh-ins-buf-prefix}. I suggest that you not modify this option -since it is used by many mailers and news readers: messages are far -easier to read if several included messages have all been indented by -the same string. This prefix is not inserted if you use one of the -supercite flavors of @code{mh-yank-behavior} or you have added a -@code{mail-citation-hook} as described below. - -@vindex mh-delete-yanked-msg-window-flag - -You can also turn on the @code{mh-delete-yanked-msg-window-flag} -option to delete the window containing the original message after -yanking it to make more room on your screen for your reply. - -@cindex Emacs, packages, supercite -@cindex supercite package -@kindex r -@vindex mail-citation-hook -@vindex mh-yank-behavior - -You can control how the message to which you are replying is yanked -into your reply using @code{mh-yank-behavior}. To include the entire -message, including the entire header, use @samp{Body and -Header}@footnote{If you'd rather have the header cleaned up, use -@kbd{C-u r} instead of @kbd{r} when replying -(@pxref{Replying}).}@footnote{In the past you would use this setting -and set @code{mail-citation-hook} to @samp{supercite}, but this usage -is now deprecated in favor of the @samp{Invoke supercite} setting.}. -Use @samp{Body} to yank just the body without the header. To yank only -the portion of the message following the point, set this option to -@samp{Below Point}. - -Choose @samp{Invoke supercite}@footnote{@emph{Supercite} is a -full-bodied, full-featured, citation package that comes standard with -Emacs.} to pass the entire message and header through supercite. - -@vindex mh-extract-from-attribution-verb - -If the @samp{Body With Attribution} setting is used, then the message -minus the header is yanked and a simple attribution line is added at -the top using the value of the option -@code{mh-extract-from-attribution-verb}. This is the default. - -@kindex C-c C-y -@vindex mh-delete-yanked-msg-window-flag - -If the @samp{Invoke supercite} or @samp{Body With Attribution} -settings are used, the @samp{-noformat} argument is passed to the -@command{repl} program to override a @samp{-filter} or @samp{-format} -argument. These settings also have @samp{Automatically} variants that -perform the action automatically when you reply so that you don't need -to use @kbd{C-c C-y} at all. Note that this automatic action is only -performed if the show buffer matches the message being replied to. -People who use the automatic variants tend to turn on the option -@code{mh-delete-yanked-msg-window-flag} as well so that the show -window is never displayed. - -@vindex mh-yank-behavior - -If the show buffer has a region, the option @code{mh-yank-behavior} is -ignored unless its value is one of @samp{Attribution} variants in -which case the attribution is added to the yanked region. - -@findex trivial-cite -@vindex mail-citation-hook -@vindex mh-ins-buf-prefix -@vindex mh-yank-behavior - -If this isn't enough, you can gain full control over the appearance of -the included text by setting @code{mail-citation-hook} to a function -that modifies it. This hook is ignored if the option -@code{mh-yank-behavior} is set to one of the supercite flavors. -Otherwise, this option controls how much of the message is passed to -the hook. The function can find the citation between point and mark -and it should leave point and mark around the modified citation text -for the next hook function. The standard prefix -@code{mh-ins-buf-prefix} is not added if this hook is set. - -@cindex Emacs, packages, trivial-cite -@cindex trivial-cite package -@vindex mh-yank-behavior - -For example, if you use the hook function -@uref{http://shasta.cs.uiuc.edu/~lrclause/tc.html, -@code{trivial-cite}} (which is NOT part of Emacs), set -@code{mh-yank-behavior} to @samp{Body and Header}. - -@node Inserting Messages, Signature, Inserting Letter, Editing Drafts -@section Inserting Messages - -@cindex inserting messages -@findex mh-insert-letter -@findex mh-yank-behavior -@kindex C-c C-i -@vindex mh-ins-buf-prefix -@vindex mh-invisible-header-fields-compiled -@vindex mh-yank-behavior - -Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}). -This command prompts you for the folder and message number, which -defaults to the current message in that folder. It then inserts the -messages, indented by @code{mh-ins-buf-prefix} (@samp{> }) unless -@code{mh-yank-behavior} is set to one of the supercite flavors in -which case supercite is used to format the message. Certain -undesirable header fields (see -@code{mh-invisible-header-fields-compiled}) are removed before -insertion. - -If given a prefix argument (like @kbd{C-u C-c C-i}), the header is -left intact, the message is not indented, and @samp{> } is not -inserted before each line. This command leaves the mark before the -letter and point after it. - -@node Signature, Picture, Inserting Messages, Editing Drafts -@section Inserting Your Signature - -@cindex signature -@findex mh-insert-signature -@kindex C-c C-s - -You can insert your signature at the current cursor location with the -command @kbd{C-c C-s} (@code{mh-insert-signature}). - -@cindex files, @file{.signature} -@cindex @file{.signature} -@cindex vCard -@vindex mh-signature-file-name - -By default, the text of your signature is taken from the file -@file{~/.signature}. You can read from other sources by changing the -option @code{mh-signature-file-name}. This file may contain a -@dfn{vCard} in which case an attachment is added with the vCard. - -@findex mh-signature-separator-p -@vindex mh-signature-file-name -@vindex mh-signature-separator -@vindex mh-signature-separator-regexp - -The option @code{mh-signature-file-name} may also be a symbol, in -which case that function is called. You may not want a signature -separator to be added for you; instead you may want to insert one -yourself. Options that you may find useful to do this include -@code{mh-signature-separator} (when inserting a signature separator) -and @code{mh-signature-separator-regexp} (for finding said separator). -The function @code{mh-signature-separator-p}, which reports @code{t} -if the buffer contains a separator, may be useful as well. - -@cindex signature separator -@vindex mh-signature-separator-flag - -A signature separator (@code{"-- "}) will be added if the signature -block does not contain one and @code{mh-signature-separator-flag} is -on. It is not recommended that you change this option since various -mail user agents, including MH-E, use the separator to present the -signature differently, and to suppress the signature when replying or -yanking a letter into a draft. - -@vindex mh-insert-signature-hook -@vindex mh-signature-file-name - -The hook @code{mh-insert-signature-hook} is run after the signature is -inserted. Hook functions may access the actual name of the file or the -function used to insert the signature with -@code{mh-signature-file-name}. - -The signature can also be inserted using Identities. -@xref{Identities}. - -@node Picture, Adding Attachments, Signature, Editing Drafts -@section Inserting Your Picture - -@cindex @file{.face} -@cindex files, @file{.face} -@vindex mh-x-face-file - -You can insert your picture in the header of your mail message so that -recipients see your face in the @samp{From:} header field if their -mail user agent is sophisticated enough. In MH-E, this is done by -placing your image in the file named by the option -@code{mh-x-face-file} which is @file{~/.face} by default. - -@cindex @samp{Face:} header field -@cindex @samp{X-Face:} header field -@cindex @samp{X-Image-URL:} header field -@cindex header field, @samp{Face:} -@cindex header field, @samp{X-Face:} -@cindex header field, @samp{X-Image-URL:} - -If the file starts with either of the strings @samp{X-Face:}, -@samp{Face:} or @samp{X-Image-URL:} then the contents are added to the -message header verbatim. Otherwise it is assumed that the file -contains the value of the @samp{X-Face:} header field. - -@cindex @command{compface} -@cindex Unix commands, @command{compface} - -The @samp{X-Face:} header field, which is a low-resolution, black and -white image, can be generated using the -@uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, -@command{compface}} command. The @uref{http://www.dairiki.org/xface/, -@cite{Online X-Face Converter}} is a useful resource for quick -conversion of images into @samp{X-Face:} header fields. - -Use the @uref{http://quimby.gnus.org/circus/face/make-face, -@command{make-face}} script to convert a JPEG image to the higher -resolution, color, @samp{Face:} header field. - -The URL of any image can be used for the @samp{X-Image-URL:} field and -no processing of the image is required. - -@vindex mh-x-face-file - -To prevent the setting of any of these header fields, either set -@code{mh-x-face-file} to @code{nil}, or simply ensure that the file -defined by this option doesn't exist. - -@xref{Viewing}, to see how these header fields are displayed in MH-E. - -@node Adding Attachments, Sending PGP, Picture, Editing Drafts -@section Adding Attachments - -@cindex @command{mhbuild} -@cindex @command{mhn} -@cindex MH commands, @command{mhbuild} -@cindex MH commands, @command{mhn} -@cindex MIME -@cindex multimedia mail - -MH-E has the capability to create multimedia messages. It uses the -@sc{mime} (Multipurpose Internet Mail Extensions) -protocol@footnote{@sc{mime} is defined in -@uref{http://www.rfc-editor.org/rfc/rfc2045.txt, RFC 2045}.} The -@sc{mime} protocol allows you to incorporate images, sound, video, -binary files, and even commands that fetch a file with @samp{ftp} when -your recipient reads the message! - -@kindex C-c C-m - -If you were to create a multimedia message with plain MH commands, you -would insert @command{mhbuild} or @command{mhn} directives (henceforth -called @dfn{MH-style directives} into your draft and use the -@command{mhbuild} command in nmh or @command{mhn} command in MH and -GNU mailutils to expand them. MH-E works in much the same way, -although it provides a handful of commands prefixed with @kbd{C-c C-m} -to insert the directives so you don't need to remember the syntax of -them. Remember: you can always add MH-style directives by -hand@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in -the MH book.}. - -@cindex MIME Meta Language (MML) -@cindex MML -@vindex mh-compose-insertion - -In addition to MH-style directives, MH-E also supports MML (@sc{mime} -Meta Language) tags@footnote{ -@ifinfo -@c Although the third argument should default to the -@c first, makeinfo goes to the wrong Info file without it being -@c different--it seems to be getting our own Composing node. -@xref{Composing,,Composing with MML,emacs-mime}. -@end ifinfo -@ifnotinfo -See the section Composing in -@uref{http://www.gnus.org/manual/emacs-mime.html, @cite{The Emacs MIME -Manual}}. -@end ifnotinfo -}. The option @code{mh-compose-insertion} can be used to choose -between them. By default, this option is set to @samp{MML} if it is -supported since it provides a lot more functionality. This option can -also be set to @samp{MH} if MH-style directives are preferred. - -@cindex media types -@cindex MIME, media types - -The MH-E @sc{mime} commands require a @dfn{media type} for each body -part or attachment. For example, a PDF document is of type -@samp{application/pdf} and an HTML document is of type -@samp{text/html}. Some commands fill in the media type for you, -whereas others require you to enter one. - -@cindex @command{file} -@cindex @file{/etc/mime.types} -@cindex files, @file{/etc/mime.types} -@cindex Unix commands, @command{file} -@findex mailcap-mime-types - -In the cases where MH-E can do so, it will determine the media type -automatically. It uses the @command{file} command to do this. Failing -that, the Emacs function @code{mailcap-mime-types} is used to provide -a list from which to choose. This function usually reads the file -@file{/etc/mime.types}. - -Whether the media type is chosen automatically, or you choose it from -a list, use the type that seems to match best the file that you are -including. In the case of binaries, the media type -@samp{application/x-executable} can be useful. If you can't find an -appropriate media type, use @samp{text/plain} for text messages and -@samp{application/octet-stream} for everything else. - -@cindex content description -@cindex MIME, content description - -You are also sometimes asked for a @dfn{content description}. This is -simply an optional brief phrase, in your own words, that describes the -object. If you don't care to enter a content description, just press -return and none will be included; however, a reader may skip over -multimedia fields unless the content description is compelling. - -You can also create your own @sc{mime} body parts. In the following -example, I describe how you can create and edit a @samp{text/enriched} -body part to liven up your plain text messages with boldface, -underlining, and italics. I include an Emacs function which inserts -enriched text tags. - -@smalllisp -@group -(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") - ("u" . "underline") - ("s" . "smaller") ("B" . "bigger") - ("f" . "fixed") - ("c" . "center")) - "Alist of (final-character . tag) choices for add-enriched-text. -Additional types can be found in RFC 1563.") - -(defun add-enriched-text (begin end) - "Add enriched text tags around region. -The tag used comes from the list enriched-text-types and is -specified by the last keystroke of the command. When called from Lisp, -arguments are BEGIN and END@." - (interactive "r") - ;; @r{Set type to the tag indicated by the last keystroke.} - (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`})) - enriched-text-types)))) - (save-restriction ; @r{restores state from narrow-to-region} - (narrow-to-region begin end) ; @r{narrow view to region} - (goto-char (point-min)) ; @r{move to beginning of text} - (insert "<" type ">") ; @r{insert beginning tag} - (goto-char (point-max)) ; @r{move to end of text} - (insert "")))) ; @r{insert terminating tag} -@i{Emacs function for entering enriched text} - -@end group -@end smalllisp - -To use the function @code{add-enriched-text}, first add it to -@file{~/.emacs} and create key bindings for it (@pxref{Composing}). - -Then, in your plain text message, set the mark with @kbd{C-@@} or -@kbd{C-@key{SPC}}, type in the text to be highlighted, and type @kbd{C-c t -b}. This adds @samp{} where you set the mark and adds -@samp{} at the location of your cursor, giving you something -like: @samp{You should be very}. - -Before sending this message, use @kbd{C-c C-m C-m} -(@code{mh-mml-to-mime})@footnote{Use @kbd{C-c C-e} -(@code{mh-mh-to-mime}) if you're using MH-style directives.} to add -MIME header fields. Then replace @samp{text/plain} with -@samp{text/enriched} in the @samp{Content-Type:} header field. - -You may also be interested in investigating @code{sgml-mode}. - -@subheading Including Files - -@cindex attachments, inserting -@cindex images -@cindex MIME, images -@cindex MIME, sound -@cindex MIME, video -@cindex sound -@cindex video -@findex mh-compose-insertion -@kindex C-c C-m C-i -@kindex C-c C-m i -@vindex mh-compose-insertion - -Binaries, images, sound, and video can be inserted in your message -with the command @kbd{C-c C-m C-i} (@code{mh-compose-insertion}). You -are prompted for the filename containing the object, the media type if -it cannot be determined automatically, and a content description. If -you're using MH-style directives, you will also be prompted for -additional attributes. - -@subheading Forwarding Multimedia Messages - -@findex mh-compose-forward -@kindex C-c C-m C-f -@kindex C-c C-m f - -Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m -C-f} (@code{mh-compose-forward}). You are prompted for a content -description, the name of the folder in which the messages to forward -are located, and a range of messages, which defaults to the current -message in that folder. @xref{Ranges}. - -@subheading Including an FTP Reference - -@cindex @command{ftp} -@cindex MIME, @command{ftp} -@cindex Unix commands, @command{ftp} -@findex mh-mh-compose-anon-ftp -@kindex C-c C-m C-g -@kindex C-c C-m g - -You can have your message initiate an @command{ftp} transfer when the -recipient reads the message. To do this, use the command @kbd{C-c C-m -C-g} (@code{mh-mh-compose-anon-ftp}). You are prompted for the remote -host and filename, the media type, and the content description. - -@subheading Including tar Files - -@cindex @command{ftp} -@cindex @command{tar} -@cindex MIME, @command{ftp} -@cindex MIME, @command{tar} -@cindex Unix commands, @command{ftp} -@cindex Unix commands, @command{tar} -@findex mh-mh-compose-anon-ftp -@findex mh-mh-compose-external-compressed-tar -@kindex C-c C-m C-g -@kindex C-c C-m C-t -@kindex C-c C-m t - -If the remote file is a compressed tar file, you can use @kbd{C-c C-m -C-t} (@code{mh-mh-compose-external-compressed-tar}). Then, in addition -to retrieving the file via anonymous @emph{ftp} as per the command -@kbd{C-c C-m C-g} (@code{mh-mh-compose-anon-ftp}), the file will also -be uncompressed and untarred. You are prompted for the remote host and -filename and the content description. - -@subheading Including Other External Files - -@findex mh-mh-compose-external-type -@kindex C-c C-m C-x -@kindex C-c C-m x - -The command @kbd{C-c C-m C-x} (@code{mh-mh-compose-external-type}) is -a general utility for referencing external files. In fact, all of the -other commands that insert tags to access external files call this -command. You are prompted for the access type, remote host and -filename, and content type. If you provide a prefix argument, you are -also prompted for a content description, attributes, parameters, and a -comment. - -@subheading Previewing Multimedia Messages - -When you are finished editing a @sc{mime} message, it might look like this: - -@cartouche -@smallexample -3 t08/24 root received fax files on Wed Aug 24 11:00: -4+t08/24 To:wohler Test< -<#/part> ---:** @{draft@} All L8 (MH-Letter)---------------------------------- - -@end smallexample -@end cartouche -@i{MH-E @sc{mime} draft} - -@findex mh-mml-to-mime -@kindex C-c C-m C-m -@kindex C-c C-m m - -Typically, you send a message with attachments just like any other -message (@pxref{Sending Message}). - -@findex mh-mml-to-mime -@kindex C-c C-m C-m - -However, you may take a sneak preview of the @sc{mime} encoding if you -wish by running the command @kbd{C-c C-m C-m} (@code{mh-mml-to-mime}). -The following screen shows the @sc{mime} encoding specified by the -tags. You can see why mail user agents are usually built to hide these -details from the user. - -@cartouche -@smallexample -To: wohler -cc: -Subject: Test of MIME -X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -MIME-Version: 1.0 -Content-Type: multipart/mixed; boundary="=-=-=" --------- ---=-=-= - -Here is the SETI@@Home logo: - - ---=-=-= -Content-Type: image/x-xpm -Content-Disposition: inline; filename=setiathome.xpm -Content-Transfer-Encoding: base64 -Content-Description: SETI@@home logo - -LyogWFBNICovCnN0YXRpYyBjaGFyICogc2V0aWF0aG9tZV94cG1bXSA9IHsKIjQ1IDQ1IDc2N ---:-- @{draft@} Top L1 (MH-Letter)---------------------------------- - -@end smallexample -@end cartouche -@i{MH-E @sc{mime} draft ready to send} - -@cindex undo effects of mh-mml-to-mime - -This action can be undone by running @kbd{C-_} (@code{undo}). - -@cindex @command{mhbuild} -@cindex @command{mhn} -@cindex MH commands, @command{mhbuild} -@cindex MH commands, @command{mhn} -@cindex undo effects of mh-mh-to-mime -@findex mh-mh-to-mime -@findex mh-mh-to-mime-undo -@kindex C-c C-e -@kindex C-c C-m C-m -@kindex C-c C-m C-u -@kindex C-c C-m u - -If you're using MH-style directives, use @kbd{C-c C-e} -(@code{mh-mh-to-mime}) instead of @kbd{C-c C-m C-m}. This runs the -command @command{mhbuild} (@command{mhn}) on the message which expands -the tags@footnote{See the section -@uref{@value{MH-BOOK-HOME}/usimim.html#SeMIMa, Sending MIME Mail} in -the MH book.}. This action can be undone by running @kbd{C-c C-m C-u} -(@code{mh-mh-to-mime-undo}), which works by reverting to a backup -file. You are prompted to confirm this action, but you can avoid the -confirmation by adding an argument (for example, @kbd{C-u C-c C-m -C-u}). - -@kindex C-c C-e -@vindex mh-mh-to-mime-args - -If you wish to pass additional arguments to @command{mhbuild} -(@command{mhn}) to affect how it builds your message, use the option -@code{mh-mh-to-mime-args}. For example, you can build a consistency -check into the message by setting @code{mh-mh-to-mime-args} to -@samp{-check}. The recipient of your message can then run -@samp{mhbuild -check} on the message---@command{mhbuild} -(@command{mhn}) will complain if the message has been corrupted on the -way. The command @kbd{C-c C-e} only consults this option when given a -prefix argument (as in @kbd{C-u C-c C-e}). - -@kindex C-c C-e -@vindex mh-mh-to-mime-hook - -The hook @code{mh-mh-to-mime-hook} is called after the message has -been formatted by @kbd{C-c C-e}. - -@node Sending PGP, Checking Recipients, Adding Attachments, Editing Drafts -@section Signing and Encrypting Messages - -@cindex signing messages -@cindex encrypting messages -@cindex RFC 3156 - -MH-E can sign and encrypt messages as defined in -@uref{http://www.rfc-editor.org/rfc/rfc3156.txt, RFC 3156}. If you -should choose to sign or encrypt your message, use one of the -following commands to do so any time before sending your message. - -@findex mh-mml-secure-message-encrypt -@findex mh-mml-secure-message-sign -@findex mh-mml-secure-message-signencrypt -@kindex C-c C-m C-e -@kindex C-c C-m C-s -@kindex C-c C-m e e -@kindex C-c C-m e s -@kindex C-c C-m s e -@kindex C-c C-m s s - -The command @kbd{C-c C-m C-s} (@code{mh-mml-secure-message-sign}) -inserts the following tag: - -@smallexample -<#secure method=pgpmime mode=sign> -@end smallexample - -This is used to sign your message digitally. Likewise, the command -@kbd{C-c C-m C-e} (@code{mh-mml-secure-message-encrypt}) inserts the -following tag: - -@smallexample -<#secure method=pgpmime mode=encrypt> -@end smallexample - -This is used to encrypt your message. Finally, the command @kbd{C-c -C-m s e} (@code{mh-mml-secure-message-signencrypt}) inserts the -following tag: - -@smallexample -<#secure method=pgpmime mode=signencrypt> -@end smallexample - -@findex mh-mml-unsecure-message -@kindex C-c C-m C-n -@kindex C-c C-m n -@vindex mh-mml-method-default - -This is used to sign and encrypt your message. In each of these cases, -a proper multipart message is created for you when you send the -message. Use the command @kbd{C-c C-m C-n} -(@code{mh-mml-unsecure-message}) to remove these tags. Use a prefix -argument (as in @kbd{C-u C-c C-m s e}) to be prompted for one of the -possible security methods (see @code{mh-mml-method-default}). - -@vindex mh-mml-method-default - -The option @code{mh-mml-method-default} is used to select between a -variety of mail security mechanisms. The default is @samp{PGP (MIME)} -if it is supported; otherwise, the default is @samp{None}. Other -mechanisms include vanilla @samp{PGP} and @samp{S/MIME}. - -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{http://www.dk.xemacs.org/Documentation/packages/html/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - -@cindex header field, @samp{Fcc:} -@cindex @samp{Fcc:} header field -@vindex pgg-encrypt-for-me - -In particular, I turn on the option @code{pgg-encrypt-for-me} so that -all messages I encrypt are encrypted with my public key as well. If -you keep a copy of all of your outgoing mail with a @samp{Fcc:} header -field, this setting is vital so that you can read the mail you write! - -@node Checking Recipients, Sending Message, Sending PGP, Editing Drafts -@section Checking Recipients - -@cindex @samp{*MH-E Recipients*} -@cindex @command{whom} -@cindex MH commands, @command{whom} -@cindex buffers, @samp{*MH-E Recipients*} -@cindex checking recipients -@cindex recipients, checking -@findex mh-check-whom -@kindex C-c C-w - -The command @kbd{C-c C-w} (@code{mh-check-whom}) expands aliases so -you can check the actual address(es) in the alias. A new buffer named -@samp{*MH-E Recipients*} is created with the output of @command{whom} -(@pxref{Miscellaneous})@footnote{See the section -@uref{@value{MH-BOOK-HOME}/senove.html#WhaPro, What now? -- and the -whatnow Program} in the MH book.}. - -@node Sending Message, Killing Draft, Checking Recipients, Editing Drafts -@section Sending a Message - -@cindex buffers, @samp{*MH-E Mail Delivery*} -@cindex @samp{*MH-E Mail Delivery*} -@cindex sending mail -@findex mh-send-letter -@kindex C-c C-c - -When you are all through editing a message, you send it with the -command @kbd{C-c C-c} (@code{mh-send-letter}). You can give a prefix -argument (as in @kbd{C-u C-c C-c}) to monitor the first stage of the -delivery; this output can be found in a buffer called @samp{*MH-E Mail -Delivery*} (@pxref{Miscellaneous}). - -@cindex sending mail -@cindex spell check -@findex ispell-message -@kindex C-c C-c -@vindex mh-before-send-letter-hook - -The hook @code{mh-before-send-letter-hook} is run at the beginning of -the command @kbd{C-c C-c}. For example, if you want to check your -spelling in your message before sending, add the function -@code{ispell-message}. - -@cindex @command{send} -@cindex MH commands, @command{send} -@vindex mh-send-prog - -In case the MH @command{send} program@footnote{See the section -@uref{@value{MH-BOOK-HOME}/sensen.html, Sending Some Mail: comp send} -in the MH book.} is installed under a different name, use -@code{mh-send-prog} to tell MH-E the name. - -The hook @code{mh-annotate-msg-hook} is run after annotating the -message and scan line (@pxref{Sending Mail}). - -@node Killing Draft, , Sending Message, Editing Drafts -@section Killing the Draft - -@cindex killing draft -@findex kill-buffer -@findex mh-fully-kill-draft -@kindex C-c C-q -@kindex C-x k - -If for some reason you are not happy with the draft, you can use the -command @kbd{C-c C-q} (@code{mh-fully-kill-draft}) to kill the draft -buffer and delete the draft message. Use the command @kbd{C-x k} -(@code{kill-buffer}) if you don't want to delete the draft message. - -@node Aliases, Identities, Editing Drafts, Top -@chapter Aliases - -@cindex aliases - -MH aliases are used in the same way in MH-E as they are in MH. Any -alias listed as a recipient will be expanded when the message is sent. -This chapter discusses other things you can do with aliases in MH-E. - -@cindex MH-Letter mode -@cindex modes, MH-Letter - -The following commands are available in MH-Letter mode with the -exception of @code{mh-alias-reload} which can be called from anywhere. - -@table @kbd -@kindex @key{SPC} -@findex mh-letter-complete-or-space -@item @key{SPC} -Perform completion or insert space (@code{mh-letter-complete-or-space}). -@c ------------------------- -@kindex M-@key{TAB} -@findex mh-letter-complete -@item M-@key{TAB} -Perform completion on header field or word preceding point -(@code{mh-letter-complete}). -@c ------------------------- -@findex mh-alias-apropos -@item mh-alias-apropos -Show all aliases or addresses that match a regular expression. -@c ------------------------- -@findex mh-alias-grab-from-field -@item mh-alias-grab-from-field -Add alias for the sender of the current message -@c ------------------------- -@findex mh-alias-reload -@item mh-alias-reload -Reload MH aliases. -@end table - -@cindex @samp{mh-alias} customization group -@cindex customization group, @samp{mh-alias} - -The @samp{mh-alias} customization group contains options associated -with aliases. - -@vtable @code -@item mh-alias-completion-ignore-case-flag -On means don't consider case significant in MH alias completion -(default: @samp{on}). -@c ------------------------- -@item mh-alias-expand-aliases-flag -On means to expand aliases entered in the minibuffer (default: -@samp{off}). -@c ------------------------- -@item mh-alias-flash-on-comma -Specify whether to flash address or warn on translation (default: @samp{Flash -but Don't Warn If No Alias}). -@c ------------------------- -@item mh-alias-insert-file -Filename used to store a new MH-E alias (default: @samp{Use Aliasfile -Profile Component}). -@c ------------------------- -@item mh-alias-insertion-location -Specifies where new aliases are entered in alias files (default: -@samp{Alphabetical}). -@c ------------------------- -@item mh-alias-local-users -If @samp{on}, local users are added to alias completion (default: -@samp{on}). -@c ------------------------- -@item mh-alias-local-users-prefix -String prefixed to the real names of users from the password file -(default: @code{"local."}. -@c ------------------------- -@item mh-alias-passwd-gecos-comma-separator-flag -On means the GECOS field in the password file uses a comma separator -(default: @samp{on}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-alias-reloaded-hook -Hook run by @code{mh-alias-reload} after loading aliases (default: -@code{nil}). -@end vtable - -@subheading Adding Addresses to Draft - -You can use aliases when you are adding recipients to a message. - -@findex minibuffer-complete -@kindex @key{TAB} -@vindex mh-alias-expand-aliases-flag -@vindex mh-compose-prompt-flag - -In order to use minibuffer prompting for recipients and the subject -line in the minibuffer, turn on the option -@code{mh-compose-prompt-flag} (@pxref{Composing}), and use the -@key{TAB} (@code{minibuffer-complete}) command to complete aliases -(and optionally local logins) when prompted for the recipients. Turn -on the option @code{mh-alias-expand-aliases-flag} if you want these -aliases to be expanded to their respective addresses in the draft. - -@findex mh-letter-complete -@findex mh-letter-complete-or-space -@kindex @key{SPC} -@kindex M-@key{TAB} - -Otherwise, you can complete aliases in the header of the draft with -@kbd{M-@key{TAB}} (@code{mh-letter-complete}) or @key{SPC} -(@code{mh-letter-complete-or-space}). - -@vindex mh-alias-completion-ignore-case-flag - -As MH ignores case in the aliases, so too does MH-E. However, you may -turn off the option @code{mh-alias-completion-ignore-case-flag} to -make case significant which can be used to segregate completion of -your aliases. You might use uppercase for mailing lists and lowercase -for people. For example, you might have: - -@smallexample -mark.baushke: Mark Baushke -MH-E: MH-E Mailing List -@end smallexample - -When this option is turned off, if you were to type @kbd{M} in the -@samp{To:} field and then @kbd{M-@key{TAB}}, then you'd get the list; -if you started with @kbd{m} and then entered @kbd{M-@key{TAB}}, then -you'd get Mark's address. Note that this option affects completion -only. If you were to enter @kbd{Mark.Baushke}, it would still be -identified with your @samp{mark.baushke} alias. - -@findex mh-alias-minibuffer-confirm-address -@findex mh-letter-confirm-address -@vindex mh-alias-flash-on-comma -@vindex mh-compose-prompt-flag - -To verify that the alias you've entered is valid, the alias will be -displayed in the minibuffer when you type a comma -(@code{mh-letter-confirm-address} or -@code{mh-alias-minibuffer-confirm-address} if the option -@code{mh-compose-prompt-flag} is turned on). @xref{Composing}. This -behavior can be controlled with the option -@code{mh-alias-flash-on-comma} which provides three choices: -@samp{Flash but Don't Warn If No Alias}, @samp{Flash and Warn If No -Alias}, and @samp{Don't Flash Nor Warn If No Alias}. - -For another way to verify the alias expansion, see @ref{Checking -Recipients}. - -@subheading Loading Aliases - -@cindex @command{ali} -@cindex @file{/etc/nmh/MailAliases} -@cindex @samp{Aliasfile:} MH profile component -@cindex MH commands, @command{ali} -@cindex MH profile component, @samp{Aliasfile:} -@cindex files, @file{/etc/nmh/MailAliases} - -MH-E loads aliases for completion and folder name hints from various -places. It uses the MH command @command{ali}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/mh.html, MH Aliases} in the MH book.} to -read aliases from the files listed in the profile component -@samp{Aliasfile:} as well as system-wide aliases (for example, -@file{/etc/nmh/MailAliases}). - -@cindex @file{/etc/passwd} -@cindex files, @file{/etc/passwd} - -In addition, aliases are created from @file{/etc/passwd} entries with -a user ID larger than a magical number, typically 200. This can be a -handy tool on a machine where you and co-workers exchange messages. -These aliases have the form @samp{local.@var{first.last}} if a real -name is present in the password file. Otherwise, the alias will have -the form @samp{local.@var{login}}. - -@vindex mh-alias-local-users-prefix - -The prefix @samp{local.} can be modified via the option -@code{mh-alias-local-users-prefix}. This option can also be set to -@samp{Use Login}. - -For example, consider the following password file entry: - -@smallexample -psg:x:1000:1000:Peter S Galbraith,,,:/home/psg:/bin/tcsh -@end smallexample - -@vindex mh-alias-local-users-prefix - -The following settings of option @code{mh-alias-local-users-prefix} -will produce the associated aliases: - -@table @code -@item "local." -local.peter.galbraith -@c ------------------------- -@item "" -peter.galbraith -@c ------------------------- -@item Use Login -psg -@end table - -@vindex mh-alias-passwd-gecos-comma-separator-flag - -In the example above, commas are used to separate different values -within the so-called GECOS field. This is a fairly common usage. -However, in the rare case that the GECOS field in your password file -is not separated by commas and whose contents may contain commas, you -can turn the option @code{mh-alias-passwd-gecos-comma-separator-flag} -off. - -@cindex NIS, obtaining local aliases from -@cindex @samp{ypcat passwd} -@vindex mh-alias-local-users - -If you're on a system with thousands of users you don't know, and the -loading of local aliases slows MH-E down noticeably, then the local -alias feature can be disabled by turning off the option -@code{mh-alias-local-users}. This option also takes a string which is -executed to generate the password file. For example, use @samp{ypcat -passwd} to obtain the NIS password file. - -@findex mh-alias-reload -@kindex M-x mh-alias-reload -@vindex mh-alias-reloaded-hook - -Since aliases are updated frequently, MH-E reloads aliases -automatically whenever an alias lookup occurs if an alias source has -changed. However, you can reload your aliases manually by calling the -command @kbd{M-x mh-alias-reload} directly. This command runs -@code{mh-alias-reloaded-hook} after the aliases have been loaded. - -@subheading Adding Aliases - -In the past, you have manually added aliases to your alias file(s) -listed in your @samp{Aliasfile:} profile component. MH-E provides -other methods for maintaining your alias file(s). - -@findex mh-alias-add-alias -@kindex M-x mh-alias-add-alias - -You can use the @kbd{M-x mh-alias-add-alias} command which will prompt -you for the alias and address that you would like to add. If the alias -exists already, you will have the choice of inserting the new alias -before or after the old alias. In the former case, this alias will be -used when sending mail to this alias. In the latter case, the alias -serves as an additional folder name hint when filing messages -(@pxref{Folder Selection}). - -Earlier, the alias prefix @samp{local} was presented. You can use -other prefixes to organize your aliases or disambiguate entries. You -might use prefixes for locales, jobs, or activities. For example, I -have: - -@smallexample -@group -; Work -attensity.don.mitchell: Don Mitchell -isharp.don.mitchell: Don Mitchell -... -; Sport -diving.ken.mayer: Ken Mayer -sailing.mike.maloney: Mike Maloney -... -; Personal -ariane.kolkmann: Ariane Kolkmann -... -@end group -@end smallexample - -Using prefixes instead of postfixes helps you explore aliases during -completion. If you forget the name of an old dive buddy, you can enter -@samp{div} and then @key{SPC} to get a listing of all your dive buddies. - -@kindex M-x mh-alias-add-address-under-point -@kindex M-x mh-alias-grab-from-field - -An alias for the sender of the current message is added automatically -by clicking on the @samp{Grab From alias} tool bar button or by running -the @kbd{M-x mh-alias-grab-from-field} command. Aliases for other -recipients of the current message are added by placing your cursor -over the desired recipient and giving the @kbd{M-x -mh-alias-add-address-under-point} command. - -@vindex mh-alias-insert-file -@vindex mh-alias-insertion-location - -The options @code{mh-alias-insert-file} and -@code{mh-alias-insertion-location} controls how and where these aliases -are inserted. - -@vindex mh-alias-insert-file - -The default setting of option @code{mh-alias-insert-file} is @samp{Use -Aliasfile Profile Component}. This option can also hold the name of a -file or a list a file names. If this option is set to a list of file -names, or the @samp{Aliasfile:} profile component contains more than -one file name, MH-E will prompt for one of them. - -@vindex mh-alias-insertion-location - -The option @code{mh-alias-insertion-location} is set to -@samp{Alphabetical} by default. If you organize your alias file in -other ways, then the settings @samp{Top} and @samp{Bottom} might be -more appropriate. - -@subheading Querying Aliases - -@cindex regular expressions, @code{mh-alias-apropos} -@findex mh-alias-apropos -@kindex M-x mh-alias-apropos - -If you can't quite remember an alias, you can use @kbd{M-x -mh-alias-apropos} to show all aliases or addresses that match a -regular expression -@ifnothtml -(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in -@cite{The GNU Emacs Manual}). -@end ifhtml - -@node Identities, Speedbar, Aliases, Top -@chapter Identities - -@cindex identities -@cindex multiple personalities - -MH-E supports the concept of multiple personalities or identities. -This means that you can easily have a different header and signature -at home and at work. - -@cindex @samp{Identity} menu -@cindex menu, @samp{Identity} - -A couple of commands are used to insert identities in MH-Letter mode -which are also found in the @samp{Identity} menu. - -@table @kbd -@kindex C-c C-d -@findex mh-insert-identity -@item C-c C-d -Insert fields specified by given identity (@code{mh-insert-identity}). -@c ------------------------- -@cindex @samp{Identity > Insert Auto Fields} menu item -@cindex menu item, @samp{Identity > Insert Auto Fields} -@kindex C-c M-d -@findex mh-insert-auto-fields -@item C-c M-d -Insert custom fields if recipient found in @code{mh-auto-fields-list} -(@code{mh-insert-auto-fields}). -@end table - -@cindex @samp{mh-identity} customization group -@cindex customization group, @samp{mh-identity} - -The @samp{mh-identity} customization group contains the following -options. - -@vtable @code -@item mh-auto-fields-list -List of recipients for which header lines are automatically inserted -(default: @code{nil}). -@c ------------------------- -@item mh-auto-fields-prompt-flag -On means to prompt before sending if fields inserted (default: -@samp{on}) -@c ------------------------- -@item mh-identity-default -Default identity to use when @code{mh-letter-mode} is called (default: -@samp{None}). -@c ------------------------- -@item mh-identity-handlers -Handler functions for fields in @code{mh-identity-list}. -@c ------------------------- -@item mh-identity-list -List of identities (default: @code{nil}). -@end vtable - -Some of the common header fields that people change depending on the -context are the @samp{From:} and @samp{Organization:} fields, as well -as the signature. - -@vindex mh-identity-list - -This is done by customizing the option @code{mh-identity-list}. In the -customization buffer for this option, click on the @samp{INS} button -and enter a label such as @samp{Home} or @samp{Work}. Then click on -the @samp{INS} button with the label @samp{Add at least one item -below}. The @samp{Value Menu} has the following menu items: - -@table @samp -@cindex header field, @samp{From:} -@cindex @samp{From:} header field -@item From Field -Specify an alternate @samp{From:} header field. You must include a -valid email address. A standard format is @samp{First Last -}. If you use an initial with a period, then you -must quote your name as in @samp{"First I. Last" -}. -@c ------------------------- -@cindex header field, @samp{Organization:} -@cindex @samp{Organization:} header field -@item Organization Field -People usually list the name of the company where they work here. -@c ------------------------- -@item Other Field -Set any arbitrary header field and value here. Unless the header field -is a standard one, precede the name of your field's label with -@samp{X-}, as in @samp{X-Fruit-of-the-Day:}. -@c ------------------------- -@item Attribution Verb -This value overrides the setting of -@code{mh-extract-from-attribution-verb}. @xref{Inserting Letter}. -@c ------------------------- -@cindex signature -@vindex mh-signature-file-name -@item Signature -Set your signature with this item. You can specify the contents of -@code{mh-signature-file-name}, a file, or a function. -@xref{Signature}. -@c ------------------------- -@item GPG Key ID -Specify a different key to sign or encrypt messages. -@end table - -@cindex Identity menu -@cindex menu, Identity -@findex mh-insert-identity -@kindex C-c C-d - -You can select the identities you have added via the menu called -@samp{Identity} in the MH-Letter buffer. You can also use @kbd{C-c -C-d} (@code{mh-insert-identity}). To clear the fields and signature -added by the identity, select the @samp{None} identity. - -@cindex menu item, @samp{Identity > Customize Identities} -@cindex menu item, @samp{Identity > Save as Default} -@cindex menu item, @samp{Identity > Set Default for Session} -@cindex @samp{Identity > Customize Identities} menu item -@cindex @samp{Identity > Save as Default} menu item -@cindex @samp{Identity > Set Default for Session} menu item -@vindex mh-identity-default - -The @samp{Identity} menu contains two other items to save you from -having to set the identity on every message. The menu item @samp{Set -Default for Session} can be used to set the default identity to the -current identity until you exit Emacs. The menu item @samp{Save as -Default} sets the option @code{mh-identity-default} to the current -identity setting. You can also customize the option -@code{mh-identity-default} in the usual fashion. If you find that you -need to add another identity, the menu item @samp{Customize -Identities} is available for your convenience. - -@cindex regular expressions, @code{mh-auto-fields-list} -@vindex mh-auto-fields-list - -The option @code{mh-auto-fields-list} can also be used to set the -identity depending on the recipient to provide even more control. To -customize @code{mh-auto-fields-list}, click on the @samp{INS} button -and enter a regular expression for the recipient's address -@ifnothtml -(@pxref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}). -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in -@cite{The GNU Emacs Manual}). -@end ifhtml -Click on the @samp{INS} button with the @samp{Add at least one item -below} label. The @samp{Value Menu} contains the following menu items: - -@table @samp -@item Identity -Select an identity from those configured in @code{mh-identity-list}. -All of the information for that identity will be added if the -recipient matches. -@c ------------------------- -@cindex @samp{Fcc:} header field -@cindex header field, @samp{Fcc:} -@item Fcc Field -Insert an @samp{Fcc:} header field with the folder you provide. When -you send the message, MH will put a copy of your message in this -folder. -@c ------------------------- -@cindex @samp{Mail-Followup-To:} header field -@cindex header field, @samp{Mail-Followup-To:} -@item Mail-Followup-To Field -Insert an @samp{Mail-Followup-To:} header field with the recipients -you provide. If the recipient's mail user agent supports this header -field@footnote{@samp{Mail-Followup-To:} is supported by nmh.}, then -their replies will go to the addresses listed. This is useful if their -replies go both to the list and to you and you don't have a mechanism -to suppress duplicates. If you reply to someone not on the list, you -must either remove the @samp{Mail-Followup-To:} field, or ensure the -recipient is also listed there so that he receives replies to your -reply. -@c ------------------------- -@item Other Field -Other header fields may be added using this menu item. -@end table - -@findex mh-insert-auto-fields -@kindex C-c M-d -@vindex mh-auto-fields-prompt-flag - -These fields can only be added after the recipient is known. Because -you can continue to add recipients as you edit the draft, MH-E waits -until the message is sent to perform the auto-insertions. This seems -strange at first, but you'll get used to it. There are two ways to -help you feel that the desired fields are added. The first is the -action when the message is sent: if any fields are added -automatically, you are given a chance to see and to confirm these -fields before the message is actually sent. You can do away with this -confirmation by turning off the option -@code{mh-auto-fields-prompt-flag}. The second method is manual: once -the header contains one or more recipients, you may run the command -@kbd{C-c M-d} (@code{mh-insert-auto-fields}) or choose the -@samp{Identity -> Insert Auto Fields} menu item to insert these fields -manually. However, if you use this command, the automatic insertion -when the message is sent is disabled. - -@vindex mh-auto-fields-list -@vindex mh-identity-list - -You should avoid using the same header field in -@code{mh-auto-fields-list} and @code{mh-identity-list} definitions -that may apply to the same message as the result is undefined. - -@vindex mh-identity-handlers -@vindex mh-identity-list - -The option @code{mh-identity-handlers} is used to change the way that -fields, signatures, and attributions in @code{mh-identity-list} are -added. To customize @code{mh-identity-handlers}, replace the name of -an existing handler function associated with the field you want to -change with the name of a function you have written. You can also -click on an @samp{INS} button and insert a field of your choice and -the name of the function you have written to handle it. - -@vindex mh-identity-list - -The @samp{Field} field can be any field that you've used in your -@code{mh-identity-list}. The special fields @samp{:attribution-verb}, -@samp{:signature}, or @samp{:pgg-default-user-id} are used for the -@code{mh-identity-list} choices @samp{Attribution Verb}, -@samp{Signature}, and @samp{GPG Key ID} respectively. - -The handler associated with the @samp{:default} field is used when no -other field matches. - -The handler functions are passed two or three arguments: the field -itself (for example, @samp{From}), or one of the special fields (for -example, @samp{:signature}), and the action @samp{'remove} or -@samp{'add}. If the action is @samp{'add}, an additional argument -containing the value for the field is given. - -@node Speedbar, Menu Bar, Identities, Top -@chapter The Speedbar - -@cindex folder navigation -@cindex speedbar -@findex mh-visit-folder -@kindex F v -@kindex M-x speedbar -@kindex Mouse-2 - -You can also use the speedbar -@ifnothtml -(@pxref{Speedbar, , Speedbar Frames, emacs, The GNU Emacs Manual},) -@end ifnothtml -@ifhtml -(see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Speedbar.html, -Speedbar Frames} in @cite{The GNU Emacs Manual}) -@end ifhtml -to view your folders. To bring up the speedbar, run @kbd{M-x speedbar -@key{RET}}. You will see a new frame appear with all of your MH -folders. Folders with unseen messages appear in boldface. Click on a -folder name with @kbd{Mouse-2} to visit that folder in a similar -fashion to the command @kbd{F v} (@code{mh-visit-folder}) -(@pxref{Folders}). Click on the @samp{+} icon to expand and view the -sub-folders of that folder. - -The speedbar can be manipulated with the keyboard as well. Use the -Emacs navigational keys (like the arrow keys, or @kbd{C-n}) to move -the cursor over the desired folder and then use the shortcuts for the -menu items listed in the table below. - -@table @samp -@findex mh-speed-view -@item Visit Folder (@key{RET}) -Visits the selected folder just as if you had used @kbd{F v} -(@code{mh-speed-view}). -@c ------------------------- -@findex mh-speed-expand-folder -@item Expand Nested Folders (@kbd{+}) -Expands the selected folder in the speedbar, exposing the children -folders inside it (@code{mh-speed-expand-folder}). -@c ------------------------- -@findex mh-speed-contract-folder -@item Contract Nested Folders (@kbd{-}) -Contracts or collapses the selected folder in the speedbar, hiding the -children folders inside it (@code{mh-speed-contract-folder}). -@c ------------------------- -@findex mh-speed-refresh -@item Refresh Speedbar (@kbd{r}) -Regenerates the list of folders in the speedbar. Run this command if -you've added or deleted a folder, or want to update the unseen message -count before the next automatic update (@code{mh-speed-refresh}). -@end table - -@findex delete-frame -@kindex C-x 5 0 -@kindex Mouse-3 - -You can click on @kbd{Mouse-3} to bring up a context menu that -contains these items. Dismiss the speedbar with @kbd{C-x 5 0} -(@code{delete-frame}). - -@cindex @command{flists} -@cindex MH commands, @command{flists} -@cindex @samp{mh-speedbar} customization group -@cindex customization group, @samp{mh-speedbar} - -The MH-E speedbar uses the MH command @command{flists}@footnote{See -the section @uref{@value{MH-BOOK-HOME}/morseq.html#flist, Searching for -Sequences with flist} in the MH book.} to generate the list of -folders. The @samp{mh-speedbar} customization group contains the -following option which controls how often the speedbar calls -@command{flists}. - -@vtable @code -@item mh-speed-update-interval -Time between speedbar updates in seconds (default: 60). Set to 0 to -disable automatic update. -@end vtable - -You can modify the appearance of the folders in the speedbar by -customizing the following faces. - -@vtable @code -@item mh-speedbar-folder -Basic folder face. -@c ------------------------- -@item mh-speedbar-folder-with-unseen-messages -Folder face when folder contains unread messages. -@c ------------------------- -@item mh-speedbar-selected-folder -Selected folder face. -@c ------------------------- -@item mh-speedbar-selected-folder-with-unseen-messages -Selected folder face when folder contains unread messages. -@end vtable - -@node Menu Bar, Tool Bar, Speedbar, Top -@chapter The Menu Bar - -@cindex @samp{Folder} menu -@cindex @samp{Identity} menu -@cindex @samp{Letter} menu -@cindex @samp{Message} menu -@cindex @samp{Search} menu -@cindex @samp{Sequence} menu -@cindex Folder menu -@cindex Identity menu -@cindex Letter menu -@cindex MH-Folder mode -@cindex MH-Letter mode -@cindex MH-Search mode -@cindex Message menu -@cindex Search menu -@cindex Sequence menu -@cindex menu bar -@cindex menu, Folder -@cindex menu, Identity -@cindex menu, Letter -@cindex menu, Message -@cindex menu, Search -@cindex menu, Sequence -@cindex menu, @samp{Folder} -@cindex menu, @samp{Identity} -@cindex menu, @samp{Letter} -@cindex menu, @samp{Message} -@cindex menu, @samp{Search} -@cindex menu, @samp{Sequence} -@cindex modes, MH-Folder -@cindex modes, MH-Letter -@cindex modes, MH-Search - -For those of you who prefer to mouse and menu instead of using the -meta-coke-bottle-bucky keys, MH-E provides menu items for most of its -functions. The MH-Folder buffer adds the @samp{Folder}, -@samp{Message}, and @samp{Sequence} menus. The MH-Letter buffer adds -the @samp{Identity} and @samp{Letter} menus. The MH-Search buffer adds -the @samp{Search} menu. There's no need to list the actual items here, -as you can more easily see them for yourself, and the functions are -already described elsewhere in this manual. - -For a description of the menu bar, please -@ifnothtml -@xref{Menu Bar, , The Menu Bar, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Menu-Bar.html, -The Menu Bar} in @cite{The GNU Emacs Manual}. -@end ifhtml - -The Emacs manual describes how to get online help for a particular -menu item. You can also look up a menu item in the index of this -manual in two ways: all of the menu items are listed alphabetically, -and you can also browse all of the items under the index entry -@samp{menu item}. - -@node Tool Bar, Searching, Menu Bar, Top -@chapter The Tool Bar - -@cindex tool bar - -Emacs also provides a graphical tool bar. For a description of the -tool bar, please -@ifnothtml -@xref{Tool Bars, , Tool Bars, emacs, The GNU Emacs Manual}. -@end ifnothtml -@ifhtml -see the section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Tool-Bars.html, -Tool Bars} in @cite{The GNU Emacs Manual}. -@end ifhtml - -@cindex @samp{mh-tool-bar} customization group -@cindex customization group, @samp{mh-tool-bar} - -MH-E adds several icons to this tool bar; you can modify the MH-E -aspects of the tool bar via the @samp{mh-tool-bar} customization group. - -@vtable @code -@item mh-tool-bar-folder-buttons -List of buttons to include in MH-Folder tool bar (default: a checklist -too long to list here). -@c ------------------------- -@item mh-tool-bar-letter-buttons -List of buttons to include in MH-Letter tool bar (default: a checklist -too long to list here). -@c ------------------------- -@item mh-tool-bar-search-function -Function called by the tool bar search button (default: -@code{mh-search}). -@c ------------------------- -@item mh-xemacs-tool-bar-position -Tool bar location (default: @samp{Same As Default Tool Bar}). -@c ------------------------- -@item mh-xemacs-use-tool-bar-flag -If @samp{on}, use tool bar (default: @samp{on}, if supported). -@end vtable - -In GNU Emacs, icons for some of MH-E's functions are added to the tool -bar. In XEmacs, you have the opportunity to create a separate tool bar for -the MH-E icons. - -@vindex mh-tool-bar-folder-buttons -@vindex mh-tool-bar-letter-buttons - -In either case, you can select which of these functions you'd like to -see by customizing the options @code{mh-tool-bar-folder-buttons} and -@code{mh-tool-bar-letter-buttons}. As you probably guessed, the former -customizes the tool bar in MH-Folder mode and the latter in MH-Letter -mode. Both of these options present you with a list of functions; -check the functions whose icons you want to see and clear the check -boxes for those you don't. - -@findex mh-search -@vindex mh-tool-bar-search-function - -The function associated with the searching icon can be set via the -option @code{mh-tool-bar-search-function}. By default, this is set to -@code{mh-search}. @xref{Searching}. You can also choose @samp{Other -Function} from the @samp{Value Menu} and enter a function of your own -choosing. - -@vindex mh-xemacs-use-tool-bar-flag - -XEmacs provides a couple of extra options. The first, -@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E -icons at all. By default, this option is turned on if the window -system supports tool bars. If your system doesn't support tool bars, -then you won't be able to turn on this option. - -@vindex mh-xemacs-tool-bar-position - -The second extra option is @code{mh-xemacs-tool-bar-position} which -controls the placement of the tool bar along the four edges of the -frame. You can choose from one of @samp{Same As Default Tool Bar}, -@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this -variable is set to anything other than @samp{Same As Default Tool Bar} -and the default tool bar is in a different location, then two tool -bars will be displayed: the MH-E tool bar and the default tool bar. - -@node Searching, Threading, Tool Bar, Top -@chapter Searching Through Messages - -@cindex @samp{Search} menu -@cindex menu, @samp{Search} -@cindex searching -@findex mh-search -@kindex F s - -Earlier, the command @kbd{F s} (@code{mh-search}) was introduced which -helps you find messages that lie buried in your folders -(@pxref{Folders}). This chapter covers this command in more detail. -Several commands are used to compose the search criteria and to start -searching. A couple of them can be found in the @samp{Search} menu. - -@table @kbd -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@cindex @samp{Search > Perform Search} menu item -@cindex menu item, @samp{Search > Perform Search} -@kindex C-c C-c -@findex mh-index-do-search -@item C-c C-c -Find messages using @code{mh-search-program} -(@code{mh-index-do-search}). -@c ------------------------- -@cindex @samp{Search > Search with pick} menu item -@cindex menu item, @samp{Search > Search with pick} -@kindex C-c C-p -@findex mh-pick-do-search -@item C-c C-p -Find messages using @command{pick} (@code{mh-pick-do-search}). -@c ------------------------- -@kindex C-c ? -@findex mh-help -@item C-c ? -Display cheat sheet for the MH-E commands (@code{mh-help}). -@c ------------------------- -@kindex C-c C-f C-a -@kindex C-c C-f a -@findex mh-to-field -@item C-c C-f a -@itemx C-c C-f C-a -Move to @samp{Mail-Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-b -@kindex C-c C-f b -@item C-c C-f b -@itemx C-c C-f C-b -Move to @samp{Bcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-c -@kindex C-c C-f c -@item C-c C-f c -@itemx C-c C-f C-c -Move to @samp{Cc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-d -@kindex C-c C-f d -@item C-c C-f d -@itemx C-c C-f C-d -Move to @samp{Dcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-f -@kindex C-c C-f f -@item C-c C-f f -@itemx C-c C-f C-f -Move to @samp{Fcc:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-l -@kindex C-c C-f l -@item C-c C-f l -@itemx C-c C-f C-l -Move to @samp{Mail-Followup-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-m -@kindex C-c C-f m -@item C-c C-f m -@itemx C-c C-f C-m -Move to @samp{From:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-r -@kindex C-c C-f r -@item C-c C-f r -@itemx C-c C-f C-r -Move to @samp{Reply-To:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-s -@kindex C-c C-f s -@item C-c C-f s -@itemx C-c C-f C-s -Move to @samp{Subject:} header field (@code{mh-to-field}). -@c ------------------------- -@kindex C-c C-f C-t -@kindex C-c C-f t -@item C-c C-f t -@itemx C-c C-f C-t -Move to @samp{To:} header field (@code{mh-to-field}). -@end table - -Another few commands are available in the MH-Folder buffer resulting -from a search. - -@table @kbd -@kindex @key{TAB} -@findex mh-index-next-folder -@item @key{TAB} -Jump to the next folder marker (@code{mh-index-next-folder}). -@c ------------------------- -@kindex S-@key{TAB} -@findex mh-index-previous-folder -@item S-@key{TAB} -Jump to the previous folder marker (@code{mh-index-previous-folder}). -@c ------------------------- -@kindex v -@findex mh-index-visit-folder -@item v -Visit original folder from where the message at point was found -(@code{mh-index-visit-folder}). -@end table - -@cindex @samp{mh-search} customization group -@cindex customization group, @samp{mh-search} - -There is one option from the @samp{mh-search} customization group used -in searching. - -@vtable @code -@item mh-search-program -Search program that MH-E shall use (default: @samp{Auto-detect}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-search-mode-hook -Hook run upon entry to @code{mh-search-mode} (default: @code{nil}). -@end vtable - -The following face is available. - -@vtable @code -@item mh-search-folder -Folder heading face in MH-Folder buffers created by searches. -@end vtable - -@findex mh-search-folder -@kindex F s - -The command @kbd{F s} (@code{mh-search-folder}) helps you find -messages in your entire corpus of mail. You can search for messages to -or from a particular person or about a particular subject. In fact, -you can also search for messages containing selected strings in any -arbitrary header field or any string found within the messages. - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -Out of the box, MH-E uses @command{pick} to find messages. With a -little extra effort, you can set an indexing program which rewards you -with extremely quick results. The drawback is that sometimes the index -does not contain the words you're looking for. You can still use -@command{pick} in these situations. - -You are prompted for the folder to search. This can be @samp{all} to -search all folders. Note that the search works recursively on the -listed folder. - -@cindex MH-Search mode -@cindex modes, MH-Search - -Next, an MH-Search buffer appears where you can enter search criteria. - -@cartouche -@smallexample -From: -To: -Cc: -Date: -Subject: --------- -# - - - - - - - - ---:** search-pattern All L7 (MH-Search)--------------------------- -Type C-c C-c to search messages, C-c C-p to use pick, C-c ? for help -@end smallexample -@end cartouche -@i{Search window} - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -Edit this template by entering your search criteria in an appropriate -header field that is already there, or create a new field yourself. If -the string you're looking for could be anywhere in a message, then -place the string underneath the row of dashes. - -As an example, let's say that we want to find messages from Ginnean -about horseback riding in the Kosciusko National Park (Australia) -during January, 1994. Normally we would start with a broad search and -narrow it down if necessary to produce a manageable amount of data, -but we'll cut to the chase and create a fairly restrictive set of -criteria as follows: - -@smallexample -@group -From: ginnean -To: -Cc: -Date: Jan 1994 -Subject: --------- -horse -kosciusko -@end group -@end smallexample - -@findex mh-to-field -@kindex C-c C-f C-t - -As with MH-Letter mode, MH-Search provides commands like @kbd{C-c C-f -C-t} (@code{mh-to-field}) to help you fill in the blanks. -@xref{Editing Message}. - -@kindex F s -@vindex mh-search-mode-hook - -If you find that you do the same thing over and over when editing the -search template, you may wish to bind some shortcuts to keys. This can -be done with the variable @code{mh-search-mode-hook}, which is called -when @kbd{F s} is run on a new pattern. - -@findex mh-index-do-search -@findex mh-pick-do-search -@kindex C-c C-c -@kindex C-c C-p - -To perform the search, type @kbd{C-c C-c} (@code{mh-index-do-search}). -Sometimes you're searching for text that is either not indexed, or -hasn't been indexed yet. In this case you can override the default -method with the pick method by running the command @kbd{C-c C-p} -(@code{mh-pick-do-search}). - -@cindex folders, @samp{+mhe-index} -@cindex @samp{+mhe-index} -@findex mh-index-next-folder -@findex mh-index-previous-folder -@kindex @key{TAB} -@kindex S-@key{TAB} -@vindex mh-search-folder - -The messages that are found are put in a temporary sub-folder of -@samp{+mhe-index} and are displayed in an MH-Folder buffer. This -buffer is special because it displays messages from multiple folders; -each set of messages from a given folder has a heading with the folder -name. The appearance of the heading can be modified by customizing the -face @code{mh-search-folder}. You can jump back and forth between the -headings using the commands @kbd{@key{TAB}} -(@code{mh-index-next-folder}) and @kbd{S-@key{TAB}} -(@code{mh-index-previous-folder}). - -@findex mh-index-visit-folder -@findex mh-rescan-folder -@kindex F r -@kindex v - -In addition, the command @kbd{v} (@code{mh-index-visit-folder}) can be -used to visit the folder of the message at point. Initially, only the -messages that matched the search criteria are displayed in the folder. -While the temporary buffer has its own set of message numbers, the -actual messages numbers are shown in the visited folder. Thus, the -command @kbd{v} is useful to find the actual message number of an -interesting message, or to view surrounding messages with the command -@kbd{F r} @code{mh-rescan-folder}. @xref{Folders}. - -@findex mh-kill-folder -@kindex F k - -Because this folder is temporary, you'll probably get in the habit of -killing it when you're done with @kbd{F k} (@code{mh-kill-folder}). -@xref{Folders}. - -@kindex F s - -You can regenerate the results by running @kbd{F s} with a prefix -argument. - -@cindex @command{procmail} -@cindex Unix commands, @command{procmail} -@cindex @samp{X-MHE-Checksum:} header field -@cindex header field, @samp{X-MHE-Checksum:} - -Note: This command uses an @samp{X-MHE-Checksum:} header field to -cache the MD5 checksum of a message. This means that if an incoming -message already contains an @samp{X-MHE-Checksum:} field, that message -might not be found by this command. The following @command{procmail} -recipe avoids this problem by renaming the existing header field: - -@smallexample -@group -:0 wf -| formail -R "X-MHE-Checksum" "X-Old-MHE-Checksum" -@end group -@end smallexample - -@xref{Limits}, for an alternative interface to searching. - -@section Configuring Indexed Searches - -@cindex @command{grep} -@cindex @command{mairix} -@cindex @command{namazu} -@cindex @command{pick} -@cindex @command{swish++} -@cindex @command{swish-e} -@cindex Unix commands, @command{grep} -@cindex Unix commands, @command{mairix} -@cindex Unix commands, @command{namazu} -@cindex Unix commands, @command{pick} -@cindex Unix commands, @command{swish++} -@cindex Unix commands, @command{swish-e} -@findex mh-search -@kindex F s -@vindex mh-search-program - -The command @kbd{F s} (@code{mh-search}) runs the command defined by -the option @code{mh-search-program}. The default value is -@samp{Auto-detect} which means that MH-E will automatically choose one -of @command{swish++}, @command{swish-e}, @command{mairix}, -@command{namazu}, @command{pick} and @command{grep} in that order. If, -for example, you have both @command{swish++} and @command{mairix} -installed and you want to use @command{mairix}, then you can set this -option to @samp{mairix}. - -The following sub-sections describe how to set up the various indexing -programs to use with MH-E. - -@subsection swish++ - -@cindex @command{swish++} -@cindex Unix commands, @command{swish++} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.swish++}. Then -create the file @file{/home/user/Mail/.swish++/swish++.conf} with the -following contents: - -@smallexample -@group -IncludeMeta Bcc Cc Comments Content-Description From Keywords -IncludeMeta Newsgroups Resent-To Subject To -IncludeMeta Message-Id References In-Reply-To -IncludeFile Mail * -IndexFile /home/user/Mail/.swish++/swish++.index -@end group -@end smallexample - -Use the following command line to generate the swish index. Run this -daily from cron: - -@smallexample -@group -find /home/user/Mail -path /home/user/Mail/mhe-index -prune \ - -o -path /home/user/Mail/.swish++ -prune \ - -o -name "[0-9]*" -print \ - | index -c /home/user/Mail/.swish++/swish++.conf - -@end group -@end smallexample - -This command does not index the folders that hold the results of your -searches in @samp{+mhe-index} since they tend to be ephemeral and the -original messages are indexed anyway. - -@cindex @command{index} -@cindex Unix commands, @command{index} -@cindex @command{index++} -@cindex Unix commands, @command{index++} - -On some systems (Debian GNU/Linux, for example), use @command{index++} -instead of @command{index}. - -@subsection swish - -@cindex @command{swish-e} -@cindex Unix commands, @command{swish-e} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.swish}. Then create -the file @file{/home/user/Mail/.swish/config} with the following -contents: - -@smallexample -@group -DefaultContents TXT* -IndexDir /home/user/Mail -IndexFile /home/user/Mail/.swish/index -IndexName "Mail Index" -IndexDescription "Mail Index" -IndexPointer "http://nowhere" -IndexAdmin "nobody" -#MetaNames automatic -IndexReport 3 -FollowSymLinks no -UseStemming no -IgnoreTotalWordCountWhenRanking yes -WordCharacters abcdefghijklmnopqrstuvwxyz0123456789- -BeginCharacters abcdefghijklmnopqrstuvwxyz -EndCharacters abcdefghijklmnopqrstuvwxyz0123456789 -IgnoreLimit 50 1000 -IndexComments 0 -FileRules filename contains \D -FileRules pathname contains /home/user/Mail/.swish -FileRules pathname contains /home/user/Mail/mhe-index -FileRules filename is index -@end group -@end smallexample - -This configuration does not index the folders that hold the results of -your searches in @samp{+mhe-index} since they tend to be ephemeral and -the original messages are indexed anyway. - -If there are any directories you would like to ignore, append lines -like the following to @file{config}: - -@smallexample -FileRules pathname contains /home/user/Mail/scripts -@end smallexample - -@cindex @command{swish-e} -@cindex Unix commands, @command{swish-e} - -Use the following command line to generate the swish index. Run this -daily from cron: - -@smallexample -swish-e -c /home/user/Mail/.swish/config -@end smallexample - -@subsection mairix - -@cindex @command{mairix} -@cindex Unix commands, @command{mairix} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.mairix}. Then create -the file @file{/home/user/Mail/.mairix/config} with the following -contents: - -@smallexample -@group -base=/home/user/Mail - -# List of folders that should be indexed. 3 dots at the end means there -# are subfolders within the folder -mh=archive...:inbox:drafts:news:sent:trash - -vfolder_format=raw -database=/home/user/Mail/mairix/database -@end group -@end smallexample - -Use the following command line to generate the mairix index. Run this daily -from cron: - -@smallexample -mairix -f /home/user/Mail/.mairix/config -@end smallexample - -@subsection namazu - -@cindex @command{namazu} -@cindex Unix commands, @command{namazu} - -In the examples below, replace @file{/home/user/Mail} with the path to -your MH directory. - -First create the directory @file{/home/user/Mail/.namazu}. Then create -the file @file{/home/user/Mail/.namazu/mknmzrc} with the following -contents: - -@smallexample -@group -package conf; # Don't remove this line! -$ADDRESS = 'user@@localhost'; -$ALLOW_FILE = "[0-9]*"; -$EXCLUDE_PATH = "^/home/user/Mail/(mhe-index|spam)"; -@end group -@end smallexample - -This configuration does not index the folders that hold the results of -your searches in @samp{+mhe-index} since they tend to be ephemeral and -the original messages are indexed anyway. - -Use the following command line to generate the namazu index. Run this -daily from cron: - -@smallexample -mknmz -f /home/user/Mail/.namazu/mknmzrc -O /home/user/Mail/.namazu \ - /home/user/Mail -@end smallexample - -@subsection pick - -@cindex @command{pick} -@cindex MH commands, @command{pick} - -This search method does not require any setup. - -Read @command{pick}(1) or the section -@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in -the MH book to find out more about how to enter the criteria. - -@subsection grep - -@cindex @command{grep} -@cindex Unix commands, @command{grep} - -This search method does not require any setup. - -Unlike the other search methods, this method does not use the -MH-Search buffer. Instead, you simply enter a regular expression in -the minibuffer. For help in constructing regular expressions, see your -man page for @command{grep}. - -@node Threading, Limits, Searching, Top -@chapter Viewing Message Threads - -@cindex threading - -MH-E groups messages by @dfn{threads} which are messages that are part -of the same discussion and usually all have the same @samp{Subject:} -header field. Other ways to organize messages in a folder include -limiting (@pxref{Limits}) or using full-text indexed searches -(@pxref{Searching}). - -@cindex root, in threads -@cindex siblings, in threads -@cindex ancestor, in threads - -A thread begins with a single message called a @dfn{root}. All replies -to the same message are @dfn{siblings} of each other. Any message that -has replies to it is an @dfn{ancestor} of those replies. - -There are several commands that you can use to navigate and operate on -threads. - -@table @kbd -@kindex T ? -@findex mh-prefix-help -@item T ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex T o -@findex mh-thread-refile -@item T o -Refile (output) thread into folder (@code{mh-thread-refile}). -@c ------------------------- -@kindex T d -@findex mh-thread-delete -@item T d -Delete thread (@code{mh-thread-delete}). -@c ------------------------- -@kindex T t -@findex mh-toggle-threads -@item T t -Toggle threaded view of folder (@code{mh-toggle-threads}). -@c ------------------------- -@kindex T n -@findex mh-thread-next-sibling -@item T n -Display next sibling (@code{mh-thread-next-sibling}). -@c ------------------------- -@kindex T p -@findex mh-thread-previous-sibling -@item T p -Display previous sibling (@code{mh-thread-previous-sibling}). -@c ------------------------- -@kindex T u -@findex mh-thread-ancestor -@item T u -Display ancestor of current message (@code{mh-thread-ancestor}). -@end table - -@cindex @samp{mh-thread} customization group -@cindex customization group, @samp{mh-thread} - -The @samp{mh-thread} customization group contains one option. - -@vtable @code -@item mh-show-threads-flag -On means new folders start in threaded mode (default: @samp{off}). -@end vtable - -@findex mh-toggle-threads -@kindex T t -@vindex mh-large-folder -@vindex mh-show-threads-flag - -Threading large number of messages can be time consuming so the option -@code{mh-show-threads-flag} is turned off by default. If you turn on -this option, then threading will be done only if the number of -messages being threaded is less than @code{mh-large-folder}. In any -event, threading can be turned on (and off) with the command @kbd{T t} -(@code{mh-toggle-threads}). - -@findex mh-thread-ancestor -@findex mh-thread-next-sibling -@findex mh-thread-previous-sibling -@kindex T n -@kindex T p -@kindex T u - -There are a few commands to help you navigate threads. If you do not -care for the way a particular thread has turned, you can move up the -chain of messages with the command @kbd{T u} -(@code{mh-thread-ancestor}. At any point you can use @kbd{T n} -(@code{mh-thread-next-sibling} or @kbd{T p} -(@code{mh-thread-previous-sibling}) to jump to the next or previous -sibling, skipping the sub-threads. The command @kbd{T u} can also take -a prefix argument to jump to the message that started everything. - -@findex mh-delete-subject-or-thread -@findex mh-thread-delete -@findex mh-thread-refile -@kindex k -@kindex T d -@kindex T o - -There are threaded equivalents for the commands that delete and refile -messages. For example, @kbd{T o} (@code{mh-thread-refile}) refiles the -current message and all its children. Similarly, the command @kbd{T d} -(@code{mh-thread-delete}) deletes the current message and all its -children. These commands do not refile or delete sibling messages. -@xref{Navigating}, for a description of the similar command @kbd{k} -(@code{mh-delete-subject-or-thread}). - -@vindex mh-large-folder - -If you find that threading is too slow, it may be that you have -@code{mh-large-folder} set too high. Also, threading is one of the few -features of MH-E that really benefits from compiling. If you haven't -compiled MH-E, I encourage you to do so@footnote{If you're not sure if -MH-E has been byte-compiled, you could try running @samp{locate -mh-thread.elc} or otherwise find MH-E on your system and ensure that -@file{mh-thread.elc} exists. If you have multiple versions and you -find that one is compiled but the other is not, then go into your -@samp{*scratch*} buffer in Emacs, enter @kbd{load-path C-j}, and -ensure that the byte-compiled version appears first in the -@code{load-path}. If you find that MH-E is not compiled and you -installed MH-E yourself, please refer to the installation directions -in the file @file{README} in the distribution.}. - -@node Limits, Sequences, Threading, Top -@chapter Limiting Display - -@cindex limits -@cindex filters - -Another way to organize messages in a folder besides threading -(@pxref{Threading}) or using full-text indexed searches -(@pxref{Searching}) is by limiting the folder display to messages that -are similar to the current message. - -@table @kbd -@kindex / ? -@findex mh-prefix-help -@item / ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Tick Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} -@kindex / ' -@findex mh-narrow-to-tick -@item / ' -Limit to messages in the @samp{tick} sequence -(@code{mh-narrow-to-tick}). -@c ------------------------- -@kindex / c -@findex mh-narrow-to-cc -@item / c -Limit to messages with the same @samp{Cc:} field -(@code{mh-narrow-to-cc}). -@c ------------------------- -@kindex / m -@findex mh-narrow-to-from -@item / m -Limit to messages with the same @samp{From:} field -(@code{mh-narrow-to-from}). -@c ------------------------- -@kindex / g -@findex mh-narrow-to-range -@item / g -Limit to range (@code{mh-narrow-to-range}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Subject Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Subject Sequence} -@kindex / s -@findex mh-narrow-to-subject -@item / s -Limit to messages with the same @samp{Subject:} field -(@code{mh-narrow-to-subject}). -@c ------------------------- -@kindex / t -@findex mh-narrow-to-to -@item / t -Limit to messages with the same @samp{To:} field -(@code{mh-narrow-to-to}). -@c ------------------------- -@cindex @samp{Sequence > Widen from Sequence} menu item -@cindex menu item, @samp{Sequence > Widen from Sequence} -@kindex / w -@findex mh-widen -@item / w -Remove last restriction (@code{mh-widen}). -@end table - -All of the limiting commands above refine the display in some way. - -@cindex @command{pick} -@cindex MH commands, @command{pick} -@findex mh-narrow-to-cc -@findex mh-narrow-to-from -@findex mh-narrow-to-subject -@findex mh-narrow-to-to -@kindex / c -@kindex / m -@kindex / s -@kindex / t - -The commands @kbd{/ c} (@code{mh-narrow-to-cc}), @kbd{/ m} -(@code{mh-narrow-to-from}), @kbd{/ s} (@code{mh-narrow-to-subject}), -and @kbd{/ t} (@code{mh-narrow-to-to}) restrict the display to -messages matching the content of the respective field in the current -message. However, you can give any of these a prefix argument to edit -the @command{pick} expression used to narrow the view@footnote{See -@command{pick}(1) or the section -@uref{@value{MH-BOOK-HOME}/finpic.html, Finding Messages with pick} in -the MH book.}. - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticked messages, viewing -@findex mh-narrow-to-range -@findex mh-narrow-to-tick -@kindex / ' -@kindex / g - -You can also limit the display to messages in the @samp{tick} sequence -with the command @kbd{/ '} (@code{mh-narrow-to-tick}). -@xref{Sequences}, for information on putting message into the -@samp{tick} sequence. Use the @kbd{/ g} (@code{mh-narrow-to-range}) -command to limit the display to messages in a range (@pxref{Ranges}). - -@findex mh-widen -@kindex / w - -Each limit can be undone in turn with the @kbd{/ w} (@code{mh-widen}) -command. Give this command a prefix argument to remove all limits. - -@node Sequences, Junk, Limits, Top -@chapter Using Sequences - -@cindex @samp{Sequence} menu -@cindex menu, @samp{Sequence} -@cindex sequences - -For the whole scoop on MH sequences, refer to -@samp{mh-sequence}(5)@footnote{See the section -@uref{@value{MH-BOOK-HOME}/morseq.html, More About Sequences} in the MH -book.}. As you've read, several of the MH-E commands can operate on a -sequence, which is a shorthand for a range or group of messages. For -example, you might want to forward several messages to a friend or -colleague. Here's how to manipulate sequences. These commands are also -available in the @samp{Sequence} menu. - -@table @kbd -@cindex @samp{Sequence > Toggle Tick Mark} menu item -@cindex menu item, @samp{Sequence > Toggle Tick Mark} -@kindex ' -@findex mh-toggle-tick -@item ' -Toggle tick mark of range (@code{mh-toggle-tick}). -@c ------------------------- -@kindex S ? -@findex mh-prefix-help -@item S ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Tick Sequence} menu item -@cindex menu item, @samp{Sequence > Narrow to Tick Sequence} -@kindex S ' -@findex mh-narrow-to-tick -@item S ' -Limit to ticked messages (@code{mh-narrow-to-tick}). -@c ------------------------- -@cindex @samp{Sequence > Delete Message from Sequence...} menu item -@cindex menu item, @samp{Sequence > Delete Message from Sequence...} -@kindex S d -@findex mh-delete-msg-from-seq -@item S d -Delete range from sequence (@code{mh-delete-msg-from-seq}). -@c ------------------------- -@cindex @samp{Sequence > Delete Sequence...} menu item -@cindex menu item, @samp{Sequence > Delete Sequence...} -@kindex S k -@findex mh-delete-seq -@item S k -Delete sequence (@code{mh-delete-seq}). -@c ------------------------- -@cindex @samp{Sequence > List Sequences in Folder...} menu item -@cindex menu item, @samp{Sequence > List Sequences in Folder...} -@kindex S l -@findex mh-list-sequences -@item S l -List all sequences in folder (@code{mh-list-sequences}). -@c ------------------------- -@cindex @samp{Sequence > Narrow to Sequence...} menu item -@cindex menu item, @samp{Sequence > Narrow to Sequence...} -@kindex S n -@findex mh-narrow-to-seq -@item S n -Restrict display to messages in sequence (@code{mh-narrow-to-seq}). -@c ------------------------- -@cindex @samp{Sequence > Add Message to Sequence...} menu item -@cindex menu item, @samp{Sequence > Add Message to Sequence...} -@kindex S p -@findex mh-put-msg-in-seq -@item S p -Add range to sequence (@code{mh-put-msg-in-seq}). -@c ------------------------- -@cindex @samp{Sequence > List Sequences for Message} menu item -@cindex menu item, @samp{Sequence > List Sequences for Message} -@kindex S s -@findex mh-msg-is-in-seq -@item S s -Display the sequences in which the current message appears -(@code{mh-msg-is-in-seq}). -@c ------------------------- -@cindex @samp{Sequence > Widen from Sequence} menu item -@cindex menu item, @samp{Sequence > Widen from Sequence} -@kindex S w -@findex mh-widen -@item S w -Remove last restriction (@code{mh-widen}). -@c ------------------------- -@findex mh-update-sequences -@item M-x mh-update-sequences -Flush MH-E's state out to MH@. -@end table - -@cindex @samp{mh-sequences} customization group -@cindex customization group, @samp{mh-sequences} - -The @samp{mh-sequences} customization group contains the options -associated with sequences. - -@vtable @code -@item mh-refile-preserves-sequences-flag -On means that sequences are preserved when messages are refiled -(default: @samp{on}). -@c ------------------------- -@item mh-tick-seq -The name of the MH sequence for ticked messages (default: @samp{'tick}). -@c ------------------------- -@item mh-update-sequences-after-mh-show-flag -On means flush MH sequences to disk after message is shown (default: -@samp{on}). -@end vtable - -The following hook is available. - -@vtable @code -@item mh-unseen-updated-hook -Hook run after the unseen sequence has been updated (default: @code{nil}). -@end vtable - -@cindex @command{pick} -@cindex MH commands, @command{pick} -@findex mh-put-msg-in-seq -@kindex S p - -To place a message in a sequence, use @kbd{S p} -(@code{mh-put-msg-in-seq}). Give @kbd{S p} a range and you can add all -the messages in a sequence to another sequence (for example, @kbd{C-u -S p SourceSequence @key{RET} DestSequence @key{RET}}, @pxref{Ranges}). - -@cindex @samp{tick} sequence -@cindex sequence, @samp{tick} -@cindex ticking messages -@findex mh-index-ticked-messages -@findex mh-toggle-tick -@kindex ' -@kindex F ' -@kindex S p - -One specific use of the @kbd{S p} command is @kbd{'} -(@code{mh-toggle-tick}) which adds messages to the @samp{tick} -sequence. This sequence can be viewed later with the @kbd{F '} -(@code{mh-index-ticked-messages}) command (@pxref{Folders}). - -@vindex mh-tick-seq - -You can customize the option @code{mh-tick-seq} if you already use the -@samp{tick} sequence for your own use. You can also disable all of the -ticking functions by choosing the @samp{Disable Ticking} item but -there isn't much advantage to that. - -@cindex MH-Folder mode -@cindex modes, MH-Folder -@findex mh-narrow-to-seq -@findex mh-narrow-to-tick -@findex mh-widen -@kindex S ' -@kindex S n -@kindex S w - -Once you've placed some messages in a sequence, you may wish to narrow -the field of view to just those messages in the sequence you've -created. To do this, use @kbd{S n} (@code{mh-narrow-to-seq}). You are -prompted for the name of the sequence. What this does is show only -those messages that are in the selected sequence in the MH-Folder -buffer. In addition, it limits further MH-E searches to just those -messages. To narrow the view to the messages in the @samp{tick} -sequence, use @kbd{S '} (@code{mh-narrow-to-tick}). When you want to -widen the view to all your messages again, use @kbd{S w} -(@code{mh-widen}). - -@cindex buffers, @samp{*MH-E Sequences*} -@cindex @samp{*MH-E Sequences*} -@findex mh-list-sequences -@findex mh-msg-is-in-seq -@kindex S l -@kindex S s - -You can see which sequences in which a message appears with the -command @kbd{S s} (@code{mh-msg-is-in-seq}). Use a prefix argument to -display the sequences in which another message appears (as in @kbd{C-u -42 S s @key{RET}}). Or, you can list all sequences in a selected -folder (default is current folder) with @kbd{S l} -(@code{mh-list-sequences}). The list appears in a buffer named -@samp{*MH-E Sequences*} (@pxref{Miscellaneous}). - -@cindex MH profile component, @samp{Previous-Sequence:} -@cindex @samp{cur} sequence -@cindex @samp{Previous-Sequence:} MH profile component -@cindex sequence, @samp{cur} -@cindex sequence, @samp{Previous-Sequence} -@vindex mh-refile-preserves-sequences-flag - -If a message is in any sequence (except -@samp{Previous-Sequence:}@footnote{See @samp{mh-profile}(5)).} and -@samp{cur}) when it is refiled, then it will still be in those -sequences in the destination folder. If this behavior is not desired, -then turn off the option @code{mh-refile-preserves-sequences-flag}. - -@findex mh-delete-msg-from-seq -@findex mh-delete-seq -@kindex d -@kindex S d -@kindex S k - -If you want to remove a message (or range, @pxref{Ranges}) from a -sequence, use @kbd{S d} (@code{mh-delete-msg-from-seq}). If you want -to delete an entire sequence, use @kbd{S k} (@code{mh-delete-seq}). In -the latter case you are prompted for the sequence to delete. Note that -this deletes only the sequence, not the messages in the sequence. If -you want to delete the messages, use @kbd{C-u d} (@pxref{Reading -Mail}). - -@cindex @samp{Unseen-Sequence:} MH profile component -@cindex @samp{cur} sequence -@cindex @samp{tick} sequence -@cindex MH profile component, @samp{Unseen-Sequence:} -@cindex sequence, @samp{Unseen-Sequence} -@cindex sequence, @samp{cur} -@cindex sequence, @samp{tick} -@findex mh-update-sequences -@kindex M-x mh-update-sequences -@kindex q -@kindex x -@vindex mh-tick-seq -@vindex mh-update-sequences-after-mh-show-flag - -Three sequences are maintained internally by MH-E and pushed out to MH -when a message is shown. They include the sequence specified by your -@samp{Unseen-Sequence:} profile component, @samp{cur}, and the -sequence listed by the option @code{mh-tick-seq} which is @samp{tick} -by default. If you do not like this behavior, turn off the option -@code{mh-update-sequences-after-mh-show-flag}. You can then update the -state manually with the @kbd{x}, @kbd{q}, or @kbd{M-x -mh-update-sequences} commands. - -@vindex mh-seen-list -@vindex mh-unseen-updated-hook - -The hook @code{mh-unseen-updated-hook} is run after the unseen -sequence has been updated. The variable @code{mh-seen-list} can be -used by this hook to obtain the list of messages which were removed -from the unseen sequence. - -@cindex @command{mark} -@cindex MH commands, @command{mark} -@kindex S n -@kindex S w - -With the exceptions of @kbd{S n} and @kbd{S w}, the underlying MH -command dealing with sequences is @command{mark}@footnote{See the -section @uref{@value{MH-BOOK-HOME}/mmbwm.html, Make Message Bookmarks -with mark} in the MH book.}. - -@node Junk, Miscellaneous, Sequences, Top -@chapter Dealing With Junk Mail - -@cindex Marshall Rose -@cindex junk mail -@cindex spam - -Marshall Rose once wrote a paper on MH entitled, @cite{How to process -200 messages a day and still get some real work done}. This chapter -could be entitled, @cite{How to process 1000 spams a day and still get -some real work done}. - -@cindex blacklisting -@cindex ham -@cindex viruses -@cindex whitelisting -@cindex worms - -We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for -any unwanted message which includes spam, @dfn{viruses}, and -@dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying -a sender as one who sends junk mail is called @dfn{blacklisting}; the -opposite is called @dfn{whitelisting}. - -@table @kbd -@kindex J ? -@findex mh-prefix-help -@item J ? -Display cheat sheet for the commands of the current prefix in -minibuffer (@code{mh-prefix-help}). -@c ------------------------- -@kindex J b -@findex mh-junk-blacklist -@item J b -Blacklist range as spam (@code{mh-junk-blacklist}). -@c ------------------------- -@kindex J w -@findex mh-junk-whitelist -@item J w -Whitelist range as ham (@code{mh-junk-whitelist}). -@c ------------------------- -@item @code{mh-spamassassin-identify-spammers} -Identify spammers who are repeat offenders. -@end table - -@cindex @samp{mh-junk} customization group -@cindex customization group, @samp{mh-junk} - -The following table lists the options from the @samp{mh-junk} -customization group. - -@vtable @code -@item mh-junk-background -If on, spam programs are run in background (default: @samp{off}). -@c ------------------------- -@item mh-junk-disposition -Disposition of junk mail (default: @samp{Delete Spam}). -@c ------------------------- -@item mh-junk-program -Spam program that MH-E should use (default: @samp{Auto-detect}). -@end vtable - -@cindex SpamProbe -@cindex Spamassassin -@cindex bogofilter -@cindex spam filters, SpamProbe -@cindex spam filters, Spamassassin -@cindex spam filters, bogofilter - -MH-E depends on @uref{http://spamassassin.apache.org/, SpamAssassin}, -@uref{http://bogofilter.sourceforge.net/, bogofilter}, or -@uref{http://spamprobe.sourceforge.net/, SpamProbe} to throw the dreck -away. This chapter describes briefly how to configure these programs -to work well with MH-E and how to use MH-E's interface that provides -continuing education for these programs. - -@vindex mh-junk-program - -The default setting of the option @code{mh-junk-program} is -@samp{Auto-detect} which means that MH-E will automatically choose one -of SpamAssassin, bogofilter, or SpamProbe in that order. If, for -example, you have both SpamAssassin and bogofilter installed and you -want to use bogofilter, then you can set this option to -@samp{Bogofilter}. - -@findex mh-junk-blacklist -@kindex J b -@vindex mh-junk-disposition - -The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam -program in use with the content of the range (@pxref{Ranges}) and then -handles the message(s) as specified by the option -@code{mh-junk-disposition}. By default, this option is set to -@samp{Delete Spam} but you can also specify the name of the folder -which is useful for building a corpus of spam for training purposes. - -@findex mh-junk-whitelist -@kindex J w - -In contrast, the command @kbd{J w} (@code{mh-junk-whitelist}) -reclassifies a range of messages (@pxref{Ranges}) as ham if it were -incorrectly classified as spam. It then refiles the message into the -@file{+inbox} folder. - -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} -@findex call-process -@vindex mh-junk-background - -By default, the programs are run in the foreground, but this can be -slow when junking large numbers of messages. If you have enough memory -or don't junk that many messages at the same time, you might try -turning on the option @code{mh-junk-background}. @footnote{Note that -the option @code{mh-junk-background} is used as the @code{display} -argument in the call to @code{call-process}. Therefore, turning on -this option means setting its value to @samp{0}. You can also set its -value to @samp{t} to direct the programs' output to the @samp{*MH-E -Log*} buffer; this may be useful for debugging.} - -The following sections discuss the various counter-spam measures that -MH-E can work with. - -@cindex @file{.procmailrc} -@cindex files, @file{.procmailrc} - -@subheading SpamAssassin - -@cindex Spamassassin -@cindex spam filters, Spamassassin - -SpamAssassin is one of the more popular spam filtering programs. Get -it from your local distribution or from the -@uref{http://spamassassin.apache.org/, SpamAssassin web site}. - -To use SpamAssassin, add the following recipes to @file{~/.procmailrc}: - -@cindex @command{spamc} -@cindex @samp{X-Spam-Level:} header field -@cindex @samp{X-Spam-Status:} header field -@cindex header field, @samp{X-Spam-Level:} -@cindex header field, @samp{X-Spam-Status:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with SpamAssassin. -:0fw -| spamc - -# Anything with a spam level of 10 or more is junked immediately. -:0: -* ^X-Spam-Level: .......... -/dev/null - -:0: -* ^X-Spam-Status: Yes -spam/. -@end smallexample - -If you don't use @command{spamc}, use @samp{spamassassin -P -a}. - -Note that one of the recipes above throws away messages with a score -greater than or equal to 10. Here's how you can determine a value that -works best for you. - -First, run @samp{spamassassin -t} on every mail message in your -archive and use @command{gnumeric} to verify that the average plus the -standard deviation of good mail is under 5, the SpamAssassin default -for ``spam''. - -Using @command{gnumeric}, sort the messages by score and view the -messages with the highest score. Determine the score which encompasses -all of your interesting messages and add a couple of points to be -conservative. Add that many dots to the @samp{X-Spam-Level:} header -field above to send messages with that score down the drain. - -In the example above, messages with a score of 5-9 are set aside in -the @samp{+spam} folder for later review. The major weakness of -rules-based filters is a plethora of false positives so it is -worthwhile to check. - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If SpamAssassin classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and -@kbd{J w} (@code{mh-junk-whitelist}). - -@cindex @command{sa-learn} -@cindex @file{.spamassassin/user_prefs} -@cindex files, @file{.spamassassin/user_prefs} - -The command @kbd{J b} (@code{mh-junk-blacklist}) adds a -@samp{blacklist_from} entry to @file{~/spamassassin/user_prefs}, -deletes the message, and sends the message to the Razor, so that -others might not see this spam. If the @command{sa-learn} command is -available, the message is also recategorized as spam. - -The command@kbd{J w} (@code{mh-junk-whitelist}) adds a -@samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If -the @command{sa-learn} command is available, the message is also -recategorized as ham. - -Over time, you'll observe that the same host or domain occurs -repeatedly in the @samp{blacklist_from} entries, so you might think -that you could avoid future spam by blacklisting all mail from a -particular domain. The utility function -@code{mh-spamassassin-identify-spammers} helps you do precisely that. -This function displays a frequency count of the hosts and domains in -the @samp{blacklist_from} entries from the last blank line in -@file{~/.spamassassin/user_prefs} to the end of the file. This -information can be used so that you can replace multiple -@samp{blacklist_from} entries with a single wildcard entry such as: - -@smallexample -blacklist_from *@@*amazingoffersdirect2u.com -@end smallexample - -In versions of SpamAssassin (2.50 and on) that support a Bayesian -classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program -@command{sa-learn} to recategorize the message as spam. Neither MH-E, -nor SpamAssassin, rebuilds the database after adding words, so you -will need to run @samp{sa-learn --rebuild} periodically. This can be -done by adding the following to your @file{crontab}: - -@smallexample -0 * * * * sa-learn --rebuild > /dev/null 2>&1 -@end smallexample - -@subheading Bogofilter - -@cindex bogofilter -@cindex spam filters, bogofilter - -Bogofilter is a Bayesian spam filtering program. Get it from your -local distribution or from the -@uref{http://bogofilter.sourceforge.net/, bogofilter web site}. - -Bogofilter is taught by running: - -@smallexample -bogofilter -n < good-message -@end smallexample - -on every good message, and - -@smallexample -bogofilter -s < spam-message -@end smallexample - -@cindex full training - -on every spam message. This is called a @dfn{full training}; three -other training methods are described in the FAQ that is distributed -with bogofilter. Note that most Bayesian filters need 1000 to 5000 of -each type of message to start doing a good job. - -To use bogofilter, add the following recipes to @file{~/.procmailrc}: - -@cindex @samp{X-Bogosity:} header field -@cindex header field, @samp{X-Bogosity:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with Bogofilter. -:0fw -| bogofilter -3 -e -p - -:0: -* ^X-Bogosity: Yes, tests=bogofilter -spam/. - -:0: -* ^X-Bogosity: Unsure, tests=bogofilter -spam/unsure/. -@end smallexample - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If bogofilter classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J -w} (@code{mh-junk-whitelist}) to update bogofilter's training. - -The @cite{Bogofilter FAQ} suggests that you run the following -occasionally to shrink the database: - -@smallexample -bogoutil -d wordlist.db | bogoutil -l wordlist.db.new -mv wordlist.db wordlist.db.prv -mv wordlist.db.new wordlist.db -@end smallexample - -The @cite{Bogofilter tuning HOWTO} describes how you can fine-tune -bogofilter. - -@subheading SpamProbe - -@cindex SpamProbe -@cindex spam filters, SpamProbe - -SpamProbe is a Bayesian spam filtering program. Get it from your local -distribution or from the @uref{http://spamprobe.sourceforge.net, -SpamProbe web site}. - -To use SpamProbe, add the following recipes to @file{~/.procmailrc}: - -@cindex @command{formail} -@cindex @samp{X-SpamProbe:} header field -@cindex header field, @samp{X-SpamProbe:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# Fight spam with SpamProbe. -:0 -SCORE=| spamprobe receive - -:0 wf -| formail -I "X-SpamProbe: $SCORE" - -:0: -*^X-SpamProbe: SPAM -spam/. -@end smallexample - -@findex mh-junk-blacklist -@findex mh-junk-whitelist -@kindex J b -@kindex J w - -If SpamProbe classifies a message incorrectly, you can use the MH-E -commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w} -(@code{mh-junk-whitelist}) to update SpamProbe's training. - -@subheading Other Things You Can Do - -There are a couple of things that you can add to @file{~/.procmailrc} -in order to filter out a lot of spam and viruses. The first is to -eliminate any message with a Windows executable (which is most likely -a virus). The second is to eliminate mail in character sets that you -can't read. - -@cindex @samp{Content-Transfer-Encoding:} header field -@cindex @samp{Content-Type:} header field -@cindex @samp{Subject:} header field -@cindex header field, @samp{Content-Transfer-Encoding:} -@cindex header field, @samp{Content-Type:} -@cindex header field, @samp{Subject:} - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` - -# -# Filter messages with win32 executables/virii. -# -# These attachments are base64 and have a TVqQAAMAAAAEAAAA//8AALg -# pattern. The string "this program cannot be run in MS-DOS mode" -# encoded in base64 is 4fug4AtAnNIbg and helps to avoid false -# positives (Roland Smith via Pete from the bogofilter mailing list). -# -:0 B: -* ^Content-Transfer-Encoding:.*base64 -* ^TVqQAAMAAAAEAAAA//8AALg -* 4fug4AtAnNIbg -spam/exe/. - -# -# Filter mail in unreadable character sets (from the Bogofilter FAQ). -# -UNREADABLE='[^?"]*big5|iso-2022-jp|ISO-2022-KR|euc-kr|gb2312|ks_c_5601-1987' - -:0: -* 1^0 $ ^Subject:.*=\?($UNREADABLE) -* 1^0 $ ^Content-Type:.*charset="?($UNREADABLE) -spam/unreadable/. - -:0: -* ^Content-Type:.*multipart -* B ?? $ ^Content-Type:.*^?.*charset="?($UNREADABLE) -spam/unreadable/. -@end smallexample - -@node Miscellaneous, Scan Line Formats, Junk, Top -@chapter Miscellaneous Commands, Variables, and Buffers - -This chapter covers the following command and the various MH-E -buffers, - -@ftable @code -@item mh-version -Display version information about MH-E and the MH mail handling -system. -@end ftable - -@cindex buffers, @samp{*MH-E Info*} -@cindex MH-E version -@cindex @samp{*MH-E Info*} -@cindex version -@kindex M-x mh-version - -One command worth noting is @kbd{M-x mh-version}. You can compare the -version this command prints to the latest release (@pxref{Getting -MH-E}). The output of @kbd{M-x mh-version}, found in a buffer named -@samp{*MH-E Info*}, should usually be included with any bug report you -submit (@pxref{Bug Reports}). - -@subheading MH-E Buffers - -Besides the MH-Folder, MH-Show, and MH-Letter buffers, MH-E creates -several other buffers. They are: - -@table @samp -@cindex @samp{*MH-E Folders*} -@cindex buffers, @samp{*MH-E Folders*} -@findex mh-list-folders -@item *MH-E Folders* -@kindex F l -This buffer contains the output of @kbd{F l} (@code{mh-list-folders}). -@xref{Folders}. -@c ------------------------- -@cindex @samp{*MH-E Help*} -@cindex buffers, @samp{*MH-E Help*} -@findex mh-help -@item *MH-E Help* -@kindex ? -@kindex C-c ? -This buffer contains the output of @kbd{?} (@code{mh-help}) and -@kbd{C-c ?} in MH-Letter mode. @xref{Using This Manual}. -@c ------------------------- -@cindex @samp{*MH-E Info*} -@cindex buffers, @samp{*MH-E Info*} -@item *MH-E Info* -This buffer contains the output of @kbd{M-x mh-version @key{RET}}. -@c ------------------------- -@cindex @samp{*MH-E Log*} -@cindex buffers, @samp{*MH-E Log*} -@item *MH-E Log* -This buffer contains the last 100 lines of the output of the various -MH commands. -@c ------------------------- -@cindex @samp{*MH-E Mail Delivery*} -@cindex buffers, @samp{*MH-E Mail Delivery*} -@item *MH-E Mail Delivery* -This buffer contains the transcript of a mail delivery. @xref{Sending -Message}. -@c ------------------------- -@cindex @samp{*MH-E Recipients*} -@cindex buffers, @samp{*MH-E Recipients*} -@findex mh-check-whom -@item *MH-E Recipients* -@kindex C-c C-w -This buffer contains the output of @kbd{C-c C-w} -(@code{mh-check-whom}) and is killed when draft is sent. -@xref{Checking Recipients}. -@c ------------------------- -@cindex @samp{*MH-E Sequences*} -@cindex buffers, @samp{*MH-E Sequences*} -@item *MH-E Sequences* -This buffer contains the output of @kbd{S l} -(@code{mh-list-sequences}). @xref{Sequences}. -@c ------------------------- -@cindex @samp{*mh-temp*} -@cindex buffers, @samp{*mh-temp*} -@item *mh-temp* -This is a scratch, ephemeral, buffer used by MH-E functions. Note that -it is hidden because the first character in the name is a space. -You'll generally not have any need for this buffer. -@end table - -@node Scan Line Formats, Procmail, Miscellaneous, Top -@appendix Scan Line Formats - -@cindex scan line formats - -This appendix discusses how MH-E creates, parses, and manipulates scan -lines. If you have your own MH scan or inc format files, you -@strong{can} teach MH-E how to handle them, but it isn't easy as -you'll see. - -@cindex @samp{mh-scan-line-formats} customization group -@cindex customization group, @samp{mh-scan-line-formats} - -This table lists the options in the @samp{mh-scan-line-formats} -customization group. - -@vtable @code -@item mh-adaptive-cmd-note-flag -On means that the message number width is determined dynamically -(default: @samp{on}). -@c ------------------------- -@item mh-scan-format-file -Specifies the format file to pass to the scan program (default: -@samp{Use MH-E scan Format}). -@c ------------------------- -@item mh-scan-prog -Program used to scan messages (default: @code{"scan"}). -@end vtable - -@vindex mh-adaptive-cmd-note-flag - -There are a couple of caveats when creating your own scan format file. -First, MH-E will not work if your scan lines do not include message -numbers. It will work poorly if you don't dedicate a column for -showing the current message and notations. It is also best to keep the -first column empty to make room for the cursor and so that text isn't -obscured by the current message's overlay arrow when running in a -terminal. You won't be able to use the option -@code{mh-adaptive-cmd-note-flag} or the threading features -(@pxref{Threading}). - -@cindex message numbers -@findex mh-set-cmd-note -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file - -If you've created your own format to handle long message numbers, -you'll be pleased to know you no longer need it since MH-E adapts its -internal format based upon the largest message number if -@code{mh-adaptive-cmd-note-flag} is on (the default). If you prefer -fixed-width message numbers, turn off @code{mh-adaptive-cmd-note-flag} -and call @code{mh-set-cmd-note} with the width specified by your -format file (see @code{mh-scan-format-file}). For example, the default -width is 4, so you would use @samp{(mh-set-cmd-note 4)}. - -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file -@vindex mh-scan-format-mh -@vindex mh-scan-format-nmh - -The default setting for @code{mh-scan-format-file} is @samp{Use MH-E -scan Format}. This means that the format string will be taken from the -either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending -on whether MH or nmh (or GNU mailutils MH) is in use. This setting -also enables you to turn on the option -@code{mh-adaptive-cmd-note-flag}. You can also set this option to -@samp{Use Default scan Format} to get the same output as you would get -if you ran @command{scan} from the shell. If you have a format file -that you want MH-E to use but not MH, you can set this option to -@samp{Specify a scan Format File} and enter the name of your format -file. - -@vindex mh-scan-format-file -@vindex mh-scan-format-mh -@vindex mh-scan-format-nmh - -The scan format that MH-E uses when @code{mh-scan-format-file} is set -to its default of @samp{Use MH-E scan Format} is held in the variables -@code{mh-scan-format-nmh} and @code{mh-scan-format-mh} depending on -whether you are using nmh (or GNU mailutils MH) or not. Typically, you -create your own format files rather than modifying these variables. -The value of @code{mh-scan-format-nmh} is: - -@smallexample -(concat - "%4(msg)" - "%<(cur)+%| %>" - "%<@{replied@}-" - "%?(nonnull(comp@{to@}))%<(mymbox@{to@})t%>" - "%?(nonnull(comp@{cc@}))%<(mymbox@{cc@})c%>" - "%?(nonnull(comp@{bcc@}))%<(mymbox@{bcc@})b%>" - "%?(nonnull(comp@{newsgroups@}))n%>" - "%<(zero) %>" - "%02(mon@{date@})/%02(mday@{date@})%<@{date@} %|*%>" - "%<(mymbox@{from@})%<@{to@}To:%14(decode(friendly@{to@}))%>%>" - "%<(zero)%17(decode(friendly@{from@}))%> " - "%(decode@{subject@})%<@{body@}<<%@{body@}%>") -@end smallexample - -@cindex decoding RFC 2047 -@cindex RFC 2047, decoding -@vindex mh-scan-format-mh - -The setting for @code{mh-scan-format-mh} is similar, except that MH -doesn't have the function @code{decode} (which is used to decode RFC -2047 encodings). - -@cindex notations, scan line -@cindex scan line notations - -These strings are passed to the @command{scan} program via the -@option{-format} argument. The formats are identical to the defaults -except that additional hints for fontification have been added to the -existing notations in the fifth column (remember that in Emacs, the -columns start at 0). The values of the fifth column, in priority -order, are: @samp{-} if the message has been replied to, @samp{t} if -an address in the @samp{To:} field matches one of the mailboxes of the -current user, @samp{c} if the @samp{Cc:} field matches, @samp{b} if -the @samp{Bcc:} field matches, and @samp{n} if a non-empty -@samp{Newsgroups:} field is present. - -@cindex @command{scan} -@cindex MH commands, @command{scan} -@vindex mh-progs -@vindex mh-scan-prog - -The name of the program that generates a listing of one line per -message is held in @code{mh-scan-prog} (default: @code{"scan"}). -Unless this variable contains an absolute pathname, it is assumed to -be in the @code{mh-progs} directory (@pxref{Getting Started}). You may -link another program to @command{scan} (see @samp{mh-profile}(5)) to -produce a different type of listing@footnote{See the section -@uref{@value{MH-BOOK-HOME}/faswsprs.html, Find and Specify with scan -pick Ranges Sequences} in the MH book.}. - -@cindex regular expressions, scan line formats -@findex mh-set-cmd-note -@findex setq - -If you change the format of the scan lines you'll need to tell MH-E -how to parse the new format. As you will see, quite a lot of variables -are involved to do that. Use @kbd{M-x apropos @key{RET} -mh-scan.*regexp @key{RET}} to obtain a list of these variables. You -will also have to call @code{mh-set-cmd-note} if your notations are -not in column 4 (columns in Emacs start with 0). Note that unlike most -of the user options described in this manual, these are variables and -must be set with @code{setq} instead of in a customization buffer. For -help with regular expressions, see -@ifnothtml -@ref{Regexps, , Syntax of Regular Expressions, emacs, The -GNU Emacs Manual}. -@end ifnothtml -@ifhtml -section -@uref{http://www.gnu.org/software/emacs/manual/html_node/Regexps.html, -Syntax of Regular Expressions} in @cite{The GNU Emacs Manual}. -@end ifhtml - -The first variable has to do with pruning out garbage. - -@vtable @code -@cindex @command{inc} -@cindex MH commands, @command{inc} -@cindex @command{scan} -@cindex MH commands, @command{scan} -@item mh-scan-valid-regexp -This regular expression describes a valid scan line. This is used to -eliminate error messages that are occasionally produced by -@command{inc}@footnote{See the section -@uref{@value{MH-BOOK-HOME}/reapre.html, Reading Mail: inc show next -prev} in the MH book.} or @command{scan} (default: @code{"^ *[0-9]"}). -@end vtable - -Next, many variables control how the scan lines are parsed. - -@vtable @code -@vindex mh-folder-body -@vindex mh-folder-font-lock-keywords -@item mh-scan-body-regexp -This regular expression matches the message body fragment. Note that -the default setting of @code{mh-folder-font-lock-keywords} expects -this expression to contain at least one parenthesized expression which -matches the body text as in the default of -@code{"\\(<<\\([^\n]+\\)?\\)"}. If this regular expression is not -correct, the body fragment will not be highlighted with the face -@code{mh-folder-body}. -@c ------------------------- -@vindex mh-folder-cur-msg-number -@vindex mh-folder-font-lock-keywords -@vindex mh-note-cur -@item mh-scan-cur-msg-number-regexp -This regular expression matches the current message. It must match -from the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\+\\).*"}}. This -expression includes the leading space and current message marker -@samp{+} within the parenthesis since it looks better to highlight -these items as well. The highlighting is done with the face -@code{mh-folder-cur-msg-number}. This regular expression should be -correct as it is needed by non-fontification functions. See also -@code{mh-note-cur}. -@c ------------------------- -@vindex mh-folder-date -@vindex mh-folder-font-lock-keywords -@vindex mh-scan-sent-to-me-sender-regexp -@item mh-scan-date-regexp -This regular expression matches a valid date. It must @strong{not} be -anchored to the beginning or the end of the line. Note that the -default setting of @code{mh-folder-font-lock-keywords} expects this -expression to contain only one parenthesized expression which matches -the date field as in the default of -@code{"\\([0-9][0-9]/[0-9][0-9]\\)"}. If this regular expression is -not correct, the date will not be highlighted with the face -@code{mh-folder-date}. -@c ------------------------- -@vindex mh-folder-deleted -@vindex mh-folder-font-lock-keywords -@vindex mh-note-deleted -@item mh-scan-deleted-msg-regexp -This regular expression matches deleted messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @code{"^\\( *[0-9]+\\)D"}. This expression -includes the leading space within the parenthesis since it looks -better to highlight it as well. The highlighting is done with the face -@code{mh-folder-deleted}. This regular expression should be correct as -it is needed by non-fontification functions. See also -@code{mh-note-deleted}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-msg-number -@item mh-scan-good-msg-regexp -This regular expression matches ``good'' messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\)[^D^0-9]"}}. This -expression includes the leading space within the parenthesis since it -looks better to highlight it as well. The highlighting is done with -the face @code{mh-folder-msg-number}. This regular expression should -be correct as it is needed by non-fontification functions. -@c ------------------------- -@vindex mh-scan-format-file -@item mh-scan-msg-format-regexp -This regular expression finds the message number width in a scan -format. Note that the message number must be placed in a parenthesized -expression as in the default of @code{"%\\([0-9]*\\)(msg)"}. This -variable is only consulted if @code{mh-scan-format-file} is set to -@samp{Use MH-E scan Format}. -@c ------------------------- -@vindex mh-scan-format-file -@item mh-scan-msg-format-string -This is a format string for the width of the message number in a scan -format. Use @samp{0%d} for zero-filled message numbers. This variable -is only consulted if @code{mh-scan-format-file} is set to @samp{Use -MH-E scan Format} (default: @code{"%d"}). -@c ------------------------- -@item mh-scan-msg-number-regexp -This regular expression extracts the message number. It must match -from the beginning of the line. Note that the message number must be -placed in a parenthesized expression as in the default of @w{@code{"^ -*\\([0-9]+\\)"}}. -@c ------------------------- -@item mh-scan-msg-overflow-regexp -This regular expression matches overflowed message numbers (default: -@code{"^[?0-9][0-9]"}). -@c ------------------------- -@item mh-scan-msg-search-regexp -This regular expression matches a particular message. It is a format -string; use @samp{%d} to represent the location of the message number -within the expression as in the default of @code{"^[^0-9]*%d[^0-9]"}. -@c ------------------------- -@vindex mh-folder-address -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-to -@item mh-scan-rcpt-regexp -This regular expression specifies the recipient in messages you sent. -Note that the default setting of @code{mh-folder-font-lock-keywords} -expects this expression to contain two parenthesized expressions. The -first is expected to match the @samp{To:} that the default scan format -file generates. The second is expected to match the recipient's name -as in the default of @code{"\\(To:\\)\\(..............\\)"}. If this -regular expression is not correct, the @samp{To:} string will not be -highlighted with the face @code{mh-folder-to} and the recipient will not be -highlighted with the face @code{mh-folder-address}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-refiled -@vindex mh-note-refiled -@item mh-scan-refiled-msg-regexp -This regular expression matches refiled messages. It must match from -the beginning of the line. Note that the default setting of -@code{mh-folder-font-lock-keywords} expects this expression to contain -at least one parenthesized expression which matches the message number -as in the default of @w{@code{"^\\( *[0-9]+\\)\\^"}}. This expression -includes the leading space within the parenthesis since it looks -better to highlight it as well. The highlighting is done with the face -@code{mh-folder-refiled}. This regular expression should be correct as -it is needed by non-fontification functions. See also -@code{mh-note-refiled}. -@c ------------------------- -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-sent-to-me-sender -@vindex mh-mh-folder-sent-to-me-hint -@vindex mh-scan-format-nmh -@item mh-scan-sent-to-me-sender-regexp -This regular expression matches messages sent to us. Note that the -default setting of @code{mh-folder-font-lock-keywords} expects this -expression to contain at least two parenthesized expressions. The -first should match the fontification hint (see -@code{mh-scan-format-nmh}) and the second should match the user name -as in the default of -@w{@code{"^ *[0-9]+.\\([bct]\\).....[ ]*\\(..................\\)"}}. -If this regular expression is not correct, the notation hints will not -be highlighted with the face @code{mh-mh-folder-sent-to-me-hint} and -the sender will not be highlighted with the face -@code{mh-folder-sent-to-me-sender}. -@c ------------------------- -@vindex mh-folder-followup -@vindex mh-folder-font-lock-keywords -@vindex mh-folder-subject -@item mh-scan-subject-regexp -This regular expression matches the subject. It must match from the -beginning of the line. Note that the default setting of -@samp{mh-folder-font-lock-keywords} expects this expression to contain -at least three parenthesized expressions. The first is expected to -match the @samp{Re:} string, if any, and is highlighted with the face -@code{mh-folder-followup}. The second matches an optional bracketed -number after @samp{Re:}, such as in @samp{Re[2]:} (and is thus a -sub-expression of the first expression). The third is expected to -match the subject line itself which is highlighted with the face -@code{mh-folder-subject}. For example, the default is -@w{@code{"^ *[0-9]+........[ ]*...................}}@* -@w{@code{\\([Rr][Ee]\\(\\[[0-9]+\\]\\)?:\\s-*\\)*\\([^<\n]*\\)"}}. -This regular expression should be correct as it is needed by -non-fontification functions. Note that this example is broken up on -two lines for readability, but is actually a single string. -@end vtable - -Finally, there are a slew of variables that control how MH-E annotates -the scan lines. - -@vtable @code -@findex mh-set-cmd-note -@vindex mh-adaptive-cmd-note-flag -@item mh-cmd-note -Column for notations (default: 4). This variable should be set with -the function @code{mh-set-cmd-note}. This variable may be updated -dynamically if @code{mh-adaptive-cmd-note-flag} is on. The following -variables contain the notational characters. Note that columns in -Emacs start with 0. -@c ------------------------- -@item mh-note-copied -Messages that have been copied are marked by this character (default: -@code{?C}). -@c ------------------------- -@vindex mh-scan-cur-msg-number-regexp -@item mh-note-cur -The current message (in MH, not in MH-E) is marked by this character -(default: @code{?+}). See also @code{mh-scan-cur-msg-number-regexp}. -@c ------------------------- -@vindex mh-scan-deleted-msg-regexp -@item mh-note-deleted -Messages that have been deleted are marked by this character (default: -@code{?D}). See also @code{mh-scan-deleted-msg-regexp}. -@c ------------------------- -@item mh-note-dist -Messages that have been redistributed are marked by this character -(default: @code{?R}). -@c ------------------------- -@item mh-note-forw -Messages that have been forwarded are marked by this character -(default: @code{?F}). -@c ------------------------- -@item mh-note-printed -Messages that have been printed are marked by this character (default: -@code{?P}). -@c ------------------------- -@vindex mh-scan-refiled-msg-regexp -@item mh-note-refiled -Messages that have been refiled are marked by this character (default: -@code{?^}). See also @code{mh-scan-refiled-msg-regexp}. -@c ------------------------- -@item mh-note-repl -Messages that have been replied to are marked by this character -(default: @code{?-}). -@c ------------------------- -@item mh-note-seq -Messages in a user-defined sequence are marked by this character -(default: @code{?%}). Messages in the @samp{search} sequence are -marked by this character as well. -@end vtable - -For example, let's say I have the following in @file{scan.format} -which displays the sender, the subject, and the message number. This -format places a @samp{+} after the message number for the current -message according to MH; it also uses that column for notations. - -@smallexample -%20(decode(friendly@{from@})) %50(decode@{subject@}) %4(msg)%<(cur)+%| %> -@end smallexample - -@vindex mh-adaptive-cmd-note-flag -@vindex mh-scan-format-file -@vindex mh-scan-format-file, example - -The first thing you have to do is tell MH-E to use this file. -Customize @code{mh-scan-format-file} and set its value to @samp{Use -Default scan Format}. If you didn't get already turn off -@code{mh-adaptive-cmd-note-flag}, you'll need to do that first. - -Next, tell MH-E what a valid scan line looks like so that you can at -least display the output of scan in your MH-Folder buffer. - -@vindex mh-scan-valid-regexp, example - -@smalllisp -(setq mh-scan-valid-regexp "[0-9]+[+D^ ]$") -@end smalllisp - -Now, in order to get rid of the @samp{Cursor not pointing to message} -message, you need to tell MH-E how to access the message number. You -should also see why MH-E requires that you include a message number in -the first place. - -@vindex mh-scan-msg-number-regexp, example -@vindex mh-scan-msg-search-regexp, example - -@smalllisp -(setq mh-scan-msg-number-regexp "^.* \\([0-9]+\\)[+D^ ]$") -(setq mh-scan-msg-search-regexp " %d[+D^ ]$") -@end smalllisp - -In order to get the next and previous commands working, add this. - -@vindex mh-scan-good-msg-regexp, example - -@smalllisp -(setq mh-scan-good-msg-regexp "^.* \\([0-9]+\\)[+D^ ]$") -@end smalllisp - -Note that the current message isn't marked with a @samp{+} when moving -between the next and previous messages. Here is the code required to -get this working. - -@vindex set-mh-cmd-note, example -@vindex mh-scan-cur-msg-number-regexp, example - -@smalllisp -(set-mh-cmd-note 76) -(setq mh-scan-cur-msg-number-regexp "^.* \\([0-9]+\\)\\+$") -@end smalllisp - -Finally, add the following to delete and refile messages. - -@vindex mh-scan-deleted-msg-regexp, example -@vindex mh-scan-refiled-msg-regexp, example - -@smalllisp -(setq mh-scan-deleted-msg-regexp "^.* \\([0-9]+\\)D$") -(setq mh-scan-refiled-msg-regexp "^.* \\([0-9]+\\)\\^$") -@end smalllisp - -This is just a bare minimum; it's best to adjust all of the regular -expressions to ensure that MH-E and highlighting perform well. - -@node Procmail, Odds and Ends, Scan Line Formats, Top -@appendix Reading Mailing Lists Effectively - -@cindex @command{procmail} -@cindex @command{slocal} -@cindex Gnus -@cindex MH commands, @command{slocal} -@cindex Unix commands, @command{procmail} -@cindex mailing lists, reading - -This appendix explains how to use @uref{http://www.procmail.org/, -procmail} to file mail from mailing lists into folders which can then -be read easily with MH-E@footnote{The MH equivalent, @command{slocal}, -can be used as well, but procmail is more flexible and more packages -exist for procmail than for slocal.}. Some mailing lists have such -high traffic that Gnus must be used and I discuss how to use Gnus -side-by-side with MH-E. - -@cindex @file{.procmailrc} -@cindex files, @file{.procmailrc} - -First, I'll describe how to put mail from your mailing lists directly -into an MH folder using @command{procmail}. First, add the following -to @file{~/.procmailrc}. While the logging variables aren't strictly -necessary, they are extremely useful. - -@smallexample -[1] # Update PATH so procmail can find myrcvstore, rcvstore and mhparam. -[2] PATH=$PATH:/usr/lib/mh:/usr/bin/mh:$HOME/bin -[3] -[4] # Point LOGFILE at the actual log file. -[5] LOGFILE=$HOME/.procmail.log -[6] -[7] # This setting provides just the right amount of information. -[8] LOGABSTRACT=all -[9] -[10] # Uncomment the following line to see how your patterns match. -[11] #VERBOSE=yes -[12] -[13] # Place mail sent to any MH-E mailing list in +mh-e. -[14] :0 w: mh-e$LOCKEXT -[15] * ^TO.*mh-e-.*@.*sourceforge.net -[16] | myrcvstore -create +mh-e -@end smallexample - -@cindex @command{rcvstore} -@cindex MH commands, @command{rcvstore} - -Line 14 creates a lock file in your mail directory based upon the name -of the folder. This is done because @command{rcvstore} does not -perform locking. While this lock file will prevent @command{procmail} -from writing to a folder concurrently, there is a slight chance that -you might lose a message if you're performing operations on a folder -at the same time @command{rcvstore} is placing a message there. You -have been warned. Now that that disclaimer is out of the way, note -that I've been using this set-up for over a decade and haven't lost -anything to my knowledge@footnote{See -@uref{https://savannah.nongnu.org/bugs/?func=detailbug&bug_id=4361&group_id=2166, -Savannah issue #4361} to see if @command{rcvstore} locking is still an -issue.}. - -@cindex @samp{Unseen-Sequence:} MH profile component -@cindex MH profile component, @samp{Unseen-Sequence:} - -Line 16 uses the following script, @code{myrcvstore}, to massage the -message as described in the comment and file the message in the given -folder@footnote{The @samp{-create} argument wasn't always the default -to @command{rcvstore}.}. - -@smallexample -#! /bin/sh - -# Accepts a message on standard input and passes it through rcvstore -# after first passing it through any filters. All arguments are passed -# on to rcvstore. - -# Force the "From user date" to become part of header. One reason this -# is done is because the presence of the From field confuses dist so -# that dist adds a new header, rather than using the existing header. -# Note that this should not be done for any message that goes into a -# Gnus incoming file (Gnus will thrown an error) nor should it be -# applied to any message that goes to the system mailbox because the -# entire mailbox will be incorporated as a single message. -formail -c -z -R 'From ' X-Envelope-From: | -rcvstore $@@ -@end smallexample - -If your version of @command{rcvstore} doesn't add messages to the -@samp{unseen} sequence by default, add the following line to your MH -profile: - -@smallexample -Unseen-Sequence: unseen -@end smallexample - -Now view your new messages with the speedbar (@pxref{Speedbar}) or with -@kbd{F n} (@code{mh-index-new-messages}). @xref{Folders}. - -If you're on a mailing list that is so voluminous that it is -impossible to read every message, it usually better to read the -mailing list like a newsgroup in a news reader. Emacs has a built-in -newsreader called Gnus. The remainder of this appendix talks about how -to use Gnus with an MH message store. The version of Gnus that was -used to prepare this manual was 5.10. Versions 5.8 through 5.10 should -work but versions prior to 5.8 use different options. - -This table contains a list of Gnus options that you will have to -modify. Note that for them to become accessible, you'll have to load -@file{nnml.el} first. This can be done with @kbd{M-x load-library -@key{RET} nnml @key{RET}}. - -@vtable @code -@item gnus-secondary-select-methods -Select the @samp{nnml} value. This select method uses directories for -folders and individual files for messages, just like MH. You do not -have to set an address. -@c ------------------------- -@item mail-sources -Select the @samp{Several files in a directory} value, check the -@samp{Path} box and enter @file{~/Mail} to tell Gnus where to find -your mail. -@c ------------------------- -@vindex mail-user-agent -@item message-mail-user-agent -In order to send mail within Gnus using MH-E, set this option to -@samp{mail-user-agent} and set the @code{mail-user-agent} option to -@samp{Emacs interface to MH}. -@c ------------------------- -@item nnmail-keep-last-article -Since Gnus keeps track of which messages you have read, it would be -bad if Gnus expired the last message, for example, message 100, and -@command{rcvstore} gave the next new message number 1. Gnus would then -ignore it since it thinks that you've read messages 1-100. Turning on -this option ensures that the last message is never removed thereby -eliminating this problem. -@end vtable - -Next add the following to @file{~/.procmailrc}. If you don't subscribe -to the GnuCash mailing list, substitute one to which you are -subscribed. - -@smallexample -PATH=$PATH:/usr/bin/mh -MAILDIR=$HOME/`mhparam Path` -# Place mail sent to the GnuCash mailing list in gnucash.spool, where -# Gnus will pick it up. -:0: -* ^TO.*gnucash.*@.*gnucash.org -gnucash.spool -@end smallexample - -Wait for some messages to appear in @file{gnucash.spool} and run Gnus -with @kbd{M-x gnus @key{RET}}. To view the folder created in the -example above, you would tell Gnus about it the first time only with -@kbd{G m gnucash @key{RET} nnml @key{RET}}. In MH-E, this folder is -known as @samp{+gnucash}. - -@node Odds and Ends, History, Procmail, Top -@appendix Odds and Ends - -This appendix covers a few topics that don't fit elsewhere. Here I -tell you how to report bugs and how to get on the MH-E mailing lists. -I also point out some additional sources of information. - -@menu -* Bug Reports:: -* Mailing Lists:: -* MH FAQ and Support:: -* Getting MH-E:: -@end menu - -@node Bug Reports, Mailing Lists, Odds and Ends, Odds and Ends -@appendixsec Bug Reports - -@cindex bugs -@cindex SourceForge -@kindex M-x mh-version - -Bug reports should be filed at -@uref{https://sourceforge.net/tracker/?group_id=13357&atid=113357, -SourceForge}. You need to be a SourceForge user to submit bug reports, -but this is easy enough to do that it shouldn't be a restriction for -you. Please include the output of @kbd{M-x mh-version} -(@pxref{Miscellaneous}) in any bug report you send unless you're 110% -positive we won't ask for it. - -@node Mailing Lists, MH FAQ and Support, Bug Reports, Odds and Ends -@appendixsec MH-E Mailing Lists - -@cindex SourceForge -@cindex mailing lists - -There are several mailing lists for MH-E. They are @i{mh-e-users at -lists.sourceforge.net}, @i{mh-e-announce at lists.sourceforge.net}, -and @i{mh-e-devel at lists.sourceforge.net}. You can subscribe or view -the archives at @uref{https://sourceforge.net/mail/?group_id=13357, -SourceForge}. Do not report bugs on these lists; please submit them -via SourceForge (@pxref{Bug Reports}). - -@node MH FAQ and Support, Getting MH-E, Mailing Lists, Odds and Ends -@appendixsec MH FAQ and Support - -@cindex FAQ -@cindex MH FAQ - -The article @uref{http://www.newt.com/faq/mh.html, @cite{MH Frequently -Asked Questions (FAQ) with Answers}} appears monthly in the newsgroup -@samp{comp.mail.mh}. While very little is there that deals with MH-E -specifically, there is an incredible wealth of material about MH -itself which you will find useful. - -@cindex support - -You can find FAQs on MH-E at the -@uref{https://sourceforge.net/tracker/?group_id=13357&atid=213357, -Support Requests} page on SourceForge. If you don't find the answer to -your question, file a support request and your question will become a -new FAQ! - -@node Getting MH-E, , MH FAQ and Support, Odds and Ends -@appendixsec Getting MH-E - -@cindex MH-E, obtaining -@cindex getting MH-E -@cindex obtaining MH-E - -Because MH-E is undergoing a phase of sustained growth, the version of -MH-E in your Emacs is likely to be out of date although it is most -likely to be more up to date than the copy that comes with the MH -distribution in @file{miscellany/mh-e}. - -@cindex change log -@cindex release notes - -New MH-E releases are always available for downloading at -@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, -SourceForge} before they appear in an Emacs release. You can read the -release notes on that page to determine if the given release of MH-E -is already installed in your version of Emacs. You can also read the -change log to see if you are interested in what the given release of -MH-E has to offer (although we have no doubt that you will be -extremely interested in all new releases). - -@cindex Debian - -If you use Debian, you can install the Debian -@uref{http://packages.debian.org/unstable/mail/mh-e, mh-e package} -instead. - -@cindex files, @samp{MH-E-NEWS} -@cindex files, @samp{README} -@cindex news -@cindex @samp{MH-E-NEWS} -@cindex @samp{README} -@kindex M-x mh-version - -After you download and extract the MH-E tarball, read the -@file{README} file and @file{MH-E-NEWS}. These correspond to the -release notes and change log mentioned above. The file @file{README} -contains instructions on installing MH-E. If you're already running -Emacs, please quit that session and start again to load in the new -MH-E. Check that you're running the new version with the command -@kbd{M-x mh-version}. - -@cindex contributed software -@cindex manual -@cindex documentation - -In addition to the mh-e package, the -@uref{https://sourceforge.net/project/showfiles.php?group_id=13357, -SourceForge} site also contains doc and contrib packages. The former -is the latest release of this manual, and the latter contains a few -contributed packages you might find useful. - -@node History, GFDL, Odds and Ends, Top -@appendix History of MH-E - -@cindex Bill Wohler -@cindex Brian Reid -@cindex Gildea, Stephen -@cindex Jim Larus -@cindex Larus, Jim -@cindex MH-E, versions -@cindex Reid, Brian -@cindex SourceForge -@cindex Stephen Gildea -@cindex Wohler, Bill -@cindex history of MH-E -@cindex versions of MH-E - -MH-E was originally written by Brian Reid in 1983 and has changed -hands several times since then. Jim Larus wanted to do something -similar for GNU Emacs, and ended up completely rewriting it that same -year. In 1989, Stephen Gildea picked it up and added many -improvements. Bill Wohler then took over in 2000 and moved its -development to @uref{http://sourceforge.net/, SourceForge} where it -lives today. - -@menu -* From Brian Reid:: -* From Jim Larus:: -* From Stephen Gildea:: -* From Bill Wohler:: -@end menu - -@node From Brian Reid, From Jim Larus, History, History -@appendixsec From Brian Reid - -@cindex Brian Reid -@cindex Reid, Brian - -One day in 1983 I got the flu and had to stay home from work for three -days with nothing to do. I used that time to write MHE@. The -fundamental idea behind MHE was that it was a ``puppeteer'' driving -the MH programs underneath it. MH had a model that the editor was -supposed to run as a sub-process of the mailer, which seemed to me at -the time to be the tail wagging the dog. So I turned it around and -made the editor drive the MH programs. I made sure that the UCI people -(who were maintaining MH at the time) took in my changes and made them -stick. - -Today, I still use my own version of MHE because I don't at all like -the way that GNU MH-E works and I've never gotten to be good enough at -hacking Emacs Lisp to make GNU MH-E do what I want. The Gosling-emacs -version of MHE and the GNU Emacs version of MH-E have almost nothing -in common except similar names. They work differently, have different -conceptual models, and have different key bindings@footnote{After -reading this article, I questioned Brian about his version of MHE, and -received some great ideas for improving MH-E such as a dired-like -method of selecting folders; and removing the prompting when sending -mail, filling in the blanks in the draft buffer instead. I passed them -on to Stephen Gildea, the current maintainer, and he was excited about -the ideas as well. Perhaps one day, MH-E will again resemble MHE -(draft form editing was introduced in version 7.4).}. - -Brian Reid, June 1994 - -@node From Jim Larus, From Stephen Gildea, From Brian Reid, History -@appendixsec From Jim Larus - -@cindex Jim Larus -@cindex Larus, Jim - -Brian Reid, while at CMU or shortly after going to Stanford wrote a -mail reading program called MHE for Gosling Emacs. It had much the -same structure as MH-E (i.e., invoked MH programs), though it was -simpler and the commands were slightly different. Unfortunately, I no -longer have a copy so the differences are lost in the mists of time. - -In '82-83, I was working at BBN and wrote a lot of mlisp code in -Gosling Emacs to make it look more like Tennex Emacs. One of the -packages that I picked up and improved was Reid's mail system. In '83, -I went back to Berkeley. About that time, Stallman's first version of -GNU Emacs came out and people started to move to it from Gosling Emacs -(as I recall, the transition took a year or two). I decided to port -Reid's MHE and used the mlisp to Emacs Lisp translator that came with -GNU Emacs. It did a lousy job and the resulting code didn't work, so I -bit the bullet and rewrote the code by hand (it was a lot smaller and -simpler then, so it took only a day or two). - -Soon after that, MH-E became part of the standard Emacs distribution -and suggestions kept dribbling in for improvements. MH-E soon reached -sufficient functionality to keep me happy, but I kept on improving it -because I was a graduate student with plenty of time on my hands and -it was more fun than my dissertation. In retrospect, the one thing -that I regret is not writing any documentation, which seriously -limited the use and appeal of the package. - -@cindex @command{xmh}, in MH-E history - -In '89, I came to Wisconsin as a professor and decided not to work on -MH-E. It was stable, except for minor bugs, and had enough -functionality, so I let it be for a few years. Stephen Gildea of BBN -began to pester me about the bugs, but I ignored them. In 1990, he -went off to the X Consortium, said good bye, and said that he would -now be using @command{xmh}. A few months later, he came back and said -that he couldn't stand @command{xmh} and could I put a few more bug fixes -into MH-E. At that point, I had no interest in fixing MH-E, so I gave -the responsibility of maintenance to him and he has done a fine job -since then. - -Jim Larus, June 1994 - -@node From Stephen Gildea, From Bill Wohler, From Jim Larus, History -@appendixsec From Stephen Gildea - -@cindex Gildea, Stephen -@cindex Stephen Gildea - -In 1987 I went to work for Bolt Beranek and Newman, as Jim had before -me. In my previous job, I had been using RMAIL, but as my folders tend -to run large, I was frustrated with the speed of RMAIL@. However, I -stuck with it because I wanted the GNU Emacs interface. I am very -familiar and comfortable with the Emacs interface (with just a few -modifications of my own) and dislike having to use applications with -embedded editors; they never live up to Emacs. - -MH is the mail reader of choice at BBN, so I converted to it. Since I -didn't want to give up using an Emacs interface, I started using MH-E. -As is my wont, I started hacking on it almost immediately. I first -used version 3.4m. One of the first features I added was to treat the -folder buffer as a file-visiting buffer: you could lock it, save it, -and be warned of unsaved changes when killing it. I also worked to -bring its functionality a little closer to RMAIL@. Jim Larus was very -cooperative about merging in my changes, and my efforts first appeared -in version 3.6, distributed with Emacs 18.52 in 1988. Next I decided -MH-E was too slow and optimized it a lot. Version, 3.7, distributed -with Emacs 18.56 in 1990, was noticeably faster. - -When I moved to the X Consortium I became the first person there to -not use xmh. (There is now one other engineer there using MH-E.) About -this point I took over maintenance of MH-E from Jim and was finally -able to add some features Jim hadn't accepted, such as the backward -searching undo. My first release was 3.8 (Emacs 18.58) in 1992. - -Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0. -Version 4.0 added many new features, including background folder -collection and support for composing @sc{mime} messages. (Reading -@sc{mime} messages remains to be done, alas.) While writing this book, -Bill Wohler gave MH-E its closest examination ever, uncovering bugs -and inconsistencies that required a new major version to fix, and so -version 5 was released. - -Stephen Gildea, June 1994 - -@node From Bill Wohler, , From Stephen Gildea, History -@appendixsec From Bill Wohler - -@cindex Wohler, Bill -@cindex Bill Wohler - -The preface originally included the following text which I use to -begin my story: - -@quotation -But it's important to note a brief history of MH-E. - -@w{Version 3} was prevalent through the @w{Emacs 18} and early -@w{Emacs 19} years. Then @w{Version 4} came out (@w{Emacs 19.23}), -which introduced several new and changed commands. Next, @w{Version -5.0} was released, which fixed some bugs and incompatibilities, and -was incorporated into @w{Emacs 19.29}. -@end quotation - -After a long break, Stephen handed the reins over to me in 2000. I -moved the project to a new site called SourceForge and organized a -great team of developers. Our first release in late 2001 was version -6. It appeared around the time of Emacs 21.2 and had menus and tool -bar buttons. - -Then, indexed searches, improved MIME handling, a speedbar, multiple -identities, alias completion, an index view of unseen messages, spam -software support, Face and X-Image-URL header field support, Fcc -completion, arbitrary range handling, and draft form editing were -introduced in the version 7 series around the time of Emacs 21.4 -(2004). Still, Emacs itself contained version 5 of MH-E released back -in 1994. - -Version 8 development was mostly driven by the rewrite of the manual. -It also brought GNU mailutils MH support, S/MIME support, picon -support, and an improved interface for hiding header fields. The CVS -repository was migrated from SourceForge to Savannah (only for those -files that were already part of Emacs) and the software was completely -reorganized to push back two decades of entropy. Version 8 appeared in -Emacs 22.1 in 2006. - -Development was then quiet for a couple of years. Emacs 23.1, which is -due out in 2009, will contain version 8.1. This version includes a few -new features and several bug fixes. - -Bill Wohler, August 2008 - -@node GFDL, GPL, History, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node GPL, Key Index, GFDL, Top -@appendix GNU General Public License -@include gpl.texi - -@node Key Index, Command Index, GPL, Top -@unnumbered Key (Character) Index -@printindex ky - -@node Command Index, Option Index, Key Index, Top -@unnumbered Command Index -@printindex fn - -@node Option Index, Concept Index, Command Index, Top -@unnumbered Option (Variable) Index -@printindex vr - -@node Concept Index, , Option Index, Top -@unnumbered Concept Index -@printindex cp - -@bye - -@c Ispell Helpers -@c -@c The following are words that ispell should ignore that would not -@c normally be in a dictionary (global or personal). Be careful not to -@c include words here that could potentially be typos of other words -@c (such as url, elisp, or MHE). -@c -@c LocalWords: CTRL ESC SPC f's -@c LocalWords: addr Aliasfile alist -@c LocalWords: Baushke Bcc BBN Beranek bogofilter bogofilter's -@c LocalWords: cmd CMU contrib cron -@c LocalWords: DesBrisay Dcc devel dir dired docstring filll forw -@c LocalWords: GECOS Gildea Gildea's Ginnean GnuCash goto gnuserv htm -@c LocalWords: ImageMagick inbox ispell keychain -@c LocalWords: Larus licensor LocalWords lookup lpr -@c LocalWords: makeinfo mairix mbox mh mhbuild mhl mhpath mlisp -@c LocalWords: MML msg multipart -@c LocalWords: Namazu NIS nenscript nnml num -@c LocalWords: packmbox passphrase pathname prev procmail prog repl -@c LocalWords: slocal sortm SpamAssassin spammers SpamProbe SpamProbe's -@c LocalWords: sublicense supercite speedbar -@c LocalWords: Tennex texi texinfo Thelen thelenm -@c LocalWords: UCI undeleted whatnow wohler xmh ypcat -@c -@c See http://www.oreilly.com/oreilly/author/stylesheet.html. -@c See http://en.wikipedia.org/. -@c -@c Note the lowercase mh which is needed to avoid hits in the -@c functions and variables. Occasionally, check for accidental -@c inclusion of mh in text by uncommenting the following and executing -@c it with C-x C-e. You want to see "Search failed" -@c (let ((case-fold-search nil)) -@c (goto-char (point-min)) -@c (search-forward-regexp "^mh\\( \\|$\\)")) -@c -@c An extremely useful setting for texinfo-mode-hook is: -@c (add-to-list -@c 'ispell-skip-region-alist -@c (list -@c (concat "\\(@\\(small\\)?\\(example\\|lisp\\)" -@c "\\(@\\([irw]\\|code\\|var\\){[^}]+}\\|" -@c "@[@{}.]\\|" -@c "[^@]\\|" -@c "@\\(end \\)?group\\|" -@c "@\\(end \\)?cartouche\\)+" -@c "@end \\(small\\)?\\(example\\|lisp\\)\\|" -@c "@\\(code\\|command\\|file\\|kbd\\|sc\\){[^}]+}\\|" -@c "^@end [a-z]+$\\|" -@c "^@\\([fv]\\|print\\)index .*$\\|" -@c "@uref{[^,]+,\\|" -@c "@[a-z]+\\|" -@c "/[a-z.]+[/}]\\)"))))) -@c -@c Cross References -@c -@c See existing cross-references to the Emacs manual and the Emacs -@c Lisp manual (search for ``GNU Emacs Manual'' and ``GNU -@c Emacs Lisp Reference Manual'' respectively). - -@c @ftable Sorting -@c -@c As per index (sort of): Punctuation, keyboard characters (such as -@c RET and BS) upper and lowercase mixed (lower comes before -@c uppercase), control characters go with uppercase C, meta characters -@c go with uppercase M. -@c In some cases, the sort isn't strictly ASCII. -@c For example, SPC (mh-page-msg) reads better before BS -@c (mh-previous-page) and . (mh-show) is better before , -@c (mh-header-display). - -@c @vtable Sorting -@c -@c Alphabetical, pull hooks into their own table. - -@c Local Variables: -@c sentence-end-double-space: nil -@c End: - -@ignore - arch-tag: b778477d-1a10-4a99-84de-f877a2ea6bef -@end ignore diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi deleted file mode 100644 index 10ac0069eb3..00000000000 --- a/doc/misc/newsticker.texi +++ /dev/null @@ -1,321 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename ../../info/newsticker -@set VERSION 1.99 -@set UPDATED June 2008 -@settitle Newsticker @value{VERSION} -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex pg cp -@comment %**end of header - -@copying -This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). - -@noindent -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Newsticker: (newsticker). A Newsticker for Emacs. -@end direntry - -@titlepage -@title Newsticker -- a Newsticker for Emacs -@subtitle for version @value{VERSION}, @value{UPDATED} -@author Ulf Jasper -@author @email{ulf.jasper@@web.de} -@author @uref{http://ulf.epplejasper.de/} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Newsticker - -@insertcopying - -@end ifnottex - -@menu -* Overview:: General description of newsticker. -* Requirements:: Requirements for using newsticker. -* Installation:: Installing newsticker on your system. -* Usage:: Basic newsticker instructions. -* Configuration:: Customizable newsticker settings. -* Remarks:: Remarks about newsticker. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Variable, function, and concept index. -@end menu - -@node Overview -@chapter Overview - -Newsticker provides a newsticker for Emacs. A newsticker is a thing -that asynchronously retrieves headlines from a list of news sites, -prepares these headlines for reading, and allows for loading the -corresponding articles in a web browser. - - -Headlines consist of a title and (possibly) a small description. They -are contained in "RSS" (RDF Site Summary) or "Atom" files. Newsticker -works with the following RSS formats: - -@itemize -@item RSS 0.91 (see @uref{http://backend.userland.com/rss091} or -@uref{http://my.netscape.com/publish/formats/rss-spec-0.91.html}), -@item RSS 0.92 (see @uref{http://backend.userland.com/rss092}), -@item RSS 1.0 (see @uref{http://purl.org/rss/1.0/spec} -@item RSS 2.0 (see @uref{http://blogs.law.harvard.edu/tech/rss}), -@end itemize -@itemize -as well as the following Atom formats: -@item Atom 0.3 -@item Atom 1.0 (see -@uref{http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-11.txt}). -@end itemize - -That makes Newsticker.el an ``Atom aggregator'', ``RSS reader'', ``Feed -aggregator'', or ``Feed reader''. - -Newsticker provides several commands for reading headlines, navigating -through them, marking them as read/unread, hiding old headlines etc. -Headlines can be displayed as plain text or as rendered HTML. - -Headlines can be displayed in the echo area, either scrolling like -messages in a stock-quote ticker, or just changing. - -Newsticker allows for automatic processing of headlines by providing -hooks and (sample) functions for automatically downloading images and -enclosed files (as delivered by podcasts, e.g.). - -@ifhtml -Here are screen shots of the @uref{newsticker-1.7.png, version 1.7 -(current version)} and some older screen shots: -@uref{newsticker-1.6.png, version 1.6}, -@uref{newsticker-1.5.png, version 1.5}, -@uref{newsticker-1.4.png, version 1.4} -@uref{newsticker-1.3.png, version 1.3}, -@uref{newsticker-1.0.png, version 1.0}. -@end ifhtml - -@node Requirements -@chapter Requirements - -Newsticker can be used with -@uref{http://www.gnu.org/software/emacs/emacs.html, GNU Emacs} version -21.1 or later as well as @uref{http://www.xemacs.org, XEmacs}. It -requires an XML-parser (@file{xml.el}) which is part of GNU Emacs. If -you are using XEmacs you want to get the @file{net-utils} package -which contains @file{xml.el} for XEmacs. - -Newsticker retrieves headlines either via Emacs' built-in retrieval -functions, by an arbitrary external program that retrieves files via -http and prints them to stdout (like -@uref{http://www.gnu.org/software/wget/wget.html, wget}, or -- on a -per feed basis -- via an arbitrary Lisp command. - - -@node Installation -@chapter Installation - -As Newsticker is part of GNU Emacs there is no need to perform any -installation steps in order to use Newsticker. - -However, if you are using imenu, which allows for navigating with the -help of a menu, you should add the following to your Emacs startup file -(@file{~/.emacs}). - -@lisp -(add-hook 'newsticker-mode-hook 'imenu-add-menubar-index) -@end lisp - -That's it. - -@node Usage -@chapter Usage - -@findex newsticker-show-news -The command @code{newsticker-show-news} will display all available -headlines. It will also start the asynchronous download of headlines. - -You can choose between two different frontends for reading headlines: -@itemize -@item Newsticker's @emph{treeview} uses separate windows for the -feeds (in tree form), a list of headlines for the current feed, and -the content of the current headline. Feeds can be placed into groups -which itself can be placed in groups and so on. -@item Newsticker's @emph{plainview} displays all headlines in a -single buffer, called @samp{*newsticker*}. The modeline in the -@samp{*newsticker*} buffer informs whenever new headlines have -arrived. -@end itemize -In both views clicking mouse-button 2 or pressing RET on a headline -will call @code{browse-url} to load the corresponding news story in -your favourite web browser. - -@findex newsticker-start-ticker -@findex newsticker-stop-ticker -The scrolling, or flashing of headlines in the echo area, can be -started with the command @code{newsticker-start-ticker}. It can be -stopped with @code{newsticker-stop-ticker}. - -@findex newsticker-start -@findex newsticker-stop -If you just want to start the periodic download of headlines use the -command @code{newsticker-start}. Calling @code{newsticker-stop} will -stop the periodic download, but will call -@code{newsticker-stop-ticker} as well. - -@node Configuration -@chapter Configuration - -All Newsticker options are customizable, i.e. they can be changed with -Emacs customization methods: Call the command -@code{customize-group} and enter @samp{newsticker} for the customization -group. - -All Newsticker options have reasonable default values, so that in most -cases it is not necessary to customize settings before starting Newsticker -for the first time. - -The following list shows the available groups of newsticker options -and some of the most important options. - -@itemize - -@item -@code{newsticker-retrieval} contains options that define which news -feeds are retrieved and how this is done. - -@itemize -@item -@vindex newsticker-url-list -@code{newsticker-url-list} defines the list of headlines which are -retrieved. -@item -@vindex newsticker-retrieval-method -@code{newsticker-retrieval-method} defines how headlines are -retrieved. This is either done using Emacs' built-in download -capabilities or using an external tool. -@item -@vindex newsticker-retrieval-interval -@code{newsticker-retrieval-interval} defines how often headlines -are retrieved. -@end itemize - -@item -@code{newsticker-headline-processing} contains options that define -how the retrieved headlines are processed. - -@itemize -@item -@vindex newsticker-keep-obsolete-items -@code{newsticker-keep-obsolete-items} decides whether unread -headlines that have been removed from the feed are kept in the -Newsticker cache. -@item -@vindex newsticker-auto-mark-filter-list -@code{newsticker-auto-mark-filter-list} provides the possibility to -automatically mark headlines as immortal or old. -@end itemize - -@item -@code{newsticker-hooks} contains options for hooking other Emacs -commands to newsticker functions. -@itemize -@item -@vindex newsticker-new-item-functions -@code{newsticker-new-item-functions} allows for automatic -processing of headlines. See `newsticker-download-images', and -`newsticker-download-enclosures' for sample functions. -@item -@vindex newsticker-plainview-hooks -The subgroup @code{newsticker-plainview-hooks} contains hook which -apply to the plainview reader only. -@end itemize - -@item -@code{newsticker-miscellaneous} contains other Newsticker options. - -@item -@code{newsticker-ticker} contains options that define how headlines -are shown in the echo area, i.e. the ``ticker''. - -@itemize -@item -@vindex newsticker-display-interval -@vindex newsticker-scroll-smoothly -@code{newsticker-ticker-interval} and -@code{newsticker-scroll-smoothly} define how headlines are shown in -the echo area. -@end itemize - - -@item -@code{newsticker-reader} contains options for adjusting the headline reader. - -@itemize -@item -@vindex newsticker-frontend -@code{newsticker-frontend} determines the actual headline reader. The -``plainview'' reader uses a single buffer, the ``treeview'' uses -separate buffers and windows. -@end itemize - -@itemize -@item -@vindex newsticker-plainview -The subgroup @code{newsticker-plainview} contains options for the -plainview reader. -@item -@vindex newsticker-treeview -The subgroup @code{newsticker-treeview} contains options for the -treeview reader. -@end itemize - -@end itemize - -For the complete list of options please have a look at the -customization buffers. - -@node Remarks -@chapter Remarks - -Byte-compiling newsticker.el is recommended. - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index - -@printindex cp - -@bye - - - -@ignore - arch-tag: 7a4de539-117c-4658-b799-0b9e3d0ccec0 -@end ignore diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi deleted file mode 100644 index a27835a7576..00000000000 --- a/doc/misc/nxml-mode.texi +++ /dev/null @@ -1,865 +0,0 @@ -\input texinfo @c -*- texinfo -*- -@c %**start of header -@setfilename ../../info/nxml-mode -@settitle nXML Mode -@c %**end of header - -@copying -This manual documents nxml-mode, an Emacs major mode for editing -XML with RELAX NG support. - -Copyright @copyright{} 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU -Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the -license is included in the section entitled ``GNU Free Documentation -License'' in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* nXML Mode: (nxml-mode). XML editing mode with RELAX NG support. -@end direntry - -@node Top -@top nXML Mode - -@insertcopying - -This manual is not yet complete. - -@menu -* Completion:: -* Inserting end-tags:: -* Paragraphs:: -* Outlining:: -* Locating a schema:: -* DTDs:: -* Limitations:: -@end menu - -@node Completion -@chapter Completion - -Apart from real-time validation, the most important feature that -nxml-mode provides for assisting in document creation is "completion". -Completion assists the user in inserting characters at point, based on -knowledge of the schema and on the contents of the buffer before -point. - -The traditional GNU Emacs key combination for completion in a -buffer is @kbd{M-@key{TAB}}. However, many window systems -and window managers use this key combination themselves (typically for -switching between windows) and do not pass it to applications. It's -hard to find key combinations in GNU Emacs that are both easy to type -and not taken by something else. @kbd{C-@key{RET}} (i.e. -pressing the Enter or Return key, while the Ctrl key is held down) is -available. It won't be available on a traditional terminal (because -it is indistinguishable from Return), but it will work with a window -system. Therefore we adopt the following solution by default: use -@kbd{C-@key{RET}} when there's a window system and -@kbd{M-@key{TAB}} when there's not. In the following, I -will assume that a window system is being used and will therefore -refer to @kbd{C-@key{RET}}. - -Completion works by examining the symbol preceding point. This -is the symbol to be completed. The symbol to be completed may be the -empty. Completion considers what symbols starting with the symbol to -be completed would be valid replacements for the symbol to be -completed, given the schema and the contents of the buffer before -point. These symbols are the possible completions. An example may -make this clearer. Suppose the buffer looks like this (where @point{} -indicates point): - -@example - - - -<@point{} -@end example - -@noindent -In this case, the symbol to be completed is empty, and the possible -completions are @samp{base}, @samp{isindex}, -@samp{link}, @samp{meta}, @samp{script}, -@samp{style}, @samp{title}. Another example is: - -@example - -<@point{} -@end example - -@noindent -@kbd{C-@key{RET}} will yield - -@example - - - - - - -@end example - -@noindent -This says to use the schema @samp{xhtml.rnc} for a document with -namespace @samp{http://www.w3.org/1999/xhtml}, and to use the -schema @samp{docbook.rnc} for a document whose local name is -@samp{book}. If the document element had both a namespace URI -of @samp{http://www.w3.org/1999/xhtml} and a local name of -@samp{book}, then the matching rule that comes first will be -used and so the schema @samp{xhtml.rnc} would be used. There is -no precedence between different types of rule; the first matching rule -of any type is used. - -As usual with XML-related technologies, resources are identified -by URIs. The @samp{uri} attribute identifies the schema by -specifying the URI. The URI may be relative. If so, it is resolved -relative to the URI of the schema locating file that contains -attribute. This means that if the value of @samp{uri} attribute -does not contain a @samp{/}, then it will refer to a filename in -the same directory as the schema locating file. - -@node Using the document's URI to locate a schema -@subsection Using the document's URI to locate a schema - -A @samp{uri} rule locates a schema based on the URI of the -document. The @samp{uri} attribute specifies the URI of the -schema. The @samp{resource} attribute can be used to specify -the schema for a particular document. For example, - -@example - -@end example - -@noindent -specifies that the schema for @samp{spec.xml} is -@samp{docbook.rnc}. - -The @samp{pattern} attribute can be used instead of the -@samp{resource} attribute to specify the schema for any document -whose URI matches a pattern. The pattern has the same syntax as an -absolute or relative URI except that the path component of the URI can -use a @samp{*} character to stand for zero or more characters -within a path segment (i.e. any character other @samp{/}). -Typically, the URI pattern looks like a relative URI, but, whereas a -relative URI in the @samp{resource} attribute is resolved into a -particular absolute URI using the base URI of the schema locating -file, a relative URI pattern matches if it matches some number of -complete path segments of the document's URI ending with the last path -segment of the document's URI. For example, - -@example - -@end example - -@noindent -specifies that the schema for documents with a URI whose path ends -with @samp{.xsl} is @samp{xslt.rnc}. - -A @samp{transformURI} rule locates a schema by -transforming the URI of the document. The @samp{fromPattern} -attribute specifies a URI pattern with the same meaning as the -@samp{pattern} attribute of the @samp{uri} element. The -@samp{toPattern} attribute is a URI pattern that is used to -generate the URI of the schema. Each @samp{*} in the -@samp{toPattern} is replaced by the string that matched the -corresponding @samp{*} in the @samp{fromPattern}. The -resulting string is appended to the initial part of the document's URI -that was not explicitly matched by the @samp{fromPattern}. The -rule matches only if the transformed URI identifies an existing -resource. For example, the rule - -@example - -@end example - -@noindent -would transform the URI @samp{file:///home/jjc/docs/spec.xml} -into the URI @samp{file:///home/jjc/docs/spec.rnc}. Thus, this -rule specifies that to locate a schema for a document -@samp{@var{foo}.xml}, Emacs should test whether a file -@samp{@var{foo}.rnc} exists in the same directory as -@samp{@var{foo}.xml}, and, if so, should use it as the -schema. - -@node Using the document element to locate a schema -@subsection Using the document element to locate a schema - -A @samp{documentElement} rule locates a schema based on -the local name and prefix of the document element. For example, a rule - -@example - -@end example - -@noindent -specifies that when the name of the document element is -@samp{xsl:stylesheet}, then @samp{xslt.rnc} should be used -as the schema. Either the @samp{prefix} or -@samp{localName} attribute may be omitted to allow any prefix or -local name. - -A @samp{namespace} rule locates a schema based on the -namespace URI of the document element. For example, a rule - -@example - -@end example - -@noindent -specifies that when the namespace URI of the document is -@samp{http://www.w3.org/1999/XSL/Transform}, then -@samp{xslt.rnc} should be used as the schema. - -@node Using type identifiers in schema locating files -@subsection Using type identifiers in schema locating files - -Type identifiers allow a level of indirection in locating the -schema for a document. Instead of associating the document directly -with a schema URI, the document is associated with a type identifier, -which is in turn associated with a schema URI. nXML mode does not -constrain the format of type identifiers. They can be simply strings -without any formal structure or they can be public identifiers or -URIs. Note that these type identifiers have nothing to do with the -DOCTYPE declaration. When comparing type identifiers, whitespace is -normalized in the same way as with the @samp{xsd:token} -datatype: leading and trailing whitespace is stripped; other sequences -of whitespace are normalized to a single space character. - -Each of the rules described in previous sections that uses a -@samp{uri} attribute to specify a schema, can instead use a -@samp{typeId} attribute to specify a type identifier. The type -identifier can be associated with a URI using a @samp{typeId} -element. For example, - -@example - - - - - - -@end example - -@noindent -declares three type identifiers @samp{XHTML} (representing the -default variant of XHTML to be used), @samp{XHTML Strict} and -@samp{XHTML Transitional}. Such a schema locating file would -use @samp{xhtml-strict.rnc} for a document whose namespace is -@samp{http://www.w3.org/1999/xhtml}. But it is considerably -more flexible than a schema locating file that simply specified - -@example - -@end example - -@noindent -A user can easily use @kbd{C-c C-s C-t} to select between XHTML -Strict and XHTML Transitional. Also, a user can easily add a catalog - -@example - - - -@end example - -@noindent -that makes the default variant of XHTML be XHTML Transitional. - -@node Using multiple schema locating files -@subsection Using multiple schema locating files - -The @samp{include} element includes rules from another -schema locating file. The behavior is exactly as if the rules from -that file were included in place of the @samp{include} element. -Relative URIs are resolved into absolute URIs before the inclusion is -performed. For example, - -@example - -@end example - -@noindent -includes the rules from @samp{rules.xml}. - -The process of locating a schema takes as input a list of schema -locating files. The rules in all these files and in the files they -include are resolved into a single list of rules, which are applied -strictly in order. Sometimes this order is not what is needed. -For example, suppose you have two schema locating files, a private -file - -@example - - - -@end example - -@noindent -followed by a public file - -@example - - - - -@end example - -@noindent -The effect of these two files is that the XHTML @samp{namespace} -rule takes precedence over the @samp{transformURI} rule, which -is almost certainly not what is needed. This can be solved by adding -an @samp{applyFollowingRules} to the private file. - -@example - - - - -@end example - -@node DTDs -@chapter DTDs - -nxml-mode is designed to support the creation of standalone XML -documents that do not depend on a DTD. Although it is common practice -to insert a DOCTYPE declaration referencing an external DTD, this has -undesirable side-effects. It means that the document is no longer -self-contained. It also means that different XML parsers may interpret -the document in different ways, since the XML Recommendation does not -require XML parsers to read the DTD. With DTDs, it was impractical to -get validation without using an external DTD or reference to an -parameter entity. With RELAX NG and other schema languages, you can -simulataneously get the benefits of validation and standalone XML -documents. Therefore, I recommend that you do not reference an -external DOCTYPE in your XML documents. - -One problem is entities for characters. Typically, as well as -providing validation, DTDs also provide a set of character entities -for documents to use. Schemas cannot provide this functionality, -because schema validation happens after XML parsing. The recommended -solution is to either use the Unicode characters directly, or, if this -is impractical, use character references. nXML mode supports this by -providing commands for entering characters and character references -using the Unicode names, and can display the glyph corresponding to a -character reference. - -@node Limitations -@chapter Limitations - -nXML mode has some limitations: - -@itemize @bullet -@item -DTD support is limited. Internal parsed general entities declared -in the internal subset are supported provided they do not contain -elements. Other usage of DTDs is ignored. -@item -The restrictions on RELAX NG schemas in section 7 of the RELAX NG -specification are not enforced. -@item -Unicode support has problems. This stems mostly from the fact that -the XML (and RELAX NG) character model is based squarely on Unicode, -whereas the Emacs character model is not. Emacs 22 is slated to have -full Unicode support, which should improve the situation here. -@end itemize - -@bye - -@ignore - arch-tag: 3b6e8ac2-ae8d-4f38-bd43-ce9f80be04d6 -@end ignore diff --git a/doc/misc/org.texi b/doc/misc/org.texi deleted file mode 100644 index aad349567fb..00000000000 --- a/doc/misc/org.texi +++ /dev/null @@ -1,10525 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/org -@settitle The Org Manual - -@set VERSION 6.21b -@set DATE February 2009 - -@c Version and Contact Info -@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage} -@set AUTHOR Carsten Dominik -@set MAINTAINER Carsten Dominik -@set MAINTAINEREMAIL @email{carsten at orgmode dot org} -@set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer} -@c %**end of header -@finalout - -@c Macro definitions - -@c Subheadings inside a table. -@macro tsubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@copying -This manual is for Org (version @value{VERSION}). - -Copyright @copyright{} 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Org Mode: (org). Outline-based notes management and organizer -@end direntry - -@titlepage -@title The Org Manual - -@subtitle Release @value{VERSION} -@author by Carsten Dominik - -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@c Output the table of contents at the beginning. -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@top Org Mode Manual - -@insertcopying -@end ifnottex - -@menu -* Introduction:: Getting started -* Document Structure:: A tree works like your brain -* Tables:: Pure magic for quick formatting -* Hyperlinks:: Notes in context -* TODO Items:: Every tree branch can be a TODO item -* Tags:: Tagging headlines and matching sets of tags -* Properties and Columns:: Storing information about an entry -* Dates and Times:: Making items useful for planning -* Capture:: Creating tasks and attaching files -* Agenda Views:: Collecting information into views -* Embedded LaTeX:: LaTeX fragments and formulas -* Exporting:: Sharing and publishing of notes -* Publishing:: Create a web site of linked Org files -* Miscellaneous:: All the rest which did not fit elsewhere -* Extensions:: Add-ons for Org mode -* Hacking:: How to hack your way around -* History and Acknowledgments:: How Org came into being -* Main Index:: An index of Org's concepts and features -* Key Index:: Key bindings and where they are described - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual - -Document Structure - -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Archiving:: Move done task trees to a different place -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org - -Archiving - -* ARCHIVE tag:: Marking a tree as inactive -* Moving subtrees:: Moving a tree to an archive file - -Tables - -* Built-in table editor:: Simple tables -* Narrow columns:: Stop wasting space in tables -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org Plot:: Plotting from org tables - -The spreadsheet - -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Field formulas:: Formulas valid for a single field -* Column formulas:: Formulas valid for an entire column -* Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc - -Hyperlinks - -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough - -Internal links - -* Radio targets:: Make targets trigger links in plain text - -TODO Items - -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists - -Extended use of TODO keywords - -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others - -Progress logging - -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? - -Tags - -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags - -Properties and Columns - -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers - -Column view - -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view - -Defining columns - -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column - -Dates and Times - -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer - -Creating timestamps - -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different - -Deadlines and scheduling - -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again - -Capture - -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. - -Remember - -* Setting up Remember:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs -* Refiling notes:: Moving a note or task to a project - -Agenda Views - -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Agenda column view:: Using column view for collected entries - -The built-in agenda views - -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Keyword search:: Finding entries by keyword -* Stuck projects:: Find projects you need to review - -Presentation and sorting - -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things - -Custom agenda views - -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules -* Exporting Agenda Views:: Writing agendas to files -* Using the agenda elsewhere:: Using agenda information in other programs - -Embedded LaTeX - -* Math symbols:: TeX macros for symbols and Greek letters -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Processing LaTeX fragments:: Previewing LaTeX processing -* CDLaTeX mode:: Speed up entering of formulas - -Exporting - -* Markup rules:: Which structures are recognized? -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII export:: Exporting to plain ASCII -* HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format - -Markup rules - -* Document title:: How the document title is determined -* Headings and sections:: The main structure of the exported document -* Table of contents:: If, where, how to create a table of contents -* Initial text:: Text before the first headline -* Lists:: Plain lists are exported -* Paragraphs:: What determines beginning and ending -* Literal examples:: Source code and other examples -* Include files:: Include the contents of a file during export -* Tables exported:: Tables are exported richly -* Inlined images:: How to inline images during export -* Footnote markup:: -* Emphasis and monospace:: To bold or not to bold -* TeX macros and LaTeX fragments:: Create special, rich export. -* Horizontal rules:: A line across the page -* Comment lines:: Some lines will not be exported - -HTML export - -* HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode -* Links:: Transformation of links for HTML -* Images in HTML export:: How to insert figures into HTML output -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser - -LaTeX and PDF export - -* LaTeX/PDF export commands:: Which key invokes which commands -* Quoting LaTeX code:: Incorporating literal LaTeX code -* Sectioning structure:: Changing sectioning in LaTeX output -* Tables in LaTeX export:: Options for exporting tables to LaTeX -* Images in LaTeX export:: How to insert figures into LaTeX output - -Publishing - -* Configuration:: Defining projects -* Sample configuration:: Example projects -* Triggering publication:: Publication commands - -Configuration - -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML export -* Publishing links:: Which links keep working after publishing? -* Project page index:: Publishing a list of project files - -Sample configuration - -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example - -Miscellaneous - -* Completion:: M-TAB knows what you need -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages -* Bugs:: Things which do not work perfectly - -Interaction with other packages - -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts - -Extensions - -* Extensions in the contrib directory:: These come with the Org distro -* Other extensions:: These you have to find on the web. - -Hacking - -* Adding hyperlink types:: New custom link types -* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries - -Tables and lists in arbitrary syntax - -* Radio tables:: Sending and receiving -* A LaTeX example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists - -@end detailmenu -@end menu - -@node Introduction, Document Structure, Top, Top -@chapter Introduction -@cindex introduction - -@menu -* Summary:: Brief summary of what Org does -* Installation:: How to install a downloaded version of Org -* Activation:: How to activate Org for certain buffers -* Feedback:: Bug reports, ideas, patches etc. -* Conventions:: Type-setting conventions in the manual -@end menu - -@node Summary, Installation, Introduction, Introduction -@section Summary -@cindex summary - -Org is a mode for keeping notes, maintaining TODO lists, and doing -project planning with a fast and effective plain-text system. - -Org develops organizational tasks around NOTES files that contain -lists or information about projects as plain text. Org is -implemented on top of Outline mode, which makes it possible to keep the -content of large files well structured. Visibility cycling and -structure editing help to work with the tree. Tables are easily created -with a built-in table editor. Org supports TODO items, deadlines, -time stamps, and scheduling. It dynamically compiles entries into an -agenda that utilizes and smoothly integrates much of the Emacs calendar -and diary. Plain text URL-like links connect to websites, emails, -Usenet messages, BBDB entries, and any files related to the projects. -For printing and sharing of notes, an Org file can be exported as a -structured ASCII file, as HTML, or (TODO and agenda items only) as an -iCalendar file. It can also serve as a publishing tool for a set of -linked web pages. - -An important design aspect that distinguishes Org from for example -Planner/Muse is that it encourages to store every piece of information -only once. In Planner, you have project pages, day pages and possibly -other files, duplicating some information such as tasks. In Org, -you only have notes files. In your notes you mark entries as tasks, -label them with tags and timestamps. All necessary lists like a -schedule for the day, the agenda for a meeting, tasks lists selected by -tags etc are created dynamically when you need them. - -Org keeps simple things simple. When first fired up, it should -feel like a straightforward, easy to use outliner. Complexity is not -imposed, but a large amount of functionality is available when you need -it. Org is a toolbox and can be used in different ways, for -example as: - -@example -@r{@bullet{} outline extension with visibility cycling and structure editing} -@r{@bullet{} ASCII system and table editor for taking structured notes} -@r{@bullet{} ASCII table editor with spreadsheet-like capabilities} -@r{@bullet{} TODO list editor} -@r{@bullet{} full agenda and planner with deadlines and work scheduling} -@r{@bullet{} environment to implement David Allen's GTD system} -@r{@bullet{} a basic database application} -@r{@bullet{} simple hypertext system, with HTML and LaTeX export} -@r{@bullet{} publishing tool to create a set of interlinked webpages} -@end example - -Org's automatic, context sensitive table editor with spreadsheet -capabilities can be integrated into any major mode by activating the -minor Orgtbl mode. Using a translation step, it can be used to maintain -tables in arbitrary file types, for example in La@TeX{}. The structure -editing and list creation capabilities can be used outside Org with -the minor Orgstruct mode. - -@cindex FAQ -There is a website for Org which provides links to the newest -version of Org, as well as additional information, frequently asked -questions (FAQ), links to tutorials etc. This page is located at -@uref{http://orgmode.org}. - -@page - - -@node Installation, Activation, Summary, Introduction -@section Installation -@cindex installation -@cindex XEmacs - -@b{Important:} @i{If Org is part of the Emacs distribution or an -XEmacs package, please skip this section and go directly to -@ref{Activation}.} - -If you have downloaded Org from the Web, either as a distribution @file{.zip} -or @file{.tar} file, or as a GIT archive, you must take the following steps -to install it: Go into the unpacked Org distribution directory and edit the -top section of the file @file{Makefile}. You must set the name of the Emacs -binary (likely either @file{emacs} or @file{xemacs}), and the paths to the -directories where local Lisp and Info files are kept. If you don't have -access to the system-wide directories, you can simply run Org directly from -the distribution directory by adding the @file{lisp} subdirectory to the -Emacs load path. To do this, add the following line to @file{.emacs}: - -@example -(setq load-path (cons "~/path/to/orgdir/lisp" load-path)) -@end example - -@noindent -If you plan to use code from the @file{contrib} subdirectory, do a similar -step for this directory: - -@example -(setq load-path (cons "~/path/to/orgdir/contrib/lisp" load-path)) -@end example - -@b{XEmacs users now need to install the file @file{noutline.el} from -the @file{xemacs} sub-directory of the Org distribution. Use the -command:} - -@example -@b{make install-noutline} -@end example - -@noindent Now byte-compile the Lisp files with the shell command: - -@example -make -@end example - -@noindent If you are running Org from the distribution directory, this is -all. If you want to install into the system directories, use - -@example -make install -make install-info -@end example - -@noindent Then add to @file{.emacs}: - -@lisp -;; This line only if Org is not part of the X/Emacs distribution. -(require 'org-install) -@end lisp - -Do not forget to activate Org as described in the following section. - -@node Activation, Feedback, Installation, Introduction -@section Activation -@cindex activation -@cindex autoload -@cindex global key bindings -@cindex key bindings, global - -@iftex -@b{Important:} @i{If you use copy-and-paste to copy lisp code from the -PDF documentation as viewed by some PDF viewers to your .emacs file, the -single quote character comes out incorrectly and the code will not work. -You need to fix the single quotes by hand, or copy from Info -documentation.} -@end iftex - -Add the following lines to your @file{.emacs} file. The last three lines -define @emph{global} keys for the commands @command{org-store-link}, -@command{org-agenda}, and @command{org-iswitchb} - please choose suitable -keys yourself. - -@lisp -;; The following lines are always needed. Choose your own keys. -(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode)) -(global-set-key "\C-cl" 'org-store-link) -(global-set-key "\C-ca" 'org-agenda) -(global-set-key "\C-cb" 'org-iswitchb) -@end lisp - -Furthermore, you must activate @code{font-lock-mode} in Org -buffers, because significant functionality depends on font-locking being -active. You can do this with either one of the following two lines -(XEmacs user must use the second option): -@lisp -(global-font-lock-mode 1) ; for all buffers -(add-hook 'org-mode-hook 'turn-on-font-lock) ; Org buffers only -@end lisp - -@cindex Org mode, turning on -With this setup, all files with extension @samp{.org} will be put -into Org mode. As an alternative, make the first line of a file look -like this: - -@example -MY PROJECTS -*- mode: org; -*- -@end example - -@noindent which will select Org mode for this buffer no matter what -the file's name is. See also the variable -@code{org-insert-mode-line-in-empty-file}. - -Many commands in Org work on the region if the region is active. To make use -of this, you need to have @code{transient-mark-mode} (@code{zmacs-regions} in -XEmacs) turned on. In Emacs 23 this is the default, in Emacs 22 you need to -do this yourself with - -@lisp -(transient-mark-mode 1) -@end lisp - -@node Feedback, Conventions, Activation, Introduction -@section Feedback -@cindex feedback -@cindex bug reports -@cindex maintainer -@cindex author - -If you find problems with Org, or if you have questions, remarks, or ideas -about it, please mail to the Org mailing list @code{emacs-orgmode@@gnu.org}. -If you are not a member of the mailing list, your mail will be reviewed by a -moderator and then passed through to the list. - -For bug reports, please provide as much information as possible, -including the version information of Emacs (@kbd{C-h v emacs-version -@key{RET}}) and Org (@kbd{C-h v org-version @key{RET}}), as well as -the Org related setup in @file{.emacs}. If an error occurs, a -backtrace can be very useful (see below on how to create one). Often a -small example file helps, along with clear information about: - -@enumerate -@item What exactly did you do? -@item What did you expect to happen? -@item What happened instead? -@end enumerate -@noindent Thank you for helping to improve this mode. - -@subsubheading How to create a useful backtrace - -@cindex backtrace of an error -If working with Org produces an error with a message you don't -understand, you may have hit a bug. The best way to report this is by -providing, in addition to what was mentioned above, a @emph{Backtrace}. -This is information from the built-in debugger about where and how the -error occurred. Here is how to produce a useful backtrace: - -@enumerate -@item -Start a fresh Emacs or XEmacs, and make sure that it will load the -original Lisp code in @file{org.el} instead of the compiled version in -@file{org.elc}. The backtrace contains much more information if it is -produced with uncompiled code. To do this, either rename @file{org.elc} -to something else before starting Emacs, or ask Emacs explicitly to load -@file{org.el} by using the command line -@example -emacs -l /path/to/org.el -@end example -@item -Go to the @code{Options} menu and select @code{Enter Debugger on Error} -(XEmacs has this option in the @code{Troubleshooting} sub-menu). -@item -Do whatever you have to do to hit the error. Don't forget to -document the steps you take. -@item -When you hit the error, a @file{*Backtrace*} buffer will appear on the -screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and -attach it to your bug report. -@end enumerate - -@node Conventions, , Feedback, Introduction -@section Typesetting conventions used in this manual - -Org uses three types of keywords: TODO keywords, tags, and property -names. In this manual we use the following conventions: - -@table @code -@item TODO -@itemx WAITING -TODO keywords are written with all capitals, even if they are -user-defined. -@item boss -@itemx ARCHIVE -User-defined tags are written in lowercase; built-in tags with special -meaning are written with all capitals. -@item Release -@itemx PRIORITY -User-defined properties are capitalized; built-in properties with -special meaning are written with all capitals. -@end table - -@node Document Structure, Tables, Introduction, Top -@chapter Document Structure -@cindex document structure -@cindex structure of document - -Org is based on outline mode and provides flexible commands to -edit the structure of the document. - -@menu -* Outlines:: Org is based on Outline mode -* Headlines:: How to typeset Org tree headlines -* Visibility cycling:: Show and hide, much simplified -* Motion:: Jumping to other headlines -* Structure editing:: Changing sequence and level of headlines -* Archiving:: Move done task trees to a different place -* Sparse trees:: Matches embedded in context -* Plain lists:: Additional structure within an entry -* Drawers:: Tucking stuff away -* Footnotes:: How footnotes are defined in Org's syntax -* Orgstruct mode:: Structure editing outside Org -@end menu - -@node Outlines, Headlines, Document Structure, Document Structure -@section Outlines -@cindex outlines -@cindex Outline mode - -Org is implemented on top of Outline mode. Outlines allow a -document to be organized in a hierarchical structure, which (at least -for me) is the best representation of notes and thoughts. An overview -of this structure is achieved by folding (hiding) large parts of the -document to show only the general document structure and the parts -currently being worked on. Org greatly simplifies the use of -outlines by compressing the entire show/hide functionality into a single -command @command{org-cycle}, which is bound to the @key{TAB} key. - -@node Headlines, Visibility cycling, Outlines, Document Structure -@section Headlines -@cindex headlines -@cindex outline tree - -Headlines define the structure of an outline tree. The headlines in -Org start with one or more stars, on the left margin@footnote{See -the variable @code{org-special-ctrl-a/e} to configure special behavior -of @kbd{C-a} and @kbd{C-e} in headlines.}. For example: - -@example -* Top level headline -** Second level -*** 3rd level - some text -*** 3rd level - more text - -* Another top level headline -@end example - -@noindent Some people find the many stars too noisy and would prefer an -outline that has whitespace followed by a single star as headline -starters. @ref{Clean view} describes a setup to realize this. - -An empty line after the end of a subtree is considered part of it and -will be hidden when the subtree is folded. However, if you leave at -least two empty lines, one empty line will remain visible after folding -the subtree, in order to structure the collapsed view. See the -variable @code{org-cycle-separator-lines} to modify this behavior. - -@node Visibility cycling, Motion, Headlines, Document Structure -@section Visibility cycling -@cindex cycling, visibility -@cindex visibility cycling -@cindex trees, visibility -@cindex show hidden text -@cindex hide text - -Outlines make it possible to hide parts of the text in the buffer. -Org uses just two commands, bound to @key{TAB} and -@kbd{S-@key{TAB}} to change the visibility in the buffer. - -@cindex subtree visibility states -@cindex subtree cycling -@cindex folded, subtree visibility state -@cindex children, subtree visibility state -@cindex subtree, subtree visibility state -@table @kbd -@kindex @key{TAB} -@item @key{TAB} -@emph{Subtree cycling}: Rotate current subtree among the states - -@example -,-> FOLDED -> CHILDREN -> SUBTREE --. -'-----------------------------------' -@end example - -The cursor must be on a headline for this to work@footnote{see, however, -the option @code{org-cycle-emulate-tab}.}. When the cursor is at the -beginning of the buffer and the first line is not a headline, then -@key{TAB} actually runs global cycling (see below)@footnote{see the -option @code{org-cycle-global-at-bob}.}. Also when called with a prefix -argument (@kbd{C-u @key{TAB}}), global cycling is invoked. - -@cindex global visibility states -@cindex global cycling -@cindex overview, global visibility state -@cindex contents, global visibility state -@cindex show all, global visibility state -@kindex S-@key{TAB} -@item S-@key{TAB} -@itemx C-u @key{TAB} -@emph{Global cycling}: Rotate the entire buffer among the states - -@example -,-> OVERVIEW -> CONTENTS -> SHOW ALL --. -'--------------------------------------' -@end example - -When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the -CONTENTS view up to headlines of level N will be shown. Note that inside -tables, @kbd{S-@key{TAB}} jumps to the previous field. - -@cindex show all, command -@kindex C-u C-u C-u @key{TAB} -@item C-u C-u C-u @key{TAB} -Show all, including drawers. -@kindex C-c C-r -@item C-c C-r -Reveal context around point, showing the current entry, the following heading -and the hierarchy above. Useful for working near a location that has been -exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command -(@pxref{Agenda commands}). With a prefix argument show, on each -level, all sibling headings. -@kindex C-c C-x b -@item C-c C-x b -Show the current subtree in an indirect buffer@footnote{The indirect -buffer -@ifinfo -(@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) -@end ifinfo -@ifnotinfo -(see the Emacs manual for more information about indirect buffers) -@end ifnotinfo -will contain the entire buffer, but will be narrowed to the current -tree. Editing the indirect buffer will also change the original buffer, -but without affecting visibility in that buffer.}. With a numeric -prefix argument N, go up to level N and then take that tree. If N is -negative then go up that many levels. With a @kbd{C-u} prefix, do not remove -the previously used indirect buffer. -@end table - -When Emacs first visits an Org file, the global state is set to -OVERVIEW, i.e. only the top level headlines are visible. This can be -configured through the variable @code{org-startup-folded}, or on a -per-file basis by adding one of the following lines anywhere in the -buffer: - -@example -#+STARTUP: overview -#+STARTUP: content -#+STARTUP: showall -@end example - -@noindent -Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties -and Columns}) will get their visibility adapted accordingly. Allowed values -for this property are @code{folded}, @code{children}, @code{content}, and -@code{all}. -@table @kbd -@kindex C-u C-u @key{TAB} -@item C-u C-u @key{TAB} -Switch back to the startup visibility of the buffer, i.e. whatever is -requested by startup options and @samp{VISIBILITY} properties in individual -entries. -@end table - -@node Motion, Structure editing, Visibility cycling, Document Structure -@section Motion -@cindex motion, between headlines -@cindex jumping, to headlines -@cindex headline navigation -The following commands jump to other headlines in the buffer. - -@table @kbd -@kindex C-c C-n -@item C-c C-n -Next heading. -@kindex C-c C-p -@item C-c C-p -Previous heading. -@kindex C-c C-f -@item C-c C-f -Next heading same level. -@kindex C-c C-b -@item C-c C-b -Previous heading same level. -@kindex C-c C-u -@item C-c C-u -Backward to higher level heading. -@kindex C-c C-j -@item C-c C-j -Jump to a different place without changing the current outline -visibility. Shows the document structure in a temporary buffer, where -you can use the following keys to find your destination: -@example -@key{TAB} @r{Cycle visibility.} -@key{down} / @key{up} @r{Next/previous visible headline.} -@key{RET} @r{Select this location.} -@kbd{/} @r{Do a Sparse-tree search} -@r{The following keys work if you turn off @code{org-goto-auto-isearch}} -n / p @r{Next/previous visible headline.} -f / b @r{Next/previous headline same level.} -u @r{One level up.} -0-9 @r{Digit argument.} -q @r{Quit} -@end example -See also the variable@code{org-goto-interface}. -@end table - -@node Structure editing, Archiving, Motion, Document Structure -@section Structure editing -@cindex structure editing -@cindex headline, promotion and demotion -@cindex promotion, of subtrees -@cindex demotion, of subtrees -@cindex subtree, cut and paste -@cindex pasting, of subtrees -@cindex cutting, of subtrees -@cindex copying, of subtrees -@cindex subtrees, cut and paste - -@table @kbd -@kindex M-@key{RET} -@item M-@key{RET} -Insert new heading with same level as current. If the cursor is in a -plain list item, a new item is created (@pxref{Plain lists}). To force -creation of a new headline, use a prefix argument, or first press @key{RET} -to get to the beginning of the next line. When this command is used in -the middle of a line, the line is split and the rest of the line becomes -the new headline@footnote{If you do not want the line to be split, -customize the variable @code{org-M-RET-may-split-line}.}. If the -command is used at the beginning of a headline, the new headline is -created before the current line. If at the beginning of any other line, -the content of that line is made the new heading. If the command is -used at the end of a folded subtree (i.e. behind the ellipses at the end -of a headline), then a headline like the current one will be inserted -after the end of the subtree. -@kindex C-@key{RET} -@item C-@key{RET} -Just like @kbd{M-@key{RET}}, except when adding a new heading below the -current heading, the new heading is placed after the body instead of before -it. This command works from anywhere in the entry. -@kindex M-S-@key{RET} -@item M-S-@key{RET} -Insert new TODO entry with same level as current heading. -@kindex C-S-@key{RET} -@item C-S-@key{RET} -Insert new TODO entry with same level as current heading. Like -@kbd{C-@key{RET}}, the new headline will be inserted after the current -subtree. -@kindex M-@key{left} -@item M-@key{left} -Promote current heading by one level. -@kindex M-@key{right} -@item M-@key{right} -Demote current heading by one level. -@kindex M-S-@key{left} -@item M-S-@key{left} -Promote the current subtree by one level. -@kindex M-S-@key{right} -@item M-S-@key{right} -Demote the current subtree by one level. -@kindex M-S-@key{up} -@item M-S-@key{up} -Move subtree up (swap with previous subtree of same -level). -@kindex M-S-@key{down} -@item M-S-@key{down} -Move subtree down (swap with next subtree of same level). -@kindex C-c C-x C-w -@item C-c C-x C-w -Kill subtree, i.e. remove it from buffer but save in kill ring. -With a numeric prefix argument N, kill N sequential subtrees. -@kindex C-c C-x M-w -@item C-c C-x M-w -Copy subtree to kill ring. With a numeric prefix argument N, copy the N -sequential subtrees. -@kindex C-c C-x C-y -@item C-c C-x C-y -Yank subtree from kill ring. This does modify the level of the subtree to -make sure the tree fits in nicely at the yank position. The yank level can -also be specified with a numeric prefix argument, or by yanking after a -headline marker like @samp{****}. -@kindex C-y -@item C-y -Depending on the variables @code{org-yank-adjusted-subtrees} and -@code{org-yank-folded-subtrees}, Org's internal @code{yank} command will -paste subtrees folded and in a clever way, using the same command as @kbd{C-c -C-x C-y}. With the default settings, no level adjustment will take place, -but the yanked tree will be folded unless doing so would swallow text -previously visible. Any prefix argument to this command will force a normal -@code{yank} to be executed, with the prefix passed along. A good way to -force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a -yank, it will yank previous kill items plainly, without adjustment and -folding. -@kindex C-c C-w -@item C-c C-w -Refile entry or region to a different location. @xref{Refiling notes}. -@kindex C-c ^ -@item C-c ^ -Sort same-level entries. When there is an active region, all entries in the -region will be sorted. Otherwise the children of the current headline are -sorted. The command prompts for the sorting method, which can be -alphabetically, numerically, by time (using the first time stamp in each -entry), by priority, or by TODO keyword (in the sequence the keywords have -been defined in the setup). Reverse sorting is possible as well. You can -also supply your own function to extract the sorting key. With a @kbd{C-u} -prefix, sorting will be case-sensitive. With two @kbd{C-u C-u} prefixes, -duplicate entries will also be removed. -@kindex C-x n s -@item C-x n s -Narrow buffer to current subtree. -@kindex C-x n w -@item C-x n w -Widen buffer to remove a narrowing. -@kindex C-c * -@item C-c * -Turn a normal line or plain list item into a headline (so that it becomes a -subheading at its location). Also turn a headline into a normal line by -removing the stars. If there is an active region, turn all lines in the -region into headlines. If the first line in the region was an item, turn -only the item lines into headlines. Finally, if the first line is a -headline, remove the stars from all headlines in the region. -@end table - -@cindex region, active -@cindex active region -@cindex Transient mark mode -When there is an active region (Transient mark mode), promotion and -demotion work on all headlines in the region. To select a region of -headlines, it is best to place both point and mark at the beginning of a -line, mark at the beginning of the first headline, and point at the line -just after the last headline to change. Note that when the cursor is -inside a table (@pxref{Tables}), the Meta-Cursor keys have different -functionality. - -@node Archiving, Sparse trees, Structure editing, Document Structure -@section Archiving -@cindex archiving - -When a project represented by a (sub)tree is finished, you may want -to move the tree out of the way and to stop it from contributing to the -agenda. Org mode knows two ways of archiving. You can mark a tree with -the ARCHIVE tag, or you can move an entire (sub)tree to a different -location. - -@menu -* ARCHIVE tag:: Marking a tree as inactive -* Moving subtrees:: Moving a tree to an archive file -@end menu - -@node ARCHIVE tag, Moving subtrees, Archiving, Archiving -@subsection The ARCHIVE tag -@cindex internal archiving - -A headline that is marked with the ARCHIVE tag (@pxref{Tags}) stays at -its location in the outline tree, but behaves in the following way: -@itemize @minus -@item -It does not open when you attempt to do so with a visibility cycling -command (@pxref{Visibility cycling}). You can force cycling archived -subtrees with @kbd{C-@key{TAB}}, or by setting the option -@code{org-cycle-open-archived-trees}. Also normal outline commands like -@code{show-all} will open archived subtrees. -@item -During sparse tree construction (@pxref{Sparse trees}), matches in -archived subtrees are not exposed, unless you configure the option -@code{org-sparse-tree-open-archived-trees}. -@item -During agenda view construction (@pxref{Agenda Views}), the content of -archived trees is ignored unless you configure the option -@code{org-agenda-skip-archived-trees}, in which case these trees will always -be included. In the agenda you can press the @kbd{v} key to get archives -temporarily included. -@item -Archived trees are not exported (@pxref{Exporting}), only the headline -is. Configure the details using the variable -@code{org-export-with-archived-trees}. -@end itemize - -The following commands help managing the ARCHIVE tag: - -@table @kbd -@kindex C-c C-x a -@item C-c C-x a -Toggle the ARCHIVE tag for the current headline. When the tag is set, -the headline changes to a shadowed face, and the subtree below it is -hidden. -@kindex C-u C-c C-x a -@item C-u C-c C-x a -Check if any direct children of the current headline should be archived. -To do this, each subtree is checked for open TODO entries. If none are -found, the command offers to set the ARCHIVE tag for the child. If the -cursor is @emph{not} on a headline when this command is invoked, the -level 1 trees will be checked. -@kindex C-@kbd{TAB} -@item C-@kbd{TAB} -Cycle a tree even if it is tagged with ARCHIVE. -@end table - -@node Moving subtrees, , ARCHIVE tag, Archiving -@subsection Moving subtrees -@cindex external archiving - -Once an entire project is finished, you may want to move it to a different -location. Org can move it to an @emph{Archive Sibling} in the same tree, to a -different tree in the current file, or to a different file, the archive file. - -@table @kbd -@kindex C-c C-x A -@item C-c C-x A -Move the current entry to the @emph{Archive Sibling}. This is a sibling of -the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE} -(@pxref{ARCHIVE tag}). The entry becomes a child of that sibling and in this -way retains a lot of its original context, including inherited tags and -approximate position in the outline. -@kindex C-c C-x C-s -@item C-c C-x C-s -Archive the subtree starting at the cursor position to the location -given by @code{org-archive-location}. Context information that could be -lost like the file name, the category, inherited tags, and the TODO -state will be store as properties in the entry. -@kindex C-u C-c C-x C-s -@item C-u C-c C-x C-s -Check if any direct children of the current headline could be moved to -the archive. To do this, each subtree is checked for open TODO entries. -If none are found, the command offers to move it to the archive -location. If the cursor is @emph{not} on a headline when this command -is invoked, the level 1 trees will be checked. -@end table - -@cindex archive locations -The default archive location is a file in the same directory as the -current file, with the name derived by appending @file{_archive} to the -current file name. For information and examples on how to change this, -see the documentation string of the variable -@code{org-archive-location}. There is also an in-buffer option for -setting this variable, for example@footnote{For backward compatibility, -the following also works: If there are several such lines in a file, -each specifies the archive location for the text below it. The first -such line also applies to any text before its definition. However, -using this method is @emph{strongly} deprecated as it is incompatible -with the outline structure of the document. The correct method for -setting multiple archive locations in a buffer is using properties.}: - -@example -#+ARCHIVE: %s_done:: -@end example - -@noindent -If you would like to have a special ARCHIVE location for a single entry -or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the -location as the value (@pxref{Properties and Columns}). - -When a subtree is moved, it receives a number of special properties that -record context information like the file from where the entry came, it's -outline path the archiving time etc. Configure the variable -@code{org-archive-save-context-info} to adjust the amount of information -added. - -@node Sparse trees, Plain lists, Archiving, Document Structure -@section Sparse trees -@cindex sparse trees -@cindex trees, sparse -@cindex folding, sparse trees -@cindex occur, command - -An important feature of Org mode is the ability to construct @emph{sparse -trees} for selected information in an outline tree, so that the entire -document is folded as much as possible, but the selected information is made -visible along with the headline structure above it@footnote{See also the -variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, -@code{org-show-siblings}, and @code{org-show-entry-below} for detailed -control on how much context is shown around each match.}. Just try it out -and you will see immediately how it works. - -Org mode contains several commands creating such trees, all these -commands can be accessed through a dispatcher: - -@table @kbd -@kindex C-c / -@item C-c / -This prompts for an extra key to select a sparse-tree creating command. -@kindex C-c / r -@item C-c / r -Occur. Prompts for a regexp and shows a sparse tree with all matches. If -the match is in a headline, the headline is made visible. If the match is in -the body of an entry, headline and body are made visible. In order to -provide minimal context, also the full hierarchy of headlines above the match -is shown, as well as the headline following the match. Each match is also -highlighted; the highlights disappear when the buffer is changed by an -editing command@footnote{depending on the option -@code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}. -When called with a @kbd{C-u} prefix argument, previous highlights are kept, -so several calls to this command can be stacked. -@end table - -@noindent -For frequently used sparse trees of specific search strings, you can -use the variable @code{org-agenda-custom-commands} to define fast -keyboard access to specific sparse trees. These commands will then be -accessible through the agenda dispatcher (@pxref{Agenda dispatcher}). -For example: - -@lisp -(setq org-agenda-custom-commands - '(("f" occur-tree "FIXME"))) -@end lisp - -@noindent will define the key @kbd{C-c a f} as a shortcut for creating -a sparse tree matching the string @samp{FIXME}. - -The other sparse tree commands select headings based on TODO keywords, -tags, or properties and will be discussed later in this manual. - -@kindex C-c C-e v -@cindex printing sparse trees -@cindex visible text, printing -To print a sparse tree, you can use the Emacs command -@code{ps-print-buffer-with-faces} which does not print invisible parts -of the document @footnote{This does not work under XEmacs, because -XEmacs uses selective display for outlining, not text properties.}. -Or you can use the command @kbd{C-c C-e v} to export only the visible -part of the document and print the resulting file. - -@node Plain lists, Drawers, Sparse trees, Document Structure -@section Plain lists -@cindex plain lists -@cindex lists, plain -@cindex lists, ordered -@cindex ordered lists - -Within an entry of the outline tree, hand-formatted lists can provide -additional structure. They also provide a way to create lists of -checkboxes (@pxref{Checkboxes}). Org supports editing such lists, -and the HTML exporter (@pxref{Exporting}) parses and formats them. - -Org knows ordered lists, unordered lists, and description lists. -@itemize @bullet -@item -@emph{Unordered} list items start with @samp{-}, @samp{+}, or -@samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or -they will be seen as top-level headlines. Also, when you are hiding leading -stars to get a clean outline view, plain list items starting with a star are -visually indistinguishable from true headlines. In short: even though -@samp{*} is supported, it may be better to not use it for plain list items.} -as bullets. -@item -@emph{Ordered} list items start with a numeral followed by either a period or -a right parenthesis, such as @samp{1.} or @samp{1)}. -@item -@emph{Description} list items are like unordered list items, but contain the -separator @samp{ :: } to separate the description @emph{term} from the -description. -@end itemize - -Items belonging to the same list must have the same indentation on the first -line. In particular, if an ordered list reaches number @samp{10.}, then the -2--digit numbers must be written left-aligned with the other numbers in the -list. Indentation also determines the end of a list item. It ends before -the next line that is indented like the bullet/number, or less. Empty lines -are part of the previous item, so you can have several paragraphs in one -item. If you would like an empty line to terminate all currently open plain -lists, configure the variable @code{org-empty-line-terminates-plain-lists}. -Here is an example: - -@example -@group -** Lord of the Rings - My favorite scenes are (in this order) - 1. The attack of the Rohirrim - 2. Eowyn's fight with the witch king - + this was already my favorite scene in the book - + I really like Miranda Otto. - 3. Peter Jackson being shot by Legolas - - on DVD only - He makes a really funny face when it happens. - But in the end, no individual scenes matter but the film as a whole. - Important actors in this film are: - - @b{Elijah Wood} :: He plays Frodo - - @b{Sean Austin} :: He plays Sam, Frodo's friend. I still remember - him very well from his role as Mikey Walsh in the Goonies. -@end group -@end example - -Org supports these lists by tuning filling and wrapping commands to -deal with them correctly@footnote{Org only changes the filling -settings for Emacs. For XEmacs, you should use Kyle E. Jones' -@file{filladapt.el}. To turn this on, put into @file{.emacs}: -@code{(require 'filladapt)}}, and by exporting them properly -(@pxref{Exporting}). - -The following commands act on items when the cursor is in the first line -of an item (the line with the bullet or number). - -@table @kbd -@kindex @key{TAB} -@item @key{TAB} -Items can be folded just like headline levels if you set the variable -@code{org-cycle-include-plain-lists}. The level of an item is then -given by the indentation of the bullet/number. Items are always -subordinate to real headlines, however; the hierarchies remain -completely separated. - -If @code{org-cycle-include-plain-lists} has not been set, @key{TAB} -fixes the indentation of the current line in a heuristic way. -@kindex M-@key{RET} -@item M-@key{RET} -Insert new item at current level. With a prefix argument, force a new -heading (@pxref{Structure editing}). If this command is used in the middle -of a line, the line is @emph{split} and the rest of the line becomes the new -item@footnote{If you do not want the line to be split, customize the variable -@code{org-M-RET-may-split-line}.}. If this command is executed in the -@emph{whitespace before a bullet or number}, the new item is created -@emph{before} the current item. If the command is executed in the white -space before the text that is part of an item but does not contain the -bullet, a bullet is added to the current line. -@kindex M-S-@key{RET} -@item M-S-@key{RET} -Insert a new item with a checkbox (@pxref{Checkboxes}). -@kindex S-@key{up} -@kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} -@cindex shift-selection-mode -Jump to the previous/next item in the current list, but only if -@code{org-support-shift-select} is off. If not, you can still use paragraph -jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite -similar effect. -@kindex M-S-@key{up} -@kindex M-S-@key{down} -@item M-S-@key{up} -@itemx M-S-@key{down} -Move the item including subitems up/down (swap with previous/next item -of same indentation). If the list is ordered, renumbering is -automatic. -@kindex M-S-@key{left} -@kindex M-S-@key{right} -@item M-S-@key{left} -@itemx M-S-@key{right} -Decrease/increase the indentation of the item, including subitems. -Initially, the item tree is selected based on current indentation. -When these commands are executed several times in direct succession, -the initially selected region is used, even if the new indentation -would imply a different hierarchy. To use the new hierarchy, break -the command chain with a cursor motion or so. -@kindex C-c C-c -@item C-c C-c -If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the -state of the checkbox. If not, this command makes sure that all the -items on this list level use the same bullet. Furthermore, if this is -an ordered list, make sure the numbering is OK. -@kindex C-c - -@item C-c - -Cycle the entire list level through the different itemize/enumerate bullets -(@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}). With a numeric prefix -argument N, select the Nth bullet from this list. If there is an active -region when calling this, all lines will be converted to list items. If the -first line already was a list item, any item markers will be removed from the -list. Finally, even without an active region, a normal line will be -converted into a list item. -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left}/@key{right} -This command also cycles bullet styles when the cursor in on the bullet or -anywhere in an item line, details depending on -@code{org-support-shift-select}. -@end table - -@node Drawers, Footnotes, Plain lists, Document Structure -@section Drawers -@cindex drawers -@cindex visibility cycling, drawers - -Sometimes you want to keep information associated with an entry, but you -normally don't want to see it. For this, Org mode has @emph{drawers}. -Drawers need to be configured with the variable -@code{org-drawers}@footnote{You can define drawers on a per-file basis -with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers -look like this: - -@example -** This is a headline - Still outside the drawer - :DRAWERNAME: - This is inside the drawer. - :END: - After the drawer. -@end example - -Visibility cycling (@pxref{Visibility cycling}) on the headline will -hide and show the entry, but keep the drawer collapsed to a single line. -In order to look inside the drawer, you need to move the cursor to the -drawer line and press @key{TAB} there. Org mode uses a drawer for -storing properties (@pxref{Properties and Columns}), and another one for -storing clock times (@pxref{Clocking work time}). - -@node Footnotes, Orgstruct mode, Drawers, Document Structure -@section Footnotes -@cindex footnotes - -Org-mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org-mode's footnotes are designed for work on a -larger document, not only for one-off documents like emails. The basic -syntax is similar to the one used by @file{footnote.el}, i.e. a footnote is -defined in a paragraph that is started by a footnote marker in square -brackets in column 0, no indentation allowed. If you need a paragraph break -inside a footnote, use the LaTeX idiom @samp{\par}. The footnote reference -is simply the marker in square brackets, inside text. For example: - -@example -The Org homepage[fn:1] now looks a lot better than it used to. -... -[fn:1] The link is: http://orgmode.org -@end example - -Org-mode extends the number-based syntax to @emph{named} footnotes and -optional inline definition. Using plain numbers as markers (as -@file{footnote.el} does) is supported for backward compatibility, but not -encouraged because of possible conflicts with LaTeX snippets @pxref{Embedded -LaTeX}. Here are the valid references: - -@table @code -@item [1] -A plain numeric footnote marker. -@item [fn:name] -A named footnote reference, where @code{name} is a unique label word, or, for -simplicity of automatic creation, a number. -@item [fn:: This is the inline definition of this footnote] -A LaTeX-like anonymous footnote where the definition is given directly at the -reference point. -@item [fn:name: a definition] -An inline definition of a footnote, which also specifies a name for the note. -Since Org allows multiple references to the same note, you can then use -@code{[fn:name]} to create additional references. -@end table - -Footnote labels can be created automatically, or you create names yourself. -This is handled by the variable @code{org-footnote-auto-label} and its -corresponding @code{#+STARTUP} keywords, see the docstring of that variable -for details. - -@noindent The following command handles footnotes: - -@table @kbd -@kindex C-c C-x f -@item C-c C-x f -The footnote action command. - -When the cursor is on a footnote reference, jump to the definition. When it -is at a definition, jump to the (first) reference. - -Otherwise, create a new footnote. Depending on the variable -@code{org-footnote-define-inline}@footnote{The corresponding in-buffer -setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the -definition will be placed right into the text as part of the reference, or -separately into the location determined by the variable -@code{org-footnote-section}. - -When this command is called with a prefix argument, a menu of additional -options is offered: -@example -s @r{Sort the footnote definitions by reference sequence. During editing,} - @r{Org makes no effort to sort footnote definitions into a particular} - @r{sequence. If you want them sorted, use this command, which will} - @r{also move entries according to @code{org-footnote-section}.} -n @r{Normalize the footnotes by collecting all definitions (including} - @r{inline definitions) into a special section, and then numbering them} - @r{in sequence. The references will then also be numbers. This is} - @r{meant to be the final step before finishing a document (e.g. sending} - @r{off an email). The exporters do this automatically, and so could} - @r{something like @code{message-send-hook}.} -d @r{Delete the footnote at point, and all definitions of and references} - @r{to it.} -@end example -@kindex C-c C-c -@item C-c C-c -If the cursor is on a footnote reference, jump to the definition. If it is a -the definition, jump back to the reference. When called at a footnote -location with a prefix argument, offer the same menu as @kbd{C-c C-x f}. -@kindex C-c C-o -@kindex mouse-1 -@kindex mouse-2 -@item C-c C-c @r{or} mouse-1/2 -Footnote labels are also links to the corresponding definition/reference, and -you can use the usual commands to follow these links. -@end table - -@node Orgstruct mode, , Footnotes, Document Structure -@section The Orgstruct minor mode -@cindex Orgstruct mode -@cindex minor mode for structure editing - -If you like the intuitive way the Org mode structure editing and list -formatting works, you might want to use these commands in other modes -like Text mode or Mail mode as well. The minor mode Orgstruct mode -makes this possible. You can always toggle the mode with @kbd{M-x -orgstruct-mode}. To turn it on by default, for example in Mail mode, -use - -@lisp -(add-hook 'mail-mode-hook 'turn-on-orgstruct) -@end lisp - -When this mode is active and the cursor is on a line that looks to -Org like a headline of the first line of a list item, most -structure editing commands will work, even if the same keys normally -have different functionality in the major mode you are using. If the -cursor is not in one of those special lines, Orgstruct mode lurks -silently in the shadow. - -@node Tables, Hyperlinks, Document Structure, Top -@chapter Tables -@cindex tables -@cindex editing tables - -Org comes with a fast and intuitive table editor. Spreadsheet-like -calculations are supported in connection with the Emacs @file{calc} -package -@ifinfo -(@pxref{Top,Calc,,Calc,Gnu Emacs Calculator Manual}). -@end ifinfo -@ifnotinfo -(see the Emacs Calculator manual for more information about the Emacs -calculator). -@end ifnotinfo - -@menu -* Built-in table editor:: Simple tables -* Narrow columns:: Stop wasting space in tables -* Column groups:: Grouping to trigger vertical lines -* Orgtbl mode:: The table editor as minor mode -* The spreadsheet:: The table editor has spreadsheet capabilities -* Org Plot:: Plotting from org tables -@end menu - -@node Built-in table editor, Narrow columns, Tables, Tables -@section The built-in table editor -@cindex table editor, built-in - -Org makes it easy to format tables in plain ASCII. Any line with -@samp{|} as the first non-whitespace character is considered part of a -table. @samp{|} is also the column separator. A table might look like -this: - -@example -| Name | Phone | Age | -|-------+-------+-----| -| Peter | 1234 | 17 | -| Anna | 4321 | 25 | -@end example - -A table is re-aligned automatically each time you press @key{TAB} or -@key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to -the next field (@key{RET} to the next row) and creates new table rows -at the end of the table or before horizontal lines. The indentation -of the table is set by the first line. Any line starting with -@samp{|-} is considered as a horizontal separator line and will be -expanded on the next re-align to span the whole table width. So, to -create the above table, you would only type - -@example -|Name|Phone|Age| -|- -@end example - -@noindent and then press @key{TAB} to align the table and start filling in -fields. Even faster would be to type @code{|Name|Phone|Age} followed by -@kbd{C-c @key{RET}}. - -When typing text into a field, Org treats @key{DEL}, -@key{Backspace}, and all character keys in a special way, so that -inserting and deleting avoids shifting other fields. Also, when -typing @emph{immediately after the cursor was moved into a new field -with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or @kbd{@key{RET}}}, the -field is automatically made blank. If this behavior is too -unpredictable for you, configure the variables -@code{org-enable-table-editor} and @code{org-table-auto-blank-field}. - -@table @kbd -@tsubheading{Creation and conversion} -@kindex C-c | -@item C-c | -Convert the active region to table. If every line contains at least one -TAB character, the function assumes that the material is tab separated. -If every line contains a comma, comma-separated values (CSV) are assumed. -If not, lines are split at whitespace into fields. You can use a prefix -argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u -C-u} forces TAB, and a numeric argument N indicates that at least N -consecutive spaces, or alternatively a TAB will be the separator. -@* -If there is no active region, this command creates an empty Org -table. But it's easier just to start typing, like -@kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}. - -@tsubheading{Re-aligning and field motion} -@kindex C-c C-c -@item C-c C-c -Re-align the table without moving the cursor. -@c -@kindex @key{TAB} -@item @key{TAB} -Re-align the table, move to the next field. Creates a new row if -necessary. -@c -@kindex S-@key{TAB} -@item S-@key{TAB} -Re-align, move to previous field. -@c -@kindex @key{RET} -@item @key{RET} -Re-align the table and move down to next row. Creates a new row if -necessary. At the beginning or end of a line, @key{RET} still does -NEWLINE, so it can be used to split a table. - -@tsubheading{Column and row editing} -@kindex M-@key{left} -@kindex M-@key{right} -@item M-@key{left} -@itemx M-@key{right} -Move the current column left/right. -@c -@kindex M-S-@key{left} -@item M-S-@key{left} -Kill the current column. -@c -@kindex M-S-@key{right} -@item M-S-@key{right} -Insert a new column to the left of the cursor position. -@c -@kindex M-@key{up} -@kindex M-@key{down} -@item M-@key{up} -@itemx M-@key{down} -Move the current row up/down. -@c -@kindex M-S-@key{up} -@item M-S-@key{up} -Kill the current row or horizontal line. -@c -@kindex M-S-@key{down} -@item M-S-@key{down} -Insert a new row above the current row. With a prefix argument, the line is -created below the current one. -@c -@kindex C-c - -@item C-c - -Insert a horizontal line below current row. With a prefix argument, the line -is created above the current line. -@c -@kindex C-c @key{RET} -@item C-c @key{RET} -Insert a horizontal line below current row, and move the cursor into the row -below that line. -@c -@kindex C-c ^ -@item C-c ^ -Sort the table lines in the region. The position of point indicates the -column to be used for sorting, and the range of lines is the range -between the nearest horizontal separator lines, or the entire table. If -point is before the first column, you will be prompted for the sorting -column. If there is an active region, the mark specifies the first line -and the sorting column, while point should be in the last line to be -included into the sorting. The command prompts for the sorting type -(alphabetically, numerically, or by time). When called with a prefix -argument, alphabetic sorting will be case-sensitive. - -@tsubheading{Regions} -@kindex C-c C-x M-w -@item C-c C-x M-w -Copy a rectangular region from a table to a special clipboard. Point -and mark determine edge fields of the rectangle. The process ignores -horizontal separator lines. -@c -@kindex C-c C-x C-w -@item C-c C-x C-w -Copy a rectangular region from a table to a special clipboard, and -blank all fields in the rectangle. So this is the ``cut'' operation. -@c -@kindex C-c C-x C-y -@item C-c C-x C-y -Paste a rectangular region into a table. -The upper left corner ends up in the current field. All involved fields -will be overwritten. If the rectangle does not fit into the present table, -the table is enlarged as needed. The process ignores horizontal separator -lines. -@c -@kindex M-@key{RET} -@itemx M-@kbd{RET} -Wrap several fields in a column like a paragraph. If there is an active -region, and both point and mark are in the same column, the text in the -column is wrapped to minimum width for the given number of lines. A numeric -prefix argument may be used to change the number of desired lines. If there -is no region, the current field is split at the cursor position and the text -fragment to the right of the cursor is prepended to the field one line -down. If there is no region, but you specify a prefix argument, the current -field is made blank, and the content is appended to the field above. - -@tsubheading{Calculations} -@cindex formula, in tables -@cindex calculations, in tables -@cindex region, active -@cindex active region -@cindex Transient mark mode -@kindex C-c + -@item C-c + -Sum the numbers in the current column, or in the rectangle defined by -the active region. The result is shown in the echo area and can -be inserted with @kbd{C-y}. -@c -@kindex S-@key{RET} -@item S-@key{RET} -When current field is empty, copy from first non-empty field above. When not -empty, copy current field down to next row and move cursor along with it. -Depending on the variable @code{org-table-copy-increment}, integer field -values will be incremented during copy. Integers that are too large will not -be incremented. Also, a @code{0} prefix argument temporarily disables the -increment. This key is also used by CUA mode (@pxref{Cooperation}). - -@tsubheading{Miscellaneous} -@kindex C-c ` -@item C-c ` -Edit the current field in a separate window. This is useful for fields -that are not fully visible (@pxref{Narrow columns}). When called with a -@kbd{C-u} prefix, just make the full field visible, so that it can be -edited in place. -@c -@item M-x org-table-import -Import a file as a table. The table should be TAB- or whitespace -separated. Useful, for example, to import a spreadsheet table or data -from a database, because these programs generally can write -TAB-separated text files. This command works by inserting the file into -the buffer and then converting the region to a table. Any prefix -argument is passed on to the converter, which uses it to determine the -separator. -@item C-c | -Tables can also be imported by pasting tabular text into the Org -buffer, selecting the pasted text with @kbd{C-x C-x} and then using the -@kbd{C-c |} command (see above under @i{Creation and conversion}). -@c -@item M-x org-table-export -Export the table, by default as a TAB-separated file. Useful for data -exchange with, for example, spreadsheet or database programs. The format -used to export the file can be configured in the variable -@code{org-table-export-default-format}. You may also use properties -@code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file -name and the format for table export in a subtree. Org supports quite -general formats for exported tables. The exporter format is the same as the -format used by Orgtbl radio tables, see @ref{Translator functions} for a -detailed description. -@end table - -If you don't like the automatic table editor because it gets in your -way on lines which you would like to start with @samp{|}, you can turn -it off with - -@lisp -(setq org-enable-table-editor nil) -@end lisp - -@noindent Then the only table command that still works is -@kbd{C-c C-c} to do a manual re-align. - -@node Narrow columns, Column groups, Built-in table editor, Tables -@section Narrow columns -@cindex narrow columns in tables - -The width of columns is automatically determined by the table editor. -Sometimes a single field or a few fields need to carry more text, -leading to inconveniently wide columns. To limit@footnote{This feature -does not work on XEmacs.} the width of a column, one field anywhere in -the column may contain just the string @samp{} where @samp{N} is an -integer specifying the width of the column in characters. The next -re-align will then set the width of this column to no more than this -value. - -@example -@group -|---+------------------------------| |---+--------| -| | | | | <6> | -| 1 | one | | 1 | one | -| 2 | two | ----\ | 2 | two | -| 3 | This is a long chunk of text | ----/ | 3 | This=> | -| 4 | four | | 4 | four | -|---+------------------------------| |---+--------| -@end group -@end example - -@noindent -Fields that are wider become clipped and end in the string @samp{=>}. -Note that the full text is still in the buffer, it is only invisible. -To see the full text, hold the mouse over the field - a tool-tip window -will show the full content. To edit such a field, use the command -@kbd{C-c `} (that is @kbd{C-c} followed by the backquote). This will -open a new window with the full field. Edit it and finish with @kbd{C-c -C-c}. - -When visiting a file containing a table with narrowed columns, the -necessary character hiding has not yet happened, and the table needs to -be aligned before it looks nice. Setting the option -@code{org-startup-align-all-tables} will realign all tables in a file -upon visiting, but also slow down startup. You can also set this option -on a per-file basis with: - -@example -#+STARTUP: align -#+STARTUP: noalign -@end example - -@node Column groups, Orgtbl mode, Narrow columns, Tables -@section Column groups -@cindex grouping columns in tables - -When Org exports tables, it does so by default without vertical -lines because that is visually more satisfying in general. Occasionally -however, vertical lines can be useful to structure a table into groups -of columns, much like horizontal lines can do for groups of rows. In -order to specify column groups, you can use a special row where the -first field contains only @samp{/}. The further fields can either -contain @samp{<} to indicate that this column should start a group, -@samp{>} to indicate the end of a column, or @samp{<>} to make a column -a group of its own. Boundaries between column groups will upon export be -marked with vertical lines. Here is an example: - -@example -| | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | -|---+----+-----+-----+-----+---------+------------| -| / | <> | < | | > | < | > | -| # | 1 | 1 | 1 | 1 | 1 | 1 | -| # | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | -| # | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | -|---+----+-----+-----+-----+---------+------------| -#+TBLFM: $3=$2^2::$4=$2^3::$5=$2^4::$6=sqrt($2)::$7=sqrt(sqrt(($2))) -@end example - -It is also sufficient to just insert the column group starters after -every vertical line you'd like to have: - -@example -| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | -|----+-----+-----+-----+---------+------------| -| / | < | | | < | | -@end example - -@node Orgtbl mode, The spreadsheet, Column groups, Tables -@section The Orgtbl minor mode -@cindex Orgtbl mode -@cindex minor mode for tables - -If you like the intuitive way the Org table editor works, you -might also want to use it in other modes like Text mode or Mail mode. -The minor mode Orgtbl mode makes this possible. You can always toggle -the mode with @kbd{M-x orgtbl-mode}. To turn it on by default, for -example in mail mode, use - -@lisp -(add-hook 'mail-mode-hook 'turn-on-orgtbl) -@end lisp - -Furthermore, with some special setup, it is possible to maintain tables -in arbitrary syntax with Orgtbl mode. For example, it is possible to -construct La@TeX{} tables with the underlying ease and power of -Orgtbl mode, including spreadsheet capabilities. For details, see -@ref{Tables in arbitrary syntax}. - -@node The spreadsheet, Org Plot, Orgtbl mode, Tables -@section The spreadsheet -@cindex calculations, in tables -@cindex spreadsheet capabilities -@cindex @file{calc} package - -The table editor makes use of the Emacs @file{calc} package to implement -spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to -derive fields from other fields. While fully featured, Org's -implementation is not identical to other spreadsheets. For example, -Org knows the concept of a @emph{column formula} that will be -applied to all non-header fields in a column without having to copy the -formula to each relevant field. - -@menu -* References:: How to refer to another field or range -* Formula syntax for Calc:: Using Calc to compute stuff -* Formula syntax for Lisp:: Writing formulas in Emacs Lisp -* Field formulas:: Formulas valid for a single field -* Column formulas:: Formulas valid for an entire column -* Editing and debugging formulas:: Fixing formulas -* Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc -@end menu - -@node References, Formula syntax for Calc, The spreadsheet, The spreadsheet -@subsection References -@cindex references - -To compute fields in the table from other fields, formulas must -reference other fields or ranges. In Org, fields can be referenced -by name, by absolute coordinates, and by relative coordinates. To find -out what the coordinates of a field are, press @kbd{C-c ?} in that -field, or press @kbd{C-c @}} to toggle the display of a grid. - -@subsubheading Field references -@cindex field references -@cindex references, to fields - -Formulas can reference the value of another field in two ways. Like in -any other spreadsheet, you may reference fields with a letter/number -combination like @code{B3}, meaning the 2nd field in the 3rd row. -@c Such references are always fixed to that field, they don't change -@c when you copy and paste a formula to a different field. So -@c Org's @code{B3} behaves like @code{$B$3} in other spreadsheets. - -@noindent -Org also uses another, more general operator that looks like this: -@example -@@row$column -@end example - -@noindent -Column references can be absolute like @samp{1}, @samp{2},...@samp{N}, -or relative to the current column like @samp{+1} or @samp{-2}. - -The row specification only counts data lines and ignores horizontal -separator lines (hlines). You can use absolute row numbers -@samp{1}...@samp{N}, and row numbers relative to the current row like -@samp{+3} or @samp{-1}. Or specify the row relative to one of the -hlines: @samp{I} refers to the first hline@footnote{Note that only -hlines are counted that @emph{separate} table lines. If the table -starts with a hline above the header, it does not count.}, @samp{II} to -the second etc. @samp{-I} refers to the first such line above the -current line, @samp{+I} to the first such line below the current line. -You can also write @samp{III+2} which is the second data line after the -third hline in the table. Relative row numbers like @samp{-3} will not -cross hlines if the current line is too close to the hline. Instead, -the value directly at the hline is used. - -@samp{0} refers to the current row and column. Also, if you omit -either the column or the row part of the reference, the current -row/column is implied. - -Org's references with @emph{unsigned} numbers are fixed references -in the sense that if you use the same reference in the formula for two -different fields, the same field will be referenced each time. -Org's references with @emph{signed} numbers are floating -references because the same reference operator can reference different -fields depending on the field being calculated by the formula. - -As a special case references like @samp{$LR5} and @samp{$LR12} can be used to -refer in a stable way to the 5th and 12th field in the last row of the -table. - -Here are a few examples: - -@example -@@2$3 @r{2nd row, 3rd column} -C2 @r{same as previous} -$5 @r{column 5 in the current row} -E& @r{same as previous} -@@2 @r{current column, row 2} -@@-1$-3 @r{the field one row up, three columns to the left} -@@-I$2 @r{field just under hline above current row, column 2} -@end example - -@subsubheading Range references -@cindex range references -@cindex references, to ranges - -You may reference a rectangular range of fields by specifying two field -references connected by two dots @samp{..}. If both fields are in the -current row, you may simply use @samp{$2..$7}, but if at least one field -is in a different row, you need to use the general @code{@@row$column} -format at least for the first field (i.e the reference must start with -@samp{@@} in order to be interpreted correctly). Examples: - -@example -$1..$3 @r{First three fields in the current row.} -$P..$Q @r{Range, using column names (see under Advanced)} -@@2$1..@@4$3 @r{6 fields between these two fields.} -A2..C4 @r{Same as above.} -@@-1$-2..@@-1 @r{3 numbers from the column to the left, 2 up to current row} -@end example - -@noindent Range references return a vector of values that can be fed -into Calc vector functions. Empty fields in ranges are normally -suppressed, so that the vector contains only the non-empty fields (but -see the @samp{E} mode switch below). If there are no non-empty fields, -@samp{[0]} is returned to avoid syntax errors in formulas. - -@subsubheading Named references -@cindex named references -@cindex references, named -@cindex name, of column or field -@cindex constants, in calculations - -@samp{$name} is interpreted as the name of a column, parameter or -constant. Constants are defined globally through the variable -@code{org-table-formula-constants}, and locally (for the file) through a -line like - -@example -#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6 -@end example - -@noindent -Also properties (@pxref{Properties and Columns}) can be used as -constants in table formulas: For a property @samp{:Xyz:} use the name -@samp{$PROP_Xyz}, and the property will be searched in the current -outline entry and in the hierarchy above it. If you have the -@file{constants.el} package, it will also be used to resolve constants, -including natural constants like @samp{$h} for Planck's constant, and -units like @samp{$km} for kilometers@footnote{@file{Constant.el} can -supply the values of constants in two different unit systems, @code{SI} -and @code{cgs}. Which one is used depends on the value of the variable -@code{constants-unit-system}. You can use the @code{#+STARTUP} options -@code{constSI} and @code{constcgs} to set this value for the current -buffer.}. Column names and parameters can be specified in special table -lines. These are described below, see @ref{Advanced features}. All -names must start with a letter, and further consist of letters and -numbers. - -@subsubheading Remote references -@cindex remote references -@cindex references, remote -@cindex references, to a different table -@cindex name, of column or field -@cindex constants, in calculations - -You may also reference constants, fields and ranges from a different table, -either in the current file or even in a different file. The syntax is - -@example -remote(NAME-OR-ID,REF) -@end example - -@noindent -where NAME can be the name of a table in the current file as set by a -@code{#+TBLNAME: NAME} line before the table. It can also be the ID of an -entry, even in a different file, and the reference then refers to the first -table in that entry. REF is an absolute field or range reference as -described above, valid in the referenced table. - -@node Formula syntax for Calc, Formula syntax for Lisp, References, The spreadsheet -@subsection Formula syntax for Calc -@cindex formula syntax, Calc -@cindex syntax, of formulas - -A formula can be any algebraic expression understood by the Emacs -@file{Calc} package. @b{Note that @file{calc} has the -non-standard convention that @samp{/} has lower precedence than -@samp{*}, so that @samp{a/b*c} is interpreted as @samp{a/(b*c)}.} Before -evaluation by @code{calc-eval} (@pxref{Calling Calc from -Your Programs,calc-eval,Calling Calc from Your Lisp Programs,Calc,GNU -Emacs Calc Manual}), -@c FIXME: The link to the Calc manual in HTML does not work. -variable substitution takes place according to the rules described above. -@cindex vectors, in table calculations -The range vectors can be directly fed into the Calc vector functions -like @samp{vmean} and @samp{vsum}. - -@cindex format specifier -@cindex mode, for @file{calc} -A formula can contain an optional mode string after a semicolon. This -string consists of flags to influence Calc and other modes during -execution. By default, Org uses the standard Calc modes (precision -12, angular units degrees, fraction and symbolic modes off). The display -format, however, has been changed to @code{(float 5)} to keep tables -compact. The default settings can be configured using the variable -@code{org-calc-default-modes}. - -@example -p20 @r{switch the internal precision to 20 digits} -n3 s3 e2 f4 @r{normal, scientific, engineering, or fixed display format} -D R @r{angle modes: degrees, radians} -F S @r{fraction and symbolic modes} -N @r{interpret all fields as numbers, use 0 for non-numbers} -T @r{force text interpretation} -E @r{keep empty fields in ranges} -@end example - -@noindent -In addition, you may provide a @code{printf} format specifier to -reformat the final result. A few examples: - -@example -$1+$2 @r{Sum of first and second field} -$1+$2;%.2f @r{Same, format result to two decimals} -exp($2)+exp($1) @r{Math functions can be used} -$0;%.1f @r{Reformat current cell to 1 decimal} -($3-32)*5/9 @r{Degrees F -> C conversion} -$c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}} -tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1} -sin($1);Dp3%.1e @r{Same, but use printf specifier for display} -vmean($2..$7) @r{Compute column range mean, using vector function} -vmean($2..$7);EN @r{Same, but treat empty fields as 0} -taylor($3,x=7,2) @r{taylor series of $3, at x=7, second degree} -@end example - -Calc also contains a complete set of logical operations. For example - -@example -if($1<20,teen,string("")) @r{``teen'' if age $1 less than 20, else empty} -@end example - -@node Formula syntax for Lisp, Field formulas, Formula syntax for Calc, The spreadsheet -@subsection Emacs Lisp forms as formulas -@cindex Lisp forms, as table formulas - -It is also possible to write a formula in Emacs Lisp; this can be useful -for string manipulation and control structures, if Calc's -functionality is not enough. If a formula starts with a single quote -followed by an opening parenthesis, then it is evaluated as a lisp form. -The evaluation should return either a string or a number. Just as with -@file{calc} formulas, you can specify modes and a printf format after a -semicolon. With Emacs Lisp forms, you need to be conscious about the way -field references are interpolated into the form. By default, a -reference will be interpolated as a Lisp string (in double quotes) -containing the field. If you provide the @samp{N} mode switch, all -referenced elements will be numbers (non-number fields will be zero) and -interpolated as Lisp numbers, without quotes. If you provide the -@samp{L} flag, all fields will be interpolated literally, without quotes. -I.e., if you want a reference to be interpreted as a string by the Lisp -form, enclose the reference operator itself in double quotes, like -@code{"$3"}. Ranges are inserted as space-separated fields, so you can -embed them in list or vector syntax. A few examples, note how the -@samp{N} mode is used when we do computations in lisp. - -@example -@r{Swap the first two characters of the content of column 1} - '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) -@r{Add columns 1 and 2, equivalent to Calc's @code{$1+$2}} - '(+ $1 $2);N -@r{Compute the sum of columns 1-4, like Calc's @code{vsum($1..$4)}} - '(apply '+ '($1..$4));N -@end example - -@node Field formulas, Column formulas, Formula syntax for Lisp, The spreadsheet -@subsection Field formulas -@cindex field formula -@cindex formula, for individual table field - -To assign a formula to a particular field, type it directly into the -field, preceded by @samp{:=}, for example @samp{:=$1+$2}. When you -press @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in -the field, the formula will be stored as the formula for this field, -evaluated, and the current field replaced with the result. - -Formulas are stored in a special line starting with @samp{#+TBLFM:} -directly below the table. If you typed the equation in the 4th field of -the 3rd data line in the table, the formula will look like -@samp{@@3$4=$1+$2}. When inserting/deleting/swapping column and rows -with the appropriate commands, @i{absolute references} (but not relative -ones) in stored formulas are modified in order to still reference the -same field. Of cause this is not true if you edit the table structure -with normal editing commands - then you must fix the equations yourself. -The left hand side of a formula may also be a named field (@pxref{Advanced -features}), or a last-row reference like @samp{$LR3}. - -Instead of typing an equation into the field, you may also use the -following command - -@table @kbd -@kindex C-u C-c = -@item C-u C-c = -Install a new formula for the current field. The command prompts for a -formula, with default taken from the @samp{#+TBLFM:} line, applies -it to the current field and stores it. -@end table - -@node Column formulas, Editing and debugging formulas, Field formulas, The spreadsheet -@subsection Column formulas -@cindex column formula -@cindex formula, for table column - -Often in a table, the same formula should be used for all fields in a -particular column. Instead of having to copy the formula to all fields -in that column, Org allows to assign a single formula to an entire -column. If the table contains horizontal separator hlines, everything -before the first such line is considered part of the table @emph{header} -and will not be modified by column formulas. - -To assign a formula to a column, type it directly into any field in the -column, preceded by an equal sign, like @samp{=$1+$2}. When you press -@key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the -field, the formula will be stored as the formula for the current column, -evaluated and the current field replaced with the result. If the field -contains only @samp{=}, the previously stored formula for this column is -used. For each column, Org will only remember the most recently -used formula. In the @samp{TBLFM:} line, column formulas will look like -@samp{$4=$1+$2}. - -Instead of typing an equation into the field, you may also use the -following command: - -@table @kbd -@kindex C-c = -@item C-c = -Install a new formula for the current column and replace current field with -the result of the formula. The command prompts for a formula, with default -taken from the @samp{#+TBLFM} line, applies it to the current field and -stores it. With a numeric prefix argument(e.g. @kbd{C-5 C-c =}) the command -will apply it to that many consecutive fields in the current column. -@end table - -@node Editing and debugging formulas, Updating the table, Column formulas, The spreadsheet -@subsection Editing and debugging formulas -@cindex formula editing -@cindex editing, of table formulas - -You can edit individual formulas in the minibuffer or directly in the -field. Org can also prepare a special buffer with all active -formulas of a table. When offering a formula for editing, Org -converts references to the standard format (like @code{B3} or @code{D&}) -if possible. If you prefer to only work with the internal format (like -@code{@@3$2} or @code{$4}), configure the variable -@code{org-table-use-standard-references}. - -@table @kbd -@kindex C-c = -@kindex C-u C-c = -@item C-c = -@itemx C-u C-c = -Edit the formula associated with the current column/field in the -minibuffer. See @ref{Column formulas} and @ref{Field formulas}. -@kindex C-u C-u C-c = -@item C-u C-u C-c = -Re-insert the active formula (either a -field formula, or a column formula) into the current field, so that you -can edit it directly in the field. The advantage over editing in the -minibuffer is that you can use the command @kbd{C-c ?}. -@kindex C-c ? -@item C-c ? -While editing a formula in a table field, highlight the field(s) -referenced by the reference at the cursor position in the formula. -@kindex C-c @} -@item C-c @} -Toggle the display of row and column numbers for a table, using -overlays. These are updated each time the table is aligned, you can -force it with @kbd{C-c C-c}. -@kindex C-c @{ -@item C-c @{ -Toggle the formula debugger on and off. See below. -@kindex C-c ' -@item C-c ' -Edit all formulas for the current table in a special buffer, where the -formulas will be displayed one per line. If the current field has an -active formula, the cursor in the formula editor will mark it. -While inside the special buffer, Org will automatically highlight -any field or range reference at the cursor position. You may edit, -remove and add formulas, and use the following commands: -@table @kbd -@kindex C-c C-c -@kindex C-x C-s -@item C-c C-c -@itemx C-x C-s -Exit the formula editor and store the modified formulas. With @kbd{C-u} -prefix, also apply the new formulas to the entire table. -@kindex C-c C-q -@item C-c C-q -Exit the formula editor without installing changes. -@kindex C-c C-r -@item C-c C-r -Toggle all references in the formula editor between standard (like -@code{B3}) and internal (like @code{@@3$2}). -@kindex @key{TAB} -@item @key{TAB} -Pretty-print or indent lisp formula at point. When in a line containing -a lisp formula, format the formula according to Emacs Lisp rules. -Another @key{TAB} collapses the formula back again. In the open -formula, @key{TAB} re-indents just like in Emacs lisp mode. -@kindex M-@key{TAB} -@item M-@key{TAB} -Complete Lisp symbols, just like in Emacs lisp mode. -@kindex S-@key{up} -@kindex S-@key{down} -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{up}/@key{down}/@key{left}/@key{right} -Shift the reference at point. For example, if the reference is -@code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}. -This also works for relative references, and for hline references. -@kindex M-S-@key{up} -@kindex M-S-@key{down} -@item M-S-@key{up}/@key{down} -Move the test line for column formulas in the Org buffer up and -down. -@kindex M-@key{up} -@kindex M-@key{down} -@item M-@key{up}/@key{down} -Scroll the window displaying the table. -@kindex C-c @} -@item C-c @} -Turn the coordinate grid in the table on and off. -@end table -@end table - -Making a table field blank does not remove the formula associated with -the field, because that is stored in a different line (the @samp{TBLFM} -line) - during the next recalculation the field will be filled again. -To remove a formula from a field, you have to give an empty reply when -prompted for the formula, or to edit the @samp{#+TBLFM} line. - -@kindex C-c C-c -You may edit the @samp{#+TBLFM} directly and re-apply the changed -equations with @kbd{C-c C-c} in that line, or with the normal -recalculation commands in the table. - -@subsubheading Debugging formulas -@cindex formula debugging -@cindex debugging, of table formulas -When the evaluation of a formula leads to an error, the field content -becomes the string @samp{#ERROR}. If you would like see what is going -on during variable substitution and calculation in order to find a bug, -turn on formula debugging in the @code{Tbl} menu and repeat the -calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a -field. Detailed information will be displayed. - -@node Updating the table, Advanced features, Editing and debugging formulas, The spreadsheet -@subsection Updating the table -@cindex recomputing table fields -@cindex updating, table - -Recalculation of a table is normally not automatic, but needs to be -triggered by a command. See @ref{Advanced features} for a way to make -recalculation at least semi-automatically. - -In order to recalculate a line of a table or the entire table, use the -following commands: - -@table @kbd -@kindex C-c * -@item C-c * -Recalculate the current row by first applying the stored column formulas -from left to right, and all field formulas in the current row. -@c -@kindex C-u C-c * -@item C-u C-c * -@kindex C-u C-c C-c -@itemx C-u C-c C-c -Recompute the entire table, line by line. Any lines before the first -hline are left alone, assuming that these are part of the table header. -@c -@kindex C-u C-u C-c * -@kindex C-u C-u C-c C-c -@item C-u C-u C-c * -@itemx C-u C-u C-c C-c -Iterate the table by recomputing it until no further changes occur. -This may be necessary if some computed fields use the value of other -fields that are computed @i{later} in the calculation sequence. -@end table - -@node Advanced features, , Updating the table, The spreadsheet -@subsection Advanced features - -If you want the recalculation of fields to happen automatically, or if -you want to be able to assign @i{names} to fields and columns, you need -to reserve the first column of the table for special marking characters. -@table @kbd -@kindex C-# -@item C-# -Rotate the calculation mark in first column through the states @samp{}, -@samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region, -change all marks in the region. -@end table - -Here is an example of a table that collects exam results of students and -makes use of these features: - -@example -@group -|---+---------+--------+--------+--------+-------+------| -| | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | -|---+---------+--------+--------+--------+-------+------| -| ! | | P1 | P2 | P3 | Tot | | -| # | Maximum | 10 | 15 | 25 | 50 | 10.0 | -| ^ | | m1 | m2 | m3 | mt | | -|---+---------+--------+--------+--------+-------+------| -| # | Peter | 10 | 8 | 23 | 41 | 8.2 | -| # | Sam | 2 | 4 | 3 | 9 | 1.8 | -|---+---------+--------+--------+--------+-------+------| -| | Average | | | | 29.7 | | -| ^ | | | | | at | | -| $ | max=50 | | | | | | -|---+---------+--------+--------+--------+-------+------| -#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f -@end group -@end example - -@noindent @b{Important}: Please note that for these special tables, -recalculating the table with @kbd{C-u C-c *} will only affect rows that -are marked @samp{#} or @samp{*}, and fields that have a formula assigned -to the field itself. The column formulas are not applied in rows with -empty first field. - -@cindex marking characters, tables -The marking characters have the following meaning: -@table @samp -@item ! -The fields in this line define names for the columns, so that you may -refer to a column as @samp{$Tot} instead of @samp{$6}. -@item ^ -This row defines names for the fields @emph{above} the row. With such -a definition, any formula in the table may use @samp{$m1} to refer to -the value @samp{10}. Also, if you assign a formula to a names field, it -will be stored as @samp{$name=...}. -@item _ -Similar to @samp{^}, but defines names for the fields in the row -@emph{below}. -@item $ -Fields in this row can define @emph{parameters} for formulas. For -example, if a field in a @samp{$} row contains @samp{max=50}, then -formulas in this table can refer to the value 50 using @samp{$max}. -Parameters work exactly like constants, only that they can be defined on -a per-table basis. -@item # -Fields in this row are automatically recalculated when pressing -@key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row -is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked -lines will be left alone by this command. -@item * -Selects this line for global recalculation with @kbd{C-u C-c *}, but -not for automatic recalculation. Use this when automatic -recalculation slows down editing too much. -@item -Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}. -All lines that should be recalculated should be marked with @samp{#} -or @samp{*}. -@item / -Do not export this line. Useful for lines that contain the narrowing -@samp{} markers. -@end table - -Finally, just to whet your appetite on what can be done with the -fantastic @file{calc} package, here is a table that computes the Taylor -series of degree @code{n} at location @code{x} for a couple of -functions. - -@example -@group -|---+-------------+---+-----+--------------------------------------| -| | Func | n | x | Result | -|---+-------------+---+-----+--------------------------------------| -| # | exp(x) | 1 | x | 1 + x | -| # | exp(x) | 2 | x | 1 + x + x^2 / 2 | -| # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | -| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | -| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | -| * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | -|---+-------------+---+-----+--------------------------------------| -#+TBLFM: $5=taylor($2,$4,$3);n3 -@end group -@end example - -@page -@node Org Plot, , The spreadsheet, Tables -@section Org Plot -@cindex graph, in tables -@cindex plot tables using gnuplot - -Org Plot can produce 2D and 3D graphs of information stored in org tables -using @file{Gnuplot} @uref{http://www.gnuplot.info/} and @file{gnuplot-mode} -@uref{http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html}. To see -this in action ensure that you have both Gnuplot and Gnuplot-mode installed -on your system, then call @code{org-plot/gnuplot} on the following table. - -@example -@group -#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" -| Sede | Max cites | H-index | -|-----------+-----------+---------| -| Chile | 257.72 | 21.39 | -| Leeds | 165.77 | 19.68 | -| Sao Paolo | 71.00 | 11.50 | -| Stockholm | 134.19 | 14.33 | -| Morelia | 257.56 | 17.67 | -@end group -@end example - -Notice that Org Plot is smart enough to apply the tables headers as labels. -Further control over the labels, type, content, and appearance of plots can -be exercised through the @code{#+Plot:} lines preceding a table. See below -for a complete list of Org plot options. For more information and examples -see the org-plot tutorial at -@uref{http://orgmode.org/worg/org-tutorials/org-plot.php}. - -@subsubheading Plot Options - -@table @code -@item set -Specify any @file{gnuplot} option to be set when graphing. - -@item title -Specify the title of the plot. - -@item ind -Specify which column of the table to use as the @code{x} axis. - -@item deps -Specify the columns to graph as a lisp style list, surrounded by parenthesis -and separated by spaces for example @code{dep:(3 4)} to graph the third and -fourth columns (defaults to graphing all other columns aside from the ind -column). - -@item type -Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}. - -@item with -Specify a @code{with} option to be inserted for every col being plotted -(e.g. @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...). -Defaults to @code{lines}. - -@item file -If you want to plot to a file specify the @code{"path/to/desired/output-file"}. - -@item labels -List of labels to be used for the deps (defaults to column headers if they -exist). - -@item line -Specify an entire line to be inserted in the gnuplot script. - -@item map -When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a -flat mapping rather than a @code{3d} slope. - -@item timefmt -Specify format of org-mode timestamps as they will be parsed by gnuplot. -Defaults to @samp{%Y-%m-%d-%H:%M:%S}. - -@item script -If you want total control you can specify a script file (place the file name -between double quotes) which will be used to plot. Before plotting, every -instance of @code{$datafile} in the specified script will be replaced with -the path to the generated data file. Note even if you set this option you -may still want to specify the plot type, as that can impact the content of -the data file. -@end table - -@node Hyperlinks, TODO Items, Tables, Top -@chapter Hyperlinks -@cindex hyperlinks - -Like HTML, Org provides links inside a file, external links to -other files, Usenet articles, emails, and much more. - -@menu -* Link format:: How links in Org are formatted -* Internal links:: Links to other places in the current file -* External links:: URL-like links to the world -* Handling links:: Creating, inserting and following -* Using links outside Org:: Linking from my C source code? -* Link abbreviations:: Shortcuts for writing complex links -* Search options:: Linking to a specific location -* Custom searches:: When the default search is not enough -@end menu - -@node Link format, Internal links, Hyperlinks, Hyperlinks -@section Link format -@cindex link format -@cindex format, of links - -Org will recognize plain URL-like links and activate them as -clickable links. The general link format, however, looks like this: - -@example -[[link][description]] @r{or alternatively} [[link]] -@end example - -Once a link in the buffer is complete (all brackets present), Org -will change the display so that @samp{description} is displayed instead -of @samp{[[link][description]]} and @samp{link} is displayed instead of -@samp{[[link]]}. Links will be highlighted in the face @code{org-link}, -which by default is an underlined face. You can directly edit the -visible part of a link. Note that this can be either the @samp{link} -part (if there is no description) or the @samp{description} part. To -edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the -cursor on the link. - -If you place the cursor at the beginning or just behind the end of the -displayed text and press @key{BACKSPACE}, you will remove the -(invisible) bracket at that location. This makes the link incomplete -and the internals are again displayed as plain text. Inserting the -missing bracket hides the link internals again. To show the -internal structure of all links, use the menu entry -@code{Org->Hyperlinks->Literal links}. - -@node Internal links, External links, Link format, Hyperlinks -@section Internal links -@cindex internal links -@cindex links, internal -@cindex targets, for links - -If the link does not look like a URL, it is considered to be internal in -the current file. Links such as @samp{[[My Target]]} or @samp{[[My -Target][Find my target]]} lead to a text search in the current file. -The link can be followed with @kbd{C-c C-o} when the cursor is on the -link, or with a mouse click (@pxref{Handling links}). The preferred -match for such a link is a dedicated target: the same string in double -angular brackets. Targets may be located anywhere; sometimes it is -convenient to put them into a comment line. For example - -@example -# <> -@end example - -@noindent In HTML export (@pxref{HTML export}), such targets will become -named anchors for direct access through @samp{http} links@footnote{Note that -text before the first headline is usually not exported, so the first such -target should be after the first headline, or in the line directly before the -first headline.}. - -If no dedicated target exists, Org will search for the words in the -link. In the above example the search would be for @samp{my target}. -Links starting with a star like @samp{*My Target} restrict the search to -headlines. When searching, Org mode will first try an exact match, but -then move on to more and more lenient searches. For example, the link -@samp{[[*My Targets]]} will find any of the following: - -@example -** My targets -** TODO my targets are bright -** my 20 targets are -@end example - -To insert a link targeting a headline, in-buffer completion can be used. -Just type a star followed by a few optional letters into the buffer and -press @kbd{M-@key{TAB}}. All headlines in the current buffer will be -offered as completions. @xref{Handling links}, for more commands -creating links. - -Following a link pushes a mark onto Org's own mark ring. You can -return to the previous position with @kbd{C-c &}. Using this command -several times in direct succession goes back to positions recorded -earlier. - -@menu -* Radio targets:: Make targets trigger links in plain text -@end menu - -@node Radio targets, , Internal links, Internal links -@subsection Radio targets -@cindex radio targets -@cindex targets, radio -@cindex links, radio targets - -Org can automatically turn any occurrences of certain target names -in normal text into a link. So without explicitly creating a link, the -text connects to the target radioing its position. Radio targets are -enclosed by triple angular brackets. For example, a target @samp{<<>>} causes each occurrence of @samp{my target} in normal text to -become activated as a link. The Org file is scanned automatically -for radio targets only when the file is first loaded into Emacs. To -update the target list during editing, press @kbd{C-c C-c} with the -cursor on or at a target. - -@node External links, Handling links, Internal links, Hyperlinks -@section External links -@cindex links, external -@cindex external links -@cindex links, external -@cindex Gnus links -@cindex BBDB links -@cindex IRC links -@cindex URL links -@cindex file links -@cindex VM links -@cindex RMAIL links -@cindex WANDERLUST links -@cindex MH-E links -@cindex USENET links -@cindex SHELL links -@cindex Info links -@cindex elisp links - -Org supports links to files, websites, Usenet and email messages, -BBDB database entries and links to both IRC conversations and their -logs. External links are URL-like locators. They start with a short -identifying string followed by a colon. There can be no space after -the colon. The following list shows examples for each link type. - -@example -http://www.astro.uva.nl/~dominik @r{on the web} -file:/home/dominik/images/jupiter.jpg @r{file, absolute path} -/home/dominik/images/jupiter.jpg @r{same as above} -file:papers/last.pdf @r{file, relative path} -./papers/last.pdf @r{same as above} -file:projects.org @r{another org file} -file:projects.org::some words @r{text search in org file} -file:projects.org::*task title @r{heading search in org file} -id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} -news:comp.emacs @r{Usenet link} -mailto:adent@@galaxy.net @r{Mail link} -vm:folder @r{VM folder link} -vm:folder#id @r{VM message link} -vm://myself@@some.where.org/folder#id @r{VM on remote machine} -wl:folder @r{WANDERLUST folder link} -wl:folder#id @r{WANDERLUST message link} -mhe:folder @r{MH-E folder link} -mhe:folder#id @r{MH-E message link} -rmail:folder @r{RMAIL folder link} -rmail:folder#id @r{RMAIL message link} -gnus:group @r{Gnus group link} -gnus:group#id @r{Gnus article link} -bbdb:R.*Stallman @r{BBDB link (with regexp)} -irc:/irc.com/#emacs/bob @r{IRC link} -shell:ls *.org @r{A shell command} -elisp:org-agenda @r{Interactive elisp command} -elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} -@end example - -A link should be enclosed in double brackets and may contain a -descriptive text to be displayed instead of the URL (@pxref{Link -format}), for example: - -@example -[[http://www.gnu.org/software/emacs/][GNU Emacs]] -@end example - -@noindent -If the description is a file name or URL that points to an image, HTML -export (@pxref{HTML export}) will inline the image as a clickable -button. If there is no description at all and the link points to an -image, -that image will be inlined into the exported HTML file. - -@cindex angular brackets, around links -@cindex plain text external links -Org also finds external links in the normal text and activates them -as links. If spaces must be part of the link (for example in -@samp{bbdb:Richard Stallman}), or if you need to remove ambiguities -about the end of the link, enclose them in angular brackets. - -@node Handling links, Using links outside Org, External links, Hyperlinks -@section Handling links -@cindex links, handling - -Org provides methods to create a link in the correct syntax, to -insert it into an Org file, and to follow the link. - -@table @kbd -@kindex C-c l -@cindex storing links -@item C-c l -Store a link to the current location. This is a @emph{global} command (you -must create the key binding yourself) which can be used in any buffer to -create a link. The link will be stored for later insertion into an Org -buffer (see below). - -For Org files, if there is a @samp{<>} at the cursor, the link points -to the target. Otherwise it points to the current headline, either by text -(unsafe), or, if @file{org-id.el} is loaded and @code{org-link-to-org-use-id} -is set, by ID property. - -For VM, Rmail, Wanderlust, MH-E, Gnus and BBDB buffers, the link will -indicate the current article/entry. For W3 and W3M buffers, the link goes to -the current URL. For IRC links, if you set the variable -@code{org-irc-link-to-logs} to non-nil then @kbd{C-c l} will store a -@samp{file:/} style link to the relevant point in the logs for the current -conversation. Otherwise an @samp{irc:/} style link to the user/channel/server -under the point will be stored. - -For any other files, the link will point to the file, with a search string -(@pxref{Search options}) pointing to the contents of the current line. If -there is an active region, the selected words will form the basis of the -search string. If the automatically created link is not working correctly or -accurately enough, you can write custom functions to select the search string -and to do the search for particular file types - see @ref{Custom searches}. -The key binding @kbd{C-c l} is only a suggestion - see @ref{Installation}. -@c -@kindex C-c C-l -@cindex link completion -@cindex completion, of links -@cindex inserting links -@item C-c C-l -Insert a link. This prompts for a link to be inserted into the buffer. You -can just type a link, using text for an internal link, or one of the link -type prefixes mentioned in the examples above. All links stored during the -current session are part of the history for this prompt, so you can access -them with @key{up} and @key{down} (or @kbd{M-p/n}). Completion, on the other -hand, will help you to insert valid link prefixes like @samp{http:} or -@samp{ftp:}, including the prefixes defined through link abbreviations -(@pxref{Link abbreviations}). The link will be inserted into the -buffer@footnote{After insertion of a stored link, the link will be removed -from the list of stored links. To keep it in the list later use, use a -triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option -@code{org-keep-stored-link-after-insertion}.}, along with a descriptive text. -If some text was selected when this command is called, the selected text -becomes the default description.@* Note that you don't have to use this -command to insert a link. Links in Org are plain text, and you can type -or paste them straight into the buffer. By using this command, the links are -automatically enclosed in double brackets, and you will be asked for the -optional descriptive text. -@c -@c If the link is a @samp{file:} link and -@c the linked file is located in the same directory as the current file or -@c a subdirectory of it, the path of the file will be inserted relative to -@c the current directory. -@c -@kindex C-u C-c C-l -@cindex file name completion -@cindex completion, of file names -@item C-u C-c C-l -When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to -a file will be inserted and you may use file name completion to select -the name of the file. The path to the file is inserted relative to the -directory of the current org file, if the linked file is in the current -directory or in a sub-directory of it, or if the path is written relative -to the current directory using @samp{../}. Otherwise an absolute path -is used, if possible with @samp{~/} for your home directory. You can -force an absolute path with two @kbd{C-u} prefixes. -@c -@item C-c C-l @r{(with cursor on existing link)} -When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the -link and description parts of the link. -@c -@cindex following links -@kindex C-c C-o -@kindex RET -@item C-c C-o -Open link at point. This will launch a web browser for URLs (using -@command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for -the corresponding links, and execute the command in a shell link. When the -cursor is on an internal link, this commands runs the corresponding search. -When the cursor is on a TAG list in a headline, it creates the corresponding -TAGS view. If the cursor is on a time stamp, it compiles the agenda for that -date. Furthermore, it will visit text and remote files in @samp{file:} links -with Emacs and select a suitable application for local non-text files. -Classification of files is based on file extension only. See option -@code{org-file-apps}. If you want to override the default application and -visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid -opening in Emacs, use a @kbd{C-u C-u} prefix. -@c -@kindex mouse-2 -@kindex mouse-1 -@item mouse-2 -@itemx mouse-1 -On links, @kbd{mouse-2} will open the link just as @kbd{C-c C-o} -would. Under Emacs 22, also @kbd{mouse-1} will follow a link. -@c -@kindex mouse-3 -@item mouse-3 -Like @kbd{mouse-2}, but force file links to be opened with Emacs, and -internal links to be displayed in another window@footnote{See the -variable @code{org-display-internal-link-with-indirect-buffer}}. -@c -@cindex mark ring -@kindex C-c % -@item C-c % -Push the current position onto the mark ring, to be able to return -easily. Commands following an internal link do this automatically. -@c -@cindex links, returning to -@kindex C-c & -@item C-c & -Jump back to a recorded position. A position is recorded by the -commands following internal links, and by @kbd{C-c %}. Using this -command several times in direct succession moves through a ring of -previously recorded positions. -@c -@kindex C-c C-x C-n -@kindex C-c C-x C-p -@cindex links, finding next/previous -@item C-c C-x C-n -@itemx C-c C-x C-p -Move forward/backward to the next link in the buffer. At the limit of -the buffer, the search fails once, and then wraps around. The key -bindings for this are really too long, you might want to bind this also -to @kbd{C-n} and @kbd{C-p} -@lisp -(add-hook 'org-load-hook - (lambda () - (define-key 'org-mode-map "\C-n" 'org-next-link) - (define-key 'org-mode-map "\C-p" 'org-previous-link))) -@end lisp -@end table - -@node Using links outside Org, Link abbreviations, Handling links, Hyperlinks -@section Using links outside Org - -You can insert and follow links that have Org syntax not only in -Org, but in any Emacs buffer. For this, you should create two -global commands, like this (please select suitable global keys -yourself): - -@lisp -(global-set-key "\C-c L" 'org-insert-link-global) -(global-set-key "\C-c o" 'org-open-at-point-global) -@end lisp - -@node Link abbreviations, Search options, Using links outside Org, Hyperlinks -@section Link abbreviations -@cindex link abbreviations -@cindex abbreviation, links - -Long URLs can be cumbersome to type, and often many similar links are -needed in a document. For this you can use link abbreviations. An -abbreviated link looks like this - -@example -[[linkword:tag][description]] -@end example - -@noindent -where the tag is optional. Such abbreviations are resolved according to -the information in the variable @code{org-link-abbrev-alist} that -relates the linkwords to replacement text. Here is an example: - -@lisp -@group -(setq org-link-abbrev-alist - '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("google" . "http://www.google.com/search?q=") - ("ads" . "http://adsabs.harvard.edu/cgi-bin/ - nph-abs_connect?author=%s&db_key=AST"))) -@end group -@end lisp - -If the replacement text contains the string @samp{%s}, it will be -replaced with the tag. Otherwise the tag will be appended to the string -in order to create the link. You may also specify a function that will -be called with the tag as the only argument to create the link. - -With the above setting, you could link to a specific bug with -@code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with -@code{[[google:OrgMode]]} and find out what the Org author is -doing besides Emacs hacking with @code{[[ads:Dominik,C]]}. - -If you need special abbreviations just for a single Org buffer, you -can define them in the file with - -@example -#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id= -#+LINK: google http://www.google.com/search?q=%s -@end example - -@noindent -In-buffer completion @pxref{Completion} can be used after @samp{[} to -complete link abbreviations. - -@node Search options, Custom searches, Link abbreviations, Hyperlinks -@section Search options in file links -@cindex search option in file links -@cindex file links, searching - -File links can contain additional information to make Emacs jump to a -particular location in the file when following a link. This can be a -line number or a search option after a double@footnote{For backward -compatibility, line numbers can also follow a single colon.} colon. For -example, when the command @kbd{C-c l} creates a link (@pxref{Handling -links}) to a file, it encodes the words in the current line as a search -string that can be used to find this line back later when following the -link with @kbd{C-c C-o}. - -Here is the syntax of the different ways to attach a search to a file -link, together with an explanation: - -@example -[[file:~/code/main.c::255]] -[[file:~/xx.org::My Target]] -[[file:~/xx.org::*My Target]] -[[file:~/xx.org::/regexp/]] -@end example - -@table @code -@item 255 -Jump to line 255. -@item My Target -Search for a link target @samp{<>}, or do a text search for -@samp{my target}, similar to the search in internal links, see -@ref{Internal links}. In HTML export (@pxref{HTML export}), such a file -link will become an HTML reference to the corresponding named anchor in -the linked file. -@item *My Target -In an Org file, restrict search to headlines. -@item /regexp/ -Do a regular expression search for @code{regexp}. This uses the Emacs -command @code{occur} to list all matches in a separate window. If the -target file is in Org mode, @code{org-occur} is used to create a -sparse tree with the matches. -@c If the target file is a directory, -@c @code{grep} will be used to search all files in the directory. -@end table - -As a degenerate case, a file link with an empty file name can be used -to search the current file. For example, @code{[[file:::find me]]} does -a search for @samp{find me} in the current file, just as -@samp{[[find me]]} would. - -@node Custom searches, , Search options, Hyperlinks -@section Custom Searches -@cindex custom search strings -@cindex search strings, custom - -The default mechanism for creating search strings and for doing the -actual search related to a file link may not work correctly in all -cases. For example, BibTeX database files have many entries like -@samp{year="1993"} which would not result in good search strings, -because the only unique identification for a BibTeX entry is the -citation key. - -If you come across such a problem, you can write custom functions to set -the right search string for a particular file type, and to do the search -for the string in the file. Using @code{add-hook}, these functions need -to be added to the hook variables -@code{org-create-file-search-functions} and -@code{org-execute-file-search-functions}. See the docstring for these -variables for more information. Org actually uses this mechanism -for Bib@TeX{} database files, and you can use the corresponding code as -an implementation example. See the file @file{org-bibtex.el}. - -@node TODO Items, Tags, Hyperlinks, Top -@chapter TODO Items -@cindex TODO items - -Org mode does not maintain TODO lists as separate documents@footnote{Of -course, you can make a document that contains only long lists of TODO items, -but this is not required.}. Instead, TODO items are an integral part of the -notes file, because TODO items usually come up while taking notes! With Org -mode, simply mark any entry in a tree as being a TODO item. In this way, -information is not duplicated, and the entire context from which the TODO -item emerged is always present. - -Of course, this technique for managing TODO items scatters them -throughout your notes file. Org mode compensates for this by providing -methods to give you an overview of all the things that you have to do. - -@menu -* TODO basics:: Marking and displaying TODO entries -* TODO extensions:: Workflow and assignments -* Progress logging:: Dates and notes for progress -* Priorities:: Some things are more important than others -* Breaking down tasks:: Splitting a task into manageable pieces -* Checkboxes:: Tick-off lists -@end menu - -@node TODO basics, TODO extensions, TODO Items, TODO Items -@section Basic TODO functionality - -Any headline becomes a TODO item when it starts with the word -@samp{TODO}, for example: - -@example -*** TODO Write letter to Sam Fortune -@end example - -@noindent -The most important commands to work with TODO entries are: - -@table @kbd -@kindex C-c C-t -@cindex cycling, of TODO states -@item C-c C-t -Rotate the TODO state of the current item among - -@example -,-> (unmarked) -> TODO -> DONE --. -'--------------------------------' -@end example - -The same rotation can also be done ``remotely'' from the timeline and -agenda buffers with the @kbd{t} command key (@pxref{Agenda commands}). - -@kindex C-u C-c C-t -@item C-u C-c C-t -Select a specific keyword using completion or (if it has been set up) -the fast selection interface. For the latter, you need to assign keys -to TODO states, see @ref{Per-file keywords} and @ref{Setting tags} for -more information. - -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{right} -@itemx S-@key{left} -Select the following/preceding TODO state, similar to cycling. Useful -mostly if more than two TODO states are possible (@pxref{TODO -extensions}). See also @ref{Conflicts} for a discussion of the interaction -with @code{shift-selection-mode}. -@kindex C-c C-v -@kindex C-c / t -@cindex sparse tree, for TODO -@item C-c C-v -@itemx C-c / t -View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds -the entire buffer, but shows all TODO items and the headings hierarchy -above them. With a prefix argument, search for a specific TODO. You will be -prompted for the keyword, and you can also give a list of keywords like -@code{KWD1|KWD2|...}. With numeric prefix argument N, show the tree for the -Nth keyword in the variable @code{org-todo-keywords}. With two prefix -arguments, find all TODO and DONE entries. -@kindex C-c a t -@item C-c a t -Show the global TODO list. Collects the TODO items from all agenda -files (@pxref{Agenda Views}) into a single buffer. The new buffer will -be in @code{agenda-mode}, which provides commands to examine and -manipulate the TODO entries from the new buffer (@pxref{Agenda -commands}). @xref{Global TODO list}, for more information. -@kindex S-M-@key{RET} -@item S-M-@key{RET} -Insert a new TODO entry below the current one. -@end table - -@noindent -Changing a TODO state can also trigger tag changes. See the docstring of the -option @code{org-todo-state-tags-triggers} for details. - -@node TODO extensions, Progress logging, TODO basics, TODO Items -@section Extended use of TODO keywords -@cindex extended TODO keywords - -By default, marked TODO entries have one of only two states: TODO and -DONE. Org mode allows you to classify TODO items in more complex ways -with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With -special setup, the TODO keyword system can work differently in different -files. - -Note that @i{tags} are another way to classify headlines in general and -TODO items in particular (@pxref{Tags}). - -@menu -* Workflow states:: From TODO to DONE in steps -* TODO types:: I do this, Fred does the rest -* Multiple sets in one file:: Mixing it all, and still finding your way -* Fast access to TODO states:: Single letter selection of a state -* Per-file keywords:: Different files, different requirements -* Faces for TODO keywords:: Highlighting states -* TODO dependencies:: When one task needs to wait for others -@end menu - -@node Workflow states, TODO types, TODO extensions, TODO extensions -@subsection TODO keywords as workflow states -@cindex TODO workflow -@cindex workflow states as TODO keywords - -You can use TODO keywords to indicate different @emph{sequential} states -in the process of working on an item, for example@footnote{Changing -this variable only becomes effective after restarting Org mode in a -buffer.}: - -@lisp -(setq org-todo-keywords - '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED"))) -@end lisp - -The vertical bar separates the TODO keywords (states that @emph{need -action}) from the DONE states (which need @emph{no further action}). If -you don't provide the separator bar, the last state is used as the DONE -state. -@cindex completion, of TODO keywords -With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO -to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED. You may -also use a numeric prefix argument to quickly select a specific state. For -example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY. -Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you -define many keywords, you can use in-buffer completion -(@pxref{Completion}) or even a special one-key selection scheme -(@pxref{Fast access to TODO states}) to insert these words into the -buffer. Changing a TODO state can be logged with a timestamp, see -@ref{Tracking TODO state changes} for more information. - -@node TODO types, Multiple sets in one file, Workflow states, TODO extensions -@subsection TODO keywords as types -@cindex TODO types -@cindex names as TODO keywords -@cindex types as TODO keywords - -The second possibility is to use TODO keywords to indicate different -@emph{types} of action items. For example, you might want to indicate -that items are for ``work'' or ``home''. Or, when you work with several -people on a single project, you might want to assign action items -directly to persons, by using their names as TODO keywords. This would -be set up like this: - -@lisp -(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE"))) -@end lisp - -In this case, different keywords do not indicate a sequence, but rather -different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org mode supports this style by adapting -the workings of the command @kbd{C-c C-t}@footnote{This is also true for the -@kbd{t} command in the timeline and agenda buffers.}. When used several -times in succession, it will still cycle through all names, in order to first -select the right type for a task. But when you return to the item after some -time and execute @kbd{C-c C-t} again, it will switch from any name directly -to DONE. Use prefix arguments or completion to quickly select a specific -name. You can also review the items of a specific TODO type in a sparse tree -by using a numeric prefix to @kbd{C-c C-v}. For example, to see all things -Lucy has to do, you would use @kbd{C-3 C-c C-v}. To collect Lucy's items -from all agenda files into a single buffer, you would use the numeric prefix -argument as well when creating the global TODO list: @kbd{C-3 C-c t}. - -@node Multiple sets in one file, Fast access to TODO states, TODO types, TODO extensions -@subsection Multiple keyword sets in one file -@cindex TODO keyword sets - -Sometimes you may want to use different sets of TODO keywords in -parallel. For example, you may want to have the basic -@code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a -separate state indicating that an item has been canceled (so it is not -DONE, but also does not require action). Your setup would then look -like this: - -@lisp -(setq org-todo-keywords - '((sequence "TODO" "|" "DONE") - (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED") - (sequence "|" "CANCELED"))) -@end lisp - -The keywords should all be different, this helps Org mode to keep track -of which subsequence should be used for a given entry. In this setup, -@kbd{C-c C-t} only operates within a subsequence, so it switches from -@code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to -(nothing) to @code{REPORT}. Therefore you need a mechanism to initially -select the correct sequence. Besides the obvious ways like typing a -keyword or using completion, you may also apply the following commands: - -@table @kbd -@kindex C-S-@key{right} -@kindex C-S-@key{left} -@kindex C-u C-u C-c C-t -@item C-u C-u C-c C-t -@itemx C-S-@key{right} -@itemx C-S-@key{left} -These keys jump from one TODO subset to the next. In the above example, -@kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or -@code{DONE} to @code{REPORT}, and any of the words in the second row to -@code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with -@code{shift-selection-mode} (@pxref{Conflicts}). -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{right} -@itemx S-@key{left} -@kbd{S-@key{}} and @kbd{S-@key{}} and walk through @emph{all} -keywords from all sets, so for example @kbd{S-@key{}} would switch -from @code{DONE} to @code{REPORT} in the example above. See also -@ref{Conflicts} for a discussion of the interaction with -@code{shift-selection-mode}. -@end table - -@node Fast access to TODO states, Per-file keywords, Multiple sets in one file, TODO extensions -@subsection Fast access to TODO states - -If you would like to quickly change an entry to an arbitrary TODO state -instead of cycling through the states, you can set up keys for -single-letter access to the states. This is done by adding the section -key after each keyword, in parenthesis. For example: - -@lisp -(setq org-todo-keywords - '((sequence "TODO(t)" "|" "DONE(d)") - (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)") - (sequence "|" "CANCELED(c)"))) -@end lisp - -If you then press @code{C-c C-t} followed by the selection key, the entry -will be switched to this state. @key{SPC} can be used to remove any TODO -keyword from an entry.@footnote{Check also the variable -@code{org-fast-tag-selection-include-todo}, it allows to change the TODO -state through the tags interface (@pxref{Setting tags}), in case you like to -mingle the two concepts. Note that this means you need to come up with -unique keys across both sets of keywords.} - -@node Per-file keywords, Faces for TODO keywords, Fast access to TODO states, TODO extensions -@subsection Setting up keywords for individual files -@cindex keyword options -@cindex per-file keywords - -It can be very useful to use different aspects of the TODO mechanism in -different files. For file-local settings, you need to add special lines -to the file which set the keywords and interpretation for that file -only. For example, to set one of the two examples discussed above, you -need one of the following lines, starting in column zero anywhere in the -file: - -@example -#+SEQ_TODO: TODO FEEDBACK VERIFY | DONE CANCELED -@end example -or -@example -#+TYP_TODO: Fred Sara Lucy Mike | DONE -@end example - -A setup for using several sets in parallel would be: - -@example -#+SEQ_TODO: TODO | DONE -#+SEQ_TODO: REPORT BUG KNOWNCAUSE | FIXED -#+SEQ_TODO: | CANCELED -@end example - -@cindex completion, of option keywords -@kindex M-@key{TAB} -@noindent To make sure you are using the correct keyword, type -@samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion. - -@cindex DONE, final TODO keyword -Remember that the keywords after the vertical bar (or the last keyword -if no bar is there) must always mean that the item is DONE (although you -may use a different word). After changing one of these lines, use -@kbd{C-c C-c} with the cursor still in the line to make the changes -known to Org mode@footnote{Org mode parses these lines only when -Org mode is activated after visiting a file. @kbd{C-c C-c} with the -cursor in a line starting with @samp{#+} is simply restarting Org mode -for the current buffer.}. - -@node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions -@subsection Faces for TODO keywords -@cindex faces, for TODO keywords - -Org mode highlights TODO keywords with special faces: @code{org-todo} -for keywords indicating that an item still has to be acted upon, and -@code{org-done} for keywords indicating that an item is finished. If -you are using more than 2 different states, you might want to use -special faces for some of them. This can be done using the variable -@code{org-todo-keyword-faces}. For example: - -@lisp -@group -(setq org-todo-keyword-faces - '(("TODO" . org-warning) - ("DEFERRED" . shadow) - ("CANCELED" . (:foreground "blue" :weight bold)))) -@end group -@end lisp - -While using a list with face properties as shown for CANCELED -@emph{should} work, this does not aways seem to be the case. If -necessary, define a special face and use that. - -@node TODO dependencies, , Faces for TODO keywords, TODO extensions -@subsection TODO dependencies -@cindex TODO dependencies -@cindex dependencies, of TODO states - -The structure of Org files (hierarchy and lists) makes it easy to define TODO -dependencies. Usually, a parent TODO task should not be marked DONE until -all subtasks (defined as children tasks) are marked as DONE. And sometimes -there is a logical sequence to a number of (sub)tasks, so that one task -cannot be acted upon before all siblings above it are done. If you customize -the variable @code{org-enforce-todo-dependencies}, Org will block entries -from changing state to DONE while they have children that are not DONE. -Furthermore, if an entry has a property @code{ORDERED}, each of its children -will be blocked until all earlier siblings are marked DONE. Here is an -example: - -@example -* TODO Blocked until (two) is done -** DONE one -** TODO two - -* Parent - :PROPERTIES: - :ORDERED: t - :END: -** TODO a -** TODO b, needs to wait for (a) -** TODO c, needs to wait for (a) and (b) -@end example - -@table @kbd -@kindex C-c C-x o -@item C-c C-x o -Toggle the @code{ORDERED} property of the current entry. -@kindex C-u C-u C-u C-c C-t -@item C-u C-u C-u C-c C-t -Change TODO state, circumventin any state blocking. -@end table - -If you set the variable @code{org-agenda-dim-blocked-tasks}, TODO entries -that cannot be closed because of such dependencies will be shown in a dimmed -font or even made invisible in agenda views (@pxref{Agenda Views}). - -@cindex checkboxes and TODO dependencies -You can also block changes of TODO states by looking at checkboxes -(@pxref{Checkboxes}). If you set the variable -@code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked -checkboxes will be blocked from switching to DONE. - -If you need more complex dependency structures, for example dependencies -between entries in different trees or files, check out the contributed -module @file{org-depend.el}. - -@page -@node Progress logging, Priorities, TODO extensions, TODO Items -@section Progress logging -@cindex progress logging -@cindex logging, of progress - -Org mode can automatically record a time stamp and possibly a note when -you mark a TODO item as DONE, or even each time you change the state of -a TODO item. This system is highly configurable, settings can be on a -per-keyword basis and can be localized to a file or even a subtree. For -information on how to clock working time for a task, see @ref{Clocking -work time}. - -@menu -* Closing items:: When was this entry marked DONE? -* Tracking TODO state changes:: When did the status change? -@end menu - -@node Closing items, Tracking TODO state changes, Progress logging, Progress logging -@subsection Closing items - -The most basic logging is to keep track of @emph{when} a certain TODO -item was finished. This is achieved with@footnote{The corresponding -in-buffer setting is: @code{#+STARTUP: logdone}}. - -@lisp -(setq org-log-done 'time) -@end lisp - -@noindent -Then each time you turn an entry from a TODO (not-done) state into any -of the DONE states, a line @samp{CLOSED: [timestamp]} will be inserted -just after the headline. If you turn the entry back into a TODO item -through further state cycling, that line will be removed again. If you -want to record a note along with the timestamp, use@footnote{The -corresponding in-buffer setting is: @code{#+STARTUP: lognotedone}} - -@lisp -(setq org-log-done 'note) -@end lisp - -@noindent -You will then be prompted for a note, and that note will be stored below -the entry with a @samp{Closing Note} heading. - -In the timeline (@pxref{Timeline}) and in the agenda -(@pxref{Weekly/daily agenda}), you can then use the @kbd{l} key to -display the TODO items with a @samp{CLOSED} timestamp on each day, -giving you an overview of what has been done. - -@node Tracking TODO state changes, , Closing items, Progress logging -@subsection Tracking TODO state changes - -When TODO keywords are used as workflow states (@pxref{Workflow -states}), you might want to keep track of when a state change occurred -and maybe take a note about this change. Since it is normally too much -to record a note for every state, Org mode expects configuration on a -per-keyword basis for this. This is achieved by adding special markers -@samp{!} (for a time stamp) and @samp{@@} (for a note) in parenthesis -after each keyword. For example, with the setting - -@lisp -(setq org-todo-keywords - '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) -@end lisp - -@noindent -you not only define global TODO keywords and fast access keys, but also -request that a time is recorded when the entry is turned into -DONE@footnote{It is possible that Org mode will record two time stamps -when you are using both @code{org-log-done} and state change logging. -However, it will never prompt for two notes - if you have configured -both, the state change recording note will take precedence and cancel -the @samp{Closing Note}.}, and that a note is recorded when switching to -WAIT or CANCELED. The setting for WAIT is even more special: The -@samp{!} after the slash means that in addition to the note taken when -entering the state, a time stamp should be recorded when @i{leaving} the -WAIT state, if and only if the @i{target} state does not configure -logging for entering it. So it has no effect when switching from WAIT -to DONE, because DONE is configured to record a timestamp only. But -when switching from WAIT back to TODO, the @samp{/!} in the WAIT -setting now triggers a timestamp even though TODO has no logging -configured. - -You can use the exact same syntax for setting logging preferences local -to a buffer: -@example -#+SEQ_TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@) -@end example - -In order to define logging settings that are local to a subtree or a -single item, define a LOGGING property in this entry. Any non-empty -LOGGING property resets all logging settings to nil. You may then turn -on logging for this specific tree using STARTUP keywords like -@code{lognotedone} or @code{logrepeat}, as well as adding state specific -settings like @code{TODO(!)}. For example - -@example -* TODO Log each state with only a time - :PROPERTIES: - :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!) - :END: -* TODO Only log when switching to WAIT, and when repeating - :PROPERTIES: - :LOGGING: WAIT(@@) logrepeat - :END: -* TODO No logging at all - :PROPERTIES: - :LOGGING: nil - :END: -@end example - -@node Priorities, Breaking down tasks, Progress logging, TODO Items -@section Priorities -@cindex priorities - -If you use Org mode extensively, you may end up enough TODO items that -it starts to make sense to prioritize them. Prioritizing can be done by -placing a @emph{priority cookie} into the headline of a TODO item, like -this - -@example -*** TODO [#A] Write letter to Sam Fortune -@end example - -@noindent -By default, Org mode supports three priorities: @samp{A}, @samp{B}, and -@samp{C}. @samp{A} is the highest priority. An entry without a cookie -is treated as priority @samp{B}. Priorities make a difference only in -the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they have -no inherent meaning to Org mode. - -Priorities can be attached to any outline tree entries; they do not need -to be TODO items. - -@table @kbd -@kindex @kbd{C-c ,} -@item @kbd{C-c ,} -Set the priority of the current headline. The command prompts for a -priority character @samp{A}, @samp{B} or @samp{C}. When you press -@key{SPC} instead, the priority cookie is removed from the headline. -The priorities can also be changed ``remotely'' from the timeline and -agenda buffer with the @kbd{,} command (@pxref{Agenda commands}). -@c -@kindex S-@key{up} -@kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} -Increase/decrease priority of current headline@footnote{See also the option -@code{org-priority-start-cycle-with-default'}.}. Note that these keys are -also used to modify time stamps (@pxref{Creating timestamps}). See also -@ref{Conflicts} for a discussion of the interaction with -@code{shift-selection-mode}. -@end table - -You can change the range of allowed priorities by setting the variables -@code{org-highest-priority}, @code{org-lowest-priority}, and -@code{org-default-priority}. For an individual buffer, you may set -these values (highest, lowest, default) like this (please make sure that -the highest priority is earlier in the alphabet than the lowest -priority): - -@example -#+PRIORITIES: A C B -@end example - -@node Breaking down tasks, Checkboxes, Priorities, TODO Items -@section Breaking tasks down into subtasks -@cindex tasks, breaking down - -It is often advisable to break down large tasks into smaller, manageable -subtasks. You can do this by creating an outline tree below a TODO item, -with detailed subtasks on the tree@footnote{To keep subtasks out of the -global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep -the overview over the fraction of subtasks that are already completed, insert -either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will -be updates each time the todo status of a child changes. For example: - -@example -* Organize Party [33%] -** TODO Call people [1/2] -*** TODO Peter -*** DONE Sarah -** TODO Buy food -** DONE Talk to neighbor -@end example - -If you would like a TODO entry to automatically change to DONE when all -children are done, you can use the following setup: - -@example -(defun org-summary-todo (n-done n-not-done) - "Switch entry to DONE when all subentries are done, to TODO otherwise." - (let (org-log-done org-log-states) ; turn off logging - (org-todo (if (= n-not-done 0) "DONE" "TODO")))) - -(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) -@end example - - -Another possibility is the use of checkboxes to identify (a hierarchy of) a -large number of subtasks (@pxref{Checkboxes}). - - -@node Checkboxes, , Breaking down tasks, TODO Items -@section Checkboxes -@cindex checkboxes - -Every item in a plain list (@pxref{Plain lists}) can be made into a -checkbox by starting it with the string @samp{[ ]}. This feature is -similar to TODO items (@pxref{TODO Items}), but is more lightweight. -Checkboxes are not included into the global TODO list, so they are often -great to split a task into a number of simple steps. Or you can use -them in a shopping list. To toggle a checkbox, use @kbd{C-c C-c}, or -use the mouse (thanks to Piotr Zielinski's @file{org-mouse.el}). - -Here is an example of a checkbox list. - -@example -* TODO Organize party [2/4] - - [-] call people [1/3] - - [ ] Peter - - [X] Sarah - - [ ] Sam - - [X] order food - - [ ] think about what music to play - - [X] talk to the neighbors -@end example - -Checkboxes work hierarchically, so if a checkbox item has children that -are checkboxes, toggling one of the children checkboxes will make the -parent checkbox reflect if none, some, or all of the children are -checked. - -@cindex statistics, for checkboxes -@cindex checkbox statistics -The @samp{[2/4]} and @samp{[1/3]} in the first and second line are -cookies indicating how many checkboxes present in this entry have been -checked off, and the total number of checkboxes are present. This can -give you an idea on how many checkboxes remain, even without opening a -folded entry. The cookies can be placed into a headline or into (the -first line of) a plain list item. Each cookie covers all checkboxes -structurally below the headline/item on which the cookie appear. You -have to insert the cookie yourself by typing either @samp{[/]} or -@samp{[%]}. With @samp{[/]} you get an @samp{n out of m} result, as in -the examples above. With @samp{[%]} you get information about the -percentage of checkboxes checked (in the above example, this would be -@samp{[50%]} and @samp{[33%]}, respectively). - -@noindent The following commands work with checkboxes: - -@table @kbd -@kindex C-c C-c -@item C-c C-c -Toggle checkbox at point. With a prefix argument, set it to @samp{[-]}, -which is considered to be an intermediate state. -@kindex C-c C-x C-b -@item C-c C-x C-b -Toggle checkbox status or (with prefix arg) checkbox presence at point. -@itemize @minus -@item -If there is an active region, toggle the first checkbox in the region -and set all remaining boxes to the same status as the first. With a prefix -arg, add or remove the checkbox for all items in the region. -@item -If the cursor is in a headline, toggle checkboxes in the region between -this headline and the next (so @emph{not} the entire subtree). -@item -If there is no active region, just toggle the checkbox at point. -@end itemize -@kindex M-S-@key{RET} -@item M-S-@key{RET} -Insert a new item with a checkbox. -This works only if the cursor is already in a plain list item -(@pxref{Plain lists}). -@kindex C-c # -@item C-c # -Update the checkbox statistics in the current outline entry. When -called with a @kbd{C-u} prefix, update the entire file. Checkbox -statistic cookies are updated automatically if you toggle checkboxes -with @kbd{C-c C-c} and make new ones with @kbd{M-S-@key{RET}}. If you -delete boxes or add/change them by hand, use this command to get things -back into sync. Or simply toggle any checkbox twice with @kbd{C-c C-c}. -@end table - -@node Tags, Properties and Columns, TODO Items, Top -@chapter Tags -@cindex tags -@cindex headline tagging -@cindex matching, tags -@cindex sparse tree, tag based - -An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org mode has extensive -support for tags. - -Every headline can contain a list of tags; they occur at the end of the -headline. Tags are normal words containing letters, numbers, @samp{_}, and -@samp{@@}. Tags must be preceded and followed by a single colon, e.g., -@samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}. -Tags will by default get a bold face with the same color as the headline. -You may specify special faces for specific tags using the variable -@code{org-tag-faces}, much in the same way as you can do for TODO keywords -(@pxref{Faces for TODO keywords}). - -@menu -* Tag inheritance:: Tags use the tree structure of the outline -* Setting tags:: How to assign tags to a headline -* Tag searches:: Searching for combinations of tags -@end menu - -@node Tag inheritance, Setting tags, Tags, Tags -@section Tag inheritance -@cindex tag inheritance -@cindex inheritance, of tags -@cindex sublevels, inclusion into tags match - -@i{Tags} make use of the hierarchical structure of outline trees. If a -heading has a certain tag, all subheadings will inherit the tag as -well. For example, in the list - -@example -* Meeting with the French group :work: -** Summary by Frank :boss:notes: -*** TODO Prepare slides for him :action: -@end example - -@noindent -the final heading will have the tags @samp{:work:}, @samp{:boss:}, -@samp{:notes:}, and @samp{:action:} even though the final heading is not -explicitly marked with those tags. You can also set tags that all entries in -a file should inherit as if these tags would be defined in a hypothetical -level zero that surrounds the entire file. - -@example -#+FILETAGS: :Peter:Boss:Secret: -@end example - -@noindent -To limit tag inheritance to specific tags, or to turn it off entirely, use -the variables @code{org-use-tag-inheritance} and -@code{org-tags-exclude-from-inheritance}. - -When a headline matches during a tags search while tag inheritance is turned -on, all the sublevels in the same tree will (for a simple match form) match -as well@footnote{This is only true if the search does not involve more -complex tests including properties (@pxref{Property searches}).}. The list -of matches may then become very long. If you only want to see the first tags -match in a subtree, configure the variable -@code{org-tags-match-list-sublevels} (not recommended). - -@node Setting tags, Tag searches, Tag inheritance, Tags -@section Setting tags -@cindex setting tags -@cindex tags, setting - -@kindex M-@key{TAB} -Tags can simply be typed into the buffer at the end of a headline. -After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is -also a special command for inserting tags: - -@table @kbd -@kindex C-c C-q -@item C-c C-q -@cindex completion, of tags -Enter new tags for the current headline. Org mode will either offer -completion or a special single-key interface for setting tags, see -below. After pressing @key{RET}, the tags will be inserted and aligned -to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all -tags in the current buffer will be aligned to that column, just to make -things look nice. TAGS are automatically realigned after promotion, -demotion, and TODO state changes (@pxref{TODO basics}). -@kindex C-c C-c -@item C-c C-c -When the cursor is in a headline, this does the same as @kbd{C-c C-q}. -@end table - -Org will support tag insertion based on a @emph{list of tags}. By -default this list is constructed dynamically, containing all tags -currently used in the buffer. You may also globally specify a hard list -of tags with the variable @code{org-tag-alist}. Finally you can set -the default tags for a given file with lines like - -@example -#+TAGS: @@work @@home @@tennisclub -#+TAGS: laptop car pc sailboat -@end example - -If you have globally defined your preferred set of tags using the -variable @code{org-tag-alist}, but would like to use a dynamic tag list -in a specific file, add an empty TAGS option line to that file: - -@example -#+TAGS: -@end example - -By default Org mode uses the standard minibuffer completion facilities for -entering tags. However, it also implements another, quicker, tag selection -method called @emph{fast tag selection}. This allows you to select and -deselect tags with just a single key press. For this to work well you should -assign unique letters to most of your commonly used tags. You can do this -globally by configuring the variable @code{org-tag-alist} in your -@file{.emacs} file. For example, you may find the need to tag many items in -different files with @samp{:@@home:}. In this case you can set something -like: - -@lisp -(setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l))) -@end lisp - -@noindent If the tag is only relevant to the file you are working on then you -can, instead, set the TAGS option line as: - -@example -#+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p) -@end example - -@noindent -You can also group together tags that are mutually exclusive. By using -braces, as in: - -@example -#+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p) -@end example - -@noindent you indicate that at most one of @samp{@@work}, @samp{@@home}, -and @samp{@@tennisclub} should be selected. Multiple such groups are allowed. - -@noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of -these lines to activate any changes. - -@noindent -To set these mutually exclusive groups in the variable @code{org-mode-alist} -you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead -of the braces. The previous example would be set globally by the following -configuration: - -@lisp -(setq org-tag-alist '((:startgroup . nil) - ("@@work" . ?w) ("@@home" . ?h) - ("@@tennisclub" . ?t) - (:endgroup . nil) - ("laptop" . ?l) ("pc" . ?p))) -@end lisp - -If at least one tag has a selection key then pressing @kbd{C-c C-c} will -automatically present you with a special interface, listing inherited tags, -the tags of the current headline, and a list of all valid tags with -corresponding keys@footnote{Keys will automatically be assigned to tags which -have no configured keys.}. In this interface, you can use the following -keys: - -@table @kbd -@item a-z... -Pressing keys assigned to tags will add or remove them from the list of -tags in the current line. Selecting a tag in a group of mutually -exclusive tags will turn off any other tags from that group. -@kindex @key{TAB} -@item @key{TAB} -Enter a tag in the minibuffer, even if the tag is not in the predefined -list. You will be able to complete on all tags present in the buffer. -@kindex @key{SPC} -@item @key{SPC} -Clear all tags for this line. -@kindex @key{RET} -@item @key{RET} -Accept the modified set. -@item C-g -Abort without installing changes. -@item q -If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}. -@item ! -Turn off groups of mutually exclusive tags. Use this to (as an -exception) assign several tags from such a group. -@item C-c -Toggle auto-exit after the next change (see below). -If you are using expert mode, the first @kbd{C-c} will display the -selection window. -@end table - -@noindent -This method lets you assign tags to a headline with very few keys. With -the above setup, you could clear the current tags and set @samp{@@home}, -@samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c -C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to -@samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or -alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag -@samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h -@key{RET} @key{RET}}. - -If you find that most of the time, you need only a single key press to -modify your list of tags, set the variable -@code{org-fast-tag-selection-single-key}. Then you no longer have to -press @key{RET} to exit fast tag selection - it will immediately exit -after the first change. If you then occasionally need more keys, press -@kbd{C-c} to turn off auto-exit for the current tag selection process -(in effect: start selection with @kbd{C-c C-c C-c} instead of @kbd{C-c -C-c}). If you set the variable to the value @code{expert}, the special -window is not even shown for single-key tag selection, it comes up only -when you press an extra @kbd{C-c}. - -@node Tag searches, , Setting tags, Tags -@section Tag searches -@cindex tag searches -@cindex searching for tags - -Once a system of tags has been set up, it can be used to collect related -information into special lists. - -@table @kbd -@kindex C-c \ -@kindex C-c / T -@item C-c \ -@itemx C-c / T -Create a sparse tree with all headlines matching a tags search. With a -@kbd{C-u} prefix argument, ignore headlines that are not a TODO line. -@kindex C-c a m -@item C-c a m -Create a global list of tag matches from all agenda files. -@xref{Matching tags and properties}. -@kindex C-c a M -@item C-c a M -Create a global list of tag matches from all agenda files, but check -only TODO items and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). -@end table - -@cindex Boolean logic, for tag searches -A @i{tags} search string can use Boolean operators @samp{&} for AND and -@samp{|} for OR. @samp{&} binds more strongly than @samp{|}. -Parenthesis are currently not implemented. A tag may also be preceded -by @samp{-}, to select against it, and @samp{+} is syntactic sugar for -positive selection. The AND operator @samp{&} is optional when @samp{+} -or @samp{-} is present. Examples: - -@table @samp -@item +work-boss -Select headlines tagged @samp{:work:}, but discard those also tagged -@samp{:boss:}. -@item work|laptop -Selects lines tagged @samp{:work:} or @samp{:laptop:}. -@item work|laptop&night -Like before, but require the @samp{:laptop:} lines to be tagged also -@samp{:night:}. -@end table - -@cindex TODO keyword matching, with tags search -You may also test for TODO keywords (@pxref{TODO extensions}) and properties -(@pxref{Properties and Columns}) at the same time as matching tags. For a -guide on how to match properties, see @ref{Property searches}. To match a -specific TODO keyword, include an expression like @samp{+TODO="NEXT"} as one -of the terms in a tags search. - -There is also the possibility to end the tags part of the match (which may -include several terms connected with @samp{|}) with a @samp{/} and then -specify a Boolean expression just for TODO keywords. The syntax is then -similar to the tag matches, but should be applied with consideration: For -example, a positive selection on several TODO keywords can not meaningfully -be combined with boolean AND. However, @emph{negative selection} combined -with AND can be meaningful. To make sure that only lines are checked that -actually have any TODO keyword (resulting in a speed-up), use @kbd{C-c a M}, -or equivalently start the TODO part after the slash with @samp{!}. Examples: - -@table @samp -@item work+TODO="WAITING" -Select @samp{:work:}-tagged TODO lines with the specific TODO -keyword @samp{WAITING}. -@item work+TODO="WAITING"|home+TODO="WAITING" -Waiting tasks both at work and at home. -@item work/WAITING -Same as the first example. -@item work/!-WAITING-NEXT -Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING} -nor @samp{NEXT} -@item work/!+WAITING|+NEXT -Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or -@samp{NEXT}. -@end table - -@cindex regular expressions, with tags search -Any element of the tag/todo match can be a regular expression - in this -case it must be enclosed in curly braces. For example, -@samp{work+@{^boss.*@}} matches headlines that contain the tag -@samp{:work:} and any tag @i{starting} with @samp{boss}. You may also use a -regular expression in @samp{TODO=@{^W@}} which would match TODO keywords -starting with the letter @samp{W}. - -@cindex level, require for tags/property match -@cindex category, require for tags/property match -You can also require a headline to be of a certain level or category, by -writing instead of any TAG an expression like @samp{LEVEL=3} or -@samp{CATEGORY="work"}, respectively. For example, a search -@samp{+LEVEL=3+boss/-DONE} lists all level three headlines that have the -tag @samp{boss} and are @emph{not} marked with the TODO keyword DONE. - -Accessing TODO, LEVEL, and CATEGORY during a search is fast. Accessing any -other properties will slow down the search. - -@node Properties and Columns, Dates and Times, Tags, Top -@chapter Properties and Columns -@cindex properties - -Properties are a set of key-value pairs associated with an entry. There -are two main applications for properties in Org mode. First, properties -are like tags, but with a value. Second, you can use properties to -implement (very basic) database capabilities in an Org buffer. For -an example of the first application, imagine maintaining a file where -you document bugs and plan releases of a piece of software. Instead of -using tags like @code{:release_1:}, @code{:release_2:}, one can use a -property, say @code{:Release:}, that in different subtrees has different -values, such as @code{1.0} or @code{2.0}. For an example of the second -application of properties, imagine keeping track of your music CDs, -where properties could be things such as the album artist, date of -release, number of tracks, and so on. - -Properties can be conveniently edited and viewed in column view -(@pxref{Column view}). - -@menu -* Property syntax:: How properties are spelled out -* Special properties:: Access to other Org mode features -* Property searches:: Matching property values -* Property inheritance:: Passing values down the tree -* Column view:: Tabular viewing and editing -* Property API:: Properties for Lisp programmers -@end menu - -@node Property syntax, Special properties, Properties and Columns, Properties and Columns -@section Property syntax -@cindex property syntax -@cindex drawer, for properties - -Properties are key-value pairs. They need to be inserted into a special -drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property -is specified on a single line, with the key (surrounded by colons) -first, and the value after it. Here is an example: - -@example -* CD collection -** Classic -*** Goldberg Variations - :PROPERTIES: - :Title: Goldberg Variations - :Composer: J.S. Bach - :Artist: Glen Gould - :Publisher: Deutsche Grammphon - :NDisks: 1 - :END: -@end example - -You may define the allowed values for a particular property @samp{:Xyz:} -by setting a property @samp{:Xyz_ALL:}. This special property is -@emph{inherited}, so if you set it in a level 1 entry, it will apply to -the entire tree. When allowed values are defined, setting the -corresponding property becomes easier and is less prone to typing -errors. For the example with the CD collection, we can predefine -publishers and the number of disks in a box like this: - -@example -* CD collection - :PROPERTIES: - :NDisks_ALL: 1 2 3 4 - :Publisher_ALL: "Deutsche Grammophon" Philips EMI - :END: -@end example - -If you want to set properties that can be inherited by any entry in a -file, use a line like - -@example -#+PROPERTY: NDisks_ALL 1 2 3 4 -@end example - -Property values set with the global variable -@code{org-global-properties} can be inherited by all entries in all -Org files. - -@noindent -The following commands help to work with properties: - -@table @kbd -@kindex M-@key{TAB} -@item M-@key{TAB} -After an initial colon in a line, complete property keys. All keys used -in the current file will be offered as possible completions. -@kindex C-c C-x p -@item C-c C-x p -Set a property. This prompts for a property name and a value. If -necessary, the property drawer is created as well. -@item M-x org-insert-property-drawer -Insert a property drawer into the current entry. The drawer will be -inserted early in the entry, but after the lines with planning -information like deadlines. -@kindex C-c C-c -@item C-c C-c -With the cursor in a property drawer, this executes property commands. -@item C-c C-c s -Set a property in the current entry. Both the property and the value -can be inserted using completion. -@kindex S-@key{right} -@kindex S-@key{left} -@item S-@key{left}/@key{right} -Switch property at point to the next/previous allowed value. -@item C-c C-c d -Remove a property from the current entry. -@item C-c C-c D -Globally remove a property, from all entries in the current file. -@item C-c C-c c -Compute the property at point, using the operator and scope from the -nearest column format definition. -@end table - -@node Special properties, Property searches, Property syntax, Properties and Columns -@section Special properties -@cindex properties, special - -Special properties provide alternative access method to Org mode -features discussed in the previous chapters, like the TODO state or the -priority of an entry. This interface exists so that you can include -these states into columns view (@pxref{Column view}), or to use them in -queries. The following property names are special and should not be -used as keys in the properties drawer: - -@example -TODO @r{The TODO keyword of the entry.} -TAGS @r{The tags defined directly in the headline.} -ALLTAGS @r{All tags, including inherited ones.} -PRIORITY @r{The priority of the entry, a string with a single letter.} -DEADLINE @r{The deadline time string, without the angular brackets.} -SCHEDULED @r{The scheduling time stamp, without the angular brackets.} -TIMESTAMP @r{The first keyword-less time stamp in the entry.} -TIMESTAMP_IA @r{The first inactive time stamp in the entry.} -CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}} - @r{must be run first to compute the values.} -@end example - -@node Property searches, Property inheritance, Special properties, Properties and Columns -@section Property searches -@cindex properties, searching -@cindex searching, of properties - -To create sparse trees and special lists with selection based on properties, -the same commands are used as for tag searches (@pxref{Tag searches}), and -the same logic applies. For example, here is a search string: - -@example -+work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \ - +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>" -@end example - -@noindent -The type of comparison will depend on how the comparison value is written: -@itemize @minus -@item -If the comparison value is a plain number, a numerical comparison is done, -and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=}, -@samp{>=}, and @samp{<>}. -@item -If the comparison value is enclosed in double -quotes, a string comparison is done, and the same operators are allowed. -@item -If the comparison value is enclosed in double quotes @emph{and} angular -brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are -assumed to be date/time specifications in the standard Org way, and the -comparison will be done accordingly. Special values that will be recognized -are @code{""} for now (including time), and @code{""}, and -@code{""} for these days at 0:00 hours, i.e. without a time -specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units -@code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year, -respectively, can be used. -@item -If the comparison value is enclosed -in curly braces, a regexp match is performed, with @samp{=} meaning that the -regexp matches the property value, and @samp{<>} meaning that it does not -match. -@end itemize - -So the search string in the example finds entries tagged @samp{:work:} but -not @samp{:boss:}, which also have a priority value @samp{A}, a -@samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort} -property that is numerically smaller than 2, a @samp{:With:} property that is -matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled -on or after October 11, 2008. - -You can configure Org mode to use property inheritance during a search, but -beware that this can slow down searches considerably. See @ref{Property -inheritance} for details. - -There is also a special command for creating sparse trees based on a -single property: - -@table @kbd -@kindex C-c / p -@item C-c / p -Create a sparse tree based on the value of a property. This first -prompts for the name of a property, and then for a value. A sparse tree -is created with all entries that define this property with the given -value. If you enclose the value into curly braces, it is interpreted as -a regular expression and matched against the property values. -@end table - -@node Property inheritance, Column view, Property searches, Properties and Columns -@section Property Inheritance -@cindex properties, inheritance -@cindex inheritance, of properties - -The outline structure of Org mode documents lends itself for an -inheritance model of properties: If the parent in a tree has a certain -property, the children can inherit this property. Org mode does not -turn this on by default, because it can slow down property searches -significantly and is often not needed. However, if you find inheritance -useful, you can turn it on by setting the variable -@code{org-use-property-inheritance}. It may be set to @code{t}, to make -all properties inherited from the parent, to a list of properties -that should be inherited, or to a regular expression that matches -inherited properties. - -Org mode has a few properties for which inheritance is hard-coded, at -least for the special applications for which they are used: - -@table @code -@item COLUMNS -The @code{:COLUMNS:} property defines the format of column view -(@pxref{Column view}). It is inherited in the sense that the level -where a @code{:COLUMNS:} property is defined is used as the starting -point for a column view table, independently of the location in the -subtree from where columns view is turned on. -@item CATEGORY -For agenda view, a category set through a @code{:CATEGORY:} property -applies to the entire subtree. -@item ARCHIVE -For archiving, the @code{:ARCHIVE:} property may define the archive -location for the entire subtree (@pxref{Moving subtrees}). -@item LOGGING -The LOGGING property may define logging settings for an entry or a -subtree (@pxref{Tracking TODO state changes}). -@end table - -@node Column view, Property API, Property inheritance, Properties and Columns -@section Column view - -A great way to view and edit properties in an outline tree is -@emph{column view}. In column view, each outline item is turned into a -table row. Columns in this table provide access to properties of the -entries. Org mode implements columns by overlaying a tabular structure -over the headline of each item. While the headlines have been turned -into a table row, you can still change the visibility of the outline -tree. For example, you get a compact table by switching to CONTENTS -view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view -is active), but you can still open, read, and edit the entry below each -headline. Or, you can switch to column view after executing a sparse -tree command and in this way get a table only for the selected items. -Column view also works in agenda buffers (@pxref{Agenda Views}) where -queries have collected selected items, possibly from a number of files. - -@menu -* Defining columns:: The COLUMNS format property -* Using column view:: How to create and use column view -* Capturing column view:: A dynamic block for column view -@end menu - -@node Defining columns, Using column view, Column view, Column view -@subsection Defining columns -@cindex column view, for properties -@cindex properties, column view - -Setting up a column view first requires defining the columns. This is -done by defining a column format line. - -@menu -* Scope of column definitions:: Where defined, where valid? -* Column attributes:: Appearance and content of a column -@end menu - -@node Scope of column definitions, Column attributes, Defining columns, Defining columns -@subsubsection Scope of column definitions - -To define a column format for an entire file, use a line like - -@example -#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO -@end example - -To specify a format that only applies to a specific tree, add a -@code{:COLUMNS:} property to the top node of that tree, for example: - -@example -** Top node for columns view - :PROPERTIES: - :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO - :END: -@end example - -If a @code{:COLUMNS:} property is present in an entry, it defines columns -for the entry itself, and for the entire subtree below it. Since the -column definition is part of the hierarchical structure of the document, -you can define columns on level 1 that are general enough for all -sublevels, and more specific columns further down, when you edit a -deeper part of the tree. - -@node Column attributes, , Scope of column definitions, Defining columns -@subsubsection Column attributes -A column definition sets the attributes of a column. The general -definition looks like this: - -@example - %[width]property[(title)][@{summary-type@}] -@end example - -@noindent -Except for the percent sign and the property name, all items are -optional. The individual parts have the following meaning: - -@example -width @r{An integer specifying the width of the column in characters.} - @r{If omitted, the width will be determined automatically.} -property @r{The property that should be edited in this column.} -(title) @r{The header text for the column. If omitted, the} - @r{property name is used.} -@{summary-type@} @r{The summary type. If specified, the column values for} - @r{parent nodes are computed from the children.} - @r{Supported summary types are:} - @{+@} @r{Sum numbers in this column.} - @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.} - @{$@} @r{Currency, short for @samp{+;%.2f}.} - @{:@} @r{Sum times, HH:MM:SS, plain numbers are hours.} - @{X@} @r{Checkbox status, [X] if all children are [X].} - @{X/@} @r{Checkbox status, [n/m].} - @{X%@} @r{Checkbox status, [n%].} -@end example - -@noindent -Here is an example for a complete columns definition, along with allowed -values. - -@example -:COLUMNS: %20ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line - it is wrapped here only because of formatting constraints.} - %10Time_Estimate@{:@} %CLOCKSUM -:Owner_ALL: Tammy Mark Karl Lisa Don -:Status_ALL: "In progress" "Not started yet" "Finished" "" -:Approved_ALL: "[ ]" "[X]" -@end example - -The first column, @samp{%25ITEM}, means the first 25 characters of the -item itself, i.e. of the headline. You probably always should start the -column definition with the @samp{ITEM} specifier. The other specifiers -create columns @samp{Owner} with a list of names as allowed values, for -@samp{Status} with four different possible values, and for a checkbox -field @samp{Approved}. When no width is given after the @samp{%} -character, the column will be exactly as wide as it needs to be in order -to fully display all values. The @samp{Approved} column does have a -modified title (@samp{Approved?}, with a question mark). Summaries will -be created for the @samp{Time_Estimate} column by adding time duration -expressions like HH:MM, and for the @samp{Approved} column, by providing -an @samp{[X]} status if all children have been checked. The -@samp{CLOCKSUM} column is special, it lists the sum of CLOCK intervals -in the subtree. - -@node Using column view, Capturing column view, Defining columns, Column view -@subsection Using column view - -@table @kbd -@tsubheading{Turning column view on and off} -@kindex C-c C-x C-c -@item C-c C-x C-c -Create the column view for the local environment. This command searches -the hierarchy, up from point, for a @code{:COLUMNS:} property that defines -a format. When one is found, the column view table is established for -the entire tree, starting from the entry that contains the @code{:COLUMNS:} -property. If none is found, the format is taken from the @code{#+COLUMNS} -line or from the variable @code{org-columns-default-format}, and column -view is established for the current entry and its subtree. -@kindex r -@item r -Recreate the column view, to include recent changes made in the buffer. -@kindex g -@item g -Same as @kbd{r}. -@kindex q -@item q -Exit column view. -@tsubheading{Editing values} -@item @key{left} @key{right} @key{up} @key{down} -Move through the column view from field to field. -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left}/@key{right} -Switch to the next/previous allowed value of the field. For this, you -have to have specified allowed values for a property. -@item 1..9,0 -Directly select the nth allowed value, @kbd{0} selects the 10th value. -@kindex n -@kindex p -@itemx n / p -Same as @kbd{S-@key{left}/@key{right}} -@kindex e -@item e -Edit the property at point. For the special properties, this will -invoke the same interface that you normally use to change that -property. For example, when editing a TAGS property, the tag completion -or fast selection interface will pop up. -@kindex C-c C-c -@item C-c C-c -When there is a checkbox at point, toggle it. -@kindex v -@item v -View the full value of this property. This is useful if the width of -the column is smaller than that of the value. -@kindex a -@item a -Edit the list of allowed values for this property. If the list is found -in the hierarchy, the modified values is stored there. If no list is -found, the new value is stored in the first entry that is part of the -current column view. -@tsubheading{Modifying the table structure} -@kindex < -@kindex > -@item < / > -Make the column narrower/wider by one character. -@kindex S-M-@key{right} -@item S-M-@key{right} -Insert a new column, to the left of the current column. -@kindex S-M-@key{left} -@item S-M-@key{left} -Delete the current column. -@end table - -@node Capturing column view, , Using column view, Column view -@subsection Capturing column view - -Since column view is just an overlay over a buffer, it cannot be -exported or printed directly. If you want to capture a column view, use -this @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame -of this block looks like this: - -@cindex #+BEGIN: columnview -@example -* The column view -#+BEGIN: columnview :hlines 1 :id "label" - -#+END: -@end example - -@noindent This dynamic block has the following parameters: - -@table @code -@item :id -This is most important parameter. Column view is a feature that is -often localized to a certain (sub)tree, and the capture block might be -in a different location in the file. To identify the tree whose view to -capture, you can use 3 values: -@example -local @r{use the tree in which the capture block is located} -global @r{make a global view, including all headings in the file} -"file:path-to-file" - @r{run column view at the top of this file} -"ID" @r{call column view in the tree that has an @code{:ID:}} - @r{property with the value @i{label}. You can use} - @r{@kbd{M-x org-id-copy} to create a globally unique ID for} - @r{the current entry and copy it to the kill-ring.} -@end example -@item :hlines -When @code{t}, insert a hline after every line. When a number N, insert -a hline before each headline with level @code{<= N}. -@item :vlines -When set to @code{t}, enforce column groups to get vertical lines. -@item :maxlevel -When set to a number, don't capture entries below this level. -@item :skip-empty-rows -When set to @code{t}, skip row where the only non-empty specifier of the -column view is @code{ITEM}. - -@end table - -@noindent -The following commands insert or update the dynamic block: - -@table @kbd -@kindex C-c C-x i -@item C-c C-x i -Insert a dynamic block capturing a column view. You will be prompted -for the scope or id of the view. -@kindex C-c C-c -@item C-c C-c -@kindex C-c C-x C-u -@itemx C-c C-x C-u -Update dynamical block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u -Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks in a buffer. -@end table - -You can add formulas to the column view table and you may add plotting -instructions in front of the table - these will survive an update of the -block. If there is a @code{#+TBLFM:} after the table, the table will -actually be recalculated automatically after an update. - -@node Property API, , Column view, Properties and Columns -@section The Property API -@cindex properties, API -@cindex API, for properties - -There is a full API for accessing and changing properties. This API can -be used by Emacs Lisp programs to work with properties and to implement -features based on them. For more information see @ref{Using the -property API}. - -@node Dates and Times, Capture, Properties and Columns, Top -@chapter Dates and Times -@cindex dates -@cindex times -@cindex time stamps -@cindex date stamps - -To assist project planning, TODO items can be labeled with a date and/or -a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org mode. This may be a -little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org mode this term -is used in a much wider sense. - -@menu -* Timestamps:: Assigning a time to a tree entry -* Creating timestamps:: Commands which insert timestamps -* Deadlines and scheduling:: Planning your work -* Clocking work time:: Tracking how long you spend on a task -* Effort estimates:: Planning work effort in advance -* Relative timer:: Notes with a running timer -@end menu - - -@node Timestamps, Creating timestamps, Dates and Times, Dates and Times -@section Timestamps, deadlines and scheduling -@cindex time stamps -@cindex ranges, time -@cindex date stamps -@cindex deadlines -@cindex scheduling - -A time stamp is a specification of a date (possibly with time or a range -of times) in a special format, either @samp{<2003-09-16 Tue>} or -@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue -12:00-12:30>}@footnote{This is the standard ISO date/time format. To -use an alternative format, see @ref{Custom time format}.}. A time stamp -can appear anywhere in the headline or body of an Org tree entry. Its -presence causes entries to be shown on specific dates in the agenda -(@pxref{Weekly/daily agenda}). We distinguish: - -@table @var -@item Plain time stamp; Event; Appointment -@cindex timestamp -A simple time stamp just assigns a date/time to an item. This is just -like writing down an appointment or event in a paper agenda. In the -timeline and agenda displays, the headline of an entry associated with a -plain time stamp will be shown exactly on that date. - -@example -* Meet Peter at the movies <2006-11-01 Wed 19:15> -* Discussion on climate change <2006-11-02 Thu 20:00-22:00> -@end example - -@item Time stamp with repeater interval -@cindex timestamp, with repeater interval -A time stamp may contain a @emph{repeater interval}, indicating that it -applies not only on the given date, but again and again after a certain -interval of N days (d), weeks (w), months(m), or years(y). The -following will show up in the agenda every Wednesday: - -@example -* Pick up Sam at school <2007-05-16 Wed 12:30 +1w> -@end example - -@item Diary-style sexp entries -For more complex date specifications, Org mode supports using the -special sexp diary entries implemented in the Emacs calendar/diary -package. For example - -@example -* The nerd meeting on every 2nd Thursday of the month - <%%(diary-float t 4 2)> -@end example - -@item Time/Date range -@cindex timerange -@cindex date range -Two time stamps connected by @samp{--} denote a range. The headline -will be shown on the first and last day of the range, and on any dates -that are displayed and fall in the range. Here is an example: - -@example -** Meeting in Amsterdam - <2004-08-23 Mon>--<2004-08-26 Thu> -@end example - -@item Inactive time stamp -@cindex timestamp, inactive -@cindex inactive timestamp -Just like a plain time stamp, but with square brackets instead of -angular ones. These time stamps are inactive in the sense that they do -@emph{not} trigger an entry to show up in the agenda. - -@example -* Gillian comes late for the fifth time [2006-11-01 Wed] -@end example - -@end table - -@node Creating timestamps, Deadlines and scheduling, Timestamps, Dates and Times -@section Creating timestamps -@cindex creating timestamps -@cindex timestamps, creating - -For Org mode to recognize time stamps, they need to be in the specific -format. All commands listed below produce time stamps in the correct -format. - -@table @kbd -@kindex C-c . -@item C-c . -Prompt for a date and insert a corresponding time stamp. When the cursor is -at an existing time stamp in the buffer, the command is used to modify this -timestamp instead of inserting a new one. When this command is used twice in -succession, a time range is inserted. -@c -@kindex C-u C-c . -@item C-u C-c . -Like @kbd{C-c .}, but use the alternative format which contains date -and time. The default time can be rounded to multiples of 5 minutes, -see the option @code{org-time-stamp-rounding-minutes}. -@c -@kindex C-c ! -@item C-c ! -Like @kbd{C-c .}, but insert an inactive time stamp that will not cause -an agenda entry. -@c -@kindex C-c < -@item C-c < -Insert a time stamp corresponding to the cursor date in the Calendar. -@c -@kindex C-c > -@item C-c > -Access the Emacs calendar for the current date. If there is a -timestamp in the current line, go to the corresponding date -instead. -@c -@kindex C-c C-o -@item C-c C-o -Access the agenda for the date given by the time stamp or -range at -point (@pxref{Weekly/daily agenda}). -@c -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left} -@itemx S-@key{right} -Change date at cursor by one day. These key bindings conflict with -CUA mode (@pxref{Conflicts}). -@c -@kindex S-@key{up} -@kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} -Change the item under the cursor in a timestamp. The cursor can be on a -year, month, day, hour or minute. Note that if the cursor is in a -headline and not at a time stamp, these same keys modify the priority of -an item. (@pxref{Priorities}). The key bindings also conflict with -CUA mode (@pxref{Conflicts}). -@c -@kindex C-c C-y -@cindex evaluate time range -@item C-c C-y -Evaluate a time range by computing the difference between start and end. -With a prefix argument, insert result after the time range (in a table: into -the following column). -@end table - - -@menu -* The date/time prompt:: How Org mode helps you entering date and time -* Custom time format:: Making dates look different -@end menu - -@node The date/time prompt, Custom time format, Creating timestamps, Creating timestamps -@subsection The date/time prompt -@cindex date, reading in minibuffer -@cindex time, reading in minibuffer - -When Org mode prompts for a date/time, the default is shown as an ISO -date, and the prompt therefore seems to ask for an ISO date. But it -will in fact accept any string containing some date and/or time -information, and it is really smart about interpreting your input. You -can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org mode will find whatever information -is in there and derive anything you have not specified from the -@emph{default date and time}. The default is usually the current date -and time, but when modifying an existing time stamp, or when entering -the second stamp of a range, it is taken from the stamp in the buffer. -When filling in information, Org mode assumes that most of the time you -will want to enter a date in the future: If you omit the month/year and -the given day/month is @i{before} today, it will assume that you mean a -future date@footnote{See the variable -@code{org-read-date-prefer-future}.}. - -For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org mode are -in @b{bold}. - -@example -3-2-5 --> 2003-02-05 -14 --> @b{2006}-@b{06}-14 -12 --> @b{2006}-@b{07}-12 -Fri --> nearest Friday (defaultdate or later) -sep 15 --> @b{2006}-09-15 -feb 15 --> @b{2007}-02-15 -sep 12 9 --> 2009-09-12 -12:45 --> @b{2006}-@b{06}-@b{13} 12:45 -22 sept 0:34 --> @b{2006}-09-22 0:34 -w4 --> ISO week for of the current year @b{2006} -2012 w4 fri --> Friday of ISO week 4 in 2012 -2012-w04-5 --> Same as above -@end example - -Furthermore you can specify a relative date by giving, as the -@emph{first} thing in the input: a plus/minus sign, a number and a -letter [dwmy] to indicate change in days weeks, months, years. With a -single plus or minus, the date is always relative to today. With a -double plus or minus, it is relative to the default date. If instead of -a single letter, you use the abbreviation of day name, the date will be -the nth such day. E.g. - -@example -+0 --> today -. --> today -+4d --> four days from today -+4 --> same as above -+2w --> two weeks from today -++5 --> five days from default date -+2tue --> second tuesday from now. -@end example - -The function understands English month and weekday abbreviations. If -you want to use unabbreviated names and/or other languages, configure -the variables @code{parse-time-months} and @code{parse-time-weekdays}. - -@cindex calendar, for selecting date -Parallel to the minibuffer prompt, a calendar is popped up@footnote{If -you don't need/want the calendar, configure the variable -@code{org-popup-calendar-for-date-prompt}.}. When you exit the date -prompt, either by clicking on a date in the calendar, or by pressing -@key{RET}, the date selected in the calendar will be combined with the -information entered at the prompt. You can control the calendar fully -from the minibuffer: - -@kindex < -@kindex > -@kindex mouse-1 -@kindex S-@key{right} -@kindex S-@key{left} -@kindex S-@key{down} -@kindex S-@key{up} -@kindex M-S-@key{right} -@kindex M-S-@key{left} -@kindex @key{RET} -@example -> / < @r{Scroll calendar forward/backward by one month.} -mouse-1 @r{Select date by clicking on it.} -S-@key{right}/@key{left} @r{One day forward/backward.} -S-@key{down}/@key{up} @r{One week forward/backward.} -M-S-@key{right}/@key{left} @r{One month forward/backward.} -@key{RET} @r{Choose date in calendar.} -@end example - -The actions of the date/time prompt may seem complex, but I assure you they -will grow on you, and you will start getting annoyed by pretty much any other -way of entering a date/time out there. To help you understand what is going -on, the current interpretation of your input will be displayed live in the -minibuffer@footnote{If you find this distracting, turn the display of with -@code{org-read-date-display-live}.}. - -@node Custom time format, , The date/time prompt, Creating timestamps -@subsection Custom time format -@cindex custom date/time format -@cindex time format, custom -@cindex date format, custom - -Org mode uses the standard ISO notation for dates and times as it is -defined in ISO 8601. If you cannot get used to this and require another -representation of date and time to keep you happy, you can get it by -customizing the variables @code{org-display-custom-times} and -@code{org-time-stamp-custom-formats}. - -@table @kbd -@kindex C-c C-x C-t -@item C-c C-x C-t -Toggle the display of custom formats for dates and times. -@end table - -@noindent -Org mode needs the default format for scanning, so the custom date/time -format does not @emph{replace} the default format - instead it is put -@emph{over} the default format using text properties. This has the -following consequences: -@itemize @bullet -@item -You cannot place the cursor onto a time stamp anymore, only before or -after. -@item -The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust -each component of a time stamp. If the cursor is at the beginning of -the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day, -just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the -time will be changed by one minute. -@item -If the time stamp contains a range of clock times or a repeater, these -will not be overlayed, but remain in the buffer as they were. -@item -When you delete a time stamp character-by-character, it will only -disappear from the buffer after @emph{all} (invisible) characters -belonging to the ISO timestamp have been removed. -@item -If the custom time stamp format is longer than the default and you are -using dates in tables, table alignment will be messed up. If the custom -format is shorter, things do work as expected. -@end itemize - - -@node Deadlines and scheduling, Clocking work time, Creating timestamps, Dates and Times -@section Deadlines and scheduling - -A time stamp may be preceded by special keywords to facilitate planning: - -@table @var -@item DEADLINE -@cindex DEADLINE keyword - -Meaning: the task (most likely a TODO item, though not necessarily) is supposed -to be finished on that date. - -On the deadline date, the task will be listed in the agenda. In -addition, the agenda for @emph{today} will carry a warning about the -approaching or missed deadline, starting -@code{org-deadline-warning-days} before the due date, and continuing -until the entry is marked DONE. An example: - -@example -*** TODO write article about the Earth for the Guide - The editor in charge is [[bbdb:Ford Prefect]] - DEADLINE: <2004-02-29 Sun> -@end example - -You can specify a different lead time for warnings for a specific -deadlines using the following syntax. Here is an example with a warning -period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. - -@item SCHEDULED -@cindex SCHEDULED keyword - -Meaning: you are planning to start working on that task on the given -date. - -The headline will be listed under the given date@footnote{It will still -be listed on that date after it has been marked DONE. If you don't like -this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In -addition, a reminder that the scheduled date has passed will be present -in the compilation for @emph{today}, until the entry is marked DONE. -I.e., the task will automatically be forwarded until completed. - -@example -*** TODO Call Trillian for a date on New Years Eve. - SCHEDULED: <2004-12-25 Sat> -@end example - -@noindent -@b{Important:} Scheduling an item in Org mode should @i{not} be -understood in the same way that we understand @i{scheduling a meeting}. -Setting a date for a meeting is just a simple appointment, you should -mark this entry with a simple plain time stamp, to get this item shown -on the date where it applies. This is a frequent mis-understanding from -Org-users. In Org mode, @i{scheduling} means setting a date when you -want to start working on an action item. -@end table - -You may use time stamps with repeaters in scheduling and deadline -entries. Org mode will issue early and late warnings based on the -assumption that the time stamp represents the @i{nearest instance} of -the repeater. However, the use of diary sexp entries like -@c -@code{<%%(diary-float t 42)>} -@c -in scheduling and deadline timestamps is limited. Org mode does not -know enough about the internals of each sexp function to issue early and -late warnings. However, it will show the item on each day where the -sexp entry matches. - -@menu -* Inserting deadline/schedule:: Planning items -* Repeated tasks:: Items that show up again and again -@end menu - -@node Inserting deadline/schedule, Repeated tasks, Deadlines and scheduling, Deadlines and scheduling -@subsection Inserting deadlines or schedules - -The following commands allow to quickly insert a deadline or to schedule -an item: - -@table @kbd -@c -@kindex C-c C-d -@item C-c C-d -Insert @samp{DEADLINE} keyword along with a stamp. The insertion will -happen in the line directly following the headline. When called with a -prefix arg, an existing deadline will be removed from the entry. -@c FIXME Any CLOSED timestamp will be removed.???????? -@c -@kindex C-c / d -@cindex sparse tree, for deadlines -@item C-c / d -Create a sparse tree with all deadlines that are either past-due, or -which will become due within @code{org-deadline-warning-days}. -With @kbd{C-u} prefix, show all deadlines in the file. With a numeric -prefix, check that many days. For example, @kbd{C-1 C-c / d} shows -all deadlines due tomorrow. -@c -@kindex C-c C-s -@item C-c C-s -Insert @samp{SCHEDULED} keyword along with a stamp. The insertion will -happen in the line directly following the headline. Any CLOSED -timestamp will be removed. When called with a prefix argument, remove -the scheduling date from the entry. -@c -@kindex C-c C-x C-k -@kindex k a -@kindex k s -@item C-c C-x C-k -Mark the current entry for agenda action. After you have marked the entry -like this, you can open the agenda or the calendar to find an appropriate -date. With the cursor on the selected date, press @kbd{k s} or @kbd{k d} to -schedule the marked item. -@end table - -@node Repeated tasks, , Inserting deadline/schedule, Deadlines and scheduling -@subsection Repeated tasks - -Some tasks need to be repeated again and again. Org mode helps to -organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, -or plain time stamp. In the following example -@example -** TODO Pay the rent - DEADLINE: <2005-10-01 Sat +1m> -@end example -the @code{+1m} is a repeater; the intended interpretation is that the -task has a deadline on <2005-10-01> and repeats itself every (one) month -starting from that time. If you need both a repeater and a special -warning period in a deadline entry, the repeater comes first and the -warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}. - -Deadlines and scheduled items produce entries in the agenda when they -are over-due, so it is important to be able to mark such an entry as -completed once you have done so. When you mark a DEADLINE or a SCHEDULE -with the TODO keyword DONE, it will no longer produce entries in the -agenda. The problem with this is, however, that then also the -@emph{next} instance of the repeated entry will not be active. Org mode -deals with this in the following way: When you try to mark such an entry -DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating -time stamp by the repeater interval, and immediately set the entry state -back to TODO. In the example above, setting the state to DONE would -actually switch the date like this: - -@example -** TODO Pay the rent - DEADLINE: <2005-11-01 Tue +1m> -@end example - -A timestamp@footnote{You can change this using the option -@code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat}, -@code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you -will also be prompted for a note.} will be added under the deadline, to keep -a record that you actually acted on the previous instance of this deadline. - -As a consequence of shifting the base date, this entry will no longer be -visible in the agenda when checking past dates, but all future instances -will be visible. - -With the @samp{+1m} cookie, the date shift will always be exactly one -month. So if you have not payed the rent for three months, marking this -entry DONE will still keep it as an overdue deadline. Depending on the -task, this may not be the best way to handle it. For example, if you -forgot to call you father for 3 weeks, it does not make sense to call -him 3 times in a single day to make up for it. Finally, there are tasks -like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org mode has -special repeaters markers with @samp{++} and @samp{.+}. For example: - -@example -** TODO Call Father - DEADLINE: <2008-02-10 Sun ++1w> - Marking this DONE will shift the date by at least one week, - but also by as many weeks as it takes to get this date into - the future. However, it stays on a Sunday, even if you called - and marked it done on Saturday. -** TODO Check the batteries in the smoke detectors - DEADLINE: <2005-11-01 Tue .+1m> - Marking this DONE will shift the date to one month after - today. -@end example - -You may have both scheduling and deadline information for a specific -task - just make sure that the repeater intervals on both are the same. - -@node Clocking work time, Effort estimates, Deadlines and scheduling, Dates and Times -@section Clocking work time - -Org mode allows you to clock the time you spent on specific tasks in a -project. When you start working on an item, you can start the clock. -When you stop working on that task, or when you mark the task done, the -clock is stopped and the corresponding time interval is recorded. It -also computes the total time spent on each subtree of a project. - -@table @kbd -@kindex C-c C-x C-i -@item C-c C-x C-i -Start the clock on the current item (clock-in). This inserts the CLOCK -keyword together with a timestamp. If this is not the first clocking of -this item, the multiple CLOCK lines will be wrapped into a -@code{:CLOCK:} drawer (see also the variable -@code{org-clock-into-drawer}). When called with a @kbd{C-u} prefix argument, -select the task from a list of recently clocked tasks. With two @kbd{C-u -C-u} prefixes, clock into the task at point and mark it as the default task. -The default task will always be available when selecting a clocking task, -with letter @kbd{d}. -@kindex C-c C-x C-o -@item C-c C-x C-o -Stop the clock (clock-out). This inserts another timestamp at the same -location where the clock was last started. It also directly computes -the resulting time in inserts it after the time range as @samp{=> -HH:MM}. See the variable @code{org-log-note-clock-out} for the -possibility to record an additional note together with the clock-out -time stamp@footnote{The corresponding in-buffer setting is: -@code{#+STARTUP: lognoteclock-out}}. -@kindex C-c C-y -@item C-c C-y -Recompute the time interval after changing one of the time stamps. This -is only necessary if you edit the time stamps directly. If you change -them with @kbd{S-@key{cursor}} keys, the update is automatic. -@kindex C-c C-t -@item C-c C-t -Changing the TODO state of an item to DONE automatically stops the clock -if it is running in this same item. -@kindex C-c C-x C-x -@item C-c C-x C-x -Cancel the current clock. This is useful if a clock was started by -mistake, or if you ended up working on something else. -@kindex C-c C-x C-j -@item C-c C-x C-j -Jump to the entry that contains the currently running clock. With a -@kbd{C-u} prefix arg, select the target task from a list of recently clocked -tasks. -@kindex C-c C-x C-d -@item C-c C-x C-d -Display time summaries for each subtree in the current buffer. This -puts overlays at the end of each headline, showing the total time -recorded under that heading, including the time of any subheadings. You -can use visibility cycling to study the tree, but the overlays disappear -when you change the buffer (see variable -@code{org-remove-highlights-with-change}) or press @kbd{C-c C-c}. -@kindex C-c C-x C-r -@item C-c C-x C-r -Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock -report as an Org mode table into the current file. When the cursor is -at an existing clock table, just update it. When called with a prefix -argument, jump to the first clock report in the current document and -update it. -@cindex #+BEGIN: clocktable -@example -#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file -#+END: clocktable -@end example -@noindent -If such a block already exists at point, its content is replaced by the -new table. The @samp{BEGIN} line can specify options: -@example -:maxlevel @r{Maximum level depth to which times are listed in the table.} -:emphasize @r{When @code{t}, emphasize level one and level two items} -:scope @r{The scope to consider. This can be any of the following:} - nil @r{the current buffer or narrowed region} - file @r{the full current buffer} - subtree @r{the subtree where the clocktable is located} - treeN @r{the surrounding level N tree, for example @code{tree3}} - tree @r{the surrounding level 1 tree} - agenda @r{all agenda files} - ("file"..) @r{scan these files} - file-with-archives @r{current file and its archives} - agenda-with-archives @r{all agenda files, including archives} -:block @r{The time block to consider. This block is specified either} - @r{absolute, or relative to the current time and may be any of} - @r{these formats:} - 2007-12-31 @r{New year eve 2007} - 2007-12 @r{December 2007} - 2007-W50 @r{ISO-week 50 in 2007} - 2007 @r{the year 2007} - today, yesterday, today-N @r{a relative day} - thisweek, lastweek, thisweek-N @r{a relative week} - thismonth, lastmonth, thismonth-N @r{a relative month} - thisyear, lastyear, thisyear-N @r{a relative year} - @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.} -:tstart @r{A time string specifying when to start considering times} -:tend @r{A time string specifying when to stop considering times} -:step @r{@code{week} or @code{day}, to split the table into chunks.} - @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.} -:link @r{Link the item headlines in the table to their origins} -:formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.} - @r{As a special case, @samp{:formula %} adds column with % time.} - @r{If you do not specify a formula here, any existing formula} - @r{below the clock table will survive updates and be evaluated.} -@end example -So to get a clock summary of the current level 1 tree, for the current -day, you could write -@example -#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t -#+END: clocktable -@end example -and to use a specific time range you could write@footnote{Note that all -parameters must be specified in a single line - the line is broken here -only to fit it onto the manual.} -@example -#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>" - :tend "<2006-08-10 Thu 12:00>" -#+END: clocktable -@end example -A summary of the current subtree with % times would be -@example -#+BEGIN: clocktable :scope subtree :link t :formula % -#+END: clocktable -@end example -@kindex C-c C-c -@item C-c C-c -@kindex C-c C-x C-u -@itemx C-c C-x C-u -Update dynamical block at point. The cursor needs to be in the -@code{#+BEGIN} line of the dynamic block. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u -Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if -you have several clock table blocks in a buffer. -@kindex S-@key{left} -@kindex S-@key{right} -@item S-@key{left} -@itemx S-@key{right} -Shift the current @code{:block} interval and update the table. The cursor -needs to be in the @code{#+BEGIN: clocktable} line for this command. If -@code{:block} is @code{today}, it will be shifted to @code{today-1} etc. -@end table - -The @kbd{l} key may be used in the timeline (@pxref{Timeline}) and in -the agenda (@pxref{Weekly/daily agenda}) to show which tasks have been -worked on or closed during a day. - -@node Effort estimates, Relative timer, Clocking work time, Dates and Times -@section Effort estimates -@cindex effort estimates - -If you want to plan your work in a very detailed way, or if you need to -produce offers with quotations of the estimated work effort, you may want to -assign effort estimates to entries. If you are also clocking your work, you -may later want to compare the planned effort with the actual working time, a -great way to improve planning estimates. Effort estimates are stored in a -special property @samp{Effort}@footnote{You may change the property being -used with the variable @code{org-effort-property}.}. Clearly the best way to -work with effort estimates is through column view (@pxref{Column view}). You -should start by setting up discrete values for effort estimates, and a -@code{COLUMNS} format that displays these values together with clock sums (if -you want to clock your time). For a specific buffer you can use - -@example -#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00 8:00 -#+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM -@end example - -@noindent -or, even better, you can set up these values globally by customizing the -variables @code{org-global-properties} and @code{org-columns-default-format}. -In particular if you want to use this setup also in the agenda, a global -setup may be advised. - -The way to assign estimates to individual items is then to switch to column -mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the -value. The values you enter will immediately be summed up in the hierarchy. -In the column next to it, any clocked time will be displayed. - -If you switch to column view in the daily/weekly agenda, the effort column -will summarize the estimated work effort for each day@footnote{Please note -the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda -column view}).}, and you can use this to find space in your schedule. To get -an overview of the entire part of the day that is committed, you can set the -option @code{org-agenda-columns-add-appointments-to-effort-sum}. The -appointments on a day that take place over a specified time interval will -then also be added to the load estimate of the day. - -Effort estimates can be used in secondary agenda filtering that is triggered -with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have -these estimates defined consistently, two or three key presses will narrow -down the list to stuff that fits into an available time slot. - -@node Relative timer, , Effort estimates, Dates and Times -@section Taking notes with a relative timer -@cindex relative timer - -When taking notes during, for example, a meeting or a video viewing, it can -be useful to have access to times relative to a starting time. Org provides -such a relative timer and make it easy to create timed notes. - -@table @kbd -@kindex C-c C-x . -@item C-c C-x . -Insert a relative time into the buffer. The first time you use this, the -timer will be started. When called with a prefix argument, the timer is -restarted. -@kindex C-c C-x - -@item C-c C-x - -Insert a description list item with the current relative time. With a prefix -argument, first reset the timer to 0. -@kindex M-@key{RET} -@item M-@key{RET} -Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert -new timer items. -@kindex C-c C-x , -@item C-c C-x , -Pause the timer, or continue it if it is already paused. With prefix -argument, stop it entirely. -@kindex C-u C-c C-x , -@item C-u C-c C-x , -Stop the timer. After this, you can only start a new timer, not continue the -old one. This command also removes the timer from the mode line. -@kindex C-c C-x 0 -@item C-c C-x 0 -Reset the timer without inserting anything into the buffer. By default, the -timer is reset to 0. When called with a @kbd{C-u} prefix, reset the timer to -specific starting offset. The user is prompted for the offset, with a -default taken from a timer string at point, if any, So this can be used to -restart taking notes after a break in the process. When called with a double -prefix argument @kbd{C-c C-u}, change all timer strings in the active region -by a certain amount. This can be used to fix timer strings if the timer was -not started at exactly the right moment. -@end table - -@node Capture, Agenda Views, Dates and Times, Top -@chapter Capture -@cindex capture - -An important part of any organization system is the ability to quickly -capture new ideas and tasks, and to associate reference material with them. -Org uses the @file{remember} package to create tasks, and stores files -related to a task (@i{attachments}) in a special directory. - -@menu -* Remember:: Capture new tasks/ideas with little interruption -* Attachments:: Add files to tasks. -@end menu - -@node Remember, Attachments, Capture, Capture -@section Remember -@cindex @file{remember.el} - -The @i{Remember} package by John Wiegley lets you store quick notes with -little interruption of your work flow. See -@uref{http://www.emacswiki.org/cgi-bin/wiki/RememberMode} for more -information. It is an excellent way to add new notes and tasks to -Org files. Org significantly expands the possibilities of -@i{remember}: You may define templates for different note types, and -associate target files and headlines with specific templates. It also -allows you to select the location where a note should be stored -interactively, on the fly. - -@menu -* Setting up Remember:: Some code for .emacs to get things going -* Remember templates:: Define the outline of different note types -* Storing notes:: Directly get the note to where it belongs -* Refiling notes:: Moving a note or task to a project -@end menu - -@node Setting up Remember, Remember templates, Remember, Remember -@subsection Setting up Remember - -The following customization will tell @i{remember} to use org files as -target, and to create annotations compatible with Org links. - -@example -(org-remember-insinuate) -(setq org-directory "~/path/to/my/orgfiles/") -(setq org-default-notes-file (concat org-directory "/notes.org")) -(define-key global-map "\C-cr" 'org-remember) -@end example - -The last line binds the command @code{org-remember} to a global -key@footnote{Please select your own key, @kbd{C-c r} is only a -suggestion.}. @code{org-remember} basically just calls @code{remember}, -but it makes a few things easier: If there is an active region, it will -automatically copy the region into the remember buffer. It also allows -to jump to the buffer and location where remember notes are being -stored: Just call @code{org-remember} with a prefix argument. If you -use two prefix arguments, Org jumps to the location where the last -remember note was stored. - -The remember buffer will actually use @code{org-mode} as its major mode, so -that all editing features of Org-mode are available. In addition to this, a -minor mode @code{org-remember-mode} is turned on, for the single purpose that -you can use its keymap @code{org-remember-mode-map} to overwrite some of -Org-mode's key bindings. - -You can also call @code{org-remember} in a special way from the agenda, -using the @kbd{k r} key combination. With this access, any time stamps -inserted by the selected remember template (see below) will default to -the cursor date in the agenda, rather than to the current date. - -@node Remember templates, Storing notes, Setting up Remember, Remember -@subsection Remember templates -@cindex templates, for remember - -In combination with Org, you can use templates to generate -different types of @i{remember} notes. For example, if you would like -to use one template to create general TODO entries, another one for -journal entries, and a third one for collecting random ideas, you could -use: - -@example -(setq org-remember-templates - '(("Todo" ?t "* TODO %?\n %i\n %a" "~/org/TODO.org" "Tasks") - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org") - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) -@end example - -@noindent In these entries, the first string is just a name, and the -character specifies how to select the template. It is useful if the -character is also the first letter of the name. The next string specifies -the template. Two more (optional) strings give the file in which, and the -headline under which the new note should be stored. The file (if not present -or @code{nil}) defaults to @code{org-default-notes-file}, the heading to -@code{org-remember-default-headline}. If the file name is not an absolute -path, it will be interpreted relative to @code{org-directory}. The heading -can also be the symbols @code{top} or @code{bottom} to send note as level 1 -entries to the beginning or end of the file, respectively. - -An optional sixth element specifies the contexts in which the user can select -the template. This element can be a list of major modes or a function. -@code{org-remember} will first check whether the function returns @code{t} or -if we are in any of the listed major mode, and exclude templates for which -this condition is not fulfilled. Templates that do not specify this element -at all, or that use @code{nil} or @code{t} as a value will always be -selectable. - -So for example: - -@example -(setq org-remember-templates - '(("Bug" ?b "* BUG %?\n %i\n %a" "~/org/BUGS.org" "Bugs" (emacs-lisp-mode)) - ("Journal" ?j "* %U %?\n\n %i\n %a" "~/org/JOURNAL.org" "X" my-check) - ("Idea" ?i "* %^@{Title@}\n %i\n %a" "~/org/JOURNAL.org" "New Ideas"))) -@end example - -The first template will only be available when invoking @code{org-remember} -from an buffer in @code{emacs-lisp-mode}. The second template will only be -available when the function @code{my-check} returns @code{t}. The third -template will be proposed in any context. - -When you call @kbd{M-x org-remember} (or @kbd{M-x remember}) to remember -something, Org will prompt for a key to select the template (if you have -more than one template) and then prepare the buffer like -@example -* TODO - [[file:link to where you called remember]] -@end example - -@noindent -During expansion of the template, special @kbd{%}-escapes allow dynamic -insertion of content: -@example -%^@{prompt@} @r{prompt the user for a string and replace this sequence with it.} - @r{You may specify a default value and a completion table with} - @r{%^@{prompt|default|completion2|completion3...@}} - @r{The arrow keys access a prompt-specific history.} -%a @r{annotation, normally the link created with @code{org-store-link}} -%A @r{like @code{%a}, but prompt for the description part} -%i @r{initial content, the region when remember is called with C-u.} - @r{The entire text will be indented like @code{%i} itself.} -%t @r{time stamp, date only} -%T @r{time stamp with date and time} -%u, %U @r{like the above, but inactive time stamps} -%^t @r{like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}} - @r{You may define a prompt like @code{%^@{Birthday@}t}} -%n @r{user name (taken from @code{user-full-name})} -%c @r{Current kill ring head.} -%x @r{Content of the X clipboard.} -%^C @r{Interactive selection of which kill or clip to use.} -%^L @r{Like @code{%^C}, but insert as link.} -%^g @r{prompt for tags, with completion on tags in target file.} -%k @r{title of currently clocked task} -%K @r{link to currently clocked task} -%^G @r{prompt for tags, with completion all tags in all agenda files.} -%^@{prop@}p @r{Prompt the user for a value for property @code{prop}} -%:keyword @r{specific information for certain link types, see below} -%[pathname] @r{insert the contents of the file given by @code{pathname}} -%(sexp) @r{evaluate elisp @code{(sexp)} and replace with the result} -%! @r{immediately store note after completing the template} - @r{(skipping the @kbd{C-c C-c} that normally triggers storing)} -%& @r{jump to target location immediately after storing note} -@end example - -@noindent -For specific link types, the following keywords will be -defined@footnote{If you define your own link types (@pxref{Adding -hyperlink types}), any property you store with -@code{org-store-link-props} can be accessed in remember templates in a -similar way.}: - -@example -Link type | Available keywords --------------------+---------------------------------------------- -bbdb | %:name %:company -bbdb | %::server %:port %:nick -vm, wl, mh, rmail | %:type %:subject %:message-id - | %:from %:fromname %:fromaddress - | %:to %:toname %:toaddress - | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}} -gnus | %:group, @r{for messages also all email fields} -w3, w3m | %:url -info | %:file %:node -calendar | %:date" -@end example - -@noindent -To place the cursor after template expansion use: - -@example -%? @r{After completing the template, position cursor here.} -@end example - -@noindent -If you change your mind about which template to use, call -@code{org-remember} in the remember buffer. You may then select a new -template that will be filled with the previous context information. - -@node Storing notes, Refiling notes, Remember templates, Remember -@subsection Storing notes - -When you are finished preparing a note with @i{remember}, you have to press -@kbd{C-c C-c} to file the note away. If you have started the clock in the -remember buffer, you will first be asked if you want to clock out -now@footnote{To avoid this query, configure the variable -@code{org-remember-clock-out-on-exit}.}. If you answer @kbd{n}, the clock -will continue to run after the note was filed away. - -The handler will then store the note in the file and under the headline -specified in the template, or it will use the default file and headlines. -The window configuration will be restored, sending you back to the working -context before the call to @code{remember}. To re-use the location found -during the last call to @code{remember}, exit the remember buffer with -@kbd{C-0 C-c C-c}, i.e. specify a zero prefix argument to @kbd{C-c C-c}. -Another special case is @kbd{C-2 C-c C-c} which files the note as a child of -the currently clocked item. - -If you want to store the note directly to a different place, use -@kbd{C-1 C-c C-c} instead to exit remember@footnote{Configure the -variable @code{org-remember-store-without-prompt} to make this behavior -the default.}. The handler will then first prompt for a target file - -if you press @key{RET}, the value specified for the template is used. -Then the command offers the headings tree of the selected file, with the -cursor position at the default headline (if you had specified one in the -template). You can either immediately press @key{RET} to get the note -placed there. Or you can use the following keys to find a different -location: -@example -@key{TAB} @r{Cycle visibility.} -@key{down} / @key{up} @r{Next/previous visible headline.} -n / p @r{Next/previous visible headline.} -f / b @r{Next/previous headline same level.} -u @r{One level up.} -@c 0-9 @r{Digit argument.} -@end example -@noindent -Pressing @key{RET} or @key{left} or @key{right} -then leads to the following result. - -@multitable @columnfractions 0.2 0.15 0.65 -@item @b{Cursor position} @tab @b{Key} @tab @b{Note gets inserted} -@item on headline @tab @key{RET} @tab as sublevel of the heading at cursor, first or last -@item @tab @tab depending on @code{org-reverse-note-order}. -@item @tab @key{left}/@key{right} @tab as same level, before/after current heading -@item buffer-start @tab @key{RET} @tab as level 2 heading at end of file or level 1 at beginning -@item @tab @tab depending on @code{org-reverse-note-order}. -@item not on headline @tab @key{RET} - @tab at cursor position, level taken from context. -@end multitable - -Before inserting the text into a tree, the function ensures that the text has -a headline, i.e. a first line that starts with a @samp{*}. If not, a -headline is constructed from the current date. If you have indented the text -of the note below the headline, the indentation will be adapted if inserting -the note into the tree requires demotion from level 1. - -@node Refiling notes, , Storing notes, Remember -@subsection Refiling notes -@cindex refiling notes - -Remember is usually used to quickly capture notes and tasks into one or -a few capture lists. When reviewing the captured data, you may want to -refile some of the entries into a different list, for example into a -project. Cutting, finding the right location and then pasting the note -is cumbersome. To simplify this process, you can use the following -special command: - -@table @kbd -@kindex C-c C-w -@item C-c C-w -Refile the entry or region at point. This command offers possible locations -for refiling the entry and lets you select one with completion. The item (or -all items in the region) is filed below the target heading as a subitem. -Depending on @code{org-reverse-note-order}, it will be either the first or -last subitem.@* -By default, all level 1 headlines in the current buffer are considered to be -targets, but you can have more complex definitions across a number of files. -See the variable @code{org-refile-targets} for details. If you would like to -select a location via a file-path-like completion along the outline path, see -the variables @code{org-refile-use-outline-path} and -@code{org-outline-path-complete-in-steps}. -@kindex C-u C-c C-w -@item C-u C-c C-w -Use the refile interface to jump to a heading. -@kindex C-u C-u C-c C-w -@item C-u C-u C-c C-w -Jump to the location where @code{org-refile} last moved a tree to. -@end table - -@node Attachments, , Remember, Capture -@section Attachments -@cindex attachments - -It is often useful to associate reference material with an outline node/task. -Small chunks of plain text can simply be stored in the subtree of a project. -Hyperlinks (@pxref{Hyperlinks}) can be used to establish associations with -files that live elsewhere on your computer or in the cloud, like emails or -source code files belonging to a project. Another method is @i{attachments}, -which are files located in a directory belonging to an outline node. Org -uses directories named by the unique ID of each entry. These directories are -located in the @file{data} directory which lives in the same directory where -your org-file lives@footnote{If you move entries or Org-files from one -directory to the next, you may want to configure @code{org-attach-directory} -to contain an absolute path.}. If you initialize this directory with -@code{git-init}, Org will automatically commit changes when it sees them. -The attachment system has been contributed to Org by John Wiegley. - -In cases where this seems better, you can also attach a directory of your -choice to an entry. You can also make children inherit the attachment -directory from a parent, so that an entire subtree uses the same attached -directory. - -@noindent The following commands deal with attachments. - -@table @kbd - -@kindex C-c C-a -@item C-c C-a -The dispatcher for commands related to the attachment system. After these -keys, a list of commands is displayed and you need to press an additional key -to select a command: - -@table @kbd -@kindex C-c C-a a -@item a -Select a file and move it into the task's attachment directory. The file -will be copied, moved, or linked, depending on @code{org-attach-method}. -Note that hard links are not supported on all systems. - -@kindex C-c C-a c -@kindex C-c C-a m -@kindex C-c C-a l -@item c/m/l -Attach a file using the copy/move/link method. -Note that hard links are not supported on all systems. - -@kindex C-c C-a n -@item n -Create a new attachment as an Emacs buffer. - -@kindex C-c C-a z -@item z -Synchronize the current task with its attachment directory, in case you added -attachments yourself. - -@kindex C-c C-a o -@item o -Open current task's attachment. If there are more than one, prompt for a -file name first. Opening will follow the rules set by @code{org-file-apps}. -For more details, see the information on following hyperlinks -(@pxref{Handling links}). - -@kindex C-c C-a O -@item O -Also open the attachment, but force opening the file in Emacs. - -@kindex C-c C-a f -@item f -Open the current task's attachment directory. - -@kindex C-c C-a F -@item F -Also open the directory, but force using @code{dired} in Emacs. - -@kindex C-c C-a d -@item d -Select and delete a single attachment. - -@kindex C-c C-a D -@item D -Delete all of a task's attachments. A safer way is to open the directory in -dired and delete from there. - -@kindex C-c C-a s -@item C-c C-a s -Set a specific directory as the entry's attachment directory. This works by -putting the directory path into the @code{ATTACH_DIR} property. - -@kindex C-c C-a i -@item C-c C-a i -Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the -same directory for attachments as the parent. -@end table -@end table - -@node Agenda Views, Embedded LaTeX, Capture, Top -@chapter Agenda Views -@cindex agenda views - -Due to the way Org works, TODO items, time-stamped items, and -tagged headlines can be scattered throughout a file or even a number of -files. To get an overview of open action items, or of events that are -important for a particular date, this information must be collected, -sorted and displayed in an organized way. - -Org can select items based on various criteria, and display them -in a separate buffer. Seven different view types are provided: - -@itemize @bullet -@item -an @emph{agenda} that is like a calendar and shows information -for specific dates, -@item -a @emph{TODO list} that covers all unfinished -action items, -@item -a @emph{match view}, showings headlines based on the tags, properties and -TODO state associated with them, -@item -a @emph{timeline view} that shows all events in a single Org file, -in time-sorted view, -@item -a @emph{keyword search view} that shows all entries from multiple files -that contain specified keywords. -@item -a @emph{stuck projects view} showing projects that currently don't move -along, and -@item -@emph{custom views} that are special tag/keyword searches and -combinations of different views. -@end itemize - -@noindent -The extracted information is displayed in a special @emph{agenda -buffer}. This buffer is read-only, but provides commands to visit the -corresponding locations in the original Org files, and even to -edit these files remotely. - -Two variables control how the agenda buffer is displayed and whether the -window configuration is restored when the agenda exits: -@code{org-agenda-window-setup} and -@code{org-agenda-restore-windows-after-quit}. - -@menu -* Agenda files:: Files being searched for agenda information -* Agenda dispatcher:: Keyboard access to agenda views -* Built-in agenda views:: What is available out of the box? -* Presentation and sorting:: How agenda items are prepared for display -* Agenda commands:: Remote editing of Org trees -* Custom agenda views:: Defining special searches and views -* Agenda column view:: Using column view for collected entries -@end menu - -@node Agenda files, Agenda dispatcher, Agenda Views, Agenda Views -@section Agenda files -@cindex agenda files -@cindex files for agenda - -The information to be shown is normally collected from all @emph{agenda -files}, the files listed in the variable -@code{org-agenda-files}@footnote{If the value of that variable is not a -list, but a single file name, then the list of agenda files will be -maintained in that external file.}. If a directory is part of this list, -all files with the extension @file{.org} in this directory will be part -of the list. - -Thus even if you only work with a single Org file, this file should -be put into that list@footnote{When using the dispatcher, pressing -@kbd{<} before selecting a command will actually limit the command to -the current file, and ignore @code{org-agenda-files} until the next -dispatcher command.}. You can customize @code{org-agenda-files}, but -the easiest way to maintain it is through the following commands - -@cindex files, adding to agenda list -@table @kbd -@kindex C-c [ -@item C-c [ -Add current file to the list of agenda files. The file is added to -the front of the list. If it was already in the list, it is moved to -the front. With a prefix argument, file is added/moved to the end. -@kindex C-c ] -@item C-c ] -Remove current file from the list of agenda files. -@kindex C-, -@kindex C-' -@item C-, -@itemx C-' -Cycle through agenda file list, visiting one file after the other. -@kindex M-x org-iswitchb -@item M-x org-iswitchb -Command to use an @code{iswitchb}-like interface to switch to and between Org -buffers. -@end table - -@noindent -The Org menu contains the current list of files and can be used -to visit any of them. - -If you would like to focus the agenda temporarily onto a file not in -this list, or onto just one file in the list or even only a subtree in a -file, this can be done in different ways. For a single agenda command, -you may press @kbd{<} once or several times in the dispatcher -(@pxref{Agenda dispatcher}). To restrict the agenda scope for an -extended period, use the following commands: - -@table @kbd -@kindex C-c C-x < -@item C-c C-x < -Permanently restrict the agenda to the current subtree. When with a -prefix argument, or with the cursor before the first headline in a file, -the agenda scope is set to the entire file. This restriction remains in -effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<} -or @kbd{>} in the agenda dispatcher. If there is a window displaying an -agenda view, the new restriction takes effect immediately. -@kindex C-c C-x > -@item C-c C-x > -Remove the permanent restriction created by @kbd{C-c C-x <}. -@end table - -@noindent -When working with @file{Speedbar}, you can use the following commands in -the Speedbar frame: -@table @kbd -@kindex < -@item < @r{in the speedbar frame} -Permanently restrict the agenda to the item at the cursor in the -Speedbar frame, either an Org file or a subtree in such a file. -If there is a window displaying an agenda view, the new restriction takes -effect immediately. -@kindex > -@item > @r{in the speedbar frame} -Lift the restriction again. -@end table - -@node Agenda dispatcher, Built-in agenda views, Agenda files, Agenda Views -@section The agenda dispatcher -@cindex agenda dispatcher -@cindex dispatching agenda commands -The views are created through a dispatcher that should be bound to a -global key, for example @kbd{C-c a} (@pxref{Installation}). In the -following we will assume that @kbd{C-c a} is indeed how the dispatcher -is accessed and list keyboard access to commands accordingly. After -pressing @kbd{C-c a}, an additional letter is required to execute a -command. The dispatcher offers the following default commands: -@table @kbd -@item a -Create the calendar-like agenda (@pxref{Weekly/daily agenda}). -@item t @r{/} T -Create a list of all TODO items (@pxref{Global TODO list}). -@item m @r{/} M -Create a list of headlines matching a TAGS expression (@pxref{Matching -tags and properties}). -@item L -Create the timeline view for the current buffer (@pxref{Timeline}). -@item s -Create a list of entries selected by a boolean expression of keywords -and/or regular expressions that must or must not occur in the entry. -@item / -Search for a regular expression in all agenda files and additionally in -the files listed in @code{org-agenda-multi-occur-extra-files}. This -uses the Emacs command @code{multi-occur}. A prefix argument can be -used to specify the number of context lines for each match, default is -1. -@item # @r{/} ! -Create a list of stuck projects (@pxref{Stuck projects}). -@item < -Restrict an agenda command to the current buffer@footnote{For backward -compatibility, you can also press @kbd{1} to restrict to the current -buffer.}. After pressing @kbd{<}, you still need to press the character -selecting the command. -@item < < -If there is an active region, restrict the following agenda command to -the region. Otherwise, restrict it to the current subtree@footnote{For -backward compatibility, you can also press @kbd{0} to restrict to the -current buffer.}. After pressing @kbd{< <}, you still need to press the -character selecting the command. -@end table - -You can also define custom commands that will be accessible through the -dispatcher, just like the default commands. This includes the -possibility to create extended agenda buffers that contain several -blocks together, for example the weekly agenda, the global TODO list and -a number of special tags matches. @xref{Custom agenda views}. - -@node Built-in agenda views, Presentation and sorting, Agenda dispatcher, Agenda Views -@section The built-in agenda views - -In this section we describe the built-in views. - -@menu -* Weekly/daily agenda:: The calendar page with current tasks -* Global TODO list:: All unfinished action items -* Matching tags and properties:: Structured information with fine-tuned search -* Timeline:: Time-sorted view for single file -* Keyword search:: Finding entries by keyword -* Stuck projects:: Find projects you need to review -@end menu - -@node Weekly/daily agenda, Global TODO list, Built-in agenda views, Built-in agenda views -@subsection The weekly/daily agenda -@cindex agenda -@cindex weekly agenda -@cindex daily agenda - -The purpose of the weekly/daily @emph{agenda} is to act like a page of a -paper agenda, showing all the tasks for the current week or day. - -@table @kbd -@cindex org-agenda, command -@kindex C-c a a -@item C-c a a -Compile an agenda for the current week from a list of org files. The agenda -shows the entries for each day. With a numeric prefix@footnote{For backward -compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be -listed before the agenda. This feature is deprecated, use the dedicated TODO -list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1 -C-c a a}) you may set the number of days to be displayed (see also the -variable @code{org-agenda-ndays}) -@end table - -Remote editing from the agenda buffer means, for example, that you can -change the dates of deadlines and appointments from the agenda buffer. -The commands available in the Agenda buffer are listed in @ref{Agenda -commands}. - -@subsubheading Calendar/Diary integration -@cindex calendar integration -@cindex diary integration - -Emacs contains the calendar and diary by Edward M. Reingold. The -calendar displays a three-month calendar with holidays from different -countries and cultures. The diary allows you to keep track of -anniversaries, lunar phases, sunrise/set, recurrent appointments -(weekly, monthly) and more. In this way, it is quite complementary to -Org. It can be very useful to combine output from Org with -the diary. - -In order to include entries from the Emacs diary into Org mode's -agenda, you only need to customize the variable - -@lisp -(setq org-agenda-include-diary t) -@end lisp - -@noindent After that, everything will happen automatically. All diary -entries including holidays, anniversaries etc will be included in the -agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and -@key{RET} can be used from the agenda buffer to jump to the diary -file in order to edit existing diary entries. The @kbd{i} command to -insert new entries for the current date works in the agenda buffer, as -well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display -Sunrise/Sunset times, show lunar phases and to convert to other -calendars, respectively. @kbd{c} can be used to switch back and forth -between calendar and agenda. - -If you are using the diary only for sexp entries and holidays, it is -faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org mode evaluates diary-style sexp -entries, and does it faster because there is no overhead for first -creating the diary display. Note that the sexp entries must start at -the left margin, no white space is allowed before them. For example, -the following segment of an Org file will be processed and entries -will be made in the agenda: - -@example -* Birthdays and similar stuff -#+CATEGORY: Holiday -%%(org-calendar-holiday) ; special function for holiday names -#+CATEGORY: Ann -%%(diary-anniversary 14 5 1956) Arthur Dent is %d years old -%%(diary-anniversary 2 10 1869) Mahatma Gandhi would be %d years old -@end example - -@subsubheading Appointment reminders -@cindex @file{appt.el} -@cindex appointment reminders - -Org can interact with Emacs appointments notification facility. - -To add all the appointments of your agenda files, use the command -@code{org-agenda-to-appt}. This commands also lets you filter through -the list of your appointments and add only those belonging to a specific -category or matching a regular expression. See the docstring for -details. - -@node Global TODO list, Matching tags and properties, Weekly/daily agenda, Built-in agenda views -@subsection The global TODO list -@cindex global TODO list -@cindex TODO list, global - -The global TODO list contains all unfinished TODO items, formatted and -collected into a single place. - -@table @kbd -@kindex C-c a t -@item C-c a t -Show the global TODO list. This collects the TODO items from all -agenda files (@pxref{Agenda Views}) into a single buffer. The buffer is in -@code{agenda-mode}, so there are commands to examine and manipulate -the TODO entries directly from that buffer (@pxref{Agenda commands}). -@kindex C-c a T -@item C-c a T -@cindex TODO keyword matching -Like the above, but allows selection of a specific TODO keyword. You -can also do this by specifying a prefix argument to @kbd{C-c a t}. With -a @kbd{C-u} prefix you are prompted for a keyword, and you may also -specify several keywords by separating them with @samp{|} as boolean OR -operator. With a numeric prefix, the Nth keyword in -@code{org-todo-keywords} is selected. -@kindex r -The @kbd{r} key in the agenda buffer regenerates it, and you can give -a prefix argument to this command to change the selected TODO keyword, -for example @kbd{3 r}. If you often need a search for a specific -keyword, define a custom command for it (@pxref{Agenda dispatcher}).@* -Matching specific TODO keywords can also be done as part of a tags -search (@pxref{Tag searches}). -@end table - -Remote editing of TODO items means that you can change the state of a -TODO entry with a single key press. The commands available in the -TODO list are described in @ref{Agenda commands}. - -@cindex sublevels, inclusion into TODO list -Normally the global TODO list simply shows all headlines with TODO -keywords. This list can become very long. There are two ways to keep -it more compact: -@itemize @minus -@item -Some people view a TODO item that has been @emph{scheduled} for -execution (@pxref{Timestamps}) as no longer @emph{open}. Configure the -variable @code{org-agenda-todo-ignore-scheduled} to exclude scheduled -items from the global TODO list. -@item -TODO items may have sublevels to break up the task into subtasks. In -such cases it may be enough to list only the highest level TODO headline -and omit the sublevels from the global list. Configure the variable -@code{org-agenda-todo-list-sublevels} to get this behavior. -@end itemize - -@node Matching tags and properties, Timeline, Global TODO list, Built-in agenda views -@subsection Matching tags and properties -@cindex matching, of tags -@cindex matching, of properties -@cindex tags view -@cindex match view - -If headlines in the agenda files are marked with @emph{tags} -(@pxref{Tags}), you can select headlines based on the tags that apply -to them and collect them into an agenda buffer. - -@table @kbd -@kindex C-c a m -@item C-c a m -Produce a list of all headlines that match a given set of tags. The -command prompts for a selection criterion, which is a boolean logic -expression with tags, like @samp{+work+urgent-withboss} or -@samp{work|home} (@pxref{Tags}). If you often need a specific search, -define a custom command for it (@pxref{Agenda dispatcher}). -@kindex C-c a M -@item C-c a M -Like @kbd{C-c a m}, but only select headlines that are also TODO items -and force checking subitems (see variable -@code{org-tags-match-list-sublevels}). Matching specific TODO keywords -together with a tags match is also possible, see @ref{Tag searches}. -@end table - -The commands available in the tags list are described in @ref{Agenda -commands}. - -@node Timeline, Keyword search, Matching tags and properties, Built-in agenda views -@subsection Timeline for a single file -@cindex timeline, single file -@cindex time-sorted view - -The timeline summarizes all time-stamped items from a single Org mode -file in a @emph{time-sorted view}. The main purpose of this command is -to give an overview over events in a project. - -@table @kbd -@kindex C-c a L -@item C-c a L -Show a time-sorted view of the org file, with all time-stamped items. -When called with a @kbd{C-u} prefix, all unfinished TODO entries -(scheduled or not) are also listed under the current date. -@end table - -@noindent -The commands available in the timeline buffer are listed in -@ref{Agenda commands}. - -@node Keyword search, Stuck projects, Timeline, Built-in agenda views -@subsection Keyword search -@cindex keyword search -@cindex searching, for keywords - -This agenda view is a general text search facility for Org mode entries. -It is particularly useful to find notes. - -@table @kbd -@kindex C-c a s -@item C-c a s -This is a special search that lets you select entries by keywords or -regular expression, using a boolean logic. For example, the search -string - -@example -+computer +wifi -ethernet -@{8\.11[bg]@} -@end example - -@noindent -will search for note entries that contain the keywords @code{computer} -and @code{wifi}, but not the keyword @code{ethernet}, and which are also -not matched by the regular expression @code{8\.11[bg]}, meaning to -exclude both 8.11b and 8.11g. - -Note that in addition to the agenda files, this command will also search -the files listed in @code{org-agenda-text-search-extra-files}. -@end table - -@node Stuck projects, , Keyword search, Built-in agenda views -@subsection Stuck projects - -If you are following a system like David Allen's GTD to organize your -work, one of the ``duties'' you have is a regular review to make sure -that all projects move along. A @emph{stuck} project is a project that -has no defined next actions, so it will never show up in the TODO lists -Org mode produces. During the review, you need to identify such -projects and define next actions for them. - -@table @kbd -@kindex C-c a # -@item C-c a # -List projects that are stuck. -@kindex C-c a ! -@item C-c a ! -Customize the variable @code{org-stuck-projects} to define what a stuck -project is and how to find it. -@end table - -You almost certainly will have to configure this view before it will -work for you. The built-in default assumes that all your projects are -level-2 headlines, and that a project is not stuck if it has at least -one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. - -Let's assume that you, in your own way of using Org mode, identify -projects with a tag PROJECT, and that you use a TODO keyword MAYBE to -indicate a project that should not be considered yet. Let's further -assume that the TODO keyword DONE marks finished projects, and that NEXT -and TODO indicate next actions. The tag @@SHOP indicates shopping and -is a next action even without the NEXT tag. Finally, if the project -contains the special word IGNORE anywhere, it should not be listed -either. In this case you would start by identifying eligible projects -with a tags/todo match @samp{+PROJECT/-MAYBE-DONE}, and then check for -TODO, NEXT, @@SHOP, and IGNORE in the subtree to identify projects that -are not stuck. The correct customization for this is - -@lisp -(setq org-stuck-projects - '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP") - "\\")) -@end lisp - - -@node Presentation and sorting, Agenda commands, Built-in agenda views, Agenda Views -@section Presentation and sorting -@cindex presentation, of agenda items - -Before displaying items in an agenda view, Org mode visually prepares -the items and sorts them. Each item occupies a single line. The line -starts with a @emph{prefix} that contains the @emph{category} -(@pxref{Categories}) of the item and other important information. You can -customize the prefix using the option @code{org-agenda-prefix-format}. -The prefix is followed by a cleaned-up version of the outline headline -associated with the item. - -@menu -* Categories:: Not all tasks are equal -* Time-of-day specifications:: How the agenda knows the time -* Sorting of agenda items:: The order of things -@end menu - -@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting -@subsection Categories - -@cindex category -The category is a broad label assigned to each agenda item. By default, -the category is simply derived from the file name, but you can also -specify it with a special line in the buffer, like this@footnote{For -backward compatibility, the following also works: If there are several -such lines in a file, each specifies the category for the text below it. -The first category also applies to any text before the first CATEGORY -line. However, using this method is @emph{strongly} deprecated as it is -incompatible with the outline structure of the document. The correct -method for setting multiple categories in a buffer is using a -property.}: - -@example -#+CATEGORY: Thesis -@end example - -@noindent -If you would like to have a special CATEGORY for a single entry or a -(sub)tree, give the entry a @code{:CATEGORY:} property with the -special category you want to apply as the value. - -@noindent -The display in the agenda buffer looks best if the category is not -longer than 10 characters. - -@node Time-of-day specifications, Sorting of agenda items, Categories, Presentation and sorting -@subsection Time-of-day specifications -@cindex time-of-day specification - -Org mode checks each agenda item for a time-of-day specification. The -time can be part of the time stamp that triggered inclusion into the -agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time -ranges can be specified with two time stamps, like -@c -@w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}. - -In the headline of the entry itself, a time(range) may also appear as -plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda -integrates the Emacs diary (@pxref{Weekly/daily agenda}), time -specifications in diary entries are recognized as well. - -For agenda display, Org mode extracts the time and displays it in a -standard 24 hour format as part of the prefix. The example times in -the previous paragraphs would end up in the agenda like this: - -@example - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 19:00...... The Vogon reads his poem - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge -@end example - -@cindex time grid -If the agenda is in single-day mode, or for the display of today, the -timed entries are embedded in a time grid, like - -@example - 8:00...... ------------------ - 8:30-13:00 Arthur Dent lies in front of the bulldozer - 10:00...... ------------------ - 12:00...... ------------------ - 12:45...... Ford Prefect arrives and takes Arthur to the pub - 14:00...... ------------------ - 16:00...... ------------------ - 18:00...... ------------------ - 19:00...... The Vogon reads his poem - 20:00...... ------------------ - 20:30-22:15 Marvin escorts the Hitchhikers to the bridge -@end example - -The time grid can be turned on and off with the variable -@code{org-agenda-use-time-grid}, and can be configured with -@code{org-agenda-time-grid}. - -@node Sorting of agenda items, , Time-of-day specifications, Presentation and sorting -@subsection Sorting of agenda items -@cindex sorting, of agenda items -@cindex priorities, of agenda items -Before being inserted into a view, the items are sorted. How this is -done depends on the type of view. -@itemize @bullet -@item -For the daily/weekly agenda, the items for each day are sorted. The -default order is to first collect all items containing an explicit -time-of-day specification. These entries will be shown at the beginning -of the list, as a @emph{schedule} for the day. After that, items remain -grouped in categories, in the sequence given by @code{org-agenda-files}. -Within each category, items are sorted by priority (@pxref{Priorities}), -which is composed of the base priority (2000 for priority @samp{A}, 1000 -for @samp{B}, and 0 for @samp{C}), plus additional increments for -overdue scheduled or deadline items. -@item -For the TODO list, items remain in the order of categories, but within -each category, sorting takes place according to priority -(@pxref{Priorities}). -@item -For tags matches, items are not sorted at all, but just appear in the -sequence in which they are found in the agenda files. -@end itemize - -Sorting can be customized using the variable -@code{org-agenda-sorting-strategy}, and may also include criteria based on -the estimated effort of an entry (@pxref{Effort estimates}). - -@node Agenda commands, Custom agenda views, Presentation and sorting, Agenda Views -@section Commands in the agenda buffer -@cindex commands, in agenda buffer - -Entries in the agenda buffer are linked back to the org file or diary -file where they originate. You are not allowed to edit the agenda -buffer itself, but commands are provided to show and jump to the -original entry location, and to edit the org-files ``remotely'' from -the agenda buffer. In this way, all information is stored only once, -removing the risk that your agenda and note files may diverge. - -Some commands can be executed with mouse clicks on agenda lines. For -the other commands, the cursor needs to be in the desired line. - -@table @kbd -@tsubheading{Motion} -@cindex motion commands in agenda -@kindex n -@item n -Next line (same as @key{up} and @kbd{C-p}). -@kindex p -@item p -Previous line (same as @key{down} and @kbd{C-n}). -@tsubheading{View/Go to org file} -@kindex mouse-3 -@kindex @key{SPC} -@item mouse-3 -@itemx @key{SPC} -Display the original location of the item in another window. -With prefix arg, make sure that the entire entry is made visible in the -outline, not only the heading. -@c -@kindex L -@item L -Display original location and recenter that window. -@c -@kindex mouse-2 -@kindex mouse-1 -@kindex @key{TAB} -@item mouse-2 -@itemx mouse-1 -@itemx @key{TAB} -Go to the original location of the item in another window. Under Emacs -22, @kbd{mouse-1} will also works for this. -@c -@kindex @key{RET} -@itemx @key{RET} -Go to the original location of the item and delete other windows. -@c -@kindex f -@item f -Toggle Follow mode. In Follow mode, as you move the cursor through -the agenda buffer, the other window always shows the corresponding -location in the org file. The initial setting for this mode in new -agenda buffers can be set with the variable -@code{org-agenda-start-with-follow-mode}. -@c -@kindex b -@item b -Display the entire subtree of the current item in an indirect buffer. With a -numeric prefix argument N, go up to level N and then take that tree. If N is -negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the -previously used indirect buffer. -@c -@kindex l -@item l -Toggle Logbook mode. In Logbook mode, entries that were marked DONE while -logging was on (variable @code{org-log-done}) are shown in the agenda, as are -entries that have been clocked on that day. You can configure the entry -types that should be included in log mode using the variable -@code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show -all possible logbook entries, including state changes. When called with two -prefix args @kbd{C-u C-u}, show only logging information, nothing else. -@c -@kindex v -@item v -Toggle Archives mode. In archives mode, trees that are marked -@code{ARCHIVED} are also scanned when producing the agenda. When you call -this command with a @kbd{C-u} prefix argument, even all archive files are -included. To exit archives mode, press @kbd{v} again. -@c -@kindex R -@item R -Toggle Clockreport mode. In clockreport mode, the daily/weekly agenda will -always show a table with the clocked times for the timespan and file scope -covered by the current agenda view. The initial setting for this mode in new -agenda buffers can be set with the variable -@code{org-agenda-start-with-clockreport-mode}. - -@tsubheading{Change display} -@cindex display changing, in agenda -@kindex o -@item o -Delete other windows. -@c -@kindex d -@kindex w -@kindex m -@kindex y -@item d w m y -Switch to day/week/month/year view. When switching to day or week view, -this setting becomes the default for subsequent agenda commands. Since -month and year views are slow to create, they do not become the default. -A numeric prefix argument may be used to jump directly to a specific day -of the year, ISO week, month, or year, respectively. For example, -@kbd{32 d} jumps to February 1st, @kbd{9 w} to ISO week number 9. When -setting day, week, or month view, a year may be encoded in the prefix -argument as well. For example, @kbd{200712 w} will jump to week 12 in -2007. If such a year specification has only one or two digits, it will -be mapped to the interval 1938-2037. -@c -@kindex D -@item D -Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}. -@c -@kindex G -@item G -Toggle the time grid on and off. See also the variables -@code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}. -@c -@kindex r -@item r -Recreate the agenda buffer, for example to reflect the changes after -modification of the time stamps of items with @kbd{S-@key{left}} and -@kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix -argument is interpreted to create a selective list for a specific TODO -keyword. -@kindex g -@item g -Same as @kbd{r}. -@c -@kindex s -@kindex C-x C-s -@item s -@itemx C-x C-s -Save all Org buffers in the current Emacs session. -@c -@kindex @key{right} -@item @key{right} -Display the following @code{org-agenda-ndays} days. For example, if -the display covers a week, switch to the following week. With prefix -arg, go forward that many times @code{org-agenda-ndays} days. -@c -@kindex @key{left} -@item @key{left} -Display the previous dates. -@c -@kindex . -@item . -Go to today. -@c -@kindex C-c C-x C-c -@item C-c C-x C-c -Invoke column view (@pxref{Column view}) in the agenda buffer. The column -view format is taken from the entry at point, or (if there is no entry at -point), from the first entry in the agenda view. So whatever the format for -that entry would be in the original buffer (taken from a property, from a -@code{#+COLUMNS} line, or from the default variable -@code{org-columns-default-format}), will be used in the agenda. - -@tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag and effort, in agenda -@cindex tag filtering, in agenda -@cindex effort filtering, in agenda -@cindex query editing, in agenda - -@kindex / -@item / -Filter the current agenda view with respect to a tag and/or effort estimates. -The difference between this and a custom agenda commands is that filtering is -very fast, so that you can switch quickly between different filters without -having to recreate the agenda. - -You will be prompted for a tag selection letter. Pressing @key{TAB} at that -prompt will offer use completion to select a tag (including any tags that do -not have a selection character). The command then hides all entries that do -not contain or inherit this tag. When called with prefix arg, remove the -entries that @emph{do} have the tag. A second @kbd{/} at the prompt will -turn off the filter and unhide any hidden entries. If the first key you -press is either @kbd{+} or @kbd{-}, the previous filter will be narrowed by -requiring or forbidding the selected additional tag. Instead of pressing -@kbd{+} or @kbd{-} after @kbd{/}, you can also immediately use the @kbd{\} -command. - -In order to filter for effort estimates, you should set-up allowed -efforts globally, for example -@lisp -(setq org-global-properties - '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00"))) -@end lisp -You can then filter for an effort by first typing an operator, one of @kbd{<}, -@kbd{>}, and @kbd{=}, and then the one-digit index of an effort estimate in -your array of allowed values, where @kbd{0} means the 10th value. The filter -will then restrict to entries with effort smaller-or-equal, equal, or -larger-or-equal than the selected value. If the digits 0-9 are not used as -fast access keys to tags, you can also simply press the index digit directly -without an operator. In this case, @kbd{<} will be assumed. - -@kindex \ -@item \ -Narrow the current agenda filter by an additional condition. When called with -prefix arg, remove the entries that @emph{do} have the tag, or that do match -the effort criterion. You can achieve the same effect by pressing @kbd{+} or -@kbd{-} as the first key after the @kbd{/} command. - -@kindex [ -@kindex ] -@kindex @{ -@kindex @} -@item [ ] @{ @} -In the @i{search view} (@pxref{Keyword search}), these keys add new search -words (@kbd{[} and @kbd{]}) or new regular expressions (@kbd{@{} and -@kbd{@}}) to the query string. The opening bracket/brace will add a positive -search term prefixed by @samp{+}, indicating that this search term @i{must} -occur/match in the entry. The closing bracket/brace will add a negative -search term which @i{must not} occur/match in the entry for it to be -selected. - - -@tsubheading{Remote editing} -@cindex remote editing, from agenda - -@item 0-9 -Digit argument. -@c -@cindex undoing remote-editing events -@cindex remote editing, undo -@kindex C-_ -@item C-_ -Undo a change due to a remote editing command. The change is undone -both in the agenda buffer and in the remote buffer. -@c -@kindex t -@item t -Change the TODO state of the item, both in the agenda and in the -original org file. -@c -@kindex C-k -@item C-k -Delete the current agenda item along with the entire subtree belonging -to it in the original Org file. If the text to be deleted remotely -is longer than one line, the kill needs to be confirmed by the user. See -variable @code{org-agenda-confirm-kill}. -@c -@kindex a -@item a -Toggle the ARCHIVE tag for the current headline. -@c -@kindex A -@item A -Move the subtree corresponding to the current entry to its @emph{Archive -Sibling}. -@c -@kindex $ -@item $ -Archive the subtree corresponding to the current headline. This means the -entry will be moved to the configured archive location, most likely a -different file. -@c -@kindex T -@item T -Show all tags associated with the current item. This is useful if you have -turned off @code{org-agenda-show-inherited-tags}, but still want to see all -tags of a headline occasionally. -@c -@kindex : -@item : -Set tags for the current headline. If there is an active region in the -agenda, change a tag for all headings in the region. -@c -@kindex , -@item , -Set the priority for the current item. Org mode prompts for the -priority character. If you reply with @key{SPC}, the priority cookie -is removed from the entry. -@c -@kindex P -@item P -Display weighted priority of current item. -@c -@kindex + -@kindex S-@key{up} -@item + -@itemx S-@key{up} -Increase the priority of the current item. The priority is changed in -the original buffer, but the agenda is not resorted. Use the @kbd{r} -key for this. -@c -@kindex - -@kindex S-@key{down} -@item - -@itemx S-@key{down} -Decrease the priority of the current item. -@c -@kindex C-c C-a -@item C-c C-a -Dispatcher for all command related to attachments. -@c -@kindex C-c C-s -@item C-c C-s -Schedule this item -@c -@kindex C-c C-d -@item C-c C-d -Set a deadline for this item. -@c -@kindex k -@item k -Agenda actions, to set dates for selected items to the cursor date. -This command also works in the calendar! The command prompts for an -additional key: -@example -m @r{Mark the entry at point for action. You can also make entries} - @r{in Org files with @kbd{C-c C-x C-k}.} -d @r{Set the deadline of the marked entry to the date at point.} -s @r{Schedule the marked entry at the date at point.} -r @r{Call @code{org-remember} with the cursor date as default date.} -@end example -Press @kbd{r} afterward to refresh the agenda and see the effect of the -command. -@c -@kindex S-@key{right} -@item S-@key{right} -Change the time stamp associated with the current line by one day into the -future. With a numeric prefix argument, change it by that many days. For -example, @kbd{3 6 5 S-@key{right}} will change it by a year. The stamp is -changed in the original org file, but the change is not directly reflected in -the agenda buffer. Use the @kbd{r} key to update the buffer. -@c -@kindex S-@key{left} -@item S-@key{left} -Change the time stamp associated with the current line by one day -into the past. -@c -@kindex > -@item > -Change the time stamp associated with the current line to today. -The key @kbd{>} has been chosen, because it is the same as @kbd{S-.} -on my keyboard. -@c -@kindex I -@item I -Start the clock on the current item. If a clock is running already, it -is stopped first. -@c -@kindex O -@item O -Stop the previously started clock. -@c -@kindex X -@item X -Cancel the currently running clock. - -@kindex J -@item J -Jump to the running clock in another window. - -@tsubheading{Calendar commands} -@cindex calendar commands, from agenda -@kindex c -@item c -Open the Emacs calendar and move to the date at the agenda cursor. -@c -@item c -When in the calendar, compute and show the Org mode agenda for the -date at the cursor. -@c -@cindex diary entries, creating from agenda -@kindex i -@item i -Insert a new entry into the diary. Prompts for the type of entry -(day, weekly, monthly, yearly, anniversary, cyclic) and creates a new -entry in the diary, just as @kbd{i d} etc. would do in the calendar. -The date is taken from the cursor position. -@c -@kindex M -@item M -Show the phases of the moon for the three months around current date. -@c -@kindex S -@item S -Show sunrise and sunset times. The geographical location must be set -with calendar variables, see documentation of the Emacs calendar. -@c -@kindex C -@item C -Convert the date at cursor into many other cultural and historic -calendars. -@c -@kindex H -@item H -Show holidays for three month around the cursor date. - -@item M-x org-export-icalendar-combine-agenda-files -Export a single iCalendar file containing entries from all agenda files. -This is a globally available command, and also available in the agenda menu. - -@tsubheading{Exporting to a file} -@kindex C-x C-w -@item C-x C-w -@cindex exporting agenda views -@cindex agenda views, exporting -Write the agenda view to a file. Depending on the extension of the -selected file name, the view will be exported as HTML (extension -@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), or -plain text (any other extension). Use the variable -@code{org-agenda-exporter-settings} to set options for @file{ps-print} -and for @file{htmlize} to be used during export. - -@tsubheading{Quit and Exit} -@kindex q -@item q -Quit agenda, remove the agenda buffer. -@c -@kindex x -@cindex agenda files, removing buffers -@item x -Exit agenda, remove the agenda buffer and all buffers loaded by Emacs -for the compilation of the agenda. Buffers created by the user to -visit org files will not be removed. -@end table - - -@node Custom agenda views, Agenda column view, Agenda commands, Agenda Views -@section Custom agenda views -@cindex custom agenda views -@cindex agenda views, custom - -Custom agenda commands serve two purposes: to store and quickly access -frequently used TODO and tags searches, and to create special composite -agenda buffers. Custom agenda commands will be accessible through the -dispatcher (@pxref{Agenda dispatcher}), just like the default commands. - -@menu -* Storing searches:: Type once, use often -* Block agenda:: All the stuff you need in a single buffer -* Setting Options:: Changing the rules -* Exporting Agenda Views:: Writing agendas to files -* Using the agenda elsewhere:: Using agenda information in other programs -@end menu - -@node Storing searches, Block agenda, Custom agenda views, Custom agenda views -@subsection Storing searches - -The first application of custom searches is the definition of keyboard -shortcuts for frequently used searches, either creating an agenda -buffer, or a sparse tree (the latter covering of course only the current -buffer). -@kindex C-c a C -Custom commands are configured in the variable -@code{org-agenda-custom-commands}. You can customize this variable, for -example by pressing @kbd{C-c a C}. You can also directly set it with -Emacs Lisp in @file{.emacs}. The following example contains all valid -search types: - -@lisp -@group -(setq org-agenda-custom-commands - '(("w" todo "WAITING") - ("W" todo-tree "WAITING") - ("u" tags "+boss-urgent") - ("v" tags-todo "+boss-urgent") - ("U" tags-tree "+boss-urgent") - ("f" occur-tree "\\") - ("h" . "HOME+Name tags searches") ; description for "h" prefix - ("hl" tags "+home+Lisa") - ("hp" tags "+home+Peter") - ("hk" tags "+home+Kim"))) -@end group -@end lisp - -@noindent -The initial string in each entry defines the keys you have to press -after the dispatcher command @kbd{C-c a} in order to access the command. -Usually this will be just a single character, but if you have many -similar commands, you can also define two-letter combinations where the -first character is the same in several combinations and serves as a -prefix key@footnote{You can provide a description for a prefix key by -inserting a cons cell with the prefix and the description.}. The second -parameter is the search type, followed by the string or regular -expression to be used for the matching. The example above will -therefore define: - -@table @kbd -@item C-c a w -as a global search for TODO entries with @samp{WAITING} as the TODO -keyword -@item C-c a W -as the same search, but only in the current buffer and displaying the -results as a sparse tree -@item C-c a u -as a global tags search for headlines marked @samp{:boss:} but not -@samp{:urgent:} -@item C-c a v -as the same search as @kbd{C-c a u}, but limiting the search to -headlines that are also TODO items -@item C-c a U -as the same search as @kbd{C-c a u}, but only in the current buffer and -displaying the result as a sparse tree -@item C-c a f -to create a sparse tree (again: current buffer only) with all entries -containing the word @samp{FIXME} -@item C-c a h -as a prefix command for a HOME tags search where you have to press an -additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa, -Peter, or Kim) as additional tag to match. -@end table - -@node Block agenda, Setting Options, Storing searches, Custom agenda views -@subsection Block agenda -@cindex block agenda -@cindex agenda, with block views - -Another possibility is the construction of agenda views that comprise -the results of @emph{several} commands, each of which creates a block in -the agenda buffer. The available commands include @code{agenda} for the -daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo} -for the global TODO list (as constructed with @kbd{C-c a t}), and the -matching commands discussed above: @code{todo}, @code{tags}, and -@code{tags-todo}. Here are two examples: - -@lisp -@group -(setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden"))) - ("o" "Agenda and Office-related tasks" - ((agenda "") - (tags-todo "work") - (tags "office"))))) -@end group -@end lisp - -@noindent -This will define @kbd{C-c a h} to create a multi-block view for stuff -you need to attend to at home. The resulting agenda buffer will contain -your agenda for the current week, all TODO items that carry the tag -@samp{home}, and also all lines tagged with @samp{garden}. Finally the -command @kbd{C-c a o} provides a similar view for office tasks. - -@node Setting Options, Exporting Agenda Views, Block agenda, Custom agenda views -@subsection Setting options for custom commands -@cindex options, for custom agenda views - -Org mode contains a number of variables regulating agenda construction -and display. The global variables define the behavior for all agenda -commands, including the custom commands. However, if you want to change -some settings just for a single custom view, you can do so. Setting -options requires inserting a list of variable names and values at the -right spot in @code{org-agenda-custom-commands}. For example: - -@lisp -@group -(setq org-agenda-custom-commands - '(("w" todo "WAITING" - ((org-agenda-sorting-strategy '(priority-down)) - (org-agenda-prefix-format " Mixed: "))) - ("U" tags-tree "+boss-urgent" - ((org-show-following-heading nil) - (org-show-hierarchy-above nil))) - ("N" search "" - ((org-agenda-files '("~org/notes.org")) - (org-agenda-text-search-extra-files nil))))) -@end group -@end lisp - -@noindent -Now the @kbd{C-c a w} command will sort the collected entries only by -priority, and the prefix format is modified to just say @samp{ Mixed: } -instead of giving the category of the entry. The sparse tags tree of -@kbd{C-c a U} will now turn out ultra-compact, because neither the -headline hierarchy above the match, nor the headline following the match -will be shown. The command @kbd{C-c a N} will do a text search limited -to only a single file. - -For command sets creating a block agenda, -@code{org-agenda-custom-commands} has two separate spots for setting -options. You can add options that should be valid for just a single -command in the set, and options that should be valid for all commands in -the set. The former are just added to the command entry, the latter -must come after the list of command entries. Going back to the block -agenda example (@pxref{Block agenda}), let's change the sorting strategy -for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort -the results for GARDEN tags query in the opposite order, -@code{priority-up}. This would look like this: - -@lisp -@group -(setq org-agenda-custom-commands - '(("h" "Agenda and Home-related tasks" - ((agenda) - (tags-todo "home") - (tags "garden" - ((org-agenda-sorting-strategy '(priority-up))))) - ((org-agenda-sorting-strategy '(priority-down)))) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office"))))) -@end group -@end lisp - -As you see, the values and parenthesis setting is a little complex. -When in doubt, use the customize interface to set this variable - it -fully supports its structure. Just one caveat: When setting options in -this interface, the @emph{values} are just lisp expressions. So if the -value is a string, you need to add the double quotes around the value -yourself. - - -@node Exporting Agenda Views, Using the agenda elsewhere, Setting Options, Custom agenda views -@subsection Exporting Agenda Views -@cindex agenda views, exporting - -If you are away from your computer, it can be very useful to have a printed -version of some agenda views to carry around. Org mode can export custom -agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's -@file{htmlize.el}.}, Postscript, and iCalendar files. If you want to do this -only occasionally, use the command - -@table @kbd -@kindex C-x C-w -@item C-x C-w -@cindex exporting agenda views -@cindex agenda views, exporting -Write the agenda view to a file. Depending on the extension of the -selected file name, the view will be exported as HTML (extension -@file{.html} or @file{.htm}), Postscript (extension @file{.ps}), -iCalendar (extension @file{.ics}), or plain text (any other extension). -Use the variable @code{org-agenda-exporter-settings} to -set options for @file{ps-print} and for @file{htmlize} to be used during -export, for example - -@lisp -(setq org-agenda-exporter-settings - '((ps-number-of-columns 2) - (ps-landscape-mode t) - (htmlize-output-type 'css))) -@end lisp -@end table - -If you need to export certain agenda views frequently, you can associate -any custom agenda command with a list of output file names -@footnote{If you want to store standard views like the weekly agenda -or the global TODO list as well, you need to define custom commands for -them in order to be able to specify file names.}. Here is an example -that first does define custom commands for the agenda and the global -todo list, together with a number of files to which to export them. -Then we define two block agenda commands and specify file names for them -as well. File names can be relative to the current working directory, -or absolute. - -@lisp -@group -(setq org-agenda-custom-commands - '(("X" agenda "" nil ("agenda.html" "agenda.ps")) - ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps")) - ("h" "Agenda and Home-related tasks" - ((agenda "") - (tags-todo "home") - (tags "garden")) - nil - ("~/views/home.html")) - ("o" "Agenda and Office-related tasks" - ((agenda) - (tags-todo "work") - (tags "office")) - nil - ("~/views/office.ps" "~/calendars/office.ics")))) -@end group -@end lisp - -The extension of the file name determines the type of export. If it is -@file{.html}, Org mode will use the @file{htmlize.el} package to convert -the buffer to HTML and save it to this file name. If the extension is -@file{.ps}, @code{ps-print-buffer-with-faces} is used to produce -postscript output. If the extension is @file{.ics}, iCalendar export is -run export over all files that were used to construct the agenda, and -limit the export to entries listed in the agenda now. Any other -extension produces a plain ASCII file. - -The export files are @emph{not} created when you use one of those -commands interactively because this might use too much overhead. -Instead, there is a special command to produce @emph{all} specified -files in one step: - -@table @kbd -@kindex C-c a e -@item C-c a e -Export all agenda views that have export file names associated with -them. -@end table - -You can use the options section of the custom agenda commands to also -set options for the export commands. For example: - -@lisp -(setq org-agenda-custom-commands - '(("X" agenda "" - ((ps-number-of-columns 2) - (ps-landscape-mode t) - (org-agenda-prefix-format " [ ] ") - (org-agenda-with-colors nil) - (org-agenda-remove-tags t)) - ("theagenda.ps")))) -@end lisp - -@noindent -This command sets two options for the postscript exporter, to make it -print in two columns in landscape format - the resulting page can be cut -in two and then used in a paper agenda. The remaining settings modify -the agenda prefix to omit category and scheduling information, and -instead include a checkbox to check off items. We also remove the tags -to make the lines compact, and we don't want to use colors for the -black-and-white printer. Settings specified in -@code{org-agenda-exporter-settings} will also apply, but the settings -in @code{org-agenda-custom-commands} take precedence. - -@noindent -From the command line you may also use -@example -emacs -f org-batch-store-agenda-views -kill -@end example -@noindent -or, if you need to modify some parameters@footnote{Quoting may depend on the -system you use, please check th FAQ for examples.} -@example -emacs -eval '(org-batch-store-agenda-views \ - org-agenda-ndays 30 \ - org-agenda-start-day "2007-11-01" \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - -kill -@end example -@noindent -which will create the agenda views restricted to the file -@file{~/org/project.org}, without diary entries and with 30 days -extent. - -@node Using the agenda elsewhere, , Exporting Agenda Views, Custom agenda views -@subsection Using agenda information outside of Org -@cindex agenda, pipe -@cindex Scripts, for agenda processing - -Org provides commands to access agenda information for the command -line in emacs batch mode. This extracted information can be sent -directly to a printer, or it can be read by a program that does further -processing of the data. The first of these commands is the function -@code{org-batch-agenda}, that produces an agenda view and sends it as -ASCII text to STDOUT. The command takes a single string as parameter. -If the string has length 1, it is used as a key to one of the commands -you have configured in @code{org-agenda-custom-commands}, basically any -key you can use after @kbd{C-c a}. For example, to directly print the -current TODO list, you could use - -@example -emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr -@end example - -If the parameter is a string with 2 or more characters, it is used as a -tags/todo match string. For example, to print your local shopping list -(all items with the tag @samp{shop}, but excluding the tag -@samp{NewYork}), you could use - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "+shop-NewYork")' | lpr -@end example - -@noindent -You may also modify parameters on the fly like this: - -@example -emacs -batch -l ~/.emacs \ - -eval '(org-batch-agenda "a" \ - org-agenda-ndays 30 \ - org-agenda-include-diary nil \ - org-agenda-files (quote ("~/org/project.org")))' \ - | lpr -@end example - -@noindent -which will produce a 30 day agenda, fully restricted to the Org file -@file{~/org/projects.org}, not even including the diary. - -If you want to process the agenda data in more sophisticated ways, you -can use the command @code{org-batch-agenda-csv} to get a comma-separated -list of values for each agenda item. Each line in the output will -contain a number of fields separated by commas. The fields in a line -are: - -@example -category @r{The category of the item} -head @r{The headline, without TODO kwd, TAGS and PRIORITY} -type @r{The type of the agenda entry, can be} - todo @r{selected in TODO match} - tagsmatch @r{selected in tags match} - diary @r{imported from diary} - deadline @r{a deadline} - scheduled @r{scheduled} - timestamp @r{appointment, selected by timestamp} - closed @r{entry was closed on date} - upcoming-deadline @r{warning about nearing deadline} - past-scheduled @r{forwarded scheduled item} - block @r{entry has date block including date} -todo @r{The TODO keyword, if any} -tags @r{All tags including inherited ones, separated by colons} -date @r{The relevant date, like 2007-2-14} -time @r{The time, like 15:00-16:50} -extra @r{String with extra planning info} -priority-l @r{The priority letter if any was given} -priority-n @r{The computed numerical priority} -@end example - -@noindent -Time and date will only be given if a timestamp (or deadline/scheduled) -lead to the selection of the item. - -A CSV list like this is very easy to use in a post processing script. -For example, here is a Perl program that gets the TODO list from -Emacs/Org and prints all the items, preceded by a checkbox: - -@example -@group -#!/usr/bin/perl - -# define the Emacs command to run -$cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'"; - -# run it and capture the output -$agenda = qx@{$cmd 2>/dev/null@}; - -# loop over all lines -foreach $line (split(/\n/,$agenda)) @{ - - # get the individual values - ($category,$head,$type,$todo,$tags,$date,$time,$extra, - $priority_l,$priority_n) = split(/,/,$line); - - # process and print - print "[ ] $head\n"; -@} -@end group -@end example - -@node Agenda column view, , Custom agenda views, Agenda Views -@section Using column view in the agenda -@cindex column view, in agenda -@cindex agenda, column view - -Column view (@pxref{Column view}) is normally used to view and edit -properties embedded in the hierarchical structure of an Org file. It can be -quite useful to use column view also from the agenda, where entries are -collected by certain criteria. - -@table @kbd -@kindex C-c C-x C-c -@item C-c C-x C-c -Turn on column view in the agenda. -@end table - -To understand how to use this properly, it is important to realize that the -entries in the agenda are no longer in their proper outline environment. -This causes the following issues: - -@enumerate -@item -Org needs to make a decision which @code{COLUMNS} format to use. Since the -entries in the agenda are collected from different files, and different files -may have different @code{COLUMNS} formats, this is a non-trivial problem. -Org first checks if the variable @code{org-overriding-columns-format} is -currently set, and if yes takes the format from there. Otherwise it takes -the format associated with the first item in the agenda, or, if that item -does not have a specific format (defined in a property, or in it's file), it -uses @code{org-columns-default-format}. -@item -If any of the columns has a summary type defined (@pxref{Column attributes}), -turning on column view in the agenda will visit all relevant agenda files and -make sure that the computations of this property are up to date. This is -also true for the special @code{CLOCKSUM} property. Org will then sum the -values displayed in the agenda. In the daily/weekly agenda, the sums will -cover a single day, in all other views they cover the entire block. It is -vital to realize that the agenda may show the same entry @emph{twice} (for -example as scheduled and as a deadline), and it may show two entries from the -same hierarchy (for example a @emph{parent} and it's @emph{child}). In these -cases, the summation in the agenda will lead to incorrect results because -some values will count double. -@item -When the column view in the agenda shows the @code{CLOCKSUM}, that is always -the entire clocked time for this item. So even in the daily/weekly agenda, -the clocksum listed in column view may originate from times outside the -current view. This has the advantage that you can compare these values with -a column listing the planned total effort for a task - one of the major -applications for column view in the agenda. If you want information about -clocked time in the displayed period use clock table mode (press @kbd{R} in -the agenda). -@end enumerate - - -@node Embedded LaTeX, Exporting, Agenda Views, Top -@chapter Embedded LaTeX -@cindex @TeX{} interpretation -@cindex La@TeX{} interpretation - -Plain ASCII is normally sufficient for almost all note taking. One -exception, however, are scientific notes which need to be able to contain -mathematical symbols and the occasional formula. La@TeX{}@footnote{La@TeX{} -is a macro system based on Donald E. Knuth's @TeX{} system. Many of the -features described here as ``La@TeX{}'' are really from @TeX{}, but for -simplicity I am blurring this distinction.} is widely used to typeset -scientific documents. Org mode supports embedding La@TeX{} code into its -files, because many academics are used to reading La@TeX{} source code, and -because it can be readily processed into images for HTML production. - -It is not necessary to mark La@TeX{} macros and code in any special way. -If you observe a few conventions, Org mode knows how to find it and what -to do with it. - -@menu -* Math symbols:: TeX macros for symbols and Greek letters -* Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Processing LaTeX fragments:: Previewing LaTeX processing -* CDLaTeX mode:: Speed up entering of formulas -@end menu - -@node Math symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX -@section Math symbols -@cindex math symbols -@cindex TeX macros - -You can use La@TeX{} macros to insert special symbols like @samp{\alpha} to -indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion -for these macros is available, just type @samp{\} and maybe a few letters, -and press @kbd{M-@key{TAB}} to see possible completions. Unlike La@TeX{} -code, Org mode allows these macros to be present without surrounding math -delimiters, for example: - -@example -Angles are written as Greek letters \alpha, \beta and \gamma. -@end example - -During HTML export (@pxref{HTML export}), these symbols are translated -into the proper syntax for HTML, for the above examples this is -@samp{α} and @samp{→}, respectively. If you need such a symbol -inside a word, terminate it like this: @samp{\Aacute@{@}stor}. - -@node Subscripts and superscripts, LaTeX fragments, Math symbols, Embedded LaTeX -@section Subscripts and superscripts -@cindex subscript -@cindex superscript - -Just like in La@TeX{}, @samp{^} and @samp{_} are used to indicate super- -and subscripts. Again, these can be used without embedding them in -math-mode delimiters. To increase the readability of ASCII text, it is -not necessary (but OK) to surround multi-character sub- and superscripts -with curly braces. For example - -@example -The mass if the sun is M_sun = 1.989 x 10^30 kg. The radius of -the sun is R_@{sun@} = 6.96 x 10^8 m. -@end example - -To avoid interpretation as raised or lowered text, you can quote -@samp{^} and @samp{_} with a backslash: @samp{\_} and @samp{\^}. - -During HTML export (@pxref{HTML export}), subscript and superscripts -are surrounded with @code{} and @code{} tags, respectively. - -@node LaTeX fragments, Processing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX -@section LaTeX fragments -@cindex LaTeX fragments - -With symbols, sub- and superscripts, HTML is pretty much at its end when -it comes to representing mathematical formulas@footnote{Yes, there is -MathML, but that is not yet fully supported by many browsers, and there -is no decent converter for turning La@TeX{} or ASCII representations of -formulas into MathML. So for the time being, converting formulas into -images seems the way to go.}. More complex expressions need a dedicated -formula processor. To this end, Org mode can contain arbitrary La@TeX{} -fragments. It provides commands to preview the typeset result of these -fragments, and upon export to HTML, all fragments will be converted to -images and inlined into the HTML document@footnote{The La@TeX{} export -will not use images for displaying La@TeX{} fragments but include these -fragments directly into the La@TeX{} code.}. For this to work you -need to be on a system with a working La@TeX{} installation. You also -need the @file{dvipng} program, available at -@url{http://sourceforge.net/projects/dvipng/}. The La@TeX{} header that -will be used when processing a fragment can be configured with the -variable @code{org-format-latex-header}. - -La@TeX{} fragments don't need any special marking at all. The following -snippets will be identified as La@TeX{} source code: -@itemize @bullet -@item -Environments of any kind. The only requirement is that the -@code{\begin} statement appears on a new line, preceded by only -whitespace. -@item -Text within the usual La@TeX{} math delimiters. To avoid conflicts with -currency specifications, single @samp{$} characters are only recognized as -math delimiters if the enclosed text contains at most two line breaks, is -directly attached to the @samp{$} characters with no whitespace in between, -and if the closing @samp{$} is followed by whitespace, punctuation or a dash. -For the other delimiters, there is no such restriction, so when in doubt, use -@samp{\(...\)} as inline math delimiters. -@end itemize - -@noindent For example: - -@example -\begin@{equation@} % arbitrary environments, -x=\sqrt@{b@} % even tables, figures -\end@{equation@} % etc - -If $a^2=b$ and \( b=2 \), then the solution must be -either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \]. -@end example - -@noindent -If you need any of the delimiter ASCII sequences for other purposes, you -can configure the option @code{org-format-latex-options} to deselect the -ones you do not wish to have interpreted by the La@TeX{} converter. - -@node Processing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX -@section Processing LaTeX fragments -@cindex LaTeX fragments, preview - -La@TeX{} fragments can be processed to produce a preview images of the -typeset expressions: - -@table @kbd -@kindex C-c C-x C-l -@item C-c C-x C-l -Produce a preview image of the La@TeX{} fragment at point and overlay it -over the source code. If there is no fragment at point, process all -fragments in the current entry (between two headlines). When called -with a prefix argument, process the entire subtree. When called with -two prefix arguments, or when the cursor is before the first headline, -process the entire buffer. -@kindex C-c C-c -@item C-c C-c -Remove the overlay preview images. -@end table - -During HTML export (@pxref{HTML export}), all La@TeX{} fragments are -converted into images and inlined into the document if the following -setting is active: - -@lisp -(setq org-export-with-LaTeX-fragments t) -@end lisp - -@node CDLaTeX mode, , Processing LaTeX fragments, Embedded LaTeX -@section Using CDLaTeX to enter math -@cindex CDLaTeX - -CDLaTeX mode is a minor mode that is normally used in combination with a -major La@TeX{} mode like AUCTeX in order to speed-up insertion of -environments and math templates. Inside Org mode, you can make use of -some of the features of CDLaTeX mode. You need to install -@file{cdlatex.el} and @file{texmathp.el} (the latter comes also with -AUCTeX) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CDLaTeX mode itself under Org mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it -on for the current buffer with @code{M-x org-cdlatex-mode}, or for all -Org files with - -@lisp -(add-hook 'org-mode-hook 'turn-on-org-cdlatex) -@end lisp - -When this mode is enabled, the following features are present (for more -details see the documentation of CDLaTeX mode): -@itemize @bullet -@kindex C-c @{ -@item -Environment templates can be inserted with @kbd{C-c @{}. -@item -@kindex @key{TAB} -The @key{TAB} key will do template expansion if the cursor is inside a -La@TeX{} fragment@footnote{Org mode has a method to test if the cursor is -inside such a fragment, see the documentation of the function -@code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will -expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor -correctly inside the first brace. Another @key{TAB} will get you into -the second brace. Even outside fragments, @key{TAB} will expand -environment abbreviations at the beginning of a line. For example, if -you write @samp{equ} at the beginning of a line and press @key{TAB}, -this abbreviation will be expanded to an @code{equation} environment. -To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help}. -@item -@kindex _ -@kindex ^ -Pressing @kbd{_} and @kbd{^} inside a La@TeX{} fragment will insert these -characters together with a pair of braces. If you use @key{TAB} to move -out of the braces, and if the braces surround only a single character or -macro, they are removed again (depending on the variable -@code{cdlatex-simplify-sub-super-scripts}). -@item -@kindex ` -Pressing the backquote @kbd{`} followed by a character inserts math -macros, also outside La@TeX{} fragments. If you wait more than 1.5 seconds -after the backquote, a help window will pop up. -@item -@kindex ' -Pressing the normal quote @kbd{'} followed by another character modifies -the symbol before point with an accent or a font. If you wait more than -1.5 seconds after the backquote, a help window will pop up. Character -modification will work only inside La@TeX{} fragments, outside the quote -is normal. -@end itemize - -@node Exporting, Publishing, Embedded LaTeX, Top -@chapter Exporting -@cindex exporting - -Org mode documents can be exported into a variety of other formats. For -printing and sharing of notes, ASCII export produces a readable and -simple version of an Org file. HTML export allows you to publish a -notes file on the web, while the XOXO format provides a solid base for -exchange with a broad range of other applications. La@TeX{} export lets -you use Org mode and its structured editing functions to easily create -La@TeX{} files. To incorporate entries with associated times like -deadlines or appointments into a desktop calendar program like iCal, -Org mode can also produce extracts in the iCalendar format. Currently -Org mode only supports export, not import of these different formats. - -Org supports export of selected regions when @code{transient-mark-mode} is -enabled (default in Emacs 23). - -@menu -* Markup rules:: Which structures are recognized? -* Selective export:: Using tags to select and exclude trees -* Export options:: Per-file export settings -* The export dispatcher:: How to access exporter commands -* ASCII export:: Exporting to plain ASCII -* HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to LaTeX, and processing to PDF -* XOXO export:: Exporting to XOXO -* iCalendar export:: Exporting in iCalendar format -@end menu - -@node Markup rules, Selective export, Exporting, Exporting -@section Markup rules - -When exporting Org mode documents, the exporter tries to reflect the -structure of the document as accurately as possible in the back-end. Since -export targets like HTML or La@TeX{} allow much richer formatting, Org mode -has rules how to prepare text for rich export. This section summarizes the -markup rule used in an Org mode buffer. - -@menu -* Document title:: How the document title is determined -* Headings and sections:: The main structure of the exported document -* Table of contents:: If, where, how to create a table of contents -* Initial text:: Text before the first headline -* Lists:: Plain lists are exported -* Paragraphs:: What determines beginning and ending -* Literal examples:: Source code and other examples -* Include files:: Include the contents of a file during export -* Tables exported:: Tables are exported richly -* Inlined images:: How to inline images during export -* Footnote markup:: -* Emphasis and monospace:: To bold or not to bold -* TeX macros and LaTeX fragments:: Create special, rich export. -* Horizontal rules:: A line across the page -* Comment lines:: Some lines will not be exported -@end menu - -@node Document title, Headings and sections, Markup rules, Markup rules -@subheading Document title -@cindex document title, markup rules - -@noindent -The title of the exported document is taken from the special line - -@example -#+TITLE: This is the title of the document -@end example - -@noindent -If this line does not exist, the title is derived from the first non-empty, -non-comment line in the buffer. If no such line exists, or if you have -turned off exporting of the text before the first headline (see below), the -title will be the file name without extension. - -If you are exporting only a subtree by marking is as the region, the heading -of the subtree will become the title of the document. If the subtree has a -property @code{EXPORT_TITLE}, that will take precedence. - -@node Headings and sections, Table of contents, Document title, Markup rules -@subheading Headings and sections -@cindex headings and sections, markup rules - -The outline structure of the document as described in @ref{Document -Structure} forms the basis for defining sections of the exported document. -However, since the outline structure is also used for (for example) lists of -tasks, only the first three outline levels will be used as headings. Deeper -levels will become itemized lists. You can change the location of this -switch, globally by setting the variable @code{org-headline-levels}, or on a -per file basis with a line - -@example -#+OPTIONS: H:4 -@end example - -@node Table of contents, Initial text, Headings and sections, Markup rules -@subheading Table of contents -@cindex table of contents, markup rules - -The table of contents is normally inserted directly before the first headline -of the file. If you would like to get it to a different location, insert the -string @code{[TABLE-OF-CONTENTS]} on a line by itself at the desired -location. The depth of the table of contents is by default the same as the -number of headline levels, but you can choose a smaller number or turn off -the table of contents entirely by configuring the variable -@code{org-export-with-toc}, or on a per-file basis with a line like - -@example -#+OPTIONS: toc:2 (only to two levels in TOC) -#+OPTIONS: toc:nil (no TOC at all) -@end example - -@node Initial text, Lists, Table of contents, Markup rules -@subheading Text before the first headline -@cindex text before first headline, markup rules -@cindex #+TEXT - -Org mode normally exports the text before the first headline, and even uses -the first line as the document title. The text will be fully marked up. If -you need to include literal HTML or La@TeX{} code, use the special constructs -described below in the sections for the individual exporters. - -Some people like to use the space before the first headline for setup and -internal links and therefore would like to control the exported text before -the first headline in a different way. You can do so by setting the variable -@code{org-export-skip-text-before-1st-heading} to @code{t}. On a per-file -basis, you can get the same effect with @samp{#+OPTIONS: skip:t}. - -@noindent -If you still want to have some text before the first headline, use the -@code{#+TEXT} construct: - -@example -#+OPTIONS: skip:t -#+TEXT: This text will go before the *first* headline. -#+TEXT: [TABLE-OF-CONTENTS] -#+TEXT: This goes between the table of contents and the first headline -@end example - -@node Lists, Paragraphs, Initial text, Markup rules -@subheading Lists -@cindex lists, markup rules - -Plain lists as described in @ref{Plain lists} are translated to the back-ends -syntax for such lists. Most back-ends support unordered, ordered, and -description lists. - -@node Paragraphs, Literal examples, Lists, Markup rules -@subheading Paragraphs, line breaks, and quoting -@cindex paragraphs, markup rules - -Paragraphs are separated by at least one empty line. If you need to enforce -a line break within a paragraph, use @samp{\\} at the end of a line. - -To keep the line breaks in a region, but otherwise use normal formatting, you -can use this construct, which can also be used to format poetry. - -@example -#+BEGIN_VERSE - Great clouds overhead - Tiny black birds rise and fall - Snow covers Emacs - - -- AlexSchroeder -#+END_VERSE -@end example - -When quoting a passage from another document, it is customary to format this -as a paragraph that is indented on both the left and the right margin. You -can include quotations in Org mode documents like this: - -@example -#+BEGIN_QUOTE -Everything should be made as simple as possible, -but not any simpler -- Albert Einstein -#+END_QUOTE -@end example - - -@node Literal examples, Include files, Paragraphs, Markup rules -@subheading Literal examples -@cindex literal examples, markup rules -@cindex code line refenences, markup rules - -You can include literal examples that should not be subjected to -markup. Such examples will be typeset in monospace, so this is well suited -for source code and similar examples. -@cindex #+BEGIN_EXAMPLE - -@example -#+BEGIN_EXAMPLE -Some example from a text file. -#+END_EXAMPLE -@end example - -For simplicity when using small examples, you can also start the example -lines with a colon followed by a space. There may also be additional -whitespace before the colon: - -@example -Here is an example - : Some example from a text file. -@end example - -@cindex formatting source code, markup rules -If the example is source code from a programming language, or any other text -that can be marked up by font-lock in Emacs, you can ask for the example to -look like the fontified Emacs buffer@footnote{Currently this works only for -the HTML back-end, and requires the @file{htmlize.el} package version 1.34 or -later.}. This is done with the @samp{src} block, where you also need to -specify the name of the major mode that should be used to fontify the -example: -@cindex #+BEGIN_SRC - -@example -#+BEGIN_SRC emacs-lisp -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_SRC -@end example - -Both in @code{example} and in @code{src} snippets, you can add a @code{-n} -switch to the end of the @code{BEGIN} line, to get the lines of the example -numbered. If you use a @code{+n} switch, the numbering from the previous -numbered snippet will be continued in the current one. In literal examples, -Org will interpret strings like @samp{(ref:name)} as labels, and use them as -targets for special hyperlinks like @code{[[(name)]]} (i.e. the reference -name enclosed in single parenthesis). In HTML, hovering the mouse over such -a link will remote-highlight the corresponding code line, which is kind of -cool. If the example/src snippet is numbered, you can also add a @code{-r} -switch. Then labels will be @i{removed} from the source code and the links -will be @i{replaced}@footnote{If you want to explain the use of such labels -themelves in org-mode example code, you can use the @code{-k} switch to make -sure they are not touched.} with line numbers from the code listing. Here is -an example: - -@example -#+BEGIN_SRC emacs-lisp -n -r -(save-excursion (ref:sc) - (goto-char (point-min)) (ref:jump) -#+END SRC -In line [[(sc)]] we remember the current positon. [[(jump)][Line (jump)]] -jumps to point-min. -@end example - -If the syntax for the label format conflicts with the language syntax, use a -@code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal --n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}. - -HTML export also allows examples to be published as text areas, @pxref{Text -areas in HTML export}. - -@table @kbd -@kindex C-c ' -@item C-c ' -Edit the source code example at point in its native mode. This works by -switching to an indirect buffer, narrowing the buffer and switching to the -other mode. You need to exit by pressing @kbd{C-c '} again@footnote{Upon -exit, lines starting with @samp{*} or @samp{#} will get a comma prepended, to -keep them from being interpreted by Org as outline nodes or special -comments. These commas will be striped for editing with @kbd{C-c '}, and -also for export.}. Fixed-width -regions (where each line starts with a colon followed by a space) will be -edited using @code{artist-mode}@footnote{You may select a different-mode with -the variable @code{org-edit-fixed-width-region-mode}.} to allow creating -ASCII drawings easily. Using this command in an empty line will create a new -fixed-width region. -@kindex C-c l -@item C-c l -Calling @code{org-store-link} while editing a source code example in a -temporary buffer created with @kbd{C-c '} will prompt for a label, make sure -that it is unique in the current buffer, and insert it with the proper -formatting like @samp{(ref:label)} at the end of the current line. Then the -label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}. -@end table - - -@node Include files, Tables exported, Literal examples, Markup rules -@subheading Include files -@cindex include files, markup rules - -During export, you can include the content of another file. For example, to -include your .emacs file, you could use: -@cindex #+INCLUDE - -@example -#+INCLUDE: "~/.emacs" src emacs-lisp -@end example - -The optional second and third parameter are the markup (@samp{quote}, -@samp{example}, or @samp{src}), and, if the markup is @samp{src}, the -language for formatting the contents. The markup is optional, if it is not -given, the text will be assumed to be in Org mode format and will be -processed normally. The include line will also allow additional keyword -parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the -first line and for each following line, as well as any options accepted by -the selected markup. For example, to include a file as an item, use - -@example -#+INCLUDE: "~/snippets/xx" :prefix1 " + " :prefix " " -@end example - -@table @kbd -@kindex C-c ' -@item C-c ' -Visit the include file at point. -@end table - -@node Tables exported, Inlined images, Include files, Markup rules -@subheading Tables -@cindex tables, markup rules - -Both the native Org mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org mode tables, -the lines before the first horizontal separator line will become table header -lines. You can use the following lines somewhere before the table to assign -a caption and a label for cross references: - -@example -#+CAPTION: This is the caption for the next table (or link) -#+LABEL: tbl:basic-data -@end example - -@node Inlined images, Footnote markup, Tables exported, Markup rules -@subheading Inlined Images -@cindex inlined images, markup rules - -Some backends (HTML and LaTeX) allow to directly include images into the -exported document. Org does this, if a link to an image files does not have -a description part, for example @code{[[./img/a.jpg]]}. If you wish to -define a caption for the image and maybe a label for internal cross -references, you can use (before, but close to the link) - -@example -#+CAPTION: This is the caption for the next figure link (or table) -#+LABEL: fig:SED-HR4049 -@end example - -You may also define additional attributes for the figure. As this is -backend-specific, see the sections about the individual backends for more -information. - -@node Footnote markup, Emphasis and monospace, Inlined images, Markup rules -@subheading Footnote markup -@cindex footnotes, markup rules -@cindex @file{footnote.el} - -Footnotes defined in the way descriped in @ref{Footnotes} will be exported by -all backends. Org does allow multiple references to the same note, and -different backends support this to varying degree. - -@node Emphasis and monospace, TeX macros and LaTeX fragments, Footnote markup, Markup rules -@subheading Emphasis and monospace - -@cindex underlined text, markup rules -@cindex bold text, markup rules -@cindex italic text, markup rules -@cindex verbatim text, markup rules -@cindex code text, markup rules -@cindex strike-through text, markup rules -You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} -and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text -in the code and verbatim string is not processed for Org mode specific -syntax, it is exported verbatim. - -@node TeX macros and LaTeX fragments, Horizontal rules, Emphasis and monospace, Markup rules -@subheading @TeX{} macros and La@TeX{} fragments -@cindex LaTeX fragments, markup rules -@cindex TeX macros, markup rules -@cindex HTML entities -@cindex LaTeX entities - -A @TeX{}-like syntax is used to specify special characters. Where possible, -these will be transformed into the native format of the exporter back-end. -Strings like @code{\alpha} will be exported as @code{α} in the HTML -output, and as @code{$\alpha$} in the La@TeX{} output. Similarly, -@code{\nbsp} will become @code{ } in HTML and @code{~} in La@TeX{}. -This applies for a large number of entities, with names taken from both HTML -and La@TeX{}, see the variable @code{org-html-entities} for the complete -list. If you are unsure about a name, use @kbd{M-@key{TAB}} for completion -after having typed the backslash and maybe a few characters -(@pxref{Completion}). - -La@TeX{} fragments are converted into images for HTML export, and they are -written literally into the La@TeX{} export. See also @ref{Embedded LaTeX}. - -Finally, @samp{\-} is treated as a shy hyphen, and @samp{--}, @samp{---}, and -@samp{...} are all converted into special commands creating hyphens of -different lengths or a compact set of dots. - -@node Horizontal rules, Comment lines, TeX macros and LaTeX fragments, Markup rules -@subheading Horizontal rules -@cindex horizontal rules, markup rules -A line consisting of only dashes, and at least 5 of them, will be -exported as a horizontal line (@samp{
} in HTML). - -@node Comment lines, , Horizontal rules, Markup rules -@subheading Comment lines -@cindex comment lines -@cindex exporting, not - -Lines starting with @samp{#} in column zero are treated as comments and will -never be exported. Also entire subtrees starting with the word -@samp{COMMENT} will never be exported. Finally, regions surrounded by -@samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will not be exported. - -@table @kbd -@kindex C-c ; -@item C-c ; -Toggle the COMMENT keyword at the beginning of an entry. -@end table - -@node Selective export, Export options, Markup rules, Exporting -@section Selective export -@cindex export, selective by tags - -You may use tags to select the parts of a document that should be exported, -or to exclude parts from export. This behavior is governed by two variables: -@code{org-export-select-tags} and @code{org-export-exclude-tags}. - -Org first checks if any of the @emph{select} tags is present in the buffer. -If yes, all trees that do not carry one of these tags will be excluded. If a -selected tree is a subtree, the heading hierarchy above it will also be -selected for export, but not the text below those headings. - -@noindent -If none of the select tags is found, the whole buffer will be selected for -export. - -@noindent -Finally, all subtrees that are marked by any of the @emph{exclude} tags will -be removed from the export buffer. - -@node Export options, The export dispatcher, Selective export, Exporting -@section Export options -@cindex options, for export - -@cindex completion, of option keywords -The exporter recognizes special lines in the buffer which provide -additional information. These lines may be put anywhere in the file. -The whole set of lines can be inserted into the buffer with @kbd{C-c -C-e t}. For individual lines, a good way to make sure the keyword is -correct is to type @samp{#+} and then use @kbd{M-@key{TAB}} completion -(@pxref{Completion}). - -@table @kbd -@kindex C-c C-e t -@item C-c C-e t -Insert template with export options, see example below. -@end table - -@cindex #+TITLE: -@cindex #+AUTHOR: -@cindex #+DATE: -@cindex #+EMAIL: -@cindex #+LANGUAGE: -@cindex #+TEXT: -@cindex #+OPTIONS: -@cindex #+LINK_UP: -@cindex #+LINK_HOME: -@cindex #+EXPORT_SELECT_TAGS: -@cindex #+EXPORT_EXCLUDE_TAGS: -@example -#+TITLE: the title to be shown (default is the buffer name) -#+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: A date, fixed, of a format string for @code{format-time-string} -#+EMAIL: his/her email address (default from @code{user-mail-address}) -#+LANGUAGE: language for HTML, e.g. @samp{en} (@code{org-export-default-language}) -#+TEXT: Some descriptive text to be inserted at the beginning. -#+TEXT: Several lines may be given. -#+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+LINK_UP: the ``up'' link of an exported page -#+LINK_HOME: the ``home'' link of an exported page -#+EXPORT_SELECT_TAGS: Tags that select a tree for export -#+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export -@end example - -@noindent -The OPTIONS line is a compact@footnote{If you want to configure many options -this way, you can use several OPTIONS lines.} form to specify export settings. Here -you can: -@cindex headline levels -@cindex section-numbers -@cindex table of contents -@cindex line-break preservation -@cindex quoted HTML tags -@cindex fixed-width sections -@cindex tables -@cindex @TeX{}-like syntax for sub- and superscripts -@cindex footnotes -@cindex special strings -@cindex emphasized text -@cindex @TeX{} macros -@cindex La@TeX{} fragments -@cindex author info, in export -@cindex time info, in export -@example -H: @r{set the number of headline levels for export} -num: @r{turn on/off section-numbers} -toc: @r{turn on/off table of contents, or set level limit (integer)} -\n: @r{turn on/off line-break-preservation} -@@: @r{turn on/off quoted HTML tags} -:: @r{turn on/off fixed-width sections} -|: @r{turn on/off tables} -^: @r{turn on/off @TeX{}-like syntax for sub- and superscripts. If} - @r{you write "^:@{@}", @code{a_@{b@}} will be interpreted, but} - @r{the simple @code{a_b} will be left as it is.} --: @r{turn on/off conversion of special strings.} -f: @r{turn on/off footnotes like this[1].} -todo: @r{turn on/off inclusion of TODO keywords into exported text} -pri: @r{turn on/off priority cookies} -tags: @r{turn on/off inclusion of tags, may also be @code{not-in-toc}} -<: @r{turn on/off inclusion of any time/date stamps like DEADLINES} -*: @r{turn on/off emphasized text (bold, italic, underlined)} -TeX: @r{turn on/off simple @TeX{} macros in plain text} -LaTeX: @r{turn on/off La@TeX{} fragments} -skip: @r{turn on/off skipping the text before the first heading} -author: @r{turn on/off inclusion of author name/email into exported file} -creator: @r{turn on/off inclusion of creator info into exported file} -timestamp: @r{turn on/off inclusion creation time into exported file} -d: @r{turn on/off inclusion of drawers} -@end example - -These options take effect in both the HTML and La@TeX{} export, except -for @code{TeX} and @code{LaTeX}, which are respectively @code{t} and -@code{nil} for the La@TeX{} export. - -When exporting only a single subtree by selecting it with @kbd{C-c @@} before -calling an export command, the subtree can overrule some of the file's export -settings with properties @code{EXPORT_FILE_NAME}, @code{EXPORT_TITLE}, -@code{EXPORT_TEXT}, and @code{EXPORT_OPTIONS}. - -@node The export dispatcher, ASCII export, Export options, Exporting -@section The export dispatcher -@cindex dispatcher, for export commands - -All export commands can be reached using the export dispatcher, which is a -prefix key that prompts for an additional key specifying the command. -Normally the entire file is exported, but if there is an active region that -contains one outline tree, the first heading is used as document title and -the subtrees are exported. - -@table @kbd -@kindex C-c C-e -@item C-c C-e -Dispatcher for export and publishing commands. Displays a help-window -listing the additional key(s) needed to launch an export or publishing -command. The prefix arg is passed through to the exporter. A double prefix -@kbd{C-u C-u} causes most commands to be executed in the background, in a -separate emacs process@footnote{To make this behavior the default, customize -the variable @code{org-export-run-in-background}.}. -@kindex C-c C-e v -@item C-c C-e v -Like @kbd{C-c C-e}, but only export the text that is currently visible -(i.e. not hidden by outline visibility). -@kindex C-u C-u C-c C-e -@item C-u C-u C-c C-e -Call an the exporter, but reverse the setting of -@code{org-export-run-in-background}, i.e. request background processing if -not set, or force processing in the current Emacs process if st. -@end table - -@node ASCII export, HTML export, The export dispatcher, Exporting -@section ASCII export -@cindex ASCII export - -ASCII export produces a simple and very readable version of an Org mode -file. - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@kindex C-c C-e a -@item C-c C-e a -Export as ASCII file. For an org file @file{myfile.org}, the ASCII file -will be @file{myfile.txt}. The file will be overwritten without -warning. If there is an active region@footnote{this requires -@code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will -become the document title. If the tree head entry has or inherits an -@code{EXPORT_FILE_NAME} property, that name will be used for the -export. -@kindex C-c C-e v a -@item C-c C-e v a -Export only the visible part of the document. -@end table - -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as itemized lists. If you want that transition to occur -at a different level, specify it with a prefix argument. For example, - -@example -@kbd{C-1 C-c C-e a} -@end example - -@noindent -creates only top level headlines and does the rest as items. When -headlines are converted to items, the indentation of the text following -the headline is changed to fit nicely under the item. This is done with -the assumption that the first body line indicates the base indentation of -the body text. Any indentation larger than this is adjusted to preserve -the layout relative to the first line. Should there be lines with less -indentation than the first, these are left alone. - -@node HTML export, LaTeX and PDF export, ASCII export, Exporting -@section HTML export -@cindex HTML export - -Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive -HTML formatting, in ways similar to John Gruber's @emph{markdown} -language, but with additional support for tables. - -@menu -* HTML Export commands:: How to invoke HTML export -* Quoting HTML tags:: Using direct HTML in Org mode -* Links:: Transformation of links for HTML -* Images in HTML export:: How to insert figures into HTML output -* Text areas in HTML export:: An alternative way to show an example -* CSS support:: Changing the appearance of the output -* Javascript support:: Info and Folding in a web browser -@end menu - -@node HTML Export commands, Quoting HTML tags, HTML export, HTML export -@subsection HTML export commands - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@kindex C-c C-e h -@item C-c C-e h -Export as HTML file @file{myfile.html}. For an org file @file{myfile.org}, -the ASCII file will be @file{myfile.html}. The file will be overwritten -without warning. If there is an active region@footnote{this requires -@code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@kindex C-c C-e b -@item C-c C-e b -Export as HTML file and immediately open it with a browser. -@kindex C-c C-e H -@item C-c C-e H -Export to a temporary buffer, do not create a file. -@kindex C-c C-e R -@item C-c C-e R -Export the active region to a temporary buffer. With a prefix argument, do -not produce the file header and footer, but just the plain HTML section for -the region. This is good for cut-and-paste operations. -@kindex C-c C-e v h -@kindex C-c C-e v b -@kindex C-c C-e v H -@kindex C-c C-e v R -@item C-c C-e v h -@item C-c C-e v b -@item C-c C-e v H -@item C-c C-e v R -Export only the visible part of the document. -@item M-x org-export-region-as-html -Convert the region to HTML under the assumption that it was Org mode -syntax before. This is a global command that can be invoked in any -buffer. -@item M-x org-replace-region-by-HTML -Replace the active region (assumed to be in Org mode syntax) by HTML -code. -@end table - -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become headlines, -defining a general document structure. Additional levels will be exported as -itemized lists. If you want that transition to occur at a different level, -specify it with a numeric prefix argument. For example, - -@example -@kbd{C-2 C-c C-e b} -@end example - -@noindent -creates two levels of headings and does the rest as items. - -@node Quoting HTML tags, Links, HTML Export commands, HTML export -@subsection Quoting HTML tags - -Plain @samp{<} and @samp{>} are always transformed to @samp{<} and -@samp{>} in HTML export. If you want to include simple HTML tags -which should be interpreted as such, mark them with @samp{@@} as in -@samp{@@bold text@@}. Note that this really works only for -simple tags. For more extensive HTML that should be copied verbatim to -the exported file use either - -@example -#+HTML: Literal HTML code for export -@end example - -@noindent or -@cindex #+BEGIN_HTML - -@example -#+BEGIN_HTML -All lines between these markers are exported literally -#+END_HTML -@end example - - -@node Links, Images in HTML export, Quoting HTML tags, HTML export -@subsection Links - -@cindex links, in HTML export -@cindex internal links, in HTML export -@cindex external links, in HTML export -Internal links (@pxref{Internal links}) will continue to work in HTML. This -does include automatic links created by radio targets (@pxref{Radio -targets}). Links to external files will still work if the target file is on -the same @i{relative} path as the published Org file. Links to other -@file{.org} files will be translated into HTML links under the assumption -that an HTML version also exists of the linked file, at the same relative -path. @samp{id:} links can then be used to jump to specific entries across -files. For information related to linking files while publishing them to a -publishing directory see @ref{Publishing links}. - -If you want to specify attributes for links, you can do so using a special -@code{#+ATTR_HTML} line to define attributes that will be added to the -@code{} or @code{} tags. Here is an example that sets @code{alt} and -@code{title} attributes for an inlined image: - -@example -#+ATTR_HTML: alt="This is image A" title="Image with no action" -[[./img/a.jpg]] -@end example - -@node Images in HTML export, Text areas in HTML export, Links, HTML export -@subsection Images - -@cindex images, inline in HTML -@cindex inlining images in HTML -HTML export can inline images given as links in the Org file, and -it can make an image the clickable part of a link. By -default@footnote{but see the variable -@code{org-export-html-inline-images}}, images are inlined if a link does -not have a description. So @samp{[[file:myimg.jpg]]} will be inlined, -while @samp{[[file:myimg.jpg][the image]]} will just produce a link -@samp{the image} that points to the image. If the description part -itself is a @code{file:} link or a @code{http:} URL pointing to an -image, this image will be inlined and activated so that clicking on the -image will activate the link. For example, to include a thumbnail that -will link to a high resolution version of the image, you could use: - -@example -[[file:highres.jpg][file:thumb.jpg]] -@end example - -@noindent -and you could use @code{http} addresses just as well. - -@node Text areas in HTML export, CSS support, Images in HTML export, HTML export -@subsection Text areas - -@cindex text areas, in HTML -An alternative way to publish literal code examples in HTML is to use text -areas, where the example can even be edited before pasting it into an -application. It is triggered by a @code{-t} switch at an @code{example} or -@code{src} block. Using this switch disables any options for syntax and -label highlighting, and line numbering, which may be present. You may also -use @code{-h} and @code{-w} switches to specify the height and width of the -text area, which default to the number of lines in the example, and 80, -respectively. For example - -@example -#+BEGIN_EXAMPLE -t -w 40 -(defun org-xor (a b) - "Exclusive or." - (if a (not b) b)) -#+END_EXAMPLE -@end example - - -@node CSS support, Javascript support, Text areas in HTML export, HTML export -@subsection CSS support -@cindex CSS, for HTML export -@cindex HTML export, CSS - -You can also give style information for the exported file. The HTML exporter -assigns the following special CSS classes to appropriate parts of the -document - your style specifications may change these, in addition to any of -the standard classes like for headlines, tables etc. -@example -.todo @r{TODO keywords} -.done @r{the DONE keyword} -.timestamp @r{time stamp} -.timestamp-kwd @r{keyword associated with a time stamp, like SCHEDULED} -.tag @r{tag in a headline} -.target @r{target for links} -div.figure @r{how to format an inlined image} -.linenr @r{the line number in a code example} -.code-highlighted @r{for highlighting referenced code lines} -@end example - -Each exported files contains a compact default style that defines these -classes in a basic way@footnote{This style is defined in the constant -@code{org-export-html-style-default}, which you should not modify. To turn -inclusion of these defaults off, customize -@code{org-export-html-style-include-default}}. You may overwrite these -settings, or add to them by using the variables @code{org-export-html-style} -(for Org-wide settings) and @code{org-export-html-style-extra} (for more -granular settings, like file-local settings). To set the latter variable -individually for each file, you can use - -@example -#+STYLE: -@end example - -@noindent -For longer style definitions, you can use several such lines. You could also -directly write a @code{} section in this way, without -referring to an external file. - -@c FIXME: More about header and footer styles -@c FIXME: Talk about links and targets. - -@node Javascript support, , CSS support, HTML export -@subsection Javascript supported display of web pages - -@emph{Sebastian Rose} has written a JavaScript program especially designed to -enhance the web viewing experience of HTML files created with Org. This -program allows you to view large files in two different ways. The first one -is an @emph{Info}-like mode where each section is displayed separately and -navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys -as well, press @kbd{?} for an overview of the available keys). The second -view type is a @emph{folding} view much like Org provides inside Emacs. The -script is available at @url{http://orgmode.org/org-info.js} and you can find -the documentation for it at @url{http://orgmode.org/worg/code/org-info-js/}. -We are serving the script from our site, but if you use it a lot, you might -not want to be dependent on @url{orgmode.org} and prefer to install a local -copy on your own web server. - -To use the script, you need to make sure that the @file{org-jsinfo.el} module -gets loaded. It should be loaded by default, but you can try @kbd{M-x -customize-variable @key{RET} org-modules @key{RET}} to convince yourself that -this is indeed the case. All it then takes to make use of the program is -adding a single line to the Org file: - -@example -#+INFOJS_OPT: view:info toc:nil -@end example - -@noindent -If this line is found, the HTML header will automatically contain the code -needed to invoke the script. Using the line above, you can set the following -viewing options: - -@example -path: @r{The path to the script. The default is to grab the script from} - @r{@url{http://orgmode.org/org-info.js}, but you might want to have} - @r{a local copy and use a path like @samp{../scripts/org-info.js}.} -view: @r{Initial view when website is first shown. Possible values are:} - info @r{Info-like interface with one section per page.} - overview @r{Folding interface, initially showing only top-level.} - content @r{Folding interface, starting with all headlines visible.} - showall @r{Folding interface, all headlines and text visible.} -sdepth: @r{Maximum headline level that will still become an independent} - @r{section for info and folding modes. The default is taken from} - @r{@code{org-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).} - @r{If this is smaller than in @code{org-headline-levels}, each} - @r{info/folding section can still contain children headlines.} -toc: @r{Should the table of content @emph{initially} be visible?} - @r{Even when @code{nil}, you can always get to the toc with @kbd{i}.} -tdepth: @r{The depth of the table of contents. The defaults are taken from} - @r{the variables @code{org-headline-levels} and @code{org-export-with-toc}.} -ftoc: @r{Does the css of the page specify a fixed position for the toc?} - @r{If yes, the toc will never be displayed as a section.} -ltoc: @r{Should there be short contents (children) in each section?} - @r{Make this @code{above} it the section should be above initial text.} -mouse: @r{Headings are highlighted when the mouse is over them. Should be} - @r{@samp{underline} (default) or a background color like @samp{#cccccc}.} -buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the} - @r{default), only one such button will be present.} -@end example - -You can choose default values for these options by customizing the variable -@code{org-infojs-options}. If you always want to apply the script to your -pages, configure the variable @code{org-export-html-use-infojs}. - -@node LaTeX and PDF export, XOXO export, HTML export, Exporting -@section LaTeX and PDF export -@cindex LaTeX export -@cindex PDF export - -Org mode contains a La@TeX{} exporter written by Bastien Guerry. With -further processing, this backend is also used to produce PDF output. Since -the LaTeX output uses @file{hyperref} to implement links and cross -references, the PDF output file will be fully linked. - -@menu -* LaTeX/PDF export commands:: Which key invokes which commands -* Quoting LaTeX code:: Incorporating literal LaTeX code -* Sectioning structure:: Changing sectioning in LaTeX output -* Tables in LaTeX export:: Options for exporting tables to LaTeX -* Images in LaTeX export:: How to insert figures into LaTeX output -@end menu - -@node LaTeX/PDF export commands, Quoting LaTeX code, LaTeX and PDF export, LaTeX and PDF export -@subsection LaTeX export commands - -@cindex region, active -@cindex active region -@cindex transient-mark-mode -@table @kbd -@kindex C-c C-e l -@item C-c C-e l -Export as La@TeX{} file @file{myfile.tex}. For an org file -@file{myfile.org}, the ASCII file will be @file{myfile.tex}. The file will -be overwritten without warning. If there is an active region@footnote{this -requires @code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has or inherits an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. -@kindex C-c C-e L -@item C-c C-e L -Export to a temporary buffer, do not create a file. -@kindex C-c C-e v l -@kindex C-c C-e v L -@item C-c C-e v l -@item C-c C-e v L -Export only the visible part of the document. -@item M-x org-export-region-as-latex -Convert the region to La@TeX{} under the assumption that it was Org mode -syntax before. This is a global command that can be invoked in any -buffer. -@item M-x org-replace-region-by-latex -Replace the active region (assumed to be in Org mode syntax) by La@TeX{} -code. -@kindex C-c C-e p -@item C-c C-e p -Export as LaTeX and then process to PDF. -@kindex C-c C-e d -@item C-c C-e d -Export as LaTeX and then process to PDF, then open the resulting PDF file. -@end table - -@cindex headline levels, for exporting -In the exported version, the first 3 outline levels will become -headlines, defining a general document structure. Additional levels -will be exported as description lists. The exporter can ignore them or -convert them to a custom string depending on -@code{org-latex-low-levels}. - -If you want that transition to occur at a different level, specify it -with a numeric prefix argument. For example, - -@example -@kbd{C-2 C-c C-e l} -@end example - -@noindent -creates two levels of headings and does the rest as items. - -@node Quoting LaTeX code, Sectioning structure, LaTeX/PDF export commands, LaTeX and PDF export -@subsection Quoting LaTeX code - -Embedded La@TeX{} as described in @ref{Embedded LaTeX} will be correctly -inserted into the La@TeX{} file. This includes simple macros like -@samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, -you can add special code that should only be present in La@TeX{} export with -the following constructs: - -@example -#+LaTeX: Literal LaTeX code for export -@end example - -@noindent or -@cindex #+BEGIN_LaTeX - -@example -#+BEGIN_LaTeX -All lines between these markers are exported literally -#+END_LaTeX -@end example - -@node Sectioning structure, Tables in LaTeX export, Quoting LaTeX code, LaTeX and PDF export -@subsection Sectioning structure -@cindex LaTeX class -@cindex LaTeX sectioning structure - -By default, the La@TeX{} output uses the class @code{article}. - -You can change this globally by setting a different value for -@code{org-export-latex-default-class} or locally by adding an option like -@code{#+LaTeX_CLASS: myclass} in your file, or with a @code{:LaTeX_CLASS:} -property that applies when exporting a region containing only this (sub)tree. -The class should be listed in @code{org-export-latex-classes}, where you can -also define the sectioning structure for each class, as well as defining -additional classes. - -@node Tables in LaTeX export, Images in LaTeX export, Sectioning structure, LaTeX and PDF export -@subsection Tables in LaTeX export -@cindex tables, in LaTeX export - -For LaTeX export of a table, you can specify a label and a caption -(@pxref{Markup rules}). You can also use the @code{ATTR_LaTeX} line to -request a longtable environment for the table, so that it may span several -pages: - -@example -#+CAPTION: A long table -#+LABEL: tbl:long -#+ATTR_LaTeX: longtable -| ..... | ..... | -| ..... | ..... | -@end example - - -@node Images in LaTeX export, , Tables in LaTeX export, LaTeX and PDF export -@subsection Images in LaTeX export -@cindex images, inline in LaTeX -@cindex inlining images in LaTeX - -Images that are linked to without a description part in the link, like -@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]} will be inserted into the PDF -output files resulting from LaTeX output. Org will use an -@code{\includegraphics} macro to insert the image. If you have specified a -caption and/or a label as described in @ref{Markup rules}, the figure will -be wrapped into a @code{figure} environment and thus become a floating -element. Finally, you can use an @code{#+ATTR_LaTeX:} line to specify the -options that can be used in the optional argument of the -@code{\includegraphics} macro. - -@example -#+CAPTION: The black-body emission of the disk around HR 4049 -#+LABEL: fig:SED-HR4049 -#+ATTR_LaTeX: width=5cm,angle=90 -[[./img/sed-hr4049.pdf]] -@end example - -If you need references to a label created in this way, write -@samp{\ref@{fig:SED-HR4049@}} just like in LaTeX. The default settings will -recognize files types that can be included as images during processing by -pdflatex (@file{png}, @file{jpg}, and @file{pdf} files). If you process your -files in a different way, you may need to customize the variable -@code{org-export-latex-inline-image-extensions}. - -@node XOXO export, iCalendar export, LaTeX and PDF export, Exporting -@section XOXO export -@cindex XOXO export - -Org mode contains an exporter that produces XOXO-style output. -Currently, this exporter only handles the general outline structure and -does not interpret any additional Org mode features. - -@table @kbd -@kindex C-c C-e x -@item C-c C-e x -Export as XOXO file @file{myfile.html}. -@kindex C-c C-e v -@item C-c C-e v x -Export only the visible part of the document. -@end table - -@node iCalendar export, , XOXO export, Exporting -@section iCalendar export -@cindex iCalendar export - -Some people like to use Org mode for keeping track of projects, but still -prefer a standard calendar application for anniversaries and appointments. -In this case it can be useful to have deadlines and other time-stamped items -in Org files show up in the calendar application. Org mode can export -calendar information in the standard iCalendar format. If you also want to -have TODO entries included in the export, configure the variable -@code{org-icalendar-include-todo}. iCalendar export will export plain time -stamps as VEVENT, and TODO items as VTODO. It will also create events from -deadlines that are in non-TODO items. Deadlines and scheduling dates in TODO -items will be used to set the start and due dates for the todo -entry@footnote{See the variables @code{org-icalendar-use-deadline} and -@code{org-icalendar-use-scheduled}.}. As categories, it will use the tags -locally defined in the heading, and the file/tree category@footnote{To add -inherited tags or the TODO state, configure the variable -@code{org-icalendar-categories}.}. - -The iCalendar standard requires each entry to have a globally unique -identifier (UID). Org creates these identifiers during export. If you set -the variable @code{org-icalendar-store-UID}, the UID will be stored in the -@code{:ID:} property of the entry and re-used next time you report this -entry. Since a single entry can give rise to multiple iCalendar entries (as -a timestamp, a deadline, a scheduled item, and as a TODO item), Org adds -prefixes to the UID, depending on what triggered the inclusion of the entry. -In this way the UID remains unique, but a synchronization program can still -figure out from which entry all the different instances originate. - -@table @kbd -@kindex C-c C-e i -@item C-c C-e i -Create iCalendar entries for the current file and store them in the same -directory, using a file extension @file{.ics}. -@kindex C-c C-e I -@item C-c C-e I -Like @kbd{C-c C-e i}, but do this for all files in -@code{org-agenda-files}. For each of these files, a separate iCalendar -file will be written. -@kindex C-c C-e c -@item C-c C-e c -Create a single large iCalendar file from all files in -@code{org-agenda-files} and write it to the file given by -@code{org-combined-agenda-icalendar-file}. -@end table - -The export will honor SUMMARY, DESCRIPTION and LOCATION@footnote{The LOCATION -property can be inherited from higher in the hierarchy if you configure -@code{org-use-property-inheritance} accordingly.} properties if the selected -entries have them. If not, the summary will be derived from the headline, -and the description from the body (limited to -@code{org-icalendar-include-body} characters). - -How this calendar is best read and updated, that depends on the application -you are using. The FAQ covers this issue. - -@node Publishing, Miscellaneous, Exporting, Top -@chapter Publishing -@cindex publishing - -Org includes@footnote{@file{org-publish.el} is not distributed with -Emacs 21, if you are still using Emacs 21, you need you need to download -this file separately.} a publishing management system that allows you to -configure automatic HTML conversion of @emph{projects} composed of -interlinked org files. This system is called @emph{org-publish}. You can -also configure org-publish to automatically upload your exported HTML -pages and related attachments, such as images and source code files, to -a web server. Org-publish turns Org into a web-site authoring tool. - -You can also use Org-publish to convert files into La@TeX{}, or even -combine HTML and La@TeX{} conversion so that files are available in both -formats on the server@footnote{Since La@TeX{} files on a server are not -that helpful, you surely want to perform further conversion on them -- -e.g. convert them to @code{PDF} format.}. - -Org-publish has been contributed to Org by David O'Toole. - -@menu -* Configuration:: Defining projects -* Sample configuration:: Example projects -* Triggering publication:: Publication commands -@end menu - -@node Configuration, Sample configuration, Publishing, Publishing -@section Configuration - -Publishing needs significant configuration to specify files, destination -and many other properties of a project. - -@menu -* Project alist:: The central configuration variable -* Sources and destinations:: From here to there -* Selecting files:: What files are part of the project? -* Publishing action:: Setting the function doing the publishing -* Publishing options:: Tweaking HTML export -* Publishing links:: Which links keep working after publishing? -* Project page index:: Publishing a list of project files -@end menu - -@node Project alist, Sources and destinations, Configuration, Configuration -@subsection The variable @code{org-publish-project-alist} -@cindex org-publish-project-alist -@cindex projects, for publishing - -Org-publish is configured almost entirely through setting the value of -one variable, called @code{org-publish-project-alist}. -Each element of the list configures one project, and may be in one of -the two following forms: - -@lisp -("project-name" :property value :property value ...) - -@r{or} - -("project-name" :components ("project-name" "project-name" ...)) - -@end lisp - -In both cases, projects are configured by specifying property values. -A project defines the set of files that will be published, as well as -the publishing configuration to use when publishing those files. When -a project takes the second form listed above, the individual members -of the ``components'' property are taken to be components of the -project, which group together files requiring different publishing -options. When you publish such a ``meta-project'' all the components -will also publish. The @code{:components} are published in the sequence -provided. - -@node Sources and destinations, Selecting files, Project alist, Configuration -@subsection Sources and destinations for files -@cindex directories, for publishing - -Most properties are optional, but some should always be set. In -particular, org-publish needs to know where to look for source files, -and where to put published files. - -@multitable @columnfractions 0.3 0.7 -@item @code{:base-directory} -@tab Directory containing publishing source files -@item @code{:publishing-directory} -@tab Directory (possibly remote) where output files will be published. -@item @code{:preparation-function} -@tab Function called before starting the publishing process, for example to -run @code{make} for updating files to be published. -@item @code{:completion-function} -@tab Function called after finishing the publishing process, for example to -change permissions of the resulting files. -@end multitable -@noindent - -@node Selecting files, Publishing action, Sources and destinations, Configuration -@subsection Selecting files -@cindex files, selecting for publishing - -By default, all files with extension @file{.org} in the base directory -are considered part of the project. This can be modified by setting the -properties -@multitable @columnfractions 0.25 0.75 -@item @code{:base-extension} -@tab Extension (without the dot!) of source files. This actually is a -regular expression. - -@item @code{:exclude} -@tab Regular expression to match file names that should not be -published, even though they have been selected on the basis of their -extension. - -@item @code{:include} -@tab List of files to be included regardless of @code{:base-extension} -and @code{:exclude}. -@end multitable - -@node Publishing action, Publishing options, Selecting files, Configuration -@subsection Publishing action -@cindex action, for publishing - -Publishing means that a file is copied to the destination directory and -possibly transformed in the process. The default transformation is to export -Org files as HTML files, and this is done by the function -@code{org-publish-org-to-html} which calls the HTML exporter (@pxref{HTML -export}). But you also can publish your files in La@TeX{} by using the -function @code{org-publish-org-to-latex} instead, or as PDF files using -@code{org-publish-org-to-pdf}. Other files like images only need to be -copied to the publishing destination. For non-Org files, you need to provide -your own publishing function: - -@multitable @columnfractions 0.3 0.7 -@item @code{:publishing-function} -@tab Function executing the publication of a file. This may also be a -list of functions, which will all be called in turn. -@end multitable - -The function must accept two arguments: a property list containing at -least a @code{:publishing-directory} property, and the name of the file -to be published. It should take the specified file, make the necessary -transformation (if any) and place the result into the destination folder. -You can write your own publishing function, but @code{org-publish} -provides one for attachments (files that only need to be copied): -@code{org-publish-attachment}. - -@node Publishing options, Publishing links, Publishing action, Configuration -@subsection Options for the HTML/LaTeX exporters -@cindex options, for publishing - -The property list can be used to set many export options for the HTML -and La@TeX{} exporters. In most cases, these properties correspond to user -variables in Org. The table below lists these properties along -with the variable they belong to. See the documentation string for the -respective variable for details. - -@multitable @columnfractions 0.32 0.68 -@item @code{:link-up} @tab @code{org-export-html-link-up} -@item @code{:link-home} @tab @code{org-export-html-link-home} -@item @code{:language} @tab @code{org-export-default-language} -@item @code{:customtime} @tab @code{org-display-custom-times} -@item @code{:headline-levels} @tab @code{org-export-headline-levels} -@item @code{:section-numbers} @tab @code{org-export-with-section-numbers} -@item @code{:section-number-format} @tab @code{org-export-section-number-format} -@item @code{:table-of-contents} @tab @code{org-export-with-toc} -@item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks} -@item @code{:archived-trees} @tab @code{org-export-with-archived-trees} -@item @code{:emphasize} @tab @code{org-export-with-emphasize} -@item @code{:sub-superscript} @tab @code{org-export-with-sub-superscripts} -@item @code{:special-strings} @tab @code{org-export-with-special-strings} -@item @code{:footnotes} @tab @code{org-export-with-footnotes} -@item @code{:drawers} @tab @code{org-export-with-drawers} -@item @code{:tags} @tab @code{org-export-with-tags} -@item @code{:todo-keywords} @tab @code{org-export-with-todo-keywords} -@item @code{:priority} @tab @code{org-export-with-priority} -@item @code{:TeX-macros} @tab @code{org-export-with-TeX-macros} -@item @code{:LaTeX-fragments} @tab @code{org-export-with-LaTeX-fragments} -@item @code{:skip-before-1st-heading} @tab @code{org-export-skip-text-before-1st-heading} -@item @code{:fixed-width} @tab @code{org-export-with-fixed-width} -@item @code{:timestamps} @tab @code{org-export-with-timestamps} -@item @code{:author-info} @tab @code{org-export-author-info} -@item @code{:creator-info} @tab @code{org-export-creator-info} -@item @code{:tables} @tab @code{org-export-with-tables} -@item @code{:table-auto-headline} @tab @code{org-export-highlight-first-table-line} -@item @code{:style-include-default} @tab @code{org-export-html-style-include-default} -@item @code{:style} @tab @code{org-export-html-style} -@item @code{:style-extra} @tab @code{org-export-html-style-extra} -@item @code{:convert-org-links} @tab @code{org-export-html-link-org-files-as-html} -@item @code{:inline-images} @tab @code{org-export-html-inline-images} -@item @code{:html-extension} @tab @code{org-export-html-extension} -@item @code{:html-table-tag} @tab @code{org-export-html-table-tag} -@item @code{:expand-quoted-html} @tab @code{org-export-html-expand} -@item @code{:timestamp} @tab @code{org-export-html-with-timestamp} -@item @code{:publishing-directory} @tab @code{org-export-publishing-directory} -@item @code{:preamble} @tab @code{org-export-html-preamble} -@item @code{:postamble} @tab @code{org-export-html-postamble} -@item @code{:auto-preamble} @tab @code{org-export-html-auto-preamble} -@item @code{:auto-postamble} @tab @code{org-export-html-auto-postamble} -@item @code{:author} @tab @code{user-full-name} -@item @code{:email} @tab @code{user-mail-address} -@item @code{:select-tags} @tab @code{org-export-select-tags} -@item @code{:exclude-tags} @tab @code{org-export-exclude-tags} -@end multitable - -If you use several email addresses, separate them by a semi-column. - -Most of the @code{org-export-with-*} variables have the same effect in -both HTML and La@TeX{} exporters, except for @code{:TeX-macros} and -@code{:LaTeX-fragments}, respectively @code{nil} and @code{t} in the -La@TeX{} export. - -When a property is given a value in @code{org-publish-project-alist}, -its setting overrides the value of the corresponding user variable (if -any) during publishing. Options set within a file (@pxref{Export -options}), however, override everything. - -@node Publishing links, Project page index, Publishing options, Configuration -@subsection Links between published files -@cindex links, publishing - -To create a link from one Org file to another, you would use -something like @samp{[[file:foo.org][The foo]]} or simply -@samp{file:foo.org.} (@pxref{Hyperlinks}). Upon publishing this link -becomes a link to @file{foo.html}. In this way, you can interlink the -pages of your "org web" project and the links will work as expected when -you publish them to HTML. - -You may also link to related files, such as images. Provided you are -careful with relative pathnames, and provided you have also configured -@code{org-publish} to upload the related files, these links will work -too. See @ref{Complex example} for an example of this usage. - -Sometime an Org file to be published may contain links that are -only valid in your production environment, but not in the publishing -location. In this case, use the property - -@multitable @columnfractions 0.4 0.6 -@item @code{:link-validation-function} -@tab Function to validate links -@end multitable - -@noindent -to define a function for checking link validity. This function must -accept two arguments, the file name and a directory relative to which -the file name is interpreted in the production environment. If this -function returns @code{nil}, then the HTML generator will only insert a -description into the HTML file, but no link. One option for this -function is @code{org-publish-validate-link} which checks if the given -file is part of any project in @code{org-publish-project-alist}. - -@node Project page index, , Publishing links, Configuration -@subsection Project page index -@cindex index, of published pages - -The following properties may be used to control publishing of an -index of files or summary page for a given project. - -@multitable @columnfractions 0.25 0.75 -@item @code{:auto-index} -@tab When non-nil, publish an index during org-publish-current-project or -org-publish-all. - -@item @code{:index-filename} -@tab Filename for output of index. Defaults to @file{index.org} (which -becomes @file{index.html}). - -@item @code{:index-title} -@tab Title of index page. Defaults to name of file. - -@item @code{:index-function} -@tab Plug-in function to use for generation of index. -Defaults to @code{org-publish-org-index}, which generates a plain list -of links to all files in the project. -@end multitable - -@node Sample configuration, Triggering publication, Configuration, Publishing -@section Sample configuration - -Below we provide two example configurations. The first one is a simple -project publishing only a set of Org files. The second example is -more complex, with a multi-component project. - -@menu -* Simple example:: One-component publishing -* Complex example:: A multi-component publishing example -@end menu - -@node Simple example, Complex example, Sample configuration, Sample configuration -@subsection Example: simple publishing configuration - -This example publishes a set of Org files to the @file{public_html} -directory on the local machine. - -@lisp -(setq org-publish-project-alist - '(("org" - :base-directory "~/org/" - :publishing-directory "~/public_html" - :section-numbers nil - :table-of-contents nil - :style ""))) -@end lisp - -@node Complex example, , Simple example, Sample configuration -@subsection Example: complex publishing configuration - -This more complicated example publishes an entire website, including -org files converted to HTML, image files, emacs lisp source code, and -style sheets. The publishing-directory is remote and private files are -excluded. - -To ensure that links are preserved, care should be taken to replicate -your directory structure on the web server, and to use relative file -paths. For example, if your org files are kept in @file{~/org} and your -publishable images in @file{~/images}, you'd link to an image with -@c -@example -file:../images/myimage.png -@end example -@c -On the web server, the relative path to the image should be the -same. You can accomplish this by setting up an "images" folder in the -right place on the web server, and publishing images to it. - -@lisp -(setq org-publish-project-alist - '(("orgfiles" - :base-directory "~/org/" - :base-extension "org" - :publishing-directory "/ssh:user@@host:~/html/notebook/" - :publishing-function org-publish-org-to-html - :exclude "PrivatePage.org" ;; regexp - :headline-levels 3 - :section-numbers nil - :table-of-contents nil - :style "" - :auto-preamble t - :auto-postamble nil) - - ("images" - :base-directory "~/images/" - :base-extension "jpg\\|gif\\|png" - :publishing-directory "/ssh:user@@host:~/html/images/" - :publishing-function org-publish-attachment) - - ("other" - :base-directory "~/other/" - :base-extension "css\\|el" - :publishing-directory "/ssh:user@@host:~/html/other/" - :publishing-function org-publish-attachment) - ("website" :components ("orgfiles" "images" "other")))) -@end lisp - -@node Triggering publication, , Sample configuration, Publishing -@section Triggering publication - -Once org-publish is properly configured, you can publish with the -following functions: - -@table @kbd -@item C-c C-e C -Prompt for a specific project and publish all files that belong to it. -@item C-c C-e P -Publish the project containing the current file. -@item C-c C-e F -Publish only the current file. -@item C-c C-e A -Publish all projects. -@end table - -Org uses timestamps to track when a file has changed. The above -functions normally only publish changed files. You can override this and -force publishing of all files by giving a prefix argument. - -@node Miscellaneous, Extensions, Publishing, Top -@chapter Miscellaneous - -@menu -* Completion:: M-TAB knows what you need -* Customization:: Adapting Org to your taste -* In-buffer settings:: Overview of the #+KEYWORDS -* The very busy C-c C-c key:: When in doubt, press C-c C-c -* Clean view:: Getting rid of leading stars in the outline -* TTY keys:: Using Org on a tty -* Interaction:: Other Emacs packages -* Bugs:: Things which do not work perfectly -@end menu - -@node Completion, Customization, Miscellaneous, Miscellaneous -@section Completion -@cindex completion, of @TeX{} symbols -@cindex completion, of TODO keywords -@cindex completion, of dictionary words -@cindex completion, of option keywords -@cindex completion, of tags -@cindex completion, of property keys -@cindex completion, of link abbreviations -@cindex @TeX{} symbol completion -@cindex TODO keywords completion -@cindex dictionary word completion -@cindex option keyword completion -@cindex tag completion -@cindex link abbreviations, completion of - -Org supports in-buffer completion. This type of completion does -not make use of the minibuffer. You simply type a few letters into -the buffer and use the key to complete text right there. - -@table @kbd -@kindex M-@key{TAB} -@item M-@key{TAB} -Complete word at point -@itemize @bullet -@item -At the beginning of a headline, complete TODO keywords. -@item -After @samp{\}, complete @TeX{} symbols supported by the exporter. -@item -After @samp{*}, complete headlines in the current buffer so that they -can be used in search links like @samp{[[*find this headline]]}. -@item -After @samp{:} in a headline, complete tags. The list of tags is taken -from the variable @code{org-tag-alist} (possibly set through the -@samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created -dynamically from all tags used in the current buffer. -@item -After @samp{:} and not in a headline, complete property keys. The list -of keys is constructed dynamically from all keys used in the current -buffer. -@item -After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). -@item -After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org mode. When the -option keyword is already complete, pressing @kbd{M-@key{TAB}} again -will insert example settings for this keyword. -@item -In the line after @samp{#+STARTUP: }, complete startup keywords, -i.e. valid keys for this line. -@item -Elsewhere, complete dictionary words using Ispell. -@end itemize -@end table - -@node Customization, In-buffer settings, Completion, Miscellaneous -@section Customization -@cindex customization -@cindex options, for customization -@cindex variables, for customization - -There are more than 180 variables that can be used to customize -Org. For the sake of compactness of the manual, I am not -describing the variables here. A structured overview of customization -variables is available with @kbd{M-x org-customize}. Or select -@code{Browse Org Group} from the @code{Org->Customization} menu. Many -settings can also be activated on a per-file basis, by putting special -lines into the buffer (@pxref{In-buffer settings}). - -@node In-buffer settings, The very busy C-c C-c key, Customization, Miscellaneous -@section Summary of in-buffer settings -@cindex in-buffer settings -@cindex special keywords - -Org mode uses special lines in the buffer to define settings on a -per-file basis. These lines start with a @samp{#+} followed by a -keyword, a colon, and then individual words defining a setting. Several -setting words can be in the same line, but you can also have multiple -lines for the keyword. While these settings are described throughout -the manual, here is a summary. After changing any of those lines in the -buffer, press @kbd{C-c C-c} with the cursor still in the line to -activate the changes immediately. Otherwise they become effective only -when the file is visited again in a new Emacs session. - -@table @kbd -@item #+ARCHIVE: %s_done:: -This line sets the archive location for the agenda file. It applies for -all subsequent lines until the next @samp{#+ARCHIVE} line, or the end -of the file. The first such line also applies to any entries before it. -The corresponding variable is @code{org-archive-location}. -@item #+CATEGORY: -This line sets the category for the agenda file. The category applies -for all subsequent lines until the next @samp{#+CATEGORY} line, or the -end of the file. The first such line also applies to any entries before it. -@item #+COLUMNS: %25ITEM ..... -Set the default format for columns view. This format applies when -columns view is invoked in location where no @code{COLUMNS} property -applies. -@item #+CONSTANTS: name1=value1 ... -Set file-local values for constants to be used in table formulas. This -line set the local variable @code{org-table-formula-constants-local}. -The global version of this variable is -@code{org-table-formula-constants}. -@item #+FILETAGS: :tag1:tag2:tag3: -Set tags that can be inherited by any entry in the file, including the -top-level entries. -@item #+DRAWERS: NAME1 ..... -Set the file-local set of drawers. The corresponding global variable is -@code{org-drawers}. -@item #+LINK: linkword replace -These lines (several are allowed) specify link abbreviations. -@xref{Link abbreviations}. The corresponding variable is -@code{org-link-abbrev-alist}. -@item #+PRIORITIES: highest lowest default -This line sets the limits and the default for the priorities. All three -must be either letters A-Z or numbers 0-9. The highest priority must -have a lower ASCII number that the lowest priority. -@item #+PROPERTY: Property_Name Value -This line sets a default inheritance value for entries in the current -buffer, most useful for specifying the allowed values of a property. -@item #+SETUPFILE: file -This line defines a file that holds more in-buffer setup. Normally this is -entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e. when starting Org mode for a file, when pressing @kbd{C-c C-c} in a -settings line, or when exporting), then the contents of this file are parsed -as if they had been included in the buffer. In particular, the file can be -any other Org mode file with internal setup. You can visit the file the -cursor is in the line with @kbd{C-c '}. -@item #+STARTUP: -This line sets options to be used at startup of Org mode, when an -Org file is being visited. The first set of options deals with the -initial visibility of the outline tree. The corresponding variable for -global default settings is @code{org-startup-folded}, with a default -value @code{t}, which means @code{overview}. -@cindex @code{overview}, STARTUP keyword -@cindex @code{content}, STARTUP keyword -@cindex @code{showall}, STARTUP keyword -@example -overview @r{top-level headlines only} -content @r{all headlines} -showall @r{no folding at all, show everything} -@end example -Then there are options for aligning tables upon visiting a file. This -is useful in files containing narrowed table columns. The corresponding -variable is @code{org-startup-align-all-tables}, with a default value -@code{nil}. -@cindex @code{align}, STARTUP keyword -@cindex @code{noalign}, STARTUP keyword -@example -align @r{align all tables} -noalign @r{don't align tables on startup} -@end example -Logging closing and reinstating TODO items, and clock intervals -(variables @code{org-log-done}, @code{org-log-note-clock-out}, and -@code{org-log-repeat}) can be configured using these options. -@cindex @code{logdone}, STARTUP keyword -@cindex @code{lognotedone}, STARTUP keyword -@cindex @code{nologdone}, STARTUP keyword -@cindex @code{lognoteclock-out}, STARTUP keyword -@cindex @code{nolognoteclock-out}, STARTUP keyword -@cindex @code{logrepeat}, STARTUP keyword -@cindex @code{lognoterepeat}, STARTUP keyword -@cindex @code{nologrepeat}, STARTUP keyword -@example -logdone @r{record a timestamp when an item is marked DONE} -lognotedone @r{record timestamp and a note when DONE} -nologdone @r{don't record when items are marked DONE} -logrepeat @r{record a time when reinstating a repeating item} -lognoterepeat @r{record a note when reinstating a repeating item} -nologrepeat @r{do not record when reinstating repeating item} -lognoteclock-out @r{record a note when clocking out} -nolognoteclock-out @r{don't record a note when clocking out} -@end example -Here are the options for hiding leading stars in outline headings, and for -indenting outlines. The corresponding variables are -@code{org-hide-leading-stars} and @code{org-odd-levels-only}, both with a -default setting @code{nil} (meaning @code{showstars} and @code{oddeven}). -@cindex @code{hidestars}, STARTUP keyword -@cindex @code{showstars}, STARTUP keyword -@cindex @code{odd}, STARTUP keyword -@cindex @code{even}, STARTUP keyword -@example -hidestars @r{make all but one of the stars starting a headline invisible.} -showstars @r{show all stars starting a headline} -indent @r{virtual indentation according to outline level} -noindent @r{no virtual indentation according to outline level} -odd @r{allow only odd outline levels (1,3,...)} -oddeven @r{allow all outline levels} -@end example -To turn on custom format overlays over time stamps (variables -@code{org-put-time-stamp-overlays} and -@code{org-time-stamp-overlay-formats}), use -@cindex @code{customtime}, STARTUP keyword -@example -customtime @r{overlay custom time format} -@end example -The following options influence the table spreadsheet (variable -@code{constants-unit-system}). -@cindex @code{constcgs}, STARTUP keyword -@cindex @code{constSI}, STARTUP keyword -@example -constcgs @r{@file{constants.el} should use the c-g-s unit system} -constSI @r{@file{constants.el} should use the SI unit system} -@end example -To influence footnote settings, use the following keywords. The -corresponding variables are @code{org-footnote-define-inline} and -@code{org-footnote-auto-label}. -@cindex @code{fninline}, STARTUP keyword -@cindex @code{fnnoinline}, STARTUP keyword -@cindex @code{fnlocal}, STARTUP keyword -@cindex @code{fnprompt}, STARTUP keyword -@cindex @code{fnauto}, STARTUP keyword -@cindex @code{fnconfirm}, STARTUP keyword -@cindex @code{fnplain}, STARTUP keyword -@example -fninline @r{define footnotes inline} -fnnoinline @r{define footnotes in separate section} -fnlocal @r{define footnotes near first reference, but not inline} -fnprompt @r{prompt for footnote labels} -fnauto @r{create [fn:1]-like labels automatically (default)} -fnconfirm @r{offer automatic label for editing or confirmation} -fnplain @r{create [1]-like labels automatically} -@end example -@item #+TAGS: TAG1(c1) TAG2(c2) -These lines (several such lines are allowed) specify the valid tags in -this file, and (potentially) the corresponding @emph{fast tag selection} -keys. The corresponding variable is @code{org-tag-alist}. -@item #+TBLFM: -This line contains the formulas for the table directly above the line. -@item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+OPTIONS, #+DATE: -These lines provide settings for exporting files. For more details see -@ref{Export options}. -@item #+SEQ_TODO: #+TYP_TODO: -These lines set the TODO keywords and their interpretation in the -current file. The corresponding variables are @code{org-todo-keywords} -and @code{org-todo-interpretation}. -@end table - -@node The very busy C-c C-c key, Clean view, In-buffer settings, Miscellaneous -@section The very busy C-c C-c key -@kindex C-c C-c -@cindex C-c C-c, overview - -The key @kbd{C-c C-c} has many purposes in Org, which are all -mentioned scattered throughout this manual. One specific function of -this key is to add @emph{tags} to a headline (@pxref{Tags}). In many -other circumstances it means something like @emph{Hey Org, look -here and update according to what you see here}. Here is a summary of -what this means in different contexts. - -@itemize @minus -@item -If there are highlights in the buffer from the creation of a sparse -tree, or from clock display, remove these highlights. -@item -If the cursor is in one of the special @code{#+KEYWORD} lines, this -triggers scanning the buffer for these lines and updating the -information. -@item -If the cursor is inside a table, realign the table. This command -works even if the automatic table editor has been turned off. -@item -If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to -the entire table. -@item -If the cursor is inside a table created by the @file{table.el} package, -activate that table. -@item -If the current buffer is a remember buffer, close the note and file it. -With a prefix argument, file it, without further interaction, to the -default location. -@item -If the cursor is on a @code{<<>>}, update radio targets and -corresponding links in this buffer. -@item -If the cursor is in a property line or at the start or end of a property -drawer, offer property commands. -@item -If the cursor is at a footnote reference, go to the corresponding -definition, and vice versa. -@item -If the cursor is in a plain list item with a checkbox, toggle the status -of the checkbox. -@item -If the cursor is on a numbered item in a plain list, renumber the -ordered list. -@item -If the cursor is on the @code{#+BEGIN} line of a dynamical block, the -block is updated. -@end itemize - -@node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous -@section A cleaner outline view -@cindex hiding leading stars -@cindex dynamic indentation -@cindex odd-levels-only outlines -@cindex clean outline view - -Some people find it noisy and distracting that the Org headlines are starting -with a potentially large number of stars, and that text below the headlines -is not indented. This is not really a problem when you are writing a book -where the outline headings are really section headlines. However, in a more -list-oriented outline, it is clear that an indented structure is a lot -cleaner, as can be seen by comparing the two columns in the following -example: - -@example -@group -* Top level headline | * Top level headline -** Second level | * Second level -*** 3rd level | * 3rd level -some text | some text -*** 3rd level | * 3rd level -more text | more text -* Another top level headline | * Another top level headline -@end group -@end example - -@noindent -It is non-trivial to make such a look work in Emacs, but Org contains three -separate features that, combined, achieve just that. - -@enumerate -@item -@emph{Indentation of text below headlines}@* -You may indent text below each headline to make the left boundary line up -with the headline, like - -@example -*** 3rd level - more text, now indented -@end example - -A good way to get this indentation is by hand, and Org supports this with -paragraph filling, line wrapping, and structure editing@footnote{See also the -variable @code{org-adapt-indentation}.} preserving or adapting the -indentation appropriate. A different approach would be to have a way to -automatically indent lines according to outline structure by adding overlays -or text properties. But I have not yet found a robust and efficient way to -do this in large files. - -@item -@emph{Hiding leading stars}@* You can modify the display in such a way that -all leading stars become invisible. To do this in a global way, configure -the variable @code{org-hide-leading-stars} or change this on a per-file basis -with - -@example -#+STARTUP: hidestars -@end example - -@noindent -Note that the opposite behavior is selected with @code{showstars}. - -With hidden stars, the tree becomes: - -@example -@group -* Top level headline - * Second level - * 3rd level - ... -@end group -@end example - -@noindent -Note that the leading stars are not truly replaced by whitespace, they -are only fontified with the face @code{org-hide} that uses the -background color as font color. If you are not using either white or -black background, you may have to customize this face to get the wanted -effect. Another possibility is to set this font such that the extra -stars are @i{almost} invisible, for example using the color -@code{grey90} on a white background. - -@item -Things become cleaner still if you skip all the even levels and use only odd -levels 1, 3, 5..., effectively adding two stars to go from one outline level -to the next. In this way we get the outline view shown at the beginning of -this section. In order to make the structure editing and export commands -handle this convention correctly, configure the variable -@code{org-odd-levels-only}, or set this on a per-file basis with one of the -following lines: - -@example -#+STARTUP: odd -#+STARTUP: oddeven -@end example - -You can convert an Org file from single-star-per-level to the -double-star-per-level convention with @kbd{M-x org-convert-to-odd-levels -RET} in that file. The reverse operation is @kbd{M-x -org-convert-to-oddeven-levels}. -@end enumerate - -@node TTY keys, Interaction, Clean view, Miscellaneous -@section Using Org on a tty -@cindex tty key bindings - -Because Org contains a large number of commands, by default much of -Org's core commands are bound to keys that are generally not -accessible on a tty, such as the cursor keys (@key{left}, @key{right}, -@key{up}, @key{down}), @key{TAB} and @key{RET}, in particular when used -together with modifiers like @key{Meta} and/or @key{Shift}. To access -these commands on a tty when special keys are unavailable, the following -alternative bindings can be used. The tty bindings below will likely be -more cumbersome; you may find for some of the bindings below that a -customized work-around suits you better. For example, changing a time -stamp is really only fun with @kbd{S-@key{cursor}} keys, whereas on a -tty you would rather use @kbd{C-c .} to re-insert the timestamp. - -@multitable @columnfractions 0.15 0.2 0.2 -@item @b{Default} @tab @b{Alternative 1} @tab @b{Alternative 2} -@item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab -@item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{@key{Esc} @key{left}} -@item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab -@item @kbd{M-@key{right}} @tab @kbd{C-c C-x i} @tab @kbd{@key{Esc} @key{right}} -@item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab -@item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{@key{Esc} @key{up}} -@item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab -@item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{@key{Esc} @key{down}} -@item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab -@item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab -@item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{@key{Esc} @key{RET}} -@item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab -@item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab -@item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab -@item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab -@item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab -@item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab -@item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab -@end multitable - -@node Interaction, Bugs, TTY keys, Miscellaneous -@section Interaction with other packages -@cindex packages, interaction with other -Org lives in the world of GNU Emacs and interacts in various ways -with other code out there. - -@menu -* Cooperation:: Packages Org cooperates with -* Conflicts:: Packages that lead to conflicts -@end menu - -@node Cooperation, Conflicts, Interaction, Interaction -@subsection Packages that Org cooperates with - -@table @asis -@cindex @file{calc.el} -@item @file{calc.el} by Dave Gillespie -Org uses the Calc package for implementing spreadsheet -functionality in its tables (@pxref{The spreadsheet}). Org -checks for the availability of Calc by looking for the function -@code{calc-eval} which should be autoloaded in your setup if Calc has -been installed properly. As of Emacs 22, Calc is part of the Emacs -distribution. Another possibility for interaction between the two -packages is using Calc for embedded calculations. @xref{Embedded Mode, -, Embedded Mode, Calc, GNU Emacs Calc Manual}. -@cindex @file{constants.el} -@item @file{constants.el} by Carsten Dominik -In a table formula (@pxref{The spreadsheet}), it is possible to use -names for natural constants or units. Instead of defining your own -constants in the variable @code{org-table-formula-constants}, install -the @file{constants} package which defines a large number of constants -and units, and lets you use unit prefixes like @samp{M} for -@samp{Mega} etc. You will need version 2.0 of this package, available -at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for -the function @code{constants-get}, which has to be autoloaded in your -setup. See the installation instructions in the file -@file{constants.el}. -@item @file{cdlatex.el} by Carsten Dominik -@cindex @file{cdlatex.el} -Org mode can make use of the CDLaTeX package to efficiently enter -La@TeX{} fragments into Org files. See @ref{CDLaTeX mode}. -@item @file{imenu.el} by Ake Stenhoff and Lars Lindberg -@cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org mode -supports Imenu - all you need to do to get the index is the following: -@lisp -(add-hook 'org-mode-hook - (lambda () (imenu-add-to-menubar "Imenu"))) -@end lisp -By default the index is two levels deep - you can modify the depth using -the option @code{org-imenu-depth}. -@item @file{remember.el} by John Wiegley -@cindex @file{remember.el} -Org cooperates with remember, see @ref{Remember}. -@file{Remember.el} is not part of Emacs, find it on the web. -@item @file{speedbar.el} by Eric M. Ludlam -@cindex @file{speedbar.el} -Speedbar is a package that creates a special frame displaying files and -index items in files. Org mode supports Speedbar and allows you to -drill into Org files directly from the Speedbar. It also allows to -restrict the scope of agenda commands to a file or a subtree by using -the command @kbd{<} in the Speedbar frame. -@cindex @file{table.el} -@item @file{table.el} by Takaaki Ota -@kindex C-c C-c -@cindex table editor, @file{table.el} -@cindex @file{table.el} - -Complex ASCII tables with automatic line wrapping, column- and -row-spanning, and alignment can be created using the Emacs table -package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}, -and also part of Emacs 22). -When @key{TAB} or @kbd{C-c C-c} is pressed in such a table, Org mode -will call @command{table-recognize-table} and move the cursor into the -table. Inside a table, the keymap of Org mode is inactive. In order -to execute Org mode-related commands, leave the table. - -@table @kbd -@kindex C-c C-c -@item C-c C-c -Recognize @file{table.el} table. Works when the cursor is in a -table.el table. -@c -@kindex C-c ~ -@item C-c ~ -Insert a table.el table. If there is already a table at point, this -command converts it between the table.el format and the Org mode -format. See the documentation string of the command -@code{org-convert-table} for the restrictions under which this is -possible. -@end table -@file{table.el} is part of Emacs 22. -@cindex @file{footnote.el} -@item @file{footnote.el} by Steven L. Baur -Org mode recognizes numerical footnotes as provided by this package. -However, Org-mode also has its own footnote support (@pxref{Footnotes}), -which makes using @file{footnote.el} unnecessary. -@end table - -@node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org mode - -@table @asis - -@cindex @code{shift-selection-mode} -In Emacs 23, @code{shift-selection-mode} is on by default, meaning that -cursor motions combined with the shift key should start or enlarge regions. -This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change -timestamps, TODO keywords, priorities, and item bullet types if the cursor is -at such a location. By default, @kbd{S-@key{cursor}} commands outside -special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org-mode then tries to accommodate shift -selection by (i) using it outside of the special contexts where special -commands apply, and by (ii) extending an existing active region even if the -cursor moves across a special context. - -@cindex @file{CUA.el} -@item @file{CUA.el} by Kim. F. Storm -Key bindings in Org conflict with the @kbd{S-} keys used by CUA mode -(as well as pc-select-mode and s-region-mode) to select and extend the -region. In fact, Emacs 23 has this built-in in the form of -@code{shift-selection-mode}, see previous paragraph. If you are using Emacs -23 you probably don't want to use another package for this purpose. However, -if you prefer to leave these keys to a different package while working in -Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, -Org will move the following key bindings in Org files, and in the agenda -buffer (but not during date selection). - -@example -S-UP -> M-p S-DOWN -> M-n -S-LEFT -> M-- S-RIGHT -> M-+ -C-S-LEFT -> M-S-- C-S-RIGHT -> M-S-+ -@end example - -Yes, these are unfortunately more difficult to remember. If you want -to have other replacement keys, look at the variable -@code{org-disputed-keys}. - -@item @file{windmove.el} by Hovav Shacham -@cindex @file{windmove.el} -Also this package uses the @kbd{S-} keys, so everything written -in the paragraph above about CUA mode also applies here. - -@end table - - -@node Bugs, , Interaction, Miscellaneous -@section Bugs -@cindex bugs - -Here is a list of things that should work differently, but which I -have found too hard to fix. - -@itemize @bullet -@item -If a table field starts with a link, and if the corresponding table -column is narrowed (@pxref{Narrow columns}) to a width too small to -display the link, the field would look entirely empty even though it is -not. To prevent this, Org throws an error. The work-around is to -make the column wide enough to fit the link, or to add some text (at -least 2 characters) before the link in the same field. -@item -Narrowing table columns does not work on XEmacs, because the -@code{format} function does not transport text properties. -@item -Text in an entry protected with the @samp{QUOTE} keyword should not -autowrap. -@item -When the application called by @kbd{C-c C-o} to open a file link fails -(for example because the application does not exist or refuses to open -the file), it does so silently. No error message is displayed. -@item -Recalculating a table line applies the formulas from left to right. -If a formula uses @emph{calculated} fields further down the row, -multiple recalculation may be needed to get all fields consistent. You -may use the command @code{org-table-iterate} (@kbd{C-u C-c *}) to -recalculate until convergence. -@item -The exporters work well, but could be made more efficient. -@end itemize - - -@node Extensions, Hacking, Miscellaneous, Top -@appendix Extensions - -This appendix lists the extension modules that have been written for Org. -Many of these extensions live in the @file{contrib} directory of the Org -distribution, others are available somewhere on the web. - -@menu -* Extensions in the contrib directory:: These come with the Org distro -* Other extensions:: These you have to find on the web. -@end menu - -@node Extensions in the contrib directory, Other extensions, Extensions, Extensions -@section Extensions in the @file{contrib} directory - -A number of extension are distributed with Org when you download it from its -homepage. Please note that these extensions are @emph{not} distributed as -part of Emacs, so if you use Org as delivered with Emacs, you still need to -go to @url{http://orgmode.org} to get access to these modules. - -@table @asis -@item @file{org-annotate-file.el} by @i{Philip Jackson} -Annotate a file with org syntax, in a separate file, with links back to the -annotated file. - -@item @file{org-annotation-helper.el} by @i{Bastien Guerry and Daniel E. German} -Call @i{remember} directly from Firefox/Opera, or from Adobe Reader. When -activating a special link or bookmark, Emacs receives a trigger to create a -note with a link back to the website. Requires some setup, a detailed -description is in @file{contrib/packages/org-annotation-helper}. - -@item @file{org-bookmark.el} by @i{Tokuya Kameshima} -Support for links to Emacs bookmarks. - -@item @file{org-depend.el} by @i{Carsten Dominik} -TODO dependencies for Org-mode. Make TODO state changes in one entry trigger -changes in another, or be blocked by the state of another entry. Also, -easily create chains of TODO items with exactly one active item at any time. - -@item @file{org-elisp-symbol.el} by @i{Bastien Guerry} -Org links to emacs-lisp symbols. This can create annotated links that -exactly point to the definition location of a variable of function. - -@item @file{org-eval.el} by @i{Carsten Dominik} -The @code{} tag, adapted from Emacs Wiki and Emacs Muse, allows text to -be included in a document that is the result of evaluating some code. Other -scripting languages like @code{perl} can be supported with this package as -well. - -@item @file{org-eval-light.el} by @i{Eric Schulte} -User-controlled evaluation of code in an Org buffer. - -@item @file{org-exp-blocks.el} by @i{Eric Schulte} -Preprocess user-defined blocks for export. - -@item @file{org-expiry.el} by @i{Bastien Guerry} -Expiry mechanism for Org entries. - -@item @file{org-indent.el} by @i{Carsten Dominik} -Dynamic indentation of Org outlines. The plan is to indent an outline -according to level, but so far this is too hard for a proper and stable -implementation. Still, it works somewhat. - -@item @file{org-interactive-query.el} by @i{Christopher League} -Interactive modification of tags queries. After running a general query in -Org, this package allows you to narrow down the results by adding more tags -or keywords. - -@item @file{org-mairix.el} by @i{Georg C. F. Greve} -Hook mairix search into Org for different MUAs. - -@item @file{org-man.el} by @i{Carsten Dominik} -Support for links to manpages in Org-mode. - -@item @file{org-mtags.el} by @i{Carsten Dominik} -Support for some Muse-like tags in Org-mode. This package allows you to -write @code{} and @code{} and other syntax copied from Emacs -Muse, right inside an Org file. The goal here is to make it easy to publish -the same file using either org-publish or Muse. - -@item @file{org-panel.el} by @i{Lennart Borgman} -Simplified and display-aided access to some Org commands. - -@item @file{org-registry.el} by @i{Bastien Guerry} -A registry for Org links, to find out from where links point to a given file -or location. - -@item @file{org2rem.el} by @i{Bastien Guerry} -Convert org appointments into reminders for the @file{remind} program. - -@item @file{org-screen.el} by @i{Andrew Hyatt} -Visit screen sessions through Org-mode links. - -@item @file{org-toc.el} by @i{Bastien Guerry} -Table of contents in a separate buffer, with fast access to sections and easy -visibility cycling. - -@item @file{orgtbl-sqlinsert.el} by @i{Jason Riedy} -Convert Org-mode tables to SQL insertions. Documentation for this can be -found on the Worg pages. - -@end table - -@node Other extensions, , Extensions in the contrib directory, Extensions -@section Other extensions - -@i{TO BE DONE} - -@node Hacking, History and Acknowledgments, Extensions, Top -@appendix Hacking - -This appendix covers some aspects where users can extend the functionality of -Org. - -@menu -* Adding hyperlink types:: New custom link types -* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs -* Dynamic blocks:: Automatically filled blocks -* Special agenda views:: Customized views -* Using the property API:: Writing programs that use entry properties -* Using the mapping API:: Mapping over all or selected entries -@end menu - -@node Adding hyperlink types, Tables in arbitrary syntax, Hacking, Hacking -@section Adding hyperlink types -@cindex hyperlinks, adding new types - -Org has a large number of hyperlink types built-in -(@pxref{Hyperlinks}). If you would like to add new link types, it -provides an interface for doing so. Let's look at an example file -@file{org-man.el} that will add support for creating links like -@samp{[[man:printf][The printf manpage]]} to show Unix manual pages inside -emacs: - -@lisp -;;; org-man.el - Support for links to manpages in Org - -(require 'org) - -(org-add-link-type "man" 'org-man-open) -(add-hook 'org-store-link-functions 'org-man-store-link) - -(defcustom org-man-command 'man - "The Emacs command to be used to display a man page." - :group 'org-link - :type '(choice (const man) (const woman))) - -(defun org-man-open (path) - "Visit the manpage on PATH. -PATH should be a topic that can be thrown at the man command." - (funcall org-man-command path)) - -(defun org-man-store-link () - "Store a link to a manpage." - (when (memq major-mode '(Man-mode woman-mode)) - ;; This is a man page, we do make this link - (let* ((page (org-man-get-page-name)) - (link (concat "man:" page)) - (description (format "Manpage for %s" page))) - (org-store-link-props - :type "man" - :link link - :description description)))) - -(defun org-man-get-page-name () - "Extract the page name from the buffer name." - ;; This works for both `Man-mode' and `woman-mode'. - (if (string-match " \\(\\S-+\\)\\*" (buffer-name)) - (match-string 1 (buffer-name)) - (error "Cannot create link to this man page"))) - -(provide 'org-man) - -;;; org-man.el ends here -@end lisp - -@noindent -You would activate this new link type in @file{.emacs} with - -@lisp -(require 'org-man) -@end lisp - -@noindent -Let's go through the file and see what it does. -@enumerate -@item -It does @code{(require 'org)} to make sure that @file{org.el} has been -loaded. -@item -The next line calls @code{org-add-link-type} to define a new link type -with prefix @samp{man}. The call also contains the name of a function -that will be called to follow such a link. -@item -The next line adds a function to @code{org-store-link-functions}, in -order to allow the command @kbd{C-c l} to record a useful link in a -buffer displaying a man page. -@end enumerate - -The rest of the file defines the necessary variables and functions. -First there is a customization variable that determines which emacs -command should be used to display man pages. There are two options, -@code{man} and @code{woman}. Then the function to follow a link is -defined. It gets the link path as an argument - in this case the link -path is just a topic for the manual command. The function calls the -value of @code{org-man-command} to display the man page. - -Finally the function @code{org-man-store-link} is defined. When you try -to store a link with @kbd{C-c l}, also this function will be called to -try to make a link. The function must first decide if it is supposed to -create the link for this buffer type, we do this by checking the value -of the variable @code{major-mode}. If not, the function must exit and -return the value @code{nil}. If yes, the link is created by getting the -manual topic from the buffer name and prefixing it with the string -@samp{man:}. Then it must call the command @code{org-store-link-props} -and set the @code{:type} and @code{:link} properties. Optionally you -can also set the @code{:description} property to provide a default for -the link description when the link is later inserted into an Org -buffer with @kbd{C-c C-l}. - -@node Tables in arbitrary syntax, Dynamic blocks, Adding hyperlink types, Hacking -@section Tables and lists in arbitrary syntax -@cindex tables, in other modes -@cindex lists, in other modes -@cindex Orgtbl mode - -Since Orgtbl mode can be used as a minor mode in arbitrary buffers, a -frequent feature request has been to make it work with native tables in -specific languages, for example La@TeX{}. However, this is extremely -hard to do in a general way, would lead to a customization nightmare, -and would take away much of the simplicity of the Orgtbl mode table -editor. - - -This appendix describes a different approach. We keep the Orgtbl mode -table in its native format (the @i{source table}), and use a custom -function to @i{translate} the table to the correct syntax, and to -@i{install} it in the right location (the @i{target table}). This puts -the burden of writing conversion functions on the user, but it allows -for a very flexible system. - -Bastien added the ability to do the same with lists. You can use Org's -facilities to edit and structure lists by turning @code{orgstruct-mode} -on, then locally exporting such lists in another format (HTML, La@TeX{} -or Texinfo.) - - -@menu -* Radio tables:: Sending and receiving -* A LaTeX example:: Step by step, almost a tutorial -* Translator functions:: Copy and modify -* Radio lists:: Doing the same for lists -@end menu - -@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax -@subsection Radio tables -@cindex radio tables - -To define the location of the target table, you first need to create two -lines that are comments in the current mode, but contain magic words for -Orgtbl mode to find. Orgtbl mode will insert the translated table -between these lines, replacing whatever was there before. For example: - -@example -/* BEGIN RECEIVE ORGTBL table_name */ -/* END RECEIVE ORGTBL table_name */ -@end example - -@noindent -Just above the source table, we put a special line that tells -Orgtbl mode how to translate this table and where to install it. For -example: -@example -#+ORGTBL: SEND table_name translation_function arguments.... -@end example - -@noindent -@code{table_name} is the reference name for the table that is also used -in the receiver lines. @code{translation_function} is the Lisp function -that does the translation. Furthermore, the line can contain a list of -arguments (alternating key and value) at the end. The arguments will be -passed as a property list to the translation function for -interpretation. A few standard parameters are already recognized and -acted upon before the translation function is called: - -@table @code -@item :skip N -Skip the first N lines of the table. Hlines do count as separate lines for -this parameter! - -@item :skipcols (n1 n2 ...) -List of columns that should be skipped. If the table has a column with -calculation marks, that column is automatically discarded as well. -Please note that the translator function sees the table @emph{after} the -removal of these columns, the function never knows that there have been -additional columns. -@end table - -@noindent -The one problem remaining is how to keep the source table in the buffer -without disturbing the normal workings of the file, for example during -compilation of a C file or processing of a La@TeX{} file. There are a -number of different solutions: - -@itemize @bullet -@item -The table could be placed in a block comment if that is supported by the -language. For example, in C mode you could wrap the table between -@samp{/*} and @samp{*/} lines. -@item -Sometimes it is possible to put the table after some kind of @i{END} -statement, for example @samp{\bye} in TeX and @samp{\end@{document@}} -in La@TeX{}. -@item -You can just comment the table line by line whenever you want to process -the file, and uncomment it whenever you need to edit the table. This -only sounds tedious - the command @kbd{M-x orgtbl-toggle-comment} does -make this comment-toggling very easy, in particular if you bind it to a -key. -@end itemize - -@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax -@subsection A LaTeX example of radio tables -@cindex LaTeX, and Orgtbl mode - -The best way to wrap the source table in La@TeX{} is to use the -@code{comment} environment provided by @file{comment.sty}. It has to be -activated by placing @code{\usepackage@{comment@}} into the document -header. Orgtbl mode can insert a radio table skeleton@footnote{By -default this works only for La@TeX{}, HTML, and Texinfo. Configure the -variable @code{orgtbl-radio-tables} to install templates for other -modes.} with the command @kbd{M-x orgtbl-insert-radio-table}. You will -be prompted for a table name, let's say we use @samp{salesfigures}. You -will then get the following template: - -@cindex #+ORGTBL: SEND -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| | | -\end@{comment@} -@end example - -@noindent -The @code{#+ORGTBL: SEND} line tells Orgtbl mode to use the function -@code{orgtbl-to-latex} to convert the table into La@TeX{} and to put it -into the receiver location with name @code{salesfigures}. You may now -fill in the table, feel free to use the spreadsheet features@footnote{If -the @samp{#+TBLFM} line contains an odd number of dollar characters, -this may cause problems with font-lock in LaTeX mode. As shown in the -example you can fix this by adding an extra line inside the -@code{comment} environment that is used to balance the dollar -expressions. If you are using AUCTeX with the font-latex library, a -much better solution is to add the @code{comment} environment to the -variable @code{LaTeX-verbatim-environments}.}: - -@example -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -% $ (optional extra dollar to keep font-lock happy, see footnote) -\end@{comment@} -@end example - -@noindent -When you are done, press @kbd{C-c C-c} in the table to get the converted -table inserted between the two marker lines. - -Now let's assume you want to make the table header by hand, because you -want to control how columns are aligned etc. In this case we make sure -that the table translator does skip the first 2 lines of the source -table, and tell the command to work as a @i{splice}, i.e. to not produce -header and footer commands of the target table: - -@example -\begin@{tabular@}@{lrrr@} -Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\ -% BEGIN RECEIVE ORGTBL salesfigures -% END RECEIVE ORGTBL salesfigures -\end@{tabular@} -% -\begin@{comment@} -#+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2 -| Month | Days | Nr sold | per day | -|-------+------+---------+---------| -| Jan | 23 | 55 | 2.4 | -| Feb | 21 | 16 | 0.8 | -| March | 22 | 278 | 12.6 | -#+TBLFM: $4=$3/$2;%.1f -\end@{comment@} -@end example - -The La@TeX{} translator function @code{orgtbl-to-latex} is already part of -Orgtbl mode. It uses a @code{tabular} environment to typeset the table -and marks horizontal lines with @code{\hline}. Furthermore, it -interprets the following parameters (see also @ref{Translator functions}): - -@table @code -@item :splice nil/t -When set to t, return only table body lines, don't wrap them into a -tabular environment. Default is nil. - -@item :fmt fmt -A format to be used to wrap each field, should contain @code{%s} for the -original field value. For example, to wrap each field value in dollars, -you could use @code{:fmt "$%s$"}. This may also be a property list with -column numbers and formats. for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}. -A function of one argument can be used in place of the strings; the -function must return a formatted string. - -@item :efmt efmt -Use this format to print numbers with exponentials. The format should -have @code{%s} twice for inserting mantissa and exponent, for example -@code{"%s\\times10^@{%s@}"}. The default is @code{"%s\\,(%s)"}. This -may also be a property list with column numbers and formats, for example -@code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After -@code{efmt} has been applied to a value, @code{fmt} will also be -applied. Similar to @code{fmt}, functions of two arguments can be -supplied instead of strings. -@end table - -@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax -@subsection Translator functions -@cindex HTML, and Orgtbl mode -@cindex translator function - -Orgtbl mode has several translator functions built-in: @code{orgtbl-to-csv} -(comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values) -@code{orgtbl-to-latex}, @code{orgtbl-to-html}, and @code{orgtbl-to-texinfo}. -Except for @code{orgtbl-to-html}@footnote{The HTML translator uses the same -code that produces tables during HTML export.}, these all use a generic -translator, @code{orgtbl-to-generic}. For example, @code{orgtbl-to-latex} -itself is a very short function that computes the column definitions for the -@code{tabular} environment, defines a few field and line separators and then -hands over to the generic translator. Here is the entire code: - -@lisp -@group -(defun orgtbl-to-latex (table params) - "Convert the Orgtbl mode TABLE to LaTeX." - (let* ((alignment (mapconcat (lambda (x) (if x "r" "l")) - org-table-last-alignment "")) - (params2 - (list - :tstart (concat "\\begin@{tabular@}@{" alignment "@}") - :tend "\\end@{tabular@}" - :lstart "" :lend " \\\\" :sep " & " - :efmt "%s\\,(%s)" :hline "\\hline"))) - (orgtbl-to-generic table (org-combine-plists params2 params)))) -@end group -@end lisp - -As you can see, the properties passed into the function (variable -@var{PARAMS}) are combined with the ones newly defined in the function -(variable @var{PARAMS2}). The ones passed into the function (i.e. the -ones set by the @samp{ORGTBL SEND} line) take precedence. So if you -would like to use the La@TeX{} translator, but wanted the line endings to -be @samp{\\[2mm]} instead of the default @samp{\\}, you could just -overrule the default with - -@example -#+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]" -@end example - -For a new language, you can either write your own converter function in -analogy with the La@TeX{} translator, or you can use the generic function -directly. For example, if you have a language where a table is started -with @samp{!BTBL!}, ended with @samp{!ETBL!}, and where table lines are -started with @samp{!BL!}, ended with @samp{!EL!} and where the field -separator is a TAB, you could call the generic translator like this (on -a single line!): - -@example -#+ORGTBL: SEND test orgtbl-to-generic :tstart "!BTBL!" :tend "!ETBL!" - :lstart "!BL! " :lend " !EL!" :sep "\t" -@end example - -@noindent -Please check the documentation string of the function -@code{orgtbl-to-generic} for a full list of parameters understood by -that function and remember that you can pass each of them into -@code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function -using the generic function. - -Of course you can also write a completely new function doing complicated -things the generic translator cannot do. A translator function takes -two arguments. The first argument is the table, a list of lines, each -line either the symbol @code{hline} or a list of fields. The second -argument is the property list containing all parameters specified in the -@samp{#+ORGTBL: SEND} line. The function must return a single string -containing the formatted table. If you write a generally useful -translator, please post it on @code{emacs-orgmode@@gnu.org} so that -others can benefit from your work. - -@node Radio lists, , Translator functions, Tables in arbitrary syntax -@subsection Radio lists -@cindex radio lists -@cindex org-list-insert-radio-list - -Sending and receiving radio lists works exactly the same way than -sending and receiving radio tables (@pxref{Radio tables}) @footnote{You -need to load the @code{org-export-latex.el} package to use radio lists -since the relevant code is there for now.}. As for radio tables, you -can insert radio lists templates in HTML, La@TeX{} and Texinfo modes by -calling @code{org-list-insert-radio-list}. - -Here are the differences with radio tables: - -@itemize @minus -@item -Use @code{ORGLST} instead of @code{ORGTBL}. -@item -The available translation functions for radio lists don't take -parameters. -@item -`C-c C-c' will work when pressed on the first item of the list. -@end itemize - -Here is a La@TeX{} example. Let's say that you have this in your -La@TeX{} file: - -@example -% BEGIN RECEIVE ORGLST to-buy -% END RECEIVE ORGLST to-buy -\begin@{comment@} -#+ORGLIST: SEND to-buy orgtbl-to-latex -- a new house -- a new computer - + a new keyboard - + a new mouse -- a new life -\end@{comment@} -@end example - -Pressing `C-c C-c' on @code{a new house} and will insert the converted -La@TeX{} list between the two marker lines. - -@node Dynamic blocks, Special agenda views, Tables in arbitrary syntax, Hacking -@section Dynamic blocks -@cindex dynamic blocks - -Org documents can contain @emph{dynamic blocks}. These are -specially marked regions that are updated by some user-written function. -A good example for such a block is the clock table inserted by the -command @kbd{C-c C-x C-r} (@pxref{Clocking work time}). - -Dynamic block are enclosed by a BEGIN-END structure that assigns a name -to the block and can also specify parameters for the function producing -the content of the block. - -#+BEGIN:dynamic block -@example -#+BEGIN: myblock :parameter1 value1 :parameter2 value2 ... - -#+END: -@end example - -Dynamic blocks are updated with the following commands - -@table @kbd -@kindex C-c C-x C-u -@item C-c C-x C-u -Update dynamic block at point. -@kindex C-u C-c C-x C-u -@item C-u C-c C-x C-u -Update all dynamic blocks in the current file. -@end table - -Updating a dynamic block means to remove all the text between BEGIN and -END, parse the BEGIN line for parameters and then call the specific -writer function for this block to insert the new content. If you want -to use the original content in the writer function, you can use the -extra parameter @code{:content}. - -For a block with name @code{myblock}, the writer function is -@code{org-dblock-write:myblock} with as only parameter a property list -with the parameters given in the begin line. Here is a trivial example -of a block that keeps track of when the block update function was last -run: - -@example -#+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M" - -#+END: -@end example - -@noindent -The corresponding block writer function could look like this: - -@lisp -(defun org-dblock-write:block-update-time (params) - (let ((fmt (or (plist-get params :format) "%d. %m. %Y"))) - (insert "Last block update at: " - (format-time-string fmt (current-time))))) -@end lisp - -If you want to make sure that all dynamic blocks are always up-to-date, -you could add the function @code{org-update-all-dblocks} to a hook, for -example @code{before-save-hook}. @code{org-update-all-dblocks} is -written in a way that is does nothing in buffers that are not in -@code{org-mode}. - -@node Special agenda views, Using the property API, Dynamic blocks, Hacking -@section Special agenda views -@cindex agenda views, user-defined - -Org provides a special hook that can be used to narrow down the -selection made by any of the agenda views. You may specify a function -that is used at each match to verify if the match should indeed be part -of the agenda view, and if not, how much should be skipped. - -Let's say you want to produce a list of projects that contain a WAITING -tag anywhere in the project tree. Let's further assume that you have -marked all tree headings that define a project with the TODO keyword -PROJECT. In this case you would run a TODO search for the keyword -PROJECT, but skip the match unless there is a WAITING tag anywhere in -the subtree belonging to the project line. - -To achieve this, you must write a function that searches the subtree for -the tag. If the tag is found, the function must return @code{nil} to -indicate that this match should not be skipped. If there is no such -tag, return the location of the end of the subtree, to indicate that -search should continue from there. - -@lisp -(defun my-skip-unless-waiting () - "Skip trees that are not waiting" - (let ((subtree-end (save-excursion (org-end-of-subtree t)))) - (if (re-search-forward ":waiting:" subtree-end t) - nil ; tag found, do not skip - subtree-end))) ; tag not found, continue after end of subtree -@end lisp - -Now you may use this function in an agenda custom command, for example -like this: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function 'my-skip-unless-waiting) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -Note that this also binds @code{org-agenda-overriding-header} to get a -meaningful header in the agenda view. - -A general way to create custom searches is to base them on a search for -entries with a certain level limit. If you want to study all entries with -your custom search function, simply do a search for @samp{LEVEL>0}, and then -use @code{org-agenda-skip-function} to select the entries you really want to -have. - -You may also put a Lisp form into @code{org-agenda-skip-function}. In -particular, you may use the functions @code{org-agenda-skip-entry-if} -and @code{org-agenda-skip-subtree-if} in this form, for example: - -@table @code -@item '(org-agenda-skip-entry-if 'scheduled) -Skip current entry if it has been scheduled. -@item '(org-agenda-skip-entry-if 'notscheduled) -Skip current entry if it has not been scheduled. -@item '(org-agenda-skip-entry-if 'deadline) -Skip current entry if it has a deadline. -@item '(org-agenda-skip-entry-if 'scheduled 'deadline) -Skip current entry if it has a deadline, or if it is scheduled. -@item '(org-agenda-skip-entry 'regexp "regular expression") -Skip current entry if the regular expression matches in the entry. -@item '(org-agenda-skip-entry 'notregexp "regular expression") -Skip current entry unless the regular expression matches. -@item '(org-agenda-skip-subtree-if 'regexp "regular expression") -Same as above, but check and skip the entire subtree. -@end table - -Therefore we could also have written the search for WAITING projects -like this, even without defining a special function: - -@lisp -(org-add-agenda-custom-command - '("b" todo "PROJECT" - ((org-agenda-skip-function '(org-agenda-skip-subtree-if - 'regexp ":waiting:")) - (org-agenda-overriding-header "Projects waiting for something: ")))) -@end lisp - -@node Using the property API, Using the mapping API, Special agenda views, Hacking -@section Using the property API -@cindex API, for properties -@cindex properties, API - -Here is a description of the functions that can be used to work with -properties. - -@defun org-entry-properties &optional pom which -Get all properties of the entry at point-or-marker POM. -This includes the TODO keyword, the tags, time strings for deadline, -scheduled, and clocking, and any additional properties defined in the -entry. The return value is an alist, keys may occur multiple times -if the property key was used several times. -POM may also be nil, in which case the current entry is used. -If WHICH is nil or `all', get all properties. If WHICH is -`special' or `standard', only get that subclass. -@end defun -@defun org-entry-get pom property &optional inherit -Get value of PROPERTY for entry at point-or-marker POM. By default, -this only looks at properties defined locally in the entry. If INHERIT -is non-nil and the entry does not have the property, then also check -higher levels of the hierarchy. If INHERIT is the symbol -@code{selective}, use inheritance if and only if the setting of -@code{org-use-property-inheritance} selects PROPERTY for inheritance. -@end defun - -@defun org-entry-delete pom property -Delete the property PROPERTY from entry at point-or-marker POM. -@end defun - -@defun org-entry-put pom property value -Set PROPERTY to VALUE for entry at point-or-marker POM. -@end defun - -@defun org-buffer-property-keys &optional include-specials -Get all property keys in the current buffer. -@end defun - -@defun org-insert-property-drawer -Insert a property drawer at point. -@end defun - -@defun org-entry-put-multivalued-property pom property &rest values -Set PROPERTY at point-or-marker POM to VALUES. VALUES should be a list of -strings. They will be concatenated, with spaces as separators. -@end defun - -@defun org-entry-get-multivalued-property pom property -Treat the value of the property PROPERTY as a whitespace-separated list of -values and return the values as a list of strings. -@end defun - -@defun org-entry-add-to-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is in this list. -@end defun - -@defun org-entry-remove-from-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and make sure that VALUE is @emph{not} in this list. -@end defun - -@defun org-entry-member-in-multivalued-property pom property value -Treat the value of the property PROPERTY as a whitespace-separated list of -values and check if VALUE is in this list. -@end defun - -@node Using the mapping API, , Using the property API, Hacking -@section Using the mapping API -@cindex API, for mapping -@cindex mapping entries, API - -Org has sophisticated mapping capabilities to find all entries satisfying -certain criteria. Internally, this functionality is used to produce agenda -views, but there is also an API that can be used to execute arbitrary -functions for each or selected entries. The main entry point for this API -is: - -@defun org-map-entries func &optional match scope &rest skip -Call FUNC at each headline selected by MATCH in SCOPE. - -FUNC is a function or a lisp form. The function will be called without -arguments, with the cursor positioned at the beginning of the headline. -The return values of all calls to the function will be collected and -returned as a list. - -MATCH is a tags/property/todo match as it is used in the agenda match view. -Only headlines that are matched by this query will be considered during -the iteration. When MATCH is nil or t, all headlines will be -visited by the iteration. - -SCOPE determines the scope of this command. It can be any of: - -@example -nil @r{the current buffer, respecting the restriction if any} -tree @r{the subtree started with the entry at point} -file @r{the current buffer, without restriction} -file-with-archives - @r{the current buffer, and any archives associated with it} -agenda @r{all agenda files} -agenda-with-archives - @r{all agenda files with any archive files associated with them} -(file1 file2 ...) - @r{if this is a list, all files in the list will be scanned} -@end example - -The remaining args are treated as settings for the skipping facilities of -the scanner. The following items can be given here: - -@example -archive @r{skip trees with the archive tag} -comment @r{skip trees with the COMMENT keyword} -function or Lisp form - @r{will be used as value for @code{org-agenda-skip-function},} - @r{so whenever the function returns t, FUNC} - @r{will not be called for that entry and search will} - @r{continue from the point where the function leaves it} -@end example -@end defun - -The function given to that mapping routine can really do anything you like. -It can use the property API (@pxref{Using the property API}) to gather more -information about the entry, or in order to change metadata in the entry. -Here are a couple of functions that might be handy: - -@defun org-todo &optional arg -Change the TODO state of the entry, see the docstring of the functions for -the many possible values for the argument ARG. -@end defun - -@defun org-priority &optional action -Change the priority of the entry, see the docstring of this function for the -possible values for ACTION. -@end defun - -@defun org-toggle-tag tag &optional onoff -Toggle the tag TAG in the current entry. Setting ONOFF to either @code{on} -or @code{off} will not toggle tag, but ensure that it is either on or off. -@end defun - -@defun org-promote -Promote the current entry. -@end defun - -@defun org-demote -Demote the current entry. -@end defun - -Here is a simple example that will turn all entries in the current file with -a tag @code{TOMORROW} into TODO entries with the keyword @code{UPCOMING}. -Entries in comment trees and in archive trees will be ignored. - -@lisp -(org-map-entries - '(org-todo "UPCOMING") - "+TOMORROW" 'file 'archive 'comment) -@end lisp - -The following example counts the number of entries with TODO keyword -@code{WAITING}, in all agenda files. - -@lisp -(length (org-map-entries t "/+WAITING" 'agenda)) -@end lisp - -@node History and Acknowledgments, Main Index, Hacking, Top -@appendix History and Acknowledgments -@cindex acknowledgments -@cindex history -@cindex thanks - -Org was borne in 2003, out of frustration over the user interface -of the Emacs Outline mode. I was trying to organize my notes and -projects, and using Emacs seemed to be the natural way to go. However, -having to remember eleven different commands with two or three keys per -command, only to hide and show parts of the outline tree, that seemed -entirely unacceptable to me. Also, when using outlines to take notes, I -constantly want to restructure the tree, organizing it parallel to my -thoughts and plans. @emph{Visibility cycling} and @emph{structure -editing} were originally implemented in the package -@file{outline-magic.el}, but quickly moved to the more general -@file{org.el}. As this environment became comfortable for project -planning, the next step was adding @emph{TODO entries}, basic @emph{time -stamps}, and @emph{table support}. These areas highlight the two main -goals that Org still has today: To create a new, outline-based, -plain text mode with innovative and intuitive editing features, and to -incorporate project planning functionality directly into a notes file. - -A special thanks goes to @i{Bastien Guerry} who has not only written a large -number of extensions to Org (most of them integrated into the core by now), -but has also helped the development and maintenance of Org so much that he -should be considered the main co-contributor to this package. - -Since the first release, literally thousands of emails to me or on -@code{emacs-orgmode@@gnu.org} have provided a constant stream of bug -reports, feedback, new ideas, and sometimes patches and add-on code. -Many thanks to everyone who has helped to improve this package. I am -trying to keep here a list of the people who had significant influence -in shaping one or more aspects of Org. The list may not be -complete, if I have forgotten someone, please accept my apologies and -let me know. - -@itemize @bullet - -@item -@i{Russel Adams} came up with the idea for drawers. -@item -@i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. -@item -@i{Christophe Bataillon} created the great unicorn logo that we use on the -Org-mode website. -@item -@i{Alex Bochannek} provided a patch for rounding time stamps. -@item -@i{Charles Cave}'s suggestion sparked the implementation of templates -for Remember. -@item -@i{Pavel Chalmoviansky} influenced the agenda treatment of items with -specified time. -@item -@i{Gregory Chernov} patched support for lisp forms into table -calculations and improved XEmacs compatibility, in particular by porting -@file{nouline.el} to XEmacs. -@item -@i{Sacha Chua} suggested to copy some linking code from Planner. -@item -@i{Eddward DeVilla} proposed and tested checkbox statistics. He also -came up with the idea of properties, and that there should be an API for -them. -@item -@i{Kees Dullemond} used to edit projects lists directly in HTML and so -inspired some of the early development, including HTML export. He also -asked for a way to narrow wide table columns. -@item -@i{Christian Egli} converted the documentation into Texinfo format, -patched CSS formatting into the HTML exporter, and inspired the agenda. -@item -@i{David Emery} provided a patch for custom CSS support in exported -HTML agendas. -@item -@i{Nic Ferrier} contributed mailcap and XOXO support. -@item -@i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes. -@item -@i{John Foerch} figured out how to make incremental search show context -around a match in a hidden outline tree. -@item -@i{Niels Giesen} had the idea to automatically archive DONE trees. -@item -@i{Bastien Guerry} wrote the La@TeX{} exporter and @file{org-bibtex.el}, and -has been prolific with patches, ideas, and bug reports. -@item -@i{Kai Grossjohann} pointed out key-binding conflicts with other packages. -@item -@i{Bernt Hansen} has driven much of the support for auto-repeating tasks, -task state change logging, and the clocktable. His clear explanations have -been critical when we started to adopt the GIT version control system. -@item -@i{Manuel Hermenegildo} has contributed various ideas, small fixed and -patches. -@item -@i{Phil Jackson} wrote @file{org-irc.el}. -@item -@i{Scott Jaderholm} proposed footnotes, control over whitespace between -folded entries, and column view for properties. -@item -@i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}. -@item -@i{Shidai Liu} ("Leo") asked for embedded La@TeX{} and tested it. He also -provided frequent feedback and some patches. -@item -@i{Matt Lundin} has proposed last-row references for table formulas and named -invisible anchors. He has also worked a lot on the FAQ. -@item -@i{Jason F. McBrayer} suggested agenda export to CSV format. -@item -@i{Max Mikhanosha} came up with the idea of refiling. -@item -@i{Dmitri Minaev} sent a patch to set priority limits on a per-file -basis. -@item -@i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler -happy. -@item -@i{Rick Moynihan} proposed to allow multiple TODO sequences in a file -and to be able to quickly restrict the agenda to a subtree. -@item -@i{Todd Neal} provided patches for links to Info files and elisp forms. -@item -@i{Tim O'Callaghan} suggested in-file links, search options for general -file links, and TAGS. -@item -@i{Takeshi Okano} translated the manual and David O'Toole's tutorial -into Japanese. -@item -@i{Oliver Oppitz} suggested multi-state TODO items. -@item -@i{Scott Otterson} sparked the introduction of descriptive text for -links, among other things. -@item -@i{Pete Phillips} helped during the development of the TAGS feature, and -provided frequent feedback. -@item -@i{T.V. Raman} reported bugs and suggested improvements. -@item -@i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality -control. -@item -@i{Paul Rivier} provided the basic implementation of named footnotes. -@item -@i{Kevin Rogers} contributed code to access VM files on remote hosts. -@item -@i{Sebastian Rose} wrote @file{org-info.js}, a Java script for displaying -webpages derived from Org using an Info-like, or a folding interface with -single key navigation. -@item -@i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a -conflict with @file{allout.el}. -@item -@i{Jason Riedy} generalized the send-receive mechanism for orgtbl tables with -extensive patches. -@item -@i{Philip Rooke} created the Org reference card, provided lots -of feedback, developed and applied standards to the Org documentation. -@item -@i{Christian Schlauer} proposed angular brackets around links, among -other things. -@item -@i{Eric Schulte} wrote @file{org-plot.el}. -@item -Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s -@file{organizer-mode.el}. -@item -@i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal -examples, and remote highlighting for referenced code lines. -@item -@i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is -now packaged into Org's @file{contrib} directory. -@item -@i{Daniel Sinder} came up with the idea of internal archiving by locking -subtrees. -@item -@i{Dale Smith} proposed link abbreviations. -@item -@i{James TD Smith} has contributed a large number of patches for useful -tweaks and features. -@item -@i{Adam Spiers} asked for global linking commands, inspired the link -extension system, added support for mairix, and proposed the mapping API. -@item -@i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content -with links transformation to Org syntax. -@item -@i{David O'Toole} wrote @file{org-publish.el} and drafted the manual -chapter about publishing. -@item -@i{J@"urgen Vollmer} contributed code generating the table of contents -in HTML output. -@item -@i{Chris Wallace} provided a patch implementing the @samp{QUOTE} -keyword. -@item -@i{David Wainberg} suggested archiving, and improvements to the linking -system. -@item -@i{John Wiegley} wrote @file{emacs-wiki.el}, @file{planner.el}, and -@file{muse.el}, which have some overlap with Org. Initially the development -of Org was fully independent because I was not aware of the existence of -these packages. But with time I have occasionally looked at John's code and -learned a lot from it. John has also contributed a number of great ideas and -patches directly to Org, including the attachment system -(@file{org-attach.el}), integration with Apple Mail -(@file{org-mac-message.el}), and hierarchical dependencies of TODO items. -@item -@i{Carsten Wimmer} suggested some changes and helped fix a bug in -linking to Gnus. -@item -@i{Roland Winkler} requested additional key bindings to make Org -work on a tty. -@item -@i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks -and contributed various ideas and code snippets. -@end itemize - - -@node Main Index, Key Index, History and Acknowledgments, Top -@unnumbered The Main Index - -@printindex cp - -@node Key Index, , Main Index, Top -@unnumbered Key Index - -@printindex ky - -@bye - -@ignore - arch-tag: 7893d1Fe-cc57-4d13-b5e5-f494a1CBC7ac -@end ignore - -@c Local variables: -@c ispell-local-dictionary: "en_US-w_accents" -@c ispell-local-pdict: "./.aspell.org.pws" -@c fill-column: 77 -@c End: - diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi deleted file mode 100644 index 12194416659..00000000000 --- a/doc/misc/pcl-cvs.texi +++ /dev/null @@ -1,1438 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/pcl-cvs -@settitle PCL-CVS --- Emacs Front-End to CVS -@syncodeindex vr fn -@c %**end of header - -@copying -Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* PCL-CVS: (pcl-cvs). Emacs front-end to CVS. -@end direntry - -@c The titlepage section does not appear in the Info file. -@titlepage -@sp 4 -@c The title is printed in a large font. -@center @titlefont{User's Guide} -@sp -@center @titlefont{to} -@sp -@center @titlefont{PCL-CVS --- The Emacs Front-End to CVS} -@ignore -@sp 2 -@center release 2.9 -@c -release- -@end ignore -@sp 3 -@center Per Cederqvist -@center Stefan Monnier -@c -date- - -@c The following two commands start the copyright page -@c for the printed manual. This will not appear in the Info file. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c ================================================================ -@c The real text starts here -@c ================================================================ - -@node Top, About PCL-CVS, (dir), (dir) -@ifnottex -@top PCL-CVS - -This manual describes PCL-CVS, the GNU Emacs front-end to CVS. It -is nowhere near complete, so you are advised to use @kbd{M-x -customize-group RET pcl-cvs @key{RET}} and to look at the documentation strings -of the various commands and major modes for further information. -@c This manual is updated to release 2.5 of PCL-CVS. - -@insertcopying - -@end ifnottex - -@menu -* About PCL-CVS:: Credits, history, @dots{} - -* Getting started:: An introduction with a walk-through example. -* Buffer contents:: An explanation of the buffer contents. -* Selected files:: To which files are commands applied. -* Commands:: All commands, grouped by type. - -* Log Edit Mode:: Major mode to edit log messages. -* Log View Mode:: Major mode to browse log changes. -@c * CVS Status Mode:: Major mode to view CVS' status output. -* Customization:: How you can tailor PCL-CVS to suit your needs. -* Bugs:: Bugs (known and unknown). - -* GNU Free Documentation License:: The license for this documentation. -* Function and Variable Index:: List of functions and variables. -* Concept Index:: List of concepts. -* Key Index:: List of keystrokes. - -@detailmenu - --- The Detailed Node Listing --- - -About PCL-CVS - -* Contributors:: Contributors to PCL-CVS. - -Commands - -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. - -Customization - -* Customizing Faces:: - -@end detailmenu -@end menu - -@node About PCL-CVS, Getting started, Top, Top -@chapter About PCL-CVS -@cindex About PCL-CVS - -PCL-CVS is a front-end to CVS versions 1.9 and later. -It concisely shows the present status of a checked out module in an -Emacs buffer and provides single-key access to the most frequently used CVS -commands. -For Emacs users accustomed to VC, PCL-CVS can be thought of as a replacement -for VC-dired (@pxref{VC Directory Mode, , , emacs, The GNU -Emacs Manual}) specifically designed for CVS. - -PCL-CVS was originally written many years ago by Per Cederqvist who -proudly maintained it until January 1996, at which point he released the -beta version 2.0b2 and passed on the maintainership to Greg A Woods. -Development stayed mostly dormant for a few years during which -version 2.0 never seemed to be able to leave the ``beta'' stage while a -separate XEmacs version was slowly splitting away. In late 1998, -Stefan Monnier picked up development again, adding some major new -functionality and taking over the maintenance. - -@menu -* Contributors:: Contributors to PCL-CVS. -@end menu - -@node Contributors,, About PCL-CVS, About PCL-CVS -@section Contributors to PCL-CVS -@cindex Contributors -@cindex Authors - -Contributions to the package are welcome. I have limited time to work -on this project, but I will gladly add any code that you contribute to -me to this package (@pxref{Bugs}). - -The following persons have made contributions to PCL-CVS. - -@itemize @bullet -@item -Brian Berliner wrote CVS, together with some other contributors. -Without his work on CVS this package would be useless@dots{} - -@item -Per Cederqvist wrote most of the otherwise unattributed functions in -PCL-CVS as well as all the documentation. - -@item -@email{inge@@lysator.liu.se, Inge Wallin} wrote the skeleton of -@file{pcl-cvs.texi}, and gave useful comments on it. He also wrote -the files @file{elib-node.el} and @file{compile-all.el}. The file -@file{cookie.el} was inspired by Inge.@refill - -@item -@email{linus@@lysator.liu.se, Linus Tolke} contributed useful comments -on both the functionality and the documentation.@refill - -@item -@email{jwz@@jwz.com, Jamie Zawinski} contributed -@file{pcl-cvs-lucid.el}, which was later renamed to -@file{pcl-cvs-xemacs.el}.@refill - -@item -Leif Lonnblad contributed RCVS support (since superseded by the new -remote CVS support). - -@item -@email{jimb@@cyclic.com, Jim Blandy} contributed hooks to automatically -guess CVS log entries from @file{ChangeLog} contents, and initial support of -the new Cygnus / Cyclic remote CVS, as well as various sundry bug fixes -and cleanups. - -@item -@email{kingdon@@cyclic.com, Jim Kingdon} contributed lots of fixes to -the build and installation procedure. - -@item -@email{woods@@weird.com, Greg A.@: Woods} contributed code to implement -the use of per-file diff buffers, and vendor join diffs with emerge and -ediff, as well as various and sundry bug fixes and cleanups. - -@item -@email{greg.klanderman@@alum.mit.edu, Greg Klanderman} implemented -toggling of marked files, setting of CVS command flags via prefix -arguments, updated the XEmacs support, updated the manual, and fixed -numerous bugs. - -@item -@email{monnier@@gnu.org, Stefan Monnier} added a slew of other -features and introduced even more new bugs. If there's any bug left, -you can be sure it's his. - -@item -@c wordy to avoid an underfull hbox -@email{masata-y@@is.aist-nara.ac.jp, Masatake YAMATO} made a gracious -contribution of his cvstree code to display a tree of tags which was later -superseded by the new @code{cvs-status-mode}. -@end itemize - -Apart from these, a lot of people have sent us suggestions, ideas, -requests, bug reports and encouragement. Thanks a lot! Without you -there would be no new releases of PCL-CVS. - - -@node Getting started, Buffer contents, About PCL-CVS, Top -@chapter Getting started -@cindex Introduction -@cindex Example run -@cindex Sample session - -This document assumes that you know what CVS is, and that you at least -know the fundamental concepts of CVS. If that is not the case, you -should read the CVS documentation. Type @kbd{info -f cvs} or @kbd{man -cvs}. - -PCL-CVS is only useful once you have checked out a module. So before -you invoke it, you must have a copy of a module somewhere in the file -system. - -You can invoke PCL-CVS by typing @kbd{M-x cvs-examine @key{RET}}. -You can also invoke it via the menu bar, under @samp{Tools}. -Or, if you prefer, you can also invoke PCL-CVS by simply visiting the -CVS administrative subdirectory of your module, with a prefix argument. -For example, to invoke PCL-CVS in a separate frame, type @kbd{C-u C-x 5 -f ~/my/project/CVS @key{RET}}. - -The function @code{cvs-examine} will ask for a directory. The command -@samp{cvs -n update} will be run in that directory. (It should contain -files that have been checked out from a CVS archive.) The output from -@code{cvs} will be parsed and presented in a table in a buffer called -@samp{*cvs*}. It might look something like this: - -@example -Repository : /usr/CVSroot -Module : test -Working dir: /users/ceder/FOO/test - - -In directory .: - Need-Update bar - Need-Update file.txt - Modified namechange - Need-Update newer -In directory sub: - Modified ChangeLog - ---------------------- End --------------------- --- last cmd: cvs -f -z6 -n update -d -P -- -@end example - -In this example, your repository is in @file{/usr/CVSroot} and CVS has -been run in the directory @file{/users/ceder/FOO/test}. The three files -(@file{bar}, @file{file.txt} and -@file{newer}) that are marked with @samp{Need-Update} have been changed -by someone else in the CVS repository. Two files (@file{namechange} -and @file{sub/ChangeLog}) have been modified locally, and need to be -checked in. - -You can move the cursor up and down in the buffer with @kbd{C-n} and -@kbd{C-p} or @kbd{n} and @kbd{p}. If you press @kbd{c} on one of the -@samp{Modified} files, that file will be checked in to the CVS -repository. @xref{Committing changes}. You can also press @kbd{O} to -update any of the files that are marked @samp{Need-Update}. You can -also run @kbd{M-x cvs-update @key{RET}} (bound to @kbd{M-u} in the -@samp{*cvs*} buffer) to update all the files.@refill - -You can then press @kbd{=} to easily get a @samp{diff} between your -modified file and the base version that you started from, or you can -press @kbd{l} to get the output from @samp{cvs log}. Many more such -commands are available simply by pressing a key (@pxref{Getting info -about files}). - -@node Buffer contents, Selected files, Getting started, Top -@chapter Buffer contents -@cindex Buffer contents -@cindex @code{*cvs*} buffer contents - -The display contains several columns, some of which are optional. -These columns are, from left to right: - -@itemize @bullet - -@item -Optionally, the head revision of the file. This is the latest version -found in the repository. It might also contain (instead of the head -revision) a sub status which typically gives further information about -how we got to the current state, for example @samp{patched}, -@samp{merged}, @dots{} - -@item -An asterisk when the file is @dfn{marked} (@pxref{Selected -files}).@refill - -@item -The actual status of the file wrt the repository. See below. - -@item -Optionally, the base revision of the file. This is the version -which the copy in your working directory is based upon. - -@item -The file name. - -@end itemize - -The @samp{file status} field can have the following values: - -@table @samp -@item Modified -The file is modified in your working directory, and there was no -modification to the same file in the repository. This status can have -the following substatus: - -@table @samp -@item merged -The file was modified in your working directory, and there were -modifications in the repository as well, but they were merged -successfully, without conflict, in your working directory.@refill -@end table - -@item Conflict -A conflict was detected while trying to merge your changes to @var{file} -with changes from the repository. @var{file} (the copy in your -working directory) is now the output of the @code{rcsmerge} command on -the two versions; an unmodified copy of your file is also in your -working directory, with the name @file{.#@var{file}.@var{version}}, -where @var{version} is the RCS revision that your modified file started -from. @xref{Viewing differences}, for more details.@refill - -A conflict can also come from a disagreement on the existence of the file -rather than on its content. This case is indicated by the following -possible substatus: - -@table @samp -@item removed -The file is locally removed but a new revision has been committed to -the repository by someone else. - -@item added -The file is locally added and has also been added to the repository -by someone else. - -@item modified -The file is locally modified but someone else has removed it from the -repository. -@end table - -@item Added -The file has been added by you, but it still needs to be checked in to -the repository.@refill - -@item Removed -The file has been removed by you, but it still needs to be checked in to -the repository. You can resurrect it by typing @kbd{a} (@pxref{Adding -and removing files}).@refill - -@item Unknown -A file that was detected in your directory, but that neither appears in -the repository, nor is present on the list of files that CVS should -ignore.@refill - -@item Up-to-date -The file is up to date with respect to the version in the repository. -This status can have a substatus of: - -@table @samp -@item added -You have just added the file to the repository.@refill - -@item updated -The file was brought up to date with respect to the repository. This is -done for any file that exists in the repository but not in your source, -and for files that you haven't changed but are not the most recent -versions available in the repository.@refill - -@item patched -The file was brought up to date with respect to the remote repository by -way of fetching and applying a patch to the file in your source. This -is equivalent to @samp{updated} except that CVS decided to use a hopefully -more efficient method.@refill - -@item committed -You just committed the file.@refill -@end table - -@item Need-Update -Either a newer version than the one in your source is available in the -repository and you have not modified your checked out version, or the -file exists in the repository but not in your source. Use -@samp{cvs-mode-update} bound to @kbd{O} to update the file.@refill - -@item Need-Merge -You have modified the checked out version of the file, and a newer -version is available in the repository. A merge will take place when -you run a @samp{cvs-update}. - -@item Missing -The file has been unexpectedly removed from your working directory -although it has not been @samp{cvs remove}d. -@end table - -@node Selected files, Commands, Buffer contents, Top -@chapter Selected files -@cindex Selected files -@cindex Marked files -@cindex File selection -@cindex Active files -@cindex Applicable - -Many of the commands work on the current set of @dfn{selected} files -which can be either the set of marked files (if any file is marked and -marks are not ignored) or whichever file or directory the cursor is on. - -If a directory is selected but the command cannot be applied to a -directory, then it will be applied to the set of files under this -directory which are in the @samp{*cvs*} buffer. - -@findex cvs-mode-force-command -@findex cvs-allow-dir-commit -Furthermore, each command only operates on a subset of the selected -files, depending on whether or not the command is @dfn{applicable} to -each file (based on the file's status). For example, -@code{cvs-mode-commit} is not applicable to a file whose status is -@samp{Need-Update}. If it should happen that PCL-CVS guesses the -applicability wrong, you can override it with the special prefix -@code{cvs-mode-force-command} normally bound to @kbd{M-f} (and file a -bug report). The applicability rule can be slightly changed with -@code{cvs-allow-dir-commit} and @code{cvs-force-dir-tag}. - -By default, marks are always in effect (you may change this, however, by -setting the variable @code{cvs-default-ignore-marks}) except for the -commands that @samp{tag} or @samp{diff} a file (which can be changed -with the variable @code{cvs-invert-ignore-marks}). - -In addition, you may use the special prefix @code{cvs-mode-toggle-marks} -normally bound to @key{T} to toggle the use of marks for the following -command. - -This scheme might seem a little complicated, but once one gets used to -it, it is quite powerful. - -For commands to mark and unmark files, see @ref{Marking files}. - -@node Commands, Log Edit Mode, Selected files, Top -@chapter Commands - -@iftex -This chapter describes all the commands that you can use in PCL-CVS. -@end iftex -@ifnottex -The nodes in this menu contains explanations about all the commands that -you can use in PCL-CVS. They are grouped together by type. -@end ifnottex - -@menu -* Entering PCL-CVS:: Commands to invoke PCL-CVS -* Setting flags:: Setting flags for CVS commands -* Updating the buffer:: -* Movement commands:: How to move up and down in the buffer -* Marking files:: How to mark files that other commands - will later operate on. -* Committing changes:: Checking in your modifications to the - CVS repository. -* Editing files:: Loading files into Emacs. -* Getting info about files:: Display the log and status of files. -* Adding and removing files:: Adding and removing files -* Undoing changes:: Undoing changes -* Removing handled entries:: Uninteresting lines can easily be removed. -* Ignoring files:: Telling CVS to ignore generated files. -* Viewing differences:: Commands to @samp{diff} different versions. -* Invoking Ediff:: Running @samp{ediff} from @samp{*cvs*} buffer. -* Updating files:: Updating files that Need-update. -* Tagging files:: Tagging files. -* Miscellaneous commands:: Miscellaneous commands. -@end menu - - -@node Entering PCL-CVS, Setting flags, Commands, Commands -@section Entering PCL-CVS -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-checkout -@findex cvs-quickdir -@cindex Creating the *cvs* buffer - -Most commands in PCL-CVS require that you have a @samp{*cvs*} -buffer. The commands that you use to get one are listed below. -For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @samp{*cvs*} buffer (see -@ref{Buffer contents}, for a description of the buffer's contents). - -@table @kbd -@item M-x cvs-update -Run a @samp{cvs update} command. You will be asked for the directory -in which the @samp{cvs update} will be run. - -@item M-x cvs-examine -Run a @samp{cvs -n update} command. This is identical to the previous -command, except that it will only check what needs to be done but will -not change anything. You will be asked for the directory in -which the @samp{cvs -n update} will be run. - -@item M-x cvs-status -Run a @samp{cvs status} command. You will be asked for the directory -in which the @samp{cvs status} will be run. - -@item M-x cvs-checkout -Run a @samp{cvs checkout} command. You will be asked for the directory -in which the @samp{cvs update} will be run and the module to be checked -out. - -@item M-x cvs-quickdir -Populate the @samp{*cvs*} buffer by just looking at the @file{CVS/Entries} -files. This is very much like @code{cvs-examine} except that it does -not access the CVS repository, which is a major advantage when the -repository is far away. But of course, it will not be able to detect -when a file needs to be updated or merged. -@end table - -@findex cvs-dired-action -@findex cvs-dired-use-hook -The first four of -those commands are also reachable from the menu bar -under @samp{Tools->PCL-CVS}. Finally, an alternative way is to visit -the CVS administrative subdirectory in your work area with a simple -prefix argument. For example @kbd{C-u C-x C-f ~/my/work/CVS @key{RET}}. This -by default runs @code{cvs-quickdir} but the specific behavior can be -changed with @code{cvs-dired-action} and @code{cvs-dired-use-hook}. - -By default, the commands above will descend recursively into -subdirectories. You can avoid that behavior by including @samp{-l} in -the flags for the command. These flags can be set by giving a prefix -argument to the command (e.g., by typing -@kbd{C-u M-x cvs-update @key{RET} -l @key{RET}}). - - -@node Setting flags, Updating the buffer, Entering PCL-CVS, Commands -@section Setting flags for CVS commands -@cindex Optional switches to CVS -@cindex Command-line options to CVS - -This section describes the convention used by nearly all PCL-CVS -commands for setting optional flags sent to CVS. A single @kbd{C-u} -prefix argument is used to cause the command to prompt for flags to be -used for the current invocation of the command only. Two @kbd{C-u} prefix -arguments are used to prompt for flags which will be set permanently, for the -current invocation and all that follow, until the flags are changed, or -unless temporary flags are set which override them. - -Perhaps an example or two is in order. Say you are about to add a -binary file to the repository, and want to specify the flags @samp{-kb} -to @samp{cvs add}. You can type @kbd{C-u a -kb @key{RET}}, -and the file will be added. Subsequent @samp{cvs add} -commands will use the previously prevailing flags. - -As a second example, say you are about to perform a diff and want to see -the result in unified diff format, i.e. you'd like to pass the flag -@samp{-u} to both @samp{cvs diff} and @samp{diff}. You'd also like all -subsequent diffs to use this flag. You can type @kbd{C-u C-u = -u @key{RET}} -and the diff will be performed, and the default flags will be set to -@code{("-u")}. You can of course override this flag for a single diff -by using a single @kbd{C-u} prefix argument. - -@cindex Special prefix -In addition to this, some commands can take @dfn{special prefix} arguments. -These work as follows: When called with a @kbd{C-u} prefix, the user is -prompted for a new value of the special prefix and the special prefix is -activated for the next command. When called without the @kbd{C-u} -prefix, the special prefix is re-activated (with the same value as last -time) for the next command. Calling the prefix command again when it's -already activated deactivates it. Calling it with the @kbd{C-u C-u} -prefix activates it for all subsequent commands until you deactivate it -explicitly. The special prefixes are: - -@table @kbd -@item T -Toggles whether or not marks will be active in the next command.@refill - -@item b -Provide the next command with a branch (can be any version -specifier) to work on.@refill - -@item B -Secondary branch argument. Only meaningful if @kbd{b} is also used. -It can be used to provide a second branch argument to -@code{cvs-mode-diff} or to @code{cvs-mode-update}. - -@item M-f -Forces the next command to apply to every selected file rather than only -to the ones PCL-CVS thinks are relevant. -@end table - -@node Updating the buffer, Movement commands, Setting flags, Commands -@section Updating the @samp{*cvs*} buffer -@findex cvs-update -@findex cvs-examine -@findex cvs-status -@findex cvs-mode-update -@findex cvs-mode-examine -@findex cvs-mode-status - -The following commands can be used from within the @samp{*cvs*} buffer -to update the display: - -@table @kbd -@item M-u -Runs the command @samp{cvs-update}.@refill - -@item M-e -Runs the command @samp{cvs-examine}.@refill - -@item M-s -Runs the command @samp{cvs-status}.@refill -@end table - -In addition to the above commands which operate on the whole module, -you can run the equivalent CVS command on just a subset of the -files/directories with these keys: - -@table @kbd -@item O -Runs @code{cvs-mode-update} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-u}.@refill - -@item e -Runs @code{cvs-mode-examine} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-e}.@refill - -@findex cvs-status-mode -@item s -Runs @code{cvs-mode-status} on the selected files. When run on the -top-level directory, this is equivalent to @kbd{M-s}, except that -CVS output will be shown in a @samp{*cvs-info*} buffer that will be -put in @samp{cvs-status-mode}.@refill -@end table - - -@node Movement commands, Marking files, Updating the buffer, Commands -@section Movement Commands -@cindex Movement Commands -@findex cvs-mode-next-line -@findex cvs-mode-previous-line -@kindex SPC@r{--Move down one file} -@kindex n@r{--Move down one file} -@kindex p@r{--Move up one file} - -You can use most normal Emacs commands to move forward and backward in -the buffer. Some keys are rebound to functions that take advantage of -the fact that the buffer is a PCL-CVS buffer: - - -@table @kbd -@item @key{SPC} -@itemx n -These keys move the cursor one file forward, towards the end of the -buffer (@code{cvs-mode-next-line}).@refill - -@itemx p -This key moves one file backward, towards the beginning of the buffer -(@code{cvs-mode-previous-line}). -@end table - - -@node Marking files, Committing changes, Movement commands, Commands -@section Marking files -@cindex Selecting files (commands to mark files) -@cindex Marking files -@kindex m@r{--marking a file} -@kindex M@r{--marking all files} -@kindex u@r{--unmark a file} -@kindex ESC DEL@r{--unmark all files} -@kindex DEL@r{--unmark previous file} -@kindex %@r{--mark files matching regexp} -@kindex S@r{--mark files in a particular state} -@kindex T@r{--toggle marks} -@findex cvs-mode-mark -@findex cvs-mode-unmark -@findex cvs-mode-mark-all-files -@findex cvs-mode-unmark-all-files -@findex cvs-mode-unmark-up -@findex cvs-mode-mark-matching-files -@findex cvs-mode-mark-on-state -@findex cvs-mode-toggle-marks - -PCL-CVS works on a set of @dfn{selected files} (@pxref{Selected files}). -You can mark and unmark files with these commands: - -@table @kbd -@item m -This marks the file that the cursor is positioned on. If the cursor is -positioned on a directory all files in that directory are marked -(@code{cvs-mode-mark}).@refill - -@item u -Unmark the file that the cursor is positioned on. If the cursor is on a -directory, all files in that directory are unmarked -(@code{cvs-mode-unmark}).@refill - -@item M -Mark @emph{all} files in the buffer (@code{cvs-mode-mark-all-files}). - -@item M-@key{DEL} -Unmark @emph{all} files (@code{cvs-mode-unmark-all-files}). - -@item @key{DEL} -Unmark the file on the previous line, and move point to that line -(@code{cvs-mode-unmark-up}). - -@item % -Mark all files matching a regular expression -(@code{cvs-mode-mark-matching-files}). - -@item S -Mark all files in a particular state, such as ``Modified'' or -``Removed'' (@code{cvs-mode-mark-on-state}). - -@item T -Toggle use of marks for the next command (@code{cvs-mode-toggle-marks}). -@end table - - -@node Committing changes, Editing files, Marking files, Commands -@section Committing changes -@cindex Committing changes -@findex cvs-mode-commit -@findex cvs-mode-commit-setup -@kindex c@r{--commit files} -@kindex C@r{--commit files with @file{ChangeLog} message} -@vindex cvs-auto-revert@r{ (variable)} -@cindex Commit buffer -@cindex Edit buffer -@cindex Erasing commit message -@cindex Reverting buffers after commit - -Committing changes basically works as follows: - -@enumerate -@item -After having selected the files you want to commit, you type either -@kbd{c} or @kbd{C} which brings up a special buffer -@samp{*cvs-commit*}.@refill - -@item -You type in the log message describing the changes you're about to -commit (@pxref{Log Edit Mode}). - -@item -When you're happy with it, you type @kbd{C-c C-c} to do the actual -commit.@refill -@end enumerate - -There's no hidden state, so you can abort the process or pick it up -again at any time. - -@vindex log-edit-confirm@r{ (variable)} -The set of files actually committed is really decided only during the -very last step, which is a mixed blessing. It allows you to go back and -change your mind about which files to commit, but it also means that you -might inadvertently change the set of selected files. To reduce the -risk of error, @kbd{C-c C-c} will ask for confirmation if the set of -selected files has changed between the first step and the last. You can -change this last detail with @code{log-edit-confirm}. - -As for the difference between @kbd{c} (i.e. @code{cvs-mode-commit}) and -@kbd{C} (i.e. @code{cvs-mode-commit-setup}) is that the first gets you -straight to @samp{*cvs-commit*} without erasing it or changing anything -to its content, while the second first erases @samp{*cvs-commit*} -and tries to initialize it with a sane default (it does that by either -using a template provided by the CVS administrator or by extracting a -relevant log message from a @file{ChangeLog} file). - -If you are editing the files in your Emacs, an automatic -@samp{revert-buffer} will be performed. (If the file contains -@samp{$@asis{Id}$} keywords, @samp{cvs commit} will write a new file with -the new values substituted. The auto-revert makes sure that you get -them into your buffer.) The revert will not occur if you have modified -your buffer, or if @samp{cvs-auto-revert} is set to -@samp{nil}. - - -@node Editing files, Getting info about files, Committing changes, Commands -@section Editing files -@cindex Editing files -@cindex Finding files -@cindex Loading files -@cindex Dired -@cindex Invoking dired -@findex cvs-mode-find-file -@findex cvs-mode-find-file-other-window -@findex cvs-mode-add-change-log-entry-other-window -@kindex f@r{--find file or directory} -@kindex o@r{--find file in other window} -@kindex A@r{--add @file{ChangeLog} entry} - -There are currently three commands that can be used to find a file (that -is, load it into a buffer and start editing it there). These commands -work on the line that the cursor is situated at. They always ignore any marked -files. - -@table @kbd -@item f -Find the file that the cursor points to (@code{cvs-mode-find-file}). If -the cursor points to a directory, run @code{dired} on that directory; -@inforef{Dired, , emacs}. - -@item o -Like @kbd{f}, but use another window -(@code{cvs-mode-find-file-other-window}).@refill - -@item A -Invoke @samp{add-change-log-entry-other-window} to edit a -@file{ChangeLog} file. The @file{ChangeLog} file will be found in the -directory of the file the cursor points to, or in a parent of that -directory (@code{cvs-mode-add-change-log-entry-other-window}).@refill -@end table - - -@node Getting info about files, Adding and removing files, Editing files, Commands -@section Getting info about files -@cindex Status (cvs command) -@cindex Log (RCS/cvs command) -@cindex Getting status -@kindex l@r{--run @samp{cvs log}} -@kindex s@r{--run @samp{cvs status}} -@findex cvs-mode-log -@findex cvs-mode-status - -@table @kbd -@item l -Call the command @code{cvs-mode-log} which runs @samp{cvs log} on all -selected files, and show the result in a temporary buffer -@samp{*cvs-info*} (@pxref{Log View Mode}). - -@item s -Call the command @code{cvs-mode-status} which runs @samp{cvs status} on -all selected files, and show the result in a temporary buffer -@samp{*cvs-info*}. -@c Fixme: reinstate when node is written: -@c (@pxref{CVS Status Mode}). -@end table - - -@node Adding and removing files, Undoing changes, Getting info about files, Commands -@section Adding and removing files -@cindex Adding files -@cindex Removing files -@cindex Resurrecting files -@cindex Deleting files -@cindex Putting files under CVS control -@kindex a@r{--add a file} -@kindex r@r{--remove a file} -@findex cvs-mode-add -@findex cvs-mode-remove-file - -The following commands are available to make it easy to add files to -and remove them from the CVS repository. - -@table @kbd -@item a -Add all selected files. This command can be used on @samp{Unknown} -files (@pxref{Buffer contents}). The status of the file will change to -@samp{Added}, and you will have to use @kbd{c} (@samp{cvs-mode-commit} -@pxref{Committing changes}), to really add the file to the -repository.@refill - -This command can also be used on @samp{Removed} files (before you commit -them) to resurrect them. - -The command that is run is @code{cvs-mode-add}. - -@item r -This command removes the selected files (after prompting for -confirmation). The files are deleted from your directory and -(unless the status was @samp{Unknown}; @pxref{Buffer contents}) they will -also be @samp{cvs remove}d. If the files' status was @samp{Unknown} -they will disappear from the buffer. Otherwise their status will change to -@samp{Removed}, and you must use @kbd{c} (@samp{cvs-mode-commit}, -@pxref{Committing changes}) to commit the removal.@refill - -The command that is run is @code{cvs-mode-remove-file}. -@end table - - -@node Undoing changes, Removing handled entries, Adding and removing files, Commands -@section Undoing changes -@cindex Undo changes -@cindex Flush changes -@kindex U@r{--undo changes} -@findex cvs-mode-undo-local-changes - -@table @kbd -@item U -If you have modified a file, and for some reason decide that you don't -want to keep the changes, you can undo them with this command. It works -by removing your working copy of the file and then getting the latest -version from the repository (@code{cvs-mode-undo-local-changes}). -@end table - - -@node Removing handled entries, Ignoring files, Undoing changes, Commands -@section Removing handled entries -@cindex Expunging uninteresting entries -@cindex Uninteresting entries, getting rid of them -@cindex Getting rid of uninteresting lines -@cindex Removing uninteresting (processed) lines -@cindex Handled lines, removing them -@kindex x@r{--remove processed entries} -@kindex C-k@r{--remove selected entries} -@findex cvs-mode-remove-handled -@findex cvs-mode-acknowledge -@findex cvs-mode-ignore - -@table @kbd -@item x -This command allows you to remove all entries that you have processed. -More specifically, the lines for @samp{Up-to-date} files (@pxref{Buffer -contents}) are removed from the buffer. If a directory becomes empty -the heading for that directory is also removed. This makes it easier to -get an overview of what needs to be done. - -@vindex cvs-mode-remove-handled@r{ (variable)} -@kbd{x} invokes @code{cvs-mode-remove-handled}. If -@samp{cvs-auto-remove-handled} is set to non-@code{nil}, this will -automatically be performed after every commit.@refill - -@item C-k -This command can be used for lines that @samp{cvs-mode-remove-handled} would -not delete, but that you want to delete (@code{cvs-mode-acknowledge}). -@end table - - -@node Ignoring files, Viewing differences, Removing handled entries, Commands -@section Ignoring files -@cindex Ignoring files -@kindex i@r{--ignoring files} -@findex cvs-mode-ignore - -@table @kbd -@item i -Arrange so that CVS will ignore the selected files. The file names are -added to the @file{.cvsignore} file in the corresponding directory. If -the @file{.cvsignore} file doesn't exist, it will be created. - -The @file{.cvsignore} file should normally be added to the repository, -but you could ignore it as well, if you like it better that way. - -This runs @code{cvs-mode-ignore}. -@end table - -@node Viewing differences, Invoking Ediff, Ignoring files, Commands -@section Viewing differences -@cindex Diff -@cindex Invoking @code{diff} -@cindex Conflicts, how to resolve them -@cindex Viewing differences -@kindex d=@r{--run @samp{cvs diff}} -@kindex =@r{--run @samp{cvs diff}} -@kindex db@r{--diff against base version} -@kindex dh@r{--diff against head of repository} -@kindex dr@r{--diff between base and head of repository} -@kindex dv@r{--diff against vendor branch} -@kindex dy@r{--diff against yesterday's head} -@findex cvs-mode-diff -@findex cvs-mode-diff-backup -@findex cvs-mode-diff-head -@findex cvs-mode-diff-repository -@findex cvs-mode-diff-vendor -@findex cvs-mode-diff-yesterday -@vindex cvs-invert-ignore-marks@r{ (variable)} - -@table @kbd -@item = -@itemx d = -Display a @samp{cvs diff} between the selected files and the version -that they are based on (@code{cvs-mode-diff}).@refill - -@item d b -If CVS finds a conflict while merging two versions of a file (during a -@samp{cvs update}, @pxref{Updating the buffer}) it will save the -original file in a file called @file{.#@var{file}.@var{version}} where -@var{file} is the name of the file, and @var{version} is the revision -number that @var{file} was based on.@refill - -With the @kbd{d b} command you can run a @samp{diff} on the files -@file{.#@var{file}.@var{version}} and @file{@var{file}}.@refill - -@item d h -Display a @samp{cvs diff} between the selected files and the head -revision (the most recent version on the current -branch) in the repository (@code{cvs-mode-diff-head}).@refill - -@item d r -Display a @samp{cvs diff} between the base revision of the selected -files and the head revision in the repository. This displays the -changes anyone has committed to the repository since you last executed -a checkout, update or commit operation -(@code{cvs-mode-diff-repository}). - -@item d v -Display a @samp{cvs diff} between the selected files and the head -revision of the vendor branch in the repository -(@code{cvs-mode-diff-vendor}).@refill - -@item d y -Display a @samp{cvs diff} between the selected files and yesterday's -head revision in the repository -(@code{cvs-mode-diff-yesterday}).@refill -@end table - -By default, @samp{diff} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. - -@node Invoking Ediff, Updating files, Viewing differences, Commands -@section Running ediff -@cindex Ediff -@cindex Invoking ediff -@cindex Viewing differences -@cindex Conflicts, how to resolve them -@cindex Resolving conflicts -@kindex e@r{--invoke @samp{ediff}} -@findex cvs-mode-idiff -@findex cvs-mode-imerge - -@table @kbd -@vindex cvs-idiff-imerge-handlers@r{ (variable)} -@item d e -This uses @code{ediff} (or @code{emerge}, depending on -@samp{cvs-idiff-imerge-handlers}) to allow you to view diffs. -If a prefix argument is given, PCL-CVS will prompt for a revision against -which the diff should be made, else the default will be to use the BASE -revision. - -@cindex Merging with @code{ediff} and @code{emerge} -@item d E -This command use @code{ediff} (or @code{emerge}, see above) to allow you -to do an interactive 3-way merge. - -@strong{Please note:} when the file status is @samp{Conflict}, -CVS has already performed a merge. The resulting file is not used in -any way if you use this command. If you use the @kbd{q} command inside -@samp{ediff} (to successfully terminate a merge) the file that CVS -created will be overwritten.@refill -@end table - -@node Updating files, Tagging files, Invoking Ediff, Commands -@section Updating files -@findex cvs-mode-update -@cindex Updating files -@kindex O@r{--update files} - -@table @kbd -@item O -Update all selected files with status @samp{Need-update} by running -@samp{cvs update} on them (@code{cvs-mode-update}). -@end table - - -@node Tagging files, Miscellaneous commands, Updating files, Commands -@section Tagging files -@findex cvs-mode-tag -@findex cvs-mode-untag -@findex cvs-rtag -@cindex Tagging files -@kindex M-t@r{--repository tag files} -@kindex t@r{--tag files} -@vindex cvs-invert-ignore-marks@r{ (variable)} -@vindex cvs-force-dir-tag@r{ (variable)} - -@table @kbd -@item t -Tag all selected files by running @samp{cvs tag} on -them (@code{cvs-mode-tag}). It's usually preferable to tag a directory -at a time. Rather than selecting all files (which too often doesn't -select all files but only the few that are displayed), clear the -selection with @kbd{M-DEL} (@code{cvs-mode-unmark-all-files}), position -the cursor on the directory you want to tag and hit @kbd{t}. -@end table - -By default, @samp{tag} commands ignore the marks. This can be changed -with @code{cvs-invert-ignore-marks}. Also, by default @samp{tag} can -only be applied to directories, see @code{cvs-force-dir-tag} if you want -to change this behavior. - - -@node Miscellaneous commands, , Tagging files, Commands -@section Miscellaneous commands -@findex cvs-mode-byte-compile-files -@cindex Recompiling elisp files -@cindex Byte compilation -@findex cvs-mode-delete-lock -@cindex Getting rid of lock files -@cindex Lock files -@kindex q@r{--bury the PCL-CVS buffer} -@findex cvs-bury-buffer -@findex cvs-mode-quit -@cindex Quitting -@kindex h@r{--help} -@kindex ?@r{--help} -@findex cvs-help -@cindex Help - -@table @kbd -@item M-x cvs-mode-byte-compile-files -Byte compile all selected files that end in @file{.el}. - -@item M-x cvs-mode-delete-lock -This command deletes the lock files that -the @samp{*cvs*} buffer informs you about. You should normally never have to -use this command, since CVS tries very carefully to always remove the -lock files itself. - -You can only use this command when a message in the @samp{*cvs*} buffer tells -you so. You should wait a while before using this command in case -someone else is running a @code{cvs} command. - -Also note that this only works if the repository is local. - -@item ? -@itemx h -Show a summary of common command key bindings in the echo -area (@code{cvs-help}). - -@item q -Bury the PCL-CVS buffer (@code{cvs-bury-buffer}). - -@item M-x cvs-mode-quit -Quit PCL-CVS, killing the @samp{*cvs*} buffer. -@end table - -@node Log Edit Mode, Log View Mode, Commands, Top -@chapter Editing a Log Message - -@cindex Log Edit mode -@cindex mode, Log Edit -Buffers for entering/editing log messages for changes which are about -to be committed are put into Log Edit mode. - -Sometimes the log buffer contains default text when you enter it, -typically the last log message entered. If it does, mark and point -are set around the entire contents of the buffer so that it is easy to -kill the contents of the buffer with @kbd{C-w}. - -@findex log-edit-insert-changelog -If you work by writing entries in the @file{ChangeLog} -(@pxref{(emacs)Change Log}) and then commit the change under revision -control, you can generate the Log Edit text from the ChangeLog using -@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for -entries for the file(s) concerned in the top entry in the ChangeLog -and uses those paragraphs as the log text. This text is only inserted -if the top entry was made under your user name on the current date. -@xref{(emacs)Change Logs and VC}, for the opposite way of -working---generating ChangeLog entries from the revision control log. - -In the Log Edit buffer, @kbd{C-c C-f} (@kbd{M-x log-edit-show-files}) -shows the list of files to be committed in case you need to check -that. - -When you have finished editing the log message, type @kbd{C-c C-c} to -exit the buffer and commit the change. - -@c Fixme: customization variables - -@node Log View Mode, Customization, Log Edit Mode, Top -@chapter Browsing a Log of Changes - -@cindex Log View mode -@cindex mode, Log View -@cindex output, logs - -@findex cvs-mode-log -@findex vc-print-log -Log View mode provides a few useful commands for navigating revision -control log output. It is used for the output buffers of both -@code{cvs-mode-log} and @code{vc-print-log}. - -In this mode, @kbd{n} goes to the next message and @kbd{p} goes to the -previous message and @kbd{N} and @kbd{P} go to the next and previous -files, respectively, in multi-file output. With a numeric prefix -argument, these commands move that many messages of files. - -@c @node CVS Status Mode -@c @chapter Viewing CVS' Status output - -@node Customization, Bugs, Log View Mode, Top -@chapter Customization -@vindex log-edit-changelog-full-paragraphs@r{ (variable)} -@vindex cvs-auto-remove-handled@r{ (variable)} -@vindex cvs-auto-remove-directories@r{ (variable)} -@vindex cvs-update-prog-output-skip-regexp@r{ (variable)} -@vindex cvs-cvsroot@r{ (variable)} -@vindex cvs-auto-revert@r{ (variable)} -@vindex log-edit-require-final-newline@r{ (variable)} -@vindex cvs-sort-ignore-file@r{ (variable)} -@cindex Customization -@cindex Variables, list of all -@cindex Erasing input buffer -@cindex Context diff, how to get -@cindex Unidiff, how to get -@cindex Automatically remove handled files -@cindex @samp{-u} option in modules file -@cindex Modules file (@samp{-u} option) -@cindex Update program (@samp{-u} option in modules file) -@cindex Reverting buffers after commit -@cindex Require final newline -@cindex Automatically inserting newline -@cindex Commit message, inserting newline -@cindex Sorting @file{.cvsignore} file -@cindex @file{.cvsignore} file, sorting -@cindex Automatically sorting @file{.cvsignore} -@cindex @samp{CVSROOT}, overriding - -If you have an idea about any customization that would be handy but -isn't present in this list, please tell us! -For info on how to reach us, see @ref{Bugs}.@refill - -@table @samp -@item cvs-auto-remove-handled -If this variable is set to any non-@code{nil} value, -@samp{cvs-mode-remove-handled} will be called every time you check in -files, after the check-in is ready. @xref{Removing handled -entries}.@refill - -@item cvs-auto-remove-directories -If this variable is set to any non-@code{nil} value, directories that do -not contain any files to be checked in will not be listed in the -@samp{*cvs*} buffer.@refill - -@item cvs-auto-revert -If this variable is set to any non-@samp{nil} value any buffers you have -that visit a file that is committed will be automatically reverted. -This variable defaults to @samp{t}. @xref{Committing changes}.@refill - -@item cvs-update-prog-output-skip-regexp -The @samp{-u} flag in the @file{modules} file can be used to run a command -whenever a @samp{cvs update} is performed (see @code{cvs(5)}). This regexp -is used to search for the last line in that output. It is normally set -to @samp{$}. That setting is only correct if the command outputs -nothing. Note that PCL-CVS will get very confused if the command -outputs @emph{anything} to @code{stderr}. - -@item cvs-cvsroot -This variable can be set to override @samp{CVSROOT}. It should be a -string. If it is set, then every time a @code{cvs} command is run, it -will be called as @samp{cvs -d @var{cvs-cvsroot}@dots{}}. This can be -useful if your site has several repositories. - -@item log-edit-require-final-newline -@c wordy to avoid unhderfull hbox -When you enter a log message by typing into the -@samp{*cvs-commit-message*} buffer, PCL-CVS normally automatically -inserts a trailing newline, unless there already is one. This behavior -can be controlled via @samp{cvs-commit-buffer-require-final-newline}. -If it is @samp{t} (the default behavior), a newline will always be -appended. If it is @samp{nil}, newlines will never be appended. Any -other value causes PCL-CVS to ask the user whenever there is no trailing -newline in the commit message buffer. - -@findex cvs-mode-changelog-commit -@item log-edit-changelog-full-paragraphs -If this variable is non-@code{nil}, include full @file{ChangeLog} -paragraphs in the CVS log created by @samp{cvs-mode-changelog-commit}. -This may be set in the local variables section of a @file{ChangeLog} -file, to indicate the policy for that @file{ChangeLog}. - -@cindex @file{ChangeLog} paragraphs -A @dfn{@file{ChangeLog} paragraph} is a bunch of log text containing no -blank lines; a paragraph usually describes a set of changes with a -single purpose, but perhaps spanning several functions in several files. -Changes in different paragraphs are unrelated. - -You could argue that the CVS log entry for a file should contain the -full @file{ChangeLog} paragraph mentioning the change to the file, even though -it may mention other files, because that gives you the full context you -need to understand the change. This is the behavior you get when this -variable is set to @code{t}, the default. - -On the other hand, you could argue that the CVS log entry for a change -should contain only the text for the changes which occurred in that -file, because the CVS log is per-file. This is the behavior you get -when this variable is set to @code{nil}. - -@findex cvs-mode-ignore@r{, and @file{.cvsignore} sorting} -@item cvs-sort-ignore-file -If this variable is set to any non-@samp{nil} value, the -@file{.cvsignore} file will always be sorted whenever you use -@samp{cvs-mode-ignore} to add a file to it. This option is on by -default. -@end table - - -@menu -* Customizing Faces:: -@end menu - -@node Customizing Faces, , Customization, Customization -@section Customizing Faces -@vindex cvs-header (face) -@vindex cvs-filename (face) -@vindex cvs-unknown (face) -@vindex cvs-handled (face) -@vindex cvs-need-action (face) -@vindex cvs-marked (face) -@vindex cvs-msg (face) - -PCL-CVS adds a few extra features, including menus, mouse bindings, and -fontification of the @samp{*cvs*} buffer. The faces defined for -fontification are listed below: - -@table @samp -@item cvs-header -used to highlight directory changes. - -@item cvs-filename -Used to highlight file names. - -@item cvs-unknown -Used to highlight the status of files which are @samp{Unknown}. - -@item cvs-handled -Used to highlight the status of files which are handled and -need no further action. - -@item cvs-need-action -Used to highlight the status of files which still need action. - -@item cvs-marked -Used to highlight the marked file indicator (@samp{*}). - -@item cvs-msg -Used to highlight CVS messages. -@end table - - -@node Bugs, GNU Free Documentation License, Customization, Top -@chapter Bugs (known and unknown) -@cindex Reporting bugs and ideas -@cindex Bugs, how to report them -@cindex Author, how to reach -@cindex Email to the author -@cindex Known bugs -@cindex Bugs, known -@cindex FAQ -@cindex Problems, list of common - -If you find a bug or misfeature, don't hesitate to tell us! Send email -to @email{bug-gnu-emacs@@gnu.org} which is gatewayed to the newsgroup -@samp{gnu.emacs.bugs}. Feature requests should also be sent there. We -prefer discussing one thing at a time. If you find several unrelated -bugs, please report them separately. If you are running PCL-CVS under -XEmacs, you should also send a copy of bug reports to -@email{xemacs-beta@@xemacs.org}. - -If you have problems using PCL-CVS or other questions, send them to -@email{help-gnu-emacs@@gnu.org}, which is gatewayed to the -@samp{gnu.emacs.help} newsgroup. This is a good place to get help, as -is @email{cvs-info@@gnu.org}, gatewayed to @samp{gnu.cvs.help}. - -If you have ideas for improvements, or if you have written some -extensions to this package, we would like to hear from you. We hope that -you find this package useful! - -Below is a partial list of currently known problems with PCL-CVS. - -@table @asis -@item Unexpected output from CVS -Unexpected output from CVS may confuse PCL-CVS. It will create -warning messages in the @samp{*cvs*} buffer alerting you to any parse errors. -If you get these messages, please send a bug report to the email -addresses listed above. Include the contents of the @samp{*cvs*} buffer, the -output of the CVS process (which should be found in the @samp{ *cvs-tmp*} -buffer), and the versions of Emacs, PCL-CVS and CVS you are using. -@end table - -@node GNU Free Documentation License, Function and Variable Index, Bugs, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - - -@node Function and Variable Index, Concept Index, GNU Free Documentation License, Top -@unnumbered Function and Variable Index - -This is an index of all the functions and variables documented in this -manual. - -@printindex fn - -@node Concept Index, Key Index, Function and Variable Index, Top -@unnumbered Concept Index - -This is an index of concepts discussed in this manual. - -@printindex cp - -@node Key Index, , Concept Index, Top -@unnumbered Key Index - -This index includes an entry for each PCL-CVS key sequence documented in -this manual. - -@printindex ky - -@bye - -@ignore - arch-tag: 5c7178ce-56fa-40b0-abd7-f4a09758b235 -@end ignore diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi deleted file mode 100644 index 11b03924139..00000000000 --- a/doc/misc/pgg.texi +++ /dev/null @@ -1,503 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/pgg -@settitle PGG @value{VERSION} - -@set VERSION 0.1 - -@copying -This file describes PGG @value{VERSION}, an Emacs interface to various -PGP implementations. - -Copyright @copyright{} 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* PGG: (pgg). Emacs interface to various PGP implementations. -@end direntry - -@titlepage -@title PGG - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top PGG - -PGG is an interface library between Emacs -and various tools for secure communication. PGG also provides a simple -user interface to encrypt, decrypt, sign, and verify MIME messages. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What PGG is. -* Prerequisites:: Complicated stuff you may have to do. -* How to use:: Getting started quickly. -* Architecture:: -* Parsing OpenPGP packets:: -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -PGG is an interface library between Emacs and various tools for secure -communication. Even though Mailcrypt has similar feature, it does not -deal with detached PGP messages, normally used in PGP/MIME -infrastructure. This was the main reason why I wrote the new library. - -PGP/MIME is an application of MIME Object Security Services (RFC1848). -The standard is documented in RFC2015. - -@node Prerequisites -@chapter Prerequisites - -PGG requires at least one implementation of privacy guard system. -This document assumes that you have already obtained and installed them -and that you are familiar with its basic functions. - -By default, PGG uses GnuPG. If you are new to such a system, I -recommend that you should look over the GNU Privacy Handbook (GPH) -which is available at @uref{http://www.gnupg.org/documentation/}. - -When using GnuPG, we recommend the use of the @code{gpg-agent} -program, which is distributed with versions 2.0 and later of GnuPG. -This is a daemon to manage private keys independently from any -protocol, and provides the most secure way to input and cache your -passphrases (@pxref{Caching passphrase}). By default, PGG will -attempt to use @code{gpg-agent} if it is running. @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -PGG also supports Pretty Good Privacy version 2 or version 5. - -@node How to use -@chapter How to use - -The toplevel interface of this library is quite simple, and only -intended to use with public-key cryptographic operation. - -To use PGG, evaluate following expression at the beginning of your -application program. - -@lisp -(require 'pgg) -@end lisp - -If you want to check existence of pgg.el at runtime, instead you can -list autoload setting for desired functions as follows. - -@lisp -(autoload 'pgg-encrypt-region "pgg" - "Encrypt the current region." t) -(autoload 'pgg-encrypt-symmetric-region "pgg" - "Encrypt the current region with symmetric algorithm." t) -(autoload 'pgg-decrypt-region "pgg" - "Decrypt the current region." t) -(autoload 'pgg-sign-region "pgg" - "Sign the current region." t) -(autoload 'pgg-verify-region "pgg" - "Verify the current region." t) -(autoload 'pgg-insert-key "pgg" - "Insert the ASCII armored public key." t) -(autoload 'pgg-snarf-keys-region "pgg" - "Import public keys in the current region." t) -@end lisp - -@menu -* User Commands:: -* Selecting an implementation:: -* Caching passphrase:: -* Default user identity:: -@end menu - -@node User Commands -@section User Commands - -At this time you can use some cryptographic commands. The behavior of -these commands relies on a fashion of invocation because they are also -intended to be used as library functions. In case you don't have the -signer's public key, for example, the function @code{pgg-verify-region} -fails immediately, but if the function had been called interactively, it -would ask you to retrieve the signer's public key from the server. - -@deffn Command pgg-encrypt-region start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. When the function were called interactively, you -would be asked about the recipients. - -If encryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional argument @var{sign} is non-@code{nil}, the function is -request to do a combined sign and encrypt. This currently is -confirmed to work with GnuPG, but might not work with PGP or PGP5. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-encrypt-symmetric-region &optional start end passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher. After invocation you are asked for a passphrase. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. - -symmetric-cipher encryption is currently only implemented for GnuPG. -@end deffn - -@deffn Command pgg-decrypt-region start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-sign-region start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, or the -function is called interactively, it does not create a detached -signature. In such a case, it replaces the current region contents (in -the accessible portion) with the resulting data. - -If optional @var{passphrase} is @code{nil}, the passphrase will be -obtained from the passphrase cache or user. -@end deffn - -@deffn Command pgg-verify-region start end &optional signature fetch -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature file of the current region. - -If the optional 4th argument @var{fetch} is non-@code{nil}, or the -function is called interactively, we attempt to fetch the signer's -public key from the key server. -@end deffn - -@deffn Command pgg-insert-key -Retrieve the user's public key and insert it as ASCII-armored format. -@end deffn - -@deffn Command pgg-snarf-keys-region start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -@end deffn - -@node Selecting an implementation -@section Selecting an implementation - -Since PGP has a long history and there are a number of PGP -implementations available today, the function which each one has differs -considerably. For example, if you are using GnuPG, you know you can -select cipher algorithm from 3DES, CAST5, BLOWFISH, and so on, but on -the other hand the version 2 of PGP only supports IDEA. - -Which implementation is used is controlled by the @code{pgg-scheme} -variable. If it is @code{nil} (the default), the value of the -@code{pgg-default-scheme} variable will be used instead. - -@defvar pgg-scheme -Force specify the scheme of PGP implementation. The value can be set to -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{nil}. -@end defvar - -@defvar pgg-default-scheme -The default scheme of PGP implementation. The value should be one of -@code{gpg}, @code{pgp}, and @code{pgp5}. The default is @code{gpg}. -@end defvar - -@node Caching passphrase -@section Caching passphrase - -When using GnuPG (gpg) as the PGP scheme, we recommend using a program -called @code{gpg-agent} for entering and caching -passphrases@footnote{Actually, @code{gpg-agent} does not cache -passphrases but private keys. On the other hand, from a user's point -of view, this technical difference isn't visible.}. - -@defvar pgg-gpg-use-agent -If non-@code{nil}, attempt to use @code{gpg-agent} whenever possible. -The default is @code{t}. If @code{gpg-agent} is not running, or GnuPG -is not the current PGP scheme, PGG's own passphrase-caching mechanism -is used (see below). -@end defvar - -To use @code{gpg-agent} with PGG, you must first ensure that -@code{gpg-agent} is running. For example, if you are running in the X -Window System, you can do this by putting the following line in your -@file{.xsession} file: - -@smallexample -eval "$(gpg-agent --daemon)" -@end smallexample - -For more details on invoking @code{gpg-agent}, @xref{Invoking -GPG-AGENT,,,gnupg,Using the GNU Privacy Guard}. - -Whenever you perform a PGG operation that requires a GnuPG passphrase, -GnuPG will contact @code{gpg-agent}, which prompts you for the -passphrase. Furthermore, @code{gpg-agent} ``caches'' the result, so -that subsequent uses will not require you to enter the passphrase -again. (This cache usually expires after a certain time has passed; -you can change this using the @code{--default-cache-ttl} option when -invoking @code{gpg-agent}.) - -If you are running in a X Window System environment, @code{gpg-agent} -prompts for a passphrase by opening a graphical window. However, if -you are running Emacs on a text terminal, @code{gpg-agent} has trouble -receiving input from the terminal, since it is being sent to Emacs. -One workaround for this problem is to run @code{gpg-agent} on a -different terminal from Emacs, with the @code{--keep-tty} option; this -tells @code{gpg-agent} use its own terminal to prompt for passphrases. - -When @code{gpg-agent} is not being used, PGG prompts for a passphrase -through Emacs. It also has its own passphrase caching mechanism, -which is controlled by the variable @code{pgg-cache-passphrase} (see -below). - -There is a security risk in handling passphrases through PGG rather -than @code{gpg-agent}. When you enter your passphrase into an Emacs -prompt, it is temporarily stored as a cleartext string in the memory -of the Emacs executable. If the executable memory is swapped to disk, -the root user can, in theory, extract the passphrase from the -swapfile. Furthermore, the swapfile containing the cleartext -passphrase might remain on the disk after the system is discarded or -stolen. @code{gpg-agent} avoids this problem by using certain tricks, -such as memory locking, which have not been implemented in Emacs. - -@defvar pgg-cache-passphrase -If non-@code{nil}, store passphrases. The default value of this -variable is @code{t}. If you are worried about security issues, -however, you could stop the caching of passphrases by setting this -variable to @code{nil}. -@end defvar - -@defvar pgg-passphrase-cache-expiry -Elapsed time for expiration in seconds. -@end defvar - -If your passphrase contains non-ASCII characters, you might need to -specify the coding system to be used to encode your passphrases, since -GnuPG treats them as a byte sequence, not as a character sequence. - -@defvar pgg-passphrase-coding-system -Coding system used to encode passphrase. -@end defvar - -@node Default user identity -@section Default user identity - -The PGP implementation is usually able to select the proper key to use -for signing and decryption, but if you have more than one key, you may -need to specify the key id to use. - -@defvar pgg-default-user-id -User ID of your default identity. It defaults to the value returned -by @samp{(user-login-name)}. You can customize this variable. -@end defvar - -@defvar pgg-gpg-user-id -User ID of the GnuPG default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@defvar pgg-pgp-user-id -User ID of the PGP 2.x/6.x default identity. It defaults to -@samp{nil}. This overrides @samp{pgg-default-user-id}. You can -customize this variable. -@end defvar - -@defvar pgg-pgp5-user-id -User ID of the PGP 5.x default identity. It defaults to @samp{nil}. -This overrides @samp{pgg-default-user-id}. You can customize this -variable. -@end defvar - -@node Architecture -@chapter Architecture - -PGG introduces the notion of a "scheme of PGP implementation" (used -interchangeably with "scheme" in this document). This term refers to a -singleton object wrapped with the luna object system. - -Since PGG was designed for accessing and developing PGP functionality, -the architecture had to be designed not just for interoperability but -also for extensiblity. In this chapter we explore the architecture -while finding out how to write the PGG back end. - -@menu -* Initializing:: -* Back end methods:: -* Getting output:: -@end menu - -@node Initializing -@section Initializing - -A scheme must be initialized before it is used. -It had better guarantee to keep only one instance of a scheme. - -The following code is snipped out of @file{pgg-gpg.el}. Once an -instance of @code{pgg-gpg} scheme is initialized, it's stored to the -variable @code{pgg-scheme-gpg-instance} and will be reused from now on. - -@lisp -(defvar pgg-scheme-gpg-instance nil) - -(defun pgg-make-scheme-gpg () - (or pgg-scheme-gpg-instance - (setq pgg-scheme-gpg-instance - (luna-make-entity 'pgg-scheme-gpg)))) -@end lisp - -The name of the function must follow the -regulation---@code{pgg-make-scheme-} follows the back end name. - -@node Back end methods -@section Back end methods - -In each back end, these methods must be present. The output of these -methods is stored in special buffers (@ref{Getting output}), so that -these methods must tell the status of the execution. - -@deffn Method pgg-scheme-lookup-key scheme string &optional type -Return keys associated with @var{string}. If the optional third -argument @var{type} is non-@code{nil}, it searches from the secret -keyrings. -@end deffn - -@deffn Method pgg-scheme-encrypt-region scheme start end recipients &optional sign passphrase -Encrypt the current region between @var{start} and @var{end} for -@var{recipients}. If @var{sign} is non-@code{nil}, do a combined sign -and encrypt. If encryption is successful, it returns @code{t}, -otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-encrypt-symmetric-region scheme start end &optional passphrase -Encrypt the current region between @var{start} and @var{end} using a -symmetric cipher and a passphrases. If encryption is successful, it -returns @code{t}, otherwise @code{nil}. This function is currently only -implemented for GnuPG. -@end deffn - -@deffn Method pgg-scheme-decrypt-region scheme start end &optional passphrase -Decrypt the current region between @var{start} and @var{end}. If -decryption is successful, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-sign-region scheme start end &optional cleartext passphrase -Make the signature from text between @var{start} and @var{end}. If the -optional third argument @var{cleartext} is non-@code{nil}, it does not -create a detached signature. If signing is successful, it returns -@code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-verify-region scheme start end &optional signature -Verify the current region between @var{start} and @var{end}. If the -optional third argument @var{signature} is non-@code{nil}, it is treated -as the detached signature of the current region. If the signature is -successfully verified, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-insert-key scheme -Retrieve the user's public key and insert it as ASCII-armored format. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@deffn Method pgg-scheme-snarf-keys-region scheme start end -Collect public keys in the current region between @var{start} and -@var{end}, and add them into the user's keyring. -On success, it returns @code{t}, otherwise @code{nil}. -@end deffn - -@node Getting output -@section Getting output - -The output of the back end methods (@ref{Back end methods}) is stored in -special buffers, so that these methods must tell the status of the -execution. - -@defvar pgg-errors-buffer -The standard error output of the execution of the PGP command is stored -here. -@end defvar - -@defvar pgg-output-buffer -The standard output of the execution of the PGP command is stored here. -@end defvar - -@defvar pgg-status-buffer -The rest of status information of the execution of the PGP command is -stored here. -@end defvar - -@node Parsing OpenPGP packets -@chapter Parsing OpenPGP packets - -The format of OpenPGP messages is maintained in order to publish all -necessary information needed to develop interoperable applications. -The standard is documented in RFC 2440. - -PGG has its own parser for the OpenPGP packets. - -@defun pgg-parse-armor string -List the sequence of packets in @var{string}. -@end defun - -@defun pgg-parse-armor-region start end -List the sequence of packets in the current region between @var{start} -and @var{end}. -@end defun - -@defvar pgg-ignore-packet-checksum -If non-@code{nil}, don't check the checksum of the packets. -@end defvar - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@bye - -@c End: - -@ignore - arch-tag: 0c205838-34b9-41a5-b9d7-49ae57ccac85 -@end ignore diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi deleted file mode 100644 index e2902ccbed0..00000000000 --- a/doc/misc/rcirc.texi +++ /dev/null @@ -1,953 +0,0 @@ -\input texinfo -@c %**start of header -@setfilename ../../info/rcirc -@settitle rcirc Manual -@c %**end of header - -@copying -Copyright @copyright{} 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license is -included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Rcirc: (rcirc). Internet Relay Chat (IRC) client. -@end direntry - -@titlepage -@title rcirc Manual -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Basics, (dir), (dir) -@top rcirc Manual - -@code{rcirc} is an Emacs IRC client. - -IRC (Internet Relay Chat) is a multi-user chat protocol. Users -communicate with each other in real-time. Communication occurs both in -topic channels which are collections of many users, or privately, with -just one other user. - -@insertcopying - -@end ifnottex - -@menu -* Basics:: -* Reference:: -* Fighting Information Overload:: -* Hacking and Tweaking:: -* GNU Free Documentation License:: -* Key Index:: -* Variable Index:: -* Index:: - -@detailmenu - --- The Detailed Node Listing --- - -Basics - -* Internet Relay Chat:: -* Getting started with rcirc:: - -Reference - -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: - -Fighting Information Overload - -* Channels:: -* People:: -* Keywords:: -* Notices:: - -Hacking and Tweaking - -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: - -@end detailmenu -@end menu - -@node Basics, Reference, Top, Top -@chapter Basics - -This chapter contains a brief introduction to IRC (Internet Relay Chat), -and a quick tutorial on @code{rcirc}. - -@menu -* Internet Relay Chat:: -* Getting started with rcirc:: -@end menu - -@node Internet Relay Chat, Getting started with rcirc, Basics, Basics -@section Internet Relay Chat -@cindex internet relay chat -@cindex irc - -@cindex channel -@dfn{Internet Relay Chat} (IRC) is a form of instant communication over the -Internet. It is mainly designed for group (many-to-many) communication -in discussion forums called channels, but also allows one-to-one -communication. - -@cindex instant messaging, comparison -@cindex server -@cindex network -Contrary to most Instant Messenger (IM) systems, users usually don't -connect to a central server. Instead, users connect to a random -server in a network, and servers relay messages from one to the next. - -Here's a typical example: - -@cindex redirection to random servers -When you connect to the Freenode network -(@code{http://freenode.net/}), you point your IRC client at the -server @code{irc.freenode.net}. That server will redirect your client -to a random server on the network, such as @code{zelazny.freenode.net}. - -@cindex channel name -@cindex # starts a channel name -Once you're connected, you can send messages to all other users -connected to the same network, and you can join all channels on the same -network. You might join the @code{#emacs} and the @code{#rcirc} -channels, for example. (Typically, channel names begin with a hash -character.) - -Once you have joined a channel, anything you type will be broadcast to -all the other users on the same channel. - -@cindex addressing other people -@cindex other people, addressing them -@cindex talk to other people -If you want to address someone specifically, for example as an answer to -a question, it is customary to prefix the message with the nick followed -by a colon, like this: - -@example -deego: fsbot rules! -@end example - -@cindex nick completion -@cindex completion of nicks -@kindex TAB -Since this is so common, you can use @key{TAB} to do nick completion. - -@node Getting started with rcirc, , Internet Relay Chat, Basics -@section Getting started with rcirc -@cindex getting started -@cindex connecting to a server - -@cindex irc command -Use the command @kbd{M-x irc} to connect using the defaults. -@xref{Configuration}, if you want to change the defaults. - -Use @kbd{C-u M-x irc} if you don't want to use the defaults, eg. if you -want to connect to a different network, or connect to the same network -using a different nick. This will prompt you for four things: - -@table @asis -@cindex server, connecting -@cindex Freenode network -@item IRC Server -What server do you want to connect to? All the servers in a particular -network are equivalent. Some networks use a round-robin system where a -single server redirects new connections to a random server in the -network. @code{irc.freenode.net} is such a server for the Freenode -network. Freenode provides the network ``for the Free and Open Source -Software communities, for not-for-profit organizations and for related -communities and organizations.'' - -@cindex port, connecting -@cindex 6667, default IRC port -@item IRC Port -All network connections require a port. Just as web servers and clients -use port 80 per default, IRC uses port 6667 per default. You rarely -have to use a different port. - -@cindex nick, connecting -@cindex changing nick -@cindex name changes -@item IRC Nick -@vindex user-login-name -Every users needs a handle on-line. You will automatically be assigned -a slightly different nick if your chosen nick is already in use. If -your @code{user-login-name} is @code{alex}, and this nick is already -in use, you might for example get assigned the nick @code{alex`}. - -@cindex channels, connecting -@cindex initial channels -@cindex startup channels -@item IRC Channels -A space separated list of channels you want to join when connecting. -You don't need to join any channels, if you just want to have one-to-one -conversations with friends on the same network. If you're new to the -Freenode network, join @code{#emacs}, the channel about all things -Emacs, or join @code{#rcirc}, the channel about @code{rcirc}. -@end table - -@cindex server buffer -When you have answered these questions, @code{rcirc} will create a server -buffer, which will be named something like @code{*irc.freenode.net*}, -and a channel buffer for each of the channels you wanted to join. - -@kindex RET -@cindex talking -@cindex communicating -To talk in a channel, just type what you want to say in a channel -buffer, and press @key{RET}. - -@kindex C-c C-c -@cindex multiline messages -@cindex messages, multiple lines -@cindex pasting multiple lines -@cindex edit message before sending -If you want to paste multiple lines, such as source code, you can use -@kbd{C-c C-c} to edit your message in a separate buffer. Use @kbd{C-c -C-c} to finish editing. You still need to press @key{RET} to send it, -though. Generally, IRC users don't like people pasting more than around -four lines of code, so use with care. - -@comment This section copied from the Channels section. -@comment All index markers should point to the original! -Once you are connected to multiple channels, or once you've turned you -attention to other buffers in Emacs, you probably want to be notified -of any activity in channels not currently visible. All you need to do -is switch channel tracking on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -Use @kbd{C-c C-@key{SPC}} to switch to these buffers. - -@node Reference, Fighting Information Overload, Basics, Top -@chapter Reference -@cindex reference - -This is the reference section of the manual. It is not complete. For -complete listings of @code{rcirc} features, use Emacs built-in -documentation. - -@menu -* rcirc commands:: -* Useful IRC commands:: -* Configuration:: -@end menu - -@node rcirc commands, Useful IRC commands, Reference, Reference -@section rcirc commands -@cindex rcirc commands -@cindex commands - -@kindex C-h m -This is a list of commands that you may use in @code{rcirc}. It is not -complete. For a complete listing, press @kbd{C-h m} in an @code{rcirc} -buffer. - -In addition to using regular Emacs key bindings, you can call them by -typing them into an @code{rcirc} buffer. - -@cindex call commands -@cindex typing commands -@cindex commands -For instance, instead of using the command @kbd{C-c C-j} to join a new -channel, you may type this in an @code{rcirc} buffer, and press @key{RET}: - -@example -/join #emacs -@end example - -@cindex / starts a command -@cindex messages starting with a slash disappear -@cindex disappearing messages if starting with a slash -@cindex slash hides message -This is why you cannot start a message with a slash. You will have to -precede the command with a space, or rewrite your message in order to -send it to a channel. - -@cindex multiple words as parameters -@cindex string delimiters -@cindex quotes -@cindex double-quotes -Many commands take parameters. IRC commands usually ignore string -delimiters. Neither quote nor double-quote have special meanings in -IRC. - -@example -/nick "alex schroeder" -@end example - -This will try to change your nick to @code{"alex}. Usually this will -fail because the double quote character is not a valid character for -nicks. - -@cindex case insensitive commands -These commands are case insensitive. - -@cindex new command -@cindex unknown command -@cindex command unknown -If a command isn't known by @code{rcirc}, it will simply be sent along to the -server. There is a list of some useful commands like that in the next -section. - -@table @kbd -@item C-c C-j -@kindex C-c C-j -@cindex /join -@cindex join channels -@cindex other channels -@cindex rooms, joining -@cindex discussion, joining -This joins a channel such as @code{#rcirc} or @code{#emacs}. On most -networks, anybody can create new channels. If you want to talk with -some friends, for example, all you have to do is agree on a valid -channel name and join that channel. (Also @code{/join #emacs}.) - -@item C-c C-p -@kindex C-c C-p -@cindex /part -@cindex part a channel -@cindex leave a channel -@cindex disconnect from a channel -@cindex stop talking on a channel -@cindex kill channel buffer -This leaves the current channel. You can optionally provide a reason -for parting. When you kill a channel buffer, you automatically part the -corresponding channel. (Also @code{/part you are too weird!}.) - -@item C-c C-r -@kindex C-c C-r -@cindex /nick -@cindex change name -@cindex nick changing -@cindex rename yourself -@cindex other name -This changes your nick to some other name. Your nick must be unique -across the network. Most networks don't allow too many nick changes in -quick succession, and have restrictions on the valid characters in nick -names. (Also @code{/nick alex-test}) - -@item C-c C-w -@kindex C-c C-w -@cindex /whois -@cindex who are these people -@cindex identifying people -@cindex channels other people are on -@cindex what channels people are on -Gives you some basic information about a nick. This often includes what -other channels people are on. (Also @code{/whois fsbot}.) - -@item C-c C-q -@kindex C-c C-q -@cindex /query -@cindex starting a private conversation -@cindex one-to-one conversation -@cindex talk privately -@cindex private conversation -@cindex contact one person only -@cindex query a person -Starts a one-to-one conversation with another person on the same -network. A new buffer will be created for this conversation. It works -like a channel with only two members. (Also @code{/query fsbot}.) - -@item C-c @key{RET} -@kindex C-c RET -@cindex /msg -@cindex single message -@cindex message sending -This sends a single message to a nick. Like with @kbd{C-c C-q}, a new -buffer is created, where the response from the other party will show -up. (Also @code{/msg nickserv identify secret}.) - -@item C-c C-x -@kindex C-c C-x -@cindex /quit -@cindex quit -@cindex disconnect -@cindex kill connection -@cindex connection end -@cindex part all channels -@cindex end connection -@cindex server buffer killing -@cindex reason for quitting -This disconnects from the server and parts all channels. You can -optionally provide a reason for quitting. When you kill the server -buffer, you automatically quit the server and part all channels. (Also -@code{/quit ZZZzzz...}.) -@end table - -@node Useful IRC commands, Configuration, rcirc commands, Reference -@section Useful IRC commands -@cindex irc commands -@cindex commands - -As mentioned, if a command isn't known by @code{rcirc}, it will simply be sent -along to the server. Some such commands are available on nearly all IRC -servers, such as: - -@table @code -@item /away -@cindex /away -@cindex away status -@cindex pause status -@cindex unavailable status -@cindex set away status -This sets your status as ``being away'' if you provide a reason, or sets -your status as ``being back'' if you do not. People can use the -@kbd{C-c C-w} command to check your status. Example: @code{/away food}. -@end table - -@cindex irc resources -@cindex help about irc -Typical IRC servers implement many more commands. You can read more -about the fantastic world of IRC online at -@uref{http://www.irchelp.org/, the Internet Relay Chat (IRC) help -archive}. - -@node Configuration, , Useful IRC commands, Reference -@section Configuration -@cindex configuring rcirc - -These are some variables you can change to configure @code{rcirc} to your -liking. - -@table @code -@item rcirc-server-alist -@vindex rcirc-server-alist -@cindex channels, configuration -@cindex initial channels, configuration -@cindex startup channels, configuration -@cindex servers, configuration -@cindex initial servers, configuration -@cindex startup servers, configuration -This variable contains an alist of servers to connect to by default -and the keywords parameters to use. The keyword parameters are -optional. If you don't provide any, the defaults as documented below -will be used. - -The most important parameter is the @code{:channels} parameter. It -controls which channels you will join by default as soon as you are -connected to the server. - -Here's an example of how to set it: - -@example -(add-to-list 'rcirc-server-alist - '("otherworlders.org" - :channels ("#FUDGE" "#game-design"))) -@end example - -By default you will be connected to the @code{rcirc} support channel: -@code{#rcirc} on @code{irc.freenode.net}. - -@table @code -@item :nick -This overrides @code{rcirc-default-nick}. - -@item :port -This overrides @code{rcirc-default-port}. - -@item :user-name -This overrides @code{rcirc-default-user-name}. - -@item :full-name -This overrides @code{rcirc-default-full-name}. - -@item :channels -This describes which channels to join when connecting to the server. -If absent, no channels will be connected to automatically. - -@end table - -@item rcirc-default-nick -@vindex rcirc-default-nick -This variable is used for the default nick. It defaults to the login -name returned by @code{user-login-name}. - -@example -(setq rcirc-default-nick "kensanata") -@end example - -@item rcirc-default-port -@vindex rcirc-default-port -@cindex port -This variable contains the default port to connect to. It is 6667 by -default and rarely needs changing. - -@item rcirc-default-user-name -@vindex rcirc-default-user-name -@cindex user name -This variable contains the default user name to report to the server. -It defaults to the login name returned by @code{user-login-name}, just -like @code{rcirc-default-nick}. - -@item rcirc-default-user-full-name -@vindex rcirc-default-user-full-name -@cindex full name -@cindex real name -@cindex surname -This variable is used to set your ``real name'' on IRC. It defaults -to the name returned by @code{user-full-name}. If you want to hide -your full name, you might want to set it to some pseudonym. - -@example -(setq rcirc-default-user-full-name "Curious Minds Want To Know") -@end example - -@item rcirc-authinfo -@vindex rcirc-authinfo -@cindex authentification -@cindex identification -@cindex nickserv -@cindex login -This variable is an alist used to automatically identify yourself on -networks. Each sublist starts with a regular expression that is -compared to the server address you're connecting to. The second -element in the list is a symbol representing the method to use, -followed by the arguments this method requires. - -Here is an example to illustrate how you would set it: - -@example -(setq rcirc-authinfo - '(("freenode" nickserv "bob" "p455w0rd") - ("freenode" chanserv "bob" "#bobland" "passwd99") - ("bitlbee" bitlbee "robert" "sekrit"))) -@end example - -And here are the valid method symbols and the arguments they require: - -@table @code -@item nickserv -@cindex nickserv authentification -Use this symbol if you need to identify yourself as follows when -connecting to a network: @code{/msg nickserv identify secret}. The -necessary arguments are the nickname you want to use this for, and the -password to use. - -Before you can use this method, you will have to register your nick and -pick a password for it. Contact @code{nickserv} and check out the -details. (Using @code{/msg nickserv help}, for example.) - -@item chanserv -@cindex chanserv authentification -Use this symbol if you need to identify yourself as follows if you want -to join a particular channel: @code{/msg chanserv identify #underground -secret}. The necessary arguments are the nickname and channel you want -to use this for, and the password to use. - -Before you can use this method, a channel contact must tell you about -the password to use. Contact @code{chanserv} and check out the details. -(Using @code{/msg chanserv help}, for example.) - -@item bitlbee -@cindex bitlbee authentification -Use this symbol if you need to identify yourself in the Bitlbee channel -as follows: @code{identify secret}. The necessary arguments are the -nickname you want to use this for, and the password to use. - -@cindex gateway to other IM services -@cindex instant messaging, other services -@cindex Jabber -@cindex AIM -@cindex ICQ -@cindex MSN -@cindex Yahoo! -Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of -other instant messaging services. You can either install Bitlbee -locally or use a public Bitlbee server. There, you need to create an -account with a password. This is the nick and password you need to -provide for the bitlbee authentification method. - -Later, you will tell Bitlbee about your accounts and passwords on all -the other instant messaging services, and Bitlbee will log you in. All -@code{rcirc} needs to know, is the login to your Bitlbee account. Don't -confuse the Bitlbee account with all the other accounts. - -@end table - -@end table - -@node Fighting Information Overload, Hacking and Tweaking, Reference, Top -@chapter Fighting Information Overload -@cindex information overload - -This is the section of the manual that caters to the busy person -online. There are support channels with several hundred people in -them. Trying to follow a conversation in these channels can be a -daunting task. This chapters tells you how @code{rcirc} can help. - -@menu -* Channels:: -* People:: -* Keywords:: -* Notices:: -@end menu - -@node Channels, People, Fighting Information Overload, Fighting Information Overload -@section Channels -@cindex channels -@cindex modeline - -@comment This section copied to the Getting started with rcirc section -@kindex C-c C-SPC -@vindex rcirc-track-minor-mode -@cindex switching channels -@cindex tracking activity -@cindex active channel -@cindex abbreviated channel names -@cindex modeline tracks activity -Most people want a notification when something is said on a channel they -have joined, particularly if they have been addressed directly. There -is a global minor mode that will do this kind of tracking for you. All -you need to do is switch it on using @kbd{M-x rcirc-track-minor-mode}. -To make this permanent, add the following to your init file: - -@example -(rcirc-track-minor-mode 1) -@end example - -When other people say things in buffers that are currently buried (no -window is showing them), the mode line will now show you the abbreviated -channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these -buffers. - -@vindex rcirc-mode-hook -If you prefer not to load @code{rcirc} immediately, you can delay the -activation of this mode: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (rcirc-track-minor-mode 1))) -@end example - -@cindex busy channels -If you've joined a very active support channel, tracking activity is -no longer useful. The channel will be always active. Switching to -active channels using @kbd{C-c C-@key{SPC}} no longer works as -expected. - -@kindex C-c C-l -@cindex low priority channels -The solution is to mark this channel as a low priority channel. -Use @kbd{C-c C-l} to make the current channel a low-priority channel. -Low priority channels have the modeline indicator ``LowPri''. -@kbd{C-c C-@key{SPC}} will not switch to low priority channels unless -you use the @kbd{C-u} prefix. - -@kindex C-c TAB -@cindex ignored channels -If you prefer a channel to never show up in the modeline, then you -have to ignore it. Use @kbd{C-c @key{TAB}} to ignore the current -channel. - -@node People, Keywords, Channels, Fighting Information Overload -@section People -@cindex people, how to ignore -@cindex nicks, how to ignore -@cindex friends -@cindex buddies -@cindex trolls - -The most important command available to the discerning IRC user is -@code{/ignore}. It's the big equalizer online: If people aggravate -you, just ignore them. - -This is of course a crude all-or-nothing solution. Fear not, -@code{rcirc} offers alternatives: You can ``brighten'' your buddies -and ``dim'' certain other nicks that you don't want to ignore -altogether. - -@table @code -@item /ignore -@cindex /ignore -@cindex ignoring other people -@cindex trolls, ignoring -@cindex hide some posts -@cindex idiots online -This command toggles the ignore status of a nick, if you provide one. -If you don't provide a nick, the command lists all the nicks you are -ignoring. All messages by ignored nicks are---you guessed it---ignored. -Since only ``operators'' can kick people from channels, the -ignore command is often the only way to deal with some of the more -obnoxious fellows online. Example: @code{/ignore rudybot}. - -@item /bright -@cindex /bright -@cindex highlight other people -@cindex friends, highlight -@cindex buddies, highlight -@cindex nicks, highlight -@cindex brighten nicks -This command toggles the bright status of a nick, if you provide one. -If you don't provide a nick, the command lists all the ``brightened'' -nicks. All messages by brightened nicks are---you guessed -it---brightened. Use this for your friends. Example: @code{/bright -rcy}. - -@item /dim -@cindex /dim -@cindex soft-ignore other people -@cindex obnoxious people online -@cindex rabble online -This command toggles the dim status of a nick, if you provide one. If -you don't provide a nick, the command lists all the ``dimmed'' nicks. -All messages by dimmed nicks are---you guessed it---dimmed. Use this -for boring people and bots. If you are tracking channel activity, -messages by dimmed nicks will not register as activity. Example: -@code{/dim fsbot}. -@end table - - -@node Keywords, Notices, People, Fighting Information Overload -@section Keywords -@cindex keywords - -On a busy channel, you might want to ignore all activity (using -@kbd{C-c @key{TAB}}) and just watch for certain keywords. The -following command allows you to highlight certain keywords: - -@table @code -@item /keyword -@cindex /keyword -This command toggles the highlighting of a keyword, if you provide -one. If you don't provide a keyword, the current keywords are -listed. Example: @code{/keyword manual}. -@end table - -@node Notices, , Keywords, Fighting Information Overload -@section Notices -@cindex part notices, how to omit -@cindex join notices, how to omit -@cindex quit notices, how to omit -@cindex nick notices, how to omit - -@kindex C-c C-o -@cindex low priority channels -In busy channels you might not be interested in all the joining, -parting, quitting, and renaming that goes on. You can omit those -notices using @kbd{C-c C-o}. - -@vindex rcirc-omit-responses -@cindex away notices, how to omit -You can control which notices get omitted via the -@code{rcirc-omit-responses} variable. Here's an example of how to -omit away messages: - -@example -(setq rcirc-omit-responses '("JOIN" "PART" "QUIT" "NICK" "AWAY)) -@end example - -@vindex rcirc-omit-threshold -Notice that these messages will not be omitted if the nick in question -has recently been active. After all, you don't want to continue a -conversation with somebody who just left. That's why @code{rcirc} -checks recent lines in the buffer to figure out if a nick has been -active and only omits a message if the nick has not been active. The -window @code{rcirc} considers is controlled by the -@code{rcirc-omit-threshold} variable. - -@node Hacking and Tweaking, GNU Free Documentation License, Fighting Information Overload, Top -@chapter Hacking and Tweaking -@cindex hacking and tweaking - -Here are some examples of stuff you can do to configure @code{rcirc}. - -@menu -* Skipping /away messages using handlers:: -* Using fly spell mode:: -* Scrolling conservatively:: -* Changing the time stamp format:: -* Defining a new command:: -* Reconnecting after you have lost the connection:: -@end menu - -@node Skipping /away messages using handlers, Using fly spell mode, Hacking and Tweaking, Hacking and Tweaking -@section Skipping @code{/away} messages using handlers -@cindex /away messages - -@cindex handlers -@cindex status codes -The IRC protocol specifies how certain events are signaled from server -to client. These events have numbers and are dealt with using so-called -handlers. You can override existing handlers by exploiting the naming -convention adopted for @code{rcirc}. - -Here's how to stop @code{rcirc} from printing @code{/away} messages. -Since @code{rcirc} doesn't define a 301 handler, you don't need to -require @code{rcirc} before defining the handler: - -@example -(defun rcirc-handler-301 (process cmd sender args) - "/away message handler.") -@end example - -@node Using fly spell mode, Scrolling conservatively, Skipping /away messages using handlers, Hacking and Tweaking -@section Using fly spell mode -@cindex fly spell -@cindex spelling -@cindex spell-checking as you type -@cindex automatic spelling -@vindex rcirc-mode-hook - -The following code activates Fly Spell Mode -for @code{rcirc} buffers: - -@example -(add-hook 'rcirc-mode-hook (lambda () - (flyspell-mode 1))) -@end example - -@xref{Spelling, , Flyspell mode, emacs, The GNU Emacs Manual}, -for details. - -@node Scrolling conservatively, Changing the time stamp format, Using fly spell mode, Hacking and Tweaking -@section Scrolling conservatively -@cindex input line -@cindex scrolling -@vindex scroll-conservatively -@vindex rcirc-mode-hook - -IRC buffers are constantly growing. If you want to see as much as -possible at all times, you would want the prompt at the bottom of the -window when possible. The following snippet uses a local value for -@code{scroll-conservatively} to achieve this: - -@example -(add-hook 'rcirc-mode-hook - (lambda () - (set (make-local-variable 'scroll-conservatively) - 8192))) -@end example - -@xref{Scrolling, , Scrolling conservatively, emacs, The GNU Emacs -Manual}, for details. - -@node Changing the time stamp format, Defining a new command, Scrolling conservatively, Hacking and Tweaking -@section Changing the time stamp format -@cindex time stamp -@cindex date time -@cindex format time stamp -@vindex rcirc-time-format - -@code{rcirc-time-format} is the format used for the time stamp. Here's -how to include the date in the time stamp: - -@example -(setq rcirc-time-format "%Y-%m-%d %H:%M ") -@end example - -@node Defining a new command, Reconnecting after you have lost the connection, Changing the time stamp format, Hacking and Tweaking -@section Defining a new command -@cindex defining commands -@cindex commands, defining -@cindex new commands, defining - -Here's a simple new command, @code{/sv}. With it, you can boast about -your IRC client. It shows how you can use @code{defun-rcirc-command} to -define new commands. - -We're waiting for the definition of this command until @code{rcirc} is loaded -because @code{defun-rcirc-command} is not yet available, and without -@code{rcirc} loaded, the command wouldn't do us much good anyway. - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command sv (arg) - "Boast about rcirc." - (interactive "i") - (rcirc-send-message process target - (concat "I use " rcirc-id-string)))) -@end smallexample - -@node Reconnecting after you have lost the connection, , Defining a new command, Hacking and Tweaking -@section Reconnecting after you have lost the connection -@cindex reconnecting -@cindex disconnecting servers, reconnecting - -If you're chatting from a laptop, then you might be familiar with this -problem: When your laptop falls asleep and wakes up later, your IRC -client doesn't realize that it has been disconnected. It takes several -minutes until the client decides that the connection has in fact been -lost. The simple solution is to use @kbd{M-x rcirc}. The problem is -that this opens an @emph{additional} connection, so you'll have two -copies of every channel buffer --- one dead and one live. - -The real answer, therefore, is a @code{/reconnect} command: - -@smallexample -(eval-after-load 'rcirc - '(defun-rcirc-command reconnect (arg) - "Reconnect the server process." - (interactive "i") - (unless process - (error "There's no process for this target")) - (let* ((server (car (process-contact process))) - (port (process-contact process :service)) - (nick (rcirc-nick process)) - channels query-buffers) - (dolist (buf (buffer-list)) - (with-current-buffer buf - (when (eq process (rcirc-buffer-process)) - (remove-hook 'change-major-mode-hook - 'rcirc-change-major-mode-hook) - (if (rcirc-channel-p rcirc-target) - (setq channels (cons rcirc-target channels)) - (setq query-buffers (cons buf query-buffers)))))) - (delete-process process) - (rcirc-connect server port nick - rcirc-default-user-name - rcirc-default-user-full-name - channels)))) -@end smallexample - -@node GNU Free Documentation License, Key Index, Hacking and Tweaking, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Key Index, Variable Index, GNU Free Documentation License, Top -@unnumbered Key Index -@printindex ky - -@node Variable Index, Index, Key Index, Top -@unnumbered Variable Index -@printindex vr - -@node Index, , Variable Index, Top -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: 2589e562-3843-4ffc-8c2f-477cbad57c01 -@end ignore diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi deleted file mode 100644 index c8876cc9512..00000000000 --- a/doc/misc/reftex.texi +++ /dev/null @@ -1,5895 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/reftex -@settitle RefTeX User Manual -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp - -@c Version and Contact Info -@set VERSION 4.31 -@set EDITION 4.31 -@set DATE February 2006 -@set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site} -@set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page} -@set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} -@set MAINTAINER the AUC@TeX{} project -@set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org}) -@set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org}) -@set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org}) -@set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site} -@c %**end of header - -@copying -This file documents @b{Ref@TeX{}}, a package to do labels, references, -citations and indices for LaTeX documents with Emacs. - -This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for -@b{Ref@TeX{}} @value{VERSION} - -Copyright @copyright{} 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations. -@end direntry - -@finalout - -@c Macro definitions - -@c Subheadings inside a table. Need a difference between info and the rest. -@macro tablesubheading{text} -@ifinfo -@subsubheading \text\ -@end ifinfo -@ifnotinfo -@item @b{\text\} -@end ifnotinfo -@end macro - -@titlepage -@title Ref@TeX{} User Manual -@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs -@subtitle Edition @value{EDITION}, @value{DATE} - -@author by Carsten Dominik -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top,,,(dir) - -@b{Ref@TeX{}} is a package for managing Labels, References, -Citations and index entries with GNU Emacs. - -Don't be discouraged by the size of this manual, which covers -@b{Ref@TeX{}} in great depth. All you need to know to use -@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a -Nutshell}). You can go back later to other parts of this document when -needed. - -@insertcopying - -@menu -* Introduction:: Quick-Start information. - -* Table of Contents:: A Tool to move around quickly. -* Labels and References:: Creating and referencing labels. -* Citations:: Creating Citations. -* Index Support:: Creating and Checking Index Entries. -* Viewing Cross-References:: Who references or cites what? - -* RefTeXs Menu:: The Ref menu in the menubar. -* Key Bindings:: The default key bindings. -* Faces:: Fontification of RefTeX's buffers. -* Multifile Documents:: Document spread over many files. -* Language Support:: How to support other languages. -* Finding Files:: Included TeX files and BibTeX .bib files. -* AUCTeX:: Cooperation with AUCTeX. -* Optimizations:: When RefTeX is too slow. -* Problems and Work-Arounds:: First Aid. -* Imprint:: Author, Web-site, Thanks - -* Commands:: Which are the available commands. -* Options:: How to extend and configure RefTeX. -* Keymaps and Hooks:: For customization. -* Changes:: A List of recent changes to RefTeX. -* GNU Free Documentation License:: The license for this documentation. - -The Index - -* Index:: The full index. - -@detailmenu - -Introduction - -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. - -Labels and References - -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* xr (LaTeX package):: References to external documents. -* varioref (LaTeX package):: How to create \vref instead of \ref. -* fancyref (LaTeX package):: How to create \fref instead of \ref. - -Defining Label Environments - -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-LaTeX macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. - -Citations - -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. - -Index Support - -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. - -The Index Phrases File - -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. - -AUCTeX - -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: AUCTeX's style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document - -Options, Keymaps, Hooks - -* Options (Table of Contents):: -* Options (Defining Label Environments):: -* Options (Creating Labels):: -* Options (Referencing Labels):: -* Options (Creating Citations):: -* Options (Index Support):: -* Options (Viewing Cross-References):: -* Options (Finding Files):: -* Options (Optimizations):: -* Options (Fontification):: -* Options (Misc):: - -@end detailmenu -@end menu - -@end ifnottex - -@node Introduction, Table of Contents, , Top -@chapter Introduction -@cindex Introduction - -@b{Ref@TeX{}} is a specialized package for support of labels, -references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps -itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, -and @code{\index}. Using these macros usually requires looking up -different parts of the document and searching through BibTeX database -files. @b{Ref@TeX{}} automates these time--consuming tasks almost -entirely. It also provides functions to display the structure of a -document and to move around in this structure quickly. - -@iftex -Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} -in great depth. All you need to know to use @b{Ref@TeX{}} can be -summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go -back later to other parts of this document when needed. -@end iftex - -@xref{Imprint}, for information about who to contact for help, bug -reports or suggestions. - -@menu -* Installation:: How to install and activate RefTeX. -* RefTeX in a Nutshell:: A brief summary and quick guide. -@end menu - -@node Installation, RefTeX in a Nutshell, , Introduction -@section Installation -@cindex Installation - -@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version -20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. -XEmacs 21.x users want to install the corresponding plug-in package -which is available from the @value{XEMACSFTP}. See the XEmacs 21.x -documentation on package installation for details. - -Users of earlier Emacs distributions (including Emacs 19) can get a copy -of the @b{Ref@TeX{}} distribution from the maintainers web-page. -@xref{Imprint}, for more information. - -@section Environment -@cindex Finding files -@cindex BibTeX database files, not found -@cindex TeX files, not found -@cindex @code{TEXINPUTS}, environment variable -@cindex @code{BIBINPUTS}, environment variable - -@b{Ref@TeX{}} needs to access all files which are part of a multifile -document, and the BibTeX database files requested by the -@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will -require a search path, i.e. a list of directories to check. Normally -this list is stored in the environment variables @code{TEXINPUTS} and -@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some -systems these variables do not contain the full search path. If -@b{Ref@TeX{}} does not work for you because it cannot find some files, -read @ref{Finding Files}. - -@section Entering @b{Ref@TeX{}} Mode - -@findex turn-on-reftex -@findex reftex-mode -@vindex LaTeX-mode-hook -@vindex latex-mode-hook -To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use -@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX -files, add the following lines to your @file{.emacs} file: - -@example -(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode -(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode -@end example - -@page -@node RefTeX in a Nutshell, , Installation, Introduction -@section @b{Ref@TeX{}} in a Nutshell -@cindex Quick-Start -@cindex Getting Started -@cindex RefTeX in a Nutshell -@cindex Nutshell, RefTeX in a - -@enumerate -@item -@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show -a table of contents of the document. This buffer can display sections, -labels and index entries defined in the document. From the buffer, you -can jump quickly to every part of your document. Press @kbd{?} to get -help. - -@item -@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels -and to find the correct key for references quickly. It distinguishes -labels for different environments, knows about all standard -environments (and many others), and can be configured to recognize any -additional labeled environments you have defined yourself (variable -@code{reftex-label-alist}). - -@itemize @bullet -@item -@b{Creating Labels}@* -Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. -@b{Ref@TeX{}} will either -@itemize @minus -@item -derive a label from context (default for section labels) -@item -prompt for a label string (default for figures and tables) or -@item -insert a simple label made of a prefix and a number (all other -environments) -@end itemize -@noindent -Which labels are created how is configurable with the variable -@code{reftex-insert-label-flags}. - -@item -@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} -(@code{reftex-reference}). This shows an outline of the document with -all labels of a certain type (figure, equation,...) and some label -context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro -into the original buffer. -@end itemize - -@item -@b{Citations}@* -Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a -regular expression to search in current BibTeX database files (as -specified in the @code{\bibliography} command) and pull out a list of -matches for you to choose from. The list is @emph{formatted} and -sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} -(see the variable @code{reftex-cite-format} if you want to insert -different macros). - -@item -@b{Index Support}@* -@b{Ref@TeX{}} helps to enter index entries. It also compiles all -entries into an alphabetically sorted @file{*Index*} buffer which you -can use to check and edit the entries. @b{Ref@TeX{}} knows about the -standard index macros and can be configured to recognize any additional -macros you have defined (@code{reftex-index-macros}). Multiple indices -are supported. - -@itemize @bullet -@item -@b{Creating Index Entries}@* -To index the current selection or the word at point, type @kbd{C-c /} -(@code{reftex-index-selection-or-word}). The default macro -@code{reftex-index-default-macro} will be used. For a more complex entry -type @kbd{C-c <} (@code{reftex-index}), select any of the index macros -and enter the arguments with completion. - -@item -@b{The Index Phrases File (Delayed Indexing)}@* -Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add -the current word or selection to a special @emph{index phrase file}. -@b{Ref@TeX{}} can later search the document for occurrences of these -phrases and let you interactively index the matches. - -@item -@b{Displaying and Editing the Index}@* -To display the compiled index in a special buffer, type @kbd{C-c >} -(@code{reftex-display-index}). From that buffer you can check and edit -all entries. -@end itemize - -@page -@item @b{Viewing Cross-References}@* -When point is on the @var{key} argument of a cross--referencing macro -(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, -@code{\index}, and variations) or inside a BibTeX database entry, you -can press @kbd{C-c &} (@code{reftex-view-crossref}) to display -corresponding locations in the document and associated BibTeX database -files. @* -When the enclosing macro is @code{\cite} or @code{\ref} and no other -message occupies the echo area, information about the citation or label -will automatically be displayed in the echo area. - -@item -@b{Multifile Documents}@* -Multifile Documents are fully supported. The included files must have a -file variable @code{TeX-master} or @code{tex-main-file} pointing to the -master file. @b{Ref@TeX{}} provides cross-referencing information from -all parts of the document, and across document borders -(@file{xr.sty}). - -@item -@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in -order to find labels and other information. It does it automatically -once and updates its list internally when @code{reftex-label} and -@code{reftex-index} are used. To enforce reparsing, call any of the -commands described above with a raw @kbd{C-u} prefix, or press the -@kbd{r} key in the label selection buffer, the table of contents -buffer, or the index buffer. - -@item -@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can -cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX -contains style files which trigger appropriate settings in -@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no -additional customizations will be necessary. - -@item -@b{Useful Settings}@* -To integrate RefTeX with AUCTeX, use -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, -customize the variables -@example -@code{reftex-label-alist} @r{(for label macros/environments)} -@code{reftex-section-levels} @r{(for sectioning commands)} -@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} -@code{reftex-index-macros} @r{(for @code{\index}-like macros)} -@code{reftex-index-default-macro} @r{(to set the default macro)} -@end example -If you have a large number of macros defined, you may want to write -an AUCTeX style file to support them with both AUCTeX and -@b{Ref@TeX{}}. - -@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus -until you have picked up the key bindings. For an overview of what you -can do in each of the different special buffers, press @kbd{?}. Read -the manual if you get stuck, of if you are curious what else might be -available. The first part of the manual explains in -a tutorial way how to use and customize @b{Ref@TeX{}}. The second -part is a command and variable reference. -@end enumerate - -@node Table of Contents, Labels and References, Introduction, Top -@chapter Table of Contents -@cindex @file{*toc*} buffer -@cindex Structure editing -@cindex Table of contents buffer -@findex reftex-toc -@kindex C-c = - -Pressing the keys @kbd{C-c =} pops up a buffer showing the table of -contents of the document. By default, this @file{*toc*} buffer shows -only the sections of a document. Using the @kbd{l} and @kbd{i} keys you -can display all labels and index entries defined in the document as -well. - -With the cursor in any of the lines denoting a location in the -document, simple key strokes will display the corresponding part in -another window, jump to that location, or perform other actions. - -@kindex ? -Here is a list of special commands in the @file{*toc*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd - -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item n -Goto next entry in the table of context. - -@item p -Goto previous entry in the table of context. - -@item C-c C-n -Goto next section heading. Useful when many labels and index entries -separate section headings. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps -to section 3. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the corresponding location in another window. This command does -@emph{not} select that other window. - -@item @key{TAB} -Goto the location in another window. - -@item @key{RET} -Go to the location and hide the @file{*toc*} buffer. This will restore -the window configuration before @code{reftex-toc} (@kbd{C-c =}) was -called. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a line has the same effect as @key{RET}. -See also variable @code{reftex-highlight-selection}, @ref{Options -(Fontification)}. - -@item f -@vindex reftex-toc-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line at point in the -@file{*toc*} buffer. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-toc-follow-mode}. Note that only context in files already -visited is shown. @b{Ref@TeX{}} will not visit a file just for follow -mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show calling point in another window. This is the point from where -@code{reftex-toc} was last called. - -@page -@tablesubheading{Promotion and Demotion} - -@item < -Promote the current section. This will convert @code{\section} to -@code{\chapter}, @code{\subsection} to @code{\section} etc. If there is -an active region, all sections in the region will be promoted, including -the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh -document scan before executing this command - if necessary, it will -automatically do this scan and ask the user to repeat the promotion -command. - -@item > -Demote the current section. This is the opposite of promotion. It will -convert @code{\chapter} to @code{\section} etc. If there is an active -region, all sections in the region will be demoted, including the one at -point. - -@item M-% -Rename the label at point. While generally not recommended, this can be -useful when a package like @file{fancyref} is used where the label -prefix determines the wording of a reference. After a -promotion/demotion it may be necessary to change a few labels from -@samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be -used to do this - it launches a query replace to rename the definition -and all references of a label. - -@tablesubheading{Exiting} -@item q -Hide the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item k -Kill the @file{*toc*} buffer, return to the position where -@code{reftex-toc} was last called. - -@item C-c > -Switch to the @file{*Index*} buffer of this document. With prefix -@samp{2}, restrict the index to the section at point in the @file{*toc*} -buffer. - -@tablesubheading{Controlling what gets displayed} - -@item t -@vindex reftex-toc-max-level -Change the maximum level of toc entries displayed in the @file{*toc*} -buffer. Without prefix arg, all levels will be included. With prefix -arg (e.g @kbd{3 t}), ignore all toc entries with level greater than -@var{arg} (3 in this case). Chapters are level 1, sections are level 2. -The mode line @samp{T<>} indicator shows the current value. The default -depth can be configured with the variable -@code{reftex-toc-max-level}. - -@item F -@vindex reftex-toc-include-file-boundaries -Toggle the display of the file borders of a multifile document in the -@file{*toc*} buffer. The default for this flag can be set with the -variable @code{reftex-toc-include-file-boundaries}. - -@item l -@vindex reftex-toc-include-labels -Toggle the display of labels in the @file{*toc*} buffer. The default -for this flag can be set with the variable -@code{reftex-toc-include-labels}. When called with a prefix argument, -@b{Ref@TeX{}} will prompt for a label type and include only labels of -the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} -indicator shows which labels are included. - -@item i -@vindex reftex-toc-include-index-entries -Toggle the display of index entries in the @file{*toc*} buffer. The -default for this flag can be set with the variable -@code{reftex-toc-include-index-entries}. When called with a prefix -argument, @b{Ref@TeX{}} will prompt for a specific index and include -only entries in the selected index in the @file{*toc*} buffer. The mode -line @samp{I<>} indicator shows which index is used. - -@item c -@vindex reftex-toc-include-context -Toggle the display of label and index context in the @file{*toc*} -buffer. The default for this flag can be set with the variable -@code{reftex-toc-include-context}. - -@tablesubheading{Updating the buffer} - -@item g -Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the -document. - -@item r -@vindex reftex-enable-partial-scans -Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} -buffer. - -@item x -Switch to the @file{*toc*} buffer of an external document. When the -current document is using the @code{xr} package (@pxref{xr (LaTeX -package)}), @b{Ref@TeX{}} will switch to one of the external -documents. - - -@tablesubheading{Automatic recentering} - -@item d -Toggle the display of a dedicated frame displaying just the @file{*toc*} -buffer. Follow mode and visiting locations will not work that frame, -but automatic recentering will make this frame always show your current -editing location in the document (see below). - -@item a -Toggle the automatic recentering of the @file{*toc*} buffer. When this -option is on, moving around in the document will cause the @file{*toc*} -to always highlight the current section. By default, this option is -active while the dedicated @file{*TOC*} frame exists. See also the -variable @code{reftex-auto-recenter-toc}. - -@end table - -@vindex reftex-toc-map -In order to define additional commands for the @file{*toc*} buffer, the -keymap @code{reftex-toc-map} may be used. - -@findex reftex-toc-recenter -@vindex reftex-auto-recenter-toc -@vindex reftex-idle-time -@cindex @file{*toc*} buffer, recentering -@cindex Table of contents buffer, recentering -@kindex C-c - -If you call @code{reftex-toc} while the @file{*toc*} buffer already -exists, the cursor will immediately jump to the right place, i.e. the -section from which @code{reftex-toc} was called will be highlighted. -The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay -the @file{*toc*} buffer and highlight the correct line without actually -selecting the @file{*toc*} window. This can be useful to quickly find -out where in the document you currently are. You can also automate this -by asking RefTeX to keep track of your current editing position in the -TOC. The TOC window will then be updated whenever you stop typing for -more than @code{reftex-idle-time} seconds. By default this works only -with the dedicated @file{*TOC*} frame. But you can also force automatic -recentering of the TOC window on the current frame with -@lisp -(setq reftex-auto-recenter-toc t) -@end lisp - - -@cindex Sectioning commands -@cindex KOMA-Script, LaTeX classes -@cindex LaTeX classes, KOMA-Script -@cindex TOC entries for environments -@vindex reftex-section-levels -The section macros recognized by @b{Ref@TeX{}} are all LaTeX section -macros (from @code{\part} to @code{\subsubparagraph}) and the commands -@code{\addchap} and @code{\addsec} from the KOMA-Script classes. -Additional macros can be configured with the variable -@code{reftex-section-levels}. It is also possible to add certain LaTeX -environments to the table of contents. This is probably only useful for -theorem-like environments. @xref{Defining Label Environments}, for an -example. - -@node Labels and References, Citations, Table of Contents, Top -@chapter Labels and References -@cindex Labels in LaTeX -@cindex References in LaTeX -@cindex Label category -@cindex Label environment -@cindex @code{\label} - -LaTeX provides a powerful mechanism to deal with cross--references in a -document. When writing a document, any part of it can be marked with a -label, like @samp{\label@{mark@}}. LaTeX records the current value of a -certain counter when a label is defined. Later references to this label -(like @samp{\ref@{mark@}}) will produce the recorded value of the -counter. - -Labels can be used to mark sections, figures, tables, equations, -footnotes, items in enumerate lists etc. LaTeX is context sensitive in -doing this: A label defined in a figure environment automatically -records the figure counter, not the section counter. - -Several different environments can share a common counter and therefore -a common label category. E.g. labels in both @code{equation} and -@code{eqnarray} environments record the value of the same counter - the -equation counter. - -@menu -* Creating Labels:: -* Referencing Labels:: -* Builtin Label Environments:: The environments RefTeX knows about. -* Defining Label Environments:: ... and environments it doesn't. -* Reference Info:: View the label corresponding to a \ref. -* xr (LaTeX package):: References to external documents. -* varioref (LaTeX package):: How to create \vref instead of \ref. -* fancyref (LaTeX package):: How to create \fref instead of \ref. -@end menu - -@node Creating Labels, Referencing Labels, , Labels and References -@section Creating Labels -@cindex Creating labels -@cindex Labels, creating -@cindex Labels, deriving from context -@kindex C-c ( -@findex reftex-label - -In order to create a label in a LaTeX document, press @kbd{C-c (} -(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive -and will figure out the environment it currently is in and adapt the -label to that environment. A label usually consists of a short prefix -indicating the type of the label and a unique mark. @b{Ref@TeX{}} has -3 different modes to create this mark. - -@enumerate -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-derive-label-parameters -@vindex reftex-label-illegal-re -@vindex reftex-abbrev-parameters -A label can be derived from context. This means, @b{Ref@TeX{}} takes -the context of the label definition and constructs a label from -that@footnote{Note that the context may contain constructs which are -invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from -accented Latin-1 characters and remove everything else which is not -valid in labels. This mechanism is safe, but may not be satisfactory -for non-western languages. Check the following variables if you need to -change things: @code{reftex-translate-to-ascii-function}, -@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, -@code{reftex-abbrev-parameters}.}. This works best for section labels, -where the section heading is used to construct a label. In fact, -@b{Ref@TeX{}}'s default settings use this method only for section -labels. You will be asked to confirm the derived label, or edit -it. - -@item -We may also use a simple unique number to identify a label. This is -mostly useful for labels where it is difficult to come up with a very -good descriptive name. @b{Ref@TeX{}}'s default settings use this method -for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} -tends to write documents with many equations and finds it impossible -to come up with good names for each of them. These simple labels are -inserted without query, and are therefore very fast. Good descriptive -names are not really necessary as @b{Ref@TeX{}} will provide context to -reference a label (@pxref{Referencing Labels}). - -@item -The third method is to ask the user for a label. This is most -useful for things which are easy to describe briefly and do not turn up -too frequently in a document. @b{Ref@TeX{}} uses this for figures and -tables. Of course, one can enter the label directly by typing the full -@samp{\label@{mark@}}. The advantage of using @code{reftex-label} -anyway is that @b{Ref@TeX{}} will know that a new label has been defined. -It will then not be necessary to rescan the document in order to access -this label later. -@end enumerate - -@vindex reftex-insert-label-flags -If you want to change the way certain labels are created, check out the -variable @code{reftex-insert-label-flags} (@pxref{Options (Creating -Labels)}). - -If you are using AUCTeX to write your LaTeX documents, you can -set it up to delegate the creation of labels to -@b{Ref@TeX{}}. @xref{AUCTeX}, for more information. - -@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References -@section Referencing Labels -@cindex Referencing labels -@cindex Labels, referencing -@cindex Selection buffer, labels -@cindex Selection process -@cindex @code{\ref} -@kindex C-c ) -@findex reftex-reference - -@vindex reftex-trust-label-prefix -@b{Ref@TeX{}} scans the document in order to find all labels. To make -referencing labels easier, it assigns to each label a category, the -@emph{label type} (for example section, table, figure, equation, etc.). -In order to determine the label type, RefTeX parses around each label -to see in what kind of environments it is located. You can speed up -the parsing by using type-specific prefixes for labels and configuring -the variable @code{reftex-trust-label-prefix}. - -Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c -)} in order to reference a label (reftex-reference). This will start a -selection process and finally insert the complete @samp{\ref@{label@}} -into the buffer. - -First, @b{Ref@TeX{}} will determine the label category which is required. -Often that can be figured out from context. For example, if you -write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows -that an equation label is going to be referenced. If it cannot figure -out what label category is needed, it will query for one. - -You will then be presented with a label selection menu. This is a -special buffer which contains an outline of the document along with all -labels of the given label category. In addition, next to the label -there will be one line of context of the label definition, which is some -text in the buffer near the label definition. Usually this is -sufficient to identify the label. If you are unsure about a certain -label, pressing @key{SPC} will show the label definition point in -another window. - -In order to reference a label, move to cursor to the correct label and -press @key{RET}. You can also reference several labels with a single -call to @code{reftex-reference} by marking entries with the @kbd{m} -key (see below). - -@kindex ? -Here is a list of special commands in the selection buffer. A summary -of this information is always available from the selection process by -pressing @kbd{?}. - - - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next label. - -@item p -Go to previous label. - -@item b -Jump back to the position where you last left the selection buffer. -Normally this should get you back to the last referenced label. - -@item C-c C-n -Goto next section heading. - -@item C-c C-p -Goto previous section heading. - -@item N z -Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to -section 3. - -@tablesubheading{Displaying Context} -@item @key{SPC} -Show the surroundings of the definition of the current label in another -window. See also the @kbd{f} key. - -@item f -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always display the full context of the current label. This is similar -to pressing @key{SPC} after each cursor motion. Note that only context -in files already visited is shown. @b{RefTeX} will not visit a file -just for follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-reference}. - -@tablesubheading{Selecting a label and creating the reference} -@item @key{RET} -Insert a reference to the label at point into the buffer from which the -selection process was started. When entries have been marked, @key{RET} -references all marked labels. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a label will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, @ref{Options -(Misc)}. - -@vindex reftex-multiref-punctuation -@item m - + , -Mark the current entry. When several entries have been marked, pressing -@kbd{RET} will accept all of them and place them into several -@code{\ref} macros. The special markers @samp{,-+} also store a -separator to be inserted before the corresponding reference. So marking -six entries with the keys @samp{m , , - , +} will give a reference list -like this (see the variable @code{reftex-multiref-punctuation}) -@example -In eqs. (1), (2), (3)--(4), (5) and (6) -@end example - -@item u -Unmark a marked entry. - -@c FIXME: Do we need `A' as well for consistency? -@cindex LaTeX packages, @code{saferef} -@cindex @code{saferef}, LaTeX package -@item a -Accept the marked entries and put all labels as a comma-separated list -into one @emph{single} @code{\ref} macro. Some packages like -@file{saferef.sty} support multiple references in this way. - -@item l -Use the last referenced label(s) again. This is equivalent to moving to -that label and pressing @key{RET}. - -@item @key{TAB} -Enter a label with completion. This may also be a label which does not -yet exist in the document. - -@item v -@cindex @code{varioref}, LaTeX package -@cindex @code{\vref} -@cindex LaTeX packages, @code{varioref} -Toggle between @code{\ref} and @code{\vref} macro for references. The -@code{\vref} macro is defined in the @code{varioref} LaTeX package. -With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} -macro. The current state of this flag is displayed by the @samp{S<>} -indicator in the mode line of the selection buffer. - -@item V -@cindex @code{fancyref}, LaTeX package -@cindex @code{\fref} -@cindex @code{\Fref} -@cindex LaTeX packages, @code{fancyref} -Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The -@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} -LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a -@code{\fref} or @code{\Fref} macro. The current state of this flag is -displayed by the @samp{S<>} indicator in the mode line of the -selection buffer. - -@tablesubheading{Exiting} - -@item q -Exit the selection process without inserting any reference into the -buffer. - -@tablesubheading{Controlling what gets displayed} -@vindex reftex-label-menu-flags -The defaults for the following flags can be configured with the variable -@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). - -@item c -Toggle the display of the one-line label definition context in the -selection buffer. - -@item F -Toggle the display of the file borders of a multifile document in the -selection buffer. - -@item t -Toggle the display of the table of contents in the selection buffer. -With prefix @var{arg}, change the maximum level of toc entries displayed -to @var{arg}. Chapters are level 1, section are level 2. - -@item # -Toggle the display of a label counter in the selection buffer. - -@item % -Toggle the display of labels hidden in comments in the selection -buffers. Sometimes, you may have commented out parts of your document. -If these parts contain label definitions, @b{Ref@TeX{}} can still display -and reference these labels. - -@tablesubheading{Updating the buffer} -@item g -Update the menu. This will rebuilt the menu from the internal label -list, but not reparse the document (see @kbd{r}). - -@item r -@vindex reftex-enable-partial-scans -Reparse the document to update the information on all labels and rebuild -the menu. If the variable @code{reftex-enable-partial-scans} is -non-@code{nil} and your document is a multifile document, this will -reparse only a part of the document (the file in which the label at -point was defined). - -@item C-u r -Reparse the @emph{entire} document. - -@item s -Switch the label category. After prompting for another label category, -a menu for that category will be shown. - -@item x -Reference a label from an external document. With the LaTeX package -@code{xr} it is possible to reference labels defined in another -document. This key will switch to the label menu of an external -document and let you select a label from there (@pxref{xr (LaTeX -package),,xr}). - -@end table - -@vindex reftex-select-label-map -In order to define additional commands for the selection process, the -keymap @code{reftex-select-label-map} may be used. - -@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References -@section Builtin Label Environments -@cindex Builtin label environments -@cindex Label environments, builtin -@cindex Environments, builtin -@vindex reftex-label-alist -@vindex reftex-label-alist-builtin - -@b{Ref@TeX{}} needs to be aware of the environments which can be referenced -with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} -recognizes all labeled environments and macros discussed in @cite{The -LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley -1994.}. These are: - -@itemize @minus -@item -@cindex @code{figure}, LaTeX environment -@cindex @code{figure*}, LaTeX environment -@cindex @code{table}, LaTeX environment -@cindex @code{table*}, LaTeX environment -@cindex @code{equation}, LaTeX environment -@cindex @code{eqnarray}, LaTeX environment -@cindex @code{enumerate}, LaTeX environment -@cindex @code{\footnote}, LaTeX macro -@cindex LaTeX macro @code{footnote} -@cindex LaTeX core -@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, -@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is -the LaTeX core stuff) -@item -@cindex AMS-LaTeX -@cindex @code{amsmath}, LaTeX package -@cindex LaTeX packages, @code{amsmath} -@cindex @code{align}, AMS-LaTeX environment -@cindex @code{gather}, AMS-LaTeX environment -@cindex @code{multline}, AMS-LaTeX environment -@cindex @code{flalign}, AMS-LaTeX environment -@cindex @code{alignat}, AMS-LaTeX environment -@cindex @code{xalignat}, AMS-LaTeX environment -@cindex @code{xxalignat}, AMS-LaTeX environment -@cindex @code{subequations}, AMS-LaTeX environment -@code{align}, @code{gather}, @code{multline}, @code{flalign}, -@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} -(from AMS-LaTeX's @file{amsmath.sty} package) -@item -@cindex @code{endnote}, LaTeX package -@cindex LaTeX packages, @code{endnote} -@cindex @code{\endnote}, LaTeX macro -the @code{\endnote} macro (from @file{endnotes.sty}) -@item -@cindex @code{fancybox}, LaTeX package -@cindex LaTeX packages, @code{fancybox} -@cindex @code{Beqnarray}, LaTeX environment -@code{Beqnarray} (@file{fancybox.sty}) -@item -@cindex @code{floatfig}, LaTeX package -@cindex LaTeX packages, @code{floatfig} -@cindex @code{floatingfig}, LaTeX environment -@code{floatingfig} (@file{floatfig.sty}) -@item -@cindex @code{longtable}, LaTeX package -@cindex LaTeX packages, @code{longtable} -@cindex @code{longtable}, LaTeX environment -@code{longtable} (@file{longtable.sty}) -@item -@cindex @code{picinpar}, LaTeX package -@cindex LaTeX packages, @code{picinpar} -@cindex @code{figwindow}, LaTeX environment -@cindex @code{tabwindow}, LaTeX environment -@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) -@item -@cindex @code{sidecap}, LaTeX package -@cindex LaTeX packages, @code{sidecap} -@cindex @code{SCfigure}, LaTeX environment -@cindex @code{SCtable}, LaTeX environment -@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) -@item -@cindex @code{rotating}, LaTeX package -@cindex LaTeX packages, @code{rotating} -@cindex @code{sidewaysfigure}, LaTeX environment -@cindex @code{sidewaystable}, LaTeX environment -@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) -@item -@cindex @code{subfig}, LaTeX package -@cindex LaTeX packages, @code{subfigure} -@cindex @code{subfigure}, LaTeX environment -@cindex @code{subfigure*}, LaTeX environment -@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro -(@file{subfigure.sty}) -@item -@cindex @code{supertab}, LaTeX package -@cindex LaTeX packages, @code{supertab} -@cindex @code{supertabular}, LaTeX environment -@code{supertabular} (@file{supertab.sty}) -@item -@cindex @code{wrapfig}, LaTeX package -@cindex LaTeX packages, @code{wrapfig} -@cindex @code{wrapfigure}, LaTeX environment -@code{wrapfigure} (@file{wrapfig.sty}) -@end itemize - -If you want to use other labeled environments, defined with -@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize -them (@pxref{Defining Label Environments}). - -@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References -@section Defining Label Environments -@cindex Label environments, defining - -@vindex reftex-label-alist -@b{Ref@TeX{}} can be configured to recognize additional labeled -environments and macros. This is done with the variable -@code{reftex-label-alist} (@pxref{Options (Defining Label -Environments)}). If you are not familiar with Lisp, you can use the -@code{custom} library to configure this rather complex variable. To do -this, use - -@example -@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} -@end example - -@vindex reftex-label-alist-builtin -Here we will discuss a few examples, in order to make things clearer. -It can also be instructive to look at the constant -@code{reftex-label-alist-builtin} which contains the entries for -all the builtin environments and macros (@pxref{Builtin Label -Environments}). - -@menu -* Theorem and Axiom:: Defined with @code{\newenvironment}. -* Quick Equation:: When a macro sets the label type. -* Figure Wrapper:: When a macro argument is a label. -* Adding Magic Words:: Other words for other languages. -* Using \eqref:: How to switch to this AMS-LaTeX macro. -* Non-Standard Environments:: Environments without \begin and \end -* Putting it Together:: How to combine many entries. -@end menu - -@node Theorem and Axiom, Quick Equation, , Defining Label Environments -@subsection Theorem and Axiom Environments -@cindex @code{theorem}, newtheorem -@cindex @code{axiom}, newtheorem -@cindex @code{\newtheorem} - -Suppose you are using @code{\newtheorem} in LaTeX in order to define two -new environments, @code{theorem} and @code{axiom} - -@example -\newtheorem@{axiom@}@{Axiom@} -\newtheorem@{theorem@}@{Theorem@} -@end example - -@noindent -to be used like this: - -@example -\begin@{axiom@} -\label@{ax:first@} - .... -\end@{axiom@} -@end example - -So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new -labeled environments which define their own label categories. We can -either use Lisp to do this (e.g. in @file{.emacs}) or use the custom -library. With Lisp it would look like this - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) -@end lisp - -The type indicator characters @code{?a} and @code{?h} are used for -prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} -was chosen for @code{theorem} since @code{?t} is already taken by -@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, -@code{?i}, @code{?n} are already used for standard environments. - -@noindent -The labels for Axioms and Theorems will have the prefixes @samp{ax:} and -@samp{thr:}, respectively. @xref{AUCTeX}, for information on how -AUCTeX can use RefTeX to automatically create labels when a new environment -is inserted into a buffer. Additionally, the following needs to be -added to one's .emacs file before AUCTeX will automatically create -labels for the new environments. - -@lisp -(add-hook 'LaTeX-mode-hook - (lambda () - (LaTeX-add-environments - '("axiom" LaTeX-env-label) - '("theorem" LaTeX-env-label)))) -@end lisp - - -@noindent -The @samp{~\ref@{%s@}} is a format string indicating how to insert -references to these labels. - -@noindent -The next item indicates how to grab context of the label definition. -@itemize @minus -@item -@code{t} means to get it from a default location (from the beginning of -a @code{\macro} or after the @code{\begin} statement). @code{t} is -@emph{not} a good choice for eqnarray and similar environments. -@item -@code{nil} means to use the text right after the label definition. -@item -For more complex ways of getting context, see the variable -@code{reftex-label-alist} (@ref{Options (Defining Label -Environments)}). -@end itemize - -The following list of strings is used to guess the correct label type -from the word before point when creating a reference. E.g. if you -write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, -@b{Ref@TeX{}} will know that you are looking for a theorem label and -restrict the menu to only these labels without even asking. - -The final item in each entry is the level at which the environment -should produce entries in the table of context buffer. If the number is -positive, the environment will produce numbered entries (like -@code{\section}), if it is negative the entries will be unnumbered (like -@code{\section*}). Use this only for environments which structure the -document similar to sectioning commands. For everything else, omit the -item. - -To do the same configuration with @code{customize}, you need to click on -the @code{[INS]} button twice to create two templates and fill them in -like this: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: axiom - Type specification : [Value Menu] Char : a - Label prefix string : [Value Menu] String: ax: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] After label - Magic words: - [INS] [DEL] String: axiom - [INS] [DEL] String: ax. - [INS] - [X] Make TOC entry : [Value Menu] Level: -2 -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: theorem - Type specification : [Value Menu] Char : h - Label prefix string : [Value Menu] String: thr: - Label reference format: [Value Menu] String: ~\ref@{%s@} - Context method : [Value Menu] Default position - Magic words: - [INS] [DEL] String: theorem - [INS] [DEL] String: theor. - [INS] [DEL] String: th. - [INS] - [X] Make TOC entry : [Value Menu] Level: -3 -@end example - -@vindex reftex-insert-label-flags -@vindex reftex-label-menu-flags -Depending on how you would like the label insertion and selection for -the new environments to work, you might want to add the letters @samp{a} -and @samp{h} to some of the flags in the variables -@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) -and @code{reftex-label-menu-flags} (@pxref{Options (Referencing -Labels)}). - - -@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments -@subsection Quick Equation Macro -@cindex Quick equation macro -@cindex Macros as environment wrappers - -Suppose you would like to have a macro for quick equations. It -could be defined like this: - -@example -\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} -@end example - -@noindent -and used like this: - -@example -Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. -@end example - -We need to tell @b{Ref@TeX{}} that any label defined in the argument of the -@code{\quickeq} is an equation label. Here is how to do this with lisp: - -@lisp -(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) -@end lisp - -The first element in this list is now the macro with empty braces as an -@emph{image} of the macro arguments. @code{?e} indicates that this is -an equation label, the different @code{nil} elements indicate to use the -default values for equations. The @samp{1} as the fifth element -indicates that the context of the label definition should be the 1st -argument of the macro. - -Here is again how this would look in the customization buffer: - -@example -Reftex Label Alist: [Hide] -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \quickeq@{@} - Type specification : [Value Menu] Char : e - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 1 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments -@subsection Figure Wrapping Macro -@cindex Macros as environment wrappers -@cindex Figure wrapping macro - -Suppose you want to make figures not directly with the figure -environment, but with a macro like - -@example -\newcommand@{\myfig@}[5][tbp]@{% - \begin@{figure@}[#1] - \epsimp[#5]@{#2@} - \caption@{#3@} - \label@{#4@} - \end@{figure@}@} -@end example - -@noindent -which would be called like - -@example -\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} -@end example - -Now we need to tell @b{Ref@TeX{}} that the 4th argument of the -@code{\myfig} macro @emph{is itself} a figure label, and where to find -the context. - -@lisp -(setq reftex-label-alist - '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) -@end lisp - -The empty pairs of brackets indicate the different arguments of the -@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} -indicates that this is a figure label which will be listed together with -labels from normal figure environments. The @code{nil} entries for -prefix and reference format mean to use the defaults for figure labels. -The @samp{3} for the context method means to grab the 3rd macro argument -- the caption. - -As a side effect of this configuration, @code{reftex-label} will now -insert the required naked label (without the @code{\label} macro) when -point is directly after the opening parenthesis of a @code{\myfig} macro -argument. - -Again, here the configuration in the customization buffer: - -@example -[INS] [DEL] Package or Detailed : [Value Menu] Detailed: - Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} - Type specification : [Value Menu] Char : f - Label prefix string : [Value Menu] Default - Label reference format: [Value Menu] Default - Context method : [Value Menu] Macro arg nr: 3 - Magic words: - [INS] - [ ] Make TOC entry : [Value Menu] No entry -@end example - -@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments -@subsection Adding Magic Words -@cindex Magic words -@cindex German magic words -@cindex Label category - -Sometimes you don't want to define a new label environment or macro, but -just change the information associated with a label category. Maybe you -want to add some magic words, for another language. Changing only the -information associated with a label category is done by giving -@code{nil} for the environment name and then specify the items you want -to define. Here is an example which adds German magic words to all -predefined label categories. - -@lisp -(setq reftex-label-alist - '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) - (nil ?e nil nil nil ("Gleichung" "Gl.")) - (nil ?t nil nil nil ("Tabelle")) - (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) - (nil ?n nil nil nil ("Anmerkung" "Anm.")) - (nil ?i nil nil nil ("Punkt")))) -@end lisp - -@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments -@subsection Using @code{\eqref} -@cindex @code{\eqref}, AMS-LaTeX macro -@cindex AMS-LaTeX -@cindex Label category - -Another case where one only wants to change the information associated -with the label category is to change the macro which is used for -referencing the label. When working with the AMS-LaTeX stuff, you might -prefer @code{\eqref} for doing equation references. Here is how to -do this: - -@lisp -(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) -@end lisp - -@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The -following is equivalent to the line above. - -@lisp -(setq reftex-label-alist '(AMSTeX)) -@end lisp - -Note that this is automatically done by the @file{amsmath.el} style file -of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, -this configuration will not be necessary. - -@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments -@subsection Non-standard Environments -@cindex Non-standard environments -@cindex Environments without @code{\begin} -@cindex Special parser functions -@cindex Parser functions, for special environments - -Some LaTeX packages define environment-like structures without using the -standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse -these directly, but you can write your own special-purpose parser and -use it instead of the name of an environment in an entry for -@code{reftex-label-alist}. The function should check if point is -currently in the special environment it was written to detect. If so, -it must return a buffer position indicating the start of this -environment. The return value must be @code{nil} on failure to detect -the environment. The function is called with one argument @var{bound}. -If non-@code{nil}, @var{bound} is a boundary for backwards searches -which should be observed. We will discuss two examples. - -@cindex LaTeX commands, abbreviated - -Some people define abbreviations for -environments, like @code{\be} for @code{\begin@{equation@}}, and -@code{\ee} for @code{\end@{equation@}}. The parser function would have -to search backward for these macros. When the first match is -@code{\ee}, point is not in this environment. When the first match is -@code{\be}, point is in this environment and the function must return -the beginning of the match. To avoid scanning too far, we can also look -for empty lines which cannot occur inside an equation environment. -Here is the setup: - -@lisp -;; Setup entry in reftex-label-alist, using all defaults for equations -(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) - -(defun detect-be-ee (bound) - ;; Search backward for the macros or an empty line - (if (re-search-backward - "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) - (if (match-beginning 2) - (match-beginning 2) ; Return start of environment - nil) ; Return nil because env is closed - nil)) ; Return nil for not found -@end lisp - -@cindex @code{linguex}, LaTeX package -@cindex LaTeX packages, @code{linguex} -A more complex example is the @file{linguex.sty} package which defines -list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are -terminated by @samp{\z.} or by an empty line. - -@example -\ex. \label@{ex:12@} Some text in an exotic language ... - \a. \label@{ex:13@} more stuff - \b. \label@{ex:14@} still more stuff - \a. List on a deeper level - \b. Another item - \b. and the third one - \z. - \b. Third item on this level. - -... text after the empty line terminating all lists -@end example - -The difficulty is that the @samp{\a.} lists can nest and that an empty -line terminates all list levels in one go. So we have to count nesting -levels between @samp{\a.} and @samp{\z.}. Here is the implementation -for @b{Ref@TeX{}}. - -@lisp -(setq reftex-label-alist - '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) - -(defun detect-linguex (bound) - (let ((cnt 0)) - (catch 'exit - (while - ;; Search backward for all possible delimiters - (re-search-backward - (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" - "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") - nil t) - ;; Check which delimiter was matched. - (cond - ((match-beginning 1) - ;; empty line terminates all - return nil - (throw 'exit nil)) - ((match-beginning 2) - ;; \z. terminates one list level - decrease nesting count - (decf cnt)) - ((match-beginning 3) - ;; \ex. : return match unless there was a \z. on this level - (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) - ((match-beginning 4) - ;; \a. : return match when on level 0, otherwise - ;; increment nesting count - (if (>= cnt 0) - (throw 'exit (match-beginning 4)) - (incf cnt)))))))) -@end lisp - -@node Putting it Together, , Non-Standard Environments, Defining Label Environments -@subsection Putting it all together - -When you have to put several entries into @code{reftex-label-alist}, just -put them after each other in a list, or create that many templates in -the customization buffer. Here is a lisp example which uses several of -the entries described above: - -@lisp -(setq reftex-label-alist - '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) - ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) - ("\\quickeq@{@}" ?e nil nil 1 nil) - AMSTeX - ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) - (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) -@end lisp - -@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References -@section Reference Info -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@cindex Cross-references, displaying -@cindex Reference info -@cindex Displaying cross-references -@cindex Viewing cross-references -@kindex C-c & -@kindex S-mouse-2 - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\ref} macro, the echo area will display some -information about the label referenced there. Note that the information -is only displayed if the echo area is not occupied by a different -message. - -@b{Ref@TeX{}} can also display the label definition corresponding to a -@code{\ref} macro, or all reference locations corresponding to a -@code{\label} macro. @xref{Viewing Cross-References}, for more -information. - -@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References -@section @code{xr}: Cross-Document References -@cindex @code{xr}, LaTeX package -@cindex LaTeX packages, @code{xr} -@cindex @code{\externaldocument} -@cindex External documents -@cindex References to external documents -@cindex Cross-document references - -The LaTeX package @code{xr} makes it possible to create references to -labels defined in external documents. The preamble of a document using -@code{xr} will contain something like this: - -@example -\usepackage@{xr@} -\externaldocument[V1-]@{volume1@} -\externaldocument[V3-]@{volume3@} -@end example - -@noindent -and we can make references to any labels defined in these -external documents by using the prefixes @samp{V1-} and @samp{V3-}, -respectively. - -@b{Ref@TeX{}} can be used to create such references as well. Start the -referencing process normally, by pressing @kbd{C-c )}. Select a label -type if necessary. When you see the label selection buffer, pressing -@kbd{x} will switch to the label selection buffer of one of the external -documents. You may then select a label as before and @b{Ref@TeX{}} will -insert it along with the required prefix. - -For this kind of inter-document cross-references, saving of parsing -information and the use of multiple selection buffers can mean a large -speed-up (@pxref{Optimizations}). - -@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References -@section @code{varioref}: Variable Page References -@cindex @code{varioref}, LaTeX package -@cindex @code{\vref} -@cindex LaTeX packages, @code{varioref} -@vindex reftex-vref-is-default -@code{varioref} is a frequently used LaTeX package to create -cross--references with page information. When you want to make a -reference with the @code{\vref} macro, just press the @kbd{v} key in the -selection buffer to toggle between @code{\ref} and @code{\vref} -(@pxref{Referencing Labels}). The mode line of the selection buffer -shows the current status of this switch. If you find that you almost -always use @code{\vref}, you may want to make it the default by -customizing the variable @code{reftex-vref-is-default}. If this -toggling seems too inconvenient, you can also use the command -@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. -Or use AUCTeX to create your macros (@pxref{AUCTeX}). - -@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References -@section @code{fancyref}: Fancy Cross References -@cindex @code{fancyref}, LaTeX package -@cindex @code{\fref} -@cindex @code{\Fref} -@cindex LaTeX packages, @code{fancyref} -@vindex reftex-fref-is-default -@code{fancyref} is a LaTeX package where a macro call like -@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of -the referenced counter but also the complete text around it, like -@samp{Figure 3 on the preceding page}. In order to make it work you -need to use label prefixes like @samp{fig:} consistently - something -@b{Ref@TeX{}} does automatically. When you want to make a reference -with the @code{\fref} macro, just press the @kbd{V} key in the selection -buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} -(@pxref{Referencing Labels}). The mode line of the selection buffer -shows the current status of this switch. If this cycling seems -inconvenient, you can also use the commands @code{reftex-fancyref-fref} -and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c -f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros -(@pxref{AUCTeX}). - -@node Citations, Index Support, Labels and References, Top -@chapter Citations -@cindex Citations -@cindex @code{\cite} - -Citations in LaTeX are done with the @code{\cite} macro or variations of -it. The argument of the macro is a citation key which identifies an -article or book in either a BibTeX database file or in an explicit -@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s -support for citations helps to select the correct key quickly. - -@menu -* Creating Citations:: How to create them. -* Citation Styles:: Natbib, Harvard, Chicago and Co. -* Citation Info:: View the corresponding database entry. -* Chapterbib and Bibunits:: Multiple bibliographies in a Document. -* Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. -@end menu - -@node Creating Citations, Citation Styles, , Citations -@section Creating Citations -@cindex Creating citations -@cindex Citations, creating -@findex reftex-citation -@kindex C-c [ -@cindex Selection buffer, citations -@cindex Selection process - -In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then -prompts for a regular expression which will be used to search through -the database and present the list of matches to choose from in a -selection process similar to that for selecting labels -(@pxref{Referencing Labels}). - -The regular expression uses an extended syntax: @samp{&&} defines a -logic @code{and} for regular expressions. For example -@samp{Einstein&&Bose} will match all articles which mention -Bose-Einstein condensation, or which are co-authored by Bose and -Einstein. When entering the regular expression, you can complete on -known citation keys. RefTeX also offers a default when prompting for a -regular expression. This default is the word before the cursor or the -word before the current @samp{\cite} command. Sometimes this may be a -good search key. - -@cindex @code{\bibliography} -@cindex @code{thebibliography}, LaTeX environment -@cindex @code{BIBINPUTS}, environment variable -@cindex @code{TEXBIB}, environment variable -@b{Ref@TeX{}} prefers to use BibTeX database files specified with a -@code{\bibliography} macro to collect its information. Just like -BibTeX, it will search for the specified files in the current directory -and along the path given in the environment variable @code{BIBINPUTS}. -If you do not use BibTeX, but the document contains an explicit -@code{thebibliography} environment, @b{Ref@TeX{}} will collect its -information from there. Note that in this case the information -presented in the selection buffer will just be a copy of relevant -@code{\bibitem} entries, not the structured listing available with -BibTeX database files. - -@kindex ? -In the selection buffer, the following keys provide special commands. A -summary of this information is always available from the selection -process by pressing @kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Show a summary of available commands. - -@item 0-9,- -Prefix argument. - -@tablesubheading{Moving around} -@item n -Go to next article. - -@item p -Go to previous article. - -@tablesubheading{Access to full database entries} -@item @key{SPC} -Show the database entry corresponding to the article at point, in -another window. See also the @kbd{f} key. - -@item f -Toggle follow mode. When follow mode is active, the other window will -always display the full database entry of the current article. This is -equivalent to pressing @key{SPC} after each cursor motion. With BibTeX -entries, follow mode can be rather slow. - -@tablesubheading{Selecting entries and creating the citation} -@item @key{RET} -Insert a citation referencing the article at point into the buffer from -which the selection process was started. - -@item mouse-2 -@vindex reftex-highlight-selection -Clicking with mouse button 2 on a citation will accept it like @key{RET} -would. See also variable @code{reftex-highlight-selection}, @ref{Options -(Misc)}. - -@item m -Mark the current entry. When one or several entries are marked, -pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, -@key{RET} behaves like the @kbd{a} key. - -@item u -Unmark a marked entry. - -@item a -Accept all (marked) entries in the selection buffer and create a single -@code{\cite} macro referring to them. - -@item A -Accept all (marked) entries in the selection buffer and create a -separate @code{\cite} macro for each of it. - -@item e -Create a new BibTeX database file which contains all @i{marked} entries -in the selection buffer. If no entries are marked, all entries are -selected. - -@item E -Create a new BibTeX database file which contains all @i{unmarked} -entries in the selection buffer. If no entries are marked, all entries -are selected. - -@item @key{TAB} -Enter a citation key with completion. This may also be a key which does -not yet exist. - -@item . -Show insertion point in another window. This is the point from where you -called @code{reftex-citation}. - -@tablesubheading{Exiting} -@item q -Exit the selection process without inserting a citation into the -buffer. - -@tablesubheading{Updating the buffer} - -@item g -Start over with a new regular expression. The full database will be -rescanned with the new expression (see also @kbd{r}). - -@c FIXME: Should we use something else here? r is usually rescan! -@item r -Refine the current selection with another regular expression. This will -@emph{not} rescan the entire database, but just the already selected -entries. - -@end table - -@vindex reftex-select-bib-map -In order to define additional commands for this selection process, the -keymap @code{reftex-select-bib-map} may be used. - -@node Citation Styles, Citation Info, Creating Citations, Citations -@section Citation Styles -@cindex Citation styles -@cindex Citation styles, @code{natbib} -@cindex Citation styles, @code{harvard} -@cindex Citation styles, @code{chicago} -@cindex Citation styles, @code{jurabib} -@cindex @code{natbib}, citation style -@cindex @code{harvard}, citation style -@cindex @code{chicago}, citation style -@cindex @code{jurabib}, citation style - -@vindex reftex-cite-format -The standard LaTeX macro @code{\cite} works well with numeric or simple -key citations. To deal with the more complex task of author-year -citations as used in many natural sciences, a variety of packages has -been developed which define derived forms of the @code{\cite} macro. -@b{Ref@TeX{}} can be configured to produce these citation macros as well -by setting the variable @code{reftex-cite-format}. For the most -commonly used packages (@code{natbib}, @code{harvard}, @code{chicago}, -@code{jurabib}) this may be done from the menu, under -@code{Ref->Citation Styles}. Since there are usually several macros to -create the citations, executing @code{reftex-citation} (@kbd{C-c [}) -starts by prompting for the correct macro. For the Natbib style, this -looks like this: - -@example -SELECT A CITATION FORMAT - -[^M] \cite@{%l@} -[t] \citet@{%l@} -[T] \citet*@{%l@} -[p] \citep@{%l@} -[P] \citep*@{%l@} -[e] \citep[e.g.][]@{%l@} -[s] \citep[see][]@{%l@} -[a] \citeauthor@{%l@} -[A] \citeauthor*@{%l@} -[y] \citeyear@{%l@} -@end example - -@vindex reftex-cite-prompt-optional-args -If cite formats contain empty paris of square brackets, RefTeX can -will prompt for values of these optional arguments if you call the -@code{reftex-citation} command with a @kbd{C-u} prefix. -Following the most generic of these packages, @code{natbib}, the builtin -citation packages always accept the @kbd{t} key for a @emph{textual} -citation (like: @code{Jones et al. (1997) have shown...}) as well as -the @kbd{p} key for a parenthetical citation (like: @code{As shown -earlier (Jones et al, 1997)}). - -To make one of these styles the default, customize the variable -@code{reftex-cite-format} or put into @file{.emacs}: - -@lisp -(setq reftex-cite-format 'natbib) -@end lisp - -You can also use AUCTeX style files to automatically set the -citation style based on the @code{usepackage} commands in a given -document. @xref{Style Files}, for information on how to set up the style -files correctly. - -@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top -@section Citation Info -@cindex Displaying citations -@cindex Citations, displaying -@cindex Citation info -@cindex Viewing citations -@kindex C-c & -@kindex S-mouse-2 -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref - -When point is idle for more than @code{reftex-idle-time} seconds on the -argument of a @code{\cite} macro, the echo area will display some -information about the article cited there. Note that the information is -only displayed if the echo area is not occupied by a different message. - -@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database -entry corresponding to a @code{\cite} macro, or all citation locations -corresponding to a @code{\bibitem} or BibTeX database entry. -@xref{Viewing Cross-References}. - -@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations -@section Chapterbib and Bibunits -@cindex @code{chapterbib}, LaTeX package -@cindex @code{bibunits}, LaTeX package -@cindex Bibliographies, multiple - -@code{chapterbib} and @code{bibunits} are two LaTeX packages which -produce multiple bibliographies in a document. This is no problem for -@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database -files. If they do not, it is best to have each document part in a -separate file (as it is required for @code{chapterbib} anyway). Then -@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If -you have multiple bibliographies within a @emph{single file}, this may -or may not be the case. - -@node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations -@section Citations outside LaTeX -@cindex Citations outside LaTeX -@vindex reftex-default-bibliography - -The command @code{reftex-citation} can also be executed outside a LaTeX -buffer. This can be useful to reference articles in the mail buffer and -other documents. You should @emph{not} enter @code{reftex-mode} for -this, just execute the command. The list of BibTeX files will in this -case be taken from the variable @code{reftex-default-bibliography}. -Setting the variable @code{reftex-cite-format} to the symbol -@code{locally} does a decent job of putting all relevant information -about a citation directly into the buffer. Here is the lisp code to add -the @kbd{C-c [} binding to the mail buffer. It also provides a local -binding for @code{reftex-cite-format}. - -@lisp -(add-hook 'mail-setup-hook - (lambda () (define-key mail-mode-map "\C-c[" - (lambda () - (interactive) - (let ((reftex-cite-format 'locally)) - (reftex-citation)))))) -@end lisp - -@node BibTeX Database Subsets, , Citations Outside LaTeX, Citations -@section Database Subsets -@cindex BibTeX database subsets -@findex reftex-create-bibtex-file - -@b{Ref@TeX{}} offers two ways to create a new BibTeX database file. - -The first option produces a file which contains only the entries -actually referenced in the current document. This can be useful if -the database in only meant for a single document and you want to clean -it of old and unused ballast. It can also be useful while writing a -document together with collaborators, in order to avoid sending around -the entire (possibly very large) database. To create the file, use -@kbd{M-x reftex-create-bibtex-file}, also available from the menu -under @code{Ref->Global Actions->Create Bibtex File}. The command will -prompt for a BibTeX file name and write the extracted entries to that -file. - -The second option makes use of the selection process started by the -command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a -regular expression to select entries, and lists them in a formatted -selection buffer. After pressing the @kbd{e} key (mnemonics: Export), -the command will prompt for the name of a new BibTeX file and write -the selected entries to that file. You can also first mark some -entries in the selection buffer with the @kbd{m} key and then export -either the @i{marked} entries (with the @kbd{e} key) or the -@i{unmarked} entries (with the @kbd{E} key). - -@node Index Support, Viewing Cross-References, Citations, Top -@chapter Index Support -@cindex Index Support -@cindex @code{\index} - -LaTeX has builtin support for creating an Index. The LaTeX core -supports two different indices, the standard index and a glossary. With -the help of special LaTeX packages (@file{multind.sty} or -@file{index.sty}), any number of indices can be supported. - -Index entries are created with the @code{\index@{@var{entry}@}} macro. -All entries defined in a document are written out to the @file{.aux} -file. A separate tool must be used to convert this information into a -nicely formatted index. Tools used with LaTeX include @code{MakeIndex} -and @code{xindy}. - -Indexing is a very difficult task. It must follow strict conventions to -make the index consistent and complete. There are basically two -approaches one can follow, and both have their merits. - -@enumerate -@item -Part of the indexing should already be done with the markup. The -document structure should be reflected in the index, so when starting -new sections, the basic topics of the section should be indexed. If the -document contains definitions, theorems or the like, these should all -correspond to appropriate index entries. This part of the index can -very well be developed along with the document. Often it is worthwhile -to define special purpose macros which define an item and at the same -time make an index entry, possibly with special formatting to make the -reference page in the index bold or underlined. To make @b{Ref@TeX{}} -support for indexing possible, these special macros must be added to -@b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}). - -@item -The rest of the index is often just a collection of where in the -document certain words or phrases are being used. This part is -difficult to develop along with the document, because consistent entries -for each occurrence are needed and are best selected when the document -is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file} -which collects phrases and helps indexing the phrases globally. -@end enumerate - -Before you start, you need to make sure that @b{Ref@TeX{}} knows about -the index style being used in the current document. @b{Ref@TeX{}} has -builtin support for the default @code{\index} and @code{\glossary} -macros. Other LaTeX packages, like the @file{multind} or @file{index} -package, redefine the @code{\index} macro to have an additional -argument, and @b{Ref@TeX{}} needs to be configured for those. A -sufficiently new version of AUCTeX (9.10c or later) will do this -automatically. If you really don't use AUCTeX (you should!), this -configuration needs to be done by hand with the menu (@code{Ref->Index -Style}), or globally for all your documents with - -@lisp -(setq reftex-index-macros '(multind)) @r{or} -(setq reftex-index-macros '(index)) -@end lisp - -@menu -* Creating Index Entries:: Macros and completion of entries. -* The Index Phrases File:: A special file for global indexing. -* Displaying and Editing the Index:: The index editor. -* Builtin Index Macros:: The index macros RefTeX knows about. -* Defining Index Macros:: ... and macros it doesn't. -@end menu - -@node Creating Index Entries, The Index Phrases File, , Index Support -@section Creating Index Entries -@cindex Creating index entries -@cindex Index entries, creating -@kindex C-c < -@findex reftex-index -@kindex C-c / -@findex reftex-index-selection-or-word - -In order to index the current selection or the word at the cursor press -@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the -selection or word @samp{@var{word}} to be replaced with -@samp{\index@{@var{word}@}@var{word}}. The macro which is used -(@code{\index} by default) can be configured with the variable -@code{reftex-index-default-macro}. When the command is called with a -prefix argument (@kbd{C-u C-c /}), you get a chance to edit the -generated index entry. Use this to change the case of the word or to -make the entry a subentry, for example by entering -@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes -(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. -When there is nothing selected and no word at point, this command will -just call @code{reftex-index}, described below. - -In order to create a general index entry, press @kbd{C-c <} -(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the -available index macros and for its arguments. Completion will be -available for the index entry and, if applicable, the index tag. The -index tag is a string identifying one of multiple indices. With the -@file{multind} and @file{index} packages, this tag is the first argument -to the redefined @code{\index} macro. - -@node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support -@section The Index Phrases File -@cindex Index phrase file -@cindex Phrase file -@kindex C-c | -@findex reftex-index-visit-phrases-buffer -@cindex Macro definition lines, in phrase buffer - -@b{Ref@TeX{}} maintains a file in which phrases can be collected for -later indexing. The file is located in the same directory as the master -file of the document and has the extension @file{.rip} (@b{R}eftex -@b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c -|} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it -is initialized by inserting a file header which contains the definition -of the available index macros. This list is initialized from -@code{reftex-index-macros} (@pxref{Defining Index Macros}). You can -edit the header as needed, but if you define new LaTeX indexing macros, -don't forget to add them to @code{reftex-index-macros} as well. Here is -a phrase file header example: - -@example -% -*- mode: reftex-index-phrases -*- -% Key Macro Format Repeat -%---------------------------------------------------------- ->>>INDEX_MACRO_DEFINITION: i \index@{%s@} t ->>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil ->>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t ->>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil -%---------------------------------------------------------- -@end example - -The macro definition lines consist of a unique letter identifying a -macro, a format string and the @var{repeat} flag, all separated by -@key{TAB}. The format string shows how the macro is to be applied, the -@samp{%s} will be replaced with the index entry. The repeat flag -indicates if @var{word} is indexed by the macro as -@samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as -@samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the -above example it is assumed that the macro @code{\index*@{@var{word}@}} -already typesets its argument in the text, so that it is unnecessary to -repeat @var{word} outside the macro. - -@menu -* Collecting Phrases:: Collecting from document or external. -* Consistency Checks:: Check for duplicates etc. -* Global Indexing:: The interactive indexing process. -@end menu - -@node Collecting Phrases, Consistency Checks, , The Index Phrases File -@subsection Collecting Phrases -@cindex Collecting index phrases -@cindex Index phrases, collection -@cindex Phrases, collecting - -Phrases for indexing can be collected while writing the document. The -command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) -copies the current selection (if active) or the word near point into the -phrases buffer. It then selects this buffer, so that the phrase line -can be edited. To return to the LaTeX document, press @kbd{C-c C-c} -(@code{reftex-index-phrases-save-and-return}). - -You can also prepare the list of index phrases in a different way and -copy it into the phrases file. For example you might want to start from -a word list of the document and remove all words which should not be -indexed. - -The phrase lines in the phrase buffer must have a specific format. -@b{Ref@TeX{}} will use font-lock to indicate if a line has the proper -format. A phrase line looks like this: - -@example -[@var{key}] @var{phrase} [ @var{arg}[&&@var{arg}]... [ || @var{arg}]...] -@end example - -@code{} stands for white space containing at least one @key{TAB}. -@var{key} must be at the start of the line and is the character -identifying one of the macros defined in the file header. It is -optional - when omitted, the first macro definition line in the file -will be used for this phrase. The @var{phrase} is the phrase to be -searched for when indexing. It may contain several words separated by -spaces. By default the search phrase is also the text entered as -argument of the index macro. If you want the index entry to be -different from the search phrase, enter another @key{TAB} and the index -argument @var{arg}. If you want to have each match produce several -index entries, separate the different index arguments with @samp{ && -}@footnote{@samp{&&} with optional spaces, see -@code{reftex-index-phrases-logical-and-regexp}.}. If you want to be -able to choose at each match between several different index arguments, -separate them with @samp{ || }@footnote{@samp{||} with optional spaces, -see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an -example: - -@example -%-------------------------------------------------------------------- -I Sun -i Planet Planets -i Vega Stars!Vega - Jupiter Planets!Jupiter -i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars -i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto -@end example - - -So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while -@samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. -@samp{Vega} will be indexed as a subitem of @samp{Stars}. The -@samp{Jupiter} line will also use the @samp{i} macro as it was the first -macro definition in the file header (see above example). At each -occurrence of @samp{Mars} you will be able choose between indexing it as -a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. -Finally, every occurrence of @samp{Pluto} will be indexed as -@samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} -and will therefore create two different index entries. - -@node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File -@subsection Consistency Checks -@cindex Index phrases, consistency checks -@cindex Phrases, consistency checks -@cindex Consistency check for index phrases - -@kindex C-c C-s -Before indexing the phrases in the phrases buffer, they should be -checked carefully for consistency. A first step is to sort the phrases -alphabetically - this is done with the command @kbd{C-c C-s} -(@code{reftex-index-sort-phrases}). It will sort all phrases in the -buffer alphabetically by search phrase. If you want to group certain -phrases and only sort within the groups, insert empty lines between the -groups. Sorting will only change the sequence of phrases within each -group (see the variable @code{reftex-index-phrases-sort-in-blocks}). - -@kindex C-c C-i -A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) -which lists information about the phrase at point, including an example -of how the index entry will look like and the number of expected matches -in the document. - -@kindex C-c C-t -Another important check is to find out if there are double or -overlapping entries in the buffer. For example if you are first -searching and indexing @samp{Mars} and then @samp{Planet Mars}, the -second phrase will not match because of the index macro inserted before -@samp{Mars} earlier. The command @kbd{C-c C-t} -(@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in -the buffer which is either duplicate or a subphrase of another phrase. -In order to check the whole buffer like this, start at the beginning and -execute this command repeatedly. - -@node Global Indexing, , Consistency Checks, The Index Phrases File -@subsection Global Indexing -@cindex Global indexing -@cindex Indexing, global -@cindex Indexing, from @file{phrases} buffer - -Once the index phrases have been collected and organized, you are set -for global indexing. I recommend to do this only on an otherwise -finished document. Global indexing starts from the phrases buffer. -There are several commands which start indexing: @kbd{C-c C-x} acts on -the current phrase line, @kbd{C-c C-r} on all lines in the current -region and @kbd{C-c C-a} on all phrase lines in the buffer. It is -probably good to do indexing in small chunks since your concentration -may not last long enough to do everything in one go. - -@b{Ref@TeX{}} will start at the first phrase line and search the phrase -globally in the whole document. At each match it will stop, compute the -replacement string and offer you the following choices@footnote{Windows -users: Restrict yourself to the described keys during indexing. Pressing -@key{Help} at the indexing prompt can apparently hang Emacs.}: - -@table @kbd -@item y -Replace this match with the proposed string. -@item n -Skip this match. -@item ! -Replace this and all further matches in this file. -@item q -Skip this match, start with next file. -@item Q -Skip this match, start with next phrase. -@item o -Select a different indexing macro for this match. -@item 1-9 -Select one of multiple index keys (those separated with @samp{||}). -@item e -Edit the replacement text. -@item C-r -Recursive edit. Use @kbd{C-M-c} to return to the indexing process. -@item s -Save this buffer and ask again about the current match. -@item S -Save all document buffers and ask again about the current match. -@item C-g -Abort the indexing process. -@end table - -The @samp{Find and Index in Document} menu in the phrases buffer also -lists a few options for the indexing process. The options have -associated customization variables to set the defaults (@pxref{Options -(Index Support)}). Here is a short explanation of what the options do: - -@table @i -@item Match Whole Words -When searching for index phrases, make sure whole words are matched. -This should probably always be on. -@item Case Sensitive Search -Search case sensitively for phrases. I recommend to have this setting -off, in order to match the capitalized words at the beginning of a -sentence, and even typos. You can always say @emph{no} at a match you -do not like. -@item Wrap Long Lines -Inserting index macros increases the line length. Turn this option on -to allow @b{Ref@TeX{}} to wrap long lines. -@item Skip Indexed Matches -When this is on, @b{Ref@TeX{}} will at each match try to figure out if -this match is already indexed. A match is considered indexed if it is -either the argument of an index macro, or if an index macro is directly -(without whitespace separation) before or after the match. Index macros -are those configured in @code{reftex-index-macros}. Intended for -re-indexing a documents after changes have been made. -@end table - -Even though indexing should be the last thing you do to a document, you -are bound to make changes afterwards. Indexing then has to be applied -to the changed regions. The command -@code{reftex-index-phrases-apply-to-region} is designed for this -purpose. When called from a LaTeX document with active region, it will -apply @code{reftex-index-all-phrases} to the current region. - -@node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support -@section Displaying and Editing the Index -@cindex Displaying the Index -@cindex Editing the Index -@cindex Index entries, creating -@cindex Index, displaying -@cindex Index, editing -@kindex C-c > -@findex reftex-display-index - -In order to compile and display the index, press @kbd{C-c >}. If the -document uses multiple indices, @b{Ref@TeX{}} will ask you to select -one. Then, all index entries will be sorted alphabetically and -displayed in a special buffer, the @file{*Index*} buffer. From that -buffer you can check and edit each entry. - -The index can be restricted to the current section or the region. Then -only entries in that part of the document will go into the compiled -index. To restrict to the current section, use a numeric prefix -@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current -region, make the region active and use a numeric prefix @samp{3} (press -@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the -restriction can be moved from one section to the next by pressing the -@kbd{<} and @kbd{>} keys. - -One caveat: @b{Ref@TeX{}} finds the definition point of an index entry -by searching near the buffer position where it had found to macro during -scanning. If you have several identical index entries in the same -buffer and significant changes have shifted the entries around, you must -rescan the buffer to ensure the correspondence between the -@file{*Index*} buffer and the definition locations. It is therefore -advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) -frequently while editing the index from the @file{*Index*} -buffer. - -@kindex ? -Here is a list of special commands available in the @file{*Index*} buffer. A -summary of this information is always available by pressing -@kbd{?}. - -@table @kbd -@tablesubheading{General} -@item ? -Display a summary of commands. - -@item 0-9, - -Prefix argument. - -@tablesubheading{Moving around} -@item ! A..Z -Pressing any capital letter will jump to the corresponding section in -the @file{*Index*} buffer. The exclamation mark is special and jumps to -the first entries alphabetically sorted below @samp{A}. These are -usually non-alphanumeric characters. -@item n -Go to next entry. -@item p -Go to previous entry. - -@tablesubheading{Access to document locations} -@item @key{SPC} -Show the place in the document where this index entry is defined. - -@item @key{TAB} -Go to the definition of the current index entry in another -window. - -@item @key{RET} -Go to the definition of the current index entry and hide the -@file{*Index*} buffer window. - -@item f -@vindex reftex-index-follow-mode -@vindex reftex-revisit-to-follow -Toggle follow mode. When follow mode is active, the other window will -always show the location corresponding to the line in the @file{*Index*} -buffer at point. This is similar to pressing @key{SPC} after each -cursor motion. The default for this flag can be set with the variable -@code{reftex-index-follow-mode}. Note that only context in files -already visited is shown. @b{Ref@TeX{}} will not visit a file just for -follow mode. See, however, the variable -@code{reftex-revisit-to-follow}. - -@tablesubheading{Entry editing} -@item e -Edit the current index entry. In the minibuffer, you can edit the -index macro which defines this entry. - -@item C-k -Kill the index entry. Currently not implemented because I don't know -how to implement an @code{undo} function for this. - -@item * -Edit the @var{key} part of the entry. This is the initial part of the -entry which determines the location of the entry in the index. - -@item | -Edit the @var{attribute} part of the entry. This is the part after the -vertical bar. With @code{MakeIndex}, this part is an encapsulating -macro. With @code{xindy}, it is called @emph{attribute} and is a -property of the index entry that can lead to special formatting. When -called with @kbd{C-u} prefix, kill the entire @var{attribute} -part. - -@item @@ -Edit the @var{visual} part of the entry. This is the part after the -@samp{@@} which is used by @code{MakeIndex} to change the visual -appearance of the entry in the index. When called with @kbd{C-u} -prefix, kill the entire @var{visual} part. - -@item ( -Toggle the beginning of page range property @samp{|(} of the -entry. - -@item ) -Toggle the end of page range property @samp{|)} of the entry. - -@item _ -Make the current entry a subentry. This command will prompt for the -superordinate entry and insert it. - -@item ^ -Remove the highest superordinate entry. If the current entry is a -subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy -(@samp{bbb!ccc}). - -@tablesubheading{Exiting} -@item q -Hide the @file{*Index*} buffer. - -@item k -Kill the @file{*Index*} buffer. - -@item C-c = -Switch to the Table of Contents buffer of this document. - -@tablesubheading{Controlling what gets displayed} -@item c -@vindex reftex-index-include-context -Toggle the display of short context in the @file{*Index*} buffer. The -default for this flag can be set with the variable -@code{reftex-index-include-context}. - -@item @} -Restrict the index to a single document section. The corresponding -section number will be displayed in the @code{R<>} indicator in the -mode line and in the header of the @file{*Index*} buffer. - -@item @{ -Widen the index to contain all entries of the document. - -@item < -When the index is currently restricted, move the restriction to the -previous section. - -@item > -When the index is currently restricted, move the restriction to the -next section. - -@tablesubheading{Updating the buffer} -@item g -Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the -document. However, it sorts the entries again, so that edited entries -will move to the correct position. - -@item r -@vindex reftex-enable-partial-scans -Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When -@code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this -location is defined in, not the entire document. - -@item C-u r -Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} -buffer. - -@item s -Switch to a different index (for documents with multiple -indices). -@end table - - -@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support -@section Builtin Index Macros -@cindex Builtin index macros -@cindex Index macros, builtin -@vindex reftex-index-macros -@cindex @code{multind}, LaTeX package -@cindex @code{index}, LaTeX package -@cindex LaTeX packages, @code{multind} -@cindex LaTeX packages, @code{index} - -@b{Ref@TeX{}} by default recognizes the @code{\index} and -@code{\glossary} macros which are defined in the LaTeX core. It has -also builtin support for the re-implementations of @code{\index} -in the @file{multind} and @file{index} packages. However, since -the different definitions of the @code{\index} macro are incompatible, -you will have to explicitly specify the index style used. -@xref{Creating Index Entries}, for information on how to do that. - -@node Defining Index Macros, , Builtin Index Macros, Index Support -@section Defining Index Macros -@cindex Defining Index Macros -@cindex Index macros, defining -@vindex reftex-index-macros - -When writing a document with an index you will probably define -additional macros which make entries into the index. -Let's look at an example. - -@example -\newcommand@{\ix@}[1]@{#1\index@{#1@}@} -\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} -\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} -@end example - -The first macro @code{\ix} typesets its argument in the text and places -it into the index. The second macro @code{\nindex} typesets its -argument in the text and places it into a separate index with the tag -@samp{name}@footnote{We are using the syntax of the @file{index} package -here.}. The last macro also places its argument into the index, but as -subitems under the main index entry @samp{Astronomical Objects}. Here -is how to make @b{Ref@TeX{}} recognize and correctly interpret these -macros, first with Emacs Lisp. - -@lisp -(setq reftex-index-macros - '(("\\ix@{*@}" "idx" ?x "" nil nil) - ("\\nindex@{*@}" "name" ?n "" nil nil) - ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) -@end lisp - -Note that the index tag is @samp{idx} for the main index, and -@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved -for the default index and for the glossary. - -The character arguments @code{?x}, @code{?n}, and @code{?o} are for -quick identification of these macros when @b{Ref@TeX{}} inserts new -index entries with @code{reftex-index}. These codes need to be -unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the -@code{\index}, @code{\index*}, and @code{\glossary} macros, -respectively. - -The following string is empty unless your macro adds a superordinate -entry to the index key - this is the case for the @code{\astobj} macro. - -The next entry can be a hook function to exclude certain matches, it -almost always can be @code{nil}. - -The final element in the list indicates if the text being indexed needs -to be repeated outside the macro. For the normal index macros, this -should be @code{t}. Only if the macro typesets the entry in the text -(like @code{\ix} and @code{\nindex} in the example do), this should be -@code{nil}. - -To do the same thing with customize, you need to fill in the templates -like this: - -@example -Repeat: -[INS] [DEL] List: - Macro with args: \ix@{*@} - Index Tag : [Value Menu] String: idx - Access Key : x - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \nindex@{*@} - Index Tag : [Value Menu] String: name - Access Key : n - Key Prefix : - Exclusion hook : nil - Repeat Outside : [Toggle] off (nil) -[INS] [DEL] List: - Macro with args: \astobj@{*@} - Index Tag : [Value Menu] String: idx - Access Key : o - Key Prefix : Astronomical Objects! - Exclusion hook : nil - Repeat Outside : [Toggle] on (non-nil) -[INS] -@end example - -With the macro @code{\ix} defined, you may want to change the default -macro used for indexing a text phrase (@pxref{Creating Index Entries}). -This would be done like this - -@lisp -(setq reftex-index-default-macro '(?x "idx")) -@end lisp - -which specifies that the macro identified with the character @code{?x} (the -@code{\ix} macro) should be used for indexing phrases and words already -in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). -The index tag is "idx". - -@node Viewing Cross-References, RefTeXs Menu, Index Support, Top -@chapter Viewing Cross--References -@findex reftex-view-crossref -@findex reftex-mouse-view-crossref -@kindex C-c & -@kindex S-mouse-2 - -@b{Ref@TeX{}} can display cross--referencing information. This means, -if two document locations are linked, @b{Ref@TeX{}} can display the -matching location(s) in another window. The @code{\label} and @code{\ref} -macros are one way of establishing such a link. Also, a @code{\cite} -macro is linked to the corresponding @code{\bibitem} macro or a BibTeX -database entry. - -The feature is invoked by pressing @kbd{C-c &} -(@code{reftex-view-crossref}) while point is on the @var{key} argument -of a macro involved in cross--referencing. You can also click with -@kbd{S-mouse-2} on the macro argument. Here is what will happen for -individual classes of macros: - -@table @asis - -@item @code{\ref} -@cindex @code{\ref} -Display the corresponding label definition. All usual -variants@footnote{all macros that start with @samp{ref} or end with -@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for -cross--reference display. This works also for labels defined in an -external document when the current document refers to them through the -@code{xr} interface (@pxref{xr (LaTeX package)}). - -@item @code{\label} -@cindex @code{\label} -@vindex reftex-label-alist -Display a document location which references this label. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. Not only the @code{\label} macro but also other macros -with label arguments (as configured with @code{reftex-label-alist}) are -active for cross--reference display. - -@item @code{\cite} -@cindex @code{\cite} -Display the corresponding BibTeX database entry or @code{\bibitem}. -All usual variants@footnote{all macros that either start or end with -@samp{cite}} of the @code{\cite} macro are active for cross--reference -display. - -@item @code{\bibitem} -@cindex @code{\bibitem} -Display a document location which cites this article. Pressing -@kbd{C-c &} several times moves through the entire document and finds -all locations. - -@item BibTeX -@cindex BibTeX buffer, viewing cite locations from -@cindex Viewing cite locations from BibTeX buffer -@kbd{C-c &} is also active in BibTeX buffers. All locations in a -document where the database entry at point is cited will be displayed. -On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to -the document you want to search. Subsequent calls will use the same -document, until you break this link with a prefix argument to @kbd{C-c -&}. - -@item @code{\index} -@cindex @code{\index} -Display other locations in the document which are marked by an index -macro with the same key argument. Along with the standard @code{\index} -and @code{\glossary} macros, all macros configured in -@code{reftex-index-macros} will be recognized. -@end table - -@vindex reftex-view-crossref-extra -While the display of cross referencing information for the above -mentioned macros is hard--coded, you can configure additional relations -in the variable @code{reftex-view-crossref-extra}. - -@iftex -@chapter All the Rest -@end iftex - -@node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top -@section @b{Ref@TeX{}}'s Menu -@cindex RefTeXs Menu -@cindex Menu, in the menu bar - -@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems -which support this. From this menu you can access all of -@b{Ref@TeX{}}'s commands and a few of its options. There is also a -@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s -entire set of options. - -@node Key Bindings, Faces, RefTeXs Menu, Top -@section Default Key Bindings -@cindex Key Bindings, summary - -Here is a summary of the available key bindings. - -@kindex C-c = -@kindex C-c - -@kindex C-c ( -@kindex C-c ) -@kindex C-c [ -@kindex C-c & -@kindex S-mouse-2 -@kindex C-c / -@kindex C-c \ -@kindex C-c | -@kindex C-c < -@kindex C-c > -@example -@kbd{C-c =} @code{reftex-toc} -@kbd{C-c -} @code{reftex-toc-recenter} -@kbd{C-c (} @code{reftex-label} -@kbd{C-c )} @code{reftex-reference} -@kbd{C-c [} @code{reftex-citation} -@kbd{C-c &} @code{reftex-view-crossref} -@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} -@kbd{C-c /} @code{reftex-index-selection-or-word} -@kbd{C-c \} @code{reftex-index-phrase-selection-or-word} -@kbd{C-c |} @code{reftex-index-visit-phrases-buffer} -@kbd{C-c <} @code{reftex-index} -@kbd{C-c >} @code{reftex-display-index} -@end example - -Note that the @kbd{S-mouse-2} binding is only provided if this key is -not already used by some other package. @b{Ref@TeX{}} will not override an -existing binding to @kbd{S-mouse-2}. - -Personally, I also bind some functions in the users @kbd{C-c} map for -easier access. - -@c FIXME: Do we need bindings for the Index macros here as well? -@c C-c i C-c I or so???? -@c How about key bindings for reftex-reset-mode and reftex-parse-document? -@kindex C-c t -@kindex C-c l -@kindex C-c r -@kindex C-c c -@kindex C-c v -@kindex C-c s -@kindex C-c g -@example -@kbd{C-c t} @code{reftex-toc} -@kbd{C-c l} @code{reftex-label} -@kbd{C-c r} @code{reftex-reference} -@kbd{C-c c} @code{reftex-citation} -@kbd{C-c v} @code{reftex-view-crossref} -@kbd{C-c s} @code{reftex-search-document} -@kbd{C-c g} @code{reftex-grep-document} -@end example - -@noindent These keys are reserved for the user, so I cannot bind them by -default. If you want to have these key bindings available, set in your -@file{.emacs} file: - -@vindex reftex-extra-bindings -@lisp -(setq reftex-extra-bindings t) -@end lisp - -@vindex reftex-load-hook -Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook -@code{reftex-load-hook}. For information on the keymaps -which should be used to add keys, see @ref{Keymaps and Hooks}. - -@node Faces, AUCTeX, Key Bindings, Top -@section Faces -@cindex Faces - -@b{Ref@TeX{}} uses faces when available to structure the selection and -table of contents buffers. It does not create its own faces, but uses -the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will -use faces only when @code{font-lock} is loaded. This seems to be -reasonable because people who like faces will very likely have it -loaded. If you wish to turn off fontification or change the involved -faces, see @ref{Options (Fontification)}. - -@node Multifile Documents, Language Support, AUCTeX, Top -@section Multifile Documents -@cindex Multifile documents -@cindex Documents, spread over files - -The following is relevant when working with documents spread over many -files: - -@itemize @bullet -@item -@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of -several (multifile) documents at the same time without conflicts. -@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and -@code{query-replace} on all files which are part of a multifile -document. - -@item -@vindex tex-main-file -@vindex TeX-master -All files belonging to a multifile document should define a File -Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the -standard Emacs LaTeX mode) containing the name of the master file. For -example, to set the file variable @code{TeX-master}, include something -like the following at the end of each TeX file: - -@example -%%% Local Variables: *** -%%% mode:latex *** -%%% TeX-master: "thesis.tex" *** -%%% End: *** -@end example - -AUCTeX with the setting - -@lisp -(setq-default TeX-master nil) -@end lisp - -will actually ask you for each new file about the master file and insert -this comment automatically. For more details see the documentation of -the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the -documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, -The GNU Emacs Manual}) and the Emacs documentation on File Variables -(@pxref{File Variables,,,emacs, The GNU Emacs Manual}). - -@item -The context of a label definition must be found in the same file as the -label itself in order to be processed correctly by @b{Ref@TeX{}}. The only -exception is that section labels referring to a section statement -outside the current file can still use that section title as -context. -@end itemize - -@node Language Support, Finding Files, Multifile Documents, Top -@section Language Support -@cindex Language support - -Some parts of @b{Ref@TeX{}} are language dependent. The default -settings work well for English. If you are writing in a different -language, the following hints may be useful: - -@itemize @bullet -@item -@vindex reftex-derive-label-parameters -@vindex reftex-abbrev-parameters -The mechanism to derive a label from context includes the abbreviation -of words and omission of unimportant words. These mechanisms may have -to be changed for other languages. See the variables -@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. - -@item -@vindex reftex-translate-to-ascii-function -@vindex reftex-label-illegal-re -Also, when a label is derived from context, @b{Ref@TeX{}} clears the -context string from non-ASCII characters in order to make a valid label. -If there should ever be a version of @TeX{} which allows extended -characters @emph{in labels}, then we will have to look at the -variables @code{reftex-translate-to-ascii-function} and -@code{reftex-label-illegal-re}. - -@item -When a label is referenced, @b{Ref@TeX{}} looks at the word before point -to guess which label type is required. These @emph{magic words} are -different in every language. For an example of how to add magic words, -see @ref{Adding Magic Words}. - -@vindex reftex-multiref-punctuation -@vindex reftex-cite-punctuation -@item -@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and -for the author list in citations. Some of this may be language -dependent. See the variables @code{reftex-multiref-punctuation} and -@code{reftex-cite-punctuation}. -@end itemize - -@node Finding Files, Optimizations, Language Support, Top -@section Finding Files -@cindex Finding files - -In order to find files included in a document via @code{\input} or -@code{\include}, @b{Ref@TeX{}} searches all directories specified in the -environment variable @code{TEXINPUTS}. Similarly, it will search the -path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for -BibTeX database files. - -When searching, @b{Ref@TeX{}} will also expand recursive path -definitions (directories ending in @samp{//} or @samp{!!}). But it will -only search and expand directories @emph{explicitly} given in these -variables. This may cause problems under the following circumstances: - -@itemize @bullet -@item -Most TeX system have a default search path for both TeX files and BibTeX -files which is defined in some setup file. Usually this default path is -for system files which @b{Ref@TeX{}} does not need to see. But if your -document needs TeX files or BibTeX database files in a directory only -given in the default search path, @b{Ref@TeX{}} will fail to find them. -@item -Some TeX systems do not use environment variables at all in order to -specify the search path. Both default and user search path are then -defined in setup files. -@end itemize - -@noindent -There are three ways to solve this problem: - -@itemize @bullet -@item -Specify all relevant directories explicitly in the environment -variables. If for some reason you don't want to mess with the default -variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own -variables and configure @b{Ref@TeX{}} to use them instead: - -@lisp -(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) -(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) -@end lisp - -@item -Specify the full search path directly in @b{Ref@TeX{}}'s variables. - -@lisp -(setq reftex-texpath-environment-variables - '("./inp:/home/cd/tex//:/usr/local/tex//")) -(setq reftex-bibpath-environment-variables - '("/home/cd/tex/lit/")) -@end lisp - -@item -Some TeX systems provide stand--alone programs to do the file search just -like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the -@code{kpathsearch} library which provides the command @code{kpsewhich} -to search for files. @b{Ref@TeX{}} can be configured to use this -program. Note that the exact syntax of the @code{kpsewhich} -command depends upon the version of that program. - -@lisp -(setq reftex-use-external-file-finders t) -(setq reftex-external-file-finders - '(("tex" . "kpsewhich -format=.tex %f") - ("bib" . "kpsewhich -format=.bib %f"))) -@end lisp -@end itemize - -@cindex Noweb files -@vindex reftex-file-extensions -@vindex TeX-file-extensions -Some people like to use RefTeX with noweb files, which usually have the -extension @file{.nw}. In order to deal with such files, the new -extension must be added to the list of valid extensions in the variable -@code{reftex-file-extensions}. When working with AUCTeX as major mode, -the new extension must also be known to AUCTeX via the variable -@code{TeX-file-extension}. For example: - -@lisp -(setq reftex-file-extensions - '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) -(setq TeX-file-extensions - '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) -@end lisp - -@node Optimizations, Problems and Work-Arounds, Finding Files, Top -@section Optimizations -@cindex Optimizations - -@b{Note added 2002. Computers have gotten a lot faster, so most of the -optimizations discussed below will not be necessary on new machines. I -am leaving this stuff in the manual for people who want to write thick -books, where some of it still might be useful.} - -Implementing the principle of least surprises, the default settings of -@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, -when using @b{Ref@TeX{}} for a large project and/or on a small computer, -there are ways to improve speed or memory usage. - -@itemize @bullet -@item -@b{Removing Lookup Buffers}@* -@cindex Removing lookup buffers -@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX -database files for lookup purposes. These buffers are kept, so that -subsequent use of the same files is fast. If you can't afford keeping -these buffers around, and if you can live with a speed penalty, try - -@vindex reftex-keep-temporary-buffers -@lisp -(setq reftex-keep-temporary-buffers nil) -@end lisp - -@item -@b{Partial Document Scans}@* -@cindex Partial documents scans -@cindex Document scanning, partial -A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} -(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), -@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c -=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates -re-parsing of the entire document in order to update the parsing -information. For a large document this can be unnecessary, in -particular if only one file has changed. @b{Ref@TeX{}} can be configured -to do partial scans instead of full ones. @kbd{C-u} re-parsing then -does apply only to the current buffer and files included from it. -Likewise, the @kbd{r} key in both the label selection buffer and the -table-of-contents buffer will only prompt scanning of the file in which -the label or section macro near the cursor was defined. Re-parsing of -the entire document is still available by using @kbd{C-u C-u} as a -prefix, or the capital @kbd{R} key in the menus. To use this feature, -try - -@vindex reftex-enable-partial-scans -@lisp -(setq reftex-enable-partial-scans t) -@end lisp - -@item -@b{Saving Parser Information}@* -@cindex Saving parser information -@cindex Parse information, saving to a file -@vindex reftex-parse-file-extension -Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full -scan, when you start working with a document. To avoid this, parsing -information can be stored in a file. The file @file{MASTER.rel} is used -for storing information about a document with master file -@file{MASTER.tex}. It is written automatically when you kill a buffer -in @code{reftex-mode} or when you exit Emacs. The information is -restored when you begin working with a document in a new editing -session. To use this feature, put into @file{.emacs}: - -@vindex reftex-save-parse-info -@lisp -(setq reftex-save-parse-info t) -@end lisp - -@item -@b{Identifying label types by prefix}@* -@cindex Parse information, saving to a file -@vindex reftex-trust-label-prefix -@b{Ref@TeX{}} normally parses around each label to check in which -environment this label is located, in order to assign a label type to -the label. If your document contains thousands of labels, document -parsing will take considerable time. If you have been using label prefixes -like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the -label type directly from the prefix, without additional parsing. This -will be faster and also allow labels to end up in the correct category -if for some reason it is not possible to derive the correct type from -context. For example, to enable this feature for footnote and -equation labels, use - -@lisp -(setq reftex-trust-label-prefix '("fn:" "eq:")) -@end lisp - -@item -@b{Automatic Document Scans}@* -@cindex Automatic document scans -@cindex Document scanning, automatic -At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the -document. If this gets into your way, it can be turned off with - -@vindex reftex-allow-automatic-rescan -@lisp -(setq reftex-allow-automatic-rescan nil) -@end lisp - -@b{Ref@TeX{}} will then occasionally annotate new labels in the selection -buffer, saying that their position in the label list in uncertain. A -manual document scan will fix this. - -@item -@b{Multiple Selection Buffers}@* -@cindex Multiple selection buffers -@cindex Selection buffers, multiple -Normally, the selection buffer @file{*RefTeX Select*} is re-created for -every selection process. In documents with very many labels this can -take several seconds. @b{Ref@TeX{}} provides an option to create a -separate selection buffer for each label type and to keep this buffer -from one selection to the next. These buffers are updated automatically -only when a new label has been added in the buffers category with -@code{reftex-label}. Updating the buffer takes as long as recreating it -- so the time saving is limited to cases where no new labels of that -category have been added. To turn on this feature, use - -@vindex reftex-use-multiple-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t) -@end lisp - -@noindent -@cindex Selection buffers, updating -You can also inhibit the automatic updating entirely. Then the -selection buffer will always pop up very fast, but may not contain the -most recently defined labels. You can always update the buffer by hand, -with the @kbd{g} key. To get this behavior, use instead - -@vindex reftex-auto-update-selection-buffers -@lisp -(setq reftex-use-multiple-selection-buffers t - reftex-auto-update-selection-buffers nil) -@end lisp -@end itemize - -@need 2000 -@noindent -@b{As a summary}, here are the settings I recommend for heavy use of -@b{Ref@TeX{}} with large documents: - -@lisp -@group -(setq reftex-enable-partial-scans t - reftex-save-parse-info t - reftex-use-multiple-selection-buffers t) -@end group -@end lisp - -@node AUCTeX, Multifile Documents, Faces, Top -@section AUC@TeX{} -@cindex @code{AUCTeX}, Emacs package -@cindex Emacs packages, @code{AUCTeX} - -AUCTeX is without doubt the best major mode for editing TeX and LaTeX -files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). -If AUCTeX is not part of your Emacs distribution, you can get -it@footnote{XEmacs 21.x users may want to install the corresponding -XEmacs package.} by ftp from the @value{AUCTEXSITE}. - -@menu -* AUCTeX-RefTeX Interface:: How both packages work together -* Style Files:: AUCTeX's style files can support RefTeX -* Bib-Cite:: Hypertext reading of a document -@end menu - -@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX -@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface - -@b{Ref@TeX{}} contains code to interface with AUCTeX. When this -interface is turned on, both packages will interact closely. Instead of -using @b{Ref@TeX{}}'s commands directly, you can then also use them -indirectly as part of the AUCTeX -environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be -needed for all of this to work. Parts of it work also with earlier -versions.}. The interface is turned on with - -@lisp -(setq reftex-plug-into-AUCTeX t) -@end lisp - -If you need finer control about which parts of the interface are used -and which not, read the docstring of the variable -@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x -customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. - -The following list describes the individual parts of the interface. - -@itemize @bullet -@item -@findex reftex-label -@vindex LaTeX-label-function, @r{AUCTeX} -@kindex C-c C-e -@kindex C-c C-s -@findex LaTeX-section, @r{AUCTeX} -@findex TeX-insert-macro, @r{AUCTeX} -@b{AUCTeX calls @code{reftex-label} to insert labels}@* -When a new section is created with @kbd{C-c C-s}, or a new environment -is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to -go with it. With the interface, @code{reftex-label} is called instead. -For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and -@b{Ref@TeX{}} will insert - -@example -\begin@{equation@} -\label@{eq:1@} - -\end@{equation@} -@end example - -@noindent -without further prompts. - -Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} -will offer its default label which is derived from the section title. - -@item -@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* -When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not -have to rescan the buffer in order to see it. - -@item -@findex reftex-arg-label -@findex TeX-arg-label, @r{AUCTeX function} -@findex reftex-arg-ref -@findex TeX-arg-ref, @r{AUCTeX function} -@findex reftex-arg-cite -@findex TeX-arg-cite, @r{AUCTeX function} -@findex reftex-arg-index -@findex TeX-arg-index, @r{AUCTeX function} -@findex TeX-insert-macro, @r{AUCTeX function} -@kindex C-c @key{RET} -@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro -interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for -macro arguments. Internally, it uses the functions -@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to -prompt for arguments which are labels, citation keys and index entries. -The interface takes over these functions@footnote{@code{fset} is used to -do this, which is not reversible. However, @b{Ref@TeX{}} implements the -old functionality when you later decide to turn off the interface.} and -supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For -example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} -will supply its label selection process (@pxref{Referencing -Labels}). - -@item -@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* -@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. -@end itemize - -@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX -@subsection Style Files -@cindex Style files, AUCTeX -@findex TeX-add-style-hook, @r{AUCTeX} -Style files are Emacs Lisp files which are evaluated by AUCTeX in -association with the @code{\documentclass} and @code{\usepackage} -commands of a document (@pxref{Style Files,,,auctex}). Support for -@b{Ref@TeX{}} in such a style file is useful when the LaTeX style -defines macros or environments connected with labels, citations, or the -index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el}) -distributed with AUCTeX already support @b{Ref@TeX{}} in this -way. - -Before calling a @b{Ref@TeX{}} function, the style hook should always -test for the availability of the function, so that the style file will -also work for people who do not use @b{Ref@TeX{}}. - -Additions made with style files in the way described below remain local -to the current document. For example, if one package uses AMSTeX, the -style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but -this will not affect other documents. - -@findex reftex-add-label-environments -@findex reftex-add-to-label-alist -A style hook may contain calls to -@code{reftex-add-label-environments}@footnote{This used to be the -function @code{reftex-add-to-label-alist} which is still available as an -alias for compatibility.} which defines additions to -@code{reftex-label-alist}. The argument taken by this function must have -the same format as @code{reftex-label-alist}. The @file{amsmath.el} -style file of AUCTeX for example contains the following: - -@lisp -@group -(TeX-add-style-hook "amsmath" - (lambda () - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments '(AMSTeX))))) -@end group -@end lisp - -@noindent -@findex LaTeX-add-environments, @r{AUCTeX} -while a package @code{myprop} defining a @code{proposition} environment -with @code{\newtheorem} might use - -@lisp -@group -(TeX-add-style-hook "myprop" - (lambda () - (LaTeX-add-environments '("proposition" LaTeX-env-label)) - (if (fboundp 'reftex-add-label-environments) - (reftex-add-label-environments - '(("proposition" ?p "prop:" "~\\ref@{%s@}" t - ("Proposition" "Prop.") -3)))))) -@end group -@end lisp - -@findex reftex-set-cite-format -Similarly, a style hook may contain a call to -@code{reftex-set-cite-format} to set the citation format. The style -file @file{natbib.el} for the Natbib citation style does switch -@b{Ref@TeX{}}'s citation format like this: - -@lisp -(TeX-add-style-hook "natbib" - (lambda () - (if (fboundp 'reftex-set-cite-format) - (reftex-set-cite-format 'natbib)))) -@end lisp - -@findex reftex-add-index-macros -The hook may contain a call to @code{reftex-add-index-macros} to -define additional @code{\index}-like macros. The argument must have -the same format as @code{reftex-index-macros}. It may be a symbol, to -trigger support for one of the builtin index packages. For example, -the style @file{multind.el} contains - -@lisp -(TeX-add-style-hook "multind" - (lambda () - (and (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros '(multind))))) -@end lisp - -If you have your own package @file{myindex} which defines the -following macros to be used with the LaTeX @file{index.sty} file -@example -\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} -\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} -@end example - -you could write this in the style file @file{myindex.el}: - -@lisp -(TeX-add-style-hook "myindex" - (lambda () - (TeX-add-symbols - '("molec" TeX-arg-index) - '("aindex" TeX-arg-index)) - (if (fboundp 'reftex-add-index-macros) - (reftex-add-index-macros - '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) - ("aindex@{*@}" "author" ?a "" nil nil)))))) -@end lisp - -@findex reftex-add-section-levels -Finally the hook may contain a call to @code{reftex-add-section-levels} -to define additional section statements. For example, the FoilTeX class -has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here -is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: - -@lisp -(TeX-add-style-hook "foils" - (lambda () - (if (fboundp 'reftex-add-section-levels) - (reftex-add-section-levels '(("foilhead" . 3) - ("rotatefoilhead" . 3)))))) -@end lisp - -@node Bib-Cite, , Style Files, AUCTeX -@subsection Bib-Cite -@cindex @code{bib-cite}, Emacs package -@cindex Emacs packages, @code{bib-cite} - -Once you have written a document with labels, references and citations, -it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has -support for that: @code{reftex-view-crossref} (bound to @kbd{C-c -&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and -@code{reftex-search-document}. A somewhat fancier interface with mouse -highlighting is provided (among other things) by Peter S. Galbraith's -@file{bib-cite.el}. There is some overlap in the functionalities of -Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with -AUCTeX. - -Bib-cite version 3.06 and later can be configured so that bib-cite's -mouse functions use @b{Ref@TeX{}} for displaying references and citations. -This can be useful in particular when working with the LaTeX @code{xr} -package or with an explicit @code{thebibliography} environment (rather -than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To -make use of this feature, try - -@vindex bib-cite-use-reftex-view-crossref -@lisp -(setq bib-cite-use-reftex-view-crossref t) -@end lisp - -@page -@node Problems and Work-Arounds, Imprint, Optimizations, Top -@section Problems and Work-arounds -@cindex Problems and work-arounds - -@itemize @bullet -@item -@b{LaTeX commands}@* -@cindex LaTeX commands, not found -@code{\input}, @code{\include}, and @code{\section} (etc.) statements -have to be first on a line (except for white space). - -@item -@b{Commented regions}@* -@cindex Labels, commented out -@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to -make duplicates of such labels. This is considered to be a feature. - -@item -@b{Wrong section numbers}@* -@cindex Section numbers, wrong -@vindex reftex-enable-partial-scans -When using partial scans (@code{reftex-enable-partial-scans}), the section -numbers in the table of contents may eventually become wrong. A full -scan will fix this. - -@item -@b{Local settings}@* -@cindex Settings, local -@findex reftex-add-label-environments -@findex reftex-set-cite-format -@findex reftex-add-section-levels -The label environment definitions in @code{reftex-label-alist} are -global and apply to all documents. If you need to make definitions -local to a document, because they would interfere with settings in other -documents, you should use AUCTeX and set up style files with calls to -@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, -@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. -Settings made with these functions remain local to the current -document. @xref{AUCTeX}. - -@item -@b{Funny display in selection buffer}@* -@cindex @code{x-symbol}, Emacs package -@cindex Emacs packages, @code{x-symbol} -@cindex @code{isotex}, Emacs package -@cindex Emacs packages, @code{isotex} -@cindex @code{iso-cvt}, Emacs package -@cindex Emacs packages, @code{iso-cvt} -When using packages which make the buffer representation of a file -different from its disk representation (e.g. x-symbol, isotex, -iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes -reflects the disk state of a file. This happens only in @emph{unvisited} -parts of a multifile document, because @b{Ref@TeX{}} visits these files -literally for speed reasons. Then both short context and section -headings may look different from what you usually see on your screen. -In rare cases @code{reftex-toc} may have problems to jump to an affected -section heading. There are three possible ways to deal with -this: -@itemize @minus -@item -@vindex reftex-keep-temporary-buffers -@code{(setq reftex-keep-temporary-buffers t)}@* -This implies that @b{Ref@TeX{}} will load all parts of a multifile -document into Emacs (i.e. there won't be any temporary buffers). -@item -@vindex reftex-initialize-temporary-buffers -@code{(setq reftex-initialize-temporary-buffers t)}@* -This means full initialization of temporary buffers. It involves -a penalty when the same unvisited file is used for lookup often. -@item -Set @code{reftex-initialize-temporary-buffers} to a list of hook -functions doing a minimal initialization. -@end itemize -@vindex reftex-refontify-context -See also the variable @code{reftex-refontify-context}. - -@item -@b{Labels as arguments to \begin}@* -@cindex @code{pf}, LaTeX package -@cindex LaTeX packages, @code{pf} -Some packages use an additional argument to a @code{\begin} macro -to specify a label. E.g. Lamport's @file{pf.sty} uses both -@example -\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} - @var{claim} - \end@{step+@} -@end example - -@noindent -We need to trick @b{Ref@TeX{}} into swallowing this: - -@lisp -@group -;; Configuration for Lamport's pf.sty -(setq reftex-label-alist - '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) - ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) -@end group -@end lisp - -@noindent -The first line is just a normal configuration for a macro. For the -@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the -@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} -argument (which really is a second argument to the macro @code{\begin}) -as a label of type @code{?p}. Argument count for this macro starts only -after the @samp{@{step+@}}, also when specifying how to get -context. - -@item -@b{Idle timers in XEmacs}@* -@cindex Idle timer restart -@vindex reftex-use-itimer-in-xemacs -In XEmacs, idle timer restart does not work reliably after fast -keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command -hook to start the timer used for automatic crossref information. When -this bug gets fixed, a real idle timer can be requested with -@lisp -(setq reftex-use-itimer-in-xemacs t) -@end lisp - -@item -@b{Viper mode}@* -@cindex Viper mode -@cindex Key bindings, problems with Viper mode -@findex viper-harness-minor-mode -With @i{Viper} mode prior to Vipers version 3.01, you need to protect -@b{Ref@TeX{}}'s keymaps with - -@lisp -(viper-harness-minor-mode "reftex") -@end lisp - -@end itemize - -@page -@node Imprint, Commands, Problems and Work-Arounds, Top -@section Imprint -@cindex Imprint -@cindex Maintainer -@cindex Acknowledgments -@cindex Thanks -@cindex Bug reports -@cindex @code{http}, @b{Ref@TeX{}} home page -@cindex @code{ftp}, @b{Ref@TeX{}} site - -Ref@TeX{} was written by @i{Carsten Dominik} -@email{dominik@@science.uva.nl}, with contributions by @i{Stephen -Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see -the @value{MAINTAINERSITE} for detailed information. - -If you have questions about Ref@TeX{}, you can send email to the -@value{SUPPORTADDRESS}. If you want to contribute code or ideas, write -to the @value{DEVELADDRESS}. And in the rare case of finding a bug, -please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a -bug report with useful information about your setup. Remember to add -essential information like a recipe for reproducing the bug, what you -expected to happen, and what actually happened. Send the bug report to -the @value{BUGADDRESS}. - -There are also several Usenet groups which have competent readers who -might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, -@code{comp.emacs.xemacs}, and @code{comp.text.tex}. - -@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. -It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs -21.x users want to install the corresponding plugin package which is -available from the @value{XEMACSFTP}. See the XEmacs 21.x -documentation on package installation for details. - -Users of earlier Emacs distributions (including Emacs 19) can get a -@b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that -the Emacs 19 version supports many but not all features described in -this manual. - -Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped -developing it with their reports. In particular thanks to @i{Ralf -Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, -Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai -Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan -Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, -Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan -Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, -Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan -Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}. - - -The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} -@file{bib-cite.el}. - -Finally thanks to @i{Uwe Bolick} who first got me interested in -supporting LaTeX labels and references with an editor (which was -MicroEmacs at the time). - -@node Commands, Options, Imprint, Top -@chapter Commands -@cindex Commands, list of - -Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from -LaTeX files. Command which are executed from the special buffers are -not described here. All commands are available from the @code{Ref} -menu. See @xref{Key Bindings}. - -@deffn Command reftex-toc -Show the table of contents for the current document. When called with -one ore two @kbd{C-u} prefixes, rescan the document first. -@end deffn - -@deffn Command reftex-label -Insert a unique label. With one or two @kbd{C-u} prefixes, enforce -document rescan first. -@end deffn - -@deffn Command reftex-reference -Start a selection process to select a label, and insert a reference to -it. With one or two @kbd{C-u} prefixes, enforce document rescan first. -@end deffn - -@deffn Command reftex-citation -Make a citation using BibTeX database files. After prompting for a regular -expression, scans the buffers with BibTeX entries (taken from the -@code{\bibliography} command or a @code{thebibliography} environment) -and offers the matching entries for selection. The selected entry is -formatted according to @code{reftex-cite-format} and inserted into the -buffer. @* -When called with a @kbd{C-u} prefix, prompt for optional arguments in -cite macros. When called with a numeric prefix, make that many citations. -When called with point inside the braces of a @code{\cite} command, it -will add another key, ignoring the value of -@code{reftex-cite-format}. @* -The regular expression uses an expanded syntax: @samp{&&} is interpreted -as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain -both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion -on knows citation keys is possible. @samp{=} is a good regular -expression to match all entries in all files. -@end deffn - -@deffn Command reftex-index -Query for an index macro and insert it along with its arguments. The -index macros available are those defined in @code{reftex-index-macro} or -by a call to @code{reftex-add-index-macros}, typically from an AUCTeX -style file. @b{Ref@TeX{}} provides completion for the index tag and the -index key, and will prompt for other arguments. -@end deffn - -@deffn Command reftex-index-selection-or-word -Put current selection or the word near point into the default index -macro. This uses the information in @code{reftex-index-default-macro} -to make an index entry. The phrase indexed is the current selection or -the word near point. When called with one @kbd{C-u} prefix, let the -user have a chance to edit the index entry. When called with 2 -@kbd{C-u} as prefix, also ask for the index macro and other stuff. When -called inside TeX math mode as determined by the @file{texmathp.el} -library which is part of AUCTeX, the string is first processed with the -@code{reftex-index-math-format}, which see. -@end deffn - -@deffn Command reftex-index-phrase-selection-or-word -Add current selection or the word at point to the phrases buffer. -When you are in transient-mark-mode and the region is active, the -selection will be used - otherwise the word at point. -You get a chance to edit the entry in the phrases buffer - to save the -buffer and return to the LaTeX document, finish with @kbd{C-c C-c}. -@end deffn - -@deffn Command reftex-index-visit-phrases-buffer -Switch to the phrases buffer, initialize if empty. -@end deffn - -@deffn Command reftex-index-phrases-apply-to-region -Index all index phrases in the current region. -This works exactly like global indexing from the index phrases buffer, -but operation is restricted to the current region. -@end deffn - -@deffn Command reftex-display-index -Display a buffer with an index compiled from the current document. -When the document has multiple indices, first prompts for the correct one. -When index support is turned off, offer to turn it on. -With one or two @kbd{C-u} prefixes, rescan document first. -With prefix 2, restrict index to current document section. -With prefix 3, restrict index to active region. -@end deffn - -@deffn Command reftex-view-crossref -View cross reference of macro at point. Point must be on the @var{key} -argument. Works with the macros @code{\label}, @code{\ref}, -@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of -these. Where it makes sense, subsequent calls show additional -locations. See also the variable @code{reftex-view-crossref-extra} and -the command @code{reftex-view-crossref-from-bibtex}. With one or two -@kbd{C-u} prefixes, enforce rescanning of the document. With argument -2, select the window showing the cross reference. -@end deffn - -@deffn Command reftex-view-crossref-from-bibtex -View location in a LaTeX document which cites the BibTeX entry at point. -Since BibTeX files can be used by many LaTeX documents, this function -prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this -link to a document, call the function with a prefix arg. Calling -this function several times find successive citation locations. -@end deffn - -@deffn Command reftex-create-tags-file -Create TAGS file by running @code{etags} on the current document. The -TAGS file is also immediately visited with -@code{visit-tags-table}. -@end deffn - -@deffn Command reftex-grep-document -Run grep query through all files related to this document. -With prefix arg, force to rescan document. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-search-document -Regexp search through all files of the current document. -Starts always in the master file. Stops when a match is found. -No active TAGS table is required. -@end deffn - -@deffn Command reftex-query-replace-document -Run a query-replace-regexp of @var{from} with @var{to} over the entire -document. With prefix arg, replace only word-delimited matches. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-isearch-minor-mode -Toggle a minor mode which enables incremental search to work globally -on the entire multifile document. Files will be searched in th -sequence they appear in the document. -@end deffn - -@deffn Command reftex-goto-label -Prompt for a label (with completion) and jump to the location of this -label. Optional prefix argument @var{other-window} goes to the label in -another window. -@end deffn - - -@deffn Command reftex-change-label -Query replace @var{from} with @var{to} in all @code{\label} and -@code{\ref} commands. Works on the entire multifile document. No -active TAGS table is required. -@end deffn - -@deffn Command reftex-renumber-simple-labels -Renumber all simple labels in the document to make them sequentially. -Simple labels are the ones created by RefTeX, consisting only of the -prefix and a number. After the command completes, all these labels will -have sequential numbers throughout the document. Any references to the -labels will be changed as well. For this, @b{Ref@TeX{}} looks at the -arguments of any macros which either start or end with the string -@samp{ref}. This command should be used with care, in particular in -multifile documents. You should not use it if another document refers -to this one with the @code{xr} package. -@end deffn - -@deffn Command reftex-find-duplicate-labels -Produce a list of all duplicate labels in the document. -@end deffn - -@deffn Command reftex-create-bibtex-file -Create a new BibTeX database file with all entries referenced in document. -The command prompts for a filename and writes the collected entries to -that file. Only entries referenced in the current document with -any @code{\cite}-like macros are used. -The sequence in the new file is the same as it was in the old database. -@end deffn - -@deffn Command reftex-customize -Run the customize browser on the @b{Ref@TeX{}} group. -@end deffn -@deffn Command reftex-show-commentary -Show the commentary section from @file{reftex.el}. -@end deffn -@deffn Command reftex-info -Run info on the top @b{Ref@TeX{}} node. -@end deffn -@deffn Command reftex-parse-document -Parse the entire document in order to update the parsing information. -@end deffn -@deffn Command reftex-reset-mode -Enforce rebuilding of several internal lists and variables. Also -removes the parse file associated with the current document. -@end deffn - -@node Options, Keymaps and Hooks, Commands, Top -@chapter Options, Keymaps, Hooks -@cindex Options, list of - -Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All -variables have customize support - so if you are not familiar with Emacs -Lisp (and even if you are) you might find it more comfortable to use -@code{customize} to look at and change these variables. @kbd{M-x -reftex-customize} will get you there. - -@menu -* Options (Table of Contents):: -* Options (Defining Label Environments):: -* Options (Creating Labels):: -* Options (Referencing Labels):: -* Options (Creating Citations):: -* Options (Index Support):: -* Options (Viewing Cross-References):: -* Options (Finding Files):: -* Options (Optimizations):: -* Options (Fontification):: -* Options (Misc):: -@end menu - -@node Options (Table of Contents), Options (Defining Label Environments), , Options -@section Table of Contents -@cindex Options, table of contents -@cindex Table of contents, options - -@defopt reftex-include-file-commands -List of LaTeX commands which input another file. -The file name is expected after the command, either in braces or separated -by whitespace. -@end defopt - -@defopt reftex-max-section-depth -Maximum depth of section levels in document structure. -Standard LaTeX needs 7, default is 12. -@end defopt - -@defopt reftex-section-levels -Commands and levels used for defining sections in the document. The -@code{car} of each cons cell is the name of the section macro. The -@code{cdr} is a number indicating its level. A negative level means the -same as the positive value, but the section will never get a number. -The @code{cdr} may also be a function which then has to return the -level. This list is also used for promotion and demotion of sectioning -commands. If you are using a document class which has several sets of -sectioning commands, promotion only works correctly if this list is -sorted first by set, then within each set by level. The promotion -commands always select the nearest entry with the correct new level. - -@end defopt - -@defopt reftex-toc-max-level -The maximum level of toc entries which will be included in the TOC. -Section headings with a bigger level will be ignored. In RefTeX, -chapters are level 1, sections level 2 etc. This variable can be -changed from within the @file{*toc*} buffer with the @kbd{t} key. -@end defopt - -@defopt reftex-part-resets-chapter -Non-@code{nil} means, @code{\part} is like any other sectioning command. -This means, part numbers will be included in the numbering of chapters, and -chapter counters will be reset for each part. -When @code{nil} (the default), parts are special, do not reset the -chapter counter and also do not show up in chapter numbers. -@end defopt - -@defopt reftex-auto-recenter-toc -Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. -When active, the @file{*TOC*} window will always show the section you -are currently working in. Recentering happens whenever Emacs is idle for -more than @code{reftex-idle-time} seconds. - -Value @code{t} means, turn on immediately when RefTeX gets started. Then, -recentering will work for any toc window created during the session. - -Value @code{frame} (the default) means, turn automatic recentering on -only while the dedicated TOC frame does exist, and do the recentering -only in that frame. So when creating that frame (with @kbd{d} key in an -ordinary TOC window), the automatic recentering is turned on. When the -frame gets destroyed, automatic recentering is turned off again. - -This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-toc-split-windows-horizontally -Non-@code{nil} means, create TOC window by splitting window -horizontally. The default is to split vertically. -@end defopt - -@defopt reftex-toc-split-windows-fraction -Fraction of the width or height of the frame to be used for TOC window. -@end defopt - -@defopt reftex-toc-keep-other-windows -Non-@code{nil} means, split the selected window to display the -@file{*toc*} buffer. This helps to keep the window configuration, but -makes the @file{*toc*} small. When @code{nil}, all other windows except -the selected one will be deleted, so that the @file{*toc*} window fills -half the frame. -@end defopt - -@defopt reftex-toc-include-file-boundaries -Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-labels -Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag -can be toggled from within the @file{*toc*} buffer with the @kbd{l} -key. -@end defopt - -@defopt reftex-toc-include-index-entries -Non-@code{nil} means, include index entries in @file{*toc*} buffer. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{i} key. -@end defopt - -@defopt reftex-toc-include-context -Non-@code{nil} means, include context with labels in the @file{*toc*} -buffer. Context will only be shown if the labels are visible as well. -This flag can be toggled from within the @file{*toc*} buffer with the -@kbd{c} key. -@end defopt - -@defopt reftex-toc-follow-mode -Non-@code{nil} means, point in @file{*toc*} buffer (the -table-of-contents buffer) will cause other window to follow. The other -window will show the corresponding part of the document. This flag can -be toggled from within the @file{*toc*} buffer with the @kbd{f} -key. -@end defopt - -@deffn {Normal Hook} reftex-toc-mode-hook -Normal hook which is run when a @file{*toc*} buffer is -created. -@end deffn - -@deffn Keymap reftex-toc-map -The keymap which is active in the @file{*toc*} buffer. -(@pxref{Table of Contents}). -@end deffn - -@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options -@section Defining Label Environments -@cindex Options, defining label environments -@cindex Defining label environments, options - -@defopt reftex-default-label-alist-entries -Default label alist specifications. It is a list of symbols with -associations in the constant @code{reftex-label-alist-builtin}. -@code{LaTeX} should always be the last entry. -@end defopt - -@defopt reftex-label-alist -Set this variable to define additions and changes to the defaults in -@code{reftex-default-label-alist-entries}. The only things you -@emph{must not} change is that @code{?s} is the type indicator for -section labels, and @key{SPC} for the @code{any} label type. These are -hard-coded at other places in the code. - -The value of the variable must be a list of items. Each item is a list -itself and has the following structure: - -@example - (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} - @var{context-method} (@var{magic-word} ... ) @var{toc-level}) -@end example - -Each list entry describes either an environment carrying a counter for -use with @code{\label} and @code{\ref}, or a LaTeX macro defining a -label as (or inside) one of its arguments. The elements of each list -entry are: - -@table @asis -@item @var{env-or-macro} -Name of the environment (like @samp{table}) or macro (like -@samp{\myfig}). For macros, indicate the arguments, as in -@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional -arguments, a star to mark the label argument, if any. The macro does -not have to have a label argument - you could also use -@samp{\label@{...@}} inside one of its arguments. - -Special names: @code{section} for section labels, @code{any} to define a -group which contains all labels. - -This may also be a function to do local parsing and identify point to be -in a non-standard label environment. The function must take an -argument @var{bound} and limit backward searches to this value. It -should return either nil or a cons cell @code{(@var{function} -. @var{position})} with the function symbol and the position where the -special environment starts. See the Info documentation for an -example. - -Finally this may also be @code{nil} if the entry is only meant to change -some settings associated with the type indicator character (see -below). - -@item @var{type-key} -Type indicator character, like @code{?t}, must be a printable ASCII -character. The type indicator is a single character which defines a -label type. Any label inside the environment or macro is assumed to -belong to this type. The same character may occur several times in this -list, to cover cases in which different environments carry the same -label type (like @code{equation} and @code{eqnarray}). If the type -indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, -the macro defines neutral labels just like @code{\label}. In this case -the reminder of this entry is ignored. - -@item @var{label-prefix} -Label prefix string, like @samp{tab:}. The prefix is a short string -used as the start of a label. It may be the empty string. The prefix -may contain the following @samp{%} escapes: - -@example -%f Current file name, directory and extension stripped. -%F Current file name relative to master file directory. -%m Master file name, directory and extension stripped. -%M Directory name (without path) where master file is located. -%u User login name, on systems which support this. -%S A section prefix derived with variable @code{reftex-section-prefixes}. -@end example - -@noindent -Example: In a file @file{intro.tex}, @samp{eq:%f:} will become -@samp{eq:intro:}. - -@item @var{reference-format} -Format string for reference insert in buffer. @samp{%s} will be -replaced by the label. When the format starts with @samp{~}, this -@samp{~} will only be inserted when the character before point is -@emph{not} a whitespace. - -@item @var{context-method} -Indication on how to find the short context. -@itemize @minus -@item -If @code{nil}, use the text following the @samp{\label@{...@}} macro. -@item -If @code{t}, use -@itemize @minus -@item -the section heading for section labels. -@item -text following the @samp{\begin@{...@}} statement of environments (not -a good choice for environments like eqnarray or enumerate, where one has -several labels in a single environment). -@item -text after the macro name (starting with the first arg) for -macros. -@end itemize -@item -If an integer, use the nth argument of the macro. As a special case, -1000 means to get text after the last macro argument. -@item -If a string, use as regexp to search @emph{backward} from the label. -Context is then the text following the end of the match. E.g. putting -this to @samp{\\caption[[@{]} will use the caption in a figure or table -environment. @samp{\\begin@{eqnarray@}\|\\\\} works for -eqnarrays. -@item -If any of @code{caption}, @code{item}, @code{eqnarray-like}, -@code{alignat-like}, this symbol will internally be translated into an -appropriate regexp (see also the variable -@code{reftex-default-context-regexps}). -@item -If a function, call this function with the name of the environment/macro -as argument. On call, point will be just after the @code{\label} macro. -The function is expected to return a suitable context string. It should -throw an exception (error) when failing to find context. As an example, -here is a function returning the 10 chars following the label macro as -context: - -@example -(defun my-context-function (env-or-mac) - (if (> (point-max) (+ 10 (point))) - (buffer-substring (point) (+ 10 (point))) - (error "Buffer too small"))) -@end example -@end itemize - -Label context is used in two ways by @b{Ref@TeX{}}: For display in the label -menu, and to derive a label string. If you want to use a different -method for each of these, specify them as a dotted pair. -E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for -display, and text from the default position (@code{t}) to derive a label -string. This is actually used for section labels. - -@item @var{magic-word-list} -List of magic words which identify a reference to be of this type. If -the word before point is equal to one of these words when calling -@code{reftex-reference}, the label list offered will be automatically -restricted to labels of the correct type. If the first element of this -word--list is the symbol `regexp', the strings are interpreted as regular -expressions. - -@item @var{toc-level} -The integer level at which this environment should be added to the table -of contents. See also @code{reftex-section-levels}. A positive value -will number the entries mixed with the sectioning commands of the same -level. A negative value will make unnumbered entries. Useful only for -theorem-like environments which structure the document. Will be ignored -for macros. When omitted or @code{nil}, no TOC entries will be -made. -@end table - -If the type indicator characters of two or more entries are the same, -@b{Ref@TeX{}} will use -@itemize @minus -@item -the first non-@code{nil} format and prefix -@item -the magic words of all involved entries. -@end itemize - -Any list entry may also be a symbol. If that has an association in -@code{reftex-label-alist-builtin}, the @code{cddr} of that association is -spliced into the list. However, builtin defaults should normally be set -with the variable @code{reftex-default-label-alist-entries}. -@end defopt - -@defopt reftex-section-prefixes -Prefixes for section labels. When the label prefix given in an entry in -@code{reftex-label-alist} contains @samp{%S}, this list is used to -determine the correct prefix string depending on the current section -level. The list is an alist, with each entry of the form -@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro -names like @samp{chapter}, integer section levels (as given in -@code{reftex-section-levels}), and @code{t} for the default. -@end defopt - -@defopt reftex-default-context-regexps -Alist with default regular expressions for finding context. The emacs -lisp form @w{@code{(format regexp (regexp-quote environment))}} is used -to calculate the final regular expression - so @samp{%s} will be -replaced with the environment or macro. -@end defopt - -@defopt reftex-trust-label-prefix -Non-@code{nil} means, trust the label prefix when determining label type. -It is customary to use special label prefixes to distinguish different label -types. The label prefixes have no syntactic meaning in LaTeX (unless -special packages like fancyref) are being used. RefTeX can and by -default does parse around each label to detect the correct label type, -but this process can be slow when a document contains thousands of -labels. If you use label prefixes consistently, you may speed up -document parsing by setting this variable to a non-nil value. RefTeX -will then compare the label prefix with the prefixes found in -`reftex-label-alist' and derive the correct label type in this way. -Possible values for this option are: - -@example -t @r{This means to trust any label prefixes found.} -regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} -list @r{List of accepted prefixes, as strings. The colon is part of} - @r{the prefix, e.g. ("fn:" "eqn:" "item:").} -nil @r{Never trust a label prefix.} -@end example -The only disadvantage of using this feature is that the label context -displayed in the label selection buffer along with each label is -simply some text after the label definition. This is no problem if you -place labels keeping this in mind (e.g. @i{before} the equation, @i{at -the beginning} of a fig/tab caption ...). Anyway, it is probably best -to use the regexp or the list value types to fine-tune this feature. -For example, if your document contains thousands of footnotes with -labels fn:xxx, you may want to set this variable to the value "^fn:$" or -("fn:"). Then RefTeX will still do extensive parsing for any -non-footnote labels. -@end defopt - -@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options -@section Creating Labels -@cindex Options, creating labels -@cindex Creating labels, options - -@defopt reftex-insert-label-flags -Flags governing label insertion. The value has the form - -@example -(@var{derive} @var{prompt}) -@end example - -If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible -label from context. A section label for example will be derived from -the section heading. The conversion of the context to a valid label is -governed by the specifications given in -@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, -the default label will consist of the prefix and a unique number, like -@samp{eq:23}. - -If @var{prompt} is @code{t}, the user will be prompted for a label -string. When @var{prompt} is @code{nil}, the default label will be -inserted without query. - -So the combination of @var{derive} and @var{prompt} controls label -insertion. Here is a table describing all four possibilities: - -@example -@group -@var{derive} @var{prompt} @var{action} ------------------------------------------------------------ -nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} -nil t @r{Prompt for label.} -t nil @r{Derive a label from context and insert. No query.} -t t @r{Derive a label from context, prompt for confirmation.} -@end group -@end example - -Each flag may be set to @code{t}, @code{nil}, or a string of label type -letters indicating the label types for which it should be true. Thus, -the combination may be set differently for each label type. The default -settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from -headings (with confirmation). Prompt for figure and table labels. Use -simple labels without confirmation for everything else. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), @code{N} (endnote) plus any definitions in -@code{reftex-label-alist}. -@end defopt - -@deffn Hook reftex-format-label-function -If non-@code{nil}, should be a function which produces the string to -insert as a label definition. The function will be called with two -arguments, the @var{label} and the @var{default-format} (usually -@samp{\label@{%s@}}). It should return the string to insert into the -buffer. -@end deffn - -@deffn Hook reftex-string-to-label-function -Function to turn an arbitrary string into a valid label. -@b{Ref@TeX{}}'s default function uses the variable -@code{reftex-derive-label-parameters}. -@end deffn - -@deffn Hook reftex-translate-to-ascii-function -Filter function which will process a context string before it is used to -derive a label from it. The intended application is to convert ISO or -Mule characters into something valid in labels. The default function -@code{reftex-latin1-to-ascii} removes the accents from Latin-1 -characters. X-Symbol (>=2.6) sets this variable to the much more -general @code{x-symbol-translate-to-ascii}. -@end deffn - -@defopt reftex-derive-label-parameters -Parameters for converting a string into a label. This variable is a -list of the following items: -@table @asis -@item @var{nwords} -Number of words to use. -@item @var{maxchar} -Maximum number of characters in a label string. -@item @var{invalid} -@code{nil}: Throw away any words containing characters invalid in labels.@* -@code{t}: Throw away only the invalid characters, not the whole word. -@item @var{abbrev} -@code{nil}: Never abbreviate words.@* -@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* -@code{1}: Abbreviate words if necessary to shorten label string. -@item @var{separator} -String separating different words in the label. -@item @var{ignorewords} -List of words which should not be part of labels. -@item @var{downcase} -@code{t}: Downcase words before putting them into the label.@* -@end table -@end defopt - -@defopt reftex-label-illegal-re -Regexp matching characters not valid in labels. -@end defopt - -@defopt reftex-abbrev-parameters -Parameters for abbreviation of words. A list of four parameters. -@table @asis -@item @var{min-chars} -Minimum number of characters remaining after abbreviation. -@item @var{min-kill} -Minimum number of characters to remove when abbreviating words. -@item @var{before} -Character class before abbrev point in word. -@item @var{after} -Character class after abbrev point in word. -@end table -@end defopt - -@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options -@section Referencing Labels -@cindex Options, referencing labels -@cindex Referencing labels, options - -@defopt reftex-label-menu-flags -List of flags governing the label menu makeup. The flags are: -@table @asis -@item @var{table-of-contents} -Show the labels embedded in a table of context. -@item @var{section-numbers} -Include section numbers (like 4.1.3) in table of contents. -@item @var{counters} -Show counters. This just numbers the labels in the menu. -@item @var{no-context} -Non-@code{nil} means do @emph{not} show the short context. -@item @var{follow} -Follow full context in other window. -@item @var{show-commented} -Show labels from regions which are commented out. -@item @var{match-everywhere} -Obsolete flag. -@item @var{show-files} -Show begin and end of included files. -@end table - -Each of these flags can be set to @code{t} or @code{nil}, or to a string -of type letters indicating the label types for which it should be true. -These strings work like character classes in regular expressions. Thus, -setting one of the flags to @samp{"sf"} makes the flag true for section -and figure labels, @code{nil} for everything else. Setting it to -@samp{"^sf"} makes it the other way round. - -The available label types are: @code{s} (section), @code{f} (figure), -@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} -(footnote), plus any definitions in @code{reftex-label-alist}. - -Most options can also be switched from the label menu itself - so if you -decide here to not have a table of contents in the label menu, you can -still get one interactively during selection from the label menu. -@end defopt - -@defopt reftex-multiref-punctuation -Punctuation strings for multiple references. When marking is used in -the selection buffer to select several references, this variable -associates the 3 marking characters @samp{,-+} with prefix strings to be -inserted into the buffer before the corresponding @code{\ref} macro. -This is used to string together whole reference sets, like -@samp{eqs. 1,2,3-5,6 and 7} in a single call to -@code{reftex-reference}. -@end defopt - -@defopt reftex-vref-is-default -Non-@code{nil} means, the varioref macro @code{\vref} is used as -default. In the selection buffer, the @kbd{v} key toggles the reference -macro between @code{\ref} and @code{\vref}. The value of this variable -determines the default which is active when entering the selection -process. Instead of @code{nil} or @code{t}, this may also be a string -of type letters indicating the label types for which it should be -true. -@end defopt - -@defopt reftex-fref-is-default -Non-@code{nil} means, the fancyref macro @code{\fref} is used as -default. In the selection buffer, the @kbd{V} key toggles the reference -macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of -this variable determines the default which is active when entering the -selection process. Instead of @code{nil} or @code{t}, this may also be -a string of type letters indicating the label types for which it should -be true. -@end defopt - -@deffn Hook reftex-format-ref-function -If non-@code{nil}, should be a function which produces the string to -insert as a reference. Note that the insertion format can also be -changed with @code{reftex-label-alist}. This hook also is used by the -special commands to insert @code{\vref} and @code{\fref} references, so -even if you set this, your setting will be ignored by the special -commands. The function will be called with two arguments, the -@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). -It should return the string to insert into the buffer. -@end deffn - -@defopt reftex-level-indent -Number of spaces to be used for indentation per section level. -@end defopt - -@defopt reftex-guess-label-type -Non-@code{nil} means, @code{reftex-reference} will try to guess the -label type. To do that, @b{Ref@TeX{}} will look at the word before the -cursor and compare it with the magic words given in -@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will -immediately offer the correct label menu - otherwise it will prompt you -for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} -will always prompt for a label type. -@end defopt - -@deffn {Normal Hook} reftex-display-copied-context-hook -Normal Hook which is run before context is displayed anywhere. Designed -for @w{@code{X-Symbol}}, but may have other uses as well. -@end deffn - -@deffn Hook reftex-pre-refontification-functions -@code{X-Symbol} specific hook. Probably not useful for other purposes. -The functions get two arguments, the buffer from where the command -started and a symbol indicating in what context the hook is -called. -@end deffn - -@deffn {Normal Hook} reftex-select-label-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-label-mode}. -@end deffn - -@deffn Keymap reftex-select-label-map -The keymap which is active in the labels selection process -(@pxref{Referencing Labels}). -@end deffn - -@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options -@section Creating Citations -@cindex Options, creating citations -@cindex Creating citations, options - -@defopt reftex-bibliography-commands -LaTeX commands which specify the BibTeX databases to use with the document. -@end defopt - -@defopt reftex-bibfile-ignore-regexps -List of regular expressions to exclude files in -@code{\\bibliography@{..@}}. File names matched by any of these regexps -will not be parsed. Intended for files which contain only -@code{@@string} macro definitions and the like, which are ignored by -@b{Ref@TeX{}} anyway. -@end defopt - -@defopt reftex-default-bibliography -List of BibTeX database files which should be used if none are specified. -When @code{reftex-citation} is called from a document with neither -a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} -environment, @b{Ref@TeX{}} will scan these files instead. Intended for -using @code{reftex-citation} in non-LaTeX files. The files will be -searched along the BIBINPUTS or TEXBIB path. -@end defopt - -@defopt reftex-sort-bibtex-matches -Sorting of the entries found in BibTeX databases by reftex-citation. -Possible values: -@example -nil @r{Do not sort entries.} -author @r{Sort entries by author name.} -year @r{Sort entries by increasing year.} -reverse-year @r{Sort entries by decreasing year.} -@end example -@end defopt - -@defopt reftex-cite-format -The format of citations to be inserted into the buffer. It can be a -string, an alist or a symbol. In the simplest case this is just the string -@samp{\cite@{%l@}}, which is also the default. See the definition of -@code{reftex-cite-format-builtin} for more complex examples. - -If @code{reftex-cite-format} is a string, it will be used as the format. -In the format, the following percent escapes will be expanded. - -@table @code -@item %l -The BibTeX label of the citation. -@item %a -List of author names, see also @code{reftex-cite-punctuation}. -@item %2a -Like %a, but abbreviate more than 2 authors like Jones et al. -@item %A -First author name only. -@item %e -Works like @samp{%a}, but on list of editor names. (@samp{%2e} and -@samp{%E} work a well). -@end table - -It is also possible to access all other BibTeX database fields: - -@example -%b booktitle %c chapter %d edition %h howpublished -%i institution %j journal %k key %m month -%n number %o organization %p pages %P first page -%r address %s school %u publisher %t title -%v volume %y year -%B booktitle, abbreviated %T title, abbreviated -@end example - -@noindent -Usually, only @samp{%l} is needed. The other stuff is mainly for the -echo area display, and for @code{(setq reftex-comment-citations t)}. - -@samp{%<} as a special operator kills punctuation and space around it -after the string has been formatted. - -A pair of square brackets indicates an optional argument, and RefTeX -will prompt for the values of these arguments. - -Beware that all this only works with BibTeX database files. When -citations are made from the @code{\bibitems} in an explicit -@code{thebibliography} environment, only @samp{%l} is available. - -If @code{reftex-cite-format} is an alist of characters and strings, the -user will be prompted for a character to select one of the possible -format strings. - -In order to configure this variable, you can either set -@code{reftex-cite-format} directly yourself or set it to the -@emph{symbol} of one of the predefined styles. The predefined symbols -are those which have an association in the constant -@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format -'natbib)}. -@end defopt - -@deffn Hook reftex-format-cite-function -If non-@code{nil}, should be a function which produces the string to -insert as a citation. Note that the citation format can also be changed -with the variable @code{reftex-cite-format}. The function will be -called with two arguments, the @var{citation-key} and the -@var{default-format} (taken from @code{reftex-cite-format}). It should -return the string to insert into the buffer. -@end deffn - -@defopt reftex-cite-prompt-optional-args -Non-@code{nil} means, prompt for empty optional arguments in cite macros. -When an entry in @code{reftex-cite-format} ist given with square brackets to -indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can -prompt for values. Possible values are: -@example -nil @r{Never prompt for optional arguments} -t @r{Always prompt} -maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example -Unnecessary empty optional arguments are removed before insertion into -the buffer. See @code{reftex-cite-cleanup-optional-args}. -@end defopt - -@defopt reftex-cite-cleanup-optional-args -Non-@code{nil} means, remove empty optional arguments from cite macros -if possible. -@end defopt - -@defopt reftex-comment-citations -Non-@code{nil} means add a comment for each citation describing the full -entry. The comment is formatted according to -@code{reftex-cite-comment-format}. -@end defopt - -@defopt reftex-cite-comment-format -Citation format used for commented citations. Must @emph{not} contain -@samp{%l}. See the variable @code{reftex-cite-format} for possible -percent escapes. -@end defopt - -@defopt reftex-cite-punctuation -Punctuation for formatting of name lists in citations. This is a list -of 3 strings. -@enumerate -@item -normal names separator, like @samp{, } in Jones, Brown and Miller -@item -final names separator, like @samp{ and } in Jones, Brown and Miller -@item -The @samp{et al.} string, like @samp{ @{\it et al.@}} in -Jones @{\it et al.@} -@end enumerate -@end defopt - -@deffn {Normal Hook} reftex-select-bib-mode-hook -Normal hook which is run when a selection buffer enters -@code{reftex-select-bib-mode}. -@end deffn - -@deffn Keymap reftex-select-bib-map -The keymap which is active in the citation-key selection process -(@pxref{Creating Citations}). -@end deffn - -@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options -@section Index Support -@cindex Options, Index support -@cindex Index support, options - -@defopt reftex-support-index -Non-@code{nil} means, index entries are parsed as well. Index support -is resource intensive and the internal structure holding the parsed -information can become quite big. Therefore it can be turned off. When -this is @code{nil} and you execute a command which requires index -support, you will be asked for confirmation to turn it on and rescan the -document. -@end defopt - -@defopt reftex-index-special-chars -List of special characters in index entries, given as strings. These -correspond to the @code{MakeIndex} keywords -@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. -@end defopt - -@defopt reftex-index-macros -List of macros which define index entries. The structure of each entry -is -@lisp -(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) -@end lisp - -@var{macro} is the macro. Arguments should be denoted by empty braces, -as for example in @samp{\index[]@{*@}}. Use square brackets to denote -optional arguments. The star marks where the index key is. - -@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} -are reserved for the default index and the glossary. Other indices can -be defined as well. If this is an integer, the Nth argument of the -macro holds the index tag. - -@var{key} is a character which is used to identify the macro for input -with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are -reserved for default index and glossary. - -@var{prefix} can be a prefix which is added to the @var{key} part of the -index entry. If you have a macro -@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix -should be @samp{Molecules!}. - -@var{exclude} can be a function. If this function exists and returns a -non-@code{nil} value, the index entry at point is ignored. This was -implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts -in the LaTeX2e @code{index} package. - -@var{repeat}, if non-@code{nil}, means the index macro does not typeset -the entry in the text, so that the text has to be repeated outside the -index macro. Needed for @code{reftex-index-selection-or-word} and for -indexing from the phrase buffer. - -The final entry may also be a symbol. It must have an association in -the variable @code{reftex-index-macros-builtin} to specify the main -indexing package you are using. Valid values are currently -@example -default @r{The LaTeX default - unnecessary to specify this one} -multind @r{The multind.sty package} -index @r{The index.sty package} -index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} - @r{Should not be used - only for old documents} -@end example -Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, -so with a sufficiently new version of AUCTeX, you should not set the -package here. -@end defopt - -@defopt reftex-index-default-macro -The default index macro for @code{reftex-index-selection-or-word}. -This is a list with @code{(@var{macro-key} @var{default-tag})}. - -@var{macro-key} is a character identifying an index macro - see -@code{reftex-index-macros}. - -@var{default-tag} is the tag to be used if the macro requires a -@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, -@b{Ref@TeX{}} will ask for it. When this is the empty string and the -TAG argument of the index macro is optional, the TAG argument will be -omitted. -@end defopt - -@defopt reftex-index-default-tag -Default index tag. When working with multiple indexes, RefTeX queries -for an index tag when creating index entries or displaying a specific -index. This variable controls the default offered for these queries. -The default can be selected with @key{RET} during selection or -completion. Valid values of this variable are: -@example -nil @r{Do not provide a default index} -"tag" @r{The default index tag given as a string, e.g. "idx"} -last @r{The last used index tag will be offered as default} -@end example -@end defopt - -@defopt reftex-index-math-format -Format of index entries when copied from inside math mode. When -@code{reftex-index-selection-or-word} is executed inside TeX math mode, -the index key copied from the buffer is processed with this format -string through the @code{format} function. This can be used to add the -math delimiters (e.g. @samp{$}) to the string. Requires the -@file{texmathp.el} library which is part of AUCTeX. -@end defopt - -@defopt reftex-index-phrase-file-extension -File extension for the index phrase file. This extension will be added -to the base name of the master file. -@end defopt - -@defopt reftex-index-phrases-logical-and-regexp -Regexp matching the @samp{and} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, each part will generate an index macro. So each match of -the search phrase will produce @emph{several} different index entries. -Make sure this does no match things which are not separators. This -logical @samp{and} has higher priority than the logical @samp{or} -specified in @code{reftex-index-phrases-logical-or-regexp}. -@end defopt - -@defopt reftex-index-phrases-logical-or-regexp -Regexp matching the @samp{or} operator for index arguments in phrases -file. When several index arguments in a phrase line are separated by -this operator, the user will be asked to select one of them at each -match of the search phrase. The first index arg will be the default. A -number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make -sure this does no match things which are not separators. The logical -@samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} -has higher priority than this logical @samp{or}. -@end defopt - -@defopt reftex-index-phrases-search-whole-words -Non-@code{nil} means phrases search will look for whole words, not subwords. -This works by requiring word boundaries at the beginning and end of -the search string. When the search phrase already has a non-word-char -at one of these points, no word boundary is required there. -@end defopt - -@defopt reftex-index-phrases-case-fold-search -Non-@code{nil} means, searching for index phrases will ignore -case. -@end defopt - -@defopt reftex-index-verify-function -A function which is called at each match during global indexing. -If the function returns nil, the current match is skipped. -@end defopt - -@defopt reftex-index-phrases-skip-indexed-matches -Non-@code{nil} means, skip matches which appear to be indexed already. -When doing global indexing from the phrases buffer, searches for some -phrases may match at places where that phrase was already indexed. In -particular when indexing an already processed document again, this -will even be the norm. When this variable is non-@code{nil}, -@b{Ref@TeX{}} checks if the match is an index macro argument, or if an -index macro is directly before or after the phrase. If that is the -case, that match will be ignored. -@end defopt - -@defopt reftex-index-phrases-wrap-long-lines -Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. -Inserting indexing commands in a line makes the line longer - often -so long that it does not fit onto the screen. When this variable is -non-@code{nil}, newlines will be added as necessary before and/or after the -indexing command to keep lines short. However, the matched text -phrase and its index command will always end up on a single line. -@end defopt - -@defopt reftex-index-phrases-sort-prefers-entry -Non-@code{nil} means when sorting phrase lines, the explicit index entry -is used. Phrase lines in the phrases buffer contain a search phrase, and -sorting is normally based on these. Some phrase lines also have -an explicit index argument specified. When this variable is -non-@code{nil}, the index argument will be used for sorting. -@end defopt - -@defopt reftex-index-phrases-sort-in-blocks -Non-@code{nil} means, empty and comment lines separate phrase buffer -into blocks. Sorting will then preserve blocks, so that lines are -re-arranged only within blocks. -@end defopt - -@defopt reftex-index-phrases-map -Keymap for the Index Phrases buffer. -@end defopt - -@defopt reftex-index-phrases-mode-hook -Normal hook which is run when a buffer is put into -@code{reftex-index-phrases-mode}. -@end defopt - -@defopt reftex-index-section-letters -The letters which denote sections in the index. Usually these are all -capital letters. Don't use any downcase letters. Order is not -significant, the index will be sorted by whatever the sort function -thinks is correct. In addition to these letters, @b{Ref@TeX{}} will -create a group @samp{!} which contains all entries sorted below the -lowest specified letter. In the @file{*Index*} buffer, pressing any of -these capital letters or @kbd{!} will jump to that section. -@end defopt - -@defopt reftex-index-include-context -Non-@code{nil} means, display the index definition context in the -@file{*Index*} buffer. This flag may also be toggled from the -@file{*Index*} buffer with the @kbd{c} key. -@end defopt - -@defopt reftex-index-follow-mode -Non-@code{nil} means, point in @file{*Index*} buffer will cause other -window to follow. The other window will show the corresponding part of -the document. This flag can be toggled from within the @file{*Index*} -buffer with the @kbd{f} key. -@end defopt - -@deffn Keymap reftex-index-map -The keymap which is active in the @file{*Index*} buffer -(@pxref{Index Support}). -@end deffn - -@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options -@section Viewing Cross-References -@cindex Options, viewing cross-references -@cindex Viewing cross-references, options - -@defopt reftex-view-crossref-extra -Macros which can be used for the display of cross references. -This is used when `reftex-view-crossref' is called with point in an -argument of a macro. Note that crossref viewing for citations, -references (both ways) and index entries is hard-coded. This variable -is only to configure additional structures for which crossreference -viewing can be useful. Each entry has the structure -@example -(@var{macro-re} @var{search-re} @var{highlight}). -@end example -@var{macro-re} is matched against the macro. @var{search-re} is the -regexp used to search for cross references. @samp{%s} in this regexp is -replaced with the macro argument at point. @var{highlight} is an -integer indicating which subgroup of the match should be highlighted. -@end defopt - -@defopt reftex-auto-view-crossref -Non-@code{nil} means, initially turn automatic viewing of crossref info -on. Automatic viewing of crossref info normally uses the echo area. -Whenever point is idle for more than @code{reftex-idle-time} seconds on -the argument of a @code{\ref} or @code{\cite} macro, and no other -message is being displayed, the echo area will display information about -that cross reference. You can also set the variable to the symbol -@code{window}. In this case a small temporary window is used for the -display. This feature can be turned on and off from the menu -(Ref->Options). -@end defopt - -@defopt reftex-idle-time -Time (secs) Emacs has to be idle before automatic crossref display -or toc recentering is done. -@end defopt - -@defopt reftex-cite-view-format -Citation format used to display citation info in the message area. See -the variable @code{reftex-cite-format} for possible percent -escapes. -@end defopt - -@defopt reftex-revisit-to-echo -Non-@code{nil} means, automatic citation display will revisit files if -necessary. When nil, citation display in echo area will only be active -for cached echo strings (see @code{reftex-cache-cite-echo}), or for -BibTeX database files which are already visited by a live associated -buffers. -@end defopt - -@defopt reftex-cache-cite-echo -Non-@code{nil} means, the information displayed in the echo area for -cite macros (see variable @code{reftex-auto-view-crossref}) is cached and -saved along with the parsing information. The cache survives document -scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. -@end defopt - -@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options -@section Finding Files -@cindex Options, Finding Files -@cindex Finding files, options - -@defopt reftex-texpath-environment-variables -List of specifications how to retrieve the search path for TeX files. -Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.tex"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-bibpath-environment-variables -List of specifications how to retrieve the search path for BibTeX -files. Several entries are possible. -@itemize @minus -@item -If an element is the name of an environment variable, its content is -used. -@item -If an element starts with an exclamation mark, it is used as a command -to retrieve the path. A typical command with the kpathsearch library -would be @w{@code{"!kpsewhich -show-path=.bib"}}. -@item -Otherwise the element itself is interpreted as a path. -@end itemize -Multiple directories can be separated by the system dependent -@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will -be expanded recursively. See also @code{reftex-use-external-file-finders}. -@end defopt - -@defopt reftex-file-extensions -Association list with file extensions for different file types. -This is a list of items, each item is like: -@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} -@example -@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} -@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} -@var{other-ext}: @r{Any number of other valid extensions for this file type.} -@end example -When a files is searched and it does not have any of the valid extensions, -we try the default extension first, and then the naked file name. -@end defopt - -@defopt reftex-search-unrecursed-path-first -Non-@code{nil} means, search all specified directories before trying -recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, -then @samp{/tex/}, and then all subdirectories of @samp{./}. If this -option is @code{nil}, the subdirectories of @samp{./} are searched -before @samp{/tex/}. This is mainly for speed - most of the time the -recursive path is for the system files and not for the user files. Set -this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with -equal names in wrong sequence. -@end defopt - -@defopt reftex-use-external-file-finders -Non-@code{nil} means, use external programs to find files. Normally, -@b{Ref@TeX{}} searches the paths given in the environment variables -@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX -database files. With this option turned on, it calls an external -program specified in the option @code{reftex-external-file-finders} -instead. As a side effect, the variables -@code{reftex-texpath-environment-variables} and -@code{reftex-bibpath-environment-variables} will be ignored. -@end defopt - -@defopt reftex-external-file-finders -Association list with external programs to call for finding files. Each -entry is a cons cell @w{@code{(@var{type} . @var{program})}}. -@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a -string containing the external program to use with any arguments. -@code{%f} will be replaced by the name of the file to be found. Note -that these commands will be executed directly, not via a shell. Only -relevant when @code{reftex-use-external-file-finders} is -non-@code{nil}. -@end defopt - -@page -@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options -@section Optimizations -@cindex Options, optimizations -@cindex Optimizations, options - -@defopt reftex-keep-temporary-buffers -Non-@code{nil} means, keep buffers created for parsing and lookup. -@b{Ref@TeX{}} sometimes needs to visit files related to the current -document. We distinguish files visited for -@table @asis -@item PARSING -Parts of a multifile document loaded when (re)-parsing the -document. -@item LOOKUP -BibTeX database files and TeX files loaded to find a reference, to -display label context, etc. -@end table -The created buffers can be kept for later use, or be thrown away -immediately after use, depending on the value of this variable: - -@table @code -@item nil -Throw away as much as possible. -@item t -Keep everything. -@item 1 -Throw away buffers created for parsing, but keep the ones created for -lookup. -@end table - -If a buffer is to be kept, the file is visited normally (which is -potentially slow but will happen only once). If a buffer is to be thrown -away, the initialization of the buffer depends upon the variable -@code{reftex-initialize-temporary-buffers}. -@end defopt - -@defopt reftex-initialize-temporary-buffers -Non-@code{nil} means do initializations even when visiting file -temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and -other stuff to briefly visit a file. When @code{t}, the full default -initializations are done (@code{find-file-hook} etc.). Instead of -@code{t} or @code{nil}, this variable may also be a list of hook -functions to do a minimal initialization. -@end defopt - -@defopt reftex-no-include-regexps -List of regular expressions to exclude certain input files from parsing. -If the name of a file included via @code{\include} or @code{\input} is -matched by any of the regular expressions in this list, that file is not -parsed by @b{Ref@TeX{}}. -@end defopt - -@defopt reftex-enable-partial-scans -Non-@code{nil} means, re-parse only 1 file when asked to re-parse. -Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} -commands, or with the @kbd{r} key in menus. When this option is -@code{t} in a multifile document, we will only parse the current buffer, -or the file associated with the label or section heading near point in a -menu. Requesting re-parsing of an entire multifile document then -requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in -menus. -@end defopt - -@defopt reftex-save-parse-info -Non-@code{nil} means, save information gathered with parsing in files. -The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is -used to save the information. When this variable is @code{t}, -@itemize @minus -@item -accessing the parsing information for the first time in an editing -session will read that file (if available) instead of parsing the -document. -@item -exiting Emacs or killing a buffer in reftex-mode will cause a new -version of the file to be written. -@end itemize -@end defopt - -@defopt reftex-parse-file-extension -File extension for the file in which parser information is stored. -This extension is added to the base name of the master file. -@end defopt - -@defopt reftex-allow-automatic-rescan -Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems -necessary. Applies (currently) only in rare cases, when a new label -cannot be placed with certainty into the internal label list. -@end defopt - -@defopt reftex-use-multiple-selection-buffers -Non-@code{nil} means use a separate selection buffer for each label -type. These buffers are kept from one selection to the next and need -not to be created for each use - so the menu generally comes up faster. -The selection buffers will be erased (and therefore updated) -automatically when new labels in its category are added. See the -variable @code{reftex-auto-update-selection-buffers}. -@end defopt - -@defopt reftex-auto-update-selection-buffers -Non-@code{nil} means, selection buffers will be updated automatically. -When a new label is defined with @code{reftex-label}, all selection -buffers associated with that label category are emptied, in order to -force an update upon next use. When @code{nil}, the buffers are left -alone and have to be updated by hand, with the @kbd{g} key from the -label selection process. The value of this variable will only have any -effect when @code{reftex-use-multiple-selection-buffers} is -non-@code{nil}. -@end defopt - -@node Options (Fontification), Options (Misc), Options (Optimizations), Options -@section Fontification -@cindex Options, fontification -@cindex Fontification, options - -@defopt reftex-use-fonts -Non-@code{nil} means, use fonts in label menu and on-the-fly help. -Font-lock must be loaded as well to actually get fontified -display. After changing this option, a rescan may be necessary to -activate it. -@end defopt - -@defopt reftex-refontify-context -Non-@code{nil} means, re-fontify the context in the label menu with -font-lock. This slightly slows down the creation of the label menu. It -is only necessary when you definitely want the context fontified. - -This option may have 3 different values: -@table @code -@item nil -Never refontify. -@item t -Always refontify. -@item 1 -Refontify when necessary, e.g. with old versions of the x-symbol -package. -@end table -The option is ignored when @code{reftex-use-fonts} is @code{nil}. -@end defopt - -@defopt reftex-highlight-selection -Non-@code{nil} means, highlight selected text in selection and -@file{*toc*} buffers. Normally, the text near the cursor is the -@emph{selected} text, and it is highlighted. This is the entry most -keys in the selection and @file{*toc*} buffers act on. However, if you -mainly use the mouse to select an item, you may find it nice to have -mouse-triggered highlighting @emph{instead} or @emph{as well}. The -variable may have one of these values: - -@example -nil @r{No highlighting.} -cursor @r{Highlighting is cursor driven.} -mouse @r{Highlighting is mouse driven.} -both @r{Both cursor and mouse trigger highlighting.} -@end example - -Changing this variable requires to rebuild the selection and *toc* -buffers to become effective (keys @kbd{g} or @kbd{r}). -@end defopt - -@defopt reftex-cursor-selected-face -Face name to highlight cursor selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-mouse-selected-face -Face name to highlight mouse selected item in toc and selection buffers. -See also the variable @code{reftex-highlight-selection}. -@end defopt -@defopt reftex-file-boundary-face -Face name for file boundaries in selection buffer. -@end defopt -@defopt reftex-label-face -Face name for labels in selection buffer. -@end defopt -@defopt reftex-section-heading-face -Face name for section headings in toc and selection buffers. -@end defopt -@defopt reftex-toc-header-face -Face name for the header of a toc buffer. -@end defopt -@defopt reftex-bib-author-face -Face name for author names in bib selection buffer. -@end defopt -@defopt reftex-bib-year-face -Face name for year in bib selection buffer. -@end defopt -@defopt reftex-bib-title-face -Face name for article title in bib selection buffer. -@end defopt -@defopt reftex-bib-extra-face -Face name for bibliographic information in bib selection buffer. -@end defopt -@defopt reftex-select-mark-face -Face name for marked entries in the selection buffers. -@end defopt -@defopt reftex-index-header-face -Face name for the header of an index buffer. -@end defopt -@defopt reftex-index-section-face -Face name for the start of a new letter section in the index. -@end defopt -@defopt reftex-index-tag-face -Face name for index names (for multiple indices). -@end defopt -@defopt reftex-index-face -Face name for index entries. -@end defopt - -@node Options (Misc), , Options (Fontification), Options -@section Miscellaneous -@cindex Options, misc - -@defopt reftex-extra-bindings -Non-@code{nil} means, make additional key bindings on startup. These -extra bindings are located in the users @samp{C-c letter} -map. @xref{Key Bindings}. -@end defopt - -@defopt reftex-plug-into-AUCTeX -Plug-in flags for AUCTeX interface. This variable is a list of -5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} -will - -@example -- supply labels in new sections and environments (flag 1) -- supply arguments for macros like @code{\label} (flag 2) -- supply arguments for macros like @code{\ref} (flag 3) -- supply arguments for macros like @code{\cite} (flag 4) -- supply arguments for macros like @code{\index} (flag 5) -@end example - -You may also set the variable itself to t or nil in order to turn all -options on or off, respectively.@* -Supplying labels in new sections and environments applies when creating -sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* -Supplying macro arguments applies when you insert such a macro -interactively with @kbd{C-c @key{RET}}.@* -See the AUCTeX documentation for more information. -@end defopt - -@defopt reftex-revisit-to-follow -Non-@code{nil} means, follow-mode will revisit files if necessary. -When nil, follow-mode will be suspended for stuff in unvisited files. -@end defopt - -@defopt reftex-allow-detached-macro-args -Non-@code{nil} means, allow arguments of macros to be detached by -whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb -[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that -this will be the case even if @code{\bb} is defined with zero or one -argument. -@end defopt - -@node Keymaps and Hooks, Changes, Options, Top -@section Keymaps and Hooks -@cindex Keymaps - -@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. - -@deffn Keymap reftex-mode-map -The keymap for @b{Ref@TeX{}} mode. -@end deffn - -@deffn {Normal Hook} reftex-load-hook -Normal hook which is being run when loading @file{reftex.el}. -@end deffn - -@deffn {Normal Hook} reftex-mode-hook -Normal hook which is being run when turning on @b{Ref@TeX{}} mode. -@end deffn - -Furthermore, the 4 modes used for referencing labels, creating -citations, the table of contents buffer and the phrases buffer have -their own keymaps and mode hooks. See the respective sections. There -are many more hooks which are described in the relevant sections about -options for a specific part of @b{Ref@TeX{}}. - -@node Changes, GNU Free Documentation License, Keymaps and Hooks, Top -@chapter Changes -@cindex Changes - -Here is a list of recent changes to @b{Ref@TeX{}}. - -@noindent @b{Version 4.28} -@itemize @bullet -@item Support for the Jurabib package. -@item Improvements when selecting several items in a selection buffer. -@end itemize - -@noindent @b{Version 4.26} -@itemize @bullet -@item -Support for global incremental search. -@item -Some improvements for XEmacs compatibility. -@end itemize - -@noindent @b{Version 4.25} -@itemize @bullet -@item -Fixed bug with @samp{%F} in a label prefix. Added new escapes -@samp{%m} and @samp{%M} for mater file name and master directory. -@end itemize - -@noindent @b{Version 4.24} -@itemize @bullet -@item -Inserting citation commands now prompts for optional arguments -when called with a prefix argument. Related new options are -@code{reftex-cite-prompt-optional-args} and -@code{reftex-cite-cleanup-optional-args}. -@item -New option @code{reftex-trust-label-prefix}. Configure this variable -if you'd like RefTeX to base its classification of labels on prefixes. -This can speed-up document parsing, but may in some cases reduce the -quality of the context used by RefTeX to describe a label. -@item -Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} -is non-nil. -@item -Fixed bugs in indexing: Case-sensitive search, quotes before and/or -after words. Disabled indexing in comment lines. -@end itemize - -@noindent @b{Version 4.22} -@itemize @bullet -@item -New command @code{reftex-create-bibtex-file} to create a new database -with all entries referenced in the current document. -@item -New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file -from entries marked in a citation selection buffer. -@end itemize - -@noindent @b{Version 4.21} -@itemize @bullet -@item -Renaming labels from the toc buffer with key @kbd{M-%}. -@end itemize - -@noindent @b{Version 4.20} -@itemize @bullet -@item -Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in -the TOC buffer promote/demote the section at point or all sections in -the current region. -@item -New option @code{reftex-toc-split-windows-fraction} to set the size of -the window used by the TOC. This makes the old variable -@code{reftex-toc-split-windows-horizontally-fraction} obsolete. -@item -A dedicated frame can show the TOC with the current section -always automatically highlighted. The frame is created and -deleted from the toc buffer with the @kbd{d} key. -@end itemize - -@noindent @b{Version 4.19} -@itemize @bullet -@item -New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current -section in the TOC buffer without selecting the TOC window. -@item -Recentering happens automatically in idle time when the option -@code{reftex-auto-recenter-toc} is turned on. -@item -Fixed several bugs related to automatic cursor positioning in the TOC -buffer. -@item -The highlight in the TOC buffer stays when the focus moves to a -different window. -@item -New command `reftex-goto-label'. -@item -Part numbers are no longer included in chapter numbers, and a new -part does not reset the chapter counter. See new option -@code{reftex-part-resets-chapter}. -@end itemize - -@noindent @b{Version 4.18} -@itemize @bullet -@item -@code{reftex-citation} uses the word before the cursor as a default -search string. -@item -Simplified several regular expressions for speed. -@item -Better support for chapterbib. -@end itemize - -@noindent @b{Version 4.17} -@itemize @bullet -@item -The toc window can be split off horizontally. See new options -@code{reftex-toc-split-windows-horizontally}, -@code{reftex-toc-split-windows-horizontally-fraction}. -@item -It is possible to specify a function which verifies an index match -during global indexing. See new option @code{reftex-index-verify-function}. -@item -The macros which input a file in LaTeX (like \input, \include) can -be configured. See new option @code{reftex-include-file-commands}. -@item -The macros which specify the bibliography file (like \bibliography) can -be configured. See new option @code{reftex-bibliography-commands}. -@item -The regular expression used to search for the \bibliography macro has -been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by -chapterbib. -@item -Small bug fixes. -@end itemize - -@noindent @b{Version 4.15} -@itemize @bullet -@item -Fixed bug with parsing of BibTeX files, when fields contain quotes or -unmatched parenthesis. -@item -Small bug fixes. -@item -Improved interaction with Emacs LaTeX mode. -@end itemize - -@noindent @b{Version 4.12} -@itemize @bullet -@item -Support for @file{bibentry} citation style. -@end itemize - -@noindent @b{Version 4.11} -@itemize @bullet -@item -Fixed bug which would parse @samp{\Section} just like @samp{\section}. -@end itemize - -@noindent @b{Version 4.10} -@itemize @bullet -@item -Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict -with @file{reftex-vars.el} on DOS machines. -@item -New options @code{reftex-parse-file-extension} and -@code{reftex-index-phrase-file-extension}. -@end itemize - -@noindent [.....] -@ignore -@noindent @b{Version 4.09} -@itemize @bullet -@item -New option @code{reftex-toc-max-level} to limit the depth of the toc. -New key binding @kbd{t} in the @file{*toc*} buffer to change this -setting. -@item -RefTeX maintains an @file{Index Phrases} file in which phrases can be -collected. When the document is ready, RefTeX can search all -these phrases and assist indexing all matches. -@item -The variables @code{reftex-index-macros} and -@code{reftex-index-default-macro} have changed their syntax slightly. -The @var{repeat} parameter has move from the latter to the former. -Also calls to @code{reftex-add-index-macros} from AUCTeX style files -need to be adapted. -@item -The variable @code{reftex-section-levels} no longer contains the -default stuff which has been moved to a constant. -@item -Environments like theorems can be placed into the TOC by putting -entries for @samp{"begin@{theorem@}"} in -@code{reftex-setion-levels}. -@end itemize - -@noindent @b{Version 4.06} -@itemize @bullet -@item -@code{reftex-section-levels} can contain a function to compute the level -of a sectioning command. -@item -Multiple @code{thebibliography} environments recognized. -@end itemize - -@noindent @b{Version 4.04} -@itemize @bullet -@item -New option @code{reftex-index-default-tag} implements a default for queries. -@end itemize - -@noindent @b{Version 4.02} -@itemize @bullet -@item -macros ending in @samp{refrange} are considered to contain references. -@item -Index entries made with @code{reftex-index-selection-or-word} in TeX -math mode automatically get enclosing @samp{$} to preserve math mode. See -new option @code{reftex-index-math-format}. Requires AUCTeX. -@end itemize - -@noindent @b{Version 4.01} -@itemize @bullet -@item -New command @code{reftex-index-globally} to index a word in many -places in the document. Also available from the index buffer with -@kbd{&}. -@item -The first item in a @code{reftex-label-alist} entry may now also be a parser -function to do non-standard parsing. -@item -@code{reftex-auto-view-crossref} no longer interferes with -@code{pop-up-frames} (patch from Stefan Monnier). -@end itemize - -@noindent @b{Version 4.00} -@itemize @bullet -@item -RefTeX has been split into several smaller files which are autoloaded on -demand. -@item -Index support, along with many new options. -@item -The selection of keys for @code{\ref} and @code{\cite} now allows to -select multiple items by marking entries with the @kbd{m} key. -@item -Fancyref support. -@end itemize - -@noindent @b{Version 3.43} -@itemize @bullet -@item -Viewing cross-references generalized. Now works on @code{\label}, -@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of -these, and from BibTeX buffers. -@item -New option @code{reftex-view-crossref-extra}. -@item -Support for the additional sectioning commands @code{\addchap} and -@code{\addsec} which are defined in the LaTeX KOMA-Script classes. -@item -Files in @code{reftex-default-bibliography} will be searched along -@code{BIBINPUTS} path. -@item -Reading a parse file now checks consistency. -@end itemize - -@noindent @b{Version 3.42} -@itemize @bullet -@item -File search further refined. New option @code{reftex-file-extensions}. -@item -@file{*toc*} buffer can show the file boundaries of a multifile -document, all labels and associated context. New keys @kbd{i}, @kbd{l}, -and @kbd{c}. New options @code{reftex-toc-include-labels}, -@code{reftex-toc-include-context}, -@code{reftex-toc-include-file-boundaries}. -@end itemize - -@noindent @b{Version 3.41} -@itemize @bullet -@item -New options @code{reftex-texpath-environment-variables}, -@code{reftex-use-external-file-finders}, -@code{reftex-external-file-finders}, -@code{reftex-search-unrecursed-path-first}. -@item -@emph{kpathsearch} support. See new options and -@code{reftex-bibpath-environment-variables}. -@end itemize - -@noindent @b{Version 3.38} -@itemize @bullet -@item -@code{reftex-view-crossref} no longer moves to find a macro. Point has -to be on the macro argument. -@end itemize - -@noindent @b{Version 3.36} -@itemize @bullet -@item -New value @code{window} for option @code{reftex-auto-view-crossref}. -@end itemize - -@noindent @b{Version 3.35} -@itemize @bullet -@item -ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. -This takes back the related changes in 3.34 for safety reasons. -@end itemize - -@noindent @b{Version 3.34} -@itemize @bullet -@item -Additional flag in @code{reftex-derive-label-parameters} do make only -lowercase labels (default @code{t}). -@item -All @file{.rel} files have a final newline to avoid queries. -@item -Single byte representations of accented European letters (ISO-8859-1) -are now valid in labels. -@end itemize - -@noindent @b{Version 3.33} -@itemize @bullet -@item -Multiple selection buffers are now hidden buffers (they start with a -SPACE). -@item -Fixed bug with file search when TEXINPUTS environment variable is empty. -@end itemize - -@noindent @b{Version 3.30} -@itemize @bullet -@item -In @code{reftex-citation}, the regular expression used to scan BibTeX -files can be specified using completion on known citation keys. -@item -New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} -entries. -@item -New command @code{reftex-renumber-simple-labels} to renumber simple -labels like @samp{eq:13} sequentially through a document. -@end itemize - -@noindent @b{Version 3.28} -@itemize @bullet -@item -Auto view crossref for XEmacs uses @code{post-command-hook} to restart the -timer, since itimer restart is not reliable. -@item -Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. -@item -Expansion of recursive tex and bib path rewritten. -@item -Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. -@item -Fixed bug with section numbering after *-red sections. -@end itemize - -@noindent @b{Version 3.27} -@itemize @bullet -@item -Macros can define @emph{neutral} labels, just like @code{\label} -itself. -@item -New option @code{reftex-allow-detached-macro-args}, default @code{nil}! -@end itemize - -@noindent @b{Version 3.26} -@itemize @bullet -@item -[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. -@item -New hooks @code{reftex-translate-to-ascii-function}, -@code{reftex-string-to-label-function}. -@item -Made sure automatic crossref display will not visit/scan files. -@end itemize - -@noindent @b{Version 3.25} -@itemize @bullet -@item -Echoing of citation info caches the info for displayed entries. -New option @code{reftex-cache-cite-echo}. -@item -@kbd{M-x reftex-reset-mode} now also removes the file with parsing -info. -@item -Default of @code{reftex-revisit-to-follow} changed to nil. -@end itemize - -@noindent @b{Version 3.24} -@itemize @bullet -@item -New option @code{reftex-revisit-to-echo}. -@item -Interface with X-Symbol (>=2.6) is now complete and stable. -@item -Adapted to new outline, which uses overlays. -@item -File names in @code{\bibliography} may now have the @code{.bib} -extension. -@item -Fixed Bug with parsing "single file" from master file buffer. -@end itemize - -@noindent @b{Version 3.23} -@itemize @bullet -@item -Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. -@item -@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse -file. -@item -The cursor inside a @code{\ref} or @code{\cite} macro can now trigger -automatic display of crossref information in the echo area. See -variable @code{reftex-auto-view-crossref}. -@item -AUCTeX interface updates: -@itemize @minus -@item -AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. -@item -@b{Ref@TeX{}} notifies AUCTeX about new labels. -@item -@code{TeX-arg-ref} no longer used (introduction was unnecessary). -@item -@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. -@item -Settings added to @b{Ref@TeX{}} via style files remain local. -@end itemize -@item -Fixed bug with @code{reftex-citation} in non-latex buffers. -@item -Fixed bug with syntax table and context refontification. -@item -Safety-net for name change of @code{font-lock-reference-face}. -@end itemize - -@noindent @b{Version 3.22} -@itemize @bullet -@item -Fixed bug with empty context strings. -@item -@code{reftex-mouse-view-crossref} is now bound by default at -@kbd{S-mouse-2}. -@end itemize - -@noindent @b{Version 3.21} -@itemize @bullet -@item -New options for all faces used by @b{Ref@TeX{}}. They're in the -customization group @code{reftex-fontification-configurations}. -@end itemize - -@noindent @b{Version 3.19} -@itemize @bullet -@item -Fixed bug with AUCTeX @code{TeX-master}. -@end itemize - -@noindent @b{Version 3.18} -@itemize @bullet -@item -The selection now uses a recursive edit, much like minibuffer input. -This removes all restrictions during selection. E.g. you can now -switch buffers at will, use the mouse etc. -@item -New option @code{reftex-highlight-selection}. -@item -@kbd{mouse-2} can be used to select in selection and @file{*toc*} -buffers. -@item -Fixed some problems regarding the interaction with VIPER mode. -@item -Follow-mode is now only used after point motion. -@item -@b{Ref@TeX{}} now finally does not fontify temporary files anymore. -@end itemize - -@noindent @b{Version 3.17} -@itemize @bullet -@item -Additional bindings in selection and @file{*toc*} buffers. @kbd{g} -redefined. -@item -New command @code{reftex-save-all-document-buffers}. -@item -Magic word matching made more intelligent. -@item -Selection process can switch to completion (with @key{TAB}). -@item -@code{\appendix} is now recognized and influences section numbering. -@item -File commentary shortened considerably (use Info documentation). -@item -New option @code{reftex-no-include-regexps} to skip some include files. -@item -New option @code{reftex-revisit-to-follow}. -@end itemize - -@noindent @b{Version 3.16} -@itemize @bullet -@item -New hooks @code{reftex-format-label-function}, -@code{reftex-format-ref-function}, @code{reftex-format-cite-function}. -@item -TeXInfo documentation completed. -@item -Some restrictions in Label inserting and referencing removed. -@item -New variable @code{reftex-default-bibliography}. -@end itemize - -@noindent @b{Version 3.14} -@itemize @bullet -@item -Selection buffers can be kept between selections: this is faster. -See new variable @code{reftex-use-multiple-selection-buffers}. -@item -Prefix interpretation of reftex-view-crossref changed. -@item -Support for the @code{varioref} package (@kbd{v} key in selection -buffer). -@end itemize - -@noindent @b{Version 3.12} -@itemize @bullet -@item -There are 3 new keymaps for customization: @code{reftex-toc-map}, -@code{reftex-select-label-map}, @code{reftex-select-bib-map}. -@item -Refontification uses more standard font-lock stuff. -@item -When no BibTeX database files are specified, citations can also use -@code{\bibitem} entries from a @code{thebibliography} environment. -@end itemize - -@noindent @b{Version 3.11} -@itemize @bullet -@item -Fixed bug which led to naked label in (e.g.) footnotes. -@item -Added scroll-other-window functions to RefTeX-Select. -@end itemize - -@noindent @b{Version 3.10} -@itemize @bullet -@item -Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. -@item -Removed unimportant code which caused OS/2 Emacs to crash. -@item -All customization variables now accessible from menu. -@end itemize - -@noindent @b{Version 3.07} -@itemize @bullet -@item -@code{Ref} menu improved. -@end itemize - -@noindent @b{Version 3.05} -@itemize @bullet -@item -Compatibility code now first checks for XEmacs feature. -@end itemize - -@noindent @b{Version 3.04} -@itemize @bullet -@item -Fixed BUG in the @emph{xr} support. -@end itemize - -@noindent @b{Version 3.03} -@itemize @bullet -@item -Support for the LaTeX package @code{xr}, for inter-document -references. -@item -A few (minor) Mule-related changes. -@item -Fixed bug which could cause @emph{huge} @file{.rel} files. -@item -Search for input and @file{.bib} files with recursive path definitions. -@end itemize - -@noindent @b{Version 3.00} -@itemize @bullet -@item -@b{Ref@TeX{}} should work better for very large projects: -@item -The new parser works without creating a master buffer. -@item -Rescanning can be limited to a part of a multifile document. -@item -Information from the parser can be stored in a file. -@item -@b{Ref@TeX{}} can deal with macros having a naked label as an argument. -@item -Macros may have white space and newlines between arguments. -@item -Multiple identical section headings no longer confuse -@code{reftex-toc}. -@item -@b{Ref@TeX{}} should work correctly in combination with buffer-altering -packages like outline, folding, x-symbol, iso-cvt, isotex, etc. -@item -All labeled environments discussed in @emph{The LaTeX Companion} by -Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of -@b{Ref@TeX{}}'s defaults. -@end itemize - -@noindent @b{Version 2.17} -@itemize @bullet -@item -Label prefix expands % escapes with current file name and other stuff. -@item -Citation format now with % escapes. This is not backward -compatible! -@item -TEXINPUTS variable recognized when looking for input files. -@item -Context can be the nth argument of a macro. -@item -Searching in the select buffer is now possible (@kbd{C-s} and -@kbd{C-r}). -@item -Display and derive-label can use two different context methods. -@item -AMSmath @code{xalignat} and @code{xxalignat} added. -@end itemize - -@noindent @b{Version 2.14} -@itemize @bullet -@item -Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with -AUCTeX. -@end itemize - -@noindent @b{Version 2.11} -@itemize @bullet -@item -Submitted for inclusion to Emacs and XEmacs. -@end itemize - -@noindent @b{Version 2.07} -@itemize @bullet -@item -New functions @code{reftex-search-document}, -@code{reftex-query-replace-document}. -@end itemize - -@noindent @b{Version 2.05} -@itemize @bullet -@item -Support for @file{custom.el}. -@item -New function @code{reftex-grep-document} (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 2.03} -@itemize @bullet -@item -@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to -default environments. -@item -@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). -@item -New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, -@code{reftex-arg-cite}. -@item -Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is -required. -@item -@code{reftex-add-to-label-alist} (to be called from AUCTeX style -files). -@item -Finding context with a hook function. -@item -Sorting BibTeX entries (new variable: -@code{reftex-sort-bibtex-matches}). -@end itemize - -@noindent @b{Version 2.00} -@itemize @bullet -@item -Labels can be derived from context (default for sections). -@item -Configuration of label insertion and label referencing revised. -@item -Crossref fields in BibTeX database entries. -@item -@code{reftex-toc} introduced (thanks to Stephen Eglen). -@end itemize - -@noindent @b{Version 1.09} -@itemize @bullet -@item -Support for @code{tex-main-file}, an analogue for -@code{TeX-master}. -@item -MS-DOS support. -@end itemize - -@noindent @b{Version 1.07} -@itemize @bullet -@item -@b{Ref@TeX{}} gets its own menu. -@end itemize - -@noindent @b{Version 1.05} -@itemize @bullet -@item -XEmacs port. -@end itemize - -@noindent @b{Version 1.04} -@itemize @bullet -@item -Macros as wrappers, AMSTeX support, delayed context parsing for -new labels. -@end itemize -@end ignore - -@noindent @b{Version 1.00} -@itemize @bullet -@item -released on 7 Jan 1997. -@end itemize - -@node GNU Free Documentation License, Index, Changes, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: 1e055774-0576-4b1b-b47f-550d0961fd43 -@end ignore diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi deleted file mode 100644 index ef6bce24f76..00000000000 --- a/doc/misc/remember.texi +++ /dev/null @@ -1,409 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/remember -@settitle Remember Manual -@syncodeindex fn cp -@c %**end of header - -@copying -This manual is for Remember Mode, version 1.9 - -Copyright @copyright{} 2001, 2004, 2005, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Remember: (remember). Simple information manager for Emacs -@end direntry - -@titlepage -@title Guide to Remember Mode -@subtitle a simple information manager -@subtitle for Emacs and XEmacs - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Preface, (dir), (dir) -@comment node-name, next, previous, up -@top Remember - -@insertcopying -@end ifnottex - -@menu -* Preface:: About the documentation. -* Introduction:: What is Remember Mode? -* Installation:: How to install Remember. -* Implementation:: How Remember came into existence. -* Quick Start:: Get started using Remember. -* Function Reference:: Interactive functions in remember.el. -* Keystrokes:: Keystrokes bound in Remember Mode. -* Backends:: Backends for saving notes. -* GNU Free Documentation License:: The license for this documentation. -* Concept Index:: Search for terms. - -@detailmenu - --- The Detailed Node Listing --- - -Backends - -* Text File:: Saving to a text file. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. - -@end detailmenu -@end menu - -@node Preface, Introduction, Top, Top -@comment node-name, next, previous, up -@chapter Preface - -This document describes remember-el, which was written by John Wiegley, -was once maintained by Sacha Chua, and is now maintained by the Emacs -developers. - -This document is a work in progress, and your contribution will be -greatly appreciated. - -@node Introduction, Installation, Preface, Top -@comment node-name, next, previous, up -@chapter Introduction - -Todo lists, schedules, phone databases... everything we use databases -for is really just a way to extend the power of our memory, to be able -to remember what our conscious mind may not currently have access to. - -There are many different databases out there---and good ones---which -this mode is not trying to replace. Rather, it's how that data gets -there that's the question. Most of the time, we just want to say -"Remember so-and-so's phone number, or that I have to buy dinner for the -cats tonight." That's the FACT. How it's stored is really the -computer's problem. But at this point in time, it's most definitely -also the user's problem, and sometimes so laboriously so that people -just let data slip, rather than expend the effort to record it. - -``Remember'' is a mode for remembering data. It uses whatever -back-end is appropriate to record and correlate the data, but its main -intention is to allow you to express as @emph{little} structure as -possible up front. If you later want to express more powerful -relationships between your data, or state assumptions that were at -first too implicit to be recognized, you can ``study'' the data later -and rearrange it. But the initial ``just remember this'' impulse -should be as close to simply throwing the data at Emacs as possible. - -Have you ever noticed that having a laptop to write on doesn't -@emph{actually} increase the amount of quality material that you turn -out, in the long run? Perhaps it's because the time we save -electronically in one way, we're losing electronically in another; the -tool should never dominate one's focus. As the mystic Faridu'd-Din -`Attar wrote: ``Be occupied as little as possible with things of the -outer world but much with things of the inner world; then right action -will overcome inaction.'' - -If Emacs could become a more intelligent data store, where brainstorming -would focus on the @emph{ideas} involved---rather than the structuring -and format of those ideas, or having to stop your current flow of work -in order to record them---it would map much more closely to how the mind -(well, at least mine) works, and hence would eliminate that very -manual-ness which computers from the very beginning have been championed -as being able to reduce. - -@node Installation, Implementation, Introduction, Top -@comment node-name, next, previous, up -@chapter Installation - -Installing Remember Mode is as simple as adding the following lines to -your Emacs configuration file (usually @file{~/.emacs.d/init.el} or -@file{~/.emacs}). - -@lisp -(add-to-list 'load-path "/path/to/remember") -(require 'remember) -@end lisp - -@node Implementation, Quick Start, Installation, Top -@comment node-name, next, previous, up -@chapter Implementation - -Hyperbole, as a data presentation tool, always struck me as being very -powerful, but it seemed to require a lot of ``front-end'' work before -that data was really available. The problem with BBDB, or keeping up -a Bibl-mode file, is that you have to use different functions to -record the data, and it always takes time to stop what you're doing, -format the data in the manner expected by that particular data -interface, and then resume your work. - -With ``remember'', you just hit @kbd{M-x remember} (you'd probably -want to bind this to an easily accessible keystroke, like @kbd{C-x -M-r}), slam in your text however you like, and then hit @kbd{C-c C-c}. -It will file the data away for later retrieval, and possibly indexing. - -Indexing is to data what ``studying'' is in the real world. What you do -when you study (or lucubrate, for some of us) is to realize certain -relationships implicit in the data, so that you can make use of those -relationships. Expressing that a certain quote you remembered was a -literary quote, and that you want the ability to pull up all quotes of a -literary nature, is what studying does. This is a more labor intensive -task than the original remembering of the data, and it's typical in real -life to set aside a special period of time for doing this work. - -``Remember'' works in the same way. When you enter data, either by -typing it into a buffer, or using the contents of the selected region, -it will store that data---unindexed, uninterpreted---in a data pool. -It will also try to remember as much context information as possible -(any text properties that were set, where you copied it from, when, -how, etc). Later, you can walk through your accumulated set of data -(both organized, and unorganized) and easily begin moving things -around, and making annotations that will express the full meaning of -that data, as far as you know it. - -Obviously this latter stage is more user-interface intensive, and it -would be nice if ``remember'' could do it as elegantly as possible, -rather than requiring a billion keystrokes to reorganize your -hierarchy. Well, as the future arrives, hopefully experience and user -feedback will help to make this as intuitive a tool as possible. - -@node Quick Start, Function Reference, Implementation, Top -@comment node-name, next, previous, up -@chapter Quick Start - -@itemize - -@item -Load @file{remember.el}. - -@item -Type @kbd{M-x remember}. The @samp{*Remember*} buffer should be -displayed. - -@item -Type in what you want to remember. The first line will be treated as -the headline, and the rest of the buffer will contain the body of the -note. - -@item -Type @kbd{C-c C-c} (@code{remember-finalize}) to save the note and close -the @samp{*Remember*} buffer. -@end itemize - -By default, @code{remember-finalize} saves the note in @file{~/.notes}. -You can edit it now to see the remembered and timestamped note. You -can edit this file however you want. New entries will always be added -to the end. - -To remember a region of text, use the universal prefix. @kbd{C-u M-x -remember} displays a @samp{*Remember*} buffer with the region as the -initial contents. - -As a simple beginning, you can start by using the Text File backend, -keeping your @file{~/.notes} file in outline-mode format, with a final -entry called @samp{* Raw data}. Remembered data will be added to the -end of the file. Every so often, you can move the data that gets -appended there into other files, or reorganize your document. - -You can also store remembered data in other backends. -(@pxref{Backends}) - -Here is one way to map the remember functions in your @file{.emacs} to -very accessible keystrokes facilities using the mode: - -@lisp -(autoload 'remember ``remember'' nil t) -(autoload 'remember-region ``remember'' nil t) - -(define-key global-map (kbd " r") 'remember) -(define-key global-map (kbd " R") 'remember-region) -@end lisp - -By default, remember uses the first annotation returned by -@code{remember-annotation-functions}. To include all of the annotations, -set @code{remember-run-all-annotation-functions-flag} to non-nil. - -@defopt remember-run-all-annotation-functions-flag -Non-nil means use all annotations returned by -@code{remember-annotation-functions}. -@end defopt - -You can write custom functions that use a different set of -remember-annotation-functions. For example: - -@lisp -(defun my/remember-with-filename () - "Always use the filename." - (interactive) - (let ((remember-annotation-functions '(buffer-file-name))) - (call-interactively 'remember))) -@end lisp - -@node Function Reference, Keystrokes, Quick Start, Top -@comment node-name, next, previous, up -@chapter Function Reference - -@file{remember.el} defines the following interactive functions: - -@defun remember initial -Remember an arbitrary piece of data. With a prefix, it will use the -region as @var{initial}. -@end defun - -@defun remember-region beg end -If called from within the remember buffer, @var{beg} and @var{end} are -ignored, and the entire buffer will be remembered. If called from any -other buffer, that region, plus any context information specific to -that region, will be remembered. -@end defun - -@defun remember-clipboard -Remember the contents of the current clipboard. This is most useful -for remembering things from Netscape or other X Windows applications. -@end defun - -@defun remember-finalize -Remember the contents of the current buffer. -@end defun - -@defun remember-mode -This enters the major mode for output from @command{remember}. This -buffer is used to collect data that you want remember. Just hit -@kbd{C-c C-c} when you're done entering, and it will go ahead and file -the data for latter retrieval, and possible indexing. -@end defun - -@node Keystrokes, Backends, Function Reference, Top -@comment node-name, next, previous, up -@chapter Keystroke Reference - -@file{remember.el} defines the following keybindings by default: - -@table @kbd - -@item C-c C-c (`remember-finalize') -Remember the contents of the current buffer. - -@item C-c C-k (`remember-destroy') -Destroy the current *Remember* buffer. - -@item C-x C-s (`remember-finalize') -Remember the contents of the current buffer. - -@end table - -@node Backends, GNU Free Documentation License, Keystrokes, Top -@comment node-name, next, previous, up -@chapter Backends - -You can save remembered notes to a variety of backends. - -@menu -* Text File:: Saving to a text file. -* Diary:: Saving to a Diary file. -* Mailbox:: Saving to a mailbox. -* Org:: Saving to an Org Mode file. -@end menu - -@node Text File, Diary, Backends, Backends -@comment node-name, next, previous, up -@section Saving to a Text File -@cindex text file, saving to - -@subheading Insinuation - -@lisp -(setq remember-handler-functions '(remember-append-to-file)) -@end lisp - -@subheading Options - -@defopt remember-data-file -The file in which to store unprocessed data. -@end defopt - -@defopt remember-leader-text -The text used to begin each remember item. -@end defopt - -@node Diary, Mailbox, Text File, Backends -@comment node-name, next, previous, up -@section Saving to a Diary file -@cindex diary, integration - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-diary-extract-entries) -@end lisp - -@subheading Options - -@defopt remember-diary-file -File for extracted diary entries. -If this is nil, then @code{diary-file} will be used instead." -@end defopt - -@node Mailbox, Org, Diary, Backends -@comment node-name, next, previous, up -@section Saving to a Mailbox -@cindex mailbox, saving to - -@subheading Insinuation - -@lisp -(add-to-list 'remember-handler-functions 'remember-store-in-mailbox) -@end lisp - -@subheading Options - -@defopt remember-mailbox -The file in which to store remember data as mail. -@end defopt - -@defopt remember-default-priority -The default priority for remembered mail messages. -@end defopt - -@node Org, , Mailbox, Backends -@comment node-name, next, previous, up -@section Saving to an Org Mode file -@cindex org mode, integration - -For instructions on how to integrate Remember with Org Mode, -consult @ref{Remember, , , org}. - -@node GNU Free Documentation License, Concept Index, Backends, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Index - -@printindex cp - -@bye - -@ignore - arch-tag: 5b980db0-20cc-4167-b845-52dc11d53b9f -@end ignore diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi deleted file mode 100644 index b7873025318..00000000000 --- a/doc/misc/sasl.texi +++ /dev/null @@ -1,273 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/sasl - -@set VERSION 0.2 -@settitle Emacs SASL Library @value{VERSION} - -@copying -This file describes the Emacs SASL library, version @value{VERSION}. - -Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License'' -in the Emacs manual. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' - -This document is part of a collection distributed under the GNU Free -Documentation License. If you want to distribute this document -separately from the collection, you can do so by adding a copy of the -license to the document, as described in section 6 of the license. -@end quotation -@end copying - -@dircategory Emacs -@direntry -* SASL: (sasl). The Emacs SASL library. -@end direntry - - -@titlepage -@title Emacs SASL Library @value{VERSION} - -@author by Daiki Ueno -@page - -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - - -@node Top -@top Emacs SASL - -SASL is a common interface to share several authentication mechanisms between -applications using different protocols. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Overview:: What Emacs SASL library is. -* How to use:: Adding authentication support to your applications. -* Data types:: -* Back end drivers:: Writing your own drivers. -* Index:: -* Function Index:: -* Variable Index:: -@end menu - -@node Overview -@chapter Overview - -@sc{sasl} is short for @dfn{Simple Authentication and Security Layer}. -This standard is documented in RFC2222. It provides a simple method for -adding authentication support to various application protocols. - -The toplevel interface of this library is inspired by Java @sc{sasl} -Application Program Interface. It defines an abstraction over a series -of authentication mechanism drivers (@ref{Back end drivers}). - -Back end drivers are designed to be close as possible to the -authentication mechanism. You can access the additional configuration -information anywhere from the implementation. - -@node How to use -@chapter How to use - -(Not yet written). - -To use Emacs SASL library, please evaluate following expression at the -beginning of your application program. - -@lisp -(require 'sasl) -@end lisp - -If you want to check existence of sasl.el at runtime, instead you -can list autoload settings for functions you want. - -@node Data types -@chapter Data types - -There are three data types to be used for carrying a negotiated -security layer---a mechanism, a client parameter and an authentication -step. - -@menu -* Mechanisms:: -* Clients:: -* Steps:: -@end menu - -@node Mechanisms -@section Mechanisms - -A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} -authentication mechanism driver. - -@defvar sasl-mechanisms -A list of mechanism names. -@end defvar - -@defun sasl-find-mechanism mechanisms - -Retrieve an appropriate mechanism. -This function compares @var{mechanisms} and @code{sasl-mechanisms} then -returns appropriate @code{sasl-mechanism} object. - -@example -(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) - (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) -@end example - -@end defun - -@defun sasl-mechanism-name mechanism -Return name of mechanism, a string. -@end defun - -If you want to write an authentication mechanism driver (@ref{Back end -drivers}), use @code{sasl-make-mechanism} and modify -@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly. - -@defun sasl-make-mechanism name steps -Allocate a @code{sasl-mechanism} object. -This function takes two parameters---name of the mechanism, and a list -of authentication functions. - -@example -(defconst sasl-anonymous-steps - '(identity ;no initial response - sasl-anonymous-response)) - -(put 'sasl-anonymous 'sasl-mechanism - (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) -@end example - -@end defun - -@node Clients -@section Clients - -A client (@code{sasl-client} object) initialized with four -parameters---a mechanism, a user name, name of the service and name of -the server. - -@defun sasl-make-client mechanism name service server -Prepare a @code{sasl-client} object. -@end defun - -@defun sasl-client-mechanism client -Return the mechanism (@code{sasl-mechanism} object) of client. -@end defun - -@defun sasl-client-name client -Return the authorization name of client, a string. -@end defun - -@defun sasl-client-service client -Return the service name of client, a string. -@end defun - -@defun sasl-client-server client -Return the server name of client, a string. -@end defun - -If you want to specify additional configuration properties, please use -@code{sasl-client-set-property}. - -@defun sasl-client-set-property client property value -Add the given property/value to client. -@end defun - -@defun sasl-client-property client property -Return the value of the property of client. -@end defun - -@defun sasl-client-set-properties client plist -Destructively set the properties of client. -The second argument is the new property list. -@end defun - -@defun sasl-client-properties client -Return the whole property list of client configuration. -@end defun - -@node Steps -@section Steps - -A step (@code{sasl-step} object) is an abstraction of authentication -``step'' which holds the response value and the next entry point for the -authentication process (the latter is not accessible). - -@defun sasl-step-data step -Return the data which @var{step} holds, a string. -@end defun - -@defun sasl-step-set-data step data -Store @var{data} string to @var{step}. -@end defun - -To get the initial response, you should call the function -@code{sasl-next-step} with the second argument @code{nil}. - -@example -(setq name (sasl-mechanism-name mechanism)) -@end example - -At this point we could send the command which starts a SASL -authentication protocol exchange. For example, - -@example -(process-send-string - process - (if (sasl-step-data step) ;initial response - (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t)) - (format "AUTH %s\r\n" name))) -@end example - -To go on with the authentication process, all you have to do is call -@code{sasl-next-step} consecutively. - -@defun sasl-next-step client step -Perform the authentication step. -At the first time @var{step} should be set to @code{nil}. -@end defun - -@node Back end drivers -@chapter Back end drivers - -(Not yet written). - -@node Index -@chapter Index -@printindex cp - -@node Function Index -@chapter Function Index -@printindex fn - -@node Variable Index -@chapter Variable Index -@printindex vr - -@summarycontents -@contents -@bye - -@c End: - -@ignore - arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875 -@end ignore diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi deleted file mode 100644 index 979cff23ca7..00000000000 --- a/doc/misc/sc.texi +++ /dev/null @@ -1,1946 +0,0 @@ -\input texinfo @comment -*-texinfo-*- -@comment 3.48 -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename ../../info/sc -@settitle Supercite User's Manual -@iftex -@finalout -@end iftex - -@c @setchapternewpage odd % For book style double sided manual. -@comment %**end of header (This is for running Texinfo on a region.) - -@copying -This document describes Supercite, an Emacs package for citing and -attributing replies to mail and news messages. - -Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c @smallbook - -@dircategory Emacs -@direntry -* SC: (sc). Supercite lets you cite parts of messages you're - replying to, in flexible ways. -@end direntry - -@titlepage -@title Supercite User's Manual -@subtitle cite and attribute mail and -@subtitle news, in flexible ways - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@insertcopying - -The manual is divided -into the following chapters. - -@menu -* Introduction:: -* Citations:: -* Getting Connected:: -* Replying and Yanking:: -* Selecting an Attribution:: -* Configuring the Citation Engine:: -* Post-yank Formatting Commands:: -* Information Keys and the Info Alist:: -* Reference Headers:: -* Hints to MUA Authors:: -* Thanks and History:: - -* GNU Free Documentation License:: -* Concept Index:: -* Command Index:: -* Key Index:: -* Variable Index:: -@end menu -@end ifnottex - - -@node Introduction, Usage Overview, Top, Top -@chapter Introduction - -Supercite is a GNU Emacs package written entirely in Emacs Lisp. It -interfaces to most of the commonly used Emacs mail user agents -(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides -sophisticated facilities for the citing and attributing of message -replies. Supercite has a very specific and limited role in the process -of composing replies to both USENET network news and electronic mail. - -The preferred way to spell Supercite is with a capital @samp{S}, -lowercase @samp{upercite}. - -@ifinfo -@menu -* Usage Overview:: -* What Supercite Does Not Do:: -* What Supercite Does:: -@end menu -@end ifinfo - -@cindex MUA -@cindex NUA -Supercite is only useful in conjunction with MUAs and NUAs such as VM, -Gnus, RMAIL, MH-E, etc. Supercite is typically called by the MUA after a -reply buffer has been setup. Thereafter, Supercite's many commands and -formatting styles are available in that reply buffer until the reply is -sent. Supercite is re-initialized in each new reply buffer. - - -@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction -@kindex r -@kindex f -@kindex C-c C-y -@cindex yank -@cindex cite, citing -@cindex attribute, attributing -@section Usage Overview - -Typical usage is as follows. You want to reply or followup to a message -in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} -(i.e., ``forward'') to begin composing the reply. In response, the MUA -will create a reply buffer and initialize the outgoing mail headers -appropriately. The body of the reply will usually be empty at this -point. You now decide that you would like to include part of the -original message in your reply. To do this, you @dfn{yank} the original -message into the reply buffer, typically with a key stroke such as -@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which -fills the body of the reply with the original message and then -@dfn{attributes} this text to its author. This is called @dfn{citing} -and its effect is to prefix every line from the original message with a -special text tag. Most MUAs provide some default style of citing; by -using Supercite you gain a wider flexibility in the look and style of -citations. Supercite's only job is to cite the original message. - -@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction -@section What Supercite Doesn't Do - -Because of this clear division of labor, there are useful features which -are the sole responsibility of the MUA, even though it might seem that -Supercite should provide them. For example, many people would like to -be able to yank (and cite) only a portion of the original message. -Since Supercite only modifies the text it finds in the reply buffer as -set up by the MUA, it is the MUA's responsibility to do partial yanking. -@xref{Reply Buffer Initialization}.@refill - -@vindex mail-header-separator -Another potentially useful thing would be for Supercite to set up the -outgoing mail headers with information it gleans from the reply buffer. -But by previously agreed upon convention, any text above the -@code{mail-header-separator} which separates mail headers from message -bodies cannot be modified by Supercite. Supercite, in fact, doesn't -know anything about the meaning of these headers, and never ventures -outside the designated region. @xref{Hints to MUA Authors}, for more -details.@refill - -@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction -@findex sc-cite-original -@section What Supercite Does - -Supercite is invoked for the first time on a reply buffer via your MUA's -reply or forward command. This command will actually perform citations -by calling a hook variable to which Supercite's top-level function -@code{sc-cite-original} has been added. When @code{sc-cite-original} is -executed, the original message must be set up in a very specific way, -but this is handled automatically by the MUA. @xref{Hints to MUA -Authors}.@refill - -@cindex info alist -The first thing Supercite does, via @code{sc-cite-original}, is to parse -through the original message's mail headers. It saves this data in an -@dfn{information association list}, or @dfn{info alist}. The information -in this list is used in a number of places throughout Supercite. -@xref{Information Keys and the Info Alist}.@refill - -@cindex nuking mail headers -@cindex reference header -After the mail header info is extracted, the headers are optionally -removed (@dfn{nuked}) from the reply. Supercite then writes a -@dfn{reference header} into the buffer. This reference header is a -string carrying details about the citation it is about to perform. - -@cindex modeline -Next, Supercite visits each line in the reply, transforming the line -according to a customizable ``script.'' Lines which were not previously -cited in the original message are given a citation, while already cited -lines remain untouched, or are coerced to your preferred style. -Finally, Supercite installs a keymap into the reply buffer so that you -have access to Supercite's post-yank formatting and reciting commands as -you subsequently edit your reply. You can tell that Supercite has been -installed into the reply buffer because that buffer's modeline will -display the minor mode string @samp{SC}. - -@cindex filladapt -@cindex gin-mode -@vindex fill-prefix -@findex fill-paragraph -When the original message is cited by @code{sc-cite-original}, it will -(optionally) be filled by Supercite. However, if you manually edit the -cited text and want to re-fill it, you must use an add-on package such -as @cite{filladapt} or @cite{gin-mode}. These packages can recognize -Supercited text and will fill them appropriately. Emacs' built-in -filling routines, e.g@. @code{fill-paragraph}, do not recognize cited -text and will not re-fill them properly because it cannot guess the -@code{fill-prefix} being used. -@xref{Post-yank Formatting Commands}, for details.@refill - -As mentioned above, Supercite provides commands to recite or uncite -regions of text in the reply buffer, and commands to perform other -beautifications on the cited original text, maintaining consistent and -informative citations throughout. Supercite tries to be as configurable -as possible to allow for a wide range of personalized citation styles, -but it is also immediately useful with the default configuration, once -it has been properly connected to your MUA. @xref{Getting Connected}, -for more details.@refill - -@node Citations, Citation Elements, What Supercite Does, Top -@cindex nested citations -@cindex citation -@chapter Citations - -A @dfn{citation} is the acknowledgement of the original author of a mail -message in the body of the reply. There are two basic citation styles -which Supercite supports. The first, called @dfn{nested citations} is -an anonymous form of citation; in other words, an indication is made -that the cited line was written by someone @emph{other} that the current -message author (i.e., other than you, the person composing the reply), -but no reference is made as to the identity of the original author. -This style should look familiar since its use on the net is widespread. -Here's an example of what a message buffer would look like using nested -citations after multiple replies: - -@example ->> John originally wrote this ->> and this as well -> Jane said that John didn't know -> what he was talking about -And that's what I think too. -@end example - -@ifinfo -@menu -* Citation Elements:: -* Recognizing Citations:: -@end menu -@end ifinfo - -Note that multiple inclusions of the original messages result in a -nesting of the @samp{@code{>}} characters. This can sometimes be quite -confusing when many levels of citations are included since it may be -difficult or impossible to figure out who actually participated in the -thread, and multiple nesting of @samp{@code{>}} characters can sometimes -make the message very difficult for the eye to scan. - -@cindex non-nested citations -In @dfn{non-nested citations}, each cited line begins with an -informative string attributing that line to the original author. Only -the first level of attribution will be shown; subsequent citations don't -nest the citation strings. The above dialog might look like this when -non-nested citations are used: - -@example -John> John originally wrote this -John> and this as well -Jane> Jane said that John didn't know -Jane> what he was talking about -And that's what I think too. -@end example - -Notice here that my inclusion of Jane's inclusion of John's original -message did not result in a line cited with @samp{Jane>John>}. - -@vindex sc-nested-citation-p -@vindex nested-citation-p (sc-) -Supercite supports both styles of citation, and the variable -@code{sc-nested-citation-p} controls which style it will use when citing -previously uncited text. When this variable is @code{nil} (the default), -non-nested citations are used. When non-@code{nil}, nested citations -are used. - - -@node Citation Elements, Recognizing Citations, Citations, Citations -@cindex citation string -@section Citation Elements - -@dfn{Citation strings} are composed of one or more elements. Non-nested -citations are composed of four elements, three of which are directly -user definable. The elements are concatenated together, in this order: - -@cindex citation leader -@vindex citation-leader (sc-) -@vindex sc-citation-leader -@enumerate -@item -The @dfn{citation leader}. The citation leader is contained in the -variable @code{sc-citation-leader}, and has the default value of a -string containing four spaces. - -@cindex attribution string -@item -The @dfn{attribution string}. This element is supplied automatically by -Supercite, based on your preferences and the original message's mail -headers, though you may be asked to confirm Supercite's choice. -@xref{Selecting an Attribution}, for more details.@refill - -@cindex citation delimiter -@vindex sc-citation-delimiter -@vindex citation-delimiter (sc-) -@item -The @dfn{citation delimiter}. This string, contained in the variable -@code{sc-citation-delimiter} visually separates the citation from the -text of the line. This variable has a default value of @code{">"} and -for best results, the string should consist of only a single character. - -@cindex citation separator -@vindex citation-separator (sc-) -@vindex sc-citation-separator -@item -The @dfn{citation separator}. The citation separator is contained in -the variable @code{sc-citation-separator}, and has the default value of -a string containing a single space. -@end enumerate - -For example, suppose you were using the default values for the above -variables, and Supercite provided the attribution string @samp{Jane}. -In this case, the composed, non-nested citation string used might be -something like -@code{@asis{" Jane> "}}. -This citation string will be inserted in front of -every line in the original message that is not already cited.@refill - -Nested citations, being simpler than non-nested citations, are composed -of the same elements, sans the attribution string. Supercite is smart -enough to not put additional spaces between citation delimiters for -multi-level nested citations. - -@node Recognizing Citations, Getting Connected, Citation Elements, Citations -@section Recognizing Citations - -Supercite also recognizes citations in the original article, and can -transform these already cited lines in a number of ways. This is how -Supercite suppresses the multiple citing of non-nested citations. -Recognition of cited lines is controlled by variables analogous to those -that make up the citation string as mentioned previously. - -@vindex sc-citation-leader-regexp -@vindex citation-leader-regexp (sc-) -@vindex sc-citation-delimiter-regexp -@vindex citation-delimiter-regexp (sc-) -@vindex sc-citation-separator-regexp -@vindex citation-separator-regexp (sc-) -@vindex sc-citation-root-regexp -@vindex citation-root-regexp (sc-) -@vindex sc-citation-nonnested-root-regexp -@vindex citation-nonnested-root-regexp (sc-) - -The variable @code{sc-citation-leader-regexp} describes how citation -leaders can look, by default it matches any number of spaces or tabs. -Note that since the lisp function @code{looking-at} is used to do the -matching, if you change this variable it need not start with a leading -@code{"^"}. - -Similarly, the variables @code{sc-citation-delimiter-regexp} and -@code{sc-citation-separator-regexp} respectively describe how citation -delimiters and separators can look. They follow the same rule as -@code{sc-citation-leader-regexp} above. - -When Supercite composes a citation string, it provides the attribution -automatically. The analogous variable which handles recognition of the -attribution part of citation strings is @code{sc-citation-root-regexp}. -This variable describes the attribution root for both nested and -non-nested citations. By default it can match zero-to-many alphanumeric -characters (also ``.'', ``-'', and ``_''). But in some situations, -Supercite has to determine whether it is looking at a nested or -non-nested citation. Thus the variable -@code{sc-citation-nonnested-root-regexp} is used to describe only -non-nested citation roots. It is important to remember that if you -change @code{sc-citation-root-regexp} you should always also change -@code{sc-citation-nonnested-root-regexp}.@refill - -@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top -@cindex information keys -@cindex Info Alist -@cindex information extracted from mail fields -@findex sc-mail-field -@findex mail-field (sc-) -@chapter Information Keys and the Info Alist - -@dfn{Mail header information keys} are nuggets of information that -Supercite extracts from the various mail headers of the original -message, placed in the reply buffer by the MUA. Information is kept in -the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in -various places within Supercite, such as in header rewrite functions and -attribution selection. Other bits of data, composed and created by -Supercite, are also kept as key-value pairs in this alist. In the case -of mail fields, the key is the name of the field, omitting the trailing -colon. Info keys are always case insensitive (as are mail headers), and -the value for a corresponding key can be retrieved from the alist with -the @code{sc-mail-field} function. Thus, if the following fields were -present in the original article:@refill - -@example -Date:@: 08 April 1991, 17:32:09 EST -Subject:@: Better get out your asbestos suit -@end example - -@vindex sc-mumble -@vindex mumble (sc-) -@noindent -then, the following lisp constructs return: - -@example -(sc-mail-field "date") -==> "08 April 1991, 17:32:09 EST" - -(sc-mail-field "subject") -==> "Better get out your asbestos suit" -@end example - -Since the argument to @code{sc-mail-field} can be any string, it is -possible that the mail field will not be present on the info alist -(possibly because the mail header was not present in the original -message). In this case, @code{sc-mail-field} will return the value of -the variable @code{sc-mumble}. - -Supercite always places all mail fields found in the yanked original -article into the info alist. If possible, Supercite will also places -the following keys into the info alist: - -@table @code -@cindex sc-attribution info field -@cindex attribution info field (sc-) -@item "sc-attribution" -the selected attribution string. - -@cindex sc-citation info field -@cindex citation info field (sc-) -@item "sc-citation" -the non-nested citation string. - -@cindex sc-from-address info field -@cindex from-address info field (sc-) -@item "sc-from-address" -email address extracted from the @samp{From:@:} field. - -@cindex sc-reply-address info field -@cindex reply-address info field (sc-) -@item "sc-reply-address" -email address extracted from the @samp{Reply-To:@:} field. - -@cindex sc-sender-address info field -@cindex sender-address info field (sc-) -@item "sc-sender-address" -email address extracted from the @samp{Sender:@:} field. - -@cindex sc-emailname info field -@cindex emailname info field (sc-) -@item "sc-emailname" -email terminus extracted from the @samp{From:@:} field. - -@cindex sc-initials info field -@cindex initials info field (sc-) -@item "sc-initials" -the author's initials. - -@cindex sc-author info field -@cindex author info field (sc-) -@item "sc-author" -the author's full name. - -@cindex sc-firstname info field -@cindex firstname info field (sc-) -@item "sc-firstname" -the author's first name. - -@cindex sc-lastname info field -@cindex lastname info field (sc-) -@item "sc-lastname" -the author's last name. - -@cindex sc-middlename-1 info field -@cindex middlename-1 info field (sc-) -@item "sc-middlename-1" -the author's first middle name. -@end table - -If the author's name has more than one middle name, they will appear as -info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, -@dots{}). @xref{Selecting an Attribution}.@refill - -@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top -@cindex reference headers -@chapter Reference Headers - -Supercite will insert an informative @dfn{reference header} at the -beginning of the cited body of text, which display more detail about the -original article and provides the mapping between the attribution and -the original author in non-nested citations. Whereas the citation -string usually only contains a portion of the original author's name, -the reference header can contain such information as the author's full -name, email address, the original article's subject, etc. In fact any -information contained in the info alist can be inserted into a reference -header. - -@ifinfo -@menu -* The Built-in Header Rewrite Functions:: -* Electric References:: -@end menu -@end ifinfo - -@cindex header rewrite functions -@vindex sc-rewrite-header-list -@vindex rewrite-header-list (sc-) -There are a number of built-in @dfn{header rewrite functions} supplied -by Supercite, but you can write your own custom header rewrite functions -(perhaps using the built-in ones as examples). The variable -@code{sc-rewrite-header-list} contains the list of such header rewrite -functions. This list is consulted both when inserting the initial -reference header, and when displaying @dfn{electric references}. -@xref{Electric References}. - -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -When Supercite is initially run on a reply buffer (via -@code{sc-cite-original}), it will automatically call one of these -functions. The one it uses is defined in the variable -@code{sc-preferred-header-style}. The value of this variable is an -integer which is an index into the @code{sc-rewrite-header-list}, -beginning at zero. - -@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers -@cindex header rewrite functions, built-in -@section The Built-in Header Rewrite Functions - -Below are examples of the various built-in header rewrite functions. -Please note the following:@: first, the text which appears in the -examples below as @var{infokey} indicates that the corresponding value -of the info key from the info alist will be inserted there. -(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} -below, @var{date} and @var{from} correspond to the values of the -@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill - -@vindex sc-reference-tag-string -@vindex reference-tag-string (sc-) -Also, the string @code{">>>>>"} below is really the value of the -variable @code{sc-reference-tag-string}. This variable is used in all -built-in header rewrite functions, and you can customize its value to -change the tag string globally. - -Finally, the references headers actually written may omit certain parts -of the header if the info key associated with @var{infokey} is not -present in the info alist. In fact, for all built-in headers, if the -@samp{From:@:} field is not present in the mail headers, the entire -reference header will be omitted (but this usually signals a serious -problem either in your MUA or in Supercite's installation). - -@table @code -@findex sc-no-header -@findex no-header (sc-) -@item sc-no-header -This function produces no header. It should be used instead of -@code{nil} to produce a blank header. This header can possibly contain -a blank line after the @code{mail-header-separator} line. - -@item sc-no-blank-line-or-header -@findex sc-no-blank-line-or-header -@findex no-blank-line-or-header (sc-) -This function is similar to @code{sc-no-header} except that any blank -line after the @code{mail-header-separator} line will be removed. - -@item sc-header-on-said -@findex sc-header-on-said -@findex header-on-said (sc-) -@code{>>>>> On @var{date}, @var{from} said:} - -@item sc-header-inarticle-writes -@findex sc-header-inarticle-writes -@findex header-inarticle-writes (sc-) -@code{>>>>> In article @var{message-id}, @var{from} writes:} - -@item sc-header-regarding-adds -@findex sc-header-regarding-adds -@findex header-regarding-adds (sc-) -@code{>>>>> Regarding @var{subject}; @var{from} adds:} - -@item sc-header-attributed-writes -@findex sc-header-attributed-writes -@findex header-attributed-writes (sc-) -@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:} - -@item sc-header-author-writes -@findex sc-header-author-writes -@findex header-author-writes (sc-) -@code{>>>>> @var{sc-author} writes:} - -@item sc-header-verbose -@findex sc-header-verbose -@findex header-verbose (sc-) -@code{>>>>> On @var{date},}@* -@code{>>>>> @var{sc-author}}@* -@code{>>>>> from the organization of @var{organization}}@* -@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@* -@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@* -@code{>>>>> had this to say in article @var{message-id}}@* -@code{>>>>> in newsgroups @var{newsgroups}}@* -@code{>>>>> concerning the subject of @var{subject}}@* -@code{>>>>> see @var{references} for more details} -@end table - -@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers -@cindex electric references -@section Electric References - -By default, when Supercite cites the original message for the first -time, it just goes ahead and inserts the reference header indexed by -@code{sc-preferred-header-style}. However, you may want to select -different reference headers based on the type of reply or forwarding you -are doing. You may also want to preview the reference header before -deciding whether to insert it into the reply buffer or not. Supercite -provides an optional @dfn{electric reference} mode which you can drop -into to give you this functionality. - -@vindex sc-electric-references-p -@vindex electric-references-p (sc-) -If the variable @code{sc-electric-references-p} is non-@code{nil}, -Supercite will bring up an electric reference mode buffer and place you -into a recursive edit. The electric reference buffer is read-only, so -you cannot directly modify the reference text until you exit electric -references and insert the text into the reply buffer. But you can cycle -through all the reference header rewrite functions in your -@code{sc-rewrite-header-list}. - -You can also set a new preferred header style, jump to any header, or -jump to the preferred header. The header will be shown in the electric -reference buffer and the header index and function name will appear in -the echo area. - -The following commands are available while in electric reference mode -(shown here with their default key bindings): - -@table @asis -@item @code{sc-eref-next} (@kbd{n}) -@findex sc-eref-next -@findex eref-next (sc-) -@kindex n -@vindex sc-electric-circular-p -@vindex electric-circular-p (sc-) -Displays the next reference header in the electric reference buffer. If -the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking -@code{sc-eref-next} while viewing the last reference header in the list -will wrap around to the first header.@refill - -@item @code{sc-eref-prev} (@kbd{p}) -@findex sc-eref-prev -@findex eref-prev (sc-) -@kindex p -Displays the previous reference header in the electric reference buffer. -If the variable @code{sc-electric-circular-p} is non-@code{nil}, -invoking @code{sc-eref-prev} will wrap around to the last header.@refill - -@item @code{sc-eref-goto} (@kbd{g}) -@findex sc-eref-goto -@findex eref-goto (sc-) -@kindex g -Goes to a specified reference header. The index (into the -@code{sc-rewrite-header-list}) can be specified as a numeric argument to -the command. Otherwise, Supercite will query you for the index in the -minibuffer.@refill - -@item @code{sc-eref-jump} (@kbd{j}) -@findex sc-eref-jump -@findex eref-jump (sc-) -@kindex j -Display the preferred reference header, i.e., the one indexed by the current -value of @code{sc-preferred-header-style}. - -@item @code{sc-eref-setn} (@kbd{s}) -@findex sc-eref-setn -@findex eref-setn (sc-) -@kindex s -Set the preferred reference header (i.e., -@code{sc-preferred-header-style}) to the currently displayed header.@refill - -@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) -@kindex RET -@kindex C-j -@kindex q -@findex sc-eref-exit -@findex eref-exit (sc-) -Exit from electric reference mode and insert the current header into the -reply buffer.@refill - -@item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) -@findex sc-eref-abort -@findex eref-abort (sc-) -@kindex x -Exit from electric reference mode without inserting the current header. -@end table - -@vindex sc-electric-mode-hook -@vindex electric-mode-hook (sc-) -@noindent -Supercite will execute the hook @code{sc-electric-mode-hook} before -entering electric reference mode. - -@node Getting Connected, Replying and Yanking, Recognizing Citations, Top -@cindex citation interface specification -@chapter Getting Connected - - -@vindex mail-citation-hook -@cindex .emacs file -In most cases, all that is necessary to begin using Supercite is to add -the following to @file{~.emacs}: - -@example -(add-hook 'mail-citation-hook 'sc-cite-original) -@end example - -@noindent For more details of the process, read on@dots{} - -Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the -original message into the reply buffer. In reality, the citation of the -original message is performed via a call through a configurable hook -variable. The name of this variable has been agreed to in advance as -part of the @dfn{citation interface specification}. By default this -hook variable has a @code{nil} value, which the MUA recognizes to mean, -``use your default citation function.'' When you add Supercite's -citation function to the hook, thereby giving the variable a -non-@code{nil} value, it tells the MUA to run the hook via -@code{run-hooks} instead of using the default citation.@refill - -Early in Supercite's development, the Supercite author, a few MUA -authors, and some early Supercite users got together and agreed upon a -standard interface between MUAs and citation packages (of which -Supercite is currently the only known add-on @t{:-)}. Supercite can -probably be used with most Emacs MUAs, with a greater or lesser degree -of effort. - -To learn exactly how to connect Supercite to the software systems you -are using, read the appropriate following sections. For details on the -interface specifications, or if you are writing or maintaining an MUA, -@pxref{Hints to MUA Authors}. - -@cindex autoload -@cindex .emacs file -@findex sc-cite-original -@findex cite-original (sc-) -@findex sc-submit-bug-report -@findex submit-bug-report (sc-) -The first thing that everyone should do, regardless of the MUA you are -using is to set up Emacs so it will load Supercite at the appropriate -time. This happens automatically if Supercite is distributed with your -Emacs version. If not, you can set up an @dfn{autoload} for Supercite. - -To do the latter, put the following in your @file{.emacs} file: - -@example -(autoload 'sc-cite-original "supercite" nil t) -@end example - -@cindex point -@cindex mark -The function @code{sc-cite-original} is the top-level Supercite function -designed to be run from the citation hook. It expects -@samp{point} and @samp{mark} to be set around the region to cite, and it -expects the original article's mail headers to be present within this -region. Note that Supercite @emph{never} touches any text outside this -region. Note further that the region need not be active -for @code{sc-cite-original} to do its job. -@xref{Hints to MUA Authors}.@refill - -The other step in the getting connected process is to make sure your -MUA calls @code{sc-cite-original} at the right time. As mentioned -above, some MUAs handle this differently. Read the sections that follow -pertaining to the MUAs you are using. - -@vindex sc-load-hook -@vindex load-hook (sc-) -@vindex sc-pre-hook -@vindex pre-hook (sc-) -One final note. After Supercite is loaded into your Emacs session, it -runs the hook @code{sc-load-hook}. You can put any customizations into -this hook since it is only run once. This will not work, however, if -your Emacs maintainer has put Supercite into your dumped Emacs' image. -In that case, you can use the @code{sc-pre-hook} variable, but this will -get executed every time @code{sc-cite-original} is called. @xref{Reply -Buffer Initialization}.@refill - -@node Replying and Yanking, Reply Buffer Initialization, Getting Connected, Top -@chapter Replying and Yanking -@ifinfo - -This chapter explains what happens when you reply and yank an original -message from an MUA. - -@menu -* Reply Buffer Initialization:: -* Filling Cited Text:: -@end menu -@end ifinfo -@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking -@findex sc-cite-original -@findex cite-original (sc-) -@section Reply Buffer Initialization - -Executing @code{sc-cite-original} performs the following steps as it -initializes the reply buffer: - -@enumerate -@item -@vindex sc-pre-hook -@vindex pre-hook (sc-) -@emph{Runs @code{sc-pre-hook}.} -This hook variable is run before @code{sc-cite-original} does any other -work. You could conceivably use this hook to set certain Supercite -variables based on the reply buffer's mode or name (i.e., to do -something different based on whether you are replying or following up to -an article).@refill - -@item -@emph{Inserts Supercite's keymap.} -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p -@cindex keymap prefix -Supercite provides a number of commands for performing post-yank -modifications to the reply buffer. These commands are installed on -Supercite's top-level keymap. Since Supercite has to interface with a -wide variety of MUAs, it does not install all of its commands directly -into the reply buffer's keymap. Instead, it puts its commands on a -keymap prefix, then installs this prefix onto the buffer's keymap. What -this means is that you typically have to type more characters to invoke -a Supercite command, but Supercite's key bindings can be made much more -consistent across MUAs. - -You can control what key Supercite uses as its keymap prefix by changing -the variable @code{sc-mode-map-prefix}. By default, this variable is -set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the -best default due to the scarcity of available key bindings in many MUAs. - -@item -@emph{Turns on Supercite minor mode.} -@cindex modeline -The modeline of the reply buffer should indicate that Supercite is -active in that buffer by displaying the string @samp{SC}. - -@item -@emph{Sets the ``Undo Boundary.''} -@cindex undo boundary -Supercite sets an undo boundary before it begins to modify the original -yanked text. This allows you to easily undo Supercite's changes to -affect alternative citing styles. - -@item -@emph{Processes the mail headers.} -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -@vindex sc-mail-warn-if-non-rfc822-p -@vindex mail-warn-if-non-rfc822-p (sc-) -All previously retrieved info key-value pairs are deleted from the info -alist, then the mail headers in the body of the yanked message are -scanned. Info key-value pairs are created for each header found. Also, -such useful information as the author's name and email address are -extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is -non-@code{nil}, then Supercite will warn you if it finds a mail header -that does not conform to RFC822. This is rare and indicates a problem -either with your MUA or the original author's MUA, or some MTA (mail -transport agent) along the way. - -@vindex sc-nuke-mail-headers -@vindex sc-nuke-mail-header-list -@vindex nuke-mail-headers (sc-) -@vindex nuke-mail-header-list (sc-) -Once the info keys have been extracted from the mail headers, the -headers are nuked from the reply buffer. You can control exactly which -headers are removed or kept, but by default, all headers are removed. - -There are two variables which control mail header nuking. The variable -@code{sc-nuke-mail-headers} controls the overall behavior of the header -nuking routines. By setting this variable to @code{'all}, you -automatically nuke all mail headers. Likewise, setting this variable to -@code{'none} inhibits nuking of any mail headers. In between these -extremes, you can tell Supercite to nuke only a specified list of mail -headers by setting this variable to @code{'specified}, or to keep only a -specified list of headers by setting it to @code{'keep}. - -If @code{sc-nuke-mail-headers} is set to @code{'specified} or -@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is -consulted for the list of headers to nuke or keep. This variable -contains a list of regular expressions. If the mail header line matches -a regular expression in this list, the header will be nuked or kept. -The line is matched against the regexp using @code{looking-at} rooted at -the beginning of the line. - -@vindex sc-blank-lines-after-headers -@vindex blank-lines-after-headers (sc-) -If the variable @code{sc-blank-lines-after-headers} is non-@code{nil}, -it contains the number of blank lines remaining in the buffer after mail -headers are nuked. By default, only one blank line is left in the buffer. - -@item -@emph{Selects the attribution and citation strings.} -Once the mail headers have been processed, Supercite selects a -attribution string and a citation string which it will use to cite the -original message. @xref{Selecting an Attribution}, for details. - -@item -@emph{Cites the message body.} -@vindex sc-cite-region-limit -@vindex cite-region-limit (sc-)b -After the selection of the attribution and citation strings, Supercite -cites the original message by inserting the citation string prefix in -front of every uncited line. You may not want Supercite to -automatically cite very long messages however. For example, some email -could contain a smaller header section followed by a huge uuencoded -message. It wouldn't make sense to cite the uuencoded message part when -responding to the original author's short preface. For this reason, -Supercite provides a variable which limits the automatic citation of -long messages to a certain maximum number of lines. The variable is -called @code{sc-cite-region-limit}. If this variable contains an -integer, messages with more lines that this will not be cited at all, -and a warning message will be displayed. Supercite has performed -everything necessary, though, for you to manually cite only the small -portion of the original message that you want to use. - -If @code{sc-cite-region-limit} contains a non-@code{nil} value, the -original message will always be cited, regardless of its size. If the -variable contains the value @code{nil}, the region will never be cited -automatically. Use this if you always want to be able to edit and cite -the message manually. - -@vindex sc-cite-blank-lines-p -@vindex cite-blank-lines-p (sc-) -The variable @code{sc-cite-blank-lines-p} controls whether blank lines -in the original message should be cited or not. If this variable is -non-@code{nil}, blank lines will be cited just like non-blank lines. -Otherwise, blank lines will be treated as paragraph separators. - -Citing of the original message is highly configurable. Supercite's -default setup does a pretty good job of citing many common forms of -previously cited messages. But there are as many citation styles out -there as people on the net, or just about! It would be impossible for -Supercite to anticipate every style in existence, and you probably -wouldn't encounter them all anyway. But you can configure Supercite to -recognize those styles you see often. -@xref{Configuring the Citation Engine}, for details.@refill - -@item -@emph{Runs @code{sc-post-hook}.} -@vindex sc-post-hook -@vindex post-hook (sc-) -This variable is very similar to @code{sc-pre-hook}, except that it runs -after @code{sc-cite-original} is finished. This hook is provided mostly -for completeness and backward compatibility. Perhaps it could be used to -reset certain variables set in @code{sc-pre-hook}.@refill -@end enumerate - -@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking -@cindex filling paragraphs -@vindex sc-auto-fill-region-p -@vindex auto-fill-region-p (sc-) -@cindex filladapt -@cindex gin-mode -@findex sc-setup-filladapt -@findex setup-filladapt (sc-) -@vindex sc-load-hook -@vindex load-hook (sc-) -@section Filling Cited Text - -Supercite will automatically fill newly cited text from the original -message unless the variable @code{sc-auto-fill-region-p} has a -@code{nil} value. Supercite will also re-fill paragraphs when you -manually cite or re-cite text. - -However, during normal editing, Supercite itself cannot be used to fill -paragraphs. This is a change from version 2. There are other add-on -lisp packages which do filling much better than Supercite ever did. The -two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well -with Supercite and both are available at the normal Emacs Lisp archive -sites. @dfn{gin-mode} works pretty well out of the box, but if you use -@dfn{filladapt}, you may want to run the function -@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply -makes @dfn{filladapt} a little more Supercite savvy than its default -setup. - -@vindex sc-fixup-whitespace-p -@vindex fixup-whitespace-p (sc-) -Also, Supercite will collapse leading whitespace between the citation -string and the text on a line when the variable -@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for -this variable is @code{nil}.@refill - -@vindex fill-prefix -Its important to understand that Supercite's automatic filling (during -the initial citation of the reply) is very fragile. That is because -figuring out the @code{fill-prefix} for a particular paragraph is a -really hard thing to do automatically. This is especially the case when -the original message contains code or some other text where leading -whitespace is important to preserve. For this reason, many Supercite -users typically run with @code{sc-auto-fill-region-p} (and possibly also -@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually -fill each cited paragraph in the reply buffer. - -I usually run with both these variables containing their default values. -When Supercite's automatic filling breaks on a particular message, I -will use Emacs' undo feature to undo back before the citation was -applied to the original message. Then I'll toggle the variables and -manually cite those paragraphs that I don't want to fill or collapse -whitespace on. @xref{Variable Toggling Shortcuts}.@refill - -@kindex C-c C-p C-p -If you find that Supercite's automatic filling is just too fragile for -your tastes, you might consider one of these alternate approaches. -Also, to make life easier, a shortcut function to toggle the state of -both of these variables is provided on the key binding -@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; -@pxref{Post-yank Formatting Commands}).@refill - -You will noticed that the minor mode string will -show the state of these variables as qualifier characters. When both -variables are @code{nil}, the Supercite minor mode string will display -@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the -string will display @samp{SC:f}, and when just -@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display -@samp{SC:w}. When both variables are non-@code{nil}, the string will -display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for -the default bindings of the toggling function for each respective -variable. -@xref{Variable Toggling Shortcuts}.@refill - -Why are these variables not set to @code{nil} by default? It is because -many users won't manually fill paragraphs that are Supercited, and there -have been widespread complaints on the net about mail and news messages -containing lines greater than about 72 characters. So the default is to -fill cited text. - -@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top -@cindex attribution list -@vindex sc-preferred-attribution-list -@vindex preferred-attribution-list (sc-) -@chapter Selecting an Attribution - -As you know, the attribution string is the part of the author's name -that will be used to composed a non-nested citation string. Supercite -scans the various mail headers present in the original article and uses -a number of heuristics to extract strings which it puts into the -@dfn{attribution association list} or @dfn{attribution alist}. This is -analogous, but different than, the info alist previously mentioned. Each -element in the attribution alist is a key-value pair containing such -information as the author's first name, middle names, and last name, the -author's initials, and the author's email terminus. - -@ifinfo -@menu -* Attribution Preferences:: -* Anonymous Attributions:: -* Author Names:: -@end menu -@end ifinfo - -@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution -@section Attribution Preferences - -When you cite an original message, you can tell Supercite which part of -the author's name you would prefer it to use as the attribution. The -variable @code{sc-preferred-attribution-list} controls this; it contains -keys which are matched against the attribution alist in the given order. -The first value of a key that produces a non-@code{nil}, non-empty -string match is used as the attribution string, and if no keys match, a -secondary mechanism is used to generate the attribution. -@xref{Anonymous Attributions}. - -The following preferences are always available in the attribution alist -(barring error): - -@table @code -@item "emailname" -the author's email terminus. - -@item "initials" -the author's initials. - -@item "firstname" -the author's first name. - -@item "lastname" -the author's last name. - -@item "middlename-1" -the author's first middle name. - -@item "sc-lastchoice" -the last attribution string you have selected. This is useful when you -recite paragraphs in the reply.@refill - -@item "sc-consult" -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -consults the customizable list @code{sc-attrib-selection-list} which can -be used to select special attributions based on the value of any info -key. See below for details. - -@item "x-attribution" -the original author's suggestion for attribution string choice. See below -for details.@refill -@end table - -Middle name indexes can be any positive integer greater than zero, -though it is unlikely that many authors will have more than one middle -name, if that many. - -At this point, let me digress into a discussion of etiquette. It is my -belief that while the style of the citations is a reflection of the -personal tastes of the replier (i.e., you), the attribution selection is -ultimately the personal choice of the original author. In a sense it is -his or her ``net nickname'', and therefore the author should have some -say in the selection of attribution string. Imagine how you would feel -if someone gave you a nickname that you didn't like? - -For this reason, Supercite recognizes a special mail header, -@samp{X-Attribution:}, which if present, tells Supercite the attribution -string preferred by the original author. It is the value of this header -that is associated with the @code{"x-attribution"} key in the -attribution alist. Currently, you can override the preference of this -key by changing @code{sc-preferred-attribution-list}, but that isn't -polite, and in the future Supercite may hard-code this. For now, it is -suggested that if you change the order of the keys in this list, that -@code{"x-attribution"} always be first, or possible second behind only -@code{"sc-lastchoice"}. This latter is the default. - -@vindex sc-attrib-selection-list -@vindex attrib-selection-list (sc-) -The value @code{"sc-consult"} in @code{sc-preferred-attribution-list} -has a special meaning during attribution selection. When Supercite -encounters this preference, it begins processing a customizable list of -attributions, contained in the variable @code{sc-attrib-selection-list}. -Each element in this list contains lists of the following form: - -@example -@group -(@var{infokey} ((@var{regexp} @. @var{attribution}) - (@var{regexp} @. @var{attribution}) - (@dots{}))) -@end group -@end example - -@noindent -@findex sc-mail-field -@findex mail-field (sc-) -where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} -is a regular expression to match against the @var{infokey}'s value. If -@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is -used as the attribution string. Actually, @var{attribution} can be a -string or a list; if it is a list, it is @code{eval}uated and the return -value (which must be a string), is used as the attribution. - -This can be very useful for when you are replying to net acquaintances -who do not use the @samp{X-Attribution:@:} mail header. You may know -what nickname they would prefer to use, and you can set up this list to -match against a specific mail field, e.g., @samp{From:@:}, allowing you -to cite your friend's message with the appropriate attribution. - -@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution -@vindex sc-default-author-name -@vindex default-author-name (sc-) -@vindex sc-default-attribution -@vindex default-attribution (sc-) -@section Anonymous Attributions - -When the author's name cannot be found in the @samp{From:@:} mail -header, a fallback author name and attribution string must be supplied. -The fallback author name is contained in the variable -@code{sc-default-author-name} and the fallback attribution string is -contained in the variable @code{sc-default-attribution}. Default values -for these variables are @code{"Anonymous"} and @code{"Anon"}, -respectively. Note that in most circumstances, getting the default -author name or attribution is a sign that something is set up -incorrectly. - -@vindex sc-use-only-preference-p -@vindex use-only-preference-p (sc-) -Also, if the preferred attribution, which you specified in your -@code{sc-preferred-attribution-list} variable cannot be found, a -secondary method can be employed to find a valid attribution string. The -variable @code{sc-use-only-preference-p} controls what happens in this -case. If the variable's value is non-@code{nil}, then -@code{sc-default-author-name} and @code{sc-default-attribution} are -used, otherwise, the following steps are taken to find a valid -attribution string, and the first step to return a non-@code{nil}, -non-empty string becomes the attribution:@refill - -@enumerate -@item -Use the last selected attribution, if there is one. - -@item -Use the value of the @code{"x-attribution"} key. - -@item -Use the author's first name. - -@item -Use the author's last name. - -@item -Use the author's initials. - -@item -Find the first non-@code{nil}, non-empty attribution string in the -attribution alist. - -@item -@code{sc-default-attribution} is used. -@end enumerate - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Once the attribution string has been automatically selected, a number of -things can happen. If the variable @code{sc-confirm-always-p} is -non-@code{nil}, you are queried for confirmation of the chosen -attribution string. The possible values for completion are those strings -in the attribution alist, however you are not limited to these choices. -You can type any arbitrary string at the confirmation prompt. The string -you enter becomes the value associated with the @code{"sc-lastchoice"} -key in the attribution alist. - -@vindex sc-downcase-p -@vindex downcase-p (sc-) -Once an attribution string has been selected, Supercite will force the -string to lower case if the variable @code{sc-downcase-p} is -non-@code{nil}. - -@vindex sc-attribs-preselect-hook -@vindex attribs-preselect-hook (sc-) -@vindex sc-attribs-postselect-hook -@vindex attribs-postselect-hook (sc-) - -Two hook variables provide even greater control of the attribution -selection process. The hook @code{sc-attribs-preselect-hook} is run -before any attribution is selected. Likewise, the hook -@code{sc-attribs-postselect-hook} is run after the attribution is -selected (and the corresponding citation string is built), but before -these values are committed for use by Supercite. During the -post-selection hook, the local variables @code{attribution} and -@code{citation} are bound to the appropriate strings. By changing these -variables in your hook functions, you change the attribution and -citation strings used by Supercite. One possible use of this would be -to override any automatically derived attribution string when it is only -one character long; e.g. you prefer to use @code{"initials"} but the -author only has one name.@refill - -@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution -@cindex author names -@section Author Names - -Supercite employs a number of heuristics to decipher the author's name -based on value of the @samp{From:@:} mail field of the original message. -Supercite can recognize almost all of the common @samp{From:@:} field -formats in use. If you encounter a @samp{From:@:} field that Supercite -cannot parse, please report this bug using @kbd{M-x report-emacs-bug}. - -@vindex sc-titlecue-regexp -@vindex titlecue-regexp (sc-) -There are a number of Supercite variables that control how author names -are extracted from the @samp{From:@:} header. Some headers may contain a -descriptive title as in: - -@example -From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker) -@end example - -Supercite knows which part of the @samp{From:@:} header is email address -and which part is author name, but in this case the string @code{"Decent -Hacker"} is not part of the author's name. You can tell Supercite to -ignore the title, while still recognizing hyphenated names through the -use of a regular expression in the variable @code{sc-titlecue-regexp}. -This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any -text after this regexp is encountered is ignored as noise. - -@vindex sc-name-filter-alist -@vindex name-filter-alist (sc-) -Some @samp{From:@:} headers may contain extra titles in the name fields -not separated by a title cue, but which are nonetheless not part of the -author's name proper. Examples include the titles ``Dr.'', ``Mr.'', -``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third). -Also, some companies prepend or append the name of the division, -organization, or project on the author's name. All of these titles are -noise which should be ignored. The variable @code{sc-name-filter-alist} -is used for this purpose. As implied by its name, this variable is an -association list, where each element is a cons cell of the form: - -@example -(@var{regexp} @. @var{position}) -@end example - -@noindent -where @var{regexp} is a regular expression that is matched (using -@code{string-match}) against each element of the @samp{From:@:} field's -author name. @var{position} is a position indicator, starting at zero. -Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, -@code{sc-name-filter-alist} would have an entry such as: - -@example -("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0) -@end example - -@noindent -which only removes them if they appear as the first word in the name. -The position indicator is an integer, or one of the two special symbols -@code{last} or @code{any}. @code{last} always matches against the last -word in the name field, while @code{any} matches against every word in -the name field. - -@node Configuring the Citation Engine, Using Regi, Author Names, Top -@cindex Regi -@cindex frames (Regi) -@cindex entries (Regi) -@chapter Configuring the Citation Engine - -At the heart of Supercite is a regular expression interpreting engine -called @dfn{Regi}. Regi operates by interpreting a data structure -called a Regi-frame (or just @dfn{frame}), which is a list of -Regi-entries (or just @dfn{entry}). Each entry contains a predicate, -typically a regular expression, which is matched against a line of text -in the current buffer. If the predicate matches true, an associated -expression is @code{eval}uated. In this way, an entire region of text -can be transformed in an @emph{awk}-like manner. Regi is used -throughout Supercite, from mail header information extraction, to header -nuking, to citing text. - -@ifinfo -@menu -* Using Regi:: -* Frames You Can Customize:: -@end menu -@end ifinfo - -While the details of Regi are discussed below (@pxref{Using Regi}), only -those who wish to customize certain aspects of Supercite need concern -themselves with it. It is important to understand though, that any -conceivable citation style that can be described by a regular expression -can be recognized by Supercite. This leads to some interesting -applications. For example, if you regularly receive email from a -co-worker that uses an uncommon citation style (say one that employs a -@samp{|} or @samp{@}} character at the front of the line), it is -possible for Supercite to recognize this and @emph{coerce} the citation -to your preferred style, for consistency. In theory, it is possible for -Supercite to recognize such things as uuencoded messages or C code and -cite or fill those differently than normal text. None of this is -currently part of Supercite, but contributions are welcome! - -@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine -@findex regi-interpret -@findex eval -@findex looking-at -@section Using Regi - -Regi works by interpreting frames with the function -@code{regi-interpret}. A frame is a list of arbitrary size where each -element is a entry of the following form: - -@example -(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]]) -@end example - -Regi starts with the first entry in a frame, evaluating the @var{pred} -of that entry against the beginning of the line that @samp{point} is on. -If the @var{pred} evaluates to true (or false if the optional -@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is -@code{eval}uated. How processing continues is determined by the return -value for @var{func}, and is described below. If @var{pred} was false -the next entry in the frame is checked until all entries have been -matched against the current line. If no entry matches, @samp{point} is -moved forward one line and the frame is reset to the first entry. - -@var{pred} can be a string, a variable, a list or one of the following -symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If -@var{pred} is a string, or a variable or list that @code{eval}uates to a -string, it is interpreted as a regular expression. This regexp is -matched against the current line, from the beginning, using -@code{looking-at}. This match folds case if the optional -@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a -string, or does not @code{eval}uate to a string, it is interpreted as a -binary value (@code{nil} or non-@code{nil}).@refill - -The four special symbol values for @var{pred} are recognized: - -@table @code -@item t -Always produces a true outcome. -@item begin -Always executed before the frame is interpreted. This can be used to -initialize some global variables for example. -@item end -Always executed after frame interpreting is completed. This can be used -to perform any necessary post-processing. -@item every -Executes whenever the frame is reset, usually after the entire frame has -been matched against the current line. -@end table - -Note that @var{negate-p} and @var{case-fold-search} are ignored if -@var{pred} is one of these special symbols. Only the first occurrence of -each symbol in a frame is used; any duplicates are ignored. Also -note that for performance reasons, the entries associated with these -symbols are removed from the frame during the main interpreting loop. - -Your @var{func} can return certain values which control continued Regi -processing. By default, if your @var{func} returns @code{nil} (as it -should be careful to do explicitly), Regi will reset the frame to the -first entry, and advance @samp{point} to the beginning of the next line. -If a list is returned from your function, it can contain any combination -of the following elements:@refill - -@table @asis -@item the symbol @code{continue} -This tells Regi to continue processing entries after a match, instead of -resetting the frame and moving @samp{point}. In this way, lines of text -can have multiple matches, but you have to be careful to avoid entering -infinite loops. - -@item the symbol @code{abort} -This tells Regi to terminate frame processing. However, any @code{end} -entry is still processed. - -@item the list @code{(frame . @var{newframe})} -This tells Regi to substitute @var{newframe} as the frame it is -interpreting. In other words, your @var{func} can modify the Regi frame -on the fly. @var{newframe} can be a variable containing a frame, or it -can be the frame in-lined.@refill - -@item the list @code{(step . @var{step})} -Tells Regi to move @var{step} number of lines forward as it continues -processing. By default, Regi moves forward one line. @var{step} can be -zero or negative of course, but watch out for infinite loops.@refill -@end table - -During execution of your @var{func}, the following variables will be -temporarily bound to some useful information:@refill - -@table @code -@item curline -The current line in the buffer that Regi is @code{looking-at}, as a string. -@item curframe -The current frame being interpreted. -@item curentry -The current frame entry being interpreted. -@end table - -@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine -@vindex sc-nuke-mail-header -@section Frames You Can Customize - -As mentioned earlier, Supercite uses various frames to perform -certain jobs such as mail header information extraction and mail header -nuking. However, these frames are not available for you to customize, -except through abstract interfaces such as @code{sc-nuke-mail-header}, -et al. - -@vindex sc-default-cite-frame -However, the citation frames Supercite uses provide a lot of customizing -power and are thus available to you to change to suit your needs. The -workhorse of citation is the frame contained in the variable -@code{sc-default-cite-frame}. This frame recognizes many situations, -such as blank lines, which it interprets as paragraph separators. It -also recognizes previously cited nested and non-nested citations in the -original message. By default it will coerce non-nested citations into -your preferred citation style, and it will add a level of citation to -nested citations. It will also simply cite uncited lines in your -preferred style. - -@cindex unciting -@cindex reciting -@vindex sc-default-uncite-frame -@vindex sc-default-recite-frame -In a similar vein, there are default frames for @dfn{unciting} and -@dfn{reciting}, contained in the variables -@code{sc-default-uncite-frame} and @code{sc-default-recite-frame} -respectively.@refill - -As mentioned earlier (@pxref{Recognizing Citations}), citations are -recognized through the values of the regular expressions -@code{sc-citation-root-regexp}, et al. To recognize odd styles, you -could modify these variables, or you could modify the default citing -frame. Alternatively, you could set up association lists of frames for -recognizing specific alternative forms. - -@vindex sc-cite-frame-alist -@vindex sc-uncite-frame-alist -@vindex sc-recite-frame-alist -For each of the actions -- citing, unciting, and reciting -- an alist is -consulted to find the frame to use (@code{sc-cite-frame-alist}, -@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} -respectively). These frames can contain alists of the form: - -@example -((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) - (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) - (@dots{})) -@end example - -@vindex sc-mail-field -@findex string-match -Where @var{infokey} is a key suitable for @code{sc-mail-field}, -@var{regexp} is a regular expression which is @code{string-match}'d -against the value of the @code{sc-mail-field} key, and @var{frame} is -the frame to use if a match occurred. @var{frame} can be a variable -containing a frame or a frame in-lined.@refill - -When Supercite is about to cite, uncite, or recite a region, it consults -the appropriate alist and attempts to find a frame to use. If one -is not found from the alist, then the appropriate default frame is used. - -@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top -@vindex sc-mode-map-prefix -@vindex mode-map-prefix (sc-) -@kindex C-c C-p -@chapter Post-yank Formatting Commands - -Once the original message has been yanked into the reply buffer, and -@code{sc-cite-original} has had a chance to do its thing, a number of -useful Supercite commands will be available to you. Since there is wide -variety in the keymaps that MUAs set up in their reply buffers, it is -next to impossible for Supercite to properly sprinkle its commands into -the existing keymap. For this reason Supercite places its commands on a -separate keymap, putting this keymap onto a prefix key in the reply -buffer. You can customize the prefix key Supercite uses by changing the -variable @code{sc-mode-map-prefix}. By default, the -@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, -but unfortunately the best general solution so far. In the rest of this -chapter, we'll assume you've installed Supercite's keymap on the default -prefix.@refill - -@ifinfo -@menu -* Citing Commands:: -* Insertion Commands:: -* Variable Toggling Shortcuts:: -* Mail Field Commands:: -* Miscellaneous Commands:: -@end menu -@end ifinfo - -@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands -@vindex sc-cite-region-limit -@section Commands to Manually Cite, Recite, and Uncite - -Probably the three most common post-yank formatting operations that you -will perform will be the manual citing, reciting, and unciting of -regions of text in the reply buffer. Often you may want to recite a -paragraph to use a nickname, or manually cite a message when setting -@code{sc-cite-region-limit} to @code{nil}. The following commands -perform these functions on the region of text between @samp{point} and -@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying -the region so that the command can be undone in the standard Emacs -way.@refill - -Here is the list of Supercite citing commands: - -@table @asis -@findex sc-cite-region -@findex cite-region (sc-) -@kindex C-c C-p c -@vindex sc-pre-cite-hook -@vindex pre-cite-hook (sc-) -@vindex sc-confirm-always-p -@vindex confirm-always-p -@kindex C-u -@item @code{sc-cite-region} (@kbd{C-c C-p c}) -This command cites each line in the region of text by interpreting the -selected frame from @code{sc-cite-frame-alist}, or the default citing -frame @code{sc-default-cite-frame}. It runs the hook -@code{sc-pre-cite-hook} before interpreting the frame. With an optional -universal argument (@kbd{C-u}), it temporarily sets -@code{sc-confirm-always-p} to @code{t} so you can confirm the -attribution string for a single manual citing. -@xref{Configuring the Citation Engine}.@refill - -@findex sc-uncite-region -@findex uncite-region (sc-) -@kindex C-c C-p u -@item @code{sc-uncite-region} (@kbd{C-c C-p u}) -This command removes any citation strings from the beginning of each -cited line in the region by interpreting the selected frame from -@code{sc-uncite-frame-alist}, or the default unciting frame -@code{sc-default-uncite-frame}. It runs the hook -@code{sc-pre-uncite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill - -@findex sc-recite-region -@findex recite-region (sc-) -@kindex C-c C-p r -@item @code{sc-recite-region} (@kbd{C-c C-p r}) -This command recites each line the region by interpreting the selected -frame from @code{sc-recite-frame-alist}, or the default reciting frame -@code{sc-default-recite-frame}. It runs the hook -@code{sc-pre-recite-hook} before interpreting the frame. -@xref{Configuring the Citation Engine}.@refill - -@vindex sc-confirm-always-p -@vindex confirm-always-p (sc-) -Supercite will always ask you to confirm the attribution when reciting a -region, regardless of the value of @code{sc-confirm-always-p}. -@end table - -@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands -@section Insertion Commands - -These two functions insert various strings into the reply buffer. - -@table @asis -@findex sc-insert-reference -@findex insert-reference (sc-) -@kindex C-c C-p w -@item @code{sc-insert-reference} (@kbd{C-c C-p w}) -@vindex sc-preferred-header-style -@vindex preferred-header-style (sc-) -Inserts a reference header into the reply buffer at @samp{point}. With -no arguments, the header indexed by @code{sc-preferred-header-style} is -inserted. An optional numeric argument is the index into -@code{sc-rewrite-header-list} indicating which reference header to -write.@refill - -With just the universal argument (@kbd{C-u}), electric reference mode is -entered, regardless of the value of @code{sc-electric-references-p}. - -@findex sc-insert-citation -@findex insert-citation (sc-) -@kindex C-c C-p i -@item @code{sc-insert-citation} (@kbd{C-c C-p i}) -Inserts the current citation string at the beginning of the line that -@samp{point} is on. If the line is already cited, Supercite will issue -an error and will not cite the line. -@end table - -@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands -@cindex toggling variables -@section Variable Toggling Shortcuts - -Supercite defines a number of commands that make it easier for you to -toggle and set various Supercite variables as you are editing the reply -buffer. For example, you may want to turn off filling or whitespace -cleanup, but only temporarily. These toggling shortcut commands make -this easy to do. - -@kindex C-c C-p C-t -Like Supercite commands in general, the toggling commands are placed on -a keymap prefix within the greater Supercite keymap. For the default -value of @code{sc-mode-map-prefix}, this will be -@kbd{C-c C-p C-t}.@refill - -The following commands toggle the value of certain Supercite variables -which take only a binary value: - -@table @kbd -@item C-c C-p C-t b -Toggles the variable @code{sc-mail-nuke-blank-lines-p}. - -@item C-c C-p C-t c -Toggles the variable @code{sc-confirm-always-p}. - -@item C-c C-p C-t d -Toggles the variable @code{sc-downcase-p}. - -@item C-c C-p C-t e -Toggles the variable @code{sc-electric-references-p}. - -@item C-c C-p C-t f -Toggles the variable @code{sc-auto-fill-region-p}. - -@item C-c C-p C-t o -Toggles the variable @code{sc-electric-circular-p}. - -@item C-c C-p C-t s -Toggles the variable @code{sc-nested-citation-p}. - -@item C-c C-p C-t u -Toggles the variable @code{sc-use-only-preferences-p}. - -@item C-c C-p C-t w -Toggles the variable @code{sc-fixup-whitespace-p}. -@end table - -@findex set-variable -The following commands let you set the value of multi-value variables, -in the same way that Emacs' @code{set-variable} does: - -@table @kbd -@item C-c C-p C-t a -Sets the value of the variable @code{sc-preferred-attribution-list}. - -@item C-c C-p C-t l -Sets the value of the variable @code{sc-cite-region-limit}. - -@item C-c C-p C-t n -Sets the value of the variable @code{sc-mail-nuke-mail-headers}. - -@item C-c C-p C-t N -Sets the value of the variable @code{sc-mail-header-nuke-list}. - -@item C-c C-p C-t p -Sets the value of the variable @code{sc-preferred-header-style}. -@end table - -@kindex C-c C-p C-p -One special command is provided to toggle both -@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. -This is because you typically want to run Supercite with either variable -as @code{nil} or non-@code{nil}. The command to toggle these variables -together is bound on @kbd{C-c C-p C-p}.@refill - -Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) -brings up a Help message on the toggling keymap. - - -@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands -@section Mail Field Commands - -These commands allow you to view, modify, add, and delete various bits -of information from the info alist. -@xref{Information Keys and the Info Alist}.@refill - -@table @asis -@kindex C-c C-p f -@findex sc-mail-field-query -@findex mail-field-query (sc-) -@kindex C-c C-p f -@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) -Allows you to interactively view, modify, add, and delete info alist -key-value pairs. With no argument, you are prompted (with completion) -for a info key. The value associated with that key is displayed in the -minibuffer. With an argument, this command will first ask if you want -to view, modify, add, or delete an info key. Viewing is identical to -running the command with no arguments. - -If you want to modify the value of a key, Supercite will first prompt -you (with completion) for the key of the value you want to change. It -will then put you in the minibuffer with the key's current value so you -can edit the value as you wish. When you hit @key{RET}, the key's value -is changed. Minibuffer history is kept for the values. - -If you choose to delete a key-value pair, Supercite will prompt you (with -completion) for the key to delete. - -If you choose to add a new key-value pair, Supercite firsts prompts you -for the key to add. Note that completion is turned on for this prompt, -but you can type any key name here, even one that does not yet exist. -After entering the key, Supercite prompts you for the key's value. It -is not an error to enter a key that already exists, but the new value -will override any old value. It will not replace it though; if you -subsequently delete the key-value pair, the old value will reappear. - -@findex sc-mail-process-headers -@findex mail-process-headers (sc-) -@kindex C-c C-p g -@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) -This command lets you re-initialize Supercite's info alist from any set -of mail headers in the region between @samp{point} and @samp{mark}. -This function is especially useful for replying to digest messages where -Supercite will initially set up its information for the digest -originator, but you want to cite each component article with the real -message author. Note that unless an error during processing occurs, any -old information is lost.@refill -@end table - -@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands -@section Miscellaneous Commands - -@table @asis -@findex sc-open-line -@findex open-line (sc-) -@findex open-line -@kindex C-c C-p o -@item @code{sc-open-line} (@kbd{C-c C-p o}) -Similar to Emacs' standard @code{open-line} commands, but inserts the -citation string in front of the new line. As with @code{open-line}, -an optional numeric argument inserts that many new lines.@refill -@end table - -@node Hints to MUA Authors, Thanks and History, Electric References, Top -@chapter Hints to MUA Authors - -In June of 1989, some discussion was held between the various MUA -authors, the Supercite author, and other Supercite users. These -discussions centered around the need for a standard interface between -MUAs and Supercite (or any future Supercite-like packages). This -interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in -a mail message to the Supercite mailing list: - -@example - Martin> Each news/mail-reader should provide a form of - Martin> mail-yank-original that - - Martin> 1: inserts the original message incl. header into the - Martin> reply buffer; no indentation/prefixing is done, the header - Martin> tends to be a "full blown" version rather than to be - Martin> stripped down. - - Martin> 2: `point' is at the start of the header, `mark' at the - Martin> end of the message body. - - Martin> 3: (run-hooks 'mail-yank-hooks) - - Martin> [Supercite] should be run as such a hook and merely - Martin> rewrite the message. This way it isn't anymore - Martin> [Supercite]'s job to gather the original from obscure - Martin> sources. [@dots{}] -@end example - -@vindex mail-citation-hook -@vindex mail-yank-hooks -@cindex sendmail.el -@findex mail-yank-original -@findex defvar -This specification was adopted, but underwent a slight modification with -the release of Emacs 19. Instead of the variable -@code{mail-yank-hooks}, the hook variable that the MUA should provide is -@code{mail-citation-hook}. Richard Stallman suggests that the MUAs -should @code{defvar} @code{mail-citation-hook} to @code{nil} and perform -some default citing when that is the case.@refill - -If you are writing a new MUA package, or maintaining an existing MUA -package, you should make it conform to this interface so that your users -will be able to link Supercite easily and seamlessly. To do this, when -setting up a reply or forward buffer, your MUA should follow these -steps: - -@enumerate -@item -Insert the original message, including the mail headers into the reply -buffer. At this point you should not modify the raw text in any way, and -you should place all the original headers into the body of the reply. -This means that many of the mail headers will be duplicated, one copy -above the @code{mail-header-separator} line and one copy below, -however there will probably be more headers below this line.@refill - -@item -Set @samp{point} to the beginning of the line containing the first mail -header in the body of the reply. Set @samp{mark} at the end of the -message text. It is very important that the region be set around the -text Supercite is to modify and that the mail headers are within this -region. Supercite will not venture outside the region for any reason, -and anything within the region is fair game, so don't put anything that -@strong{must} remain unchanged inside the region.@refill - -@item -Run the hook @code{mail-citation-hook}. You will probably want to -provide some kind of default citation functions in cases where the user -does not have Supercite installed. By default, your MUA should -@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your -yanking function, check its value. If it finds -@code{mail-citation-hook} to be @code{nil}, it should perform some -default citing behavior. User who want to connect to Supercite then -need only add @code{sc-cite-original} to this list of hooks using -@code{add-hook}.@refill -@end enumerate - -If you do all this your MUA will join the ranks of those that conform to -this interface ``out of the box.'' - -@node Thanks and History, GNU Free Documentation License, Hints to MUA Authors, Top -@chapter Thanks and History - -The Supercite package was derived from its predecessor Superyank 1.11 -which was inspired by various bits of code and ideas from Martin Neitzel -and Ashwin Ram. They were the folks who came up with the idea of -non-nested citations and implemented some rough code to provide this -style. Superyank and Supercite version 2 evolved to the point where much -of the attribution selection mechanism was automatic, and features have -been continuously added through the comments and suggestions of the -Supercite mailing list participants. - -With version 3, Supercite underwent an almost complete rewrite, -benefitting in a number of ways, including vast improvements in the -speed of performance, a big reduction in size of the code and in the use -of Emacs resources, and a much cleaner and flexible internal -architecture. Most of this work was internal and not of very great -importance to the casual user. There were some changes at the -user-visible level, but for the most part, the Supercite configuration -variables from version 2 should still be relevant to version 3. -Hopefully Supercite version 3 is faster, smaller, and much more flexible -than its predecessors. - -In the version 2 manual I thanked some specific people for their help in -developing Supercite 2. You folks know who you are and your continued -support is greatly appreciated. I wish to thank everyone on the -Supercite mailing list, especially the brave alpha testers, who helped -considerably in testing out the concepts and implementation of Supercite -version 3. Special thanks go out to the MUA and Emacs authors Kyle -Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming -to a quick agreement on the new @code{mail-citation-hook} interface, and -for adding the magic lisp to their code to support this. - -All who have helped and contributed have been greatly appreciated. - -Supercite was written by Barry Warsaw. - -@node GNU Free Documentation License, Concept Index, Thanks and History, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Concept Index, Command Index, GNU Free Documentation License, Top -@unnumbered Concept Index -@printindex cp - -@node Command Index, Key Index, Concept Index, Top -@unnumbered Command Index -@ifinfo - -@end ifinfo -Since all supercite commands are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{command} name and -its @var{command} name. -@iftex -@sp 2 -@end iftex -@printindex fn - -@node Key Index, Variable Index, Command Index, Top -@unnumbered Key Index -@printindex ky - -@node Variable Index, , Key Index, Top -@unnumbered Variable Index -@ifinfo - -@end ifinfo -Since all supercite variables are prepended with the string -``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and -its @var{variable} name. -@iftex -@sp 2 -@end iftex -@printindex vr -@bye - -@ignore - arch-tag: 0521847a-4680-44b6-ae6e-13ce20e18436 -@end ignore diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi deleted file mode 100644 index 89228df57c5..00000000000 --- a/doc/misc/ses.texi +++ /dev/null @@ -1,988 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../../info/ses -@settitle SES: Simple Emacs Spreadsheet -@setchapternewpage off -@syncodeindex fn cp -@syncodeindex vr cp -@syncodeindex ky cp -@c %**end of header - -@copying -This file documents SES: the Simple Emacs Spreadsheet. - -Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License.'' - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* SES: (ses). Simple Emacs Spreadsheet -@end direntry - -@finalout - -@titlepage -@title SES -@subtitle Simple Emacs Spreadsheet -@author Jonathan A. Yavner -@author @email{jyavner@@member.fsf.org} - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@c =================================================================== - -@ifnottex -@node Top, Sales Pitch, (dir), (dir) -@comment node-name, next, previous, up -@top SES: Simple Emacs Spreadsheet - -@display -SES is a major mode for GNU Emacs to edit spreadsheet files, which -contain a rectangular grid of cells. The cells' values are specified -by formulas that can refer to the values of other cells. -@end display -@end ifnottex - -To report bugs, send email to @email{jyavner@@member.fsf.org}. - -@insertcopying - -@menu -* Sales Pitch:: Why use SES? -* The Basics:: Basic spreadsheet commands -* Advanced Features:: Want to know more? -* For Gurus:: Want to know @emph{even more}? -* Index:: Concept, Function and Variable Index -* Acknowledgements:: Acknowledgements -* GNU Free Documentation License:: The license for this documentation. -@end menu - -@c =================================================================== - -@node Sales Pitch, The Basics, Top, Top -@comment node-name, next, previous, up -@chapter Sales Pitch -@cindex features - -@itemize @bullet -@item Create and edit simple spreadsheets with a minimum of fuss. -@item Full undo/redo/autosave. -@item Immune to viruses in spreadsheet files. -@item Cell formulas are straight Emacs Lisp. -@item Printer functions for control of cell appearance. -@item Intuitive keystroke commands: C-o = insert row, M-o = insert column, etc. -@item ``Spillover'' of lengthy cell values into following blank cells. -@item Header line shows column letters or a selected row. -@item Completing-read for entering symbols as cell values. -@item Cut, copy, and paste can transfer formulas and printer functions. -@item Import and export of tab-separated values or tab-separated formulas. -@item Plaintext, easily-hacked file format. -@end itemize - -@c =================================================================== - -@node The Basics, Advanced Features, Sales Pitch, Top -@comment node-name, next, previous, up -@chapter The Basics -@cindex basic commands -@findex ses-jump -@findex ses-mark-row -@findex ses-mark-column -@findex ses-mark-whole-buffer -@findex set-mark-command -@findex keyboard-quit - -To create a new spreadsheet, visit a nonexistent file whose name ends - with ".ses". For example, @kbd{C-x C-f test.ses RET}. - - -A @dfn{cell identifier} is a symbol with a column letter and a row -number. Cell B7 is the 2nd column of the 7th row. For very wide -spreadsheets, there are two column letters: cell AB7 is the 28th -column of the 7th row. Super wide spreadsheets get AAA1, etc. - -@table @kbd -@item j -Moves point to cell, specified by identifier (@code{ses-jump}). -@end table - -Point is always at the left edge of a cell, or at the empty endline. -When mark is inactive, the current cell is underlined. When mark is -active, the range is the highlighted rectangle of cells (SES always -uses transient mark mode). Drag the mouse from A1 to A3 to create the -range A1-A2. Many SES commands operate only on single cells, not -ranges. - -@table @kbd -@item C-SPC -@itemx C-@@ -Set mark at point (@code{set-mark-command}). - -@item C-g -Turn off the mark (@code{keyboard-quit}). - -@item M-h -Highlight current row (@code{ses-mark-row}). - -@item S-M-h -Highlight current column (@code{ses-mark-column}). - -@item C-x h -Highlight all cells (@code{mark-whole-buffer}). -@end table - -@menu -* Formulas:: -* Resizing:: -* Printer functions:: -* Clearing cells:: -* Copy/cut/paste:: -* Customizing SES:: -@end menu - -@node Formulas, Resizing, The Basics, The Basics -@section Cell formulas -@cindex formulas -@cindex formulas, entering -@findex ses-read-cell -@findex ses-read-symbol -@findex ses-edit-cell -@findex ses-recalculate-cell -@findex ses-recalculate-all - -To enter a number into the current cell, just start typing: - -@table @kbd -@item 0..9 -Self-insert a digit (@code{ses-read-cell}). - -@item - -Self-insert a negative number (@code{ses-read-cell}). - -@item . -Self-insert a fractional number (@code{ses-read-cell}). - -@item " -Self-insert a quoted string. The ending double-quote -is inserted for you (@code{ses-read-cell}). - -@item ( -Self-insert an expression. The right-parenthesis is inserted for you -(@code{ses-read-cell}). To access another cell's value, just use its -identifier in your expression. Whenever the other cell is changed, -this cell's formula will be reevaluated. While typing in the -expression, you can use @kbd{M-@key{TAB}} to complete symbol names. - -@item ' @r{(apostrophe)} -Enter a symbol (ses-read-symbol). SES remembers all symbols that have -been used as formulas, so you can type just the beginning of a symbol -and use @kbd{@key{SPC}}, @kbd{@key{TAB}}, and @kbd{?} to complete it. -@end table - -To enter something else (e.g., a vector), begin with a digit, then -erase the digit and type whatever you want. - -@table @kbd -@item RET -Edit the existing formula in the current cell (@code{ses-edit-cell}). - -@item C-c C-c -Force recalculation of the current cell or range (@code{ses-recalculate-cell}). - -@item C-c C-l -Recalculate the entire spreadsheet (@code{ses-recalculate-all}). -@end table - -@node Resizing, Printer functions, Formulas, The Basics -@section Resizing the spreadsheet -@cindex resizing spreadsheets -@findex ses-insert-row -@findex ses-insert-column -@findex ses-delete-row -@findex ses-delete-column -@findex ses-set-column-width -@findex ses-forward-or-insert -@findex ses-append-row-jump-first-column - - -Basic commands: - -@table @kbd -@item C-o -(@code{ses-insert-row}) - -@item M-o -(@code{ses-insert-column}) - -@item C-k -(@code{ses-delete-row}) - -@item M-k -(@code{ses-delete-column}) - -@item w -(@code{ses-set-column-width}) - -@item TAB -Moves point to the next rightward cell, or inserts a new column if -already at last cell on line, or inserts a new row if at endline -(@code{ses-forward-or-insert}). - -@item C-j -Linefeed inserts below the current row and moves to column A -(@code{ses-append-row-jump-first-column}). -@end table - -Resizing the spreadsheet (unless you're just changing a column width) -relocates all the cell-references in formulas so they still refer to -the same cells. If a formula mentioned B1 and you insert a new first -row, the formula will now mention B2. - -If you delete a cell that a formula refers to, the cell-symbol is -deleted from the formula, so @code{(+ A1 B1 C1)} after deleting the third -column becomes @code{(+ A1 B1)}. In case this is not what you wanted: - -@table @kbd -@item C-_ -@itemx C-x u -Undo previous action (@code{(undo)}). -@end table - - -@node Printer functions, Clearing cells, Resizing, The Basics -@section Printer functions -@cindex printer functions -@findex ses-read-cell-printer -@findex ses-read-column-printer -@findex ses-read-default-printer -@findex ses-center -@findex ses-center-span -@findex ses-dashfill -@findex ses-dashfill-span -@findex ses-tildefill-span - - -Printer functions convert binary cell values into the print forms that -Emacs will display on the screen. - -A printer can be a format string, like @samp{"$%.2f"}. The result -string is right-aligned within the print cell. To get left-alignment, -use parentheses: @samp{("$%.2f")}. A printer can also be a -one-argument function (a symbol or a lambda), whose result is a string -(right-aligned) or list of one string (left-aligned). While typing in -a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. - -Each cell has a printer. If @code{nil}, the column-printer for the cell's -column is used. If that is also @code{nil}, the default-printer for the -spreadsheet is used. - -@table @kbd -@item p -Enter a printer for current cell or range (@code{ses-read-cell-printer}). - -@item M-p -Enter a printer for the current column (@code{ses-read-column-printer}). - -@item C-c C-p -Enter the default printer for the spreadsheet -(@code{ses-read-default-printer}). -@end table - -The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer -history, which is preloaded with the set of all printers used in this -spreadsheet, plus the standard printers. - -The standard printers are suitable only for cells, not columns or -default, because they format the value using the column-printer (or -default-printer if @code{nil}) and then center the result: - -@table @code -@item ses-center -Just centering. - -@item ses-center-span -Centering with spill-over to following blank cells. - -@item ses-dashfill -Centering using dashes (-) instead of spaces. - -@item ses-dashfill-span -Centering with dashes and spill-over. - -@item ses-tildefill-span -Centering with tildes (~) and spill-over. -@end table - - -@node Clearing cells, Copy/cut/paste, Printer functions, The Basics -@section Clearing cells -@cindex clearing commands -@findex ses-clear-cell-backward -@findex ses-clear-cell-forward - -These commands set both formula and printer to @code{nil}: - -@table @kbd -@item DEL -Clear cell and move left (@code{ses-clear-cell-backward}). - -@item C-d -Clear cell and move right (@code{ses-clear-cell-forward}). -@end table - - -@node Copy/cut/paste, Customizing SES, Clearing cells, The Basics -@section Copy, cut, and paste -@cindex copy -@cindex cut -@cindex paste -@findex kill-ring-save -@findex mouse-set-region -@findex mouse-set-secondary -@findex ses-kill-override -@findex yank -@findex clipboard-yank -@findex mouse-yank-at-click -@findex mouse-yank-at-secondary -@findex ses-yank-pop - -The copy functions work on rectangular regions of cells. You can paste the -copies into non-SES buffers to export the print text. - -@table @kbd -@item M-w -@itemx [copy] -@itemx [C-insert] -Copy the highlighted cells to kill ring and primary clipboard -(@code{kill-ring-save}). - -@item [drag-mouse-1] -Mark a region and copy it to kill ring and primary clipboard -(@code{mouse-set-region}). - -@item [M-drag-mouse-1] -Mark a region and copy it to kill ring and secondary clipboard -(@code{mouse-set-secondary}). - -@item C-w -@itemx [cut] -@itemx [S-delete] -The cut functions do not actually delete rows or columns---they copy -and then clear (@code{ses-kill-override}). - -@item C-y -@itemx [S-insert] -Paste from kill ring (@code{yank}). The paste functions behave -differently depending on the format of the text being inserted: -@itemize @bullet -@item -When pasting cells that were cut from a SES buffer, the print text is -ignored and only the attached formula and printer are inserted; cell -references in the formula are relocated unless you use @kbd{C-u}. -@item -The pasted text overwrites a rectangle of cells whose top left corner -is the current cell. If part of the rectangle is beyond the edges of -the spreadsheet, you must confirm the increase in spreadsheet size. -@item -Non-SES text is usually inserted as a replacement formula for the -current cell. If the formula would be a symbol, it's treated as a -string unless you use @kbd{C-u}. Pasted formulas with syntax errors -are always treated as strings. -@end itemize - -@item [paste] -Paste from primary clipboard or kill ring (@code{clipboard-yank}). - -@item [mouse-2] -Set point and paste from primary clipboard (@code{mouse-yank-at-click}). - -@item [M-mouse-2] -Set point and paste from secondary clipboard (@code{mouse-yank-secondary}). - -@item M-y -Immediately after a paste, you can replace the text with a preceding -element from the kill ring (@code{ses-yank-pop}). Unlike the standard -Emacs yank-pop, the SES version uses @code{undo} to delete the old -yank. This doesn't make any difference? -@end table - -@node Customizing SES, , Copy/cut/paste, The Basics -@section Customizing SES -@cindex customizing -@vindex enable-local-eval -@vindex ses-mode-hook -@vindex safe-functions -@vindex enable-local-eval - - -By default, a newly-created spreadsheet has 1 row and 1 column. The -column width is 7 and the default printer is @samp{"%.7g"}. Each of these -can be customized. Look in group ``ses''. - -After entering a cell value, point normally moves right to the next -cell. You can customize @code{ses-after-entry-functions} to move left or -up or down. For diagonal movement, select two functions from the -list. - -@code{ses-mode-hook} is a normal mode hook (list of functions to -execute when starting SES mode for a buffer). - -The variable @code{safe-functions} is a list of possibly-unsafe -functions to be treated as safe when analysing formulas and printers. -@xref{Virus protection}. Before customizing @code{safe-functions}, -think about how much you trust the person who's suggesting this -change. The value @code{t} turns off all anti-virus protection. A -list-of-functions value might enable a ``gee whiz'' spreadsheet, but it -also creates trapdoors in your anti-virus armor. In order for virus -protection to work, you must always press @kbd{n} when presented with -a virus warning, unless you understand what the questionable code is -trying to do. Do not listen to those who tell you to customize -@code{enable-local-eval}---this variable is for people who don't wear -safety belts! - - -@c =================================================================== - -@node Advanced Features, For Gurus, The Basics, Top -@chapter Advanced Features -@cindex advanced features -@findex ses-read-header-row - - -@table @kbd -@item C-c M-C-h -(@code{ses-set-header-row}). The header line at the top of the SES -window normally shows the column letter for each column. You can set -it to show a copy of some row, such as a row of column titles, so that -row will always be visible. Default is to set the current row as the -header; use C-u to prompt for header row. Set the header to row 0 to -show column letters again. -@item [header-line mouse-3] -Pops up a menu to set the current row as the header, or revert to -column letters. -@end table - -@menu -* The print area:: -* Ranges in formulas:: -* Sorting by column:: -* Standard formula functions:: -* More on cell printing:: -* Import and export:: -* Virus protection:: -* Spreadsheets with details and summary:: -@end menu - -@node The print area, Ranges in formulas, Advanced Features, Advanced Features -@section The print area -@cindex print area -@findex widen -@findex ses-renarrow-buffer -@findex ses-reprint-all - -A SES file consists of a print area and a data area. Normally the -buffer is narrowed to show only the print area. The print area is -read-only except for special SES commands; it contains cell values -formatted by printer functions. The data area records the formula and -printer functions, etc. - -@table @kbd -@item C-x n w -Show print and data areas (@code{widen}). - -@item C-c C-n -Show only print area (@code{ses-renarrow-buffer}). - -@item S-C-l -@itemx M-C-l -Recreate print area by reevaluating printer functions for all cells -(@code{ses-reprint-all}). -@end table - -@node Ranges in formulas, Sorting by column, The print area, Advanced Features -@section Ranges in formulas -@cindex ranges -@findex ses-insert-range-click -@findex ses-insert-range -@findex ses-insert-ses-range-click -@findex ses-insert-ses-range -@vindex from -@vindex to - -A formula like -@lisp -(+ A1 A2 A3) -@end lisp -is the sum of three specific cells. If you insert a new second row, -the formula becomes -@lisp -(+ A1 A3 A4) -@end lisp -and the new row is not included in the sum. - -The macro @code{(ses-range @var{from} @var{to})} evaluates to a list of -the values in a rectangle of cells. If your formula is -@lisp -(apply '+ (ses-range A1 A3)) -@end lisp -and you insert a new second row, it becomes -@lisp -(apply '+ (ses-range A1 A4)) -@end lisp -and the new row is included in the sum. - -While entering or editing a formula in the minibuffer, you can select -a range in the spreadsheet (using mouse or keyboard), then paste a -representation of that range into your formula. Suppose you select -A1-C1: - -@table @kbd -@item [S-mouse-3] -Inserts "A1 B1 C1" @code{(ses-insert-range-click}) - -@item C-c C-r -Keyboard version (@code{ses-insert-range}). - -@item [C-S-mouse-3] -Inserts "(ses-range A1 C1)" (@code{ses-insert-ses-range-click}). - -@item C-c C-s -Keyboard version (@code{ses-insert-ses-range}). -@end table - -If you delete the @var{from} or @var{to} cell for a range, the nearest -still-existing cell is used instead. If you delete the entire range, -the formula relocator will delete the ses-range from the formula. - -If you insert a new row just beyond the end of a one-column range, or -a new column just beyond a one-row range, the new cell is included in -the range. New cells inserted just before a range are not included. - - -@node Sorting by column, Standard formula functions, Ranges in formulas, Advanced Features -@section Sorting by column -@cindex sorting -@findex ses-sort-column -@findex ses-sort-column-click - -@table @kbd -@item C-c M-C-s -Sort the cells of a range using one of the columns -(@code{ses-sort-column}). The rows (or partial rows if the range -doesn't include all columns) are rearranged so the chosen column will -be in order. - -@item [header-line mouse-2] -The easiest way to sort is to click mouse-2 on the chosen column's header row -(@code{ses-sort-column-click}). -@end table - -The sort comparison uses @code{string<}, which works well for -right-justified numbers and left-justified strings. - -With prefix arg, sort is in descending order. - -Rows are moved one at a time, with relocation of formulas. This works -well if formulas refer to other cells in their row, not so well for -formulas that refer to other rows in the range or to cells outside the -range. - - -@node Standard formula functions, More on cell printing, Sorting by column, Advanced Features -@section Standard formula functions -@cindex standard formula functions -@cindex *skip* -@cindex *error* -@findex ses-delete-blanks -@findex ses-average -@findex ses+ - -Oftentimes you want a calculation to exclude the blank cells. Here -are some useful functions to call from your formulas: - -@table @code -@item (ses-delete-blanks &rest @var{args}) -Returns a list from which all blank cells (value is either @code{nil} or -'*skip*) have been deleted. - -@item (ses+ &rest @var{args}) -Sum of non-blank arguments. - -@item (ses-average @var{list}) -Average of non-blank elements in @var{list}. Here the list is passed -as a single argument, since you'll probably use it with @code{ses-range}. -@end table - -@node More on cell printing, Import and export, Standard formula functions, Advanced Features -@section More on cell printing -@cindex cell printing, more -@findex ses-truncate-cell -@findex ses-recalculate-cell - -Special cell values: -@itemize -@item nil prints the same as "", but allows previous cell to spill over. -@item '*skip* replaces nil when the previous cell actually does spill over; -nothing is printed for it. -@item '*error* indicates that the formula signaled an error instead of -producing a value: the print cell is filled with hash marks (#). -@end itemize - -If the result from the printer function is too wide for the cell and -the following cell is @code{nil}, the result will spill over into the -following cell. Very wide results can spill over several cells. If -the result is too wide for the available space (up to the end of the -row or the next non-@code{nil} cell), the result is truncated if the cell's -value is a string, or replaced with hash marks otherwise. - -SES could get confused by printer results that contain newlines or -tabs, so these are replaced with question marks. - -@table @kbd -@item t -Confine a cell to its own column (@code{ses-truncate-cell}). This -allows you to move point to a rightward cell that would otherwise be -covered by a spill-over. If you don't change the rightward cell, the -confined cell will spill over again the next time it is reprinted. - -@item c -When applied to a single cell, this command displays in the echo area -any formula error or printer error that occurred during -recalculation/reprinting (@code{ses-recalculate-cell}). You can use -this to undo the effect of @kbd{t}. -@end table - -When a printer function signals an error, the fallback printer -@samp{"%s"} is substituted. This is useful when your column printer -is numeric-only and you use a string as a cell value. Note that the -standard default printer is ``%.7g'' which is numeric-only, so cells -that are empty of contain strings will use the fallback printer. -@kbd{c} on such cells will display ``Format specifier doesn't match -argument type''. - - -@node Import and export, Virus protection, More on cell printing, Advanced Features -@section Import and export -@cindex import and export -@cindex export, and import -@findex ses-export-tsv -@findex ses-export-tsf - -@table @kbd -@item x t -Export a range of cells as tab-separated values (@code{ses-export-tsv}). -@item x T -Export a range of cells as tab-separated formulas (@code{ses-export-tsf}). -@end table - -The exported text goes to the kill ring --- you can paste it into -another buffer. Columns are separated by tabs, rows by newlines. - -To import text, use any of the yank commands where the text to paste -contains tabs and/or newlines. Imported formulas are not relocated. - -@node Virus protection, Spreadsheets with details and summary, Import and export, Advanced Features -@section Virus protection -@cindex virus protection - -Whenever a formula or printer is read from a file or is pasted into -the spreadsheet, it receives a ``needs safety check'' marking. Later, -when the formula or printer is evaluated for the first time, it is -checked for safety using the @code{unsafep} predicate; if found to be -``possibly unsafe'', the questionable formula or printer is displayed -and you must press Y to approve it or N to use a substitute. The -substitute always signals an error. - -Formulas or printers that you type in are checked immediately for -safety. If found to be possibly unsafe and you press N to disapprove, -the action is canceled and the old formula or printer will remain. - -Besides viruses (which try to copy themselves to other files), -@code{unsafep} can also detect all other kinds of Trojan horses, such as -spreadsheets that delete files, send email, flood Web sites, alter -your Emacs settings, etc. - -Generally, spreadsheet formulas and printers are simple things that -don't need to do any fancy computing, so all potentially-dangerous -parts of the Emacs Lisp environment can be excluded without cramping -your style as a formula-writer. See the documentation in @file{unsafep.el} -for more info on how Lisp forms are classified as safe or unsafe. - -@node Spreadsheets with details and summary, , Virus protection, Advanced Features -@section Spreadsheets with details and summary -@cindex details and summary -@cindex summary, and details - -A common organization for spreadsheets is to have a bunch of ``detail'' -rows, each perhaps describing a transaction, and then a set of -``summary'' rows that each show reduced data for some subset of the -details. SES supports this organization via the @code{ses-select} -function. - -@table @code -@item (ses-select @var{fromrange} @var{test} @var{torange}) -Returns a subset of @var{torange}. For each member in @var{fromrange} -that is equal to @var{test}, the corresponding member of @var{torange} -is included in the result. -@end table - -Example of use: -@lisp -(ses-average (ses-select (ses-range A1 A5) 'Smith (ses-range B1 B5))) -@end lisp -This computes the average of the B column values for those rows whose -A column value is the symbol 'Smith. - -Arguably one could specify only @var{fromrange} plus -@var{to-row-offset} and @var{to-column-offset}. The @var{torange} is -stated explicitly to ensure that the formula will be recalculated if -any cell in either range is changed. - -File @file{etc/ses-example.el} in the Emacs distribution is an example of a -details-and-summary spreadsheet. - - -@c =================================================================== - -@node For Gurus, Index, Advanced Features, Top -@chapter For Gurus -@cindex advanced features - -@menu -* Deferred updates:: -* Nonrelocatable references:: -* The data area:: -* Buffer-local variables in spreadsheets:: -* Uses of defadvice in SES:: -@end menu - -@node Deferred updates, Nonrelocatable references, For Gurus, For Gurus -@section Deferred updates -@cindex deferred updates -@cindex updates, deferred -@vindex run-with-idle-timer - -To save time by avoiding redundant computations, cells that need -recalculation due to changes in other cells are added to a set. At -the end of the command, each cell in the set is recalculated once. -This can create a new set of cells that need recalculation. The -process is repeated until either the set is empty or it stops changing -(due to circular references among the cells). In extreme cases, you -might see progress messages of the form ``Recalculating... (@var{nnn} -cells left)''. If you interrupt the calculation using @kbd{C-g}, the -spreadsheet will be left in an inconsistent state, so use @kbd{C-_} or -@kbd{C-c C-l} to fix it. - -To save even more time by avoiding redundant writes, cells that have -changes are added to a set instead of being written immediately to the -data area. Each cell in the set is written once, at the end of the -command. If you change vast quantities of cells, you might see a -progress message of the form ``Writing... (@var{nnn} cells left)''. -These deferred cell-writes cannot be interrupted by @kbd{C-g}, so -you'll just have to wait. - -SES uses @code{run-with-idle-timer} to move the cell underline when -Emacs will be scrolling the buffer after the end of a command, and -also to narrow and underline after @kbd{C-x C-v}. This is visible as -a momentary glitch after C-x C-v and certain scrolling commands. You -can type ahead without worrying about the glitch. - - -@node Nonrelocatable references, The data area, Deferred updates, For Gurus -@section Nonrelocatable references -@cindex nonrelocatable references -@cindex references, nonrelocatable - -@kbd{C-y} relocates all cell-references in a pasted formula, while -@kbd{C-u C-y} relocates none of the cell-references. What about mixed -cases? - -You can use -@lisp -(symbol-value 'B3) -@end lisp -to make an @dfn{absolute reference}. The formula relocator skips over -quoted things, so this will not be relocated when pasted or when -rows/columns are inserted/deleted. However, B3 will not be recorded -as a dependency of this cell, so this cell will not be updated -automatically when B3 is changed. - -The variables @code{row} and @code{col} are dynamically bound while a -cell formula is being evaluated. You can use -@lisp -(ses-cell-value row 0) -@end lisp -to get the value from the leftmost column in the current row. This -kind of dependency is also not recorded. - - -@node The data area, Buffer-local variables in spreadsheets, Nonrelocatable references, For Gurus -@section The data area -@cindex data area -@findex ses-reconstruct-all - -Begins with an 014 character, followed by sets of cell-definition -macros for each row, followed by column-widths, column-printers, -default-printer, and header-row. Then there's the global parameters -(file-format ID, numrows, numcols) and the local variables (specifying -SES mode for the buffer, etc.) - -When a SES file is loaded, first the numrows and numcols values are -loaded, then the entire data area is @code{eval}ed, and finally the local -variables are processed. - -You can edit the data area, but don't insert or delete any newlines -except in the local-variables part, since SES locates things by -counting newlines. Use @kbd{C-x C-e} at the end of a line to install -your edits into the spreadsheet data structures (this does not update -the print area, use e.g. @kbd{C-c C-l} for that). - -The data area is maintained as an image of spreadsheet data -structures that area stored in buffer-local variables. If the data -area gets messed up, you can try reconstructing the data area from the -data structures: - -@table @kbd -@item C-c M-C-l -(@code{ses-reconstruct-all}). -@end table - - -@node Buffer-local variables in spreadsheets, Uses of defadvice in SES, The data area, For Gurus -@section Buffer-local variables in spreadsheets -@cindex buffer-local variables -@cindex variables, buffer-local - -You can add additional local variables to the list at the bottom of -the data area, such as hidden constants you want to refer to in your -formulas. - -You can override the variable @code{ses--symbolic-formulas} to be a list of -symbols (as parenthesized strings) to show as completions for the ' -command. This initial completions list is used instead of the actual -set of symbols-as-formulas in the spreadsheet. - -For an example of this, see file @file{etc/ses-example.ses}. - -If (for some reason) you want your formulas or printers to save data -into variables, you must declare these variables as buffer-locals in -order to avoid a virus warning. - -You can define functions by making them values for the fake local -variable @code{eval}. Such functions can then be used in your -formulas and printers, but usually each @code{eval} is presented to -the user during file loading as a potential virus --- this can get -annoying. - -You can define functions in your @file{.emacs} file. Other people can -still read the print area of your spreadsheet, but they won't be able -to recalculate or reprint anything that depends on your functions. To -avoid virus warnings, each function used in a formula needs -@lisp -(put 'your-function-name 'safe-function t) -@end lisp - -@node Uses of defadvice in SES, , Buffer-local variables in spreadsheets, For Gurus -@section Uses of defadvice in SES -@cindex defadvice -@cindex undo-more -@cindex copy-region-as-kill -@cindex yank - -@table @code -@item undo-more -Defines a new undo element format (@var{fun} . @var{args}), which -means ``undo by applying @var{fun} to @var{args}''. For spreadsheet -buffers, it allows undos in the data area even though that's outside -the narrowing. - -@item copy-region-as-kill -When copying from the print area of a spreadsheet, treat the region as -a rectangle and attach each cell's formula and printer as 'ses -properties. - -@item yank -When yanking into the print area of a spreadsheet, first try to yank -as cells (if the yank text has 'ses properties), then as tab-separated -formulas, then (if all else fails) as a single formula for the current -cell. -@end table - -@c =================================================================== -@node Index, Acknowledgements, For Gurus, Top -@unnumbered Index - -@printindex cp - -@c =================================================================== - -@node Acknowledgements, GNU Free Documentation License, Index, Top -@chapter Acknowledgements - -Coding by: -@quotation -Jonathan Yavner @email{jyavner@@member.fsf.org}@* -Stefan Monnier @email{monnier@@gnu.org}@* -Shigeru Fukaya @email{shigeru.fukaya@@gmail.com} -@end quotation - -@noindent -Texinfo manual by: -@quotation -Jonathan Yavner @email{jyavner@@member.fsf.org}@* -Brad Collins -@end quotation - -@noindent -Ideas from: -@quotation -Christoph Conrad @email{christoph.conrad@@gmx.de}@* -CyberBob @email{cyberbob@@redneck.gacracker.org}@* -Syver Enstad @email{syver-en@@online.no}@* -Ami Fischman @email{fischman@@zion.bpnetworks.com}@* -Thomas Gehrlein @email{Thomas.Gehrlein@@t-online.de}@* -Chris F.A. Johnson @email{c.f.a.johnson@@rogers.com}@* -Yusong Li @email{lyusong@@hotmail.com}@* -Juri Linkov @email{juri@@jurta.org}@* -Harald Maier @email{maierh@@myself.com}@* -Alan Nash @email{anash@@san.rr.com}@* -François Pinard @email{pinard@@iro.umontreal.ca}@* -Pedro Pinto @email{ppinto@@cs.cmu.edu}@* -Stefan Reichör @email{xsteve@@riic.at}@* -Oliver Scholz @email{epameinondas@@gmx.de}@* -Richard M. Stallman @email{rms@@gnu.org}@* -Luc Teirlinck @email{teirllm@@dms.auburn.edu}@* -J. Otto Tennant @email{jotto@@pobox.com}@* -Jean-Philippe Theberge @email{jphil@@acs.pagesjaunes.fr} -@end quotation - -@c =================================================================== - -@node GNU Free Documentation License, , Acknowledgements, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@bye - -@ignore - arch-tag: 10a4ee1c-7ef4-4c06-8b7a-f975e39f0dec -@end ignore diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi deleted file mode 100644 index 19848426f0b..00000000000 --- a/doc/misc/sieve.texi +++ /dev/null @@ -1,362 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/sieve -@settitle Emacs Sieve Manual -@synindex fn cp -@synindex vr cp -@synindex pg cp - -@copying -This file documents the Emacs Sieve package, for server-side mail filtering. - -Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Sieve: (sieve). Managing Sieve scripts in Emacs. -@end direntry -@iftex -@finalout -@end iftex -@setchapternewpage odd - -@titlepage -@title Emacs Sieve Manual - -@author by Simon Josefsson -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@node Top -@top Sieve Support for Emacs - -This is intended as a users manual for Sieve Mode and Manage Sieve, and -as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp -API. - -Sieve is a language for server-side filtering of mail. The language -is documented in RFC 3028. This manual does not attempt to document -the language, so keep RFC 3028 around. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Installation:: Getting ready to use the package. -* Sieve Mode:: Editing Sieve scripts. -* Managing Sieve:: Managing Sieve scripts on a remote server. -* Examples :: A few Sieve code snippets. -* Manage Sieve API :: Interfacing to the Manage Sieve Protocol API. -* Standards:: A summary of RFCs and working documents used. -* GNU Free Documentation License:: The license for this documentation. -* Index:: Function and variable index. -@end menu - - -@node Installation -@chapter Installation -@cindex Install -@cindex Setup - -The Sieve package should come with your Emacs version, and should be -ready for use directly. - -However, to manually set up the package you can put the following -commands in your @code{~/.emacs}: - -@lisp -(autoload 'sieve-mode "sieve-mode") -@end lisp -@lisp -(setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode) - auto-mode-alist)) -@end lisp - - -@node Sieve Mode -@chapter Sieve Mode - -Sieve mode provides syntax-based indentation, font-locking support and -other handy functions to make editing Sieve scripts easier. - -Use @samp{M-x sieve-mode} to switch to this major mode. This command -runs the hook @code{sieve-mode-hook}. - -@vindex sieve-mode-map -@vindex sieve-mode-syntax-table -Sieve mode is derived from @code{c-mode}, and is very similar except -for the syntax of comments. The keymap (@code{sieve-mode-map}) is -inherited from @code{c-mode}, as are the variables for customizing -indentation. Sieve mode has its own abbrev table -(@code{sieve-mode-abbrev-table}) and syntax table -(@code{sieve-mode-syntax-table}). - -In addition to the editing utility functions, Sieve mode also contains -bindings to manage Sieve scripts remotely. @xref{Managing Sieve}. - -@table @kbd - -@item C-c RET -@kindex C-c RET -@findex sieve-manage -@cindex manage remote sieve script -Open a connection to a remote server using the Managesieve protocol. - -@item C-c C-l -@kindex C-c C-l -@findex sieve-upload -@cindex upload sieve script -Upload the Sieve script to the currently open server. - -@end table - - -@node Managing Sieve -@chapter Managing Sieve - -Manage Sieve is a special mode used to display Sieve scripts available -on a remote server. It can be invoked with @kbd{M-x sieve-manage -RET}, which queries the user for a server and if necessary, user -credentials to use. - -When a server has been successfully contacted, the Manage Sieve buffer -looks something like: - -@example -Server : mailserver:2000 - -2 scripts on server, press RET on a script name edits it, or -press RET on to create a new script. - - ACTIVE .sieve - template.siv -@end example - -One of the scripts are highlighted, and standard point navigation -commands (@kbd{}, @kbd{} etc) can be used to navigate the -list. - -The following commands are available in the Manage Sieve buffer: - -@table @kbd - -@item m -@kindex m -@findex sieve-activate -Activates the currently highlighted script. - -@item u -@kindex u -@findex sieve-deactivate -Deactivates the currently highlighted script. - -@item C-M-? -@kindex C-M-? -@findex sieve-deactivate-all -Deactivates all scripts. - -@item r -@kindex r -@findex sieve-remove -Remove currently highlighted script. - -@item RET -@item mouse-2 -@item f -@kindex RET -@kindex mouse-2 -@kindex f -@findex sieve-edit-script -Bury the server buffer and download the currently highlighted script -into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}). - -@item o -@kindex o -@findex sieve-edit-script-other-window -Create a new buffer in another window containing the currently -highlighted script for editing in Sieve mode (@pxref{Sieve Mode}). - -@item q -@kindex q -@findex sieve-bury-buffer -Bury the Manage Sieve buffer without closing the connection. - -@item ? -@item h -@kindex ? -@kindex h -@findex sieve-help -Displays help in the minibuffer. - -@end table - -@node Examples -@chapter Examples - -If you are not familiar with Sieve, this chapter contains a few simple -code snippets that you can cut'n'paste and modify at will, until you -feel more comfortable with the Sieve language to write the rules from -scratch. - -The following complete Sieve script places all messages with a matching -@samp{Sender:} header into the given mailbox. Many mailing lists uses -this format. The first line makes sure your Sieve server understands -the @code{fileinto} command. - -@example -require "fileinto"; - -if address "sender" "owner-w3-beta@@xemacs.org" @{ - fileinto "INBOX.w3-beta"; -@} -@end example - -A few mailing lists do not use the @samp{Sender:} header, but has a -unique identifier in some other header. The following is not a -complete script, it assumes that @code{fileinto} has already been -required. - -@example -if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{ - fileinto "INBOX.auc-tex"; -@} -@end example - -At last, we have the hopeless mailing lists that does not have any -unique identifier and you are forced to match on the @samp{To:} and -@samp{Cc} headers. As before, this snippet assumes that @code{fileinto} -has been required. - -@example -if address ["to", "cc"] "kerberos@@mit.edu" @{ - fileinto "INBOX.kerberos"; -@} -@end example - -@node Manage Sieve API -@chapter Manage Sieve API - -The @file{sieve-manage.el} library contains low-level functionality -for talking to a server with the @sc{managesieve} protocol. - -A number of user-visible variables exist, which all can be customized -in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}): - -@table @code - -@item sieve-manage-default-user -@vindex sieve-manage-default-user -Sets the default username. - -@item sieve-manage-default-port -@vindex sieve-manage-default-port -Sets the default port to use, the suggested port number is @code{2000}. - -@item sieve-manage-log -@vindex sieve-manage-log -If non-@code{nil}, should be a string naming a buffer where a protocol trace -is dumped (for debugging purposes). - -@end table - -The API functions include: - -@table @code - -@item sieve-manage-open -@findex sieve-manage-open -Open connection to managesieve server, returning a buffer to be used -by all other API functions. - -@item sieve-manage-opened -@findex sieve-manage-opened -Check if a server is open or not. - -@item sieve-manage-close -@findex sieve-manage-close -Close a server connection. - -@item sieve-manage-authenticate -@findex sieve-manage-authenticate -Authenticate to the server. - -@item sieve-manage-capability -@findex sieve-manage-capability -Return a list of capabilities the server supports. - -@item sieve-manage-listscripts -@findex sieve-manage-listscripts -List scripts on the server. - -@item sieve-manage-havespace -@findex sieve-manage-havespace -Return non-@code{nil} if the server has room for a script of given -size. - -@item sieve-manage-getscript -@findex sieve-manage-getscript -Download script from server. - -@item sieve-manage-putscript -@findex sieve-manage-putscript -Upload script to server. - -@item sieve-manage-setactive -@findex sieve-manage-setactive -Indicate which script on the server should be active. - -@end table - -@node Standards -@chapter Standards - -The Emacs Sieve package implements all or parts of a small but -hopefully growing number of RFCs and drafts documents. This chapter -lists the relevant ones. They can all be fetched from -@uref{http://quimby.gnus.org/notes/}. - -@table @dfn - -@item RFC3028 -Sieve: A Mail Filtering Language. - -@item draft-martin-managesieve-03 -A Protocol for Remotely Managing Sieve Scripts - -@end table - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index -@unnumbered Index -@printindex cp - -@bye - -@c End: - -@ignore - arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3 -@end ignore diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi deleted file mode 100644 index 848da3ec6ea..00000000000 --- a/doc/misc/smtpmail.texi +++ /dev/null @@ -1,421 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/smtpmail -@settitle Emacs SMTP Library -@syncodeindex vr fn -@copying -Copyright @copyright{} 2003, 2004, 2005, 2006, 2007, 2008, 2009 -Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* SMTP: (smtpmail). Emacs library for sending mail via SMTP. -@end direntry - -@titlepage -@title{Emacs SMTP Library} -@subtitle{An Emacs package for sending mail via SMTP} -@author{Simon Josefsson, Alex Schroeder} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top Emacs SMTP Library - -@insertcopying -@end ifnottex - -@menu -* How Mail Works:: Brief introduction to mail concepts. -* Emacs Speaks SMTP:: How to use the SMTP library in Emacs. -* Authentication:: Authenticating yourself to the server. -* Queued delivery:: Sending mail without an internet connection. -* Server workarounds:: Mail servers with special requirements. -* Debugging:: Tracking down problems. -* GNU Free Documentation License:: The license for this documentation. - -Indices - -* Index:: Index over variables and functions. -@end menu - -@node How Mail Works -@chapter How Mail Works - -@cindex SMTP -@cindex MTA - On the internet, mail is sent from mail host to mail host using the -simple mail transfer protocol (SMTP). To send and receive mail, you -must get it from and send it to a mail host. Every mail host runs a -mail transfer agent (MTA) such as Exim that accepts mails and passes -them on. The communication between a mail host and other clients does -not necessarily involve SMTP, however. Here is short overview of what -is involved. - -@cindex MUA - The mail program --- also called a mail user agent (MUA) --- -usually sends outgoing mail to a mail host. When your computer is -permanently connected to the internet, it might even be a mail host -itself. In this case, the MUA will pipe mail to the -@file{/usr/lib/sendmail} application. It will take care of your mail -and pass it on to the next mail host. - -@cindex ISP - When you are only connected to the internet from time to time, your -internet service provider (ISP) has probably told you which mail host -to use. You must configure your MUA to use that mail host. Since you -are reading this manual, you probably want to configure Emacs to use -SMTP to send mail to that mail host. More on that in the next -section. - -@cindex MDA - Things are different when reading mail. The mail host responsible -for your mail keeps it in a file somewhere. The messages get into the -file by way of a mail delivery agent (MDA) such as procmail. These -delivery agents often allow you to filter and munge your mails before -you get to see it. When your computer is that mail host, this file is -called a spool, and sometimes located in the directory -@file{/var/spool/mail/}. All your MUA has to do is read mail from the -spool, then. - -@cindex POP3 -@cindex IMAP - When your computer is not always connected to the internet, you -must get the mail from the remote mail host using a protocol such as -POP3 or IMAP. POP3 essentially downloads all your mail from the mail -host to your computer. The mail is stored in some file on your -computer, and again, all your MUA has to do is read mail from the -spool. - - When you read mail from various machines, downloading mail from the -mail host to your current machine is not convenient. In that case, -you will probably want to use the IMAP protocol. Your mail is kept on -the mail host, and you can read it while you are connected via IMAP to -the mail host. - -@cindex Webmail - So how does reading mail via the web work, you ask. In that case, -the web interface just allows you to remote-control a MUA on the web -host. Whether the web host is also a mail host, and how all the -pieces interact is completely irrelevant. You usually cannot use -Emacs to read mail via the web, unless you use software that parses -the ever-changing HTML of the web interface. - -@node Emacs Speaks SMTP -@chapter Emacs Speaks SMTP - - Emacs includes a package for sending your mail to a SMTP server and -have it take care of delivering it to the final destination, rather -than letting the MTA on your local system take care of it. This can -be useful if you don't have a MTA set up on your host, or if your -machine is often disconnected from the internet. - - Sending mail via SMTP requires configuring your mail user agent -(@pxref{Mail Methods,,,emacs}) to use the SMTP library. How to do -this should be described for each mail user agent; for the default -mail user agent the variable @code{send-mail-function} (@pxref{Mail -Sending,,,emacs}) is used; for the Message and Gnus user agents the -variable @code{message-send-mail-function} (@pxref{Mail -Variables,,,message}) is used. - -@example -;; If you use the default mail user agent. -(setq send-mail-function 'smtpmail-send-it) -;; If you use Message or Gnus. -(setq message-send-mail-function 'smtpmail-send-it) -@end example - - Before using SMTP you must find out the hostname of the SMTP server -to use. Your system administrator should provide you with this -information, but often it is the same as the server you receive mail -from. - -@table @code -@item smtpmail-smtp-server -@vindex smtpmail-smtp-server -@vindex SMTPSERVER - The variable @code{smtpmail-smtp-server} controls the hostname of -the server to use. It is a string with an IP address or hostname. It -defaults to the contents of the @env{SMTPSERVER} environment -variable, or, if empty, the contents of -@code{smtpmail-default-smtp-server}. - -@item smtpmail-default-smtp-server -@vindex smtpmail-default-smtp-server - The variable @code{smtpmail-default-smtp-server} controls the -default hostname of the server to use. It is a string with an IP -address or hostname. It must be set before the SMTP library is -loaded. It has no effect if set after the SMTP library has been -loaded, or if @code{smtpmail-smtp-server} is defined. It is usually -set by system administrators in a site wide initialization file. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP server name. - -@example -;; Send mail using SMTP via mail.example.org. -(setq smtpmail-smtp-server "mail.example.org") -@end example - -@cindex Mail Submission -SMTP is normally used on the registered ``smtp'' TCP service port 25. -Some environments use SMTP in ``Mail Submission'' mode, which uses -port 587. Using other ports is not uncommon, either for security by -obscurity purposes, port forwarding, or otherwise. - -@table @code -@item smtpmail-smtp-service -@vindex smtpmail-smtp-service - The variable @code{smtpmail-smtp-service} controls the port on the -server to contact. It is either a string, in which case it will be -translated into an integer using system calls, or an integer. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to set the SMTP service port. - -@example -;; Send mail using SMTP on the mail submission port 587. -(setq smtpmail-smtp-service 587) -@end example - -@node Authentication -@chapter Authentication - -@cindex SASL -@cindex CRAM-MD5 -@cindex LOGIN -@cindex STARTTLS -@cindex TLS -@cindex SSL -Many environments require SMTP clients to authenticate themselves -before they are allowed to route mail via a server. The two following -variables contains the authentication information needed for this. - -The first variable, @code{smtpmail-auth-credentials}, instructs the -SMTP library to use a SASL authentication step, currently only the -CRAM-MD5 and LOGIN mechanisms are supported and will be selected in -that order if the server support both. - -The second variable, @code{smtpmail-starttls-credentials}, instructs -the SMTP library to connect to the server using STARTTLS. This means -the protocol exchange may be integrity protected and confidential by -using the Transport Layer Security (TLS) protocol, and optionally also -authentication of the client and server. - -TLS is a security protocol that is also known as SSL, although -strictly speaking, SSL is an older variant of TLS. TLS is backwards -compatible with SSL. In most mundane situations, the two terms are -equivalent. - -The TLS feature uses the elisp package @file{starttls.el} (see it for -more information on customization), which in turn require that at -least one of the following external tools are installed: - -@enumerate -@item -The GNUTLS command line tool @samp{gnutls-cli}, you can get it from -@url{http://www.gnu.org/software/gnutls/}. This is the recommended -tool, mainly because it can verify the server certificates. - -@item -The @samp{starttls} external program, you can get it from -@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. -@end enumerate - -It is not uncommon to use both these mechanisms, e.g., to use STARTTLS -to achieve integrity and confidentiality and then use SASL for client -authentication. - -@table @code -@item smtpmail-auth-credentials -@vindex smtpmail-auth-credentials - The variable @code{smtpmail-auth-credentials} contains a list of -hostname, port, username and password tuples. When the SMTP library -connects to a host on a certain port, this variable is searched to -find a matching entry for that hostname and port. If an entry is -found, the authentication process is invoked and the credentials are -used. - -The hostname field follows the same format as -@code{smtpmail-smtp-server} (i.e., a string) and the port field the -same format as @code{smtpmail-smtp-service} (i.e., a string or an -integer). The username and password fields, which either can be -@code{nil} to indicate that the user is prompted for the value -interactively, should be strings with the username and password, -respectively, information that is normally provided by system -administrators. - -@item smtpmail-starttls-credentials -@vindex smtpmail-starttls-credentials - The variable @code{smtpmail-starttls-credentials} contains a list of -tuples with hostname, port, name of file containing client key, and -name of file containing client certificate. The processing is similar -to the previous variable. The client key and certificate may be -@code{nil} if you do not wish to use client authentication. -@end table - -The following example illustrates what you could put in -@file{~/.emacs} to enable both SASL authentication and STARTTLS. The -server name (@code{smtpmail-smtp-server}) is @var{hostname}, the -server port (@code{smtpmail-smtp-service}) is @var{port}, and the -username and password are @var{username} and @var{password} -respectively. - -@example -;; Authenticate using this username and password against my server. -(setq smtpmail-auth-credentials - '(("@var{hostname}" "@var{port}" "@var{username}" "@var{password}"))) - -;; Note that if @var{port} is an integer, you must not quote it as a -;; string. Normally @var{port} should be the integer 25, and the example -;; become: -(setq smtpmail-auth-credentials - '(("@var{hostname}" 25 "@var{username}" "@var{password}"))) - -;; Use STARTTLS without authentication against the server. -(setq smtpmail-starttls-credentials - '(("@var{hostname}" "@var{port}" nil nil))) -@end example - -@node Queued delivery -@chapter Queued delivery - -@cindex Dialup connection -If you connect to the internet via a dialup connection, or for some -other reason don't have permanent internet connection, sending mail -will fail when you are not connected. The SMTP library implements -queued delivery, and the following variable control its behavior. - -@table @code -@item smtpmail-queue-mail -@vindex smtpmail-queue-mail - The variable @code{smtpmail-queue-mail} controls whether a simple -off line mail sender is active. This variable is a boolean, and -defaults to @code{nil} (disabled). If this is non-@code{nil}, mail is -not sent immediately but rather queued in the directory -@code{smtpmail-queue-dir} and can be later sent manually by invoking -@code{smtpmail-send-queued-mail} (typically when you connect to the -internet). - -@item smtpmail-queue-dir -@vindex smtpmail-queue-dir - The variable @code{smtpmail-queue-dir} specifies the name of the -directory to hold queued messages. It defaults to -@file{~/Mail/queued-mail/}. -@end table - -@findex smtpmail-send-queued-mail - The function @code{smtpmail-send-queued-mail} can be used to send -any queued mail when @code{smtpmail-queue-mail} is enabled. It is -typically invoked interactively with @kbd{M-x -smtpmail-send-queued-mail RET} when you are connected to the internet. - -@node Server workarounds -@chapter Server workarounds - -Some SMTP servers have special requirements. The following variables -implement support for common requirements. - -@table @code - -@item smtpmail-local-domain -@vindex smtpmail-local-domain - The variable @code{smtpmail-local-domain} controls the hostname sent -in the first @code{EHLO} or @code{HELO} command sent to the server. -It should only be set if the @code{system-name} function returns a -name that isn't accepted by the server. Do not set this variable -unless your server complains. - -@item smtpmail-sendto-domain -@vindex smtpmail-sendto-domain - The variable @code{smtpmail-sendto-domain} makes the SMTP library -add @samp{@@} and the specified value to recipients specified in the -message when they are sent using the @code{RCPT TO} command. Some -configurations of sendmail requires this behavior. Don't bother to -set this unless you have get an error like: - -@example - Sending failed; SMTP protocol error -@end example - -when sending mail, and the debug buffer (@pxref{Debugging})) contains -an error such as: - -@example - RCPT TO: @var{someone} - 501 @var{someone}: recipient address must contain a domain -@end example - -@end table - - -@node Debugging -@chapter Debugging - -Sometimes delivery fails, often with the generic error message -@samp{Sending failed; SMTP protocol error}. Enabling one or both of -the following variables and inspecting a trace buffer will often give -clues to the reason for the error. - -@table @code - -@item smtpmail-debug-info -@vindex smtpmail-debug-info - The variable @code{smtpmail-debug-info} controls whether to print -the SMTP protocol exchange in the minibuffer, and retain the entire -exchange in a buffer @samp{*trace of SMTP session to @var{server}*}, -where @var{server} is the name of the mail server to which you send -mail. - -@item smtpmail-debug-verb -@vindex smtpmail-debug-verb - The variable @code{smtpmail-debug-verb} controls whether to send the -@code{VERB} token to the server. The @code{VERB} server instructs the -server to be more verbose, and often also to attempt final delivery -while your SMTP session is still running. It is usually only useful -together with @code{smtpmail-debug-info}. Note that this may cause -mail delivery to take considerable time if the final destination -cannot accept mail. - -@end table - -@node GNU Free Documentation License -@chapter GNU Free Documentation License -@include doclicense.texi - -@node Index -@chapter Index - -@section Concept Index - -@printindex cp - -@section Function and Variable Index - -@printindex fn - -@bye - -@ignore - arch-tag: 6316abdf-b366-4562-87a2-f37e8f894b6f -@end ignore diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi deleted file mode 100644 index 2e6e27330ec..00000000000 --- a/doc/misc/speedbar.texi +++ /dev/null @@ -1,1259 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/speedbar -@settitle Speedbar: File/Tag summarizing utility -@syncodeindex fn cp - -@copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* Speedbar: (speedbar). File/Tag summarizing utility. -@end direntry - -@titlepage -@sp 10 -@center @titlefont{Speedbar} -@sp 2 -@center Eric Ludlam -@vskip 0pt plus 1 fill -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top, , , (dir)Top -@comment node-name, next, previous, up - -Speedbar is a program for Emacs which can be used to summarize -information related to the current buffer. Its original inspiration -is the `explorer' often used in modern development environments, office -packages, and web browsers. - -Speedbar displays a narrow frame in which a tree view is shown. This -tree view defaults to containing a list of files and directories. Files -can be `expanded' to list tags inside. Directories can be expanded to -list the files within itself. Each file or tag can be jumped to -immediately. - -Speedbar expands upon `explorer' windows by maintaining context with the -user. For example, when using the file view, the current buffer's file -is highlighted. Speedbar also mimics the explorer windows by providing -multiple display modes. These modes come in two flavors. Major display -modes remain consistent across buffers, and minor display modes appear -only when a buffer of the applicable type is shown. This allows -authors of other packages to provide speedbar summaries customized to -the needs of that mode. - -Throughout this manual, activities are defined as `clicking on', or -`expanding' items. Clicking means using @kbd{Mouse-2} on a -button. Expanding refers to clicking on an expansion button to display -an expanded summary of the entry the expansion button is -on. @xref{Basic Navigation}. - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Introduction:: Basics of speedbar. -* Basic Navigation:: Basics of speedbar common between all modes. -* File Mode:: Summarizing files. -* Buffer Mode:: Summarizing buffers. -* Minor Modes:: Additional minor modes such as Info and RMAIL. -* Customizing:: Changing speedbar behavior. -* Extending:: Extend speedbar for your own project. -* GNU Free Documentation License:: The license for this documentation. -* Index:: -@end menu - -@node Introduction, Basic Navigation, , Top -@comment node-name, next, previous, up -@chapter Introduction -@cindex introduction - -To start using speedbar use the command @kbd{M-x speedbar RET} or -select it from the @samp{Options->Show/Hide} sub-menu. This command -will open a new frame to summarize the local files. On X Window -systems or on MS-Windows, speedbar's frame is twenty characters wide, -and will mimic the height of the frame from which it was started. It -positions itself to the left or right of the frame you started it -from. - -To use speedbar effectively, it is important to understand its -relationship with the frame you started it from. This frame is the -@dfn{attached frame} which speedbar will use as a reference point. Once -started, speedbar watches the contents of this frame, and attempts to -make its contents relevant to the buffer loaded into the attached -frame. In addition, all requests made in speedbar that require the -display of another buffer will display in the attached frame. - -When used in terminal mode, the new frame appears the same size as the -terminal. Since it is not visible while working in the attached frame, -speedbar will save time by using the @dfn{slowbar mode}, where no tracking is -done until speedbar is requested to show itself (i.e., the speedbar's -frame becomes the selected frame). - -@cindex @code{speedbar-get-focus} -The function to use when switching between frames using the keyboard is -@code{speedbar-get-focus}. This function will toggle between frames, and -it's useful to bind it to a key in terminal mode. @xref{Customizing}. - -@node Basic Navigation, File Mode, Introduction, Top -@comment node-name, next, previous, up -@chapter Basic Navigation - -Speedbar can display different types of data, and has several display -and behavior modes. These modes all have a common behavior, menu -system, and look. If one mode is learned, then the other modes are easy -to use. - -@menu -* Basic Key Bindings:: -* Basic Visuals:: -* Mouse Bindings:: -* Displays Submenu:: -@end menu - -@node Basic Key Bindings, Basic Visuals, Basic Navigation, Basic Navigation -@comment node-name, next, previous, up -@section Basic Key Bindings -@cindex key bindings - -These key bindings are common across all modes: - -@table @kbd -@item Q -@cindex quitting speedbar -Quit speedbar, and kill the frame. -@item q -Quit speedbar, and hide the frame. This makes it faster to restore the -speedbar frame, than if you press @kbd{Q}. -@item g -@cindex refresh speedbar display -Refresh whatever contents are in speedbar. -@item t -@cindex slowbar mode -Toggle speedbar to and from slowbar mode. In slowbar mode, frame -tracking is not done. -@item n -@itemx p -@cindex navigation -Move, respectively, to the next or previous item. A summary of that -item will be displayed in the attached frame's minibuffer. -@item M-n -@itemx M-p -Move to the next or previous item in a restricted fashion. If a list is -open, the cursor will skip over it. If the cursor is in an open list, -it will not leave it. -@item C-M-n -@itemx C-M-n -Move forwards and backwards across extended groups. This lets you -quickly skip over all files, directories, or other common sub-items at -the same current depth. -@item C-x b -Switch buffers in the attached frame. -@end table - -Speedbar can handle multiple modes. Two are provided by default. -These modes are File mode, and Buffers mode. There are accelerators to -switch into these different modes. - -@cindex mode switching hotkeys -@table @kbd -@item b -Switch into Quick Buffers mode (@pxref{Buffer Mode}). After one use, the -previous display mode is restored. -@item f -Switch into File mode. -@item r -Switch back to the previous mode. -@end table - -Some modes provide groups, lists and tags. @xref{Basic Visuals}. When -these are available, some additional common bindings are available. - -@cindex common keys -@table @kbd -@item RET -@itemx e -Edit/Open the current group or tag. This behavior is dependent on the -mode. In general, files or buffers are opened in the attached frame, -and directories or group nodes are expanded locally. -@item + -@itemx = -Expand the current group, displaying sub items. -When used with a prefix argument, any data that may have been cached is -flushed. This is similar to a power click. @xref{Mouse Bindings}. -@item - -Contract the current group, hiding sub items. -@end table - -@node Basic Visuals, Mouse Bindings, Basic Key Bindings, Basic Navigation -@comment node-name, next, previous, up -@section Basic Visuals -@cindex visuals - -Speedbar has visual cues for indicating different types of data. These -cues are used consistently across the different speedbar modes to make -them easier to interpret. - -At a high level, in File mode, there are directory buttons, sub -directory buttons, file buttons, tag buttons, and expansion buttons. -This makes it easy to use the mouse to navigate a directory tree, and -quickly view files, or a summary of those files. - -The most basic visual effect used to distinguish between these button -types is color and mouse highlighting. Anything the mouse highlights -can be clicked on and is called a button (@pxref{Mouse Bindings}). -Anything not highlighted by the mouse will not be clickable. - -Text in speedbar consists of four different types of data. Knowing how -to read these textual elements will make it easier to navigate by -identifying the types of data available. - -@subsubsection Groups -@cindex groups - -Groups summarize information in a single line, and provide a high level -view of more complex systems, like a directory tree, or manual chapters. - -Groups appear at different indentation levels, and are prefixed with a -@samp{+} in some sort of `box'. The group name will summarize the -information within it, and the expansion box will display that -information inline. In File mode, directories and files are `groups' -where the @samp{+} is surrounded by brackets like this: - -@example -<+> include -<-> src - [+] foo.c -@end example - -In this example, we see both open and closed directories, in addition to -a file. The directories have a box consisting of angle brackets, and a -file uses square brackets. - -In all modes, a group can be `edited' by pressing @kbd{RET}, meaning a -file will be opened, or a directory explicitly opened in speedbar. A -group can be expanded or contracted using @kbd{+} or -@kbd{-}. @xref{Basic Key Bindings}. - -Sometimes groups may have a @samp{?} in its indicator box. This means -that it is a group type, but there are no contents, or no known way of -extracting contents of that group. - -When a group has been expanded, the indicator button changes from -@samp{+} to @samp{-}. This indicates that the contents are being shown. -Click the @samp{-} button to contract the group, or hide the contents -currently displayed. - -@subsubsection Tags -@cindex tags - -Tags are the leaf nodes of the tree system. Tags are generally prefixed -with a simple character, such as @samp{>}. Tags can only be jumped to using -@kbd{RET} or @kbd{e}. - -@subsubsection Boolean Flags - -Sometimes a group or tag is given a boolean flag. These flags appear as -extra text characters at the end of the line. File mode uses boolean -flags, such as a @samp{*} to indicate that a file has been checked out -of a versioning system. - -For additional flags, see -@c Note to self, update these to sub-nodes which are more relevant. -@ref{File Mode}, and @ref{Version Control}. - -@subsubsection Unadorned Text - -Unadorned text generally starts in column 0, without any special symbols -prefixing them. In Buffers mode different buffer groups are prefixed -with a description of what the following buffers are (Files, scratch -buffers, and invisible buffers.) - -Unadorned text will generally be colorless, and not clickable. - -@subsubsection Color Cues - -Each type of Group, item indicator, and label is given a different -color. The colors chosen are dependent on whether the background color -is light or dark. -Of important note is that the `current item', which may be a buffer or -file name, is highlighted red, and underlined. - -Colors can be customized from the group @code{speedbar-faces}. Some -modes, such as for Info, will use the Info colors instead of default -speedbar colors as an indication of what is currently being displayed. - -The face naming convention mirrors the File display mode. Modes which -do not use files will attempt to use the same colors on analogous -entries. - -@node Mouse Bindings, Displays Submenu, Basic Visuals, Basic Navigation -@comment node-name, next, previous, up -@section Mouse Bindings -@cindex mouse bindings - -The mouse has become a common information navigation tool. Speedbar -will use the mouse to navigate file systems, buffer lists, and other -data. The different textual cues provide buttons which can be clicked -on (@pxref{Basic Visuals}). Anything that highlights can be clicked on -with the mouse, or affected by the menu. - -The mouse bindings are: - -@table @kbd -@item Mouse-1 -Move cursor to that location. -@item Mouse-2 -@itemx Double-Mouse-1 -Activate the current button. @kbd{Double-Mouse-1} is called a @dfn{double -click} on other platforms, and is useful for windows users with two -button mice. -@c Isn't it true that with two-button mice, the right button is Mouse-2? -@c On GNU/Linux, the right button is Mouse-3. -@item S-Mouse-2 -@itemx S-Double-Mouse-1 -@cindex power click -This has the same effect as @kbd{Mouse-2}, except it is called a power -click. This means that if a group with an expansion button @samp{+} is -clicked, any caches are flushed, and subitems re-read. If it is a name, -it will be opened in a new frame. -@item Mouse-3 -Activate the speedbar menu. The item selected affects the line clicked, -not the line where the cursor was. -@item Mouse-1 @r{(mode line)} -Activate the menu. This affects the item the cursor is on before the -click, since the mouse was not clicked on anything. -@item C-Mouse-1 -Buffers sub-menu. The buffer in the attached frame is switched. -@end table - -When the mouse moves over buttons in speedbar, details of that item -should be displayed in the minibuffer of the attached frame. Sometimes -this can contain extra information such as file permissions, or tag -location. - -@node Displays Submenu, , Mouse Bindings, Basic Navigation -@comment node-name, next, previous, up -@section Displays Submenu -@cindex displays submenu - -You can display different data by using different display modes. These -specialized modes make it easier to navigate the relevant pieces of -information, such as files and directories, or buffers. - -In the main menu, found by clicking @kbd{Mouse-3}, there is a submenu -labeled @samp{Displays}. This submenu lets you easily choose between -different display modes. - -The contents are modes currently loaded into emacs. By default, this -would include Files, Quick Buffers, and Buffers. Other major display -modes such as Info are loaded separately. - -@node File Mode, Buffer Mode, Basic Navigation, Top -@comment node-name, next, previous, up -@chapter File Mode -@cindex file mode - -File mode displays a summary of your current directory. You can display -files in the attached frame, or summarize the tags found in files. You -can even see if a file is checked out of a version control system, or -has some associated object file. - -Advanced behavior, like copying and renaming files, is also provided. - -@menu -* Directory Display:: What the display means. -* Hidden Files:: How to display hidden files. -* File Key Bindings:: Performing file operations. -@end menu - -@node Directory Display, Hidden Files, File Mode, File Mode -@comment node-name, next, previous, up -@section Directory Display -@cindex directory display - -There are three major sections in the display. The first line or two is -the root directory speedbar is currently viewing. You can jump to one -of the parent directories by clicking on the name of the directory you -wish to jump to. - -Next, directories are listed. A directory starts with the group -indicator button @samp{<+>}. Clicking the directory name makes speedbar -load that directory as the root directory for its display. Clicking the -@samp{<+>} button will list all directories and files beneath. - -Next, files are listed. Files start with the group indicator @samp{[+]} -or @samp{[?]}. You can jump to a file in the attached frame by clicking -on the file name. You can expand a file and look at its tags by -clicking on the @samp{[+]} symbol near the file name. - -A typical session might look like this: - -@example -~/lisp/ -<+> checkdoc -<+> eieio -<-> speedbar - [+] Makefile - [+] rpm.el # - [+] sb-gud.el # - [+] sb-info.el # - [+] sb-rmail.el # - [+] sb-w3.el - [-] speedbar.el *! - @{+@} Types - @{+@} Variables - @{+@} def (group) - @{+@} speedbar- - [+] speedbar.texi * -<+> testme -[+] align.el -[+] autoconf.el -@end example - -In this example, you can see several directories. The directory -@file{speedbar} has been opened inline. Inside the directory -@file{speedbar}, the file @file{speedbar.el} has its tags exposed. -These tags are extensive, and they are summarized into tag groups. - -Files get additional boolean flags associated with them. Valid flags are: - -@cindex file flags -@table @code -@item * -This file has been checked out of a version control -system. @xref{Version Control}. -@cindex @code{speedbar-obj-alist} -@item # -This file has an up to date object file associated with it. The -variable @code{speedbar-obj-alist} defines how speedbar determines this -value. -@item ! -This file has an out of date object file associated with it. -@end table - -A Tag group is prefixed with the symbol @samp{@{+@}}. Clicking this -symbol will show all symbols that have been organized into that group. -Different types of files have unique tagging methods as defined by their -major mode. Tags are generated with either the @code{imenu} package, or -through the @code{etags} interface. - -Tag groups are defined in multiple ways which make it easier to find the -tag you are looking for. Imenu keywords explicitly create groups, and -speedbar will automatically create groups if tag lists are too long. - -In our example, Imenu created the groups @samp{Types} and -@samp{Variables}. All remaining top-level symbols are then regrouped -based on the variable @code{speedbar-tag-hierarchy-method}. The -subgroups @samp{def} and @samp{speedbar-} are groupings where the first -few characters of the given symbols are specified in the group name. -Some group names may say something like @samp{speedbar-t to speedbar-v}, -indicating that all symbols which alphabetically fall between those -categories are included in that sub-group. @xref{Tag Hierarchy Methods}. - -@node Hidden Files, File Key Bindings, Directory Display, File Mode -@comment node-name, next, previous, up -@section Hidden Files -@cindex hidden files - -On GNU and Unix systems, a hidden file is a file whose name starts -with a period. They are hidden from a regular directory listing -because the user is not generally interested in them. - -In speedbar, a hidden file is a file which isn't very interesting and -might prove distracting to the user. Any uninteresting files are -removed from the File display. There are two levels of uninterest in -speedbar. The first level of uninterest are files which have no -expansion method, or way of extracting tags. The second level is any -file that matches the same pattern used for completion in -@code{find-file}. This is derived from the variable -@code{completion-ignored-extensions}. - -You can toggle the display of uninteresting files from the toggle menu -item @samp{Show All Files}. This will display all level one hidden files. -These files will be shown with a @samp{?} indicator. Level 2 hidden -files will still not be shown. - -Object files fall into the category of level 2 hidden files. You can -determine their presence by the @samp{#} and @samp{!} file indicators. -@xref{Directory Display}. - -@node File Key Bindings, , Hidden Files, File Mode -@comment node-name, next, previous, up -@section File Key Bindings -@cindex file key bindings - -File mode has key bindings permitting different file system operations -such as copy or rename. These commands all operate on the @dfn{current -file}. In this case, the current file is the file at point, or clicked -on when pulling up the menu. - -@table @kbd -@item U -Move the entire speedbar display up one directory. -@item I -Display information in the minibuffer about this line. This is the same -information shown when navigating with @kbd{n} and @kbd{p}, or moving -the mouse over an item. -@item B -Byte compile the Emacs Lisp file on this line. -@item L -Load the Emacs Lisp file on this line. If a @file{.elc} file exists, -optionally load that. -@item C -Copy the current file to some other location. -@item R -Rename the current file, possibly moving it to some other location. -@item D -Delete the current file. -@item O -Delete the current file's object file. Use the symbols @samp{#} and -@samp{!} to determine if there is an object file available. -@end table - -One menu item toggles the display of all available files. By default, -only files which Emacs understands, and knows how to convert into a tag -list, are shown. By showing all files, additional files such as text files are -also displayed, but they are prefixed with the @samp{[?]} symbol. This -means that it is a file, but Emacs doesn't know how to expand it. - -@node Buffer Mode, Minor Modes, File Mode, Top -@comment node-name, next, previous, up -@chapter Buffer Mode -@cindex buffer mode - -Buffer mode is very similar to File mode, except that instead of -tracking the current directory and all files available there, the -current list of Emacs buffers is shown. - -These buffers can have their tags expanded in the same way as files, -and uses the same unknown file indicator (@pxref{File Mode}). - -Buffer mode does not have file operation bindings, but the following -buffer specific key bindings are available: - -@table @kbd -@item k -Kill this buffer. Do not touch its file. -@item r -Revert this buffer, reloading from disk. -@end table - -In addition to Buffer mode, there is also Quick Buffer mode. In fact, -Quick Buffers is bound to the @kbd{b} key. The only difference between -Buffers and Quick Buffers is that after one operation is performed -which affects the attached frame, the display is immediately reverted to -the last displayed mode. - -Thus, if you are in File mode, and you need quick access to a buffer, -press @kbd{b}, click on the buffer you want, and speedbar will revert -back to File mode. - -@node Minor Modes, Customizing, Buffer Mode, Top -@comment node-name, next, previous, up -@chapter Minor Display Modes -@cindex minor display modes - -For some buffers, a list of files and tags makes no sense. This could -be because files are not currently in reference (such as web pages), or -that the files you might be interested have special properties (such as -email folders.) - -In these cases, a minor display mode is needed. A minor display mode -will override any major display mode currently being displayed for the -duration of the specialized buffer's use. Minor display modes -will follow the general rules of their major counterparts in terms of -key bindings and visuals, but will have specialized behaviors. - -@menu -* RMAIL:: Managing folders. -* Info:: Browsing topics. -* GDB:: Watching expressions or managing the current - stack trace. -@end menu - -@node RMAIL, Info, Minor Modes, Minor Modes -@comment node-name, next, previous, up -@section RMAIL -@cindex RMAIL - -When using RMAIL, speedbar will display two sections. The first is a -layer one reply button. Clicking here will initialize a reply buffer -showing only this email address in the @samp{To:} field. - -The second section lists all RMAIL folders in the same directory as your -main RMAIL folder. The general rule is that RMAIL folders always appear -in all caps, or numbers. It is possible to save mail in folders with -lower case letters, but there is no clean way of detecting such RMAIL folders -without opening them all. - -Each folder can be visited by clicking the name. You can move mail from -the current RMAIL folder into a different folder by clicking the -@samp{} button. The @samp{M} stands for Move. - -In this way you can manage your existing RMAIL folders fairly easily -using the mouse. - -@node Info, GDB, RMAIL, Minor Modes -@comment node-name, next, previous, up -@section Info -@cindex Info - -When browsing Info files, all local relevant information is displayed in -the info buffer and a topical high-level view is provided in speedbar. -All top-level info nodes are shown in the speedbar frame, and can be -jumped to by clicking the name. - -You can open these nodes with the @samp{[+]} button to see what sub-topics -are available. Since these sub-topics are not examined until you click -the @samp{[+]} button, sometimes a @samp{[?]} will appear when you click on -a @samp{[+]}, indicating that there are no sub-topics. - -@node GDB, , Info, Minor Modes -@comment node-name, next, previous, up -@section GDB -@cindex gdb -@cindex gud - -You can debug an application with GDB in Emacs using graphical mode or -text command mode (@pxref{GDB Graphical Interface,,, emacs, The -extensible self-documenting text editor}). - -If you are using graphical mode you can see how selected variables -change each time your program stops (@pxref{Watch Expressions,,, -emacs, The extensible self-documenting text editor}). - -If you are using text command mode, speedbar can show -you the current stack when the current buffer is the @file{*gdb*} -buffer. Usually, it will just report that there is no stack, but when -the application is stopped, the current stack will be shown. - -You can click on any stack element and gdb will move to that stack -level. You can then check variables local to that level at the GDB -prompt. - -@node Customizing, Extending, Minor Modes, Top -@comment node-name, next, previous, up -@chapter Customizing -@cindex customizing - -Speedbar is highly customizable, with a plethora of control elements. -Since speedbar is so visual and reduces so much information, this is an -important aspect of its behavior. - -In general, there are three custom groups you can use to quickly modify -speedbar's behavior. - -@table @code -@item speedbar -Basic speedbar behaviors. -@item speedbar-vc -Customizations regarding version control handling. -@item speedbar-faces -Customize speedbar's many colors and fonts. -@end table - -@menu -* Frames and Faces:: Visible behaviors. -* Tag Hierarchy Methods:: Customizing how tags are displayed. -* Version Control:: Adding new VC detection modes. -* Hooks:: The many hooks you can use. -@end menu - -@node Frames and Faces, Tag Hierarchy Methods, Customizing, Customizing -@comment node-name, next, previous, up -@section Frames and Faces -@cindex faces -@cindex frame parameters - -There are several faces speedbar generates to provide a consistent -color scheme across display types. You can customize these faces using -your favorite method. They are: - -@table @asis -@cindex @code{speedbar-button-face} -@item speedbar-button-face -Face used on expand/contract buttons. -@cindex @code{speedbar-file-face} -@item speedbar-file-face -Face used on Files. Should also be used on non-directory like nodes. -@cindex @code{speedbar-directory-face} -@item speedbar-directory-face -Face used for directories, or nodes which consist of groups of other nodes. -@cindex @code{speedbar-tag-face} -@item speedbar-tag-face -Face used for tags in a file, or for leaf items. -@cindex @code{speedbar-selected-face} -@item speedbar-selected-face -Face used to highlight the selected item. This would be the current -file being edited. -@cindex @code{speedbar-highlight-face} -@item speedbar-highlight-face -Face used when the mouse passes over a button. -@end table - -You can also customize speedbar's initial frame parameters. How this is -accomplished is dependent on your platform being Emacs or XEmacs. - -@cindex @code{speedbar-frame-parameters}, Emacs -In Emacs, change the alist @code{speedbar-frame-parameters}. This -variable is used to set up initial details. Height is also -automatically added when speedbar is created, though you can override -it. - -@cindex @code{speedbar-frame-plist}, XEmacs -In XEmacs, change the plist @code{speedbar-frame-plist}. This is the -XEmacs way of doing the same thing. - -@node Tag Hierarchy Methods, Version Control, Frames and Faces, Customizing -@comment node-name, next, previous, up -@section Tag Hierarchy Methods -@cindex tag hierarchy -@cindex tag groups -@cindex tag sorting - -When listing tags within a file, it is possible to get an annoyingly -long list of entries. Imenu (which generates the tag list in Emacs) -will group some classes of items automatically. Even here, however, -some tag groups can be quite large. - -@cindex @code{speedbar-tag-hierarchy-method} -To solve this problem, tags can be grouped into logical units through a -hierarchy processor. The specific variable to use is -@code{speedbar-tag-hierarchy-method}. There are several methods that -can be applied in any order. They are: - -@table @code -@cindex @code{speedbar-trim-words-tag-hierarchy} -@item speedbar-trim-words-tag-hierarchy -Find a common prefix for all elements of a group, and trim it off. -@cindex @code{speedbar-prefix-group-tag-hierarchy} -@item speedbar-prefix-group-tag-hierarchy -If a group is too large, place sets of tags into bins based on common -prefixes. -@cindex @code{speedbar-simple-group-tag-hierarchy} -@item speedbar-simple-group-tag-hierarchy -Take all items in the top level list not in a group, and stick them into -a @samp{Tags} group. -@cindex @code{speedbar-sort-tag-hierarchy} -@item speedbar-sort-tag-hierarchy -Sort all items, leaving groups on top. -@end table - -You can also add your own functions to reorganize tags as you see fit. - -Some other control variables are: - -@table @code -@cindex @code{speedbar-tag-group-name-minimum-length} -@item speedbar-tag-group-name-minimum-length -Default value: 4. - -The minimum length of a prefix group name before expanding. Thus, if -the @code{speedbar-tag-hierarchy-method} includes -@code{speedbar-prefix-group-tag-hierarchy} and one such group's common -characters is less than this number of characters, then the group name -will be changed to the form of: - -@example -worda to wordb -@end example - -instead of just - -@example -word -@end example - -This way we won't get silly looking listings. - -@cindex @code{speedbar-tag-split-minimum-length} -@item speedbar-tag-split-minimum-length -Default value: 20. - -Minimum length before we stop trying to create sub-lists in tags. -This is used by all tag-hierarchy methods that break large lists into -sub-lists. - -@cindex @code{speedbar-tag-regroup-maximum-length} -@item speedbar-tag-regroup-maximum-length -Default value: 10. - -Maximum length of submenus that are regrouped. -If the regrouping option is used, then if two or more short subgroups -are next to each other, then they are combined until this number of -items is reached. -@end table - -@node Version Control, Hooks, Tag Hierarchy Methods, Customizing -@comment node-name, next, previous, up -@section Version Control -@cindex version control -@cindex vc extensions - -When using the file mode in speedbar, information regarding a version -control system adds small details to the display. If a file is in a -version control system, and is ``checked out'' or ``locked'' locally, an -asterisk @samp{*} appears at the end of the file name. In addition, -the directory name for Version Control systems are left out of the -speedbar display. - -@cindex @code{speedbar-directory-unshown-regexp} -You can easily add new version control systems into speedbar's detection -scheme. To make a directory ``disappear'' from the list, use the variable -@code{speedbar-directory-unshown-regexp}. - -@cindex @code{speedbar-vc-path-enable-hook} -Next, you need to write entries for two hooks. The first is -@code{speedbar-vc-path-enable-hook} which will enable a VC check in the -current directory for the group of files being checked. Your hook -function should take one parameter (the directory to check) and return -@code{t} if your VC method is in control here. - -@cindex @code{speedbar-vc-in-control-hook} -The second function is @code{speedbar-vc-in-control-hook}. This hook -takes two parameters, the @var{path} of the file to check, and the -@var{file} name. Return @code{t} if you want to have the asterisk -placed near this file. - -@cindex @code{speedbar-vc-indicator} -Lastly, you can change the VC indicator using the variable -@code{speedbar-vc-indicator}, and specify a single character string. - -@node Hooks, , Version Control, Customizing -@comment node-name, next, previous, up -@section Hooks -@cindex hooks - -There are several hooks in speedbar allowing custom behaviors to be -added. Available hooks are: - -@table @code -@cindex @code{speedbar-visiting-file-hook} -@item speedbar-visiting-file-hook -Hooks run when speedbar visits a file in the selected frame. -@cindex @code{speedbar-visiting-tag-hook} -@item speedbar-visiting-tag-hook -Hooks run when speedbar visits a tag in the selected frame. -@cindex @code{speedbar-load-hook} -@item speedbar-load-hook -Hooks run when speedbar is loaded. -@cindex @code{speedbar-reconfigure-keymaps-hook} -@item speedbar-reconfigure-keymaps-hook -Hooks run when the keymaps are regenerated. Keymaps are reconfigured -whenever modes change. This will let you add custom key bindings. -@cindex @code{speedbar-before-popup-hook} -@item speedbar-before-popup-hook -Hooks called before popping up the speedbar frame. -New frames are often popped up when ``power clicking'' on an item to view -it. -@cindex @code{speedbar-before-delete-hook} -@item speedbar-before-delete-hook -Hooks called before deleting or hiding the speedbar frame. -@cindex @code{speedbar-mode-hook} -@item speedbar-mode-hook -Hooks called after creating a speedbar buffer. -@cindex @code{speedbar-timer-hook} -@item speedbar-timer-hook -Hooks called after running the speedbar timer function. -@cindex @code{speedbar-scanner-reset-hook} -@item speedbar-scanner-reset-hook -Hook called whenever generic scanners are reset. -Set this to implement your own scanning or rescan safe functions with -state data. -@end table - -@node Extending, GNU Free Documentation License, Customizing, Top -@comment node-name, next, previous, up -@chapter Extending -@cindex extending - -Speedbar can run different types of Major display modes such as Files -(@pxref{File Mode}), and Buffers (@pxref{Buffer Mode}). It can also manage -different minor display modes for use with buffers handling specialized -data. - -These major and minor display modes are handled through an extension -system which permits specialized keymaps and menu extensions, in -addition to a unique rendering function. You can also specify a wide -range of tagging functions. The default uses @code{imenu}, but new -tagging methods can be easily added. In this chapter, you will -learn how to write your own major or minor display modes, and how to -create specialized tagging functions. - -@menu -* Minor Display Modes:: How to create a minor display mode. -* Major Display Modes:: How to create a major display mode. -* Tagging Extensions:: How to create your own tagging methods. -* Creating a display:: How to insert buttons and hierarchies. -@end menu - -@node Minor Display Modes, Major Display Modes, Extending, Extending -@section Minor Display Modes -@cindex create minor display mode - -A @dfn{minor display mode} is a mode useful when using a specific type of -buffer. This mode might not be useful for any other kind of data or -mode, or may just be more useful that a files or buffers based mode when -working with a specialized mode. - -Examples that already exist for speedbar include RMAIL, Info, and gdb. -These modes display information specific to the major mode shown in the -attached frame. - -To enable a minor display mode in your favorite Major mode, follow these -steps. The string @samp{@var{name}} is the name of the major mode being -augmented with speedbar. - -@enumerate -@item -Create the keymap variable @code{@var{name}-speedbar-key-map}. - -@item -Create a function, named whatever you like, which assigns values into your -keymap. Use this command to create the keymap before assigning -bindings: - -@smallexample - (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) -@end smallexample - -This function creates a special keymap for use in speedbar. - -@item -Call your install function, or assign it to a hook like this: - -@smallexample -(if (featurep 'speedbar) - (@var{name}-install-speedbar-variables) - (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) -@end smallexample - -@item -Create an easymenu compatible vector named -@code{@var{name}-speedbar-menu-items}. This will be spliced into -speedbar's control menu. - -@item -Create a function called @code{@var{name}-speedbar-buttons}. This function -should take one variable, which is the buffer for which it will create -buttons. At this time @code{(current-buffer)} will point to the -uncleared speedbar buffer. -@end enumerate - -When writing @code{@var{name}-speedbar-buttons}, the first thing you will -want to do is execute a check to see if you need to re-create your -display. If it needs to be cleared, you need to erase the speedbar -buffer yourself, and start drawing buttons. @xref{Creating a display}. - -@node Major Display Modes, Tagging Extensions, Minor Display Modes, Extending -@section Major Display Modes -@cindex create major display mode - -Creating a @dfn{Major Display Mode} for speedbar requires authoring a keymap, -an easy-menu segment, and writing several functions. These items can be -given any name, and are made the same way as in a minor display mode -(@pxref{Minor Display Modes}). Once this is done, these items need to be -registered. - -Because this setup activity may or may not have speedbar available when -it is being loaded, it is necessary to create an install function. This -function should create and initialize the keymap, and add your -expansions into the customization tables. - -@cindex @code{speedbar-make-specialized-keymap} -When creating the keymap, use the function -@code{speedbar-make-specialized-keymap} instead of other keymap making -functions. This will provide you with the initial bindings needed. -Some common speedbar functions you might want to bind are: - -@table @code -@cindex @code{speedbar-edit-line} -@item speedbar-edit-line -Edit the item on the current line. -@cindex @code{speedbar-expand-line} -@item speedbar-expand-line -Expand the item under the cursor. -With a numeric argument (@kbd{C-u}), flush cached data before expanding. -@cindex @code{speedbar-contract-line} -@item speedbar-contract-line -Contract the item under the cursor. -@end table - -@cindex @code{speedbar-line-path} -These function require that function @code{speedbar-line-path} be -correctly overloaded to work. - -Next, register your extension like this; - -@example - (speedbar-add-expansion-list '("MyExtension" - MyExtension-speedbar-menu-items - MyExtension-speedbar-key-map - MyExtension-speedbar-buttons)) -@end example - -There are no limitations to the names you use. - -The first parameter is the string representing your display mode. -The second parameter is a variable name containing an easymenu compatible -menu definition. This will be stuck in the middle of speedbar's menu. -The third parameter is the variable name containing the keymap we -discussed earlier. -The last parameter is a function which draws buttons for your mode. -This function must take two parameters. The directory currently being -displayed, and the depth at which you should start rendering buttons. -The function will then draw (starting at the current cursor position) -any buttons deemed necessary based on the input parameters. -@xref{Creating a display}. - -Next, you need to register function overrides. This may look something -like this: - -@example -(speedbar-add-mode-functions-list - '("MYEXTENSION" - (speedbar-item-info . MyExtension-speedbar-item-info) - (speedbar-line-path . MyExtension-speedbar-line-path))) -@end example - -The first element in the list is the name of you extension. The second -is an alist of functions to overload. The function to overload is -first, followed by what you want called instead. - -For @code{speedbar-line-path} your function should take an optional DEPTH -parameter. This is the starting depth for heavily indented lines. If -it is not provided, you can derive it like this: - -@example -(save-match-data - (if (not depth) - (progn - (beginning-of-line) - (looking-at "^\\([0-9]+\\):") - (setq depth (string-to-int (match-string 1))))) -@end example - -@noindent -where the depth is stored as invisible text at the beginning of each -line. - -The path returned should be the full path name of the file associated -with that line. If the cursor is on a tag, then the file containing -that tag should be returned. This is critical for built in file based -functions to work (meaning less code for you to write). If your display -does not deal in files, you do not need to overload this function. - -@cindex @code{speedbar-item-info} -The function @code{speedbar-item-info}, however, is very likely to need -overloading. This function takes no parameters and must derive a text -summary to display in the minibuffer. - -There are several helper functions you can use if you are going to use -built in tagging. These functions can be @code{or}ed since each one -returns non-@code{nil} if it displays a message. They are: - -@table @code -@cindex @code{speedbar-item-info-file-helper} -@item speedbar-item-info-file-helper -This takes an optional @var{filename} parameter. You can derive your own -filename, or it will derive it using a (possibly overloaded) function -@code{speedbar-line-file}. It shows details about a file. -@cindex @code{speedbar-item-info-tag-helper} -@item speedbar-item-info-tag-helper -If the current line is a tag, then display information about that tag, -such as its parent file, and location. -@end table - -Your custom function might look like this: - -@example -(defun MyExtension-item-info () - "Display information about the current line." - (or (speedbar-item-info-tag-helper) - (message "Interesting detail."))) -@end example - -Once you have done all this, speedbar will show an entry in the -@samp{Displays} menu declaring that your extension is available. - -@node Tagging Extensions, Creating a display, Major Display Modes, Extending -@section Tagging Extensions - -It is possible to create new methods for tagging files in speedbar. -To do this, you need two basic functions, one function to fetch the -tags from a buffer, the other to insert them below the filename. - -@defun my-fetch-dynamic-tags file -Parse @var{file} for a list of tags. Return the list, or @code{t} if there was -an error. -@end defun - -The non-error return value can be anything, as long as it can be -inserted by its paired function: - -@defun my-insert-tag-list level lst -Insert a list of tags @var{lst} started at indentation level -@var{level}. Creates buttons for each tag, and provides any other -display information required. -@end defun - -@cindex @code{speedbar-create-tag-hierarchy} -It is often useful to use @code{speedbar-create-tag-hierarchy} on your -token list. See that function's documentation for details on what it -requires. - -@cindex @code{speedbar-dynamic-tags-function-list} -Once these two functions are written, modify the variable -@code{speedbar-dynamic-tags-function-list} to include your parser at the -beginning, like this: - -@example -(add-to-list 'speedbar-dynamic-tags-function-list - '(my-fetch-dynamic-tags . my-insert-tag-list)) -@end example - -If your parser is only good for a few types of files, make sure that it -is either a buffer local modification, or that the tag generator returns -@code{t} for non valid buffers. - -@node Creating a display, , Tagging Extensions, Extending -@section Creating a display -@cindex creating a display - -Rendering a display in speedbar is completely flexible. When your -button function is called, see @ref{Minor Display Modes}, and @ref{Major -Display Modes}, you have control to @code{insert} anything you want. - -The conventions allow almost anything to be inserted, but several helper -functions are provided to make it easy to create the standardized -buttons. - -To understand the built in functions, each `button' in speedbar consists -of four important pieces of data. The text to be displayed, token -data to be associated with the text, a function to call, and some face to -display it in. - -When a function is provided, then that text becomes mouse activated, -meaning the mouse will highlight the text. - -Additionally, for data which can form deep trees, each line is given a -depth which indicates how far down the tree it is. This information is -stored in invisible text at the beginning of each line, and is used by -the navigation commands. - -@defun speedbar-insert-button text face mouse function &optional token prevline -This function inserts one button into the current location. -@var{text} is the text to insert. @var{face} is the face in which it -will be displayed. @var{mouse} is the face to display over the text -when the mouse passes over it. @var{function} is called whenever the -user clicks on the text. - -The optional argument @var{token} is extra data to associated with the -text. Lastly @var{prevline} should be non-@code{nil} if you want this line to -appear directly after the last button which was created instead of on -the next line. -@end defun - -@defun speedbar-make-tag-line exp-button-type exp-button-char exp-button-function exp-button-data tag-button tag-button-function tag-button-data tag-button-face depth - -Create a tag line with @var{exp-button-type} for the small expansion -button. This is the button that expands or contracts a node (if -applicable), and @var{exp-button-char} the character in it (@samp{+}, -@samp{-}, @samp{?}, etc). @var{exp-button-function} is the function -to call if it's clicked on. Button types are @code{bracket}, -@code{angle}, @code{curly}, @code{expandtag}, @code{statictag}, and -@code{nil}. @var{exp-button-data} is extra data attached to the text -forming the expansion button. - -Next, @var{tag-button} is the text of the tag. -@var{tag-button-function} is the function to call if clicked on, and -@var{tag-button-data} is the data to attach to the text field (such a -tag positioning, etc). @var{tag-button-face} is a face used for this -type of tag. - -Lastly, @var{depth} shows the depth of expansion. - -This function assumes that the cursor is in the speedbar window at the -position to insert a new item, and that the new item will end with a CR. -@end defun - -@defun speedbar-insert-generic-list level list expand-fun find-fun - -At @var{level}, (the current indentation level desired) insert a generic -multi-level alist @var{list}. Associations with lists get @samp{@{+@}} -tags (to expand into more nodes) and those with positions or other data -just get a @samp{>} as the indicator. @samp{@{+@}} buttons will have the -function @var{expand-fun} and the token is the @code{cdr} list. The -token name will have the function @var{find-fun} and not token. - -Each element of the list can have one of these forms: - -@table @code -@item (@var{name} . marker-or-number) -One tag at this level. -@item (@var{name} (@var{name} . marker-or-number) (@var{name} . marker-or-number) ... ) -One group of tags. -@item (@var{name} marker-or-number (@var{name} . marker-or-number) ... ) -One Group of tags where the group has a starting position. -@end table - -When you use @code{speedbar-insert-generic-list}, there are some -variables you can set buffer-locally to change the behavior. The most -obvious is @code{speedbar-tag-hierarchy-method}. -@xref{Tag Hierarchy Methods}. - -@defvar speedbar-generic-list-group-expand-button-type -This is the button type used for groups of tags, whether expanded -or added in via a hierarchy method. Two good values are -@code{curly} and @code{expandtag}. Curly is the default button, and -@code{expandtag} is useful if the groups also has a position. -@end defvar - -@defvar speedbar-generic-list-tag-button-type -This is the button type used for a single tag. -Two good values are @code{nil} and @code{statictag}. -@code{nil} is the default, and @code{statictag} has the same width as -@code{expandtag}. -@end defvar - -@end defun - -@node GNU Free Documentation License, Index, Extending, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@node Index, , GNU Free Documentation License, Top -@comment node-name, next, previous, up -@unnumbered Concept Index -@printindex cp - -@bye -@c LocalWords: speedbar's xref slowbar kbd subsubsection -@c LocalWords: keybindings - -@ignore - arch-tag: e1fc85f0-1eeb-489f-a8d4-a2bfe711fa02 -@end ignore diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex deleted file mode 100644 index 62f7a723ed7..00000000000 --- a/doc/misc/texinfo.tex +++ /dev/null @@ -1,8662 +0,0 @@ -% texinfo.tex -- TeX macros to handle Texinfo files. -% -% Load plain if necessary, i.e., if running under initex. -\expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi -% -\def\texinfoversion{2007-07-09.21} -% -% Copyright (C) 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, -% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008 Free Software Foundation, Inc. -% -% This texinfo.tex file is free software; you can redistribute it and/or -% modify it under the terms of the GNU General Public License as -% published by the Free Software Foundation; either version 2, or (at -% your option) any later version. -% -% This texinfo.tex file is distributed in the hope that it will be -% useful, but WITHOUT ANY WARRANTY; without even the implied warranty -% of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -% General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this texinfo.tex file; see the file COPYING. If not, write -% to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -% Boston, MA 02110-1301, USA. -% -% As a special exception, when this file is read by TeX when processing -% a Texinfo source document, you may use the result without -% restriction. (This has been our intent since Texinfo was invented.) -% -% Please try the latest version of texinfo.tex before submitting bug -% reports; you can get the latest version from: -% http://www.gnu.org/software/texinfo/ (the Texinfo home page), or -% ftp://tug.org/tex/texinfo.tex -% (and all CTAN mirrors, see http://www.ctan.org). -% The texinfo.tex in any given distribution could well be out -% of date, so if that's what you're using, please check. -% -% Send bug reports to bug-texinfo@gnu.org. Please include including a -% complete document in each bug report with which we can reproduce the -% problem. Patches are, of course, greatly appreciated. -% -% To process a Texinfo manual with TeX, it's most reliable to use the -% texi2dvi shell script that comes with the distribution. For a simple -% manual foo.texi, however, you can get away with this: -% tex foo.texi -% texindex foo.?? -% tex foo.texi -% tex foo.texi -% dvips foo.dvi -o # or whatever; this makes foo.ps. -% The extra TeX runs get the cross-reference information correct. -% Sometimes one run after texindex suffices, and sometimes you need more -% than two; texi2dvi does it as many times as necessary. -% -% It is possible to adapt texinfo.tex for other languages, to some -% extent. You can get the existing language-specific files from the -% full Texinfo distribution. -% -% The GNU Texinfo home page is http://www.gnu.org/software/texinfo. - - -\message{Loading texinfo [version \texinfoversion]:} - -% If in a .fmt file, print the version number -% and turn on active characters that we couldn't do earlier because -% they might have appeared in the input file name. -\everyjob{\message{[Texinfo version \texinfoversion]}% - \catcode`+=\active \catcode`\_=\active} - - -\chardef\other=12 - -% We never want plain's \outer definition of \+ in Texinfo. -% For @tex, we can use \tabalign. -\let\+ = \relax - -% Save some plain tex macros whose names we will redefine. -\let\ptexb=\b -\let\ptexbullet=\bullet -\let\ptexc=\c -\let\ptexcomma=\, -\let\ptexdot=\. -\let\ptexdots=\dots -\let\ptexend=\end -\let\ptexequiv=\equiv -\let\ptexexclam=\! -\let\ptexfootnote=\footnote -\let\ptexgtr=> -\let\ptexhat=^ -\let\ptexi=\i -\let\ptexindent=\indent -\let\ptexinsert=\insert -\let\ptexlbrace=\{ -\let\ptexless=< -\let\ptexnewwrite\newwrite -\let\ptexnoindent=\noindent -\let\ptexplus=+ -\let\ptexrbrace=\} -\let\ptexslash=\/ -\let\ptexstar=\* -\let\ptext=\t - -% If this character appears in an error message or help string, it -% starts a new line in the output. -\newlinechar = `^^J - -% Use TeX 3.0's \inputlineno to get the line number, for better error -% messages, but if we're using an old version of TeX, don't do anything. -% -\ifx\inputlineno\thisisundefined - \let\linenumber = \empty % Pre-3.0. -\else - \def\linenumber{l.\the\inputlineno:\space} -\fi - -% Set up fixed words for English if not already set. -\ifx\putwordAppendix\undefined \gdef\putwordAppendix{Appendix}\fi -\ifx\putwordChapter\undefined \gdef\putwordChapter{Chapter}\fi -\ifx\putwordfile\undefined \gdef\putwordfile{file}\fi -\ifx\putwordin\undefined \gdef\putwordin{in}\fi -\ifx\putwordIndexIsEmpty\undefined \gdef\putwordIndexIsEmpty{(Index is empty)}\fi -\ifx\putwordIndexNonexistent\undefined \gdef\putwordIndexNonexistent{(Index is nonexistent)}\fi -\ifx\putwordInfo\undefined \gdef\putwordInfo{Info}\fi -\ifx\putwordInstanceVariableof\undefined \gdef\putwordInstanceVariableof{Instance Variable of}\fi -\ifx\putwordMethodon\undefined \gdef\putwordMethodon{Method on}\fi -\ifx\putwordNoTitle\undefined \gdef\putwordNoTitle{No Title}\fi -\ifx\putwordof\undefined \gdef\putwordof{of}\fi -\ifx\putwordon\undefined \gdef\putwordon{on}\fi -\ifx\putwordpage\undefined \gdef\putwordpage{page}\fi -\ifx\putwordsection\undefined \gdef\putwordsection{section}\fi -\ifx\putwordSection\undefined \gdef\putwordSection{Section}\fi -\ifx\putwordsee\undefined \gdef\putwordsee{see}\fi -\ifx\putwordSee\undefined \gdef\putwordSee{See}\fi -\ifx\putwordShortTOC\undefined \gdef\putwordShortTOC{Short Contents}\fi -\ifx\putwordTOC\undefined \gdef\putwordTOC{Table of Contents}\fi -% -\ifx\putwordMJan\undefined \gdef\putwordMJan{January}\fi -\ifx\putwordMFeb\undefined \gdef\putwordMFeb{February}\fi -\ifx\putwordMMar\undefined \gdef\putwordMMar{March}\fi -\ifx\putwordMApr\undefined \gdef\putwordMApr{April}\fi -\ifx\putwordMMay\undefined \gdef\putwordMMay{May}\fi -\ifx\putwordMJun\undefined \gdef\putwordMJun{June}\fi -\ifx\putwordMJul\undefined \gdef\putwordMJul{July}\fi -\ifx\putwordMAug\undefined \gdef\putwordMAug{August}\fi -\ifx\putwordMSep\undefined \gdef\putwordMSep{September}\fi -\ifx\putwordMOct\undefined \gdef\putwordMOct{October}\fi -\ifx\putwordMNov\undefined \gdef\putwordMNov{November}\fi -\ifx\putwordMDec\undefined \gdef\putwordMDec{December}\fi -% -\ifx\putwordDefmac\undefined \gdef\putwordDefmac{Macro}\fi -\ifx\putwordDefspec\undefined \gdef\putwordDefspec{Special Form}\fi -\ifx\putwordDefvar\undefined \gdef\putwordDefvar{Variable}\fi -\ifx\putwordDefopt\undefined \gdef\putwordDefopt{User Option}\fi -\ifx\putwordDeffunc\undefined \gdef\putwordDeffunc{Function}\fi - -% Since the category of space is not known, we have to be careful. -\chardef\spacecat = 10 -\def\spaceisspace{\catcode`\ =\spacecat} - -% sometimes characters are active, so we need control sequences. -\chardef\colonChar = `\: -\chardef\commaChar = `\, -\chardef\dashChar = `\- -\chardef\dotChar = `\. -\chardef\exclamChar= `\! -\chardef\lquoteChar= `\` -\chardef\questChar = `\? -\chardef\rquoteChar= `\' -\chardef\semiChar = `\; -\chardef\underChar = `\_ - -% Ignore a token. -% -\def\gobble#1{} - -% The following is used inside several \edef's. -\def\makecsname#1{\expandafter\noexpand\csname#1\endcsname} - -% Hyphenation fixes. -\hyphenation{ - Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script - ap-pen-dix bit-map bit-maps - data-base data-bases eshell fall-ing half-way long-est man-u-script - man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm - par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces - spell-ing spell-ings - stand-alone strong-est time-stamp time-stamps which-ever white-space - wide-spread wrap-around -} - -% Margin to add to right of even pages, to left of odd pages. -\newdimen\bindingoffset -\newdimen\normaloffset -\newdimen\pagewidth \newdimen\pageheight - -% For a final copy, take out the rectangles -% that mark overfull boxes (in case you have decided -% that the text looks ok even though it passes the margin). -% -\def\finalout{\overfullrule=0pt} - -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). -% -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% -} - -% Sometimes it is convenient to have everything in the transcript file -% and nothing on the terminal. We don't just call \tracingall here, -% since that produces some useless output on the terminal. We also make -% some effort to order the tracing commands to reduce output in the log -% file; cf. trace.sty in LaTeX. -% -\def\gloggingall{\begingroup \globaldefs = 1 \loggingall \endgroup}% -\def\loggingall{% - \tracingstats2 - \tracingpages1 - \tracinglostchars2 % 2 gives us more in etex - \tracingparagraphs1 - \tracingoutput1 - \tracingmacros2 - \tracingrestores1 - \showboxbreadth\maxdimen \showboxdepth\maxdimen - \ifx\eTeXversion\undefined\else % etex gives us more logging - \tracingscantokens1 - \tracingifs1 - \tracinggroups1 - \tracingnesting2 - \tracingassigns1 - \fi - \tracingcommands3 % 3 gives us more in etex - \errorcontextlines16 -}% - -% add check for \lastpenalty to plain's definitions. If the last thing -% we did was a \nobreak, we don't want to insert more space. -% -\def\smallbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\smallskipamount - \removelastskip\penalty-50\smallskip\fi\fi} -\def\medbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\medskipamount - \removelastskip\penalty-100\medskip\fi\fi} -\def\bigbreak{\ifnum\lastpenalty<10000\par\ifdim\lastskip<\bigskipamount - \removelastskip\penalty-200\bigskip\fi\fi} - -% For @cropmarks command. -% Do @cropmarks to get crop marks. -% -\newif\ifcropmarks -\let\cropmarks = \cropmarkstrue -% -% Dimensions to add cropmarks at corners. -% Added by P. A. MacKay, 12 Nov. 1986 -% -\newdimen\outerhsize \newdimen\outervsize % set by the paper size routines -\newdimen\cornerlong \cornerlong=1pc -\newdimen\cornerthick \cornerthick=.3pt -\newdimen\topandbottommargin \topandbottommargin=.75in - -% Main output routine. -\chardef\PAGE = 255 -\output = {\onepageout{\pagecontents\PAGE}} - -\newbox\headlinebox -\newbox\footlinebox - -% \onepageout takes a vbox as an argument. Note that \pagecontents -% does insertions, but you have to call it yourself. -\def\onepageout#1{% - \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi - % - \ifodd\pageno \advance\hoffset by \bindingoffset - \else \advance\hoffset by -\bindingoffset\fi - % - % Do this outside of the \shipout so @code etc. will be expanded in - % the headline as they should be, not taken literally (outputting ''code). - \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}% - \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}% - % - {% - % Have to do this stuff outside the \shipout because we want it to - % take effect in \write's, yet the group defined by the \vbox ends - % before the \shipout runs. - % - \indexdummies % don't expand commands in the output. - \normalturnoffactive % \ in index entries must not stay \, e.g., if - % the page break happens to be in the middle of an example. - % We don't want .vr (or whatever) entries like this: - % \entry{{\tt \indexbackslash }acronym}{32}{\code {\acronym}} - % "\acronym" won't work when it's read back in; - % it needs to be - % {\code {{\tt \backslashcurfont }acronym} - \shipout\vbox{% - % Do this early so pdf references go to the beginning of the page. - \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi - % - \ifcropmarks \vbox to \outervsize\bgroup - \hsize = \outerhsize - \vskip-\topandbottommargin - \vtop to0pt{% - \line{\ewtop\hfil\ewtop}% - \nointerlineskip - \line{% - \vbox{\moveleft\cornerthick\nstop}% - \hfill - \vbox{\moveright\cornerthick\nstop}% - }% - \vss}% - \vskip\topandbottommargin - \line\bgroup - \hfil % center the page within the outer (page) hsize. - \ifodd\pageno\hskip\bindingoffset\fi - \vbox\bgroup - \fi - % - \unvbox\headlinebox - \pagebody{#1}% - \ifdim\ht\footlinebox > 0pt - % Only leave this space if the footline is nonempty. - % (We lessened \vsize for it in \oddfootingyyy.) - % The \baselineskip=24pt in plain's \makefootline has no effect. - \vskip 24pt - \unvbox\footlinebox - \fi - % - \ifcropmarks - \egroup % end of \vbox\bgroup - \hfil\egroup % end of (centering) \line\bgroup - \vskip\topandbottommargin plus1fill minus1fill - \boxmaxdepth = \cornerthick - \vbox to0pt{\vss - \line{% - \vbox{\moveleft\cornerthick\nsbot}% - \hfill - \vbox{\moveright\cornerthick\nsbot}% - }% - \nointerlineskip - \line{\ewbot\hfil\ewbot}% - }% - \egroup % \vbox from first cropmarks clause - \fi - }% end of \shipout\vbox - }% end of group with \indexdummies - \advancepageno - \ifnum\outputpenalty>-20000 \else\dosupereject\fi -} - -\newinsert\margin \dimen\margin=\maxdimen - -\def\pagebody#1{\vbox to\pageheight{\boxmaxdepth=\maxdepth #1}} -{\catcode`\@ =11 -\gdef\pagecontents#1{\ifvoid\topins\else\unvbox\topins\fi -% marginal hacks, juha@viisa.uucp (Juha Takala) -\ifvoid\margin\else % marginal info is present - \rlap{\kern\hsize\vbox to\z@{\kern1pt\box\margin \vss}}\fi -\dimen@=\dp#1 \unvbox#1 -\ifvoid\footins\else\vskip\skip\footins\footnoterule \unvbox\footins\fi -\ifr@ggedbottom \kern-\dimen@ \vfil \fi} -} - -% Here are the rules for the cropmarks. Note that they are -% offset so that the space between them is truly \outerhsize or \outervsize -% (P. A. MacKay, 12 November, 1986) -% -\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} -\def\nstop{\vbox - {\hrule height\cornerthick depth\cornerlong width\cornerthick}} -\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} -\def\nsbot{\vbox - {\hrule height\cornerlong depth\cornerthick width\cornerthick}} - -% Parse an argument, then pass it to #1. The argument is the rest of -% the input line (except we remove a trailing comment). #1 should be a -% macro which expects an ordinary undelimited TeX argument. -% -\def\parsearg{\parseargusing{}} -\def\parseargusing#1#2{% - \def\argtorun{#2}% - \begingroup - \obeylines - \spaceisspace - #1% - \parseargline\empty% Insert the \empty token, see \finishparsearg below. -} - -{\obeylines % - \gdef\parseargline#1^^M{% - \endgroup % End of the group started in \parsearg. - \argremovecomment #1\comment\ArgTerm% - }% -} - -% First remove any @comment, then any @c comment. -\def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} -\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} - -% Each occurence of `\^^M' or `\^^M' is replaced by a single space. -% -% \argremovec might leave us with trailing space, e.g., -% @end itemize @c foo -% This space token undergoes the same procedure and is eventually removed -% by \finishparsearg. -% -\def\argcheckspaces#1\^^M{\argcheckspacesX#1\^^M \^^M} -\def\argcheckspacesX#1 \^^M{\argcheckspacesY#1\^^M} -\def\argcheckspacesY#1\^^M#2\^^M#3\ArgTerm{% - \def\temp{#3}% - \ifx\temp\empty - % Do not use \next, perhaps the caller of \parsearg uses it; reuse \temp: - \let\temp\finishparsearg - \else - \let\temp\argcheckspaces - \fi - % Put the space token in: - \temp#1 #3\ArgTerm -} - -% If a _delimited_ argument is enclosed in braces, they get stripped; so -% to get _exactly_ the rest of the line, we had to prevent such situation. -% We prepended an \empty token at the very beginning and we expand it now, -% just before passing the control to \argtorun. -% (Similarily, we have to think about #3 of \argcheckspacesY above: it is -% either the null string, or it ends with \^^M---thus there is no danger -% that a pair of braces would be stripped. -% -% But first, we have to remove the trailing space token. -% -\def\finishparsearg#1 \ArgTerm{\expandafter\argtorun\expandafter{#1}} - -% \parseargdef\foo{...} -% is roughly equivalent to -% \def\foo{\parsearg\Xfoo} -% \def\Xfoo#1{...} -% -% Actually, I use \csname\string\foo\endcsname, ie. \\foo, as it is my -% favourite TeX trick. --kasal, 16nov03 - -\def\parseargdef#1{% - \expandafter \doparseargdef \csname\string#1\endcsname #1% -} -\def\doparseargdef#1#2{% - \def#2{\parsearg#1}% - \def#1##1% -} - -% Several utility definitions with active space: -{ - \obeyspaces - \gdef\obeyedspace{ } - - % Make each space character in the input produce a normal interword - % space in the output. Don't allow a line break at this space, as this - % is used only in environments like @example, where each line of input - % should produce a line of output anyway. - % - \gdef\sepspaces{\obeyspaces\let =\tie} - - % If an index command is used in an @example environment, any spaces - % therein should become regular spaces in the raw index file, not the - % expansion of \tie (\leavevmode \penalty \@M \ ). - \gdef\unsepspaces{\let =\space} -} - - -\def\flushcr{\ifx\par\lisppar \def\next##1{}\else \let\next=\relax \fi \next} - -% Define the framework for environments in texinfo.tex. It's used like this: -% -% \envdef\foo{...} -% \def\Efoo{...} -% -% It's the responsibility of \envdef to insert \begingroup before the -% actual body; @end closes the group after calling \Efoo. \envdef also -% defines \thisenv, so the current environment is known; @end checks -% whether the environment name matches. The \checkenv macro can also be -% used to check whether the current environment is the one expected. -% -% Non-false conditionals (@iftex, @ifset) don't fit into this, so they -% are not treated as enviroments; they don't open a group. (The -% implementation of @end takes care not to call \endgroup in this -% special case.) - - -% At runtime, environments start with this: -\def\startenvironment#1{\begingroup\def\thisenv{#1}} -% initialize -\let\thisenv\empty - -% ... but they get defined via ``\envdef\foo{...}'': -\long\def\envdef#1#2{\def#1{\startenvironment#1#2}} -\def\envparseargdef#1#2{\parseargdef#1{\startenvironment#1#2}} - -% Check whether we're in the right environment: -\def\checkenv#1{% - \def\temp{#1}% - \ifx\thisenv\temp - \else - \badenverr - \fi -} - -% Evironment mismatch, #1 expected: -\def\badenverr{% - \errhelp = \EMsimple - \errmessage{This command can appear only \inenvironment\temp, - not \inenvironment\thisenv}% -} -\def\inenvironment#1{% - \ifx#1\empty - out of any environment% - \else - in environment \expandafter\string#1% - \fi -} - -% @end foo executes the definition of \Efoo. -% But first, it executes a specialized version of \checkenv -% -\parseargdef\end{% - \if 1\csname iscond.#1\endcsname - \else - % The general wording of \badenverr may not be ideal, but... --kasal, 06nov03 - \expandafter\checkenv\csname#1\endcsname - \csname E#1\endcsname - \endgroup - \fi -} - -\newhelp\EMsimple{Press RETURN to continue.} - - -%% Simple single-character @ commands - -% @@ prints an @ -% Kludge this until the fonts are right (grr). -\def\@{{\tt\char64}} - -% This is turned off because it was never documented -% and you can use @w{...} around a quote to suppress ligatures. -%% Define @` and @' to be the same as ` and ' -%% but suppressing ligatures. -%\def\`{{`}} -%\def\'{{'}} - -% Used to generate quoted braces. -\def\mylbrace {{\tt\char123}} -\def\myrbrace {{\tt\char125}} -\let\{=\mylbrace -\let\}=\myrbrace -\begingroup - % Definitions to produce \{ and \} commands for indices, - % and @{ and @} for the aux/toc files. - \catcode`\{ = \other \catcode`\} = \other - \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\! = 0 \catcode`\\ = \other - !gdef!lbracecmd[\{]% - !gdef!rbracecmd[\}]% - !gdef!lbraceatcmd[@{]% - !gdef!rbraceatcmd[@}]% -!endgroup - -% @comma{} to avoid , parsing problems. -\let\comma = , - -% Accents: @, @dotaccent @ringaccent @ubaraccent @udotaccent -% Others are defined by plain TeX: @` @' @" @^ @~ @= @u @v @H. -\let\, = \c -\let\dotaccent = \. -\def\ringaccent#1{{\accent23 #1}} -\let\tieaccent = \t -\let\ubaraccent = \b -\let\udotaccent = \d - -% Other special characters: @questiondown @exclamdown @ordf @ordm -% Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. -\def\questiondown{?`} -\def\exclamdown{!`} -\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} -\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} - -% Dotless i and dotless j, used for accents. -\def\imacro{i} -\def\jmacro{j} -\def\dotless#1{% - \def\temp{#1}% - \ifx\temp\imacro \ptexi - \else\ifx\temp\jmacro \j - \else \errmessage{@dotless can be used only with i or j}% - \fi\fi -} - -% The \TeX{} logo, as in plain, but resetting the spacing so that a -% period following counts as ending a sentence. (Idea found in latex.) -% -\edef\TeX{\TeX \spacefactor=1000 } - -% @LaTeX{} logo. Not quite the same results as the definition in -% latex.ltx, since we use a different font for the raised A; it's most -% convenient for us to use an explicitly smaller font, rather than using -% the \scriptstyle font (since we don't reset \scriptstyle and -% \scriptscriptstyle). -% -\def\LaTeX{% - L\kern-.36em - {\setbox0=\hbox{T}% - \vbox to \ht0{\hbox{\selectfonts\lllsize A}\vss}}% - \kern-.15em - \TeX -} - -% Be sure we're in horizontal mode when doing a tie, since we make space -% equivalent to this in @example-like environments. Otherwise, a space -% at the beginning of a line will start with \penalty -- and -% since \penalty is valid in vertical mode, we'd end up putting the -% penalty on the vertical list instead of in the new paragraph. -{\catcode`@ = 11 - % Avoid using \@M directly, because that causes trouble - % if the definition is written into an index file. - \global\let\tiepenalty = \@M - \gdef\tie{\leavevmode\penalty\tiepenalty\ } -} - -% @: forces normal size whitespace following. -\def\:{\spacefactor=1000 } - -% @* forces a line break. -\def\*{\hfil\break\hbox{}\ignorespaces} - -% @/ allows a line break. -\let\/=\allowbreak - -% @. is an end-of-sentence period. -\def\.{.\spacefactor=\endofsentencespacefactor\space} - -% @! is an end-of-sentence bang. -\def\!{!\spacefactor=\endofsentencespacefactor\space} - -% @? is an end-of-sentence query. -\def\?{?\spacefactor=\endofsentencespacefactor\space} - -% @frenchspacing on|off says whether to put extra space after punctuation. -% -\def\onword{on} -\def\offword{off} -% -\parseargdef\frenchspacing{% - \def\temp{#1}% - \ifx\temp\onword \plainfrenchspacing - \else\ifx\temp\offword \plainnonfrenchspacing - \else - \errhelp = \EMsimple - \errmessage{Unknown @frenchspacing option `\temp', must be on/off}% - \fi\fi -} - -% @w prevents a word break. Without the \leavevmode, @w at the -% beginning of a paragraph, when TeX is still in vertical mode, would -% produce a whole line of output instead of starting the paragraph. -\def\w#1{\leavevmode\hbox{#1}} - -% @group ... @end group forces ... to be all on one page, by enclosing -% it in a TeX vbox. We use \vtop instead of \vbox to construct the box -% to keep its height that of a normal line. According to the rules for -% \topskip (p.114 of the TeXbook), the glue inserted is -% max (\topskip - \ht (first item), 0). If that height is large, -% therefore, no glue is inserted, and the space between the headline and -% the text is small, which looks bad. -% -% Another complication is that the group might be very large. This can -% cause the glue on the previous page to be unduly stretched, because it -% does not have much material. In this case, it's better to add an -% explicit \vfill so that the extra space is at the bottom. The -% threshold for doing this is if the group is more than \vfilllimit -% percent of a page (\vfilllimit can be changed inside of @tex). -% -\newbox\groupbox -\def\vfilllimit{0.7} -% -\envdef\group{% - \ifnum\catcode`\^^M=\active \else - \errhelp = \groupinvalidhelp - \errmessage{@group invalid in context where filling is enabled}% - \fi - \startsavinginserts - % - \setbox\groupbox = \vtop\bgroup - % Do @comment since we are called inside an environment such as - % @example, where each end-of-line in the input causes an - % end-of-line in the output. We don't want the end-of-line after - % the `@group' to put extra space in the output. Since @group - % should appear on a line by itself (according to the Texinfo - % manual), we don't worry about eating any user text. - \comment -} -% -% The \vtop produces a box with normal height and large depth; thus, TeX puts -% \baselineskip glue before it, and (when the next line of text is done) -% \lineskip glue after it. Thus, space below is not quite equal to space -% above. But it's pretty close. -\def\Egroup{% - % To get correct interline space between the last line of the group - % and the first line afterwards, we have to propagate \prevdepth. - \endgraf % Not \par, as it may have been set to \lisppar. - \global\dimen1 = \prevdepth - \egroup % End the \vtop. - % \dimen0 is the vertical size of the group's box. - \dimen0 = \ht\groupbox \advance\dimen0 by \dp\groupbox - % \dimen2 is how much space is left on the page (more or less). - \dimen2 = \pageheight \advance\dimen2 by -\pagetotal - % if the group doesn't fit on the current page, and it's a big big - % group, force a page break. - \ifdim \dimen0 > \dimen2 - \ifdim \pagetotal < \vfilllimit\pageheight - \page - \fi - \fi - \box\groupbox - \prevdepth = \dimen1 - \checkinserts -} -% -% TeX puts in an \escapechar (i.e., `@') at the beginning of the help -% message, so this ends up printing `@group can only ...'. -% -\newhelp\groupinvalidhelp{% -group can only be used in environments such as @example,^^J% -where each line of input produces a line of output.} - -% @need space-in-mils -% forces a page break if there is not space-in-mils remaining. - -\newdimen\mil \mil=0.001in - -% Old definition--didn't work. -%\parseargdef\need{\par % -%% This method tries to make TeX break the page naturally -%% if the depth of the box does not fit. -%{\baselineskip=0pt% -%\vtop to #1\mil{\vfil}\kern -#1\mil\nobreak -%\prevdepth=-1000pt -%}} - -\parseargdef\need{% - % Ensure vertical mode, so we don't make a big box in the middle of a - % paragraph. - \par - % - % If the @need value is less than one line space, it's useless. - \dimen0 = #1\mil - \dimen2 = \ht\strutbox - \advance\dimen2 by \dp\strutbox - \ifdim\dimen0 > \dimen2 - % - % Do a \strut just to make the height of this box be normal, so the - % normal leading is inserted relative to the preceding line. - % And a page break here is fine. - \vtop to #1\mil{\strut\vfil}% - % - % TeX does not even consider page breaks if a penalty added to the - % main vertical list is 10000 or more. But in order to see if the - % empty box we just added fits on the page, we must make it consider - % page breaks. On the other hand, we don't want to actually break the - % page after the empty box. So we use a penalty of 9999. - % - % There is an extremely small chance that TeX will actually break the - % page at this \penalty, if there are no other feasible breakpoints in - % sight. (If the user is using lots of big @group commands, which - % almost-but-not-quite fill up a page, TeX will have a hard time doing - % good page breaking, for example.) However, I could not construct an - % example where a page broke at this \penalty; if it happens in a real - % document, then we can reconsider our strategy. - \penalty9999 - % - % Back up by the size of the box, whether we did a page break or not. - \kern -#1\mil - % - % Do not allow a page break right after this kern. - \nobreak - \fi -} - -% @br forces paragraph break (and is undocumented). - -\let\br = \par - -% @page forces the start of a new page. -% -\def\page{\par\vfill\supereject} - -% @exdent text.... -% outputs text on separate line in roman font, starting at standard page margin - -% This records the amount of indent in the innermost environment. -% That's how much \exdent should take out. -\newskip\exdentamount - -% This defn is used inside fill environments such as @defun. -\parseargdef\exdent{\hfil\break\hbox{\kern -\exdentamount{\rm#1}}\hfil\break} - -% This defn is used inside nofill environments such as @example. -\parseargdef\nofillexdent{{\advance \leftskip by -\exdentamount - \leftline{\hskip\leftskip{\rm#1}}}} - -% @inmargin{WHICH}{TEXT} puts TEXT in the WHICH margin next to the current -% paragraph. For more general purposes, use the \margin insertion -% class. WHICH is `l' or `r'. -% -\newskip\inmarginspacing \inmarginspacing=1cm -\def\strutdepth{\dp\strutbox} -% -\def\doinmargin#1#2{\strut\vadjust{% - \nobreak - \kern-\strutdepth - \vtop to \strutdepth{% - \baselineskip=\strutdepth - \vss - % if you have multiple lines of stuff to put here, you'll need to - % make the vbox yourself of the appropriate size. - \ifx#1l% - \llap{\ignorespaces #2\hskip\inmarginspacing}% - \else - \rlap{\hskip\hsize \hskip\inmarginspacing \ignorespaces #2}% - \fi - \null - }% -}} -\def\inleftmargin{\doinmargin l} -\def\inrightmargin{\doinmargin r} -% -% @inmargin{TEXT [, RIGHT-TEXT]} -% (if RIGHT-TEXT is given, use TEXT for left page, RIGHT-TEXT for right; -% else use TEXT for both). -% -\def\inmargin#1{\parseinmargin #1,,\finish} -\def\parseinmargin#1,#2,#3\finish{% not perfect, but better than nothing. - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \def\lefttext{#1}% have both texts - \def\righttext{#2}% - \else - \def\lefttext{#1}% have only one text - \def\righttext{#1}% - \fi - % - \ifodd\pageno - \def\temp{\inrightmargin\righttext}% odd page -> outside is right margin - \else - \def\temp{\inleftmargin\lefttext}% - \fi - \temp -} - -% @include file insert text of that file as input. -% -\def\include{\parseargusing\filenamecatcodes\includezzz} -\def\includezzz#1{% - \pushthisfilestack - \def\thisfile{#1}% - {% - \makevalueexpandable - \def\temp{\input #1 }% - \expandafter - }\temp - \popthisfilestack -} -\def\filenamecatcodes{% - \catcode`\\=\other - \catcode`~=\other - \catcode`^=\other - \catcode`_=\other - \catcode`|=\other - \catcode`<=\other - \catcode`>=\other - \catcode`+=\other - \catcode`-=\other -} - -\def\pushthisfilestack{% - \expandafter\pushthisfilestackX\popthisfilestack\StackTerm -} -\def\pushthisfilestackX{% - \expandafter\pushthisfilestackY\thisfile\StackTerm -} -\def\pushthisfilestackY #1\StackTerm #2\StackTerm {% - \gdef\popthisfilestack{\gdef\thisfile{#1}\gdef\popthisfilestack{#2}}% -} - -\def\popthisfilestack{\errthisfilestackempty} -\def\errthisfilestackempty{\errmessage{Internal error: - the stack of filenames is empty.}} - -\def\thisfile{} - -% @center line -% outputs that line, centered. -% -\parseargdef\center{% - \ifhmode - \let\next\centerH - \else - \let\next\centerV - \fi - \next{\hfil \ignorespaces#1\unskip \hfil}% -} -\def\centerH#1{% - {% - \hfil\break - \advance\hsize by -\leftskip - \advance\hsize by -\rightskip - \line{#1}% - \break - }% -} -\def\centerV#1{\line{\kern\leftskip #1\kern\rightskip}} - -% @sp n outputs n lines of vertical space - -\parseargdef\sp{\vskip #1\baselineskip} - -% @comment ...line which is ignored... -% @c is the same as @comment -% @ignore ... @end ignore is another way to write a comment - -\def\comment{\begingroup \catcode`\^^M=\other% -\catcode`\@=\other \catcode`\{=\other \catcode`\}=\other% -\commentxxx} -{\catcode`\^^M=\other \gdef\commentxxx#1^^M{\endgroup}} - -\let\c=\comment - -% @paragraphindent NCHARS -% We'll use ems for NCHARS, close enough. -% NCHARS can also be the word `asis' or `none'. -% We cannot feasibly implement @paragraphindent asis, though. -% -\def\asisword{asis} % no translation, these are keywords -\def\noneword{none} -% -\parseargdef\paragraphindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \defaultparindent = 0pt - \else - \defaultparindent = #1em - \fi - \fi - \parindent = \defaultparindent -} - -% @exampleindent NCHARS -% We'll use ems for NCHARS like @paragraphindent. -% It seems @exampleindent asis isn't necessary, but -% I preserve it to make it similar to @paragraphindent. -\parseargdef\exampleindent{% - \def\temp{#1}% - \ifx\temp\asisword - \else - \ifx\temp\noneword - \lispnarrowing = 0pt - \else - \lispnarrowing = #1em - \fi - \fi -} - -% @firstparagraphindent WORD -% If WORD is `none', then suppress indentation of the first paragraph -% after a section heading. If WORD is `insert', then do indent at such -% paragraphs. -% -% The paragraph indentation is suppressed or not by calling -% \suppressfirstparagraphindent, which the sectioning commands do. -% We switch the definition of this back and forth according to WORD. -% By default, we suppress indentation. -% -\def\suppressfirstparagraphindent{\dosuppressfirstparagraphindent} -\def\insertword{insert} -% -\parseargdef\firstparagraphindent{% - \def\temp{#1}% - \ifx\temp\noneword - \let\suppressfirstparagraphindent = \dosuppressfirstparagraphindent - \else\ifx\temp\insertword - \let\suppressfirstparagraphindent = \relax - \else - \errhelp = \EMsimple - \errmessage{Unknown @firstparagraphindent option `\temp'}% - \fi\fi -} - -% Here is how we actually suppress indentation. Redefine \everypar to -% \kern backwards by \parindent, and then reset itself to empty. -% -% We also make \indent itself not actually do anything until the next -% paragraph. -% -\gdef\dosuppressfirstparagraphindent{% - \gdef\indent{% - \restorefirstparagraphindent - \indent - }% - \gdef\noindent{% - \restorefirstparagraphindent - \noindent - }% - \global\everypar = {% - \kern -\parindent - \restorefirstparagraphindent - }% -} - -\gdef\restorefirstparagraphindent{% - \global \let \indent = \ptexindent - \global \let \noindent = \ptexnoindent - \global \everypar = {}% -} - - -% @asis just yields its argument. Used with @table, for example. -% -\def\asis#1{#1} - -% @math outputs its argument in math mode. -% -% One complication: _ usually means subscripts, but it could also mean -% an actual _ character, as in @math{@var{some_variable} + 1}. So make -% _ active, and distinguish by seeing if the current family is \slfam, -% which is what @var uses. -{ - \catcode`\_ = \active - \gdef\mathunderscore{% - \catcode`\_=\active - \def_{\ifnum\fam=\slfam \_\else\sb\fi}% - } -} -% Another complication: we want \\ (and @\) to output a \ character. -% FYI, plain.tex uses \\ as a temporary control sequence (why?), but -% this is not advertised and we don't care. Texinfo does not -% otherwise define @\. -% -% The \mathchar is class=0=ordinary, family=7=ttfam, position=5C=\. -\def\mathbackslash{\ifnum\fam=\ttfam \mathchar"075C \else\backslash \fi} -% -\def\math{% - \tex - \mathunderscore - \let\\ = \mathbackslash - \mathactive - $\finishmath -} -\def\finishmath#1{#1$\endgroup} % Close the group opened by \tex. - -% Some active characters (such as <) are spaced differently in math. -% We have to reset their definitions in case the @math was an argument -% to a command which sets the catcodes (such as @item or @section). -% -{ - \catcode`^ = \active - \catcode`< = \active - \catcode`> = \active - \catcode`+ = \active - \gdef\mathactive{% - \let^ = \ptexhat - \let< = \ptexless - \let> = \ptexgtr - \let+ = \ptexplus - } -} - -% @bullet and @minus need the same treatment as @math, just above. -\def\bullet{$\ptexbullet$} -\def\minus{$-$} - -% @dots{} outputs an ellipsis using the current font. -% We do .5em per period so that it has the same spacing in the cm -% typewriter fonts as three actual period characters; on the other hand, -% in other typewriter fonts three periods are wider than 1.5em. So do -% whichever is larger. -% -\def\dots{% - \leavevmode - \setbox0=\hbox{...}% get width of three periods - \ifdim\wd0 > 1.5em - \dimen0 = \wd0 - \else - \dimen0 = 1.5em - \fi - \hbox to \dimen0{% - \hskip 0pt plus.25fil - .\hskip 0pt plus1fil - .\hskip 0pt plus1fil - .\hskip 0pt plus.5fil - }% -} - -% @enddots{} is an end-of-sentence ellipsis. -% -\def\enddots{% - \dots - \spacefactor=\endofsentencespacefactor -} - -% @comma{} is so commas can be inserted into text without messing up -% Texinfo's parsing. -% -\let\comma = , - -% @refill is a no-op. -\let\refill=\relax - -% If working on a large document in chapters, it is convenient to -% be able to disable indexing, cross-referencing, and contents, for test runs. -% This is done with @novalidate (before @setfilename). -% -\newif\iflinks \linkstrue % by default we want the aux files. -\let\novalidate = \linksfalse - -% @setfilename is done at the beginning of every texinfo file. -% So open here the files we need to have open while reading the input. -% This makes it possible to make a .fmt file for texinfo. -\def\setfilename{% - \fixbackslash % Turn off hack to swallow `\input texinfo'. - \iflinks - \tryauxfile - % Open the new aux file. TeX will close it automatically at exit. - \immediate\openout\auxfile=\jobname.aux - \fi % \openindices needs to do some work in any case. - \openindices - \let\setfilename=\comment % Ignore extra @setfilename cmds. - % - % If texinfo.cnf is present on the system, read it. - % Useful for site-wide @afourpaper, etc. - \openin 1 texinfo.cnf - \ifeof 1 \else \input texinfo.cnf \fi - \closein 1 - % - \comment % Ignore the actual filename. -} - -% Called from \setfilename. -% -\def\openindices{% - \newindex{cp}% - \newcodeindex{fn}% - \newcodeindex{vr}% - \newcodeindex{tp}% - \newcodeindex{ky}% - \newcodeindex{pg}% -} - -% @bye. -\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} - - -\message{pdf,} -% adobe `portable' document format -\newcount\tempnum -\newcount\lnkcount -\newtoks\filename -\newcount\filenamelength -\newcount\pgn -\newtoks\toksA -\newtoks\toksB -\newtoks\toksC -\newtoks\toksD -\newbox\boxA -\newcount\countA -\newif\ifpdf -\newif\ifpdfmakepagedest - -% when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1 -% can be set). So we test for \relax and 0 as well as \undefined, -% borrowed from ifpdf.sty. -\ifx\pdfoutput\undefined -\else - \ifx\pdfoutput\relax - \else - \ifcase\pdfoutput - \else - \pdftrue - \fi - \fi -\fi - -% PDF uses PostScript string constants for the names of xref targets, -% for display in the outlines, and in other places. Thus, we have to -% double any backslashes. Otherwise, a name like "\node" will be -% interpreted as a newline (\n), followed by o, d, e. Not good. -% http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html -% (and related messages, the final outcome is that it is up to the TeX -% user to double the backslashes and otherwise make the string valid, so -% that's what we do). - -% double active backslashes. -% -{\catcode`\@=0 \catcode`\\=\active - @gdef@activebackslashdouble{% - @catcode`@\=@active - @let\=@doublebackslash} -} - -% To handle parens, we must adopt a different approach, since parens are -% not active characters. hyperref.dtx (which has the same problem as -% us) handles it with this amazing macro to replace tokens, with minor -% changes for Texinfo. It is included here under the GPL by permission -% from the author, Heiko Oberdiek. -% -% #1 is the tokens to replace. -% #2 is the replacement. -% #3 is the control sequence with the string. -% -\def\HyPsdSubst#1#2#3{% - \def\HyPsdReplace##1#1##2\END{% - ##1% - \ifx\\##2\\% - \else - #2% - \HyReturnAfterFi{% - \HyPsdReplace##2\END - }% - \fi - }% - \xdef#3{\expandafter\HyPsdReplace#3#1\END}% -} -\long\def\HyReturnAfterFi#1\fi{\fi#1} - -% #1 is a control sequence in which to do the replacements. -\def\backslashparens#1{% - \xdef#1{#1}% redefine it as its expansion; the definition is simply - % \lastnode when called from \setref -> \pdfmkdest. - \HyPsdSubst{(}{\realbackslash(}{#1}% - \HyPsdSubst{)}{\realbackslash)}{#1}% -} - -\newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images -with PDF output, and none of those formats could be found. (.eps cannot -be supported due to the design of the PDF format; use regular TeX (DVI -output) for that.)} - -\ifpdf - \input pdfcolor - \pdfcatalog{/PageMode /UseOutlines} - % - % #1 is image name, #2 width (might be empty/whitespace), #3 height (ditto). - \def\dopdfimage#1#2#3{% - \def\imagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% - \def\imageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% - % - % pdftex (and the PDF format) support .png, .jpg, .pdf (among - % others). Let's try in that order. - \let\pdfimgext=\empty - \begingroup - \openin 1 #1.png \ifeof 1 - \openin 1 #1.jpg \ifeof 1 - \openin 1 #1.jpeg \ifeof 1 - \openin 1 #1.JPG \ifeof 1 - \openin 1 #1.pdf \ifeof 1 - \errhelp = \nopdfimagehelp - \errmessage{Could not find image file #1 for pdf}% - \else \gdef\pdfimgext{pdf}% - \fi - \else \gdef\pdfimgext{JPG}% - \fi - \else \gdef\pdfimgext{jpeg}% - \fi - \else \gdef\pdfimgext{jpg}% - \fi - \else \gdef\pdfimgext{png}% - \fi - \closein 1 - \endgroup - % - % without \immediate, pdftex seg faults when the same image is - % included twice. (Version 3.14159-pre-1.0-unofficial-20010704.) - \ifnum\pdftexversion < 14 - \immediate\pdfimage - \else - \immediate\pdfximage - \fi - \ifdim \wd0 >0pt width \imagewidth \fi - \ifdim \wd2 >0pt height \imageheight \fi - \ifnum\pdftexversion<13 - #1.\pdfimgext - \else - {#1.\pdfimgext}% - \fi - \ifnum\pdftexversion < 14 \else - \pdfrefximage \pdflastximage - \fi} - % - \def\pdfmkdest#1{{% - % We have to set dummies so commands such as @code, and characters - % such as \, aren't expanded when present in a section title. - \indexnofonts - \turnoffactive - \activebackslashdouble - \makevalueexpandable - \def\pdfdestname{#1}% - \backslashparens\pdfdestname - \safewhatsit{\pdfdest name{\pdfdestname} xyz}% - }} - % - % used to mark target names; must be expandable. - \def\pdfmkpgn#1{#1} - % - % by default, use a color that is dark enough to print on paper as - % nearly black, but still distinguishable for online viewing. - % (Defined in pdfcolor.tex.) - \let\urlcolor = \BrickRed - \let\linkcolor = \BrickRed - \def\endlink{\Black\pdfendlink} - % - % Adding outlines to PDF; macros for calculating structure of outlines - % come from Petr Olsak - \def\expnumber#1{\expandafter\ifx\csname#1\endcsname\relax 0% - \else \csname#1\endcsname \fi} - \def\advancenumber#1{\tempnum=\expnumber{#1}\relax - \advance\tempnum by 1 - \expandafter\xdef\csname#1\endcsname{\the\tempnum}} - % - % #1 is the section text, which is what will be displayed in the - % outline by the pdf viewer. #2 is the pdf expression for the number - % of subentries (or empty, for subsubsections). #3 is the node text, - % which might be empty if this toc entry had no corresponding node. - % #4 is the page number - % - \def\dopdfoutline#1#2#3#4{% - % Generate a link to the node text if that exists; else, use the - % page number. We could generate a destination for the section - % text in the case where a section has no node, but it doesn't - % seem worth the trouble, since most documents are normally structured. - \def\pdfoutlinedest{#3}% - \ifx\pdfoutlinedest\empty - \def\pdfoutlinedest{#4}% - \else - % Doubled backslashes in the name. - {\activebackslashdouble \xdef\pdfoutlinedest{#3}% - \backslashparens\pdfoutlinedest}% - \fi - % - % Also double the backslashes in the display string. - {\activebackslashdouble \xdef\pdfoutlinetext{#1}% - \backslashparens\pdfoutlinetext}% - % - \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% - } - % - \def\pdfmakeoutlines{% - \begingroup - % Thanh's hack / proper braces in bookmarks - \edef\mylbrace{\iftrue \string{\else}\fi}\let\{=\mylbrace - \edef\myrbrace{\iffalse{\else\string}\fi}\let\}=\myrbrace - % - % Read toc silently, to get counts of subentries for \pdfoutline. - \def\numchapentry##1##2##3##4{% - \def\thischapnum{##2}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - }% - \def\numsecentry##1##2##3##4{% - \advancenumber{chap\thischapnum}% - \def\thissecnum{##2}% - \def\thissubsecnum{0}% - }% - \def\numsubsecentry##1##2##3##4{% - \advancenumber{sec\thissecnum}% - \def\thissubsecnum{##2}% - }% - \def\numsubsubsecentry##1##2##3##4{% - \advancenumber{subsec\thissubsecnum}% - }% - \def\thischapnum{0}% - \def\thissecnum{0}% - \def\thissubsecnum{0}% - % - % use \def rather than \let here because we redefine \chapentry et - % al. a second time, below. - \def\appentry{\numchapentry}% - \def\appsecentry{\numsecentry}% - \def\appsubsecentry{\numsubsecentry}% - \def\appsubsubsecentry{\numsubsubsecentry}% - \def\unnchapentry{\numchapentry}% - \def\unnsecentry{\numsecentry}% - \def\unnsubsecentry{\numsubsecentry}% - \def\unnsubsubsecentry{\numsubsubsecentry}% - \readdatafile{toc}% - % - % Read toc second time, this time actually producing the outlines. - % The `-' means take the \expnumber as the absolute number of - % subentries, which we calculated on our first read of the .toc above. - % - % We use the node names as the destinations. - \def\numchapentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% - \def\numsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% - \def\numsubsecentry##1##2##3##4{% - \dopdfoutline{##1}{count-\expnumber{subsec##2}}{##3}{##4}}% - \def\numsubsubsecentry##1##2##3##4{% count is always zero - \dopdfoutline{##1}{}{##3}{##4}}% - % - % PDF outlines are displayed using system fonts, instead of - % document fonts. Therefore we cannot use special characters, - % since the encoding is unknown. For example, the eogonek from - % Latin 2 (0xea) gets translated to a | character. Info from - % Staszek Wawrykiewicz, 19 Jan 2004 04:09:24 +0100. - % - % xx to do this right, we have to translate 8-bit characters to - % their "best" equivalent, based on the @documentencoding. Right - % now, I guess we'll just let the pdf reader have its way. - \indexnofonts - \setupdatafile - \catcode`\\=\active \otherbackslash - \input \tocreadfilename - \endgroup - } - % - \def\skipspaces#1{\def\PP{#1}\def\D{|}% - \ifx\PP\D\let\nextsp\relax - \else\let\nextsp\skipspaces - \ifx\p\space\else\addtokens{\filename}{\PP}% - \advance\filenamelength by 1 - \fi - \fi - \nextsp} - \def\getfilename#1{\filenamelength=0\expandafter\skipspaces#1|\relax} - \ifnum\pdftexversion < 14 - \let \startlink \pdfannotlink - \else - \let \startlink \pdfstartlink - \fi - % make a live url in pdf output. - \def\pdfurl#1{% - \begingroup - % it seems we really need yet another set of dummies; have not - % tried to figure out what each command should do in the context - % of @url. for now, just make @/ a no-op, that's the only one - % people have actually reported a problem with. - % - \normalturnoffactive - \def\@{@}% - \let\/=\empty - \makevalueexpandable - \leavevmode\urlcolor - \startlink attr{/Border [0 0 0]}% - user{/Subtype /Link /A << /S /URI /URI (#1) >>}% - \endgroup} - \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} - \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} - \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} - \def\poptoks#1#2|ENDTOKS|{\let\first=#1\toksD={#1}\toksA={#2}} - \def\maketoks{% - \expandafter\poptoks\the\toksA|ENDTOKS|\relax - \ifx\first0\adn0 - \else\ifx\first1\adn1 \else\ifx\first2\adn2 \else\ifx\first3\adn3 - \else\ifx\first4\adn4 \else\ifx\first5\adn5 \else\ifx\first6\adn6 - \else\ifx\first7\adn7 \else\ifx\first8\adn8 \else\ifx\first9\adn9 - \else - \ifnum0=\countA\else\makelink\fi - \ifx\first.\let\next=\done\else - \let\next=\maketoks - \addtokens{\toksB}{\the\toksD} - \ifx\first,\addtokens{\toksB}{\space}\fi - \fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \next} - \def\makelink{\addtokens{\toksB}% - {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} - \def\pdflink#1{% - \startlink attr{/Border [0 0 0]} goto name{\pdfmkpgn{#1}} - \linkcolor #1\endlink} - \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} -\else - \let\pdfmkdest = \gobble - \let\pdfurl = \gobble - \let\endlink = \relax - \let\linkcolor = \relax - \let\pdfmakeoutlines = \relax -\fi % \ifx\pdfoutput - - -\message{fonts,} - -% Change the current font style to #1, remembering it in \curfontstyle. -% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in -% italics, not bold italics. -% -\def\setfontstyle#1{% - \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. - \csname ten#1\endcsname % change the current font -} - -% Select #1 fonts with the current style. -% -\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} - -\def\rm{\fam=0 \setfontstyle{rm}} -\def\it{\fam=\itfam \setfontstyle{it}} -\def\sl{\fam=\slfam \setfontstyle{sl}} -\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}} - -% Texinfo sort of supports the sans serif font style, which plain TeX does not. -% So we set up a \sf. -\newfam\sffam -\def\sf{\fam=\sffam \setfontstyle{sf}} -\let\li = \sf % Sometimes we call it \li, not \sf. - -% We don't need math for this font style. -\def\ttsl{\setfontstyle{ttsl}} - - -% Default leading. -\newdimen\textleading \textleading = 13.2pt - -% Set the baselineskip to #1, and the lineskip and strut size -% correspondingly. There is no deep meaning behind these magic numbers -% used as factors; they just match (closely enough) what Knuth defined. -% -\def\lineskipfactor{.08333} -\def\strutheightpercent{.70833} -\def\strutdepthpercent {.29167} -% -\def\setleading#1{% - \normalbaselineskip = #1\relax - \normallineskip = \lineskipfactor\normalbaselineskip - \normalbaselines - \setbox\strutbox =\hbox{% - \vrule width0pt height\strutheightpercent\baselineskip - depth \strutdepthpercent \baselineskip - }% -} - -% -% PDF CMaps. See also LaTeX's t1.cmap. -% -% \cmapOT1 -\ifpdf - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1-0) -%%Title: (TeX-OT1-0 TeX OT1 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1) -/Supplement 0 ->> def -/CMapName /TeX-OT1-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -8 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<23> <26> <0023> -<28> <3B> <0028> -<3F> <5B> <003F> -<5D> <5E> <005D> -<61> <7A> <0061> -<7B> <7C> <2013> -endbfrange -40 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <00660066> -<0C> <00660069> -<0D> <0066006C> -<0E> <006600660069> -<0F> <00660066006C> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<21> <0021> -<22> <201D> -<27> <2019> -<3C> <00A1> -<3D> <003D> -<3E> <00BF> -<5C> <201C> -<5F> <02D9> -<60> <2018> -<7D> <02DD> -<7E> <007E> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -% -% \cmapOT1IT - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1IT-0) -%%Title: (TeX-OT1IT-0 TeX OT1IT 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1IT) -/Supplement 0 ->> def -/CMapName /TeX-OT1IT-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -8 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<25> <26> <0025> -<28> <3B> <0028> -<3F> <5B> <003F> -<5D> <5E> <005D> -<61> <7A> <0061> -<7B> <7C> <2013> -endbfrange -42 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <00660066> -<0C> <00660069> -<0D> <0066006C> -<0E> <006600660069> -<0F> <00660066006C> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<21> <0021> -<22> <201D> -<23> <0023> -<24> <00A3> -<27> <2019> -<3C> <00A1> -<3D> <003D> -<3E> <00BF> -<5C> <201C> -<5F> <02D9> -<60> <2018> -<7D> <02DD> -<7E> <007E> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1IT\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -% -% \cmapOT1TT - \begingroup - \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char. - \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap -%%DocumentNeededResources: ProcSet (CIDInit) -%%IncludeResource: ProcSet (CIDInit) -%%BeginResource: CMap (TeX-OT1TT-0) -%%Title: (TeX-OT1TT-0 TeX OT1TT 0) -%%Version: 1.000 -%%EndComments -/CIDInit /ProcSet findresource begin -12 dict begin -begincmap -/CIDSystemInfo -<< /Registry (TeX) -/Ordering (OT1TT) -/Supplement 0 ->> def -/CMapName /TeX-OT1TT-0 def -/CMapType 2 def -1 begincodespacerange -<00> <7F> -endcodespacerange -5 beginbfrange -<00> <01> <0393> -<09> <0A> <03A8> -<21> <26> <0021> -<28> <5F> <0028> -<61> <7E> <0061> -endbfrange -32 beginbfchar -<02> <0398> -<03> <039B> -<04> <039E> -<05> <03A0> -<06> <03A3> -<07> <03D2> -<08> <03A6> -<0B> <2191> -<0C> <2193> -<0D> <0027> -<0E> <00A1> -<0F> <00BF> -<10> <0131> -<11> <0237> -<12> <0060> -<13> <00B4> -<14> <02C7> -<15> <02D8> -<16> <00AF> -<17> <02DA> -<18> <00B8> -<19> <00DF> -<1A> <00E6> -<1B> <0153> -<1C> <00F8> -<1D> <00C6> -<1E> <0152> -<1F> <00D8> -<20> <2423> -<27> <2019> -<60> <2018> -<7F> <00A8> -endbfchar -endcmap -CMapName currentdict /CMap defineresource pop -end -end -%%EndResource -%%EOF - }\endgroup - \expandafter\edef\csname cmapOT1TT\endcsname#1{% - \pdffontattr#1{/ToUnicode \the\pdflastobj\space 0 R}% - }% -\else - \expandafter\let\csname cmapOT1\endcsname\gobble - \expandafter\let\csname cmapOT1IT\endcsname\gobble - \expandafter\let\csname cmapOT1TT\endcsname\gobble -\fi - - -% Set the font macro #1 to the font named #2, adding on the -% specified font prefix (normally `cm'). -% #3 is the font's design size, #4 is a scale factor, #5 is the CMap -% encoding (currently only OT1, OT1IT and OT1TT are allowed, pass -% empty to omit). -\def\setfont#1#2#3#4#5{% - \font#1=\fontprefix#2#3 scaled #4 - \csname cmap#5\endcsname#1% -} -% This is what gets called when #5 of \setfont is empty. -\let\cmap\gobble - - -% Use cm as the default font prefix. -% To specify the font prefix, you must define \fontprefix -% before you read in texinfo.tex. -\ifx\fontprefix\undefined -\def\fontprefix{cm} -\fi -% Support font families that don't use the same naming scheme as CM. -\def\rmshape{r} -\def\rmbshape{bx} %where the normal face is bold -\def\bfshape{b} -\def\bxshape{bx} -\def\ttshape{tt} -\def\ttbshape{tt} -\def\ttslshape{sltt} -\def\itshape{ti} -\def\itbshape{bxti} -\def\slshape{sl} -\def\slbshape{bxsl} -\def\sfshape{ss} -\def\sfbshape{ss} -\def\scshape{csc} -\def\scbshape{csc} - -% Definitions for a main text size of 11pt. This is the default in -% Texinfo. -% -\def\definetextfontsizexi{% -% Text fonts (11.2pt, magstep1). -\def\textnominalsize{11pt} -\edef\mainmagstep{\magstephalf} -\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} -\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} -\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} -\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} -\setfont\textsl\slshape{10}{\mainmagstep}{OT1} -\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} -\setfont\textsc\scshape{10}{\mainmagstep}{OT1} -\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstep1}{OT1} -\setfont\deftt\ttshape{10}{\magstep1}{OT1TT} -\setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000}{OT1} -\setfont\smalltt\ttshape{9}{1000}{OT1TT} -\setfont\smallbf\bfshape{10}{900}{OT1} -\setfont\smallit\itshape{9}{1000}{OT1IT} -\setfont\smallsl\slshape{9}{1000}{OT1} -\setfont\smallsf\sfshape{9}{1000}{OT1} -\setfont\smallsc\scshape{10}{900}{OT1} -\setfont\smallttsl\ttslshape{10}{900}{OT1TT} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000}{OT1} -\setfont\smallertt\ttshape{8}{1000}{OT1TT} -\setfont\smallerbf\bfshape{10}{800}{OT1} -\setfont\smallerit\itshape{8}{1000}{OT1IT} -\setfont\smallersl\slshape{8}{1000}{OT1} -\setfont\smallersf\sfshape{8}{1000}{OT1} -\setfont\smallersc\scshape{10}{800}{OT1} -\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} -\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} -\setfont\titlesl\slbshape{10}{\magstep4}{OT1} -\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} -\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} -\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4}{OT1} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} - -% Chapter (and unnumbered) fonts (17.28pt). -\def\chapnominalsize{17pt} -\setfont\chaprm\rmbshape{12}{\magstep2}{OT1} -\setfont\chapit\itbshape{10}{\magstep3}{OT1IT} -\setfont\chapsl\slbshape{10}{\magstep3}{OT1} -\setfont\chaptt\ttbshape{12}{\magstep2}{OT1TT} -\setfont\chapttsl\ttslshape{10}{\magstep3}{OT1TT} -\setfont\chapsf\sfbshape{17}{1000}{OT1} -\let\chapbf=\chaprm -\setfont\chapsc\scbshape{10}{\magstep3}{OT1} -\font\chapi=cmmi12 scaled \magstep2 -\font\chapsy=cmsy10 scaled \magstep3 - -% Section fonts (14.4pt). -\def\secnominalsize{14pt} -\setfont\secrm\rmbshape{12}{\magstep1}{OT1} -\setfont\secit\itbshape{10}{\magstep2}{OT1IT} -\setfont\secsl\slbshape{10}{\magstep2}{OT1} -\setfont\sectt\ttbshape{12}{\magstep1}{OT1TT} -\setfont\secttsl\ttslshape{10}{\magstep2}{OT1TT} -\setfont\secsf\sfbshape{12}{\magstep1}{OT1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep2}{OT1} -\font\seci=cmmi12 scaled \magstep1 -\font\secsy=cmsy10 scaled \magstep2 - -% Subsection fonts (13.15pt). -\def\ssecnominalsize{13pt} -\setfont\ssecrm\rmbshape{12}{\magstephalf}{OT1} -\setfont\ssecit\itbshape{10}{1315}{OT1IT} -\setfont\ssecsl\slbshape{10}{1315}{OT1} -\setfont\ssectt\ttbshape{12}{\magstephalf}{OT1TT} -\setfont\ssecttsl\ttslshape{10}{1315}{OT1TT} -\setfont\ssecsf\sfbshape{12}{\magstephalf}{OT1} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1315}{OT1} -\font\sseci=cmmi12 scaled \magstephalf -\font\ssecsy=cmsy10 scaled 1315 - -% Reduced fonts for @acro in text (10pt). -\def\reducednominalsize{10pt} -\setfont\reducedrm\rmshape{10}{1000}{OT1} -\setfont\reducedtt\ttshape{10}{1000}{OT1TT} -\setfont\reducedbf\bfshape{10}{1000}{OT1} -\setfont\reducedit\itshape{10}{1000}{OT1IT} -\setfont\reducedsl\slshape{10}{1000}{OT1} -\setfont\reducedsf\sfshape{10}{1000}{OT1} -\setfont\reducedsc\scshape{10}{1000}{OT1} -\setfont\reducedttsl\ttslshape{10}{1000}{OT1TT} -\font\reducedi=cmmi10 -\font\reducedsy=cmsy10 - -% reset the current fonts -\textfonts -\rm -} % end of 11pt text font size definitions - - -% Definitions to make the main text be 10pt Computer Modern, with -% section, chapter, etc., sizes following suit. This is for the GNU -% Press printing of the Emacs 22 manual. Maybe other manuals in the -% future. Used with @smallbook, which sets the leading to 12pt. -% -\def\definetextfontsizex{% -% Text fonts (10pt). -\def\textnominalsize{10pt} -\edef\mainmagstep{1000} -\setfont\textrm\rmshape{10}{\mainmagstep}{OT1} -\setfont\texttt\ttshape{10}{\mainmagstep}{OT1TT} -\setfont\textbf\bfshape{10}{\mainmagstep}{OT1} -\setfont\textit\itshape{10}{\mainmagstep}{OT1IT} -\setfont\textsl\slshape{10}{\mainmagstep}{OT1} -\setfont\textsf\sfshape{10}{\mainmagstep}{OT1} -\setfont\textsc\scshape{10}{\mainmagstep}{OT1} -\setfont\textttsl\ttslshape{10}{\mainmagstep}{OT1TT} -\font\texti=cmmi10 scaled \mainmagstep -\font\textsy=cmsy10 scaled \mainmagstep - -% A few fonts for @defun names and args. -\setfont\defbf\bfshape{10}{\magstephalf}{OT1} -\setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} -\setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf \let\tenttsl=\defttsl \bf} - -% Fonts for indices, footnotes, small examples (9pt). -\def\smallnominalsize{9pt} -\setfont\smallrm\rmshape{9}{1000}{OT1} -\setfont\smalltt\ttshape{9}{1000}{OT1TT} -\setfont\smallbf\bfshape{10}{900}{OT1} -\setfont\smallit\itshape{9}{1000}{OT1IT} -\setfont\smallsl\slshape{9}{1000}{OT1} -\setfont\smallsf\sfshape{9}{1000}{OT1} -\setfont\smallsc\scshape{10}{900}{OT1} -\setfont\smallttsl\ttslshape{10}{900}{OT1TT} -\font\smalli=cmmi9 -\font\smallsy=cmsy9 - -% Fonts for small examples (8pt). -\def\smallernominalsize{8pt} -\setfont\smallerrm\rmshape{8}{1000}{OT1} -\setfont\smallertt\ttshape{8}{1000}{OT1TT} -\setfont\smallerbf\bfshape{10}{800}{OT1} -\setfont\smallerit\itshape{8}{1000}{OT1IT} -\setfont\smallersl\slshape{8}{1000}{OT1} -\setfont\smallersf\sfshape{8}{1000}{OT1} -\setfont\smallersc\scshape{10}{800}{OT1} -\setfont\smallerttsl\ttslshape{10}{800}{OT1TT} -\font\smalleri=cmmi8 -\font\smallersy=cmsy8 - -% Fonts for title page (20.4pt): -\def\titlenominalsize{20pt} -\setfont\titlerm\rmbshape{12}{\magstep3}{OT1} -\setfont\titleit\itbshape{10}{\magstep4}{OT1IT} -\setfont\titlesl\slbshape{10}{\magstep4}{OT1} -\setfont\titlett\ttbshape{12}{\magstep3}{OT1TT} -\setfont\titlettsl\ttslshape{10}{\magstep4}{OT1TT} -\setfont\titlesf\sfbshape{17}{\magstep1}{OT1} -\let\titlebf=\titlerm -\setfont\titlesc\scbshape{10}{\magstep4}{OT1} -\font\titlei=cmmi12 scaled \magstep3 -\font\titlesy=cmsy10 scaled \magstep4 -\def\authorrm{\secrm} -\def\authortt{\sectt} - -% Chapter fonts (14.4pt). -\def\chapnominalsize{14pt} -\setfont\chaprm\rmbshape{12}{\magstep1}{OT1} -\setfont\chapit\itbshape{10}{\magstep2}{OT1IT} -\setfont\chapsl\slbshape{10}{\magstep2}{OT1} -\setfont\chaptt\ttbshape{12}{\magstep1}{OT1TT} -\setfont\chapttsl\ttslshape{10}{\magstep2}{OT1TT} -\setfont\chapsf\sfbshape{12}{\magstep1}{OT1} -\let\chapbf\chaprm -\setfont\chapsc\scbshape{10}{\magstep2}{OT1} -\font\chapi=cmmi12 scaled \magstep1 -\font\chapsy=cmsy10 scaled \magstep2 - -% Section fonts (12pt). -\def\secnominalsize{12pt} -\setfont\secrm\rmbshape{12}{1000}{OT1} -\setfont\secit\itbshape{10}{\magstep1}{OT1IT} -\setfont\secsl\slbshape{10}{\magstep1}{OT1} -\setfont\sectt\ttbshape{12}{1000}{OT1TT} -\setfont\secttsl\ttslshape{10}{\magstep1}{OT1TT} -\setfont\secsf\sfbshape{12}{1000}{OT1} -\let\secbf\secrm -\setfont\secsc\scbshape{10}{\magstep1}{OT1} -\font\seci=cmmi12 -\font\secsy=cmsy10 scaled \magstep1 - -% Subsection fonts (10pt). -\def\ssecnominalsize{10pt} -\setfont\ssecrm\rmbshape{10}{1000}{OT1} -\setfont\ssecit\itbshape{10}{1000}{OT1IT} -\setfont\ssecsl\slbshape{10}{1000}{OT1} -\setfont\ssectt\ttbshape{10}{1000}{OT1TT} -\setfont\ssecttsl\ttslshape{10}{1000}{OT1TT} -\setfont\ssecsf\sfbshape{10}{1000}{OT1} -\let\ssecbf\ssecrm -\setfont\ssecsc\scbshape{10}{1000}{OT1} -\font\sseci=cmmi10 -\font\ssecsy=cmsy10 - -% Reduced fonts for @acro in text (9pt). -\def\reducednominalsize{9pt} -\setfont\reducedrm\rmshape{9}{1000}{OT1} -\setfont\reducedtt\ttshape{9}{1000}{OT1TT} -\setfont\reducedbf\bfshape{10}{900}{OT1} -\setfont\reducedit\itshape{9}{1000}{OT1IT} -\setfont\reducedsl\slshape{9}{1000}{OT1} -\setfont\reducedsf\sfshape{9}{1000}{OT1} -\setfont\reducedsc\scshape{10}{900}{OT1} -\setfont\reducedttsl\ttslshape{10}{900}{OT1TT} -\font\reducedi=cmmi9 -\font\reducedsy=cmsy9 - -% reduce space between paragraphs -\divide\parskip by 2 - -% reset the current fonts -\textfonts -\rm -} % end of 10pt text font size definitions - - -% We provide the user-level command -% @fonttextsize 10 -% (or 11) to redefine the text font size. pt is assumed. -% -\def\xword{10} -\def\xiword{11} -% -\parseargdef\fonttextsize{% - \def\textsizearg{#1}% - \wlog{doing @fonttextsize \textsizearg}% - % - % Set \globaldefs so that documents can use this inside @tex, since - % makeinfo 4.8 does not support it, but we need it nonetheless. - % - \begingroup \globaldefs=1 - \ifx\textsizearg\xword \definetextfontsizex - \else \ifx\textsizearg\xiword \definetextfontsizexi - \else - \errhelp=\EMsimple - \errmessage{@fonttextsize only supports `10' or `11', not `\textsizearg'} - \fi\fi - \endgroup -} - - -% In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. Since -% texinfo doesn't allow for producing subscripts and superscripts except -% in the main text, we don't bother to reset \scriptfont and -% \scriptscriptfont (which would also require loading a lot more fonts). -% -\def\resetmathfonts{% - \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy - \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf - \textfont\ttfam=\tentt \textfont\sffam=\tensf -} - -% The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this because \STYLE needs to also set the -% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire -% \tenSTYLE to set the current font. -% -% Each font-changing command also sets the names \lsize (one size lower) -% and \lllsize (three sizes lower). These relative commands are used in -% the LaTeX logo and acronyms. -% -% This all needs generalizing, badly. -% -\def\textfonts{% - \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl - \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy - \let\tenttsl=\textttsl - \def\curfontsize{text}% - \def\lsize{reduced}\def\lllsize{smaller}% - \resetmathfonts \setleading{\textleading}} -\def\titlefonts{% - \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl - \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc - \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy - \let\tenttsl=\titlettsl - \def\curfontsize{title}% - \def\lsize{chap}\def\lllsize{subsec}% - \resetmathfonts \setleading{25pt}} -\def\titlefont#1{{\titlefonts\rm #1}} -\def\chapfonts{% - \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl - \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy - \let\tenttsl=\chapttsl - \def\curfontsize{chap}% - \def\lsize{sec}\def\lllsize{text}% - \resetmathfonts \setleading{19pt}} -\def\secfonts{% - \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl - \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy - \let\tenttsl=\secttsl - \def\curfontsize{sec}% - \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{16pt}} -\def\subsecfonts{% - \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl - \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy - \let\tenttsl=\ssecttsl - \def\curfontsize{ssec}% - \def\lsize{text}\def\lllsize{small}% - \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts -\def\reducedfonts{% - \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl - \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc - \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy - \let\tenttsl=\reducedttsl - \def\curfontsize{reduced}% - \def\lsize{small}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallfonts{% - \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl - \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc - \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy - \let\tenttsl=\smallttsl - \def\curfontsize{small}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallerfonts{% - \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl - \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc - \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy - \let\tenttsl=\smallerttsl - \def\curfontsize{smaller}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{9.5pt}} - -% Set the fonts to use with the @small... environments. -\let\smallexamplefonts = \smallfonts - -% About \smallexamplefonts. If we use \smallfonts (9pt), @smallexample -% can fit this many characters: -% 8.5x11=86 smallbook=72 a4=90 a5=69 -% If we use \scriptfonts (8pt), then we can fit this many characters: -% 8.5x11=90+ smallbook=80 a4=90+ a5=77 -% For me, subjectively, the few extra characters that fit aren't worth -% the additional smallness of 8pt. So I'm making the default 9pt. -% -% By the way, for comparison, here's what fits with @example (10pt): -% 8.5x11=71 smallbook=60 a4=75 a5=58 -% -% I wish the USA used A4 paper. -% --karl, 24jan03. - - -% Set up the default fonts, so we can use them for creating boxes. -% -\definetextfontsizexi - -% Define these so they can be easily changed for other fonts. -\def\angleleft{$\langle$} -\def\angleright{$\rangle$} - -% Count depth in font-changes, for error checks -\newcount\fontdepth \fontdepth=0 - -% Fonts for short table of contents. -\setfont\shortcontrm\rmshape{12}{1000}{OT1} -\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 -\setfont\shortcontsl\slshape{12}{1000}{OT1} -\setfont\shortconttt\ttshape{12}{1000}{OT1TT} - -%% Add scribe-like font environments, plus @l for inline lisp (usually sans -%% serif) and @ii for TeX italic - -% \smartitalic{ARG} outputs arg in italics, followed by an italic correction -% unless the following character is such as not to need one. -\def\smartitalicx{\ifx\next,\else\ifx\next-\else\ifx\next.\else - \ptexslash\fi\fi\fi} -\def\smartslanted#1{{\ifusingtt\ttsl\sl #1}\futurelet\next\smartitalicx} -\def\smartitalic#1{{\ifusingtt\ttsl\it #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally uses \ttsl. -% @var is set to this for defun arguments. -\def\ttslanted#1{{\ttsl #1}\futurelet\next\smartitalicx} - -% like \smartslanted except unconditionally use \sl. We never want -% ttsl for book titles, do we? -\def\cite#1{{\sl #1}\futurelet\next\smartitalicx} - -\let\i=\smartitalic -\let\slanted=\smartslanted -\let\var=\smartslanted -\let\dfn=\smartslanted -\let\emph=\smartitalic - -% @b, explicit bold. -\def\b#1{{\bf #1}} -\let\strong=\b - -% @sansserif, explicit sans. -\def\sansserif#1{{\sf #1}} - -% We can't just use \exhyphenpenalty, because that only has effect at -% the end of a paragraph. Restore normal hyphenation at the end of the -% group within which \nohyphenation is presumably called. -% -\def\nohyphenation{\hyphenchar\font = -1 \aftergroup\restorehyphenation} -\def\restorehyphenation{\hyphenchar\font = `- } - -% Set sfcode to normal for the chars that usually have another value. -% Can't use plain's \frenchspacing because it uses the `\x notation, and -% sometimes \x has an active definition that messes things up. -% -\catcode`@=11 - \def\plainfrenchspacing{% - \sfcode\dotChar =\@m \sfcode\questChar=\@m \sfcode\exclamChar=\@m - \sfcode\colonChar=\@m \sfcode\semiChar =\@m \sfcode\commaChar =\@m - \def\endofsentencespacefactor{1000}% for @. and friends - } - \def\plainnonfrenchspacing{% - \sfcode`\.3000\sfcode`\?3000\sfcode`\!3000 - \sfcode`\:2000\sfcode`\;1500\sfcode`\,1250 - \def\endofsentencespacefactor{3000}% for @. and friends - } -\catcode`@=\other -\def\endofsentencespacefactor{3000}% default - -\def\t#1{% - {\tt \rawbackslash \plainfrenchspacing #1}% - \null -} -\def\samp#1{`\tclose{#1}'\null} -\setfont\keyrm\rmshape{8}{1000}{OT1} -\font\keysy=cmsy9 -\def\key#1{{\keyrm\textfont2=\keysy \leavevmode\hbox{% - \raise0.4pt\hbox{\angleleft}\kern-.08em\vtop{% - \vbox{\hrule\kern-0.4pt - \hbox{\raise0.4pt\hbox{\vphantom{\angleleft}}#1}}% - \kern-0.4pt\hrule}% - \kern-.06em\raise0.4pt\hbox{\angleright}}}} -\def\key #1{{\nohyphenation \uppercase{#1}}\null} -% The old definition, with no lozenge: -%\def\key #1{{\ttsl \nohyphenation \uppercase{#1}}\null} -\def\ctrl #1{{\tt \rawbackslash \hat}#1} - -% @file, @option are the same as @samp. -\let\file=\samp -\let\option=\samp - -% @code is a modification of @t, -% which makes spaces the same size as normal in the surrounding text. -\def\tclose#1{% - {% - % Change normal interword space to be same as for the current font. - \spaceskip = \fontdimen2\font - % - % Switch to typewriter. - \tt - % - % But `\ ' produces the large typewriter interword space. - \def\ {{\spaceskip = 0pt{} }}% - % - % Turn off hyphenation. - \nohyphenation - % - \rawbackslash - \plainfrenchspacing - #1% - }% - \null -} - -% We *must* turn on hyphenation at `-' and `_' in @code. -% Otherwise, it is too hard to avoid overfull hboxes -% in the Emacs manual, the Library manual, etc. - -% Unfortunately, TeX uses one parameter (\hyphenchar) to control -% both hyphenation at - and hyphenation within words. -% We must therefore turn them both off (\tclose does that) -% and arrange explicitly to hyphenate at a dash. -% -- rms. -{ - \catcode`\-=\active \catcode`\_=\active - \catcode`\'=\active \catcode`\`=\active - % - \global\def\code{\begingroup - \catcode\rquoteChar=\active \catcode\lquoteChar=\active - \let'\codequoteright \let`\codequoteleft - % - \catcode\dashChar=\active \catcode\underChar=\active - \ifallowcodebreaks - \let-\codedash - \let_\codeunder - \else - \let-\realdash - \let_\realunder - \fi - \codex - } -} - -\def\realdash{-} -\def\codedash{-\discretionary{}{}{}} -\def\codeunder{% - % this is all so @math{@code{var_name}+1} can work. In math mode, _ - % is "active" (mathcode"8000) and \normalunderscore (or \char95, etc.) - % will therefore expand the active definition of _, which is us - % (inside @code that is), therefore an endless loop. - \ifusingtt{\ifmmode - \mathchar"075F % class 0=ordinary, family 7=ttfam, pos 0x5F=_. - \else\normalunderscore \fi - \discretionary{}{}{}}% - {\_}% -} -\def\codex #1{\tclose{#1}\endgroup} - -% An additional complication: the above will allow breaks after, e.g., -% each of the four underscores in __typeof__. This is undesirable in -% some manuals, especially if they don't have long identifiers in -% general. @allowcodebreaks provides a way to control this. -% -\newif\ifallowcodebreaks \allowcodebreakstrue - -\def\keywordtrue{true} -\def\keywordfalse{false} - -\parseargdef\allowcodebreaks{% - \def\txiarg{#1}% - \ifx\txiarg\keywordtrue - \allowcodebreakstrue - \else\ifx\txiarg\keywordfalse - \allowcodebreaksfalse - \else - \errhelp = \EMsimple - \errmessage{Unknown @allowcodebreaks option `\txiarg'}% - \fi\fi -} - -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. - -% @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), -% `example' (@kbd uses ttsl only inside of @example and friends), -% or `code' (@kbd uses normal tty font always). -\parseargdef\kbdinputstyle{% - \def\txiarg{#1}% - \ifx\txiarg\worddistinct - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\ttsl}% - \else\ifx\txiarg\wordexample - \gdef\kbdexamplefont{\ttsl}\gdef\kbdfont{\tt}% - \else\ifx\txiarg\wordcode - \gdef\kbdexamplefont{\tt}\gdef\kbdfont{\tt}% - \else - \errhelp = \EMsimple - \errmessage{Unknown @kbdinputstyle option `\txiarg'}% - \fi\fi\fi -} -\def\worddistinct{distinct} -\def\wordexample{example} -\def\wordcode{code} - -% Default is `distinct.' -\kbdinputstyle distinct - -\def\xkey{\key} -\def\kbdfoo#1#2#3\par{\def\one{#1}\def\three{#3}\def\threex{??}% -\ifx\one\xkey\ifx\threex\three \key{#2}% -\else{\tclose{\kbdfont\look}}\fi -\else{\tclose{\kbdfont\look}}\fi} - -% For @indicateurl, @env, @command quotes seem unnecessary, so use \code. -\let\indicateurl=\code -\let\env=\code -\let\command=\code - -% @uref (abbreviation for `urlref') takes an optional (comma-separated) -% second argument specifying the text to display and an optional third -% arg as text to display instead of (rather than in addition to) the url -% itself. First (mandatory) arg is the url. Perhaps eventually put in -% a hypertex \special here. -% -\def\uref#1{\douref #1,,,\finish} -\def\douref#1,#2,#3,#4\finish{\begingroup - \unsepspaces - \pdfurl{#1}% - \setbox0 = \hbox{\ignorespaces #3}% - \ifdim\wd0 > 0pt - \unhbox0 % third arg given, show only that - \else - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0 > 0pt - \ifpdf - \unhbox0 % PDF: 2nd arg given, show only it - \else - \unhbox0\ (\code{#1})% DVI: 2nd arg given, show both it and url - \fi - \else - \code{#1}% only url given, so show it - \fi - \fi - \endlink -\endgroup} - -% @url synonym for @uref, since that's how everyone uses it. -% -\let\url=\uref - -% rms does not like angle brackets --karl, 17may97. -% So now @email is just like @uref, unless we are pdf. -% -%\def\email#1{\angleleft{\tt #1}\angleright} -\ifpdf - \def\email#1{\doemail#1,,\finish} - \def\doemail#1,#2,#3\finish{\begingroup - \unsepspaces - \pdfurl{mailto:#1}% - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi - \endlink - \endgroup} -\else - \let\email=\uref -\fi - -% Check if we are currently using a typewriter font. Since all the -% Computer Modern typewriter fonts have zero interword stretch (and -% shrink), and it is reasonable to expect all typewriter fonts to have -% this property, we can check that font parameter. -% -\def\ifmonospace{\ifdim\fontdimen3\font=0pt } - -% Typeset a dimension, e.g., `in' or `pt'. The only reason for the -% argument is to make the input look right: @dmn{pt} instead of @dmn{}pt. -% -\def\dmn#1{\thinspace #1} - -\def\kbd#1{\def\look{#1}\expandafter\kbdfoo\look??\par} - -% @l was never documented to mean ``switch to the Lisp font'', -% and it is not used as such in any manual I can find. We need it for -% Polish suppressed-l. --karl, 22sep96. -%\def\l#1{{\li #1}\null} - -% Explicit font changes: @r, @sc, undocumented @ii. -\def\r#1{{\rm #1}} % roman font -\def\sc#1{{\smallcaps#1}} % smallcaps font -\def\ii#1{{\it #1}} % italic font - -% @acronym for "FBI", "NATO", and the like. -% We print this one point size smaller, since it's intended for -% all-uppercase. -% -\def\acronym#1{\doacronym #1,,\finish} -\def\doacronym#1,#2,#3\finish{% - {\selectfonts\lsize #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @abbr for "Comput. J." and the like. -% No font change, but don't do end-of-sentence spacing. -% -\def\abbr#1{\doabbr #1,,\finish} -\def\doabbr#1,#2,#3\finish{% - {\plainfrenchspacing #1}% - \def\temp{#2}% - \ifx\temp\empty \else - \space ({\unsepspaces \ignorespaces \temp \unskip})% - \fi -} - -% @pounds{} is a sterling sign, which Knuth put in the CM italic font. -% -\def\pounds{{\it\$}} - -% @euro{} comes from a separate font, depending on the current style. -% We use the free feym* fonts from the eurosym package by Henrik -% Theiling, which support regular, slanted, bold and bold slanted (and -% "outlined" (blackboard board, sort of) versions, which we don't need). -% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. -% -% Although only regular is the truly official Euro symbol, we ignore -% that. The Euro is designed to be slightly taller than the regular -% font height. -% -% feymr - regular -% feymo - slanted -% feybr - bold -% feybo - bold slanted -% -% There is no good (free) typewriter version, to my knowledge. -% A feymr10 euro is ~7.3pt wide, while a normal cmtt10 char is ~5.25pt wide. -% Hmm. -% -% Also doesn't work in math. Do we need to do math with euro symbols? -% Hope not. -% -% -\def\euro{{\eurofont e}} -\def\eurofont{% - % We set the font at each command, rather than predefining it in - % \textfonts and the other font-switching commands, so that - % installations which never need the symbol don't have to have the - % font installed. - % - % There is only one designed size (nominal 10pt), so we always scale - % that to the current nominal size. - % - % By the way, simply using "at 1em" works for cmr10 and the like, but - % does not work for cmbx10 and other extended/shrunken fonts. - % - \def\eurosize{\csname\curfontsize nominalsize\endcsname}% - % - \ifx\curfontstyle\bfstylename - % bold: - \font\thiseurofont = \ifusingit{feybo10}{feybr10} at \eurosize - \else - % regular: - \font\thiseurofont = \ifusingit{feymo10}{feymr10} at \eurosize - \fi - \thiseurofont -} - -% @registeredsymbol - R in a circle. The font for the R should really -% be smaller yet, but lllsize is the best we can do for now. -% Adapted from the plain.tex definition of \copyright. -% -\def\registeredsymbol{% - $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% - \hfil\crcr\Orb}}% - }$% -} - -% @textdegree - the normal degrees sign. -% -\def\textdegree{$^\circ$} - -% Laurent Siebenmann reports \Orb undefined with: -% Textures 1.7.7 (preloaded format=plain 93.10.14) (68K) 16 APR 2004 02:38 -% so we'll define it if necessary. -% -\ifx\Orb\undefined -\def\Orb{\mathhexbox20D} -\fi - - -\message{page headings,} - -\newskip\titlepagetopglue \titlepagetopglue = 1.5in -\newskip\titlepagebottomglue \titlepagebottomglue = 2pc - -% First the title page. Must do @settitle before @titlepage. -\newif\ifseenauthor -\newif\iffinishedtitlepage - -% Do an implicit @contents or @shortcontents after @end titlepage if the -% user says @setcontentsaftertitlepage or @setshortcontentsaftertitlepage. -% -\newif\ifsetcontentsaftertitlepage - \let\setcontentsaftertitlepage = \setcontentsaftertitlepagetrue -\newif\ifsetshortcontentsaftertitlepage - \let\setshortcontentsaftertitlepage = \setshortcontentsaftertitlepagetrue - -\parseargdef\shorttitlepage{\begingroup\hbox{}\vskip 1.5in \chaprm \centerline{#1}% - \endgroup\page\hbox{}\page} - -\envdef\titlepage{% - % Open one extra group, as we want to close it in the middle of \Etitlepage. - \begingroup - \parindent=0pt \textfonts - % Leave some space at the very top of the page. - \vglue\titlepagetopglue - % No rule at page bottom unless we print one at the top with @title. - \finishedtitlepagetrue - % - % Most title ``pages'' are actually two pages long, with space - % at the top of the second. We don't want the ragged left on the second. - \let\oldpage = \page - \def\page{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - \let\page = \oldpage - \page - \null - }% -} - -\def\Etitlepage{% - \iffinishedtitlepage\else - \finishtitlepage - \fi - % It is important to do the page break before ending the group, - % because the headline and footline are only empty inside the group. - % If we use the new definition of \page, we always get a blank page - % after the title page, which we certainly don't want. - \oldpage - \endgroup - % - % Need this before the \...aftertitlepage checks so that if they are - % in effect the toc pages will come out with page numbers. - \HEADINGSon - % - % If they want short, they certainly want long too. - \ifsetshortcontentsaftertitlepage - \shortcontents - \contents - \global\let\shortcontents = \relax - \global\let\contents = \relax - \fi - % - \ifsetcontentsaftertitlepage - \contents - \global\let\contents = \relax - \global\let\shortcontents = \relax - \fi -} - -\def\finishtitlepage{% - \vskip4pt \hrule height 2pt width \hsize - \vskip\titlepagebottomglue - \finishedtitlepagetrue -} - -%%% Macros to be used within @titlepage: - -\let\subtitlerm=\tenrm -\def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} - -\def\authorfont{\authorrm \normalbaselineskip = 16pt \normalbaselines - \let\tt=\authortt} - -\parseargdef\title{% - \checkenv\titlepage - \leftline{\titlefonts\rm #1} - % print a rule at the page bottom also. - \finishedtitlepagefalse - \vskip4pt \hrule height 4pt width \hsize \vskip4pt -} - -\parseargdef\subtitle{% - \checkenv\titlepage - {\subtitlefont \rightline{#1}}% -} - -% @author should come last, but may come many times. -% It can also be used inside @quotation. -% -\parseargdef\author{% - \def\temp{\quotation}% - \ifx\thisenv\temp - \def\quotationauthor{#1}% printed in \Equotation. - \else - \checkenv\titlepage - \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi - {\authorfont \leftline{#1}}% - \fi -} - - -%%% Set up page headings and footings. - -\let\thispage=\folio - -\newtoks\evenheadline % headline on even pages -\newtoks\oddheadline % headline on odd pages -\newtoks\evenfootline % footline on even pages -\newtoks\oddfootline % footline on odd pages - -% Now make TeX use those variables -\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline - \else \the\evenheadline \fi}} -\footline={{\textfonts\rm \ifodd\pageno \the\oddfootline - \else \the\evenfootline \fi}\HEADINGShook} -\let\HEADINGShook=\relax - -% Commands to set those variables. -% For example, this is what @headings on does -% @evenheading @thistitle|@thispage|@thischapter -% @oddheading @thischapter|@thispage|@thistitle -% @evenfooting @thisfile|| -% @oddfooting ||@thisfile - - -\def\evenheading{\parsearg\evenheadingxxx} -\def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} -\def\evenheadingyyy #1\|#2\|#3\|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddheading{\parsearg\oddheadingxxx} -\def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} -\def\oddheadingyyy #1\|#2\|#3\|#4\finish{% -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% - -\def\evenfooting{\parsearg\evenfootingxxx} -\def\evenfootingxxx #1{\evenfootingyyy #1\|\|\|\|\finish} -\def\evenfootingyyy #1\|#2\|#3\|#4\finish{% -\global\evenfootline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} - -\def\oddfooting{\parsearg\oddfootingxxx} -\def\oddfootingxxx #1{\oddfootingyyy #1\|\|\|\|\finish} -\def\oddfootingyyy #1\|#2\|#3\|#4\finish{% - \global\oddfootline = {\rlap{\centerline{#2}}\line{#1\hfil#3}}% - % - % Leave some space for the footline. Hopefully ok to assume - % @evenfooting will not be used by itself. - \global\advance\pageheight by -12pt - \global\advance\vsize by -12pt -} - -\parseargdef\everyfooting{\oddfootingxxx{#1}\evenfootingxxx{#1}} - - -% @headings double turns headings on for double-sided printing. -% @headings single turns headings on for single-sided printing. -% @headings off turns them off. -% @headings on same as @headings double, retained for compatibility. -% @headings after turns on double-sided headings after this page. -% @headings doubleafter turns on double-sided headings after this page. -% @headings singleafter turns on single-sided headings after this page. -% By default, they are off at the start of a document, -% and turned `on' after @end titlepage. - -\def\headings #1 {\csname HEADINGS#1\endcsname} - -\def\HEADINGSoff{% -\global\evenheadline={\hfil} \global\evenfootline={\hfil} -\global\oddheadline={\hfil} \global\oddfootline={\hfil}} -\HEADINGSoff -% When we turn headings on, set the page number to 1. -% For double-sided printing, put current file name in lower left corner, -% chapter name on inside top of right hand pages, document -% title on inside top of left hand pages, and page numbers on outside top -% edge of all pages. -\def\HEADINGSdouble{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} -\let\contentsalignmacro = \chappager - -% For single-sided printing, chapter title goes across top left of page, -% page number on top right. -\def\HEADINGSsingle{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} -\def\HEADINGSon{\HEADINGSdouble} - -\def\HEADINGSafter{\let\HEADINGShook=\HEADINGSdoublex} -\let\HEADINGSdoubleafter=\HEADINGSafter -\def\HEADINGSdoublex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage -} - -\def\HEADINGSsingleafter{\let\HEADINGShook=\HEADINGSsinglex} -\def\HEADINGSsinglex{% -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapter\hfil\folio}} -\global\oddheadline={\line{\thischapter\hfil\folio}} -\global\let\contentsalignmacro = \chappager -} - -% Subroutines used in generating headings -% This produces Day Month Year style of output. -% Only define if not already defined, in case a txi-??.tex file has set -% up a different format (e.g., txi-cs.tex does this). -\ifx\today\undefined -\def\today{% - \number\day\space - \ifcase\month - \or\putwordMJan\or\putwordMFeb\or\putwordMMar\or\putwordMApr - \or\putwordMMay\or\putwordMJun\or\putwordMJul\or\putwordMAug - \or\putwordMSep\or\putwordMOct\or\putwordMNov\or\putwordMDec - \fi - \space\number\year} -\fi - -% @settitle line... specifies the title of the document, for headings. -% It generates no output of its own. -\def\thistitle{\putwordNoTitle} -\def\settitle{\parsearg{\gdef\thistitle}} - - -\message{tables,} -% Tables -- @table, @ftable, @vtable, @item(x). - -% default indentation of table text -\newdimen\tableindent \tableindent=.8in -% default indentation of @itemize and @enumerate text -\newdimen\itemindent \itemindent=.3in -% margin between end of table item and start of table text. -\newdimen\itemmargin \itemmargin=.1in - -% used internally for \itemindent minus \itemmargin -\newdimen\itemmax - -% Note @table, @ftable, and @vtable define @item, @itemx, etc., with -% these defs. -% They also define \itemindex -% to index the item name in whatever manner is desired (perhaps none). - -\newif\ifitemxneedsnegativevskip - -\def\itemxpar{\par\ifitemxneedsnegativevskip\nobreak\vskip-\parskip\nobreak\fi} - -\def\internalBitem{\smallbreak \parsearg\itemzzz} -\def\internalBitemx{\itemxpar \parsearg\itemzzz} - -\def\itemzzz #1{\begingroup % - \advance\hsize by -\rightskip - \advance\hsize by -\tableindent - \setbox0=\hbox{\itemindicate{#1}}% - \itemindex{#1}% - \nobreak % This prevents a break before @itemx. - % - % If the item text does not fit in the space we have, put it on a line - % by itself, and do not allow a page break either before or after that - % line. We do not start a paragraph here because then if the next - % command is, e.g., @kindex, the whatsit would get put into the - % horizontal list on a line by itself, resulting in extra blank space. - \ifdim \wd0>\itemmax - % - % Make this a paragraph so we get the \parskip glue and wrapping, - % but leave it ragged-right. - \begingroup - \advance\leftskip by-\tableindent - \advance\hsize by\tableindent - \advance\rightskip by0pt plus1fil - \leavevmode\unhbox0\par - \endgroup - % - % We're going to be starting a paragraph, but we don't want the - % \parskip glue -- logically it's part of the @item we just started. - \nobreak \vskip-\parskip - % - % Stop a page break at the \parskip glue coming up. However, if - % what follows is an environment such as @example, there will be no - % \parskip glue; then the negative vskip we just inserted would - % cause the example and the item to crash together. So we use this - % bizarre value of 10001 as a signal to \aboveenvbreak to insert - % \parskip glue after all. Section titles are handled this way also. - % - \penalty 10001 - \endgroup - \itemxneedsnegativevskipfalse - \else - % The item text fits into the space. Start a paragraph, so that the - % following text (if any) will end up on the same line. - \noindent - % Do this with kerns and \unhbox so that if there is a footnote in - % the item text, it can migrate to the main vertical list and - % eventually be printed. - \nobreak\kern-\tableindent - \dimen0 = \itemmax \advance\dimen0 by \itemmargin \advance\dimen0 by -\wd0 - \unhbox0 - \nobreak\kern\dimen0 - \endgroup - \itemxneedsnegativevskiptrue - \fi -} - -\def\item{\errmessage{@item while not in a list environment}} -\def\itemx{\errmessage{@itemx while not in a list environment}} - -% @table, @ftable, @vtable. -\envdef\table{% - \let\itemindex\gobble - \tablecheck{table}% -} -\envdef\ftable{% - \def\itemindex ##1{\doind {fn}{\code{##1}}}% - \tablecheck{ftable}% -} -\envdef\vtable{% - \def\itemindex ##1{\doind {vr}{\code{##1}}}% - \tablecheck{vtable}% -} -\def\tablecheck#1{% - \ifnum \the\catcode`\^^M=\active - \endgroup - \errmessage{This command won't work in this context; perhaps the problem is - that we are \inenvironment\thisenv}% - \def\next{\doignore{#1}}% - \else - \let\next\tablex - \fi - \next -} -\def\tablex#1{% - \def\itemindicate{#1}% - \parsearg\tabley -} -\def\tabley#1{% - {% - \makevalueexpandable - \edef\temp{\noexpand\tablez #1\space\space\space}% - \expandafter - }\temp \endtablez -} -\def\tablez #1 #2 #3 #4\endtablez{% - \aboveenvbreak - \ifnum 0#1>0 \advance \leftskip by #1\mil \fi - \ifnum 0#2>0 \tableindent=#2\mil \fi - \ifnum 0#3>0 \advance \rightskip by #3\mil \fi - \itemmax=\tableindent - \advance \itemmax by -\itemmargin - \advance \leftskip by \tableindent - \exdentamount=\tableindent - \parindent = 0pt - \parskip = \smallskipamount - \ifdim \parskip=0pt \parskip=2pt \fi - \let\item = \internalBitem - \let\itemx = \internalBitemx -} -\def\Etable{\endgraf\afterenvbreak} -\let\Eftable\Etable -\let\Evtable\Etable -\let\Eitemize\Etable -\let\Eenumerate\Etable - -% This is the counter used by @enumerate, which is really @itemize - -\newcount \itemno - -\envdef\itemize{\parsearg\doitemize} - -\def\doitemize#1{% - \aboveenvbreak - \itemmax=\itemindent - \advance\itemmax by -\itemmargin - \advance\leftskip by \itemindent - \exdentamount=\itemindent - \parindent=0pt - \parskip=\smallskipamount - \ifdim\parskip=0pt \parskip=2pt \fi - \def\itemcontents{#1}% - % @itemize with no arg is equivalent to @itemize @bullet. - \ifx\itemcontents\empty\def\itemcontents{\bullet}\fi - \let\item=\itemizeitem -} - -% Definition of @item while inside @itemize and @enumerate. -% -\def\itemizeitem{% - \advance\itemno by 1 % for enumerations - {\let\par=\endgraf \smallbreak}% reasonable place to break - {% - % If the document has an @itemize directly after a section title, a - % \nobreak will be last on the list, and \sectionheading will have - % done a \vskip-\parskip. In that case, we don't want to zero - % parskip, or the item text will crash with the heading. On the - % other hand, when there is normal text preceding the item (as there - % usually is), we do want to zero parskip, or there would be too much - % space. In that case, we won't have a \nobreak before. At least - % that's the theory. - \ifnum\lastpenalty<10000 \parskip=0in \fi - \noindent - \hbox to 0pt{\hss \itemcontents \kern\itemmargin}% - \vadjust{\penalty 1200}}% not good to break after first line of item. - \flushcr -} - -% \splitoff TOKENS\endmark defines \first to be the first token in -% TOKENS, and \rest to be the remainder. -% -\def\splitoff#1#2\endmark{\def\first{#1}\def\rest{#2}}% - -% Allow an optional argument of an uppercase letter, lowercase letter, -% or number, to specify the first label in the enumerated list. No -% argument is the same as `1'. -% -\envparseargdef\enumerate{\enumeratey #1 \endenumeratey} -\def\enumeratey #1 #2\endenumeratey{% - % If we were given no argument, pretend we were given `1'. - \def\thearg{#1}% - \ifx\thearg\empty \def\thearg{1}\fi - % - % Detect if the argument is a single token. If so, it might be a - % letter. Otherwise, the only valid thing it can be is a number. - % (We will always have one token, because of the test we just made. - % This is a good thing, since \splitoff doesn't work given nothing at - % all -- the first parameter is undelimited.) - \expandafter\splitoff\thearg\endmark - \ifx\rest\empty - % Only one token in the argument. It could still be anything. - % A ``lowercase letter'' is one whose \lccode is nonzero. - % An ``uppercase letter'' is one whose \lccode is both nonzero, and - % not equal to itself. - % Otherwise, we assume it's a number. - % - % We need the \relax at the end of the \ifnum lines to stop TeX from - % continuing to look for a . - % - \ifnum\lccode\expandafter`\thearg=0\relax - \numericenumerate % a number (we hope) - \else - % It's a letter. - \ifnum\lccode\expandafter`\thearg=\expandafter`\thearg\relax - \lowercaseenumerate % lowercase letter - \else - \uppercaseenumerate % uppercase letter - \fi - \fi - \else - % Multiple tokens in the argument. We hope it's a number. - \numericenumerate - \fi -} - -% An @enumerate whose labels are integers. The starting integer is -% given in \thearg. -% -\def\numericenumerate{% - \itemno = \thearg - \startenumeration{\the\itemno}% -} - -% The starting (lowercase) letter is in \thearg. -\def\lowercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more lowercase letters in @enumerate; get a bigger - alphabet}% - \fi - \char\lccode\itemno - }% -} - -% The starting (uppercase) letter is in \thearg. -\def\uppercaseenumerate{% - \itemno = \expandafter`\thearg - \startenumeration{% - % Be sure we're not beyond the end of the alphabet. - \ifnum\itemno=0 - \errmessage{No more uppercase letters in @enumerate; get a bigger - alphabet} - \fi - \char\uccode\itemno - }% -} - -% Call \doitemize, adding a period to the first argument and supplying the -% common last two arguments. Also subtract one from the initial value in -% \itemno, since @item increments \itemno. -% -\def\startenumeration#1{% - \advance\itemno by -1 - \doitemize{#1.}\flushcr -} - -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - - -% @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab do not need to be on their own lines, but it will not hurt -% if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. -% -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt - -% Macros used to set up halign preamble: -% -\let\endsetuptable\relax -\def\xendsetuptable{\endsetuptable} -\let\columnfractions\relax -\def\xcolumnfractions{\columnfractions} -\newif\ifsetpercent - -% #1 is the @columnfraction, usually a decimal number like .5, but might -% be just 1. We just use it, whatever it is. -% -\def\pickupwholefraction#1 {% - \global\advance\colcount by 1 - \expandafter\xdef\csname col\the\colcount\endcsname{#1\hsize}% - \setuptable -} - -\newcount\colcount -\def\setuptable#1{% - \def\firstarg{#1}% - \ifx\firstarg\xendsetuptable - \let\go = \relax - \else - \ifx\firstarg\xcolumnfractions - \global\setpercenttrue - \else - \ifsetpercent - \let\go\pickupwholefraction - \else - \global\advance\colcount by 1 - \setbox0=\hbox{#1\unskip\space}% Add a normal word space as a - % separator; typically that is always in the input, anyway. - \expandafter\xdef\csname col\the\colcount\endcsname{\the\wd0}% - \fi - \fi - \ifx\go\pickupwholefraction - % Put the argument back for the \pickupwholefraction call, so - % we'll always have a period there to be parsed. - \def\go{\pickupwholefraction#1}% - \else - \let\go = \setuptable - \fi% - \fi - \go -} - -% multitable-only commands. -% -% @headitem starts a heading row, which we typeset in bold. -% Assignments have to be global since we are inside the implicit group -% of an alignment entry. Note that \everycr resets \everytab. -\def\headitem{\checkenv\multitable \crcr \global\everytab={\bf}\the\everytab}% -% -% A \tab used to include \hskip1sp. But then the space in a template -% line is not enough. That is bad. So let's go back to just `&' until -% we encounter the problem it was intended to solve again. -% --karl, nathan@acm.org, 20apr99. -\def\tab{\checkenv\multitable &\the\everytab}% - -% @multitable ... @end multitable definitions: -% -\newtoks\everytab % insert after every tab. -% -\envdef\multitable{% - \vskip\parskip - \startsavinginserts - % - % @item within a multitable starts a normal row. - % We use \def instead of \let so that if one of the multitable entries - % contains an @itemize, we don't choke on the \item (seen as \crcr aka - % \endtemplate) expanding \doitemize. - \def\item{\crcr}% - % - \tolerance=9500 - \hbadness=9500 - \setmultitablespacing - \parskip=\multitableparskip - \parindent=\multitableparindent - \overfullrule=0pt - \global\colcount=0 - % - \everycr = {% - \noalign{% - \global\everytab={}% - \global\colcount=0 % Reset the column counter. - % Check for saved footnotes, etc. - \checkinserts - % Keeps underfull box messages off when table breaks over pages. - %\filbreak - % Maybe so, but it also creates really weird page breaks when the - % table breaks over pages. Wouldn't \vfil be better? Wait until the - % problem manifests itself, so it can be fixed for real --karl. - }% - }% - % - \parsearg\domultitable -} -\def\domultitable#1{% - % To parse everything between @multitable and @item: - \setuptable#1 \endsetuptable - % - % This preamble sets up a generic column definition, which will - % be used as many times as user calls for columns. - % \vtop will set a single line and will also let text wrap and - % continue for many paragraphs if desired. - \halign\bgroup &% - \global\advance\colcount by 1 - \multistrut - \vtop{% - % Use the current \colcount to find the correct column width: - \hsize=\expandafter\csname col\the\colcount\endcsname - % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. - \rightskip=0pt - \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip - \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace - \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively - % marking characters. - \noindent\ignorespaces##\unskip\multistrut - }\cr -} -\def\Emultitable{% - \crcr - \egroup % end the \halign - \global\setpercentfalse -} - -\def\setmultitablespacing{% - \def\multistrut{\strut}% just use the standard line spacing - % - % Compute \multitablelinespace (if not defined by user) for use in - % \multitableparskip calculation. We used define \multistrut based on - % this, but (ironically) that caused the spacing to be off. - % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. -\ifdim\multitablelinespace=0pt -\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip -\global\advance\multitablelinespace by-\ht0 -\fi -%% Test to see if parskip is larger than space between lines of -%% table. If not, do nothing. -%% If so, set to same dimension as multitablelinespace. -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller - %% than skip between lines in the table. -\fi} - - -\message{conditionals,} - -% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, -% @ifnotxml always succeed. They currently do nothing; we don't -% attempt to check whether the conditionals are properly nested. But we -% have to remember that they are conditionals, so that @end doesn't -% attempt to close an environment group. -% -\def\makecond#1{% - \expandafter\let\csname #1\endcsname = \relax - \expandafter\let\csname iscond.#1\endcsname = 1 -} -\makecond{iftex} -\makecond{ifnotdocbook} -\makecond{ifnothtml} -\makecond{ifnotinfo} -\makecond{ifnotplaintext} -\makecond{ifnotxml} - -% Ignore @ignore, @ifhtml, @ifinfo, and the like. -% -\def\direntry{\doignore{direntry}} -\def\documentdescription{\doignore{documentdescription}} -\def\docbook{\doignore{docbook}} -\def\html{\doignore{html}} -\def\ifdocbook{\doignore{ifdocbook}} -\def\ifhtml{\doignore{ifhtml}} -\def\ifinfo{\doignore{ifinfo}} -\def\ifnottex{\doignore{ifnottex}} -\def\ifplaintext{\doignore{ifplaintext}} -\def\ifxml{\doignore{ifxml}} -\def\ignore{\doignore{ignore}} -\def\menu{\doignore{menu}} -\def\xml{\doignore{xml}} - -% Ignore text until a line `@end #1', keeping track of nested conditionals. -% -% A count to remember the depth of nesting. -\newcount\doignorecount - -\def\doignore#1{\begingroup - % Scan in ``verbatim'' mode: - \obeylines - \catcode`\@ = \other - \catcode`\{ = \other - \catcode`\} = \other - % - % Make sure that spaces turn into tokens that match what \doignoretext wants. - \spaceisspace - % - % Count number of #1's that we've seen. - \doignorecount = 0 - % - % Swallow text until we reach the matching `@end #1'. - \dodoignore{#1}% -} - -{ \catcode`_=11 % We want to use \_STOP_ which cannot appear in texinfo source. - \obeylines % - % - \gdef\dodoignore#1{% - % #1 contains the command name as a string, e.g., `ifinfo'. - % - % Define a command to find the next `@end #1'. - \long\def\doignoretext##1^^M@end #1{% - \doignoretextyyy##1^^M@#1\_STOP_}% - % - % And this command to find another #1 command, at the beginning of a - % line. (Otherwise, we would consider a line `@c @ifset', for - % example, to count as an @ifset for nesting.) - \long\def\doignoretextyyy##1^^M@#1##2\_STOP_{\doignoreyyy{##2}\_STOP_}% - % - % And now expand that command. - \doignoretext ^^M% - }% -} - -\def\doignoreyyy#1{% - \def\temp{#1}% - \ifx\temp\empty % Nothing found. - \let\next\doignoretextzzz - \else % Found a nested condition, ... - \advance\doignorecount by 1 - \let\next\doignoretextyyy % ..., look for another. - % If we're here, #1 ends with ^^M\ifinfo (for example). - \fi - \next #1% the token \_STOP_ is present just after this macro. -} - -% We have to swallow the remaining "\_STOP_". -% -\def\doignoretextzzz#1{% - \ifnum\doignorecount = 0 % We have just found the outermost @end. - \let\next\enddoignore - \else % Still inside a nested condition. - \advance\doignorecount by -1 - \let\next\doignoretext % Look for the next @end. - \fi - \next -} - -% Finish off ignored text. -{ \obeylines% - % Ignore anything after the last `@end #1'; this matters in verbatim - % environments, where otherwise the newline after an ignored conditional - % would result in a blank line in the output. - \gdef\enddoignore#1^^M{\endgroup\ignorespaces}% -} - - -% @set VAR sets the variable VAR to an empty value. -% @set VAR REST-OF-LINE sets VAR to the value REST-OF-LINE. -% -% Since we want to separate VAR from REST-OF-LINE (which might be -% empty), we can't just use \parsearg; we have to insert a space of our -% own to delimit the rest of the line, and then take it out again if we -% didn't need it. -% We rely on the fact that \parsearg sets \catcode`\ =10. -% -\parseargdef\set{\setyyy#1 \endsetyyy} -\def\setyyy#1 #2\endsetyyy{% - {% - \makevalueexpandable - \def\temp{#2}% - \edef\next{\gdef\makecsname{SET#1}}% - \ifx\temp\empty - \next{}% - \else - \setzzz#2\endsetzzz - \fi - }% -} -% Remove the trailing space \setxxx inserted. -\def\setzzz#1 \endsetzzz{\next{#1}} - -% @clear VAR clears (i.e., unsets) the variable VAR. -% -\parseargdef\clear{% - {% - \makevalueexpandable - \global\expandafter\let\csname SET#1\endcsname=\relax - }% -} - -% @value{foo} gets the text saved in variable foo. -\def\value{\begingroup\makevalueexpandable\valuexxx} -\def\valuexxx#1{\expandablevalue{#1}\endgroup} -{ - \catcode`\- = \active \catcode`\_ = \active - % - \gdef\makevalueexpandable{% - \let\value = \expandablevalue - % We don't want these characters active, ... - \catcode`\-=\other \catcode`\_=\other - % ..., but we might end up with active ones in the argument if - % we're called from @code, as @code{@value{foo-bar_}}, though. - % So \let them to their normal equivalents. - \let-\realdash \let_\normalunderscore - } -} - -% We have this subroutine so that we can handle at least some @value's -% properly in indexes (we call \makevalueexpandable in \indexdummies). -% The command has to be fully expandable (if the variable is set), since -% the result winds up in the index file. This means that if the -% variable's value contains other Texinfo commands, it's almost certain -% it will fail (although perhaps we could fix that with sufficient work -% to do a one-level expansion on the result, instead of complete). -% -\def\expandablevalue#1{% - \expandafter\ifx\csname SET#1\endcsname\relax - {[No value for ``#1'']}% - \message{Variable `#1', used in @value, is not set.}% - \else - \csname SET#1\endcsname - \fi -} - -% @ifset VAR ... @end ifset reads the `...' iff VAR has been defined -% with @set. -% -% To get special treatment of `@end ifset,' call \makeond and the redefine. -% -\makecond{ifset} -\def\ifset{\parsearg{\doifset{\let\next=\ifsetfail}}} -\def\doifset#1#2{% - {% - \makevalueexpandable - \let\next=\empty - \expandafter\ifx\csname SET#2\endcsname\relax - #1% If not set, redefine \next. - \fi - \expandafter - }\next -} -\def\ifsetfail{\doignore{ifset}} - -% @ifclear VAR ... @end ifclear reads the `...' iff VAR has never been -% defined with @set, or has been undefined with @clear. -% -% The `\else' inside the `\doifset' parameter is a trick to reuse the -% above code: if the variable is not set, do nothing, if it is set, -% then redefine \next to \ifclearfail. -% -\makecond{ifclear} -\def\ifclear{\parsearg{\doifset{\else \let\next=\ifclearfail}}} -\def\ifclearfail{\doignore{ifclear}} - -% @dircategory CATEGORY -- specify a category of the dir file -% which this file should belong to. Ignore this in TeX. -\let\dircategory=\comment - -% @defininfoenclose. -\let\definfoenclose=\comment - - -\message{indexing,} -% Index generation facilities - -% Define \newwrite to be identical to plain tex's \newwrite -% except not \outer, so it can be used within macros and \if's. -\edef\newwrite{\makecsname{ptexnewwrite}} - -% \newindex {foo} defines an index named foo. -% It automatically defines \fooindex such that -% \fooindex ...rest of line... puts an entry in the index foo. -% It also defines \fooindfile to be the number of the output channel for -% the file that accumulates this index. The file's extension is foo. -% The name of an index should be no more than 2 characters long -% for the sake of vms. -% -\def\newindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 % Open the file - \fi - \expandafter\xdef\csname#1index\endcsname{% % Define @#1index - \noexpand\doindex{#1}} -} - -% @defindex foo == \newindex{foo} -% -\def\defindex{\parsearg\newindex} - -% Define @defcodeindex, like @defindex except put all entries in @code. -% -\def\defcodeindex{\parsearg\newcodeindex} -% -\def\newcodeindex#1{% - \iflinks - \expandafter\newwrite \csname#1indfile\endcsname - \openout \csname#1indfile\endcsname \jobname.#1 - \fi - \expandafter\xdef\csname#1index\endcsname{% - \noexpand\docodeindex{#1}}% -} - - -% @synindex foo bar makes index foo feed into index bar. -% Do this instead of @defindex foo if you don't want it as a separate index. -% -% @syncodeindex foo bar similar, but put all entries made for index foo -% inside @code. -% -\def\synindex#1 #2 {\dosynindex\doindex{#1}{#2}} -\def\syncodeindex#1 #2 {\dosynindex\docodeindex{#1}{#2}} - -% #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), -% #3 the target index (bar). -\def\dosynindex#1#2#3{% - % Only do \closeout if we haven't already done it, else we'll end up - % closing the target index. - \expandafter \ifx\csname donesynindex#2\endcsname \undefined - % The \closeout helps reduce unnecessary open files; the limit on the - % Acorn RISC OS is a mere 16 files. - \expandafter\closeout\csname#2indfile\endcsname - \expandafter\let\csname\donesynindex#2\endcsname = 1 - \fi - % redefine \fooindfile: - \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname - \expandafter\let\csname#2indfile\endcsname=\temp - % redefine \fooindex: - \expandafter\xdef\csname#2index\endcsname{\noexpand#1{#3}}% -} - -% Define \doindex, the driver for all \fooindex macros. -% Argument #1 is generated by the calling \fooindex macro, -% and it is "foo", the name of the index. - -% \doindex just uses \parsearg; it calls \doind for the actual work. -% This is because \doind is more useful to call from other macros. - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. - -\def\doindex#1{\edef\indexname{#1}\parsearg\singleindexer} -\def\singleindexer #1{\doind{\indexname}{#1}} - -% like the previous two, but they put @code around the argument. -\def\docodeindex#1{\edef\indexname{#1}\parsearg\singlecodeindexer} -\def\singlecodeindexer #1{\doind{\indexname}{\code{#1}}} - -% Take care of Texinfo commands that can appear in an index entry. -% Since there are some commands we want to expand, and others we don't, -% we have to laboriously prevent expansion for those that we don't. -% -\def\indexdummies{% - \escapechar = `\\ % use backslash in output files. - \def\@{@}% change to @@ when we switch to @ as escape char in index files. - \def\ {\realbackslash\space }% - % - % Need these in case \tex is in effect and \{ is a \delimiter again. - % But can't use \lbracecmd and \rbracecmd because texindex assumes - % braces and backslashes are used only as delimiters. - \let\{ = \mylbrace - \let\} = \myrbrace - % - % I don't entirely understand this, but when an index entry is - % generated from a macro call, the \endinput which \scanmacro inserts - % causes processing to be prematurely terminated. This is, - % apparently, because \indexsorttmp is fully expanded, and \endinput - % is an expandable command. The redefinition below makes \endinput - % disappear altogether for that purpose -- although logging shows that - % processing continues to some further point. On the other hand, it - % seems \endinput does not hurt in the printed index arg, since that - % is still getting written without apparent harm. - % - % Sample source (mac-idx3.tex, reported by Graham Percival to - % help-texinfo, 22may06): - % @macro funindex {WORD} - % @findex xyz - % @end macro - % ... - % @funindex commtest - % - % The above is not enough to reproduce the bug, but it gives the flavor. - % - % Sample whatsit resulting: - % .@write3{\entry{xyz}{@folio }{@code {xyz@endinput }}} - % - % So: - \let\endinput = \empty - % - % Do the redefinitions. - \commondummies -} - -% For the aux and toc files, @ is the escape character. So we want to -% redefine everything using @ as the escape character (instead of -% \realbackslash, still used for index files). When everything uses @, -% this will be simpler. -% -\def\atdummies{% - \def\@{@@}% - \def\ {@ }% - \let\{ = \lbraceatcmd - \let\} = \rbraceatcmd - % - % Do the redefinitions. - \commondummies - \otherbackslash -} - -% Called from \indexdummies and \atdummies. -% -\def\commondummies{% - % - % \definedummyword defines \#1 as \string\#1\space, thus effectively - % preventing its expansion. This is used only for control% words, - % not control letters, because the \space would be incorrect for - % control characters, but is needed to separate the control word - % from whatever follows. - % - % For control letters, we have \definedummyletter, which omits the - % space. - % - % These can be used both for control words that take an argument and - % those that do not. If it is followed by {arg} in the input, then - % that will dutifully get written to the index (or wherever). - % - \def\definedummyword ##1{\def##1{\string##1\space}}% - \def\definedummyletter##1{\def##1{\string##1}}% - \let\definedummyaccent\definedummyletter - % - \commondummiesnofonts - % - \definedummyletter\_% - % - % Non-English letters. - \definedummyword\AA - \definedummyword\AE - \definedummyword\L - \definedummyword\OE - \definedummyword\O - \definedummyword\aa - \definedummyword\ae - \definedummyword\l - \definedummyword\oe - \definedummyword\o - \definedummyword\ss - \definedummyword\exclamdown - \definedummyword\questiondown - \definedummyword\ordf - \definedummyword\ordm - % - % Although these internal commands shouldn't show up, sometimes they do. - \definedummyword\bf - \definedummyword\gtr - \definedummyword\hat - \definedummyword\less - \definedummyword\sf - \definedummyword\sl - \definedummyword\tclose - \definedummyword\tt - % - \definedummyword\LaTeX - \definedummyword\TeX - % - % Assorted special characters. - \definedummyword\bullet - \definedummyword\comma - \definedummyword\copyright - \definedummyword\registeredsymbol - \definedummyword\dots - \definedummyword\enddots - \definedummyword\equiv - \definedummyword\error - \definedummyword\euro - \definedummyword\expansion - \definedummyword\minus - \definedummyword\pounds - \definedummyword\point - \definedummyword\print - \definedummyword\result - \definedummyword\textdegree - % - % We want to disable all macros so that they are not expanded by \write. - \macrolist - % - \normalturnoffactive - % - % Handle some cases of @value -- where it does not contain any - % (non-fully-expandable) commands. - \makevalueexpandable -} - -% \commondummiesnofonts: common to \commondummies and \indexnofonts. -% -\def\commondummiesnofonts{% - % Control letters and accents. - \definedummyletter\!% - \definedummyaccent\"% - \definedummyaccent\'% - \definedummyletter\*% - \definedummyaccent\,% - \definedummyletter\.% - \definedummyletter\/% - \definedummyletter\:% - \definedummyaccent\=% - \definedummyletter\?% - \definedummyaccent\^% - \definedummyaccent\`% - \definedummyaccent\~% - \definedummyword\u - \definedummyword\v - \definedummyword\H - \definedummyword\dotaccent - \definedummyword\ringaccent - \definedummyword\tieaccent - \definedummyword\ubaraccent - \definedummyword\udotaccent - \definedummyword\dotless - % - % Texinfo font commands. - \definedummyword\b - \definedummyword\i - \definedummyword\r - \definedummyword\sc - \definedummyword\t - % - % Commands that take arguments. - \definedummyword\acronym - \definedummyword\cite - \definedummyword\code - \definedummyword\command - \definedummyword\dfn - \definedummyword\emph - \definedummyword\env - \definedummyword\file - \definedummyword\kbd - \definedummyword\key - \definedummyword\math - \definedummyword\option - \definedummyword\pxref - \definedummyword\ref - \definedummyword\samp - \definedummyword\strong - \definedummyword\tie - \definedummyword\uref - \definedummyword\url - \definedummyword\var - \definedummyword\verb - \definedummyword\w - \definedummyword\xref -} - -% \indexnofonts is used when outputting the strings to sort the index -% by, and when constructing control sequence names. It eliminates all -% control sequences and just writes whatever the best ASCII sort string -% would be for a given command (usually its argument). -% -\def\indexnofonts{% - % Accent commands should become @asis. - \def\definedummyaccent##1{\let##1\asis}% - % We can just ignore other control letters. - \def\definedummyletter##1{\let##1\empty}% - % Hopefully, all control words can become @asis. - \let\definedummyword\definedummyaccent - % - \commondummiesnofonts - % - % Don't no-op \tt, since it isn't a user-level command - % and is used in the definitions of the active chars like <, >, |, etc. - % Likewise with the other plain tex font commands. - %\let\tt=\asis - % - \def\ { }% - \def\@{@}% - % how to handle braces? - \def\_{\normalunderscore}% - % - % Non-English letters. - \def\AA{AA}% - \def\AE{AE}% - \def\L{L}% - \def\OE{OE}% - \def\O{O}% - \def\aa{aa}% - \def\ae{ae}% - \def\l{l}% - \def\oe{oe}% - \def\o{o}% - \def\ss{ss}% - \def\exclamdown{!}% - \def\questiondown{?}% - \def\ordf{a}% - \def\ordm{o}% - % - \def\LaTeX{LaTeX}% - \def\TeX{TeX}% - % - % Assorted special characters. - % (The following {} will end up in the sort string, but that's ok.) - \def\bullet{bullet}% - \def\comma{,}% - \def\copyright{copyright}% - \def\registeredsymbol{R}% - \def\dots{...}% - \def\enddots{...}% - \def\equiv{==}% - \def\error{error}% - \def\euro{euro}% - \def\expansion{==>}% - \def\minus{-}% - \def\pounds{pounds}% - \def\point{.}% - \def\print{-|}% - \def\result{=>}% - \def\textdegree{degrees}% - % - % We need to get rid of all macros, leaving only the arguments (if present). - % Of course this is not nearly correct, but it is the best we can do for now. - % makeinfo does not expand macros in the argument to @deffn, which ends up - % writing an index entry, and texindex isn't prepared for an index sort entry - % that starts with \. - % - % Since macro invocations are followed by braces, we can just redefine them - % to take a single TeX argument. The case of a macro invocation that - % goes to end-of-line is not handled. - % - \macrolist -} - -\let\indexbackslash=0 %overridden during \printindex. -\let\SETmarginindex=\relax % put index entries in margin (undocumented)? - -% Most index entries go through here, but \dosubind is the general case. -% #1 is the index name, #2 is the entry text. -\def\doind#1#2{\dosubind{#1}{#2}{}} - -% Workhorse for all \fooindexes. -% #1 is name of index, #2 is stuff to put there, #3 is subentry -- -% empty if called from \doind, as we usually are (the main exception -% is with most defuns, which call us directly). -% -\def\dosubind#1#2#3{% - \iflinks - {% - % Store the main index entry text (including the third arg). - \toks0 = {#2}% - % If third arg is present, precede it with a space. - \def\thirdarg{#3}% - \ifx\thirdarg\empty \else - \toks0 = \expandafter{\the\toks0 \space #3}% - \fi - % - \edef\writeto{\csname#1indfile\endcsname}% - % - \safewhatsit\dosubindwrite - }% - \fi -} - -% Write the entry in \toks0 to the index file: -% -\def\dosubindwrite{% - % Put the index entry in the margin if desired. - \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% - \fi - % - % Remember, we are within a group. - \indexdummies % Must do this here, since \bf, etc expand at this stage - \def\backslashcurfont{\indexbackslash}% \indexbackslash isn't defined now - % so it will be output as is; and it will print as backslash. - % - % Process the index entry with all font commands turned off, to - % get the string to sort by. - {\indexnofonts - \edef\temp{\the\toks0}% need full expansion - \xdef\indexsorttmp{\temp}% - }% - % - % Set up the complete index entry, with both the sort key and - % the original text, including any font commands. We write - % three arguments to \entry to the .?? file (four in the - % subentry case), texindex reduces to two when writing the .??s - % sorted result. - \edef\temp{% - \write\writeto{% - \string\entry{\indexsorttmp}{\noexpand\folio}{\the\toks0}}% - }% - \temp -} - -% Take care of unwanted page breaks/skips around a whatsit: -% -% If a skip is the last thing on the list now, preserve it -% by backing up by \lastskip, doing the \write, then inserting -% the skip again. Otherwise, the whatsit generated by the -% \write or \pdfdest will make \lastskip zero. The result is that -% sequences like this: -% @end defun -% @tindex whatever -% @defun ... -% will have extra space inserted, because the \medbreak in the -% start of the @defun won't see the skip inserted by the @end of -% the previous defun. -% -% But don't do any of this if we're not in vertical mode. We -% don't want to do a \vskip and prematurely end a paragraph. -% -% Avoid page breaks due to these extra skips, too. -% -% But wait, there is a catch there: -% We'll have to check whether \lastskip is zero skip. \ifdim is not -% sufficient for this purpose, as it ignores stretch and shrink parts -% of the skip. The only way seems to be to check the textual -% representation of the skip. -% -% The following is almost like \def\zeroskipmacro{0.0pt} except that -% the ``p'' and ``t'' characters have catcode \other, not 11 (letter). -% -\edef\zeroskipmacro{\expandafter\the\csname z@skip\endcsname} -% -\newskip\whatsitskip -\newcount\whatsitpenalty -% -% ..., ready, GO: -% -\def\safewhatsit#1{% -\ifhmode - #1% -\else - % \lastskip and \lastpenalty cannot both be nonzero simultaneously. - \whatsitskip = \lastskip - \edef\lastskipmacro{\the\lastskip}% - \whatsitpenalty = \lastpenalty - % - % If \lastskip is nonzero, that means the last item was a - % skip. And since a skip is discardable, that means this - % -\skip0 glue we're inserting is preceded by a - % non-discardable item, therefore it is not a potential - % breakpoint, therefore no \nobreak needed. - \ifx\lastskipmacro\zeroskipmacro - \else - \vskip-\whatsitskip - \fi - % - #1% - % - \ifx\lastskipmacro\zeroskipmacro - % If \lastskip was zero, perhaps the last item was a penalty, and - % perhaps it was >=10000, e.g., a \nobreak. In that case, we want - % to re-insert the same penalty (values >10000 are used for various - % signals); since we just inserted a non-discardable item, any - % following glue (such as a \parskip) would be a breakpoint. For example: - % - % @deffn deffn-whatever - % @vindex index-whatever - % Description. - % would allow a break between the index-whatever whatsit - % and the "Description." paragraph. - \ifnum\whatsitpenalty>9999 \penalty\whatsitpenalty \fi - \else - % On the other hand, if we had a nonzero \lastskip, - % this make-up glue would be preceded by a non-discardable item - % (the whatsit from the \write), so we must insert a \nobreak. - \nobreak\vskip\whatsitskip - \fi -\fi -} - -% The index entry written in the file actually looks like -% \entry {sortstring}{page}{topic} -% or -% \entry {sortstring}{page}{topic}{subtopic} -% The texindex program reads in these files and writes files -% containing these kinds of lines: -% \initial {c} -% before the first topic whose initial is c -% \entry {topic}{pagelist} -% for a topic that is used without subtopics -% \primary {topic} -% for the beginning of a topic that is used with subtopics -% \secondary {subtopic}{pagelist} -% for each subtopic. - -% Define the user-accessible indexing commands -% @findex, @vindex, @kindex, @cindex. - -\def\findex {\fnindex} -\def\kindex {\kyindex} -\def\cindex {\cpindex} -\def\vindex {\vrindex} -\def\tindex {\tpindex} -\def\pindex {\pgindex} - -\def\cindexsub {\begingroup\obeylines\cindexsub} -{\obeylines % -\gdef\cindexsub "#1" #2^^M{\endgroup % -\dosubind{cp}{#2}{#1}}} - -% Define the macros used in formatting output of the sorted index material. - -% @printindex causes a particular index (the ??s file) to get printed. -% It does not print any chapter heading (usually an @unnumbered). -% -\parseargdef\printindex{\begingroup - \dobreak \chapheadingskip{10000}% - % - \smallfonts \rm - \tolerance = 9500 - \plainfrenchspacing - \everypar = {}% don't want the \kern\-parindent from indentation suppression. - % - % See if the index file exists and is nonempty. - % Change catcode of @ here so that if the index file contains - % \initial {@} - % as its first line, TeX doesn't complain about mismatched braces - % (because it thinks @} is a control sequence). - \catcode`\@ = 11 - \openin 1 \jobname.#1s - \ifeof 1 - % \enddoublecolumns gets confused if there is no text in the index, - % and it loses the chapter title and the aux file entries for the - % index. The easiest way to prevent this problem is to make sure - % there is some text. - \putwordIndexNonexistent - \else - % - % If the index file exists but is empty, then \openin leaves \ifeof - % false. We have to make TeX try to read something from the file, so - % it can discover if there is anything in it. - \read 1 to \temp - \ifeof 1 - \putwordIndexIsEmpty - \else - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \def\indexbackslash{\backslashcurfont}% - \catcode`\\ = 0 - \escapechar = `\\ - \begindoublecolumns - \input \jobname.#1s - \enddoublecolumns - \fi - \fi - \closein 1 -\endgroup} - -% These macros are used by the sorted index file itself. -% Change them to control the appearance of the index. - -\def\initial#1{{% - % Some minor font changes for the special characters. - \let\tentt=\sectt \let\tt=\sectt \let\sf=\sectt - % - % Remove any glue we may have, we'll be inserting our own. - \removelastskip - % - % We like breaks before the index initials, so insert a bonus. - \nobreak - \vskip 0pt plus 3\baselineskip - \penalty 0 - \vskip 0pt plus -3\baselineskip - % - % Typeset the initial. Making this add up to a whole number of - % baselineskips increases the chance of the dots lining up from column - % to column. It still won't often be perfect, because of the stretch - % we need before each entry, but it's better. - % - % No shrink because it confuses \balancecolumns. - \vskip 1.67\baselineskip plus .5\baselineskip - \leftline{\secbf #1}% - % Do our best not to break after the initial. - \nobreak - \vskip .33\baselineskip plus .1\baselineskip -}} - -% \entry typesets a paragraph consisting of the text (#1), dot leaders, and -% then page number (#2) flushed to the right margin. It is used for index -% and table of contents entries. The paragraph is indented by \leftskip. -% -% A straightforward implementation would start like this: -% \def\entry#1#2{... -% But this frozes the catcodes in the argument, and can cause problems to -% @code, which sets - active. This problem was fixed by a kludge--- -% ``-'' was active throughout whole index, but this isn't really right. -% -% The right solution is to prevent \entry from swallowing the whole text. -% --kasal, 21nov03 -\def\entry{% - \begingroup - % - % Start a new paragraph if necessary, so our assignments below can't - % affect previous text. - \par - % - % Do not fill out the last line with white space. - \parfillskip = 0in - % - % No extra space above this paragraph. - \parskip = 0in - % - % Do not prefer a separate line ending with a hyphen to fewer lines. - \finalhyphendemerits = 0 - % - % \hangindent is only relevant when the entry text and page number - % don't both fit on one line. In that case, bob suggests starting the - % dots pretty far over on the line. Unfortunately, a large - % indentation looks wrong when the entry text itself is broken across - % lines. So we use a small indentation and put up with long leaders. - % - % \hangafter is reset to 1 (which is the value we want) at the start - % of each paragraph, so we need not do anything with that. - \hangindent = 2em - % - % When the entry text needs to be broken, just fill out the first line - % with blank space. - \rightskip = 0pt plus1fil - % - % A bit of stretch before each entry for the benefit of balancing - % columns. - \vskip 0pt plus1pt - % - % Swallow the left brace of the text (first parameter): - \afterassignment\doentry - \let\temp = -} -\def\doentry{% - \bgroup % Instead of the swallowed brace. - \noindent - \aftergroup\finishentry - % And now comes the text of the entry. -} -\def\finishentry#1{% - % #1 is the page number. - % - % The following is kludged to not output a line of dots in the index if - % there are no page numbers. The next person who breaks this will be - % cursed by a Unix daemon. - \setbox\boxA = \hbox{#1}% - \ifdim\wd\boxA = 0pt - \ % - \else - % - % If we must, put the page number on a line of its own, and fill out - % this line with blank space. (The \hfil is overwhelmed with the - % fill leaders glue in \indexdotfill if the page number does fit.) - \hfil\penalty50 - \null\nobreak\indexdotfill % Have leaders before the page number. - % - % The `\ ' here is removed by the implicit \unskip that TeX does as - % part of (the primitive) \par. Without it, a spurious underfull - % \hbox ensues. - \ifpdf - \pdfgettoks#1.% - \ \the\toksA - \else - \ #1% - \fi - \fi - \par - \endgroup -} - -% Like plain.tex's \dotfill, except uses up at least 1 em. -\def\indexdotfill{\cleaders - \hbox{$\mathsurround=0pt \mkern1.5mu.\mkern1.5mu$}\hskip 1em plus 1fill} - -\def\primary #1{\line{#1\hfil}} - -\newskip\secondaryindent \secondaryindent=0.5cm -\def\secondary#1#2{{% - \parfillskip=0in - \parskip=0in - \hangindent=1in - \hangafter=1 - \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill - \ifpdf - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. - \else - #2 - \fi - \par -}} - -% Define two-column mode, which we use to typeset indexes. -% Adapted from the TeXbook, page 416, which is to say, -% the manmac.tex format used to print the TeXbook itself. -\catcode`\@=11 - -\newbox\partialpage -\newdimen\doublecolumnhsize - -\def\begindoublecolumns{\begingroup % ended by \enddoublecolumns - % Grab any single-column material above us. - \output = {% - % - % Here is a possibility not foreseen in manmac: if we accumulate a - % whole lot of material, we might end up calling this \output - % routine twice in a row (see the doublecol-lose test, which is - % essentially a couple of indexes with @setchapternewpage off). In - % that case we just ship out what is in \partialpage with the normal - % output routine. Generally, \partialpage will be empty when this - % runs and this will be a no-op. See the indexspread.tex test case. - \ifvoid\partialpage \else - \onepageout{\pagecontents\partialpage}% - \fi - % - \global\setbox\partialpage = \vbox{% - % Unvbox the main output page. - \unvbox\PAGE - \kern-\topskip \kern\baselineskip - }% - }% - \eject % run that output routine to set \partialpage - % - % Use the double-column output routine for subsequent pages. - \output = {\doublecolumnout}% - % - % Change the page size parameters. We could do this once outside this - % routine, in each of @smallbook, @afourpaper, and the default 8.5x11 - % format, but then we repeat the same computation. Repeating a couple - % of assignments once per index is clearly meaningless for the - % execution time, so we may as well do it in one place. - % - % First we halve the line length, less a little for the gutter between - % the columns. We compute the gutter based on the line length, so it - % changes automatically with the paper format. The magic constant - % below is chosen so that the gutter has the same value (well, +-<1pt) - % as it did when we hard-coded it. - % - % We put the result in a separate register, \doublecolumhsize, so we - % can restore it in \pagesofar, after \hsize itself has (potentially) - % been clobbered. - % - \doublecolumnhsize = \hsize - \advance\doublecolumnhsize by -.04154\hsize - \divide\doublecolumnhsize by 2 - \hsize = \doublecolumnhsize - % - % Double the \vsize as well. (We don't need a separate register here, - % since nobody clobbers \vsize.) - \vsize = 2\vsize -} - -% The double-column output routine for all double-column pages except -% the last. -% -\def\doublecolumnout{% - \splittopskip=\topskip \splitmaxdepth=\maxdepth - % Get the available space for the double columns -- the normal - % (undoubled) page height minus any material left over from the - % previous page. - \dimen@ = \vsize - \divide\dimen@ by 2 - \advance\dimen@ by -\ht\partialpage - % - % box0 will be the left-hand column, box2 the right. - \setbox0=\vsplit255 to\dimen@ \setbox2=\vsplit255 to\dimen@ - \onepageout\pagesofar - \unvbox255 - \penalty\outputpenalty -} -% -% Re-output the contents of the output page -- any previous material, -% followed by the two boxes we just split, in box0 and box2. -\def\pagesofar{% - \unvbox\partialpage - % - \hsize = \doublecolumnhsize - \wd0=\hsize \wd2=\hsize - \hbox to\pagewidth{\box0\hfil\box2}% -} -% -% All done with double columns. -\def\enddoublecolumns{% - % The following penalty ensures that the page builder is exercised - % _before_ we change the output routine. This is necessary in the - % following situation: - % - % The last section of the index consists only of a single entry. - % Before this section, \pagetotal is less than \pagegoal, so no - % break occurs before the last section starts. However, the last - % section, consisting of \initial and the single \entry, does not - % fit on the page and has to be broken off. Without the following - % penalty the page builder will not be exercised until \eject - % below, and by that time we'll already have changed the output - % routine to the \balancecolumns version, so the next-to-last - % double-column page will be processed with \balancecolumns, which - % is wrong: The two columns will go to the main vertical list, with - % the broken-off section in the recent contributions. As soon as - % the output routine finishes, TeX starts reconsidering the page - % break. The two columns and the broken-off section both fit on the - % page, because the two columns now take up only half of the page - % goal. When TeX sees \eject from below which follows the final - % section, it invokes the new output routine that we've set after - % \balancecolumns below; \onepageout will try to fit the two columns - % and the final section into the vbox of \pageheight (see - % \pagebody), causing an overfull box. - % - % Note that glue won't work here, because glue does not exercise the - % page builder, unlike penalties (see The TeXbook, pp. 280-281). - \penalty0 - % - \output = {% - % Split the last of the double-column material. Leave it on the - % current page, no automatic page break. - \balancecolumns - % - % If we end up splitting too much material for the current page, - % though, there will be another page break right after this \output - % invocation ends. Having called \balancecolumns once, we do not - % want to call it again. Therefore, reset \output to its normal - % definition right away. (We hope \balancecolumns will never be - % called on to balance too much material, but if it is, this makes - % the output somewhat more palatable.) - \global\output = {\onepageout{\pagecontents\PAGE}}% - }% - \eject - \endgroup % started in \begindoublecolumns - % - % \pagegoal was set to the doubled \vsize above, since we restarted - % the current page. We're now back to normal single-column - % typesetting, so reset \pagegoal to the normal \vsize (after the - % \endgroup where \vsize got restored). - \pagegoal = \vsize -} -% -% Called at the end of the double column material. -\def\balancecolumns{% - \setbox0 = \vbox{\unvbox255}% like \box255 but more efficient, see p.120. - \dimen@ = \ht0 - \advance\dimen@ by \topskip - \advance\dimen@ by-\baselineskip - \divide\dimen@ by 2 % target to split to - %debug\message{final 2-column material height=\the\ht0, target=\the\dimen@.}% - \splittopskip = \topskip - % Loop until we get a decent breakpoint. - {% - \vbadness = 10000 - \loop - \global\setbox3 = \copy0 - \global\setbox1 = \vsplit3 to \dimen@ - \ifdim\ht3>\dimen@ - \global\advance\dimen@ by 1pt - \repeat - }% - %debug\message{split to \the\dimen@, column heights: \the\ht1, \the\ht3.}% - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% - % - \pagesofar -} -\catcode`\@ = \other - - -\message{sectioning,} -% Chapters, sections, etc. - -% \unnumberedno is an oxymoron, of course. But we count the unnumbered -% sections so that we can refer to them unambiguously in the pdf -% outlines by their "section number". We avoid collisions with chapter -% numbers by starting them at 10000. (If a document ever has 10000 -% chapters, we're in trouble anyway, I'm sure.) -\newcount\unnumberedno \unnumberedno = 10000 -\newcount\chapno -\newcount\secno \secno=0 -\newcount\subsecno \subsecno=0 -\newcount\subsubsecno \subsubsecno=0 - -% This counter is funny since it counts through charcodes of letters A, B, ... -\newcount\appendixno \appendixno = `\@ -% -% \def\appendixletter{\char\the\appendixno} -% We do the following ugly conditional instead of the above simple -% construct for the sake of pdftex, which needs the actual -% letter in the expansion, not just typeset. -% -\def\appendixletter{% - \ifnum\appendixno=`A A% - \else\ifnum\appendixno=`B B% - \else\ifnum\appendixno=`C C% - \else\ifnum\appendixno=`D D% - \else\ifnum\appendixno=`E E% - \else\ifnum\appendixno=`F F% - \else\ifnum\appendixno=`G G% - \else\ifnum\appendixno=`H H% - \else\ifnum\appendixno=`I I% - \else\ifnum\appendixno=`J J% - \else\ifnum\appendixno=`K K% - \else\ifnum\appendixno=`L L% - \else\ifnum\appendixno=`M M% - \else\ifnum\appendixno=`N N% - \else\ifnum\appendixno=`O O% - \else\ifnum\appendixno=`P P% - \else\ifnum\appendixno=`Q Q% - \else\ifnum\appendixno=`R R% - \else\ifnum\appendixno=`S S% - \else\ifnum\appendixno=`T T% - \else\ifnum\appendixno=`U U% - \else\ifnum\appendixno=`V V% - \else\ifnum\appendixno=`W W% - \else\ifnum\appendixno=`X X% - \else\ifnum\appendixno=`Y Y% - \else\ifnum\appendixno=`Z Z% - % The \the is necessary, despite appearances, because \appendixletter is - % expanded while writing the .toc file. \char\appendixno is not - % expandable, thus it is written literally, thus all appendixes come out - % with the same letter (or @) in the toc without it. - \else\char\the\appendixno - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi - \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi} - -% Each @chapter defines this as the name of the chapter. -% page headings and footings can use it. @section does likewise. -% However, they are not reliable, because we don't use marks. -\def\thischapter{} -\def\thissection{} - -\newcount\absseclevel % used to calculate proper heading level -\newcount\secbase\secbase=0 % @raisesections/@lowersections modify this count - -% @raisesections: treat @section as chapter, @subsection as section, etc. -\def\raisesections{\global\advance\secbase by -1} -\let\up=\raisesections % original BFox name - -% @lowersections: treat @chapter as section, @section as subsection, etc. -\def\lowersections{\global\advance\secbase by 1} -\let\down=\lowersections % original BFox name - -% we only have subsub. -\chardef\maxseclevel = 3 -% -% A numbered section within an unnumbered changes to unnumbered too. -% To achive this, remember the "biggest" unnum. sec. we are currently in: -\chardef\unmlevel = \maxseclevel -% -% Trace whether the current chapter is an appendix or not: -% \chapheadtype is "N" or "A", unnumbered chapters are ignored. -\def\chapheadtype{N} - -% Choose a heading macro -% #1 is heading type -% #2 is heading level -% #3 is text for heading -\def\genhead#1#2#3{% - % Compute the abs. sec. level: - \absseclevel=#2 - \advance\absseclevel by \secbase - % Make sure \absseclevel doesn't fall outside the range: - \ifnum \absseclevel < 0 - \absseclevel = 0 - \else - \ifnum \absseclevel > 3 - \absseclevel = 3 - \fi - \fi - % The heading type: - \def\headtype{#1}% - \if \headtype U% - \ifnum \absseclevel < \unmlevel - \chardef\unmlevel = \absseclevel - \fi - \else - % Check for appendix sections: - \ifnum \absseclevel = 0 - \edef\chapheadtype{\headtype}% - \else - \if \headtype A\if \chapheadtype N% - \errmessage{@appendix... within a non-appendix chapter}% - \fi\fi - \fi - % Check for numbered within unnumbered: - \ifnum \absseclevel > \unmlevel - \def\headtype{U}% - \else - \chardef\unmlevel = 3 - \fi - \fi - % Now print the heading: - \if \headtype U% - \ifcase\absseclevel - \unnumberedzzz{#3}% - \or \unnumberedseczzz{#3}% - \or \unnumberedsubseczzz{#3}% - \or \unnumberedsubsubseczzz{#3}% - \fi - \else - \if \headtype A% - \ifcase\absseclevel - \appendixzzz{#3}% - \or \appendixsectionzzz{#3}% - \or \appendixsubseczzz{#3}% - \or \appendixsubsubseczzz{#3}% - \fi - \else - \ifcase\absseclevel - \chapterzzz{#3}% - \or \seczzz{#3}% - \or \numberedsubseczzz{#3}% - \or \numberedsubsubseczzz{#3}% - \fi - \fi - \fi - \suppressfirstparagraphindent -} - -% an interface: -\def\numhead{\genhead N} -\def\apphead{\genhead A} -\def\unnmhead{\genhead U} - -% @chapter, @appendix, @unnumbered. Increment top-level counter, reset -% all lower-level sectioning counters to zero. -% -% Also set \chaplevelprefix, which we prepend to @float sequence numbers -% (e.g., figures), q.v. By default (before any chapter), that is empty. -\let\chaplevelprefix = \empty -% -\outer\parseargdef\chapter{\numhead0{#1}} % normally numhead0 calls chapterzzz -\def\chapterzzz#1{% - % section resetting is \global in case the chapter is in a group, such - % as an @include file. - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\chapno by 1 - % - % Used for \float. - \gdef\chaplevelprefix{\the\chapno.}% - \resetallfloatnos - % - \message{\putwordChapter\space \the\chapno}% - % - % Write the actual heading. - \chapmacro{#1}{Ynumbered}{\the\chapno}% - % - % So @section and the like are numbered underneath this chapter. - \global\let\section = \numberedsec - \global\let\subsection = \numberedsubsec - \global\let\subsubsection = \numberedsubsubsec -} - -\outer\parseargdef\appendix{\apphead0{#1}} % normally apphead0 calls appendixzzz -\def\appendixzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\appendixno by 1 - \gdef\chaplevelprefix{\appendixletter.}% - \resetallfloatnos - % - \def\appendixnum{\putwordAppendix\space \appendixletter}% - \message{\appendixnum}% - % - \chapmacro{#1}{Yappendix}{\appendixletter}% - % - \global\let\section = \appendixsec - \global\let\subsection = \appendixsubsec - \global\let\subsubsection = \appendixsubsubsec -} - -\outer\parseargdef\unnumbered{\unnmhead0{#1}} % normally unnmhead0 calls unnumberedzzz -\def\unnumberedzzz#1{% - \global\secno=0 \global\subsecno=0 \global\subsubsecno=0 - \global\advance\unnumberedno by 1 - % - % Since an unnumbered has no number, no prefix for figures. - \global\let\chaplevelprefix = \empty - \resetallfloatnos - % - % This used to be simply \message{#1}, but TeX fully expands the - % argument to \message. Therefore, if #1 contained @-commands, TeX - % expanded them. For example, in `@unnumbered The @cite{Book}', TeX - % expanded @cite (which turns out to cause errors because \cite is meant - % to be executed, not expanded). - % - % Anyway, we don't want the fully-expanded definition of @cite to appear - % as a result of the \message, we just want `@cite' itself. We use - % \the to achieve this: TeX expands \the only once, - % simply yielding the contents of . (We also do this for - % the toc entries.) - \toks0 = {#1}% - \message{(\the\toks0)}% - % - \chapmacro{#1}{Ynothing}{\the\unnumberedno}% - % - \global\let\section = \unnumberedsec - \global\let\subsection = \unnumberedsubsec - \global\let\subsubsection = \unnumberedsubsubsec -} - -% @centerchap is like @unnumbered, but the heading is centered. -\outer\parseargdef\centerchap{% - % Well, we could do the following in a group, but that would break - % an assumption that \chapmacro is called at the outermost level. - % Thus we are safer this way: --kasal, 24feb04 - \let\centerparametersmaybe = \centerparameters - \unnmhead0{#1}% - \let\centerparametersmaybe = \relax -} - -% @top is like @unnumbered. -\let\top\unnumbered - -% Sections. -\outer\parseargdef\numberedsec{\numhead1{#1}} % normally calls seczzz -\def\seczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}% -} - -\outer\parseargdef\appendixsection{\apphead1{#1}} % normally calls appendixsectionzzz -\def\appendixsectionzzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}% -} -\let\appendixsec\appendixsection - -\outer\parseargdef\unnumberedsec{\unnmhead1{#1}} % normally calls unnumberedseczzz -\def\unnumberedseczzz#1{% - \global\subsecno=0 \global\subsubsecno=0 \global\advance\secno by 1 - \sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}% -} - -% Subsections. -\outer\parseargdef\numberedsubsec{\numhead2{#1}} % normally calls numberedsubseczzz -\def\numberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\appendixsubsec{\apphead2{#1}} % normally calls appendixsubseczzz -\def\appendixsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno}% -} - -\outer\parseargdef\unnumberedsubsec{\unnmhead2{#1}} %normally calls unnumberedsubseczzz -\def\unnumberedsubseczzz#1{% - \global\subsubsecno=0 \global\advance\subsecno by 1 - \sectionheading{#1}{subsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno}% -} - -% Subsubsections. -\outer\parseargdef\numberedsubsubsec{\numhead3{#1}} % normally numberedsubsubseczzz -\def\numberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynumbered}% - {\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\appendixsubsubsec{\apphead3{#1}} % normally appendixsubsubseczzz -\def\appendixsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Yappendix}% - {\appendixletter.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -\outer\parseargdef\unnumberedsubsubsec{\unnmhead3{#1}} %normally unnumberedsubsubseczzz -\def\unnumberedsubsubseczzz#1{% - \global\advance\subsubsecno by 1 - \sectionheading{#1}{subsubsec}{Ynothing}% - {\the\unnumberedno.\the\secno.\the\subsecno.\the\subsubsecno}% -} - -% These macros control what the section commands do, according -% to what kind of chapter we are in (ordinary, appendix, or unnumbered). -% Define them by default for a numbered chapter. -\let\section = \numberedsec -\let\subsection = \numberedsubsec -\let\subsubsection = \numberedsubsubsec - -% Define @majorheading, @heading and @subheading - -% NOTE on use of \vbox for chapter headings, section headings, and such: -% 1) We use \vbox rather than the earlier \line to permit -% overlong headings to fold. -% 2) \hyphenpenalty is set to 10000 because hyphenation in a -% heading is obnoxious; this forbids it. -% 3) Likewise, headings look best if no \parindent is used, and -% if justification is not attempted. Hence \raggedright. - - -\def\majorheading{% - {\advance\chapheadingskip by 10pt \chapbreak }% - \parsearg\chapheadingzzz -} - -\def\chapheading{\chapbreak \parsearg\chapheadingzzz} -\def\chapheadingzzz#1{% - {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}% - \bigskip \par\penalty 200\relax - \suppressfirstparagraphindent -} - -% @heading, @subheading, @subsubheading. -\parseargdef\heading{\sectionheading{#1}{sec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subheading{\sectionheading{#1}{subsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} -\parseargdef\subsubheading{\sectionheading{#1}{subsubsec}{Yomitfromtoc}{} - \suppressfirstparagraphindent} - -% These macros generate a chapter, section, etc. heading only -% (including whitespace, linebreaking, etc. around it), -% given all the information in convenient, parsed form. - -%%% Args are the skip and penalty (usually negative) -\def\dobreak#1#2{\par\ifdim\lastskip<#1\removelastskip\penalty#2\vskip#1\fi} - -%%% Define plain chapter starts, and page on/off switching for it -% Parameter controlling skip before chapter headings (if needed) - -\newskip\chapheadingskip - -\def\chapbreak{\dobreak \chapheadingskip {-4000}} -\def\chappager{\par\vfill\supereject} -\def\chapoddpage{\chappager \ifodd\pageno \else \hbox to 0pt{} \chappager\fi} - -\def\setchapternewpage #1 {\csname CHAPPAG#1\endcsname} - -\def\CHAPPAGoff{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chapbreak -\global\let\pagealignmacro=\chappager} - -\def\CHAPPAGon{% -\global\let\contentsalignmacro = \chappager -\global\let\pchapsepmacro=\chappager -\global\let\pagealignmacro=\chappager -\global\def\HEADINGSon{\HEADINGSsingle}} - -\def\CHAPPAGodd{% -\global\let\contentsalignmacro = \chapoddpage -\global\let\pchapsepmacro=\chapoddpage -\global\let\pagealignmacro=\chapoddpage -\global\def\HEADINGSon{\HEADINGSdouble}} - -\CHAPPAGon - -% Chapter opening. -% -% #1 is the text, #2 is the section type (Ynumbered, Ynothing, -% Yappendix, Yomitfromtoc), #3 the chapter number. -% -% To test against our argument. -\def\Ynothingkeyword{Ynothing} -\def\Yomitfromtockeyword{Yomitfromtoc} -\def\Yappendixkeyword{Yappendix} -% -\def\chapmacro#1#2#3{% - \pchapsepmacro - {% - \chapfonts \rm - % - % Have to define \thissection before calling \donoderef, because the - % xref code eventually uses it. On the other hand, it has to be called - % after \pchapsepmacro, or the headline will change too soon. - \gdef\thissection{#1}% - \gdef\thischaptername{#1}% - % - % Only insert the separating space if we have a chapter/appendix - % number, and don't print the unnumbered ``number''. - \def\temptype{#2}% - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unnchap}% - \gdef\thischapternum{}% - \gdef\thischapter{#1}% - \else\ifx\temptype\Yomitfromtockeyword - \setbox0 = \hbox{}% contents like unnumbered, but no toc entry - \def\toctype{omit}% - \gdef\thischapternum{}% - \gdef\thischapter{}% - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{\putwordAppendix{} #3\enspace}% - \def\toctype{app}% - \xdef\thischapternum{\appendixletter}% - % We don't substitute the actual chapter name into \thischapter - % because we don't want its macros evaluated now. And we don't - % use \thissection because that changes with each section. - % - \xdef\thischapter{\putwordAppendix{} \appendixletter: - \noexpand\thischaptername}% - \else - \setbox0 = \hbox{#3\enspace}% - \def\toctype{numchap}% - \xdef\thischapternum{\the\chapno}% - \xdef\thischapter{\putwordChapter{} \the\chapno: - \noexpand\thischaptername}% - \fi\fi\fi - % - % Write the toc entry for this chapter. Must come before the - % \donoderef, because we include the current node name in the toc - % entry, and \donoderef resets it to empty. - \writetocentry{\toctype}{#1}{#3}% - % - % For pdftex, we have to write out the node definition (aka, make - % the pdfdest) after any page break, but before the actual text has - % been typeset. If the destination for the pdf outline is after the - % text, then jumping from the outline may wind up with the text not - % being visible, for instance under high magnification. - \donoderef{#2}% - % - % Typeset the actual heading. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 \centerparametersmaybe - \unhbox0 #1\par}% - }% - \nobreak\bigskip % no page break after a chapter title - \nobreak -} - -% @centerchap -- centered and unnumbered. -\let\centerparametersmaybe = \relax -\def\centerparameters{% - \advance\rightskip by 3\rightskip - \leftskip = \rightskip - \parfillskip = 0pt -} - - -% I don't think this chapter style is supported any more, so I'm not -% updating it with the new noderef stuff. We'll see. --karl, 11aug03. -% -\def\setchapterstyle #1 {\csname CHAPF#1\endcsname} -% -\def\unnchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt\raggedright - \rm #1\hfill}}\bigskip \par\nobreak -} -\def\chfopen #1#2{\chapoddpage {\chapfonts -\vbox to 3in{\vfil \hbox to\hsize{\hfil #2} \hbox to\hsize{\hfil #1} \vfil}}% -\par\penalty 5000 % -} -\def\centerchfopen #1{% -\chapoddpage {\chapfonts \vbox{\hyphenpenalty=10000\tolerance=5000 - \parindent=0pt - \hfill {\rm #1}\hfill}}\bigskip \par\nobreak -} -\def\CHAPFopen{% - \global\let\chapmacro=\chfopen - \global\let\centerchapmacro=\centerchfopen} - - -% Section titles. These macros combine the section number parts and -% call the generic \sectionheading to do the printing. -% -\newskip\secheadingskip -\def\secheadingbreak{\dobreak \secheadingskip{-1000}} - -% Subsection titles. -\newskip\subsecheadingskip -\def\subsecheadingbreak{\dobreak \subsecheadingskip{-500}} - -% Subsubsection titles. -\def\subsubsecheadingskip{\subsecheadingskip} -\def\subsubsecheadingbreak{\subsecheadingbreak} - - -% Print any size, any type, section title. -% -% #1 is the text, #2 is the section level (sec/subsec/subsubsec), #3 is -% the section type for xrefs (Ynumbered, Ynothing, Yappendix), #4 is the -% section number. -% -\def\sectionheading#1#2#3#4{% - {% - % Switch to the right set of fonts. - \csname #2fonts\endcsname \rm - % - % Insert space above the heading. - \csname #2headingbreak\endcsname - % - % Only insert the space after the number if we have a section number. - \def\sectionlevel{#2}% - \def\temptype{#3}% - % - \ifx\temptype\Ynothingkeyword - \setbox0 = \hbox{}% - \def\toctype{unn}% - \gdef\thissection{#1}% - \else\ifx\temptype\Yomitfromtockeyword - % for @headings -- no section number, don't include in toc, - % and don't redefine \thissection. - \setbox0 = \hbox{}% - \def\toctype{omit}% - \let\sectionlevel=\empty - \else\ifx\temptype\Yappendixkeyword - \setbox0 = \hbox{#4\enspace}% - \def\toctype{app}% - \gdef\thissection{#1}% - \else - \setbox0 = \hbox{#4\enspace}% - \def\toctype{num}% - \gdef\thissection{#1}% - \fi\fi\fi - % - % Write the toc entry (before \donoderef). See comments in \chapmacro. - \writetocentry{\toctype\sectionlevel}{#1}{#4}% - % - % Write the node reference (= pdf destination for pdftex). - % Again, see comments in \chapmacro. - \donoderef{#3}% - % - % Interline glue will be inserted when the vbox is completed. - % That glue will be a valid breakpoint for the page, since it'll be - % preceded by a whatsit (usually from the \donoderef, or from the - % \writetocentry if there was no node). We don't want to allow that - % break, since then the whatsits could end up on page n while the - % section is on page n+1, thus toc/etc. are wrong. Debian bug 276000. - \nobreak - % - % Output the actual section heading. - \vbox{\hyphenpenalty=10000 \tolerance=5000 \parindent=0pt \raggedright - \hangindent=\wd0 % zero if no section number - \unhbox0 #1}% - }% - % Add extra space after the heading -- half of whatever came above it. - % Don't allow stretch, though. - \kern .5 \csname #2headingskip\endcsname - % - % Do not let the kern be a potential breakpoint, as it would be if it - % was followed by glue. - \nobreak - % - % We'll almost certainly start a paragraph next, so don't let that - % glue accumulate. (Not a breakpoint because it's preceded by a - % discardable item.) - \vskip-\parskip - % - % This is purely so the last item on the list is a known \penalty > - % 10000. This is so \startdefun can avoid allowing breakpoints after - % section headings. Otherwise, it would insert a valid breakpoint between: - % - % @section sec-whatever - % @deffn def-whatever - \penalty 10001 -} - - -\message{toc,} -% Table of contents. -\newwrite\tocfile - -% Write an entry to the toc file, opening it if necessary. -% Called from @chapter, etc. -% -% Example usage: \writetocentry{sec}{Section Name}{\the\chapno.\the\secno} -% We append the current node name (if any) and page number as additional -% arguments for the \{chap,sec,...}entry macros which will eventually -% read this. The node name is used in the pdf outlines as the -% destination to jump to. -% -% We open the .toc file for writing here instead of at @setfilename (or -% any other fixed time) so that @contents can be anywhere in the document. -% But if #1 is `omit', then we don't do anything. This is used for the -% table of contents chapter openings themselves. -% -\newif\iftocfileopened -\def\omitkeyword{omit}% -% -\def\writetocentry#1#2#3{% - \edef\writetoctype{#1}% - \ifx\writetoctype\omitkeyword \else - \iftocfileopened\else - \immediate\openout\tocfile = \jobname.toc - \global\tocfileopenedtrue - \fi - % - \iflinks - {\atdummies - \edef\temp{% - \write\tocfile{@#1entry{#2}{#3}{\lastnode}{\noexpand\folio}}}% - \temp - }% - \fi - \fi - % - % Tell \shipout to create a pdf destination on each page, if we're - % writing pdf. These are used in the table of contents. We can't - % just write one on every page because the title pages are numbered - % 1 and 2 (the page numbers aren't printed), and so are the first - % two pages of the document. Thus, we'd have two destinations named - % `1', and two named `2'. - \ifpdf \global\pdfmakepagedesttrue \fi -} - - -% These characters do not print properly in the Computer Modern roman -% fonts, so we must take special care. This is more or less redundant -% with the Texinfo input format setup at the end of this file. -% -\def\activecatcodes{% - \catcode`\"=\active - \catcode`\$=\active - \catcode`\<=\active - \catcode`\>=\active - \catcode`\\=\active - \catcode`\^=\active - \catcode`\_=\active - \catcode`\|=\active - \catcode`\~=\active -} - - -% Read the toc file, which is essentially Texinfo input. -\def\readtocfile{% - \setupdatafile - \activecatcodes - \input \tocreadfilename -} - -\newskip\contentsrightmargin \contentsrightmargin=1in -\newcount\savepageno -\newcount\lastnegativepageno \lastnegativepageno = -1 - -% Prepare to read what we've written to \tocfile. -% -\def\startcontents#1{% - % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund - \contentsalignmacro - \immediate\closeout\tocfile - % - % Don't need to put `Contents' or `Short Contents' in the headline. - % It is abundantly clear what they are. - \def\thischapter{}% - \chapmacro{#1}{Yomitfromtoc}{}% - % - \savepageno = \pageno - \begingroup % Set up to handle contents files properly. - \raggedbottom % Worry more about breakpoints than the bottom. - \advance\hsize by -\contentsrightmargin % Don't use the full line length. - % - % Roman numerals for page numbers. - \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi -} - -% redefined for the two-volume lispref. We always output on -% \jobname.toc even if this is redefined. -% -\def\tocreadfilename{\jobname.toc} - -% Normal (long) toc. -% -\def\contents{% - \startcontents{\putwordTOC}% - \openin 1 \tocreadfilename\space - \ifeof 1 \else - \readtocfile - \fi - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \ifeof 1 \else - \pdfmakeoutlines - \fi - \closein 1 - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} - -% And just the chapters. -\def\summarycontents{% - \startcontents{\putwordShortTOC}% - % - \let\numchapentry = \shortchapentry - \let\appentry = \shortchapentry - \let\unnchapentry = \shortunnchapentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf - \let\sl=\shortcontsl \let\tt=\shortconttt - \rm - \hyphenpenalty = 10000 - \advance\baselineskip by 1pt % Open it up a little. - \def\numsecentry##1##2##3##4{} - \let\appsecentry = \numsecentry - \let\unnsecentry = \numsecentry - \let\numsubsecentry = \numsecentry - \let\appsubsecentry = \numsecentry - \let\unnsubsecentry = \numsecentry - \let\numsubsubsecentry = \numsecentry - \let\appsubsubsecentry = \numsecentry - \let\unnsubsubsecentry = \numsecentry - \openin 1 \tocreadfilename\space - \ifeof 1 \else - \readtocfile - \fi - \closein 1 - \vfill \eject - \contentsalignmacro % in case @setchapternewpage odd is in effect - \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno -} -\let\shortcontents = \summarycontents - -% Typeset the label for a chapter or appendix for the short contents. -% The arg is, e.g., `A' for an appendix, or `3' for a chapter. -% -\def\shortchaplabel#1{% - % This space should be enough, since a single number is .5em, and the - % widest letter (M) is 1em, at least in the Computer Modern fonts. - % But use \hss just in case. - % (This space doesn't include the extra space that gets added after - % the label; that gets put in by \shortchapentry above.) - % - % We'd like to right-justify chapter numbers, but that looks strange - % with appendix letters. And right-justifying numbers and - % left-justifying letters looks strange when there is less than 10 - % chapters. Have to read the whole toc once to know how many chapters - % there are before deciding ... - \hbox to 1em{#1\hss}% -} - -% These macros generate individual entries in the table of contents. -% The first argument is the chapter or section name. -% The last argument is the page number. -% The arguments in between are the chapter number, section number, ... - -% Chapters, in the main contents. -\def\numchapentry#1#2#3#4{\dochapentry{#2\labelspace#1}{#4}} -% -% Chapters, in the short toc. -% See comments in \dochapentry re vbox and related settings. -\def\shortchapentry#1#2#3#4{% - \tocentry{\shortchaplabel{#2}\labelspace #1}{\doshortpageno\bgroup#4\egroup}% -} - -% Appendices, in the main contents. -% Need the word Appendix, and a fixed-size box. -% -\def\appendixbox#1{% - % We use M since it's probably the widest letter. - \setbox0 = \hbox{\putwordAppendix{} M}% - \hbox to \wd0{\putwordAppendix{} #1\hss}} -% -\def\appentry#1#2#3#4{\dochapentry{\appendixbox{#2}\labelspace#1}{#4}} - -% Unnumbered chapters. -\def\unnchapentry#1#2#3#4{\dochapentry{#1}{#4}} -\def\shortunnchapentry#1#2#3#4{\tocentry{#1}{\doshortpageno\bgroup#4\egroup}} - -% Sections. -\def\numsecentry#1#2#3#4{\dosecentry{#2\labelspace#1}{#4}} -\let\appsecentry=\numsecentry -\def\unnsecentry#1#2#3#4{\dosecentry{#1}{#4}} - -% Subsections. -\def\numsubsecentry#1#2#3#4{\dosubsecentry{#2\labelspace#1}{#4}} -\let\appsubsecentry=\numsubsecentry -\def\unnsubsecentry#1#2#3#4{\dosubsecentry{#1}{#4}} - -% And subsubsections. -\def\numsubsubsecentry#1#2#3#4{\dosubsubsecentry{#2\labelspace#1}{#4}} -\let\appsubsubsecentry=\numsubsubsecentry -\def\unnsubsubsecentry#1#2#3#4{\dosubsubsecentry{#1}{#4}} - -% This parameter controls the indentation of the various levels. -% Same as \defaultparindent. -\newdimen\tocindent \tocindent = 15pt - -% Now for the actual typesetting. In all these, #1 is the text and #2 is the -% page number. -% -% If the toc has to be broken over pages, we want it to be at chapters -% if at all possible; hence the \penalty. -\def\dochapentry#1#2{% - \penalty-300 \vskip1\baselineskip plus.33\baselineskip minus.25\baselineskip - \begingroup - \chapentryfonts - \tocentry{#1}{\dopageno\bgroup#2\egroup}% - \endgroup - \nobreak\vskip .25\baselineskip plus.1\baselineskip -} - -\def\dosecentry#1#2{\begingroup - \secentryfonts \leftskip=\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsecentry#1#2{\begingroup - \subsecentryfonts \leftskip=2\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -\def\dosubsubsecentry#1#2{\begingroup - \subsubsecentryfonts \leftskip=3\tocindent - \tocentry{#1}{\dopageno\bgroup#2\egroup}% -\endgroup} - -% We use the same \entry macro as for the index entries. -\let\tocentry = \entry - -% Space between chapter (or whatever) number and the title. -\def\labelspace{\hskip1em \relax} - -\def\dopageno#1{{\rm #1}} -\def\doshortpageno#1{{\rm #1}} - -\def\chapentryfonts{\secfonts \rm} -\def\secentryfonts{\textfonts} -\def\subsecentryfonts{\textfonts} -\def\subsubsecentryfonts{\textfonts} - - -\message{environments,} -% @foo ... @end foo. - -% @point{}, @result{}, @expansion{}, @print{}, @equiv{}. -% -% Since these characters are used in examples, it should be an even number of -% \tt widths. Each \tt character is 1en, so two makes it 1em. -% -\def\point{$\star$} -\def\result{\leavevmode\raise.15ex\hbox to 1em{\hfil$\Rightarrow$\hfil}} -\def\expansion{\leavevmode\raise.1ex\hbox to 1em{\hfil$\mapsto$\hfil}} -\def\print{\leavevmode\lower.1ex\hbox to 1em{\hfil$\dashv$\hfil}} -\def\equiv{\leavevmode\lower.1ex\hbox to 1em{\hfil$\ptexequiv$\hfil}} - -% The @error{} command. -% Adapted from the TeXbook's \boxit. -% -\newbox\errorbox -% -{\tentt \global\dimen0 = 3em}% Width of the box. -\dimen2 = .55pt % Thickness of rules -% The text. (`r' is open on the right, `e' somewhat less so on the left.) -\setbox0 = \hbox{\kern-.75pt \reducedsf error\kern-1.5pt} -% -\setbox\errorbox=\hbox to \dimen0{\hfil - \hsize = \dimen0 \advance\hsize by -5.8pt % Space to left+right. - \advance\hsize by -2\dimen2 % Rules. - \vbox{% - \hrule height\dimen2 - \hbox{\vrule width\dimen2 \kern3pt % Space to left of text. - \vtop{\kern2.4pt \box0 \kern2.4pt}% Space above/below. - \kern3pt\vrule width\dimen2}% Space to right. - \hrule height\dimen2} - \hfil} -% -\def\error{\leavevmode\lower.7ex\copy\errorbox} - -% @tex ... @end tex escapes into raw Tex temporarily. -% One exception: @ is still an escape character, so that @end tex works. -% But \@ or @@ will get a plain tex @ character. - -\envdef\tex{% - \catcode `\\=0 \catcode `\{=1 \catcode `\}=2 - \catcode `\$=3 \catcode `\&=4 \catcode `\#=6 - \catcode `\^=7 \catcode `\_=8 \catcode `\~=\active \let~=\tie - \catcode `\%=14 - \catcode `\+=\other - \catcode `\"=\other - \catcode `\|=\other - \catcode `\<=\other - \catcode `\>=\other - \escapechar=`\\ - % - \let\b=\ptexb - \let\bullet=\ptexbullet - \let\c=\ptexc - \let\,=\ptexcomma - \let\.=\ptexdot - \let\dots=\ptexdots - \let\equiv=\ptexequiv - \let\!=\ptexexclam - \let\i=\ptexi - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \let\{=\ptexlbrace - \let\+=\tabalign - \let\}=\ptexrbrace - \let\/=\ptexslash - \let\*=\ptexstar - \let\t=\ptext - \let\frenchspacing=\plainfrenchspacing - % - \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% - \def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% - \def\@{@}% -} -% There is no need to define \Etex. - -% Define @lisp ... @end lisp. -% @lisp environment forms a group so it can rebind things, -% including the definition of @end lisp (which normally is erroneous). - -% Amount to narrow the margins by for @lisp. -\newskip\lispnarrowing \lispnarrowing=0.4in - -% This is the definition that ^^M gets inside @lisp, @example, and other -% such environments. \null is better than a space, since it doesn't -% have any width. -\def\lisppar{\null\endgraf} - -% This space is always present above and below environments. -\newskip\envskipamount \envskipamount = 0pt - -% Make spacing and below environment symmetrical. We use \parskip here -% to help in doing that, since in @example-like environments \parskip -% is reset to zero; thus the \afterenvbreak inserts no space -- but the -% start of the next paragraph will insert \parskip. -% -\def\aboveenvbreak{{% - % =10000 instead of <10000 because of a special case in \itemzzz and - % \sectionheading, q.v. - \ifnum \lastpenalty=10000 \else - \advance\envskipamount by \parskip - \endgraf - \ifdim\lastskip<\envskipamount - \removelastskip - % it's not a good place to break if the last penalty was \nobreak - % or better ... - \ifnum\lastpenalty<10000 \penalty-50 \fi - \vskip\envskipamount - \fi - \fi -}} - -\let\afterenvbreak = \aboveenvbreak - -% \nonarrowing is a flag. If "set", @lisp etc don't narrow margins; it will -% also clear it, so that its embedded environments do the narrowing again. -\let\nonarrowing=\relax - -% @cartouche ... @end cartouche: draw rectangle w/rounded corners around -% environment contents. -\font\circle=lcircle10 -\newdimen\circthick -\newdimen\cartouter\newdimen\cartinner -\newskip\normbskip\newskip\normpskip\newskip\normlskip -\circthick=\fontdimen8\circle -% -\def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth -\def\ctr{{\hskip 6pt\circle\char'010}} -\def\cbl{{\circle\char'012\hskip -6pt}} -\def\cbr{{\hskip 6pt\circle\char'011}} -\def\carttop{\hbox to \cartouter{\hskip\lskip - \ctl\leaders\hrule height\circthick\hfil\ctr - \hskip\rskip}} -\def\cartbot{\hbox to \cartouter{\hskip\lskip - \cbl\leaders\hrule height\circthick\hfil\cbr - \hskip\rskip}} -% -\newskip\lskip\newskip\rskip - -\envdef\cartouche{% - \ifhmode\par\fi % can't be in the midst of a paragraph. - \startsavinginserts - \lskip=\leftskip \rskip=\rightskip - \leftskip=0pt\rightskip=0pt % we want these *outside*. - \cartinner=\hsize \advance\cartinner by-\lskip - \advance\cartinner by-\rskip - \cartouter=\hsize - \advance\cartouter by 18.4pt % allow for 3pt kerns on either - % side, and for 6pt waste from - % each corner char, and rule thickness - \normbskip=\baselineskip \normpskip=\parskip \normlskip=\lineskip - % Flag to tell @lisp, etc., not to narrow margin. - \let\nonarrowing = t% - \vbox\bgroup - \baselineskip=0pt\parskip=0pt\lineskip=0pt - \carttop - \hbox\bgroup - \hskip\lskip - \vrule\kern3pt - \vbox\bgroup - \kern3pt - \hsize=\cartinner - \baselineskip=\normbskip - \lineskip=\normlskip - \parskip=\normpskip - \vskip -\parskip - \comment % For explanation, see the end of \def\group. -} -\def\Ecartouche{% - \ifhmode\par\fi - \kern3pt - \egroup - \kern3pt\vrule - \hskip\rskip - \egroup - \cartbot - \egroup - \checkinserts -} - - -% This macro is called at the beginning of all the @example variants, -% inside a group. -\def\nonfillstart{% - \aboveenvbreak - \hfuzz = 12pt % Don't be fussy - \sepspaces % Make spaces be word-separators rather than space tokens. - \let\par = \lisppar % don't ignore blank lines - \obeylines % each line of input is a line of output - \parskip = 0pt - \parindent = 0pt - \emergencystretch = 0pt % don't try to avoid overfull boxes - \ifx\nonarrowing\relax - \advance \leftskip by \lispnarrowing - \exdentamount=\lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \let\exdent=\nofillexdent -} - -% If you want all examples etc. small: @set dispenvsize small. -% If you want even small examples the full size: @set dispenvsize nosmall. -% This affects the following displayed environments: -% @example, @display, @format, @lisp -% -\def\smallword{small} -\def\nosmallword{nosmall} -\let\SETdispenvsize\relax -\def\setnormaldispenv{% - \ifx\SETdispenvsize\smallword - % end paragraph for sake of leading, in case document has no blank - % line. This is redundant with what happens in \aboveenvbreak, but - % we need to do it before changing the fonts, and it's inconvenient - % to change the fonts afterward. - \ifnum \lastpenalty=10000 \else \endgraf \fi - \smallexamplefonts \rm - \fi -} -\def\setsmalldispenv{% - \ifx\SETdispenvsize\nosmallword - \else - \ifnum \lastpenalty=10000 \else \endgraf \fi - \smallexamplefonts \rm - \fi -} - -% We often define two environments, @foo and @smallfoo. -% Let's do it by one command: -\def\makedispenv #1#2{ - \expandafter\envdef\csname#1\endcsname {\setnormaldispenv #2} - \expandafter\envdef\csname small#1\endcsname {\setsmalldispenv #2} - \expandafter\let\csname E#1\endcsname \afterenvbreak - \expandafter\let\csname Esmall#1\endcsname \afterenvbreak -} - -% Define two synonyms: -\def\maketwodispenvs #1#2#3{ - \makedispenv{#1}{#3} - \makedispenv{#2}{#3} -} - -% @lisp: indented, narrowed, typewriter font; @example: same as @lisp. -% -% @smallexample and @smalllisp: use smaller fonts. -% Originally contributed by Pavel@xerox. -% -\maketwodispenvs {lisp}{example}{% - \nonfillstart - \tt\quoteexpand - \let\kbdfont = \kbdexamplefont % Allow @kbd to do something special. - \gobble % eat return -} -% @display/@smalldisplay: same as @lisp except keep current font. -% -\makedispenv {display}{% - \nonfillstart - \gobble -} - -% @format/@smallformat: same as @display except don't narrow margins. -% -\makedispenv{format}{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} - -% @flushleft: same as @format, but doesn't obey \SETdispenvsize. -\envdef\flushleft{% - \let\nonarrowing = t% - \nonfillstart - \gobble -} -\let\Eflushleft = \afterenvbreak - -% @flushright. -% -\envdef\flushright{% - \let\nonarrowing = t% - \nonfillstart - \advance\leftskip by 0pt plus 1fill - \gobble -} -\let\Eflushright = \afterenvbreak - - -% @quotation does normal linebreaking (hence we can't use \nonfillstart) -% and narrows the margins. We keep \parskip nonzero in general, since -% we're doing normal filling. So, when using \aboveenvbreak and -% \afterenvbreak, temporarily make \parskip 0. -% -\envdef\quotation{% - {\parskip=0pt \aboveenvbreak}% because \aboveenvbreak inserts \parskip - \parindent=0pt - % - % @cartouche defines \nonarrowing to inhibit narrowing at next level down. - \ifx\nonarrowing\relax - \advance\leftskip by \lispnarrowing - \advance\rightskip by \lispnarrowing - \exdentamount = \lispnarrowing - \else - \let\nonarrowing = \relax - \fi - \parsearg\quotationlabel -} - -% We have retained a nonzero parskip for the environment, since we're -% doing normal filling. -% -\def\Equotation{% - \par - \ifx\quotationauthor\undefined\else - % indent a bit. - \leftline{\kern 2\leftskip \sl ---\quotationauthor}% - \fi - {\parskip=0pt \afterenvbreak}% -} - -% If we're given an argument, typeset it in bold with a colon after. -\def\quotationlabel#1{% - \def\temp{#1}% - \ifx\temp\empty \else - {\bf #1: }% - \fi -} - - -% LaTeX-like @verbatim...@end verbatim and @verb{...} -% If we want to allow any as delimiter, -% we need the curly braces so that makeinfo sees the @verb command, eg: -% `@verbx...x' would look like the '@verbx' command. --janneke@gnu.org -% -% [Knuth]: Donald Ervin Knuth, 1996. The TeXbook. -% -% [Knuth] p.344; only we need to do the other characters Texinfo sets -% active too. Otherwise, they get lost as the first character on a -% verbatim line. -\def\dospecials{% - \do\ \do\\\do\{\do\}\do\$\do\&% - \do\#\do\^\do\^^K\do\_\do\^^A\do\%\do\~% - \do\<\do\>\do\|\do\@\do+\do\"% -} -% -% [Knuth] p. 380 -\def\uncatcodespecials{% - \def\do##1{\catcode`##1=\other}\dospecials} -% -% [Knuth] pp. 380,381,391 -% Disable Spanish ligatures ?` and !` of \tt font -\begingroup - \catcode`\`=\active\gdef`{\relax\lq} -\endgroup -% -% Setup for the @verb command. -% -% Eight spaces for a tab -\begingroup - \catcode`\^^I=\active - \gdef\tabeightspaces{\catcode`\^^I=\active\def^^I{\ \ \ \ \ \ \ \ }} -\endgroup -% -\def\setupverb{% - \tt % easiest (and conventionally used) font for verbatim - \def\par{\leavevmode\endgraf}% - \catcode`\`=\active - \tabeightspaces - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces -} - -% Setup for the @verbatim environment -% -% Real tab expansion -\newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount -% -\def\starttabbox{\setbox0=\hbox\bgroup} - -% Allow an option to not replace quotes with a regular directed right -% quote/apostrophe (char 0x27), but instead use the undirected quote -% from cmtt (char 0x0d). The undirected quote is ugly, so don't make it -% the default, but it works for pasting with more pdf viewers (at least -% evince), the lilypond developers report. xpdf does work with the -% regular 0x27. -% -\def\codequoteright{% - \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax - \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax - '% - \else \char'15 \fi - \else \char'15 \fi -} -% -% and a similar option for the left quote char vs. a grave accent. -% Modern fonts display ASCII 0x60 as a grave accent, so some people like -% the code environments to do likewise. -% -\def\codequoteleft{% - \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax - \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax - `% - \else \char'22 \fi - \else \char'22 \fi -} -% -\begingroup - \catcode`\^^I=\active - \gdef\tabexpand{% - \catcode`\^^I=\active - \def^^I{\leavevmode\egroup - \dimen0=\wd0 % the width so far, or since the previous tab - \divide\dimen0 by\tabw - \multiply\dimen0 by\tabw % compute previous multiple of \tabw - \advance\dimen0 by\tabw % advance to next multiple of \tabw - \wd0=\dimen0 \box0 \starttabbox - }% - } - \catcode`\'=\active - \gdef\rquoteexpand{\catcode\rquoteChar=\active \def'{\codequoteright}}% - % - \catcode`\`=\active - \gdef\lquoteexpand{\catcode\lquoteChar=\active \def`{\codequoteleft}}% - % - \gdef\quoteexpand{\rquoteexpand \lquoteexpand}% -\endgroup - -% start the verbatim environment. -\def\setupverbatim{% - \let\nonarrowing = t% - \nonfillstart - % Easiest (and conventionally used) font for verbatim - \tt - \def\par{\leavevmode\egroup\box0\endgraf}% - \catcode`\`=\active - \tabexpand - \quoteexpand - % Respect line breaks, - % print special symbols as themselves, and - % make each space count - % must do in this order: - \obeylines \uncatcodespecials \sepspaces - \everypar{\starttabbox}% -} - -% Do the @verb magic: verbatim text is quoted by unique -% delimiter characters. Before first delimiter expect a -% right brace, after last delimiter expect closing brace: -% -% \def\doverb'{'#1'}'{#1} -% -% [Knuth] p. 382; only eat outer {} -\begingroup - \catcode`[=1\catcode`]=2\catcode`\{=\other\catcode`\}=\other - \gdef\doverb{#1[\def\next##1#1}[##1\endgroup]\next] -\endgroup -% -\def\verb{\begingroup\setupverb\doverb} -% -% -% Do the @verbatim magic: define the macro \doverbatim so that -% the (first) argument ends when '@end verbatim' is reached, ie: -% -% \def\doverbatim#1@end verbatim{#1} -% -% For Texinfo it's a lot easier than for LaTeX, -% because texinfo's \verbatim doesn't stop at '\end{verbatim}': -% we need not redefine '\', '{' and '}'. -% -% Inspired by LaTeX's verbatim command set [latex.ltx] -% -\begingroup - \catcode`\ =\active - \obeylines % - % ignore everything up to the first ^^M, that's the newline at the end - % of the @verbatim input line itself. Otherwise we get an extra blank - % line in the output. - \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% - % We really want {...\end verbatim} in the body of the macro, but - % without the active space; thus we have to use \xdef and \gobble. -\endgroup -% -\envdef\verbatim{% - \setupverbatim\doverbatim -} -\let\Everbatim = \afterenvbreak - - -% @verbatiminclude FILE - insert text of file in verbatim environment. -% -\def\verbatiminclude{\parseargusing\filenamecatcodes\doverbatiminclude} -% -\def\doverbatiminclude#1{% - {% - \makevalueexpandable - \setupverbatim - \input #1 - \afterenvbreak - }% -} - -% @copying ... @end copying. -% Save the text away for @insertcopying later. -% -% We save the uninterpreted tokens, rather than creating a box. -% Saving the text in a box would be much easier, but then all the -% typesetting commands (@smallbook, font changes, etc.) have to be done -% beforehand -- and a) we want @copying to be done first in the source -% file; b) letting users define the frontmatter in as flexible order as -% possible is very desirable. -% -\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} -\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} -% -\def\insertcopying{% - \begingroup - \parindent = 0pt % paragraph indentation looks wrong on title page - \scanexp\copyingtext - \endgroup -} - - -\message{defuns,} -% @defun etc. - -\newskip\defbodyindent \defbodyindent=.4in -\newskip\defargsindent \defargsindent=50pt -\newskip\deflastargmargin \deflastargmargin=18pt -\newcount\defunpenalty - -% Start the processing of @deffn: -\def\startdefun{% - \ifnum\lastpenalty<10000 - \medbreak - \defunpenalty=10003 % Will keep this @deffn together with the - % following @def command, see below. - \else - % If there are two @def commands in a row, we'll have a \nobreak, - % which is there to keep the function description together with its - % header. But if there's nothing but headers, we need to allow a - % break somewhere. Check specifically for penalty 10002, inserted - % by \printdefunline, instead of 10000, since the sectioning - % commands also insert a nobreak penalty, and we don't want to allow - % a break between a section heading and a defun. - % - % As a minor refinement, we avoid "club" headers by signalling - % with penalty of 10003 after the very first @deffn in the - % sequence (see above), and penalty of 10002 after any following - % @def command. - \ifnum\lastpenalty=10002 \penalty2000 \else \defunpenalty=10002 \fi - % - % Similarly, after a section heading, do not allow a break. - % But do insert the glue. - \medskip % preceded by discardable penalty, so not a breakpoint - \fi - % - \parindent=0in - \advance\leftskip by \defbodyindent - \exdentamount=\defbodyindent -} - -\def\dodefunx#1{% - % First, check whether we are in the right environment: - \checkenv#1% - % - % As above, allow line break if we have multiple x headers in a row. - % It's not a great place, though. - \ifnum\lastpenalty=10002 \penalty3000 \else \defunpenalty=10002 \fi - % - % And now, it's time to reuse the body of the original defun: - \expandafter\gobbledefun#1% -} -\def\gobbledefun#1\startdefun{} - -% \printdefunline \deffnheader{text} -% -\def\printdefunline#1#2{% - \begingroup - % call \deffnheader: - #1#2 \endheader - % common ending: - \interlinepenalty = 10000 - \advance\rightskip by 0pt plus 1fil - \endgraf - \nobreak\vskip -\parskip - \penalty\defunpenalty % signal to \startdefun and \dodefunx - % Some of the @defun-type tags do not enable magic parentheses, - % rendering the following check redundant. But we don't optimize. - \checkparencounts - \endgroup -} - -\def\Edefun{\endgraf\medbreak} - -% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; -% the only thing remainnig is to define \deffnheader. -% -\def\makedefun#1{% - \expandafter\let\csname E#1\endcsname = \Edefun - \edef\temp{\noexpand\domakedefun - \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% - \temp -} - -% \domakedefun \deffn \deffnx \deffnheader -% -% Define \deffn and \deffnx, without parameters. -% \deffnheader has to be defined explicitly. -% -\def\domakedefun#1#2#3{% - \envdef#1{% - \startdefun - \parseargusing\activeparens{\printdefunline#3}% - }% - \def#2{\dodefunx#1}% - \def#3% -} - -%%% Untyped functions: - -% @deffn category name args -\makedefun{deffn}{\deffngeneral{}} - -% @deffn category class name args -\makedefun{defop}#1 {\defopon{#1\ \putwordon}} - -% \defopon {category on}class name args -\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deffngeneral {subind}category name args -% -\def\deffngeneral#1#2 #3 #4\endheader{% - % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. - \dosubind{fn}{\code{#3}}{#1}% - \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% -} - -%%% Typed functions: - -% @deftypefn category type name args -\makedefun{deftypefn}{\deftypefngeneral{}} - -% @deftypeop category class type name args -\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} - -% \deftypeopon {category on}class type name args -\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deftypefngeneral {subind}category type name args -% -\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% - \dosubind{fn}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Typed variables: - -% @deftypevr category type var args -\makedefun{deftypevr}{\deftypecvgeneral{}} - -% @deftypecv category class type var args -\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} - -% \deftypecvof {category of}class type var args -\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } - -% \deftypecvgeneral {subind}category type var args -% -\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% - \dosubind{vr}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% -} - -%%% Untyped variables: - -% @defvr category var args -\makedefun{defvr}#1 {\deftypevrheader{#1} {} } - -% @defcv category class var args -\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} - -% \defcvof {category of}class var args -\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } - -%%% Type: -% @deftp category name args -\makedefun{deftp}#1 #2 #3\endheader{% - \doind{tp}{\code{#2}}% - \defname{#1}{}{#2}\defunargs{#3\unskip}% -} - -% Remaining @defun-like shortcuts: -\makedefun{defun}{\deffnheader{\putwordDeffunc} } -\makedefun{defmac}{\deffnheader{\putwordDefmac} } -\makedefun{defspec}{\deffnheader{\putwordDefspec} } -\makedefun{deftypefun}{\deftypefnheader{\putwordDeffunc} } -\makedefun{defvar}{\defvrheader{\putwordDefvar} } -\makedefun{defopt}{\defvrheader{\putwordDefopt} } -\makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } -\makedefun{defmethod}{\defopon\putwordMethodon} -\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} -\makedefun{defivar}{\defcvof\putwordInstanceVariableof} -\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} - -% \defname, which formats the name of the @def (not the args). -% #1 is the category, such as "Function". -% #2 is the return type, if any. -% #3 is the function name. -% -% We are followed by (but not passed) the arguments, if any. -% -\def\defname#1#2#3{% - % Get the values of \leftskip and \rightskip as they were outside the @def... - \advance\leftskip by -\defbodyindent - % - % How we'll format the type name. Putting it in brackets helps - % distinguish it from the body text that may end up on the next line - % just below it. - \def\temp{#1}% - \setbox0=\hbox{\kern\deflastargmargin \ifx\temp\empty\else [\rm\temp]\fi} - % - % Figure out line sizes for the paragraph shape. - % The first line needs space for \box0; but if \rightskip is nonzero, - % we need only space for the part of \box0 which exceeds it: - \dimen0=\hsize \advance\dimen0 by -\wd0 \advance\dimen0 by \rightskip - % The continuations: - \dimen2=\hsize \advance\dimen2 by -\defargsindent - % (plain.tex says that \dimen1 should be used only as global.) - \parshape 2 0in \dimen0 \defargsindent \dimen2 - % - % Put the type name to the right margin. - \noindent - \hbox to 0pt{% - \hfil\box0 \kern-\hsize - % \hsize has to be shortened this way: - \kern\leftskip - % Intentionally do not respect \rightskip, since we need the space. - }% - % - % Allow all lines to be underfull without complaint: - \tolerance=10000 \hbadness=10000 - \exdentamount=\defbodyindent - {% - % defun fonts. We use typewriter by default (used to be bold) because: - % . we're printing identifiers, they should be in tt in principle. - % . in languages with many accents, such as Czech or French, it's - % common to leave accents off identifiers. The result looks ok in - % tt, but exceedingly strange in rm. - % . we don't want -- and --- to be treated as ligatures. - % . this still does not fix the ?` and !` ligatures, but so far no - % one has made identifiers using them :). - \df \tt - \def\temp{#2}% return value type - \ifx\temp\empty\else \tclose{\temp} \fi - #3% output function name - }% - {\rm\enskip}% hskip 0.5 em of \tenrm - % - \boldbrax - % arguments will be output next, if any. -} - -% Print arguments in slanted roman (not ttsl), inconsistently with using -% tt for the name. This is because literal text is sometimes needed in -% the argument list (groff manual), and ttsl and tt are not very -% distinguishable. Prevent hyphenation at `-' chars. -% -\def\defunargs#1{% - % use sl by default (not ttsl), - % tt for the names. - \df \sl \hyphenchar\font=0 - % - % On the other hand, if an argument has two dashes (for instance), we - % want a way to get ttsl. Let's try @var for that. - \let\var=\ttslanted - #1% - \sl\hyphenchar\font=45 -} - -% We want ()&[] to print specially on the defun line. -% -\def\activeparens{% - \catcode`\(=\active \catcode`\)=\active - \catcode`\[=\active \catcode`\]=\active - \catcode`\&=\active -} - -% Make control sequences which act like normal parenthesis chars. -\let\lparen = ( \let\rparen = ) - -% Be sure that we always have a definition for `(', etc. For example, -% if the fn name has parens in it, \boldbrax will not be in effect yet, -% so TeX would otherwise complain about undefined control sequence. -{ - \activeparens - \global\let(=\lparen \global\let)=\rparen - \global\let[=\lbrack \global\let]=\rbrack - \global\let& = \& - - \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} - \gdef\magicamp{\let&=\amprm} -} - -\newcount\parencount - -% If we encounter &foo, then turn on ()-hacking afterwards -\newif\ifampseen -\def\amprm#1 {\ampseentrue{\bf\ }} - -\def\parenfont{% - \ifampseen - % At the first level, print parens in roman, - % otherwise use the default font. - \ifnum \parencount=1 \rm \fi - \else - % The \sf parens (in \boldbrax) actually are a little bolder than - % the contained text. This is especially needed for [ and ] . - \sf - \fi -} -\def\infirstlevel#1{% - \ifampseen - \ifnum\parencount=1 - #1% - \fi - \fi -} -\def\bfafterword#1 {#1 \bf} - -\def\opnr{% - \global\advance\parencount by 1 - {\parenfont(}% - \infirstlevel \bfafterword -} -\def\clnr{% - {\parenfont)}% - \infirstlevel \sl - \global\advance\parencount by -1 -} - -\newcount\brackcount -\def\lbrb{% - \global\advance\brackcount by 1 - {\bf[}% -} -\def\rbrb{% - {\bf]}% - \global\advance\brackcount by -1 -} - -\def\checkparencounts{% - \ifnum\parencount=0 \else \badparencount \fi - \ifnum\brackcount=0 \else \badbrackcount \fi -} -\def\badparencount{% - \errmessage{Unbalanced parentheses in @def}% - \global\parencount=0 -} -\def\badbrackcount{% - \errmessage{Unbalanced square braces in @def}% - \global\brackcount=0 -} - - -\message{macros,} -% @macro. - -% To do this right we need a feature of e-TeX, \scantokens, -% which we arrange to emulate with a temporary file in ordinary TeX. -\ifx\eTeXversion\undefined - \newwrite\macscribble - \def\scantokens#1{% - \toks0={#1}% - \immediate\openout\macscribble=\jobname.tmp - \immediate\write\macscribble{\the\toks0}% - \immediate\closeout\macscribble - \input \jobname.tmp - } -\fi - -\def\scanmacro#1{% - \begingroup - \newlinechar`\^^M - \let\xeatspaces\eatspaces - % Undo catcode changes of \startcontents and \doprintindex - % When called from @insertcopying or (short)caption, we need active - % backslash to get it printed correctly. Previously, we had - % \catcode`\\=\other instead. We'll see whether a problem appears - % with macro expansion. --kasal, 19aug04 - \catcode`\@=0 \catcode`\\=\active \escapechar=`\@ - % ... and \example - \spaceisspace - % - % Append \endinput to make sure that TeX does not see the ending newline. - % I've verified that it is necessary both for e-TeX and for ordinary TeX - % --kasal, 29nov03 - \scantokens{#1\endinput}% - \endgroup -} - -\def\scanexp#1{% - \edef\temp{\noexpand\scanmacro{#1}}% - \temp -} - -\newcount\paramno % Count of parameters -\newtoks\macname % Macro name -\newif\ifrecursive % Is it recursive? - -% List of all defined macros in the form -% \definedummyword\macro1\definedummyword\macro2... -% Currently is also contains all @aliases; the list can be split -% if there is a need. -\def\macrolist{} - -% Add the macro to \macrolist -\def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} -\def\addtomacrolistxxx#1{% - \toks0 = \expandafter{\macrolist\definedummyword#1}% - \xdef\macrolist{\the\toks0}% -} - -% Utility routines. -% This does \let #1 = #2, with \csnames; that is, -% \let \csname#1\endcsname = \csname#2\endcsname -% (except of course we have to play expansion games). -% -\def\cslet#1#2{% - \expandafter\let - \csname#1\expandafter\endcsname - \csname#2\endcsname -} - -% Trim leading and trailing spaces off a string. -% Concepts from aro-bend problem 15 (see CTAN). -{\catcode`\@=11 -\gdef\eatspaces #1{\expandafter\trim@\expandafter{#1 }} -\gdef\trim@ #1{\trim@@ @#1 @ #1 @ @@} -\gdef\trim@@ #1@ #2@ #3@@{\trim@@@\empty #2 @} -\def\unbrace#1{#1} -\unbrace{\gdef\trim@@@ #1 } #2@{#1} -} - -% Trim a single trailing ^^M off a string. -{\catcode`\^^M=\other \catcode`\Q=3% -\gdef\eatcr #1{\eatcra #1Q^^MQ}% -\gdef\eatcra#1^^MQ{\eatcrb#1Q}% -\gdef\eatcrb#1Q#2Q{#1}% -} - -% Macro bodies are absorbed as an argument in a context where -% all characters are catcode 10, 11 or 12, except \ which is active -% (as in normal texinfo). It is necessary to change the definition of \. - -% It's necessary to have hard CRs when the macro is executed. This is -% done by making ^^M (\endlinechar) catcode 12 when reading the macro -% body, and then making it the \newlinechar in \scanmacro. - -\def\scanctxt{% - \catcode`\"=\other - \catcode`\+=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\@=\other - \catcode`\^=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\~=\other -} - -\def\scanargctxt{% - \scanctxt - \catcode`\\=\other - \catcode`\^^M=\other -} - -\def\macrobodyctxt{% - \scanctxt - \catcode`\{=\other - \catcode`\}=\other - \catcode`\^^M=\other - \usembodybackslash -} - -\def\macroargctxt{% - \scanctxt - \catcode`\\=\other -} - -% \mbodybackslash is the definition of \ in @macro bodies. -% It maps \foo\ => \csname macarg.foo\endcsname => #N -% where N is the macro parameter number. -% We define \csname macarg.\endcsname to be \realbackslash, so -% \\ in macro replacement text gets you a backslash. - -{\catcode`@=0 @catcode`@\=@active - @gdef@usembodybackslash{@let\=@mbodybackslash} - @gdef@mbodybackslash#1\{@csname macarg.#1@endcsname} -} -\expandafter\def\csname macarg.\endcsname{\realbackslash} - -\def\macro{\recursivefalse\parsearg\macroxxx} -\def\rmacro{\recursivetrue\parsearg\macroxxx} - -\def\macroxxx#1{% - \getargs{#1}% now \macname is the macname and \argl the arglist - \ifx\argl\empty % no arguments - \paramno=0% - \else - \expandafter\parsemargdef \argl;% - \fi - \if1\csname ismacro.\the\macname\endcsname - \message{Warning: redefining \the\macname}% - \else - \expandafter\ifx\csname \the\macname\endcsname \relax - \else \errmessage{Macro name \the\macname\space already defined}\fi - \global\cslet{macsave.\the\macname}{\the\macname}% - \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% - \addtomacrolist{\the\macname}% - \fi - \begingroup \macrobodyctxt - \ifrecursive \expandafter\parsermacbody - \else \expandafter\parsemacbody - \fi} - -\parseargdef\unmacro{% - \if1\csname ismacro.#1\endcsname - \global\cslet{#1}{macsave.#1}% - \global\expandafter\let \csname ismacro.#1\endcsname=0% - % Remove the macro name from \macrolist: - \begingroup - \expandafter\let\csname#1\endcsname \relax - \let\definedummyword\unmacrodo - \xdef\macrolist{\macrolist}% - \endgroup - \else - \errmessage{Macro #1 not defined}% - \fi -} - -% Called by \do from \dounmacro on each macro. The idea is to omit any -% macro definitions that have been changed to \relax. -% -\def\unmacrodo#1{% - \ifx #1\relax - % remove this - \else - \noexpand\definedummyword \noexpand#1% - \fi -} - -% This makes use of the obscure feature that if the last token of a -% is #, then the preceding argument is delimited by -% an opening brace, and that opening brace is not consumed. -\def\getargs#1{\getargsxxx#1{}} -\def\getargsxxx#1#{\getmacname #1 \relax\getmacargs} -\def\getmacname #1 #2\relax{\macname={#1}} -\def\getmacargs#1{\def\argl{#1}} - -% Parse the optional {params} list. Set up \paramno and \paramlist -% so \defmacro knows what to do. Define \macarg.blah for each blah -% in the params list, to be ##N where N is the position in that list. -% That gets used by \mbodybackslash (above). - -% We need to get `macro parameter char #' into several definitions. -% The technique used is stolen from LaTeX: let \hash be something -% unexpandable, insert that wherever you need a #, and then redefine -% it to # just before using the token list produced. -% -% The same technique is used to protect \eatspaces till just before -% the macro is used. - -\def\parsemargdef#1;{\paramno=0\def\paramlist{}% - \let\hash\relax\let\xeatspaces\relax\parsemargdefxxx#1,;,} -\def\parsemargdefxxx#1,{% - \if#1;\let\next=\relax - \else \let\next=\parsemargdefxxx - \advance\paramno by 1% - \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname - {\xeatspaces{\hash\the\paramno}}% - \edef\paramlist{\paramlist\hash\the\paramno,}% - \fi\next} - -% These two commands read recursive and nonrecursive macro bodies. -% (They're different since rec and nonrec macros end differently.) - -\long\def\parsemacbody#1@end macro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% -\long\def\parsermacbody#1@end rmacro% -{\xdef\temp{\eatcr{#1}}\endgroup\defmacro}% - -% This defines the macro itself. There are six cases: recursive and -% nonrecursive macros of zero, one, and many arguments. -% Much magic with \expandafter here. -% \xdef is used so that macro definitions will survive the file -% they're defined in; @include reads the file inside a group. -\def\defmacro{% - \let\hash=##% convert placeholders to macro parameter chars - \ifrecursive - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\temp}}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup\noexpand\scanmacro{\temp}}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{\egroup\noexpand\scanmacro{\temp}}% - \fi - \else - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \or % 1 - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname xxx\endcsname}% - \expandafter\xdef\csname\the\macname xxx\endcsname##1{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \else % many - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup\noexpand\macroargctxt - \expandafter\noexpand\csname\the\macname xx\endcsname}% - \expandafter\xdef\csname\the\macname xx\endcsname##1{% - \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname xxx\endcsname - \paramlist{% - \egroup - \noexpand\norecurse{\the\macname}% - \noexpand\scanmacro{\temp}\egroup}% - \fi - \fi} - -\def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}} - -% \braceorline decides whether the next nonwhitespace character is a -% {. If so it reads up to the closing }, if not, it reads the whole -% line. Whatever was read is then fed to the next control sequence -% as an argument (by \parsebrace or \parsearg) -\def\braceorline#1{\let\macnamexxx=#1\futurelet\nchar\braceorlinexxx} -\def\braceorlinexxx{% - \ifx\nchar\bgroup\else - \expandafter\parsearg - \fi \macnamexxx} - - -% @alias. -% We need some trickery to remove the optional spaces around the equal -% sign. Just make them active and then expand them all to nothing. -\def\alias{\parseargusing\obeyspaces\aliasxxx} -\def\aliasxxx #1{\aliasyyy#1\relax} -\def\aliasyyy #1=#2\relax{% - {% - \expandafter\let\obeyedspace=\empty - \addtomacrolist{#1}% - \xdef\next{\global\let\makecsname{#1}=\makecsname{#2}}% - }% - \next -} - - -\message{cross references,} - -\newwrite\auxfile -\newif\ifhavexrefs % True if xref values are known. -\newif\ifwarnedxrefs % True if we warned once that they aren't known. - -% @inforef is relatively simple. -\def\inforef #1{\inforefzzz #1,,,,**} -\def\inforefzzz #1,#2,#3,#4**{\putwordSee{} \putwordInfo{} \putwordfile{} \file{\ignorespaces #3{}}, - node \samp{\ignorespaces#1{}}} - -% @node's only job in TeX is to define \lastnode, which is used in -% cross-references. The @node line might or might not have commas, and -% might or might not have spaces before the first comma, like: -% @node foo , bar , ... -% We don't want such trailing spaces in the node name. -% -\parseargdef\node{\checkenv{}\donode #1 ,\finishnodeparse} -% -% also remove a trailing comma, in case of something like this: -% @node Help-Cross, , , Cross-refs -\def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} -\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} - -\let\nwnode=\node -\let\lastnode=\empty - -% Write a cross-reference definition for the current node. #1 is the -% type (Ynumbered, Yappendix, Ynothing). -% -\def\donoderef#1{% - \ifx\lastnode\empty\else - \setref{\lastnode}{#1}% - \global\let\lastnode=\empty - \fi -} - -% @anchor{NAME} -- define xref target at arbitrary point. -% -\newcount\savesfregister -% -\def\savesf{\relax \ifhmode \savesfregister=\spacefactor \fi} -\def\restoresf{\relax \ifhmode \spacefactor=\savesfregister \fi} -\def\anchor#1{\savesf \setref{#1}{Ynothing}\restoresf \ignorespaces} - -% \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an -% anchor), which consists of three parts: -% 1) NAME-title - the current sectioning name taken from \thissection, -% or the anchor name. -% 2) NAME-snt - section number and type, passed as the SNT arg, or -% empty for anchors. -% 3) NAME-pg - the page number. -% -% This is called from \donoderef, \anchor, and \dofloat. In the case of -% floats, there is an additional part, which is not written here: -% 4) NAME-lof - the text as it should appear in a @listoffloats. -% -\def\setref#1#2{% - \pdfmkdest{#1}% - \iflinks - {% - \atdummies % preserve commands, but don't expand them - \edef\writexrdef##1##2{% - \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef - ##1}{##2}}% these are parameters of \writexrdef - }% - \toks0 = \expandafter{\thissection}% - \immediate \writexrdef{title}{\the\toks0 }% - \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. - \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, during \shipout - }% - \fi -} - -% @xref, @pxref, and @ref generate cross-references. For \xrefX, #1 is -% the node name, #2 the name of the Info cross-reference, #3 the printed -% node name, #4 the name of the Info file, #5 the name of the printed -% manual. All but the node name can be omitted. -% -\def\pxref#1{\putwordsee{} \xrefX[#1,,,,,,,]} -\def\xref#1{\putwordSee{} \xrefX[#1,,,,,,,]} -\def\ref#1{\xrefX[#1,,,,,,,]} -\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup - \unsepspaces - \def\printedmanual{\ignorespaces #5}% - \def\printedrefname{\ignorespaces #3}% - \setbox1=\hbox{\printedmanual\unskip}% - \setbox0=\hbox{\printedrefname\unskip}% - \ifdim \wd0 = 0pt - % No printed node name was explicitly given. - \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax - % Use the node name inside the square brackets. - \def\printedrefname{\ignorespaces #1}% - \else - % Use the actual chapter/section title appear inside - % the square brackets. Use the real section title if we have it. - \ifdim \wd1 > 0pt - % It is in another manual, so we don't have it. - \def\printedrefname{\ignorespaces #1}% - \else - \ifhavexrefs - % We know the real title if we have the xref values. - \def\printedrefname{\refx{#1-title}{}}% - \else - % Otherwise just copy the Info node name. - \def\printedrefname{\ignorespaces #1}% - \fi% - \fi - \fi - \fi - % - % Make link in pdf output. - \ifpdf - \leavevmode - \getfilename{#4}% - {\indexnofonts - \turnoffactive - % See comments at \activebackslashdouble. - {\activebackslashdouble \xdef\pdfxrefdest{#1}% - \backslashparens\pdfxrefdest}% - % - \ifnum\filenamelength>0 - \startlink attr{/Border [0 0 0]}% - goto file{\the\filename.pdf} name{\pdfxrefdest}% - \else - \startlink attr{/Border [0 0 0]}% - goto name{\pdfmkpgn{\pdfxrefdest}}% - \fi - }% - \linkcolor - \fi - % - % Float references are printed completely differently: "Figure 1.2" - % instead of "[somenode], p.3". We distinguish them by the - % LABEL-title being set to a magic string. - {% - % Have to otherify everything special to allow the \csname to - % include an _ in the xref name, etc. - \indexnofonts - \turnoffactive - \expandafter\global\expandafter\let\expandafter\Xthisreftitle - \csname XR#1-title\endcsname - }% - \iffloat\Xthisreftitle - % If the user specified the print name (third arg) to the ref, - % print it instead of our usual "Figure 1.2". - \ifdim\wd0 = 0pt - \refx{#1-snt}{}% - \else - \printedrefname - \fi - % - % if the user also gave the printed manual name (fifth arg), append - % "in MANUALNAME". - \ifdim \wd1 > 0pt - \space \putwordin{} \cite{\printedmanual}% - \fi - \else - % node/anchor (non-float) references. - % - % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not - % insert empty discretionaries after hyphens, which means that it will - % not find a line break at a hyphen in a node names. Since some manuals - % are best written with fairly long node names, containing hyphens, this - % is a loss. Therefore, we give the text of the node name again, so it - % is as if TeX is seeing it for the first time. - \ifdim \wd1 > 0pt - \putwordsection{} ``\printedrefname'' \putwordin{} \cite{\printedmanual}% - \else - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% - \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi - }% - % output the `[mynode]' via a macro so it can be overridden. - \xrefprintnodename\printedrefname - % - % But we always want a comma and a space: - ,\space - % - % output the `page 3'. - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% - \fi - \fi - \endlink -\endgroup} - -% This macro is called from \xrefX for the `[nodename]' part of xref -% output. It's a separate macro only so it can be changed more easily, -% since square brackets don't work well in some documents. Particularly -% one that Bob is working on :). -% -\def\xrefprintnodename#1{[#1]} - -% Things referred to by \setref. -% -\def\Ynothing{} -\def\Yomitfromtoc{} -\def\Ynumbered{% - \ifnum\secno=0 - \putwordChapter@tie \the\chapno - \else \ifnum\subsecno=0 - \putwordSection@tie \the\chapno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno - \else - \putwordSection@tie \the\chapno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} -\def\Yappendix{% - \ifnum\secno=0 - \putwordAppendix@tie @char\the\appendixno{}% - \else \ifnum\subsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno - \else \ifnum\subsubsecno=0 - \putwordSection@tie @char\the\appendixno.\the\secno.\the\subsecno - \else - \putwordSection@tie - @char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno - \fi\fi\fi -} - -% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. -% If its value is nonempty, SUFFIX is output afterward. -% -\def\refx#1#2{% - {% - \indexnofonts - \otherbackslash - \expandafter\global\expandafter\let\expandafter\thisrefX - \csname XR#1\endcsname - }% - \ifx\thisrefX\relax - % If not defined, say something at least. - \angleleft un\-de\-fined\angleright - \iflinks - \ifhavexrefs - \message{\linenumber Undefined cross reference `#1'.}% - \else - \ifwarnedxrefs\else - \global\warnedxrefstrue - \message{Cross reference values unknown; you must run TeX again.}% - \fi - \fi - \fi - \else - % It's defined, so just use it. - \thisrefX - \fi - #2% Output the suffix in any case. -} - -% This is the macro invoked by entries in the aux file. Usually it's -% just a \def (we prepend XR to the control sequence name to avoid -% collisions). But if this is a float type, we have more work to do. -% -\def\xrdef#1#2{% - {% The node name might contain 8-bit characters, which in our current - % implementation are changed to commands like @'e. Don't let these - % mess up the control sequence name. - \indexnofonts - \turnoffactive - \xdef\safexrefname{#1}% - }% - % - \expandafter\gdef\csname XR\safexrefname\endcsname{#2}% remember this xref - % - % Was that xref control sequence that we just defined for a float? - \expandafter\iffloat\csname XR\safexrefname\endcsname - % it was a float, and we have the (safe) float type in \iffloattype. - \expandafter\let\expandafter\floatlist - \csname floatlist\iffloattype\endcsname - % - % Is this the first time we've seen this float type? - \expandafter\ifx\floatlist\relax - \toks0 = {\do}% yes, so just \do - \else - % had it before, so preserve previous elements in list. - \toks0 = \expandafter{\floatlist\do}% - \fi - % - % Remember this xref in the control sequence \floatlistFLOATTYPE, - % for later use in \listoffloats. - \expandafter\xdef\csname floatlist\iffloattype\endcsname{\the\toks0 - {\safexrefname}}% - \fi -} - -% Read the last existing aux file, if any. No error if none exists. -% -\def\tryauxfile{% - \openin 1 \jobname.aux - \ifeof 1 \else - \readdatafile{aux}% - \global\havexrefstrue - \fi - \closein 1 -} - -\def\setupdatafile{% - \catcode`\^^@=\other - \catcode`\^^A=\other - \catcode`\^^B=\other - \catcode`\^^C=\other - \catcode`\^^D=\other - \catcode`\^^E=\other - \catcode`\^^F=\other - \catcode`\^^G=\other - \catcode`\^^H=\other - \catcode`\^^K=\other - \catcode`\^^L=\other - \catcode`\^^N=\other - \catcode`\^^P=\other - \catcode`\^^Q=\other - \catcode`\^^R=\other - \catcode`\^^S=\other - \catcode`\^^T=\other - \catcode`\^^U=\other - \catcode`\^^V=\other - \catcode`\^^W=\other - \catcode`\^^X=\other - \catcode`\^^Z=\other - \catcode`\^^[=\other - \catcode`\^^\=\other - \catcode`\^^]=\other - \catcode`\^^^=\other - \catcode`\^^_=\other - % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. - % in xref tags, i.e., node names. But since ^^e4 notation isn't - % supported in the main text, it doesn't seem desirable. Furthermore, - % that is not enough: for node names that actually contain a ^ - % character, we would end up writing a line like this: 'xrdef {'hat - % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first - % argument, and \hat is not an expandable control sequence. It could - % all be worked out, but why? Either we support ^^ or we don't. - % - % The other change necessary for this was to define \auxhat: - % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter - % and then to call \auxhat in \setq. - % - \catcode`\^=\other - % - % Special characters. Should be turned off anyway, but... - \catcode`\~=\other - \catcode`\[=\other - \catcode`\]=\other - \catcode`\"=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\<=\other - \catcode`\>=\other - \catcode`\$=\other - \catcode`\#=\other - \catcode`\&=\other - \catcode`\%=\other - \catcode`+=\other % avoid \+ for paranoia even though we've turned it off - % - % This is to support \ in node names and titles, since the \ - % characters end up in a \csname. It's easier than - % leaving it active and making its active definition an actual \ - % character. What I don't understand is why it works in the *value* - % of the xrdef. Seems like it should be a catcode12 \, and that - % should not typeset properly. But it works, so I'm moving on for - % now. --karl, 15jan04. - \catcode`\\=\other - % - % Make the characters 128-255 be printing characters. - {% - \count1=128 - \def\loop{% - \catcode\count1=\other - \advance\count1 by 1 - \ifnum \count1<256 \loop \fi - }% - }% - % - % @ is our escape character in .aux files, and we need braces. - \catcode`\{=1 - \catcode`\}=2 - \catcode`\@=0 -} - -\def\readdatafile#1{% -\begingroup - \setupdatafile - \input\jobname.#1 -\endgroup} - - -\message{insertions,} -% including footnotes. - -\newcount \footnoteno - -% The trailing space in the following definition for supereject is -% vital for proper filling; pages come out unaligned when you do a -% pagealignmacro call if that space before the closing brace is -% removed. (Generally, numeric constants should always be followed by a -% space to prevent strange expansion errors.) -\def\supereject{\par\penalty -20000\footnoteno =0 } - -% @footnotestyle is meaningful for info output only. -\let\footnotestyle=\comment - -{\catcode `\@=11 -% -% Auto-number footnotes. Otherwise like plain. -\gdef\footnote{% - \let\indent=\ptexindent - \let\noindent=\ptexnoindent - \global\advance\footnoteno by \@ne - \edef\thisfootno{$^{\the\footnoteno}$}% - % - % In case the footnote comes at the end of a sentence, preserve the - % extra spacing after we do the footnote number. - \let\@sf\empty - \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\ptexslash\fi - % - % Remove inadvertent blank space before typesetting the footnote number. - \unskip - \thisfootno\@sf - \dofootnote -}% - -% Don't bother with the trickery in plain.tex to not require the -% footnote text as a parameter. Our footnotes don't need to be so general. -% -% Oh yes, they do; otherwise, @ifset (and anything else that uses -% \parseargline) fails inside footnotes because the tokens are fixed when -% the footnote is read. --karl, 16nov96. -% -\gdef\dofootnote{% - \insert\footins\bgroup - % We want to typeset this text as a normal paragraph, even if the - % footnote reference occurs in (for example) a display environment. - % So reset some parameters. - \hsize=\pagewidth - \interlinepenalty\interfootnotelinepenalty - \splittopskip\ht\strutbox % top baseline for broken footnotes - \splitmaxdepth\dp\strutbox - \floatingpenalty\@MM - \leftskip\z@skip - \rightskip\z@skip - \spaceskip\z@skip - \xspaceskip\z@skip - \parindent\defaultparindent - % - \smallfonts \rm - % - % Because we use hanging indentation in footnotes, a @noindent appears - % to exdent this text, so make it be a no-op. makeinfo does not use - % hanging indentation so @noindent can still be needed within footnote - % text after an @example or the like (not that this is good style). - \let\noindent = \relax - % - % Hang the footnote text off the number. Use \everypar in case the - % footnote extends for more than one paragraph. - \everypar = {\hang}% - \textindent{\thisfootno}% - % - % Don't crash into the line above the footnote text. Since this - % expands into a box, it must come within the paragraph, lest it - % provide a place where TeX can split the footnote. - \footstrut - \futurelet\next\fo@t -} -}%end \catcode `\@=11 - -% In case a @footnote appears in a vbox, save the footnote text and create -% the real \insert just after the vbox finished. Otherwise, the insertion -% would be lost. -% Similarily, if a @footnote appears inside an alignment, save the footnote -% text to a box and make the \insert when a row of the table is finished. -% And the same can be done for other insert classes. --kasal, 16nov03. - -% Replace the \insert primitive by a cheating macro. -% Deeper inside, just make sure that the saved insertions are not spilled -% out prematurely. -% -\def\startsavinginserts{% - \ifx \insert\ptexinsert - \let\insert\saveinsert - \else - \let\checkinserts\relax - \fi -} - -% This \insert replacement works for both \insert\footins{foo} and -% \insert\footins\bgroup foo\egroup, but it doesn't work for \insert27{foo}. -% -\def\saveinsert#1{% - \edef\next{\noexpand\savetobox \makeSAVEname#1}% - \afterassignment\next - % swallow the left brace - \let\temp = -} -\def\makeSAVEname#1{\makecsname{SAVE\expandafter\gobble\string#1}} -\def\savetobox#1{\global\setbox#1 = \vbox\bgroup \unvbox#1} - -\def\checksaveins#1{\ifvoid#1\else \placesaveins#1\fi} - -\def\placesaveins#1{% - \ptexinsert \csname\expandafter\gobblesave\string#1\endcsname - {\box#1}% -} - -% eat @SAVE -- beware, all of them have catcode \other: -{ - \def\dospecials{\do S\do A\do V\do E} \uncatcodespecials % ;-) - \gdef\gobblesave @SAVE{} -} - -% initialization: -\def\newsaveins #1{% - \edef\next{\noexpand\newsaveinsX \makeSAVEname#1}% - \next -} -\def\newsaveinsX #1{% - \csname newbox\endcsname #1% - \expandafter\def\expandafter\checkinserts\expandafter{\checkinserts - \checksaveins #1}% -} - -% initialize: -\let\checkinserts\empty -\newsaveins\footins -\newsaveins\margin - - -% @image. We use the macros from epsf.tex to support this. -% If epsf.tex is not installed and @image is used, we complain. -% -% Check for and read epsf.tex up front. If we read it only at @image -% time, we might be inside a group, and then its definitions would get -% undone and the next image would fail. -\openin 1 = epsf.tex -\ifeof 1 \else - % Do not bother showing banner with epsf.tex v2.7k (available in - % doc/epsf.tex and on ctan). - \def\epsfannounce{\toks0 = }% - \input epsf.tex -\fi -\closein 1 -% -% We will only complain once about lack of epsf.tex. -\newif\ifwarnednoepsf -\newhelp\noepsfhelp{epsf.tex must be installed for images to - work. It is also included in the Texinfo distribution, or you can get - it from ftp://tug.org/tex/epsf.tex.} -% -\def\image#1{% - \ifx\epsfbox\undefined - \ifwarnednoepsf \else - \errhelp = \noepsfhelp - \errmessage{epsf.tex not found, images will be ignored}% - \global\warnednoepsftrue - \fi - \else - \imagexxx #1,,,,,\finish - \fi -} -% -% Arguments to @image: -% #1 is (mandatory) image filename; we tack on .eps extension. -% #2 is (optional) width, #3 is (optional) height. -% #4 is (ignored optional) html alt text. -% #5 is (ignored optional) extension. -% #6 is just the usual extra ignored arg for parsing this stuff. -\newif\ifimagevmode -\def\imagexxx#1,#2,#3,#4,#5,#6\finish{\begingroup - \catcode`\^^M = 5 % in case we're inside an example - \normalturnoffactive % allow _ et al. in names - % If the image is by itself, center it. - \ifvmode - \imagevmodetrue - \nobreak\bigskip - % Usually we'll have text after the image which will insert - % \parskip glue, so insert it here too to equalize the space - % above and below. - \nobreak\vskip\parskip - \nobreak - \line\bgroup - \fi - % - % Output the image. - \ifpdf - \dopdfimage{#1}{#2}{#3}% - \else - % \epsfbox itself resets \epsf?size at each figure. - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \epsfxsize=#2\relax \fi - \setbox0 = \hbox{\ignorespaces #3}\ifdim\wd0 > 0pt \epsfysize=#3\relax \fi - \epsfbox{#1.eps}% - \fi - % - \ifimagevmode \egroup \bigbreak \fi % space after the image -\endgroup} - - -% @float FLOATTYPE,LABEL,LOC ... @end float for displayed figures, tables, -% etc. We don't actually implement floating yet, we always include the -% float "here". But it seemed the best name for the future. -% -\envparseargdef\float{\eatcommaspace\eatcommaspace\dofloat#1, , ,\finish} - -% There may be a space before second and/or third parameter; delete it. -\def\eatcommaspace#1, {#1,} - -% #1 is the optional FLOATTYPE, the text label for this float, typically -% "Figure", "Table", "Example", etc. Can't contain commas. If omitted, -% this float will not be numbered and cannot be referred to. -% -% #2 is the optional xref label. Also must be present for the float to -% be referable. -% -% #3 is the optional positioning argument; for now, it is ignored. It -% will somehow specify the positions allowed to float to (here, top, bottom). -% -% We keep a separate counter for each FLOATTYPE, which we reset at each -% chapter-level command. -\let\resetallfloatnos=\empty -% -\def\dofloat#1,#2,#3,#4\finish{% - \let\thiscaption=\empty - \let\thisshortcaption=\empty - % - % don't lose footnotes inside @float. - % - % BEWARE: when the floats start float, we have to issue warning whenever an - % insert appears inside a float which could possibly float. --kasal, 26may04 - % - \startsavinginserts - % - % We can't be used inside a paragraph. - \par - % - \vtop\bgroup - \def\floattype{#1}% - \def\floatlabel{#2}% - \def\floatloc{#3}% we do nothing with this yet. - % - \ifx\floattype\empty - \let\safefloattype=\empty - \else - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - \fi - % - % If label is given but no type, we handle that as the empty type. - \ifx\floatlabel\empty \else - % We want each FLOATTYPE to be numbered separately (Figure 1, - % Table 1, Figure 2, ...). (And if no label, no number.) - % - \expandafter\getfloatno\csname\safefloattype floatno\endcsname - \global\advance\floatno by 1 - % - {% - % This magic value for \thissection is output by \setref as the - % XREFLABEL-title value. \xrefX uses it to distinguish float - % labels (which have a completely different output format) from - % node and anchor labels. And \xrdef uses it to construct the - % lists of floats. - % - \edef\thissection{\floatmagic=\safefloattype}% - \setref{\floatlabel}{Yfloat}% - }% - \fi - % - % start with \parskip glue, I guess. - \vskip\parskip - % - % Don't suppress indentation if a float happens to start a section. - \restorefirstparagraphindent -} - -% we have these possibilities: -% @float Foo,lbl & @caption{Cap}: Foo 1.1: Cap -% @float Foo,lbl & no caption: Foo 1.1 -% @float Foo & @caption{Cap}: Foo: Cap -% @float Foo & no caption: Foo -% @float ,lbl & Caption{Cap}: 1.1: Cap -% @float ,lbl & no caption: 1.1 -% @float & @caption{Cap}: Cap -% @float & no caption: -% -\def\Efloat{% - \let\floatident = \empty - % - % In all cases, if we have a float type, it comes first. - \ifx\floattype\empty \else \def\floatident{\floattype}\fi - % - % If we have an xref label, the number comes next. - \ifx\floatlabel\empty \else - \ifx\floattype\empty \else % if also had float type, need tie first. - \appendtomacro\floatident{\tie}% - \fi - % the number. - \appendtomacro\floatident{\chaplevelprefix\the\floatno}% - \fi - % - % Start the printed caption with what we've constructed in - % \floatident, but keep it separate; we need \floatident again. - \let\captionline = \floatident - % - \ifx\thiscaption\empty \else - \ifx\floatident\empty \else - \appendtomacro\captionline{: }% had ident, so need a colon between - \fi - % - % caption text. - \appendtomacro\captionline{\scanexp\thiscaption}% - \fi - % - % If we have anything to print, print it, with space before. - % Eventually this needs to become an \insert. - \ifx\captionline\empty \else - \vskip.5\parskip - \captionline - % - % Space below caption. - \vskip\parskip - \fi - % - % If have an xref label, write the list of floats info. Do this - % after the caption, to avoid chance of it being a breakpoint. - \ifx\floatlabel\empty \else - % Write the text that goes in the lof to the aux file as - % \floatlabel-lof. Besides \floatident, we include the short - % caption if specified, else the full caption if specified, else nothing. - {% - \atdummies - % - % since we read the caption text in the macro world, where ^^M - % is turned into a normal character, we have to scan it back, so - % we don't write the literal three characters "^^M" into the aux file. - \scanexp{% - \xdef\noexpand\gtemp{% - \ifx\thisshortcaption\empty - \thiscaption - \else - \thisshortcaption - \fi - }% - }% - \immediate\write\auxfile{@xrdef{\floatlabel-lof}{\floatident - \ifx\gtemp\empty \else : \gtemp \fi}}% - }% - \fi - \egroup % end of \vtop - % - % place the captured inserts - % - % BEWARE: when the floats start floating, we have to issue warning - % whenever an insert appears inside a float which could possibly - % float. --kasal, 26may04 - % - \checkinserts -} - -% Append the tokens #2 to the definition of macro #1, not expanding either. -% -\def\appendtomacro#1#2{% - \expandafter\def\expandafter#1\expandafter{#1#2}% -} - -% @caption, @shortcaption -% -\def\caption{\docaption\thiscaption} -\def\shortcaption{\docaption\thisshortcaption} -\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} -\def\defcaption#1#2{\egroup \def#1{#2}} - -% The parameter is the control sequence identifying the counter we are -% going to use. Create it if it doesn't exist and assign it to \floatno. -\def\getfloatno#1{% - \ifx#1\relax - % Haven't seen this figure type before. - \csname newcount\endcsname #1% - % - % Remember to reset this floatno at the next chap. - \expandafter\gdef\expandafter\resetallfloatnos - \expandafter{\resetallfloatnos #1=0 }% - \fi - \let\floatno#1% -} - -% \setref calls this to get the XREFLABEL-snt value. We want an @xref -% to the FLOATLABEL to expand to "Figure 3.1". We call \setref when we -% first read the @float command. -% -\def\Yfloat{\floattype@tie \chaplevelprefix\the\floatno}% - -% Magic string used for the XREFLABEL-title value, so \xrefX can -% distinguish floats from other xref types. -\def\floatmagic{!!float!!} - -% #1 is the control sequence we are passed; we expand into a conditional -% which is true if #1 represents a float ref. That is, the magic -% \thissection value which we \setref above. -% -\def\iffloat#1{\expandafter\doiffloat#1==\finish} -% -% #1 is (maybe) the \floatmagic string. If so, #2 will be the -% (safe) float type for this float. We set \iffloattype to #2. -% -\def\doiffloat#1=#2=#3\finish{% - \def\temp{#1}% - \def\iffloattype{#2}% - \ifx\temp\floatmagic -} - -% @listoffloats FLOATTYPE - print a list of floats like a table of contents. -% -\parseargdef\listoffloats{% - \def\floattype{#1}% floattype - {% - % the floattype might have accents or other special characters, - % but we need to use it in a control sequence name. - \indexnofonts - \turnoffactive - \xdef\safefloattype{\floattype}% - }% - % - % \xrdef saves the floats as a \do-list in \floatlistSAFEFLOATTYPE. - \expandafter\ifx\csname floatlist\safefloattype\endcsname \relax - \ifhavexrefs - % if the user said @listoffloats foo but never @float foo. - \message{\linenumber No `\safefloattype' floats to list.}% - \fi - \else - \begingroup - \leftskip=\tocindent % indent these entries like a toc - \let\do=\listoffloatsdo - \csname floatlist\safefloattype\endcsname - \endgroup - \fi -} - -% This is called on each entry in a list of floats. We're passed the -% xref label, in the form LABEL-title, which is how we save it in the -% aux file. We strip off the -title and look up \XRLABEL-lof, which -% has the text we're supposed to typeset here. -% -% Figures without xref labels will not be included in the list (since -% they won't appear in the aux file). -% -\def\listoffloatsdo#1{\listoffloatsdoentry#1\finish} -\def\listoffloatsdoentry#1-title\finish{{% - % Can't fully expand XR#1-lof because it can contain anything. Just - % pass the control sequence. On the other hand, XR#1-pg is just the - % page number, and we want to fully expand that so we can get a link - % in pdf output. - \toksA = \expandafter{\csname XR#1-lof\endcsname}% - % - % use the same \entry macro we use to generate the TOC and index. - \edef\writeentry{\noexpand\entry{\the\toksA}{\csname XR#1-pg\endcsname}}% - \writeentry -}} - - -\message{localization,} - -% @documentlanguage is usually given very early, just after -% @setfilename. If done too late, it may not override everything -% properly. Single argument is the language (de) or locale (de_DE) -% abbreviation. It would be nice if we could set up a hyphenation file. -% -{ - \catcode`\_ = \active - \globaldefs=1 -\parseargdef\documentlanguage{\begingroup - \let_=\normalunderscore % normal _ character for filenames - \tex % read txi-??.tex file in plain TeX. - % Read the file by the name they passed if it exists. - \openin 1 txi-#1.tex - \ifeof 1 - \documentlanguagetrywithoutunderscore{#1_\finish}% - \else - \input txi-#1.tex - \fi - \closein 1 - \endgroup -\endgroup} -} -% -% If they passed de_DE, and txi-de_DE.tex doesn't exist, -% try txi-de.tex. -% -\def\documentlanguagetrywithoutunderscore#1_#2\finish{% - \openin 1 txi-#1.tex - \ifeof 1 - \errhelp = \nolanghelp - \errmessage{Cannot read language file txi-#1.tex}% - \else - \input txi-#1.tex - \fi - \closein 1 -} -% -\newhelp\nolanghelp{The given language definition file cannot be found or -is empty. Maybe you need to install it? In the current directory -should work if nowhere else does.} - -% Set the catcode of characters 128 through 255 to the specified number. -% -\def\setnonasciicharscatcode#1{% - \count255=128 - \loop\ifnum\count255<256 - \global\catcode\count255=#1 - \advance\count255 by 1 - \repeat -} - -% @documentencoding sets the definition of non-ASCII characters -% according to the specified encoding. -% -\parseargdef\documentencoding{% - % Encoding being declared for the document. - \def\declaredencoding{\csname #1.enc\endcsname}% - % - % Supported encodings: names converted to tokens in order to be able - % to compare them with \ifx. - \def\ascii{\csname US-ASCII.enc\endcsname}% - \def\latnine{\csname ISO-8859-15.enc\endcsname}% - \def\latone{\csname ISO-8859-1.enc\endcsname}% - \def\lattwo{\csname ISO-8859-2.enc\endcsname}% - \def\utfeight{\csname UTF-8.enc\endcsname}% - % - \ifx \declaredencoding \ascii - \asciichardefs - % - \else \ifx \declaredencoding \lattwo - \setnonasciicharscatcode\active - \lattwochardefs - % - \else \ifx \declaredencoding \latone - \setnonasciicharscatcode\active - \latonechardefs - % - \else \ifx \declaredencoding \latnine - \setnonasciicharscatcode\active - \latninechardefs - % - \else \ifx \declaredencoding \utfeight - \setnonasciicharscatcode\active - \utfeightchardefs - % - \else - \message{Unknown document encoding #1, ignoring.}% - % - \fi % utfeight - \fi % latnine - \fi % latone - \fi % lattwo - \fi % ascii -} - -% A message to be logged when using a character that isn't available -% the default font encoding (OT1). -% -\def\missingcharmsg#1{\message{Character missing in OT1 encoding: #1.}} - -% Take account of \c (plain) vs. \, (Texinfo) difference. -\def\cedilla#1{\ifx\c\ptexc\c{#1}\else\,{#1}\fi} - -% First, make active non-ASCII characters in order for them to be -% correctly categorized when TeX reads the replacement text of -% macros containing the character definitions. -\setnonasciicharscatcode\active -% -% Latin1 (ISO-8859-1) character definitions. -\def\latonechardefs{% - \gdef^^a0{~} - \gdef^^a1{\exclamdown} - \gdef^^a2{\missingcharmsg{CENT SIGN}} - \gdef^^a3{{\pounds}} - \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} - \gdef^^a5{\missingcharmsg{YEN SIGN}} - \gdef^^a6{\missingcharmsg{BROKEN BAR}} - \gdef^^a7{\S} - \gdef^^a8{\"{}} - \gdef^^a9{\copyright} - \gdef^^aa{\ordf} - \gdef^^ab{\missingcharmsg{LEFT-POINTING DOUBLE ANGLE QUOTATION MARK}} - \gdef^^ac{$\lnot$} - \gdef^^ad{\-} - \gdef^^ae{\registeredsymbol} - \gdef^^af{\={}} - % - \gdef^^b0{\textdegree} - \gdef^^b1{$\pm$} - \gdef^^b2{$^2$} - \gdef^^b3{$^3$} - \gdef^^b4{\'{}} - \gdef^^b5{$\mu$} - \gdef^^b6{\P} - % - \gdef^^b7{$^.$} - \gdef^^b8{\cedilla\ } - \gdef^^b9{$^1$} - \gdef^^ba{\ordm} - % - \gdef^^bb{\missingcharmsg{RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK}} - \gdef^^bc{$1\over4$} - \gdef^^bd{$1\over2$} - \gdef^^be{$3\over4$} - \gdef^^bf{\questiondown} - % - \gdef^^c0{\`A} - \gdef^^c1{\'A} - \gdef^^c2{\^A} - \gdef^^c3{\~A} - \gdef^^c4{\"A} - \gdef^^c5{\ringaccent A} - \gdef^^c6{\AE} - \gdef^^c7{\cedilla C} - \gdef^^c8{\`E} - \gdef^^c9{\'E} - \gdef^^ca{\^E} - \gdef^^cb{\"E} - \gdef^^cc{\`I} - \gdef^^cd{\'I} - \gdef^^ce{\^I} - \gdef^^cf{\"I} - % - \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER ETH}} - \gdef^^d1{\~N} - \gdef^^d2{\`O} - \gdef^^d3{\'O} - \gdef^^d4{\^O} - \gdef^^d5{\~O} - \gdef^^d6{\"O} - \gdef^^d7{$\times$} - \gdef^^d8{\O} - \gdef^^d9{\`U} - \gdef^^da{\'U} - \gdef^^db{\^U} - \gdef^^dc{\"U} - \gdef^^dd{\'Y} - \gdef^^de{\missingcharmsg{LATIN CAPITAL LETTER THORN}} - \gdef^^df{\ss} - % - \gdef^^e0{\`a} - \gdef^^e1{\'a} - \gdef^^e2{\^a} - \gdef^^e3{\~a} - \gdef^^e4{\"a} - \gdef^^e5{\ringaccent a} - \gdef^^e6{\ae} - \gdef^^e7{\cedilla c} - \gdef^^e8{\`e} - \gdef^^e9{\'e} - \gdef^^ea{\^e} - \gdef^^eb{\"e} - \gdef^^ec{\`{\dotless i}} - \gdef^^ed{\'{\dotless i}} - \gdef^^ee{\^{\dotless i}} - \gdef^^ef{\"{\dotless i}} - % - \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER ETH}} - \gdef^^f1{\~n} - \gdef^^f2{\`o} - \gdef^^f3{\'o} - \gdef^^f4{\^o} - \gdef^^f5{\~o} - \gdef^^f6{\"o} - \gdef^^f7{$\div$} - \gdef^^f8{\o} - \gdef^^f9{\`u} - \gdef^^fa{\'u} - \gdef^^fb{\^u} - \gdef^^fc{\"u} - \gdef^^fd{\'y} - \gdef^^fe{\missingcharmsg{LATIN SMALL LETTER THORN}} - \gdef^^ff{\"y} -} - -% Latin9 (ISO-8859-15) encoding character definitions. -\def\latninechardefs{% - % Encoding is almost identical to Latin1. - \latonechardefs - % - \gdef^^a4{\euro} - \gdef^^a6{\v S} - \gdef^^a8{\v s} - \gdef^^b4{\v Z} - \gdef^^b8{\v z} - \gdef^^bc{\OE} - \gdef^^bd{\oe} - \gdef^^be{\"Y} -} - -% Latin2 (ISO-8859-2) character definitions. -\def\lattwochardefs{% - \gdef^^a0{~} - \gdef^^a1{\missingcharmsg{LATIN CAPITAL LETTER A WITH OGONEK}} - \gdef^^a2{\u{}} - \gdef^^a3{\L} - \gdef^^a4{\missingcharmsg{CURRENCY SIGN}} - \gdef^^a5{\v L} - \gdef^^a6{\'S} - \gdef^^a7{\S} - \gdef^^a8{\"{}} - \gdef^^a9{\v S} - \gdef^^aa{\cedilla S} - \gdef^^ab{\v T} - \gdef^^ac{\'Z} - \gdef^^ad{\-} - \gdef^^ae{\v Z} - \gdef^^af{\dotaccent Z} - % - \gdef^^b0{\textdegree} - \gdef^^b1{\missingcharmsg{LATIN SMALL LETTER A WITH OGONEK}} - \gdef^^b2{\missingcharmsg{OGONEK}} - \gdef^^b3{\l} - \gdef^^b4{\'{}} - \gdef^^b5{\v l} - \gdef^^b6{\'s} - \gdef^^b7{\v{}} - \gdef^^b8{\cedilla\ } - \gdef^^b9{\v s} - \gdef^^ba{\cedilla s} - \gdef^^bb{\v t} - \gdef^^bc{\'z} - \gdef^^bd{\H{}} - \gdef^^be{\v z} - \gdef^^bf{\dotaccent z} - % - \gdef^^c0{\'R} - \gdef^^c1{\'A} - \gdef^^c2{\^A} - \gdef^^c3{\u A} - \gdef^^c4{\"A} - \gdef^^c5{\'L} - \gdef^^c6{\'C} - \gdef^^c7{\cedilla C} - \gdef^^c8{\v C} - \gdef^^c9{\'E} - \gdef^^ca{\missingcharmsg{LATIN CAPITAL LETTER E WITH OGONEK}} - \gdef^^cb{\"E} - \gdef^^cc{\v E} - \gdef^^cd{\'I} - \gdef^^ce{\^I} - \gdef^^cf{\v D} - % - \gdef^^d0{\missingcharmsg{LATIN CAPITAL LETTER D WITH STROKE}} - \gdef^^d1{\'N} - \gdef^^d2{\v N} - \gdef^^d3{\'O} - \gdef^^d4{\^O} - \gdef^^d5{\H O} - \gdef^^d6{\"O} - \gdef^^d7{$\times$} - \gdef^^d8{\v R} - \gdef^^d9{\ringaccent U} - \gdef^^da{\'U} - \gdef^^db{\H U} - \gdef^^dc{\"U} - \gdef^^dd{\'Y} - \gdef^^de{\cedilla T} - \gdef^^df{\ss} - % - \gdef^^e0{\'r} - \gdef^^e1{\'a} - \gdef^^e2{\^a} - \gdef^^e3{\u a} - \gdef^^e4{\"a} - \gdef^^e5{\'l} - \gdef^^e6{\'c} - \gdef^^e7{\cedilla c} - \gdef^^e8{\v c} - \gdef^^e9{\'e} - \gdef^^ea{\missingcharmsg{LATIN SMALL LETTER E WITH OGONEK}} - \gdef^^eb{\"e} - \gdef^^ec{\v e} - \gdef^^ed{\'\i} - \gdef^^ee{\^\i} - \gdef^^ef{\v d} - % - \gdef^^f0{\missingcharmsg{LATIN SMALL LETTER D WITH STROKE}} - \gdef^^f1{\'n} - \gdef^^f2{\v n} - \gdef^^f3{\'o} - \gdef^^f4{\^o} - \gdef^^f5{\H o} - \gdef^^f6{\"o} - \gdef^^f7{$\div$} - \gdef^^f8{\v r} - \gdef^^f9{\ringaccent u} - \gdef^^fa{\'u} - \gdef^^fb{\H u} - \gdef^^fc{\"u} - \gdef^^fd{\'y} - \gdef^^fe{\cedilla t} - \gdef^^ff{\dotaccent{}} -} - -% UTF-8 character definitions. -% -% This code to support UTF-8 is based on LaTeX's utf8.def, with some -% changes for Texinfo conventions. It is included here under the GPL by -% permission from Frank Mittelbach and the LaTeX team. -% -\newcount\countUTFx -\newcount\countUTFy -\newcount\countUTFz - -\gdef\UTFviiiTwoOctets#1#2{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\endcsname} -% -\gdef\UTFviiiThreeOctets#1#2#3{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\string #3\endcsname} -% -\gdef\UTFviiiFourOctets#1#2#3#4{\expandafter - \UTFviiiDefined\csname u8:#1\string #2\string #3\string #4\endcsname} - -\gdef\UTFviiiDefined#1{% - \ifx #1\relax - \message{\linenumber Unicode char \string #1 not defined for Texinfo}% - \else - \expandafter #1% - \fi -} - -\begingroup - \catcode`\~13 - \catcode`\"12 - - \def\UTFviiiLoop{% - \global\catcode\countUTFx\active - \uccode`\~\countUTFx - \uppercase\expandafter{\UTFviiiTmp}% - \advance\countUTFx by 1 - \ifnum\countUTFx < \countUTFy - \expandafter\UTFviiiLoop - \fi} - - \countUTFx = "C2 - \countUTFy = "E0 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiTwoOctets\string~}} - \UTFviiiLoop - - \countUTFx = "E0 - \countUTFy = "F0 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiThreeOctets\string~}} - \UTFviiiLoop - - \countUTFx = "F0 - \countUTFy = "F4 - \def\UTFviiiTmp{% - \xdef~{\noexpand\UTFviiiFourOctets\string~}} - \UTFviiiLoop -\endgroup - -\begingroup - \catcode`\"=12 - \catcode`\<=12 - \catcode`\.=12 - \catcode`\,=12 - \catcode`\;=12 - \catcode`\!=12 - \catcode`\~=13 - - \gdef\DeclareUnicodeCharacter#1#2{% - \countUTFz = "#1\relax - \wlog{\space\space defining Unicode char U+#1 (decimal \the\countUTFz)}% - \begingroup - \parseXMLCharref - \def\UTFviiiTwoOctets##1##2{% - \csname u8:##1\string ##2\endcsname}% - \def\UTFviiiThreeOctets##1##2##3{% - \csname u8:##1\string ##2\string ##3\endcsname}% - \def\UTFviiiFourOctets##1##2##3##4{% - \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% - \expandafter\expandafter\expandafter\expandafter - \expandafter\expandafter\expandafter - \gdef\UTFviiiTmp{#2}% - \endgroup} - - \gdef\parseXMLCharref{% - \ifnum\countUTFz < "A0\relax - \errhelp = \EMsimple - \errmessage{Cannot define Unicode char value < 00A0}% - \else\ifnum\countUTFz < "800\relax - \parseUTFviiiA,% - \parseUTFviiiB C\UTFviiiTwoOctets.,% - \else\ifnum\countUTFz < "10000\relax - \parseUTFviiiA;% - \parseUTFviiiA,% - \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% - \else - \parseUTFviiiA;% - \parseUTFviiiA,% - \parseUTFviiiA!% - \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% - \fi\fi\fi - } - - \gdef\parseUTFviiiA#1{% - \countUTFx = \countUTFz - \divide\countUTFz by 64 - \countUTFy = \countUTFz - \multiply\countUTFz by 64 - \advance\countUTFx by -\countUTFz - \advance\countUTFx by 128 - \uccode `#1\countUTFx - \countUTFz = \countUTFy} - - \gdef\parseUTFviiiB#1#2#3#4{% - \advance\countUTFz by "#10\relax - \uccode `#3\countUTFz - \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} -\endgroup - -\def\utfeightchardefs{% - \DeclareUnicodeCharacter{00A0}{\tie} - \DeclareUnicodeCharacter{00A1}{\exclamdown} - \DeclareUnicodeCharacter{00A3}{\pounds} - \DeclareUnicodeCharacter{00A8}{\"{ }} - \DeclareUnicodeCharacter{00A9}{\copyright} - \DeclareUnicodeCharacter{00AA}{\ordf} - \DeclareUnicodeCharacter{00AD}{\-} - \DeclareUnicodeCharacter{00AE}{\registeredsymbol} - \DeclareUnicodeCharacter{00AF}{\={ }} - - \DeclareUnicodeCharacter{00B0}{\ringaccent{ }} - \DeclareUnicodeCharacter{00B4}{\'{ }} - \DeclareUnicodeCharacter{00B8}{\cedilla{ }} - \DeclareUnicodeCharacter{00BA}{\ordm} - \DeclareUnicodeCharacter{00BF}{\questiondown} - - \DeclareUnicodeCharacter{00C0}{\`A} - \DeclareUnicodeCharacter{00C1}{\'A} - \DeclareUnicodeCharacter{00C2}{\^A} - \DeclareUnicodeCharacter{00C3}{\~A} - \DeclareUnicodeCharacter{00C4}{\"A} - \DeclareUnicodeCharacter{00C5}{\AA} - \DeclareUnicodeCharacter{00C6}{\AE} - \DeclareUnicodeCharacter{00C7}{\cedilla{C}} - \DeclareUnicodeCharacter{00C8}{\`E} - \DeclareUnicodeCharacter{00C9}{\'E} - \DeclareUnicodeCharacter{00CA}{\^E} - \DeclareUnicodeCharacter{00CB}{\"E} - \DeclareUnicodeCharacter{00CC}{\`I} - \DeclareUnicodeCharacter{00CD}{\'I} - \DeclareUnicodeCharacter{00CE}{\^I} - \DeclareUnicodeCharacter{00CF}{\"I} - - \DeclareUnicodeCharacter{00D1}{\~N} - \DeclareUnicodeCharacter{00D2}{\`O} - \DeclareUnicodeCharacter{00D3}{\'O} - \DeclareUnicodeCharacter{00D4}{\^O} - \DeclareUnicodeCharacter{00D5}{\~O} - \DeclareUnicodeCharacter{00D6}{\"O} - \DeclareUnicodeCharacter{00D8}{\O} - \DeclareUnicodeCharacter{00D9}{\`U} - \DeclareUnicodeCharacter{00DA}{\'U} - \DeclareUnicodeCharacter{00DB}{\^U} - \DeclareUnicodeCharacter{00DC}{\"U} - \DeclareUnicodeCharacter{00DD}{\'Y} - \DeclareUnicodeCharacter{00DF}{\ss} - - \DeclareUnicodeCharacter{00E0}{\`a} - \DeclareUnicodeCharacter{00E1}{\'a} - \DeclareUnicodeCharacter{00E2}{\^a} - \DeclareUnicodeCharacter{00E3}{\~a} - \DeclareUnicodeCharacter{00E4}{\"a} - \DeclareUnicodeCharacter{00E5}{\aa} - \DeclareUnicodeCharacter{00E6}{\ae} - \DeclareUnicodeCharacter{00E7}{\cedilla{c}} - \DeclareUnicodeCharacter{00E8}{\`e} - \DeclareUnicodeCharacter{00E9}{\'e} - \DeclareUnicodeCharacter{00EA}{\^e} - \DeclareUnicodeCharacter{00EB}{\"e} - \DeclareUnicodeCharacter{00EC}{\`{\dotless{i}}} - \DeclareUnicodeCharacter{00ED}{\'{\dotless{i}}} - \DeclareUnicodeCharacter{00EE}{\^{\dotless{i}}} - \DeclareUnicodeCharacter{00EF}{\"{\dotless{i}}} - - \DeclareUnicodeCharacter{00F1}{\~n} - \DeclareUnicodeCharacter{00F2}{\`o} - \DeclareUnicodeCharacter{00F3}{\'o} - \DeclareUnicodeCharacter{00F4}{\^o} - \DeclareUnicodeCharacter{00F5}{\~o} - \DeclareUnicodeCharacter{00F6}{\"o} - \DeclareUnicodeCharacter{00F8}{\o} - \DeclareUnicodeCharacter{00F9}{\`u} - \DeclareUnicodeCharacter{00FA}{\'u} - \DeclareUnicodeCharacter{00FB}{\^u} - \DeclareUnicodeCharacter{00FC}{\"u} - \DeclareUnicodeCharacter{00FD}{\'y} - \DeclareUnicodeCharacter{00FF}{\"y} - - \DeclareUnicodeCharacter{0100}{\=A} - \DeclareUnicodeCharacter{0101}{\=a} - \DeclareUnicodeCharacter{0102}{\u{A}} - \DeclareUnicodeCharacter{0103}{\u{a}} - \DeclareUnicodeCharacter{0106}{\'C} - \DeclareUnicodeCharacter{0107}{\'c} - \DeclareUnicodeCharacter{0108}{\^C} - \DeclareUnicodeCharacter{0109}{\^c} - \DeclareUnicodeCharacter{010A}{\dotaccent{C}} - \DeclareUnicodeCharacter{010B}{\dotaccent{c}} - \DeclareUnicodeCharacter{010C}{\v{C}} - \DeclareUnicodeCharacter{010D}{\v{c}} - \DeclareUnicodeCharacter{010E}{\v{D}} - - \DeclareUnicodeCharacter{0112}{\=E} - \DeclareUnicodeCharacter{0113}{\=e} - \DeclareUnicodeCharacter{0114}{\u{E}} - \DeclareUnicodeCharacter{0115}{\u{e}} - \DeclareUnicodeCharacter{0116}{\dotaccent{E}} - \DeclareUnicodeCharacter{0117}{\dotaccent{e}} - \DeclareUnicodeCharacter{011A}{\v{E}} - \DeclareUnicodeCharacter{011B}{\v{e}} - \DeclareUnicodeCharacter{011C}{\^G} - \DeclareUnicodeCharacter{011D}{\^g} - \DeclareUnicodeCharacter{011E}{\u{G}} - \DeclareUnicodeCharacter{011F}{\u{g}} - - \DeclareUnicodeCharacter{0120}{\dotaccent{G}} - \DeclareUnicodeCharacter{0121}{\dotaccent{g}} - \DeclareUnicodeCharacter{0124}{\^H} - \DeclareUnicodeCharacter{0125}{\^h} - \DeclareUnicodeCharacter{0128}{\~I} - \DeclareUnicodeCharacter{0129}{\~{\dotless{i}}} - \DeclareUnicodeCharacter{012A}{\=I} - \DeclareUnicodeCharacter{012B}{\={\dotless{i}}} - \DeclareUnicodeCharacter{012C}{\u{I}} - \DeclareUnicodeCharacter{012D}{\u{\dotless{i}}} - - \DeclareUnicodeCharacter{0130}{\dotaccent{I}} - \DeclareUnicodeCharacter{0131}{\dotless{i}} - \DeclareUnicodeCharacter{0132}{IJ} - \DeclareUnicodeCharacter{0133}{ij} - \DeclareUnicodeCharacter{0134}{\^J} - \DeclareUnicodeCharacter{0135}{\^{\dotless{j}}} - \DeclareUnicodeCharacter{0139}{\'L} - \DeclareUnicodeCharacter{013A}{\'l} - - \DeclareUnicodeCharacter{0141}{\L} - \DeclareUnicodeCharacter{0142}{\l} - \DeclareUnicodeCharacter{0143}{\'N} - \DeclareUnicodeCharacter{0144}{\'n} - \DeclareUnicodeCharacter{0147}{\v{N}} - \DeclareUnicodeCharacter{0148}{\v{n}} - \DeclareUnicodeCharacter{014C}{\=O} - \DeclareUnicodeCharacter{014D}{\=o} - \DeclareUnicodeCharacter{014E}{\u{O}} - \DeclareUnicodeCharacter{014F}{\u{o}} - - \DeclareUnicodeCharacter{0150}{\H{O}} - \DeclareUnicodeCharacter{0151}{\H{o}} - \DeclareUnicodeCharacter{0152}{\OE} - \DeclareUnicodeCharacter{0153}{\oe} - \DeclareUnicodeCharacter{0154}{\'R} - \DeclareUnicodeCharacter{0155}{\'r} - \DeclareUnicodeCharacter{0158}{\v{R}} - \DeclareUnicodeCharacter{0159}{\v{r}} - \DeclareUnicodeCharacter{015A}{\'S} - \DeclareUnicodeCharacter{015B}{\'s} - \DeclareUnicodeCharacter{015C}{\^S} - \DeclareUnicodeCharacter{015D}{\^s} - \DeclareUnicodeCharacter{015E}{\cedilla{S}} - \DeclareUnicodeCharacter{015F}{\cedilla{s}} - - \DeclareUnicodeCharacter{0160}{\v{S}} - \DeclareUnicodeCharacter{0161}{\v{s}} - \DeclareUnicodeCharacter{0162}{\cedilla{t}} - \DeclareUnicodeCharacter{0163}{\cedilla{T}} - \DeclareUnicodeCharacter{0164}{\v{T}} - - \DeclareUnicodeCharacter{0168}{\~U} - \DeclareUnicodeCharacter{0169}{\~u} - \DeclareUnicodeCharacter{016A}{\=U} - \DeclareUnicodeCharacter{016B}{\=u} - \DeclareUnicodeCharacter{016C}{\u{U}} - \DeclareUnicodeCharacter{016D}{\u{u}} - \DeclareUnicodeCharacter{016E}{\ringaccent{U}} - \DeclareUnicodeCharacter{016F}{\ringaccent{u}} - - \DeclareUnicodeCharacter{0170}{\H{U}} - \DeclareUnicodeCharacter{0171}{\H{u}} - \DeclareUnicodeCharacter{0174}{\^W} - \DeclareUnicodeCharacter{0175}{\^w} - \DeclareUnicodeCharacter{0176}{\^Y} - \DeclareUnicodeCharacter{0177}{\^y} - \DeclareUnicodeCharacter{0178}{\"Y} - \DeclareUnicodeCharacter{0179}{\'Z} - \DeclareUnicodeCharacter{017A}{\'z} - \DeclareUnicodeCharacter{017B}{\dotaccent{Z}} - \DeclareUnicodeCharacter{017C}{\dotaccent{z}} - \DeclareUnicodeCharacter{017D}{\v{Z}} - \DeclareUnicodeCharacter{017E}{\v{z}} - - \DeclareUnicodeCharacter{01C4}{D\v{Z}} - \DeclareUnicodeCharacter{01C5}{D\v{z}} - \DeclareUnicodeCharacter{01C6}{d\v{z}} - \DeclareUnicodeCharacter{01C7}{LJ} - \DeclareUnicodeCharacter{01C8}{Lj} - \DeclareUnicodeCharacter{01C9}{lj} - \DeclareUnicodeCharacter{01CA}{NJ} - \DeclareUnicodeCharacter{01CB}{Nj} - \DeclareUnicodeCharacter{01CC}{nj} - \DeclareUnicodeCharacter{01CD}{\v{A}} - \DeclareUnicodeCharacter{01CE}{\v{a}} - \DeclareUnicodeCharacter{01CF}{\v{I}} - - \DeclareUnicodeCharacter{01D0}{\v{\dotless{i}}} - \DeclareUnicodeCharacter{01D1}{\v{O}} - \DeclareUnicodeCharacter{01D2}{\v{o}} - \DeclareUnicodeCharacter{01D3}{\v{U}} - \DeclareUnicodeCharacter{01D4}{\v{u}} - - \DeclareUnicodeCharacter{01E2}{\={\AE}} - \DeclareUnicodeCharacter{01E3}{\={\ae}} - \DeclareUnicodeCharacter{01E6}{\v{G}} - \DeclareUnicodeCharacter{01E7}{\v{g}} - \DeclareUnicodeCharacter{01E8}{\v{K}} - \DeclareUnicodeCharacter{01E9}{\v{k}} - - \DeclareUnicodeCharacter{01F0}{\v{\dotless{j}}} - \DeclareUnicodeCharacter{01F1}{DZ} - \DeclareUnicodeCharacter{01F2}{Dz} - \DeclareUnicodeCharacter{01F3}{dz} - \DeclareUnicodeCharacter{01F4}{\'G} - \DeclareUnicodeCharacter{01F5}{\'g} - \DeclareUnicodeCharacter{01F8}{\`N} - \DeclareUnicodeCharacter{01F9}{\`n} - \DeclareUnicodeCharacter{01FC}{\'{\AE}} - \DeclareUnicodeCharacter{01FD}{\'{\ae}} - \DeclareUnicodeCharacter{01FE}{\'{\O}} - \DeclareUnicodeCharacter{01FF}{\'{\o}} - - \DeclareUnicodeCharacter{021E}{\v{H}} - \DeclareUnicodeCharacter{021F}{\v{h}} - - \DeclareUnicodeCharacter{0226}{\dotaccent{A}} - \DeclareUnicodeCharacter{0227}{\dotaccent{a}} - \DeclareUnicodeCharacter{0228}{\cedilla{E}} - \DeclareUnicodeCharacter{0229}{\cedilla{e}} - \DeclareUnicodeCharacter{022E}{\dotaccent{O}} - \DeclareUnicodeCharacter{022F}{\dotaccent{o}} - - \DeclareUnicodeCharacter{0232}{\=Y} - \DeclareUnicodeCharacter{0233}{\=y} - \DeclareUnicodeCharacter{0237}{\dotless{j}} - - \DeclareUnicodeCharacter{1E02}{\dotaccent{B}} - \DeclareUnicodeCharacter{1E03}{\dotaccent{b}} - \DeclareUnicodeCharacter{1E04}{\udotaccent{B}} - \DeclareUnicodeCharacter{1E05}{\udotaccent{b}} - \DeclareUnicodeCharacter{1E06}{\ubaraccent{B}} - \DeclareUnicodeCharacter{1E07}{\ubaraccent{b}} - \DeclareUnicodeCharacter{1E0A}{\dotaccent{D}} - \DeclareUnicodeCharacter{1E0B}{\dotaccent{d}} - \DeclareUnicodeCharacter{1E0C}{\udotaccent{D}} - \DeclareUnicodeCharacter{1E0D}{\udotaccent{d}} - \DeclareUnicodeCharacter{1E0E}{\ubaraccent{D}} - \DeclareUnicodeCharacter{1E0F}{\ubaraccent{d}} - - \DeclareUnicodeCharacter{1E1E}{\dotaccent{F}} - \DeclareUnicodeCharacter{1E1F}{\dotaccent{f}} - - \DeclareUnicodeCharacter{1E20}{\=G} - \DeclareUnicodeCharacter{1E21}{\=g} - \DeclareUnicodeCharacter{1E22}{\dotaccent{H}} - \DeclareUnicodeCharacter{1E23}{\dotaccent{h}} - \DeclareUnicodeCharacter{1E24}{\udotaccent{H}} - \DeclareUnicodeCharacter{1E25}{\udotaccent{h}} - \DeclareUnicodeCharacter{1E26}{\"H} - \DeclareUnicodeCharacter{1E27}{\"h} - - \DeclareUnicodeCharacter{1E30}{\'K} - \DeclareUnicodeCharacter{1E31}{\'k} - \DeclareUnicodeCharacter{1E32}{\udotaccent{K}} - \DeclareUnicodeCharacter{1E33}{\udotaccent{k}} - \DeclareUnicodeCharacter{1E34}{\ubaraccent{K}} - \DeclareUnicodeCharacter{1E35}{\ubaraccent{k}} - \DeclareUnicodeCharacter{1E36}{\udotaccent{L}} - \DeclareUnicodeCharacter{1E37}{\udotaccent{l}} - \DeclareUnicodeCharacter{1E3A}{\ubaraccent{L}} - \DeclareUnicodeCharacter{1E3B}{\ubaraccent{l}} - \DeclareUnicodeCharacter{1E3E}{\'M} - \DeclareUnicodeCharacter{1E3F}{\'m} - - \DeclareUnicodeCharacter{1E40}{\dotaccent{M}} - \DeclareUnicodeCharacter{1E41}{\dotaccent{m}} - \DeclareUnicodeCharacter{1E42}{\udotaccent{M}} - \DeclareUnicodeCharacter{1E43}{\udotaccent{m}} - \DeclareUnicodeCharacter{1E44}{\dotaccent{N}} - \DeclareUnicodeCharacter{1E45}{\dotaccent{n}} - \DeclareUnicodeCharacter{1E46}{\udotaccent{N}} - \DeclareUnicodeCharacter{1E47}{\udotaccent{n}} - \DeclareUnicodeCharacter{1E48}{\ubaraccent{N}} - \DeclareUnicodeCharacter{1E49}{\ubaraccent{n}} - - \DeclareUnicodeCharacter{1E54}{\'P} - \DeclareUnicodeCharacter{1E55}{\'p} - \DeclareUnicodeCharacter{1E56}{\dotaccent{P}} - \DeclareUnicodeCharacter{1E57}{\dotaccent{p}} - \DeclareUnicodeCharacter{1E58}{\dotaccent{R}} - \DeclareUnicodeCharacter{1E59}{\dotaccent{r}} - \DeclareUnicodeCharacter{1E5A}{\udotaccent{R}} - \DeclareUnicodeCharacter{1E5B}{\udotaccent{r}} - \DeclareUnicodeCharacter{1E5E}{\ubaraccent{R}} - \DeclareUnicodeCharacter{1E5F}{\ubaraccent{r}} - - \DeclareUnicodeCharacter{1E60}{\dotaccent{S}} - \DeclareUnicodeCharacter{1E61}{\dotaccent{s}} - \DeclareUnicodeCharacter{1E62}{\udotaccent{S}} - \DeclareUnicodeCharacter{1E63}{\udotaccent{s}} - \DeclareUnicodeCharacter{1E6A}{\dotaccent{T}} - \DeclareUnicodeCharacter{1E6B}{\dotaccent{t}} - \DeclareUnicodeCharacter{1E6C}{\udotaccent{T}} - \DeclareUnicodeCharacter{1E6D}{\udotaccent{t}} - \DeclareUnicodeCharacter{1E6E}{\ubaraccent{T}} - \DeclareUnicodeCharacter{1E6F}{\ubaraccent{t}} - - \DeclareUnicodeCharacter{1E7C}{\~V} - \DeclareUnicodeCharacter{1E7D}{\~v} - \DeclareUnicodeCharacter{1E7E}{\udotaccent{V}} - \DeclareUnicodeCharacter{1E7F}{\udotaccent{v}} - - \DeclareUnicodeCharacter{1E80}{\`W} - \DeclareUnicodeCharacter{1E81}{\`w} - \DeclareUnicodeCharacter{1E82}{\'W} - \DeclareUnicodeCharacter{1E83}{\'w} - \DeclareUnicodeCharacter{1E84}{\"W} - \DeclareUnicodeCharacter{1E85}{\"w} - \DeclareUnicodeCharacter{1E86}{\dotaccent{W}} - \DeclareUnicodeCharacter{1E87}{\dotaccent{w}} - \DeclareUnicodeCharacter{1E88}{\udotaccent{W}} - \DeclareUnicodeCharacter{1E89}{\udotaccent{w}} - \DeclareUnicodeCharacter{1E8A}{\dotaccent{X}} - \DeclareUnicodeCharacter{1E8B}{\dotaccent{x}} - \DeclareUnicodeCharacter{1E8C}{\"X} - \DeclareUnicodeCharacter{1E8D}{\"x} - \DeclareUnicodeCharacter{1E8E}{\dotaccent{Y}} - \DeclareUnicodeCharacter{1E8F}{\dotaccent{y}} - - \DeclareUnicodeCharacter{1E90}{\^Z} - \DeclareUnicodeCharacter{1E91}{\^z} - \DeclareUnicodeCharacter{1E92}{\udotaccent{Z}} - \DeclareUnicodeCharacter{1E93}{\udotaccent{z}} - \DeclareUnicodeCharacter{1E94}{\ubaraccent{Z}} - \DeclareUnicodeCharacter{1E95}{\ubaraccent{z}} - \DeclareUnicodeCharacter{1E96}{\ubaraccent{h}} - \DeclareUnicodeCharacter{1E97}{\"t} - \DeclareUnicodeCharacter{1E98}{\ringaccent{w}} - \DeclareUnicodeCharacter{1E99}{\ringaccent{y}} - - \DeclareUnicodeCharacter{1EA0}{\udotaccent{A}} - \DeclareUnicodeCharacter{1EA1}{\udotaccent{a}} - - \DeclareUnicodeCharacter{1EB8}{\udotaccent{E}} - \DeclareUnicodeCharacter{1EB9}{\udotaccent{e}} - \DeclareUnicodeCharacter{1EBC}{\~E} - \DeclareUnicodeCharacter{1EBD}{\~e} - - \DeclareUnicodeCharacter{1ECA}{\udotaccent{I}} - \DeclareUnicodeCharacter{1ECB}{\udotaccent{i}} - \DeclareUnicodeCharacter{1ECC}{\udotaccent{O}} - \DeclareUnicodeCharacter{1ECD}{\udotaccent{o}} - - \DeclareUnicodeCharacter{1EE4}{\udotaccent{U}} - \DeclareUnicodeCharacter{1EE5}{\udotaccent{u}} - - \DeclareUnicodeCharacter{1EF2}{\`Y} - \DeclareUnicodeCharacter{1EF3}{\`y} - \DeclareUnicodeCharacter{1EF4}{\udotaccent{Y}} - - \DeclareUnicodeCharacter{1EF8}{\~Y} - \DeclareUnicodeCharacter{1EF9}{\~y} - - \DeclareUnicodeCharacter{2013}{--} - \DeclareUnicodeCharacter{2014}{---} - \DeclareUnicodeCharacter{2022}{\bullet} - \DeclareUnicodeCharacter{2026}{\dots} - \DeclareUnicodeCharacter{20AC}{\euro} - - \DeclareUnicodeCharacter{2192}{\expansion} - \DeclareUnicodeCharacter{21D2}{\result} - - \DeclareUnicodeCharacter{2212}{\minus} - \DeclareUnicodeCharacter{2217}{\point} - \DeclareUnicodeCharacter{2261}{\equiv} -}% end of \utfeightchardefs - - -% US-ASCII character definitions. -\def\asciichardefs{% nothing need be done - \relax -} - -% Make non-ASCII characters printable again for compatibility with -% existing Texinfo documents that may use them, even without declaring a -% document encoding. -% -\setnonasciicharscatcode \other - - -\message{formatting,} - -\newdimen\defaultparindent \defaultparindent = 15pt - -\chapheadingskip = 15pt plus 4pt minus 2pt -\secheadingskip = 12pt plus 3pt minus 2pt -\subsecheadingskip = 9pt plus 2pt minus 2pt - -% Prevent underfull vbox error messages. -\vbadness = 10000 - -% Don't be so finicky about underfull hboxes, either. -\hbadness = 2000 - -% Following George Bush, just get rid of widows and orphans. -\widowpenalty=10000 -\clubpenalty=10000 - -% Use TeX 3.0's \emergencystretch to help line breaking, but if we're -% using an old version of TeX, don't do anything. We want the amount of -% stretch added to depend on the line length, hence the dependence on -% \hsize. We call this whenever the paper size is set. -% -\def\setemergencystretch{% - \ifx\emergencystretch\thisisundefined - % Allow us to assign to \emergencystretch anyway. - \def\emergencystretch{\dimen0}% - \else - \emergencystretch = .15\hsize - \fi -} - -% Parameters in order: 1) textheight; 2) textwidth; -% 3) voffset; 4) hoffset; 5) binding offset; 6) topskip; -% 7) physical page height; 8) physical page width. -% -% We also call \setleading{\textleading}, so the caller should define -% \textleading. The caller should also set \parskip. -% -\def\internalpagesizes#1#2#3#4#5#6#7#8{% - \voffset = #3\relax - \topskip = #6\relax - \splittopskip = \topskip - % - \vsize = #1\relax - \advance\vsize by \topskip - \outervsize = \vsize - \advance\outervsize by 2\topandbottommargin - \pageheight = \vsize - % - \hsize = #2\relax - \outerhsize = \hsize - \advance\outerhsize by 0.5in - \pagewidth = \hsize - % - \normaloffset = #4\relax - \bindingoffset = #5\relax - % - \ifpdf - \pdfpageheight #7\relax - \pdfpagewidth #8\relax - \pdfhorigin = 1 true in - \pdfvorigin = 1 true in - \fi - % - \setleading{\textleading} - % - \parindent = \defaultparindent - \setemergencystretch -} - -% @letterpaper (the default). -\def\letterpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % If page is nothing but text, make it come out even. - \internalpagesizes{46\baselineskip}{6in}% - {\voffset}{.25in}% - {\bindingoffset}{36pt}% - {11in}{8.5in}% -}} - -% Use @smallbook to reset parameters for 7x9.25 trim size. -\def\smallbook{{\globaldefs = 1 - \parskip = 2pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.5in}{5in}% - {-.2in}{0in}% - {\bindingoffset}{16pt}% - {9.25in}{7in}% - % - \lispnarrowing = 0.3in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .5cm -}} - -% Use @smallerbook to reset parameters for 6x9 trim size. -% (Just testing, parameters still in flux.) -\def\smallerbook{{\globaldefs = 1 - \parskip = 1.5pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.4in}{4.8in}% - {-.2in}{-.4in}% - {0pt}{14pt}% - {9in}{6in}% - % - \lispnarrowing = 0.25in - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = .4cm -}} - -% Use @afourpaper to print on European A4 paper. -\def\afourpaper{{\globaldefs = 1 - \parskip = 3pt plus 2pt minus 1pt - \textleading = 13.2pt - % - % Double-side printing via postscript on Laserjet 4050 - % prints double-sided nicely when \bindingoffset=10mm and \hoffset=-6mm. - % To change the settings for a different printer or situation, adjust - % \normaloffset until the front-side and back-side texts align. Then - % do the same for \bindingoffset. You can set these for testing in - % your texinfo source file like this: - % @tex - % \global\normaloffset = -6mm - % \global\bindingoffset = 10mm - % @end tex - \internalpagesizes{51\baselineskip}{160mm} - {\voffset}{\hoffset}% - {\bindingoffset}{44pt}% - {297mm}{210mm}% - % - \tolerance = 700 - \hfuzz = 1pt - \contentsrightmargin = 0pt - \defbodyindent = 5mm -}} - -% Use @afivepaper to print on European A5 paper. -% From romildo@urano.iceb.ufop.br, 2 July 2000. -% He also recommends making @example and @lisp be small. -\def\afivepaper{{\globaldefs = 1 - \parskip = 2pt plus 1pt minus 0.1pt - \textleading = 12.5pt - % - \internalpagesizes{160mm}{120mm}% - {\voffset}{\hoffset}% - {\bindingoffset}{8pt}% - {210mm}{148mm}% - % - \lispnarrowing = 0.2in - \tolerance = 800 - \hfuzz = 1.2pt - \contentsrightmargin = 0pt - \defbodyindent = 2mm - \tableindent = 12mm -}} - -% A specific text layout, 24x15cm overall, intended for A4 paper. -\def\afourlatex{{\globaldefs = 1 - \afourpaper - \internalpagesizes{237mm}{150mm}% - {\voffset}{4.6mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - % - % Must explicitly reset to 0 because we call \afourpaper. - \globaldefs = 0 -}} - -% Use @afourwide to print on A4 paper in landscape format. -\def\afourwide{{\globaldefs = 1 - \afourpaper - \internalpagesizes{241mm}{165mm}% - {\voffset}{-2.95mm}% - {\bindingoffset}{7mm}% - {297mm}{210mm}% - \globaldefs = 0 -}} - -% @pagesizes TEXTHEIGHT[,TEXTWIDTH] -% Perhaps we should allow setting the margins, \topskip, \parskip, -% and/or leading, also. Or perhaps we should compute them somehow. -% -\parseargdef\pagesizes{\pagesizesyyy #1,,\finish} -\def\pagesizesyyy#1,#2,#3\finish{{% - \setbox0 = \hbox{\ignorespaces #2}\ifdim\wd0 > 0pt \hsize=#2\relax \fi - \globaldefs = 1 - % - \parskip = 3pt plus 2pt minus 1pt - \setleading{\textleading}% - % - \dimen0 = #1 - \advance\dimen0 by \voffset - % - \dimen2 = \hsize - \advance\dimen2 by \normaloffset - % - \internalpagesizes{#1}{\hsize}% - {\voffset}{\normaloffset}% - {\bindingoffset}{44pt}% - {\dimen0}{\dimen2}% -}} - -% Set default to letter. -% -\letterpaper - - -\message{and turning on texinfo input format.} - -% Define macros to output various characters with catcode for normal text. -\catcode`\"=\other -\catcode`\~=\other -\catcode`\^=\other -\catcode`\_=\other -\catcode`\|=\other -\catcode`\<=\other -\catcode`\>=\other -\catcode`\+=\other -\catcode`\$=\other -\def\normaldoublequote{"} -\def\normaltilde{~} -\def\normalcaret{^} -\def\normalunderscore{_} -\def\normalverticalbar{|} -\def\normalless{<} -\def\normalgreater{>} -\def\normalplus{+} -\def\normaldollar{$}%$ font-lock fix - -% This macro is used to make a character print one way in \tt -% (where it can probably be output as-is), and another way in other fonts, -% where something hairier probably needs to be done. -% -% #1 is what to print if we are indeed using \tt; #2 is what to print -% otherwise. Since all the Computer Modern typewriter fonts have zero -% interword stretch (and shrink), and it is reasonable to expect all -% typewriter fonts to have this, we can check that font parameter. -% -\def\ifusingtt#1#2{\ifdim \fontdimen3\font=0pt #1\else #2\fi} - -% Same as above, but check for italic font. Actually this also catches -% non-italic slanted fonts since it is impossible to distinguish them from -% italic fonts. But since this is only used by $ and it uses \sl anyway -% this is not a problem. -\def\ifusingit#1#2{\ifdim \fontdimen1\font>0pt #1\else #2\fi} - -% Turn off all special characters except @ -% (and those which the user can use as if they were ordinary). -% Most of these we simply print from the \tt font, but for some, we can -% use math or other variants that look better in normal text. - -\catcode`\"=\active -\def\activedoublequote{{\tt\char34}} -\let"=\activedoublequote -\catcode`\~=\active -\def~{{\tt\char126}} -\chardef\hat=`\^ -\catcode`\^=\active -\def^{{\tt \hat}} - -\catcode`\_=\active -\def_{\ifusingtt\normalunderscore\_} -\let\realunder=_ -% Subroutine for the previous macro. -\def\_{\leavevmode \kern.07em \vbox{\hrule width.3em height.1ex}\kern .07em } - -\catcode`\|=\active -\def|{{\tt\char124}} -\chardef \less=`\< -\catcode`\<=\active -\def<{{\tt \less}} -\chardef \gtr=`\> -\catcode`\>=\active -\def>{{\tt \gtr}} -\catcode`\+=\active -\def+{{\tt \char 43}} -\catcode`\$=\active -\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix - -% If a .fmt file is being used, characters that might appear in a file -% name cannot be active until we have parsed the command line. -% So turn them off again, and have \everyjob (or @setfilename) turn them on. -% \otherifyactive is called near the end of this file. -\def\otherifyactive{\catcode`+=\other \catcode`\_=\other} - -% Used sometimes to turn off (effectively) the active characters even after -% parsing them. -\def\turnoffactive{% - \normalturnoffactive - \otherbackslash -} - -\catcode`\@=0 - -% \backslashcurfont outputs one backslash character in current font, -% as in \char`\\. -\global\chardef\backslashcurfont=`\\ -\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work - -% \realbackslash is an actual character `\' with catcode other, and -% \doublebackslash is two of them (for the pdf outlines). -{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} - -% In texinfo, backslash is an active character; it prints the backslash -% in fixed width font. -\catcode`\\=\active -@def@normalbackslash{{@tt@backslashcurfont}} -% On startup, @fixbackslash assigns: -% @let \ = @normalbackslash - -% \rawbackslash defines an active \ to do \backslashcurfont. -% \otherbackslash defines an active \ to be a literal `\' character with -% catcode other. -@gdef@rawbackslash{@let\=@backslashcurfont} -@gdef@otherbackslash{@let\=@realbackslash} - -% Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of -% the literal character `\'. -% -@def@normalturnoffactive{% - @let\=@normalbackslash - @let"=@normaldoublequote - @let~=@normaltilde - @let^=@normalcaret - @let_=@normalunderscore - @let|=@normalverticalbar - @let<=@normalless - @let>=@normalgreater - @let+=@normalplus - @let$=@normaldollar %$ font-lock fix - @unsepspaces -} - -% Make _ and + \other characters, temporarily. -% This is canceled by @fixbackslash. -@otherifyactive - -% If a .fmt file is being used, we don't want the `\input texinfo' to show up. -% That is what \eatinput is for; after that, the `\' should revert to printing -% a backslash. -% -@gdef@eatinput input texinfo{@fixbackslash} -@global@let\ = @eatinput - -% On the other hand, perhaps the file did not have a `\input texinfo'. Then -% the first `\' in the file would cause an error. This macro tries to fix -% that, assuming it is called before the first `\' could plausibly occur. -% Also turn back on active characters that might appear in the input -% file name, in case not using a pre-dumped format. -% -@gdef@fixbackslash{% - @ifx\@eatinput @let\ = @normalbackslash @fi - @catcode`+=@active - @catcode`@_=@active -} - -% Say @foo, not \foo, in error messages. -@escapechar = `@@ - -% These look ok in all fonts, so just make them not special. -@catcode`@& = @other -@catcode`@# = @other -@catcode`@% = @other - - -@c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) -@c page-delimiter: "^\\\\message" -@c time-stamp-start: "def\\\\texinfoversion{" -@c time-stamp-format: "%:y-%02m-%02d.%02H" -@c time-stamp-end: "}" -@c End: - -@c vim:sw=2: - -@ignore - arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 -@end ignore diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi deleted file mode 100644 index 00b5f4ca909..00000000000 --- a/doc/misc/tramp.texi +++ /dev/null @@ -1,3500 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename ../../info/tramp -@c %**start of header -@settitle TRAMP User Manual -@c %**end of header - -@c This is *so* much nicer :) -@footnotestyle end - -@c In the Tramp CVS, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. - -@c Additionally, flags are set with respect to the Emacs flavor; and -@c depending whether Tramp is packaged into (X)Emacs, or standalone. - -@include trampver.texi - -@c Macro for formatting a filename according to the repective syntax. -@c xxx and yyy are auxiliary macros in order to omit leading and -@c trailing whitespace. Not very elegant, but I don't know it better. - -@macro xxx {one}@c -@set \one\@c -@end macro - -@macro yyy {one, two}@c -@xxx{x\one\}@c -@ifclear x@c -\one\@w{}\two\@c -@end ifclear -@clear x\one\@c -@end macro - -@macro trampfn {method, user, host, localname}@c -@value{prefix}@yyy{\method\,@value{postfixhop}}@yyy{\user\,@@}\host\@value{postfix}\localname\@c -@end macro - -@copying -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, -2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c Entries for @command{install-info} to use -@dircategory @value{emacsname} -@direntry -* TRAMP: (tramp). Transparent Remote Access, Multiple Protocol - @value{emacsname} remote file access via rsh and rcp. -@end direntry - -@titlepage -@title @value{tramp} version @value{trampver} User Manual -@author by Daniel Pittman -@author based on documentation by Kai Gro@ss{}johann -@page -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top @value{tramp} version @value{trampver} User Manual - -This file documents @value{tramp} version @value{trampver}, a remote file -editing package for @value{emacsname}. - -@value{tramp} stands for `Transparent Remote (file) Access, Multiple -Protocol'. This package provides remote file editing, similar to -@value{ftppackagename}. - -The difference is that @value{ftppackagename} uses FTP to transfer -files between the local and the remote host, whereas @value{tramp} uses a -combination of @command{rsh} and @command{rcp} or other work-alike -programs, such as @command{ssh}/@command{scp}. - -You can find the latest version of this document on the web at -@uref{http://www.gnu.org/software/tramp/}. - -@c Pointer to the other Emacs flavor is necessary only in case of -@c standalone installation. -@ifset installchapter -The manual has been generated for @value{emacsname}. -@ifinfo -If you want to read the info pages for @value{emacsothername}, you -should read in @ref{Installation} how to create them. -@end ifinfo -@ifhtml -If you're using the other Emacs flavor, you should read the -@uref{@value{emacsotherfilename}, @value{emacsothername}} pages. -@end ifhtml -@end ifset - -@ifhtml -@ifset jamanual -This manual is also available as a @uref{@value{japanesemanual}, -Japanese translation}. -@end ifset - -The latest release of @value{tramp} is available for -@uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see -@ref{Obtaining Tramp} for more details, including the CVS server -details. - -@value{tramp} also has a @uref{http://savannah.gnu.org/projects/tramp/, -Savannah Project Page}. -@end ifhtml - -There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{http://lists.gnu.org/archive/html/tramp-devel/, the -@value{tramp} Mail Archive}. -@ifhtml -Older archives are located at -@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, -SourceForge Mail Archive} and -@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, -The Mail Archive}. -@c in HTML output, there's no new paragraph. -@*@* -@end ifhtml - -@insertcopying - -@end ifnottex - -@menu -* Overview:: What @value{tramp} can and cannot do. - -For the end user: - -* Obtaining Tramp:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. -@ifset installchapter -* Installation:: Installing @value{tramp} with your @value{emacsname}. -@end ifset -* Configuration:: Configuring @value{tramp} for use. -* Usage:: An overview of the operation of @value{tramp}. -* Bug Reports:: Reporting Bugs and Problems. -* Frequently Asked Questions:: Questions and answers from the mailing list. -* Function Index:: @value{tramp} functions. -* Variable Index:: User options and variables. -* Concept Index:: An item for each concept. - -For the developer: - -* Version Control:: The inner workings of remote version control. -* Files directories and localnames:: How file names, directories and localnames are mangled and managed. -* Traces and Profiles:: How to Customize Traces. -* Issues:: Debatable Issues and What Was Decided. - -* GNU Free Documentation License:: The license for this documentation. - -@detailmenu - --- The Detailed Node Listing --- -@c -@ifset installchapter -Installing @value{tramp} with your @value{emacsname} - -* Installation parameters:: Parameters in order to control installation. -* Load paths:: How to plug-in @value{tramp} into your environment. -* Japanese manual:: Japanese manual. - -@end ifset - -Configuring @value{tramp} for use - -* Connection types:: Types of connections made to remote machines. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. -* Remote shell setup:: Remote shell setup hints. -* Windows setup hints:: Issues with Cygwin ssh. -* Auto-save and Backup:: Auto-save and Backup. - -Using @value{tramp} - -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. - -The inner workings of remote version control - -* Version Controlled Files:: Determining if a file is under version control. -* Remote Commands:: Executing the version control commands on the remote machine. -* Changed workfiles:: Detecting if the working file has changed. -* Checking out files:: Bringing the workfile out of the repository. -* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. - -Things related to Version Control that don't fit elsewhere - -* Remote File Ownership:: How VC determines who owns a workfile. -* Back-end Versions:: How VC determines what release your RCS is. - -How file names, directories and localnames are mangled and managed - -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset - -@end detailmenu -@end menu - -@node Overview -@chapter An overview of @value{tramp} -@cindex overview - -After the installation of @value{tramp} into your @value{emacsname}, you -will be able to access files on remote machines as though they were -local. Access to the remote file system for editing files, version -control, and @code{dired} are transparently enabled. - -Your access to the remote machine can be with the @command{rsh}, -@command{rlogin}, @command{telnet} programs or with any similar -connection method. This connection must pass @acronym{ASCII} -successfully to be usable but need not be 8-bit clean. - -The package provides support for @command{ssh} connections out of the -box, one of the more common uses of the package. This allows -relatively secure access to machines, especially if @command{ftp} -access is disabled. - -Under Windows, @value{tramp} is integrated with the PuTTY package, -using the @command{plink} program. - -The majority of activity carried out by @value{tramp} requires only that -the remote login is possible and is carried out at the terminal. In -order to access remote files @value{tramp} needs to transfer their content -to the local machine temporarily. - -@value{tramp} can transfer files between the machines in a variety of ways. -The details are easy to select, depending on your needs and the -machines in question. - -The fastest transfer methods for large files rely on a remote file -transfer package such as @command{rcp}, @command{scp}, @command{rsync} -or (under Windows) @command{pscp}. - -If the remote copy methods are not suitable for you, @value{tramp} also -supports the use of encoded transfers directly through the shell. -This requires that the @command{mimencode} or @command{uuencode} tools -are available on the remote machine. These methods are generally -faster for small files. - -@value{tramp} is still under active development and any problems you encounter, -trivial or major, should be reported to the @value{tramp} developers. -@xref{Bug Reports}. - - -@subsubheading Behind the scenes -@cindex behind the scenes -@cindex details of operation -@cindex how it works - -This section tries to explain what goes on behind the scenes when you -access a remote file through @value{tramp}. - -Suppose you type @kbd{C-x C-f} and enter part of an @value{tramp} file name, -then hit @kbd{@key{TAB}} for completion. Suppose further that this is -the first time that @value{tramp} is invoked for the host in question. Here's -what happens: - -@itemize -@item -@value{tramp} discovers that it needs a connection to the host. So it -invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l -@var{user}} or a similar tool to connect to the remote host. -Communication with this process happens through an -@value{emacsname} buffer, that is, the output from the remote end -goes into a buffer. - -@item -The remote host may prompt for a login name (for @command{telnet}). -The login name is given in the file name, so @value{tramp} sends the -login name and a newline. - -@item -The remote host may prompt for a password or pass phrase (for -@command{rsh} or for @command{telnet} after sending the login name). -@value{tramp} displays the prompt in the minibuffer, asking you for the -password or pass phrase. - -You enter the password or pass phrase. @value{tramp} sends it to the remote -host, followed by a newline. - -@item -@value{tramp} now waits for the shell prompt or for a message that the login -failed. - -If @value{tramp} sees neither of them after a certain period of time -(a minute, say), then it issues an error message saying that it -couldn't find the remote shell prompt and shows you what the remote -host has sent. - -If @value{tramp} sees a @samp{login failed} message, it tells you so, -aborts the login attempt and allows you to try again. - -@item -Suppose that the login was successful and @value{tramp} sees the shell prompt -from the remote host. Now @value{tramp} invokes @command{/bin/sh} because -Bourne shells and C shells have different command -syntaxes.@footnote{Invoking @command{/bin/sh} will fail if your login -shell doesn't recognize @samp{exec /bin/sh} as a valid command. -Maybe you use the Scheme shell @command{scsh}@dots{}} - -After the Bourne shell has come up, @value{tramp} sends a few commands to -ensure a good working environment. It turns off echoing, it sets the -shell prompt, and a few other things. - -@item -Now the remote shell is up and it good working order. Remember, what -was supposed to happen is that @value{tramp} tries to find out what files exist -on the remote host so that it can do filename completion. - -So, @value{tramp} basically issues @command{cd} and @command{ls} commands and -also sometimes @command{echo} with globbing. Another command that is -often used is @command{test} to find out whether a file is writable or a -directory or the like. The output of each command is parsed for the -necessary operation. - -@item -Suppose you are finished with filename completion, have entered @kbd{C-x -C-f}, a full file name and hit @kbd{@key{RET}}. Now comes the time to -transfer the file contents from the remote host to the local host so -that you can edit them. - -See above for an explanation of how @value{tramp} transfers the file contents. - -For inline transfers, @value{tramp} issues a command like @samp{mimencode -b -/path/to/remote/file}, waits until the output has accumulated in the -buffer that's used for communication, then decodes that output to -produce the file contents. - -For external transfers, @value{tramp} issues a command like the -following: -@example -rcp user@@host:/path/to/remote/file /tmp/tramp.4711 -@end example -It then reads the local temporary file @file{/tmp/tramp.4711} into a -buffer and deletes the temporary file. - -@item -You now edit the buffer contents, blithely unaware of what has happened -behind the scenes. (Unless you have read this section, that is.) When -you are finished, you type @kbd{C-x C-s} to save the buffer. - -@item -Again, @value{tramp} transfers the file contents to the remote host -either inline or external. This is the reverse of what happens when -reading the file. -@end itemize - -I hope this has provided you with a basic overview of what happens -behind the scenes when you open a file with @value{tramp}. - - -@c For the end user -@node Obtaining Tramp -@chapter Obtaining Tramp. -@cindex obtaining Tramp - -@value{tramp} is freely available on the Internet and the latest -release may be downloaded from -@uref{ftp://ftp.gnu.org/gnu/tramp/}. This release includes the full -documentation and code for @value{tramp}, suitable for installation. -But GNU Emacs (22 or later) includes @value{tramp} already, and there -is a @value{tramp} package for XEmacs, as well. So maybe it is easier -to just use those. But if you want the bleeding edge, read -on@dots{...} - -For the especially brave, @value{tramp} is available from CVS. The CVS -version is the latest version of the code and may contain incomplete -features or new issues. Use these versions at your own risk. - -Instructions for obtaining the latest development version of @value{tramp} -from CVS can be found by going to the Savannah project page at the -following URL and then clicking on the CVS link in the navigation bar -at the top. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - -@noindent -Or follow the example session below: - -@example -] @strong{cd ~/@value{emacsdir}} -] @strong{export CVS_RSH="ssh"} -] @strong{cvs -z3 -d:ext:anoncvs@@savannah.gnu.org:/cvsroot/tramp co tramp} -@end example - -@noindent -You should now have a directory @file{~/@value{emacsdir}/tramp} -containing the latest version of @value{tramp}. You can fetch the latest -updates from the repository by issuing the command: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{export CVS_RSH="ssh"} -] @strong{cvs update -d} -@end example - -@noindent -Once you've got updated files from the CVS repository, you need to run -@command{autoconf} in order to get an up-to-date @file{configure} -script: - -@example -] @strong{cd ~/@value{emacsdir}/tramp} -] @strong{autoconf} -@end example - -People who have no direct CVS access (maybe because sitting behind a -blocking firewall), can try the -@uref{http://savannah.gnu.org/cvs-backup/tramp-sources.tar.gz, Nightly -CVS Tree Tarball} instead of. - - -@node History -@chapter History of @value{tramp} -@cindex history -@cindex development history - -Development was started end of November 1998. The package was called -@file{rssh.el}, back then. It only provided one method to access a -file, using @command{ssh} to log in to a remote host and using -@command{scp} to transfer the file contents. After a while, the name -was changed to @file{rcp.el}, and now it's @value{tramp}. Along the way, -many more methods for getting a remote shell and for transferring the -file contents were added. Support for VC was added. - -The most recent addition of major features were the multi-hop methods -added in April 2000 and the unification of @value{tramp} and Ange-FTP -filenames in July 2002. In July 2004, multi-hop methods have been -replaced by proxy hosts. Running commands on remote hosts was -introduced in December 2005. -@ifset emacsgw -Support of gateways exists since April 2007. -@end ifset - -In December 2001, @value{tramp} has been added to the XEmacs package -repository. Being part of the GNU Emacs repository happened in June -2002, the first release including @value{tramp} was GNU Emacs 22.1. - -@value{tramp} is also a GNU/Linux Debian package since February 2001. - - -@c Installation chapter is necessary only in case of standalone -@c installation. Text taken from trampinst.texi. -@ifset installchapter -@include trampinst.texi -@end ifset - -@node Configuration -@chapter Configuring @value{tramp} for use -@cindex configuration - -@cindex default configuration -@value{tramp} is (normally) fully functional when it is initially -installed. It is initially configured to use the @command{scp} -program to connect to the remote host. So in the easiest case, you -just type @kbd{C-x C-f} and then enter the filename -@file{@trampfn{, user, machine, /path/to.file}}. - -On some hosts, there are problems with opening a connection. These are -related to the behavior of the remote shell. See @xref{Remote shell -setup}, for details on this. - -If you do not wish to use these commands to connect to the remote -host, you should change the default connection and transfer method -that @value{tramp} uses. There are several different methods that @value{tramp} -can use to connect to remote machines and transfer files -(@pxref{Connection types}). - -If you don't know which method is right for you, see @xref{Default -Method}. - - -@menu -* Connection types:: Types of connections made to remote machines. -* Inline methods:: Inline methods. -* External methods:: External methods. -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset -* Default Method:: Selecting a default method. - Here we also try to help those who - don't have the foggiest which method - is right for them. -* Default User:: Selecting a default user. -* Default Host:: Selecting a default host. -* Multi-hops:: Connecting to a remote host using multiple hops. -* Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. -* Password handling:: Reusing passwords for several connections. -* Connection caching:: Reusing connection related information. -* Remote Programs:: How @value{tramp} finds and uses programs on the remote machine. -* Remote shell setup:: Remote shell setup hints. -* Windows setup hints:: Issues with Cygwin ssh. -* Auto-save and Backup:: Auto-save and Backup. -@end menu - - -@node Connection types -@section Types of connections made to remote machines. -@cindex connection types, overview - -There are two basic types of transfer methods, each with its own -advantages and limitations. Both types of connection make use of a -remote shell access program such as @command{rsh}, @command{ssh} or -@command{telnet} to connect to the remote machine. - -This connection is used to perform many of the operations that @value{tramp} -requires to make the remote file system transparently accessible from -the local machine. It is only when visiting files that the methods -differ. - -@cindex inline methods -@cindex external methods -@cindex methods, inline -@cindex methods, external -Loading or saving a remote file requires that the content of the file -be transfered between the two machines. The content of the file can -be transfered using one of two methods: the @dfn{inline method} over -the same connection used to log in to the remote machine, or the -@dfn{external method} through another connection using a remote copy -program such as @command{rcp}, @command{scp} or @command{rsync}. - -The performance of the external methods is generally better than that -of the inline methods, at least for large files. This is caused by -the need to encode and decode the data when transferring inline. - -The one exception to this rule are the @command{scp} based transfer -methods. While these methods do see better performance when actually -transferring files, the overhead of the cryptographic negotiation at -startup may drown out the improvement in file transfer times. - -External methods should be configured such a way that they don't -require a password (with @command{ssh-agent}, or such alike). Modern -@command{scp} implementations offer options to reuse existing -@command{ssh} connections, see method @command{scpc}. If it isn't -possible, you should consider @ref{Password handling}, otherwise you -will be prompted for a password every copy action. - - -@node Inline methods -@section Inline methods -@cindex inline methods -@cindex methods, inline - -The inline methods in @value{tramp} are quite powerful and can work in -situations where you cannot use an external transfer program to connect. -Inline methods are the only methods that work when connecting to the -remote machine via telnet. (There are also strange inline methods which -allow you to transfer files between @emph{user identities} rather than -hosts, see below.) - -These methods depend on the existence of a suitable encoding and -decoding command on remote machine. Locally, @value{tramp} may be able to -use features of @value{emacsname} to decode and encode the files or -it may require access to external commands to perform that task. - -@cindex uuencode -@cindex mimencode -@cindex base-64 encoding -@value{tramp} checks the availability and usability of commands like -@command{mimencode} (part of the @command{metamail} package) or -@command{uuencode} on the remote host. The first reliable command -will be used. The search path can be customized, see @ref{Remote -Programs}. - -If both commands aren't available on the remote host, @value{tramp} -transfers a small piece of Perl code to the remote host, and tries to -apply it for encoding and decoding. - - -@table @asis -@item @option{rsh} -@cindex method rsh -@cindex rsh method - -Connect to the remote host with @command{rsh}. Due to the unsecure -connection it is recommended for very local host topology only. - -On operating systems which provide the command @command{remsh} instead -of @command{rsh}, you can use the method @option{remsh}. This is true -for HP-UX or Cray UNICOS, for example. - - -@item @option{ssh} -@cindex method ssh -@cindex ssh method - -Connect to the remote host with @command{ssh}. This is identical to -the previous option except that the @command{ssh} package is used, -making the connection more secure. - -There are also two variants, @option{ssh1} and @option{ssh2}, that -call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can -explicitly select whether you want to use the SSH protocol version 1 -or 2 to connect to the remote host. (You can also specify in -@file{~/.ssh/config}, the SSH configuration file, which protocol -should be used, and use the regular @option{ssh} method.) - -Two other variants, @option{ssh1_old} and @option{ssh2_old}, use the -@command{ssh1} and @command{ssh2} commands explicitly. If you don't -know what these are, you do not need these options. - -All the methods based on @command{ssh} have an additional kludgy -feature: you can specify a host name which looks like @file{host#42} -(the real host name, then a hash sign, then a port number). This -means to connect to the given host but to also pass @code{-p 42} as -arguments to the @command{ssh} command. - - -@item @option{telnet} -@cindex method telnet -@cindex telnet method - -Connect to the remote host with @command{telnet}. This is as unsecure -as the @option{rsh} method. - - -@item @option{su} -@cindex method su -@cindex su method - -This method does not connect to a remote host at all, rather it uses -the @command{su} program to allow you to edit files as another user. -That means, the specified host name in the file name must be either -@samp{localhost} or the host name as returned by the function -@command{(system-name)}. For an exception of this rule see -@ref{Multi-hops}. - - -@item @option{sudo} -@cindex method sudo -@cindex sudo method - -This is similar to the @option{su} method, but it uses @command{sudo} -rather than @command{su} to become a different user. - -Note that @command{sudo} must be configured to allow you to start a -shell as the user. It would be nice if it was sufficient if -@command{ls} and @command{mimencode} were allowed, but that is not -easy to implement, so I haven't got around to it, yet. - - -@item @option{sshx} -@cindex method sshx -@cindex sshx method - -As you would expect, this is similar to @option{ssh}, only a little -different. Whereas @option{ssh} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -Note that this procedure does not eliminate questions asked by -@command{ssh} itself. For example, @command{ssh} might ask ``Are you -sure you want to continue connecting?'' if the host key of the remote -host is not known. @value{tramp} does not know how to deal with such a -question (yet), therefore you will need to make sure that you can log -in without such questions. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. -For reasons unknown, some Windows ports for @command{ssh} require the -doubled @samp{-t} option. - -This supports the @samp{-p} kludge. - - -@item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex Kerberos (with krlogin method) - -This method is also similar to @option{ssh}. It only uses the -@command{krlogin -x} command to log in to the remote host. - - -@item @option{plink} -@cindex method plink -@cindex plink method - -This method is mostly interesting for Windows users using the PuTTY -implementation of SSH. It uses @samp{plink -ssh} to log in to the -remote host. - -This supports the @samp{-P} kludge. - -Additionally, the methods @option{plink1} and @option{plink2} are -provided, which call @samp{plink -1 -ssh} or @samp{plink -2 -ssh} in -order to use SSH protocol version 1 or 2 explicitly. - -CCC: Do we have to connect to the remote host once from the command -line to accept the SSH key? Maybe this can be made automatic? - -CCC: Say something about the first shell command failing. This might -be due to a wrong setting of @code{tramp-rsh-end-of-line}. - - -@item @option{plinkx} -@cindex method plinkx -@cindex plinkx method - -Another method using PuTTY on Windows. Instead of host names, it -expects PuTTY session names, calling @samp{plink -load @var{session} --t"}. User names are relevant only in case the corresponding session -hasn't defined a user name. Different port numbers must be defined in -the session. - - -@item @option{fish} -@cindex method fish -@cindex fish method - -This is an experimental implementation of the fish protocol, known from -the GNU Midnight Commander or the KDE Konqueror. @value{tramp} expects -the fish server implementation from the KDE kioslave. That means, the -file @file{~/.fishsrv.pl} is expected to reside on the remote host. - -The implementation lacks good performance. The code is offered anyway, -maybe somebody can improve the performance. - -@end table - - -@node External methods -@section External methods -@cindex methods, external -@cindex external methods - -The external methods operate through multiple channels, using the -remote shell connection for many actions while delegating file -transfers to an external transfer utility. - -This saves the overhead of encoding and decoding that multiplexing the -transfer through the one connection has with the inline methods. - -Since external methods need their own overhead opening a new channel, -all files which are smaller than @var{tramp-copy-size-limit} are still -transferred with the corresponding inline method. It should provide a -fair trade-off between both approaches. - -@table @asis -@item @option{rcp} --- @command{rsh} and @command{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) - -This method uses the @command{rsh} and @command{rcp} commands to connect -to the remote machine and transfer files. This is probably the fastest -connection method available. - -The alternative method @option{remcp} uses the @command{remsh} and -@command{rcp} commands. It should be applied on machines where -@command{remsh} is used instead of @command{rsh}. - - -@item @option{scp} --- @command{ssh} and @command{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) - -Using @command{ssh} to connect to the remote host and @command{scp} to -transfer files between the machines is the best method for securely -connecting to a remote machine and accessing files. - -The performance of this option is also quite good. It may be slower than -the inline methods when you often open and close small files however. -The cost of the cryptographic handshake at the start of an @command{scp} -session can begin to absorb the advantage that the lack of encoding and -decoding presents. - -There are also two variants, @option{scp1} and @option{scp2}, that -call @samp{ssh -1} and @samp{ssh -2}, respectively. This way, you can -explicitly select whether you want to use the SSH protocol version 1 -or 2 to connect to the remote host. (You can also specify in -@file{~/.ssh/config}, the SSH configuration file, which protocol -should be used, and use the regular @option{scp} method.) - -Two other variants, @option{scp1_old} and @option{scp2_old}, use the -@command{ssh1} and @command{ssh2} commands explicitly. If you don't -know what these are, you do not need these options. - -All the @command{ssh} based methods support the kludgy @samp{-p} -feature where you can specify a port number to connect to in the host -name. For example, the host name @file{host#42} tells @value{tramp} to -specify @samp{-p 42} in the argument list for @command{ssh}, and to -specify @samp{-P 42} in the argument list for @command{scp}. - - -@item @option{sftp} --- @command{ssh} and @command{sftp} -@cindex method sftp -@cindex sftp method -@cindex sftp (with sftp method) -@cindex ssh (with sftp method) - -That is mostly the same method as @option{scp}, but using -@command{sftp} as transfer command. So the same remarks are valid. - -This command does not work like @value{ftppackagename}, where -@command{ftp} is called interactively, and all commands are send from -within this session. Instead of, @command{ssh} is used for login. - -This method supports the @samp{-p} hack. - - -@item @option{rsync} --- @command{ssh} and @command{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) - -Using the @command{ssh} command to connect securely to the remote -machine and the @command{rsync} command to transfer files is almost -identical to the @option{scp} method. - -While @command{rsync} performs much better than @command{scp} when -transferring files that exist on both hosts, this advantage is lost if -the file exists only on one side of the connection. - -The @command{rsync} based method may be considerably faster than the -@command{rcp} based methods when writing to the remote system. Reading -files to the local machine is no faster than with a direct copy. - -This method supports the @samp{-p} hack. - - -@item @option{scpx} --- @command{ssh} and @command{scp} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) - -As you would expect, this is similar to @option{scp}, only a little -different. Whereas @option{scp} opens a normal interactive shell on -the remote host, this option uses @samp{ssh -t -t @var{host} -l -@var{user} /bin/sh} to open a connection. This is useful for users -where the normal login shell is set up to ask them a number of -questions when logging in. This procedure avoids these questions, and -just gives @value{tramp} a more-or-less `standard' login shell to work -with. - -This is also useful for Windows users where @command{ssh}, when -invoked from an @value{emacsname} buffer, tells them that it is not -allocating a pseudo tty. When this happens, the login shell is wont -to not print any shell prompt, which confuses @value{tramp} mightily. - -This method supports the @samp{-p} hack. - - -@item @option{scpc} --- @command{ssh} and @command{scp} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) - -Newer versions of @option{ssh} (for example OpenSSH 4) offer an option -@option{ControlMaster}. This allows @option{scp} to reuse an existing -@option{ssh} channel, which increases performance. - -Before you use this method, you shall check whether your @option{ssh} -implementation does support this option. Try from the command line - -@example -ssh localhost -o ControlMaster=yes -@end example - -This method supports the @samp{-p} hack. - - -@item @option{pscp} --- @command{plink} and @command{pscp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex PuTTY (with pscp method) - -This method is similar to @option{scp}, but it uses the -@command{plink} command to connect to the remote host, and it uses -@command{pscp} for transferring the files. These programs are part -of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} hack. - - -@item @option{psftp} --- @command{plink} and @command{psftp} -@cindex method psftp -@cindex psftp method -@cindex psftp (with psftp method) -@cindex plink (with psftp method) -@cindex PuTTY (with psftp method) - -As you would expect, this method is similar to @option{sftp}, but it -uses the @command{plink} command to connect to the remote host, and it -uses @command{psftp} for transferring the files. These programs are -part of PuTTY, an SSH implementation for Windows. - -This method supports the @samp{-P} hack. - - -@item @option{fcp} --- @command{fsh} and @command{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) - -This method is similar to @option{scp}, but it uses the @command{fsh} -command to connect to the remote host, and it uses @command{fcp} for -transferring the files. @command{fsh/fcp} are a front-end for -@command{ssh} which allow for reusing the same @command{ssh} session -for submitting several commands. This avoids the startup overhead of -@command{scp} (which has to establish a secure connection whenever it -is called). Note, however, that you can also use one of the inline -methods to achieve a similar effect. - -This method uses the command @samp{fsh @var{host} -l @var{user} -/bin/sh -i} to establish the connection, it does not work to just say -@command{fsh @var{host} -l @var{user}}. - -@cindex method fsh -@cindex fsh method - -There is no inline method using @command{fsh} as the multiplexing -provided by the program is not very useful in our context. @value{tramp} -opens just one connection to the remote host and then keeps it open, -anyway. - - -@item @option{ftp} -@cindex method ftp -@cindex ftp method - -This is not a native @value{tramp} method. Instead of, it forwards all -requests to @value{ftppackagename}. -@ifset xemacs -This works only for unified filenames, see @ref{Issues}. -@end ifset - - -@item @option{smb} --- @command{smbclient} -@cindex method smb -@cindex smb method - -This is another not natural @value{tramp} method. It uses the -@command{smbclient} command on different Unices in order to connect to -an SMB server. An SMB server might be a Samba (or CIFS) server on -another UNIX host or, more interesting, a host running MS Windows. So -far, it is tested towards MS Windows NT, MS Windows 2000, and MS -Windows XP. - -The first directory in the localname must be a share name on the remote -host. Remember, that the @code{$} character in which default shares -usually end, must be written @code{$$} due to environment variable -substitution in file names. If no share name is given (i.e. remote -directory @code{/}), all available shares are listed. - -Since authorization is done on share level, you will be prompted -always for a password if you access another share on the same host. -This can be suppressed by @ref{Password handling}. - -MS Windows uses for authorization both a user name and a domain name. -Because of this, the @value{tramp} syntax has been extended: you can -specify a user name which looks like @code{user%domain} (the real user -name, then a percent sign, then the domain name). So, to connect to -the machine @code{melancholia} as user @code{daniel} of the domain -@code{BIZARRE}, and edit @file{.emacs} in the home directory (share -@code{daniel$}) I would specify the filename @file{@trampfn{smb, -daniel%BIZARRE, melancholia, /daniel$$/.emacs}}. - -Depending on the Windows domain configuration, a Windows user might be -considered as domain user per default. In order to connect as local -user, the WINS name of that machine must be given as domain name. -Usually, it is the machine name in capital letters. In the example -above, the local user @code{daniel} would be specified as -@file{@trampfn{smb, daniel%MELANCHOLIA, melancholia, /daniel$$/.emacs}}. - -The domain name as well as the user name are optional. If no user -name is specified at all, the anonymous user (without password -prompting) is assumed. This is different from all other @value{tramp} -methods, where in such a case the local user name is taken. - -The @option{smb} method supports the @samp{-p} hack. - -@strong{Please note:} If @value{emacsname} runs locally under MS -Windows, this method isn't available. Instead of, you can use UNC -file names like @file{//melancholia/daniel$$/.emacs}. The only -disadvantage is that there's no possibility to specify another user -name. - -@end table - - -@ifset emacsgw -@node Gateway methods -@section Gateway methods -@cindex methods, gateway -@cindex gateway methods - -Gateway methods are not methods to access a remote host directly. -These methods are intended to pass firewalls or proxy servers. -Therefore, they can be used for proxy host declarations -(@pxref{Multi-hops}) only. - -A gateway method must come always along with a method who supports -port setting (referred to as @samp{-p} kludge). This is because -@value{tramp} targets the accompanied method to -@file{localhost#random_port}, from where the firewall or proxy server -is accessed to. - -Gateway methods support user name and password declarations. These -are used to authenticate towards the corresponding firewall or proxy -server. They can be passed only if your friendly administrator has -granted your access. - -@table @asis -@item @option{tunnel} -@cindex method tunnel -@cindex tunnel method - -This method implements an HTTP tunnel via the @command{CONNECT} -command (see RFC 2616, 2817). Any HTTP 1.1 compliant (proxy) server -shall support this command. - -As authentication method, only @option{Basic Authentication} (see RFC -2617) is implemented so far. If no port number is given in the -declaration, port @option{8080} is used for the proxy server. - - -@item @option{socks} -@cindex method socks -@cindex socks method - -The @command{socks} method provides access to SOCKSv5 servers (see -RFC 1928). @option{Username/Password Authentication} according to RFC -1929 is supported. - -The default port number of the socks server is @option{1080}, if not -specified otherwise. - -@end table -@end ifset - - -@node Default Method -@section Selecting a default method -@cindex default method - -@vindex tramp-default-method -When you select an appropriate transfer method for your typical usage -you should set the variable @code{tramp-default-method} to reflect that -choice. This variable controls which method will be used when a method -is not specified in the @value{tramp} file name. For example: - -@lisp -(setq tramp-default-method "ssh") -@end lisp - -@vindex tramp-default-method-alist -You can also specify different methods for certain user/host -combinations, via the variable @code{tramp-default-method-alist}. For -example, the following two lines specify to use the @option{ssh} -method for all user names matching @samp{john} and the @option{rsync} -method for all host names matching @samp{lily}. The third line -specifies to use the @option{su} method for the user @samp{root} on -the machine @samp{localhost}. - -@lisp -(add-to-list 'tramp-default-method-alist '("" "john" "ssh")) -(add-to-list 'tramp-default-method-alist '("lily" "" "rsync")) -(add-to-list 'tramp-default-method-alist - '("\\`localhost\\'" "\\`root\\'" "su")) -@end lisp - -@noindent -See the documentation for the variable -@code{tramp-default-method-alist} for more details. - -External methods are normally preferable to inline methods, giving -better performance. - -@xref{Inline methods}. -@xref{External methods}. - -Another consideration with the selection of transfer methods is the -environment you will use them in and, especially when used over the -Internet, the security implications of your preferred method. - -The @option{rsh} and @option{telnet} methods send your password as -plain text as you log in to the remote machine, as well as -transferring the files in such a way that the content can easily be -read from other machines. - -If you need to connect to remote systems that are accessible from the -Internet, you should give serious thought to using @option{ssh} based -methods to connect. These provide a much higher level of security, -making it a non-trivial exercise for someone to obtain your password -or read the content of the files you are editing. - - -@subsection Which method is the right one for me? -@cindex choosing the right method - -Given all of the above, you are probably thinking that this is all fine -and good, but it's not helping you to choose a method! Right you are. -As a developer, we don't want to boss our users around but give them -maximum freedom instead. However, the reality is that some users would -like to have some guidance, so here I'll try to give you this guidance -without bossing you around. You tell me whether it works @dots{} - -My suggestion is to use an inline method. For large files, external -methods might be more efficient, but I guess that most people will -want to edit mostly small files. - -I guess that these days, most people can access a remote machine by -using @command{ssh}. So I suggest that you use the @option{ssh} -method. So, type @kbd{C-x C-f @trampfn{ssh, root, otherhost, -/etc/motd} @key{RET}} to edit the @file{/etc/motd} file on the other -host. - -If you can't use @option{ssh} to log in to the remote host, then -select a method that uses a program that works. For instance, Windows -users might like the @option{plink} method which uses the PuTTY -implementation of @command{ssh}. Or you use Kerberos and thus like -@option{krlogin}. - -For the special case of editing files on the local host as another -user, see the @option{su} or @option{sudo} methods. They offer -shortened syntax for the @samp{root} account, like -@file{@trampfn{su, , , /etc/motd}}. - -People who edit large files may want to consider @option{scpc} instead -of @option{ssh}, or @option{pscp} instead of @option{plink}. These -external methods are faster than inline methods for large files. -Note, however, that external methods suffer from some limitations. -Please try first whether you really get a noticeable speed advantage -from using an external method! Maybe even for large files, inline -methods are fast enough. - - -@node Default User -@section Selecting a default user -@cindex default user - -The user part of a @value{tramp} file name can be omitted. Usually, -it is replaced by the user name you are logged in. Often, this is not -what you want. A typical use of @value{tramp} might be to edit some -files with root permissions on the local host. This case, you should -set the variable @code{tramp-default-user} to reflect that choice. -For example: - -@lisp -(setq tramp-default-user "root") -@end lisp - -@code{tramp-default-user} is regarded as obsolete, and will be removed -soon. - -@vindex tramp-default-user-alist -You can also specify different users for certain method/host -combinations, via the variable @code{tramp-default-user-alist}. For -example, if you always have to use the user @samp{john} in the domain -@samp{somewhere.else}, you can specify the following: - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" ".*\\.somewhere\\.else\\'" "john")) -@end lisp - -@noindent -See the documentation for the variable -@code{tramp-default-user-alist} for more details. - -One trap to fall in must be known. If @value{tramp} finds a default -user, this user will be passed always to the connection command as -parameter (for example @samp{ssh here.somewhere.else -l john}. If you -have specified another user for your command in its configuration -files, @value{tramp} cannot know it, and the remote access will fail. -If you have specified in the given example in @file{~/.ssh/config} the -lines - -@example -Host here.somewhere.else - User lily -@end example - -@noindent -than you must discard selecting a default user by @value{tramp}. This -will be done by setting it to @code{nil} (or @samp{lily}, likewise): - -@lisp -(add-to-list 'tramp-default-user-alist - '("ssh" "\\`here\\.somewhere\\.else\\'" nil)) -@end lisp - -The last entry in @code{tramp-default-user-alist} could be your -default user you'll apply predominantly. You shall @emph{append} it -to that list at the end: - -@lisp -(add-to-list 'tramp-default-user-alist '(nil nil "jonas") t) -@end lisp - - -@node Default Host -@section Selecting a default host -@cindex default host - -@vindex tramp-default-host -Finally, it is even possible to omit the host name part of a -@value{tramp} file name. This case, the value of the variable -@code{tramp-default-host} is used. Per default, it is initialized -with the host name your local @value{emacsname} is running. - -If you, for example, use @value{tramp} mainly to contact the host -@samp{target} as user @samp{john}, you can specify: - -@lisp -(setq tramp-default-user "john" - tramp-default-host "target") -@end lisp - -Then the simple file name @samp{@trampfn{ssh, , ,}} will connect you -to John's home directory on target. -@ifset emacs -Note, however, that the most simplification @samp{/::} won't work, -because @samp{/:} is the prefix for quoted file names. -@end ifset - - -@node Multi-hops -@section Connecting to a remote host using multiple hops -@cindex multi-hop -@cindex proxy hosts - -Sometimes, the methods described before are not sufficient. Sometimes, -it is not possible to connect to a remote host using a simple command. -For example, if you are in a secured network, you might have to log in -to a `bastion host' first before you can connect to the outside world. -Of course, the target host may also require a bastion host. - -@vindex tramp-default-proxies-alist -In order to specify such multiple hops, it is possible to define a proxy -host to pass through, via the variable -@code{tramp-default-proxies-alist}. This variable keeps a list of -triples (@var{host} @var{user} @var{proxy}). - - The first matching item specifies the proxy host to be passed for a -file name located on a remote target matching @var{user}@@@var{host}. -@var{host} and @var{user} are regular expressions or @code{nil}, which -is interpreted as a regular expression which always matches. - -@var{proxy} must be a Tramp filename which localname part is ignored. -Method and user name on @var{proxy} are optional, which is interpreted -with the default values. -@ifset emacsgw -The method must be an inline or gateway method (@pxref{Inline -methods}, @pxref{Gateway methods}). -@end ifset -@ifclear emacsgw -The method must be an inline method (@pxref{Inline methods}). -@end ifclear -If @var{proxy} is @code{nil}, no additional hop is required reaching -@var{user}@@@var{host}. - -If you, for example, must pass the host @samp{bastion.your.domain} as -user @samp{bird} for any remote host which is not located in your local -domain, you can set - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\." nil "@trampfn{ssh, bird, bastion.your.domain,}")) -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" nil nil)) -@end lisp - -Please note the order of the code. @code{add-to-list} adds elements at the -beginning of a list. Therefore, most relevant rules must be added last. - -Proxy hosts can be cascaded. If there is another host called -@samp{jump.your.domain}, which is the only one in your local domain who -is allowed connecting @samp{bastion.your.domain}, you can add another -rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`bastion\\.your\\.domain\\'" - "\\`bird\\'" - "@trampfn{ssh, , jump.your.domain,}")) -@end lisp - -@var{proxy} can contain the patterns @code{%h} or @code{%u}. These -patterns are replaced by the strings matching @var{host} or -@var{user}, respectively. - -If you, for example, wants to work as @samp{root} on hosts in the -domain @samp{your.domain}, but login as @samp{root} is disabled for -non-local access, you might add the following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh, , %h,}")) -@end lisp - -Opening @file{@trampfn{sudo, , randomhost.your.domain,}} would connect -first @samp{randomhost.your.domain} via @code{ssh} under your account -name, and perform @code{sudo -u root} on that host afterwards. It is -important to know that the given method is applied on the host which -has been reached so far. @code{sudo -u root}, applied on your local -host, wouldn't be useful here. - -This is the recommended configuration to work as @samp{root} on remote -Ubuntu hosts. - -@ifset emacsgw -Finally, @code{tramp-default-proxies-alist} can be used to pass -firewalls or proxy servers. Imagine your local network has a host -@samp{proxy.your.domain} which is used on port 3128 as HTTP proxy to -the outer world. Your friendly administrator has granted you access -under your user name to @samp{host.other.domain} on that proxy -server.@footnote{HTTP tunnels are intended for secure SSL/TLS -communication. Therefore, many proxy server restrict the tunnels to -related target ports. You might need to run your ssh server on your -target host @samp{host.other.domain} on such a port, like 443 (https). -See @uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} -for discussion of ethical issues.} You would need to add the -following rule: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`host\\.other\\.domain\\'" nil - "@trampfn{tunnel, , proxy.your.domain#3128,}")) -@end lisp - -Gateway methods can be declared as first hop only in a multiple hop -chain. -@end ifset - - -@node Customizing Methods -@section Using Non-Standard Methods -@cindex customizing methods -@cindex using non-standard methods -@cindex create your own methods - -There is a variable @code{tramp-methods} which you can change if the -predefined methods don't seem right. - -For the time being, I'll refer you to the Lisp documentation of that -variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. - - -@node Customizing Completion -@section Selecting config files for user/host name completion -@cindex customizing completion -@cindex selecting config files -@vindex tramp-completion-function-alist - -The variable @code{tramp-completion-function-alist} is intended to -customize which files are taken into account for user and host name -completion (@pxref{Filename completion}). For every method, it keeps -a set of configuration files, accompanied by a Lisp function able to -parse that file. Entries in @code{tramp-completion-function-alist} -have the form (@var{method} @var{pair1} @var{pair2} ...). - -Each @var{pair} is composed of (@var{function} @var{file}). -@var{function} is responsible to extract user names and host names -from @var{file} for completion. There are two functions which access -this variable: - -@defun tramp-get-completion-function method -This function returns the list of completion functions for @var{method}. - -Example: -@example -(tramp-get-completion-function "rsh") - - @result{} ((tramp-parse-rhosts "/etc/hosts.equiv") - (tramp-parse-rhosts "~/.rhosts")) -@end example -@end defun - -@defun tramp-set-completion-function method function-list -This function sets @var{function-list} as list of completion functions -for @var{method}. - -Example: -@example -(tramp-set-completion-function "ssh" - '((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config"))) - - @result{} ((tramp-parse-sconfig "/etc/ssh_config") - (tramp-parse-sconfig "~/.ssh/config")) -@end example -@end defun - -The following predefined functions parsing configuration files exist: - -@table @asis -@item @code{tramp-parse-rhosts} -@findex tramp-parse-rhosts - -This function parses files which are syntactical equivalent to -@file{~/.rhosts}. It returns both host names and user names, if -specified. - -@item @code{tramp-parse-shosts} -@findex tramp-parse-shosts - -This function parses files which are syntactical equivalent to -@file{~/.ssh/known_hosts}. Since there are no user names specified -in such files, it can return host names only. - -@item @code{tramp-parse-sconfig} -@findex tramp-parse-shosts - -This function returns the host nicknames defined by @code{Host} entries -in @file{~/.ssh/config} style files. - -@item @code{tramp-parse-shostkeys} -@findex tramp-parse-shostkeys - -SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and -@file{~/ssh2/hostkeys/*}. Hosts are coded in file names -@file{hostkey_@var{portnumber}_@var{host-name}.pub}. User names -are always @code{nil}. - -@item @code{tramp-parse-sknownhosts} -@findex tramp-parse-shostkeys - -Another SSH2 style parsing of directories like -@file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This -case, hosts names are coded in file names -@file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. - -@item @code{tramp-parse-hosts} -@findex tramp-parse-hosts - -A function dedicated to @file{/etc/hosts} style files. It returns -host names only. - -@item @code{tramp-parse-passwd} -@findex tramp-parse-passwd - -A function which parses @file{/etc/passwd} like files. Obviously, it -can return user names only. - -@item @code{tramp-parse-netrc} -@findex tramp-parse-netrc - -Finally, a function which parses @file{~/.netrc} like files. -@end table - -If you want to keep your own data in a file, with your own structure, -you might provide such a function as well. This function must meet -the following conventions: - -@defun my-tramp-parse file -@var{file} must be either a file name on your host, or @code{nil}. -The function must return a list of (@var{user} @var{host}), which are -taken as candidates for user and host name completion. - -Example: -@example -(my-tramp-parse "~/.my-tramp-hosts") - - @result{} ((nil "toto") ("daniel" "melancholia")) -@end example -@end defun - - -@node Password handling -@section Reusing passwords for several connections. -@cindex passwords - -Sometimes it is necessary to connect to the same remote host several -times. Reentering passwords again and again would be annoying, when -the chosen method does not support access without password prompt -through own configuration. - -The best recommendation is to use the method's own mechanism for -password handling. Consider @command{ssh-agent} for @option{ssh}-like -methods, or @command{pageant} for @option{plink}-like methods. - -However, if you cannot apply such native password handling, -@value{tramp} offers altenatives. - - -@anchor{auth-sources} -@subsection Using an authentication file - -@vindex auth-sources -The package @file{auth-source.el}, originally developed in No Gnus, -offers the possibility to read passwords from a file, like FTP does it -from @file{~/.netrc}. The default authentication file is -@file{~/.authinfo.gpg}, this can be changed via the variable -@code{auth-sources}. - -@noindent -A typical entry in the authentication file would be - -@example -machine melancholia port scp login daniel password geheim -@end example - -The port can be any @value{tramp} method (@pxref{Inline methods}, -@pxref{External methods}), to match only this method. When you omit -the port, you match all @value{tramp} methods. - - -@anchor{password-cache} -@subsection Caching passwords - -If there is no authentication file, @value{tramp} caches the passwords -entered by you. They will be reused next time if a connection needs -them for the same user name and host name, independently of the -connection method. - -@vindex password-cache-expiry -Passwords are not saved permanently, that means the password caching -is limited to the lifetime of your @value{emacsname} session. You -can influence the lifetime of password caching by customizing the -variable @code{password-cache-expiry}. The value is the number of -seconds how long passwords are cached. Setting it to @code{nil} -disables the expiration. - -@vindex password-cache -If you don't like this feature for security reasons, password caching -can be disabled totally by customizing the variable -@code{password-cache} (setting it to @code{nil}). - -Implementation Note: password caching is based on the package -@file{password-cache.el}. For the time being, it is activated only -when this package is seen in the @code{load-path} while loading -@value{tramp}. -@ifset installchapter -If you don't use No Gnus, you can take @file{password.el} from the -@value{tramp} @file{contrib} directory, see @ref{Installation -parameters}. -@end ifset - - -@node Connection caching -@section Reusing connection related information. -@cindex caching - -@vindex tramp-persistency-file-name -In order to reduce initial connection time, @value{tramp} stores -connection related information persistently. The variable -@code{tramp-persistency-file-name} keeps the file name where these -information are written. Its default value is -@ifset emacs -@file{~/.emacs.d/tramp}. -@end ifset -@ifset xemacs -@file{~/.xemacs/tramp}. -@end ifset -It is recommended to choose a local file name. - -@value{tramp} reads this file during startup, and writes it when -exiting @value{emacsname}. You can simply remove this file if -@value{tramp} shall be urged to recompute these information next -@value{emacsname} startup time. - -Using such persistent information can be disabled by setting -@code{tramp-persistency-file-name} to @code{nil}. - -Once consequence of reusing connection related information is that -@var{tramp} needs to distinguish hosts. If you, for example, run a -local @code{sshd} on port 3001, which tunnels @command{ssh} to another -host, you could access both @file{@trampfn{ssh, , localhost,}} and -@file{@trampfn{ssh, , localhost#3001,}}. @var{tramp} would use the -same host related information (like paths, Perl variants, etc) for -both connections, although the information is valid only for one of -them. - -In order to avoid trouble, you must use another host name for one of -the connections, like introducing a @option{Host} section in -@file{~/.ssh/config} (@pxref{Frequently Asked Questions}) or applying -multiple hops (@pxref{Multi-hops}). - -When @value{tramp} detects a changed operating system version on a -remote host (via the command @command{uname -sr}), it flushes all -connection related information for this host, and opens the -connection, again. - - -@node Remote Programs -@section How @value{tramp} finds and uses programs on the remote machine. - -@value{tramp} depends on a number of programs on the remote host in order to -function, including @command{ls}, @command{test}, @command{find} and -@command{cat}. - -In addition to these required tools, there are various tools that may be -required based on the connection method. See @ref{Inline methods} and -@ref{External methods} for details on these. - -Certain other tools, such as @command{perl} (or @command{perl5}) and -@command{grep} will be used if they can be found. When they are -available, they are used to improve the performance and accuracy of -remote file access. - -@vindex tramp-remote-path -When @value{tramp} connects to the remote machine, it searches for the -programs that it can use. The variable @code{tramp-remote-path} -controls the directories searched on the remote machine. - -By default, this is set to a reasonable set of defaults for most -machines. The symbol @code{tramp-default-remote-path} is a place -holder, it is replaced by the list of directories received via the -command @command{getconf PATH} on your remote machine. For example, -on GNU Debian this is @file{/bin:/usr/bin}, whereas on Solaris this is -@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin}. It is -recommended to apply this symbol on top of @code{tramp-remote-path}. - -It is possible, however, that your local (or remote ;) system -administrator has put the tools you want in some obscure local -directory. - -In this case, you can still use them with @value{tramp}. You simply -need to add code to your @file{.emacs} to add the directory to the -remote path. This will then be searched by @value{tramp} when you -connect and the software found. - -To add a directory to the remote search path, you could use code such -as: - -@lisp -@i{;; We load @value{tramp} to define the variable.} -(require 'tramp) -@i{;; We have @command{perl} in "/usr/local/perl/bin"} -(add-to-list 'tramp-remote-path "/usr/local/perl/bin") -@end lisp - -@value{tramp} caches several information, like the Perl binary -location. The changed remote search path wouldn't affect these -settings. In order to force @value{tramp} to recompute these values, -you must exit @value{emacsname}, remove your persistency file -(@pxref{Connection caching}), and restart @value{emacsname}. - - -@node Remote shell setup -@section Remote shell setup hints -@cindex remote shell setup -@cindex @file{.profile} file -@cindex @file{.login} file -@cindex shell init files - -As explained in the @ref{Overview} section, @value{tramp} connects to the -remote host and talks to the shell it finds there. Of course, when you -log in, the shell executes its init files. Suppose your init file -requires you to enter the birth date of your mother; clearly @value{tramp} -does not know this and hence fails to log you in to that host. - -There are different possible strategies for pursuing this problem. One -strategy is to enable @value{tramp} to deal with all possible situations. -This is a losing battle, since it is not possible to deal with -@emph{all} situations. The other strategy is to require you to set up -the remote host such that it behaves like @value{tramp} expects. This might -be inconvenient because you have to invest a lot of effort into shell -setup before you can begin to use @value{tramp}. - -The package, therefore, pursues a combined approach. It tries to -figure out some of the more common setups, and only requires you to -avoid really exotic stuff. For example, it looks through a list of -directories to find some programs on the remote host. And also, it -knows that it is not obvious how to check whether a file exists, and -therefore it tries different possibilities. (On some hosts and -shells, the command @command{test -e} does the trick, on some hosts -the shell builtin doesn't work but the program @command{/usr/bin/test --e} or @command{/bin/test -e} works. And on still other hosts, -@command{ls -d} is the right way to do this.) - -Below you find a discussion of a few things that @value{tramp} does not deal -with, and that you therefore have to set up correctly. - -@table @asis -@item @var{shell-prompt-pattern} -@vindex shell-prompt-pattern - -After logging in to the remote host, @value{tramp} has to wait for the remote -shell startup to finish before it can send commands to the remote -shell. The strategy here is to wait for the shell prompt. In order to -recognize the shell prompt, the variable @code{shell-prompt-pattern} has -to be set correctly to recognize the shell prompt on the remote host. - -Note that @value{tramp} requires the match for @code{shell-prompt-pattern} -to be at the end of the buffer. Many people have something like the -following as the value for the variable: @code{"^[^>$][>$] *"}. Now -suppose your shell prompt is @code{a c $ }. In this case, -@value{tramp} recognizes the @code{>} character as the end of the prompt, -but it is not at the end of the buffer. - -@item @var{tramp-shell-prompt-pattern} -@vindex tramp-shell-prompt-pattern - -This regular expression is used by @value{tramp} in the same way as -@code{shell-prompt-pattern}, to match prompts from the remote shell. -This second variable exists because the prompt from the remote shell -might be different from the prompt from a local shell --- after all, -the whole point of @value{tramp} is to log in to remote hosts as a -different user. The default value of -@code{tramp-shell-prompt-pattern} is the same as the default value of -@code{shell-prompt-pattern}, which is reported to work well in many -circumstances. - -@item @var{tramp-password-prompt-regexp} -@vindex tramp-password-prompt-regexp -@vindex tramp-wrong-passwd-regexp - -During login, @value{tramp} might be forced to enter a password or a -passphrase. The difference between both is that a password is -requested from the shell on the remote host, while a passphrase is -needed for accessing local authentication information, like your ssh -key. - -@var{tramp-password-prompt-regexp} handles the detection of such -requests for English environments. When you use another localization -of your (local or remote) host, you might need to adapt this. Example: - -@lisp -(setq - tramp-password-prompt-regexp - (concat - "^.*" - (regexp-opt - '("passphrase" "Passphrase" - ;; English - "password" "Password" - ;; Deutsch - "passwort" "Passwort" - ;; Fran@,{c}ais - "mot de passe" "Mot de passe") t) - ".*:? *")) -@end lisp - -In parallel, it might also be necessary to adapt -@var{tramp-wrong-passwd-regexp}. - -@item @command{tset} and other questions -@cindex Unix command tset -@cindex tset Unix command - -Some people invoke the @command{tset} program from their shell startup -scripts which asks the user about the terminal type of the shell. -Maybe some shells ask other questions when they are started. -@value{tramp} does not know how to answer these questions. There are -two approaches for dealing with this problem. One approach is to take -care that the shell does not ask any questions when invoked from -@value{tramp}. You can do this by checking the @code{TERM} -environment variable, it will be set to @code{dumb} when connecting. - -@vindex tramp-terminal-type -The variable @code{tramp-terminal-type} can be used to change this value -to @code{dumb}. - -@vindex tramp-actions-before-shell -The other approach is to teach @value{tramp} about these questions. See -the variable @code{tramp-actions-before-shell}. Example: - -@lisp -(defconst my-tramp-prompt-regexp - (concat (regexp-opt '("Enter the birth date of your mother:") t) - "\\s-*") - "Regular expression matching my login prompt question.") - -(defun my-tramp-action (proc vec) - "Enter \"19000101\" in order to give a correct answer." - (save-window-excursion - (with-current-buffer (tramp-get-connection-buffer vec) - (tramp-message vec 6 "\n%s" (buffer-string)) - (tramp-send-string vec "19000101")))) - -(add-to-list 'tramp-actions-before-shell - '(my-tramp-prompt-regexp my-tramp-action)) -@end lisp - - -@item Environment variables named like users in @file{.profile} - -If you have a user named frumple and set the variable @code{FRUMPLE} in -your shell environment, then this might cause trouble. Maybe rename -the variable to @code{FRUMPLE_DIR} or the like. - -This weird effect was actually reported by a @value{tramp} user! - - -@item Non-Bourne commands in @file{.profile} - -After logging in to the remote host, @value{tramp} issues the command -@command{exec /bin/sh}. (Actually, the command is slightly -different.) When @command{/bin/sh} is executed, it reads some init -files, such as @file{~/.shrc} or @file{~/.profile}. - -Now, some people have a login shell which is not @code{/bin/sh} but a -Bourne-ish shell such as bash or ksh. Some of these people might put -their shell setup into the files @file{~/.shrc} or @file{~/.profile}. -This way, it is possible for non-Bourne constructs to end up in those -files. Then, @command{exec /bin/sh} might cause the Bourne shell to -barf on those constructs. - -As an example, imagine somebody putting @command{export FOO=bar} into -the file @file{~/.profile}. The standard Bourne shell does not -understand this syntax and will emit a syntax error when it reaches -this line. - -Another example is the tilde (@code{~}) character, say when adding -@file{~/bin} to @code{$PATH}. Many Bourne shells will not expand this -character, and since there is usually no directory whose name consists -of the single character tilde, strange things will happen. - -What can you do about this? - -Well, one possibility is to make sure that everything in -@file{~/.shrc} and @file{~/.profile} on all remote hosts is -Bourne-compatible. In the above example, instead of @command{export -FOO=bar}, you might use @command{FOO=bar; export FOO} instead. - -The other possibility is to put your non-Bourne shell setup into some -other files. For example, bash reads the file @file{~/.bash_profile} -instead of @file{~/.profile}, if the former exists. So bash -aficionados just rename their @file{~/.profile} to -@file{~/.bash_profile} on all remote hosts, and Bob's your uncle. - -The @value{tramp} developers would like to circumvent this problem, so -if you have an idea about it, please tell us. However, we are afraid -it is not that simple: before saying @command{exec /bin/sh}, -@value{tramp} does not know which kind of shell it might be talking -to. It could be a Bourne-ish shell like ksh or bash, or it could be a -csh derivative like tcsh, or it could be zsh, or even rc. If the -shell is Bourne-ish already, then it might be prudent to omit the -@command{exec /bin/sh} step. But how to find out if the shell is -Bourne-ish? - -@end table - - -@node Auto-save and Backup -@section Auto-save and Backup configuration -@cindex auto-save -@cindex backup -@ifset emacs -@vindex backup-directory-alist -@end ifset -@ifset xemacs -@vindex bkup-backup-directory-info -@end ifset - -Normally, @value{emacsname} writes backup files to the same directory -as the original files, but this behavior can be changed via the -variable -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -In connection with @value{tramp}, this can have unexpected side -effects. Suppose that you specify that all backups should go to the -directory @file{~/.emacs.d/backups/}, and then you edit the file -@file{@trampfn{su, root, localhost, /etc/secretfile}}. The effect is -that the backup file will be owned by you and not by root, thus -possibly enabling others to see it even if they were not intended to -see it. - -When -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -is @code{nil} (the default), such problems do not occur. - -Therefore, it is useful to set special values for @value{tramp} -files. For example, the following statement effectively `turns off' -the effect of -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -for @value{tramp} files: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons tramp-file-name-regexp nil)) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list tramp-file-name-regexp "")) -@end lisp -@end ifset - -Another possibility is to use the @value{tramp} variable -@ifset emacs -@code{tramp-backup-directory-alist}. -@end ifset -@ifset xemacs -@code{tramp-bkup-backup-directory-info}. -@end ifset -This variable has the same meaning like -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset -If a @value{tramp} file is backed up, and DIRECTORY is an absolute -local file name, DIRECTORY is prepended with the @value{tramp} file -name prefix of the file to be backed up. - -@noindent -Example: - -@ifset emacs -@lisp -(add-to-list 'backup-directory-alist - (cons "." "~/.emacs.d/backups/")) -(setq tramp-backup-directory-alist backup-directory-alist) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list "." "~/.emacs.d/backups/" 'full-path)) -(setq tramp-bkup-backup-directory-info bkup-backup-directory-info) -@end lisp -@end ifset - -@noindent -The backup file name of @file{@trampfn{su, root, localhost, -/etc/secretfile}} would be -@ifset emacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} -@end ifset -@ifset xemacs -@file{@trampfn{su, root, localhost, -~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} -@end ifset - -The same problem can happen with auto-saving files. -@ifset emacs -Since @value{emacsname} 21, the variable -@code{auto-save-file-name-transforms} keeps information, on which -directory an auto-saved file should go. By default, it is initialized -for @value{tramp} files to the local temporary directory. - -On some versions of @value{emacsname}, namely the version built for -Debian GNU/Linux, the variable @code{auto-save-file-name-transforms} -contains the directory where @value{emacsname} was built. A -workaround is to manually set the variable to a sane value. - -If auto-saved files should go into the same directory as the original -files, @code{auto-save-file-name-transforms} should be set to @code{nil}. - -Another possibility is to set the variable -@code{tramp-auto-save-directory} to a proper value. -@end ifset -@ifset xemacs -For this purpose you can set the variable @code{auto-save-directory} -to a proper value. -@end ifset - - -@node Windows setup hints -@section Issues with Cygwin ssh -@cindex Cygwin, issues - -This section needs a lot of work! Please help. - -@cindex method sshx with Cygwin -@cindex sshx method with Cygwin -The recent Cygwin installation of @command{ssh} works only with a -Cygwinized @value{emacsname}. You can check it by typing @kbd{M-x -eshell}, and starting @kbd{ssh test.machine}. The problem is evident -if you see a message like this: - -@example -Pseudo-terminal will not be allocated because stdin is not a terminal. -@end example - -Older @command{ssh} versions of Cygwin are told to cooperate with -@value{tramp} selecting @option{sshx} as the connection method. You -can find information about setting up Cygwin in their FAQ at -@uref{http://cygwin.com/faq/}. - -@cindex method scpx with Cygwin -@cindex scpx method with Cygwin -If you wish to use the @option{scpx} connection method, then you might -have the problem that @value{emacsname} calls @command{scp} with a -Windows filename such as @code{c:/foo}. The Cygwin version of -@command{scp} does not know about Windows filenames and interprets -this as a remote filename on the host @code{c}. - -One possible workaround is to write a wrapper script for @option{scp} -which converts the Windows filename to a Cygwinized filename. - -@cindex Cygwin and ssh-agent -@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows -If you want to use either @option{ssh} based method on Windows, then -you might encounter problems with @command{ssh-agent}. Using this -program, you can avoid typing the pass-phrase every time you log in. -However, if you start @value{emacsname} from a desktop shortcut, then -the environment variable @code{SSH_AUTH_SOCK} is not set and so -@value{emacsname} and thus @value{tramp} and thus @command{ssh} and -@command{scp} started from @value{tramp} cannot communicate with -@command{ssh-agent}. It works better to start @value{emacsname} from -the shell. - -If anyone knows how to start @command{ssh-agent} under Windows in such a -way that desktop shortcuts can profit, please holler. I don't really -know anything at all about Windows@dots{} - - -@node Usage -@chapter Using @value{tramp} -@cindex using @value{tramp} - -Once you have installed @value{tramp} it will operate fairly -transparently. You will be able to access files on any remote machine -that you can log in to as though they were local. - -Files are specified to @value{tramp} using a formalized syntax specifying the -details of the system to connect to. This is similar to the syntax used -by the @value{ftppackagename} package. - -@cindex type-ahead -Something that might happen which surprises you is that -@value{emacsname} remembers all your keystrokes, so if you see a -password prompt from @value{emacsname}, say, and hit @kbd{@key{RET}} -twice instead of once, then the second keystroke will be processed by -@value{emacsname} after @value{tramp} has done its thing. Why, this -type-ahead is normal behavior, you say. Right you are, but be aware -that opening a remote file might take quite a while, maybe half a -minute when a connection needs to be opened. Maybe after half a -minute you have already forgotten that you hit that key! - -@menu -* Filename Syntax:: @value{tramp} filename conventions. -* Alternative Syntax:: URL-like filename syntax. -* Filename completion:: Filename completion. -* Remote processes:: Integration with other @value{emacsname} packages. -* Cleanup remote connections:: Cleanup remote connections. -@end menu - - -@node Filename Syntax -@section @value{tramp} filename conventions -@cindex filename syntax -@cindex filename examples - -To access the file @var{localname} on the remote machine @var{machine} -you would specify the filename @file{@trampfn{, , machine, -localname}}. This will connect to @var{machine} and transfer the file -using the default method. @xref{Default Method}. - -Some examples of @value{tramp} filenames are shown below. - -@table @file -@item @trampfn{, , melancholia, .emacs} -Edit the file @file{.emacs} in your home directory on the machine -@code{melancholia}. - -@item @trampfn{, , melancholia.danann.net, .emacs} -This edits the same file, using the fully qualified domain name of -the machine. - -@item @trampfn{, , melancholia, ~/.emacs} -This also edits the same file --- the @file{~} is expanded to your -home directory on the remote machine, just like it is locally. - -@item @trampfn{, , melancholia, ~daniel/.emacs} -This edits the file @file{.emacs} in the home directory of the user -@code{daniel} on the machine @code{melancholia}. The @file{~} -construct is expanded to the home directory of that user on the remote -machine. - -@item @trampfn{, , melancholia, /etc/squid.conf} -This edits the file @file{/etc/squid.conf} on the machine -@code{melancholia}. - -@end table - -@var{machine} can also be an IPv4 or IPv6 address, like in -@file{@trampfn{, , 127.0.0.1, .emacs}} or @file{@trampfn{, , -@value{ipv6prefix}::1@value{ipv6postfix}, .emacs}}. -@ifset emacs -For syntactical reasons, IPv6 addresses must be embedded in square -brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. -@end ifset - -Unless you specify a different name to use, @value{tramp} will use the -current local user name as the remote user name to log in with. If you -need to log in as a different user, you can specify the user name as -part of the filename. - -To log in to the remote machine as a specific user, you use the syntax -@file{@trampfn{, user, machine, path/to.file}}. That means that -connecting to @code{melancholia} as @code{daniel} and editing -@file{.emacs} in your home directory you would specify -@file{@trampfn{, daniel, melancholia, .emacs}}. - -It is also possible to specify other file transfer methods -(@pxref{Inline methods}, @pxref{External methods}) as part of the -filename. -@ifset emacs -This is done by putting the method before the user and host name, as -in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the -trailing colon). -@end ifset -@ifset xemacs -This is done by replacing the initial @file{@value{prefix}} with -@file{@value{prefix}@value{postfixhop}}. (Note the trailing -slash!). -@end ifset -The user, machine and file specification remain the same. - -So, to connect to the machine @code{melancholia} as @code{daniel}, -using the @option{ssh} method to transfer files, and edit -@file{.emacs} in my home directory I would specify the filename -@file{@trampfn{ssh, daniel, melancholia, .emacs}}. - - -@node Alternative Syntax -@section URL-like filename syntax -@cindex filename syntax -@cindex filename examples - -Additionally to the syntax described in the previous chapter, it is -possible to use a URL-like syntax for @value{tramp}. This can be -switched on by customizing the variable @code{tramp-syntax}. Please -note that this feature is experimental for the time being. - -The variable @code{tramp-syntax} must be set before requiring @value{tramp}: - -@lisp -(setq tramp-syntax 'url) -(require 'tramp) -@end lisp - -Then, a @value{tramp} filename would look like this: -@file{/@var{method}://@var{user}@@@var{machine}:@var{port}/@var{path/to.file}}. -@file{/@var{method}://} is mandatory, all other parts are optional. -@file{:@var{port}} is useful for methods only who support this. - -The last example from the previous section would look like this: -@file{/ssh://daniel@@melancholia/.emacs}. - -For the time being, @code{tramp-syntax} can have the following values: - -@itemize @w{} -@ifset emacs -@item @code{ftp} -- That is the default syntax -@item @code{url} -- URL-like syntax -@end ifset -@ifset xemacs -@item @code{sep} -- That is the default syntax -@item @code{url} -- URL-like syntax -@item @code{ftp} -- EFS-like syntax -@end ifset -@end itemize - - -@node Filename completion -@section Filename completion -@cindex filename completion - -Filename completion works with @value{tramp} for completion of method -names, of user names and of machine names as well as for completion of -file names on remote machines. -@ifset emacs -In order to enable this, Partial Completion mode must be set on. -@ifinfo -@xref{Completion Options, , , @value{emacsdir}}. -@end ifinfo -@end ifset - -If you, for example, type @kbd{C-x C-f @value{prefix}t -@key{TAB}}, @value{tramp} might give you as result the choice for - -@example -@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@ifset emacs -@item @value{prefixhop}telnet@value{postfixhop} @tab tmp/ -@item @value{prefixhop}toto@value{postfix} @tab -@end ifset -@ifset xemacs -@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix} -@end ifset -@end multitable -@end example - -@samp{@value{prefixhop}telnet@value{postfixhop}} -is a possible completion for the respective method, -@ifset emacs -@samp{tmp/} stands for the directory @file{/tmp} on your local -machine, -@end ifset -and @samp{@value{prefixhop}toto@value{postfix}} -might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} -file (given you're using default method @option{ssh}). - -If you go on to type @kbd{e @key{TAB}}, the minibuffer is completed to -@samp{@value{prefix}telnet@value{postfixhop}}. -Next @kbd{@key{TAB}} brings you all machine names @value{tramp} detects in -your @file{/etc/hosts} file, let's say - -@example -@multitable {@trampfn{telnet, , melancholia.danann.net,}} {@trampfn{telnet, , 192.168.0.1,}} -@item @trampfn{telnet, , 127.0.0.1,} @tab @trampfn{telnet, , 192.168.0.1,} -@item @trampfn{telnet, , @value{ipv6prefix}::1@value{ipv6postfix},} @tab @trampfn{telnet, , localhost,} -@item @trampfn{telnet, , melancholia.danann.net,} @tab @trampfn{telnet, , melancholia,} -@end multitable -@end example - -Now you can choose the desired machine, and you can continue to -complete file names on that machine. - -If the configuration files (@pxref{Customizing Completion}), which -@value{tramp} uses for analysis of completion, offer user names, those user -names will be taken into account as well. - -Remote machines, which have been visited in the past and kept -persistently (@pxref{Connection caching}), will be offered too. - -Once the remote machine identification is completed, it comes to -filename completion on the remote host. This works pretty much like -for files on the local host, with the exception that minibuffer -killing via a double-slash works only on the filename part, except -that filename part starts with @file{//}. -@ifset emacs -A triple-slash stands for the default behavior. -@end ifset -@ifinfo -@xref{Minibuffer File, , , @value{emacsdir}}. -@end ifinfo - -@noindent -Example: - -@example -@ifset emacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//etc} @key{TAB}} - @print{} @trampfn{telnet, , melancholia, /etc} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //etc} @key{TAB}} - @print{} /etc - -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin///etc} @key{TAB}} - @print{} /etc -@end ifset - -@ifset xemacs -@kbd{C-x C-f @trampfn{telnet, , melancholia, /usr/local/bin//}} - @print{} @trampfn{telnet, , melancholia, /} - -@kbd{C-x C-f @trampfn{telnet, , melancholia, //}} - @print{} / -@end ifset -@end example - -A remote directory might have changed its contents out of -@value{emacsname} control, for example by creation or deletion of -files by other processes. Therefore, during filename completion the -remote directory contents is reread regularly in order to detect such -changes, which would be invisible otherwise (@pxref{Connection caching}). - -@defopt tramp-completion-reread-directory-timeout -This variable defines the number of seconds since last remote command -before rereading a directory contents. A value of 0 would require an -immediate reread during filename completion, @code{nil} means to use -always cached values for the directory contents. -@end defopt - - -@node Remote processes -@section Integration with other @value{emacsname} packages. -@cindex compile -@cindex recompile - -@value{tramp} supports running processes on a remote host. This -allows to exploit @value{emacsname} packages without modification for -remote file names. It does not work for the @option{ftp} and -@option{smb} methods. - -Remote processes are started when a corresponding command is executed -from a buffer belonging to a remote file or directory. Up to now, the -packages @file{compile.el} (commands like @code{compile} and -@code{grep}) and @file{gud.el} (@code{gdb} or @code{perldb}) have been -integrated. Integration of further packages is planned, any help for -this is welcome! - -When your program is not found in the default search path -@value{tramp} sets on the remote machine, you should either use an -absolute path, or extend @code{tramp-remote-path} (see @ref{Remote -Programs}): - -@lisp -(add-to-list 'tramp-remote-path "~/bin") -(add-to-list 'tramp-remote-path "/appli/pub/bin") -@end lisp - -The environment for your program can be adapted by customizing -@code{tramp-remote-process-environment}. This variable is a list of -strings. It is structured like @code{process-environment}. Each -element is a string of the form ENVVARNAME=VALUE. An entry -ENVVARNAME= disables the corresponding environment variable, which -might have been set in your init file like @file{~/.profile}. - -@noindent -Adding an entry can be performed via @code{add-to-list}: - -@lisp -(add-to-list 'tramp-remote-process-environment "JAVA_HOME=/opt/java") -@end lisp - -Changing or removing an existing entry is not encouraged. The default -values are chosen for proper @value{tramp} work. Nevertheless, if for -example a paranoid system administrator disallows changing the -@var{$HISTORY} environment variable, you can customize -@code{tramp-remote-process-environment}, or you can apply the -following code in your @file{.emacs}: - -@lisp -(let ((process-environment tramp-remote-process-environment)) - (setenv "HISTORY" nil) - (setq tramp-remote-process-environment process-environment)) -@end lisp - -If you use other @value{emacsname} packages which do not run -out-of-the-box on a remote host, please let us know. We will try to -integrate them as well. @xref{Bug Reports}. - - -@subsection Running shell-command on a remote host -@cindex shell-command - -@code{shell-command} allows to execute commands in a shell, either -synchronously, either asynchronously. This works also on remote -hosts. Example: - -@example -@kbd{C-x C-f @trampfn{sudo, , , } @key{RET}} -@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} -@end example - -You will see the buffer @file{*Async Shell Command*}, containing the -continous output of the @command{tail} command. - - -@subsection Running eshell on a remote host -@cindex eshell - -@value{tramp} is integrated into @file{eshell.el}. That is, you can -open an interactive shell on your remote host, and run commands there. -After you have started @code{eshell}, you could perform commands like -this: - -@example -@b{~ $} cd @trampfn{sudo, , , /etc} @key{RET} -@b{@trampfn{sudo, root, host, /etc} $} hostname @key{RET} -host -@b{@trampfn{sudo, root, host, /etc} $} id @key{RET} -uid=0(root) gid=0(root) groups=0(root) -@b{@trampfn{sudo, root, host, /etc} $} find-file shadow @key{RET} -# -@b{@trampfn{sudo, root, host, /etc} $} -@end example - - -@anchor{Running a debugger on a remote host} -@subsection Running a debugger on a remote host -@cindex gud -@cindex gdb -@cindex perldb - -@file{gud.el} offers an unified interface to several symbolic -debuggers -@ifset emacs -@ifinfo -(@ref{Debuggers, , , @value{emacsdir}}). -@end ifinfo -@end ifset -With @value{tramp}, it is possible to debug programs on -remote hosts. You can call @code{gdb} with a remote file name: - -@example -@kbd{M-x gdb @key{RET}} -@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh, , host, ~/myprog} @key{RET} -@end example - -The file name can also be relative to a remote default directory. -Given you are in a buffer that belongs to the remote directory -@trampfn{ssh, , host, /home/user}, you could call - -@example -@kbd{M-x perldb @key{RET}} -@b{Run perldb (like this):} perl -d myprog.pl @key{RET} -@end example - -It is not possible to use just the absolute local part of a remote -file name as program to debug, like @kbd{perl -d -/home/user/myprog.pl}, though. - -Arguments of the program to be debugged are taken literally. That -means, file names as arguments must be given as ordinary relative or -absolute file names, without any remote specification. - - -@node Cleanup remote connections -@section Cleanup remote connections. -@cindex cleanup - -Sometimes it is useful to cleanup remote connections. The following -commands support this. - -@deffn Command tramp-cleanup-connection vec -This command flushes all connection related objects. @option{vec} is -the internal representation of a remote connection. Called -interactively, the command offers all active remote connections in the -minibuffer as remote file name prefix like @file{@trampfn{method, -user, host, }}. The cleanup includes password cache (@pxref{Password -handling}), file cache, connection cache (@pxref{Connection caching}), -connection buffers. -@end deffn - -@deffn Command tramp-cleanup-all-connections -This command flushes objects for all active remote connections. The -same objects are removed as in @code{tramp-cleanup-connection}. -@end deffn - -@deffn Command tramp-cleanup-all-buffers -Like in @code{tramp-cleanup-all-connections}, all remote connections -are cleaned up. Additionally all buffers, which are related to a -remote connection, are killed. -@end deffn - - -@node Bug Reports -@chapter Reporting Bugs and Problems -@cindex bug reports - -Bugs and problems with @value{tramp} are actively worked on by the -development team. Feature requests and suggestions are also more than -welcome. - -The @value{tramp} mailing list is a great place to get information on -working with @value{tramp}, solving problems and general discussion -and advice on topics relating to the package. It is moderated so -non-subscribers can post but messages will be delayed, possibly up to -48 hours (or longer in case of holidays), until the moderator approves -your message. - -The mailing list is at @email{tramp-devel@@gnu.org}. Messages sent to -this address go to all the subscribers. This is @emph{not} the address -to send subscription requests to. - -Subscribing to the list is performed via -@uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, -the @value{tramp} Mail Subscription Page}. - -@findex tramp-bug -To report a bug in @value{tramp}, you should execute @kbd{M-x -tramp-bug}. This will automatically generate a buffer with the details -of your system and @value{tramp} version. - -When submitting a bug report, please try to describe in excruciating -detail the steps required to reproduce the problem, the setup of the -remote machine and any special conditions that exist. You should also -check that your problem is not described already in @xref{Frequently -Asked Questions}. - -If you can identify a minimal test case that reproduces the problem, -include that with your bug report. This will make it much easier for -the development team to analyze and correct the problem. - -Before reporting the bug, you should set the verbosity level to 6 -(@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file and -repeat the bug. Then, include the contents of the @file{*tramp/foo*} -and @file{*debug tramp/foo*} buffers in your bug report. A verbosity -level greater than 6 will produce a very huge debug buffer, which is -mostly not necessary for the analysis. - -Please be aware that, with a verbosity level of 6 or greater, the -contents of files and directories will be included in the debug -buffer. Passwords you've typed will never be included there. - - -@node Frequently Asked Questions -@chapter Frequently Asked Questions -@cindex frequently asked questions -@cindex FAQ - -@itemize @bullet -@item -Where can I get the latest @value{tramp}? - -@value{tramp} is available under the URL below. - -@noindent -@uref{ftp://ftp.gnu.org/gnu/tramp/} - -@noindent -There is also a Savannah project page. - -@noindent -@uref{http://savannah.gnu.org/projects/tramp/} - - -@item -Which systems does it work on? - -The package has been used successfully on GNU Emacs 21, GNU Emacs 22 -and XEmacs 21 (starting with 21.4). Gateway methods are supported for -GNU Emacs 22 only. - -The package was intended to work on Unix, and it really expects a -Unix-like system on the remote end (except the @option{smb} method), -but some people seemed to have some success getting it to work on MS -Windows NT/2000/XP @value{emacsname}. - -There is some informations on @value{tramp} on NT at the following URL; -many thanks to Joe Stoy for providing the information: -@uref{ftp://ftp.comlab.ox.ac.uk/tmp/Joe.Stoy/} - -@c The link is broken. I've contacted Tom for clarification. Michael. -@ignore -The above mostly contains patches to old ssh versions; Tom Roche has a -Web page with instructions: -@uref{http://www4.ncsu.edu/~tlroche/plinkTramp.html} -@end ignore - -@item -How could I speed up @value{tramp}? - -In the backstage, @value{tramp} needs a lot of operations on the -remote host. The time for transferring data from and to the remote -host as well as the time needed to perform the operations there count. -In order to speed up @value{tramp}, one could either try to avoid some -of the operations, or one could try to improve their performance. - -Use an external method, like @option{scpc}. - -Use caching. This is already enabled by default. Information about -the remote host as well as the remote files are cached for reuse. The -information about remote hosts is kept in the file specified in -@code{tramp-persistency-file-name}. Keep this file. - -Disable version control. If you access remote files which are not -under version control, a lot of check operations can be avoided by -disabling VC. This can be achieved by - -@lisp -(setq vc-handled-backends nil) -@end lisp - -Disable excessive traces. The default trace level of @value{tramp}, -defined in the variable @code{tramp-verbose}, is 3. You should -increase this level only temporarily, hunting bugs. - - -@item -@value{tramp} does not connect to the remote host - -When @value{tramp} does not connect to the remote host, there are two -reasons heading the bug mailing list: - -@itemize @minus - -@item -Unknown characters in the prompt - -@value{tramp} needs to recognize the prompt on the remote machine -after execution any command. This is not possible, when the prompt -contains unknown characters like escape sequences for coloring. This -should be avoided on the remote side. @xref{Remote shell setup}. for -setting the regular expression detecting the prompt. - -You can check your settings after an unsuccessful connection by -switching to the @value{tramp} connection buffer @file{*tramp/foo*}, -setting the cursor at the top of the buffer, and applying the expression - -@example -@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} -@end example - -If it fails, or the cursor is not moved at the end of the buffer, your -prompt is not recognized correctly. - -A special problem is the zsh, which uses left-hand side and right-hand -side prompts in parallel. Therefore, it is necessary to disable the -zsh line editor on the remote host. You shall add to @file{~/.zshrc} -the following command: - -@example -[ $TERM = "dumb" ] && unsetopt zle && PS1='$ ' -@end example - - -@item -@value{tramp} doesn't transfer strings with more than 500 characters -correctly - -On some few systems, the implementation of @code{process-send-string} -seems to be broken for longer strings. It is reported for HP-UX, -FreeBSD and Tru64 Unix, for example. This case, you should customize -the variable @code{tramp-chunksize} to 500. For a description how to -determine whether this is necessary see the documentation of -@code{tramp-chunksize}. - -Additionally, it will be useful to set @code{file-precious-flag} to -@code{t} for @value{tramp} files. Then the file contents will be -written into a temporary file first, which is checked for correct -checksum. -@ifinfo -@pxref{Saving Buffers, , , elisp} -@end ifinfo - -@lisp -(add-hook - 'find-file-hooks - '(lambda () - (when (file-remote-p default-directory) - (set (make-local-variable 'file-precious-flag) t)))) -@end lisp - -@end itemize - - -@item -File name completion does not work with @value{tramp} - -When you log in to the remote machine, do you see the output of -@command{ls} in color? If so, this may be the cause of your problems. - -@command{ls} outputs @acronym{ANSI} escape sequences that your terminal -emulator interprets to set the colors. These escape sequences will -confuse @value{tramp} however. - -In your @file{.bashrc}, @file{.profile} or equivalent on the remote -machine you probably have an alias configured that adds the option -@option{--color=yes} or @option{--color=auto}. - -You should remove that alias and ensure that a new login @emph{does not} -display the output of @command{ls} in color. If you still cannot use -filename completion, report a bug to the @value{tramp} developers. - - -@item -File name completion does not work in large directories - -@value{tramp} uses globbing for some operations. (Globbing means to use the -shell to expand wildcards such as `*.c'.) This might create long -command lines, especially in directories with many files. Some shells -choke on long command lines, or don't cope well with the globbing -itself. - -If you have a large directory on the remote end, you may wish to execute -a command like @samp{ls -d * ..?* > /dev/null} and see if it hangs. -Note that you must first start the right shell, which might be -@command{/bin/sh}, @command{ksh} or @command{bash}, depending on which -of those supports tilde expansion. - - -@item -How can I get notified when @value{tramp} file transfers are complete? - -The following snippet can be put in your @file{~/.emacs} file. It -makes @value{emacsname} beep after reading from or writing to the -remote host. - -@lisp -(defadvice tramp-handle-write-region - (after tramp-write-beep-advice activate) - "Make tramp beep after writing a file." - (interactive) - (beep)) - -(defadvice tramp-handle-do-copy-or-rename-file - (after tramp-copy-beep-advice activate) - "Make tramp beep after copying a file." - (interactive) - (beep)) - -(defadvice tramp-handle-insert-file-contents - (after tramp-insert-beep-advice activate) - "Make tramp beep after inserting a file." - (interactive) - (beep)) -@end lisp - - -@ifset emacs -@item -I'ld like to get a Visual Warning when working in a sudo:ed context - -When you are working with @samp{root} privileges, it might be useful -to get an indication in the buffer's modeline. The following code, -tested with @value{emacsname} 22.1, does the job. You should put it -into your @file{~/.emacs}: - -@lisp -(defun my-mode-line-function () - (when (string-match "^/su\\(do\\)?:" default-directory) - (setq mode-line-format - (format-mode-line mode-line-format 'font-lock-warning-face)))) - -(add-hook 'find-file-hooks 'my-mode-line-function) -(add-hook 'dired-mode-hook 'my-mode-line-function) -@end lisp -@end ifset - - -@ifset emacs -@item -I'ld like to see a host indication in the mode line when I'm remote - -The following code has been tested with @value{emacsname} 22.1. You -should put it into your @file{~/.emacs}: - -@lisp -(defconst my-mode-line-buffer-identification - (list - '(:eval - (let ((host-name - (if (file-remote-p default-directory) - (tramp-file-name-host - (tramp-dissect-file-name default-directory)) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) - ": %12b")) - -(setq-default - mode-line-buffer-identification - my-mode-line-buffer-identification) - -(add-hook - 'dired-mode-hook - '(lambda () - (setq - mode-line-buffer-identification - my-mode-line-buffer-identification))) -@end lisp - -Since @value{emacsname} 23.1, the mode line contains an indication if -@code{default-directory} for the current buffer is on a remote host. -The corresponding tooltip includes the name of that host. If you -still want the host name as part of the mode line, you can use the -example above, but the @code{:eval} clause can be simplified: - -@lisp - '(:eval - (let ((host-name - (or (file-remote-p default-directory 'host) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) -@end lisp -@end ifset - - -@ifset emacs -@item -My remote host does not understand default directory listing options - -@value{emacsname} computes the @command{dired} options depending on -the local host you are working. If your @command{ls} command on the -remote host does not understand those options, you can change them -like this: - -@lisp -(add-hook - 'dired-before-readin-hook - '(lambda () - (when (file-remote-p default-directory) - (setq dired-actual-switches "-al")))) -@end lisp -@end ifset - - -@item -There's this @file{~/.sh_history} file on the remote host which keeps -growing and growing. What's that? - -Sometimes, @value{tramp} starts @command{ksh} on the remote host for -tilde expansion. Maybe @command{ksh} saves the history by default. -@value{tramp} tries to turn off saving the history, but maybe you have -to help. For example, you could put this in your @file{.kshrc}: - -@example -if [ -f $HOME/.sh_history ] ; then - /bin/rm $HOME/.sh_history -fi -if [ "$@{HISTFILE-unset@}" != "unset" ] ; then - unset HISTFILE -fi -if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then - unset HISTSIZE -fi -@end example - - -@item There are longish file names to type. How to shorten this? - -Let's say you need regularly access to @file{@trampfn{ssh, news, -news.my.domain, /opt/news/etc}}, which is boring to type again and -again. The following approaches can be mixed: - -@enumerate - -@item Use default values for method and user name: - -You can define default methods and user names for hosts, -(@pxref{Default Method}, @pxref{Default User}): - -@lisp -(setq tramp-default-method "ssh" - tramp-default-user "news") -@end lisp - -The file name left to type would be -@kbd{C-x C-f @trampfn{, , news.my.domain, /opt/news/etc}}. - -Note, that there are some useful settings already. Accessing your -local host as @samp{root} user, is possible just by @kbd{C-x C-f -@trampfn{su, , ,}}. - -@item Use configuration possibilities of your method: - -Several connection methods (i.e. the programs used) offer powerful -configuration possibilities (@pxref{Customizing Completion}). In the -given case, this could be @file{~/.ssh/config}: - -@example -Host xy - HostName news.my.domain - User news -@end example - -The file name left to type would be @kbd{C-x C-f @trampfn{ssh, , xy, -/opt/news/etc}}. Depending on files in your directories, it is even -possible to complete the host name with @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop}x @key{TAB}}. - -@item Use environment variables: - -File names typed in the minibuffer can be expanded by environment -variables. You can set them outside @value{emacsname}, or even with -Lisp: - -@lisp -(setenv "xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}") -@end lisp - -Then you need simply to type @kbd{C-x C-f $xy @key{RET}}, and here you -are. The disadvantage is, that you cannot edit the file name, because -environment variables are not expanded during editing in the -minibuffer. - -@item Define own keys: - -You can define your own key sequences in @value{emacsname}, which can -be used instead of @kbd{C-x C-f}: - -@lisp -(global-set-key - [(control x) (control y)] - (lambda () - (interactive) - (find-file - (read-file-name - "Find Tramp file: " - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")))) -@end lisp - -Simply typing @kbd{C-x C-y} would initialize the minibuffer for -editing with your beloved file name. - -See also @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the -Emacs Wiki} for a more comprehensive example. - -@item Define own abbreviation (1): - -It is possible to define an own abbreviation list for expanding file -names: - -@lisp -(add-to-list - 'directory-abbrev-alist - '("^/xy" . "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -This shortens the file openening command to @kbd{C-x C-f /xy -@key{RET}}. The disadvantage is, again, that you cannot edit the file -name, because the expansion happens after entering the file name only. - -@item Define own abbreviation (2): - -The @code{abbrev-mode} gives more flexibility for editing the -minibuffer: - -@lisp -(define-abbrev-table 'my-tramp-abbrev-table - '(("xy" "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}"))) - -(add-hook - 'minibuffer-setup-hook - '(lambda () - (abbrev-mode 1) - (setq local-abbrev-table my-tramp-abbrev-table))) - -(defadvice minibuffer-complete - (before my-minibuffer-complete activate) - (expand-abbrev)) - -;; If you use partial-completion-mode -(defadvice PC-do-completion - (before my-PC-do-completion activate) - (expand-abbrev)) -@end lisp - -After entering @kbd{C-x C-f xy @key{TAB}}, the minibuffer is -expanded, and you can continue editing. - -@item Use bookmarks: - -Bookmarks can be used to visit Tramp files or directories. -@ifinfo -@pxref{Bookmarks, , , @value{emacsdir}} -@end ifinfo - -When you have opened @file{@trampfn{ssh, news, news.my.domain, -/opt/news/etc/}}, you should save the bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}. -@end ifset - -Later on, you can always navigate to that bookmark via -@ifset emacs -@kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}. -@end ifset - -@item Use recent files: - -@ifset emacs -@file{recentf} -@end ifset -@ifset xemacs -@file{recent-files} -@end ifset -remembers visited places. -@ifinfo -@ifset emacs -@pxref{File Conveniences, , , @value{emacsdir}} -@end ifset -@ifset xemacs -@pxref{recent-files, , , edit-utils} -@end ifset -@end ifinfo - -You could keep remote file names in the recent list without checking -their readability through a remote access: - -@lisp -@ifset emacs -(recentf-mode 1) -@end ifset -@ifset xemacs -(recent-files-initialize) -(add-hook - 'find-file-hooks - (lambda () - (when (file-remote-p (buffer-file-name)) - (recent-files-make-permanent))) - 'append) -@end ifset -@end lisp - -The list of files opened recently is reachable via -@ifset emacs -@kbd{@key{menu-bar} @key{file} @key{Open Recent}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{Recent Files}}. -@end ifset - -@ifset emacs -@item Use filecache: - -@file{filecache} remembers visited places. Add the directory into -the cache: - -@lisp -(eval-after-load "filecache" - '(file-cache-add-directory - "@trampfn{ssh, news, news.my.domain, /opt/news/etc/}")) -@end lisp - -Whenever you want to load a file, you can enter @kbd{C-x C-f -C-@key{TAB}} in the minibuffer. The completion is done for the given -directory. -@end ifset - -@ifset emacs -@item Use bbdb: - -@file{bbdb} has a built-in feature for @value{ftppackagename} files, -which works also for @value{tramp}. -@ifinfo -@pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb} -@end ifinfo - -You need to load @file{bbdb}: - -@lisp -(require 'bbdb) -(bbdb-initialize) -@end lisp - -Then you can create a BBDB entry via @kbd{M-x bbdb-create-ftp-site}. -Because BBDB is not prepared for @value{tramp} syntax, you must -specify a method together with the user name, when needed. Example: - -@example -@kbd{M-x bbdb-create-ftp-site @key{RET}} -@b{Ftp Site:} news.my.domain @key{RET} -@b{Ftp Directory:} /opt/news/etc/ @key{RET} -@b{Ftp Username:} ssh@value{postfixhop}news @key{RET} -@b{Company:} @key{RET} -@b{Additional Comments:} @key{RET} -@end example - -When you have opened your BBDB buffer, you can access such an entry by -pressing the key @key{F}. -@end ifset - -@end enumerate - -I would like to thank all @value{tramp} users, who have contributed to -the different recipes! - - -@item -How can I disable @value{tramp}? - -Shame on you, why did you read until now? - -@itemize @minus - -@item -@ifset emacs -If you just want to have @value{ftppackagename} as default remote -files access package, you should apply the following code: - -@lisp -(setq tramp-default-method "ftp") -@end lisp -@end ifset - -@item -In order to disable -@ifset emacs -@value{tramp} (and @value{ftppackagename}), -@end ifset -@ifset xemacs -@value{tramp}, -@end ifset -you must set @code{tramp-mode} to @code{nil}: - -@lisp -(setq tramp-mode nil) -@end lisp - -@item -Unloading @value{tramp} can be achieved by applying @kbd{M-x -tramp-unload-tramp}. -@ifset emacs -This resets also the @value{ftppackagename} plugins. -@end ifset -@end itemize -@end itemize - - -@c For the developer -@node Version Control -@chapter The inner workings of remote version control -@cindex Version Control - -Unlike @value{ftppackagename}, @value{tramp} has full shell access to the -remote machine. This makes it possible to provide version control for -files accessed under @value{tramp}. - -The actual version control binaries must be installed on the remote -machine, accessible in the directories specified in -@code{tramp-remote-path}. - -This transparent integration with the version control systems is one of -the most valuable features provided by @value{tramp}, but it is far from perfect. -Work is ongoing to improve the transparency of the system. - -@menu -* Version Controlled Files:: Determining if a file is under version control. -* Remote Commands:: Executing the version control commands on the remote machine. -* Changed workfiles:: Detecting if the working file has changed. -* Checking out files:: Bringing the workfile out of the repository. -* Miscellaneous Version Control:: Things related to Version Control that don't fit elsewhere. -@end menu - - -@node Version Controlled Files -@section Determining if a file is under version control - -The VC package uses the existence of on-disk revision control master -files to determine if a given file is under revision control. These file -tests happen on the remote machine through the standard @value{tramp} mechanisms. - - -@node Remote Commands -@section Executing the version control commands on the remote machine - -There are no hooks provided by VC to allow intercepting of the version -control command execution. The calls occur through the -@code{call-process} mechanism, a function that is somewhat more -efficient than the @code{shell-command} function but that does not -provide hooks for remote execution of commands. - -To work around this, the functions @code{vc-do-command} and -@code{vc-simple-command} have been advised to intercept requests for -operations on files accessed via @value{tramp}. - -In the case of a remote file, the @code{shell-command} interface is -used, with some wrapper code, to provide the same functionality on the -remote machine as would be seen on the local machine. - - -@node Changed workfiles -@section Detecting if the working file has changed - -As there is currently no way to get access to the mtime of a file on a -remote machine in a portable way, the @code{vc-workfile-unchanged-p} -function is advised to call an @value{tramp} specific function for remote files. - -The @code{tramp-vc-workfile-unchanged-p} function uses the functioning VC -diff functionality to determine if any changes have occurred between the -workfile and the version control master. - -This requires that a shell command be executed remotely, a process that -is notably heavier-weight than the mtime comparison used for local -files. Unfortunately, unless a portable solution to the issue is found, -this will remain the cost of remote version control. - - -@node Checking out files -@section Bringing the workfile out of the repository - -VC will, by default, check for remote files and refuse to act on them -when checking out files from the repository. To work around this -problem, the function @code{vc-checkout} knows about @value{tramp} files and -allows version control to occur. - - -@node Miscellaneous Version Control -@section Things related to Version Control that don't fit elsewhere - -Minor implementation details, &c. - -@menu -* Remote File Ownership:: How VC determines who owns a workfile. -* Back-end Versions:: How VC determines what release your RCS is. -@end menu - - -@node Remote File Ownership -@subsection How VC determines who owns a workfile - -@value{emacsname} provides the @code{user-login-name} function to -return the login name of the current user as well as mapping from -arbitrary user id values back to login names. The VC code uses this -functionality to map from the uid of the owner of a workfile to the -login name in some circumstances. - -This will not, for obvious reasons, work if the remote system has a -different set of logins. As such, it is necessary to delegate to the -remote machine the job of determining the login name associated with a -uid. - -Unfortunately, with the profusion of distributed management systems such -as @code{NIS}, @code{NIS+} and @code{NetInfo}, there is no simple, -reliable and portable method for performing this mapping. - -Thankfully, the only place in the VC code that depends on the mapping of -a uid to a login name is the @code{vc-file-owner} function. This returns -the login of the owner of the file as a string. - -This function has been advised to use the output of @command{ls} on the -remote machine to determine the login name, delegating the problem of -mapping the uid to the login to the remote system which should know more -about it than I do. - - -@node Back-end Versions -@subsection How VC determines what release your RCS is - -VC needs to know what release your revision control binaries you are -running as not all features VC supports are available with older -versions of @command{rcs(1)}, @command{cvs(1)} or @command{sccs(1)}. - -The default implementation of VC determines this value the first time it -is needed and then stores the value globally to avoid the overhead of -executing a process and parsing its output each time the information is -needed. - -Unfortunately, life is not quite so easy when remote version control -comes into the picture. Each remote machine may have a different version -of the version control tools and, while this is painful, we need to -ensure that unavailable features are not used remotely. - -To resolve this issue, @value{tramp} currently takes the sledgehammer -approach of making the release values of the revision control tools -local to each @value{tramp} buffer, forcing VC to determine these values -again each time a new file is visited. - -This has, quite obviously, some performance implications. Thankfully, -most of the common operations performed by VC do not actually require -that the remote version be known. This makes the problem far less -apparent. - -Eventually these values will be captured by @value{tramp} on a system by -system basis and the results cached to improve performance. - - -@node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. - -@menu -* Localname deconstruction:: Breaking a localname into its components. -@ifset emacs -* External packages:: Integration with external Lisp packages. -@end ifset -@end menu - - -@node Localname deconstruction -@section Breaking a localname into its components. - -@value{tramp} file names are somewhat different, obviously, to ordinary file -names. As such, the lisp functions @code{file-name-directory} and -@code{file-name-nondirectory} are overridden within the @value{tramp} -package. - -Their replacements are reasonably simplistic in their approach. They -dissect the filename, call the original handler on the localname and -then rebuild the @value{tramp} file name with the result. - -This allows the platform specific hacks in the original handlers to take -effect while preserving the @value{tramp} file name information. - - -@ifset emacs -@node External packages -@section Integration with external Lisp packages. - -While reading filenames in the minibuffer, @value{tramp} must decide -whether it completes possible incomplete filenames, or not. Imagine -there is the following situation: You have typed @kbd{C-x C-f -@value{prefix}ssh@value{postfixhop} @key{TAB}}. @value{tramp} cannot -know, whether @option{ssh} is a method or a host name. It checks -therefore the last input character you have typed. If this is -@key{TAB}, @key{SPACE} or @kbd{?}, @value{tramp} assumes that you are -still in filename completion, and it does not connect to the possible -remote host @option{ssh}. - -@vindex tramp-completion-mode -External packages, which use other characters for completing filenames -in the minibuffer, must signal this to @value{tramp}. For this case, -the variable @code{tramp-completion-mode} can be bound temporarily to -a non-nil value. - -@lisp -(let ((tramp-completion-mode t)) - ...) -@end lisp -@end ifset - - -@node Traces and Profiles -@chapter How to Customize Traces - -All @value{tramp} messages are raised with a verbosity level. The -verbosity level can be any number between 0 and 10. Only messages with -a verbosity level less than or equal to @code{tramp-verbose} are -displayed. - -The verbosity levels are - - @w{ 0} silent (no @value{tramp} messages at all) -@*@indent @w{ 1} errors -@*@indent @w{ 2} warnings -@*@indent @w{ 3} connection to remote hosts (default verbosity) -@*@indent @w{ 4} activities -@*@indent @w{ 5} internal -@*@indent @w{ 6} sent and received strings -@*@indent @w{ 7} file caching -@*@indent @w{ 8} connection properties -@*@indent @w{10} traces (huge) - -When @code{tramp-verbose} is greater than or equal to 4, the messages -are also written into a @value{tramp} debug buffer. This debug buffer -is useful for analysing problems; sending a @value{tramp} bug report -should be done with @code{tramp-verbose} set to a verbosity level of at -least 6 (@pxref{Bug Reports}). - -The debug buffer is in -@ifinfo -@ref{Outline Mode, , , @value{emacsdir}}. -@end ifinfo -@ifnotinfo -Outline Mode. -@end ifnotinfo -That means, you can change the level of messages to be viewed. If you -want, for example, see only messages up to verbosity level 5, you must -enter @kbd{C-u 6 C-c C-q}. -@ifinfo -Other keys for navigating are described in -@ref{Outline Visibility, , , @value{emacsdir}}. -@end ifinfo - -@value{tramp} errors are handled internally in order to raise the -verbosity level 1 messages. When you want to get a Lisp backtrace in -case of an error, you need to set both - -@lisp -(setq debug-on-error t - debug-on-signal t) -@end lisp - -Sometimes, it might be even necessary to step through @value{tramp} -function call traces. Such traces are enabled by the following code: - -@lisp -(require 'tramp) -(require 'trace) -(dolist (elt (all-completions "tramp-" obarray 'functionp)) - (trace-function-background (intern elt))) -(untrace-function 'tramp-read-passwd) -(untrace-function 'tramp-gw-basic-authentication) -@end lisp - -The function call traces are inserted in the buffer -@file{*trace-output*}. @code{tramp-read-passwd} and -@code{tramp-gw-basic-authentication} shall be disabled when the -function call traces are added to @value{tramp}, because both -functions return password strings, which should not be distributed. - - -@node Issues -@chapter Debatable Issues and What Was Decided - -@itemize @bullet -@item The uuencode method does not always work. - -Due to the design of @value{tramp}, the encoding and decoding programs -need to read from stdin and write to stdout. On some systems, -@command{uudecode -o -} will read stdin and write the decoded file to -stdout, on other systems @command{uudecode -p} does the same thing. -But some systems have uudecode implementations which cannot do this at -all---it is not possible to call these uudecode implementations with -suitable parameters so that they write to stdout. - -Of course, this could be circumvented: the @code{begin foo 644} line -could be rewritten to put in some temporary file name, then -@command{uudecode} could be called, then the temp file could be -printed and deleted. - -But I have decided that this is too fragile to reliably work, so on some -systems you'll have to do without the uuencode methods. - -@item The @value{tramp} filename syntax differs between GNU Emacs and XEmacs. - -The GNU Emacs maintainers wish to use a unified filename syntax for -Ange-FTP and @value{tramp} so that users don't have to learn a new -syntax. It is sufficient to learn some extensions to the old syntax. - -For the XEmacs maintainers, the problems caused from using a unified -filename syntax are greater than the gains. The XEmacs package system -uses EFS for downloading new packages. So, obviously, EFS has to be -installed from the start. If the filenames were unified, @value{tramp} -would have to be installed from the start, too. - -@ifset xemacs -@strong{Note:} If you'd like to use a similar syntax like -@value{ftppackagename}, you need the following settings in your init -file: - -@lisp -(setq tramp-unified-filenames t) -(require 'tramp) -@end lisp - -The autoload of the @value{emacsname} @value{tramp} package must be -disabled. This can be achieved by setting file permissions @code{000} -to the files @file{.../xemacs-packages/lisp/tramp/auto-autoloads.el*}. - -In case of unified filenames, all @value{emacsname} download sites are -added to @code{tramp-default-method-alist} with default method -@option{ftp} @xref{Default Method}. These settings shouldn't be -touched for proper working of the @value{emacsname} package system. - -The syntax for unified filenames is described in the @value{tramp} manual -for @value{emacsothername}. -@end ifset -@end itemize - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye - -@c TODO -@c -@c * Say something about the .login and .profile files of the remote -@c shells. -@c * Explain how tramp.el works in principle: open a shell on a remote -@c host and then send commands to it. -@c * Use `filename' resp. `file name' consistently. -@c * Use `host' resp. `machine' consistently. -@c * Consistent small or capitalized words especially in menues. - -@ignore - arch-tag: f96dd66e-6dd3-4c92-8d77-9c56205ba808 -@end ignore diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi deleted file mode 100644 index 7644a4aa264..00000000000 --- a/doc/misc/trampver.texi +++ /dev/null @@ -1,71 +0,0 @@ -@c -*-texinfo-*- -@c texi/trampver.texi. Generated from trampver.texi.in by configure. - -@c This is part of the Emacs manual. -@c Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -@c Free Software Foundation, Inc. -@c See file doclicense.texi for copying conditions. - -@c In the Tramp CVS, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.1.15 - -@c Other flags from configuration -@set instprefix /usr/local -@set lispdir /usr/local/share/emacs/site-lisp -@set infodir /usr/local/share/info - -@c Formatting of the tramp program name consistent. -@set tramp @sc{tramp} - -@c Whether or not describe gateway methods. -@ifclear noemacsgw -@set emacsgw -@end ifclear - -@c Some flags which make the text independent on the (X)Emacs flavor. -@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs". -@ifclear emacs -@ifclear xemacs -@set emacs -@end ifclear -@end ifclear - -@c Emacs values. -@ifset emacs -@set emacsname GNU Emacs -@set emacsdir emacs -@set ftppackagename Ange-FTP -@set prefix / -@set prefixhop -@set postfix : -@set postfixhop : -@set ipv6prefix [ -@set ipv6postfix ] -@set emacsothername XEmacs -@set emacsotherdir xemacs -@set emacsotherfilename tramp-xemacs.html -@set japanesemanual tramp_ja-emacs.html -@end ifset - -@c XEmacs counterparts. -@ifset xemacs -@set emacsname XEmacs -@set emacsdir xemacs -@set ftppackagename EFS -@set prefix /[ -@set prefixhop [ -@set postfix ] -@set postfixhop / -@set ipv6prefix -@set ipv6postfix -@set emacsothername GNU Emacs -@set emacsotherdir emacs -@set emacsotherfilename tramp-emacs.html -@set japanesemanual tramp_ja-xemacs.html -@end ifset - -@ignore - arch-tag: e0fe322c-e06b-46eb-bb5b-d091b521f41c -@end ignore diff --git a/doc/misc/url.texi b/doc/misc/url.texi deleted file mode 100644 index f60952a10f7..00000000000 --- a/doc/misc/url.texi +++ /dev/null @@ -1,1192 +0,0 @@ -\input texinfo -@setfilename ../../info/url -@settitle URL Programmer's Manual - -@iftex -@c @finalout -@end iftex -@c @setchapternewpage odd -@c @smallbook - -@tex -\overfullrule=0pt -%\global\baselineskip 30pt % for printing in double space -@end tex -@dircategory World Wide Web -@dircategory Emacs -@direntry -* URL: (url). URL loading package. -@end direntry - -@copying -This file documents the Emacs Lisp URL loading package. - -Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002, -2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@c -@titlepage -@title URL Programmer's Manual -@subtitle First Edition, URL Version 2.0 -@author William M. Perry @email{wmperry@@gnu.org} -@author David Love @email{fx@@gnu.org} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@node Top -@top URL - -@ifnottex -@insertcopying -@end ifnottex - -@menu -* Getting Started:: Preparing your program to use URLs. -* Retrieving URLs:: How to use this package to retrieve a URL. -* Supported URL Types:: Descriptions of URL types currently supported. -* Defining New URLs:: How to define a URL loader for a new protocol. -* General Facilities:: URLs can be cached, accessed via a gateway - and tracked in a history list. -* Customization:: Variables you can alter. -* GNU Free Documentation License:: The license for this documentation. -* Function Index:: -* Variable Index:: -* Concept Index:: -@end menu - -@node Getting Started -@chapter Getting Started -@cindex URLs, definition -@cindex URIs - -@dfn{Uniform Resource Locators} (URLs) are a specific form of -@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which -updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource -agents. - -URIs have the form @var{scheme}:@var{scheme-specific-part}, where the -@var{scheme}s supported by this library are described below. -@xref{Supported URL Types}. - -FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270, -IRC and gopher URLs all have the form - -@example -@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]} -@end example -@noindent -where @samp{@r{[}} and @samp{@r{]}} delimit optional parts. -@var{userinfo} sometimes takes the form @var{username}:@var{password} -but you should beware of the security risks of sending cleartext -passwords. @var{hostname} may be a domain name or a dotted decimal -address. If the @samp{:@var{port}} is omitted then the library will -use the `well known' port for that service when accessing URLs. With -the possible exception of @code{telnet}, it is rare for ports to be -specified, and it is possible using a non-standard port may have -undesired consequences if a different service is listening on that -port (e.g., an HTTP URL specifying the SMTP port can cause mail to be -sent). @c , but @xref{Other Variables, url-bad-port-list}. -The meaning of the @var{path} component depends on the service. - -@menu -* Configuration:: -* Parsed URLs:: URLs are parsed into vector structures. -@end menu - -@node Configuration -@section Configuration - -@defvar url-configuration-directory -@cindex @file{~/.url} -@cindex configuration files -The directory in which URL configuration files, the cache etc., -reside. Default @file{~/.url}. -@end defvar - -@node Parsed URLs -@section Parsed URLs -@cindex parsed URLs -The library functions typically operate on @dfn{parsed} versions of -URLs. These are actually vectors of the form: - -@example -[@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}] -@end example - -@noindent where -@table @var -@item type -is the type of the URL scheme, e.g., @code{http} -@item user -is the username associated with it, or @code{nil}; -@item password -is the user password associated with it, or @code{nil}; -@item host -is the host name associated with it, or @code{nil}; -@item port -is the port number associated with it, or @code{nil}; -@item file -is the `file' part of it, or @code{nil}. This doesn't necessarily -actually refer to a file; -@item target -is the target part, or @code{nil}; -@item attributes -is the attributes associated with it, or @code{nil}; -@item full -is @code{t} for a fully-specified URL, with a host part indicated by -@samp{//} after the scheme part. -@end table - -@findex url-type -@findex url-user -@findex url-password -@findex url-host -@findex url-port -@findex url-file -@findex url-target -@findex url-attributes -@findex url-full -@findex url-set-type -@findex url-set-user -@findex url-set-password -@findex url-set-host -@findex url-set-port -@findex url-set-file -@findex url-set-target -@findex url-set-attributes -@findex url-set-full -These attributes have accessors named @code{url-@var{part}}, where -@var{part} is the name of one of the elements above, e.g., -@code{url-host}. Similarly, there are setters of the form -@code{url-set-@var{part}}. - -There are functions for parsing and unparsing between the string and -vector forms. - -@defun url-generic-parse-url url -Return a parsed version of the string @var{url}. -@end defun - -@defun url-recreate-url url -@cindex unparsing URLs -Recreates a URL string from the parsed @var{url}. -@end defun - -@node Retrieving URLs -@chapter Retrieving URLs - -@defun url-retrieve-synchronously url -Retrieve @var{url} synchronously and return a buffer containing the -data. @var{url} is either a string or a parsed URL structure. Return -@code{nil} if there are no data associated with it (the case for dired, -info, or mailto URLs that need no further processing). -@end defun - -@defun url-retrieve url callback &optional cbargs -Retrieve @var{url} asynchronously and call @var{callback} with args -@var{cbargs} when finished. The callback is called when the object -has been completely retrieved, with the current buffer containing the -object and any MIME headers associated with it. @var{url} is either a -string or a parsed URL structure. Returns the buffer @var{url} will -load into, or @code{nil} if the process has already completed. -@end defun - -@node Supported URL Types -@chapter Supported URL Types - -@menu -* http/https:: Hypertext Transfer Protocol. -* file/ftp:: Local files and FTP archives. -* info:: Emacs `Info' pages. -* mailto:: Sending email. -* news/nntp/snews:: Usenet news. -* rlogin/telnet/tn3270:: Remote host connectivity. -* irc:: Internet Relay Chat. -* data:: Embedded data URLs. -* nfs:: Networked File System -@c * finger:: -@c * gopher:: -@c * netrek:: -@c * prospero:: -* cid:: Content-ID. -* about:: -* ldap:: Lightweight Directory Access Protocol -* imap:: IMAP mailboxes. -* man:: Unix man pages. -@end menu - -@node http/https -@section @code{http} and @code{https} - -The scheme @code{http} is Hypertext Transfer Protocol. The library -supports version 1.1, specified in RFC 2616. (This supersedes 1.0, -defined in RFC 1945) HTTP URLs have the following form, where most of -the parts are optional: -@example -http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment} -@end example -@c The @code{:@var{port}} part is optional, and @var{port} defaults to -@c 80. The @code{/@var{path}} part, if present, is a slash-separated -@c series elements. The @code{?@var{searchpart}}, if present, is the -@c query for a search or the content of a form submission. The -@c @code{#fragment} part, if present, is a location in the document. - -The scheme @code{https} is a secure version of @code{http}, with -transmission via SSL. It is defined in RFC 2069. Its default port is -443. This scheme depends on SSL support in Emacs via the -@file{ssl.el} library and is actually implemented by forcing the -@code{ssl} gateway method to be used. @xref{Gateways in general}. - -@defopt url-honor-refresh-requests -This controls honoring of HTTP @samp{Refresh} headers by which -servers can direct clients to reload documents from the same URL or a -or different one. @code{nil} means they will not be honored, -@code{t} (the default) means they will always be honored, and -otherwise the user will be asked on each request. -@end defopt - - -@menu -* Cookies:: -* HTTP language/coding:: -* HTTP URL Options:: -* Dealing with HTTP documents:: -@end menu - -@node Cookies -@subsection Cookies - -@defopt url-cookie-file -The file in which cookies are stored, defaulting to @file{cookies} in -the directory specified by @code{url-configuration-directory}. -@end defopt - -@defopt url-cookie-confirmation -Specifies whether confirmation is require to accept cookies. -@end defopt - -@defopt url-cookie-multiple-line -Specifies whether to put all cookies for the server on one line in the -HTTP request to satisfy broken servers like -@url{http://www.hotmail.com}. -@end defopt - -@defopt url-cookie-trusted-urls -A list of regular expressions matching URLs from which to accept -cookies always. -@end defopt - -@defopt url-cookie-untrusted-urls -A list of regular expressions matching URLs from which to reject -cookies always. -@end defopt - -@defopt url-cookie-save-interval -The number of seconds between automatic saves of cookies to disk. -Default is one hour. -@end defopt - - -@node HTTP language/coding -@subsection Language and Encoding Preferences - -HTTP allows clients to express preferences for the language and -encoding of documents which servers may honor. For each of these -variables, the value is a string; it can specify a single choice, or -it can be a comma-separated list. - -Normally this list ordered by descending preference. However, each -element can be followed by @samp{;q=@var{priority}} to specify its -preference level, a decimal number from 0 to 1; e.g., for -@code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8, -en;q=0.7"}}. An element that has no @samp{;q} specification has -preference level 1. - -@defopt url-mime-charset-string -@cindex character sets -@cindex coding systems -This variable specifies a preference for character sets when documents -can be served in more than one encoding. - -HTTP allows specifying a series of MIME charsets which indicate your -preferred character set encodings, e.g., Latin-9 or Big5, and these -can be weighted. The default series is generated automatically from -the associated MIME types of all defined coding systems, sorted by the -coding system priority specified in Emacs. @xref{Recognize Coding, , -Recognizing Coding Systems, emacs, The GNU Emacs Manual}. -@end defopt - -@defopt url-mime-language-string -@cindex language preferences -A string specifying the preferred language when servers can serve -files in several languages. Use RFC 1766 abbreviations, e.g., -@samp{en} for English, @samp{de} for German. - -The string can be @code{"*"} to get the first available language (as -opposed to the default). -@end defopt - -@node HTTP URL Options -@subsection HTTP URL Options - -HTTP supports an @samp{OPTIONS} method describing things supported by -the URL@. - -@defun url-http-options url -Returns a property list describing options available for URL. The -property list members are: - -@table @code -@item methods -A list of symbols specifying what HTTP methods the resource -supports. - -@item dav -@cindex DAV -A list of numbers specifying what DAV protocol/schema versions are -supported. - -@item dasl -@cindex DASL -A list of supported DASL search types supported (string form). - -@item ranges -A list of the units available for use in partial document fetches. - -@item p3p -@cindex P3P -The @dfn{Platform For Privacy Protection} description for the resource. -Currently this is just the raw header contents. -@end table - -@end defun - -@node Dealing with HTTP documents -@subsection Dealing with HTTP documents - -HTTP URLs are retrieved into a buffer containing the HTTP headers -followed by the body. Since the headers are quasi-MIME, they may be -processed using the MIME library. @xref{Top,, Emacs MIME, -emacs-mime, The Emacs MIME Manual}. The URL package provides a -function to do this in general: - -@defun url-decode-text-part handle &optional coding -This function decodes charset-encoded text in the current buffer. In -Emacs, the buffer is expected to be unibyte initially and is set to -multibyte after decoding. -HANDLE is the MIME handle of the original part. CODING is an explicit -coding to use, overriding what the MIME headers specify. -The coding system used for the decoding is returned. - -Note that this function doesn't deal with @samp{http-equiv} charset -specifications in HTML @samp{} elements. -@end defun - -@node file/ftp -@section file and ftp -@cindex files -@cindex FTP -@cindex File Transfer Protocol -@cindex compressed files -@cindex dired - -@example -ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -These schemes are defined in RFC 1808. -@samp{ftp:} and @samp{file:} are synonymous in this library. They -allow reading arbitrary files from hosts. Either @samp{ange-ftp} -(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote -hosts. Local files are accessed directly. - -Compressed files are handled, but support is hard-coded so that -@code{jka-compr-compression-info-list} and so on have no affect. -Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and -@samp{.bz2}. - -@defopt url-directory-index-file -The filename to look for when indexing a directory, default -@samp{"index.html"}. If this file exists, and is readable, then it -will be viewed instead of using @code{dired} to view the directory. -@end defopt - -@node info -@section info -@cindex Info -@cindex Texinfo -@findex Info-goto-node - -@example -info:@var{file}#@var{node} -@end example - -Info URLs are not officially defined. They invoke -@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}. -@samp{#@var{node}} is optional, defaulting to @samp{Top}. - -@node mailto -@section mailto - -@cindex mailto -@cindex email -A mailto URL will send an email message to the address in the -URL, for example @samp{mailto:foo@@bar.com} would compose a -message to @samp{foo@@bar.com}. - -@defopt url-mail-command -@vindex mail-user-agent -The function called whenever url needs to send mail. This should -normally be left to default from @var{mail-user-agent}. @xref{Mail -Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}. -@end defopt - -An @samp{X-Url-From} header field containing the URL of the document -that contained the mailto URL is added if that URL is known. - -RFC 2368 extends the definition of mailto URLs in RFC 1738. -The form of a mailto URL is -@example -@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]} -@end example -@noindent where an arbitrary number of @var{header}s can be added. If the -@var{header} is @samp{body}, then @var{contents} is put in the body -otherwise a @var{header} header field is created with @var{contents} -as its contents. Note that the URL library does not consider any -headers `dangerous' so you should check them before sending the -message. - -@c Fixme: update -Email messages are defined in @sc{rfc}822. - -@node news/nntp/snews -@section @code{news}, @code{nntp} and @code{snews} -@cindex news -@cindex network news -@cindex usenet -@cindex NNTP -@cindex snews - -@c draft-gilman-news-url-01 -The network news URL scheme take the following forms following RFC -1738 except that for compatibility with other clients, host and port -fields may be included in news URLs though they are properly only -allowed for nntp an snews. - -@table @samp -@item news:@var{newsgroup} -Retrieves a list of messages in @var{newsgroup}; -@item news:@var{message-id} -Retrieves the message with the given @var{message-id}; -@item news:* -Retrieves a list of all available newsgroups; -@item nntp://@var{host}:@var{port}/@var{newsgroup} -@itemx nntp://@var{host}:@var{port}/@var{message-id} -@itemx nntp://@var{host}:@var{port}/* -Similar to the @samp{news} versions. -@end table - -@samp{:@var{port}} is optional and defaults to :119. - -@samp{snews} is the same as @samp{nntp} except that the default port -is :563. -@cindex SSL -(It is tunneled through SSL.) - -An @samp{nntp} URL is the same as a news URL, except that the URL may -specify an article by its number. - -@defopt url-news-server -This variable can be used to override the default news server. -Usually this will be set by the Gnus package, which is used to fetch -news. -@cindex environment variable -@vindex NNTPSERVER -It may be set from the conventional environment variable -@code{NNTPSERVER}. -@end defopt - -@node rlogin/telnet/tn3270 -@section rlogin, telnet and tn3270 -@cindex rlogin -@cindex telnet -@cindex tn3270 -@cindex terminal emulation -@findex terminal-emulator - -These URL schemes from RFC 1738 for logon via a terminal emulator have -the form -@example -telnet://@var{user}:@var{password}@@@var{host}:@var{port} -@end example -but the @code{:@var{password}} component is ignored. - -To handle rlogin, telnet and tn3270 URLs, a @code{rlogin}, -@code{telnet} or @code{tn3270} (the program names and arguments are -hardcoded) session is run in a @code{terminal-emulator} buffer. -Well-known ports are used if the URL does not specify a port. - -@node irc -@section irc -@cindex IRC -@cindex Internet Relay Chat -@cindex ZEN IRC -@cindex ERC -@cindex rcirc -@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt) -@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc} -session to a function named in @code{url-irc-function}. - -@defopt url-irc-function -A function to actually open an IRC connection. -This function -must take five arguments, @var{host}, @var{port}, @var{channel}, -@var{user} and @var{password}. The @var{channel} argument specifies the -channel to join immediately, this can be @code{nil}. By default this is -@code{url-irc-rcirc}. -@end defopt -@defun url-irc-rcirc host port channel user password -Processes the arguments and lets @code{rcirc} handle the session. -@end defun -@defun url-irc-erc host port channel user password -Processes the arguments and lets @code{ERC} handle the session. -@end defun -@defun url-irc-zenirc host port channel user password -Processes the arguments and lets @code{zenirc} handle the session. -@end defun - -@node data -@section data -@cindex data URLs - -@example -data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data} -@end example - -Data URLs contain MIME data in the URL itself. They are defined in -RFC 2397. - -@var{media-type} is a MIME @samp{Content-Type} string, possibly -including parameters. It defaults to -@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be -omitted but the charset parameter supplied. If @samp{;base64} is -present, the @var{data} are base64-encoded. - -@node nfs -@section nfs -@cindex NFS -@cindex Network File System -@cindex automounter - -@example -nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file} -@end example - -The @samp{nfs:} scheme is defined in RFC 2224. It is similar to -@samp{ftp:} except that it points to a file on a remote host that is -handled by the automounter on the local host. - -@defvar url-nfs-automounter-directory-spec -@end defvar -A string saying how to invoke the NFS automounter. Certain @samp{%} -sequences are recognized: - -@table @samp -@item %h -The hostname of the NFS server; -@item %n -The port number of the NFS server; -@item %u -The username to use to authenticate; -@item %p -The password to use to authenticate; -@item %f -The filename on the remote server; -@item %% -A literal @samp{%}. -@end table - -Each can be used any number of times. - -@node cid -@section cid -@cindex Content-ID - -RFC 2111 - -@node about -@section about - -@node ldap -@section ldap -@cindex LDAP -@cindex Lightweight Directory Access Protocol - -The LDAP scheme is defined in RFC 2255. - -@node imap -@section imap -@cindex IMAP - -RFC 2192 - -@node man -@section man -@cindex @command{man} -@cindex Unix man pages -@findex man - -@example -@samp{man:@var{page-spec}} -@end example - -This is a non-standard scheme. @var{page-spec} is passed directly to -the Lisp @code{man} function. - -@node Defining New URLs -@chapter Defining New URLs - -@menu -* Naming conventions:: -* Required functions:: -* Optional functions:: -* Asynchronous fetching:: -* Supporting file-name-handlers:: -@end menu - -@node Naming conventions -@section Naming conventions - -@node Required functions -@section Required functions - -@node Optional functions -@section Optional functions - -@node Asynchronous fetching -@section Asynchronous fetching - -@node Supporting file-name-handlers -@section Supporting file-name-handlers - -@node General Facilities -@chapter General Facilities - -@menu -* Disk Caching:: -* Proxies:: -* Gateways in general:: -* History:: -@end menu - -@node Disk Caching -@section Disk Caching -@cindex Caching -@cindex Persistent Cache -@cindex Disk Cache - -The disk cache stores retrieved documents locally, whence they can be -retrieved more quickly. When requesting a URL that is in the cache, -the library checks to see if the page has changed since it was last -retrieved from the remote machine. If not, the local copy is used, -saving the transmission over the network. -@cindex Cleaning the cache -@cindex Clearing the cache -@cindex Cache cleaning -Currently the cache isn't cleared automatically. -@c Running the @code{clean-cache} shell script -@c fist is recommended, to allow for future cleaning of the cache. This -@c shell script will remove all files that have not been accessed since it -@c was last run. To keep the cache pared down, it is recommended that this -@c script be run from @i{at} or @i{cron} (see the manual pages for -@c crontab(5) or at(1) for more information) - -@defopt url-automatic-caching -Setting this variable non-@code{nil} causes documents to be cached -automatically. -@end defopt - -@defopt url-cache-directory -This variable specifies the -directory to store the cache files. It defaults to sub-directory -@file{cache} of @code{url-configuration-directory}. -@end defopt - -@c Fixme: function v. option, but neither used. -@c @findex url-cache-expired -@c @defopt url-cache-expired -@c This is a function to decide whether or not a cache entry has expired. -@c It takes two times as it parameters and returns non-@code{nil} if the -@c second time is ``too old'' when compared with the first time. -@c @end defopt - -@defopt url-cache-creation-function -The cache relies on a scheme for mapping URLs to files in the cache. -This variable names a function which sets the type of cache to use. -It takes a URL as argument and returns the absolute file name of the -corresponding cache file. The two supplied possibilities are -@code{url-cache-create-filename-using-md5} and -@code{url-cache-create-filename-human-readable}. -@end defopt - -@defun url-cache-create-filename-using-md5 url -Creates a cache file name from @var{url} using MD5 hashing. -This is creates entries with very few cache collisions and is fast. -@cindex MD5 -@smallexample -(url-cache-create-filename-using-md5 "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f" -@end smallexample -@end defun - -@defun url-cache-create-filename-human-readable url -Creates a cache file name from @var{url} more obviously connected to -@var{url} than for @code{url-cache-create-filename-using-md5}, but -more likely to conflict with other files. -@smallexample -(url-cache-create-filename-human-readable "http://www.example.com/foo/bar") - @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar" -@end smallexample -@end defun - -@c Fixme: never actually used currently? -@c @defopt url-standalone-mode -@c @cindex Relying on cache -@c @cindex Cache only mode -@c @cindex Standalone mode -@c If this variable is non-@code{nil}, the library relies solely on the -@c cache for fetching documents and avoids checking if they have changed -@c on remote servers. -@c @end defopt - -@c With a large cache of documents on the local disk, it can be very handy -@c when traveling, or any other time the network connection is not active -@c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely -@c solely on its cache, and avoid checking to see if the page has changed -@c on the remote server. In the case of a dial-on-demand PPP connection, -@c this will keep the phone line free as long as possible, only bringing up -@c the PPP connection when asking for a page that is not located in the -@c cache. This is very useful for demonstrations as well. - -@node Proxies -@section Proxies and Gatewaying - -@c fixme: check/document url-ns stuff -@cindex proxy servers -@cindex proxies -@cindex environment variables -@vindex HTTP_PROXY -Proxy servers are commonly used to provide gateways through firewalls -or as caches serving some more-or-less local network. Each protocol -(HTTP, FTP, etc.)@: can have a different gateway server. Proxying is -conventionally configured commonly amongst different programs through -environment variables of the form @code{@var{protocol}_proxy}, where -@var{protocol} is one of the supported network protocols (@code{http}, -@code{ftp} etc.). The library recognizes such variables in either -upper or lower case. Their values are of one of the forms: -@itemize @bullet -@item @code{@var{host}:@var{port}} -@item A full URL; -@item Simply a host name. -@end itemize - -@vindex NO_PROXY -The @code{NO_PROXY} environment variable specifies URLs that should be -excluded from proxying (on servers that should be contacted directly). -This should be a comma-separated list of hostnames, domain names, or a -mixture of both. Asterisks can be used as wildcards, but other -clients may not support that. Domain names may be indicated by a -leading dot. For example: -@example -NO_PROXY="*.aventail.com,home.com,.seanet.com" -@end example -@noindent says to contact all machines in the @samp{aventail.com} and -@samp{seanet.com} domains directly, as well as the machine named -@samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY} -and @code{no_proxy} are also tried, in that order. - -Proxies may also be specified directly in Lisp. - -@defopt url-proxy-services -This variable is an alist of URL schemes and proxy servers that -gateway them. The items are of the form @w{@code{(@var{scheme} -. @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is -gatewayed through @var{portnumber} on the specified @var{host}. An -exception is the pseudo scheme @code{"no_proxy"}, which is paired with -a regexp matching host names not to be proxied. This variable is -initialized from the environment as above. - -@example -(setq url-proxy-services - '(("http" . "proxy.aventail.com:80") - ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com"))) -@end example -@end defopt - -@node Gateways in general -@section Gateways in General -@cindex gateways -@cindex firewalls - -The library provides a general gateway layer through which all -networking passes. It can both control access to the network and -provide access through gateways in firewalls. This may make direct -connections in some cases and pass through some sort of gateway in -others.@footnote{Proxies (which only operate over HTTP) are -implemented using this.} The library's basic function responsible for -making connections is @code{url-open-stream}. - -@defun url-open-stream name buffer host service -@cindex opening a stream -@cindex stream, opening -Open a stream to @var{host}, possibly via a gateway. The other -arguments are as for @code{open-network-stream}. This will not make a -connection if @code{url-gateway-unplugged} is non-@code{nil}. -@end defun - -@defvar url-gateway-local-host-regexp -This is a regular expression that matches local hosts that do not -require the use of a gateway. If @code{nil}, all connections are made -through the gateway. -@end defvar - -@defvar url-gateway-method -This variable controls which gateway method is used. It may be useful -to bind it temporarily in some applications. It has values taken from -a list of symbols. Possible values are: - -@table @code -@item telnet -@cindex @command{telnet} -Use this method if you must first telnet and log into a gateway host, -and then run telnet from that host to connect to outside machines. - -@item rlogin -@cindex @command{rlogin} -This method is identical to @code{telnet}, but uses @command{rlogin} -to log into the remote machine without having to send the username and -password over the wire every time. - -@item socks -@cindex @sc{socks} -Use if the firewall has a @sc{socks} gateway running on it. The -@sc{socks} v5 protocol is defined in RFC 1928. - -@c @item ssl -@c This probably shouldn't be documented -@c Fixme: why not? -- fx - -@item native -This method uses Emacs's builtin networking directly. This is the -default. It can be used only if there is no firewall blocking access. -@end table -@end defvar - -The following variables control the gateway methods. - -@defopt url-gateway-telnet-host -The gateway host to telnet to. Once logged in there, you then telnet -out to the hosts you want to connect to. -@end defopt -@defopt url-gateway-telnet-parameters -This should be a list of parameters to pass to the @command{telnet} program. -@end defopt -@defopt url-gateway-telnet-password-prompt -This is a regular expression that matches the password prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-login-prompt -This is a regular expression that matches the username prompt when -logging in. -@end defopt -@defopt url-gateway-telnet-user-name -The username to log in with. -@end defopt -@defopt url-gateway-telnet-password -The password to send when logging in. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt url-gateway-rlogin-host -Host to @samp{rlogin} to before telnetting out. -@end defopt -@defopt url-gateway-rlogin-parameters -Parameters to pass to @samp{rsh}. -@end defopt -@defopt url-gateway-rlogin-user-name -User name to use when logging in to the gateway. -@end defopt -@defopt url-gateway-prompt-pattern -This is a regular expression that matches the shell prompt. -@end defopt - -@defopt socks-server -This specifies the default server, it takes the form -@w{@code{("Default server" @var{server} @var{port} @var{version})}} -where @var{version} can be either 4 or 5. -@end defopt -@defvar socks-password -If this is @code{nil} then you will be asked for the password, -otherwise it will be used as the password for authenticating you to -the @sc{socks} server. -@end defvar -@defvar socks-username -This is the username to use when authenticating yourself to the -@sc{socks} server. By default this is your login name. -@end defvar -@defvar socks-timeout -This controls how long, in seconds, to wait for responses from the -@sc{socks} server; it is 5 by default. -@end defvar -@c fixme: these have been effectively commented-out in the code -@c @defopt socks-server-aliases -@c This a list of server aliases. It is a list of aliases of the form -@c @var{(alias hostname port version)}. -@c @end defopt -@c @defopt socks-network-aliases -@c This a list of network aliases. Each entry in the list takes the form -@c @var{(alias (network))} where @var{alias} is a string that names the -@c @var{network}. The networks can contain a pair (not a dotted pair) of -@c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip} -@c address and a netmask, a domain name or a unique hostname or @sc{ip} -@c address. -@c @end defopt -@c @defopt socks-redirection-rules -@c This a list of redirection rules. Each rule take the form -@c @var{(Destination network Connection type)} where @var{Destination -@c network} is a network alias from @code{socks-network-aliases} and -@c @var{Connection type} can be @code{nil} in which case a direct -@c connection is used, or it can be an alias from -@c @code{socks-server-aliases} in which case that server is used as a -@c proxy. -@c @end defopt -@defopt socks-nslookup-program -@cindex @command{nslookup} -This the @samp{nslookup} program. It is @code{"nslookup"} by default. -@end defopt - -@menu -* Suppressing network connections:: -@end menu -@c * Broken hostname resolution:: - -@node Suppressing network connections -@subsection Suppressing Network Connections - -@cindex network connections, suppressing -@cindex suppressing network connections -@cindex bugs, HTML -@cindex HTML `bugs' -In some circumstances it is desirable to suppress making network -connections. A typical case is when rendering HTML in a mail user -agent, when external URLs should not be activated, particularly to -avoid `bugs' which `call home' by fetch single-pixel images and the -like. To arrange this, bind the following variable for the duration -of such processing. - -@defvar url-gateway-unplugged -If this variable is non-@code{nil} new network connections are never -opened by the URL library. -@end defvar - -@c @node Broken hostname resolution -@c @subsection Broken Hostname Resolution - -@c @cindex hostname resolver -@c @cindex resolver, hostname -@c Some C libraries do not include the hostname resolver routines in -@c their static libraries. If Emacs was linked statically, and was not -@c linked with the resolver libraries, it will not be able to get to any -@c machines off the local network. This is characterized by being able -@c to reach someplace with a raw ip number, but not its hostname -@c (@url{http://129.79.254.191/} works, but -@c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on -@c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be -@c rebuilt linked against the resolver library, it can use the external -@c @command{nslookup} program instead. - -@c @defopt url-gateway-broken-resolution -@c @cindex @code{nslookup} program -@c @cindex program, @code{nslookup} -@c If non-@code{nil}, this variable says to use the program specified by -@c @code{url-gateway-nslookup-program} program to do hostname resolution. -@c @end defopt - -@c @defopt url-gateway-nslookup-program -@c The name of the program to do hostname lookup if Emacs can't do it -@c directly. This program should expect a single argument on the command -@c line---the hostname to resolve---and should produce output similar to -@c the standard Unix @command{nslookup} program: -@c @example -@c Name: www.cs.indiana.edu -@c Address: 129.79.254.191 -@c @end example -@c @end defopt - -@node History -@section History - -@findex url-do-setup -The library can maintain a global history list tracking URLs accessed. -URL completion can be done from it. The history mechanism is set up -automatically via @code{url-do-setup} when it is configured to be on. -Note that the size of the history list is currently not limited. - -@vindex url-history-hash-table -The history `list' is actually a hash table, -@code{url-history-hash-table}. It contains access times keyed by URL -strings. The times are in the format returned by @code{current-time}. - -@defun url-history-update-url url time -This function updates the history table with an entry for @var{url} -accessed at the given @var{time}. -@end defun - -@defopt url-history-track -If non-@code{nil}, the library will keep track of all the URLs -accessed. If it is @code{t}, the list is saved to disk at the end of -each Emacs session. The default is @code{nil}. -@end defopt - -@defopt url-history-file -The file storing the history list between sessions. It defaults to -@file{history} in @code{url-configuration-directory}. -@end defopt - -@defopt url-history-save-interval -@findex url-history-setup-save-timer -The number of seconds between automatic saves of the history list. -Default is one hour. Note that if you change this variable directly, -rather than using Custom, after @code{url-do-setup} has been run, you -need to run the function @code{url-history-setup-save-timer}. -@end defopt - -@defun url-history-parse-history &optional fname -Parses the history file @var{fname} (default @code{url-history-file}) -and sets up the history list. -@end defun - -@defun url-history-save-history &optional fname -Saves the current history to file @var{fname} (default -@code{url-history-file}). -@end defun - -@defun url-completion-function string predicate function -You can use this function to do completion of URLs from the history. -@end defun - -@node Customization -@chapter Customization - -@section Environment Variables - -@cindex environment variables -The following environment variables affect the library's operation at -startup. - -@table @code -@item TMPDIR -@vindex TMPDIR -@vindex url-temporary-directory -If this is defined, @var{url-temporary-directory} is initialized from -it. -@end table - -@section General User Options - -The following user options, settable with Customize, affect the -general operation of the package. - -@defopt url-debug -@cindex debugging -Specifies the types of debug messages the library which are logged to -the @code{*URL-DEBUG*} buffer. -@code{t} means log all messages. -A number means log all messages and show them with @code{message}. -If may also be a list of the types of messages to be logged. -@end defopt -@defopt url-personal-mail-address -@end defopt -@defopt url-privacy-level -@end defopt -@defopt url-uncompressor-alist -@end defopt -@defopt url-passwd-entry-func -@end defopt -@defopt url-standalone-mode -@end defopt -@defopt url-bad-port-list -@end defopt -@defopt url-max-password-attempts -@end defopt -@defopt url-temporary-directory -@end defopt -@defopt url-show-status -@end defopt -@defopt url-confirmation-func -The function to use for asking yes or no functions. This is normally -either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another -function taking a single argument (the prompt) and returning @code{t} -only if an affirmative answer is given. -@end defopt -@defopt url-gateway-method -@c fixme: describe gatewaying -A symbol specifying the type of gateway support to use for connections -from the local machine. The supported methods are: - -@table @code -@item telnet -Run telnet in a subprocess to connect; -@item rlogin -Rlogin to another machine to connect; -@item socks -Connect through a socks server; -@item ssl -Connect with SSL; -@item native -Connect directly. -@end table -@end defopt - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Function Index -@unnumbered Command and Function Index -@printindex fn - -@node Variable Index -@unnumbered Variable Index -@printindex vr - -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@bye - -@ignore - arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0 -@end ignore diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi deleted file mode 100644 index a1ef6b9717a..00000000000 --- a/doc/misc/vip.texi +++ /dev/null @@ -1,1952 +0,0 @@ -\input texinfo -@setfilename ../../info/vip -@settitle VIP - -@copying -Copyright @copyright{} 1987, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@titlepage -@sp 10 -@center @titlefont{VIP} -@sp 1 -@center A Vi Package for GNU Emacs -@center (Version 3.5, September 15, 1987) -@sp 2 -@center Masahiko Sato -@page -@vskip 0pt plus1filll -@insertcopying -@end titlepage - -@finalout -@contents - -@dircategory Emacs -@direntry -* VIP: (vip). An older VI-emulation for Emacs. -@end direntry - -@ifnottex -@node Top, Survey,, (DIR) -@top VIP - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This info file describes the usage of VIP assuming that you -are fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read nodes on survey and on customization before -you start using VIP. Other nodes may be visited as needed. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill - -@insertcopying - -@end ifnottex - -@menu -* Survey:: A survey of VIP. -* Vi Commands:: Details of Vi commands. -* Ex Commands:: Details of Ex commands. -* Customization:: How to customize VIP. -* GNU Free Documentation License:: The license for this documentation. - -@end menu -@iftex -@unnumbered Introduction - -VIP is a Vi emulating package written in Emacs Lisp. VIP implements most -Vi commands including Ex commands. It is therefore hoped that this package -will enable you to do Vi style editing under the powerful GNU Emacs -environment. This manual describes the usage of VIP assuming that you are -fairly accustomed to Vi but not so much with Emacs. Also we will -concentrate mainly on differences from Vi, especially features unique to -VIP. - -It is recommended that you read chapters on survey and on customization -before you start using VIP. Other chapters may be used as future -references. - -Comments and bug reports are welcome. Please send messages to -@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to -@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan. -@end iftex - -@node Survey, Basic Concepts, Top, Top -@chapter A Survey of VIP - -In this chapter we describe basics of VIP with emphasis on the features not -found in Vi and on how to use VIP under GNU Emacs. - -@menu -* Basic Concepts:: Basic concepts in Emacs. -* Loading VIP:: How to load VIP automatically. -* Modes in VIP:: VIP has three modes, which are orthogonal to modes - in Emacs. -* Differences from Vi:: Differences of VIP from Vi is explained. -@end menu - -@node Basic Concepts, Loading VIP, Survey, Survey -@section Basic Concepts - -We begin by explaining some basic concepts of Emacs. These concepts are -explained in more detail in the GNU Emacs Manual. - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex region - -Conceptually, a @dfn{buffer} is just a string of @acronym{ASCII} characters and two -special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such -that the character @key{PNT} occurs exactly once and @key{MRK} occurs at -most once. The @dfn{text} of a buffer is obtained by deleting the -occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a -character following @key{PNT} then we say that point is @dfn{looking at} -the character; otherwise we say that point is @dfn{at the end of buffer}. -@key{PNT} and @key{MRK} are used -to indicate positions in a buffer and they are not part of the text of the -buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} -and @key{PNT} is called the @dfn{region} of the buffer.@refill - -@cindex window - -Emacs provides (multiple) @dfn{windows} on the screen, and you can see the -content of a buffer through the window associated with the buffer. The -cursor of the screen is always positioned on the character after @key{PNT}. -@refill - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap - -A @dfn{keymap} is a table that records the bindings between characters and -command functions. There is the @dfn{global keymap} common to all the -buffers. Each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if -a function is bound to some key in the local keymap then that function will -be executed when you type the key. If no function is bound to a key in the -local map, however, the function bound to the key in the global map becomes -in effect.@refill - -@node Loading VIP, Modes in VIP, Basic Concepts, Survey -@section Loading VIP - -The recommended way to load VIP automatically is to include the line: -@example -(load "vip") -@end example -@noindent -in your @file{.emacs} file. The @file{.emacs} file is placed in your home -directory and it will be executed every time you invoke Emacs. If you wish -to be in vi mode whenever Emacs starts up, you can include the following -line in your @file{.emacs} file instead of the above line: -@example -(setq term-setup-hook 'vip-mode) -@end example -@noindent -(@xref{Vi Mode}, for the explanation of vi mode.) - -Even if your @file{.emacs} file does not contain any of the above lines, -you can load VIP and enter vi mode by typing the following from within -Emacs. -@example -M-x vip-mode -@end example -@noindent - -@node Modes in VIP, Emacs Mode, Loading VIP, Survey -@section Modes in VIP - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) -@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs}) - -Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) -to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} -in GNU Emacs is @code{suspend-emacs}, but, you can also call -@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the -key bindings of Emacs remain the same after loading VIP.@refill - -@cindex vi mode - -Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be -called and you will be in @dfn{vi mode}. (Some major modes may locally bind -@kbd{C-z} to some special functions. In such cases, you can call -@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is -invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your -terminal does not have a @key{META} key you can enter it by typing -@kbd{@key{ESC} x}. The same effect can also be achieve by typing -@kbd{M-x vip-mode}.)@refill - -@cindex mode line - -You can observe the change of mode by looking at the @dfn{mode line}. For -instance, if the mode line is:@refill -@example ------Emacs: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -then it will change to: -@example ------Vi: *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. - -@cindex insert mode -@cindex emacs mode - -You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in -vi mode. Thus @kbd{C-z} toggles between these two modes.@refill - -Note that modes in VIP exist orthogonally to modes in Emacs. This means -that you can be in vi mode and at the same time, say, shell mode. - -Vi mode corresponds to Vi's command mode. From vi mode you can enter -@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command -keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc. - -In insert mode, the mode line will look like this: -@example ------Insert *scratch* (Lisp Interaction)----All------------ -@end example -@noindent -You can exit from insert mode by hitting @key{ESC} key as you do in Vi. - -That VIP has three modes may seem very complicated, but in fact it is not -so. VIP is implemented so that you can do most editing remaining only -in the two modes for Vi (that is vi mode and insert mode). - -@ifinfo -The figure below shows the transition of three modes in VIP. -@display - - - === C-z ==> == i,o ... ==> -emacs mode vi mode insert mode - <== X-z === <=== ESC ==== -@end display -@end ifinfo - -@menu -* Emacs Mode:: This is the mode you should know better. -* Vi Mode:: Vi commands are executed in this mode. -* Insert Mode:: You can enter text, and also can do editing if you - know enough Emacs commands. -@end menu - -@node Emacs Mode, Vi Mode, Modes in VIP, Modes in VIP -@subsection Emacs Mode - -@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) - -You will be in this mode just after you loaded VIP. You can do all -normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally -bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode -then you will be in vi mode.@refill - -@node Vi Mode, Insert Mode, Emacs Mode, Modes in VIP -@subsection Vi Mode - -This mode corresponds to Vi's command mode. Most Vi commands work as they -do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can -enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc. - -@node Insert Mode, Differences from Vi, Vi Mode, Modes in VIP -@subsection Insert Mode - -The key bindings in this mode is the same as in the emacs mode except for -the following 4 keys. So, you can move around in the buffer and change -its content while you are in insert mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode. -@item C-h -@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode) -Delete previous character. -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word. -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -Typing this key has the same effect as typing @key{ESC} in emacs mode. -Thus typing @kbd{C-z x} in insert mode will have the same effect as typing -@kbd{ESC x} in emacs mode. -@end table - -@node Differences from Vi, Undoing, Insert Mode, Survey -@section Differences from Vi - -The major differences from Vi are explained below. - -@menu -* Undoing:: You can undo more in VIP. -* Changing:: Commands for changing the text. -* Searching:: Search commands. -* z Command:: You can now use zH, zM and zL as well as z- etc. -* Counts:: Some Vi commands which do not accept a count now - accept one. -* Marking:: You can now mark the current point, beginning of - the buffer etc. -* Region Commands:: You can now give a region as an argument for delete - commands etc. -* New Commands:: Some new commands not available in Vi are added. -* New Bindings:: Bindings of some keys are changed for the - convenience of editing under Emacs. -* Window Commands:: Commands for moving among windows etc. -* Buffer Commands:: Commands for selecting buffers etc. -* File Commands:: Commands for visiting files etc. -* Misc Commands:: Other useful commands. -@end menu - -@node Undoing, Changing, Differences from Vi, Differences from Vi -@subsection Undoing - -@kindex 165 @kbd{u} (@code{vip-undo}) -@kindex 056 @kbd{.} (@code{vip-repeat}) - -You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo -a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous -changes. Undo is undoable as in Vi. So the content of the buffer will -be the same before and after @kbd{u u}.@refill - -@node Changing, Searching, Undoing, Differences from Vi -@subsection Changing - -Some commands which change a small number of characters are executed -slightly differently. Thus, if point is at the beginning of a word -@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}}, -then VIP will prompt you for a new word in the minibuffer by the prompt -@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or -@key{ESC} to complete the command. Before you enter @key{RET} or -@key{ESC} you can abort the command by typing @kbd{C-g}. In general, -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -you can abort a partially formed command by typing @kbd{C-g}.@refill - -@node Searching, z Command, Changing, Differences from Vi -@subsection Searching - -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) - -As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be -searched literally by default. To invoke a regular expression search, -first execute the search command @kbd{/} (or @kbd{?}) with empty search -string. (I.e, type @kbd{/} followed by @key{RET}.) -A search for empty string will toggle the search mode between vanilla -search and regular expression search. You cannot give an offset to the -search string. (It is a limitation.) By default, search will wrap around -the buffer as in Vi. You can change this by rebinding the variable -@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill - -@node z Command, Counts, Searching, Differences from Vi -@subsection z Command - -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) - -For those of you who cannot remember which of @kbd{z} followed by @key{RET}, -@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, -@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and -Last) line of the window.@refill - -@node Counts, Marking, z Command, Differences from Vi -@subsection Counts - -Some Vi commands which do not accept a count now accept one - -@table @kbd -@item p -@itemx P -@kindex 160 @kbd{p} (@code{vip-put-back}) -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Given counts, text will be yanked (in Vi's sense) that many times. Thus -@kbd{3 p} is the same as @kbd{p p p}. -@item o -@itemx O -@kindex 157 @kbd{o} (@code{vip-open-line}) -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Given counts, that many copies of text will be inserted. Thus -@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current -line. -@item / -@itemx ? -@kindex 057 @kbd{/} (@code{vip-search-forward}) -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Given a count @var{n}, @var{n}-th occurrence will be searched. -@end table - -@node Marking, Region Commands, Counts, Differences from Vi -@subsection Marking - -Typing an @kbd{m} followed by a lower-case character @var{ch} marks the -point to the register named @var{ch} as in Vi. In addition to these, we -have following key bindings for marking. - -@kindex 155 @kbd{m} (@code{vip-mark-point}) - -@table @kbd -@item m < -Set mark at the beginning of buffer. -@item m > -Set mark at the end of buffer. -@item m . -Set mark at point (and push old mark on mark ring). -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@node Region Commands, New Commands, Marking, Differences from Vi -@subsection Region Commands - -@cindex region - -Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination -with motion commands. It is now possible to use current region as the -argument to these operators. (A @dfn{region} is a part of buffer -delimited by point and mark.) The key @kbd{r} is used for this purpose. -Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead -of @kbd{r} the region will first be enlarged so that it will become the -smallest region containing the original region and consisting of whole -lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill - -@node New Commands, New Bindings, Region Commands, Differences from Vi -@subsection Some New Commands - -Note that the keys below (except for @kbd{R}) are not used in Vi. - -@table @kbd -@item C-a -@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line}) -Move point to the beginning of line. -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -If you have two or more windows in the screen, this key will move point to -the next window. -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode. -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Backward incremental search. -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Forward incremental search. -@item C-c -@itemx C-x -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -These keys will exit from vi mode and return to emacs mode temporarily. If -you hit one of these keys, Emacs will be in emacs mode and will believe -that you hit that key in emacs mode. For example, if you hit @kbd{C-x} -followed by @kbd{2}, then the current window will be split into 2 and you -will be in vi mode again. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you -can execute a single Emacs command. After executing the Emacs command you -will be in vi mode again. You can give a count before typing @kbd{\}. -Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} -before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above -the current line.@refill -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill current buffer if it is not modified. Useful when you selected a -buffer which you did not want. -@item Q -@itemx R -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -@kindex 122 @kbd{R} (@code{vip-replace-string}) -@kbd{Q} is for query replace and @kbd{R} is for replace. By default, -string to be replaced are treated literally. If you wish to do a regular -expression replace, first do replace with empty string as the string to be -replaced. In this way, you can toggle between vanilla and regular -expression replacement. -@item v -@itemx V -@kindex 166 @kbd{v} (@code{vip-find-file}) -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -These keys are used to Visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the minibuffer. @kbd{V} is -similar, but will use window different from the current window. -@item # -@kindex 0430 @kbd{#} (@code{vip-command-argument}) -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows. -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and -@kbd{s}.@refill -@item # c -@kindex 0432 @kbd{# c} (@code{downcase-region}) -Change upper-case characters in the region to lower case -(@code{downcase-region}). -@item # C -@kindex 0431 @kbd{# C} (@code{upcase-region}) -Change lower-case characters in the region to upper case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -@item # g -@kindex 0432 @kbd{# g} (@code{vip-global-execute}) -Execute last keyboard macro for each line in the region -(@code{vip-global-execute}).@refill -@item # q -@kindex 0432 @kbd{# q} (@code{vip-quote-region}) -Insert specified string at the beginning of each line in the region -(@code{vip-quote-region}). -@item # s -@kindex 0432 @kbd{# s} (@code{spell-region}) -Check spelling of words in the region (@code{spell-region}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last keyboard macro. -@end table - -@node New Bindings, Window Commands, New Commands, Differences from Vi -@subsection New Key Bindings - -In VIP the meanings of some keys are entirely different from Vi. These key -bindings are done deliberately in the hope that editing under Emacs will -become easier. It is however possible to rebind these keys to functions -which behave similarly as in Vi. @xref{Customizing Key Bindings}, for -details. - -@table @kbd -@item C-g -@itemx g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -In Vi, @kbd{C-g} is used to get information about the file associated to -the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is -used to abort a command (this is for compatibility with emacs mode.) -@item SPC -@itemx @key{RET} -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -Now these keys will scroll up and down the text of current window. -Convenient for viewing the text. -@item s -@itemx S -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -They are used to switch to a specified buffer. Useful for switching to -already existing buffer since buffer name completion is provided. Also -a default buffer will be given as part of the prompt, to which you can -switch by just typing @key{RET} key. @kbd{s} is used to select buffer -in the current window, while @kbd{S} selects buffer in another window. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -These keys will exit from vi mode and return to emacs mode temporarily. -If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe -that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover, -if the following character you type is an upper-case letter, then Emacs -will believe that you have typed the corresponding control character. -You will be in vi mode again after the command is executed. For example, -typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs -mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but -the idea here is that you can execute useful Emacs commands without typing -control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed -by @kbd{2}, then the current window will be split into 2 and you will be in -vi mode again.@refill -@end table - -In addition to these, @code{ctl-x-map} is slightly modified: - -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) - -@table @kbd -@item X 3 -@itemx C-x 3 -This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3). -@end table - -@node Window Commands, Buffer Commands, New Bindings, Differences from Vi -@subsection Window Commands - -In this and following subsections, we give a summary of key bindings for -basic functions related to windows, buffers and files. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Switch to next window. -@item X 1 -@itemx C-x 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows. -@item X 2 -@itemx C-x 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows. -@item X 3 -@itemx C-x 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@end table - -@node Buffer Commands, File Commands, Window Commands, Differences from Vi -@subsection Buffer Commands - -@table @kbd -@item s -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Switch to the specified buffer in the current window -(@code{vip-switch-to-buffer}). -@item S -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Switch to the specified buffer in another window -(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified. -@item X S -@itemx C-x C-s -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save the current buffer in the file associated to the buffer. -@end table - -@node File Commands, Misc Commands, Buffer Commands, Differences from Vi -@subsection File Commands - -@table @kbd -@item v -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window. -@item V -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window. -@item X W -@itemx C-x C-w -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into the specified file. -@item X I -@itemx C-x C-i -@kindex 1302 @kbd{X I} (@code{insert-file}) - -Insert specified file at point. -@end table - -@node Misc Commands, Vi Commands, File Commands, Differences from Vi -@subsection Miscellaneous Commands - -@table @kbd -@item X ( -@itemx C-x ( -@kindex 1301 @kbd{X (} (@code{start-kbd-macro}) -Start remembering keyboard macro. -@item X ) -@itemx C-x ) -@kindex 1301 @kbd{X )} (@code{end-kbd-macro}) -Finish remembering keyboard macro. -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item X Z -@itemx C-x C-z -@kindex 1302 @kbd{X Z} (@code{suspend-emacs}) -Suspend Emacs. -@item Z Z -Exit Emacs. -@itemx Q -Query replace. -@itemx R -Replace. -@end table - -@node Vi Commands, Numeric Arguments, Misc Commands, Top -@chapter Vi Commands - -This chapter describes Vi commands other than Ex commands implemented in -VIP. Except for the last section which discusses insert mode, all the -commands described in this chapter are to be used in vi mode. - -@menu -* Numeric Arguments:: Many commands accept numeric arguments -* Important Keys:: Some very important keys. -* Buffers and Windows:: Commands for handling buffers and windows. -* Files:: Commands for handling files. -* Viewing the Buffer:: How you can view the current buffer. -* Mark Commands:: Marking positions in a buffer. -* Motion Commands:: Commands for moving point. -* Searching and Replacing:: Commands for searching and replacing. -* Modifying Commands:: Commands for modifying the buffer. -* Other Vi Commands:: Miscellaneous Commands. -* Commands in Insert Mode:: Commands for entering insert mode. -@end menu - -@node Numeric Arguments, Important Keys, Vi Commands, Vi Commands -@section Numeric Arguments - -@cindex numeric arguments -@cindex count -@kindex 061 @kbd{1} (numeric argument) -@kindex 062 @kbd{2} (numeric argument) -@kindex 063 @kbd{3} (numeric argument) -@kindex 064 @kbd{4} (numeric argument) -@kindex 065 @kbd{5} (numeric argument) -@kindex 066 @kbd{6} (numeric argument) -@kindex 067 @kbd{7} (numeric argument) -@kindex 068 @kbd{8} (numeric argument) -@kindex 069 @kbd{9} (numeric argument) - -Most Vi commands accept a @dfn{numeric argument} which can be supplied as -a prefix to the commands. A numeric argument is also called a @dfn{count}. -In many cases, if a count is given, the command is executed that many times. -For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a -line. In this manual the metavariable @var{n} will denote a count.@refill - -@node Important Keys, Buffers and Windows, Numeric Arguments, Vi Commands -@section Important Keys - -The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated -functions are the same in any of emacs, vi and insert mode. - -@table @kbd -@item C-g -@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) -Quit. Cancel running or partially typed command (@code{keyboard-quit}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@end table - -In Emacs many commands are bound to the key strokes that start with -@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be -accessed from vi mode as easily as from emacs mode.@refill - -@table @kbd -@item C-x -@itemx C-c -@itemx @key{ESC} -@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) -@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) -@kindex 033 @kbd{ESC} (@code{vip-ESC}) -Typing one of these keys have the same effect as typing it in emacs mode. -Appropriate command will be executed according as the keys you type after -it. You will be in vi mode again after the execution of the command. -For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will -move to the beginning of the buffer and you will still be in vi mode. -@item C -@itemx X -@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) -@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) -Typing one of these keys have the effect of typing the corresponding -control character in emacs mode. Moreover, if you type an upper-case -character following it, that character will also be translated to the -corresponding control character. Thus typing @kbd{X W} in vi mode is the -same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again -after the execution of a command. -@item \ -@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) -Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, -and you can execute a single Emacs command. After executing the -Emacs command you will be in vi mode again. You can give a count before -typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert -@samp{+++++} before point.@refill -@end table - -@node Buffers and Windows, Files, Important Keys, Vi Commands -@section Buffers and Windows - -@cindex buffer -@cindex selected buffer -@cindex current buffer - -In Emacs the text you edit is stored in a @dfn{buffer}. -See GNU Emacs Manual, for details. There is always one @dfn{current} -buffer, also called the @dfn{selected buffer}.@refill - -@cindex window -@cindex modified (buffer) - -You can see the contents of buffers through @dfn{windows} created by Emacs. -When you have multiple windows on the screen only one of them is selected. -Each buffer has a unique name, and each window has a mode line which shows -the name of the buffer associated with the window and other information -about the status of the buffer. You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the content of -the buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. - -We have the following commands related to windows and buffers. - -@table @kbd -@item C-n -@kindex 016 @kbd{C-n} (@code{vip-next-window}) -Move cursor to the next-window (@code{vip-next-window}). -@item X 1 -@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) -Delete other windows and make the selected window fill the screen -@*(@code{delete-other-windows}). -@item X 2 -@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) -Split current window into two windows (@code{split-window-vertically}). -@item X 3 -@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) -Show current buffer in two windows. -@item s @var{buffer} @key{RET} -@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) -Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}). -@item S @var{buffer} @key{RET} -@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) -Similar but select a buffer named @var{buffer} in another window -@*(@code{vip-switch-to-buffer-other-window}). -@item K -@kindex 113 @kbd{K} (@code{vip-kill-buffer}) -Kill the current buffer if it is not modified or if it is not associated -with a file @*(@code{vip-kill-buffer}). -@item X B -@kindex 1302 @kbd{X B} (@code{list-buffers}) -List the existing buffers (@code{list-buffers}). -@end table - -@cindex buffer name completion - -As @dfn{buffer name completion} is provided, you have only to type in -initial substring of the buffer name which is sufficient to identify it -among names of existing buffers. After that, if you hit @key{TAB} the rest -of the buffer name will be supplied by the system, and you can confirm it -by @key{RET}. The default buffer name to switch to will also be prompted, -and you can select it by giving a simple @key{RET}. See GNU Emacs Manual -for details of completion. - -@node Files, Viewing the Buffer, Buffers and Windows, Vi Commands -@section Files - -We have the following commands related to files. They are used to visit, -save and insert files. - -@table @kbd -@item v @var{file} @key{RET} -@kindex 166 @kbd{v} (@code{vip-find-file}) -Visit specified file in the current window (@code{vip-find-file}). -@item V @var{file} @key{RET} -@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) -Visit specified file in another window (@code{vip-find-file-other-window}). -@item X S -@kindex 1302 @kbd{X S} (@code{save-buffer}) -Save current buffer to the file associated with the buffer. If no file is -associated with the buffer, the name of the file to write out the content -of the buffer will be asked in the minibuffer. -@item X W @var{file} @key{RET} -@kindex 1302 @kbd{X W} (@code{write-file}) -Write current buffer into a specified file. -@item X I @var{file} @key{RET} -@kindex 1302 @kbd{X I} (@code{insert-file}) -Insert a specified file at point. -@item g -@kindex 147 @kbd{g} (@code{vip-info-on-file}) -Give information on the file associated with the current buffer. Tell you -the name of the file associated with the buffer, the line number of the -current point and total line numbers in the buffer. If no file is -associated with the buffer, this fact will be indicated by the null file -name @samp{""}. -@end table - -@cindex visiting (a file) -@cindex default directory - -In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a -file in the current window, you can just type @kbd{v}. Emacs maintains the -@dfn{default directory} which is specific to each buffer. Suppose, for -instance, that the default directory of the current buffer is -@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the -minibuffer.@refill -@example -visit file: /usr/masahiko/lisp/ -@end example -@noindent -@cindex file name completion -If you wish to visit, say, @file{vip.el} in this directory, then you can -just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} -already exists in the directory, Emacs will visit that file, and if not, -the file will be created. Emacs will use the file name (@file{vip.el}, in -this case) as the name of the buffer visiting the file. In order to make -the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to -the buffer name. As the @dfn{file name completion} is provided here, you -can sometime save typing. For instance, suppose there is only one file in the -default directory whose name starts with @samp{v}, that is @samp{vip.el}. -Then if you just type @kbd{v @key{TAB}} then it will be completed to -@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} -@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the -example, let us now suppose that you wished to visit the file -@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get -after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or -@samp{../man/vip.texinfo} followed by @key{RET}. - -Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another -window. - -You can verify which file you are editing by typing @kbd{g}. (You can also -type @kbd{X B} to get information on other buffers too.) If you type -@kbd{g} you will get an information like below in the echo area:@refill -@example -"/usr/masahiko/man/vip.texinfo" line 921 of 1949 -@end example - -After you edited the buffer (@samp{vip.texinfo}, in our example) for a while, -you may wish to save it in a file. If you wish to save it in the file -associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this -case), you can just say @kbd{X S}. If you wish to save it in another file, -you can type @kbd{X W}. You will then get a similar prompt as you get for -@kbd{v}, to which you can enter the file name.@refill - -@node Viewing the Buffer, Mark Commands, Files, Vi Commands -@section Viewing the Buffer - -In this and next section we discuss commands for moving around in the -buffer. These command do not change the content of the buffer. The -following commands are useful for viewing the content of the current -buffer. - -@table @kbd -@item @key{SPC} -@itemx C-f -@kindex 040 @kbd{SPC} (@code{vip-scroll}) -@kindex 006 @kbd{C-f} (@code{vip-scroll-back}) -Scroll text of current window upward almost full screen. You can go -@i{forward} in the buffer by this command (@code{vip-scroll}). -@item @key{RET} -@itemx C-b -@kindex 015 @kbd{RET} (@code{vip-scroll-back}) -@kindex 002 @kbd{C-b} (@code{vip-scroll-back}) -Scroll text of current window downward almost full screen. You can go -@i{backward} in the buffer by this command (@code{vip-scroll-back}). -@itemx C-d -@kindex 004 @kbd{C-d} (@code{vip-scroll-up}) -Scroll text of current window upward half screen. You can go -@i{down} in the buffer by this command (@code{vip-scroll-down}). -@itemx C-u -@kindex 025 @kbd{C-u} (@code{vip-scroll-down}) -Scroll text of current window downward half screen. You can go -@i{up} in the buffer by this command (@code{vip-scroll-up}). -@item C-y -@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one}) -Scroll text of current window upward by one line (@code{vip-scroll-down-one}). -@item C-e -@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one}) -Scroll text of current window downward by one line (@code{vip-scroll-up-one}). -@end table -@noindent -You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}} -has the same effect as @kbd{@key{SPC} @key{SPC}}. - -The following commands reposition point in the window. - -@table @kbd -@item z H -@itemx z @key{RET} -@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) -@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) -Put point on the top (@i{home}) line in the window. So the current line -becomes the top line in the window. Given a count @var{n}, point will be -placed in the @var{n}-th line from top (@code{vip-line-to-top}). -@item z M -@itemx z . -@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) -@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) -Put point on the @i{middle} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from the middle line -(@code{vip-line-to-middle}). -@item z L -@itemx z - -@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) -@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) -Put point on the @i{bottom} line in the window. Given a count @var{n}, -point will be placed in the @var{n}-th line from bottom -(@code{vip-line-to-bottom}). -@item C-l -Center point in window and redisplay screen (@code{recenter}). -@end table - -@node Mark Commands, Motion Commands, Viewing the Buffer, Vi Commands -@section Mark Commands - -The following commands are used to mark positions in the buffer. - -@table @kbd -@item m @var{ch} -@kindex 155 @kbd{m} (@code{vip-mark-point}) -Store current point in the register @var{ch}. @var{ch} must be a -lower-case @acronym{ASCII} letter. -@item m < -Set mark at the beginning of current buffer. -@item m > -Set mark at the end of current buffer. -@item m . -Set mark at point. -@item m , -Jump to mark (and pop mark off the mark ring). -@end table - -@cindex mark ring - -Emacs uses the @dfn{mark ring} to store marked positions. The commands -@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the -latest element of the mark ring (replacing the oldest one). By repeating -the command `@kbd{m ,}' you can visit older and older marked positions. You -will eventually be in a loop as the mark ring is a ring. - -@node Motion Commands, Searching and Replacing, Mark Commands, Vi Commands -@section Motion Commands - -Commands for moving around in the current buffer are collected here. These -commands are used as an `argument' for the delete, change and yank commands -to be described in the next section. - -@table @kbd -@item h -@kindex 150 @kbd{h} (@code{vip-backward-char}) -Move point backward by one character. Signal error if point is at the -beginning of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-backward-char}). -@item l -@kindex 154 @kbd{l} (@code{vip-forward-char}) -Move point backward by one character. Signal error if point is at the -end of buffer, but (unlike Vi) do not complain otherwise -(@code{vip-forward-char}). -@item j -@kindex 152 @kbd{j} (@code{vip-next-line}) -Move point to the next line keeping the current column. If point is on the -last line of the buffer, a new line will be created and point will move to -that line (@code{vip-next-line}). -@item k -@kindex 153 @kbd{k} (@code{vip-previous-line}) -Move point to the previous line keeping the current column -(@code{vip-next-line}). -@item + -@kindex 053 @kbd{+} (@code{vip-next-line-at-bol}) -Move point to the next line at the first non-white character. If point is -on the last line of the buffer, a new line will be created and point will -move to the beginning of that line (@code{vip-next-line-at-bol}). -@item - -@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol}) -Move point to the previous line at the first non-white character -(@code{vip-previous-line-at-bol}). -@end table -@noindent -If a count is given to these commands, the commands will be repeated that -many times. - -@table @kbd -@item 0 -@kindex 060 @kbd{0} (@code{vip-beginning-of-line}) -Move point to the beginning of line (@code{vip-beginning-of-line}). -@item ^ -@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white}) -Move point to the first non-white character on the line -(@code{vip-bol-and-skip-white}). -@item $ -@kindex 044 @kbd{$} (@code{vip-goto-eol}) -Move point to the end of line (@code{vip-goto-eol}). -@item @var{n} | -@kindex 174 @kbd{|} (@code{vip-goto-col}) -Move point to the @var{n}-th column on the line (@code{vip-goto-col}). -@end table -@noindent -Except for the @kbd{|} command, these commands neglect a count. - -@cindex word - -@table @kbd -@item w -@kindex 167 @kbd{w} (@code{vip-forward-word}) -Move point forward to the beginning of the next word -(@code{vip-forward-word}). -@item W -@kindex 127 @kbd{W} (@code{vip-forward-Word}) -Move point forward to the beginning of the next word, where a @dfn{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item b -@kindex 142 @kbd{b} (@code{vip-backward-word}) -Move point backward to the beginning of a word (@code{vip-backward-word}). -@item B -@kindex 102 @kbd{B} (@code{vip-backward-Word}) -Move point backward to the beginning of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-forward-Word}). -@item e -@kindex 145 @kbd{e} (@code{vip-end-of-word}) -Move point forward to the end of a word (@code{vip-end-of-word}). -@item E -@kindex 105 @kbd{E} (@code{vip-end-of-Word}) -Move point forward to the end of a word, where a @i{word} is -considered as a sequence of non-white characters (@code{vip-end-of-Word}). -@end table -@noindent -@cindex syntax table -Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} -commands is determined by the @dfn{syntax table} effective in the current -buffer. Each major mode has its syntax mode, and therefore the meaning of -a word also changes as the major mode changes. See GNU Emacs Manual for -details of syntax table. - -@table @kbd -@item H -@kindex 110 @kbd{H} (@code{vip-window-top}) -Move point to the beginning of the @i{home} (top) line of the window. -Given a count @var{n}, go to the @var{n}-th line from top -(@code{vip-window-top}). -@item M -@kindex 115 @kbd{M} (@code{vip-window-middle}) -Move point to the beginning of the @i{middle} line of the window. Given -a count @var{n}, go to the @var{n}-th line from the middle line -(@code{vip-window-middle}). -@item L -@kindex 114 @kbd{L} (@code{vip-window-bottom}) -Move point to the beginning of the @i{lowest} (bottom) line of the -window. Given count, go to the @var{n}-th line from bottom -(@code{vip-window-bottom}). -@end table -@noindent -These commands can be used to go to the desired line visible on the screen. - -@table @kbd -@item ( -@kindex 050 @kbd{(} (@code{vip-backward-sentence}) -Move point backward to the beginning of the sentence -(@code{vip-backward-sentence}). -@item ) -@kindex 051 @kbd{)} (@code{vip-forward-sentence}) -Move point forward to the end of the sentence -(@code{vip-forward-sentence}). -@item @{ -@kindex 173 @kbd{@{} (@code{vip-backward-paragraph}) -Move point backward to the beginning of the paragraph -(@code{vip-backward-paragraph}). -@item @} -@kindex 175 @kbd{@}} (@code{vip-forward-paragraph}) -Move point forward to the end of the paragraph -(@code{vip-forward-paragraph}). -@end table -@noindent -A count repeats the effect for these commands. - -@table @kbd -@item G -@kindex 107 @kbd{G} (@code{vip-goto-line}) -Given a count @var{n}, move point to the @var{n}-th line in the buffer on -the first non-white character. Without a count, go to the end of the buffer -(@code{vip-goto-line}). -@item ` ` -@kindex 140 @kbd{`} (@code{vip-goto-mark}) -Exchange point and mark (@code{vip-goto-mark}). -@item ` @var{ch} -Move point to the position stored in the register @var{ch}. @var{ch} must -be a lower-case letter. -@item ' ' -@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white}) -Exchange point and mark, and then move point to the first non-white -character on the line (@code{vip-goto-mark-and-skip-white}). -@item ' @var{ch} -Move point to the position stored in the register @var{ch} and skip to the -first non-white character on the line. @var{ch} must be a lower-case letter. -@item % -@kindex 045 @kbd{%} (@code{vip-paren-match}) -Move point to the matching parenthesis if point is looking at @kbd{(}, -@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]} -@*(@code{vip-paren-match}). -@end table -@noindent -The command @kbd{G} mark point before move, so that you can return to the -original point by @kbd{` `}. The original point will also be stored in -the mark ring. - -The following commands are useful for moving points on the line. A count -will repeat the effect. - -@table @kbd -@item f @var{ch} -@kindex 146 @kbd{f} (@code{vip-find-char-forward}) -Move point forward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-forward}). -@item F @var{ch} -@kindex 106 @kbd{F} (@code{vip-find-char-backward}) -Move point backward to the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-find-char-backward}). -@item t @var{ch} -@kindex 164 @kbd{t} (@code{vip-goto-char-forward}) -Move point forward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-forward}). -@item T @var{ch} -@kindex 124 @kbd{T} (@code{vip-goto-char-backward}) -Move point backward upto the character @var{ch} on the line. Signal error if -@var{ch} could not be found (@code{vip-goto-char-backward}). -@item ; -@kindex 073 @kbd{;} (@code{vip-repeat-find}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command -(@code{vip-repeat-find}). -@item , -@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite}) -Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the -opposite direction (@code{vip-repeat-find-opposite}). -@end table - -@node Searching and Replacing, Modifying Commands, Motion Commands, Vi Commands -@section Searching and Replacing - -Following commands are available for searching and replacing. - -@cindex regular expression (search) - -@table @kbd -@item / @var{string} @key{RET} -@kindex 057 @kbd{/} (@code{vip-search-forward}) -Search the first occurrence of the string @var{string} forward starting -from point. Given a count @var{n}, the @var{n}-th occurrence of -@var{string} will be searched. If the variable @code{vip-re-search} has value -@code{t} then @dfn{regular expression} search is done and the string -matching the regular expression @var{string} is found. If you give an -empty string as @var{string} then the search mode will change from vanilla -search to regular expression search and vice versa -(@code{vip-search-forward}). -@item ? @var{string} @key{RET} -@kindex 077 @kbd{?} (@code{vip-search-backward}) -Same as @kbd{/}, except that search is done backward -(@code{vip-search-backward}). -@item n -@kindex 156 @kbd{n} (@code{vip-search-next}) -Search the previous search pattern in the same direction as before -(@code{vip-search-next}). -@item N -@kindex 116 @kbd{N} (@code{vip-search-Next}) -Search the previous search pattern in the opposite direction -(@code{vip-search-Next}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally. See GNU Emacs Manual for details -(@code{isearch-forward}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@cindex vanilla (replacement) -@cindex regular expression (replacement) -@item R @var{string} RET @var{newstring} -@kindex 122 @kbd{R} (@code{vip-replace-string}) -There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}. -If the mode is @i{vanilla} you will get a prompt @samp{Replace string:}, -and if the mode is @i{regular expression} you will ge a prompt -@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can -toggle these modes by giving a null string as @var{string}. If the mode is -vanilla, this command replaces every occurrence of @var{string} with -@var{newstring}. If the mode is regular expression, @var{string} is -treated as a regular expression and every string matching the regular -expression is replaced with @var{newstring} (@code{vip-replace-string}). -@item Q @var{string} RET @var{newstring} -@kindex 121 @kbd{Q} (@code{vip-query-replace}) -Same as @kbd{R} except that you will be asked form confirmation before each -replacement -@*(@code{vip-query-replace}). -@item r @var{ch} -@kindex 162 @kbd{r} (@code{vip-replace-char}) -Replace the character point is looking at by the character @var{ch}. Give -count, replace that many characters by @var{ch} (@code{vip-replace-char}). -@end table -@noindent -The commands @kbd{/} and @kbd{?} mark point before move, so that you can -return to the original point by @w{@kbd{` `}}. - -@node Modifying Commands, Delete Commands, Searching and Replacing, Vi Commands -@section Modifying Commands - -In this section, commands for modifying the content of a buffer are -described. These commands affect the region determined by a motion command -which is given to the commands as their argument. - -@cindex point commands -@cindex line commands - -We classify motion commands into @dfn{point commands} and -@dfn{line commands}. The point commands are as follows: -@example -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,} -@end example -@noindent -The line commands are as follows: -@example -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'} -@end example -@noindent -@cindex expanding (region) -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. - -@menu -* Delete Commands:: Commands for deleting text. -* Yank Commands:: Commands for yanking text in Vi's sense. -* Put Back Commands:: Commands for putting back deleted/yanked text. -* Change Commands:: Commands for changing text. -* Repeating and Undoing Modifications:: -@end menu -@node Delete Commands, Yank Commands, Modifying Commands, Modifying Commands -@subsection Delete Commands - -@table @kbd -@item d @var{motion-command} -@kindex 1440 @kbd{d} (@code{vip-command-argument}) -Delete the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{d $} will delete the region between point and end of -current line since @kbd{$} is a point command that moves point to end of line. -@kbd{d G} will delete the region between the beginning of current line and -end of the buffer, since @kbd{G} is a line command. A count given to the -command above will become the count for the associated motion command. -Thus, @kbd{3 d w} will delete three words. - -@kindex 042 @kbd{"} (@code{vip-command-argument}) -It is also possible to save the deleted text into a register you specify. -For example, you can say @kbd{" t 3 d w} to delete three words and save it -to register @kbd{t}. The name of a register is a lower-case letter between -@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to -a delete command, then the deleted text will be appended to the content of -the register having the corresponding lower-case letter as its name. So, -@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other -modifying commands also accept a register name as their argument, and we -will not repeat similar explanations. - -We have more delete commands as below. - -@table @kbd -@item d d -@kindex 1442 @kbd{d d} -Delete a line. Given a count @var{n}, delete @var{n} lines. -@item d r -@kindex 1442 @kbd{d r} -Delete current region. -@item d R -@kindex 1441 @kbd{d R} -Expand current region and delete it. -@item D -@kindex 104 @kbd{D} (@code{vip-kill-line}) -Delete to the end of a line (@code{vip-kill-line}). -@item x -@kindex 170 @kbd{x} (@code{vip-delete-char}) -Delete a character after point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-char}). -@item @key{DEL} -@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char}) -Delete a character before point. Given @var{n}, delete @var{n} characters -(@code{vip-delete-backward-char}). -@end table - -@node Yank Commands, Put Back Commands, Delete Commands, Modifying Commands -@subsection Yank Commands - -@cindex yank - -Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. -Here the word `yank' is used in Vi's sense. Thus yank commands do not -alter the content of the buffer, and useful only in combination with -commands that put back the yanked text into the buffer. - -@table @kbd -@item y @var{motion-command} -@kindex 1710 @kbd{y} (@code{vip-command-argument}) -Yank the region determined by the motion command @var{motion-command}. -@end table -@noindent -For example, @kbd{y $} will yank the text between point and the end of line -into an anonymous register, while @kbd{"c y $} will yank the same text into -register @kbd{c}. - -Use the following command to yank consecutive lines of text. - -@table @kbd -@item y y -@itemx Y -@kindex 131 @kbd{Y} (@code{vip-yank-line}) -@kindex 1712 @kbd{y y} (@code{vip-yank-line}) -Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}). -@item y r -@kindex 1712 @kbd{y r} -Yank current region. -@item y R -@kindex 1711 @kbd{y R} -Expand current region and yank it. -@end table - -@node Put Back Commands, Change Commands, Yank Commands, Modifying Commands -@subsection Put Back Commands -Deleted or yanked texts can be put back into the buffer by the command -below. - -@table @kbd -@item p -@kindex 160 @kbd{p} (@code{vip-put-back}) -Insert, after the character point is looking at, most recently -deleted/yanked text from anonymous register. Given a register name -argument, the content of the named register will be put back. Given a -count, the command will be repeated that many times. This command also -checks if the text to put back ends with a new line character, and if so -the text will be put below the current line (@code{vip-put-back}). -@item P -@kindex 120 @kbd{P} (@code{vip-Put-back}) -Insert at point most recently deleted/yanked text from anonymous register. -Given a register name argument, the content of the named register will -be put back. Given a count, the command will be repeated that many times. -This command also checks if the text to put back ends with a new line -character, and if so the text will be put above the current line rather -than at point (@code{vip-Put-back}). -@end table -@noindent -@cindex number register -Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the -buffer. It is also possible to specify @dfn{number register} which is a -numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is -specified, @var{n}-th previously deleted/yanked text will be put back. It -is an error to specify a number register for the delete/yank commands. - -@node Change Commands, Repeating and Undoing Modifications, Put Back Commands, Modifying Commands -@subsection Change Commands - -Most commonly used change command takes the following form. - -@table @kbd -@item c @var{motion-command} -@kindex 1430 @kbd{c} (@code{vip-command-argument}) -Replace the content of the region determined by the motion command -@var{motion-command} by the text you type. If the motion command is a -point command then you will type the text into minibuffer, and if the -motion command is a line command then the region will be deleted first and -you can insert the text in @var{insert mode}. -@end table -@noindent -For example, if point is at the beginning of a word @samp{foo} and you -wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} -is a point command, you will get the prompt @samp{foo =>} in the -minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change -command.@refill - -@table @kbd -@item c c -@kindex 1432 @kbd{c c} -Change a line. Given a count, that many lines are changed. -@item c r -@kindex 1432 @kbd{c r} -Change current region. -@item c R -@kindex 1431 @kbd{c R} -Expand current region and change it. -@end table - -@node Repeating and Undoing Modifications, Other Vi Commands, Change Commands, Modifying Commands -@subsection Repeating and Undoing Modifications - -VIP records the previous modifying command, so that it is easy to repeat -it. It is also very easy to undo changes made by modifying commands. - -@table @kbd -@item u -@kindex 165 @kbd{u} (@code{vip-undo}) -Undo the last change. You can undo more by repeating undo by the repeat -command @samp{.}. For example, you can undo 5 previous changes by typing -@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the -first undo command (@code{vip-undo}). -@item . -@kindex 056 @kbd{.} (@code{vip-repeat}) -Repeat the last modifying command. Given count @var{n} it becomes the new -count for the repeated command. Otherwise, the count for the last -modifying command is used again (@code{vip-repeat}). -@end table - -@node Other Vi Commands, Commands in Insert Mode, Repeating and Undoing Modifications, Vi Commands -@section Other Vi Commands - -Miscellaneous Vi commands are collected here. - -@table @kbd -@item Z Z -@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs}) -Exit Emacs. If modified buffers exist, you will be asked whether you wish -to save them or not (@code{save-buffers-kill-emacs}). -@item !@: @var{motion-command} @var{format-command} -@itemx @var{n} !@: !@: @var{format-command} -@kindex 041 @kbd{!} (@code{vip-command-argument}) -The region determined by the motion command @var{motion-command} will be -given to the shell command @var{format-command} and the region will be -replaced by its output. If a count is given, it will be passed to -@var{motion-command}. For example, @samp{3!Gsort} will sort the region -between point and the 3rd line. If @kbd{!} is used instead of -@var{motion-command} then @var{n} lines will be processed by -@var{format-command} (@code{vip-command-argument}). -@item J -@kindex 112 @kbd{J} (@code{vip-join-lines}) -Join two lines. Given count, join that many lines. A space will be -inserted at each junction (@code{vip-join-lines}). -@item < @var{motion-command} -@itemx @var{n} < < -@kindex 074 @kbd{<} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -left by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item > @var{motion-command} -@itemx @var{n} > > -@kindex 076 @kbd{>} (@code{vip-command-argument}) -Shift region determined by the motion command @var{motion-command} to -right by @var{shift-width} (default is 8). If @kbd{<} is used instead of -@var{motion-command} then shift @var{n} lines -@*(@code{vip-command-argument}). -@item = @var{motion-command} -@kindex 075 @kbd{=} (@code{vip-command-argument}) -Indent region determined by the motion command @var{motion-command}. If -@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines -(@code{vip-command-argument}). -@item * -@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) -Call last remembered keyboard macro. -@item # -A new vi operator. @xref{New Commands}, for more details. -@end table - -The following keys are reserved for future extensions, and currently -assigned to a function that just beeps (@code{vip-nil}). - -@kindex 046 @kbd{&} (@code{vip-nil}) -@kindex 100 @kbd{@@} (@code{vip-nil}) -@kindex 125 @kbd{U} (@code{vip-nil}) -@kindex 133 @kbd{[} (@code{vip-nil}) -@kindex 135 @kbd{]} (@code{vip-nil}) -@kindex 137 @kbd{_} (@code{vip-nil}) -@kindex 161 @kbd{q} (@code{vip-nil}) -@kindex 176 @kbd{~} (@code{vip-nil}) - -@example -&, @@, U, [, ], _, q, ~ -@end example - -VIP uses a special local keymap to interpret key strokes you enter in vi -mode. The following keys are bound to @var{nil} in the keymap. Therefore, -these keys are interpreted by the global keymap of Emacs. We give below a -short description of the functions bound to these keys in the global -keymap. See GNU Emacs Manual for details. - -@table @kbd -@item C-@@ -@kindex 000 @kbd{C-@@} (@code{set-mark-command}) -Set mark and push previous mark on mark ring (@code{set-mark-command}). -@item TAB -@kindex 011 TAB (@code{indent-for-tab-command}) -Indent line for current major mode (@code{indent-for-tab-command}). -@item C-j -@kindex 012 @kbd{C-j} (@code{newline-and-indent}) -Insert a newline, then indent according to mode (@code{newline-and-indent}). -@item C-k -@kindex 013 @kbd{C-k} (@code{kill-line}) -Kill the rest of the current line; before a newline, kill the newline. -With a numeric argument, kill that many lines from point. Negative arguments -kill lines backward (@code{kill-line}). -@item C-l -@kindex 014 @kbd{C-l} (@code{recenter}) -Clear the screen and reprint everything (@code{recenter}). -@item @var{n} C-p -@kindex 020 @kbd{C-p} (@code{previous-line}) -Move cursor vertically up @var{n} lines (@code{previous-line}). -@item C-q -@kindex 021 @kbd{C-q} (@code{quoted-insert}) -Read next input character and insert it. Useful for inserting control -characters -@*(@code{quoted-insert}). -@item C-r -@kindex 022 @kbd{C-r} (@code{isearch-backward}) -Search backward incrementally (@code{isearch-backward}). -@item C-s -@kindex 023 @kbd{C-s} (@code{isearch-forward}) -Search forward incrementally (@code{isearch-forward}). -@item @var{n} C-t -@kindex 024 @kbd{C-t} (@code{transpose-chars}) -Interchange characters around point, moving forward one character. With -count @var{n}, take character before point and drag it forward past @var{n} -other characters. If no argument and at end of line, the previous two -characters are exchanged (@code{transpose-chars}). -@item @var{n} C-v -@kindex 026 @kbd{C-v} (@code{scroll-up}) -Scroll text upward @var{n} lines. If @var{n} is not given, scroll near -full screen (@code{scroll-up}). -@item C-w -@kindex 027 @kbd{C-w} (@code{kill-region}) -Kill between point and mark. The text is save in the kill ring. The -command @kbd{P} or @kbd{p} can retrieve it from kill ring -(@code{kill-region}). -@end table - -@node Commands in Insert Mode, Ex Commands, Other Vi Commands, Vi Commands -@section Insert Mode - -You can enter insert mode by one of the following commands. In addition to -these, you will enter insert mode if you give a change command with a line -command as the motion command. Insert commands are also modifying commands -and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}). - -@table @kbd -@item i -@kindex 151 @kbd{i} (@code{vip-insert}) -Enter insert mode at point (@code{vip-insert}). -@item I -@kindex 111 @kbd{I} (@code{vip-Insert}) -Enter insert mode at the first non white character on the line -(@code{vip-Insert}). -@item a -@kindex 141 @kbd{a} (@code{vip-append}) -Move point forward by one character and then enter insert mode -(@code{vip-append}). -@item A -@kindex 101 @kbd{A} (@code{vip-Append}) -Enter insert mode at end of line (@code{vip-Append}). -@item o -@kindex 157 @kbd{o} (@code{vip-open-line}) -Open a new line below the current line and enter insert mode -(@code{vip-open-line}). -@item O -@kindex 117 @kbd{O} (@code{vip-Open-line}) -Open a new line above the current line and enter insert mode -(@code{vip-Open-line}). -@item C-o -@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) -Insert a newline and leave point before it, and then enter insert mode -@*(@code{vip-open-line-at-point}). -@end table - -Insert mode is almost like emacs mode. Only the following 4 keys behave -differently from emacs mode. - -@table @kbd -@item @key{ESC} -@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) -This key will take you back to vi mode (@code{vip-change-mode-to-vi}). -@item C-h -@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode) -Delete previous character (@code{delete-backward-char}). -@item C-w -@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) -Delete previous word (@code{vip-delete-backward-word}). -@item C-z -@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) -This key simulates @key{ESC} key in emacs mode. For instance, typing -@kbd{C-z x} in insert mode is the same as typing @kbd{ESC x} in emacs mode -(@code{vip-ESC}). -@end table -@noindent -You can also bind @kbd{C-h} to @code{help-command} if you like. -(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to -@code{help-command} has the effect of making the meaning of @kbd{C-h} -uniform among emacs, vi and insert modes. - -When you enter insert mode, VIP records point as the start point of -insertion, and when you leave insert mode the region between point and -start point is saved for later use by repeat command etc. Therefore, repeat -command will not really repeat insertion if you move point by emacs -commands while in insert mode. - -@node Ex Commands, Ex Command Reference, Commands in Insert Mode, Top -@chapter Ex Commands - -@kindex 072 @kbd{:} (@code{vip-ex}) - -In vi mode, you can execute an Ex command @var{ex-command} by typing: -@example -@kbd{:@: @var{ex-command} @key{RET}} -@end example -Every Ex command follows the following pattern: -@example -@var{address command} @kbd{!}@: @var{parameters count flags} -@end example -@noindent -@cindex address -where all parts are optional. For the syntax of @dfn{address}, the reader -is referred to the reference manual of Ex. - -@cindex magic -@cindex regular expression - -In the current version of VIP, searching by Ex commands is always -@dfn{magic}. That is, search patterns are always treated as @dfn{regular -expressions}. For example, a typical forward search would be invoked by -@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of -@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s -before @kbd{/} and the resulting @var{pat} becomes the actual search -pattern. Emacs provides a different and richer class or regular -expressions than Vi/Ex, and VIP uses Emacs' regular expressions. See GNU -Emacs Manual for details of regular expressions. - -Several Ex commands can be entered in a line by separating them by a pipe -character @samp{|}. - -@menu -* Ex Command Reference:: Explain all the Ex commands available in VIP. -@end menu -@node Ex Command Reference, Customization, Ex Commands, Ex Commands -@section Ex Command Reference -In this section we briefly explain all the Ex commands supported by VIP. -Most Ex commands expect @var{address} as their argument, and they use -default addresses if they are not explicitly given. In the following, such -default addresses will be shown in parentheses. - -Most command names can and preferably be given in abbreviated forms. In -the following, optional parts of command names will be enclosed in -brackets. For example, @samp{co[py]} will mean that copy command can be -give as @samp{co} or @samp{cop} or @samp{copy}. - -If @var{command} is empty, point will move to the beginning of the line -specified by the @var{address}. If @var{address} is also empty, point will -move to the beginning of the current line. - -@cindex flag - -Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and -@kbd{#}. If @var{flags} are given, the text affected by the commands will -be displayed on a temporary window, and you will be asked to hit return to -continue. In this way, you can see the text affected by the commands -before the commands will be executed. If you hit @kbd{C-g} instead of -@key{RET} then the commands will be aborted. Note that the meaning of -@var{flags} is different in VIP from that in Vi/Ex. - -@table @kbd -@item (.,.@:) co[py] @var{addr} @var{flags} -@itemx (.,.@:) t @var{addr} @var{flags} -Place a copy of specified lines after @var{addr}. If @var{addr} is -@kbd{0}, it will be placed before the first line. -@item (.,.@:) d[elete] @var{register} @var{count} @var{flags} -Delete specified lines. Text will be saved in a named @var{register} if a -lower-case letter is given, and appended to a register if a capital letter is -given. -@item e[dit] !@: +@var{addr} @var{file} -@itemx e[x] !@: +@var{addr} @var{file} -@itemx vi[sual] !@: +@var{addr} @var{file} -Edit a new file @var{file} in the current window. The command will abort -if current buffer is modified, which you can override by giving @kbd{!}. -If @kbd{+}@var{addr} is given, @var{addr} becomes the current line. -@item file -Give information about the current file. -@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds} -@itemx (1,$) v /@var{pat}/ @var{cmds} -Among specified lines first mark each line which matches the regular -expression @var{pat}, and then execute @var{cmds} on each marked line. -If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching -@var{pat}. @kbd{v} is same as @kbd{g!}. -@item (.,.+1) j[oin] !@: @var{count} @var{flags} -Join specified lines into a line. Without @kbd{!}, a space character will -be inserted at each junction. -@item (.@:) k @var{ch} -@itemx (.@:) mar[k] @var{ch} -Mark specified line by a lower-case character @var{ch}. Then the -addressing form @kbd{'}@var{ch} will refer to this line. No white space is -required between @kbd{k} and @var{ch}. A white space is necessary between -@kbd{mark} and @var{ch}, however. -@item map @var{ch} @var{rhs} -Define a macro for vi mode. After this command, the character @var{ch} -will be expanded to @var{rhs} in vi mode. -@item (.,.@:) m[ove] @var{addr} -Move specified lines after @var{addr}. -@item (.@:) pu[t] @var{register} -Put back previously deleted or yanked text. If @var{register} is given, -the text saved in the register will be put back; otherwise, last deleted or -yanked text will be put back. -@item q[uit] ! -Quit from Emacs. If modified buffers with associated files exist, you will -be asked whether you wish to save each of them. At this point, you may -choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from -Emacs without saving modified buffers. -@item (.@:) r[ead] @var{file} -Read in the content of the file @var{file} after the specified line. -@item (.@:) r[ead] !@: @var{command} -Read in the output of the shell command @var{command} after the specified -line. -@item se[t] -Set a variable's value. @xref{Customizing Constants}, for the list of variables -you can set. -@item sh[ell] -Run a subshell in a window. -@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags} -@itemx (.,.@:) & @var{options} @var{count} @var{flags} -On each specified line, the first occurrence of string matching regular -expression @var{pat} is replaced by replacement pattern @var{repl}. Option -characters are @kbd{g} and @kbd{c}. If global option character @kbd{g} -appears as part of @var{options}, all occurrences are substituted. If -confirm option character @kbd{c} appears, you will be asked to give -confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is -missing, the last substitution is repeated. -@item st[op] -Suspend Emacs. -@item ta[g] @var{tag} -@cindex tag -@cindex selected tags table -Find first definition of @var{tag}. If no @var{tag} is given, previously -given @var{tag} is used and next alternate definition is find. By default, -the file @file{TAGS} in the current directory becomes the @dfn{selected tags -table}. You can select another tags table by @kbd{set} command. -@xref{Customizing Constants}, for details. -@item und[o] -Undo the last change. -@item unm[ap] @var{ch} -The macro expansion associated with @var{ch} is removed. -@item ve[rsion] -Tell the version number of VIP. -@item (1,$) w[rite] !@: @var{file} -Write out specified lines into file @var{file}. If no @var{file} is given, -text will be written to the file associated to the current buffer. Unless -@kbd{!}@: is given, if @var{file} is different from the file associated to -the current buffer and if the file @var{file} exists, the command will not -be executed. Unlike Ex, @var{file} becomes the file associated to the -current buffer. -@item (1,$) w[rite]>> @var{file} -Write out specified lines at the end of file @var{file}. @var{file} -becomes the file associated to the current buffer. -@item (1,$) wq !@: @var{file} -Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as -@kbd{write !}@: then @kbd{quit}. -@item (.,.) y[ank] @var{register} @var{count} -Save specified lines into register @var{register}. If no register is -specified, text will be saved in an anonymous register. -@item @var{addr} !@: @var{command} -Execute shell command @var{command}. The output will be shown in a new -window. If @var{addr} is given, specified lines will be used as standard -input to @var{command}. -@item ($) = -Print the line number of the addressed line. -@item (.,.) > @var{count} @var{flags} -Shift specified lines to the right. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.) < @var{count} @var{flags} -Shift specified lines to the left. The variable @code{vip-shift-width} -(default value is 8) determines the amount of shift. -@item (.,.@:) ~ @var{options} @var{count} @var{flags} -Repeat the previous @kbd{substitute} command using previous search pattern -as @var{pat} for matching. -@end table - -The following Ex commands are available in Vi, but not implemented in VIP. -@example -@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source}, -@kbd{unabbreviate}, @kbd{xit}, @kbd{z} -@end example - -@node Customization, Customizing Constants, Ex Command Reference, Top -@chapter Customization - -If you have a file called @file{.vip} in your home directory, then it -will also be loaded when VIP is loaded. This file is thus useful for -customizing VIP. - -@menu -* Customizing Constants:: How to change values of constants. -* Customizing Key Bindings:: How to change key bindings. -@end menu - -@node Customizing Constants, Customizing Key Bindings, Customization, Customization -@section Customizing Constants -An easy way to customize VIP is to change the values of constants used -in VIP. Here is the list of the constants used in VIP and their default -values. - -@table @code -@item vip-shift-width 8 -The number of columns shifted by @kbd{>} and @kbd{<} command. -@item vip-re-replace nil -If @code{t} then do regexp replace, if @code{nil} then do string replace. -@item vip-search-wrap-around t -If @code{t}, search wraps around the buffer. -@item vip-re-search nil -If @code{t} then search is reg-exp search, if @code{nil} then vanilla -search. -@item vip-case-fold-search nil -If @code{t} search ignores cases. -@item vip-re-query-replace nil -If @code{t} then do reg-exp replace in query replace. -@item vip-open-with-indent nil -If @code{t} then indent to the previous current line when open a new line -by @kbd{o} or @kbd{O} command. -@item vip-tags-file-name "TAGS" -The name of the file used as the tags table. -@item vip-help-in-insert-mode nil -If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode, -if @code{nil} then it sis bound to @code{delete-backward-char}. -@end table -@noindent -You can reset these constants in VIP by the Ex command @kbd{set}. Or you -can include a line like this in your @file{.vip} file: -@example -(setq vip-case-fold-search t) -@end example - -@node Customizing Key Bindings,, Customizing Constants, Customization -@section Customizing Key Bindings - -@cindex local keymap - -VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. -For example, in vi mode, @key{SPC} is bound to the function -@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys - behave like Vi, you can include the following lines in your @file{.vip} -file. - -@example -(define-key vip-command-mode-map "\C-g" 'vip-info-on-file) -(define-key vip-command-mode-map "\C-h" 'vip-backward-char) -(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol) -(define-key vip-command-mode-map " " 'vip-forward-char) -(define-key vip-command-mode-map "g" 'vip-keyboard-quit) -(define-key vip-command-mode-map "s" 'vip-substitute) -(define-key vip-command-mode-map "C" 'vip-change-to-eol) -(define-key vip-command-mode-map "R" 'vip-change-to-eol) -(define-key vip-command-mode-map "S" 'vip-substitute-line) -(define-key vip-command-mode-map "X" 'vip-delete-backward-char) -@end example - -@node GNU Free Documentation License,,, Top -@appendix GNU Free Documentation License -@include doclicense.texi - - -@unnumbered Key Index - -@printindex ky - -@unnumbered Concept Index -@printindex cp - -@bye - -@ignore - arch-tag: 7c5d17b9-1d21-4261-a88a-b9fdbbf1020b -@end ignore diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi deleted file mode 100644 index 11f8f214663..00000000000 --- a/doc/misc/viper.texi +++ /dev/null @@ -1,4547 +0,0 @@ -% -*-texinfo-*- -\input texinfo - -@comment Using viper.info instead of viper in setfilename breaks DOS. -@comment @setfilename viper -@comment @setfilename viper.info -@setfilename ../../info/viper - -@copying -Copyright @copyright{} 1995, 1996, 1997, 2001, 2002, 2003, 2004, -2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation License''. - -(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and -modify this GNU manual. Buying copies from the FSF supports it in -developing GNU and promoting software freedom.'' -@end quotation -@end copying - -@dircategory Emacs -@direntry -* VIPER: (viper). The newest Emacs VI-emulation mode. - (also, A VI Plan for Emacs Rescue - or the VI PERil.) -@end direntry - -@finalout - -@titlepage -@title Viper Is a Package for Emacs Rebels -@subtitle a Vi emulator for Emacs -@subtitle November 2008, Viper Version 3.11.2 - -@author Michael Kifer (Viper) -@author Aamod Sane (VIP 4.4) -@author Masahiko Sato (VIP 3.5) - -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview,, (DIR) - -@unnumbered Viper - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Technically speaking, Viper is a Vi emulation package for Emacs. It -implements all Vi and Ex commands, occasionally improving on them and -adding many new features. It gives the user the best of both worlds: Vi -keystrokes for editing combined with the power of the Emacs environment. - -Viper emulates Vi at several levels, from the one that closely follows Vi -conventions to the one that departs from many of them. It has many -customizable options, which can be used to tailor Viper to the work habits -of various users. -This manual describes Viper, concentrating on the differences from Vi and -new features of Viper. - -Viper, formerly known as VIP-19, was written by Michael Kifer. It is based -on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane. -About 15% of the code still comes from those older packages. - -Viper is intended to be usable without reading this manual --- the defaults -are set to make Viper as close to Vi as possible. At startup, Viper will -try to set the most appropriate default environment for you, based on -your familiarity with Emacs. It will also tell you the basic GNU Emacs window -management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the Overview node. The other nodes may -be visited as needed. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill - -@insertcopying -@end ifnottex - -@menu -* Overview:: Read for a smoother start -* Improvements over Vi:: New features, Improvements -* Customization:: How to customize Viper -* Commands:: Vi and Ex Commands - -* Key Index:: Index of Vi and Ex Commands -* Function Index:: Index of Viper Functions -* Variable Index:: Index of Viper Variables -* Package Index:: Index of Packages Mentioned in this Document -* Concept Index:: Vi, Ex and Emacs concepts - -* Acknowledgments:: -* GNU Free Documentation License:: The license for this documentation. - -@end menu -@iftex -@unnumbered Introduction - -We believe that one or more of the following statements are adequate -descriptions of Viper: - -@example -Viper Is a Package for Emacs Rebels; -it is a VI Plan for Emacs Rescue -and/or a venomous VI PERil. -@end example - -Viper is a Vi emulation package for Emacs. Viper contains virtually all -of Vi and Ex functionality and much more. It gives you the best of both -worlds: Vi keystrokes for editing combined with the GNU Emacs -environment. Viper also fixes some common complaints with Vi commands. -This manual describes Viper, concentrating on the differences from Vi -and on the new features of Viper. - -Viper was written by Michael Kifer. It is based on VIP version 3.5 by -Masahiko Sato and VIP version 4.4 by Aamod Sane. About 15% of the code -still comes from those older packages. - -Viper is intended to be usable out of the box, without reading this manual ---- the defaults are set to make Viper as close to Vi as possible. At -startup, Viper will attempt to set the most appropriate default environment -for you, based on your familiarity with Emacs. It will also tell you the -basic GNU Emacs window management commands to help you start immediately. - -Although this manual explains how to customize Viper, some basic -familiarity with Emacs Lisp is a plus. - -It is recommended that you read the chapter Overview. The other chapters -will be useful for customization and advanced usage. - -You should also learn to use the Info on-line hypertext manual system that -comes with Emacs. This manual can be read as an Info file. Try the command -@kbd{@key{ESC} x info} with vanilla Emacs sometime. - -Comments and bug reports are welcome. -@code{kifer@@cs.stonybrook.edu} is the current address for Viper bug reports. -Please use the Ex command @kbd{:submitReport} for this purpose.@refill - -@end iftex - -@node Overview,Improvements over Vi,Top,Top -@chapter Overview of Viper - -Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a -virtually unrestricted access to Emacs facilities. Perfect compatibility -with Vi is possible but not desirable. This chapter tells you about the -Emacs ideas that you should know about, how to use Viper within Emacs and -some incompatibilities. - -This manual is written with the assumption that you are an experienced Vi -user who wants to switch to Emacs while retaining the ability to edit files -Vi style. Incredible as it might seem, there are experienced Emacs users -who use Viper as a backdoor into the superior (as every Vi user already knows) -world of Vi! These users are well familiar with Emacs bindings and prefer them -in some cases, especially in the Vi Insert state. John Hawkins - has provided a set of customizations, which -enables additional Emacs bindings under Viper. These customizations can be -included in your @file{~/.viper} file and are found at the following URL: -@file{http://traeki.freeshell.org/files/viper-sample}. - -@menu -* Emacs Preliminaries:: Basic concepts in Emacs. -* Loading Viper:: Loading and Preliminary Configuration. -* States in Viper:: Viper has four states orthogonal to Emacs - modes. -* The Minibuffer:: Command line in Emacs. -* Multiple Files in Viper:: True multiple file handling. -* Unimplemented Features:: That are unlikely to be implemented. -@end menu - -@node Emacs Preliminaries, Loading Viper, Overview, Overview -@section Emacs Preliminaries - -@cindex buffer -@cindex point -@cindex mark -@cindex text -@cindex looking at -@cindex end (of buffer) -@cindex end (of line) -@cindex region - -Emacs can edit several files at once. A file in Emacs is placed in a -@dfn{buffer} that usually has the same name as the file. Buffers are also used -for other purposes, such as shell interfaces, directory editing, etc. -@xref{Dired,,Directory Editor,emacs,The -GNU Emacs Manual}, for an example.@refill - -A buffer has a distinguished position called the @dfn{point}. -A @dfn{point} is always between 2 characters, and is @dfn{looking at} -the right hand character. The cursor is positioned on the right hand -character. Thus, when the @dfn{point} is looking at the end-of-line, -the cursor is on the end-of-line character, i.e.@: beyond the last -character on the line. This is the default Emacs behavior.@refill - -The default settings of Viper try to mimic the behavior of Vi, preventing -the cursor from going beyond the last character on the line. By using -Emacs commands directly (such as those bound to arrow keys), it is possible -to get the cursor beyond the end-of-line. However, this won't (or -shouldn't) happen if you restrict yourself to standard Vi keys, unless you -modify the default editing style. @xref{Customization}.@refill - -In addition to the @dfn{point}, there is another distinguished buffer -position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs -manual}, for more info on the mark. The text between the @dfn{point} and -the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper -user, this simply means that in addition to the Vi textmarkers a--z, there -is another marker called @dfn{mark}. This is similar to the unnamed Vi -marker used by the jump commands @kbd{``} and @kbd{''}, which move the -cursor to the position of the last absolute jump. Viper provides access to -the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix -to commands that operate on text regions, e.g., @kbd{dr} to delete region, -etc. - -Furthermore, Viper lets Ex-style commands to work on the current region. -This is done by typing a digit argument before @kbd{:}. For instance, -typing @kbd{1:} will prompt you with something like @emph{:123,135}, -assuming that the current region starts at line 123 and ends at line -135. There is no need to type the line numbers, since Viper inserts them -automatically in front of the Ex command. - -@xref{Basics}, for more info.@refill - -@cindex window -@cindex mode line -@cindex buffer information -@cindex Minibuffer -@cindex command line -@cindex buffer (modified) - -Emacs divides the screen into tiled @dfn{windows}. You can see the -contents of a buffer through the window associated with the buffer. The -cursor of the screen is positioned on the character after @dfn{point}. -Every window has a @dfn{mode line} that displays information about the buffer. -You can change the format of the mode -line, but normally if you see @samp{**} at the beginning of a mode line it -means that the buffer is @dfn{modified}. If you write out the contents of -a buffer to a file, then the buffer will become not modified. Also if -you see @samp{%%} at the beginning of the mode line, it means that the file -associated with the buffer is write protected. The mode line will also -show the buffer name and current major and minor modes (see below). -A special buffer called @dfn{Minibuffer} is displayed as the last line -in a Minibuffer window. The Minibuffer window is used for command input -output. Viper uses Minibuffer window for @kbd{/} and @kbd{:} -commands.@refill - -@cindex mode -@cindex keymap -@cindex local keymap -@cindex global keymap -@cindex major mode -@cindex minor mode - -An Emacs buffer can have a @dfn{major mode} that customizes Emacs for -editing text of a particular sort by changing the functionality of the keys. -Keys are defined using a @dfn{keymap} that records the bindings between -keystrokes and -functions. The @dfn{global keymap} is common to all the -buffers. Additionally, each buffer has its @dfn{local keymap} that determines the -@dfn{mode} of the buffer. If a function is bound to some key in the local -keymap then that function will be executed when you type the key. -If no function is bound to a key in the -local map, however, the function bound to the key in the global map -will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The -GNU Emacs Manual}, for more information.@refill - -A buffer can also have a @dfn{minor mode}. Minor modes are options that -you can use or not. A buffer in @code{text-mode} can have -@code{auto-fill-mode} as minor mode, which can be turned off or on at -any time. In Emacs, a minor mode may have it own keymap, -which overrides the local keymap when the minor mode is turned on. For -more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The -GNU Emacs Manual} @refill - -@cindex Viper as minor mode -@cindex Control keys -@cindex Meta key - -Viper is implemented as a collection of minor modes. Different minor modes -are involved when Viper emulates Vi command mode, Vi insert mode, etc. -You can also turn Viper on and off at any time while in Vi command mode. -@xref{States in Viper}, for -more information.@refill - -Emacs uses Control and Meta modifiers. These are denoted as C and M, -e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is -usually located on each side of the Space bar; it is used in a manner -similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while -holding the Meta key down. For keyboards that do not have a Meta key, -@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} -x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore -Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for -more info.@refill - -Emacs is structured as a Lisp interpreter around a C core. Emacs keys -cause Lisp functions to be called. It is possible to call these -functions directly, by typing @kbd{M-x function-name}. - -@node Loading Viper, States in Viper, Emacs Preliminaries, Overview -@section Loading Viper - -The most common way to load it automatically is to include the following -lines (in the given order!): - -@lisp -(setq viper-mode t) -(require 'viper) -@end lisp - -@noindent -in your @file{~/.emacs} file. The @file{.emacs} file is placed in your -home directory and it is be executed every time you invoke Emacs. This is -the place where all general Emacs customization takes place. Beginning with -version 20.0, Emacsen have an interactive interface, which simplifies the -job of customization significantly. - -Viper also uses the file @file{~/.viper} for Viper-specific customization. -The location of Viper customization file can be changed by setting the -variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading -Viper. - -The latest versions of Emacs have an interactive customization facility, -which allows you to (mostly) bypass the use of the @file{.emacs} and -@file{.viper} files. You can reach this customization -facility from within Viper's VI state by executing the Ex command -@kbd{:customize}. - -Once invoked, Viper will arrange to bring up Emacs buffers in Vi state -whenever this makes sense. -@xref{Packages that Change Keymaps}, to find out when forcing Vi command state -on a buffer may be counter-productive. - -Even if your @file{.emacs} file does not invoke Viper automatically, -you can still load Viper and enter the Vi command state by typing the -following from within Emacs: - -@lisp -M-x viper-mode -@end lisp - -When Emacs first comes up, if you have not specified a file on the -command line, it will show the @samp{*scratch*} buffer, in the -@samp{Lisp Interaction} mode. After you invoke Viper, you can start -editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. -(@xref{File and Buffer Handling}, for more information on @kbd{v} and other -new commands that, in many cases, are more convenient than @kbd{:e}, -@kbd{:vi}, and similar old-style Vi commands.)@refill - -Finally, if at some point you would want to de-Viperize your running -copy of Emacs after Viper has been loaded, the command @kbd{M-x -viper-go-away} will do it for you. The function @code{toggle-viper-mode} -toggles Viperization of Emacs on and off. - -@node States in Viper, The Minibuffer, Loading Viper,Overview -@section States in Viper - -@kindex @kbd{C-z} -@kindex @key{ESC} -@kindex @kbd{i} -@cindex Emacs state -@cindex Vi state -@cindex Insert state -@cindex Replace state -@cindex Ex commands -@findex @code{viper-go-away} -@findex @code{toggle-viper-mode} - -Viper has four states, Emacs, Vi, Insert, and Replace. - -@table @samp -@item Emacs state -This is the state plain vanilla Emacs is normally in. After you have loaded -Viper, @kbd{C-z} will normally take you to Vi command state. Another -@kbd{C-z} will take you back to Emacs state. This toggle key can be -changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to -change to Vi state.@refill - - -For users who chose to set their user level to 1 at Viper setup time, -switching to Emacs state is deliberately made harder in order to not -confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs -(if Emacs runs as an application under X) or it will stop Emacs (if -Emacs runs on a dumb terminal or in an Xterm window). - -@item Vi state -This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a}, -@dots{}, will take you to Insert state. All Vi commands may -be used in this mode. Most Ex commands can also be used. -For a full list of Ex commands supported by Viper, type -@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex -commands, type @kbd{:help}. This will invoke Viper Info -(if it is installed). Then typing @kbd{i} will prompt you for a topic to -search in the index. Note: to search for Ex commands in the index, you -should start them with a @kbd{:}, e.g., @kbd{:WW}. - -In Viper, Ex commands can be made to work on the current Emacs region. -This is done by typing a digit argument before @kbd{:}. -For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. - -@item Insert state -Insert state is the Vi insertion mode. @key{ESC} will take you back to -Vi state. Insert state editing can be done, including auto-indentation. By -default, Viper disables Emacs key bindings in Insert state. - -@item Replace state -Commands like @kbd{cw} invoke the Replace state. When you cross the -boundary of a replacement region (usually designated via a @samp{$} sign), -it will automatically change to Insert state. You do not have to worry -about it. The key bindings remain practically the same as in Insert -state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the -replacement state.@refill -@end table - -@cindex mode line - -The modes are indicated on the @dfn{mode line} as , , , and , -so that the multiple modes do not confuse you. Most of your editing can be -done in Vi and Insert states. Viper will try to make all new buffers be in Vi -state, but sometimes they may come up in Emacs state. @kbd{C-z} -will take you to Vi state in such a case. In some major modes, like Dired, -Info, Gnus, etc., you should not switch to Vi state (and Viper will not -attempt to do so) because these modes are not intended for text editing and -many of the Vi keys have special meaning there. If you plan to read news, -browse directories, read mail, etc., from Emacs (which you should start -doing soon!), you should learn about the meaning of the various keys in -those special modes (typing @kbd{C-h m} in a buffer provides -help with key bindings for the major mode of that buffer). - -If you switch to Vi in Dired or similar modes---no harm is done. It is just -that the special key bindings provided by those modes will be temporarily -overshadowed by Viper's bindings. Switching back to Viper's Emacs state -will revive the environment provided by the current major mode. - -States in Viper are orthogonal to Emacs major modes, such as C mode or Dired -mode. You can turn Viper on and off for any Emacs state. When Viper is turned -on, Vi state can be used to move around. In Insert state, the bindings for -these modes can be accessed. For beginners (users at Viper levels 1 and 2), -these bindings are suppressed in Insert state, so that new users are not -confused by the Emacs states. Note that unless you allow Emacs bindings in -Insert state, you cannot do many interesting things, like language -sensitive editing. For the novice user (at Viper level 1), all major mode -bindings are turned off in Vi state as well. This includes the bindings for -key sequences that start with @kbd{C-c}, which practically means that all -major mode bindings are unsupported. @xref{Customization}, to find out how -to allow Emacs keys in Insert state. - -@menu -* Emacs State:: This is the state you should learn more about when - you get up to speed with Viper. -* Vi State:: Vi commands are executed in this state. -* Insert State:: You can enter text, and also can do sophisticated - editing if you know enough Emacs commands. -* Replace State:: Like Insert mode, but it is invoked via the - replacement commands, such as cw, C, R, etc. -@end menu - -@node Emacs State, Vi State, States in Viper, States in Viper -@subsection Emacs State - -@kindex @kbd{C-z} -@cindex Emacs state - - -You will be in this mode only by accident (hopefully). This is the state -Emacs is normally in (imagine!!). Now leave it as soon as possible by -typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-). - -Emacs state is actually a Viperism to denote all the major and minor modes -(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs -can have several modes, such as C mode for editing C programs, LaTeX mode -for editing LaTeX documents, Dired for directory editing, etc. These are -major modes, each with a different set of key-bindings. Viper states are -orthogonal to these Emacs major modes. The presence of these language -sensitive and other modes is a major win over Vi. @xref{Improvements over -Vi}, for more.@refill - -The bindings for these modes can be made available in the Viper Insert state -as well as in Emacs state. Unless you specify your user level as 1 (a -novice), all major mode key sequences that start with @kbd{C-x} and -@kbd{C-c} are also available in Vi state. This is important because major -modes designed for editing files, such as cc-mode or latex-mode, use key -sequences that begin with @kbd{C-x} and @kbd{C-c}. - -There is also a key that lets you temporarily escape to Vi command state -from the Insert state: typing @kbd{C-z} will let you execute a -single Vi command while staying in Viper's Insert state. - - -@node Vi State, Insert State, Emacs State, States in Viper -@subsection Vi State - -@cindex Vi state - -This is the Vi command mode. When Viper is in Vi state, you will see the sign - in the mode line. Most keys will work as in Vi. The notable -exceptions are: - -@table @kbd -@item C-x -@kindex @kbd{C-x} -@kbd{C-x} is used to invoke Emacs commands, mainly those that do window -management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a -window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to -switch buffers in a window, and @kbd{C-xo} to move through windows. -These are about the only necessary keystrokes. -For the rest, see the GNU Emacs Manual. - -@item C-c -@kindex @kbd{C-c} -For user levels 2 and higher, this key serves as a prefix key for the key -sequences used by various major modes. For users at Viper level 1, @kbd{C-c} -simply beeps. - -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} - -These are the Emacs @samp{quit} keys. -There will be cases where you will have to -use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit -@samp{Recursive Edits} in Emacs for which there is no comparable Vi -functionality and no key-binding. Recursive edits are indicated by -@samp{[]} brackets framing the modes on the mode line. -@xref{Recursive Edit,Recursive -Edit,Recursive Edit,emacs,The GNU Emacs Manual}. -At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} -function instead. -@refill -@item C-\ -@kindex @kbd{C-\} -@cindex Meta key - -Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses -@key{ESC} for Meta. The Meta key is very important in Emacs since many -functions are accessible only via that key as @kbd{M-x function-name}. -Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and -Replace states, the meta key is set to be @kbd{C-\}. Thus, to get -@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key, -which is rare these days). -This works both in the Vi command state and in the Insert and Replace -states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the -meta key. - -Note: Emacs binds @kbd{C-\} to a function that offers to change the -keyboard input method in the multilingual environment. Viper overrides this -binding. However, it is still possible to switch the input method by typing -@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. -Or you can use the MULE menu in the menubar. -@end table -@noindent -Other differences are mostly improvements. The ones you should know -about are: - -@table @samp -@item Undo -@kindex @kbd{u} -@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself -can be undone. Another @kbd{u} will change the direction. The presence -of repeatable undo means that @kbd{U}, undoing lines, is not very -important. Therefore, @kbd{U} also calls @code{viper-undo}. -@cindex multiple undo -@cindex undo - - -@item Counts -Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts. - -@comment ]] Just to balance parens -@item Regexps -Viper uses Emacs Regular Expressions for searches. These are a superset of -Vi regular -expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L}, -@dots{}, etc. @xref{Regexps,,Syntax of Regular Expressions,emacs,The -GNU Emacs Manual}, for details. -Files specified to @kbd{:e} use @code{csh} regular expressions -(globbing, wildcards, what have you). -However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /}, -lets the user switch from search with regular expressions to plain vanilla -search and vice versa. It also lets one switch from case-sensitive search -to case-insensitive and back. -@xref{Viper Specials}, for more details. -@cindex regular expressions -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@kindex @kbd{C-c /} - -@item Ex commands -@cindex Ex commands -The current working directory of a buffer is automatically inserted in the -minibuffer if you type @kbd{:e} then space. Absolute filenames are -required less often in Viper. For file names, Emacs uses a convention that -is slightly different from other programs. It is designed to minimize the -need for deleting file names that Emacs provides in its prompts. (This is -usually convenient, but occasionally the prompt may suggest a wrong file -name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the -file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply -continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper} -correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to -@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as -@kbd{/bar/file}, since when it sees @samp{//}, it understands that -@kbd{~/foo/} is to be discarded. - -The command @kbd{:cd} will change the default directory for the -current buffer. The command @kbd{:e} will interpret the -filename argument in @code{csh}. @xref{Customization}, if you -want to change the default shell. -The command @kbd{:next} takes counts from -@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only -the invisible files (i.e., those that are not currently seen in Emacs -windows). - -When applicable, Ex commands support file completion and history. This -means that by typing a partial file name and then @key{TAB}, Emacs will try -to complete the name or it will offer a menu of possible completions. -This works similarly to Tcsh and extends the behavior of Csh. While Emacs -is waiting for a file name, you can type @kbd{M-p} to get the previous file -name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you -browse through the file history. - -Like file names, partially typed Ex commands can be completed by typing -@key{TAB}, and Viper keeps the history of Ex commands. After typing -@kbd{:}, you can browse through the previously entered Ex commands by -typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex -commands on the history list. For instance, if you typed @kbd{:w!@: foo}, -only @kbd{:w!} will be placed on the history list. This is because the -last history element is the default that can be invoked simply by typing -@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to -easy to override valuable data in another file. Reconstructing the full -command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper -has a separate history for file names. By typing @kbd{: M-p}, you will get -@kbd{:w!} in the Minibuffer. Then, repeated @kbd{M-p} will get you through -the file history, inserting one file name after another. - -In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire -command will appear in the history list. This is because having @kbd{:r} -alone as a default is meaningless, since this command requires a file -argument. -@refill -@end table -@noindent -As Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. -However, in addition, Viper keeps track of the history of such commands. This -history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. -Having found the appropriate command, it can be then executed by typing -`@kbd{.}'. -@xref{Improvements over Vi}, for more information. - -@node Insert State, Replace State, Vi State, States in Viper -@subsection Insert State - -@cindex Insert state - -To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the -standard Vi keys available in Insert state. The implication is that -Emacs major modes cannot be used in Insert state. -It is strongly recommended that as soon as you are comfortable, make the -Emacs state bindings visible (by changing your user level to 3 or higher). -@xref{Customization}, -to see how to do this.@refill - -Once this is done, it is possible to do quite a bit of editing in -Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, -which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be -used in Insert state of Viper. Emacs also has a kill ring where it keeps -pieces of text you deleted while editing buffers. The command @kbd{M-y} is -used to delete the text previously put back by Emacs' @kbd{C-y} or by Vi's -@kbd{p} command and reinsert text that was placed on the kill-ring earlier. - -This works both in Vi and Insert states. -In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way -of recovering the 10 previously deleted chunks of text. In Insert state, -you can -use this as follows. Suppose you deleted a piece of text and now you need -to re-insert it while editing in Insert mode. The key @kbd{C-y} will put -back the most recently deleted chunk. If this is not what you want, type -@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want. - -Finally, in Insert and Replace states, Viper provides the history of -pieces of text inserted in previous insert or replace commands. These -strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or -@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled -in the minibuffer: the above keys are usually bound to other histories, -which are more appropriate in the minibuffer.) - - -@cindex Meta key - -You can call Meta functions from Insert state. As in Vi state, the Meta key -is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}. - -Other Emacs commands that are useful in Insert state are @kbd{C-e} -and @kbd{C-a}, which move the cursor to the end and the beginning of the -current line, respectively. You can also use @kbd{M-f} and @kbd{M-b}, -which move the cursor forward (or backward) one word. -If your display has a Meta key, these functions are invoked by holding the -Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays -without the Meta key, these functions are invoked by typing -@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert -state, as explained above). - -The key @kbd{C-z} is sometimes also useful in Insert state: it allows you -to execute a single command in Vi state without leaving the Insert state! -For instance, @kbd{C-z d2w} will delete the next two words without leaving -the Insert state. - -When Viper is in Insert state, you will see in the mode line. - -@node Replace State,, Insert State, States in Viper -@subsection Replace State - -@cindex Replace state - -This state is entered through Vi replacement commands, such as @kbd{C}, -@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts in -the mode line to let you know which state is in effect. If Replace state is -entered through @kbd{R}, Viper stays in that state until the user hits -@key{ESC}. If this state is entered via the other replacement commands, -then Replace state is in effect until you hit @key{ESC} or until you cross -the rightmost boundary of the replacement region. In the latter case, Viper -changes its state from Replace to Insert (which you will notice by the -change in the mode line). - -Since Viper runs under Emacs, it is possible to switch between buffers -while in Replace state. You can also move the cursor using the arrow keys -(even on dumb terminals!)@: and the mouse. Because of this freedom (which is -unattainable in regular Vi), it is possible to take the cursor outside the -replacement region. (This may be necessary for several reasons, including -the need to enable text selection and region-setting with the mouse.) - -The issue then arises as to what to do when the user -hits the @key{ESC} key. In Vi, this would cause the text between cursor and -the end of the replacement region to be deleted. But what if, as is -possible in Viper, the cursor is not inside the replacement region? - -To solve the problem, Viper keeps track of the last cursor position while it -was still inside the replacement region. So, in the above situation, Viper -would delete text between this position and the end of the replacement -region. - -@node The Minibuffer,Multiple Files in Viper, States in Viper, Overview -@section The Minibuffer - -@cindex Minibuffer - -The Minibuffer is where commands are entered in. Editing can be done -by commands from Insert state, namely: - -@table @kbd -@item C-h -Backspace -@item C-w -Delete Word -@item C-u -Erase line -@item C-v -Quote the following character -@item @key{RET} -Execute command -@item C-g and C-] -Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an -explanation. -@item M-p and M-n -These keys are bound to functions that peruse minibuffer history. The -precise history to be perused depends on the context. It may be the history -of search strings, Ex commands, file names, etc. -@end table - -Most of the Emacs keys are functional in the Minibuffer. While in the -Minibuffer, Viper tries to make editing resemble Vi's behavior when the -latter is waiting for the user to type an Ex command. In particular, you -can use the regular Vi commands to edit the Minibuffer. You can switch -between the Vi state and Insert state at will, and even use the replace mode. -Initially, the Minibuffer comes up in Insert state. - -Some users prefer plain Emacs bindings in the Minibuffer. To this end, set -@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}. -@xref{Customization}, to learn how to do this. - -When the Minibuffer changes Viper states, you will notice that the appearance -of the text there changes as well. This is useful because the Minibuffer -has no mode line to tell which Vi state it is in. -The appearance of the text in the Minibuffer can be changed. -@xref{Viper Specials}, for more details. - -@node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview -@section Multiple Files in Viper - -@cindex multiple files -@cindex managing multiple files - -Viper can edit multiple files. This means, for example that you never need -to suffer through @code{No write since last change} errors. -Some Viper elements are common over all the files. - -@table @samp -@item Textmarkers -@cindex markers -@cindex textmarkers -Textmarkers remember @emph{files and positions}. -If you set marker @samp{a} in -file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then -@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a -textmarker using the Viper command @kbd{[} where are the -textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill -@item Repeated Commands -Command repetitions are common over files. Typing @kbd{!!} will repeat the -last @kbd{!} command whichever file it was issued from. -Typing @kbd{.} will repeat the last command from any file, and -searches will repeat the last search. Ex commands can be repeated by typing -@kbd{: @key{RET}}.@refill -Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. -However, usually its effect can be undone by typing @kbd{u}. -@item Registers -@cindex registers -Registers are common to files. Also, text yanked with @kbd{y} can be -put back (@kbd{p}) into any file. The Viper command @kbd{]}, where are -the registers, can be used to look at the contents of a register, e.g., -type @kbd{]a} to view register @samp{a}. - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. -@item Absolute Filenames -@cindex absolute file names -The current directory name for a file is automatically prepended to the -file name in any -@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a -current directory). -This directory is inserted in the Minibuffer once you type space after -@kbd{:e, r}, etc. Viper also supports completion of file names and Ex -commands (@key{TAB}), and it keeps track of -command and file history (@kbd{M-p}, @kbd{M-n}). -Absolute filenames are required less -often in Viper. - -You should be aware that Emacs interprets @kbd{/foo/bar//bla} as -@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to -minimize the need for erasing file names that Emacs suggests in its -prompts, if a suggested file name is not what you wanted. - -The command @kbd{:cd} will change the default directory for the -current Emacs buffer. The Ex command @kbd{:e} will interpret the -filename argument in @samp{csh}, by default. @xref{Customization}, if you -want to change this. -@end table - -@noindent -Currently undisplayed files can be listed using the @kbd{:ar} command. The -command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to -other files. For example, use `:n3' to move to the third file in that list. - -@node Unimplemented Features,,Multiple Files in Viper,Overview -@section Unimplemented Features - -Unimplemented features include: - -@itemize @bullet -@item -@kbd{:ab} and @kbd{:una} are not implemented, since -@kbd{:ab} is considered obsolete, since Emacs has much -more powerful facilities for defining abbreviations. -@item -@kbd{:set option?} is not implemented. The current -@kbd{:set} can also be used to set Emacs variables. -@item -@kbd{:se list} requires modification of the display code for Emacs, so -it is not implemented. -A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot -be used directly inside Emacs, since Emacs will obdurately change @samp{^I} -back to normal tabs.@refill -@end itemize - -@comment node-name, next, previous, up -@node Improvements over Vi, Customization, Overview, Top -@chapter Improvements over Vi - -Some common problems with Vi and Ex have been solved in Viper. This -includes better implementation of existing commands, new commands, and -the facilities provided by Emacs. - -@menu -* Basics:: Basic Viper differences, Multi-file effects. -* Undo and Backups:: Multiple undo, auto-save, backups and changes -* History:: History for Ex and Vi commands. -* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution. -* Completion:: Filename and Command Completion for Ex. -* Improved Search:: Incremental Search and Buffer Content Search. -* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs. -* Movement and Markers:: Screen Editor movements, viewing textmarkers. -* New Commands:: Commands that do not exist in Vi. -* Useful Packages:: A Sampling of some Emacs packages, and things - you should know about. -@end menu - -@node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi -@section Basics - -The Vi command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation - -@cindex region -@cindex region specification -@cindex expanding (region) -@cindex describing regions -@cindex movement commands - -@noindent -If a point command is given as an argument to a modifying command, the -region determined by the point command will be affected by the modifying -command. On the other hand, if a line command is given as an argument to a -modifying command, the region determined by the line command will be -enlarged so that it will become the smallest region properly containing the -region and consisting of whole lines (we call this process @dfn{expanding -the region}), and then the enlarged region will be affected by the modifying -command. -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. -Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or -@kbd{!'afmt} to format a region from @samp{point} to textmarker -@samp{a}. - -@cindex r and R region specifiers - -Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a -special marker called @dfn{mark}. The text-area between the current cursor -position @dfn{point} and the @dfn{mark} is called the @dfn{region}. -@samp{r} specifies the raw region and @samp{R} is the expanded region -(i.e., the minimal contiguous chunk of full lines that contains the raw -region). -@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc. -@kbd{r,R} are not motion commands, however. The special mark is set by -@kbd{m.} and other commands. @xref{Marking}, for more info. - -Viper also adds counts to most commands for which it would make sense. - -In the Overview chapter, some Multiple File issues were discussed -(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has -buffers. These can be seen in the @kbd{:args} list and switched using -@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or -specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper} -file. @xref{Customization}, for details. - -@node Undo and Backups, History, Basics, Improvements over Vi -@section Undo and Backups - -@cindex undo - -Viper provides multiple undo. The number of undo's and the size is limited -by the machine. The Viper command @kbd{u} does an undo. Undo can be -repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo, -and further -@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the -direction. - -@cindex backup files -@cindex auto save - -Since the undo size is limited, Viper can create backup files and -auto-save files. It will normally do this automatically. It is possible -to have numbered backups, etc. For details, @pxref{Backup,,Backup and -Auto-Save,emacs,The GNU Emacs Manual} @refill - -@comment [ balance parens -@cindex viewing registers and markers -@cindex registers -@cindex markers -@cindex textmarkers - -The results of the 9 previous changes are available in the 9 numeric -registers, as in Vi. The extra goody is the ability to @emph{view} these -registers, in addition to being able to access them through @kbd{p} and -@kbd{M-y} (@xref{Insert State}, for details.) -The Viper command @kbd{] register} will display the contents of any -register, numeric or alphabetical. The related command @kbd{[ textmarker} -will show the text around the textmarker. @samp{register} and @samp{textmarker} -can be any letters from a through z. -@comment ] balance parens - -@node History, Macros and Registers, Undo and Backups,Improvements over Vi -@section History - -@cindex history -@cindex Minibuffer - -History is provided for Ex commands, Vi searches, file names, pieces of -text inserted in earlier commands that use Insert or Replace state, and for -destructive commands in Vi state. These are -useful for fixing those small typos that screw up searches and @kbd{:s}, -and for eliminating routine associated with repeated typing of file names -or pieces of text that need to be inserted frequently. -At the @kbd{:} or @kbd{/} prompts in the Minibuffer, you can do the following: - -@table @kbd -@item M-p and M-n -To move to previous and next history items. This causes the history -items to appear on the command line, where you can edit them, or -simply type Return to execute. -@item M-r and M-s -To search backward and forward through the history. -@item @key{RET} -Type @key{RET} to accept a default (which is displayed in the prompt). -@end table - -The history of insertions can be perused by -typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state. -The history of destructive Vi commands can be perused via the same keys -when Viper is in Vi state. @xref{Viper Specials}, for details. - -All Ex commands have a file history. For instance, typing @kbd{:e}, space -and then @kbd{M-p} will bring up the name of the previously typed file -name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse -through the file history. - -Similarly, commands that have to do with switching buffers -have a buffer history, and commands that expect strings or regular -expressions keep a history on those items. - -@node Macros and Registers,Completion,History,Improvements over Vi -@section Macros and Registers - -@cindex keyboard macros -@cindex macros -@cindex registers -@cindex register execution - -Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will -start a macro definition. As you type, the commands will be executed, and -remembered (This is called ``learn mode'' in some editors.) -@kbd{@@register} will complete the macro, putting it into @samp{register}, -where @samp{register} is any character from @samp{a} through @samp{z}. Then -you can execute this macro using @kbd{@@register}. It is, of course, -possible to yank some text into a register and execute it using -@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will -execute the last macro that was executed using @kbd{@@register}.@refill - -Viper will automatically lowercase the register, so that pressing the -@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for -@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y}, -@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it -is an error to use a Uppercase register name. - -@comment [ balance parens -@cindex viewing registers and markers - -The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker} -will show the contents of a textmarker). -@comment ] balance parens - -@cindex last keyboard macro - -The last keyboard macro can also be executed using -@kbd{*}, and it can be yanked into a register using @kbd{@@!register}. -This is useful for Emacs style keyboard macros defined using @kbd{C-x(} -and @kbd{C-x)}. Emacs keyboard macros have more capabilities. -@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for -details.@refill - -Keyboard Macros allow an interesting form of Query-Replace: -@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a -Keyboard Macro execution @kbd{@@@@} (the replace). - -Viper also provides Vi-style macros. @xref{Vi Macros}, for details. - - -@node Completion, Improved Search, Macros and Registers, Improvements over Vi -@section Completion - -@cindex completion - -Completion is done when you type @key{TAB}. The Emacs completer does not -grok wildcards in file names. Once you type a wildcard, the completer will -no longer work for that file name. Remember that Emacs interprets a file name -of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as -@kbd{~/bar}. - -@node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi -@section Improved Search - -@cindex buffer search -@cindex word search - -Viper provides buffer search, the ability to search the buffer for a region -under the cursor. You have to turn this on in @file{.viper} either by calling - -@example -(viper-buffer-search-enable) -@end example - -@noindent -or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}: -@example -(setq viper-buffer-search-char ?g) -@end example - -@noindent -If the user calls @code{viper-buffer-search-enable} explicitly (the first -method), then @code{viper-buffer-search-char} will be set to @kbd{g}. -Regardless of how this feature is enabled, the key -@code{viper-buffer-search-char} will take movement commands, like -@kbd{w,/,e}, to find a region and then search for the contents of that -region. This command is very useful for searching for variable names, etc., -in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}. - -@cindex incremental search - -Emacs provides incremental search. As you type the string in, the -cursor will move to the next match. You can snarf words from the buffer -as you go along. Incremental Search is normally bound to @kbd{C-s} and -@kbd{C-r}. @xref{Customization}, to find out how to change the bindings -of @kbd{C-r or C-s}. -For details, @pxref{Incremental Search,,Incremental -Search,emacs,The GNU Emacs Manual} @refill - -@cindex query replace - -Viper also provides a query replace function that prompts through the -Minibuffer. It is invoked by the @kbd{Q} key in Vi state. - -@cindex mouse search - -On a window display, Viper supports mouse search, i.e., you can search for a -word by clicking on it. @xref{Viper Specials}, for details. - -Finally, on a window display, Viper highlights search patterns as it finds -them. This is done through what is known as @emph{faces} in Emacs. The -variable that controls how search patterns are highlighted is -@code{viper-search-face}. If you don't want any highlighting at all, put -@example -(copy-face 'default 'viper-search-face) -@end example -@vindex @code{viper-search-face} -@noindent -in @file{~/.viper}. If you want to change how patterns are highlighted, you -will have to change @code{viper-search-face} to your liking. The easiest -way to do this is to use Emacs customization widget, which is accessible -from the menubar. Viper customization group is located under the -@emph{Emulations} customization group, which in turn is under the -@emph{Editing} group (or simply by typing @kbd{:customize}). All Viper -faces are grouped together under Viper's -@emph{Highlighting} group. - -Try it: it is really simple! - -@node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi -@section Abbreviation Facilities - -@cindex abbrevs - -It is possible in Emacs to define abbrevs based on the contents of the -buffer. -Sophisticated templates can be defined using the Emacs abbreviation -facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for -details. - -@cindex dynamic abbrevs - -Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs -will search the buffer to find an extension for this word. For instance, -one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke -that completed the @samp{A} to @samp{Abbreviations}. Repeated typing -will search further back in the buffer, so that one could get -@samp{Abbrevs} by repeating the -keystroke, which appears earlier in the text. Emacs binds this to -@kbd{@key{ESC} /}, so you will have to find a key and bind the function -@code{dabbrev-expand} to that key. -Facilities like this make Vi's @kbd{:ab} command obsolete. - -@node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi -@section Movement and Markers - -@cindex Ex style motion -@cindex line editor motion - -Viper can be set free from the line--limited movements in Vi, such as @kbd{l} -refusing to move beyond the line, @key{ESC} moving one character back, -etc. These derive from Ex, which is a line editor. If your @file{.viper} -contains - -@example -@code{(setq viper-ex-style-motion nil)} -@end example - -@noindent -the motion will be a true screen editor motion. One thing you must then -watch out for is that it is possible to be on the end-of-line character. -The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they -were on the last character. - -@vindex @code{viper-syntax-preference} -@cindex syntax table - -The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated -deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to -understand Emacs syntax tables. If the variable -@code{viper-syntax-preference} is set to @code{strict-vi} then -the meaning of @emph{word} is the same as in -Vi. However, if the value is @code{reformed-vi} (the default) then the -alphanumeric symbols will be those specified by the current Emacs syntax -table (which may be different for different major modes) plus the -underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc. -Both @code{strict-vi} and @code{reformed-vi} work close to Vi in -traditional cases, but @code{reformed-vi} does a better job when editing -text in non-Latin alphabets. - -The user can also specify the value @code{emacs}, which would -make Viper use exactly the Emacs notion of word. In particular, the -underscore may not be part of a word. Finally, if -@code{viper-syntax-preference} is set to @code{extended}, Viper words would -consist of characters that are classified as alphanumeric @emph{or} as -parts of symbols. This is convenient for writing programs and in many other -situations. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. - -Changes to @code{viper-syntax-preference} should be done in the hooks to -various major modes by executing @code{viper-set-syntax-preference} as in -the following example: - -@example -(viper-set-syntax-preference nil "emacs") -@end example - -@findex @code{viper-set-syntax-preference} - -The above discussion of the meaning of Viper's words concerns only Viper's -movement commands. In regular expressions, words remain the same as in -Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use -Emacs' idea of what is a word, and they don't look into the value of -variable @code{viper-syntax-preference}. This is because Viper doesn't change -syntax tables in fear of upsetting the various major modes that set these -tables. - -@cindex textmarkers - -Textmarkers in Viper remember the file and the position, so that you can -switch files by simply doing @kbd{'a}. If you set up a regimen for using -Textmarkers, this is very useful. Contents of textmarkers can be viewed -by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}). - -@node New Commands, Useful Packages, Movement and Markers, Improvements over Vi -@section New Commands - -These commands have no Vi analogs. - -@table @kbd -@item C-x, C-c -@kindex @kbd{C-x} -@kindex @kbd{C-c} -These two keys invoke many important Emacs functions. For example, if you -hit @kbd{C-x} followed by @kbd{2}, then the current window will be split -into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs -command from the current major mode. @key{ESC} will do the same, if you -configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to @code{nil} -in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi -states will make Emacs think @kbd{Meta} has been hit.@refill -@item \ -@kindex @kbd{\} -Escape to Emacs to execute a single Emacs command. For instance, -@kbd{\ @key{ESC}} will act like a Meta key. -@item Q -@kindex @kbd{Q} -@cindex query replace -@kbd{Q} is for query replace. By default, -each string to be replaced is treated as a regular expression. You can use -@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to -turn this off. (For normal searches, @kbd{:se nomagic} will work. Note -that @kbd{:se nomagic} turns Regexps off completely, unlike Vi). -@item v -@itemx V -@itemx C-v -@kindex @kbd{v} -@kindex @kbd{V} -@kindex @kbd{C-v} -These keys are used to visit files. @kbd{v} will switch to a buffer -visiting file whose name can be entered in the Minibuffer. @kbd{V} is -similar, but will use a window different from the current window. -@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used -instead of a new Emacs window. -@item # -@kindex @kbd{#} -If followed by a certain character @var{ch}, it becomes an operator whose -argument is the region determined by the motion command that follows -(indicated as ). -Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and -@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then -prepend this string to each line in the buffer.@refill -@item # c -@kindex @kbd{#c} -@cindex changing case -Change upper-case characters in the region to lower-case -(@code{downcase-region}). -Emacs command @kbd{M-l} does the same for words. -@item # C -@kindex @kbd{#C} -Change lower-case characters in the region to upper-case. For instance, -@kbd{# C 3 w} will capitalize 3 words from the current point -(@code{upcase-region}). -Emacs command @kbd{M-u} does the same for words. -@item # g -@kindex @kbd{#g} -Execute last keyboard macro for each line in the region -(@code{viper-global-execute}).@refill -@item # q -@kindex @kbd{#q} -Insert specified string at the beginning of each line in the region -(@code{viper-quote-region}). The default string is composed of the comment -character(s) appropriate for the current major mode. -@item # s -@kindex @kbd{#s} -Check spelling of words in the region (@code{spell-region}). -The function used for spelling is determined from the variable -@code{viper-spell-function}. -@vindex @code{viper-spell-function} -@item * -@kindex @kbd{*} -Call last keyboard macro. -@item m . -Set mark at point and push old mark off the ring -@item m< -@item m> -Set mark at beginning and end of buffer, respectively. -@item m, -Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU -Emacs Manual}, for more info. -@item ] register -@kindex @kbd{]} -View contents of register -@item [ textmarker -@kindex @kbd{[} -View filename and position of textmarker -@item @@# -@item @@register -@item @@! -@kindex @kbd{@@#} -@kindex @kbd{@@} -@kindex @kbd{@@!} -@cindex keyboard macros -@cindex register execution - -Begin/end keyboard macro. @@register has a different meaning when used after -a @kbd{@@#}. @xref{Macros and Registers}, for details -@item [] -@kindex @kbd{[]} -Go to end of heading. -@item g <@emph{movement command}> -Search buffer for text delimited by movement command. The canonical -example is @kbd{gw} to search for the word under the cursor. -@xref{Improved Search}, for details.@refill -@item C-g and C-] -@kindex @kbd{C-g} -@kindex @kbd{C-]} -Quit and Abort Recursive edit. These may be necessary on occasion. -@xref{Vi State}, for a reason. -@item C-c C-g -@kindex @kbd{C-c C-g} -Hitting @kbd{C-c} followed by @kbd{C-g} will display the information on the -current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as -explained above, @kbd{C-g} is needed for other purposes in Emacs. -@item C-c / -@kindex @kbd{C-c /} -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search - -@item M-p and M-n -@kindex @kbd{M-p} -@kindex @kbd{M-n} -In the Minibuffer, these commands navigate through the minibuffer -histories, such as the history of search strings, Ex commands, etc. - -@item C-c M-p and C-c M-n -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@cindex Insertion history -@cindex Insertion ring -@cindex Command history -@cindex Command ring - -In Insert or Replace state, these commands let the user -peruse the history of insertion strings used in previous insert or replace -commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what -happens. @xref{Viper Specials}, for more. - -In Vi state, these commands let the user peruse the history of Vi-style -destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. -By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper -through the recent history of Vi commands, displaying the commands one by -one. Once -an appropriate command is found, it can be executed by typing `@kbd{.}'. - -Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an -appropriate function to a function key on the keyboard and use that key. -@xref{Viper Specials}, for details. - -@item Ex commands -@findex @kbd{:args} -@findex @kbd{:n} -@findex @kbd{:pwd} -@findex @kbd{:pre} -The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave -differently. @kbd{:pwd} exists to get current directory. -The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and -Buffer Handling}, for details. -There are also the new commands @kbd{:RelatedFile} and -@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, -respectively. @xref{Viper Specials}, for details. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} -@end table - -Apart from the new commands, many old commands have been enhanced. Most -notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi -Macros}, for details. - -@node Useful Packages, ,New Commands, Improvements over Vi -@section Useful Packages - -Some Emacs packages are mentioned here as an aid to the new Viper user, to -indicate what Viper is capable of. -A vast number comes with the standard Emacs distribution, and many more exist -on the net and on the archives. - -This manual also mentions some Emacs features a new user -should know about. The details of these are found in the GNU Emacs -Manual. - -The features first. For details, look up the Emacs Manual. - -@table @samp -@item Make -@cindex make -@cindex compiling - -Makes and Compiles can be done from the editor. Error messages will be -parsed and you can move to the error lines. -@item Shell -@cindex shell -@cindex interactive shell -You can talk to Shells from inside the editor. Your entire shell session -can be treated as a file. -@item Mail -@cindex email -@cindex mail -Mail can be read from and sent within the editor. Several sophisticated -packages exist. -@item Language Sensitive Editing -Editing modes are written for most computer languages in existence. By -controlling indentation, they catch punctuation errors. -@end table - -The packages, below, represents a drop in the sea of special-purpose -packages that come with standard distribution of Emacs. - -@table @samp -@item Transparent FTP -@cindex transparent ftp -@pindex ange-ftp.el -@code{ange-ftp.el} can ftp from the editor to files on other machines -transparent to the user. -@item RCS Interfaces -@cindex version maintenance -@cindex RCS -@pindex vc.el -@code{vc.el} for doing RCS commands from inside the editor -@item Directory Editor -@cindex dired -@pindex dired.el -@code{dired.el} for editing contents of directories and for navigating in -the file system. -@item Syntactic Highlighting -@cindex font-lock -@pindex font-lock.el -@code{font-lock.el} for automatic highlighting various parts of a buffer -using different fonts and colors. -@item Saving Emacs Configuration -@cindex desktop -@pindex desktop.el -@code{desktop.el} for saving/restoring configuration on Emacs exit/startup. -@item Spell Checker -@cindex ispell -@pindex ispell.el -@code{ispell.el} for spell checking the buffer, words, regions, etc. -@item File and Buffer Comparison -@cindex ediff -@pindex ediff.el -@code{ediff.el} for finding differences between files and for applying -patches. -@end table - -@noindent -Emacs Lisp archives exist on -@samp{archive.cis.ohio-state.edu} -and @samp{wuarchive.wustl.edu}@refill - - -@node Customization,Commands,Improvements over Vi,Top -@chapter Customization - -@cindex customization - -Customization can be done in 2 ways. - -@itemize @bullet -@item -@cindex initialization -@cindex .viper -Elisp code in a @file{.viper} file in your home directory. Viper -loads @file{.viper} just before it does the binding for mode -hooks. This is recommended for experts only. -@item -@cindex .emacs -Elisp code in your @file{.emacs} file before and after the @code{(require -'viper)} line. This method is @emph{not} recommended, unless you know what -you are doing. Only two variables, @code{viper-mode} and -@code{viper-custom-file-name}, are supposed to be customized in @file{.emacs}, -prior to loading Viper (i.e., prior to @code{(require 'viper)} command.@refill -@item -@cindex :customize -By executing the @kbd{:customize} Ex command. This takes you to the Emacs -customization widget, which lets you change the values of Viper -customizable variables easily. This method is good for novice and -experts alike. The customization code in the form of Lisp commands will be -placed in @file{~/.emacs} or some other customization file depending on the -version of Emacs that you use. Still, it is recommended to separate -Viper-related customization produced by the Emacs customization widget -and keep it in the @file{.viper} file. - -Some advanced customization cannot be accomplished this way, however, and -has to be done in Emacs Lisp in the @file{.viper} file. For the common -cases, examples are provided that you can use directly. -@end itemize - - -@menu -* Rudimentary Changes:: Simple constant definitions. -* Key Bindings:: Enabling Emacs Keys, Rebinding keys, etc. -* Packages that Change Keymaps:: How to deal with such beasts. -* Viper Specials:: Special Viper commands. -* Vi Macros:: How to do Vi style macros. -@end menu - -@node Rudimentary Changes,Key Bindings,Customization,Customization -@section Rudimentary Changes - -@cindex setting variables -@cindex variables for customization -@findex @kbd{:set} - -An easy way to customize Viper is to change the values of constants used in -Viper. Here is the list of the constants used in Viper and their default -values. The corresponding :se command is also indicated. (The symbols -@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp). - -Viper supports both the abbreviated Vi variable names and their full -names. Variable completion is done on full names only. @key{TAB} and -@key{SPC} complete -variable names. Typing `=' will complete the name and then will prompt for -a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the -command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command -and prompt further like this: @kbd{:set tabstop = }. -However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message -because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports -completion on full names only. However, you can still hit @key{RET} -or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and -Viper will be waiting for you to type a value for the tabstop variable. -To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}. - -@table @code -@item viper-auto-indent nil -@itemx :se ai (:se autoindent) -@itemx :se ai-g (:se autoindent-global) -If @code{t}, enable auto indentation. -by @key{RET}, @kbd{o} or @kbd{O} command. - -@code{viper-auto-indent} is a local variable. To change the value globally, use -@code{setq-default}. It may be useful for certain major modes to have their -own values of @code{viper-auto-indent}. This can be achieved by using -@code{setq} to change the local value of this variable in the hooks to the -appropriate major modes. - -@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current -buffer only; @kbd{:se ai-g} does the same globally. -@item viper-electric-mode t -If not @code{nil}, auto-indentation becomes electric, which means that -@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current -major mode. In the future, this variable may control additional electric -features. - -This is a local variable: @code{setq} changes the value of this variable -in the current buffer only. Use @code{setq-default} to change the value in -all buffers. -@item viper-case-fold-search nil -@itemx :se ic (:se ignorecase) -If not @code{nil}, search ignores cases. -This can also be toggled by quickly hitting @kbd{/} twice. -@item viper-re-search nil -@itemx :se magic -If not @code{nil}, search will use regular expressions; if @code{nil} then -use vanilla search. -This behavior can also be toggled by quickly hitting @kbd{/} trice. -@item buffer-read-only -@itemx :se ro (:se readonly) -Set current buffer to read only. To change globally put -@code{(setq-default buffer-read-only t)} in your @file{.emacs} file. -@item blink-matching-paren t -@itemx :se sm (:se showmatch) -Show matching parens by blinking cursor. -@item tab-width t (default setting via @code{setq-default}) -@itemx :se ts=value (:se tabstop=value) -@itemx :se ts-g=value (:se tabstop-global=value) -@code{tab-width} is a local variable that controls the width of the tab stops. -To change the value globally, use @code{setq-default}; for local settings, -use @code{setq}. - -The command @kbd{:se ts} -sets the tab width in the current -buffer only; it has no effect on other buffers. - -The command @kbd{:se ts-g} sets tab width globally, -for all buffers where the tab is not yet set locally, -including the new buffers. - -Note that typing @key{TAB} normally -doesn't insert the tab, since this key is usually bound to -a text-formatting function, @code{indent-for-tab-command} (which facilitates -programming and document writing). Instead, the tab is inserted via the -command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab). - -On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so -@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have -to bind @code{viper-insert-tab} to some other convenient key. - -@item viper-shift-width 8 -@itemx :se sw=value (:se shiftwidth=value) -The number of columns shifted by @kbd{>} and @kbd{<} commands. -@item viper-search-wrap-around t -@itemx :se ws (:se wrapscan) -If not @code{nil}, search wraps around the end/beginning of buffer. -@item viper-search-scroll-threshold 2 -If search lands within this many lines of the window top or bottom, the -window will be scrolled up or down by about 1/7-th of its size, to reveal -the context. If the value is negative---don't scroll. -@item viper-tags-file-name "TAGS" -The name of the file used as the tag table. -@item viper-re-query-replace nil -If not @code{nil}, use reg-exp replace in query replace. -@item viper-want-ctl-h-help nil -If not @code{nil}, @kbd{C-h} is bound to @code{help-command}; -otherwise, @kbd{C-h} is bound as usual in Vi. -@item viper-vi-style-in-minibuffer t -If not @code{nil}, Viper provides a high degree of compatibility with Vi -insert mode when you type text in the Minibuffer; if @code{nil}, typing in -the Minibuffer feels like plain Emacs. -@item viper-no-multiple-ESC t -If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state. -Normally, this is not necessary, since graphical displays have separate -Meta keys (usually on each side of the space bar). On a dumb terminal, Viper -sets this variable to @code{twice}, which is almost like @code{nil}, except -that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta. -@item viper-fast-keyseq-timeout 200 -Key sequences separated by this many milliseconds are treated as Vi-style -keyboard macros. If the key sequence is defined as such a macro, it will be -executed. Otherwise, it is processed as an ordinary sequence of typed keys. - -Setting this variable too high may slow down your typing. Setting it too -low may make it hard to type macros quickly enough. -@item viper-ex-style-motion t -Set this to @code{nil}, if you want @kbd{l,h} to cross -lines, etc. @xref{Movement and Markers}, for more info. -@item viper-ex-style-editing t -Set this to @code{nil}, if you want -@kbd{C-h} and @key{DEL} to not stop -at the beginning of a line in Insert state, @key{X} and @key{x} to delete -characters across lines in Vi command state, etc. -@item viper-ESC-moves-cursor-back t -It @code{t}, cursor moves back 1 character when switching from insert state to vi -state. If @code{nil}, the cursor stays where it was before the switch. -@item viper-always t -@code{t} means: leave it to Viper to decide when a buffer must be brought -up in Vi state, -Insert state, or Emacs state. This heuristics works well in virtually all -cases. @code{nil} means you either has to invoke @code{viper-mode} manually -for each buffer (or you can add @code{viper-mode} to the appropriate major mode -hooks using @code{viper-load-hook}). - -This option must be set in the file @file{~/.viper}. -@item viper-custom-file-name "~/.viper" -File used for Viper-specific customization. -Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!) -before Viper is loaded. Note that you -have to set it as a string inside double quotes. -@item viper-spell-function 'ispell-region -Function used by the command @kbd{#c} to spell. -@item viper-glob-function -The value of this variable is the function symbol used to expand wildcard -symbols. This is platform-dependent. The default tries to set this variable -to work with most shells, MS Windows, OS/2, etc. However, if it -doesn't work the way you expect, you should write your own. -Use @code{viper-glob-unix-files} and @code{viper-glob-mswindows-files} in -@file{viper-util.el} as examples. - -This feature is used to expand wildcards in the Ex command @kbd{:e}. -Note that Viper doesn't support wildcards in the @kbd{:r} and @kbd{:w} -commands, because file completion is a better mechanism. -@findex @code{viper-glob-function} - -@item ex-cycle-other-window t -If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another -window, if one exists. -@item ex-cycle-through-non-files nil -@kbd{:n} does not normally cycle through buffers. Set this to get -buffers also. -@item viper-want-emacs-keys-in-insert -This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user -levels 3 and 4. Users who specify level 5 are allowed to set this variable -as they please (the default for this level is @code{t}). If set to -@code{nil}, complete Vi compatibility is provided in Insert state. This is -really not recommended, as this precludes you from using language-specific -features provided by the major modes. -@item viper-want-emacs-keys-in-vi -This is set to @code{nil} for user -level 1 and to @code{t} for user levels 2--4. -At level 5, users are allowed to set this variable as they please (the -default for this level is @code{t}). -If set to @code{nil}, complete Vi compatibility is provided -in Vi command state. Setting this to @code{nil} is really a bad idea, -unless you are a novice, as this precludes the use -of language-specific features provided by the major modes. -@item viper-keep-point-on-repeat t -If not @code{nil}, point is not moved when the user repeats the previous -command by typing `.' This is very useful for doing repeated changes with -the @kbd{.} key. -@item viper-repeat-from-history-key 'f12 -Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat -the second-last and the third-last destructive command. -Both these macros are bound (as Viper macros) to -@code{viper-repeat-from-history}, -which checks the second key by which it is invoked to see which of the -previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, -but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do -this. -@item viper-keep-point-on-undo nil -If not @code{nil}, Viper tries to not move point when undoing commands. -Instead, it will briefly move the cursor to the place where change has -taken place. However, if the undone piece of text is not seen in window, -then point will be moved to the place where the change took place. -Set it to @code{t} and see if you like it better. -@item viper-delete-backwards-in-replace nil -If not @code{nil}, @key{DEL} key will delete characters while moving the cursor -backwards. If @code{nil}, the cursor will move backwards without deleting -anything. -@item viper-replace-overlay-face 'viper-replace-overlay-face -On a graphical display, Viper highlights replacement regions instead of -putting a @samp{$} at the end. This variable controls the so called -@dfn{face} used to highlight the region. - -By default, @code{viper-replace-overlay-face} underlines the replacement on -monochrome displays and also lays a stipple over them. On color displays, -replacement regions are highlighted with color. - -If you know something about Emacs faces and don't like how Viper highlights -replacement regions, you can change @code{viper-replace-overlay-face} by -specifying a new face. (Emacs faces are described in the Emacs Lisp -reference.) On a color display, the following customization method is -usually most effective: -@example -(set-face-foreground viper-replace-overlay-face "DarkSlateBlue") -(set-face-background viper-replace-overlay-face "yellow") -@end example -For a complete list of colors available to you, evaluate the expression -@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then -hit the @kbd{C-j} key. - -@item viper-replace-overlay-cursor-color "Red" -@vindex @code{viper-replace-overlay-cursor-color} -Cursor color when it is inside the replacement region. -This has effect only on color displays and only when Emacs runs as an X -application. -@item viper-insert-state-cursor-color nil -@vindex @code{viper-insert-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -insert state. -@item viper-emacs-state-cursor-color nil -@vindex @code{viper-emacs-state-cursor-color} -If set to a valid color, this will be the cursor color when Viper is in -emacs state. -@item viper-replace-region-end-delimiter "$" -A string used to mark the end of replacement regions. It is used only on -TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-replace-region-start-delimiter "" -A string used to mark the beginning of replacement regions. It is used -only on TTYs or if @code{viper-use-replace-region-delimiters} is non-@code{nil}. -@item viper-use-replace-region-delimiters -If non-@code{nil}, Viper will always use @code{viper-replace-region-end-delimiter} and -@code{viper-replace-region-start-delimiter} to delimit replacement regions, -even on color displays (where this is unnecessary). By default, this -variable is non-@code{nil} only on TTYs or monochrome displays. -@item viper-allow-multiline-replace-regions t -If non-@code{nil}, multi-line text replacement regions, such as those produced by -commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits -the replacement mode. In this variable is set to @code{nil}, Viper will -emulate the standard Vi behavior, which supports only intra-line -replacement regions (and multi-line replacement regions are deleted). -@item viper-toggle-key "\C-z" -Specifies the key used to switch from Emacs to Vi and back. -Must be set in @file{.viper}. This variable can't be -changed interactively after Viper is loaded. - -In Insert state, this key acts as a temporary escape to Vi state, i.e., it -will set Viper up so that the very next command will be executed as if it -were typed in Vi state. -@item viper-buffer-search-char nil -Key used for buffer search. @xref{Viper Specials}, for details. -@item viper-surrounding-word-function 'viper-surrounding-word -The value of this variable is a function name that is used to determine -what constitutes a word clicked upon by the mouse. This is used by mouse -search and insert. -@item viper-search-face 'viper-search-face -Variable that controls how search patterns are highlighted when they are -found. -@item viper-vi-state-hook nil -List of parameterless functions to be run just after entering the Vi -command state. -@item viper-insert-state-hook nil -Same for Insert state. This hook is also run after entering Replace state. -@item viper-replace-state-hook nil -List of (parameterless) functions called just after entering Replace state -(and after all @code{viper-insert-state-hook}). -@item viper-emacs-state-hook nil -List of (parameterless) functions called just after switching from Vi state -to Emacs state. -@item viper-load-hook nil -List of (parameterless) functions called just after loading Viper. This is -the last chance to do customization before Viper is up and running. -@end table -@noindent -You can reset some of these constants in Viper with the Ex command @kbd{:set} -(when so indicated in the table). Or you -can include a line like this in your @file{.viper} file: -@example -(setq viper-case-fold-search t) -@end example -@vindex @code{viper-auto-indent} -@vindex @code{viper-electric-mode} -@vindex @code{viper-case-fold-search} -@vindex @code{viper-re-search} -@vindex @code{viper-shift-width} -@vindex @code{buffer-read-only} -@vindex @code{viper-search-wrap-around} -@vindex @code{viper-search-scroll-threshold} -@vindex @code{viper-search-face} -@vindex @code{viper-tags-file-name} -@vindex @code{viper-re-query-replace} -@vindex @code{viper-want-ctl-h-help} -@vindex @code{viper-vi-style-in-minibuffer} -@vindex @code{viper-no-multiple-ESC} -@vindex @code{viper-always} -@vindex @code{viper-fast-keyseq-timeout} -@vindex @code{viper-ex-style-motion} -@vindex @code{viper-ex-style-editing} -@vindex @code{viper-ESC-moves-cursor-back} -@vindex @code{viper-custom-file-name} -@vindex @code{viper-spell-function} -@vindex @code{ex-cycle-other-window} -@vindex @code{ex-cycle-through-non-files} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-keep-point-on-repeat} -@vindex @code{viper-keep-point-on-undo} -@vindex @code{viper-delete-backwards-in-replace} -@vindex @code{viper-replace-overlay-face} -@vindex @code{viper-replace-region-end-symbol} -@vindex @code{viper-replace-region-start-symbol} -@vindex @code{viper-allow-multiline-replace-regions} -@vindex @code{viper-toggle-key} -@vindex @code{viper-buffer-search-char} -@vindex @code{viper-surrounding-word-function} -@vindex @code{viper-vi-state-hook} -@vindex @code{viper-insert-state-hook} -@vindex @code{viper-replace-state-hook} -@vindex @code{viper-emacs-state-hook} - -@node Key Bindings, Packages that Change Keymaps, Rudimentary Changes,Customization -@section Key Bindings - -@cindex key bindings -@cindex keymaps - -Viper lets you define hot keys, i.e., you can associate keyboard keys -such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already -exist or that you will write). Each key has a "preferred form" in -Emacs. For instance, the Up key's preferred form is [up], the Help key's -preferred form is [help], and the Undo key has the preferred form [f14]. -You can find out the preferred form of a key by typing @kbd{M-x -describe-key-briefly} and then typing the key you want to know about. - -Under the X Window System, every keyboard key emits its preferred form, -so you can just type - -@lisp -(global-set-key [f11] 'calendar) ; L1, Stop -(global-set-key [f14] 'undo) ; L4, Undo -@end lisp - -@noindent -to bind L1 (a key that exists on some SUN workstations) so it will invoke -the Emacs Calendar and to bind L4 so it will undo changes. -However, on a dumb terminal or in an Xterm window, even the standard arrow -keys may -not emit the right signals for Emacs to understand. To let Emacs know about -those keys, you will have to find out which key sequences they emit -by typing @kbd{C-q} and then the key (you should switch to Emacs state -first). Then you can bind those sequences to their preferred forms using -@code{input-decode-map} as follows: - -@lisp -(cond ((string= (getenv "TERM") "xterm") -(define-key input-decode-map "\e[192z" [f11]) ; L1 -(define-key input-decode-map "\e[195z" [f14]) ; L4, Undo -@end lisp - -The above illustrates how to do this for Xterm. On VT100, you would have to -replace "xterm" with "vt100" and also change the key sequences (the same -key may emit different sequences on different types of terminals). - -The above keys are global, so they are overwritten by the local maps -defined by the major modes and by Viper itself. Therefore, if you wish to -change a binding set by a major mode or by Viper, read this. - -Viper users who wish to specify their own key bindings should be concerned -only with the following three keymaps: -@code{viper-vi-global-user-map} for Vi state commands, -@code{viper-insert-global-user-map} for Insert state commands, -and @code{viper-emacs-global-user-map} for Emacs state commands (note: -customized bindings for Emacs state made to @code{viper-emacs-global-user-map} -are @emph{not} inherited by Insert state). - -For more information on Viper keymaps, see the header of the file -@file{viper.el}. -If you wish to change a Viper binding, you can use the -@code{define-key} command, to modify @code{viper-vi-global-user-map}, -@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as -explained below. Each of these key maps affects the corresponding Viper state. -The keymap @code{viper-insert-global-user-map} also affects Viper's Replace -state. - -@noindent -If you want to -bind a key, say @kbd{C-v}, to the function that scrolls -page down and to make @kbd{0} display information on the current buffer, -putting this in @file{.viper} will do the trick in Vi state: -@example -(define-key viper-vi-global-user-map "\C-v" 'scroll-down) -@end example -@noindent -To set a key globally, -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -(define-key viper-vi-global-user-map "0" 'viper-info-on-file) -@end example -@noindent -Note, however, that this binding may be overwritten by other keymaps, since -the global keymap has the lowest priority. -To make sure that nothing will override a binding in Emacs state, you -can write this: -@example -(define-key viper-emacs-global-user-map "\C-c m" 'smail) -@end example -@noindent -To customize the binding for @kbd{C-h} in Insert state: -@example -(define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function) -@end example -@noindent - -Each Emacs command key calls some Lisp function. If you have enabled the -Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function -for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m} -will provide information on the major mode in effect. If Help is not -enabled, you can still get help in Vi state by prefixing the above commands -with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the -menu bar, if Emacs runs under X). - -Viper users can also change bindings on a per major mode basis. As with -global bindings, this can be done separately for each of the three main Viper -states. To this end, Viper provides the function -@code{viper-modify-major-mode}. -@findex @code{viper-modify-major-mode} - -To modify keys in Emacs state for @code{my-favorite-major-mode}, the user -needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever -keys necessary in that keymap, and put - -@example -(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map) -@end example - -@noindent -in @file{~/.viper}. To do the same in Vi and Insert states, you should use -@code{vi-state} and @code{insert-state}. Changes in Insert state are also -in effect in Replace state. For instance, suppose that the user wants to -use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark -files, etc. The following code in @file{~/.viper} will then do the job: - -@example -(setq my-dired-modifier-map (make-sparse-keymap)) -(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) -(define-key my-dired-modifier-map "u" 'dired-unmark) -(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map) -@end example - -A Vi purist may want to modify Emacs state under Dired mode so that -@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in -Vi. Although this is not recommended, as these keys are bound to useful -Dired functions, the trick can be accomplished via the following code: - -@example -(setq my-dired-vi-purist-map (make-sparse-keymap)) -(define-key my-dired-vi-purist-map "k" 'viper-previous-line) -(define-key my-dired-vi-purist-map "l" 'viper-forward-char) -(viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map) -@end example - -Yet another way to customize key bindings in a major mode is to edit the -list @code{viper-major-mode-modifier-list} using the customization widget. -@vindex @code{viper-major-mode-modifier-list} -(This variable is in the Viper-misc customization group.) -The elements of this list are triples of the form: (major-mode viper-state -keymap), where the keymap contains bindings that are supposed to be active -in the given major mode and the given viper-state. - -Effects similar to key binding changes can be achieved by defining Vi -keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The -difference is that multi-key Vi macros do not override the keys they are -bound to, unless these keys are typed in quick succession. So, with macros, -one can use the normal keys alongside with the macros. If per-mode -modifications are needed, the user can try both ways and see which one is -more convenient. -@findex @kbd{:map} -@xref{Vi Macros}, for details. - -Note: in major modes that come up in @emph{Emacs state} by default, the -aforesaid modifications may not take place immediately (but only after the -buffer switches to some other Viper state and then back to Emacs state). To -avoid this, one should add @code{viper-change-state-to-emacs} to an -appropriate hook of that major mode. (Check the function -@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you -did not set @code{viper-always} to @code{nil}, chances are that you won't -need to perform the above procedure, because Viper will take care of most -useful defaults. - - -Finally, Viper has a facility that lets the user define per-buffer -bindings, i.e., bindings that are in effect in some specific buffers -only. Unlike per-mode bindings described above, per-buffer bindings can be -defined based on considerations other than the major mode. This is done -via the function @code{viper-add-local-keys}, which lets one specify bindings -that should be in effect in the current buffer only and for a specific Viper -state. For instance, -@lisp -(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master) - ("ZQ" .@: viper-save-kill-buffer))) -@end lisp -@noindent -redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state} -and @kbd{ZQ} to save-then-kill the current buffer. These bindings take -effect only in the buffer where this command is executed. The typical use -of this function is to execute the above expression from within a function -that is included in a hook to some major mode. For instance, the above -expression -could be called from a function, @code{my-tex-init}, which may be added to -@code{tex-mode-hook} as follows: -@lisp -(add-hook 'tex-mode-hook 'my-tex-init) -@end lisp -@noindent -When TeX mode starts, the hook is executed and the above Lisp expression is -evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi -command mode for all buffers in TeX mode. - -Another useful application is to bind @kbd{ZZ} to @code{send-mail} -in the Mail mode buffers (the specifics of this depend on which mail -package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc. -For instance, here is how to do this for @code{mh-e}, the Emacs interface -to MH: -@lisp -(defun mh-add-vi-keys () - "Set up ZZ for MH-e and XMH." - (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter)))) -(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys) -@end lisp - -You can also use @code{viper-add-local-keys} to set per buffer -bindings in Insert state and Emacs state by passing as a parameter the -symbols @code{insert-state} and @code{emacs-state}, respectively. -As with global bindings, customized local bindings done to Emacs state -are not inherited by Insert state. - -On rare occasions, local keys may be added by mistake. Usually this is done -indirectly, by invoking a major mode that adds local keys (e.g., -@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong -major mode won't rid you from unwanted local keys, since these keys are -local to Viper state and the current buffer, not to the major mode. -In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}. - -So much about Viper-specific bindings. -@xref{Customization,,Customization,emacs,The GNU Emacs -Manual}, and the Emacs quick reference card for the general info on key -bindings in Emacs. - -@vindex @code{input-decode-map} -@vindex @code{function-key-map} -@vindex @code{viper-vi-global-user-map} -@vindex @code{viper-insert-global-user-map} -@vindex @code{viper-emacs-global-user-map} -@findex @code{viper-add-local-keys} -@findex @code{viper-zap-local-keys} - -@node Packages that Change Keymaps,Viper Specials,Key Bindings,Customization -@subsection Packages that Change Keymaps -@cindex C-c and Viper -@cindex Viper and C-c - -Viper is designed to coexist with all major and minor modes of Emacs. This -means that bindings set by those modes are generally available with Viper -(unless you explicitly prohibit them by setting -@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to -@code{nil}). -If @code{viper-always} is set to @code{t} (which is the default), Viper -will try to bring each buffer -in the Viper state that is most appropriate for that buffer. -Usually, this would be the Vi state, but sometimes it could be the Insert -state or the Emacs state. - -Some major mode bindings will necessarily be overwritten by Viper. Indeed, in -Vi state, most of the 1-character keys are used for Vi-style editing. This -usually causes no problems because most packages designed for editing files -typically do not bind such keys. Instead, they use key sequences that start -with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to -free up @kbd{C-x} and @kbd{C-c}. -It is common for language-specific major modes to bind @key{TAB} and -@kbd{C-j} (the line feed) keys to various formatting functions. This is -extremely useful, but may require some getting used to for a Vi user. If you -decide that this feature is not for you, you can re-bind these keys as -explained earlier (@pxref{Customization}). - -Binding for @key{TAB} is one of the most unusual aspects of Viper for many -novice users. In Emacs, @key{TAB} is used to format text and programs, and -is extremely useful. For instance, hitting @key{TAB} causes the current -line to be re-indented in accordance with the context. In programming, -this is very important, since improper automatic indentation would -immediately alert the programmer to a possible error. For instance, if a -@kbd{)} or a @kbd{"} is missing somewhere above the current -line, @key{TAB} is likely to mis-indent the line. - -For this reason, Viper doesn't change the standard Emacs binding of -@key{TAB}, thereby sacrificing Vi compatibility -(except for users at level 1). Instead, in Viper, the key -@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}. - -We should note that on some non-windowing terminals, Shift doesn't modify -the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such -a case, you will have to bind @code{viper-insert-tab} to some other -convenient key. - -Some packages, notably Dired, Gnus, Info, etc., attach special meaning to -common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This -means that Vi command state is inappropriate for working with these -packages. Fortunately, these modes operate on read-only buffers and are -designed not for editing files, but for special-purpose browsing, reading -news, mail, etc., and Vi commands are meaningless in these situations. For -this reason, Viper doesn't force Vi state on such major modes---it -brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z} -if, for instance, you want to do Vi-style search in a buffer (although, -usually, incremental search, which is bound to @kbd{C-s}, is sufficient in -these situations). But you should then switch back to Emacs state if you -plan to continue using these major modes productively. You can also switch -to Vi temporarily, to execute just one command. This is done by typing -@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound -Vi-style, unless these keys perform essential duties.) - -If you would like certain major modes to come up in Emacs state rather than -Vi state (but Viper thinks otherwise), you should put these major modes -on the @code{viper-emacs-state-mode-list} list and delete them from -@code{viper-vi-state-mode-list}. -Likewise, you can force Viper's Insert state on a major mode by putting it -in @code{viper-insert-state-mode-list}. -@vindex @code{viper-emacs-state-mode-list} -@vindex @code{viper-insert-state-mode-list} -@vindex @code{viper-vi-state-mode-list} - -It is also possible to impose Vi on some major modes, even though they may -bind common keys to specialized commands. This might make sense for modes -that bind only a small number of common keys. For instance, Viper subverts -the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using -@code{viper-add-local-keys} described in the section on customization -(@pxref{Customization}). - -In some cases, some @emph{minor} modes might override certain essential -bindings in Vi command state. This is not a big problem because this -can happen only in the beginning, when the minor mode kicks in. Typing -@code{M-x viper-mode} will correct the situation. Viper knows about -several such minor modes and takes care of them, so the above trick -is usually not necessary. If you find that some minor mode, e.g., -@code{nasty-mode} interferes with Viper, putting the following in -@file{.viper} should fix the problem: -@lisp -(viper-harness-minor-mode "nasty-mode") -@end lisp -@noindent -The argument to @code{viper-harness-minor-mode} is the name of the file for the -offending minor mode with the suffixes @file{.el} and @file{.elc} removed. - -It may not be always obvious which minor mode is at fault. The only -guidance here is to look into the file that defines the minor mode you are -suspecting, say @file{nasty-mode.el}, and see if it has a variable called -@code{nasty-mode-map}. Then check if there is a statement of the form -@lisp -(define-key nasty-mode-map key function) -@end lisp -@noindent -that binds the misbehaving -keys. If so, use the above line to harness @code{nasty-mode}. If your -suspicion is wrong, no harm is done if you harness a minor mode that -doesn't need to be harnessed. - -It is recommended to harness even those minor modes that don't override -Viper keys, but still have their own keymaps. A general way to -make a minor mode, @code{my-mode}, -compatible with Viper is to have the file @file{my-mode.el} include the following code: - -@lisp -(when (fboundp 'viper-harness-minor-mode) - (let ((lib (file-name-sans-extension - (file-name-nondirectory load-file-name)))) - (viper-harness-minor-mode lib))) -@end lisp - -@vindex @code{viper-want-emacs-keys-in-vi} -@vindex @code{viper-want-emacs-keys-in-insert} -@vindex @code{viper-always} -@findex @code{viper-set-hooks} -@findex @code{viper-mode} -@findex @code{viper-harness-minor-mode} -@findex @code{remove-hook} -@findex @code{add-hook} - -@node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization -@section Viper Specials - -Viper extends Vi with a number of useful features. This includes various -search functions, histories of search strings, Ex commands, insertions, and -Vi's destructive commands. In addition, Viper supports file name completion -and history, completion of Ex commands and variables, and many other -features. Some of these features are explained in detail elsewhere in this -document. Other features are explained here. - -@table @code -@item (viper-buffer-search-enable) -@item viper-buffer-search-char nil -Enable buffer search. Explicit call to @code{viper-buffer-search-enable} -sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can -set @code{viper-buffer-search-char} in @file{.viper} to a key sequence -to be used for buffer search. There is no need to call -@code{viper-buffer-search-enable} in that case. -@findex @code{viper-buffer-search-enable} -@vindex @code{viper-buffer-search-char} -@item viper-toggle-search-style -This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and -case-insensitive search, and also switch between plain vanilla search and -search via regular expressions. Without the prefix argument, the user is -asked which mode to toggle. With prefix argument 1, this toggles -case-sensitivity. With prefix argument 2, regular expression/vanilla search -will be toggled. - -However, we found that the most convenient way to toggle -these options is to bind a Vi macro to -bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles -vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from -case sensitive search to case-insensitive. Repeating this once again will -restore the original state. Likewise, quickly hitting @kbd{/} three times -will switch you from vanilla-style search to search via regular expressions. -If you hit something other than @kbd{/} after the first @kbd{/} or if the -second @kbd{/} doesn't follow quickly enough, then Viper will issue the -usual prompt @kbd{/} and will wait for input, as usual in Vi. -If you don't like this behavior, you can ``unrecord'' these macros in your -@file{~/.viper} file. For instance, if you don't like the above feature, put -this in @file{~/.viper}: -@example -(viper-set-searchstyle-toggling-macros 'undefine) -@end example -@findex @code{viper-set-searchstyle-toggling-macros} - -If you don't like this feature as a default, but would still like to have -it in some major modes, you can do so by first unsetting it globally, as -shown above, and then setting it in the desired major modes as follows: -@example -(viper-set-searchstyle-toggling-macros nil 'c-mode) -(viper-set-searchstyle-toggling-macros nil 'lisp-mode) -@end example - -@item Vi-isms in Emacs state -Some people find it useful to use the Vi-style search key, `/', to invoke -search in modes which Viper leaves in emacs-state. These modes are: -@code{dired-mode}, @code{mh-folder-mode}, -@code{Info-mode}, and @code{Buffer-menu-mode} -(more may be added in the future). So, in the above modes, Viper binds `/' -so that it will behave Vi-style. Furthermore, in those major modes, Viper -binds `:' to invoke ex-style commands, like in vi-state. And, as described -above, `//' and `///' get bound to Vi-style macros that toggle -case-insensitivity and regexp-search. - -If you don't like these features---which I don't really understand---you -can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in -@code{viper-slash-and-colon-map}, for other modes. -@vindex @code{viper-slash-and-colon-map} -@vindex @code{viper-dired-modifier-map} - -To unbind the macros `//' and `///' for a major mode where you feel they -are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a -non-@code{nil} argument. This can be done either interactively, by supplying a -prefix argument, or by placing -@example -(viper-set-emacs-state-searchstyle-macros 'undefine) -@end example -@findex @code{viper-set-emacs-state-searchstyle-macros} -in the hook to the major mode (e.g., @code{dired-mode-hook}). -@xref{Vi Macros}, for more information on Vi macros. - -@item viper-heading-start -@item viper-heading-end -@cindex headings -@cindex sections -@cindex paragraphs -@cindex sentences -Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines -Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and -Sentences,emacs,The GNU Emacs Manual}, for details. -@item M-x viper-set-expert-level -@findex @code{viper-set-expert-level} -Change your user level interactively. -@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p") -@vindex @code{viper-smart-suffix-list} -Viper supports Emacs-style file completion when it prompts the user for a -file name. However, in many cases, the same directory may contain files -with identical prefix but different suffixes, e.g., prog.c, prog.o, -paper.tex, paper.dvi. In such cases, completion will stop at the `.'. -If the above variable is a list of strings representing suffixes, Viper will -try these suffixes -in the order listed and will check if the corresponding file exists. - -For instance, if completion stopped at `paper.'@: and the user typed -@key{RET}, -then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. -It will take the first such file. If no file exists, Viper will give a chance -to complete the file name by typing the appropriate suffix. If `paper.'@: was -the intended file name, hitting return will accept it. - -To turn this feature off, set the above variable to @code{nil}. - -@item viper-insertion-ring-size 14 -@vindex @code{viper-insertion-ring-size} -@cindex Insertion ring -Viper remembers what was previously inserted in Insert and Replace states. -Several such recent insertions are kept in a special ring of strings of size -@code{viper-insertion-ring-size}. -If you enter Insert or Replace state you can reinsert strings from this -ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the -ring in -the direction of older insertions, and the latter will search in -the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} -in succession -will undo the previous insertion from the ring and insert the next item on -the ring. If a larger ring size is needed, change the value of the above -variable in the @file{~/.viper} file. - -Since typing these sequences of keys may be tedious, it is suggested that the -user should bind a function key, such as @kbd{f31}, as follows: -@example -(define-key viper-insert-global-user-map [f31] - 'viper-insert-prev-from-insertion-ring) -@end example -This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that inserts the previous string in the insertion history. -To rotate the history in the opposite -direction, you can either bind an unused key to -@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then -@kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the Minibuffer histories and, possibly, other -major modes. - -@item viper-command-ring-size 14 -@vindex @code{viper-command-ring-size} -@cindex Destructive command ring -@cindex Destructive command history -Viper keeps track of the recent history of destructive -commands, such as @kbd{dw}, @kbd{i}, etc. -In Vi state, -the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. -However, repeated typing @kbd{C-c M-p} will cause Viper to show the -previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' -will execute the command that was displayed last. -The key @kbd{C-c M-n} will cycle through the command history in the -opposite direction. -Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an -appropriate function to an unused function key on the keyboard and use that -key. For instance, the following -@example -(define-key viper-vi-global-user-map [f31] - 'viper-prev-destructive-command) -@end example -binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) -to the function that searches the command history in the direction of older -commands. To search in the opposite -direction, you can either bind an unused key to -@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}. - -One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since -this will interfere with the Minibuffer histories and, possibly, other -major modes. - -@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face -@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face -@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face -These faces control the appearance of the minibuffer text in the -corresponding Viper states. You can change the appearance of these faces -through Emacs' customization widget, which is accessible through the -menubar. - -Viper is located in this widget under the @emph{Emulations} customization -subgroup of the @emph{Editing} group. All Viper faces are grouped together -in Viper's @emph{Highlighting} customization subgroup. - -Note that only the text you type in is affected by the above faces. -Prompts and Minibuffer messages are not affected. - -Purists who do not like adornments in the minibuffer can always zap them by -putting -@example -(copy-face 'default 'viper-minibuffer-vi-face) -(copy-face 'default 'viper-minibuffer-insert-face) -(copy-face 'default 'viper-minibuffer-emacs-face) -@end example -in the @file{~/.viper} file or through the customization widget, as -described above. However, in that case, the user will not have any -indication of the current Viper state in the minibuffer. (This is important -if the user accidentally switches to another Viper state by typing @key{ESC} or -@kbd{C-z}). -@item M-x viper-go-away -@findex @code{viper-go-away} -Make Viper disappear from the face of your running Emacs instance. If your -fingers start aching again, @kbd{M-x viper-mode} might save your day. -@item M-x toggle-viper-mode -@findex @code{toggle-viper-mode} -Toggle Viperization of Emacs on and off. -@end table - -@cindex Multifile documents and programs - -Viper provides some support for multi-file documents and programs. -If a document consists of several files we can designate one of them as a -master and put the following at the end of that file: -@lisp -;; Local Variables: -;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file4") -;; End: -@end lisp -@noindent -where @code{file1} to @code{file4} are names of files related to the master -file. Next time, when the master file is visited, the command -@code{viper-setup-master-buffer} will be evaluated and the above files will -be associated with the master file. Then, the new Ex command -@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 4 one after -another, so you can edit them. If a file is not in any Emacs buffer, it -will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) -goes through the file list in the opposite direction. -@findex @kbd{:RelatedFile} -@findex @kbd{:PreviousRelatedFile} - -These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to -focus on relevant files only. - -Note that only the master file needs to have the aforementioned block of -commands. Also, ";;" above can be replaced by some other -markers. Semicolon is good for Lisp programs, since it is considered a -comment designator there. For LaTeX, this could be "%%%", and for C the -above block should be commented out. - -Even though these commands are sometimes useful, they are no substitute for -the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command -in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, -The GNU Emacs Manual}, for more information on tags. - -The following two commands are normally bound to a mouse click and are part -of Viper. They work only if Emacs runs as an application under X -Windows (or under some other window system for which a port of GNU Emacs 20 -is available). Clicking the mouse when Emacs is invoked in an Xterm window -(using @code{emacs -nw}) will do no good. - -@table @code -@cindex mouse -@cindex mouse-search -@item viper-mouse-search-key (meta shift 1) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-search} feature of Viper. The -default value -states that holding Meta and Shift keys while clicking mouse button 1 -should initiate search for a region under the mouse pointer (defined -below). This command can take a prefix argument, which indicates the -occurrence of the pattern to search for. - -Note: while loading initially, Viper binds this mouse action only if it is -not already bound to something else. If you want to use the mouse-search -feature, and the @kbd{Meta-Shift-Mouse-1} mouse action is already bound to -something else, you can rebind the mouse-search feature by setting -@code{viper-mouse-search-key} to something else in your @code{~/.viper} -file: -@lisp -(setq viper-mouse-search-key '(meta 1)) -@end lisp -This would bind mouse search to the action invoked by pressing the -Meta key and clicking mouse button 1. The allowed values of -@code{viper-mouse-search-key} are lists that contain a mouse-button number -(1,2, or 3) and any combination of the words `control', `meta', and -`shift'. - -If the requested mouse action (e.g., (meta 1)) is already taken for other -purposes then you have to confirm your intention by placing the following -command in @code{~/.viper} after setting @code{viper-mouse-search-key}: -@lisp -(viper-bind-mouse-search-key 'force) -@end lisp - -You can also change this setting interactively, through the customization -widget of Emacs (type @kbd{:customize}). - -The region that is chosen as a pattern to search for is determined as -follows. If search is invoked via a single click, Viper chooses the region -that lies between the beginning of the ``word'' under the pointer (``word'' -is understood in Vi sense) and the end of that word. The only difference -with Vi's words is that in Lisp major modes `-' is considered an -alphanumeric symbol. This is done for the convenience of working with Lisp -symbols, which often have an `-' in them. Also, if you click on a -non-alphanumeric character that is not a word separator (in Vi sense) then -this character will also be considered alphanumeric, provided that it is -adjacent (from either side) to an alphanumeric character. This useful -feature gives added control over the patterns selected by the mouse click. - -On a double-click, the region is determined by the beginning of the current -Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End -of that ``Word'' (as determined by the @kbd{E} command). - -On a triple-click, the region consists of the entire line where the click -occurred with all leading and trailing spaces and tabs removed. - -@cindex mouse-insert -@item viper-mouse-insert-key (meta shift 2) -@vindex @code{viper-mouse-insert-key} -This variable controls the @emph{mouse-insert} feature of Viper. -The above default value states that -holding Meta and Shift keys while clicking mouse button 2 -should insert the region surrounding the -mouse pointer. The rules defining this region are the same as for -mouse-search. This command takes an optional prefix argument, which -indicates how many such regions to snarf from the buffer and insert. (In -case of a triple-click, the prefix argument is ignored.) - -Note: while loading initially, Viper binds this mouse action only if it not -already bound to something else. If you want to use this feature and the -default mouse action is already bound, you can rebind mouse-insert by -placing this command in @code{~/.viper}: -@lisp -(setq viper-mouse-insert-key '(meta 2)) -@end lisp -If you want to bind mouse-insert to an action even if this action is -already taken for other purposes in Emacs, then you should add this command -to @code{~/.viper}, after setting @code{viper-mouse-insert-key}: -@lisp -(viper-bind-mouse-insert-key 'force) -@end lisp - -This value can also be changed via the Emacs customization widget at the -menubar. - -@item viper-multiclick-timeout -This variable controls the rate at which double-clicking must occur for the -purpose of mouse search and mouse insert. By default, this is set to -@code{double-click-time} in Emacs and to -@code{mouse-track-multi-click-time} milliseconds in XEmacs. -@end table -@kindex @kbd{S-Mouse-1} -@kindex @kbd{S-Mouse-2} -@kindex @kbd{meta shift button1up} -@kindex @kbd{meta shift button2up} -@vindex @code{viper-multiclick-timeout} -@findex @code{viper-mouse-click-insert-word} -@findex @code{viper-mouse-click-search-word} - -Note: The above functions search and insert in the selected window of -the latest active frame. This means that you can click in another window or -another frame and have search or insertion done in the frame and window you -just left. This lets one use these functions in a multi-frame -configuration. However, this may require some getting used to. For -instance, if you are typing in a frame, A, and then move the mouse to frame -B and click to invoke mouse search, search (or insertion) will be performed -in frame A. To perform search/insertion in frame B, you will first have to -shift focus there, which doesn't happen until you type a character or -perform some other action in frame B---mouse search doesn't shift focus. - -If you decide that you don't like the above feature and always want -search/insertion be performed in the frame where the click occurs, don't -bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from -the mouse event it is bound to. - -Mouse search is integrated with Vi-style search, so you can -repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while -case-sensitivity of search in Viper is controlled by the variable -@code{viper-case-fold-search}, the case of mouse search is -controlled by the Emacs variable @code{case-fold-search}, which may be set -differently from @code{viper-case-fold-search}. Therefore, case-sensitivity -of mouse search may be different from that of the usual Vi-style search. - -Finally, if the way Viper determines the word to be searched for or to be -inserted is not what you want, there is a variable, -@code{viper-surrounding-word-function}, which can be changed to indicate -another function for snarfing words out of the buffer. The catch is that -you will then have to write such a function and make it known to your -Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be -used as a guiding example. - -@node Vi Macros, ,Viper Specials,Customization -@section Vi Macros - -@cindex Vi macros - -Viper supports much enhanced Vi-style macros and also facilitates the use -of Emacs-style macros. To define a temporary macro, it is generally more -convenient to use Emacs keyboard macro facility. Emacs keyboard macros are -usually defined anonymously, and the latest macro can be executed by typing -@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several -temporary macros, Viper lets you save them to a -register (a lowercase letter); such macros can then be executed by typing -@kbd{@@a} in Vi state (if a macro was previously saved in register -@kbd{a}). -@xref{Macros and Registers}, for details. - -If, however, you need to use a macro regularly, it must be given a -permanent name and saved. Emacs manual explains how to do this, but -invocation of named Emacs macros is quite different from Vi's. First, -invocation of permanent Emacs macros takes time because it requires typing -too many keys (to a Vi user's taste, anyway). -Second, binding such macros to function keys, for -fast access, hogs valuable real estate on the keyboard. - -Vi-style macros are better in that respect, since Vi lets the user overload -the meaning of key sequences: keys typed in fast succession are treated -specially, if this key sequence is bound to a macro. - -Viper provides Vi-style keyboard macros through the usual Ex commands, -@kbd{:map} and -@kbd{:map!}. These macros are much more powerful in Viper than -they are in the original Vi and in other emulators. This is because Viper -implements an enhanced vi-style -interface to the powerful Emacs keyboard macro facility. - -First, any Emacs -command can be executed while defining a macro, not just the Vi -commands. In particular, the user can invoke Emacs commands via @kbd{M-x -command-name} or by pressing various function keys on the keyboard. One -can even use the mouse, although this is usually not useful and is not -recommended (and macros defined with the use of the mouse cannot be saved in -command history and in the startup file, for future use). - -Macros defined by mixing Vi and Emacs commands are represented as -vectors. So, don't be confused when you see one (usually through the -history of Ex commands). For instance, if @kbd{gg} is defined by typing -@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look -as follows in Emacs: - -@example -[l up (meta x) n e x t - l i n e return] -@end example - -Second, Viper macros are defined in a WYSIWYG style. This means that -commands are executed as you type them, so you can see precisely what is -being defined. Third, macros can be bound to arbitrary sequences of keys, -not just to printable keys. For instance, one can define a macro that will -be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys -@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation -sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and -@kbd{help}, can't be bound to macros under Emacs, since they -are bound in @code{key-translation-map}, which overrides any other binding -the user gives to keys. In general, keys that have a binding in -@code{key-translation-map} can't be bound to a macro.) - -Fourth, in Viper, one can define macros that are specific to a given -buffer, a given major mode, or macros that are defined for all buffers. In -fact, the same macro name can have several different definitions: one -global, several definitions for various major modes, and -definitions for various specific buffers. Buffer-specific definitions -override mode-specific definitions, which, in turn, override global -definitions. - -As if all that is not enough, Viper (through its interface to Emacs -macros) lets the user define keyboard macros that ask for confirmation or -even prompt the user for input and then continue. To do this, one should -type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). -For details, @pxref{Keyboard Macro Query,,Customization,emacs,The GNU Emacs -Manual} @refill - -When the user finishes defining a macro (which is done by typing @kbd{C-x)} --- -a departure from Vi), you will be asked whether you want this -macro to be global, mode-specific, or buffer-specific. You will also be -given a chance to save the macro in your @file{~/.viper} file. -This is the easiest way to save a macro and make -it permanently available. If you work your startup files with bare hands, -here is how Viper saves the above macro so that it will be -available in Viper's Insert state (and Replace state) in buffer @code{my-buf} -only: - -@example -(viper-record-kbd-macro "gg" 'insert-state - [l up (meta x) n e x t - l i n e return] - "my-buf") -@end example - -@noindent -To do the same for Vi state and all buffers with the major mode -@code{cc-mode}, use: - -@example -(viper-record-kbd-macro "gg" 'vi-state - [l up (meta x) n e x t - l i n e return] - 'cc-mode) -@end example - -@noindent -Both macro names and macro definitions are vectors of symbols that denote -keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must -be escaped with a backslash. Modified keys are represented as lists. For -instance, holding Meta and Control and pressing @kbd{f4} is represented as -@kbd{(control meta f4)}. -If all members of a vectors are printable characters (or sequences, such as -@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as -strings: - -@example -(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer") -@end example - -@noindent -Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state -(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi -state. All this will take effect only in the buffer named @code{my-buffer}. - -Note that the last argument to @code{viper-record-kbd-macro} must be either a -string (a buffer name), a symbol representing a major mode, or @code{t}; -the latter says that the macro is to be defined for all buffers -(which is how macros are defined in original Vi). - -For convenience, Viper also lets you define Vi-style macros in its Emacs -state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing -this, but the user can include such a macro in the @file{~/.viper} file. The -only thing is that the @code{viper-record-kbd-macro} command should specify -@code{emacs-state} instead of @code{vi-state} or @code{insert-state}. - -The user can get rid of a macro either by using the Ex commands @kbd{:unmap} -and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}. -The latter is more powerful, since it can delete macros even in -@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually -needed only when the user needs to get rid of the macros that are already -predefined in Viper. -The syntax is: -@findex @code{viper-unrecord-kbd-macro} -@example -(viper-unrecord-kbd-macro macro state) -@end example -@noindent -The second argument must be @code{vi-state}, @code{insert-state}, or -@code{emacs-state}. The first argument is a name of a macro. To avoid -mistakes in specifying names of existing macros, type @kbd{M-x -viper-describe-kbd-macros} and use a name from the list displayed by this -command. - -If an error occurs during macro definition, Emacs -aborts the process, and it must be repeated. This is analogous to Vi, -except that in Vi the user doesn't know there is an error until the macro is -actually run. All that means that in order for a definition to be -successful, the user must do some simple planning of the process in -advance, to avoid errors. For instance, if you want to map @kbd{gg} to -@kbd{llll} in Vi state, you must make sure that there is enough room on the -current line. Since @kbd{l} moves the cursor forward, it may signal an -error on reaching the end of line, which will abort the definition. - -These precautions are necessary only when defining macros; they will help -avoid the need to redo the job. When macros are actually run, an error -during the execution will simply terminate the current execution -(but the macro will remain mapped). - -A macro name can be a string of characters or a vector of keys. -The latter makes it possible to define macros bound to, say, double-hits -on a function key, such as @kbd{up} or @kbd{f13}. -This is very useful if you run out of function keys on your keyboard; it -makes Viper macro facility a @emph{keyboard doubler}, so to speak. - -Elsewhere (@xref{Key Bindings}, for details), we review -the standard Emacs mechanism for binding function keys to commands. -For instance, - -@example -(global-set-key [f13] 'repeat-complex-command) -@end example - -@noindent -binds the key f13 to the Emacs function that repeats the last minibuffer -command. Under Viper, however, you may still use this key for additional -purposes, if you bind, say, a double-hitting action for that key to some -other function. Emacs doesn't allow the user to do that, but Viper does -this through its keyboard macro facility. To do this, type @kbd{:map } -first. When you are asked to enter a macro name, hit f13 twice, followed by -@key{RET} or @key{SPC}. - -Emacs will now start the mapping process by actually executing -Vi and Emacs commands, so that you could see what will happen each time the -macro is executed. Suppose now we wanted to bind the key sequence -@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we -can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. -If you answer positively to Viper's offer to save this macro in @file{~/.viper} -for future uses, the following will be inserted in that file: - -@example -(viper-record-kbd-macro [f16 f16] 'vi-state - [(meta x) e v a l - l a s t - s e x p] - 'lisp-interaction-mode) -@end example - -To illustrate the above point, Viper provides two canned macros, which, by -default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing -@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful -shortcuts to Viper's command ring history. The first macro will execute the -second-last destructive command (the last one is executed by @kbd{.}, as -usual). The second macro executes the third-last command. - -If you need to go deeper into the command history, you will have to use -other commands, as described earlier in this section; or you can bind, -say, @kbd{f12 \3} like this: - -@example -(viper-record-kbd-macro [f12 \3] 'vi-state - [(meta x) r e p e a t - f r o m - h i s t o r y] - t) -@end example - - -Note that even though the macro uses the function key @kbd{f12}, the key is -actually free and can still be bound to some Emacs function via -@code{define-key} or @code{global-set-key}. - - -Viper allows the user to define macro names that are prefixes of other macros. -For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros. -If you type the exact sequence of such keys and then pause, Viper will -execute the right macro. However, if you don't pause and, say, type -@kbd{[[[[text} then the conflict is resolved as follows. If only one of the -key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the -current buffer, then, in fact, there is no conflict and the right macro -will be chosen. If both have applicable definitions, then the first one -found will be executed. Usually this is the macro with a shorter name. So, -in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed -twice and then the remaining keys, @kbd{t e x t}, will be processed. - -When defining macros using @kbd{:map} or @kbd{:map!}, the user enters -the actually keys to be used to invoke the macro. For instance, you -should hit the actual key @kbd{f6} if it is to be part of a macro -name; you do @emph{not} write @kbd{f 6}. When entering keys, Viper -displays them as strings or vectors (e.g., @code{"abc"} or @code{[f6 -f7 a]}). The same holds for unmapping. Hitting @key{TAB} while -typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command will -cause name completion. Completions are displayed as strings or -vectors. However, as before, you don't actually type @samp{"}, -@samp{[}, or @samp{]} that appear in the completions. These are -meta-symbols that indicate whether the corresponding macro name is a -vector or a string. - -One last difference from Vi: Vi-style keyboard macros cannot be defined in -terms of other Vi-style keyboard macros (but named Emacs macros are OK). -More precisely, while defining or executing a macro, the special meaning -of key sequences (as Vi macros) is ignored. -This is because it is all too easy to create an infinite loop in this way. -Since Viper macros are much more powerful than Vi's it is impossible to -detect such loops. In practice, this is not really a limitation but, -rather, a feature. - -We should also note that Vi macros are disabled in the Minibuffer, which -helps keep some potential troubles away. - -The rate at which the user must type keys in order for them to be -recognized as a timeout macro is controlled by the variable -@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. - -For the most part, Viper macros defined in @file{~/.viper} can be shared -between X and TTY modes. -The problem with TTY may be that the function keys there generate sequences -of events instead of a single event (as under a window system). -Emacs maps some of these sequences back to the logical keys -(e.g., the sequences generated by the arrow keys are mapped to @kbd{up}, -@kbd{left}, etc.). However, not all function keys are mapped in this way. -Macros that are bound to key sequences that contain such unmapped function -keys have to be redefined for TTY's (and possibly for every type of TTY you -may be using). To do this, start Emacs on an appropriate TTY device and -define the macro using @kbd{:map}, as usual. - -@findex @code{viper-describe-kbd-macros} -Finally, Viper provides a function that conveniently displays all macros -currently defined. To see all macros along with their definitions, type -@kbd{M-x viper-describe-kbd-macros}. - -@node Commands,,Customization,Top -@chapter Commands - -This section is a semi-automatically bowdlerized version of the Vi -reference created by @* @samp{maart@@cs.vu.nl} and others. It can be -found on the Vi archives. This reference has been adapted for Viper.@refill - -@menu -* Groundwork:: Textual Conventions and Viper basics -* Text Handling:: Moving, Editing, Undoing. -* Display:: Scrolling. -* File and Buffer Handling:: Editing, Writing and Quitting. -* Mapping:: Mapping Keys, Keyboard Macros -* Shell Commands:: Accessing Shell Commands, Processing Text -* Options:: Ex options, the @kbd{:set} commands -* Emacs Related Commands:: Meta Keys, Windows -* Mouse-bound Commands:: Search and insertion of text -@end menu - -@node Groundwork, Text Handling, Commands, Commands -@comment node-name, next, previous, up -@section Groundwork - -The VI command set is based on the idea of combining motion commands -with other commands. The motion command is used as a text region -specifier for other commands. -We classify motion commands into @dfn{point commands} and -@dfn{line commands}.@refill - -@cindex point commands - -The point commands are: - -@quotation -@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, -@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, -@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} -@end quotation - -@cindex line commands - -The line commands are: - -@quotation -@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, -@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} -@end quotation -@noindent - -Text Deletion Commands (@pxref{Deleting Text}), Change commands -(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) -use these commands to describe a region of text to operate on. - -@cindex r and R region specifiers - -Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe -the Emacs regions (@pxref{Basics}), but they are not movement commands. - -The command description uses angle brackets @samp{<>} to indicate -metasyntactic variables, since the normal conventions of using simple -text can be confusing with Viper where the commands themselves are -characters. Watch out where @kbd{<} shift commands and @kbd{} are -mentioned together!!! - -@kindex -@kindex -@kindex
-@cindex -@cindex -@cindex
-@cindex movements - -@samp{} refers to the above movement commands, and @samp{} -refers to registers or textmarkers from @samp{a} to @samp{z}. Note -that the @samp{} is described by full move commands, that is to -say they will take counts, and otherwise behave like normal move commands. -@cindex Ex addresses -@samp{
} refers to Ex line addresses, which include - -@table @kbd -@item .@: -Current line -@item .+n .-n -Add or subtract for current line -@item number -Actual line number, use @kbd{.=} to get the line number -@item ' -Textmarker -@item $ -Last line -@item x,y -Where x and y are one of the above -@item % -@cindex % (Ex address) -For the whole file, same as (1,$). -@item // -@itemx ?? -Next or previous line with pattern . - -Note that the pattern is allowed to contain newline character (inserted as -@kbd{C-qC-j}). Therefore, one can search for patterns that span several -lines. -@end table - -@cindex % (Current file) -Note that @samp{%} is used in Ex commands @kbd{:e} and @kbd{:r } -to mean current file. If you want a @samp{%} in your command, it must be -escaped as @samp{\%}. Note that @kbd{:w} and the regular @kbd{:r } -command doesn't support the meta symbols @samp{%} and @samp{#}, because -file history is a better mechanism. -@cindex # (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is -the first file in @kbd{:args} listing. This defaults to previous window -in the VI sense if you have one window only. - -@kindex -@kindex -@cindex -@cindex -@noindent -Others like @samp{ -- arguments}, @samp{ -- command} etc. -should be fairly obvious. - -@noindent -Common characters referred to include: - -@table @kbd -@item -Space -@item -Tab -@item -Linefeed -@item -Escape -@item -Return, Enter -@end table -@cindex -@cindex -@cindex -@cindex -@cindex - -@cindex words -@cindex WORDS -@cindex char -@cindex CHAR - -We also use @samp{word} for alphanumeric/non-alphanumeric words, and -@samp{WORD} for whitespace delimited words. @samp{char} refers to any -@acronym{ASCII} character, @samp{CHAR} to non-whitespace character. -Brackets @samp{[]} indicate optional parameters; @samp{} also -optional, usually defaulting to 1. Brackets are elided for -@samp{} to eschew obfuscation. - -Viper's idea of Vi's words is slightly different from Vi. First, Viper -words understand Emacs symbol tables. Therefore, all symbols declared to be -alphanumeric in a symbol table can automatically be made part of the Viper -word. This is useful when, for instance, editing text containing European, -Cyrillic, Japanese, etc., texts. - -Second, Viper lets you depart from Vi's idea of a word by changing the a -syntax preference via the customization widget (the variable -@code{viper-syntax-preference}) or by executing -@code{viper-set-syntax-preference} interactively. - -By default, Viper syntax preference is @code{reformed-vi}, which means that -Viper considers only those symbols to be part of a word that are specified -as word-symbols by the current Emacs syntax table (which may be different -for different major modes) plus the underscore symbol @kbd{_}, minus the -symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be -considered as word-symbols by various Emacs major modes. Reformed-Vi works -very close to Vi, and it also recognizes words in other -alphabets. Therefore, this is the most appropriate mode for editing text -and is likely to fit all your needs. - -You can also set Viper syntax preference to @code{strict-vi}, which would -cause Viper to view all non-English letters as non-word-symbols. - -You can also specify @code{emacs} as your preference, which would -make Viper use exactly the same notion of a word as Emacs does. In -particular, the underscore may not be part of a word in some major modes. - -Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper -words would consist of characters that are classified as alphanumeric -@emph{or} as parts of symbols. This is convenient for editing programs. - -@code{viper-syntax-preference} is a local variable, so it can have different -values for different major modes. For instance, in programming modes it can -have the value @code{extended}. In text modes where words contain special -characters, such as European (non-English) letters, Cyrillic letters, etc., -the value can be @code{reformed-vi} or @code{emacs}. -If you consider using different syntactic preferences for different major -modes, you should execute, for example, - -@example -(viper-set-syntax-preference nil "extended") -@end example - -in the appropriate major mode hooks. - -@vindex @code{viper-syntax-preference} -@findex @code{viper-set-syntax-preference} -@cindex syntax table - - - -The above discussion concerns only the movement commands. In regular -expressions, words remain the same as in Emacs. That is, the expressions -@code{\w}, @code{\>}, @code{\<}, etc., use Emacs' idea of what is a word, -and they don't look into the value of variable -@code{viper-syntax-preference}. This is because Viper avoids changing -syntax tables in order to not thwart the various major modes that set these -tables. - -The usual Emacs convention is used to indicate Control Characters, i.e -C-h for Control-h. @emph{Do not confuse this with a sequence of separate -characters -C, -, h!!!} The @kbd{^} is itself, never used to indicate a -Control character. - -Finally, we note that Viper's Ex-style commands can be made to work on the -current Emacs region. This is done by typing a digit argument before -@kbd{:}. For instance, typing @kbd{1:} will prompt you with something like -@emph{:123,135}, assuming that the current region starts at line 123 and -ends at line 135. There is no need to type the line numbers, since Viper -inserts them automatically in front of the Ex command. -@cindex Ex commands - -@node Text Handling, Display, Groundwork, Commands -@section Text Handling - -@menu -* Move Commands:: Moving, Searching -* Marking:: Textmarkers in Viper and the Emacs Mark. -* Appending Text:: Text insertion, Shifting, Putting -* Editing in Insert State:: Autoindent, Quoting etc. -* Deleting Text:: Deleting -* Changing Text:: Changing, Replacement, Joining -* Search and Replace:: Searches, Query Replace, Pattern Commands -* Yanking:: Yanking, Viewing Registers -* Undoing:: Multiple Undo, Backups -@end menu - -@node Move Commands,Marking,,Text Handling -@subsection Move Commands - -@cindex movement commands -@cindex searching -@cindex textmarkers -@cindex markers -@cindex column movement -@cindex paragraphs -@cindex headings -@cindex sections -@cindex sentences -@cindex matching parens -@cindex paren matching - -@table @kbd -@item h C-h - chars to the left. -@item j C-n - lines downward. -@item l - chars to the right. -@item k C-p - lines upward. -@item $ -To the end of line from the cursor. -@item ^ -To the first CHAR - 1 lines lower. -@item - -To the first CHAR lines higher. -@item + -To the first CHAR lines lower. -@item 0 -To the first char of the line. -@item | -To column -@item f - s to the right (find). -@item t -Till before s to the right. -@item F - s to the left. -@item T -Till after s to the left. -@item ; -Repeat latest @kbd{f t F T} times. -@item , -Repeat latest @kbd{f t F T} - times in opposite direction. -@item w - words forward. -@item W - WORDS forward. -@item b - words backward. -@item B - WORDS backward. -@item e -To the end of word forward. -@item E -To the end of WORD forward. -@item G -Go to line (default end-of-file). -@item H -To line from top of the screen (home). -@item L -To line from bottom of the screen (last). -@item M -To the middle line of the screen. -@item ) - sentences forward. -@item ( - sentences backward. -@item @} - paragraphs forward. -@item @{ - paragraphs backward. -@item ]] -To the th heading. -@item [[ -To the th previous heading. -@item [] -To the end of th heading. -@item m -Mark the cursor position with a letter. -@item ` -To the mark. -@item ' -To the first CHAR of the line with the mark. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item `` -To the cursor position before the latest absolute -jump (of which are examples @kbd{/} and @kbd{G}). -@item '' -To the first CHAR of the line on which the cursor -was placed before the latest absolute jump. -@item / -To the th occurrence of . -@item / -To the th occurrence of from previous @kbd{/ or ?}. -@item ? -To the th previous occurrence of . -@item ? -To the th previous occurrence of from previous @kbd{?@: or /}. -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Repeat latest search in opposite direction. -@item C-c / -Without a prefix argument, this command toggles -case-sensitive/case-insensitive search modes and plain vanilla/regular -expression search. With the prefix argument 1, i.e., -@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, -toggles plain vanilla search and search using -regular expressions. @xref{Viper Specials}, for alternative ways to invoke -this function. -@cindex vanilla search -@cindex case-sensitive search -@cindex case-insensitive search -@item % -Find the next bracket/parenthesis/brace and go to its match. -By default, Viper ignores brackets/parentheses/braces that occur inside -parentheses. You can change this by setting -@code{viper-parse-sexp-ignore-comments} to @code{nil} in your @file{.viper} file. -This option can also be toggled interactively if you quickly hit @kbd{%%%}. - -This latter feature is implemented as a vi-style keyboard macro. If you -don't want this macro, put - -@example -(viper-set-parsing-style-toggling-macro 'undefine) -@end example -@findex @code{viper-set-parsing-style-toggling-macro} - -in your @file{~/.viper} file. - -@end table -@kindex @kbd{%} -@kindex @kbd{C-c /} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{?} -@kindex @kbd{/} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{'} -@kindex @kbd{`} -@kindex @kbd{m} -@kindex @kbd{[]} -@kindex @kbd{[[} -@kindex @kbd{]]} -@kindex @kbd{@{} -@kindex @kbd{@}} -@kindex @kbd{(} -@kindex @kbd{)} -@kindex @kbd{M} -@kindex @kbd{L} -@kindex @kbd{H} -@kindex @kbd{G} -@kindex @kbd{E} -@kindex @kbd{e} -@kindex @kbd{B} -@kindex @kbd{b} -@kindex @kbd{W} -@kindex @kbd{w} -@kindex @kbd{,} -@kindex @kbd{;} -@kindex @kbd{T} -@kindex @kbd{F} -@kindex @kbd{t} -@kindex @kbd{f} -@kindex @kbd{|} -@kindex @kbd{0} -@kindex @kbd{} -@kindex @kbd{+} -@kindex @kbd{-} -@kindex @kbd{^} -@kindex @kbd{$} -@kindex @kbd{C-p} -@kindex @kbd{} -@kindex @kbd{} -@kindex @kbd{C-n} -@kindex @kbd{C-h} -@kindex @kbd{h} -@kindex @kbd{j} -@kindex @kbd{k} -@kindex @kbd{l} -@vindex @code{viper-parse-sexp-ignore-comments} - -@node Marking,Appending Text,Move Commands,Text Handling -@subsection Marking - -Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}. -@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also -see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of -the Emacs mark ring. - -@cindex marking - -@table @kbd -@item m -Mark the current file and position with the specified letter. -@item m . -Set the Emacs mark (@pxref{Emacs Preliminaries}) at point. -@item m ^ -Set the Emacs mark (@pxref{Emacs Preliminaries}) back to where it was last -set with the @kbd{m.} command. This is useful when you set the mark with -@kbd{m.}, but then some other command (such as @kbd{L} or @kbd{G}) changes -it in a way that you didn't like. -@item m < -Set the Emacs mark at beginning of buffer. -@item m > -Set the Emacs mark at end of buffer. -@item m , -Jump to the Emacs mark. -@item :mark -Mark position with text marker named . This is an Ex command. -@item :k -Same as @kbd{:mark}. -@item `` -Exchange point and mark. -@item '' -Exchange point and mark and go to the first CHAR on line. -@item ' -Go to specified Viper mark. -@item -Go to specified Viper mark and go to the first CHAR on line. -@end table -@kindex @kbd{m} -@kindex @kbd{m.} -@kindex @kbd{m>} -@kindex @kbd{m<} -@kindex @kbd{m,} -@kindex @kbd{m^} -@findex @kbd{:mark} -@findex @kbd{:k} -@kindex @kbd{''} -@kindex @kbd{``} -@kindex @kbd{`} -@kindex @kbd{'} - -@node Appending Text, Editing in Insert State, Marking,Text Handling -@subsection Appending Text - -@xref{Options}, to see how to change tab and shiftwidth size. See the GNU -Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on). -Check out the variable @code{indent-tabs-mode} to put in just spaces. -Also see options for word-wrap. - -@cindex inserting -@cindex appending -@cindex paste -@cindex put - -@table @kbd -@item a - times after the cursor. -@item A - times at the end of line. -@item i - times before the cursor (insert). -@item I - times before the first CHAR of the line -@item o -On a new line below the current (open). -The count is only useful on a slow terminal. -@item O -On a new line above the current. -The count is only useful on a slow terminal. -@item > -Shift the lines described by one -shiftwidth to the right (layout!). -@item >> -Shift lines one shiftwidth to the right. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item . -Repeat previous command times. For destructive -commands as well as undo. -@item f1 1 and f1 2 -While @kbd{.} repeats the last destructive command, -these two macros repeat the second-last and the third-last destructive -commands. @xref{Vi Macros}, for more information on Vi macros. -@item C-c M-p and C-c M-n -In Vi state, -these commands help peruse the history of Vi's destructive commands. -Successive typing of @kbd{C-c M-p} causes Viper to search the history in -the direction -of older commands, while hitting @kbd{C-c M-n} does so in reverse -order. Each command in the history is displayed in the Minibuffer. The -displayed command can -then be executed by typing `@kbd{.}'. - -Since typing the above sequences of keys may be tedious, the -functions doing the perusing can be bound to unused keyboard keys in the -@file{~/.viper} file. @xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{.} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{>>} -@kindex @kbd{>} -@kindex @kbd{O} -@kindex @kbd{o} -@kindex @kbd{i} -@kindex @kbd{A} -@kindex @kbd{a} - -@node Editing in Insert State, Deleting Text, Appending Text,Text Handling -@subsection Editing in Insert State - -Minibuffer can be edited similarly to Insert state, and you can switch -between Insert/Replace/Vi states at will. -Some users prefer plain Emacs feel in the Minibuffer. To this end, set -@var{viper-vi-style-in-minibuffer} to @code{nil}. - -@cindex Insert state - -@table @kbd -@item C-v -Deprive the next char of its special meaning (quoting). -@item C-h -One char back. -@item C-w -One word back. -@item C-u -Back to the begin of the change on the -current line. - -@end table -@kindex @kbd{C-u} -@kindex @kbd{C-w} -@kindex @kbd{C-v} - -@node Deleting Text, Changing Text, Editing in Insert State, Text Handling -@subsection Deleting Text - - -There is one difference in text deletion that you should be -aware of. This difference comes from Emacs and was adopted in Viper -because we find it very useful. In Vi, if you delete a line, say, and then -another line, these two deletions are separated and are put back -separately if you use the @samp{p} command. In Emacs (and Viper), successive -series of deletions that are @emph{not interrupted} by other commands are -lumped together, so the deleted text gets accumulated and can be put back -as one chunk. If you want to break a sequence of deletions so that the -newly deleted text could be put back separately from the previously deleted -text, you should perform a non-deleting action, e.g., move the cursor one -character in any direction. - -@cindex shifting text - -@table @kbd -@item x -Delete chars under and after the cursor. -@item X -Delete chars before the cursor. -@item d -Delete from point to endpoint of . -@item dd -Delete lines. -@item D -The rest of the line. -@item < -Shift the lines described by one -shiftwidth to the left (layout!). -@item << -Shift lines one shiftwidth to the left. -@end table -@kindex @kbd{<<} -@kindex @kbd{<} -@kindex @kbd{D} -@kindex @kbd{dd} -@kindex @kbd{d} -@kindex @kbd{X} -@kindex @kbd{x} - -@node Changing Text, Search and Replace, Deleting Text,Text Handling -@subsection Changing Text - -@cindex joining lines -@cindex changing case -@cindex quoting regions -@cindex substitution - -@table @kbd -@item r -Replace chars by - no . -@item R -Overwrite the rest of the line, -appending change @var{count - 1} times. -@item s -Substitute chars. -@item S -Change lines. -@item c -Change from begin to endpoint of . -@item cc -Change lines. -@item C -The rest of the line and - 1 next lines. -@item = -Reindent the region described by move. -@item ~ -Switch lower and upper cases. -@item J -Join lines (default 2). -@item :[x,y]s/// -Substitute (on lines x through y) the pattern - (default the last pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e.@: change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n} ). Instead of @kbd{/} any -punctuation CHAR unequal to and can be used as -delimiter. - -In Emacs, @samp{\&} stands for the last matched expression, so -@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}. -Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead. - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item :[x,y]copy [z] -Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item :[x,y]t [z] -Same as @kbd{:copy}. -@item :[x,y]move [z] -Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}. -@item & -Repeat latest Ex substitute command, e.g. -@kbd{:s/wrong/right}. -@item :x,yp -@itemx :g/Pat/p -@itemx :v/Pat/p -The above commands display certain buffer lines in a -temporary buffer. The first form above displays the buffer lines between -@kbd{x} and @kbd{y}. The second displays the lines of the buffer, which -match a given pattern. The third form displays the lines that do @emph{not} -match the given pattern. -@item #c -Change upper-case characters in the region to lower-case. -@item #C -Change lower-case characters in the region to upper-case. -@item #q -Insert specified string at the beginning of each line in the region -@item C-c M-p and C-c M-n -In Insert and Replace states, these keys are bound to commands that peruse -the history of the text -previously inserted in other insert or replace commands. By repeatedly typing -@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to -insert these previously used strings one by one. -When a new string is inserted, the previous one is deleted. - -In Vi state, these keys are bound to functions that peruse the history of -destructive Vi commands. -@xref{Viper Specials}, for details. -@end table -@kindex @kbd{C-c M-p} -@kindex @kbd{C-c M-n} -@kindex @kbd{#q } -@kindex @kbd{#C} -@kindex @kbd{#c} -@kindex @kbd{&} -@kindex @kbd{\&} -@findex @kbd{:substitute///} -@findex @kbd{:s///} -@findex @kbd{:copy [z]} -@findex @kbd{:t [z]} -@findex @kbd{:move [z]} -@kindex @kbd{J} -@kindex @kbd{~} -@kindex @kbd{=} -@kindex @kbd{C} -@kindex @kbd{cc} -@kindex @kbd{c} -@kindex @kbd{S} -@kindex @kbd{s} -@kindex @kbd{R} -@kindex @kbd{r} - -@node Search and Replace, Yanking, Changing Text,Text Handling -@subsection Search and Replace - -@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to -get literal (non-regular-expression) search and how to stop search from -wrapping around. - -@table @kbd -@item C-c / -Toggle case-sensitive search. With prefix argument, toggle vanilla/regular -expression search. -@item / -To the th occurrence of . - -Viper does not parse search patterns and does not expand special symbols -found there (e.g., @samp{~} is not expanded to the result of the previous -substitution). - -@item ? -To the th previous occurrence of . -@item g -Search for the text described by move. (off by default) -@item n -Repeat latest @kbd{/} @kbd{?} (next). -@item N -Idem in opposite direction. -@item % -Find the next bracket and go to its match -@item :[x,y]g// -@cindex text processing -Search globally [from line x to y] for -and execute the Ex on each occurrence. -@item :[x,y]v// -Execute on the lines that don't match. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item Q -Query Replace. -@item :ta -Search in the tags file where is defined (file, line), and go to it. -@item :[x,y]s/// -Substitute (on lines x through y) the pattern (default the last -pattern) with . Useful -flags are @samp{g} for @samp{global} (i.e.@: change every -non-overlapping occurrence of ) and @samp{c} for -@samp{confirm} (type @samp{y} to confirm a particular -substitution, else @samp{n}). Instead of @kbd{/} any -punctuation character other than and can be used as -delimiter. - -Note: @emph{The newline character (inserted as @kbd{C-qC-j}) -can be used in }. -@item & -Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}. -@item :global // -@itemx :g // -Execute on all lines that match . -@item :vglobal // -@itemx :v // -Execute on all lines that do not match . -@end table -@kindex @kbd{&} -@findex @kbd{:substitute///} -@kindex @kbd{Q} -@kindex @kbd{#g} -@findex @kbd{:v} -@findex @kbd{:g} -@findex @kbd{:global} -@findex @kbd{:vglobal} -@findex @kbd{:tag } -@kindex @kbd{%} -@kindex @kbd{N} -@kindex @kbd{n} -@kindex @kbd{g} -@kindex @kbd{?} -@kindex @kbd{/} - -@node Yanking,Undoing,Search and Replace,Text Handling -@subsection Yanking - -@cindex cut and paste -@cindex paste - -@table @kbd -@item y -Yank from begin to endpoint of . -@item "y -Yank from begin to endpoint of to register. -@item "y -Yank from begin to endpoint of and append -to register. -@item yy - lines. -@item Y -Idem (should be equivalent to @kbd{y$} though). -@item m -Mark the cursor position with a letter. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@item ["]p -Put the contents of the (default undo) buffer - times after the cursor. The register will -be automatically down-cased. -@item ["]P -Put the contents of the (default undo) buffer - times before the cursor. The register will -@end table -@kindex @kbd{P} -@kindex @kbd{p} -@kindex @kbd{"p} -@kindex @kbd{"P} -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{m} -@kindex @kbd{Y} -@kindex @kbd{yy} -@kindex @kbd{"y} -@kindex @kbd{"y} -@kindex @kbd{y} -@kindex @kbd{yank} -@findex @kbd{:yank} - -@node Undoing,, Yanking,Text Handling -@subsection Undoing - -@cindex undo -@cindex backup files - -@table @kbd -@item u U -Undo the latest change. -@item . -Repeat undo. -@item :q! -Quit Vi without writing. -@item :e! -Re-edit a messed-up file. -@item :rec -Recover file from autosave. Viper also creates backup files -that have a @samp{~} appended to them. -@end table -@findex @kbd{:rec} -@findex @kbd{:e!} -@findex @kbd{:q!} -@kindex @kbd{.} -@kindex @kbd{U} -@kindex @kbd{u} - -@node Display, File and Buffer Handling, Text Handling, Commands -@section Display - -@cindex scrolling - -@table @kbd -@item C-g -At user level 1, -give file name, status, current line number -and relative position.@* -At user levels 2 and higher, abort the current command. -@item C-c g -Give file name, status, current line number and relative position -- all -user levels. -@item C-l -Refresh the screen. -@item C-e -Expose more lines at bottom, cursor stays put (if possible). -@item C-y -Expose more lines at top, cursor stays put (if possible). -@item C-d -Scroll lines downward (default the number of the previous scroll; -initialization: half a page). -@item C-u -Scroll lines upward (default the number of the previous scroll; -initialization: half a page). -@item C-f - pages forward. -@item C-b - pages backward (in older versions @kbd{C-b} only works without count). -@item z -@item zH -Put line at the top of the window (default the current line). -@item z- -@item zL -Put line at the bottom of the window -(default the current line). -@item z. -@item zM -Put line in the center of the window -(default the current line). -@end table -@kindex @kbd{zM} -@kindex @kbd{zL} -@kindex @kbd{zH} -@kindex @kbd{z} -@kindex @kbd{z.} -@kindex @kbd{z-} -@kindex @kbd{z} -@kindex @kbd{C-b} -@kindex @kbd{C-f} -@kindex @kbd{C-u} -@kindex @kbd{C-d} -@kindex @kbd{C-y} -@kindex @kbd{C-e} -@kindex @kbd{C-l} -@kindex @kbd{C-g} - - -@node File and Buffer Handling, Mapping, Display,Commands -@section File and Buffer Handling - -@cindex multiple files - -In all file handling commands, space should be typed before entering the file -name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't -put any space between the command and the modifier. - -Note that many Ex commands, e.g., @kbd{:w}, accept command arguments. The -effect is that the command would start acting on the current region. For -instance, if the current region spans the lines 11 through 22, then if you -type @kbd{1:w} you would see @samp{:11,22w} in the minibuffer. - -@table @kbd -@item :q -Quit buffer except if modified. -@item :q! -Quit buffer without checking. In Viper, these two commands -are identical. Confirmation is required if exiting modified buffers that -visit files. -@item :suspend -@item :stop -Suspend Viper -@item :[x,y] w -Write the file. Viper makes sure that a final newline is always added to -any file where this newline is missing. This is done by setting Emacs -variable @code{require-final-newline} to @code{t}. If you don't like this -feature, use @code{setq-default} to set @code{require-final-newline} to -@code{nil}. This must be done in @file{.viper} file. -@item :[x,y] w -Write to the file . -@item :[x,y] w>> -Append the buffer to the file . There should be no space between -@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens. -@item :w!@: -Overwrite the file . In Viper, @kbd{:w} and @kbd{:w!} are identical. -Confirmation is required for writing to an existing file (if this is not -the file the buffer is visiting) or to a read-only file. -@item :x,y w -Write lines x through y to the file . -@item :wq -Write the file and kill buffer. -@item :r [ ...] -Read file into a buffer, inserting its contents after the current line. -@item :xit -Same as @kbd{:wq}. -@item :Write -@itemx :W -Save all unsaved buffers, asking for confirmation. -@item :WWrite -@itemx :WW -Like @kbd{W}, but without asking for confirmation. -@item ZZ -Save current buffer and kill it. If user level is 1, then save all files -and kill Emacs. Killing Emacs is the wrong way to use it, so you should -switch to higher user levels as soon as possible. -@item :x [] -Save and kill buffer. -@item :x!@: [] -@kbd{:w![]} and @kbd{:q}. -@item :pre -Preserve the file -- autosave buffers. -@item :rec -Recover file from autosave. -@item :f [] -without the argument, prints file name and character/line information afout -the currently visited file. With an argument, sets the currently visited -filename to @file{file}. -@item :cd [] -Set the working directory to (default home directory). -@item :pwd -Print present working directory. -@item :e [+] -Edit files. If no filename is given, edit the file visited by the current -buffer. If buffer was modified or the file changed on disk, ask for -confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments. -The first file is edited the same way as in Vi. The rest are visited -in the usual Emacs way. -@item :e!@: [+] -Re-edit file. If no filename, re-edit current file. -In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the -user is asked to confirm if there is a danger of discarding changes to a -buffer. -@item :q! -Quit Vi without writing. -@item C-^ -Edit the alternate (normally the previous) file. -@item :rew -Obsolete -@item :args -List files not shown anywhere with counts for next -@item :n [count] [+] [] -Edit file, or edit files. The count comes from @kbd{:args}. -@item :N [count] [+] [] -Like @kbd{:n}, but the meaning of the variable -@var{ex-cycle-other-window} is reversed. -@item :b -Switch to another buffer. If @var{ex-cycle-other-window} is @code{t}, -switch in another window. Buffer completion is supported. -The variable @var{viper-read-buffer-function} controls which function is -actually used to read the buffer name. The default is @code{read-buffer}, -but better alternatives are also available in Emacs (e.g., -@code{iswitchb-read-buffer}). -@vindex @var{viper-read-buffer-function} -@item :B -Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. -@item :
r -Read the file into the buffer after the line
. -@item v, V, C-v -Edit a file in current or another window, or in another frame. File name -is typed in Minibuffer. File completion and history are supported. -@end table -@kindex @kbd{v} -@kindex @kbd{V} -@findex @kbd{:args} -@findex @kbd{:rew} -@kindex @kbd{C-^} -@findex @kbd{:e!@: []} -@findex @kbd{:e []} -@findex @kbd{:edit []} -@findex @kbd{:edit!@: []} -@findex @kbd{:q!} -@findex @kbd{:q} -@findex @kbd{:quit} -@findex @kbd{:quit!} -@findex @kbd{:f} -@findex @kbd{:rec} -@findex @kbd{:r} -@findex @kbd{:read} -@findex @kbd{:pre} -@kindex @kbd{ZZ} -@findex @kbd{:wq} -@findex @kbd{:w } -@findex @kbd{:w!@: } -@findex @kbd{:w >> } -@findex @kbd{:write } -@findex @kbd{:write!@: } -@findex @kbd{:write >> } -@findex @kbd{:W} -@findex @kbd{:WW} -@findex @kbd{:Write} -@findex @kbd{:WWrite} -@findex @kbd{:WWrite} -@findex @kbd{:x} -@findex @kbd{:x!} -@findex @kbd{:suspend} -@findex @kbd{:stop} -@findex @kbd{:n [ | ]} -@findex @kbd{:cd []} -@findex @kbd{:pwd} - -@node Mapping, Shell Commands, File and Buffer Handling, Commands -@section Mapping - -@cindex key bindings -@cindex key mapping - -@table @kbd -@item :map -Start defining a Vi-style keyboard macro. -For instance, typing -@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )} -will cause @kbd{www} to run wc on -current file (Vi replaces @samp{%} with the current file name). -@item C-x ) -Finish defining a keyboard macro. -In Viper, this command completes the process of defining all keyboard -macros, whether they are Emacs-style or Vi-style. -This is a departure from Vi, needed to allow WYSIWYG mapping of -keyboard macros and to permit the use of function keys and arbitrary Emacs -functions in the macros. -@item :unmap -Deprive of its mappings in Vi state. -@item :map!@: -Map a macro for Insert state. -@item :unmap!@: -Deprive of its mapping in Insert state (see @kbd{:unmap}). -@item @@ -In Vi state, -execute the contents of register as a command. -@item @@@@ -In Vi state, -repeat last register command. -@item @@# -In Vi state, -begin keyboard macro. End with @@. This will -put the macro in the proper register. Register will -be automatically down-cased. -@xref{Macros and Registers}, for more info. -@item @@! -In Vi state, -yank anonymous macro to register -@item * -In Vi state, -execute anonymous macro (defined by C-x( and C-x )). -@item C-x e -Like @kbd{*}, but works in all Viper states. -@item #g -Execute the last keyboard macro for each line in the region. -@xref{Macros and Registers}, for more info. -@item [ -Show contents of textmarker. -@item ] -Show contents of register. -@end table -@kindex @kbd{]} -@kindex @kbd{[} -@kindex @kbd{#g} -@kindex @kbd{*} -@kindex @kbd{@@!} -@kindex @kbd{@@#} -@kindex @kbd{@@@@} -@kindex @kbd{@@} -@findex @kbd{:unmap } -@findex @kbd{:map } -@findex @kbd{:unmap!@: } -@findex @kbd{:map!@: } - -@node Shell Commands, Options, Mapping, Commands -@section Shell Commands - -@cindex % (Current file) - -The symbol @samp{%} is used in Ex shell commands to mean current file. If -you want a @samp{%} in your command, it must be escaped as @samp{\%}. -@cindex @samp{%} (Ex address) -However if @samp{%} is the first character, it stands as the address for -the whole file. -@cindex @samp{#} (Previous file) -Similarly, @samp{#} expands to the previous file. The previous file is the -first file in @kbd{:args} listing. This defaults to the previous file in -the VI sense if you have one window.@refill - -Symbols @samp{%} and @samp{#} are also used in the Ex commands @kbd{:e} and -@kbd{:r }. The commands @kbd{:w} and the regular @kbd{:r -} command don't support these meta symbols, because file history is a -better mechanism. - -@cindex shell commands - -@table @kbd -@item :sh -Execute a subshell in another window -@item :[x,y]! -Execute a shell [on lines x through y; -% is replace by current file, \% is changed to % -@item :[x,y]!!@: [] -Repeat last shell command [and append ]. -@item :! -Just execute command and display result in a buffer. -@item :!!@: -Repeat last shell command and append -@item ! -The shell executes , with standard -input the lines described by , -next the standard output replaces those lines -(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.). -@item !! -Give lines as standard input to the -shell , next let the standard output -replace those lines. -@item :[x,y] w ! -Let lines x to y be standard input for -(notice the between @kbd{w} and @kbd{!}). -@item :
r ! -Put the output of after the line
(default current). -@item :
r -Read the file into the buffer after the line
(default -current). -@item :make -Run the make command in the current directory. -@end table -@findex @kbd{:
r } -@findex @kbd{:
r !} -@findex @kbd{!} -@findex @kbd{!!} -@findex @kbd{!} -@findex @kbd{:w !} -@findex @kbd{:x,y w !} -@findex @kbd{:!!@: } -@findex @kbd{:!} -@findex @kbd{:sh} -@findex @kbd{:make} - -@node Options,Emacs Related Commands,Shell Commands,Commands -@section Options - -@cindex Vi options - -@table @kbd -@item autoindent -@itemx ai -@cindex autoindent -autoindent -- In append mode after a the -cursor will move directly below the first -character on the previous line. -This setting affects the current buffer only. -@item autoindent-global -@itemx ai-global -Same as `autoindent', but affects all buffers. -@item noautoindent -@itemx noai -Cancel autoindent. -@item noautoindent-global -@itemx noai-g -Cancel autoindent-global. -@item ignorecase -@itemx ic -@cindex case and searching -ignorecase -- No distinction between upper and lower cases when searching. -@item noignorecase -@itemx noic -Cancel ignorecase. -@item magic -@itemx ma -@cindex literal searching -Regular expressions used in searches; nomagic means no regexps. -@item nomagic -@item noma -Cancel magic. -@item readonly -@itemx ro -@cindex readonly files -readonly -- The file is not to be changed. -If the user attempts to write to this file, confirmation will be requested. -@item noreadonly -@itemx noro -Cancel readonly. -@item shell= -@itemx sh= -@cindex shell -shell -- The program to be used for shell escapes -(default @samp{$SHELL} (default @file{/bin/sh})). -@item shiftwidth= -@itemx sw= -@cindex layout -@cindex shifting text -shiftwidth -- Gives the shiftwidth (default 8 positions). -@item showmatch -@itemx sm -@cindex paren matching -@cindex matching parens -showmatch -- Whenever you append a @kbd{)}, Vi shows -its match if it's on the same page; also with -@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep. -@item noshowmatch -@itemx nosm -Cancel showmatch. -@item tabstop= -@itemx ts= -@cindex changing tab width -@cindex tabbing -tabstop -- The length of a ; warning: this is -only IN the editor, outside of it s have -their normal length (default 8 positions). -This setting affects the current buffer only. -@item tabstop-global -@itemx ts-g -Same as `tabstop', but affects all buffers. -@item wrapmargin= -@itemx wm= -@cindex auto fill -@cindex word wrap -wrapmargin -- In append mode Vi automatically -puts a whenever there is a or -within columns from the right margin. -@item wrapscan -@itemx ws -@cindex searching -wrapscan -- When searching, the end is -considered @samp{stuck} to the begin of the file. -@item nowrapscan -@itemx nows -Cancel wrapscan. -@item :set see also somename. In the same way see also URL where URL is a filename relative to current +directory, or absolute as in `http://www.cs.indiana.edu/elisp/w3/docs.html'. + +Images in many formats can be inlined with . + +If you mainly create your own documents, `sgml-specials' might be +interesting. But note that some HTML 2 browsers can't handle `''. +To work around that, do: + (eval-after-load \"sgml-mode\" '(aset sgml-char-names ?' nil)) + +\\{html-mode-map} + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (sh-mode) "sh-script" "progmodes/sh-script.el" +;;;;;; (19005 47404)) +;;; Generated autoloads from progmodes/sh-script.el +(put 'sh-shell 'safe-local-variable 'symbolp) + +(autoload 'sh-mode "sh-script" "\ +Major mode for editing shell scripts. +This mode works for many shells, since they all have roughly the same syntax, +as far as commands, arguments, variables, pipes, comments etc. are concerned. +Unless the file's magic number indicates the shell, your usual shell is +assumed. Since filenames rarely give a clue, they are not further analyzed. + +This mode adapts to the variations between shells (see `sh-set-shell') by +means of an inheritance based feature lookup (see `sh-feature'). This +mechanism applies to all variables (including skeletons) that pertain to +shell-specific features. + +The default style of this mode is that of Rosenblatt's Korn shell book. +The syntax of the statements varies with the shell being used. The +following commands are available, based on the current shell's syntax: +\\ +\\[sh-case] case statement +\\[sh-for] for loop +\\[sh-function] function definition +\\[sh-if] if statement +\\[sh-indexed-loop] indexed loop from 1 to n +\\[sh-while-getopts] while getopts loop +\\[sh-repeat] repeat loop +\\[sh-select] select loop +\\[sh-until] until loop +\\[sh-while] while loop + +For sh and rc shells indentation commands are: +\\[sh-show-indent] Show the variable controlling this line's indentation. +\\[sh-set-indent] Set then variable controlling this line's indentation. +\\[sh-learn-line-indent] Change the indentation variable so this line +would indent to the way it currently is. +\\[sh-learn-buffer-indent] Set the indentation variables so the +buffer indents as it currently is indented. + + +\\[backward-delete-char-untabify] Delete backward one position, even if it was a tab. +\\[newline-and-indent] Delete unquoted space and indent new line same as this one. +\\[sh-end-of-command] Go to end of successive commands. +\\[sh-beginning-of-command] Go to beginning of successive commands. +\\[sh-set-shell] Set this buffer's shell, and maybe its magic number. +\\[sh-execute-region] Have optional header and region be executed in a subshell. + +\\[sh-maybe-here-document] Without prefix, following an unquoted < inserts here document. +{, (, [, ', \", ` + Unless quoted with \\, insert the pairs {}, (), [], or '', \"\", ``. + +If you generally program a shell different from your login shell you can +set `sh-shell-file' accordingly. If your shell's file name doesn't correctly +indicate what shell it is use `sh-alias-alist' to translate. + +If your shell gives error messages with line numbers, you can use \\[executable-interpret] +with your script for an edit-interpret-debug cycle. + +\(fn)" t nil) + +(defalias 'shell-script-mode 'sh-mode) + +;;;*** + +;;;### (autoloads (sha1) "sha1" "sha1.el" (18785 31824)) +;;; Generated autoloads from sha1.el + +(autoload 'sha1 "sha1" "\ +Return the SHA1 (Secure Hash Algorithm) of an object. +OBJECT is either a string or a buffer. +Optional arguments BEG and END denote buffer positions for computing the +hash of a portion of OBJECT. +If BINARY is non-nil, return a string in binary form. + +\(fn OBJECT &optional BEG END BINARY)" nil nil) + +;;;*** + +;;;### (autoloads (list-load-path-shadows) "shadow" "emacs-lisp/shadow.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emacs-lisp/shadow.el + +(autoload 'list-load-path-shadows "shadow" "\ +Display a list of Emacs Lisp files that shadow other files. + +This function lists potential load path problems. Directories in +the `load-path' variable are searched, in order, for Emacs Lisp +files. When a previously encountered file name is found again, a +message is displayed indicating that the later file is \"hidden\" by +the earlier. + +For example, suppose `load-path' is set to + +\(\"/usr/gnu/emacs/site-lisp\" \"/usr/gnu/emacs/share/emacs/19.30/lisp\") + +and that each of these directories contains a file called XXX.el. Then +XXX.el in the site-lisp directory is referred to by all of: +\(require 'XXX), (autoload .... \"XXX\"), (load-library \"XXX\") etc. + +The first XXX.el file prevents Emacs from seeing the second (unless +the second is loaded explicitly via `load-file'). + +When not intended, such shadowings can be the source of subtle +problems. For example, the above situation may have arisen because the +XXX package was not distributed with versions of Emacs prior to +19.30. An Emacs maintainer downloaded XXX from elsewhere and installed +it. Later, XXX was updated and included in the Emacs distribution. +Unless the Emacs maintainer checks for this, the new version of XXX +will be hidden behind the old (which may no longer work with the new +Emacs version). + +This function performs these checks and flags all possible +shadowings. Because a .el file may exist without a corresponding .elc +\(or vice-versa), these suffixes are essentially ignored. A file +XXX.elc in an early directory (that does not contain XXX.el) is +considered to shadow a later file XXX.el, and vice-versa. + +When run interactively, the shadowings (if any) are displayed in a +buffer called `*Shadows*'. Shadowings are located by calling the +\(non-interactive) companion function, `find-emacs-lisp-shadows'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (shadow-initialize shadow-define-regexp-group shadow-define-literal-group +;;;;;; shadow-define-cluster) "shadowfile" "shadowfile.el" (19005 +;;;;;; 47386)) +;;; Generated autoloads from shadowfile.el + +(autoload 'shadow-define-cluster "shadowfile" "\ +Edit (or create) the definition of a cluster NAME. +This is a group of hosts that share directories, so that copying to or from +one of them is sufficient to update the file on all of them. Clusters are +defined by a name, the network address of a primary host (the one we copy +files to), and a regular expression that matches the hostnames of all the +sites in the cluster. + +\(fn NAME)" t nil) + +(autoload 'shadow-define-literal-group "shadowfile" "\ +Declare a single file to be shared between sites. +It may have different filenames on each site. When this file is edited, the +new version will be copied to each of the other locations. Sites can be +specific hostnames, or names of clusters (see `shadow-define-cluster'). + +\(fn)" t nil) + +(autoload 'shadow-define-regexp-group "shadowfile" "\ +Make each of a group of files be shared between hosts. +Prompts for regular expression; files matching this are shared between a list +of sites, which are also prompted for. The filenames must be identical on all +hosts (if they aren't, use `shadow-define-literal-group' instead of this +function). Each site can be either a hostname or the name of a cluster (see +`shadow-define-cluster'). + +\(fn)" t nil) + +(autoload 'shadow-initialize "shadowfile" "\ +Set up file shadowing. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (shell shell-dumb-shell-regexp) "shell" "shell.el" +;;;;;; (19005 47386)) +;;; Generated autoloads from shell.el + +(defvar shell-dumb-shell-regexp "cmd\\(proxy\\)?\\.exe" "\ +Regexp to match shells that don't save their command history, and +don't handle the backslash as a quote character. For shells that +match this regexp, Emacs will write out the command history when the +shell finishes, and won't remove backslashes when it unquotes shell +arguments.") + +(custom-autoload 'shell-dumb-shell-regexp "shell" t) + +(autoload 'shell "shell" "\ +Run an inferior shell, with I/O through BUFFER (which defaults to `*shell*'). +Interactively, a prefix arg means to prompt for BUFFER. +If `default-directory' is a remote file name, it is also prompted +to change if called with a prefix arg. + +If BUFFER exists but shell process is not running, make new shell. +If BUFFER exists and shell process is running, just switch to BUFFER. +Program used comes from variable `explicit-shell-file-name', + or (if that is nil) from the ESHELL environment variable, + or (if that is nil) from `shell-file-name'. +If a file `~/.emacs_SHELLNAME' exists, or `~/.emacs.d/init_SHELLNAME.sh', +it is given as initial input (but this may be lost, due to a timing +error, if the shell discards input when it starts up). +The buffer is put in Shell mode, giving commands for sending input +and controlling the subjobs of the shell. See `shell-mode'. +See also the variable `shell-prompt-pattern'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the shell, use \\[universal-coding-system-argument] +before \\[shell]. You can also specify this with \\[set-buffer-process-coding-system] +in the shell buffer, after you start the shell. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +The shell file name (sans directories) is used to make a symbol name +such as `explicit-csh-args'. If that symbol is a variable, +its value is used as a list of arguments when invoking the shell. +Otherwise, one argument `-i' is passed to the shell. + +\(Type \\[describe-mode] in the shell buffer for a list of commands.) + +\(fn &optional BUFFER)" t nil) + (add-hook 'same-window-buffer-names "*shell*") + +;;;*** + +;;;### (autoloads (sieve-upload-and-bury sieve-upload sieve-manage) +;;;;;; "sieve" "gnus/sieve.el" (19005 47394)) +;;; Generated autoloads from gnus/sieve.el + +(autoload 'sieve-manage "sieve" "\ +Not documented + +\(fn SERVER &optional PORT)" t nil) + +(autoload 'sieve-upload "sieve" "\ +Not documented + +\(fn &optional NAME)" t nil) + +(autoload 'sieve-upload-and-bury "sieve" "\ +Not documented + +\(fn &optional NAME)" t nil) + +;;;*** + +;;;### (autoloads (sieve-mode) "sieve-mode" "gnus/sieve-mode.el" +;;;;;; (19005 47394)) +;;; Generated autoloads from gnus/sieve-mode.el + +(autoload 'sieve-mode "sieve-mode" "\ +Major mode for editing Sieve code. +This is much like C mode except for the syntax of comments. Its keymap +inherits from C mode's and it has the same variables for customizing +indentation. It has its own abbrev table and its own syntax table. + +Turning on Sieve mode runs `sieve-mode-hook'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (simula-mode) "simula" "progmodes/simula.el" (19005 +;;;;;; 47404)) +;;; Generated autoloads from progmodes/simula.el + +(autoload 'simula-mode "simula" "\ +Major mode for editing SIMULA code. +\\{simula-mode-map} +Variables controlling indentation style: + `simula-tab-always-indent' + Non-nil means TAB in SIMULA mode should always reindent the current line, + regardless of where in the line point is when the TAB command is used. + `simula-indent-level' + Indentation of SIMULA statements with respect to containing block. + `simula-substatement-offset' + Extra indentation after DO, THEN, ELSE, WHEN and OTHERWISE. + `simula-continued-statement-offset' 3 + Extra indentation for lines not starting a statement or substatement, + e.g. a nested FOR-loop. If value is a list, each line in a multiple- + line continued statement will have the car of the list extra indentation + with respect to the previous line of the statement. + `simula-label-offset' -4711 + Offset of SIMULA label lines relative to usual indentation. + `simula-if-indent' '(0 . 0) + Extra indentation of THEN and ELSE with respect to the starting IF. + Value is a cons cell, the car is extra THEN indentation and the cdr + extra ELSE indentation. IF after ELSE is indented as the starting IF. + `simula-inspect-indent' '(0 . 0) + Extra indentation of WHEN and OTHERWISE with respect to the + corresponding INSPECT. Value is a cons cell, the car is + extra WHEN indentation and the cdr extra OTHERWISE indentation. + `simula-electric-indent' nil + If this variable is non-nil, `simula-indent-line' + will check the previous line to see if it has to be reindented. + `simula-abbrev-keyword' 'upcase + Determine how SIMULA keywords will be expanded. Value is one of + the symbols `upcase', `downcase', `capitalize', (as in) `abbrev-table', + or nil if they should not be changed. + `simula-abbrev-stdproc' 'abbrev-table + Determine how standard SIMULA procedure and class names will be + expanded. Value is one of the symbols `upcase', `downcase', `capitalize', + (as in) `abbrev-table', or nil if they should not be changed. + +Turning on SIMULA mode calls the value of the variable simula-mode-hook +with no arguments, if that value is non-nil. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (skeleton-pair-insert-maybe skeleton-insert skeleton-proxy-new +;;;;;; define-skeleton) "skeleton" "skeleton.el" (19005 47386)) +;;; Generated autoloads from skeleton.el + +(defvar skeleton-filter-function 'identity "\ +Function for transforming a skeleton proxy's aliases' variable value.") + +(autoload 'define-skeleton "skeleton" "\ +Define a user-configurable COMMAND that enters a statement skeleton. +DOCUMENTATION is that of the command. +SKELETON is as defined under `skeleton-insert'. + +\(fn COMMAND DOCUMENTATION &rest SKELETON)" nil (quote macro)) + +(autoload 'skeleton-proxy-new "skeleton" "\ +Insert SKELETON. +Prefix ARG allows wrapping around words or regions (see `skeleton-insert'). +If no ARG was given, but the region is visible, ARG defaults to -1 depending +on `skeleton-autowrap'. An ARG of M-0 will prevent this just for once. +This command can also be an abbrev expansion (3rd and 4th columns in +\\[edit-abbrevs] buffer: \"\" command-name). + +Optional second argument STR may also be a string which will be the value +of `str' whereas the skeleton's interactor is then ignored. + +\(fn SKELETON &optional STR ARG)" nil nil) + +(autoload 'skeleton-insert "skeleton" "\ +Insert the complex statement skeleton SKELETON describes very concisely. + +With optional second argument REGIONS, wrap first interesting point +\(`_') in skeleton around next REGIONS words, if REGIONS is positive. +If REGIONS is negative, wrap REGIONS preceding interregions into first +REGIONS interesting positions (successive `_'s) in skeleton. + +An interregion is the stretch of text between two contiguous marked +points. If you marked A B C [] (where [] is the cursor) in +alphabetical order, the 3 interregions are simply the last 3 regions. +But if you marked B A [] C, the interregions are B-A, A-[], []-C. + +The optional third argument STR, if specified, is the value for the +variable `str' within the skeleton. When this is non-nil, the +interactor gets ignored, and this should be a valid skeleton element. + +SKELETON is made up as (INTERACTOR ELEMENT ...). INTERACTOR may be nil if +not needed, a prompt-string or an expression for complex read functions. + +If ELEMENT is a string or a character it gets inserted (see also +`skeleton-transformation-function'). Other possibilities are: + + \\n go to next line and indent according to mode + _ interesting point, interregion here + - interesting point, no interregion interaction, overrides + interesting point set by _ + > indent line (or interregion if > _) according to major mode + @ add position to `skeleton-positions' + & do next ELEMENT if previous moved point + | do next ELEMENT if previous didn't move point + -num delete num preceding characters (see `skeleton-untabify') + resume: skipped, continue here if quit is signaled + nil skipped + +After termination, point will be positioned at the last occurrence of - +or at the first occurrence of _ or at the end of the inserted text. + +Further elements can be defined via `skeleton-further-elements'. ELEMENT may +itself be a SKELETON with an INTERACTOR. The user is prompted repeatedly for +different inputs. The SKELETON is processed as often as the user enters a +non-empty string. \\[keyboard-quit] terminates skeleton insertion, but +continues after `resume:' and positions at `_' if any. If INTERACTOR in such +a subskeleton is a prompt-string which contains a \".. %s ..\" it is +formatted with `skeleton-subprompt'. Such an INTERACTOR may also be a list of +strings with the subskeleton being repeated once for each string. + +Quoted Lisp expressions are evaluated for their side-effects. +Other Lisp expressions are evaluated and the value treated as above. +Note that expressions may not return t since this implies an +endless loop. Modes can define other symbols by locally setting them +to any valid skeleton element. The following local variables are +available: + + str first time: read a string according to INTERACTOR + then: insert previously read string once more + help help-form during interaction with the user or nil + input initial input (string or cons with index) while reading str + v1, v2 local variables for memorizing anything you want + +When done with skeleton, but before going back to `_'-point call +`skeleton-end-hook' if that is non-nil. + +\(fn SKELETON &optional REGIONS STR)" nil nil) + +(autoload 'skeleton-pair-insert-maybe "skeleton" "\ +Insert the character you type ARG times. + +With no ARG, if `skeleton-pair' is non-nil, pairing can occur. If the region +is visible the pair is wrapped around it depending on `skeleton-autowrap'. +Else, if `skeleton-pair-on-word' is non-nil or we are not before or inside a +word, and if `skeleton-pair-filter-function' returns nil, pairing is performed. +Pairing is also prohibited if we are right after a quoting character +such as backslash. + +If a match is found in `skeleton-pair-alist', that is inserted, else +the defaults are used. These are (), [], {}, <> and `' for the +symmetrical ones, and the same character twice for the others. + +\(fn ARG)" t nil) + +;;;*** + +;;;### (autoloads (smerge-start-session smerge-mode smerge-ediff) +;;;;;; "smerge-mode" "smerge-mode.el" (19005 47386)) +;;; Generated autoloads from smerge-mode.el + +(autoload 'smerge-ediff "smerge-mode" "\ +Invoke ediff to resolve the conflicts. +NAME-MINE, NAME-OTHER, and NAME-BASE, if non-nil, are used for the +buffer names. + +\(fn &optional NAME-MINE NAME-OTHER NAME-BASE)" t nil) + +(autoload 'smerge-mode "smerge-mode" "\ +Minor mode to simplify editing output from the diff3 program. +\\{smerge-mode-map} + +\(fn &optional ARG)" t nil) + +(autoload 'smerge-start-session "smerge-mode" "\ +Turn on `smerge-mode' and move point to first conflict marker. +If no conflict maker is found, turn off `smerge-mode'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (smiley-buffer smiley-region) "smiley" "gnus/smiley.el" +;;;;;; (19005 47394)) +;;; Generated autoloads from gnus/smiley.el + +(autoload 'smiley-region "smiley" "\ +Replace in the region `smiley-regexp-alist' matches with corresponding images. +A list of images is returned. + +\(fn START END)" t nil) + +(autoload 'smiley-buffer "smiley" "\ +Run `smiley-region' at the buffer, specified in the argument or +interactively. If there's no argument, do it at the current buffer + +\(fn &optional BUFFER)" t nil) + +;;;*** + +;;;### (autoloads (smtpmail-send-queued-mail smtpmail-send-it) "smtpmail" +;;;;;; "mail/smtpmail.el" (19005 47398)) +;;; Generated autoloads from mail/smtpmail.el + +(autoload 'smtpmail-send-it "smtpmail" "\ +Not documented + +\(fn)" nil nil) + +(autoload 'smtpmail-send-queued-mail "smtpmail" "\ +Send mail that was queued as a result of setting `smtpmail-queue-mail'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (snake) "snake" "play/snake.el" (19005 47402)) +;;; Generated autoloads from play/snake.el + +(autoload 'snake "snake" "\ +Play the Snake game. +Move the snake around without colliding with its tail or with the border. + +Eating dots causes the snake to get longer. + +Snake mode keybindings: + \\ +\\[snake-start-game] Starts a new game of Snake +\\[snake-end-game] Terminates the current game +\\[snake-pause-game] Pauses (or resumes) the current game +\\[snake-move-left] Makes the snake move left +\\[snake-move-right] Makes the snake move right +\\[snake-move-up] Makes the snake move up +\\[snake-move-down] Makes the snake move down + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (snmpv2-mode snmp-mode) "snmp-mode" "net/snmp-mode.el" +;;;;;; (19005 47400)) +;;; Generated autoloads from net/snmp-mode.el + +(autoload 'snmp-mode "snmp-mode" "\ +Major mode for editing SNMP MIBs. +Expression and list commands understand all C brackets. +Tab indents for C code. +Comments start with -- and end with newline or another --. +Delete converts tabs to spaces as it moves back. +\\{snmp-mode-map} +Turning on snmp-mode runs the hooks in `snmp-common-mode-hook', then +`snmp-mode-hook'. + +\(fn)" t nil) + +(autoload 'snmpv2-mode "snmp-mode" "\ +Major mode for editing SNMPv2 MIBs. +Expression and list commands understand all C brackets. +Tab indents for C code. +Comments start with -- and end with newline or another --. +Delete converts tabs to spaces as it moves back. +\\{snmp-mode-map} +Turning on snmp-mode runs the hooks in `snmp-common-mode-hook', +then `snmpv2-mode-hook'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (sunrise-sunset) "solar" "calendar/solar.el" (19005 +;;;;;; 47389)) +;;; Generated autoloads from calendar/solar.el + +(autoload 'sunrise-sunset "solar" "\ +Local time of sunrise and sunset for today. Accurate to a few seconds. +If called with an optional prefix argument ARG, prompt for date. +If called with an optional double prefix argument, prompt for +longitude, latitude, time zone, and date, and always use standard time. + +This function is suitable for execution in a .emacs file. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (solitaire) "solitaire" "play/solitaire.el" (19005 +;;;;;; 47402)) +;;; Generated autoloads from play/solitaire.el + +(autoload 'solitaire "solitaire" "\ +Play Solitaire. + +To play Solitaire, type \\[solitaire]. +\\ +Move around the board using the cursor keys. +Move stones using \\[solitaire-move] followed by a direction key. +Undo moves using \\[solitaire-undo]. +Check for possible moves using \\[solitaire-do-check]. +\(The variable `solitaire-auto-eval' controls whether to automatically +check after each move or undo.) + +What is Solitaire? + +I don't know who invented this game, but it seems to be rather old and +its origin seems to be northern Africa. Here's how to play: +Initially, the board will look similar to this: + + Le Solitaire + ============ + + o o o + + o o o + + o o o o o o o + + o o o . o o o + + o o o o o o o + + o o o + + o o o + +Let's call the o's stones and the .'s holes. One stone fits into one +hole. As you can see, all holes but one are occupied by stones. The +aim of the game is to get rid of all but one stone, leaving that last +one in the middle of the board if you're cool. + +A stone can be moved if there is another stone next to it, and a hole +after that one. Thus there must be three fields in a row, either +horizontally or vertically, up, down, left or right, which look like +this: o o . + +Then the first stone is moved to the hole, jumping over the second, +which therefore is taken away. The above thus `evaluates' to: . . o + +That's all. Here's the board after two moves: + + o o o + + . o o + + o o . o o o o + + o . o o o o o + + o o o o o o o + + o o o + + o o o + +Pick your favourite shortcuts: + +\\{solitaire-mode-map} + +\(fn ARG)" t nil) + +;;;*** + +;;;### (autoloads (reverse-region sort-columns sort-regexp-fields +;;;;;; sort-fields sort-numeric-fields sort-pages sort-paragraphs +;;;;;; sort-lines sort-subr) "sort" "sort.el" (19005 47386)) +;;; Generated autoloads from sort.el +(put 'sort-fold-case 'safe-local-variable 'booleanp) + +(autoload 'sort-subr "sort" "\ +General text sorting routine to divide buffer into records and sort them. + +We divide the accessible portion of the buffer into disjoint pieces +called sort records. A portion of each sort record (perhaps all of +it) is designated as the sort key. The records are rearranged in the +buffer in order by their sort keys. The records may or may not be +contiguous. + +Usually the records are rearranged in order of ascending sort key. +If REVERSE is non-nil, they are rearranged in order of descending sort key. +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +The next four arguments are functions to be called to move point +across a sort record. They will be called many times from within sort-subr. + +NEXTRECFUN is called with point at the end of the previous record. +It moves point to the start of the next record. +It should move point to the end of the buffer if there are no more records. +The first record is assumed to start at the position of point when sort-subr +is called. + +ENDRECFUN is called with point within the record. +It should move point to the end of the record. + +STARTKEYFUN moves from the start of the record to the start of the key. +It may return either a non-nil value to be used as the key, or +else the key is the substring between the values of point after +STARTKEYFUN and ENDKEYFUN are called. If STARTKEYFUN is nil, the key +starts at the beginning of the record. + +ENDKEYFUN moves from the start of the sort key to the end of the sort key. +ENDKEYFUN may be nil if STARTKEYFUN returns a value or if it would be the +same as ENDRECFUN. + +PREDICATE is the function to use to compare keys. If keys are numbers, +it defaults to `<', otherwise it defaults to `string<'. + +\(fn REVERSE NEXTRECFUN ENDRECFUN &optional STARTKEYFUN ENDKEYFUN PREDICATE)" nil nil) + +(autoload 'sort-lines "sort" "\ +Sort lines in region alphabetically; argument means descending order. +Called from a program, there are three arguments: +REVERSE (non-nil means reverse order), BEG and END (region to sort). +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +\(fn REVERSE BEG END)" t nil) + +(autoload 'sort-paragraphs "sort" "\ +Sort paragraphs in region alphabetically; argument means descending order. +Called from a program, there are three arguments: +REVERSE (non-nil means reverse order), BEG and END (region to sort). +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +\(fn REVERSE BEG END)" t nil) + +(autoload 'sort-pages "sort" "\ +Sort pages in region alphabetically; argument means descending order. +Called from a program, there are three arguments: +REVERSE (non-nil means reverse order), BEG and END (region to sort). +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +\(fn REVERSE BEG END)" t nil) +(put 'sort-numeric-base 'safe-local-variable 'integerp) + +(autoload 'sort-numeric-fields "sort" "\ +Sort lines in region numerically by the ARGth field of each line. +Fields are separated by whitespace and numbered from 1 up. +Specified field must contain a number in each line of the region, +which may begin with \"0x\" or \"0\" for hexadecimal and octal values. +Otherwise, the number is interpreted according to sort-numeric-base. +With a negative arg, sorts by the ARGth field counted from the right. +Called from a program, there are three arguments: +FIELD, BEG and END. BEG and END specify region to sort. + +\(fn FIELD BEG END)" t nil) + +(autoload 'sort-fields "sort" "\ +Sort lines in region lexicographically by the ARGth field of each line. +Fields are separated by whitespace and numbered from 1 up. +With a negative arg, sorts by the ARGth field counted from the right. +Called from a program, there are three arguments: +FIELD, BEG and END. BEG and END specify region to sort. +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +\(fn FIELD BEG END)" t nil) + +(autoload 'sort-regexp-fields "sort" "\ +Sort the region lexicographically as specified by RECORD-REGEXP and KEY. +RECORD-REGEXP specifies the textual units which should be sorted. + For example, to sort lines RECORD-REGEXP would be \"^.*$\" +KEY specifies the part of each record (ie each match for RECORD-REGEXP) + is to be used for sorting. + If it is \"\\\\digit\" then the digit'th \"\\\\(...\\\\)\" match field from + RECORD-REGEXP is used. + If it is \"\\\\&\" then the whole record is used. + Otherwise, it is a regular-expression for which to search within the record. +If a match for KEY is not found within a record then that record is ignored. + +With a negative prefix arg sorts in reverse order. + +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +For example: to sort lines in the region by the first word on each line + starting with the letter \"f\", + RECORD-REGEXP would be \"^.*$\" and KEY would be \"\\\\=\\\" + +\(fn REVERSE RECORD-REGEXP KEY-REGEXP BEG END)" t nil) + +(autoload 'sort-columns "sort" "\ +Sort lines in region alphabetically by a certain range of columns. +For the purpose of this command, the region BEG...END includes +the entire line that point is in and the entire line the mark is in. +The column positions of point and mark bound the range of columns to sort on. +A prefix argument means sort into REVERSE order. +The variable `sort-fold-case' determines whether alphabetic case affects +the sort order. + +Note that `sort-columns' rejects text that contains tabs, +because tabs could be split across the specified columns +and it doesn't know how to handle that. Also, when possible, +it uses the `sort' utility program, which doesn't understand tabs. +Use \\[untabify] to convert tabs to spaces before sorting. + +\(fn REVERSE &optional BEG END)" t nil) + +(autoload 'reverse-region "sort" "\ +Reverse the order of lines in a region. +From a program takes two point or marker arguments, BEG and END. + +\(fn BEG END)" t nil) + +;;;*** + +;;;### (autoloads (spam-initialize) "spam" "gnus/spam.el" (19005 +;;;;;; 47394)) +;;; Generated autoloads from gnus/spam.el + +(autoload 'spam-initialize "spam" "\ +Install the spam.el hooks and do other initialization. +When SYMBOLS is given, set those variables to t. This is so you +can call `spam-initialize' before you set spam-use-* variables on +explicitly, and matters only if you need the extra headers +installed through `spam-necessary-extra-headers'. + +\(fn &rest SYMBOLS)" t nil) + +;;;*** + +;;;### (autoloads (spam-report-deagentize spam-report-agentize spam-report-url-to-file +;;;;;; spam-report-url-ping-mm-url spam-report-process-queue) "spam-report" +;;;;;; "gnus/spam-report.el" (19005 47394)) +;;; Generated autoloads from gnus/spam-report.el + +(autoload 'spam-report-process-queue "spam-report" "\ +Report all queued requests from `spam-report-requests-file'. + +If FILE is given, use it instead of `spam-report-requests-file'. +If KEEP is t, leave old requests in the file. If KEEP is the +symbol `ask', query before flushing the queue file. + +\(fn &optional FILE KEEP)" t nil) + +(autoload 'spam-report-url-ping-mm-url "spam-report" "\ +Ping a host through HTTP, addressing a specific GET resource. Use +the external program specified in `mm-url-program' to connect to +server. + +\(fn HOST REPORT)" nil nil) + +(autoload 'spam-report-url-to-file "spam-report" "\ +Collect spam report requests in `spam-report-requests-file'. +Customize `spam-report-url-ping-function' to use this function. + +\(fn HOST REPORT)" nil nil) + +(autoload 'spam-report-agentize "spam-report" "\ +Add spam-report support to the Agent. +Spam reports will be queued with \\[spam-report-url-to-file] when +the Agent is unplugged, and will be submitted in a batch when the +Agent is plugged. + +\(fn)" t nil) + +(autoload 'spam-report-deagentize "spam-report" "\ +Remove spam-report support from the Agent. +Spam reports will be queued with the method used when +\\[spam-report-agentize] was run. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (speedbar-get-focus speedbar-frame-mode) "speedbar" +;;;;;; "speedbar.el" (19005 47386)) +;;; Generated autoloads from speedbar.el + +(defalias 'speedbar 'speedbar-frame-mode) + +(autoload 'speedbar-frame-mode "speedbar" "\ +Enable or disable speedbar. Positive ARG means turn on, negative turn off. +A nil ARG means toggle. Once the speedbar frame is activated, a buffer in +`speedbar-mode' will be displayed. Currently, only one speedbar is +supported at a time. +`speedbar-before-popup-hook' is called before popping up the speedbar frame. +`speedbar-before-delete-hook' is called before the frame is deleted. + +\(fn &optional ARG)" t nil) + +(autoload 'speedbar-get-focus "speedbar" "\ +Change frame focus to or from the speedbar frame. +If the selected frame is not speedbar, then speedbar frame is +selected. If the speedbar frame is active, then select the attached frame. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (spell-string spell-region spell-word spell-buffer) +;;;;;; "spell" "textmodes/spell.el" (19005 47406)) +;;; Generated autoloads from textmodes/spell.el + +(put 'spell-filter 'risky-local-variable t) + +(autoload 'spell-buffer "spell" "\ +Check spelling of every word in the buffer. +For each incorrect word, you are asked for the correct spelling +and then put into a query-replace to fix some or all occurrences. +If you do not want to change a word, just give the same word +as its \"correct\" spelling; then the query replace is skipped. + +\(fn)" t nil) + +(make-obsolete 'spell-buffer 'ispell-buffer "23.1") + +(autoload 'spell-word "spell" "\ +Check spelling of word at or before point. +If it is not correct, ask user for the correct spelling +and `query-replace' the entire buffer to substitute it. + +\(fn)" t nil) + +(make-obsolete 'spell-word 'ispell-word "23.1") + +(autoload 'spell-region "spell" "\ +Like `spell-buffer' but applies only to region. +Used in a program, applies from START to END. +DESCRIPTION is an optional string naming the unit being checked: +for example, \"word\". + +\(fn START END &optional DESCRIPTION)" t nil) + +(make-obsolete 'spell-region 'ispell-region "23.1") + +(autoload 'spell-string "spell" "\ +Check spelling of string supplied as argument. + +\(fn STRING)" t nil) + +(make-obsolete 'spell-string "The `spell' package is obsolete - use `ispell'." "23.1") + +;;;*** + +;;;### (autoloads (snarf-spooks spook) "spook" "play/spook.el" (19005 +;;;;;; 47402)) +;;; Generated autoloads from play/spook.el + +(autoload 'spook "spook" "\ +Adds that special touch of class to your outgoing mail. + +\(fn)" t nil) + +(autoload 'snarf-spooks "spook" "\ +Return a vector containing the lines from `spook-phrases-file'. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (sql-linter sql-db2 sql-interbase sql-postgres +;;;;;; sql-ms sql-ingres sql-solid sql-mysql sql-sqlite sql-informix +;;;;;; sql-sybase sql-oracle sql-product-interactive sql-mode sql-help +;;;;;; sql-add-product-keywords) "sql" "progmodes/sql.el" (19005 +;;;;;; 47404)) +;;; Generated autoloads from progmodes/sql.el + +(autoload 'sql-add-product-keywords "sql" "\ +Add highlighting KEYWORDS for SQL PRODUCT. + +PRODUCT should be a symbol, the name of a sql product, such as +`oracle'. KEYWORDS should be a list; see the variable +`font-lock-keywords'. By default they are added at the beginning +of the current highlighting list. If optional argument APPEND is +`set', they are used to replace the current highlighting list. +If APPEND is any other non-nil value, they are added at the end +of the current highlighting list. + +For example: + + (sql-add-product-keywords 'ms + '((\"\\\\b\\\\w+_t\\\\b\" . font-lock-type-face))) + +adds a fontification pattern to fontify identifiers ending in +`_t' as data types. + +\(fn PRODUCT KEYWORDS &optional APPEND)" nil nil) + +(autoload 'sql-help "sql" "\ +Show short help for the SQL modes. + +Use an entry function to open an interactive SQL buffer. This buffer is +usually named `*SQL*'. The name of the major mode is SQLi. + +Use the following commands to start a specific SQL interpreter: + + PostGres: \\[sql-postgres] + MySQL: \\[sql-mysql] + SQLite: \\[sql-sqlite] + +Other non-free SQL implementations are also supported: + + Solid: \\[sql-solid] + Oracle: \\[sql-oracle] + Informix: \\[sql-informix] + Sybase: \\[sql-sybase] + Ingres: \\[sql-ingres] + Microsoft: \\[sql-ms] + DB2: \\[sql-db2] + Interbase: \\[sql-interbase] + Linter: \\[sql-linter] + +But we urge you to choose a free implementation instead of these. + +Once you have the SQLi buffer, you can enter SQL statements in the +buffer. The output generated is appended to the buffer and a new prompt +is generated. See the In/Out menu in the SQLi buffer for some functions +that help you navigate through the buffer, the input history, etc. + +If you have a really complex SQL statement or if you are writing a +procedure, you can do this in a separate buffer. Put the new buffer in +`sql-mode' by calling \\[sql-mode]. The name of this buffer can be +anything. The name of the major mode is SQL. + +In this SQL buffer (SQL mode), you can send the region or the entire +buffer to the interactive SQL buffer (SQLi mode). The results are +appended to the SQLi buffer without disturbing your SQL buffer. + +\(fn)" t nil) + +(autoload 'sql-mode "sql" "\ +Major mode to edit SQL. + +You can send SQL statements to the SQLi buffer using +\\[sql-send-region]. Such a buffer must exist before you can do this. +See `sql-help' on how to create SQLi buffers. + +\\{sql-mode-map} +Customization: Entry to this mode runs the `sql-mode-hook'. + +When you put a buffer in SQL mode, the buffer stores the last SQLi +buffer created as its destination in the variable `sql-buffer'. This +will be the buffer \\[sql-send-region] sends the region to. If this +SQLi buffer is killed, \\[sql-send-region] is no longer able to +determine where the strings should be sent to. You can set the +value of `sql-buffer' using \\[sql-set-sqli-buffer]. + +For information on how to create multiple SQLi buffers, see +`sql-interactive-mode'. + +Note that SQL doesn't have an escape character unless you specify +one. If you specify backslash as escape character in SQL, +you must tell Emacs. Here's how to do that in your `~/.emacs' file: + +\(add-hook 'sql-mode-hook + (lambda () + (modify-syntax-entry ?\\\\ \".\" sql-mode-syntax-table))) + +\(fn)" t nil) + +(autoload 'sql-product-interactive "sql" "\ +Run product interpreter as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn &optional PRODUCT)" t nil) + +(autoload 'sql-oracle "sql" "\ +Run sqlplus by Oracle as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-oracle-program'. Login uses +the variables `sql-user', `sql-password', and `sql-database' as +defaults, if set. Additional command line parameters can be stored in +the list `sql-oracle-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-oracle]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-sybase "sql" "\ +Run isql by SyBase as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-sybase-program'. Login uses +the variables `sql-server', `sql-user', `sql-password', and +`sql-database' as defaults, if set. Additional command line parameters +can be stored in the list `sql-sybase-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-sybase]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-informix "sql" "\ +Run dbaccess by Informix as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-informix-program'. Login uses +the variable `sql-database' as default, if set. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-informix]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-sqlite "sql" "\ +Run sqlite as an inferior process. + +SQLite is free software. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-sqlite-program'. Login uses +the variables `sql-user', `sql-password', `sql-database', and +`sql-server' as defaults, if set. Additional command line parameters +can be stored in the list `sql-sqlite-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-sqlite]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-mysql "sql" "\ +Run mysql by TcX as an inferior process. + +Mysql versions 3.23 and up are free software. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-mysql-program'. Login uses +the variables `sql-user', `sql-password', `sql-database', and +`sql-server' as defaults, if set. Additional command line parameters +can be stored in the list `sql-mysql-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-mysql]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-solid "sql" "\ +Run solsql by Solid as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-solid-program'. Login uses +the variables `sql-user', `sql-password', and `sql-server' as +defaults, if set. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-solid]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-ingres "sql" "\ +Run sql by Ingres as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-ingres-program'. Login uses +the variable `sql-database' as default, if set. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-ingres]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-ms "sql" "\ +Run osql by Microsoft as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-ms-program'. Login uses the +variables `sql-user', `sql-password', `sql-database', and `sql-server' +as defaults, if set. Additional command line parameters can be stored +in the list `sql-ms-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-ms]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-postgres "sql" "\ +Run psql by Postgres as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-postgres-program'. Login uses +the variables `sql-database' and `sql-server' as default, if set. +Additional command line parameters can be stored in the list +`sql-postgres-options'. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-postgres]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. If your output lines end with ^M, +your might try undecided-dos as a coding system. If this doesn't help, +Try to set `comint-output-filter-functions' like this: + +\(setq comint-output-filter-functions (append comint-output-filter-functions + '(comint-strip-ctrl-m))) + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-interbase "sql" "\ +Run isql by Interbase as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-interbase-program'. Login +uses the variables `sql-user', `sql-password', and `sql-database' as +defaults, if set. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-interbase]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-db2 "sql" "\ +Run db2 by IBM as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-db2-program'. There is not +automatic login. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +If you use \\[sql-accumulate-and-indent] to send multiline commands to +db2, newlines will be escaped if necessary. If you don't want that, set +`comint-input-sender' back to `comint-simple-send' by writing an after +advice. See the elisp manual for more information. + +To specify a coding system for converting non-ASCII characters +in the input and output to the process, use \\[universal-coding-system-argument] +before \\[sql-db2]. You can also specify this with \\[set-buffer-process-coding-system] +in the SQL buffer, after you start the process. +The default comes from `process-coding-system-alist' and +`default-process-coding-system'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +(autoload 'sql-linter "sql" "\ +Run inl by RELEX as an inferior process. + +If buffer `*SQL*' exists but no process is running, make a new process. +If buffer exists and a process is running, just switch to buffer +`*SQL*'. + +Interpreter used comes from variable `sql-linter-program' - usually `inl'. +Login uses the variables `sql-user', `sql-password', `sql-database' and +`sql-server' as defaults, if set. Additional command line parameters +can be stored in the list `sql-linter-options'. Run inl -h to get help on +parameters. + +`sql-database' is used to set the LINTER_MBX environment variable for +local connections, `sql-server' refers to the server name from the +`nodetab' file for the network connection (dbc_tcp or friends must run +for this to work). If `sql-password' is an empty string, inl will use +an empty password. + +The buffer is put in sql-interactive-mode, giving commands for sending +input. See `sql-interactive-mode'. + +\(Type \\[describe-mode] in the SQL buffer for a list of commands.) + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (strokes-compose-complex-stroke strokes-decode-buffer +;;;;;; strokes-mode strokes-list-strokes strokes-load-user-strokes +;;;;;; strokes-help strokes-describe-stroke strokes-do-complex-stroke +;;;;;; strokes-do-stroke strokes-read-complex-stroke strokes-read-stroke +;;;;;; strokes-global-set-stroke) "strokes" "strokes.el" (19005 +;;;;;; 47386)) +;;; Generated autoloads from strokes.el + +(autoload 'strokes-global-set-stroke "strokes" "\ +Interactively give STROKE the global binding as COMMAND. +Operated just like `global-set-key', except for strokes. +COMMAND is a symbol naming an interactively-callable function. STROKE +is a list of sampled positions on the stroke grid as described in the +documentation for the `strokes-define-stroke' function. + +See also `strokes-global-set-stroke-string'. + +\(fn STROKE COMMAND)" t nil) + +(autoload 'strokes-read-stroke "strokes" "\ +Read a simple stroke (interactively) and return the stroke. +Optional PROMPT in minibuffer displays before and during stroke reading. +This function will display the stroke interactively as it is being +entered in the strokes buffer if the variable +`strokes-use-strokes-buffer' is non-nil. +Optional EVENT is acceptable as the starting event of the stroke. + +\(fn &optional PROMPT EVENT)" nil nil) + +(autoload 'strokes-read-complex-stroke "strokes" "\ +Read a complex stroke (interactively) and return the stroke. +Optional PROMPT in minibuffer displays before and during stroke reading. +Note that a complex stroke allows the user to pen-up and pen-down. This +is implemented by allowing the user to paint with button 1 or button 2 and +then complete the stroke with button 3. +Optional EVENT is acceptable as the starting event of the stroke. + +\(fn &optional PROMPT EVENT)" nil nil) + +(autoload 'strokes-do-stroke "strokes" "\ +Read a simple stroke from the user and then execute its command. +This must be bound to a mouse event. + +\(fn EVENT)" t nil) + +(autoload 'strokes-do-complex-stroke "strokes" "\ +Read a complex stroke from the user and then execute its command. +This must be bound to a mouse event. + +\(fn EVENT)" t nil) + +(autoload 'strokes-describe-stroke "strokes" "\ +Displays the command which STROKE maps to, reading STROKE interactively. + +\(fn STROKE)" t nil) + +(autoload 'strokes-help "strokes" "\ +Get instruction on using the Strokes package. + +\(fn)" t nil) + +(autoload 'strokes-load-user-strokes "strokes" "\ +Load user-defined strokes from file named by `strokes-file'. + +\(fn)" t nil) + +(autoload 'strokes-list-strokes "strokes" "\ +Pop up a buffer containing an alphabetical listing of strokes in STROKES-MAP. +With CHRONOLOGICAL prefix arg (\\[universal-argument]) list strokes +chronologically by command name. +If STROKES-MAP is not given, `strokes-global-map' will be used instead. + +\(fn &optional CHRONOLOGICAL STROKES-MAP)" t nil) + +(defvar strokes-mode nil "\ +Non-nil if Strokes mode is enabled. +See the command `strokes-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `strokes-mode'.") + +(custom-autoload 'strokes-mode "strokes" nil) + +(autoload 'strokes-mode "strokes" "\ +Toggle Strokes global minor mode.\\ +With ARG, turn strokes on if and only if ARG is positive. +Strokes are pictographic mouse gestures which invoke commands. +Strokes are invoked with \\[strokes-do-stroke]. You can define +new strokes with \\[strokes-global-set-stroke]. See also +\\[strokes-do-complex-stroke] for `complex' strokes. + +To use strokes for pictographic editing, such as Chinese/Japanese, use +\\[strokes-compose-complex-stroke], which draws strokes and inserts them. +Encode/decode your strokes with \\[strokes-encode-buffer], +\\[strokes-decode-buffer]. + +\\{strokes-mode-map} + +\(fn &optional ARG)" t nil) + +(autoload 'strokes-decode-buffer "strokes" "\ +Decode stroke strings in BUFFER and display their corresponding glyphs. +Optional BUFFER defaults to the current buffer. +Optional FORCE non-nil will ignore the buffer's read-only status. + +\(fn &optional BUFFER FORCE)" t nil) + +(autoload 'strokes-compose-complex-stroke "strokes" "\ +Read a complex stroke and insert its glyph into the current buffer. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (studlify-buffer studlify-word studlify-region) +;;;;;; "studly" "play/studly.el" (19005 47402)) +;;; Generated autoloads from play/studly.el + +(autoload 'studlify-region "studly" "\ +Studlify-case the region. + +\(fn BEGIN END)" t nil) + +(autoload 'studlify-word "studly" "\ +Studlify-case the current word, or COUNT words if given an argument. + +\(fn COUNT)" t nil) + +(autoload 'studlify-buffer "studly" "\ +Studlify-case the current buffer. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (sc-cite-original) "supercite" "mail/supercite.el" +;;;;;; (19005 47398)) +;;; Generated autoloads from mail/supercite.el + +(autoload 'sc-cite-original "supercite" "\ +Workhorse citing function which performs the initial citation. +This is callable from the various mail and news readers' reply +function according to the agreed upon standard. See the associated +info node `(SC)Top' for more details. +`sc-cite-original' does not do any yanking of the +original message but it does require a few things: + + 1) The reply buffer is the current buffer. + + 2) The original message has been yanked and inserted into the + reply buffer. + + 3) Verbose mail headers from the original message have been + inserted into the reply buffer directly before the text of the + original message. + + 4) Point is at the beginning of the verbose headers. + + 5) Mark is at the end of the body of text to be cited. + +The region need not be active (and typically isn't when this +function is called). Also, the hook `sc-pre-hook' is run before, +and `sc-post-hook' is run after the guts of this function. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (symbol-completion-try-complete symbol-complete) +;;;;;; "sym-comp" "progmodes/sym-comp.el" (18785 32071)) +;;; Generated autoloads from progmodes/sym-comp.el + +(autoload 'symbol-complete "sym-comp" "\ +Perform completion of the symbol preceding point. +This is done in a way appropriate to the current major mode, +perhaps by interrogating an inferior interpreter. Compare +`complete-symbol'. +If no characters can be completed, display a list of possible completions. +Repeating the command at that point scrolls the list. + +When called from a program, optional arg PREDICATE is a predicate +determining which symbols are considered. + +This function requires `symbol-completion-completions-function' +to be set buffer-locally. Variables `symbol-completion-symbol-function', +`symbol-completion-predicate-function' and +`symbol-completion-transform-function' are also consulted. + +\(fn &optional PREDICATE)" t nil) + +(autoload 'symbol-completion-try-complete "sym-comp" "\ +Completion function for use with `hippie-expand'. +Uses `symbol-completion-symbol-function' and +`symbol-completion-completions-function'. It is intended to be +used something like this in a major mode which provides symbol +completion: + + (if (featurep 'hippie-exp) + (set (make-local-variable 'hippie-expand-try-functions-list) + (cons 'symbol-completion-try-complete + hippie-expand-try-functions-list))) + +\(fn OLD)" nil nil) + +;;;*** + +;;;### (autoloads (gpm-mouse-mode) "t-mouse" "t-mouse.el" (19005 +;;;;;; 47386)) +;;; Generated autoloads from t-mouse.el + +(define-obsolete-function-alias 't-mouse-mode 'gpm-mouse-mode "23.1") + +(defvar gpm-mouse-mode t "\ +Non-nil if Gpm-Mouse mode is enabled. +See the command `gpm-mouse-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `gpm-mouse-mode'.") + +(custom-autoload 'gpm-mouse-mode "t-mouse" nil) + +(autoload 'gpm-mouse-mode "t-mouse" "\ +Toggle gpm-mouse mode to use the mouse in GNU/Linux consoles. +With prefix arg, turn gpm-mouse mode on if arg is positive, +otherwise turn it off. + +This allows the use of the mouse when operating on a GNU/Linux console, +in the same way as you can use the mouse under X11. +It relies on the `gpm' daemon being activated. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (tabify untabify) "tabify" "tabify.el" (19005 47386)) +;;; Generated autoloads from tabify.el + +(autoload 'untabify "tabify" "\ +Convert all tabs in region to multiple spaces, preserving columns. +Called non-interactively, the region is specified by arguments +START and END, rather than by the position of point and mark. +The variable `tab-width' controls the spacing of tab stops. + +\(fn START END)" t nil) + +(autoload 'tabify "tabify" "\ +Convert multiple spaces in region to tabs when possible. +A group of spaces is partially replaced by tabs +when this can be done without changing the column they end at. +Called non-interactively, the region is specified by arguments +START and END, rather than by the position of point and mark. +The variable `tab-width' controls the spacing of tab stops. + +\(fn START END)" t nil) + +;;;*** + +;;;### (autoloads (table-release table-capture table-delete-column +;;;;;; table-delete-row table-insert-sequence table-generate-source +;;;;;; table-query-dimension table-fixed-width-mode table-justify-column +;;;;;; table-justify-row table-justify-cell table-justify table-split-cell +;;;;;; table-split-cell-horizontally table-split-cell-vertically +;;;;;; table-span-cell table-backward-cell table-forward-cell table-narrow-cell +;;;;;; table-widen-cell table-shorten-cell table-heighten-cell table-unrecognize-cell +;;;;;; table-recognize-cell table-unrecognize-table table-recognize-table +;;;;;; table-unrecognize-region table-recognize-region table-unrecognize +;;;;;; table-recognize table-insert-row-column table-insert-column +;;;;;; table-insert-row table-insert table-point-left-cell-hook +;;;;;; table-point-entered-cell-hook table-load-hook table-cell-map-hook) +;;;;;; "table" "textmodes/table.el" (19005 47406)) +;;; Generated autoloads from textmodes/table.el + +(defvar table-cell-map-hook nil "\ +*Normal hooks run when finishing construction of `table-cell-map'. +User can modify `table-cell-map' by adding custom functions here.") + +(custom-autoload 'table-cell-map-hook "table" t) + +(defvar table-load-hook nil "\ +*List of functions to be called after the table is first loaded.") + +(custom-autoload 'table-load-hook "table" t) + +(defvar table-point-entered-cell-hook nil "\ +*List of functions to be called after point entered a table cell.") + +(custom-autoload 'table-point-entered-cell-hook "table" t) + +(defvar table-point-left-cell-hook nil "\ +*List of functions to be called after point left a table cell.") + +(custom-autoload 'table-point-left-cell-hook "table" t) + +(autoload 'table-insert "table" "\ +Insert an editable text table. +Insert a table of specified number of COLUMNS and ROWS. Optional +parameter CELL-WIDTH and CELL-HEIGHT can specify the size of each +cell. The cell size is uniform across the table if the specified size +is a number. They can be a list of numbers to specify different size +for each cell. When called interactively, the list of number is +entered by simply listing all the numbers with space characters +delimiting them. + +Examples: + +\\[table-insert] inserts a table at the current point location. + +Suppose we have the following situation where `-!-' indicates the +location of point. + + -!- + +Type \\[table-insert] and hit ENTER key. As it asks table +specification, provide 3 for number of columns, 1 for number of rows, +5 for cell width and 1 for cell height. Now you shall see the next +table and the point is automatically moved to the beginning of the +first cell. + + +-----+-----+-----+ + |-!- | | | + +-----+-----+-----+ + +Inside a table cell, there are special key bindings. \\ + +M-9 \\[table-widen-cell] (or \\[universal-argument] 9 \\[table-widen-cell]) widens the first cell by 9 character +width, which results as + + +--------------+-----+-----+ + |-!- | | | + +--------------+-----+-----+ + +Type TAB \\[table-widen-cell] then type TAB M-2 M-7 \\[table-widen-cell] (or \\[universal-argument] 2 7 \\[table-widen-cell]). Typing +TAB moves the point forward by a cell. The result now looks like this: + + +--------------+------+--------------------------------+ + | | |-!- | + +--------------+------+--------------------------------+ + +If you knew each width of the columns prior to the table creation, +what you could have done better was to have had given the complete +width information to `table-insert'. + +Cell width(s): 14 6 32 + +instead of + +Cell width(s): 5 + +This would have eliminated the previously mentioned width adjustment +work all together. + +If the point is in the last cell type S-TAB S-TAB to move it to the +first cell. Now type \\[table-heighten-cell] which heighten the row by a line. + + +--------------+------+--------------------------------+ + |-!- | | | + | | | | + +--------------+------+--------------------------------+ + +Type \\[table-insert-row-column] and tell it to insert a row. + + +--------------+------+--------------------------------+ + |-!- | | | + | | | | + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + +Move the point under the table as shown below. + + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + -!- + +Type M-x table-insert-row instead of \\[table-insert-row-column]. \\[table-insert-row-column] does not work +when the point is outside of the table. This insertion at +outside of the table effectively appends a row at the end. + + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + |-!- | | | + | | | | + +--------------+------+--------------------------------+ + +Text editing inside the table cell produces reasonably expected +results. + + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + | | |Text editing inside the table | + | | |cell produces reasonably | + | | |expected results.-!- | + +--------------+------+--------------------------------+ + | | | | + | | | | + +--------------+------+--------------------------------+ + +Inside a table cell has a special keymap. + +\\{table-cell-map} + +\(fn COLUMNS ROWS &optional CELL-WIDTH CELL-HEIGHT)" t nil) + +(autoload 'table-insert-row "table" "\ +Insert N table row(s). +When point is in a table the newly inserted row(s) are placed above +the current row. When point is outside of the table it must be below +the table within the table width range, then the newly created row(s) +are appended at the bottom of the table. + +\(fn N)" t nil) + +(autoload 'table-insert-column "table" "\ +Insert N table column(s). +When point is in a table the newly inserted column(s) are placed left +of the current column. When point is outside of the table it must be +right side of the table within the table height range, then the newly +created column(s) are appended at the right of the table. + +\(fn N)" t nil) + +(autoload 'table-insert-row-column "table" "\ +Insert row(s) or column(s). +See `table-insert-row' and `table-insert-column'. + +\(fn ROW-COLUMN N)" t nil) + +(autoload 'table-recognize "table" "\ +Recognize all tables within the current buffer and activate them. +Scans the entire buffer and recognizes valid table cells. If the +optional numeric prefix argument ARG is negative the tables in the +buffer become inactive, meaning the tables become plain text and loses +all the table specific features. + +\(fn &optional ARG)" t nil) + +(autoload 'table-unrecognize "table" "\ +Not documented + +\(fn)" t nil) + +(autoload 'table-recognize-region "table" "\ +Recognize all tables within region. +BEG and END specify the region to work on. If the optional numeric +prefix argument ARG is negative the tables in the region become +inactive, meaning the tables become plain text and lose all the table +specific features. + +\(fn BEG END &optional ARG)" t nil) + +(autoload 'table-unrecognize-region "table" "\ +Not documented + +\(fn BEG END)" t nil) + +(autoload 'table-recognize-table "table" "\ +Recognize a table at point. +If the optional numeric prefix argument ARG is negative the table +becomes inactive, meaning the table becomes plain text and loses all +the table specific features. + +\(fn &optional ARG)" t nil) + +(autoload 'table-unrecognize-table "table" "\ +Not documented + +\(fn)" t nil) + +(autoload 'table-recognize-cell "table" "\ +Recognize a table cell that contains current point. +Probe the cell dimension and prepare the cell information. The +optional two arguments FORCE and NO-COPY are for internal use only and +must not be specified. When the optional numeric prefix argument ARG +is negative the cell becomes inactive, meaning that the cell becomes +plain text and loses all the table specific features. + +\(fn &optional FORCE NO-COPY ARG)" t nil) + +(autoload 'table-unrecognize-cell "table" "\ +Not documented + +\(fn)" t nil) + +(autoload 'table-heighten-cell "table" "\ +Heighten the current cell by N lines by expanding the cell vertically. +Heightening is done by adding blank lines at the bottom of the current +cell. Other cells aligned horizontally with the current one are also +heightened in order to keep the rectangular table structure. The +optional argument NO-COPY is internal use only and must not be +specified. + +\(fn N &optional NO-COPY NO-UPDATE)" t nil) + +(autoload 'table-shorten-cell "table" "\ +Shorten the current cell by N lines by shrinking the cell vertically. +Shortening is done by removing blank lines from the bottom of the cell +and possibly from the top of the cell as well. Therefor, the cell +must have some bottom/top blank lines to be shorten effectively. This +is applicable to all the cells aligned horizontally with the current +one because they are also shortened in order to keep the rectangular +table structure. + +\(fn N)" t nil) + +(autoload 'table-widen-cell "table" "\ +Widen the current cell by N columns and expand the cell horizontally. +Some other cells in the same table are widen as well to keep the +table's rectangle structure. + +\(fn N &optional NO-COPY NO-UPDATE)" t nil) + +(autoload 'table-narrow-cell "table" "\ +Narrow the current cell by N columns and shrink the cell horizontally. +Some other cells in the same table are narrowed as well to keep the +table's rectangle structure. + +\(fn N)" t nil) + +(autoload 'table-forward-cell "table" "\ +Move point forward to the beginning of the next cell. +With argument ARG, do it ARG times; +a negative argument ARG = -N means move backward N cells. +Do not specify NO-RECOGNIZE and UNRECOGNIZE. They are for internal use only. + +Sample Cell Traveling Order (In Irregular Table Cases) + +You can actually try how it works in this buffer. Press +\\[table-recognize] and go to cells in the following tables and press +\\[table-forward-cell] or TAB key. + ++-----+--+ +--+-----+ +--+--+--+ +--+--+--+ +---------+ +--+---+--+ +|0 |1 | |0 |1 | |0 |1 |2 | |0 |1 |2 | |0 | |0 |1 |2 | ++--+--+ | | +--+--+ +--+ | | | | +--+ +----+----+ +--+-+-+--+ +|2 |3 | | | |2 |3 | |3 +--+ | | +--+3 | |1 |2 | |3 |4 | +| +--+--+ +--+--+ | +--+4 | | | |4 +--+ +--+-+-+--+ +----+----+ +| |4 | |4 | | |5 | | | | | |5 | |3 |4 |5 | |5 | ++--+-----+ +-----+--+ +--+--+--+ +--+--+--+ +--+---+--+ +---------+ + ++--+--+--+ +--+--+--+ +--+--+--+ +--+--+--+ +|0 |1 |2 | |0 |1 |2 | |0 |1 |2 | |0 |1 |2 | +| | | | | +--+ | | | | | +--+ +--+ ++--+ +--+ +--+3 +--+ | +--+ | |3 +--+4 | +|3 | |4 | |4 +--+5 | | |3 | | +--+5 +--+ +| | | | | |6 | | | | | | |6 | |7 | ++--+--+--+ +--+--+--+ +--+--+--+ +--+--+--+ + ++--+--+--+ +--+--+--+ +--+--+--+--+ +--+-----+--+ +--+--+--+--+ +|0 |1 |2 | |0 |1 |2 | |0 |1 |2 |3 | |0 |1 |2 | |0 |1 |2 |3 | +| +--+ | | +--+ | | +--+--+ | | | | | | +--+--+ | +| |3 +--+ +--+3 | | +--+4 +--+ +--+ +--+ +--+4 +--+ ++--+ |4 | |4 | +--+ |5 +--+--+6 | |3 +--+--+4 | |5 | |6 | +|5 +--+ | | +--+5 | | |7 |8 | | | |5 |6 | | | | | | +| |6 | | | |6 | | +--+--+--+--+ +--+--+--+--+ +--+-----+--+ ++--+--+--+ +--+--+--+ + +\(fn &optional ARG NO-RECOGNIZE UNRECOGNIZE)" t nil) + +(autoload 'table-backward-cell "table" "\ +Move backward to the beginning of the previous cell. +With argument ARG, do it ARG times; +a negative argument ARG = -N means move forward N cells. + +\(fn &optional ARG)" t nil) + +(autoload 'table-span-cell "table" "\ +Span current cell into adjacent cell in DIRECTION. +DIRECTION is one of symbols; right, left, above or below. + +\(fn DIRECTION)" t nil) + +(autoload 'table-split-cell-vertically "table" "\ +Split current cell vertically. +Creates a cell above and a cell below the current point location. + +\(fn)" t nil) + +(autoload 'table-split-cell-horizontally "table" "\ +Split current cell horizontally. +Creates a cell on the left and a cell on the right of the current point location. + +\(fn)" t nil) + +(autoload 'table-split-cell "table" "\ +Split current cell in ORIENTATION. +ORIENTATION is a symbol either horizontally or vertically. + +\(fn ORIENTATION)" t nil) + +(autoload 'table-justify "table" "\ +Justify contents of a cell, a row of cells or a column of cells. +WHAT is a symbol 'cell, 'row or 'column. JUSTIFY is a symbol 'left, +'center, 'right, 'top, 'middle, 'bottom or 'none. + +\(fn WHAT JUSTIFY)" t nil) + +(autoload 'table-justify-cell "table" "\ +Justify cell contents. +JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or 'top, +'middle, 'bottom or 'none for vertical. When optional PARAGRAPH is +non-nil the justify operation is limited to the current paragraph, +otherwise the entire cell contents is justified. + +\(fn JUSTIFY &optional PARAGRAPH)" t nil) + +(autoload 'table-justify-row "table" "\ +Justify cells of a row. +JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or top, +'middle, 'bottom or 'none for vertical. + +\(fn JUSTIFY)" t nil) + +(autoload 'table-justify-column "table" "\ +Justify cells of a column. +JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or top, +'middle, 'bottom or 'none for vertical. + +\(fn JUSTIFY)" t nil) + +(autoload 'table-fixed-width-mode "table" "\ +Toggle fixing width mode. +In the fixed width mode, typing inside a cell never changes the cell +width where in the normal mode the cell width expands automatically in +order to prevent a word being folded into multiple lines. + +\(fn &optional ARG)" t nil) + +(autoload 'table-query-dimension "table" "\ +Return the dimension of the current cell and the current table. +The result is a list (cw ch tw th c r cells) where cw is the cell +width, ch is the cell height, tw is the table width, th is the table +height, c is the number of columns, r is the number of rows and cells +is the total number of cells. The cell dimension excludes the cell +frame while the table dimension includes the table frame. The columns +and the rows are counted by the number of cell boundaries. Therefore +the number tends to be larger than it appears for the tables with +non-uniform cell structure (heavily spanned and split). When optional +WHERE is provided the cell and table at that location is reported. + +\(fn &optional WHERE)" t nil) + +(autoload 'table-generate-source "table" "\ +Generate source of the current table in the specified language. +LANGUAGE is a symbol that specifies the language to describe the +structure of the table. It must be either 'html, 'latex or 'cals. +The resulted source text is inserted into DEST-BUFFER and the buffer +object is returned. When DEST-BUFFER is omitted or nil the default +buffer specified in `table-dest-buffer-name' is used. In this case +the content of the default buffer is erased prior to the generation. +When DEST-BUFFER is non-nil it is expected to be either a destination +buffer or a name of the destination buffer. In this case the +generated result is inserted at the current point in the destination +buffer and the previously existing contents in the buffer are +untouched. + +References used for this implementation: + +HTML: + http://www.w3.org + +LaTeX: + http://www.maths.tcd.ie/~dwilkins/LaTeXPrimer/Tables.html + +CALS (DocBook DTD): + http://www.oasis-open.org/html/a502.htm + http://www.oreilly.com/catalog/docbook/chapter/book/table.html#AEN114751 + +\(fn LANGUAGE &optional DEST-BUFFER CAPTION)" t nil) + +(autoload 'table-insert-sequence "table" "\ +Travel cells forward while inserting a specified sequence string in each cell. +STR is the base string from which the sequence starts. When STR is an +empty string then each cell content is erased. When STR ends with +numerical characters (they may optionally be surrounded by a pair of +parentheses) they are incremented as a decimal number. Otherwise the +last character in STR is incremented in ASCII code order. N is the +number of sequence elements to insert. When N is negative the cell +traveling direction is backward. When N is zero it travels forward +entire table. INCREMENT is the increment between adjacent sequence +elements and can be a negative number for effectively decrementing. +INTERVAL is the number of cells to travel between sequence element +insertion which is normally 1. When zero or less is given for +INTERVAL it is interpreted as number of cells per row so that sequence +is placed straight down vertically as long as the table's cell +structure is uniform. JUSTIFY is one of the symbol 'left, 'center or +'right, that specifies justification of the inserted string. + +Example: + + (progn + (table-insert 16 3 5 1) + (table-forward-cell 15) + (table-insert-sequence \"D0\" -16 1 1 'center) + (table-forward-cell 16) + (table-insert-sequence \"A[0]\" -16 1 1 'center) + (table-forward-cell 1) + (table-insert-sequence \"-\" 16 0 1 'center)) + + (progn + (table-insert 16 8 5 1) + (table-insert-sequence \"@\" 0 1 2 'right) + (table-forward-cell 1) + (table-insert-sequence \"64\" 0 1 2 'left)) + +\(fn STR N INCREMENT INTERVAL JUSTIFY)" t nil) + +(autoload 'table-delete-row "table" "\ +Delete N row(s) of cells. +Delete N rows of cells from current row. The current row is the row +contains the current cell where point is located. Each row must +consists from cells of same height. + +\(fn N)" t nil) + +(autoload 'table-delete-column "table" "\ +Delete N column(s) of cells. +Delete N columns of cells from current column. The current column is +the column contains the current cell where point is located. Each +column must consists from cells of same width. + +\(fn N)" t nil) + +(autoload 'table-capture "table" "\ +Convert plain text into a table by capturing the text in the region. +Create a table with the text in region as cell contents. BEG and END +specify the region. The text in the region is replaced with a table. +The removed text is inserted in the table. When optional +COL-DELIM-REGEXP and ROW-DELIM-REGEXP are provided the region contents +is parsed and separated into individual cell contents by using the +delimiter regular expressions. This parsing determines the number of +columns and rows of the table automatically. If COL-DELIM-REGEXP and +ROW-DELIM-REGEXP are omitted the result table has only one cell and +the entire region contents is placed in that cell. Optional JUSTIFY +is one of 'left, 'center or 'right, which specifies the cell +justification. Optional MIN-CELL-WIDTH specifies the minimum cell +width. Optional COLUMNS specify the number of columns when +ROW-DELIM-REGEXP is not specified. + + +Example 1: + +1, 2, 3, 4 +5, 6, 7, 8 +, 9, 10 + +Running `table-capture' on above 3 line region with COL-DELIM-REGEXP +\",\" and ROW-DELIM-REGEXP \"\\n\" creates the following table. In +this example the cells are centered and minimum cell width is +specified as 5. + ++-----+-----+-----+-----+ +| 1 | 2 | 3 | 4 | ++-----+-----+-----+-----+ +| 5 | 6 | 7 | 8 | ++-----+-----+-----+-----+ +| | 9 | 10 | | ++-----+-----+-----+-----+ + +Note: + +In case the function is called interactively user must use \\[quoted-insert] `quoted-insert' +in order to enter \"\\n\" successfully. COL-DELIM-REGEXP at the end +of each row is optional. + + +Example 2: + +This example shows how a table can be used for text layout editing. +Let `table-capture' capture the following region starting from +-!- and ending at -*-, that contains three paragraphs and two item +name headers. This time specify empty string for both +COL-DELIM-REGEXP and ROW-DELIM-REGEXP. + +-!-`table-capture' is a powerful command however mastering its power +requires some practice. Here is a list of items what it can do. + +Parse Cell Items By using column delimiter regular + expression and raw delimiter regular + expression, it parses the specified text + area and extracts cell items from + non-table text and then forms a table out + of them. + +Capture Text Area When no delimiters are specified it + creates a single cell table. The text in + the specified region is placed in that + cell.-*- + +Now the entire content is captured in a cell which is itself a table +like this. + ++-----------------------------------------------------------------+ +|`table-capture' is a powerful command however mastering its power| +|requires some practice. Here is a list of items what it can do. | +| | +|Parse Cell Items By using column delimiter regular | +| expression and raw delimiter regular | +| expression, it parses the specified text | +| area and extracts cell items from | +| non-table text and then forms a table out | +| of them. | +| | +|Capture Text Area When no delimiters are specified it | +| creates a single cell table. The text in | +| the specified region is placed in that | +| cell. | ++-----------------------------------------------------------------+ + +By splitting the cell appropriately we now have a table consisting of +paragraphs occupying its own cell. Each cell can now be edited +independently. + ++-----------------------------------------------------------------+ +|`table-capture' is a powerful command however mastering its power| +|requires some practice. Here is a list of items what it can do. | ++---------------------+-------------------------------------------+ +|Parse Cell Items |By using column delimiter regular | +| |expression and raw delimiter regular | +| |expression, it parses the specified text | +| |area and extracts cell items from | +| |non-table text and then forms a table out | +| |of them. | ++---------------------+-------------------------------------------+ +|Capture Text Area |When no delimiters are specified it | +| |creates a single cell table. The text in | +| |the specified region is placed in that | +| |cell. | ++---------------------+-------------------------------------------+ + +By applying `table-release', which does the opposite process, the +contents become once again plain text. `table-release' works as +companion command to `table-capture' this way. + +\(fn BEG END &optional COL-DELIM-REGEXP ROW-DELIM-REGEXP JUSTIFY MIN-CELL-WIDTH COLUMNS)" t nil) + +(autoload 'table-release "table" "\ +Convert a table into plain text by removing the frame from a table. +Remove the frame from a table and inactivate the table. This command +converts a table into plain text without frames. It is a companion to +`table-capture' which does the opposite process. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (talk talk-connect) "talk" "talk.el" (19005 47386)) +;;; Generated autoloads from talk.el + +(autoload 'talk-connect "talk" "\ +Connect to display DISPLAY for the Emacs talk group. + +\(fn DISPLAY)" t nil) + +(autoload 'talk "talk" "\ +Connect to the Emacs talk group from the current X display or tty frame. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tar-mode) "tar-mode" "tar-mode.el" (19005 47386)) +;;; Generated autoloads from tar-mode.el + +(autoload 'tar-mode "tar-mode" "\ +Major mode for viewing a tar file as a dired-like listing of its contents. +You can move around using the usual cursor motion commands. +Letters no longer insert themselves. +Type `e' to pull a file out of the tar file and into its own buffer; +or click mouse-2 on the file's line in the Tar mode buffer. +Type `c' to copy an entry from the tar file into another file on disk. + +If you edit a sub-file of this archive (as with the `e' command) and +save it with \\[save-buffer], the contents of that buffer will be +saved back into the tar-file buffer; in this way you can edit a file +inside of a tar archive without extracting it and re-archiving it. + +See also: variables `tar-update-datestamp' and `tar-anal-blocksize'. +\\{tar-mode-map} + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tcl-help-on-word inferior-tcl tcl-mode) "tcl" +;;;;;; "progmodes/tcl.el" (19005 47404)) +;;; Generated autoloads from progmodes/tcl.el + +(autoload 'tcl-mode "tcl" "\ +Major mode for editing Tcl code. +Expression and list commands understand all Tcl brackets. +Tab indents for Tcl code. +Paragraphs are separated by blank lines only. +Delete converts tabs to spaces as it moves back. + +Variables controlling indentation style: + `tcl-indent-level' + Indentation of Tcl statements within surrounding block. + `tcl-continued-indent-level' + Indentation of continuation line relative to first line of command. + +Variables controlling user interaction with mode (see variable +documentation for details): + `tcl-tab-always-indent' + Controls action of TAB key. + `tcl-auto-newline' + Non-nil means automatically newline before and after braces, brackets, + and semicolons inserted in Tcl code. + `tcl-use-smart-word-finder' + If not nil, use a smarter, Tcl-specific way to find the current + word when looking up help on a Tcl command. + +Turning on Tcl mode runs `tcl-mode-hook'. Read the documentation for +`tcl-mode-hook' to see what kinds of interesting hook functions +already exist. + +Commands: +\\{tcl-mode-map} + +\(fn)" t nil) + +(autoload 'inferior-tcl "tcl" "\ +Run inferior Tcl process. +Prefix arg means enter program name interactively. +See documentation for function `inferior-tcl-mode' for more information. + +\(fn CMD)" t nil) + +(autoload 'tcl-help-on-word "tcl" "\ +Get help on Tcl command. Default is word at point. +Prefix argument means invert sense of `tcl-use-smart-word-finder'. + +\(fn COMMAND &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (rsh telnet) "telnet" "net/telnet.el" (19005 47400)) +;;; Generated autoloads from net/telnet.el + (add-hook 'same-window-regexps "\\*telnet-.*\\*\\(\\|<[0-9]+>\\)") + +(autoload 'telnet "telnet" "\ +Open a network login connection to host named HOST (a string). +Optional arg PORT specifies alternative port to connect to. +Interactively, use \\[universal-argument] prefix to be prompted for port number. + +Communication with HOST is recorded in a buffer `*PROGRAM-HOST*' +where PROGRAM is the telnet program being used. This program +is controlled by the contents of the global variable `telnet-host-properties', +falling back on the value of the global variable `telnet-program'. +Normally input is edited in Emacs and sent a line at a time. + +\(fn HOST &optional PORT)" t nil) + (add-hook 'same-window-regexps "\\*rsh-[^-]*\\*\\(\\|<[0-9]*>\\)") + +(autoload 'rsh "telnet" "\ +Open a network login connection to host named HOST (a string). +Communication with HOST is recorded in a buffer `*rsh-HOST*'. +Normally input is edited in Emacs and sent a line at a time. + +\(fn HOST)" t nil) + +;;;*** + +;;;### (autoloads (serial-term ansi-term term make-term) "term" "term.el" +;;;;;; (19005 47386)) +;;; Generated autoloads from term.el + +(autoload 'make-term "term" "\ +Make a term process NAME in a buffer, running PROGRAM. +The name of the buffer is made by surrounding NAME with `*'s. +If there is already a running process in that buffer, it is not restarted. +Optional third arg STARTFILE is the name of a file to send the contents of to +the process. Any more args are arguments to PROGRAM. + +\(fn NAME PROGRAM &optional STARTFILE &rest SWITCHES)" nil nil) + +(autoload 'term "term" "\ +Start a terminal-emulator in a new buffer. +The buffer is in Term mode; see `term-mode' for the +commands to use in that buffer. + +\\Type \\[switch-to-buffer] to switch to another buffer. + +\(fn PROGRAM)" t nil) + +(autoload 'ansi-term "term" "\ +Start a terminal-emulator in a new buffer. + +\(fn PROGRAM &optional NEW-BUFFER-NAME)" t nil) + +(autoload 'serial-term "term" "\ +Start a terminal-emulator for a serial port in a new buffer. +PORT is the path or name of the serial port. For example, this +could be \"/dev/ttyS0\" on Unix. On Windows, this could be +\"COM1\" or \"\\\\.\\COM10\". +SPEED is the speed of the serial port in bits per second. 9600 +is a common value. SPEED can be nil, see +`serial-process-configure' for details. +The buffer is in Term mode; see `term-mode' for the commands to +use in that buffer. +\\Type \\[switch-to-buffer] to switch to another buffer. + +\(fn PORT SPEED)" t nil) + +;;;*** + +;;;### (autoloads (terminal-emulator) "terminal" "terminal.el" (19005 +;;;;;; 47386)) +;;; Generated autoloads from terminal.el + +(autoload 'terminal-emulator "terminal" "\ +Under a display-terminal emulator in BUFFER, run PROGRAM on arguments ARGS. +ARGS is a list of argument-strings. Remaining arguments are WIDTH and HEIGHT. +BUFFER's contents are made an image of the display generated by that program, +and any input typed when BUFFER is the current Emacs buffer is sent to that +program as keyboard input. + +Interactively, BUFFER defaults to \"*terminal*\" and PROGRAM and ARGS +are parsed from an input-string using your usual shell. +WIDTH and HEIGHT are determined from the size of the current window +-- WIDTH will be one less than the window's width, HEIGHT will be its height. + +To switch buffers and leave the emulator, or to give commands +to the emulator itself (as opposed to the program running under it), +type Control-^. The following character is an emulator command. +Type Control-^ twice to send it to the subprogram. +This escape character may be changed using the variable `terminal-escape-char'. + +`Meta' characters may not currently be sent through the terminal emulator. + +Here is a list of some of the variables which control the behavior +of the emulator -- see their documentation for more information: +terminal-escape-char, terminal-scrolling, terminal-more-processing, +terminal-redisplay-interval. + +This function calls the value of terminal-mode-hook if that exists +and is non-nil after the terminal buffer has been set up and the +subprocess started. + +\(fn BUFFER PROGRAM ARGS &optional WIDTH HEIGHT)" t nil) + +;;;*** + +;;;### (autoloads (testcover-this-defun) "testcover" "emacs-lisp/testcover.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emacs-lisp/testcover.el + +(autoload 'testcover-this-defun "testcover" "\ +Start coverage on function under point. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tetris) "tetris" "play/tetris.el" (19005 47402)) +;;; Generated autoloads from play/tetris.el + +(autoload 'tetris "tetris" "\ +Play the Tetris game. +Shapes drop from the top of the screen, and the user has to move and +rotate the shape to fit in with those at the bottom of the screen so +as to form complete rows. + +tetris-mode keybindings: + \\ +\\[tetris-start-game] Starts a new game of Tetris +\\[tetris-end-game] Terminates the current game +\\[tetris-pause-game] Pauses (or resumes) the current game +\\[tetris-move-left] Moves the shape one square to the left +\\[tetris-move-right] Moves the shape one square to the right +\\[tetris-rotate-prev] Rotates the shape clockwise +\\[tetris-rotate-next] Rotates the shape anticlockwise +\\[tetris-move-bottom] Drops the shape to the bottom of the playing area + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (doctex-mode tex-start-shell slitex-mode latex-mode +;;;;;; plain-tex-mode tex-mode tex-close-quote tex-open-quote tex-default-mode +;;;;;; tex-show-queue-command tex-dvi-view-command tex-alt-dvi-print-command +;;;;;; tex-dvi-print-command tex-bibtex-command latex-block-names +;;;;;; tex-start-commands tex-start-options slitex-run-command latex-run-command +;;;;;; tex-run-command tex-offer-save tex-main-file tex-first-line-header-regexp +;;;;;; tex-directory tex-shell-file-name) "tex-mode" "textmodes/tex-mode.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from textmodes/tex-mode.el + +(defvar tex-shell-file-name nil "\ +*If non-nil, the shell file name to run in the subshell used to run TeX.") + +(custom-autoload 'tex-shell-file-name "tex-mode" t) + +(defvar tex-directory "." "\ +*Directory in which temporary files are written. +You can make this `/tmp' if your TEXINPUTS has no relative directories in it +and you don't try to apply \\[tex-region] or \\[tex-buffer] when there are +`\\input' commands with relative directories.") + +(custom-autoload 'tex-directory "tex-mode" t) + +(defvar tex-first-line-header-regexp nil "\ +Regexp for matching a first line which `tex-region' should include. +If this is non-nil, it should be a regular expression string; +if it matches the first line of the file, +`tex-region' always includes the first line in the TeX run.") + +(custom-autoload 'tex-first-line-header-regexp "tex-mode" t) + +(defvar tex-main-file nil "\ +*The main TeX source file which includes this buffer's file. +The command `tex-file' runs TeX on the file specified by `tex-main-file' +if the variable is non-nil.") + +(custom-autoload 'tex-main-file "tex-mode" t) + +(defvar tex-offer-save t "\ +*If non-nil, ask about saving modified buffers before \\[tex-file] is run.") + +(custom-autoload 'tex-offer-save "tex-mode" t) + +(defvar tex-run-command "tex" "\ +*Command used to run TeX subjob. +TeX Mode sets `tex-command' to this string. +See the documentation of that variable.") + +(custom-autoload 'tex-run-command "tex-mode" t) + +(defvar latex-run-command "latex" "\ +*Command used to run LaTeX subjob. +LaTeX Mode sets `tex-command' to this string. +See the documentation of that variable.") + +(custom-autoload 'latex-run-command "tex-mode" t) + +(defvar slitex-run-command "slitex" "\ +*Command used to run SliTeX subjob. +SliTeX Mode sets `tex-command' to this string. +See the documentation of that variable.") + +(custom-autoload 'slitex-run-command "tex-mode" t) + +(defvar tex-start-options "" "\ +*TeX options to use when starting TeX. +These immediately precede the commands in `tex-start-commands' +and the input file name, with no separating space and are not shell-quoted. +If nil, TeX runs with no options. See the documentation of `tex-command'.") + +(custom-autoload 'tex-start-options "tex-mode" t) + +(defvar tex-start-commands "\\nonstopmode\\input" "\ +*TeX commands to use when starting TeX. +They are shell-quoted and precede the input file name, with a separating space. +If nil, no commands are used. See the documentation of `tex-command'.") + +(custom-autoload 'tex-start-commands "tex-mode" t) + +(defvar latex-block-names nil "\ +*User defined LaTeX block names. +Combined with `latex-standard-block-names' for minibuffer completion.") + +(custom-autoload 'latex-block-names "tex-mode" t) + +(defvar tex-bibtex-command "bibtex" "\ +*Command used by `tex-bibtex-file' to gather bibliographic data. +If this string contains an asterisk (`*'), that is replaced by the file name; +otherwise, the file name, preceded by blank, is added at the end.") + +(custom-autoload 'tex-bibtex-command "tex-mode" t) + +(defvar tex-dvi-print-command "lpr -d" "\ +*Command used by \\[tex-print] to print a .dvi file. +If this string contains an asterisk (`*'), that is replaced by the file name; +otherwise, the file name, preceded by blank, is added at the end.") + +(custom-autoload 'tex-dvi-print-command "tex-mode" t) + +(defvar tex-alt-dvi-print-command "lpr -d" "\ +*Command used by \\[tex-print] with a prefix arg to print a .dvi file. +If this string contains an asterisk (`*'), that is replaced by the file name; +otherwise, the file name, preceded by blank, is added at the end. + +If two printers are not enough of a choice, you can set the variable +`tex-alt-dvi-print-command' to an expression that asks what you want; +for example, + + (setq tex-alt-dvi-print-command + '(format \"lpr -P%s\" (read-string \"Use printer: \"))) + +would tell \\[tex-print] with a prefix argument to ask you which printer to +use.") + +(custom-autoload 'tex-alt-dvi-print-command "tex-mode" t) + +(defvar tex-dvi-view-command '(cond ((eq window-system 'x) "xdvi") ((eq window-system 'w32) "yap") (t "dvi2tty * | cat -s")) "\ +*Command used by \\[tex-view] to display a `.dvi' file. +If it is a string, that specifies the command directly. +If this string contains an asterisk (`*'), that is replaced by the file name; +otherwise, the file name, preceded by a space, is added at the end. + +If the value is a form, it is evaluated to get the command to use.") + +(custom-autoload 'tex-dvi-view-command "tex-mode" t) + +(defvar tex-show-queue-command "lpq" "\ +*Command used by \\[tex-show-print-queue] to show the print queue. +Should show the queue(s) that \\[tex-print] puts jobs on.") + +(custom-autoload 'tex-show-queue-command "tex-mode" t) + +(defvar tex-default-mode 'latex-mode "\ +*Mode to enter for a new file that might be either TeX or LaTeX. +This variable is used when it can't be determined whether the file +is plain TeX or LaTeX or what because the file contains no commands. +Normally set to either `plain-tex-mode' or `latex-mode'.") + +(custom-autoload 'tex-default-mode "tex-mode" t) + +(defvar tex-open-quote "``" "\ +*String inserted by typing \\[tex-insert-quote] to open a quotation.") + +(custom-autoload 'tex-open-quote "tex-mode" t) + +(defvar tex-close-quote "''" "\ +*String inserted by typing \\[tex-insert-quote] to close a quotation.") + +(custom-autoload 'tex-close-quote "tex-mode" t) + +(autoload 'tex-mode "tex-mode" "\ +Major mode for editing files of input for TeX, LaTeX, or SliTeX. +Tries to determine (by looking at the beginning of the file) whether +this file is for plain TeX, LaTeX, or SliTeX and calls `plain-tex-mode', +`latex-mode', or `slitex-mode', respectively. If it cannot be determined, +such as if there are no commands in the file, the value of `tex-default-mode' +says which mode to use. + +\(fn)" t nil) + +(defalias 'TeX-mode 'tex-mode) + +(defalias 'plain-TeX-mode 'plain-tex-mode) + +(defalias 'LaTeX-mode 'latex-mode) + +(autoload 'plain-tex-mode "tex-mode" "\ +Major mode for editing files of input for plain TeX. +Makes $ and } display the characters they match. +Makes \" insert `` when it seems to be the beginning of a quotation, +and '' when it appears to be the end; it inserts \" only after a \\. + +Use \\[tex-region] to run TeX on the current region, plus a \"header\" +copied from the top of the file (containing macro definitions, etc.), +running TeX under a special subshell. \\[tex-buffer] does the whole buffer. +\\[tex-file] saves the buffer and then processes the file. +\\[tex-print] prints the .dvi file made by any of these. +\\[tex-view] previews the .dvi file made by any of these. +\\[tex-bibtex-file] runs bibtex on the file of the current buffer. + +Use \\[tex-validate-buffer] to check buffer for paragraphs containing +mismatched $'s or braces. + +Special commands: +\\{plain-tex-mode-map} + +Mode variables: +tex-run-command + Command string used by \\[tex-region] or \\[tex-buffer]. +tex-directory + Directory in which to create temporary files for TeX jobs + run by \\[tex-region] or \\[tex-buffer]. +tex-dvi-print-command + Command string used by \\[tex-print] to print a .dvi file. +tex-alt-dvi-print-command + Alternative command string used by \\[tex-print] (when given a prefix + argument) to print a .dvi file. +tex-dvi-view-command + Command string used by \\[tex-view] to preview a .dvi file. +tex-show-queue-command + Command string used by \\[tex-show-print-queue] to show the print + queue that \\[tex-print] put your job on. + +Entering Plain-tex mode runs the hook `text-mode-hook', then the hook +`tex-mode-hook', and finally the hook `plain-tex-mode-hook'. When the +special subshell is initiated, the hook `tex-shell-hook' is run. + +\(fn)" t nil) + +(autoload 'latex-mode "tex-mode" "\ +Major mode for editing files of input for LaTeX. +Makes $ and } display the characters they match. +Makes \" insert `` when it seems to be the beginning of a quotation, +and '' when it appears to be the end; it inserts \" only after a \\. + +Use \\[tex-region] to run LaTeX on the current region, plus the preamble +copied from the top of the file (containing \\documentstyle, etc.), +running LaTeX under a special subshell. \\[tex-buffer] does the whole buffer. +\\[tex-file] saves the buffer and then processes the file. +\\[tex-print] prints the .dvi file made by any of these. +\\[tex-view] previews the .dvi file made by any of these. +\\[tex-bibtex-file] runs bibtex on the file of the current buffer. + +Use \\[tex-validate-buffer] to check buffer for paragraphs containing +mismatched $'s or braces. + +Special commands: +\\{latex-mode-map} + +Mode variables: +latex-run-command + Command string used by \\[tex-region] or \\[tex-buffer]. +tex-directory + Directory in which to create temporary files for LaTeX jobs + run by \\[tex-region] or \\[tex-buffer]. +tex-dvi-print-command + Command string used by \\[tex-print] to print a .dvi file. +tex-alt-dvi-print-command + Alternative command string used by \\[tex-print] (when given a prefix + argument) to print a .dvi file. +tex-dvi-view-command + Command string used by \\[tex-view] to preview a .dvi file. +tex-show-queue-command + Command string used by \\[tex-show-print-queue] to show the print + queue that \\[tex-print] put your job on. + +Entering Latex mode runs the hook `text-mode-hook', then +`tex-mode-hook', and finally `latex-mode-hook'. When the special +subshell is initiated, `tex-shell-hook' is run. + +\(fn)" t nil) + +(autoload 'slitex-mode "tex-mode" "\ +Major mode for editing files of input for SliTeX. +Makes $ and } display the characters they match. +Makes \" insert `` when it seems to be the beginning of a quotation, +and '' when it appears to be the end; it inserts \" only after a \\. + +Use \\[tex-region] to run SliTeX on the current region, plus the preamble +copied from the top of the file (containing \\documentstyle, etc.), +running SliTeX under a special subshell. \\[tex-buffer] does the whole buffer. +\\[tex-file] saves the buffer and then processes the file. +\\[tex-print] prints the .dvi file made by any of these. +\\[tex-view] previews the .dvi file made by any of these. +\\[tex-bibtex-file] runs bibtex on the file of the current buffer. + +Use \\[tex-validate-buffer] to check buffer for paragraphs containing +mismatched $'s or braces. + +Special commands: +\\{slitex-mode-map} + +Mode variables: +slitex-run-command + Command string used by \\[tex-region] or \\[tex-buffer]. +tex-directory + Directory in which to create temporary files for SliTeX jobs + run by \\[tex-region] or \\[tex-buffer]. +tex-dvi-print-command + Command string used by \\[tex-print] to print a .dvi file. +tex-alt-dvi-print-command + Alternative command string used by \\[tex-print] (when given a prefix + argument) to print a .dvi file. +tex-dvi-view-command + Command string used by \\[tex-view] to preview a .dvi file. +tex-show-queue-command + Command string used by \\[tex-show-print-queue] to show the print + queue that \\[tex-print] put your job on. + +Entering SliTeX mode runs the hook `text-mode-hook', then the hook +`tex-mode-hook', then the hook `latex-mode-hook', and finally the hook +`slitex-mode-hook'. When the special subshell is initiated, the hook +`tex-shell-hook' is run. + +\(fn)" t nil) + +(autoload 'tex-start-shell "tex-mode" "\ +Not documented + +\(fn)" nil nil) + +(autoload 'doctex-mode "tex-mode" "\ +Major mode to edit DocTeX files. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (texi2info texinfo-format-region texinfo-format-buffer) +;;;;;; "texinfmt" "textmodes/texinfmt.el" (19005 47406)) +;;; Generated autoloads from textmodes/texinfmt.el + +(autoload 'texinfo-format-buffer "texinfmt" "\ +Process the current buffer as texinfo code, into an Info file. +The Info file output is generated in a buffer visiting the Info file +name specified in the @setfilename command. + +Non-nil argument (prefix, if interactive) means don't make tag table +and don't split the file if large. You can use `Info-tagify' and +`Info-split' to do these manually. + +\(fn &optional NOSPLIT)" t nil) + +(autoload 'texinfo-format-region "texinfmt" "\ +Convert the current region of the Texinfo file to Info format. +This lets you see what that part of the file will look like in Info. +The command is bound to \\[texinfo-format-region]. The text that is +converted to Info is stored in a temporary buffer. + +\(fn REGION-BEGINNING REGION-END)" t nil) + +(autoload 'texi2info "texinfmt" "\ +Convert the current buffer (written in Texinfo code) into an Info file. +The Info file output is generated in a buffer visiting the Info file +names specified in the @setfilename command. + +This function automatically updates all node pointers and menus, and +creates a master menu. This work is done on a temporary buffer that +is automatically removed when the Info file is created. The original +Texinfo source buffer is not changed. + +Non-nil argument (prefix, if interactive) means don't split the file +if large. You can use `Info-split' to do this manually. + +\(fn &optional NOSPLIT)" t nil) + +;;;*** + +;;;### (autoloads (texinfo-mode texinfo-close-quote texinfo-open-quote) +;;;;;; "texinfo" "textmodes/texinfo.el" (19005 47406)) +;;; Generated autoloads from textmodes/texinfo.el + +(defvar texinfo-open-quote "``" "\ +String inserted by typing \\[texinfo-insert-quote] to open a quotation.") + +(custom-autoload 'texinfo-open-quote "texinfo" t) + +(defvar texinfo-close-quote "''" "\ +String inserted by typing \\[texinfo-insert-quote] to close a quotation.") + +(custom-autoload 'texinfo-close-quote "texinfo" t) + +(autoload 'texinfo-mode "texinfo" "\ +Major mode for editing Texinfo files. + + It has these extra commands: +\\{texinfo-mode-map} + + These are files that are used as input for TeX to make printed manuals +and also to be turned into Info files with \\[makeinfo-buffer] or +the `makeinfo' program. These files must be written in a very restricted and +modified version of TeX input format. + + Editing commands are like text-mode except that the syntax table is +set up so expression commands skip Texinfo bracket groups. To see +what the Info version of a region of the Texinfo file will look like, +use \\[makeinfo-region], which runs `makeinfo' on the current region. + + You can show the structure of a Texinfo file with \\[texinfo-show-structure]. +This command shows the structure of a Texinfo file by listing the +lines with the @-sign commands for @chapter, @section, and the like. +These lines are displayed in another window called the *Occur* window. +In that window, you can position the cursor over one of the lines and +use \\[occur-mode-goto-occurrence], to jump to the corresponding spot +in the Texinfo file. + + In addition, Texinfo mode provides commands that insert various +frequently used @-sign commands into the buffer. You can use these +commands to save keystrokes. And you can insert balanced braces with +\\[texinfo-insert-braces] and later use the command \\[up-list] to +move forward past the closing brace. + +Also, Texinfo mode provides functions for automatically creating or +updating menus and node pointers. These functions + + * insert the `Next', `Previous' and `Up' pointers of a node, + * insert or update the menu for a section, and + * create a master menu for a Texinfo source file. + +Here are the functions: + + texinfo-update-node \\[texinfo-update-node] + texinfo-every-node-update \\[texinfo-every-node-update] + texinfo-sequential-node-update + + texinfo-make-menu \\[texinfo-make-menu] + texinfo-all-menus-update \\[texinfo-all-menus-update] + texinfo-master-menu + + texinfo-indent-menu-description (column &optional region-p) + +The `texinfo-column-for-description' variable specifies the column to +which menu descriptions are indented. + +Passed an argument (a prefix argument, if interactive), the +`texinfo-update-node' and `texinfo-make-menu' functions do their jobs +in the region. + +To use the updating commands, you must structure your Texinfo file +hierarchically, such that each `@node' line, with the exception of the +Top node, is accompanied by some kind of section line, such as an +`@chapter' or `@section' line. + +If the file has a `top' node, it must be called `top' or `Top' and +be the first node in the file. + +Entering Texinfo mode calls the value of `text-mode-hook', and then the +value of `texinfo-mode-hook'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (thai-composition-function thai-compose-buffer +;;;;;; thai-compose-string thai-compose-region) "thai-util" "language/thai-util.el" +;;;;;; (19005 47397)) +;;; Generated autoloads from language/thai-util.el + +(autoload 'thai-compose-region "thai-util" "\ +Compose Thai characters in the region. +When called from a program, expects two arguments, +positions (integers or markers) specifying the region. + +\(fn BEG END)" t nil) + +(autoload 'thai-compose-string "thai-util" "\ +Compose Thai characters in STRING and return the resulting string. + +\(fn STRING)" nil nil) + +(autoload 'thai-compose-buffer "thai-util" "\ +Compose Thai characters in the current buffer. + +\(fn)" t nil) + +(autoload 'thai-composition-function "thai-util" "\ +Not documented + +\(fn GSTRING)" nil nil) + +;;;*** + +;;;### (autoloads (list-at-point number-at-point symbol-at-point +;;;;;; sexp-at-point thing-at-point bounds-of-thing-at-point forward-thing) +;;;;;; "thingatpt" "thingatpt.el" (19005 47386)) +;;; Generated autoloads from thingatpt.el + +(autoload 'forward-thing "thingatpt" "\ +Move forward to the end of the Nth next THING. + +\(fn THING &optional N)" nil nil) + +(autoload 'bounds-of-thing-at-point "thingatpt" "\ +Determine the start and end buffer locations for the THING at point. +THING is a symbol which specifies the kind of syntactic entity you want. +Possibilities include `symbol', `list', `sexp', `defun', `filename', `url', +`email', `word', `sentence', `whitespace', `line', `page' and others. + +See the file `thingatpt.el' for documentation on how to define +a symbol as a valid THING. + +The value is a cons cell (START . END) giving the start and end positions +of the textual entity that was found. + +\(fn THING)" nil nil) + +(autoload 'thing-at-point "thingatpt" "\ +Return the THING at point. +THING is a symbol which specifies the kind of syntactic entity you want. +Possibilities include `symbol', `list', `sexp', `defun', `filename', `url', +`email', `word', `sentence', `whitespace', `line', `page' and others. + +See the file `thingatpt.el' for documentation on how to define +a symbol as a valid THING. + +\(fn THING)" nil nil) + +(autoload 'sexp-at-point "thingatpt" "\ +Return the sexp at point, or nil if none is found. + +\(fn)" nil nil) + +(autoload 'symbol-at-point "thingatpt" "\ +Return the symbol at point, or nil if none is found. + +\(fn)" nil nil) + +(autoload 'number-at-point "thingatpt" "\ +Return the number at point, or nil if none is found. + +\(fn)" nil nil) + +(autoload 'list-at-point "thingatpt" "\ +Return the Lisp list at point, or nil if none is found. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (thumbs-dired-setroot thumbs-dired-show thumbs-dired-show-marked +;;;;;; thumbs-show-from-dir thumbs-find-thumb) "thumbs" "thumbs.el" +;;;;;; (19005 47386)) +;;; Generated autoloads from thumbs.el + +(autoload 'thumbs-find-thumb "thumbs" "\ +Display the thumbnail for IMG. + +\(fn IMG)" t nil) + +(autoload 'thumbs-show-from-dir "thumbs" "\ +Make a preview buffer for all images in DIR. +Optional argument REG to select file matching a regexp, +and SAME-WINDOW to show thumbs in the same window. + +\(fn DIR &optional REG SAME-WINDOW)" t nil) + +(autoload 'thumbs-dired-show-marked "thumbs" "\ +In dired, make a thumbs buffer with marked files. + +\(fn)" t nil) + +(autoload 'thumbs-dired-show "thumbs" "\ +In dired, make a thumbs buffer with all files in current directory. + +\(fn)" t nil) + +(defalias 'thumbs 'thumbs-show-from-dir) + +(autoload 'thumbs-dired-setroot "thumbs" "\ +In dired, call the setroot program on the image at point. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tibetan-pre-write-canonicalize-for-unicode tibetan-pre-write-conversion +;;;;;; tibetan-post-read-conversion tibetan-compose-buffer tibetan-decompose-buffer +;;;;;; tibetan-decompose-string tibetan-decompose-region tibetan-compose-region +;;;;;; tibetan-compose-string tibetan-transcription-to-tibetan tibetan-tibetan-to-transcription +;;;;;; tibetan-char-p) "tibet-util" "language/tibet-util.el" (19005 +;;;;;; 47397)) +;;; Generated autoloads from language/tibet-util.el + +(autoload 'tibetan-char-p "tibet-util" "\ +Check if char CH is Tibetan character. +Returns non-nil if CH is Tibetan. Otherwise, returns nil. + +\(fn CH)" nil nil) + +(autoload 'tibetan-tibetan-to-transcription "tibet-util" "\ +Transcribe Tibetan string STR and return the corresponding Roman string. + +\(fn STR)" nil nil) + +(autoload 'tibetan-transcription-to-tibetan "tibet-util" "\ +Convert Tibetan Roman string STR to Tibetan character string. +The returned string has no composition information. + +\(fn STR)" nil nil) + +(autoload 'tibetan-compose-string "tibet-util" "\ +Compose Tibetan string STR. + +\(fn STR)" nil nil) + +(autoload 'tibetan-compose-region "tibet-util" "\ +Compose Tibetan text the region BEG and END. + +\(fn BEG END)" t nil) + +(autoload 'tibetan-decompose-region "tibet-util" "\ +Decompose Tibetan text in the region FROM and TO. +This is different from decompose-region because precomposed Tibetan characters +are decomposed into normal Tibetan character sequences. + +\(fn FROM TO)" t nil) + +(autoload 'tibetan-decompose-string "tibet-util" "\ +Decompose Tibetan string STR. +This is different from decompose-string because precomposed Tibetan characters +are decomposed into normal Tibetan character sequences. + +\(fn STR)" nil nil) + +(autoload 'tibetan-decompose-buffer "tibet-util" "\ +Decomposes Tibetan characters in the buffer into their components. +See also the documentation of the function `tibetan-decompose-region'. + +\(fn)" t nil) + +(autoload 'tibetan-compose-buffer "tibet-util" "\ +Composes Tibetan character components in the buffer. +See also docstring of the function tibetan-compose-region. + +\(fn)" t nil) + +(autoload 'tibetan-post-read-conversion "tibet-util" "\ +Not documented + +\(fn LEN)" nil nil) + +(autoload 'tibetan-pre-write-conversion "tibet-util" "\ +Not documented + +\(fn FROM TO)" nil nil) + +(autoload 'tibetan-pre-write-canonicalize-for-unicode "tibet-util" "\ +Not documented + +\(fn FROM TO)" nil nil) + +;;;*** + +;;;### (autoloads (tildify-buffer tildify-region) "tildify" "textmodes/tildify.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from textmodes/tildify.el + +(autoload 'tildify-region "tildify" "\ +Add hard spaces in the region between BEG and END. +See variables `tildify-pattern-alist', `tildify-string-alist', and +`tildify-ignored-environments-alist' for information about configuration +parameters. +This function performs no refilling of the changed text. + +\(fn BEG END)" t nil) + +(autoload 'tildify-buffer "tildify" "\ +Add hard spaces in the current buffer. +See variables `tildify-pattern-alist', `tildify-string-alist', and +`tildify-ignored-environments-alist' for information about configuration +parameters. +This function performs no refilling of the changed text. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (emacs-init-time emacs-uptime display-time-world +;;;;;; display-time-mode display-time display-time-day-and-date) +;;;;;; "time" "time.el" (19005 47386)) +;;; Generated autoloads from time.el + +(defvar display-time-day-and-date nil "\ +*Non-nil means \\[display-time] should display day and date as well as time.") + +(custom-autoload 'display-time-day-and-date "time" t) + +(autoload 'display-time "time" "\ +Enable display of time, load level, and mail flag in mode lines. +This display updates automatically every minute. +If `display-time-day-and-date' is non-nil, the current day and date +are displayed as well. +This runs the normal hook `display-time-hook' after each update. + +\(fn)" t nil) + +(defvar display-time-mode nil "\ +Non-nil if Display-Time mode is enabled. +See the command `display-time-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `display-time-mode'.") + +(custom-autoload 'display-time-mode "time" nil) + +(autoload 'display-time-mode "time" "\ +Toggle display of time, load level, and mail flag in mode lines. +With a numeric arg, enable this display if arg is positive. + +When this display is enabled, it updates automatically every minute. +If `display-time-day-and-date' is non-nil, the current day and date +are displayed as well. +This runs the normal hook `display-time-hook' after each update. + +\(fn &optional ARG)" t nil) + +(autoload 'display-time-world "time" "\ +Enable updating display of times in various time zones. +`display-time-world-list' specifies the zones. +To turn off the world time display, go to that window and type `q'. + +\(fn)" t nil) + +(autoload 'emacs-uptime "time" "\ +Return a string giving the uptime of this instance of Emacs. +FORMAT is a string to format the result, using `format-seconds'. +For example, the Unix uptime command format is \"%D, %z%2h:%.2m\". + +\(fn &optional FORMAT)" t nil) + +(autoload 'emacs-init-time "time" "\ +Return a string giving the duration of the Emacs initialization. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (format-seconds safe-date-to-time time-to-days +;;;;;; time-to-day-in-year date-leap-year-p days-between date-to-day +;;;;;; time-add time-subtract time-since days-to-time time-less-p +;;;;;; seconds-to-time time-to-seconds date-to-time) "time-date" +;;;;;; "calendar/time-date.el" (19005 47389)) +;;; Generated autoloads from calendar/time-date.el + +(autoload 'date-to-time "time-date" "\ +Parse a string DATE that represents a date-time and return a time value. + +\(fn DATE)" nil nil) + +(autoload 'time-to-seconds "time-date" "\ +Convert time value TIME to a floating point number. +You can use `float-time' instead. + +\(fn TIME)" nil nil) + +(autoload 'seconds-to-time "time-date" "\ +Convert SECONDS (a floating point number) to a time value. + +\(fn SECONDS)" nil nil) + +(autoload 'time-less-p "time-date" "\ +Say whether time value T1 is less than time value T2. + +\(fn T1 T2)" nil nil) + +(autoload 'days-to-time "time-date" "\ +Convert DAYS into a time value. + +\(fn DAYS)" nil nil) + +(autoload 'time-since "time-date" "\ +Return the time elapsed since TIME. +TIME should be either a time value or a date-time string. + +\(fn TIME)" nil nil) + +(defalias 'subtract-time 'time-subtract) + +(autoload 'time-subtract "time-date" "\ +Subtract two time values, T1 minus T2. +Return the difference in the format of a time value. + +\(fn T1 T2)" nil nil) + +(autoload 'time-add "time-date" "\ +Add two time values T1 and T2. One should represent a time difference. + +\(fn T1 T2)" nil nil) + +(autoload 'date-to-day "time-date" "\ +Return the number of days between year 1 and DATE. +DATE should be a date-time string. + +\(fn DATE)" nil nil) + +(autoload 'days-between "time-date" "\ +Return the number of days between DATE1 and DATE2. +DATE1 and DATE2 should be date-time strings. + +\(fn DATE1 DATE2)" nil nil) + +(autoload 'date-leap-year-p "time-date" "\ +Return t if YEAR is a leap year. + +\(fn YEAR)" nil nil) + +(autoload 'time-to-day-in-year "time-date" "\ +Return the day number within the year corresponding to TIME. + +\(fn TIME)" nil nil) + +(autoload 'time-to-days "time-date" "\ +The number of days between the Gregorian date 0001-12-31bce and TIME. +TIME should be a time value. +The Gregorian date Sunday, December 31, 1bce is imaginary. + +\(fn TIME)" nil nil) + +(autoload 'safe-date-to-time "time-date" "\ +Parse a string DATE that represents a date-time and return a time value. +If DATE is malformed, return a time value of zeros. + +\(fn DATE)" nil nil) + +(autoload 'format-seconds "time-date" "\ +Use format control STRING to format the number SECONDS. +The valid format specifiers are: +%y is the number of (365-day) years. +%d is the number of days. +%h is the number of hours. +%m is the number of minutes. +%s is the number of seconds. +%z is a non-printing control flag (see below). +%% is a literal \"%\". + +Upper-case specifiers are followed by the unit-name (e.g. \"years\"). +Lower-case specifiers return only the unit. + +\"%\" may be followed by a number specifying a width, with an +optional leading \".\" for zero-padding. For example, \"%.3Y\" will +return something of the form \"001 year\". + +The \"%z\" specifier does not print anything. When it is used, specifiers +must be given in order of decreasing size. To the left of \"%z\", nothing +is output until the first non-zero unit is encountered. + +This function does not work for SECONDS greater than `most-positive-fixnum'. + +\(fn STRING SECONDS)" nil nil) + +;;;*** + +;;;### (autoloads (time-stamp-toggle-active time-stamp) "time-stamp" +;;;;;; "time-stamp.el" (19005 47386)) +;;; Generated autoloads from time-stamp.el +(put 'time-stamp-format 'safe-local-variable 'stringp) +(put 'time-stamp-time-zone 'safe-local-variable 'string-or-null-p) +(put 'time-stamp-line-limit 'safe-local-variable 'integerp) +(put 'time-stamp-start 'safe-local-variable 'stringp) +(put 'time-stamp-end 'safe-local-variable 'stringp) +(put 'time-stamp-inserts-lines 'safe-local-variable 'symbolp) +(put 'time-stamp-count 'safe-local-variable 'integerp) +(put 'time-stamp-pattern 'safe-local-variable 'stringp) + +(autoload 'time-stamp "time-stamp" "\ +Update the time stamp string(s) in the buffer. +A template in a file can be automatically updated with a new time stamp +every time you save the file. Add this line to your .emacs file: + (add-hook 'before-save-hook 'time-stamp) +or customize `before-save-hook' through Custom. +Normally the template must appear in the first 8 lines of a file and +look like one of the following: + Time-stamp: <> + Time-stamp: \" \" +The time stamp is written between the brackets or quotes: + Time-stamp: <2001-02-18 10:20:51 gildea> +The time stamp is updated only if the variable `time-stamp-active' is non-nil. +The format of the time stamp is set by the variable `time-stamp-pattern' or +`time-stamp-format'. The variables `time-stamp-pattern', +`time-stamp-line-limit', `time-stamp-start', `time-stamp-end', +`time-stamp-count', and `time-stamp-inserts-lines' control finding +the template. + +\(fn)" t nil) + +(autoload 'time-stamp-toggle-active "time-stamp" "\ +Toggle `time-stamp-active', setting whether \\[time-stamp] updates a buffer. +With ARG, turn time stamping on if and only if arg is positive. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (timeclock-when-to-leave-string timeclock-workday-elapsed-string +;;;;;; timeclock-workday-remaining-string timeclock-reread-log timeclock-query-out +;;;;;; timeclock-change timeclock-status-string timeclock-out timeclock-in +;;;;;; timeclock-modeline-display) "timeclock" "calendar/timeclock.el" +;;;;;; (19005 47389)) +;;; Generated autoloads from calendar/timeclock.el + +(autoload 'timeclock-modeline-display "timeclock" "\ +Toggle display of the amount of time left today in the modeline. +If `timeclock-use-display-time' is non-nil (the default), then +the function `display-time-mode' must be active, and the modeline +will be updated whenever the time display is updated. Otherwise, +the timeclock will use its own sixty second timer to do its +updating. With prefix ARG, turn modeline display on if and only +if ARG is positive. Returns the new status of timeclock modeline +display (non-nil means on). + +\(fn &optional ARG)" t nil) + +(autoload 'timeclock-in "timeclock" "\ +Clock in, recording the current time moment in the timelog. +With a numeric prefix ARG, record the fact that today has only that +many hours in it to be worked. If ARG is a non-numeric prefix argument +\(non-nil, but not a number), 0 is assumed (working on a holiday or +weekend). *If not called interactively, ARG should be the number of +_seconds_ worked today*. This feature only has effect the first time +this function is called within a day. + +PROJECT is the project being clocked into. If PROJECT is nil, and +FIND-PROJECT is non-nil -- or the user calls `timeclock-in' +interactively -- call the function `timeclock-get-project-function' to +discover the name of the project. + +\(fn &optional ARG PROJECT FIND-PROJECT)" t nil) + +(autoload 'timeclock-out "timeclock" "\ +Clock out, recording the current time moment in the timelog. +If a prefix ARG is given, the user has completed the project that was +begun during the last time segment. + +REASON is the user's reason for clocking out. If REASON is nil, and +FIND-REASON is non-nil -- or the user calls `timeclock-out' +interactively -- call the function `timeclock-get-reason-function' to +discover the reason. + +\(fn &optional ARG REASON FIND-REASON)" t nil) + +(autoload 'timeclock-status-string "timeclock" "\ +Report the overall timeclock status at the present moment. +If SHOW-SECONDS is non-nil, display second resolution. +If TODAY-ONLY is non-nil, the display will be relative only to time +worked today, ignoring the time worked on previous days. + +\(fn &optional SHOW-SECONDS TODAY-ONLY)" t nil) + +(autoload 'timeclock-change "timeclock" "\ +Change to working on a different project. +This clocks out of the current project, then clocks in on a new one. +With a prefix ARG, consider the previous project as finished at the +time of changeover. PROJECT is the name of the last project you were +working on. + +\(fn &optional ARG PROJECT)" t nil) + +(autoload 'timeclock-query-out "timeclock" "\ +Ask the user whether to clock out. +This is a useful function for adding to `kill-emacs-query-functions'. + +\(fn)" nil nil) + +(autoload 'timeclock-reread-log "timeclock" "\ +Re-read the timeclock, to account for external changes. +Returns the new value of `timeclock-discrepancy'. + +\(fn)" t nil) + +(autoload 'timeclock-workday-remaining-string "timeclock" "\ +Return a string representing the amount of time left today. +Display second resolution if SHOW-SECONDS is non-nil. If TODAY-ONLY +is non-nil, the display will be relative only to time worked today. +See `timeclock-relative' for more information about the meaning of +\"relative to today\". + +\(fn &optional SHOW-SECONDS TODAY-ONLY)" t nil) + +(autoload 'timeclock-workday-elapsed-string "timeclock" "\ +Return a string representing the amount of time worked today. +Display seconds resolution if SHOW-SECONDS is non-nil. If RELATIVE is +non-nil, the amount returned will be relative to past time worked. + +\(fn &optional SHOW-SECONDS)" t nil) + +(autoload 'timeclock-when-to-leave-string "timeclock" "\ +Return a string representing the end of today's workday. +This string is relative to the value of `timeclock-workday'. If +SHOW-SECONDS is non-nil, the value printed/returned will include +seconds. If TODAY-ONLY is non-nil, the value returned will be +relative only to the time worked today, and not to past time. + +\(fn &optional SHOW-SECONDS TODAY-ONLY)" t nil) + +;;;*** + +;;;### (autoloads (batch-titdic-convert titdic-convert) "titdic-cnv" +;;;;;; "international/titdic-cnv.el" (19005 47395)) +;;; Generated autoloads from international/titdic-cnv.el + +(autoload 'titdic-convert "titdic-cnv" "\ +Convert a TIT dictionary of FILENAME into a Quail package. +Optional argument DIRNAME if specified is the directory name under which +the generated Quail package is saved. + +\(fn FILENAME &optional DIRNAME)" t nil) + +(autoload 'batch-titdic-convert "titdic-cnv" "\ +Run `titdic-convert' on the files remaining on the command line. +Use this from the command line, with `-batch'; +it won't work in an interactive Emacs. +For example, invoke \"emacs -batch -f batch-titdic-convert XXX.tit\" to + generate Quail package file \"xxx.el\" from TIT dictionary file \"XXX.tit\". +To get complete usage, invoke \"emacs -batch -f batch-titdic-convert -h\". + +\(fn &optional FORCE)" nil nil) + +;;;*** + +;;;### (autoloads (tmm-prompt tmm-menubar-mouse tmm-menubar) "tmm" +;;;;;; "tmm.el" (19005 47386)) +;;; Generated autoloads from tmm.el + (define-key global-map "\M-`" 'tmm-menubar) + (define-key global-map [menu-bar mouse-1] 'tmm-menubar-mouse) + +(autoload 'tmm-menubar "tmm" "\ +Text-mode emulation of looking and choosing from a menubar. +See the documentation for `tmm-prompt'. +X-POSITION, if non-nil, specifies a horizontal position within the menu bar; +we make that menu bar item (the one at that position) the default choice. + +\(fn &optional X-POSITION)" t nil) + +(autoload 'tmm-menubar-mouse "tmm" "\ +Text-mode emulation of looking and choosing from a menubar. +This command is used when you click the mouse in the menubar +on a console which has no window system but does have a mouse. +See the documentation for `tmm-prompt'. + +\(fn EVENT)" t nil) + +(autoload 'tmm-prompt "tmm" "\ +Text-mode emulation of calling the bindings in keymap. +Creates a text-mode menu of possible choices. You can access the elements +in the menu in two ways: + *) via history mechanism from minibuffer; + *) Or via completion-buffer that is automatically shown. +The last alternative is currently a hack, you cannot use mouse reliably. + +MENU is like the MENU argument to `x-popup-menu': either a +keymap or an alist of alists. +DEFAULT-ITEM, if non-nil, specifies an initial default choice. +Its value should be an event that has a binding in MENU. + +\(fn MENU &optional IN-POPUP DEFAULT-ITEM)" nil nil) + +;;;*** + +;;;### (autoloads (todo-show todo-cp todo-mode todo-print todo-top-priorities +;;;;;; todo-insert-item todo-add-item-non-interactively todo-add-category) +;;;;;; "todo-mode" "calendar/todo-mode.el" (19005 47389)) +;;; Generated autoloads from calendar/todo-mode.el + +(autoload 'todo-add-category "todo-mode" "\ +Add new category CAT to the TODO list. + +\(fn &optional CAT)" t nil) + +(autoload 'todo-add-item-non-interactively "todo-mode" "\ +Insert NEW-ITEM in TODO list as a new entry in CATEGORY. + +\(fn NEW-ITEM CATEGORY)" nil nil) + +(autoload 'todo-insert-item "todo-mode" "\ +Insert new TODO list entry. +With a prefix argument solicit the category, otherwise use the current +category. + +\(fn ARG)" t nil) + +(autoload 'todo-top-priorities "todo-mode" "\ +List top priorities for each category. + +Number of entries for each category is given by NOF-PRIORITIES which +defaults to 'todo-show-priorities'. + +If CATEGORY-PR-PAGE is non-nil, a page separator '^L' is inserted +between each category. + +\(fn &optional NOF-PRIORITIES CATEGORY-PR-PAGE)" t nil) + +(autoload 'todo-print "todo-mode" "\ +Print todo summary using `todo-print-function'. +If CATEGORY-PR-PAGE is non-nil, a page separator `^L' is inserted +between each category. + +Number of entries for each category is given by `todo-print-priorities'. + +\(fn &optional CATEGORY-PR-PAGE)" t nil) + +(autoload 'todo-mode "todo-mode" "\ +Major mode for editing TODO lists. + +\\{todo-mode-map} + +\(fn)" t nil) + +(autoload 'todo-cp "todo-mode" "\ +Make a diary entry appear only in the current date's diary. + +\(fn)" nil nil) + +(autoload 'todo-show "todo-mode" "\ +Show TODO list. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tool-bar-local-item-from-menu tool-bar-add-item-from-menu +;;;;;; tool-bar-local-item tool-bar-add-item toggle-tool-bar-mode-from-frame) +;;;;;; "tool-bar" "tool-bar.el" (19005 47386)) +;;; Generated autoloads from tool-bar.el + +(autoload 'toggle-tool-bar-mode-from-frame "tool-bar" "\ +Toggle tool bar on or off, based on the status of the current frame. +See `tool-bar-mode' for more information. + +\(fn &optional ARG)" t nil) + +(put 'tool-bar-mode 'standard-value '(t)) + +(autoload 'tool-bar-add-item "tool-bar" "\ +Add an item to the tool bar. +ICON names the image, DEF is the key definition and KEY is a symbol +for the fake function key in the menu keymap. Remaining arguments +PROPS are additional items to add to the menu item specification. See +Info node `(elisp)Tool Bar'. Items are added from left to right. + +ICON is the base name of a file containing the image to use. The +function will first try to use low-color/ICON.xpm if `display-color-cells' +is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally +ICON.xbm, using `find-image'. + +Use this function only to make bindings in the global value of `tool-bar-map'. +To define items in any other map, use `tool-bar-local-item'. + +\(fn ICON DEF KEY &rest PROPS)" nil nil) + +(autoload 'tool-bar-local-item "tool-bar" "\ +Add an item to the tool bar in map MAP. +ICON names the image, DEF is the key definition and KEY is a symbol +for the fake function key in the menu keymap. Remaining arguments +PROPS are additional items to add to the menu item specification. See +Info node `(elisp)Tool Bar'. Items are added from left to right. + +ICON is the base name of a file containing the image to use. The +function will first try to use low-color/ICON.xpm if `display-color-cells' +is less or equal to 256, then ICON.xpm, then ICON.pbm, and finally +ICON.xbm, using `find-image'. + +\(fn ICON DEF KEY MAP &rest PROPS)" nil nil) + +(autoload 'tool-bar-add-item-from-menu "tool-bar" "\ +Define tool bar binding for COMMAND in keymap MAP using the given ICON. +This makes a binding for COMMAND in `tool-bar-map', copying its +binding from the menu bar in MAP (which defaults to `global-map'), but +modifies the binding by adding an image specification for ICON. It +finds ICON just like `tool-bar-add-item'. PROPS are additional +properties to add to the binding. + +MAP must contain appropriate binding for `[menu-bar]' which holds a keymap. + +Use this function only to make bindings in the global value of `tool-bar-map'. +To define items in any other map, use `tool-bar-local-item-from-menu'. + +\(fn COMMAND ICON &optional MAP &rest PROPS)" nil nil) + +(autoload 'tool-bar-local-item-from-menu "tool-bar" "\ +Define local tool bar binding for COMMAND using the given ICON. +This makes a binding for COMMAND in IN-MAP, copying its binding from +the menu bar in FROM-MAP (which defaults to `global-map'), but +modifies the binding by adding an image specification for ICON. It +finds ICON just like `tool-bar-add-item'. PROPS are additional +properties to add to the binding. + +FROM-MAP must contain appropriate binding for `[menu-bar]' which +holds a keymap. + +\(fn COMMAND ICON IN-MAP &optional FROM-MAP &rest PROPS)" nil nil) + +;;;*** + +;;;### (autoloads (tpu-edt-on tpu-edt-mode) "tpu-edt" "emulation/tpu-edt.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emulation/tpu-edt.el + +(defvar tpu-edt-mode nil "\ +Non-nil if Tpu-Edt mode is enabled. +See the command `tpu-edt-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `tpu-edt-mode'.") + +(custom-autoload 'tpu-edt-mode "tpu-edt" nil) + +(autoload 'tpu-edt-mode "tpu-edt" "\ +TPU/edt emulation. + +\(fn &optional ARG)" t nil) + +(defalias 'tpu-edt 'tpu-edt-on) + +(autoload 'tpu-edt-on "tpu-edt" "\ +Turn on TPU/edt emulation. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tpu-mapper) "tpu-mapper" "emulation/tpu-mapper.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emulation/tpu-mapper.el + +(autoload 'tpu-mapper "tpu-mapper" "\ +Create an Emacs lisp file defining the TPU-edt keypad for X-windows. + +This command displays an instruction screen showing the TPU-edt keypad +and asks you to press the TPU-edt editing keys. It uses the keys you +press to create an Emacs Lisp file that will define a TPU-edt keypad +for your X server. You can even re-arrange the standard EDT keypad to +suit your tastes (or to cope with those silly Sun and PC keypads). + +Finally, you will be prompted for the name of the file to store the key +definitions. If you chose the default, TPU-edt will find it and load it +automatically. If you specify a different file name, you will need to +set the variable ``tpu-xkeys-file'' before starting TPU-edt. Here's how +you might go about doing that in your .emacs file. + + (setq tpu-xkeys-file (expand-file-name \"~/.my-emacs-x-keys\")) + (tpu-edt) + +Known Problems: + +Sometimes, tpu-mapper will ignore a key you press, and just continue to +prompt for the same key. This can happen when your window manager sucks +up the key and doesn't pass it on to Emacs, or it could be an Emacs bug. +Either way, there's nothing that tpu-mapper can do about it. You must +press RETURN, to skip the current key and continue. Later, you and/or +your local X guru can try to figure out why the key is being ignored. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tq-create) "tq" "emacs-lisp/tq.el" (19005 47390)) +;;; Generated autoloads from emacs-lisp/tq.el + +(autoload 'tq-create "tq" "\ +Create and return a transaction queue communicating with PROCESS. +PROCESS should be a subprocess capable of sending and receiving +streams of bytes. It may be a local process, or it may be connected +to a tcp server on another machine. + +\(fn PROCESS)" nil nil) + +;;;*** + +;;;### (autoloads (trace-function-background trace-function trace-buffer) +;;;;;; "trace" "emacs-lisp/trace.el" (19005 47390)) +;;; Generated autoloads from emacs-lisp/trace.el + +(defvar trace-buffer "*trace-output*" "\ +*Trace output will by default go to that buffer.") + +(custom-autoload 'trace-buffer "trace" t) + +(autoload 'trace-function "trace" "\ +Traces FUNCTION with trace output going to BUFFER. +For every call of FUNCTION Lisp-style trace messages that display argument +and return values will be inserted into BUFFER. This function generates the +trace advice for FUNCTION and activates it together with any other advice +there might be!! The trace BUFFER will popup whenever FUNCTION is called. +Do not use this to trace functions that switch buffers or do any other +display oriented stuff, use `trace-function-background' instead. + +\(fn FUNCTION &optional BUFFER)" t nil) + +(autoload 'trace-function-background "trace" "\ +Traces FUNCTION with trace output going quietly to BUFFER. +When this tracing is enabled, every call to FUNCTION writes +a Lisp-style trace message (showing the arguments and return value) +into BUFFER. This function generates advice to trace FUNCTION +and activates it together with any other advice there might be. +The trace output goes to BUFFER quietly, without changing +the window or buffer configuration. + +BUFFER defaults to `trace-buffer'. + +\(fn FUNCTION &optional BUFFER)" t nil) + +;;;*** + +;;;### (autoloads (tramp-unload-tramp tramp-completion-handle-file-name-completion +;;;;;; tramp-completion-handle-file-name-all-completions tramp-unload-file-name-handlers +;;;;;; tramp-file-name-handler tramp-syntax tramp-mode) "tramp" +;;;;;; "net/tramp.el" (19028 40363)) +;;; Generated autoloads from net/tramp.el + +(defvar tramp-mode t "\ +*Whether Tramp is enabled. +If it is set to nil, all remote file names are used literally.") + +(custom-autoload 'tramp-mode "tramp" t) + +(defvar tramp-syntax (if (featurep 'xemacs) 'sep 'ftp) "\ +Tramp filename syntax to be used. + +It can have the following values: + + 'ftp -- Ange-FTP respective EFS like syntax (GNU Emacs default) + 'sep -- Syntax as defined for XEmacs (not available yet for GNU Emacs) + 'url -- URL-like syntax.") + +(custom-autoload 'tramp-syntax "tramp" t) + +(defconst tramp-file-name-regexp-unified "\\`/\\([^[/:]+\\|[^/]+]\\):" "\ +Value for `tramp-file-name-regexp' for unified remoting. +Emacs (not XEmacs) uses a unified filename syntax for Ange-FTP and +Tramp. See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-file-name-regexp-separate "\\`/\\[.*\\]" "\ +Value for `tramp-file-name-regexp' for separate remoting. +XEmacs uses a separate filename syntax for Tramp and EFS. +See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-file-name-regexp-url "\\`/[^/:]+://" "\ +Value for `tramp-file-name-regexp' for URL-like remoting. +See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-file-name-regexp (cond ((equal tramp-syntax 'ftp) tramp-file-name-regexp-unified) ((equal tramp-syntax 'sep) tramp-file-name-regexp-separate) ((equal tramp-syntax 'url) tramp-file-name-regexp-url) (t (error "Wrong `tramp-syntax' defined"))) "\ +*Regular expression matching file names handled by Tramp. +This regexp should match Tramp file names but no other file names. +\(When tramp.el is loaded, this regular expression is prepended to +`file-name-handler-alist', and that is searched sequentially. Thus, +if the Tramp entry appears rather early in the `file-name-handler-alist' +and is a bit too general, then some files might be considered Tramp +files which are not really Tramp files. + +Please note that the entry in `file-name-handler-alist' is made when +this file (tramp.el) is loaded. This means that this variable must be set +before loading tramp.el. Alternatively, `file-name-handler-alist' can be +updated after changing this variable. + +Also see `tramp-file-name-structure'.") + +(defconst tramp-root-regexp (if (memq system-type '(cygwin windows-nt)) "^\\([a-zA-Z]:\\)?/" "^/") "\ +Beginning of an incomplete Tramp file name. +Usually, it is just \"^/\". On W32 systems, there might be a +volume letter, which will be removed by `tramp-drop-volume-letter'.") + +(defconst tramp-completion-file-name-regexp-unified (concat tramp-root-regexp "[^/]*$") "\ +Value for `tramp-completion-file-name-regexp' for unified remoting. +GNU Emacs uses a unified filename syntax for Tramp and Ange-FTP. +See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-completion-file-name-regexp-separate (concat tramp-root-regexp "\\([[][^]]*\\)?$") "\ +Value for `tramp-completion-file-name-regexp' for separate remoting. +XEmacs uses a separate filename syntax for Tramp and EFS. +See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-completion-file-name-regexp-url (concat tramp-root-regexp "[^/:]+\\(:\\(/\\(/[^/]*\\)?\\)?\\)?$") "\ +Value for `tramp-completion-file-name-regexp' for URL-like remoting. +See `tramp-file-name-structure' for more explanations.") + +(defconst tramp-completion-file-name-regexp (cond ((equal tramp-syntax 'ftp) tramp-completion-file-name-regexp-unified) ((equal tramp-syntax 'sep) tramp-completion-file-name-regexp-separate) ((equal tramp-syntax 'url) tramp-completion-file-name-regexp-url) (t (error "Wrong `tramp-syntax' defined"))) "\ +*Regular expression matching file names handled by Tramp completion. +This regexp should match partial Tramp file names only. + +Please note that the entry in `file-name-handler-alist' is made when +this file (tramp.el) is loaded. This means that this variable must be set +before loading tramp.el. Alternatively, `file-name-handler-alist' can be +updated after changing this variable. + +Also see `tramp-file-name-structure'.") + +(defconst tramp-completion-file-name-handler-alist '((file-name-all-completions . tramp-completion-handle-file-name-all-completions) (file-name-completion . tramp-completion-handle-file-name-completion)) "\ +Alist of completion handler functions. +Used for file names matching `tramp-file-name-regexp'. Operations not +mentioned here will be handled by `tramp-file-name-handler-alist' or the +normal Emacs functions.") + +(defun tramp-run-real-handler (operation args) "\ +Invoke normal file name handler for OPERATION. +First arg specifies the OPERATION, second arg is a list of arguments to +pass to the OPERATION." (let* ((inhibit-file-name-handlers (\` (tramp-file-name-handler tramp-completion-file-name-handler cygwin-mount-name-hook-function cygwin-mount-map-drive-hook-function \, (and (eq inhibit-file-name-operation operation) inhibit-file-name-handlers)))) (inhibit-file-name-operation operation)) (apply operation args))) + +(defun tramp-completion-run-real-handler (operation args) "\ +Invoke `tramp-file-name-handler' for OPERATION. +First arg specifies the OPERATION, second arg is a list of arguments to +pass to the OPERATION." (let* ((inhibit-file-name-handlers (\` (tramp-completion-file-name-handler cygwin-mount-name-hook-function cygwin-mount-map-drive-hook-function \, (and (eq inhibit-file-name-operation operation) inhibit-file-name-handlers)))) (inhibit-file-name-operation operation)) (apply operation args))) + +(autoload 'tramp-file-name-handler "tramp" "\ +Invoke Tramp file name handler. +Falls back to normal file name handler if no Tramp file name handler exists. + +\(fn OPERATION &rest ARGS)" nil nil) + +(defun tramp-completion-file-name-handler (operation &rest args) "\ +Invoke Tramp file name completion handler. +Falls back to normal file name handler if no Tramp file name handler exists." (let ((directory-sep-char 47) (fn (assoc operation tramp-completion-file-name-handler-alist))) (if (and fn tramp-mode) (save-match-data (apply (cdr fn) args)) (tramp-completion-run-real-handler operation args)))) + +(defsubst tramp-register-file-name-handler nil "\ +Add Tramp file name handler to `file-name-handler-alist'." (let ((a1 (rassq (quote tramp-file-name-handler) file-name-handler-alist))) (setq file-name-handler-alist (delete a1 file-name-handler-alist))) (add-to-list (quote file-name-handler-alist) (cons tramp-file-name-regexp (quote tramp-file-name-handler))) (let ((jka (rassoc (quote jka-compr-handler) file-name-handler-alist))) (when jka (setq file-name-handler-alist (cons jka (delete jka file-name-handler-alist)))))) +(tramp-register-file-name-handler) + +(defsubst tramp-register-completion-file-name-handler nil "\ +Add Tramp completion file name handler to `file-name-handler-alist'." (let ((a1 (rassq (quote tramp-completion-file-name-handler) file-name-handler-alist))) (setq file-name-handler-alist (delete a1 file-name-handler-alist))) (when (or (not (boundp (quote partial-completion-mode))) (symbol-value (quote partial-completion-mode)) (featurep (quote ido)) (featurep (quote icicles))) (add-to-list (quote file-name-handler-alist) (cons tramp-completion-file-name-regexp (quote tramp-completion-file-name-handler))) (put (quote tramp-completion-file-name-handler) (quote safe-magic) t)) (let ((jka (rassoc (quote jka-compr-handler) file-name-handler-alist))) (when jka (setq file-name-handler-alist (cons jka (delete jka file-name-handler-alist)))))) +(add-hook + 'after-init-hook + 'tramp-register-completion-file-name-handler) + +(autoload 'tramp-unload-file-name-handlers "tramp" "\ +Not documented + +\(fn)" nil nil) + +(autoload 'tramp-completion-handle-file-name-all-completions "tramp" "\ +Like `file-name-all-completions' for partial Tramp files. + +\(fn FILENAME DIRECTORY)" nil nil) + +(autoload 'tramp-completion-handle-file-name-completion "tramp" "\ +Like `file-name-completion' for Tramp files. + +\(fn FILENAME DIRECTORY &optional PREDICATE)" nil nil) + +(autoload 'tramp-unload-tramp "tramp" "\ +Discard Tramp from loading remote files. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (tramp-ftp-enable-ange-ftp) "tramp-ftp" "net/tramp-ftp.el" +;;;;;; (19005 47400)) +;;; Generated autoloads from net/tramp-ftp.el + +(autoload 'tramp-ftp-enable-ange-ftp "tramp-ftp" "\ +Not documented + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (help-with-tutorial) "tutorial" "tutorial.el" (19005 +;;;;;; 47387)) +;;; Generated autoloads from tutorial.el + +(autoload 'help-with-tutorial "tutorial" "\ +Select the Emacs learn-by-doing tutorial. +If there is a tutorial version written in the language +of the selected language environment, that version is used. +If there's no tutorial in that language, `TUTORIAL' is selected. +With ARG, you are asked to choose which language. +If DONT-ASK-FOR-REVERT is non-nil the buffer is reverted without +any question when restarting the tutorial. + +If any of the standard Emacs key bindings that are used in the +tutorial have been changed then an explanatory note about this is +shown in the beginning of the tutorial buffer. + +When the tutorial buffer is killed the content and the point +position in the buffer is saved so that the tutorial may be +resumed later. + +\(fn &optional ARG DONT-ASK-FOR-REVERT)" t nil) + +;;;*** + +;;;### (autoloads (tai-viet-composition-function) "tv-util" "language/tv-util.el" +;;;;;; (18785 31990)) +;;; Generated autoloads from language/tv-util.el + +(autoload 'tai-viet-composition-function "tv-util" "\ +Not documented + +\(fn FROM TO FONT-OBJECT STRING)" nil nil) + +;;;*** + +;;;### (autoloads (2C-split 2C-associate-buffer 2C-two-columns) "two-column" +;;;;;; "textmodes/two-column.el" (19005 47741)) +;;; Generated autoloads from textmodes/two-column.el + (autoload '2C-command "two-column" () t 'keymap) + (global-set-key "\C-x6" '2C-command) + (global-set-key [f2] '2C-command) + +(autoload '2C-two-columns "two-column" "\ +Split current window vertically for two-column editing. +\\When called the first time, associates a buffer with the current +buffer in two-column minor mode (use \\[describe-mode] once in the mode, +for details.). It runs `2C-other-buffer-hook' in the new buffer. +When called again, restores the screen layout with the current buffer +first and the associated buffer to its right. + +\(fn &optional BUFFER)" t nil) + +(autoload '2C-associate-buffer "two-column" "\ +Associate another buffer with this one in two-column minor mode. +Can also be used to associate a just previously visited file, by +accepting the proposed default buffer. + +\(See \\[describe-mode] .) + +\(fn)" t nil) + +(autoload '2C-split "two-column" "\ +Split a two-column text at point, into two buffers in two-column minor mode. +Point becomes the local value of `2C-window-width'. Only lines that +have the ARG same preceding characters at that column get split. The +ARG preceding characters without any leading whitespace become the local +value for `2C-separator'. This way lines that continue across both +columns remain untouched in the first buffer. + +This function can be used with a prototype line, to set up things. You +write the first line of each column and then split that line. E.g.: + +First column's text sSs Second column's text + \\___/\\ + / \\ + 5 character Separator You type M-5 \\[2C-split] with the point here. + +\(See \\[describe-mode] .) + +\(fn ARG)" t nil) + +;;;*** + +;;;### (autoloads (type-break-guesstimate-keystroke-threshold type-break-statistics +;;;;;; type-break type-break-mode type-break-keystroke-threshold +;;;;;; type-break-good-break-interval type-break-good-rest-interval +;;;;;; type-break-interval type-break-mode) "type-break" "type-break.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from type-break.el + +(defvar type-break-mode nil "\ +Toggle typing break mode. +See the docstring for the `type-break-mode' command for more information. +Setting this variable directly does not take effect; +use either \\[customize] or the function `type-break-mode'.") + +(custom-autoload 'type-break-mode "type-break" nil) + +(defvar type-break-interval (* 60 60) "\ +Number of seconds between scheduled typing breaks.") + +(custom-autoload 'type-break-interval "type-break" t) + +(defvar type-break-good-rest-interval (/ type-break-interval 6) "\ +Number of seconds of idle time considered to be an adequate typing rest. + +When this variable is non-nil, Emacs checks the idle time between +keystrokes. If this idle time is long enough to be considered a \"good\" +rest from typing, then the next typing break is simply rescheduled for later. + +If a break is interrupted before this much time elapses, the user will be +asked whether or not really to interrupt the break.") + +(custom-autoload 'type-break-good-rest-interval "type-break" t) + +(defvar type-break-good-break-interval nil "\ +Number of seconds considered to be an adequate explicit typing rest. + +When this variable is non-nil, its value is considered to be a \"good\" +length (in seconds) for a break initiated by the command `type-break', +overriding `type-break-good-rest-interval'. This provides querying of +break interruptions when `type-break-good-rest-interval' is nil.") + +(custom-autoload 'type-break-good-break-interval "type-break" t) + +(defvar type-break-keystroke-threshold (let* ((wpm 35) (avg-word-length 5) (upper (* wpm avg-word-length (/ type-break-interval 60))) (lower (/ upper 5))) (cons lower upper)) "\ +Upper and lower bound on number of keystrokes for considering typing break. +This structure is a pair of numbers (MIN . MAX). + +The first number is the minimum number of keystrokes that must have been +entered since the last typing break before considering another one, even if +the scheduled time has elapsed; the break is simply rescheduled until later +if the minimum threshold hasn't been reached. If this first value is nil, +then there is no minimum threshold; as soon as the scheduled time has +elapsed, the user will always be queried. + +The second number is the maximum number of keystrokes that can be entered +before a typing break is requested immediately, pre-empting the originally +scheduled break. If this second value is nil, then no pre-emptive breaks +will occur; only scheduled ones will. + +Keys with bucky bits (shift, control, meta, etc) are counted as only one +keystroke even though they really require multiple keys to generate them. + +The command `type-break-guesstimate-keystroke-threshold' can be used to +guess a reasonably good pair of values for this variable.") + +(custom-autoload 'type-break-keystroke-threshold "type-break" t) + +(autoload 'type-break-mode "type-break" "\ +Enable or disable typing-break mode. +This is a minor mode, but it is global to all buffers by default. + +When this mode is enabled, the user is encouraged to take typing breaks at +appropriate intervals; either after a specified amount of time or when the +user has exceeded a keystroke threshold. When the time arrives, the user +is asked to take a break. If the user refuses at that time, Emacs will ask +again in a short period of time. The idea is to give the user enough time +to find a good breaking point in his or her work, but be sufficiently +annoying to discourage putting typing breaks off indefinitely. + +A negative prefix argument disables this mode. +No argument or any non-negative argument enables it. + +The user may enable or disable this mode by setting the variable of the +same name, though setting it in that way doesn't reschedule a break or +reset the keystroke counter. + +If the mode was previously disabled and is enabled as a consequence of +calling this function, it schedules a break with `type-break-schedule' to +make sure one occurs (the user can call that command to reschedule the +break at any time). It also initializes the keystroke counter. + +The variable `type-break-interval' specifies the number of seconds to +schedule between regular typing breaks. This variable doesn't directly +affect the time schedule; it simply provides a default for the +`type-break-schedule' command. + +If set, the variable `type-break-good-rest-interval' specifies the minimum +amount of time which is considered a reasonable typing break. Whenever +that time has elapsed, typing breaks are automatically rescheduled for +later even if Emacs didn't prompt you to take one first. Also, if a break +is ended before this much time has elapsed, the user will be asked whether +or not to continue. A nil value for this variable prevents automatic +break rescheduling, making `type-break-interval' an upper bound on the time +between breaks. In this case breaks will be prompted for as usual before +the upper bound if the keystroke threshold is reached. + +If `type-break-good-rest-interval' is nil and +`type-break-good-break-interval' is set, then confirmation is required to +interrupt a break before `type-break-good-break-interval' seconds +have passed. This provides for an upper bound on the time between breaks +together with confirmation of interruptions to these breaks. + +The variable `type-break-keystroke-threshold' is used to determine the +thresholds at which typing breaks should be considered. You can use +the command `type-break-guesstimate-keystroke-threshold' to try to +approximate good values for this. + +There are several variables that affect how or when warning messages about +imminent typing breaks are displayed. They include: + + `type-break-mode-line-message-mode' + `type-break-time-warning-intervals' + `type-break-keystroke-warning-intervals' + `type-break-warning-repeat' + `type-break-warning-countdown-string' + `type-break-warning-countdown-string-type' + +There are several variables that affect if, how, and when queries to begin +a typing break occur. They include: + + `type-break-query-mode' + `type-break-query-function' + `type-break-query-interval' + +The command `type-break-statistics' prints interesting things. + +Finally, a file (named `type-break-file-name') is used to store information +across Emacs sessions. This provides recovery of the break status between +sessions and after a crash. Manual changes to the file may result in +problems. + +\(fn &optional PREFIX)" t nil) + +(autoload 'type-break "type-break" "\ +Take a typing break. + +During the break, a demo selected from the functions listed in +`type-break-demo-functions' is run. + +After the typing break is finished, the next break is scheduled +as per the function `type-break-schedule'. + +\(fn)" t nil) + +(autoload 'type-break-statistics "type-break" "\ +Print statistics about typing breaks in a temporary buffer. +This includes the last time a typing break was taken, when the next one is +scheduled, the keystroke thresholds and the current keystroke count, etc. + +\(fn)" t nil) + +(autoload 'type-break-guesstimate-keystroke-threshold "type-break" "\ +Guess values for the minimum/maximum keystroke threshold for typing breaks. + +If called interactively, the user is prompted for their guess as to how +many words per minute they usually type. This value should not be your +maximum WPM, but your average. Of course, this is harder to gauge since it +can vary considerably depending on what you are doing. For example, one +tends to type less when debugging a program as opposed to writing +documentation. (Perhaps a separate program should be written to estimate +average typing speed.) + +From that, this command sets the values in `type-break-keystroke-threshold' +based on a fairly simple algorithm involving assumptions about the average +length of words (5). For the minimum threshold, it uses about a fifth of +the computed maximum threshold. + +When called from Lisp programs, the optional args WORDLEN and FRAC can be +used to override the default assumption about average word length and the +fraction of the maximum threshold to which to set the minimum threshold. +FRAC should be the inverse of the fractional value; for example, a value of +2 would mean to use one half, a value of 4 would mean to use one quarter, etc. + +\(fn WPM &optional WORDLEN FRAC)" t nil) + +;;;*** + +;;;### (autoloads (uce-reply-to-uce) "uce" "mail/uce.el" (19005 47398)) +;;; Generated autoloads from mail/uce.el + +(autoload 'uce-reply-to-uce "uce" "\ +Compose a reply to unsolicited commercial email (UCE). +Sets up a reply buffer addressed to: the sender, his postmaster, +his abuse@ address, and the postmaster of the mail relay used. +You might need to set `uce-mail-reader' before using this. + +\(fn &optional IGNORED)" t nil) + +;;;*** + +;;;### (autoloads (ununderline-region underline-region) "underline" +;;;;;; "textmodes/underline.el" (19005 47406)) +;;; Generated autoloads from textmodes/underline.el + +(autoload 'underline-region "underline" "\ +Underline all nonblank characters in the region. +Works by overstriking underscores. +Called from program, takes two arguments START and END +which specify the range to operate on. + +\(fn START END)" t nil) + +(autoload 'ununderline-region "underline" "\ +Remove all underlining (overstruck underscores) in the region. +Called from program, takes two arguments START and END +which specify the range to operate on. + +\(fn START END)" t nil) + +;;;*** + +;;;### (autoloads (unforward-rmail-message undigestify-rmail-message) +;;;;;; "undigest" "mail/undigest.el" (19005 47398)) +;;; Generated autoloads from mail/undigest.el + +(autoload 'undigestify-rmail-message "undigest" "\ +Break up a digest message into its constituent messages. +Leaves original message, deleted, before the undigestified messages. + +\(fn)" t nil) + +(autoload 'unforward-rmail-message "undigest" "\ +Extract a forwarded message from the containing message. +This puts the forwarded message into a separate rmail message +following the containing message. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (unrmail batch-unrmail) "unrmail" "mail/unrmail.el" +;;;;;; (19028 3034)) +;;; Generated autoloads from mail/unrmail.el + +(autoload 'batch-unrmail "unrmail" "\ +Convert old-style Rmail Babyl files to system inbox format. +Specify the input Rmail Babyl file names as command line arguments. +For each Rmail file, the corresponding output file name +is made by adding `.mail' at the end. +For example, invoke `emacs -batch -f batch-unrmail RMAIL'. + +\(fn)" nil nil) + +(autoload 'unrmail "unrmail" "\ +Convert old-style Rmail Babyl file FILE to system inbox format file TO-FILE. + +\(fn FILE TO-FILE)" t nil) + +;;;*** + +;;;### (autoloads (unsafep) "unsafep" "emacs-lisp/unsafep.el" (19005 +;;;;;; 47390)) +;;; Generated autoloads from emacs-lisp/unsafep.el + +(autoload 'unsafep "unsafep" "\ +Return nil if evaluating FORM couldn't possibly do any harm. +Otherwise result is a reason why FORM is unsafe. +UNSAFEP-VARS is a list of symbols with local bindings. + +\(fn FORM &optional UNSAFEP-VARS)" nil nil) + +;;;*** + +;;;### (autoloads (url-retrieve-synchronously url-retrieve) "url" +;;;;;; "url/url.el" (19005 47406)) +;;; Generated autoloads from url/url.el + +(autoload 'url-retrieve "url" "\ +Retrieve URL asynchronously and call CALLBACK with CBARGS when finished. +URL is either a string or a parsed URL. + +CALLBACK is called when the object has been completely retrieved, with +the current buffer containing the object, and any MIME headers associated +with it. It is called as (apply CALLBACK STATUS CBARGS). +STATUS is a list with an even number of elements representing +what happened during the request, with most recent events first, +or an empty list if no events have occurred. Each pair is one of: + +\(:redirect REDIRECTED-TO) - the request was redirected to this URL +\(:error (ERROR-SYMBOL . DATA)) - an error occurred. The error can be +signaled with (signal ERROR-SYMBOL DATA). + +Return the buffer URL will load into, or nil if the process has +already completed (i.e. URL was a mailto URL or similar; in this case +the callback is not called). + +The variables `url-request-data', `url-request-method' and +`url-request-extra-headers' can be dynamically bound around the +request; dynamic binding of other variables doesn't necessarily +take effect. + +\(fn URL CALLBACK &optional CBARGS)" nil nil) + +(autoload 'url-retrieve-synchronously "url" "\ +Retrieve URL synchronously. +Return the buffer containing the data, or nil if there are no data +associated with it (the case for dired, info, or mailto URLs that need +no further processing). URL is either a string or a parsed URL. + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-register-auth-scheme url-get-authentication) +;;;;;; "url-auth" "url/url-auth.el" (19005 47406)) +;;; Generated autoloads from url/url-auth.el + +(autoload 'url-get-authentication "url-auth" "\ +Return an authorization string suitable for use in the WWW-Authenticate +header in an HTTP/1.0 request. + +URL is the url you are requesting authorization to. This can be either a + string representing the URL, or the parsed representation returned by + `url-generic-parse-url' +REALM is the realm at a specific site we are looking for. This should be a + string specifying the exact realm, or nil or the symbol 'any' to + specify that the filename portion of the URL should be used as the + realm +TYPE is the type of authentication to be returned. This is either a string + representing the type (basic, digest, etc), or nil or the symbol 'any' + to specify that any authentication is acceptable. If requesting 'any' + the strongest matching authentication will be returned. If this is + wrong, it's no big deal, the error from the server will specify exactly + what type of auth to use +PROMPT is boolean - specifies whether to ask the user for a username/password + if one cannot be found in the cache + +\(fn URL REALM TYPE PROMPT &optional ARGS)" nil nil) + +(autoload 'url-register-auth-scheme "url-auth" "\ +Register an HTTP authentication method. + +TYPE is a string or symbol specifying the name of the method. + This should be the same thing you expect to get returned in + an Authenticate header in HTTP/1.0 - it will be downcased. +FUNCTION is the function to call to get the authorization information. + This defaults to `url-?-auth', where ? is TYPE. +RATING a rating between 1 and 10 of the strength of the authentication. + This is used when asking for the best authentication for a specific + URL. The item with the highest rating is returned. + +\(fn TYPE &optional FUNCTION RATING)" nil nil) + +;;;*** + +;;;### (autoloads (url-cache-expired url-cache-extract url-is-cached +;;;;;; url-store-in-cache) "url-cache" "url/url-cache.el" (19005 +;;;;;; 47406)) +;;; Generated autoloads from url/url-cache.el + +(autoload 'url-store-in-cache "url-cache" "\ +Store buffer BUFF in the cache. + +\(fn &optional BUFF)" nil nil) + +(autoload 'url-is-cached "url-cache" "\ +Return non-nil if the URL is cached. + +\(fn URL)" nil nil) + +(autoload 'url-cache-extract "url-cache" "\ +Extract FNAM from the local disk cache. + +\(fn FNAM)" nil nil) + +(autoload 'url-cache-expired "url-cache" "\ +Return t if a cached file has expired. + +\(fn URL MOD)" nil nil) + +;;;*** + +;;;### (autoloads (url-cid) "url-cid" "url/url-cid.el" (19005 47406)) +;;; Generated autoloads from url/url-cid.el + +(autoload 'url-cid "url-cid" "\ +Not documented + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-dav-vc-registered url-dav-supported-p) "url-dav" +;;;;;; "url/url-dav.el" (19005 47406)) +;;; Generated autoloads from url/url-dav.el + +(autoload 'url-dav-supported-p "url-dav" "\ +Not documented + +\(fn URL)" nil nil) + +(autoload 'url-dav-vc-registered "url-dav" "\ +Not documented + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-file) "url-file" "url/url-file.el" (19005 +;;;;;; 47406)) +;;; Generated autoloads from url/url-file.el + +(autoload 'url-file "url-file" "\ +Handle file: and ftp: URLs. + +\(fn URL CALLBACK CBARGS)" nil nil) + +;;;*** + +;;;### (autoloads (url-open-stream url-gateway-nslookup-host) "url-gw" +;;;;;; "url/url-gw.el" (19005 47406)) +;;; Generated autoloads from url/url-gw.el + +(autoload 'url-gateway-nslookup-host "url-gw" "\ +Attempt to resolve the given HOST using nslookup if possible. + +\(fn HOST)" t nil) + +(autoload 'url-open-stream "url-gw" "\ +Open a stream to HOST, possibly via a gateway. +Args per `open-network-stream'. +Will not make a connection if `url-gateway-unplugged' is non-nil. +Might do a non-blocking connection; use `process-status' to check. + +\(fn NAME BUFFER HOST SERVICE)" nil nil) + +;;;*** + +;;;### (autoloads (url-insert-file-contents url-file-local-copy url-copy-file +;;;;;; url-file-handler url-handler-mode) "url-handlers" "url/url-handlers.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from url/url-handlers.el + +(defvar url-handler-mode nil "\ +Non-nil if Url-Handler mode is enabled. +See the command `url-handler-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `url-handler-mode'.") + +(custom-autoload 'url-handler-mode "url-handlers" nil) + +(autoload 'url-handler-mode "url-handlers" "\ +Use URL to handle URL-like file names. + +\(fn &optional ARG)" t nil) + +(autoload 'url-file-handler "url-handlers" "\ +Function called from the `file-name-handler-alist' routines. +OPERATION is what needs to be done (`file-exists-p', etc). ARGS are +the arguments that would have been passed to OPERATION. + +\(fn OPERATION &rest ARGS)" nil nil) + +(autoload 'url-copy-file "url-handlers" "\ +Copy URL to NEWNAME. Both args must be strings. +Signals a `file-already-exists' error if file NEWNAME already exists, +unless a third argument OK-IF-ALREADY-EXISTS is supplied and non-nil. +A number as third arg means request confirmation if NEWNAME already exists. +This is what happens in interactive use with M-x. +Fourth arg KEEP-TIME non-nil means give the new file the same +last-modified time as the old one. (This works on only some systems.) +A prefix arg makes KEEP-TIME non-nil. + +\(fn URL NEWNAME &optional OK-IF-ALREADY-EXISTS KEEP-TIME)" nil nil) + +(autoload 'url-file-local-copy "url-handlers" "\ +Copy URL into a temporary file on this machine. +Returns the name of the local copy, or nil, if FILE is directly +accessible. + +\(fn URL &rest IGNORED)" nil nil) + +(autoload 'url-insert-file-contents "url-handlers" "\ +Not documented + +\(fn URL &optional VISIT BEG END REPLACE)" nil nil) + +;;;*** + +;;;### (autoloads (url-http-options url-http-file-attributes url-http-file-exists-p +;;;;;; url-http) "url-http" "url/url-http.el" (19005 47406)) +;;; Generated autoloads from url/url-http.el + +(autoload 'url-http "url-http" "\ +Retrieve URL via HTTP asynchronously. +URL must be a parsed URL. See `url-generic-parse-url' for details. +When retrieval is completed, the function CALLBACK is executed with +CBARGS as the arguments. + +\(fn URL CALLBACK CBARGS)" nil nil) + +(autoload 'url-http-file-exists-p "url-http" "\ +Not documented + +\(fn URL)" nil nil) + +(defalias 'url-http-file-readable-p 'url-http-file-exists-p) + +(autoload 'url-http-file-attributes "url-http" "\ +Not documented + +\(fn URL &optional ID-FORMAT)" nil nil) + +(autoload 'url-http-options "url-http" "\ +Return a property list describing options available for URL. +This list is retrieved using the `OPTIONS' HTTP method. + +Property list members: + +methods + A list of symbols specifying what HTTP methods the resource + supports. + +dav + A list of numbers specifying what DAV protocol/schema versions are + supported. + +dasl + A list of supported DASL search types supported (string form) + +ranges + A list of the units available for use in partial document fetches. + +p3p + The `Platform For Privacy Protection' description for the resource. + Currently this is just the raw header contents. This is likely to + change once P3P is formally supported by the URL package or + Emacs/W3. + +\(fn URL)" nil nil) + +(defconst url-https-default-port 443 "\ +Default HTTPS port.") + +(defconst url-https-asynchronous-p t "\ +HTTPS retrievals are asynchronous.") + (autoload 'url-default-expander "url-expand") + +(defalias 'url-https-expand-file-name 'url-default-expander) + (autoload 'url-https "url-http") + (autoload 'url-https-file-exists-p "url-http") + (autoload 'url-https-file-readable-p "url-http") + (autoload 'url-https-file-attributes "url-http") + +;;;*** + +;;;### (autoloads (url-irc) "url-irc" "url/url-irc.el" (19005 47406)) +;;; Generated autoloads from url/url-irc.el + +(autoload 'url-irc "url-irc" "\ +Not documented + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-ldap) "url-ldap" "url/url-ldap.el" (19005 +;;;;;; 47406)) +;;; Generated autoloads from url/url-ldap.el + +(autoload 'url-ldap "url-ldap" "\ +Perform an LDAP search specified by URL. +The return value is a buffer displaying the search results in HTML. +URL can be a URL string, or a URL vector of the type returned by +`url-generic-parse-url'. + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-mailto url-mail) "url-mailto" "url/url-mailto.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from url/url-mailto.el + +(autoload 'url-mail "url-mailto" "\ +Not documented + +\(fn &rest ARGS)" t nil) + +(autoload 'url-mailto "url-mailto" "\ +Handle the mailto: URL syntax. + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-data url-generic-emulator-loader url-info +;;;;;; url-man) "url-misc" "url/url-misc.el" (19005 47406)) +;;; Generated autoloads from url/url-misc.el + +(autoload 'url-man "url-misc" "\ +Fetch a Unix manual page URL. + +\(fn URL)" nil nil) + +(autoload 'url-info "url-misc" "\ +Fetch a GNU Info URL. + +\(fn URL)" nil nil) + +(autoload 'url-generic-emulator-loader "url-misc" "\ +Not documented + +\(fn URL)" nil nil) + +(defalias 'url-rlogin 'url-generic-emulator-loader) + +(defalias 'url-telnet 'url-generic-emulator-loader) + +(defalias 'url-tn3270 'url-generic-emulator-loader) + +(autoload 'url-data "url-misc" "\ +Fetch a data URL (RFC 2397). + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-snews url-news) "url-news" "url/url-news.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from url/url-news.el + +(autoload 'url-news "url-news" "\ +Not documented + +\(fn URL)" nil nil) + +(autoload 'url-snews "url-news" "\ +Not documented + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-ns-user-pref url-ns-prefs isInNet isResolvable +;;;;;; dnsResolve dnsDomainIs isPlainHostName) "url-ns" "url/url-ns.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from url/url-ns.el + +(autoload 'isPlainHostName "url-ns" "\ +Not documented + +\(fn HOST)" nil nil) + +(autoload 'dnsDomainIs "url-ns" "\ +Not documented + +\(fn HOST DOM)" nil nil) + +(autoload 'dnsResolve "url-ns" "\ +Not documented + +\(fn HOST)" nil nil) + +(autoload 'isResolvable "url-ns" "\ +Not documented + +\(fn HOST)" nil nil) + +(autoload 'isInNet "url-ns" "\ +Not documented + +\(fn IP NET MASK)" nil nil) + +(autoload 'url-ns-prefs "url-ns" "\ +Not documented + +\(fn &optional FILE)" nil nil) + +(autoload 'url-ns-user-pref "url-ns" "\ +Not documented + +\(fn KEY &optional DEFAULT)" nil nil) + +;;;*** + +;;;### (autoloads (url-generic-parse-url url-recreate-url) "url-parse" +;;;;;; "url/url-parse.el" (19005 47406)) +;;; Generated autoloads from url/url-parse.el + +(autoload 'url-recreate-url "url-parse" "\ +Recreate a URL string from the parsed URLOBJ. + +\(fn URLOBJ)" nil nil) + +(autoload 'url-generic-parse-url "url-parse" "\ +Return an URL-struct of the parts of URL. +The CL-style struct contains the following fields: +TYPE USER PASSWORD HOST PORTSPEC FILENAME TARGET ATTRIBUTES FULLNESS. + +\(fn URL)" nil nil) + +;;;*** + +;;;### (autoloads (url-setup-privacy-info) "url-privacy" "url/url-privacy.el" +;;;;;; (19005 47406)) +;;; Generated autoloads from url/url-privacy.el + +(autoload 'url-setup-privacy-info "url-privacy" "\ +Setup variables that expose info about you and your system. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (url-view-url url-truncate-url-for-viewing url-file-extension +;;;;;; url-hexify-string url-unhex-string url-parse-query-string +;;;;;; url-file-nondirectory url-file-directory url-percentage url-display-percentage +;;;;;; url-pretty-length url-strip-leading-spaces url-eat-trailing-space +;;;;;; url-get-normalized-date url-lazy-message url-normalize-url +;;;;;; url-insert-entities-in-string url-parse-args url-debug url-debug) +;;;;;; "url-util" "url/url-util.el" (19005 47406)) +;;; Generated autoloads from url/url-util.el + +(defvar url-debug nil "\ +*What types of debug messages from the URL library to show. +Debug messages are logged to the *URL-DEBUG* buffer. + +If t, all messages will be logged. +If a number, all messages will be logged, as well shown via `message'. +If a list, it is a list of the types of messages to be logged.") + +(custom-autoload 'url-debug "url-util" t) + +(autoload 'url-debug "url-util" "\ +Not documented + +\(fn TAG &rest ARGS)" nil nil) + +(autoload 'url-parse-args "url-util" "\ +Not documented + +\(fn STR &optional NODOWNCASE)" nil nil) + +(autoload 'url-insert-entities-in-string "url-util" "\ +Convert HTML markup-start characters to entity references in STRING. +Also replaces the \" character, so that the result may be safely used as + an attribute value in a tag. Returns a new string with the result of the + conversion. Replaces these characters as follows: + & ==> & + < ==> < + > ==> > + \" ==> " + +\(fn STRING)" nil nil) + +(autoload 'url-normalize-url "url-util" "\ +Return a 'normalized' version of URL. +Strips out default port numbers, etc. + +\(fn URL)" nil nil) + +(autoload 'url-lazy-message "url-util" "\ +Just like `message', but is a no-op if called more than once a second. +Will not do anything if `url-show-status' is nil. + +\(fn &rest ARGS)" nil nil) + +(autoload 'url-get-normalized-date "url-util" "\ +Return a 'real' date string that most HTTP servers can understand. + +\(fn &optional SPECIFIED-TIME)" nil nil) + +(autoload 'url-eat-trailing-space "url-util" "\ +Remove spaces/tabs at the end of a string. + +\(fn X)" nil nil) + +(autoload 'url-strip-leading-spaces "url-util" "\ +Remove spaces at the front of a string. + +\(fn X)" nil nil) + +(autoload 'url-pretty-length "url-util" "\ +Not documented + +\(fn N)" nil nil) + +(autoload 'url-display-percentage "url-util" "\ +Not documented + +\(fn FMT PERC &rest ARGS)" nil nil) + +(autoload 'url-percentage "url-util" "\ +Not documented + +\(fn X Y)" nil nil) + +(defalias 'url-basepath 'url-file-directory) + +(autoload 'url-file-directory "url-util" "\ +Return the directory part of FILE, for a URL. + +\(fn FILE)" nil nil) + +(autoload 'url-file-nondirectory "url-util" "\ +Return the nondirectory part of FILE, for a URL. + +\(fn FILE)" nil nil) + +(autoload 'url-parse-query-string "url-util" "\ +Not documented + +\(fn QUERY &optional DOWNCASE ALLOW-NEWLINES)" nil nil) + +(autoload 'url-unhex-string "url-util" "\ +Remove %XX embedded spaces, etc in a URL. +If optional second argument ALLOW-NEWLINES is non-nil, then allow the +decoding of carriage returns and line feeds in the string, which is normally +forbidden in URL encoding. + +\(fn STR &optional ALLOW-NEWLINES)" nil nil) + +(autoload 'url-hexify-string "url-util" "\ +Return a new string that is STRING URI-encoded. +First, STRING is converted to utf-8, if necessary. Then, for each +character in the utf-8 string, those found in `url-unreserved-chars' +are left as-is, all others are represented as a three-character +string: \"%\" followed by two lowercase hex digits. + +\(fn STRING)" nil nil) + +(autoload 'url-file-extension "url-util" "\ +Return the filename extension of FNAME. +If optional argument X is t, then return the basename +of the file with the extension stripped off. + +\(fn FNAME &optional X)" nil nil) + +(autoload 'url-truncate-url-for-viewing "url-util" "\ +Return a shortened version of URL that is WIDTH characters wide or less. +WIDTH defaults to the current frame width. + +\(fn URL &optional WIDTH)" nil nil) + +(autoload 'url-view-url "url-util" "\ +View the current document's URL. +Optional argument NO-SHOW means just return the URL, don't show it in +the minibuffer. + +This uses `url-current-object', set locally to the buffer. + +\(fn &optional NO-SHOW)" t nil) + +;;;*** + +;;;### (autoloads (ask-user-about-supersession-threat ask-user-about-lock) +;;;;;; "userlock" "userlock.el" (19005 47387)) +;;; Generated autoloads from userlock.el + +(autoload 'ask-user-about-lock "userlock" "\ +Ask user what to do when he wants to edit FILE but it is locked by OPPONENT. +This function has a choice of three things to do: + do (signal 'file-locked (list FILE OPPONENT)) + to refrain from editing the file + return t (grab the lock on the file) + return nil (edit the file even though it is locked). +You can redefine this function to choose among those three alternatives +in any way you like. + +\(fn FILE OPPONENT)" nil nil) + +(autoload 'ask-user-about-supersession-threat "userlock" "\ +Ask a user who is about to modify an obsolete buffer what to do. +This function has two choices: it can return, in which case the modification +of the buffer will proceed, or it can (signal 'file-supersession (file)), +in which case the proposed buffer modification will not be made. + +You can rewrite this to use any criterion you like to choose which one to do. +The buffer in question is current when this function is called. + +\(fn FN)" nil nil) + +;;;*** + +;;;### (autoloads (utf-7-imap-pre-write-conversion utf-7-pre-write-conversion +;;;;;; utf-7-imap-post-read-conversion utf-7-post-read-conversion) +;;;;;; "utf-7" "international/utf-7.el" (19005 47396)) +;;; Generated autoloads from international/utf-7.el + +(autoload 'utf-7-post-read-conversion "utf-7" "\ +Not documented + +\(fn LEN)" nil nil) + +(autoload 'utf-7-imap-post-read-conversion "utf-7" "\ +Not documented + +\(fn LEN)" nil nil) + +(autoload 'utf-7-pre-write-conversion "utf-7" "\ +Not documented + +\(fn FROM TO)" nil nil) + +(autoload 'utf-7-imap-pre-write-conversion "utf-7" "\ +Not documented + +\(fn FROM TO)" nil nil) + +;;;*** + +;;;### (autoloads (uudecode-decode-region uudecode-decode-region-internal +;;;;;; uudecode-decode-region-external) "uudecode" "mail/uudecode.el" +;;;;;; (18785 31998)) +;;; Generated autoloads from mail/uudecode.el + +(autoload 'uudecode-decode-region-external "uudecode" "\ +Uudecode region between START and END using external program. +If FILE-NAME is non-nil, save the result to FILE-NAME. The program +used is specified by `uudecode-decoder-program'. + +\(fn START END &optional FILE-NAME)" t nil) + +(autoload 'uudecode-decode-region-internal "uudecode" "\ +Uudecode region between START and END without using an external program. +If FILE-NAME is non-nil, save the result to FILE-NAME. + +\(fn START END &optional FILE-NAME)" t nil) + +(autoload 'uudecode-decode-region "uudecode" "\ +Uudecode region between START and END. +If FILE-NAME is non-nil, save the result to FILE-NAME. + +\(fn START END &optional FILE-NAME)" nil nil) + +;;;*** + +;;;### (autoloads (vc-branch-part vc-trunk-p vc-update-change-log +;;;;;; vc-rename-file vc-delete-file vc-transfer-file vc-switch-backend +;;;;;; vc-update vc-rollback vc-revert vc-print-log vc-retrieve-tag +;;;;;; vc-create-tag vc-merge vc-insert-headers vc-revision-other-window +;;;;;; vc-diff vc-version-diff vc-register vc-next-action vc-before-checkin-hook +;;;;;; vc-checkin-hook vc-checkout-hook) "vc" "vc.el" (19005 47387)) +;;; Generated autoloads from vc.el + +(defvar vc-checkout-hook nil "\ +Normal hook (list of functions) run after checking out a file. +See `run-hooks'.") + +(custom-autoload 'vc-checkout-hook "vc" t) + +(defvar vc-checkin-hook nil "\ +Normal hook (list of functions) run after commit or file checkin. +See also `log-edit-done-hook'.") + +(custom-autoload 'vc-checkin-hook "vc" t) + +(defvar vc-before-checkin-hook nil "\ +Normal hook (list of functions) run before a commit or a file checkin. +See `run-hooks'.") + +(custom-autoload 'vc-before-checkin-hook "vc" t) + +(autoload 'vc-next-action "vc" "\ +Do the next logical version control operation on the current fileset. +This requires that all files in the fileset be in the same state. + +For locking systems: + If every file is not already registered, this registers each for version +control. + If every file is registered and not locked by anyone, this checks out +a writable and locked file of each ready for editing. + If every file is checked out and locked by the calling user, this +first checks to see if each file has changed since checkout. If not, +it performs a revert on that file. + If every file has been changed, this pops up a buffer for entry +of a log message; when the message has been entered, it checks in the +resulting changes along with the log message as change commentary. If +the variable `vc-keep-workfiles' is non-nil (which is its default), a +read-only copy of each changed file is left in place afterwards. + If the affected file is registered and locked by someone else, you are +given the option to steal the lock(s). + +For merging systems: + If every file is not already registered, this registers each one for version +control. This does an add, but not a commit. + If every file is added but not committed, each one is committed. + If every working file is changed, but the corresponding repository file is +unchanged, this pops up a buffer for entry of a log message; when the +message has been entered, it checks in the resulting changes along +with the logmessage as change commentary. A writable file is retained. + If the repository file is changed, you are asked if you want to +merge in the changes into your working copy. + +\(fn VERBOSE)" t nil) + +(autoload 'vc-register "vc" "\ +Register into a version control system. +If VC-FILESET is given, register the files in that fileset. +Otherwise register the current file. +With prefix argument SET-REVISION, allow user to specify initial revision +level. If COMMENT is present, use that as an initial comment. + +The version control system to use is found by cycling through the list +`vc-handled-backends'. The first backend in that list which declares +itself responsible for the file (usually because other files in that +directory are already registered under that backend) will be used to +register the file. If no backend declares itself responsible, the +first backend that could register the file is used. + +\(fn &optional SET-REVISION VC-FILESET COMMENT)" t nil) + +(autoload 'vc-version-diff "vc" "\ +Report diffs between revisions of the fileset in the repository history. + +\(fn FILES REV1 REV2)" t nil) + +(autoload 'vc-diff "vc" "\ +Display diffs between file revisions. +Normally this compares the currently selected fileset with their +working revisions. With a prefix argument HISTORIC, it reads two revision +designators specifying which revisions to compare. + +The optional argument NOT-URGENT non-nil means it is ok to say no to +saving the buffer. + +\(fn HISTORIC &optional NOT-URGENT)" t nil) + +(autoload 'vc-revision-other-window "vc" "\ +Visit revision REV of the current file in another window. +If the current file is named `F', the revision is named `F.~REV~'. +If `F.~REV~' already exists, use it instead of checking it out again. + +\(fn REV)" t nil) + +(autoload 'vc-insert-headers "vc" "\ +Insert headers into a file for use with a version control system. +Headers desired are inserted at point, and are pulled from +the variable `vc-BACKEND-header'. + +\(fn)" t nil) + +(autoload 'vc-merge "vc" "\ +Merge changes between two revisions into the current buffer's file. +This asks for two revisions to merge from in the minibuffer. If the +first revision is a branch number, then merge all changes from that +branch. If the first revision is empty, merge news, i.e. recent changes +from the current branch. + +See Info node `Merging'. + +\(fn)" t nil) + +(defalias 'vc-resolve-conflicts 'smerge-ediff) + +(autoload 'vc-create-tag "vc" "\ +Descending recursively from DIR, make a tag called NAME. +For each registered file, the working revision becomes part of +the named configuration. If the prefix argument BRANCHP is +given, the tag is made as a new branch and the files are +checked out in that new branch. + +\(fn DIR NAME BRANCHP)" t nil) + +(autoload 'vc-retrieve-tag "vc" "\ +Descending recursively from DIR, retrieve the tag called NAME. +If NAME is empty, it refers to the latest revisions. +If locking is used for the files in DIR, then there must not be any +locked files at or below DIR (but if NAME is empty, locked files are +allowed and simply skipped). + +\(fn DIR NAME)" t nil) + +(autoload 'vc-print-log "vc" "\ +List the change log of the current fileset in a window. +If WORKING-REVISION is non-nil, leave the point at that revision. + +\(fn &optional WORKING-REVISION)" t nil) + +(autoload 'vc-revert "vc" "\ +Revert working copies of the selected fileset to their repository contents. +This asks for confirmation if the buffer contents are not identical +to the working revision (except for keyword expansion). + +\(fn)" t nil) + +(autoload 'vc-rollback "vc" "\ +Roll back (remove) the most recent changeset committed to the repository. +This may be either a file-level or a repository-level operation, +depending on the underlying version-control system. + +\(fn)" t nil) + +(define-obsolete-function-alias 'vc-revert-buffer 'vc-revert "23.1") + +(autoload 'vc-update "vc" "\ +Update the current fileset's files to their tip revisions. +For each one that contains no changes, and is not locked, then this simply +replaces the work file with the latest revision on its branch. If the file +contains changes, and the backend supports merging news, then any recent +changes from the current branch are merged into the working file. + +\(fn)" t nil) + +(autoload 'vc-switch-backend "vc" "\ +Make BACKEND the current version control system for FILE. +FILE must already be registered in BACKEND. The change is not +permanent, only for the current session. This function only changes +VC's perspective on FILE, it does not register or unregister it. +By default, this command cycles through the registered backends. +To get a prompt, use a prefix argument. + +\(fn FILE BACKEND)" t nil) + +(autoload 'vc-transfer-file "vc" "\ +Transfer FILE to another version control system NEW-BACKEND. +If NEW-BACKEND has a higher precedence than FILE's current backend +\(i.e. it comes earlier in `vc-handled-backends'), then register FILE in +NEW-BACKEND, using the revision number from the current backend as the +base level. If NEW-BACKEND has a lower precedence than the current +backend, then commit all changes that were made under the current +backend to NEW-BACKEND, and unregister FILE from the current backend. +\(If FILE is not yet registered under NEW-BACKEND, register it.) + +\(fn FILE NEW-BACKEND)" nil nil) + +(autoload 'vc-delete-file "vc" "\ +Delete file and mark it as such in the version control system. + +\(fn FILE)" t nil) + +(autoload 'vc-rename-file "vc" "\ +Rename file OLD to NEW, and rename its master file likewise. + +\(fn OLD NEW)" t nil) + +(autoload 'vc-update-change-log "vc" "\ +Find change log file and add entries from recent version control logs. +Normally, find log entries for all registered files in the default +directory. + +With prefix arg of \\[universal-argument], only find log entries for the current buffer's file. + +With any numeric prefix arg, find log entries for all currently visited +files that are under version control. This puts all the entries in the +log for the default directory, which may not be appropriate. + +From a program, any ARGS are assumed to be filenames for which +log entries should be gathered. + +\(fn &rest ARGS)" t nil) + +(autoload 'vc-trunk-p "vc" "\ +Return t if REV is a revision on the trunk. + +\(fn REV)" nil nil) + +(autoload 'vc-branch-part "vc" "\ +Return the branch part of a revision number REV. + +\(fn REV)" nil nil) + +;;;*** + +;;;### (autoloads (vc-annotate) "vc-annotate" "vc-annotate.el" (18869 +;;;;;; 47965)) +;;; Generated autoloads from vc-annotate.el + +(autoload 'vc-annotate "vc-annotate" "\ +Display the edit history of the current file using colors. + +This command creates a buffer that shows, for each line of the current +file, when it was last edited and by whom. Additionally, colors are +used to show the age of each line--blue means oldest, red means +youngest, and intermediate colors indicate intermediate ages. By +default, the time scale stretches back one year into the past; +everything that is older than that is shown in blue. + +With a prefix argument, this command asks two questions in the +minibuffer. First, you may enter a revision number; then the buffer +displays and annotates that revision instead of the working revision +\(type RET in the minibuffer to leave that default unchanged). Then, +you are prompted for the time span in days which the color range +should cover. For example, a time span of 20 days means that changes +over the past 20 days are shown in red to blue, according to their +age, and everything that is older than that is shown in blue. + +If MOVE-POINT-TO is given, move the point to that line. + +Customization variables: + +`vc-annotate-menu-elements' customizes the menu elements of the +mode-specific menu. `vc-annotate-color-map' and +`vc-annotate-very-old-color' define the mapping of time to colors. +`vc-annotate-background' specifies the background color. + +\(fn FILE REV &optional DISPLAY-MODE BUF MOVE-POINT-TO)" t nil) + +;;;*** + +;;;### (autoloads nil "vc-arch" "vc-arch.el" (19005 47387)) +;;; Generated autoloads from vc-arch.el + (defun vc-arch-registered (file) + (if (vc-find-root file "{arch}/=tagging-method") + (progn + (load "vc-arch") + (vc-arch-registered file)))) + +;;;*** + +;;;### (autoloads nil "vc-bzr" "vc-bzr.el" (19005 47387)) +;;; Generated autoloads from vc-bzr.el + +(defconst vc-bzr-admin-dirname ".bzr" "\ +Name of the directory containing Bzr repository status files.") + +(defconst vc-bzr-admin-checkout-format-file (concat vc-bzr-admin-dirname "/checkout/format")) + (defun vc-bzr-registered (file) + (if (vc-find-root file vc-bzr-admin-checkout-format-file) + (progn + (load "vc-bzr") + (vc-bzr-registered file)))) + +;;;*** + +;;;### (autoloads nil "vc-cvs" "vc-cvs.el" (19005 47387)) +;;; Generated autoloads from vc-cvs.el + (defun vc-cvs-registered (f) + (when (file-readable-p (expand-file-name + "CVS/Entries" (file-name-directory f))) + (load "vc-cvs") + (vc-cvs-registered f))) + +;;;*** + +;;;### (autoloads (vc-dir) "vc-dir" "vc-dir.el" (18911 21861)) +;;; Generated autoloads from vc-dir.el + +(autoload 'vc-dir "vc-dir" "\ +Show the VC status for \"interesting\" files in and below DIR. +This allows you to mark files and perform VC operations on them. +The list omits files which are up to date, with no changes in your copy +or the repository, if there is nothing in particular to say about them. + +Preparing the list of file status takes time; when the buffer +first appears, it has only the first few lines of summary information. +The file lines appear later. + +Optional second argument BACKEND specifies the VC backend to use. +Interactively, a prefix argument means to ask for the backend. + +These are the commands available for use in the file status buffer: + +\\ + +\(fn DIR &optional BACKEND)" t nil) + +;;;*** + +;;;### (autoloads (vc-do-command) "vc-dispatcher" "vc-dispatcher.el" +;;;;;; (18785 31832)) +;;; Generated autoloads from vc-dispatcher.el + +(autoload 'vc-do-command "vc-dispatcher" "\ +Execute a slave command, notifying user and checking for errors. +Output from COMMAND goes to BUFFER, or the current buffer if +BUFFER is t. If the destination buffer is not already current, +set it up properly and erase it. The command is considered +successful if its exit status does not exceed OKSTATUS (if +OKSTATUS is nil, that means to ignore error status, if it is +`async', that means not to wait for termination of the +subprocess; if it is t it means to ignore all execution errors). +FILE-OR-LIST is the name of a working file; it may be a list of +files or be nil (to execute commands that don't expect a file +name or set of files). If an optional list of FLAGS is present, +that is inserted into the command line before the filename. + +\(fn BUFFER OKSTATUS COMMAND FILE-OR-LIST &rest FLAGS)" nil nil) + +;;;*** + +;;;### (autoloads nil "vc-git" "vc-git.el" (19005 47387)) +;;; Generated autoloads from vc-git.el + (defun vc-git-registered (file) + "Return non-nil if FILE is registered with git." + (if (vc-find-root file ".git") ; short cut + (progn + (load "vc-git") + (vc-git-registered file)))) + +;;;*** + +;;;### (autoloads nil "vc-hg" "vc-hg.el" (19005 47387)) +;;; Generated autoloads from vc-hg.el + (defun vc-hg-registered (file) + "Return non-nil if FILE is registered with hg." + (if (vc-find-root file ".hg") ; short cut + (progn + (load "vc-hg") + (vc-hg-registered file)))) + +;;;*** + +;;;### (autoloads nil "vc-mtn" "vc-mtn.el" (19005 47387)) +;;; Generated autoloads from vc-mtn.el + +(defconst vc-mtn-admin-dir "_MTN") + +(defconst vc-mtn-admin-format (concat vc-mtn-admin-dir "/format")) + (defun vc-mtn-registered (file) + (if (vc-find-root file vc-mtn-admin-format) + (progn + (load "vc-mtn") + (vc-mtn-registered file)))) + +;;;*** + +;;;### (autoloads (vc-rcs-master-templates) "vc-rcs" "vc-rcs.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from vc-rcs.el + +(defvar vc-rcs-master-templates '("%sRCS/%s,v" "%s%s,v" "%sRCS/%s") "\ +Where to look for RCS master files. +For a description of possible values, see `vc-check-master-templates'.") + +(custom-autoload 'vc-rcs-master-templates "vc-rcs" t) + +(defun vc-rcs-registered (f) (vc-default-registered 'RCS f)) + +;;;*** + +;;;### (autoloads (vc-sccs-master-templates) "vc-sccs" "vc-sccs.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from vc-sccs.el + +(defvar vc-sccs-master-templates '("%sSCCS/s.%s" "%ss.%s" vc-sccs-search-project-dir) "\ +Where to look for SCCS master files. +For a description of possible values, see `vc-check-master-templates'.") + +(custom-autoload 'vc-sccs-master-templates "vc-sccs" t) + (defun vc-sccs-registered(f) (vc-default-registered 'SCCS f)) + +(defun vc-sccs-search-project-dir (dirname basename) "\ +Return the name of a master file in the SCCS project directory. +Does not check whether the file exists but returns nil if it does not +find any project directory." (let ((project-dir (getenv "PROJECTDIR")) dirs dir) (when project-dir (if (file-name-absolute-p project-dir) (setq dirs (quote ("SCCS" ""))) (setq dirs (quote ("src/SCCS" "src" "source/SCCS" "source"))) (setq project-dir (expand-file-name (concat "~" project-dir)))) (while (and (not dir) dirs) (setq dir (expand-file-name (car dirs) project-dir)) (unless (file-directory-p dir) (setq dir nil) (setq dirs (cdr dirs)))) (and dir (expand-file-name (concat "s." basename) dir))))) + +;;;*** + +;;;### (autoloads nil "vc-svn" "vc-svn.el" (19005 47387)) +;;; Generated autoloads from vc-svn.el + (defun vc-svn-registered (f) + (let ((admin-dir (cond ((and (eq system-type 'windows-nt) + (getenv "SVN_ASP_DOT_NET_HACK")) + "_svn") + (t ".svn")))) + (when (file-readable-p (expand-file-name + (concat admin-dir "/entries") + (file-name-directory f))) + (load "vc-svn") + (vc-svn-registered f)))) + +;;;*** + +;;;### (autoloads (vera-mode) "vera-mode" "progmodes/vera-mode.el" +;;;;;; (19005 47404)) +;;; Generated autoloads from progmodes/vera-mode.el + (add-to-list 'auto-mode-alist '("\\.vr[hi]?\\'" . vera-mode)) + +(autoload 'vera-mode "vera-mode" "\ +Major mode for editing Vera code. + +Usage: +------ + + INDENTATION: Typing `TAB' at the beginning of a line indents the line. + The amount of indentation is specified by option `vera-basic-offset'. + Indentation can be done for an entire region (`M-C-\\') or buffer (menu). + `TAB' always indents the line if option `vera-intelligent-tab' is nil. + + WORD/COMMAND COMPLETION: Typing `TAB' after a (not completed) word looks + for a word in the buffer or a Vera keyword that starts alike, inserts it + and adjusts case. Re-typing `TAB' toggles through alternative word + completions. + + Typing `TAB' after a non-word character inserts a tabulator stop (if not + at the beginning of a line). `M-TAB' always inserts a tabulator stop. + + COMMENTS: `C-c C-c' comments out a region if not commented out, and + uncomments a region if already commented out. + + HIGHLIGHTING (fontification): Vera keywords, predefined types and + constants, function names, declaration names, directives, as well as + comments and strings are highlighted using different colors. + + VERA VERSION: OpenVera 1.4 and Vera version 6.2.8. + + +Maintenance: +------------ + +To submit a bug report, use the corresponding menu entry within Vera Mode. +Add a description of the problem and include a reproducible test case. + +Feel free to send questions and enhancement requests to . + +Official distribution is at +. + + + The Vera Mode Maintainer + Reto Zimmermann + +Key bindings: +------------- + +\\{vera-mode-map} + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (verilog-mode) "verilog-mode" "progmodes/verilog-mode.el" +;;;;;; (19005 47405)) +;;; Generated autoloads from progmodes/verilog-mode.el + +(autoload 'verilog-mode "verilog-mode" "\ +Major mode for editing Verilog code. +\\ +See \\[describe-function] verilog-auto (\\[verilog-auto]) for details on how +AUTOs can improve coding efficiency. + +Use \\[verilog-faq] for a pointer to frequently asked questions. + +NEWLINE, TAB indents for Verilog code. +Delete converts tabs to spaces as it moves back. + +Supports highlighting. + +Turning on Verilog mode calls the value of the variable `verilog-mode-hook' +with no args, if that value is non-nil. + +Variables controlling indentation/edit style: + + variable `verilog-indent-level' (default 3) + Indentation of Verilog statements with respect to containing block. + `verilog-indent-level-module' (default 3) + Absolute indentation of Module level Verilog statements. + Set to 0 to get initial and always statements lined up + on the left side of your screen. + `verilog-indent-level-declaration' (default 3) + Indentation of declarations with respect to containing block. + Set to 0 to get them list right under containing block. + `verilog-indent-level-behavioral' (default 3) + Indentation of first begin in a task or function block + Set to 0 to get such code to lined up underneath the task or + function keyword. + `verilog-indent-level-directive' (default 1) + Indentation of `ifdef/`endif blocks. + `verilog-cexp-indent' (default 1) + Indentation of Verilog statements broken across lines i.e.: + if (a) + begin + `verilog-case-indent' (default 2) + Indentation for case statements. + `verilog-auto-newline' (default nil) + Non-nil means automatically newline after semicolons and the punctuation + mark after an end. + `verilog-auto-indent-on-newline' (default t) + Non-nil means automatically indent line after newline. + `verilog-tab-always-indent' (default t) + Non-nil means TAB in Verilog mode should always reindent the current line, + regardless of where in the line point is when the TAB command is used. + `verilog-indent-begin-after-if' (default t) + Non-nil means to indent begin statements following a preceding + if, else, while, for and repeat statements, if any. Otherwise, + the begin is lined up with the preceding token. If t, you get: + if (a) + begin // amount of indent based on `verilog-cexp-indent' + otherwise you get: + if (a) + begin + `verilog-auto-endcomments' (default t) + Non-nil means a comment /* ... */ is set after the ends which ends + cases, tasks, functions and modules. + The type and name of the object will be set between the braces. + `verilog-minimum-comment-distance' (default 10) + Minimum distance (in lines) between begin and end required before a comment + will be inserted. Setting this variable to zero results in every + end acquiring a comment; the default avoids too many redundant + comments in tight quarters. + `verilog-auto-lineup' (default `(all)) + List of contexts where auto lineup of code should be done. + +Variables controlling other actions: + + `verilog-linter' (default surelint) + Unix program to call to run the lint checker. This is the default + command for \\[compile-command] and \\[verilog-auto-save-compile]. + +See \\[customize] for the complete list of variables. + +AUTO expansion functions are, in part: + + \\[verilog-auto] Expand AUTO statements. + \\[verilog-delete-auto] Remove the AUTOs. + \\[verilog-inject-auto] Insert AUTOs for the first time. + +Some other functions are: + + \\[verilog-complete-word] Complete word with appropriate possibilities. + \\[verilog-mark-defun] Mark function. + \\[verilog-beg-of-defun] Move to beginning of current function. + \\[verilog-end-of-defun] Move to end of current function. + \\[verilog-label-be] Label matching begin ... end, fork ... join, etc statements. + + \\[verilog-comment-region] Put marked area in a comment. + \\[verilog-uncomment-region] Uncomment an area commented with \\[verilog-comment-region]. + \\[verilog-insert-block] Insert begin ... end. + \\[verilog-star-comment] Insert /* ... */. + + \\[verilog-sk-always] Insert an always @(AS) begin .. end block. + \\[verilog-sk-begin] Insert a begin .. end block. + \\[verilog-sk-case] Insert a case block, prompting for details. + \\[verilog-sk-for] Insert a for (...) begin .. end block, prompting for details. + \\[verilog-sk-generate] Insert a generate .. endgenerate block. + \\[verilog-sk-header] Insert a header block at the top of file. + \\[verilog-sk-initial] Insert an initial begin .. end block. + \\[verilog-sk-fork] Insert a fork begin .. end .. join block. + \\[verilog-sk-module] Insert a module .. (/*AUTOARG*/);.. endmodule block. + \\[verilog-sk-primitive] Insert a primitive .. (.. );.. endprimitive block. + \\[verilog-sk-repeat] Insert a repeat (..) begin .. end block. + \\[verilog-sk-specify] Insert a specify .. endspecify block. + \\[verilog-sk-task] Insert a task .. begin .. end endtask block. + \\[verilog-sk-while] Insert a while (...) begin .. end block, prompting for details. + \\[verilog-sk-casex] Insert a casex (...) item: begin.. end endcase block, prompting for details. + \\[verilog-sk-casez] Insert a casez (...) item: begin.. end endcase block, prompting for details. + \\[verilog-sk-if] Insert an if (..) begin .. end block. + \\[verilog-sk-else-if] Insert an else if (..) begin .. end block. + \\[verilog-sk-comment] Insert a comment block. + \\[verilog-sk-assign] Insert an assign .. = ..; statement. + \\[verilog-sk-function] Insert a function .. begin .. end endfunction block. + \\[verilog-sk-input] Insert an input declaration, prompting for details. + \\[verilog-sk-output] Insert an output declaration, prompting for details. + \\[verilog-sk-state-machine] Insert a state machine definition, prompting for details. + \\[verilog-sk-inout] Insert an inout declaration, prompting for details. + \\[verilog-sk-wire] Insert a wire declaration, prompting for details. + \\[verilog-sk-reg] Insert a register declaration, prompting for details. + \\[verilog-sk-define-signal] Define signal under point as a register at the top of the module. + +All key bindings can be seen in a Verilog-buffer with \\[describe-bindings]. +Key bindings specific to `verilog-mode-map' are: + +\\{verilog-mode-map} + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (vhdl-mode) "vhdl-mode" "progmodes/vhdl-mode.el" +;;;;;; (19005 47405)) +;;; Generated autoloads from progmodes/vhdl-mode.el + +(autoload 'vhdl-mode "vhdl-mode" "\ +Major mode for editing VHDL code. + +Usage: +------ + + TEMPLATE INSERTION (electrification): + After typing a VHDL keyword and entering `SPC', you are prompted for + arguments while a template is generated for that VHDL construct. Typing + `RET' or `C-g' at the first (mandatory) prompt aborts the current + template generation. Optional arguments are indicated by square + brackets and removed if the queried string is left empty. Prompts for + mandatory arguments remain in the code if the queried string is left + empty. They can be queried again by `C-c C-t C-q'. Enabled + electrification is indicated by `/e' in the modeline. + + Typing `M-SPC' after a keyword inserts a space without calling the + template generator. Automatic template generation (i.e. + electrification) can be disabled (enabled) by typing `C-c C-m C-e' or by + setting option `vhdl-electric-mode' (see OPTIONS). + + Template generators can be invoked from the VHDL menu, by key + bindings, by typing `C-c C-i C-c' and choosing a construct, or by typing + the keyword (i.e. first word of menu entry not in parenthesis) and + `SPC'. The following abbreviations can also be used: arch, attr, cond, + conf, comp, cons, func, inst, pack, sig, var. + + Template styles can be customized in customization group + `vhdl-template' (see OPTIONS). + + + HEADER INSERTION: + A file header can be inserted by `C-c C-t C-h'. A file footer + (template at the end of the file) can be inserted by `C-c C-t C-f'. + See customization group `vhdl-header'. + + + STUTTERING: + Double striking of some keys inserts cumbersome VHDL syntax elements. + Stuttering can be disabled (enabled) by typing `C-c C-m C-s' or by + option `vhdl-stutter-mode'. Enabled stuttering is indicated by `/s' in + the modeline. The stuttering keys and their effects are: + + ;; --> \" : \" [ --> ( -- --> comment + ;;; --> \" := \" [[ --> [ --CR --> comment-out code + .. --> \" => \" ] --> ) --- --> horizontal line + ,, --> \" <= \" ]] --> ] ---- --> display comment + == --> \" == \" '' --> \\\" + + + WORD COMPLETION: + Typing `TAB' after a (not completed) word looks for a VHDL keyword or a + word in the buffer that starts alike, inserts it and adjusts case. + Re-typing `TAB' toggles through alternative word completions. This also + works in the minibuffer (i.e. in template generator prompts). + + Typing `TAB' after `(' looks for and inserts complete parenthesized + expressions (e.g. for array index ranges). All keywords as well as + standard types and subprograms of VHDL have predefined abbreviations + (e.g. type \"std\" and `TAB' will toggle through all standard types + beginning with \"std\"). + + Typing `TAB' after a non-word character indents the line if at the + beginning of a line (i.e. no preceding non-blank characters), and + inserts a tabulator stop otherwise. `M-TAB' always inserts a tabulator + stop. + + + COMMENTS: + `--' puts a single comment. + `---' draws a horizontal line for separating code segments. + `----' inserts a display comment, i.e. two horizontal lines + with a comment in between. + `--CR' comments out code on that line. Re-hitting CR comments + out following lines. + `C-c c' comments out a region if not commented out, + uncomments a region if already commented out. + + You are prompted for comments after object definitions (i.e. signals, + variables, constants, ports) and after subprogram and process + specifications if option `vhdl-prompt-for-comments' is non-nil. + Comments are automatically inserted as additional labels (e.g. after + begin statements) and as help comments if `vhdl-self-insert-comments' is + non-nil. + + Inline comments (i.e. comments after a piece of code on the same line) + are indented at least to `vhdl-inline-comment-column'. Comments go at + maximum to `vhdl-end-comment-column'. `RET' after a space in a comment + will open a new comment line. Typing beyond `vhdl-end-comment-column' + in a comment automatically opens a new comment line. `M-q' re-fills + multi-line comments. + + + INDENTATION: + `TAB' indents a line if at the beginning of the line. The amount of + indentation is specified by option `vhdl-basic-offset'. `C-c C-i C-l' + always indents the current line (is bound to `TAB' if option + `vhdl-intelligent-tab' is nil). + + Indentation can be done for a group of lines (`C-c C-i C-g'), a region + (`M-C-\\') or the entire buffer (menu). Argument and port lists are + indented normally (nil) or relative to the opening parenthesis (non-nil) + according to option `vhdl-argument-list-indent'. + + If option `vhdl-indent-tabs-mode' is nil, spaces are used instead of + tabs. `M-x tabify' and `M-x untabify' allow to convert spaces to tabs + and vice versa. + + Syntax-based indentation can be very slow in large files. Option + `vhdl-indent-syntax-based' allows to use faster but simpler indentation. + + + ALIGNMENT: + The alignment functions align operators, keywords, and inline comments + to beautify the code. `C-c C-a C-a' aligns a group of consecutive lines + separated by blank lines, `C-c C-a C-i' a block of lines with same + indent. `C-c C-a C-l' aligns all lines belonging to a list enclosed by + a pair of parentheses (e.g. port clause/map, argument list), and `C-c + C-a C-d' all lines within the declarative part of a design unit. `C-c + C-a M-a' aligns an entire region. `C-c C-a C-c' aligns inline comments + for a group of lines, and `C-c C-a M-c' for a region. + + If option `vhdl-align-groups' is non-nil, groups of code lines + separated by special lines (see option `vhdl-align-group-separate') are + aligned individually. If option `vhdl-align-same-indent' is non-nil, + blocks of lines with same indent are aligned separately. Some templates + are automatically aligned after generation if option `vhdl-auto-align' + is non-nil. + + Alignment tries to align inline comments at + `vhdl-inline-comment-column' and tries inline comment not to exceed + `vhdl-end-comment-column'. + + `C-c C-x M-w' fixes up whitespace in a region. That is, operator + symbols are surrounded by one space, and multiple spaces are eliminated. + + + CODE FILLING: + Code filling allows to condense code (e.g. sensitivity lists or port + maps) by removing comments and newlines and re-wrapping so that all + lines are maximally filled (block filling). `C-c C-f C-f' fills a list + enclosed by parenthesis, `C-c C-f C-g' a group of lines separated by + blank lines, `C-c C-f C-i' a block of lines with same indent, and + `C-c C-f M-f' an entire region. + + + CODE BEAUTIFICATION: + `C-c M-b' and `C-c C-b' beautify the code of a region or of the entire + buffer respectively. This inludes indentation, alignment, and case + fixing. Code beautification can also be run non-interactively using the + command: + + emacs -batch -l ~/.emacs filename.vhd -f vhdl-beautify-buffer + + + PORT TRANSLATION: + Generic and port clauses from entity or component declarations can be + copied (`C-c C-p C-w') and pasted as entity and component declarations, + as component instantiations and corresponding internal constants and + signals, as a generic map with constants as actual generics, and as + internal signal initializations (menu). + + To include formals in component instantiations, see option + `vhdl-association-list-with-formals'. To include comments in pasting, + see options `vhdl-include-...-comments'. + + A clause with several generic/port names on the same line can be + flattened (`C-c C-p C-f') so that only one name per line exists. The + direction of ports can be reversed (`C-c C-p C-r'), i.e., inputs become + outputs and vice versa, which can be useful in testbenches. (This + reversion is done on the internal data structure and is only reflected + in subsequent paste operations.) + + Names for actual ports, instances, testbenches, and + design-under-test instances can be derived from existing names according + to options `vhdl-...-name'. See customization group `vhdl-port'. + + + SUBPROGRAM TRANSLATION: + Similar functionality exists for copying/pasting the interface of + subprograms (function/procedure). A subprogram interface can be copied + and then pasted as a subprogram declaration, body or call (uses + association list with formals). + + + TESTBENCH GENERATION: + A copied port can also be pasted as a testbench. The generated + testbench includes an entity, an architecture, and an optional + configuration. The architecture contains the component declaration and + instantiation of the DUT as well as internal constant and signal + declarations. Additional user-defined templates can be inserted. The + names used for entity/architecture/configuration/DUT as well as the file + structure to be generated can be customized. See customization group + `vhdl-testbench'. + + + KEY BINDINGS: + Key bindings (`C-c ...') exist for most commands (see in menu). + + + VHDL MENU: + All commands can be found in the VHDL menu including their key bindings. + + + FILE BROWSER: + The speedbar allows browsing of directories and file contents. It can + be accessed from the VHDL menu and is automatically opened if option + `vhdl-speedbar-auto-open' is non-nil. + + In speedbar, open files and directories with `mouse-2' on the name and + browse/rescan their contents with `mouse-2'/`S-mouse-2' on the `+'. + + + DESIGN HIERARCHY BROWSER: + The speedbar can also be used for browsing the hierarchy of design units + contained in the source files of the current directory or the specified + projects (see option `vhdl-project-alist'). + + The speedbar can be switched between file, directory hierarchy and + project hierarchy browsing mode in the speedbar menu or by typing `f', + `h' or `H' in speedbar. + + In speedbar, open design units with `mouse-2' on the name and browse + their hierarchy with `mouse-2' on the `+'. Ports can directly be copied + from entities and components (in packages). Individual design units and + complete designs can directly be compiled (\"Make\" menu entry). + + The hierarchy is automatically updated upon saving a modified source + file when option `vhdl-speedbar-update-on-saving' is non-nil. The + hierarchy is only updated for projects that have been opened once in the + speedbar. The hierarchy is cached between Emacs sessions in a file (see + options in group `vhdl-speedbar'). + + Simple design consistency checks are done during scanning, such as + multiple declarations of the same unit or missing primary units that are + required by secondary units. + + + STRUCTURAL COMPOSITION: + Enables simple structural composition. `C-c C-c C-n' creates a skeleton + for a new component. Subcomponents (i.e. component declaration and + instantiation) can be automatically placed from a previously read port + (`C-c C-c C-p') or directly from the hierarchy browser (`P'). Finally, + all subcomponents can be automatically connected using internal signals + and ports (`C-c C-c C-w') following these rules: + - subcomponent actual ports with same name are considered to be + connected by a signal (internal signal or port) + - signals that are only inputs to subcomponents are considered as + inputs to this component -> input port created + - signals that are only outputs from subcomponents are considered as + outputs from this component -> output port created + - signals that are inputs to AND outputs from subcomponents are + considered as internal connections -> internal signal created + + Purpose: With appropriate naming conventions it is possible to + create higher design levels with only a few mouse clicks or key + strokes. A new design level can be created by simply generating a new + component, placing the required subcomponents from the hierarchy + browser, and wiring everything automatically. + + Note: Automatic wiring only works reliably on templates of new + components and component instantiations that were created by VHDL mode. + + Component declarations can be placed in a components package (option + `vhdl-use-components-package') which can be automatically generated for + an entire directory or project (`C-c C-c M-p'). The VHDL'93 direct + component instantiation is also supported (option + `vhdl-use-direct-instantiation'). + +| Configuration declarations can automatically be generated either from +| the menu (`C-c C-c C-f') (for the architecture the cursor is in) or from +| the speedbar menu (for the architecture under the cursor). The +| configurations can optionally be hierarchical (i.e. include all +| component levels of a hierarchical design, option +| `vhdl-compose-configuration-hierarchical') or include subconfigurations +| (option `vhdl-compose-configuration-use-subconfiguration'). For +| subcomponents in hierarchical configurations, the most-recently-analyzed +| (mra) architecture is selected. If another architecture is desired, it +| can be marked as most-recently-analyzed (speedbar menu) before +| generating the configuration. +| +| Note: Configurations of subcomponents (i.e. hierarchical configuration +| declarations) are currently not considered when displaying +| configurations in speedbar. + + See the options group `vhdl-compose' for all relevant user options. + + + SOURCE FILE COMPILATION: + The syntax of the current buffer can be analyzed by calling a VHDL + compiler (menu, `C-c C-k'). The compiler to be used is specified by + option `vhdl-compiler'. The available compilers are listed in option + `vhdl-compiler-alist' including all required compilation command, + command options, compilation directory, and error message syntax + information. New compilers can be added. + + All the source files of an entire design can be compiled by the `make' + command (menu, `C-c M-C-k') if an appropriate Makefile exists. + + + MAKEFILE GENERATION: + Makefiles can be generated automatically by an internal generation + routine (`C-c M-k'). The library unit dependency information is + obtained from the hierarchy browser. Makefile generation can be + customized for each compiler in option `vhdl-compiler-alist'. + + Makefile generation can also be run non-interactively using the + command: + + emacs -batch -l ~/.emacs -l vhdl-mode + [-compiler compilername] [-project projectname] + -f vhdl-generate-makefile + + The Makefile's default target \"all\" compiles the entire design, the + target \"clean\" removes it and the target \"library\" creates the + library directory if not existent. The Makefile also includes a target + for each primary library unit which allows selective compilation of this + unit, its secondary units and its subhierarchy (example: compilation of + a design specified by a configuration). User specific parts can be + inserted into a Makefile with option `vhdl-makefile-generation-hook'. + + Limitations: + - Only library units and dependencies within the current library are + considered. Makefiles for designs that span multiple libraries are + not (yet) supported. + - Only one-level configurations are supported (also hierarchical), + but configurations that go down several levels are not. + - The \"others\" keyword in configurations is not supported. + + + PROJECTS: + Projects can be defined in option `vhdl-project-alist' and a current + project be selected using option `vhdl-project' (permanently) or from + the menu or speedbar (temporarily). For each project, title and + description strings (for the file headers), source files/directories + (for the hierarchy browser and Makefile generation), library name, and + compiler-dependent options, exceptions and compilation directory can be + specified. Compilation settings overwrite the settings of option + `vhdl-compiler-alist'. + + Project setups can be exported (i.e. written to a file) and imported. + Imported setups are not automatically saved in `vhdl-project-alist' but + can be saved afterwards in its customization buffer. When starting + Emacs with VHDL Mode (i.e. load a VHDL file or use \"emacs -l + vhdl-mode\") in a directory with an existing project setup file, it is + automatically loaded and its project activated if option + `vhdl-project-auto-load' is non-nil. Names/paths of the project setup + files can be specified in option `vhdl-project-file-name'. Multiple + project setups can be automatically loaded from global directories. + This is an alternative to specifying project setups with option + `vhdl-project-alist'. + + + SPECIAL MENUES: + As an alternative to the speedbar, an index menu can be added (set + option `vhdl-index-menu' to non-nil) or made accessible as a mouse menu + (e.g. add \"(global-set-key '[S-down-mouse-3] 'imenu)\" to your start-up + file) for browsing the file contents (is not populated if buffer is + larger than `font-lock-maximum-size'). Also, a source file menu can be + added (set option `vhdl-source-file-menu' to non-nil) for browsing the + current directory for VHDL source files. + + + VHDL STANDARDS: + The VHDL standards to be used are specified in option `vhdl-standard'. + Available standards are: VHDL'87/'93, VHDL-AMS, and Math Packages. + + + KEYWORD CASE: + Lower and upper case for keywords and standardized types, attributes, + and enumeration values is supported. If the option + `vhdl-upper-case-keywords' is set to non-nil, keywords can be typed in + lower case and are converted into upper case automatically (not for + types, attributes, and enumeration values). The case of keywords, + types, attributes,and enumeration values can be fixed for an entire + region (menu) or buffer (`C-c C-x C-c') according to the options + `vhdl-upper-case-{keywords,types,attributes,enum-values}'. + + + HIGHLIGHTING (fontification): + Keywords and standardized types, attributes, enumeration values, and + function names (controlled by option `vhdl-highlight-keywords'), as well + as comments, strings, and template prompts are highlighted using + different colors. Unit, subprogram, signal, variable, constant, + parameter and generic/port names in declarations as well as labels are + highlighted if option `vhdl-highlight-names' is non-nil. + + Additional reserved words or words with a forbidden syntax (e.g. words + that should be avoided) can be specified in option + `vhdl-forbidden-words' or `vhdl-forbidden-syntax' and be highlighted in + a warning color (option `vhdl-highlight-forbidden-words'). Verilog + keywords are highlighted as forbidden words if option + `vhdl-highlight-verilog-keywords' is non-nil. + + Words with special syntax can be highlighted by specifying their + syntax and color in option `vhdl-special-syntax-alist' and by setting + option `vhdl-highlight-special-words' to non-nil. This allows to + establish some naming conventions (e.g. to distinguish different kinds + of signals or other objects by using name suffices) and to support them + visually. + + Option `vhdl-highlight-case-sensitive' can be set to non-nil in order + to support case-sensitive highlighting. However, keywords are then only + highlighted if written in lower case. + + Code between \"translate_off\" and \"translate_on\" pragmas is + highlighted using a different background color if option + `vhdl-highlight-translate-off' is non-nil. + + For documentation and customization of the used colors see + customization group `vhdl-highlight-faces' (`M-x customize-group'). For + highlighting of matching parenthesis, see customization group + `paren-showing'. Automatic buffer highlighting is turned on/off by + option `global-font-lock-mode' (`font-lock-auto-fontify' in XEmacs). + + + USER MODELS: + VHDL models (templates) can be specified by the user and made accessible + in the menu, through key bindings (`C-c C-m ...'), or by keyword + electrification. See option `vhdl-model-alist'. + + + HIDE/SHOW: + The code of blocks, processes, subprograms, component declarations and + instantiations, generic/port clauses, and configuration declarations can + be hidden using the `Hide/Show' menu or by pressing `S-mouse-2' within + the code (see customization group `vhdl-menu'). XEmacs: limited + functionality due to old `hideshow.el' package. + + + CODE UPDATING: + - Sensitivity List: `C-c C-u C-s' updates the sensitivity list of the + current process, `C-c C-u M-s' of all processes in the current buffer. + Limitations: + - Only declared local signals (ports, signals declared in + architecture and blocks) are automatically inserted. + - Global signals declared in packages are not automatically inserted. + Insert them once manually (will be kept afterwards). + - Out parameters of procedures are considered to be read. + Use option `vhdl-entity-file-name' to specify the entity file name + (used to obtain the port names). + + + CODE FIXING: + `C-c C-x C-p' fixes the closing parenthesis of a generic/port clause + (e.g. if the closing parenthesis is on the wrong line or is missing). + + + PRINTING: + Postscript printing with different faces (an optimized set of faces is + used if `vhdl-print-customize-faces' is non-nil) or colors (if + `ps-print-color-p' is non-nil) is possible using the standard Emacs + postscript printing commands. Option `vhdl-print-two-column' defines + appropriate default settings for nice landscape two-column printing. + The paper format can be set by option `ps-paper-type'. Do not forget to + switch `ps-print-color-p' to nil for printing on black-and-white + printers. + + + OPTIONS: + User options allow customization of VHDL Mode. All options are + accessible from the \"Options\" menu entry. Simple options (switches + and choices) can directly be changed, while for complex options a + customization buffer is opened. Changed options can be saved for future + sessions using the \"Save Options\" menu entry. + + Options and their detailed descriptions can also be accessed by using + the \"Customize\" menu entry or the command `M-x customize-option' (`M-x + customize-group' for groups). Some customizations only take effect + after some action (read the NOTE in the option documentation). + Customization can also be done globally (i.e. site-wide, read the + INSTALL file). + + Not all options are described in this documentation, so go and see + what other useful user options there are (`M-x vhdl-customize' or menu)! + + + FILE EXTENSIONS: + As default, files with extensions \".vhd\" and \".vhdl\" are + automatically recognized as VHDL source files. To add an extension + \".xxx\", add the following line to your Emacs start-up file (`.emacs'): + + (setq auto-mode-alist (cons '(\"\\\\.xxx\\\\'\" . vhdl-mode) auto-mode-alist)) + + + HINTS: + - To start Emacs with open VHDL hierarchy browser without having to load + a VHDL file first, use the command: + + emacs -l vhdl-mode -f speedbar-frame-mode + + - Type `C-g C-g' to interrupt long operations or if Emacs hangs. + + - Some features only work on properly indented code. + + + RELEASE NOTES: + See also the release notes (menu) for added features in new releases. + + +Maintenance: +------------ + +To submit a bug report, enter `M-x vhdl-submit-bug-report' within VHDL Mode. +Add a description of the problem and include a reproducible test case. + +Questions and enhancement requests can be sent to . + +The `vhdl-mode-announce' mailing list informs about new VHDL Mode releases. +The `vhdl-mode-victims' mailing list informs about new VHDL Mode beta +releases. You are kindly invited to participate in beta testing. Subscribe +to above mailing lists by sending an email to . + +VHDL Mode is officially distributed at +http://opensource.ethz.ch/emacs/vhdl-mode.html +where the latest version can be found. + + +Known problems: +--------------- + +- Indentation bug in simultaneous if- and case-statements (VHDL-AMS). +- XEmacs: Incorrect start-up when automatically opening speedbar. +- XEmacs: Indentation in XEmacs 21.4 (and higher). + + + The VHDL Mode Authors + Reto Zimmermann and Rod Whitby + +Key bindings: +------------- + +\\{vhdl-mode-map} + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (vi-mode) "vi" "emulation/vi.el" (19005 47390)) +;;; Generated autoloads from emulation/vi.el + +(autoload 'vi-mode "vi" "\ +Major mode that acts like the `vi' editor. +The purpose of this mode is to provide you the combined power of vi (namely, +the \"cross product\" effect of commands and repeat last changes) and Emacs. + +This command redefines nearly all keys to look like vi commands. +It records the previous major mode, and any vi command for input +\(`i', `a', `s', etc.) switches back to that mode. +Thus, ordinary Emacs (in whatever major mode you had been using) +is \"input\" mode as far as vi is concerned. + +To get back into vi from \"input\" mode, you must issue this command again. +Therefore, it is recommended that you assign it to a key. + +Major differences between this mode and real vi : + +* Limitations and unsupported features + - Search patterns with line offset (e.g. /pat/+3 or /pat/z.) are + not supported. + - Ex commands are not implemented; try ':' to get some hints. + - No line undo (i.e. the 'U' command), but multi-undo is a standard feature. + +* Modifications + - The stopping positions for some point motion commands (word boundary, + pattern search) are slightly different from standard 'vi'. + Also, no automatic wrap around at end of buffer for pattern searching. + - Since changes are done in two steps (deletion then insertion), you need + to undo twice to completely undo a change command. But this is not needed + for undoing a repeated change command. + - No need to set/unset 'magic', to search for a string with regular expr + in it just put a prefix arg for the search commands. Replace cmds too. + - ^R is bound to incremental backward search, so use ^L to redraw screen. + +* Extensions + - Some standard (or modified) Emacs commands were integrated, such as + incremental search, query replace, transpose objects, and keyboard macros. + - In command state, ^X links to the 'ctl-x-map', and ESC can be linked to + esc-map or set undefined. These can give you the full power of Emacs. + - See vi-com-map for those keys that are extensions to standard vi, e.g. + `vi-name-last-change-or-macro', `vi-verify-spelling', `vi-locate-def', + `vi-mark-region', and 'vi-quote-words'. Some of them are quite handy. + - Use \\[vi-switch-mode] to switch among different modes quickly. + +Syntax table and abbrevs while in vi mode remain as they were in Emacs. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (viqr-pre-write-conversion viqr-post-read-conversion +;;;;;; viet-encode-viqr-buffer viet-encode-viqr-region viet-decode-viqr-buffer +;;;;;; viet-decode-viqr-region viet-encode-viscii-char) "viet-util" +;;;;;; "language/viet-util.el" (19005 47397)) +;;; Generated autoloads from language/viet-util.el + +(autoload 'viet-encode-viscii-char "viet-util" "\ +Return VISCII character code of CHAR if appropriate. + +\(fn CHAR)" nil nil) + +(autoload 'viet-decode-viqr-region "viet-util" "\ +Convert `VIQR' mnemonics of the current region to Vietnamese characters. +When called from a program, expects two arguments, +positions (integers or markers) specifying the stretch of the region. + +\(fn FROM TO)" t nil) + +(autoload 'viet-decode-viqr-buffer "viet-util" "\ +Convert `VIQR' mnemonics of the current buffer to Vietnamese characters. + +\(fn)" t nil) + +(autoload 'viet-encode-viqr-region "viet-util" "\ +Convert Vietnamese characters of the current region to `VIQR' mnemonics. +When called from a program, expects two arguments, +positions (integers or markers) specifying the stretch of the region. + +\(fn FROM TO)" t nil) + +(autoload 'viet-encode-viqr-buffer "viet-util" "\ +Convert Vietnamese characters of the current buffer to `VIQR' mnemonics. + +\(fn)" t nil) + +(autoload 'viqr-post-read-conversion "viet-util" "\ +Not documented + +\(fn LEN)" nil nil) + +(autoload 'viqr-pre-write-conversion "viet-util" "\ +Not documented + +\(fn FROM TO)" nil nil) + +;;;*** + +;;;### (autoloads (View-exit-and-edit view-mode-enter view-return-to-alist-update +;;;;;; view-mode view-buffer-other-frame view-buffer-other-window +;;;;;; view-buffer view-file-other-frame view-file-other-window +;;;;;; view-file kill-buffer-if-not-modified view-remove-frame-by-deleting) +;;;;;; "view" "view.el" (19005 47387)) +;;; Generated autoloads from view.el + +(defvar view-remove-frame-by-deleting t "\ +Determine how View mode removes a frame no longer needed. +If nil, make an icon of the frame. If non-nil, delete the frame.") + +(custom-autoload 'view-remove-frame-by-deleting "view" t) + +(defvar view-mode nil "\ +Non-nil if View mode is enabled. +Don't change this variable directly, you must change it by one of the +functions that enable or disable view mode.") + +(make-variable-buffer-local 'view-mode) + +(autoload 'kill-buffer-if-not-modified "view" "\ +Like `kill-buffer', but does nothing if the buffer is modified. + +\(fn BUF)" nil nil) + +(autoload 'view-file "view" "\ +View FILE in View mode, returning to previous buffer when done. +Emacs commands editing the buffer contents are not available; instead, a +special set of commands (mostly letters and punctuation) are defined for +moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +\(fn FILE)" t nil) + +(autoload 'view-file-other-window "view" "\ +View FILE in View mode in another window. +When done, return that window to its previous buffer, and kill the +buffer visiting FILE if unmodified and if it wasn't visited before. + +Emacs commands editing the buffer contents are not available; instead, +a special set of commands (mostly letters and punctuation) +are defined for moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +\(fn FILE)" t nil) + +(autoload 'view-file-other-frame "view" "\ +View FILE in View mode in another frame. +When done, kill the buffer visiting FILE if unmodified and if it wasn't +visited before; also, maybe delete other frame and/or return to previous +buffer. + +Emacs commands editing the buffer contents are not available; instead, +a special set of commands (mostly letters and punctuation) +are defined for moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +\(fn FILE)" t nil) + +(autoload 'view-buffer "view" "\ +View BUFFER in View mode, returning to previous buffer when done. +Emacs commands editing the buffer contents are not available; instead, a +special set of commands (mostly letters and punctuation) are defined for +moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +Optional argument EXIT-ACTION is either nil or a function with buffer as +argument. This function is called when finished viewing buffer. Use +this argument instead of explicitly setting `view-exit-action'. + +Do not set EXIT-ACTION to `kill-buffer' when BUFFER visits a +file: Users may suspend viewing in order to modify the buffer. +Exiting View mode will then discard the user's edits. Setting +EXIT-ACTION to `kill-buffer-if-not-modified' avoids this. + +\(fn BUFFER &optional EXIT-ACTION)" t nil) + +(autoload 'view-buffer-other-window "view" "\ +View BUFFER in View mode in another window. +Return to previous buffer when done, unless optional NOT-RETURN is +non-nil. Emacs commands editing the buffer contents are not available; +instead, a special set of commands (mostly letters and punctuation) are +defined for moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +Optional argument EXIT-ACTION is either nil or a function with buffer as +argument. This function is called when finished viewing buffer. Use +this argument instead of explicitly setting `view-exit-action'. + +\(fn BUFFER &optional NOT-RETURN EXIT-ACTION)" t nil) + +(autoload 'view-buffer-other-frame "view" "\ +View BUFFER in View mode in another frame. +Return to previous buffer when done, unless optional NOT-RETURN is +non-nil. Emacs commands editing the buffer contents are not available; +instead, a special set of commands (mostly letters and punctuation) are +defined for moving around in the buffer. +Space scrolls forward, Delete scrolls backward. +For a list of all View commands, type H or h while viewing. + +This command runs the normal hook `view-mode-hook'. + +Optional argument EXIT-ACTION is either nil or a function with buffer as +argument. This function is called when finished viewing buffer. Use +this argument instead of explicitly setting `view-exit-action'. + +\(fn BUFFER &optional NOT-RETURN EXIT-ACTION)" t nil) + +(autoload 'view-mode "view" "\ +Toggle View mode, a minor mode for viewing text but not editing it. +With prefix argument ARG, turn View mode on if ARG is positive, otherwise +turn it off. + +Emacs commands that do not change the buffer contents are available as usual. +Kill commands insert text in kill buffers but do not delete. Other commands +\(among them most letters and punctuation) beep and tell that the buffer is +read-only. +\\ +The following additional commands are provided. Most commands take prefix +arguments. Page commands default to \"page size\" lines which is almost a whole +window full, or number of lines set by \\[View-scroll-page-forward-set-page-size] or \\[View-scroll-page-backward-set-page-size]. Half page commands default to +and set \"half page size\" lines which initially is half a window full. Search +commands default to a repeat count of one. + +H, h, ? This message. +Digits provide prefix arguments. +\\[negative-argument] negative prefix argument. +\\[beginning-of-buffer] move to the beginning of buffer. +> move to the end of buffer. +\\[View-scroll-to-buffer-end] scroll so that buffer end is at last line of window. +SPC scroll forward \"page size\" lines. + With prefix scroll forward prefix lines. +DEL scroll backward \"page size\" lines. + With prefix scroll backward prefix lines. +\\[View-scroll-page-forward-set-page-size] like \\[View-scroll-page-forward] but with prefix sets \"page size\" to prefix. +\\[View-scroll-page-backward-set-page-size] like \\[View-scroll-page-backward] but with prefix sets \"page size\" to prefix. +\\[View-scroll-half-page-forward] scroll forward \"half page size\" lines. With prefix, sets + \"half page size\" to prefix lines and scrolls forward that much. +\\[View-scroll-half-page-backward] scroll backward \"half page size\" lines. With prefix, sets + \"half page size\" to prefix lines and scrolls backward that much. +RET, LFD scroll forward one line. With prefix scroll forward prefix line(s). +y scroll backward one line. With prefix scroll backward prefix line(s). +\\[View-revert-buffer-scroll-page-forward] revert-buffer if necessary and scroll forward. + Use this to view a changing file. +\\[what-line] prints the current line number. +\\[View-goto-percent] goes prefix argument (default 100) percent into buffer. +\\[View-goto-line] goes to line given by prefix argument (default first line). +. set the mark. +x exchanges point and mark. +\\[View-back-to-mark] return to mark and pops mark ring. + Mark ring is pushed at start of every successful search and when + jump to line occurs. The mark is set on jump to buffer start or end. +\\[point-to-register] save current position in character register. +' go to position saved in character register. +s do forward incremental search. +r do reverse incremental search. +\\[View-search-regexp-forward] searches forward for regular expression, starting after current page. + ! and @ have a special meaning at the beginning of the regexp. + ! means search for a line with no match for regexp. @ means start + search at beginning (end for backward search) of buffer. +\\ searches backward for regular expression, starting before current page. +\\[View-search-last-regexp-forward] searches forward for last regular expression. +p searches backward for last regular expression. +\\[View-quit] quit View mode, restoring this window and buffer to previous state. + \\[View-quit] is the normal way to leave view mode. +\\[View-exit] exit View mode but stay in current buffer. Use this if you started + viewing a buffer (file) and find out you want to edit it. + This command restores the previous read-only status of the buffer. +\\[View-exit-and-edit] exit View mode, and make the current buffer editable + even if it was not editable before entry to View mode. +\\[View-quit-all] quit View mode, restoring all windows to previous state. +\\[View-leave] quit View mode and maybe switch buffers, but don't kill this buffer. +\\[View-kill-and-leave] quit View mode, kill current buffer and go back to other buffer. + +The effect of \\[View-leave], \\[View-quit] and \\[View-kill-and-leave] depends on how view-mode was entered. If it was +entered by view-file, view-file-other-window, view-file-other-frame, or +\\[dired-view-file] (\\[view-file], \\[view-file-other-window], +\\[view-file-other-frame], or the Dired mode v command), +then \\[View-quit] will try to kill the current buffer. +If view-mode was entered from another buffer, by \\[view-buffer], +\\[view-buffer-other-window], \\[view-buffer-other frame], \\[view-file], +\\[view-file-other-window], or \\[view-file-other-frame], +then \\[View-leave], \\[View-quit] and \\[View-kill-and-leave] will return to that buffer. + +Entry to view-mode runs the normal hook `view-mode-hook'. + +\(fn &optional ARG)" t nil) + +(autoload 'view-return-to-alist-update "view" "\ +Update `view-return-to-alist' of buffer BUFFER. +Remove from `view-return-to-alist' all entries referencing dead +windows. Optional argument ITEM non-nil means add ITEM to +`view-return-to-alist' after purging. For a decsription of items +that can be added see the RETURN-TO-ALIST argument of the +function `view-mode-exit'. If `view-return-to-alist' contains an +entry for the selected window, purge that entry from +`view-return-to-alist' before adding ITEM. + +\(fn BUFFER &optional ITEM)" nil nil) + +(autoload 'view-mode-enter "view" "\ +Enter View mode and set up exit from view mode depending on optional arguments. +RETURN-TO non-nil means add RETURN-TO as an element to the buffer +local alist `view-return-to-alist'. Save EXIT-ACTION in buffer +local variable `view-exit-action'. It should be either nil or a +function that takes a buffer as argument. This function will be +called by `view-mode-exit'. + +RETURN-TO is either nil, meaning do nothing when exiting view +mode, or must have the format (WINDOW OLD-WINDOW . OLD-BUF-INFO). +WINDOW is the window used for viewing. OLD-WINDOW is nil or the +window to select after viewing. OLD-BUF-INFO tells what to do +with WINDOW when exiting. It is one of: +1) nil Do nothing. +2) t Delete WINDOW or, if it is the only window and + `view-remove-frame-by-deleting' is non-nil, its + frame. +3) (OLD-BUFF START POINT) Display buffer OLD-BUFF with displayed text + starting at START and point at POINT in WINDOW. +4) quit-window Do `quit-window' in WINDOW. +5) keep-frame Like case 2) but do not delete the frame. + +For a list of all View commands, type H or h while viewing. + +This function runs the normal hook `view-mode-hook'. + +\(fn &optional RETURN-TO EXIT-ACTION)" nil nil) + +(autoload 'View-exit-and-edit "view" "\ +Exit View mode and make the current buffer editable. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (vip-mode vip-setup) "vip" "emulation/vip.el" (19005 +;;;;;; 47390)) +;;; Generated autoloads from emulation/vip.el + +(autoload 'vip-setup "vip" "\ +Set up bindings for C-x 7 and C-z that are useful for VIP users. + +\(fn)" nil nil) + +(autoload 'vip-mode "vip" "\ +Turn on VIP emulation of VI. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (viper-mode toggle-viper-mode) "viper" "emulation/viper.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emulation/viper.el + +(autoload 'toggle-viper-mode "viper" "\ +Toggle Viper on/off. +If Viper is enabled, turn it off. Otherwise, turn it on. + +\(fn)" t nil) + +(autoload 'viper-mode "viper" "\ +Turn on Viper emulation of Vi in Emacs. See Info node `(viper)Top'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (warn lwarn display-warning) "warnings" "emacs-lisp/warnings.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emacs-lisp/warnings.el + +(defvar warning-prefix-function nil "\ +Function to generate warning prefixes. +This function, if non-nil, is called with two arguments, +the severity level and its entry in `warning-levels', +and should return the entry that should actually be used. +The warnings buffer is current when this function is called +and the function can insert text in it. This text becomes +the beginning of the warning.") + +(defvar warning-series nil "\ +Non-nil means treat multiple `display-warning' calls as a series. +A marker indicates a position in the warnings buffer +which is the start of the current series; it means that +additional warnings in the same buffer should not move point. +t means the next warning begins a series (and stores a marker here). +A symbol with a function definition is like t, except +also call that function before the next warning.") + +(defvar warning-fill-prefix nil "\ +Non-nil means fill each warning text using this string as `fill-prefix'.") + +(defvar warning-type-format " (%s)" "\ +Format for displaying the warning type in the warning message. +The result of formatting the type this way gets included in the +message under the control of the string in `warning-levels'.") + +(autoload 'display-warning "warnings" "\ +Display a warning message, MESSAGE. +TYPE is the warning type: either a custom group name (a symbol), +or a list of symbols whose first element is a custom group name. +\(The rest of the symbols represent subcategories, for warning purposes +only, and you can use whatever symbols you like.) + +LEVEL should be either :debug, :warning, :error, or :emergency +\(but see `warning-minimum-level' and `warning-minimum-log-level'). +Default is :warning. + +:emergency -- a problem that will seriously impair Emacs operation soon + if you do not attend to it promptly. +:error -- data or circumstances that are inherently wrong. +:warning -- data or circumstances that are not inherently wrong, + but raise suspicion of a possible problem. +:debug -- info for debugging only. + +BUFFER-NAME, if specified, is the name of the buffer for logging +the warning. By default, it is `*Warnings*'. If this function +has to create the buffer, it disables undo in the buffer. + +See the `warnings' custom group for user customization features. + +See also `warning-series', `warning-prefix-function' and +`warning-fill-prefix' for additional programming features. + +\(fn TYPE MESSAGE &optional LEVEL BUFFER-NAME)" nil nil) + +(autoload 'lwarn "warnings" "\ +Display a warning message made from (format MESSAGE ARGS...). +Aside from generating the message with `format', +this is equivalent to `display-warning'. + +TYPE is the warning type: either a custom group name (a symbol), +or a list of symbols whose first element is a custom group name. +\(The rest of the symbols represent subcategories and +can be whatever you like.) + +LEVEL should be either :debug, :warning, :error, or :emergency +\(but see `warning-minimum-level' and `warning-minimum-log-level'). + +:emergency -- a problem that will seriously impair Emacs operation soon + if you do not attend to it promptly. +:error -- invalid data or circumstances. +:warning -- suspicious data or circumstances. +:debug -- info for debugging only. + +\(fn TYPE LEVEL MESSAGE &rest ARGS)" nil nil) + +(autoload 'warn "warnings" "\ +Display a warning message made from (format MESSAGE ARGS...). +Aside from generating the message with `format', +this is equivalent to `display-warning', using +`emacs' as the type and `:warning' as the level. + +\(fn MESSAGE &rest ARGS)" nil nil) + +;;;*** + +;;;### (autoloads (wdired-change-to-wdired-mode) "wdired" "wdired.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from wdired.el + +(autoload 'wdired-change-to-wdired-mode "wdired" "\ +Put a dired buffer in a mode in which filenames are editable. +\\ +This mode allows the user to change the names of the files, and after +typing \\[wdired-finish-edit] Emacs renames the files and directories +in disk. + +See `wdired-mode'. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (webjump) "webjump" "net/webjump.el" (19005 47402)) +;;; Generated autoloads from net/webjump.el + +(autoload 'webjump "webjump" "\ +Jumps to a Web site from a programmable hotlist. + +See the documentation for the `webjump-sites' variable for how to customize the +hotlist. + +Please submit bug reports and other feedback to the author, Neil W. Van Dyke +. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (which-function-mode) "which-func" "progmodes/which-func.el" +;;;;;; (19005 47405)) +;;; Generated autoloads from progmodes/which-func.el + (put 'which-func-format 'risky-local-variable t) + (put 'which-func-current 'risky-local-variable t) + +(defalias 'which-func-mode 'which-function-mode) + +(defvar which-function-mode nil "\ +Non-nil if Which-Function mode is enabled. +See the command `which-function-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `which-function-mode'.") + +(custom-autoload 'which-function-mode "which-func" nil) + +(autoload 'which-function-mode "which-func" "\ +Toggle Which Function mode, globally. +When Which Function mode is enabled, the current function name is +continuously displayed in the mode line, in certain major modes. + +With prefix ARG, turn Which Function mode on if arg is positive, +and off otherwise. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (whitespace-report-region whitespace-report whitespace-cleanup-region +;;;;;; whitespace-cleanup global-whitespace-toggle-options whitespace-toggle-options +;;;;;; global-whitespace-newline-mode global-whitespace-mode whitespace-newline-mode +;;;;;; whitespace-mode) "whitespace" "whitespace.el" (19005 47387)) +;;; Generated autoloads from whitespace.el + +(autoload 'whitespace-mode "whitespace" "\ +Toggle whitespace minor mode visualization (\"ws\" on modeline). + +If ARG is null, toggle whitespace visualization. +If ARG is a number greater than zero, turn on visualization; +otherwise, turn off visualization. +Only useful with a windowing system. + +See also `whitespace-style', `whitespace-newline' and +`whitespace-display-mappings'. + +\(fn &optional ARG)" t nil) + +(autoload 'whitespace-newline-mode "whitespace" "\ +Toggle NEWLINE minor mode visualization (\"nl\" on modeline). + +If ARG is null, toggle NEWLINE visualization. +If ARG is a number greater than zero, turn on visualization; +otherwise, turn off visualization. +Only useful with a windowing system. + +Use `whitespace-newline-mode' only for NEWLINE visualization +exclusively. For other visualizations, including NEWLINE +visualization together with (HARD) SPACEs and/or TABs, please, +use `whitespace-mode'. + +See also `whitespace-newline' and `whitespace-display-mappings'. + +\(fn &optional ARG)" t nil) + +(defvar global-whitespace-mode nil "\ +Non-nil if Global-Whitespace mode is enabled. +See the command `global-whitespace-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `global-whitespace-mode'.") + +(custom-autoload 'global-whitespace-mode "whitespace" nil) + +(autoload 'global-whitespace-mode "whitespace" "\ +Toggle whitespace global minor mode visualization (\"WS\" on modeline). + +If ARG is null, toggle whitespace visualization. +If ARG is a number greater than zero, turn on visualization; +otherwise, turn off visualization. +Only useful with a windowing system. + +See also `whitespace-style', `whitespace-newline' and +`whitespace-display-mappings'. + +\(fn &optional ARG)" t nil) + +(defvar global-whitespace-newline-mode nil "\ +Non-nil if Global-Whitespace-Newline mode is enabled. +See the command `global-whitespace-newline-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `global-whitespace-newline-mode'.") + +(custom-autoload 'global-whitespace-newline-mode "whitespace" nil) + +(autoload 'global-whitespace-newline-mode "whitespace" "\ +Toggle NEWLINE global minor mode visualization (\"NL\" on modeline). + +If ARG is null, toggle NEWLINE visualization. +If ARG is a number greater than zero, turn on visualization; +otherwise, turn off visualization. +Only useful with a windowing system. + +Use `global-whitespace-newline-mode' only for NEWLINE +visualization exclusively. For other visualizations, including +NEWLINE visualization together with (HARD) SPACEs and/or TABs, +please, use `global-whitespace-mode'. + +See also `whitespace-newline' and `whitespace-display-mappings'. + +\(fn &optional ARG)" t nil) + +(autoload 'whitespace-toggle-options "whitespace" "\ +Toggle local `whitespace-mode' options. + +If local whitespace-mode is off, toggle the option given by ARG +and turn on local whitespace-mode. + +If local whitespace-mode is on, toggle the option given by ARG +and restart local whitespace-mode. + +Interactively, it reads one of the following chars: + + CHAR MEANING + (VIA FACES) + t toggle TAB visualization + s toggle SPACE and HARD SPACE visualization + r toggle trailing blanks visualization + l toggle \"long lines\" visualization + L toggle \"long lines\" tail visualization + n toggle NEWLINE visualization + e toggle empty line at bob and/or eob visualization + C-i toggle indentation SPACEs visualization (via `indent-tabs-mode') + I toggle indentation SPACEs visualization + i toggle indentation TABs visualization + C-a toggle SPACEs after TAB visualization (via `indent-tabs-mode') + A toggle SPACEs after TAB: SPACEs visualization + a toggle SPACEs after TAB: TABs visualization + C-b toggle SPACEs before TAB visualization (via `indent-tabs-mode') + B toggle SPACEs before TAB: SPACEs visualization + b toggle SPACEs before TAB: TABs visualization + + (VIA DISPLAY TABLE) + T toggle TAB visualization + S toggle SPACEs before TAB visualization + N toggle NEWLINE visualization + + x restore `whitespace-style' value + ? display brief help + +Non-interactively, ARG should be a symbol or a list of symbols. +The valid symbols are: + + tabs toggle TAB visualization + spaces toggle SPACE and HARD SPACE visualization + trailing toggle trailing blanks visualization + lines toggle \"long lines\" visualization + lines-tail toggle \"long lines\" tail visualization + newline toggle NEWLINE visualization + empty toggle empty line at bob and/or eob visualization + indentation toggle indentation SPACEs visualization + indentation::tab toggle indentation SPACEs visualization + indentation::space toggle indentation TABs visualization + space-after-tab toggle SPACEs after TAB visualization + space-after-tab::tab toggle SPACEs after TAB: SPACEs visualization + space-after-tab::space toggle SPACEs after TAB: TABs visualization + space-before-tab toggle SPACEs before TAB visualization + space-before-tab::tab toggle SPACEs before TAB: SPACEs visualization + space-before-tab::space toggle SPACEs before TAB: TABs visualization + + tab-mark toggle TAB visualization + space-mark toggle SPACEs before TAB visualization + newline-mark toggle NEWLINE visualization + + whitespace-style restore `whitespace-style' value + +Only useful with a windowing system. + +See `whitespace-style' and `indent-tabs-mode' for documentation. + +\(fn ARG)" t nil) + +(autoload 'global-whitespace-toggle-options "whitespace" "\ +Toggle global `whitespace-mode' options. + +If global whitespace-mode is off, toggle the option given by ARG +and turn on global whitespace-mode. + +If global whitespace-mode is on, toggle the option given by ARG +and restart global whitespace-mode. + +Interactively, it accepts one of the following chars: + + CHAR MEANING + (VIA FACES) + t toggle TAB visualization + s toggle SPACE and HARD SPACE visualization + r toggle trailing blanks visualization + l toggle \"long lines\" visualization + L toggle \"long lines\" tail visualization + n toggle NEWLINE visualization + e toggle empty line at bob and/or eob visualization + C-i toggle indentation SPACEs visualization (via `indent-tabs-mode') + I toggle indentation SPACEs visualization + i toggle indentation TABs visualization + C-a toggle SPACEs after TAB visualization (via `indent-tabs-mode') + A toggle SPACEs after TAB: SPACEs visualization + a toggle SPACEs after TAB: TABs visualization + C-b toggle SPACEs before TAB visualization (via `indent-tabs-mode') + B toggle SPACEs before TAB: SPACEs visualization + b toggle SPACEs before TAB: TABs visualization + + (VIA DISPLAY TABLE) + T toggle TAB visualization + S toggle SPACEs before TAB visualization + N toggle NEWLINE visualization + + x restore `whitespace-style' value + ? display brief help + +Non-interactively, ARG should be a symbol or a list of symbols. +The valid symbols are: + + tabs toggle TAB visualization + spaces toggle SPACE and HARD SPACE visualization + trailing toggle trailing blanks visualization + lines toggle \"long lines\" visualization + lines-tail toggle \"long lines\" tail visualization + newline toggle NEWLINE visualization + empty toggle empty line at bob and/or eob visualization + indentation toggle indentation SPACEs visualization + indentation::tab toggle indentation SPACEs visualization + indentation::space toggle indentation TABs visualization + space-after-tab toggle SPACEs after TAB visualization + space-after-tab::tab toggle SPACEs after TAB: SPACEs visualization + space-after-tab::space toggle SPACEs after TAB: TABs visualization + space-before-tab toggle SPACEs before TAB visualization + space-before-tab::tab toggle SPACEs before TAB: SPACEs visualization + space-before-tab::space toggle SPACEs before TAB: TABs visualization + + tab-mark toggle TAB visualization + space-mark toggle SPACEs before TAB visualization + newline-mark toggle NEWLINE visualization + + whitespace-style restore `whitespace-style' value + +Only useful with a windowing system. + +See `whitespace-style' and `indent-tabs-mode' for documentation. + +\(fn ARG)" t nil) + +(autoload 'whitespace-cleanup "whitespace" "\ +Cleanup some blank problems in all buffer or at region. + +It usually applies to the whole buffer, but in transient mark +mode when the mark is active, it applies to the region. It also +applies to the region when it is not in transient mark mode, the +mark is active and \\[universal-argument] was pressed just before +calling `whitespace-cleanup' interactively. + +See also `whitespace-cleanup-region'. + +The problems cleaned up are: + +1. empty lines at beginning of buffer. +2. empty lines at end of buffer. + If `whitespace-style' includes the value `empty', remove all + empty lines at beginning and/or end of buffer. + +3. 8 or more SPACEs at beginning of line. + If `whitespace-style' includes the value `indentation': + replace 8 or more SPACEs at beginning of line by TABs, if + `indent-tabs-mode' is non-nil; otherwise, replace TABs by + SPACEs. + If `whitespace-style' includes the value `indentation::tab', + replace 8 or more SPACEs at beginning of line by TABs. + If `whitespace-style' includes the value `indentation::space', + replace TABs by SPACEs. + +4. SPACEs before TAB. + If `whitespace-style' includes the value `space-before-tab': + replace SPACEs by TABs, if `indent-tabs-mode' is non-nil; + otherwise, replace TABs by SPACEs. + If `whitespace-style' includes the value + `space-before-tab::tab', replace SPACEs by TABs. + If `whitespace-style' includes the value + `space-before-tab::space', replace TABs by SPACEs. + +5. SPACEs or TABs at end of line. + If `whitespace-style' includes the value `trailing', remove + all SPACEs or TABs at end of line. + +6. 8 or more SPACEs after TAB. + If `whitespace-style' includes the value `space-after-tab': + replace SPACEs by TABs, if `indent-tabs-mode' is non-nil; + otherwise, replace TABs by SPACEs. + If `whitespace-style' includes the value + `space-after-tab::tab', replace SPACEs by TABs. + If `whitespace-style' includes the value + `space-after-tab::space', replace TABs by SPACEs. + +See `whitespace-style', `indent-tabs-mode' and `tab-width' for +documentation. + +\(fn)" t nil) + +(autoload 'whitespace-cleanup-region "whitespace" "\ +Cleanup some blank problems at region. + +The problems cleaned up are: + +1. 8 or more SPACEs at beginning of line. + If `whitespace-style' includes the value `indentation': + replace 8 or more SPACEs at beginning of line by TABs, if + `indent-tabs-mode' is non-nil; otherwise, replace TABs by + SPACEs. + If `whitespace-style' includes the value `indentation::tab', + replace 8 or more SPACEs at beginning of line by TABs. + If `whitespace-style' includes the value `indentation::space', + replace TABs by SPACEs. + +2. SPACEs before TAB. + If `whitespace-style' includes the value `space-before-tab': + replace SPACEs by TABs, if `indent-tabs-mode' is non-nil; + otherwise, replace TABs by SPACEs. + If `whitespace-style' includes the value + `space-before-tab::tab', replace SPACEs by TABs. + If `whitespace-style' includes the value + `space-before-tab::space', replace TABs by SPACEs. + +3. SPACEs or TABs at end of line. + If `whitespace-style' includes the value `trailing', remove + all SPACEs or TABs at end of line. + +4. 8 or more SPACEs after TAB. + If `whitespace-style' includes the value `space-after-tab': + replace SPACEs by TABs, if `indent-tabs-mode' is non-nil; + otherwise, replace TABs by SPACEs. + If `whitespace-style' includes the value + `space-after-tab::tab', replace SPACEs by TABs. + If `whitespace-style' includes the value + `space-after-tab::space', replace TABs by SPACEs. + +See `whitespace-style', `indent-tabs-mode' and `tab-width' for +documentation. + +\(fn START END)" t nil) + +(autoload 'whitespace-report "whitespace" "\ +Report some whitespace problems in buffer. + +Return nil if there is no whitespace problem; otherwise, return +non-nil. + +If FORCE is non-nil or \\[universal-argument] was pressed just +before calling `whitespace-report' interactively, it forces +`whitespace-style' to have: + + empty + trailing + indentation + space-before-tab + space-after-tab + +If REPORT-IF-BOGUS is non-nil, it reports only when there are any +whitespace problems in buffer. + +Report if some of the following whitespace problems exist: + +* If `indent-tabs-mode' is non-nil: + empty 1. empty lines at beginning of buffer. + empty 2. empty lines at end of buffer. + trailing 3. SPACEs or TABs at end of line. + indentation 4. 8 or more SPACEs at beginning of line. + space-before-tab 5. SPACEs before TAB. + space-after-tab 6. 8 or more SPACEs after TAB. + +* If `indent-tabs-mode' is nil: + empty 1. empty lines at beginning of buffer. + empty 2. empty lines at end of buffer. + trailing 3. SPACEs or TABs at end of line. + indentation 4. TABS at beginning of line. + space-before-tab 5. SPACEs before TAB. + space-after-tab 6. 8 or more SPACEs after TAB. + +See `whitespace-style' for documentation. +See also `whitespace-cleanup' and `whitespace-cleanup-region' for +cleaning up these problems. + +\(fn &optional FORCE REPORT-IF-BOGUS)" t nil) + +(autoload 'whitespace-report-region "whitespace" "\ +Report some whitespace problems in a region. + +Return nil if there is no whitespace problem; otherwise, return +non-nil. + +If FORCE is non-nil or \\[universal-argument] was pressed just +before calling `whitespace-report-region' interactively, it +forces `whitespace-style' to have: + + empty + indentation + space-before-tab + trailing + space-after-tab + +If REPORT-IF-BOGUS is non-nil, it reports only when there are any +whitespace problems in buffer. + +Report if some of the following whitespace problems exist: + +* If `indent-tabs-mode' is non-nil: + empty 1. empty lines at beginning of buffer. + empty 2. empty lines at end of buffer. + trailing 3. SPACEs or TABs at end of line. + indentation 4. 8 or more SPACEs at beginning of line. + space-before-tab 5. SPACEs before TAB. + space-after-tab 6. 8 or more SPACEs after TAB. + +* If `indent-tabs-mode' is nil: + empty 1. empty lines at beginning of buffer. + empty 2. empty lines at end of buffer. + trailing 3. SPACEs or TABs at end of line. + indentation 4. TABS at beginning of line. + space-before-tab 5. SPACEs before TAB. + space-after-tab 6. 8 or more SPACEs after TAB. + +See `whitespace-style' for documentation. +See also `whitespace-cleanup' and `whitespace-cleanup-region' for +cleaning up these problems. + +\(fn START END &optional FORCE REPORT-IF-BOGUS)" t nil) + +;;;*** + +;;;### (autoloads (widget-minor-mode widget-browse-other-window widget-browse +;;;;;; widget-browse-at) "wid-browse" "wid-browse.el" (19005 47387)) +;;; Generated autoloads from wid-browse.el + +(autoload 'widget-browse-at "wid-browse" "\ +Browse the widget under point. + +\(fn POS)" t nil) + +(autoload 'widget-browse "wid-browse" "\ +Create a widget browser for WIDGET. + +\(fn WIDGET)" t nil) + +(autoload 'widget-browse-other-window "wid-browse" "\ +Show widget browser for WIDGET in other window. + +\(fn &optional WIDGET)" t nil) + +(autoload 'widget-minor-mode "wid-browse" "\ +Togle minor mode for traversing widgets. +With arg, turn widget mode on if and only if arg is positive. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (widget-setup widget-insert widget-delete widget-create +;;;;;; widget-prompt-value widgetp) "wid-edit" "wid-edit.el" (19005 +;;;;;; 47387)) +;;; Generated autoloads from wid-edit.el + +(autoload 'widgetp "wid-edit" "\ +Return non-nil if WIDGET is a widget. + +\(fn WIDGET)" nil nil) + +(autoload 'widget-prompt-value "wid-edit" "\ +Prompt for a value matching WIDGET, using PROMPT. +The current value is assumed to be VALUE, unless UNBOUND is non-nil. + +\(fn WIDGET PROMPT &optional VALUE UNBOUND)" nil nil) + +(autoload 'widget-create "wid-edit" "\ +Create widget of TYPE. +The optional ARGS are additional keyword arguments. + +\(fn TYPE &rest ARGS)" nil nil) + +(autoload 'widget-delete "wid-edit" "\ +Delete WIDGET. + +\(fn WIDGET)" nil nil) + +(autoload 'widget-insert "wid-edit" "\ +Call `insert' with ARGS even if surrounding text is read only. + +\(fn &rest ARGS)" nil nil) + +(defvar widget-keymap (let ((map (make-sparse-keymap))) (define-key map " " 'widget-forward) (define-key map " " 'widget-backward) (define-key map [(shift tab)] 'advertised-widget-backward) (define-key map [backtab] 'widget-backward) (define-key map [down-mouse-2] 'widget-button-click) (define-key map [down-mouse-1] 'widget-button-click) (define-key map [(control 109)] 'widget-button-press) map) "\ +Keymap containing useful binding for buffers containing widgets. +Recommended as a parent keymap for modes using widgets.") + +(autoload 'widget-setup "wid-edit" "\ +Setup current buffer so editing string widgets works. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (windmove-default-keybindings windmove-down windmove-right +;;;;;; windmove-up windmove-left) "windmove" "windmove.el" (19005 +;;;;;; 47387)) +;;; Generated autoloads from windmove.el + +(autoload 'windmove-left "windmove" "\ +Select the window to the left of the current one. +With no prefix argument, or with prefix argument equal to zero, +\"left\" is relative to the position of point in the window; otherwise +it is relative to the top edge (for positive ARG) or the bottom edge +\(for negative ARG) of the current window. +If no window is at the desired location, an error is signaled. + +\(fn &optional ARG)" t nil) + +(autoload 'windmove-up "windmove" "\ +Select the window above the current one. +With no prefix argument, or with prefix argument equal to zero, \"up\" +is relative to the position of point in the window; otherwise it is +relative to the left edge (for positive ARG) or the right edge (for +negative ARG) of the current window. +If no window is at the desired location, an error is signaled. + +\(fn &optional ARG)" t nil) + +(autoload 'windmove-right "windmove" "\ +Select the window to the right of the current one. +With no prefix argument, or with prefix argument equal to zero, +\"right\" is relative to the position of point in the window; +otherwise it is relative to the top edge (for positive ARG) or the +bottom edge (for negative ARG) of the current window. +If no window is at the desired location, an error is signaled. + +\(fn &optional ARG)" t nil) + +(autoload 'windmove-down "windmove" "\ +Select the window below the current one. +With no prefix argument, or with prefix argument equal to zero, +\"down\" is relative to the position of point in the window; otherwise +it is relative to the left edge (for positive ARG) or the right edge +\(for negative ARG) of the current window. +If no window is at the desired location, an error is signaled. + +\(fn &optional ARG)" t nil) + +(autoload 'windmove-default-keybindings "windmove" "\ +Set up keybindings for `windmove'. +Keybindings are of the form MODIFIER-{left,right,up,down}. +Default MODIFIER is 'shift. + +\(fn &optional MODIFIER)" t nil) + +;;;*** + +;;;### (autoloads (winner-mode winner-mode) "winner" "winner.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from winner.el + +(defvar winner-mode nil "\ +Toggle Winner mode. +Setting this variable directly does not take effect; +use either \\[customize] or the function `winner-mode'.") + +(custom-autoload 'winner-mode "winner" nil) + +(autoload 'winner-mode "winner" "\ +Toggle Winner mode. +With arg, turn Winner mode on if and only if arg is positive. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (woman-find-file woman-dired-find-file woman woman-locale) +;;;;;; "woman" "woman.el" (19005 47387)) +;;; Generated autoloads from woman.el + +(defvar woman-locale nil "\ +String specifying a manual page locale, or nil. +If a manual page is available in the specified locale +\(e.g. \"sv_SE.ISO8859-1\"), it will be offered in preference to the +default version. Normally, `set-locale-environment' sets this at startup.") + +(custom-autoload 'woman-locale "woman" t) + +(autoload 'woman "woman" "\ +Browse UN*X man page for TOPIC (Without using external Man program). +The major browsing mode used is essentially the standard Man mode. +Choose the filename for the man page using completion, based on the +topic selected from the directories specified in `woman-manpath' and +`woman-path'. The directory expansions and topics are cached for +speed, but a non-nil interactive argument forces the caches to be +updated (e.g. to re-interpret the current directory). + +Used non-interactively, arguments are optional: if given then TOPIC +should be a topic string and non-nil RE-CACHE forces re-caching. + +\(fn &optional TOPIC RE-CACHE)" t nil) + +(autoload 'woman-dired-find-file "woman" "\ +In dired, run the WoMan man-page browser on this file. + +\(fn)" t nil) + +(autoload 'woman-find-file "woman" "\ +Find, decode and browse a specific UN*X man-page source file FILE-NAME. +Use existing buffer if possible; reformat only if prefix arg given. +When called interactively, optional argument REFORMAT forces reformatting +of an existing WoMan buffer formatted earlier. +No external programs are used, except that `gunzip' will be used to +decompress the file if appropriate. See the documentation for the +`woman' command for further details. + +\(fn FILE-NAME &optional REFORMAT)" t nil) + +;;;*** + +;;;### (autoloads (wordstar-mode) "ws-mode" "emulation/ws-mode.el" +;;;;;; (19005 47390)) +;;; Generated autoloads from emulation/ws-mode.el + +(autoload 'wordstar-mode "ws-mode" "\ +Major mode with WordStar-like key bindings. + +BUGS: + - Help menus with WordStar commands (C-j just calls help-for-help) + are not implemented + - Options for search and replace + - Show markers (C-k h) is somewhat strange + - Search and replace (C-q a) is only available in forward direction + +No key bindings beginning with ESC are installed, they will work +Emacs-like. + +The key bindings are: + + C-a backward-word + C-b fill-paragraph + C-c scroll-up-line + C-d forward-char + C-e previous-line + C-f forward-word + C-g delete-char + C-h backward-char + C-i indent-for-tab-command + C-j help-for-help + C-k ordstar-C-k-map + C-l ws-repeat-search + C-n open-line + C-p quoted-insert + C-r scroll-down-line + C-s backward-char + C-t kill-word + C-u keyboard-quit + C-v overwrite-mode + C-w scroll-down + C-x next-line + C-y kill-complete-line + C-z scroll-up + + C-k 0 ws-set-marker-0 + C-k 1 ws-set-marker-1 + C-k 2 ws-set-marker-2 + C-k 3 ws-set-marker-3 + C-k 4 ws-set-marker-4 + C-k 5 ws-set-marker-5 + C-k 6 ws-set-marker-6 + C-k 7 ws-set-marker-7 + C-k 8 ws-set-marker-8 + C-k 9 ws-set-marker-9 + C-k b ws-begin-block + C-k c ws-copy-block + C-k d save-buffers-kill-emacs + C-k f find-file + C-k h ws-show-markers + C-k i ws-indent-block + C-k k ws-end-block + C-k p ws-print-block + C-k q kill-emacs + C-k r insert-file + C-k s save-some-buffers + C-k t ws-mark-word + C-k u ws-exdent-block + C-k C-u keyboard-quit + C-k v ws-move-block + C-k w ws-write-block + C-k x kill-emacs + C-k y ws-delete-block + + C-o c wordstar-center-line + C-o b switch-to-buffer + C-o j justify-current-line + C-o k kill-buffer + C-o l list-buffers + C-o m auto-fill-mode + C-o r set-fill-column + C-o C-u keyboard-quit + C-o wd delete-other-windows + C-o wh split-window-horizontally + C-o wo other-window + C-o wv split-window-vertically + + C-q 0 ws-find-marker-0 + C-q 1 ws-find-marker-1 + C-q 2 ws-find-marker-2 + C-q 3 ws-find-marker-3 + C-q 4 ws-find-marker-4 + C-q 5 ws-find-marker-5 + C-q 6 ws-find-marker-6 + C-q 7 ws-find-marker-7 + C-q 8 ws-find-marker-8 + C-q 9 ws-find-marker-9 + C-q a ws-query-replace + C-q b ws-to-block-begin + C-q c end-of-buffer + C-q d end-of-line + C-q f ws-search + C-q k ws-to-block-end + C-q l ws-undo + C-q p ws-last-cursorp + C-q r beginning-of-buffer + C-q C-u keyboard-quit + C-q w ws-last-error + C-q y ws-kill-eol + C-q DEL ws-kill-bol + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (xesam-search) "xesam" "net/xesam.el" (18785 32010)) +;;; Generated autoloads from net/xesam.el + +(autoload 'xesam-search "xesam" "\ +Perform an interactive search. +ENGINE is the Xesam search engine to be applied, it must be one of the +entries of `xesam-search-engines'. QUERY is the search string in the +Xesam user query language. If the search engine does not support +the Xesam user query language, a Xesam fulltext search is applied. + +The default search engine is the first entry in `xesam-search-engines'. +Example: + + (xesam-search (car (xesam-search-engines)) \"emacs\") + +\(fn ENGINE QUERY)" t nil) + +;;;*** + +;;;### (autoloads (xml-parse-region xml-parse-file) "xml" "xml.el" +;;;;;; (19005 47387)) +;;; Generated autoloads from xml.el + +(autoload 'xml-parse-file "xml" "\ +Parse the well-formed XML file FILE. +If FILE is already visited, use its buffer and don't kill it. +Returns the top node with all its children. +If PARSE-DTD is non-nil, the DTD is parsed rather than skipped. +If PARSE-NS is non-nil, then QNAMES are expanded. + +\(fn FILE &optional PARSE-DTD PARSE-NS)" nil nil) + +(autoload 'xml-parse-region "xml" "\ +Parse the region from BEG to END in BUFFER. +If BUFFER is nil, it defaults to the current buffer. +Returns the XML list for the region, or raises an error if the region +is not well-formed XML. +If PARSE-DTD is non-nil, the DTD is parsed rather than skipped, +and returned as the first element of the list. +If PARSE-NS is non-nil, then QNAMES are expanded. + +\(fn BEG END &optional BUFFER PARSE-DTD PARSE-NS)" nil nil) + +;;;*** + +;;;### (autoloads (xmltok-get-declared-encoding-position) "xmltok" +;;;;;; "nxml/xmltok.el" (18785 32015)) +;;; Generated autoloads from nxml/xmltok.el + +(autoload 'xmltok-get-declared-encoding-position "xmltok" "\ +Return the position of the encoding in the XML declaration at point. +If there is a well-formed XML declaration starting at point and it +contains an encoding declaration, then return (START . END) +where START and END are the positions of the start and the end +of the encoding name; if there is no encoding declaration return +the position where and encoding declaration could be inserted. +If there is XML that is not well-formed that looks like an XML +declaration, return nil. Otherwise, return t. +If LIMIT is non-nil, then do not consider characters beyond LIMIT. + +\(fn &optional LIMIT)" nil nil) + +;;;*** + +;;;### (autoloads (xterm-mouse-mode) "xt-mouse" "xt-mouse.el" (19005 +;;;;;; 47387)) +;;; Generated autoloads from xt-mouse.el + +(defvar xterm-mouse-mode nil "\ +Non-nil if Xterm-Mouse mode is enabled. +See the command `xterm-mouse-mode' for a description of this minor mode. +Setting this variable directly does not take effect; +either customize it (see the info node `Easy Customization') +or call the function `xterm-mouse-mode'.") + +(custom-autoload 'xterm-mouse-mode "xt-mouse" nil) + +(autoload 'xterm-mouse-mode "xt-mouse" "\ +Toggle XTerm mouse mode. +With prefix arg, turn XTerm mouse mode on if arg is positive, otherwise turn +it off. + +Turn it on to use Emacs mouse commands, and off to use xterm mouse commands. +This works in terminal emulators compatible with xterm. It only +works for simple uses of the mouse. Basically, only non-modified +single clicks are supported. When turned on, the normal xterm +mouse functionality for such clicks is still available by holding +down the SHIFT key while pressing the mouse button. + +\(fn &optional ARG)" t nil) + +;;;*** + +;;;### (autoloads (yenc-extract-filename yenc-decode-region) "yenc" +;;;;;; "gnus/yenc.el" (19005 47394)) +;;; Generated autoloads from gnus/yenc.el + +(autoload 'yenc-decode-region "yenc" "\ +Yenc decode region between START and END using an internal decoder. + +\(fn START END)" t nil) + +(autoload 'yenc-extract-filename "yenc" "\ +Extract file name from an yenc header. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (psychoanalyze-pinhead apropos-zippy insert-zippyism +;;;;;; yow) "yow" "play/yow.el" (19005 47402)) +;;; Generated autoloads from play/yow.el + +(autoload 'yow "yow" "\ +Return or display a random Zippy quotation. With prefix arg, insert it. + +\(fn &optional INSERT DISPLAY)" t nil) + +(autoload 'insert-zippyism "yow" "\ +Prompt with completion for a known Zippy quotation, and insert it at point. + +\(fn &optional ZIPPYISM)" t nil) + +(autoload 'apropos-zippy "yow" "\ +Return a list of all Zippy quotes matching REGEXP. +If called interactively, display a list of matches. + +\(fn REGEXP)" t nil) + +(autoload 'psychoanalyze-pinhead "yow" "\ +Zippy goes to the analyst. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (zone) "zone" "play/zone.el" (19005 47402)) +;;; Generated autoloads from play/zone.el + +(autoload 'zone "zone" "\ +Zone out, completely. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads nil nil ("abbrev.el" "bindings.el" "buff-menu.el" +;;;;;; "button.el" "calc/calc-aent.el" "calc/calc-alg.el" "calc/calc-arith.el" +;;;;;; "calc/calc-bin.el" "calc/calc-comb.el" "calc/calc-cplx.el" +;;;;;; "calc/calc-embed.el" "calc/calc-ext.el" "calc/calc-fin.el" +;;;;;; "calc/calc-forms.el" "calc/calc-frac.el" "calc/calc-funcs.el" +;;;;;; "calc/calc-graph.el" "calc/calc-help.el" "calc/calc-incom.el" +;;;;;; "calc/calc-keypd.el" "calc/calc-lang.el" "calc/calc-macs.el" +;;;;;; "calc/calc-map.el" "calc/calc-math.el" "calc/calc-menu.el" +;;;;;; "calc/calc-misc.el" "calc/calc-mode.el" "calc/calc-mtx.el" +;;;;;; "calc/calc-nlfit.el" "calc/calc-poly.el" "calc/calc-prog.el" +;;;;;; "calc/calc-rewr.el" "calc/calc-rules.el" "calc/calc-sel.el" +;;;;;; "calc/calc-stat.el" "calc/calc-store.el" "calc/calc-stuff.el" +;;;;;; "calc/calc-trail.el" "calc/calc-undo.el" "calc/calc-units.el" +;;;;;; "calc/calc-vec.el" "calc/calc-yank.el" "calc/calcalg2.el" +;;;;;; "calc/calcalg3.el" "calc/calccomp.el" "calc/calcsel2.el" +;;;;;; "calendar/cal-bahai.el" "calendar/cal-coptic.el" "calendar/cal-french.el" +;;;;;; "calendar/cal-html.el" "calendar/cal-islam.el" "calendar/cal-iso.el" +;;;;;; "calendar/cal-julian.el" "calendar/cal-loaddefs.el" "calendar/cal-mayan.el" +;;;;;; "calendar/cal-menu.el" "calendar/cal-move.el" "calendar/cal-persia.el" +;;;;;; "calendar/cal-tex.el" "calendar/cal-x.el" "calendar/diary-loaddefs.el" +;;;;;; "calendar/hol-loaddefs.el" "case-table.el" "cdl.el" "cus-dep.el" +;;;;;; "cus-face.el" "cus-start.el" "custom.el" "dframe.el" "dos-fns.el" +;;;;;; "dos-vars.el" "dos-w32.el" "ediff-diff.el" "ediff-init.el" +;;;;;; "ediff-merg.el" "ediff-ptch.el" "ediff-vers.el" "ediff-wind.el" +;;;;;; "electric.el" "emacs-lisp/assoc.el" "emacs-lisp/authors.el" +;;;;;; "emacs-lisp/avl-tree.el" "emacs-lisp/backquote.el" "emacs-lisp/bindat.el" +;;;;;; "emacs-lisp/byte-opt.el" "emacs-lisp/byte-run.el" "emacs-lisp/cl-compat.el" +;;;;;; "emacs-lisp/cl-extra.el" "emacs-lisp/cl-loaddefs.el" "emacs-lisp/cl-macs.el" +;;;;;; "emacs-lisp/cl-seq.el" "emacs-lisp/cl-specs.el" "emacs-lisp/cust-print.el" +;;;;;; "emacs-lisp/find-gc.el" "emacs-lisp/float-sup.el" "emacs-lisp/gulp.el" +;;;;;; "emacs-lisp/levents.el" "emacs-lisp/lisp-mnt.el" "emacs-lisp/lisp-mode.el" +;;;;;; "emacs-lisp/lisp.el" "emacs-lisp/lmenu.el" "emacs-lisp/lucid.el" +;;;;;; "emacs-lisp/map-ynp.el" "emacs-lisp/regi.el" "emacs-lisp/sregex.el" +;;;;;; "emacs-lisp/syntax.el" "emacs-lisp/tcover-ses.el" "emacs-lisp/tcover-unsafep.el" +;;;;;; "emacs-lisp/timer.el" "emacs-lock.el" "emulation/cua-gmrk.el" +;;;;;; "emulation/cua-rect.el" "emulation/edt-lk201.el" "emulation/edt-mapper.el" +;;;;;; "emulation/edt-pc.el" "emulation/edt-vt100.el" "emulation/tpu-extras.el" +;;;;;; "emulation/viper-cmd.el" "emulation/viper-ex.el" "emulation/viper-init.el" +;;;;;; "emulation/viper-keym.el" "emulation/viper-macs.el" "emulation/viper-mous.el" +;;;;;; "emulation/viper-util.el" "env.el" "epa-hook.el" "erc/erc-backend.el" +;;;;;; "erc/erc-goodies.el" "erc/erc-ibuffer.el" "erc/erc-lang.el" +;;;;;; "eshell/em-alias.el" "eshell/em-banner.el" "eshell/em-basic.el" +;;;;;; "eshell/em-cmpl.el" "eshell/em-dirs.el" "eshell/em-glob.el" +;;;;;; "eshell/em-hist.el" "eshell/em-ls.el" "eshell/em-pred.el" +;;;;;; "eshell/em-prompt.el" "eshell/em-rebind.el" "eshell/em-script.el" +;;;;;; "eshell/em-smart.el" "eshell/em-term.el" "eshell/em-unix.el" +;;;;;; "eshell/em-xtra.el" "eshell/esh-arg.el" "eshell/esh-cmd.el" +;;;;;; "eshell/esh-ext.el" "eshell/esh-io.el" "eshell/esh-module.el" +;;;;;; "eshell/esh-opt.el" "eshell/esh-proc.el" "eshell/esh-util.el" +;;;;;; "eshell/esh-var.el" "ezimage.el" "facemenu.el" "faces.el" +;;;;;; "files.el" "foldout.el" "font-core.el" "font-lock.el" "format-spec.el" +;;;;;; "format.el" "forms-d2.el" "forms-pass.el" "frame.el" "fringe.el" +;;;;;; "generic-x.el" "gnus/auth-source.el" "gnus/compface.el" "gnus/gnus-async.el" +;;;;;; "gnus/gnus-bcklg.el" "gnus/gnus-cite.el" "gnus/gnus-cus.el" +;;;;;; "gnus/gnus-demon.el" "gnus/gnus-dup.el" "gnus/gnus-eform.el" +;;;;;; "gnus/gnus-ems.el" "gnus/gnus-int.el" "gnus/gnus-logic.el" +;;;;;; "gnus/gnus-mh.el" "gnus/gnus-salt.el" "gnus/gnus-score.el" +;;;;;; "gnus/gnus-setup.el" "gnus/gnus-srvr.el" "gnus/gnus-sum.el" +;;;;;; "gnus/gnus-topic.el" "gnus/gnus-undo.el" "gnus/gnus-util.el" +;;;;;; "gnus/gnus-uu.el" "gnus/gnus-vm.el" "gnus/ietf-drums.el" +;;;;;; "gnus/legacy-gnus-agent.el" "gnus/mail-parse.el" "gnus/mail-prsvr.el" +;;;;;; "gnus/mail-source.el" "gnus/mailcap.el" "gnus/messcompat.el" +;;;;;; "gnus/mm-bodies.el" "gnus/mm-decode.el" "gnus/mm-encode.el" +;;;;;; "gnus/mm-util.el" "gnus/mm-view.el" "gnus/mml-sec.el" "gnus/mml-smime.el" +;;;;;; "gnus/mml.el" "gnus/nnagent.el" "gnus/nnbabyl.el" "gnus/nndb.el" +;;;;;; "gnus/nndir.el" "gnus/nndraft.el" "gnus/nneething.el" "gnus/nngateway.el" +;;;;;; "gnus/nnheader.el" "gnus/nnimap.el" "gnus/nnir.el" "gnus/nnlistserv.el" +;;;;;; "gnus/nnmail.el" "gnus/nnmaildir.el" "gnus/nnmairix.el" "gnus/nnmbox.el" +;;;;;; "gnus/nnmh.el" "gnus/nnnil.el" "gnus/nnoo.el" "gnus/nnrss.el" +;;;;;; "gnus/nnslashdot.el" "gnus/nnspool.el" "gnus/nntp.el" "gnus/nnultimate.el" +;;;;;; "gnus/nnvirtual.el" "gnus/nnwarchive.el" "gnus/nnweb.el" +;;;;;; "gnus/nnwfm.el" "gnus/pop3.el" "gnus/rfc1843.el" "gnus/rfc2045.el" +;;;;;; "gnus/rfc2047.el" "gnus/rfc2104.el" "gnus/rfc2231.el" "gnus/sieve-manage.el" +;;;;;; "gnus/smime.el" "gnus/spam-stat.el" "gnus/spam-wash.el" "gnus/starttls.el" +;;;;;; "gnus/utf7.el" "gnus/webmail.el" "help.el" "hex-util.el" +;;;;;; "indent.el" "international/characters.el" "international/charprop.el" +;;;;;; "international/cp51932.el" "international/eucjp-ms.el" "international/fontset.el" +;;;;;; "international/iso-ascii.el" "international/ja-dic-cnv.el" +;;;;;; "international/ja-dic-utl.el" "international/mule-cmds.el" +;;;;;; "international/mule-conf.el" "international/mule.el" "international/ogonek.el" +;;;;;; "international/uni-bidi.el" "international/uni-category.el" +;;;;;; "international/uni-combining.el" "international/uni-comment.el" +;;;;;; "international/uni-decimal.el" "international/uni-decomposition.el" +;;;;;; "international/uni-digit.el" "international/uni-lowercase.el" +;;;;;; "international/uni-mirrored.el" "international/uni-name.el" +;;;;;; "international/uni-numeric.el" "international/uni-old-name.el" +;;;;;; "international/uni-titlecase.el" "international/uni-uppercase.el" +;;;;;; "isearch.el" "jit-lock.el" "jka-cmpr-hook.el" "json.el" "kermit.el" +;;;;;; "language/burmese.el" "language/cham.el" "language/chinese.el" +;;;;;; "language/cyrillic.el" "language/czech.el" "language/english.el" +;;;;;; "language/ethiopic.el" "language/european.el" "language/georgian.el" +;;;;;; "language/greek.el" "language/hanja-util.el" "language/hebrew.el" +;;;;;; "language/indian.el" "language/japanese.el" "language/khmer.el" +;;;;;; "language/korean.el" "language/lao.el" "language/misc-lang.el" +;;;;;; "language/romanian.el" "language/sinhala.el" "language/slovak.el" +;;;;;; "language/tai-viet.el" "language/thai-word.el" "language/thai.el" +;;;;;; "language/tibetan.el" "language/utf-8-lang.el" "language/vietnamese.el" +;;;;;; "ldefs-boot.el" "loadup.el" "mail/blessmail.el" "mail/mailheader.el" +;;;;;; "mail/mailpost.el" "mail/mspools.el" "mail/rfc2368.el" "mail/rfc822.el" +;;;;;; "mail/rmail-spam-filter.el" "md4.el" "mh-e/mh-acros.el" "mh-e/mh-alias.el" +;;;;;; "mh-e/mh-buffers.el" "mh-e/mh-compat.el" "mh-e/mh-funcs.el" +;;;;;; "mh-e/mh-gnus.el" "mh-e/mh-identity.el" "mh-e/mh-inc.el" +;;;;;; "mh-e/mh-junk.el" "mh-e/mh-letter.el" "mh-e/mh-limit.el" +;;;;;; "mh-e/mh-loaddefs.el" "mh-e/mh-mime.el" "mh-e/mh-print.el" +;;;;;; "mh-e/mh-scan.el" "mh-e/mh-search.el" "mh-e/mh-seq.el" "mh-e/mh-show.el" +;;;;;; "mh-e/mh-speed.el" "mh-e/mh-thread.el" "mh-e/mh-tool-bar.el" +;;;;;; "mh-e/mh-utils.el" "mh-e/mh-xface.el" "minibuffer.el" "mouse-copy.el" +;;;;;; "mouse.el" "net/dig.el" "net/dns.el" "net/eudc-vars.el" "net/eudcb-bbdb.el" +;;;;;; "net/eudcb-ldap.el" "net/eudcb-mab.el" "net/eudcb-ph.el" +;;;;;; "net/hmac-def.el" "net/hmac-md5.el" "net/imap.el" "net/ldap.el" +;;;;;; "net/mairix.el" "net/netrc.el" "net/newsticker.el" "net/ntlm.el" +;;;;;; "net/sasl-cram.el" "net/sasl-digest.el" "net/sasl-ntlm.el" +;;;;;; "net/sasl.el" "net/socks.el" "net/tls.el" "net/tramp-cache.el" +;;;;;; "net/tramp-cmds.el" "net/tramp-compat.el" "net/tramp-fish.el" +;;;;;; "net/tramp-gw.el" "net/tramp-smb.el" "net/tramp-uu.el" "net/trampver.el" +;;;;;; "net/zeroconf.el" "nxml/nxml-enc.el" "nxml/nxml-maint.el" +;;;;;; "nxml/nxml-ns.el" "nxml/nxml-outln.el" "nxml/nxml-parse.el" +;;;;;; "nxml/nxml-rap.el" "nxml/nxml-util.el" "nxml/rng-dt.el" "nxml/rng-loc.el" +;;;;;; "nxml/rng-maint.el" "nxml/rng-match.el" "nxml/rng-parse.el" +;;;;;; "nxml/rng-pttrn.el" "nxml/rng-uri.el" "nxml/rng-util.el" +;;;;;; "nxml/xsd-regexp.el" "org/org-archive.el" "org/org-bibtex.el" +;;;;;; "org/org-colview.el" "org/org-compat.el" "org/org-faces.el" +;;;;;; "org/org-gnus.el" "org/org-info.el" "org/org-install.el" +;;;;;; "org/org-jsinfo.el" "org/org-list.el" "org/org-mac-message.el" +;;;;;; "org/org-macs.el" "org/org-mew.el" "org/org-mhe.el" "org/org-mouse.el" +;;;;;; "org/org-rmail.el" "org/org-vm.el" "org/org-w3m.el" "org/org-wl.el" +;;;;;; "password-cache.el" "patcomp.el" "paths.el" "pcvs-info.el" +;;;;;; "pcvs-parse.el" "pcvs-util.el" "pgg-def.el" "pgg-parse.el" +;;;;;; "pgg-pgp.el" "pgg-pgp5.el" "play/gamegrid.el" "play/gametree.el" +;;;;;; "play/meese.el" "progmodes/ada-prj.el" "progmodes/cc-align.el" +;;;;;; "progmodes/cc-awk.el" "progmodes/cc-bytecomp.el" "progmodes/cc-cmds.el" +;;;;;; "progmodes/cc-defs.el" "progmodes/cc-fonts.el" "progmodes/cc-langs.el" +;;;;;; "progmodes/cc-menus.el" "progmodes/ebnf-abn.el" "progmodes/ebnf-bnf.el" +;;;;;; "progmodes/ebnf-dtd.el" "progmodes/ebnf-ebx.el" "progmodes/ebnf-iso.el" +;;;;;; "progmodes/ebnf-otz.el" "progmodes/ebnf-yac.el" "progmodes/idlw-complete-structtag.el" +;;;;;; "progmodes/idlw-help.el" "progmodes/idlw-toolbar.el" "progmodes/mantemp.el" +;;;;;; "progmodes/xscheme.el" "ps-def.el" "ps-mule.el" "ps-samp.el" +;;;;;; "replace.el" "rfn-eshadow.el" "s-region.el" "saveplace.el" +;;;;;; "sb-image.el" "scroll-bar.el" "select.el" "simple.el" "soundex.el" +;;;;;; "startup.el" "subdirs.el" "subr.el" "tempo.el" "textmodes/bib-mode.el" +;;;;;; "textmodes/fill.el" "textmodes/makeinfo.el" "textmodes/page-ext.el" +;;;;;; "textmodes/page.el" "textmodes/paragraphs.el" "textmodes/refbib.el" +;;;;;; "textmodes/refer.el" "textmodes/reftex-auc.el" "textmodes/reftex-dcr.el" +;;;;;; "textmodes/reftex-ref.el" "textmodes/reftex-sel.el" "textmodes/reftex-toc.el" +;;;;;; "textmodes/texnfo-upd.el" "textmodes/text-mode.el" "timezone.el" +;;;;;; "tooltip.el" "tree-widget.el" "uniquify.el" "url/url-about.el" +;;;;;; "url/url-cookie.el" "url/url-dired.el" "url/url-expand.el" +;;;;;; "url/url-ftp.el" "url/url-history.el" "url/url-imap.el" "url/url-methods.el" +;;;;;; "url/url-nfs.el" "url/url-proxy.el" "url/url-vars.el" "vc-dav.el" +;;;;;; "vc-hooks.el" "vcursor.el" "version.el" "vt-control.el" "vt100-led.el" +;;;;;; "w32-fns.el" "w32-vars.el" "widget.el" "window.el" "x-dnd.el") +;;;;;; (19056 26498 763946)) + +;;;*** + +(provide 'loaddefs) +;; Local Variables: +;; version-control: never +;; no-byte-compile: t +;; no-update-autoloads: t +;; coding: utf-8 +;; End: +;;; loaddefs.el ends here diff --git a/lisp/mail/.cvsignore b/lisp/mail/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/mail/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/mh-e/.arch-inventory b/lisp/mh-e/.arch-inventory deleted file mode 100644 index 2fada52b96f..00000000000 --- a/lisp/mh-e/.arch-inventory +++ /dev/null @@ -1,4 +0,0 @@ -# Auto-generated lisp files, which ignore -precious ^(mh-loaddefs)\.el$ - -# arch-tag: 03c1cf02-6c80-44af-b4ec-b41b53fbf8f2 diff --git a/lisp/mh-e/.cvsignore b/lisp/mh-e/.cvsignore deleted file mode 100644 index 2e5b1740f15..00000000000 --- a/lisp/mh-e/.cvsignore +++ /dev/null @@ -1,3 +0,0 @@ -mh-autoloads.el -mh-cus-load.el -mh-loaddefs.el diff --git a/lisp/mh-e/mh-loaddefs.el b/lisp/mh-e/mh-loaddefs.el new file mode 100644 index 00000000000..2f61bfe9c8e --- /dev/null +++ b/lisp/mh-e/mh-loaddefs.el @@ -0,0 +1,3150 @@ +;;; mh-loaddefs.el --- automatically extracted autoloads +;; +;;; Code: + + +;;;### (autoloads (mh-iterate-on-range mh-iterate-on-messages-in-region +;;;;;; mh-do-at-event-location mh-in-show-buffer with-mh-folder-updating +;;;;;; mh-defstruct mh-mark-active-p mh-make-local-hook defmacro-mh +;;;;;; defun-mh mh-funcall-if-exists mh-do-in-xemacs mh-do-in-gnu-emacs +;;;;;; mh-require-cl) "mh-acros" "mh-acros.el" (19005 47398)) +;;; Generated autoloads from mh-acros.el + +(autoload 'mh-require-cl "mh-acros" "\ +Macro to load \"cl\" if needed. + +Emacs coding conventions require that the \"cl\" package not be +required at runtime. However, the \"cl\" package in Emacs 21.4 +and earlier left \"cl\" routines in their macro expansions. In +particular, the expansion of (setf (gethash ...) ...) used +functions in \"cl\" at run time. This macro recognizes that and +loads \"cl\" appropriately. + +\(fn)" nil (quote macro)) + +(autoload 'mh-do-in-gnu-emacs "mh-acros" "\ +Execute BODY if in GNU Emacs. + +\(fn &rest BODY)" nil (quote macro)) + +(autoload 'mh-do-in-xemacs "mh-acros" "\ +Execute BODY if in XEmacs. + +\(fn &rest BODY)" nil (quote macro)) + +(autoload 'mh-funcall-if-exists "mh-acros" "\ +Call FUNCTION with ARGS as parameters if it exists. + +\(fn FUNCTION &rest ARGS)" nil (quote macro)) + +(autoload 'defun-mh "mh-acros" "\ +Create function NAME. +If FUNCTION exists, then NAME becomes an alias for FUNCTION. +Otherwise, create function NAME with ARG-LIST and BODY. + +\(fn NAME FUNCTION ARG-LIST &rest BODY)" nil (quote macro)) + +(autoload 'defmacro-mh "mh-acros" "\ +Create macro NAME. +If MACRO exists, then NAME becomes an alias for MACRO. +Otherwise, create macro NAME with ARG-LIST and BODY. + +\(fn NAME MACRO ARG-LIST &rest BODY)" nil (quote macro)) + +(autoload 'mh-make-local-hook "mh-acros" "\ +Make HOOK local if needed. +XEmacs and versions of GNU Emacs before 21.1 require +`make-local-hook' to be called. + +\(fn HOOK)" nil (quote macro)) + +(autoload 'mh-mark-active-p "mh-acros" "\ +A macro that expands into appropriate code in XEmacs and nil in GNU Emacs. +In GNU Emacs if CHECK-TRANSIENT-MARK-MODE-FLAG is non-nil then +check if variable `transient-mark-mode' is active. + +\(fn CHECK-TRANSIENT-MARK-MODE-FLAG)" nil (quote macro)) + +(autoload 'mh-defstruct "mh-acros" "\ +Replacement for `defstruct' from the \"cl\" package. +The `defstruct' in the \"cl\" library produces compiler warnings, +and generates code that uses functions present in \"cl\" at +run-time. This is a partial replacement, that avoids these +issues. + +NAME-SPEC declares the name of the structure, while FIELDS +describes the various structure fields. Lookup `defstruct' for +more details. + +\(fn NAME-SPEC &rest FIELDS)" nil (quote macro)) + +(autoload 'with-mh-folder-updating "mh-acros" "\ +Format is (with-mh-folder-updating (SAVE-MODIFICATION-FLAG) &body BODY). +Execute BODY, which can modify the folder buffer without having to +worry about file locking or the read-only flag, and return its result. +If SAVE-MODIFICATION-FLAG is non-nil, the buffer's modification flag +is unchanged, otherwise it is cleared. + +\(fn SAVE-MODIFICATION-FLAG &rest BODY)" nil (quote macro)) + +(autoload 'mh-in-show-buffer "mh-acros" "\ +Format is (mh-in-show-buffer (SHOW-BUFFER) &body BODY). +Display buffer SHOW-BUFFER in other window and execute BODY in it. +Stronger than `save-excursion', weaker than `save-window-excursion'. + +\(fn SHOW-BUFFER &rest BODY)" nil (quote macro)) + +(autoload 'mh-do-at-event-location "mh-acros" "\ +Switch to the location of EVENT and execute BODY. +After BODY has been executed return to original window. The +modification flag of the buffer in the event window is +preserved. + +\(fn EVENT &rest BODY)" nil (quote macro)) + +(defsubst mh-seq-msgs (sequence) "\ +Extract messages from the given SEQUENCE." (cdr sequence)) + +(autoload 'mh-iterate-on-messages-in-region "mh-acros" "\ +Iterate over region. + +VAR is bound to the message on the current line as we loop +starting from BEGIN till END. In each step BODY is executed. + +If VAR is nil then the loop is executed without any binding. + +\(fn VAR BEGIN END &rest BODY)" nil (quote macro)) + +(autoload 'mh-iterate-on-range "mh-acros" "\ +Iterate an operation over a region or sequence. + +VAR is bound to each message in turn in a loop over RANGE, which +can be a message number, a list of message numbers, a sequence, a +region in a cons cell, or a MH range (something like last:20) in +a string. In each iteration, BODY is executed. + +The parameter RANGE is usually created with +`mh-interactive-range' in order to provide a uniform interface to +MH-E functions. + +\(fn VAR RANGE &rest BODY)" nil (quote macro)) + +;;;*** + +;;;### (autoloads (mh-alias-grab-from-field mh-alias-for-from-p mh-alias-address-to-alias +;;;;;; mh-alias-letter-expand-alias mh-alias-minibuffer-confirm-address +;;;;;; mh-read-address mh-alias-expand mh-alias-reload-maybe) "mh-alias" +;;;;;; "mh-alias.el" (19005 47398)) +;;; Generated autoloads from mh-alias.el + +(autoload 'mh-alias-reload-maybe "mh-alias" "\ +Load new MH aliases. + +\(fn)" nil nil) + +(autoload 'mh-alias-expand "mh-alias" "\ +Return expansion for ALIAS. +Blind aliases or users from /etc/passwd are not expanded. + +\(fn ALIAS)" nil nil) + +(autoload 'mh-read-address "mh-alias" "\ +Read an address from the minibuffer with PROMPT. + +\(fn PROMPT)" nil nil) + +(autoload 'mh-alias-minibuffer-confirm-address "mh-alias" "\ +Display the alias expansion if `mh-alias-flash-on-comma' is non-nil. + +\(fn)" t nil) + +(autoload 'mh-alias-letter-expand-alias "mh-alias" "\ +Expand mail alias before point. + +\(fn)" nil nil) + +(autoload 'mh-alias-address-to-alias "mh-alias" "\ +Return the ADDRESS alias if defined, or nil. + +\(fn ADDRESS)" nil nil) + +(autoload 'mh-alias-for-from-p "mh-alias" "\ +Return t if sender's address has a corresponding alias. + +\(fn)" nil nil) + +(autoload 'mh-alias-grab-from-field "mh-alias" "\ +Add alias for the sender of the current message. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (mh-insert-auto-fields mh-show-buffer-message-number +;;;;;; mh-send mh-reply mh-redistribute mh-forward mh-extract-rejected-mail +;;;;;; mh-edit-again) "mh-comp" "mh-comp.el" (19005 47398)) +;;; Generated autoloads from mh-comp.el + +(autoload 'mh-edit-again "mh-comp" "\ +Edit a MESSAGE to send it again. + +If you don't complete a draft for one reason or another, and if +the draft buffer is no longer available, you can pick your draft +up again with this command. If you don't use a draft folder, your +last \"draft\" file will be used. If you use draft folders, +you'll need to visit the draft folder with \"\\[mh-visit-folder] +drafts \", use \\[mh-next-undeleted-msg] to move to the +appropriate message, and then use \\[mh-edit-again] to prepare +the message for editing. + +This command can also be used to take messages that were sent to +you and to send them to more people. + +Don't use this command to re-edit a message from a Mailer-Daemon +who complained that your mail wasn't posted for some reason or +another (see `mh-extract-rejected-mail'). + +The default message is the current message. + +See also `mh-send'. + +\(fn MESSAGE)" t nil) + +(autoload 'mh-extract-rejected-mail "mh-comp" "\ +Edit a MESSAGE that was returned by the mail system. + +This command prepares the message for editing by removing the +Mailer-Daemon envelope and unneeded header fields. Fix whatever +addressing problem you had, and send the message again with +\\[mh-send-letter]. + +The default message is the current message. + +See also `mh-send'. + +\(fn MESSAGE)" t nil) + +(autoload 'mh-forward "mh-comp" "\ +Forward message. + +You are prompted for the TO and CC recipients. You are given a +draft to edit that looks like it would if you had run the MH +command \"forw\". You can then add some text. + +You can forward several messages by using a RANGE. All of the +messages in the range are inserted into your draft. Check the +documentation of `mh-interactive-range' to see how RANGE is read +in interactive use. + +The hook `mh-forward-hook' is called on the draft. + +See also `mh-compose-forward-as-mime-flag', +`mh-forward-subject-format', and `mh-send'. + +\(fn TO CC &optional RANGE)" t nil) + +(autoload 'mh-redistribute "mh-comp" "\ +Redistribute a message. + +This command is similar in function to forwarding mail, but it +does not allow you to edit the message, nor does it add your name +to the \"From\" header field. It appears to the recipient as if +the message had come from the original sender. When you run this +command, you are prompted for the TO and CC recipients. The +default MESSAGE is the current message. + +Also investigate the command \\[mh-edit-again] for another way to +redistribute messages. + +See also `mh-redist-full-contents-flag'. + +The hook `mh-annotate-msg-hook' is run after annotating the +message and scan line. + +\(fn TO CC &optional MESSAGE)" t nil) + +(autoload 'mh-reply "mh-comp" "\ +Reply to a MESSAGE. + +When you reply to a message, you are first prompted with \"Reply +to whom?\" (unless the optional argument REPLY-TO is provided). +You have several choices here. + + Response Reply Goes To + + from The person who sent the message. This is the + default, so is sufficient. + + to Replies to the sender, plus all recipients in the + \"To:\" header field. + + all cc Forms a reply to the addresses in the + \"Mail-Followup-To:\" header field if one + exists; otherwise forms a reply to the sender, + plus all recipients. + +Depending on your answer, \"repl\" is given a different argument +to form your reply. Specifically, a choice of \"from\" or none at +all runs \"repl -nocc all\", and a choice of \"to\" runs \"repl +-cc to\". Finally, either \"cc\" or \"all\" runs \"repl -cc all +-nocc me\". + +Two windows are then created. One window contains the message to +which you are replying in an MH-Show buffer. Your draft, in +MH-Letter mode (*note `mh-letter-mode'), is in the other window. +If the reply draft was not one that you expected, check the +things that affect the behavior of \"repl\" which include the +\"repl:\" profile component and the \"replcomps\" and +\"replgroupcomps\" files. + +If you supply a prefix argument INCLUDEP, the message you are +replying to is inserted in your reply after having first been run +through \"mhl\" with the format file \"mhl.reply\". + +Alternatively, you can customize the option `mh-yank-behavior' +and choose one of its \"Automatically\" variants to do the same +thing. If you do so, the prefix argument has no effect. + +Another way to include the message automatically in your draft is +to use \"repl: -filter repl.filter\" in your MH profile. + +If you wish to customize the header or other parts of the reply +draft, please see \"repl\" and \"mh-format\". + +See also `mh-reply-show-message-flag', +`mh-reply-default-reply-to', and `mh-send'. + +\(fn MESSAGE &optional REPLY-TO INCLUDEP)" t nil) + +(autoload 'mh-send "mh-comp" "\ +Compose a message. + +Your letter appears in an Emacs buffer whose mode is +MH-Letter (see `mh-letter-mode'). + +The arguments TO, CC, and SUBJECT can be used to prefill the +draft fields or suppress the prompts if `mh-compose-prompt-flag' +is on. They are also passed to the function set in the option +`mh-compose-letter-function'. + +See also `mh-insert-x-mailer-flag' and `mh-letter-mode-hook'. + +Outside of an MH-Folder buffer (`mh-folder-mode'), you must call +either \\[mh-smail] or \\[mh-smail-other-window] to compose a new +message. + +\(fn TO CC SUBJECT)" t nil) + +(autoload 'mh-show-buffer-message-number "mh-comp" "\ +Message number of displayed message in corresponding show buffer. + +Return nil if show buffer not displayed. +If in `mh-letter-mode', don't display the message number being replied +to, but rather the message number of the show buffer associated with +our originating folder buffer. +Optional argument BUFFER can be used to specify the buffer. + +\(fn &optional BUFFER)" nil nil) + +(autoload 'mh-insert-auto-fields "mh-comp" "\ +Insert custom fields if recipient is found in `mh-auto-fields-list'. + +Once the header contains one or more recipients, you may run this +command to insert these fields manually. However, if you use this +command, the automatic insertion when the message is sent is +disabled. + +In a program, set buffer-local `mh-insert-auto-fields-done-local' +if header fields were added. If NON-INTERACTIVE is non-nil, +perform actions quietly and only if +`mh-insert-auto-fields-done-local' is nil. Return t if fields +added; otherwise return nil. + +\(fn &optional NON-INTERACTIVE)" t nil) + +;;;*** + +;;;### (autoloads (mh-msg-filename mh-refile-a-msg mh-delete-a-msg +;;;;;; mh-folder-from-address mh-prompt-for-refile-folder mh-next-msg +;;;;;; mh-reset-threads-and-narrowing mh-regenerate-headers mh-process-or-undo-commands +;;;;;; mh-scan-folder mh-make-folder-mode-line mh-set-folder-modified-p +;;;;;; mh-outstanding-commands-p mh-recenter mh-goto-cur-msg mh-update-sequences +;;;;;; mh-write-msg-to-file mh-visit-folder mh-undo mh-toggle-showing +;;;;;; mh-rescan-folder mh-refile-or-write-again mh-refile-msg mh-quit +;;;;;; mh-previous-unread-msg mh-previous-undeleted-msg mh-previous-page +;;;;;; mh-prev-button mh-page-msg mh-next-unread-msg mh-next-undeleted-msg +;;;;;; mh-next-button mh-modify mh-last-msg mh-inc-folder mh-goto-msg +;;;;;; mh-first-msg mh-execute-commands mh-delete-msg-no-motion +;;;;;; mh-delete-msg) "mh-folder" "mh-folder.el" (19005 47398)) +;;; Generated autoloads from mh-folder.el + +(autoload 'mh-delete-msg "mh-folder" "\ +Delete RANGE\\. + +To mark a message for deletion, use this command. A \"D\" is +placed by the message in the scan window, and the next undeleted +message is displayed. If the previous command had been +\\[mh-previous-undeleted-msg], then the next message displayed is +the first undeleted message previous to the message just deleted. +Use \\[mh-next-undeleted-msg] to force subsequent +\\[mh-delete-msg] commands to move forward to the next undeleted +message after deleting the message under the cursor. + +The hook `mh-delete-msg-hook' is called after you mark a message +for deletion. For example, a past maintainer of MH-E used this +once when he kept statistics on his mail usage. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-delete-msg-no-motion "mh-folder" "\ +Delete RANGE, don't move to next message. + +This command marks the RANGE for deletion but leaves the cursor +at the current message in case you wish to perform other +operations on the message. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-execute-commands "mh-folder" "\ +Process outstanding delete and refile requests\\. + +If you've marked messages to be deleted or refiled and you want +to go ahead and delete or refile the messages, use this command. +Many MH-E commands that may affect the numbering of the +messages (such as \\[mh-rescan-folder] or \\[mh-pack-folder]) +will ask if you want to process refiles or deletes first and then +either run this command for you or undo the pending refiles and +deletes. + +This function runs `mh-before-commands-processed-hook' before the +commands are processed and `mh-after-commands-processed-hook' +after the commands are processed. + +\(fn)" t nil) + +(autoload 'mh-first-msg "mh-folder" "\ +Display first message. + +\(fn)" t nil) + +(autoload 'mh-goto-msg "mh-folder" "\ +Go to a message\\. + +You can enter the message NUMBER either before or after typing +\\[mh-goto-msg]. In the latter case, Emacs prompts you. + +In a program, optional non-nil second argument NO-ERROR-IF-NO-MESSAGE +means return nil instead of signaling an error if message does not +exist; in this case, the cursor is positioned near where the message +would have been. Non-nil third argument DONT-SHOW means not to show +the message. + +\(fn NUMBER &optional NO-ERROR-IF-NO-MESSAGE DONT-SHOW)" t nil) + +(autoload 'mh-inc-folder "mh-folder" "\ +Incorporate new mail into a folder. + +You can incorporate mail from any file into the current folder by +specifying a prefix argument; you'll be prompted for the name of +the FILE to use as well as the destination FOLDER + +The hook `mh-inc-folder-hook' is run after incorporating new +mail. + +Do not call this function from outside MH-E; use \\[mh-rmail] +instead. + +\(fn &optional FILE FOLDER)" t nil) + +(autoload 'mh-last-msg "mh-folder" "\ +Display last message. + +\(fn)" t nil) + +(autoload 'mh-modify "mh-folder" "\ +Edit message. + +There are times when you need to edit a message. For example, you +may need to fix a broken Content-Type header field. You can do +this with this command. It displays the raw message in an +editable buffer. When you are done editing, save and kill the +buffer as you would any other. + +From a program, edit MESSAGE; nil means edit current message. + +\(fn &optional MESSAGE)" t nil) + +(autoload 'mh-next-button "mh-folder" "\ +Go to the next button. + +If the end of the buffer is reached then the search wraps over to +the start of the buffer. + +If an optional prefix argument BACKWARD-FLAG is given, the cursor +will move to the previous button. + +\(fn &optional BACKWARD-FLAG)" t nil) + +(autoload 'mh-next-undeleted-msg "mh-folder" "\ +Display next message. + +This command can be given a prefix argument COUNT to specify how +many unread messages to skip. + +In a program, pause for a second after printing message if we are +at the last undeleted message and optional argument +WAIT-AFTER-COMPLAINING-FLAG is non-nil. + +\(fn &optional COUNT WAIT-AFTER-COMPLAINING-FLAG)" t nil) + +(autoload 'mh-next-unread-msg "mh-folder" "\ +Display next unread message. + +This command can be given a prefix argument COUNT to specify how +many unread messages to skip. + +\(fn &optional COUNT)" t nil) + +(autoload 'mh-page-msg "mh-folder" "\ +Display next page in message. + +You can give this command a prefix argument that specifies the +number of LINES to scroll. This command will also show the next +undeleted message if it is used at the bottom of a message. + +\(fn &optional LINES)" t nil) + +(autoload 'mh-prev-button "mh-folder" "\ +Go to the previous button. + +If the beginning of the buffer is reached then the search wraps +over to the end of the buffer. + +\(fn)" t nil) + +(autoload 'mh-previous-page "mh-folder" "\ +Display next page in message. + +You can give this command a prefix argument that specifies the +number of LINES to scroll. + +\(fn &optional LINES)" t nil) + +(autoload 'mh-previous-undeleted-msg "mh-folder" "\ +Display previous message. + +This command can be given a prefix argument COUNT to specify how +many unread messages to skip. + +In a program, pause for a second after printing message if we are +at the last undeleted message and optional argument +WAIT-AFTER-COMPLAINING-FLAG is non-nil. + +\(fn &optional COUNT WAIT-AFTER-COMPLAINING-FLAG)" t nil) + +(autoload 'mh-previous-unread-msg "mh-folder" "\ +Display previous unread message. + +This command can be given a prefix argument COUNT to specify how +many unread messages to skip. + +\(fn &optional COUNT)" t nil) + +(autoload 'mh-quit "mh-folder" "\ +Quit the current MH-E folder. + +When you want to quit using MH-E and go back to editing, you can use +this command. This buries the buffers of the current MH-E folder and +restores the buffers that were present when you first ran +\\[mh-rmail]. It also removes any MH-E working buffers whose name +begins with \" *mh-\" or \"*MH-E \". You can later restore your MH-E +session by selecting the \"+inbox\" buffer or by running \\[mh-rmail] +again. + +The two hooks `mh-before-quit-hook' and `mh-quit-hook' are called by +this function. The former one is called before the quit occurs, so you +might use it to perform any MH-E operations; you could perform some +query and abort the quit or call `mh-execute-commands', for example. +The latter is not run in an MH-E context, so you might use it to +modify the window setup. + +\(fn)" t nil) + +(autoload 'mh-refile-msg "mh-folder" "\ +Refile (output) RANGE into FOLDER. + +You are prompted for the folder name. Note that this command can also +be used to create folders. If you specify a folder that does not +exist, you will be prompted to create it. + +The hook `mh-refile-msg-hook' is called after a message is marked to +be refiled. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +In a program, the variables `mh-last-destination' and +`mh-last-destination-folder' are not updated if +DONT-UPDATE-LAST-DESTINATION-FLAG is non-nil. + +\(fn RANGE FOLDER &optional DONT-UPDATE-LAST-DESTINATION-FLAG)" t nil) + +(autoload 'mh-refile-or-write-again "mh-folder" "\ +Repeat last output command. + +If you are refiling several messages into the same folder, you +can use this command to repeat the last +refile (\\[mh-refile-msg]) or write (\\[mh-write-msg-to-file]). +You can use a range. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +In a program, a non-nil INTERACTIVE-FLAG means that the function was +called interactively. + +\(fn RANGE &optional INTERACTIVE-FLAG)" t nil) + +(autoload 'mh-rescan-folder "mh-folder" "\ +Rescan folder\\. + +This command is useful to grab all messages in your \"+inbox\" after +processing your new mail for the first time. If you don't want to +rescan the entire folder, this command will accept a RANGE. Check the +documentation of `mh-interactive-range' to see how RANGE is read in +interactive use. + +This command will ask if you want to process refiles or deletes first +and then either run \\[mh-execute-commands] for you or undo the +pending refiles and deletes. + +In a program, the processing of outstanding commands is not performed +if DONT-EXEC-PENDING is non-nil. + +\(fn &optional RANGE DONT-EXEC-PENDING)" t nil) + +(autoload 'mh-toggle-showing "mh-folder" "\ +Toggle between MH-Folder and MH-Folder Show modes. + +This command switches between MH-Folder mode and MH-Folder Show +mode. MH-Folder mode turns off the associated show buffer so that +you can perform operations on the messages quickly without +reading them. This is an excellent way to prune out your junk +mail or to refile a group of messages to another folder for later +examination. + +\(fn)" t nil) + +(autoload 'mh-undo "mh-folder" "\ +Undo pending deletes or refiles in RANGE. + +If you've deleted a message or refiled it, but changed your mind, +you can cancel the action before you've executed it. Use this +command to undo a refile on or deletion of a single message. You +can also undo refiles and deletes for messages that are found in +a given RANGE. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-visit-folder "mh-folder" "\ +Visit FOLDER. + +When you want to read the messages that you have refiled into folders, +use this command to visit the folder. You are prompted for the folder +name. + +The folder buffer will show just unseen messages if there are any; +otherwise, it will show all the messages in the buffer as long there +are fewer than `mh-large-folder' messages. If there are more, then you +are prompted for a range of messages to scan. + +You can provide a prefix argument in order to specify a RANGE of +messages to show when you visit the folder. In this case, regions are +not used to specify the range and `mh-large-folder' is ignored. Check +the documentation of `mh-interactive-range' to see how RANGE is read +in interactive use. + +Note that this command can also be used to create folders. If you +specify a folder that does not exist, you will be prompted to create +it. + +Do not call this function from outside MH-E; use \\[mh-rmail] instead. + +If, in a program, RANGE is nil (the default), then all messages in +FOLDER are displayed. If an index buffer is being created then +INDEX-DATA is used to initialize the index buffer specific data +structures. + +\(fn FOLDER &optional RANGE INDEX-DATA)" t nil) + +(autoload 'mh-write-msg-to-file "mh-folder" "\ +Append MESSAGE to end of FILE\\. + +You are prompted for the filename. If the file already exists, +the message is appended to it. You can also write the message to +the file without the header by specifying a prefix argument +NO-HEADER. Subsequent writes to the same file can be made with +the command \\[mh-refile-or-write-again]. + +\(fn MESSAGE FILE NO-HEADER)" t nil) + +(autoload 'mh-update-sequences "mh-folder" "\ +Flush MH-E's state out to MH. + +This function updates the sequence specified by your +\"Unseen-Sequence:\" profile component, \"cur\", and the sequence +listed by the `mh-tick-seq' option which is \"tick\" by default. +The message at the cursor is used for \"cur\". + +\(fn)" t nil) + +(autoload 'mh-goto-cur-msg "mh-folder" "\ +Position the cursor at the current message. +When optional argument MINIMAL-CHANGES-FLAG is non-nil, the +function doesn't recenter the folder buffer. + +\(fn &optional MINIMAL-CHANGES-FLAG)" nil nil) + +(autoload 'mh-recenter "mh-folder" "\ +Like recenter but with three improvements: + +- At the end of the buffer it tries to show fewer empty lines. + +- operates only if the current buffer is in the selected window. + (Commands like `save-some-buffers' can make this false.) + +- nil ARG means recenter as if prefix argument had been given. + +\(fn ARG)" nil nil) + +(autoload 'mh-outstanding-commands-p "mh-folder" "\ +Return non-nil if there are outstanding deletes or refiles. + +\(fn)" nil nil) + +(autoload 'mh-set-folder-modified-p "mh-folder" "\ +Mark current folder as modified or unmodified according to FLAG. + +\(fn FLAG)" nil nil) + +(autoload 'mh-make-folder-mode-line "mh-folder" "\ +Set the fields of the mode line for a folder buffer. +The optional argument is now obsolete and IGNORED. It used to be +used to pass in what is now stored in the buffer-local variable +`mh-mode-line-annotation'. + +\(fn &optional IGNORED)" nil nil) + +(autoload 'mh-scan-folder "mh-folder" "\ +Scan FOLDER over RANGE. + +After the scan is performed, switch to the buffer associated with +FOLDER. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +The processing of outstanding commands is not performed if +DONT-EXEC-PENDING is non-nil. + +\(fn FOLDER RANGE &optional DONT-EXEC-PENDING)" nil nil) + +(autoload 'mh-process-or-undo-commands "mh-folder" "\ +If FOLDER has outstanding commands, then either process or discard them. +Called by functions like `mh-sort-folder', so also invalidate +show buffer. + +\(fn FOLDER)" nil nil) + +(autoload 'mh-regenerate-headers "mh-folder" "\ +Scan folder over RANGE. +If UPDATE, append the scan lines, otherwise replace. + +\(fn RANGE &optional UPDATE)" nil nil) + +(autoload 'mh-reset-threads-and-narrowing "mh-folder" "\ +Reset all variables pertaining to threads and narrowing. +Also removes all content from the folder buffer. + +\(fn)" nil nil) + +(autoload 'mh-next-msg "mh-folder" "\ +Move backward or forward to the next undeleted message in the buffer. +If optional argument WAIT-AFTER-COMPLAINING-FLAG is non-nil and +we are at the last message, then wait for a second after telling +the user that there aren't any more unread messages. + +\(fn &optional WAIT-AFTER-COMPLAINING-FLAG)" nil nil) + +(autoload 'mh-prompt-for-refile-folder "mh-folder" "\ +Prompt the user for a folder in which the message should be filed. +The folder is returned as a string. + +The default folder name is generated by the option +`mh-default-folder-for-message-function' if it is non-nil or +`mh-folder-from-address'. + +\(fn)" nil nil) + +(autoload 'mh-folder-from-address "mh-folder" "\ +Derive folder name from sender. + +The name of the folder is derived as follows: + + a) The folder name associated with the first address found in + the list `mh-default-folder-list' is used. Each element in + this list contains a \"Check Recipient\" item. If this item is + turned on, then the address is checked against the recipient + instead of the sender. This is useful for mailing lists. + + b) An alias prefixed by `mh-default-folder-prefix' + corresponding to the address is used. The prefix is used to + prevent clutter in your mail directory. + +Return nil if a folder name was not derived, or if the variable +`mh-default-folder-must-exist-flag' is t and the folder does not +exist. + +\(fn)" nil nil) + +(autoload 'mh-delete-a-msg "mh-folder" "\ +Delete MESSAGE. +If MESSAGE is nil then the message at point is deleted. +The hook `mh-delete-msg-hook' is called after you mark a message +for deletion. For example, a past maintainer of MH-E used this +once when he kept statistics on his mail usage. + +\(fn MESSAGE)" nil nil) + +(autoload 'mh-refile-a-msg "mh-folder" "\ +Refile MESSAGE in FOLDER. +If MESSAGE is nil then the message at point is refiled. +Folder is a symbol, not a string. +The hook `mh-refile-msg-hook' is called after a message is marked to +be refiled. + +\(fn MESSAGE FOLDER)" nil nil) + +(autoload 'mh-msg-filename "mh-folder" "\ +Return the file name of MSG in FOLDER (default current folder). + +\(fn MSG &optional FOLDER)" nil nil) + +;;;*** + +;;;### (autoloads (mh-undo-folder mh-store-msg mh-sort-folder mh-pipe-msg +;;;;;; mh-page-digest-backwards mh-page-digest mh-pack-folder mh-list-folders +;;;;;; mh-kill-folder mh-copy-msg mh-burst-digest) "mh-funcs" "mh-funcs.el" +;;;;;; (19005 47398)) +;;; Generated autoloads from mh-funcs.el + +(autoload 'mh-burst-digest "mh-funcs" "\ +Break up digest into separate messages\\. + +This command uses the MH command \"burst\" to break out each +message in the digest into its own message. Using this command, +you can quickly delete unwanted messages, like this: Once the +digest is split up, toggle out of MH-Folder Show mode with +\\[mh-toggle-showing] so that the scan lines fill the screen and +messages aren't displayed. Then use \\[mh-delete-msg] to quickly +delete messages that you don't want to read (based on the +\"Subject:\" header field). You can also burst the digest to +reply directly to the people who posted the messages in the +digest. One problem you may encounter is that the \"From:\" +header fields are preceded with a \">\" so that your reply can't +create the \"To:\" field correctly. In this case, you must +correct the \"To:\" field yourself. + +\(fn)" t nil) + +(autoload 'mh-copy-msg "mh-funcs" "\ +Copy RANGE to FOLDER\\. + +If you wish to copy a message to another folder, you can use this +command (see the \"-link\" argument to \"refile\"). Like the +command \\[mh-refile-msg], this command prompts you for the name +of the target folder and you can specify a range. Note that +unlike the command \\[mh-refile-msg], the copy takes place +immediately. The original copy remains in the current folder. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE FOLDER)" t nil) + +(autoload 'mh-kill-folder "mh-funcs" "\ +Remove folder. + +Remove all of the messages (files) within the current folder, and +then remove the folder (directory) itself. + +Run the abnormal hook `mh-kill-folder-suppress-prompt-hooks'. The +hook functions are called with no arguments and should return a +non-nil value to suppress the normal prompt when you remove a +folder. This is useful for folders that are easily regenerated. + +\(fn)" t nil) + +(autoload 'mh-list-folders "mh-funcs" "\ +List mail folders. + +\(fn)" t nil) + +(autoload 'mh-pack-folder "mh-funcs" "\ +Pack folder\\. + +This command packs the folder, removing gaps from the numbering +sequence. If you don't want to rescan the entire folder +afterward, this command will accept a RANGE. Check the +documentation of `mh-interactive-range' to see how RANGE is read +in interactive use. + +This command will ask if you want to process refiles or deletes +first and then either run \\[mh-execute-commands] for you or undo +the pending refiles and deletes. + +The hook `mh-pack-folder-hook' is run after the folder is packed; +see its documentation for variables it can use. + +\(fn RANGE)" t nil) + +(autoload 'mh-page-digest "mh-funcs" "\ +Display next message in digest. + +\(fn)" t nil) + +(autoload 'mh-page-digest-backwards "mh-funcs" "\ +Display previous message in digest. + +\(fn)" t nil) + +(autoload 'mh-pipe-msg "mh-funcs" "\ +Pipe message through shell command COMMAND. + +You are prompted for the Unix command through which you wish to +run your message. If you give a prefix argument INCLUDE-HEADER to +this command, the message header is included in the text passed +to the command. + +\(fn COMMAND INCLUDE-HEADER)" t nil) + +(autoload 'mh-sort-folder "mh-funcs" "\ +Sort folder. + +By default, messages are sorted by date. The option +`mh-sortm-args' holds extra arguments to pass on to the command +\"sortm\" when a prefix argument EXTRA-ARGS is used. + +\(fn &optional EXTRA-ARGS)" t nil) + +(autoload 'mh-store-msg "mh-funcs" "\ +Unpack message created with \"uudecode\" or \"shar\". + +The default DIRECTORY for extraction is the current directory; +however, you have a chance to specify a different extraction +directory. The next time you use this command, the default +directory is the last directory you used. If you would like to +change the initial default directory, customize the option +`mh-store-default-directory', change the value from \"Current\" +to \"Directory\", and then enter the name of the directory for +storing the content of these messages. + +\(fn DIRECTORY)" t nil) + +(autoload 'mh-undo-folder "mh-funcs" "\ +Undo all refiles and deletes in the current folder. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (mh-identity-handler-bottom mh-identity-handler-top +;;;;;; mh-identity-insert-attribution-verb mh-identity-handler-attribution-verb +;;;;;; mh-identity-handler-signature mh-identity-handler-gpg-identity +;;;;;; mh-insert-identity mh-identity-add-menu mh-identity-make-menu) +;;;;;; "mh-identity" "mh-identity.el" (19005 47398)) +;;; Generated autoloads from mh-identity.el + +(autoload 'mh-identity-make-menu "mh-identity" "\ +Build the Identity menu. +This should be called any time `mh-identity-list' or +`mh-auto-fields-list' change. +See `mh-identity-add-menu'. + +\(fn)" nil nil) + +(autoload 'mh-identity-add-menu "mh-identity" "\ +Add the current Identity menu. +See `mh-identity-make-menu'. + +\(fn)" nil nil) + +(autoload 'mh-insert-identity "mh-identity" "\ +Insert fields specified by given IDENTITY. + +In a program, do not insert fields if MAYBE-INSERT is non-nil, +`mh-identity-default' is non-nil, and fields have already been +inserted. + +See `mh-identity-list'. + +\(fn IDENTITY &optional MAYBE-INSERT)" t nil) + +(autoload 'mh-identity-handler-gpg-identity "mh-identity" "\ +Process header FIELD \":pgg-default-user-id\". +The ACTION is one of 'remove or 'add. If 'add, the VALUE is added. +The buffer-local variable `mh-identity-pgg-default-user-id' is set to +VALUE when action 'add is selected. + +\(fn FIELD ACTION &optional VALUE)" nil nil) + +(autoload 'mh-identity-handler-signature "mh-identity" "\ +Process header FIELD \":signature\". +The ACTION is one of 'remove or 'add. If 'add, the VALUE is +added. + +\(fn FIELD ACTION &optional VALUE)" nil nil) + +(autoload 'mh-identity-handler-attribution-verb "mh-identity" "\ +Process header FIELD \":attribution-verb\". +The ACTION is one of 'remove or 'add. If 'add, the VALUE is +added. + +\(fn FIELD ACTION &optional VALUE)" nil nil) + +(autoload 'mh-identity-insert-attribution-verb "mh-identity" "\ +Insert VALUE as attribution verb, setting up delimiting markers. +If VALUE is nil, use `mh-extract-from-attribution-verb'. + +\(fn VALUE)" nil nil) + +(autoload 'mh-identity-handler-top "mh-identity" "\ +Process header FIELD. +The ACTION is one of 'remove or 'add. If 'add, the VALUE is +added. If the field wasn't present, it is added to the top of the +header. + +\(fn FIELD ACTION &optional VALUE)" nil nil) + +(autoload 'mh-identity-handler-bottom "mh-identity" "\ +Process header FIELD. +The ACTION is one of 'remove or 'add. If 'add, the VALUE is +added. If the field wasn't present, it is added to the bottom of +the header. + +\(fn FIELD ACTION &optional VALUE)" nil nil) + +;;;*** + +;;;### (autoloads (mh-inc-spool-make) "mh-inc" "mh-inc.el" (19005 +;;;;;; 47398)) +;;; Generated autoloads from mh-inc.el + +(autoload 'mh-inc-spool-make "mh-inc" "\ +Make all commands and defines keys for contents of `mh-inc-spool-list'. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (mh-spamprobe-whitelist mh-spamprobe-blacklist +;;;;;; mh-bogofilter-whitelist mh-bogofilter-blacklist mh-spamassassin-identify-spammers +;;;;;; mh-spamassassin-whitelist mh-spamassassin-blacklist mh-junk-whitelist +;;;;;; mh-junk-blacklist) "mh-junk" "mh-junk.el" (19005 47398)) +;;; Generated autoloads from mh-junk.el + +(autoload 'mh-junk-blacklist "mh-junk" "\ +Blacklist RANGE as spam. + +This command trains the spam program in use (see the option +`mh-junk-program') with the content of RANGE and then handles the +message(s) as specified by the option `mh-junk-disposition'. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +For more information about using your particular spam fighting +program, see: + + - `mh-spamassassin-blacklist' + - `mh-bogofilter-blacklist' + - `mh-spamprobe-blacklist' + +\(fn RANGE)" t nil) + +(autoload 'mh-junk-whitelist "mh-junk" "\ +Whitelist RANGE as ham. + +This command reclassifies the RANGE as ham if it were incorrectly +classified as spam (see the option `mh-junk-program'). It then +refiles the message into the \"+inbox\" folder. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-spamassassin-blacklist "mh-junk" "\ +Blacklist MSG with SpamAssassin. + +SpamAssassin is one of the more popular spam filtering programs. +Get it from your local distribution or from +http://spamassassin.org/. + +To use SpamAssassin, add the following recipes to +\".procmailrc\": + + PATH=$PATH:/usr/bin/mh + MAILDIR=$HOME/`mhparam Path` + + # Fight spam with SpamAssassin. + :0fw + | spamc + + # Anything with a spam level of 10 or more is junked immediately. + :0: + * ^X-Spam-Level: .......... + /dev/null + + :0: + * ^X-Spam-Status: Yes + spam/. + +If you don't use \"spamc\", use \"spamassassin -P -a\". + +Note that one of the recipes above throws away messages with a +score greater than or equal to 10. Here's how you can determine a +value that works best for you. + +First, run \"spamassassin -t\" on every mail message in your +archive and use Gnumeric to verify that the average plus the +standard deviation of good mail is under 5, the SpamAssassin +default for \"spam\". + +Using Gnumeric, sort the messages by score and view the messages +with the highest score. Determine the score which encompasses all +of your interesting messages and add a couple of points to be +conservative. Add that many dots to the \"X-Spam-Level:\" header +field above to send messages with that score down the drain. + +In the example above, messages with a score of 5-9 are set aside +in the \"+spam\" folder for later review. The major weakness of +rules-based filters is a plethora of false positives so it is +worthwhile to check. + +If SpamAssassin classifies a message incorrectly, or is unsure, +you can use the MH-E commands \\[mh-junk-blacklist] and +\\[mh-junk-whitelist]. + +The command \\[mh-junk-blacklist] adds a \"blacklist_from\" entry +to \"~/spamassassin/user_prefs\", deletes the message, and sends +the message to the Razor, so that others might not see this spam. +If the \"sa-learn\" command is available, the message is also +recategorized as spam. + +The command \\[mh-junk-whitelist] adds a \"whitelist_from\" rule +to the \"~/.spamassassin/user_prefs\" file. If the \"sa-learn\" +command is available, the message is also recategorized as ham. + +Over time, you'll observe that the same host or domain occurs +repeatedly in the \"blacklist_from\" entries, so you might think +that you could avoid future spam by blacklisting all mail from a +particular domain. The utility function +`mh-spamassassin-identify-spammers' helps you do precisely that. +This function displays a frequency count of the hosts and domains +in the \"blacklist_from\" entries from the last blank line in +\"~/.spamassassin/user_prefs\" to the end of the file. This +information can be used so that you can replace multiple +\"blacklist_from\" entries with a single wildcard entry such as: + + blacklist_from *@*amazingoffersdirect2u.com + +In versions of SpamAssassin (2.50 and on) that support a Bayesian +classifier, \\[mh-junk-blacklist] uses the program \"sa-learn\" +to recategorize the message as spam. Neither MH-E, nor +SpamAssassin, rebuilds the database after adding words, so you +will need to run \"sa-learn --rebuild\" periodically. This can be +done by adding the following to your crontab: + + 0 * * * * sa-learn --rebuild > /dev/null 2>&1 + +\(fn MSG)" nil nil) + +(autoload 'mh-spamassassin-whitelist "mh-junk" "\ +Whitelist MSG with SpamAssassin. + +The \\[mh-junk-whitelist] command adds a \"whitelist_from\" rule to +the \"~/.spamassassin/user_prefs\" file. If the \"sa-learn\" command +is available, the message is also recategorized as ham. + +See `mh-spamassassin-blacklist' for more information. + +\(fn MSG)" nil nil) + +(autoload 'mh-spamassassin-identify-spammers "mh-junk" "\ +Identify spammers who are repeat offenders. + +This function displays a frequency count of the hosts and domains +in the \"blacklist_from\" entries from the last blank line in +\"~/.spamassassin/user_prefs\" to the end of the file. This +information can be used so that you can replace multiple +\"blacklist_from\" entries with a single wildcard entry such as: + + blacklist_from *@*amazingoffersdirect2u.com + +\(fn)" t nil) + +(autoload 'mh-bogofilter-blacklist "mh-junk" "\ +Blacklist MSG with bogofilter. + +Bogofilter is a Bayesian spam filtering program. Get it from your +local distribution or from http://bogofilter.sourceforge.net/. + +Bogofilter is taught by running: + + bogofilter -n < good-message + +on every good message, and + + bogofilter -s < spam-message + +on every spam message. This is called a full training; three other +training methods are described in the FAQ that is distributed with +bogofilter. Note that most Bayesian filters need 1000 to 5000 of each +type of message to start doing a good job. + +To use bogofilter, add the following recipes to \".procmailrc\": + + PATH=$PATH:/usr/bin/mh + MAILDIR=$HOME/`mhparam Path` + + # Fight spam with bogofilter. + :0fw + | bogofilter -3 -e -p + + :0: + * ^X-Bogosity: Yes, tests=bogofilter + spam/. + + :0: + * ^X-Bogosity: Unsure, tests=bogofilter + spam/unsure/. + +If bogofilter classifies a message incorrectly, or is unsure, you can +use the MH-E commands \\[mh-junk-blacklist] and \\[mh-junk-whitelist] +to update bogofilter's training. + +The \"Bogofilter FAQ\" suggests that you run the following +occasionally to shrink the database: + + bogoutil -d wordlist.db | bogoutil -l wordlist.db.new + mv wordlist.db wordlist.db.prv + mv wordlist.db.new wordlist.db + +The \"Bogofilter tuning HOWTO\" describes how you can fine-tune Bogofilter. + +\(fn MSG)" nil nil) + +(autoload 'mh-bogofilter-whitelist "mh-junk" "\ +Whitelist MSG with bogofilter. + +See `mh-bogofilter-blacklist' for more information. + +\(fn MSG)" nil nil) + +(autoload 'mh-spamprobe-blacklist "mh-junk" "\ +Blacklist MSG with SpamProbe. + +SpamProbe is a Bayesian spam filtering program. Get it from your local +distribution or from http://spamprobe.sourceforge.net. + +To use SpamProbe, add the following recipes to \".procmailrc\": + + PATH=$PATH:/usr/bin/mh + MAILDIR=$HOME/`mhparam Path` + + # Fight spam with SpamProbe. + :0 + SCORE=| spamprobe receive + + :0 wf + | formail -I \"X-SpamProbe: $SCORE\" + + :0: + *^X-SpamProbe: SPAM + spam/. + +If SpamProbe classifies a message incorrectly, you can use the +MH-E commands \\[mh-junk-blacklist] and \\[mh-junk-whitelist] to +update SpamProbe's training. + +\(fn MSG)" nil nil) + +(autoload 'mh-spamprobe-whitelist "mh-junk" "\ +Whitelist MSG with SpamProbe. + +See `mh-spamprobe-blacklist' for more information. + +\(fn MSG)" nil nil) + +;;;*** + +;;;### (autoloads (mh-letter-toggle-header-field-display-button mh-complete-word +;;;;;; mh-position-on-field mh-letter-next-header-field mh-yank-cur-msg +;;;;;; mh-insert-signature mh-letter-mode) "mh-letter" "mh-letter.el" +;;;;;; (19005 47398)) +;;; Generated autoloads from mh-letter.el + +(autoload 'mh-letter-mode "mh-letter" "\ +Mode for composing letters in MH-E\\. + +When you have finished composing, type \\[mh-send-letter] to send +the message using the MH mail handling system. + +There are two types of tags used by MH-E when composing MIME +messages: MML and MH. The option `mh-compose-insertion' controls +what type of tags are inserted by MH-E commands. These tags can +be converted to MIME body parts by running \\[mh-mh-to-mime] for +MH-style directives or \\[mh-mml-to-mime] for MML tags. + +Options that control this mode can be changed with +\\[customize-group]; specify the \"mh-compose\" group. + +When a message is composed, the hooks `text-mode-hook', +`mail-mode-hook', and `mh-letter-mode-hook' are run (in that +order). + +\\{mh-letter-mode-map} + +\(fn)" t nil) + +(autoload 'mh-insert-signature "mh-letter" "\ +Insert signature in message. + +This command inserts your signature at the current cursor location. + +By default, the text of your signature is taken from the file +\"~/.signature\". You can read from other sources by changing the +option `mh-signature-file-name'. + +A signature separator (\"-- \") will be added if the signature block +does not contain one and `mh-signature-separator-flag' is on. + +The hook `mh-insert-signature-hook' is run after the signature is +inserted. Hook functions may access the actual name of the file or the +function used to insert the signature with `mh-signature-file-name'. + +The signature can also be inserted using Identities (see +`mh-identity-list'). + +In a program, you can pass in a signature FILE. + +\(fn &optional FILE)" t nil) + +(autoload 'mh-yank-cur-msg "mh-letter" "\ +Insert the current message into the draft buffer. + +It is often useful to insert a snippet of text from a letter that +someone mailed to provide some context for your reply. This +command does this by adding an attribution, yanking a portion of +text from the message to which you're replying, and inserting +`mh-ins-buf-prefix' (`> ') before each line. + +The attribution consists of the sender's name and email address +followed by the content of the option +`mh-extract-from-attribution-verb'. + +You can also turn on the option +`mh-delete-yanked-msg-window-flag' to delete the window +containing the original message after yanking it to make more +room on your screen for your reply. + +You can control how the message to which you are replying is +yanked into your reply using `mh-yank-behavior'. + +If this isn't enough, you can gain full control over the +appearance of the included text by setting `mail-citation-hook' +to a function that modifies it. For example, if you set this hook +to `trivial-cite' (which is NOT part of Emacs), set +`mh-yank-behavior' to \"Body and Header\" (see URL +`http://shasta.cs.uiuc.edu/~lrclause/tc.html'). + +Note that if `mail-citation-hook' is set, `mh-ins-buf-prefix' is +not inserted. If the option `mh-yank-behavior' is set to one of +the supercite flavors, the hook `mail-citation-hook' is ignored +and `mh-ins-buf-prefix' is not inserted. + +\(fn)" t nil) + +(autoload 'mh-letter-next-header-field "mh-letter" "\ +Cycle to the next header field. +If we are at the last header field go to the start of the message +body. + +\(fn)" nil nil) + +(autoload 'mh-position-on-field "mh-letter" "\ +Move to the end of the FIELD in the header. +Move to end of entire header if FIELD not found. +Returns non-nil if FIELD was found. +The optional second arg is for pre-version 4 compatibility and is +IGNORED. + +\(fn FIELD &optional IGNORED)" nil nil) + +(autoload 'mh-complete-word "mh-letter" "\ +Complete WORD from CHOICES. +Any match found replaces the text from BEGIN to END. + +\(fn WORD CHOICES BEGIN END)" nil nil) + +(autoload 'mh-letter-toggle-header-field-display-button "mh-letter" "\ +Toggle header field display at location of EVENT. +This function does the same thing as +`mh-letter-toggle-header-field-display' except that it is +callable from a mouse button. + +\(fn EVENT)" t nil) + +;;;*** + +;;;### (autoloads (mh-narrow-to-to mh-narrow-to-subject mh-narrow-to-range +;;;;;; mh-narrow-to-from mh-narrow-to-cc mh-delete-subject-or-thread +;;;;;; mh-delete-subject) "mh-limit" "mh-limit.el" (19005 47398)) +;;; Generated autoloads from mh-limit.el + +(autoload 'mh-delete-subject "mh-limit" "\ +Delete messages with same subject\\. + +To delete messages faster, you can use this command to delete all +the messages with the same subject as the current message. This +command puts these messages in a sequence named \"subject\". You +can undo this action by using \\[mh-undo] with a prefix argument +and then specifying the \"subject\" sequence. + +\(fn)" t nil) + +(autoload 'mh-delete-subject-or-thread "mh-limit" "\ +Delete messages with same subject or thread\\. + +To delete messages faster, you can use this command to delete all +the messages with the same subject as the current message. This +command puts these messages in a sequence named \"subject\". You +can undo this action by using \\[mh-undo] with a prefix argument +and then specifying the \"subject\" sequence. + +However, if the buffer is displaying a threaded view of the +folder then this command behaves like \\[mh-thread-delete]. + +\(fn)" t nil) + +(autoload 'mh-narrow-to-cc "mh-limit" "\ +Limit to messages with the same \"Cc:\" field. +With a prefix argument, edit PICK-EXPR. + +Use \\\\[mh-widen] to undo this command. + +\(fn &optional PICK-EXPR)" t nil) + +(autoload 'mh-narrow-to-from "mh-limit" "\ +Limit to messages with the same \"From:\" field. +With a prefix argument, edit PICK-EXPR. + +Use \\\\[mh-widen] to undo this command. + +\(fn &optional PICK-EXPR)" t nil) + +(autoload 'mh-narrow-to-range "mh-limit" "\ +Limit to RANGE. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +Use \\\\[mh-widen] to undo this command. + +\(fn RANGE)" t nil) + +(autoload 'mh-narrow-to-subject "mh-limit" "\ +Limit to messages with same subject. +With a prefix argument, edit PICK-EXPR. +The string Re: is removed from the search. + +Use \\\\[mh-widen] to undo this command. + +\(fn &optional PICK-EXPR)" t nil) + +(autoload 'mh-narrow-to-to "mh-limit" "\ +Limit to messages with the same \"To:\" field. +With a prefix argument, edit PICK-EXPR. + +Use \\\\[mh-widen] to undo this command. + +\(fn &optional PICK-EXPR)" t nil) + +;;;*** + +;;;### (autoloads (mh-destroy-postponed-handles mh-mime-cleanup mh-have-file-command +;;;;;; mh-file-mime-type mh-mh-directive-present-p mh-mml-tag-present-p +;;;;;; mh-mml-unsecure-message mh-mml-to-mime mh-mml-secure-message-signencrypt +;;;;;; mh-mml-secure-message-sign mh-mml-secure-message-encrypt +;;;;;; mh-mh-to-mime-undo mh-mh-to-mime mh-mh-compose-external-type +;;;;;; mh-mh-compose-external-compressed-tar mh-mh-compose-anon-ftp +;;;;;; mh-compose-insertion mh-mml-forward-message mh-compose-forward +;;;;;; mh-display-emphasis mh-display-smileys mh-add-missing-mime-version-header +;;;;;; mh-goto-next-button mh-mime-display mh-decode-message-header +;;;;;; mh-toggle-mime-buttons mh-toggle-mh-decode-mime-flag mh-mime-save-parts +;;;;;; mh-folder-toggle-mime-part mh-folder-save-mime-part mh-folder-inline-mime-part +;;;;;; mh-display-with-external-viewer mh-buffer-data) "mh-mime" +;;;;;; "mh-mime.el" (19005 47398)) +;;; Generated autoloads from mh-mime.el + +(autoload 'mh-buffer-data "mh-mime" "\ +Convenience macro to get the MIME data structures of the current buffer. + +\(fn)" nil (quote macro)) + +(autoload 'mh-display-with-external-viewer "mh-mime" "\ +View attachment externally. + +If Emacs does not know how to view an attachment, you could save +it into a file and then run some program to open it. It is +easier, however, to launch the program directly from MH-E with +this command. While you'll most likely use this to view +spreadsheets and documents, it is also useful to use your browser +to view HTML attachments with higher fidelity than what Emacs can +provide. + +This command displays the attachment associated with the button +under the cursor. If the cursor is not located over a button, +then the cursor first moves to the next button, wrapping to the +beginning of the message if necessary. You can provide a numeric +prefix argument PART-INDEX to view the attachment labeled with +that number. + +This command tries to provide a reasonable default for the viewer +by calling the Emacs function `mailcap-mime-info'. This function +usually reads the file \"/etc/mailcap\". + +\(fn PART-INDEX)" t nil) + +(autoload 'mh-folder-inline-mime-part "mh-mime" "\ +Show attachment verbatim. + +You can view the raw contents of an attachment with this command. +This command displays (or hides) the contents of the attachment +associated with the button under the cursor verbatim. If the +cursor is not located over a button, then the cursor first moves +to the next button, wrapping to the beginning of the message if +necessary. + +You can also provide a numeric prefix argument PART-INDEX to view +the attachment labeled with that number. + +\(fn PART-INDEX)" t nil) + +(autoload 'mh-folder-save-mime-part "mh-mime" "\ +Save (output) attachment. + +This command saves the attachment associated with the button under the +cursor. If the cursor is not located over a button, then the cursor +first moves to the next button, wrapping to the beginning of the +message if necessary. + +You can also provide a numeric prefix argument PART-INDEX to save the +attachment labeled with that number. + +This command prompts you for a filename and suggests a specific name +if it is available. + +\(fn PART-INDEX)" t nil) + +(autoload 'mh-folder-toggle-mime-part "mh-mime" "\ +View attachment. + +This command displays (or hides) the attachment associated with +the button under the cursor. If the cursor is not located over a +button, then the cursor first moves to the next button, wrapping +to the beginning of the message if necessary. This command has +the advantage over related commands of working from the MH-Folder +buffer. + +You can also provide a numeric prefix argument PART-INDEX to view +the attachment labeled with that number. If Emacs does not know +how to display the attachment, then Emacs offers to save the +attachment in a file. + +\(fn PART-INDEX)" t nil) + +(autoload 'mh-mime-save-parts "mh-mime" "\ +Save attachments. + +You can save all of the attachments at once with this command. +The attachments are saved in the directory specified by the +option `mh-mime-save-parts-default-directory' unless you use a +prefix argument PROMPT in which case you are prompted for the +directory. These directories may be superseded by MH profile +components, since this function calls on \"mhstore\" (\"mhn\") to +do the work. + +\(fn PROMPT)" t nil) + +(autoload 'mh-toggle-mh-decode-mime-flag "mh-mime" "\ +Toggle the value of `mh-decode-mime-flag'. + +\(fn)" t nil) + +(autoload 'mh-toggle-mime-buttons "mh-mime" "\ +Toggle option `mh-display-buttons-for-inline-parts-flag'. + +\(fn)" t nil) + +(autoload 'mh-decode-message-header "mh-mime" "\ +Decode RFC2047 encoded message header fields. + +\(fn)" nil nil) + +(autoload 'mh-mime-display "mh-mime" "\ +Display (and possibly decode) MIME handles. +Optional argument, PRE-DISSECTED-HANDLES is a list of MIME +handles. If present they are displayed otherwise the buffer is +parsed and then displayed. + +\(fn &optional PRE-DISSECTED-HANDLES)" nil nil) + +(autoload 'mh-goto-next-button "mh-mime" "\ +Search for next button satisfying criterion. + +If BACKWARD-FLAG is non-nil search backward in the buffer for a mime +button. +If CRITERION is a function or a symbol which has a function binding +then that function must return non-nil at the button we stop. + +\(fn BACKWARD-FLAG &optional CRITERION)" nil nil) + +(autoload 'mh-add-missing-mime-version-header "mh-mime" "\ +Some mail programs don't put a MIME-Version header. +I have seen this only in spam, so maybe we shouldn't fix +this ;-) + +\(fn)" nil nil) + +(autoload 'mh-display-smileys "mh-mime" "\ +Display smileys. + +\(fn)" nil nil) + +(autoload 'mh-display-emphasis "mh-mime" "\ +Display graphical emphasis. + +\(fn)" nil nil) + +(autoload 'mh-compose-forward "mh-mime" "\ +Add tag to forward a message. + +You are prompted for a content DESCRIPTION, the name of the +FOLDER in which the messages to forward are located, and a RANGE +of messages, which defaults to the current message in that +folder. Check the documentation of `mh-interactive-range' to see +how RANGE is read in interactive use. + +The option `mh-compose-insertion' controls what type of tags are inserted. + +\(fn &optional DESCRIPTION FOLDER RANGE)" t nil) + +(autoload 'mh-mml-forward-message "mh-mime" "\ +Forward a message as attachment. + +The function will prompt the user for a DESCRIPTION, a FOLDER and +MESSAGE number. + +\(fn DESCRIPTION FOLDER MESSAGE)" nil nil) + +(autoload 'mh-compose-insertion "mh-mime" "\ +Add tag to include a file such as an image or sound. + +You are prompted for the filename containing the object, the +media type if it cannot be determined automatically, and a +content description. If you're using MH-style directives, you +will also be prompted for additional attributes. + +The option `mh-compose-insertion' controls what type of tags are +inserted. Optional argument INLINE means make it an inline +attachment. + +\(fn &optional INLINE)" t nil) + +(autoload 'mh-mh-compose-anon-ftp "mh-mime" "\ +Add tag to include anonymous ftp reference to a file. + +You can have your message initiate an \"ftp\" transfer when the +recipient reads the message. You are prompted for the remote HOST +and FILENAME, the media TYPE, and the content DESCRIPTION. + +See also \\[mh-mh-to-mime]. + +\(fn HOST FILENAME TYPE DESCRIPTION)" t nil) + +(autoload 'mh-mh-compose-external-compressed-tar "mh-mime" "\ +Add tag to include anonymous ftp reference to a compressed tar file. + +In addition to retrieving the file via anonymous \"ftp\" as per +the command \\[mh-mh-compose-anon-ftp], the file will also be +uncompressed and untarred. You are prompted for the remote HOST +and FILENAME and the content DESCRIPTION. + +See also \\[mh-mh-to-mime]. + +\(fn HOST FILENAME DESCRIPTION)" t nil) + +(autoload 'mh-mh-compose-external-type "mh-mime" "\ +Add tag to refer to a remote file. + +This command is a general utility for referencing external files. +In fact, all of the other commands that insert directives to +access external files call this command. You are prompted for the +ACCESS-TYPE, remote HOST and FILENAME, and content TYPE. If you +provide a prefix argument, you are also prompted for a content +DESCRIPTION, ATTRIBUTES, PARAMETERS, and a COMMENT. + +See also \\[mh-mh-to-mime]. + +\(fn ACCESS-TYPE HOST FILENAME TYPE &optional DESCRIPTION ATTRIBUTES PARAMETERS COMMENT)" t nil) + +(autoload 'mh-mh-to-mime "mh-mime" "\ +Compose MIME message from MH-style directives. + +Typically, you send a message with attachments just like any other +message. However, you may take a sneak preview of the MIME encoding if +you wish by running this command. + +If you wish to pass additional arguments to \"mhbuild\" (\"mhn\") +to affect how it builds your message, use the option +`mh-mh-to-mime-args'. For example, you can build a consistency +check into the message by setting `mh-mh-to-mime-args' to +\"-check\". The recipient of your message can then run \"mhbuild +-check\" on the message--\"mhbuild\" (\"mhn\") will complain if +the message has been corrupted on the way. This command only +consults this option when given a prefix argument EXTRA-ARGS. + +The hook `mh-mh-to-mime-hook' is called after the message has been +formatted. + +The effects of this command can be undone by running +\\[mh-mh-to-mime-undo]. + +\(fn &optional EXTRA-ARGS)" t nil) + +(autoload 'mh-mh-to-mime-undo "mh-mime" "\ +Undo effects of \\[mh-mh-to-mime]. + +It does this by reverting to a backup file. You are prompted to +confirm this action, but you can avoid the confirmation by adding +a prefix argument NOCONFIRM. + +\(fn NOCONFIRM)" t nil) + +(autoload 'mh-mml-secure-message-encrypt "mh-mime" "\ +Add tag to encrypt the message. + +A proper multipart message is created for you when you send the +message. Use the command \\[mh-mml-unsecure-message] to remove +this tag. Use a prefix argument METHOD to be prompted for one of +the possible security methods (see `mh-mml-method-default'). + +\(fn METHOD)" t nil) + +(autoload 'mh-mml-secure-message-sign "mh-mime" "\ +Add tag to sign the message. + +A proper multipart message is created for you when you send the +message. Use the command \\[mh-mml-unsecure-message] to remove +this tag. Use a prefix argument METHOD to be prompted for one of +the possible security methods (see `mh-mml-method-default'). + +\(fn METHOD)" t nil) + +(autoload 'mh-mml-secure-message-signencrypt "mh-mime" "\ +Add tag to encrypt and sign the message. + +A proper multipart message is created for you when you send the +message. Use the command \\[mh-mml-unsecure-message] to remove +this tag. Use a prefix argument METHOD to be prompted for one of +the possible security methods (see `mh-mml-method-default'). + +\(fn METHOD)" t nil) + +(autoload 'mh-mml-to-mime "mh-mime" "\ +Compose MIME message from MML tags. + +Typically, you send a message with attachments just like any +other message. However, you may take a sneak preview of the MIME +encoding if you wish by running this command. + +This action can be undone by running \\[undo]. + +\(fn)" t nil) + +(autoload 'mh-mml-unsecure-message "mh-mime" "\ +Remove any secure message tags. + +\(fn)" t nil) + +(autoload 'mh-mml-tag-present-p "mh-mime" "\ +Check if the current buffer has text which may be a MML tag. + +\(fn)" nil nil) + +(autoload 'mh-mh-directive-present-p "mh-mime" "\ +Check if the text between BEGIN and END might be a MH-style directive. +The optional argument BEGIN defaults to the beginning of the +buffer, while END defaults to the end of the buffer. + +\(fn &optional BEGIN END)" nil nil) + +(autoload 'mh-file-mime-type "mh-mime" "\ +Return MIME type of FILENAME from file command. +Returns nil if file command not on system. + +\(fn FILENAME)" nil nil) + +(autoload 'mh-have-file-command "mh-mime" "\ +Return t if 'file' command is on the system. +'file -i' is used to get MIME type of composition insertion. + +\(fn)" nil nil) + +(autoload 'mh-mime-cleanup "mh-mime" "\ +Free the decoded MIME parts. + +\(fn)" nil nil) + +(autoload 'mh-destroy-postponed-handles "mh-mime" "\ +Free MIME data for externally displayed MIME parts. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (mh-print-msg mh-ps-print-toggle-color mh-ps-print-toggle-faces +;;;;;; mh-ps-print-msg-file mh-ps-print-msg) "mh-print" "mh-print.el" +;;;;;; (19005 47398)) +;;; Generated autoloads from mh-print.el + +(autoload 'mh-ps-print-msg "mh-print" "\ +Print RANGE\\. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +This command will print inline text attachments but will not decrypt +messages. However, when a message is displayed in an MH-Show buffer, +then that buffer is used verbatim for printing with the caveat that +only text attachments, if opened inline, are printed. Therefore, +encrypted messages can be printed by showing and decrypting them +first. + +MH-E uses the \"ps-print\" package to do the printing, so you can +customize the printing further by going to the `ps-print' +customization group. This command does not use the options +`mh-lpr-command-format' or `mh-print-background-flag'. See also the +commands \\[mh-ps-print-toggle-color] and +\\[mh-ps-print-toggle-faces]. + +\(fn RANGE)" t nil) + +(autoload 'mh-ps-print-msg-file "mh-print" "\ +Print RANGE to FILE\\. + +Check the documentation of `mh-interactive-range' to see how RANGE is +read in interactive use. + +This command will print inline text attachments but will not decrypt +messages. However, when a message is displayed in an MH-Show buffer, +then that buffer is used verbatim for printing with the caveat that +only text attachments, if opened inline, are printed. Therefore, +encrypted messages can be printed by showing and decrypting them +first. + +MH-E uses the \"ps-print\" package to do the printing, so you can +customize the printing further by going to the `ps-print' +customization group. This command does not use the options +`mh-lpr-command-format' or `mh-print-background-flag'. See also the +commands \\[mh-ps-print-toggle-color] and +\\[mh-ps-print-toggle-faces]. + +\(fn RANGE FILE)" t nil) + +(autoload 'mh-ps-print-toggle-faces "mh-print" "\ +Toggle whether printing is done with faces or not. + +When faces are enabled, the printed message will look very +similar to the message in the MH-Show buffer. + +\(fn)" t nil) + +(autoload 'mh-ps-print-toggle-color "mh-print" "\ +Toggle whether color is used in printing messages. + +Colors are emulated on black-and-white printers with shades of +gray. This might produce illegible output, even if your screen +colors only use shades of gray. If this is the case, try using +this command to toggle between color, no color, and a black and +white representation of the colors and see which works best. You +change this setting permanently by customizing the option +`ps-print-color-p'. + +\(fn)" t nil) + +(autoload 'mh-print-msg "mh-print" "\ +Print RANGE the old fashioned way\\. + +The message is formatted with \"mhl\" (see option +`mh-mhl-format-file') and printed with the \"lpr\" command (see +option `mh-lpr-command-format'). + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +Consider using \\[mh-ps-print-msg] instead. + +\(fn RANGE)" t nil) + +;;;*** + +;;;### (autoloads (mh-msg-num-width-to-column mh-msg-num-width mh-scan-format +;;;;;; mh-set-cmd-note mh-scan-msg-search-regexp mh-scan-msg-number-regexp) +;;;;;; "mh-scan" "mh-scan.el" (19005 47398)) +;;; Generated autoloads from mh-scan.el + +(autoload 'mh-scan-msg-number-regexp "mh-scan" "\ +Return value of variable `mh-scan-msg-number-regexp'. + +\(fn)" nil nil) + +(autoload 'mh-scan-msg-search-regexp "mh-scan" "\ +Return value of variable `mh-scan-msg-search-regexp'. + +\(fn)" nil nil) + +(autoload 'mh-set-cmd-note "mh-scan" "\ +Set `mh-cmd-note' to COLUMN. +Note that columns in Emacs start with 0. + +\(fn COLUMN)" nil nil) + +(autoload 'mh-scan-format "mh-scan" "\ +Return the output format argument for the scan program. + +\(fn)" nil nil) + +(autoload 'mh-msg-num-width "mh-scan" "\ +Return the width of the largest message number in this FOLDER. + +\(fn FOLDER)" nil nil) + +(autoload 'mh-msg-num-width-to-column "mh-scan" "\ +Return the column for notations given message number WIDTH. +Note that columns in Emacs start with 0. + +If `mh-scan-format-file' is set to \"Use MH-E scan Format\" this +means that either `mh-scan-format-mh' or `mh-scan-format-nmh' are +in use. This function therefore assumes that the first column is +empty (to provide room for the cursor), the following WIDTH +columns contain the message number, and the column for notations +comes after that. + +\(fn WIDTH)" nil nil) + +;;;*** + +;;;### (autoloads (mh-index-update-maps mh-index-read-data mh-index-delete-from-sequence +;;;;;; mh-index-add-to-sequence mh-create-sequence-map mh-index-create-sequences +;;;;;; mh-index-execute-commands mh-search-p mh-index-create-imenu-index +;;;;;; mh-index-delete-folder-headers mh-index-insert-folder-headers +;;;;;; mh-index-group-by-folder mh-index-visit-folder mh-index-previous-folder +;;;;;; mh-index-next-folder mh-index-sequenced-messages mh-index-ticked-messages +;;;;;; mh-index-new-messages mh-search) "mh-search" "mh-search.el" +;;;;;; (19005 47398)) +;;; Generated autoloads from mh-search.el + +(autoload 'mh-search "mh-search" "\ +Search your MH mail. + +This command helps you find messages in your entire corpus of +mail. You can search for messages to or from a particular person +or about a particular subject. In fact, you can also search for +messages containing selected strings in any arbitrary header +field or any string found within the messages. + +Out of the box, MH-E uses \"pick\" to find messages. With a +little extra effort, you can set an indexing program which +rewards you with extremely quick results. The drawback is that +sometimes the index does not contain the words you're looking +for. You can still use \"pick\" in these situations. + +You are prompted for the FOLDER to search. This can be \"all\" to +search all folders. Note that the search works recursively on the +listed folder. + +Next, an MH-Search buffer appears where you can enter search +criteria SEARCH-REGEXP. + + From: + To: + Cc: + Date: + Subject: + -------- + +Edit this template by entering your search criteria in an +appropriate header field that is already there, or create a new +field yourself. If the string you're looking for could be +anywhere in a message, then place the string underneath the row +of dashes. + +As an example, let's say that we want to find messages from +Ginnean about horseback riding in the Kosciusko National +Park (Australia) during January, 1994. Normally we would start +with a broad search and narrow it down if necessary to produce a +manageable amount of data, but we'll cut to the chase and create +a fairly restrictive set of criteria as follows:\\ + + From: ginnean + To: + Cc: + Date: Jan 1994 + Subject: + -------- + horse + kosciusko + +As with MH-Letter mode, MH-Search provides commands like +\\[mh-to-field] to help you fill in the blanks.\\ + +If you find that you do the same thing over and over when editing +the search template, you may wish to bind some shortcuts to keys. +This can be done with the variable `mh-search-mode-hook', which is +called when \\[mh-search] is run on a new pattern.\\ + +To perform the search, type \\[mh-index-do-search]. + +Sometimes you're searching for text that is either not indexed, +or hasn't been indexed yet. In this case you can override the +default method with the pick method by running the command +\\[mh-pick-do-search]. + +The messages that are found are put in a temporary sub-folder of +\"+mhe-index\" and are displayed in an MH-Folder buffer. This +buffer is special because it displays messages from multiple +folders; each set of messages from a given folder has a heading +with the folder name.\\ + +The appearance of the heading can be modified by customizing the +face `mh-search-folder'. You can jump back and forth between the +headings using the commands \\[mh-index-next-folder] and +\\[mh-index-previous-folder]. + +In addition, the command \\[mh-index-visit-folder] can be used to +visit the folder of the message at point. Initially, only the +messages that matched the search criteria are displayed in the +folder. While the temporary buffer has its own set of message +numbers, the actual messages numbers are shown in the visited +folder. Thus, the command \\[mh-index-visit-folder] is useful to +find the actual message number of an interesting message, or to +view surrounding messages with the command \\[mh-rescan-folder]. + +Because this folder is temporary, you'll probably get in the +habit of killing it when you're done with \\[mh-kill-folder]. + +You can regenerate the results by running this command with a +prefix argument REDO-SEARCH-FLAG. + +Note: This command uses an \"X-MHE-Checksum:\" header field to +cache the MD5 checksum of a message. This means that if an +incoming message already contains an \"X-MHE-Checksum:\" field, +that message might not be found by this command. The following +\"procmail\" recipe avoids this problem by renaming the existing +header field: + + :0 wf + | formail -R \"X-MHE-Checksum\" \"X-Old-MHE-Checksum\" + +Configuring Indexed Searches + +The command \\[mh-search] runs the command defined by the option +`mh-search-program'. The default value is \"Auto-detect\" which +means that MH-E will automatically choose one of \"swish++\", +\"swish-e\", \"mairix\", \"namazu\", \"pick\" and \"grep\" in +that order. If, for example, you have both \"swish++\" and +\"mairix\" installed and you want to use \"mairix\", then you can +set this option to \"mairix\". + +The documentation for the following commands describe how to set +up the various indexing programs to use with MH-E. + + - `mh-swish++-execute-search' + - `mh-swish-execute-search' + - `mh-mairix-execute-search' + - `mh-namazu-execute-search' + - `mh-pick-execute-search' + - `mh-grep-execute-search' + +In a program, if FOLDER is \"+\" or nil, then mail in all folders +are searched. Optional argument WINDOW-CONFIG stores the window +configuration that will be restored after the user quits the +folder containing the index search results. + +\(fn FOLDER SEARCH-REGEXP &optional REDO-SEARCH-FLAG WINDOW-CONFIG)" t nil) + +(autoload 'mh-index-new-messages "mh-search" "\ +Display unseen messages. + +If you use a program such as \"procmail\" to use \"rcvstore\" to file +your incoming mail automatically, you can display new, unseen, +messages using this command. All messages in the \"unseen\" +sequence from the folders in `mh-new-messages-folders' are +listed. + +With a prefix argument, enter a space-separated list of FOLDERS, +or nothing to search all folders. + +\(fn FOLDERS)" t nil) + +(autoload 'mh-index-ticked-messages "mh-search" "\ +Display ticked messages. + +All messages in `mh-tick-seq' from the folders in +`mh-ticked-messages-folders' are listed. + +With a prefix argument, enter a space-separated list of FOLDERS, +or nothing to search all folders. + +\(fn FOLDERS)" t nil) + +(autoload 'mh-index-sequenced-messages "mh-search" "\ +Display messages in any sequence. + +All messages from the FOLDERS in `mh-new-messages-folders' in the +SEQUENCE you provide are listed. With a prefix argument, enter a +space-separated list of folders at the prompt, or nothing to +search all folders. + +\(fn FOLDERS SEQUENCE)" t nil) + +(autoload 'mh-index-next-folder "mh-search" "\ +Jump to the next folder marker. + +With non-nil optional argument BACKWARD-FLAG, jump to the previous +group of results. + +\(fn &optional BACKWARD-FLAG)" t nil) + +(autoload 'mh-index-previous-folder "mh-search" "\ +Jump to the previous folder marker. + +\(fn)" t nil) + +(autoload 'mh-index-visit-folder "mh-search" "\ +Visit original folder from where the message at point was found. + +\(fn)" t nil) + +(autoload 'mh-index-group-by-folder "mh-search" "\ +Partition the messages based on source folder. +Returns an alist with the folder names in the car and the cdr +being the list of messages originally from that folder. + +\(fn)" nil nil) + +(autoload 'mh-index-insert-folder-headers "mh-search" "\ +Annotate the search results with original folder names. + +\(fn)" nil nil) + +(autoload 'mh-index-delete-folder-headers "mh-search" "\ +Delete the folder headers. + +\(fn)" nil nil) + +(autoload 'mh-index-create-imenu-index "mh-search" "\ +Create alist of folder names and positions in index folder buffers. + +\(fn)" nil nil) + +(autoload 'mh-search-p "mh-search" "\ +Non-nil means that this folder was generated by searching. + +\(fn)" nil nil) + +(autoload 'mh-index-execute-commands "mh-search" "\ +Delete/refile the actual messages. +The copies in the searched folder are then deleted/refiled to get +the desired result. Before deleting the messages we make sure +that the message being deleted is identical to the one that the +user has marked in the index buffer. + +\(fn)" nil nil) + +(autoload 'mh-index-create-sequences "mh-search" "\ +Mirror sequences present in source folders in index folder. + +\(fn)" nil nil) + +(autoload 'mh-create-sequence-map "mh-search" "\ +Return a map from msg number to list of sequences in which it is present. +SEQ-LIST is an assoc list whose keys are sequence names and whose +cdr is the list of messages in that sequence. + +\(fn SEQ-LIST)" nil nil) + +(autoload 'mh-index-add-to-sequence "mh-search" "\ +Add to SEQ the messages in the list MSGS. +This function updates the source folder sequences. Also makes an +attempt to update the source folder buffer if we have it open. + +\(fn SEQ MSGS)" nil nil) + +(autoload 'mh-index-delete-from-sequence "mh-search" "\ +Delete from SEQ the messages in MSGS. +This function updates the source folder sequences. Also makes an +attempt to update the source folder buffer if present. + +\(fn SEQ MSGS)" nil nil) + +(autoload 'mh-index-read-data "mh-search" "\ +Read index data from file. + +\(fn)" nil nil) + +(autoload 'mh-index-update-maps "mh-search" "\ +Annotate all as yet unannotated messages in FOLDER with their MD5 hash. +As a side effect msg -> checksum map is updated. Optional +argument ORIGIN-MAP is a hashtable which maps each message in the +index folder to the original folder and message from whence it +was copied. If present the checksum -> (origin-folder, +origin-index) map is updated too. + +\(fn FOLDER &optional ORIGIN-MAP)" nil nil) + +;;;*** + +;;;### (autoloads (mh-remove-all-notation mh-notate-user-sequences +;;;;;; mh-notate-deleted-and-refiled mh-remove-cur-notation mh-notate-cur +;;;;;; mh-notate mh-read-folder-sequences mh-parse-flist-output-line +;;;;;; mh-translate-range mh-range-to-msg-list mh-read-range mh-interactive-range +;;;;;; mh-valid-view-change-operation-p mh-add-msgs-to-seq mh-undefine-sequence +;;;;;; mh-define-sequence mh-seq-to-msgs mh-find-seq mh-valid-seq-p +;;;;;; mh-read-seq-default mh-widen mh-toggle-tick mh-put-msg-in-seq +;;;;;; mh-narrow-to-tick mh-narrow-to-seq mh-msg-is-in-seq mh-list-sequences +;;;;;; mh-delete-seq mh-delete-msg-from-seq mh-catchup) "mh-seq" +;;;;;; "mh-seq.el" (19005 47398)) +;;; Generated autoloads from mh-seq.el + +(autoload 'mh-catchup "mh-seq" "\ +Delete RANGE from the \"unseen\" sequence. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-delete-msg-from-seq "mh-seq" "\ +Delete RANGE from SEQUENCE. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +In a program, non-nil INTERNAL-FLAG means do not inform MH of the +change. + +\(fn RANGE SEQUENCE &optional INTERNAL-FLAG)" t nil) + +(autoload 'mh-delete-seq "mh-seq" "\ +Delete SEQUENCE. + +You are prompted for the sequence to delete. Note that this +deletes only the sequence, not the messages in the sequence. If +you want to delete the messages, use \"\\[universal-argument] +\\[mh-delete-msg]\". + +\(fn SEQUENCE)" t nil) + +(autoload 'mh-list-sequences "mh-seq" "\ +List all sequences in folder. + +The list appears in a buffer named \"*MH-E Sequences*\". + +\(fn)" t nil) + +(autoload 'mh-msg-is-in-seq "mh-seq" "\ +Display the sequences in which the current message appears. + +Use a prefix argument to display the sequences in which another +MESSAGE appears. + +\(fn MESSAGE)" t nil) + +(autoload 'mh-narrow-to-seq "mh-seq" "\ +Restrict display to messages in SEQUENCE. + +You are prompted for the name of the sequence. What this command +does is show only those messages that are in the selected +sequence in the MH-Folder buffer. In addition, it limits further +MH-E searches to just those messages. + +When you want to widen the view to all your messages again, use +\\[mh-widen]. + +\(fn SEQUENCE)" t nil) + +(autoload 'mh-narrow-to-tick "mh-seq" "\ +Limit to ticked messages. + +What this command does is show only those messages that are in +the \"tick\" sequence (which you can customize via the +`mh-tick-seq' option) in the MH-Folder buffer. In addition, it +limits further MH-E searches to just those messages. When you +want to widen the view to all your messages again, use +\\[mh-widen]. + +\(fn)" t nil) + +(autoload 'mh-put-msg-in-seq "mh-seq" "\ +Add RANGE to SEQUENCE\\. + +Give this command a RANGE and you can add all the messages in a +sequence to another sequence (for example, +\"\\[universal-argument] \\[mh-put-msg-in-seq] SourceSequence RET +DestSequence RET\"). Check the documentation of +`mh-interactive-range' to see how RANGE is read in interactive +use. + +\(fn RANGE SEQUENCE)" t nil) + +(autoload 'mh-toggle-tick "mh-seq" "\ +Toggle tick mark of RANGE. + +This command adds messages to the \"tick\" sequence (which you can customize +via the option `mh-tick-seq'). This sequence can be viewed later with the +\\[mh-index-ticked-messages] command. + +Check the documentation of `mh-interactive-range' to see how RANGE is read in +interactive use. + +\(fn RANGE)" t nil) + +(autoload 'mh-widen "mh-seq" "\ +Remove last restriction. + +Each limit or sequence restriction can be undone in turn with +this command. Give this command a prefix argument ALL-FLAG to +remove all limits and sequence restrictions. + +\(fn &optional ALL-FLAG)" t nil) + +(autoload 'mh-read-seq-default "mh-seq" "\ +Read and return sequence name with default narrowed or previous sequence. +PROMPT is the prompt to use when reading. If NOT-EMPTY is non-nil +then a non-empty sequence is read. + +\(fn PROMPT NOT-EMPTY)" nil nil) + +(autoload 'mh-valid-seq-p "mh-seq" "\ +Return non-nil if NAME is a valid MH sequence name. + +\(fn NAME)" nil nil) + +(autoload 'mh-find-seq "mh-seq" "\ +Return sequence NAME. + +\(fn NAME)" nil nil) + +(autoload 'mh-seq-to-msgs "mh-seq" "\ +Return a list of the messages in SEQ. + +\(fn SEQ)" nil nil) + +(autoload 'mh-define-sequence "mh-seq" "\ +Define the SEQ to contain the list of MSGS. +Do not mark pseudo-sequences or empty sequences. +Signals an error if SEQ is an invalid name. + +\(fn SEQ MSGS)" nil nil) + +(autoload 'mh-undefine-sequence "mh-seq" "\ +Remove from the SEQ the list of MSGS. + +\(fn SEQ MSGS)" nil nil) + +(autoload 'mh-add-msgs-to-seq "mh-seq" "\ +Add MSGS to SEQ. + +Remove duplicates and keep sequence sorted. If optional +INTERNAL-FLAG is non-nil, do not mark the message in the scan +listing or inform MH of the addition. + +If DONT-ANNOTATE-FLAG is non-nil then the annotations in the +folder buffer are not updated. + +\(fn MSGS SEQ &optional INTERNAL-FLAG DONT-ANNOTATE-FLAG)" nil nil) + +(autoload 'mh-valid-view-change-operation-p "mh-seq" "\ +Check if the view change operation can be performed. +OP is one of 'widen and 'unthread. + +\(fn OP)" nil nil) + +(autoload 'mh-interactive-range "mh-seq" "\ +Return interactive specification for message, sequence, range or region. +By convention, the name of this argument is RANGE. + +If variable `transient-mark-mode' is non-nil and the mark is active, +then this function returns a cons-cell of the region. + +If optional prefix argument is provided, then prompt for message range +with RANGE-PROMPT. A list of messages in that range is returned. + +If a MH range is given, say something like last:20, then a list +containing the messages in that range is returned. + +If DEFAULT non-nil then it is returned. + +Otherwise, the message number at point is returned. + +This function is usually used with `mh-iterate-on-range' in order to +provide a uniform interface to MH-E functions. + +\(fn RANGE-PROMPT &optional DEFAULT)" nil nil) + +(autoload 'mh-read-range "mh-seq" "\ +Read a message range with PROMPT. + +If FOLDER is non-nil then a range is read from that folder, otherwise +use `mh-current-folder'. + +If DEFAULT is a string then use that as default range to return. If +DEFAULT is nil then ask user with default answer a range based on the +sequences that seem relevant. Finally if DEFAULT is t, try to avoid +prompting the user. Unseen messages, if present, are returned. If the +folder has fewer than `mh-large-folder' messages then \"all\" messages +are returned. Finally as a last resort prompt the user. + +If EXPAND-FLAG is non-nil then a list of message numbers corresponding +to the input is returned. If this list is empty then an error is +raised. If EXPAND-FLAG is nil just return the input string. In this +case we don't check if the range is empty. + +If ASK-FLAG is non-nil, then the user is always queried for a range of +messages. If ASK-FLAG is nil, then the function checks if the unseen +sequence is non-empty. If that is the case, `mh-unseen-seq', or the +list of messages in it depending on the value of EXPAND, is returned. +Otherwise if the folder has fewer than `mh-large-folder' messages then +the list of messages corresponding to \"all\" is returned. If neither +of the above holds then as a last resort the user is queried for a +range of messages. + +If NUMBER-AS-RANGE-FLAG is non-nil, then if a number, N is read as +input, it is interpreted as the range \"last:N\". + +This function replaces the existing function `mh-read-msg-range'. +Calls to: + + (mh-read-msg-range folder flag) + +should be replaced with: + + (mh-read-range \"Suitable prompt\" folder t nil flag + mh-interpret-number-as-range-flag) + +\(fn PROMPT &optional FOLDER DEFAULT EXPAND-FLAG ASK-FLAG NUMBER-AS-RANGE-FLAG)" nil nil) + +(autoload 'mh-range-to-msg-list "mh-seq" "\ +Return a list of messages for RANGE. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use. + +\(fn RANGE)" nil nil) + +(autoload 'mh-translate-range "mh-seq" "\ +In FOLDER, translate the string EXPR to a list of messages numbers. + +\(fn FOLDER EXPR)" nil nil) + +(autoload 'mh-parse-flist-output-line "mh-seq" "\ +Parse LINE to generate folder name, unseen messages and total messages. +If CURRENT-FOLDER is non-nil then it contains the current folder +name and it is used to avoid problems in corner cases involving +folders whose names end with a '+' character. + +\(fn LINE &optional CURRENT-FOLDER)" nil nil) + +(autoload 'mh-read-folder-sequences "mh-seq" "\ +Read and return the predefined sequences for a FOLDER. +If SAVE-REFILES is non-nil, then keep the sequences +that note messages to be refiled. + +\(fn FOLDER SAVE-REFILES)" nil nil) + +(autoload 'mh-notate "mh-seq" "\ +Mark MSG with the character NOTATION at position OFFSET. +Null MSG means the message at cursor. +If NOTATION is nil then no change in the buffer occurs. + +\(fn MSG NOTATION OFFSET)" nil nil) + +(autoload 'mh-notate-cur "mh-seq" "\ +Mark the MH sequence cur. +In addition to notating the current message with `mh-note-cur' +the function uses `overlay-arrow-position' to put a marker in the +fringe. + +\(fn)" nil nil) + +(autoload 'mh-remove-cur-notation "mh-seq" "\ +Remove old cur notation. + +\(fn)" nil nil) + +(autoload 'mh-notate-deleted-and-refiled "mh-seq" "\ +Notate messages marked for deletion or refiling. +Messages to be deleted are given by `mh-delete-list' while +messages to be refiled are present in `mh-refile-list'. + +\(fn)" nil nil) + +(autoload 'mh-notate-user-sequences "mh-seq" "\ +Mark user-defined sequences in RANGE. + +Check the documentation of `mh-interactive-range' to see how +RANGE is read in interactive use; if nil all messages are +notated. + +\(fn &optional RANGE)" nil nil) + +(autoload 'mh-remove-all-notation "mh-seq" "\ +Remove all notations on all scan lines that MH-E introduces. + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (mh-gnus-article-highlight-citation mh-show-addr +;;;;;; mh-show-mode mh-show-font-lock-keywords-with-cite mh-show-font-lock-keywords +;;;;;; mh-invalidate-show-buffer mh-clean-msg-header mh-display-msg +;;;;;; mh-start-of-uncleaned-message mh-showing-mode mh-maybe-show +;;;;;; mh-show-preferred-alternative mh-header-display mh-show) +;;;;;; "mh-show" "mh-show.el" (19005 47398)) +;;; Generated autoloads from mh-show.el + +(autoload 'mh-show "mh-show" "\ +Display message\\. + +If the message under the cursor is already displayed, this command +scrolls to the beginning of the message. MH-E normally hides a lot of +the superfluous header fields that mailers add to a message, but if +you wish to see all of them, use the command \\[mh-header-display]. + +Two hooks can be used to control how messages are displayed. The +first hook, `mh-show-mode-hook', is called early on in the +process of the message display. It is usually used to perform +some action on the message's content. The second hook, +`mh-show-hook', is the last thing called after messages are +displayed. It's used to affect the behavior of MH-E in general or +when `mh-show-mode-hook' is too early. + +From a program, optional argument MESSAGE can be used to display an +alternative message. The optional argument REDISPLAY-FLAG forces the +redisplay of the message even if the show buffer was already +displaying the correct message. + +See the \"mh-show\" customization group for a litany of options that +control what displayed messages look like. + +\(fn &optional MESSAGE REDISPLAY-FLAG)" t nil) + +(autoload 'mh-header-display "mh-show" "\ +Display message with all header fields\\. + +Use the command \\[mh-show] to show the message normally again. + +\(fn)" t nil) + +(autoload 'mh-show-preferred-alternative "mh-show" "\ +Display message with the default preferred alternative. +This is as if `mm-discouraged-alternatives' is set to nil. + +Use the command \\[mh-show] to show the message normally again. + +\(fn)" t nil) + +(autoload 'mh-maybe-show "mh-show" "\ +Display message at cursor, but only if in show mode. +If optional arg MSG is non-nil, display that message instead. + +\(fn &optional MSG)" nil nil) + +(autoload 'mh-showing-mode "mh-show" "\ +Change whether messages should be displayed. + +With ARG, display messages if ARG is positive, otherwise don't display them. + +\(fn &optional ARG)" nil nil) + +(autoload 'mh-start-of-uncleaned-message "mh-show" "\ +Position uninteresting headers off the top of the window. + +\(fn)" nil nil) + +(autoload 'mh-display-msg "mh-show" "\ +Display MSG-NUM of FOLDER-NAME. +Sets the current buffer to the show buffer. + +\(fn MSG-NUM FOLDER-NAME)" nil nil) + +(autoload 'mh-clean-msg-header "mh-show" "\ +Flush extraneous lines in message header. + +Header is cleaned from START to the end of the message header. +INVISIBLE-HEADERS contains a regular expression specifying lines +to delete from the header. VISIBLE-HEADERS contains a regular +expression specifying the lines to display. INVISIBLE-HEADERS is +ignored if VISIBLE-HEADERS is non-nil. + +\(fn START INVISIBLE-HEADERS VISIBLE-HEADERS)" nil nil) + +(autoload 'mh-invalidate-show-buffer "mh-show" "\ +Invalidate the show buffer so we must update it to use it. + +\(fn)" nil nil) + +(autoload 'mh-show-font-lock-keywords "mh-show" "\ +Return variable `mh-show-font-lock-keywords'. + +\(fn)" nil nil) + +(autoload 'mh-show-font-lock-keywords-with-cite "mh-show" "\ +Return variable `mh-show-font-lock-keywords-with-cite'. + +\(fn)" nil nil) + +(autoload 'mh-show-mode "mh-show" "\ +Major mode for showing messages in MH-E.\\ + +Email addresses and URLs in the message are highlighted if the +option `goto-address-highlight-p' is on, which it is by default. +To view the web page for a highlighted URL or to send a message +using a highlighted email address, use the middle mouse button or +\\[goto-address-at-point]. See Info node `(mh-e)Sending Mail' to +see how to configure Emacs to send the message using MH-E. + +The hook `mh-show-mode-hook' is called upon entry to this mode. + +See also `mh-folder-mode'. + +\\{mh-show-mode-map} + +\(fn)" t nil) + +(autoload 'mh-show-addr "mh-show" "\ +Use `goto-address'. + +\(fn)" nil nil) + +(autoload 'mh-gnus-article-highlight-citation "mh-show" "\ +Highlight cited text in current buffer using Gnus. + +\(fn)" t nil) + +;;;*** + +;;;### (autoloads (mh-speed-add-folder mh-speed-invalidate-map mh-speed-flists +;;;;;; mh-folder-speedbar-buttons) "mh-speed" "mh-speed.el" (19005 +;;;;;; 47398)) +;;; Generated autoloads from mh-speed.el + +(autoload 'mh-folder-speedbar-buttons "mh-speed" "\ +Interface function to create MH-E speedbar buffer. +BUFFER is the MH-E buffer for which the speedbar buffer is to be +created. + +\(fn BUFFER)" nil nil) + +(defalias 'mh-show-speedbar-buttons 'mh-folder-speedbar-buttons) + +(defalias 'mh-letter-speedbar-buttons 'mh-folder-speedbar-buttons) + +(autoload 'mh-speed-flists "mh-speed" "\ +Execute flists -recurse and update message counts. +If FORCE is non-nil the timer is reset. + +Any number of optional FOLDERS can be specified. If specified, +flists is run only for that one folder. + +\(fn FORCE &rest FOLDERS)" t nil) + +(autoload 'mh-speed-invalidate-map "mh-speed" "\ +Remove FOLDER from various optimization caches. + +\(fn FOLDER)" t nil) + +(autoload 'mh-speed-add-folder "mh-speed" "\ +Add FOLDER since it is being created. +The function invalidates the latest ancestor that is present. + +\(fn FOLDER)" nil nil) + +;;;*** + +;;;### (autoloads (mh-thread-forget-message mh-thread-add-spaces +;;;;;; mh-thread-find-msg-subject mh-thread-update-scan-line-map +;;;;;; mh-thread-print-scan-lines mh-thread-generate mh-thread-parse-scan-line +;;;;;; mh-thread-inc mh-toggle-threads mh-thread-refile mh-thread-previous-sibling +;;;;;; mh-thread-next-sibling mh-thread-delete mh-thread-ancestor) +;;;;;; "mh-thread" "mh-thread.el" (19005 47398)) +;;; Generated autoloads from mh-thread.el + +(autoload 'mh-thread-ancestor "mh-thread" "\ +Display ancestor of current message. + +If you do not care for the way a particular thread has turned, +you can move up the chain of messages with this command. This +command can also take a prefix argument THREAD-ROOT-FLAG to jump +to the message that started everything. + +\(fn &optional THREAD-ROOT-FLAG)" t nil) + +(autoload 'mh-thread-delete "mh-thread" "\ +Delete thread. + +\(fn)" t nil) + +(autoload 'mh-thread-next-sibling "mh-thread" "\ +Display next sibling. + +With non-nil optional argument PREVIOUS-FLAG jump to the previous +sibling. + +\(fn &optional PREVIOUS-FLAG)" t nil) + +(autoload 'mh-thread-previous-sibling "mh-thread" "\ +Display previous sibling. + +\(fn)" t nil) + +(autoload 'mh-thread-refile "mh-thread" "\ +Refile (output) thread into FOLDER. + +\(fn FOLDER)" t nil) + +(autoload 'mh-toggle-threads "mh-thread" "\ +Toggle threaded view of folder. + +\(fn)" t nil) + +(autoload 'mh-thread-inc "mh-thread" "\ +Update thread tree for FOLDER. +All messages after START-POINT are added to the thread tree. + +\(fn FOLDER START-POINT)" nil nil) + +(autoload 'mh-thread-parse-scan-line "mh-thread" "\ +Parse a scan line. +If optional argument STRING is given then that is assumed to be +the scan line. Otherwise uses the line at point as the scan line +to parse. + +\(fn &optional STRING)" nil nil) + +(autoload 'mh-thread-generate "mh-thread" "\ +Scan FOLDER to get info for threading. +Only information about messages in MSG-LIST are added to the tree. + +\(fn FOLDER MSG-LIST)" nil nil) + +(autoload 'mh-thread-print-scan-lines "mh-thread" "\ +Print scan lines in THREAD-TREE in threaded mode. + +\(fn THREAD-TREE)" nil nil) + +(autoload 'mh-thread-update-scan-line-map "mh-thread" "\ +In threaded view update `mh-thread-scan-line-map'. +MSG is the message being notated with NOTATION at OFFSET. + +\(fn MSG NOTATION OFFSET)" nil nil) + +(autoload 'mh-thread-find-msg-subject "mh-thread" "\ +Find canonicalized subject of MSG. +This function can only be used the folder is threaded. + +\(fn MSG)" nil nil) + +(autoload 'mh-thread-add-spaces "mh-thread" "\ +Add COUNT spaces to each scan line in `mh-thread-scan-line-map'. + +\(fn COUNT)" nil nil) + +(autoload 'mh-thread-forget-message "mh-thread" "\ +Forget the message INDEX from the threading tables. + +\(fn INDEX)" nil nil) + +;;;*** + +;;;### (autoloads (mh-signature-separator-p mh-letter-skip-leading-whitespace-in-header-field +;;;;;; mh-letter-toggle-header-field-display mh-letter-skipped-header-field-p +;;;;;; mh-letter-hide-all-skipped-fields mh-header-field-end mh-header-field-beginning +;;;;;; mh-mail-header-end mh-goto-header-end mh-goto-header-field +;;;;;; mh-get-header-field mh-extract-from-header-value mh-in-header-p +;;;;;; mh-prompt-for-folder mh-folder-completion-function mh-speed-flists-active-p +;;;;;; mh-expand-file-name mh-folder-name-p mh-remove-from-sub-folders-cache +;;;;;; mh-sub-folders mh-folder-list mh-clear-sub-folders-cache +;;;;;; mh-get-msg-num mh-lessp mh-coalesce-msg-list mh-prefix-help +;;;;;; mh-help mh-set-help mh-ephem-message mh-find-path mh-logo-display +;;;;;; mh-replace-string mh-quote-pick-expr mh-mapc mh-make-local-vars +;;;;;; mh-delete-line mh-colors-in-use-p mh-colors-available-p mh-beginning-of-word +;;;;;; mh-search-from-end) "mh-utils" "mh-utils.el" (19005 47398)) +;;; Generated autoloads from mh-utils.el + +(autoload 'mh-search-from-end "mh-utils" "\ +Return the position of last occurrence of CHAR in STRING. +If CHAR is not present in STRING then return nil. The function is +used in lieu of `search' in the CL package. + +\(fn CHAR STRING)" nil nil) + +(autoload 'mh-beginning-of-word "mh-utils" "\ +Return position of the N th word backwards. + +\(fn &optional N)" nil nil) + +(autoload 'mh-colors-available-p "mh-utils" "\ +Check if colors are available in the Emacs being used. + +\(fn)" nil nil) + +(autoload 'mh-colors-in-use-p "mh-utils" "\ +Check if colors are being used in the folder buffer. + +\(fn)" nil nil) + +(autoload 'mh-delete-line "mh-utils" "\ +Delete the next LINES lines. + +\(fn LINES)" nil nil) + +(autoload 'mh-make-local-vars "mh-utils" "\ +Initialize local variables according to the variable-value PAIRS. + +\(fn &rest PAIRS)" nil nil) + +(autoload 'mh-mapc "mh-utils" "\ +Apply FUNCTION to each element of LIST for side effects only. + +\(fn FUNCTION LIST)" nil nil) + +(autoload 'mh-quote-pick-expr "mh-utils" "\ +Quote `mh-pick-regexp-chars' in PICK-EXPR. +PICK-EXPR is a list of strings. Return nil if PICK-EXPR is nil. + +\(fn PICK-EXPR)" nil nil) + +(autoload 'mh-replace-string "mh-utils" "\ +Replace all occurrences of OLD with NEW in the current buffer. +Ignores case when searching for OLD. + +\(fn OLD NEW)" nil nil) + +(autoload 'mh-logo-display "mh-utils" "\ +Modify mode line to display MH-E logo. + +\(fn)" nil nil) + +(autoload 'mh-find-path "mh-utils" "\ +Set variables from user's MH profile. + +This function sets `mh-user-path' from your \"Path:\" MH profile +component (but defaults to \"Mail\" if one isn't present), +`mh-draft-folder' from \"Draft-Folder:\", `mh-unseen-seq' from +\"Unseen-Sequence:\", `mh-previous-seq' from +\"Previous-Sequence:\", and `mh-inbox' from \"Inbox:\" (defaults +to \"+inbox\"). + +The hook `mh-find-path-hook' is run after these variables have +been set. This hook can be used the change the value of these +variables if you need to run with different values between MH and +MH-E. + +\(fn)" nil nil) + +(autoload 'mh-ephem-message "mh-utils" "\ +Display STRING in the minibuffer momentarily. + +\(fn STRING)" nil nil) + +(autoload 'mh-set-help "mh-utils" "\ +Set help messages. + +The MESSAGES are assumed to be an associative array. It is used +to show help for the most common commands in the current mode. +The key is a prefix char. The value is one or more strings which +are concatenated together and displayed in a help buffer if ? is +pressed after the prefix character. The special key nil is used +to display the non-prefixed commands. + +The substitutions described in `substitute-command-keys' are performed as +well. + +If optional argument DEFAULT is non-nil, then these messages will +be used if help is asked for an unknown mode. + +\(fn MESSAGES &optional DEFAULT)" nil nil) + +(autoload 'mh-help "mh-utils" "\ +Display cheat sheet for the MH-E commands. +See `mh-set-help' for setting the help messages. +HELP-MESSAGES are used instead if given. +This is a list of one or more strings which are concatenated together +and displayed in a help buffer. + +\(fn &optional HELP-MESSAGES)" t nil) + +(autoload 'mh-prefix-help "mh-utils" "\ +Display cheat sheet for the commands of the current prefix in minibuffer. + +\(fn)" t nil) + +(autoload 'mh-coalesce-msg-list "mh-utils" "\ +Given a list of MESSAGES, return a list of message number ranges. +This is the inverse of `mh-read-msg-list', which expands ranges. +Message lists passed to MH programs should be processed by this +function to avoid exceeding system command line argument limits. + +\(fn MESSAGES)" nil nil) + +(autoload 'mh-lessp "mh-utils" "\ +Return the lesser of two message indicators MSG1 and MSG2. +Strings are \"smaller\" than numbers. +Valid values are things like \"cur\", \"last\", 1, and 1820. + +\(fn MSG1 MSG2)" nil nil) + +(autoload 'mh-get-msg-num "mh-utils" "\ +Return the message number of the displayed message. +If the argument ERROR-IF-NO-MESSAGE is non-nil, then complain if +the cursor is not pointing to a message. + +\(fn ERROR-IF-NO-MESSAGE)" nil nil) + +(autoload 'mh-clear-sub-folders-cache "mh-utils" "\ +Clear `mh-sub-folders-cache'. + +\(fn)" nil nil) + +(autoload 'mh-folder-list "mh-utils" "\ +Return FOLDER and its descendents. +FOLDER may have a + prefix. Returns a list of strings without the ++ prefix. If FOLDER is nil, then all folders are considered. For +example, if your Mail directory only contains the folders +inbox, ++outbox, +lists, and +lists/mh-e, then + + (mh-folder-list nil) + => (\"inbox\" \"lists\" \"lists/mh-e\" \"outbox\") + (mh-folder-list \"+lists\") + => (\"lists\" \"lists/mh-e\") + +Respects the value of `mh-recursive-folders-flag'. If this flag +is nil, and the sub-folders have not been explicitly viewed, then +they will not be returned. + +\(fn FOLDER)" nil nil) + +(autoload 'mh-sub-folders "mh-utils" "\ +Find the subfolders of FOLDER. +The function avoids running folders unnecessarily by caching the +results of the actual folders call. + +If optional argument ADD-TRAILING-SLASH-FLAG is non-nil then a +slash is added to each of the sub-folder names that may have +nested folders within them. + +\(fn FOLDER &optional ADD-TRAILING-SLASH-FLAG)" nil nil) + +(autoload 'mh-remove-from-sub-folders-cache "mh-utils" "\ +Remove FOLDER and its parent from `mh-sub-folders-cache'. +FOLDER should be unconditionally removed from the cache. Also the +last ancestor of FOLDER present in the cache must be removed as +well. + +To see why this is needed assume we have a folder +foo which has +a single sub-folder qux. Now we create the folder +foo/bar/baz. +Here we will need to invalidate the cached sub-folders of +foo, +otherwise completion on +foo won't tell us about the option ++foo/bar! + +\(fn FOLDER)" nil nil) + +(autoload 'mh-folder-name-p "mh-utils" "\ +Return non-nil if NAME is the name of a folder. +A name (a string or symbol) can be a folder name if it begins +with \"+\". + +\(fn NAME)" nil nil) + +(autoload 'mh-expand-file-name "mh-utils" "\ +Expand FILENAME like `expand-file-name', but also handle MH folder names. +Any filename that starts with '+' is treated as a folder name. +See `expand-file-name' for description of DEFAULT. + +\(fn FILENAME &optional DEFAULT)" nil nil) + +(autoload 'mh-speed-flists-active-p "mh-utils" "\ +Check if speedbar is running with message counts enabled. + +\(fn)" nil nil) + +(autoload 'mh-folder-completion-function "mh-utils" "\ +Programmable completion for folder names. +NAME is the partial folder name that has been input. PREDICATE if +non-nil is a function that is used to filter the possible +choices. FLAG is nil to indicate `try-completion', t for +`all-completions', or the symbol lambda for `test-completion'. +See Info node `(elisp) Programmed Completion' for details. + +\(fn NAME PREDICATE FLAG)" nil nil) + +(autoload 'mh-prompt-for-folder "mh-utils" "\ +Prompt for a folder name with PROMPT. +Returns the folder's name as a string. DEFAULT is used if the +folder exists and the user types return. If the CAN-CREATE flag +is t, then a folder is created if it doesn't already exist. If +optional argument DEFAULT-STRING is non-nil, use it in the prompt +instead of DEFAULT. If ALLOW-ROOT-FOLDER-FLAG is non-nil then the +function will accept the folder +, which means all folders when +used in searching. + +\(fn PROMPT DEFAULT CAN-CREATE &optional DEFAULT-STRING ALLOW-ROOT-FOLDER-FLAG)" nil nil) + +(autoload 'mh-in-header-p "mh-utils" "\ +Return non-nil if the point is in the header of a draft message. + +\(fn)" nil nil) + +(autoload 'mh-extract-from-header-value "mh-utils" "\ +Extract From: string from header. + +\(fn)" nil nil) + +(autoload 'mh-get-header-field "mh-utils" "\ +Find and return the body of FIELD in the mail header. +Returns the empty string if the field is not in the header of the +current buffer. + +\(fn FIELD)" nil nil) + +(autoload 'mh-goto-header-field "mh-utils" "\ +Move to FIELD in the message header. +Move to the end of the FIELD name, which should end in a colon. +Returns t if found, nil if not. + +\(fn FIELD)" nil nil) + +(autoload 'mh-goto-header-end "mh-utils" "\ +Move the cursor ARG lines after the header. + +\(fn ARG)" nil nil) + +(autoload 'mh-mail-header-end "mh-utils" "\ +Substitute for `mail-header-end' that doesn't widen the buffer. + +In MH-E we frequently need to find the end of headers in nested +messages, where the buffer has been narrowed. This function works +in this situation. + +\(fn)" nil nil) + +(autoload 'mh-header-field-beginning "mh-utils" "\ +Move to the beginning of the current header field. +Handles RFC 822 continuation lines. + +\(fn)" nil nil) + +(autoload 'mh-header-field-end "mh-utils" "\ +Move to the end of the current header field. +Handles RFC 822 continuation lines. + +\(fn)" nil nil) + +(autoload 'mh-letter-hide-all-skipped-fields "mh-utils" "\ +Hide all skipped fields. + +\(fn)" nil nil) + +(autoload 'mh-letter-skipped-header-field-p "mh-utils" "\ +Check if FIELD is to be skipped. + +\(fn FIELD)" nil nil) + +(autoload 'mh-letter-toggle-header-field-display "mh-utils" "\ +Toggle display of header field at point. + +Use this command to display truncated header fields. This command +is a toggle so entering it again will hide the field. This +command takes a prefix argument ARG: if negative then the field +is hidden, if positive then the field is displayed. + +\(fn ARG)" t nil) + +(autoload 'mh-letter-skip-leading-whitespace-in-header-field "mh-utils" "\ +Skip leading whitespace in a header field. +If the header field doesn't have at least one space after the +colon then a space character is added. + +\(fn)" nil nil) + +(autoload 'mh-signature-separator-p "mh-utils" "\ +Return non-nil if buffer includes \"^-- $\". + +\(fn)" nil nil) + +;;;*** + +;;;### (autoloads (mh-set-x-image-cache-directory mh-show-xface) +;;;;;; "mh-xface" "mh-xface.el" (19005 47398)) +;;; Generated autoloads from mh-xface.el + +(autoload 'mh-show-xface "mh-xface" "\ +Display X-Face. + +\(fn)" nil nil) + +(autoload 'mh-set-x-image-cache-directory "mh-xface" "\ +Set the DIRECTORY where X-Image-URL images are cached. +This is only done if `mh-x-image-cache-directory' is nil. + +\(fn DIRECTORY)" nil nil) + +;;;*** + +;;;### (autoloads nil nil ("mh-buffers.el" "mh-compat.el" "mh-e.el" +;;;;;; "mh-gnus.el" "mh-tool-bar.el") (19056 26497 754103)) + +;;;*** + +(provide 'mh-loaddefs) +;; Local Variables: +;; version-control: never +;; no-byte-compile: t +;; no-update-autoloads: t +;; coding: utf-8 +;; End: +;;; mh-loaddefs.el ends here diff --git a/lisp/net/.cvsignore b/lisp/net/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/net/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/nxml/.cvsignore b/lisp/nxml/.cvsignore deleted file mode 100644 index f18ed02a937..00000000000 --- a/lisp/nxml/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -*.elc -subdirs.el diff --git a/lisp/obsolete/.cvsignore b/lisp/obsolete/.cvsignore deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/lisp/play/.cvsignore b/lisp/play/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/play/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/progmodes/.cvsignore b/lisp/progmodes/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/progmodes/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/subdirs.el b/lisp/subdirs.el new file mode 100644 index 00000000000..fae0f17fd6d --- /dev/null +++ b/lisp/subdirs.el @@ -0,0 +1,8 @@ +;; -*- no-byte-compile: t -*- +;; In load-path, after this directory should come +;; certain of its subdirectories. Here we specify them. +(normal-top-level-add-to-load-path '("url" "textmodes" "progmodes" "play" "org" "nxml" "net" "mh-e" "mail" "language" "international" "gnus" "eshell" "erc" "emulation" "emacs-lisp" "calendar" "calc" "obsolete")) +;; Local Variables: +;; version-control: never +;; no-byte-compile: t +;; End: diff --git a/lisp/term/.cvsignore b/lisp/term/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/term/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/textmodes/.cvsignore b/lisp/textmodes/.cvsignore deleted file mode 100644 index c531d9867f6..00000000000 --- a/lisp/textmodes/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -*.elc diff --git a/lisp/url/.cvsignore b/lisp/url/.cvsignore deleted file mode 100644 index 362a9c89b75..00000000000 --- a/lisp/url/.cvsignore +++ /dev/null @@ -1,4 +0,0 @@ -Makefile -auto-autoloads.el -custom-load.el -url-auto.el diff --git a/lwlib/.cvsignore b/lwlib/.cvsignore deleted file mode 100644 index f3c7a7c5da6..00000000000 --- a/lwlib/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -Makefile diff --git a/nextstep/.cvsignore b/nextstep/.cvsignore deleted file mode 100644 index 0789870dd2d..00000000000 --- a/nextstep/.cvsignore +++ /dev/null @@ -1,2 +0,0 @@ -Emacs.app -build diff --git a/nt/.arch-inventory b/nt/.arch-inventory deleted file mode 100644 index a2db727951f..00000000000 --- a/nt/.arch-inventory +++ /dev/null @@ -1,3 +0,0 @@ -source ^subdirs\.el$ - -# arch-tag: 01b87183-9d94-4b6b-93cb-fece25c4eec9 diff --git a/nt/.cvsignore b/nt/.cvsignore deleted file mode 100644 index 3827bfaf513..00000000000 --- a/nt/.cvsignore +++ /dev/null @@ -1,7 +0,0 @@ -*-spd -*.pdb -config.log -makefile -obj -oo -stamp_BLD diff --git a/nt/.gitignore b/nt/.gitignore deleted file mode 100644 index bdeeae1e892..00000000000 --- a/nt/.gitignore +++ /dev/null @@ -1,7 +0,0 @@ -config.log -stamp_BLD - -oo/ -oo-spd/ - -# arch-tag: a25a0376-d3d9-4b3e-a52a-7c3eac9fdba3 diff --git a/oldXMenu/.cvsignore b/oldXMenu/.cvsignore deleted file mode 100644 index f3c7a7c5da6..00000000000 --- a/oldXMenu/.cvsignore +++ /dev/null @@ -1 +0,0 @@ -Makefile diff --git a/src/.arch-inventory b/src/.arch-inventory deleted file mode 100644 index c21e38d47d7..00000000000 --- a/src/.arch-inventory +++ /dev/null @@ -1,12 +0,0 @@ -# Source files which don't match the usual naming conventions, mostly dot files -source ^\.(gdbinit|dbxinit)$ - -# Auto-generated files, which ignore -precious ^(config\.stamp|config\.h|epaths\.h|buildobj\.lst)$ -precious ^(TAGS-LISP)$ -precious ^(buildobj\.lst)$ - -backup ^(stamp-oldxmenu|prefix-args|temacs|emacs|emacs-[0-9.]*)$ -backup ^(bootstrap-emacs)$ - -# arch-tag: 277cc7ae-b3f5-44af-abf1-84c073164543 diff --git a/src/.cvsignore b/src/.cvsignore deleted file mode 100644 index faa37bce4a1..00000000000 --- a/src/.cvsignore +++ /dev/null @@ -1,25 +0,0 @@ -*-spd -*.core -*.d -*.pdb -.gdb_history -Makefile -makefile -Makefile.c -TAGS-LISP -_gdbinit -_dbxinit -bootstrap-emacs -config.h -config.stamp -emacs -emacs-* -epaths.h -gdb.ini -obj -oo -prefix-args -stamp-oldxmenu -temacs -buildobj.lst -stamp_BLD diff --git a/src/.gitignore b/src/.gitignore deleted file mode 100644 index d5fd8e0715e..00000000000 --- a/src/.gitignore +++ /dev/null @@ -1,8 +0,0 @@ -config.h -epaths.h -stamp_BLD - -oo/ -oo-spd/ - -# arch-tag: 0648c91e-6070-4cc5-a029-cade1f8b6098 diff --git a/test/ChangeLog b/test/ChangeLog deleted file mode 100644 index d1679d564e9..00000000000 --- a/test/ChangeLog +++ /dev/null @@ -1,84 +0,0 @@ -2009-07-29 Chong Yidong - - * Version 23.1 released. - -2009-01-25 Ulf Jasper - - * icalendar-testsuite.el - (icalendar-testsuite--run-function-tests): Added - icalendar-testsuite--test-diarytime-to-isotime. - (icalendar-testsuite--test-parse-summary-and-rest): Adjusted to - recent icalendar fixes. - (icalendar-testsuite--test-diarytime-to-isotime): New. - (icalendar-testsuite--test-create-uid): Adjusted to recent - icalendar changes. - -2008-11-30 Shigeru Fukaya - - * bytecomp-testsuite.el: New file. - -2008-10-31 Ulf Jasper - - * icalendar-testsuite.el (icalendar-testsuite--run-function-tests): - Added `icalendar-testsuite--test-create-uid'. - (icalendar-testsuite--test-create-uid): New. - -2008-06-14 Ulf Jasper - - * newsticker-testsuite.el: New file. - -2008-05-24 Ulf Jasper - - * icalendar-testsuite.el (icalendar-testsuite--run-function-tests): - Add icalendar-testsuite--test-datestring-to-isodate, - icalendar-testsuite--test-datetime-to-diary-date, and - icalendar-testsuite--test-calendar-style. - (icalendar-testsuite--test-format-ical-event): - (icalendar-testsuite--test-parse-summary-and-rest): - Doc fix. Remove european-calendar-style. - (icalendar-testsuite--get-ical-event): Doc fix. - (icalendar-testsuite--test-first-weekday-of-year): - (icalendar-testsuite--run-cycle-tests): Add doc string. - (icalendar-testsuite--test-datestring-to-isodate): - (icalendar-testsuite--test-datetime-to-diary-date): - (icalendar-testsuite--test-calendar-style): New functions. - (icalendar-testsuite--test-export): Handle iso date style. - New arg INPUT-ISO. Use calendar-date-style. - (icalendar-testsuite--test-import): Handle iso date style. - New arg EXPECTED-ISO. Use calendar-date-style. - (icalendar-testsuite--test-cycle): Handle iso date style. - (icalendar-testsuite--run-import-tests): - (icalendar-testsuite--run-export-tests): - (icalendar-testsuite--run-real-world-tests): Add iso style tests. - -2008-02-29 Glenn Morris - - * README: New file. - -2008-02-29 Ulf Jasper - - * icalendar-testsuite.el: New file. - -;; Local Variables: -;; coding: utf-8 -;; add-log-time-zone-rule: t -;; End: - - Copyright (C) 2008, 2009 Free Software Foundation, Inc. - - This file is part of GNU Emacs. - - GNU Emacs is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - GNU Emacs is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNU Emacs. If not, see . - -;;; arch-tag: 6f0d1c86-c141-46da-b387-cf17e38c7bf7 diff --git a/test/README b/test/README deleted file mode 100644 index ee9994d109d..00000000000 --- a/test/README +++ /dev/null @@ -1,2 +0,0 @@ -This directory contains files intended to test various aspects of -Emacs's functionality. Please help add tests! diff --git a/test/bytecomp-testsuite.el b/test/bytecomp-testsuite.el deleted file mode 100644 index 66a45560868..00000000000 --- a/test/bytecomp-testsuite.el +++ /dev/null @@ -1,283 +0,0 @@ -;;; bytecomp-testsuite.el - -;; Copyright (C) 2008, 2009 Free Software Foundation, Inc. - -;; Author: Shigeru Fukaya -;; Created: November 2008 -;; Keywords: internal -;; Human-Keywords: internal - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;;; Code: -(defconst byte-opt-testsuite-arith-data - '( - ;; some functional tests - (let ((a most-positive-fixnum) (b 1) (c 1.0)) (+ a b c)) - (let ((a most-positive-fixnum) (b -2) (c 1.0)) (- a b c)) - (let ((a most-positive-fixnum) (b 2) (c 1.0)) (* a b c)) - (let ((a 3) (b 2) (c 1.0)) (/ a b c)) - (let ((a (+ 1 (expt 2 -64))) (b (expt 2 -65))) (+ a -1 b)) - (let ((a (+ 1 (expt 2 -64))) (b (expt 2 -65))) (- a 1 (- b))) - (let ((a (expt 2 -1074)) (b 0.125)) (* a 8 b)) - (let ((a 1.0)) (* a 0)) - (let ((a 1.0)) (* a 2.0 0)) - (let ((a 1.0)) (/ 0 a)) - (let ((a 1.0)) (/ 3 a 2)) - (let ((a most-positive-fixnum) (b 2.0)) (* a 2 b)) - (let ((a 3) (b 2)) (/ a b 1.0)) - (/ 3 -1) - (+ 4 3 2 1) - (+ 4 3 2.0 1) - (- 4 3 2 1) ; not new, for reference - (- 4 3 2.0 1) ; not new, for reference - (* 4 3 2 1) - (* 4 3 2.0 1) - (/ 4 3 2 1) - (/ 4 3 2.0 1) - (let ((a 3) (b 2)) (+ a b 1)) - (let ((a 3) (b 2)) (+ a b -1)) - (let ((a 3) (b 2)) (- a b 1)) - (let ((a 3) (b 2)) (- a b -1)) - (let ((a 3) (b 2)) (+ a b a 1)) - (let ((a 3) (b 2)) (+ a b a -1)) - (let ((a 3) (b 2)) (- a b a 1)) - (let ((a 3) (b 2)) (- a b a -1)) - (let ((a 3) (b 2)) (* a b -1)) - (let ((a 3) (b 2)) (* a -1)) - (let ((a 3) (b 2)) (/ a b 1)) - (let ((a 3) (b 2)) (/ (+ a b) 1)) - - ;; coverage test - (let ((a 3) (b 2) (c 1.0)) (+)) - (let ((a 3) (b 2) (c 1.0)) (+ 2)) - (let ((a 3) (b 2) (c 1.0)) (+ 2 0)) - (let ((a 3) (b 2) (c 1.0)) (+ 2 0.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 2.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 2.0 0)) - (let ((a 3) (b 2) (c 1.0)) (+ 2.0 0.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 2)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 0.0 2)) - (let ((a 3) (b 2) (c 1.0)) (+ 0.0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (+ a)) - (let ((a 3) (b 2) (c 1.0)) (+ a 0)) - (let ((a 3) (b 2) (c 1.0)) (+ a 0.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 a)) - (let ((a 3) (b 2) (c 1.0)) (+ 0.0 a)) - (let ((a 3) (b 2) (c 1.0)) (+ c 0)) - (let ((a 3) (b 2) (c 1.0)) (+ c 0.0)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 c)) - (let ((a 3) (b 2) (c 1.0)) (+ 0.0 c)) - (let ((a 3) (b 2) (c 1.0)) (+ a b 0 c 0)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 a)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 a b)) - (let ((a 3) (b 2) (c 1.0)) (+ 0 a b c)) - (let ((a 3) (b 2) (c 1.0)) (+ 1 2 3)) - (let ((a 3) (b 2) (c 1.0)) (+ 3.0 2.0 1)) - (let ((a 3) (b 2) (c 1.0)) (+ 3.0 2.0 1 4)) - (let ((a 3) (b 2) (c 1.0)) (+ a 1)) - (let ((a 3) (b 2) (c 1.0)) (+ a -1)) - (let ((a 3) (b 2) (c 1.0)) (+ 1 a)) - (let ((a 3) (b 2) (c 1.0)) (+ -1 a)) - (let ((a 3) (b 2) (c 1.0)) (+ c 1)) - (let ((a 3) (b 2) (c 1.0)) (+ c -1)) - (let ((a 3) (b 2) (c 1.0)) (+ 1 c)) - (let ((a 3) (b 2) (c 1.0)) (+ -1 c)) - (let ((a 3) (b 2) (c 1.0)) (+ a b 0)) - (let ((a 3) (b 2) (c 1.0)) (+ a b 1)) - (let ((a 3) (b 2) (c 1.0)) (+ a b -1)) - (let ((a 3) (b 2) (c 1.0)) (+ a b 2)) - (let ((a 3) (b 2) (c 1.0)) (+ 1 a b c)) - (let ((a 3) (b 2) (c 1.0)) (+ a b c 0)) - (let ((a 3) (b 2) (c 1.0)) (+ a b c 1)) - (let ((a 3) (b 2) (c 1.0)) (+ a b c -1)) - - (let ((a 3) (b 2) (c 1.0)) (-)) - (let ((a 3) (b 2) (c 1.0)) (- 2)) - (let ((a 3) (b 2) (c 1.0)) (- 2 0)) - (let ((a 3) (b 2) (c 1.0)) (- 2 0.0)) - (let ((a 3) (b 2) (c 1.0)) (- 2.0)) - (let ((a 3) (b 2) (c 1.0)) (- 2.0 0)) - (let ((a 3) (b 2) (c 1.0)) (- 2.0 0.0)) - (let ((a 3) (b 2) (c 1.0)) (- 0 2)) - (let ((a 3) (b 2) (c 1.0)) (- 0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (- 0.0 2)) - (let ((a 3) (b 2) (c 1.0)) (- 0.0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (- a)) - (let ((a 3) (b 2) (c 1.0)) (- a 0)) - (let ((a 3) (b 2) (c 1.0)) (- a 0.0)) - (let ((a 3) (b 2) (c 1.0)) (- 0 a)) - (let ((a 3) (b 2) (c 1.0)) (- 0.0 a)) - (let ((a 3) (b 2) (c 1.0)) (- c 0)) - (let ((a 3) (b 2) (c 1.0)) (- c 0.0)) - (let ((a 3) (b 2) (c 1.0)) (- 0 c)) - (let ((a 3) (b 2) (c 1.0)) (- 0.0 c)) - (let ((a 3) (b 2) (c 1.0)) (- a b 0 c 0)) - (let ((a 3) (b 2) (c 1.0)) (- 0 a)) - (let ((a 3) (b 2) (c 1.0)) (- 0 a b)) - (let ((a 3) (b 2) (c 1.0)) (- 0 a b c)) - (let ((a 3) (b 2) (c 1.0)) (- 1 2 3)) - (let ((a 3) (b 2) (c 1.0)) (- 3.0 2.0 1)) - (let ((a 3) (b 2) (c 1.0)) (- 3.0 2.0 1 4)) - (let ((a 3) (b 2) (c 1.0)) (- a 1)) - (let ((a 3) (b 2) (c 1.0)) (- a -1)) - (let ((a 3) (b 2) (c 1.0)) (- 1 a)) - (let ((a 3) (b 2) (c 1.0)) (- -1 a)) - (let ((a 3) (b 2) (c 1.0)) (- c 1)) - (let ((a 3) (b 2) (c 1.0)) (- c -1)) - (let ((a 3) (b 2) (c 1.0)) (- 1 c)) - (let ((a 3) (b 2) (c 1.0)) (- -1 c)) - (let ((a 3) (b 2) (c 1.0)) (- a b 0)) - (let ((a 3) (b 2) (c 1.0)) (- a b 1)) - (let ((a 3) (b 2) (c 1.0)) (- a b -1)) - (let ((a 3) (b 2) (c 1.0)) (- a b 2)) - (let ((a 3) (b 2) (c 1.0)) (- 1 a b c)) - (let ((a 3) (b 2) (c 1.0)) (- a b c 0)) - (let ((a 3) (b 2) (c 1.0)) (- a b c 1)) - (let ((a 3) (b 2) (c 1.0)) (- a b c -1)) - - (let ((a 3) (b 2) (c 1.0)) (*)) - (let ((a 3) (b 2) (c 1.0)) (* 2)) - (let ((a 3) (b 2) (c 1.0)) (* 2 0)) - (let ((a 3) (b 2) (c 1.0)) (* 2 0.0)) - (let ((a 3) (b 2) (c 1.0)) (* 2.0)) - (let ((a 3) (b 2) (c 1.0)) (* 2.0 0)) - (let ((a 3) (b 2) (c 1.0)) (* 2.0 0.0)) - (let ((a 3) (b 2) (c 1.0)) (* 0 2)) - (let ((a 3) (b 2) (c 1.0)) (* 0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (* 0.0 2)) - (let ((a 3) (b 2) (c 1.0)) (* 0.0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (* a)) - (let ((a 3) (b 2) (c 1.0)) (* a 0)) - (let ((a 3) (b 2) (c 1.0)) (* a 0.0)) - (let ((a 3) (b 2) (c 1.0)) (* 0 a)) - (let ((a 3) (b 2) (c 1.0)) (* 0.0 a)) - (let ((a 3) (b 2) (c 1.0)) (* c 0)) - (let ((a 3) (b 2) (c 1.0)) (* c 0.0)) - (let ((a 3) (b 2) (c 1.0)) (* 0 c)) - (let ((a 3) (b 2) (c 1.0)) (* 0.0 c)) - (let ((a 3) (b 2) (c 1.0)) (* a b 0 c 0)) - (let ((a 3) (b 2) (c 1.0)) (* 0 a)) - (let ((a 3) (b 2) (c 1.0)) (* 0 a b)) - (let ((a 3) (b 2) (c 1.0)) (* 0 a b c)) - (let ((a 3) (b 2) (c 1.0)) (* 1 2 3)) - (let ((a 3) (b 2) (c 1.0)) (* 3.0 2.0 1)) - (let ((a 3) (b 2) (c 1.0)) (* 3.0 2.0 1 4)) - (let ((a 3) (b 2) (c 1.0)) (* a 1)) - (let ((a 3) (b 2) (c 1.0)) (* a -1)) - (let ((a 3) (b 2) (c 1.0)) (* 1 a)) - (let ((a 3) (b 2) (c 1.0)) (* -1 a)) - (let ((a 3) (b 2) (c 1.0)) (* c 1)) - (let ((a 3) (b 2) (c 1.0)) (* c -1)) - (let ((a 3) (b 2) (c 1.0)) (* 1 c)) - (let ((a 3) (b 2) (c 1.0)) (* -1 c)) - (let ((a 3) (b 2) (c 1.0)) (* a b 0)) - (let ((a 3) (b 2) (c 1.0)) (* a b 1)) - (let ((a 3) (b 2) (c 1.0)) (* a b -1)) - (let ((a 3) (b 2) (c 1.0)) (* a b 2)) - (let ((a 3) (b 2) (c 1.0)) (* 1 a b c)) - (let ((a 3) (b 2) (c 1.0)) (* a b c 0)) - (let ((a 3) (b 2) (c 1.0)) (* a b c 1)) - (let ((a 3) (b 2) (c 1.0)) (* a b c -1)) - - (let ((a 3) (b 2) (c 1.0)) (/)) - (let ((a 3) (b 2) (c 1.0)) (/ 2)) - (let ((a 3) (b 2) (c 1.0)) (/ 2 0)) - (let ((a 3) (b 2) (c 1.0)) (/ 2 0.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 2.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 2.0 0)) - (let ((a 3) (b 2) (c 1.0)) (/ 2.0 0.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 2)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 0.0 2)) - (let ((a 3) (b 2) (c 1.0)) (/ 0.0 2.0)) - (let ((a 3) (b 2) (c 1.0)) (/ a)) - (let ((a 3) (b 2) (c 1.0)) (/ a 0)) - (let ((a 3) (b 2) (c 1.0)) (/ a 0.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 a)) - (let ((a 3) (b 2) (c 1.0)) (/ 0.0 a)) - (let ((a 3) (b 2) (c 1.0)) (/ c 0)) - (let ((a 3) (b 2) (c 1.0)) (/ c 0.0)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 c)) - (let ((a 3) (b 2) (c 1.0)) (/ 0.0 c)) - (let ((a 3) (b 2) (c 1.0)) (/ a b 0 c 0)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 a)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 a b)) - (let ((a 3) (b 2) (c 1.0)) (/ 0 a b c)) - (let ((a 3) (b 2) (c 1.0)) (/ 1 2 3)) - (let ((a 3) (b 2) (c 1.0)) (/ 3.0 2.0 1)) - (let ((a 3) (b 2) (c 1.0)) (/ 3.0 2.0 1 4)) - (let ((a 3) (b 2) (c 1.0)) (/ a 1)) - (let ((a 3) (b 2) (c 1.0)) (/ a -1)) - (let ((a 3) (b 2) (c 1.0)) (/ 1 a)) - (let ((a 3) (b 2) (c 1.0)) (/ -1 a)) - (let ((a 3) (b 2) (c 1.0)) (/ c 1)) - (let ((a 3) (b 2) (c 1.0)) (/ c -1)) - (let ((a 3) (b 2) (c 1.0)) (/ 1 c)) - (let ((a 3) (b 2) (c 1.0)) (/ -1 c)) - (let ((a 3) (b 2) (c 1.0)) (/ a b 0)) - (let ((a 3) (b 2) (c 1.0)) (/ a b 1)) - (let ((a 3) (b 2) (c 1.0)) (/ a b -1)) - (let ((a 3) (b 2) (c 1.0)) (/ a b 2)) - (let ((a 3) (b 2) (c 1.0)) (/ 1 a b c)) - (let ((a 3) (b 2) (c 1.0)) (/ a b c 0)) - (let ((a 3) (b 2) (c 1.0)) (/ a b c 1)) - (let ((a 3) (b 2) (c 1.0)) (/ a b c -1))) - "List of expression for test. -Each element will be executed by interpreter and with -bytecompiled code, and their results are compared.") - - -(defun bytecomp-testsuite-run () - "Run bytecomp test suite." - (interactive) - (with-output-to-temp-buffer "*bytecomp test*" - (byte-opt-testsuite--run-arith) - (message "All byte-opt tests finished successfully."))) - - -(defun byte-opt-testsuite--run-arith (&optional arg) - "Unit test for byte-opt arithmetic operations. -Subtests signal errors if something goes wrong." - (interactive "P") - (let ((print-escape-nonascii t) - (print-escape-newlines t) - (print-quoted t) - v0 v1 - indent-tabs-mode - (patterns byte-opt-testsuite-arith-data)) - (mapc - (lambda (pat) - (condition-case nil - (setq v0 (eval pat)) - (error (setq v0 nil))) - (condition-case nil - (setq v1 (funcall (byte-compile (list 'lambda nil pat)))) - (error (setq v1 nil))) - (princ (format "%s" pat)) - (if (equal v0 v1) - (princ (format " --> %s, OK\n" v1)) - (princ (format " --> %s, NG\n" v0)) - (princ (format " --> %s\n" v1)) - (error "Arithmetic test failed!"))) - patterns))) - -(provide 'byte-opt-testsuite) - -;; arch-tag: 01cb2664-5e7f-4213-ace0-91447d70b7dc diff --git a/test/icalendar-testsuite.el b/test/icalendar-testsuite.el deleted file mode 100644 index e926eabce24..00000000000 --- a/test/icalendar-testsuite.el +++ /dev/null @@ -1,1571 +0,0 @@ -;; icalendar-testsuite.el --- Test suite for icalendar.el - -;; Copyright (C) 2005, 2008, 2009 Free Software Foundation, Inc. - -;; Author: Ulf Jasper -;; Created: March 2005 -;; Keywords: calendar -;; Human-Keywords: calendar, diary, iCalendar, vCalendar - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;;; Commentary: - -;; TODO: -;; - Add more unit tests for functions, timezone etc. - -;; Note: Watch the trailing blank that is added on import. - -;;; Code: -(defun icalendar-testsuite-run () - "Run icalendar test suite." - (interactive) - (icalendar-testsuite--run-function-tests) - (icalendar-testsuite--run-import-tests) - (icalendar-testsuite--run-export-tests) - (icalendar-testsuite--run-cycle-tests) - (icalendar-testsuite--run-real-world-tests) - (message "All icalendar tests finished successfully.")) - -;; ====================================================================== -;; Test methods for functions -;; ====================================================================== -(defun icalendar-testsuite--run-function-tests () - "Perform tests for single icalendar functions." - (icalendar-testsuite--test-parse-summary-and-rest) - (icalendar-testsuite--test-format-ical-event) - (icalendar-testsuite--test-import-format-sample) - (icalendar-testsuite--test-first-weekday-of-year) - (icalendar-testsuite--test-datestring-to-isodate) - (icalendar-testsuite--test-datetime-to-diary-date) - (icalendar-testsuite--test-diarytime-to-isotime) - (icalendar-testsuite--test-calendar-style) - (icalendar-testsuite--test-create-uid)) - -(defun icalendar-testsuite--test-format-ical-event () - "Test `icalendar--format-ical-event'." - (let ((icalendar-import-format "%s%d%l%o%t%u%c") - (icalendar-import-format-summary "SUM %s") - (icalendar-import-format-location " LOC %s") - (icalendar-import-format-description " DES %s") - (icalendar-import-format-organizer " ORG %s") - (icalendar-import-format-status " STA %s") - (icalendar-import-format-url " URL %s") - (icalendar-import-format-class " CLA %s") - (event (icalendar-testsuite--get-ical-event "BEGIN:VEVENT -DTSTAMP:20030509T043439Z -DTSTART:20030509T103000 -SUMMARY:sum -ORGANIZER:org -LOCATION:loc -DTEND:20030509T153000 -DESCRIPTION:des -END:VEVENT -"))) - (assert (string= (icalendar--format-ical-event event) - "SUM sum DES des LOC loc ORG org") t) - (setq icalendar-import-format (lambda (&rest ignore) - "helloworld")) - (assert (string= (icalendar--format-ical-event event) - "helloworld") t) - (setq icalendar-import-format - (lambda (e) - (format "-%s-%s-%s-%s-%s-%s-%s-" - (icalendar--get-event-property event 'SUMMARY) - (icalendar--get-event-property event 'DESCRIPTION) - (icalendar--get-event-property event 'LOCATION) - (icalendar--get-event-property event 'ORGANIZER) - (icalendar--get-event-property event 'STATUS) - (icalendar--get-event-property event 'URL) - (icalendar--get-event-property event 'CLASS)))) - (assert (string= (icalendar--format-ical-event event) - "-sum-des-loc-org-nil-nil-nil-") t))) - -(defun icalendar-testsuite--test-parse-summary-and-rest () - "Test `icalendar--parse-summary-and-rest'." - (let ((icalendar-import-format "%s%d%l%o%t%u%c") - (icalendar-import-format-summary "SUM %s") - (icalendar-import-format-location " LOC %s") - (icalendar-import-format-description " DES %s") - (icalendar-import-format-organizer " ORG %s") - (icalendar-import-format-status " STA %s") - (icalendar-import-format-url " URL %s") - (icalendar-import-format-class " CLA %s") - (result)) - (setq result (icalendar--parse-summary-and-rest "SUM sum ORG org")) - (assert (string= (cdr (assoc 'org result)) "org")) - - (setq result (icalendar--parse-summary-and-rest - "SUM sum DES des LOC loc ORG org STA sta URL url CLA cla")) - (assert (string= (cdr (assoc 'des result)) "des")) - (assert (string= (cdr (assoc 'loc result)) "loc")) - (assert (string= (cdr (assoc 'org result)) "org")) - (assert (string= (cdr (assoc 'sta result)) "sta")) - (assert (string= (cdr (assoc 'cla result)) "cla")) - - (setq icalendar-import-format (lambda () "Hello world")) - (setq result (icalendar--parse-summary-and-rest - "blah blah ")) - (assert (not result)) - )) - -(defun icalendar-testsuite--get-ical-event (ical-string) - "Helper function for testing `icalendar-testsuite--test-format-ical-event'. -Return icalendar event for ICAL-STRING." - (save-excursion - (with-temp-buffer - (insert ical-string) - (goto-char (point-min)) - (car (icalendar--read-element nil nil))))) - -(defun icalendar-testsuite--test-import-format-sample () - "Test method for `icalendar-import-format-sample'." - (assert (string= (icalendar-import-format-sample - (icalendar-testsuite--get-ical-event "BEGIN:VEVENT -DTSTAMP:20030509T043439Z -DTSTART:20030509T103000 -SUMMARY:a -ORGANIZER:d -LOCATION:c -DTEND:20030509T153000 -DESCRIPTION:b -END:VEVENT -")) - (concat "SUMMARY=`a' DESCRIPTION=`b' LOCATION=`c' " - "ORGANIZER=`d' STATUS=`' URL=`' CLASS=`'")))) - -(defun icalendar-testsuite--test-first-weekday-of-year () - "Test method for `icalendar-first-weekday-of-year'." - (assert (eq 1 (icalendar-first-weekday-of-year "TU" 2008))) - (assert (eq 3 (icalendar-first-weekday-of-year "WE" 2007))) - (assert (eq 5 (icalendar-first-weekday-of-year "TH" 2006))) - (assert (eq 7 (icalendar-first-weekday-of-year "FR" 2005))) - (assert (eq 3 (icalendar-first-weekday-of-year "SA" 2004))) - (assert (eq 5 (icalendar-first-weekday-of-year "SU" 2003))) - (assert (eq 7 (icalendar-first-weekday-of-year "MO" 2002))) - (assert (eq 3 (icalendar-first-weekday-of-year "MO" 2000))) - (assert (eq 1 (icalendar-first-weekday-of-year "TH" 1970)))) - -(defun icalendar-testsuite--test-datestring-to-isodate () - "Test method for `icalendar--datestring-to-isodate'." - (let ((calendar-date-style 'iso)) - ;; numeric iso - (assert (string= (icalendar--datestring-to-isodate "2008 05 11") - "20080511")) - (assert (string= (icalendar--datestring-to-isodate "2008 05 31") - "20080531")) - (assert (string= (icalendar--datestring-to-isodate "2008 05 31" 2) - "20080602")) - - ;; numeric european - (setq calendar-date-style 'european) - (assert (string= (icalendar--datestring-to-isodate "11 05 2008") - "20080511")) - (assert (string= (icalendar--datestring-to-isodate "31 05 2008") - "20080531")) - (assert (string= (icalendar--datestring-to-isodate "31 05 2008" 2) - "20080602")) - - ;; numeric american - (setq calendar-date-style 'american) - (assert (string= (icalendar--datestring-to-isodate "11 05 2008") - "20081105")) - (assert (string= (icalendar--datestring-to-isodate "12 30 2008") - "20081230")) - (assert (string= (icalendar--datestring-to-isodate "12 30 2008" 2) - "20090101")) - - ;; non-numeric - (setq calendar-date-style nil) ;not necessary for conversion - (assert (string= (icalendar--datestring-to-isodate "Nov 05 2008") - "20081105")) - (assert (string= (icalendar--datestring-to-isodate "05 Nov 2008") - "20081105")) - (assert (string= (icalendar--datestring-to-isodate "2008 Nov 05") - "20081105")))) - -(defun icalendar-testsuite--test-datetime-to-diary-date () - "Test method for `icalendar--datetime-to-diary-date'." - (let* ((datetime '(59 59 23 31 12 2008)) - (calendar-date-style 'iso)) - (assert (string= (icalendar--datetime-to-diary-date datetime) - "2008 12 31")) - (setq calendar-date-style 'european) - (assert (string= (icalendar--datetime-to-diary-date datetime) - "31 12 2008")) - (setq calendar-date-style 'american) - (assert (string= (icalendar--datetime-to-diary-date datetime) - "12 31 2008")))) - -(defun icalendar-testsuite--test-diarytime-to-isotime () - "Test method for `icalendar--diarytime-to-isotime'." - (assert (string= (icalendar--diarytime-to-isotime "0100" "") - "T010000")) - (assert (string= (icalendar--diarytime-to-isotime "0100" "am") - "T010000")) - (assert (string= (icalendar--diarytime-to-isotime "0100" "pm") - "T130000")) - (assert (string= (icalendar--diarytime-to-isotime "1200" "") - "T120000")) - (assert (string= (icalendar--diarytime-to-isotime "17:17" "") - "T171700")) - (assert (string= (icalendar--diarytime-to-isotime "1200" "am") - "T000000")) - (assert (string= (icalendar--diarytime-to-isotime "1201" "am") - "T000100")) - (assert (string= (icalendar--diarytime-to-isotime "1259" "am") - "T005900")) - (assert (string= (icalendar--diarytime-to-isotime "1200" "pm") - "T120000")) - (assert (string= (icalendar--diarytime-to-isotime "1201" "pm") - "T120100")) - (assert (string= (icalendar--diarytime-to-isotime "1259" "pm") - "T125900"))) - -(defun icalendar-testsuite--test-calendar-style () - "Test method for `icalendar--date-style'." - (dolist (calendar-date-style '(iso american european)) - (assert (eq (icalendar--date-style) calendar-date-style))) - (let ((cds calendar-date-style) - (european-calendar-style t)) - (makunbound 'calendar-date-style) - (assert (eq (icalendar--date-style) 'european)) - (with-no-warnings (setq european-calendar-style nil)) ;still get warning!?! FIXME - (assert (eq (icalendar--date-style) 'american)) - (setq calendar-date-style cds))) - -(defun icalendar-testsuite--test-create-uid () - "Test method for `icalendar--create-uid'." - (let* ((icalendar-uid-format "xxx-%t-%c-%h-%u-%s") - t-ct - (icalendar--uid-count 77) - (entry-full "30.06.1964 07:01 blahblah") - (hash (format "%d" (abs (sxhash entry-full)))) - (contents "DTSTART:19640630T070100\nblahblah") - (username (or user-login-name "UNKNOWN_USER")) - ) - ;; FIXME! If a test fails 'current-time is screwed. FIXME! - (fset 't-ct (symbol-function 'current-time)) - (fset 'current-time (lambda () '(1 2 3))) - (assert (= 77 icalendar--uid-count)) - (assert (string= (concat "xxx-123-77-" hash "-" username "-19640630") - (icalendar--create-uid entry-full contents))) - (assert (= 78 icalendar--uid-count)) - (fset 'current-time (symbol-function 't-ct)) - - (setq contents "blahblah") - (setq icalendar-uid-format "yyy%syyy") - (assert (string= (concat "yyyDTSTARTyyy") - (icalendar--create-uid entry-full contents))) - )) - - -;; ====================================================================== -;; Test methods for exporting from diary to icalendar -;; ====================================================================== - -(defun icalendar-testsuite--test-export (input-iso input-european input-american - expected-output) - "Perform an export test. -Argument INPUT-ISO iso style diary string. -Argument INPUT-EUROPEAN european style diary string. -Argument INPUT-AMERICAN american style diary string. -Argument EXPECTED-OUTPUT expected icalendar result string. - -European style input data must use german month names. American -and ISO style input data must use english month names." - (message "--- icalendar-testsuite--test-export ---") - (let ((calendar-date-style 'iso) - (icalendar-recurring-start-year 2000)) - (set-time-zone-rule "CET") ;;FIXME: reset timezone! - (when input-iso - (let ((calendar-month-name-array - ["January" "February" "March" "April" "May" "June" "July" "August" - "September" "October" "November" "December"]) - (calendar-day-name-array - ["Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" - "Saturday"])) - (setq calendar-date-style 'iso) - (icalendar-testsuite--do-test-export input-iso expected-output))) - (when input-european - (let ((calendar-month-name-array - ["Januar" "Februar" "März" "April" "Mai" "Juni" "Juli" "August" - "September" "Oktober" "November" "Dezember"]) - (calendar-day-name-array - ["Sonntag" "Montag" "Dienstag" "Mittwoch" "Donnerstag" "Freitag" - "Samstag"])) - (setq calendar-date-style 'european) - (icalendar-testsuite--do-test-export input-european expected-output))) - (when input-american - (let ((calendar-month-name-array - ["January" "February" "March" "April" "May" "June" "July" "August" - "September" "October" "November" "December"]) - (calendar-day-name-array - ["Sunday" "Monday" "Tuesday" "Wednesday" "Thursday" "Friday" - "Saturday"])) - (setq calendar-date-style 'american) - (icalendar-testsuite--do-test-export input-american expected-output))))) - -(defun icalendar-testsuite--do-test-export (input expected-output) - "Actually perform export test. -Argument INPUT input diary string. -Argument EXPECTED-OUTPUT expected icalendar result string." - (let ((temp-file (make-temp-file "icalendar-testsuite-ics"))) - (with-temp-buffer - (insert input) - (icalendar-export-region (point-min) (point-max) temp-file)) - (save-excursion - (find-file temp-file) - (goto-char (point-min)) - (unless - (cond (expected-output - (and (re-search-forward "^\\s-*BEGIN:VCALENDAR -PRODID:-//Emacs//NONSGML icalendar.el//EN -VERSION:2.0 -BEGIN:VEVENT -UID:emacs[0-9]+ -\\(\\(.\\|\n\\)+\\) -END:VEVENT -END:VCALENDAR -\\s-*$" - nil t) - (string-match - (concat "^\\s-*" - (regexp-quote (buffer-substring-no-properties - (match-beginning 1) (match-end 1))) - "\\s-*$") - expected-output))) - (t - (re-search-forward "^\\s-*BEGIN:VCALENDAR -PRODID:-//Emacs//NONSGML icalendar.el//EN -VERSION:2.0 -END:VCALENDAR -\\s-*$" - nil t))) - (error - "Export test failed! Input: `%s'\nFound:\n\n%s\n\nbut expected\n\n%s" - input - (or (and (match-beginning 1) - (buffer-substring-no-properties (match-beginning 1) (match-end 1))) - "") - (or expected-output "")))) - (kill-buffer (find-buffer-visiting temp-file)) - (delete-file temp-file))) - -;; ====================================================================== -;; Test methods for importing from icalendar to diary -;; ====================================================================== - -(defun icalendar-testsuite--test-import (input expected-iso expected-european - expected-american) - "Perform import test. -Argument INPUT icalendar event string. -Argument EXPECTED-ISO expected iso style diary string. -Argument EXPECTED-EUROPEAN expected european style diary string. -Argument EXPECTED-AMERICAN expected american style diary string." - (message "--- icalendar-testsuite--test-import ---") - (let ((timezone (cadr (current-time-zone)))) - (set-time-zone-rule "CET") - (with-temp-buffer - (if (string-match "^BEGIN:VCALENDAR" input) - (insert input) - (insert "BEGIN:VCALENDAR\nPRODID:-//Emacs//NONSGML icalendar.el//EN\n") - (insert "VERSION:2.0\nBEGIN:VEVENT\n") - (insert input) - (unless (eq (char-before) ?\n) - (insert "\n")) - (insert "END:VEVENT\nEND:VCALENDAR\n")) - (let ((icalendar-import-format "%s%d%l%o%t%u%c") - (icalendar-import-format-summary "%s") - (icalendar-import-format-location "\n Location: %s") - (icalendar-import-format-description "\n Desc: %s") - (icalendar-import-format-organizer "\n Organizer: %s") - (icalendar-import-format-status "\n Status: %s") - (icalendar-import-format-url "\n URL: %s") - (icalendar-import-format-class "\n Class: %s") - calendar-date-style) - (when expected-iso - (setq calendar-date-style 'iso) - (icalendar-testsuite--do-test-import input expected-iso)) - (when expected-european - (setq calendar-date-style 'european) - (icalendar-testsuite--do-test-import input expected-european)) - (when expected-american - (setq calendar-date-style 'american) - (icalendar-testsuite--do-test-import input expected-american)))) - (set-time-zone-rule timezone))) - -(defun icalendar-testsuite--do-test-import (input expected-output) - "Actually perform import test. -Argument INPUT input icalendar string. -Argument EXPECTED-OUTPUT expected diary string." - (let ((temp-file (make-temp-file "icalendar-test-diary"))) - (icalendar-import-buffer temp-file t t) - (save-excursion - (find-file temp-file) - (let ((result (buffer-substring-no-properties (point-min) (point-max)))) - (unless (string-match (concat "^\\s-*" expected-output "\\s-*$") - result) - (error "Import test failed! Found `%s'\nbut expected `%s'" result - expected-output))) - (kill-buffer (find-buffer-visiting temp-file)) - (delete-file temp-file)))) - -;; ====================================================================== -;; Test methods for cycle... -;; ====================================================================== -(defun icalendar-testsuite--test-cycle (input) - "Perform cycle test. -Argument INPUT icalendar event string." - (with-temp-buffer - (if (string-match "^BEGIN:VCALENDAR" input) - (insert input) - (insert "BEGIN:VCALENDAR\nPRODID:-//Emacs//NONSGML icalendar.el//EN\n") - (insert "VERSION:2.0\nBEGIN:VEVENT\n") - (insert input) - (unless (eq (char-before) ?\n) - (insert "\n")) - (insert "END:VEVENT\nEND:VCALENDAR\n")) - (let ((icalendar-import-format "%s%d%l%o%t%u%c") - (icalendar-import-format-summary "%s") - (icalendar-import-format-location "\n Location: %s") - (icalendar-import-format-description "\n Desc: %s") - (icalendar-import-format-organizer "\n Organizer: %s") - (icalendar-import-format-status "\n Status: %s") - (icalendar-import-format-url "\n URL: %s") - (icalendar-import-format-class "\n Class: %s")) - (dolist (calendar-date-style '(iso european american)) - (icalendar-testsuite--do-test-cycle))))) - -(defun icalendar-testsuite--do-test-cycle () - "Actually perform import/export cycle test." - (let ((temp-diary (make-temp-file "icalendar-test-diary")) - (temp-ics (make-temp-file "icalendar-test-ics")) - (org-input (buffer-substring-no-properties (point-min) (point-max)))) - (icalendar-import-buffer temp-diary t t) - (save-excursion - (find-file temp-diary) - (icalendar-export-region (point-min) (point-max) temp-ics)) - (save-excursion - (find-file temp-ics) - (goto-char (point-min)) - (when (re-search-forward "\nUID:.*\n" nil t) - (replace-match "\n")) - (let ((cycled (buffer-substring-no-properties (point-min) (point-max)))) - (unless (string-equal org-input cycled) - (error "Import test failed! Found `%s'\nbut expected `%s'" cycled - org-input)))) - (kill-buffer (find-buffer-visiting temp-diary)) - (save-excursion - (set-buffer (find-buffer-visiting temp-ics)) - (set-buffer-modified-p nil) - (kill-buffer (current-buffer))) - (delete-file temp-diary) - (delete-file temp-ics))) - -;; ====================================================================== -;; Import tests -;; ====================================================================== -(defun icalendar-testsuite--run-import-tests () - "Perform standard import tests." - (icalendar-testsuite--test-import - "SUMMARY:non-recurring -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000" - "&2003/9/19 09:00-11:30 non-recurring" - "&19/9/2003 09:00-11:30 non-recurring" - "&9/19/2003 09:00-11:30 non-recurring") - - (icalendar-testsuite--test-import - "SUMMARY:non-recurring allday -DTSTART;VALUE=DATE-TIME:20030919" - "&2003/9/19 non-recurring allday" - "&19/9/2003 non-recurring allday" - "&9/19/2003 non-recurring allday") - - (icalendar-testsuite--test-import - "SUMMARY:long - summary -DTSTART;VALUE=DATE:20030919" - "&2003/9/19 long summary" - "&19/9/2003 long summary" - "&9/19/2003 long summary") - - (icalendar-testsuite--test-import - "UID:748f2da0-0d9b-11d8-97af-b4ec8686ea61 -SUMMARY:Sommerferien -STATUS:TENTATIVE -CLASS:PRIVATE -X-MOZILLA-ALARM-DEFAULT-UNITS:Minuten -X-MOZILLA-RECUR-DEFAULT-INTERVAL:0 -DTSTART;VALUE=DATE:20040719 -DTEND;VALUE=DATE:20040828 -DTSTAMP:20031103T011641Z -" - "&%%(and (diary-block 2004 7 19 2004 8 27)) Sommerferien" - "&%%(and (diary-block 19 7 2004 27 8 2004)) Sommerferien" - "&%%(and (diary-block 7 19 2004 8 27 2004)) Sommerferien") - - (icalendar-testsuite--test-import - "UID - :04979712-3902-11d9-93dd-8f9f4afe08da -SUMMARY - :folded summary -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - :20041123T140000 -DTEND - :20041123T143000 -DTSTAMP - :20041118T013430Z -LAST-MODIFIED - :20041118T013640Z -" - "&2004/11/23 14:00-14:30 folded summary" - "&23/11/2004 14:00-14:30 folded summary" - "&11/23/2004 14:00-14:30 folded summary") - (icalendar-testsuite--test-import - "UID - :6161a312-3902-11d9-b512-f764153bb28b -SUMMARY - :another example -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - :20041123T144500 -DTEND - :20041123T154500 -DTSTAMP - :20041118T013641Z -" - "&2004/11/23 14:45-15:45 another example" - "&23/11/2004 14:45-15:45 another example" - "&11/23/2004 14:45-15:45 another example") - - (icalendar-testsuite--test-import - "SUMMARY:rrule daily -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=DAILY; -" - "&%%(and (diary-cyclic 1 2003 9 19)) 09:00-11:30 rrule daily" - "&%%(and (diary-cyclic 1 19 9 2003)) 09:00-11:30 rrule daily" - "&%%(and (diary-cyclic 1 9 19 2003)) 09:00-11:30 rrule daily") - - ;; RRULE examples - (icalendar-testsuite--test-import - "SUMMARY:rrule daily -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=DAILY;INTERVAL=2 -" - "&%%(and (diary-cyclic 2 2003 9 19)) 09:00-11:30 rrule daily" - "&%%(and (diary-cyclic 2 19 9 2003)) 09:00-11:30 rrule daily" - "&%%(and (diary-cyclic 2 9 19 2003)) 09:00-11:30 rrule daily") - (icalendar-testsuite--test-import - "SUMMARY:rrule daily with exceptions -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=DAILY;INTERVAL=2 -EXDATE:20030921,20030925 -" - "&%%(and (not (diary-date 2003 9 25)) (not (diary-date 2003 9 21)) (diary-cyclic 2 2003 9 19)) 09:00-11:30 rrule daily with exceptions" - "&%%(and (not (diary-date 25 9 2003)) (not (diary-date 21 9 2003)) (diary-cyclic 2 19 9 2003)) 09:00-11:30 rrule daily with exceptions" - "&%%(and (not (diary-date 9 25 2003)) (not (diary-date 9 21 2003)) (diary-cyclic 2 9 19 2003)) 09:00-11:30 rrule daily with exceptions") - - (icalendar-testsuite--test-import - "SUMMARY:rrule weekly -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=WEEKLY; -" - "&%%(and (diary-cyclic 7 2003 9 19)) 09:00-11:30 rrule weekly" - "&%%(and (diary-cyclic 7 19 9 2003)) 09:00-11:30 rrule weekly" - "&%%(and (diary-cyclic 7 9 19 2003)) 09:00-11:30 rrule weekly") - (icalendar-testsuite--test-import - "SUMMARY:rrule monthly no end -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=MONTHLY; -" - "&%%(and (diary-date t t 19) (diary-block 2003 9 19 9999 1 1)) 09:00-11:30 rrule monthly no end" - "&%%(and (diary-date 19 t t) (diary-block 19 9 2003 1 1 9999)) 09:00-11:30 rrule monthly no end" - "&%%(and (diary-date t 19 t) (diary-block 9 19 2003 1 1 9999)) 09:00-11:30 rrule monthly no end") - (icalendar-testsuite--test-import - "SUMMARY:rrule monthly with end -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=MONTHLY;UNTIL=20050819; -" - "&%%(and (diary-date t t 19) (diary-block 2003 9 19 2005 8 19)) 09:00-11:30 rrule monthly with end" - "&%%(and (diary-date 19 t t) (diary-block 19 9 2003 19 8 2005)) 09:00-11:30 rrule monthly with end" - "&%%(and (diary-date t 19 t) (diary-block 9 19 2003 8 19 2005)) 09:00-11:30 rrule monthly with end") - (icalendar-testsuite--test-import - "DTSTART;VALUE=DATE:20040815 -DTEND;VALUE=DATE:20040816 -SUMMARY:Maria Himmelfahrt -UID:CC56BEA6-49D2-11D8-8833-00039386D1C2-RID -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=8 -" - "&%%(and (diary-anniversary 2004 8 15)) Maria Himmelfahrt" - "&%%(and (diary-anniversary 15 8 2004)) Maria Himmelfahrt" - "&%%(and (diary-anniversary 8 15 2004)) Maria Himmelfahrt") - (icalendar-testsuite--test-import - "SUMMARY:rrule yearly -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=YEARLY;INTERVAL=2 -" - "&%%(and (diary-anniversary 2003 9 19)) 09:00-11:30 rrule yearly" ;FIXME - "&%%(and (diary-anniversary 19 9 2003)) 09:00-11:30 rrule yearly" ;FIXME - "&%%(and (diary-anniversary 9 19 2003)) 09:00-11:30 rrule yearly") ;FIXME - (icalendar-testsuite--test-import - "SUMMARY:rrule count daily short -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=DAILY;COUNT=1;INTERVAL=1 -" - "&%%(and (diary-cyclic 1 2003 9 19) (diary-block 2003 9 19 2003 9 19)) 09:00-11:30 rrule count daily short" - "&%%(and (diary-cyclic 1 19 9 2003) (diary-block 19 9 2003 19 9 2003)) 09:00-11:30 rrule count daily short" - "&%%(and (diary-cyclic 1 9 19 2003) (diary-block 9 19 2003 9 19 2003)) 09:00-11:30 rrule count daily short") - (icalendar-testsuite--test-import - "SUMMARY:rrule count daily long -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=DAILY;COUNT=14;INTERVAL=1 -" - "&%%(and (diary-cyclic 1 2003 9 19) (diary-block 2003 9 19 2003 10 2)) 09:00-11:30 rrule count daily long" - "&%%(and (diary-cyclic 1 19 9 2003) (diary-block 19 9 2003 2 10 2003)) 09:00-11:30 rrule count daily long" - "&%%(and (diary-cyclic 1 9 19 2003) (diary-block 9 19 2003 10 2 2003)) 09:00-11:30 rrule count daily long") - (icalendar-testsuite--test-import - "SUMMARY:rrule count bi-weekly 3 times -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=WEEKLY;COUNT=3;INTERVAL=2 -" - "&%%(and (diary-cyclic 14 2003 9 19) (diary-block 2003 9 19 2003 10 31)) 09:00-11:30 rrule count bi-weekly 3 times" - "&%%(and (diary-cyclic 14 19 9 2003) (diary-block 19 9 2003 31 10 2003)) 09:00-11:30 rrule count bi-weekly 3 times" - "&%%(and (diary-cyclic 14 9 19 2003) (diary-block 9 19 2003 10 31 2003)) 09:00-11:30 rrule count bi-weekly 3 times") - (icalendar-testsuite--test-import - "SUMMARY:rrule count monthly -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=MONTHLY;INTERVAL=1;COUNT=5 -" - "&%%(and (diary-date t t 19) (diary-block 2003 9 19 2004 1 19)) 09:00-11:30 rrule count monthly" - "&%%(and (diary-date 19 t t) (diary-block 19 9 2003 19 1 2004)) 09:00-11:30 rrule count monthly" - "&%%(and (diary-date t 19 t) (diary-block 9 19 2003 1 19 2004)) 09:00-11:30 rrule count monthly") - (icalendar-testsuite--test-import - "SUMMARY:rrule count every second month -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=5 -" - "&%%(and (diary-date t t 19) (diary-block 2003 9 19 2004 5 19)) 09:00-11:30 rrule count every second month" ;FIXME - "&%%(and (diary-date 19 t t) (diary-block 19 9 2003 19 5 2004)) 09:00-11:30 rrule count every second month" ;FIXME - "&%%(and (diary-date t 19 t) (diary-block 9 19 2003 5 19 2004)) 09:00-11:30 rrule count every second month") ;FIXME - (icalendar-testsuite--test-import - "SUMMARY:rrule count yearly -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=YEARLY;INTERVAL=1;COUNT=5 -" - "&%%(and (diary-date t 9 19) (diary-block 2003 9 19 2007 9 19)) 09:00-11:30 rrule count yearly" - "&%%(and (diary-date 19 9 t) (diary-block 19 9 2003 19 9 2007)) 09:00-11:30 rrule count yearly" - "&%%(and (diary-date 9 19 t) (diary-block 9 19 2003 9 19 2007)) 09:00-11:30 rrule count yearly") - (icalendar-testsuite--test-import - "SUMMARY:rrule count every second year -DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=5 -" - "&%%(and (diary-date t 9 19) (diary-block 2003 9 19 2011 9 19)) 09:00-11:30 rrule count every second year" ;FIXME!!! - "&%%(and (diary-date 19 9 t) (diary-block 19 9 2003 19 9 2011)) 09:00-11:30 rrule count every second year" ;FIXME!!! - "&%%(and (diary-date 9 19 t) (diary-block 9 19 2003 9 19 2011)) 09:00-11:30 rrule count every second year") ;FIXME!!! - - ;; duration - (icalendar-testsuite--test-import - "DTSTART;VALUE=DATE:20050217 -SUMMARY:duration -DURATION:P7D -" - "&%%(and (diary-block 2005 2 17 2005 2 23)) duration" - "&%%(and (diary-block 17 2 2005 23 2 2005)) duration" - "&%%(and (diary-block 2 17 2005 2 23 2005)) duration") - - (icalendar-testsuite--test-import - "UID:20041127T183329Z-18215-1001-4536-49109@andromeda -DTSTAMP:20041127T183315Z -LAST-MODIFIED:20041127T183329 -SUMMARY:Urlaub -DTSTART;VALUE=DATE:20011221 -DTEND;VALUE=DATE:20011221 -RRULE:FREQ=DAILY;UNTIL=20011229;INTERVAL=1;WKST=SU -CLASS:PUBLIC -SEQUENCE:1 -CREATED:20041127T183329 -" - "&%%(and (diary-cyclic 1 2001 12 21) (diary-block 2001 12 21 2001 12 29)) Urlaub" - "&%%(and (diary-cyclic 1 21 12 2001) (diary-block 21 12 2001 29 12 2001)) Urlaub" - "&%%(and (diary-cyclic 1 12 21 2001) (diary-block 12 21 2001 12 29 2001)) Urlaub") - ) - -;; ====================================================================== -;; Export tests -;; ====================================================================== -(defun icalendar-testsuite--run-export-tests () - "Perform standard export tests." - - (let ((icalendar-export-hidden-diary-entries nil)) - (icalendar-testsuite--test-export - "&2000 Oct 3 ordinary no time " - "&3 Okt 2000 ordinary no time " - "&Oct 3 2000 ordinary no time " - nil)) - - ;; "ordinary" events - (icalendar-testsuite--test-export - "2000 Oct 3 ordinary no time " - "3 Okt 2000 ordinary no time " - "Oct 3 2000 ordinary no time " - "DTSTART;VALUE=DATE:20001003 -DTEND;VALUE=DATE:20001004 -SUMMARY:ordinary no time -") - (icalendar-testsuite--test-export - "2000 Oct 3 16:30 ordinary with time" - "3 Okt 2000 16:30 ordinary with time" - "Oct 3 2000 16:30 ordinary with time" - "DTSTART;VALUE=DATE-TIME:20001003T163000 -DTEND;VALUE=DATE-TIME:20001003T173000 -SUMMARY:ordinary with time -") - (icalendar-testsuite--test-export - "2000 10 3 16:30 ordinary with time 2" - "3 10 2000 16:30 ordinary with time 2" - "10 3 2000 16:30 ordinary with time 2" - "DTSTART;VALUE=DATE-TIME:20001003T163000 -DTEND;VALUE=DATE-TIME:20001003T173000 -SUMMARY:ordinary with time 2 -") - - (icalendar-testsuite--test-export - "2000/10/3 16:30 ordinary with time 3" - "3/10/2000 16:30 ordinary with time 3" - "10/3/2000 16:30 ordinary with time 3" - "DTSTART;VALUE=DATE-TIME:20001003T163000 -DTEND;VALUE=DATE-TIME:20001003T173000 -SUMMARY:ordinary with time 3 -") - - ;; multiline -- FIXME!!! - (icalendar-testsuite--test-export - "2000 October 3 16:30 multiline - 17:30 multiline continued FIXME" - "3 Oktober 2000 16:30 multiline - 17:30 multiline continued FIXME" - "October 3 2000 16:30 multiline - 17:30 multiline continued FIXME" - "DTSTART;VALUE=DATE-TIME:20001003T163000 -DTEND;VALUE=DATE-TIME:20001003T173000 -SUMMARY:multiline -DESCRIPTION: - 17:30 multiline continued FIXME -") - - ;; weekly by day - (icalendar-testsuite--test-export - "Monday 1:30pm weekly by day with start time" - "Montag 13:30 weekly by day with start time" - "Monday 1:30pm weekly by day with start time" - "DTSTART;VALUE=DATE-TIME:20000103T133000 -DTEND;VALUE=DATE-TIME:20000103T143000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -SUMMARY:weekly by day with start time -") - - (icalendar-testsuite--test-export - "Monday 13:30-15:00 weekly by day with start and end time" - "Montag 13:30-15:00 weekly by day with start and end time" - "Monday 01:30pm-03:00pm weekly by day with start and end time" - "DTSTART;VALUE=DATE-TIME:20000103T133000 -DTEND;VALUE=DATE-TIME:20000103T150000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -SUMMARY:weekly by day with start and end time -") - - ;; yearly - (icalendar-testsuite--test-export - "may 1 yearly no time" - "1 Mai yearly no time" - "may 1 yearly no time" - "DTSTART;VALUE=DATE:19000501 -DTEND;VALUE=DATE:19000502 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=5;BYMONTHDAY=1 -SUMMARY:yearly no time -") - - ;; anniversaries - (icalendar-testsuite--test-export - "%%(diary-anniversary 1989 10 3) anniversary no time" - "%%(diary-anniversary 3 10 1989) anniversary no time" - "%%(diary-anniversary 10 3 1989) anniversary no time" - "DTSTART;VALUE=DATE:19891003 -DTEND;VALUE=DATE:19891004 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=10;BYMONTHDAY=03 -SUMMARY:anniversary no time -") - (icalendar-testsuite--test-export - "%%(diary-anniversary 1989 10 3) 19:00-20:00 anniversary with time" - "%%(diary-anniversary 3 10 1989) 19:00-20:00 anniversary with time" - "%%(diary-anniversary 10 3 1989) 19:00-20:00 anniversary with time" - "DTSTART;VALUE=DATE-TIME:19891003T190000 -DTEND;VALUE=DATE-TIME:19891004T200000 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=10;BYMONTHDAY=03 -SUMMARY:anniversary with time -") - - ;; block - (icalendar-testsuite--test-export - "%%(diary-block 2001 6 18 2001 7 6) block no time" - "%%(diary-block 18 6 2001 6 7 2001) block no time" - "%%(diary-block 6 18 2001 7 6 2001) block no time" - "DTSTART;VALUE=DATE:20010618 -DTEND;VALUE=DATE:20010707 -SUMMARY:block no time -") - (icalendar-testsuite--test-export - "%%(diary-block 2001 6 18 2001 7 6) 13:00-17:00 block with time" - "%%(diary-block 18 6 2001 6 7 2001) 13:00-17:00 block with time" - "%%(diary-block 6 18 2001 7 6 2001) 13:00-17:00 block with time" - "DTSTART;VALUE=DATE-TIME:20010618T130000 -DTEND;VALUE=DATE-TIME:20010618T170000 -RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20010706 -SUMMARY:block with time -") - (icalendar-testsuite--test-export - "%%(diary-block 2001 6 18 2001 7 6) 13:00 block no end time" - "%%(diary-block 18 6 2001 6 7 2001) 13:00 block no end time" - "%%(diary-block 6 18 2001 7 6 2001) 13:00 block no end time" - "DTSTART;VALUE=DATE-TIME:20010618T130000 -DTEND;VALUE=DATE-TIME:20010618T140000 -RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20010706 -SUMMARY:block no end time -") - ) - -;; ====================================================================== -;; Real world -;; ====================================================================== -(defun icalendar-testsuite--run-real-world-tests () - "Perform real-world tests, as gathered from problem reports." - ;; 2003-05-29 - (icalendar-testsuite--test-import - "BEGIN:VCALENDAR -METHOD:REQUEST -PRODID:Microsoft CDO for Microsoft Exchange -VERSION:2.0 -BEGIN:VTIMEZONE -TZID:Kolkata\, Chennai\, Mumbai\, New Delhi -X-MICROSOFT-CDO-TZID:23 -BEGIN:STANDARD -DTSTART:16010101T000000 -TZOFFSETFROM:+0530 -TZOFFSETTO:+0530 -END:STANDARD -BEGIN:DAYLIGHT -DTSTART:16010101T000000 -TZOFFSETFROM:+0530 -TZOFFSETTO:+0530 -END:DAYLIGHT -END:VTIMEZONE -BEGIN:VEVENT -DTSTAMP:20030509T043439Z -DTSTART;TZID=\"Kolkata, Chennai, Mumbai, New Delhi\":20030509T103000 -SUMMARY:On-Site Interview -UID:040000008200E00074C5B7101A82E0080000000080B6DE661216C301000000000000000 - 010000000DB823520692542408ED02D7023F9DFF9 -ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=\"Xxxxx - xxx Xxxxxxxxxxxx\":MAILTO:xxxxxxxx@xxxxxxx.com -ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=\"Yyyyyyy Y - yyyy\":MAILTO:yyyyyyy@yyyyyyy.com -ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=\"Zzzz Zzzz - zz\":MAILTO:zzzzzz@zzzzzzz.com -ORGANIZER;CN=\"Aaaaaa Aaaaa\":MAILTO:aaaaaaa@aaaaaaa.com -LOCATION:Cccc -DTEND;TZID=\"Kolkata, Chennai, Mumbai, New Delhi\":20030509T153000 -DESCRIPTION:10:30am - Blah -SEQUENCE:0 -PRIORITY:5 -CLASS: -CREATED:20030509T043439Z -LAST-MODIFIED:20030509T043459Z -STATUS:CONFIRMED -TRANSP:OPAQUE -X-MICROSOFT-CDO-BUSYSTATUS:BUSY -X-MICROSOFT-CDO-INSTTYPE:0 -X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY -X-MICROSOFT-CDO-ALLDAYEVENT:FALSE -X-MICROSOFT-CDO-IMPORTANCE:1 -X-MICROSOFT-CDO-OWNERAPPTID:126441427 -BEGIN:VALARM -ACTION:DISPLAY -DESCRIPTION:REMINDER -TRIGGER;RELATED=START:-PT00H15M00S -END:VALARM -END:VEVENT -END:VCALENDAR" - nil - "&9/5/2003 10:30-15:30 On-Site Interview - Desc: 10:30am - Blah - Location: Cccc - Organizer: MAILTO:aaaaaaa@aaaaaaa.com" - "&5/9/2003 10:30-15:30 On-Site Interview - Desc: 10:30am - Blah - Location: Cccc - Organizer: MAILTO:aaaaaaa@aaaaaaa.com") - - ;; 2003-06-18 a - (icalendar-testsuite--test-import - "DTSTAMP:20030618T195512Z -DTSTART;TZID=\"Mountain Time (US & Canada)\":20030623T110000 -SUMMARY:Dress Rehearsal for XXXX-XXXX -UID:040000008200E00074C5B7101A82E00800000000608AA7DA9835C301000000000000000 - 0100000007C3A6D65EE726E40B7F3D69A23BD567E -ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE;CN=\"AAAAA,AAA - AA (A-AAAAAAA,ex1)\":MAILTO:aaaaa_aaaaa@aaaaa.com -ORGANIZER;CN=\"ABCD,TECHTRAINING - (A-Americas,exgen1)\":MAILTO:xxx@xxxxx.com -LOCATION:555 or TN 555-5555 ID 5555 & NochWas (see below) -DTEND;TZID=\"Mountain Time (US & Canada)\":20030623T120000 -DESCRIPTION:753 Zeichen hier radiert -SEQUENCE:0 -PRIORITY:5 -CLASS: -CREATED:20030618T195518Z -LAST-MODIFIED:20030618T195527Z -STATUS:CONFIRMED -TRANSP:OPAQUE -X-MICROSOFT-CDO-BUSYSTATUS:BUSY -X-MICROSOFT-CDO-INSTTYPE:0 -X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY -X-MICROSOFT-CDO-ALLDAYEVENT:FALSE -X-MICROSOFT-CDO-IMPORTANCE:1 -X-MICROSOFT-CDO-OWNERAPPTID:1022519251 -BEGIN:VALARM -ACTION:DISPLAY -DESCRIPTION:REMINDER -TRIGGER;RELATED=START:-PT00H15M00S -END:VALARM" - nil - "&23/6/2003 11:00-12:00 Dress Rehearsal for XXXX-XXXX - Desc: 753 Zeichen hier radiert - Location: 555 or TN 555-5555 ID 5555 & NochWas (see below) - Organizer: MAILTO:xxx@xxxxx.com" - "&6/23/2003 11:00-12:00 Dress Rehearsal for XXXX-XXXX - Desc: 753 Zeichen hier radiert - Location: 555 or TN 555-5555 ID 5555 & NochWas (see below) - Organizer: MAILTO:xxx@xxxxx.com") - - ;; 2003-06-18 b -- uses timezone - (icalendar-testsuite--test-import - "BEGIN:VCALENDAR -METHOD:REQUEST -PRODID:Microsoft CDO for Microsoft Exchange -VERSION:2.0 -BEGIN:VTIMEZONE -TZID:Mountain Time (US & Canada) -X-MICROSOFT-CDO-TZID:12 -BEGIN:STANDARD -DTSTART:16010101T020000 -TZOFFSETFROM:-0600 -TZOFFSETTO:-0700 -RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=10;BYDAY=-1SU -END:STANDARD -BEGIN:DAYLIGHT -DTSTART:16010101T020000 -TZOFFSETFROM:-0700 -TZOFFSETTO:-0600 -RRULE:FREQ=YEARLY;WKST=MO;INTERVAL=1;BYMONTH=4;BYDAY=1SU -END:DAYLIGHT -END:VTIMEZONE -BEGIN:VEVENT -DTSTAMP:20030618T230323Z -DTSTART;TZID=\"Mountain Time (US & Canada)\":20030623T090000 -SUMMARY:Updated: Dress Rehearsal for ABC01-15 -UID:040000008200E00074C5B7101A82E00800000000608AA7DA9835C301000000000000000 - 0100000007C3A6D65EE726E40B7F3D69A23BD567E -ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;X-REPLYTIME=20030618T20 - 0700Z;RSVP=TRUE;CN=\"AAAAA,AAAAAA -\(A-AAAAAAA,ex1)\":MAILTO:aaaaaa_aaaaa@aaaaa - .com -ORGANIZER;CN=\"ABCD,TECHTRAINING -\(A-Americas,exgen1)\":MAILTO:bbb@bbbbb.com -LOCATION:123 or TN 123-1234 ID abcd & SonstWo (see below) -DTEND;TZID=\"Mountain Time (US & Canada)\":20030623T100000 -DESCRIPTION:Viele Zeichen standen hier früher -SEQUENCE:0 -PRIORITY:5 -CLASS: -CREATED:20030618T230326Z -LAST-MODIFIED:20030618T230335Z -STATUS:CONFIRMED -TRANSP:OPAQUE -X-MICROSOFT-CDO-BUSYSTATUS:BUSY -X-MICROSOFT-CDO-INSTTYPE:0 -X-MICROSOFT-CDO-INTENDEDSTATUS:BUSY -X-MICROSOFT-CDO-ALLDAYEVENT:FALSE -X-MICROSOFT-CDO-IMPORTANCE:1 -X-MICROSOFT-CDO-OWNERAPPTID:1022519251 -BEGIN:VALARM -ACTION:DISPLAY -DESCRIPTION:REMINDER -TRIGGER;RELATED=START:-PT00H15M00S -END:VALARM -END:VEVENT -END:VCALENDAR" - nil - "&23/6/2003 17:00-18:00 Updated: Dress Rehearsal for ABC01-15 - Desc: Viele Zeichen standen hier früher - Location: 123 or TN 123-1234 ID abcd & SonstWo (see below) - Organizer: MAILTO:bbb@bbbbb.com - Status: CONFIRMED" - "&6/23/2003 17:00-18:00 Updated: Dress Rehearsal for ABC01-15 - Desc: Viele Zeichen standen hier früher - Location: 123 or TN 123-1234 ID abcd & SonstWo (see below) - Organizer: MAILTO:bbb@bbbbb.com - Status: CONFIRMED") - - ;; export 2004-10-28 block entries - (icalendar-testsuite--test-export - nil - nil - "-*- mode: text; fill-column: 256;-*- - ->>> block entries: - -%%(diary-block 11 8 2004 11 10 2004) Nov 8-10 aa -" - "DTSTART;VALUE=DATE:20041108 -DTEND;VALUE=DATE:20041111 -SUMMARY:Nov 8-10 aa") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-block 12 13 2004 12 17 2004) Dec 13-17 bb" - "DTSTART;VALUE=DATE:20041213 -DTEND;VALUE=DATE:20041218 -SUMMARY:Dec 13-17 bb") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-block 2 3 2005 2 4 2005) Feb 3-4 cc" - "DTSTART;VALUE=DATE:20050203 -DTEND;VALUE=DATE:20050205 -SUMMARY:Feb 3-4 cc") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-block 4 24 2005 4 29 2005) April 24-29 dd" - "DTSTART;VALUE=DATE:20050424 -DTEND;VALUE=DATE:20050430 -SUMMARY:April 24-29 dd -") - (icalendar-testsuite--test-export - nil - nil - "%%(diary-block 5 30 2005 6 1 2005) may 30 - June 1: ee" - "DTSTART;VALUE=DATE:20050530 -DTEND;VALUE=DATE:20050602 -SUMMARY:may 30 - June 1: ee") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-block 6 6 2005 6 8 2005) ff" - "DTSTART;VALUE=DATE:20050606 -DTEND;VALUE=DATE:20050609 -SUMMARY:ff") - - ;; export 2004-10-28 anniversary entries - (icalendar-testsuite--test-export - nil - nil - " ->>> anniversaries: - -%%(diary-anniversary 3 28 1991) aa birthday (%d years old)" - "DTSTART;VALUE=DATE:19910328 -DTEND;VALUE=DATE:19910329 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=03;BYMONTHDAY=28 -SUMMARY:aa birthday (%d years old) -") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-anniversary 5 17 1957) bb birthday (%d years old)" - "DTSTART;VALUE=DATE:19570517 -DTEND;VALUE=DATE:19570518 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=05;BYMONTHDAY=17 -SUMMARY:bb birthday (%d years old)") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-anniversary 6 8 1997) cc birthday (%d years old)" - "DTSTART;VALUE=DATE:19970608 -DTEND;VALUE=DATE:19970609 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=06;BYMONTHDAY=08 -SUMMARY:cc birthday (%d years old)") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-anniversary 7 22 1983) dd (%d years ago...!)" - "DTSTART;VALUE=DATE:19830722 -DTEND;VALUE=DATE:19830723 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=07;BYMONTHDAY=22 -SUMMARY:dd (%d years ago...!)") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-anniversary 8 1 1988) ee birthday (%d years old)" - "DTSTART;VALUE=DATE:19880801 -DTEND;VALUE=DATE:19880802 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=08;BYMONTHDAY=01 -SUMMARY:ee birthday (%d years old)") - - (icalendar-testsuite--test-export - nil - nil - "%%(diary-anniversary 9 21 1957) ff birthday (%d years old)" - "DTSTART;VALUE=DATE:19570921 -DTEND;VALUE=DATE:19570922 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=09;BYMONTHDAY=21 -SUMMARY:ff birthday (%d years old)") - - - ;; FIXME! - - ;; export 2004-10-28 monthly, weekly entries - - ;; (icalendar-testsuite--test-export - ;; nil - ;; " - ;; >>> ------------ monthly: - - ;; */27/* 10:00 blah blah" - ;; "xxx") - - (icalendar-testsuite--test-export - nil - nil - ">>> ------------ my week: - -Monday 13:00 MAC" - "DTSTART;VALUE=DATE-TIME:20000103T130000 -DTEND;VALUE=DATE-TIME:20000103T140000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -SUMMARY:MAC") - - (icalendar-testsuite--test-export - nil - nil - "Monday 15:00 a1" - "DTSTART;VALUE=DATE-TIME:20000103T150000 -DTEND;VALUE=DATE-TIME:20000103T160000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -SUMMARY:a1") - - - (icalendar-testsuite--test-export - nil - nil - "Monday 16:00-17:00 a2" - "DTSTART;VALUE=DATE-TIME:20000103T160000 -DTEND;VALUE=DATE-TIME:20000103T170000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -SUMMARY:a2") - - (icalendar-testsuite--test-export - nil - nil - "Tuesday 11:30-13:00 a3" - "DTSTART;VALUE=DATE-TIME:20000104T113000 -DTEND;VALUE=DATE-TIME:20000104T130000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=TU -SUMMARY:a3") - - (icalendar-testsuite--test-export - nil - nil - "Tuesday 15:00 a4" - "DTSTART;VALUE=DATE-TIME:20000104T150000 -DTEND;VALUE=DATE-TIME:20000104T160000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=TU -SUMMARY:a4") - - (icalendar-testsuite--test-export - nil - nil - "Wednesday 13:00 a5" - "DTSTART;VALUE=DATE-TIME:20000105T130000 -DTEND;VALUE=DATE-TIME:20000105T140000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=WE -SUMMARY:a5") - - (icalendar-testsuite--test-export - nil - nil - "Wednesday 11:30-13:30 a6" - "DTSTART;VALUE=DATE-TIME:20000105T113000 -DTEND;VALUE=DATE-TIME:20000105T133000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=WE -SUMMARY:a6") - - (icalendar-testsuite--test-export - nil - nil - "Wednesday 15:00 s1" - "DTSTART;VALUE=DATE-TIME:20000105T150000 -DTEND;VALUE=DATE-TIME:20000105T160000 -RRULE:FREQ=WEEKLY;INTERVAL=1;BYDAY=WE -SUMMARY:s1") - - - ;; export 2004-10-28 regular entries - (icalendar-testsuite--test-export - nil - nil - " ->>> regular diary entries: - -Oct 12 2004, 14:00 Tue: [2004-10-12] q1" - "DTSTART;VALUE=DATE-TIME:20041012T140000 -DTEND;VALUE=DATE-TIME:20041012T150000 -SUMMARY:Tue: [2004-10-12] q1") - - ;; 2004-11-19 - (icalendar-testsuite--test-import - "BEGIN:VCALENDAR -VERSION - :2.0 -PRODID - :-//Mozilla.org/NONSGML Mozilla Calendar V1.0//EN -BEGIN:VEVENT -UID - :04979712-3902-11d9-93dd-8f9f4afe08da -SUMMARY - :Jjjjj & Wwwww -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - :20041123T140000 -DTEND - :20041123T143000 -DTSTAMP - :20041118T013430Z -LAST-MODIFIED - :20041118T013640Z -END:VEVENT -BEGIN:VEVENT -UID - :6161a312-3902-11d9-b512-f764153bb28b -SUMMARY - :BB Aaaaaaaa Bbbbb -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - :20041123T144500 -DTEND - :20041123T154500 -DTSTAMP - :20041118T013641Z -END:VEVENT -BEGIN:VEVENT -UID - :943a4d7e-3902-11d9-9ce7-c9addeadf928 -SUMMARY - :Hhhhhhhh -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - :20041123T110000 -DTEND - :20041123T120000 -DTSTAMP - :20041118T013831Z -END:VEVENT -BEGIN:VEVENT -UID - :fe53615e-3902-11d9-9dd8-9d38a155bf41 -SUMMARY - :MMM Aaaaaaaaa -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -X-MOZILLA-RECUR-DEFAULT-INTERVAL - :2 -RRULE - :FREQ=WEEKLY;INTERVAL=2;BYDAY=FR -DTSTART - :20041112T140000 -DTEND - :20041112T183000 -DTSTAMP - :20041118T014117Z -END:VEVENT -BEGIN:VEVENT -UID - :87c928ee-3901-11d9-b21f-b45042155024 -SUMMARY - :Rrrr/Cccccc ii Aaaaaaaa -DESCRIPTION - :Vvvvv Rrrr aaa Cccccc -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -DTSTART - ;VALUE=DATE - :20041119 -DTEND - ;VALUE=DATE - :20041120 -DTSTAMP - :20041118T013107Z -LAST-MODIFIED - :20041118T014203Z -END:VEVENT -BEGIN:VEVENT -UID - :e8f331ae-3902-11d9-9948-dfdcb66a2872 -SUMMARY - :Wwww aa hhhh -STATUS - :TENTATIVE -CLASS - :PRIVATE -X-MOZILLA-ALARM-DEFAULT-LENGTH - :0 -RRULE - :FREQ=WEEKLY;INTERVAL=1;BYDAY=MO -DTSTART - ;VALUE=DATE - :20041101 -DTEND - ;VALUE=DATE - :20041102 -DTSTAMP - :20041118T014045Z -LAST-MODIFIED - :20041118T023846Z -END:VEVENT -END:VCALENDAR -" - nil - "&23/11/2004 14:00-14:30 Jjjjj & Wwwww - Status: TENTATIVE - Class: PRIVATE -&23/11/2004 14:45-15:45 BB Aaaaaaaa Bbbbb - Status: TENTATIVE - Class: PRIVATE -&23/11/2004 11:00-12:00 Hhhhhhhh - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-cyclic 14 12 11 2004)) 14:00-18:30 MMM Aaaaaaaaa - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-block 19 11 2004 19 11 2004)) Rrrr/Cccccc ii Aaaaaaaa - Desc: Vvvvv Rrrr aaa Cccccc - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-cyclic 7 1 11 2004)) Wwww aa hhhh - Status: TENTATIVE - Class: PRIVATE " - "&11/23/2004 14:00-14:30 Jjjjj & Wwwww - Status: TENTATIVE - Class: PRIVATE -&11/23/2004 14:45-15:45 BB Aaaaaaaa Bbbbb - Status: TENTATIVE - Class: PRIVATE -&11/23/2004 11:00-12:00 Hhhhhhhh - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-cyclic 14 11 12 2004)) 14:00-18:30 MMM Aaaaaaaaa - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-block 11 19 2004 11 19 2004)) Rrrr/Cccccc ii Aaaaaaaa - Desc: Vvvvv Rrrr aaa Cccccc - Status: TENTATIVE - Class: PRIVATE -&%%(and (diary-cyclic 7 11 1 2004)) Wwww aa hhhh - Status: TENTATIVE - Class: PRIVATE ") - - ;; 2004-09-09 pg - (icalendar-testsuite--test-export - "%%(diary-block 1 1 2004 4 1 2004) Urlaub" - nil - nil - "DTSTART;VALUE=DATE:20040101 -DTEND;VALUE=DATE:20040105 -SUMMARY:Urlaub") - - ;; 2004-10-25 pg - (icalendar-testsuite--test-export - nil - "5 11 2004 Bla Fasel" - nil - "DTSTART;VALUE=DATE:20041105 -DTEND;VALUE=DATE:20041106 -SUMMARY:Bla Fasel") - - ;; 2004-10-30 pg - (icalendar-testsuite--test-export - nil - "2 Nov 2004 15:00-16:30 Zahnarzt" - nil - "DTSTART;VALUE=DATE-TIME:20041102T150000 -DTEND;VALUE=DATE-TIME:20041102T163000 -SUMMARY:Zahnarzt") - - ;; 2005-02-07 lt - (icalendar-testsuite--test-import - "UID - :b60d398e-1dd1-11b2-a159-cf8cb05139f4 -SUMMARY - :Waitangi Day -DESCRIPTION - :abcdef -CATEGORIES - :Public Holiday -STATUS - :CONFIRMED -CLASS - :PRIVATE -DTSTART - ;VALUE=DATE - :20050206 -DTEND - ;VALUE=DATE - :20050207 -DTSTAMP - :20050128T011209Z" - nil - "&%%(and (diary-block 6 2 2005 6 2 2005)) Waitangi Day - Desc: abcdef" - "&%%(and (diary-block 2 6 2005 2 6 2005)) Waitangi Day - Desc: abcdef") - - ;; 2005-03-01 lt - (icalendar-testsuite--test-import - "DTSTART;VALUE=DATE:20050217 -SUMMARY:Hhhhhh Aaaaa ii Aaaaaaaa -UID:6AFA7558-6994-11D9-8A3A-000A95A0E830-RID -DTSTAMP:20050118T210335Z -DURATION:P7D" - nil - "&%%(and (diary-block 17 2 2005 23 2 2005)) Hhhhhh Aaaaa ii Aaaaaaaa" - "&%%(and (diary-block 2 17 2005 2 23 2005)) Hhhhhh Aaaaa ii Aaaaaaaa") - - ;; 2005-03-23 lt - (icalendar-testsuite--test-export - nil - "&%%(diary-cyclic 7 8 2 2005) 16:00-16:45 [WORK] Pppp" - nil - "DTSTART;VALUE=DATE-TIME:20050208T160000 -DTEND;VALUE=DATE-TIME:20050208T164500 -RRULE:FREQ=DAILY;INTERVAL=7 -SUMMARY:[WORK] Pppp -") - - ;; 2005-05-27 eu - (icalendar-testsuite--test-export - nil - nil - ;; FIXME: colon not allowed! - ;;"Nov 1: NNN Wwwwwwww Wwwww - Aaaaaa Pppppppp rrrrrr ddd oo Nnnnnnnn 30" - "Nov 1 NNN Wwwwwwww Wwwww - Aaaaaa Pppppppp rrrrrr ddd oo Nnnnnnnn 30" - "DTSTART;VALUE=DATE:19001101 -DTEND;VALUE=DATE:19001102 -RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=11;BYMONTHDAY=1 -SUMMARY:NNN Wwwwwwww Wwwww - Aaaaaa Pppppppp rrrrrr ddd oo Nnnnnnnn 30 -") - ) - -(defun icalendar-testsuite--run-cycle-tests () - "Perform cycling tests." - (icalendar-testsuite--test-cycle - "DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -SUMMARY:Cycletest -") - - (icalendar-testsuite--test-cycle - "DTSTART;VALUE=DATE-TIME:20030919T090000 -DTEND;VALUE=DATE-TIME:20030919T113000 -SUMMARY:Cycletest -DESCRIPTION:beschreibung! -LOCATION:nowhere -ORGANIZER:ulf -") - - ;; FIXME: does not work - ;; (icalendar-testsuite--test-cycle - ;; "DTSTART;VALUE=DATE:19190909 - ;;DTEND;VALUE=DATE:19190910 - ;;RRULE:FREQ=YEARLY;INTERVAL=1;BYMONTH=09;BYMONTHDAY=09 - ;;SUMMARY:and diary-anniversary - ;;") - ) - - -(provide 'icalendar-testsuite) - -;; arch-tag: 33a98396-90e9-49c8-b0e9-b606386d6e8c -;;; icalendar-testsuite.el ends here diff --git a/test/newsticker-testsuite.el b/test/newsticker-testsuite.el deleted file mode 100644 index acc02edba1c..00000000000 --- a/test/newsticker-testsuite.el +++ /dev/null @@ -1,181 +0,0 @@ -;;; newsticker-testsuite.el --- Test suite for newsticker. - -;; Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 -;; Free Software Foundation, Inc. - -;; Author: Ulf Jasper -;; Filename: newsticker-testsuite.el -;; URL: http://www.nongnu.org/newsticker -;; Keywords: News, RSS, Atom -;; Time-stamp: "14. Juni 2008, 12:09:39 (ulf)" - -;; ====================================================================== - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see . - -;; ====================================================================== - -;;; Commentary: - -;;; Code: - -(require 'cl) ; assert - -;; ====================================================================== -;; Entry point -;; ====================================================================== -(defun newsticker--testsuite () - "Unit test for newsticker. -Subtests signal errors if something goes wrong." - (interactive) - (newsticker--test--guid) - (newsticker--test--cache-contains) - (newsticker--test--decode-iso8601-date) - (newsticker--test--decode-rfc822-date) - (newsticker--test--group-manage-orphan-feeds) - (message "All tests passed successfully.")) - -;; ====================================================================== -;; Tests for newsticker-backend -;; ====================================================================== -(defun newsticker--test--guid () - "Test `newsticker-guid-*'. -Signals an error if something goes wrong." - (assert (string= "blah" (newsticker--guid-to-string "blah"))) - (assert (string= "myguid" (newsticker--guid '("title1" "description1" "link1" - nil 'new 42 nil nil - ((guid () "myguid"))))))) - -(defun newsticker--test--cache-contains () - "Test `newsticker--test--cache-contains'. -Signals an error if something goes wrong." - (let ((newsticker--cache '((feed1 - ("title1" "description1" "link1" nil 'new 42 - nil nil ((guid () "myguid"))))))) - (newsticker--guid-to-string - (assoc 'guid (newsticker--extra '("title1" "description1" - "link1" nil 'new 42 nil nil - ((guid "myguid")))))) - (assert (newsticker--cache-contains newsticker--cache 'feed1 "WRONGTITLE" - "description1" "link1" 'new "myguid")) - (assert (not (newsticker--cache-contains newsticker--cache 'feed1 "title1" - "description1" "link1" 'new - "WRONG GUID"))) - (assert (newsticker--cache-contains newsticker--cache 'feed1 "title1" - "description1" "link1" 'new "myguid"))) - (let ((newsticker--cache '((feed1 - ("title1" "description1" "link1" nil 'new 42 - nil nil ((guid () "myguid1"))) - ("title1" "description1" "link1" nil 'new 42 - nil nil ((guid () "myguid2"))))))) - (assert (not (newsticker--cache-contains newsticker--cache 'feed1 "title1" - "description1" "link1" 'new - "myguid"))) - (assert (string= "myguid1" - (newsticker--guid (newsticker--cache-contains - newsticker--cache 'feed1 "title1" - "description1" "link1" 'new - "myguid1")))) - (assert (string= "myguid2" - (newsticker--guid (newsticker--cache-contains - newsticker--cache 'feed1 "title1" - "description1" "link1" 'new - "myguid2")))))) - -(defun newsticker--do-test--decode-iso8601-date (input expected) - "Actually test `newsticker--decode-iso8601-date'. -Signals an error if iso8601-encoded INPUT does not match EXPECTED." - (let ((result (format-time-string "%Y-%m-%dT%H:%M:%S" - (newsticker--decode-iso8601-date input) - t))) - (assert (string= result expected) - nil "Error decoding '%s': found '%s' but expected '%s'." - input result expected))) - -(defun newsticker--test--decode-iso8601-date () - "Test `newsticker--decode-iso8601-date'." - (newsticker--decode-iso8601-date "2004-09-17T05:09:49+00:00") - (newsticker--decode-iso8601-date "2004-09-17T05:09+00:00") - (newsticker--decode-iso8601-date "2004-09-17T05:09:49") - (newsticker--decode-iso8601-date "2004-09-17T05:09") - (newsticker--decode-iso8601-date "2004-09-17") - (newsticker--decode-iso8601-date "2004-09") - (newsticker--do-test--decode-iso8601-date "2004" - "2004-01-01T00:00:00") - (newsticker--do-test--decode-iso8601-date "2004-09" - "2004-09-01T00:00:00") - (newsticker--do-test--decode-iso8601-date "2004-09-17" - "2004-09-17T00:00:00") - (newsticker--do-test--decode-iso8601-date "2004-09-17T05:09" - "2004-09-17T05:09:00") - (newsticker--do-test--decode-iso8601-date "2004-09-17T05:09:49" - "2004-09-17T05:09:49") - (newsticker--do-test--decode-iso8601-date "2004-09-17T05:09:49.123" - "2004-09-17T05:09:49") - (newsticker--do-test--decode-iso8601-date "2004-09-17T05:09+01:00" - "2004-09-17T04:09:00") - (newsticker--do-test--decode-iso8601-date "2004-09-17T05:09-02:00" - "2004-09-17T07:09:00")) - -(defun newsticker--do-test--decode-rfc822-date (input expected) - "Actually test `newsticker--decode-rfc822-date'. -Signals an error if rfc822-encoded INPUT does not match EXPECTED." - (let ((result (format-time-string "%Y-%m-%dT%H:%M:%S" - (newsticker--decode-rfc822-date input) - t))) - (assert (string= result expected) - nil "Error decoding '%s': found '%s' but expected '%s'." - input result expected))) - -(defun newsticker--test--decode-rfc822-date () - "Test `newsticker--decode-rfc822-date'." - (newsticker--do-test--decode-rfc822-date "Mon, 10 Mar 2008 19:27:52 +0100" - "2008-03-10T18:27:52") - ;;(format-time-string "%d.%m.%y, %H:%M %T%z" - ;;(newsticker--decode-rfc822-date "Mon, 10 Mar 2008 19:27:52 +0200")) - - (newsticker--do-test--decode-rfc822-date "Mon, 10 Mar 2008 19:27:52" - "2008-03-10T19:27:52") - (newsticker--do-test--decode-rfc822-date "Mon, 10 Mar 2008 19:27" - "2008-03-10T19:27:00") - (newsticker--do-test--decode-rfc822-date "10 Mar 2008 19:27" - "2008-03-10T19:27:00") - (newsticker--do-test--decode-rfc822-date "Mon, 10 Mar 2008" - "2008-03-10T00:00:00") - (newsticker--do-test--decode-rfc822-date "10 Mar 2008" - "2008-03-10T00:00:00") - (newsticker--do-test--decode-rfc822-date "Sat, 01 Dec 2007 00:05:00 +0100" - "2007-11-30T23:05:00") - (newsticker--do-test--decode-rfc822-date "Sun, 30 Dec 2007 18:58:13 +0100" - "2007-12-30T17:58:13")) - -;; ====================================================================== -;; Tests for newsticker-treeview -;; ====================================================================== -(defun newsticker--test--group-manage-orphan-feeds () - "Test `newsticker--group-manage-orphan-feeds'. -Signals an error if something goes wrong." - (let ((newsticker-groups '("Feeds")) - (newsticker-url-list-defaults nil) - (newsticker-url-list '(("feed1") ("feed2") ("feed3")))) - (newsticker--group-manage-orphan-feeds) - (assert (equal '("Feeds" "feed3" "feed2" "feed1") - newsticker-groups)))) - -(provide 'newsticker-testsuite) - -;; arch-tag: e6c09af2-cc7a-4373-8f5f-9c36699ec34c -;;; newsticker-testsuite.el ends here -- 2.30.2